@co-engram/core 0.1.0

package/dist/storage/git-stage.js

@@ -0,0 +1,147 @@
+/**
+ * Git 暂存与提交消息生成（P0-C 规范化提交）
+ *
+ * 提供：
+ *   - stageChanges: 根据 engramIds 收集对应三文件路径
+ *   - generateCommitMessage: 分析暂存文件，生成规范化提交消息
+ *   - assessChangeRisk: 根据 synapse 类型评估变更风险
+ *
+ * @module @co-engram/core/storage
+ */
+import { deriveAllFilePaths } from "./path.js";
+/** 低风险 synapse（建立性连接） */
+const LOW_RISK_SYNAPSE_KINDS = new Set([
+    "extends",
+    "similar_to",
+    "exemplifies",
+    "contextualizes",
+    "consolidates",
+]);
+/** 高风险 synapse（矛盾/取代） */
+const HIGH_RISK_SYNAPSE_KINDS = new Set([
+    "contradicts",
+    "supersedes",
+]);
+/**
+ * 将 engramIds 转换为三文件路径列表
+ *
+ * @param engramIds - 相对路径形式的 engram ID 列表
+ * @returns 相对 rootPath 的文件路径数组（每个 engram 对应 3 个文件）
+ */
+export function stageChanges(engramIds) {
+    const files = [];
+    for (const id of engramIds) {
+        const paths = deriveAllFilePaths(id);
+        files.push(paths.content, paths.meta, paths.synapses);
+    }
+    return files;
+}
+/**
+ * 分析变更类型
+ *
+ * 通过比较暂存文件路径的模式推断整体变更类型：
+ *   - 全部含新增：create
+ *   - 全部含更新：update
+ *   - 全部含删除：delete
+ *   - 混合：mixed
+ */
+function classifyChange(stagedFiles) {
+    if (stagedFiles.length === 0)
+        return "mixed";
+    const kinds = new Set();
+    for (const f of stagedFiles) {
+        if (f.startsWith("engrams/content/") ||
+            f.startsWith("engrams/meta/") ||
+            f.startsWith("engrams/synapses/")) {
+            kinds.add("create");
+        }
+    }
+    if (kinds.size === 0)
+        return "mixed";
+    if (kinds.size === 1) {
+        return [...kinds][0];
+    }
+    return "mixed";
+}
+/**
+ * 从文件路径提取 engram id
+ *
+ * `engrams/content/a/b.md` → `a/b`
+ * `engrams/meta/x.yaml` → `x`
+ * `engrams/synapses/y/z.yaml` → `y/z`
+ */
+function extractEngramIdFromPath(filePath) {
+    const match = /^engrams\/(?:content|meta|synapses)\/(.+)\.(?:md|ya?ml)$/.exec(filePath);
+    return match ? match[1] : null;
+}
+/**
+ * 生成规范化提交消息
+ *
+ * 形如：`co-engram: 新增[设备ADB调试方法]及3条连接(supersedes, depends_on)`
+ *
+ * P0 简化版：只基于文件路径数量生成消息，不解析实际内容。
+ * P1+ 版本会读 YAML 提取 title/kind/synapse kinds 生成更详细消息。
+ */
+export function generateCommitMessage(stagedFiles, options) {
+    if (stagedFiles.length === 0) {
+        return { message: "co-engram: (空变更)", kind: "mixed", engramCount: 0 };
+    }
+    const engramIds = new Set();
+    for (const f of stagedFiles) {
+        const id = extractEngramIdFromPath(f);
+        if (id)
+            engramIds.add(id);
+    }
+    const engramCount = engramIds.size;
+    const changeKind = classifyChange(stagedFiles);
+    const actionByKind = {
+        create: "新增",
+        update: "更新",
+        delete: "删除",
+        mixed: "调整",
+    };
+    const action = actionByKind[changeKind];
+    const titlePart = options?.title ?? `${engramCount} 个 engram`;
+    const synapsePart = options?.synapseKinds && options.synapseKinds.length > 0
+        ? `及 ${options.synapseKinds.length} 条连接(${options.synapseKinds.join(", ")})`
+        : "";
+    const message = `co-engram: ${action}[${titlePart}]${synapsePart}`;
+    return { message, kind: changeKind, engramCount };
+}
+/**
+ * 评估变更风险
+ *
+ * 规则（来自设计文档 §八）：
+ *   低风险：新增 extends/similar_to/exemplifies/contextualizes/consolidates
+ *   中风险：新增 depends_on/causes/follows/derives_from/part_of
+ *   高风险：新增 contradicts/supersedes 或删除已有连接
+ */
+export function assessChangeRisk(synapseKinds, hasDeletions) {
+    const reasons = [];
+    if (hasDeletions) {
+        return {
+            risk: "high",
+            reasons: ["删除已有连接（可能影响知识结构）"],
+        };
+    }
+    const hasHigh = synapseKinds.some((k) => HIGH_RISK_SYNAPSE_KINDS.has(k));
+    const hasLow = synapseKinds.some((k) => LOW_RISK_SYNAPSE_KINDS.has(k));
+    const hasMedium = synapseKinds.length > 0 && !hasHigh && !hasLow;
+    if (hasHigh) {
+        if (synapseKinds.includes("contradicts"))
+            reasons.push("新增 contradicts 连接");
+        if (synapseKinds.includes("supersedes"))
+            reasons.push("新增 supersedes 连接（取代关系）");
+        return { risk: "high", reasons };
+    }
+    if (hasMedium) {
+        const mediumKinds = synapseKinds.filter((k) => !LOW_RISK_SYNAPSE_KINDS.has(k) && !HIGH_RISK_SYNAPSE_KINDS.has(k));
+        reasons.push(`新增中风险连接: ${mediumKinds.join(", ")}`);
+        return { risk: "medium", reasons };
+    }
+    if (hasLow) {
+        return { risk: "low", reasons: ["仅含建立性连接"] };
+    }
+    return { risk: "low", reasons: ["无连接变更"] };
+}
+//# sourceMappingURL=git-stage.js.map

