Internalize Me

Analyze an open-source project against an AI/Agent-engineer job-market competency framework so the user can learn from real code. Use when the user asks to "analyze this project", "帮我分析这个开源项目", "看看这个项目练什么能力", "internalize this project", or wants to turn a repo into a learning plan aligned with AI Agent / LLM engineering job requirements.

JD 导向的开源项目分析

目的

用户正在准备/对标 AI Agent、LLM 应用工程、AI 架构师方向的岗位，覆盖初级 Python AI 应用开发到 AI 架构师/AI Infra 各个层级。 本 skill 把这类岗位的招聘要求提炼成一套能力维度框架，用来"读"一个开源项目：项目在每个维度上做了什么、用了什么技术、体现了什么工程/架构判断，从而让用户通过读代码积累对应岗位要求的经验。

视角原则：工程实现和架构设计都要覆盖，但具体在哪个维度上深挖、哪个维度一笔带过，取决于这个项目实际做了什么——不要为了套框架而强行分析项目里不存在的内容，也不要因为框架里没列到就漏掉项目里出现的重要设计。维度框架是检索表，不是评分表。

深度原则：分析必须落到具体代码细节，不能停在维度框架的泛泛复述上——每个结论都要能指向具体的文件/函数/代码片段，说清楚这段代码实际是怎么写的（数据结构、控制流、边界条件）。同时，看到一个设计后不能只描述"它做了什么"，还要主动对比业界通行方案，判断这个实现相对于常见做法是更简化/更取巧/更严谨，并给出"为什么可能这么设计"的推断（性能、团队规模、上线时间压力、还是单纯没做完善）。只描述不判断的分析是不合格的。

能力维度框架

对每个维度，标注了在 AI Agent/LLM 应用工程类岗位招聘要求中出现的相对频率（高/中/低），分析时优先深挖高频维度，但如果项目在低频维度上有出彩设计，同样值得记录。

1. Agent 单体核心能力（高频）

覆盖：Planning / 任务规划拆解、Reasoning / 多步推理、Tool Use / 工具调用、Memory（长期/短期记忆）、上下文工程（Context Engineering）、长链路任务执行、自我进化（Self-improving Agent）。

分析角度：

• 主循环结构：Agent 的 think-act-observe 循环是怎么实现的？是显式状态机（如 LangGraph 的图）还是隐式的 while 循环 + if/else？循环的终止条件是什么（步数上限/任务完成判定/超时）？
• 规划粒度：是"先整体规划再逐步执行"（Plan-and-Execute）还是"边想边做"（ReAct 式单步决策）？规划结果是不是可以被中途修正（reflect/replan）？
• 工具调用协议：工具的 schema 怎么定义和暴露给模型（JSON Schema/Pydantic/自定义 DSL）？模型选错工具或参数时怎么处理（校验、重试、fallback）？工具的执行是同步阻塞还是异步/并发？
• Memory 设计：短期记忆（当前对话/任务上下文）怎么截断和压缩（滑动窗口/摘要/token 计数）？长期记忆怎么持久化和检索（向量库/结构化存储/纯文本文件）？记忆写入的时机是每一步都写还是任务结束后总结写？
• 上下文工程：随任务变长，怎么控制送入模型的上下文不爆 token（压缩、摘要、按需检索、丢弃低价值历史）？上下文的组织方式是否体现了"哪些信息该长期保留、哪些该即用即弃"的判断。
• 多轮上下文管理：多轮对话或多步任务之间，状态怎么传递？是否有 session/thread 的概念，怎么隔离不同任务的上下文？
• 失败与纠错：单步执行失败（工具报错、模型输出格式不对）时，Agent 怎么处理——重试、请求人工介入、还是让模型自己反思重新规划？
• 自我进化 / 持久化 Agent（如果有）：Agent 会不会根据历史执行结果调整自己的策略/prompt（比如记录成功模式并复用）？长期运行的 Agent 状态是怎么持久化和恢复的？

2. Multi-Agent 协同与调度（高频）

