带质检工序的流水线式源码考察队 —— 对任意项目（开源或私有）进行系统化深度考察，产出结构化架构文档与工程风险 / 源码缺陷 / 设计问题评估。
版本：v2.6.2 ｜ 语言：中文 / English ｜ 形态：META-SKILL（Skill 元技能）
deep-code-analyzer 是一套可移植的源码深度考察流程协议。它以「流水线 + 显式状态机 + 契约驱动」的方式，把一个 AI 代理（或一组代理）组织成一支只分析、不修改的考察队，对任意代码库执行：
-
全景扫描 → 模块映射 → 数据流追踪 → 模式提取
-
（经人工确认后）目标深挖 / 功能复现 / 缺陷扫描
-
报告组装 → （可选）实测验证
所有评估结论以源码证据为锚：可复核的结论标注置信度，无法复核的标注 unverified，禁止输出与证据脱节的个人偏好。
首次使用前必读——避免踩坑。
| ✅ 你可以 | ❌ 你不可以 |
|-----------|-------------|
| 读项目代码、文档、配置文件 | 直接修改、删除、重写项目中的任何代码 |
| 分析架构、追踪数据流、提取设计模式 | 执行项目的编译、运行、测试、部署 |
| 评估工程风险、扫描源码缺陷、给出改进建议 | 把建议直接落地为代码改动（可输出方案，执行交由用户） |
| 为指定模块 + 相关 docs 分析并输出修改方案参考 | 代替用户做决策——所有关键节点必须经过确认 |
| 生成架构分析报告、功能复现指南、迁移方案 | 跳过人工介入点——S4 完成后必须停止等待确认 |
| 踩坑 | 正确做法 |
|------|----------|
| "帮我优化一下这段代码" → 直接修改 | 本技能不直接改代码，但链路是：定位问题（附源码证据）→ 给出修改方案 → 询问"是否按此方案修改"，执行交由用户或编码模式 |
| "运行一下这个项目看看效果" → 尝试执行 | 回答"我只分析不执行，这是项目的入口文件与启动方式…你可以自行运行" |
| 以为 S1-S4 跑完就自动出报告了 | S4 完成后强制停止等待确认，不点"跳过"不会自动往下走——这是设计，不是卡住 |
| 想改代码但不熟悉源码，不知从哪下手 | 选阶段选择框的 ⑤ 修改参考：指定要改的模块，先对该模块 + 相关 docs 分析，输出修改方案参考 |
-
需求明确（点名算法名/功能名/缺陷目标）→ 直接聚焦模式（S1 快速全景 → 直达 S5/S6/S6B）。
-
需求不明确（只说"分析这个项目"）→ S1 全景扫描完成后，展示项目卡片，给出阶段选择框，由用户决定后续方向：
【阶段选择 · S1 完成】已产出项目全景卡片。请选择后续阶段（可多选，回复编号或文字即可）：
① 继续全景链路：S2 模块映射 → S3 数据流 → S4 模式提取（跑完在 S4 介入点再次停止）
② 直接深挖目标：____（可指定，如"缓存机制"）→ S5
③ 复现功能：____（可指定）→ S6
④ 源码缺陷扫描 → S6B
⑤ 修改参考：指定要改的模块，先对该模块 + 相关 docs 分析，输出修改方案参考 → S5 聚焦 + 修改参考输出
⑥ 跳过深挖，直接交付报告 → S7
| # | 铁律 | 含义 |
|---|------|------|
| 1 | 正交解耦 | Meta 层只管流程（S1→S8），Atom 层只管执行（每一步只做一个操作） |
| 2 | 显式状态机 | 所有流转必须有可枚举的定量闸门（覆盖率 ≥ 80%、环节 ≥ 5、模式 ≥ 3、子章节 ≥ 7），禁止「然后 / 接着 / 差不多」 |
| 3 | 契约驱动 | 原子技能间只通过 schemas/context.md 定义的 Context 传递数据，禁止依赖隐式记忆 |
| 4 | 有界执行 | 每阶段重试 ≤ 2 次、全流程总轮次 ≤ 24、深挖 / 复现循环 ≤ 3 轮、缺陷扫描循环 ≤ 2 轮 |
| 5 | 复核后落档 | 任何关键结论写入产出文档前，必须完成至少一次针对原始源码的独立取证复核；无法复核的必须显式标注 unverified |
| 6 | Docs 优先 | 存在文档目录时，先读文档建立框架认知（三级分层、预算受控），以文档声明结构为"预期基线"解剖源码；文档与源码不符处为高价值异常信号 |
S1 全景扫描 → S2 模块映射 → S3 数据流追踪 → S4 模式提取
│
├──【人工介入点】范围与深度确认（必须停止等待）
│
├─→ S5 目标深挖（可循环 ≤ 3 轮）
├─→ S6 功能复现（可循环 ≤ 3 轮）
├─→ S6B 缺陷扫描（可选分支，默认不执行）
│
└─→ S7 报告组装与交付
└─→（可选）S8 实测验证（能力驱动，命令白名单）
| 阶段 | 名称 | 关键流转闸门 |
|------|------|------------|
| S1 | 项目全景扫描 | 产出项目卡片：技术栈 + 项目类型 + 入口点 + 设计原则（四必填）+ docs_map（Docs 优先侦察） |
| S2 | 模块映射 | 模块清单覆盖率 ≥ 80% 一级源码承载目录，每模块含一句话职责 + 入口路径；以 docs_map 声明的模块为预期基线对照 |
| S3 | 数据流追踪 | 数据流图 ≥ 5 环节，每环节假设-验证 + 置信度，假设表 ≥ 3 条已闭合 |
| S4 | 设计模式提取 | 提取 ≥ 3 个模式/亮点/约定，每条带统一证据格式 + 置信度 |
| S5 | 目标深挖 | 符号追踪表 + 调用链 + 状态机图 + 复杂度分析 + 替代方案对比 + 配置速查 |
| S6 | 功能复现 | 功能定位 + 依赖链 + 分步拆解 + 数据契约 + 边界条件 + 代码骨架 + 配置速查 |
| S6B | 缺陷扫描 | 每条含 文件:行号 + 类型 + 证据 + 级别(P0-P3) + 置信度 |
| S7 | 报告组装 | 必填章节全覆盖 + 图存在性硬闸门 + 关键数字带 origin 标注 |
| S8 | 实测验证 | 命令白名单（只读/基准类），任何写操作命令拒绝执行 |
-
全量模式（默认）：按 S1→S7 顺序执行。
-
聚焦模式：用户首条消息即明确指定深挖 / 复现 / 缺陷扫描目标时，先执行 S1 最低限度全景（仅技术栈 + 入口点），随后直接跳转对应阶段（跳转前向用户确认一次）。
-
恢复模式：存在
_context_checkpoint.json时，读取 checkpoint 重建 Context，从下一个未完成阶段继续，不重跑已完成阶段。
S4 完成后必须停止并向用户展示 Stage 1-4 初步全景分析结果，收集四个方向的指令：
① 深挖目标（预填 [必挖] / [CANDIDATE] 候选）→ S5
② 复现功能：____ → S6
③ 源码缺陷扫描（默认不执行，省 token）→ S6B
④ 跳过，直接交付报告 → S7
-
[必挖]强制消费：至少 1 条[必挖]异常信号必须进入 S5，或由用户显式跳过并记录理由。 -
无响应处理：用户 3 轮未回复 → 默认跳过 S5/S6/S6B，未确认项写入
human_decisions.pending_confirmations后进入 S7，不报错、不无限等待；交付时提醒可补做项，回复「深挖 <目标>」「复现 <功能>」「扫描缺陷」即可从 checkpoint 续跑。
-
每阶段结束后，将
stage_outputs + human_decisions + metadata写入output_dir/_context_checkpoint.json（覆盖写，UTF-8）。 -
checkpoint 是跨会话恢复的唯一事实来源；对话上下文只是缓存。
项目存在文档目录（docs/、documentation/ 等）时，S1 先读文档建立框架认知，再解剖源码：
| 层级 | 内容 | 读取方式 |
|------|------|----------|
| L1 必读 | 文档目录树（2 层）+ 根级索引（index.md、README.md、SUMMARY.md 等） | 全读（小文件） |
| L2 按需精读 | 架构 / 设计 / 规范类 + 入门 / 指南类 | 按相关性精读 |
| L3 标题扫描 | API / 参考 / 变更日志类 | 仅列文件名 + 首行标题 |
-
读取预算硬上限：L2 + L3 合计 ≤ 10 个文件；单文档 > 400 行只读前 400 行 + 章节标题
-
产物
docs_map：文档结构树 + 声明技术栈 + 声明模块（S2 预期基线）+ 架构概念 + 术语表 + 漂移信号 -
漂移检测：文档声明但源码缺失的模块 →
[必挖]异常信号；源码存在但文档未提及的一级目录 →[可选]信号
采样三档（控制 Token 消耗）
| 采样档位 | 模块规模（文件数） | 采样策略 | 备注 |
| :--- | :--- | :--- | :--- |
| 低消耗 | ≤ 20 | 全读，不采样 | 上下文窗口压力小，保证完整性 |
| 中消耗 | 21 – 100 | 读取 min(15, max(5, ceil(n/10))) 个核心文件 | 动态采样，平衡覆盖率与 Token 开销 |
| 高消耗 | > 100 | 不进自动采样，标记 [CANDIDATE] 加入深挖候选池 | 由人工决策，防止无效 Token 浪费 |
-
仓库内已读 →
repo_verified -
仓库内推断 →
repo_inferred -
外部依赖已读（venv / node_modules 定位成功）→
external_read -
外部依赖未读 →
external_unread，必须附定位命令（如pip show <pkg>），标记后跳过该模块继续
S1 结束后探测宿主能力并写入 metadata.capabilities：能否执行命令、能否读仓库外依赖、能否统计 token、能否提供结构化交互组件——探测结果决定后续可选项（如仅当 can_execute_commands 为真才启用 S8 实测）。
deep-code-analyzer/
├── SKILL.md # Meta 层主文件（流程编排 + 全局规则）
├── README.md # 本文档
├── atoms/ # Atom 层：可独立执行的原子步骤
│ ├── 01-scan-landscape.md # S1 项目全景扫描
│ ├── 02-map-modules.md # S2 模块映射
│ ├── 03-trace-dataflow.md # S3 数据流追踪
│ ├── 04-extract-patterns.md # S4 设计模式与架构原则提取
│ ├── 05-deep-dive-target.md # S5 目标深挖（可循环）
│ ├── 06-reproduce-feature.md # S6 功能复现研究（可循环）
│ ├── 06b-scan-defects.md # S6B 源码缺陷与工程风险扫描（可选）
│ ├── 07-assemble-report.md # S7 报告组装与交付
│ └── 08-measure.md # S8 实测验证（可选）
├── references/
│ ├── capabilities.md # 12+1 维度能力覆盖检查清单
│ └── report-template.md # 统一报告骨架模板
└── schemas/
└── context.md # Context 结构契约（跨原子唯一数据通道）
将本目录放入宿主环境的技能目录（如 skills/deep-code-analyzer/），由宿主技能加载工具注册；若宿主环境的技能加载工具不可用，直接从技能安装目录读取 SKILL.md 及 atoms/、schemas/、references/ 下全部文件，按 Meta 层执行，流程不变。
对任意 AI 代理说：
-
「分析 XX 项目结构」
-
「深挖 XX 算法/机制」
-
「解析 XX 架构」
-
「帮我理解 XX 代码库」
-
「复现 XX 功能」
-
「评估 XX 工程风险」
-
「扫描 XX 源码缺陷」
原子中提到的工具名均为功能性描述（枚举目录、读取文件内容、全文检索、跨文件跳转定位等），执行时映射到宿主环境提供的等价工具，不得因特定工具名不存在而中断流程。
-
默认为文件集：
README.md（架构全景图）、architecture-analysis.md（模块依赖关系图）、tech-stack.md（依赖拓扑图）+ 各专题文件，落盘于<项目根>/<项目名>-analysis/。 -
三份基础文件各含 ≥ 1 张非空图（Mermaid 或 ASCII 形式）——图存在性是硬闸门。
-
关键数字均带
origin标注；报告章节树与references/report-template.md严格一致。
本技能自身任何结构性修改（采样规则、契约字段、原子结构）后，必须跑一轮回归验证：用 300–500 文件的开源小项目执行全量流程（或至少 S1–S4 + 一次 S5），对照验收清单逐条核对：
-
checkpoint 记账自检 gate 通过
-
报告关键数字均带
origin标注 -
巨型模块出现在人工介入点候选池
-
报告章节树与
references/report-template.md一致 -
外部依赖断头有定位命令或显式
external_unread -
无实测的性能/复杂度结论带
[推演]标注 -
Docs 优先：有文档目录的项目 S1 产出
docs_map且漂移信号进入异常信号池；无文档目录项目docs_map=null且不阻断流程
清单未全绿前不得视为改动生效。
本项目采用 MIT 许可证 开源。
你可以自由使用、修改和分发本项目的代码，但需保留原版权声明。
本项目按"原样"提供，作者不承担任何责任。
Copyright © 2026 QinLuza 魔法少女独断万古