@armadra/agent 0.5.1 → 0.6.1

package/dist/i18n/messages/trace.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 消息目录：trace（键名规范见 docs/i18n.md）。[W6-C0 建空壳，W6-T1 填 TUI / line 模式文案，W6-T2 追加 HTML]
+ *
+ * en 是形状源；zh 用 `satisfies Messages<typeof en>`，缺键 / 多键 / 参数不符在 tsc 期报错。
+ * 整句一个键、禁止片段拼接；插值写成函数，条件分支写进函数体。
+ * 不译：ttft、tok/s、↑ ↓、模型名、工具名、任务 id、触发方式（threshold / overflow / manual）。
+ */
+export declare const en: {
+    title: string;
+    /** 顶部汇总行。 */
+    summary: (turns: number, requests: number, tools: number) => string;
+    cache: (percent: string) => string;
+    empty: string;
+    /** 子轨迹标题（`/trace t2`）。 */
+    taskTitle: (taskId: string, agent: string) => string;
+    taskNotFound: (taskId: string) => string;
+    follow: {
+        on: string;
+        off: string;
+    };
+    hints: {
+        list: string;
+        listNarrow: string;
+        detail: string;
+    };
+    row: {
+        turn: (n: number, text: string) => string;
+        turnOrigin: (n: number, origin: string, text: string) => string;
+        step: (model: string) => string;
+        stepAttempt: (model: string, attempt: number) => string;
+        fallback: (from: string) => string;
+        subagent: (taskId: string, agent: string) => string;
+        subagentExternal: (taskId: string, agent: string, runner: string) => string;
+        background: string;
+        childMissing: string;
+        compaction: (trigger: string) => string;
+        compactionPlain: string;
+        retryWait: (delay: string, attempt: number) => string;
+        aux: {
+            cache_warm: string;
+            permission_classify: string;
+        };
+        auxGroup: (n: number) => string;
+        externalTurn: (turn: number, tools: number, files: number) => string;
+        more: (n: number) => string;
+    };
+    status: {
+        ok: string;
+        error: string;
+        aborted: string;
+        denied: string;
+        running: string;
+        retried: string;
+        interrupted: string;
+    };
+    detail: {
+        kind: string;
+        status: string;
+        start: string;
+        duration: string;
+        approx: string;
+        approxValue: string;
+        model: string;
+        attempt: string;
+        fallbackFrom: string;
+        ttft: string;
+        tps: string;
+        thinking: string;
+        stopReason: string;
+        error: string;
+        usage: string;
+        usageValue: (input: string, output: string, cacheRead: string, cacheWrite: string) => string;
+        cacheHit: string;
+        cost: string;
+        approval: string;
+        denied: string;
+        yes: string;
+        task: string;
+        runner: string;
+        background: string;
+        turns: string;
+        childFile: string;
+        childMissing: string;
+        tools: string;
+        files: string;
+        origin: string;
+        input: string;
+        output: string;
+        args: string;
+        result: string;
+        reason: string;
+        truncated: (length: number) => string;
+    };
+    /** [W6-T2] HTML 导出的静态文案（按导出时的语言渲染）。 */
+    html: {
+        docTitle: (sessionId: string) => string;
+        search: string;
+        noMatch: string;
+        jump: string;
+        zoomIn: string;
+        zoomOut: string;
+        zoomFit: string;
+        expandAll: string;
+        collapseAll: string;
+        legendTtft: string;
+        legendDecode: string;
+        legendTool: string;
+        legendAgent: string;
+        legendWait: string;
+        legendOther: string;
+        axisNote: string;
+        detailEmpty: string;
+        noContent: string;
+        previewDropped: string;
+        childPreviewOff: string;
+        footer: (version: string, generatedAt: string) => string;
+        keys: string;
+    };
+    /** [W6-T2] `ama sessions trace`。 */
+    cli: {
+        usage: string;
+        wrote: (path: string) => string;
+        openFailed: (reason: string) => string;
+        formatConflict: string;
+        badNow: (raw: string) => string;
+    };
+};
+export declare const zh: {
+    title: string;
+    summary: (turns: number, requests: number, tools: number) => string;
+    cache: (percent: string) => string;
+    empty: string;
+    taskTitle: (taskId: string, agent: string) => string;
+    taskNotFound: (taskId: string) => string;
+    follow: {
+        on: string;
+        off: string;
+    };
+    hints: {
+        list: string;
+        listNarrow: string;
+        detail: string;
+    };
+    row: {
+        turn: (n: number, text: string) => string;
+        turnOrigin: (n: number, origin: string, text: string) => string;
+        step: (model: string) => string;
+        stepAttempt: (model: string, attempt: number) => string;
+        fallback: (from: string) => string;
+        subagent: (taskId: string, agent: string) => string;
+        subagentExternal: (taskId: string, agent: string, runner: string) => string;
+        background: string;
+        childMissing: string;
+        compaction: (trigger: string) => string;
+        compactionPlain: string;
+        retryWait: (delay: string, attempt: number) => string;
+        aux: {
+            cache_warm: string;
+            permission_classify: string;
+        };
+        auxGroup: (n: number) => string;
+        externalTurn: (turn: number, tools: number, files: number) => string;
+        more: (n: number) => string;
+    };
+    status: {
+        ok: string;
+        error: string;
+        aborted: string;
+        denied: string;
+        running: string;
+        retried: string;
+        interrupted: string;
+    };
+    detail: {
+        kind: string;
+        status: string;
+        start: string;
+        duration: string;
+        approx: string;
+        approxValue: string;
+        model: string;
+        attempt: string;
+        fallbackFrom: string;
+        ttft: string;
+        tps: string;
+        thinking: string;
+        stopReason: string;
+        error: string;
+        usage: string;
+        usageValue: (input: string, output: string, cacheRead: string, cacheWrite: string) => string;
+        cacheHit: string;
+        cost: string;
+        approval: string;
+        denied: string;
+        yes: string;
+        task: string;
+        runner: string;
+        background: string;
+        turns: string;
+        childFile: string;
+        childMissing: string;
+        tools: string;
+        files: string;
+        origin: string;
+        input: string;
+        output: string;
+        args: string;
+        result: string;
+        reason: string;
+        truncated: (length: number) => string;
+    };
+    html: {
+        docTitle: (sessionId: string) => string;
+        search: string;
+        noMatch: string;
+        jump: string;
+        zoomIn: string;
+        zoomOut: string;
+        zoomFit: string;
+        expandAll: string;
+        collapseAll: string;
+        legendTtft: string;
+        legendDecode: string;
+        legendTool: string;
+        legendAgent: string;
+        legendWait: string;
+        legendOther: string;
+        axisNote: string;
+        detailEmpty: string;
+        noContent: string;
+        previewDropped: string;
+        childPreviewOff: string;
+        footer: (version: string, generatedAt: string) => string;
+        keys: string;
+    };
+    cli: {
+        usage: string;
+        wrote: (path: string) => string;
+        openFailed: (reason: string) => string;
+        formatConflict: string;
+        badNow: (raw: string) => string;
+    };
+};