覆盖：多智能体协同、角色分工、并发调度、分布式状态管理、Workflow 编排（AutoGen/CrewAI/LangGraph 等框架的多 Agent 能力）。

分析角度：

• 分工模式：多个 Agent 是固定角色预设（如 Planner/Executor/Critic）还是动态路由（一个 Router Agent 决定派给谁）？角色之间的边界怎么定义。
• 通信协议：Agent 之间怎么传递信息——共享内存/黑板模式、消息传递（pub-sub）、还是通过一个中心协调者转发？消息格式是否有统一 schema。
• 并发调度：多个 Agent 是并行执行还是严格串行？如果并行，资源竞争（比如同时调用同一个工具/写同一份状态）怎么处理，有没有锁或队列机制。
• 状态一致性：多 Agent 共享的全局状态（比如任务进度、共享上下文）在并发修改下怎么保证一致（乐观锁/版本号/单一写入者）？
• 终止与死锁：怎么判断整个多 Agent 任务"完成了"（谁说了算）？有没有防止 Agent 之间互相等待、无限循环讨论的机制（步数上限、超时、仲裁者介入）。
• 失败隔离：某个 Agent 失败/输出异常时，会不会拖垮整个协同流程？有没有隔离和降级设计（比如跳过该 Agent 或用默认策略兜底）。

3. Agent Framework / Runtime（高频）

覆盖：LangChain / LangGraph / AutoGen / CrewAI / MCP 协议；Agent 主循环、状态流转管理、工具调用网关、本地/远程工具适配、代码执行沙箱、权限隔离、Skill System。

分析角度：

• 自研 vs 依赖框架：项目是直接用现成框架（LangChain/LangGraph 等），还是自己撸了一套 runtime？如果自研，对标现成框架的话，抽象层次高在哪、低在哪、为什么这么取舍（性能？可控性？依赖包体积？）。
• 状态机设计：如果用了状态图（graph-based），节点/边代表什么？状态是怎么序列化和持久化的（能否中断后恢复）？状态转换的触发条件是硬编码还是可配置。
• 工具调用网关：本地工具和远程工具（RPC/HTTP/MCP Server）是不是统一了调用接口？有没有做统一的参数校验、超时控制、错误归一化？如果接了 MCP，Server 的发现和注册机制是什么样的？
• 代码执行沙箱（如果有）：用什么隔离技术（子进程/容器/WASM/受限解释器）？资源限制（CPU/内存/网络访问）怎么控制？沙箱逃逸的防护措施有没有考虑。
• 权限隔离：Agent 能调用哪些工具是不是可配置/可分级（比如只读 vs 读写）？有没有类似"用户确认后才执行危险操作"的机制。
• Skill/Plugin 系统（如果有）：新增一个能力是通过写代码扩展，还是通过配置/插件热加载？扩展点设计得是否清晰（接口契约是什么）。
• 调度与并发：多个任务/Agent 实例并发跑的时候，资源怎么分配、有没有队列或限流。

4. RAG 系统（高频）

覆盖：向量数据库（Chroma / FAISS / Milvus）、Embedding、检索排序/重排、Prompt 注入、知识库构建、解决幻觉问题。

分析角度：

• 数据摄入（ingestion）：文档怎么切分成 chunk（固定长度/按语义边界/递归切分）？chunk 的 overlap 策略是什么？有没有对不同文档类型（PDF/HTML/代码）做差异化处理？
• Embedding 策略：用什么模型做 embedding（本地模型 vs API），embedding 的维度和更新频率（增量更新 vs 全量重建索引）。
• 检索策略：纯向量检索还是 hybrid（向量 + BM25/关键词）？top-k 怎么定的，有没有做 rerank（用什么模型/规则）？有没有做查询改写（query rewriting/HyDE）？
• 上下文拼接：检索到的片段怎么组装进 Prompt（顺序、去重、长度截断策略）？有没有引用来源标注（citation），方便验证生成内容是否有据可查？
• 幻觉缓解：有没有做"检索结果为空/不相关时拒答"的兜底逻辑？生成结果和检索内容的一致性有没有做校验（比如 groundedness check）？
• 更新与一致性：知识库更新后，索引是怎么同步的？增量更新和检索一致性怎么保证（有没有版本控制/双写）？
• 多路召回（如果有）：是否针对不同类型问题（事实型 vs 摘要型）用不同检索策略。

