skill-system-analyst

name	skill-system-analyst
description	系统/代码库架构分析与技术文档编排（mindmap 驱动，分章节 append/render），生成可视化（Mermaid）且注意 XSS 安全的深度报告。

Skill: System Analyst (Mindmap-Driven)

用“先制图（全局地图），再下潜（逐叶节点深挖）”的方式，生成细致、结构化、可视化的系统分析文档。你不是一次性写完，而是像写书一样：分解 → 计划 → 分章执行 → 校验 → 汇总。

适用场景

• 接手陌生代码库，需要快速但不粗糙地建立系统认知
• 架构评审/技术尽调：关注边界、权衡、风险、演进路径
• 需要产出可分享的分析报告（HTML + Mermaid + mindmap）

输出标准（深度门槛）

每个“章节”至少包含：

• 范围与职责：这个模块解决什么问题，不解决什么
• 关键证据：具体到文件路径、关键函数/类、关键配置项
• 数据/控制流：至少 1 张 Mermaid（组件图/时序图/数据流图择一）
• 关键权衡：为什么这样设计（trade-offs），替代方案是什么
• 风险分级：安全/可靠性/性能/可维护性风险（高/中/低），并给出修复建议

默认以中文输出（除非用户要求英文）。

核心规则

1. 必须编排：禁止“一口气写完整报告”；必须用 doc-generator.js 分章节追加。
2. 必须可追溯：关键结论要落到“文件 + 入口 + 证据”，禁止空泛描述。
3. 必须可视化：每个重要章节都要有 Mermaid，或明确引用全局 mindmap 的节点。
4. 必须安全：输出 HTML 中展示代码/用户输入时必须转义（例如 <script>）。

工具约定（在 Codex CLI 中）

优先用可复现的命令提取证据：ls、rg -n、sed -n、git log、git blame 等。

工作流（系统性执行）

Phase 0：需求澄清（先问清楚再开始）

在动手扫描前，先确认：

• 分析目标：架构总览 / 安全审计 / 性能瓶颈 / 可维护性 / 上线风险
• 受众：开发/架构/管理层（决定术语密度与建议形式）
• 产出范围：需要覆盖哪些模块/路径，是否要包含改进方案与优先级

Phase 1：Cartography（全局制图 + 计划）

1. 全局扫描：找入口（main/server/app）、路由、任务调度、配置、依赖、数据存储、外部集成点。
2. 构建 mindmap（Markdown 列表，≥3 层）：覆盖 Server / DB / Async / View / Security / Config / Observability。
3. 把 mindmap 转成执行计划：把每个重要叶节点映射为“章节列表”（章节名要可读、可检索）。
4. 初始化会话：在项目根目录生成 metadata.json，并用本 skill 的生成器初始化会话：
   • 生成器路径：本 skill 目录的 lib/doc-generator.js（即 SKILL.md 所在目录下的 lib/）。
   • 命令：

     node <skill_dir>/lib/doc-generator.js init metadata.json
     

   • metadata.json 必须包含 mindmap_markdown；建议包含 related_files（入口文件、关键配置、DB schema 等）。

Phase 2：Deep Dive Loop（逐章深挖，保持深度）

对“章节列表”逐个执行，直到覆盖关键叶节点：

1. 选定章节：一次只做一个章节，避免上下文发散。
2. 定向取证：只读这个章节相关的文件集（必要时扩展），并记录“入口/出口/调用链/数据结构”。
3. 产出章节 JSON：写 section.json，字段：
   • heading: 章节标题（与 mindmap 节点一致）
   • content: HTML 字符串（包含转义后的代码片段与 Mermaid）
4. 追加：

   node <skill_dir>/lib/doc-generator.js append <session_id> section.json
   

5. 更新进度：每追加一个章节，回写当前完成度（已覆盖哪些节点、还缺哪些风险点）。

Phase 3：Final Assembly（汇总 + 质量校验）

1. 渲染：

   node <skill_dir>/lib/doc-generator.js render <session_id>
   

2. 质量校验：确认 HTML 可打开、Mermaid 可渲染、代码与用户输入已转义、章节结构完整。
3. 交付摘要：给出 1 页级别的“系统概览 + 风险清单 + 建议路线图（按优先级）”。

章节内容模板（建议）

章节 content 至少按以下结构组织（HTML）：

• <h3>职责与边界</h3>
• <h3>关键组件与接口</h3>（含文件/函数证据）
• <h3>关键流程</h3>（Mermaid）
• <h3>权衡与替代方案</h3>
• <h3>风险与改进建议</h3>（分级 + 具体行动项）