package/dist/storage/git-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-stage.js","sourceRoot":"","sources":["../../src/storage/git-stage.ts"],"names":[],"mappings":"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"}

package/dist/storage/git.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Git 操作封装（基于 child_process 调用系统 git）
+ *
+ * 不依赖外部 npm 包，保持 host-agnostic。
+ * 只封装 co-engram 需要的最小操作集。
+ *
+ * @module @co-engram/core/storage
+ */
+/** Git 提交选项 */
+export interface GitCommitOptions {
+    /** 仓库根目录 */
+    readonly repoPath: string;
+    /** 要提交的文件相对路径列表 */
+    readonly files: readonly string[];
+    /** 提交消息 */
+    readonly message: string;
+    /** 作者（覆盖 git config） */
+    readonly authorName?: string;
+    readonly authorEmail?: string;
+}
+/** Git 提交结果 */
+export interface GitCommitResult {
+    readonly commitHash: string;
+    readonly branch: string;
+    readonly filesChanged: number;
+}
+/**
+ * 检查路径是否是 Git 仓库
+ */
+export declare function isGitRepo(repoPath: string): boolean;
+/**
+ * 初始化 Git 仓库
+ */
+export declare function initGitRepo(repoPath: string): void;
+/**
+ * Stage 文件并提交
+ *
+ * 注意：不会自动 push，团队需要时手动 push。
+ */
+export declare function commitFiles(options: GitCommitOptions): GitCommitResult;
+/**
+ * 获取当前分支名
+ */
+export declare function getCurrentBranch(repoPath: string): string;
+/**
+ * 获取文件最后的提交信息
+ */
+export declare function getFileLastCommit(repoPath: string, relativePath: string): {
+    hash: string;
+    date: string;
+    message: string;
+} | null;
+/**
+ * 获取仓库根目录的绝对路径
+ */
+export declare function resolveRepoPath(repoPath: string): string;
+//# sourceMappingURL=git.d.ts.map

package/dist/storage/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/storage/git.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAe;AACf,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAe;AACf,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAanD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAclD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA8DtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwBxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD"}

package/dist/storage/git.js