5. LLM 调用工程化（高频）

覆盖：模型调用的重试、降级、超时、缓存、幂等性、成本控制；Prompt Engineering；Function Calling / Structured Output；多模型/多供应商适配（OpenAI/Anthropic/国产模型）。

分析角度：

• 重试与降级：调用失败（限流/超时/5xx）时的重试策略是什么（固定间隔/指数退避/抖动）？重试次数上限和降级路径（换模型/换供应商/返回缓存结果/直接报错）是怎么设计的？
• 超时控制：单次调用和整个任务链路分别有没有超时设置？流式响应（streaming）情况下怎么判断"卡住了"。
• 缓存：有没有对相同/相似请求做缓存（精确匹配 key，还是语义缓存）？缓存失效策略是什么。
• 幂等性：同一个任务被重复触发（比如用户重复点击、消息队列重复投递）时，怎么保证不会重复调用模型/重复产生副作用（幂等 key、去重表）。
• 成本控制：有没有 token 计数、按模型/按用户的成本统计？有没有根据任务复杂度动态选择模型（小模型先筛选，大模型精处理）？
• Prompt 工程实现：Prompt 模板是硬编码字符串拼接，还是有专门的模板引擎/版本管理？System Prompt 和 few-shot 示例是怎么组织和维护的（是否支持 A/B 测试或版本回滚）？
• Structured Output / Function Calling：怎么保证模型输出符合 schema（用模型原生 function calling，还是 prompt 约束 + 解析 + 校验失败重试）？解析失败时的容错逻辑。
• 多供应商适配：是否抽象了统一的 LLM 调用接口（类似 adapter/provider 模式），切换模型供应商的成本有多大？

6. 模型与算法基础（中频，偏研究/大厂岗位）

覆盖：Transformer/LLM/VLM 原理、强化学习与偏好对齐（SFT/DPO/PPO/GRPO/RLVR）、微调（LoRA）、本地推理部署（vLLM/Ollama）、推理加速（量化/蒸馏）。

分析角度：

• 训练 vs 纯调用：项目里有没有真正的训练/微调代码，还是完全基于闭源/开源模型的 API 调用？如果有微调，用的是全参微调还是 LoRA/QLoRA，训练数据是怎么构造的（人工标注/模型蒸馏/规则生成）。
• 对齐方法（如果涉及）：用的是 SFT 还是偏好对齐（DPO/PPO/GRPO），偏好数据从哪来（人工排序/模型自评/规则打分）。
• 本地部署与推理引擎：如果自己部署模型，用什么推理引擎（vLLM/TGI/Ollama/llama.cpp），有没有做批处理（continuous batching）、KV cache 复用。
• 推理加速：有没有量化（int8/int4/GPTQ/AWQ）、蒸馏、投机采样等加速手段，量化后的精度损失怎么评估的。
• 模型选型逻辑：项目怎么决定用哪个模型/哪个规格（延迟 vs 效果 vs 成本的权衡），有没有可替换的模型抽象层。

7. 系统架构与工程基础（高频）

覆盖：分布式系统、微服务、高并发高可用设计、数据库设计与调优（PostgreSQL/MySQL/Redis）、消息队列、缓存设计、容器化（Docker/K8s）、云平台部署。

分析角度：

