核心定位
project-doc-analyst 是一款专为深度代码仓库分析设计的专家级 Agent，目标是将任意项目转化为结构化的"工程语义资产"——既可被人类工程师快速理解，也能作为 AI 系统的上下文输入。
核心用法
用户通过触发词（如"分析项目"、"生成文档"、"架构分析"）激活技能后，Agent 执行四阶段流程：
1. 项目识别与计划：确认输入路径、识别项目类型、制定分析计划并等待用户确认
2. 深度阅读：按 P0/P1/P2 优先级策略扫描源码，优先关注入口文件、类型定义、核心业务逻辑
3. 逐份生成文档：严格按优先级输出结构化文档，每份完成后暂停等待确认
4. 反馈迭代：根据用户反馈精准修改或补充
文档套件包含必选项（项目总览、技术架构）与可选项（设计哲学、产品分析、代码示例、接口语义、部署运维等），并支持复杂专题深挖（认证、缓存、异步、状态机等）。
显著优点
- 双重受众设计：同时优化人类可读性与 AI 可解析性，明确边界、依赖、数据流、控制流
- 证据优先原则：区分"已确认事实/合理推断/证据不足"，拒绝编造和模板填充
- 智能文件过滤：自动跳过样式/图片/日志等低信号文件，聚焦架构关键路径
- 自包含文档：无需访问源码即可理解系统，用"模块+职责"替代文件路径引用
- 阶段式交付：大项目支持中间汇报，避免 token 耗尽导致失败
潜在局限
- 大项目成本：>200 文件时必须执行采样策略，可能遗漏边缘模块
- 语言依赖：默认中文输出，多语言混合仓库可能判断偏差
- 非实时分析：不支持 live debugging 或动态代码生成
- 用户介入点较多：每份文档后需确认，追求速度时需显式启用"快速模式"
适合人群
- 技术负责人接手新项目、准备架构评审
- 外包团队需要快速理解客户代码库
- 开源项目维护者生成 onboarding 文档
- AI 系统需要高质量项目上下文输入
常规风险
- 仓库较大时可能因 token 限制中断，需分会话续作
- 证据不足时部分文档会被跳过，需用户补充说明
- 对隐蔽实现或复杂动态机制（如插件系统）推断深度有限