@armadra/agent 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,14 @@
+/**
+ * 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 的正反例守住。
+ */
+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,182 @@
+/**
+ * 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 的正反例守住。
+ */
+import { WARMING_MODES } from "../ai/cache/types.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.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";
+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("只改已有模型的元数据") },
+});
+/** 生成 config.json 的 JSON Schema。 */
+export function buildConfigJsonSchema() {
+    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] },
+            }),
+            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_PRESETS_STRICT_FIRST),
+                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"]),
+                markdown: bool(),
+                showThinking: oneOf(["full", "collapsed", "hidden"]),
+                tuiMode: oneOf(["regular"]),
+                quietStartup: oneOf(["normal", "header", "silent"]),
+            }),
+            skills: object({ dirs: strings }),
+            cache: object({
+                warming: oneOf(WARMING_MODES),
+                retention: oneOf(CACHE_RETENTIONS),
+                minSavingsUsd: num(0),
+                missNotices: bool(),
+                warmSubagents: bool(),
+            }),
+        }),
+        required: ["version"],
+    };
+}
+/** 写进文件的文本（2 空格缩进 + 换行结尾）。 */
+export function configSchemaText() {
+    return `${JSON.stringify(buildConfigJsonSchema(), null, 2)}\n`;
+}

package/dist/config/load.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 读配置文件 + 校验 + 诊断（设计 §11.1 第 6 / 9 / 10 步）。[B5]
+ *
+ * JSON 语法错误给出行列号；字段错误给出字段路径。任何 error 级诊断都抛
+ * `StartupError{exitCode: 3}`（code 依文件种类为 config_invalid / profile_invalid），
+ * warning 级诊断（未知字段）原样返回给调用方汇入 Runtime.warnings。
+ */
+import { type Diagnostic } from "./schema.js";
+import type { AmaConfig, AuthFile, ProfileFile, TrustFile } from "./types.js";
+import type { HookConfig } from "../hooks/types.js";
+export type ConfigFileKind = "config" | "auth" | "profile" | "hooks" | "trust";
+interface KindMap {
+    config: AmaConfig;
+    auth: AuthFile;
+    profile: ProfileFile;
+    hooks: HookConfig;
+    trust: TrustFile;
+}
+export interface LoadedFile<T> {
+    path: string;
+    value: T;
+    /** 已格式化的 warning（`<path>: <field>: <message>`）。 */
+    warnings: string[];
+}
+/** 字符偏移 → 1 起的行列。 */
+export declare function lineColumnAt(text: string, offset: number): {
+    line: number;
+    column: number;
+};
+/** 解析 JSON；语法错误抛带行列号的 Error。容忍 UTF-8 BOM。 */
+export declare function parseJsonText(text: string): unknown;
+export declare function formatDiagnostic(path: string, d: Diagnostic): string;
+export interface ReadOptions {
+    /** 文件不存在时报错（缺省 false：返回 undefined）。 */
+    required?: boolean;
+}
+/** 读并校验一个配置文件；不存在且非必需时返回 undefined。 */
+export declare function loadConfigFile<K extends ConfigFileKind>(kind: K, path: string, options?: ReadOptions): LoadedFile<KindMap[K]> | undefined;
+/** 读失败不抛：返回诊断（doctor 用）。 */
+export declare function probeConfigFile(kind: ConfigFileKind, path: string): {
+    exists: boolean;
+    ok: boolean;
+    messages: string[];
+};
+export {};

package/dist/config/load.js

