# ACCESS-DESIGN — 历史会话接入蓝图(让用户把"他们的历史"请进来)

> 状态:2026-09-08 方向已拍板(见 §7 决策记录),本文是实施时的对照蓝本。
> 服务对象:**非开发者用户**——想用"TA 与 TA 的 AI 的共同对话历史"培养自己的器灵(每人不同:小灵、小肥鱼,或任何别的名字)。

## 0. 四条铁律

1. **零数据库知识**:绝不要求用户"把库改造成什么样"再接入——schema 是插件的事;
2. **数据本地**:文件只在浏览器 → 本机插件之间流动,不上任何云;
3. **渐进接入**:有多少给多少——轻量档先入,完整消息与摘要由后台管线慢慢补;
4. **幂等安全**:重复导入只刷新、不重复;绝不覆盖用户态字段(summary / importance / 置顶)。

## 1. 会话契约 v1(统一搬运格式)

**文件形态**:JSON 或 JSONL(逐行一个会话对象;大文件优先 JSONL,便于流式分批)。

```
顶层: {"format":"dsh-ling-import","version":1,"sessions":[ … ]}   // JSON 数组亦可
```

**会话对象**:

```jsonc
{
  "id": "唯一 id(建议 平台:本地id;无则自动 文件:序号)",
  "startedAt": "2026-01-01T10:00:00Z",      // 与 updatedAt 至少其一
  "updatedAt": "2026-01-02T10:00:00Z",
  "title": "可选但强烈建议(缺省=首条用户消息前 40 字)",
  "category": "knowledge|daily|feeling",     // 可选,缺省走启发式
  // 二选一(深度可升级):
  "messages": [{ "role": "user|assistant", "text": "…", "at": "ISO" }],  // 完整档
  // 或 轻量档:
  "summary": "…", "keywords": ["…"]
}
```

- **完整档** → 原始轮次入库(dsh_turns_raw 语义)+ 生成概述,与 DSH 会话同质量;
- **轻量档** → 只入概述;后续由深摘/摘要管线按热度补全(叙事:"器灵先认得这些日子,再慢慢读你们的对话");
- 角色过滤与现有捕捉规则一致:仅 user/assistant;系统提示与 reasoning 丢弃;
- 同 `id` 再导入 = 更新刷新;轻量 → 完整可原地升级(补 raw)。

## 2. 通道(当前范围:先对齐 DeepSeek 体系)

| 通道 | 说明 | 状态 |
|---|---|---|
| **A. DSH 一键扫描** | 扫描本机 `~/.dsh/sessions` 存量(顶层会话、zstd 多帧解码、弱会话过滤、幂等)→ 收纳现有 `tools/backfill-dsh.mjs` 逻辑,用户零准备 | P0 |
| **B. 文件导入**(契约文件) | DeepSeek 网页端官方**无导出** → 发布材料(P1)附两种获取路径:① 已有 ds-search/数据整理产物(`deepseek_library.db` 或 conversations.json)→ 导入器直接接受 db 路径(现 scan-dsweb UI 化)或提供转换脚本导出为契约文件;② 从零开始:网页抓取不在本包范围,文档如实说明(P2 再决策是否自研) | P0(契约)/P1(网页端指引) |
| ~~C. 纯文本粘贴~~ | **暂缓**(2026-09-08):见下 | P2 再评估 |

**为什么文本粘贴暂缓(决策记录)**:① 批量历史靠手工复制粘贴成本畸高,与"接入应省力"相悖;② 它真正的价值只剩"补最近零散对话"这一小场景,与"想办法抓数据"的路径重叠且更弱;③ 未来若做官方/浏览器渠道抓取,该通道价值近零。故 P2 前不投入。

## 3. 导入流水线与工程约束

- **分页提交**:`/api` 读 body 上限 4MB → 前端流式读文件(JSONL 逐行),每批 ≤200 会话 POST;
- **端点语义**(`/import/batch` 或扩展现有 /import):逐批校验 → 返回 `{new, refreshed, skipped, broken}` 统计 → UI 确认后落库(每批事务);
- **幂等键**:`source="import:<平台>"` 命名空间 + 本地 id;轻量档不写空 summary 覆盖用户已有内容;
- **导入后衔接**:新概述 `overview_ok=1` 入队 → 现有 summarizer/deep 通道按热度自动补摘要与深摘;
- **进度体验**:批处理期间显示进度、可中断;完成后给一句"她开始读你的历史了"式的总结,而不是"已写入 N 行"。

## 4. UI:记忆中心 →「接入历史」页签

- 区块一:通道 A 一键扫描(按钮 + 结果:新增/刷新/跳过);
- 区块二:通道 B 文件导入(拖放/选文件 → 格式说明 → 预览表 新增/刷新/跳过/异常 → 确认导入);
- 区块三:帮助与文案(轻量/完整档是什么、如何拿到契约文件——DeepSeek 网页端指引在 P1 补入此区);
- 基调:接入 = "把你们的历史请进门",不是技术操作。

## 5. 命名空间与落库映射(实施对照)

| 契约字段 | 记忆库 |
|---|---|
| `id`(含命名空间) | conv_overview.conv_id / dsh_turns_raw.session_id |
| `source=import:<平台>` | conv_overview.source('dsweb'/'dsh' 之外的第三类) |
| startedAt / updatedAt / title / category | 同名列(类别缺省走启发式) |
| summary / keywords(轻量档) | 同名列(importance/heat/hit 不动) |
| messages(完整档) | dsh_turns_raw + 摘要管线 |

> 注意:引入第三来源后,L1/统计格/筛选器需确认对 `source` 的既有假设(现在 UI 按 dsweb/dsh 两类写死标签,需泛化为"已命名空间")。

