@furongjun1999/dsh-memory 0.4.4 → 0.4.5

package/lib/index.js

@@ -1,16 +1,40 @@
 /**
- * @furongjun1999/dsh-memory —— 灵枢（AEIS）DeepSeek Harness 插件
+ * @furongjun1999/dsh-memory —— 灵枢 DeepSeek Harness 插件
+ * （大脑唯一真源 = md_cg 认知图；aeis 能力库已下线）
  *
  * 把灵枢的时空记忆/知识飞轮/自我认知接入 DSH：
- * - 工具桥接：Agent 可调用 lingshu_remember / recall / search / think 等
- * - 自动记忆：DSH 对话自动沉淀进灵枢记忆库（去重+重要性）
+ * - 记忆唯一真源：**md_cg 认知图（md 文档）**，插件侧唯一显式入口
+ *   `src/lib/mdcg_client.ts`（每个方法 = 一条 MCP cg / stg 调用）
+ * - 工具桥接：Agent 可调用工具，经**唯一的大脑桥**（同一 md_cg 子进程）从
+ *   **md_cg.mcp_server** 拉取（`MDCG_MCP_SURFACE=full`：`cg` / `stg` 基元 +
+ *   `mdcg_*` 细粒度全家，再由 `config.tools` 选择表筛），注册为 `lingshu_<name>`
+ * - 自动记忆：DSH 对话经**认知图**自动沉淀（主动遗忘闸门去重 + 重要性 + 脱敏）
+ * - 使命分离：理论仓（CTP）只留方法论文档，工程代码全部在主仓 md_cg
  *
  * 用法（cordis.yml）：
  * ```yaml
  * - id: lingshu-memory
  *   name: '@furongjun1999/dsh-memory'
  *   config:
- *     dbPath: 'D:/path/to/lingshu.db'
+ *     mdcg:                              # 记忆真源：认知图（md 文档）
+ *       # root = 记忆写入路径（用户可改）。缺省 = 插件仓自身 data/mdcg。
+ *       # 覆盖优先级：env MDCG_ROOT > <插件仓>/data/paths.json > 本项 > 默认
+ *       # root: 'D:/somewhere/mdcg'        # 例：把记忆库放到别处
+ *       actor: 'dsh-memory'
+ *     env:                               # 写入凭据：默认【关闭】，由你决定是否打开
+ *       # 不配 → 只读 guest：读/召回/时间线可用，自动记忆/转录/落图不落盘（启动会告警）
+ *       # 打开①推荐：先签发再引用（明文不进配置文件）
+ *       #   python -m md_cg.tokens issue --role designer --actor dsh-memory \
+ *       #     --clearance internal \
+ *       #     --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify \
+ *       #     --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
+ *       # MDCG_TOKEN: !!js process.env.MDCG_TOKEN
+ *       # 打开②最小权限：--role recorder（无 whitebox/identity/verify，不能写 self 层）
+ *       # 打开③兼容旧部署（不推荐）：MDCG_LEGACY_ENV_AUTH: '1'
+ *     dbPath: '/path/to/legacy.db'       # 遗留：仅角色数据目录推导用（不存记忆）
+ *     capability:                        # 可选「身体」后端（默认关 → 单进程纯大脑）
+ *       enabled: false
+ *       args: ['-m', 'aeis.mcp.server']
  *     identity: '灵枢'
  *     memory:
  *       userMessage: true
@@ -23,7 +47,10 @@ import { homedir } from 'node:os';
 import { LingshuBridge } from './bridge.js';
 import { registerLingshuTools } from './tools.js';
 import { installMemoryHooks } from './hooks.js';
-import { installRoleplayWeb } from './roleplay_web.js';
+// LIB 本地库：角色扮演网页 / 互维维护 / 白箱 LLM 适配器统一收在 src/lib/。
+import { installRoleplayWeb } from './lib/roleplay_web.js';
+import { MdcgClient } from './lib/mdcg_client.js';
+import { describeDataPaths, mdcgRoot } from './lib/datapath.js';
 /**
  * 调试探针：记录 apply 失败到独立文件（绕过 DSH 日志系统）。
  * 路径从用户家目录动态解析（issue #5，与 bridge.ts 同因同修）。
@@ -54,11 +81,11 @@ export const inject = ['tools'];
 export const Config = z.object({
     serverName: z.string().default('lingshu'),
     python: z.string().default('python'),
-    moduleArgs: z.array(String).default(['-m', 'aeis.mcp.server']),
+    moduleArgs: z.array(String).default(['-m', 'md_cg.mcp_server']),
     dbPath: z.string().default('data/lingshu.db'),
     identity: z.string().default('灵枢'),
     env: z.dict(String).default({}),
-    tools: z.union([z.const('core'), z.const('brain'), z.const('all'), z.array(String)]).default('brain'),
+    tools: z.union([z.const('core'), z.const('brain'), z.const('all'), z.array(String)]).default('core'),
     /** 护栏宪章版本声明（接入即接受宪章约束，docs/guardrail-charter.md）。 */
     charter: z.string().default('v2.0-published'),
     memory: z
