CLI and MCP

CLI 与 MCP 说明书

Decretum Matrix 对外提供两个并列的传输面：统一 CLI 与只读 stdio MCP。二者共用 scripts/court_public_api.py 与同一份命令权威清单，因此语义一致，不互为包装。

references/manifests/cli-command-surface.v1.json   ← 唯一命令权威
        │
        ├── CLI  : scripts/court_cli.py → court_cli_registry.py
        └── MCP  : scripts/court_mcp_server.py → court_public_registry.py
                        └── 共用 court_public_api.py

MCP 不 spawn CLI、不解析 stdout；CLI 不依赖 MCP 进程。

第一部分：CLI

1.1 入口与调用约定

项目	值
公开命令	`decretum-matrix`
源码等价入口	`python -B scripts/court_cli.py`
命令权威	`references/manifests/cli-command-surface.v1.json`
注册表实现	`scripts/court_cli_registry.py`

decretum-matrix [--format text|json] <group> <command> [args...]

--format 默认 text；自动化与验收一律显式用 --format json。
兼容期内，旧的顶层 court 命令（如 decretum-matrix status）仍被接受。
若 PATH 里没有 decretum-matrix，解析 npm prefix -g 下的 decretum-matrix.cmd，不要降级为内部 Python 业务脚本。

1.2 命令组

组	用途	日常面（默认帮助展示）
`court`	开朝、受理、语义门禁、计划复核、状态、结诏	`open` `status` `plan` `intake-template` `workflow-status` `closeout-session`
`office`	官署生命周期与原生派遣	`start` `admit` `preload-ack` `native-request` `native-capture` `report` `finish` `close`
`shiguan`	史馆归档、索引、记忆裁定	`archive-runtime-task` `archive-checkpoint` `query-shiguan-index` `memory-decision` `grow-shiguan-tree` `tidy-shiguan-records`
`supercc`	独立 superCC runtime	`supercc-squad`
`install`	安装、迁移、更新、修复	`update` `migrate` `rollback` `fix`
`check`	只读门禁与诊断（源码检出）	`doctor` `debug` `all`
`release`	打包与发布产物（源码检出）	项目阶段命令，按显式命令调用

清单中共有 156 条命令，其中大部分是 unified_compatibility_adapter 兼容适配器。默认帮助只展示日常 Skill 面；兼容适配器仍可显式调用，但不应被当作启动依赖。

1.3 常用命令速查

# 开朝与状态
decretum-matrix court open --fast --request-template \
  --task-id <id> --authority <approval|autonomous|super> \
  --behavior <serial|parallel> --worktree <worktree> --task-focus <focus>

decretum-matrix court status --view compact --limit 1 --format json
decretum-matrix court workflow-status --task-id <id> --format json

# 受理与计划
decretum-matrix court intake-template --charter <charter> --format json
decretum-matrix court plan template --task-id <id> --format json
decretum-matrix court plan submit  --task-id <id> --request-file <plan.json> --format json
decretum-matrix court plan review  --task-id <id> --request-file <review.json> --format json
decretum-matrix court plan show    --task-id <id> --format json

# 官署派遣
decretum-matrix office admit --request-file <admit.json> --format json
decretum-matrix office native-request --request-file <selector.json> --format json
decretum-matrix office native-capture --request-file <selector.json> --format json
decretum-matrix office report --request-file <report.json> --format json

# 史馆
decretum-matrix shiguan query-shiguan-index <关键词> --limit 5 --format compact
decretum-matrix shiguan archive-runtime-task --request-file <archive.json> --format json

# 维护（源码检出内）
decretum-matrix check doctor --format json
decretum-matrix install fix --format json          # 只读计划
decretum-matrix install fix --apply --format json  # 显式写入

1.4 关键参数约定

参数	约定
`--task-id`	绑定当前任务；跨任务复用会失败
`--request-file`	请求体为 UTF-8 JSON，不带 BOM
`--worktree`	写集为 worktree 相对路径；绝对路径或目录穿越直接失败
`--authority`	只能取 `approval` / `autonomous` / `super`
`--behavior`	只能取 `serial` / `parallel`
`--format`	`text`（默认）或 `json`

模板参数的作用域不同：--worktree . 按 cwd 解析，request-file 里的 worktree 按文件解析，文档类路径按 skill 根解析。宿主证据可以记录解析后的路径与基准。

1.5 退出与错误

需要源码检出的命令在安装副本外运行会返回 source_checkout_required，这是预期行为，不是故障。
校验失败返回结构化 problem 字符串（如 missing_arguments:...、 unknown_arguments:...），用 --format json 读取。
状态变更必须走 receipt-bound CLI；检查 domain success，不要只检查命令是否打印帮助。

第二部分：MCP

2.1 服务器与协议

