安装 Maestro 资源到项目或全局目录。交互式步骤选择。

maestro install                           # 交互式安装
maestro install --force                   # 非交互批量安装
maestro install components                # 安装文件组件
maestro install hooks                     # 安装 Hook
maestro install mcp                       # 注册 MCP 服务器

交互式模式新增 Codex Hooks 和 Codex MCP 配置步骤。

uninstall -- 移除已安装资源：

maestro uninstall              # 交互式卸载
maestro uninstall --all -y     # 卸载所有，跳过确认

update -- 检查并安装最新版本：

maestro update                 # 检查并提示安装
maestro update --check         # 仅检查

委派任务给 AI 智能体（gemini/qwen/codex/claude/opencode）。支持同步、异步、会话恢复。

maestro delegate "analyze auth module" --to gemini
maestro delegate "fix bug" --to gemini --async
maestro delegate show
maestro delegate output gem-143022-a7f2
maestro delegate status gem-143022-a7f2
maestro delegate message gem-143022-a7f2 "also check utils"
maestro delegate "continue" --to gemini --resume

子命令: show [--all]、output <id>、status <id>、tail <id>、cancel <id>、message <id> <text>、messages <id>

Run 知识生命周期与项目知识维护：

maestro knowledge stage knowhow "事务写入配方" "统一通过 SessionStore transaction 写入" --run <run-id> --category recipe
maestro knowledge stage knowhow "长文配方" --content-file recipe.md --run <run-id>
maestro knowledge stage spec "规则" "内容" --run <run-id> --signal validated --signal-ids spec:S-1
maestro knowledge record spec:S-1 knowhow:K-9 --signal consumed --source search --run <run-id>
maestro knowledge review <session-id> [--refresh]
maestro knowledge review <session-id> --resolve KDC-... --as related --target <knowledge-id> --reason "确认关联"
maestro knowledge promote <session-id> --candidate KDC-...
maestro knowledge promote <session-id> --all
maestro knowledge audit --scope all --prune

search 和自动注入只代表 exposure；显式 load 自动记录为 consumed。stage --signal --signal-ids 在暂存 candidate 的同时记录 cited / validated / contradicted 等 Run 关系。session done 返回精确 candidate receipt，但不会直接写项目 spec/knowhow。review 展示 diversified matches、证据和可复制的下一步命令；--refresh 内含 reconcile；--resolve 内含裁决。promote --all 晋升所有 eligible 候选（observed-only 输出警告）。

统一知识加载命令 — 替代旧版 spec load/wiki load/session load，支持 9 种类型。

maestro load --type spec --category coding           # 加载 coding 类 spec
maestro load --type knowhow --list                   # 列出 knowhow 条目
maestro load --type session --id WFS-20260624-abc    # 加载特定 session
maestro load --type domain --keyword auth            # 按关键词过滤 domain
maestro load --type spec --list --json               # JSON 格式输出

与旧版命令的关系: maestro load --type spec 等效于 maestro spec load，maestro load --type knowhow 等效于 maestro wiki list --type knowhow。推荐使用统一命令。

统一知识搜索 — BM25F 排名，支持 wiki + code 混合搜索。

maestro search "user authentication"              # 混合搜索（wiki + code）
maestro search "auth" --type spec                 # 仅搜索 spec 类型
maestro search "login" --code                     # 仅代码图搜索
maestro search "api" --wiki-only                  # 仅 wiki 搜索
maestro search "domain term" --kg                 # KG 全源统一搜索
maestro search "hook" --category coding # 按类别过滤

搜索模式:

• 默认: wiki + code 混合，按归一化分数交错排列
• --code: 仅 CodeGraph 结果
• --wiki-only: 仅 wiki 结果
• --kg: MaestroGraph 全源统一搜索（代码符号 + 领域术语 + spec 规则 + knowhow 文档）

评分: Wiki 使用 BM25F + 类型加权（spec > knowhow > note）；Code 使用 BM25 + kind 加权 + 名称匹配奖励。Per-source caps: session ≤3, scratch ≤3。

管理搜索守护进程 — 保持 ONNX 模型热缓存，避免冷启动惩罚。

