decisionscope

decisionscope

decisionscope 为工具提供对托管决策记录的只读访问权限：这是一个记录实际决策内容的系统。采取行动前，工具可以用自然语言向记录提问——“我们还要推出新的引导流程吗？”——并获取当前权威答案；如果记录没有足够可信的答案，则会明确要求暂缓。轮询调用方也可以从游标开始，读取状态发生变化的决策。该记录只提供答案，绝不会在你的系统中采取任何行动。

decisionscope 是一个转发客户端。它在本地以 CLI 和 stdio MCP 服务的形式运行，并将每次调用转发到托管端点，作为 JSON-RPC tools/call 请求。端点由 RITHMO_MCP_URL 指定，默认使用托管服务 https://app.rithmo.ai/api/mcp；可自托管的部署会在自己的地址提供相同的工具和协议。

设置

每个请求都会携带一个组织专属的服务令牌作为 Bearer 令牌。该令牌只会关联到一个组织，必须具有 mcp:read 范围，并且每个结果都限定于该组织。系统不允许匿名访问。

export RITHMO_MCP_TOKEN="<your service token>"
# Optional; only needed for a self-hosted endpoint:
export RITHMO_MCP_URL="https://app.rithmo.ai/api/mcp"

请将令牌保存在密钥存储中，切勿写入代码。未设置令牌时，每次调用都会在发送任何请求前失败，并提示错误中提及 RITHMO_MCP_TOKEN。

安装

npx @reneturcios/decisionscope whoami

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/decisionscope

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI，并使用 -e 传入上文提到的两个环境变量，以便容器访问你的记录。

CLI

decisionscope query_decision "Are we still shipping the new onboarding flow?"
decisionscope query_decision "What did we decide about GitHub integration?" --type decision
decisionscope query_decision "Who owns the pricing change?" --owner "Priya" --surface jira
decisionscope list_decision_changes
decisionscope list_decision_changes --since "0_" --limit 200
decisionscope whoami

decisionscope --version

结果以 JSON 格式输出。退出码：成功时为 0，操作错误时为 1（包括缺少令牌），用法错误时为 2。参数会在检查令牌前进行验证，因此格式错误的调用始终会报为用法错误。

MCP 服务

同一个二进制文件支持两种运行方式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/decisionscope mcp

MCP 客户端配置：

{
  "mcpServers": {
    "decisionscope": {
      "command": "npx",
      "args": ["-y", "@reneturcios/decisionscope", "mcp"],
      "env": {
        "RITHMO_MCP_TOKEN": "<your service token>"
      }
    }
  }
}

对象结果会以 JSON 文本块的形式返回，同时也会放在 structuredContent 中，因此客户端可以直接读取 res.structuredContent。

工具

工具	输入	返回内容
query_decision	question（必填）；可选的 type（action_item | follow_up | decision）、owner、area、surface	由 result 区分的结果：found、found_record 或 no_record——见下文。
list_decision_changes	可选的 since（不透明游标）；可选的 limit（整数，范围为 1–200，默认值为 50）	{ changes, cursor, has_more }——游标之后发生的变更，按 (changed_at, decision_id) 顺序排列。
whoami	（无）	配置的令牌对应的 { org_id, scopes }。

阅读 query_decision 结果

result 字段有三种变体，区分它们很重要：

• found — 来自承诺台账的实时答案。答案文本位于 answer，并附带 status、lifecycle_state、owner 和 source（两者都是带判别状态的值，绝不会是裸 null）、decided_at、due_at、rationale、conditions、director、context、supersedes 链（从最新到最旧，带循环保护，最多 12 跳）、可选的 spine，以及 confidence 分数。除 confidence 外，同一决策的 found 结果在每次调用中都逐字节相同。
• found_record — 来自主体记录的实时答案。这是答案，不是拒答。答案文本位于 subject.currentAnswer，而不是 answer；它也可能为 null，这表示该主体有记录，但没有可采取行动的答案文本。
• no_record — 没有可信答案。裸形式只有 { "result": "no_record" }；带类型的形式会添加 record，说明为何暂不提供答案（closed、no_record，或者当所询问的表面是记录无法观察到的内容时为 not_observed）。如果存在 premise_check，其 safe_to_proceed: false 始终为 false。遇到 no_record 时，绝不要继续操作。

应根据答案是否可用进行判断，而不是根据变体名称：

const r = res.structuredContent;
const answer =
  r.result === 'found'        ? r.answer :
  r.result === 'found_record' ? r.subject.currentAnswer :
  null;
if (answer != null && String(answer).trim() !== '') { /* act */ }
else { /* hold — no answer to act on */ }

一个特殊情况：如果 no_record 的 record.reason 以 record_unavailable: 开头，表示无法读取记录本身（暂时性故障）。这不代表“我们决定了否”——应暂缓并重试。

排空变更

list_decision_changes 专为轮询触发器而构建：

• 首次调用（不带 since）：返回无变更以及当前头游标。从现在开始；不会重放历史记录。若要从头回填，请传入 since: "0_"。
• has_more 表示页面已满（changes.length === limit）。即使最后一页刚好装满，它也可能为 true，因此下一次调用可能合理地返回零条变更——这表示排空结束，并非错误。
• 页面没有返回任何行时，游标会原样回显，因此使用该游标重新轮询是安全且幂等的。
• 每条变更都包含与 found 结果相同的记录核心，以及 changed_at，但不包含 supersedes、spine 或 confidence。其 status 范围更广：撤销会显示为 dropped 或 superseded，这些值不会由 found 结果返回。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch only)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。