@momenttttt/pi-zcode-memory 0.0.0-stage → 0.1.0

package/src/resolve.ts

@@ -0,0 +1,130 @@
+/**
+ * 记忆目录定位的三级回退（设计文档 §5.1）：
+ *
+ *   1. 配置里的 `dir`（最高优先级，任何异常场景的兜底）
+ *   2. 按路径算法算出的目录**存在** → 用它
+ *   3. 计算路径不存在时，`memories/projects/` 下若恰好一个 `<slug>-*` 目录 → 用它并警告
+ *      都没有 → 视为"该项目尚无记忆"，不创建目录
+ *   4. 第 3 步失败但存在 `project-*` 目录 → 提示目录可能是按 workspace identity 建的
+ *      （slug 固定为 `project`，hash 输入不是工作区路径）
+ *
+ * 只做字符串路径判定，不做 realpath / `~` 展开：hash 的输入就是 `resolve(cwd)` 这个字符串，
+ * realpath 会把符号链接、短路径折成另一种写法，算出来的目录反而对不上。
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  computeMemoryDir,
+  computeProjectDirParts,
+  projectsRootOf,
+  resolveZcodeStorageRoot,
+  type MemoryDirInput,
+} from "./paths.ts";
+
+export type MemoryDirSource = "config" | "computed" | "fallback" | "none";
+
+export interface MemoryDirResolution {
+  /** 最终使用的记忆目录；`none` 时为 undefined。 */
+  dir: string | undefined;
+  source: MemoryDirSource;
+  /** 按算法算出的目录（`memory_write` 在 `none` 时按它创建）。 */
+  computedDir: string;
+  /** `<storageRoot>/memories/projects`，回退扫描与提示用。 */
+  projectsRoot: string;
+  /** 计算路径与账户目录不一致时为什么。 */
+  warnings: string[];
+}
+
+export interface ResolveMemoryDirOptions {
+  cwd: string;
+  /** 显式配置的目录。 */
+  configDir?: string;
+  /** 覆盖 home（测试用）。默认 `homedir()`。 */
+  homeDir?: string;
+  /** 覆盖存储根（测试用）；给了就不再由 homeDir 推导。 */
+  storageRoot?: string;
+  workspaceIdentity?: string;
+  platform?: NodeJS.Platform;
+  /** 注入文件系统判定（测试用）。默认真实 fs。 */
+  pathExists?: (path: string) => boolean;
+  listDirNames?: (path: string) => string[];
+}
+
+export function resolveMemoryDir(options: ResolveMemoryDirOptions): MemoryDirResolution {
+  const storageRoot =
+    options.storageRoot ?? resolveZcodeStorageRoot(options.homeDir ?? homedir(), options.platform);
+  const dirInput: MemoryDirInput = {
+    cwd: options.cwd,
+    storageRoot,
+    ...(options.workspaceIdentity === undefined ? {} : { workspaceIdentity: options.workspaceIdentity }),
+    ...(options.platform === undefined ? {} : { platform: options.platform }),
+  };
+  const parts = computeProjectDirParts(dirInput);
+  const projectsRoot = projectsRootOf(storageRoot, options.platform);
+  const computedDir = computeMemoryDir(dirInput);
+  const exists = options.pathExists ?? isDirectory;
+  const listNames = options.listDirNames ?? listDirectoryNames;
+
+  if (options.configDir !== undefined) {
+    // 配置是显式覆盖：不要求目录已存在（memory_write 会创建它）。
+    return { dir: options.configDir, source: "config", computedDir, projectsRoot, warnings: [] };
+  }
+
+  if (exists(computedDir)) {
+    return { dir: computedDir, source: "computed", computedDir, projectsRoot, warnings: [] };
+  }
+
+  const candidates = listNames(projectsRoot).filter((name) => name.startsWith(`${parts.slug}-`));
+  if (candidates.length === 1) {
+    const dir = join(projectsRoot, candidates[0]!, "memory");
+    return {
+      dir,
+      source: "fallback",
+      computedDir,
+      projectsRoot,
+      warnings: [
+        `The computed memory directory does not exist: ${computedDir}; using the only candidate with the same slug instead: ${dir}. ` +
+          `Different hashes on the two sides usually mean the workspace path is written differently from the one the memory directory was computed from; set dir explicitly in the config.`,
+      ],
+    };
+  }
+
+  const warnings: string[] = [];
+  if (candidates.length > 1) {
+    warnings.push(
+      `The computed memory directory does not exist, and ${projectsRoot} holds ${candidates.length} directories starting with ${parts.slug}-, so there is no way to tell which one to use.`,
+    );
+  } else {
+    warnings.push(`This project has no ZCode memory yet (the computed directory does not exist: ${computedDir}).`);
+  }
+
+  if (listNames(projectsRoot).some((name) => name.startsWith("project-"))) {
+    warnings.push(
+      "Found memory directories with the project- prefix: a workspace identity may be in use (slug fixed to project, hash input not the workspace path). " +
+        "Set dir explicitly in this package's config.",
+    );
+  }
+
+  return { dir: undefined, source: "none", computedDir, projectsRoot, warnings };
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDirectoryNames(path: string): string[] {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}

package/src/status.ts

@@ -0,0 +1,111 @@
+/**
+ * `/memory` 的状态与索引体检。
+ *
+ * 索引体检只做两件确定的事：索引行指向的文件不存在（孤儿行）、磁盘上的事实文件没出现在
+ * 索引里（未入索引）。索引可能被模型写坏（重复、失效链接），`memory_list` 走文件系统兜底。
+ */
+import { INDEX_CHARACTER_LIMIT, INDEX_LINE_LIMIT } from "./index-content.ts";
+import { INDEX_FILENAME } from "./index-file.ts";
+import type { MemoryListEntry } from "./list.ts";
+import type { MemoryDirResolution } from "./resolve.ts";
+
+export interface IndexHealth {
+  indexLineCount: number;
+  /** 索引里的链接目标（相对记忆目录，`/` 分隔）。 */
+  linkTargets: string[];
+  /** 指向不存在文件的索引行。 */
+  orphanIndexLines: string[];
+  /** 磁盘上有、但索引里没有链接的事实文件。 */
+  unindexedFiles: string[];
+}
+
+const LINK_TARGET_PATTERN = /\]\(\s*([^)\s]+)\s*\)/gu;
+
+/** 抽出索引里的相对 `.md` 链接目标。 */
+export function extractIndexTargets(indexContent: string): string[] {
+  const targets: string[] = [];
+  for (const match of indexContent.matchAll(LINK_TARGET_PATTERN)) {
+    const target = match[1]!.replace(/\\/gu, "/").replace(/^(?:\.\/)+/u, "");
+    if (target.startsWith("http://") || target.startsWith("https://")) continue;
+    if (!target.endsWith(".md")) continue;
+    if (target.split("/").pop() === INDEX_FILENAME) continue;
+    targets.push(target);
+  }
+  return targets;
+}
+
+/** 文件内容的"实际行数"：末尾换行不算一行。 */
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  const lines = content.replace(/\r\n/gu, "\n").split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.length;
+}
+
+export function inspectMemoryIndex(input: {
+  indexContent: string | undefined;
+  files: readonly MemoryListEntry[];
+}): IndexHealth {
+  const indexContent = input.indexContent ?? "";
+  const linkTargets = extractIndexTargets(indexContent);
+  const fileNames = new Set(input.files.map((entry) => entry.filename));
+  const targetNames = new Set(linkTargets);
+  return {
+    indexLineCount: countLines(indexContent),
+    linkTargets,
+    orphanIndexLines: [...new Set(linkTargets)].filter((target) => !fileNames.has(target)),
+    unindexedFiles: input.files.map((entry) => entry.filename).filter((filename) => !targetNames.has(filename)),
+  };
+}
+
+export interface MemoryStatusInput {
+  resolution: MemoryDirResolution;
+  /** `MEMORY.md` 的内容；不存在/读不了时 undefined。 */
+  indexContent: string | undefined;
+  files: readonly MemoryListEntry[];
+  /** 由扩展算出的注入状态描述。 */
+  injectionLabel: string;
+}
+
+function sourceLabel(source: MemoryDirResolution["source"]): string {
+  switch (source) {
+    case "config":
+      return "配置指定";
+    case "computed":
+      return "按算法计算（路径存在）";
+    case "fallback":
+      return "同 slug 唯一候选回退";
+    case "none":
+      return "尚无记忆";
+  }
+}
+
+function preview(values: readonly string[], limit = 10): string {
+  if (values.length === 0) return "无";
+  const shown = values.slice(0, limit).join("、");
+  return values.length > limit ? `${shown} 等 ${values.length} 项` : shown;
+}
+
+export function formatMemoryStatus(input: MemoryStatusInput): string {
+  const { resolution, files } = input;
+  const health = inspectMemoryIndex({ indexContent: input.indexContent, files });
+  const lines: string[] = [];
+  lines.push(`记忆目录：${resolution.dir ?? "未解析到"}`);
+  lines.push(`来源：${sourceLabel(resolution.source)}`);
+  if (resolution.dir === undefined || resolution.source !== "computed") {
+    lines.push(`计算路径：${resolution.computedDir}`);
+  }
+  lines.push(
+    input.indexContent === undefined
+      ? `索引 ${INDEX_FILENAME}：不存在（注入会跳过；memory_write 会创建它）`
+      : `索引 ${INDEX_FILENAME}：${health.indexLineCount} 行（注入上限 ${INDEX_LINE_LIMIT} 行 / ${INDEX_CHARACTER_LIMIT} 字符）`,
+  );
+  lines.push(`事实文件：${files.length} 个`);
+  lines.push(
+    `索引体检：孤儿索引行 ${health.orphanIndexLines.length} 条（${preview(health.orphanIndexLines)}）；` +
+      `未入索引的文件 ${health.unindexedFiles.length} 个（${preview(health.unindexedFiles)}）`,
+  );
+  lines.push(`索引注入：${input.injectionLabel}`);
+  for (const warning of resolution.warnings) lines.push(`注意：${warning}`);
+  return lines.join("\n");
+}