package/dist/i18n/messages/trace.js

@@ -0,0 +1,238 @@
+/**
+ * 消息目录：trace（键名规范见 docs/i18n.md）。[W6-C0 建空壳，W6-T1 填 TUI / line 模式文案，W6-T2 追加 HTML]
+ *
+ * en 是形状源；zh 用 `satisfies Messages<typeof en>`，缺键 / 多键 / 参数不符在 tsc 期报错。
+ * 整句一个键、禁止片段拼接；插值写成函数，条件分支写进函数体。
+ * 不译：ttft、tok/s、↑ ↓、模型名、工具名、任务 id、触发方式（threshold / overflow / manual）。
+ */
+import { plural } from "../format.js";
+export const en = {
+    title: "Trace",
+    /** 顶部汇总行。 */
+    summary: (turns, requests, tools) => `${plural(turns, "turn")} · ${plural(requests, "request")} · ${plural(tools, "tool call")}`,
+    cache: (percent) => `cache ${percent}`,
+    empty: "No turns yet",
+    /** 子轨迹标题（`/trace t2`）。 */
+    taskTitle: (taskId, agent) => `Trace · task ${taskId} ${agent}`,
+    taskNotFound: (taskId) => `No task ${taskId} in this session (see /tasks)`,
+    follow: { on: "following", off: "paused" },
+    hints: {
+        list: "↑↓ move · → expand · ← collapse · Enter details · f follow · Esc close",
+        listNarrow: "↑↓ → ← Enter f Esc",
+        detail: "↑↓ scroll · Esc back",
+    },
+    row: {
+        turn: (n, text) => `#${n} ${text}`,
+        turnOrigin: (n, origin, text) => `#${n} [${origin}] ${text}`,
+        step: (model) => `request ${model}`,
+        stepAttempt: (model, attempt) => `request ${model} (attempt ${attempt})`,
+        fallback: (from) => `fallback from ${from}`,
+        subagent: (taskId, agent) => `task ${taskId} ${agent}`,
+        subagentExternal: (taskId, agent, runner) => `task ${taskId} ${agent} (${runner})`,
+        background: "background",
+        childMissing: "child session missing",
+        compaction: (trigger) => `compaction (${trigger})`,
+        compactionPlain: "compaction",
+        retryWait: (delay, attempt) => `retry wait ${delay} (attempt ${attempt})`,
+        aux: { cache_warm: "cache warm-up", permission_classify: "permission classifier" },
+        auxGroup: (n) => `auxiliary requests: ${n}`,
+        externalTurn: (turn, tools, files) => `turn ${turn} · ${plural(tools, "tool")} · ${plural(files, "file")}`,
+        more: (n) => `… ${plural(n, "earlier turn")} (Enter to load)`,
+    },
+    status: {
+        ok: "done",
+        error: "failed",
+        aborted: "aborted",
+        denied: "denied",
+        running: "running",
+        retried: "retried",
+        interrupted: "interrupted",
+    },
+    detail: {
+        kind: "Kind",
+        status: "Status",
+        start: "Start",
+        duration: "Duration",
+        approx: "Timing",
+        approxValue: "estimated from entry times (no ama.trace)",
+        model: "Model",
+        attempt: "Attempt",
+        fallbackFrom: "Fallback from",
+        ttft: "Time to first token",
+        tps: "Throughput",
+        thinking: "Thinking level",
+        stopReason: "Stop reason",
+        error: "Error",
+        usage: "Tokens",
+        usageValue: (input, output, cacheRead, cacheWrite) => `in ${input} · out ${output} · cache read ${cacheRead} · cache write ${cacheWrite}`,
+        cacheHit: "Cache hit",
+        cost: "Cost",
+        approval: "Waiting for approval",
+        denied: "Denied before running",
+        yes: "yes",
+        task: "Task",
+        runner: "Runner",
+        background: "Background",
+        turns: "Turns",
+        childFile: "Child session",
+        childMissing: "missing or unreadable",
+        tools: "Tools",
+        files: "Files touched",
+        origin: "Origin",
+        input: "Input",
+        output: "Output",
+        args: "Arguments",
+        result: "Result",
+        reason: "Reason",
+        truncated: (length) => `… (truncated, ${length} characters in total)`,
+    },
+    /** [W6-T2] HTML 导出的静态文案（按导出时的语言渲染）。 */
+    html: {
+        docTitle: (sessionId) => `Trace · ${sessionId}`,
+        search: "Search",
+        noMatch: "No match",
+        jump: "Jump to turn",
+        zoomIn: "Zoom in",
+        zoomOut: "Zoom out",
+        zoomFit: "Fit",
+        expandAll: "Expand all",
+        collapseAll: "Collapse all",
+        legendTtft: "Time to first token",
+        legendDecode: "Decoding",
+        legendTool: "Tool",
+        legendAgent: "Subagent",
+        legendWait: "Retry wait",
+        legendOther: "Compaction / auxiliary",
+        axisNote: "Idle time between turns is compressed",
+        detailEmpty: "Select a row to see its details",
+        noContent: "Content omitted (--no-content)",
+        previewDropped: "Preview omitted: over the 4 MB preview budget",
+        childPreviewOff: "Child session previews are not embedded (use --children)",
+        footer: (version, generatedAt) => `Generated by ama ${version} at ${generatedAt}`,
+        keys: "↑↓ move · ←→ collapse / expand · / search · Ctrl + wheel zoom",
+    },
+    /** [W6-T2] `ama sessions trace`。 */
+    cli: {
+        usage: `Usage: ama sessions trace <id|file> [--html [file]] [--json] [--output <file>] [--open]
+                           [--branch leaf|all] [--no-content] [--children] [--now <ms>]
+                           [--session-dir <dir>]
+`,
+        wrote: (path) => `Trace written to ${path}\n`,
+        openFailed: (reason) => `Could not open a browser: ${reason}\n`,
+        formatConflict: "--html and --json are exclusive",
+        badNow: (raw) => `--now expects epoch milliseconds (got ${raw})`,
+    },
+};
+export const zh = {
+    title: "轨迹",
+    summary: (turns, requests, tools) => `${turns} 回合 · ${requests} 请求 · ${tools} 次工具`,
+    cache: (percent) => `缓存 ${percent}`,
+    empty: "还没有回合",
+    taskTitle: (taskId, agent) => `轨迹 · 任务 ${taskId} ${agent}`,
+    taskNotFound: (taskId) => `本会话没有任务 ${taskId}（见 /tasks）`,
+    follow: { on: "跟随中", off: "已暂停跟随" },
+    hints: {
+        list: "↑↓ 移动 · → 展开 · ← 折叠 · Enter 详情 · f 跟随 · Esc 关闭",
+        listNarrow: "↑↓ → ← Enter f Esc",
+        detail: "↑↓ 滚动 · Esc 返回",
+    },
+    row: {
+        turn: (n, text) => `#${n} ${text}`,
+        turnOrigin: (n, origin, text) => `#${n} [${origin}] ${text}`,
+        step: (model) => `请求 ${model}`,
+        stepAttempt: (model, attempt) => `请求 ${model}（第 ${attempt} 次）`,
+        fallback: (from) => `回退自 ${from}`,
+        subagent: (taskId, agent) => `任务 ${taskId} ${agent}`,
+        subagentExternal: (taskId, agent, runner) => `任务 ${taskId} ${agent}（${runner}）`,
+        background: "后台",
+        childMissing: "子会话缺失",
+        compaction: (trigger) => `压缩（${trigger}）`,
+        compactionPlain: "压缩",
+        retryWait: (delay, attempt) => `重试等待 ${delay}（第 ${attempt} 次）`,
+        aux: { cache_warm: "缓存保温", permission_classify: "权限分类" },
+        auxGroup: (n) => `辅助请求 ${n} 次`,
+        externalTurn: (turn, tools, files) => `回合 ${turn} · ${tools} 个工具 · ${files} 个文件`,
+        more: (n) => `… 更早的 ${n} 个回合（Enter 加载）`,
+    },
+    status: {
+        ok: "完成",
+        error: "失败",
+        aborted: "已中断",
+        denied: "已拒绝",
+        running: "进行中",
+        retried: "已重试",
+        interrupted: "未完成",
+    },
+    detail: {
+        kind: "类型",
+        status: "状态",
+        start: "开始",
+        duration: "耗时",
+        approx: "计时",
+        approxValue: "按条目时间推算（没有 ama.trace）",
+        model: "模型",
+        attempt: "尝试",
+        fallbackFrom: "回退自",
+        ttft: "首 token",
+        tps: "吞吐",
+        thinking: "思考级别",
+        stopReason: "停止原因",
+        error: "错误",
+        usage: "Token",
+        usageValue: (input, output, cacheRead, cacheWrite) => `输入 ${input} · 输出 ${output} · 缓存读 ${cacheRead} · 缓存写 ${cacheWrite}`,
+        cacheHit: "缓存命中",
+        cost: "费用",
+        approval: "等待审批",
+        denied: "执行前被拒",
+        yes: "是",
+        task: "任务",
+        runner: "运行方",
+        background: "后台",
+        turns: "轮数",
+        childFile: "子会话",
+        childMissing: "缺失或无法读取",
+        tools: "工具",
+        files: "改动文件",
+        origin: "来源",
+        input: "输入",
+        output: "输出",
+        args: "参数",
+        result: "结果",
+        reason: "原因",
+        truncated: (length) => `…（截断，原长 ${length} 字符）`,
+    },
+    html: {
+        docTitle: (sessionId) => `轨迹 · ${sessionId}`,
+        search: "搜索",
+        noMatch: "无匹配",
+        jump: "跳到回合",
+        zoomIn: "放大",
+        zoomOut: "缩小",
+        zoomFit: "适应宽度",
+        expandAll: "全部展开",
+        collapseAll: "全部折叠",
+        legendTtft: "首 token 等待",
+        legendDecode: "解码",
+        legendTool: "工具",
+        legendAgent: "子 Agent",
+        legendWait: "重试等待",
+        legendOther: "压缩 / 辅助请求",
+        axisNote: "回合之间的空闲时间已压缩",
+        detailEmpty: "选中一行查看详情",
+        noContent: "已省略正文（--no-content）",
+        previewDropped: "预览已省略：超出 4 MB 预览预算",
+        childPreviewOff: "未内嵌子会话预览（加 --children）",
+        footer: (version, generatedAt) => `由 ama ${version} 生成于 ${generatedAt}`,
+        keys: "↑↓ 移动 · ←→ 折叠 / 展开 · / 搜索 · Ctrl + 滚轮缩放",
+    },
+    cli: {
+        usage: `用法：ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [--open]
+                           [--branch leaf|all] [--no-content] [--children] [--now <毫秒>]
+                           [--session-dir <目录>]
+`,
+        wrote: (path) => `轨迹已写入 ${path}\n`,
+        openFailed: (reason) => `无法打开浏览器：${reason}\n`,
+        formatConflict: "--html 与 --json 不能同时使用",
+        badNow: (raw) => `--now 应为毫秒时间戳（收到 ${raw}）`,
+    },
+};

