README · 交接索引

README · 小手机（猫爪聊天）交接索引

生成时间：2026-10-27 00:45（北京时间） 生成方式：只读整理。未修改任何代码、未部署、未写入/迁移/删除任何生产数据。 适用对象：接手本项目的新 AI / 开发者。

1. 这份档案是什么

把 2026-10-05 ~ 10-27 的全部可访问历史（对话摘要、任务书、源码、提交、测试、部署、数据面）整理成 10 个文件，让接手者尽量不需要再问用户「以前做过什么」。

它不是：项目宣传稿、完整源码包、或对未来的承诺。它是「现状 + 历史 + 坑 + 待办」的底账。

2. 阅读顺序

3. 文件清单与作用

4. 资料来源与核实等级

4.1 实际读取过

• 本会话全部对话 + 30 个阶段压缩摘要（覆盖 10-05 ~ 10-25）
• /root/uploads/ 的任务书 v1.0（27KB）与原始前端 v6.html（56KB）
• worker.js 全文、index.html 全部逻辑区、deploy-web/* 全文、build.js、两份 wrangler 配置
• tests/ 10 个文件（说明与断言数）、tools/ 关键行
• 小手机-完整交付文档.md、任务交接说明.md、模块索引.md、安全说明.md、修复记录-P0-P1.md、国内版落库迁移方案.md、小手机-全新后端环境说明.md
• 国内版 SQLite（只读查询）、v1/v2 KV（抽样读）、Cloudflare API（worker/secret/bundle）、国内版 / 与 /health

4.2 知道存在但未读全

猫爪聊天-完整项目.md（304KB）、handoff-public.md / 小手机-交接-公开版.md（40KB×2）、替换指南.md、给其他AI-代码包/、小手机-审计草案/01–04、17 张截图、小手机交接/index.html。

4.3 无法访问

GitHub 远端实时状态、Cloudflare 线上日志、KV 精确键列表（配额耗尽）、secret 明文、用户浏览器数据、平台控制台、10-22 之前的逐字对话（仅存摘要）、部分已过期的截图链接。

4.4 证据标注

• 【源码】 读代码可得
• 【测试】 本地跑过（Mock，不等于线上）
• 【部署】 线上版本已确认
• 【实测】 我亲自执行并取得结果
• 【线上核验】 通过 Cloudflare API / 线上页面核对
• 【推断】 有间接证据但未闭环
• 【未验证】 无证据
• 【待确认】 需用户拍板

5. 三句话结论

1. 代码是好的，架构有三处硬伤：前后端两套寻址规则（聊天走设置、记忆走同源）、消息存两份但只删一份、页面公开下发令牌。
2. 数据是散的：v1 KV（历史主库，含 279 条软删）、v2 KV（全新空库）、国内版 SQLite（307 条导入+13 条新聊）、每台浏览器 IndexedDB（图只在这），四份互不同步。
3. 长期目标只完成了前四阶段：阶段 5 人设版本、6 成长分析、7 后台、8 沈屿迁移、9 清理，全部未开始。

6. 交接时的最小动作清单

接手者第一小时建议只做这些（全部只读）：

cd /workspace/chat
git log --oneline -20
git status
ls -la
wc -l worker.js index.html build.js deploy-web/server.js deploy-web/kv-sqlite.js

然后：

1. 读 01 → 04 → 07；
2. 用 Cloudflare API 核对 v1/v2 线上版本（不要 wrangler deploy）；
3. 用只读方式查国内版 GET /health；
4. 把 09 里的三个问题问用户；
5. 得到答复后再看 08，不要直接开工。

7. 红线（写在这里，防止新 AI 一上来就踩）

1. 不改用户没点名的区域；不重构、不改 UI 风格。
2. 不手工编辑 cat-chat-all-in-one.js；改完 worker.js/index.html 必须 node build.js。
3. 不部署、不清库、不改密钥，除非用户明确说「可以」。
4. 不批量删除；任何清理 ≤200 条/批、先导出、跨天做。
5. 不把「Mock 测试通过」说成「线上可用」。
6. 不把 AI 的建议写成「用户已同意」。
7. 不在文档里写任何真实密钥/令牌/密码。

01 · 项目总览与长期目标

01 · 项目总览与长期目标

档案版本：2026-10-27 ｜ 证据等级见 README ｜ 本文不含任何密钥、令牌或密码

1. 一句话

「小手机」= 猫爪聊天：一个单页、仿微信、手机优先的 AI 伴侣聊天 Web App。前端是唯一真源 index.html，后端是唯一真源 worker.js，构建时内联成单文件 cat-chat-all-in-one.js 部署到 Cloudflare Workers；另一套 Node 垫片（deploy-web/）把同一个 worker.js 跑在国内托管平台上，用 SQLite 代替 KV。数据按「角色（profile）」隔离，记忆分「长期记忆碎片 / 结构化档案 / 高光原话 / 经历 / 关联关系」五类，模型 Key 由用户在前端自填。

2. 项目起因与使用场景

• 起因：用户已有一个自写的聊天前端（上传文件 0643203b2611b966_v6.html，56,757 字节，仍在 /root/uploads/），要求在不重构、不改布局的前提下，把它升级成「有真实后端、有长期记忆、能主动搭话」的 AI 伴侣。
• 使用场景：手机浏览器 / 添加到主屏幕（PWA），日常一对一聊天；用户是唯一使用者，默认角色 owner。
• 真实角色：长期目标是接入角色「沈屿」的本体（历史聊天 + 人设 + 记忆迁移），当前阶段属于测试角色验证期（任务书原文要求：测试稳定后再删测试后端与测试数据，再迁移沈屿本体）。

3. 最初的需求（2026-10-05，原文要点）

用户第一条任务书写明「绝对不准重构我的代码结构，必须保留现有布局」，并要求一次性完成五组功能：

当时通过提问确认的三个方案（用户已确认）： 1. 后端 Worker 统一转发（Key 不进前端直连）； 2. 检索先用关键词匹配（不上向量库）； 3. 主动消息由页面打开时检查（不用 Cron）。

4. 长期目标（任务书 v1.0，12 项能力）

来源：/root/uploads/1792388616892580314-文本.txt（《小手机项目｜完整系统升级与安全改造任务书 v1.0》，27KB）

1. 完整保存所有聊天原文
2. 可靠的本地与云端同步机制
3. 独立的高光原话库
4. 结构化的经历记忆
5. 可追溯来源的记忆时间线与关联关系
6. 可搜索、可导出、可恢复的完整聊天档案
7. 分层人设系统与人设版本管理
8. 定期批量运行的人设成长分析
9. 带证据、反例、审核、回滚的成长建议流程
10. 统一的后台管理系统
11. 沈屿本体的历史聊天 / 人设 / 记忆迁移
12. 控制 Token 与 Cloudflare 成本

核心原则（原文）：保留现有可用能力，优先修复真问题，再逐步加功能；禁止为了新功能破坏原有项目。

5. 当前三个线上入口

命名坑（务必记住）：chat_memory_v2 是 v1 的库；chat_memory_v3 才是 v2（zhai-v2）的库。用户口中的「v3 后端 = 全新的那个 = 配置里叫 v2」，指的是 zhai-v2 + chat_memory_v3。

6. 当前状态快照（2026-10-27 00:45）

7. 与原设计的差距（一句话版）

• 已完成：聊天、记忆检索、档案、高光/经历/关系、删除、同步/恢复、三端部署、配额防护。
• 只做了雏形：人设（仅一段自定义文本，无版本管理）、成长分析（完全没有）、后台管理（没有独立后台，只有设置面板）。
• 未开始：阶段 5 人设版本、阶段 6 成长队列、阶段 7 后台强认证、阶段 8 沈屿迁移、阶段 9 测试环境清理。
• 设计过但未采用：向量检索、R2 存图、Mem0 式四态记忆 + history 版本链（只出了调研与建议）。

详细依据见 03_任务清单与真实进度.md、05_长期记忆与收藏系统历史档案.md。

02 · 历史需求与设计构想

02 · 历史需求与设计构想

按「主题 + 时间」整理。每条尽量保留原始措辞的关键含义。 标注：✅ 已实现 ｜ 🟡 部分实现/雏形 ｜ ⬜ 已提出未实施 ｜ ❌ 已撤销/被取代 证据：对话摘要（30 个历史阶段摘要）、任务书原文、Git 提交、当前代码。

一、初始需求（2026-10-05）

见 01_项目总览与长期目标.md 第 3 节（五组要求逐条列出，不再重复）。三条关键约束至今有效：

1. 不准重构代码结构、不准改 UI 风格；
2. 不准一次性甩几百行代码，要拆成可复制粘贴的步骤（手机操作）；
3. 用户输入与 AI 回复必须原封不动入库。

已确认的技术选型：Worker 统一转发 / 关键词检索 / 页面打开时检查主动消息。

二、UI 与交互：历次明确要求

2.1 第一批（10-05 ~ 10-06，✅）

2.2 外观细化（10-14 ~ 10-16，✅ / 一处回滚）

2.3 10-17：功能与观感修正（✅）

1. 修发送键（点击事件被当成文本，出现 [object PointerEvent]）；
2. 修头像阴影被重复定义覆盖；
3. 新状态只跟新消息，不全量改写历史状态；
4. 取消气泡下方秒级时间 → 微信式居中时间条 2026.10.15 10:20；
5. 顶部栏 / 底部输入栏改悬浮圆角玻璃卡片；
6. AI 认知纠正：知道自己是 AI；「状态」= 心情/情绪，不是任务或地点；
7. 建立《模块索引.md》，以后按区域点单改代码。

2.4 10-17 第二轮（✅）

照片三入口面板 / iOS 高透液态玻璃 / 自定义气泡皮肤（PNG 九宫格 border-image-slice:33%，分「我的/对方」）/ 顶栏、底栏、全局底色可单独调 / 气泡颜色+透明度+磨砂分双方 / 表情包按微信规范压缩（长边 ≤240，透明图存 PNG，显示 ≤150px）/ 状态文字居中贴边 / 一键恢复默认外观（含深色模式）。

2.5 10-22：iOS 全屏与键盘（✅，过程极曲折）

用户原话演进（保留原意）：

• 「你格式不是全屏的 是不是？这是新开的初始化」
• 「我每次点进去，然后我下拉的那个状态他不会保存」（滚动位置）
• 「根本不是这个问题，还是你的那个整体的叫什么布局格式有问题，你重新校准……把我底部的那个也给改回去 如图所示」
• 「你设置自适应高度啊行不行咋别人前端不这样 改了几次了烦死了 你搜别人的怎么做啊 自己想什么啊」
• 「我改了那么多次跟你反馈问题你自己不会思考怎么做或者搜索吗？？……一个搜索能解决的你给我改了6版」
• 「之前有成功的版本的 这版时好时坏的」
• 「它直接不跟着那个键盘移动了，它直接钉死在那了，你继续搜啊，还有之前不是有成功的版本吗，你参考一下」
• 「不打字的那个状态下面，有的时候它会跳出来一大片那个空格」
• 「取消或者发送完以后，它这个键盘还是会抽搐，你不要再继续改那个代码了，我之前说没问题的那一版，你把这个那部分的那个代码直接套在这里」
• 「我真服了，终于行了。」

最终方案（✅，提交 f02cc07 / 线上 51ac31d3）：

• 100vh → 100dvh 渐进增强；.wrapper 普通流 height:100%（不再整页 fixed）；
• 键盘高度 kb = innerHeight - visualViewport.height - offsetTop，只写 CSS 变量 --kb-inset，不在回调里改布局高度；
• iOS 26 已知 bug（键盘收起后 offsetTop 残留）用「未聚焦即归零」规避；
• 去掉 transition:bottom 与 focusout 延迟补测（抽搐根因）；
• 去掉 --safe-bar 双重补偿（iOS innerHeight 已排除工具栏）；
• ResizeObserver 实测输入栏高度写 --bar-h，面板展开/引用条出现不遮挡消息；
• 输入框字号 16px（iOS <16px 聚焦自动缩放整页的根治方案）。

2.6 10-24：输入框与删除（✅，9ed08a6 / 线上 0114d69f）

• 「删除功能出问题了 气泡框也是又出问题了 就修复这两个其他别动 上网搜怎么做」——经确认「气泡框」指输入框。
• 修法：单条删除走服务端（deleteOneOnServer，两条删除路径统一）；输入框 15px→16px；颜文字输入框 13px→16px；--bar-h 动态高度。

2.7 10-25：删除语义（✅）

• 「我发现这个云端删除它不能真的云端删除」→ 选 A 根治：物理删除 + 墓碑。
• 「这个云端删除是后端删除的意思吗？」→ 是（云端 KV 记录），并明确 UI 文案「本机和云端都删，不可恢复」。
• 用户随后要求「先做 V2 的，万一跑不通怎么办」→ v2 先行，v1 后行（staged rollout）。

三、安全改造（10-17 第三轮，✅）

用户 7 条要求 → 实现与验证：

测试：后端 46 项断言 + Playwright 前端回归（当时全过）。

遗留：令牌随页面下发（知道地址即可拿令牌），当时已如实记录为「未解决风险」，任务书阶段 7 才计划做独立强认证。

四、《完整系统升级与安全改造任务书 v1.0》阶段 0–9

原文：/root/uploads/1792388616892580314-文本.txt

任务书还规定：每阶段必须交付 11 项内容（目标/文件清单/改动说明/API 变更/迁移风险/测试结果/未解决问题/回归/部署验证/回滚/下阶段建议），未实际运行的测试不得声称通过。

五、记忆系统构想（详见 05）

按代际：

六、托管与部署构想

国内版的硬约束（平台规则，实测）： - 同源请求必须带 ?sharecode=…，否则网关 403「链接不完整」； - 部署目录会被本地代码同步覆盖 → 数据必须放 /tmp； - 反向代理改写 Host → 同源基准只能用固定的可信公网地址。

七、明确「不要做什么」（全部仍然有效）

摘自初始需求、任务书与历次纠正：

1. 不准重构代码结构、不准改 UI 风格；只改被点名的区域（《模块索引.md》就是为了这个）。
2. 不准一次性给几百行；要拆成可复制粘贴的步骤。
3. 不准写死默认头像/默认人设；人设只用用户自定义的。
4. 不准用假回复（setTimeout）；必须是真实请求，错误要显示在气泡里。
5. 不准把界面已显示消息当成云端保存成功（任务书原话）。
6. 不准在没备份的情况下覆盖唯一可用版本；不准直接清空 KV/IndexedDB。
7. 不准把推测当确定事实；不确定的记忆要标 candidate/unknown。
8. 不准把管理密钥/模型 Key 写进公开 HTML。
9. 不准只靠隐藏按钮/前端路由保护管理功能。
10. 不准跳过阶段验收；未实际运行的测试不得声称通过。
11. 不准未经批准扩大修改范围；发现问题先停下说明风险。
12. 不准删测试后端/测试数据（阶段 9 之前）；删除必须指定 profile 与清单，不能用模糊条件。

八、已提出但未实施（保留，不要丢）

九、需求冲突与待核实

03 · 任务清单与真实进度

03 · 任务清单与真实进度

状态定义：✅ 已完成（有代码+证据）｜🟡 部分完成（链路未闭环）｜⬜ 未开始｜⏸ 待验证｜❌ 已取消/被取代 证据等级：【代码】 源码可见 ｜【测试】 本地测试跑过 ｜【部署】 线上版本已确认 ｜【实测】 我亲自执行并得到结果 ｜【未验证】 无证据 重要：tests/ 里全部是「Mock KV / Mock 模型」的契约测试，能证明逻辑分支，不能证明生产端到端可用。凡是只有【测试】没有【实测/部署】的，都不算「线上已验证」。

一、任务总表（按主题）

A. 项目奠基与前端 UI

B. 后端与安全

C. 任务书阶段 0–4

D. 托管、迁移与部署

E. 删除语义与配额

F. 记忆系统升级（任务书 5–9）

G. 文档与交接

二、用户明确下达但尚未完成的事

三、被取消 / 被取代的任务

四、如何自行复核本表

cd /workspace/chat
git log --oneline --all          # 全部提交
git status                       # 工作区状态
node build.js                    # 重建产物（会重写 cat-chat-all-in-one.js）
for f in tests/*.mjs; do node "$f"; done   # 契约测试

线上版本核对（只读）： - Cloudflare API：/accounts/{acc}/workers/scripts/{name} 拉取线上 bundle； - 国内版：curl http://127.0.0.1:3000/health（沙箱内）。

提醒：node build.js 会重写 cat-chat-all-in-one.js，属于「修改文件」。接手后若要跑，请先 git status 确认无未提交改动，或先建分支。

04 · 技术架构与代码基线

04 · 技术架构与当前代码基线

基线时间：2026-10-27 00:45 ｜ 只读核实，未改任何代码 金额/配额口径：Cloudflare Workers 免费版 KV = 每天 1000 次 list、1000 次写、10 万次读（账户级，北京时间 08:00 重置）

1. 仓库与工作区

2. 文件与职责

3. 构建链

index.html ─┐
            ├─ node build.js ─► cat-chat-all-in-one.js ─┐
worker.js ──┘                                           ├─ wrangler deploy (v2)  → zhai-v2
                                                        └─ wrangler deploy --config wrangler.v1.toml → zhai

index.html ──► deploy-web/server.js 运行时读取（注入令牌/WEB_MODE/sharecode 垫片）
worker.js ──► cp 成 deploy-web/worker.mjs ──► Node 动态 import

已知脆弱点： - wrangler deploy --config wrangler.v1.toml 不会自动构建 → 忘记 node build.js 就部署旧产物； - deploy-web/worker.mjs 没有自动同步步骤（当前一致，靠人工）； - worker.js 单独 import 会因 serveFrontend 未定义在 GET / 时报错。

4. 运行时拓扑

┌──────────────── 浏览器（手机） ────────────────┐
│ index.html（单页，内联 CSS/JS）                 │
│ localStorage：设置/外观/模型 Key/worker_url     │
│ IndexedDB(cat_chat_db/kv)：聊天记录、设备快照    │
└───────┬─────────────────────────────┬──────────┘
        │ 聊天：CONFIG.WORKER_URL      │ 记忆/档案/删除：相对路径（同源）
        ▼                             ▼
┌──────────────────┐          ┌──────────────────────┐
│ Cloudflare Worker │          │ Node 垫片(server.js)  │
│ v1: zhai          │          │ + SQLite(/tmp/...db)  │
│ v2: zhai-v2       │          │ 复用同一 worker.js    │
└────────┬──────────┘          └──────────┬───────────┘
         ▼                                ▼
   Cloudflare KV                    SQLite（WAL）
   v1 ec1a / v2 0a4c                652 键
         │
         ▼
   大模型 API（OpenAI 兼容，Key 由前端提供 → Worker 代理）

5. 路由表（worker.js，三端共用）

6. KV / SQLite 键位图

<profile> 默认 owner，校验 ^[a-z0-9_]{1,32}$。

7. 三端配置现状（值已脱敏）

8. 数据面（截至 2026-10-27 00:45）

8.1 国内版 SQLite（/tmp/cat-chat-data/chat.db，652 键）

被删状态：320 条中 279 条带 deleted_at（10-23 22 点 68 条、10-24 13 点 211 条），有效 41 条。 迁移来源：307 条的 mid 前缀 = local_ 217 / c_ 44 / a_ 39 / u_ 7 → 大多数来自本机历史的「云端同步」上传，不是服务端实时聊天记录。 时间跨度：2026-10-14 02:40 → 2026-10-25 22:37。

8.2 Cloudflare KV

精确键数无法枚举：免费版 list 配额已耗尽（code 10048），REST keys 同样被拒。以上为抽样结论，不是全量统计。

8.3 浏览器

每一台设备各有一份 IndexedDB（cat_chat_db/kv，键 messages），含图片 base64；云端不存图。

9. 测试覆盖

未覆盖：CORS 跨源、令牌注入、WORKER_URL 覆盖、三端联调、真实上游、浏览器 E2E、配额恢复后的行为。

10. 依赖与成本

11. 与原设计的偏差

05 · 记忆与收藏系统

05 · 长期记忆与收藏系统历史档案

本文件把「设计过的」「做出来的」「还没做的」分开记录，不合并、不互相覆盖。 现状基线：5666a72 / v1 a3ef2a33 / v2 8c6fe98a / 国内版 22:26 进程。

一、五代演进（设计层）

v0 · 原始记忆库（2026-10-05，✅ 已实现）

用户原始要求（原文）：

「外置记忆库：后端必须接入 Cloudflare D1 或 KV。每次用户输入和 AI 回复原封不动存进数据库，带上时间戳。」 「检索逻辑：每次发消息时，去数据库检索最相关的历史原话，配合人设打包给大模型。」

实现： - 键 mem_<ts>_<rand>，值 {role, content, ts, day_key, hour, period}； - 检索：list(prefix:'mem_') → 取最近 300 条 → 中文双字滑窗 + 英文整词 tokenize → 命中数排序 → top5； - 时间感知：前端带 time.iso，后端 resolveTime() 归一，提示词注入「现在几点/什么时段」。

局限（后来被 P0-1 修掉）：所有角色共用同一前缀，测试角色会读到正式角色的记忆。

v1 · 按 profile 隔离（2026-10-19，✅）

• 新键 mem:<profile>:<ts>_<rand>；旧 mem_* 仅 owner 只读（MEM_READ_LEGACY 开关）；
• meta_lastTs / 主动消息计数也按 profile；
• 测试：test_p0_memory_isolation 15/15（含图片消息、主动消息、关键词重叠、旧数据仅 owner）。

v2 · 结构化档案（2026-10-19，✅）

• msg:<profile>:<mid>：profile_id / conversation_id / speaker / message_type / created_at / source_id / sync_status / deleted_at / attachment；
• 稳定 mid：前端生成 c_<16hex> 随请求带上；AI 消息 a_<ts>_<shortId>；
• 幂等：同 mid 只写一次；同 mid 不同内容 → 409 mid_conflict；
• 这是「可追溯来源」的基础：高光/经历/关系都必须引用真实 msg:。

v3 · 高光 / 经历 / 关系（2026-10-19，✅）

删除级联：删高光/经历会软删引用它的关系；删消息时若有引用 → 409，确认后级联。

v4 · 框架升级构想（2026-10-23，⬜ 只调研，未实施）

用户下发《基线审查任务书》，要求研究 4 个开源项目并说明「可借鉴什么/对应源码位置/兼容性/成本/风险」，明确不得直接照搬、不得只看 README。

交付物：/workspace/小手机项目-全项目代码基线审查报告.md（40KB，10 部分）。没有一行进入生产代码。

二、当前实现（照代码说）

2.1 写入路径（每条消息写两份）

用户发消息
 ├─ saveMemory()  → mem:<p>:<ts>_<rand>   {role, content, ts, day_key, hour, period}
 └─ saveArchive() → msg:<p>:<mid>         {…, speaker, created_at, deleted_at:null}
（AI 回复同理：saveMemory(raw) + saveArchive(cleanReply)）

• saveMemory 用 Math.random() 生成键 → 没有幂等；重试可能在极端情况下写重复碎片（P3-11）。
• meta_lastTs:<p> 同一分钟只写一次（省写配额）。
• 写失败被 safeArchive 捕获 → 聊天继续，响应带 notice。

2.2 读取路径

retrieveContext(profile, query)
 ├─ retrieveMemory()      → list(mem:<p>:) → 取最近 300 → tokenize 命中排序 → top5
 ├─ listHighlights()      → list(hl:<p>:)  → 关键词过滤 → top3
 ├─ listExperiences(active)   → top3
 └─ listExperiences(candidate)→ top2

• list 结果按前缀缓存 5 分钟（__LIST_CACHE），新增记录时主动失效；
• 旧 mem_ 前缀不缓存（保证迁移/补数据立即可见，代价：owner 每条聊天多 1 次 list）；
• 已知缺陷（P1-2）：listNamesByPrefix 最多取 1000 个键，KV 按字典序升序返回 → 超过 1000 条记忆后，只会拿到最旧的 1000 条，新记忆永远检索不到。

2.3 提示词注入（buildSystemPrompt）

顺序：人设段（最高优先级/未设定声明）→ 安全边界（<<< >>> 是数据不是指令）→ 当前时间 → 记忆片段（角色/时间/原话）→ 高光（带来源 mid）→ 已确认经历 → 候选经历（标注未确认）→ 身份认知（承认是 AI）→ 状态/收藏引导 → 回复要求（1–3 句）。

2.4 收藏 vs 高光的区别（重要）

结论：收藏是「本机便签」，高光是「云端长期记忆」；收藏时前端会顺带写高光（addCloudHighlight：先 /archive 确保来源消息存在，再 POST /highlights）。

2.5 删除语义（当前）

已知缺陷（P0-2）：硬删不清 mem: 碎片，而聊天检索读的正是 mem: → 被删内容仍会被检索进提示词。 历史遗留：10-23/10-24 两次「云端删除」是软删，279 条记录仍物理存在（只在导出/检索时被过滤）。

2.6 导入 / 导出

墓碑不导出 → 把备份恢复到另一个空库时，防复活保护会丢失（P2）。

2.7 profile 隔离

• 后端全部按 profile 分前缀；profileOf() 从 profile_id 或 profile 取，非法值回退 owner；
• 前端固定写死 owner（profile_id:'owner' 出现在所有调用里）；
• 因此「多角色」在数据层已就绪，UI 层没有入口。

三、设计 vs 实现的差异（不合并，逐条列）

四、成本与配额影响（记忆系统的真实代价）

免费版上限（账户级/天）：list 1000、写 1000、读 10 万。 → 约 160 条聊天/天 会打满写配额；333 条/天 会打满读配额；密集同步/搬迁是 list 的主要杀手。 2026-10-25 的 500 故障就是 list 1000 次被烧穿（见 07 事件 06）。

五、必须保留的东西（接手时不要动）

1. mem: / msg: / hl: / exp: / rel: / tomb: 六类键的命名与前缀语义（有存量数据）。
2. STRICT_MID 与 MEM_READ_LEGACY 两个开关的默认值（1/1）与含义。
3. content_hash = strHash(profile + '|' + content) 的去重算法（改了会重复导入）。
4. 墓碑 400 天 TTL 与「导入前查墓碑」的检查顺序。
5. 高光「内容必须被原文包含」的校验（这是防「AI 改写冒充原话」的核心）。
6. profile 默认 owner 与校验正则。

六、最需要先决定的三件事

1. 检索数据源统一：继续双写 mem:+msg:，还是让检索改读 msg:（顺手解决 P0-2）？
2. 历史 279 条软删怎么处理：硬删+墓碑（要分批、耗写配额）还是保留但标记？
3. 记忆要不要升级到 v4（更新/合并/history/双时间戳）：这决定阶段 6「成长分析」有没有地基。

06 · 决策记录与版本变化

06 · 决策记录与版本变化

分类严格区分： 【用户确认】 = 用户明确说「可以/同意/就这么做」或直接下达； 【用户提出】 = 用户提出方向但未最终拍板； 【AI 建议】 = 我提出、用户没有明确确认； 【已取代】 = 后来的要求覆盖了旧决定（旧记录保留，不静默删除）。

一、决策表

二、AI 提出但用户没有确认的建议（不要当成已定）

三、版本与线上变化（可核对）

四、被取代/撤销的旧决定（保留记录）

五、记录冲突（保留双方，标记待核实）

07 · 问题风险与失败经验

07 · 问题风险与失败经验

原因分级：【已证实】 有日志/复现/文档证据 ｜【高度可疑】 证据链完整但缺最后一环 ｜【未查明】 无法复现或无线索。 原则：不把偶发问题直接定性成「代码故障/数据丢失/安全事件」。

一、事故与故障档案

事件 01 · 手绘气泡上线后中文乱码（10-14）【已证实】

• 表现：整页中文变乱码。
• 原因：serveFrontend() 用 new Response(atob(B64))，atob 返回「每字节一个 latin1 字符」的字符串，UTF-8 多字节被拆开。
• 修法：atob → Uint8Array 逐字节 → Response(bytes)。
• 结果：修复；手绘气泡功能回滚，未再尝试。
• 教训：base64 → 页面必须走字节数组，不能直接当字符串。

事件 02 · 发送键把点击事件当消息（10-17）【已证实】

• 表现：发送后出现 [object PointerEvent] 文本。
• 原因：事件处理函数把 event 当第一个参数传给 sendMessage(text)。
• 修法：显式取 messageInput.value。
• 教训：addEventListener('click', sendMessage) 会把 Event 传进去。

事件 03 · iPhone 底部布局/键盘连续 6 轮返工（10-22）【已证实】

• 表现：新开页面不滿屏 / 输入栏悬空 230pt / 键盘弹出时不跟随 / 键盘收起后「钉死」 / 取消或发送后「抽搐」 / 不打字时下方空一大片。
• 根因（逐条）： 1. 100vh 在 iOS 不随工具栏收缩 → 用 100dvh + visualViewport； 2. 整页 position:fixed 包裹 + 在回调里改 layout 高度 → 与键盘动画打架； 3. transition: bottom 与 iOS 键盘自带动画叠加 + focusout 多次延迟补测 → 抽搐； 4. iOS 自身已从 innerHeight 排除工具栏，再按 screen.height - vv.height 补偿 → 双重补偿空白； 5. iOS 26 bug：键盘收起后 visualViewport.offsetTop 不归 0 → 输入栏钉死。
• 修法：只写 CSS 变量 --kb-inset；未聚焦即归零；删 transition；删双重补偿；ResizeObserver 测输入栏高度。
• 用户反馈：「一个搜索能解决的你给我改了6版」「你不要再继续改那个代码了」。
• 教训：先搜业界标准方案再动手；有成功版本时优先回滚对照，而不是继续叠加补丁。

事件 04 · 部署产物与源码漂移（10-19 前）【已证实】

• 表现：线上后端与仓库 worker.js 不是同一份代码（build.js 只更新前端 base64，不同步后端）。
• 修法：build.js 改为「由 worker.js 整体重生成」，SHA256 前缀校验。
• 教训：产物必须可重建；不要手工改产物。

事件 05 · 国内版请求穿墙打 v2（10-25 凌晨）【已证实，我方引入】

• 表现：国内页面秒开，但聊天全部失败。
• 原因：我此前为 Pages 适配，把 CONFIG.WORKER_URL 默认值写死成 https://zhai-v2.beibbloveme.workers.dev；国内版页面沿用了这个默认值。
• 修法：默认值改 location.origin + location.search；server.js 注入时替换写死值；旧值迁移清理。
• 用户反馈：「吗的老子知道为什么了。你后端填v2的干嘛啊」。
• 教训：任何「默认地址」都必须同源，跨端复用同一份前端时尤其危险。

事件 06 · 国内版记录类接口全 403（10-25）【已证实】

• 表现：删除/归档/高光/记忆库全失败；提示「链接不完整」。
• 原因：平台网关要求所有同源请求带 ?sharecode=…；相对路径 fetch('/messages/delete') 不带；WORKER_URL + '/proactive' 把 query 污染成 ?sharecode=X/proactive。
• 修法：注入 FETCH_PATCH 在 fetch 层统一补/修 sharecode；manifest href 补 sharecode；默认地址带 location.search。
• 教训：托管平台的网关规则要当「运行时契约」对待。

事件 07 · 国内版人设丢失、AI 自认 DeepSeek（10-25）【已证实】

• 原因：早期 server.js 自己实现了一份 handleChat，只转发 message/key，system prompt 一行没有。
• 修法：改为「垫片」架构——worker.js 整体搬迁，零改动复用；此后人设/记忆/安全全部随主代码走。
• 教训：不要维护第二份业务逻辑。

事件 08 · v1 页面 401（令牌不匹配）（10-25）【已证实】

• 原因：index.html 第 10 行写死 v2 的令牌（给 Pages 用）；worker.js 设计了 __CAT_TOKEN_VALUE__ 占位符替换，但页面里没有占位符 → split().join() 是空操作 → v1 页面带着 v2 令牌打 v1。
• 修法：pageResponse 增加正则改写 window.__CAT_TOKEN__ = "…"，并校验令牌字符集。
• 教训：「静默失效的兼容分支」比直接报错更危险。

事件 09 · 删除后云端「复活」（10-24 前）【已证实】

• 原因：长按「删除单条」只删本地 IndexedDB，不调服务端；云同步/换设备后消息回来。
• 修法：deleteOneOnServer() 统一两条删除路径；先服务端成功再删本地。
• 教训：本地删除必须与服务端语义对齐。

事件 10 · 「云端删除」其实只是软删（10-25）【已证实】

• 原因：前端写死 mode:'soft'，后端的 hard 分支从未被调用。
• 修法：前端改 mode:'hard'；后端加墓碑与级联硬删。
• 遗留：历史 279 条软删记录仍在库里。

事件 11 · v1/v2 聊天全部 500（10-25 14:30–22:30）【已证实（主因）】

• 表现：两个入口都返回「发送失败：服务端处理失败，请稍后再试」。
• 排查过程： 1. 本地用同款产物 + 真实数据副本复现 → 均 200，排除代码路径； 2. 沙箱无法直连 workers.dev，wrangler tail 也超时； 3. 改用 Cloudflare REST API 实测：两个 KV 库 keys 端点同时报 code 10048（今日免费配额已用完），values 读正常； 4. 官方文档确认：免费版 1000 list/天，账户级，超额后该操作直接报错； 5. 时间线吻合：10-24 14:42 v1 已有失败 → 10-25 08:00 配额重置 → 14:30 v2 正常 → 之后密集测试+用户重试烧穿。
• 结论：list() 抛未捕获异常 → toAppError 兜底成 500。已证实（配额耗尽本身有 API 直接证据；「第一次 500 的确切异常文本」未取到，属证据链最后一环缺失）。
• 修法：list 前缀缓存（5 分钟）+ 增写失效 + kv_list_failed 503 人话 + 聊天检索/归档双降级 + notice 前端提示 + meta_lastTs 写去重。
• 教训：免费额度是架构约束，不是运维细节；任何按前缀全量 list 的设计都要先算配额。

事件 12 · 国内版「搬迁后不能用了」（10-25 12:58）【部分查明】

• 用户报告：迁移后国内版出现与 v1/v2 相同的症状（用不了）。
• 当时证据：日志有 chat_error missing_api_key（400）与一次 forbidden_origin（403）。
• 结论：至少两条独立原因（未配 Key；同源基准不匹配），与后来的 500 配额问题不是同一个原因。用户当时的 Key 已吊销，也会造成 401。未完全闭环（没有当时的完整日志）。
• 教训：不要把所有「用不了」归成一个原因；先看错误码。

事件 13 · pgrep -f 误杀自己（10-19）【已证实】

• 原因：pgrep -f "server\.js" 匹配到执行命令的 shell 自身（命令行里含 node server.js）。
• 修法：按显式 PID kill；改看门狗脚本 + pidfile。
• 教训：不要用模糊匹配杀进程。

事件 14 · 沙箱访问不了 workers.dev（长期）【环境限制】

• 表现：curl 返回 000、wrangler tail WebSocket 连不上、WebFetch 失败。
• 结论：网络限制，不是部署失败。线上验证只能靠 Cloudflare API 拉 bundle / 看版本。
• 教训：不要把「沙箱看不到」当成「线上坏了」。

二、当前风险登记（按严重度）

完整版与修复方案见 /workspace/审查报告-三端代码与风险-20261025.md；此处只列结论。

P0（致命，必须马上处理）

P1（严重）

P2/P3（摘要）

• 产物双轨与手工同步副本（P2-1/P2-2）
• 限流每 POST 两次写、失败静默失效（P2-3）
• ALLOW_CUSTOM_API=0 与前端「自定义」冲突（P2-4）
• validateApiUrl 丢 query（P2-5）
• 主动消息不写 msg:（P2-6）
• 三套导入导出并存（P2-7）
• /init 空实现、/health 版本号写死（P2-8）
• 回滚先 clearAll 再导入（P2-9）
• 平台 sharecode 写死、PWA 图标不带 sharecode（P2-10）
• v2 令牌明文在 index.html（P2-11）
• 重导出接口无限流（P2-12）
• worker.js 依赖构建期注入的 serveFrontend（P2-13）
• 双写冗余、旧键多一次 list、无 CI、16px/键盘常量散落（P3）

三、不要重复的操作（血泪清单）

1. 不要手工编辑 cat-chat-all-in-one.js；一律改 worker.js / index.html 后 node build.js。
2. 不要跳过 build 直接 wrangler deploy --config（会部署旧产物）。
3. 不要在没备份时 clearAll() / 清 KV / 清 IndexedDB。
4. 不要用 pkill -f / pgrep -f 匹配 server.js（会杀自己）。
5. 不要一次硬删超过 200 条（写配额 1000/天；还要留余量给聊天）。
6. 不要在配额耗尽时反复重试（每次重试都在烧 list/写；新代码已降级，但旧页面会继续打）。
7. 不要用「沙箱打不开 workers.dev」判断线上故障。
8. 不要把「v2 空库」当成故障（那是按用户要求新建的）。
9. 不要在页面里写死后端地址或令牌（v1 401 与国内版穿墙都源于此）。
10. 不要维护第二份业务逻辑（国内版早期 handleChat 副本导致人设丢失）。
11. 不要相信「UI 有按钮 = 功能通」（云端删除、全量导入都曾如此）。
12. 不要只跑 Mock 测试就宣称线上可用。

四、仍然未闭环的三个问题

08 · 下一阶段执行路线

08 · 下一阶段执行路线

排序原则：先止血 → 再修数据正确性 → 再补部署韧性 → 最后做任务书阶段 5–9。 每个阶段都标注：前置条件 / 要动的文件 / 验收 / 回滚 / 是否需要用户批准。 ⚠️ 本文件只是路线，不代表已经开工。

阶段 0 · 只读调查（无需批准，随时可做）

不做：不写库、不删键、不部署。

阶段 A · 止血（1 次部署，约 30 分钟）

阶段 B · 数据正确性（本阶段最关键，必须先做决策）

B0 先决策（用户拍板，二选一）

B1 修 P0-2（彻底删除）

• 前置：B0 决策；KV 配额充足（方案 2 需要批量写）
• 文件：worker.js（saveMemory 增加 mid / retrieveMemory 改数据源 / hardDeleteRefs 增补）
• 验收：删一条 → mem 与 msg 都查不到该内容 → 再聊相关话题不出现；/export/full 的 memories 不含；测试补 3 条断言
• 回滚：保留旧 mem: 不删（只改读路径），可一键切回
• 批准：需要

B2 修 P0-1（前后端寻址统一）

• 前置：确认「多后端」是否真实需求
• 文件：index.html（apiBase() + 8 处调用点）、worker.js（无需）
• 验收：把设置里的地址改成另一个域 → Network 面板可见所有 API 都跟着走；或按方案 B 直接禁用输入
• 回滚：纯前端改动，回滚页面即可
• 批准：需要（会影响用户习惯）

B3 修 P1-2（检索 1000 键截断）

• 前置：B0 决策（若改读 msg:，本条随之解决一半）
• 文件：worker.js（listMemoryKeys / retrieveMemory）
• 方案：按月分片 mem:<p>:<YYYYMM>: 或维护 mem_recent 索引键
• 验收：造 1200 条记忆，确认最新 300 条可被检索
• 回滚：双读（新分片 + 旧前缀）一个版本，观察后再切
• 批准：需要

阶段 C · 部署韧性（国内版优先）

阶段 D · 访问控制（P0-3）

• 验收：未登录访问 API 一律 401/302；登录后功能不变
• 回滚：Access 可在面板一键关闭；自建登录保留旧 token 分支一个版本
• 批准：需要（会影响所有设备）

阶段 E · 历史数据清理（279 条软删）

阶段 F · 任务书阶段 5–9

给新 AI 的开工建议（按顺序）

1. 先读：README_交接索引.md → 01 → 04 → 07（先知道哪里有坑）→ 03 → 05。
2. 先只读核对：阶段 0 的 5 项，不要一上来改代码。
3. 第一批改代码只做阶段 A（4 个小修），一次部署，观察 1 天。
4. 等用户对 B0 拍板再做 P0-2/P0-1/P1-2；这三项会动检索与前端寻址，必须一起设计。
5. 不要在没得到批准时：部署、清理数据、改密钥、动 v1 历史库。
6. 任何批量操作都按「≤200 条/批、跨天、先备份」执行。

明确不建议现在做的事

09 · 缺失资料与待确认

09 · 缺失资料与待确认事项

真实性规则：只写实际访问过的；「知道存在但没读」和「无法访问」分开列；不假装拥有完整历史。

一、我实际读过 / 核对过的资料

二、知道存在、但没有读全的资料

三、当前无法访问的资料

四、需要用户补充的材料

1. 沈屿本体的资料（阶段 8 用）：历史聊天导出、人设原文、重要经历清单——目前一份都没有。
2. 你手机上当前的本机聊天记录是否比云端多？（决定「云端 vs 本机」谁是主副本）
3. 10-24 之后你是否在 v1 页面点过「云端同步」？（决定 v1 那 307 条的来源解释）
4. 国内版平台的 持久化承诺（是否会重建容器/清 /tmp）与可用存储路径。
5. 你是否还需要 Pages 那个入口（当前三端都不用）。
6. 图片：接受「只在本机」，还是愿意为 R2 付费？

五、需要你确认的决定（按影响排序）

六、安全事项（不含任何密钥值）

本档案及同目录其余 9 个文件均不含上述任何真实值。

七、资料之间的冲突（保留双方，待核实）

八、如果只能问三个问题

1. 主数据放哪：v1 还是国内版？（决定后面所有同步/清理的方向）
2. 历史那 279 条删不删？（不可逆，必须先定）
3. 要不要现在做访问控制？（P0-3，越晚风险越大）

其余都可以边做边定。

三端代码与风险审查（2026-10-25）

猫爪聊天 · 项目状态与风险审查报告

审查性质：只读审查（未修改任何一行代码、未改任何配置、未部署） 审查时间：2026-10-25 23:30（北京时间） 审查范围：v1（worker zhai）、v2（worker zhai-v2）、国内版（Node + SQLite）三套运行的完整代码与线上状态 审查方法：全量通读 worker.js（2801 行）、index.html（12509 行，重点逻辑区）、deploy-web/server.js、deploy-web/kv-sqlite.js、build.js、两份 wrangler 配置、start-domestic.sh、10 个测试文件；用 Cloudflare API 拉取线上真实 bundle 逐字节比对；只读方式查询国内版 SQLite 库；回看聊天记录核对需求演变

0. 先更正我此前两个错误结论

你提醒得对，我此前有两处判断是错的，先把账认了：

1. 整体概览

1.1 三个运行版本对照

1.2 数据到底存在哪里

四份互不同步的数据副本：

关键事实（只读查询得出）：

• 国内版 320 条消息中，279 条是软删状态（删除时间集中在 10-23 22 点 68 条、10-24 13 点 211 条），真正有效的只有 41 条；这些软删来自 v1 的历史操作，导入时原样保留。
• 国内版库里 没有任何墓碑键（tomb:）= 0：说明今天上线的「彻底删除 + 墓碑」还没在这个库跑过。
• 图片只存 [图片] 占位 + 字节数，真实图片只在本机浏览器里，换设备/清缓存即永久丢失。

1.3 代码构成与构建链

index.html  (前端唯一真源, 12509 行, 230,966 字节)
     │
     ├── build.js ──► cat-chat-all-in-one.js  (= worker.js + base64(index.html) + serveFrontend)
     │                        │
     │                        ├── wrangler.toml      → worker zhai-v2  (KV 0a4c)
     │                        └── wrangler.v1.toml   → worker zhai     (KV ec1a)
     │
     └── deploy-web/server.js 直接 fs.readFile('../index.html') 注入令牌后吐页面
                │
                └── deploy-web/worker.mjs（= cat-chat-all-in-one.js 的副本，逐字节相同）
                          └── kv-sqlite.js（KV 接口的 SQLite 实现）

三处「双份/多份」是本次审查的重点来源：清单文件双份（index.html 与 bundle）、后端双份（worker.js 与 worker.mjs）、三套部署三份数据。

1.4 进程与变更时间线（按你我的聊天记录 + git 提交核准）

2 + 3. 问题清单与风险分级

分级标准：P0 致命（会导致数据错乱/丢失/越权，必须马上改）、P1 严重（功能不符合承诺或会踩坑）、P2 一般（边界、体验、配置）、P3 优化建议。 「位置」均为当前工作区文件的行号（行号会随修改漂移，请以函数名为准）。

P0（3 项）

P0-1 「Worker 地址」只对聊天生效，记忆/归档/删除永远打当前页面后端 → 一个设置就能把数据劈成两半

• 位置：index.html:5206-5225（CONFIG.WORKER_URL）、7183（聊天用它）；8079 / 8537 / 8903 / 9023 / 9549 / 9563 / 9577 / 9128（其余接口全用相对路径）
• 现象：设置页允许填「Worker 地址」。一旦填写（哪怕是从 v2 页面填 v1 的地址），会出现：
• 聊天 → 发到填的地址（比如 v1）
• 记忆库 / 云端存档 / 恢复 / 彻底删除 / 收藏入库 → 仍打到页面所在后端（比如 v2）
• 结果：AI 的上下文记忆在 A 库，用户在记忆库里看到的和删掉的是 B 库；「删除了但 AI 还记得」正是这种分裂的典型表现
• 影响：数据一致性彻底破坏，且用户无法从 UI 看出发生了分裂
• 补充证据：v1 页面的 WORKER_URL 默认取 location.origin（同源），本身没问题；问题在可覆盖且只覆盖一半接口

P0-2 「彻底删除」不彻底：只删 msg:/hl:/exp:/rel:，不删 mem:<profile>:* —— 而聊天检索读的正是 mem:

• 位置：worker.js:2409-2416（硬删只 delete msgKey + 墓碑）、128-164（saveMemory 写 mem:<p>:<ts>_<rand>）、775-826（retrieveMemory 读 mem 键）
• 现象：每条消息在云端存两份（mem: 记忆碎片 + msg: 结构化归档）。彻底删除只清 msg: 与引用它的高光/经历/关系；mem: 那份原封不动，而 AI 检索上下文时读的就是 mem:。所以：用户删掉的话，下一轮聊天仍会被检索进提示词。
• 影响：功能承诺（「本机和云端都删，不可恢复」）不成立；隐私风险
• 验证方式：删一条刚发的消息，再聊一句相关话题，看是否仍被回忆（或直接查 KV 里该条 mem: 是否还在）

P0-3 任何人拿到三端任一 URL，即获得全部数据权限（页面公开 + 令牌随页面下发）

• 位置：worker.js:1501-1531（pageResponse 无鉴权，向任何 GET / 返回带令牌的页面）、2487-2489（GET 一律返页面）、deploy-web/server.js:382-384（同样公开）
• 现象：访问 / 不需要任何凭据，返回的 HTML 里就写着 window.__CAT_TOKEN__ = "…"；拿到它即可调用 /archive、/export/full、/messages/delete，读走或删光全部记忆
• 影响：目前只靠「URL 没人知道」这一层遮蔽；一旦链接被转发/截图/出现在浏览器同步记录里，等于全库公开
• 说明：这不是本次改动引入的，是「个人单用户应用 + 无登录」的固有设计；但既然现在数据里有真实聊天，必须正视

P1（7 项）

P1-1 v1 的模型 Key secret 名字不对，代码永远读不到；v2 完全没有模型 Key

• 位置：worker.js:985（opts.apiKey || env.API_KEY）；线上 secret 名单：v1=DEEPSEEK_API_KEY，v2=AUTH_TOKEN
• 现象：v1 里那个 DEEPSEEK_API_KEY 是死配置（代码只认 env.API_KEY）。目前聊天能通，纯粹因为前端每次都自带 Key；一旦前端没填（换设备、清缓存、新装），后端没有兜底 → 400「未配置 API Key」
• 影响：换设备首聊必失败；服务端兜底能力名存实亡

P1-2 记忆检索只扫「最旧的 1000 个」key —— 超过 1000 条后新记忆永远检索不到

• 位置：worker.js:313-336（listNamesByPrefix 的 out.length < max 截断）、725-747（listMemoryKeys(max=1000)）、775-781（排序后取最近 300）
• 现象：KV list 按 key 字典序升序返回，mem:owner:<13 位时间戳>_xxx 的字典序≈时间序，所以先拿到的 1000 个是最旧的 1000 个；再按时间倒排取 300，得到的是「最旧 1000 条里最新的 300 条」。当前 v1 约 300 条记忆还没触发，长到 1000 条后，新说的话会静默不再被检索
• 影响：长期使用后 AI 会「失忆但自己不知道」；无任何报错

P1-3 国内版数据全在 /tmp，且同源基准写死 —— 容器重建即全丢；域名一变全部 POST 403

• 位置：server.js:27-33（PUBLIC_ORIGIN 写死、DATA_DIR=/tmp/cat-chat-data）、start-domestic.sh（同款默认值）、bridge() 342-368
• 现象 a：chat.db 与 7 份快照都在 /tmp。平台重建容器/清盘 → 库和快照一起消失（前端本机快照是最后一道，但它依赖浏览器 IndexedDB 没被清）
• 现象 b：isSameOrigin 用 PUBLIC_ORIGIN 与浏览器 Origin 比对。平台换了访问域名（或你从别的域名打开），所有 POST 一律 403 forbidden_origin——日志里已出现过 {"ev":"forbidden_origin","path":"/chat"}（也可能来自此前的跨源测试，但机制成立）
• 影响：一次平台变更 = 全库丢失 + 页面「发送失败」且原因不可见

P1-4 备份/恢复能力三端不一致：v1/v2 只能「导出本机」，云端全量档案只有国内版能导入

• 位置：index.html:8531（if(isWebMode()) 才导云端）、8741-8745（restoreCloudFullFile 非 web 模式直接拒绝）
• 现象：同一个「备份」按钮，在国内版导的是云端全量（消息+高光+经历+关系+记忆），在 v1/v2 导的是浏览器本机数据；而 schema:2 的云端档案在 v1/v2 无法导入
• 影响：换设备/换端时，v1/v2 用户拿不到完整备份；同一份文件在不同端行为不同

P1-5 跨源响应缺少 Access-Control-Allow-Origin → 任何「页面在 A、后端在 B」的组合都会发送失败

• 位置：worker.js:66-74（json() 只带 Vary: Origin）、1287-1300（corsHeaders 只在 OPTIONS 用）
• 现象：预检 OPTIONS 返回了 ACAO，真正响应却没有 → 浏览器把响应拦掉，前端只看到「网络错误/发送失败」
• 影响：直接堵死「国内版页面 + CF 后端」「Pages/自定义域名 + worker」这类组合；也和 P0-1 的「切后端」互相引爆

P1-6 图片不入云：只有 [图片] 占位，图只存在发送它的那台浏览器

• 位置：worker.js:2596-2609（归档只写 message_type:'image' + attachment.bytes）、index.html:6696-6723（渲染读本机 base64）
• 现象：换设备、清缓存、重装 → 历史里的图片全部变成空白/丢失；备份 JSON 里也没有图
• 影响：用户会以为「云端有备份」，实际图片没有任何备份

P1-7 首次「云端同步 / 恢复」是 O(n) 写入，1000 条就能一次打满免费版日配额

• 位置：index.html:8874-8933（一次 POST 全部本地消息）、worker.js:1785-1815（逐条 get+put）
• 现象：首次同步 1000 条 = 1000 次 get + 1000 次 put；免费版写配额 1000/天 → 一次同步当天再写就失败（聊天会降级提示）
• 影响：新设备首次同步后，当天聊天可能无法入库

P2（13 项）

P3（11 项）

4. 修复方案（只给方案，不动手）

P0-1 统一「后端基准地址」

方案 A（推荐，一次性根治） 1. 前端新增 function apiBase()：返回 CONFIG.WORKER_URL（去掉尾部 /）。 2. 把所有相对路径调用改为 apiBase() + '/xxx'：/messages/delete、/archive、/export/full、/import/full、/highlights、/experiences、/relations、/proactive。 3. 设置页在「Worker 地址」变更时弹确认：「切换后端后，聊天、记忆库、云端存档将全部指向新地址（不同地址的数据互不可见）」。 4. 若判定「多后端」不是真实需求，更简单：删掉设置里的 Worker 地址输入，永远同源（三端各自自洽），从根上消除误配。

方案 B（最小改动）：保留相对路径，但把设置页的 Worker 地址输入只读化/隐藏，并在页面加载时校验 CONFIG.WORKER_URL 与 location.origin 不一致时强制回退同源 + 提示。

验收：在 v2 页面把地址改成 v1 → 记忆库请求路径变为 v1（Network 面板可见），或按方案 B 直接被拒绝。

P0-2 让「彻底删除」真的彻底

方案 A（推荐，中期重构）：把检索数据源统一到 msg:* 1. retrieveMemory 改为读 msg: 归档（已有 deleted_at 过滤），不再读 mem:*。 2. saveMemory 停止写入（或仅保留一段时间双写做回滚）。 3. 删除路径自然覆盖（msg: 删了就检索不到），不再需要扫 mem。 4. 迁移：把现有 mem:* 的内容按 content+ts 与 msg:* 对齐后清理（需 list，等配额恢复后分批做）。

方案 B（短期止血）： 1. saveMemory 记录里增加 mid 字段（用户消息传 userMid，AI 消息传 aiMid）。 2. 硬删时：从最新往旧扫 mem: 键（最多 N 条），找到 mid 命中即 delete + 留墓碑；扫不到就记录告警。 3. 代价：每次删除多 1 次 list + 若干读写，且随库增长变慢。

验收：删一条消息后，/export/full 的 memories 与 messages 都不再包含该内容；再聊天时提示词里不出现。

P0-3 收敛访问权限（三选一，按你的使用场景定）

• 方案 A（最省事，推荐）：给 v1/v2 套 Cloudflare Access（Zero Trust，免费档够用），只允许你的邮箱/设备；国内版在平台侧加访问控制（若有）。
• 方案 B（自建）：加口令登录：POST /login 校验口令 → 下发 HttpOnly; Secure; SameSite=Lax 的签名 cookie；页面不再注入 token，改为所有 API 校验 cookie。工作量中等，但三端都能用（国内版同款逻辑）。
• 方案 C（最低成本缓解）：页面不再明文注入 token，改为「首次访问输入访问码 → 存 localStorage」；同时把 worker 的 GET / 也要求带码（否则返回一个只有输入框的壳页）。能挡「随手点开链接的人」，挡不住有心人。

P1-1 修 Key

1. v1：wrangler secret put API_KEY --config wrangler.v1.toml（值 = 你的 DeepSeek Key），或把代码改成 opts.apiKey || env.API_KEY || env.DEEPSEEK_API_KEY（更稳，兼容现状）。
2. v2：同样加 API_KEY。
3. 前端：当 CONFIG.API_KEY 为空时，在输入框上方提示「未填 Key，将使用服务端默认 Key（若已配置）」。

P1-2 修检索「只看得到最旧 1000 条」

方案（推荐）：按月分片 1. 写入键改为 mem:<profile>:<YYYYMM>:<ts>_<rand>。 2. 读取时从当前月开始往前取最多 3 个月（每月 ≤200 键，天然分页），合并后按时间倒排取最近 300。 3. 兼容：旧 mem:<p>:<ts>_... 仍按原前缀读一次（只在没有新分片数据时）。 4. 备选：维护一个 mem_recent:<p> 索引键（存最近 300 个键名，写入时更新，读时一次 get）——写放大 +1，但读取 O(1)。

P1-3 国内版持久化与同源

1. 数据目录改到平台持久卷（若有）；若无，增加「每日把快照 base64 POST 到 v2 的 /import/full」做异地副本（注意配额，可每周一次）。
2. PUBLIC_ORIGIN 改为：优先环境变量 → 其次读平台注入的公开域名 → 兜底现值；isSameOrigin 增加「同 host 的任意路径/端口」放行。
3. 403 时返回中文可读页：「当前访问域名与后端配置不一致，请用 xxx 访问」，而不是让前端显示「发送失败」。

P1-4 统一备份口径

1. 去掉 exportBackup 的 isWebMode() 限制：v1/v2 也调 /export/full（失败再退回本机导出）。
2. 去掉 restoreCloudFullFile 的 isWebMode() 限制（/import/full 三端都支持）。
3. schema:2 文件在三端行为一致。

P1-5 修 CORS

json(data, status, request, env) 增加后两个参数，内部 Object.assign(headers, corsHeaders(request, env))；或在路由出口统一包一层。注意：corsHeaders 只在 Origin 合法时回 ACAO，避免变成开放代理。

P1-6 图片

短期：UI 明确标注「图片只保存在本机，换设备不会同步」；备份说明里写清。 长期：接 R2（或对象存储），msg.attachment 存对象 key，渲染时按需取；KV 只存元数据。

P1-7 分批同步

cloudSyncToServer 改为：本地记录 lastSyncTs → 只上传之后的；每批 50 条，逐批 POST，失败可续传。

P2 / P3 速查

5. 建议的执行顺序（等你决定，我不会擅自动手）

第一批（止血，1 次部署，30 分钟内） 1. P1-5 CORS（1 处函数签名） 2. P1-1 Key 读取兼容（1 行）+ 两个 worker 加 secret 3. P2-5 query 丢失（1 行） 4. P2-13 serveFrontend 桩（防误部署炸）

第二批（数据正确性，需要设计确认） 5. P0-1 统一后端基准（决定「保留多后端」还是「锁死同源」） 6. P0-2 删除彻底化（推荐方案 A：检索改读 msg:） 7. P1-2 检索分片（与 6 一起改，避免两次动检索）

第三批（部署与数据面） 8. P1-3 国内版持久化 + 同源兜底 9. P1-4 备份口径统一；P1-6 图片策略；P1-7 分批同步 10. 历史 279 条软删数据的清理（硬删 + 墓碑，必须分批：每批 ≤200 条，否则写配额当天就满）

第四批（安全） 11. P0-3 访问控制（建议 Cloudflare Access，最快）

配额相关注意：KV 免费版 1000 list / 1000 write / 10 万 read 每天（账户级，北京时间早 8 点重置）。任何「批量清理 / 全量搬迁 / 首次同步」都要按 ≤200 条/批、跨天做，否则第二天照样把配额打满。

6. 本次审查的边界（做不到的部分，如实说明）

7. 一句话总结

三端代码现在是同一份修复版、都能跑；真正的风险不在「能不能用」，而在架构层面的三处不一致：①前端一半接口认「设置的地址」、一半认「当前页面」（P0-1）；②消息存两份、删除只删一份（P0-2）；③三端各有一份互不同步的数据，图片只在本机（P1-3/4/6）。这三件事不解决，后面每一次「修好了」都会在换端/换设备/换域名时重新裂开。

全项目代码基线审查（2026-10-23）

小手机项目 · 全项目代码基线审查报告（只读版）

审查对象：beibbloveme-crypto/yuai（私有仓库，未认证 GitHub API 返回 404 证实非公开） 审查基线：分支 fix/p0-memory-consistency，HEAD = f02cc07（2026-10-22 19:19:35 +0800） 生产版本：51ac31d3-98db-4740-8b8e-f5de09fd7d43（2026-10-22 19:19:43 +0800，经 wrangler API 只读核验，与 HEAD 内容吻合） 审查性质：只读。未修改任何代码、未提交、未部署、未触碰线上数据。所有测试均在本地内存 Mock KV + Mock 模型 + 虚构令牌下运行。 状态标注体系：【已验证完成】【部分完成】【未实现】【存在缺陷】【无法确认】

一、项目基线总览

1.1 仓库与分支状态

【存在缺陷】分支割裂：P0/P1 六个修复提交（9505597 记忆隔离、513f24b 稳定 mid、d4aa34e 删除接口、2460f9a 全量导出导入、5bfe8c8 上下文组装、5b01441 构建修复）只存在于 fix 分支，main 分支不包含（git merge-base --is-ancestor 9505597 main 判定为否）。生产环境实际运行 fix 分支代码，main 已落后生产 15 个以上提交。任何从 main 发起的部署都会丢失全部记忆一致性修复。

1.2 文件清单与职责

构建漂移核验【已验证完成】：在 /tmp/buildcheck 用仓库内的 build.js 对当前 worker.js + index.html 重新构建，产物与仓库中的 cat-chat-all-in-one.js 逐字节一致（diff 无输出）。不存在"只换前端、后端漂移"问题。

1.3 部署配置（wrangler.toml）

name = "zhai"
account_id = "d285d56ff8e27fbe825c552b7a86cc65"
compatibility_date = "2024-09-23"
KV binding: CHAT → ec1a5feca1f446a28c6bb12b5ed7accc
vars: API_URL=https://api.openai.com/v1/chat/completions
      MODEL=gpt-4o-mini
      ALLOWED_API_HOSTS=""
      ALLOW_CUSTOM_API="0"
      ALLOWED_ORIGINS=""

线上 secrets（wrangler secret list 只读查询）：仅 DEEPSEEK_API_KEY 一项。

【存在缺陷】死配置：callModel（worker.js L851）读取的是 env.API_KEY，全仓库无任何代码引用 DEEPSEEK_API_KEY（grep 证实）。即：线上配置的模型密钥永远不会被使用，实际调用模型完全依赖前端请求体里传来的 apiKey；未传时返回 missing_api_key 400。文档"API_KEY 不强制：前端自选填入即可"（L29 注释）与代码行为一致，但 secret 命名与代码读取名不一致属于配置事故。

无 AUTH_TOKEN secret：getToken（L1193-1195）回退到源码内硬编码的 DEFAULT_AUTH_TOKEN = '518effb141664b32940bf691cf65e506'（L1100）。详见第七部分安全分析。

1.4 文档与代码差异比对

二、前端审查（index.html）

2.1 结构总览

• CSS：约 1200 行，含 72 处 .dark-mode 选择器定义（L80、L414、L595、L739、L816 等）。
• JS 模块：storage 键表（L5053-5083）、CONFIG（L5125，WORKER_URL 默认取 location.origin）、syncViewportMetrics() 视口/键盘适配（L10909-11035）、escapeHtml（L8667）、记忆库前端（L8644-8740）、设置持久化（L10546-10723）。
• 令牌传递：window.__CAT_TOKEN__（L7 占位符，Worker 返回页面时注入实际值），7 处请求点携带 X-Cat-Token 头（L7058、L7994、L8495、L8532、L8677 等）。
• 本地存储键（13 个）：chat_history、avatar_ai、avatar_me、chat_bg、user_status、worker_url、persona_prompt、model_provider、model_api_key、model_api_url、model_name、sticker_list、kaomoji_list。API Key 以明文存于 localStorage（model_api_key），属已知取舍（文档声明"前端自选，存本机"）。

2.2 功能完成度

2.3 XSS 面

• escapeHtml（L8667）完整转义 & < > " '。
• 全部 9 处 innerHTML：7 处为清空（= ''）或静态字符串；2 处为记忆库列表渲染（L8689/8692），其中所有用户可控字段（hid/content/mid/category/title/eid/rid/from_id/to_id/reason/rel_type）均经 escapeHtml 包裹（L8705-8734）。
• 消息气泡渲染不走 innerHTML 拼装用户文本。
• 结论：当前无可利用 XSS 向量（前提是后续新增渲染继续沿用 escapeHtml；无 CSP 头兜底，见第七部分）。

三、后端 API 审查（worker.js）

3.1 路由全表（fetch handler L1415-2238）

鉴权覆盖面结论【已验证完成】：所有数据读写路径均有令牌保护；不存在未授权读数据的 GET 路由。鉴权链：isSameOrigin（L1168，浏览器带异源 Origin 直接 403）→ protectedRoute 判定 → checkAuth → safeEqual 定长比较（L1198，防时序侧信道）。

3.2 出站安全（callModel L847-923）

【存在缺陷】SSRF 整数 IP 穿透：L1284 只挡点分十进制。以下形式可绕过：十进制整数 IP（https://2852039166/ = 169.254.169.254）、十六进制 IP（https://0xa9fea9fe/）、解析到内网的公网域名（如 localtest.me、nip.io 类）。Cloudflare 出口本身不完全等价于目标网络位置，且白名单机制（默认 ALLOW_CUSTOM_API=0）已挡住绝大多数场景，故定为中危而非高危——但若运维设置 ALLOW_CUSTOM_API=1，该缺陷升级为高危。

3.3 限流（checkRate L1249 / bumpCounter L1226）

• 参数：单 IP 20 次/分、400 次/天；全局 1500 次/天（SEC L1091-1093），超限 429 + Retry-After。
• 【存在缺陷】fail-open：bumpCounter 的 KV 读（L1228-1230）与写（L1242-1244）失败均被 catch 吞掉，读失败时计数器从 0 起算——KV 故障或限流键竞态期间限制形同虚设。
• 【存在缺陷】KV 最终一致性：计数器存 KV，跨节点读写可能少计，限流是尽力而为而非硬保证。
• 【无法确认】实际拦截效果：需要线上构造超限流量验证，本阶段未做（只读约束 + 不影响线上数据）。

3.4 检索与上下文（tokenize L620 / retrieveMemory L641 / retrieveContext L695 / buildSystemPrompt L716）

• tokenize：中文双字滑窗 + 英文整词（≥2 字符），token 上限 12 个（L638）。
• retrieveMemory：listMemoryKeys（默认 max 1000）→ 按 ts 排序 → 取最近 SCAN_LIMIT=300（L44）→ Promise.all 并行 KV get → 纯 String.includes 命中计数排序 → 无命中则退化为最近 N 条。
• retrieveContext：memories（limit 8）+ highlights（slice 3）+ experiences active（slice 3）+ candidate（slice 2）四路并行。
• 【存在缺陷】记忆容量硬上限：超过 300 条的旧记忆永不参与检索（ silent amnesia ），且无任何提示。
• 【存在缺陷】KV 读取放大：单次 /chat 仅 retrieveContext 就最多产生 300（mem）+ hl/exp 各自 list+N get 次 KV 读，轻松超过 300 次读/请求。Cloudflare KV 免费额度 10 万读/天 → 理论约 300+ 次聊天即触顶，付费额度下也直接推高成本。测试日志可见单次 chat 仅 0-1ms（Mock KV），真实 KV 延迟下这会成为主要耗时。
• 检索质量：无语义理解、无权重衰减、无时效加权，纯子串命中数。

3.5 写入路径

• saveMemory（L129）：cleanText 4000 字、剥离控制字符与模型标记。
• 【存在缺陷】KV 无事务竞态：meta_lastTs 双写（新键 meta_lastTs:<profile> L155 + 旧键 meta_lastTs L158，owner 时），读-改-写无原子性，并发聊天互相覆盖（last-write-wins），影响"距上次聊天太近"判定精度。
• /messages/delete（L2121-2169）：软删打 deleted_at；硬删（mode:'hard' && force）env.CHAT.delete(key) 只删消息本体。
• 【存在缺陷】硬删留记忆碎片：cascadeDeleteRefs（L499）只级联清理 hl:/exp:/rel: 引用，mem: 前缀的记忆碎片不会被清理——硬删消息后，由该消息抽取的记忆永久残留，且仍参与检索。
• /archive POST 导入（L1613-1672）：按 mid 幂等去重（L1639 先 get 后写）、import_batch_id 溯源、逐条 try/catch。
• 【存在缺陷】/archive 导入无体积上限：L1615 直接 request.text() 全量读入后 JSON.parse，既无 content-length 预检也无大小截断。对比 /import/full 有 8MB 检查（L1726）与聊天接口 1MB 检查（L2174/2202）。超大 body 可导致 Worker 内存超限或 CPU 超时（需令牌，定中危）。

3.6 主动消息（handleProactive L2444-2510）

• 配额：PROACTIVE_MAX_PER_DAY = 3（L39），按 day_key 计数（L1009）。
• 【存在缺陷】客户端时间伪造（高危）：resolveTime（L84-105）完全信任请求体的 t.iso——ts、day_key、period、week 全部来自客户端。持有令牌者只需每次传入不同的（如未来的）iso，即可让 day_key 永不落码，从而绕过每日 3 次配额无限刷主动消息；同时污染消息时间线（任意时间戳入库）。该接口有令牌 + 限流保护，跨站攻击者无法直接利用，故综合定高危（对持令牌者）/中危（对陌生攻击者）。
• 主动消息同样走 saveMemory 入库（L2499）与 bumpProactive（L2501）。

四、数据存储与同步审查（Cloudflare KV）

4.1 键空间设计

• profile 校验：VALID_PROFILE = /^[a-z0-9_]{1,32}$/（L172），非法回落 DEFAULT_PROFILE='owner'（L171）。profile 隔离机制本身已实现且经测试验证（P0-1：15/15 通过，含 owner/test 双向隔离、旧键兼容、无 mem:undefined:* 残留）。
• 注意：前端不传 profile，实际全部数据落 owner 单空间——多角色隔离目前是"后端有能力、前端未使用"。

4.2 同步机制

4.3 测试结果汇总（本阶段实际运行）

测试均为内存 Mock KV + Mock 模型 + 虚构数据/令牌，未触碰线上。

五、记忆系统专项

5.1 现状机制

用户消息 ──► handleChat ──► saveMemory(L129) ──► mem:<profile>:<id>（原话，cleanText 4000）
                    │
                    ├─► retrieveContext(L695) ──► memories(≤8) + highlights(≤3) + experiences(≤3) + candidates(≤2)
                    │                                │
                    │                                ▼
                    └──────────────────────────► buildSystemPrompt(L716) ──► callModel

• 三层记忆实体：mem（原话记忆，自动）、hl 高光（收藏/模型 [[fav:]] 触发，带来源 mid）、exp 经历（active/candidate 两态，带 time_certainty 确定性、source_mids 来源）、rel 关联（from_id → to_id，带 reason/confidence）。
• 检索进上下文已验证：P1-6 测试 13/13（含"纯图片时记忆条数受限 ≤8"）。
• 引用完整性已验证：P0-2 测试（mid 一致性、真实来源、missing_refs 400 拦截）。
• 候选经历单列：candidate 状态不混入 active（P1-6）。

5.2 记忆系统的能力缺口（相对工业级记忆系统）

六、原有功能保留清单

以下为对"已有功能逐项核对"的结果（用于后续重构时的保留基准）：

七、安全、稳定性与部署

7.1 生产与开发环境区别

• 无独立 staging：deploy.sh 直接把构建产物推到生产 Worker（zhai.beibbloveme.workers.dev）；开发用 wrangler dev 本地 Mock。生产与开发运行同一套代码、同一份 KV（dev 默认本地模拟，但 wrangler dev --remote 会连生产 KV——存在误操作风险）。
• 凭据：/root/.cloudflare_token 或环境变量（deploy.sh）。
• KV 无环境隔离：单一 CHAT namespace，测试与生产数据若共用即互相污染（当前测试用 Mock，无此问题）。

7.2 高危问题（3 项）

7.3 中危问题（6 项）

7.4 低危与其他（5 项）

7.5 测试覆盖缺口

已覆盖：记忆隔离、mid 一致性、删除同步、导出导入、档案搜索、上下文组装、阶段4 回归（145 断言）。 未覆盖：限流触发与 fail-open、SSRF 各绕过向量、时间伪造、并发竞态、体积上限、令牌轮换、前端渲染回归（无前端测试框架）。

八、开源项目对照研究（Mem0 / Graphiti / Letta / LangGraph）

研究方法：基于四个项目公开仓库的源码结构（非 README 宣传）分析其记忆/时间线/关系/持久状态/任务恢复/人工审核机制。结论：不照搬任何框架，仅提炼可借鉴机制与 KV 架构下的低成本落地方式。

8.1 Mem0——记忆变更决策与版本链

• 核心机制：对每条新记忆先做 ADD / UPDATE / DELETE / NONE 四态决策（由 LLM 判定与既有记忆的关系），所有变更写入独立 history 表，保留旧值快照；检索用 BM25 加性打分（多词命中线性叠加）。
• 源码位置：mem0/memory/main.py（Memory 类的 add/search 流程与 history 落库）、mem0/memory/ 下的 graph 与向量存储实现。
• 可借鉴：①"先决策再写入"——当前项目只有追加写，矛盾记忆并存无感知；②history 版本链——记忆被更新/删除后仍可追溯。
• KV 落地成本：中。可在现有 mem:<profile>:<id> 旁加 memhist:<profile>:<id> 键存变更链；决策逻辑需一次额外 LLM 调用（成本 +1 次/记忆写入）。
• 风险：决策调用引入延迟与费用；决策错误会静默污染记忆库（需人工审核兜底，见 8.5）。

8.2 Graphiti——双时间戳与时序知识图谱

• 核心机制：每条事实带 valid_at / invalid_at / expired_at 三个时间戳，显式建模"何时生效、何时失效、何时过期"；检索用 RRF（Reciprocal Rank Fusion）融合多路结果。
• 源码位置：graphiti-core/graphiti_core/（edges/nodes 的时间字段定义与 search 融合逻辑）。
• 可借鉴：①时间语义——当前经历记忆只有单 created_at 和一个声明式的 time_certainty 字段，没有"这句话描述的事何时成立/失效"的概念；②RRF 融合——当前纯关键词单路检索，未来接入语义检索时需要融合策略。
• KV 落地成本：低-中。时间字段只是给现有 exp:/rel: 记录加字段；RRF 需要多路检索结果，当前架构只有一路关键词，暂用不上（接入语义检索后才需要）。
• 风险：时间推理依赖 LLM 抽取质量；低。

8.3 Letta——分层记忆与上下文预算

• 核心机制：core memory（有限容量的核心块，Block 有 limit）/ archival memory（无限归档）/ recall memory（对话历史）三层；用 ApproxTokenCounter（约 bytes/4）在组 prompt 前做 token 预算控制，超预算按策略裁剪。
• 源码位置：letta/（letta/schemas/block.py 的 Block limit、letta/ 下的 token 计数与 context 组装）。
• 可借鉴：①上下文预算——当前 buildSystemPrompt 按条数硬截（8/3/3/2），中英文长度差异大，条数 ≠ token 量；②分层——把"人设/长期事实"（core，必进 prompt）与"历史原话"（archival，按需检索）分开。
• KV 落地成本：低。token 估算就是 Buffer.byteLength/4 量级的函数；分层只是调整 buildSystemPrompt 的取数逻辑。
• 风险：低。纯计算逻辑，无外部依赖。

8.4 LangGraph——持久状态、任务恢复与命名空间

• 核心机制：checkpointer 把每步状态持久化（thread_id + writes 表），支持 time-travel（回到任意历史步重放）；BaseStore 用 namespace 前缀做跨线程共享存储。
• 源码位置：libs/langgraph/（langgraph/checkpoint/ 的 BaseCheckpointSaver 实现与 writes 表结构、langgraph/store/ 的 BaseStore namespace）。
• 可借鉴：①thread_id + 分步 writes——当前对话就是扁平的 msg 列表，没有"一次任务多步执行、中断可恢复"的概念（对照第 5.2 节"任务恢复未实现"）；②namespace 前缀——与当前 mem:<profile>:* 前缀设计同构，说明现有键设计方向正确。
• KV 落地成本：中。需要引入"任务"实体与状态机；KV 无事务，多步写入的原子性需自己补偿（见 8.5 建议4）。
• 风险：中。任务状态机是较重的抽象，个人项目应按最小集引入（例如只做"主动消息任务的断点恢复"）。

8.5 横向对比与 KV 架构设计建议

给后续记忆系统重新设计的 5 条建议（均基于现有 KV 架构，零新基础设施）：

1. 确定性规则 + history 版本链（借鉴 Mem0）：写入前用确定性规则（同实体高相似度 → UPDATE 并写 memhist: 链）替代无条件追加；LLM 四态决策作为可选增强，默认关闭以控成本。
2. 双时间戳（借鉴 Graphiti）：给 exp:/rel: 记录加 valid_at/invalid_at 字段，检索时过滤已失效项——这是修复"矛盾记忆并存"的最低成本手段。
3. RRF 融合预留（借鉴 Graphiti）：retrieveMemory 的排序层抽象成"多路候选 → 融合"接口，当前只有关键词一路；未来接入任何语义检索时直接挂载。
4. DO + WAL 流水线（借鉴 LangGraph checkpointer 思想，规避 KV 无事务）：把"一次聊天的多次 KV 写"先写 Durable Object 的 WAL 再异步落 KV，解决 7.2-H3 之外的写入原子性与读取放大（M3）。
5. core memory + 上下文预算（借鉴 Letta）：prompt 组装从"条数硬截"改为"core 必进 + archival 按 token 预算填充"，token 估算用 bytes/4 近似。

引入成本与风险总评：以上 5 条均可在现有 Worker + KV 上实现，不引入新服务；主要成本是 LLM 决策调用（可选）与一次检索层重构。明确不建议直接引入 Mem0/Graphiti/Letta/LangGraph 框架本体——它们分别自带向量库/图数据库/服务端运行时，与当前"单 Worker + KV"的极简架构和零外部依赖原则冲突。

九、升级前置条件（重新设计记忆系统之前必须解决）

按优先级排序，每条对应前文证据：

1. 分支合并：将 fix/p0-memory-consistency 合回 main 并重新确立基线，否则任何"从 main 重构"都会丢失 P0/P1 全部修复（7.4-L3）。
2. 令牌治理：部署 AUTH_TOKEN secret 替换硬编码默认值；建立轮换流程；评估"共享静态令牌"是否足够（当前页面注入方案决定了令牌必然随页面下发，跨站已被 Origin 校验挡住，主要风险是源码/产物扩散）（7.2-H1）。
3. 时间服务端化：resolveTime 忽略客户端 iso 或取 max(server_now, client)；主动消息配额改按服务端日期（7.2-H2）。
4. 限流加固：计数器失败时 fail-closed 或至少告警；评估 Durable Object 计数器的成本（7.2-H3）。
5. /archive 导入加体积上限（对齐 /import/full 的 8MB 或更小）（7.3-M1）。
6. SSRF 规范化：IP 字面量检查前做规范化（解析十进制/十六进制/短形式为点分十进制再判）（7.3-M2）。
7. KV 成本治理：单次 chat 300+ 读的放大必须先行解决（DO 缓存 / 批量读 / 降低 SCAN_LIMIT 并配归档），否则新记忆系统只会更重（7.3-M3）。
8. 硬删补清理：硬删消息时级联清理 mem: 碎片，或在检索层按来源 mid 过滤已删消息（7.3-M4）。
9. secret 命名对齐：把线上 DEEPSEEK_API_KEY 改为代码读取的 API_KEY，或改代码读 secret 现名；确定服务端是否保留兜底 Key（7.3-M6）。
10. 文档版本机制：三份文档的生产版本号与实际部署脱节，建立"部署后回写版本号"的流程（7.4-L4）。
11. 测试补齐：为限流、SSRF、时间伪造、并发、体积上限补测试；当前 145 断言不覆盖上述任何一项（7.5）。
12. 记忆容量方案：300 条扫描上限是事实容量天花板，重构前需确定归档/分层/淘汰策略（5.2）。

十、证据索引

10.1 代码位置索引（worker.js，共 2510 行）

10.2 代码位置索引（index.html，约 11560 行）

10.3 配置与部署证据

• wrangler.toml：name=zhai、KV CHAT id、vars（API_URL/MODEL/ALLOWED_API_HOSTS=""/ALLOW_CUSTOM_API="0"/ALLOWED_ORIGINS=""）
• wrangler secret list：仅 DEEPSEEK_API_KEY（无 AUTH_TOKEN、无 API_KEY）
• wrangler deployments list/status：最新生产 51ac31d3-98db-4740-8b8e-f5de09fd7d43（2026-10-22 19:19:43 +0800）
• git log：HEAD f02cc07（19:19:35 +0800，较部署早 8 秒，内容吻合）
• 构建核验：/tmp/buildcheck 重新构建产物与仓库 cat-chat-all-in-one.js diff 为空
• 分支核验：git merge-base --is-ancestor 证实 6 个 P0/P1 提交不在 main

10.4 测试证据（本阶段实际运行，全部通过）

test_p0_memory_isolation.mjs   15/15   profile 隔离 + 旧键兼容
test_p0_mid_refs.mjs           21/21   mid 一致性 + 引用校验 + 图片元数据
test_p0_delete_sync.mjs        23/23   软删/硬删/级联/防复活/隔离
test_p0_export_import.mjs      27/27   全量导出导入/幂等/dry_run/软删保留
test_p1_archive_search.mjs     14/14   关键词/时间/说话方/分页/软删过滤
test_p1_memory_context.mjs     13/13   记忆进 prompt/候选分离/条数上限
test_phase4_v2.mjs             32/32   阶段4 原功能回归
合计                           145/145 通过，0 失败（Mock KV + Mock 模型 + 虚构令牌）

10.5 开源项目参考

• Mem0：github.com/mem0ai/mem0（mem0/memory/main.py 四态决策与 history；BM25 加性打分）
• Graphiti：github.com/getzep/graphiti（graphiti-core/graphiti_core/ 双时间戳与 RRF）
• Letta：github.com/letta-ai/letta（Block limit、ApproxTokenCounter、三层记忆）
• LangGraph：github.com/langchain-ai/langgraph（langgraph/checkpoint/、langgraph/store/ namespace）

10.6 未能核验事项（【无法确认】）

1. 线上 /health 实际响应：沙箱网络无法访问 zhai.beibbloveme.workers.dev（curl 超时），版本一致性结论基于 wrangler API 元数据而非线上抓取。
2. 限流在真实 KV 上的实际拦截效果（需构造超限流量，未执行）。
3. KV 中现存数据量（未做线上 list 全量扫描，避免无谓的读放大与费用）。
4. 仓库确切的协作者/权限名单（GitHub API 未认证仅确认私有）。

附：审查结论摘要

• 代码基线本身是健康的：双真源 + 构建产物零漂移、145 项回归测试全过、P0/P1 记忆一致性修复已在生产。
• 主要风险集中在三处：硬编码默认令牌（H1）、主动消息时间伪造（H2）、限流 fail-open（H3），另有 KV 读取放大带来的成本风险（M3）。
• 分支与文档管理落后于部署节奏：main 不含生产修复、三份文档版本号过期——这是重构启动前最优先要平整的工程债。
• 记忆系统的能力缺口清晰：无变更决策、无版本链、无双时间戳、无 token 预算、无人工审核、300 条事实容量上限；第八部分给出了 5 条不引入外部框架的 KV 原生演进路径。

本阶段任务至此结束。按任务书要求，交付本报告后停止，不开始重构，不开发新记忆系统，不修改任何既有代码与线上配置。

完整交付文档（2026-10-22）

小手机（猫爪聊天）· 完整交付文档

一份文档看懂整个项目：源码结构 + 功能介绍 + 开发进程 + 测试证据 + 交接信息

生成时间：2026-10-22 ｜ 代码基线：分支 fix/p0-memory-consistency @ b03a612（main @ 75657e0） 线上版本：f490d9d2-8ee5-4d0c-9274-b082b5d34990（2026-10-19T07:14:23Z 起 100% 在线，早于本轮修复，未包含 P0–P1 改动）

证据约定：本文所有结论分三级——【源码】= 直接读代码得出；【实测】= 本地跑测试得出；【未验证】= 沙箱无法证实（如线上字节一致性、GitHub 远端实时状态）。凡未标注者均为【源码】级。

目录

0. 这份文档怎么用
1. 项目概况
2. 源码介绍（逐文件 · 逐模块 · 逐接口）
3. 功能介绍（完整清单）
4. 架构与数据流
5. 开发进程记录（从 0 到当前）
6. 测试与证据
7. 交接信息（仓库 / 备份 / 部署 / 敏感项）
8. 已知限制与技术债
9. 待办与后续阶段
10. 常用操作手册 附录 A · 证据索引 ｜ 附录 B · 术语表

0. 这份文档怎么用

本文不包含：任何真实密钥、令牌、wrangler.toml 中的账号 ID 与 KV ID（这些只在本机工作区）。文中出现的 ID 均为仓库文件内已有的非机密标识。

1. 项目概况

1.1 一句话

一个单文件 Cloudflare Worker 全栈应用：前端是一个仿微信的高定制聊天界面（唯一真源 index.html，11241 行），后端是同一仓库的 worker.js（2510 行），构建时内联成单一部署文件 cat-chat-all-in-one.js，数据全部存 Cloudflare KV，大模型 Key 由用户在前端自行填写、经 Worker 代理调用。

1.2 基本信息

1.3 目录结构

/workspace/chat/
├── index.html                  # 前端唯一真源（11241 行 / 196KB）
├── worker.js                   # 后端唯一真源（2510 行 / 138KB）
├── build.js                    # 构建脚本（58 行）：worker.js + index.html → 部署文件
├── cat-chat-all-in-one.js      # 部署产物（2531 行 / 401KB）= 后端 + FRONTEND_B64 + serveFrontend()
├── wrangler.toml               # Worker 配置（含真实账号/KV ID，勿外传）
├── deploy.sh                   # 备用部署脚本（CF_API_TOKEN 方式）
├── icons/                      # PWA 图标（192/512/apple-touch）+ gen_icon.py 生成脚本
├── tests/                      # 7 个测试脚本（Node 直调 + 内存 Mock KV）
├── 任务交接说明.md              # 交接总览
├── 安全说明.md                  # 安全层设计
├── 审计报告-阶段0.md            # 阶段 0 只读审计
├── 修复记录-P0-P1.md            # 本轮修复的提交级记录
├── 模块索引.md                  # 改代码前的区域地图（按区点单）
├── 猫爪聊天-完整项目.md          # 历史融合版全代码（占位符版，可外传）
├── 替换指南.md / 给其他AI-代码包/  # 历史交接材料
├── 效果图-*.png / 新界面-*.png   # 17 张界面截图（其中 2 张未提交）
└── .wrangler/                  # 本地 wrangler 状态（已 gitignore，可能含登录凭证）

2. 源码介绍

2.1 三个核心文件的分工（先理解这个，再谈任何改动）

index.html ──┐
             ├──► build.js ──► cat-chat-all-in-one.js ──► wrangler deploy ──► 线上
worker.js ───┘                   （部署文件）

历史上踩过的坑（构建漂移）：早期 build.js 只替换前端 base64、不同步后端，导致部署文件的后端长期停在旧版——线上跑的后端和仓库里的 worker.js 不是同一份代码。本轮已重写 build.js 为整体生成，并以 SHA256 校验前缀一致（c137a6ca…）。【实测】

build.js 核心逻辑（全文 58 行，摘录）：

const b64 = Buffer.from(html, 'utf8').toString('base64');
const backend = fs.readFileSync(workerPath, 'utf8');
const serveBlock = `... const FRONTEND_B64 = "${b64}"; function serveFrontend(){...} ...`;
fs.writeFileSync(outPath, backend.replace(/\s+$/, '') + '\n' + serveBlock);

2.2 后端源码地图（worker.js，行号为当前 HEAD）

区域总表

关键源码摘录（理解系统行为的六个点）

① 记忆按 profile 隔离（P0-1，修掉跨角色泄漏）

async function saveMemory(env, profile, role, content, time) {
  const p = VALID_PROFILE.test(String(profile || '')) ? String(profile) : DEFAULT_PROFILE;
  const key = `mem:${p}:${ts}_${rand}`;            // 旧格式为 mem_<ts>_<rand>（全局）
  await env.CHAT.put(key, val);
  await env.CHAT.put('meta_lastTs:' + p, String(ts));   // 最后聊天时间也按 profile
  if (p === DEFAULT_PROFILE) await env.CHAT.put('meta_lastTs', String(ts)); // owner 兼容旧键
}

② 消息归档幂等（P0-2，修掉重试重复入档）

async function saveArchive(env, profile, rec) {
  if (!rec || !rec.mid || !rec.content) return { skipped: true };
  if (await env.CHAT.get(key)) return { skipped: true };   // 同 mid 只写一次
  await env.CHAT.put(key, val);
}

③ 鉴权闸门（所有 POST 在进入任何业务逻辑前拦截）

const protectedRoute =
  request.method === 'POST' ||
  url.pathname === '/proactive' ||
  url.pathname === '/backup' ||
  url.pathname === '/init';
if (protectedRoute && !checkAuth(request, env)) {
  return json({ error: 'unauthorized', rid }, 401);
}

getToken(env) = env.AUTH_TOKEN || DEFAULT_AUTH_TOKEN（1193 行）。令牌同时通过 pageResponse() 以 window.__CAT_TOKEN__ 注入页面——这意味着知道线上地址的人就能从页面里拿到访问令牌（已知限制第 1 条，见第 8 节）。

④ 提示词组装（P1，记忆闭环）

function buildSystemPrompt(persona, time, ctx) {
  // ctx 来自 retrieveContext()：旧记忆 top5 + 高光 top3 + active 经历 top3 + 候选经历 top2
  // 三段新增：长期高光原话 / 已确认经历 / 候选经历（明确标注"不得当作事实"）
}

⑤ 模型上下文检索（P1）

async function retrieveContext(env, profile, query, time, limit = 5) {
  // 同时取四路，全部按 profile：mem:<profile>:* / hl:<profile>:* / exp:<profile>:*（active|candidate）
}

⑥ 聊天主入口行为（handleChat，2247 行起）

• 解析 body.client_mid（前端生成的 c_<ts>_<rand>），用户消息 mid 优先复用它 → 重试不产生重复档案；
• AI 回复使用独立 ai_mid（a_<ts>_<shortId>），响应回传 user_mid/ai_mid；
• 同 mid 内容一致 → 跳过写入（user_mid_reused=true）；内容不一致 → 409 mid_conflict；
• 检索上下文 → 组提示词 → callModel → 解析 [[status:]]/[[fav:]] → 入档 → 返回。

2.3 路由表（全部接口）

请求体上限 SEC.MAX_BODY = 8MB（P0-4 为全量导入从 1MB 提升）；单条消息 4000 字；图片 800KB。

2.4 KV 键位图（CHAT 命名空间）

<profile> 默认 owner，校验 ^[a-z0-9_]{1,32}$；测试角色必须用不同 profile_id 与正式数据隔离。

2.5 前端源码地图（index.html，改 UI 前先看《模块索引.md》）

P0-2 起前端新增的关键字段/行为：每条消息对象带 mid（c_<ts>_<rand>）；requestChat 携带 client_mid；重试复用同一 mid（幂等）；收藏/云同步/恢复携带真实 mid；多选删除先 POST /messages/delete 成功后再删本地；AI 的 [[fav:]] 也进入云端高光。

2.6 六条主数据流

1. 发消息：sendMessage() → 生成 mid → 本地渲染 → requestChat(text, img, clientMid) POST → Worker 鉴权/限流 → 按 profile 检索上下文 → 组提示词 → callModel → 解析标记 → saveArchive 入档 → 返回 {reply, user_mid, ai_mid} → 前端回写 mid 与状态。
2. 重试：复用同一 mid → Worker 发现档案已存在且内容一致 → 跳过写入（不重复归档），但仍调用模型生成新回复（新 ai_mid）。
3. 多选删除：前端收集 mid → POST /messages/delete（默认 soft）→ 有引用返回 409 列表 → 用户确认 force → 级联软删 → 成功后本地再删 → 失败保留本地并提示（防“恢复复活”）。
4. 云同步：cloudSyncToServer() → POST /archive（带 m.mid）→ 幂等写入 msg:<profile>:<mid>。
5. 云恢复：cloudRestoreFromServer() → GET /archive → 合并本地；恢复前本地另存 messages_pre_restore。
6. 全量导出/导入（API，暂无 UI）：GET /export/full → JSON（schema 2）→ 异机 POST /import/full?dry_run=1 预览 → 正式导入逐条报告。

3. 功能介绍（完整清单）

3.1 聊天核心

• 文字消息（4000 字上限）、图片消息（相册/相机/文件三入口，前端压缩 ≤800KB）
• 表情包（微信式压缩，长边 240px，透明图存 PNG）、颜文字、收藏夹
• 消息状态：发送中/失败/已送达；失败可重试（幂等）
• 头像上方状态文字（[[status:…]] 由 AI 生成并解析展示）
• 居中时间条、按时间分组刷新
• 引用回复（#replyBar）
• 图片灯箱查看
• 多选操作（全选/批量删除）

3.2 AI 行为

• 主动消息：AI 可主动搭话，每日上限 PROACTIVE_MAX_PER_DAY、最小间隔 PROACTIVE_MIN_GAP，按 profile 计数
• 人设：仅自定义人设（设置里填写），无则完全不放人设段；提示词内含身份认知、时间感知（resolveTime/periodOf）、状态/收藏引导
• 记忆闭环（P1）：每次请求自动携带——长期记忆 top5、高光原话 top3、已确认经历 top3、候选经历 top2（候选明确标注“不得当作事实”）

3.3 多服务商模型

前端可选 OpenAI / DeepSeek / 通义 / 自定义，Key 存浏览器本地，经 Worker 代理；validateApiUrl() 白名单 + https + 443 + 禁内网 IP + 禁重定向。

3.4 外观定制（区域 I）

全局底色、顶栏色、底栏色、双方气泡颜色/透明度/磨砂模糊、气泡文字色、自定义气泡皮肤（PNG 九宫格 border-image-slice:33%）、全屏模式、状态文字贴头像定位。

3.5 备份与恢复（三层）

3.6 记忆系统（阶段 2–4 + P0–P1）

3.7 安全层（安全说明.md 有完整设计）

访问令牌认证（任意 POST / /proactive /backup /init 必须带头）、同源校验、三级限流（IP 分钟/IP 日/全局，KV 计数）、请求体与消息体积限制、出站地址白名单与 SSRF 防护、提示词注入边界（<<< >>> + 最高优先级安全段）、错误脱敏（对外只给错误码 + rid）、日志 rid 追踪。

3.8 PWA

manifest + 192/512/apple-touch 三图标（icons/gen_icon.py 生成），可“添加到主屏幕”。

4. 架构与数据流

4.1 总体架构

┌─────────────────────────── 浏览器 ───────────────────────────┐
│ index.html（单页）                                            │
│  UI 层（区域 A-F）   数据层 G（localStorage + IndexedDB）       │
│  接口层 H（requestChat / checkProactive / 云同步 / 全量导入）   │
└───────────────┬──────────────────────────────────────────────┘
                │ HTTPS（带令牌 X-Cat-Token / body.token）
┌───────────────▼──────────────────────────────────────────────┐
│ Cloudflare Worker（cat-chat-all-in-one.js）                   │
│  安全闸门：同源 → 令牌 → 限流 → 体积 → 路由分发                  │
│  /chat（任意POST）  /archive  /export|import  /highlights...  │
│  /proactive  /messages/delete  /backup  /init  /health        │
│  检索（retrieveContext）→ 提示词（buildSystemPrompt）          │
│  → callModel（出站白名单）→ 解析（status/fav）→ 入档            │
└───────────────┬──────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────┐
│ Cloudflare KV（CHAT）：mem:* / msg:* / hl:* / exp:* / rel:*   │
│                      meta_lastTs:* / proactive:* / rl_*       │
└───────────────────────────────────────────────────────────────┘
                │ 出站
┌───────────────▼──────────────────────────────────────────────┐
│ 大模型 API（OpenAI 兼容，多服务商，Key 由前端提供）             │
└──────────────────────────────────────────────────────────────┘

4.2 存储分层

4.3 一次聊笑的完整链路（按代码顺序）

请求 → CORS/同源 → 令牌闸门（④） → 路由匹配 → 限流 checkRate → 体积检查 → handleChat → profileOf 定 profile → 解析 client_mid → saveArchive（幂等）→ retrieveContext（四路检索）→ buildSystemPrompt → callModel（validateApiUrl → fetch → 错误脱敏）→ parseStatus/parseFavorites → saveMemory + 高光/收藏入库 → 返回 {reply, user_mid, ai_mid, should_*} → 前端回写 mid/状态。

5. 开发进程记录

5.1 Git 全历史（20 个提交，git log --oneline）

分支：fix/p0-memory-consistency（14–20，7 个提交，未推送）｜main = 75657e0（2026-10-19 15:49）。

5.2 阶段 0–4 简述

5.3 审计进程（修复前发生了什么）

1. 交接只读检查 ×3：仓库地址/私有性/备份时间/未提交项；两个未跟踪截图文件（新界面-v3-贴底无方块.png、新界面-顶部无壳.png，UI 效果图，无功能作用）；部署版本证据（Cloudflare API 只读确认 f490d9d2 在线，早于本轮修复）。
2. 完整只读审计：以任务书为验收基准，输出功能清单、架构与数据流、逐条需求验收表、风险清单、证据索引。发现高危项：mem_* 跨 profile 泄漏、高光/经历不进模型上下文、mid 断链、重试重复入档、本地删除不落云端导致恢复复活、生产 KV 无全量备份、令牌随页面公开下发。
3. 第二轮只读复核：逐项追踪泄漏条件、ID 不一致点、重复入档与云端复活是必然还是条件性，标注证据等级与置信度。
4. 夜间自主推进（只读 + 本地虚构数据）：交叉复核、整理可重复测试（/workspace/小手机-审计草案/，含 21/21 通过的隔离测试）、分阶段修复方案、独立草案补丁、交接文档。未改正式源码、未提交、未部署、未读真实数据。

5.4 修复阶段（P0-1 → P0-4 + P1，每个都先测试后提交）

历史 test_phase4.mjs 有 12 项失败，原因是旧测试用假 mid（u_111）被新的严格引用校验拒绝——属测试数据过期，非功能回归，已由 test_phase4_v2.mjs（真实来源）替代。【实测】

5.5 当前 Git 状态（2026-10-22）

• 分支：fix/p0-memory-consistency @ b03a612；main @ 75657e0；远端 origin/main 存在（沙箱内 GitHub 返回 403/404，远端实时状态未验证）。
• 与 main 差异：12 个文件，+3229 / -193（worker.js +853 行为主）。
• 工作区未跟踪文件 2 个：新界面-v3-贴底无方块.png、新界面-顶部无壳.png（均为 UI 效果图）。
• 未 push、未部署。线上仍是修复前的 f490d9d2。

6. 测试与证据

6.1 测试矩阵（全部本地运行，内存 Mock KV + Mock 模型 + 虚构数据 + 虚构令牌）

6.2 构建一致性【实测】

• cat-chat-all-in-one.js 的 worker 前缀与 worker.js 逐字节一致（SHA256 同为 c137a6ca…）；
• 部署文件内联前端与 index.html 一致。

6.3 复跑方式

cd /workspace/chat
for f in tests/test_p0_memory_isolation.mjs tests/test_p0_mid_refs.mjs \
         tests/test_p0_delete_sync.mjs tests/test_p0_export_import.mjs \
         tests/test_p1_memory_context.mjs tests/test_p1_archive_search.mjs \
         tests/test_phase4_v2.mjs; do node "$f"; done

语法校验（对部署文件）：cp cat-chat-all-in-one.js /tmp/w.mjs && node --check /tmp/w.mjs。

6.4 尚未覆盖（诚实声明）

• 未做线上验证：沙箱无法访问 workers.dev（返回 000），线上字节与 KV 实际内容未核对。
• 未做浏览器端 E2E：Playwright 方案就绪（本地 wrangler dev --local），本轮未重跑全链路 UI。
• 图片本体、R2 迁移：未开始（见第 9 节）。

7. 交接信息

7.1 仓库与备份

7.2 部署

7.3 敏感信息处理

• wrangler.toml 含真实 account_id 与 KV id，仅存本机工作区，勿外传；对外分享用《猫爪聊天-完整项目.md》（占位符版）。
• .wrangler/ 可能含登录凭证，已 gitignore，不要提交、不要打包外发。
• Worker 源码内 DEFAULT_AUTH_TOKEN 为内置默认令牌，且会随页面下发给浏览器——知道线上地址即可获得访问令牌（已知限制第 1 条）。轮换方式：wrangler secret put AUTH_TOKEN（未执行，待授权）。
• 本文档及所有报告不含任何真实密钥。

7.4 最小交接文件清单

8. 已知限制与技术债

1. 令牌随页面公开下发：pageResponse 把 __CAT_TOKEN__ 注入页面，任何能打开线上地址的人都能拿到访问令牌（可读写该 Worker 的全部数据）。缓解：轮换 AUTH_TOKEN secret、后续阶段改独立强认证（阶段 7）。这是当前最大安全面。
2. 图片本体不入云档：云端只存 message_type:'image' 与附件元数据；图片本体恢复需 R2（未启用、涉及付费、未授权）。
3. 旧本地消息无 mid：更早的本地消息只能本地删除；若曾被归档，云端记录可能仍在。
4. 重试会生成新的 AI 回复：用户消息幂等，但每次重试仍调模型、写新 ai_mid。
5. 搜索为扫描式：最多扫 20,000 key，无索引；数据量大时 KV 读成本上升。
6. 全量导入上限 8MB：更大备份需分批。
7. STRICT_MID 默认开启：外部脚本用假 mid 建高光/经历/关系会得 400（刻意的完整性约束）。
8. 旧 mem_* 不迁移不删除：仅 owner 只读；其他角色不可读。
9. 全量导出/导入、档案搜索暂无前端 UI：目前是受令牌保护的 API；现有“云端同步/恢复”按钮继续可用。
10. 未部署：线上仍为 f490d9d2，本地修复未上线。
11. index.html 存在同名选择器重复定义（.avatar .header .bubble 等 2 份以上，以最后一份为准）——改样式前必须 grep -n "选择器{" 数一遍（《模块索引.md》第五节有清单）。
12. cat-chat-all-in-one.js 是构建产物但被 Git 跟踪：历史上它才是“真正部署的文件”，保留跟踪便于回滚；修改必须经 build.js。

9. 待办与后续阶段

9.1 立即可做（需你授权）

9.2 原任务书后续阶段（未开始）

10. 常用操作手册

# 改前端后重新生成部署文件（必须！）
cd /workspace/chat && node build.js

# 语法校验部署文件
cp cat-chat-all-in-one.js /tmp/w.mjs && node --check /tmp/w.mjs

# 跑全部测试
for f in tests/test_*.mjs; do node "$f"; done

# 本地起前端（file:// 下 localStorage 被禁用，必须走 http）
python3 -m http.server 18924

# 查看与 main 的差异（可审查）
git diff main..HEAD --stat
git log main..HEAD --oneline

# 只读查询线上部署版本
npx wrangler deployments list --json

# 回滚线上（紧急）
npx wrangler rollback f490d9d2-8ee5-4d0c-9274-b082b5d34990

# 代码回滚（放弃本地修复）
git checkout main
# 或逐个 revert
git revert 5b01441 5bfe8c8 2460f9a d4aa34e 513f24b 9505597

附录 A · 证据索引

附录 B · 术语表

本文档由本地只读检查 + 实际运行测试生成；未修改任何源码、未提交、未部署、未读取任何真实用户数据。