@@ -86,6 +113,32 @@ export const Config = z.object({
         heartbeatMs: z.number().default(10 * 60 * 1000),
     })
         .default({ enabled: false, heartbeatMs: 10 * 60 * 1000 }),
+    /** 认知图（md_cg）：记忆唯一真源。
+     *  root 为**记忆写入路径**（用户可改）。缺省空串 = 未指定，按优先级解析：
+     *    ① env MDCG_ROOT ② `<插件仓>/data/paths.json` 的 root
+     *    ③ 本项 ④ 默认 `<插件仓>/data/mdcg`
+     *  相对路径一律相对**插件仓根**解析——历史教训：相对 cwd 的相对路径随
+     *  宿主 cwd 漂移，cwd 落在别仓时记忆真源分裂成互不可见的两处。
+     *  tenant/actor 决定私有内容加解密的身份：与 migrate_roleplay 的
+     *  --tenant/--actor 必须一致，否则读不到已迁移节点。 */
+    mdcg: z
+        .object({
+        enabled: z.boolean().default(true),
+        root: z.string().default(''),
+        actor: z.string().default('dsh-memory'),
+        tenant: z.string().default('default'),
+        clearance: z.string().default('private'),
+    })
+        .default({ enabled: true, root: '', actor: 'dsh-memory', tenant: 'default', clearance: 'private' }),
+    /** 「身体」能力后端（可选）：默认关闭 → 单进程纯大脑。
+     *  开启需同时给出 args（能力库启动参数），否则跳过并告警。 */
+    capability: z
+        .object({
+        enabled: z.boolean().default(false),
+        python: z.string().default(''),
+        args: z.array(String).default([]),
+    })
+        .default({ enabled: false, python: '', args: [] }),
 });
 /**
  * 插件激活：启动灵枢子进程 → 注册工具 → 安装自动记忆钩子。
@@ -95,37 +148,107 @@ export async function apply(ctx, config) {
     // 宪章宣告（接入即接受宪章约束——docs/guardrail-charter.md v2.0-published）
     ctx.logger.info(`dsh-memory: 灵枢插件激活（大脑模式）· 接受护栏宪章 ${config.charter} —— ` +
         '接入即接受宪章约束（公开/可执行/可审计/设计者终裁）');
-    const bridge = new LingshuBridge({
-        python: config.python,
-        args: config.moduleArgs,
-        env: {
-            AEIS_DB: config.dbPath,
-            AEIS_IDENTITY: config.identity,
-            ...config.env,
-        },
-        timeoutMs: config.toolCallTimeoutMs,
-        maxRetryDelayMs: config.maxRetryDelayMs,
-    });
-    bridge.start();
-    const ready = await bridge.waitReady();
-    if (!ready) {
-        const message = '灵枢进程无法启动（检查 python 是否可用、aeis 是否安装：pip install aeis）';
-        if (config.failOnStartupError) {
+    // ═══ 大脑进程：md_cg（主仓自带）——**唯一**子进程 ═══
+    // 工具面 / 记忆写入 / 互维核验 / 角色落图共用这一个桥。S4（2026-09-10）已删除
+    // 历史上并存的第二个 aeis 进程：双进程方案下两侧工具名互不交集（86 vs 33，
+    // 交集为 0），切换时会静默丢功能；收敛为单进程后由 MDCG_MCP_SURFACE=full
+    // 提供完整认知面。插件侧唯一显式入口：src/lib/mdcg_client.ts（一方法 = 一条 MCP 调用）。
+    let mdcg = null;
+    let brainReady = false;
+    /** 记忆真源解析结果（「新写入去哪」）——用户可改：env > paths.json > 配置 > 默认自身仓 data/。 */
+    const resolvedRoot = mdcgRoot(config.mdcg.root);
+    if (config.mdcg.enabled) {
+        mdcg = new MdcgClient({
+            python: config.python,
+            args: config.moduleArgs,
+            root: resolvedRoot,
+            actor: config.mdcg.actor,
+            tenant: config.mdcg.tenant,
+            clearance: config.mdcg.clearance,
+            identity: config.identity,
+            env: config.env,
+            timeoutMs: config.toolCallTimeoutMs,
+            maxRetryDelayMs: config.maxRetryDelayMs,
+        });
+        mdcg.start();
+        // 启动留痕：把「记忆真源在哪、由谁决定、路径是否存在」写进可审计日志，
+        // 避免再次出现「以为在记忆、其实写到了别仓」的静默分裂（历史事故）。
+        const dp = describeDataPaths(config.mdcg.root);
+        ctx.logger.info(`dsh-memory: 记忆真源路径 = ${dp.mdcgRoot}（来源 ${dp.source}，`
+            + `dataRoot=${dp.dataRoot}，存在=${dp.mdcgRootExists ? '是' : '否（首次写入将创建）'}，`
+            + `用户可改：${dp.pathsFile}）`);
+        brainReady = await mdcg.waitReady();
+        if (brainReady) {
+            ctx.logger.info(`dsh-memory: 认知图已就绪（MDCG_ROOT=${resolvedRoot}）`);
+        }
+        else {
+            ctx.logger.warn(`dsh-memory: 认知图未就绪（MDCG_ROOT=${resolvedRoot}），`
+                + '核验按白箱纪律 fail-closed；桥将后台重连并在就绪后补注册工具。');
+        }
+        // 写入凭据检查（fail-closed，且**默认关闭**）：md_cg 身份优先级
+        // ① MDCG_TOKEN ② MDCG_LEGACY_ENV_AUTH=1 ③ 都没有 → 只读 guest。
+        // 默认即第 ③ 种：读 / 召回 / 时间线照常，但自动记忆、转录、角色落图**不落盘**。
+        // 是否打开写权限由用户自行决定（见 cordis.yml.example 的「写入凭据」段），
+        // 插件不代为注入任何凭据，只在启动时告警——避免「看起来在记忆、其实没落盘」。
+        const authEnv = { ...process.env, ...config.env };
+        if (!authEnv.MDCG_TOKEN && !authEnv.MDCG_LEGACY_ENV_AUTH) {
+            ctx.logger.warn('dsh-memory: 未配置认知图写入凭据（默认关闭），以只读 guest 运行——'
+                + '读 / 召回 / 时间线可用，但自动记忆、转录、角色落图不会落盘。'
+                + '要打开：签发令牌 MDCG_TOKEN（推荐）或设 MDCG_LEGACY_ENV_AUTH=1，'
+                + '经 config.env 注入，见 cordis.yml.example。');
+        }
+    }
+    else {
+        ctx.logger.warn('dsh-memory: mdcg.enabled=false —— 大脑（认知图）未启动，工具与自动记忆不可用');
+    }
+    /** 大脑桥：工具面 + 互维 + 角色落图共用的唯一 md_cg 通道（mdcg 关闭时为 null）。 */
+    const bridge = mdcg?.bridge ?? null;
+    if (!brainReady) {
+        const message = '灵枢大脑（md_cg）未就绪（检查 python 是否可用、md_cg 是否可导入：python -m md_cg.mcp_server）';
+        if (config.failOnStartupError && config.mdcg.enabled) {
             // P1 修复（GPT 审查）：启动失败抛错前必须 dispose——此前 throw 在 try 之前，
             // 桥接对象泄漏 + 后台重试计时器继续跑
-            bridge.dispose();
+            mdcg?.dispose();
             throw new Error(message);
         }
         ctx.logger.warn(`dsh-memory: ${message}，继续后台重试`);
     }
