spec-injection-guide.md

通过 keyword 颗粒度控制哪些 spec entry 注入到 agent 上下文中，支持关联额外文档、全局过滤、自定义 agent 映射。配置存储在 .workflow/config.json 的 specInjection 键中。

目录

• 概览
• 注入流程
• 配置 Schema
• CLI 配置
• TUI 配置
• Dashboard 配置
• 使用场景
• 参考

概览

Spec 注入系统在 session 启动和 agent 创建时，自动将项目规范注入到上下文中。

核心能力：

• keyword 级别过滤 — 仅注入/排除包含特定 keyword 的 spec entry
• 额外文档关联 — 为 category 或 agent 绑定额外的 markdown 文档
• 始终注入 — 指定无论哪种 agent 都注入的文档
• 全局过滤 — 跨所有 agent 的 keyword 白名单/黑名单

默认 Agent → Category 映射

仅含 markdown 标题的空 seed 文件会被自动跳过。只有包含实质内容或 <spec-entry> 的文件才参与注入。

注入流程

Session Start / Agent Spawn
        │
        ▼
loadSpecInjectionConfig()   ← .workflow/config.json
        │
        ▼
resolveCategories()         ← config.mapping 覆盖默认映射
        │
        ▼
resolveKeywordFilters()     ← 合并 agent 级 + 全局级过滤
        │
        ▼
┌─ for each category ────────────────────┐
│  loadSpecs(category, filters)          │
│  loadExtraDocs(categoryDocs[cat])      │
│  loadWikiByCategory(category)          │
└────────────────────────────────────────┘
        │
        ▼
loadExtraDocs(always)  →  maxContentLength 截断 → context budget → 注入

配置 Schema

配置存储在 .workflow/config.json → specInjection：

{
  "specInjection": {
    "mapping": {
      "<agent-type>": {
        "categories": ["coding", "test"],
        "includeKeywords": ["react", "typescript"],
        "excludeKeywords": ["legacy", "deprecated"],
        "extras": [".workflow/docs/api-guide.md"]
      }
    },
    "categoryDocs": {
      "<category>": {
        "specFiles": ["api-conventions.md"],
        "docs": ["knowhow/AST-patterns.md", ".workflow/docs/style.md"]
      }
    },
    "always": [".workflow/docs/project-overview.md"],
    "keywordFilters": {
      "include": ["react", "hooks"],
      "exclude": ["deprecated"]
    },
    "maxContentLength": 8000
  }
}

字段说明

Keyword 过滤优先级

1. Agent 级 includeKeywords 覆盖全局 keywordFilters.include
2. Agent 级和全局 excludeKeywords 合并（取并集）
3. 先 include 过滤，再 exclude 排除

文档路径解析

CLI 配置

通过 maestro spec injection 命令组管理配置：

查看配置

maestro spec injection show          # 格式化显示
maestro spec injection show --json   # 原始 JSON

配置 Agent 映射

# 设置 agent 的 categories 和 keyword 过滤
maestro spec injection agent code-developer \
  --categories coding,ui \
  --include react,typescript \
  --exclude legacy

# 删除 agent 映射（恢复默认）
maestro spec injection agent code-developer --remove

关联 Category 文档

maestro spec injection category coding \
  --spec-files api-conventions.md \
  --docs knowhow/AST-patterns.md,.workflow/docs/style.md

maestro spec injection category coding --remove

管理 Always 注入

maestro spec injection always --add .workflow/docs/overview.md
maestro spec injection always --remove .workflow/docs/overview.md
maestro spec injection always --clear

全局 Keyword 过滤

maestro spec injection filter --include react,hooks --exclude deprecated
maestro spec injection filter --clear

预览注入效果

maestro spec injection preview code-developer
maestro spec injection preview general --json

TUI 配置

通过 maestro config specs 进入 TUI 面板：

Config 模式

按 c 进入，5 个 section 按 1-5 切换：

所有修改即时保存到 .workflow/config.json。

Dashboard 配置

在 Dashboard 的 Settings → Specs 区域：

使用场景

前端项目只注入前端相关 spec

maestro spec injection agent code-developer \
  --categories coding,ui \
  --include react,css,component,hooks \
  --exclude backend,sql,migration

为 coding category 关联 API 规范文档

echo "## API 命名规范\n\n- REST 风格..." > .workflow/docs/api-guide.md
maestro spec injection category coding --docs .workflow/docs/api-guide.md

所有 agent 注入项目架构概览

maestro spec injection always --add .workflow/docs/project-overview.md

排除已废弃的 spec entry

maestro spec injection filter --exclude deprecated,legacy,removed

预览后微调

maestro spec injection preview code-developer
maestro config specs  # TUI 交互式调整

参考