@armadra/agent 0.3.0 → 0.5.0

package/dist/config/init.js

@@ -1,7 +1,9 @@
 /**
  * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
  *
- * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）：只有 `$schema`、
+ *   `version` 与空 `providers`，不写死任何缺省值——缺省值以后调整（例如 codemode 跟随预设）对老用户
+ *   同样生效，`config show` 的来源也显示 default 而不是 user；
  * - `config.schema.json` 不是用户文件，每次 init 都按当前版本重写（内容相同则不动）；
  * - 不创建 auth.json（只有 `ama auth set` / `ama providers add` 才写，0600）。
  * - 自动初始化只在 CLI 里、配置目录不存在时触发，`AMA_NO_INIT=1` 关闭；SDK 与测试不走这里。
@@ -12,14 +14,11 @@ import { CONFIG_SCHEMA_FILE, configSchemaText } from "./json-schema.js";
 import { AUTH_FILE, CONFIG_FILE } from "./paths.js";
 import { CONFIG_FILE_VERSION } from "./types.js";
 export const NO_INIT_ENV = "AMA_NO_INIT";
-/** 最小 config.json：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+/** 最小 config.json：只有 `$schema`、`version` 与空 `providers`（缺省值见 `ama config show`）。 */
 export function minimalConfig() {
     return {
         $schema: `./${CONFIG_SCHEMA_FILE}`,
         version: CONFIG_FILE_VERSION,
-        thinkingLevel: "medium",
-        permission: { mode: "default" },
-        tools: { preset: "default" },
         providers: {},
     };
 }
@@ -84,6 +83,14 @@ const STATUS_TEXT = {
     unchanged: "已是当前版本",
     overwritten: "已重写（原文件备份为 .bak）",
 };