package/dist/i18n/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 消息目录的类型（docs/wave6-plan.md §5.1；docs/i18n.md）。[W6-C0]
+ *
+ * 每个领域文件导出 `en`（形状源）与 `zh`（`satisfies Messages<typeof en>`）：缺键、多键、函数参数个数 /
+ * 类型不符都在 `tsc --noEmit` 期报错——这就是覆盖率检查，不需要运行期脚本。
+ */
+/** 消息叶子：整句字符串，或返回整句的插值函数（参数类型由 en 决定）。 */
+export type MessageLeaf = string | ((...args: any[]) => string);
+/**
+ * 由 en 的形状推出另一种语言必须满足的形状：字符串叶子 → `string`，函数叶子 → 同参数签名返回 `string`，
+ * 对象 → 递归。
+ */
+export type Messages<T> = {
+    readonly [K in keyof T]: T[K] extends (...args: infer A) => string ? (...args: A) => string : T[K] extends string ? string : Messages<T[K]>;
+};

package/dist/i18n/types.js

@@ -0,0 +1,7 @@
+/**
+ * 消息目录的类型（docs/wave6-plan.md §5.1；docs/i18n.md）。[W6-C0]
+ *
+ * 每个领域文件导出 `en`（形状源）与 `zh`（`satisfies Messages<typeof en>`）：缺键、多键、函数参数个数 /
+ * 类型不符都在 `tsc --noEmit` 期报错——这就是覆盖率检查，不需要运行期脚本。
+ */
+export {};