@@ -0,0 +1,97 @@
+/**
+ * 读配置文件 + 校验 + 诊断（设计 §11.1 第 6 / 9 / 10 步）。[B5]
+ *
+ * JSON 语法错误给出行列号；字段错误给出字段路径。任何 error 级诊断都抛
+ * `StartupError{exitCode: 3}`（code 依文件种类为 config_invalid / profile_invalid），
+ * warning 级诊断（未知字段）原样返回给调用方汇入 Runtime.warnings。
+ */
+import { readFileSync } from "node:fs";
+import { StartupError } from "../errors.js";
+import { hasErrors, validateAuthFile, validateConfig, validateHookConfig, validateProfile, validateTrustFile, } from "./schema.js";
+const EXIT_CONFIG = 3;
+const VALIDATORS = {
+    config: validateConfig,
+    auth: validateAuthFile,
+    profile: validateProfile,
+    hooks: validateHookConfig,
+    trust: validateTrustFile,
+};
+/** 字符偏移 → 1 起的行列。 */
+export function lineColumnAt(text, offset) {
+    const before = text.slice(0, Math.max(0, Math.min(offset, text.length)));
+    const lines = before.split("\n");
+    return { line: lines.length, column: (lines[lines.length - 1]?.length ?? 0) + 1 };
+}
+/** 解析 JSON；语法错误抛带行列号的 Error。容忍 UTF-8 BOM。 */
+export function parseJsonText(text) {
+    const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const lineCol = /line (\d+) column (\d+)/.exec(message);
+        if (lineCol !== null)
+            throw new Error(`JSON 语法错误（第 ${lineCol[1]} 行第 ${lineCol[2]} 列）：${message}`);
+        const position = /position (\d+)/.exec(message);
+        if (position?.[1] !== undefined) {
+            const { line, column } = lineColumnAt(source, Number(position[1]));
+            throw new Error(`JSON 语法错误（第 ${line} 行第 ${column} 列）：${message}`);
+        }
+        if (source.trim() === "")
+            throw new Error("JSON 语法错误：文件为空");
+        const end = lineColumnAt(source, source.length);
+        throw new Error(`JSON 语法错误（第 ${end.line} 行第 ${end.column} 列附近）：${message}`);
+    }
+}
+export function formatDiagnostic(path, d) {
+    return `${path}: ${d.path === "" ? "" : `${d.path}: `}${d.message}`;
+}
+function failure(kind, message, detail) {
+    return new StartupError(kind === "profile" ? "profile_invalid" : "config_invalid", message, EXIT_CONFIG, detail === undefined ? {} : { detail });
+}
+/** 读并校验一个配置文件；不存在且非必需时返回 undefined。 */
+export function loadConfigFile(kind, path, options = {}) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" && options.required !== true)
+            return undefined;
+        const reason = code === "ENOENT" ? "文件不存在" : error.message;
+        throw failure(kind, `${path}: ${reason}`, { path });
+    }
+    let value;
+    try {
+        value = parseJsonText(text);
+    }
+    catch (error) {
+        throw failure(kind, `${path}: ${error.message}`, { path });
+    }
+    const diagnostics = VALIDATORS[kind](value);
+    if (hasErrors(diagnostics)) {
+        const lines = diagnostics
+            .filter((d) => d.severity === "error")
+            .map((d) => formatDiagnostic(path, d));
+        throw failure(kind, `配置文件无效：\n  ${lines.join("\n  ")}`, { path, diagnostics });
+    }
+    return {
+        path,
+        value: value,
+        warnings: diagnostics.map((d) => formatDiagnostic(path, d)),
+    };
+}
+/** 读失败不抛：返回诊断（doctor 用）。 */
+export function probeConfigFile(kind, path) {
+    try {
+        const loaded = loadConfigFile(kind, path);
+        if (loaded === undefined)
+            return { exists: false, ok: true, messages: [] };
+        return { exists: true, ok: true, messages: loaded.warnings };
+    }
+    catch (error) {
+        return { exists: true, ok: false, messages: [error.message] };
+    }
+}