+    // ═══ 「身体」能力后端（可选）—— 角色扮演生成等「身」的生成能力 ═══
+    // 默认**不挂载**：主仓保持纯大脑单进程（只起 md_cg）。开启后额外起一个能力库
+    // 子进程（如 AEIS），**仅**角色扮演生成使用；记忆真源仍是 md_cg（大脑）。
+    // 未挂载时角色生成接口 fail-closed（返回明确原因，不编造回复）。
+    let capability = null;
+    if (config.capability.enabled) {
+        if (!config.capability.args.length) {
+            ctx.logger.warn('dsh-memory: capability.enabled=true 但未配置 capability.args，跳过身体能力后端');
+        }
+        else {
+            capability = new LingshuBridge({
+                python: config.capability.python || config.python,
+                args: config.capability.args,
+                env: {
+                    // 能力库的旧版数据目录约定（AEIS_* 为遗留名，md_cg 不读）。
+                    AEIS_DB: config.dbPath,
+                    AEIS_IDENTITY: config.identity,
+                    ...config.env,
+                },
+                timeoutMs: config.toolCallTimeoutMs,
+                maxRetryDelayMs: config.maxRetryDelayMs,
+            });
+            capability.start();
+            if (!(await capability.waitReady())) {
+                ctx.logger.warn('dsh-memory: 身体能力后端未就绪，角色生成接口将 fail-closed（不编造回复）');
+            }
+        }
+    }
     const disposers = [];
     let toolsPoll = null;
     try {
-        // 工具注册：初始就绪立即注册；若启动时未就绪（python 暂不可用/aeis 未装等
+        // 工具注册：初始就绪立即注册；若启动时未就绪（python 暂不可用等
         // 竞态），桥重连成功后自动补注册——修复"工具永久缺失"问题。
         let toolsRegistered = false;
         const tryRegister = async () => {
-            if (toolsRegistered || !bridge.isReady())
+            if (toolsRegistered || !bridge?.isReady())
                 return;
             try {
                 const dispose = await registerLingshuTools(ctx, bridge, {
@@ -145,23 +268,23 @@ export async function apply(ctx, config) {
                 ctx.logger.warn(`dsh-memory: 工具注册失败，稍后重试: ${String(err)}`);
             }
         };
-        if (ready)
+        if (brainReady)
             await tryRegister();
         if (!toolsRegistered) {
             toolsPoll = setInterval(() => { void tryRegister(); }, 2000);
             disposers.push(() => { if (toolsPoll)
                 clearInterval(toolsPoll); });
         }
-        installMemoryHooks(ctx, bridge, config.memory);
-        // 角色扮演网页（同源挂载 /roleplay，复用本插件 bridge）
-        await installRoleplayWeb(ctx, bridge, config, disposers);
-        // 白箱 LLM 服务商（v0.4 新能力）：把灵枢注册为 DSH 的 provider，
-        // Web/QQ/飞书等所有会话可选「白箱灵枢」模型——白箱直答（零 LLM），
-        // 输入/输出/缓存命中 token 计数对齐 dsh-llm 协议。动态检测 llm 服务。
-        {
-            const { installWhiteboxLlm } = await import('./llm_adapter.js');
-            disposers.push(installWhiteboxLlm(ctx, bridge));
-        }
+        // 自动记忆：沉淀进 md_cg 认知图（记忆唯一真源）。mdcg=null 时整体停用。
+        installMemoryHooks(ctx, mdcg, config.memory);
+        // 角色扮演网页（同源挂载 /roleplay）：生成能力走可选「身体」后端（capability），
+        // 转录/历史/翻译/落图走大脑（mdcg）。capability=null 时生成接口 fail-closed。
+        await installRoleplayWeb(ctx, capability, config, disposers, mdcg);
+        // 白箱 LLM provider 已下线（2026-09-10）：功能尚不完善，不再注册
+        // 'lingshu-whitebox' provider。适配器保留为 LIB 本地库
+        // （src/lib/whitebox_llm.ts），白箱能力改由 md_cg 显式调用验证：
+        //   MCP cg(op=whitebox, action=verify_encoding|verify_existing)
+        // 见 docs/功能调用映射表_v0.1.md。
         // 互维维护（v1.1）：心跳写戳 + 守护 A + 任务验证双通道
         if (config.mutual.enabled) {
             // P1 修复（GPT 审查）：timer 是可选服务——缺失时告警跳过互维，
@@ -173,34 +296,62 @@ export async function apply(ctx, config) {
                 ctx.logger.warn('dsh-memory: timer 服务不可用，跳过互维维护（mutual.enabled=true 但无 timer）');
             }
             else {
-                const { installMutualMaintenance } = await import('./mutual.js');
-                // 双通道 hooks：白箱 base_verify（走 bridge 调灵枢）+ DeepSeek 复核
+                const { installMutualMaintenance } = await import('./lib/mutual.js');
+                // 双通道 hooks：白箱 base_verify（mdcg.verifyClaim 走认知图）+ 宿主 LLM 复核
                 installMutualMaintenance(ctx, { heartbeatMs: config.mutual.heartbeatMs }, {
+                    // memory 通道 → 认知图（md_cg = 唯一真源）。
+                    // 显式调用：MdcgClient.verifyClaim → cg(op=read) + 依据强度判定。
+                    // 回退通道已下线（aeis 能力库随进程剥离；md_cg 是唯一大脑）：
+                    // 认知图不可用时按白箱纪律 fail-closed，不编造判定。
                     verify: async (claim) => {
-                        const r = await bridge.callTool('wisdom_verify', { knowledge: claim, limit: 4 });
-                        // P1 修复（GPT 审查）：结果在 content[].text（JSON），非 .result
-                        const text = mcpText(r);
-                        let data = {};
-                        try {
-                            data = JSON.parse(text);
+                        if (mdcg?.isReady()) {
+                            try {
+                                return await mdcg.verifyClaim(claim);
+                            }
+                            catch (err) {
+                                ctx.logger.warn(`dsh-memory: 认知图核验失败，按 fail-closed 处理：${String(err)}`);
+                            }
                         }
-                        catch { /* 非 JSON 时用默认 */ }
-                        return {
-                            judgment: data.judgment ?? '分析中',
-                            best: data.best?.name ?? '',
-                            d_norm: typeof data.D_norm === 'number' ? data.D_norm : -1,
-                            record_id: data.record_id ?? '',
-                        };
+                        else {
+                            ctx.logger.warn('dsh-memory: 认知图未就绪，核验按 fail-closed 处理');
+                        }
+                        return { judgment: '无法核验', best: '', d_norm: -1, record_id: '' };
                     },
                     review: async (claim, w) => {
-                        // DeepSeek 复核（在白箱判定之上，不重复白箱工作）
-                        const reviewResult = await bridge.callTool('think', {
-                            query: `复核以下主张（白箱判定已给出，请独立评估是否同意）：${claim.slice(0, 200)}。白箱判定：${w.judgment}，best=${w.best}。只输出 同意/质疑/不同意 + 一句话理由`,
-                        });
-                        // P1 修复（GPT 审查）：文本在 content[].text；结论解析必须先查
-                        // 「不同意/不通过」再「质疑」再「同意」——「不同意」含子串「同意」，
-                        // 此前先匹配「同意」→ 不同意被误判为同意
-                        const text = mcpText(reviewResult);
+                        // 复核通道改走**宿主 LLM**（aeis 的 think 工具随进程下线）。
+                        // 取 llm 服务：Cordis 未 inject 的属性访问会抛，ctx.get 安全返回 undefined。
+                        const llm = ctx.get('llm');
+                        const prov = llm?.listProviders?.()
+                            ?.find((p) => p?.id && p.id !== 'lingshu-whitebox');
+                        if (!llm?.stream || !prov?.id) {
+                            ctx.logger.warn('dsh-memory: 宿主 LLM 不可用，复核按 fail-closed 处理（不编造结论）');
+                            return { conclusion: '不同意', reason: '复核通道不可用（宿主 LLM 未就绪）' };
+                        }
+                        let text = '';
+                        try {
+                            const stream = llm.stream({
+                                provider: prov.id,
+                                model: prov.model ?? prov.id,
+                                messages: [{
+                                        role: 'user',
+                                        content: [{
+                                                type: 'text',
+                                                text: `复核以下主张（白箱判定已给出，请独立评估是否同意）：${claim.slice(0, 200)}。白箱判定：${w.judgment}，best=${w.best}。只输出 同意/质疑/不同意 + 一句话理由`,
+                                            }],
+                                    }],
+                                maxTokens: 256,
+                            });
+                            for await (const chunk of stream) {
+                                if (typeof chunk?.text === 'string' && chunk.type !== 'reasoning-delta')
+                                    text += chunk.text;
+                            }
+                        }
+                        catch (err) {
+                            ctx.logger.warn(`dsh-memory: 复核 LLM 调用失败，按 fail-closed 处理：${String(err)}`);
+                            return { conclusion: '不同意', reason: '复核调用失败（fail-closed）' };
+                        }
+                        // 结论解析：必须先查「不同意/不通过」再「质疑」再「同意」——「不同意」
+                        // 含子串「同意」，颠倒顺序会把不同意误判为同意（P1 修复，勿回退）。
                         const conclusion = text.includes('不同意') || text.includes('不通过')
                             ? '不同意'
                             : text.includes('质疑') ? '质疑'
@@ -215,15 +366,17 @@ export async function apply(ctx, config) {
     catch (err) {
         // 探针：记录 apply 失败的具体错误（定位插件加载失败根因）
         probeApplyError(err);
-        bridge.dispose();
+        mdcg?.dispose();
+        capability?.dispose();
         throw err;
     }
     ctx.effect(() => {
         return () => {
             for (const dispose of disposers)
                 dispose();
-            bridge.dispose();
-            ctx.logger.info('dsh-memory: 已卸载（工具已注销，灵枢进程已退出）');
+            mdcg?.dispose();
+            capability?.dispose();
+            ctx.logger.info('dsh-memory: 已卸载（工具已注销，md_cg 大脑 / 可选身体后端进程已退出）');
         };
     }, 'dsh-memory');
 }

package/lib/lib/datapath.d.ts

@@ -0,0 +1,16 @@
+export declare const ENV_DATA_ROOT = "MDCG_DATA_ROOT";
+export declare const ENV_MDCG_ROOT = "MDCG_ROOT";
+/** 插件仓根目录：自本模块所在目录向上找 package.json（对构建层级不敏感）。 */
+export declare function repoRoot(): string;
+/** 用户可编辑的路径配置文件（固定在插件仓 data/，不受 dataRoot 取值影响）。 */
+export declare function pathsFile(): string;
+export declare function defaultDataRoot(): string;
+/** 数据根（记忆/账本/运行态的父目录）。 */
+export declare function dataRoot(): string;
+/**
+ * 认知图根（记忆唯一真源）。
+ * @param configured 插件配置项 `mdcg.root`；空串/未给=None 表示未指定，走默认。
+ */
+export declare function mdcgRoot(configured?: string): string;
+/** 当前解析快照（供启动日志留痕——把「记忆真源在哪」写进可审计痕迹）。 */
+export declare function describeDataPaths(configured?: string): Record<string, string | boolean>;

package/lib/lib/datapath.js

@@ -0,0 +1,114 @@
+/**
+ * datapath.ts · 灵枢数据根解析（记忆写入路径可配置）
+ *
+ * 与 Python 侧 `md_cg/datapath.py` **同口径**——两侧读同一份
+ * `<插件仓>/data/paths.json`，避免大脑与脚本对「记忆真源在哪」各持一说。
+ *
+ * 优先级（高 → 低）：
+ *   1. 环境变量 `MDCG_DATA_ROOT`（数据根）／ `MDCG_ROOT`（认知图根）
+ *   2. 用户可编辑配置 `<插件仓>/data/paths.json` 的 `data_root` / `root`
+ *   3. 插件配置项 `mdcg.root`（可为空=未指定）
+ *   4. 默认 `<插件仓>/data/mdcg`（**自身仓库**，与进程 cwd 解耦）
+ *
+ * 为什么默认不再取「相对 cwd 的 data/mdcg」：
+ *   node 侧插件与 python 侧脚本的 cwd 不同，相对路径会漂移成
+ *   `<cwd>/data/mdcg`。历史事故：宿主 cwd 落在 AEIS 时，记忆真源
+ *   分裂到 `AEIS/data/mdcg`，与插件仓 `data/` 变成互不可见的两处。
+ *   锚定 `package.json` 所在目录后，默认值稳定且可预期。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const ENV_DATA_ROOT = 'MDCG_DATA_ROOT';
+export const ENV_MDCG_ROOT = 'MDCG_ROOT';
+let cachedRepoRoot = null;
+/** 插件仓根目录：自本模块所在目录向上找 package.json（对构建层级不敏感）。 */
+export function repoRoot() {
+    if (cachedRepoRoot)
+        return cachedRepoRoot;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        if (existsSync(join(dir, 'package.json'))) {
+            cachedRepoRoot = dir;
+            return dir;
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    // 兜底：lib/lib/x.js 或 lib/x.js → 均回到仓根
+    cachedRepoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return cachedRepoRoot;
+}
+/** 用户可编辑的路径配置文件（固定在插件仓 data/，不受 dataRoot 取值影响）。 */
+export function pathsFile() {
+    return join(repoRoot(), 'data', 'paths.json');
+}
+function readUserPaths() {
+    try {
+        const raw = readFileSync(pathsFile(), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 相对路径一律对「插件仓根」解析（不随宿主 cwd 漂移）。 */
+function anchor(p) {
+    return isAbsolute(p) ? p : resolve(repoRoot(), p);
+}
+export function defaultDataRoot() {
+    return join(repoRoot(), 'data');
+}
+/** 数据根（记忆/账本/运行态的父目录）。 */
+export function dataRoot() {
+    const env = process.env[ENV_DATA_ROOT];
+    if (env)
+        return anchor(env);
+    const cfg = readUserPaths()['data_root'];
+    if (typeof cfg === 'string' && cfg)
+        return anchor(cfg);
+    return defaultDataRoot();
+}
+/**
+ * 认知图根（记忆唯一真源）。
+ * @param configured 插件配置项 `mdcg.root`；空串/未给=None 表示未指定，走默认。
+ */
+export function mdcgRoot(configured) {
+    const env = process.env[ENV_MDCG_ROOT];
+    if (env)
+        return anchor(env);
+    const cfg = readUserPaths()['root'];
+    if (typeof cfg === 'string' && cfg)
+        return anchor(cfg);
+    if (configured && configured.trim())
+        return anchor(configured.trim());
+    return join(dataRoot(), 'mdcg');
+}
+/** 当前解析快照（供启动日志留痕——把「记忆真源在哪」写进可审计痕迹）。 */
+export function describeDataPaths(configured) {
+    const dr = dataRoot();
+    const mr = mdcgRoot(configured);
+    const paths = readUserPaths();
+    let source = 'default(插件仓自身 data/)';
+    if (process.env[ENV_DATA_ROOT])
+        source = `env:${ENV_DATA_ROOT}`;
+    else if (process.env[ENV_MDCG_ROOT])
+        source = `env:${ENV_MDCG_ROOT}`;
+    else if (typeof paths['data_root'] === 'string' || typeof paths['root'] === 'string')
+        source = 'paths.json';
+    else if (configured && configured.trim())
+        source = 'config.mdcg.root';
+    return {
+        repoRoot: repoRoot(),
+        dataRoot: dr,
+        mdcgRoot: mr,
+        source,
+        pathsFile: pathsFile(),
+        isDefault: dr === defaultDataRoot(),
+        dataRootExists: existsSync(dr),
+        mdcgRootExists: existsSync(mr),
+    };
+}