@armadra/agent 0.0.0-stage → 0.2.1

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);
+}

package/dist/config/paths.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 目录解析（设计 §10.1、§11.1 第 5 步）。[B5]
+ *
+ * - 用户级配置目录：`AMA_CONFIG_DIR` > Windows `%APPDATA%\ama` > `$XDG_CONFIG_HOME/ama` > `~/.config/ama`。
+ * - 数据目录：`AMA_DATA_DIR` > Windows `%LOCALAPPDATA%\ama` > `$XDG_DATA_HOME/ama` > `~/.local/share/ama`。
+ * - 会话目录：`--session-dir` > profile.sessionDir > `<dataDir>/sessions`。
+ */
+import type { ResolvedPaths } from "../cli/runtime.js";
+export declare const CONFIG_FILE = "config.json";
+export declare const AUTH_FILE = "auth.json";
+export declare const HOOKS_FILE = "hooks.json";
+export declare const TRUST_FILE = "trust.json";
+export declare const KEYBINDINGS_FILE = "keybindings.json";
+/** 项目级目录名（`<cwd>/.ama/`）。 */
+export declare const PROJECT_DIR = ".ama";
+export interface PathEnv {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+}
+/** 展开开头的 `~`。 */
+export declare function expandHome(path: string, options?: PathEnv): string;
+export declare function resolveConfigDir(options?: PathEnv): string;
+export declare function resolveDataDir(options?: PathEnv): string;
+export interface ResolvePathsInput extends PathEnv {
+    cwd: string;
+    /** `--session-dir`（相对 cwd）。 */
+    sessionDirFlag?: string | undefined;
+    /** profile.sessionDir（已校验为绝对路径）。 */
+    profileSessionDir?: string | undefined;
+}
+export declare function resolvePaths(input: ResolvePathsInput): ResolvedPaths;
+/** 建目录（0700）并确认可写；失败抛 StartupError（退出码 3）。 */
+export declare function ensureDir(dir: string, label: string): void;
+/** 第 5 步：建 configDir / dataDir / sessionDir。 */
+export declare function ensurePaths(paths: ResolvedPaths): void;
+export declare function userFile(paths: Pick<ResolvedPaths, "configDir">, name: string): string;
+export declare function projectFile(cwd: string, name: string): string;

package/dist/config/paths.js

@@ -0,0 +1,108 @@
+/**
+ * 目录解析（设计 §10.1、§11.1 第 5 步）。[B5]
+ *
+ * - 用户级配置目录：`AMA_CONFIG_DIR` > Windows `%APPDATA%\ama` > `$XDG_CONFIG_HOME/ama` > `~/.config/ama`。
+ * - 数据目录：`AMA_DATA_DIR` > Windows `%LOCALAPPDATA%\ama` > `$XDG_DATA_HOME/ama` > `~/.local/share/ama`。
+ * - 会话目录：`--session-dir` > profile.sessionDir > `<dataDir>/sessions`。
+ */
+import { accessSync, constants, mkdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+/** 与 cli/exit-codes.ts 的 Config 相同；config 层不反向依赖 cli 的值。 */
+const EXIT_CONFIG = 3;
+export const CONFIG_FILE = "config.json";
+export const AUTH_FILE = "auth.json";
+export const HOOKS_FILE = "hooks.json";
+export const TRUST_FILE = "trust.json";
+export const KEYBINDINGS_FILE = "keybindings.json";
+/** 项目级目录名（`<cwd>/.ama/`）。 */
+export const PROJECT_DIR = ".ama";
+function envOf(options) {
+    return options.env ?? process.env;
+}
+function nonEmpty(value) {
+    return value !== undefined && value.trim() !== "" ? value : undefined;
+}
+function homeOf(options) {
+    const env = envOf(options);
+    return options.home ?? nonEmpty(env["HOME"]) ?? nonEmpty(env["USERPROFILE"]) ?? homedir();
+}
+/** 展开开头的 `~`。 */
+export function expandHome(path, options = {}) {
+    if (path === "~")
+        return homeOf(options);
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(homeOf(options), path.slice(2));
+    return path;
+}
+export function resolveConfigDir(options = {}) {
+    const env = envOf(options);
+    const explicit = nonEmpty(env["AMA_CONFIG_DIR"]);
+    if (explicit !== undefined)
+        return resolve(expandHome(explicit, options));
+    if ((options.platform ?? process.platform) === "win32") {
+        const appData = nonEmpty(env["APPDATA"]);
+        if (appData !== undefined)
+            return join(appData, "ama");
+    }
+    const xdg = nonEmpty(env["XDG_CONFIG_HOME"]);
+    if (xdg !== undefined && isAbsolute(xdg))
+        return join(xdg, "ama");
+    return join(homeOf(options), ".config", "ama");
+}
+export function resolveDataDir(options = {}) {
+    const env = envOf(options);
+    const explicit = nonEmpty(env["AMA_DATA_DIR"]);
+    if (explicit !== undefined)
+        return resolve(expandHome(explicit, options));
+    if ((options.platform ?? process.platform) === "win32") {
+        const local = nonEmpty(env["LOCALAPPDATA"]);
+        if (local !== undefined)
+            return join(local, "ama");
+    }
+    const xdg = nonEmpty(env["XDG_DATA_HOME"]);
+    if (xdg !== undefined && isAbsolute(xdg))
+        return join(xdg, "ama");
+    return join(homeOf(options), ".local", "share", "ama");
+}
+export function resolvePaths(input) {
+    const configDir = resolveConfigDir(input);
+    const dataDir = resolveDataDir(input);
+    const cwd = resolve(input.cwd);
+    let sessionDir;
+    if (input.sessionDirFlag !== undefined) {
+        sessionDir = resolve(cwd, expandHome(input.sessionDirFlag, input));
+    }
+    else if (input.profileSessionDir !== undefined) {
+        sessionDir = resolve(input.profileSessionDir);
+    }
+    else {
+        sessionDir = join(dataDir, "sessions");
+    }
+    return { configDir, dataDir, sessionDir, cwd };
+}
+/** 建目录（0700）并确认可写；失败抛 StartupError（退出码 3）。 */
+export function ensureDir(dir, label) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (!statSync(dir).isDirectory())
+            throw new Error("不是目录");
+        accessSync(dir, constants.W_OK);
+    }
+    catch (error) {
+        throw new StartupError("config_invalid", `${label}不可写：${dir}（${error instanceof Error ? error.message : String(error)}）`, EXIT_CONFIG, { cause: error });
+    }
+}
+/** 第 5 步：建 configDir / dataDir / sessionDir。 */
+export function ensurePaths(paths) {
+    ensureDir(paths.configDir, "配置目录");
+    ensureDir(paths.dataDir, "数据目录");
+    ensureDir(paths.sessionDir, "会话目录");
+}
+export function userFile(paths, name) {
+    return join(paths.configDir, name);
+}
+export function projectFile(cwd, name) {
+    return join(cwd, PROJECT_DIR, name);
+}