项目	值
服务器入口	`scripts/court_mcp_server.py`
传输	stdio
投影实现	`scripts/court_public_registry.py`
主协议版本	`2026-07-28`（现代、无状态）
兼容协议版本	`2025-11-25`
工具数	13（全部 `read_only`）
服务器身份	`decretum-matrix`

现代 wire 要求每个请求携带 _meta.io.modelcontextprotocol/protocolVersion 与 _meta.io.modelcontextprotocol/clientCapabilities；clientInfo 可省略，但存在时必须是带非空 name / version 的 Implementation 对象。

server/discover 已实现，返回支持的版本、tools 能力、服务器身份与公共缓存提示。
tools/list / tools/call 返回 resultType=complete 加自描述服务器元数据。
tools/list 不分页：省略 cursor 或传空串；非空 cursor 返回 -32602。
畸形 JSON 为 -32700；非法 JSON-RPC 请求（含缺失或 null id）为 -32600。

发送 initialize 的客户端选择 legacy 每进程语义，须再发 notifications/initialized，之后可不用现代 _meta 调用 tools/list / tools/call。现代与 legacy 回执分别记录。

2.2 工具矩阵（13 个，全部只读）

工具	用途	参数（`*` 为必填）
`court.capsule_validate`	校验 P00 不变量胶囊	`charter` `value`
`court.closeout_checklist`	返回十四行结诏清单与缺失项	`task_id`
`court.command_help`	返回公开 court 命令帮助	无
`court.dispatch_plan_validate`	只读校验派遣计划	`entries*` `authority` `behavior`
`court.intake_validate`	校验受理载荷（会话门禁 + 胶囊）	`charter` `intake_value` `capsule_value`
`court.semantic_context_validate`	校验绑定诏令编号的语义上下文	`value*`
`court.status`	读取当前 court 运行时状态	`view` `limit`
`court.workflow_status`	读取任务/会话/编号与计划复核绑定	`task_id*`
`memory.scan`	报告记忆扫描边界（不读私有正文）	无
`shiguan.archive_dry_run`	报告归档边界，不写史馆	无
`shiguan.entries_query`	元数据投影查询史馆条目	`query*` `limit`
`shiguan.iku_candidates`	扫描 IKU 占位候选（dry-run）	`scope` `limit`
`shiguan.query`	查询公开史馆索引记录	`terms` `limit`

参数枚举：

court.status.view：compact | full（默认 full，limit 默认 12）
court.dispatch_plan_validate.authority：approval | autonomous | super （默认 approval）
court.dispatch_plan_validate.behavior：serial | parallel（默认 serial）
shiguan.iku_candidates.scope：plan-archives（默认）

2.3 调用示例

{ "name": "court.status", "arguments": { "view": "compact", "limit": 1 } }

{
  "name": "court.dispatch_plan_validate",
  "arguments": {
    "authority": "autonomous",
    "behavior": "serial",
    "entries": []
  }
}

成功返回形如：

{
  "ok": true,
  "tool": "court.status",
  "command_id": "court.court-runtime",
  "api": { "...": "工具自身载荷" },
  "dry_run": false,
  "write_enabled": false
}

失败返回 {"ok": false, "problem": "<bounded error code>"} 且 isError=true。 write_enabled 恒为 false，这是 MCP 面的硬保证。

2.4 只读保证与审计

MCP 只投影命令清单中显式标记 mcp 且 side_effect=read_only 的条目；非只读投影在加载时直接报错。
输入参数按闭合 schema 校验：未知参数返回 unknown_arguments:*，缺参数返回 missing_arguments:*。
每次 tools/call 都会尽力写一条 metadata-only 审计 journal 到 court-runtime 根。审计只记录工具名、协议、成功/错误码与 actor，不记录参数与结果正文，也不记录其摘要；审计失败不会中断工具调用。
court.status 会附带 transport_corruption 标记，用于发现编码损坏。

2.5 边界

MCP 面只做只读校验、状态读取与史馆检索。任何状态变更、归档写入、安装或发布都必须走 CLI 或宿主入口；MCP 永远不会替你执行写入。

2.6 验证 MCP 面

源码检出内可用 wire 探针：

python -B scripts/probe_court_mcp_modern_wire.py --host-state source_checkout
python -B scripts/check_court_mcp_server.py

探针只证明源码 wire 行为；它不证明 Codex / CC Switch 已加载服务器或工具已可见。宿主可见性需要单独的宿主回执。

Navigation Menu

Repository navigation

CLI and MCP

CLI 与 MCP 说明书

第一部分：CLI

1.1 入口与调用约定

1.2 命令组

1.3 常用命令速查

1.4 关键参数约定

1.5 退出与错误

第二部分：MCP

2.1 服务器与协议

2.2 工具矩阵（13 个，全部只读）

2.3 调用示例

2.4 只读保证与审计

2.5 边界

2.6 验证 MCP 面

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally