审阅报告后，且源文件与 repo_id 未变化：

Maestro 知识沉淀分两种：约束和积累。约束是编码规范、架构决策、质量规则——规定"不能做什么"。积累是操作步骤、设计资产、调试经验——记录"怎么做过"。前者需要强制加载，后者需要按需检索。

系统权威设计见 Maestro 知识系统架构。本文聚焦日常操作；身份模型、Run ledger、reconciliation freshness、检索多样性和安全剪枝以架构文档为准。

.workflow/
├── specs/                          # 约束层：基于 category 的规则索引
│   ├── coding-conventions.md       # category: coding
│   ├── architecture-constraints.md # category: arch
│   ├── review-standards.md         # category: review
│   ├── debug-notes.md              # category: debug
│   ├── test-conventions.md         # category: test
│   └── learnings.md                # category: learning（经验教训）
├── knowhow/                        # 积累层：完整知识文档
│   ├── KNW-*.md                    # 会话压缩记录
│   ├── RCP-*.md                    # 操作配方（步骤指南，可标记 tool: true）
│   ├── TPL-*.md                    # 代码/配置模板
│   ├── REF-*.md                    # 外部文档摘要
│   ├── DCS-*.md                    # 架构决策记录
│   ├── TIP-*.md                    # 快速提示
│   ├── AST-*.md                    # 代码资产（API 契约、数据模型）
│   ├── BLP-*.md                    # 架构蓝图
│   └── DOC-*.md                    # 长文档（通用兜底）
├── domain/                         # 领域知识：项目术语表
│   └── glossary.yaml               # 领域术语（YAML 格式，主格式；另有 glossary.json 向后兼容）
├── wiki-index.json                 # 统一索引（WikiIndexer 自动生成）
└── codebase/
    └── knowledge-graph.json        # 代码知识图谱（kg CLI 查询）

Spec 与 Knowhow 的关系

Spec 是索引和规则，Knowhow 是详情和过程。 二者通过 ref 属性桥接。

最小 canonical creation surface

普通 Knowhow 只有三个必填知识参数：type/title/content；普通 Spec 只有三个：category/title/content。

maestro knowhow add --type tip --title "有界重试" --content "瞬态失败最多重试三次。"
maestro spec add coding "有界重试规则" "瞬态失败最多重试三次。"

九种 Knowhow 类型保持兼容：session|tip|template|recipe|reference|decision|asset|blueprint|document。keywords/sourceRef/relatedPaths/appliesToRepoIds/language/decisionState/explicitId/tool 都是高级可选字段。

CLI --repo 接受 repository selector 并选择物理写入目标；repeatable --applies-to-repo 只记录适用范围，不会改变目标。host/MCP targetRepoId 不是 CLI flag：当前仓库写入省略它，Agent 只有在用户/工作流显式选择 linked physical target，且 host 提供该目标的 exact stable UUID 与匹配 corpus 的 live write capability 时才传。禁止从 cwd、repo name、alias 或 path 推导 ID，也禁止持久化 alias/path 作为 identity；缺权限或 cached/live ID mismatch 时 fail closed。

Session/Run 知识审查闭环

Run 不再把结论直接写入 Spec/Knowhow，而是经过可审查的两阶段流程：

[auto] search/load → 自动记录 consumed
[auto] check → 自动 reconcile
[auto] complete → 自动暂存 decisions/constraints
[manual] review → 审查 + 裁决
[manual] promote → 显式提升
[manual] seal → 收口

# 暂存候选（可选，decisions/constraints 在 complete 时自动暂存）
# 长正文可改用 --content-file <path|->
# --signal/--signal-ids 可同时记录 validated/contradicted 等 Run 关系
maestro knowledge stage spec "规则标题" --content-file <path|-> \
  --action propose --run <run-id> --session <session-id> \
  --signal validated --signal-ids spec:S-1,knowhow:K-1

# 审查（--refresh 内含 reconcile）
maestro knowledge review <session-id> --refresh

# 对 review_required candidate 做证据化裁决（内含刷新视图）
maestro knowledge review <session-id> \
  --resolve <candidate-id> --as related --target <knowledge-id> --reason "<reason>"

# Run sealed 后显式提升选中的 candidate
maestro knowledge promote <session-id> --candidate <candidate-id>
maestro knowledge promote <session-id> --all
maestro session seal <session-id>

review 默认只读；--refresh 内含 reconcile，仅在显示 missing 或 stale 时使用。--resolve 在审查界面内直接裁决，无需单独命令。Search/自动注入只是 exposure，显式 load 自动记录为 consumed，也不会触发 promotion。

只读 audit 与 report-first normalization

maestro knowledge audit --scope all --json
maestro knowledge normalize --report .workflow/knowledge-normalize.json
# 审阅报告后，且源文件与 repo_id 未变化：
maestro knowledge normalize --report .workflow/knowledge-normalize.json --apply