• 服务拆分：项目是单体还是微服务？拆分边界是按业务域还是按技术层（API 层/任务执行层/存储层）？服务间通信用同步 RPC 还是异步消息。
• 状态管理：核心服务是无状态（方便水平扩展）还是有状态（比如长时间运行的 Agent session）？有状态的部分怎么做持久化和故障恢复（checkpoint/断点续跑）。
• 数据库设计：schema 设计是否体现了对读写模式的思考（比如高频写的表和高频读的表是否分离）？有没有索引设计、分库分表、读写分离的痕迹？
• 缓存设计：缓存放在哪一层（应用层/DB 层/CDN）？缓存和数据库的一致性怎么保证（cache-aside/write-through）？
• 消息队列：用在哪些场景（异步任务/削峰填谷/服务解耦）？消息丢失/重复/顺序性问题怎么处理。
• 并发与扩展性：高并发场景下有没有限流/熔断/背压（backpressure）设计？水平扩展的瓶颈在哪（比如某个有状态组件成为单点）。
• 容器化与部署：Dockerfile/K8s manifest 的设计是否体现了资源限制、健康检查、优雅关闭（graceful shutdown）等生产级考量。
• 私有化 / 国产化适配（如果涉及）：项目是否考虑了内网隔离、离线部署、国产模型/国产硬件适配？这类约束通常会体现在"可插拔的模型/存储后端"设计上，可以看它的抽象层是否为此留了口子。
• 可以从哪里找线索：issue/PR 讨论、CHANGELOG、架构文档（如果有 ADR/Architecture Decision Record）、性能测试代码。

8. 第三方集成与安全合规（中频）

覆盖：OAuth、Webhook、Rate Limit 处理、幂等性设计、数据隐私保护、模型安全、审计。

分析角度：

• 鉴权集成：对接第三方系统（如 HubSpot/Salesforce/Gmail 等）用的什么鉴权方式（OAuth2 授权码/刷新令牌流程），token 怎么存储和刷新。
• Webhook 处理：接收 webhook 时怎么验证来源合法性（签名校验）？怎么处理重复投递和乱序到达。
• Rate Limit：调用第三方 API 时怎么应对限流（本地限流器、退避重试、配额管理）。
• 数据隐私：敏感数据（用户输入、第三方数据）在日志/缓存/向量库里是否做了脱敏或加密？
• 模型安全：有没有对用户输入做 prompt injection 防护？有没有对模型输出做内容安全过滤？
• 审计：关键操作（谁在什么时候调用了什么工具、改了什么数据）有没有留痕，方便事后追溯。

9. 可观测性与运维（中频）

覆盖：监控告警、日志体系、Trace/全链路追踪、异常重试、断点续跑、灰度发布、回滚机制、成本监控。

分析角度：

• 日志：日志的结构化程度（纯文本 vs JSON 结构化）？关键路径（每次 LLM 调用、每次工具调用）是否都有日志，包含哪些字段（耗时、token 数、成功/失败）。
• 链路追踪：多步 Agent 任务的每一步是否可以串成一条 trace（用 trace_id/span），方便排查"某次任务在哪一步卡住了"。
• 监控指标：暴露了哪些 metrics（QPS、延迟分布、错误率、token 消耗、成本）？有没有对接 Prometheus/Grafana 之类的标准工具。
• 异常处理与恢复：任务执行到一半失败，能不能从断点恢复而不是从头重跑？有没有死信队列（DLQ）处理反复失败的任务。
• 发布与回滚：有没有灰度发布、feature flag 的设计，方便新 Prompt/新模型上线时控制影响面。
• 成本监控：有没有把 LLM 调用成本纳入监控体系，按维度（用户/任务类型/模型）拆解。

10. 评测与数据闭环（中低频，偏大厂/研究岗）

覆盖：Agent Benchmark、Tool-use Evaluation、Long-horizon Evaluation、Trajectory Dataset、AgentOps/MLOps。

分析角度：

• 评测集：项目有没有自带的测试用例/benchmark（不是普通单元测试，而是针对"Agent 表现好不好"的评测，比如任务完成率、工具调用准确率）？
• 评测方法：是人工评估、规则匹配，还是用另一个 LLM 做裁判（LLM-as-judge）？评分标准怎么定义的。
• 轨迹数据（trajectory）：有没有记录 Agent 的完整执行轨迹（每一步的思考/工具调用/结果），用于后续分析或训练数据积累？
• 回归防护：Prompt 或模型升级后，有没有机制防止效果退化（离线评测 + 上线前 gate）？
• 数据闭环：线上 badcase 有没有被收集回来，用于改进 Prompt、微调数据或规则。

