@router-agent/runtime 0.0.0-stage → 0.3.32

package/dist/runtimes/acp-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-agents.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/runtimes/acp-agents.ts"],"names":[],"mappings":"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"}

package/dist/runtimes/acp-detect-utils.d.ts

@@ -0,0 +1,4 @@
+/** 在 PATH 里解析命令；支持 Windows 的 PATHEXT。返回绝对路径。 */
+export declare function resolveExecutable(command: string, env: NodeJS.ProcessEnv): string | undefined;
+/** 从 `--version` 输出里提取 x.y.z；找不到返回 undefined。 */
+export declare function parseVersion(text: string): string | undefined;

package/dist/runtimes/acp-detect-utils.js

@@ -0,0 +1,35 @@
+/**
+ * 运行时共用的可执行文件解析与版本提取（纯函数，不 spawn）。
+ * ACP 插件与其它运行时插件都从这里取同一份语义。
+ */
+import { existsSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** 在 PATH 里解析命令；支持 Windows 的 PATHEXT。返回绝对路径。 */
+export function resolveExecutable(command, env) {
+    const value = command.trim();
+    if (!value)
+        return undefined;
+    if (isAbsolute(value) || value.includes('/') || value.includes('\\')) {
+        return existsSync(value) ? value : undefined;
+    }
+    const pathValue = env.PATH ?? env.Path ?? '';
+    const extensions = process.platform === 'win32'
+        ? ['', '.cmd', '.exe', '.bat']
+        : [''];
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of extensions) {
+            const candidate = join(dir, `${value}${ext}`);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** 从 `--version` 输出里提取 x.y.z；找不到返回 undefined。 */
+export function parseVersion(text) {
+    const match = /(\d+\.\d+\.\d+(?:[-+][\w.-]+)?)/.exec(text);
+    return match?.[1];
+}
+//# sourceMappingURL=acp-detect-utils.js.map

package/dist/runtimes/acp-detect-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-detect-utils.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/runtimes/acp-detect-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEvD,gDAAgD;AAChD,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,GAAsB;IACvE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IAC5B,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IAC9C,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAA;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC7C,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC9B,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACR,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,GAAG;YAAE,SAAQ;QAClB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC,CAAA;YAC7C,IAAI,UAAU,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAA;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,iCAAiC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC1D,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;AACnB,CAAC"}

package/dist/runtimes/builtin-options.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeOptionSpec } from './options.js';
+export declare const ORCA_OPTION_SPEC: RuntimeOptionSpec;
+export declare const HERDR_OPTION_SPEC: RuntimeOptionSpec;

package/dist/runtimes/builtin-options.js

@@ -0,0 +1,44 @@
+export const ORCA_OPTION_SPEC = {
+    runtimeId: 'orca',
+    fields: [
+        {
+            key: 'agent',
+            label: '执行 Agent',
+            kind: 'select',
+            default: 'claude',
+            options: [
+                { value: 'claude', label: 'claude · Claude Code' },
+                { value: 'codex', label: 'codex · Codex' },
+                { value: 'opencode', label: 'opencode · OpenCode' },
+                { value: 'devin', label: 'devin · Devin' },
+                { value: 'antigravity', label: 'antigravity · Antigravity' },
+            ],
+            hint: 'Orca 在工单 worktree 里启动哪个 Agent；默认 Claude Code',
+        },
+    ],
+};
+export const HERDR_OPTION_SPEC = {
+    runtimeId: 'herdr',
+    fields: [
+        {
+            key: 'agent',
+            label: '执行 Agent',
+            kind: 'select',
+            default: 'claude',
+            options: [
+                { value: 'claude', label: 'claude · Claude Code' },
+                { value: 'codex', label: 'codex · Codex' },
+                { value: 'opencode', label: 'opencode · OpenCode' },
+            ],
+            hint: 'Herdr 在工单 worktree 里启动哪个 Agent；默认 Claude Code',
+        },
+        {
+            key: 'model',
+            label: '模型',
+            kind: 'text',
+            placeholder: '留空则用 Agent 自己的默认模型',
+            hint: '传给 Agent 的模型名；不同 Agent 的参数名由 adapter 自己映射',
+        },
+    ],
+};
+//# sourceMappingURL=builtin-options.js.map

package/dist/runtimes/builtin-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-options.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/runtimes/builtin-options.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE;QACN;YACE,GAAG,EAAE,OAAO;YACZ,KAAK,EAAE,UAAU;YACjB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,sBAAsB,EAAE;gBAClD,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE;gBAC1C,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,qBAAqB,EAAE;gBACnD,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE;gBAC1C,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,2BAA2B,EAAE;aAC7D;YACD,IAAI,EAAE,8CAA8C;SACrD;KACF;CACF,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,SAAS,EAAE,OAAO;IAClB,MAAM,EAAE;QACN;YACE,GAAG,EAAE,OAAO;YACZ,KAAK,EAAE,UAAU;YACjB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,sBAAsB,EAAE;gBAClD,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE;gBAC1C,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,qBAAqB,EAAE;aACpD;YACD,IAAI,EAAE,+CAA+C;SACtD;QACD;YACE,GAAG,EAAE,OAAO;YACZ,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,MAAM;YACZ,WAAW,EAAE,oBAAoB;YACjC,IAAI,EAAE,2CAA2C;SAClD;KACF;CACF,CAAA"}

package/dist/runtimes/catalog.d.ts

@@ -0,0 +1,31 @@
+export declare const ORCA_RUNTIME_ID = "orca";
+export declare const CLAUDE_CODE_RUNTIME_ID = "claude-code";
+export declare const ACP_RUNTIME_ID = "acp";
+export declare const CODEX_APP_RUNTIME_ID = "codex-app";
+export declare const HERDR_RUNTIME_ID = "herdr";
+export interface WorkerRuntimeMeta {
+    id: string;
+    /** 产品名（自然大小写）；Web 面板按首字母大写展示，CLI 与文档保持原样。 */
+    name: string;
+    label: string;
+    hint: string;
+    /** 不能由 ra 自动安装时的界面引导文案。 */
+    installHint?: string;
+    /** CLI 的官方安装/下载页；Web 卡片直接跳转，不再展示易变的安装命令。 */
+    installUrl?: string;
+}
+export declare const WORKER_RUNTIMES: readonly WorkerRuntimeMeta[];
+export declare const WORKER_RUNTIME_IDS: readonly string[];
+/** 兼容旧配置与旧工单：claude-cli 已改名为 claude-code。 */
+export declare const LEGACY_CLAUDE_CODE_RUNTIME_ID = "claude-cli";
+export declare const LEGACY_RUNTIME_IDS: Readonly<Record<string, string>>;
+/** 把历史 runtime id 归一成当前 id；未知 id 原样返回，交给注册表报错。 */
+export declare function normalizeRuntimeId(id: string): string;
+/**
+ * 是否是已知的 worker runtime id。
+ *
+ * 包含内置运行时（orca / claude-code / codex-app / acp）和 ACP 目录里的动态运行时
+ * （acp-claude / acp-codex / ...）。未知值让配置校验直接拒绝，避免拼错后
+ * 启动期才炸。
+ */
+export declare function isWorkerRuntimeId(id: string): boolean;

package/dist/runtimes/catalog.js

@@ -0,0 +1,75 @@
+/**
+ * Worker 运行时清单：配置校验、Web 面板下拉、CLI 提示共用这一份。
+ *
+ * 这里只放纯常量，不能依赖任何 Node 内置模块 —— Web 面板会把它一起打进前端包。
+ */
+import { ACP_AGENTS } from './acp-agents.js';
+export const ORCA_RUNTIME_ID = 'orca';
+export const CLAUDE_CODE_RUNTIME_ID = 'claude-code';
+export const ACP_RUNTIME_ID = 'acp';
+export const CODEX_APP_RUNTIME_ID = 'codex-app';
+export const HERDR_RUNTIME_ID = 'herdr';
+export const WORKER_RUNTIMES = [
+    {
+        id: ORCA_RUNTIME_ID,
+        name: 'Orca',
+        label: 'orca · Orca worktree + 终端',
+        hint: '通过 Orca 创建 worktree 并启动 Agent 终端（默认跟随 Orca 配置），交互与状态读取走 Orca',
+        installHint: '从 Orca 官方发布页下载安装，并确保 orca CLI 在 PATH 中',
+        installUrl: 'https://github.com/stablyai/orca/releases',
+    },
+    {
+        id: CLAUDE_CODE_RUNTIME_ID,
+        name: 'Claude Code',
+        label: 'claude-code · git worktree + claude --bg',
+        hint: '直接调用 Claude Code CLI 的后台会话；项目 repo 需要填本地仓库绝对路径',
+        installHint: '参考 Claude Code 官方安装说明',
+        installUrl: 'https://docs.claude.com/en/docs/claude-code/setup',
+    },
+    {
+        id: CODEX_APP_RUNTIME_ID,
+        name: 'Codex App',
+        label: 'codex-app · Codex App Server',
+        hint: '直连 Codex App Server；优先使用 Codex App 内置 CLI，桌面端可见同一 thread',
+        installHint: '安装 Codex App（macOS/Windows）或 Codex CLI；ra 会优先使用 Codex App 内置的版本',
+        installUrl: 'https://chatgpt.com/codex',
+    },
+    {
+        id: ACP_RUNTIME_ID,
+        name: 'ACP',
+        label: 'acp · 任意 ACP Agent',
+        hint: '通过 ACP 协议接入其它 Agent；启用前需要在 runtime.options.acp 配置 command',
+        installHint: '在 config.yaml 的 runtime.options.acp 下配置 command 与 args，然后重启服务',
+    },
+    {
+        id: HERDR_RUNTIME_ID,
+        name: 'Herdr',
+        label: 'herdr · git worktree + Herdr 终端',
+        hint: '检出由 ra 用 git worktree 建，Herdr 只开终端窗口跑 Agent；状态来自 Herdr 的 Agent 检测',
+        installHint: '从 Herdr 官方发布页下载安装，并确保 herdr CLI 在 PATH 中',
+        installUrl: 'https://github.com/herdrdev/herdr/releases',
+    },
+];
+export const WORKER_RUNTIME_IDS = WORKER_RUNTIMES.map(runtime => runtime.id);
+/** 兼容旧配置与旧工单：claude-cli 已改名为 claude-code。 */
+export const LEGACY_CLAUDE_CODE_RUNTIME_ID = 'claude-cli';
+export const LEGACY_RUNTIME_IDS = {
+    [LEGACY_CLAUDE_CODE_RUNTIME_ID]: CLAUDE_CODE_RUNTIME_ID,
+};
+/** 把历史 runtime id 归一成当前 id；未知 id 原样返回，交给注册表报错。 */
+export function normalizeRuntimeId(id) {
+    const value = id.trim();
+    return LEGACY_RUNTIME_IDS[value] ?? value;
+}
+/**
+ * 是否是已知的 worker runtime id。
+ *
+ * 包含内置运行时（orca / claude-code / codex-app / acp）和 ACP 目录里的动态运行时
+ * （acp-claude / acp-codex / ...）。未知值让配置校验直接拒绝，避免拼错后
+ * 启动期才炸。
+ */
+export function isWorkerRuntimeId(id) {
+    const value = normalizeRuntimeId(id);
+    return WORKER_RUNTIME_IDS.includes(value) || ACP_AGENTS.some(agent => agent.runtimeId === value);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/runtimes/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/runtimes/catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAA;AACrC,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAA;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAA;AACnC,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAA;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAcvC,MAAM,CAAC,MAAM,eAAe,GAAiC;IAC3D;QACE,EAAE,EAAE,eAAe;QACnB,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,2BAA2B;QAClC,IAAI,EAAE,8DAA8D;QACpE,WAAW,EAAE,wCAAwC;QACrD,UAAU,EAAE,2CAA2C;KACxD;IACD;QACE,EAAE,EAAE,sBAAsB;QAC1B,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,0CAA0C;QACjD,IAAI,EAAE,gDAAgD;QACtD,WAAW,EAAE,uBAAuB;QACpC,UAAU,EAAE,mDAAmD;KAChE;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,8BAA8B;QACrC,IAAI,EAAE,0DAA0D;QAChE,WAAW,EAAE,iEAAiE;QAC9E,UAAU,EAAE,2BAA2B;KACxC;IACD;QACE,EAAE,EAAE,cAAc;QAClB,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,2DAA2D;QACjE,WAAW,EAAE,+DAA+D;KAC7E;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,iCAAiC;QACxC,IAAI,EAAE,mEAAmE;QACzE,WAAW,EAAE,0CAA0C;QACvD,UAAU,EAAE,4CAA4C;KACzD;CACF,CAAA;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAsB,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;AAE/F,6CAA6C;AAC7C,MAAM,CAAC,MAAM,6BAA6B,GAAG,YAAY,CAAA;AAEzD,MAAM,CAAC,MAAM,kBAAkB,GAAqC;IAClE,CAAC,6BAA6B,CAAC,EAAE,sBAAsB;CACxD,CAAA;AAED,kDAAkD;AAClD,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,EAAE,CAAA;IACvB,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,MAAM,KAAK,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAA;IACpC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,CAAA;AAClG,CAAC"}

package/dist/runtimes/options.d.ts

@@ -0,0 +1,60 @@
+export { ORCA_OPTION_SPEC, HERDR_OPTION_SPEC } from './builtin-options.js';
+export type RuntimeOptionKind = 'text' | 'select' | 'switch' | 'number';
+export interface RuntimeOptionValue {
+    value: string;
+    label: string;
+    hint?: string;
+}
+export interface RuntimeOptionField {
+    /** 选项键；配置里对应 `runtime.options.<runtimeId>.<key>`。 */
+    key: string;
+    label: string;
+    kind: RuntimeOptionKind;
+    /**
+     * 未配置时的声明式默认值。
+     *
+     * 运行时与面板都从这里取值，避免「默认值」散落在 adapter、面板、文档三处。
+     * 有些工具的选项没有可省略的形态（例如 Orca 的 `--prompt` 必须配 `--agent`），
+     * 这种情况就靠这里给出一个真实默认值，而不是让调用方猜。
+     */
+    default?: string | number | boolean;
+    /** kind=select 时的候选取值。 */
+    options?: RuntimeOptionValue[];
+    placeholder?: string;
+    hint?: string;
+    /** kind=number 时的取值范围。 */
+    min?: number;
+    max?: number;
+}
+export interface RuntimeOptionSpec {
+    runtimeId: string;
+    fields: RuntimeOptionField[];
+}
+/** 所有运行时的选项声明；新增运行时在这里加一行即可。 */
+export declare const RUNTIME_OPTION_SPECS: readonly RuntimeOptionSpec[];
+export declare function optionSpecOf(runtimeId: string): RuntimeOptionSpec | null;
+export declare function optionFieldOf(runtimeId: string, key: string): RuntimeOptionField | null;
+/** 某个选项未配置时的声明式默认值；没有声明返回 undefined。 */
+export declare function runtimeOptionDefault(runtimeId: string, key: string): unknown;
+/** 配置里的点路径：runtime.options.<runtimeId>.<key>。 */
+export declare function runtimeOptionPath(runtimeId: string, key: string): string;
+/** 解析 `runtime.options.<runtimeId>.<key>`；不是这个形状返回 null。 */
+export declare function parseRuntimeOptionPath(path: string): {
+    runtimeId: string;
+    key: string;
+} | null;
+/** 全部已声明的选项路径；面板据此判断「哪些配置被改过」。 */
+export declare function runtimeOptionPaths(): string[];
+/**
+ 从配置里取某个运行时的字符串选项。
+ *
+ * 运行时之间没有特例：调用方只需要知道「我要哪个运行时的哪个选项」。
+ * 没配置（或显式留空）时回落到声明里的默认值。
+ */
+export declare function runtimeOptionString(options: Record<string, unknown> | undefined, runtimeId: string, key: string): string;
+/**
+ * 校验一个选项值；合法返回 null，否则返回可直接展示给用户的错误文案。
+ *
+ * select 的候选取值里允许出现空串：它表示「不覆盖」，写入配置时应当删掉这个键。
+ */
+export declare function validateRuntimeOption(field: RuntimeOptionField, value: unknown): string | null;

package/dist/runtimes/options.js

@@ -0,0 +1,89 @@
+/**
+ * 运行时选项：每个运行时自己声明「可以配什么」，面板按声明渲染、后端按声明校验。
+ *
+ * 这里只放纯类型与纯函数，不能依赖任何 Node 内置模块 —— Web 面板会把它一起打进前端包。
+ * 配置落点是通用的 `runtime.options.<runtimeId>.<key>`，新增运行时不需要改内核或面板。
+ */
+import { ORCA_OPTION_SPEC, HERDR_OPTION_SPEC } from './builtin-options.js';
+export { ORCA_OPTION_SPEC, HERDR_OPTION_SPEC } from './builtin-options.js';
+/** 所有运行时的选项声明；新增运行时在这里加一行即可。 */
+export const RUNTIME_OPTION_SPECS = [ORCA_OPTION_SPEC, HERDR_OPTION_SPEC];
+export function optionSpecOf(runtimeId) {
+    return RUNTIME_OPTION_SPECS.find(spec => spec.runtimeId === runtimeId) ?? null;
+}
+export function optionFieldOf(runtimeId, key) {
+    return optionSpecOf(runtimeId)?.fields.find(field => field.key === key) ?? null;
+}
+/** 某个选项未配置时的声明式默认值；没有声明返回 undefined。 */
+export function runtimeOptionDefault(runtimeId, key) {
+    return optionFieldOf(runtimeId, key)?.default;
+}
+/** 配置里的点路径：runtime.options.<runtimeId>.<key>。 */
+export function runtimeOptionPath(runtimeId, key) {
+    return `runtime.options.${runtimeId}.${key}`;
+}
+/** 解析 `runtime.options.<runtimeId>.<key>`；不是这个形状返回 null。 */
+export function parseRuntimeOptionPath(path) {
+    const match = /^runtime\.options\.([^.]+)\.([^.]+)$/.exec(path);
+    if (!match)
+        return null;
+    return { runtimeId: match[1], key: match[2] };
+}
+/** 全部已声明的选项路径；面板据此判断「哪些配置被改过」。 */
+export function runtimeOptionPaths() {
+    return RUNTIME_OPTION_SPECS.flatMap(spec => spec.fields.map(field => runtimeOptionPath(spec.runtimeId, field.key)));
+}
+/**
+ 从配置里取某个运行时的字符串选项。
+ *
+ * 运行时之间没有特例：调用方只需要知道「我要哪个运行时的哪个选项」。
+ * 没配置（或显式留空）时回落到声明里的默认值。
+ */
+export function runtimeOptionString(options, runtimeId, key) {
+    const entry = options?.[runtimeId];
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+        const value = entry[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    const fallback = runtimeOptionDefault(runtimeId, key);
+    return typeof fallback === 'string' ? fallback.trim() : '';
+}
+/**
+ * 校验一个选项值；合法返回 null，否则返回可直接展示给用户的错误文案。
+ *
+ * select 的候选取值里允许出现空串：它表示「不覆盖」，写入配置时应当删掉这个键。
+ */
+export function validateRuntimeOption(field, value) {
+    switch (field.kind) {
+        case 'select': {
+            const text = String(value ?? '').trim();
+            const allowed = field.options?.map(option => option.value) ?? [];
+            if (allowed.includes(text))
+                return null;
+            // 留空表示回到声明里的默认值；没声明默认值的选项仍然必须显式选择。
+            if (text === '' && field.default !== undefined)
+                return null;
+            return `取值必须是：${allowed.map(item => item || '(空)').join(' / ')}`;
+        }
+        case 'switch': {
+            if (typeof value === 'boolean')
+                return null;
+            const text = String(value ?? '').trim();
+            return text === 'true' || text === 'false' ? null : '取值必须是 true / false';
+        }
+        case 'number': {
+            const n = Number(value);
+            if (!Number.isInteger(n))
+                return '必须是整数';
+            if (field.min !== undefined && n < field.min)
+                return `不能小于 ${field.min}`;
+            if (field.max !== undefined && n > field.max)
+                return `不能大于 ${field.max}`;
+            return null;
+        }
+        default:
+            return typeof value === 'string' ? null : '必须是字符串';
+    }
+}
+//# sourceMappingURL=options.js.map

package/dist/runtimes/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/runtimes/options.ts"],"names":[],"mappings":"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"}

package/dist/spec/contract.md

@@ -0,0 +1,120 @@
+# Router Agent Worker 手册
+
+你是 router-agent 派出的 Worker，在一个独立的 git worktree 里工作，负责完成下面这张工单。
+你**只对 Router（编排层）负责**：所有状态通过 `ra report` 上报，不要直接给飞书发消息，不要自己联系发起人。
+
+## 工单
+
+- 工单 ID：`{{ticketId}}`
+- 标题：{{title}}
+- 授权范围：{{scope}}
+- 仓库：{{repo}}
+- 起始分支：{{branch}}
+- 工作分支：{{workBranch}}
+- 工作目录：{{workdir}}
+
+{{attachments}}
+
+## 先判断怎么回
+
+| 产出 | 怎么交付 |
+| --- | --- |
+| 代码变更 | 开 PR（GitHub）或 MR（GitLab），`ra report` 带上 `--pr-number` / `--pr-url`，可附一段 `--reply` 说明；改 UI 时 PR / MR 描述必须附 Before / After 对比 |
+| 分析、结论、答疑 | 把要发的话直接写进 `--reply` |
+| 很长的结论 / 多章节 / 需要沉淀转发 | 先 `ra doc` 生成飞书文档，再把文档链接写进 `--reply` |
+
+- **非代码类工单不要为了交付去改代码、跑构建或开 PR / MR**，也不要因为「没有 PR / MR」而卡住。
+- GitHub 仓库用 `gh` 开 PR，GitLab 仓库用 `glab mr create` 开 MR；没有 `glab` 时可用 `git push -o merge_request.create`。两种都把编号与链接带进 `--pr-number` / `--pr-url`。
+- Router 只发送 `--reply` 的原文，不会替你改写、压缩或判断「该不该转文档」。形态由你决定。
+
+## 工作方式
+
+1. 先读仓库里的 README / 约定，确认怎么构建和测试（仅代码类需要）。
+2. 只在授权范围内改动代码；需要跨范围时，用 `blocked` 上报说明原因，等人确认。
+3. 代码类：改完必须自己跑测试或构建，确认通过后再开 PR / MR。
+4. 非代码类：直接产出完整结论，不要压缩成一句话。
+5. 每轮结束前必须执行一次 `ra report`。
+
+## 上报命令（唯一对外通道）
+
+```bash
+ra report \
+  --ticket {{ticketId}} \
+  --state progress|waiting|ready|blocked|failed|dropped \
+  --summary "一句话说明这一轮做了什么" \
+  [--reply @answer.md | - | "要发给用户的话"] \
+  [--pr-number 12 --pr-url "https://..."] \
+  [--ui-change [true|false]] \
+  [--human-action "blocked 时要人做的事"] \
+  [--ack in_xxx]
+```
+
+- `--summary` 只放一句话（给日志和列表用）；**用户真正看到的内容全部放 `--reply`**。
+- `--state progress` 是中途进展，Router 会按 `progress.syncMs` 合并后同步到话题；
+  带 `--ack` 的追问回答会立即发送。需要用户立刻看到的内容请用 `ready`。
+- **不要手写 `state.json`**。`ra report` 会 POST 给本地 Router；服务不可达时会自动落盘，等 Router 轮询。
+- 同一个工单有多轮时不用自己算 turn，Router 会自增。
+
+## 回复怎么写
+
+- 直接给结论，不要只写「我做了什么」的过程。
+- Markdown 可以直接用；Router 会以飞书卡片渲染标题、列表、链接、代码块。
+- 有 PR 就附 PR 链接；有飞书文档就附文档链接。
+
+## 代码交付
+
+- 分支名：`{{workBranch}}`。
+- PR / MR 标题用中文，正文写清「做了什么 / 怎么验证的 / 风险」。
+- 上报时带 `--pr-number`、`--pr-url`；不要自己合并 PR / MR，合并由人决定。
+- CI 失败时修到绿；修不动用 `blocked` 说明失败原因。
+
+## UI 改动：必须交 Before / After 对比
+
+只要改动会影响用户看到或操作的界面（页面、组件、样式、交互、布局），PR / MR 描述里必须同时给出 **Before** 和 **After** 两组视觉证据，并标明基线版本与改动版本。
+
+- 两组截图或录屏使用同一场景、同一视口（窗口尺寸）、同一主题（明 / 暗）和同一 UI 状态，保证对比有意义。
+- **只有 After 不算完整交付**；不要用设计稿、手工 mockup 或改动后的页面冒充 Before。
+- 必须是真实运行中的页面截图；不要暴露飞书私密内容、真实用户数据或任何凭据。
+- 后续改动让界面对不上时重新截一组，不要沿用过期截图。
+- 把截图放进 PR / MR 描述能直接看到的位置：按仓库约定提交到分支后用仓库内图片链接引用，或用项目已有的素材托管 / GitLab 项目上传接口；不要只写本机文件路径，也不要把私人图床链接写进公开仓库。
+- 拿不到真实基线时，在 PR / MR 描述和 `--reply` 里如实说明缺什么、为什么缺，本轮用 `blocked` 或 `progress` 上报，**不要报 `ready`** 说这个 UI 改动已完成。
+- 报 `ready` 前确认 PR 描述里的图片链接能打开、Before / After 都能看到；`--reply` 里说明对比证据放在 PR 的哪一段。
+- 上报时用 `--ui-change` 声明本次改动是否涉及 UI：`--ui-change` 或 `--ui-change true` 表示改了 UI，`--ui-change false` 表示没改。不声明时 Router 会按改动文件路径推断。
+- Router 可能开启 UI 证据门禁（`worker.evidence.ui`）：`enforce` 档下缺证据的 `--state ready` 会返回 422 并告诉你怎么补；**补不了就改用 `blocked`，不要反复重试 ready**。`warn` 档只记日志，不会拦。
+
+截图方法：
+
+1. 优先用仓库自带的启动、预览与截图脚本（看 README、`package.json`、`AGENTS.md`）。
+2. 没有现成脚本时，启动本地开发 / 预览服务，用 Playwright 截图（首次使用先 `npx playwright install chromium`）：
+   ```bash
+   npx playwright screenshot --viewport-size=1440,900 --wait-for-timeout=2000 http://localhost:3000/page before.png
+   ```
+3. **动手前先在未改动状态（起始分支）截 Before**，改完后在同一环境截 After；中途切换过分支就重启 dev server，确认截到的是对应版本的代码。
+4. 截图前确认页面已真正加载完成：白屏、加载中骨架、404 / 500 页面都不算证据。
+
+## 收到追问（Router 投递的新输入）
+
+Router 会把发起人的新消息投递给你，格式是：
+
+```text
+【Router 输入 in_xxxxx】
+用户的追问内容……
+```
+
+处理追问时：
+
+1. 记下 `【Router 输入 ...】` 里的 id。
+2. 回答完（或这一轮告一段落）必须再执行一次 `ra report`，不要只在终端里作答。
+3. 回答内容放进 `--reply`，`--state` 用 `ready`（答完了）或 `progress`（还要继续做）。
+4. 用 `--ack in_xxxxx` 确认已读。
+
+> **Router 只认 `ra report`，看不到你的终端输出。** 在终端里说了但没上报，等于用户什么都没收到；
+> 不上报 `--ack`，同一条追问会被反复投递给你。
+
+## 硬约束
+
+- 不要直接给飞书发消息；需要沉淀文档时用 `ra doc`。
+- 不要修改本工单授权范围之外的模块。
+- 每轮结束前必须上报；不报视为本轮没有交付。
+- **只写 summary 不写 reply 视为交付不完整**：用户只会看到一句摘要，拿不到你的结论。
+- **改了 UI 却没在 PR / MR 描述里给出 Before / After 对比，不能报 `ready`**。

package/dist/spec/index.d.ts

@@ -0,0 +1,35 @@
+import type { Attachment, Ticket } from '@router-agent/core/model.js';
+export interface WorkerPromptInput {
+    ticket: Ticket;
+    mandateScope: string;
+    statePath: string;
+    eventsPath: string;
+    repo: string;
+    /** worktree 的起始分支（base branch）。 */
+    branch?: string;
+    /** worktree 自己的工作分支（语义化命名）。 */
+    workBranch?: string;
+    workdir?: string;
+    /** 发起人随消息发来的原始附件；默认取工单上的 attachments。 */
+    attachments?: Attachment[];
+    /** 状态目录；传入后优先读 `<home>/specs/worker/` 下的覆盖文件。 */
+    home?: string;
+}
+/** 注入给 worker 的完整手册。 */
+export declare function buildWorkerPrompt(input: WorkerPromptInput): string;
+/** 运行时中立的工单契约：Claude CLI / Codex 等非 Orca 运行时使用。 */
+export interface WorkerContractInput {
+    ticketId: string;
+    title: string;
+    scope: string;
+    repo: string;
+    branch?: string;
+    workBranch?: string;
+    workdir?: string;
+    statePath: string;
+    eventsPath: string;
+    attachments?: Attachment[];
+    /** 状态目录；传入后优先读 `<home>/specs/worker/` 下的覆盖文件。 */
+    home?: string;
+}
+export declare function buildNeutralContract(input: WorkerContractInput): string;

package/dist/spec/index.js

@@ -0,0 +1,59 @@
+import { readWorkerSpec } from './reader.js';
+/** 注入给 worker 的完整手册。 */
+export function buildWorkerPrompt(input) {
+    return renderWorkerPrompt(input);
+}
+function renderWorkerPrompt(input) {
+    const template = readWorkerSpec(input.home, 'prompt-mode.md');
+    return render(template, {
+        ticketId: input.ticket.id,
+        title: input.ticket.title,
+        scope: input.mandateScope,
+        statePath: input.statePath,
+        eventsPath: input.eventsPath,
+        repo: input.repo,
+        branch: input.branch ?? input.ticket.branch ?? '(仓库默认分支)',
+        workBranch: input.workBranch ?? `ra/${input.ticket.id}`,
+        workdir: input.workdir ?? '(由 Orca 决定)',
+        attachments: attachmentsSection(input.attachments ?? input.ticket.attachments ?? []),
+    });
+}
+export function buildNeutralContract(input) {
+    return renderNeutralContract(input);
+}
+function renderNeutralContract(input) {
+    const template = readWorkerSpec(input.home, 'contract.md');
+    return render(template, {
+        ticketId: input.ticketId,
+        title: input.title,
+        scope: input.scope,
+        repo: input.repo,
+        branch: input.branch ?? '(仓库默认分支)',
+        workBranch: input.workBranch ?? `ra/${input.ticketId}`,
+        workdir: input.workdir ?? '(由运行时决定)',
+        statePath: input.statePath,
+        eventsPath: input.eventsPath,
+        attachments: attachmentsSection(input.attachments ?? []),
+    });
+}
+/**
+ * 原始附件段：把 Router 落盘的本地路径交给 Worker，让它直接看原图。
+ * 没有附件时返回空字符串，模板里对应位置自然留空。
+ */
+function attachmentsSection(attachments) {
+    if (attachments.length === 0)
+        return '';
+    const lines = attachments.map(item => `- \`${item.path}\`${item.quoted ? '（引用消息里的图片）' : ''}`);
+    return [
+        '## 附件图片（原图）',
+        '',
+        '发起人随消息发来了原始图片，Router 已落盘到本机。请直接用你的读图工具查看原图，',
+        '不要只依赖 Router 的文字转写；图片里的细节以原图为准。',
+        '',
+        ...lines,
+    ].join('\n');
+}
+function render(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_m, key) => vars[key] ?? '');
+}
+//# sourceMappingURL=index.js.map

package/dist/spec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/spec/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAmB5C,wBAAwB;AACxB,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAA;AAClC,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAwB;IAClD,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;IAC7D,OAAO,MAAM,CAAC,QAAQ,EAAE;QACtB,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE;QACzB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK;QACzB,KAAK,EAAE,KAAK,CAAC,YAAY;QACzB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,UAAU;QACzD,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE;QACvD,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,aAAa;QACvC,WAAW,EAAE,kBAAkB,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;KACrF,CAAC,CAAA;AACJ,CAAC;AAkBD,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,OAAO,qBAAqB,CAAC,KAAK,CAAC,CAAA;AACrC,CAAC;AAED,SAAS,qBAAqB,CAAC,KAA0B;IACvD,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAA;IAC1D,OAAO,MAAM,CAAC,QAAQ,EAAE;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,UAAU;QAClC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,MAAM,KAAK,CAAC,QAAQ,EAAE;QACtD,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,UAAU;QACpC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,kBAAkB,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC;KACzD,CAAC,CAAA;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,WAAyB;IACnD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACvC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC7F,OAAO;QACL,aAAa;QACb,EAAE;QACF,6CAA6C;QAC7C,iCAAiC;QACjC,EAAE;QACF,GAAG,KAAK;KACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,SAAS,MAAM,CAAC,QAAgB,EAAE,IAA4B;IAC5D,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,EAAE,EAAE,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;AACjF,CAAC"}