@armadra/agent 0.3.0 → 0.4.0

package/dist/config/json-schema.js

@@ -3,11 +3,13 @@
  * （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, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.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 +121,33 @@ const provider = object({
     models: { type: "array", items: model("自定义模型（同 id 整条替换）") },
     modelOverrides: { type: "array", items: model("只改已有模型的元数据") },
 });
+/** 给顶层与各段的键写上 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,6 +163,8 @@ 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) }),
             retry: object({
@@ -145,7 +174,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 +187,14 @@ 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(),
             }),
             skills: object({ dirs: strings }),
             cache: object({
@@ -172,6 +204,7 @@ export function buildConfigJsonSchema() {
                 missNotices: bool(),
                 warmSubagents: bool(),
             }),
+            request: object({ idleTimeoutMs: num(0) }),
         }),
         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,105 @@
+/**
+ * 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 } 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 },
+};
+/** 全部有固定缺省值的键（展示用；运行时仍以 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": "自动检测",
+});
+/** 键路径 → 说明（段落本身也有一条）。 */
+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",
+    retry: "请求失败重试",
+    "retry.enabled": "可重试的错误（限流、服务端错误、连接中断等）自动重试",
+    "retry.maxRetries": "最多重试次数",
+    "retry.baseDelayMs": "首次重试等待（毫秒，指数退避；有 Retry-After 时按它）",
+    "retry.maxDelayMs": "单次等待上限（毫秒）",
+    tools: "内置工具",
+    "tools.preset": "工具预设：default（六个工具，Node ≥ 25 时另加 codemode）、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 静止，只在秒数变化时重绘",
+    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）也保温",
+});
+/** 叶子路径（段落不算）。 */
+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,15 @@
  * 配置层级合并（设计 §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`（只能更严）、
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
+ *   auto / full-auto）、
  *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
- *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPreset } from "./types.js";
+import type { AmaConfig, CodemodeMode, 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 +29,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): RestrictResult;
 /** 命令行对配置的覆盖（只含与 config 同名的那部分参数）。 */
 export interface CliConfigOverrides {
     thinkingLevel?: ModelThinkingLevel | undefined;
@@ -45,7 +46,7 @@ export interface CliConfigOverrides {
     tuiMode?: "regular" | undefined;
     skillDirs?: readonly string[] | undefined;
     /** `--tools-preset`。 */
-    toolsPreset?: ToolsPreset | undefined;
+    toolsPreset?: ToolsPresetInput | undefined;
     /** `--codemode`。 */
     codemode?: CodemodeMode | undefined;
 }

package/dist/config/merge.js

@@ -2,14 +2,15 @@
  * 配置层级合并（设计 §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`（只能更严）、
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
+ *   auto / full-auto）、
  *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
