dsh-data-domain-knowledge 0.1.0-alpha.1

package/lib/types/layout.js

@@ -0,0 +1,312 @@
+/**
+ * Tita Agent 在磁盘上的六段布局（0029 定四段，0032 扩到六段）。
+ *
+ * ## 为什么要有这个文件
+ *
+ * 0029 之前，「东西存在哪」有**两个**入口：知识插件的 `rootDir`（知识树落在
+ * 哪）和转换内核自己的 `rootDir`（交付与工作目录落在哪）。两处都手输路径，两处
+ * 都可能指向不同的卷，于是「这个 Agent 的东西在哪」这个问题没有唯一答案 ——
+ * 备份要记得两个路径，换机器要改两处，用户也没法一眼看出磁盘上哪块是它的。
+ *
+ * 现在**只有一个设置**：Tita Agent 根路径。根路径下固定六段，职责互不重叠：
+ *
+ * ```
+ * <agentRoot>/
+ *   domain_knowledge/          知识本身（唯一的真相来源，必须备份）
+ *     <知识库 id>/             一个知识库 = 一棵独立的树（0021）
+ *       01_source_truth/       SourceRaw：原始可追溯文档
+ *       02_wiki/               Wiki 卡片（人可读的结论）
+ *       03_compiled/           编译产物：wikiNotes / 向量 / 知识图谱
+ *       05_diagnosis/          智能归因图谱（派生层，可重建）
+ *   memory/                    记忆：版本快照、反馈、访问审计（0032 从知识树搬出）
+ *     <知识库 id>/             二级按知识库分叉
+ *   intent/                    意图：registry.json（分类 / act）+ records.ndjson（留痕）
+ *   tmp/                       运行期临时文件：转换工作区、任务状态
+ *     <YYYY-MM-DD>/            二级按日期分桶
+ *   resource/                  Agent 跑起来所需要的家当（不是它的产出）
+ *     models/                 嵌入与重排模型
+ *     python/                 本地嵌入/重排用的虚拟环境
+ *     knowledge-bases.json    知识库注册表
+ * ```
+ *
+ * ## 六条原理（这是两次调整的重点）
+ *
+ * 1. **`domain_knowledge` 与 `output` / `tmp` 的边界是「能不能重建」**，不是
+ *    「谁写的」。知识树里每一样东西要么是别的层重建出来的（`03_compiled`、
+ *    `05_diagnosis`），要么是不可再生的原始记录（`01_source_truth`、`02_wiki`）——
+ *    它们同属一个必须整体备份的单位，所以同在一棵树下、按知识库分叉。`output` 是
+ *    **交付物**：转换出来的 Markdown 与图片，用户会把它拷走或录入知识库；`tmp` 是
+ *    **中间态**：转换的工作目录与任务队列快照，删掉最多让一个未完成的任务失败。
+ *    三者删掉任何一个的后果完全不同，所以不混住。
+ * 2. **日期只做二级，且只在 `output` / `tmp` 里做。** 这两处是「按时间堆积」的
+ *    东西：没有日期分桶，一个月后 `output` 就是一个几百条平铺的目录，`ls` 出来
+ *    读不出「上周那份报表在哪」。知识树**不按日期分**：它的组织维度是知识库与
+ *    知识层级，日期在那里只会把同一张卡片的历史切散。
+ * 3. **知识库目录名用 id，不用显示名。** 显示名可以随时改、可以带空格与中文，
+ *    而目录名一旦定了就不该跟着改 —— 否则改一次名字，磁盘上就多一份孤儿数据。
+ *    id 在创建时由名字派生（见 `KnowledgeBases.nextId`）且此后不可变，是唯一
+ *    既是人可读、又稳定的选择。
+ * 4. **依赖也进根路径，但它单独一段。** `resource/` 装的是模型、Python 环境与
+ *    注册表：没有它们 Agent 跑不动，但它们不是这个 Agent 的产出。把它们放进根路径
+ *    是为了让「这个 Agent 的全部磁盘足迹」是一个目录 —— 备份、迁移、整个删掉都只
+ *    需要认一个路径，而不是「一个数据目录 + 一个藏在 `~/.tita-data-agent` 的家当
+ *    目录」。单独成段是因为**删它们的后果和另外几段完全不同**：删 `output`/`tmp`
+ *    什么都不损失，删 `resource` 会让语义检索失效。
+ * 5. **记忆（`memory/`）从知识树里搬出来，因为它不是「一个知识库的知识」。**
+ *    它装的是版本快照、反馈与访问审计 —— 这些都是**关于这个 Agent 的动作留痕**，
+ *    而不是关于知识本身的断言。原来它躺在 `domain_knowledge/<库>/04_memory/`，
+ *    于是有两个说不通的地方：一是「备份知识树」被迫连审计流水一起备份，二是
+ *    「知识树有哪几段」这个问题里混进了一个跨库同构的横切层。搬出来之后知识树
+ *    只剩「知识」，`memory/<库 id>/` 与它平级、同样按库分叉（理由同原理 3）。
+ *    **代价是知识树段号留了一个空位**（没有 `04_`）：那是对的，段号是历史，
+ *    把 `05_diagnosis` 改成 `04_diagnosis` 会让所有已存在的树在迁移时被当成
+ *    陌生目录，而收益只是好看。
+ * 6. **意图（`intent/`）与记忆平级，但它不分库。** 意图是**会话级**的：同一句话
+ *    在哪个知识库下说，理解方式不该变。它的两份东西 —— 分类/act 注册表（配置）
+ *    与每轮记录（留痕）—— 原来一个住在宿主的 settings 文档里、一个只在内存里，
+ *    都不是「这个 Agent 自己的文件」；落进根路径之后，它们和知识、记忆一样可以
+ *    被备份、被 diff、被用户直接读。
+ *
+ * 这个文件是布局的**唯一真源**：运行时、知识库注册表、转换内核、设置面板读到的
+ * 都是这里算出来的路径，不在别处再拼一次字符串。
+ *
+ * @module
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * 根路径下固定存在的段。顺序即它们在文档与界面里出现的顺序。
+ *
+ * 分两组看，判据不同：
+ *
+ * - **Agent 自己的东西**：`domain_knowledge`（知识）、`memory`（记忆）、`intent`
+ *   （意图记录）、`tmp`（运行期临时态）。判据是「能不能重建」。
+ * - **跑起来所需的依赖**：`resource`（模型、Python 环境、注册表）。判据是「属于谁」。
+ *
+ * **`output` 不在这里。** 交付物是**某个工作项目的产物**，不是这个 Agent 的固有状态：
+ * 「分析华东区渠道压货」产出的那几张图属于那个项目，换一个项目打开就不该再看见它。
+ * 所以它落在**当前工作区**的 `output/<日期>/` 下，而不是跟着 Agent 的家走。
+ * 约定写在 preset 的人格提示词里（`preset/tita-data-agent/agent.cordis.yml` 的工作规则）。
+ */
+export const AGENT_DIRS = ['domain_knowledge', 'memory', 'intent', 'tmp', 'resource'];
+/** 知识树那一段的目录名。 */
+export const DOMAIN_KNOWLEDGE_DIR = 'domain_knowledge';
+/**
+ * 交付物那一段的目录名。
+ *
+ * 注意它**不在** `AGENT_DIRS` 里：交付物落在工作区，不落在 Agent 根路径。
+ */
+export const OUTPUT_DIR = 'output';
+/** 运行期临时文件那一段的目录名。 */
+export const TMP_DIR = 'tmp';
+/**
+ * Agent 跑起来所需要的家当那一段的目录名。
+ *
+ * 里面装的是「没有它就跑不动、但它不是这个 Agent 的产出」的东西：
+ * `models/`（嵌入与重排模型）、`python/`（本地嵌入用的虚拟环境）、
+ * `knowledge-bases.json`（知识库注册表）。
+ *
+ * 它和另外三段的区别在**归属**而不是可重建性：删掉模型不会丢数据，但 Agent 会
+ * 失去语义检索能力；而删掉 `output`/`tmp` 什么都不损失。所以它是四段里唯一
+ * 「删之前要想一下」的那一段。
+ */
+export const RESOURCE_DIR = 'resource';
+/**
+ * 记忆那一段的目录名（0032）。
+ *
+ * 里面装的是 `04_memory` 原来的三样东西：SourceRaw 版本快照、Wiki 卡片版本快照、
+ * 反馈与访问审计。它从知识树里**搬出来**了，理由见文件头第 5 条原理。
+ */
+export const MEMORY_DIR = 'memory';
+/**
+ * 意图那一段的目录名（0032）。
+ *
+ * 里面装的是意图的**配置与留痕**：`registry.json`（分类 / act 词表）与
+ * `records.ndjson`（每轮一条意图记录，append-only）。这两样原来一个住在宿主的
+ * settings 文档里、一个只在内存里 —— 都不是「这个 Agent 自己的文件」。
+ */
+export const INTENT_DIR = 'intent';
+/**
+ * 默认根路径：`~/Desktop/titaagent`。
+ *
+ * 落在**桌面**是刻意的：这四段目录是用户自己的东西，放在一个他们看得见、能直接
+ * 打开、能自己备份的位置，比藏进 `~/.tita-data-agent` 更诚实。这也正是 0029 之前
+ * 默认知识树的位置（`~/Desktop/titaagent/domain_knowledge`），所以对没改过设置的
+ * 用户来说，知识树**原地不动**。
+ */
+export function defaultAgentRoot() {
+    return resolve(process.env.DSH_AGENT_ROOT || join(homedir(), 'Desktop', 'titaagent'));
+}
+/** 0029 之前的知识树根：用户显式设过的 `rootDir`，或旧默认位置。只用于迁移。 */
+export function legacyKnowledgeRoot() {
+    const inRepo = join(process.cwd(), 'domain_knowledge');
+    return resolve(process.env.DSH_KNOWLEDGE_ROOT
+        || (existsSync(inRepo) ? inRepo : join(defaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR)));
+}
+/**
+ * 迁移的兜底来源：**没设过 `rootDir`** 的用户，旧树在旧默认位置。
+ *
+ * 与 `legacyKnowledgeRoot()` 的差别只有一条：**不认仓库里那个 `domain_knowledge`**。
+ * 那是 0025 留下的开发便利（进程 cwd 里恰好有一棵树就用它），而迁移是**搬数据**，
+ * 按 cwd 决定搬谁太危险 —— 一个恰好放了对拍夹具的目录会被搬去桌面。
+ */
+export function legacyDefaultKnowledgeRoot() {
+    return resolve(process.env.DSH_KNOWLEDGE_ROOT || join(defaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR));
+}
+/** `<agentRoot>/domain_knowledge`。 */
+export function domainKnowledgeRoot(agentRoot) {
+    return join(resolve(agentRoot), DOMAIN_KNOWLEDGE_DIR);
+}
+/**
+ * 一个知识库的根目录：`<agentRoot>/domain_knowledge/<知识库 id>`。
+ *
+ * `id` 由调用方保证已是文件系统安全的（注册表生成的 id 只含 `[a-z0-9-]`）。
+ */
+export function knowledgeBaseRoot(agentRoot, kbId) {
+    return join(domainKnowledgeRoot(agentRoot), kbId);
+}
+/**
+ * 交付物的落点：`<工作区>/output`。
+ *
+ * 刻意**不**由 `agentRoot` 推出来。交付物是**某个工作项目的产物** —— 同一个 Agent
+ * 换一个项目打开，不该再看见上一个项目产出的图和数据。知识、记忆、意图记录是 Agent
+ * 自己的、跨项目累积的东西，所以留在 `agentRoot`；交付物属于项目，所以跟着项目走。
+ *
+ * 二级目录按日期分桶（`output/<YYYY-MM-DD>/`），由转换内核的 `bucketByDay` 打开；
+ * Agent 自己写文件时的命名约定见 preset 的人格提示词。
+ *
+ * @param workspace - 当前工作项目的绝对路径。
+ */
+export function workspaceOutputRoot(workspace) {
+    return join(resolve(workspace), OUTPUT_DIR);
+}
+/** `<agentRoot>/tmp`。 */
+export function tmpRoot(agentRoot) {
+    return join(resolve(agentRoot), TMP_DIR);
+}
+/**
+ * 随插件分发的 preset **真源目录**：`<包根>/preset/tita-data-agent/`。
+ *
+ * ## 它和「DSH 装好的 preset」不是一回事
+ *
+ * 0.1.7 起 DSH 那边 preset 不再是一个目录，而是 profile 组合里的一条声明行
+ * （见 docs/0036）。但**写提示词的人需要一个能编辑的地方**，那个地方就是这里：
+ * `agent.cordis.yml` 的 `persona` 行是提示词的唯一真源，改完跑 `pnpm sync:preset`
+ * 把它编译进 `cordis.patch.yml`。所以「打开 preset 目录」打开的是这个目录 ——
+ * 不是 DSH 内部某个装好的副本（那种副本不存在，存在也会被下次编译覆盖）。
+ *
+ * 从 `lib/types/index.js` 回退两级就是包根，所以这个路径在源码仓库里跑和从
+ * npm 安装后跑都成立。路径不存在时调用方应当如实说明，而不是弹一个空目录。
+ */
+export function presetSourceDir() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '../../preset', TITA_PRESET_ID);
+}
+/**
+ * 这个 preset 的 id。与 `src/client/agent-preset.ts` 的 `TITA_PRESET_ID`、
+ * `scripts/install-agent-preset.mjs` 的 `PRESET_ID` 是同一个值 —— 三处各留一份
+ * 是因为它们分属三个编译单元（宿主 / 浏览器 / 脚本），测试会钉住它们一致。
+ */
+export const TITA_PRESET_ID = 'tita-data-agent';
+/** `<agentRoot>/resource`。 */
+export function resourceRoot(agentRoot) {
+    return join(resolve(agentRoot), RESOURCE_DIR);
+}
+/** `<agentRoot>/resource/models`：嵌入与重排模型。 */
+export function resourceModels(agentRoot) {
+    return join(resourceRoot(agentRoot), 'models');
+}
+/**
+ * `<agentRoot>/resource/python`：本地嵌入/重排用的虚拟环境。
+ *
+ * 里面装的是一个 uv 建的 venv。**移动它是安全的**：`pyvenv.cfg` 的 `home` 指向
+ * 基础解释器（不是自己），`bin/python` 是指向基础解释器的软链，插件也是直接按
+ * 绝对路径调用 `bin/python`，不依赖 shebang。所以从 `~/.tita-data-agent` 搬进
+ * 根路径不需要重建环境。
+ */
+export function resourcePython(agentRoot) {
+    return join(resourceRoot(agentRoot), 'python');
+}
+/** `<agentRoot>/resource/knowledge-bases.json`：知识库注册表（配置）。 */
+export function resourceRegistry(agentRoot) {
+    return join(resourceRoot(agentRoot), 'knowledge-bases.json');
+}
+/**
+ * 本地日期的 `YYYY-MM-DD`。
+ *
+ * 用本地时间而不是 UTC：这个目录名是给坐在电脑前的人读的，「今天的输出」就该是
+ * 他日历上的今天，而不是某个可能差一天的 UTC 日期。
+ */
+export function dayKey(date = new Date()) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** `<root>/<YYYY-MM-DD>`：`output` 与 `tmp` 的二级日期桶。 */
+export function datedDir(root, date = new Date()) {
+    return join(root, dayKey(date));
+}
+/** 由根路径算出六段布局。纯函数，测试直接断言。 */
+export function agentLayout(agentRoot) {
+    const root = resolve(agentRoot);
+    return {
+        agentRoot: root,
+        domainKnowledge: join(root, DOMAIN_KNOWLEDGE_DIR),
+        tmp: join(root, TMP_DIR),
+        resource: join(root, RESOURCE_DIR),
+        memory: join(root, MEMORY_DIR),
+        intent: join(root, INTENT_DIR),
+    };
+}
+/**
+ * `<agentRoot>/memory/<知识库 id>`：某个知识库的记忆段（0032）。
+ *
+ * 二级用**知识库 id** 而不是平铺：记忆里装的是 `source-versions/<docSlug>/` 与
+ * `card-versions/<type>/<id>/`，两个知识库完全可能各有一份同名的来源 ——
+ * 平铺会让它们的版本历史互相覆盖。分叉之后「记忆属于哪个库」在路径上就成立，
+ * 与知识树同一套 id（`KnowledgeBases` 里不可变的那个）。
+ */
+export function memoryRoot(agentRoot, kbId) {
+    return join(resolve(agentRoot), MEMORY_DIR, kbId);
+}
+/** `<agentRoot>/intent`：意图的配置与留痕（0032）。意图不分库。 */
+export function intentRoot(agentRoot) {
+    return join(resolve(agentRoot), INTENT_DIR);
+}
+/**
+ * 一个知识库根目录是否**已经是**一棵知识树。
+ *
+ * 迁移的判据用它，而不是「目录是否存在」：`domain_knowledge/<id>` 可能是刚建出来
+ * 的空壳（注册表 `create()` 就会先 `mkdir`），空壳不该让迁移误判为「目标已占用」。
+ */
+export function looksLikeKnowledgeTree(path) {
+    return existsSync(join(path, '01_source_truth')) || existsSync(join(path, '03_compiled'));
+}
+/** 旧布局的判据：`01_source_truth` 直接躺在被检查的目录下。 */
+export function looksLikeLegacyKnowledgeRoot(path) {
+    if (!path)
+        return false;
+    return basename(path) !== '' && looksLikeKnowledgeTree(path);
+}
+/**
+ * 把根路径下固定存在的段建出来。
+ *
+ * 在启动时调用一次：用户第一次打开控制台就能在磁盘上看到这四段，而不是等到
+ * 恰好有一次转换或一次写入才凭空出现 —— 「目录结构」本身就是这个方案要交代的
+ * 东西，它不该是隐式的。交付物（`output/`）不在这里：它跟着工作项目走。
+ *
+ * 同步 fs：调用点是 `apply()`（同步），而且只是四次 `mkdir`。
+ */
+export function ensureAgentLayout(agentRoot) {
+    const layout = agentLayout(agentRoot);
+    for (const dir of [layout.domainKnowledge, layout.tmp, layout.resource, layout.memory, layout.intent]) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            /* 目录建不出来（权限/只读卷）不该让插件起不来：真正的写入会自己报错。 */
+        }
+    }
+    return layout;
+}
+//# sourceMappingURL=layout.js.map