maestro search-daemon start     # 启动守护进程
maestro search-daemon stop      # 停止守护进程
maestro search-daemon status    # 查看状态

守护进程空闲 30 分钟后自动退出。首次搜索会自动启动守护进程。

嵌入模型管理 — 状态查看、预热、重建索引。

maestro embedding status    # 查看模型和索引状态
maestro embedding warmup    # 预热模型（首次使用前）
maestro embedding rebuild   # 重建嵌入索引

嵌入默认启用（v0.5.37+），可通过 --no-emb 标志跳过。

领域知识术语管理 — 项目术语表的增删改查。

maestro domain init                          # 初始化术语表
maestro domain add "API Gateway" "统一入口服务"   # 添加术语
maestro domain list                              # 列出所有术语
maestro domain show api-gateway                  # 查看术语详情
maestro domain search "auth"                     # 搜索术语
maestro domain discover                          # 自动发现术语
maestro domain validate                          # 验证术语表

跨工作区知识共享管理 — 链接其他 Maestro 项目的知识。

maestro workspace link ../other-project --share spec,knowhow   # 链接工作区
maestro workspace unlink other-project                          # 取消链接
maestro workspace list                                          # 列出链接
maestro workspace status                                        # 查看状态

链接的工作区知识会自动集成到 search 和 load 命令的结果中。

图工作流协调器，支持 step 模式和 auto 模式。

maestro coordinate list                                    # 列出链图
maestro coordinate run "implement auth" --chain default -y # 自动运行
maestro coordinate start "implement auth" --chain default  # 步进模式
maestro coordinate next <sessionId>                        # 下一步
maestro coordinate status <sessionId>                      # 会话状态
maestro coordinate report --session <id> --node <id> --status SUCCESS

cli -- 统一 CLI 智能体工具接口：

maestro cli -p "analyze code" --tool gemini --mode analysis
maestro cli -p "fix bug" --tool gemini --mode write

选项同 delegate（-p 必填），另有 show、output <id>、watch <id> 子命令。

serve -- 启动工作流服务器：

maestro serve --port 3600 --host localhost

run 管理一次 command invocation；session 管理 canonical Session identity 与兼容管理，bounded lifecycle 和 orchestration authority 由 execution 持有。Wave 2 仍是 additive：capabilities 支持 Session writes session/1.3 + session/2.0，但默认 writer 仍是 session/1.3，绝不会静默切换默认值。statusless session/2.0 只有在 .workflow/config.json 显式配置 session-schema-selection/1.0、writer: "session/2.0" 与 session_statusless: true 后才启用；只有带完整 Execution authority 的 Run mutation 写 command-run/1.4，并绑定 strict execution/1.0 / execution-lease/1.0。

Schema compatibility 必须区分读取与写入。历史 session/1.0-session/1.3 与 command-run/1.0-command-run/1.4 继续走各自 strict compatibility path。未知未来 Session/Run 版本采用 opaque/best-effort read compatibility：passthrough reader 保留字段供旧 CLI 尽力投影，但命令仍可能因缺少旧 shape 所需字段而失败。read acceptance 既不代表完整语义兼容，也不代表所有未知读取都 fail closed。mutation 跨越 fail-closed mutation boundary，必须通过显式选择的 strict writer schema；Execution mutation 还必须带 exact locator、revision fence 与 lease claim。

先用 capability discovery 选择协议面：

maestro capabilities --json

它输出一行原始 maestro-capabilities/1.0：session_schema_writes exact 为 session/1.3 + session/2.0，Execution writes 只有 execution/1.0，response writes 是 run-response/1.0 + run-response/1.1；features exact 为 execution_generation=true、core_execution_lease=true、execution_handoff=true、execution_operation_drain=true、session_statusless=true、legacy_session_aliases=true。capability 支持不等于项目 writer 选择；没有下面的显式配置时，新 Session 仍写 session/1.3。

{
  "session_schema": {
    "schema_version": "session-schema-selection/1.0",
    "writer": "session/2.0",
    "features": { "session_statusless": true }
  }
}