package/dist/index.d.ts

@@ -26,6 +26,12 @@ export type * from "./permissions/types.js";
 export type * from "./host/types.js";
 export type * from "./config/types.js";
 export type * from "./checkpoints/types.js";
+export type * from "./trace/types.js";
+export { TRACE_CUSTOM_TYPE } from "./trace/types.js";
+export { buildTrace, loadSubagentTrace } from "./trace/build.js";
+export type { BuildTraceOptions, LiveOverlay, TraceInput } from "./trace/build.js";
+export type { TracePreview } from "./trace/preview.js";
+export type { Locale } from "./i18n/index.js";
 export type { AmaErrorOptions, ErrorCode, KnownErrorCode } from "./errors.js";
 export type { Runtime, RuntimeMode, ResolvedPaths, TrustState, LoadedResources, } from "./cli/runtime.js";
 export { createAgentSession, createRuntime } from "./sdk.js";

package/dist/index.js

@@ -16,6 +16,8 @@ export { PERMISSION_MODES_STRICT_FIRST } from "./permissions/types.js";
 export { ExitCode, describeExitCode } from "./cli/exit-codes.js";
 export { defineTool } from "./tools/types.js";
 export { validateSchema, checkSchemaSubset, formatSchemaErrors } from "./agent/schema.js";
