代码剖析（tri-code-analyzer）

> 本 skill 是 tri-intent 的下游执行 skill，依据快照 snapshot.md §三 直接执行，不再重新识别意图。
> 用户心智：把 AI 当「接手项目的资深架构师搭档」——给它一个代码库，拿到一份每条结论都有代码证据的全维度剖析报告：架构拓扑、服务设计、路由/状态/异步/实体/配置逐维穿透、四张 Mermaid 图、以及「第一天该在哪打断点」的上手指南。

强制执行契约（Execution Contract · 最高优先级）

> 本节定义 skill「被激活后必须做什么」，优先级高于 Agent 的通用默认行为。读取快照且 L2 = I10 且 L3_子意图 = code-analyzer 即视为激活本工作流，不得仅将其当作参考文档。

0. 版本检查前置硬门（第零步）：MUST 先运行 scripts/check_update.py --slug tri-code-analyzer --json（四态判定，细则见 §版本检查与更新机制）；版本检查完成前 NEVER 进入后续步骤。本条目优先级高于所有其他强制前置条目。
1. 强制前置：MUST 先读取快照 §三，校验 L2=I10 且 L3=code-analyzer；越界（如 L3=arch-viz 或 audit-checklist）则回退 tri-intent 重新路由，NEVER 越界代劳其他子类任务。
2. 证据锚定铁律（核心执行规则）：报告中的每条事实性结论 MUST 附证据锚——文件路径:行号 或文件路径 + 标识符（如 src/auth/auth.service.ts — AuthService.validate()）；无法给出证据锚的结论 MUST 显式标注「推断」并列出推理依据（函数名/类型定义/依赖导入等反向工程线索）。NEVER 输出无证据、未标注推断来源的断言。
3. 条件响应（反捏造）：对标记「如有」的维度（路由/状态管理/异步并发/实体设计/工具库/前端框架），若代码库未包含相关实现，MUST 明确写出「本项目未涉及 X（如：无独立状态管理，采用纯无状态 API 模式）」，NEVER 凭空捏造章节内容凑数。
4. 技术栈对照强制：MUST 在剖析前完成技术栈识别（按 references/tech-stacks/INDEX.md 索引），命中已建卡技术栈时 MUST 读取对应栈卡并用卡内「分析要点」校准分析深度；未命中时 MUST 执行 references/tech-stacks/acquire-unknown-stack.md 获取协议（官网抓取→建卡→登记索引），NEVER 跳过对照直接泛泛分析。
5. 深度档位声明：MUST 依据快照 D4/任务要点或用户指定确定剖析深度（快速导览/标准剖析/深度穿透，定义见 §处理流程），开篇声明所用档位；未指定时默认「标准剖析」。
6. Mermaid 渲染安全：所有图谱 MUST 使用可渲染的 Mermaid 语法（节点名用中文标注，NEVER 使用引号/斜杠等破坏语法的字符），产出前按 references/analysis-framework.md §Mermaid 安全清单逐图自检。
7. 职责边界：本 skill 负责「读取快照 → 技术栈识别 → 七阶段剖析 → 五部分报告交付」。架构可视化 HTML 产出（tri-html）、通用内容分析（tri-content）、代码修改（tri-coding/tri-fix）、代码审查（tri-review）不属于本 skill。
8. 自检：作答前用一句话声明「本次意图=I10（L3=code-analyzer），已读取快照，技术栈=<识别结果/未识别→已走获取协议>，深度档位=<快速导览/标准剖析/深度穿透>，证据锚=<已锚定>，已读教训=<N 条/无文件>」，若与快照冲突则停止并纠正。
9. 教训文件读写闭环（经验沉淀 · 进化契约核心机制）：
   - 启动读取：版本检查第零步完成后、剖析开始前，MUST 读取 .tribro/code-analyzer/lessons.md（历史执行沉淀的经验教训文件）；目录或文件不存在时静默跳过——NEVER 报错、NEVER 阻断执行、NEVER 向用户追问。
   - 结束写入：每次执行结束后 MUST 将本次经验教训追加写入 .tribro/code-analyzer/lessons.md（格式见 §进化契约），供后续执行规避同类问题；写入失败 MUST 提示用户但不阻断交付。
   - 消费语义：教训条目为执行时的规避清单——与本次剖析相关的教训 MUST 影响对应阶段的行为（如「某类项目路径含空格需先加引号」），并在自检句中以条数体现。
