历史回顾：
【开源自荐】Maestro-FLow 工作流-实现Claude code&&Codex 自动推进/闭环治理/知识复用/团队协作/worktree并行/多cli调用 - 开发调优 - LINUX DO
Maestro-FLow codex 焚诀~~~配合/goal 闭环长时多agent推进 - 开发调优 - LINUX DO
【开源自荐】助我迭代，我将Maestro-Flow打包到一个skill，Maestro-Flow-One——软件全生命周期自动推进 - 开发调优 - LINUX DO
Maestro-Flow 的知识管理系统详解
Maestro-Flow 经过多个版本的迭代，现已经完善定型，向大家分享设计及使用说明。
Maestro-Flow 中的知识沉淀主要分两种：约束 和 积累。约束是编码规范、架构决策、质量规则——规定"不能做什么"。积累是操作步骤、设计资产、调试经验——记录"怎么做过"。前者需要强制加载，后者需要按需检索，典型产物结构如下:
.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 # 长文档（通用兜底）
└── wiki-index.json # 统一索引（WikiIndexer 自动生成）
相关命令
写入类
| 命令 | 职责 |
|---|---|
/spec-add |
向 specs 文件追加 <spec-entry> 条目，支持 inline 和 ref 两种模式 |
/manage-knowhow-capture |
捕获 6 种类型知识文档到 knowhow/（compact、template、recipe、reference、decision、tip） |
/maestro-tools-register |
将可复用业务流程注册为 knowhow 工具文档（YAML 头 tool: true + category） |
/manage-learn |
捕获原子洞察到 learnings.md（pattern、gotcha、technique、tip） |
/manage-harvest |
从工作流产物中提取知识碎片，路由到 wiki/spec/issue 三个存储 |
读取类
| 命令 | 职责 |
|---|---|
/spec-load |
按 category 加载主文档 + 跨文件 keyword 匹配条目 + 自动发现 knowhow 工具 |
/maestro-tools-execute |
从 knowhow 加载工具文档并逐步执行 |
/manage-knowhow |
跨 workflow knowhow 和 system memory 两个存储做 list/search/view/edit/delete |
/manage-wiki |
Wiki 图健康度、搜索、清理、统计 |
分析类
| 命令 | 职责 |
|---|---|
/wiki-digest |
语义主题聚类 + 知识覆盖热力图 + gap 分析 |
/wiki-connect |
发现孤立节点和缺失连接，修复图联通性 |
/learn-decompose |
从代码中提取设计模式，写入 spec 和 wiki |
/learn-follow |
引导式阅读代码/wiki，提取 pattern 并构建理解 |
初始化
| 命令 | 职责 |
|---|---|
/spec-setup |
扫描项目结构，初始化 specs 骨架文件（6 个种子文件） |
Tool — 可执行知识
Tool 是标记了 tool: true 的 knowhow 文档，存储在 .workflow/knowhow/ 中，定义可执行的业务流程。
简单来说：Tool 可以理解为轻量化的 workflow（针对业务需求，沉淀在项目目录下，具有自发现自使用特性）
任何 knowhow 文档都可以成为 Tool，只需在 YAML 头中加入 tool: true 和 category：
---
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
spec load --category test 会自动扫描 knowhow/ 中 category=test 且 tool=true 的文档，将工具摘要与 spec 一起注入 agent 上下文。
注册时机
通过 /maestro-tools-register 注册：
| 阶段 | 场景示例 |
|---|---|
| 规划期间 | 标准化业务流程（支付对账流程、OAuth 集成步骤） |
| 执行之后 | 捕获经过验证的操作步骤（数据库迁移回滚、部署流程） |
| 测试之前 | 注册验证方法给 test agent（E2E 结算流程、API 幂等性验证） |
示例：
业务需求 ──→ 规划阶段注册 tool ──→ test agent 自动发现 ──→ 执行验证
↑ │
└──── 执行后优化 ←── 发现新 edge case ←──┘
知识流转全景
执行产物 提取 存储 消费
───────── ───── ───── ─────
分析会话 ─────┐ ┌─→ specs/ ─→ spec-injector → agent
调试记录 ─────┼──→ /manage-harvest ──────────┼─→ knowhow/ ─→ wiki load → 按需
规划文档 ─────┤ /quality-retrospective ├─→ issues/ ─→ manage-issue → 追踪
代码变更 ─────┘ /learn-decompose └─→ learnings ─→ keyword-injector → 上下文
↑
/manage-learn ─┘ (原子洞察直写)
Progressive Fill
Spec 内容由流水线各阶段逐步丰富：
maestro-init → spec-setup（骨架 + 扫描）
maestro-analyze → 锁定决策 → arch，代码模式 → coding
maestro-plan → 设计约定 → coding/arch，测试策略 → test
maestro-execute → 经验教训 → learning，根因 → debug
maestro-verify → 质量发现 → review
每个阶段执行完毕，产生的知识自动沉淀到对应 category 的 spec 文件中，下一阶段的 agent 即可通过 category 加载获取前序阶段的积累。spec load 同时扫描 knowhow/ 中匹配 category 的工具文档，将可执行流程一并注入。
实践场景：前后端 API 开发闭环
以用户管理模块（注册、登录、JWT 鉴权、用户 CRUD）为例，演示知识系统如何贯穿前后端开发全周期。
闭环全景
开发过程（产出产物） 知识回收 补充 & 注册 消费
───────────────── ───────── ──────────── ──────
/workflow-lite-plan ─┐ ┌→ AST-* (API 契约) code-developer
/maestro-analyze ─┼→ /manage-harvest ──┤ category: coding 自动注入
/workflow-lite-execute┘ 提取被动知识 │
pattern/decision ├→ RCP-* (验证流程) test-fix-agent
│ category: test 自动发现
补充主动流程 ─────┤ tool: true
/manage-knowhow-capture
/maestro-tools-register
└→ specs/ (规范/决策) keyword-injector
coding/arch 上下文匹配
反哺
测试发现新边界 → /maestro-tools-register optimize
测试失败根因 → /manage-learn → learnings.md
步骤详解
Step 1 — 规划，产出 API 设计产物 (CCW 相关命令 举个例子)
/workflow-lite-plan 用户管理模块 API：注册、登录、JWT 鉴权、用户 CRUD
产物进入 .workflow/.lite-plan/，包含 API 端点列表、依赖关系、设计决策。
Step 2 — 分析（可选，产出更丰富产物）
/maestro-analyze API 端点设计模式分析：路由结构、错误处理、响应格式
产物进入 .workflow/.analysis/ANL-*/，包含 findings、recommendations。
Step 3 — 实现前后端
/workflow-lite-execute
Step 4 — harvest 提取 API 知识
/manage-harvest --source lite-plan --to auto
harvest 从 plan 产物中提取并自动路由：
| 提取内容 | 分类 | 路由目标 | 示例 |
|---|---|---|---|
| API 命名规范 | pattern | spec → coding | “所有端点使用 /api/v1/ 前缀 + RESTful 命名” |
| 鉴权方案决策 | decision | spec → arch | “密码 bcrypt(12)，token RS256 签名” |
| 响应格式知识 | knowhow | wiki → knowhow | “统一返回 { data, error, meta } 结构” |
| 缺失功能 | task | issue | “缺少 rate limiting 中间件” |
关键认知：harvest 提取的是被动知识（pattern/decision），不是可执行的 tool。要让 test agent 使用，需要后续步骤。
Step 5 — 捕获 API 契约资产
/manage-knowhow-capture asset "User Management API Contract" \
--asset-type api-contract --code-paths "src/api/users/"
产出 AST-user-api-contract.md（category: coding），开发 agent 实现时自动注入：
---
title: User Management API Contract
type: asset
category: coding
keywords: [user, api, auth, crud, jwt]
codePaths: [src/api/users/]
---
## Endpoints
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | /api/v1/auth/register | No | 用户注册 |
| POST | /api/v1/auth/login | No | 用户登录 |
| POST | /api/v1/auth/refresh | Yes | 刷新 token |
| GET | /api/v1/users/me | Yes | 获取当前用户 |
| PUT | /api/v1/users/me | Yes | 更新资料 |
| DELETE | /api/v1/users/me | Yes | 注销账号 |
Step 6 — 注册 API 验证流程为 Tool
/maestro-tools-register generate User API E2E 验证：注册 → 登录 → token 刷新 → CRUD → 异常
产出 RCP-user-api-verify.md（category: test, tool: true）：
---
title: User API E2E Verification
type: recipe
category: test
keywords: [user, api, auth, e2e, verification]
tool: true
summary: "Use when verifying user management API after implementation or refactoring."
---
## Steps
1. POST /api/v1/auth/register — 新用户 → assert 201
2. POST /api/v1/auth/register — 重复邮箱 → assert 409
3. POST /api/v1/auth/login — 正确凭证 → assert 200 + token
4. POST /api/v1/auth/login — 错误密码 → assert 401
5. GET /api/v1/users/me + Bearer token → assert 200
6. PUT /api/v1/users/me — 更新 name → assert 200
7. POST /api/v1/auth/refresh → assert new token pair
8. GET /api/v1/users/me + expired token → assert 401
9. DELETE /api/v1/users/me → assert 204
10. GET /api/v1/users/me + deleted token → assert 401
也可以从已有 knowhow 文档原地提升：
/maestro-tools-register promote RCP-user-api-verify as test tool
Step 7 — 验证发现链路
maestro spec load --category test --keyword api
确认输出包含 tool 摘要和加载命令。
Step 8 — 测试 agent 消费
/quality-auto-test --keyword user-api # 自动测试：发现 tool → 生成测试代码
/quality-test user management API # 会话式 UAT：按 tool 步骤逐项验证
会渐进式补充spec 但是tool spec 和knowhow需要手动去定义
