@armadra/agent 0.5.1 → 0.6.1

package/dist/memory/frontmatter.js

@@ -0,0 +1,79 @@
+/**
+ * 记忆条目的 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 const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+const ORDER = ["name", "description", "type", "updated"];
+const MAX_DESCRIPTION = 150;
+function unquote(value) {
+    const v = value.trim();
+    if (v.length >= 2 &&
+        ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))))
+        return v.slice(1, -1);
+    return v;
+}
+export function parseEntry(text) {
+    const normalized = text.replace(/\r\n/g, "\n").replace(/^\uFEFF/, "");
+    if (!normalized.startsWith("---\n"))
+        return { meta: {}, body: normalized };
+    const end = normalized.indexOf("\n---", 3);
+    if (end < 0)
+        return { meta: {}, body: normalized };
+    const after = normalized.slice(end + 4);
+    if (after !== "" && !after.startsWith("\n"))
+        return { meta: {}, body: normalized };
+    const meta = {};
+    for (const line of normalized.slice(4, end).split("\n")) {
+        const m = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line);
+        if (m?.[1] !== undefined)
+            meta[m[1]] = unquote(m[2] ?? "");
+    }
+    return { meta, body: after.replace(/^\n+/, "") };
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** 正文首个非空行（去掉标题井号），截到 150 字符。 */
+export function firstLineOf(body) {
+    for (const raw of body.split("\n")) {
+        const line = oneLine(raw.replace(/^#+\s*/, ""));
+        if (line !== "")
+            return line.length > MAX_DESCRIPTION ? `${line.slice(0, MAX_DESCRIPTION - 1)}…` : line;
+    }
+    return "";
+}
+export function serializeEntry(meta, body) {
+    const keys = [
+        ...ORDER.filter((k) => meta[k] !== undefined),
+        ...Object.keys(meta).filter((k) => !ORDER.includes(k)),
+    ];
+    const lines = keys.map((k) => `${k}: ${oneLine(meta[k] ?? "")}`);
+    return `---\n${lines.join("\n")}\n---\n\n${body.trim()}\n`;
+}
+/** 写入前规范化：补全 name / description / type，`updated` 写 `today`。 */
+export function normalizeEntry(text, defaults) {
+    const parsed = parseEntry(text);
+    const meta = { ...parsed.meta };
+    const body = parsed.body.trim();
+    if (oneLine(meta["name"] ?? "") === "")
+        meta["name"] = defaults.name;
+    if (oneLine(meta["description"] ?? "") === "")
+        meta["description"] = firstLineOf(body);
+    if (!MEMORY_TYPES.includes(meta["type"] ?? ""))
+        meta["type"] = defaults.type;
+    meta["updated"] = defaults.today;
+    return { text: serializeEntry(meta, body), meta, body };
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 作用域条目列表与 `MEMORY.md` 索引（docs/wave6-plan.md §3.2）。[W6-M]
+ *
+ * - 条目 = 作用域目录（含子目录）里的 `*.md`，跳过 `MEMORY.md`、隐藏文件 / 目录与符号链接；
+ * - 排序：`updated` 降序，同日按文件路径；
+ * - `MEMORY.md`：`- [name](file.md) — description` 一行一条，写操作后在作用域锁内重建（幂等，内容不变不写）。
+ *   节渲染不读它，直接列条目（用户手改条目后 `/memory reload` 或下次会话即生效）。
+ */
+import { type MemoryScope } from "./paths.js";
+export interface MemoryEntry {
+    scope: MemoryScope;
+    /** 作用域内的相对路径（`/` 分隔），如 `prefers-pnpm.md`。 */
+    file: string;
+    name: string;
+    description: string;
+    type?: string;
+    /** `YYYY-MM-DD`（缺 frontmatter 时取文件修改日期）。 */
+    updated: string;
+    bytes: number;
+}
+/** 作用域里全部条目的相对路径（目录不存在 → 空）。`under` 限定子目录。 */
+export declare function entryFiles(root: string, under?: string): string[];
+export declare function readEntry(scope: MemoryScope, root: string, file: string): MemoryEntry | undefined;
+export declare function sortEntries(entries: MemoryEntry[]): MemoryEntry[];
+export declare function listEntries(scope: MemoryScope, root: string, under?: string): MemoryEntry[];
+export declare function renderIndexFile(entries: readonly MemoryEntry[]): string;
+/** 重建 `MEMORY.md`（在作用域锁内调用；内容不变不写）。 */
+export declare function rebuildIndex(scope: MemoryScope, root: string): void;

package/dist/memory/index.js

@@ -0,0 +1,126 @@
+/**
+ * 作用域条目列表与 `MEMORY.md` 索引（docs/wave6-plan.md §3.2）。[W6-M]
+ *
+ * - 条目 = 作用域目录（含子目录）里的 `*.md`，跳过 `MEMORY.md`、隐藏文件 / 目录与符号链接；
+ * - 排序：`updated` 降序，同日按文件路径；
+ * - `MEMORY.md`：`- [name](file.md) — description` 一行一条，写操作后在作用域锁内重建（幂等，内容不变不写）。
+ *   节渲染不读它，直接列条目（用户手改条目后 `/memory reload` 或下次会话即生效）。
+ */
+import { lstatSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { firstLineOf, parseEntry } from "./frontmatter.js";
+import { INDEX_FILE } from "./paths.js";
+const MAX_DEPTH = 4;
+function isoDate(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function walk(dir, prefix, depth, out) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names.sort()) {
+        if (name.startsWith("."))
+            continue;
+        const abs = join(dir, name);
+        let info;
+        try {
+            info = lstatSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (info.isSymbolicLink())
+            continue;
+        const rel = prefix === "" ? name : `${prefix}/${name}`;
+        if (info.isDirectory()) {
+            if (depth < MAX_DEPTH)
+                walk(abs, rel, depth + 1, out);
+        }
+        else if (info.isFile() && name.endsWith(".md") && !(prefix === "" && name === INDEX_FILE)) {
+            out.push(rel);
+        }
+    }
+}
+/** 作用域里全部条目的相对路径（目录不存在 → 空）。`under` 限定子目录。 */
+export function entryFiles(root, under = "") {
+    const out = [];
+    walk(under === "" ? root : join(root, ...under.split("/")), under, under.split("/").length, out);
+    return out;
+}
+function stem(file) {
+    return (file.split("/").at(-1) ?? file).replace(/\.md$/, "");
+}
+export function readEntry(scope, root, file) {
+    const abs = join(root, ...file.split("/"));
+    let text;
+    let mtime;
+    try {
+        text = readFileSync(abs, "utf8");
+        mtime = lstatSync(abs).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+    const { meta, body } = parseEntry(text);
+    const updated = /^\d{4}-\d{2}-\d{2}$/.test(meta["updated"] ?? "")
+        ? meta["updated"]
+        : isoDate(mtime);
+    const entry = {
+        scope,
+        file,
+        name: (meta["name"] ?? "").trim() || stem(file),
+        description: (meta["description"] ?? "").trim() || firstLineOf(body),
+        updated,
+        bytes: Buffer.byteLength(text, "utf8"),
+    };
+    if (meta["type"] !== undefined && meta["type"] !== "")
+        entry.type = meta["type"];
+    return entry;
+}
+export function sortEntries(entries) {
+    return entries.sort((a, b) => a.updated === b.updated ? a.file.localeCompare(b.file) : a.updated < b.updated ? 1 : -1);
+}
+export function listEntries(scope, root, under = "") {
+    const entries = [];
+    for (const file of entryFiles(root, under)) {
+        const entry = readEntry(scope, root, file);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return sortEntries(entries);
+}
+function clean(text) {
+    return text.replace(/\s+/g, " ").replace(/[[\]]/g, "").trim();
+}
+export function renderIndexFile(entries) {
+    const lines = entries.map((e) => `- [${clean(e.name)}](${e.file})${e.description === "" ? "" : ` — ${clean(e.description)}`}`);
+    return [
+        "# Memory index",
+        "",
+        "<!-- Maintained by ama after each memory write; edit the entries, not this file. -->",
+        "",
+        ...(lines.length === 0 ? ["(no entries)"] : lines),
+        "",
+    ].join("\n");
+}
+/** 重建 `MEMORY.md`（在作用域锁内调用；内容不变不写）。 */
+export function rebuildIndex(scope, root) {
+    const text = renderIndexFile(listEntries(scope, root));
+    const path = join(root, INDEX_FILE);
+    let current;
+    try {
+        current = readFileSync(path, "utf8");
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === text)
+        return;
+    const tmp = join(root, `.${INDEX_FILE}.${process.pid}.tmp`);
+    writeFileSync(tmp, text, { mode: 0o600 });
+    renameSync(tmp, path);
+}

package/dist/memory/lock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 每作用域一把锁（docs/wave6-plan.md §3.2）。[W6-M]
+ *
+ * 进程内按目录串行（`tools/file-mutex.ts`）；跨进程用作用域目录里的 `.lock`（`O_EXCL` 创建，写 pid）。
+ * 等锁至多 `timeoutMs`（缺省 5 s）；锁文件超过 `staleMs`（缺省 30 s）视为陈旧，删掉重试。
+ * 写操作（create / str_replace / delete 与索引重建）都在锁内；读不加锁（原子 rename 保证读到整文件）。
+ */
+export declare const LOCK_FILE = ".lock";
+export declare class MemoryLockError extends Error {
+    readonly code = "locked";
+}
+export interface LockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    now?(): number;
+}
+export declare function withScopeLock<T>(dir: string, fn: () => Promise<T> | T, options?: LockOptions): Promise<T>;

package/dist/memory/lock.js

@@ -0,0 +1,62 @@
+/**
+ * 每作用域一把锁（docs/wave6-plan.md §3.2）。[W6-M]
+ *
+ * 进程内按目录串行（`tools/file-mutex.ts`）；跨进程用作用域目录里的 `.lock`（`O_EXCL` 创建，写 pid）。
+ * 等锁至多 `timeoutMs`（缺省 5 s）；锁文件超过 `staleMs`（缺省 30 s）视为陈旧，删掉重试。
+ * 写操作（create / str_replace / delete 与索引重建）都在锁内；读不加锁（原子 rename 保证读到整文件）。
+ */
+import { closeSync, mkdirSync, openSync, rmSync, statSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { withFileMutex } from "../tools/file-mutex.js";
+export const LOCK_FILE = ".lock";
+export class MemoryLockError extends Error {
+    code = "locked";
+}
+function stale(path, staleMs, now) {
+    try {
+        return now - statSync(path).mtimeMs > staleMs;
+    }
+    catch {
+        return true;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function withScopeLock(dir, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const now = options.now ?? Date.now;
+    const lock = join(dir, LOCK_FILE);
+    return withFileMutex(lock, async () => {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const start = now();
+        for (;;) {
+            try {
+                const fd = openSync(lock, "wx", 0o600);
+                try {
+                    writeSync(fd, String(process.pid));
+                }
+                finally {
+                    closeSync(fd);
+                }
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (stale(lock, staleMs, now())) {
+                    rmSync(lock, { force: true });
+                    continue;
+                }
+                if (now() - start > timeoutMs)
+                    throw new MemoryLockError("memory is locked by another process; try again");
+                await sleep(25);
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            rmSync(lock, { force: true });
+        }
+    });
+}

package/dist/memory/paths.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 记忆的目录与逻辑路径（docs/wave6-plan.md §3.2、D9、D11）。[W6-M]
+ *
+ * - 独立终端：`<dataDir>/memory/user/` 与 `<dataDir>/memory/projects/<slug>-<sha8>/`；sha8 = 项目根真实路径的
+ *   sha256 前 8 位。项目根：git 顶层（worktree 取主仓库，经 `commondir`）；子模块取子模块自己的检出；
+ *   不在 git 里取 cwd。不起 git 进程。
+ * - 嵌入宿主：只有 `workspace` 一个作用域，映射到 profile / SDK 给的 `dir`。
+ * - 模型看到的是逻辑路径 `/memories/<scope>/<file>.md`。解析时拒绝 `..`、`.`、隐藏段、反斜杠、控制字符、
+ *   百分号编码（`%2e%2e%2f` 之类）、非 `.md` 文件；映射后的绝对路径必须仍在作用域根内；根以下任何一段是
+ *   符号链接都拒绝（`assertNoSymlink`，访问磁盘前调用）。
+ */
+export type MemoryScope = "user" | "project" | "workspace";
+/** 作用域的固定顺序（节、列表、CLI 输出都按它排）。 */
+export declare const MEMORY_SCOPE_ORDER: readonly MemoryScope[];
+export declare const MEMORY_ROOT = "/memories";
+/** 每个作用域自动重建的索引文件。 */
+export declare const INDEX_FILE = "MEMORY.md";
+/** 项目作用域目录里记下项目根（`{ root, createdAt }`）。 */
+export declare const META_FILE = "meta.json";
+/** 作用域 → 绝对目录（只列启用的作用域）。 */
+export type ScopeRoots = Partial<Record<MemoryScope, string>>;
+/** 路径不合法（给模型的英文说明）。 */
+export declare class MemoryPathError extends Error {
+    readonly code = "invalid_path";
+}
+/** 记忆按哪个目录分桶：git 顶层（worktree → 主仓库）；不在 git 里取 cwd。 */
+export declare function projectRootOf(cwd: string): string;
+/** `<slug>-<sha8>`：slug 取目录名（只留 `[A-Za-z0-9._-]`，至多 40 个字符）。 */
+export declare function projectBucket(root: string): string;
+export declare function memoryBaseDir(dataDir: string): string;
+/** 独立终端的作用域目录（不创建；首次写入时才建）。 */
+export declare function standaloneRoots(input: {
+    dataDir: string;
+    /** 项目根（`projectRootOf(cwd)`）；undefined = 不启用项目作用域。 */
+    projectRoot?: string | undefined;
+    user: boolean;
+}): ScopeRoots;
+export declare function logicalPath(scope: MemoryScope, file?: string): string;
+export type MemoryTarget = {
+    kind: "root";
+} | {
+    kind: "dir";
+    scope: MemoryScope;
+    root: string;
+    file: string;
+    abs: string;
+} | {
+    kind: "file";
+    scope: MemoryScope;
+    root: string;
+    file: string;
+    abs: string;
+};
+/** 逻辑路径 → 目标；不合法抛 MemoryPathError。 */
+export declare function parseMemoryPath(path: unknown, roots: ScopeRoots): MemoryTarget;
+/** 作用域根以下（不含根）的每一段若已存在且是符号链接，拒绝。 */
+export declare function assertNoSymlink(root: string, abs: string): void;

package/dist/memory/paths.js

@@ -0,0 +1,175 @@
+/**
+ * 记忆的目录与逻辑路径（docs/wave6-plan.md §3.2、D9、D11）。[W6-M]
+ *
+ * - 独立终端：`<dataDir>/memory/user/` 与 `<dataDir>/memory/projects/<slug>-<sha8>/`；sha8 = 项目根真实路径的
+ *   sha256 前 8 位。项目根：git 顶层（worktree 取主仓库，经 `commondir`）；子模块取子模块自己的检出；
+ *   不在 git 里取 cwd。不起 git 进程。
+ * - 嵌入宿主：只有 `workspace` 一个作用域，映射到 profile / SDK 给的 `dir`。
+ * - 模型看到的是逻辑路径 `/memories/<scope>/<file>.md`。解析时拒绝 `..`、`.`、隐藏段、反斜杠、控制字符、
+ *   百分号编码（`%2e%2e%2f` 之类）、非 `.md` 文件；映射后的绝对路径必须仍在作用域根内；根以下任何一段是
+ *   符号链接都拒绝（`assertNoSymlink`，访问磁盘前调用）。
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+/** 作用域的固定顺序（节、列表、CLI 输出都按它排）。 */
+export const MEMORY_SCOPE_ORDER = ["user", "project", "workspace"];
+export const MEMORY_ROOT = "/memories";
+/** 每个作用域自动重建的索引文件。 */
+export const INDEX_FILE = "MEMORY.md";
+/** 项目作用域目录里记下项目根（`{ root, createdAt }`）。 */
+export const META_FILE = "meta.json";
+const MAX_PATH = 512;
+const MAX_SEGMENT = 128;
+/** 路径不合法（给模型的英文说明）。 */
+export class MemoryPathError extends Error {
+    code = "invalid_path";
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function real(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** 记忆按哪个目录分桶：git 顶层（worktree → 主仓库）；不在 git 里取 cwd。 */
+export function projectRootOf(cwd) {
+    const start = real(cwd);
+    let dir = start;
+    for (;;) {
+        const dotGit = join(dir, ".git");
+        let kind;
+        try {
+            const info = statSync(dotGit);
+            kind = info.isDirectory() ? "dir" : info.isFile() ? "file" : undefined;
+        }
+        catch {
+            kind = undefined;
+        }
+        if (kind === "dir")
+            return dir;
+        if (kind === "file") {
+            const match = /^gitdir:\s*(.+?)\s*$/m.exec(readText(dotGit));
+            const target = match?.[1];
+            if (target !== undefined) {
+                const gitDir = isAbsolute(target) ? target : resolve(dir, target);
+                const common = readText(join(gitDir, "commondir")).trim();
+                if (common !== "") {
+                    const commonDir = real(isAbsolute(common) ? common : resolve(gitDir, common));
+                    return basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
+                }
+            }
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return start;
+        dir = parent;
+    }
+}
+/** `<slug>-<sha8>`：slug 取目录名（只留 `[A-Za-z0-9._-]`，至多 40 个字符）。 */
+export function projectBucket(root) {
+    const slug = basename(root)
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^[-.]+/, "")
+        .slice(0, 40)
+        .replace(/-+$/, "") || "root";
+    const hash = createHash("sha256").update(root).digest("hex").slice(0, 8);
+    return `${slug}-${hash}`;
+}
+export function memoryBaseDir(dataDir) {
+    return join(dataDir, "memory");
+}
+/** 独立终端的作用域目录（不创建；首次写入时才建）。 */
+export function standaloneRoots(input) {
+    const base = memoryBaseDir(input.dataDir);
+    const roots = {};
+    if (input.user)
+        roots.user = join(base, "user");
+    if (input.projectRoot !== undefined)
+        roots.project = join(base, "projects", projectBucket(input.projectRoot));
+    return roots;
+}
+export function logicalPath(scope, file) {
+    return file === undefined || file === ""
+        ? `${MEMORY_ROOT}/${scope}`
+        : `${MEMORY_ROOT}/${scope}/${file}`;
+}
+function scopesText(roots) {
+    const names = MEMORY_SCOPE_ORDER.filter((s) => roots[s] !== undefined);
+    return names.length === 0 ? "(none)" : names.map((s) => logicalPath(s)).join(", ");
+}
+/** 逻辑路径 → 目标；不合法抛 MemoryPathError。 */
+export function parseMemoryPath(path, roots) {
+    if (typeof path !== "string" || path === "")
+        throw new MemoryPathError("path must be a non-empty string such as /memories/user/note.md");
+    if (path.length > MAX_PATH)
+        throw new MemoryPathError("path is too long");
+    if (path.includes("\\"))
+        throw new MemoryPathError("path must use forward slashes");
+    if (/[\u0000-\u001f\u007f]/.test(path))
+        throw new MemoryPathError("path contains control characters");
+    if (/%[0-9a-fA-F]{2}/.test(path))
+        throw new MemoryPathError("path must not be URL-encoded");
+    const trimmed = path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+    if (trimmed === MEMORY_ROOT)
+        return { kind: "root" };
+    if (!trimmed.startsWith(`${MEMORY_ROOT}/`))
+        throw new MemoryPathError(`path must start with ${MEMORY_ROOT}/ (scopes: ${scopesText(roots)})`);
+    const segments = trimmed.slice(MEMORY_ROOT.length + 1).split("/");
+    for (const segment of segments) {
+        if (segment === "" || segment === "." || segment === "..")
+            throw new MemoryPathError("path must not contain empty, '.' or '..' segments");
+        if (segment.startsWith("."))
+            throw new MemoryPathError("hidden files are not allowed");
+        if (segment.length > MAX_SEGMENT)
+            throw new MemoryPathError("path segment is too long");
+    }
+    const scope = segments[0];
+    const root = MEMORY_SCOPE_ORDER.includes(scope) ? roots[scope] : undefined;
+    if (root === undefined)
+        throw new MemoryPathError(`unknown memory scope "${segments[0]}"; use ${scopesText(roots)}`);
+    const rest = segments.slice(1);
+    const abs = rest.length === 0 ? root : join(root, ...rest);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        throw new MemoryPathError("path escapes memory");
+    const file = rest.join("/");
+    const last = rest.at(-1);
+    if (last !== undefined && last.toLowerCase().endsWith(".md")) {
+        if (!last.endsWith(".md"))
+            throw new MemoryPathError("memory files must end with .md");
+        return { kind: "file", scope, root, file, abs };
+    }
+    if (last !== undefined && /\.[A-Za-z0-9]+$/.test(last))
+        throw new MemoryPathError("memory files must be Markdown (.md)");
+    return { kind: "dir", scope, root, file, abs };
+}
+/** 作用域根以下（不含根）的每一段若已存在且是符号链接，拒绝。 */
+export function assertNoSymlink(root, abs) {
+    const rel = relative(root, abs);
+    if (rel === "")
+        return;
+    let current = root;
+    for (const part of rel.split(/[\\/]/)) {
+        current = join(current, part);
+        let isLink = false;
+        try {
+            isLink = lstatSync(current).isSymbolicLink();
+        }
+        catch {
+            return;
+        }
+        if (isLink)
+            throw new MemoryPathError("symbolic links are not allowed in memory");
+    }
+}

package/dist/memory/report.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 记忆的人读文本（`/memory` 行式、`ama memory`、面板共用）。[W6-M] 界面层：文案走 `msg().memory`。
+ */
+import type { MemoryEntry } from "./index.js";
+import { type MemoryScope } from "./paths.js";
+import type { MemoryRuntime } from "./runtime.js";
+import { type MemoryStore } from "./store.js";
+export declare const STALE_DAYS = 90;
+export declare function scopeLabel(scope: MemoryScope): string;
+/** 条目是否超过 90 天未更新（`/memory` 标灰）。 */
+export declare function isStale(entry: Pick<MemoryEntry, "updated">, now: number): boolean;
+/** 存储错误 → 本地化说明；不是存储错误时原样抛出。 */
+export declare function memoryErrorText(error: unknown): string;
+export type FindResult = {
+    ok: true;
+    entry: MemoryEntry;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function findOne(store: MemoryStore, name: string): FindResult;
+export interface ScopeSummary {
+    scope: MemoryScope;
+    entries: MemoryEntry[];
+    indexBytes: number;
+    omitted: number;
+}
+export declare function scopeSummaries(store: MemoryStore, scopes?: MemoryScope[]): ScopeSummary[];
+/** 纯文本列表（行式 `/memory`、`ama memory list`）。 */
+export declare function listText(store: MemoryStore, options?: {
+    scopes?: MemoryScope[];
+    now?: number;
+    notes?: string[];
+}): string;
+/** 运行期附加说明：项目作用域因未信任跳过、本会话禁止写入。 */
+export declare function runtimeNotes(runtime: MemoryRuntime): string[];

package/dist/memory/report.js

@@ -0,0 +1,86 @@
+/**
+ * 记忆的人读文本（`/memory` 行式、`ama memory`、面板共用）。[W6-M] 界面层：文案走 `msg().memory`。
+ */
+import { formatBytes } from "../checkpoints/gc.js";
+import { msg } from "../i18n/index.js";
+import { MemoryLockError } from "./lock.js";
+import { logicalPath } from "./paths.js";
+import { scopeIndex } from "./section.js";
+import { MemoryError } from "./store.js";
+export const STALE_DAYS = 90;
+export function scopeLabel(scope) {
+    return msg().memory.scope[scope];
+}
+/** 条目是否超过 90 天未更新（`/memory` 标灰）。 */
+export function isStale(entry, now) {
+    const at = Date.parse(`${entry.updated}T00:00:00Z`);
+    return Number.isFinite(at) && now - at > STALE_DAYS * 86_400_000;
+}
+/** 存储错误 → 本地化说明；不是存储错误时原样抛出。 */
+export function memoryErrorText(error) {
+    const m = msg().memory.error;
+    if (error instanceof MemoryLockError)
+        return m.locked;
+    if (!(error instanceof MemoryError))
+        throw error;
+    const d = error.detail ?? {};
+    switch (error.code) {
+        case "credential":
+            return m.credential(String(d["kind"] ?? "secret"));
+        case "too_large":
+            return m.tooLarge(Number(d["bytes"]), Number(d["limit"]));
+        case "too_many":
+            return m.tooMany(Number(d["limit"]));
+        default:
+            return m.other(error.message);
+    }
+}
+export function findOne(store, name) {
+    const m = msg().memory.command;
+    const found = store.find(name);
+    if (found.length === 0)
+        return { ok: false, message: m.notFound(name) };
+    if (found.length > 1)
+        return {
+            ok: false,
+            message: m.ambiguous(name, found.map((e) => `${e.scope}/${e.file}`).join(", ")),
+        };
+    return { ok: true, entry: found[0] };
+}
+export function scopeSummaries(store, scopes = store.scopes()) {
+    return scopes.map((scope) => {
+        const entries = store.entries(scope);
+        const index = scopeIndex(scope, entries, store.limits.indexMaxBytes);
+        return { scope, entries, indexBytes: index.bytes, omitted: index.omitted };
+    });
+}
+/** 纯文本列表（行式 `/memory`、`ama memory list`）。 */
+export function listText(store, options = {}) {
+    const m = msg().memory.panel;
+    const now = options.now ?? Date.now();
+    const lines = [];
+    for (const s of scopeSummaries(store, options.scopes)) {
+        lines.push(m.scopeLine(`${scopeLabel(s.scope)} ${logicalPath(s.scope)}/`, s.entries.length, formatBytes(s.indexBytes), formatBytes(store.limits.indexMaxBytes)));
+        if (s.entries.length === 0)
+            lines.push(`  ${m.noEntries}`);
+        for (const e of s.entries) {
+            const stale = isStale(e, now) ? ` (${m.stale})` : "";
+            const description = e.description === "" ? "" : ` — ${e.description}`;
+            lines.push(`  ${e.name} [${e.file}]${description} · ${m.entryUpdated(e.updated)}${stale}`);
+        }
+        if (s.omitted > 0)
+            lines.push(`  ${m.truncated(s.omitted)}`);
+    }
+    lines.push(...(options.notes ?? []));
+    return lines.join("\n");
+}
+/** 运行期附加说明：项目作用域因未信任跳过、本会话禁止写入。 */
+export function runtimeNotes(runtime) {
+    const m = msg().memory.panel;
+    const notes = [];
+    if (runtime.skipped.some((s) => s.reason === "untrusted"))
+        notes.push(m.untrusted);
+    if (!runtime.writesEnabled)
+        notes.push(m.writesOff);
+    return notes;
+}