@armadra/agent 0.2.1 → 0.4.0

package/dist/config/init.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 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 与测试不走这里。
+ */
+import { type AmaConfig } from "./types.js";
+export declare const NO_INIT_ENV = "AMA_NO_INIT";
+/** 最小 config.json：只有 `$schema`、`version` 与空 `providers`（缺省值见 `ama config show`）。 */
+export declare function minimalConfig(): AmaConfig & {
+    $schema: string;
+};
+export type InitStatus = "created" | "exists" | "updated" | "unchanged" | "overwritten";
+export interface InitResult {
+    dir: string;
+    dirCreated: boolean;
+    files: {
+        path: string;
+        status: InitStatus;
+    }[];
+}
+/** 建目录并补齐缺失文件；已有的 config.json 不覆盖（`force` 时备份为 .bak 再重写）。 */
+export declare function initConfigDir(dir: string, options?: {
+    force?: boolean;
+}): InitResult;
+/** CLI 启动时：配置目录不存在就静默初始化；返回是否初始化了。失败不影响启动。 */
+export declare function autoInitConfigDir(dir: string, env: Readonly<Record<string, string | undefined>>): boolean;
+/** init 之后的下一步（配 key / 接中转站 / 自检）。 */
+export declare const INIT_NEXT_STEPS: string[];
+export declare function describeInit(result: InitResult): string;

package/dist/config/init.js

