Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
docs: clarify decision extensions and Chinese guides, unify KV Cache wording (#53)
澄潭8ae4fc00cd03
diff --git a/apps/website/content/guides/cli.en.md b/apps/website/content/guides/cli.en.mdindex 2938df38..22f4ccc0 100644--- a/apps/website/content/guides/cli.en.md+++ b/apps/website/content/guides/cli.en.md@@ -101,7 +101,7 @@ hiroute worker executorshiroute worker plans```-The results contain the execution agents available on this device and the published plans allowed for the current agent. Do not infer a plan ID from its display name; use the ID returned by the command.+`worker executors` lists execution agents and their availability on this device. `worker plans` lists published plans allowed for the current agent. Choose an agent that passes dependency checks and use the returned plan ID, not its display name.## Start a task@@ -156,6 +156,6 @@ Cancellation does not undo files or external effects already produced.## Machine-readable output-Public commands support `--output text|json|quiet`. Use the default `text` interactively, `json` for scripts and main agents that consume the schema, and `quiet` when only the exit result matters. Use `hiroute schema list` and `hiroute schema show` to discover the current machine contract at runtime.+Public commands support `--output text|json|quiet`. Use the default `text` interactively, `json` for scripts and main agents that consume the schema, and `quiet` for compact output; the fields retained depend on the command's `--help`. Use `hiroute schema list` and `hiroute schema show` to discover the current machine contract at runtime.CLI and daemon accept only the currently Released business commands and continue to reject Planned commands. Automation should discover the runtime schema instead of hard-coding the command count or unreleased capabilities.diff --git a/apps/website/content/guides/cli.zh.md b/apps/website/content/guides/cli.zh.mdindex eb153e74..dc4124df 100644--- a/apps/website/content/guides/cli.zh.md+++ b/apps/website/content/guides/cli.zh.md@@ -1,11 +1,13 @@# HiRoute CLI-HiRoute CLI 是 HiRoute 本机服务的正式终端入口,可连接桌面应用,也可以作为 Linux 无界面版的完整管理界面。模型来源、智能路由、Agent 接入、会话观测和 Worker 任务都复用与桌面应用相同的生产路径,不存在第二套无界面控制面。+HiRoute CLI 让你在终端连接模型、配置路由、接入 Agent、查看会话和委派任务。它连接本机的 HiRoute 服务,与桌面应用使用相同的配置和执行记录,也可以独立管理 Linux 无界面版。++本文中的命令名、参数和 JSON 字段均保留原文。例如 `worker` 管理委派任务,`schema` 查看命令接受和返回的数据格式。## 安装与检查- macOS 桌面应用:打开“设置” → “CLI” → “终端入口”,选择“安装”。-- Linux 无界面版:按 [Linux 无界面版安装](/docs/install-linux/) 使用官网一行命令安装,再显式启动服务。+- Linux 无界面版:按 [Linux 无界面版安装](/docs/install-linux/) 使用官网一行命令安装,再手动启动服务。如果 PATH 不包含入口目录,把下面一行加入 shell 配置后重新打开终端:@@ -21,11 +23,11 @@ hiroute schema list --output jsonhiroute schema show --command-id worker.exec --output json```-CLI 入口与本机服务状态相互独立。如果命令提示服务不可用,桌面应用用户先打开应用;独立服务版(standalone)用户运行 `hiroute service status`,并在需要时运行 `hiroute service start`。CLI 不会替你自动启动服务或重放失败请求。+安装 CLI 后,还需要让本机服务保持运行。如果命令提示服务不可用,桌面应用用户先打开应用;独立服务版(standalone)用户运行 `hiroute service status`,并在需要时运行 `hiroute service start`。CLI 不会替你自动启动服务或重放失败请求。-## 两层命令合同+## 查找命令与请求格式-Host 管理命令以根帮助和 family 帮助为准:+服务启停、Gateway 管理和受保护输入等本机管理命令,用 `--help` 查看。顶层帮助列出命令分类,子命令帮助说明具体用法:```shhiroute --help@@ -34,7 +36,7 @@ hiroute gateway --helphiroute protected-input --help```-Application / Local Control 业务命令以 Released schema 和完整 leaf 帮助为准:+模型、路由、Agent、会话和委派任务等命令,还提供 schema,说明当前版本的请求字段和返回结构。例如,先查找路由保存命令,再查看其数据格式和用法:```shhiroute schema list --output json@@ -42,20 +44,26 @@ hiroute schema show --command-id routing.apply --output jsonhiroute routing apply --help```-不要期待 `schema list` 收录 Host 命令,也不要从网页示例推断当前安装的请求字段。+`schema list` 不包含前一类本机管理命令。准备 JSON 请求时,以当前安装返回的 schema 为准,避免直接套用其他版本的字段。## 管理模型、路由与 Agent-当前已发布的 CLI 支持完整无界面闭环:+常用命令如下。斜杠表示多个子命令,例如 `compute scan/list/show` 分别指 `hiroute compute scan`、`hiroute compute list` 和 `hiroute compute show`,不是要输入斜杠:- `compute scan/list/show` 发现和读取模型来源;`compute connection options/test/preview/apply/authorize` 检查并保存连接。- `models show` 查看候选模型能力。- `decision services list/apply/test` 管理决策模型或自定义扩展的已保存连接版本。- `routing options/list/show/preview/apply` 创建、更新并发布智能路由。- `agents scan/list/check` 发现本机 Agent;`agents connect preview/apply/status` 接入,`agents restore preview/apply` 恢复。-- `operations find/get` 在写响应丢失或状态不确定时,按原幂等域查询已发生的操作。+- `operations find/get` 在保存请求已发出、但结果未收到时,查询原操作是否已经完成。++配置保存分为预览和提交:-配置写入先预览再应用,并保留完整请求、预览摘要、精确 revision 与 idempotency key。模型、路由和 Agent 使用各自的 `preview/apply` 命令;决策连接的预览与保存都通过 `decision services apply` 完成。密码或 API key 通过 `protected-input` 传入,不放进普通 JSON、参数或日志。具体字段始终从对应 `schema show`、`options` 和 leaf `--help` 获取。+1. 先查看该命令的 `schema show`、`options` 和具体子命令的 `--help`,准备请求。+2. 用 `preview` 查看变更,保留返回的摘要和版本号(revision)。+3. 用 `apply` 提交同一份变更,带上这些值和固定的幂等键(idempotency key,用来识别同一次提交,避免重复执行)。++模型、路由和 Agent 分别有 `preview`、`apply` 命令。决策连接是例外:两个步骤都使用 `decision services apply`,见下一节。密码或 API Key 通过 `protected-input` 传入,不放进普通 JSON、命令参数或日志。## 管理决策连接@@ -70,11 +78,25 @@ hiroute decision services apply --request-stdin --output json < decision-apply-rhiroute decision services test --request-stdin --output json < decision-test-request.json```-没有单独的 `decision services preview` 命令。第一次 `apply` 传入 `{schema_version, spec}` 只预览;保存时传入同一 `schema_version`、返回的 `data.normalized_spec`,以及 `data.change_digest` 对应的 `accept_digest`、`data.expected_revisions` 和固定幂等键。`spec.desired_state` 包含连接 ID、`expected_revision`、完整 `service`,以及需要新凭证时的受保护 `input_slot`;`service: null` 删除未被引用的连接。+以上三个 JSON 文件需要先按当前 schema 准备;命令示例不会自动创建它们。没有单独的 `decision services preview` 命令,`apply` 根据请求内容完成两步操作:++| 步骤 | 请求中需要提供的内容 |+| --- | --- |+| 预览 | `{schema_version, spec}`;不保存配置 |+| 保存 | 同一 `schema_version`;以预览返回的 `data.normalized_spec` 作为 `spec`;以 `data.change_digest` 作为 `accept_digest`;带上 `data.expected_revisions` 和固定幂等键 |-列表返回各连接的最新版本。路由选择的是完整已保存版本,按 ID、revision 和内容核对;旧版本仍可用于发布。智能省钱在编辑器的 `smart.classifier` 和 `smart.judgment` 中配置;自定义分支使用 `branch_routing.classifier`、计划 `branch_routing.judgment`,以及各分支的常规 `candidates`、主力 `primary_candidates`(未配置主力时为空数组)和可选完整 `judgment` 覆盖。分支省略覆盖时跟随计划,整套复制后独立,清除覆盖后恢复默认。+`spec.desired_state` 包含连接 ID、`expected_revision` 和完整的 `service`。设置新凭证时,还需提供受保护输入的 `input_slot`。`service: null` 表示删除连接;仍被路由等记录引用的连接不能删除。-保存 r2 不会改变已固定 r1 的路由;需要选择新版本并通过 `routing preview/apply` 发布。测试请求使用 `hiroute.classifier-decision-test/v1`,`classifier` 为 `{kind: "decision_service", service: <完整已保存版本>}`。它只发送固定合成输入,检查该准确连接版本,不读取真实会话或生成质量样本。检查 `data.outcome` 与 `data.failure_code`,不能仅凭命令退出成功判断测试通过。+列表返回各连接的最新版本,路由使用的是你选中的完整已保存版本。保存时会核对 ID、revision 和内容,旧版本仍可用于发布。路由编辑数据中的相关字段为:++| 配置 | 字段 |+| --- | --- |+| 智能省钱的连接与判断设置 | `smart.classifier`、`smart.judgment` |+| 自定义分支的连接与计划默认判断设置 | `branch_routing.classifier`、`branch_routing.judgment` |+| 分支的常规与主力候选 | `candidates`、`primary_candidates`;没有主力组时后者为空数组 |+| 分支独立判断设置 | 可选的完整 `judgment`;省略时跟随计划,设置后独立,移除后恢复跟随计划 |++保存 r2 不会改变已固定 r1 的路由;需要选择新版本并通过 `routing preview/apply` 发布。测试请求的 schema 为 `hiroute.classifier-decision-test/v1`,`classifier` 为 `{kind: "decision_service", service: <完整已保存版本>}`。它只发送固定示例,检查指定的连接版本,不读取真实会话,也不产生实际任务的评分。检查 `data.outcome` 与 `data.failure_code`,不能仅凭命令退出成功判断测试通过。自定义扩展遵守 [自定义扩展 API](/docs/decision-api/);内置供应商配置和接口映射见 [决策模型接入指南](/docs/decision-extensions/)。可选的 [Jev 自托管参考扩展](/docs/jev-decider/) 提供自行部署的示例。完整桌面配置步骤见 [使用智能模型路由](/docs/model-routing/)。@@ -90,9 +112,9 @@ hiroute observation plan-quality samples --plan-id <PLAN_ID> --output jsonhiroute observation plan-quality samples --session-id <SESSION_ID> --limit 50 --output json```-默认会话查询返回事实和 timeline,不返回对话正文。receipt 展示实际路由、模型和上游已报告的 token;没有可信价格证据时,价值金额保持未知,不会伪造为零。+默认会话查询返回执行记录和时间线,不返回对话正文。`receipt` 展示实际路由、模型和供应商报告的 token 用量;缺少可靠价格时,金额显示为未知,不会当成零费用。-`observation plan-quality samples` 至少需要计划或会话范围,返回运行表现使用的阶段事实。`branch_execution` 记录实际任务分支、模型组、组内候选和当时判断标准;本轮选择原因与后续阶段评分分别保存。`--competence below-floor|meets-floor` 按阶段冻结的胜任下限筛选,`--unrated` 查看缺失或部分评分;未评分不等于零。返回游标用于继续分页,此查询不会调用模型或返回受保护的对话正文。+`observation plan-quality samples` 至少需要 `--plan-id` 或 `--session-id` 之一,用来查询指定计划或会话的执行阶段与评分。`branch_execution` 记录实际任务分支、模型组、组内候选和当时判断标准;本轮选择原因与后续阶段评分分别保存。`--competence below-floor|meets-floor` 按阶段冻结的胜任下限筛选,`--unrated` 查看缺失或部分评分;未评分不等于零。返回游标用于继续分页,此查询不会调用模型或返回受保护的对话正文。## 发现执行器和计划@@ -101,7 +123,7 @@ hiroute worker executorshiroute worker plans```-列表只包含当前本机实际可用的执行器,以及当前 Agent 获准使用的已发布计划。不要根据显示名称猜测计划 ID,应使用命令返回的 ID。+`worker executors` 列出本机执行 Agent 的可用状态;`worker plans` 列出当前 Agent 获准使用的已发布计划。选择通过依赖检查的执行 Agent,并使用命令返回的计划 ID,不要用显示名称代替。## 启动任务@@ -116,7 +138,7 @@ hiroute worker exec \输入必须来自 `--` 后的文本、`--file` 文件或标准输入三者之一。`--cwd` 会转换为绝对路径,但它不是目录授权或并发锁。-`--submission-key` 是调用者选择的幂等键。若网络或进程中断后不确定任务是否被接受,请保留同一个 key 查询,不要创建一个新 key 自动重试:+`--submission-key` 是调用者选择的幂等键。新任务应使用新的值。若连接或进程中断后无法确定这次任务是否被接受,使用原来的键查询,不要换一个新键直接重试:```shhiroute worker status --submission my-check-001 --operation start@@ -124,7 +146,7 @@ hiroute worker status --submission my-check-001 --operation start## 查看进度与结果-使用启动结果中的 run ID:+使用启动结果中的 run ID(这次运行的标识):```shhiroute worker status --run <RUN_ID>@@ -132,11 +154,11 @@ hiroute worker wait --run <RUN_ID>hiroute worker result --run <RUN_ID>```-`wait` 是有界等待,不会取消仍在运行的任务。`result` 支持按 offset 和最大字节数分页读取较大的结果。+`wait` 到达等待时限就返回,任务仍可在后台运行;这不代表任务被取消。`result` 支持指定偏移量(offset)和最大字节数,分次读取较大的结果。## 继续或取消-继续任务时必须同时提供 task ID 和它的精确最新 run ID:+继续任务时,同时提供 task ID(任务标识)和该任务最新的 run ID,避免基于过时的运行结果继续:```shhiroute worker continue \@@ -146,7 +168,7 @@ hiroute worker continue \-- "根据测试结果完成修复"```-取消一个精确 run:+取消指定的这次运行:```shhiroute worker cancel --run <RUN_ID> --reason user-requested@@ -156,6 +178,14 @@ hiroute worker cancel --run <RUN_ID> --reason user-requested## 机器可读输出-公开命令支持 `--output text|json|quiet`。交互使用默认的 `text`;脚本和主 Agent 使用 `json` 并按 schema 处理;只关心成功或失败时使用 `quiet`。可以用 `hiroute schema list` 和 `hiroute schema show` 在运行时发现当前版本的机器合同。+公开命令支持 `--output text|json|quiet`:++| 值 | 适用场景 |+| --- | --- |+| `text` | 默认值,供人在终端阅读 |+| `json` | 供脚本或 Agent 读取,按当前 schema 解析字段 |+| `quiet` | 精简输出,具体保留内容以该命令的 `--help` 为准 |++参数值应原样输入,不翻译成中文。用 `hiroute schema list` 和 `hiroute schema show` 查询当前版本的数据格式。-CLI 和 daemon 只接受当前已发布的业务命令,继续拒绝 Planned 命令。自动化应在运行时读取 schema,而不是把命令总数或尚未发布的能力写死。+自动化只应调用当前安装已提供的命令。规划中的功能不代表已经可以调用,也不要把命令数量写死在脚本里。diff --git a/apps/website/content/guides/install-linux.zh.md b/apps/website/content/guides/install-linux.zh.mdindex a602b157..4115af5f 100644--- a/apps/website/content/guides/install-linux.zh.md+++ b/apps/website/content/guides/install-linux.zh.md@@ -1,6 +1,6 @@# 在 Linux 上以无界面模式运行 HiRoute-Linux 无界面版把 HiRoute 的本机服务、Gateway、CLI 和 Agent 管理 Skill 安装到当前用户目录,适合服务器、远程工作站和无图形界面的自动化环境。它不是精简的只读客户端:模型来源、智能路由、Agent 接入、会话观测和任务委派都可以从 CLI 完成。+Linux 无界面版将 HiRoute 安装到当前用户目录,适合服务器、远程工作站和无图形界面的自动化环境。安装内容包括本机服务、负责转发模型请求的 Gateway、CLI,以及供 Agent 使用的管理 Skill。你可以在终端连接模型、配置路由、接入 Agent、查看会话和委派任务。Linux 安装包支持 `x86_64` 和 ARM64(`aarch64`)。不需要 `sudo`;需要 `curl`、Python 3,以及能够运行 HiRoute 二进制的 glibc Linux 环境。@@ -28,7 +28,7 @@ export PATH="$HOME/.local/bin:$PATH"安装脚本会下载最新稳定的 Linux 版本,并在安装前检查架构与文件完整性。桌面应用与独立服务版(standalone)不应在同一个 `HOME` 中同时管理服务。-## 2. 显式启动服务+## 2. 启动服务安装不会自动启动服务或重放请求。安装完成后运行:@@ -37,7 +37,7 @@ hiroute service start --output jsonhiroute system status --output json```-`service start` 使用当前用户的 systemd user manager,适合已有正常登录会话的主机。精简容器、某些 SSH 环境或未启用用户会话的系统可能没有这个条件;此时可在受管理的前台终端直接运行:+`service start` 通过 systemd 的用户服务管理器启动后台服务,需要主机已建立相应的用户会话。精简容器或部分 SSH 环境可能没有用户服务管理器;此时可在终端以前台方式运行:```shhiroute service run@@ -45,7 +45,7 @@ hiroute service run保持这个进程运行,再从另一个终端执行 `hiroute system status --output json`。如果需要登出后长期运行,请按所在发行版的安全策略启用 systemd 用户会话或 linger;这属于主机管理设置,安装器不会替你修改。-`system status` 应显示 role-all daemon 和 Gateway 已就绪。若服务不可用,先查看:+`system status` 应显示本机服务和 Gateway 已就绪。若服务不可用,先查看:```shhiroute service status --output json@@ -53,7 +53,7 @@ hiroute service doctor --output jsonhiroute service logs --output json```-`service`、`gateway` 和 `protected-input` 是 Host 管理命令,通过根帮助和 family 帮助发现:+服务启停等本机管理命令通过 `--help` 查看。例如,下面两条命令分别列出顶层命令和 `service` 的子命令:```shhiroute --help@@ -62,7 +62,7 @@ hiroute service --help## 3. 发现业务命令-模型、路由、Agent、会话和 Worker 属于 Application / Local Control 命令。以当前安装返回的 Released schema 为准,不要根据网页示例猜请求字段:+模型、路由、Agent、会话和委派任务的命令还提供 schema,用来说明当前版本接受的请求字段和返回结果。写自动化脚本前,先查看对应命令的 schema 和帮助:```shhiroute schema list --output json@@ -81,9 +81,9 @@ hiroute agents list --output jsonhiroute sessions status --output json```-它们分别展示可发现的来源、已有路由、可接入 Agent 和观测状态。确认实际 ID 后,再通过相应 `options`、`schema show` 与 leaf `--help` 生成写请求。+它们分别展示可发现的来源、已有路由、可接入 Agent 和观测状态。需要修改配置时,使用查询结果中的实际 ID,再查看对应 `options`、`schema show` 和具体子命令的 `--help` 来准备请求。-写操作遵循同一个安全流程:先读取 schema 和 options,执行有界 test,再把同一份变更送入 `preview`;确认 preview 的摘要、revision 和影响后才执行 `apply`。密码或 API key 通过 `protected-input` 传入,不放进普通 JSON、参数或日志。+保存配置通常分两步:先用 `preview` 查看将发生的变更,再用 `apply` 提交同一份变更,并带上预览返回的摘要和版本号。连接提供 `test` 时,可先检查连接。决策连接的预览与保存都使用 `decision services apply`,具体格式见 [CLI 指南](/docs/cli/)。密码或 API Key 通过 `protected-input` 传入,不放进普通 JSON、命令参数或日志。## 4. 完成无界面配置@@ -91,11 +91,11 @@ hiroute sessions status --output json1. 用 `compute scan/list/show` 查看可用来源;自定义 API 使用 `compute connection options/test/preview/apply`,需要浏览器授权的来源再使用 `authorize`。2. 用 `models show` 核对候选模型能力。-3. 用 `routing options` 取得当前选项和 revision,再用 `routing preview/apply` 创建并发布路由;用 `routing list/show` 检查结果。+3. 用 `routing options` 取得当前选项和版本号,再用 `routing preview/apply` 创建并发布路由;用 `routing list/show` 检查结果。4. 用 `agents scan/list/check` 发现本机 Agent,再用 `agents connect preview/apply/status` 接入。恢复时使用 `agents restore preview/apply`,HiRoute 只撤销仍由自己拥有的配置字段。-5. 从 Agent 发起真实请求后,用 `sessions list/show/receipt/status` 查看路由事实和用量,用 `value show` 查看已有价格证据下的价值记录。+5. 从 Agent 发起真实请求后,用 `sessions list/show/receipt/status` 查看实际路由、模型和用量,用 `value show` 查看已有价格证据下的价值记录。-这些不是另一套无界面控制面;CLI 与桌面应用调用相同的 Application、Local Control、存储、发布和恢复路径。+CLI 与桌面应用使用同一份配置和执行记录。两者都需要发布路由后才生效,也遵循相同的配置恢复规则。## 5. 任务委派@@ -122,6 +122,6 @@ hiroute service stop --output jsoncurl -fsSL https://hiroute.ai/install/standalone.py | python3 - uninstall```-卸载范围仅限安装 marker 声明的版本目录、稳定入口、服务定义和管理 Skill,运行数据会保留。删除前会拒绝已被替换的稳定入口、服务定义或 Skill;安装器不会逐个审计版本目录内部的自定义改动,因此不要把自己的文件放进这些目录。+卸载会按安装记录删除对应的程序版本目录、命令入口、服务配置和管理 Skill,保留运行数据。如果命令入口、服务配置或 Skill 已被其他程序替换,安装器会停止删除,避免误删。版本目录会整体移除,请将自己的文件保存在其他位置。下一步阅读 [HiRoute CLI](/docs/cli/) 了解输出、幂等恢复和命令边界,或阅读 [智能模型路由](/docs/model-routing/) 与 [智能任务路由](/docs/task-routing/) 了解产品机制。diff --git a/apps/website/content/guides/model-routing.zh.md b/apps/website/content/guides/model-routing.zh.mdindex d1e53a1d..8f798f81 100644--- a/apps/website/content/guides/model-routing.zh.md+++ b/apps/website/content/guides/model-routing.zh.md@@ -1,8 +1,10 @@# 使用智能模型路由-智能模型路由按已发布配置选择并执行模型。固定模型和免费优先按候选顺序工作;智能省钱和自定义分支通过判断选择模型组,并在每条新用户消息到来时重新判断。对于这两类需要判断的路由,能够识别为同一轮、历史连续且原选择可复用的工具续接沿用冻结决策,让 Agent 连续完成这一轮工作。+智能模型路由让 Agent 使用你配置的一组模型。固定模型和免费优先按候选顺序尝试;智能省钱根据任务复杂度选择省钱或主力模型,自定义分支还会先区分写稿、审稿等任务类别。修改配置后,需要发布才能处理新请求。-下面以桌面应用说明配置。Linux 无界面版通过相同的生产路径提供 `routing options/list/show/preview/apply` 和 `decision services list/apply/test`;先阅读 [Linux 无界面版安装](/docs/install-linux/) 和 [HiRoute CLI](/docs/cli/),请求字段以当前安装返回的 schema 为准。第一次接入可按 [快速开始](/docs/) 创建固定模型路由,随后再配置决策模型。+智能省钱和自定义分支会在每条新用户消息到来时重新判断。同一轮内,Agent 调用工具后继续工作时,通常沿用本轮已经选定的模型组;具体条件见下文“理解本轮选择与失败处理”。++下面以桌面应用说明配置。Linux 无界面版可通过 CLI 的 `routing options/list/show/preview/apply` 和 `decision services list/apply/test` 配置相同功能,具体步骤见 [Linux 无界面版安装](/docs/install-linux/) 和 [HiRoute CLI](/docs/cli/)。请求字段以当前安装返回的 schema(请求和响应的结构说明)为准。第一次接入可按 [快速开始](/docs/) 创建固定模型路由,随后再配置决策模型。## 选择路由类型@@ -11,11 +13,11 @@| 类型 | 适合什么情况 | 行为 || --- | --- | --- || 固定模型 | 需要可预测的候选顺序 | 按顺序尝试候选,跳过能力不满足或暂时不可用的模型 |-| 智能省钱 | 希望简单任务省钱,复杂任务使用主力 | 根据本轮程度判断及适用的上一阶段评分,选择省钱或主力模型组 |+| 智能省钱 | 希望简单任务省钱,复杂任务使用主力 | 根据本轮复杂度判断及适用的上一阶段评分,选择省钱或主力模型组 || 自定义分支 | 写稿、审稿等任务需要不同模型 | 先选择任务类别,再在该分支内选择常规或主力模型组 || 免费优先 | 希望优先使用免费模型 | 按固定顺序尝试免费候选,可选择停止或进入主力兜底 |-“模型 → 通用模型”管理实际执行任务的模型。“模型 → 决策模型”管理用于判断和评分的模型连接,以及自行部署的自定义扩展。决策模型不会代替执行模型回答任务;本期也不支持工具精选。+“模型 → 通用模型”管理实际执行任务的模型。“模型 → 决策模型”管理用于判断和评分的模型连接,以及自行部署的自定义扩展。决策模型负责判断和评分,通用模型负责回答用户、调用工具和完成任务。## 连接决策模型@@ -24,30 +26,30 @@3. 填写 API Key 和连接名称,确认模型名称与完整决策接入点。已有预填可展开修改,未预填则直接填写。4. 选择“保存并测试”,或先“仅保存”,再在详情中选择“测试连接”。-内置决策模型由 HiRoute 提供判断和评分逻辑,不需要另外部署 Jev 服务。+使用内置接入时,HiRoute 直接把判断问题发送给供应商的决策模型,并将结果用于路由。你不需要另外部署 Jev 服务。-“保存并测试”先保存,再测试刚保存的准确连接版本。测试发送固定合成输入,可能消耗供应商额度,不读取真实会话,不执行任务,也不生成质量评分。通过仅说明该版本在这次测试中的连接和必要响应字段可用,不保证任务判断准确或持续健康。测试失败时配置仍可能已保存,按详情中的状态处理。+“保存并测试”会先保存连接,再用固定示例检查它能否返回符合要求的结果。测试可能消耗供应商额度,但不会读取你的真实会话。测试通过表示这次连接可用,实际判断效果仍需通过任务观察。测试失败不代表保存失败,请查看详情中的状态后修改或重试测试。-每次编辑保存都产生一个新版本。路由固定选中的连接版本;例如保存 r2 后,已发布路由仍使用 r1,直到你在路由中选择 r2 并发布更改。仅保存连接或测试连接不会发布路由。从未完成的路由中新增连接,会保留原草稿,返回后仍需主动发布。+每次编辑保存都产生一个新版本。已发布路由继续使用原来选定的版本;例如连接从 r1 更新为 r2 后,需要在路由中选择 r2 并发布更改才会切换。仅保存连接或测试连接不会发布路由。从未完成的路由中新增连接,会保留原草稿,返回后仍需主动发布。-需要自己实现判断和评分时,可在新增菜单中选择“接入自定义扩展”,填写完整接入点并选择认证方式。扩展遵守 [自定义扩展 API](/docs/decision-api/);内置供应商配置和接口映射见 [决策模型接入指南](/docs/decision-extensions/)。可选的 [Jev 自托管参考扩展](/docs/jev-decider/) 提供自行部署的示例。+需要自己实现判断和评分时,可在新增菜单中选择“接入自定义扩展”,填写完整 endpoint(请求地址)并选择认证方式。扩展遵守 [自定义扩展 API](/docs/decision-api/);内置供应商配置和接口映射见 [决策模型接入指南](/docs/decision-extensions/)。可选的 [Jev 自托管参考扩展](/docs/jev-decider/) 提供自行部署的示例。-实际路由判断会把完整当前用户内容及允许的执行历史发送给所选决策连接。历史包括用户内容、已接受的回答、工具名称与顺序、显式粗粒度结果;请求正文不包含系统或开发者提示词、工具参数、工具结果正文和执行模型凭据。上一阶段评价使用该阶段执行时冻结的评分标准;可见历史和评分目标的不完整状态分别保留标记。+实际路由判断会把当前用户的完整输入和保留的执行历史发送给所选决策服务。历史包含用户内容、已接收的模型回答、工具名称、执行顺序,以及协议明确报告的工具状态;不包含系统或开发者提示词、工具参数、工具结果正文和执行模型凭据。上一阶段按执行时保存的标准评分,缺少的历史证据也会标记出来。## 配置智能省钱1. 选择“智能省钱”。“判断方式”默认使用决策模型,选择刚保存的连接版本;也可主动选择“启发式规则”或“自定义扩展”。2. 在“省钱模型”中加入处理要求明确、范围有限任务的模型。-3. 在“主力模型”中加入处理复杂任务或保护低胜任阶段的模型。+3. 在“主力模型”中加入处理复杂任务、或在上一阶段表现不佳时接手的模型。4. 每组用“添加模型”逐个加入候选,调整上下顺序;需要时打开模型的思考设置,应用或取消修改。-首屏只需选择判断方式及两组模型。“判断设置”默认收起,简单概率阈值默认为 **0.8**,胜任度下限默认为 **0.5**。展开后可分别修改简单/复杂的判断要求,以及“如何判断胜任”的评分要求和 0 / 0.5 / 1 三个评分标准。提高简单概率阈值会更谨慎地使用省钱模型;上一阶段的适用完整评分低于胜任下限时,本轮使用主力。+首屏只需选择判断方式及两组模型。“判断设置”默认收起,简单概率阈值默认为 **0.8**,胜任度下限默认为 **0.5**。展开后可分别修改简单/复杂的判断要求,以及“如何判断胜任”的评分要求和 0 / 0.5 / 1 三个评分标准。提高简单概率阈值会更谨慎地使用省钱模型;如果上一阶段的完整评分适用于本轮任务、且低于胜任度下限,本轮会使用主力模型。-简单概率表达本轮任务的程度判断,不是执行模型回答正确的概率。+简单概率表示决策模型认为当前任务符合“简单”条件的可能性。例如返回 0.9,表示它更倾向于判为简单,并不表示执行模型有 90% 的成功率。启发式规则只根据任务特征判断简单或复杂,不产生模型胜任评分,因此不显示概率阈值或评分提示词。切换判断方式再返回,会保留原来的连接及判断设置草稿。@@ -56,33 +58,33 @@选择“自定义分支”,例如分别为写稿和审稿安排模型。默认提供两个分支,可以按需添加:1. 给每个分支填写名称和“任务条件”,如“根据资料起草或改写文章”“审阅现有文章并提出修改意见”。条件描述任务类别;简单和复杂的标准在“判断设置”中填写。-2. 加入“常规模型”。需要两档时,选择“添加主力模型(可选)”并加入候选。只配常规组的分支不判断程度,仍可记录胜任度用于观察。-3. 在计划底部展开“计划默认判断设置”,配置共用的阈值、程度条件与评分标准。+2. 加入“常规模型”。需要两档时,选择“添加主力模型(可选)”并加入候选。只配常规组的分支不判断复杂度,仍可记录胜任度用于观察。+3. 在计划底部展开“计划默认判断设置”,配置共用的阈值、复杂度条件与评分标准。4. 分支默认跟随计划。需要不同标准时,展开该分支的“判断设置”并选择“单独调整”;要重新跟随计划,选择“恢复计划默认”。-“单独调整”复制当前完整有效设置,此后整套独立,包括阈值、程度提示词与胜任标准。“恢复计划默认”清除整套覆盖,立即重新跟随计划,保留分支名称、任务条件和模型。没有主力的分支只展示胜任设置;添加主力后才出现程度设置。+“单独调整”会复制计划当前的阈值、复杂度判断要求和胜任标准;之后修改计划默认设置,不再影响这个分支。“恢复计划默认”会移除这份独立设置,让分支重新跟随计划,同时保留它的名称、任务条件和模型。没有主力的分支只展示胜任设置;添加主力后才出现复杂度设置。-每次只选择一个任务分支。条件重叠时按当前主要意图选择;均不匹配时使用“追问偏好与失败处理”中的默认分支,继续使用该分支的程度判断。写稿低分仍属于写稿阶段,不能因为本轮改为审稿就触发审稿主力。+每次只选择一个任务分支。条件重叠时按当前主要意图选择;均不匹配时使用“追问偏好与失败处理”中的默认分支,继续使用该分支的复杂度判断。写稿低分仍属于写稿阶段,不能因为本轮改为审稿就触发审稿主力。## 理解本轮选择与失败处理在智能省钱和自定义分支中,对于有两组模型的任务,只有本轮简单概率达到阈值、且没有适用低分时,才使用常规或省钱组;否则使用主力。默认值下,简单概率 **0.8** 达标,胜任度 **0.5** 达标,低于 **0.5** 才触发保护。-保护评分必须是本次决策新返回的完整有效评分,绑定上一真实执行阶段,且与本轮任务类别、发布配置和评分标准兼容。缺失、部分证据、跨分支或无法归属的评分不能触发保护;未评分不等于零,旧低分也不会反复生效。+用于低分保护的评分必须由本次决策返回,评价上一实际执行阶段,并有完整证据。上一阶段与本轮还必须使用相同任务类别、发布版本和评分标准。缺失、部分证据、跨分支或无法归属的评分不能触发保护;未评分不等于零,旧低分也不会反复生效。-新用户轮次重新选择,升级后的模型不会锁住后续轮次。本轮仍需按程度和适用评分判断,不会无条件重置为省钱组。“优先保持当前模型”只在本轮选中的模型组内生效。工具续接和重放在能够识别为同一轮、历史连续且冻结决策可复用时继承选择,不重复判断;上下文压缩或历史重建导致消息不连续、原决策无法复用时,会重新判断。+每条新用户消息都会重新选择。上一轮使用主力,不代表以后都用主力;也不会一开始新轮次就自动回到省钱组。“优先保持当前模型”只在本轮选中的模型组内生效。工具续接和重放在能够识别为同一轮、历史连续且冻结决策可复用时继承选择,不重复判断;上下文压缩或历史重建导致消息不连续、原决策无法复用时,会重新判断。-组内候选顺序用于故障接力。常规或省钱组耗尽后,继续同一任务分支的主力组;主力组耗尽后明确失败。直接选中主力时只尝试主力候选,不降回常规或跨任务分支;单组分支在本组耗尽后失败。候选调用失败不等于不胜任,不会因此生成零分。+组内模型按你设置的顺序尝试,这就是故障接力。常规或省钱组都无法使用时,再尝试同一任务分支的主力组;主力组也无法使用时,请求失败。直接选中主力时只尝试主力候选,不降回常规或跨任务分支;单组分支在本组耗尽后失败。候选调用失败不等于不胜任,不会因此生成零分。-若双组分支的任务类别有效但程度结果不可用,使用该分支主力并记录程度判断失败。整体决策失败时,智能省钱使用启发式规则,自定义分支使用默认分支的主力组(只有一组则使用常规组)。+若双组分支的任务类别有效但复杂度结果不可用,使用该分支主力并记录复杂度判断失败。整体决策失败时,智能省钱使用启发式规则,自定义分支使用默认分支的主力组(只有一组则使用常规组)。-所有候选都必须满足请求所需的文本、图片、工具和上下文能力。开始向客户端交付回答后,HiRoute 不会在同一回答中透明换模。+所有候选都必须满足请求所需的文本、图片、工具和上下文能力。开始向客户端交付回答后,HiRoute 不会在同一回答中悄悄换用另一个模型。## 发布并连接 Agent-选择“启用”或“发布更改”,冻结连接版本、任务条件、判断设置、模型顺序及思考配置。无模型、缺连接或非法判断设置会阻止发布;隐藏在收起区域中的问题会展开定位。+选择“启用”或“发布更改”后,HiRoute 会保存本次生效的连接版本、任务条件、判断设置、模型顺序及思考配置。之后编辑草稿不会立即影响正在使用的配置。无模型、缺连接或非法判断设置会阻止发布;隐藏在收起区域中的问题会展开定位。随后在“Agent”页面选择目标 Agent,打开“模型路由”,启用 HiRoute 模型路由,勾选这份计划并选择默认项。保存后,按页面的真实检查或提交一个小任务,验证模型入口。@@ -92,13 +94,13 @@在路由的“模型表现”中,按实际任务分支、模型组、模型及思考设置查看阶段样本和胜任度覆盖。智能省钱按“省钱 / 主力”分组;自定义分支按“写稿 → 常规 / 主力”等实际位置分组。同一模型用于不同组时分别记录。-会话的“模型表现”提供同一批阶段事实,可查看每个阶段的实际模型、胜任度和评分覆盖范围。+会话的“模型表现”展示同一批执行记录,可查看每个阶段的实际模型、胜任度和评分覆盖范围。打开阶段的“查看评分依据”或“阶段详情”,再定位会话证据,依次核对:-- **本轮选择**:任务类别、简单概率、当时阈值、选中组及选择原因;没有程度判断时不适用,失败时不可用,都不能读作零概率。+- **本轮选择**:任务类别、简单概率、当时阈值、选中组及选择原因;没有复杂度判断时不适用,失败时不可用,都不能读作零概率。- **实际执行**:真正调用的模型、思考配置、组内候选位置,以及发生的故障接力。- **后续评价**:后一次决策对这个已执行阶段的评分、当时标准、评分覆盖与完整性;适用低分保护会指向它实际评价的旧阶段。diff --git a/apps/website/content/guides/quickstart.zh.md b/apps/website/content/guides/quickstart.zh.mdindex 0d42e510..782a87d4 100644--- a/apps/website/content/guides/quickstart.zh.md+++ b/apps/website/content/guides/quickstart.zh.md@@ -1,13 +1,13 @@# 快速开始-先选择 macOS 桌面应用或 Linux 无界面版,再用一条固定模型路由完成第一次接入;熟悉基本路径后按需要启用智能省钱或任务委派。开始使用不要求部署外部决策服务。+先安装 macOS 桌面应用或 Linux 无界面版,连接一个模型,再让你的 Agent 通过 HiRoute 完成一次任务。首次使用建议选择固定模型路由,之后再按需要启用智能省钱或任务委派。开始使用不要求部署外部决策服务。## 1. 选择运行方式- **macOS 桌面应用**:要求 macOS 15.0 或更高版本。公开安装包为自签名构建,下载后先核对 SHA256,再按 [macOS 安装与首次启动](/docs/install-macos/) 的说明打开应用。- **Linux 无界面版**:面向服务器、远程工作站和自动化环境,按当前用户安装,不需要 `sudo`。按 [Linux 无界面版安装](/docs/install-linux/) 启动服务并通过 CLI 完成后续配置。-下面第 2–5 步展示桌面应用的可视化路径。Linux 用户在无界面版指南中通过同一套生产能力完成对应流程。无论使用哪种入口,都先确认本机服务已经就绪;模型路由、会话记录和任务执行都依赖它。+下面第 2–5 步展示桌面应用的可视化路径。Linux 用户可按无界面版指南,用 CLI 完成相同配置。无论使用哪种入口,都先确认本机服务已经就绪;模型路由、会话记录和任务执行都依赖它。## 2. 连接一个模型@@ -27,7 +27,7 @@## 4. 连接你的 Agent-打开“Agent”,选择已发现的 Codex 或 Claude Code,然后:+下面以 Codex 为例。打开“Agent”,选择已发现的 Codex,然后:1. 在“模型路由”中选择“启用”。2. 打开“使用 HiRoute 模型路由”。@@ -45,4 +45,4 @@ HiRoute 会保留恢复点。若以后停用模型路由,可以在“连接详- [使用智能模型路由](/docs/model-routing/):配置四种路由类型、决策模型与自定义分支,查看本轮选择、实际执行及后续阶段评价。- [使用智能任务路由](/docs/task-routing/):把适合独立执行的工作委派给执行 Agent。- [Linux 无界面版安装](/docs/install-linux/):从空环境安装并用 CLI 配置模型、路由和 Agent。-- [HiRoute CLI](/docs/cli/):从终端管理 HiRoute、查询运行事实、启动任务并恢复不确定的提交。+- [HiRoute CLI](/docs/cli/):从终端管理 HiRoute、查看执行记录、启动任务,以及在连接中断后确认任务是否已提交。diff --git a/apps/website/content/guides/task-routing.en.md b/apps/website/content/guides/task-routing.en.mdindex 7f34c1a0..283f9dfd 100644--- a/apps/website/content/guides/task-routing.en.md+++ b/apps/website/content/guides/task-routing.en.md@@ -14,14 +14,14 @@ Do not delegate coordination, plan discovery, status checks, waits, or result su1. Open Smart routing and create or edit a plan.2. Under Task delegation, turn on Allow delegation to an execution agent.-3. Choose one execution agent for the plan: Codex CLI or Claude Code. A plan has one executor and no automatic executor fallback.+3. Choose one execution agent for the plan. Current options are Codex CLI, Claude Code, Qoder CLI, Pi and DeepSeek Harness; availability depends on the local installation and dependency checks. A plan has one executor and does not automatically switch to another agent on failure.4. Check the required execution environment when prompted, then publish the plan.A missing installation does not block saving the plan, but the chosen execution agent must pass its dependency check before a task can start. Give the plan a specific name and purpose that describe fitting tasks and expected results, so a main agent can choose it correctly.## Allow a main agent to delegate tasks-Open Agents, choose the Codex or Claude Code installation that will act as the main agent, then open Task routing:+Open Agents, choose your main agent with task-routing support, then open Task routing:1. Enable task routing.2. Choose when to delegate: only when you explicitly ask, or let the Agent decide by default.@@ -36,7 +36,7 @@ After enabling, explicitly mention HiRoute and delegation in the agent's normalIf you choose the default-delegation behavior, the main agent may also select a plan for suitable independent work. Desktop lists accepted work on the Tasks page.-## Use the same production path from Terminal+## Start a task from TerminalAfter installing the [HiRoute CLI](/en/docs/cli/), discover executors and plans:@@ -52,10 +52,19 @@ hiroute worker exec \--plan <PLAN_ID> \--cwd /absolute/path/to/project \--title "Fix the parser regression" \+ --submission-key parser-fix-001 \-- "Find the failure, implement the smallest fix, and run the relevant tests"```-Keep the returned submission key, task ID, and run ID. They recover uncertain submissions and identify the task for status, continuation, or cancellation.+`--submission-key` identifies this submission; use a new value for a new task. Keep it before submitting. After acceptance, also save the returned task ID and run ID for status, continuation or cancellation.++If the connection drops before you know whether the task was accepted, query the original submission key:++```sh+hiroute worker status --submission parser-fix-001 --operation start+```++Do not retry with a new key, which could start a duplicate task. See [HiRoute CLI](/en/docs/cli/) for progress and result commands.## Permission and cancellation boundariesdiff --git a/apps/website/content/guides/task-routing.zh.md b/apps/website/content/guides/task-routing.zh.mdindex fb01b2e1..dc5fe424 100644--- a/apps/website/content/guides/task-routing.zh.md+++ b/apps/website/content/guides/task-routing.zh.md@@ -2,7 +2,7 @@模型路由决定“这一阶段用哪个模型”,任务路由决定“这项工作交给哪个执行 Agent”。两者可以独立启用,也可以组合使用。-下面先展示桌面应用配置路径。Linux 无界面版可以通过 `routing preview/apply` 发布同一份计划,通过 `agents connect preview/apply` 接入 Agent,再使用同一组 Worker 命令执行;具体字段从当前安装的 schema 获取。+下面先展示桌面应用配置路径。Linux 无界面版可以通过 `routing preview/apply` 发布计划,通过 `agents connect preview/apply` 接入 Agent,再使用下文的 `worker` 命令执行任务;请求字段可用 `hiroute schema show` 查询。## 适合委派什么@@ -14,14 +14,14 @@1. 打开“智能路由”,新建或编辑一份计划。2. 在“任务委派”中打开“允许委派任务给执行 Agent”。-3. 为这份计划选择一个执行 Agent:Codex CLI 或 Claude Code。每份计划只选一个,不做自动回退。+3. 为这份计划选择一个执行 Agent。当前支持 Codex CLI、Claude Code、Qoder CLI、Pi 和 DeepSeek Harness;可用性取决于本机安装和依赖检查。每份计划只选一个,执行失败时不会自动改用另一种 Agent。4. 按页面提示检查所需执行环境,然后发布计划。安装缺失不会阻止保存计划,但真正启动任务前必须让所选执行 Agent 通过依赖检查。计划的名称和使用场景应描述适合的任务及预期交付,帮助主 Agent 做出正确选择。## 允许主 Agent 委派任务-打开“Agent”,选择作为主 Agent 的 Codex 或 Claude Code,再打开“任务路由”:+打开“Agent”,选择你日常使用且页面支持任务路由的主 Agent,再打开“任务路由”:1. 启用任务路由。2. 选择委派时机:仅在你明确要求时委派,或默认由 Agent 判断。@@ -36,7 +36,7 @@若配置为默认委派,主 Agent 也可以对适合独立执行的工作主动选择计划。任务记录会显示在桌面应用的“任务”页面。-## 从终端执行同一条生产路径+## 从终端启动任务安装 [HiRoute CLI](/docs/cli/) 后,可以先发现执行器和计划:@@ -52,13 +52,22 @@ hiroute worker exec \--plan <PLAN_ID> \--cwd /absolute/path/to/project \--title "修复解析器回归" \+ --submission-key parser-fix-001 \-- "定位失败、实现最小修复并运行相关测试"```-保存返回的 submission key、task ID 和 run ID。它们用于恢复不确定提交、查看进度、继续或取消任务。+`--submission-key` 用来标识这次提交,新的任务应使用新的值。提交前保留它;任务被接受后,再保存返回的 task ID 和 run ID,用于查询进度、继续或取消。++如果连接中断,无法确定任务是否已被接受,先用原来的提交标识查询:++```sh+hiroute worker status --submission parser-fix-001 --operation start+```++不要换一个提交标识直接重试,以免启动重复任务。更多进度和结果命令见 [HiRoute CLI](/docs/cli/)。## 权限和取消边界-默认 `approve-all` 会让所选 Harness 按其原生能力执行读写、命令和网络操作,不是操作系统沙箱。需要限制时,仅选择页面或 CLI 明确支持的策略;不受支持的限制会在提示发送前失败,而不是静默放宽。+默认权限策略 `approve-all` 允许所选执行 Agent 按自身能力读写文件、执行命令和访问网络;它不提供操作系统级沙箱。需要限制权限时,选择页面或 CLI 为该 Agent 提供的策略。若 Agent 无法执行所要求的限制,HiRoute 会在发送任务前报错,不会自动放宽权限。-取消只停止目标 run,不会撤销它已经写入的文件或产生的外部副作用。并发任务也不会因为使用同一工作目录而自动串行;是否允许重叠执行由调用者决定。+取消只停止指定的这次运行(run),不会撤销已经写入的文件或已完成的外部操作。多个任务使用同一工作目录时仍可能同时执行,请自行避免互相覆盖文件。diff --git a/apps/website/public/scripts/home.js b/apps/website/public/scripts/home.jsindex df21a9bf..5405ef33 100644--- a/apps/website/public/scripts/home.js+++ b/apps/website/public/scripts/home.js@@ -3,7 +3,7 @@ const boundaries = document.documentElement.lang === 'en' ? {continuation: {kicker: 'Tool continuation within one turn',title: 'After a tool returns, continue this turn’s work.',- copy: 'Tool results still belong to the current task. HiRoute inherits this turn’s frozen decision and prefers the eligible current model within its group, helping reuse the prefix. Candidate failures may use bounded failover; a tool result itself does not trigger another judgment.',+ copy: 'Tool results still belong to the current task. HiRoute inherits this turn’s frozen decision and prefers the eligible current model within its group, helping reuse the KV Cache. Candidate failures may use bounded failover; a tool result itself does not trigger another judgment.',assessment: 'Inherit this turn’s frozen task and model-group decision',choice: 'Model A continues with the tool results in this example'},@@ -18,7 +18,7 @@ const boundaries = document.documentElement.lang === 'en' ? {continuation: {kicker: '同一轮中的工具续接',title: '工具返回后,继续本轮工作。',- copy: '工具结果仍属于当前任务,HiRoute 沿用本轮冻结的决策,尽量复用同组内合格的当前模型与前缀。候选故障可以按计划接力,工具返回本身不会重新判断任务。',+ copy: '工具结果仍属于当前任务,HiRoute 沿用本轮冻结的决策,优先使用同组内合格的当前模型,以便复用 KV Cache。候选故障可以按计划接力,工具返回本身不会重新判断任务。',assessment: '沿用本轮已冻结的任务与模型组判断',choice: '示例中模型 A 继续处理工具结果'},diff --git a/apps/website/src/components/HomePage.astro b/apps/website/src/components/HomePage.astroindex b3c9b002..02734aab 100644--- a/apps/website/src/components/HomePage.astro+++ b/apps/website/src/components/HomePage.astro@@ -33,9 +33,9 @@ const releaseKinds = [preferredArtifact && t('macOS 桌面应用', 'macOS Deskto</div><div class="journey-art" aria-label={t('一个长任务中的模型路由示意', 'Model routing across one long task')}><div class="journey-goal"><span>{t('长程任务 · 阶段式模型路由', 'LONG-HORIZON TASKS · STAGE-BASED MODEL ROUTING')}</span><strong>{t('任务持续推进,模型按需选择。', 'One ongoing task. Model choices that adapt.')}</strong></div>- <div class="journey-stage economy"><span class="journey-dot"></span><div><small>{t('阶段 01 · 明确、局部的工作', 'STAGE 01 · BOUNDED WORK')}</small><h3>{t('经济模型,持续推进', 'Economy model, steady progress')}</h3><p>{t('理解问题 → 调用工具 → 验证结果', 'Understand → Use tools → Verify')}</p><div class="prefix-bars" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div><span class="journey-cache">{t('阶段内持续复用前缀', 'Reuse the prefix throughout the stage')}</span></div></div>+ <div class="journey-stage economy"><span class="journey-dot"></span><div><small>{t('阶段 01 · 明确、局部的工作', 'STAGE 01 · BOUNDED WORK')}</small><h3>{t('经济模型,持续推进', 'Economy model, steady progress')}</h3><p>{t('理解问题 → 调用工具 → 验证结果', 'Understand → Use tools → Verify')}</p><div class="prefix-bars" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div><span class="journey-cache">{t('阶段内尽量复用 KV Cache', 'Favor KV Cache reuse within the stage')}</span></div></div><a class="journey-pivot" href="#how"><span>↻</span><div><strong>{t('新用户请求 · 重新判断', 'New user turn · Reassess')}</strong><small>{t('回看执行表现,判断后续工作', 'Assess past performance and the work ahead')}</small></div><b>↗</b></a>- <div class="journey-stage primary"><span class="journey-dot"></span><div><small>{t('阶段 02 · 更深入的推理', 'STAGE 02 · DEEPER REASONING')}</small><h3>{t('主力模型,接续完成', 'Primary model, take it further')}</h3><p>{t('分析难点 → 完成实现 → 检查交付', 'Reason → Implement → Check the result')}</p><div class="prefix-bars" aria-hidden="true"><i></i><i></i><i></i><i></i></div><span class="journey-cache">{t('重建新前缀,随后持续复用', 'Build a new prefix, then keep reusing it')}</span></div></div>+ <div class="journey-stage primary"><span class="journey-dot"></span><div><small>{t('阶段 02 · 更深入的推理', 'STAGE 02 · DEEPER REASONING')}</small><h3>{t('主力模型,接续完成', 'Primary model, take it further')}</h3><p>{t('分析难点 → 完成实现 → 检查交付', 'Reason → Implement → Check the result')}</p><div class="prefix-bars" aria-hidden="true"><i></i><i></i><i></i><i></i></div><span class="journey-cache">{t('切换后建立新的 KV Cache', 'Build a new KV Cache after switching')}</span></div></div><p class="journey-footnote">{t('机制示例 · 重新判断也可以继续原模型', 'Illustration · Reassessment can also keep the same model')}</p></div></section>@@ -47,13 +47,13 @@ const releaseKinds = [preferredArtifact && t('macOS 桌面应用', 'macOS Deskto<div class="timeline-grid"><div class="turn-caption turn-one">{t('用户提出目标 → Agent 自主推进', 'User sets the goal → Agent works autonomously')}<span>{t('同一轮内,工具往返沿用已选决策', 'Tool round-trips inherit the decision within this turn')}</span></div><div class="turn-caption turn-two">{t('用户补充反馈 → 继续推进', 'User feedback → Continue')}<span>{t('新输入带来新的决策机会', 'New input creates another decision point')}</span></div>- <article class="execution-window first-window"><span class="eyebrow">{t('执行轮次 01', 'ROUTING TURN 01')}</span><h3>{t('经济模型 A', 'Economy model A')}</h3><p>{t('处理明确、局部的工作', 'Handles bounded, local work')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-a"><b>{t('A 的前缀持续追加', 'A’s prefix keeps growing')}</b><span>{t('连续工具往返,保持模型稳定', 'Tool round-trips keep the model stable')}</span></div></article>+ <article class="execution-window first-window"><span class="eyebrow">{t('执行轮次 01', 'ROUTING TURN 01')}</span><h3>{t('经济模型 A', 'Economy model A')}</h3><p>{t('处理明确、局部的工作', 'Handles bounded, local work')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-a"><b>{t('尽量复用 A 的 KV Cache', 'Reuse A’s KV Cache when available')}</b><span>{t('连续工具往返,保持模型稳定', 'Tool round-trips keep the model stable')}</span></div></article><button class="decision-boundary compact-boundary" type="button" data-boundary="continuation" aria-pressed="true" aria-controls="boundary-detail"><span class="boundary-symbol" aria-hidden="true">↻</span><strong>{t('工具返回', 'Tool continuation')}</strong><span class="boundary-status">{t('继承决策', 'KEEP DECISION')}</span><small>{t('沿用本轮判断', 'Keep this turn’s choice')}<br>{t('持续推进任务', 'Continue the task')}</small></button>- <article class="execution-window second-window"><span class="eyebrow">{t('轮次 01 · 工具续接', 'TURN 01 · CONTINUATION')}</span><h3>{t('继续使用模型 A', 'Continue with model A')}</h3><p>{t('示例:根据工具结果完成当前工作', 'Example: use tool results to finish the current work')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-a"><b>{t('A 的前缀继续追加', 'A’s prefix keeps growing')}</b><span>{t('同轮续接保持判断,继续复用上下文', 'Keep the decision and reuse the context')}</span></div></article>+ <article class="execution-window second-window"><span class="eyebrow">{t('轮次 01 · 工具续接', 'TURN 01 · CONTINUATION')}</span><h3>{t('继续使用模型 A', 'Continue with model A')}</h3><p>{t('示例:根据工具结果完成当前工作', 'Example: use tool results to finish the current work')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-a"><b>{t('继续复用 A 的 KV Cache', 'Reuse A’s KV Cache when available')}</b><span>{t('同轮续接保持判断,继续复用上下文', 'Keep the decision and reuse the context')}</span></div></article><button class="decision-boundary human-boundary" type="button" data-boundary="human" aria-pressed="false" aria-controls="boundary-detail"><span class="boundary-symbol" aria-hidden="true">+</span><strong>{t('用户补充反馈', 'User feedback')}</strong><span class="boundary-status">{t('重新决策', 'DECIDE AGAIN')}</span><small>{t('新问题或新要求', 'New question or requirement')}<br>{t('也可以继续原模型', 'The same model may continue')}</small></button>- <article class="execution-window third-window"><span class="eyebrow">{t('执行轮次 02', 'ROUTING TURN 02')}</span><h3>{t('转交主力模型 B', 'Hand off to primary B')}</h3><p>{t('示例:新要求需要更深入的推理', 'Example: the new request needs deeper reasoning')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-b"><b>{t('在 B 上建立新前缀', 'Build a new prefix on B')}</b><span>{t('新一轮选定后,同轮继续保持', 'Keep the new decision through this turn')}</span></div></article>+ <article class="execution-window third-window"><span class="eyebrow">{t('执行轮次 02', 'ROUTING TURN 02')}</span><h3>{t('转交主力模型 B', 'Hand off to primary B')}</h3><p>{t('示例:新要求需要更深入的推理', 'Example: the new request needs deeper reasoning')}</p><div class="tool-steps"><span>{t('回答', 'Answer')}</span><i>→</i><span>{t('工具', 'Tools')}</span><i>→</i><span>{t('继续', 'Continue')}</span></div><div class="cache-ribbon cache-b"><b>{t('在 B 上建立 KV Cache', 'Build B’s KV Cache')}</b><span>{t('新一轮选定后,同轮继续保持', 'Keep the new decision through this turn')}</span></div></article></div>- <div class="boundary-detail" id="boundary-detail" aria-live="polite"><div><span class="detail-kicker" id="boundary-kicker">{t('同一轮中的工具续接', 'Tool continuation within one turn')}</span><h3 id="boundary-title">{t('工具返回后,继续本轮工作。', 'After a tool returns, continue this turn’s work.')}</h3><p id="boundary-copy">{t('工具结果仍属于当前任务,HiRoute 沿用本轮冻结的决策,尽量复用同组内合格的当前模型与前缀。候选故障可以按计划接力,工具返回本身不会重新判断任务。', 'Tool results still belong to the current task. HiRoute inherits this turn’s frozen decision and prefers the eligible current model within its group, helping reuse the prefix. Candidate failures may use bounded failover; a tool result itself does not trigger another judgment.')}</p></div><div class="boundary-outcome"><span>{t('这一节点的示例', 'At this point')}</span><p><b>{t('路由判断', 'Routing decision')}</b><span id="boundary-assessment">{t('沿用本轮已冻结的任务与模型组判断', 'Inherit this turn’s frozen task and model-group decision')}</span></p><p><b>{t('模型接续', 'Model execution')}</b><span id="boundary-choice">{t('示例中模型 A 继续处理工具结果', 'Model A continues with the tool results in this example')}</span></p></div></div>+ <div class="boundary-detail" id="boundary-detail" aria-live="polite"><div><span class="detail-kicker" id="boundary-kicker">{t('同一轮中的工具续接', 'Tool continuation within one turn')}</span><h3 id="boundary-title">{t('工具返回后,继续本轮工作。', 'After a tool returns, continue this turn’s work.')}</h3><p id="boundary-copy">{t('工具结果仍属于当前任务,HiRoute 沿用本轮冻结的决策,优先使用同组内合格的当前模型,以便复用 KV Cache。候选故障可以按计划接力,工具返回本身不会重新判断任务。', 'Tool results still belong to the current task. HiRoute inherits this turn’s frozen decision and prefers the eligible current model within its group, helping reuse the KV Cache. Candidate failures may use bounded failover; a tool result itself does not trigger another judgment.')}</p></div><div class="boundary-outcome"><span>{t('这一节点的示例', 'At this point')}</span><p><b>{t('路由判断', 'Routing decision')}</b><span id="boundary-assessment">{t('沿用本轮已冻结的任务与模型组判断', 'Inherit this turn’s frozen task and model-group decision')}</span></p><p><b>{t('模型接续', 'Model execution')}</b><span id="boundary-choice">{t('示例中模型 A 继续处理工具结果', 'Model A continues with the tool results in this example')}</span></p></div></div></section>@@ -103,7 +103,7 @@ const releaseKinds = [preferredArtifact && t('macOS 桌面应用', 'macOS Deskto</section><section class="section wrap faq-section" id="faq"><div class="eyebrow section-label">{t('常见问题', 'Questions')}</div><h2>{t('常见问题', 'Frequently asked questions')}</h2>- <details><summary>{t('模型切换会破坏 KV cache 吗?', 'Does model switching destroy the KV cache?')}</summary><p>{t('不同模型不能共享 KV cache。同轮工具续接沿用决策,并优先复用所选组内合格的当前模型;新用户请求重新判断,也可以继续原模型。实际缓存命中取决于模型服务、配置和缓存生命周期。', 'Different models do not share KV cache. Tool continuations inherit the decision and prefer the eligible current model within the selected group. New user turns decide again and can keep the same model. Cache hits depend on the provider, configuration, and cache lifetime.')}</p></details>+ <details><summary>{t('切换模型会影响 KV Cache 吗?', 'How does model switching affect KV Cache?')}</summary><p>{t('KV Cache 保存模型已计算的注意力键和值,减少处理重复上下文时的计算。不同模型之间无法共享 KV Cache。同轮工具续接优先使用所选组内合格的当前模型,以便复用 KV Cache;新用户请求重新判断,也可以继续原模型。KV Cache 命中率取决于模型服务、配置和有效期。', 'KV Cache stores attention keys and values already computed by a model, reducing computation for repeated context. Different models cannot share this cache. Tool continuations prefer the eligible current model within the selected group to support KV Cache reuse. New user turns decide again and can keep the same model. The KV Cache hit rate depends on the provider, configuration, and cache lifetime.')}</p></details><details><summary>{t('上下文压缩一定会重新选模吗?', 'Does context compaction always trigger a new model choice?')}</summary><p>{t('要看是否仍能识别为同轮续接、此前冻结决策是否可复用。能够继承时保持本轮决策;历史重建使续接关系或决策无法复用时才再次判断。重新判断也可以选择原模型,客户端无需单独上报压缩事件。', 'It depends on whether HiRoute can still recognize the same-turn continuation and reuse the frozen decision. A reusable continuation inherits that decision. If a history rebuild breaks continuity or the decision cannot be reused, HiRoute judges again. The new choice can keep the same model; clients need no separate compaction event.')}</p></details><details id="history-faq"><summary>{t('决策模型能看到哪些执行历史?', 'What execution history can a decision model see?')}</summary><p>{t('HiRoute 提供简化的 Agent 轮次历史:用户问题、接受的回答、工具名称与粗粒度状态。内部任务类别、模型组与执行身份由 HiRoute 绑定,不要求模型猜测。历史被裁剪、淘汰或重启后可能不完整;评分目标阶段的证据完整性单独判断,缺失或部分评分不会视为零分。', 'HiRoute supplies simplified Agent-turn history: user input, accepted output, tool names, and coarse outcomes. HiRoute binds internal task categories, groups, and execution identities itself. Trimming, eviction, or restart may leave history incomplete; completeness of the assessed stage is tracked separately. Missing or partial assessments are not zero scores.')}</p></details><details><summary>{t('一定要部署 Jev 吗?', 'Must I deploy Jev?')}</summary><p>{t('不需要。在模型 → 决策模型中连接百炼、OpenRouter Jev、TypeSafe 或兼容接入点,就能使用内置判断。智能省钱也支持启发式规则;需要自有处理逻辑时才选择自定义扩展。', 'No. Connect Bailian, OpenRouter Jev, TypeSafe, or a compatible endpoint in Models → Decision models to use built-in judgment. Smart saving also supports heuristic rules. Choose a custom extension when you need your own processing logic.')}</p></details>diff --git a/apps/website/src/lib/decision-docs.mjs b/apps/website/src/lib/decision-docs.mjsindex 5deb1990..b09ef49e 100644--- a/apps/website/src/lib/decision-docs.mjs+++ b/apps/website/src/lib/decision-docs.mjs@@ -27,6 +27,8 @@ const maps = {api: {'README.md': '/en/docs/decision-api/', 'README.zh-CN.md': '/docs/decision-api/','../README.md': '/en/docs/decision-extensions/', '../README.zh-CN.md': '/docs/decision-extensions/',+ '../extensions/jev-decider/README.md': '/en/docs/jev-decider/',+ '../extensions/jev-decider/README.zh-CN.md': '/docs/jev-decider/','decision.openapi.json': '/api/decision.openapi.json','decision-examples.json': '/api/decision-examples.json','decision-design.md': sourceLink('decision-extensions/api/decision-design.md'),diff --git a/decision-extensions/README.md b/decision-extensions/README.mdindex 3c2249fb..9e48be7e 100644--- a/decision-extensions/README.md+++ b/decision-extensions/README.md@@ -55,8 +55,10 @@ simple probability meets the threshold (default **0.8**) and there is no applicacomplete score below the competence floor (default **0.5**). Otherwise HiRouteselects primary models. Low-score protection uses only a fresh score for thepreceding actual stage with the same category, published plan version and assessment-standard. Missing or partial evidence is unrated, not zero; a saved old score does-not become a fresh low score on later turns. A writing score does not upgrade a review task.+standard. Missing assessments remain unscored; assessments based on partial evidence+retain that marker and are excluded from averages. Neither is treated as zero or+triggers low-score protection. A saved old score does not become a fresh low score+on later turns. A writing score does not upgrade a review task.Each new user message is decided again and may choose either group. Toolcontinuations and same-turn replay reuse the frozen decision only when HiRoute candiff --git a/decision-extensions/README.zh-CN.md b/decision-extensions/README.zh-CN.mdindex 7b18a7f5..561cbd57 100644--- a/decision-extensions/README.zh-CN.md+++ b/decision-extensions/README.zh-CN.md@@ -2,7 +2,7 @@[English](README.md) · [自定义扩展 API](api/README.zh-CN.md) · [官方 Jev 扩展](extensions/jev-decider/README.zh-CN.md)-HiRoute 使用决策模型为当前任务选择执行模型,并在证据充分时评价上一实际执行阶段。你配置任务条件和模型组,HiRoute 在每条新用户消息到达时应用这些设置。+决策模型回答“当前任务属于哪一类、需要多强的处理能力”,执行模型负责真正完成任务。你在路由计划中配置判断条件和模型组,HiRoute 根据决策结果选择模型,并在之后的决策中评价上一阶段的执行表现。## 接入决策模型@@ -19,46 +19,46 @@ HiRoute 使用决策模型为当前任务选择执行模型,并在证据充分| 模式 | 决策模型判断什么 | 执行模型 || --- | --- | --- |-| 智能省钱 | 当前任务是简单还是复杂 | 省钱组、主力组 |-| 自定义分支 | 当前任务属于哪类;有两组模型时再判断类内程度 | 每类常规模型,可选主力模型 |+| 智能省钱 | 当前任务符合简单或复杂条件的概率 | 省钱组、主力组 |+| 自定义分支 | 当前任务属于哪类;有两组模型时再判断该类别内的复杂度 | 每类常规模型,可选主力模型 |-任务类别、处理程度和胜任度回答三个不同问题:+任务类别、复杂度和胜任度回答三个不同问题:| 问题 | 例子 | 作用 || --- | --- | --- || 当前做什么? | 写稿或审稿 | 选择一个任务分支 |-| 这项工作需要什么程度? | 局部措辞修改或全篇论证核查 | 在该分支内选择模型组 |+| 这项工作有多复杂? | 局部措辞修改或全篇论证核查 | 在该分支内选择模型组 || 上一阶段做得如何? | 稿件结构可用,但有未经证实的论断 | 记录胜任情况,适用时保护性使用主力模型 |-自定义条件重叠时按当前请求的主要意图选择;没有匹配时使用配置的默认分支。只有常规模型的类别不判断程度,但仍可记录胜任度。智能省钱只有一个任务范围,不把简单和复杂建成两个任务分支。+自定义条件重叠时按当前请求的主要意图选择;没有匹配时使用配置的默认分支。只有常规模型的类别不判断复杂度,但仍可记录胜任度。智能省钱只有一个任务范围,不把简单和复杂建成两个任务分支。## HiRoute 如何选择和执行模型-有两组模型时,本次简单概率达到阈值(默认 **0.8**),且没有本次适用的完整低分,才选择常规或省钱组;否则选择主力组。胜任下限默认 **0.5**。低分保护只接受上一实际阶段的本次新评分,且要求类别、已发布计划版本和评分标准一致。缺失或部分证据保持未评分,不能视为零分;已保存的旧评分不会在后续轮次反复作为新低分。写稿评分不能使审稿任务升级。+有两组模型时,本次简单概率达到阈值(默认 **0.8**),且没有本次适用的完整低分,才选择常规或省钱组;否则选择主力组。胜任度下限默认 **0.5**。低分保护只接受上一实际阶段的本次新评分,且要求类别、已发布计划版本和评分标准一致。没有评分时保持未评分;只有部分证据的评分会保留相应标记。两者都不能当成零分或触发低分保护,部分评分也不计入平均分。已保存的旧评分不会在后续轮次反复作为新低分。写稿评分不能使审稿任务升级。每条新用户消息都重新决策,可能选择常规,也可能选择主力。工具续接和同轮重放只有在 HiRoute 可识别为同轮且冻结决策可复用时,才继承该决策;历史重建不连续或决策无法继承时仍会重新判断。“优先保持当前模型”只在新选中的组内合格候选中生效。HiRoute 按顺序尝试选中组的候选。常规或省钱组耗尽后,可以接力同类别的主力组;主力组耗尽即失败。直接选择主力时只在该组内接力;单组类别在本组耗尽后失败。候选不可用不会生成胜任度评分。-类别有效但程度结果不可用时,HiRoute 使用该类别的主力组。整体决策失败时,智能省钱使用启发式规则;自定义分支使用默认类别,有主力组则优先使用主力。+类别有效但复杂度结果不可用时,HiRoute 使用该类别的主力组。整体决策失败时,智能省钱使用启发式规则;自定义分支使用默认类别,有主力组则优先使用主力。## 调整判断设置和查看结果-高级判断设置默认收起。展开后可编辑简单/复杂条件、阈值、胜任评分要求,以及 **0 / 0.5 / 1** 三个评分锚点。类别条件描述任务意图,程度条件描述该类别内的工作要求,胜任标准评价已经发生的工作。+高级判断设置默认收起。展开后可编辑简单/复杂条件、阈值、胜任评分要求,以及 **0 / 0.5 / 1** 三个评分锚点。类别条件描述任务意图,复杂度条件描述该类别内的工作要求,胜任标准评价已经发生的工作。-自定义类别默认跟随计划判断设置。“单独调整”复制完整设置,之后独立生效;“恢复计划默认”重新跟随计划。智能省钱还可显式选择启发式规则,规则不会产生模型胜任评分。+自定义类别默认跟随计划判断设置。“单独调整”会复制当前完整设置,此后修改计划默认设置不再影响该类别;“恢复计划默认”会移除这份独立设置,让类别重新跟随计划。智能省钱还可显式选择启发式规则,规则不会产生模型胜任评分。-发布后,任务定义、连接版本和评分标准被冻结。会话与计划视图展示本轮为什么选择这个组、实际由哪个组和模型执行,以及该阶段后来获得的评分。后续评分和草稿修改不能改写过去的选择原因。+发布后,HiRoute 保存本次生效的任务定义、连接版本和评分标准;修改草稿不会立即改变已发布配置。会话与计划视图展示本轮为什么选择这个组、实际由哪个组和模型执行,以及该阶段后来获得的评分。后续评分和草稿修改不能改写过去的选择原因。## 内置接入与自定义扩展的职责| 职责 | 负责方 || --- | --- || 任务定义、胜任标准、阈值与模型组 | HiRoute,使用已发布计划 |-| 模型选择、资格检查、可用性接力与实际阶段观测 | HiRoute |-| 内置连接的 System One 供应商调用和答案映射 | HiRoute 的[内置适配器](api/system-one-design.md) |-| 自定义连接的供应商调用、答案映射和必要历史裁剪 | 自定义扩展,遵守传入的定义和标准 |+| 模型选择、资格检查、故障接力与执行记录 | HiRoute |+| 内置连接的 System One 供应商调用和结果转换 | HiRoute 的[内置适配器](api/system-one-design.md) |+| 自定义连接的供应商调用、结果转换和必要历史裁剪 | 自定义扩展,遵守传入的定义和标准 |-[自定义扩展 API](api/README.zh-CN.md)可在一次调用中返回当前决策和上一阶段评分。当前 **v1** 只有一种请求结构,[规范示例](api/decision-examples.json)和 [OpenAPI](api/decision.openapi.json)描述这一边界。完整当前输入保持不变,评分目标的证据缺失必须标记为部分证据。具体配置方式见[路由指南](../docs/smart-saving-model-classification.zh-CN.md)。+[自定义扩展 API](api/README.zh-CN.md)可在一次调用中返回当前决策和上一阶段评分。当前 **v1** 只有一种请求结构,[规范示例](api/decision-examples.json)和 [OpenAPI](api/decision.openapi.json)描述这一边界。当前用户输入会完整传入;如果要评分的阶段缺少执行证据,评分必须带上部分证据标记。具体配置方式见[路由指南](../docs/smart-saving-model-classification.zh-CN.md)。-工具精选仅保留未来协议设计,目前没有运行时支持或产品入口。+当前扩展 API 支持 `ordinal`(复杂度概率)和 `categorical`(任务类别及可选的类内复杂度)。`assessment` 单独评价上一阶段;这些字段与枚举值在请求、响应中都保留原文。设计中的 `subset` 工具精选尚未实现。diff --git a/decision-extensions/api/README.md b/decision-extensions/api/README.mdindex 1f8c0c6d..f6b89c34 100644--- a/decision-extensions/api/README.md+++ b/decision-extensions/api/README.md@@ -2,75 +2,61 @@[简体中文](README.zh-CN.md) · [Decision models and routing mechanism](../README.md) · [Download OpenAPI 3.1](decision.openapi.json)-Use this API to implement an HTTP decision extension for HiRoute. Built-in decision-models call the provider's System One API directly using a different request shape;-see the [provider mapping](system-one-design.md). Deploying an extension is optional.+A custom extension is an **HTTP decision service that you deploy**. HiRoute sends it the current task, decision criteria and available history. The service returns a task category or complexity probabilities, optionally assessing the preceding execution stage. HiRoute then applies the routing plan, selects a model and calls that model to carry out the user's task.-HiRoute sends one `POST` to the complete endpoint saved for the custom connection.-The official extension serves **`POST /v1/decisions`**; HiRoute does not append a path.-One call can judge the current task and assess the preceding actual execution stage.-The extension follows the supplied definitions and frozen assessment standard;-HiRoute owns thresholds, model groups, candidate selection and availability relay.+This guide covers connecting a service, handling requests and returning results. You can deploy the [official Jev extension](../extensions/jev-decider/README.md), or implement the same interface with another decision model, an LLM or your own rules.-## Request contract+## Where an extension fits-The request has exactly five top-level fields:+```text+Published routing plan: task criteria, assessment rubric, thresholds and model groups+ → HiRoute sends: definition + current input + visible history + assessment target+ → Your HTTP extension returns: decision + optional assessment+ → HiRoute applies thresholds and competence protection, then selects a model group+ → Execution model handles the task; its recorded work informs later decisions+```-| Field | Meaning |+The extension turns the supplied questions into judgments. It controls provider calls, prompt construction or rule evaluation, along with any upstream credentials and response conversion. Definitions and assessment criteria arrive with each request. Following them allows one service to handle different routing plans.++| Configuration or behavior | Owner || --- | --- |-| `decision` | An ordinal degree definition or a categorical task definition with optional degree refinements |-| `latest_user` | The complete current user content parts; repeated text is allowed |-| `visible_conversation` | Retained sealed execution turns in original order: `{user,status,steps}` |-| `history_partial` | Whether HiRoute knows of a gap in the visible history |-| `assessment_target` | `null`, or `{from,instructions,criteria}` for one preceding actual stage |--An **ordinal** definition contains `kind`, `instructions` and ordered-`levels:[{id,criterion}]`. Its level IDs are unique; their order represents increasing-degree. HiRoute's current routing uses two levels, `simple` and `complex`.--A **categorical** definition contains `kind`, `instructions` and-`options:[{id,criterion,refinement?}]`. Custom routing has 2–16 task categories.-Each category with primary models has an ordinal `refinement`; a category with-only regular models omits it. Choose by the current request's main intent using-the supplied conditions, including its overlap and default-category rules.-Category conditions describe what the task is; degree conditions describe the-work required within that category.--Instructions and criteria are non-empty text with **no per-field character quota**.-IDs and the surrounding structures retain the constraints in the OpenAPI.-Overall transport budgets and provider context limits still apply; they do not-permit silently truncating conditions or assessment standards.--### Visible history and the assessment target--A history turn has `user` content parts, a `status` of `completed`, `failed`,-`interrupted` or `unknown`, and `steps`, an array of content-part arrays. Each step-represents one business-model request. Parts contain accepted text, tool names with-explicit coarse status, or unavailable-content markers. HiRoute omits credentials,-system/developer instructions, tool arguments and tool-result bodies.--`assessment_target.from` is a zero-based index in `visible_conversation`. The-suffix from that index through the end belongs to one actual preceding stage.-`instructions` and the three `{score,criterion}` anchors, ordered **0, 0.5, 1**,-are frozen for that stage. Use them rather than deployment-specific scoring rules.-HiRoute binds the score to the actual stage locally; the extension does not return-internal model or execution identifiers.--`history_partial` describes gaps in the whole visible history. Assessment `partial`-describes missing evidence within the target stage. An uncaptured earlier prefix-alone does not make a later fully captured target stage partial. If the target is-`null`, omit assessment. Repeated user text, a summary or a continuation is not by-itself evidence of failure.--## Complete examples--These are illustrative requests and responses from the-[canonical examples](decision-examples.json), not measured provider results.-The same JSON is used in both language guides to keep sample IDs and criteria aligned.--### Smart saving: first decision, no assessment--Request:+| Task categories, complexity criteria and assessment rubric | HiRoute, from the published plan |+| Computing a category, complexity probabilities and optional assessment | The extension |+| Thresholds, execution-model lists, eligibility checks and failover | HiRoute |+| Attributing assessments to actual execution stages and storing observations | HiRoute |++The response contains judgments. HiRoute manages execution-model IDs, model groups and candidate ordering; these are not extension response fields. The extension does not take over execution of the user's task.++**Built-in connections and custom extensions use different interfaces.** With a built-in decision model, HiRoute calls the provider's System One API directly. A custom extension receives the HTTP JSON request documented here. The [System One mapping](system-one-design.md) is relevant inside an extension that uses a compatible provider such as Jev. Your service can use a different upstream protocol.++## Connect a service++1. Implement an HTTP `POST` endpoint accepting JSON, or deploy the [official Jev extension](../extensions/jev-decider/README.md). Its path is `/v1/decisions`; a custom service may use another path.+2. Under **Models → Decision models**, open the add menu and choose **Connect custom extension**. Enter the complete endpoint, connection timeout and optional authentication header name and full value.+3. Save and test the connection. The test checks transport and required response fields; use representative tasks to evaluate decision quality.+4. Select the saved connection in a routing plan, configure task criteria and model groups, and publish. After editing a connection or draft, select the intended connection revision and republish to apply it.++HiRoute posts to the **complete configured endpoint** without appending a path. For example, `http://127.0.0.1:8080/v1/decisions` must point to the extension. For a remote deployment, use an address reachable from HiRoute. Configure the extension's upstream provider URL inside the extension.++## Two decision kinds and a separate assessment++Field names, `kind` values and status values are literal protocol identifiers. The current `decision.kind` values are `ordinal` and `categorical`:++| Structure | Question it answers | Extension output |+| --- | --- | --- |+| `ordinal` | How demanding is the current task? | `probabilities`: a complete distribution over the requested level IDs; current model routing uses `simple` and `complex` |+| `categorical` | What kind of task is this, such as writing or reviewing? | `choice`: one allowed option ID, plus its `ordinal` result if that option defines a `refinement` |+| `assessment` | How well was the preceding execution stage handled? | An optional object with required `score` and `partial`, plus optional `reason`; a separate response field, not a `decision.kind` |++A `refinement` is a further judgment within the chosen category. In current routing it measures that category's task complexity; return only the chosen category's result. IDs such as `simple`, `complex`, `writing` and `review` must exactly match the request. Do not translate or rename them. Instructions, criteria, user text and assessment reasons are natural-language content and may be written in any language.++## Minimal example: judge task complexity++The payloads below come from the [canonical examples](decision-examples.json). Numbers are illustrative. Both language editions use the same payloads; the Chinese instructions and user messages are valid example input, not protocol identifiers.++Smart saving submits one `ordinal` definition. The first request has no previous stage to assess, so `assessment_target` is `null`.++Request (save as `request.json`):```json{@@ -100,7 +86,15 @@ Request:}```-Response:+Send it to the running service. Include the configured authentication header if enabled:++```sh+curl --fail-with-body 'http://127.0.0.1:8080/v1/decisions' \+ --header 'Content-Type: application/json' \+ --data-binary @request.json+```++Return HTTP `200`, `Content-Type: application/json` and this response:```json{@@ -114,12 +108,57 @@ Response:}```-There is no prior stage: `assessment_target` is `null`, and the response has no-`assessment`. With the default threshold, this distribution selects economy models.+The extension reports a **0.93** probability for `simple`. HiRoute compares it with the plan's threshold, **0.8** by default. With no competence protection applying here, HiRoute selects the economy group. The extension does not return a group or model ID. Omit `assessment` when there is no assessment target.++## Request fields++All five top-level fields are required. Use `[]` for empty history and `null` for an absent assessment target:++| Field | Meaning |+| --- | --- |+| `decision` | The current `ordinal` or `categorical` definition, including criteria and allowed IDs |+| `latest_user` | Complete, non-empty user content parts from the current request; repeated text is allowed |+| `visible_conversation` | Retained, closed execution turns in their original order; each item is `{user,status,steps}` |+| `history_partial` | Whether HiRoute knows of a gap anywhere in the visible history |+| `assessment_target` | `null`, or `{from,instructions,criteria}` identifying the preceding actual stage to assess |++### decision definitions++- **`ordinal`** contains `kind: "ordinal"`, `instructions` and `levels: [{id,criterion}]`. IDs are unique, with levels ordered from lowest to highest. The protocol allows multiple levels; current HiRoute model routing produces `simple` and `complex`.+- **`categorical`** contains `kind: "categorical"`, `instructions` and `options: [{id,criterion,refinement?}]`. Custom routing supplies 2–16 categories. Select one by the current task's main intent, following the supplied overlap and default-category rules.+- **`refinement`** is an optional nested `ordinal` definition. A category with a primary model group includes it; a category with only regular models omits it. Category criteria describe the type of task, while refinement criteria describe its complexity within that category.++`instructions` and `criterion` are non-empty text with no per-field character quota. See the [OpenAPI](decision.openapi.json) for ID, array-length and other structural constraints. Overall transport and upstream context limits still apply; they do not permit silently truncating decision criteria or assessment rubrics.++### visible_conversation: execution history++Each turn contains its original `user` content, `status` and `steps`. One step represents one execution-model request, so `steps` is an array of content-part arrays.-### Writing and review: category, selected degree and prior-stage score+| Location | Supported values or content |+| --- | --- |+| Turn `status` | `completed`, `failed`, `interrupted`, `unknown` |+| Content parts in `user` and `latest_user` | `text`, or `unavailable` with a `source_kind` identifying the missing content type |+| Content parts in `steps` | `text`, `unavailable`, or `tool_activity` with a tool name in `tool` and a coarse `status` |+| Tool `status` | `completed`, `failed`, `unknown` |++`unknown` means there is no explicit terminal outcome; it does not establish success or failure. Tool status comes from explicit protocol facts. History excludes credentials, system/developer instructions, tool arguments and tool-result bodies.++### assessment_target: which work to assess++`assessment_target.from` is a zero-based index into `visible_conversation`. The suffix starting at that index belongs to one actual execution stage. For example, in a three-item history, `from: 1` targets only the last two items. The new task, which has not executed yet, is outside this target.++`instructions` and `criteria` contain the rubric frozen when that stage executed. The three `{score,criterion}` anchors are **0, 0.5 and 1**, in that order. The returned `score` may be any finite number in `[0,1]`, not just an anchor value. HiRoute retains the target's model and stage identity locally; the extension need not infer or echo it.++`history_partial` describes the whole visible history; `assessment.partial` concerns missing evidence within the target stage. A missing earlier prefix does not make an otherwise complete target partial. Return `partial: true` if the extension trims target evidence; omit assessment if it removes the entire target. Repeated user text, summaries or continuation messages do not by themselves establish failure.++## categorical examples: category and task complexity++### Select reviewing while assessing earlier writing-Request:+The request defines `writing` and `review`, each with its own `refinement`. The current task asks for a review, while the assessment target refers to the preceding writing stage.++<details>+<summary>Full request: two categories, their refinements and a historical assessment target</summary>```json{@@ -212,6 +251,8 @@ Request:}```+</details>+Response:```json@@ -235,14 +276,14 @@ Response:}```-The current task selects `review`; only review's degree appears in the response.-The score **0.35** belongs to the previous **writing** stage. It does not evaluate-review work that has not happened and does not apply writing's low-score protection-to the review category. HiRoute uses review's current degree to select its group.+`choice: "review"` selects reviewing, and `refinement` describes only the current review's complexity. Its `P(simple) = 0.28` is below the default threshold, so HiRoute selects the review category's primary group. The **0.35** assessment belongs to the earlier **writing** stage. A low writing score cannot trigger competence protection for reviewing.-### A category with only regular models+### Select a category with one model group-Request:+A plan can mix categories with one or two model groups. Here, `writing` still has a `refinement`, while `review` has only regular models and omits it.++<details>+<summary>Full request: writing has a refinement; review does not</summary>```json{@@ -286,7 +327,9 @@ Request:}```-Response:+</details>++The response only needs to select `review`:```json{@@ -297,76 +340,46 @@ Response:}```-The review option has no `refinement`, so its response omits `refinement` too.-HiRoute uses that category's regular group. The writing option can still have two-groups; this does not require degree evaluation for review. A later request can-also assess the single-group category's preceding stage.--## Response validation--Return HTTP **200** and one strict JSON object, at most **64 KiB**. Markdown,-duplicate or unknown fields, and native provider envelopes are invalid.--An ordinal result returns the exact requested level IDs and finite probabilities-in `[0,1]`, covering every level and summing to one within `1e-6`. HiRoute validates-and normalizes this permitted floating-point error. A categorical result returns-an allowed `choice` and only that option's defined `refinement`, when present.-The extension cannot return model IDs, candidate order or routing thresholds.--Optional `assessment` contains a finite `score` in `[0,1]`, required `partial`,-and an optional `reason` of 1–1024 Unicode scalars. Preserve a valid zero score.-Missing, invalid or partial assessment is not zero and cannot drive low-score-protection. Omission does not delete saved observations; an old score is not reused-as a fresh assessment.--An invalid category invalidates the decision. A valid category with an invalid-selected degree remains selected, and HiRoute uses its primary group while-recording degree as unavailable. An invalid optional assessment is discarded-independently of a valid current decision. Errors in unselected upstream degree-answers must not invalidate the selected path.--## How HiRoute consumes the result--For a category with two groups, HiRoute selects regular/economy models when the-current `P(simple)` is at or above the configured threshold (default **0.8**) and-there is no applicable fresh score below the competence floor (default **0.5**).-Otherwise it selects primary. Protection requires a complete valid score for one-actual preceding stage with the same category, published plan version and rubric.-A single-group category records competence without an upgrade group.--Each new user message decides again; it can select either group. Tool continuations-and same-turn replay reuse the frozen decision only when HiRoute can recognize the-same turn and that decision remains reusable. Discontinuous reconstructed history-or a decision that cannot be inherited requires a new judgment. Availability relay-follows regular → same-category primary → failure, or stays within primary when that-group was selected directly. A candidate failure does not manufacture a competence score.--A whole decision failure uses heuristic smart saving or the custom plan's default-category, preferring its primary group when configured. Source cancellation,-source deadline and current-input integrity failures terminate the request.--## Provider integration and request limits--The extension owns its provider integration and context preparation. Preserve the-complete current user input. To fit provider limits, remove only the oldest whole-history turns and adjust the retained target index. If trimming removes target-evidence, return `partial:true`; if it removes the whole target, omit assessment.-HiRoute also accounts for target evidence it knows is missing; the extension's-`partial:false` cannot override those facts.--The built-in adapter bounds the complete provider request, including questions and-state, to **256 KiB**. The official Jev extension defaults to the same budget and-allows deployment configuration. This is a byte allocation budget, not a token-count or a replacement for provider context limits. If current input and questions-alone exceed the budget, reject the request instead of truncating them.-Business-model context remains the routing plan's setting.--HiRoute's total deadline covers preparation, credential access, connection and-response reading. The production transport makes one call with no automatic-background retry and does not follow redirects. Configure the extension's own-budget to fit within the HiRoute connection timeout.--The [protocol design](decision-design.md) describes the current v1 boundary;-the [System One mapping](system-one-design.md) describes provider Choice/Score calls.-Tool subset selection remains future documentation only and is not supported by-current routing or the extension API runtime.+HiRoute uses the review category's regular group. The extension does not invent complexity probabilities for that category. A later request can still assess its completed execution stage.++## Response rules and error handling++Return HTTP **200** and one JSON object, at most **64 KiB**. Do not wrap it in Markdown or a native provider response, or add duplicate or unknown fields.++| Field | Requirement |+| --- | --- |+| `decision.kind` | Must match the request |+| `decision.probabilities` | For `ordinal`: exactly the requested level IDs; every value finite and in `[0,1]`, with the sum within `1e-6` of 1; HiRoute normalizes this permitted floating-point error |+| `decision.choice` | For `categorical`: one exact ID from the request's `options` |+| `decision.refinement` | The selected option's defined `ordinal` result; omit when that option has no refinement |+| `assessment` | Optional; finite `score` in `[0,1]`, required `partial`, and optional `reason` of 1–1024 Unicode scalars |++Omit `assessment` when `assessment_target` is `null`. Preserve a valid zero score; an absent score is not zero and does not delete saved observations.++| Condition | HiRoute behavior |+| --- | --- |+| `choice` outside the allowed set, or an invalid overall response | Decision failure; use the plan fallback described below |+| Missing or invalid smart-saving `ordinal` probabilities | Use primary and record complexity as unavailable |+| Valid category but missing or invalid required `refinement` | Keep the category, use its primary group and record complexity as unavailable |+| Missing, invalid or untargeted optional assessment | Do not use that assessment; a valid current decision remains usable |+| Assessment with `partial: true` | Record partial evidence; do not trigger competence protection |++If your upstream answers complexity questions for several categories at once, convert only the selected category's answer. An invalid unselected answer must not discard a valid selected path.++## How HiRoute acts on the result++For a category with two groups, HiRoute selects regular/economy models when the current `P(simple)` reaches the configured threshold (default **0.8**) and no applicable fresh score is below the competence floor (default **0.5**). Otherwise it selects primary. Protection requires a complete valid assessment of the actual preceding stage, matching the current category, published plan version and rubric. Saved scores are not reused as new low scores on later requests. A single-group category records competence without a primary group to upgrade to.++Each new user message triggers a fresh decision. Recognized tool continuations and same-turn replay inherit a frozen decision while it remains reusable; discontinuous history or a decision that cannot be inherited triggers another call. The extension should process each request without requiring the user text to change.++HiRoute tries eligible models in the selected group in order. Exhausting regular models can lead to the same category's primary group; selecting primary directly stays within that group. Candidate failures do not create zero competence scores. A whole decision failure uses heuristic rules for smart saving, or the custom plan's default category with its primary group when available.++## Context, timeouts and call boundaries++The extension owns upstream integration and context preparation. Preserve the complete current user input, decision criteria and assessment rubric. If trimming is necessary, remove the oldest whole history turns first and adjust the target index passed upstream. Determine assessment coverage from the actual target range. HiRoute also includes target gaps it knows about; an extension's `partial: false` cannot override them.++The official Jev extension defaults to a **256 KiB** complete provider-request budget, configurable at deployment. HiRoute's built-in adapter also uses 256 KiB. This is a byte budget for the provider request, not a token or context limit imposed on every custom implementation by this API. If the current input and questions alone do not fit, reject the request instead of truncating them. The routing plan still controls the execution model's context.++HiRoute makes one production call to the extension, with no automatic background retries or redirects. Its total deadline includes preparation, credential access, connection and response reading. Keep the extension's own budget below the HiRoute connection timeout. Extension outages and request failures use the decision fallback above; source cancellation, source deadline or current-input integrity errors terminate the request.++See the [OpenAPI](decision.openapi.json) for exact types, the [canonical examples](decision-examples.json) for reusable payloads, and the [protocol design](decision-design.md) for background. The current runtime supports `ordinal` and `categorical`; the documented `subset` tool-selection design is not yet implemented.diff --git a/decision-extensions/api/README.zh-CN.md b/decision-extensions/api/README.zh-CN.mdindex 686bc5b6..302afcee 100644--- a/decision-extensions/api/README.zh-CN.md+++ b/decision-extensions/api/README.zh-CN.md@@ -2,43 +2,61 @@[English](README.md) · [决策模型与路由机制](../README.zh-CN.md) · [下载 OpenAPI 3.1](decision.openapi.json)-本 API 用于实现 HiRoute 的 HTTP 决策扩展。内置决策模型直接调用供应商的 System One API,请求结构不同,见[供应商映射](system-one-design.md)。部署扩展是可选项。+自定义扩展是你部署的 **HTTP 决策服务**。HiRoute 把当前任务、判断条件和可见历史发给它;服务返回任务分类或复杂度概率,并可同时评价上一执行阶段。HiRoute 根据这些结果和路由计划选择模型,再调用模型完成用户任务。-HiRoute 向自定义连接中保存的完整接入点发送一次 `POST`,不会自行追加路径。官方扩展提供 **`POST /v1/decisions`**。一次调用可以判断当前任务,同时评估上一实际执行阶段。扩展遵守传入的定义和冻结评分标准;HiRoute 负责阈值、模型组、候选选择与可用性接力。+本文面向扩展开发者,说明如何接入服务、处理请求和返回结果。可以直接部署[官方 Jev 扩展](../extensions/jev-decider/README.zh-CN.md),也可以用其他决策模型、LLM 或自有规则实现同一接口。-## 请求契约+## 扩展在路由中做什么-顶层恰有五个字段:+```text+已发布的路由计划:任务条件、评分标准、阈值和模型组+ → HiRoute 发出决策请求:定义 + 当前输入 + 可见历史 + 评分目标+ → 你的 HTTP 扩展:执行判断,返回 decision 和可选 assessment+ → HiRoute:应用阈值和低分保护,选择类别内的模型组+ → 执行模型:处理用户任务;执行记录供之后的决策参考+```-| 字段 | 含义 |+扩展负责把请求中的问题变成判断结果。如何调用上游、组织提示词或执行规则由扩展实现;如果使用上游供应商,其凭证和响应转换也由扩展管理。判断条件和评分标准随每次请求传入,服务必须遵守它们,才能让同一个服务用于不同路由计划。++| 配置或行为 | 负责方 || --- | --- |-| `decision` | 有序程度定义,或任务类别及可选程度定义 |-| `latest_user` | 完整当前用户内容,允许与先前文本重复 |-| `visible_conversation` | 按原顺序保留的已封存执行轮次:`{user,status,steps}` |-| `history_partial` | HiRoute 已知的可见历史缺口 |-| `assessment_target` | `null`,或 `{from,instructions,criteria}`,指定上一实际阶段 |+| 任务类别、复杂度条件、评分标准 | HiRoute 从已发布计划中提供 |+| 计算类别、复杂度概率和可选评分 | 扩展 |+| 阈值、执行模型列表、模型资格检查和故障接力 | HiRoute |+| 将评分归属到实际执行阶段并保存观测 | HiRoute |++这个接口返回的是判断结果。执行模型 ID、模型组和候选顺序由 HiRoute 管理,不放进扩展响应。扩展也不接管用户任务的实际执行。++**内置接入与自定义扩展是两种连接方式。** 内置决策模型由 HiRoute 直接调用供应商的 System One API;自定义扩展则接收本文的 HTTP JSON 请求。只有使用 Jev 等兼容供应商时,扩展内部才需要做 [System One 映射](system-one-design.md)。自建服务可以使用其他上游协议。-**有序程度**定义包含 `kind`、`instructions` 和有序的 `levels:[{id,criterion}]`。level ID 唯一,数组顺序表示程度从低到高;当前模型路由使用 `simple`、`complex` 两档。+## 接入一个服务-**任务类别**定义包含 `kind`、`instructions` 和 `options:[{id,criterion,refinement?}]`。自定义路由有 2–16 个任务类别。有主力模型的类别附一个 ordinal `refinement`;只有常规模型的类别不附。按当前请求的主要意图和传入的条件选择,遵守定义中的条件重叠与默认类别规则。类别条件描述任务是什么,程度条件描述该类别内的工作要求。+1. 实现接收 JSON 的 HTTP `POST` 接口,或部署[官方 Jev 扩展](../extensions/jev-decider/README.zh-CN.md)。官方路径是 `/v1/decisions`;自建服务可选其他路径。+2. 在 **模型 → 决策模型** 中打开添加菜单,选择 **接入自定义扩展**。填写完整 endpoint、连接超时,以及可选的认证头名和完整值。+3. 保存并测试连接。连接测试检查传输和必要响应字段;实际判断效果需用代表性任务验证。+4. 在路由计划中选择这个连接,配置任务条件与模型组,然后发布。修改连接或草稿后,需要选择相应连接版本并重新发布才会生效。-instructions 和 criterion 为非空文本,**不设逐字段字符上限**。ID 和外围结构保留 OpenAPI 中的约束。整体传输预算与供应商上下文限制仍适用,不能因此静默截断条件或评分标准。+HiRoute 向配置的**完整 endpoint** 发请求,不自行追加路径。例如 `http://127.0.0.1:8080/v1/decisions` 必须指向扩展服务;远程部署时改为 HiRoute 可访问的地址。扩展使用的上游供应商地址在扩展内部配置。-### 可见历史与评分目标+## 两种 decision,以及独立的 assessment-历史轮次包含 `user` 内容、`status` 和 `steps`。轮次状态为 `completed`、`failed`、`interrupted` 或 `unknown`;steps 是内容数组的数组,每个 step 对应一次业务模型请求。内容包括已接受文本、带显式粗粒度状态的工具名称,或不可用内容标记;不含凭据、system/developer 指令、工具参数或工具结果正文。+字段名、`kind` 和状态值保留协议原文。当前 `decision.kind` 支持 `ordinal` 和 `categorical`:-`assessment_target.from` 是 `visible_conversation` 的零基下标,从该下标到末尾属于同一个上一实际阶段。`instructions` 和三项 `{score,criterion}` 按顺序固定为 **0、0.5、1**,使用该阶段执行时冻结的标准,不能被部署端固定规则替代。HiRoute 在本地绑定实际阶段,扩展无需返回内部模型或执行身份。+| 结构 | 回答的问题 | 扩展返回什么 |+| --- | --- | --- |+| `ordinal` | 当前任务需要多高的处理能力? | `probabilities`:请求中各个 level ID 的完整概率分布;当前模型路由使用 `simple`、`complex` |+| `categorical` | 当前任务属于哪一类,例如写稿还是审稿? | `choice`:一个允许的 option ID;该选项带 `refinement` 时,同时返回它的 `ordinal` 结果 |+| `assessment` | 上一实际执行阶段完成得如何? | 可选评分对象,含必填 `score`、`partial` 和可选 `reason`;它是响应的独立字段,不是 `decision.kind` |-`history_partial` 描述整段可见历史的缺口,评分的 `partial` 描述目标阶段内的证据缺失。更早的消息未采集,本身不会使后续完整采集的目标阶段成为部分证据。目标为 `null` 时省略 assessment。重复用户文本、摘要或继续消息本身不是失败证据。+`refinement` 是选定类别内的进一步判断。在当前路由中,它表示该类任务的复杂度;只返回选中类别的结果。`simple`、`complex`、`writing`、`review` 等 ID 必须与本次请求完全一致,不能翻译或自行改名。`instructions`、`criterion`、用户文本和 `reason` 是自然语言内容,可以使用中文。-## 完整示例+## 最小示例:判断当前任务的复杂度-下列请求和响应来自[规范示例](decision-examples.json),数值用于说明,不是供应商实测结果。两种语言使用相同 JSON,保持示例 ID 与条件一致。+以下示例来自[规范示例](decision-examples.json)。数值仅用于说明;中英文文档共用这些请求和响应,其中的中文条件和用户输入也是合法的示例数据。-### 智能省钱:首次决策,无历史评分+智能省钱提交一个 `ordinal`。首次请求没有历史评分目标,将 `assessment_target` 设为 `null`。-请求:+请求(保存为 `request.json`):```json{@@ -68,7 +86,15 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```-响应:+向已启动的服务发送请求;启用了认证时加上配置的认证头:++```sh+curl --fail-with-body 'http://127.0.0.1:8080/v1/decisions' \+ --header 'Content-Type: application/json' \+ --data-binary @request.json+```++服务返回 HTTP `200`、`Content-Type: application/json` 和以下响应:```json{@@ -82,11 +108,57 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```-没有上一阶段,`assessment_target` 为 `null`,响应不含 `assessment`。默认阈值下,该概率分布选择省钱组。+扩展给出 `simple` 的概率 **0.93**;HiRoute 将它与计划阈值比较。默认阈值为 **0.8**,这次没有低分保护,因此选择省钱组。扩展无需返回“省钱组”或具体模型 ID。没有评分目标时省略 `assessment`。-### 写稿与审稿:类别、选中类别程度及上一阶段评分+## 请求字段-请求:+顶层五个字段均必填,空历史使用 `[]`,没有评分目标使用 `null`:++| 字段 | 含义 |+| --- | --- |+| `decision` | 本次判断定义:`ordinal` 或 `categorical`,包含条件和允许的 ID |+| `latest_user` | 当前请求的完整、非空用户 content parts;允许与先前文本重复 |+| `visible_conversation` | 已结束并保留的执行轮次,按原顺序排列;每项为 `{user,status,steps}` |+| `history_partial` | HiRoute 是否已知整段可见历史存在缺口 |+| `assessment_target` | `null`,或 `{from,instructions,criteria}`,指定要评分的上一实际阶段 |++### decision 定义++- **`ordinal`**:包含 `kind: "ordinal"`、`instructions` 和 `levels: [{id,criterion}]`。ID 唯一,数组顺序表示从低到高的程度。协议结构允许多个 level,当前 HiRoute 模型路由生成 `simple`、`complex` 两档。+- **`categorical`**:包含 `kind: "categorical"`、`instructions` 和 `options: [{id,criterion,refinement?}]`。自定义路由提供 2–16 个类别;按当前任务的主要意图及传入的重叠、默认类别规则选择一项。+- **`refinement`**:可选的嵌套 `ordinal` 定义。有主力模型组的类别提供它,只有常规模型组的类别省略它。类别条件描述任务是什么,`refinement` 条件描述这类任务的工作复杂度。++`instructions` 和 `criterion` 是非空文本,没有逐字段字符上限。ID、数组长度和其他结构约束见 [OpenAPI](decision.openapi.json)。整体传输和上游上下文限制仍适用,不能因此静默截断判断条件或评分标准。++### visible_conversation:执行历史++每个轮次包含当时的 `user` 内容、`status` 和 `steps`。一个 step 对应一次执行模型请求,所以 `steps` 是 content parts 数组的数组。++| 位置 | 支持的值或内容 |+| --- | --- |+| 轮次 `status` | `completed`、`failed`、`interrupted`、`unknown` |+| `user` 和 `latest_user` 中的 content part | `text`(文本)或 `unavailable`(无法提供的内容,以 `source_kind` 说明来源类型) |+| `steps` 中的 content part | `text`、`unavailable`,或 `tool_activity`(工具名称 `tool` 与粗粒度 `status`) |+| 工具 `status` | `completed`、`failed`、`unknown` |++`unknown` 表示缺少明确的终态,不能据此推断成功或失败。工具状态来自显式协议事实。历史不包含凭据、system/developer 指令、工具参数或工具结果正文。++### assessment_target:评价哪段历史++`assessment_target.from` 是 `visible_conversation` 的零基下标。从该下标到数组末尾,属于同一个要评分的实际执行阶段。例如历史有三项,`from: 1` 只评价后两项。当前尚未执行的任务不属于这个目标。++`instructions` 和 `criteria` 使用该阶段执行时冻结的评分标准。`criteria` 恰有三项 `{score,criterion}`,锚点按顺序为 **0、0.5、1**;返回的 `score` 可以是 `[0,1]` 内任意有限数值,不限于这三个锚点。HiRoute 在本地保存目标的模型与阶段归属,扩展不需要猜测或回传内部身份。++`history_partial` 描述整段历史,响应中的 `assessment.partial` 描述评分目标内是否缺少证据。更早的非目标历史缺失,不会自动使完整的目标阶段变成部分证据。扩展裁剪了目标证据时返回 `partial: true`;目标全部移除时省略评分。重复用户文本、摘要或继续消息本身不算失败证据。++## categorical 示例:类别与类内复杂度++### 选择审稿,同时评价上一写稿阶段++请求的两个类别是 `writing` 和 `review`,各自有独立的 `refinement`。本次任务要求审稿,评分目标则指向上一写稿阶段。++<details>+<summary>完整请求:两个类别、各自的 refinement,以及历史评分目标</summary>```json{@@ -179,6 +251,8 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```+</details>+响应:```json@@ -202,11 +276,14 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```-当前选择 `review`,响应只返回审稿的程度。**0.35** 分属于上一**写稿**阶段,不评价尚未发生的审稿,也不能把写稿低分用于审稿类别的保护。HiRoute 根据审稿本次程度选择模型组。+`choice: "review"` 选择审稿,`refinement` 只描述这次审稿的复杂度。`P(simple) = 0.28` 低于默认阈值,HiRoute 选择审稿的主力组。**0.35** 分评价的是上一**写稿**阶段;写稿低分不能用于审稿类别的低分保护。-### 只有常规模型的类别+### 选中的类别只有一组模型-请求:+一个计划内可以同时有双组类别和单组类别。这里 `writing` 仍有 `refinement`,`review` 只有常规模型组,因此没有 `refinement`。++<details>+<summary>完整请求:writing 有 refinement,review 没有</summary>```json{@@ -250,7 +327,9 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```-响应:+</details>++响应只需选择 `review`:```json{@@ -261,32 +340,46 @@ instructions 和 criterion 为非空文本,**不设逐字段字符上限**。I}```-review 选项没有 `refinement`,响应也不附 refinement;HiRoute 使用该类别的常规组。writing 仍可有两组模型,不因此要求审稿判断程度。后续请求也可以评估单组类别的上一阶段。+HiRoute 使用审稿的常规组。扩展不为该类别补造复杂度概率;后续请求仍可评价它已执行阶段的胜任度。++## 响应规则与错误处理-## 响应校验+返回 HTTP **200** 和单个 JSON 对象,响应最大 **64 KiB**。不要包裹 Markdown 或供应商原生响应,也不要添加重复或未知字段。-返回 HTTP **200** 和一个纯 JSON 对象,最大 **64 KiB**。Markdown、重复或未知字段、原生供应商 envelope 都无效。+| 字段 | 要求 |+| --- | --- |+| `decision.kind` | 与请求一致 |+| `decision.probabilities` | `ordinal` 结果使用本次所有 level ID,不缺项、不多项;每项是有限 `[0,1]` 概率,总和与 1 的误差不超过 `1e-6`;HiRoute 会归一化这部分浮点误差 |+| `decision.choice` | `categorical` 结果必须是本次 `options` 中的一个 ID |+| `decision.refinement` | 仅返回选中选项定义的 `ordinal` 结果;该选项没有定义时省略 |+| `assessment` | 可选;包含有限 `[0,1]` 的 `score`、必填 `partial`,以及可选的 1–1024 个 Unicode 标量的 `reason` |-有序结果使用本次准确的 level ID,覆盖全部档位,返回有限 `[0,1]` 概率,总和与 1 的误差不超过 `1e-6`;HiRoute 校验后归一化这部分浮点误差。分类结果返回允许的 `choice`,有程度定义时只返回该选项的 `refinement`。扩展不能返回模型 ID、候选顺序或路由阈值。+`assessment_target: null` 时省略 `assessment`。有效零分必须保留;没有评分不等于零分,也不会删除已保存观测。-可选 `assessment` 包含有限 `[0,1]` 的 `score`、必填 `partial`,以及可选的 1–1024 个 Unicode 标量 `reason`。有效零分必须保留;缺失、非法或部分评分不是零分,不能驱动低分保护。省略评分不会删除已保存观测;旧评分不会被当作本次新评分复用。+| 情况 | HiRoute 的处理 |+| --- | --- |+| `choice` 不在允许集合,或整体响应无效 | 当前决策失败,走下文的计划兜底 |+| 智能省钱的 `ordinal` 概率缺失或非法 | 使用主力组,记录复杂度不可用 |+| 类别合法,但所需 `refinement` 缺失或非法 | 保留类别,使用该类别主力组,记录复杂度不可用 |+| 可选评分缺失、非法或无对应目标 | 不使用该评分;合法当前决策仍可用 |+| 评分 `partial: true` | 记录部分证据,不能触发低分保护 |-非法类别使当前决策无效。类别有效但选中程度非法时,保留该类别、使用它的主力组并记录程度不可用。非法可选评分独立丢弃,不影响合法当前决策。供应商未选中的程度答案错误,不应污染选中路径。+如果上游一次回答多个类别的复杂度,只转换被选中类别的答案。未选中答案有误,不应连带废弃有效的选中路径。-## HiRoute 如何使用结果+## HiRoute 如何执行判断结果-有两组模型时,本次 `P(simple)` 达到配置阈值(默认 **0.8**),且没有适用的本次评分低于胜任下限(默认 **0.5**),才选择常规或省钱组;否则选择主力。低分保护要求上一实际阶段的完整有效评分,与本次类别、已发布计划版本和评分标准一致。单组类别记录胜任度,不提供升级组。+有两组模型时,本次 `P(simple)` 达到配置阈值(默认 **0.8**),且没有适用的本次评分低于胜任下限(默认 **0.5**),才选择常规或省钱组;否则选择主力。低分保护要求评分完整有效,且上一实际阶段与本次的类别、已发布计划版本、评分标准一致。旧评分不会在后续请求中作为新低分反复使用。单组类别只记录胜任度,没有可升级的主力组。-每条新用户消息重新决策,可能选择任一组。工具续接和同轮重放只有在 HiRoute 可识别为同轮且冻结决策可复用时,才继承该决策;历史重建不连续或决策无法继承时仍会重新判断。可用性接力为常规 → 同类别主力 → 失败;直接选主力时只在主力组内接力。候选故障不会制造胜任度零分。+每条新用户消息重新决策。工具续接和同轮重放在可识别为同轮、且冻结决策仍可复用时继承它;历史不连续或无法继承时重新判断。扩展不用靠比较用户文本是否变化来决定是否处理请求。-整体决策失败时,智能省钱使用启发式规则;自定义使用默认类别,有主力组则选择主力。源取消、源 deadline 和当前输入完整性错误直接终止请求。+选定组后,HiRoute 按顺序尝试合格模型。常规组耗尽可接力同类别主力组;直接选择主力时只在主力组内接力。候选故障不会制造胜任度零分。整体决策失败时,智能省钱使用启发式规则;自定义路由使用默认类别,有主力组则选择主力。-## 供应商集成与请求限制+## 上下文、超时与调用边界-扩展负责供应商集成和上下文准备。完整当前用户输入不可截断。为适配供应商限制,可以从最旧完整历史轮次开始裁剪,并调整保留历史中的目标下标。目标证据被裁剪时返回 `partial:true`;目标全部移除时省略评分。HiRoute 还会合并自身已知的目标证据缺口,扩展的 `partial:false` 不能抵消这些事实。+扩展负责上游集成和上下文准备。保留完整当前用户输入和传入的判断条件、评分标准。需要裁剪时,从最旧的完整历史轮次开始移除,并调整传给上游的目标下标;是否影响评分按 `assessment_target` 的实际范围判断。HiRoute 还会合并自身已知的目标证据缺口,扩展的 `partial: false` 不能抵消这些事实。-内置适配器限制完整供应商请求为 **256 KiB**,包括问题和 state。官方 Jev 扩展默认使用相同预算,并允许部署配置。这是字节分配预算,不是 token 数或供应商上下文上限。当前输入与问题本身超限时拒绝请求,不截断它们。业务模型上下文仍由路由计划设置决定。+官方 Jev 扩展默认将完整供应商请求限制为 **256 KiB**,可通过部署配置调整;HiRoute 内置适配器也使用 256 KiB 预算。这是供应商请求的字节预算,不是本 API 要求所有自建扩展采用的 token 或上下文上限。当前输入与问题本身放不下时拒绝请求,不截断它们。执行模型的上下文仍由路由计划配置。-HiRoute 的总 deadline 覆盖准备、认证读取、连接和响应读取。生产传输只调用一次,无自动后台重试,禁止跳转。扩展自身预算应能容纳在 HiRoute 连接超时内。+HiRoute 对扩展的生产调用只有一次,无自动后台重试,不跟随重定向。总 deadline 覆盖准备、认证读取、连接和响应读取;扩展自身预算应小于 HiRoute 连接超时。扩展不可用或请求失败会进入上述决策兜底;源请求取消、源 deadline 或当前输入完整性错误则直接终止请求。-[协议设计](decision-design.md)描述当前 v1 边界;[System One 映射](system-one-design.md)描述供应商 Choice/Score 调用。工具精选仅保留未来文档,当前路由与扩展 API 运行时不支持。+完整类型见 [OpenAPI](decision.openapi.json),可复制数据见[规范示例](decision-examples.json),更多背景见[协议设计](decision-design.md)。当前运行时支持 `ordinal` 和 `categorical`;设计中的 `subset` 工具精选尚未开放。diff --git a/decision-extensions/extensions/jev-decider/README.zh-CN.md b/decision-extensions/extensions/jev-decider/README.zh-CN.mdindex fe2cb94a..ecbd0a24 100644--- a/decision-extensions/extensions/jev-decider/README.zh-CN.md+++ b/decision-extensions/extensions/jev-decider/README.zh-CN.md@@ -2,9 +2,11 @@[English](README.md) · [自定义扩展 API](../../api/README.zh-CN.md)-这个可选的 Python HTTP 服务用一次 System One 供应商调用实现 HiRoute 当前 **v1**。HiRoute 也可在**模型 → 决策模型**直接接入供应商;选择自行部署的自定义扩展时才需要该服务。+Jev 扩展是一个可自行部署的 Python HTTP 服务。它接收 HiRoute 的决策请求,将问题发送给兼容 System One API 的供应商,再按 [HiRoute 扩展 API v1](../../api/README.zh-CN.md) 返回结果。每次决策只调用一次上游。-扩展遵守请求传入的任务类别、程度条件和冻结评分标准,返回当前类别/程度,以及可选的上一实际阶段胜任度。阈值、模型组、可用性接力与观测由 HiRoute 负责,部署端不配置路由规则、阈值或固定分支策略。+如果只想直接使用支持的决策供应商,可以在 **模型 → 决策模型** 中添加内置连接,无需部署本服务。需要自己管理决策服务或修改供应商集成时,可以使用这份参考实现。++扩展按每次请求中的任务条件和评分标准进行判断:`categorical` 返回任务类别,`ordinal` 返回复杂度概率,`assessment` 可选地评价上一执行阶段。HiRoute 再应用阈值、选择模型组并记录执行结果。这些路由设置在 HiRoute 中配置,不写进扩展的部署参数。## 安装@@ -22,7 +24,7 @@ chmod 600 "$HOME/.config/hiroute/jev-api-key"## 配置并启动-选择一种供应商配置。包括百炼在内的兼容接入都使用 `OPENROUTER_*` 环境变量,没有另一套百炼 Key 或账户版本变量。+选择下面一种供应商配置。环境变量沿用 `OPENROUTER_*` 名称;接入百炼或其他兼容供应商时,也使用这些变量填写相应的地址和 API Key 文件路径。### OpenRouter Jev@@ -55,8 +57,8 @@ Token Plan 使用统一端点,实际可用性由凭证权限和供应商调用| `OPENROUTER_API_KEY_FILE` | 必填,私有 UTF-8 供应商 Key 文件的绝对路径 || `OPENROUTER_DECISIONS_URL` | `https://openrouter.ai/api/alpha/decisions` || `JEV_MODEL` | `typesafe/jev-1.13` |-| `JEV_REQUEST_TIMEOUT_SECONDS` | 总预算默认 2.8 秒,包含准备、排队、连接和读取;范围为 `(0,3600]` |-| `JEV_MAX_REQUEST_BYTES` | 默认 262144 字节,包括问题和 state 的完整供应商请求;不是 token 估算 |+| `JEV_REQUEST_TIMEOUT_SECONDS` | 请求总超时默认 2.8 秒,包含准备、排队、连接和读取;范围为 `(0,3600]` |+| `JEV_MAX_REQUEST_BYTES` | 发往供应商的完整请求最多 262144 字节,包括问题与 `state`;单位是字节,不是 token || `JEV_MAX_CONCURRENCY` | 默认同时进行 32 个上游调用 || `HOST`、`PORT` | `127.0.0.1`、`8080` || `DECIDER_AUTH_HEADER_NAME`、`DECIDER_AUTH_HEADER_VALUE` | 可选,必须成对设置,用于 HiRoute 请求扩展的认证;自定义连接中配置相同头名与值 |@@ -65,9 +67,9 @@ Token Plan 使用统一端点,实际可用性由凭证权限和供应商调用服务启动后,`GET http://127.0.0.1:8080/health` 检查 HTTP 服务是否运行,不会调用供应商或验证 Key 权限。-在**模型 → 决策模型**添加**自定义扩展**,完整接入点为 **`http://127.0.0.1:8080/v1/decisions`**。HiRoute 连接超时应大于扩展总预算;以上示例的扩展预算为 10 秒。设置了入站认证时,两端配置相同头名与值。扩展运行在其他主机时,应使用 HiRoute 可访问的地址代替回环地址。保存并测试连接,然后在路由计划中选择它并发布。+在**模型 → 决策模型**添加**自定义扩展**,完整接入点为 **`http://127.0.0.1:8080/v1/decisions`**。HiRoute 连接超时应大于扩展的请求总超时;以上启动命令将扩展超时设为 10 秒。设置了入站认证时,两端配置相同头名与值。扩展运行在其他主机时,应使用 HiRoute 可访问的地址代替回环地址。保存并测试连接,然后在路由计划中选择它并发布。-两层 HTTP 边界使用不同请求:+这里有两个不同的请求地址:一个供 HiRoute 调用扩展,另一个供扩展调用供应商。两者使用的 JSON 格式也不同:| 调用方 → 接收方 | 接入点 | 请求内容 || --- | --- | --- |@@ -78,11 +80,13 @@ Token Plan 使用统一端点,实际可用性由凭证权限和供应商调用## 行为和限制-扩展在一次供应商请求中提交独立的类别、程度和可选评分问题,只读取选中类别的程度;未选中答案错误不影响选中路径。程度使用完整概率分布,胜任度使用供应商原始 score 除以二,不使用 confidence。选中程度非法时保留类别,由 HiRoute 使用该类别主力组;非法评分省略,不制造评分理由。+扩展将类别选择、复杂度判断和历史评分作为独立问题,一次发送给供应商。返回结果后,只读取选中类别的复杂度;其他类别的答案有误,不影响已经选中的结果。++复杂度使用各档位的完整概率分布。历史评分使用 System One 返回的 `score`:上游以 0、1、2 对应三个评分标准,扩展将分数除以 2,转换为 HiRoute 的 `[0,1]` 范围;`confidence` 不能代替胜任度。选中类别的复杂度答案无效时,仍保留类别,由 HiRoute 选择该类别的主力组。无效评分会被省略,扩展也不会自行生成评分理由。-当前输入与传入的提示词保持完整。为满足完整请求字节预算,可以从最旧完整历史轮次开始裁剪;目标阶段内的证据被移除时标记部分评分,目标全部移除则省略评分。当前输入与问题本身超限时拒绝请求,不截断内容。供应商上下文限制仍适用,业务模型继续使用路由计划中的上下文设置。+当前输入与传入的提示词保持完整。为满足供应商请求的字节上限,可以从最旧完整历史轮次开始裁剪;目标阶段内的证据被移除时标记部分评分,目标全部移除则省略评分。当前输入与问题本身超限时拒绝请求,不截断内容。供应商上下文限制仍适用,执行模型仍使用路由计划中的上下文设置。-每次只有一个上游调用,无重试,禁止跳转;上游响应最大 **64 KiB**。服务总预算包含等待并发名额。日志记录耗时、数量、状态和供应商实际返回的用量,不记录提示词或凭据。工具精选仅保留未来文档,本服务尚未实现。+每次只有一个上游调用,不重试、不跟随重定向;上游响应最大 **64 KiB**。等待空闲并发名额的时间也计入请求总超时。日志记录耗时、数量、状态和供应商实际返回的用量,不记录提示词或凭据。`subset` 工具精选尚未实现。## 离线验证@@ -93,4 +97,4 @@ cd decision-extensions/extensions/jev-decider"$HOME/hiroute-jev/.venv/bin/python" -m unittest discover -v```-测试通过本地 fixture 验证严格请求、答案归约、裁剪、认证、deadline 和 HTTP handler,不代表供应商判断质量或原生 Desktop 验收。HiRoute 的显式连接测试验证保存的连接及必要结果字段;实际任务质量仍需代表性的真实使用确认。+这些测试使用本地模拟供应商,检查请求校验、供应商结果转换、历史裁剪、认证、超时和 HTTP 接口,不会验证真实供应商的判断质量。部署后,再在 HiRoute 中保存并测试连接,最后用代表性任务观察实际效果。