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: establish public language boundaries (#1)
澄潭c6a662337456
diff --git a/.github/workflows/gateway-core.yml b/.github/workflows/gateway-core.ymlindex 06ee0315..71cc985c 100644--- a/.github/workflows/gateway-core.yml+++ b/.github/workflows/gateway-core.yml@@ -22,7 +22,10 @@ jobs:fetch-depth: 0persist-credentials: false- name: Validate selection rules- run: python3 scripts/test-test-plan.py+ run: |+ python3 scripts/test-test-plan.py+ python3 scripts/test-public-language.py+ python3 scripts/check-public-language.py- id: planenv:BASE_SHA: ${{ github.event.pull_request.base.sha }}diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 62f90bbf..65215685 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -32,6 +32,23 @@ Run the checks relevant to your change before opening a pull request. Native macbehavior and real-provider integration require their respective environments; describe anysuch checks that you could not run.+## Language boundaries++English is the default language for source comments, GitHub metadata, and Markdown files+without a language suffix. Put a Simplified Chinese translation in a sibling+`*.zh-CN.md` file and keep links within the reader's current language whenever a translated+page exists. Website guide sources use the existing `*.en.md` and `*.zh.md` convention.++Desktop and website components may contain both locales in source, but every user-visible+sentence must be selected by the active locale; do not leave English decorative copy on a+Chinese page or Chinese fallback copy on an English page. Product names, protocol names,+commands, paths, code, API fields, and model/provider identifiers remain unchanged. Synthetic+multilingual fixtures are allowed when they test Unicode or localized behavior.++Run `python3 scripts/check-public-language.py` after changing public documentation. Internal+issue specifications, handoffs, and workflow instructions are outside this public-language+boundary.+Do not commit API keys, account data, real conversation content, diagnostic archives, ormachine-specific configuration. Use synthetic fixtures in tests. Security issues and crashreports follow [SECURITY.md](SECURITY.md).diff --git a/README.md b/README.mdindex 74bb52ee..aed3c9bd 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@# HiRoute-[简体中文](README.zh-CN.md)+[Simplified Chinese](README.zh-CN.md)HiRoute is a local model-routing and agent-coordination engine for long-running tasks. Itkeeps model sources, routing plans, agent connections and execution evidence in one place,diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 2e4469b1..7447c997 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -25,13 +25,13 @@ HiRoute 当前处于 MVP 阶段。下载页会说明各版本已验证的平台- [下载 HiRoute](https://hiroute.ai/download/)- [使用文档](https://hiroute.ai/docs/)-- [macOS 自签名安装](docs/macos-installation.md)-- [Linux headless 与 CLI](docs/standalone-cli.md)+- [macOS 自签名安装](docs/macos-installation.zh-CN.md)+- [Linux headless 与 CLI](docs/standalone-cli.zh-CN.md)- [模型选择决策机制与扩展](decision-extensions/README.zh-CN.md)- [Decision API OpenAPI 文档](decision-extensions/api/decision.openapi.json)参与开发时,Rust 版本由 `rust-toolchain.toml` 固定,Desktop UI 使用 Node.js/npm 与 Tauri。-请阅读 [贡献指南](CONTRIBUTING.md)、[Desktop 开发入口](apps/desktop/README.md)和+请阅读 [贡献指南](CONTRIBUTING.md)、[Desktop 开发入口](apps/desktop/README.zh-CN.md)和[官网开发及发布指南](apps/website/README.md)。## 代码结构diff --git a/apps/desktop/README.md b/apps/desktop/README.mdindex dd6f3e2f..8f5d7deb 100644--- a/apps/desktop/README.md+++ b/apps/desktop/README.md@@ -1,10 +1,14 @@# HiRoute Desktop-Desktop 提供模型管理、路由配置、Agent 接入、任务结果及会话记录入口,通过共享 Client Core 调用真实本机服务。公开使用入口见[官网文档](https://hiroute.ai/docs/)。+[Simplified Chinese](README.zh-CN.md)-## 开发入口+Desktop provides model management, routing configuration, Agent integration, task results,+and session history. It reaches the real local service through the shared Client Core. See+the [website documentation](https://hiroute.ai/en/docs/) for the public user entry point.-在本仓库 checkout 构建 UI,然后构建同版本的原生应用和 daemon:+## Development entry point++Build the UI from this checkout, then build the matching native application and daemon:```shcd apps/desktop@@ -15,36 +19,73 @@ cargo build --locked -p hiroute-desktop --features desktop-runtime -p hiroute-datarget/debug/hiroute-desktop```-macOS 平台构建和实际窗口交互需要在 macOS 本机验证;通用开发检查见仓库根目录-`CONTRIBUTING.md`。所有 Cargo 输出使用该 checkout 默认 `target/`。--这是开发二进制入口。公开安装包和平台说明见[下载页](https://hiroute.ai/download/)。-原生应用从同目录启动 `hirouted`,从内置正式签名资源初始化 ReleaseFacts。WebView-仅加载本地构建产物;不提供任意命令、路径、HTTP 或授权的 IPC。--关闭窗口会隐藏窗口,后台由 native 宿主持有;Dock 激活可重开。退出 native 应用会结束本次启动的 daemon,下次启动从真实后端恢复。外部 daemon 仅作为只读连接,不受 Desktop 的关闭/退出管理。正式安装与平台交付范围见官网各版本说明。--可信启动后,Desktop 锁文件记录子进程 PID、私有端点目录与 socket 身份。持有锁、原 PID 已退出、身份未替换且端点不再监听时,重开交由 daemon 自身恢复残留端点。没有可信记录、PID 仍存活或路径身份不明时保留只读状态,不删除或接管该端点。--## 恢复与授权边界--确认上下文由 native backend 持有,只绑定这次 Preview 的对象、输入、digest/revisions 和窗口生命期,60 秒后失效。业务确认统一由本地 WebView 展示;WebView 只能针对 backend 发出的当前临时确认 ID 回传一次接受或拒绝,不能携带上下文、跳过确认或取得能力。接受后才通过继承通道登记 Desktop 主体的一次性能力;匹配的成功 ACK 之后才能发送 Apply。登记通道出现不确定结果后停止使用该写入关系,重新启动 native 应用才能建立新关系。--Desktop 只在当前交互内存中保留提交 key、摘要和 Operation 引用,用于响应丢失后的查询与显式重试。重开直接读取服务端实际配置;事务恢复属于 daemon 的既有 Journal。客户端不读写 `pending-intent.json`,历史文件不会触发告警或锁定编辑。切换编辑不取消后台操作,新动作独立经过服务端版本与幂等检查。--当前交互还保留版本化的 Plan ID + 目标名称摘要。没有查到受理时,同一意图可在 revision 改变后重新 Preview/重新确认,仍用原 key。查到原 Operation 时优先观察它,digest 不同会明确提示“最新编辑尚未应用”,并保留编辑草稿。查询失败或路由结果尚未同步时不会持续禁用编辑器;用户继续修改后,迟到的旧结果不得覆盖新输入,下一次保存仍由服务端 revision 检查。--“恢复先前名称”使用当前 desired 的新 Preview/确认,只替换名称,不回写旧 revision。先前名称保存在本次 native 会话中;非敏感编辑草稿与语言/文字大小偏好保存在本机 WebView。重启后仍可查询持久 Operation,先前名称按钮的会话历史不持久化。--## 验证入口--- Core/CLI/API/Application/daemon/Desktop:`cargo test --locked -p hiroute-client-core -p hiroute-cli -p hiroute-application-api -p hiroute-application -p hiroute-daemon -p hiroute-desktop -- --test-threads=1`。Desktop 的生产 bootstrap 测试使用同一 checkout 的 `target/debug/hirouted`(先构建该二进制,或随 daemon 的集成测试一起构建)。-- 前端:`npm run build`。-- 确定性 CLI 生成器:连续两次执行 `target/debug/generate-cli-contract`,第二次生成内容必须不变。-- macOS 隔离 Plan 准备:`python3 apps/desktop/tests/prepare_plan.py /tmp/hr02-new-empty-root`。依赖本机真实 Claude CLI、正式注册模型事实和已构建的生产 CLI/daemon;通过生产 Preview/受保护 Apply 准备数据,不直接写业务库。-- 实际 GUI 验收:debug 构建用 `HIROUTE_DESKTOP_TEST_ROOT` 指向上述隔离根,在其 `agent-input/` 工作目录启动原生程序。核对 WebView 确认取消零写、确认 ID 重放/窗口关闭失败关闭、名称 A→B→A、两个独立成功 Operation、Plan/alias/其余 desired 与实际发布身份;该 debug 路径开关不进入 release 构建。--组件替身测试不能替代实际 Tauri → Client Core → 生产 daemon 的可逆切片。执行退出码、各场景结论、平台与准确 revision 分别记录。---真实 Tauri ACL 探针仅是开发 example:构建 `cargo build --locked -p hiroute-desktop --features desktop-runtime --example acl_probe`,再以 `HIROUTE_DESKTOP_TEST_ROOT` 指定独立测试根运行 `target/debug/examples/acl_probe`。它使用生产 handler/权限清单,创建未许可的本地窗口与 remote-origin 主窗口,检查十次拒绝并写入该根的 `acl-probe.json`;不加入产品 bridge。退出 0 为十次权限拒绝,1 为断言失败,2 为超时。+macOS builds and real window interactions must be validated on macOS. See the repository+root `CONTRIBUTING.md` for common development checks. Keep all Cargo output in this+checkout's default `target/` directory.++This command starts the development binary. Use the public+[download page](https://hiroute.ai/en/download/) for installers and supported-platform+details. The native application starts the adjacent `hirouted` binary and initializes+ReleaseFacts from the embedded, signed resources. The WebView loads only locally built+assets and exposes no arbitrary command, path, HTTP, or authorization IPC.++Closing the window hides it while the native host continues running; activating the Dock+icon opens it again. Quitting the native application stops the daemon that it started, and+the next launch recovers from the real backend. An externally started daemon is attached+read-only and is not managed by Desktop shutdown. The website release notes define the+actual installation and platform scope.++After a trusted launch, the Desktop lock records the child PID, private endpoint directory,+and socket identity. If the lock is still owned, the original PID has exited, identities are+unchanged, and the endpoint is no longer listening, recovery is delegated to the daemon.+When those facts cannot be established, Desktop remains read-only and neither deletes nor+takes over the endpoint.++## Recovery and authorization boundary++The native backend owns confirmation context. A confirmation is bound to one Preview's+object, input, digest/revisions, and window lifetime, and expires after 60 seconds. The local+WebView only returns a one-time accept or reject for a current confirmation ID; it cannot+supply context, skip confirmation, or acquire a capability. Acceptance registers a one-time+Desktop capability through the inherited channel, and Apply is sent only after the matching+acknowledgement succeeds. An uncertain registration result closes that write relationship;+restart the native application to establish a new one.++Desktop keeps only the current interaction's submission key, digest, and Operation reference+in memory so it can query or explicitly retry after a lost response. Reopening reads actual+server configuration; transaction recovery remains the daemon Journal's responsibility.+The client does not read or write `pending-intent.json`. Switching editors does not cancel a+background operation, and each new action is checked independently for version and+idempotency.++The current interaction also retains a versioned Plan ID and target-name summary. If no+accepted operation is found after a revision change, the same intent may be Previewed and+confirmed again with its original key. If the original Operation is found, Desktop observes+it first; a different digest reports that the latest edit has not been applied and retains+the draft. A failed query or delayed routing projection does not leave the editor disabled.+A late result from an older edit cannot overwrite newer input.++“Restore previous name” creates a new Preview and confirmation against current desired state,+changing only the name and never restoring an old revision. The prior name is native-session+state. Non-sensitive drafts and language/text-size preferences are local WebView data.+Persistent Operations remain queryable after restart, but the in-session previous-name action+does not.++## Validation entry points++- Core/CLI/API/Application/daemon/Desktop: `cargo test --locked -p hiroute-client-core -p hiroute-cli -p hiroute-application-api -p hiroute-application -p hiroute-daemon -p hiroute-desktop -- --test-threads=1`. Desktop production-bootstrap tests use this checkout's `target/debug/hirouted`; build it first or include the daemon integration tests.+- Frontend: `npm run build`.+- Deterministic CLI generator: run `target/debug/generate-cli-contract` twice; the second run must produce no changes.+- Isolated macOS Plan setup: `python3 apps/desktop/tests/prepare_plan.py /tmp/hr02-new-empty-root`. It requires the real local Claude CLI, production model facts, and built production CLI/daemon, and uses production Preview/protected Apply rather than direct database writes.+- Real GUI acceptance: start the debug native application from the isolated root's `agent-input/` directory with `HIROUTE_DESKTOP_TEST_ROOT` set. Verify confirmation cancellation has zero writes, confirmation replay/window-close fails closed, rename A→B→A, two independent successful Operations, and desired/actual publication identity. The debug path override is absent from release builds.++Component doubles do not replace the reversible Tauri → Client Core → production-daemon+slice. Record process exit, scenario result, platform, and exact revision separately.++The real Tauri ACL probe is a development example only. Build it with+`cargo build --locked -p hiroute-desktop --features desktop-runtime --example acl_probe`,+then run `target/debug/examples/acl_probe` with an isolated `HIROUTE_DESKTOP_TEST_ROOT`. It+uses production handlers and permissions, creates an unpermitted local window and a+remote-origin main window, verifies ten denials, and writes `acl-probe.json` under that root.+It adds no product bridge. Exit 0 means ten denials, 1 means an assertion failed, and 2 means+the probe timed out.diff --git a/apps/desktop/README.zh-CN.md b/apps/desktop/README.zh-CN.mdnew file mode 100644index 00000000..1a7eb655--- /dev/null+++ b/apps/desktop/README.zh-CN.md@@ -0,0 +1,52 @@+# HiRoute Desktop++[English](README.md)++Desktop 提供模型管理、路由配置、Agent 接入、任务结果及会话记录入口,通过共享 Client Core 调用真实本机服务。公开使用入口见[官网文档](https://hiroute.ai/docs/)。++## 开发入口++在本仓库 checkout 构建 UI,然后构建同版本的原生应用和 daemon:++```sh+cd apps/desktop+npm ci+npm run build+cd ../..+cargo build --locked -p hiroute-desktop --features desktop-runtime -p hiroute-daemon -p hiroute-cli --bin hiroute-desktop --bin hirouted --bin hiroute+target/debug/hiroute-desktop+```++macOS 平台构建和实际窗口交互需要在 macOS 本机验证;通用开发检查见仓库根目录+`CONTRIBUTING.md`。所有 Cargo 输出使用该 checkout 默认 `target/`。++这是开发二进制入口。公开安装包和平台说明见[下载页](https://hiroute.ai/download/)。+原生应用从同目录启动 `hirouted`,从内置正式签名资源初始化 ReleaseFacts。WebView+仅加载本地构建产物;不提供任意命令、路径、HTTP 或授权的 IPC。++关闭窗口会隐藏窗口,后台由 native 宿主持有;Dock 激活可重开。退出 native 应用会结束本次启动的 daemon,下次启动从真实后端恢复。外部 daemon 仅作为只读连接,不受 Desktop 的关闭/退出管理。正式安装与平台交付范围见官网各版本说明。++可信启动后,Desktop 锁文件记录子进程 PID、私有端点目录与 socket 身份。持有锁、原 PID 已退出、身份未替换且端点不再监听时,重开交由 daemon 自身恢复残留端点。没有可信记录、PID 仍存活或路径身份不明时保留只读状态,不删除或接管该端点。++## 恢复与授权边界++确认上下文由 native backend 持有,只绑定这次 Preview 的对象、输入、digest/revisions 和窗口生命期,60 秒后失效。业务确认统一由本地 WebView 展示;WebView 只能针对 backend 发出的当前临时确认 ID 回传一次接受或拒绝,不能携带上下文、跳过确认或取得能力。接受后才通过继承通道登记 Desktop 主体的一次性能力;匹配的成功 ACK 之后才能发送 Apply。登记通道出现不确定结果后停止使用该写入关系,重新启动 native 应用才能建立新关系。++Desktop 只在当前交互内存中保留提交 key、摘要和 Operation 引用,用于响应丢失后的查询与显式重试。重开直接读取服务端实际配置;事务恢复属于 daemon 的既有 Journal。客户端不读写 `pending-intent.json`,历史文件不会触发告警或锁定编辑。切换编辑不取消后台操作,新动作独立经过服务端版本与幂等检查。++当前交互还保留版本化的 Plan ID + 目标名称摘要。没有查到受理时,同一意图可在 revision 改变后重新 Preview/重新确认,仍用原 key。查到原 Operation 时优先观察它,digest 不同会明确提示“最新编辑尚未应用”,并保留编辑草稿。查询失败或路由结果尚未同步时不会持续禁用编辑器;用户继续修改后,迟到的旧结果不得覆盖新输入,下一次保存仍由服务端 revision 检查。++“恢复先前名称”使用当前 desired 的新 Preview/确认,只替换名称,不回写旧 revision。先前名称保存在本次 native 会话中;非敏感编辑草稿与语言/文字大小偏好保存在本机 WebView。重启后仍可查询持久 Operation,先前名称按钮的会话历史不持久化。++## 验证入口++- Core/CLI/API/Application/daemon/Desktop:`cargo test --locked -p hiroute-client-core -p hiroute-cli -p hiroute-application-api -p hiroute-application -p hiroute-daemon -p hiroute-desktop -- --test-threads=1`。Desktop 的生产 bootstrap 测试使用同一 checkout 的 `target/debug/hirouted`(先构建该二进制,或随 daemon 的集成测试一起构建)。+- 前端:`npm run build`。+- 确定性 CLI 生成器:连续两次执行 `target/debug/generate-cli-contract`,第二次生成内容必须不变。+- macOS 隔离 Plan 准备:`python3 apps/desktop/tests/prepare_plan.py /tmp/hr02-new-empty-root`。依赖本机真实 Claude CLI、正式注册模型事实和已构建的生产 CLI/daemon;通过生产 Preview/受保护 Apply 准备数据,不直接写业务库。+- 实际 GUI 验收:debug 构建用 `HIROUTE_DESKTOP_TEST_ROOT` 指向上述隔离根,在其 `agent-input/` 工作目录启动原生程序。核对 WebView 确认取消零写、确认 ID 重放/窗口关闭失败关闭、名称 A→B→A、两个独立成功 Operation、Plan/alias/其余 desired 与实际发布身份;该 debug 路径开关不进入 release 构建。++组件替身测试不能替代实际 Tauri → Client Core → 生产 daemon 的可逆切片。执行退出码、各场景结论、平台与准确 revision 分别记录。+++真实 Tauri ACL 探针仅是开发 example:构建 `cargo build --locked -p hiroute-desktop --features desktop-runtime --example acl_probe`,再以 `HIROUTE_DESKTOP_TEST_ROOT` 指定独立测试根运行 `target/debug/examples/acl_probe`。它使用生产 handler/权限清单,创建未许可的本地窗口与 remote-origin 主窗口,检查十次拒绝并写入该根的 `acl-probe.json`;不加入产品 bridge。退出 0 为十次权限拒绝,1 为断言失败,2 为超时。diff --git a/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.md b/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.mdindex 651b56e8..6ddb9461 100644--- a/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.md+++ b/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.md@@ -1,12 +1,18 @@-# HiRoute 安装候选组件声明+# HiRoute distribution candidate component notice-HiRoute Rust workspace 声明 Apache-2.0。安装包包含 HiRoute Desktop、hirouted、hiroute、-前端资源、内置模型目录及固定版本 CLIProxyAPI (CPA)。各组件保持各自版本和许可。-CPA 的版本、源码 commit、最终签名字节摘要见 installation.json。+[Simplified Chinese](DISTRIBUTION-NOTICE.zh-CN.md)-第三方 Rust/npm 依赖的版本和声明许可见 dependency-inventory.json。-`Licenses/THIRD-PARTY-LICENSES.txt` 及其 JSON 清单由打包器从锁定依赖与固定 CPA commit-确定性生成,包含各组件随源发布的 LICENSE、NOTICE 等材料;CPA 与 HiRoute 自身许可证也位于-同一目录。工具不会用 HiRoute 的许可替代第三方许可,发现缺失材料时会拒绝打包。+The HiRoute Rust workspace is licensed under Apache-2.0. The package contains HiRoute+Desktop, `hirouted`, `hiroute`, frontend resources, the built-in model catalog, and a pinned+CLIProxyAPI (CPA) version. Each component retains its own version and license. CPA's version,+source commit, and final signed-byte digest are recorded in `installation.json`.-`controlled-trial` 只表示包采用自签名且未公证,不表示省略许可证材料。+Declared licenses for third-party Rust/npm dependencies are listed in+`dependency-inventory.json`. `Licenses/THIRD-PARTY-LICENSES.txt` and its JSON manifest are+generated deterministically from locked dependencies and the pinned CPA commit. They include+the LICENSE, NOTICE, and related materials distributed with each component; the CPA and+HiRoute licenses are stored in the same directory. The tooling never substitutes HiRoute's+license for a third-party license and refuses to package incomplete materials.++`controlled-trial` means only that the package is self-signed and not notarized. It does not+waive any license-material requirement.diff --git a/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.zh-CN.md b/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.zh-CN.mdnew file mode 100644index 00000000..28ff0469--- /dev/null+++ b/apps/desktop/src-tauri/DISTRIBUTION-NOTICE.zh-CN.md@@ -0,0 +1,14 @@+# HiRoute 安装候选组件声明++[English](DISTRIBUTION-NOTICE.md)++HiRoute Rust workspace 声明 Apache-2.0。安装包包含 HiRoute Desktop、hirouted、hiroute、+前端资源、内置模型目录及固定版本 CLIProxyAPI (CPA)。各组件保持各自版本和许可。+CPA 的版本、源码 commit、最终签名字节摘要见 installation.json。++第三方 Rust/npm 依赖的版本和声明许可见 dependency-inventory.json。+`Licenses/THIRD-PARTY-LICENSES.txt` 及其 JSON 清单由打包器从锁定依赖与固定 CPA commit+确定性生成,包含各组件随源发布的 LICENSE、NOTICE 等材料;CPA 与 HiRoute 自身许可证也位于+同一目录。工具不会用 HiRoute 的许可替代第三方许可,发现缺失材料时会拒绝打包。++`controlled-trial` 只表示包采用自签名且未公证,不表示省略许可证材料。diff --git a/apps/desktop/src/features/PlanQuality.tsx b/apps/desktop/src/features/PlanQuality.tsxindex 8f9036ff..4da3b39e 100644--- a/apps/desktop/src/features/PlanQuality.tsx+++ b/apps/desktop/src/features/PlanQuality.tsx@@ -145,10 +145,10 @@ export function PlanQuality({? currentModelNames.get(sample.model_configuration_id) ?? sample.model_configuration_id: text('实际模型未记录', 'Executed model not recorded');return <article className="quality-row" key={sample.segment_id}>- <div className="quality-row-main"><strong title={sample.model_configuration_id ?? undefined}>{modelName}</strong><span>{branchText(sample)} · turn {sample.first_turn_ordinal}–{sample.last_observed_turn_ordinal}</span><span>{new Date(sample.last_at_ms).toLocaleString(language === 'zh' ? 'zh-CN' : 'en')} · plan r{sample.plan_revision}</span></div>+ <div className="quality-row-main"><strong title={sample.model_configuration_id ?? undefined}>{modelName}</strong><span>{branchText(sample)} · {text(`轮次 ${sample.first_turn_ordinal}–${sample.last_observed_turn_ordinal}`, `turn ${sample.first_turn_ordinal}–${sample.last_observed_turn_ordinal}`)}</span><span>{new Date(sample.last_at_ms).toLocaleString(language === 'zh' ? 'zh-CN' : 'en')} · {text(`计划版本 r${sample.plan_revision}`, `plan r${sample.plan_revision}`)}</span></div><div className="quality-score"><strong>{scoreText(sample)}</strong><span>{text('胜任度', 'Competence')}</span></div><div className="quality-flags">{incomplete && <span className="badge warn no-dot">{text('部分证据', 'Partial')}</span>}{!sample.assessment && <span className="badge no-dot">{text('待评分', 'Unrated')}</span>}</div>- {sample.assessment && <p className="quality-coverage">{text(`评分覆盖 turn ${sample.assessment.target_from_ordinal}–${sample.assessment.target_through_ordinal}`, `Assessed turns ${sample.assessment.target_from_ordinal}–${sample.assessment.target_through_ordinal}`)}</p>}+ {sample.assessment && <p className="quality-coverage">{text(`评分覆盖轮次 ${sample.assessment.target_from_ordinal}–${sample.assessment.target_through_ordinal}`, `Assessed turns ${sample.assessment.target_from_ordinal}–${sample.assessment.target_through_ordinal}`)}</p>}{sample.assessment?.reason && <p className="quality-reason">{sample.assessment.reason}</p>}<div className="quality-evidence-actions"><button className="btn btn-quiet" type="button" disabled={!executionRequestId || !onOpenEvidence} onClick={() => executionRequestId && onOpenEvidence?.(sample.session_id, executionRequestId)}>{executionRequestId ? text('执行证据', 'Execution evidence') : text('执行证据不可用', 'Execution unavailable')}</button>{sample.assessment && <button className="btn btn-quiet" type="button" disabled={!feedbackRequestId || !onOpenEvidence} onClick={() => feedbackRequestId && onOpenEvidence?.(sample.session_id, feedbackRequestId)}>{feedbackRequestId ? text('评分触发反馈', 'Assessment feedback') : text('反馈不可用', 'Feedback unavailable')}</button>}</div></article>;diff --git a/apps/website/content/guides/cli.zh.md b/apps/website/content/guides/cli.zh.mdindex 095277c1..a98797b1 100644--- a/apps/website/content/guides/cli.zh.md+++ b/apps/website/content/guides/cli.zh.md@@ -1,11 +1,11 @@# HiRoute CLI-HiRoute CLI 是 HiRoute 本机服务的正式终端入口,可连接 Desktop,也可以作为 Linux headless 的完整管理界面。模型来源、智能路由、Agent 接入、会话观测和 Worker 任务都复用与 Desktop 相同的生产路径,不存在第二套 headless 控制面。+HiRoute CLI 是 HiRoute 本机服务的正式终端入口,可连接桌面应用,也可以作为 Linux 无界面版的完整管理界面。模型来源、智能路由、Agent 接入、会话观测和 Worker 任务都复用与桌面应用相同的生产路径,不存在第二套无界面控制面。## 安装与检查-- macOS Desktop:打开“设置” → “CLI” → “终端入口”,选择“安装”。-- Linux headless:按 [Linux headless 安装](/docs/install-linux/) 使用官网一行命令安装,再显式启动服务。+- macOS 桌面应用:打开“设置” → “CLI” → “终端入口”,选择“安装”。+- Linux 无界面版:按 [Linux 无界面版安装](/docs/install-linux/) 使用官网一行命令安装,再显式启动服务。如果 PATH 不包含入口目录,把下面一行加入 shell 配置后重新打开终端:@@ -21,7 +21,7 @@ hiroute schema list --output jsonhiroute schema show --command-id worker.exec --output json```-CLI 入口与本机服务状态相互独立。如果命令提示服务不可用,Desktop 用户先打开应用;standalone 用户运行 `hiroute service status`,并在需要时运行 `hiroute service start`。CLI 不会替你自动启动服务或重放失败请求。+CLI 入口与本机服务状态相互独立。如果命令提示服务不可用,桌面应用用户先打开应用;独立服务版(standalone)用户运行 `hiroute service status`,并在需要时运行 `hiroute service start`。CLI 不会替你自动启动服务或重放失败请求。## 两层命令合同@@ -46,7 +46,7 @@ hiroute routing apply --help## 管理模型、路由与 Agent-当前 Released CLI 支持完整 headless 闭环:+当前已发布的 CLI 支持完整无界面闭环:- `compute scan/list/show` 发现和读取模型来源;`compute connection options/test/preview/apply/authorize` 检查并保存连接。- `models show` 查看候选模型能力。diff --git a/apps/website/content/guides/install-linux.zh.md b/apps/website/content/guides/install-linux.zh.mdindex da887c0c..49ca0ce4 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 headless+# 在 Linux 上以无界面模式运行 HiRoute-Linux headless 把 HiRoute 的本机服务、Gateway、CLI 和 Agent 管理 Skill 安装到当前用户目录,适合服务器、远程工作站和无图形界面的自动化环境。它不是精简的只读客户端:模型来源、智能路由、Agent 接入、会话观测和任务委派都可以从 CLI 完成。+Linux 无界面版把 HiRoute 的本机服务、Gateway、CLI 和 Agent 管理 Skill 安装到当前用户目录,适合服务器、远程工作站和无图形界面的自动化环境。它不是精简的只读客户端:模型来源、智能路由、Agent 接入、会话观测和任务委派都可以从 CLI 完成。当前公开产品验证以 Linux 为准,支持 `x86_64` 和 `aarch64`。不需要 `sudo`;需要 `curl`、Python 3,以及能够运行 HiRoute 二进制的 glibc Linux 环境。@@ -26,7 +26,7 @@ sh install.shexport PATH="$HOME/.local/bin:$PATH"```-安装脚本只选择官网发布清单中的最新稳定 Linux 包。现有安装器会核对目标架构、归档 SHA256、闭合文件清单和逐文件摘要;官网脚本不复制第二套安装逻辑。Desktop 与 standalone 不应在同一个 `HOME` 中同时管理服务。+安装脚本只选择官网发布清单中的最新稳定 Linux 包。现有安装器会核对目标架构、归档 SHA256、闭合文件清单和逐文件摘要;官网脚本不复制第二套安装逻辑。桌面应用与独立服务版(standalone)不应在同一个 `HOME` 中同时管理服务。## 2. 显式启动服务@@ -85,7 +85,7 @@ hiroute sessions status --output json写操作遵循同一个安全流程:先读取 schema 和 options,执行有界 test,再把同一份变更送入 `preview`;确认 preview 的摘要、revision 和影响后才执行 `apply`。密码或 API key 通过 `protected-input` 传入,不放进普通 JSON、参数或日志。-## 4. 完成 headless 配置+## 4. 完成无界面配置按下面顺序建立第一条路由:@@ -95,7 +95,7 @@ hiroute sessions status --output json4. 用 `agents scan/list/check` 发现本机 Agent,再用 `agents connect preview/apply/status` 接入。恢复时使用 `agents restore preview/apply`,HiRoute 只撤销仍由自己拥有的配置字段。5. 从 Agent 发起真实请求后,用 `sessions list/show/receipt/status` 查看路由事实和用量,用 `value show` 查看已有价格证据下的价值记录。-这些不是另一套 headless 控制面;CLI 与 Desktop 调用相同的 Application、Local Control、存储、发布和恢复路径。+这些不是另一套无界面控制面;CLI 与桌面应用调用相同的 Application、Local Control、存储、发布和恢复路径。## 5. 任务委派diff --git a/apps/website/content/guides/install-macos.zh.md b/apps/website/content/guides/install-macos.zh.mdindex 7b7060a8..a250d5a5 100644--- a/apps/website/content/guides/install-macos.zh.md+++ b/apps/website/content/guides/install-macos.zh.md@@ -1,6 +1,6 @@# macOS 安装与首次启动-HiRoute Desktop 当前支持 macOS 15.0 或更高版本。短期提供的是自签名安装包,没有 Apple Developer ID 签名和公证;因此 macOS 会要求你明确确认首次启动。+HiRoute 桌面应用当前支持 macOS 15.0 或更高版本。短期提供的是自签名安装包,没有 Apple Developer ID 签名和公证;因此 macOS 会要求你明确确认首次启动。## 下载正确的安装包@@ -37,7 +37,7 @@ Apple 的 [安全打开 Mac App 说明](https://support.apple.com/zh-cn/102445)## 安装终端入口(可选)-启动 Desktop 后,打开“设置” → “CLI” → “终端入口”,选择“安装”。该操作会把与当前应用配套的入口安装到:+启动桌面应用后,打开“设置” → “CLI” → “终端入口”,选择“安装”。该操作会把与当前应用配套的入口安装到:```text$HOME/.local/bin/hiroute@@ -55,4 +55,4 @@ export PATH="$HOME/.local/bin:$PATH"hiroute --help```-这个终端入口连接 HiRoute 的本机服务;Desktop 应已安装并让本机服务保持可用。更多命令见 [HiRoute CLI](/docs/cli/)。+这个终端入口连接 HiRoute 的本机服务;桌面应用应已安装并让本机服务保持可用。更多命令见 [HiRoute CLI](/docs/cli/)。diff --git a/apps/website/content/guides/model-routing.zh.md b/apps/website/content/guides/model-routing.zh.mdindex b19652b9..b7660ed6 100644--- a/apps/website/content/guides/model-routing.zh.md+++ b/apps/website/content/guides/model-routing.zh.md@@ -2,7 +2,7 @@智能模型路由决定一次 Agent 工作在当前阶段使用哪个模型。HiRoute 只在允许重选的自然边界做决定;普通工具续轮保持原模型,让同一阶段可以持续复用前缀缓存。-下面以 Desktop 页面说明产品概念。Linux headless 使用相同的路由合同,通过 `routing options/list/show/preview/apply` 完成配置;先阅读 [Linux headless 安装](/docs/install-linux/) 和 [HiRoute CLI](/docs/cli/),并以当前安装返回的 schema 为准。+下面以桌面应用页面说明产品概念。Linux 无界面版使用相同的路由合同,通过 `routing options/list/show/preview/apply` 完成配置;先阅读 [Linux 无界面版安装](/docs/install-linux/) 和 [HiRoute CLI](/docs/cli/),并以当前安装返回的 schema 为准。## 先选择一种路由模式diff --git a/apps/website/content/guides/quickstart.zh.md b/apps/website/content/guides/quickstart.zh.mdindex 6a62da7e..c5ff6eaf 100644--- a/apps/website/content/guides/quickstart.zh.md+++ b/apps/website/content/guides/quickstart.zh.md@@ -1,13 +1,13 @@-# Quickstart+# 快速开始-先选择 macOS Desktop 或 Linux headless,再用一条固定模型路由完成第一次接入;熟悉基本路径后按需要启用智能省钱或任务委派。开始使用不要求部署外部决策服务。+先选择 macOS 桌面应用或 Linux 无界面版,再用一条固定模型路由完成第一次接入;熟悉基本路径后按需要启用智能省钱或任务委派。开始使用不要求部署外部决策服务。## 1. 选择运行方式-- **macOS Desktop**:要求 macOS 15.0 或更高版本。公开安装包为自签名构建,下载后先核对 SHA256,再按 [macOS 安装与首次启动](/docs/install-macos/) 的说明打开应用。-- **Linux headless**:面向服务器、远程工作站和自动化环境,按当前用户安装,不需要 `sudo`。按 [Linux headless 安装](/docs/install-linux/) 启动服务并通过 CLI 完成后续配置。+- **macOS 桌面应用**:要求 macOS 15.0 或更高版本。公开安装包为自签名构建,下载后先核对 SHA256,再按 [macOS 安装与首次启动](/docs/install-macos/) 的说明打开应用。+- **Linux 无界面版**:面向服务器、远程工作站和自动化环境,按当前用户安装,不需要 `sudo`。按 [Linux 无界面版安装](/docs/install-linux/) 启动服务并通过 CLI 完成后续配置。-下面第 2–5 步展示 Desktop 的可视化路径。Linux 用户在 headless 指南中通过同一套生产能力完成对应流程。无论使用哪种入口,都先确认本机服务已经就绪;模型路由、会话记录和任务执行都依赖它。+下面第 2–5 步展示桌面应用的可视化路径。Linux 用户在无界面版指南中通过同一套生产能力完成对应流程。无论使用哪种入口,都先确认本机服务已经就绪;模型路由、会话记录和任务执行都依赖它。## 2. 连接一个模型@@ -48,5 +48,5 @@ HiRoute 会保留恢复点。若以后停用模型路由,可以在“连接详- [使用智能模型路由](/docs/model-routing/):理解三种路由模式、切换边界和运行表现。- [使用智能任务路由](/docs/task-routing/):把适合独立执行的工作委派给执行 Agent。-- [Linux headless 安装](/docs/install-linux/):从空环境安装并用 CLI 配置模型、路由和 Agent。+- [Linux 无界面版安装](/docs/install-linux/):从空环境安装并用 CLI 配置模型、路由和 Agent。- [HiRoute CLI](/docs/cli/):从终端管理 HiRoute、查询运行事实、启动任务并恢复不确定的提交。diff --git a/apps/website/content/guides/task-routing.zh.md b/apps/website/content/guides/task-routing.zh.mdindex d2085347..6a77d287 100644--- a/apps/website/content/guides/task-routing.zh.md+++ b/apps/website/content/guides/task-routing.zh.md@@ -2,7 +2,7 @@模型路由决定“这一阶段用哪个模型”,任务路由决定“这项工作交给哪个执行 Agent”。两者可以独立启用,也可以组合使用。-下面先展示 Desktop 配置路径。Linux headless 可以通过 `routing preview/apply` 发布同一份计划,通过 `agents connect preview/apply` 接入 Agent,再使用同一组 Worker 命令执行;具体字段从当前安装的 schema 获取。+下面先展示桌面应用配置路径。Linux 无界面版可以通过 `routing preview/apply` 发布同一份计划,通过 `agents connect preview/apply` 接入 Agent,再使用同一组 Worker 命令执行;具体字段从当前安装的 schema 获取。## 适合委派什么@@ -27,7 +27,7 @@2. 选择允许它发现和调用的已发布计划。3. 保存并完成技能检查。-之后可以在日常对话中明确要求委派;若配置为默认委派,主 Agent 也可以对适合独立执行的工作主动选择计划。任务记录会显示在 Desktop 的“任务”页面。+之后可以在日常对话中明确要求委派;若配置为默认委派,主 Agent 也可以对适合独立执行的工作主动选择计划。任务记录会显示在桌面应用的“任务”页面。## 从终端执行同一条生产路径diff --git a/apps/website/data/releases.json b/apps/website/data/releases.jsonindex 01bdbfe9..6ba79e4b 100644--- a/apps/website/data/releases.json+++ b/apps/website/data/releases.json@@ -6,7 +6,7 @@"channel": "stable","published_at": "2026-09-21T05:14:26Z","notes": {- "zh": "HiRoute 首个公开 MVP:提供 macOS Desktop、Linux headless CLI、智能模型路由、Agent 任务路由与可扩展 Decision API。",+ "zh": "HiRoute 首个公开 MVP:提供 macOS 桌面应用、Linux 无界面 CLI、智能模型路由、Agent 任务路由与可扩展 Decision API。","en": "HiRoute's first public MVP with macOS Desktop, Linux headless CLI, intelligent model routing, Agent task routing, and an extensible Decision API."},"artifacts": [diff --git a/apps/website/scripts/validate-build.mjs b/apps/website/scripts/validate-build.mjsindex e29fdd9e..60530f91 100644--- a/apps/website/scripts/validate-build.mjs+++ b/apps/website/scripts/validate-build.mjs@@ -34,4 +34,28 @@ for (const file of htmlFiles) {if (!fs.existsSync(candidate)) throw new Error(`broken local reference in ${file}: ${target}`);}}++for (const file of htmlFiles.filter(file => path.relative(dist, file).startsWith(`en${path.sep}`))) {+ const html = fs.readFileSync(file, 'utf8').replaceAll('中文', '');+ if (/[\u3400-\u9fff]/u.test(html)) throw new Error(`Chinese copy leaked into English page: ${file}`);+}++const untranslatedChinesePageCopy = [+ 'Intelligent routing for long-horizon agents.',+ 'ONE TASK. MANY DECISIONS.',+ 'Powered by TypeSafe Jev',+ 'Evidence for the next decision',+ 'From evidence to better delegation',+ 'Agent ecosystem',+ 'Your policy, one interface',+ 'Start with HiRoute',+ 'Questions',+ 'CHANGELOG',+ 'DOWNLOAD',+];+for (const file of htmlFiles.filter(file => !path.relative(dist, file).startsWith(`en${path.sep}`))) {+ const html = fs.readFileSync(file, 'utf8');+ const leaked = untranslatedChinesePageCopy.find(value => html.includes(value));+ if (leaked) throw new Error(`English copy leaked into Chinese page ${file}: ${leaked}`);+}console.log(`Validated ${htmlFiles.length} static HTML pages and ${required.length} required outputs.`);diff --git a/apps/website/src/components/ChangelogPage.astro b/apps/website/src/components/ChangelogPage.astroindex 7758bd58..16bbcbc0 100644--- a/apps/website/src/components/ChangelogPage.astro+++ b/apps/website/src/components/ChangelogPage.astro@@ -4,12 +4,13 @@ import { releaseManifest } from '../lib/releases.mjs';const { language = 'zh' } = Astro.props;const en = language === 'en';const t = (zh, english) => en ? english : zh;+const channelLabel = channel => en ? channel : channel === 'stable' ? '稳定版' : channel === 'preview' ? '预览版' : channel;const path = en ? '/en/changelog/' : '/changelog/';const alternatePath = en ? '/changelog/' : '/en/changelog/';---<SiteLayout language={language} title={t('更新日志', 'Changelog') + ' · HiRoute'}description={t('HiRoute 公开版本更新记录。', 'Public HiRoute release notes.')}path={path} alternatePath={alternatePath}>- <section class="page-hero wrap"><div class="eyebrow section-label">CHANGELOG</div><h1>{t('更新日志', 'Changelog')}</h1><p>{t('与下载页共用同一份发布清单,不单独维护容易漂移的版本列表。', 'Generated from the same release manifest as the download page—no separate version list to drift.')}</p></section>- <section class="content-section wrap changelog-list">{releaseManifest.releases.length === 0 ? <div class="empty-release"><h2>{t('尚无公开版本', 'No public releases yet')}</h2><p>{t('首个通过公开发布门槛的版本会显示在这里。', 'The first release admitted by the public release gates will appear here.')}</p></div> : releaseManifest.releases.map(release => <article><span>{release.channel}</span><h2>HiRoute {release.version}</h2><time datetime={release.published_at}>{new Intl.DateTimeFormat(en ? 'en' : 'zh-CN', { dateStyle: 'long' }).format(new Date(release.published_at))}</time><p>{release.notes[language]}</p><a href={en ? '/en/download/' : '/download/'}>{t('下载与摘要', 'Downloads and checksums')} →</a></article>)}</section>+ <section class="page-hero wrap"><div class="eyebrow section-label">{t('更新日志', 'CHANGELOG')}</div><h1>{t('更新日志', 'Changelog')}</h1><p>{t('与下载页共用同一份发布清单,不单独维护容易漂移的版本列表。', 'Generated from the same release manifest as the download page—no separate version list to drift.')}</p></section>+ <section class="content-section wrap changelog-list">{releaseManifest.releases.length === 0 ? <div class="empty-release"><h2>{t('尚无公开版本', 'No public releases yet')}</h2><p>{t('首个通过公开发布门槛的版本会显示在这里。', 'The first release admitted by the public release gates will appear here.')}</p></div> : releaseManifest.releases.map(release => <article><span>{channelLabel(release.channel)}</span><h2>HiRoute {release.version}</h2><time datetime={release.published_at}>{new Intl.DateTimeFormat(en ? 'en' : 'zh-CN', { dateStyle: 'long' }).format(new Date(release.published_at))}</time><p>{release.notes[language]}</p><a href={en ? '/en/download/' : '/download/'}>{t('下载与摘要', 'Downloads and checksums')} →</a></article>)}</section></SiteLayout>diff --git a/apps/website/src/components/DocsNav.astro b/apps/website/src/components/DocsNav.astroindex dc2d8457..c907cbf1 100644--- a/apps/website/src/components/DocsNav.astro+++ b/apps/website/src/components/DocsNav.astro@@ -5,9 +5,9 @@ const prefix = en ? '/en' : '';---<aside class="docs-nav" aria-label={en ? 'HiRoute documentation' : 'HiRoute 文档'}><span>{en ? 'GET STARTED' : '开始使用'}</span>- <a class:list={{active:active === 'quickstart'}} href={`${prefix}/docs/`}>Quickstart</a>+ <a class:list={{active:active === 'quickstart'}} href={`${prefix}/docs/`}>{en ? 'Quickstart' : '快速开始'}</a><a class:list={{active:active === 'install-macos'}} href={`${prefix}/docs/install-macos/`}>{en ? 'Install on macOS' : 'macOS 安装与首次启动'}</a>- <a class:list={{active:active === 'install-linux'}} href={`${prefix}/docs/install-linux/`}>{en ? 'Linux headless' : 'Linux headless 安装'}</a>+ <a class:list={{active:active === 'install-linux'}} href={`${prefix}/docs/install-linux/`}>{en ? 'Linux headless' : 'Linux 无界面版安装'}</a><span>{en ? 'USE HIROUTE' : '使用 HIROUTE'}</span><a class:list={{active:active === 'model-routing'}} href={`${prefix}/docs/model-routing/`}>{en ? 'Smart model routing' : '智能模型路由'}</a>diff --git a/apps/website/src/components/DownloadPage.astro b/apps/website/src/components/DownloadPage.astroindex c11235b5..174a1d20 100644--- a/apps/website/src/components/DownloadPage.astro+++ b/apps/website/src/components/DownloadPage.astro@@ -4,6 +4,7 @@ import { artifactManifestUrl, artifactUrl, formatBytes, releaseManifest } from 'const { language = 'zh' } = Astro.props;const en = language === 'en';const t = (zh, english) => en ? english : zh;+const channelLabel = channel => en ? channel : channel === 'stable' ? '稳定版' : channel === 'preview' ? '预览版' : channel;const path = en ? '/en/download/' : '/download/';const alternatePath = en ? '/download/' : '/en/download/';const stable = releaseManifest.releases.find(release => release.channel === 'stable');@@ -13,12 +14,12 @@ const stableLinux = stable?.artifacts.filter(artifact => artifact.kind === 'stanconst linuxArchitectures = stableLinux.map(artifact => artifact.architecture).join(' / ');---<SiteLayout language={language} title={t('下载 HiRoute', 'Download HiRoute') + ' · HiRoute'}- description={t('在 macOS 使用 Desktop,或在 Linux 用一条命令安装 HiRoute headless。', 'Use HiRoute Desktop on macOS or install HiRoute headless on Linux with one command.')}+ description={t('在 macOS 使用桌面应用,或在 Linux 用一条命令安装 HiRoute 无界面版。', 'Use HiRoute Desktop on macOS or install HiRoute headless on Linux with one command.')}path={path} alternatePath={alternatePath}>- <section class="page-hero wrap"><div class="eyebrow section-label">DOWNLOAD</div><h1>{t('选择你的运行方式', 'Choose how to run HiRoute')}</h1><p>{t('macOS 提供可视化 Desktop;Linux 提供面向服务器和自动化环境的 headless CLI。发布文件都来自 hiroute.ai 的不可变 OSS 对象,并公开版本与 SHA256。', 'macOS provides the visual Desktop app. Linux provides a headless CLI for servers and automation. Every published file is an immutable hiroute.ai OSS object with a declared version and SHA256.')}</p></section>+ <section class="page-hero wrap"><div class="eyebrow section-label">{t('下载', 'DOWNLOAD')}</div><h1>{t('选择你的运行方式', 'Choose how to run HiRoute')}</h1><p>{t('macOS 提供可视化桌面应用;Linux 提供面向服务器和自动化环境的无界面命令行。发布文件都来自 hiroute.ai 的不可变 OSS 对象,并公开版本与 SHA256。', 'macOS provides the visual Desktop app. Linux provides a headless CLI for servers and automation. Every published file is an immutable hiroute.ai OSS object with a declared version and SHA256.')}</p></section><section class="content-section wrap platform-install">- <div class="platform-heading"><div><span class="release-channel">Linux · headless</span><h2>{t('一条命令,按当前用户安装', 'One command, installed for the current user')}</h2><p>{t('安装器识别 x86_64 或 aarch64,下载稳定版的不可变 manifest 和归档,验证内容后安装到 ~/.local;不使用 sudo,也不会自动启动服务。', 'The installer detects x86_64 or aarch64, downloads the stable immutable manifest and archive, verifies them, and installs under ~/.local. It uses no sudo and does not start the service automatically.')}</p></div><a class="text-link" href={en ? '/en/docs/install-linux/' : '/docs/install-linux/'}>{t('Linux headless 指南', 'Linux headless guide')} →</a></div>+ <div class="platform-heading"><div><span class="release-channel">{t('Linux · 无界面版', 'Linux · headless')}</span><h2>{t('一条命令,按当前用户安装', 'One command, installed for the current user')}</h2><p>{t('安装器识别 x86_64 或 aarch64,下载稳定版的不可变清单和归档,验证内容后安装到 ~/.local;不使用 sudo,也不会自动启动服务。', 'The installer detects x86_64 or aarch64, downloads the stable immutable manifest and archive, verifies them, and installs under ~/.local. It uses no sudo and does not start the service automatically.')}</p></div><a class="text-link" href={en ? '/en/docs/install-linux/' : '/docs/install-linux/'}>{t('Linux 无界面版指南', 'Linux headless guide')} →</a></div><div class:list={['install-command', { unavailable: stableLinux.length === 0 }]}><span>{stableLinux.length > 0 ? t(`稳定版 ${stable.version} · ${linuxArchitectures}`, `Stable ${stable.version} · ${linuxArchitectures}`) : t('首个 Linux 稳定包准备中', 'First stable Linux package in preparation')}</span><pre><code>curl -fsSL https://hiroute.ai/install.sh | sh</code></pre>@@ -30,9 +31,9 @@ sh install.sh</code></pre></details></section><section class="content-section wrap release-section">- <div class="platform-heading"><div><span class="release-channel">macOS · Desktop / {t('手动包', 'manual packages')}</span><h2>{t('版本与发布文件', 'Versions and release files')}</h2><p>{t('Desktop 直接下载 DMG;Linux 一行安装是推荐入口,归档与伴随 manifest 仍保留给离线、镜像和审计场景。', 'Download a DMG for Desktop. The one-line command is the recommended Linux path; archives and companion manifests remain available for offline, mirroring, and audit workflows.')}</p></div></div>- {shown.length === 0 ? <div class="empty-release"><span>{t('准备中', 'IN PREPARATION')}</span><h2>{t('首个公开版本尚未发布', 'The first public release is not published yet')}</h2><p>{t('安装包通过完整性检查、安装走查和发布审核后才会出现在这里。你可以先阅读 Quickstart。', 'Packages appear here only after integrity checks, installation review, and release approval. Start with the Quickstart in the meantime.')}</p><div class="actions"><a class="button" href={en ? '/en/docs/' : '/docs/'}>Quickstart ↗</a></div></div> : shown.map(release => <article class="release-card"><div class="release-heading"><div><span class="release-channel">{release.channel}</span><h2>HiRoute {release.version}</h2><p>{release.notes[language]}</p></div><time datetime={release.published_at}>{new Intl.DateTimeFormat(en ? 'en' : 'zh-CN', { dateStyle: 'long' }).format(new Date(release.published_at))}</time></div><div class="artifact-list">{release.artifacts.map(artifact => artifact.kind === 'desktop' ? <div class="artifact-row"><div><strong>macOS Desktop · {artifact.architecture}</strong><span>{t(`最低 macOS ${artifact.minimum_os}`, `macOS ${artifact.minimum_os}+`)}</span><span class:list={['distribution-badge', { 'self-signed': artifact.distribution === 'self-signed' }]}>{artifact.distribution === 'self-signed' ? t('自签名 · 首次启动需手动确认', 'Self-signed · manual approval required on first launch') : t('Developer ID 签名与公证', 'Developer ID signed and notarized')}</span><code>SHA256 {artifact.sha256}</code></div><a class="button" href={artifactUrl(release, artifact)}>{t('下载 DMG', 'Download DMG')} · {formatBytes(artifact.size, language)}</a></div> : <div class="artifact-row"><div><strong>Linux headless · {artifact.architecture}</strong><span>{artifact.target} · {formatBytes(artifact.size, language)}</span><span class="distribution-badge">{t('未签名 · manifest 与 SHA256 验证', 'Unsigned · manifest and SHA256 verified')}</span><code>SHA256 {artifact.sha256}</code><a class="companion-link" href={artifactManifestUrl(release, artifact)} download>{t('下载伴随 manifest', 'Download companion manifest')}</a></div><a class="button outline" href={artifactUrl(release, artifact)}>{t('手动下载归档', 'Manual archive')} ↓</a></div>)}</div></article>)}+ <div class="platform-heading"><div><span class="release-channel">macOS · {t('桌面应用 / 手动包', 'Desktop / manual packages')}</span><h2>{t('版本与发布文件', 'Versions and release files')}</h2><p>{t('桌面应用直接下载 DMG;Linux 一行安装是推荐入口,归档与伴随清单仍保留给离线、镜像和审计场景。', 'Download a DMG for Desktop. The one-line command is the recommended Linux path; archives and companion manifests remain available for offline, mirroring, and audit workflows.')}</p></div></div>+ {shown.length === 0 ? <div class="empty-release"><span>{t('准备中', 'IN PREPARATION')}</span><h2>{t('首个公开版本尚未发布', 'The first public release is not published yet')}</h2><p>{t('安装包通过完整性检查、安装走查和发布审核后才会出现在这里。你可以先阅读快速开始。', 'Packages appear here only after integrity checks, installation review, and release approval. Start with the Quickstart in the meantime.')}</p><div class="actions"><a class="button" href={en ? '/en/docs/' : '/docs/'}>{t('快速开始', 'Quickstart')} ↗</a></div></div> : shown.map(release => <article class="release-card"><div class="release-heading"><div><span class="release-channel">{channelLabel(release.channel)}</span><h2>HiRoute {release.version}</h2><p>{release.notes[language]}</p></div><time datetime={release.published_at}>{new Intl.DateTimeFormat(en ? 'en' : 'zh-CN', { dateStyle: 'long' }).format(new Date(release.published_at))}</time></div><div class="artifact-list">{release.artifacts.map(artifact => artifact.kind === 'desktop' ? <div class="artifact-row"><div><strong>{t('macOS 桌面应用', 'macOS Desktop')} · {artifact.architecture}</strong><span>{t(`最低 macOS ${artifact.minimum_os}`, `macOS ${artifact.minimum_os}+`)}</span><span class:list={['distribution-badge', { 'self-signed': artifact.distribution === 'self-signed' }]}>{artifact.distribution === 'self-signed' ? t('自签名 · 首次启动需手动确认', 'Self-signed · manual approval required on first launch') : t('Developer ID 签名与公证', 'Developer ID signed and notarized')}</span><code>SHA256 {artifact.sha256}</code></div><a class="button" href={artifactUrl(release, artifact)}>{t('下载 DMG', 'Download DMG')} · {formatBytes(artifact.size, language)}</a></div> : <div class="artifact-row"><div><strong>{t('Linux 无界面版', 'Linux headless')} · {artifact.architecture}</strong><span>{artifact.target} · {formatBytes(artifact.size, language)}</span><span class="distribution-badge">{t('未签名 · 清单与 SHA256 验证', 'Unsigned · manifest and SHA256 verified')}</span><code>SHA256 {artifact.sha256}</code><a class="companion-link" href={artifactManifestUrl(release, artifact)} download>{t('下载伴随清单', 'Download companion manifest')}</a></div><a class="button outline" href={artifactUrl(release, artifact)}>{t('手动下载归档', 'Manual archive')} ↓</a></div>)}</div></article>)}</section>- <section class="content-section wrap install-note"><h2>{t('安装边界', 'Installation boundaries')}</h2><ol><li>{t('Linux headless 是当前用户安装,不要求 root;Desktop 与 standalone 不应在同一 HOME 中同时管理服务。', 'Linux headless is a per-user installation with no root requirement. Desktop and standalone must not manage the service in the same HOME.')}</li><li>{t('Linux 安装不会自动启动服务;安装完成后由你显式启动并检查状态。', 'Linux installation never starts the service automatically; start it explicitly and verify status after installation.')}</li><li>{t('macOS Desktop 当前要求 macOS 15.0 或更高版本,架构必须与设备匹配。', 'The current Desktop package requires macOS 15.0 or later and must match the device architecture.')}</li></ol><div class="self-signed-note"><strong>{t('关于 macOS 自签名版本', 'About self-signed macOS builds')}</strong><p>{t('短期发布没有 Apple Developer ID 签名和公证。macOS 首次阻止启动时,请在“系统设置 → 隐私与安全性”中确认“仍要打开”;不需要关闭 Gatekeeper 或 SIP。', 'Near-term releases do not have an Apple Developer ID signature or notarization. If macOS blocks the first launch, approve Open Anyway under System Settings → Privacy & Security. Do not disable Gatekeeper or SIP.')}</p><a class="text-link" href={en ? '/en/docs/install-macos/' : '/docs/install-macos/'}>{t('查看完整 macOS 步骤', 'Read the macOS installation steps')} →</a></div><a class="text-link" href={en ? '/en/changelog/' : '/changelog/'}>{t('查看更新日志', 'View changelog')} →</a></section>+ <section class="content-section wrap install-note"><h2>{t('安装边界', 'Installation boundaries')}</h2><ol><li>{t('Linux 无界面版按当前用户安装,不要求 root;桌面应用与独立服务版(standalone)不应在同一 HOME 中同时管理服务。', 'Linux headless is a per-user installation with no root requirement. Desktop and standalone must not manage the service in the same HOME.')}</li><li>{t('Linux 安装不会自动启动服务;安装完成后由你显式启动并检查状态。', 'Linux installation never starts the service automatically; start it explicitly and verify status after installation.')}</li><li>{t('macOS 桌面应用当前要求 macOS 15.0 或更高版本,架构必须与设备匹配。', 'The current Desktop package requires macOS 15.0 or later and must match the device architecture.')}</li></ol><div class="self-signed-note"><strong>{t('关于 macOS 自签名版本', 'About self-signed macOS builds')}</strong><p>{t('短期发布没有 Apple Developer ID 签名和公证。macOS 首次阻止启动时,请在“系统设置 → 隐私与安全性”中确认“仍要打开”;不需要关闭 Gatekeeper 或 SIP。', 'Near-term releases do not have an Apple Developer ID signature or notarization. If macOS blocks the first launch, approve Open Anyway under System Settings → Privacy & Security. Do not disable Gatekeeper or SIP.')}</p><a class="text-link" href={en ? '/en/docs/install-macos/' : '/docs/install-macos/'}>{t('查看完整 macOS 步骤', 'Read the macOS installation steps')} →</a></div><a class="text-link" href={en ? '/en/changelog/' : '/changelog/'}>{t('查看更新日志', 'View changelog')} →</a></section></SiteLayout>diff --git a/apps/website/src/components/HomePage.astro b/apps/website/src/components/HomePage.astroindex 67b2bae3..bcdce75f 100644--- a/apps/website/src/components/HomePage.astro+++ b/apps/website/src/components/HomePage.astro@@ -10,7 +10,7 @@ const release = latestRelease('stable');const preferredArtifact = release?.artifacts.find(item => item.kind === 'desktop' && item.architecture === 'arm64')?? release?.artifacts.find(item => item.kind === 'desktop');const linuxArtifact = release?.artifacts.find(item => item.kind === 'standalone');-const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Linux headless'].filter(Boolean).join(' / ');+const releaseKinds = [preferredArtifact && t('macOS 桌面应用', 'macOS Desktop'), linuxArtifact && t('Linux 无界面版', 'Linux headless')].filter(Boolean).join(' / ');---<SiteLayout language={language}title={t('HiRoute · 长程 Agent 智能路由引擎', 'HiRoute · Intelligent routing for long-horizon agents')}@@ -18,7 +18,7 @@ const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Lipath={path} alternatePath={alternatePath} fullWidth><section class="hero wrap"><div>- <div class="eyebrow section-label">Intelligent routing for long-horizon agents.</div>+ <div class="eyebrow section-label">{t('面向长程 Agent 的智能路由', 'Intelligent routing for long-horizon agents.')}</div><h1>{en ? <><span>Intelligent routing</span><span>for long-horizon agents.</span></> : <><span>为长程 Agent 而生的</span><span>智能路由引擎。</span></>}</h1><p class="intro">{t('一段长任务,不必始终依赖同一个模型。按任务选择 Agent,再根据执行表现与后续工作的需要,决定继续使用还是切换模型。', 'A long task need not rely on one model from start to finish. Match the agent to the task, then choose the right model for each stage—guided by past performance and the work ahead.')}</p><a class="jev-callout" href="#how"><strong>Jev</strong><span>{t('官方决策扩展 · 一次调用,选择与评分', 'Official extension · One call to choose and assess')}</span><span aria-hidden="true">↗</span></a>@@ -26,7 +26,7 @@ const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Li<p class="small-note">{t('开发、研究、分析与自动化。保留惯用工作流,按需投入算力。', 'Code, research, analysis, and automation. Keep your workflow and spend compute where it counts.')}</p></div><div class="engine-map">- <div class="route-top"><span>ONE TASK. MANY DECISIONS.</span><span>{t('机制示意', 'MECHANISM')}</span></div>+ <div class="route-top"><span>{t('一个任务,多次决策', 'ONE TASK. MANY DECISIONS.')}</span><span>{t('机制示意', 'MECHANISM')}</span></div><div class="engine-goal"><span>{t('一个长程目标', 'One long-horizon goal')}</span><strong>{t('理解 → 规划 → 执行 → 验证', 'Understand → Plan → Execute → Verify')}</strong></div><div class="engine-link" aria-hidden="true">↓</div><div class="engine-agent"><span>{t('主 Agent / 执行 Agent', 'Main agent / Execution agent')}</span><small>{t('按用途选择工作计划,保留惯用工作流', 'Choose a work plan by purpose; keep the familiar workflow')}</small></div>@@ -39,7 +39,7 @@ const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Li<div class="trust-line wrap"><span><b>{t('更省', 'Efficient')}</b> · {t('按需投入算力', 'Compute where it counts')}</span><span><b>{t('更稳', 'Reliable')}</b> · {t('有边界地接力', 'Bounded failover')}</span><span><b>{t('更懂', 'Adaptive')}</b> · {t('用执行事实改进选择', 'Decisions grounded in execution')}</span></div><section class="section wrap lifecycle-section" id="boundaries">- <div class="section-title"><div><div class="eyebrow section-label">01 / A long task is not one model choice</div><h2>{t('阶段内保持稳定,', 'Stay stable within a stage.')}<br>{t('在自然边界重新选择。', 'Choose again at natural boundaries.')}</h2></div><p>{t('不必等用户再次提问。Agent 自主执行时,ContextHold 允许切换的上下文重建也能成为决策机会;持续追加的工具续轮保持稳定。', 'A new user prompt is not the only boundary. A ContextHold boundary can also trigger a decision, while ordinary tool continuations stay stable.')}</p></div>+ <div class="section-title"><div><div class="eyebrow section-label">{t('01 / 长任务不只做一次模型选择', '01 / A long task is not one model choice')}</div><h2>{t('阶段内保持稳定,', 'Stay stable within a stage.')}<br>{t('在自然边界重新选择。', 'Choose again at natural boundaries.')}</h2></div><p>{t('不必等用户再次提问。Agent 自主执行时,ContextHold 允许切换的上下文重建也能成为决策机会;持续追加的工具续轮保持稳定。', 'A new user prompt is not the only boundary. A ContextHold boundary can also trigger a decision, while ordinary tool continuations stay stable.')}</p></div><div class="timeline-legend"><span class="legend-economy">{t('经济模型', 'Economy model')}</span><span class="legend-primary">{t('主力模型', 'Primary model')}</span><span>{t('选择决策节点查看接续方式 · 机制示例', 'Select a decision point to inspect the handoff · Illustration')}</span></div><div class="timeline-grid"><div class="turn-caption turn-one">{t('用户提出目标 → Agent 自主推进', 'User sets the goal → Agent works autonomously')}<span>{t('同一个用户任务可以跨多个路由执行轮次', 'One user task can span multiple routing turns')}</span></div>@@ -53,34 +53,34 @@ const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Li<div class="boundary-detail" id="boundary-detail" aria-live="polite"><div><span class="detail-kicker" id="boundary-kicker">{t('自主执行中的决策机会', 'A decision point during autonomous work')}</span><h3 id="boundary-title">{t('重建上下文时,可以重新选择。', 'A rebuilt context is a chance to choose again.')}</h3><p id="boundary-copy">{t('ContextHold 判断当前边界允许切换时,HiRoute 重新评估下一段工作;不要求客户端额外报告“发生了压缩”。', 'When ContextHold permits a switch, HiRoute reassesses the work ahead; the client need not send a separate compaction signal.')}</p></div><div class="boundary-outcome"><span>{t('这一节点的示例', 'At this point')}</span><p><b>{t('评估上一阶段', 'Assess the prior stage')}</b><span id="boundary-assessment">{t('回看模型 A 已完成的执行', 'Assess the work already performed by model A')}</span></p><p><b>{t('选择下一分支', 'Choose the next branch')}</b><span id="boundary-choice">{t('选择主力分支,让模型 B 接续', 'Choose the primary branch; model B takes over')}</span></p></div></div></section>- <section class="section wrap" id="product"><div class="section-title"><div><div class="eyebrow section-label">02 / Route the task. Then the compute.</div><h2>{t('按任务选择 Agent,', 'Choose the agent for the task.')}<br>{t('按需要配置模型与算力。', 'Then configure models and compute.')}</h2></div><p>{t('面向开发、研究、复杂分析与通用自动化,不把产品定义绑定在某个 Agent 上。', 'Designed for coding, research, deep analysis, and general automation—not around one hard-coded agent.')}</p></div><div class="features">+ <section class="section wrap" id="product"><div class="section-title"><div><div class="eyebrow section-label">{t('02 / 先选择任务路径,再配置算力', '02 / Route the task. Then the compute.')}</div><h2>{t('按任务选择 Agent,', 'Choose the agent for the task.')}<br>{t('按需要配置模型与算力。', 'Then configure models and compute.')}</h2></div><p>{t('面向开发、研究、复杂分析与通用自动化,不把产品定义绑定在某个 Agent 上。', 'Designed for coding, research, deep analysis, and general automation—not around one hard-coded agent.')}</p></div><div class="features"><article class="feature"><span class="num">01—</span><h3>{t('按用途选择执行 Agent', 'Choose an agent by purpose')}</h3><p>{t('主 Agent 发现开放的工作计划,按目标委派任务并取得结果。任务委派与模型路由可独立启用。', 'A main agent discovers allowed work plans, delegates a goal, and retrieves the result. Delegation and model routing remain independent.')}</p></article><article class="feature"><span class="num">02—</span><h3>{t('按需要配置模型与算力', 'Configure models and compute')}</h3><p>{t('组合模型来源、思考档位和候选顺序;可以智能省钱、固定模型或免费优先。', 'Compose model sources, reasoning profiles, and ordered candidates; use smart saving, fixed, or free-first routing.')}</p></article><article class="feature"><span class="num">03—</span><h3>{t('让接力有边界', 'Keep failover bounded')}</h3><p>{t('候选满足工具、图像和上下文要求;候选耗尽时明确停止,开始交付后不透明换模。', 'Candidates satisfy tool, image, and context requirements; exhaustion stops explicitly and delivery is not silently switched.')}</p></article></div></section>- <section class="night" id="how"><div class="section wrap mechanism"><div><div class="eyebrow section-label">03 / Powered by TypeSafe Jev</div><span class="jev-extension-label">{t('HiRoute 官方决策扩展', 'Official HiRoute decision extension')}</span><h2>{t('用 Jev 选择模型,', 'Let Jev choose the model.')}<br><em>{t('也评价之前的表现。', 'And assess the work so far.')}</em></h2><p class="explain">{t('同一次上游调用选择下一分支,并可对上一阶段给出胜任度评分。不是每个工具 step 都调用一次。', 'One upstream call chooses the next branch and can assess the previous stage. It is not called for every tool step.')}</p><p class="policy-principle">{t('胜任度只负责阻止冒险降本,', 'Competence blocks risky cost-cutting.')}<br>{t('复杂度负责提供降本机会。', 'Complexity creates opportunities to save.')}</p><p class="explain">{t('rules 按简单概率与胜任度门槛执行;auto 综合任务需要和历史表现直接选择。两种模式二选一。', 'Rules applies a simple-task probability and competence floor; auto chooses from task needs and prior performance. Choose one mode.')}</p><a class="button accent" href={en ? '/en/docs/jev-decider/' : '/docs/jev-decider/'}>{t('部署官方 Jev 扩展', 'Deploy the official Jev extension')} ↗</a><p class="jev-optional">{t('Jev 是可选扩展;也可使用内置规则或自建决策服务。', 'Jev is optional; built-in rules and custom decision services remain available.')}</p></div><div class="stage-track">+ <section class="night" id="how"><div class="section wrap mechanism"><div><div class="eyebrow section-label">{t('03 / 由 TypeSafe Jev 提供决策能力', '03 / Powered by TypeSafe Jev')}</div><span class="jev-extension-label">{t('HiRoute 官方决策扩展', 'Official HiRoute decision extension')}</span><h2>{t('用 Jev 选择模型,', 'Let Jev choose the model.')}<br><em>{t('也评价之前的表现。', 'And assess the work so far.')}</em></h2><p class="explain">{t('同一次上游调用选择下一分支,并可对上一阶段给出胜任度评分。不是每个工具步骤都调用一次。', 'One upstream call chooses the next branch and can assess the previous stage. It is not called for every tool step.')}</p><p class="policy-principle">{t('胜任度只负责阻止冒险降本,', 'Competence blocks risky cost-cutting.')}<br>{t('复杂度负责提供降本机会。', 'Complexity creates opportunities to save.')}</p><p class="explain">{t('规则模式(rules)按简单概率与胜任度门槛执行;自动模式(auto)综合任务需要和历史表现直接选择。两种模式二选一。', 'Rules applies a simple-task probability and competence floor; auto chooses from task needs and prior performance. Choose one mode.')}</p><a class="button accent" href={en ? '/en/docs/jev-decider/' : '/docs/jev-decider/'}>{t('部署官方 Jev 扩展', 'Deploy the official Jev extension')} ↗</a><p class="jev-optional">{t('Jev 是可选扩展;也可使用内置规则或自建决策服务。', 'Jev is optional; built-in rules and custom decision services remain available.')}</p></div><div class="stage-track"><article class="stage"><span>01</span><div><span class="primitive-label">Score / {t('回看', 'LOOK BACK')}</span><h3>{t('之前的模型,是否胜任?', 'Was the previous model up to the job?')}</h3><p>{t('结合接受的回答、工具状态和用户反馈评价已经发生的执行。', 'Assess completed work from accepted output, tool outcomes, and user feedback.')}</p></div></article><article class="stage"><span>02</span><div><span class="primitive-label">Choice / {t('选择', 'LOOK AHEAD')}</span><h3>{t('接下来的工作,该用哪个分支?', 'Which branch should handle the next stage?')}</h3><p>{t('auto 直接选允许分支;rules 使用简单/复杂概率并以胜任度限制冒险降本。', 'Auto chooses directly; rules uses simple/complex probability with competence as a guardrail.')}</p></div></article><article class="stage"><span>03</span><div><span class="primitive-label">HiRoute / {t('执行与记录', 'EXECUTE AND RETAIN')}</span><h3>{t('让选择生效,让评价有归属', 'Apply the choice and attribute the score')}</h3><p>{t('HiRoute 执行分支,把评分记到此前实际执行的模型阶段。', 'HiRoute executes the branch and records the score against the model’s prior stage.')}</p><a class="text-link" href={en ? '/en/docs/decision-api/' : '/docs/decision-api/'}>{t('查看决策协议', 'Explore the decision contract')} →</a></div></article></div></div></section><section class="section wrap" id="performance">- <div class="section-title"><div><div class="eyebrow section-label">04 / Evidence for the next decision</div><h2>{t('不只知道选了谁,', 'See more than who was chosen.')}<br>{t('也看得见做得怎样。', 'See how the work went.')}</h2></div><p>{t('查看当前计划所选模型一段时间内的阶段胜任度,无需输入内部模型 ID。', 'Review stage competence over time for models selected by the current plan—without typing internal model IDs.')}</p></div>+ <div class="section-title"><div><div class="eyebrow section-label">{t('04 / 为下一次决策保留证据', '04 / Evidence for the next decision')}</div><h2>{t('不只知道选了谁,', 'See more than who was chosen.')}<br>{t('也看得见做得怎样。', 'See how the work went.')}</h2></div><p>{t('查看当前计划所选模型一段时间内的阶段胜任度,无需输入内部模型 ID。', 'Review stage competence over time for models selected by the current plan—without typing internal model IDs.')}</p></div><figure class="product-shot"><img src={`/decision-assets/quality-${en ? 'en' : 'zh-CN'}.png`} alt={t('HiRoute 运行表现界面,包含阶段评分、未评分和部分历史', 'HiRoute runtime performance with stage scores, unrated work, and partial history')} loading="lazy"></figure><p class="caption">{t('真实产品组件 · 演示数据,非模型评测。保留未评分、部分历史和评分尚未覆盖最新轮次等实际状态。', 'Real product components · Illustrative data, not a model benchmark. Unrated, partial, and not-yet-covered turns remain explicit.')}</p>- <div class="proof-bottom"><article><h3>{t('分数始终带着范围', 'A score keeps its scope')}</h3><p>{t('评分属于具体计划、版本、模型和执行阶段;旧评分不会假装覆盖新增 turn。', 'A score belongs to a plan, revision, model, and execution stage; new turns are not silently covered by an older assessment.')}</p></article><article><h3>{t('证据可以帮助细分计划', 'Evidence can refine work plans')}</h3><p>{t('主 Agent 可查询高低分任务,结合证据判断是否需要建立更聚焦的工作场景。', 'A main agent can query high- and low-scoring tasks, inspect evidence, and propose a narrower work plan.')}</p></article></div>- <div class="specialization"><div class="specialization-heading"><span class="eyebrow">From evidence to better delegation</span><h3>{t('任务更聚焦,模型就有更合适的位置。', 'Focused work gives each model a clearer role.')}</h3><p>{t('先看多次执行证据,再决定是否拆出更专门的场景。', 'Inspect repeated execution evidence before proposing a specialized scenario.')}</p></div><div class="specialization-flow"><article><span class="step-number">01 / {t('观察', 'OBSERVE')}</span><h4>{t('同一模型,不同任务表现不同', 'Performance varies by task')}</h4><p>{t('先按计划、版本和任务范围查看阶段证据。', 'Inspect stages by plan, revision, and task scope.')}</p></article><span class="flow-arrow">→</span><article><span class="step-number">02 / {t('细分', 'SPECIALIZE')}</span><h4>{t('明确更聚焦的工作场景', 'Define a narrower scenario')}</h4><p>{t('缩小范围,明确输入与验证条件。', 'Narrow the scope and make acceptance criteria explicit.')}</p></article><span class="flow-arrow">→</span><article><span class="step-number">03 / {t('委派', 'DELEGATE')}</span><h4>{t('把任务交给适合的计划', 'Delegate to the fitting plan')}</h4><p>{t('再观察后续表现,不凭单次低分自动改计划。', 'Observe later performance; one low score never rewrites a plan automatically.')}</p></article></div></div>+ <div class="proof-bottom"><article><h3>{t('分数始终带着范围', 'A score keeps its scope')}</h3><p>{t('评分属于具体计划、版本、模型和执行阶段;旧评分不会假装覆盖新增轮次。', 'A score belongs to a plan, revision, model, and execution stage; new turns are not silently covered by an older assessment.')}</p></article><article><h3>{t('证据可以帮助细分计划', 'Evidence can refine work plans')}</h3><p>{t('主 Agent 可查询高低分任务,结合证据判断是否需要建立更聚焦的工作场景。', 'A main agent can query high- and low-scoring tasks, inspect evidence, and propose a narrower work plan.')}</p></article></div>+ <div class="specialization"><div class="specialization-heading"><span class="eyebrow">{t('从执行证据到更合适的委派', 'From evidence to better delegation')}</span><h3>{t('任务更聚焦,模型就有更合适的位置。', 'Focused work gives each model a clearer role.')}</h3><p>{t('先看多次执行证据,再决定是否拆出更专门的场景。', 'Inspect repeated execution evidence before proposing a specialized scenario.')}</p></div><div class="specialization-flow"><article><span class="step-number">01 / {t('观察', 'OBSERVE')}</span><h4>{t('同一模型,不同任务表现不同', 'Performance varies by task')}</h4><p>{t('先按计划、版本和任务范围查看阶段证据。', 'Inspect stages by plan, revision, and task scope.')}</p></article><span class="flow-arrow">→</span><article><span class="step-number">02 / {t('细分', 'SPECIALIZE')}</span><h4>{t('明确更聚焦的工作场景', 'Define a narrower scenario')}</h4><p>{t('缩小范围,明确输入与验证条件。', 'Narrow the scope and make acceptance criteria explicit.')}</p></article><span class="flow-arrow">→</span><article><span class="step-number">03 / {t('委派', 'DELEGATE')}</span><h4>{t('把任务交给适合的计划', 'Delegate to the fitting plan')}</h4><p>{t('再观察后续表现,不凭单次低分自动改计划。', 'Observe later performance; one low score never rewrites a plan automatically.')}</p></article></div></div></section><section class="section wrap ecosystem-section" id="ecosystem">- <div class="section-title"><div><div class="eyebrow section-label">05 / Agent ecosystem</div><h2>{t('不绑定一种 Agent,', 'Not tied to one agent.')}<br>{t('也不局限于编程。', 'Not limited to coding.')}</h2></div><p>{t('集成状态按真实支持范围开放;当前可用与规划方向明确分开。', 'Integration status follows real support; available and planned paths stay visibly separate.')}</p></div>+ <div class="section-title"><div><div class="eyebrow section-label">{t('05 / Agent 生态', '05 / Agent ecosystem')}</div><h2>{t('不绑定一种 Agent,', 'Not tied to one agent.')}<br>{t('也不局限于编程。', 'Not limited to coding.')}</h2></div><p>{t('集成状态按真实支持范围开放;当前可用与规划方向明确分开。', 'Integration status follows real support; available and planned paths stay visibly separate.')}</p></div><div class="ecosystem-groups"><article><h3>{t('当前适配', 'Available now')}</h3><div class="agent-names"><span>Codex</span><span>Claude Code</span></div></article><article class="ecosystem-planned"><h3>{t('后续方向', 'Planned')}</h3><div class="agent-names"><span>Qoder</span><span>Pi</span><span>DeepSeek Harness</span><span>OpenCode</span><span>Hermes Agent</span><span>OpenClaw</span></div><p>{t('具体顺序按真实适配和验证推进。', 'Order depends on real integration and validation.')}</p></article></div></section><section class="section wrap extension-section" id="extensions">- <div><div class="eyebrow section-label">06 / Your policy, one interface</div><h2>{t('把你的判断方式,', 'Your decision policy.')}<br>{t('接入 HiRoute。', 'One HiRoute interface.')}</h2><p>{t('用 Jev、LLM 或自己的策略实现决策服务。通用协议支持允许分支选择与可选胜任度评分。', 'Build a decision service with Jev, an LLM, or your own policy. The general API supports allowed-branch choice and optional competence scoring.')}</p><a class="text-link" href={en ? '/en/docs/decision-api/' : '/docs/decision-api/'}>{t('决策 API 文档', 'Decision API documentation')} →</a><br><a class="text-link" href="/api/decision.openapi.json" download>{t('下载 OpenAPI', 'Download OpenAPI')} ↓</a></div>- <div class="code-box"><div class="code-heading">DECISION API / SINGLE REQUEST</div><pre><code><span class="accent">POST</span> /v1/decisions+ <div><div class="eyebrow section-label">{t('06 / 一套接口,接入你的策略', '06 / Your policy, one interface')}</div><h2>{t('把你的判断方式,', 'Your decision policy.')}<br>{t('接入 HiRoute。', 'One HiRoute interface.')}</h2><p>{t('用 Jev、LLM 或自己的策略实现决策服务。通用协议支持允许分支选择与可选胜任度评分。', 'Build a decision service with Jev, an LLM, or your own policy. The general API supports allowed-branch choice and optional competence scoring.')}</p><a class="text-link" href={en ? '/en/docs/decision-api/' : '/docs/decision-api/'}>{t('决策 API 文档', 'Decision API documentation')} →</a><br><a class="text-link" href="/api/decision.openapi.json" download>{t('下载 OpenAPI', 'Download OpenAPI')} ↓</a></div>+ <div class="code-box"><div class="code-heading">{t('决策 API / 单次请求', 'DECISION API / SINGLE REQUEST')}</div><pre><code><span class="accent">POST</span> /v1/decisions{"branch_id": "smart_saving_simple",@@ -89,14 +89,14 @@ const releaseKinds = [preferredArtifact && 'macOS Desktop', linuxArtifact && 'Li</section><section class="section wrap" id="start">- <div class="download-row"><div><div class="eyebrow section-label">07 / Start with HiRoute</div><h2>{t('保留工作流,', 'Keep your workflow.')}<br>{t('重新安排算力。', 'Rearrange the compute.')}</h2><p>{release ? t(`稳定版本 ${release.version} 已通过统一发布清单提供 ${releaseKinds}。`, `Stable ${release.version} serves ${releaseKinds} through one release manifest.`) : t('公开版本正在准备中。macOS 使用 Desktop,Linux 可通过一条命令安装完整 headless 管理面。', 'The first public release is being prepared. Use Desktop on macOS or install the complete headless management surface on Linux with one command.')}</p><div class="actions"><a class="button" href={en ? '/en/download/' : '/download/'}>{t('选择安装方式', 'Choose an install path')} ↗</a><a class="button outline" href={en ? '/en/docs/' : '/docs/'}>{t('阅读 Quickstart', 'Read the Quickstart')} ↗</a></div></div>- <div class="download-state">{release && linuxArtifact ? <><b>Linux headless · {release.version}</b><p>{linuxArtifact.architecture} · {formatBytes(linuxArtifact.size, language)}</p><code>curl -fsSL https://hiroute.ai/install.sh | sh</code><a class="text-link" href={en ? '/en/docs/install-linux/' : '/docs/install-linux/'}>{t('查看安装与启动步骤', 'Installation and startup')} →</a><span class="tag">SHA256 {linuxArtifact.sha256.slice(0, 12)}…</span></> : release && preferredArtifact ? <><b>HiRoute {release.version}</b><p>macOS {preferredArtifact.architecture} · {formatBytes(preferredArtifact.size, language)}</p><a class="button download-button" href={artifactUrl(release, preferredArtifact)}>{t('下载 Desktop', 'Download Desktop')}</a><span class="tag">{preferredArtifact.distribution === 'self-signed' ? t('自签名', 'SELF-SIGNED') : 'DEVELOPER ID'} · SHA256 {preferredArtifact.sha256.slice(0, 12)}…</span></> : <><b>{t('Desktop + headless', 'Desktop + headless')}</b><p>{t('发布前先完成完整性检查、安装走查和发布审核。', 'Integrity checks, installation review, and release approval come first.')}</p><span class="tag">{t('准备中', 'IN PREPARATION')}</span></>}</div>+ <div class="download-row"><div><div class="eyebrow section-label">{t('07 / 从 HiRoute 开始', '07 / Start with HiRoute')}</div><h2>{t('保留工作流,', 'Keep your workflow.')}<br>{t('重新安排算力。', 'Rearrange the compute.')}</h2><p>{release ? t(`稳定版本 ${release.version} 已通过统一发布清单提供 ${releaseKinds}。`, `Stable ${release.version} serves ${releaseKinds} through one release manifest.`) : t('公开版本正在准备中。macOS 使用桌面应用,Linux 可通过一条命令安装完整的无界面管理端。', 'The first public release is being prepared. Use Desktop on macOS or install the complete headless management surface on Linux with one command.')}</p><div class="actions"><a class="button" href={en ? '/en/download/' : '/download/'}>{t('选择安装方式', 'Choose an install path')} ↗</a><a class="button outline" href={en ? '/en/docs/' : '/docs/'}>{t('阅读快速开始', 'Read the Quickstart')} ↗</a></div></div>+ <div class="download-state">{release && linuxArtifact ? <><b>{t('Linux 无界面版', 'Linux headless')} · {release.version}</b><p>{linuxArtifact.architecture} · {formatBytes(linuxArtifact.size, language)}</p><code>curl -fsSL https://hiroute.ai/install.sh | sh</code><a class="text-link" href={en ? '/en/docs/install-linux/' : '/docs/install-linux/'}>{t('查看安装与启动步骤', 'Installation and startup')} →</a><span class="tag">SHA256 {linuxArtifact.sha256.slice(0, 12)}…</span></> : release && preferredArtifact ? <><b>HiRoute {release.version}</b><p>macOS {preferredArtifact.architecture} · {formatBytes(preferredArtifact.size, language)}</p><a class="button download-button" href={artifactUrl(release, preferredArtifact)}>{t('下载桌面应用', 'Download Desktop')}</a><span class="tag">{preferredArtifact.distribution === 'self-signed' ? t('自签名', 'SELF-SIGNED') : 'DEVELOPER ID'} · SHA256 {preferredArtifact.sha256.slice(0, 12)}…</span></> : <><b>{t('桌面应用 + 无界面版', 'Desktop + headless')}</b><p>{t('发布前先完成完整性检查、安装走查和发布审核。', 'Integrity checks, installation review, and release approval come first.')}</p><span class="tag">{t('准备中', 'IN PREPARATION')}</span></>}</div></div></section>- <section class="section wrap faq-section" id="faq"><div class="eyebrow section-label">08 / Questions</div><h2>{t('常见问题', 'Frequently asked questions')}</h2>+ <section class="section wrap faq-section" id="faq"><div class="eyebrow section-label">{t('08 / 常见问题', '08 / 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。HiRoute 在 ContextHold 允许重选的自然边界做决定;阶段内连续工具续轮保持模型稳定。实际命中仍取决于模型服务、配置和缓存生命周期。', 'Different models do not share KV cache. HiRoute decides at natural boundaries where ContextHold permits reselection; ordinary tool continuations stay on the same model. Actual hits still depend on provider, configuration, and cache lifetime.')}</p></details>- <details id="history-faq"><summary>{t('上下文重建后,决策服务还能看到历史吗?', 'Can the decision service still see history after context rebuild?')}</summary><p>{t('可以看到 HiRoute 独立维护的简化 Agent-turn 历史:用户问题、接受的回答、工具名称与粗粒度状态、执行分支。它不是完整 transcript,淘汰或重启后可标记为部分历史。', 'It receives HiRoute’s independent simplified Agent-turn history: user input, accepted output, tool names and coarse outcomes, and executed branches. It is not a full transcript and can be marked partial after eviction or restart.')}</p></details>+ <details id="history-faq"><summary>{t('上下文重建后,决策服务还能看到历史吗?', 'Can the decision service still see history after context rebuild?')}</summary><p>{t('可以看到 HiRoute 独立维护的简化 Agent 轮次历史:用户问题、接受的回答、工具名称与粗粒度状态、执行分支。它不是完整对话转录,淘汰或重启后可标记为部分历史。', 'It receives HiRoute’s independent simplified Agent-turn history: user input, accepted output, tool names and coarse outcomes, and executed branches. It is not a full transcript and can be marked partial after eviction or restart.')}</p></details><details><summary>{t('一定要部署 Jev 吗?', 'Must I deploy Jev?')}</summary><p>{t('不需要。内置规则可以开始路由;Jev 是官方可选扩展,也可以按同一 Decision API 实现自己的服务。', 'No. Built-in rules are enough to start; Jev is an optional official extension, and you can implement your own service against the same Decision API.')}</p></details><details><summary>{t('胜任度评分是不是成功率?', 'Is competence a success rate?')}</summary><p>{t('不是。它表达模型对具体执行阶段的胜任程度,必须结合计划、版本、评分覆盖范围和部分证据状态理解。', 'No. It represents competence for a specific execution stage and must be interpreted with plan, revision, assessment coverage, and partial-evidence state.')}</p></details><details><summary>{t('安装包从哪里下载?', 'Where are installers served from?')}</summary><p>{t('下载链接直接指向 hiroute.ai/releases/<版本>/<文件名> 的不可变 OSS 对象;不存在的文件不会回退到首页。', 'Links point directly to immutable OSS objects under hiroute.ai/releases/<version>/<filename>; missing files never fall back to the homepage.')}</p></details>diff --git a/apps/website/src/lib/decision-docs.mjs b/apps/website/src/lib/decision-docs.mjsindex 6df73eb2..d4ecc823 100644--- a/apps/website/src/lib/decision-docs.mjs+++ b/apps/website/src/lib/decision-docs.mjs@@ -34,7 +34,10 @@ const maps = {function rewriteTarget(target, page, language) {if (/^(?:https?:|mailto:|#)/.test(target)) return target;if (target.startsWith('assets/') && target.endsWith('.png')) return `/decision-assets/${path.basename(target)}`;- if (target === '../../docs/smart-saving-model-classification.md') return route(language, 'model-routing');+ if (target === '../../docs/smart-saving-model-classification.md'+ || target === '../../docs/smart-saving-model-classification.zh-CN.md') {+ return route(language, 'model-routing');+ }const mapped = maps[page][target];if (!mapped) throw new Error(`unmapped relative decision-document link in ${page}: ${target}`);return mapped;diff --git a/apps/website/src/lib/user-guides.mjs b/apps/website/src/lib/user-guides.mjsindex fd12a1f8..629224d2 100644--- a/apps/website/src/lib/user-guides.mjs+++ b/apps/website/src/lib/user-guides.mjs@@ -7,9 +7,9 @@ const website = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../.const content = path.join(website, 'content/guides');export const guidePages = {- quickstart: { zh: 'Quickstart', en: 'Quickstart' },+ quickstart: { zh: '快速开始', en: 'Quickstart' },'install-macos': { zh: 'macOS 安装与首次启动', en: 'Install and open HiRoute on macOS' },- 'install-linux': { zh: 'Linux headless 安装', en: 'Install HiRoute headless on Linux' },+ 'install-linux': { zh: 'Linux 无界面版安装', en: 'Install HiRoute headless on Linux' },'model-routing': { zh: '使用智能模型路由', en: 'Use smart model routing' },'task-routing': { zh: '使用智能任务路由', en: 'Use smart task routing' },cli: { zh: 'HiRoute CLI', en: 'HiRoute CLI' },diff --git a/crates/cli/tests/contracts.rs b/crates/cli/tests/contracts.rsindex b1a535fe..eaf0a830 100644--- a/crates/cli/tests/contracts.rs+++ b/crates/cli/tests/contracts.rs@@ -124,7 +124,7 @@ fn packaged_management_skill_explains_discovery_dependency_selection_and_recoverfn packaged_headless_docs_distinguish_host_and_application_discovery() {let docs = include_str!("../../../docs/standalone-cli.md");for required in [- "Host 管理命令",+ "Host management commands","hiroute --help","hiroute service --help","hiroute gateway --help",diff --git a/crates/observation/src/managed_text/README.md b/crates/observation/src/managed_text/README.mdindex 959e6a95..a75b432a 100644--- a/crates/observation/src/managed_text/README.md+++ b/crates/observation/src/managed_text/README.md@@ -1,47 +1,61 @@-# MVP-15 → MVP-20 受管正文内部接口--入口是 `hiroute_observation::managed_text` 的类型和-`LocalObservationStore::managed_text_*` 方法。它们不是公开 RPC,也不签发权限。-Application / 委派执行服务必须用已认证的 task/run 构造 `ManagedTextScope`,-每次读检查内容许可;不能从 Worker payload、环境变量或引用本身取得权限。--## 写入和重试--1. 20 先创建可信 task/run,调用 `managed_text_put(input, now_ms)`。-2. `source_event_id + source_revision + scope` 标识同一事件;重复调用返回同一引用。- 改目的、原始时间或导入来源会产生 `Conflict`,不会刷新七天期限。-3. `append` 以从 0 开始的连续 ordinal 写块,每块 1~65536 bytes。- 同块同 bytes 可重试,不同 bytes 冲突。待写块先登记,完整落盘后才对读者发布。-4. `finish` 提交准确的已完成块数,取得 Complete 引用,再由 20 保存业务引用。- 跨库无分布式事务;业务提交失败重用原引用,内容失败由 20 保留真实任务结果和缺失状态。--`original_created_at_ms` 和 `now_ms` 来自可信生产事件/服务端时钟。-历史导入须给出仍可见的原引用,原截止时间必须相同。没有可证明来源时,-调用方不能把历史冒充新事件。继续旧 run 时应复用旧正文引用及其 scope,-由上层明确授权跨 run 读取;本接口不接受用新 run 身份重新标记原引用。--## 读取和继续--`resolve` 总是读取持久化的当前可见性,不采信引用中缓存的 state/generation。-`read` 每次最多 16 块(1 MiB),返回 `next_chunk`,在文件读取后复核 generation。-读者遇到 Stale 时先重新 resolve;Deleted/Expired/Unavailable 不能回退到本地缓存。-Complete 表示发布完成,不保证磁盘永久无损;正文实际消费还须成功 read。-Storage 错误不可当成空正文或用于证明“历史可继续”。--## 删除、过期和原生缓存--Application 以独立管理授权生成 preview 并取得精确确认后调用 apply。-preview 的 cutoff/count/generation 过时则 Stale;确认之前零删除。-apply 的事务先撤可见性并登记持久化清理记录,然后由 `gc` 每批最多 200 个块回收。-cutoff 以内的迟到事件不会恢复正文;确证 cutoff 之后的新事件可写入。--20 用 `pending_native_cleanup(scope, after_generation, limit)` 恢复未确认的原生缓存清理,-仅处理同 scope、cutoff 内的 HiRoute 受管历史,实际成功后调用 `native_gc_ack`。-通知可以丢失,主动查询和继续仍须检查当前引用。apply 重试返回当前两个 GC 状态;-任一 pending 就不能宣称清理全部完成。`expire_scope` 供 retention worker 调度,-采用每个事件七天截止时间,并使用同一原生清理协议。--生产 maintenance 已调度过期 scope 发现和分批对象 GC;原生缓存清理仍由20确认。-本模块尚需接入完整的会话清理和 Application 授权;本接口测试不代表-MVP-15 或 MVP-20 生产入口验收完成。activity 扩展迁移为本分支意图,最终 schema-编号与公共导出由总协调收敛。+# MVP-15 → MVP-20 managed-text internal interface++[Simplified Chinese](README.zh-CN.md)++The entry points are the types in `hiroute_observation::managed_text` and the+`LocalObservationStore::managed_text_*` methods. They are not public RPCs and do not grant+permissions. Application/delegation services must construct `ManagedTextScope` from an+authenticated task/run and check content permission on every read. Permission cannot be+derived from a Worker payload, environment variable, or reference alone.++## Writes and retries++1. MVP-20 first creates a trusted task/run, then calls `managed_text_put(input, now_ms)`.+2. `source_event_id + source_revision + scope` identifies one event. A repeated call returns+ the same reference. Changing purpose, original time, or import source causes `Conflict`+ and does not refresh the seven-day deadline.+3. `append` writes zero-based contiguous chunks of 1–65,536 bytes. The same bytes for the+ same chunk are retryable; different bytes conflict. A pending chunk is registered before+ it is written and is published to readers only after the complete write succeeds.+4. `finish` commits the exact number of completed chunks and returns a Complete reference;+ MVP-20 then stores the business reference. There is no distributed transaction across+ stores. A failed business commit reuses the original reference, while a content failure+ leaves MVP-20 responsible for preserving the real task result and missing-content state.++`original_created_at_ms` and `now_ms` come from trusted production events and the server+clock. A history import must provide the still-visible original reference with the same+original deadline. Without provable provenance, a caller must not present old content as a+new event. Continuing an old run should reuse its content reference and scope, with explicit+authorization for cross-run access at the upper layer; this interface does not relabel the+reference with a new run identity.++## Reads and continuation++`resolve` always reads current persistent visibility and ignores cached state/generation in+the reference. `read` returns at most 16 chunks (1 MiB) and a `next_chunk`, then verifies the+generation again after file I/O. After Stale, resolve again. Deleted, Expired, or Unavailable+must not fall back to a local cache. Complete means publication finished, not that storage can+never be damaged; consuming the body still requires a successful read. Storage errors are+not empty content and cannot prove that history is resumable.++## Deletion, expiry, and native caches++Application creates a preview under a separate management authorization and calls apply only+after precise confirmation. A stale preview cutoff/count/generation returns Stale, with zero+deletion before confirmation. The apply transaction first removes visibility and records+persistent cleanup work; `gc` then removes at most 200 chunks per batch. Late events at or+before the cutoff do not restore content. Proven events after the cutoff may be written.++MVP-20 uses `pending_native_cleanup(scope, after_generation, limit)` to recover unconfirmed+native-cache cleanup. It handles only HiRoute-managed history in the same scope and at or+before the cutoff, and calls `native_gc_ack` only after actual success. Notifications may be+lost; active queries and continuation must still check the current reference. An apply retry+returns both current GC states and cannot claim full cleanup while either is pending.+`expire_scope` is the retention-worker entry point, using each event's seven-day deadline and+the same native-cleanup protocol.++Production maintenance schedules expired-scope discovery and batched object GC. Native cache+cleanup still requires MVP-20 confirmation. Full session deletion and Application+authorization remain to be integrated; tests for this interface do not establish MVP-15 or+MVP-20 production-entry acceptance. The activity extension migration describes this branch's+intent; the convergence owner owns the final schema number and public export.diff --git a/crates/observation/src/managed_text/README.zh-CN.md b/crates/observation/src/managed_text/README.zh-CN.mdnew file mode 100644index 00000000..7772646c--- /dev/null+++ b/crates/observation/src/managed_text/README.zh-CN.md@@ -0,0 +1,49 @@+# MVP-15 → MVP-20 受管正文内部接口++[English](README.md)++入口是 `hiroute_observation::managed_text` 的类型和+`LocalObservationStore::managed_text_*` 方法。它们不是公开 RPC,也不签发权限。+Application / 委派执行服务必须用已认证的 task/run 构造 `ManagedTextScope`,+每次读检查内容许可;不能从 Worker payload、环境变量或引用本身取得权限。++## 写入和重试++1. 20 先创建可信 task/run,调用 `managed_text_put(input, now_ms)`。+2. `source_event_id + source_revision + scope` 标识同一事件;重复调用返回同一引用。+ 改目的、原始时间或导入来源会产生 `Conflict`,不会刷新七天期限。+3. `append` 以从 0 开始的连续 ordinal 写块,每块 1~65536 bytes。+ 同块同 bytes 可重试,不同 bytes 冲突。待写块先登记,完整落盘后才对读者发布。+4. `finish` 提交准确的已完成块数,取得 Complete 引用,再由 20 保存业务引用。+ 跨库无分布式事务;业务提交失败重用原引用,内容失败由 20 保留真实任务结果和缺失状态。++`original_created_at_ms` 和 `now_ms` 来自可信生产事件/服务端时钟。+历史导入须给出仍可见的原引用,原截止时间必须相同。没有可证明来源时,+调用方不能把历史冒充新事件。继续旧 run 时应复用旧正文引用及其 scope,+由上层明确授权跨 run 读取;本接口不接受用新 run 身份重新标记原引用。++## 读取和继续++`resolve` 总是读取持久化的当前可见性,不采信引用中缓存的 state/generation。+`read` 每次最多 16 块(1 MiB),返回 `next_chunk`,在文件读取后复核 generation。+读者遇到 Stale 时先重新 resolve;Deleted/Expired/Unavailable 不能回退到本地缓存。+Complete 表示发布完成,不保证磁盘永久无损;正文实际消费还须成功 read。+Storage 错误不可当成空正文或用于证明“历史可继续”。++## 删除、过期和原生缓存++Application 以独立管理授权生成 preview 并取得精确确认后调用 apply。+preview 的 cutoff/count/generation 过时则 Stale;确认之前零删除。+apply 的事务先撤可见性并登记持久化清理记录,然后由 `gc` 每批最多 200 个块回收。+cutoff 以内的迟到事件不会恢复正文;确证 cutoff 之后的新事件可写入。++20 用 `pending_native_cleanup(scope, after_generation, limit)` 恢复未确认的原生缓存清理,+仅处理同 scope、cutoff 内的 HiRoute 受管历史,实际成功后调用 `native_gc_ack`。+通知可以丢失,主动查询和继续仍须检查当前引用。apply 重试返回当前两个 GC 状态;+任一 pending 就不能宣称清理全部完成。`expire_scope` 供 retention worker 调度,+采用每个事件七天截止时间,并使用同一原生清理协议。++生产 maintenance 已调度过期 scope 发现和分批对象 GC;原生缓存清理仍由20确认。+本模块尚需接入完整的会话清理和 Application 授权;本接口测试不代表+MVP-15 或 MVP-20 生产入口验收完成。activity 扩展迁移为本分支意图,最终 schema+编号与公共导出由总协调收敛。diff --git a/decision-extensions/README.md b/decision-extensions/README.mdindex 45ca0277..78596bbd 100644--- a/decision-extensions/README.md+++ b/decision-extensions/README.md@@ -1,6 +1,6 @@# HiRoute decision extensions-[简体中文](README.zh-CN.md) · [Decision API](api/README.md) · [Official Jev extension](extensions/jev-decider/README.md)+[Simplified Chinese](README.zh-CN.md) · [Decision API](api/README.md) · [Official Jev extension](extensions/jev-decider/README.md)HiRoute can ask a trusted decision service which branch should handle a routing execution round. The same response can assess how well the model handled the preceding execution stage. The protocol describes branch decisions and competence assessments; it is not inherently a simple/complex binary classifier. The current smart-saving integration supplies two branches, while the API's `branches` map and the Jev extension's `auto` mode support multiple allowed branches. This does not add new routing modes to the current product.diff --git a/decision-extensions/api/README.md b/decision-extensions/api/README.mdindex 716f6e0a..e972aab9 100644--- a/decision-extensions/api/README.md+++ b/decision-extensions/api/README.md@@ -1,6 +1,6 @@# Decision API-[简体中文](README.zh-CN.md) · [Mechanism and usage](../README.md)+[Simplified Chinese](README.zh-CN.md) · [Mechanism and usage](../README.md)[Download the canonical OpenAPI 3.1 JSON](decision.openapi.json). This single schema is also embedded by Desktop's protocol dialog and Save OpenAPI action. The request represents an arbitrary map of allowed branches, not a hard-coded binary choice. Do not maintain a second schema in an extension.diff --git a/decision-extensions/api/README.zh-CN.md b/decision-extensions/api/README.zh-CN.mdindex 9129cbab..9b8e6921 100644--- a/decision-extensions/api/README.zh-CN.md+++ b/decision-extensions/api/README.zh-CN.md@@ -60,4 +60,4 @@ HiRoute 不设置额外固定输入字节限额,也不截断当前用户文本计划 `timeout_ms` 覆盖历史准备、凭据、连接和响应读取,同时受源请求取消与 deadline 限制。默认 3000 ms,官方服务默认总预算 2.8 秒;服务预算应略小于计划值。HiRoute 只调用一次,不自动重试。外部服务失败回退本地规则;源取消/deadline、本地 Replay 完整性或资源错误直接终止,不伪装成服务失败继续执行。-当前智能省钱配置与具体工具状态映射见[实现使用说明](../../docs/smart-saving-model-classification.md)。+当前智能省钱配置与具体工具状态映射见[实现使用说明](../../docs/smart-saving-model-classification.zh-CN.md)。diff --git a/decision-extensions/extensions/jev-decider/README.md b/decision-extensions/extensions/jev-decider/README.mdindex 73996674..326e097d 100644--- a/decision-extensions/extensions/jev-decider/README.md+++ b/decision-extensions/extensions/jev-decider/README.md@@ -1,6 +1,6 @@# HiRoute Jev decider-[简体中文](README.zh-CN.md) · [Decision mechanism](../../README.md) · [API and OpenAPI](../../api/README.md)+[Simplified Chinese](README.zh-CN.md) · [Decision mechanism](../../README.md) · [API and OpenAPI](../../api/README.md)This is HiRoute's deployable reference implementation of the five-field REST branch-decision protocol. It accepts a HiRoute decision request, makes exactly one OpenRouter Decisions call with `typesafe/jev-1.13`, and returns `branch_id` plus an optional assessment of the preceding execution segment.diff --git a/docs/macos-installation.md b/docs/macos-installation.mdindex b1320c2a..767ab73e 100644--- a/docs/macos-installation.md+++ b/docs/macos-installation.md@@ -1,24 +1,32 @@-# macOS 安装候选+# macOS installation candidate-安装目标为 macOS 15+,分别提供 Apple Silicon(arm64)和 Intel(x86_64)单架构包。-最低版本取自随包官方 CPA release 的实际构建信息;旧系统、Intel 真机及 Windows 的验证结果须单列,不能由 arm64 测试推断。-仓库提供候选构建入口;构建成功不等于 Finder、账号、Worker 或正式分发验收通过。+[Simplified Chinese](macos-installation.zh-CN.md)-## 安装与 CLI+The target is macOS 15+, with separate single-architecture packages for Apple Silicon+(`arm64`) and Intel (`x86_64`). The minimum version comes from the actual build facts of the+bundled official CPA release. Older macOS, real Intel hardware, and Windows require separate+evidence and cannot be inferred from an arm64 run. The repository provides candidate-build+entry points; a successful build is not Finder, account, Worker, or public-distribution+acceptance.-打开候选 DMG,将 `HiRoute.app` 拖到镜像中的 `Applications` 入口,拷贝完成后推出镜像,-从 `/Applications/HiRoute.app` 打开。ZIP 仍可用于直接解压安装。-首次安装自签名包可能被系统拦截;它没有 Developer ID 公证。普通工程候选不自动具备公开分发资格;-只有完成完整性、安装、组件声明和发布审核并进入官网发布清单的精确产物才作为公开下载。-请使用可信来源的包并按 macOS 的应用打开确认流程处理,不关闭系统安全检查。+## Installation and CLI-App 只能从 `/Applications/HiRoute.app` 或当前用户的 `~/Applications/HiRoute.app` 运行后安装-用户级终端入口。在“设置 → CLI”中显式选择安装,HiRoute 会创建-`~/.local/bin/hiroute` 到包内 CLI 的符号链接;不会复制二进制、请求 sudo 或修改 shell 文件。-如果该路径已有非 HiRoute 条目会报告冲突并保持原样。App 位于 DMG、下载临时目录或其他位置时-不会安装入口。+Open the candidate DMG, drag `HiRoute.app` to its `Applications` shortcut, eject the image,+and open `/Applications/HiRoute.app`. A ZIP remains available for direct extraction.+A self-signed package may be blocked on first launch because it has no Developer ID+notarization. An engineering candidate is not automatically suitable for public distribution;+only the exact artifact that passes integrity, installation, component-disclosure, and release+review and appears in the website manifest is a public download. Use a trusted package and+follow the macOS application-open confirmation flow without disabling system security.-确保 `~/.local/bin` 已在 PATH 中;zsh 可由用户自行加入 `~/.zprofile`:+The app can install its per-user terminal entry only while running from+`/Applications/HiRoute.app` or `~/Applications/HiRoute.app`. In Settings → CLI, explicitly+choose Install. HiRoute creates `~/.local/bin/hiroute` as a symlink to the bundled CLI; it+does not copy the binary, request `sudo`, or modify shell files. If that path already contains+a non-HiRoute entry, installation reports a conflict and leaves it unchanged. The entry is+not installed while the app runs from a DMG, download directory, or another location.++Ensure that `~/.local/bin` is on `PATH`; zsh users can add this to `~/.zprofile`:```shexport PATH="$HOME/.local/bin:$PATH"@@ -26,82 +34,115 @@ hiroute worker list --output jsonhiroute --help```-设置页会分别显示链接 missing/valid/broken/conflict、PATH 是否包含入口目录、是否被更早的同名-命令遮蔽,以及 daemon 是否可用;链接有效不代表服务已启动。repair/remove 只处理指向受支持-HiRoute.app 的自有链接,不删除 `~/.local` 或 `~/.local/bin`。受管 Agent 启动时也只有在该链接-重新校验为当前可信 App CLI 后才把 `~/.local/bin` 前置到子进程 PATH。--Agent 的受管技能和启动器继续使用 `hiroute` 命令名及既有接入预览/确认流程。-应用运行不需要 Rust、Go、Docker、npm 或源码。Worker 自己的 CLI、ACP adapter 及-必要 runtime 仍按设置中的依赖引导安装,它们不包含在 HiRoute 安装包内。--CLI 默认连接当前用户的 `~/Library/Application Support/ai.hiroute.desktop/run`。-`HIROUTE_RUNTIME_DIR` 优先于 `XDG_RUNTIME_DIR`,两者都是明确的开发/测试覆盖;-空值或相对路径返回不可用,不会回落到另一实例。未运行时先打开 HiRoute;-服务不可用时恢复 Desktop 后按原操作/任务身份查询,不重复提交未知结果的请求。--CPA 随包提供,只在获准订阅路径使用。缺失、替换或不能执行时订阅检查失败,-控制和其他可用 API 来源保持可用。用完整候选替换损坏 App;不要手动安装另一 CPA。--## 手动升级与卸载--1. 在 HiRoute 中明确退出,确认本次服务和任务完成停止;关闭窗口只隐藏应用。- 生命周期完整收尾的组合验收跟踪 #93,不能仅凭窗口消失判断已停止。-2. 替换 `/Applications/HiRoute.app`,保留应用数据,再启动。固定位置让用户级符号链接目标不变。-3. 若移动了 App 或接入检查报告路径失效,使用设置中的接入预览和确认重新配置;- 若出现用户配置漂移,先解决冲突,不能直接覆盖。登录项在设置中检查,必要时关闭再启用。--卸载前先通过设置预览/恢复受管模型及 Agent 接入,再关闭“登录后后台启动”,明确退出,-然后删除 App。删除 App 默认保留数据。若选择彻底清理,确认无任务运行、已恢复接入且-不再需要会话/日志/回执后,只删除当前用户 `~/Library/Application Support/ai.hiroute.desktop`-中的 HiRoute 数据。不要删除 `.codex`、`.claude`、用户项目或原有凭据。-若 App 已损坏,先恢复相同安装位置的完整候选以执行接入恢复;不要手工猜测配置覆盖。--## 构建与检查--在 macOS 的准确、干净 committed checkout 执行(默认宿主架构):+Settings reports the symlink as missing/valid/broken/conflict, whether `PATH` includes its+directory, whether an earlier command shadows it, and whether the daemon is available. A+valid symlink does not prove the service is running. Repair/remove operates only on a HiRoute-+owned link targeting a supported `HiRoute.app`; it never deletes `~/.local` or+`~/.local/bin`. A managed Agent prepends `~/.local/bin` to its subprocess `PATH` only after+revalidating the link against the current trusted app CLI.++Managed Agent skills and launchers continue to use the `hiroute` command and existing+integration Preview/confirmation flow. Running the app requires no Rust, Go, Docker, npm, or+source checkout. A Worker's own CLI, ACP adapter, and required runtime follow the dependency+guidance in Settings and are not bundled with HiRoute.++The CLI connects by default to+`~/Library/Application Support/ai.hiroute.desktop/run`. `HIROUTE_RUNTIME_DIR` takes+precedence over `XDG_RUNTIME_DIR`; both are explicit development/test overrides. An empty or+relative path is unavailable and never falls back to another instance. Open HiRoute when it+is not running. After a service outage, restore Desktop and query with the original operation+or task identity rather than resubmitting a request with an unknown outcome.++CPA is bundled and used only for authorized subscription paths. If it is missing, replaced,+or not executable, subscription checks fail while control and other available API sources+remain usable. Replace a damaged app with a complete candidate; do not install another CPA+manually.++## Manual upgrade and removal++1. Explicitly quit HiRoute and confirm that this service instance and its tasks have stopped.+ Closing the window only hides the application. Full lifecycle acceptance is tracked+ separately; a vanished window alone is not stop evidence.+2. Replace `/Applications/HiRoute.app` while preserving application data, then launch it. A+ fixed location keeps the per-user symlink target stable.+3. If the app moved or integration checks report an invalid path, use the integration Preview+ and confirmation in Settings. Resolve user-configuration drift instead of overwriting it.+ Check and, if needed, disable/re-enable the login item.++Before removal, Preview and restore managed model/Agent integration from Settings, disable+background launch at login, explicitly quit, and delete the app. App deletion preserves data+by default. For a complete data removal, first confirm that no task is running, integration+has been restored, and sessions/logs/receipts are no longer needed; then delete only the+current user's HiRoute data under+`~/Library/Application Support/ai.hiroute.desktop`. Never delete `.codex`, `.claude`, user+projects, or existing credentials. If the app is damaged, restore a complete candidate to the+same installation location before restoring integration; do not guess at configuration+overrides by hand.++## Build and checks++Run from the exact clean committed checkout on macOS (the host architecture by default):```shRUSTC_WRAPPER=sccache python3 scripts/package-desktop.py build \--arch arm64 --cpa-source-repo /path/to/CLIProxyAPI-# 使用构建结果中的实际路径:+# Use the actual paths reported by the build:python3 scripts/package-desktop.py verify /absolute/output/HiRoute.apppython3 scripts/package-desktop.py verify-dmg /absolute/output/HiRoute-VERSION-SHA-macos-arm64-trial.dmg```-构建复用本机现有 Rust 验证共享锁,输出保留在该 checkout 的 `target/`,使用 sccache-时也不能外置 Cargo target。它执行锁定依赖的 release 编译和前端构建;一般开发验证仍使用 Debug。-从显式指定的 CPA checkout 提取 `vendor/cpa/source.json` 固定的提交,核对并应用同目录的启动管道补丁,-使用 Go 构建,再对 CPA 签名并将最终摘要清单编入 Desktop;不进行 deep 重签。-补丁只让父进程通过继承管道传入已有实例管理凭据,保留 loopback 与远程管理禁用规则;不改变模型协议。-构建机须已安装 Go,并能取得锁定的 Go 依赖;不接受任意预编译 CPA,不在用户启动时下载。-上游 LICENSE 自动放入 `Licenses/CLIProxyAPI-LICENSE`,源码、补丁、编译器和产物摘要记录在构建证据中。-打包器还会从锁定的 Cargo/npm 依赖和同一 CPA commit 自动生成-`THIRD-PARTY-LICENSES.txt` 与机器可核对的许可证清单,并连同 HiRoute 的 Apache-2.0-许可证一起放入 `Contents/Resources/Licenses`;缺少可确认的许可证材料会直接中止构建。--Intel 包使用 `--arch x86_64`,需要已安装的 `x86_64-apple-darwin` Rust target;-Apple Silicon 使用 `--arch arm64` 和 `aarch64-apple-darwin` target。-交叉构建时必须能执行目标架构 CPA 的版本探针(Apple Silicon 上需要已有 Rosetta),不会自动安装 Rosetta。-两个架构独立输出到 `target/desktop-package/CANDIDATE_SHA/ARCH/ROUND/`,不会混用组件或合成 universal 包。-重复执行同一命令即可再构建;UTC 时间与随机后缀区分每轮,不覆盖先前产物,也不清理 target。-DMG/ZIP 文件名包含版本、12 位提交号、架构及 `trial`(正式包为 `developer-id`)。-每轮 `result.json` 保留完整提交号、DMG/ZIP SHA256、组件摘要和镜像验证结果;`build.log` 保留命令输出。-DMG 使用系统 `hdiutil` 生成压缩只读镜像,自动验证完整性、只读挂载入口及 App 组件,然后卸载挂载。-如果卸载失败,构建失败且保留日志中的挂载路径;关闭访问该路径的窗口后用 `hdiutil detach PATH` 重试,勿强制卸载其他镜像。--人工 review:先核对 `shasum -a 256 FILE.dmg` 与本轮 `result.json`,按上述步骤安装。-替换前按“手动升级”退出旧 App,避免覆盖运行中的实例;首次隔离验证可使用独立 macOS 测试账号,-不要把开发覆盖环境下的成功当作普通 Finder 启动已通过。-反馈记录完整提交号(见 App 内 `Contents/Resources/installation.json`)、DMG SHA256、架构、macOS 版本、-复现步骤与实际结果;系统拦截时记录提示并在“系统设置 → 隐私与安全性”核对可信 App 后按系统允许的流程打开。-不移除隔离属性、不关闭 Gatekeeper/SIP;ad-hoc 包可能仍需人工授权,构建成功不保证可启动。--原生宿主、daemon、CLI、CPA 位于 `Contents/MacOS`;当前模型目录编入 daemon,前端编入宿主。-`Contents/Resources/installation.json` 记录候选 SHA、版本、最终摘要和系统动态依赖。-`dependency-inventory.json` 是归属核对清单(含可能未链接的 Cargo 依赖),不替代许可证原文。--需要 Developer ID 分发的候选使用已有公证钥匙串 profile;组件许可证仍由同一锁定依赖收集器生成:+The build reuses the existing shared Rust-validation lock and keeps output in this checkout's+`target/`. Even with sccache, never move the Cargo target. Packaging performs a locked release+build and frontend build; ordinary development validation remains Debug.++From the explicitly supplied CPA checkout, the tool resolves the commit pinned by+`vendor/cpa/source.json`, verifies and applies the adjacent launch-pipe patch, builds with Go,+signs CPA, and compiles the final digest manifest into Desktop. It never performs deep+resigning. The patch only lets the parent pass existing instance-management credentials over+an inherited pipe; loopback and remote-management-disabled rules remain intact and the model+protocol is unchanged. The build host needs Go and access to locked Go dependencies. An+arbitrary prebuilt CPA is rejected and nothing is downloaded at user startup.++The upstream license is installed as `Licenses/CLIProxyAPI-LICENSE`; source, patch, compiler,+and artifact digests appear in build evidence. The packager also generates+`THIRD-PARTY-LICENSES.txt` and a machine-verifiable manifest from locked Cargo/npm dependencies+and the same CPA commit, placing them with HiRoute's Apache-2.0 license under+`Contents/Resources/Licenses`. Missing verifiable license material aborts the build.++Intel uses `--arch x86_64` and requires the `x86_64-apple-darwin` Rust target. Apple Silicon+uses `--arch arm64` and `aarch64-apple-darwin`. A cross-build must be able to execute the target+CPA version probe (Apple Silicon therefore needs an existing Rosetta installation for Intel);+the tool never installs Rosetta. Architectures have independent output under+`target/desktop-package/CANDIDATE_SHA/ARCH/ROUND/`; components are not mixed and no universal+binary is synthesized.++Rerun the same command for another round. UTC time and a random suffix keep rounds separate+without overwriting artifacts or cleaning `target/`. DMG/ZIP names contain version, twelve+commit characters, architecture, and either `trial` or `developer-id`. Each `result.json`+contains the full commit, DMG/ZIP SHA-256, component digests, and image checks; `build.log`+retains command output. The DMG is a compressed read-only image built with `hdiutil`, then+checked for integrity, a read-only mount entry, and app components before being detached. If+detach fails, packaging fails and logs the mount path. Close windows using that path and run+`hdiutil detach PATH`; never forcibly detach another image.++For manual review, first compare `shasum -a 256 FILE.dmg` with the round's `result.json`, then+install as described above. Quit the old app before replacement. Use a separate macOS test+account for an initial isolated check when possible, and do not present success under a+development override as ordinary Finder-launch acceptance. Record the complete commit (also+in `Contents/Resources/installation.json`), DMG SHA-256, architecture, macOS version,+reproduction steps, and actual result. If macOS blocks launch, record the message and approve+the trusted app through System Settings → Privacy & Security. Do not remove quarantine+attributes or disable Gatekeeper/SIP. An ad-hoc build may still require manual approval, and a+successful build does not guarantee launch.++The native host, daemon, CLI, and CPA are in `Contents/MacOS`; the current model catalog is+compiled into the daemon and frontend assets into the host.+`Contents/Resources/installation.json` records candidate commit, version, final digests, and+system dynamic dependencies. `dependency-inventory.json` is an attribution-review inventory,+including Cargo dependencies that may not be linked, and does not replace license texts.++A Developer ID candidate uses an existing notarization keychain profile while collecting+component licenses through the same locked process:```shpython3 scripts/package-desktop.py build \@@ -110,11 +151,16 @@ python3 scripts/package-desktop.py build \--notary-profile YOUR_PROFILE```-凭据只来自本机钥匙串,不放进仓库或命令输出。工具签名嵌套二进制和 App,提交公证,-staple 并验证后重建 zip,再封装、签名和公证 DMG;两次公证均须 Accepted。自签名构建在包内明确标记-`controlled-trial`,不声称 Developer ID 签名或公证;该技术标记本身也不代表已经完成组件声明、安装和发布审核。-短期公开自签名版本仍须显式提供并核对适用组件材料,通过上述审核后才可进入官网发布清单。--安装场景需另行记录:安装位置/Finder 无覆盖启动、CLI 同服务和未运行错误、实际委派/结果、-获准订阅调用、CPA 缺失/替换/失败时健康 API/控制、登录启动、退出、手动升级及恢复卸载。-必须注明候选 SHA、安装包摘要和实际执行结果;组件/fixture 测试不能替代这些证据。+Credentials come only from the local keychain and never enter the repository or command+output. The tool signs nested binaries and the app, submits and staples notarization, rebuilds+the ZIP, then packages, signs, and notarizes the DMG; both notarizations must be Accepted.+Self-signed builds are marked `controlled-trial` and make no Developer ID or notarization+claim. That technical marker alone does not establish component disclosure, installation, or+release review. Near-term public self-signed releases still require explicit applicable+component material and all release-manifest gates.++Record installation evidence separately for installation location/Finder launch without+overwrite; CLI access to the same service and not-running errors; real delegation/results;+authorized subscription calls; health/control behavior when CPA is missing, replaced, or+fails; login launch; quit; manual upgrade; and recoverable removal. Include the exact commit,+package digest, and actual result. Component and fixture tests cannot replace this evidence.diff --git a/docs/macos-installation.zh-CN.md b/docs/macos-installation.zh-CN.mdnew file mode 100644index 00000000..ca0fcc89--- /dev/null+++ b/docs/macos-installation.zh-CN.md@@ -0,0 +1,122 @@+# macOS 安装候选++[English](macos-installation.md)++安装目标为 macOS 15+,分别提供 Apple Silicon(arm64)和 Intel(x86_64)单架构包。+最低版本取自随包官方 CPA release 的实际构建信息;旧系统、Intel 真机及 Windows 的验证结果须单列,不能由 arm64 测试推断。+仓库提供候选构建入口;构建成功不等于 Finder、账号、Worker 或正式分发验收通过。++## 安装与 CLI++打开候选 DMG,将 `HiRoute.app` 拖到镜像中的 `Applications` 入口,拷贝完成后推出镜像,+从 `/Applications/HiRoute.app` 打开。ZIP 仍可用于直接解压安装。+首次安装自签名包可能被系统拦截;它没有 Developer ID 公证。普通工程候选不自动具备公开分发资格;+只有完成完整性、安装、组件声明和发布审核并进入官网发布清单的精确产物才作为公开下载。+请使用可信来源的包并按 macOS 的应用打开确认流程处理,不关闭系统安全检查。++App 只能从 `/Applications/HiRoute.app` 或当前用户的 `~/Applications/HiRoute.app` 运行后安装+用户级终端入口。在“设置 → CLI”中显式选择安装,HiRoute 会创建+`~/.local/bin/hiroute` 到包内 CLI 的符号链接;不会复制二进制、请求 sudo 或修改 shell 文件。+如果该路径已有非 HiRoute 条目会报告冲突并保持原样。App 位于 DMG、下载临时目录或其他位置时+不会安装入口。++确保 `~/.local/bin` 已在 PATH 中;zsh 可由用户自行加入 `~/.zprofile`:++```sh+export PATH="$HOME/.local/bin:$PATH"+hiroute worker list --output json+hiroute --help+```++设置页会分别显示链接 missing/valid/broken/conflict、PATH 是否包含入口目录、是否被更早的同名+命令遮蔽,以及 daemon 是否可用;链接有效不代表服务已启动。repair/remove 只处理指向受支持+HiRoute.app 的自有链接,不删除 `~/.local` 或 `~/.local/bin`。受管 Agent 启动时也只有在该链接+重新校验为当前可信 App CLI 后才把 `~/.local/bin` 前置到子进程 PATH。++Agent 的受管技能和启动器继续使用 `hiroute` 命令名及既有接入预览/确认流程。+应用运行不需要 Rust、Go、Docker、npm 或源码。Worker 自己的 CLI、ACP adapter 及+必要 runtime 仍按设置中的依赖引导安装,它们不包含在 HiRoute 安装包内。++CLI 默认连接当前用户的 `~/Library/Application Support/ai.hiroute.desktop/run`。+`HIROUTE_RUNTIME_DIR` 优先于 `XDG_RUNTIME_DIR`,两者都是明确的开发/测试覆盖;+空值或相对路径返回不可用,不会回落到另一实例。未运行时先打开 HiRoute;+服务不可用时恢复 Desktop 后按原操作/任务身份查询,不重复提交未知结果的请求。++CPA 随包提供,只在获准订阅路径使用。缺失、替换或不能执行时订阅检查失败,+控制和其他可用 API 来源保持可用。用完整候选替换损坏 App;不要手动安装另一 CPA。++## 手动升级与卸载++1. 在 HiRoute 中明确退出,确认本次服务和任务完成停止;关闭窗口只隐藏应用。+ 生命周期完整收尾的组合验收跟踪 #93,不能仅凭窗口消失判断已停止。+2. 替换 `/Applications/HiRoute.app`,保留应用数据,再启动。固定位置让用户级符号链接目标不变。+3. 若移动了 App 或接入检查报告路径失效,使用设置中的接入预览和确认重新配置;+ 若出现用户配置漂移,先解决冲突,不能直接覆盖。登录项在设置中检查,必要时关闭再启用。++卸载前先通过设置预览/恢复受管模型及 Agent 接入,再关闭“登录后后台启动”,明确退出,+然后删除 App。删除 App 默认保留数据。若选择彻底清理,确认无任务运行、已恢复接入且+不再需要会话/日志/回执后,只删除当前用户 `~/Library/Application Support/ai.hiroute.desktop`+中的 HiRoute 数据。不要删除 `.codex`、`.claude`、用户项目或原有凭据。+若 App 已损坏,先恢复相同安装位置的完整候选以执行接入恢复;不要手工猜测配置覆盖。++## 构建与检查++在 macOS 的准确、干净 committed checkout 执行(默认宿主架构):++```sh+RUSTC_WRAPPER=sccache python3 scripts/package-desktop.py build \+ --arch arm64 --cpa-source-repo /path/to/CLIProxyAPI+# 使用构建结果中的实际路径:+python3 scripts/package-desktop.py verify /absolute/output/HiRoute.app+python3 scripts/package-desktop.py verify-dmg /absolute/output/HiRoute-VERSION-SHA-macos-arm64-trial.dmg+```++构建复用本机现有 Rust 验证共享锁,输出保留在该 checkout 的 `target/`,使用 sccache+时也不能外置 Cargo target。它执行锁定依赖的 release 编译和前端构建;一般开发验证仍使用 Debug。+从显式指定的 CPA checkout 提取 `vendor/cpa/source.json` 固定的提交,核对并应用同目录的启动管道补丁,+使用 Go 构建,再对 CPA 签名并将最终摘要清单编入 Desktop;不进行 deep 重签。+补丁只让父进程通过继承管道传入已有实例管理凭据,保留 loopback 与远程管理禁用规则;不改变模型协议。+构建机须已安装 Go,并能取得锁定的 Go 依赖;不接受任意预编译 CPA,不在用户启动时下载。+上游 LICENSE 自动放入 `Licenses/CLIProxyAPI-LICENSE`,源码、补丁、编译器和产物摘要记录在构建证据中。+打包器还会从锁定的 Cargo/npm 依赖和同一 CPA commit 自动生成+`THIRD-PARTY-LICENSES.txt` 与机器可核对的许可证清单,并连同 HiRoute 的 Apache-2.0+许可证一起放入 `Contents/Resources/Licenses`;缺少可确认的许可证材料会直接中止构建。++Intel 包使用 `--arch x86_64`,需要已安装的 `x86_64-apple-darwin` Rust target;+Apple Silicon 使用 `--arch arm64` 和 `aarch64-apple-darwin` target。+交叉构建时必须能执行目标架构 CPA 的版本探针(Apple Silicon 上需要已有 Rosetta),不会自动安装 Rosetta。+两个架构独立输出到 `target/desktop-package/CANDIDATE_SHA/ARCH/ROUND/`,不会混用组件或合成 universal 包。+重复执行同一命令即可再构建;UTC 时间与随机后缀区分每轮,不覆盖先前产物,也不清理 target。+DMG/ZIP 文件名包含版本、12 位提交号、架构及 `trial`(正式包为 `developer-id`)。+每轮 `result.json` 保留完整提交号、DMG/ZIP SHA256、组件摘要和镜像验证结果;`build.log` 保留命令输出。+DMG 使用系统 `hdiutil` 生成压缩只读镜像,自动验证完整性、只读挂载入口及 App 组件,然后卸载挂载。+如果卸载失败,构建失败且保留日志中的挂载路径;关闭访问该路径的窗口后用 `hdiutil detach PATH` 重试,勿强制卸载其他镜像。++人工 review:先核对 `shasum -a 256 FILE.dmg` 与本轮 `result.json`,按上述步骤安装。+替换前按“手动升级”退出旧 App,避免覆盖运行中的实例;首次隔离验证可使用独立 macOS 测试账号,+不要把开发覆盖环境下的成功当作普通 Finder 启动已通过。+反馈记录完整提交号(见 App 内 `Contents/Resources/installation.json`)、DMG SHA256、架构、macOS 版本、+复现步骤与实际结果;系统拦截时记录提示并在“系统设置 → 隐私与安全性”核对可信 App 后按系统允许的流程打开。+不移除隔离属性、不关闭 Gatekeeper/SIP;ad-hoc 包可能仍需人工授权,构建成功不保证可启动。++原生宿主、daemon、CLI、CPA 位于 `Contents/MacOS`;当前模型目录编入 daemon,前端编入宿主。+`Contents/Resources/installation.json` 记录候选 SHA、版本、最终摘要和系统动态依赖。+`dependency-inventory.json` 是归属核对清单(含可能未链接的 Cargo 依赖),不替代许可证原文。++需要 Developer ID 分发的候选使用已有公证钥匙串 profile;组件许可证仍由同一锁定依赖收集器生成:++```sh+python3 scripts/package-desktop.py build \+ --cpa-source-repo /path/to/CLIProxyAPI \+ --identity 'Developer ID Application: YOUR ORGANIZATION (TEAMID)' \+ --notary-profile YOUR_PROFILE+```++凭据只来自本机钥匙串,不放进仓库或命令输出。工具签名嵌套二进制和 App,提交公证,+staple 并验证后重建 zip,再封装、签名和公证 DMG;两次公证均须 Accepted。自签名构建在包内明确标记+`controlled-trial`,不声称 Developer ID 签名或公证;该技术标记本身也不代表已经完成组件声明、安装和发布审核。+短期公开自签名版本仍须显式提供并核对适用组件材料,通过上述审核后才可进入官网发布清单。++安装场景需另行记录:安装位置/Finder 无覆盖启动、CLI 同服务和未运行错误、实际委派/结果、+获准订阅调用、CPA 缺失/替换/失败时健康 API/控制、登录启动、退出、手动升级及恢复卸载。+必须注明候选 SHA、安装包摘要和实际执行结果;组件/fixture 测试不能替代这些证据。diff --git a/docs/smart-saving-model-classification.md b/docs/smart-saving-model-classification.mdindex 9469a857..c60adf1d 100644--- a/docs/smart-saving-model-classification.md+++ b/docs/smart-saving-model-classification.md@@ -1,12 +1,25 @@-# 智能省钱自定义分类服务+# Custom decision service for smart saving-智能省钱默认使用 HiRoute 内置的确定性规则。需要自定义策略时,在计划编辑器选择“自定义分类服务”,填写服务地址;认证可留空,也可选择一个 header 名称并创建或引用 Secret。服务可基于 Jev、LLM 或其他自定义策略实现;HiRoute 只消费本文的 HTTP JSON 合同,不直接调用或解析供应商协议。+[Simplified Chinese](smart-saving-model-classification.zh-CN.md)-官方可部署参考实现位于 [`decision-extensions/extensions/jev-decider`](../decision-extensions/extensions/jev-decider/README.md)。它演示用一次 OpenRouter Jev Decisions 请求同时完成本轮 branch 选择和上一执行阶段的可选胜任度评分,也可作为自定义策略的起点。+Smart saving uses HiRoute's deterministic built-in rules by default. To use a custom policy,+select “Custom decision service” in the plan editor and enter its address. Authentication may+be omitted or configured with a header name and a newly created or existing Secret. The+service may use Jev, an LLM, or another custom policy. HiRoute consumes only the HTTP JSON+contract below and never calls or parses a provider-specific protocol directly.-Desktop 的“查看接入协议”弹窗提供可复制的 `curl` 请求和响应示例,并可下载单一当前 [OpenAPI 3.1 文档](../decision-extensions/api/decision.openapi.json)。弹窗中的地址只是示例;运行时始终向 AgentPlan 配置的完整 endpoint 发起请求。+The official deployable reference is+[`decision-extensions/extensions/jev-decider`](../decision-extensions/extensions/jev-decider/README.md).+It demonstrates one OpenRouter Jev Decisions call that both selects the current branch and,+when applicable, scores the previous execution stage. It is also a starting point for custom+policies.-## 配置+Desktop's “View integration protocol” dialog provides copyable `curl` request/response+examples and downloads the single current+[OpenAPI 3.1 document](../decision-extensions/api/decision.openapi.json). Its endpoint is an+example only; runtime always calls the complete endpoint configured in the AgentPlan.++## Configuration```json{@@ -20,16 +33,27 @@ Desktop 的“查看接入协议”弹窗提供可复制的 `curl` 请求和响}```-- `endpoint` 接受操作者授信的完整 HTTP/HTTPS URL,不允许 userinfo 或 fragment,也不跟随 redirect。-- `timeout_ms` 是整个分类链路的毫秒期限,合法范围 `1..=3_600_000`;Desktop 初值为 `3000`。有效 deadline 还会受源请求 deadline 限制。-- `auth_header` 可省略。Secret 保存完整 header 值,例如 `Bearer ...`;HiRoute 不自动补 scheme。-- 计划不保存明文 Secret,不配置分类 instructions、计划用途或可编辑 branch descriptions。-- “测试决策”显式发送固定合成首轮请求,使用与生产相同的 Secret、HTTP、timeout_ms 和响应校验。保存与发布不会自动调用服务;测试可能产生外部费用,也不会产生质量样本。-- 外置服务自己的总超时应略小于 timeout_ms,为 HiRoute 序列化和网络收尾留余量。官方 Jev 决策器通过 `JEV_REQUEST_TIMEOUT_SECONDS` 设置,默认 `2.8` 秒。--## 请求合同--每个新的 Agent turn 最多发一个 `POST`。同一 turn 的工具续轮继承已冻结分支,不再调用决策器。+- `endpoint` is a complete HTTP/HTTPS URL trusted by the operator. Userinfo and fragments are+ rejected, and redirects are not followed.+- `timeout_ms` is the millisecond deadline for the whole decision path. Its valid range is+ `1..=3_600_000`; Desktop starts at `3000`. The source request deadline can shorten the+ effective deadline.+- `auth_header` is optional. Its Secret stores the complete header value, such as `Bearer ...`;+ HiRoute does not add a scheme.+- A plan stores no plaintext Secret and configures no classifier instructions, plan purpose,+ or editable branch descriptions.+- “Test decision” explicitly sends a fixed synthetic first-turn request through the same+ Secret, HTTP, timeout, and response validation as production. Save and publish never call+ the service automatically. A test may incur an external charge and never creates a quality+ sample.+- The external service's own total timeout should be slightly shorter than `timeout_ms` so+ HiRoute can serialize and close the network operation. The official Jev decider uses+ `JEV_REQUEST_TIMEOUT_SECONDS`, defaulting to `2.8` seconds.++## Request contract++Each new Agent turn sends at most one `POST`. Tool continuations within that turn inherit the+frozen branch and do not call the decision service again.```json{@@ -37,14 +61,14 @@ Desktop 的“查看接入协议”弹窗提供可复制的 `curl` 请求和响"smart_saving_simple": "Use the economy model group for a clear, well-scoped task.","smart_saving_complex": "Use the primary model group for an ambiguous, cross-module, diagnostic, concurrent, or deep-reasoning task."},- "latest_user": [{"kind": "text", "text": "修复这条失败测试。"}],+ "latest_user": [{"kind": "text", "text": "Fix this failing test."}],"visible_conversation": [{"branch_id": "smart_saving_simple",- "user": [{"kind": "text", "text": "先修复类型错误。"}],+ "user": [{"kind": "text", "text": "Fix the type error first."}],"status": "completed","steps": [[{"kind": "tool_activity", "tool": "functions.run_tests", "status": "failed"}],- [{"kind": "text", "text": "已修复并重新验证。"}]+ [{"kind": "text", "text": "Fixed and verified again."}]]}],"history_partial": false,@@ -52,29 +76,46 @@ Desktop 的“查看接入协议”弹窗提供可复制的 `curl` 请求和响}```-顶层恰好五个字段:--- `branches`:本次允许的 branch ID 和 HiRoute 内置说明。服务只能返回其中一个 ID。-- `latest_user`:本轮完整用户 content parts。服务可以只看它。-- `visible_conversation`:内存中已结束的 Agent turns。每个 step 是一次业务模型请求,只保留回答文本和工具名称、顺序、粗粒度状态。-- `history_partial`:重启、TTL、LRU 或捕获缺口导致历史不完整时为 true。-- `assessment_from`:需要评价的上一连续执行阶段在数组中的起始下标;null 表示没有可靠评分目标。--工具状态只来自入站协议的显式事实:Messages 使用 `is_error`,Responses function output 使用 `completed/incomplete/in_progress`,provider 原生 web search 使用其明确终态;Chat tool result、Responses custom output 或缺省 Responses function status 均为 `unknown`。HiRoute 不解析工具输出正文猜测失败,因此 Chat Agent 可以在结果内容中告知业务模型错误,但分类历史不会把该自由文本冒充结构化失败。--协议不发送 system/developer、reasoning、工具参数和结果、provider state、凭据、计划用途、plan/model/session 内部 ID 或逐 step 模型。若只有实际兜底分支产生被接受输出,turn 会额外包含 `executed_branch_id`;混合模型贡献不会成为单模型评分目标。--HiRoute 不给分类请求设置额外字节上限,也不截断 `latest_user` 或文本块。超过 8 KiB 的字段从同请求 ReplayStore 流式读取;8 KiB 是存放位置阈值,不是 REST 协议限额。决策服务若有 32K token 等模型限制,应在服务内部按自己的 tokenizer 和策略裁剪完整 turns,并正确返回 partial。--## 响应合同--最小成功响应:+The top level has exactly five fields:++- `branches`: allowed branch IDs and HiRoute's built-in descriptions. The service must return+ one of these IDs.+- `latest_user`: complete content parts for this turn. A service may choose to inspect only+ this field.+- `visible_conversation`: completed Agent turns held in memory. Each step is one business-model+ request and retains only accepted response text plus tool name, order, and coarse status.+- `history_partial`: true when restart, TTL, LRU eviction, or a capture gap made history+ incomplete.+- `assessment_from`: the start index of the previous contiguous execution stage to assess;+ null means that no reliable assessment target exists.++Tool status comes only from explicit ingress-protocol facts. Messages uses `is_error`;+Responses function output uses `completed/incomplete/in_progress`; provider-native web search+uses its explicit terminal state. Chat tool results, Responses custom output, and Responses+function output without a status are `unknown`. HiRoute never parses tool-output prose to+guess failure. A Chat Agent can still tell the business model about an error in result text,+but classification history does not promote that free-form text to a structured failure.++The protocol excludes system/developer text, reasoning, tool arguments and results, provider+state, credentials, plan purpose, plan/model/session internal IDs, and per-step models. If only+the actual fallback branch produced accepted output, a turn also includes+`executed_branch_id`; mixed-model contribution is not a single-model assessment target.++HiRoute imposes no extra byte limit on a decision request and does not truncate `latest_user`+or text blocks. Fields above 8 KiB are streamed from the request's ReplayStore; 8 KiB is a+storage-location threshold, not a REST protocol limit. A decision service with a 32K-token+model limit must use its own tokenizer and policy to trim complete turns and return `partial`+accurately.++## Response contract++Minimal success:```json{"branch_id":"smart_saving_complex"}```-带上一阶段胜任度:+With previous-stage competence:```json{@@ -82,24 +123,37 @@ HiRoute 不给分类请求设置额外字节上限,也不截断 `latest_user`"assessment": {"score": 0.25,"partial": false,- "reason": "可选的可见行为说明"+ "reason": "Optional explanation of visible behavior"}}```-- `branch_id` 必填且必须属于请求的 `branches`。-- `assessment` 可省略;省略表示不更新评分,不是 0 分。-- `score` 是 `[0,1]` 的模型胜任度,不是置信度、成功概率或问题复杂度。-- `partial` 必填,表示服务是否删减了被评分区间。-- `reason` 可省略;Jev 没有文字 reason 时无需拼造。--合法 branch 配非法 assessment 时,HiRoute 仍使用 branch、丢弃评分;branch 非法时整次响应无效,评分也不会保存。成功正文上限 64 KiB,不接受未知字段、重复字段、多个对象、Markdown 或供应商 envelope。--## 阶段评分和查询--HiRoute 按连续的计划版本、选择/实际分支、实际模型配置和有效 profile 识别执行阶段。Key 轮换不切阶段;实际模型、profile、分支或计划版本变化在真实执行后开启新阶段。服务每轮都可返回上一阶段评分,也可以省略;合法新评分覆盖该阶段最新值,不为每轮创建独立分数。--Desktop 的会话“模型表现”和计划编辑“运行表现”读取同一数据。计划页默认列出当前生效版本已经选择的模型,并按所选时间范围展示这些模型的阶段胜任度;用户无需输入内部模型 ID。CLI 仍可按计划或会话查询,并组合版本、精确模型、时间、严格大于和严格小于筛选,例如:+- `branch_id` is required and must be present in request `branches`.+- `assessment` is optional. Omission means “do not update the score,” not zero.+- `score` is model competence in `[0,1]`, not confidence, success probability, or task+ complexity.+- `partial` is required within an assessment and states whether the service reduced the+ assessed interval.+- `reason` is optional. A Jev implementation should not invent text when Jev supplies none.++With a valid branch and invalid assessment, HiRoute uses the branch and drops the score. An+invalid branch invalidates the complete response and stores no score. A successful body is at+most 64 KiB. Unknown fields, duplicate fields, multiple objects, Markdown, and provider+envelopes are rejected.++## Stage scoring and queries++HiRoute identifies an execution stage by contiguous plan revision, selected/actual branch,+actual model configuration, and effective profile. Credential rotation does not split a+stage. A real change of model, profile, branch, or plan revision starts a new stage after+execution. A service may return a score every turn or omit it. A valid new score replaces the+latest score for that stage rather than creating a per-turn series.++Desktop's session “Model performance” and plan-editor “Runtime performance” read the same+data. The plan page lists models selected by the current effective revision and shows their+stage competence over the selected time range, without asking for an internal model ID. CLI+queries can still filter by plan or session and combine revision, exact model, time, strict+greater-than, and strict less-than filters, for example:```shhiroute observation plan-quality samples \@@ -108,12 +162,18 @@ hiroute observation plan-quality samples \--score-lt 0.5```-未评分样本不会被当作 0;`score_lt 0.5` 不包含等于 0.5。评分用于人工或获准主 Agent 分析某模型在特定 AgentPlan 下是否胜任,以及是否值得拆出更专门的场景;HiRoute 不会自动修改或新建计划。--## 失败边界--- 历史准备、Secret 解析、DNS/连接和 HTTP 读写共享 timeout_ms,并同时受源请求 deadline 和取消控制。-- 服务每轮最多调用一次,不重试,不裁剪后重试。-- 外部超时、不可用、拒绝输入或非法输出使用一次本地规则兜底并记录结构化原因。-- 源取消、源 deadline、Replay 完整性或本地资源错误直接终止,不能伪装成 REST 失败后继续。-- Observation 写入失败不阻塞模型回答;只有真正持久化的评分才会出现在查询中。+An unrated sample is not zero, and `score_lt 0.5` excludes exactly 0.5. A human or authorized+main Agent can use scores to judge whether a model is competent under a specific AgentPlan and+whether a narrower scenario would help. HiRoute never modifies or creates a plan automatically.++## Failure boundary++- History preparation, Secret resolution, DNS/connect, and HTTP I/O share `timeout_ms` and+ remain bounded by the source request deadline and cancellation.+- A turn calls the service at most once, with no retry and no trim-and-retry path.+- External timeout, unavailability, input rejection, or invalid output uses the local rules+ once and records a structured reason.+- Source cancellation, source deadline, Replay integrity failure, or local resource failure+ terminates directly; it cannot masquerade as a REST failure followed by fallback.+- Observation-write failure does not block the model answer. Only a persisted score appears in+ queries.diff --git a/docs/smart-saving-model-classification.zh-CN.md b/docs/smart-saving-model-classification.zh-CN.mdnew file mode 100644index 00000000..ab08c899--- /dev/null+++ b/docs/smart-saving-model-classification.zh-CN.md@@ -0,0 +1,121 @@+# 智能省钱自定义分类服务++[English](smart-saving-model-classification.md)++智能省钱默认使用 HiRoute 内置的确定性规则。需要自定义策略时,在计划编辑器选择“自定义分类服务”,填写服务地址;认证可留空,也可选择一个 header 名称并创建或引用 Secret。服务可基于 Jev、LLM 或其他自定义策略实现;HiRoute 只消费本文的 HTTP JSON 合同,不直接调用或解析供应商协议。++官方可部署参考实现位于 [`decision-extensions/extensions/jev-decider`](../decision-extensions/extensions/jev-decider/README.zh-CN.md)。它演示用一次 OpenRouter Jev Decisions 请求同时完成本轮 branch 选择和上一执行阶段的可选胜任度评分,也可作为自定义策略的起点。++Desktop 的“查看接入协议”弹窗提供可复制的 `curl` 请求和响应示例,并可下载单一当前 [OpenAPI 3.1 文档](../decision-extensions/api/decision.openapi.json)。弹窗中的地址只是示例;运行时始终向 AgentPlan 配置的完整 endpoint 发起请求。++## 配置++```json+{+ "kind": "rest",+ "endpoint": "http://127.0.0.1:8080/v1/decisions",+ "timeout_ms": 3000,+ "auth_header": {+ "name": "Authorization",+ "value_secret_ref": "secret/jev-decider"+ }+}+```++- `endpoint` 接受操作者授信的完整 HTTP/HTTPS URL,不允许 userinfo 或 fragment,也不跟随 redirect。+- `timeout_ms` 是整个分类链路的毫秒期限,合法范围 `1..=3_600_000`;Desktop 初值为 `3000`。有效 deadline 还会受源请求 deadline 限制。+- `auth_header` 可省略。Secret 保存完整 header 值,例如 `Bearer ...`;HiRoute 不自动补 scheme。+- 计划不保存明文 Secret,不配置分类 instructions、计划用途或可编辑 branch descriptions。+- “测试决策”显式发送固定合成首轮请求,使用与生产相同的 Secret、HTTP、timeout_ms 和响应校验。保存与发布不会自动调用服务;测试可能产生外部费用,也不会产生质量样本。+- 外置服务自己的总超时应略小于 timeout_ms,为 HiRoute 序列化和网络收尾留余量。官方 Jev 决策器通过 `JEV_REQUEST_TIMEOUT_SECONDS` 设置,默认 `2.8` 秒。++## 请求合同++每个新的 Agent turn 最多发一个 `POST`。同一 turn 的工具续轮继承已冻结分支,不再调用决策器。++```json+{+ "branches": {+ "smart_saving_simple": "Use the economy model group for a clear, well-scoped task.",+ "smart_saving_complex": "Use the primary model group for an ambiguous, cross-module, diagnostic, concurrent, or deep-reasoning task."+ },+ "latest_user": [{"kind": "text", "text": "修复这条失败测试。"}],+ "visible_conversation": [{+ "branch_id": "smart_saving_simple",+ "user": [{"kind": "text", "text": "先修复类型错误。"}],+ "status": "completed",+ "steps": [+ [{"kind": "tool_activity", "tool": "functions.run_tests", "status": "failed"}],+ [{"kind": "text", "text": "已修复并重新验证。"}]+ ]+ }],+ "history_partial": false,+ "assessment_from": 0+}+```++顶层恰好五个字段:++- `branches`:本次允许的 branch ID 和 HiRoute 内置说明。服务只能返回其中一个 ID。+- `latest_user`:本轮完整用户 content parts。服务可以只看它。+- `visible_conversation`:内存中已结束的 Agent turns。每个 step 是一次业务模型请求,只保留回答文本和工具名称、顺序、粗粒度状态。+- `history_partial`:重启、TTL、LRU 或捕获缺口导致历史不完整时为 true。+- `assessment_from`:需要评价的上一连续执行阶段在数组中的起始下标;null 表示没有可靠评分目标。++工具状态只来自入站协议的显式事实:Messages 使用 `is_error`,Responses function output 使用 `completed/incomplete/in_progress`,provider 原生 web search 使用其明确终态;Chat tool result、Responses custom output 或缺省 Responses function status 均为 `unknown`。HiRoute 不解析工具输出正文猜测失败,因此 Chat Agent 可以在结果内容中告知业务模型错误,但分类历史不会把该自由文本冒充结构化失败。++协议不发送 system/developer、reasoning、工具参数和结果、provider state、凭据、计划用途、plan/model/session 内部 ID 或逐 step 模型。若只有实际兜底分支产生被接受输出,turn 会额外包含 `executed_branch_id`;混合模型贡献不会成为单模型评分目标。++HiRoute 不给分类请求设置额外字节上限,也不截断 `latest_user` 或文本块。超过 8 KiB 的字段从同请求 ReplayStore 流式读取;8 KiB 是存放位置阈值,不是 REST 协议限额。决策服务若有 32K token 等模型限制,应在服务内部按自己的 tokenizer 和策略裁剪完整 turns,并正确返回 partial。++## 响应合同++最小成功响应:++```json+{"branch_id":"smart_saving_complex"}+```++带上一阶段胜任度:++```json+{+ "branch_id": "smart_saving_complex",+ "assessment": {+ "score": 0.25,+ "partial": false,+ "reason": "可选的可见行为说明"+ }+}+```++- `branch_id` 必填且必须属于请求的 `branches`。+- `assessment` 可省略;省略表示不更新评分,不是 0 分。+- `score` 是 `[0,1]` 的模型胜任度,不是置信度、成功概率或问题复杂度。+- `partial` 必填,表示服务是否删减了被评分区间。+- `reason` 可省略;Jev 没有文字 reason 时无需拼造。++合法 branch 配非法 assessment 时,HiRoute 仍使用 branch、丢弃评分;branch 非法时整次响应无效,评分也不会保存。成功正文上限 64 KiB,不接受未知字段、重复字段、多个对象、Markdown 或供应商 envelope。++## 阶段评分和查询++HiRoute 按连续的计划版本、选择/实际分支、实际模型配置和有效 profile 识别执行阶段。Key 轮换不切阶段;实际模型、profile、分支或计划版本变化在真实执行后开启新阶段。服务每轮都可返回上一阶段评分,也可以省略;合法新评分覆盖该阶段最新值,不为每轮创建独立分数。++Desktop 的会话“模型表现”和计划编辑“运行表现”读取同一数据。计划页默认列出当前生效版本已经选择的模型,并按所选时间范围展示这些模型的阶段胜任度;用户无需输入内部模型 ID。CLI 仍可按计划或会话查询,并组合版本、精确模型、时间、严格大于和严格小于筛选,例如:++```sh+hiroute observation plan-quality samples \+ --plan-id plan/codex-daily \+ --model model/config-a \+ --score-lt 0.5+```++未评分样本不会被当作 0;`score_lt 0.5` 不包含等于 0.5。评分用于人工或获准主 Agent 分析某模型在特定 AgentPlan 下是否胜任,以及是否值得拆出更专门的场景;HiRoute 不会自动修改或新建计划。++## 失败边界++- 历史准备、Secret 解析、DNS/连接和 HTTP 读写共享 timeout_ms,并同时受源请求 deadline 和取消控制。+- 服务每轮最多调用一次,不重试,不裁剪后重试。+- 外部超时、不可用、拒绝输入或非法输出使用一次本地规则兜底并记录结构化原因。+- 源取消、源 deadline、Replay 完整性或本地资源错误直接终止,不能伪装成 REST 失败后继续。+- Observation 写入失败不阻塞模型回答;只有真正持久化的评分才会出现在查询中。diff --git a/docs/standalone-cli.md b/docs/standalone-cli.mdindex 099619c7..ba346362 100644--- a/docs/standalone-cli.md+++ b/docs/standalone-cli.md@@ -1,16 +1,22 @@# HiRoute Linux headless CLI-Standalone 是不安装 Desktop 时的单用户运行方式。正式 `hiroute` CLI、`hirouted`-role-all daemon、Local Control、Gateway、业务存储和观测共同组成控制与运行闭环。它沿用同 UID-本机信任边界,不需要额外的“CLI 管理 token”,也不提供第二套 Agent 管理 API。+[Simplified Chinese](standalone-cli.zh-CN.md)-MVP 不允许 standalone 与 HiRoute Desktop 同时运行,不提供系统级多用户安装、Windows 安装、-运行时下载或自动更新。macOS 可使用相同候选包机制,但本页验证与 Quickstart 以 Linux 为准。+Standalone is the single-user mode that does not install Desktop. The production `hiroute`+CLI, role-all `hirouted` daemon, Local Control, Gateway, business storage, and observation+form one control and execution loop. It uses the same-UID local trust boundary, needs no+second “CLI management token,” and exposes no second Agent-management API.-## 安装候选+The MVP does not allow standalone and HiRoute Desktop to run at the same time. It does not+provide a system-wide multi-user install, a Windows installer, runtime downloads, or automatic+updates. macOS can use the same candidate-package mechanism, but this page and the Quickstart+are validated for Linux.-本仓库不声明官方下载地址。发行或集成方从精确 committed candidate 准备 `hiroute`、-`hirouted` 和固定版本 CPA,再生成可复现归档及伴随 manifest:+## Candidate installation++This repository does not declare an official download URL. A distributor or integrator+prepares `hiroute`, `hirouted`, and the pinned CPA from one exact committed candidate, then+builds a reproducible archive and companion manifest:```shpython3 scripts/collect-third-party-licenses.py \@@ -34,32 +40,36 @@ python3 scripts/install-standalone.py install \--archive /absolute/output/PACKAGE.tar.gz```-集成后安装器也接受 `--manifest-url https://.../PACKAGE.tar.gz.json`。重定向和归档必须保持-HTTPS;安装器会在任何写入前校验平台、归档 SHA-256、闭合集合和逐文件摘要。不要根据本页-拼造未发布的下载地址。+After distribution integration, the installer also accepts+`--manifest-url https://.../PACKAGE.tar.gz.json`. Redirects and archives must remain HTTPS.+Before any write, the installer checks the platform, archive SHA-256, closed file set, and+per-file digests. Never infer an unpublished download URL from this page.-收集器只从锁定的 Rust 依赖和 `vendor/cpa/source.json` 指定的 CPA commit 生成材料;-`--cpa-source-repo` 只是该固定 commit 的本地对象来源,不会采用 checkout 当前分支。-打包器要求收集器的闭合输出,并将 HiRoute、CPA 及其传递依赖的许可证和确定性清单随归档-安装到 `licenses/`;材料缺失时打包失败。+The collector uses only locked Rust dependencies and the CPA commit pinned by+`vendor/cpa/source.json`. `--cpa-source-repo` supplies local objects for that exact commit and+does not use the checkout's current branch. The packager requires the collector's closed+output and installs licenses and deterministic manifests for HiRoute, CPA, and transitive+dependencies under `licenses/`. Missing material fails packaging.-安装只写当前用户目录:+Installation writes only current-user paths:-- 稳定入口:`$HOME/.local/bin/hiroute`、`hirouted`;无需 sudo。-- 版本二进制:`$HOME/.local/lib/hiroute/<version>`。-- 只读资源和 marker:`$HOME/.local/share/hiroute`。-- 管理 Skill:`$HOME/.agents/skills/hiroute-management` 和- `$HOME/.claude/skills/hiroute-management`。-- Linux 状态:`${XDG_STATE_HOME:-$HOME/.local/state}/hiroute`。+- stable entry points: `$HOME/.local/bin/hiroute` and `hirouted`, with no `sudo`;+- versioned binaries: `$HOME/.local/lib/hiroute/<version>`;+- read-only resources and marker: `$HOME/.local/share/hiroute`;+- management Skill: `$HOME/.agents/skills/hiroute-management` and+ `$HOME/.claude/skills/hiroute-management`;+- Linux state: `${XDG_STATE_HOME:-$HOME/.local/state}/hiroute`.-安装器会用私有、当前用户拥有的目录安装 Skill;已有符号链接、非目录、非当前用户所有或-group/world 可写的 Skill 父目录会导致安装在写入前失败。同一安装命令用于首次安装、修复和升级。-更新后显式运行 `hiroute service restart --output json` 才会切换正在运行的 daemon。+The installer places the Skill in private, current-user-owned directories. A symlink,+non-directory, foreign-owned, or group/world-writable Skill parent aborts before any write.+The same install command handles first install, repair, and upgrade. After an update, run+`hiroute service restart --output json` explicitly to move the live daemon to the new version.-若存在 `/Applications/HiRoute.app`、`~/Applications/HiRoute.app` 或活动 Desktop Local-Control,安装会失败。反向切换时也应先停止并卸载 standalone。+Installation fails if `/Applications/HiRoute.app`, `~/Applications/HiRoute.app`, or an active+Desktop Local Control exists. Stop and uninstall standalone before switching in the other+direction.-## 启动并确认真实就绪+## Start and verify real readiness```shhiroute service start --output json@@ -68,19 +78,20 @@ hiroute system status --output jsonhiroute gateway show --output json```-只有以下事实同时成立才算业务就绪:+Business readiness requires all of these facts:-- `service status` 的 `data.local_control_ready` 为 `true`;-- `system status` 的 `data.daemon` 为 `role_all`、`data.gateway` 为 `ready`;-- `gateway show` 的 `data.ready` 为 `true`,并给出实际 `connect_address`。+- `service status` reports `data.local_control_ready=true`;+- `system status` reports `data.daemon=role_all` and `data.gateway=ready`;+- `gateway show` reports `data.ready=true` and an actual `connect_address`.-进程管理器返回成功不等于服务已就绪。systemd user unit 不可用时,可在受管理的前台终端运行:+A successful process-manager command is not service readiness. If a systemd user unit is+unavailable, run the service in a managed foreground terminal:```shhiroute service run```-其他生命周期入口:+Other lifecycle commands:```shhiroute service doctor --output json@@ -91,16 +102,17 @@ hiroute service autostart enable --output jsonhiroute service autostart disable --output json```-登录自启与当前会话启动是两个动作。`SIGTERM`/`SIGINT` 会触发有序停机。+Login autostart and starting the current session are separate actions. `SIGTERM` and `SIGINT`+request an orderly shutdown.-## 先发现当前公开合同+## Discover the current public contract first-CLI 有两层公开合同:+The CLI has two public-contract layers:-- Host 管理命令以根帮助和 family 帮助为准;`service`、`gateway`、`protected-input` 有意不进入- Application release manifest。-- Application/Local Control 命令以 `schema list/show` 返回的 Released descriptor 和完整 leaf- `--help` 为准。+- Host management commands are defined by root and family help. `service`, `gateway`, and+ `protected-input` intentionally do not appear in the Application release manifest.+- Application/Local Control commands are defined by Released descriptors from+ `schema list/show` plus complete leaf `--help`.```shhiroute --help@@ -112,17 +124,19 @@ hiroute schema show --command-id compute.connection.test --output jsonhiroute compute connection test --help```-不要用 `schema list` 是否返回来判断 Host 管理命令是否可用。Application/Local Control 只使用-`schema list` 返回的命令;CLI 和 standalone daemon 会同时拒绝 Planned 业务命令,处理函数或开发-构建中存在命令路径不代表它已公开。所有机器响应都是一个 `hiroute.machine-envelope/v2`:自动化-读取 `status`、`data`、稳定错误 `error.code`、`warnings[].code` 和-`next_actions[].command_id`,不要解析展示文案。+Do not use presence in `schema list` to decide whether a Host command exists. Use only listed+Application/Local Control commands. CLI and standalone daemon both reject Planned business+commands; a handler or development-build path does not make a command public. Every machine+response is a `hiroute.machine-envelope/v2`. Automation reads `status`, `data`, stable+`error.code`, `warnings[].code`, and `next_actions[].command_id`; it never parses display text.-以下示例中的 JSON 都是不含凭据的普通文件。`jq` 仅用于演示提取字段,不是 HiRoute 依赖。+The JSON examples below are ordinary credential-free files. `jq` is used only to demonstrate+field extraction and is not a HiRoute dependency.-## 接入 Native API 模型来源+## Connect a Native API model source-凭据只能通过受保护 FD 登记。不要把 Key 放进 argv、环境变量、普通 JSON、日志或 Agent 对话:+Credentials can be registered only through a protected file descriptor. Never put a key in+argv, environment variables, ordinary JSON, logs, or an Agent conversation:```shchmod 600 /absolute/private/provider-key@@ -133,9 +147,10 @@ hiroute protected-input register \exec 3<&-```-按 `compute.connection.test` schema 构造一次有界检查。下面是 Responses API、Bearer 认证、无-`/models` 目录时手工声明一个文本模型的完整形状;替换 endpoint、模型和能力事实,但不要添加-secret 字段:+Construct a bounded check from the `compute.connection.test` schema. This complete shape uses+Responses API, Bearer authentication, and one manually declared text model for a provider+without a `/models` catalog. Replace endpoint, model, and capability facts without adding a+secret field:```json{@@ -190,8 +205,9 @@ hiroute compute connection test --request-stdin --output json \hiroute compute list --output json > compute-before-save.json```-从 `native-checked.json.data.candidate.models[]` 选择 `selectable=true` 的 `model_ref`,从-`compute-before-save.json.data.revisions` 复制当前版本,构造保存变更:+Choose a `model_ref` with `selectable=true` from+`native-checked.json.data.candidate.models[]`. Copy current revisions from+`compute-before-save.json.data.revisions` and construct the save change:```json{@@ -209,7 +225,8 @@ hiroute compute list --output json > compute-before-save.json}```-先 preview,再原样携带返回的 `spec`、`accept_digest`、`expected_revisions` 和新的幂等键 apply:+Preview first. Pass the returned `spec`, `accept_digest`, `expected_revisions`, and a fresh+idempotency key unchanged to apply:```shhiroute compute connection preview --request-stdin --output json \@@ -229,7 +246,8 @@ hiroute protected-input release \--candidate candidate/native/my-provider --output json```-不要在 apply 结果不确定时换幂等键。保留原请求,并用公开恢复入口按相同作用域查询:+Do not replace the idempotency key after an uncertain apply response. Keep the original+request and query the same scope through the public recovery entry:```json{@@ -244,16 +262,18 @@ hiroute protected-input release \hiroute operations find --request-stdin --output json < operation-find.json```-同一 key 与同一内容会返回原 Operation;同一 key 与不同内容会稳定拒绝,不会重复写入。+The same key and content returns the original Operation. The same key with different content+is rejected deterministically and never writes twice.-## 发现并保存订阅来源+## Discover and save a subscription source```shhiroute compute connection options --output json > connection-options.json```-`data.subscriptions` 会如实给出发现状态和候选。选择一个 `connector_owned` 候选后,将候选对象放入-`{"candidate": ...}`,再使用同一 preview/apply 规则开始检查:+`data.subscriptions` reports discovery state and candidates exactly. Select one+`connector_owned` candidate, wrap it as `{"candidate": ...}`, and start its check with the+same Preview/Apply rules:```shjq '{candidate:([.data.subscriptions.candidates[] |@@ -274,19 +294,21 @@ jq '{action:"result",operation:.operation}' subscription-operation.json \> subscription-checked.json```-只有 `data.status=verified` 才表示该检查通过。将-`data.checked_candidate` 与 `data.validation` 经上节相同的 compute save preview/apply 保存。-发现、授权检查、保存和真实模型调用是不同事实;不要把发现成功描述成来源已保存或上游已调用。+Only `data.status=verified` means the check passed. Save `data.checked_candidate` and+`data.validation` through the same compute-save Preview/Apply flow above. Discovery,+authorization check, saving, and a real model call are different facts; never describe a+discovered source as already saved or called.-## 创建、调整并发布路由+## Create, update, and publish routing-先查询真实候选,不手写内部 binding:+Query real candidates instead of hand-writing an internal binding:```shprintf '{}\n' | hiroute routing options --request-stdin --output json > routing-options.json```-从 `data.candidates[].binding_id` 选择来源后构造完整编辑器。固定单模型是合法的最小计划:+Select a `binding_id` from `data.candidates[]` and construct a complete editor. A fixed single+model is a valid minimal plan:```json{@@ -332,12 +354,13 @@ hiroute routing list --output jsonhiroute routing show PLAN_ID --output json```-更新时把 `target` 改为-`{"intent":"update","plan_id":"PLAN_ID","expected_head_revision":CURRENT_HEAD}` 并提交完整-editor。过期 revision/digest 会返回 conflict,旧发布继续服务;重新读取、编辑、preview 后再 apply。-普通模型请求只执行路由,不会因为计划启用了 Worker 而隐式启动任务。+For an update, set `target` to+`{"intent":"update","plan_id":"PLAN_ID","expected_head_revision":CURRENT_HEAD}` and+submit the complete editor. A stale revision/digest returns conflict while the old publication+continues serving. Read again, edit, Preview, and Apply. A normal model request performs only+routing and never starts a Worker implicitly because the plan enables delegation.-## 接入、检查和恢复 Codex+## Connect, check, and restore Codex```shhiroute agents scan --output json > agents.json@@ -345,11 +368,12 @@ hiroute agents check agent_codex_default \--scope native-authentication --output json```-`configuration`、`native-authentication` 和 `collaboration` 是同 UID 本地有界检查,不使用第二个-授权 token,也不产生上游模型调用。`live` 会产生真实模型请求,仍要求命令 help 声明的明确同意-与受保护 probe grant。+`configuration`, `native-authentication`, and `collaboration` are bounded same-UID local+checks. They use no second authorization token and make no upstream model call. `live` does+make a real model request and still requires the command help's explicit consent and a+protected probe grant.-从扫描结果复制 Codex `context_id`,用已发布 `PLAN_ID` 连接:+Copy the Codex `context_id` from scan results and connect it to a published `PLAN_ID`:```json{@@ -383,9 +407,10 @@ jq '{spec:.data.spec,accept_digest:.data.accept_digest,hiroute agents connect status CONTEXT_ID --output json > agent-status.json```-Standalone daemon 已是 resident service,因此 preview 不要求 Desktop login item。HiRoute 只修改其-拥有的 Codex 字段;完成后用户继续运行原来的 `codex` 入口,模型请求会进入本机 Gateway。保存-`agent-status.json.data.restore_point_ref`。恢复时:+The standalone daemon is already a resident service, so Preview does not require a Desktop+login item. HiRoute changes only the Codex fields that it owns. Continue using the original+`codex` entry afterward; its model requests enter the local Gateway. Save+`agent-status.json.data.restore_point_ref`. To restore:```json{@@ -397,14 +422,15 @@ Standalone daemon 已是 resident service,因此 preview 不要求 Desktop log}```-对该 spec 依次调用 `agents restore preview`、复制 preview 返回字段并调用-`agents restore apply`,最后运行 `agents connect status`。恢复只撤销仍由 HiRoute 拥有的字段;-并发用户修改会导致冲突而不是被覆盖。Claude Code 使用其公开 profile/launcher 合同;不要把-Codex 的 Responses 计划直接配置给只支持 Messages 的 surface。+Pass this spec through `agents restore preview`, copy the returned Preview fields to+`agents restore apply`, and finish with `agents connect status`. Restore removes only fields+still owned by HiRoute; concurrent user changes conflict instead of being overwritten. Claude+Code uses its public profile/launcher contract. Do not configure a Responses-only Codex plan+for a surface that supports only Messages.-## 会话、实际选择与用量事实+## Sessions, actual selection, and usage facts-一次 Agent 或 Worker 请求完成后:+After an Agent or Worker request completes:```shhiroute sessions list --include-unlinked --limit 50 --output json@@ -414,22 +440,25 @@ hiroute sessions status --output jsonhiroute value show --routing PLAN_ID --session SESSION_ID --output json```-`sessions show` 默认只返回事实和 timeline,不返回对话正文。RoutingReceipt 的-`route_decision`、`attempt_started`、`usage_and_cache` 等有序事实给出实际计划、模型选择、Attempt-和上游报告的已知 token。`value show` 只返回已有账价值;没有可信价格证据时金额保持 `null`,-且不得把未知金额或尚未形成账值行的 token 伪造为零成本。正文、搜索、catalog 与 ancestry 仍需-各自精确的受保护 capability。+`sessions show` returns facts and timeline by default, not conversation bodies. Ordered+RoutingReceipt facts such as `route_decision`, `attempt_started`, and `usage_and_cache` record+the actual plan, model choice, Attempt, and known upstream-reported tokens. `value show`+returns only existing ledger value. Without trustworthy price evidence, an amount stays+`null`; unknown amounts or tokens without value-ledger rows are never fabricated as zero+cost. Bodies, search, catalog, and ancestry each require their own precise protected+capability.-## 配置 Worker 并委派任务+## Configure a Worker and delegate a task-Worker 复用现有命令。发现不会安装或选择软件:+Worker reuses the existing commands. Discovery does not install or select software:```shhiroute worker dependencies discover --harness codex_cli --output json \> worker-discovery.json```-从同一 Harness 的 `selection_revisions[].revision` 复制并选择完整的 `found` 绝对路径:+Copy `selection_revisions[].revision` for the same Harness and select complete absolute paths+whose state is `found`:```json{@@ -448,8 +477,9 @@ hiroute worker executors --output jsonhiroute worker plans --output json```-将路由 editor 的 `delegation_enabled` 设为 `true`,并加入-`"work":{"harness":"codex_cli","protocol":"responses"}` 后重新发布。再提交、定位、等待和读取:+Set routing-editor `delegation_enabled` to `true`, add+`"work":{"harness":"codex_cli","protocol":"responses"}`, and publish again. Then submit,+locate, wait for, and read the task:```shhiroute worker exec --plan PLAN_ID --cwd /absolute/project \@@ -463,11 +493,13 @@ hiroute worker result --run RUN_ID --output jsonhiroute worker list --output json```-等待超时只表示仍在运行,不会取消任务。响应不确定时用原 submission key 查询,或原样重放同一-`worker exec`;不要换 key。重复提交返回同一个 run,不会执行两次。`selection_revision` 是 Worker-选择配置的并发版本,不是 Codex、Claude 或 HiRoute 软件版本。+A wait timeout means only that work is still running and does not cancel it. After an+uncertain response, query with the original submission key or replay that exact JSON unchanged+through the same `worker exec`; never replace the key. Duplicate submission returns the same+run and does not execute twice. `selection_revision` is the concurrency revision for Worker+installation selection, not a Codex, Claude, or HiRoute CLI/package version.-## Gateway 监听器+## Gateway listener```shhiroute gateway show --output json@@ -477,47 +509,57 @@ hiroute gateway set --address 192.0.2.10 --port 8317 \hiroute gateway recover --output json```-`set` 保存 desired 后重启,并只在真实 ready 后推进 applied。自动端口首次选定后持久化;-`0.0.0.0` 对本机管理客户端显示为 `127.0.0.1:<port>`。非 loopback 配置要求显式风险确认。-HiRoute 不自动修改防火墙、TLS 或远端 Agent。IPv6、多监听器和防火墙管理不在 MVP。--## 常见错误与恢复--- `DAEMON_UNAVAILABLE`:Standalone 先运行 `hiroute service status`,需要时运行- `hiroute service start`,再用 `service doctor`、`service logs` 诊断;Desktop 启动或恢复应用。- 隔离实例确认使用同一个 `HOME`、`XDG_STATE_HOME` 和 `XDG_RUNTIME_DIR`。CLI 不会自动启动服务- 或重放请求。-- `UNKNOWN_COMMAND`:Host 管理路径先读根帮助和 family `--help`;Application 命令不在当前- release manifest 时,不要尝试内部 operation 名或 staged 路径,先升级或改用 `schema list`- 中的入口。-- `INVALID_ARGUMENTS`:读取 leaf `--help` 和 `schema show`;严格 schema 会拒绝未知字段。-- `REVISION_CONFLICT` / `CHANGE_PREVIEW_STALE`:重新读取当前资源和 options,重新 preview;不要- 修改旧 preview 后强行 apply。-- `IDEMPOTENCY_KEY_REUSED`:同一 key 已用于另一摘要;用 `operations find` 查看胜出 Operation,- 不要把新内容说成已应用。-- apply 响应丢失:保留原 spec/digest/revisions/key,先 `operations find`;同一内容的显式重试- 继续用原 key。-- Agent restore 冲突:用户或 Agent 已修改受管字段;停止自动覆盖,读取 status 并重新确认。-- 模型请求成功但金额未知:查看 RoutingReceipt 的实际 model/usage;没有价格证据时 `null` 是- 正确结果,不等于免费。--## 管理 Skill--安装包把同一份 `hiroute-management` Skill 安装到通用 Agent 和 Claude Code Skill 目录。它只-组织本页公开命令:检查服务、配置来源与路由、接入/恢复 Agent、查询观测和操作 Worker。它不-实现业务校验、不直接编辑数据库或 Agent 配置、不接触明文凭据,也不会自行安装、发布、变更-监听器、取消任务或启用自启动。Agent 对 Host 管理命令先读 `hiroute --help` 和对应 family-`--help`,对 Application/Local Control 命令先读 `schema list/show` 和完整 leaf `--help`,并遵循-用户明确授权的外部副作用范围。--## 卸载--先停止服务,再执行:+`set` saves desired state, restarts, and advances applied state only after real readiness.+The first automatically chosen port is persisted. Local management clients see a+`0.0.0.0` listener as `127.0.0.1:<port>`. A non-loopback address requires explicit risk+acceptance. HiRoute never changes a firewall, configures TLS, or manages a remote Agent.+IPv6, multiple listeners, and firewall management are outside the MVP.++## Common errors and recovery++- `DAEMON_UNAVAILABLE`: on Standalone, run `hiroute service status`, then+ `hiroute service start` if needed, and diagnose with `service doctor` and `service logs`.+ On Desktop, launch or restore the application. For an isolated instance, confirm the same+ `HOME`, `XDG_STATE_HOME`, and `XDG_RUNTIME_DIR`. The CLI does not start a service or replay+ a request automatically.+- `UNKNOWN_COMMAND`: for Host management, read root and family `--help`. If an Application+ command is absent from the current release manifest, do not try an internal operation name+ or staged path; upgrade or use an entry listed by `schema list`.+- `INVALID_ARGUMENTS`: read leaf `--help` and `schema show`. Strict schemas reject unknown+ fields.+- `REVISION_CONFLICT` / `CHANGE_PREVIEW_STALE`: read current resources/options and Preview+ again. Never modify and force an old Preview through Apply.+- `IDEMPOTENCY_KEY_REUSED`: the key already names another digest. Use `operations find` to+ inspect the winning Operation; do not claim that new content was applied.+- Lost Apply response: keep the original spec/digest/revisions/key and call+ `operations find` first. An explicit retry of the same content uses the original key.+- Agent restore conflict: the user or Agent changed a managed field. Stop automatic overwrite,+ read status, and confirm again.+- Successful model request with unknown cost: inspect the RoutingReceipt's actual model and+ usage. `null` without price evidence is correct and does not mean free.++## Management Skill++The package installs the same `hiroute-management` Skill in the generic Agent and Claude Code+Skill directories. It organizes only the public commands on this page: service checks,+source/routing configuration, Agent integration/restoration, observation queries, and Worker+operations. It implements no business validation, directly edits no database or Agent+configuration, handles no plaintext credential, and never installs, publishes, changes a+listener, cancels a task, or enables autostart on its own. For Host commands, an Agent first+reads `hiroute --help` and the family `--help`. For Application/Local Control commands, it+first reads `schema list/show` and complete leaf `--help`, then stays within the user's+explicitly authorized external side effects.++## Uninstall++Stop the service first, then run:```shpython3 scripts/install-standalone.py uninstall```-卸载只删除 marker 记录且仍归 HiRoute 所有的稳定入口、当前版本程序、服务定义和两处 Skill;-任何条目被外部替换都会中止而不是覆盖。业务存储、诊断和会话默认保留。删除保留数据必须另行-确认确切目录及其内容已不再需要。+Uninstall removes only marker-recorded stable entries, the current version's programs,+service definition, and the two Skills while they are still HiRoute-owned. Any externally+replaced entry aborts instead of being overwritten. Business storage, diagnostics, and+sessions are retained by default. Deleting retained data requires a separate confirmation of+the exact directory and that its contents are no longer needed.diff --git a/docs/standalone-cli.zh-CN.md b/docs/standalone-cli.zh-CN.mdnew file mode 100644index 00000000..d767f0b9--- /dev/null+++ b/docs/standalone-cli.zh-CN.md@@ -0,0 +1,525 @@+# HiRoute Linux headless CLI++[English](standalone-cli.md)++Standalone 是不安装 Desktop 时的单用户运行方式。正式 `hiroute` CLI、`hirouted`+role-all daemon、Local Control、Gateway、业务存储和观测共同组成控制与运行闭环。它沿用同 UID+本机信任边界,不需要额外的“CLI 管理 token”,也不提供第二套 Agent 管理 API。++MVP 不允许 standalone 与 HiRoute Desktop 同时运行,不提供系统级多用户安装、Windows 安装、+运行时下载或自动更新。macOS 可使用相同候选包机制,但本页验证与 Quickstart 以 Linux 为准。++## 安装候选++本仓库不声明官方下载地址。发行或集成方从精确 committed candidate 准备 `hiroute`、+`hirouted` 和固定版本 CPA,再生成可复现归档及伴随 manifest:++```sh+python3 scripts/collect-third-party-licenses.py \+ --cargo-target x86_64-unknown-linux-gnu \+ --cpa-source-repo /path/to/CLIProxyAPI \+ --output /absolute/output/notices++python3 scripts/package-standalone.py build \+ --version 0.1.0 --revision FULL_COMMIT_SHA \+ --target x86_64-unknown-linux-gnu \+ --hiroute /absolute/path/hiroute \+ --hirouted /absolute/path/hirouted \+ --cpa-binary /absolute/path/cliproxyapi \+ --cpa-version PINNED_VERSION \+ --cpa-license /absolute/path/CLIProxyAPI-LICENSE \+ --notices /absolute/output/notices \+ --output /absolute/output++python3 scripts/install-standalone.py install \+ --manifest /absolute/output/PACKAGE.tar.gz.json \+ --archive /absolute/output/PACKAGE.tar.gz+```++集成后安装器也接受 `--manifest-url https://.../PACKAGE.tar.gz.json`。重定向和归档必须保持+HTTPS;安装器会在任何写入前校验平台、归档 SHA-256、闭合集合和逐文件摘要。不要根据本页+拼造未发布的下载地址。++收集器只从锁定的 Rust 依赖和 `vendor/cpa/source.json` 指定的 CPA commit 生成材料;+`--cpa-source-repo` 只是该固定 commit 的本地对象来源,不会采用 checkout 当前分支。+打包器要求收集器的闭合输出,并将 HiRoute、CPA 及其传递依赖的许可证和确定性清单随归档+安装到 `licenses/`;材料缺失时打包失败。++安装只写当前用户目录:++- 稳定入口:`$HOME/.local/bin/hiroute`、`hirouted`;无需 sudo。+- 版本二进制:`$HOME/.local/lib/hiroute/<version>`。+- 只读资源和 marker:`$HOME/.local/share/hiroute`。+- 管理 Skill:`$HOME/.agents/skills/hiroute-management` 和+ `$HOME/.claude/skills/hiroute-management`。+- Linux 状态:`${XDG_STATE_HOME:-$HOME/.local/state}/hiroute`。++安装器会用私有、当前用户拥有的目录安装 Skill;已有符号链接、非目录、非当前用户所有或+group/world 可写的 Skill 父目录会导致安装在写入前失败。同一安装命令用于首次安装、修复和升级。+更新后显式运行 `hiroute service restart --output json` 才会切换正在运行的 daemon。++若存在 `/Applications/HiRoute.app`、`~/Applications/HiRoute.app` 或活动 Desktop Local+Control,安装会失败。反向切换时也应先停止并卸载 standalone。++## 启动并确认真实就绪++```sh+hiroute service start --output json+hiroute service status --output json+hiroute system status --output json+hiroute gateway show --output json+```++只有以下事实同时成立才算业务就绪:++- `service status` 的 `data.local_control_ready` 为 `true`;+- `system status` 的 `data.daemon` 为 `role_all`、`data.gateway` 为 `ready`;+- `gateway show` 的 `data.ready` 为 `true`,并给出实际 `connect_address`。++进程管理器返回成功不等于服务已就绪。systemd user unit 不可用时,可在受管理的前台终端运行:++```sh+hiroute service run+```++其他生命周期入口:++```sh+hiroute service doctor --output json+hiroute service logs --output json+hiroute service restart --output json+hiroute service stop --output json+hiroute service autostart enable --output json+hiroute service autostart disable --output json+```++登录自启与当前会话启动是两个动作。`SIGTERM`/`SIGINT` 会触发有序停机。++## 先发现当前公开合同++CLI 有两层公开合同:++- Host 管理命令以根帮助和 family 帮助为准;`service`、`gateway`、`protected-input` 有意不进入+ Application release manifest。+- Application/Local Control 命令以 `schema list/show` 返回的 Released descriptor 和完整 leaf+ `--help` 为准。++```sh+hiroute --help+hiroute service --help+hiroute gateway --help+hiroute protected-input --help+hiroute schema list --output json+hiroute schema show --command-id compute.connection.test --output json+hiroute compute connection test --help+```++不要用 `schema list` 是否返回来判断 Host 管理命令是否可用。Application/Local Control 只使用+`schema list` 返回的命令;CLI 和 standalone daemon 会同时拒绝 Planned 业务命令,处理函数或开发+构建中存在命令路径不代表它已公开。所有机器响应都是一个 `hiroute.machine-envelope/v2`:自动化+读取 `status`、`data`、稳定错误 `error.code`、`warnings[].code` 和+`next_actions[].command_id`,不要解析展示文案。++以下示例中的 JSON 都是不含凭据的普通文件。`jq` 仅用于演示提取字段,不是 HiRoute 依赖。++## 接入 Native API 模型来源++凭据只能通过受保护 FD 登记。不要把 Key 放进 argv、环境变量、普通 JSON、日志或 Agent 对话:++```sh+chmod 600 /absolute/private/provider-key+exec 3</absolute/private/provider-key+hiroute protected-input register \+ --candidate candidate/native/my-provider \+ --secret-fd 3 --output json+exec 3<&-+```++按 `compute.connection.test` schema 构造一次有界检查。下面是 Responses API、Bearer 认证、无+`/models` 目录时手工声明一个文本模型的完整形状;替换 endpoint、模型和能力事实,但不要添加+secret 字段:++```json+{+ "kind": "native",+ "request": {+ "draft": {+ "inference_model_id": null,+ "candidate_ref": "candidate/native/my-provider",+ "lineage_ref": "lineage/native/my-provider",+ "display_name": "My Responses API",+ "existing_source_id": null,+ "edit_revision": 1,+ "check_id": "check/native/my-provider-1",+ "base_url": "https://provider.example/v1",+ "base_kind": "api_root",+ "request_path_override": null,+ "inventory_path_override": "/v1/models",+ "protocol": "responses",+ "protocol_profile_id": "profile/custom/responses",+ "protocol_profile_revision": 1,+ "authentication": {"kind": "bearer"},+ "configuration_revision": 1,+ "models": [{+ "upstream_model_id": "provider-model-id",+ "display_name": "Provider model",+ "catalog_configuration_id": null,+ "membership": "user_declared",+ "capabilities": {+ "tool": {"value": true, "basis": "user_declared"},+ "vision": {"value": false, "basis": "user_declared"},+ "streaming": {"value": true, "basis": "user_declared"},+ "context_tokens": {"value": 32768, "basis": "user_declared"},+ "max_output_tokens": {"value": 4096, "basis": "user_declared"},+ "native_reasoning": {+ "value": {"kind": "fixed", "profile": "provider-default"},+ "basis": "user_declared"+ }+ }+ }]+ },+ "input_candidate": {+ "candidate_ref": "candidate/native/my-provider",+ "candidate_revision": 1+ }+ }+}+```++```sh+hiroute compute connection test --request-stdin --output json \+ < native-test.json > native-checked.json+hiroute compute list --output json > compute-before-save.json+```++从 `native-checked.json.data.candidate.models[]` 选择 `selectable=true` 的 `model_ref`,从+`compute-before-save.json.data.revisions` 复制当前版本,构造保存变更:++```json+{+ "change": {+ "schema": "hiroute.compute-management-change/v2",+ "subject": {"kind": "candidate", "candidate": {+ "candidate_ref": "CANDIDATE_REF_FROM_CHECK",+ "candidate_revision": 1+ }},+ "expected_revisions": {"target": 0, "dependencies": {}},+ "selected_model_refs": ["SELECTABLE_MODEL_REF"],+ "intent": "save_ready",+ "key_edits": []+ }+}+```++先 preview,再原样携带返回的 `spec`、`accept_digest`、`expected_revisions` 和新的幂等键 apply:++```sh+hiroute compute connection preview --request-stdin --output json \+ < compute-preview-request.json > compute-preview.json++jq '{spec:.data.spec,accept_digest:.data.accept_digest,+ expected_revisions:.data.expected_revisions,+ idempotency_key:"save-my-provider-1"}' \+ compute-preview.json \+ | hiroute compute connection apply --request-stdin --output json \+ > compute-apply.json++hiroute operations get "$(jq -r '.operation.operation_id' compute-apply.json)" --output json+hiroute compute list --output json+hiroute compute show "SOURCE_ID" --output json+hiroute protected-input release \+ --candidate candidate/native/my-provider --output json+```++不要在 apply 结果不确定时换幂等键。保留原请求,并用公开恢复入口按相同作用域查询:++```json+{+ "principal_kind": "interactive_user",+ "operation_kind": "ApplyComputeSave",+ "idempotency_key": "save-my-provider-1",+ "accepted_digest": "ACCEPT_DIGEST_FROM_PREVIEW"+}+```++```sh+hiroute operations find --request-stdin --output json < operation-find.json+```++同一 key 与同一内容会返回原 Operation;同一 key 与不同内容会稳定拒绝,不会重复写入。++## 发现并保存订阅来源++```sh+hiroute compute connection options --output json > connection-options.json+```++`data.subscriptions` 会如实给出发现状态和候选。选择一个 `connector_owned` 候选后,将候选对象放入+`{"candidate": ...}`,再使用同一 preview/apply 规则开始检查:++```sh+jq '{candidate:([.data.subscriptions.candidates[] |+ select(.provenance=="connector_owned")] | first)}' \+ connection-options.json \+ | hiroute compute connection preview --request-stdin --output json \+ > subscription-preview.json++jq '{spec:.data.spec,accept_digest:.data.accept_digest,+ expected_revisions:.data.expected_revisions,+ idempotency_key:"check-subscription-1"}' \+ subscription-preview.json \+ | hiroute compute connection apply --request-stdin --output json \+ > subscription-operation.json++jq '{action:"result",operation:.operation}' subscription-operation.json \+ | hiroute compute connection authorize --request-stdin --output json \+ > subscription-checked.json+```++只有 `data.status=verified` 才表示该检查通过。将+`data.checked_candidate` 与 `data.validation` 经上节相同的 compute save preview/apply 保存。+发现、授权检查、保存和真实模型调用是不同事实;不要把发现成功描述成来源已保存或上游已调用。++## 创建、调整并发布路由++先查询真实候选,不手写内部 binding:++```sh+printf '{}\n' | hiroute routing options --request-stdin --output json > routing-options.json+```++从 `data.candidates[].binding_id` 选择来源后构造完整编辑器。固定单模型是合法的最小计划:++```json+{+ "change": {+ "schema": "hiroute.plan-content-change/v2",+ "target": {"intent": "create", "creation_key": "my-first-route"},+ "editor": {+ "schema": "hiroute.plan-editor/v2",+ "display_name": "Daily coding",+ "purpose": "Coding requests from my local Agents",+ "mode": "fixed_model",+ "candidates": [{"binding_id": "BINDING_FROM_ROUTING_OPTIONS"}],+ "smart": {+ "economy": [], "primary": [], "primary_fallback": false,+ "classifier": {"kind": "local_rules"}, "complex_keywords": []+ },+ "free": {"candidates": [], "primary": [], "primary_fallback": false},+ "delegation_enabled": false,+ "requirements": {},+ "limits": {+ "maximum_attempts": 1,+ "request_timeout_ms": 30000,+ "attempt_timeout_ms": 30000+ }+ },+ "consumed_draft": null+ }+}+```++```sh+hiroute routing preview --request-stdin --output json \+ < route-change.json > route-preview.json++jq --slurpfile change route-change.json \+ '{change:$change[0].change,accept_digest:.data.change_digest,+ expected_revisions:.data.expected_revisions,+ idempotency_key:"publish-my-first-route-1"}' \+ route-preview.json \+ | hiroute routing apply --request-stdin --output json > route-apply.json++hiroute routing list --output json+hiroute routing show PLAN_ID --output json+```++更新时把 `target` 改为+`{"intent":"update","plan_id":"PLAN_ID","expected_head_revision":CURRENT_HEAD}` 并提交完整+editor。过期 revision/digest 会返回 conflict,旧发布继续服务;重新读取、编辑、preview 后再 apply。+普通模型请求只执行路由,不会因为计划启用了 Worker 而隐式启动任务。++## 接入、检查和恢复 Codex++```sh+hiroute agents scan --output json > agents.json+hiroute agents check agent_codex_default \+ --scope native-authentication --output json+```++`configuration`、`native-authentication` 和 `collaboration` 是同 UID 本地有界检查,不使用第二个+授权 token,也不产生上游模型调用。`live` 会产生真实模型请求,仍要求命令 help 声明的明确同意+与受保护 probe grant。++从扫描结果复制 Codex `context_id`,用已发布 `PLAN_ID` 连接:++```json+{+ "spec": {+ "schema_version": {"major": 2, "minor": 0},+ "context_id": "CONTEXT_ID_FROM_SCAN",+ "model": {+ "intent": "configure",+ "settings": {+ "mode": "codex_default",+ "fixed_models": [],+ "allowed_plan_ids": ["PLAN_ID"],+ "default_selection": {"kind": "plan", "plan_id": "PLAN_ID"}+ }+ }+ }+}+```++```sh+hiroute agents connect preview --request-stdin --output json \+ < agent-connect.json > agent-preview.json++jq '{spec:.data.spec,accept_digest:.data.accept_digest,+ dependency_digest:.data.dependency_digest,+ expected_revisions:.data.expected_revisions,+ idempotency_key:"connect-codex-1"}' \+ agent-preview.json \+ | hiroute agents connect apply --request-stdin --output json > agent-apply.json++hiroute agents connect status CONTEXT_ID --output json > agent-status.json+```++Standalone daemon 已是 resident service,因此 preview 不要求 Desktop login item。HiRoute 只修改其+拥有的 Codex 字段;完成后用户继续运行原来的 `codex` 入口,模型请求会进入本机 Gateway。保存+`agent-status.json.data.restore_point_ref`。恢复时:++```json+{+ "spec": {+ "schema_version": {"major": 2, "minor": 0},+ "context_id": "CONTEXT_ID",+ "model": {"intent": "restore", "restore_point_ref": "RESTORE_POINT_REF"}+ }+}+```++对该 spec 依次调用 `agents restore preview`、复制 preview 返回字段并调用+`agents restore apply`,最后运行 `agents connect status`。恢复只撤销仍由 HiRoute 拥有的字段;+并发用户修改会导致冲突而不是被覆盖。Claude Code 使用其公开 profile/launcher 合同;不要把+Codex 的 Responses 计划直接配置给只支持 Messages 的 surface。++## 会话、实际选择与用量事实++一次 Agent 或 Worker 请求完成后:++```sh+hiroute sessions list --include-unlinked --limit 50 --output json+hiroute sessions show SESSION_ID --output json+hiroute sessions receipt RECEIPT_ID --output json+hiroute sessions status --output json+hiroute value show --routing PLAN_ID --session SESSION_ID --output json+```++`sessions show` 默认只返回事实和 timeline,不返回对话正文。RoutingReceipt 的+`route_decision`、`attempt_started`、`usage_and_cache` 等有序事实给出实际计划、模型选择、Attempt+和上游报告的已知 token。`value show` 只返回已有账价值;没有可信价格证据时金额保持 `null`,+且不得把未知金额或尚未形成账值行的 token 伪造为零成本。正文、搜索、catalog 与 ancestry 仍需+各自精确的受保护 capability。++## 配置 Worker 并委派任务++Worker 复用现有命令。发现不会安装或选择软件:++```sh+hiroute worker dependencies discover --harness codex_cli --output json \+ > worker-discovery.json+```++从同一 Harness 的 `selection_revisions[].revision` 复制并选择完整的 `found` 绝对路径:++```json+{+ "harness": "codex_cli",+ "adapter_path": "/absolute/path/to/codex-acp",+ "cli_path": "/absolute/path/to/codex",+ "node_path": "/absolute/path/to/node",+ "expected_selection_revision": 0+}+```++```sh+hiroute worker dependencies select --request-stdin --output json \+ < worker-selection.json+hiroute worker executors --output json+hiroute worker plans --output json+```++将路由 editor 的 `delegation_enabled` 设为 `true`,并加入+`"work":{"harness":"codex_cli","protocol":"responses"}` 后重新发布。再提交、定位、等待和读取:++```sh+hiroute worker exec --plan PLAN_ID --cwd /absolute/project \+ --no-wait --submission-key task-20260921-1 --file task.txt --output json++hiroute worker status \+ --submission task-20260921-1 --operation start --output json+hiroute worker status --run RUN_ID --output json+hiroute worker wait --run RUN_ID --wait-timeout 30 --output json+hiroute worker result --run RUN_ID --output json+hiroute worker list --output json+```++等待超时只表示仍在运行,不会取消任务。响应不确定时用原 submission key 查询,或原样重放同一+`worker exec`;不要换 key。重复提交返回同一个 run,不会执行两次。`selection_revision` 是 Worker+选择配置的并发版本,不是 Codex、Claude 或 HiRoute 软件版本。++## Gateway 监听器++```sh+hiroute gateway show --output json+hiroute gateway set --address 127.0.0.1 --port auto --output json+hiroute gateway set --address 192.0.2.10 --port 8317 \+ --accept-remote-risk --output json+hiroute gateway recover --output json+```++`set` 保存 desired 后重启,并只在真实 ready 后推进 applied。自动端口首次选定后持久化;+`0.0.0.0` 对本机管理客户端显示为 `127.0.0.1:<port>`。非 loopback 配置要求显式风险确认。+HiRoute 不自动修改防火墙、TLS 或远端 Agent。IPv6、多监听器和防火墙管理不在 MVP。++## 常见错误与恢复++- `DAEMON_UNAVAILABLE`:Standalone 先运行 `hiroute service status`,需要时运行+ `hiroute service start`,再用 `service doctor`、`service logs` 诊断;Desktop 启动或恢复应用。+ 隔离实例确认使用同一个 `HOME`、`XDG_STATE_HOME` 和 `XDG_RUNTIME_DIR`。CLI 不会自动启动服务+ 或重放请求。+- `UNKNOWN_COMMAND`:Host 管理路径先读根帮助和 family `--help`;Application 命令不在当前+ release manifest 时,不要尝试内部 operation 名或 staged 路径,先升级或改用 `schema list`+ 中的入口。+- `INVALID_ARGUMENTS`:读取 leaf `--help` 和 `schema show`;严格 schema 会拒绝未知字段。+- `REVISION_CONFLICT` / `CHANGE_PREVIEW_STALE`:重新读取当前资源和 options,重新 preview;不要+ 修改旧 preview 后强行 apply。+- `IDEMPOTENCY_KEY_REUSED`:同一 key 已用于另一摘要;用 `operations find` 查看胜出 Operation,+ 不要把新内容说成已应用。+- apply 响应丢失:保留原 spec/digest/revisions/key,先 `operations find`;同一内容的显式重试+ 继续用原 key。+- Agent restore 冲突:用户或 Agent 已修改受管字段;停止自动覆盖,读取 status 并重新确认。+- 模型请求成功但金额未知:查看 RoutingReceipt 的实际 model/usage;没有价格证据时 `null` 是+ 正确结果,不等于免费。++## 管理 Skill++安装包把同一份 `hiroute-management` Skill 安装到通用 Agent 和 Claude Code Skill 目录。它只+组织本页公开命令:检查服务、配置来源与路由、接入/恢复 Agent、查询观测和操作 Worker。它不+实现业务校验、不直接编辑数据库或 Agent 配置、不接触明文凭据,也不会自行安装、发布、变更+监听器、取消任务或启用自启动。Agent 对 Host 管理命令先读 `hiroute --help` 和对应 family+`--help`,对 Application/Local Control 命令先读 `schema list/show` 和完整 leaf `--help`,并遵循+用户明确授权的外部副作用范围。++## 卸载++先停止服务,再执行:++```sh+python3 scripts/install-standalone.py uninstall+```++卸载只删除 marker 记录且仍归 HiRoute 所有的稳定入口、当前版本程序、服务定义和两处 Skill;+任何条目被外部替换都会中止而不是覆盖。业务存储、诊断和会话默认保留。删除保留数据必须另行+确认确切目录及其内容已不再需要。diff --git a/e2e/README.md b/e2e/README.mdindex 0382a943..cf6f09f5 100644--- a/e2e/README.md+++ b/e2e/README.md@@ -1,6 +1,10 @@# HiRoute black-box E2E-这个目录保存环境无关的产品路径合同。它位于 unit、component 和 `gateway-core` lifecycle 测试之上,从真实 TCP 边界验证用户最终看到的行为。+[Simplified Chinese](README.zh-CN.md)++This directory holds environment-independent product-path contracts. It sits above unit,+component, and `gateway-core` lifecycle tests and verifies user-visible behavior across a+real TCP boundary.```textE2E HTTP client@@ -11,82 +15,115 @@ E2E HTTP client-> Responses-native mock```-`hiroute-e2e` 不依赖 `hiroute-poc` 或 `gateway-core` Rust crate。将来 POC binary 被正式 daemon / Desktop backend 替换时,只要维持外部 CLI 与 HTTP 产品合同,scenario 不需要重写。+`hiroute-e2e` does not depend on `hiroute-poc` or the `gateway-core` Rust crate. A future+replacement of the POC binary by the production daemon/Desktop backend does not require a+scenario rewrite as long as the external CLI and HTTP product contracts remain stable.-## 当前覆盖+## Current coverage-[`scenarios/core-routing.json`](scenarios/core-routing.json) 包含十七个顺序步骤:+[`scenarios/core-routing.json`](scenarios/core-routing.json) contains seventeen ordered+steps:-| 下游协议 | 任务 | 真实 native mock | 预期来源 |+| Downstream protocol | Task | Real native mock | Expected source || --- | --- | --- | --- || Responses | simple | Anthropic `/v1/messages` | Claude-compatible || Responses | complex | Codex `/responses` | Codex subscription || Messages | simple | Anthropic `/v1/messages` | Claude-compatible || Messages | complex | Codex `/responses` | Codex subscription || Responses / Messages | large Agent envelope + simple user | Anthropic `/v1/messages` | Claude-compatible |-| Responses / Messages | tool continuation | Codex `/responses` | 原 Turn affinity hit |-| Responses | simple + Claude 500 | Claude `/v1/messages` 后 Codex `/responses` | precommit fallback 到 Codex |-| Responses | fallback 后 function output | Codex `/responses`,无 Claude Attempt | 回写后的 Turn affinity hit |-| Responses | complex 后追加 simple 完整历史 | Codex `/responses` | 同 Session 前缀保持 Codex |-| Responses | 保留前两条 user、替换后续摘要 | Anthropic `/v1/messages` | 完整历史重建后重新选择 Claude |-| Messages | simple 后追加 complex 完整历史 | Anthropic `/v1/messages` | 同 Session 前缀保持 Claude |-| Messages | 编辑 system、历史正文不变 | Codex `/responses` | 指令变化后重新选择 Codex |-| Responses | 非空 `previous_response_id` | 无 native Attempt | Planner 前返回明确 400 错误码 |--每一步同时断言:--1. 下游状态、SSE content type 与协议终止事件;-2. `x-hiroute-source`;-3. native mock 实际收到的有序 Attempt、native path、native model、response-head status,以及 CPA 使用了该 source 独有的上游鉴权;-4. 是否确实发生 Messages / Responses 协议转换;-5. 每次 Attempt 对应的 routing receipt,其 protocol、source、class、affinity、disposition 与 status;-6. fallback 后接受来源会回写 Turn affinity,function output 续轮直接命中 Codex,不再探测 Claude;-7. 同一稳定 Session 的完整可见历史 append 跨 simple/complex 分支保持实际成功来源,历史重建或指令编辑则重新选路;-8. 不支持的 Responses 服务端续链在 Planner 和 native 上游前拒绝,ledger 与 receipt 均不增加。--上述当前实现只证明基础路径、来源与有限终止事件,**不能**证明协议语义已经保真。当前-`protocol_conversion=true` 仅表示客户端协议与 native mock 协议名称不同;native ledger 只检查-`messages`/`input` 顶层形状,尚未逐项比较 Vision、Tool schema/choice/call/result/ID、-reasoning 原生字段、usage/finish reason、Provider state 和完整 SSE 事件序列。因此不能把当前 17-step suite-表述成正式协议转换 conformance 已通过。--正式 P0 目标由-[`Agent 接入与模型协议转换合同`](../design/product-contract/protocol-conversion-contract.md)定义,并拆成:--- `E2E-P028`:从 exact Codex/Claude Code 安装版本和有效配置解析 AgentIntegrationProfile,分别选择- Responses/Messages 唯一入口,执行配置 diff/apply/rollback 与真实跨协议 Turn;-- `E2E-D011`:Responses/Messages 入站到 Responses/Chat Completions/Messages 上游的六路径语义保真;-- `E2E-D012`:入站 effort 隔离、AgentPlan exact reasoning configuration 的逐目标协议原生渲染与 fallback 重渲染;-- `E2E-D013`:Tool ID/续轮、Provider state 亲和、统一流式事件、流中错误和 postcommit 零接力。--这四项必须先以有限 schema、canonical Model IR corpus、request/SSE golden 和 native semantic ledger 建成红灯-测试,再实现正式 Adapter。只看 HTTP 200、最终文本、目标 path 或协议名称不同均不构成通过证据。--来源判定以 native mock ledger 为主证据,不信任 response model 或 Gateway 自报 header;后两者只是相互独立的旁证。Native mock 只断言鉴权是否完全匹配,不把任何 credential 写入 ledger 或结果 artifact。--## 环境合同--Scenario 只描述产品行为,禁止 executable path、shell command、端口、延时、任意响应体和凭据。v2 的成功步骤只允许 1–2 次 source-native Attempt,以及有限的 response-head status:`200/429/500/502/503/504/529`;最终 Attempt 必须是 `200 Accept`。入口预校验步骤只允许固定 `400 + error code + 0 Attempt`,用于断言请求没有进入 Planner/native 上游。请求头只允许有界的 `session-id`/`thread-id`,不能注入认证或环境编排。`#[serde(deny_unknown_fields)]`、语义校验与 JSON Schema 共同防止环境编排逐渐渗入用例。--[`profiles/local-process.json`](profiles/local-process.json) 只允许两个固定引用:+| Responses / Messages | tool continuation | Codex `/responses` | original Turn affinity hit |+| Responses | simple + Claude 500 | Claude `/v1/messages`, then Codex `/responses` | precommit fallback to Codex |+| Responses | function output after fallback | Codex `/responses`, no Claude Attempt | written-back Turn affinity hit |+| Responses | simple full-history append after complex | Codex `/responses` | same Session prefix remains on Codex |+| Responses | keep first two user items, replace later history with summary | Anthropic `/v1/messages` | rebuilt history reselects Claude |+| Messages | complex full-history append after simple | Anthropic `/v1/messages` | same Session prefix remains on Claude |+| Messages | edit system while history text is unchanged | Codex `/responses` | changed instructions reselect Codex |+| Responses | non-empty `previous_response_id` | no native Attempt | explicit 400 before Planner |++Every step also asserts:++1. downstream status, SSE content type, and protocol terminal event;+2. `x-hiroute-source`;+3. ordered Attempts actually observed by the native mock, including native path/model,+ response-head status, and use of that source's unique upstream authentication;+4. whether a Messages/Responses protocol conversion actually occurred;+5. each Attempt's routing receipt, including protocol, source, class, affinity, disposition,+ and status;+6. accepted-source writeback after fallback, followed by a Codex affinity hit for function+ output without probing Claude again;+7. source stability for a full visible-history append in one stable Session, and reselection+ after history reconstruction or instruction changes;+8. early rejection of unsupported Responses server-side continuation before Planner or+ native upstream, with no new ledger or receipt entry.++The current implementation proves only these basic paths, sources, and limited terminal+events. It does **not** prove full protocol-semantic fidelity. At present,+`protocol_conversion=true` means only that client and native-mock protocol names differ.+The native ledger checks only the top-level `messages`/`input` shape; it does not yet compare+Vision, tool schema/choice/call/result/ID, native reasoning fields, usage/finish reason,+provider state, or the complete SSE event sequence. Do not describe the current seventeen+steps as passed protocol-conversion conformance.++The formal P0 target is defined by the Agent integration and model protocol-conversion+contract and split into:++- `E2E-P028`: resolve AgentIntegrationProfile from exact Codex/Claude Code installations and+ valid configuration, select the unique Responses/Messages entry, apply and roll back+ configuration diffs, and execute a real cross-protocol Turn;+- `E2E-D011`: semantic fidelity for the six ingress/upstream combinations across Responses,+ Chat Completions, and Messages;+- `E2E-D012`: isolated ingress effort and exact AgentPlan reasoning configuration rendered+ natively for each target and again after fallback;+- `E2E-D013`: tool IDs/continuation, provider-state affinity, normalized streaming events,+ in-stream errors, and zero postcommit handoff.++These items must begin as failing tests with bounded schemas, a canonical Model IR corpus,+request/SSE goldens, and a native semantic ledger, then be implemented in the production+Adapter. HTTP 200, final text, a target path, or merely different protocol names are not+sufficient evidence.++The native mock ledger is the primary source-selection evidence. A response model or a+Gateway self-reported header is only independent supporting evidence. Native mocks assert+exact authentication without writing credentials to the ledger or result artifact.++## Environment contract++A Scenario describes product behavior only. It cannot contain executable paths, shell+commands, ports, delays, arbitrary response bodies, or credentials. A v2 success step allows+one or two source-native Attempts and the bounded response-head statuses+`200/429/500/502/503/504/529`; the final Attempt must be `200 Accept`. Entry-validation steps+allow only a fixed `400 + error code + 0 Attempt`, proving that the request did not reach the+Planner/native upstream. Headers are limited to bounded `session-id`/`thread-id` values and+cannot inject authentication or environment orchestration. `#[serde(deny_unknown_fields)]`,+semantic validation, and JSON Schema prevent orchestration from leaking into cases.++[`profiles/local-process.json`](profiles/local-process.json) permits only two fixed+references:```textHIROUTE_E2E_CPA_BIN -> stock CLIProxyAPI executableHIROUTE_E2E_SUT_BIN -> external HiRoute executable```-Runner 每次使用动态端口与 0700 TempDir,生成随机 capability,启动两个 single-source CPA、两个 native mock 与一个 SUT;所有 secret-bearing 文件和进程日志为 0600。每个子进程都有独立、启动时为空的 0700 work directory,并同时作为 `current_dir`、`HOME`、XDG 与 `TMPDIR`,因此 stock CPA 不会向上搜索并读取仓库 `.env`。子进程从 `env_clear()` 的最小环境启动,不继承开发者 shell 中的真实 Provider token;外部 HTTP proxy 被指向 loopback blackhole,native source 只允许 loopback。进程 readiness 使用连接探测,不依赖固定 sleep;退出有界并由 drop 做二次 kill 保证。+Each run uses dynamic ports and a 0700 TempDir, generates random capabilities, and starts two+single-source CPAs, two native mocks, and one SUT. Secret-bearing files and process logs are+0600. Every subprocess starts from a separate empty 0700 work directory used as `current_dir`,+`HOME`, XDG, and `TMPDIR`, so stock CPA cannot search upward into a repository `.env`.+Subprocesses start after `env_clear()` with a minimal environment and do not inherit real+provider tokens. External HTTP proxies point to a loopback black hole and native sources are+loopback-only. Readiness uses connection probes, not fixed sleeps; shutdown is bounded and a+drop guard performs a second kill if necessary.-结果 artifact 只保留产品证据,不包含:+The result artifact contains product evidence only, never:-- 请求或模型响应正文;-- capability / CPA / native API key;-- 端口、临时路径或 executable path;-- command argv 或原始进程日志。+- request or model-response bodies;+- capabilities or CPA/native API keys;+- ports, temporary paths, or executable paths;+- command argv or raw process logs.-## 使用+## Usage-验证合同(不要求已有二进制):+Validate the contract without prebuilt binaries:```shcargo run -p hiroute-e2e -- validate \@@ -94,7 +131,7 @@ cargo run -p hiroute-e2e -- validate \--profile e2e/profiles/local-process.json```-运行完整黑盒链路:+Run the complete black-box path:```shHIROUTE_E2E_CPA_BIN=/absolute/path/to/CLIProxyAPI \@@ -105,9 +142,14 @@ cargo run -p hiroute-e2e -- run \--result /tmp/hiroute-e2e-result.json```-Runner 每次分配动态端口和私有临时目录,启动两个 native mock、两个隔离 stock CPA 和一个外部 HiRoute SUT。它用真实 TCP 验证四个协议/来源象限、两种 Agent envelope 反例、Responses/Messages 工具续轮的 affinity hit、context hold/重建失效、Responses 服务端续链早拒绝,以及 `Claude 500 -> Codex Accept -> function output 直接命中 Codex` 的完整链路。+The runner allocates dynamic ports and a private temporary directory, then starts two native+mocks, two isolated stock CPAs, and an external HiRoute SUT. Across real TCP it verifies the+four protocol/source quadrants, two Agent-envelope counterexamples, Responses/Messages tool+continuation affinity, ContextHold/rebuild invalidation, early rejection of Responses+server-side continuation, and the full+`Claude 500 -> Codex Accept -> function output hits Codex directly` path.-建议的质量门禁:+Recommended gates:```shcargo fmt --package hiroute-e2e -- --check@@ -116,82 +158,99 @@ cargo clippy -p hiroute-e2e --all-targets -- -D warningscargo test -p hiroute-e2e```-## 用 E2E 驱动后续功能--新增能力时遵循“产品合同先红、实现后绿”:+## Driving later features with E2E-1. 用现有字段可表达时,先添加一个 `ScenarioStep`,运行确认因未实现行为而失败。-2. response-head fallback 直接使用 v2 的有限 `attempts`;新能力需要首包断连、语义 SSE failure、更多 step 类型或新的证据时,再升级 Rust contract 与 `schema_version`,同步更新 `e2e/schema/`。-3. 不在 scenario 中加入 shell、路径、sleep、固定端口或 secret;编排能力属于 runner/profile。-4. 对路由能力优先增加 native ledger 断言;对协议能力同时增加原生事件序列和统一语义断言。-5. 实现产品代码,直到本地与 CI 的同一 scenario 通过。-6. 结果 artifact 通过敏感信息扫描后再作为评审证据保留。+Follow product-contract-first-red, implementation-green:-推荐下一批 scenario:+1. If current fields express the behavior, add a `ScenarioStep` and run it to establish a+ real not-yet-implemented failure.+2. Use the v2 bounded `attempts` for response-head fallback. Upgrade the Rust contract and+ `schema_version` with `e2e/schema/` only when a feature requires first-chunk disconnect,+ semantic SSE failure, another step type, or new evidence.+3. Never put shell, paths, sleep, fixed ports, or secrets in a scenario; orchestration belongs+ to runner/profile.+4. Prefer native-ledger assertions for routing behavior and add native-event sequence plus+ normalized-semantic assertions for protocol behavior.+5. Implement product code until the same local and CI scenario is green.+6. Scan the result artifact for sensitive data before retaining it as review evidence.-- 两个 Turn 交错,affinity 不串线;-- 429/502/503/504/529 response-head 矩阵、首包断连与首个语义 SSE error 的 precommit fallback;-- commit 后禁止重放和总 Attempt 数上限;-- SSE 任意字节切片、长流、客户端取消与内存上界;-- multimodal、`count_tokens`、`compact` 和 usage/cost evidence;-- Codex CLI / Claude Code 的 real-local smoke profile。+Good next scenarios include interleaved Turns without affinity leakage; the response-head and+first-semantic-SSE-error precommit fallback matrix; zero replay after commit and total Attempt+limits; arbitrary SSE byte slicing, long streams, cancellation, and memory bounds;+multimodal, `count_tokens`, `compact`, and usage/cost evidence; and real-local Codex CLI /+Claude Code smoke profiles.-当前 v2 native mock 对成功响应返回固定文本 SSE,并支持有限 response-head failure;`ScenarioStep` 只支持 HTTP Turn。不要用任意 shell 字段绕过这个边界;需要上述能力时,应把 stream failure 或 `AgentTurn` 建成新的有限枚举并升级 schema。+The v2 native mock currently returns fixed text SSE for success and supports bounded+response-head failure. `ScenarioStep` handles only an HTTP Turn. Do not evade this boundary+with arbitrary shell fields; model a stream failure or `AgentTurn` as a new bounded enum and+upgrade the schema when needed.-## CI 分层+## CI layers-当前公共 CI 在 Linux、macOS、Windows 上编译 harness、运行其 mock/unit tests,并通过 CLI-静态校验 checked-in scenario 与 profile;这条门禁不需要外部二进制、真实账号或凭据。+Public CI compiles the harness on Linux, macOS, and Windows, runs mock/unit tests, and+statically validates checked-in scenarios and profiles through the CLI. This gate needs no+external binary, account, or credential.-完整 10-step 进程链路当前仍需要单独提供 stock CPA 与 HiRoute SUT,按上面的 `run` 命令显式执行。-它不会被静态 `validate` 冒充已经在公共 CI 跑通。正式 SUT 可由代码仓库直接构建后,再分层扩展:+The complete process path still requires an explicit stock CPA and HiRoute SUT via the `run`+command above. Static `validate` never represents that path as executed. After building a+production SUT from the repository, expand in layers:-- `e2e-core-routing`:构建 stock CPA + SUT,执行当前 10-step hermetic suite;-- `e2e-product`:按 Proposal 增加 fallback、tool、cancel、memory 等套件;-- `e2e-real-local`:显式人工/nightly 触发,使用真实本地 Agent 和授权,不进入公共 CI,也不替代 hermetic suite。+- `e2e-core-routing`: build stock CPA + SUT and run the current hermetic suite;+- `e2e-product`: add fallback, tool, cancellation, memory, and related suites;+- `e2e-real-local`: manual/nightly only, using real local Agents and explicit authorization;+ it is not public CI and does not replace the hermetic suite.## P0 Gateway exact Oracle-最终 `gateway-isolated` 合同由 `schema/p0-production-manifest.json` 封口。Manifest 锁定一个真实-Responses → Responses production smoke、profile、scenario 和 launcher/readiness/collector/result schema;-artifact SHA-256 对 canonical JSON 计算,任何未重新封口的语义漂移都会在启动前失败。旧-`p0-gateway-manifest.json`、corpus/golden 和 fixture adversary 仍可作为历史负向输入,但不再被最终 profile-加载,也不能证明发布完成。--Runner 只用正常的 `hirouted --role gateway --listen ... --publication ... --credentials ...` 路径;最终合同中-不存在 `--fixture`、`--expect-status`、`expected_red` 或 `skip`。每次运行生成私有 publication/credential-输入、随机 client/provider capability、不可预测 freshness challenge、动态 loopback listener 和 native-Provider mock。Profile 固定 Gateway 产品源码 revision;runner 在 binary 所属 checkout 内检查源码树和构建输入相对该-revision 无 tracked/untracked 漂移,再用当前 target/toolchain 执行带随机 build nonce 的 `cargo rustc --locked---all-features` 可信重建。Launcher evidence 固定这次重建的 revision/source tree/build-input digest、target、toolchain、-build command、artifact path 和实际 executable SHA-256,因此不同 checkout/平台的合法构建无需共享本地 debug hash,-而 wrapper、非 Cargo artifact 和伪造构建输入不能被当作 SUT。-`/_hiroute/ready` 除精确回报 publication revision/digest 与 executable digest 外,runner 还会在 probe 前后-通过 OS socket-owner proof 要求动态 listener 都由同一存活 child PID 持有。调用方还可用-`HIROUTE_E2E_SUT_REVISION` 增加外部 revision 断言。--Provider 证据保存完整原生 JSON payload 和精确连接计数。Collector 分别读取 Lifecycle、ExecutionFact、-ConversationContent 和 content-free OTel JSONL,要求四套独立 producer/epoch/stream identity、从 1 开始的-连续 sequence、每条 record 的 exact channel schema digest 与拒绝未知字段的强类型 product envelope、唯一-event ID、同一 request correlation、零 gap/loss 和各自 terminal。Lifecycle 的 `request_finished` 必须-最后出现;ExecutionFact 的 `request_finished` 后只允许独立的 `usage_and_cache`;ConversationContent 必须-只含 request/response 两个方向并分别形成 `begin … finish`,绝不把 `request_finished` 解释成正文 barrier。结果中的十项-exact evidence 唯一地投影为四个有序 checkpoint;缺失、孤立、损坏、hard-coded、wrong-ready、wrong payload-或 incomplete terminal 均 fail closed。--结果 schema 只允许 scenario `green|red`,并把 `process_exit.test_process_code` 与 `scenario_state` 分开记录。-CLI 只在真实 production evidence 推出 `green` 时返回 0;证据不匹配会写出 `red` 结果并返回非零,启动、-provenance、readiness 或 collector 合同失败也返回非零且不能形成发布证明。完整结果含 synthetic challenge-和 canonical Content evidence,因此以 0600 写入指定路径;stdout 只输出无正文摘要。--验证、重新封口并运行真实 production smoke:+`schema/p0-production-manifest.json` seals the final `gateway-isolated` contract. The manifest+locks one real Responses → Responses production smoke, its profile/scenario, and the+launcher/readiness/collector/result schemas. SHA-256 values cover canonical JSON, so an+unsealed semantic change fails before startup. Old manifests, corpora, goldens, and fixture+adversaries remain historical negative inputs and cannot prove release completion.++The runner uses only the normal+`hirouted --role gateway --listen ... --publication ... --credentials ...` path. The final+contract has no `--fixture`, `--expect-status`, `expected_red`, or `skip`. Each run creates+private publication/credential input, random client/provider capabilities, an unpredictable+freshness challenge, a dynamic loopback listener, and a native provider mock. The profile+pins the Gateway product source revision. Within the binary's checkout, the runner verifies+that source and build inputs have no tracked or untracked drift from that revision, then+performs a trusted `cargo rustc --locked --all-features` rebuild with a random build nonce and+the checkout's current target/toolchain. Launcher evidence binds revision, source-tree and+build-input digests, target, toolchain, command, artifact path, and executable SHA-256.+Legitimate builds need not share a local debug hash, while wrappers and forged build inputs+cannot qualify as the SUT. Before and after readiness probing, OS socket-owner proof requires+the dynamic listener to belong to the same live child PID. `HIROUTE_E2E_SUT_REVISION` adds an+optional external revision assertion.++Provider evidence retains the complete native JSON payload and exact connection count. The+collector independently reads Lifecycle, ExecutionFact, ConversationContent, and+content-free OTel JSONL. Each must have its own producer/epoch/stream identity, contiguous+sequence beginning at 1, exact channel schema digest, strongly typed product envelope that+rejects unknown fields, unique event IDs, common request correlation, no gaps/loss, and its+own terminal. Lifecycle `request_finished` is last; after ExecutionFact `request_finished`,+only independent `usage_and_cache` is allowed. ConversationContent has only request and+response directions, each with `begin … finish`; `request_finished` is never treated as a+content barrier. Ten exact result facts project uniquely to four ordered checkpoints. Missing,+orphaned, damaged, hard-coded, wrong-ready, wrong-payload, or incomplete-terminal evidence+fails closed.++The result schema allows only scenario `green|red` and separates+`process_exit.test_process_code` from `scenario_state`. The CLI returns zero only when real+production evidence establishes green. A mismatch writes a red result and exits non-zero;+startup, provenance, readiness, or collector-contract failure is also non-zero and cannot+become release proof. The full result contains a synthetic challenge and canonical content+evidence, so it is written mode 0600; stdout contains only a body-free summary.++Validate, reseal intentionally, and run the real production smoke:```shcargo build -p hiroute-gateway --bin hirouted --all-featurescargo run -p hiroute-e2e -- validate \--schema e2e/schema --scenario e2e/scenarios/p0-gateway.json-# 只在有意修改任一已锁定 artifact 后运行;连续运行两次,第二次必须零 diff。+# Run only after intentionally changing a locked artifact. Run twice; the second run must+# produce no diff.cargo run -p hiroute-e2e -- seal-production --e2e-root e2eHIROUTE_E2E_SUT_BIN="$PWD/target/debug/hirouted" \@@ -201,19 +260,22 @@ cargo run -p hiroute-e2e -- run \--result target/e2e/p0-gateway-result.json```-本 PROCESS 只冻结这一个 production smoke 和稳定扩展点。九条协议路径、fault/resource/privacy 全矩阵继续由-PROCESS-22009 在其独立 ownership 中补齐;不得把这里的一例绿色外推成完整矩阵完成。+This process freezes only one production smoke and stable extension points. The broader+protocol, fault, resource, and privacy matrix remains owned by its dedicated convergence+work; this one green scenario must not be extrapolated to matrix completion.-`matrix/p0-gateway-coverage.json` 是 PROCESS-22009 的独立 exact coverage index,但不是完成状态的-自报输入。冻结 typed registry 定义完整 required row 集;每个 row 只引用 registry receipt,而 receipt-固定真实 `hirouted` + native Provider 执行模式、测试 target、精确 symbol、完整 source SHA-256 和-assertion identity。`seal-coverage` 只把该 registry 投影为 JSON:+`matrix/p0-gateway-coverage.json` is an exact independent coverage index, not a self-reported+completion flag. A frozen typed registry defines every required row. Each row references a+registry receipt that fixes real `hirouted` + native-provider execution mode, test target,+exact symbol, complete source SHA-256, and assertion identity. `seal-coverage` only projects+that registry:```shcargo run -p hiroute-e2e -- seal-coverage --e2e-root e2e```-`p0_gateway_matrix_coverage` 同时校验 schema、完整 registry projection、source digest、symbol/test-绑定与 assertion identity;缺失 row 或伪造 execution 均失败。index 不包含 `skip`、`expected_red` 或人工-`passed` 状态。个人版 P0 listener 的 transport 行仅是 loopback H1;release H2 benchmark 与 Enterprise-TLS listener 不属于此 matrix。+`p0_gateway_matrix_coverage` verifies schema, complete registry projection, source digest,+symbol/test binding, and assertion identity. Missing rows or forged execution fail. The index+contains no `skip`, `expected_red`, or manual `passed` state. The personal P0 listener's+transport row is loopback H1 only; release H2 benchmarks and Enterprise TLS listeners are+outside this matrix.diff --git a/e2e/README.zh-CN.md b/e2e/README.zh-CN.mdnew file mode 100644index 00000000..67c49142--- /dev/null+++ b/e2e/README.zh-CN.md@@ -0,0 +1,221 @@+# HiRoute black-box E2E++[English](README.md)++这个目录保存环境无关的产品路径合同。它位于 unit、component 和 `gateway-core` lifecycle 测试之上,从真实 TCP 边界验证用户最终看到的行为。++```text+E2E HTTP client+ -> external HiRoute SUT+ -> stock CPA Claude (one source)+ -> Anthropic-native mock+ -> stock CPA Codex (one source)+ -> Responses-native mock+```++`hiroute-e2e` 不依赖 `hiroute-poc` 或 `gateway-core` Rust crate。将来 POC binary 被正式 daemon / Desktop backend 替换时,只要维持外部 CLI 与 HTTP 产品合同,scenario 不需要重写。++## 当前覆盖++[`scenarios/core-routing.json`](scenarios/core-routing.json) 包含十七个顺序步骤:++| 下游协议 | 任务 | 真实 native mock | 预期来源 |+| --- | --- | --- | --- |+| Responses | simple | Anthropic `/v1/messages` | Claude-compatible |+| Responses | complex | Codex `/responses` | Codex subscription |+| Messages | simple | Anthropic `/v1/messages` | Claude-compatible |+| Messages | complex | Codex `/responses` | Codex subscription |+| Responses / Messages | large Agent envelope + simple user | Anthropic `/v1/messages` | Claude-compatible |+| Responses / Messages | tool continuation | Codex `/responses` | 原 Turn affinity hit |+| Responses | simple + Claude 500 | Claude `/v1/messages` 后 Codex `/responses` | precommit fallback 到 Codex |+| Responses | fallback 后 function output | Codex `/responses`,无 Claude Attempt | 回写后的 Turn affinity hit |+| Responses | complex 后追加 simple 完整历史 | Codex `/responses` | 同 Session 前缀保持 Codex |+| Responses | 保留前两条 user、替换后续摘要 | Anthropic `/v1/messages` | 完整历史重建后重新选择 Claude |+| Messages | simple 后追加 complex 完整历史 | Anthropic `/v1/messages` | 同 Session 前缀保持 Claude |+| Messages | 编辑 system、历史正文不变 | Codex `/responses` | 指令变化后重新选择 Codex |+| Responses | 非空 `previous_response_id` | 无 native Attempt | Planner 前返回明确 400 错误码 |++每一步同时断言:++1. 下游状态、SSE content type 与协议终止事件;+2. `x-hiroute-source`;+3. native mock 实际收到的有序 Attempt、native path、native model、response-head status,以及 CPA 使用了该 source 独有的上游鉴权;+4. 是否确实发生 Messages / Responses 协议转换;+5. 每次 Attempt 对应的 routing receipt,其 protocol、source、class、affinity、disposition 与 status;+6. fallback 后接受来源会回写 Turn affinity,function output 续轮直接命中 Codex,不再探测 Claude;+7. 同一稳定 Session 的完整可见历史 append 跨 simple/complex 分支保持实际成功来源,历史重建或指令编辑则重新选路;+8. 不支持的 Responses 服务端续链在 Planner 和 native 上游前拒绝,ledger 与 receipt 均不增加。++上述当前实现只证明基础路径、来源与有限终止事件,**不能**证明协议语义已经保真。当前+`protocol_conversion=true` 仅表示客户端协议与 native mock 协议名称不同;native ledger 只检查+`messages`/`input` 顶层形状,尚未逐项比较 Vision、Tool schema/choice/call/result/ID、+reasoning 原生字段、usage/finish reason、Provider state 和完整 SSE 事件序列。因此不能把当前 17-step suite+表述成正式协议转换 conformance 已通过。++正式 P0 目标由+[`Agent 接入与模型协议转换合同`](../design/product-contract/protocol-conversion-contract.md)定义,并拆成:++- `E2E-P028`:从 exact Codex/Claude Code 安装版本和有效配置解析 AgentIntegrationProfile,分别选择+ Responses/Messages 唯一入口,执行配置 diff/apply/rollback 与真实跨协议 Turn;+- `E2E-D011`:Responses/Messages 入站到 Responses/Chat Completions/Messages 上游的六路径语义保真;+- `E2E-D012`:入站 effort 隔离、AgentPlan exact reasoning configuration 的逐目标协议原生渲染与 fallback 重渲染;+- `E2E-D013`:Tool ID/续轮、Provider state 亲和、统一流式事件、流中错误和 postcommit 零接力。++这四项必须先以有限 schema、canonical Model IR corpus、request/SSE golden 和 native semantic ledger 建成红灯+测试,再实现正式 Adapter。只看 HTTP 200、最终文本、目标 path 或协议名称不同均不构成通过证据。++来源判定以 native mock ledger 为主证据,不信任 response model 或 Gateway 自报 header;后两者只是相互独立的旁证。Native mock 只断言鉴权是否完全匹配,不把任何 credential 写入 ledger 或结果 artifact。++## 环境合同++Scenario 只描述产品行为,禁止 executable path、shell command、端口、延时、任意响应体和凭据。v2 的成功步骤只允许 1–2 次 source-native Attempt,以及有限的 response-head status:`200/429/500/502/503/504/529`;最终 Attempt 必须是 `200 Accept`。入口预校验步骤只允许固定 `400 + error code + 0 Attempt`,用于断言请求没有进入 Planner/native 上游。请求头只允许有界的 `session-id`/`thread-id`,不能注入认证或环境编排。`#[serde(deny_unknown_fields)]`、语义校验与 JSON Schema 共同防止环境编排逐渐渗入用例。++[`profiles/local-process.json`](profiles/local-process.json) 只允许两个固定引用:++```text+HIROUTE_E2E_CPA_BIN -> stock CLIProxyAPI executable+HIROUTE_E2E_SUT_BIN -> external HiRoute executable+```++Runner 每次使用动态端口与 0700 TempDir,生成随机 capability,启动两个 single-source CPA、两个 native mock 与一个 SUT;所有 secret-bearing 文件和进程日志为 0600。每个子进程都有独立、启动时为空的 0700 work directory,并同时作为 `current_dir`、`HOME`、XDG 与 `TMPDIR`,因此 stock CPA 不会向上搜索并读取仓库 `.env`。子进程从 `env_clear()` 的最小环境启动,不继承开发者 shell 中的真实 Provider token;外部 HTTP proxy 被指向 loopback blackhole,native source 只允许 loopback。进程 readiness 使用连接探测,不依赖固定 sleep;退出有界并由 drop 做二次 kill 保证。++结果 artifact 只保留产品证据,不包含:++- 请求或模型响应正文;+- capability / CPA / native API key;+- 端口、临时路径或 executable path;+- command argv 或原始进程日志。++## 使用++验证合同(不要求已有二进制):++```sh+cargo run -p hiroute-e2e -- validate \+ --scenario e2e/scenarios/core-routing.json \+ --profile e2e/profiles/local-process.json+```++运行完整黑盒链路:++```sh+HIROUTE_E2E_CPA_BIN=/absolute/path/to/CLIProxyAPI \+HIROUTE_E2E_SUT_BIN=/absolute/path/to/hiroute-poc \+cargo run -p hiroute-e2e -- run \+ --scenario e2e/scenarios/core-routing.json \+ --profile e2e/profiles/local-process.json \+ --result /tmp/hiroute-e2e-result.json+```++Runner 每次分配动态端口和私有临时目录,启动两个 native mock、两个隔离 stock CPA 和一个外部 HiRoute SUT。它用真实 TCP 验证四个协议/来源象限、两种 Agent envelope 反例、Responses/Messages 工具续轮的 affinity hit、context hold/重建失效、Responses 服务端续链早拒绝,以及 `Claude 500 -> Codex Accept -> function output 直接命中 Codex` 的完整链路。++建议的质量门禁:++```sh+cargo fmt --package hiroute-e2e -- --check+cargo check -p hiroute-e2e+cargo clippy -p hiroute-e2e --all-targets -- -D warnings+cargo test -p hiroute-e2e+```++## 用 E2E 驱动后续功能++新增能力时遵循“产品合同先红、实现后绿”:++1. 用现有字段可表达时,先添加一个 `ScenarioStep`,运行确认因未实现行为而失败。+2. response-head fallback 直接使用 v2 的有限 `attempts`;新能力需要首包断连、语义 SSE failure、更多 step 类型或新的证据时,再升级 Rust contract 与 `schema_version`,同步更新 `e2e/schema/`。+3. 不在 scenario 中加入 shell、路径、sleep、固定端口或 secret;编排能力属于 runner/profile。+4. 对路由能力优先增加 native ledger 断言;对协议能力同时增加原生事件序列和统一语义断言。+5. 实现产品代码,直到本地与 CI 的同一 scenario 通过。+6. 结果 artifact 通过敏感信息扫描后再作为评审证据保留。++推荐下一批 scenario:++- 两个 Turn 交错,affinity 不串线;+- 429/502/503/504/529 response-head 矩阵、首包断连与首个语义 SSE error 的 precommit fallback;+- commit 后禁止重放和总 Attempt 数上限;+- SSE 任意字节切片、长流、客户端取消与内存上界;+- multimodal、`count_tokens`、`compact` 和 usage/cost evidence;+- Codex CLI / Claude Code 的 real-local smoke profile。++当前 v2 native mock 对成功响应返回固定文本 SSE,并支持有限 response-head failure;`ScenarioStep` 只支持 HTTP Turn。不要用任意 shell 字段绕过这个边界;需要上述能力时,应把 stream failure 或 `AgentTurn` 建成新的有限枚举并升级 schema。++## CI 分层++当前公共 CI 在 Linux、macOS、Windows 上编译 harness、运行其 mock/unit tests,并通过 CLI+静态校验 checked-in scenario 与 profile;这条门禁不需要外部二进制、真实账号或凭据。++完整 10-step 进程链路当前仍需要单独提供 stock CPA 与 HiRoute SUT,按上面的 `run` 命令显式执行。+它不会被静态 `validate` 冒充已经在公共 CI 跑通。正式 SUT 可由代码仓库直接构建后,再分层扩展:++- `e2e-core-routing`:构建 stock CPA + SUT,执行当前 10-step hermetic suite;+- `e2e-product`:按 Proposal 增加 fallback、tool、cancel、memory 等套件;+- `e2e-real-local`:显式人工/nightly 触发,使用真实本地 Agent 和授权,不进入公共 CI,也不替代 hermetic suite。++## P0 Gateway exact Oracle++最终 `gateway-isolated` 合同由 `schema/p0-production-manifest.json` 封口。Manifest 锁定一个真实+Responses → Responses production smoke、profile、scenario 和 launcher/readiness/collector/result schema;+artifact SHA-256 对 canonical JSON 计算,任何未重新封口的语义漂移都会在启动前失败。旧+`p0-gateway-manifest.json`、corpus/golden 和 fixture adversary 仍可作为历史负向输入,但不再被最终 profile+加载,也不能证明发布完成。++Runner 只用正常的 `hirouted --role gateway --listen ... --publication ... --credentials ...` 路径;最终合同中+不存在 `--fixture`、`--expect-status`、`expected_red` 或 `skip`。每次运行生成私有 publication/credential+输入、随机 client/provider capability、不可预测 freshness challenge、动态 loopback listener 和 native+Provider mock。Profile 固定 Gateway 产品源码 revision;runner 在 binary 所属 checkout 内检查源码树和构建输入相对该+revision 无 tracked/untracked 漂移,再用当前 target/toolchain 执行带随机 build nonce 的 `cargo rustc --locked+--all-features` 可信重建。Launcher evidence 固定这次重建的 revision/source tree/build-input digest、target、toolchain、+build command、artifact path 和实际 executable SHA-256,因此不同 checkout/平台的合法构建无需共享本地 debug hash,+而 wrapper、非 Cargo artifact 和伪造构建输入不能被当作 SUT。+`/_hiroute/ready` 除精确回报 publication revision/digest 与 executable digest 外,runner 还会在 probe 前后+通过 OS socket-owner proof 要求动态 listener 都由同一存活 child PID 持有。调用方还可用+`HIROUTE_E2E_SUT_REVISION` 增加外部 revision 断言。++Provider 证据保存完整原生 JSON payload 和精确连接计数。Collector 分别读取 Lifecycle、ExecutionFact、+ConversationContent 和 content-free OTel JSONL,要求四套独立 producer/epoch/stream identity、从 1 开始的+连续 sequence、每条 record 的 exact channel schema digest 与拒绝未知字段的强类型 product envelope、唯一+event ID、同一 request correlation、零 gap/loss 和各自 terminal。Lifecycle 的 `request_finished` 必须+最后出现;ExecutionFact 的 `request_finished` 后只允许独立的 `usage_and_cache`;ConversationContent 必须+只含 request/response 两个方向并分别形成 `begin … finish`,绝不把 `request_finished` 解释成正文 barrier。结果中的十项+exact evidence 唯一地投影为四个有序 checkpoint;缺失、孤立、损坏、hard-coded、wrong-ready、wrong payload+或 incomplete terminal 均 fail closed。++结果 schema 只允许 scenario `green|red`,并把 `process_exit.test_process_code` 与 `scenario_state` 分开记录。+CLI 只在真实 production evidence 推出 `green` 时返回 0;证据不匹配会写出 `red` 结果并返回非零,启动、+provenance、readiness 或 collector 合同失败也返回非零且不能形成发布证明。完整结果含 synthetic challenge+和 canonical Content evidence,因此以 0600 写入指定路径;stdout 只输出无正文摘要。++验证、重新封口并运行真实 production smoke:++```sh+cargo build -p hiroute-gateway --bin hirouted --all-features+cargo run -p hiroute-e2e -- validate \+ --schema e2e/schema --scenario e2e/scenarios/p0-gateway.json++# 只在有意修改任一已锁定 artifact 后运行;连续运行两次,第二次必须零 diff。+cargo run -p hiroute-e2e -- seal-production --e2e-root e2e++HIROUTE_E2E_SUT_BIN="$PWD/target/debug/hirouted" \+cargo run -p hiroute-e2e -- run \+ --profile e2e/profiles/gateway-isolated.json \+ --scenario e2e/scenarios/p0-gateway.json \+ --result target/e2e/p0-gateway-result.json+```++本 PROCESS 只冻结这一个 production smoke 和稳定扩展点。九条协议路径、fault/resource/privacy 全矩阵继续由+PROCESS-22009 在其独立 ownership 中补齐;不得把这里的一例绿色外推成完整矩阵完成。++`matrix/p0-gateway-coverage.json` 是 PROCESS-22009 的独立 exact coverage index,但不是完成状态的+自报输入。冻结 typed registry 定义完整 required row 集;每个 row 只引用 registry receipt,而 receipt+固定真实 `hirouted` + native Provider 执行模式、测试 target、精确 symbol、完整 source SHA-256 和+assertion identity。`seal-coverage` 只把该 registry 投影为 JSON:++```sh+cargo run -p hiroute-e2e -- seal-coverage --e2e-root e2e+```++`p0_gateway_matrix_coverage` 同时校验 schema、完整 registry projection、source digest、symbol/test+绑定与 assertion identity;缺失 row 或伪造 execution 均失败。index 不包含 `skip`、`expected_red` 或人工+`passed` 状态。个人版 P0 listener 的 transport 行仅是 loopback H1;release H2 benchmark 与 Enterprise+TLS listener 不属于此 matrix。diff --git a/scripts/check-public-language.py b/scripts/check-public-language.pynew file mode 100644index 00000000..d1fdb763--- /dev/null+++ b/scripts/check-public-language.py@@ -0,0 +1,120 @@+#!/usr/bin/env python3+"""Reject Simplified-Chinese prose in public Markdown's English/default files."""++import argparse+import fnmatch+import json+import os+from pathlib import Path+import re+import subprocess+++HAN = re.compile(r"[\u3400-\u9fff]")+INLINE_CODE = re.compile(r"`[^`]*`")+CHINESE_LINK = re.compile(r"\[[^\]]*[\u3400-\u9fff][^\]]*\]\([^)]*\.(?:zh|zh-CN)\.md(?:#[^)]*)?\)")+MANIFEST = Path(".agents/skills/hiroute-public-pr/references/public-surface.v1.json")+DISCOVERY_EXCLUDES = {".git", "dist", "node_modules", "target", "vendor"}+++def working_markdown(root: Path) -> list[Path]:+ files = []+ for directory, children, names in os.walk(root):+ children[:] = [child for child in children if child not in DISCOVERY_EXCLUDES]+ files.extend(Path(directory) / name for name in names if name.endswith(".md"))+ return files+++def tracked_markdown(root: Path) -> list[Path]:+ files = set(working_markdown(root))+ try:+ output = subprocess.run(+ ["git", "ls-files", "-z", "--", "*.md"],+ cwd=root,+ check=True,+ capture_output=True,+ ).stdout+ files.update(root / value.decode() for value in output.split(b"\0") if value)+ except (OSError, subprocess.CalledProcessError):+ pass+ return sorted(path for path in files if path.is_file())+++def public_markdown(root: Path) -> list[Path]:+ files = tracked_markdown(root)+ manifest_path = root / MANIFEST+ if not manifest_path.is_file():+ return [path for path in files if "vendor" not in path.relative_to(root).parts]++ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))+ include_files = set(manifest["include_files"])+ include_docs = set(manifest["include_docs"])+ include_roots = tuple(manifest["include_roots"])+ exclude_files = set(manifest["exclude_files"])+ exclude_roots = tuple(manifest["exclude_roots"])+ exclude_globs = tuple(manifest["exclude_doc_globs"])+ selected = []+ for path in files:+ relative = path.relative_to(root).as_posix()+ included = relative in include_files or relative in include_docs or relative.startswith(include_roots)+ excluded = (+ relative in exclude_files+ or relative.startswith(exclude_roots)+ or any(fnmatch.fnmatch(relative, pattern) for pattern in exclude_globs)+ )+ if included and not excluded and not relative.startswith("vendor/"):+ selected.append(path)+ return selected+++def is_english_default(path: Path) -> bool:+ return not path.name.endswith((".zh.md", ".zh-CN.md"))+++def prose_violations(path: Path) -> list[tuple[int, str]]:+ violations = []+ fence = None+ for number, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):+ stripped = raw.lstrip()+ marker = stripped[:3]+ if marker in {"```", "~~~"}:+ if fence is None:+ fence = marker+ elif marker == fence:+ fence = None+ continue+ if fence is not None:+ continue+ prose = CHINESE_LINK.sub("", raw)+ prose = INLINE_CODE.sub("", prose)+ if HAN.search(prose):+ violations.append((number, raw.strip()))+ return violations+++def check(root: Path) -> list[str]:+ failures = []+ for path in public_markdown(root):+ if not is_english_default(path):+ continue+ for number, line in prose_violations(path):+ failures.append(f"{path.relative_to(root)}:{number}: {line}")+ return failures+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parent.parent)+ args = parser.parse_args()+ root = args.root.resolve()+ failures = check(root)+ if failures:+ print("public English/default Markdown contains Chinese prose:")+ print("\n".join(f"- {failure}" for failure in failures))+ return 1+ print(f"public language boundary: {len(public_markdown(root))} Markdown files checked")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/test-public-language.py b/scripts/test-public-language.pynew file mode 100644index 00000000..bdc6eb69--- /dev/null+++ b/scripts/test-public-language.py@@ -0,0 +1,50 @@+#!/usr/bin/env python3+"""Tests for the public Markdown language boundary."""++import importlib.util+from pathlib import Path+import subprocess+import tempfile+import unittest+++SCRIPT = Path(__file__).with_name("check-public-language.py")+SPEC = importlib.util.spec_from_file_location("check_public_language", SCRIPT)+MODULE = importlib.util.module_from_spec(SPEC)+SPEC.loader.exec_module(MODULE)+++class PublicLanguageTest(unittest.TestCase):+ def test_detects_chinese_prose_but_ignores_code_and_translation_link(self):+ with tempfile.TemporaryDirectory() as value:+ path = Path(value) / "README.md"+ path.write_text(+ "# English\n\n[Simplified Chinese / 简体中文](README.zh-CN.md)\n\n"+ "Inline `中文 fixture` is code.\n\n```json\n{\"zh\": \"中文\"}\n```\n\n中文泄漏。\n",+ encoding="utf-8",+ )+ self.assertEqual(MODULE.prose_violations(path), [(11, "中文泄漏。")])++ def test_chinese_translation_is_not_an_english_default(self):+ self.assertFalse(MODULE.is_english_default(Path("guide.zh-CN.md")))+ self.assertFalse(MODULE.is_english_default(Path("guide.zh.md")))+ self.assertTrue(MODULE.is_english_default(Path("guide.en.md")))+ self.assertTrue(MODULE.is_english_default(Path("README.md")))++ def test_discovery_includes_untracked_markdown(self):+ with tempfile.TemporaryDirectory() as value:+ root = Path(value)+ subprocess.run(["git", "init", "-q"], cwd=root, check=True)+ (root / "README.md").write_text("# Tracked\n", encoding="utf-8")+ subprocess.run(["git", "add", "README.md"], cwd=root, check=True)+ untracked = root / "NEW.md"+ untracked.write_text("# New\n", encoding="utf-8")+ self.assertIn(untracked, MODULE.tracked_markdown(root))++ def test_repository_public_surface_is_clean(self):+ root = Path(__file__).resolve().parent.parent+ self.assertEqual(MODULE.check(root), [])+++if __name__ == "__main__":+ unittest.main()diff --git a/tools/e2e-harness/SHARDING.md b/tools/e2e-harness/SHARDING.mdindex b048a608..acd5ad4d 100644--- a/tools/e2e-harness/SHARDING.md+++ b/tools/e2e-harness/SHARDING.md@@ -1,10 +1,13 @@# E2E case sharding-通用 `hiroute-e2e` 场景可选地在 `case_shards` 中声明完整分片。每个分片列出-自己必须一起执行的步骤;所有步骤必须恰好属于一个分片。没有该声明的场景不能-用 `--case` 切分,避免把隐含顺序、会话或回退状态误判为独立。+[Simplified Chinese](SHARDING.zh-CN.md)-先查看已声明分片:+A general `hiroute-e2e` scenario may declare complete shards in `case_shards`. Each shard+lists the steps that must execute together, and every step must belong to exactly one shard.+A scenario without that declaration cannot be split with `--case`; this prevents hidden+ordering, session, or fallback state from being misrepresented as independent.++Inspect declared shards first:```shcargo run --locked -p hiroute-e2e -- validate \@@ -12,7 +15,7 @@ cargo run --locked -p hiroute-e2e -- validate \--profile e2e/profiles/local-process.json```-为一个分片运行独立的黑盒进程时,给每次运行唯一结果文件:+Give each isolated black-box process a unique result file:```shcargo run --locked -p hiroute-e2e -- run \@@ -22,11 +25,11 @@ cargo run --locked -p hiroute-e2e -- run \--result target/e2e/responses-complex-continuation.json```-每次 `run` 都创建自己的临时目录、native mock、CPA、SUT 和随机 loopback-端口;不同 case 只有在独立 checkout 中运行时才可以并发。结果会包含-`selected_case`,不能将多个 case 报告合并为一条完整场景的 green 证明。完整-场景仍需运行一次,以验证默认的全步骤顺序。+Each `run` creates its own temporary directory, native mock, CPA, SUT, and random loopback+port. Different cases may run in parallel only from independent checkouts. The result records+`selected_case`; results from several cases cannot be combined into one whole-scenario green+claim. Run the complete scenario once to validate its default full-step ordering.-P0 Gateway 生产 Oracle 是一条密封的单一场景,`--case` 会被拒绝。它的独立-组件与协议测试可按 Rust integration-test target 或精确测试名分片,但最终生产-Oracle 和 seal/汇总必须保持单片、串行。+The P0 Gateway production Oracle is one sealed scenario and rejects `--case`. Its component+and protocol tests may be sharded by Rust integration-test target or exact test name, but the+final production Oracle and seal/aggregation remain single-shard and serial.diff --git a/tools/e2e-harness/SHARDING.zh-CN.md b/tools/e2e-harness/SHARDING.zh-CN.mdnew file mode 100644index 00000000..f071b3a9--- /dev/null+++ b/tools/e2e-harness/SHARDING.zh-CN.md@@ -0,0 +1,34 @@+# E2E case sharding++[English](SHARDING.md)++通用 `hiroute-e2e` 场景可选地在 `case_shards` 中声明完整分片。每个分片列出+自己必须一起执行的步骤;所有步骤必须恰好属于一个分片。没有该声明的场景不能+用 `--case` 切分,避免把隐含顺序、会话或回退状态误判为独立。++先查看已声明分片:++```sh+cargo run --locked -p hiroute-e2e -- validate \+ --scenario e2e/scenarios/core-routing.json \+ --profile e2e/profiles/local-process.json+```++为一个分片运行独立的黑盒进程时,给每次运行唯一结果文件:++```sh+cargo run --locked -p hiroute-e2e -- run \+ --scenario e2e/scenarios/core-routing.json \+ --profile e2e/profiles/local-process.json \+ --case responses-complex-continuation \+ --result target/e2e/responses-complex-continuation.json+```++每次 `run` 都创建自己的临时目录、native mock、CPA、SUT 和随机 loopback+端口;不同 case 只有在独立 checkout 中运行时才可以并发。结果会包含+`selected_case`,不能将多个 case 报告合并为一条完整场景的 green 证明。完整+场景仍需运行一次,以验证默认的全步骤顺序。++P0 Gateway 生产 Oracle 是一条密封的单一场景,`--case` 会被拒绝。它的独立+组件与协议测试可按 Rust integration-test target 或精确测试名分片,但最终生产+Oracle 和 seal/汇总必须保持单片、串行。diff --git a/tools/product-e2e/SMOKE.md b/tools/product-e2e/SMOKE.mdindex 51f20cdf..e529b6c0 100644--- a/tools/product-e2e/SMOKE.md+++ b/tools/product-e2e/SMOKE.md@@ -1,23 +1,39 @@-# 当前候选生产冒烟+# Current-candidate production smoke-`hiroute-smoke` 是开发验证入口。默认 quick 的三个必需案例分别验证:当前生产 Gateway 的受控 Responses 请求、正式 CLI/control-role daemon 经共享 Client Core 的状态、client_access/幂等只读查询与受控发现、被篡改的当前目录资源的安全拒绝。它们不证明控制面发布成功、真实 Agent、真实账号、Desktop 或安装完成。+[Simplified Chinese](SMOKE.zh-CN.md)-## 运行+`hiroute-smoke` is a development-validation entry point. Its default quick run has three+required cases: a controlled Responses request through the production Gateway; real+CLI/control-role daemon status plus read-only `client_access`, idempotent lookup, and+controlled discovery through the shared Client Core; and safe rejection of tampered+current-directory resources. These cases do not prove successful control-plane publication,+a real Agent/account, Desktop, or installation.-遵循仓库远端 Rust 约定,先提交并推送独立候选,再运行:+## Run++Follow the repository's remote Rust convention: commit and push an isolated candidate, then+run:```shpython3 scripts/remote-rust.py run --ref refs/heads/<branch> --sha <full-commit> -- \cargo test --locked -p hiroute-product-e2e --test smoke_cli -- --nocapture```-测试实际调用开发工具并检查默认三例、control 域和单个 Gateway 案例的新运行结果。远端 `completed` 只说明 Cargo 成功及非零 Rust 测试命中,还需检查日志中的逐例状态和 checkout 内 `target/smoke/<run-id>/report.json`。+The test invokes the development tool and checks fresh results for all three default cases,+the control domain, and one Gateway case. A remote `completed` result proves only Cargo exit+and non-zero Rust test selection. Also inspect every case result and+`target/smoke/<run-id>/report.json` in the checkout.-默认 `smoke_cli` 只通过 `default_two_domain_smoke` 执行一次三例真实链路,同时核对每例步骤、scope、结果与报告。CLI domain/case 选择器由不启动产品的 `validate` 测试覆盖。不要再把默认三例与三个单例重复运行;需要定位失败时直接按 case 重跑。+The default `smoke_cli` executes the three real paths once through+`default_two_domain_smoke`, including their steps, scopes, outcomes, and report. The+non-starting `validate` tests cover CLI domain/case selectors. Do not duplicate the default+run with all three individual cases; rerun an exact case only for diagnosis.-同一 checkout 的 `target/smoke/run.lock` 仍保护真实生产子进程与恢复材料。当前构建证明流程保持不变,不能擅自传入未验证的旧二进制来缩短检查。+`target/smoke/run.lock` protects real production subprocesses and recovery materials in one+checkout. The build-proof process is unchanged; do not inject an unverified older binary to+shorten it.-在该验证 checkout 已构建工具后,可直接选择:+After the tool is built in the validation checkout, direct selectors are available:```shtarget/debug/hiroute-smoke list@@ -27,18 +43,48 @@ target/debug/hiroute-smoke run --domain controltarget/debug/hiroute-smoke run --case gateway.responses.controlled```-`list/validate` 仅校验目录或集合,不执行产品。domain/case 是精确 ID;同时提供时取交集,未知、重复、零命中或遗漏请求案例均报错。按旧报告的 `expected_cases` 重跑时,将这些 ID 逐项作为 `--case` 传入;所有 ID 在当前登记集合重新解析,生成新的身份和私有资源,不加载旧成功结果或配置。--## 读结果与恢复--报告分别保存工具退出、产品步骤退出/信号、逐例 green/expected_red/red、未执行原因、源码/产物身份、构建与执行时间、清理状态和能力缺口。大体积调试产物的完整性复核仍在每次产品命令启动前后执行,但这段 runner 证据开销不消耗 30 秒产品场景或 10 秒产品步骤等待预算。当前目录资源的 schema 或摘要篡改被正确拒绝时,daemon 非零退出与该负向案例 green 可以同时成立。未交付的 Agent、真实账号、Desktop 和安装适配只能返回 not_executed,不能返回 expected_red。`Report::verify` 是结构一致性检查,不能将外来 JSON 认证为生产证据。--子进程只使用本次隔离目录。控制面发现脚本是合成输入,不会调用日常 Codex/Claude。Agent 正式适配尚未接通;已有组件合同要求先证明全部配置层隔离,变更后经正式恢复并核对,再清理。冲突或恢复失败保留恢复上下文,不用复制备份覆盖用户配置。--日志和恢复定位信息仅存放在私有区域,不自动上传。正常取消先停止新操作并回收本次进程;强制 SIGKILL、主机重启或远端硬期限可能留下 interrupted 资源。发现未结束的 private/run.journal 时应人工检查该次 PID/资源,不能把旧记录转成 green,也不能批量清理仍活动的任务。失败 runtime 使用私有短临时目录并保留,成功后清理;Cargo 始终使用本 checkout 默认 target。--## 领域贡献--领域在 `src/smoke/registry.rs` 登记有限案例,并提供自己的真实操作和业务断言。中央 runner 只负责选择、生命周期和公共报告。17 在 control 案例中消费 CLI → shared Client Core → Application 的只读 `client_access` 与 `FindOperationByIdempotency` 路径;01 拥有控制面发布/恢复业务语义,02 拥有实际 Desktop 窗口、原生确认与改名业务案例,Agent 和安装领域提供正式恢复及平台证据。不要用内部 Application seam、手写 socket 或 fixture 输出替代所声称的产品入口。--若 Gateway 内层在返回耗时分解前失败,报告保留已知 build_ms,其余墙钟耗时记为 unclassified_ms,timing_complete=false,execution_ms 不冒充纯产品耗时。+`list/validate` checks a catalog or selection without running the product. Domain and case+are exact IDs; their combination is an intersection. Unknown, duplicate, zero-selection, or+missing requested cases fail. To rerun an old report's `expected_cases`, pass each ID as a+`--case`; every ID is resolved against the current registry with new identities and private+resources. Old successful results and configuration are never loaded.++## Results and recovery++The report records tool exit, product-step exit/signal, per-case+green/expected_red/red, reasons for non-execution, source/artifact identity, build and+execution timing, cleanup state, and capability gaps. Large debug-artifact integrity checks+run before and after each product command and do not consume the 30-second product-scenario+or 10-second product-step budgets. Safe rejection of a tampered current-directory resource+can be a green negative case even when the daemon exits non-zero. Undelivered Agent,+real-account, Desktop, or installation adapters must be `not_executed`, never `expected_red`.+`Report::verify` checks structural consistency and cannot authenticate foreign JSON as+production evidence.++Subprocesses use only the current isolated directory. The control discovery script uses+synthetic input and never calls an everyday Codex/Claude account. A production Agent adapter+is not connected here; existing component contracts require all configuration layers to be+isolated, formally restored, and checked before cleanup. Preserve recovery context after a+conflict or failed restore instead of copying a backup over user configuration.++Logs and recovery locators remain private and are not uploaded automatically. Normal+cancellation stops new work and reclaims this run's processes. SIGKILL, host restart, or a+remote hard deadline may leave interrupted resources. If `private/run.journal` shows an+unfinished run, inspect that PID and its resources manually; never turn an old journal into+green evidence or bulk-delete active work. Failed runtimes retain a short private temporary+directory; successful ones clean it. Cargo always uses this checkout's default `target/`.++## Domain contributions++A domain registers a bounded case in `src/smoke/registry.rs` and owns its real action and+business assertions. The central runner owns only selection, lifecycle, and the common+report. Domain 17 consumes the read-only CLI → shared Client Core → Application+`client_access` and `FindOperationByIdempotency` paths in the control case. Domain 01 owns+control-plane publication/recovery semantics; Domain 02 owns real Desktop windows, native+confirmation, and rename scenarios; Agent and installation domains own formal recovery and+platform evidence. Do not replace a claimed product entry with an internal Application seam,+handwritten socket, or fixture output.++If an inner Gateway failure occurs before timing decomposition is returned, the report keeps+known `build_ms`, assigns the remaining wall time to `unclassified_ms`, sets+`timing_complete=false`, and never presents `execution_ms` as pure product time.diff --git a/tools/product-e2e/SMOKE.zh-CN.md b/tools/product-e2e/SMOKE.zh-CN.mdnew file mode 100644index 00000000..aafdd625--- /dev/null+++ b/tools/product-e2e/SMOKE.zh-CN.md@@ -0,0 +1,46 @@+# 当前候选生产冒烟++[English](SMOKE.md)++`hiroute-smoke` 是开发验证入口。默认 quick 的三个必需案例分别验证:当前生产 Gateway 的受控 Responses 请求、正式 CLI/control-role daemon 经共享 Client Core 的状态、client_access/幂等只读查询与受控发现、被篡改的当前目录资源的安全拒绝。它们不证明控制面发布成功、真实 Agent、真实账号、Desktop 或安装完成。++## 运行++遵循仓库远端 Rust 约定,先提交并推送独立候选,再运行:++```sh+python3 scripts/remote-rust.py run --ref refs/heads/<branch> --sha <full-commit> -- \+ cargo test --locked -p hiroute-product-e2e --test smoke_cli -- --nocapture+```++测试实际调用开发工具并检查默认三例、control 域和单个 Gateway 案例的新运行结果。远端 `completed` 只说明 Cargo 成功及非零 Rust 测试命中,还需检查日志中的逐例状态和 checkout 内 `target/smoke/<run-id>/report.json`。++默认 `smoke_cli` 只通过 `default_two_domain_smoke` 执行一次三例真实链路,同时核对每例步骤、scope、结果与报告。CLI domain/case 选择器由不启动产品的 `validate` 测试覆盖。不要再把默认三例与三个单例重复运行;需要定位失败时直接按 case 重跑。++同一 checkout 的 `target/smoke/run.lock` 仍保护真实生产子进程与恢复材料。当前构建证明流程保持不变,不能擅自传入未验证的旧二进制来缩短检查。++在该验证 checkout 已构建工具后,可直接选择:++```sh+target/debug/hiroute-smoke list+target/debug/hiroute-smoke validate --domain control+target/debug/hiroute-smoke run+target/debug/hiroute-smoke run --domain control+target/debug/hiroute-smoke run --case gateway.responses.controlled+```++`list/validate` 仅校验目录或集合,不执行产品。domain/case 是精确 ID;同时提供时取交集,未知、重复、零命中或遗漏请求案例均报错。按旧报告的 `expected_cases` 重跑时,将这些 ID 逐项作为 `--case` 传入;所有 ID 在当前登记集合重新解析,生成新的身份和私有资源,不加载旧成功结果或配置。++## 读结果与恢复++报告分别保存工具退出、产品步骤退出/信号、逐例 green/expected_red/red、未执行原因、源码/产物身份、构建与执行时间、清理状态和能力缺口。大体积调试产物的完整性复核仍在每次产品命令启动前后执行,但这段 runner 证据开销不消耗 30 秒产品场景或 10 秒产品步骤等待预算。当前目录资源的 schema 或摘要篡改被正确拒绝时,daemon 非零退出与该负向案例 green 可以同时成立。未交付的 Agent、真实账号、Desktop 和安装适配只能返回 not_executed,不能返回 expected_red。`Report::verify` 是结构一致性检查,不能将外来 JSON 认证为生产证据。++子进程只使用本次隔离目录。控制面发现脚本是合成输入,不会调用日常 Codex/Claude。Agent 正式适配尚未接通;已有组件合同要求先证明全部配置层隔离,变更后经正式恢复并核对,再清理。冲突或恢复失败保留恢复上下文,不用复制备份覆盖用户配置。++日志和恢复定位信息仅存放在私有区域,不自动上传。正常取消先停止新操作并回收本次进程;强制 SIGKILL、主机重启或远端硬期限可能留下 interrupted 资源。发现未结束的 private/run.journal 时应人工检查该次 PID/资源,不能把旧记录转成 green,也不能批量清理仍活动的任务。失败 runtime 使用私有短临时目录并保留,成功后清理;Cargo 始终使用本 checkout 默认 target。++## 领域贡献++领域在 `src/smoke/registry.rs` 登记有限案例,并提供自己的真实操作和业务断言。中央 runner 只负责选择、生命周期和公共报告。17 在 control 案例中消费 CLI → shared Client Core → Application 的只读 `client_access` 与 `FindOperationByIdempotency` 路径;01 拥有控制面发布/恢复业务语义,02 拥有实际 Desktop 窗口、原生确认与改名业务案例,Agent 和安装领域提供正式恢复及平台证据。不要用内部 Application seam、手写 socket 或 fixture 输出替代所声称的产品入口。++若 Gateway 内层在返回耗时分解前失败,报告保留已知 build_ms,其余墙钟耗时记为 unclassified_ms,timing_complete=false,execution_ms 不冒充纯产品耗时。