@armadra/agent 0.3.0 → 0.4.0

package/dist/cli/subcommands/stats.js

@@ -0,0 +1,198 @@
+/**
+ * `ama stats`：跨会话的用量统计（只读扫描会话 JSONL）。[W4-D]
+ *
+ * - 范围：缺省当前目录的会话；`--project <目录>` 指定项目；`--all` 全部（`--by project` 未指定范围时也看全部）。
+ * - 时间：`--since` / `--until` 接受 `7d`（含今天的最近 7 天）、`today`、`YYYY-MM-DD`（本地日期，含当天）。
+ * - 分组：`--by day|week|month|provider|channel|model|project`。
+ * - 缓存：`<数据目录>/stats-index.json`，按文件 mtime / size 失效；`--no-cache` 不读也不写。
+ * - 口径见 session/stats-aggregate.ts 与 docs/sessions.md「统计」。
+ */
+import { join, resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { sessionFilesInScope } from "../../session/scan.js";
+import { STATS_GROUPS, aggregateStats, } from "../../session/stats-aggregate.js";
+import { STATS_INDEX_FILE, collectSummaries } from "../../session/stats-index.js";
+import { localDay } from "../../session/stats-scan.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const STATS_USAGE = `用法：ama stats [--since 7d|30d|today|YYYY-MM-DD] [--until …]
+                 [--by day|week|month|provider|channel|model|project]
+                 [--project <目录> | --all] [--top N] [--json] [--no-cache] [--session-dir <目录>]
+`;
+/** `7d` / `today` / `YYYY-MM-DD` → 本地日期。 */
+export function parseDaySpec(option, raw, now = new Date()) {
+    if (raw === "today")
+        return localDay(now.toISOString()) ?? "";
+    const rel = /^(\d+)d$/.exec(raw);
+    if (rel !== null) {
+        const days = Number(rel[1]);
+        if (days < 1)
+            throw new UsageError(`--${option} 的天数至少为 1（收到 ${raw}）`);
+        const d = new Date(now);
+        d.setDate(d.getDate() - (days - 1));
+        return localDay(d.toISOString()) ?? "";
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) && Number.isFinite(Date.parse(`${raw}T00:00:00`)))
+        return raw;
+    throw new UsageError(`--${option} 应为 7d、today 或 YYYY-MM-DD（收到 ${raw}）`);
+}
+export function formatTokens(count) {
+    const trim = (text) => text.replace(/\.?0+$/, "");
+    if (count < 1000)
+        return String(Math.round(count));
+    if (count < 100_000)
+        return `${trim((count / 1000).toFixed(1))}k`;
+    if (count < 1_000_000)
+        return `${Math.round(count / 1000)}k`;
+    return `${trim((count / 1_000_000).toFixed(2))}M`;
+}
+const percent = (rate) => rate === undefined ? "—" : `${(rate * 100).toFixed(1)}%`;
+const usd = (t) => {
+    if (t.cost === undefined)
+        return "—";
+    return t.cost >= 1 || t.cost === 0 ? `$${t.cost.toFixed(2)}` : `$${t.cost.toFixed(4)}`;
+};
+function seconds(ms) {
+    if (ms === undefined)
+        return "—";
+    return ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${(ms / 60_000).toFixed(1)}m`;
+}
+function width(text) {
+    let w = 0;
+    for (const ch of text)
+        w += (ch.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1;
+    return w;
+}
+function table(rows, rightAlign) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, width(cell))));
+    return rows
+        .map((row) => row
+        .map((cell, i) => {
+        const padding = " ".repeat((widths[i] ?? 0) - width(cell));
+        return rightAlign(i) ? padding + cell : cell + padding;
+    })
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+export function renderStats(report, scope) {
+    const t = report.totals;
+    const range = report.since === undefined && report.until === undefined
+        ? "全部时间"
+        : `${report.since ?? "最早"} – ${report.until ?? "今天"}`;
+    const lines = [`${range} · ${scope} · ${report.sessions} 个会话`];
+    if (t.requests === 0) {
+        lines.push("没有模型请求");
+        return lines.join("\n") + "\n";
+    }
+    const kinds = Object.entries(report.byKind)
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, n]) => `${kind === "turn" ? "对话" : kind} ${n}`)
+        .join(" · ");
+    const costLine = t.cost === undefined
+        ? "— （所有请求的模型都无价格，见 token）"
+        : t.unpriced > 0
+            ? `${usd(t)}（另有 ${t.unpriced} 次请求无价，未计入）`
+            : usd(t);
+    const rows = [
+        ["请求", `${t.requests}（${kinds}）`],
+        ["回合", `${t.turns} · 平均耗时 ${seconds(t.avgTurnMs)}`],
+        [
+            "Token",
+            `输入 ${formatTokens(t.input)} · 输出 ${formatTokens(t.output)} · 缓存读 ${formatTokens(t.cacheRead)} · 缓存写 ${formatTokens(t.cacheWrite)}`,
+        ],
+        [
+            "缓存命中率",
+            `${percent(t.hitRate)}（报告缓存的端点 ${report.endpoints.reported}/${report.endpoints.total}，其余不进分母）`,
+        ],
+        ["费用", costLine],
+        ["错误 / 重试", `${t.errors} / ${t.retries}`],
+    ];
+    lines.push(table(rows, () => false));
+    if (report.groups !== undefined && report.groups.length > 0) {
+        const head = ["", "会话", "请求", "回合", "输入", "输出", "缓存读", "缓存写", "命中率", "费用"];
+        const body = report.groups.map((g) => [
+            g.key,
+            String(g.sessions),
+            String(g.requests),
+            String(g.turns),
+            formatTokens(g.input),
+            formatTokens(g.output),
+            formatTokens(g.cacheRead),
+            formatTokens(g.cacheWrite),
+            percent(g.hitRate),
+            usd(g) + (g.cost !== undefined && g.unpriced > 0 ? "+" : ""),
+        ]);
+        lines.push("", table([head, ...body], (i) => i > 0));
+    }
+    if (report.tools.length > 0) {
+        lines.push("", `工具调用 Top ${report.tools.length}`);
+        lines.push(table(report.tools.map((tool) => [`  ${tool.name}`, String(tool.count)]), (i) => i > 0));
+    }
+    return lines.join("\n") + "\n";
+}
+export async function runStats(argv, io) {
+    const { positionals, values, flags } = parseSubArgs(argv, ["since", "until", "by", "project", "session-dir", "top"], ["all", "json", "no-cache"]);
+    if (flags.has("help")) {
+        io.stdout(STATS_USAGE);
+        return ExitCode.Ok;
+    }
+    if (positionals.length > 0)
+        throw new UsageError(`ama stats 不接受位置参数：${positionals[0]}`);
+    const now = new Date();
+    const since = values.has("since") ? parseDaySpec("since", values.get("since"), now) : undefined;
+    const until = values.has("until") ? parseDaySpec("until", values.get("until"), now) : undefined;
+    const byRaw = values.get("by");
+    if (byRaw !== undefined && !STATS_GROUPS.includes(byRaw)) {
+        throw new UsageError(`--by 的取值应为 ${STATS_GROUPS.join(" | ")}（收到 ${byRaw}）`);
+    }
+    const by = byRaw;
+    const top = Number(values.get("top") ?? "10");
+    if (!Number.isInteger(top) || top < 0)
+        throw new UsageError("--top 应为非负整数");
+    if (flags.has("all") && values.has("project")) {
+        throw new UsageError("--project 与 --all 不能同时使用");
+    }
+    const dataDir = resolveDataDir({ env: io.env });
+    const dirFlag = values.get("session-dir");
+    const root = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : join(dataDir, "sessions");
+    const projectFlag = values.get("project");
+    const project = projectFlag !== undefined
+        ? resolve(io.cwd, expandHome(projectFlag, { env: io.env }))
+        : flags.has("all") || by === "project"
+            ? undefined
+            : io.cwd;
+    const files = sessionFilesInScope(root, project);
+    const useCache = !flags.has("no-cache");
+    const collected = collectSummaries(files, {
+        ...(useCache ? { indexFile: join(dataDir, STATS_INDEX_FILE) } : {}),
+        prune: project === undefined,
+    });
+    const report = aggregateStats(collected.summaries, {
+        ...(since !== undefined ? { since } : {}),
+        ...(until !== undefined ? { until } : {}),
+        ...(by !== undefined ? { by } : {}),
+        topTools: top,
+    });
+    if (flags.has("json")) {
+        io.stdout(JSON.stringify({
+            scope: project === undefined ? { all: true } : { project },
+            ...report,
+            files: {
+                total: files.length,
+                scanned: collected.scanned,
+                cached: collected.cached,
+                invalid: collected.invalid,
+            },
+        }, null, 2) + "\n");
+        return ExitCode.Ok;
+    }
+    io.stdout(renderStats(report, project === undefined ? "全部项目" : `项目 ${project}`));
+    if (collected.invalid > 0)
+        io.stderr(`ama: 跳过 ${collected.invalid} 个无法读取的会话文件\n`);
+    return ExitCode.Ok;
+}

