用途
code-analysis 是一个用于结构化源代码分析与功能深度剖析的技能，采用多轮次（multi-pass）方法论。它适用于用户要求分析某个代码库、解释某个功能如何工作等场景，其目标是产出一份可追溯、可验证的分析文档。
核心原则（IRON LAW）
技能声明一条“铁律”：每一个结论都必须能追溯到源代码，需引用文件路径、行号范围与代码片段；没有代码证据就没有结论。在描述逻辑时，绝不能含糊带过触发条件、边界检查或错误路径，必须明确陈述。
工作流
该技能定义了四个步骤，其中部分步骤标注为强制或阻塞：
- 步骤 1：范围与深度（Scope & Depth，阻塞性）
- 步骤 2：结构发现（Structure Discovery，必需）
- 步骤 3：撰写文档（Compose Document，必需）
- 步骤 4：自检（Self-Check，必需）
1. 范围与深度（阻塞）
在继续前需与用户澄清三件事：分析什么（单个功能、一个模块、跨模块交互还是整个仓库）、目标读者（新入职工程师、架构师还是外部评审者，影响深度与术语程度）、输出位置（Markdown 文件、wiki 页面还是 PR 评论，影响格式与长度）。
随后确定深度层级：
| 层级 | 范围 | 预期输出 |
|---|---|---|
| 功能（Feature） | 单个功能端到端 | 入口点、流程、触发条件、边界情况、关键代码路径 |
| 模块（Module） | 一个模块 / 包 | 公共 API 面、内部结构、依赖、数据流 |
| 跨模块（Cross-module） | 两个及以上模块间的交互 | 接口契约、调用链、跨边界的数据转换 |
| 代码库（Codebase） | 整个仓库 | 架构分层、组件图、2-3 条关键端到端流程 |
如果用户的请求能清晰对应到某一层级，可跳过澄清直接进行。
2. 结构发现（必需）
按顺序执行各轮次通行（Pass），深度层级决定每轮的应用广度。
- Pass A — 入口点与边界：识别系统如何被进入及边界所在。入口点包括 HTTP 处理器、CLI 命令、事件监听器、定时任务、主函数、导出的 API。外部边界包括数据库、缓存、消息队列、第三方服务、文件系统。内部边界包括模块/包接口、抽象层、插件契约。对每个入口点，需说明：触发条件、输入形态、它调用的第一个内部函数。
- Pass B — 依赖与分层：映射结构关系，包括模块依赖图（谁导入谁）、分层（表示层 → 业务逻辑 → 数据访问 → 基础设施，并标记违规）、共享状态（全局变量、单例、线程局部、缓存，注明生命周期与归属）、配置（配置在哪里加载、如何传播、哪些值影响行为分支）。当依赖图节点超过 5 个时，生成 Mermaid 组件图。
- Pass C — 核心流程追踪：选择 2-3 条关键路径（面向用户或架构上重要的），逐条端到端追踪。每条路径需覆盖以下全部要点：触发条件（引用确切表达式）、正常路径（逐步走过顺利路径，注明每次函数调用与数据转换）、分支逻辑（每一个 if/else、switch/match 与守卫子句，说明每个分支的语义含义而不只是主分支）、边界与边缘情况（null/空/零值、空集合、并发访问、超时、溢出，代码如何处理，若不处理则标记出来）、错误路径（捕获/回退/重试逻辑：捕获什么异常、如何恢复、副作用是否回滚）、退出条件（调用方收到什么：返回值、响应、发出的事件，以及系统留下的状态）。当路径有 3 个及以上分支或异步步骤时使用 Mermaid 流程图；当路径跨越 3 个及以上组件时使用时序图。
3. 撰写文档（必需）
将发现整理为指定结构。
元数据表置于文档最前，包含四项：作者（使用运行环境中的真实工具/模型名，回退为 AI-assisted，绝不编造）、创建时间（当前时间，格式 YYYY-MM-DD HH:mm）、仓库（通过 git remote get-url origin 获取 HTTPS URL，SSH 需转 HTTPS 并去掉 .git）、提交（短哈希加主题，如 a1b2c3d feat: add login，通过 git log -1 --format='%h %s' 获取）。
正文按固定顺序：
- A. 概览 — 一段话说明系统/功能做什么、谁使用、为何存在。
- B. 架构 / 组件图 — Mermaid 图展示主要组件及其关系。模块级及以上必需，功能级可选。
- C. 功能 / 模块分析 — 对每个功能或模块按以下顺序呈现：整体逻辑流（先用平实语言描述端到端流程，当流程有分支、循环或异步步骤时补充 Mermaid 流程图或伪代码块）；用法与触发条件（功能如何被调用：UI 入口、CLI 命令、定时任务、事件触发等，需说明确切触发表达式而非仅“当触发时”；若功能暴露 API，按字段/内容表格记录端点、请求参数、响应结构、关键逻辑、请求示例、响应示例）；实现细节（优先用伪代码加源文件路径而非原始代码，源码引用格式为 startLine:endLine:filepath，片段不超过 30 行，突出非显而易见的设计决策、权衡或已知限制，覆盖所有分支而不只是顺利路径）。
- D. 端到端流程追踪 — Pass C 中追踪的 2-3 条路径，以叙述加图表呈现。跨模块级与代码库级必需，功能/模块级可选。
- E. 参考资料 — 官方文档、RFC、设计文档、ADR 以及关键源文件链接。
4. 自检（必需）
交付前逐项运行以下检查，每项均须通过：
- 每个事实性论断都引用了文件路径与行号范围（在文档中搜索没有代码引用的论断）。
- 不出现未说明条件的“当条件满足时”（搜索含糊的触发措辞）。
- 每个 if/else 与 switch 的所有分支都有解释（对比代码分支数与文档）。
- 错误/捕获路径有描述而非跳过（在被追踪代码中搜索 try/catch，确认每个都有记录）。
- Mermaid 图与文字叙述一致（走查图的节点，确认与描述的步骤对应）。
- 元数据表完整且仓库 URL 可点击（确认四行都已填）。
- 作者字段使用真实工具/模型名而非编造（确认值匹配运行环境；若未知，须写 AI-assisted）。
精确性要求
以下规则贯穿整个工作流的发现、撰写与自检。
触发条件：写明确切谓词而非概述。反例：“当校验失败时抛出异常。”正例：“当 age < 0 或 age > 150 时，抛出 ValidationError('age out of range')（validators.py:23）。controller.py:45 中的调用方捕获它并返回 HTTP 400。”
分支逻辑：记录每一个分支，而不只是主路径。反例：“函数处理请求并返回响应。”正例：“若 user.is_admin（handler.py:30），绕过限流并调用 admin_process()。否则检查 rate_limiter.allow(user.id)（handler.py:33）：若允许，调用 standard_process()；若拒绝，返回 HTTP 429 并带 Retry-After 头。”
边界与边缘情况：逐一列举每个边界（null、空、零、溢出、并发），绝不使用“等等”或“以及其他边缘情况”。若无守卫，应标记为潜在运行时错误。
错误路径：对每个捕获/回退/重试，说明捕获什么、恢复机制以及副作用是保留还是回滚。
反模式
文档明确列出应避免的行为：粘贴 50 行以上原始源码而不总结逻辑；写“恰当处理错误”或“处理数据”而不具体说明；只描述顺利路径而跳过 else/default/catch 分支；用“等等”“诸如此类”回避列举边界；没有文件路径与行号范围就声称行为；产出与文字描述矛盾或遗漏步骤的图表；只罗列每个函数签名而不解释其间的数据流；描述代码“是什么”（结构目录）而不解释它“做什么”（行为追踪）。
限制
资料未提供该技能的安装方式、运行平台、依赖要求、收费情况或授权信息，这些内容暂未提供。