mcpField
C
context-analyzer

context-analyzer

github.com/vladm3105文档处理1750 次安装1 天前更新
代码仓库

关于 context-analyzer

context-analyzer 是一种文档技能，扫描项目目录并构建上下文模型，帮助 AI 助手了解已有文档和工作流状态。它提取元数据、追溯关系与术语，并为目标文档整理上游候选和文档缺口。

主要功能

  1. 01扫描并分类项目文档
  2. 02提取元数据与追溯关系
  3. 03计算 SDD 工作流位置
  4. 04识别上游文档候选
  5. 05汇总术语与文档缺口

适用场景

  1. 01开始文档工作前盘点现有资料
  2. 02创建文档时查找上游引用
  3. 03检查项目文档覆盖缺口
  4. 04为其他文档技能准备上下文

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill context-analyzer

安装后在 Claude Code 中输入/context-analyzer确认已加载。

详细介绍

context-analyzer

用途

扫描项目结构，并构建用于智能创建文档的上下文模型。

解决的问题：AI 助手在创建文档时不了解项目上下文、现有成果和当前工作流状态，导致缺少引用和内容重复。

解决方案：分析项目目录，解析成果元数据和可追溯性章节，并构建上下文模型，为新文档的创建提供相关信息。

何时使用此技能

在以下情况下使用 context-analyzer：

  • 在现有项目中开始文档工作
  • 创建需要上游引用的新成果
  • 需要了解已有的文档
  • 想要找出文档覆盖范围中的缺口
  • 准备为调用 doc-* 技能提供上下文

以下情况不要使用：

  • 项目没有现有文档
  • 仅处理单个、独立的文档
  • 需要完整的项目审计（改用 trace-check）

技能输入

输入类型必填描述
project_rootstring是要分析的项目根路径
target_artifact_typestring否正在创建的成果类型（例如，“PRD”、“SPEC”）
depthstring否分析深度：“quick”（仅结构）、“standard”（默认）、“deep”（完整内容）

技能工作流

步骤 1：扫描项目结构

按类型和位置列出所有文档成果：

目录模式：

{project_root}/
├── docs/
│   ├── BRD/
│   ├── PRD/
│   ├── EARS/
│   ├── BDD/
│   ├── ADR/
│   ├── SYS/
│   ├── REQ/
│   ├── IMPL/
│   ├── CTR/
│   ├── SPEC/
│   └── TASKS/
└── ai_dev_flow/  (framework templates)

成果发现：

# Example discovery pattern
find {project_root}/docs -name "*.md" -o -name "*.yaml" -o -name "*.feature"

输出结构：

artifact_inventory:
  BRD:
    count: 3
    files:
      - id: BRD-01
        path: docs/BRD/BRD-01_platform_foundation.md
        title: Platform Foundation
        status: Approved
      - id: BRD-02
        path: docs/BRD/BRD-02_partner_integration.md
        title: Partner Integration
        status: Draft
  PRD:
    count: 2
    files:
      - id: PRD-01
        path: docs/PRD/PRD-01_core_features.md
        title: Core Features
        status: In Review
  SPEC:
    count: 0
    files: []
步骤 2：解析成果元数据

从发现的成果中提取元数据和关键信息：

YAML Frontmatter 提取：

# From document header
---
title: "BRD-01: Platform Foundation"
tags:
  - platform-brd
  - shared-architecture
custom_fields:
  layer: 1
  artifact_type: BRD
  status: Approved
---

文档控制信息提取：

## Document Control

| Item | Details |
|------|---------|
| **Status** | Approved |
| **Version** | 2.1.0 |
| **Last Updated** | 2025-11-15 |

解析后的元数据模型：

artifact_metadata:
  BRD-01:
    title: Platform Foundation
    layer: 1
    status: Approved
    version: 2.1.0
    last_updated: 2025-11-15
    tags: [platform-brd, shared-architecture]
步骤 3：提取可追溯性信息

解析每个成果中的第 7 节“可追溯性”：

上游来源提取：