package/dist/cli/system-prompt-arg.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import type { SystemPromptOverride } from "./deps.js";
+export declare function resolveSystemPromptArg(value: string | undefined, mode: "append" | "replace" | undefined, cwd: string): SystemPromptOverride | undefined;

package/dist/cli/system-prompt-arg.js

@@ -0,0 +1,34 @@
+/**
+ * `--system-prompt <文本|@文件>` 与 `--system-prompt-mode append|replace`（W4-C）。
+ *
+ * - `append`（缺省）：作为最后一条规则追加进系统提示的 rules 节——preamble 与工具表在它前面，
+ *   缓存前缀里最长的那段不受影响；同一段文本每次都逐字节相同。
+ * - `replace`：替换开头的 preamble（「You are ama…」那一段）；工具表、规则、AGENTS.md、Skill 索引、
+ *   cwd 等节照常保留，工具仍然可用。
+ * - `@文件`：相对当前目录读取（UTF-8）；文件不存在或为空 → 配置错误（退出码 3，同 `--instructions`）。
+ */
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { StartupError } from "../errors.js";
+import { ExitCode } from "./exit-codes.js";
+export function resolveSystemPromptArg(value, mode, cwd) {
+    if (value === undefined)
+        return undefined;
+    let text = value;
+    if (value.startsWith("@")) {
+        const raw = value.slice(1);
+        const path = isAbsolute(raw) ? raw : resolve(cwd, raw);
+        try {
+            if (!statSync(path).isFile())
+                throw new Error("not a file");
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            throw new StartupError("config_invalid", `--system-prompt 文件不存在：${path}`, ExitCode.Config);
+        }
+    }
+    text = text.trim();
+    if (text === "")
+        throw new StartupError("config_invalid", "--system-prompt 的内容为空", ExitCode.Config);
+    return { text, mode: mode ?? "append" };
+}

