Skip to content

Troubleshooting

Jump to bottom
RowlandL edited this page Sep 9, 2026 · 2 revisions

Troubleshooting

本页按「现象 → 原因 → 处置」组织。诊断命令默认只读；排错时不得读取或枚举 pending/private 正文。

1. $decretum-matrix 无法调用

如果错误仍要求：

C:\Users\<user>\.agents\skills\court-capability-router\SKILL.md

说明宿主 policy/index 仍引用迁移前路径。canonical path 应为：

C:\Users\<user>\.agents\skills\decretum-matrix\SKILL.md

修复 root/global AGENTS.md 与 capability index 的 locator，并在全新只读会话中 真实调用 $decretum-matrix。不要复制第二份旧目录来绕过门禁。

2. decretum-matrix 命令找不到

先确认 npm 全局 prefix：

npm prefix -g
decretum-matrix --version

如果 PATH 缺失，直接解析当前 npm prefix 下的 decretum-matrix.cmd（Windows）或 decretum-matrix（macOS/Linux）。不要降级为内部 Python 业务脚本，否则会绕过 公开 CLI 的收据与门禁。

3. CLI 返回 source_checkout_required

check、release 与部分 install 命令需要源码检出（source checkout）。 在安装副本或普通工作目录里运行会返回该错误，这是预期行为，不是故障。

处置：切到源码检出后重试，例如：

cd <source-checkout>/decretum-matrix
decretum-matrix check doctor --format json

4. MCP 工具在宿主里看不到

按顺序确认：

  1. 服务器入口是否正确：scripts/court_mcp_server.py。
  2. 协议版本：现代客户端须发 2026-07-28 与所需 _meta；发 initialize 的 客户端走 legacy 2025-11-25 语义，须补 notifications/initialized。
  3. tools/list 不分页：省略 cursor 或传空串；非空 cursor 返回 -32602。
  4. 源码 wire 行为：
python -B scripts/probe_court_mcp_modern_wire.py --host-state source_checkout

探针只证明源码 wire；宿主可见性（Codex / CC Switch 已加载）需要单独回执， 不能用探针代替。

5. MCP 调用报参数错误

MCP 输入按闭合 schema 校验，错误码可直接定位：

错误 含义 处置
unknown_arguments:<names> 传了 schema 未声明的参数 只传该工具声明的参数
missing_arguments:<names> 缺少必填参数 补上必填项
tool_not_allowed:<name> 工具名不在投影清单中 核对工具名拼写
*_must_be_one_of:... 枚举值非法 改用列出的取值

write_enabled 恒为 false；MCP 不执行任何写入，需要写入请改用 CLI。

6. 角色 projection 不同步

先运行只读检查：

python -B scripts/check_codex_agent_roles.py

若 14 个 role 格式有效但全部 unsynced，先裁定 repository profiles 与当前 .codex/agents 哪个是 source of truth；不要直接用旧 profile --write 覆盖较新 配置。

7. 史馆或 Obsidian 路径异常

检查默认共享根是否为 .agents\court-shiguan\decretum-matrix\references，再运行：

python -B scripts/sync_shiguan_obsidian_vault.py --dry-run
python -B scripts/ensure_shiguan_autosync.py --check-only

只检查公开配置和路径。不要用排错命令枚举或打开 pending/private 正文。

8. 发布 gate 失败

按 first-fail 修复单一 cluster。不要在 source gate 失败时构建 candidate，也不要 在 ZIP、manifest 或 accepted commit 漂移后复用旧 install receipt。

9. 还不知道从哪查

在源码检出内运行：

decretum-matrix check doctor --format json
decretum-matrix check debug  --format json

两个命令都会脱敏 secrets、全程只读，并输出结构化的判定依据。

Clone this wiki locally