Audit 报告 legacy tags/specCategory/free category/status/source/codePaths/lang/assetType、legacy-unscoped、缺 manifest、linked ID mismatch、read/write capabilities、pending cross-repo promotion，但不修改语料。Normalize 只迁移确定性 alias 并在写前备份；自由 category 保留为 unresolved，绝不猜 canonical category。没有先前报告、报告不匹配、源哈希变化或 repository identity 变化都 fail closed。

<spec-entry category="coding" keywords="auth,token,rotation" date="2026-04-21">

### Token rotation needs email carried through refresh flow

Revoked column must be set rather than deleting tokens.

</spec-entry>

---
title: OAuth PKCE Authorization Flow
type: recipe
category: coding
keywords: [oauth, pkce, auth]
tool: true
summary: "Use when implementing OAuth 2.0 login for public clients."
---

## Steps
1. Generate code_verifier ...

知识生命周期

稳定标识（sid）

每个 <spec-entry> 在创建时自动分配一个稳定 ID（格式 S-YYYYMMDD-xxxx），用于跨文件引用和演化链追踪。存量条目可通过 maestro spec backfill-sid 回填。

演化链（Supersession）

当新知识替代旧知识时，使用 supersede 建立演化链：

# 1. 添加新条目（自动生成 sid）
maestro spec add coding "新规则" "内容" --keywords kw1,kw2 --json
# 输出中包含 sid，如 S-20260704-a1b2

# 2. 将旧条目标记为 deprecated
maestro spec supersede <old-sid> --by <new-sid>

# 3. 查看演化链
maestro spec history <sid>
# ○ deprecated  S-20260101-x1y2  "旧规则"
#     ↓
# ● CURRENT     S-20260704-a1b2  "新规则"

被替代的条目以 canonical lifecycleStatus="deprecated" 表示（legacy status 仍可读并由显式 normalize 迁移），从搜索和 agent 注入中排除，但仍可通过 --include-deprecated 查看。

冲突双轨

新知识与旧条目的关系分两种，语义不同、操作不同：

健康检查

maestro spec health

输出：生命周期统计（active/deprecated/contested）、演化链数量、悬空/循环 supersedes 检测、整体新鲜度均值。

相关命令

写入类

读取类

分析类

初始化

Tool — 可执行知识

Tool 是标记了 tool: true 的 knowhow 文档，定义可执行的业务流程——轻量化的 workflow，沉淀在项目目录下，具有自发现自使用特性。

---
title: Payment Gateway Idempotency Verification
type: recipe
category: test
keywords: [payment, gateway, idempotency]
tool: true
summary: "Use when testing payment endpoints for retry safety."
---

## Steps
1. Generate idempotency key (UUID v4)
2. Submit charge request with key
3. Retry same request — assert identical response
4. Submit different amount with same key — assert 409
5. Verify webhook delivers exactly once

maestro spec load --category test 自动扫描 knowhow/ 中 category=test 且 tool=true 的文档，将工具摘要与 spec 一起注入 agent 上下文。

注册与使用

Tool 就是带 tool: true 的 knowhow 文档：用 /maestro-knowhow（recipe 类型 + --tool）沉淀，agent 通过 maestro spec load --category 自动发现并注入摘要——无需专门的注册/执行命令。

自动注入机制

\text{Session} 级去重：同一条目不会重复注入。

代码知识图谱集成（\text{KG} \times \text{Wiki}）