启用后，maestro session create 只能创建 identity：chain、engine、quality、auto 和 platform 都属于 Execution。已有 1.x Session 还必须通过独立的显式 migration gate；只改配置不会迁移已有 authority。

maestro session create "statusless topic" --id <id> --json
maestro session migrate --session <id> --to session/2.0
maestro session archive --session <id> --request-id <id> --actor <actor> \
  --reason "<reason>" --evidence <ref> \
  --expected-identity-revision <n> --expected-activity-revision <n> --json
maestro session unarchive --session <id> --request-id <id> --actor <actor> \
  --reason "<reason>" --evidence <ref> \
  --expected-identity-revision <n> --expected-activity-revision <n> --json

session/2.0 identity 不存 Session status 或 active_run_id，只存 current_execution_id、latest_execution_id 与 archive metadata。session list|show|status 从 canonical Execution authority 输出 derived_status/derived availability、Execution status 与 active Run。archive/unarchive 使用 session-archive-receipt/1.0，要求两个 CAS revision 与 audit evidence，按 request ID replay，并用 previous_receipt_hash 串联 immutable receipt chain。

Execution generation 与 lease 的 canonical commands：

maestro execution start --session <id> --request-id <id> \
  --owner-id <owner> --owner-kind codex --json
maestro execution status --session <id> --execution <execution-id> --json
maestro execution lease heartbeat --session <id> --execution <execution-id> \
  --request-id <id> --expected-execution-revision <n> \
  --owner-id <owner> --owner-kind codex --lease-epoch <n> --lease-id <token> --json
maestro execution handoff prepare --session <id> --execution <execution-id> \
  --request-id <id> --expected-execution-revision <n> \
  --owner-id <owner> --owner-kind codex --lease-epoch <n> --lease-id <token> \
  --to-owner-id <owner> --claim-output <private-path>
maestro execution lease recover --session <id> --execution <execution-id> \
  --request-id <id> --expected-execution-revision <n> \
  --owner-id <owner> --owner-kind manual --stale-after-ms <n> --json

Command tree 是 execution start|attach|status|pause|resolve|resume|seal、execution handoff prepare|accept|cancel、execution lease status|heartbeat|release|recover。所有 mutation 要求 exact locator、idempotent request 与 --expected-execution-revision；leased mutation 还要求完整 owner/kind/--lease-epoch/private --lease-id。acquisition surface 可用 --claim-output 写 mode-0600 claim；status、普通 response 与 receipt 只显示 public lease/hash。maestro execution seal 只关闭一个 generation，不永久封闭 Session identity，并写入 immutable execution-seal-receipt/1.0，快照 sealed Runs、chain、gates、Artifact registry/content hashes、Evidence 与 corpus refs。receipt-backed recall/import 使用 source-fence/1.1，receipt-backed reuse 使用 reuse-source-fence/1.1；二者可跨后续 Session activity 保持有效，但 receipt、Run、Artifact、generation 或跨 Session 漂移都会 fail closed。Artifact aliases 始终是 Session-global，不冻结在某个 Execution 内。session ... --execution 与 run status --execution 是 deprecated aliases，新调用应使用 maestro execution ...。

session-source knowledge 也不依赖 permanent Session seal（永久 Session seal）。maestro knowledge stage ... --session <id> --evidence <ref> 写入 candidate snapshot；session-level reconciliation fresh 后，显式 maestro knowledge promote <session-id> ... 可在不 seal Session 的情况下提升。run-source candidate 仍要求 source Run sealed。Execution seal 或历史 Session seal 都不会隐式 promotion。

Execution-aware run create|next|complete|decide 还要求 --execution <id> --generation <n> 加上述 revision/lease options，输出 run-response/1.1 并写 command-run/1.4。整组 Execution options 都省略时保留 legacy run-response/1.0 + command-run/1.3；partial options 返回 COMMANDER_USAGE，不会静默回退。

人类入口优先使用 run start / run done / run edit；run create / run complete 保留为稳定 machine protocol 和兼容面。

