为 AI 编码助手建立项目上下文claude-agent-sdk-demos 的 Primer 引导实践指南【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents在 Claude Agent SDK 的多 Agent、多示例项目中每次开启新会话时AI 编码助手都需要快速补上进度——理解项目结构、目标、关键文件、依赖与配置才能产出贴合实际的代码。本文以 claude-agent-sdk-demos 仓库为实例完整拆解 primer.md 所定义的项目上下文引导流程Priming从读取 CLAUDE.md 与 README.md到精读关键源码再到面向开发者回述项目结构、目的、关键文件、依赖与配置五要素。读完本文你将掌握一套可复用的AI 助手快速上手指南模板并能结合仓库源码理解每一步背后的工程依据。Primer 的定位一次对话的上下文引导协议primer.md 是一个专门写给 AI 编码助手而非人类读者的启动指令文件。它的核心思路是当 AI 助手第一次接触一个项目、或在新会话中丢失了上下文时通过一个固定的读取顺序与回述机制把助手拉回正轨。它定义了四个明确的动作读取 CLAUDE.md若存在理解项目的最高规则读取 README.md理解项目的整体定位与使用方法读取项目中的关键文件获得实现层面的第一手证据向开发者回述五要素项目结构、项目目的与目标、关键文件及其用途、重要依赖、重要配置文件。这套流程的价值在于它把理解项目从隐式的、随机的搜索变成了显式的、有固定顺序的协议。开发者只需在.claude/commands/下放置这样一份指令文件就能在每次新会话开始时让 AI 助手以一致的方式完成项目上下文重建避免助手因缺乏项目知识而给出泛泛而谈或不符实际的代码。第一步读取 CLAUDE.md —— 项目最高规则的入口primer 协议的第一条要求是如果 CLAUDE.md 存在先读取它。在 claude-agent-sdk-demos 中CLAUDE.md 恰好是一个非常典型的高规则文件它示范了 CLAUDE.md 应当承载哪几类信息ARCHON-FIRST 规则超越一切指令的优先级声明文件开头使用# CRITICAL强调了项目专属的硬性约束面对任何任务管理场景先检查 Archon MCP server 是否可用以 Archon 任务管理作为主要系统不使用 TodoWrite该规则覆盖所有其他指令、PRP、系统提醒和模式。这告诉 AI 助手项目有一套自有的任务管理生态外部工具的默认行为在这里不适用。这种规则声明 违规检查的写法VIOLATION CHECK本身就是 CLAUDE.md 的经典范式——把规则写得可验证、可自检。任务驱动开发工作流Task-Driven DevelopmentCLAUDE.md 定义了编码前的强制任务周期Get Task→find_tasks(task_id...)或find_tasks(filter_bystatus, filter_valuetodo)Start Work→manage_task(update, task_id..., statusdoing)Research→ 使用知识库见 RAG 工作流Implement→ 基于研究结果写代码Review→manage_task(update, task_id..., statusreview)Next Task→find_tasks(filter_bystatus, filter_valuetodo)并伴随两条纪律NEVER skip task updates绝不跳过任务状态更新、NEVER code without checking current tasks first绝不先写代码再查任务。RAG 工作流先研究、后实现CLAUDE.md 还示范了如何在项目中建立知识检索约定定向查文档先用rag_get_available_sources()获取来源列表含 id、title、url匹配到对应文档的source_id再用rag_search_knowledge_base(query..., source_idsrc_abc123)精确检索通用研究rag_search_knowledge_base(queryauthentication JWT, match_count5)检索知识库rag_search_code_examples(queryReact hooks, match_count3)检索代码示例使用要点查询只保留2~5 个关键词以获得更好的检索效果。工具参考与项目工作流文件最后给出了工具签名级的参考表Projects、Tasks、Knowledge Base 三类工具的调用方式、任务状态流todo → doing → review → done、优先级约定task_order越高越优先取值 0~100、以及任务粒度的经验值每个任务约 30 分钟到 4 小时的工作量。对 AI 助手的意义CLAUDE.md 就是项目的宪法。primer 协议要求先读它是因为后续所有对 README 和源码的理解都必须放在这套规则之下进行——例如在本仓库中助手应当先确认 Archon MCP 可用性再考虑任务编排。第二步读取 README.md —— 建立项目整体认知primer 协议的第二条是读取 README.md。本仓库的 README.md 是理解项目的总纲它把项目概括为三个由浅入深的 Claude Agent SDKPython示例Quickstart入门、Obsidian 集成OpenAI 兼容 REST API、Telegram 集成带会话管理的完整 Bot。README 同时给出了前置条件Python 3.10、Anthropic 账号、可选的 Telegram/Obsidian与两种认证方式Option A推荐Claude CLI OAuth→claude auth loginOption BAPI Key→ 复制.env.example为.env并填入ANTHROPIC_API_KEY对 AI 助手而言README 的价值在于快速定位项目是什么、能干什么、怎么跑起来从而在后续阅读源码时能带着目标去验证而不是盲目逐行浏览。第三步阅读关键文件 —— 用源码验证认知primer 协议的第三条是读取项目中的关键文件。这一步是上下文引导的核心纵深README 描述的是应然源码展示的是实然。以 claude-agent-sdk-demos 为例关键文件可以按三个递进层次去读层次一Quickstart —— 两种交互原语simple_query_example.py 演示query()函数无状态、一次性查询。它通过async for message in query(prompt..., optionsoptions)流式接收原始消息适合单次问答、脚本自动化。simple_cli.py 演示ClaudeSDKClient有状态、可续聊。它展示了三个关键机制会话持久化save_session()/load_session()把 session_id 存到sessions/current_session.json--continue参数通过options_dict[resume] session_id恢复对话流式渲染client.receive_response()会等到ResultMessage才结束循环中按TextBlock绿色文本与ToolUseBlock品红工具标记分类型展示工具限定allowed_tools[Read, Write, Bash]控制 Claude 可用工具范围。源码中options_dict[resume] session_id与ResultMessage.session_id的配合正是会话管理维持多轮上下文这一 README 论断的实现证据。层次二Obsidian 集成 —— OpenAI 兼容桥接层api_server.py 是一个 FastAPI 服务暴露 OpenAI 兼容的POST /v1/chat/completions端点让 Obsidian Copilot 等 OpenAI 客户端直接调用 ClaudePydantic 模型层ChatCompletionRequest含model、messages、stream、temperature、max_tokens、ChatCompletionResponse含id、choices、usage完整对齐 OpenAI 协议会话判定is_continuing_conversation()通过统计user消息数量判断是否续聊1 则为续聊并从api_sessions/current.json加载 session_id 传给resume流式与普通双模式streamTrue时用 SSE 流式返回streamFalse时由 openai_converter.py 的extract_full_response_text()汇总完整文本工具与 MCPoptions_dict中配置了allowed_tools含mcp__sequential-thinking并通过mcp_servers声明以npx -y modelcontextprotocol/server-sequential-thinking启动的 MCP 服务器运维细节/health健康检查、CORS 全开、端口由PORT环境变量控制默认 8003。而 openai_converter.py 实现了协议翻译的核心convert_sdk_to_openai_stream()把 Claude SDK 的receive_messages()流转换为 OpenAI 的chat.completion.chunkSSE 格式并在ResultMessage处捕获 session_id最后发送data: [DONE]结束标记。层次三Telegram 集成 —— 多用户会话管理样板telegram_bot.py 是功能最完整的示例也是理解多用户隔离的最佳范本每用户会话文件telegram_sessions/{user_id}.json存session_id、cwd、created_at、last_updated每用户工作目录/setcwd校验路径存在且为目录后转为绝对路径保存/getcwd读取无配置时回退到WORKING_DIRECTORY环境变量或当前目录/searchcwd在用户目录与常见位置按关键词搜索目录深度限制 3 层、最多 15 条结果命令体系/start、/help、/setcwd、/getcwd、/searchcwd、/reset清空会话但保留 cwd消息处理主循环handle_message()加载用户会话 → 组装ClaudeAgentOptions含resume→client.query()→receive_response()分拣TextBlock与ToolUseBlock→ 保存新 session_idTelegram 消息长度限制send_long_message()按行切分把超过 4096 字符的响应拆成多条发送并附带(continued 1/n)标记Sentry 增强版telegram_bot_sentry.py 在相同架构上引入sentry_sdk可追踪 token 用量与成本、监控 Read/Write/Bash/Edit 等工具执行、捕获带上下文的错误并做性能追踪环境配置由SENTRY_DSN与SENTRY_ENVIRONMENT控制。同时tests/test_telegram_bot.py 与 tests/test_sentry_monitoring.py 提供了会话管理与监控逻辑的测试覆盖可作为验证行为正确性的补充依据。第四步回述五要素 —— 向开发者确认理解到位primer 协议的收尾动作是让 AI 助手把理解显式回述给开发者。这正是整个引导流程的关键闭环只有把内化的知识讲出来开发者才能确认助手是否真正理解了项目。回述应覆盖以下五要素结合本仓库即为1. 项目结构claude-agent-sdk-demos/ ├── quickstart/ # 入门示例 │ ├── simple_query_example.py # 无状态 query() │ ├── simple_cli.py # 交互式终端 CLI支持 --continue │ └── sessions/ # CLI 会话存储current_session.json ├── obsidian_integration/ # Obsidian Copilot 集成 │ ├── api_server.py # FastAPI OpenAI 兼容服务默认端口 8003 │ ├── openai_converter.py # Claude 消息 → OpenAI SSE 格式转换 │ └── api_sessions/ # API 会话存储 ├── telegram_integration/ # Telegram Bot 实现 │ ├── telegram_bot.py # 基础版推荐 │ ├── telegram_bot_sentry.py # Sentry 监控版 │ └── tests/ # 测试文件 ├── telegram_sessions/ # 每用户会话存储 ├── requirements.txt # 依赖清单 └── .env.example # 环境变量模板2. 项目目的与目标用 Claude Agent SDKPython演示三类典型集成场景从最简单的无状态查询到为 Obsidian Copilot 提供 OpenAI 兼容 API再到带会话管理与工具权限的 Telegram Bot覆盖从单次调用到生产级集成的完整进阶路径。3. 关键文件及其用途quickstart/simple_query_example.py演示query()无状态调用quickstart/simple_cli.py演示ClaudeSDKClient有状态会话与--continue恢复obsidian_integration/api_server.pyOpenAI 兼容聊天端点obsidian_integration/openai_converter.pySDK 消息流到 OpenAI SSE 的桥接器telegram_integration/telegram_bot.py每用户会话与工作目录管理的完整 Bottelegram_integration/telegram_bot_sentry.py在 Bot 之上叠加 Sentry 可观测性。4. 重要依赖从 requirements.txt 可以看到三层依赖SDK 层claude-agent-sdk0.1.2、anthropic0.69.0、Web 服务层fastapi0.118.3、uvicorn0.37.0、sse-starlette3.0.2、python-multipart、集成与可观测层python-telegram-bot22.5、sentry-sdk2.31.0以及开发依赖pytest、pytest-asyncio、pytest-cov。5. 重要配置文件.envANTHROPIC_API_KEYOAuth 之外的第二认证路径、PORT默认 8003、WORKING_DIRECTORY、TELEGRAM_BOT_API_KEY、SENTRY_DSN、SENTRY_ENVIRONMENTClaudeAgentOptions是贯穿所有示例的运行时配置入口可自定义cwd、system_prompt、allowed_tools、resume、mcp_servers等参数例如options ClaudeAgentOptions( cwd/path/to/working/directory, system_promptYou are a helpful assistant..., allowed_tools[Read, Write, Bash], # 限定工具范围 # resumesession_id_here # 恢复历史会话 )把 Primer 落到自己的项目模板与最佳实践基于 primer.md 协议与本仓库的示范你可以为自己的项目建立同样的引导机制创建.claude/commands/primer.md完整保留读 CLAUDE.md → 读 README → 读关键文件 → 回述五要素的协议骨架让 CLAUDE.md 承载规则优先内容仿照本仓库 CLAUDE.md 的写法把项目的硬性约束工具使用纪律、任务管理流程、检索约定放在最前面并写明违规检查在 README 中写好地图确保 README 覆盖项目定位、前置条件、安装认证、目录结构、配置项与使用方式让助手一次读到位把关键文件清单维护在 primer 中明确指出读哪些文件、按什么顺序读、每个文件回答什么问题例如先读入口、再读转换器、最后读测试强制回述闭环让助手在动手写代码前先复述项目结构与关键结论开发者据此确认理解无误再放行进入实现阶段。这套机制的收益是双向的开发者省去重复讲解项目背景的口舌AI 助手则从猜项目变成读项目——每一次新会话都从可靠的上下文起点出发产出的代码也因此更贴近仓库的真实结构与约定。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
