用途
context-analyzer 是一个项目上下文分析引擎，用于扫描项目结构并为智能文档创建构建上下文模型。
它解决的问题是：AI 助手在创建文档时缺乏对项目上下文、已有产物和当前工作流状态的感知，导致引用缺失和内容重复。其解决方案是分析项目目录、解析产物元数据与可追溯性章节，构建上下文模型，为新文档创建提供相关信息。
适用场景
在以下情况使用 context-analyzer：
- 在已有项目中开始文档工作
- 创建需要上游引用的新产物
- 需要了解已存在哪些文档
- 想要识别文档覆盖缺口
- 为 doc-* 技能调用准备上下文
在以下情况不要使用：
- 项目没有任何已有文档
- 处理单个、孤立的文档
- 需要完整项目审计（应改用 trace-check）
输入
| 输入 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_root | string | 是 | 要分析的项目根路径 |
| target_artifact_type | string | 否 | 正在创建的产物类型（如 "PRD"、"SPEC"） |
| depth | string | 否 | 分析深度："quick"（仅结构）、"standard"（默认）、"deep"（完整内容） |
工作流程
第 1 步：扫描项目结构
按类型和位置枚举所有文档产物。目录模式示例：
{project_root}/
├── docs/
│ ├── BRD/
│ ├── PRD/
│ ├── EARS/
│ ├── BDD/
│ ├── ADR/
│ ├── SYS/
│ ├── REQ/
│ ├── IMPL/
│ ├── CTR/
│ ├── SPEC/
│ └── TASKS/
└── ai_dev_flow/ (framework templates)
产物发现示例命令：
find {project_root}/docs -name "*.md" -o -name "*.yaml" -o -name "*.feature"
输出结构包含 artifact_inventory，按类型统计数量并列出文件 ID、路径、标题和状态。
第 2 步：解析产物元数据
从发现的产物中提取元数据和关键信息，包括 YAML Frontmatter 和 Document Control 表格。解析后的元数据模型包含标题、层级、状态、版本、最后更新时间和标签。
第 3 步：提取可追溯性信息
解析每个产物的第 7 节 Traceability，提取上游来源和下游产物，构建 traceability_graph，记录各产物之间的上下游关系。
第 4 步：确定工作流位置
计算当前在 SDD 工作流中的位置。层级映射如下：
| 层级 | 产物类型 | 必需上游 |
|---|---|---|
| 1 | BRD | 无 |
| 2 | PRD | BRD |
| 3 | EARS | PRD |
| 4 | BDD | EARS |
| 5 | ADR | BDD |
| 6 | SYS | ADR |
| 7 | REQ | SYS |
| 8 | IMPL | REQ（可选） |
| 9 | CTR | IMPL 或 REQ（可选） |
| 10 | SPEC | REQ，可选 IMPL/CTR |
| 11 | TASKS | SPEC |
位置分析输出已完成层级、当前层级、下一步所需产物以及缺口。
第 5 步：识别上游候选
针对目标产物类型，识别相关的上游文档。相关性评分因素包括：直接上游（50%）、主题匹配（30%）、时效性（10%）、状态（10%）。输出上游候选列表，包含 ID、相关性百分比、标题和原因。
第 6 步：提取关键术语
从已有文档构建项目词汇表，方法包括文档标题和标题头、术语表章节、高频技术术语、领域特定词汇。输出分为领域术语和技术术语，并记录频率和出现文档。
第 7 步：构建上下文模型
组装完整的上下文模型供会话使用，包含项目根路径、扫描时间戳、扫描深度、产物清单、工作流位置、上游候选、关键术语和覆盖缺口。
使用示例
示例 1：SPEC 创建前的上下文
用户请求："我即将创建 SPEC 文档，我有哪些上下文？"
输出包含目标、就绪状态、可用上游文档、推荐引用和警告。
示例 2：缺口分析
用户请求："这个项目缺少哪些文档？"
输出按严重程度分类的文档缺口，包括关键、中等和低级别，并说明原因和影响。
示例 3：快速结构检查
用户请求："这个项目里有哪些文档？"
快速扫描输出项目结构、各类型产物数量和总数、工作流覆盖率。
与其他技能的集成
| 集成 | 说明 |
|---|---|
| skill-recommender | 提供项目上下文以获得更好的推荐 |
| doc-* skills | 提供上游候选和关键术语 |
| quality-advisor | 共享产物清单用于验证 |
| workflow-optimizer | 提供工作流位置数据 |
| trace-check | 与可追溯性提取重叠（使用 trace-check 进行深度验证） |
质量门
完成定义：
- 项目结构扫描成功
- 发现所有产物类型
- 从发现的产物中提取元数据
- 构建可追溯性图
- 计算工作流位置
- 为目标类型识别上游候选
- 组装并返回上下文模型
性能目标：
| 指标 | 目标 |
|---|---|
| 快速扫描延迟 | <500ms |
| 标准扫描延迟 | 100 个产物 <2s |
| 深度扫描延迟 | 100 个产物 <5s |
| 内存使用 | 100 个产物 <200MB |
版本信息
版本：1.0.0 创建时间：2025-11-29 状态：Active 作者：AI Dev Flow Framework Team