maestro run start "理解认证流程" --cmd learn --session 20260721-learn-auth --arg "src/auth"
maestro run start "修复登录链路" --chain analyze plan execute verify
maestro session create "修复登录链路" --chain analyze plan execute verify --engine manual
maestro run edit test review --after latest
maestro run done --verdict done-with-concerns --note "后续补充文档镜像"

maestro run prepare <step> --platform codex
maestro run create <command> --session <id> --intent "<intent>" --json
maestro run brief <run-id> --session <id> --json
maestro run check <run-id> --session <id> --json
maestro run complete <run-id> --session <id> --chain-proposal outputs/chain-proposal.json --json
maestro run seal-session <session-id> --json
maestro session status <session-id>
maestro session check <session-id>
maestro session evidence <session-id> --status accepted
maestro skills --platform codex --steps --json

run brief 的成功结果固定为 brief-result/1.1（读取兼容 1.0）：session/run 是 durable authority， guidance 携带 prepare、workflow、完整 run-mode 以及 captured/current hash drift， execution_contract 是 invocation、inputs、outputs、gates、reuse 的唯一结构化执行视图， continuity 携带 handoff/anchor，recovery.next 与外层 envelope next 必须完全一致。 顶层只保留 human locator（session_id/run_id/run_dir）和 Pi bridge 使用的 canonical upstream map；不再重复输出 args、argument requirements、reuse assessments、gate summary 或 outputs。

所有入口共享一种 Session 和一种 chain；历史 engine 只作兼容元数据。声明 orchestration.chain_effects 的 Skill 可产出 typed proposal，orchestrator 决定 accept/reject/revise，Runtime 通过 run complete --chain-proposal 将 Run seal、verdict 与链变更原子提交。/maestro 与 /maestro-ralph 可双向继续同一 Session，无需 promotion 或 engine rewrite。

Canonical paused recovery 必须按 resolve → resume 执行：

maestro session resolve --session <id> --decision <point-id> --disposition proceed \
  --request-id <id> --actor <name> --reason "<reason>" --evidence <ref> \
  --expected-identity-revision <n> --expected-activity-revision <n> --json

maestro session resume --session <id> \
  --request-id <id> --actor <name> --reason "<reason>" --evidence <ref> \
  --expected-identity-revision <n> --expected-activity-revision <n> --json

maestro run next --session <id> --json

resolve 每次只处置一个 escalated decision（--decision + proceed|retry）或 failed step（--step + retry|skip），成功后 Session 仍为 paused。resume 只在所有 blocker 清空后转为 running。两者都不创建 Run；run next 是恢复后唯一的 chain allocator。若 Session 有 lease，两条命令都必须同时提供 --execution-owner、--owner-epoch、--lease-id。

Machine operation matrix（1.0 legacy + 1.1 additive）

对 decide、recovery、chain 与 meta mutation，--request-id 提供幂等 transition receipt；--expected-identity-revision、--expected-activity-revision 与完整 lease triple 提供 fence。resolve/resume 将这些 audit/revision 字段设为必填；chain/meta mutation 接受同一组 guard options。

显式 --json 时，legacy/default surface 的 success、business error、replay 和 Commander usage 继续只写一行 strict run-response/1.0；stderr 为空，process status 与 envelope exit_code 一致。

Execution lifecycle、Execution-aware Run mutation 与 deprecated Execution aliases 使用 strict run-response/1.1。它接受全部 1.0 operations，并加入 capabilities、session-create、session-archive、session-unarchive、execution-start、execution-attach、execution-status、execution-pause、execution-resolve、execution-resume、execution-seal、execution-handoff-prepare、execution-handoff-accept、execution-handoff-cancel、execution-lease-status、execution-lease-heartbeat、execution-lease-release、execution-lease-recover、execution-operation-claim、execution-operation-heartbeat、execution-operation-release、execution-operation-status。1.1 增加 disposition、Execution locator、revision/lease fence 与 warnings，同样保持一行 stdout、空 stderr、exit parity；usage error 是 COMMANDER_USAGE、exit 2。maestro capabilities --json 则直接输出一行 capability JSON。

Claude Code 统一启动器，管理 workflow profile 和 settings 切换。

