@armadra/agent 0.0.0-stage → 0.3.0

package/dist/compaction/summarize-tier.js

@@ -0,0 +1,305 @@
+/**
+ * 档二摘要（设计 §9「档二」「模板」）。[B2]
+ *
+ * `prepareCompaction()` 在投影上找切点，得到「要摘要的消息」与 `firstKeptEntryId`；
+ * `runCompaction()` 请模型按模板写摘要，split turn 时历史与回合前缀各一份再合并；
+ * `<read-files>` / `<modified-files>` 与上一份 compaction 的 details 累计。失败抛
+ * `AmaError{code:"compaction_failed"}`，abort 抛 `aborted`。
+ *
+ * [W3-C1b] 会话前缀续写（第三波 §1.8）：调用方给出 `continuation.prefix`（与上一次真实请求
+ * 逐字节同前缀的完整转录）时，请求 = 前缀 + 一条摘要指令（「只摘要第 1–N 条，第 N+1 条起
+ * 保留原文」+ 首行引文），`cacheRetention: "short"`、`purpose: "summary"`，按读价计费。
+ * **不发 `toolChoice`**：实测（docs/benchmarks/cache-2026-10-02.md E3）中转与 Kimi 在
+ * `tool_choice: "none"` 时渲染的提示不带工具定义，前缀在工具段断开、cacheRead 为 0；Anthropic
+ * 文档也写明改动 tool_choice 会让消息缓存失效。所以 system + tools + 消息前缀与上一次真实请求
+ * 逐字节相同，「不调用工具、只输出摘要」只写在末尾指令里；响应为空 / 被截断 / 含工具调用 / 请求出错 → 回落现行独立请求（序列化转录、
+ * `cacheRetention: "none"`）并经 `onFallback` 记 warning。
+ */
+import { AmaError } from "../errors.js";
+import { findCutPoint, summarizableStart } from "./cut-point.js";
+import { collectFileOps, createFileOps, fileOpsDetails, formatFileOps, serializeConversation, } from "./serialize.js";
+export const SUMMARY_MAX_TOKENS = 4096;
+export const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. You read a record of a coding session between a " +
+    "user and an AI coding agent and write a structured checkpoint that another instance of the " +
+    "agent will use to continue the work. Do not continue the conversation and do not answer " +
+    "questions found in the record; only output the summary.";
+export const SUMMARY_TEMPLATE = `Write the checkpoint summary using EXACTLY this format:
+
+## Goal
+[What the user is trying to accomplish; several items if the session covers several tasks.]
+
+## Constraints & Preferences
+- [Constraints, preferences, or requirements stated by the user, or "(none)"]
+
+## Progress
+### Done
+- [x] [Completed tasks and changes]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Short rationale]
+
+## Next Steps
+1. [Ordered list of what should happen next]
+
+## Critical Context
+- [Data, file paths, identifiers, error messages, or references needed to continue, or "(none)"]
+
+Keep every section concise. Preserve exact file paths, function names, and error messages.`;
+/** 续写指令的首句（测试据此识别摘要请求）。 */
+export const SUMMARY_CONTINUATION_PREAMBLE = "Stop here: do not continue the conversation, do not answer questions from it and do not call any tools.";
+/** 续写指令的末句：工具仍在请求里（为了缓存前缀），只靠指令禁止调用。 */
+export const SUMMARY_CONTINUATION_TAIL = "Tools are still listed above, but you must not call any of them now. Reply with the summary text only.";
+const TURN_PREFIX_PROMPT = `The record above is the BEGINNING of the current turn; the rest of the turn is kept verbatim after this summary. Summarize only what the agent was asked to do in this turn and what it has done so far, in a short "## Turn So Far" section followed by "## Critical Context".`;
+const TURN_PREFIX_CONTINUATION_PROMPT = `These messages are the BEGINNING of the current turn; the rest of the turn is kept verbatim after this summary. Summarize only what the agent was asked to do in this turn and what it has done so far, in a short "## Turn So Far" section followed by "## Critical Context".`;
+/** 转录里（不计 system）实际发给模型的消息数：失败 / 中断的助手消息连同其工具结果不回放。 */
+export function countLlmMessages(messages) {
+    let count = 0;
+    let skipping = false;
+    for (const message of messages) {
+        if (message.role === "system")
+            continue;
+        if (message.role === "toolResult" && skipping)
+            continue;
+        skipping =
+            message.role === "assistant" &&
+                (message.stopReason === "error" || message.stopReason === "aborted");
+        if (!skipping)
+            count++;
+    }
+    return count;
+}
+/** 消息首行引文（≤ 80 字符）。 */
+export function excerptOf(message) {
+    if (message === undefined || message.role === "system")
+        return "";
+    let text;
+    if (message.role === "compactionSummary" || message.role === "branchSummary")
+        text = message.summary;
+    else if (message.role === "assistant")
+        text = message.content
+            .map((block) => block.type === "text" ? block.text : block.type === "toolCall" ? `[${block.name}]` : "")
+            .join(" ");
+    else if (typeof message.content === "string")
+        text = message.content;
+    else
+        text = message.content.map((block) => (block.type === "text" ? block.text : "")).join(" ");
+    const line = text.trim().split("\n")[0] ?? "";
+    return line.length > 80 ? `${line.slice(0, 79)}…` : line;
+}
+/** 无可摘要内容时返回 undefined。 */
+export function prepareCompaction(projection, keepRecentTokens) {
+    const items = projection.items;
+    const start = summarizableStart(items);
+    const cut = findCutPoint(items, start, keepRecentTokens);
+    if (cut.firstKeptIndex <= start)
+        return undefined;
+    const keptItem = items[cut.firstKeptIndex];
+    if (keptItem === undefined)
+        return undefined;
+    const historyEnd = cut.isSplitTurn ? cut.turnStartIndex : cut.firstKeptIndex;
+    const pick = (from, to) => items
+        .slice(from, to)
+        .map((item) => item.message)
+        .filter((message) => message.role !== "system");
+    const previous = projection.compaction;
+    const messages = items.map((item) => item.message);
+    const anchors = {
+        historyEnd: countLlmMessages(messages.slice(0, historyEnd)),
+        keptStart: countLlmMessages(messages.slice(0, cut.firstKeptIndex)),
+        historyExcerpt: excerptOf(messages[historyEnd]),
+        keptExcerpt: excerptOf(keptItem.message),
+    };
+    return {
+        anchors,
+        toSummarize: pick(start, historyEnd),
+        turnPrefix: cut.isSplitTurn ? pick(cut.turnStartIndex, cut.firstKeptIndex) : [],
+        firstKeptEntryId: keptItem.entry.id,
+        cut,
+        previousSummary: previous?.summary,
+        previousDetails: previous?.details,
+    };
+}
+function addUsage(a, b) {
+    if (a === undefined)
+        return { ...b };
+    return {
+        input: a.input + b.input,
+        output: a.output + b.output,
+        cacheRead: a.cacheRead + b.cacheRead,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+        totalTokens: a.totalTokens + b.totalTokens,
+    };
+}
+function assistantText(message) {
+    return message.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("")
+        .trim();
+}
+/** 一次无工具的文本补全；错误 / 取消 / 空输出抛错。 */
+export async function completeText(options, userText) {
+    const context = {
+        messages: [
+            {
+                role: "system",
+                sections: { preamble: SUMMARIZATION_SYSTEM_PROMPT },
+                timestamp: Date.now(),
+            },
+            { role: "user", content: userText, timestamp: Date.now() },
+        ],
+    };
+    const maxTokens = Math.min(options.maxTokens ?? SUMMARY_MAX_TOKENS, options.model.maxTokens);
+    let message;
+    try {
+        const streamOptions = {
+            signal: options.signal,
+            maxTokens,
+            cacheRetention: "none",
+            purpose: "summary",
+        };
+        if (options.apiKey !== undefined)
+            streamOptions.apiKey = options.apiKey;
+        const stream = options.stream(options.model, context, streamOptions);
+        message = await stream.result();
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw new AmaError("aborted", "compaction aborted");
+        throw new AmaError("compaction_failed", `summary request failed: ${String(error)}`, {
+            cause: error,
+        });
+    }
+    return checkSummary(message, options.signal);
+}
+function checkSummary(message, signal) {
+    if (message.stopReason === "aborted" || signal.aborted) {
+        throw new AmaError("aborted", "compaction aborted");
+    }
+    if (message.stopReason === "error") {
+        throw new AmaError("compaction_failed", message.errorMessage ?? "summary request failed");
+    }
+    const text = assistantText(message);
+    if (text === "")
+        throw new AmaError("compaction_failed", "summary model returned no text");
+    return { text, usage: message.usage };
+}
+function continuationPrompt(input, total, instructions) {
+    const { index, excerpt } = input.keepFrom;
+    const from = input.from ?? 0;
+    const parts = [SUMMARY_CONTINUATION_PREAMBLE];
+    const range = from + 1 === index ? `message ${index}` : `messages ${from + 1}–${index}`;
+    parts.push(`Write a summary of ${range} of the conversation above ` +
+        "(count user, assistant and tool-result messages from the start of the conversation; " +
+        "a summary of earlier history at the start counts as a message and must be merged in).");
+    if (index < total && excerpt !== "") {
+        parts.push(`Message ${index + 1} begins with: «${excerpt}». It and everything after it stay in the context verbatim, so do not summarize them.`);
+    }
+    parts.push(input.instruction);
+    if (instructions !== undefined && instructions.trim() !== "") {
+        parts.push(`Additional instructions:\n${instructions.trim()}`);
+    }
+    parts.push(SUMMARY_CONTINUATION_TAIL);
+    return parts.join("\n\n");
+}
+/**
+ * 会话前缀续写：前缀 + 一条摘要指令，不发 `toolChoice`（保住含工具段的缓存前缀）。空 / 截断 /
+ * 含工具调用 / 出错抛 `compaction_failed`（调用方回落），abort 抛 `aborted`。
+ */
+export async function completeByContinuation(options, input) {
+    const total = input.prefix.messages.filter((message) => message.role !== "system").length;
+    const prompt = continuationPrompt(input, total, options.customInstructions);
+    const context = {
+        messages: [...input.prefix.messages, { role: "user", content: prompt, timestamp: Date.now() }],
+    };
+    // 改动 tool_choice 会让缓存前缀失效：即使调用方传了也不带。
+    const { toolChoice: _toolChoice, ...base } = options.continuation?.streamOptions ?? {};
+    const streamOptions = {
+        ...base,
+        signal: options.signal,
+        maxTokens: base.maxTokens ?? Math.min(options.maxTokens ?? SUMMARY_MAX_TOKENS, options.model.maxTokens),
+        cacheRetention: "short",
+        purpose: "summary",
+    };
+    if (options.apiKey !== undefined)
+        streamOptions.apiKey = options.apiKey;
+    let message;
+    try {
+        message = await options.stream(options.model, context, streamOptions).result();
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw new AmaError("aborted", "compaction aborted");
+        throw new AmaError("compaction_failed", `summary request failed: ${String(error)}`);
+    }
+    if (message.stopReason === "length")
+        throw new AmaError("compaction_failed", "summary was truncated");
+    if (message.content.some((block) => block.type === "toolCall"))
+        throw new AmaError("compaction_failed", "summary response called a tool");
+    return checkSummary(message, options.signal);
+}
+/** 先试续写，失败（非 abort）回落独立请求。 */
+export async function summarizeWithFallback(options, continuation, independentPrompt) {
+    const prefix = options.continuation?.prefix;
+    if (prefix !== undefined && continuation !== undefined) {
+        try {
+            return await completeByContinuation(options, { ...continuation, prefix });
+        }
+        catch (error) {
+            if (options.signal.aborted || (error instanceof AmaError && error.code === "aborted"))
+                throw error;
+            options.onFallback?.(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return completeText(options, independentPrompt());
+}
+function buildPrompt(conversation, previousSummary, instructions, tail) {
+    const parts = [];
+    if (previousSummary !== undefined) {
+        parts.push(`<previous-summary>\n${previousSummary}\n</previous-summary>`);
+        parts.push("The previous summary covers the session before the record below. Merge it with the new record into ONE updated summary.");
+    }
+    parts.push(`<conversation>\n${conversation}\n</conversation>`);
+    parts.push(tail);
+    if (instructions !== undefined && instructions.trim() !== "") {
+        parts.push(`Additional instructions:\n${instructions.trim()}`);
+    }
+    return parts.join("\n\n");
+}
+export async function runCompaction(plan, options) {
+    let usage;
+    let summary;
+    const { anchors } = plan;
+    if (plan.toSummarize.length > 0 || plan.previousSummary !== undefined) {
+        const history = await summarizeWithFallback(options, {
+            keepFrom: { index: anchors.historyEnd, excerpt: anchors.historyExcerpt },
+            instruction: SUMMARY_TEMPLATE,
+        }, () => buildPrompt(serializeConversation(plan.toSummarize), plan.previousSummary, options.customInstructions, SUMMARY_TEMPLATE));
+        usage = addUsage(usage, history.usage);
+        summary = history.text;
+    }
+    else {
+        summary = "## Goal\n(no earlier history)";
+    }
+    if (plan.turnPrefix.length > 0) {
+        const prefix = await summarizeWithFallback({ ...options, customInstructions: undefined }, {
+            from: anchors.historyEnd,
+            keepFrom: { index: anchors.keptStart, excerpt: anchors.keptExcerpt },
+            instruction: TURN_PREFIX_CONTINUATION_PROMPT,
+        }, () => buildPrompt(serializeConversation(plan.turnPrefix), undefined, undefined, TURN_PREFIX_PROMPT));
+        usage = addUsage(usage, prefix.usage);
+        summary = `${summary}\n\n---\n\n${prefix.text}`;
+    }
+    const ops = collectFileOps([...plan.toSummarize, ...plan.turnPrefix], createFileOps(plan.previousDetails));
+    const details = fileOpsDetails(ops);
+    const files = formatFileOps(details);
+    if (files !== "")
+        summary = `${summary}\n\n${files}`;
+    return { summary, firstKeptEntryId: plan.firstKeptEntryId, usage, details };
+}

package/dist/config/auth-file.d.ts

@@ -0,0 +1,39 @@
+/**
+ * auth.json 读写（设计 §3.5 ②③、§10.1）与 `ama auth` 后端。[B5]
+ *
+ * - 文件权限 0600；读到非 0600（POSIX）→ warning 并照用，doctor 提示。
+ * - 写入：同目录临时文件（0600）→ rename，再 chmod 一次兜底。
+ * - 本模块只搬运字符串，不解析 `!command` / `$ENV`（那是 ai/providers/auth.ts 的事），
+ *   也不把 key 写进任何日志或返回给展示层（`describeAuthFile` 只给来源与形态）。
+ */
+import type { AuthFile } from "./types.js";
+export declare function defaultAuthFilePath(configDir: string): string;
+export declare const PROVIDER_ID_PATTERN: RegExp;
+export interface ReadAuthResult {
+    path: string;
+    exists: boolean;
+    file: AuthFile;
+    warnings: string[];
+    /** POSIX 下的权限位（八进制数），Windows 为 undefined。 */
+    mode?: number;
+}
+/** 当前权限位；文件不存在为 undefined。 */
+export declare function fileMode(path: string): number | undefined;
+export declare function isModeTooOpen(mode: number | undefined, platform?: NodeJS.Platform): boolean;
+/** 读 auth.json；不存在 → 空文件。语法 / 字段错误抛 StartupError（3）。 */
+export declare function readAuthFile(path: string): ReadAuthResult;
+export declare function writeAuthFile(path: string, file: AuthFile): void;
+/** `ama auth set`：设置 / 替换一家的 key（保留该条目的 env / baseUrl）。 */
+export declare function setAuthKey(path: string, provider: string, apiKey: string): void;
+/** `ama auth remove`：返回是否删除了条目。 */
+export declare function removeAuthKey(path: string, provider: string): boolean;
+export type AuthValueKind = "literal" | "command" | "env-ref";
+/** 只描述 key 的形态，不暴露值。 */
+export declare function classifyKeyValue(value: string): AuthValueKind;
+export interface AuthEntrySummary {
+    provider: string;
+    kind: AuthValueKind;
+    hasBaseUrl: boolean;
+    envNames: string[];
+}
+export declare function describeAuthFile(file: AuthFile): AuthEntrySummary[];

package/dist/config/auth-file.js

@@ -0,0 +1,92 @@
+/**
+ * auth.json 读写（设计 §3.5 ②③、§10.1）与 `ama auth` 后端。[B5]
+ *
+ * - 文件权限 0600；读到非 0600（POSIX）→ warning 并照用，doctor 提示。
+ * - 写入：同目录临时文件（0600）→ rename，再 chmod 一次兜底。
+ * - 本模块只搬运字符串，不解析 `!command` / `$ENV`（那是 ai/providers/auth.ts 的事），
+ *   也不把 key 写进任何日志或返回给展示层（`describeAuthFile` 只给来源与形态）。
+ */
+import { chmodSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadConfigFile } from "./load.js";
+import { AUTH_FILE } from "./paths.js";
+import { CONFIG_FILE_VERSION } from "./types.js";
+export function defaultAuthFilePath(configDir) {
+    return join(configDir, AUTH_FILE);
+}
+export const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+/** 当前权限位；文件不存在为 undefined。 */
+export function fileMode(path) {
+    try {
+        return statSync(path).mode & 0o777;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isModeTooOpen(mode, platform = process.platform) {
+    return platform !== "win32" && mode !== undefined && (mode & 0o077) !== 0;
+}
+/** 读 auth.json；不存在 → 空文件。语法 / 字段错误抛 StartupError（3）。 */
+export function readAuthFile(path) {
+    const loaded = loadConfigFile("auth", path);
+    if (loaded === undefined) {
+        return {
+            path,
+            exists: false,
+            file: { version: CONFIG_FILE_VERSION, providers: {} },
+            warnings: [],
+        };
+    }
+    const warnings = [...loaded.warnings];
+    const mode = fileMode(path);
+    if (isModeTooOpen(mode)) {
+        warnings.push(`${path}: 权限为 ${mode?.toString(8).padStart(4, "0")}，应为 0600（chmod 600 ${path}）`);
+    }
+    const result = { path, exists: true, file: loaded.value, warnings };
+    if (mode !== undefined && process.platform !== "win32")
+        result.mode = mode;
+    return result;
+}
+export function writeAuthFile(path, file) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+    if (process.platform !== "win32")
+        chmodSync(path, 0o600);
+}
+/** `ama auth set`：设置 / 替换一家的 key（保留该条目的 env / baseUrl）。 */
+export function setAuthKey(path, provider, apiKey) {
+    const { file } = readAuthFile(path);
+    const previous = file.providers[provider];
+    file.providers[provider] = { ...previous, apiKey };
+    writeAuthFile(path, { version: CONFIG_FILE_VERSION, providers: file.providers });
+}
+/** `ama auth remove`：返回是否删除了条目。 */
+export function removeAuthKey(path, provider) {
+    const { file, exists } = readAuthFile(path);
+    if (!exists || file.providers[provider] === undefined)
+        return false;
+    delete file.providers[provider];
+    writeAuthFile(path, { version: CONFIG_FILE_VERSION, providers: file.providers });
+    return true;
+}
+/** 只描述 key 的形态，不暴露值。 */
+export function classifyKeyValue(value) {
+    if (value.startsWith("!"))
+        return "command";
+    if (/^\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)$/.test(value))
+        return "env-ref";
+    return "literal";
+}
+export function describeAuthFile(file) {
+    return Object.entries(file.providers)
+        .map(([provider, entry]) => ({
+        provider,
+        kind: classifyKeyValue(entry.apiKey),
+        hasBaseUrl: entry.baseUrl !== undefined,
+        envNames: Object.keys(entry.env ?? {}).sort(),
+    }))
+        .sort((a, b) => a.provider.localeCompare(b.provider));
+}

package/dist/config/context-files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 项目上下文文件（AGENTS.md）向上查找（设计 §1.2、§10.1、§11.1 第 10 步）。[B5]
+ *
+ * - 每个目录取第一个存在的：`AGENTS.override.md` > `AGENTS.md` > `AGENTS.MD`。
+ * - 顺序：用户级 `<configDir>/AGENTS.md`（全局约定）在最前，其后祖先由外向内，cwd 最后。
+ * - 去重：同一真实路径只取一次（符号链接）；内容与已收集文件完全相同的跳过——
+ *   git worktree 放在主仓库目录内（如 `.worktrees/x`）时，向上会再碰到主仓库的同一份
+ *   AGENTS.md，它不带来新信息。
+ * - 不需要信任（§7.3）。读错记 warning 继续。
+ */
+export declare const CONTEXT_FILE_NAMES: readonly ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD"];
+export interface ContextFile {
+    path: string;
+    content: string;
+    scope: "user" | "project";
+}
+export interface FindContextFilesInput {
+    cwd: string;
+    /** 用户级配置目录；undefined 则不读全局 AGENTS.md。 */
+    configDir?: string | undefined;
+    /** 单文件上限（字节），超出截断并 warning；缺省 256 KiB。 */
+    maxBytes?: number;
+}
+export interface FindContextFilesResult {
+    files: ContextFile[];
+    warnings: string[];
+}
+/** 目录里按优先级取第一个存在的上下文文件。 */
+export declare function pickContextFile(dir: string): string | undefined;
+export declare function findContextFiles(input: FindContextFilesInput): FindContextFilesResult;

package/dist/config/context-files.js

@@ -0,0 +1,77 @@
+/**
+ * 项目上下文文件（AGENTS.md）向上查找（设计 §1.2、§10.1、§11.1 第 10 步）。[B5]
+ *
+ * - 每个目录取第一个存在的：`AGENTS.override.md` > `AGENTS.md` > `AGENTS.MD`。
+ * - 顺序：用户级 `<configDir>/AGENTS.md`（全局约定）在最前，其后祖先由外向内，cwd 最后。
+ * - 去重：同一真实路径只取一次（符号链接）；内容与已收集文件完全相同的跳过——
+ *   git worktree 放在主仓库目录内（如 `.worktrees/x`）时，向上会再碰到主仓库的同一份
+ *   AGENTS.md，它不带来新信息。
+ * - 不需要信任（§7.3）。读错记 warning 继续。
+ */
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ancestorsOf } from "./trust.js";
+export const CONTEXT_FILE_NAMES = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD"];
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** 目录里按优先级取第一个存在的上下文文件。 */
+export function pickContextFile(dir) {
+    for (const name of CONTEXT_FILE_NAMES) {
+        const candidate = join(dir, name);
+        if (isFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function findContextFiles(input) {
+    const maxBytes = input.maxBytes ?? 256 * 1024;
+    const files = [];
+    const warnings = [];
+    const seenPaths = new Set();
+    const seenContent = new Set();
+    const add = (path, scope) => {
+        let real;
+        try {
+            real = realpathSync(path);
+        }
+        catch {
+            real = path;
+        }
+        if (seenPaths.has(real))
+            return;
+        seenPaths.add(real);
+        let content;
+        try {
+            content = readFileSync(path, "utf8");
+        }
+        catch (error) {
+            warnings.push(`${path}: 读取失败（${error.message}）`);
+            return;
+        }
+        if (Buffer.byteLength(content) > maxBytes) {
+            content = Buffer.from(content).subarray(0, maxBytes).toString("utf8");
+            warnings.push(`${path}: 超过 ${maxBytes} 字节，已截断`);
+        }
+        if (seenContent.has(content))
+            return;
+        seenContent.add(content);
+        files.push({ path, content, scope });
+    };
+    if (input.configDir !== undefined) {
+        const global = pickContextFile(input.configDir);
+        if (global !== undefined)
+            add(global, "user");
+    }
+    for (const dir of ancestorsOf(input.cwd).reverse()) {
+        const found = pickContextFile(dir);
+        if (found !== undefined)
+            add(found, "project");
+    }
+    return { files, warnings };
+}

package/dist/config/init.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - `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：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+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;
+export declare function describeInit(result: InitResult): string;

package/dist/config/init.js

@@ -0,0 +1,92 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - `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：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+export function minimalConfig() {
+    return {
+        $schema: `./${CONFIG_SCHEMA_FILE}`,
+        version: CONFIG_FILE_VERSION,
+        thinkingLevel: "medium",
+        permission: { mode: "default" },
+        tools: { preset: "default" },
+        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）",
+};
+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`;
+}