@armadra/agent 0.3.0 → 0.5.0

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

@@ -16,6 +16,18 @@ export declare const ExitCode: {
     readonly Session: 5;
     /** 宿主 / Hook 加载或启动失败。 */
     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

@@ -16,6 +16,18 @@ export const ExitCode = {
     Session: 5,
     /** 宿主 / Hook 加载或启动失败。 */
     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）。 */
@@ -31,6 +43,9 @@ export const EXIT_CODE_DESCRIPTIONS = {
     4: "无可用模型或密钥",
     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/fake-visibility.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 测试供应商 `fake` 的可见性：零配置的模型选择器、`ama doctor`、`ama models list`、`ama providers list`、
+ * `ama config show` 缺省不列出它（实测零配置 TUI 的首项是 `fake › echo`，直接回车就用上了测试供应商）。
+ *
+ * - `AMA_SHOW_FAKE=1` 或设置了 `AMA_FAKE_SCRIPT` 时照常列出；
+ * - 只藏 `list()`：`--model fake/…`、`findModel`、`resolveApiKey` 等显式引用不受影响。
+ */
+import type { ProviderRegistryApi } from "../ai/types.js";
+export declare const SHOW_FAKE_ENV = "AMA_SHOW_FAKE";
+export declare const FAKE_PROVIDER_ID = "fake";
+export declare function fakeVisible(env: Readonly<Record<string, string | undefined>>): boolean;
+/** 列表里藏起 fake 的注册表视图（其余方法原样转给原注册表）；可见时原样返回。 */
+export declare function hideFakeProvider<T extends ProviderRegistryApi>(registry: T, env: Readonly<Record<string, string | undefined>>): T;

package/dist/cli/fake-visibility.js

@@ -0,0 +1,26 @@
+/**
+ * 测试供应商 `fake` 的可见性：零配置的模型选择器、`ama doctor`、`ama models list`、`ama providers list`、
+ * `ama config show` 缺省不列出它（实测零配置 TUI 的首项是 `fake › echo`，直接回车就用上了测试供应商）。
+ *
+ * - `AMA_SHOW_FAKE=1` 或设置了 `AMA_FAKE_SCRIPT` 时照常列出；
+ * - 只藏 `list()`：`--model fake/…`、`findModel`、`resolveApiKey` 等显式引用不受影响。
+ */
+import { FAKE_SCRIPT_ENV } from "../ai/fake/fake-provider.js";
+export const SHOW_FAKE_ENV = "AMA_SHOW_FAKE";
+export const FAKE_PROVIDER_ID = "fake";
+export function fakeVisible(env) {
+    return env[SHOW_FAKE_ENV] === "1" || (env[FAKE_SCRIPT_ENV] ?? "") !== "";
+}
+/** 列表里藏起 fake 的注册表视图（其余方法原样转给原注册表）；可见时原样返回。 */
+export function hideFakeProvider(registry, env) {
+    if (fakeVisible(env))
+        return registry;
+    return new Proxy(registry, {
+        get(target, prop) {
+            if (prop === "list")
+                return () => target.list().filter((provider) => provider.id !== FAKE_PROVIDER_ID);
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}

package/dist/cli/from-prompt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/sessions.md「复用」）。[W4-D]
+ *
+ * - 文本：那条消息的文本；命令行另有位置参数时接在后面（空一行）；
+ * - 图片：`-p` 时把图片块写进临时目录、追加到 `--image`（沿用 print 模式的图片校验：模型不收图片 →
+ *   用法错误），运行结束删掉；交互 / 行式界面只带文本，有图片时在 stderr 提示一行；
+ * - 交互模式经现有的「初始提示」参数传入（启动后直接提交，与 `ama "提示"` 相同）；
+ * - `--mode rpc` 不支持（rpc 的提示来自宿主）。
+ * 会话目录用 bootstrap 解析后的 `paths.sessionDir`（含 `--session-dir` 与 profile），本目录优先找 id。
+ */
+import { type ParsedArgs } from "./args.js";
+import type { CliIo, ModeContext } from "./deps.js";
+import type { Runtime } from "./runtime.js";
+export interface FromContext {
+    context: ModeContext;
+    cleanup(): void;
+}
+export declare function applyFromOption(args: ParsedArgs, runtime: Pick<Runtime, "mode" | "paths">, io: CliIo): FromContext;

package/dist/cli/from-prompt.js

@@ -0,0 +1,49 @@
+/**
+ * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/sessions.md「复用」）。[W4-D]
+ *
+ * - 文本：那条消息的文本；命令行另有位置参数时接在后面（空一行）；
+ * - 图片：`-p` 时把图片块写进临时目录、追加到 `--image`（沿用 print 模式的图片校验：模型不收图片 →
+ *   用法错误），运行结束删掉；交互 / 行式界面只带文本，有图片时在 stderr 提示一行；
+ * - 交互模式经现有的「初始提示」参数传入（启动后直接提交，与 `ama "提示"` 相同）；
+ * - `--mode rpc` 不支持（rpc 的提示来自宿主）。
+ * 会话目录用 bootstrap 解析后的 `paths.sessionDir`（含 `--session-dir` 与 profile），本目录优先找 id。
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveFromMessage } from "../session/reuse.js";
+import { UsageError } from "./args.js";
+const EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+export function applyFromOption(args, runtime, io) {
+    const spec = args.from;
+    const plain = { context: { args, prompt: args.prompt, io }, cleanup: () => { } };
+    if (spec === undefined)
+        return plain;
+    if (runtime.mode === "rpc")
+        throw new UsageError("--from 不用于 --mode rpc");
+    const picked = resolveFromMessage(runtime.paths.sessionDir, spec, runtime.paths.cwd);
+    const parts = [picked.text, args.prompt ?? ""].filter((p) => p.trim() !== "");
+    const prompt = parts.length > 0 ? parts.join("\n\n") : undefined;
+    if (picked.images.length === 0) {
+        return { context: { args, prompt, io }, cleanup: () => { } };
+    }
+    if (runtime.mode !== "print") {
+        io.stderr(`ama: --from 的消息带 ${picked.images.length} 张图片，交互界面只带文本（-p 会一并发送）\n`);
+        return { context: { args, prompt, io }, cleanup: () => { } };
+    }
+    const dir = mkdtempSync(join(tmpdir(), "ama-from-"));
+    const files = picked.images.map((image, i) => {
+        const file = join(dir, `${picked.n}-${i + 1}.${EXT[image.mimeType] ?? "png"}`);
+        writeFileSync(file, Buffer.from(image.data, "base64"), { mode: 0o600 });
+        return file;
+    });
+    return {
+        context: { args: { ...args, images: [...args.images, ...files] }, prompt, io },
+        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}

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/main.d.ts

@@ -5,14 +5,17 @@
  * - 设 `AMA=1`、`AI_AGENT=ama`；直接执行时装 `uncaughtException` / `unhandledRejection` →
  *   stderr 一行 + 退出码 1；SIGINT / SIGTERM 交给当前模式。
  * - `--version` / `--help` 短路；子命令 `auth / sessions / models / providers / doctor / config /
- *   init` 分派后返回；其余命令启动前若配置目录不存在则静默初始化（`AMA_NO_INIT=1` 关闭）；
+ *   init` 分派后返回；进入对话的命令（与 `providers add`）启动前若配置目录不存在则静默初始化
+ *   （`AMA_NO_INIT=1` 关闭），只读子命令（`config show`、`doctor`、`models list` 等）不写配置目录；
  *   其余交给 `runCli()`（bootstrap → 模式）。
+ * - 设了 HTTPS_PROXY / HTTP_PROXY 时启用 Node 内置的环境变量代理（cli/proxy.ts）；不支持的 Node
+ *   版本在会联网的命令里提示一次。
  * - 运行时实现（RuntimeDeps）：`MainOptions.deps` > `registerRuntimeDeps()` > 组装根
  *   `createRuntimeDeps()`（cli/compose.ts，动态 import）。
  * - 签名 `main(argv): Promise<number>` 与「直接执行才自动运行」判定保持不变：
  *   src/bundle.ts 显式调用 `main()`。
  */
-import type { CliIo, RuntimeDeps } from "./deps.js";
+import type { CliIo, RuntimeDeps, StdinKind } from "./deps.js";
 /** 集成批次注入运行时实现（B1 / B2 / B3 / B6 / B7）。 */
 export declare function registerRuntimeDeps(deps: RuntimeDeps | undefined): void;
 export interface MainOptions {
@@ -23,5 +26,9 @@ export interface MainOptions {
 }
 /** 读 stdin 全部内容；TTY 下只读一行且不回显（auth set）。 */
 export declare function readStdinDefault(): Promise<string>;
+/** fd 0 的类型；fstat 失败（已关闭）按 `null` 处理。 */
+export declare function stdinKindDefault(): StdinKind;
+/** 等 stdin 首字节至多 `timeoutMs`；超时则停止读取并返回 undefined，否则读到 EOF。 */
+export declare function readStdinFirstByteDefault(timeoutMs: number): Promise<string | undefined>;
 export declare function defaultIo(): CliIo;
 export declare function main(argv: readonly string[], options?: MainOptions): Promise<number>;

package/dist/cli/main.js

@@ -5,14 +5,17 @@
  * - 设 `AMA=1`、`AI_AGENT=ama`；直接执行时装 `uncaughtException` / `unhandledRejection` →
  *   stderr 一行 + 退出码 1；SIGINT / SIGTERM 交给当前模式。
  * - `--version` / `--help` 短路；子命令 `auth / sessions / models / providers / doctor / config /
- *   init` 分派后返回；其余命令启动前若配置目录不存在则静默初始化（`AMA_NO_INIT=1` 关闭）；
+ *   init` 分派后返回；进入对话的命令（与 `providers add`）启动前若配置目录不存在则静默初始化
+ *   （`AMA_NO_INIT=1` 关闭），只读子命令（`config show`、`doctor`、`models list` 等）不写配置目录；
  *   其余交给 `runCli()`（bootstrap → 模式）。
+ * - 设了 HTTPS_PROXY / HTTP_PROXY 时启用 Node 内置的环境变量代理（cli/proxy.ts）；不支持的 Node
+ *   版本在会联网的命令里提示一次。
  * - 运行时实现（RuntimeDeps）：`MainOptions.deps` > `registerRuntimeDeps()` > 组装根
  *   `createRuntimeDeps()`（cli/compose.ts，动态 import）。
  * - 签名 `main(argv): Promise<number>` 与「直接执行才自动运行」判定保持不变：
  *   src/bundle.ts 显式调用 `main()`。
  */
-import { realpathSync } from "node:fs";
+import { fstatSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { AMA_VERSION } from "../version.js";
 import { parseArgs } from "./args.js";
@@ -27,6 +30,8 @@ import { runInit } from "./subcommands/init.js";
 import { autoInitConfigDir } from "../config/init.js";
 import { resolveConfigDir } from "../config/paths.js";
 import { runSessions } from "./subcommands/sessions.js";
+import { runStats } from "./subcommands/stats.js";
+import { enableEnvProxy, proxyHint } from "./proxy.js";
 let registeredDeps;
 /** 集成批次注入运行时实现（B1 / B2 / B3 / B6 / B7）。 */
 export function registerRuntimeDeps(deps) {
@@ -72,6 +77,61 @@ export function readStdinDefault() {
         stdin.on("data", onData);
     });
 }
+/** fd 0 的类型；fstat 失败（已关闭）按 `null` 处理。 */
+export function stdinKindDefault() {
+    try {
+        const stat = fstatSync(0);
+        if (stat.isFile())
+            return "file";
+        if (stat.isFIFO())
+            return "fifo";
+        if (stat.isSocket())
+            return "socket";
+        if (stat.isCharacterDevice())
+            return process.stdin.isTTY === true ? "tty" : "null";
+        return "other";
+    }
+    catch {
+        return "null";
+    }
+}
+/** 等 stdin 首字节至多 `timeoutMs`；超时则停止读取并返回 undefined，否则读到 EOF。 */
+export function readStdinFirstByteDefault(timeoutMs) {
+    const stdin = process.stdin;
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let timer;
+        const cleanup = () => {
+            clearTimeout(timer);
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.off("error", onError);
+        };
+        const onData = (chunk) => {
+            clearTimeout(timer);
+            timer = undefined;
+            chunks.push(chunk);
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(Buffer.concat(chunks).toString("utf8"));
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        timer = setTimeout(() => {
+            cleanup();
+            // 不再读：释放句柄，父进程留着不关的管道不会让进程挂住
+            stdin.pause();
+            stdin.destroy();
+            resolve(undefined);
+        }, timeoutMs);
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+        stdin.once("error", onError);
+    });
+}
 export function defaultIo() {
     return {
         stdout: (text) => void process.stdout.write(text),
@@ -81,6 +141,8 @@ export function defaultIo() {
         env: process.env,
         cwd: process.cwd(),
         readStdin: readStdinDefault,
+        readStdinFirstByte: readStdinFirstByteDefault,
+        stdinKind: stdinKindDefault,
     };
 }
 let hooksInstalled = false;
@@ -122,8 +184,18 @@ export async function main(argv, options = {}) {
         if (parsed.kind !== "subcommand")
             noTui = parsed.args.noTui;
         const informational = parsed.kind === "run" ? parsed.args.help || parsed.args.version : parsed.name === "init";
-        if (!informational)
+        // 首次自动初始化只在会进入对话的命令（和接入供应商）里做；只读子命令不写配置目录
+        const startsWork = parsed.kind === "run" || (parsed.name === "providers" && parsed.argv[0] === "add");
+        if (!informational && startsWork)
             autoInitConfigDir(resolveConfigDir({ env: io.env }), io.env);
+        // 进程级副作用（全局 dispatcher）：只在真正的进程入口做，测试里调 main() 不碰
+        if (!informational && options.processHooks !== false) {
+            const proxy = enableEnvProxy(io.env);
+            const online = parsed.kind === "run" || parsed.name === "models" || parsed.name === "providers";
+            const hint = online ? proxyHint(proxy) : undefined;
+            if (hint !== undefined)
+                io.stderr(hint);
+        }
         if (parsed.kind === "subcommand") {
             switch (parsed.name) {
                 case "auth":
@@ -140,6 +212,8 @@ export async function main(argv, options = {}) {
                     return await runConfig(parsed.argv, io, await resolveDeps());
                 case "init":
                     return runInit(parsed.argv, io);
+                case "stats":
+                    return await runStats(parsed.argv, io);
             }
         }
         if (parsed.args.version) {

package/dist/cli/proxy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 环境变量代理（W4-C）：Node 的全局 fetch 缺省不读 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`。
+ *
+ * - 没设代理变量 → 什么都不做。
+ * - 运行时已接管（`NODE_USE_ENV_PROXY=1` 或 `--use-env-proxy`，且 Node 支持）→ 不重复设置。
+ * - Node 有 `http.setGlobalProxyFromEnv()`（24.x / 26.x 等）→ 进程启动时调用一次，等价于
+ *   `NODE_USE_ENV_PROXY=1`（fetch 与 http/https 全局 agent 都走代理，`NO_PROXY` 生效）。零依赖。
+ * - 不支持的 Node 版本 → 只在会联网的命令里于 stderr 提示一次（不中断）。
+ *
+ * `ama doctor` 用 `describeProxy()` 显示同一份状态；代理 URL 里的账号密码打码。
+ */
+export interface ProxyEnv {
+    httpsProxy?: string;
+    httpProxy?: string;
+    noProxy?: string;
+}
+export type ProxyState = "none"
+/** 运行时已按环境变量接管（NODE_USE_ENV_PROXY / --use-env-proxy）。 */
+ | "runtime"
+/** ama 启动时调用 http.setGlobalProxyFromEnv() 启用。 */
+ | "enabled"
+/** 设了代理变量，但当前 Node 不支持内置代理。 */
+ | "unsupported"
+/** 代理 URL 无法解析。 */
+ | "invalid";
+export interface ProxyStatus {
+    env: ProxyEnv;
+    state: ProxyState;
+    error?: string;
+}
+type SetGlobalProxy = (env?: NodeJS.ProcessEnv) => () => void;
+export interface ProxyRuntime {
+    setGlobalProxyFromEnv?: SetGlobalProxy | undefined;
+    execArgv: readonly string[];
+    version: string;
+}
+export declare function readProxyEnv(env: Readonly<Record<string, string | undefined>>): ProxyEnv;
+export declare function defaultProxyRuntime(): ProxyRuntime;
+/** 只判断不启用：没设代理 / 运行时已接管 / 能启用 / 不支持 / URL 无法解析。 */
+export declare function inspectProxy(env: Readonly<Record<string, string | undefined>>, runtime?: ProxyRuntime): ProxyStatus;
+/** 按上面的规则启用代理（进程级副作用）；同一进程只做一次，之后返回同一份状态。 */
+export declare function enableEnvProxy(env: Readonly<Record<string, string | undefined>>, runtime?: ProxyRuntime): ProxyStatus;
+/** 测试用：清掉进程内记住的状态。 */
+export declare function resetProxyForTest(): void;
+/** 代理 URL 里的账号密码打码。 */
+export declare function redactProxyUrl(value: string): string;
+/** 不能启用时给一次 stderr 提示（每个进程至多一次）；能用或没设代理返回 undefined。 */
+export declare function proxyHint(status: ProxyStatus, nodeVersion?: string): string | undefined;
+/** `ama doctor` 的代理段落。 */
+export declare function describeProxy(status: ProxyStatus): string[];
+export {};

package/dist/cli/proxy.js

@@ -0,0 +1,135 @@
+/**
+ * 环境变量代理（W4-C）：Node 的全局 fetch 缺省不读 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`。
+ *
+ * - 没设代理变量 → 什么都不做。
+ * - 运行时已接管（`NODE_USE_ENV_PROXY=1` 或 `--use-env-proxy`，且 Node 支持）→ 不重复设置。
+ * - Node 有 `http.setGlobalProxyFromEnv()`（24.x / 26.x 等）→ 进程启动时调用一次，等价于
+ *   `NODE_USE_ENV_PROXY=1`（fetch 与 http/https 全局 agent 都走代理，`NO_PROXY` 生效）。零依赖。
+ * - 不支持的 Node 版本 → 只在会联网的命令里于 stderr 提示一次（不中断）。
+ *
+ * `ama doctor` 用 `describeProxy()` 显示同一份状态；代理 URL 里的账号密码打码。
+ */
+import * as http from "node:http";
+function pick(env, name) {
+    const value = env[name.toLowerCase()] ?? env[name.toUpperCase()];
+    return value !== undefined && value.trim() !== "" ? value.trim() : undefined;
+}
+export function readProxyEnv(env) {
+    const out = {};
+    const https = pick(env, "https_proxy");
+    const plain = pick(env, "http_proxy");
+    const no = pick(env, "no_proxy");
+    if (https !== undefined)
+        out.httpsProxy = https;
+    if (plain !== undefined)
+        out.httpProxy = plain;
+    if (no !== undefined)
+        out.noProxy = no;
+    return out;
+}
+export function defaultProxyRuntime() {
+    const fn = http.setGlobalProxyFromEnv;
+    return {
+        setGlobalProxyFromEnv: typeof fn === "function" ? fn.bind(http) : undefined,
+        execArgv: process.execArgv,
+        version: process.versions.node,
+    };
+}
+/** Node ≥ 24，或 22.21+：认 NODE_USE_ENV_PROXY / --use-env-proxy。 */
+function runtimeReadsEnvProxy(version) {
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    return major >= 24 || (major === 22 && minor >= 21);
+}
+let current;
+let hinted = false;
+/** 只判断不启用：没设代理 / 运行时已接管 / 能启用 / 不支持 / URL 无法解析。 */
+export function inspectProxy(env, runtime = defaultProxyRuntime()) {
+    if (current !== undefined)
+        return current;
+    const proxy = readProxyEnv(env);
+    if (proxy.httpsProxy === undefined && proxy.httpProxy === undefined)
+        return { env: proxy, state: "none" };
+    const flagged = env["NODE_USE_ENV_PROXY"] === "1" ||
+        runtime.execArgv.includes("--use-env-proxy") ||
+        (env["NODE_OPTIONS"] ?? "").includes("--use-env-proxy");
+    if (flagged && runtimeReadsEnvProxy(runtime.version))
+        return { env: proxy, state: "runtime" };
+    if (runtime.setGlobalProxyFromEnv === undefined)
+        return { env: proxy, state: "unsupported" };
+    for (const value of [proxy.httpsProxy, proxy.httpProxy]) {
+        if (value !== undefined && !URL.canParse(value))
+            return { env: proxy, state: "invalid", error: `无法解析 ${redactProxyUrl(value)}` };
+    }
+    return { env: proxy, state: "enabled" };
+}
+/** 按上面的规则启用代理（进程级副作用）；同一进程只做一次，之后返回同一份状态。 */
+export function enableEnvProxy(env, runtime = defaultProxyRuntime()) {
+    if (current !== undefined)
+        return current;
+    const status = inspectProxy(env, runtime);
+    if (status.state === "enabled") {
+        try {
+            runtime.setGlobalProxyFromEnv?.({ ...env });
+        }
+        catch (error) {
+            current = { env: status.env, state: "invalid", error: error.message };
+            return current;
+        }
+    }
+    current = status;
+    return current;
+}
+/** 测试用：清掉进程内记住的状态。 */
+export function resetProxyForTest() {
+    current = undefined;
+    hinted = false;
+}
+/** 代理 URL 里的账号密码打码。 */
+export function redactProxyUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.username === "" && url.password === "")
+            return value;
+        url.username = url.username === "" ? "" : "***";
+        url.password = url.password === "" ? "" : "***";
+        return url.toString();
+    }
+    catch {
+        return value.replace(/\/\/[^@/]*@/, "//***@");
+    }
+}
+/** 不能启用时给一次 stderr 提示（每个进程至多一次）；能用或没设代理返回 undefined。 */
+export function proxyHint(status, nodeVersion = process.versions.node) {
+    if (hinted)
+        return undefined;
+    if (status.state === "unsupported") {
+        hinted = true;
+        return (`ama: 检测到 HTTPS_PROXY / HTTP_PROXY，但 Node ${nodeVersion} 的 fetch 不读代理变量，请求将直连；` +
+            "升级到 Node 24+，或在 Node 22.21+ 上设 NODE_USE_ENV_PROXY=1\n");
+    }
+    if (status.state === "invalid") {
+        hinted = true;
+        return `ama: 代理变量无法解析，请求将直连：${status.error ?? ""}\n`;
+    }
+    return undefined;
+}
+/** `ama doctor` 的代理段落。 */
+export function describeProxy(status) {
+    const { env } = status;
+    const lines = [];
+    if (env.httpsProxy !== undefined)
+        lines.push(`HTTPS_PROXY=${redactProxyUrl(env.httpsProxy)}`);
+    if (env.httpProxy !== undefined)
+        lines.push(`HTTP_PROXY=${redactProxyUrl(env.httpProxy)}`);
+    if (env.noProxy !== undefined)
+        lines.push(`NO_PROXY=${env.noProxy}`);
+    const state = {
+        none: "未设置代理变量：直连",
+        runtime: "已启用（Node 按 NODE_USE_ENV_PROXY / --use-env-proxy 接管）",
+        enabled: "已启用（ama 启动时调用 Node 内置的 setGlobalProxyFromEnv）",
+        unsupported: `✗ 当前 Node ${process.versions.node} 不支持内置代理，请求直连；升级到 Node 24+`,
+        invalid: `✗ 代理变量无法解析：${status.error ?? ""}`,
+    };
+    lines.push(state[status.state]);
+    return lines;
+}