@@ -0,0 +1,156 @@
+/**
+ * Git 操作封装（基于 child_process 调用系统 git）
+ *
+ * 不依赖外部 npm 包，保持 host-agnostic。
+ * 只封装 co-engram 需要的最小操作集。
+ *
+ * @module @co-engram/core/storage
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 检查路径是否是 Git 仓库
+ */
+export function isGitRepo(repoPath) {
+    if (!existsSync(repoPath)) {
+        return false;
+    }
+    try {
+        execSync("git rev-parse --is-inside-work-tree", {
+            cwd: repoPath,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 初始化 Git 仓库
+ */
+export function initGitRepo(repoPath) {
+    if (isGitRepo(repoPath)) {
+        return;
+    }
+    execSync("git init", { cwd: repoPath, stdio: "ignore" });
+    // 设置默认分支为 main
+    try {
+        execSync("git symbolic-ref HEAD refs/heads/main", {
+            cwd: repoPath,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // 老版本 git 可能不支持，忽略
+    }
+}
+/**
+ * Stage 文件并提交
+ *
+ * 注意：不会自动 push，团队需要时手动 push。
+ */
+export function commitFiles(options) {
+    const { repoPath, files, message, authorName, authorEmail } = options;
+    if (!isGitRepo(repoPath)) {
+        initGitRepo(repoPath);
+    }
+    // Stage files
+    if (files.length > 0) {
+        const fileArgs = files.map((f) => `"${f.replace(/"/g, '\\"')}"`).join(" ");
+        execSync(`git add ${fileArgs}`, { cwd: repoPath, stdio: "ignore" });
+    }
+    else {
+        execSync("git add -A", { cwd: repoPath, stdio: "ignore" });
+    }
+    // Check if there are staged changes
+    let hasStagedChanges = true;
+    try {
+        execSync("git diff --cached --quiet", { cwd: repoPath, stdio: "ignore" });
+        hasStagedChanges = false; // exit 0 means no changes
+    }
+    catch {
+        hasStagedChanges = true;
+    }
+    if (!hasStagedChanges) {
+        // Nothing to commit
+        const branch = getCurrentBranch(repoPath);
+        return { commitHash: "", branch, filesChanged: 0 };
+    }
+    // Commit
+    const authorArgs = [];
+    if (authorName) {
+        authorArgs.push(`-c "user.name=${authorName.replace(/"/g, '\\"')}"`);
+    }
+    if (authorEmail) {
+        authorArgs.push(`-c "user.email=${authorEmail}"`);
+    }
+    const authorPart = authorArgs.length > 0 ? `git ${authorArgs.join(" ")}` : "git";
+    const escapedMessage = message.replace(/"/g, '\\"');
+    execSync(`${authorPart} commit -m "${escapedMessage}"`, {
+        cwd: repoPath,
+        stdio: "ignore",
+    });
+    const commitHash = execSync("git rev-parse HEAD", {
+        cwd: repoPath,
+        encoding: "utf8",
+    }).trim();
+    const branch = getCurrentBranch(repoPath);
+    // Count changed files in this commit
+    const filesChanged = parseInt(execSync("git diff --name-only HEAD~1 HEAD 2>/dev/null | wc -l", {
+        cwd: repoPath,
+        encoding: "utf8",
+    }).trim() || "0", 10);
+    return { commitHash, branch, filesChanged };
+}
+/**
+ * 获取当前分支名
+ */
+export function getCurrentBranch(repoPath) {
+    try {
+        return execSync("git rev-parse --abbrev-ref HEAD", {
+            cwd: repoPath,
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        return "main";
+    }
+}
+/**
+ * 获取文件最后的提交信息
+ */
+export function getFileLastCommit(repoPath, relativePath) {
+    try {
+        const hash = execSync(`git log -n 1 --format="%H" -- "${relativePath}"`, {
+            cwd: repoPath,
+            encoding: "utf8",
+        }).trim();
+        if (!hash) {
+            return null;
+        }
+        const date = execSync(`git log -n 1 --format="%cI" -- "${relativePath}"`, {
+            cwd: repoPath,
+            encoding: "utf8",
+        }).trim();
+        const message = execSync(`git log -n 1 --format="%s" -- "${relativePath}"`, {
+            cwd: repoPath,
+            encoding: "utf8",
+        }).trim();
+        return { hash, date, message };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 获取仓库根目录的绝对路径
+ */
+export function resolveRepoPath(repoPath) {
+    if (existsSync(join(repoPath, ".git"))) {
+        return repoPath;
+    }
+    return repoPath;
+}
+//# sourceMappingURL=git.js.map

package/dist/storage/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/storage/git.ts"],"names":[],"mappings":"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"}

package/dist/storage/hash.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Content hash 计算（SHA-256）
+ *
+ * 用于精确去重和变更检测
+ *
+ * @module @co-engram/core/storage
+ */
+/**
+ * 计算 SHA-256 哈希
+ *
+ * @param content - 任意字符串
+ * @returns 形如 "sha256:abc123..." 的哈希字符串
+ */
+export declare function computeContentHash(content: string): string;
+/**
+ * 验证内容是否匹配给定的哈希
+ */
+export declare function verifyContentHash(content: string, expectedHash: string): boolean;
+/**
+ * 计算内容大小（字符数）
+ */
+export declare function computeContentSize(content: string): number;
+//# sourceMappingURL=hash.d.ts.map

package/dist/storage/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/storage/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/storage/hash.js

@@ -0,0 +1,31 @@
+/**
+ * Content hash 计算（SHA-256）
+ *
+ * 用于精确去重和变更检测
+ *
+ * @module @co-engram/core/storage
+ */
+import { createHash } from "node:crypto";
+/**
+ * 计算 SHA-256 哈希
+ *
+ * @param content - 任意字符串
+ * @returns 形如 "sha256:abc123..." 的哈希字符串
+ */
+export function computeContentHash(content) {
+    const hash = createHash("sha256").update(content, "utf8").digest("hex");
+    return `sha256:${hash}`;
+}
+/**
+ * 验证内容是否匹配给定的哈希
+ */
+export function verifyContentHash(content, expectedHash) {
+    return computeContentHash(content) === expectedHash;
+}
+/**
+ * 计算内容大小（字符数）
+ */
+export function computeContentSize(content) {
+    return content.length;
+}
+//# sourceMappingURL=hash.js.map

package/dist/storage/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/storage/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxE,OAAO,UAAU,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,YAAoB;IAEpB,OAAO,kBAAkB,CAAC,OAAO,CAAC,KAAK,YAAY,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC"}

package/dist/storage/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 存储 barrel
+ *
+ * @module @co-engram/core/storage
+ */
+export * from "./path.js";
+export * from "./hash.js";
+export * from "./engram-store.js";
+export * from "./synapse-store.js";
+export * from "./git.js";
+export * from "./git-stage.js";
+export * from "./engram-index.js";
+export * from "./repository.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,14 @@
+/**
+ * 存储 barrel
+ *
+ * @module @co-engram/core/storage
+ */
+export * from "./path.js";
+export * from "./hash.js";
+export * from "./engram-store.js";
+export * from "./synapse-store.js";
+export * from "./git.js";
+export * from "./git-stage.js";
+export * from "./engram-index.js";
+export * from "./repository.js";
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/storage/path.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Engram 路径推导
+ *
+ * 规则（spec 7.4）：
+ *   1. 从 domainTags 推导目录层级（取前 3 个，避免过深）
+ *   2. 从 title 生成 slug
+ *   3. 组合为 {domainPath}/{slug}
+ *
+ * 示例：
+ *   domainTags=["testing","adb","android"], title="Android 14 无线 ADB"
+ *   → "testing/adb/android/android-14-无线-adb"
+ *
+ * @module @co-engram/core/storage
+ */
+import type { EngramCreateInput } from "../types/engram.js";
+/**
+ * 推导 engram 的相对路径（不含扩展名）
+ *
+ * @param input - 创建参数
+ * @returns 相对路径，如 "testing/adb/android/android-14-无线-adb"
+ */
+export declare function deriveEngramPath(input: Pick<EngramCreateInput, "title" | "domainTags">): string;
+/**
+ * 推导 engram 在 content/ 目录下的完整路径（带 .md 扩展名）
+ */
+export declare function deriveContentFilePath(relativePath: string): string;
+/**
+ * 推导 engram 在 meta/ 目录下的完整路径（带 .yaml 扩展名）
+ */
+export declare function deriveMetaFilePath(relativePath: string): string;
+/**
+ * 推导 engram 在 synapses/ 目录下的完整路径（带 .yaml 扩展名）
+ */
+export declare function deriveSynapsesFilePath(relativePath: string): string;
+/**
+ * 从相对路径反推 engram id（即相对路径本身）
+ *
+ * 在 Co-Engram 中，engram id 就是相对路径。
+ */
+export declare function idFromRelativePath(relativePath: string): string;
+/**
+ * 从 id 推导三文件相对路径（content/meta/synapses 各一份）
+ *
+ * @returns 三个文件路径的元组
+ */
+export declare function deriveAllFilePaths(relativePath: string): {
+    content: string;
+    meta: string;
+    synapses: string;
+};
+//# sourceMappingURL=path.d.ts.map

package/dist/storage/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/storage/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAM5D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,YAAY,CAAC,GACrD,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAMA"}

package/dist/storage/path.js

@@ -0,0 +1,72 @@
+/**
+ * Engram 路径推导
+ *
+ * 规则（spec 7.4）：
+ *   1. 从 domainTags 推导目录层级（取前 3 个，避免过深）
+ *   2. 从 title 生成 slug
+ *   3. 组合为 {domainPath}/{slug}
+ *
+ * 示例：
+ *   domainTags=["testing","adb","android"], title="Android 14 无线 ADB"
+ *   → "testing/adb/android/android-14-无线-adb"
+ *
+ * @module @co-engram/core/storage
+ */
+import { slugify } from "../types/slugify.js";
+/** 最大 domainTags 深度（防止路径过深） */
+const MAX_DOMAIN_DEPTH = 3;
+/**
+ * 推导 engram 的相对路径（不含扩展名）
+ *
+ * @param input - 创建参数
+ * @returns 相对路径，如 "testing/adb/android/android-14-无线-adb"
+ */
+export function deriveEngramPath(input) {
+    const domainTags = input.domainTags ?? [];
+    const domainPath = domainTags
+        .slice(0, MAX_DOMAIN_DEPTH)
+        .map((t) => slugify(t))
+        .filter(Boolean)
+        .join("/");
+    const slug = slugify(input.title) || "untitled";
+    return domainPath ? `${domainPath}/${slug}` : slug;
+}
+/**
+ * 推导 engram 在 content/ 目录下的完整路径（带 .md 扩展名）
+ */
+export function deriveContentFilePath(relativePath) {
+    return `engrams/content/${relativePath}.md`;
+}
+/**
+ * 推导 engram 在 meta/ 目录下的完整路径（带 .yaml 扩展名）
+ */
+export function deriveMetaFilePath(relativePath) {
+    return `engrams/meta/${relativePath}.yaml`;
+}
+/**
+ * 推导 engram 在 synapses/ 目录下的完整路径（带 .yaml 扩展名）
+ */
+export function deriveSynapsesFilePath(relativePath) {
+    return `engrams/synapses/${relativePath}.yaml`;
+}
+/**
+ * 从相对路径反推 engram id（即相对路径本身）
+ *
+ * 在 Co-Engram 中，engram id 就是相对路径。
+ */
+export function idFromRelativePath(relativePath) {
+    return relativePath;
+}
+/**
+ * 从 id 推导三文件相对路径（content/meta/synapses 各一份）
+ *
+ * @returns 三个文件路径的元组
+ */
+export function deriveAllFilePaths(relativePath) {
+    return {
+        content: deriveContentFilePath(relativePath),
+        meta: deriveMetaFilePath(relativePath),
+        synapses: deriveSynapsesFilePath(relativePath),
+    };
+}
+//# sourceMappingURL=path.js.map

package/dist/storage/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/storage/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,+BAA+B;AAC/B,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsD;IAEtD,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAG,UAAU;SAC1B,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SACtB,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC;IAEhD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,mBAAmB,YAAY,KAAK,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,OAAO,gBAAgB,YAAY,OAAO,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAoB;IACzD,OAAO,oBAAoB,YAAY,OAAO,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IAKrD,OAAO;QACL,OAAO,EAAE,qBAAqB,CAAC,YAAY,CAAC;QAC5C,IAAI,EAAE,kBAAkB,CAAC,YAAY,CAAC;QACtC,QAAQ,EAAE,sBAAsB,CAAC,YAAY,CAAC;KAC/C,CAAC;AACJ,CAAC"}