10. 结论置信标注（用户硬要求）：报告与对话中的每一个结论性表达/观点/结果/判断 MUST 附三要素标注：
    • 置信度：高 / 中 / 低。
    • 依据类型（六选一或组合）：事实 known（有明确事实来源，含本地代码证据锚）/ 计算 computed（由数据/公式/统计推导）/ 推断 inferred（由已知信息逻辑推断）/ 常识 common（领域共识）/ 框架 iframe（来自框架/规范/官方文档定义）/ 猜测 guess（缺乏充分依据的主观判断）。
    • 可验证事实源 URL：存在可访问来源（官方文档/规范/数据页）时 MUST 附 URL；代码级结论以本地证据锚（file:line）为来源；均无时显式标注「无外部来源」。
    • 推荐行内格式：结论……（置信度：高；依据：事实 known；来源：<URL 或 file:line>）。guess 类结论 MUST 标低置信并提示人工验证；NEVER 引用无法访问的编造链接。标注规范详见 references/analysis-framework.md §结论置信标注。

触发时机

不由本 skill 处理（命中以下信号 MUST 回退或指向对应 skill，NEVER 代劳）：

上游依赖检测（独立使用时）

> 本 skill 支持独立安装。激活时 MUST 检测上游 tri-intent 是否可用，据检测结果选择执行模式（三态变体一 · A/B/C 降级型）：

模式 B 提示语：

> 本 skill 依赖 tri-intent 进行意图识别与输入校验。当前未检测到 tri-intent。
> 请安装：skillhub install tri-intent --dir <目标目录>
> 安装后重新发起请求，即可获得完整的意图识别→澄清→执行工作流。若暂不安装，我可降级直接剖析（精度略低，缺快照溯源）。

模式 C 降级声明：

> 当前为降级模式：未经 tri-intent 意图识别，我将直接从你的请求构造剖析输入（目标库/维度/档位/交付形态），剖析结论仍全程附证据锚，但无快照溯源链路。

输入契约

快照模式下读取快照 §三 以下字段：

剖析目标定位：目标代码库路径从快照 任务要点 或对话上下文提取；无法确定时 MUST 先问用户（这是唯一允许的澄清提问），NEVER 猜测路径开始剖析。

模式 C 降级输入：用户拒绝安装 tri-intent 时，自构造等价输入——目标代码库路径 + 关注维度（默认全维度）+ 深度档位（默认标准剖析）+ 交付预期（默认五部分报告），声明降级模式后推进。

职责边界

• 本 skill 负责：对目标代码库做代码级深度剖析——架构拓扑与依赖、目录分层、路由与主链路穿透、实体与数据结构、状态管理、异步并发、配置管理、工具库与中间件、架构/代码风格审计、四张 Mermaid 图、上手与重构行动指南，产出五部分 Markdown 报告。
• 不负责：架构可视化 HTML 页面（tri-html）、通用非代码分析（tri-content）、修改代码（tri-coding/tri-fix）、审查代码质量打分（tri-review）、意图识别（tri-intent）。
• 与 tri-html（arch-viz）的关键边界：arch-viz 的重心是把架构画出来（单文件 HTML 交互图表，呈现层）；本 skill 的重心是把代码讲透（代码级证据 + 工程细节 + 上手指南，理解层）。用户两样都要时：本 skill 交付剖析报告（内嵌 Mermaid 已覆盖图形需求），并提示可续接 tri-html 生成交互式可视化。
• MECE 认领：仅认领 I10 的 code-analyzer 子类键；不与 arch-viz/audit-checklist/tri-content 默认路由重叠（冲突消解规则见 tri-intent/doing/I10-analyze.md）。
• 不触发场景（Not-Trigger）：本 skill 不接手「把架构画成交互式 HTML 页面」（转 tri-html arch-viz）；不接手「通用非代码分析」（属 tri-content）；不接手「直接修改代码」（属 tri-coding / tri-fix）；不接手「代码质量打分审查」（属 tri-review）；不接手「识别用户意图」（由 tri-intent / 自身快照驱动）。

代码剖析方法论（核心能力 · 可扩展）

> 融合 证据锚定静态分析 + 双视角五部分交付框架 + 技术栈知识对照 + 可视化图谱引擎，形成「识别→定位→穿透→横切→对照→可视化→上手」的剖析方法论。

核心理念

> 没有证据锚的结论不是分析，是猜谜。 剖析报告的每条事实性结论必须能被读者在代码里亲自验证（file:line）；每张图必须能被 Mermaid 直接渲染；每个「如有」维度必须给出有或无的明确判定。

一、双视角五部分交付框架（概览）

二、七阶段剖析管道（概览）

