Skill v1.0.1
currentAutomated scan100/100+4 new
name: project-analyzer description: 以开源 Agent / RAG 项目为案例，撰写一部成体系的技术专著。当用户给出 GitHub 地址或要求"梳理 / 分析 / 讲透"某个 Agent、ReAct、Multi-Agent、RAG、上下文工程类项目的技术实现时触发，输出以仓库名命名的 Markdown 长文（教材体裁，1.5–3 万字，分章）。按知识体系组织章节——Agent 范式与选型、主循环、上下文工程、工具系统、提示词、记忆、RAG、模型接入、MCP、多 Agent、长任务可靠性、评测——每章讲透「概念 → 原理 → 业界做法对比 → 本案例实现 → 权衡边界 → 小结」，可直接作为学习教材与方案设计参考手册。 agent_created: true metadata: version: "1.0.1"
Project Analyzer — Agent 架构技术专著
定位：写一本书，不是写一份文档
输出物是一本以某个开源项目为贯穿案例的技术专著。读者读完后应能做到两件事：一是系统性地学会 Agent / RAG 这套技术体系，二是把书中讲到的方案直接当作设计自己系统时的参考。
这决定了两者体例的根本差异：
| 项目梳理文档 | 技术专著（本技能） | ||
|---|---|---|---|
| 组织依据 | 本项目有哪些模块 | 知识体系怎么递进 | |
| 项目角色 | 唯一主体 | 贯穿全书的案例 | |
| 章节标题 | 「工具系统」「记忆机制」 | 「为什么工具多了模型就选不准」 | |
| 讲法 | 它做了什么 | 概念 → 原理 → 有几种做法 → 它选了哪种 → 代价 | |
| 读者收益 | 知道这个项目长什么样 | 学会一类问题的解法，并知道何时该用 |
判断内容取舍的标准：
读者合上这一章，能不能独立回答"这个技术点是什么、为什么需要、有哪几种做法、我该选哪个"？
而不是"这个项目有哪些文件"。
产出物
- 文件名：
【仓库名】.md（如agentrack.md）。不加"项目梳理"后缀、不加日期前缀。 - 一级标题：
# 【仓库名】，下一行副标题点明本书视角，如> 以 X 为案例的 Agent 架构实现剖析。 - 篇幅：15,000–30,000 字。核心章每章 1,500–2,500 字。
- 落盘方式：先写全书骨架（卷首 + 全部章节标题 + 各章导读），再逐章追加填充。不要试图一次性输出全文——超长单次输出会被截断，且难以保持质量。
- 入库：本技能只输出文件。不执行上传，不追问知识库目标。
触发条件
触发：
- 用户给出 GitHub 地址或本地仓库路径，要求梳理 / 分析 / 讲透这个项目的技术实现
- 用户想通过某个开源 Agent 项目学习 Agent 架构
- 用户想要一份能当参考手册用的 Agent 技术资料
不触发：
- 只问某个具体函数怎么实现（直接回答）
- 要求在仓库里改代码、修 bug、做 code review
- 只要一份几百字的项目简介
全书的六要素体例
每一章（收束章除外）都必须覆盖以下六个要素。缺任何一条，这一章就不成立——缺「原理」变成功能清单，缺「对比」变成项目广告，缺「权衡」变成教程抄写。
| 要素 | 回答什么 | 常见错误 | |
|---|---|---|---|
| ① 概念与问题 | 这东西是什么？没有它会怎样？ | 直接跳到实现，读者不知道在解决什么 | |
| ② 原理 | 为什么必须这么设计？底层机制是什么？ | 只描述现象，不解释成因 | |
| ③ 业界做法对比 | 有哪几种主流方案？各自失效场景？ | 只讲本项目那一种，读者以为它是唯一解 | |
| ④ 本案例实现 | 这个项目选了哪种，怎么落地，参数阈值多少 | 与 ③ 脱节，看不出选择 | |
| ⑤ 权衡与边界 | 好处、坏处、什么场景别用 | 只写优点，或写"各有优劣"这种无信息量的话 | |
| ⑥ 小结 | 3–5 条可带走的结论 | 复述原文，没有提炼 |
章节顺序可按内容需要调整（如把「对比」插在「原理」前后），但这六个要素不能少。
全书章节架构
六部分十四章。核心章必写，其余按项目实况取舍。
卷首（必写）
- 本书讲什么、适合谁读、怎么读（三条阅读路径：只想了解该项目 / 想学 Agent 架构 / 只想查某个机制）
- 案例项目概况：GitHub 地址、主语言、一句话定位
- 代码地图：只列本书会引用的 8–12 个文件及其职责，让人知道从哪读起。不是完整目录树
第一部分 认识这个系统
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 1 | 案例项目全景 | 问题域、系统形态、一次请求的鸟瞰、设计取向总表 | 核心 | |
| 2 | Agent 范式与选型逻辑 | ReAct / Plan-Execute / Reflection / 图编排 / 纯 Workflow，选型矩阵与本案例的选择理由 | 核心 |
第二部分 运行时内核
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 3 | 主循环的工程实现 | 循环骨架、单轮状态、终止条件设计、并行工具调用、异常分类、中断恢复 | 核心 | |
| 4 | 上下文工程 | token 经济学、注意力衰减、组成与优先级、压缩四法、触发与保留策略、上下文隔离 | 核心 | |
| 5 | 工具系统 | schema 设计与 description 工程、注册发现、选择准确率、按需加载、返回结果设计、执行边界、Skill 封装 | 核心 | |
| 6 | 提示词设计 | 分层结构、约束写法、输出格式控制三档、解析与修复 | 核心 |
第三部分 知识与记忆
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 7 | 记忆与状态持久化 | 三层记忆、写入时机、存储形态、检索重排、遗忘与冲突、跨会话恢复 | 按实况 | |
| 8 | RAG 检索增强 | 切分、向量化、召回（稠密/稀疏/混合）、重排、注入、评测、Agentic RAG | 按实况 |
第四部分 模型与协议
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 9 | 模型接入层 | provider 差异、抽象层设计、流式、结构化输出、多模型路由、重试降级、成本控制 | 按实况 | |
| 10 | MCP 与外部能力接入 | M×N 问题、协议构成、客户端实现、与内置工具差异、命名空间、代码执行/浏览器等外部集成 | 按实况 |
第五部分 规模化与工程化
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 11 | 多 Agent 协作 | 动机、拓扑、通信方式、上下文隔离、调度、常见失败模式 | 按实况 | |
| 12 | 长任务执行与可靠性 | 任务分解与计划落盘、断点恢复、幂等与副作用、人在回路、重试边界 | 按实况 | |
| 13 | 评测与可观测性 | 为何难评测、评测维度、trace、成本归因、失败归因 | 按实况 |
第六部分 收束（必写）
| 章 | 标题 | 核心内容 | 分级 | |
|---|---|---|---|---|
| 14 | 架构决策速查与复盘 | 决策速查表、案例取舍复盘、局限、最小可行架构 | 核心 |
附录（必写）：术语表、代码位置索引。
分级处理规则
| 分级 | 处理方式 | |
|---|---|---|
| 核心 | 完整六要素，本案例实现详写，配流程图 | |
| 按实况·项目有实现 | 完整六要素，本案例实现详写，配流程图 | |
| 按实况·项目无实现 | 保留章节，①②③⑤⑥ 照写（用业界通用知识），④ 写成本项目为何不做、用什么替代、什么条件下才需要补上 | |
| 与本书主题无关 | 删除，不保留空章节 |
事实来源标注规范
这是硬约束。用户会核对，编造一处就毁掉整份材料的可信度。
| 标记 | 含义 | 写法 | |
|---|---|---|---|
| 【代码】 | 来自仓库源码 | 直接给 路径/文件.py → 函数名()，无需额外标记 | |
| 【业界】 | 通用技术知识，非本项目特有 | 句末标注 【业界】；引用具体产品/论文时给出名称 | |
| 【推断】 | 读代码得出的推测，未经直接验证 | 标注 【推断，未在代码中确认】 |
补充规则：
- 项目中不存在的东西，绝不写成本项目的实现
- 业界对比部分允许用 WebSearch 补充最新做法，但必须标注
【业界】，且不写具体版本号/发布日期 - 数字（阈值、轮数、token 上限）必须与代码一致；代码里是配置项而非硬编码的，写"默认 X，可配置"
写作流程
阶段一：读模板
读取 references/agent-book-template.md，获取各章的知识点清单、章内骨架样例、图表与代码呈现规范。
阶段二：把握案例项目
- 读 README / docs / examples，判断项目类型与形态
- 用「代码探索策略」中的锚点表定位核心文件
- 建立代码地图：本书会引用的 8–12 个文件及职责
- 形成架构假设清单：猜测的范式、主链路、机制分布 + 待验证疑点
阶段三：定章节目录
根据项目实况，对 14 章逐条判定：核心 / 有实现 / 无实现 / 删除。产出一份章节目录，标注每章预计篇幅与要写的知识点。
这一步必须显式完成。直接开写会导致章节失衡——前面几章写太细，后面草草收尾。
阶段四：落盘骨架
一次性写入文件骨架：卷首 + 全部章节标题与导读 + 附录标题，正文留占位。骨架先落盘，后续逐章填充，中途中断也不丢结构。
阶段五：逐章撰写
按章节顺序写，每章一次追加（用 Edit 替换该章的占位内容）。每章严格走六要素。
写每章前先问三个问题：
- 这一章要让读者学会解决什么问题？
- 业界的几种做法我能不能说清各自失效场景？
- 本案例的选择在这个对比里处于什么位置？
阶段六：通篇校订
全书写完后回头检查：
- 术语是否全文一致（同一概念不要换三种说法）
- 章节间交叉引用是否正确（"见 4.3 节"这类）
- 有无重复讲述同一机制
- 有无【】占位符残留
- 有无章节失衡（某章明显比其他章单薄）
阶段七：交付
确认文件路径与文件名，报告篇幅与章节结构，说明哪些章因项目未涉及而作了简化处理。不执行上传。
代码探索策略
搜索锚点
| 想找什么 | 搜索锚点 | |
|---|---|---|
| Agent 主循环 | while True、max_iterations、max_steps、stop_reason、finish_reason、tool_calls | |
| 工具注册 | @tool、register_tool、tools=、Tool(、inputSchema、parameters | |
| MCP 集成 | mcp、ModelContextProtocol、list_tools、call_tool、stdio_client | |
| 上下文压缩 | compress、truncate、summarize、context_window、max_tokens、tiktoken | |
| 记忆/状态 | memory、history、session、checkpoint、store、persist | |
| 提示词 | system_prompt、SYSTEM_PROMPT、prompts/、ChatPromptTemplate | |
| 多 Agent | handoff、delegate、sub_agent、subagent、crew、supervisor、transfer_to | |
| RAG | embed、retriever、rerank、chunk、vector_store、similarity | |
| 模型接入 | litellm、ChatOpenAI、stream=True、response_format、bind_tools |
探索纪律
- 大仓库用 Explore 子代理并行探索，围绕具体架构问题提问，不做无目的通读
- 精读范围限定：主链路 + 各机制核心文件
- 不读：前端界面、管理后台、部署脚本、测试用例、业务 CRUD 逻辑
- 读到的每个关键结论随手记下文件路径，避免写作时回查
深度要求
| 对象 | 深度 | |
|---|---|---|
| 主链路 | 到函数级，每个环节配图 | |
| 各机制 | 到机制级——策略、阈值、算法、失效条件；流程图要画全，代码不逐行 | |
| 工具实现 | 用途 + 关键参数 + 执行方式 | |
| 配置项 | 只在影响架构时提及具体值 |
输出质量要求
- 教材感：每章读完要知道"为什么"，不能只留"是什么"。原理讲不透的章节，宁可压缩篇幅也不要堆砌。
- 对比意识：凡有多种做法的地方，必须给出对比表与各自失效场景。写"各有优劣"而不说清何时用哪个，视为不合格。
- 案例贯串：每章都要落到本案例上——选了哪种、在哪实现、参数多少。纯理论章节不超过 2 章。
- 诚实：严格按「事实来源标注规范」区分代码事实、业界知识、推断。
- 流程图：主链路每个环节、每个机制单元必须配图。图是理解架构的主要载体，读者多数时候先看图。
- 可查性：关键结论附
文件路径 → 函数名()，让读者能回到源码验证。 - 不注水：不写"综上所述""值得注意的是"这类填充句；不为凑篇幅重复已讲内容。
资源说明
references/agent-book-template.md
全书模板。包含：卷首格式、十四章逐章写作大纲（每章要讲哪些知识点）、章内骨架样例、图表与代码片段呈现规范、附录格式。
阶段一必须读取。阶段四落盘骨架、阶段五逐章撰写均以此为准。