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

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

生成时间：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 · 术语表

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