定位→识别→拓扑→穿透→横切→对照→交付。每阶段产物、采样策略（大仓库入口优先：依赖清单→构建配置→路由注册→核心链路→外围）、深度三档裁剪规则，详见 references/analysis-framework.md §管道。

三、技术栈知识对照（差异化能力）

• 索引：references/tech-stacks/INDEX.md——栈 → 知识卡 → 本地深读锚点（wikihub，若存在）→ 官方文档 URL → 探测信号。
• 已建卡栈：arkts/HarmonyOS、electron、flutter、qt、react-native、taro、uni-app、generic-backend（Spring Boot/Django/FastAPI/Flask/Go/Node Express/NestJS/.NET）、agent-skills-plugin。
• 未覆盖栈：执行 references/tech-stacks/acquire-unknown-stack.md 获取协议（识别→官网抓取→建卡→登记索引），使知识库随使用自增长。

可扩展性

> 以下扩展点均为追加卡片/章节，不改七阶段管道与证据锚定铁律：

知识装配顺序（Prompt Layering）

> references/ 共 ≥3 文件，按约束 25 声明四层装配顺序；同名只加载一次，优先级从高到低：

覆盖优先级：wikihub 本地文档与栈卡冲突时，以栈卡结论 + wikihub 原文佐证为准并注明分歧；官网最新文档与栈卡冲突时，以官网为准并回写更新栈卡（进化动作）。

处理流程（七阶段剖析管道）

> 完整阶段定义、采样策略与档位裁剪见 references/analysis-framework.md §管道。本节为执行骨架。教训读写闭环（契约第 9 条）横贯全程：阶段 1 前预载教训，阶段 7 后追加沉淀：

1. 定位：确定代码库根路径、语言构成、构建体系；无法定位则向用户确认。
2. 识别：读 references/tech-stacks/INDEX.md 探测信号 → 命中栈卡即读取装配；未命中走获取协议。可选确定性预检：运行 python scripts/stack_detect.py <repo> 输出命中栈与缺信号清单（脚本不可用时退回读表判定，不影响流程）。自检句声明识别结果。
3. 拓扑（→ 报告部分一）：依赖清单/入口文件/启动流程 → 架构模式、模块划分、依赖方向、循环依赖与高耦合区。
4. 穿透（→ 报告部分二）：选 2~3 个核心业务场景逐层展开调用链（Controller→Service→DAO/持久层），记录每跳 file:line；路由/状态/异步/实体/配置/工具库各维度按「如有」判定。
5. 横切（→ 报告部分三）：命名/防御/异常/Lint 风格审计 + 设计模式落地标注 + 技术债清单。
6. 对照：用栈卡「分析要点」校准——该栈的惯例目录/路由/状态方案是否被项目遵循，偏离处标注。
7. 交付（→ 报告部分四 + 五）：生成 Mermaid 四图（逐图过安全清单）+ 上手指南 + 重构优先队列；按落盘规则交付五部分报告。

深度三档：快速导览（部分一+四精简版，≤1 轮通读）/ 标准剖析（五部分全量，核心链路 2 条）/ 深度穿透（五部分全量 + 全维度逐项 + 核心链路 ≥3 条 + 逐文件注解关键模块）。默认标准剖析。

交付产物机制

报告结构细则（每部分的必备小节与表格列）以 references/analysis-framework.md 为准。

质量标准

> 每条标准可独立验证，交付前逐行核对：

落盘规则

> 统一 ## 落盘规则 章节口径：

• 快照已由 tri-intent 落盘于 .tribro/snapshots/（本 skill 只读）。
• 经验教训文件落盘于 .tribro/code-analyzer/lessons.md（追加式，跨会话持久；启动读取、结束写入，缺失静默跳过——见契约第 9 条）。
• 剖析报告落盘于 .tribro/code-analyzer/<命名>-analysis.md（命名=快照命名或降级模式自构造名；可覆盖更新）。
• 对话内交付为默认形态；用户要求文件交付或报告超长时 MUST 落盘并告知路径。
• 技术栈知识增量的持久化：新栈卡写入本 skill references/tech-stacks/（安装态写不进时落 .tribro/code-analyzer/stack-cards/ 并提示用户回流）。
• 全程不生成 LICENSE / .gitignore。

完成判据

> 「何时算完成」外化为可机械校验的信号：