### Upstream Sources
| Source | Type | Reference |
|--------|------|-----------|
| [BRD-01](../BRD/BRD-01_platform.md#BRD-01) | Business Requirements | Platform foundation |

下游成果提取：

### Downstream Artifacts
| Artifact | Type | Reference |
|----------|------|-----------|
| [SPEC-01](../SPEC/SPEC-01_api.yaml) | Technical Specification | API implementation |

可追溯性图谱：

traceability_graph:
  BRD-01:
    upstream: []
    downstream: [PRD-01, PRD-00]
  PRD-01:
    upstream: [BRD-01]
    downstream: [EARS-01, SPEC-01]
  SPEC-01:
    upstream: [PRD-01, REQ-01]
    downstream: [TASKS-01]
步骤 4：确定工作流位置

计算当前在 SDD 工作流中的位置：

层级映射：

层级成果类型必需的上游成果
1BRD无
2PRDBRD
3EARSPRD
4BDDEARS
5ADRBDD
6SYSADR
7REQSYS
8IMPLREQ（可选）
9CTRIMPL 或 REQ（可选）
10SPECREQ，可选 IMPL/CTR
11TASKSSPEC

位置分析：

workflow_position:
  completed_layers: [1, 2, 3]
  current_layer: 4
  next_required: [BDD, ADR]
  gaps:
    - layer: 3
      type: EARS
      status: incomplete
      reason: "Only 2 of 5 PRD features have EARS coverage"
步骤 5：识别上游候选文档

针对目标成果类型，识别相关的上游文档：

相关性评分：

因素权重描述
直接上游50%工作流中的直接前置成果
主题匹配30%关键词和领域的一致性
时效性10%最近更新的文档
状态10%优先选择已批准的文档

上游候选文档输出：

upstream_candidates:
  target_type: SPEC
  candidates:
    - id: REQ-01
      relevance: 95%
      title: API Requirements
      reason: "Direct upstream, topic match: API, approved status"
    - id: REQ-02
      relevance: 80%
      title: Data Model Requirements
      reason: "Direct upstream, related topic: data"
    - id: ADR-005
      relevance: 70%
      title: API Architecture Decision
      reason: "Architecture context for API design"
步骤 6：提取关键术语

根据现有文档构建项目词汇表：

术语提取方法：

  • 文档标题和标题栏
  • 术语表章节
  • 高频使用的技术术语
  • 特定领域词汇

关键术语输出：

key_terms:
  domain_terms:
    - term: workflow
      frequency: 45
      documents: [BRD-01, PRD-01, REQ-01]
    - term: resource
      frequency: 32
      documents: [BRD-01, REQ-02, SPEC-01]
  technical_terms:
    - term: WebSocket
      frequency: 18
      documents: [ADR-003, SPEC-01]
    - term: PostgreSQL
      frequency: 12
      documents: [BRD-01, ADR-000]
步骤 7：构建上下文模型

组装完整的上下文模型，供会话使用：

完整上下文模型：

context_model:
  project_root: /path/to/project
  scan_timestamp: 2025-11-29T14:30:00Z
  scan_depth: standard

  artifact_inventory:
    total_count: 25
    by_type:
      BRD: 3
      PRD: 5
      EARS: 4
      BDD: 6
      ADR: 3
      REQ: 4
      SPEC: 0
      TASKS: 0

  workflow_position:
    completed_layers: [1, 2, 3, 4, 5, 7]
    current_layer: 7
    ready_for: [SPEC, TASKS]
    gaps:
      - type: SYS
        status: missing
        impact: "SPEC creation may lack system context"

  upstream_candidates:
    target_type: SPEC
    primary:
      - id: REQ-01
        title: Core API Requirements
        relevance: 95%
    secondary:
      - id: ADR-003
        title: WebSocket Architecture
        relevance: 75%

  key_terms:
    domain: [workflow, resource, validation, processing]
    technical: [WebSocket, PostgreSQL, Redis, REST API]

  coverage_gaps:
    - area: Testing
      description: "BDD scenarios cover only 60% of EARS requirements"
    - area: Implementation
      description: "No SPEC or TASKS documents created yet"

使用示例

示例 1：SPEC 前的上下文

用户请求：“我准备创建一份 SPEC 文档，可以使用哪些上下文？”

上下文分析：

context_summary:
  target: SPEC creation
  readiness: ready
  upstream_available:
    - REQ-01: Core API Requirements (Approved)
    - REQ-02: Data Model Requirements (Approved)
    - ADR-003: WebSocket Architecture (Approved)
  recommended_references:
    - "Reference REQ-01 for API endpoint specifications"
    - "Include ADR-003 for WebSocket implementation decisions"
  warnings:
    - "No CTR (contract) documents exist - consider if API contracts needed"
示例 2：缺口分析

用户请求：“这个项目缺少哪些文档？”

缺口分析输出：

documentation_gaps:
  critical:
    - type: SYS
      reason: "No system requirements linking ADR to REQ"
      impact: "REQ documents may lack architectural context"
    - type: SPEC
      reason: "No technical specifications for implementation"
      impact: "Cannot proceed to code generation"
  moderate:
    - type: BDD
      coverage: 60%
      reason: "4 of 10 EARS requirements have BDD scenarios"
  low:
    - type: IMPL
      reason: "Implementation plan optional but recommended for complex projects"
示例 3：快速检查结构

用户请求：“这个项目中有哪些文档？”

快速扫描输出（depth: quick）：

project_structure:
  docs_directory: /project/docs
  artifact_counts:
    BRD: 3
    PRD: 5
    EARS: 4
    BDD: 6
    ADR: 3
    SYS: 0
    REQ: 4
    IMPL: 0
    CTR: 0
    SPEC: 0
    TASKS: 0
  total_artifacts: 25
  workflow_coverage: 50% (6 of 12 layers)

与其他技能的集成

集成描述
skill-recommender提供项目上下文，以便给出更好的建议
doc-* skills提供上游候选项和关键术语
quality-advisor共享制品清单以供验证
workflow-optimizer提供工作流位置信息
trace-check与可追溯性提取功能重叠（使用 trace-check 进行深度验证）

质量门禁

完成定义
  • 成功扫描项目结构
  • 发现所有制品类型
  • 从已发现的制品中提取元数据
  • 构建可追溯性图
  • 计算工作流位置
  • 为目标类型确定上游候选项
  • 组装并返回上下文模型
性能目标
指标目标
快速扫描延迟<500ms
标准扫描延迟扫描 100 个制品时 <2s
深度扫描延迟扫描 100 个制品时 <5s
内存用量扫描 100 个制品时 <200MB

可追溯性

必需标签：

@prd: PRD.000.002
@adr: ADR-000
上游来源
来源类型参考
PRD-00产品需求PRD-00
ADR-000架构决策ADR-000
下游制品
制品类型参考
skill-recommender技能使用方使用上下文以便给出更好的建议
doc-* skills技能使用方使用上下文创建制品

版本信息

版本：1.0.0 创建时间：2025-11-29 状态：活跃 作者：AI Dev Flow Framework Team

评论

支持 Markdown