Internalize Me

SKILL.md

---
name: internalize_me
description: 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` 模板：
   ```
   # <项目名> 分析总览

   ## 项目定位
   ...

   ## 涉及的能力维度
   - [维度 A](02-xxx.md)：概述 + 值得学习的点
   - [维度 B](03-xxx.md)：...

   ## 与岗位要求的对应关系（如果用户选了这部分）
   简要说明这个项目主要能练到哪些能力维度/岗位要求，哪些常见要求这个项目覆盖不到（需要额外找项目补）。

   ## 任务清单
   见 [tasks.md](tasks.md)
   ```

   单个维度文件模板（如 `02-multi-agent.md`）：
   ```
   # <维度名>

   - 代码定位：xxx.py:123
   - 实现细节：（具体数据结构/控制流/关键参数）
   - 业界对比：（对比通行方案，指出差异）
   - 为什么这么做：（推断设计动机与取舍，工程+架构视角）
   - 值得学习的点：（可迁移的经验）
   ```
5. **产出学习任务清单**（如果用户选了这部分），写入 `.learn/<project-slug>/tasks.md`，格式为可勾选的 Markdown checklist，按维度分组，每条任务具体到"读懂/复现/对比"某个模块，例如：
   ```
   ## <维度名>（见 02-xxx.md）
   - [ ] 读懂 xxx 模块的重试/降级机制，画出状态转换图
   - [ ] 对比该项目的 Memory 设计和 LangChain 的 Memory 抽象有什么不同
   - [ ] 尝试给 xxx 模块补一个单元测试，验证你理解了它的边界条件
   ```
   任务要具体可执行，避免"了解一下 RAG"这种空泛任务。

## 使用方式

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