package/src/write.ts

@@ -0,0 +1,162 @@
+/**
+ * `memory_write` 的落盘实现。
+ *
+ * 顺序：校验 → 原子写事实文件 → 维护索引行。索引更新失败时不回滚事实文件——事实文件本身
+ * 是完整可读的，索引行下一次写入会补上；反过来（索引指了不存在的文件）更糟。
+ *
+ * frontmatter 只写设计 §2.2 规定的键，**不写** `originSessionId`：那是读文件的一方在缺失时
+ * 自己补的惰性字段，我们不伪造不属于自己的会话 id；也不加自定义键（未知键行为未核实）。
+ */
+import { mkdir, lstat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { atomicWriteFile, SymlinkWriteRefusedError } from "./atomic.ts";
+import { MemoryWriteError } from "./errors.ts";
+import { renderMemoryFile } from "./frontmatter.ts";
+import { updateMemoryIndex } from "./index-file.ts";
+import type { MemoryType } from "./paths.ts";
+
+export type MemoryWriteMode = "create" | "upsert";
+
+/** 文件名只允许安全字符；首字符必须是字母或数字（挡掉 `.`/`..`/隐藏文件与盘符写法）。 */
+const MEMORY_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** `name` → 事实文件名。`.` 与路径分隔符一律拒绝。 */
+export function memoryFilenameFor(name: string): { filename: string; slug: string } {
+  const trimmed = name.trim();
+  const slug = trimmed.toLowerCase().endsWith(".md") ? trimmed.slice(0, -3) : trimmed;
+  if (slug.length === 0) {
+    throw new MemoryWriteError(
+      "invalid_name",
+      "Memory name must not be empty.",
+      "Use a short kebab-case name, for example user-api-preference.",
+    );
+  }
+  if (!MEMORY_NAME_PATTERN.test(slug)) {
+    throw new MemoryWriteError(
+      "invalid_name",
+      `name "${name}" is not a valid memory filename: only letters, digits, dots, underscores and hyphens are allowed; it cannot start with a dot or a hyphen, and it cannot contain path separators.`,
+      "Use a short kebab-case name, for example user-api-preference.",
+    );
+  }
+  return { filename: `${slug}.md`, slug };
+}
+
+export interface WriteMemoryInput {
+  /** 记忆目录。 */
+  root: string;
+  name: string;
+  description: string;
+  type: MemoryType;
+  body: string;
+  mode: MemoryWriteMode;
+}
+
+export interface WriteMemoryOutcome {
+  filename: string;
+  absolutePath: string;
+  indexPath: string;
+  fileAction: "created" | "overwritten";
+  indexAction: "inserted" | "updated" | "unchanged";
+}
+
+export async function writeMemory(input: WriteMemoryInput): Promise<WriteMemoryOutcome> {
+  const { filename, slug } = memoryFilenameFor(input.name);
+  const description = input.description.replace(/\s+/gu, " ").trim();
+  if (description.length === 0) {
+    throw new MemoryWriteError(
+      "invalid_input",
+      "description must not be empty: it is the one-line hook in the index line, and what ZCode uses to judge relevance when recalling a memory.",
+      "Write one sentence saying what this memory is.",
+    );
+  }
+  if (!input.body.trim()) {
+    throw new MemoryWriteError(
+      "invalid_input",
+      "body must not be empty: a memory file has to carry the concrete fact (the body may link other memories with [[other-memory-name]]).",
+    );
+  }
+
+  // 目录按计算结果 mkdir -p（三级回退第 3 步：尚无记忆时写入才创建）
+  await mkdir(input.root, { recursive: true }).catch((error: unknown) => {
+    throw new MemoryWriteError(
+      "io",
+      `Failed to create the memory directory: ${input.root} (${describe(error)})`,
+      "Check the directory permissions and retry.",
+    );
+  });
+
+  const absolutePath = join(input.root, filename);
+  const existing = await lstatOrUndefined(absolutePath);
+  if (existing?.isSymbolicLink()) {
+    throw new MemoryWriteError(
+      "symlink",
+      `Refusing to write through a symbolic link: ${absolutePath}.`,
+      "Pass the real file path instead.",
+    );
+  }
+  if (input.mode === "create" && existing !== undefined) {
+    throw new MemoryWriteError(
+      "exists",
+      `Memory ${filename} already exists; create mode does not overwrite an existing memory.`,
+      'Use mode: "upsert", or choose a different name.',
+    );
+  }
+
+  const content = renderMemoryFile({ name: slug, description, type: input.type, body: input.body });
+  try {
+    await atomicWriteFile(absolutePath, content);
+  } catch (error) {
+    if (error instanceof SymlinkWriteRefusedError) {
+      throw new MemoryWriteError("symlink", error.message, "Pass the real file path instead.");
+    }
+    throw new MemoryWriteError(
+      "io",
+      `Failed to write the memory file: ${absolutePath} (${describe(error)})`,
+      "Retry later.",
+    );
+  }
+
+  let indexAction: WriteMemoryOutcome["indexAction"];
+  try {
+    const index = await updateMemoryIndex(input.root, { filename, title: slug, description });
+    indexAction = index.action;
+  } catch (error) {
+    if (error instanceof MemoryWriteError && error.code === "index_conflict") {
+      throw new MemoryWriteError(
+        "index_conflict",
+        `The memory file was written (${filename}), but MEMORY.md was changed by another process at the same time, so its index line was not updated.`,
+        "Re-read the memory and retry this write so the index line gets added.",
+      );
+    }
+    throw error;
+  }
+
+  return {
+    filename,
+    absolutePath,
+    indexPath: join(input.root, "MEMORY.md"),
+    fileAction: existing === undefined ? "created" : "overwritten",
+    indexAction,
+  };
+}
+
+async function lstatOrUndefined(path: string) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error as { code?: unknown }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    throw new MemoryWriteError("io", `Failed to check the target file: ${path} (${describe(error)})`);
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}