通过 MCP 让代理沿案内树形图前进的服务器。代理投出回答的标签后， 接下来应确认・案内什么会以规则为基础返回。走到末端即案内完成。
自循环型代理虽然灵活，但即使是同样的咨询，每次也会走不同的路径。 在退款・身份确认这类不能出错的应对中，这既经不起审计，也经不起升级判断。 将需要判断的地方作为树形图固定在外侧，只把需要措辞的部分交给代理。
并非 CS 专用。树形图的词汇不依赖领域，因此可用于所有需要按顺序推进手续的工作。
顧客の発話 guidepost-mcp (MCP · 8127)
│ ┌──────────────────────────┐
┌───▼────────┐ values │ flows/*.yaml ← 起動時に │
│ エージェント ├──────────▶│ メモリ常駐（読むだけ） │
│ │◀──────────┤ engine = 純関数で遷移 │
└────────────┘ next │ SQLite = runs / steps │
│ 発話をラベルに └──────────┬───────────────┘
│ 落とすのはこちら側 │ 読み取り専用
▼ ┌───▼──────────┐
顧客へ返す │ Web UI (SSR) │ いま樹形図のどこにいるか
└───────────────┘自然文 → 标签的解释由代理侧负责。服务器只根据收到的标签进行迁移，
因此 LLM 调用不会增加。实测（Raspberry Pi 5）中，迁移计算为 p95 0.006ms，
包含 SQLite 为 p95 0.76ms，通过 HTTP 的 MCP 端到端为 p95 9.1ms。
语音应对 1 回合总计约 2.5 秒，因此即使包含 HTTP 也只占 0.4%。
详细构成以及如何分配该预算，请参阅 docs/research/voice-agent-latency-budget.md。
flows/<flow_id>.yaml 是一棵完整的树形图。节点只有 4 种。
kind | 作用 | 分支 |
| 询问 1 个确认事项，根据答案的标签分支 | 有 |
| 传达 1 个案内 | 无 |
| 按任意顺序收集多个独立项目 | 无 |
| 终端。带有 | 无 |
id: payment_failed
title: 支払いが失敗した
entry: n_error_code
max_unmatched: 3 # 聞き直しの上限
max_branch_fanout: 3 # これより枝が多いと畳まない
branch_depth: 2 # 枝を辿って結末を探す深さ
on_unknown: broaden # 分からないと言われたとき。broaden / escalate
on_stuck: 原因が絞れないため、決済窓口の担当者に引き継ぐ
nodes:
- id: n_error_code
kind: ask
say: 決済画面に出ているエラーコードを確認する # 逐語原稿ではなく「何を伝えるか」
accepts: # ラベル → そのラベルに落とす条件
E01: カードが拒否された
E02: 残高不足・限度額超過
next:
E01: n_card_age
E02: n_balance
__other__: n_symptom # 想定外のラベルの逃がし先（任意）
__unknown__: n_generic # 分からないときの逃がし先（任意）
- id: n_identity
kind: collect
say: 本人確認に必要な情報を集める
on_unknown: escalate # 重要な手続きなので畳ませない
slots:
order_id:
ask: 注文番号を聞く
required: true # 埋まらないと進めない
phone: 登録の電話番号を聞く # 短い書き方（任意扱い）
next: n_verify
- id: n_resolved
kind: end
outcome: resolved
say: 解消したことを確認し、対応を締めるsay 不是逐字原稿，而是「要传达什么」的素材。措辞由代理根据场合调整。
1 个节点 = 1 个确认事项或 1 个案内。
写完后要验证。不可达节点或没有去向的标签，在写的时候是能运行的，因此要到运行时才会发现。
uv run guidepost-mcp lint flows/ # CI でも回している
uv run guidepost-mcp show payment_failed --flows flows # 樹形図を木で表示
uv run guidepost-mcp drafts # 預かっている草案の一覧
uv run guidepost-mcp approve refund_request # 草案を検査し直して flows/ へ移す
uv run guidepost-mcp discard refund_request # 草案を捨てるRelated MCP server: sop-mcp
工具 | 作用 |
| 无参数时返回类别列表与件数，指定 |
| 开始 run。返回 |
| 投出回答。返回以下 5 种状态之一 |
| 当前位置・路径・已收集的值。用于恢复和交接 |
| 返回。丢弃被订正的值 |
| 不走到末端直接结束 |
| 将树形图作为草案寄存。返回 lint 的指摘。不会出现在应对中 |
树形图增多后无法全部返回，因此 guide_flows() 首先返回类别（定义于 flows/categories.yaml
）和各件数，再通过 guide_flows(category=...) 返回其中的列表。如果哪个类别都
不适用，就不要勉强套用，直接不使用树形图进行应对。
guide_draft 只是寄存树形图，不会出现在 flows/ 中，也不会出现在 guide_flows() 中。只有人通过
guidepost-mcp approve 批准后才成为正本。树形图的生成是此服务器之外的工作，
也不设想在应对过程中生成（判断理由见
docs/adr/0011-draft-intake.md）。
如果客户一次性说「出现了 E01，卡是 3 年前的」，明明已有答案却还要
逐题重问，这是要避免的。将已知内容全部传入 values 后，
只要已填满就会前进，在第一个未填满的节点停下。
収集済み: {n_error_code: E01, n_card_age: over_1y}
n_error_code ──E01──▶ n_card_age ──over_1y──▶ n_expiry_check ──?──▶ …
✓ 聞かずに通過 ✓ 聞かずに通過 ▲ ここで止まる跳过的节点以 skipped 返回。为了让代理能知道后续节点的 id，
guide_start 只传递一次索引（各节点 / 槽位询问什么的 1 行说明）。
collect 的任意顺序也使用相同机制。无论按什么顺序填写，凑齐时即通过。
来咨询的人没有答案是很常见的。反复追问也不会问出来。
guide_answer
├─ ラベルが accepts にある ──────────▶ advanced / completed
├─ accepts に無い ──────────────────▶ unmatched（聞き直す）
│ │ max_unmatched 回で下へ
└─ choice="__unknown__" ──────────┐ │
▼ ▼
next.__unknown__ があるか
├─ ある ─▶ advanced（逃がし先へ）
└─ 無い ─▶ on_unknown は
├─ escalate ─▶ stalled（有人へ）
└─ broaden ──▶ 枝を畳めるか
├─ できる ─▶ branched
└─ 無理 ───▶ stalledbranched 是不固定分支，而是并列展示各分支的结局的状态。
会返回用于组织「如果是 E01 请联系信用卡公司，如果是 E02 请确认余额」的材料。
如果有全部分支汇合的节点，会进入 common，因此可以用「无论哪种情况最后都请○○」来概括。
对于退款・身份确认这类在模糊状态下案内会造成危害的手续，请写 on_unknown: escalate
来防止折叠。无法折叠的节点会被 lint 点名，因此只需针对那里进行处理即可。
uv sync
uv run uvicorn guidepost_mcp.web:app --host 127.0.0.1 --port 8127
uv run python scripts/mcp_smoke.py # 実プロトコルで 1 周辿る
uv run python scripts/mcp_smoke.py --parallel # 2 本の run を交互に進めるWeb UI 位于 http://127.0.0.1:8127/。进行中的 run 会被列出，在 /r/<run_id> 中
会在树形图上以颜色区分当前位置・经过的路径・预读跳过的节点・折叠分支的节点。
代理侧通过 HTTP 的 MCP 连接。
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient(
{
"guidepost-mcp": {"url": "http://127.0.0.1:8127/mcp/", "transport": "streamable_http"},
}
)
tools = await client.get_tools()版本正本只有 pyproject.toml 中的 version 一个，遵循 SemVer（在 0.x 期间 minor
可能包含破坏性变更）。变更历史见 CHANGELOG.md。
什么变更属于破坏性变更，定义在 docs/adr/0009-versioning.md 中。
要点是树形图的 YAML 模式与 MCP 工具的契约（工具名・参数・
返回值的键・status 的 5 个值），不包含 next 指示文的措辞。
flows/*.yaml 中的 version 是应对步骤的版本，与本库的版本无关。
为什么将标签解释放在代理侧、为什么在「不知道」时折叠分支、
为什么将 Web UI 设为只读，这些都在 docs/adr/ 中附有理由记录
（列表见 docs/adr/README.md）。作为判断依据的调查资料在
docs/research/ 中。
This server cannot be deployed
Deterministic decision layer for autonomous agents: reproducible PROCEED/REVIEW/SKIP verdicts.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
The system of record for AI agent authority: playbooks, routed policy questions, reusable rules.
Deterministic contextual decision arbitration and action routing for autonomous software. Takes current state, context, or intent plus caller-supplied candidate actions, state transitions, routes, refusals, escalations, tools, or models and returns a deterministic ordered candidate field. Also provides persistent machine representations for memory, retrieval, indexing, and downstream coherence measurement.
