@armadra/agent 0.4.0 → 0.5.0

package/dist/cli/compose.js

@@ -25,11 +25,16 @@
 import { formatModelRef } from "../ai/providers/channels.js";
 import { PermissionPipeline } from "../permissions/pipeline.js";
 import { BUILTIN_DENY_RULES, parseRule } from "../permissions/rules.js";
+import { withBuiltinSkills } from "../skills/builtin.js";
 import { discoverSkills, skillSources } from "../skills/discover.js";
 import { discoverPromptTemplates, promptSources } from "../skills/templates.js";
 import { applyCodemodeMode } from "../codemode/modes.js";
-import { detectSandboxCapability } from "../codemode/capability.js";
+import { sandboxCapabilityFor } from "../codemode/capability.js";
 import { codemodeToolFactory } from "../codemode/tool.js";
+import { configureOsSandbox } from "../sandbox/detect.js";
+import { resolveBashSandbox } from "../sandbox/bash.js";
+import { join } from "node:path";
+import { AUTH_FILE } from "../config/paths.js";
 import { PresetToolRegistry, resolvePreset } from "../tools/presets.js";
 import { builtinTools } from "../tools/registry.js";
 import { takeCodemodeNotice } from "./codemode-notice.js";
@@ -37,6 +42,7 @@ import { buildProviderRegistry } from "./compose-providers.js";
 import { composeSession, emptyComposeState, } from "./compose-session.js";
 import { createSessionStore } from "./compose-store.js";
 import { defaultSendUser } from "./startup-steps.js";
