| name | deep-functional-analysis |
| description | 深度功能分析，以问题驱动的方式深入挖掘某个功能/机制的实现原理，生成单篇深度解析文档。参考 skill-creation-mechanism.md 的分析风格：从核心问题出发，层层深入，多维度对比，最后给出总结。适用于"深入分析 X 的原理"、"深度解析 Y 机制的实现"、"理解 Z 功能的设计决策"等场景。 |
深度功能分析
概述
以问题驱动的方式深入挖掘代码库中某个功能、机制或原理，生成一篇自包含、可顺序阅读的深度解析文档。
核心方法： 开篇提出 1-2 个核心问题，全文围绕问题展开。从表面现象 → 实现细节 → 设计原理 → 权衡取舍，层层深入。不追求完整覆盖，而是把一个点讲透。
与 system-architecture-analysis 的区别：
- 本技能：问题驱动 + 逐步深入 + 多维对比，聚焦单一功能/机制
- system-architecture-analysis：C4 模型 + 架构分层，聚焦系统结构
何时使用
- 用户要求深入分析某个功能/机制/原理
- 用户说"深入解析 X 的原理"、"理解 Y 机制的设计决策"、"分析 Z 功能的权衡"
- 用户需要理解某个机制的核心问题和解决方案
- 即使用户只说"看看这个机制"，也应使用此技能生成问题驱动的深度文档
不适用： 整个系统的架构结构 → 使用 system-architecture-analysis；多系统的对比研究 → 本技能聚焦单一主题
核心原则
问题驱动原则
- 核心问题必须显式提出：文档开篇必须明确 1-2 个核心问题
- 全文围绕问题展开：每个章节都应回答或深化某个问题
- 问题必须有答案：总结章节必须明确回答所有提出的核心问题
逐步深入原则
- 从现象到原理：不能只停留在表面，必须深入到设计原理
- 量化权衡：设计取舍必须有具体数字或明确说明（如"节省 30-50% 的 token"）
- 边界条件：关键结论必须说明"何时不成立"或"残留风险"
多维对比原则
- 至少 1 张对比表格：方案对比、系统对比、场景对比
- 对比必须有维度：明确对比维度（性能、复杂度、可维护性等）
- 对比必须有结论：不是并列展示，而是给出倾向性分析
图示原则
- 至少 4 张图：状态机、时序图、分层图、流程图
- 图后必须有解释：不是读图指引，而是解释图表达的内容
- 图与问题相关：每张图都应帮助回答某个核心问题
工作流程
Step 1：定位与问题定义
1.1 确认参数（分析目标、核心问题、输出路径、语言）
1.2 定位核心文件（Glob 搜索文件名、Grep 搜索关键词/类名/函数名）
1.3 定义核心问题（1-2 个贯穿全文的问题，如"是否规范？""如何权衡？"）
产出： 核心文件清单 + 核心问题定义
Step 2：深度挖掘
2.1 追踪完整流程（入口 → 处理 → 输出，每步关键决策点）
2.2 识别关键机制（如安全检查、缓存、同步、错误处理等）
2.3 收集设计权衡（每个决策点的当前方案 vs 替代方案）
2.4 识别质量保障点（多层检查、回滚机制、边界条件等）
产出： 流程清单 + 关键机制列表 + 设计权衡表
Step 3：多维对比
3.1 与相似机制对比（同一项目中不同实现）
3.2 与外部系统对比（其他项目/框架的类似功能）
3.3 与理想方案对比（完美方案 vs 实际实现 + 缺失说明）
产出： 多个对比表格
Step 4：生成文档
4.1 撰写核心问题章节（表格形式：问题 → 答案 → 证据）
4.2 撰写生命周期/流程章节（状态机 + 时序图 + 分步解释）
4.3 撰写关键技术章节（每个技术点的原理 + 代码证据）
4.4 撰写质量保障章节（分层图 + 每层说明）
4.5 撰写对比章节（多个对比表格 + 分析）
4.6 撰写总结章节（核心洞察 + 边界条件）
产出： 完整文档
输出结构
推荐章节结构（参考 skill-creation-mechanism.md）：
一、概述 — 功能定位、核心文件关系
二、核心问题 — 1-2 个核心问题 + 直接回答表格
三、完整生命周期 — 状态机/流程图
四、实现流程详解 — 分步骤深入讲解，配合时序图
五、关键技术机制 — 核心技术点（如安全扫描、缓存策略等）
六、质量保障体系 — 多层保障的可视化总结图
七、对比分析 — 与其他系统的对比表格
八、相关文件索引 — 所有涉及的源码文件
九、总结 — 核心洞察 + 关键要点
章节增减规则： 根据分析目标灵活调整，不追求固定章节顺序，以问题为主线串联。
常见借口
| 借口 | 事实 |
|---|
| "这个机制很简单，不用深入" | 简单机制也有设计权衡；要求至少 3 个关键技术机制 |
| "没有可对比的机制" | 必须至少 1 张对比表格；可与理想方案对比 |
| "量化权衡很难" | 至少给出具体说明；禁止"大概"、"应该"等模糊表述 |
| "没有边条件" | 任何结论都有边界；必须说明"何时不成立" |
| "代码就是证据" | 代码路径不能替代解释；必须先解释原理再引用代码 |
危险信号
- 文档开篇没有明确提出核心问题
- 核心问题章节只有罗列，没有"问题 → 答案 → 证据"表格
- 停留在表面现象，没有深入设计原理
- 没有对比表格，或对比表格没有结论
- 没有量化权衡，只有"更好"、"更快"等模糊描述
- 关键结论没有边界条件说明
- 只有代码路径列表，没有连续叙述
- 图后是"这张图展示了..."的读图指引，没有内容解释
示例
差： 先按章节复述流程，最后说"整体没什么特别"。
好： 开篇直接提出核心问题："Agent 自建 Skills 是否规范？"，然后以表格形式逐项回答。
差： "安全扫描检查危险模式，如数据泄露等。相关代码在 tools/skills_guard.py。"
好： "scan_skill() 函数扫描 100+ 威胁模式，覆盖数据泄露、提示注入等 11 个类别。发现危险内容时自动回滚，回滚通过 shutil.rmtree() 删除整个 skill 目录。量化：扫描耗时约 50-200ms（取决于 skill 大小）。"
差： "采用威胁模式而不是静态分析。"
好： "当前方案：威胁模式正则扫描。替代方案：AST 静态分析。为何不选：静态分析难以处理模板展开和动态生成代码；威胁模式简单直接，覆盖常见攻击模式足够。代价量化：静态分析需要额外依赖，启动时间增加 ~1s。"
验收标准
交付前须将下列待勾选框逐项勾为已满足；全部勾选后，方可将本轮分析标为"完成"。
P0 — 问题驱动
P0 — 深度
P1 — 对比
P2 — 格式
反模式检查
以上验证项已全部满足，本轮交付物符合本技能质量契约。
参考模板
输出文档的模板位于 reference/article-template.md，包含完整的 9 章结构：
一、概述 — 功能定位、核心文件关系
二、核心问题 — 1-2 个核心问题 + 直接回答表格
三、完整生命周期 — 状态机/流程图
四、实现流程详解 — 分步骤深入讲解，配合时序图
五、关键技术机制 — 核心技术点（如安全扫描、缓存策略等）
六、质量保障体系 — 多层保障的可视化总结图
七、对比分析 — 与其他系统的对比表格
八、相关文件索引 — 所有涉及的源码文件
九、总结 — 核心洞察 + 关键要点
使用方法：直接复制模板，将 {占位符} 替换为实际内容，删除不适用章节并标注。