package/lib/types/layout.js.map

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

package/lib/types/migrate.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 0029 的一次性迁移：把旧布局的知识树搬进新根路径。
+ *
+ * ## 为什么要迁移
+ *
+ * 0029 之前，「知识树在哪」由用户直接设的那个 `rootDir` 决定，而它指向的是**知识树
+ * 本身** —— `01_source_truth` 直接躺在它下面。新布局多了一层：`rootDir` 变成
+ * `agentRoot`，知识树退到 `<agentRoot>/domain_knowledge/<知识库 id>`。
+ *
+ * 也就是说，对**改过** `rootDir` 的用户，磁盘上那棵树的位置变了。数据不能跟着
+ * 设置一起改语义就消失，所以这里搬一次。
+ *
+ * ## 四条纪律
+ *
+ * 1. **只在真的有必要时动手。** 四个前置条件缺一不可：旧设置非空、旧位置确实是一棵
+ *    知识树、新位置不是同一处、新旧不是同一个目录。
+ * 2. **目标已有树就不碰。** 那说明用户已经在新布局下建过库，旧的那棵不是它的前身；
+ *    合并两棵来路不同的树比不迁移更糟。
+ * 3. **逐个目录搬，且只搬目标里还没有的。** 这既让迁移可重入（中断后重跑接着搬），
+ *    也保证永远不覆盖目标里已有的数据。
+ * 4. **搬不动就如实说，不回滚也不假装。** 失败时返回 `failed` 与原因，两边数据
+ *    都留在原地；调用方把它写进 `/knowledge/stats`，界面上能看到。
+ *
+ * 用同步 fs：迁移发生在设置解析的回调里，而 runtime 必须在**迁移完成之后**才按新
+ * 路径构造 —— 异步化会把这段顺序打散。搬的是目录项（`rename` 是元数据操作，与树
+ * 的大小无关），跨卷时退化成复制，代价可控。
+ *
+ * @module
+ */
+export interface MigrationOutcome {
+    /** `skipped` 无事可做 / `moved` 搬成功 / `failed` 搬失败。 */
+    status: 'skipped' | 'moved' | 'failed';
+    /** 旧位置（`skipped` 且没有旧设置时为空）。 */
+    from?: string;
+    /** 新位置。 */
+    to?: string;
+    /** 实际搬过去的目录名。 */
+    moved?: string[];
+    /** 为什么跳过 / 为什么失败。界面直接展示这句话。 */
+    reason?: string;
+}
+/**
+ * 把 `legacyRoot` 下的知识树搬进 `<agentRoot>/domain_knowledge/<kbId>`。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.legacyRoot - 用户旧设置里的知识树根；空串表示没有旧设置。
+ * @param input.kbId - 承接这棵树的知识库 id，缺省 `default`。
+ * @returns 迁移结论。**不抛异常** —— 迁移失败不该让插件起不来。
+ */
+export declare function migrateLegacyKnowledgeTree(input: {
+    agentRoot: string;
+    legacyRoot: string;
+    kbId?: string;
+}): MigrationOutcome;
+/**
+ * 0029：把 Agent 的**家当**从 `~/.tita-data-agent` 搬进 `<agentRoot>/resource`。
+ *
+ * 搬三样：`models/` → `resource/models`、`embedding-venv/` → `resource/python`、
+ * `knowledge-bases.json` → `resource/knowledge-bases.json`。
+ *
+ * ## 四条纪律
+ *
+ * 1. **先 rename，不先 copy。** 这三样加起来 2.7G，而 `~/.tita-data-agent` 与默认
+ *    根路径在同一个卷上，`rename` 是元数据操作、瞬间完成。跨卷（EXDEV）时**不自动
+ *    复制** —— 一个 2.7G 的静默复制可能填满磁盘、可能花十分钟，那不是迁移该偷偷
+ *    做的事，所以如实报 `failed` 让用户自己决定。
+ * 2. **目标已存在就不动。** 用户可能已经在新位置放了自己的模型；覆盖它是不可接受
+ *    的失败。
+ * 3. **只搬存在的。** 全新安装没有这些东西，那就不搬，不是错误。
+ * 4. **按条目合并，不按目录整体跳过。** 「目标目录存在」不等于「这一样搬完了」：
+ *    用户可能只往 `resource/models/` 里放了一个重排模型，而 `models/` 里的嵌入模型
+ *    还留在旧位置 —— 整体跳过会让它**永远搬不过来**（因为迁移只跑一次）。所以
+ *    `models/` 逐个子项搬，目标里已有的子项跳过。这同时让迁移更可重入。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.legacyHome - 旧的 `TITA_DATA_AGENT_HOME`（默认 `~/.tita-data-agent`）。
+ * @returns 迁移结论；`moved` 里是真正搬过去的项（`models/<名字>` 会带上子项名）。
+ */
+export declare function migrateLegacyResources(input: {
+    agentRoot: string;
+    legacyHome: string;
+}): MigrationOutcome;
+/**
+ * 0032：把记忆段从知识树里搬出来 —— `<知识库根>/04_memory` → `<agentRoot>/memory/<库 id>`。
+ *
+ * ## 为什么搬
+ *
+ * 记忆装的是版本快照、反馈与访问审计：它们是**关于这个 Agent 的动作留痕**，不是
+ * 关于知识的断言。留在知识树里有三个说不通的地方：备份知识树被迫连审计流水一起
+ * 备份；「知识树有哪几段」这个问题里混进了一个横切层；多知识库时每棵树各存一份
+ * 同构的流水。搬出来之后知识树只剩知识，记忆与它平级、同样按库分叉。
+ *
+ * ## 纪律
+ *
+ * 与家当迁移同源，但**这里允许合并**：目标里已经有同名条目时跳过（用户可能已经
+ * 在新位置写过记忆），其余照搬。跨卷时退化成复制 + 删除 —— 记忆是**数据**，不是
+ * 可以重新下载的模型，所以这里不像家当迁移那样「不自动复制」：丢掉版本历史比
+ * 复制几百 MB 严重得多。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.kbRoot - 这个知识库的根（`<agentRoot>/domain_knowledge/<id>`）。
+ * @param input.kbId - 知识库 id，决定记忆落在 `memory/` 下的哪一格。
+ * @returns 迁移结论。**不抛异常** —— 迁移失败不该让插件起不来。
+ */
+export declare function migrateLegacyMemory(input: {
+    agentRoot: string;
+    kbRoot: string;
+    kbId: string;
+}): MigrationOutcome;
+//# sourceMappingURL=migrate.d.ts.map

package/lib/types/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAmBH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;IACtC,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW;IACX,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAOD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAuC5H;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAoEzG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CA+BhH"}