+export { TRACE_CUSTOM_TYPE } from "./trace/types.js";
+export { buildTrace, loadSubagentTrace } from "./trace/build.js"; // [W6-T1]
 // SDK（B6 追加）
 export { createAgentSession, createRuntime } from "./sdk.js";
 export { AgentSessionImpl } from "./agent/session.js";

package/dist/memory/edit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 用户在编辑器里改记忆（`/memory edit`、`ama memory edit`）。[W6-M]
+ *
+ * - 目标是已有条目：编辑全文副本，存回时与模型写入同一套规范化、凭据检查与上限（store.saveRaw）；
+ * - 目标是作用域名（或省略 = 第一个作用域）：编辑新条目模板，按 `name` 生成文件名（重名加 `-2`、`-3`…）；
+ * - 编辑器非零退出 → cancelled；内容没变 / 新条目没写名字 → unchanged。
+ * 编辑器在临时文件上工作（modes/interactive/external-editor.ts），作用域目录里不会留下半截文件。
+ */
+import type { MemoryStore } from "./store.js";
+export type EditOutcome = {
+    status: "saved";
+    path: string;
+} | {
+    status: "unchanged";
+} | {
+    status: "cancelled";
+} | {
+    status: "not_found";
+    message: string;
+};
+/** 编辑器：给全文与临时文件名，返回改后的全文；没保存返回 undefined。 */
+export type EditText = (text: string, fileName: string) => Promise<string | undefined>;
+export declare function slugify(name: string): string;
+export declare function editMemory(store: MemoryStore, target: string | undefined, edit: EditText): Promise<EditOutcome>;

