@armadra/agent 0.0.0-stage → 0.3.0

package/dist/bundle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 单文件入口（dist/bundle/ama.cjs）。[B0] 所有。
+ *
+ * esbuild 以本文件为入口打成 CJS：`import.meta.url` 由构建脚本替换为 `__filename` 的
+ * file URL，`__AMA_BUNDLED__` 定义为 true（cli/main.ts 据此不自动运行，改由这里调用）。
+ * CJS 产物里原生 `require` 可用，宿主适配器（`--host`）的 CJS 模块由 host/loader.ts（B5）
+ * 用 `createRequire` 加载，不依赖这里。
+ */
+export {};

package/dist/bundle.js

@@ -0,0 +1,15 @@
+/**
+ * 单文件入口（dist/bundle/ama.cjs）。[B0] 所有。
+ *
+ * esbuild 以本文件为入口打成 CJS：`import.meta.url` 由构建脚本替换为 `__filename` 的
+ * file URL，`__AMA_BUNDLED__` 定义为 true（cli/main.ts 据此不自动运行，改由这里调用）。
+ * CJS 产物里原生 `require` 可用，宿主适配器（`--host`）的 CJS 模块由 host/loader.ts（B5）
+ * 用 `createRequire` 加载，不依赖这里。
+ */
+import { main } from "./cli/main.js";
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`ama: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/cli/args.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 手写参数解析（设计 §11.1 第 2 步、§12.10、§13）。[B5]
+ *
+ * - 支持 `--opt value` 与 `--opt=value`；`--` 之后全部作为提示文本；可重复的参数累加。
+ * - 子命令只在第一个参数是 `auth / sessions / models / providers / doctor / config / init` 时识别，
+ *   其余参数原样交给子命令。
+ * - 互斥：`-p` 与 `--mode rpc`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
+ *   `--trust` 与 `--no-trust`；`--api-key` 需要 `--model`；`--output-format` 需要 `-p`。
+ * - `--resume [id]`：下一个参数形如会话 id（无空白、不以 `-` 开头）才被当作 id；
+ *   否则仍作为提示文本。显式写法 `--resume=<id>`。
+ * - `--provider` 不带 `--model` 不在这里报错，由 bootstrap 第 11 步报（退出码 2）。
+ */
+import { AmaError } from "../errors.js";
+import type { ModelThinkingLevel } from "../ai/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { CodemodeMode, ToolsPreset } from "../config/types.js";
+export declare const SUBCOMMANDS: readonly ["auth", "sessions", "models", "providers", "doctor", "config", "init"];
+export type SubcommandName = (typeof SUBCOMMANDS)[number];
+export type OutputFormat = "text" | "json" | "stream-json";
+export type QuietStartup = "normal" | "header" | "silent";
+export interface ParsedArgs {
+    help: boolean;
+    version: boolean;
+    profile?: string;
+    host?: string;
+    instructions: string[];
+    skillDirs: string[];
+    authFile?: string;
+    permissionMode?: PermissionMode;
+    allow: string[];
+    deny: string[];
+    model?: string;
+    provider?: string;
+    apiKey?: string;
+    thinking?: ModelThinkingLevel;
+    continue: boolean;
+    /** `--resume` 出现即为 true；`resumeId` 为可选 id。 */
+    resume: boolean;
+    resumeId?: string;
+    sessionId?: string;
+    fork?: string;
+    sessionDir?: string;
+    print: boolean;
+    outputFormat?: OutputFormat;
+    /** `--mode rpc`。 */
+    mode?: "rpc";
+    noTui: boolean;
+    tuiMode?: "regular";
+    quietStartup?: QuietStartup;
+    /** `--trust` → true、`--no-trust` → false。 */
+    trust?: boolean;
+    tools?: string[];
+    excludeTools?: string[];
+    /** `--tools-preset`：覆盖 config `tools.preset`。 */
+    toolsPreset?: ToolsPreset;
+    /** `--codemode`：覆盖 config `codemode.mode`。 */
+    codemode?: CodemodeMode;
+    /** `--image <文件>`（可重复，只用于 -p）：随首条提示发送的图片。 */
+    images: string[];
+    /** 位置参数拼成的提示（空格连接）。 */
+    prompt?: string;
+    /** 原始位置参数。 */
+    positionals: string[];
+}
+export type ParseResult = {
+    kind: "run";
+    args: ParsedArgs;
+} | {
+    kind: "subcommand";
+    name: SubcommandName;
+    argv: string[];
+};
+export declare class UsageError extends AmaError {
+    constructor(message: string);
+}
+export declare const HELP_TEXT = "\u7528\u6CD5\uFF1Aama [\u9009\u9879] [\u63D0\u793A]\n      ama <\u5B50\u547D\u4EE4> \u2026\n\n\u6A21\u5F0F\n  \uFF08\u7F3A\u7701\uFF09                     \u7EC8\u7AEF\u754C\u9762\uFF1Bstdin / stdout \u975E TTY \u6216 TERM=dumb \u65F6\u81EA\u52A8\u964D\u7EA7\u4E3A\u884C\u5F0F\n  --no-tui                     \u884C\u5F0F\u754C\u9762\uFF08readline + \u62EC\u53F7\u7C98\u8D34\uFF09\n  -p, --print                  \u975E\u4EA4\u4E92\uFF1A\u6267\u884C\u63D0\u793A\u540E\u9000\u51FA\uFF08\u63D0\u793A\u53EF\u6765\u81EA\u53C2\u6570\u4E0E stdin \u7BA1\u9053\uFF09\n  --output-format <\u683C\u5F0F>       -p \u7684\u8F93\u51FA\uFF1Atext\uFF08\u7F3A\u7701\uFF09| json | stream-json\n  --image <\u6587\u4EF6>               -p \u968F\u63D0\u793A\u53D1\u9001\u56FE\u7247\uFF08\u53EF\u91CD\u590D\uFF1Bpng / jpg / gif / webp\uFF0C\u5355\u5F20 \u2264 5 MB\uFF09\uFF1B\n                               \u4EA4\u4E92\u754C\u9762\u91CC\u5199 @\u56FE\u7247\u8DEF\u5F84 \u6216\u7C98\u8D34\u56FE\u7247\u8DEF\u5F84\n  --mode rpc                   stdio JSONL \u534F\u8BAE\uFF08\u4F9B\u5D4C\u5165\uFF09\n  --tui-mode <\u6A21\u5F0F>            \u663E\u793A\u6A21\u5F0F\uFF0C\u7B2C\u4E00\u671F\u53EA\u6709 regular\uFF08\u4E3B\u5C4F\uFF09\n  --quiet-startup <\u6863>         \u542F\u52A8\u753B\u9762\uFF1Anormal | header | silent\n\n\u6A21\u578B\n  --model <provider/id>        \u6A21\u578B\uFF08\u53EF\u914D\u5408 --provider \u53EA\u5199 id\uFF1B@\u6E20\u9053 \u6307\u5B9A\u6E20\u9053\uFF0C\u5982 packy/kimi-k2.5@messages\uFF09\n  --provider <id>              \u4F9B\u5E94\u5546\uFF08\u5FC5\u987B\u540C\u65F6\u7ED9 --model\uFF09\n  --api-key <key>              \u53EA\u7528\u4E8E\u672C\u6B21\u542F\u52A8\u7684 key\uFF08\u9700\u8981 --model\uFF1B\u4F18\u5148\u7528 ama auth set\uFF09\n  --thinking <\u7EA7\u522B>            off | minimal | low | medium | high | xhigh\n\n\u4F1A\u8BDD\n  -c, --continue               \u7EE7\u7EED\u672C\u76EE\u5F55\u6700\u8FD1\u7684\u4F1A\u8BDD\n  -r, --resume [id]            \u6062\u590D\u4F1A\u8BDD\uFF08\u4EA4\u4E92\u6A21\u5F0F\u65E0 id \u65F6\u5F39\u9009\u62E9\u5668\uFF09\n  --session-id <id>            \u4F7F\u7528\u6307\u5B9A id \u7684\u4F1A\u8BDD\uFF08\u4E0D\u5B58\u5728\u5219\u65B0\u5EFA\uFF09\n  --fork <id>                  \u4ECE\u6307\u5B9A\u4F1A\u8BDD\u5206\u53C9\u51FA\u65B0\u4F1A\u8BDD\n  --session-dir <\u76EE\u5F55>         \u4F1A\u8BDD\u76EE\u5F55\uFF08\u7F3A\u7701 ~/.local/share/ama/sessions\uFF09\n\n\u6743\u9650\u4E0E\u4FE1\u4EFB\n  --permission-mode <\u6A21\u5F0F>     plan | default | auto-edit | full-auto\n  --allow <\u89C4\u5219>               \u8FFD\u52A0\u5141\u8BB8\u89C4\u5219\uFF0C\u53EF\u91CD\u590D\uFF08\u5982 \"bash(git status*)\"\uFF09\n  --deny <\u89C4\u5219>                \u8FFD\u52A0\u62D2\u7EDD\u89C4\u5219\uFF0C\u53EF\u91CD\u590D\uFF08\u5982 \"write(**/.env*)\"\uFF09\n  --trust / --no-trust         \u4FE1\u4EFB / \u4E0D\u4FE1\u4EFB\u5F53\u524D\u9879\u76EE\uFF08\u9879\u76EE\u7EA7 Hook\u3001Skill\u3001\u63D0\u793A\u6A21\u677F\uFF09\n\n\u8D44\u6E90\n  --profile <\u6587\u4EF6>             \u5BBF\u4E3B profile.json\uFF08\u5B57\u6BB5\u7B49\u4EF7\u4E8E\u5BF9\u5E94\u53C2\u6570\uFF0C\u547D\u4EE4\u884C\u4F18\u5148\uFF09\n  --host <\u6A21\u5757>                \u5BBF\u4E3B\u9002\u914D\u5668\u6A21\u5757\uFF08CJS / ESM\uFF09\n  --instructions <\u6587\u4EF6>        \u8FFD\u52A0\u6307\u4EE4\u6587\u4EF6\uFF0C\u53EF\u91CD\u590D\n  --skill-dir <\u76EE\u5F55>           \u8FFD\u52A0 Skill \u76EE\u5F55\uFF0C\u53EF\u91CD\u590D\n  --auth-file <\u6587\u4EF6>           auth.json \u4F4D\u7F6E\uFF08\u7F3A\u7701 ~/.config/ama/auth.json\uFF09\n  --tools <a,b,\u2026>              \u53EA\u542F\u7528\u8FD9\u4E9B\u5DE5\u5177\n  --exclude-tools <a,b,\u2026>      \u7981\u7528\u8FD9\u4E9B\u5DE5\u5177\n  --tools-preset <\u540D>          \u5DE5\u5177\u9884\u8BBE\uFF1Adefault\uFF08\u7F3A\u7701\uFF09| minimal | codemode | coordinator\n  --codemode <\u6A21\u5F0F>            codemode \u8C03\u7528\u65B9\u5F0F\uFF1Aoff | on | only\n\n\u5B50\u547D\u4EE4\n  ama auth set <provider>      \u4ECE stdin \u8BFB\u53D6 key \u5199\u5165 auth.json\uFF080600\uFF09\n  ama auth list                \u5217\u51FA\u5DF2\u4FDD\u5B58 key \u7684\u4F9B\u5E94\u5546\uFF08\u4E0D\u663E\u793A key\uFF09\n  ama auth remove <provider>   \u5220\u9664\u5DF2\u4FDD\u5B58\u7684 key\n  ama sessions list|show|prune \u4F1A\u8BDD\u7BA1\u7406\n  ama models list [--provider <id>]  \u5217\u51FA\u6A21\u578B\uFF08\u542B\u6765\u6E90\u4E0E key \u72B6\u6001\uFF09\n  ama models check <provider/id>     \u53D1\u4E00\u6B21\u6700\u5C0F\u8BF7\u6C42\u68C0\u67E5\u53EF\u7528\u6027\n  ama models discover <provider> [--probe] [--write] [--limit N]\n                               \u4ECE\u4E2D\u8F6C /v1/models \u5217\u51FA\u6A21\u578B\uFF0C\u63A2\u6D4B\u534F\u8BAE\u5E76\u5199\u5165\u914D\u7F6E\n  ama models refresh-catalog   \u5F3A\u5236\u5237\u65B0 models.dev \u6A21\u578B\u5143\u6570\u636E\u7F13\u5B58\n  ama providers add <id> --base-url <url> [--key-env VAR] [--probe] [--channel n=api@url] [--yes]\n                               \u4E00\u952E\u63A5\u5165\uFF1A\u5217\u6A21\u578B\u3001\u8865 models.dev \u5143\u6570\u636E\u3001\u63A2\u6D4B\u6E20\u9053\u3001\u5199\u5165\u914D\u7F6E\n  ama providers list|channels <id>|remove <id>|refresh <id>\n                               \u4F9B\u5E94\u5546 \u2192 \u6E20\u9053 \u2192 \u6A21\u578B\uFF1B\u5220\u9664\uFF1B\u91CD\u62C9\u6A21\u578B\u5217\u8868\n  ama models cache-probe <provider/id> [--tokens N] [--gap-ms MS] [--yes] [--json]\n                               \u5224\u65AD\u7AEF\u70B9\u662F\u5426\u62A5\u544A\u7F13\u5B58\u547D\u4E2D\n  ama doctor                   \u914D\u7F6E\u5C42\u7EA7\u3001\u4FE1\u4EFB\u3001key \u6765\u6E90\u3001Hook\u3001\u7EC8\u7AEF\u80FD\u529B\n  ama config show [--json]     \u751F\u6548\u914D\u7F6E\u4E0E\u6BCF\u9879\u6765\u6E90\u3001\u5C06\u4F7F\u7528\u7684\u6A21\u578B\n  ama config path              \u914D\u7F6E\u76EE\u5F55\u3001\u6570\u636E\u76EE\u5F55\u4E0E\u5404\u6587\u4EF6\u8DEF\u5F84\n  ama config edit              \u7528 $VISUAL / $EDITOR \u6253\u5F00 config.json\n  ama init [--force]           \u5EFA\u914D\u7F6E\u76EE\u5F55\uFF080700\uFF09\u4E0E config.json\u3001config.schema.json\uFF1B\u5DF2\u6709\u7684\u4E0D\u8986\u76D6\n\n\u5176\u5B83\n  -h, --help                   \u8F93\u51FA\u672C\u5E2E\u52A9\n  -v, --version                \u8F93\u51FA\u7248\u672C\n\n\u9000\u51FA\u7801\uFF1A0 \u6B63\u5E38 \u00B7 1 \u8FD0\u884C\u671F\u9519\u8BEF \u00B7 2 \u7528\u6CD5\u9519\u8BEF \u00B7 3 \u914D\u7F6E\u9519\u8BEF \u00B7 4 \u65E0\u53EF\u7528\u6A21\u578B\u6216 key \u00B7\n        5 \u4F1A\u8BDD\u9519\u8BEF \u00B7 6 \u5BBF\u4E3B / Hook \u542F\u52A8\u5931\u8D25 \u00B7 78 \u5BBF\u4E3B API \u7248\u672C\u4E0D\u5339\u914D \u00B7 130 SIGINT \u00B7 143 SIGTERM\n";
+export declare function emptyArgs(): ParsedArgs;
+/** 解析 argv（不含 node 与脚本路径）；用法错误抛 UsageError（退出码 2）。 */
+export declare function parseArgs(argv: readonly string[]): ParseResult;
+/** 子命令内部的小解析器：`--name value` / `--name=value` / 位置参数。 */
+export declare function parseSubArgs(argv: readonly string[], valueOptions: readonly string[], flagOptions?: readonly string[]): {
+    positionals: string[];
+    values: Map<string, string>;
+    flags: Set<string>;
+};

package/dist/cli/args.js

@@ -0,0 +1,408 @@
+/**
+ * 手写参数解析（设计 §11.1 第 2 步、§12.10、§13）。[B5]
+ *
+ * - 支持 `--opt value` 与 `--opt=value`；`--` 之后全部作为提示文本；可重复的参数累加。
+ * - 子命令只在第一个参数是 `auth / sessions / models / providers / doctor / config / init` 时识别，
+ *   其余参数原样交给子命令。
+ * - 互斥：`-p` 与 `--mode rpc`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
+ *   `--trust` 与 `--no-trust`；`--api-key` 需要 `--model`；`--output-format` 需要 `-p`。
+ * - `--resume [id]`：下一个参数形如会话 id（无空白、不以 `-` 开头）才被当作 id；
+ *   否则仍作为提示文本。显式写法 `--resume=<id>`。
+ * - `--provider` 不带 `--model` 不在这里报错，由 bootstrap 第 11 步报（退出码 2）。
+ */
+import { AmaError } from "../errors.js";
+import { CODEMODE_MODES } from "../config/types.js";
+export const SUBCOMMANDS = [
+    "auth",
+    "sessions",
+    "models",
+    "providers",
+    "doctor",
+    "config",
+    "init",
+];
+export class UsageError extends AmaError {
+    constructor(message) {
+        super("invalid_arguments", message, { exitCode: 2 });
+        this.name = "UsageError";
+    }
+}
+const PERMISSION_MODES = ["plan", "default", "auto-edit", "full-auto"];
+const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+const OUTPUT_FORMATS = ["text", "json", "stream-json"];
+const QUIET_LEVELS = ["normal", "header", "silent"];
+/** 帮助与报错按常用顺序列出（校验集合同 TOOLS_PRESETS_STRICT_FIRST）。 */
+const PRESET_CHOICES = ["default", "minimal", "codemode", "coordinator"];
+const SESSION_ID_LIKE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+export const HELP_TEXT = `用法：ama [选项] [提示]
+      ama <子命令> …
+
+模式
+  （缺省）                     终端界面；stdin / stdout 非 TTY 或 TERM=dumb 时自动降级为行式
+  --no-tui                     行式界面（readline + 括号粘贴）
+  -p, --print                  非交互：执行提示后退出（提示可来自参数与 stdin 管道）
+  --output-format <格式>       -p 的输出：text（缺省）| json | stream-json
+  --image <文件>               -p 随提示发送图片（可重复；png / jpg / gif / webp，单张 ≤ 5 MB）；
+                               交互界面里写 @图片路径 或粘贴图片路径
+  --mode rpc                   stdio JSONL 协议（供嵌入）
+  --tui-mode <模式>            显示模式，第一期只有 regular（主屏）
+  --quiet-startup <档>         启动画面：normal | header | silent
+
+模型
+  --model <provider/id>        模型（可配合 --provider 只写 id；@渠道 指定渠道，如 packy/kimi-k2.5@messages）
+  --provider <id>              供应商（必须同时给 --model）
+  --api-key <key>              只用于本次启动的 key（需要 --model；优先用 ama auth set）
+  --thinking <级别>            off | minimal | low | medium | high | xhigh
+
+会话
+  -c, --continue               继续本目录最近的会话
+  -r, --resume [id]            恢复会话（交互模式无 id 时弹选择器）
+  --session-id <id>            使用指定 id 的会话（不存在则新建）
+  --fork <id>                  从指定会话分叉出新会话
+  --session-dir <目录>         会话目录（缺省 ~/.local/share/ama/sessions）
+
+权限与信任
+  --permission-mode <模式>     plan | default | auto-edit | full-auto
+  --allow <规则>               追加允许规则，可重复（如 "bash(git status*)"）
+  --deny <规则>                追加拒绝规则，可重复（如 "write(**/.env*)"）
+  --trust / --no-trust         信任 / 不信任当前项目（项目级 Hook、Skill、提示模板）
+
+资源
+  --profile <文件>             宿主 profile.json（字段等价于对应参数，命令行优先）
+  --host <模块>                宿主适配器模块（CJS / ESM）
+  --instructions <文件>        追加指令文件，可重复
+  --skill-dir <目录>           追加 Skill 目录，可重复
+  --auth-file <文件>           auth.json 位置（缺省 ~/.config/ama/auth.json）
+  --tools <a,b,…>              只启用这些工具
+  --exclude-tools <a,b,…>      禁用这些工具
+  --tools-preset <名>          工具预设：default（缺省）| minimal | codemode | coordinator
+  --codemode <模式>            codemode 调用方式：off | on | only
+
+子命令
+  ama auth set <provider>      从 stdin 读取 key 写入 auth.json（0600）
+  ama auth list                列出已保存 key 的供应商（不显示 key）
+  ama auth remove <provider>   删除已保存的 key
+  ama sessions list|show|prune 会话管理
+  ama models list [--provider <id>]  列出模型（含来源与 key 状态）
+  ama models check <provider/id>     发一次最小请求检查可用性
+  ama models discover <provider> [--probe] [--write] [--limit N]
+                               从中转 /v1/models 列出模型，探测协议并写入配置
+  ama models refresh-catalog   强制刷新 models.dev 模型元数据缓存
+  ama providers add <id> --base-url <url> [--key-env VAR] [--probe] [--channel n=api@url] [--yes]
+                               一键接入：列模型、补 models.dev 元数据、探测渠道、写入配置
+  ama providers list|channels <id>|remove <id>|refresh <id>
+                               供应商 → 渠道 → 模型；删除；重拉模型列表
+  ama models cache-probe <provider/id> [--tokens N] [--gap-ms MS] [--yes] [--json]
+                               判断端点是否报告缓存命中
+  ama doctor                   配置层级、信任、key 来源、Hook、终端能力
+  ama config show [--json]     生效配置与每项来源、将使用的模型
+  ama config path              配置目录、数据目录与各文件路径
+  ama config edit              用 $VISUAL / $EDITOR 打开 config.json
+  ama init [--force]           建配置目录（0700）与 config.json、config.schema.json；已有的不覆盖
+
+其它
+  -h, --help                   输出本帮助
+  -v, --version                输出版本
+
+退出码：0 正常 · 1 运行期错误 · 2 用法错误 · 3 配置错误 · 4 无可用模型或 key ·
+        5 会话错误 · 6 宿主 / Hook 启动失败 · 78 宿主 API 版本不匹配 · 130 SIGINT · 143 SIGTERM
+`;
+const VALUE_OPTIONS = new Set([
+    "profile",
+    "host",
+    "instructions",
+    "skill-dir",
+    "auth-file",
+    "permission-mode",
+    "allow",
+    "deny",
+    "model",
+    "provider",
+    "api-key",
+    "thinking",
+    "session-id",
+    "fork",
+    "session-dir",
+    "output-format",
+    "mode",
+    "tui-mode",
+    "quiet-startup",
+    "tools",
+    "exclude-tools",
+    "tools-preset",
+    "codemode",
+    "image",
+]);
+const FLAG_ALIASES = {
+    "-h": "help",
+    "-v": "version",
+    "-p": "print",
+    "-c": "continue",
+    "-r": "resume",
+};
+function choice(option, value, choices) {
+    if (choices.includes(value))
+        return value;
+    throw new UsageError(`--${option} 的取值应为 ${choices.join(" | ")}（收到 ${value}）`);
+}
+function list(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+export function emptyArgs() {
+    return {
+        help: false,
+        version: false,
+        instructions: [],
+        skillDirs: [],
+        allow: [],
+        deny: [],
+        images: [],
+        continue: false,
+        resume: false,
+        print: false,
+        noTui: false,
+        positionals: [],
+    };
+}
+function applyValue(args, option, value) {
+    if (value === "")
+        throw new UsageError(`--${option} 的值不能为空`);
+    switch (option) {
+        case "profile":
+            args.profile = value;
+            break;
+        case "host":
+            args.host = value;
+            break;
+        case "instructions":
+            args.instructions.push(value);
+            break;
+        case "skill-dir":
+            args.skillDirs.push(value);
+            break;
+        case "auth-file":
+            args.authFile = value;
+            break;
+        case "permission-mode":
+            args.permissionMode = choice(option, value, PERMISSION_MODES);
+            break;
+        case "allow":
+            args.allow.push(value);
+            break;
+        case "deny":
+            args.deny.push(value);
+            break;
+        case "model":
+            args.model = value;
+            break;
+        case "provider":
+            args.provider = value;
+            break;
+        case "api-key":
+            args.apiKey = value;
+            break;
+        case "thinking":
+            args.thinking = choice(option, value, THINKING_LEVELS);
+            break;
+        case "session-id":
+            args.sessionId = value;
+            break;
+        case "fork":
+            args.fork = value;
+            break;
+        case "session-dir":
+            args.sessionDir = value;
+            break;
+        case "output-format":
+            args.outputFormat = choice(option, value, OUTPUT_FORMATS);
+            break;
+        case "mode":
+            args.mode = choice(option, value, ["rpc"]);
+            break;
+        case "tui-mode":
+            if (value === "fullscreen")
+                throw new UsageError("--tui-mode fullscreen 尚未支持（第一期只有 regular）");
+            args.tuiMode = choice(option, value, ["regular"]);
+            break;
+        case "quiet-startup":
+            args.quietStartup = choice(option, value, QUIET_LEVELS);
+            break;
+        case "tools":
+            args.tools = [...(args.tools ?? []), ...list(value)];
+            break;
+        case "exclude-tools":
+            args.excludeTools = [...(args.excludeTools ?? []), ...list(value)];
+            break;
+        case "tools-preset":
+            args.toolsPreset = choice(option, value, PRESET_CHOICES);
+            break;
+        case "codemode":
+            args.codemode = choice(option, value, CODEMODE_MODES);
+            break;
+        case "image":
+            args.images.push(value);
+            break;
+    }
+}
+function applyFlag(args, name) {
+    switch (name) {
+        case "help":
+            args.help = true;
+            return true;
+        case "version":
+            args.version = true;
+            return true;
+        case "print":
+            args.print = true;
+            return true;
+        case "continue":
+            args.continue = true;
+            return true;
+        case "no-tui":
+            args.noTui = true;
+            return true;
+        case "trust":
+        case "no-trust": {
+            const value = name === "trust";
+            if (args.trust !== undefined && args.trust !== value) {
+                throw new UsageError("--trust 与 --no-trust 不能同时使用");
+            }
+            args.trust = value;
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+function validate(args) {
+    if (args.print && args.mode === "rpc")
+        throw new UsageError("-p 与 --mode rpc 不能同时使用");
+    const sessionFlags = [
+        args.continue ? "--continue" : undefined,
+        args.resume ? "--resume" : undefined,
+        args.sessionId !== undefined ? "--session-id" : undefined,
+        args.fork !== undefined ? "--fork" : undefined,
+    ].filter((f) => f !== undefined);
+    if (sessionFlags.length > 1)
+        throw new UsageError(`${sessionFlags.join(" 与 ")} 不能同时使用`);
+    if (args.apiKey !== undefined && args.model === undefined) {
+        throw new UsageError("--api-key 需要同时给出 --model");
+    }
+    if (args.outputFormat !== undefined && !args.print) {
+        throw new UsageError("--output-format 只用于 -p / --print");
+    }
+    if (args.images.length > 0 && !args.print) {
+        throw new UsageError("--image 只用于 -p / --print（交互界面里写 @图片路径）");
+    }
+}
+/** 解析 argv（不含 node 与脚本路径）；用法错误抛 UsageError（退出码 2）。 */
+export function parseArgs(argv) {
+    const first = argv[0];
+    if (first !== undefined && SUBCOMMANDS.includes(first)) {
+        return { kind: "subcommand", name: first, argv: argv.slice(1) };
+    }
+    const args = emptyArgs();
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (token === "--") {
+            args.positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!token.startsWith("-") || token === "-") {
+            args.positionals.push(token);
+            continue;
+        }
+        let name;
+        let inline;
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+            inline = eq === -1 ? undefined : token.slice(eq + 1);
+        }
+        else {
+            const alias = FLAG_ALIASES[token];
+            if (alias === undefined)
+                throw new UsageError(`未知选项：${token}`);
+            name = alias;
+        }
+        if (name === "resume") {
+            args.resume = true;
+            const next = argv[i + 1];
+            if (inline !== undefined) {
+                if (inline === "")
+                    throw new UsageError("--resume= 的 id 不能为空");
+                args.resumeId = inline;
+            }
+            else if (next !== undefined && SESSION_ID_LIKE.test(next)) {
+                args.resumeId = next;
+                i++;
+            }
+            continue;
+        }
+        if (VALUE_OPTIONS.has(name)) {
+            let value = inline;
+            if (value === undefined) {
+                value = argv[i + 1];
+                if (value === undefined)
+                    throw new UsageError(`--${name} 需要一个值`);
+                i++;
+            }
+            applyValue(args, name, value);
+            continue;
+        }
+        if (inline !== undefined)
+            throw new UsageError(`--${name} 不接受值`);
+        if (!applyFlag(args, name))
+            throw new UsageError(`未知选项：${token}`);
+    }
+    if (args.positionals.length > 0)
+        args.prompt = args.positionals.join(" ");
+    if (!args.help && !args.version)
+        validate(args);
+    return { kind: "run", args };
+}
+/** 子命令内部的小解析器：`--name value` / `--name=value` / 位置参数。 */
+export function parseSubArgs(argv, valueOptions, flagOptions = []) {
+    const positionals = [];
+    const values = new Map();
+    const flags = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (!token.startsWith("--")) {
+            if (token === "-h")
+                flags.add("help");
+            else
+                positionals.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+        if (name === "help") {
+            flags.add("help");
+            continue;
+        }
+        if (valueOptions.includes(name)) {
+            const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+            if (value === undefined || value === "")
+                throw new UsageError(`--${name} 需要一个值`);
+            values.set(name, value);
+        }
+        else if (flagOptions.includes(name) && eq === -1) {
+            flags.add(name);
+        }
+        else {
+            throw new UsageError(`未知选项：${token}`);
+        }
+    }
+    return { positionals, values, flags };
+}

package/dist/cli/bootstrap.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 启动序列编排（设计 §11.1 第 3–16 步、§11.2）。[B5]
+ *
+ * `bootstrap(args, deps, io)` 跑第 3–14 步并返回 Runtime（SDK `createRuntime()` 复用）；
+ * `runCli(argv, deps, io)` 在其前后加上第 2 步（参数）与第 15–16 步（模式分派），返回退出码。
+ * 每步失败抛 `StartupError{exitCode}`；具体实现经 RuntimeDeps 注入（见 cli/deps.ts）。
+ */
+import { type ParsedArgs } from "./args.js";
+import type { CliIo, RuntimeDeps } from "./deps.js";
+import type { Runtime } from "./runtime.js";
+/** §11.1 第 3–14 步。 */
+export declare function bootstrap(argsIn: ParsedArgs, deps: RuntimeDeps, io: CliIo): Promise<Runtime>;
+/** 非交互模式接管 stdout：console.log / info / debug 改写到 stderr；返回还原函数。 */
+export declare function takeOverStdout(): () => void;
+export declare function isTerminalInitError(error: unknown): boolean;
+/** 第 2–16 步：参数 → bootstrap → 模式；返回退出码（不含子命令）。 */
+export declare function runCli(argv: readonly string[], deps: RuntimeDeps | undefined, io: CliIo): Promise<number>;
+export declare function reportError(error: unknown, io: Pick<CliIo, "stderr">, fallback?: number): number;