package/dist/config/profile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * profile.json（宿主用，设计 §10.3、§11.1 第 3 步、§11.2）。[B5]
+ *
+ * profile 的字段等价于对应命令行参数；命令行显式参数优先（合并在 cli/bootstrap.ts）。
+ * 文件不存在 / 版本不符 / 路径不是绝对路径 → StartupError（退出码 3）。profile 不含密钥。
+ */
+import type { AmaConfig } from "./types.js";
+/** profile 展开后的等价参数（全部为绝对路径）。 */
+export interface ProfileOptions {
+    path: string;
+    host?: string;
+    instructions: string[];
+    skillDirs: string[];
+    promptDirs: string[];
+    hooksFile?: string;
+    authFile?: string;
+    /** false：key 只来自 authFile。 */
+    authEnv: boolean;
+    sessionDir?: string;
+    /** profile.config 文件路径。 */
+    configFile?: string;
+    /** profile.config 的内容（已校验）。 */
+    config?: AmaConfig;
+    trustProject: boolean;
+    warnings: string[];
+}
+export declare function loadProfile(path: string, cwd?: string): ProfileOptions;

package/dist/config/profile.js

@@ -0,0 +1,65 @@
+/**
+ * profile.json（宿主用，设计 §10.3、§11.1 第 3 步、§11.2）。[B5]
+ *
+ * profile 的字段等价于对应命令行参数；命令行显式参数优先（合并在 cli/bootstrap.ts）。
+ * 文件不存在 / 版本不符 / 路径不是绝对路径 → StartupError（退出码 3）。profile 不含密钥。
+ */
+import { isAbsolute, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+import { loadConfigFile } from "./load.js";
+import { PROFILE_PATH_FIELDS, PROFILE_PATH_LIST_FIELDS } from "./schema.js";
+const EXIT_CONFIG = 3;
+export function loadProfile(path, cwd = process.cwd()) {
+    const abs = resolve(cwd, path);
+    const loaded = loadConfigFile("profile", abs, { required: true });
+    if (loaded === undefined) {
+        throw new StartupError("profile_invalid", `${abs}: 文件不存在`, EXIT_CONFIG);
+    }
+    const profile = loaded.value;
+    const relative = [];
+    for (const key of PROFILE_PATH_FIELDS) {
+        const value = profile[key];
+        if (value !== undefined && !isAbsolute(value))
+            relative.push(`${key}: ${value}`);
+    }
+    for (const key of PROFILE_PATH_LIST_FIELDS) {
+        for (const value of profile[key] ?? []) {
+            if (!isAbsolute(value))
+                relative.push(`${key}: ${value}`);
+        }
+    }
+    if (relative.length > 0) {
+        throw new StartupError("profile_invalid", `${abs}: profile 中的路径必须是绝对路径：\n  ${relative.join("\n  ")}`, EXIT_CONFIG);
+    }
+    const options = profileToOptions(abs, profile, loaded.warnings);
+    if (profile.config !== undefined) {
+        const config = loadConfigFile("config", profile.config, { required: true });
+        if (config !== undefined) {
+            options.config = config.value;
+            options.warnings.push(...config.warnings);
+        }
+    }
+    return options;
+}
+function profileToOptions(path, profile, warnings) {
+    const options = {
+        path,
+        instructions: [...(profile.instructions ?? [])],
+        skillDirs: [...(profile.skillDirs ?? [])],
+        promptDirs: [...(profile.promptDirs ?? [])],
+        authEnv: profile.authEnv !== false,
+        trustProject: profile.trustProject === true,
+        warnings: [...warnings],
+    };
+    if (profile.host !== undefined)
+        options.host = profile.host;
+    if (profile.hooksFile !== undefined)
+        options.hooksFile = profile.hooksFile;
+    if (profile.authFile !== undefined)
+        options.authFile = profile.authFile;
+    if (profile.sessionDir !== undefined)
+        options.sessionDir = profile.sessionDir;
+    if (profile.config !== undefined)
+        options.configFile = profile.config;
+    return options;
+}