maestro launcher -w my-project -s dev   # 指定 profile 启动
maestro launcher list                   # 列出所有 profile
maestro launcher status                 # 当前活跃 profile
maestro launcher add-workflow my-proj --claude-md ./CLAUDE.md
maestro launcher add-settings dev ./settings-dev.json
maestro launcher scan ./configs         # 扫描配置文件

项目 Spec 管理（初始化、加载、列表、状态）。

maestro spec init                              # 初始化
maestro spec load --category coding --keyword auth
maestro spec list                              # 列出文件
maestro spec status                            # 状态
maestro spec add <category> "<title>" "<content>" --json  # --json 返回 sid
maestro spec supersede <old-sid> --by <new-sid>          # 演化替代
maestro spec history <sid>                          # 查看演化链
maestro spec health [--json]                             # 知识健康报告
maestro spec backfill-sid                                # 回填存量无 sid 条目

Wiki 知识图谱查询和变更。默认离线，--live 使用 HTTP API。

# 列表与搜索
maestro wiki list --type spec --tag security --status active --group --json
maestro wiki list -q "authentication"                # BM25 内联搜索
maestro wiki search "auth token"                     # 全文搜索
maestro wiki get <id>                                # 获取单条

# 创建（spec / knowhow）
maestro wiki create --type spec --slug auth --title "Auth" --body "# Auth\n..."
  # 可选: --created-by, --source-ref, --parent, --frontmatter

# 条目追加与移除
maestro wiki append <containerId> --body "..." --keywords "coding,exports"
maestro wiki remove-entry <entryId>

# 更新 / 删除
maestro wiki update <id> --title "New Title"
maestro wiki delete <id>

# 图谱分析
maestro wiki health | orphans | hubs --limit 10 | backlinks <id> | forward <id> | graph