package/dist/codemode/modes.d.ts

@@ -4,20 +4,13 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import type { CodemodeMode } from "../config/types.js";
 import { type PresetResolution, type PresetToolRegistry } from "../tools/presets.js";
-import type { ToolDefinition } from "../tools/types.js";
-export declare function codemodeHint(name: string): string;
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export declare function withCodemodeHint<I>(tool: ToolDefinition<I>): ToolDefinition<I>;
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export declare function decorateForMode(mode: CodemodeMode): <I>(tool: ToolDefinition<I>) => ToolDefinition<I>;
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export declare function applyCodemodeMode(registry: PresetToolRegistry, resolution: Pick<PresetResolution, "builtin" | "codemode">): void;

package/dist/codemode/modes.js

@@ -4,36 +4,14 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import { CODEMODE_TOOL } from "../tools/presets.js";
-export function codemodeHint(name) {
-    return `Also callable inside codemode scripts as tools.${name}(args).`;
-}
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export function withCodemodeHint(tool) {
-    const copy = Object.create(Object.getPrototypeOf(tool), {
-        ...Object.getOwnPropertyDescriptors(tool),
-    });
-    Object.defineProperty(copy, "description", {
-        value: `${tool.description}\n${codemodeHint(tool.name)}`,
-        enumerable: true,
-        writable: false,
-        configurable: true,
-    });
-    return copy;
-}
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export function decorateForMode(mode) {
-    if (mode !== "on")
-        return (tool) => tool;
-    return (tool) => (tool.name === CODEMODE_TOOL ? tool : withCodemodeHint(tool));
-}
+import {} from "../tools/presets.js";
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export function applyCodemodeMode(registry, resolution) {
     registry.setPresetTools(resolution.builtin, { exclusive: resolution.codemode === "only" });

package/dist/codemode/tool.d.ts

@@ -12,7 +12,11 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
+import type { AmaConfig } from "../config/types.js";
 import type { ToolDefinition, ToolResult } from "../tools/types.js";
 import { type SandboxCapability } from "./capability.js";
 import { type DeclarableTool } from "./declarations.js";
@@ -25,6 +29,8 @@ export interface CallableTool {
     tool: DeclarableTool;
     /** 内置工具（非 bash）解析为文本；宿主 / SDK 工具可能返回结构化值。 */
     textResult: boolean;
+    /** 模型也能直接调用（在活动集里）；`on` 模式的描述只列名字。 */
+    direct?: boolean;
 }
 export interface CodemodeToolOptions {
     /** 脚本里可调用的工具（不含 codemode 本身）；描述冻结时与每次执行时各调用一次。 */
@@ -37,6 +43,8 @@ export interface CodemodeToolOptions {
     maxResultChars?: number;
     /** `only` 模式：其它工具不直接暴露，系统提示的工具行与规则写明只能在脚本里调用。 */
     exclusive?: boolean;
+    /** 描述的写法：缺省 `only`（按预算内联声明）；`on` 只列名字（见 `buildCodemodeDescription`）。 */
+    layout?: DescriptionLayout;
     /** 子进程入口（测试 / 嵌入方覆盖）。 */
     entry?: string;
     nodePath?: string;
@@ -68,7 +76,8 @@ export declare const CODEMODE_EXAMPLE: readonly string[];
  * （实测模型常见的两种错误）。其它错误原样返回。
  */
 export declare function scriptErrorHint(error: string, toolNames: readonly string[]): string;
-export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability): string;
+export type DescriptionLayout = "only" | "on";
+export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability, layout?: DescriptionLayout): string;
 /** 结果文本：状态行 + 输出（超限保留首尾）+ 失败原因。 */
 export declare function formatCodemodeResult(run: Pick<SandboxRunResult, "ok" | "error" | "outputs" | "elapsedMs" | "droppedChars">, limitChars: number, saveFull: (text: string) => string | undefined): {
     text: string;
@@ -79,27 +88,22 @@ export declare const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the
 export declare function createCodemodeTool(options: CodemodeToolOptions): ToolDefinition<CodemodeInput>;
 /** 组装根用：从 ToolFactoryContext 的形状取所需（避免 codemode → cli 的依赖）。 */
 export interface CodemodeFactoryContext {
-    config: {
-        codemode?: {
-            mode?: "off" | "on" | "only";
-            inlineBudget?: number;
-            requireStrict?: boolean;
-        };
-        tools?: {
-            preset?: string;
-            maxToolResultChars?: number;
-        };
-    };
+    config: Pick<AmaConfig, "tools" | "codemode">;
     registry: {
         list(): readonly string[];
         get(name: string): ToolDefinition | undefined;
     } & {
         sourceOf?(name: string): string | undefined;
+        /** 活动集（coordinator 预设下脚本只能调这些）。 */
+        active?(): readonly {
+            name: string;
+        }[];
     };
     warn(message: string): void;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export declare function codemodeToolFactory(overrides?: Partial<Pick<CodemodeToolOptions, "capability" | "entry" | "nodePath">>): (ctx: CodemodeFactoryContext) => ToolDefinition | undefined;

package/dist/codemode/tool.js

@@ -12,14 +12,17 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { codemodeCallableFilter, resolveCodemodeMode } from "../tools/presets.js";
 import { codemodeAvailability, detectSandboxCapability, } from "./capability.js";
-import { DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
+import { BASH_RESULT_DECLARATION, DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
 import { runSandbox } from "./host-side.js";
-import { codemodeHint } from "./modes.js";
 import { parseOptionsLine } from "./protocol.js";
 import { commitStore, readStore } from "./store.js";
 export const CODEMODE_TOOL_NAME = "codemode";
@@ -54,13 +57,6 @@ export function toScriptValue(name, result) {
         throw new Error(textOf(result.content) || `Tool ${name} failed`);
     return result.structured !== undefined ? result.structured : textOf(result.content);
 }
-/** on 模式下其它工具描述末尾的提示不进声明。 */
-function declarable(tool) {
-    const suffix = `\n${codemodeHint(tool.name)}`;
-    if (!tool.description.endsWith(suffix))
-        return tool;
-    return { ...tool, description: tool.description.slice(0, -suffix.length) };
-}
 /** 描述里的示例脚本（6 行）：并发两个 read、过滤、return。 */
 export const CODEMODE_EXAMPLE = [
     "const [a, b] = await Promise.all([",
@@ -86,7 +82,39 @@ export function scriptErrorHint(error, toolNames) {
     }
     return error;
 }
-export function buildCodemodeDescription(tools, inlineBudget, capability) {
+/**
+ * `on` 模式的描述：规则压成三行 + 示例；已直接暴露的工具只列名字（参数同直接调用），仅脚本可调用的
+ * 工具也只列名字。不内联任何声明，字节只依赖工具名与沙箱能力。
+ */
+function buildOnDescription(tools, capability) {
+    const names = (list) => list
+        .map(({ tool }) => tool.name)
+        .sort()
+        .join(", ");
+    const direct = tools.filter((t) => t.direct === true);
+    const scriptOnly = tools.filter((t) => t.direct !== true);
+    const lines = [
+        "Run a JavaScript script that calls tools; only its output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
+        "Input: raw JavaScript (not JSON, no code fence), the body of an async function (top-level await and return work). Only tools.<name>(args) exists: no require, import, process, fetch or timers.",
+        "Example:",
+        ...CODEMODE_EXAMPLE,
+        "tools.<name>(args) returns a Promise that rejects when the call fails or is denied (Promise.allSettled keeps the rest); text(v) / console.log(...) append output; return v is text(v); store(key, v) / load(key) keep small JSON values across scripts; describeTool(name) returns a signature. At most 8 calls run at once, each through the normal permissions.",
+    ];
+    if (!capability.strict)
+        lines.push(`Sandbox: ${capability.reason}.`);
+    if (direct.length > 0) {
+        const bash = direct.some(({ tool }) => tool.name === "bash");
+        lines.push(`Your direct tools are callable here too, same arguments: ${names(direct)}${bash ? " (tools.bash resolves to BashResult; the others to text)" : ""}.`);
+        if (bash)
+            lines.push(BASH_RESULT_DECLARATION);
+    }
+    if (scriptOnly.length > 0)
+        lines.push(`Callable only from scripts: ${names(scriptOnly)}.`);
+    return lines.join("\n");
+}
+export function buildCodemodeDescription(tools, inlineBudget, capability, layout = "only") {
+    if (layout === "on")
+        return buildOnDescription(tools, capability);
     const lines = [
         "Run a JavaScript script that calls tools; only the script's output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
         "Only tools.<name>(args) is available. There is no require, import, process, fetch or timers; do not call tools directly as functions.",
@@ -98,7 +126,7 @@ export function buildCodemodeDescription(tools, inlineBudget, capability) {
     if (!capability.strict) {
         lines.push(`Sandbox: ${capability.reason}.`);
     }
-    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool: declarable(tool), textResult })), inlineBudget);
+    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool, textResult })), inlineBudget);
     if (block.text !== "")
         lines.push(block.text);
     return lines.join("\n");
@@ -151,7 +179,7 @@ export function createCodemodeTool(options) {
         name: CODEMODE_TOOL_NAME,
         label: "Codemode",
         get description() {
-            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability);
+            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability, options.layout);
             return frozenDescription;
         },
         parameters: {
@@ -179,8 +207,10 @@ export function createCodemodeTool(options) {
             }
             const tools = options.listTools().map(({ tool: t, textResult }) => ({
                 name: t.name,
-                declaration: toolDeclaration(declarable(t), textResult ? {} : { textResult: false }),
+                declaration: toolDeclaration(t, textResult ? {} : { textResult: false }),
             }));
+            // 只有清单里的工具可调（coordinator 预设的清单只含活动集）；脚本拼出别的名字也不放行。
+            const callable = new Set(tools.map((t) => t.name));
             let tail = "";
             const run = await runSandbox({
                 script: input.script,
@@ -190,7 +220,11 @@ export function createCodemodeTool(options) {
                 signal: ctx.signal,
                 ...(options.entry !== undefined ? { entry: options.entry } : {}),
                 ...(options.nodePath !== undefined ? { nodePath: options.nodePath } : {}),
-                callTool: async (name, args, signal) => toScriptValue(name, await ctx.tools.executeTool(name, args, { signal })),
+                callTool: async (name, args, signal) => {
+                    if (!callable.has(name))
+                        throw new Error(`Tool ${name} is not available in codemode`);
+                    return toScriptValue(name, await ctx.tools.executeTool(name, args, { signal }));
+                },
                 onOutput: (text) => {
                     tail = `${tail}${tail === "" ? "" : "\n"}${text}`.slice(-TAIL_CHARS);
                     ctx.onUpdate(tail);
@@ -240,33 +274,42 @@ export function createCodemodeTool(options) {
     return tool;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export function codemodeToolFactory(overrides = {}) {
     return (ctx) => {
-        const explicit = ctx.config.codemode?.mode;
-        const mode = explicit ?? (ctx.config.tools?.preset === "codemode" ? "only" : "off");
+        const capability = overrides.capability ?? detectSandboxCapability();
+        const mode = resolveCodemodeMode(ctx.config, capability.strict).mode;
         if (mode === "off")
             return undefined;
-        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, overrides.capability ?? detectSandboxCapability());
+        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, capability);
         if (!availability.available) {
             ctx.warn(availability.warning);
             return undefined;
         }
         const registry = ctx.registry;
+        const onlyActive = codemodeCallableFilter(ctx.config) === "active";
+        const allowed = (name) => !onlyActive || (registry.active?.() ?? []).some((tool) => tool.name === name);
+        const direct = () => new Set(mode === "on" ? (registry.active?.() ?? []).map((tool) => tool.name) : []);
         const options = {
             capability: availability.capability,
             exclusive: mode === "only",
-            listTools: () => registry
-                .list()
-                .filter((name) => name !== CODEMODE_TOOL_NAME)
-                .map((name) => registry.get(name))
-                .filter((t) => t !== undefined)
-                .map((t) => ({
-                tool: t,
-                textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
-            })),
+            layout: mode === "on" ? "on" : "only",
+            listTools: () => {
+                const active = direct();
+                return registry
+                    .list()
+                    .filter((name) => name !== CODEMODE_TOOL_NAME && allowed(name))
+                    .map((name) => registry.get(name))
+                    .filter((t) => t !== undefined)
+                    .map((t) => ({
+                    tool: t,
+                    textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
+                    ...(active.has(t.name) ? { direct: true } : {}),
+                }));
+            },
         };
         const budget = ctx.config.codemode?.inlineBudget;
         if (budget !== undefined)

package/dist/config/init.d.ts

@@ -1,14 +1,16 @@
 /**
  * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
  *
- * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - 目录 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：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+/** 最小 config.json：只有 `$schema`、`version` 与空 `providers`（缺省值见 `ama config show`）。 */
 export declare function minimalConfig(): AmaConfig & {
     $schema: string;
 };
@@ -27,4 +29,6 @@ export declare function initConfigDir(dir: string, options?: {
 }): 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

@@ -1,7 +1,9 @@
 /**
  * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
  *
- * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - 目录 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 与测试不走这里。
@@ -12,14 +14,11 @@ 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 相同，写出来方便直接改）。 */
+/** 最小 config.json：只有 `$schema`、`version` 与空 `providers`（缺省值见 `ama config show`）。 */
 export function minimalConfig() {
     return {
         $schema: `./${CONFIG_SCHEMA_FILE}`,
         version: CONFIG_FILE_VERSION,
-        thinkingLevel: "medium",
-        permission: { mode: "default" },
-        tools: { preset: "default" },
         providers: {},
     };
 }
@@ -84,6 +83,14 @@ const STATUS_TEXT = {
     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)

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

@@ -3,6 +3,7 @@
  * （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";