@@ -0,0 +1,99 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 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 与测试不走这里。
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+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：只有 `$schema`、`version` 与空 `providers`（缺省值见 `ama config show`）。 */
+export function minimalConfig() {
+    return {
+        $schema: `./${CONFIG_SCHEMA_FILE}`,
+        version: CONFIG_FILE_VERSION,
+        providers: {},
+    };
+}
+function writeAtomic(path, text, mode) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode });
+    renameSync(tmp, path);
+}
+/** 建目录并补齐缺失文件；已有的 config.json 不覆盖（`force` 时备份为 .bak 再重写）。 */
+export function initConfigDir(dir, options = {}) {
+    const dirCreated = !existsSync(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (dirCreated && process.platform !== "win32")
+        chmodSync(dir, 0o700);
+    const files = [];
+    const config = join(dir, CONFIG_FILE);
+    const text = `${JSON.stringify(minimalConfig(), null, 2)}\n`;
+    if (!existsSync(config)) {
+        writeAtomic(config, text, 0o644);
+        files.push({ path: config, status: "created" });
+    }
+    else if (options.force) {
+        copyFileSync(config, `${config}.bak`);
+        writeAtomic(config, text, 0o644);
+        files.push({ path: config, status: "overwritten" });
+    }
+    else
+        files.push({ path: config, status: "exists" });
+    const schema = join(dir, CONFIG_SCHEMA_FILE);
+    const schemaText = configSchemaText();
+    if (!existsSync(schema)) {
+        writeAtomic(schema, schemaText, 0o644);
+        files.push({ path: schema, status: "created" });
+    }
+    else if (readFileSync(schema, "utf8") !== schemaText) {
+        writeAtomic(schema, schemaText, 0o644);
+        files.push({ path: schema, status: "updated" });
+    }
+    else
+        files.push({ path: schema, status: "unchanged" });
+    const auth = join(dir, AUTH_FILE);
+    if (existsSync(auth))
+        files.push({ path: auth, status: "exists" });
+    return { dir, dirCreated, files };
+}
+/** CLI 启动时：配置目录不存在就静默初始化；返回是否初始化了。失败不影响启动。 */
+export function autoInitConfigDir(dir, env) {
+    if (env[NO_INIT_ENV] === "1" || existsSync(dir))
+        return false;
+    try {
+        initConfigDir(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const STATUS_TEXT = {
+    created: "已创建",
+    exists: "已存在，未改动",
+    updated: "已更新为当前版本",
+    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)
+        lines.push(`  ${file.path}  ${STATUS_TEXT[file.status]}`);
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
+ * （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";
+export declare const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
+/** 生成 config.json 的 JSON Schema。 */
+export declare function buildConfigJsonSchema(): Schema;
+/** 写进文件的文本（2 空格缩进 + 换行结尾）。 */
+export declare function configSchemaText(): string;
+export {};

package/dist/config/json-schema.js

@@ -0,0 +1,215 @@
+/**
+ * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
+ * （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_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 = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+function object(properties, extra = {}) {
+    return { type: "object", properties, additionalProperties: false, ...extra };
+}
+const str = (description) => ({
+    type: "string",
+    ...(description ? { description } : {}),
+});
+const bool = (description) => ({
+    type: "boolean",
+    ...(description ? { description } : {}),
+});
+const num = (minimum, maximum, description) => ({
+    type: "number",
+    ...(minimum !== undefined ? { minimum } : {}),
+    ...(maximum !== undefined ? { maximum } : {}),
+    ...(description ? { description } : {}),
+});
+const strings = { type: "array", items: { type: "string" } };
+const stringRecord = { type: "object", additionalProperties: { type: "string" } };
+const oneOf = (values, description) => ({
+    type: "string",
+    enum: [...values],
+    ...(description ? { description } : {}),
+});
+/** api 只查是字符串（与 validateConfig 一致），enum 给编辑器补全。 */
+const api = {
+    type: "string",
+    description: "协议",
+    examples: KNOWN_APIS,
+    anyOf: [{ enum: KNOWN_APIS }, { type: "string" }],
+};
+const compat = {
+    type: "object",
+    description: "协议兼容开关（docs/providers.md「compat」）",
+    properties: {
+        sendPromptCacheKey: bool(),
+        sendSessionAffinityHeaders: bool(),
+        supportsLongCacheRetention: bool(),
+        supportsExplicitPromptCacheMode: bool(),
+        cacheReporting: oneOf(["auto", "silent", "reported"]),
+    },
+};
+function model(description) {
+    return {
+        type: "object",
+        description,
+        required: ["id"],
+        properties: {
+            id: str("模型 id（发给上游的名字）"),
+            name: str(),
+            api,
+            baseUrl: str("覆盖渠道 / 供应商的地址"),
+            contextWindow: num(1, undefined, "上下文 token；缺省从 models.dev 补，匹配不到不猜"),
+            maxTokens: num(1, undefined, "单次输出上限；缺省 min(models.dev, 64k) 或 8192"),
+            reasoning: bool(),
+            input: {
+                type: "array",
+                items: { enum: ["text", "image"] },
+                description: '["text"] 或 ["text", "image"]（收图片）',
+            },
+            channels: { ...strings, description: "挂载的渠道，第一个是首选" },
+            modelsDev: {
+                description: 'models.dev 条目 "provider/model"；false 关闭补全',
+                anyOf: [{ type: "string", pattern: "^[^/]+/.+$" }, { const: false }],
+            },
+            headers: stringRecord,
+            compat,
+            promptCache: object({ short: num(), long: num(), minTokens: num() }),
+            cost: { type: "object", description: "$/M token" },
+            thinkingLevelMap: { type: "object" },
+            samplingParams: { type: "object" },
+        },
+    };
+}
+const channel = object({
+    api,
+    baseUrl: str("接口地址"),
+    apiKey: str("$ENV / ${ENV} / !command / 字面量；缺省用供应商的 key"),
+    authHeader: { type: "object" },
+    headers: stringRecord,
+    compat,
+}, { required: ["api", "baseUrl"] });
+const provider = object({
+    name: str(),
+    api,
+    baseUrl: str(),
+    apiKey: str("$ENV / ${ENV} / !command / 字面量"),
+    envKeys: strings,
+    authHeader: { type: "object" },
+    headers: stringRecord,
+    compat,
+    requiresApiKey: bool(),
+    channels: {
+        type: "object",
+        description: "渠道：一个供应商下的多种接口",
+        minProperties: 1,
+        propertyNames: { pattern: CHANNEL_NAME_PATTERN.source },
+        additionalProperties: channel,
+    },
+    defaultChannel: str("首选渠道；缺省 channels 的第一个"),
+    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,
+        title: "ama config.json",
+        ...object({
+            $schema: str(),
+            version: { const: 1 },
+            defaultModel: str("provider/model 或 provider/model@channel"),
+            thinkingLevel: oneOf(THINKING_LEVELS),
+            providers: { type: "object", additionalProperties: provider },
+            permission: object({
+                mode: oneOf(PERMISSION_MODES_STRICT_FIRST),
+                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({
+                enabled: bool(),
+                maxRetries: num(0, 100),
+                baseDelayMs: num(0),
+                maxDelayMs: num(0),
+            }),
+            tools: object({
+                preset: oneOf(TOOLS_PRESET_INPUTS),
+                default: strings,
+                maxToolResultChars: num(1),
+                bashTimeoutMs: num(1),
+                disabled: strings,
+            }),
+            codemode: object({
+                mode: oneOf(CODEMODE_MODES),
+                inlineBudget: num(0),
+                requireStrict: bool(),
+            }),
+            hooks: object({ timeoutMs: num(1, HOOK_TIMEOUT_MAX_MS) }),
+            ui: object({
+                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({
+                warming: oneOf(WARMING_MODES),
+                retention: oneOf(CACHE_RETENTIONS),
+                minSavingsUsd: num(0),
+                missNotices: bool(),
+                warmSubagents: bool(),
+            }),
+            request: object({ idleTimeoutMs: num(0) }),
+        }),
+        required: ["version"],
+    };
+}
+/** 写进文件的文本（2 空格缩进 + 换行结尾）。 */
+export function configSchemaText() {
+    return `${JSON.stringify(buildConfigJsonSchema(), null, 2)}\n`;
+}

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, } 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 {