• 结束态（剖析完成）：① 五部分报告结构齐备（或快速导览档的一+四精简）；② 报告头部含技术栈识别结果 + 深度档位声明；③ Mermaid 四图存在；④ 功能清单表与重构优先队列表存在；⑤ 落盘时 .tribro/code-analyzer/<命名>-analysis.md 存在且非空；⑥ 本次经验教训已追加写入 .tribro/code-analyzer/lessons.md（或已提示写入失败）。六项全满足 → 输出交付声明并结束。
• 停车态（待用户输入）：目标路径无法定位、代码库不可读、或需要用户补充分支/环境说明时——输出「已暂停，等待 <具体输入>」并停止；这是停车不是结束，恢复后从断点阶段续跑。
• 中途降级态：某维度代码不可达（如闭源二进制依赖）时，该维度标注「不可分析+原因」，不阻断其余维度交付。

进化契约

• 教训文件读写闭环（核心机制 · 契约第 9 条）：
• 载体：.tribro/code-analyzer/lessons.md（追加式 Markdown，跨会话持久）。
• 启动读取：每次激活时读取该文件作为本次执行的规避清单；目录或文件不存在 → 静默跳过，NEVER 报错、NEVER 中断（首次执行天然为空）。
• 结束写入：每次执行结束后 MUST 追加一条记录，格式：
  ```
  ## YYYY-MM-DD HH:mm ｜ <一句话问题/经验标题>
  • 场景：<什么项目/什么阶段发生>
  • 问题：<踩了什么坑 / 得到什么有效经验>
  • 规避：<下次执行时的具体规避动作>
    ```
    空泛内容（如「本次顺利」）NEVER 写入——教训 MUST 可操作；无新增教训时写「无新增」占位行以留痕。
• 消费语义：与本次剖析相关的教训 MUST 在对应阶段生效（如路径处理、栈卡偏差、采样策略调整）。
• 反馈接收点：用户对报告结论纠错（证据锚错/图错误/维度遗漏）时，当场修正报告并追加教训条目。
• 经验沉淀位：教训条目落 lessons.md（本 skill 专属）；栈卡偏差回写 references/tech-stacks/<stack>.md「常见坑」；管道缺陷回写 references/analysis-framework.md；系统性教训经用户确认后由 tri-forge 门⑥沉淀入家族规范。
• 自我修订触发条件：同类纠错出现 ≥2 次、或外部覆盖层（官网文档）与栈卡分歧被证实 → 修订对应 references 文件，bump 版本并记 CHANGELOG（MINOR）。

版本检查与更新机制（强制技术约束 · 硬红线）

> 家族级强制技术约束，优先级与「强制执行契约」同级。任一执行入口启动后的第零步。

1. 运行 python scripts/check_update.py --slug tri-code-analyzer --json（24h 节流，--force 强制重查）。
2. 解析 state：A/B/C/D 一律放行并按 warnings/actions 标注口径；BLOCK 绝对禁止执行，按 block_code 输出恢复指引。
3. 退出码 <20 放行，>=20 阻断；脚本自身异常时兜底降级放行，NEVER 因版本门故障阻断 skill 启动。
4. 四态判定、升级流程、版本比较算法等完整细则的唯一真源：tri-forge/references/version-check-spec.md（本章节仅为瘦指针 STUB，NEVER 内联细则）。

目录结构

tri-code-analyzer/
├── SKILL.md                                  # 主入口：契约 + 三态检测 + 七阶段管道 + 五部分框架指针
├── README.md                                 # 特性/目录结构/安装/使用/测试/设计原则
├── CHANGELOG.md                              # 版本变更历史（Keep a Changelog + SemVer）
├── scripts/
│   └── check_update.py                       # 版本检查与强制自动更新脚本（四态判定，与 tri-forge 同源）
├── references/
│   ├── analysis-framework.md                 # 五部分交付框架 + 七阶段管道 + 采样策略 + Mermaid 安全清单
│   └── tech-stacks/
│       ├── INDEX.md                          # 技术栈索引：栈→卡→wikihub 锚点→官网→探测信号
│       ├── arkts.md                          # ArkTS / HarmonyOS 栈卡
│       ├── electron.md                       # Electron 栈卡
│       ├── flutter.md                        # Flutter / Dart 栈卡
│       ├── qt.md                             # Qt / C++ 栈卡
│       ├── react-native.md                   # React Native 栈卡
│       ├── taro.md                           # Taro 栈卡
│       ├── uni-app.md                        # uni-app / uni-app x 栈卡
│       ├── agent-skills-plugin.md            # Agent Skills 插件栈卡
│       ├── generic-backend.md                # 通用后端栈卡（Spring/Django/FastAPI/Flask/Go/Node/.NET）
│       └── acquire-unknown-stack.md          # 未覆盖栈获取协议（官网抓取→建卡→登记索引）
└── tests/
    └── tri-code-analyzer-full-testcases.md   # 全场景测试用例