+/** init 之后的下一步（配 key / 接中转站 / 自检）。 */
+export const INIT_NEXT_STEPS = [
+    "下一步：",
+    "  ama auth set anthropic          保存内置供应商的 key（或设置 ANTHROPIC_API_KEY 等环境变量）",
+    "  ama providers add <id> --base-url <url>   接入中转站或自建服务",
+    "  ama doctor                      检查配置、key 与运行环境",
+    "  ama config show                 查看生效配置与每项来源",
+];
 export function describeInit(result) {
     const lines = [`${result.dir}${result.dirCreated ? "  已创建（0700）" : "  已存在"}`];
     for (const file of result.files)

package/dist/config/json-schema.d.ts

@@ -3,6 +3,7 @@
  * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
  * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
  * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
+ * 顶层与各段的键（供应商内部除外）的 description / default 来自 key-docs.ts（`annotate`）。
  */
 type Schema = Record<string, unknown>;
 export declare const CONFIG_SCHEMA_FILE = "config.schema.json";

package/dist/config/json-schema.js

@@ -3,11 +3,15 @@
  * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
  * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
  * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
+ * 顶层与各段的键（供应商内部除外）的 description / default 来自 key-docs.ts（`annotate`）。
  */
 import { WARMING_MODES } from "../ai/cache/types.js";
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { CONFIG_KEY_DOCS, DYNAMIC_DEFAULTS, defaultFor } from "./key-docs.js";
 import { HOOK_TIMEOUT_MAX_MS, THINKING_LEVELS } from "./schema.js";
-import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESETS_STRICT_FIRST, } from "./types.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CHECKPOINT_MODES, SANDBOX_ENABLED_MODES, SANDBOX_NETWORK_MODES, CODEMODE_MODES, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
+import { AGENT_ID_PATTERN } from "./schema-w5.js";
+import { AGENTS_RESERVED_KEYS } from "./types-w5.js";
 export const CONFIG_SCHEMA_FILE = "config.schema.json";
 export const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
 const KNOWN_APIS = [
@@ -119,8 +123,69 @@ const provider = object({
     models: { type: "array", items: model("自定义模型（同 id 整条替换）") },
     modelOverrides: { type: "array", items: model("只改已有模型的元数据") },
 });
+// [W5-C0] 第五波的段（规则同 schema-w5.ts）
+const agentEntry = object({
+    maxConcurrent: num(1, 64),
+    maxMode: oneOf(PERMISSION_MODES_STRICT_FIRST),
+    model: str(),
+    env: object({ passthrough: strings }),
+});
+function w5Sections() {
+    return {
+        images: object({ resize: oneOf(IMAGE_RESIZE_MODES) }),
+        plan: object({
+            bash: oneOf(PLAN_BASH_MODES_STRICT_FIRST),
+            directory: str(),
+            unattended: oneOf(PLAN_UNATTENDED_MODES),
+            model: str(),
+            thinkingLevel: oneOf(THINKING_LEVELS),
+        }),
+        agents: object({ maxConcurrent: num(1, 64), sessionBudgetUsd: num(0), dirs: strings }, {
+            additionalProperties: agentEntry,
+            propertyNames: {
+                pattern: `^(${AGENTS_RESERVED_KEYS.join("|")}|${AGENT_ID_PATTERN.source.slice(1, -1)})$`,
+            },
+        }),
+        subagents: object({ maxConcurrent: num(1, 64), maxPending: num(0, 1024), defaultModel: str() }),
+        models: object({ aliases: object({ fast: str(), strong: str() }) }),
+        fallbackModel: str(),
+        limits: object({ maxTurns: num(1), maxCostUsd: num(0) }),
+        reminders: object({
+            todo: bool(),
+            fileChanges: bool(),
+            contextPressure: bool(),
+            budget: bool(),
+        }),
+        todo: object({ reminder: num(0) }),
+    };
+}
+/** 给顶层与各段的键写上 description 与 default（key-docs.ts）；供应商内部不动。 */
+function annotate(properties, prefix = "") {
+    for (const [key, shared] of Object.entries(properties)) {
+        const path = prefix === "" ? key : `${prefix}.${key}`;
+        // 片段（strings、bool() 等）在多处复用：先浅拷贝再写说明
+        const schema = { ...shared };
+        properties[key] = schema;
+        const description = CONFIG_KEY_DOCS[path];
+        if (description !== undefined)
+            schema["description"] = description;
+        const nested = schema["properties"];
+        if (nested !== undefined && path !== "providers") {
+            annotate(nested, path);
+            continue;
+        }
+        const value = defaultFor(path);
+        if (value !== undefined && DYNAMIC_DEFAULTS[path] === undefined)
+            schema["default"] = value;
+    }
+}
 /** 生成 config.json 的 JSON Schema。 */
 export function buildConfigJsonSchema() {
+    const schema = buildBaseSchema();
+    annotate(schema["properties"]);
+    return schema;
+}
+function buildBaseSchema() {
     return {
         $schema: "http://json-schema.org/draft-07/schema#",
         $id: CONFIG_SCHEMA_ID,
@@ -136,8 +201,19 @@ export function buildConfigJsonSchema() {
                 allow: strings,
                 deny: strings,
                 builtinDeny: { anyOf: [{ type: "boolean" }, strings] },
+                autoModel: str("auto 模式分类器的模型 provider/model；缺省用当前会话模型"),
+                autoSafeCommands: strings,
+            }),
+            compaction: object({
+                enabled: bool(),
+                reserveTokens: num(0),
+                keepRecentTokens: num(0),
+                prune: object({
+                    keepResults: num(0),
+                    clearAtLeast: { anyOf: [{ const: "auto" }, { type: "number", minimum: 0 }] },
+                }),
+                pruneExclude: strings,
             }),
-            compaction: object({ enabled: bool(), reserveTokens: num(0), keepRecentTokens: num(0) }),
             retry: object({
                 enabled: bool(),
                 maxRetries: num(0, 100),
@@ -145,7 +221,7 @@ export function buildConfigJsonSchema() {
                 maxDelayMs: num(0),
             }),
             tools: object({
-                preset: oneOf(TOOLS_PRESETS_STRICT_FIRST),
+                preset: oneOf(TOOLS_PRESET_INPUTS),
                 default: strings,
                 maxToolResultChars: num(1),
                 bashTimeoutMs: num(1),
@@ -158,11 +234,16 @@ export function buildConfigJsonSchema() {
             }),
             hooks: object({ timeoutMs: num(1, HOOK_TIMEOUT_MAX_MS) }),
             ui: object({
-                theme: oneOf(["dark", "light"]),
+                theme: oneOf(["dark", "light", "auto"]),
                 markdown: bool(),
                 showThinking: oneOf(["full", "collapsed", "hidden"]),
                 tuiMode: oneOf(["regular"]),
                 quietStartup: oneOf(["normal", "header", "silent"]),
+                ascii: bool(),
+                compact: bool(),
+                animation: bool(),
+                restoreOnCancel: bool(),
+                statusLine: oneOf(STATUS_LINE_MODES),
             }),
             skills: object({ dirs: strings }),
             cache: object({
@@ -172,6 +253,19 @@ export function buildConfigJsonSchema() {
                 missNotices: bool(),
                 warmSubagents: bool(),
             }),
+            request: object({ idleTimeoutMs: num(0) }),
+            checkpoints: object({
+                mode: oneOf(CHECKPOINT_MODES),
+                maxFileBytes: num(0),
+                keep: num(1),
+            }),
+            sandbox: object({
+                enabled: oneOf(SANDBOX_ENABLED_MODES),
+                bash: oneOf(SANDBOX_ENABLED_MODES, "bash 经 OS 沙箱运行（缺省 off）"),
+                network: oneOf(SANDBOX_NETWORK_MODES, "bash 沙箱里的网络（缺省 deny）"),
+                writable: { ...strings, description: "bash 沙箱追加的可写目录（绝对路径或 ~/…）" },
+            }),
+            ...w5Sections(),
         }),
         required: ["version"],
     };

package/dist/config/key-docs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * config.json 每个键的说明与缺省值：config.schema.json（编辑器悬停）与 `ama config show`（来源 default
+ * 的行）共用这一张表。
+ *
+ * - `description` 写在 `CONFIG_KEY_DOCS`；缺省值不手写，从 `DEFAULT_CONFIG`（merge.ts）、
+ *   `DEFAULT_CACHE_CONFIG`（types.ts）与代码里的隐式缺省（`IMPLICIT_DEFAULTS`）合成 `DISPLAY_DEFAULTS`；
+ * - 缺省值取决于运行时的键（自动选模型、跟随预设等）列在 `DYNAMIC_DEFAULTS`，schema 里不写 `default`，
+ *   说明里写规则；
+ * - 一致性由 json-schema.test.ts 守住：schema 的每个键都在表里，表里的每个键 schema 都有，缺省值与
+ *   DISPLAY_DEFAULTS 相同，DISPLAY_DEFAULTS 本身通过 `validateConfig`。
+ */
+import { type AmaConfig } from "./types.js";
+/** 全部有固定缺省值的键（展示用；运行时仍以 DEFAULT_CONFIG 合并）。 */
+export declare const DISPLAY_DEFAULTS: Readonly<AmaConfig>;
+/** 缺省值由运行时决定的键 → 规则（schema 不写 default）。 */
+export declare const DYNAMIC_DEFAULTS: Readonly<Record<string, string>>;
+/** 键路径 → 说明（段落本身也有一条）。 */
+export declare const CONFIG_KEY_DOCS: Readonly<Record<string, string>>;
+/** 叶子路径（段落不算）。 */
+export declare function documentedLeaves(): string[];
+/** 键路径的缺省值（DISPLAY_DEFAULTS 里取；没有返回 undefined）。 */
+export declare function defaultFor(path: string): unknown;

package/dist/config/key-docs.js

@@ -0,0 +1,174 @@
+/**
+ * config.json 每个键的说明与缺省值：config.schema.json（编辑器悬停）与 `ama config show`（来源 default
+ * 的行）共用这一张表。
+ *
+ * - `description` 写在 `CONFIG_KEY_DOCS`；缺省值不手写，从 `DEFAULT_CONFIG`（merge.ts）、
+ *   `DEFAULT_CACHE_CONFIG`（types.ts）与代码里的隐式缺省（`IMPLICIT_DEFAULTS`）合成 `DISPLAY_DEFAULTS`；
+ * - 缺省值取决于运行时的键（自动选模型、跟随预设等）列在 `DYNAMIC_DEFAULTS`，schema 里不写 `default`，
+ *   说明里写规则；
+ * - 一致性由 json-schema.test.ts 守住：schema 的每个键都在表里，表里的每个键 schema 都有，缺省值与
+ *   DISPLAY_DEFAULTS 相同，DISPLAY_DEFAULTS 本身通过 `validateConfig`。
+ */
+import { DEFAULT_IDLE_TIMEOUT_MS } from "../ai/http.js";
+import { DEFAULT_INLINE_BUDGET } from "../codemode/declarations.js";
+import { DEFAULT_CONFIG, mergeConfig } from "./merge.js";
+import { DEFAULT_CACHE_CONFIG, DEFAULT_CHECKPOINTS_CONFIG } from "./types.js";
+/** 代码里生效、但 DEFAULT_CONFIG 不写的缺省（写进去会改变合并结果或 `config.codemode` 的有无）。 */
+const IMPLICIT_DEFAULTS = {
+    providers: {},
+    permission: { builtinDeny: true, autoSafeCommands: [] },
+    tools: { default: [] },
+    codemode: { inlineBudget: DEFAULT_INLINE_BUDGET, requireStrict: false },
+    cache: { ...DEFAULT_CACHE_CONFIG },
+    request: { idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS },
+    ui: { compact: false, animation: true, restoreOnCancel: true },
+    checkpoints: { ...DEFAULT_CHECKPOINTS_CONFIG },
+    sandbox: { enabled: "auto", bash: "off", network: "deny", writable: [] },
+    // [W5-C0] 第五波键的缺省（行为由各批次实现）
+    compaction: { prune: { keepResults: 5, clearAtLeast: "auto" }, pruneExclude: [] },
+    images: { resize: "auto" },
+    plan: { bash: "readonly", unattended: "stop" },
+    agents: { maxConcurrent: 3, dirs: [] },
+    subagents: { maxConcurrent: 4, maxPending: 16 },
+    reminders: { todo: true, fileChanges: true, contextPressure: true, budget: true },
+    todo: { reminder: 10 },
+};
+/** 全部有固定缺省值的键（展示用；运行时仍以 DEFAULT_CONFIG 合并）。 */
+export const DISPLAY_DEFAULTS = Object.freeze(mergeConfig(DEFAULT_CONFIG, IMPLICIT_DEFAULTS));
+/** 缺省值由运行时决定的键 → 规则（schema 不写 default）。 */
+export const DYNAMIC_DEFAULTS = Object.freeze({
+    $schema: "ama init 写 ./config.schema.json",
+    defaultModel: "零配置自动选择",
+    "permission.autoModel": "当前会话模型",
+    "codemode.mode": "跟随预设",
+    "ui.ascii": "自动检测",
+    // [W5-C0]
+    "ui.statusLine": "独立终端 full，嵌入宿主（有 profile）compact",
+    "plan.directory": "<数据目录>/plans",
+    "plan.model": "不设：沿用当前模型",
+    "plan.thinkingLevel": "不设：沿用当前思考强度",
+    "agents.sessionBudgetUsd": "不设：不限",
+    "subagents.defaultModel": "不设：继承父会话模型",
+    "models.aliases.fast": "不设：fast 按 inherit 处理",
+    "models.aliases.strong": "不设：strong 按 inherit 处理",
+    fallbackModel: "不设：不回退",
+    "limits.maxTurns": "不设：不限",
+    "limits.maxCostUsd": "不设：不限",
+});
+/** 键路径 → 说明（段落本身也有一条）。 */
+export const CONFIG_KEY_DOCS = Object.freeze({
+    $schema: "编辑器用的 JSON Schema 路径",
+    version: "配置文件格式版本，固定为 1",
+    defaultModel: "缺省模型 provider/model 或 provider/model@channel；不写时零配置自动选择（ama config show 显示选了谁、为什么）",
+    thinkingLevel: "思考强度",
+    providers: "自定义供应商与对内置供应商的覆盖（docs/providers.md）",
+    permission: "权限（docs/permissions.md）",
+    "permission.mode": "权限模式；项目级只能更严",
+    "permission.allow": "放行规则，如 bash(npm test)；项目级不能加",
+    "permission.deny": "拒绝规则，如 write(**/.env)；各层累加",
+    "permission.builtinDeny": "内置 deny 表（.git/** 写、.ssh/** 读写）：true 全部启用，false 全部移除，数组 = 要移除的规则原文；只认用户级",
+    "permission.autoModel": "auto 模式分类器的模型 provider/model；不写时用当前会话模型；只认用户级",
+    "permission.autoSafeCommands": "auto 模式安全名单追加（词前缀或含 * 的通配）；只认用户级",
+    compaction: "自动压缩",
+    "compaction.enabled": "上下文接近上限时自动压缩",
+    "compaction.reserveTokens": "为回复预留的 token；剩余不足时触发压缩",
+    "compaction.keepRecentTokens": "压缩时原样保留的最近消息 token",
+    "compaction.prune": "档一裁剪（旧工具结果换成占位）；只认用户级（第五波 W5-H1 起生效）",
+    "compaction.prune.keepResults": "保留最近 N 个工具结果不裁",
+    "compaction.prune.clearAtLeast": "一次至少能省这么多 token 才裁（避免频繁打断缓存）；auto = max(20000, 0.1 × 上下文预算)",
+    "compaction.pruneExclude": "不被档一裁剪的工具名；只认用户级（第五波 W5-H1 起生效）",
+    retry: "请求失败重试",
+    "retry.enabled": "可重试的错误（限流、服务端错误、连接中断等）自动重试",
+    "retry.maxRetries": "最多重试次数",
+    "retry.baseDelayMs": "首次重试等待（毫秒，指数退避；有 Retry-After 时按它）",
+    "retry.maxDelayMs": "单次等待上限（毫秒）",
+    tools: "内置工具",
+    "tools.preset": "工具预设：default（六个工具；网络隔离时另加 codemode，todo 需在 tools.default 加 +todo）、minimal、codemode-only、coordinator；codemode 是 codemode-only 的旧名；项目级只能更严",
+    "tools.default": "在预设上微调：+name 加、-name 去，不带前缀的名字整组替换预设的内置工具；只认用户级",
+    "tools.maxToolResultChars": "单条工具结果进上下文的字符上限，超出保留首尾",
+    "tools.bashTimeoutMs": "bash 缺省超时（毫秒，单次调用可覆盖，最大 600000）",
+    "tools.disabled": "禁用的工具名；各层累加",
+    codemode: "codemode：模型写脚本批量调用工具（docs/codemode.md）",
+    "codemode.mode": "off | on | only；不写时跟随预设：default → on（Node ≥ 25；Node 22 / 24 → off）、codemode-only → only、minimal / coordinator → off；项目级只接受 off",
+    "codemode.inlineBudget": "only 模式在描述里内联工具声明的预算（估算 token），超出只列名字",
+    "codemode.requireStrict": "true：运行时 Node 不隔离网络（Node 22 / 24）时直接禁用 codemode",
+    hooks: "Hook 设置（Hook 本身写在 hooks.json）",
+    "hooks.timeoutMs": "单个 Hook 命令的缺省超时（毫秒）",
+    ui: "终端界面",
+    "ui.theme": "配色主题：dark、light，或 auto（按 COLORFGBG 猜，不发终端查询，猜不出用 dark）",
+    "ui.markdown": "按 Markdown 渲染回复",
+    "ui.showThinking": "思考内容的显示方式",
+    "ui.tuiMode": "终端界面形态（目前只有 regular）",
+    "ui.quietStartup": "启动画面详略",
+    "ui.ascii": "ASCII 字形（> * L、+ - |）；不写时自动检测：区域设置不含 UTF-8、TERM=linux、旧 conhost 时开启；AMA_ASCII=1/0 覆盖",
+    "ui.compact": "消息区块间不空行、启动头不画框",
+    "ui.animation": "false：运行中 spinner 静止，只在秒数变化时重绘",
+    "ui.restoreOnCancel": "运行中 Esc 中断、本回合还没有任何回复或工具调用时，撤回该回合并把原消息放回输入框",
+    "ui.statusLine": "底部信息行：full 两行（速率行 + 状态行），compact 一行；运行时 Ctrl+G 或 /statusline 切换（第五波 W5-A 起生效）",
+    skills: "Skill",
+    "skills.dirs": "追加的 Skill 目录；各层累加",
+    cache: "提示缓存；整段只认用户级",
+    request: "模型请求；整段只认用户级 / profile",
+    "request.idleTimeoutMs": "流空闲超时（毫秒）：等响应头或两块数据之间超过即判卡住并按可重试错误重试；0 关闭；AMA_IDLE_TIMEOUT_MS 覆盖",
+    "cache.warming": "保温：off 关闭，streaming 生成期间保温，idle 空闲时也保温",
+    "cache.retention": "缓存时长档：none、short、long（供应商支持时）",
+    "cache.minSavingsUsd": "保温的最低期望节省（美元）",
+    "cache.missNotices": "在消息区提示缓存未命中与上下文余量",
+    "cache.warmSubagents": "子会话（task）也保温",
+    checkpoints: "检查点：回滚代码用的文件备份（docs/sessions.md「检查点与文件备份」）",
+    "checkpoints.mode": "tools：跟踪 edit / write 改过的文件；shadow-git：另用影子 git 快照整个工作目录，bash 等直接改动也能回滚（需要 git，大目录自动降级为 tools）；off：关闭；AMA_CHECKPOINTS 覆盖；项目级只接受 off",
+    "checkpoints.maxFileBytes": "单个文件的备份上限（字节），超出不备份、回滚时报告无法恢复；项目级只能调小",
+    "checkpoints.keep": "可回滚的最近检查点数，更早的不再列为回滚点；只认用户级 / profile",
+    sandbox: '操作系统级沙箱（docs/sandbox.md）；只认用户级 / profile，项目级只接受 network: "deny"',
+    "sandbox.enabled": "auto：探测到可用的 macOS sandbox-exec / Linux bwrap、unshare 就用（codemode 子进程拒绝网络与写入；Node 22 / 24 上 codemode 因此网络隔离）；off：不用；AMA_SANDBOX=off 覆盖",
+    "sandbox.bash": "auto：bash 经 sandbox-exec / bwrap 运行（unshare 不算），写入只限工作区、临时目录、输出目录与 sandbox.writable，default 模式下沙箱内命令免审批；off：不用；只认用户级 / profile",
+    "sandbox.network": "bash 沙箱里的网络：deny 拒绝（沙箱内免审批的前提）；allow 允许联网但写入仍受限、照常审批；项目级只能设 deny",
+    "sandbox.writable": "bash 沙箱追加的可写目录（绝对路径或 ~/…）；只认用户级 / profile",
+    // [W5-C0] 第五波（docs/wave5-plan.md）；括号里是起生效的批次
+    images: "图像输入；只认用户级（第五波 W5-I 起生效）",
+    "images.resize": "auto：图片超过端点上限时用系统工具（sips / magick）缩放，找不到工具按原规则拒绝；off：从不缩放",
+    plan: "Plan 模式（第五波 W5-F 起生效）",
+    "plan.bash": "plan 模式下的 bash：readonly 只读命令放行其余拒绝，ask 其余询问，deny 全拒；项目级只能更严",
+    "plan.directory": "计划文件目录（必须在项目根之内，否则回落缺省）；只认用户级",
+    "plan.unattended": "无人值守（-p、RPC 未声明 plans 能力）时：stop 落盘计划后停下等人审批，approve 自动批准执行；只认用户级",
+    "plan.model": "规划用模型 provider/model[@channel]：进入 plan 时切换、批准时切回；只认用户级",
+    "plan.thinkingLevel": "规划时的思考强度；只认用户级",
+    agents: "外部 Agent（claude / codex / ACP）与子 Agent 类型；agents.<id> 设单个 Agent 的 maxConcurrent / maxMode / model / env.passthrough；只认用户级（第五波 W5-E / W5-G 起生效）",
+    "agents.maxConcurrent": "外部 Agent 的总并发",
+    "agents.sessionBudgetUsd": "本会话外部 Agent 的美元预算",
+    "agents.dirs": "追加的子 Agent 定义目录（*.md）；各层累加",
+    subagents: "ama 自己的 task 子会话；只认用户级（第五波 W5-G 起生效）",
+    "subagents.maxConcurrent": "同时运行的子会话数",
+    "subagents.maxPending": "排队上限，超出时 task 报错",
+    "subagents.defaultModel": "子会话缺省模型 provider/model[@channel]",
+    models: "模型别名；只认用户级（第五波 W5-G 起生效）",
+    "models.aliases": "子 Agent 定义里 model: fast / strong 指向的模型",
+    "models.aliases.fast": "fast 别名的模型 provider/model[@channel]",
+    "models.aliases.strong": "strong 别名的模型 provider/model[@channel]",
+    fallbackModel: "回退模型 provider/model[@channel]：可重试错误用尽或过载时切换重试一次，下一回合回主模型；只认用户级（第五波 W5-H2 起生效）",
+    limits: "会话预算，到限结束本次运行（-p 退出码 8）；--max-turns / --max-cost 覆盖；只认用户级（第五波 W5-H2 起生效）",
+    "limits.maxTurns": "一次运行最多回合数",
+    "limits.maxCostUsd": "一次运行的美元上限",
+    reminders: "附在对话尾部的提醒（不改缓存前缀）；项目级可设（第五波 W5-H2 起生效）",
+    "reminders.todo": "todo 有未完成项且多回合未更新时复述",
+    "reminders.fileChanges": "读过的文件被外部改动时列出",
+    "reminders.contextPressure": "上下文用量到 70% / 85% 时各提醒一次",
+    "reminders.budget": "预算剩余不足 20% 时提醒",
+    todo: "todo 工具；只认用户级（第五波 W5-F / W5-H2 起生效）",
+    "todo.reminder": "连续 N 回合未更新且有未完成项时提醒复述；0 关闭",
+});
+/** 叶子路径（段落不算）。 */
+export function documentedLeaves() {
+    const keys = Object.keys(CONFIG_KEY_DOCS);
+    return keys.filter((key) => !keys.some((other) => other.startsWith(`${key}.`)));
+}
+/** 键路径的缺省值（DISPLAY_DEFAULTS 里取；没有返回 undefined）。 */
+export function defaultFor(path) {
+    let node = DISPLAY_DEFAULTS;
+    for (const key of path.split(".")) {
+        if (typeof node !== "object" || node === null || Array.isArray(node))
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}

package/dist/config/merge.d.ts

@@ -2,14 +2,17 @@
  * 配置层级合并（设计 §7.2、§10.2）。[B5]
  *
  * 顺序：内置缺省 ← 用户级 ← profile.config ← 项目级（受限字段，只能收紧）← 命令行。
- * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny`、
+ * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny / autoSafeCommands`、
  *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
- * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严）、
- *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
- *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
+ *   auto / full-auto）、
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
+ *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
+ *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；
+ *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPreset } from "./types.js";
+import type { AmaConfig, CodemodeMode, PlanBashMode, ToolsPresetInput } from "./types.js";
 import type { PermissionMode, RuleSource } from "../permissions/types.js";
 import type { ModelThinkingLevel } from "../ai/types.js";
 export declare const DEFAULT_CONFIG: Readonly<AmaConfig>;
@@ -28,13 +31,13 @@ export interface RestrictResult {
     accepted: Partial<AmaConfig>;
     warnings: string[];
 }
-/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode 最宽）。 */
-export declare function isPresetStricterOrEqual(a: ToolsPreset, b: ToolsPreset): boolean;
+/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode-only 最宽；别名按规范名比）。 */
+export declare function isPresetStricterOrEqual(a: ToolsPresetInput, b: ToolsPresetInput): boolean;
 /**
  * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
  * 权限模式与工具预设。
  */
-export declare function restrictProjectConfig(project: AmaConfig, currentMode: PermissionMode, label?: string, currentPreset?: ToolsPreset): RestrictResult;
+export declare function restrictProjectConfig(project: AmaConfig, currentMode: PermissionMode, label?: string, currentPreset?: ToolsPresetInput, currentMaxFileBytes?: number, currentPlanBash?: PlanBashMode): RestrictResult;
 /** 命令行对配置的覆盖（只含与 config 同名的那部分参数）。 */
 export interface CliConfigOverrides {
     thinkingLevel?: ModelThinkingLevel | undefined;
@@ -45,7 +48,7 @@ export interface CliConfigOverrides {
     tuiMode?: "regular" | undefined;
     skillDirs?: readonly string[] | undefined;
     /** `--tools-preset`。 */
-    toolsPreset?: ToolsPreset | undefined;
+    toolsPreset?: ToolsPresetInput | undefined;
     /** `--codemode`。 */
     codemode?: CodemodeMode | undefined;
 }