11. AI 辅助研发效能（中频，偏平台/效能岗）

覆盖：AI Coding 工具集成（Copilot/Cursor/Claude Code）、代码生成/审查/补全、CI/CD、DevOps 实践。

分析角度：

• 项目本身是否是效能工具：如果是（比如代码生成/代码审查/智能补全工具），它是怎么理解代码上下文的（AST 解析/纯文本/embedding 检索）？生成结果怎么和 IDE/CI 集成？
• 工程化成熟度（对任何项目都适用）：测试覆盖到什么程度（单元/集成/e2e）？CI 流程包含哪些检查（lint/type check/test/security scan）？
• AI 在研发流程中的应用：如果项目本身用 AI 辅助生成代码/文档/测试，痕迹在哪里（比如生成的样板代码风格、commit message 风格）？
• 效能度量（如果适用）：项目有没有定义"效能提升"的度量指标，怎么验证 AI 工具确实带来了效率提升。

12. 多模态与文档理解（中低频，偏行业应用岗）

覆盖：OCR、Document AI、图像/视觉理解（VLM）、语音交互。

分析角度：

• 多模态输入处理：图像/语音/文档怎么转换成模型可处理的表示（OCR 文本提取 vs 直接喂给 VLM 做端到端理解）？
• 文档结构化：对复杂版式文档（表格、扫描件、多栏排版），有没有做版面分析/结构还原，还是简单粗暴地整页 OCR 成纯文本？
• 多模态与文本流程的衔接：提取出的多模态信息怎么并入 RAG/Agent 的主流程（作为额外上下文，还是独立的检索索引）？
• 准确率与容错：OCR/语音识别有误差是常态，项目有没有做置信度过滤、人工复核环节、或让下游 LLM 做纠错。

分析流程

1. 项目定位（初步扫描）：一句话说清这个项目是什么（Agent 框架 / RAG 工具 / 效能平台 / 模型服务 / 其他），对照上面 12 个维度，判断项目实际涉及哪几个维度（不要对所有维度都写满，没有的维度直接跳过或注明"不涉及"）。这一步可以用 Explore agent 做代码定位，避免占用主上下文。

2. 向用户确认范围，不要一次性生成全部内容：初步扫描完成后，先把"项目定位 + 识别到的能力维度列表（一行一个，附一句话概述）"展示给用户，然后询问用户接下来想要哪部分产出，例如：

   • 全部维度详细分析，还是只挑 1-2 个维度深入？
   • 要不要生成学习任务清单？
   • 要不要生成"与岗位要求的对应关系"这一节？ 只有在用户明确选择之后，才生成对应部分，避免一次性输出一份用户用不完的长报告。

3. 逐维度深挖（只针对用户选定的维度），每个维度必须包含以下五块内容，缺一不可：

   • 代码定位：核心代码位置（文件/模块/关键函数），给出 file_path:line 引用。禁止只写"项目做了 XX"这种没有代码依据的空泛描述。
   • 实现细节：按该维度"分析角度"列表里的具体问题逐条回答，要讲清楚真实的数据结构、控制流、关键参数/常量取值（比如重试次数具体是多少次、chunk size 具体多大）——这些具体数字和实现细节才是用户要学习的东西，不是"它做了重试"这种一句话结论。
   • 业界对比：这个实现和业界通行方案/更成熟的开源项目（如相关领域的知名项目）比，是标准做法、简化版、还是有自己的创新点？如果知道业界更常见/更健壮的做法是什么，要明确指出差异在哪。
   • 为什么这么做：推断作者为什么选择这个方案而不是其他方案——可能的原因包括性能权衡、实现复杂度、团队规模/时间成本、目标场景的特殊性、或者单纯是还没做完善（这也要如实指出，不要为了显得"都合理"而强行找理由）。工程视角（实现是否健壮/有没有坑）和架构视角（抽象边界、扩展点是否合理）都要覆盖到这个判断里。
   • 值得学习的点：如果用户要通过读这段代码积累经验，应该重点看懂/记住什么——优先给"这个设计模式/取舍在其他场景也适用"这类可迁移的经验，而不是项目特有的细枝末节。

