核心用法
project-doc-analyst 是一个专家级项目分析与文档生成 Agent，专为深度理解代码仓库并生成高质量技术文档而设计。使用时需指定目标项目路径，Agent 将按优先级策略（P0/P1/P2）逐层读取源码、配置和基础设施文件，最终输出一套"工程语义资产"文档套件。
执行流程
1. 阶段一：项目识别与分析计划 — 确认项目路径、识别项目类型、决定输出语言，生成分析计划并等待用户确认
2. 阶段二：深度阅读 — 按优先级批量读取文件，建立项目整体理解，包括架构、数据流、控制流、配置体系等
3. 阶段三：逐份生成文档 — 严格按优先级顺序生成文档，每份完成后等待用户确认
4. 阶段四：用户反馈与补充 — 根据反馈精准修改或追加文档
输出文档结构
- P0 必生成：项目总览、技术架构文档（含系统架构图、数据流图、请求链路图）
- P1 重要：设计原因与工程思想、产品与交互分析、优秀代码示例、接口语义文档
- 可选文档：部署运维指南、配置参考
- Deep Dives：认证权限模型、缓存一致性、异步队列、状态机等复杂专题
显著优点
1. 双重读者设计：文档同时面向人类（老板、架构师、工程师、外包团队）和 AI（Coding Agent、AI IDE、AI Reviewer），人类用于汇报与讨论，AI 用于低歧义、高语义密度的上下文理解
2. 证据优先原则：所有结论基于仓库真实证据，明确区分"已确认事实/合理推断/证据不足"，拒绝编造和模板填充
3. 深度架构分析：不止于文件摘要，深入解释系统如何组织运行、数据/控制流、设计原因、工程思想、技术取舍与难点
4. 结构化阅读策略：P0/P1/P2 三级优先级 + 大项目采样策略，确保在上下文限制下优先理解核心链路与业务逻辑
5. 文档独立性：输出自成体系，读者无需访问源码即可理解项目，使用 【接口：功能描述】 格式替代具体路径引用
6. 阶段确认机制：每份文档生成后暂停等待用户确认，避免一次性输出过长导致返工
潜在缺点与局限性
1. 上下文消耗大：深度阅读大型仓库时 Token 消耗较高，需采用采样策略控制成本
2. 生成速度受限：完整分析需多轮交互确认，不适合"5分钟速成"场景
3. 非实时调试工具：明确 NOT for 单文件代码编写、代码片段一般问答、实时调试
4. 证据依赖性强：仓库注释不足、类型缺失或架构混乱时，分析深度会显著下降
5. 语言判断依赖启发式：虽有多层语言判断策略，极端情况下仍可能误选输出语言
适合人群
- 技术负责人/架构师：需要快速理解新接手的遗留系统，输出架构评审材料
- 工程团队 Leader：为团队生成 onboarding 文档，统一技术认知
- 外包/协作团队：在不暴露完整源码的情况下，获得自包含的项目理解文档
- AI 辅助开发用户：为 Coding Agent 或 AI IDE 生成高质量项目上下文，提升 AI 代码生成与重构质量
- 产品经理：从代码中推断产品行为与交互逻辑，理解技术实现约束
常规风险
- 输出不完整风险：用户若跳过阶段确认或强制快速模式，可能遗漏重要模块分析
- 图示准确性风险：Mermaid 架构图依赖代码推断，复杂项目可能出现
[待确认]虚线关系 - 技术债务误判：工程取舍分析依赖作者经验，可能将合理设计误判为债务
- 安全信息泄露：若输入包含敏感配置（
.env、密钥文件），需在输入阶段主动过滤，Agent 本身不内置敏感信息检测