写保护：specs/*.md 的 body 通过 wiki update 禁止修改（403），需使用 wiki append / wiki remove-entry。memory/*.md 支持 CRUD。虚拟条目（issue、codebase、KG）完全只读。

KG 集成：当 .workflow/codebase/knowledge-graph.json 存在时，KG 节点、架构层、代码导览自动作为虚拟条目索引到 wiki，可通过 wiki search、wiki list --query kg 发现。

代码知识图谱查询。操作 .workflow/codebase/knowledge-graph.json（由 maestro kg index 的 KG 管道生成）。

``$\text{bash}

统计

\text{maestro} \text{kg} \text{stats} # 节点/边/层/导览统计 \text{maestro} \text{kg} \text{stats} --\text{json} # \text{JSON} 输出

搜索

\text{maestro} \text{kg} \text{query} "认证" # 按名称/摘要/标签搜索节点 \text{maestro} \text{kg} \text{query} "\text{auth}" --\text{limit} 5 --\text{type} \text{module} --\text{json}

节点详情（含 \text{Wiki} 双向绑定）

\text{maestro} \text{kg} \text{explain} <\text{node}-\text{id}> # 节点详情 + 出入边 + 关联 \text{wiki} 条目 \text{maestro} \text{kg} \text{explain} <\text{node}-\text{id}> --\text{json} # \text{JSON} 输出（含 \text{wiki} 匹配） \text{maestro} \text{kg} \text{explain} <\text{node}-\text{id}> --\text{no}-\text{wiki} # 跳过 \text{wiki} 交叉引用

路径查找

\text{maestro} \text{kg} \text{path} <\text{from}-\text{id}> <\text{to}-\text{id}> # \text{BFS} 最短路径 \text{maestro} \text{kg} \text{path} <\text{from}-\text{id}> <\text{to}-\text{id}> --\text{json}

变更影响分析

\text{maestro} \text{kg} \text{diff} # \text{git} \text{diff} 影响的 \text{KG} 节点 + 1-\text{hop} 扩展 \text{maestro} \text{kg} \text{diff} --\text{staged} # 仅暂存区变更

变更影响 \times \text{Wiki} 交叉引用

\text{maestro} \text{kg} \text{diff}-\text{wiki} # \text{git} 变更 → \text{KG} 影响 → 受影响 \text{wiki} 条目 \text{maestro} \text{kg} \text{diff}-\text{wiki} --\text{staged} --\text{json} # \text{JSON} 输出 $``

Wiki 集成：explain 自动查询 WikiIndexer，显示与 KG 节点关联的 wiki 条目（通过 virtualKind 匹配和 codePaths/filePath 匹配）。diff-wiki 将代码变更的影响面传导到 wiki 层面。

Hook 管理与评估器运行。支持 Claude Code 和 Codex 双平台。

# Claude Code
maestro hooks install --level full
maestro hooks uninstall

# Codex
maestro hooks install --target codex --level standard
maestro hooks uninstall --target codex

# 通用
maestro hooks status               # 安装状态（双平台）
maestro hooks list                 # 列出所有 Hook
maestro hooks toggle spec-injector on
maestro hooks run spec-injector    # 运行评估器

Codex hooks 需 ~/.codex/config.toml 中启用 codex_hooks = true。Windows 暂不支持。

命令 Overlay 管理 -- 非侵入式 .claude/commands 补丁。

maestro overlay list                    # 查看并管理
maestro overlay apply                   # 重新应用（幂等）
maestro overlay add my-overlay.json     # 安装
maestro overlay remove my-overlay       # 移除
maestro overlay bundle -o bundle.json   # 打包
maestro overlay import-bundle bundle.json
maestro overlay push                    # 推送到团队共享

人类团队协作。

maestro collab join                    # 注册为团队成员
maestro collab whoami                  # 当前身份
maestro collab status                  # 团队活动
maestro collab sync                    # 同步远程
maestro collab preflight --phase 1     # 冲突预检
maestro collab guard                   # 命名空间边界
maestro collab task create --title "task"
maestro collab task list --status open
maestro collab task status <id> in_progress
maestro collab task assign <id> <uid>

智能体团队消息总线。

maestro msg send "task done" -s <session> --from worker --to coordinator
maestro msg list -s <session> --last 10
maestro msg status -s <session>
maestro msg broadcast "meeting" -s <session> --from coordinator

知识复用管理。6 种类型: session, tip, template, recipe, reference, decision。

maestro kh add --type template --title "React Hook Form" --body "..." --lang typescript
maestro kh add --type recipe --title "Deploy" --body "Steps: ..." --tags deploy
maestro kh add --type decision --title "Use PG" --body "ADR: ..." --status accepted
maestro kh list                           # 列出全部
maestro kh list --type template           # 按类型筛选
maestro kh search "deploy"               # 关键词搜索
maestro kh get knowhow-20260427-1912     # 查看详情

brainstorm-visualize -- 头脑风暴 HTML 原型可视化服务器：

maestro bv start --dir ./prototypes     # 启动服务
maestro bv status <execId>              # 查看状态
maestro bv stop <execId>                # 停止服务

ext -- 扩展管理：

maestro ext list                        # 列出扩展

tool -- 工具交互：

maestro tool list                       # 列出工具
maestro tool exec read_file '{"path":"README.md"}'

/maestro-ralph 是 canonical Session/Run 之上的 closed-loop policy，不拥有 Ralph 专属 Session。通用辅助能力使用中立 namespace；旧 maestro ralph ... 仅保留兼容窗口。

maestro session status <session-id>     # 通用 Session 状态
maestro session check <session-id>      # 通用 chain/Run/decision 检查
maestro session evidence <session-id>   # canonical Evidence Registry
maestro skills --platform codex --steps # 通用 Skill/step scanner
maestro run next --session <session-id> # 分配下一条 chain-bound Run
maestro run complete --session <session-id> --verdict done

代码知识图谱 CLI — 查询 .workflow/codebase/knowledge-graph.json 中的代码结构语义信息。

maestro kg stats                    # 图谱统计（节点数、边数、模块分布）
maestro kg query "UserService"      # 按名称/类型搜索节点
maestro kg explain "validateToken"  # 节点详情（依赖、调用者、模块）
maestro kg path "loginController" "db.query"  # 调用路径
maestro kg diff                     # 对比图谱快照差异