4. 产出文件到 .learn/ 目录：所有产出物写入被分析项目根目录下的 .learn/<project-slug>/（project-slug 用项目名的 kebab-case，比如分析 langgraph 就是 .learn/langgraph/；如果同一个项目分多次分析不同模块，复用同一个 project-slug 目录，不要重复创建）。不要把所有内容塞进一个大文件，按下面的文件拆分方案分块写：

   • .learn/<project-slug>/00-overview.md：项目定位 + 涉及的能力维度总览（每个维度一行概述 + 值得学习的点）+ 与岗位要求的对应关系（如果用户选了这部分）。这个文件始终生成，作为索引，并在末尾列出指向其余文件的相对链接。
   • .learn/<project-slug>/<序号>-<维度 slug>.md：每个用户选定的维度单独一个文件，序号按维度框架里的编号来（比如 02-multi-agent.md、04-rag.md），内容就是该维度的五块深挖内容（代码定位/实现细节/业界对比/为什么这么做/值得学习的点）。一个维度一个文件，避免单个维度分析过长时拖累其他维度的可读性，也方便用户分次只读某一个维度。
   • .learn/<project-slug>/tasks.md：学习任务清单（如果用户选了这部分），可勾选 checklist，按维度分组，每组标题对应到具体的维度文件方便跳转。

   写文件前如果 .learn/ 或 .learn/<project-slug>/ 不存在就新建；如果 00-overview.md 已存在（说明之前分析过这个项目），要读取现有内容后追加/更新，而不是覆盖掉用户之前保存的分析。

   00-overview.md 模板：

   text

   # <项目名> 分析总览
   
   ## 项目定位
   ...
   
   ## 涉及的能力维度
   - [维度 A](02-xxx.md)：概述 + 值得学习的点
   - [维度 B](03-xxx.md)：...
   
   ## 与岗位要求的对应关系（如果用户选了这部分）
   简要说明这个项目主要能练到哪些能力维度/岗位要求，哪些常见要求这个项目覆盖不到（需要额外找项目补）。
   
   ## 任务清单
   见 [tasks.md](tasks.md)
   

   单个维度文件模板（如 02-multi-agent.md）：

   text

   # <维度名>
   
   - 代码定位：xxx.py:123
   - 实现细节：（具体数据结构/控制流/关键参数）
   - 业界对比：（对比通行方案，指出差异）
   - 为什么这么做：（推断设计动机与取舍，工程+架构视角）
   - 值得学习的点：（可迁移的经验）
   

5. 产出学习任务清单（如果用户选了这部分），写入 .learn/<project-slug>/tasks.md，格式为可勾选的 Markdown checklist，按维度分组，每条任务具体到"读懂/复现/对比"某个模块，例如：

   text

   ## <维度名>（见 02-xxx.md）
   - [ ] 读懂 xxx 模块的重试/降级机制，画出状态转换图
   - [ ] 对比该项目的 Memory 设计和 LangChain 的 Memory 抽象有什么不同
   - [ ] 尝试给 xxx 模块补一个单元测试，验证你理解了它的边界条件
   

   任务要具体可执行，避免"了解一下 RAG"这种空泛任务。

使用方式

用户给出一个本地路径或 repo 时：先做步骤 1 的初步扫描，然后按步骤 2 和用户对齐范围，再按用户选择生成对应内容，写入被分析项目根目录下的 .learn/<project-slug>/（分多个文件，见步骤 4）。如果项目很大，优先聚焦用户明确提到的模块或最匹配框架高频维度的部分，而不是试图覆盖整个代码库。分析完成后，把这次生成/更新了哪些文件（相对路径）列给用户，而不是把报告内容整段贴在对话里。