当 $maestro kg index生成knowledge-graph.json` 后，WikiIndexer 自动将 KG 数据索引为虚拟 wiki 条目：

Edge 双层存储：related[] 保存 top-N 关联 ID（用于 wiki 图分析），ext.kgEdges[] 保存完整有向异构边（用于语义遍历）。

搜索降级：KG 节点在 BM25 中仅索引 title + tags，避免代码标识符污染常规搜索。

交叉引用：KG 节点通过 filePath 自动匹配 codebase-comp-* 条目，建立 ext.semanticDuplicateOf 引用。

# 查看 KG 索引
maestro wiki list --query kg

# 搜索代码实体
maestro wiki search "AuthMiddleware"

# 代码变更影响分析
maestro kg diff-wiki

# KG 节点详情（含关联 wiki 条目）
maestro kg explain <node-id>

Domain 领域知识系统

Domain 系统管理项目领域术语表（glossary），为 spec 注入和代码理解提供领域上下文。核心模块包括 domain-loader.ts（术语 CRUD + 文件锁）、domain-scanner.ts（代码扫描发现候选术语）、domain-matcher.ts（CJK 感知的术语匹配）。

CLI 子命令

术语结构

每个术语包含：id（kebab-case）、canonical（显示名）、definition、aliases[]、keywords[]、relationships[]、tier（core/extended/peripheral）、status（active/deprecated）、source（manual/discover/import）、可选 concept_ref（详细概念文档路径）。

与 Spec 注入的集成

spec-injector 和 keyword-spec-injector 在注入 spec 条目前，先通过 domain-matcher 匹配 prompt 中的领域术语，将匹配到的术语定义作为上下文前缀注入，帮助 agent 理解项目专有概念。

可信度评估系统

credibility.ts 实现基于指数衰减的知识可信度评分，spec-analytics.ts 记录注入日志用于改进分析。

衰减模型

factor = floor + (1 - floor) * e^(-λ * age_days)
λ = ln(2) / half_life

• floor = 0.3：最低可信度保底
• ceiling = 1.2：搜索命中可提升至上限
• warningThreshold = 0.5：低于此值触发低可信度警告

存储与更新

CredibilityStore 使用 SQLite credibility 表，记录 search_hits、consumption_count、last_hit_at、last_consumed_at、content_changed_at。内容变更时通过 content_hash 比对重置衰减起点。支持 incrementSearchHits（批量）和 incrementConsumption（单条）追踪使用情况。

Spec Analytics

spec-analytics.ts 记录三种日志类型到 .workflow/spec-analytics.jsonl：

统计聚合提供：按来源/agent 类型/分类的注入命中率、关键词 Top-N 排名、CLI 使用频次、hook 调用统计。日志文件自动轮转（默认 5MB）。

跨工作空间知识共享

workspace.ts 提供跨项目知识共享能力，通过链接其他 Maestro 工作空间实现 spec/knowhow/domain 的跨项目复用。

CLI 子命令

共享类型

链接信息持久化在 .workflow/config.json 的 workspace.linked[] 中。加载时自动解析路径并校验目标 .workflow/ 目录是否存在。

KG 自定义提取器插件机制

plugin-engine.ts 支持两种插件模式扩展知识图谱的代码提取能力，配置文件为 .workflow/kg/extractors.yaml。

两种插件模式

Declarative 规则类型

• regex：正则匹配，支持 $1-$9 模板提取名称
• call：函数调用模式（如 builder.define_constant($NAME, $_)）
• assignment：赋值模式，支持 module/class/any 作用域过滤

Script 插件 API

Script 插件导出 extract(ctx) 函数，PluginContext 提供：

• ctx.filePath / ctx.sourceCode / ctx.language：文件信息
• ctx.findAll(nodeType)：遍历 tree-sitter AST 查找指定类型节点
• ctx.text(startLine, endLine)：提取源码行
• ctx.makeSymbol(input)：构建标准化符号对象

合并策略

插件提取结果与核心 tree-sitter 结果合并，冲突策略由 defaults.conflictPolicy 控制：merge-metadata（默认，保留核心符号）、plugin-wins（插件覆盖）、core-wins（核心保留）。

CooldownGuard 抽象

cooldown-guard.ts 提供跨进程的冷却时间守卫，通过 tmpdir 桥接文件实现子进程间的节流控制。

核心 API

class CooldownGuard {
  shouldRun(sessionId): boolean   // 是否在冷却期内
  markDone(sessionId, extra?)     // 标记完成，写入时间戳
  timeSinceLastMs(sessionId)      // 距上次触发的毫秒数
}

预配置实例

桥接文件存储在系统 tmpdir（maestro-kg-sync-{sessionId}.json / maestro-kg-init-{sessionId}.json），包含 last_trigger 时间戳。shouldRun() 比对当前时间与上次触发时间，超过冷却窗口返回 true。

Script Plugins 安全策略

Script 插件（.mjs 文件）默认禁用，需显式开启以防止不受信任的代码执行。

启用方式

# CLI 显式启用
maestro kg sync --allow-extractor-scripts

# 在 code-extractor 调用链中传递
codeExtractor.extract({ allowScripts: true })

安全行为

warn（默认）：插件失败时输出警告继续执行；fail：插件失败时抛出错误终止提取。

知识流转全景

执行产物                    提取                      存储                    消费
─────────                  ─────                    ─────                  ─────
分析会话 ─────┐                              ┌─→ specs/     ─→ spec-injector → agent
调试记录 ─────┼──→ /maestro-knowledge harvest ──────────┼─→ knowhow/   ─→ wiki load → 按需
规划文档 ─────┤    retrospective 步骤        ├─→ issues/    ─→ /maestro-issue → 追踪
代码变更 ─────┘    /maestro-learn decompose          └─→ learnings  ─→ keyword-injector → 上下文

Progressive Fill——各阶段自动沉淀：

maestro-init → spec init（骨架 + 扫描）
analyze → 锁定决策 → arch，代码模式 → coding
plan    → 设计约定 → coding/arch，测试策略 → test
execute → 经验教训 → learning，根因 → debug
execute → 内置验证（E2.7）→ 质量发现 → review

/maestro 用户管理模块 API：注册、登录、JWT 鉴权、用户 CRUD
/maestro 分析 API 端点设计模式

/maestro 实现上述计划
/maestro-knowledge harvest --source lite-plan --to auto

# auto-test 与 test 是编排器（maestro run）派发的一级 step，不是斜杠命令
auto-test --keyword user-api             # 自动测试：发现 tool → 生成测试代码
test "user management API"               # 会话式 UAT：按 tool 步骤逐项验证

/maestro-learn "refresh token 过期后重试需要处理 race condition"