## 6. 排期

- **P0**:通道 A 收纳 backfill;通道 B 契约导入(JSON/JSONL、两档深度);页签 UI;分页/幂等/校验统计;
- **P1**:DeepSeek 网页端数据获取指引;`deepseek_library.db` 直接导入(scan-dsweb UI 化);L1/统计对第三来源泛化;
- **P2(再评估)**:文本启发式通道;导出契约文件(器灵可搬家/备份到他人环境);是否自研网页抓取;多平台适配。

## 7. 决策记录(2026-09-08,作者拍板)

- ✅ 契约支持**轻量档**(仅标题/日期也可入,后续深摘补全);
- ✅ **只做文件接入**;纯文本粘贴暂缓(理由见 §2);
- ✅ 先对齐 **DeepSeek 体系**(DSH 存量 + 网页端文件/库);
- ✅ 向导入口 = **记忆中心内新页签**;
- ⏸ 对外叙事稿(起源→机制→效果)按下不表,另行撰写。

## 8. 实施状态

- **P0 已实施(2026-09-08)**:记忆中心「接入历史」页签(通道 A 一键扫描 + 通道 B JSON/JSONL 契约导入,200/批);host 模块 `lib/host/backfill.js`(tools/backfill-dsh.mjs 已改薄壳复用)与 `lib/host/import-file.js`;接口 `POST /dsh/backfill`、`POST /import/file/batch`;
- **库迁移**:conv_overview.source 曾 CHECK 限 dsweb/dsh → schema v2 放开(自动整表重建,数据无损,真机副本演练通过);`upsertOverview` 不再强制改写来源;
- **来源泛化**:记忆浏览筛选/概览统计/L1 溯源标签新增"文件导入(import)";
- 单测:`tests/importfile.test.mjs`(两档/幂等/降级/坏行/auto-id/来源过滤)全绿;全套回归绿。
- **诞生仪式已实施(2026-09-09)**:接入历史页签新增一键深摘(import 源,后台串行 + 轮询)+ 人格初稿合成(`POST /persona/genesis`)。纯函数与测试:`lib/host/genesis.js`、`tests/genesis.test.mjs`。
- **第 2 波(2026-09-10,按作者在真机验收后的拍板)**
  - genesis 原料 **scope 参数化**:"全部记忆"(全库加权抽样 ≤140,默认)vs"刚导入的这段";UI 下拉可选;提示明示「翻遍全部记忆,按生活/情感加权选出 N 条样本」;
  - **生活/情感加权**:feeling 1.0 / daily 0.7 / knowledge 0.2 + 置顶 +1.5(`GENESIS_WEIGHTS`);prompt 声明"她首先是伴侣,其次才是同事";"评价用户/画像类任务才平权"作为语义规则保留给未来层;
  - 原料三级取用:深摘(deep.sum)→ 非占位概述 → 原文片段(短会话,≤3 轮)/关键词线索——短会话不再静音;
  - **名字主客过滤**(`filterNamePairs`):剔除 userTitle 成分与常见称谓词;prompt 明令名字属于她;
  - **草稿制(乙方案)**:genesis 候选不再直接落盘;自述/名字单选加入草稿,语气建议与相处观察可一并携带;「带着草稿去人格中心人审」→ 对应字段旁浮现「她建议…[填入]」(纵向插入,修复过 flex 行溢出);语气/观察进入「她的话」区块,可一键**作为惯例记下**(`POST /persona/hint-adopt`,惯例成长通道,定型下无需手术);
  - **深摘语义**:一次跑完所有未读会话(含快速通过的短会话),进度「已完成 x / 本轮共 y · z%」;按钮「让她读未读过的会话」;全部读完时直接亮出自述按钮(非失败态);
  - 语音语气建议等错误 toast 补齐 `error` 字段兜底。
- **第 3 波(2026-09-11)**
  - **导入记录(留账)**:三条入口(文件导入 / 本机 DSH 扫描 / 网页端库扫描)每次成功都落一条账,`lib/host/import-log.js` 存 kv `import.log.<开始时刻>`(最近 50 条自动修剪),`GET /import/history` 倒序返回,「接入历史」页签底部卡片 D 展示;**一次导入 = 一条账**:传输层仍按批(200/批)发送,各批带同一 `runId` 由 host 累加(批数/失败批数一并入账),`at` 固定为导入开始时刻;失败批经 `POST /import/log` 上报;
  - **语气 P1**:`POST /persona/tone-advice`(只读,读两侧记忆归纳语气建议)+ `POST /persona/grow`(成长通道:语气枚举替换 + 风格只追加),归"自性类"、定型锁下免手术。
- **P1 待办**:DeepSeek 网页端数据获取指引;聊天记录库直接导入 UI 化;帮助文案。

## 9. 诞生仪式(genesis)设计速览(发布文档引用用)

1. **入口**:记忆中心 →「接入历史」页签底部「🌱 诞生仪式」卡;流程 = 让读(深摘未读)→ 第一次自我介绍(加权样本合成初稿)→ 人审草稿 → 人格中心落盘;
2. **初稿四件**:自述候选 ×2~3、名字组 ×2~3、语气建议、相处观察(JSON 契约,解析带围栏剥离与长度清洗);
3. **人审闭环**:草稿携带 → 字段旁「她建议…[填入]」/「她的话…作为惯例记下」;终审与保存一律在人格中心(新老用户同路径;已定型字段需手术门);
4. **材料口径**:她的名字/自述基于"生活情感优先"的加权样本;历史中属于用户的称谓一律过滤,不得混入她的身份。