+import { imageFitOptionsFor } from "../modes/image-input.js";
 /** 缺省工具工厂：codemode（生效模式为 off 时不注册；缺省跟随预设，见 tools/presets.ts）。 */
 export const DEFAULT_TOOL_FACTORIES = [codemodeToolFactory()];
 export function lazyMode(load) {
@@ -58,17 +64,32 @@ export const DEFAULT_MODES = {
  */
 export function createTools(input, options, state) {
     const registry = new PresetToolRegistry();
-    const capability = options.sandboxCapability ?? detectSandboxCapability();
+    // 记下 sandbox.enabled：拿不到配置的只读调用方（状态栏）与这里得到同一结论。
+    const osStatus = configureOsSandbox(input.config.sandbox?.enabled);
+    // [S2] bash 沙箱：工具与权限管线用同一份设定（tools.create 先于 permissions.create）
+    const bashSandbox = options.bashSandbox ??
+        resolveBashSandbox(input.config.sandbox, {
+            status: osStatus,
+            ...(input.paths === undefined ? {} : { hidden: [join(input.paths.configDir, AUTH_FILE)] }),
+        });
+    state.bashSandbox = bashSandbox;
+    const capability = options.sandboxCapability ?? sandboxCapabilityFor(input.config);
     const factories = options.toolFactories ??
         (options.sandboxCapability !== undefined
             ? [codemodeToolFactory({ capability })]
             : DEFAULT_TOOL_FACTORIES);
-    const bash = input.config.tools?.bashTimeoutMs !== undefined
-        ? { defaultTimeoutMs: input.config.tools.bashTimeoutMs }
-        : {};
+    const bash = {
+        ...(input.config.tools?.bashTimeoutMs !== undefined
+            ? { defaultTimeoutMs: input.config.tools.bashTimeoutMs }
+            : {}),
+        ...(bashSandbox.active ? { sandbox: bashSandbox } : {}),
+    };
     const builtins = builtinTools({
         bash,
-        read: { supportsImages: (ctx) => modelAcceptsImages(state, ctx.model) },
+        read: {
+            supportsImages: (ctx) => modelAcceptsImages(state, ctx.model),
+            imageOptions: (ctx) => imageFitOptionsFor(state.providers, ctx.model, input.config.images),
+        },
     });
     const ctx = {
         ...input,
@@ -192,6 +213,7 @@ export function createRuntimeDeps(options = {}) {
                 ...(input.autoSafeCommands !== undefined
                     ? { autoSafeCommands: input.autoSafeCommands }
                     : {}),
+                ...(state.bashSandbox?.active === true ? { bashSandbox: state.bashSandbox } : {}),
             }),
         },
         resources: {
@@ -201,6 +223,11 @@ export function createRuntimeDeps(options = {}) {
                     configDir: input.configDir,
                     cliDirs: input.extraSkillDirs,
                 }), { trusted: input.trusted });
+                if (input.dataDir !== undefined) {
+                    const builtin = await withBuiltinSkills(skills.skills, input.dataDir);
+                    skills.skills = builtin.skills;
+                    skills.warnings.push(...builtin.warnings);
+                }
                 const prompts = await discoverPromptTemplates(promptSources({
                     cwd: input.cwd,
                     configDir: input.configDir,

package/dist/cli/deps.d.ts

@@ -65,6 +65,8 @@ export interface ResourceDiscoveryInput {
     /** 按 §5.3 顺序：`--skill-dir` → profile.skillDirs → config.skills.dirs。 */
     extraSkillDirs: readonly string[];
     promptDirs: readonly string[];
+    /** 数据目录：内置 Skill 的正文写在 `<dataDir>/builtin/`；缺省不加内置 Skill。 */
+    dataDir?: string;
 }
 export interface ResourceDiscoveryResult {
     skills: LoadedResources["skills"];
@@ -118,10 +120,14 @@ export interface SessionAssembly {
 export interface SessionOverrides {
     /** 一次运行（prompt）的回合上限。 */
     maxTurns?: number;
+    /** [W5-C0] `--max-cost`：并入会话 `limits.maxCostUsd`（W5-H2 实现）。 */
+    maxCostUsd?: number;
     /** `--system-prompt`：追加进 rules 节，或替换 preamble。 */
     systemPrompt?: SystemPromptOverride;
     /** `--no-session`：`/new` 等切换出的新会话也只在内存里。 */
     noSession?: boolean;
+    /** [W5-G] `--agent-dir`（可重复）与 profile `agentDirs`，按此顺序：子 Agent 定义目录。 */
+    agentDirs?: string[];
 }
 export interface SystemPromptOverride {
     text: string;

package/dist/cli/exit-codes.d.ts

@@ -18,6 +18,16 @@ export declare const ExitCode: {
     readonly HostOrHook: 6;
     /** `-p` 运行中有工具调用被拒（无人审批、deny 规则、plan 等），要求的动作没有完成。 */
     readonly ToolDenied: 7;
+    /**
+     * [W5-C0] `-p` 到达 `--max-turns` / `--max-cost` / `limits.*` 上限（`limit_reached`，W5-H2）。
+     * 设计稿写的是 7，但 7 已发布为 ToolDenied，这里用 8。
+     */
+    readonly LimitReached: 8;
+    /**
+     * [W5-H2] `-p` 在 plan 模式产出计划、已落盘但没有人审批（`plan.unattended: stop`，缺省）：
+     * 计划还没执行。不复用 7（7 已发布为「工具调用被拒」）。
+     */
+    readonly PlanPending: 9;
     /** HOST_API_VERSION 不匹配。 */
     readonly HostVersion: 78;
     /** SIGINT 退出（两次 Ctrl+C）。 */

package/dist/cli/exit-codes.js

@@ -18,6 +18,16 @@ export const ExitCode = {
     HostOrHook: 6,
     /** `-p` 运行中有工具调用被拒（无人审批、deny 规则、plan 等），要求的动作没有完成。 */
     ToolDenied: 7,
+    /**
+     * [W5-C0] `-p` 到达 `--max-turns` / `--max-cost` / `limits.*` 上限（`limit_reached`，W5-H2）。
+     * 设计稿写的是 7，但 7 已发布为 ToolDenied，这里用 8。
+     */
+    LimitReached: 8,
+    /**
+     * [W5-H2] `-p` 在 plan 模式产出计划、已落盘但没有人审批（`plan.unattended: stop`，缺省）：
+     * 计划还没执行。不复用 7（7 已发布为「工具调用被拒」）。
+     */
+    PlanPending: 9,
     /** HOST_API_VERSION 不匹配。 */
     HostVersion: 78,
     /** SIGINT 退出（两次 Ctrl+C）。 */
@@ -34,6 +44,8 @@ export const EXIT_CODE_DESCRIPTIONS = {
     5: "会话不存在 / 损坏 / cwd 不匹配",
     6: "宿主 / Hook 加载或启动失败",
     7: "-p 运行中有工具调用被拒（没有人审批）",
+    8: "-p 到达预算上限（--max-turns / --max-cost / limits）",
+    9: "-p 产出的计划已落盘、待审批（未执行）",
     78: "HOST_API_VERSION 不匹配",
     130: "SIGINT 退出（两次 Ctrl+C）",
     143: "SIGTERM",

package/dist/cli/help-text.d.ts

@@ -0,0 +1,4 @@
+/**
+ * `ama --help` 的文本（从 args.ts 搬出，args.ts 再导出）。[W5-C0]
+ */
+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\u3002\u63D0\u793A = \u53C2\u6570 + stdin \u7BA1\u9053\u5185\u5BB9\uFF1B\u6709\u63D0\u793A\u53C2\u6570\u65F6\n                               \u53EA\u7B49\u7BA1\u9053\u9996\u5B57\u8282 2 s\uFF08AMA_STDIN_WAIT_MS\uFF09\uFF0C\u6CA1\u6536\u5230\u5C31\u5FFD\u7565\u5E76\u63D0\u793A\uFF1B\n                               \u672B\u5C3E\u52A0 - \u5219\u4E00\u76F4\u7B49\u5230 EOF\uFF08\u5982 npm test | ama -p \u627E\u539F\u56E0 -\uFF09\n  --no-stdin                   -p \u4E0D\u8BFB stdin\uFF08\u7236\u8FDB\u7A0B\u7559\u7740\u7BA1\u9053\u3001\u53C8\u4E0D\u60F3\u7B49 2 s \u65F6\uFF09\n  --output-format <\u683C\u5F0F>       -p \u7684\u8F93\u51FA\uFF1Atext\uFF08\u7F3A\u7701\uFF09| json | stream-json\n  --max-turns <N>              -p \u6700\u591A\u8DD1 N \u8F6E\uFF08\u4E00\u6B21\u6A21\u578B\u8BF7\u6C42\u52A0\u5176\u5DE5\u5177\u6267\u884C\u7B97\u4E00\u8F6E\uFF09\uFF1B\u5230\u8FBE\u4E0A\u9650\u4ECD\u6709\n                               \u672A\u5B8C\u6210\u7684\u5DE5\u5177\u8C03\u7528\u65F6\u63D0\u524D\u7ED3\u675F\uFF0C\u9000\u51FA\u7801 8\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  --mode acp                   ACP \u670D\u52A1\u7AEF\uFF08\u4F9B Zed / JetBrains / Armadra \u9A71\u52A8\uFF09\n  --max-cost <USD>             \u4E00\u6B21\u8FD0\u884C\u7684\u7F8E\u5143\u4E0A\u9650\uFF08\u6309\u76EE\u5F55\u4EF7\u4F30\u7B97\uFF09\uFF1B\u5230\u9650\u7ED3\u675F\u8FD0\u884C\uFF0C-p \u9000\u51FA\u7801 8\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  --no-session                 \u4F1A\u8BDD\u53EA\u5728\u5185\u5B58\u91CC\uFF0C\u4E0D\u5199\u4F1A\u8BDD\u6587\u4EF6\uFF08\u4E4B\u540E\u65E0\u6CD5 --resume\uFF09\n  --from <id>[#\u7F16\u53F7]           \u7528\u65E7\u4F1A\u8BDD\u7684\u4E00\u6761\u7528\u6237\u6D88\u606F\u4F5C\u63D0\u793A\uFF08\u7F3A\u7701\u6700\u540E\u4E00\u6761\uFF1B-p \u65F6\u8FDE\u56FE\u7247\u4E00\u8D77\uFF1B\n                               \u7F16\u53F7\u89C1 ama sessions show\uFF09\n\n\u6743\u9650\u4E0E\u4FE1\u4EFB\n  --permission-mode <\u6A21\u5F0F>     default | auto-edit | plan | auto | full-auto | allowlist\n                               \uFF08auto \u7531 ama \u5224\u65AD\u6BCF\u4E00\u6B65\uFF1Ballowlist \u53EA\u653E\u884C allow \u89C4\u5219\u547D\u4E2D\u7684\uFF0C\u9002\u5408 CI\uFF09\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  --system-prompt <\u6587\u672C|@\u6587\u4EF6> \u8FFD\u52A0\u7CFB\u7EDF\u63D0\u793A\uFF1A\u7F3A\u7701\u4F5C\u4E3A\u6700\u540E\u4E00\u6761\u89C4\u5219\u8FFD\u52A0\uFF08\u5DE5\u5177\u8868\u7B49\u524D\u7F00\u4E0D\u53D8\uFF0C\u5229\u4E8E\u7F13\u5B58\uFF09\n  --system-prompt-mode <\u65B9\u5F0F>  append\uFF08\u7F3A\u7701\uFF09| replace\uFF08\u66FF\u6362\u5F00\u5934\u7684\u89D2\u8272\u8BF4\u660E\uFF0C\u5DE5\u5177\u4E0E\u9879\u76EE\u4E0A\u4E0B\u6587\u4FDD\u7559\uFF09\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  --agent-dir <\u76EE\u5F55>           \u8FFD\u52A0\u5B50 Agent \u5B9A\u4E49\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-only | coordinator\n                               \uFF08codemode \u662F codemode-only \u7684\u65E7\u540D\uFF0C\u4ECD\u53EF\u7528\uFF09\n  --codemode <\u6A21\u5F0F>            codemode \u8C03\u7528\u65B9\u5F0F\uFF1Aoff | on | only\uFF08\u7F3A\u7701\u968F\u9884\u8BBE\uFF09\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 sessions search <\u5173\u952E\u8BCD|/\u6B63\u5219/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]\n                               \u8DE8\u4F1A\u8BDD\u5168\u6587\u68C0\u7D22\n  ama sessions export <id> [--format md|json|jsonl] [--output <\u6587\u4EF6>] [--branch leaf|all]\n                               \u5BFC\u51FA\u4F1A\u8BDD\uFF08\u5DF2\u8131\u654F\uFF09\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 [--provider <id>]  \u8054\u7F51\u5237\u65B0 models.dev \u5143\u6570\u636E\u5230\u6570\u636E\u76EE\u5F55\uFF08\u542F\u52A8\u4E0D\u8054\u7F51\uFF1B\n                               \u65E7\u540D refresh-catalog\uFF09\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  ama stats [--since 7d] [--by day|week|month|provider|channel|model|project] [--all] [--json]\n                               \u8DE8\u4F1A\u8BDD\u7EDF\u8BA1\uFF1A\u8BF7\u6C42\u3001token\u3001\u7F13\u5B58\u547D\u4E2D\u7387\u3001\u8D39\u7528\u3001\u5DE5\u5177\u8C03\u7528\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 7 -p \u6709\u5DE5\u5177\u8C03\u7528\u88AB\u62D2\uFF08\u65E0\u4EBA\u5BA1\u6279\uFF1B\u7528\n        --permission-mode auto-edit|auto \u6216 --allow \u653E\u884C\uFF09\u00B7 8 -p \u5230\u8FBE\u9884\u7B97\u4E0A\u9650 \u00B7\n        9 -p \u7684\u8BA1\u5212\u5DF2\u843D\u76D8\u5F85\u5BA1\u6279\uFF08plan.unattended: approve \u5219\u81EA\u52A8\u6279\u51C6\u6267\u884C\uFF09\u00B7\n        78 \u5BBF\u4E3B API \u7248\u672C\u4E0D\u5339\u914D \u00B7\n        130 SIGINT \u00B7 143 SIGTERM\n";

package/dist/cli/help-text.js

@@ -0,0 +1,102 @@
+/**
+ * `ama --help` 的文本（从 args.ts 搬出，args.ts 再导出）。[W5-C0]
+ */
+export const HELP_TEXT = `用法：ama [选项] [提示]
+      ama <子命令> …
+
+模式
+  （缺省）                     终端界面；stdin / stdout 非 TTY 或 TERM=dumb 时自动降级为行式
+  --no-tui                     行式界面（readline + 括号粘贴）
+  -p, --print                  非交互：执行提示后退出。提示 = 参数 + stdin 管道内容；有提示参数时
+                               只等管道首字节 2 s（AMA_STDIN_WAIT_MS），没收到就忽略并提示；
+                               末尾加 - 则一直等到 EOF（如 npm test | ama -p 找原因 -）
+  --no-stdin                   -p 不读 stdin（父进程留着管道、又不想等 2 s 时）
+  --output-format <格式>       -p 的输出：text（缺省）| json | stream-json
+  --max-turns <N>              -p 最多跑 N 轮（一次模型请求加其工具执行算一轮）；到达上限仍有
+                               未完成的工具调用时提前结束，退出码 8
+  --image <文件>               -p 随提示发送图片（可重复；png / jpg / gif / webp，单张 ≤ 5 MB）；
+                               交互界面里写 @图片路径 或粘贴图片路径
+  --mode rpc                   stdio JSONL 协议（供嵌入）
+  --mode acp                   ACP 服务端（供 Zed / JetBrains / Armadra 驱动）
+  --max-cost <USD>             一次运行的美元上限（按目录价估算）；到限结束运行，-p 退出码 8
+  --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）
+  --no-session                 会话只在内存里，不写会话文件（之后无法 --resume）
+  --from <id>[#编号]           用旧会话的一条用户消息作提示（缺省最后一条；-p 时连图片一起；
+                               编号见 ama sessions show）
+
+权限与信任
+  --permission-mode <模式>     default | auto-edit | plan | auto | full-auto | allowlist
+                               （auto 由 ama 判断每一步；allowlist 只放行 allow 规则命中的，适合 CI）
+  --allow <规则>               追加允许规则，可重复（如 "bash(git status*)"）
+  --deny <规则>                追加拒绝规则，可重复（如 "write(**/.env*)"）
+  --trust / --no-trust         信任 / 不信任当前项目（项目级 Hook、Skill、提示模板）
+
+资源
+  --system-prompt <文本|@文件> 追加系统提示：缺省作为最后一条规则追加（工具表等前缀不变，利于缓存）
+  --system-prompt-mode <方式>  append（缺省）| replace（替换开头的角色说明，工具与项目上下文保留）
+  --profile <文件>             宿主 profile.json（字段等价于对应参数，命令行优先）
+  --host <模块>                宿主适配器模块（CJS / ESM）
+  --instructions <文件>        追加指令文件，可重复
+  --skill-dir <目录>           追加 Skill 目录，可重复
+  --agent-dir <目录>           追加子 Agent 定义目录，可重复
+  --auth-file <文件>           auth.json 位置（缺省 ~/.config/ama/auth.json）
+  --tools <a,b,…>              只启用这些工具
+  --exclude-tools <a,b,…>      禁用这些工具
+  --tools-preset <名>          工具预设：default（缺省）| minimal | codemode-only | coordinator
+                               （codemode 是 codemode-only 的旧名，仍可用）
+  --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 sessions search <关键词|/正则/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]
+                               跨会话全文检索
+  ama sessions export <id> [--format md|json|jsonl] [--output <文件>] [--branch leaf|all]
+                               导出会话（已脱敏）
+  ama models list [--provider <id>]  列出模型（含来源与 key 状态）
+  ama models check <provider/id>     发一次最小请求检查可用性
+  ama models discover <provider> [--probe] [--write] [--limit N]
+                               从中转 /v1/models 列出模型，探测协议并写入配置
+  ama models refresh [--provider <id>]  联网刷新 models.dev 元数据到数据目录（启动不联网；
+                               旧名 refresh-catalog）
+  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；已有的不覆盖
+  ama stats [--since 7d] [--by day|week|month|provider|channel|model|project] [--all] [--json]
+                               跨会话统计：请求、token、缓存命中率、费用、工具调用
+
+其它
+  -h, --help                   输出本帮助
+  -v, --version                输出版本
+
+退出码：0 正常 · 1 运行期错误 · 2 用法错误 · 3 配置错误 · 4 无可用模型或 key ·
+        5 会话错误 · 6 宿主 / Hook 启动失败 · 7 -p 有工具调用被拒（无人审批；用
+        --permission-mode auto-edit|auto 或 --allow 放行）· 8 -p 到达预算上限 ·
+        9 -p 的计划已落盘待审批（plan.unattended: approve 则自动批准执行）·
+        78 宿主 API 版本不匹配 ·
+        130 SIGINT · 143 SIGTERM
+`;

package/dist/cli/startup-screen.js

@@ -10,6 +10,7 @@
  * 交互模式（终端界面视觉设计 v1 §3.1）用结构化的 `startupInfo()` 自己排版（框 / 无框两态）；
  * `buildStartupScreen` 的纯文本行保留给 line 模式与测试。
  */
+import { isBuiltinSkill } from "../skills/builtin.js";
 import { basename } from "node:path";
 import { formatModelRef } from "../ai/providers/channels.js";
 import { effectiveCodemodeMode } from "../tools/presets.js";
@@ -45,8 +46,9 @@ export function buildStartupScreen(runtime, level = startupScreenLevel(runtime))
     if (resources.contextFiles.length > 0) {
         lines.push(`上下文：${resources.contextFiles.map((f) => f.path).join(", ")}`);
     }
-    if (resources.skills.length > 0) {
-        lines.push(`Skill：${resources.skills.map((s) => s.name).join(", ")}`);
+    const skills = resources.skills.filter((s) => !isBuiltinSkill(s));
+    if (skills.length > 0) {
+        lines.push(`Skill：${skills.map((s) => s.name).join(", ")}`);
     }
     if (resources.prompts.length > 0) {
         lines.push(`提示模板：${resources.prompts.map((p) => `/${p.name}`).join(" ")}`);
@@ -92,7 +94,7 @@ export function startupInfo(runtime, home) {
         preset: runtime.config.tools?.preset ?? "default",
         codemode: effectiveCodemodeMode(runtime.config),
         contextFiles: resources.contextFiles.map((f) => basename(f.path)),
-        skills: resources.skills.length,
+        skills: resources.skills.filter((s) => !isBuiltinSkill(s)).length,
         prompts: resources.prompts.length,
         hooks: runtime.hooks.list().length,
         warnings: runtime.warnings.length,

package/dist/cli/startup-steps.js

@@ -45,7 +45,9 @@ export function toStartupError(error, exitCode, label) {
 }
 /** 第 4 步。 */
 export function decideMode(args, io) {
-    if (args.mode === "rpc")
+    // [W5-EG] --mode acp 与 rpc 同一装配（宿主看到的 mode 也是 rpc）；ACP 服务端由调用方
+    // （runCli 或 SDK 自己的 runAcpMode）接在 Runtime 上
+    if (args.mode === "rpc" || args.mode === "acp")
         return "rpc";
     if (args.print)
         return "print";
@@ -66,6 +68,10 @@ export function applyProfile(args, profile) {
         merged.trust = true;
     merged.instructions = [...profile.instructions, ...args.instructions];
     merged.skillDirs = [...args.skillDirs, ...profile.skillDirs];
+    // [W5-C0] 子 Agent 目录：--agent-dir 在前、profile agentDirs 在后（W5-G 接入发现）
+    const agentDirs = [...(args.agentDirs ?? []), ...(profile.agentDirs ?? [])];
+    if (agentDirs.length > 0)
+        merged.agentDirs = agentDirs;
     return merged;
 }
 export function sessionRequestOf(args) {

package/dist/cli/subcommands/config.d.ts

@@ -63,7 +63,10 @@ export interface CodemodeDescription {
     /** 生效模式不是 off 但 codemode 工具不可用（requireStrict）时的说明。 */
     unavailable?: string;
 }
-/** codemode 生效模式与原因（跟随预设时写明预设与运行时 Node 是否隔离网络）。 */
+/**
+ * codemode 生效模式与原因（跟随预设时写明预设与网络由谁隔离）。传 `nodeVersion` 是假设性计算（不探测
+ * 操作系统沙箱）；不传按配置的 `sandbox.enabled` 用运行时能力。
+ */
 export declare function describeCodemode(config: AmaConfig, nodeVersion?: string): CodemodeDescription;
 export declare function runConfig(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "providers"> | undefined): Promise<number>;
 export {};

package/dist/cli/subcommands/config.js

@@ -23,7 +23,7 @@ import { modelsDevCachePath } from "../../ai/providers/models-dev-cache.js";
 import { initConfigDir } from "../../config/init.js";
 import { CONFIG_SCHEMA_FILE } from "../../config/json-schema.js";
 import { CODEMODE_MODES, TOOLS_PRESET_ALIASES, TOOLS_PRESET_INPUTS, canonicalPreset, } from "../../config/types.js";
-import { codemodeAvailability, detectSandboxCapability } from "../../codemode/capability.js";
+import { codemodeAvailability, detectSandboxCapability, sandboxCapabilityFor, } from "../../codemode/capability.js";
 import { baseUrlEnvOf } from "../../ai/providers/registry.js";
 import { classifyKeyValue } from "../../config/auth-file.js";
 import { CODEMODE_TOOL, resolveCodemodeMode, resolvePreset } from "../../tools/presets.js";
@@ -32,6 +32,8 @@ import { parseSubArgs, UsageError } from "../args.js";
 import { noModelGuidance, pickDefaultModel } from "../default-model.js";
 import { ExitCode } from "../exit-codes.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
+import { osSandboxStatus } from "../../sandbox/detect.js";
+import { resolveBashSandbox } from "../../sandbox/bash.js";
 export const CONFIG_USAGE = `用法：ama config show [--json] [--profile <文件>] [--auth-file <文件>]
                         [--tools-preset <名>] [--codemode off|on|only]
       ama config path    配置目录、数据目录与各文件路径
@@ -234,13 +236,18 @@ export function sourcesOf(effective, layers) {
     }
     return sources;
 }
-/** codemode 生效模式与原因（跟随预设时写明预设与运行时 Node 是否隔离网络）。 */
+/**
+ * codemode 生效模式与原因（跟随预设时写明预设与网络由谁隔离）。传 `nodeVersion` 是假设性计算（不探测
+ * 操作系统沙箱）；不传按配置的 `sandbox.enabled` 用运行时能力。
+ */
 export function describeCodemode(config, nodeVersion) {
-    const capability = detectSandboxCapability(nodeVersion);
+    const capability = nodeVersion === undefined ? sandboxCapabilityFor(config) : detectSandboxCapability(nodeVersion);
     const resolved = resolveCodemodeMode(config, capability.strict);
-    const sandbox = capability.strict
+    const sandbox = capability.nodeMajor >= 25
         ? `Node ${capability.nodeMajor} 网络已隔离`
-        : `Node ${capability.nodeMajor} < 25 网络未隔离`;
+        : capability.strict
+            ? `Node ${capability.nodeMajor} 网络由操作系统沙箱 ${capability.os.kind} 隔离`
+            : `Node ${capability.nodeMajor} < 25 网络未隔离`;
     const reason = resolved.source === "config"
         ? `codemode.mode 显式设置（${sandbox}）`
         : `跟随预设 ${resolved.preset}（${sandbox}）`;
@@ -309,6 +316,9 @@ export async function runConfig(argv, io, deps) {
     const model = await describeModel(config, registry);
     const providers = describeProviders(config, registry);
     const codemode = describeCodemode(config);
+    const bashSandbox = resolveBashSandbox(config.sandbox, {
+        status: osSandboxStatus(config.sandbox?.enabled ?? "auto"),
+    });
     const builtin = new Set(builtinTools().map((tool) => tool.name));
     if (codemode.mode !== "off" && codemode.unavailable === undefined)
         builtin.add(CODEMODE_TOOL);
@@ -337,7 +347,7 @@ export async function runConfig(argv, io, deps) {
             value: path.endsWith(".apiKey") ? display(path, value) : value,
             source,
         }));
-        io.stdout(`${JSON.stringify({ model, providers, tools: preset.builtin, preset: preset.preset, codemode, entries, layers: layers.map((l) => ({ name: l.name, file: l.label })), notes, warnings }, null, 2)}\n`);
+        io.stdout(`${JSON.stringify({ model, providers, tools: preset.builtin, preset: preset.preset, codemode, bashSandbox: { active: bashSandbox.active, detail: bashSandbox.detail }, entries, layers: layers.map((l) => ({ name: l.name, file: l.label })), notes, warnings }, null, 2)}\n`);
         return ExitCode.Ok;
     }
     const lines = ["生效配置（来源：default 内置 ← user ← profile ← project 只能收紧 ← cli）"];
@@ -355,6 +365,7 @@ export async function runConfig(argv, io, deps) {
     lines.push(`codemode：${codemode.mode}  ${codemode.reason}`);
     if (codemode.unavailable !== undefined)
         lines.push(`  ${codemode.unavailable}`);
+    lines.push(`bash 沙箱：${bashSandbox.detail}`);
     for (const note of notes)
         lines.push(`提示：${note}`);
     for (const warning of [...warnings, ...preset.warnings])

package/dist/cli/subcommands/doctor.js

@@ -7,6 +7,9 @@
  * [W3-B12] baseUrl 来自 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` 时在 key 行后标出变量与地址。
  */
 import { existsSync } from "node:fs";
+import { blobUsage, fileHistoryDir } from "../../checkpoints/blobs.js";
+import { shadowUsage } from "../../checkpoints/shadow-git.js";
+import { formatBytes } from "../../checkpoints/gc.js";
 import { baseUrlEnvOf } from "../../ai/providers/registry.js";
 import { classifyKeyValue, isModeTooOpen, fileMode, readAuthFile } from "../../config/auth-file.js";
 import { findContextFiles } from "../../config/context-files.js";
@@ -15,6 +18,8 @@ import { mergeProjectAndCli } from "../../config/merge.js";
 import { CONFIG_FILE, HOOKS_FILE, projectFile, userFile } from "../../config/paths.js";
 import { findTrustEntry, readTrustFile, trustGatedResources } from "../../config/trust.js";
 import { loadHookConfigs } from "../../hooks/config.js";
+import { osSandboxStatus } from "../../sandbox/detect.js";
+import { resolveBashSandbox } from "../../sandbox/bash.js";
 import { AMA_VERSION } from "../../version.js";
 import { parseSubArgs } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
@@ -190,6 +195,18 @@ function proxySection(report, io) {
     for (const line of describeProxy(inspectProxy(io.env)))
         report.item(line);
 }
+/** 检查点备份占用（docs/rewind-plan.md §1.4）。 */
+async function fileHistoryLine(report, dataDir) {
+    try {
+        const usage = await blobUsage(dataDir);
+        const shadow = await shadowUsage(dataDir);
+        const shadowText = shadow.repos === 0 ? "" : `；影子仓库 ${shadow.repos} 个，${formatBytes(shadow.bytes)}`;
+        report.item(`file-history：${usage.blobs} 个备份，${formatBytes(usage.bytes)}${shadowText}（${fileHistoryDir(dataDir)}；ama sessions prune 清理）`);
+    }
+    catch (error) {
+        report.item(`file-history：读取失败（${error.message}）`);
+    }
+}
 export async function runDoctor(argv, io, deps) {
     const { values, flags } = parseSubArgs(argv, ["profile", "auth-file"], ["trust", "no-trust"]);
     if (flags.has("help")) {
@@ -213,6 +230,7 @@ export async function runDoctor(argv, io, deps) {
     report.section("目录");
     report.item(`配置目录：${level.configDir}`);
     report.item(`数据目录：${level.dataDir}${existsSync(level.dataDir) ? "" : "（尚未创建）"}`);
+    await fileHistoryLine(report, level.dataDir);
     report.section("配置层级（缺省 ← 用户级 ← profile ← 项目级（只能收紧）← 命令行）");
     report.item("缺省：内置");
     probeLine(report, "用户级", "config", level.userConfigPath);
@@ -233,6 +251,9 @@ export async function runDoctor(argv, io, deps) {
         report.item(`codemode：${codemode.mode}（${codemode.reason}）`);
         if (codemode.unavailable !== undefined)
             report.item(`  ${codemode.unavailable}`);
+        const os = osSandboxStatus(merged.config.sandbox?.enabled ?? "auto");
+        report.item(`操作系统沙箱：${os.kind === "none" ? "无" : os.kind}（${os.detail}${os.kind !== "none" && !os.restrictsWrites ? "；只隔离网络" : ""}）`);
+        report.item(`bash 沙箱：${resolveBashSandbox(merged.config.sandbox, { status: os }).detail}`);
     }
     catch {
         // probeLine 已报告

package/dist/cli/subcommands/models-discover.js

@@ -20,7 +20,7 @@
 import { authHeaders, mergeHeaders } from "../../ai/http.js";
 import { discoverLocalModels, materializeModel } from "../../ai/providers/registry.js";
 import { withCustomDefaults } from "../../ai/providers/catalog.js";
-import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { describeModelsDev, loadModelsDevIndex } from "../../ai/providers/models-dev-cache.js";
 import { matchLabel, modelsDevFields } from "../../ai/providers/models-dev.js";
 import { existsSync } from "node:fs";
 import { loadConfigFile } from "../../config/load.js";
@@ -173,15 +173,14 @@ async function run(ctx) {
     }
     const configured = new Map(provider.models.map((m) => [m.id, m]));
     io.stdout(`${provider.id}：发现 ${found.length} 个模型（${modelsUrl(provider)}）\n`);
-    const md = await refreshModelsDev({ dataDir: ctx.level.dataDir, env: io.env });
-    io.stdout(`${describeRefresh(md)}\n`);
-    if (md.warning !== undefined)
-        io.stderr(`ama: 警告：${md.warning}\n`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(ctx.level.dataDir);
+    io.stdout(`${describeModelsDev(ctx.level.dataDir)}\n`);
     const noTools = new Set();
     const unmatched = new Set();
     for (const model of found) {
         const known = configured.get(model.id);
-        const match = md.index?.match(model.id);
+        const match = mdIndex.match(model.id);
         const fields = match !== undefined ? modelsDevFields(match.model) : undefined;
         if (fields?.toolCall === false)
             noTools.add(model.id);

package/dist/cli/subcommands/models.d.ts

@@ -7,6 +7,8 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import type { ProviderRegistryApi } from "../../ai/types.js";
 import type { CliIo, RuntimeDeps } from "../deps.js";

package/dist/cli/subcommands/models.js

@@ -7,9 +7,12 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import { formatModelRef, modelRefOf } from "../../ai/providers/channels.js";
 import { describeRefresh, modelsDevCachePath, refreshModelsDev, } from "../../ai/providers/models-dev-cache.js";
+import { snapshotMeta } from "../../ai/providers/models-dev-snapshot.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
@@ -78,6 +81,34 @@ async function check(io, registry, ref) {
     io.stdout(`${shown} 可用（${model.api}，${ms} ms，stopReason ${message.stopReason}）\n`);
     return ExitCode.Ok;
 }
+/**
+ * `ama models refresh [--provider <id>[,<id>…]]`：显式联网拉 models.dev，按内置快照的清单裁剪，
+ * 写用户级覆盖 `<dataDir>/models-dev.json`（docs/providers.md「模型元数据」）。启动与其它命令不联网。
+ */
+const REFRESH_ACTION = {
+    usage: "ama models refresh [--provider <id>[,<id>…]]",
+    valueOptions: ["provider"],
+    run: async (ctx) => {
+        const only = ctx.values.get("provider");
+        const providers = only
+            ?.split(",")
+            .map((p) => p.trim())
+            .filter(Boolean);
+        ctx.io.stdout(`内置快照：${snapshotMeta().fetchedAt}；正在拉取 models.dev…\n`);
+        const result = await refreshModelsDev({
+            dataDir: ctx.level.dataDir,
+            env: ctx.io.env,
+            ...(providers !== undefined && providers.length > 0 ? { providers } : {}),
+        });
+        if (result.warning !== undefined)
+            ctx.io.stderr(`ama: ${result.warning}\n`);
+        ctx.io.stdout(`${describeRefresh(result)}\n`);
+        if (result.status === "failed")
+            return ExitCode.RuntimeError;
+        ctx.io.stdout(`已写入 ${modelsDevCachePath(ctx.level.dataDir)}\n`);
+        return ExitCode.Ok;
+    },
+};
 /** 动作表：键是子命令名，顺序即用法文本顺序。 */
 export const MODELS_ACTIONS = Object.freeze({
     list: {
@@ -92,20 +123,8 @@ export const MODELS_ACTIONS = Object.freeze({
     },
     discover: DISCOVER_ACTION,
     "cache-probe": CACHE_PROBE_ACTION,
-    "refresh-catalog": {
-        usage: "ama models refresh-catalog",
-        run: async (ctx) => {
-            const result = await refreshModelsDev({
-                dataDir: ctx.level.dataDir,
-                env: ctx.io.env,
-                force: true,
-            });
-            ctx.io.stdout(`${describeRefresh(result)}\n${modelsDevCachePath(ctx.level.dataDir)}\n`);
-            if (result.warning !== undefined)
-                ctx.io.stderr(`ama: 警告：${result.warning}\n`);
-            return result.status === "unavailable" ? ExitCode.RuntimeError : ExitCode.Ok;
-        },
-    },
+    refresh: REFRESH_ACTION,
+    "refresh-catalog": { ...REFRESH_ACTION, usage: "ama models refresh-catalog（refresh 的旧名）" },
 });
 export const MODELS_USAGE = `用法：${Object.values(MODELS_ACTIONS)
     .map((a) => a.usage)

package/dist/cli/subcommands/providers.js

@@ -12,7 +12,7 @@
  */
 import { existsSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { describeModelsDev, loadModelsDevIndex } from "../../ai/providers/models-dev-cache.js";
 import { modelsDevFields } from "../../ai/providers/models-dev.js";
 import { PROVIDER_ID_PATTERN, setAuthKey } from "../../config/auth-file.js";
 import { loadConfigFile } from "../../config/load.js";
@@ -260,17 +260,16 @@ async function add(ctx, id, refresh) {
         return ExitCode.RuntimeError;
     }
     io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
-    const md = await refreshModelsDev({ dataDir: level.dataDir, env: io.env, force: refresh });
-    io.stdout(`${describeRefresh(md)}\n`);
-    if (md.warning !== undefined)
-        io.stderr(`ama: 警告：${md.warning}\n`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(level.dataDir);
+    io.stdout(`${describeModelsDev(level.dataDir)}\n`);
     io.stdout(`候选渠道：${candidates.map((c) => `${c.name}（${c.api} ${c.baseUrl}）`).join(" · ")}\n`);
     const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
     const result = await plan(ctx, {
         id,
         candidates,
         listed,
-        index: md.index,
+        index: mdIndex,
         existingIds,
         apiKey: key.apiKey,
         registry,

package/dist/cli/subcommands/sessions.d.ts

@@ -5,7 +5,9 @@
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
  * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
  * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
- * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）；之后清理检查点备份
+ *   （未被任何会话引用且超过 1 天的 blob，docs/rewind-plan.md §1.4）与超过 7 天的剪贴板图片
+ *   （`<数据目录>/clipboard/`，W5-I），`--dry-run` 时只报告。
  */
 import type { CliIo, RuntimeDeps } from "../deps.js";
 export declare const SESSIONS_USAGE = "\u7528\u6CD5\uFF1Aama sessions list [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions show <id> [--session-dir <\u76EE\u5F55>]\n      ama sessions prune [--older-than <\u5929>] [--dry-run] [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions search <\u5173\u952E\u8BCD|/\u6B63\u5219/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]\n      ama sessions export <id> [--format md|json|jsonl] [--output <\u6587\u4EF6>] [--branch leaf|all]\n";