package/dist/memory/edit.js

@@ -0,0 +1,63 @@
+/**
+ * 用户在编辑器里改记忆（`/memory edit`、`ama memory edit`）。[W6-M]
+ *
+ * - 目标是已有条目：编辑全文副本，存回时与模型写入同一套规范化、凭据检查与上限（store.saveRaw）；
+ * - 目标是作用域名（或省略 = 第一个作用域）：编辑新条目模板，按 `name` 生成文件名（重名加 `-2`、`-3`…）；
+ * - 编辑器非零退出 → cancelled；内容没变 / 新条目没写名字 → unchanged。
+ * 编辑器在临时文件上工作（modes/interactive/external-editor.ts），作用域目录里不会留下半截文件。
+ */
+import { parseEntry } from "./frontmatter.js";
+import { MEMORY_SCOPE_ORDER } from "./paths.js";
+import { findOne } from "./report.js";
+export function slugify(name) {
+    const slug = name
+        .normalize("NFKD")
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return slug === "" ? "note" : slug;
+}
+function template(scope) {
+    const type = scope === "user" ? "user" : "project";
+    return `---\nname: \ndescription: \ntype: ${type}\n---\n\n`;
+}
+function freeFile(store, scope, base) {
+    const taken = new Set(store.entries(scope).map((e) => e.file));
+    if (!taken.has(`${base}.md`))
+        return `${base}.md`;
+    for (let n = 2;; n++)
+        if (!taken.has(`${base}-${n}.md`))
+            return `${base}-${n}.md`;
+}
+export async function editMemory(store, target, edit) {
+    const scopes = store.scopes();
+    const asScope = MEMORY_SCOPE_ORDER.find((s) => s === target && scopes.includes(s));
+    if (target === undefined || asScope !== undefined) {
+        const scope = asScope ?? scopes[0];
+        if (scope === undefined)
+            return { status: "unchanged" };
+        const before = template(scope);
+        const after = await edit(before, "memory.md");
+        if (after === undefined)
+            return { status: "cancelled" };
+        const name = (parseEntry(after).meta["name"] ?? "").trim();
+        if (after === before || name === "")
+            return { status: "unchanged" };
+        const file = freeFile(store, scope, slugify(name));
+        return { status: "saved", path: (await store.saveRaw(scope, file, after)).path };
+    }
+    const found = findOne(store, target);
+    if (!found.ok)
+        return { status: "not_found", message: found.message };
+    const before = store.readRaw(found.entry) ?? "";
+    const after = await edit(before, found.entry.file.split("/").at(-1) ?? "memory.md");
+    if (after === undefined)
+        return { status: "cancelled" };
+    if (after === before)
+        return { status: "unchanged" };
+    return {
+        status: "saved",
+        path: (await store.saveRaw(found.entry.scope, found.entry.file, after)).path,
+    };
+}

package/dist/memory/frontmatter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 记忆条目的 frontmatter（docs/wave6-plan.md §3.2）。[W6-M]
+ *
+ * ```markdown
+ * ---
+ * name: 测试数据库重置
+ * description: 跑集成测试前要先执行的重置命令
+ * type: project        # user | feedback | project | reference
+ * updated: 2026-10-03
+ * ---
+ *
+ * 正文
+ * ```
+ *
+ * 只认单行 `key: value`（值可带成对引号）；未知键保留原顺序。写入时规范化：`name` 缺省用文件名、
+ * `description` 缺省用正文首个非空行、`type` 不在四类里用作用域缺省、`updated` 总是写当天。
+ */
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export interface ParsedEntry {
+    meta: Record<string, string>;
+    body: string;
+}
+export declare function parseEntry(text: string): ParsedEntry;
+/** 正文首个非空行（去掉标题井号），截到 150 字符。 */
+export declare function firstLineOf(body: string): string;
+export declare function serializeEntry(meta: Record<string, string>, body: string): string;
+/** 写入前规范化：补全 name / description / type，`updated` 写 `today`。 */
+export declare function normalizeEntry(text: string, defaults: {
+    name: string;
+    type: MemoryType;
+    today: string;
+}): {
+    text: string;
+    meta: Record<string, string>;
+    body: string;
+};