package/dist/config/merge.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 配置层级合并（设计 §7.2、§10.2）。[B5]
+ *
+ * 顺序：内置缺省 ← 用户级 ← profile.config ← 项目级（受限字段，只能收紧）← 命令行。
+ * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny`、
+ *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严）、
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
+ *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
+ */
+import type { AmaConfig, CodemodeMode, ToolsPreset } 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>;
+/** 嵌入宿主（有 profile）时的缺省覆盖（§12.10）。 */
+export declare const PROFILE_DEFAULTS: Readonly<Partial<AmaConfig>>;
+export type ConfigLayerName = "default" | "user" | "profile" | "project" | "cli";
+export interface PermissionRuleSpec {
+    effect: "allow" | "deny";
+    raw: string;
+    source: RuleSource;
+}
+/** 深合并两层配置（不改入参）。 */
+export declare function mergeConfig(base: AmaConfig, over: Partial<AmaConfig> | undefined): AmaConfig;
+export interface RestrictResult {
+    /** 只含被接受的字段。 */
+    accepted: Partial<AmaConfig>;
+    warnings: string[];
+}
+/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode 最宽）。 */
+export declare function isPresetStricterOrEqual(a: ToolsPreset, b: ToolsPreset): boolean;
+/**
+ * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
+ * 权限模式与工具预设。
+ */
+export declare function restrictProjectConfig(project: AmaConfig, currentMode: PermissionMode, label?: string, currentPreset?: ToolsPreset): RestrictResult;
+/** 命令行对配置的覆盖（只含与 config 同名的那部分参数）。 */
+export interface CliConfigOverrides {
+    thinkingLevel?: ModelThinkingLevel | undefined;
+    permissionMode?: PermissionMode | undefined;
+    allow?: readonly string[] | undefined;
+    deny?: readonly string[] | undefined;
+    quietStartup?: "normal" | "header" | "silent" | undefined;
+    tuiMode?: "regular" | undefined;
+    skillDirs?: readonly string[] | undefined;
+    /** `--tools-preset`。 */
+    toolsPreset?: ToolsPreset | undefined;
+    /** `--codemode`。 */
+    codemode?: CodemodeMode | undefined;
+}
+export declare function cliOverridesToConfig(cli: CliConfigOverrides): Partial<AmaConfig>;
+export interface ConfigLayers {
+    user?: AmaConfig | undefined;
+    /** profile.config 指向的文件内容；`hasProfile` 为 true 时还会叠加 PROFILE_DEFAULTS。 */
+    profile?: AmaConfig | undefined;
+    hasProfile?: boolean;
+    project?: AmaConfig | undefined;
+    cli?: CliConfigOverrides | undefined;
+}
+export interface MergeResult {
+    config: AmaConfig;
+    warnings: string[];
+    ruleSpecs: PermissionRuleSpec[];
+    /** 各层是否存在（doctor 显示）。 */
+    layers: ConfigLayerName[];
+}
+/** 第 6 步：缺省 ← 用户级 ← profile。 */
+export declare function mergeBaseLayers(layers: Pick<ConfigLayers, "user" | "profile" | "hasProfile">): MergeResult;
+/** 第 9 步：叠加项目级（受限）与命令行。 */
+export declare function mergeProjectAndCli(base: MergeResult, project: AmaConfig | undefined, cli: CliConfigOverrides | undefined, projectLabel?: string): MergeResult;
+/** 一次合并全部层（SDK / 测试用）。 */
+export declare function mergeConfigLayers(layers: ConfigLayers): MergeResult;

package/dist/config/merge.js

@@ -0,0 +1,248 @@
+/**
+ * 配置层级合并（设计 §7.2、§10.2）。[B5]
+ *
+ * 顺序：内置缺省 ← 用户级 ← profile.config ← 项目级（受限字段，只能收紧）← 命令行。
+ * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny`、
+ *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严）、
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
+ *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
+ */
+import { CONFIG_FILE_VERSION, TOOLS_PRESETS_STRICT_FIRST } from "./types.js";
+import { isAtLeastAsStrict } from "../permissions/rules.js";
+export const DEFAULT_CONFIG = Object.freeze({
+    version: CONFIG_FILE_VERSION,
+    thinkingLevel: "medium",
+    permission: { mode: "default", allow: [], deny: [] },
+    compaction: { enabled: true, reserveTokens: 16_384, keepRecentTokens: 20_000 },
+    retry: { enabled: true, maxRetries: 3, baseDelayMs: 2_000, maxDelayMs: 60_000 },
+    tools: { preset: "default", maxToolResultChars: 30_000, bashTimeoutMs: 120_000, disabled: [] },
+    hooks: { timeoutMs: 60_000 },
+    ui: {
+        theme: "dark",
+        markdown: true,
+        showThinking: "collapsed",
+        tuiMode: "regular",
+        quietStartup: "normal",
+    },
+    skills: { dirs: [] },
+});
+/** 嵌入宿主（有 profile）时的缺省覆盖（§12.10）。 */
+export const PROFILE_DEFAULTS = Object.freeze({
+    ui: { quietStartup: "header" },
+});
+/** 层名 → 规则来源（RuleSource）。 */
+const RULE_SOURCE = {
+    default: "builtin",
+    user: "user",
+    profile: "profile",
+    project: "project",
+    cli: "cli",
+};
+const ACCUMULATING = new Set([
+    "permission.allow",
+    "permission.deny",
+    "tools.disabled",
+    "skills.dirs",
+]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function mergeValue(base, over, path) {
+    if (over === undefined)
+        return structuredCloneSafe(base);
+    if (Array.isArray(over)) {
+        if (ACCUMULATING.has(path) && Array.isArray(base))
+            return unique([...base, ...over]);
+        return [...over];
+    }
+    if (isPlainObject(over)) {
+        const result = isPlainObject(base) ? { ...structuredCloneSafe(base) } : {};
+        for (const [key, value] of Object.entries(over)) {
+            result[key] = mergeValue(result[key], value, path === "" ? key : `${path}.${key}`);
+        }
+        return result;
+    }
+    return over;
+}
+function structuredCloneSafe(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+/** 深合并两层配置（不改入参）。 */
+export function mergeConfig(base, over) {
+    if (over === undefined)
+        return structuredCloneSafe(base);
+    const merged = mergeValue(base, over, "");
+    merged.version = CONFIG_FILE_VERSION;
+    return merged;
+}
+/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode 最宽）。 */
+export function isPresetStricterOrEqual(a, b) {
+    return TOOLS_PRESETS_STRICT_FIRST.indexOf(a) <= TOOLS_PRESETS_STRICT_FIRST.indexOf(b);
+}
+/**
+ * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
+ * 权限模式与工具预设。
+ */
+export function restrictProjectConfig(project, currentMode, label = ".ama/config.json", currentPreset = "default") {
+    const warnings = [];
+    const accepted = {};
+    for (const [key, value] of Object.entries(project)) {
+        if (key === "version" || key === "$schema" || value === undefined)
+            continue;
+        switch (key) {
+            case "compaction":
+                if (project.compaction !== undefined)
+                    accepted.compaction = structuredClone(project.compaction);
+                break;
+            case "ui":
+                if (project.ui !== undefined)
+                    accepted.ui = structuredClone(project.ui);
+                break;
+            case "tools": {
+                const tools = project.tools ?? {};
+                const result = {};
+                for (const sub of Object.keys(tools)) {
+                    if (sub !== "disabled" && sub !== "preset")
+                        warnings.push(`${label}: 项目级只能设 tools.disabled / tools.preset，忽略 tools.${sub}`);
+                }
+                if (tools.disabled !== undefined)
+                    result.disabled = [...tools.disabled];
+                if (tools.preset !== undefined) {
+                    if (isPresetStricterOrEqual(tools.preset, currentPreset))
+                        result.preset = tools.preset;
+                    else
+                        warnings.push(`${label}: 项目级不能放宽工具预设，忽略 tools.preset ${tools.preset}（当前 ${currentPreset}）`);
+                }
+                if (Object.keys(result).length > 0)
+                    accepted.tools = result;
+                break;
+            }
+            case "codemode": {
+                const codemode = project.codemode ?? {};
+                for (const [sub, v] of Object.entries(codemode)) {
+                    if (sub === "mode" && v === "off")
+                        continue;
+                    warnings.push(`${label}: 项目级只接受 codemode.mode "off"，忽略 codemode.${sub}${sub === "mode" ? ` ${String(v)}` : ""}`);
+                }
+                if (codemode.mode === "off")
+                    accepted.codemode = { mode: "off" };
+                break;
+            }
+            case "permission": {
+                const permission = restrictPermission(project.permission ?? {}, currentMode, label, warnings);
+                if (permission !== undefined)
+                    accepted.permission = permission;
+                break;
+            }
+            default:
+                warnings.push(`${label}: 项目级不能设 ${key}，已忽略`);
+        }
+    }
+    return { accepted, warnings };
+}
+function restrictPermission(permission, currentMode, label, warnings) {
+    const result = {};
+    if (permission.allow !== undefined && permission.allow.length > 0) {
+        warnings.push(`${label}: 项目级不能加 allow 规则，忽略 ${permission.allow.join(", ")}`);
+    }
+    if (permission.deny !== undefined && permission.deny.length > 0)
+        result.deny = [...permission.deny];
+    if (permission.builtinDeny !== undefined) {
+        warnings.push(`${label}: 项目级不能改内置 deny 表，忽略 permission.builtinDeny`);
+    }
+    if (permission.mode !== undefined) {
+        if (isAtLeastAsStrict(permission.mode, currentMode)) {
+            result.mode = permission.mode;
+        }
+        else {
+            warnings.push(`${label}: 项目级只能收紧权限模式，忽略 ${permission.mode}（当前 ${currentMode}）`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+export function cliOverridesToConfig(cli) {
+    const out = {};
+    if (cli.thinkingLevel !== undefined)
+        out.thinkingLevel = cli.thinkingLevel;
+    const permission = {};
+    if (cli.permissionMode !== undefined)
+        permission.mode = cli.permissionMode;
+    if (cli.allow !== undefined && cli.allow.length > 0)
+        permission.allow = [...cli.allow];
+    if (cli.deny !== undefined && cli.deny.length > 0)
+        permission.deny = [...cli.deny];
+    if (Object.keys(permission).length > 0)
+        out.permission = permission;
+    const ui = {};
+    if (cli.quietStartup !== undefined)
+        ui.quietStartup = cli.quietStartup;
+    if (cli.tuiMode !== undefined)
+        ui.tuiMode = cli.tuiMode;
+    if (Object.keys(ui).length > 0)
+        out.ui = ui;
+    if (cli.toolsPreset !== undefined)
+        out.tools = { preset: cli.toolsPreset };
+    if (cli.codemode !== undefined)
+        out.codemode = { mode: cli.codemode };
+    return out;
+}
+function collectRules(layer, permission) {
+    const source = RULE_SOURCE[layer];
+    const specs = [];
+    for (const raw of permission?.allow ?? [])
+        specs.push({ effect: "allow", raw, source });
+    for (const raw of permission?.deny ?? [])
+        specs.push({ effect: "deny", raw, source });
+    return specs;
+}
+/** 第 6 步：缺省 ← 用户级 ← profile。 */
+export function mergeBaseLayers(layers) {
+    let config = mergeConfig(DEFAULT_CONFIG, undefined);
+    const present = ["default"];
+    const ruleSpecs = [];
+    if (layers.user !== undefined) {
+        config = mergeConfig(config, layers.user);
+        present.push("user");
+        ruleSpecs.push(...collectRules("user", layers.user.permission));
+    }
+    if (layers.hasProfile === true)
+        config = mergeConfig(config, PROFILE_DEFAULTS);
+    if (layers.profile !== undefined) {
+        config = mergeConfig(config, layers.profile);
+        present.push("profile");
+        ruleSpecs.push(...collectRules("profile", layers.profile.permission));
+    }
+    return { config, warnings: [], ruleSpecs, layers: present };
+}
+/** 第 9 步：叠加项目级（受限）与命令行。 */
+export function mergeProjectAndCli(base, project, cli, projectLabel) {
+    let config = base.config;
+    const warnings = [...base.warnings];
+    const ruleSpecs = [...base.ruleSpecs];
+    const present = [...base.layers];
+    if (project !== undefined) {
+        const baseline = config.permission?.mode ?? "default";
+        const restricted = restrictProjectConfig(project, baseline, projectLabel, config.tools?.preset ?? "default");
+        warnings.push(...restricted.warnings);
+        config = mergeConfig(config, restricted.accepted);
+        present.push("project");
+        ruleSpecs.push(...collectRules("project", restricted.accepted.permission));
+    }
+    // 命令行是用户的显式选择，最后叠加（可以放宽项目级收紧过的 mode，§7.2「放宽只认用户级 / 命令行 / profile」）。
+    const cliConfig = cli === undefined ? undefined : cliOverridesToConfig(cli);
+    if (cliConfig !== undefined && Object.keys(cliConfig).length > 0) {
+        config = mergeConfig(config, cliConfig);
+        present.push("cli");
+        ruleSpecs.push(...collectRules("cli", cliConfig.permission));
+    }
+    return { config, warnings, ruleSpecs, layers: present };
+}
+/** 一次合并全部层（SDK / 测试用）。 */
+export function mergeConfigLayers(layers) {
+    return mergeProjectAndCli(mergeBaseLayers(layers), layers.project, layers.cli);
+}