核心能力
project-doc-analyst 是一款专家级项目分析与文档生成 Agent，定位为软件架构师、资深工程师与技术文档作者的多角色融合体。其核心使命是通过深度阅读整个代码仓库，输出一套高质量的"工程语义资产"文档套件，同时服务于人类决策者（老板、架构师、技术负责人、外包团队）与 AI 系统（Coding Agent、AI IDE、AI Reviewer 等）。
关键用法与工作流程
该 Agent 采用四阶段执行流程：
1. 项目识别与分析计划：确认输入路径、识别项目类型、制定文档生成计划并等待用户确认
2. 深度阅读：按 P0/P1/P2 优先级策略读取文件，优先核心链路（入口→中间件→服务→数据），大项目采用"扫结构→批量读 P0→识别核心模块→深入链路→尽早写作"策略
3. 逐份生成文档：严格按优先级顺序生成，每份完成后暂停等待用户确认
4. 反馈与补充：根据用户反馈精准修改或追加文档
文档输出体系包含：
- P0 必出：项目总览、技术架构文档（含系统架构图、数据流图、请求链路图）
- P1 重要：设计原因与工程思想、产品与交互分析、优秀代码示例、接口语义文档
- 可选：部署运维指南、配置参考
- 复杂专题深挖：认证权限、缓存一致性、异步队列、状态机、插件架构等
显著优点
- 证据优先原则：所有结论基于源码真实证据，明确区分"已确认事实/合理推断/证据不足"，禁止编造
- 双重受众设计：文档自成体系，人类可读可汇报，AI 可精确理解模块边界、数据流、控制流与业务规则
- 深度架构洞察：不止于"是什么"，强制解释"为什么"——设计哲学、技术取舍、工程思想、隐性复杂度
- 智能文件过滤：自动跳过样式/图片/日志等低信号文件，优先读取入口、类型定义、核心模块等高信号文件
- 大项目适配：文件>200 时启用采样策略，避免上下文耗尽，确保核心架构理解
局限性与风险
- 依赖仓库可访问性：必须提供本地路径，不支持直接分析远程 URL（需先 clone）
- Token 消耗较高：深度阅读+多文档生成对长上下文模型要求较高，大项目需分会话继续
- 非实时分析：非为单文件编写、代码片段问答或实时调试设计
- 语言推断可能偏差：虽有多层语言策略，但复杂多语言仓库可能出现输出语言与用户预期不符
- 图示生成限制：架构图依赖 Mermaid/ASCII art，复杂拓扑可能可读性受限
适合人群
- 技术负责人/架构师：需要快速理解陌生项目或向团队/客户汇报系统架构
- 新成员入职：替代传统 onboarding，通过结构化文档加速上手
- 外包/交付团队：生成客户可读的系统说明与技术方案文档
- AI 辅助开发场景：为 Coding Agent、AI IDE 提供高质量上下文，降低源码检索成本
- 代码审查/重构：识别技术债务、设计模式与改进机会
安全与可信度
该 Skill 来自 GitHub 开源社区（z-Zihan/awesome-skills），经过详细文档规范与使用说明，属于成熟的工程实践模板。输出内容基于用户提供的私有仓库，不向外传输代码，分析过程本地完成。