- *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import { CONFIG_FILE_VERSION, TOOLS_PRESETS_STRICT_FIRST } from "./types.js";
+import { CONFIG_FILE_VERSION, TOOLS_PRESETS_STRICT_FIRST, canonicalPreset } from "./types.js";
 import { isAtLeastAsStrict } from "../permissions/rules.js";
 export const DEFAULT_CONFIG = Object.freeze({
     version: CONFIG_FILE_VERSION,
@@ -43,6 +44,7 @@ const RULE_SOURCE = {
 const ACCUMULATING = new Set([
     "permission.allow",
     "permission.deny",
+    "permission.autoSafeCommands",
     "tools.disabled",
     "skills.dirs",
 ]);
@@ -78,11 +80,15 @@ export function mergeConfig(base, over) {
         return structuredCloneSafe(base);
     const merged = mergeValue(base, over, "");
     merged.version = CONFIG_FILE_VERSION;
+    // 别名（`codemode`）在合并后折成规范名：下游只见规范名。
+    if (merged.tools?.preset !== undefined)
+        merged.tools.preset = canonicalPreset(merged.tools.preset);
     return merged;
 }
-/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode 最宽）。 */
+/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode-only 最宽；别名按规范名比）。 */
 export function isPresetStricterOrEqual(a, b) {
-    return TOOLS_PRESETS_STRICT_FIRST.indexOf(a) <= TOOLS_PRESETS_STRICT_FIRST.indexOf(b);
+    return (TOOLS_PRESETS_STRICT_FIRST.indexOf(canonicalPreset(a)) <=
+        TOOLS_PRESETS_STRICT_FIRST.indexOf(canonicalPreset(b)));
 }
 /**
  * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
@@ -155,7 +161,16 @@ function restrictPermission(permission, currentMode, label, warnings) {
     if (permission.builtinDeny !== undefined) {
         warnings.push(`${label}: 项目级不能改内置 deny 表，忽略 permission.builtinDeny`);
     }
-    if (permission.mode !== undefined) {
+    if (permission.autoModel !== undefined) {
+        warnings.push(`${label}: 项目级不能设 permission.autoModel，已忽略`);
+    }
+    if (permission.autoSafeCommands !== undefined && permission.autoSafeCommands.length > 0) {
+        warnings.push(`${label}: 项目级不能追加 permission.autoSafeCommands（放宽），已忽略`);
+    }
+    if (permission.mode === "auto" || permission.mode === "full-auto") {
+        warnings.push(`${label}: 项目级不能把权限模式设为 ${permission.mode}（放宽，只能在用户级配置、profile 或命令行设），已忽略`);
+    }
+    else if (permission.mode !== undefined) {
         if (isAtLeastAsStrict(permission.mode, currentMode)) {
             result.mode = permission.mode;
         }

package/dist/config/schema.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AmaConfig, AuthFile, ProfileFile, TrustFile } from "./types.js";
 import type { HookConfig } from "../hooks/types.js";
-export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
+export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, ToolsPresetInput, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
 export type { HookConfig } from "../hooks/types.js";
 export interface Diagnostic {

package/dist/config/schema.js

@@ -8,7 +8,7 @@
 import { HOOK_EVENTS } from "../hooks/types.js";
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
-import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESETS_STRICT_FIRST, } from "./types.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 export const HOOK_TIMEOUT_MAX_MS = 600_000;
@@ -116,6 +116,7 @@ const CONFIG_KEYS = [
     "ui",
     "skills",
     "cache",
+    "request",
     "$schema",
 ];
 const PROVIDER_KEYS = [
@@ -278,10 +279,13 @@ export function validateConfig(value) {
             checkProvider(c, provider, join("providers", id));
         }
     }
-    checkSection(c, value, "permission", ["mode", "allow", "deny", "builtinDeny"], (s, p) => {
+    const permissionKeys = ["mode", "allow", "deny", "builtinDeny", "autoModel", "autoSafeCommands"];
+    checkSection(c, value, "permission", permissionKeys, (s, p) => {
         c.oneOf(s, "mode", p, PERMISSION_MODES_STRICT_FIRST);
         c.stringArray(s, "allow", p);
         c.stringArray(s, "deny", p);
+        c.string(s, "autoModel", p);
+        c.stringArray(s, "autoSafeCommands", p);
         const builtinDeny = s["builtinDeny"];
         if (builtinDeny !== undefined &&
             typeof builtinDeny !== "boolean" &&
@@ -301,7 +305,7 @@ export function validateConfig(value) {
         c.number(s, "maxDelayMs", p);
     });
     checkSection(c, value, "tools", ["preset", "default", "maxToolResultChars", "bashTimeoutMs", "disabled"], (s, p) => {
-        c.oneOf(s, "preset", p, TOOLS_PRESETS_STRICT_FIRST);
+        c.oneOf(s, "preset", p, TOOLS_PRESET_INPUTS);
         c.stringArray(s, "default", p);
         c.number(s, "maxToolResultChars", p, 1);
         c.number(s, "bashTimeoutMs", p, 1);
@@ -315,14 +319,29 @@ export function validateConfig(value) {
     checkSection(c, value, "hooks", ["timeoutMs"], (s, p) => {
         c.number(s, "timeoutMs", p, 1, HOOK_TIMEOUT_MAX_MS);
     });
-    checkSection(c, value, "ui", ["theme", "markdown", "showThinking", "tuiMode", "quietStartup"], (s, p) => {
-        c.oneOf(s, "theme", p, ["dark", "light"]);
+    checkSection(c, value, "ui", [
+        "theme",
+        "markdown",
+        "showThinking",
+        "tuiMode",
+        "quietStartup",
+        "ascii",
+        "compact",
+        "animation",
+    ], (s, p) => {
+        c.oneOf(s, "theme", p, ["dark", "light", "auto"]);
         c.boolean(s, "markdown", p);
         c.oneOf(s, "showThinking", p, ["full", "collapsed", "hidden"]);
         c.oneOf(s, "tuiMode", p, ["regular"]);
         c.oneOf(s, "quietStartup", p, ["normal", "header", "silent"]);
+        c.boolean(s, "ascii", p);
+        c.boolean(s, "compact", p);
+        c.boolean(s, "animation", p);
     });
     checkSection(c, value, "skills", ["dirs"], (s, p) => c.stringArray(s, "dirs", p));
+    checkSection(c, value, "request", ["idleTimeoutMs"], (s, p) => {
+        c.number(s, "idleTimeoutMs", p, 0);
+    });
     checkSection(c, value, "cache", ["warming", "retention", "minSavingsUsd", "missNotices", "warmSubagents"], (s, p) => {
         c.oneOf(s, "warming", p, WARMING_MODES);
         c.oneOf(s, "retention", p, CACHE_RETENTIONS);

package/dist/config/types.d.ts

@@ -65,6 +65,10 @@ export interface PermissionConfig {
      * 数组 = 要移除的规则原文。放宽项，只认用户级 / profile，项目级忽略并 warning。
      */
     builtinDeny?: boolean | string[];
+    /** auto 模式分类器的模型（`provider/model`）；缺省 = 当前会话模型。放宽项，项目级忽略。 */
+    autoModel?: string;
+    /** auto 模式安全名单追加（词前缀或含 `*` 的通配）。放宽项，项目级忽略；各层累加。 */
+    autoSafeCommands?: string[];
 }
 export interface CompactionConfig {
     enabled?: boolean;
@@ -77,13 +81,22 @@ export interface RetryConfig {
     baseDelayMs?: number;
     maxDelayMs?: number;
 }
-/** 工具预设（设计 §5.6）：模型直接看到的工具集合。 */
-export type ToolsPreset = "default" | "minimal" | "codemode" | "coordinator";
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 工具预设（设计 §5.6）：模型直接看到的工具集合（规范名）。 */
+export type ToolsPreset = "default" | "minimal" | "codemode-only" | "coordinator";
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export declare const TOOLS_PRESET_ALIASES: Readonly<Record<string, ToolsPreset>>;
+/** 配置文件、命令行、RPC、SDK 接受的写法：规范名或别名。 */
+export type ToolsPresetInput = ToolsPreset | "codemode";
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export declare const TOOLS_PRESETS_STRICT_FIRST: readonly ToolsPreset[];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export declare const TOOLS_PRESET_INPUTS: readonly ToolsPresetInput[];
+/** 规范名；未知名字原样返回（校验由 schema 负责）。 */
+export declare function canonicalPreset(name: ToolsPresetInput): ToolsPreset;
+export declare function canonicalPreset(name: string | undefined): ToolsPreset | undefined;
 export interface ToolsConfig {
-    /** 缺省 `default`；命令行 `--tools-preset`。 */
-    preset?: ToolsPreset;
+    /** 缺省 `default`；命令行 `--tools-preset`；`codemode` 是 `codemode-only` 的别名。 */
+    preset?: ToolsPresetInput;
     /**
      * 在预设上微调（设计 §5.6）：`+name` 加、`-name` 去；不带前缀的名字整组替换预设的内置工具。
      * 只认用户级 / profile（项目级忽略并 warning）。
@@ -108,12 +121,19 @@ export interface HooksSettings {
     timeoutMs?: number;
 }
 export interface UiConfig {
-    theme?: "dark" | "light";
+    /** auto 按 `COLORFGBG` / `TERM_PROGRAM` 猜（不发查询序列），猜不出用 dark。 */
+    theme?: "dark" | "light" | "auto";
     markdown?: boolean;
     showThinking?: "full" | "collapsed" | "hidden";
     /** 第一期只有 regular（§12.10）。 */
     tuiMode?: "regular";
     quietStartup?: "normal" | "header" | "silent";
+    /** ASCII 字形（`AMA_ASCII=1` 等价）；缺省按区域设置 / TERM 自动检测。 */
+    ascii?: boolean;
+    /** 消息区块间不空行、启动头无框，缺省 false。 */
+    compact?: boolean;
+    /** false：运行中 spinner 固定为 `·`，缺省 true。 */
+    animation?: boolean;
 }
 export interface SkillsConfig {
     dirs?: string[];
@@ -136,6 +156,13 @@ export interface CacheConfig {
     warmSubagents?: boolean;
 }
 export declare const DEFAULT_CACHE_CONFIG: Readonly<Required<CacheConfig>>;
+/**
+ * 模型请求（W4-C）。只认用户级 / profile；环境变量 `AMA_IDLE_TIMEOUT_MS` 覆盖 `idleTimeoutMs`。
+ */
+export interface RequestConfig {
+    /** 等响应头与流中两块数据之间的最长间隔（毫秒），收到任何字节即重新计时；缺省 300 000，0 关闭。 */
+    idleTimeoutMs?: number;
+}
 /** config.json（用户级 / 项目级 / profile.config 同形状；项目级只接受受限字段，§10.2）。 */
 export interface AmaConfig {
     version: typeof CONFIG_FILE_VERSION;
@@ -152,6 +179,7 @@ export interface AmaConfig {
     ui?: UiConfig;
     skills?: SkillsConfig;
     cache?: CacheConfig;
+    request?: RequestConfig;
 }
 /** auth.json（0600）。 */
 export interface AuthFile {

package/dist/config/types.js

@@ -11,13 +11,29 @@
 export const CONFIG_FILE_VERSION = 1;
 /** 渠道名：不含 `/` 与 `@`（`provider/model@channel`）。 */
 export const CHANNEL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export const TOOLS_PRESET_ALIASES = Object.freeze({
+    codemode: "codemode-only",
+});
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export const TOOLS_PRESETS_STRICT_FIRST = [
     "coordinator",
     "minimal",
     "default",
+    "codemode-only",
+];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export const TOOLS_PRESET_INPUTS = [
+    ...TOOLS_PRESETS_STRICT_FIRST,
     "codemode",
 ];
+export function canonicalPreset(name) {
+    if (name === undefined)
+        return undefined;
+    return Object.hasOwn(TOOLS_PRESET_ALIASES, name)
+        ? TOOLS_PRESET_ALIASES[name]
+        : name;
+}
 export const CODEMODE_MODES = ["off", "on", "only"];
 export const CACHE_RETENTIONS = ["none", "short", "long"];
 export const DEFAULT_CACHE_CONFIG = Object.freeze({

package/dist/modes/commands-core.js

@@ -13,7 +13,7 @@ import { AgentSessionImpl } from "../agent/session.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
 import { THINKING_LEVELS } from "../ai/thinking.js";
 import { AmaError } from "../errors.js";
-import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { PERMISSION_MODE_ORDER, parsePermissionMode, permissionModeLabel, } from "../permissions/modes.js";
 import { describeCache, describeFingerprint, describeSession } from "./session-report.js";
 export { describeSession } from "./session-report.js";
 export const BUILTIN_COMMANDS = [
@@ -133,11 +133,12 @@ export async function runSlashCommand(line, ctx) {
         case "permission": {
             if (args === "")
                 return { kind: "pick", what: "permission" };
-            if (!PERMISSION_MODES_STRICT_FIRST.includes(args)) {
-                throw new AmaError("invalid_arguments", `权限模式应为 ${PERMISSION_MODES_STRICT_FIRST.join(" | ")}`);
+            const mode = parsePermissionMode(args);
+            if (mode === undefined) {
+                throw new AmaError("invalid_arguments", `权限模式应为 ${PERMISSION_MODE_ORDER.join(" | ")}（也可写显示名，如 "Accept edits"）`);
             }
-            session.setPermissionMode(args);
-            return { kind: "handled", message: `权限模式：${args}` };
+            session.setPermissionMode(mode);
+            return { kind: "handled", message: `权限模式：${permissionModeLabel(mode)}` };
         }
         case "tools": {
             if (args !== "")

package/dist/modes/interactive/approval-dialog.d.ts

@@ -7,7 +7,11 @@
  * - 执行前预览（W3-B9a-2，`request.preview`）：输入摘要之后列出会碰到的路径与规模，danger 红、
  *   warn 黄、info 暗色；`other` 类预览与输入摘要重复，不显示；
  * - 原因：mode（当前权限模式需要确认）/ dangerous / hook + Hook 给的文本；
- * - 按键：`y` 允许、`n` / Esc / Ctrl+C 拒绝、`a` 本会话允许同类；
+ * - 选项（终端界面视觉设计 v1 §3.11）：编号列表 `1. 允许  y` / `2. 本会话允许同类  a` / `3. 拒绝  n Esc`，
+ *   选中行 `›` + selection 底色；缺省选中：危险命令 → 拒绝，其余 → 允许。按键 `y / a / n / Esc / Ctrl+C /
+ *   1 2 3 / ↑↓ Enter / v` 都有效；
+ * - 标题按原因：需要确认 / 危险命令 / Hook 要求确认（子 Agent 发起前缀 `[task] `）；边框颜色随预览严重度
+ *   （danger error、warn warning）；宽 < 56 时紧凑：工具名单独一行、去掉空行、按键提示缩短；
  * - 超时与中断：broker 链在超时（缺省 10 分钟）或运行被中断时 abort `signal`，对话框关闭并返回
  *   undefined（链按 deny 处理），消息区留一行说明。
  *
@@ -29,13 +33,24 @@ export interface ApprovalHost {
     /** 结果说明（消息区一行）。 */
     report?(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): void;
 }
-/** 对话框正文（不含按键行）。 */
-export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: {
+export interface DescribeOptions {
     cwd?: string;
     permissionMode?: string;
     expanded?: boolean;
-}): string[];
-export declare const APPROVAL_KEYS_HINT = "[y] \u5141\u8BB8  [n] \u62D2\u7EDD  [a] \u672C\u4F1A\u8BDD\u5141\u8BB8\u540C\u7C7B  [v] \u5B8C\u6574\u8F93\u5165";
+    /** 紧凑（窄屏）：首行只放工具名（原因已在标题上）。 */
+    compact?: boolean;
+}
+/** 原因 → 标题文字（子 Agent 发起加 `[task] `）。 */
+export declare function approvalTitle(request: ApprovalRequest): string;
+/** 对话框正文（不含选项与按键行）。 */
+export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: DescribeOptions): string[];
+interface ApprovalOption {
+    decision: ApprovalDecision;
+    label: string;
+    /** 右侧按键提示。 */
+    keys: string;
+}
+export declare const APPROVAL_OPTIONS: readonly ApprovalOption[];
 /** UI broker：每个请求开一个底部覆盖层，等用户按键或 signal abort。 */
 export declare class ApprovalDialogBroker implements ApprovalBroker {
     private readonly host;
@@ -46,3 +61,4 @@ export declare class ApprovalDialogBroker implements ApprovalBroker {
 }
 /** 结果的一行说明（消息区）。 */
 export declare function approvalOutcomeText(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): string;
+export {};