# 生命树内容工作台 · 第一阶段技术交接与维护手册

文档编号：LT-P1-HANDOVER-001　｜　登记日：2026-10-28（Asia/Shanghai）

责任方：尤智科技。工作台名称为“生命树”，不是“神秘树”。本文以实际源码和发布记录为依据；不包含密钥、咨询资料或用户文章备份。

## 1. 阶段结论与使用顺序

BOSS本次决定：内容生产先阶段性收口，保留当前成果，后续进入草稿箱对接。这个决定不等于所有已知问题消失，也不等于已经签署85分内容质量验收。

| 阶段 | 范围 | 当前结论 |
|---|---|---|
| 第一阶段 | 灵感/历史资料→选题→故事→家庭关系解析与建议→润色→文字检查→设计排版→图文复验→人工专业审核→待分发交付物 | 作为当前试用与继续开发的基线保留；内容质量持续校准 |
| 第二阶段 | 工作台已保存图文→指定小红书账号的草稿箱→回读确认 | 下一阶段，尚未完成，不把导出ZIP当作草稿箱对接完成 |
| 第三阶段 | 分发及账号/运行管理 | 按此前三阶段口径暂列；BOSS最后提到的“更换/管理”是否专指账号切换，待确认 |

**接手先读本文，再读专项文档，最后查看旧版 HANDOVER.md。** 旧文件是按日期累加的工程历史，包含早期已失效的描述；不能把“纯静态原型”“图片API未接入”等历史文字当作当前现状。事实冲突时，先核对本文标明的源码提交及实际线上设置。

## 2. 精确工程基线

| 项目 | 精确值 |
|---|---|
| Site project ID | `appgprj_6ad6cbeeaf7081919c954b258a1871a5` |
| 线上地址 | https://lifetree-ops.halemouse64.chatgpt.site |
| 功能基线应用版本 | `V0.19.19` |
| 功能基线源码提交 | `073ae2ccb6aaf4ce0ccfb3caa43b2cb37cd0aae4` |
| Sites已保存版本号 | `81`（与文章V号、数据库R号无关） |
| Sites版本ID | `appgprj_6ad6cbeeaf7081919c954b258a1871a5~appgver_99a3846aed6c8191ac58d62af7d7639c` |
| 成功部署ID | `appgdep_6ae210190c288191b1e007999bdc1522` |
| 功能基线部署时间 | 2026-10-28 23:09:36（北京时间） |
| 发布归档内容哈希 | `sha256:83e2a30a7b84ef39282300da0ec7ef3235f0f0a6270b90acfa03908cae8d1813` |
| 权限 | owner-private；后续不得默认为公开发布 |
| 持久绑定 | Cloudflare D1：`DB`；R2：`BUCKET` |

机器可读记录见 [PHASE1_BASELINE.json](PHASE1_BASELINE.json)。本次交接文档发布会产生一个更新的Sites版本，但其功能代码以第81号版本为收口基线；文档补充版不是另一个内容生产功能里程碑。

保留原 `LT-CP-001 / V0.14.7 / 第37号` 历史节点，不覆盖其登记事实。新的推荐功能参考点为 `LT-CP-002 / V0.19.19 / 第81号`。**不建议把生产环境回到缺少文章防降版保护的早期版本。**

## 3. 运行架构：哪些在云端，哪些还在浏览器

| 层 | 实际职责 | 关键边界 |
|---|---|---|
| 浏览器前端 | 编辑表单、内容Agent调用、自动生产编排、任务队列、Canvas排版、ZIP导出、本机凭据恢复、同步调度 | 内容任务执行器目前仍在浏览器；关闭整个浏览器后不会继续发起新的文字调用 |
| Sites / Vinext / Cloudflare Worker | 已登录账号识别、工作区同步、Agent设置、图片网关、图片存取、诊断、灵感接口 | 云端保存业务数据不代表所有Agent已经在云端常驻运行 |
| D1 | 工作区快照及修订、Agent设置及修订、灵感池与运行日志、模型诊断 | 当前业务同步仍是整工作区快照，不是逐篇协作数据库 |
| R2 | 每篇生成/上传的图片文件、短期供应商结果回执 | 不使用固定示例图冒充新生成图；文件与数据库须分别备份 |
| 外部文字平台 | 根据角色配置生成/解析/润色/审校/协调 | 默认OpenRouter路由；实际可用性受用户账号、服务商和网络影响 |
| MXAI | 生图任务执行；通过MCP SSE查询账号、提交任务、查询结果 | 已提交任务在外部执行；本机停止轮询不等于供应商任务取消 |

目录职责：

- `public/`：实际工作台HTML、经典JS、Agent模块、样式、字体及公开给已授权访问者的文档。
- `app/api/`：HTTP路由；`server/`：对应业务实现。
- `db/`、`drizzle/`：数据库定义及已有迁移。
- `docs/`：源码内的维护文档；关键文档镜像到 `public/` 以便工作台查看。
- `dist/`：构建输出，**不能手工修补后当作源码交付**。
- `cloud-agent/`：独立Node/SQLite服务的候选实现；不是当前已部署的五角色浏览器链路的等价替代品。
- `windows/`及旧下载包：历史部署/辅助交付物；不能据文件存在断言已经接通用户本机Chrome或小红书。

杭州阿里云部署方案由“大树”负责执行，尚不能在本文宣称已部署完成。当前Sites环境下的修改不会自动同步到阿里云服务器。搬迁须单独迁移代码、账号认证、数据库、R2等价存储、凭据与任务持久化；不能只复制网页文件。

## 4. 用户页面与实际生产节点

文章弹窗的五个页面：①素材与任务书、②文稿与封面、③人工审核、④发布包、⑤结果与日志。它们是操作页面，不等于五个固定模型请求。

默认“自动生产”的实际顺序：

1. 读取任务书、灵感参考、素材和角色设置，检查必要凭据。
2. 内容编辑生成标题、第一人称情境故事、标签、封面短句和内部构思。
3. 家庭关系解析角色补充解析与建议。程序保留故事板块，不允许解析角色重写故事。
4. 内容编辑润色合并后的全文，使故事、解析、建议自然衔接。
5. 本地规则检查，不调用模型。
6. 独立文字审校，检查当前完整文章与引文依据。
7. 若有可返修问题，最多一次文字返修，再独立复查；仍不满足则保留候选和原因。
8. 文字条件满足后，按所选风格设计/生成封面，或执行纯文字本地排版。
9. 审校实际封面和全部正文图片；分批覆盖，按责任返修并复验。
10. 保存/采用任务结果，再由实际授权人员完成专业审核登记。
11. 导出当前已保存版本或已审核发布包，交给下一阶段衔接。

入口有不同语义：

| 用户操作 | 实际行为 |
|---|---|
| 自动生产 | 走上述完整浏览器执行链；有条件、预算与断点 |
| 补充家庭解析 | 已保存正文作为保留内容，补解析/建议并独立文字检查；不生图 |
| 全文润色 | 内容编辑修改完整文章，不等于专业审核或图文复验 |
| 仅重新生成封面 | 保留正文，可能产生一次新的生图用量；现有任务应先查原任务 |
| 修正封面排版（免费，不生图） | 清除旧封面字号/位置/蒙板参数，使用本地词语换行；保存新版本并刷新预览，底图与正文保留 |
| 封面设计／完整预览 | 页面定位入口，本身不是修复或模型调用 |
| 审校并自动返修 | 对当前实际图文检查、分派、有限返修及复验；不自动专业通过 |
| 保存为新版本并更新排版 | 保存当前文字/风格；按既有图片策略判断是否需要生图，不应替代“免费修正排版” |

单独的“AI生成填表”入口在 `app.js` 中直接调用 `LTAI.generate()`；未传operation时，它目前封装故事→解析，结果先填表，不等于默认自动生产的完整润色/检查/图片链路。维护时必须分别验证两个入口，不能只改一个就宣称两者都已更新。

## 5. Agent角色、模型与权限

模型表是源码默认值，**不是声称当前账号的云端设置完全相同**。接手必须在系统设置读取实际配置；不可用代码默认值覆盖用户已保存设置。

| 角色 | 默认模型ID（OpenRouter） | 默认单次输出上限 | 主要任务 |
|---|---|---:|---|
| 内容编辑 writer | `deepseek/deepseek-v4-flash` | 4096 Token | 初稿故事、完整文章润色、按问题返修 |
| 家庭关系解析 analyst | `deepseek/deepseek-v4.1-flash` | 4096 | 从故事解释互动，补亲和、有限度的解析与建议 |
| 美工 designer | `deepseek/deepseek-v4.1-flash` | 1536 | 画面构思、可执行排版参数、必要时重画底图 |
| 审校 reviewer | `deepseek/deepseek-v4.1-flash` | 4096 | 独立文字审校、实际图文检查与复验 |
| 主编 chief | `deepseek/deepseek-v4.1-flash` | 2048 | 可选协调模式，判断责任、工具、顺序和停止理由 |

- `agent-team-core.mjs` 的兼容结构仍是 `roles.writer/designer/reviewer` 加顶层 `chief`、`analyst`；不要把旧三角色schema直接改成五元素数组。
- 每个角色的职责、模型、输出上限、Skill可在右上角“系统设置”编辑，保存在云端Agent设置中。
- 默认协调模式 `rules` 是程序按规则调度；选择 `chief` 才调用主编模型。界面出现主编名字不代表每次都调用了主编。
- 这是“大模型角色＋业务Skill＋应用状态/工具限制”的运行时，不是五个已在远端常驻的独立进程。
- 主编可以分派、暂停，不能跳过独立审校、取消未解决问题、伪造授权审核、突破图片/轮数限制。
- 文字/排版问题不能升级成重画底图；图片修改须有明确画面问题和理由。

## 6. 文风、内容结构与输出契约

内容目标：有温度、亲和、有具体生活细节；以故事启发，避免第二人称训诫、机械转述或整篇空泛金句。参考文章用于理解情绪和表达机制，不固定套用同一框架/措辞。第一人称情境故事不得冒充真实咨询案例或真实咨询师经历。记录的test=false或界面“真实内容”仅表示业务记录，不证明故事是真实个案；原创情境的provenance须单独保留。

完整文章由 `articleParts.story / analysis / actions` 组成；程序统一拼接正文，避免模型重复输出的body与三个板块不一致。解析角色的故事部分由程序从原稿注入。缺少可支撑的重要依据时返回待补材料，不补造研究、诊断或确定性因果。

- 初稿内部构思 `editorialPlan` 包含读者问题、角度、结构、候选标题及选用理由；后续解析/润色沿用，不反复生成标题候选。正式标题不应带“参考：”等内部前缀。
- `reviewNotes`、编辑构思、返修原因、业务提示与专业审核状态是内部信息，不能拼入发布正文。
- 润色差异由程序计算 `editMemo`，不信任模型自报“已经改好了”。无实质变化记录 `NO_REWRITE`，保留正文，不自动重复请求。
- 文本板块长度和结构检查只能证明交付完整，不证明专业正确或读感达到85分。
- 本地规则检查、AI文字检查、图文视觉复验、人工专业审核是四类不同记录，不能互相冒充。

专项标准：[VOICE_STYLE.md](VOICE_STYLE.md)、[NARRATIVE_EDITOR_GUIDE.md](NARRATIVE_EDITOR_GUIDE.md)、[FAMILY_RELATION_ANALYST.md](FAMILY_RELATION_ANALYST.md)、[INSPIRATION_WRITING.md](INSPIRATION_WRITING.md)。

## 7. 任务状态、预算与断点

`jobs.js` 当前最多并行3项；同一篇文章不同时执行两个任务。任务快照、候选、诊断、外部任务号都应保留。

| 状态 | 含义 |
|---|---|
| queued / running / stopping | 排队／执行／停止本机后续步骤中 |
| paused / interrupted / failed | 暂停／需要核对后继续／失败；不能标成完成 |
| ready | 候选完成但尚未采用；文章变化时不静默覆盖 |
| completed | 结果已保存/采用，仍可能存在当前问题；不等于质量验收或专业审核通过 |

文字断点包括 `family_analysis`、`text_polish`、`text_review`、`text_repair`、`text_recheck`。恢复前核对输入、版本、设置修订及原检查报告；不具备复用条件时应停止，不能悄悄从头重新收费。

默认新稿文字部分通常至少4次模型请求；若发生一次返修和复验则增加2次。美工构思、图片、视觉分批检查及主编协调另外计费，不能把“生成一篇”描述成一次固定调用。

图文循环最多2轮返修、最多新增2张封面。每批检查最多2页，每页最多3项反馈，完成一批就保存 `visualReviewPending`；若中断，续查未完成的批次。正常一轮1—8张成图对应1—4批视觉请求，不等于整轮免费。

相同问题集合返修后仍出现则记录 `no_progress` 并停下；不为制造变化继续返修。相同有效问题复用ID，当前问题和历史观察分开；只有明确复验通过的页才能将相应旧问题标为关闭。未再次列出的旧问题可记历史，不能自动声称已解决。

进行中的相同任务复用；用户明确再次发起已结束的审校可产生新请求。点击前应显示计费边界，不能把旧的completed任务假装新执行。

## 8. 封面、排版与图片服务

三种当前可选风格：留白极简文字、简约高级摄影、日光叙事插画。插画风不是每篇都默认母子，人物关系须来自内容。

- `cover.js`：标题几何与中文词边界；新旧模板统一避免“道理”等词内断行。生成图上不再叠加矩形蒙板。
- `layout.js`：900×1200 Canvas正文分页、纸张细纹与边框、分页导出；按剩余空间分段，避免为保整段而留下大空白。
- 字体：`assets/fonts/lifetree-serif-sc-600.woff2`。测试/截图缺字体会出现方框，不能据此验收中文字形。
- `image-provider.js`：按文章的 `topic/title/body/cover/style` 生成 `contentKey`，保留外部任务号，查询、下载、规范化并保存图片。
- 排版问题走 `designer/layout`；只有明确底图错误且 `imageChangeRequired=true`、`imageReason` 非空才允许 `regenerate`。主编不能把原文字/排版问题升级为生图。
- 图文循环的文字修订可以显式保留原底图并记录 `reuseDecision`，随后必须检查实际图文匹配；不能因为contentKey变了就隐式付费重画。
- 调整任一已保存图文后，原专业审核不可继续沿用。

MXAI当前适配：`https://mcp.mxai.cn/sse`，初始化后调用 `get_user_info / generate_image / get_task_status`。供应商任务号不同于本站任务ID。使用 `mxai-cn` 的Key不能擅自发给旧 `mxapi` 端点。旧任务继续查询要保持原provider。

错误522在SSE建立阶段表示上游连接超时；应看 `mcpPhase`、`upstreamStatus`、`toolMayHaveRun`，不能一律说Key失效。已取得任务号先查原任务；提交结果不明不得自动重提。下载失败与模型生成失败分别记录。已生成结果可通过回执取回，避免重复查询或付费生图。

## 9. 三种版本号与同步防护

| 标记 | 实际含义 | 禁止误解 |
|---|---|---|
| 文章V6/V8 | 同一文章的保存版本号 | V2不固定等于解析，V3不固定等于审校 |
| 云端R号 | 整个工作区快照的数据库修订 | 新R号可能装着旧文章，不能据R号覆盖高V号文章 |
| Sites版本81 | 应用代码发布版本 | 不代表用户文章版本或数据库修订 |

`sync.js` 的正常保存约900ms排队上传；网络与服务器处理时间另外计算。可见且适合同步的页面约45秒检查一次，回到页面也会核对；有未保存输入/本机执行任务/其他编辑弹窗时可能暂停替换。不能宣传所有设备已做到强实时协同。

当前采用“本机快照＋云端快照＋revision CAS”：

1. 服务端按登录用户隔离，POST带 `expectedRevision`、`operationId`，防并发写入和重试重复。
2. 同ID文章写入版本低于云端版本时，返回409及 `ARTICLE_VERSION_DOWNGRADE`，即使工作区R号正确也拒绝。
3. 云端读取若会把本机较高V号替换为较低V号，则拦截并保留本机；手动“读取云端”也不能绕过。
4. “上传本机较新文章”重新获取最新R，只替换严格较高的文章行，保留云端其他文章和素材；其他本机差异不擅自合并。
5. 打开的干净文章在载入云端后按ID重新绑定，正文、版本和对照一起重绘；有未保存输入则保留并提示冲突。

**尚未解决的同步边界：** 同一文章的两个独立分支可能产生相同V号、不同正文；当前防降版只拦截更低V号，不会据此自动判断同V号内容是否冲突。仅靠V号不能可靠判定谁更优。当前没有逐段合并、CRDT或全面逐篇事务保存。后续必须保留基准修订与内容指纹，冲突时不能简单按时间戳或数字更大者全部覆盖。删除/恢复与缺失文章的合并语义也须单独设计。

## 10. 数据恢复与备份

源码和Sites版本备份不等于业务数据备份。回滚代码不会自动恢复用户正文、图片、浏览器数据或Key。

本机键：

| 键 | 用途 |
|---|---|
| `lifetree-ops-v01` | 本机文章/任务记录 |
| `lifetree-materials-v1` | 本机素材 |
| `lifetree-cloud-sync-v1` | 用户、R号、baseHash元数据 |
| `lifetree-before-cloud-v1` | 原同步前备份，当前不反复覆盖 |
| `lifetree-before-cloud-latest-v1` | 最近一次同步前备份 |

恢复入口：内容工作台→打开文章→“2.文稿与封面”→弹窗内顶部→展开“同步版本恢复 · 查找本篇同步前备份（免费）”→“查找本机备份及云端历史”。候选版本展开后，正文底部有“恢复此内容为新草稿并同步云端”。

优先在曾保存较高版本的设备查本机备份。工具还读取本篇文章的历史及任务候选，并通过登录账号查询最近20个云端快照中这篇文章的恢复字段，不返回其他文章/素材。

用户先核对候选正文，再选择恢复。恢复V8内容时会新保存为至少V9，保留原版本、清除旧专业审核，随后按最新R同步；不直接将系统降版。候选任务稿不等于已采用成稿，必须注明来源。

恢复入口存在不等于数据一定找得回。备份被清除、旧版本从未上传、历史已超出保留窗口时，必须如实说明；不能用重新生成的近似文章冒充原V8。当前没有为本次交接另行导出真实业务数据库或用户文章。

## 11. 凭据与模型设置

- 文章与Agent设置会云同步；文字API Key目前仍由各浏览器独立保管，**不会随文章跨设备同步**。
- `ai.js` 按平台隔离模型配置及口令加密密文；`device-keys.js` 用IndexedDB中的不可导出CryptoKey保存本机记住能力。
- `KEY_MISSING_THIS_BROWSER`：当前浏览器无记录；`KEY_LOCKED`：有密文但未解锁；`KEY_RESTORE_FAILED`：读取失败。不能把它们统称Key无效。
- 新设备要安全配置一次文字平台Key并记住本机；已有记录用原口令解锁或重新读取，不反复要求换Key。
- MXAI图片Key和OpenRouter文字Key是不同凭据。服务器图片凭据有owner邮箱约束，不能任意账号共用。
- 可用的运行时变量名：`MXAI_API_KEY`、`MXAI_API_OWNER_EMAIL`；可选远端执行代理需要 `EDITOR_AGENT_URL`、`EDITOR_AGENT_TOKEN`。本文不提供任何值。
- `LT_MODEL_SETUP_TOKEN` 对应历史受控维护端点，不是普通登录凭据。未配置时不可用；不要为日常修复随意启用或写入仓库。
- Sites服务访问令牌只代表平台访问边界，不等于已登录访客身份。不能伪造身份头来读用户数据。

跨设备统一文字凭据与后台持久执行尚未落地。不能只加一个云端Key表就宣布完成：还需要账号隔离、服务端加密与轮换、用途授权、审计、预算、固定provider转发、回读诊断，且不得把密钥混入普通备份/日志/角色Skill。

## 12. 数据表与接口速查

D1已有表：`workspaces`、`workspace_revisions`、`sync_events`、`system_checks`、`inspiration_items`、`editorial_runs`、`agent_settings`、`agent_settings_history`、`model_diagnostics`。

| 接口 | 职责及关键条件 |
|---|---|
| `/api/workspace` GET/POST | 当前账号工作区读取/保存；CAS、幂等、4MB请求限制、密钥字段拒绝、文章防降版 |
| `/api/workspace?recoverRecord=文章ID` GET | 当前账号本篇的最近云端历史候选；限定恢复字段 |
| `/api/agent-settings` GET/POST | 角色/模型/Skill/协调模式，单独修订与冲突保护；不含Key |
| `/api/cover` GET/POST | 图片连接状态、余额/提交/查询/下载；不能把技术探针当实际生图验收 |
| `/api/cover-assets` GET/POST | 登录用户的R2图片存取 |
| `/api/model-diagnostics` GET/POST | 请求阶段、模型、Token、结束原因、错误诊断；不是完整模型响应备份 |
| `/api/diagnostics` GET/POST | 工作区同步等摘要事件，不保存文章正文或Key |
| `/api/inspiration` GET/POST | 灵感池与更新日志；按专项updater访问/并发/匿名化要求执行 |
| `/api/editor-agent` | 可选远端服务代理；未配置独立服务时不能接收云端后台任务 |
| `/api/system-check` | 数据库/图片传输等技术探针；不能代替专业、业务或生图全链路验收 |
| `/api/agent-model-setup` POST | 受临时维护凭据限制的维护接口，不应当作普通业务入口 |

`drizzle/0000_cloud_sync.sql` 建立基础同步表；`0001`为灵感表，`0002`为Agent设置，`0003`为模型诊断。不要仅凭文件名自动重复执行生产迁移；先核对已应用迁移。维护中优先使用受支持数据库查看器，不发未经审查的任意SQL。

## 13. 关键文件定位

| 改什么 | 从哪里读起 |
|---|---|
| 页面、当前文章引用、表单未保存保护 | `public/app.js`、`public/style.css`、`public/editor-tidy.js` |
| 文章保存/历史/审核/发布包 | `public/core.js`、`public/review-ui.js` |
| 灵感→选题参考 | `public/inspiration-writing.js`、`public/production.js`、`public/inspiration-ui.js` |
| 历史资料/专业素材导入 | `public/archive*.js`、`public/material-import.js`、`public/materials.js` |
| 默认自动生产顺序 | `public/auto-production.js` |
| 提示词、文风、结构、编辑差异 | `public/voice.js`、`public/writing.js`、`public/quality.js`、`public/ai.js` |
| Agent角色/Skill/模型设置 | `public/agent-team-core.mjs`、`public/agent-team-ui.mjs`、`server/agent-settings-core.mjs` |
| 队列、重复任务、候选采用、续接 | `public/jobs.js` |
| 图文循环/主编分派/问题账本 | `public/editorial-loop.mjs`、`public/chief-coordinator.mjs`、`public/issue-ledger.js` |
| 视觉协议、分批、矛盾报告 | `public/visual-review-core.mjs`、`public/agent-visual-review.mjs` |
| 封面标题与正文分页 | `public/cover.js`、`public/layout.js` |
| 逐篇图片任务与错误阶段 | `public/image-provider.js`、`public/image-ui.js`、`server/cover-core.mjs`、`server/mxai-mcp.mjs` |
| 跨设备同步与恢复 | `public/sync.js`、`public/sync-recovery.js`、`server/sync-core.mjs` |
| 凭据恢复/平台端点 | `public/ai.js`、`public/device-keys.js`、`public/settings.js` |
| 诊断及隐私边界 | `public/model-diagnostics.js`、`server/model-diagnostics-core.mjs` |
| 未来独立执行服务 | `cloud-agent/README.md`、`cloud-agent/service.mjs`、`cloud-agent/engine.mjs`；须先做与当前链路的差距核对 |

## 14. 故障处理：先定位，不让用户反复整篇重跑

| 现象 | 先查 | 处理边界 |
|---|---|---|
| V6覆盖V8／两端不同版 | 文章ID、文章V、云端R、各端同步状态、同步前备份 | 先停写入、导出/找回；不要先读旧云端或清缓存 |
| 当前版本没变，候选V更高 | 任务status、work.version、是否ready/failed、fingerprint变化 | 候选未采用不等于丢失；不得强制覆盖新编辑 |
| 文字Key未配置 | 实际角色provider、本机saved/unlocked、错误码 | 先“检查本机文字Key”；不能要求用MXAI Key代替文字Key |
| HTTP403模型不可用 | provider原始安全错误投影、模型ID、地区/额度 | 保留任务，核对服务商；不能只换Key或反复重试 |
| OUTPUT_TRUNCATED | 输出上限、actual tokens、finish_reason、阶段 | 截断响应不能当有效JSON；图文分批续接，不重新起草 |
| 审校pass却列问题 | normalizationNotes / PASS_WITH_ISSUES | 保守转change、保留问题，不升级为通过 |
| 引文与原文不符 | 当前全文、quoteBank、字段及签名 | 必须真实包含；不能放松成“意思差不多就通过” |
| 解析改动故事／正文与板块不一致 | articleParts、程序拼接、storyText | 统一生成正文；不删除解析环节来消除报错 |
| 问题从9项累计到34项 | 当前报告与历史观察、账本schema | 只统计当前有效集合；历史保留，不凭数字变小声称已修好 |
| 标题断词、字体太小、蒙板 | cover.js、旧designAdjust、本地排版入口 | 免费本地修正；不重画底图、不整篇重跑 |
| MXAI522／下载失败 | submit/poll/download、mcpPhase、外部任务号 | 区分连接、生成、取回、保存；不自动重复提交未知任务 |

每次报告至少说明：文章ID/版本、任务ID/attempt/stage、失败码、是否已发请求、是否可能计费、保存/候选/原图是否保留，以及继续原阶段还是明确另起任务。不要在日志中存Key、口令、原始身份头或咨询隐私。

## 15. 验证清单与证据等级

本阶段已执行的隔离检查包括下列测试；它们证明控制逻辑和数据保护，不是实际服务商持续可用或读者质量验收。

| 范围 | 代表测试 |
|---|---|
| 同步、旧版保护、恢复 | `tests/sync-ui.cjs`、`tests/sync-downgrade.cjs`、`tests/cloud-sync.mjs` |
| 文本阶段/续接 | `tests/automatic-polish.cjs`、`tests/repair-resume.cjs`、`tests/analyst-resume.cjs`、`tests/analysis-task.cjs` |
| 正文/构思/编辑差异 | `tests/carried-editorial-plan.cjs`、`tests/program-edit-audit.cjs`、`tests/visual-verdict.cjs` |
| 审校/图文账本 | `tests/mixed-repair.mjs`、`tests/repair-image-routing.mjs`、`tests/issue-ledger.mjs`、`tests/visual-batches.mjs` |
| 实际本地排版 | `tests/template-word-wrap.cjs`、`tests/local-cover-repair.cjs`、`tests/no-cover-panel.cjs`、`tests/flow-pagination.cjs` |
| 凭据与任务展示 | `tests/credential-errors.cjs`、`tests/pending-work-ui.cjs`、`tests/live-queue-ui.cjs` |
| MXAI协议 | `tests/mxai-mcp.mjs` |

CJS页面测试需要 `jsdom`、`fake-indexeddb`、`@napi-rs/canvas`。它们是测试依赖，可在独立QA目录安装，通过 `NODE_PATH` 指向该目录；不要为了跑测试改坏生产依赖锁文件。中文字形测试要注册项目字体。Node须支持 `node:sqlite`，当前工程要求至少22.13。

建议接手先跑与改动对应的最小集合，例如：

```bash
node --test tests/cloud-sync.mjs tests/issue-ledger.mjs tests/visual-batches.mjs
NODE_PATH=/你的QA目录/node_modules node tests/sync-ui.cjs
NODE_PATH=/你的QA目录/node_modules node tests/sync-downgrade.cjs
NODE_PATH=/你的QA目录/node_modules node tests/local-cover-repair.cjs
node tests/credential-errors.cjs
```

存在历史测试，其旧默认流程或字段预期已过时；未在本文承诺整个tests目录全绿。不要通过删除语义断言让旧测试“好看”。

证据分层：BOSS已完成流程试用并决定阶段收口；模型调用和部分图片生成曾经实际成功；上述控制回归已通过。**尚无持续新样本的85分质量签署，也没有所有角色、图片、跨设备同步、草稿箱在一次真实后台运行中全部验收的记录。** 本次文档整理不触发付费模型，不读取/导出业务正文。

## 16. 维护发布与回滚步骤

### Sites现有站点维护

1. 读取 `.openai/hosting.json`，复用现有project ID，不能重建另一个站点冒充更新。
2. 通过Sites读取当前权限、已保存版本和源码凭据；按当前Sites技能的source helper打开最新仓库。
3. 先核对Git状态及最新提交；只修改相关 `public/`、`app/`、`server/`、`docs/` 源码，保留用户凭据及数据。
4. 文档变更同步到 `docs/` 与必要的 `public/` 镜像；执行相关检查及构建。常用构建助手为当前Sites插件的 `scripts/build-site.mjs`，不要手改dist。
5. source helper提交、推送并打包同一源码状态。保存时使用其返回的精确commit_sha与archive。
6. owner-private站点使用 `save_version_and_deploy_private`；只对非终态部署查询状态，成功后记录版本和部署ID。
7. 如果失败结果已有saved_version_id，继续部署该版本，不重复保存新的不明版本。
8. 交接中明确：改了什么、测试了什么、哪些没有实测。发布成功不等于用户内容质量已经验收。

### 回滚

- 先停止新任务、确认无未保存表单，导出当前业务数据与图片备份，记录当前应用/文章/云端R号。
- 只回滚应用代码时优先使用本文第81号保存版本；不要复制旧本地镜像覆盖线上。
- **Sites代码回滚不回滚D1/R2/浏览器缓存/Key/登录状态。** 数据恢复用已确认的记录备份或本篇历史，不还原整库覆盖所有用户。
- 生产若已出现新schema或安全修复，先核对兼容性；不能为了UI问题回到会发生V8→V6覆盖的版本。
- 回滚后核对权限、读写、同步防降版、原图引用及任务重复保护；未经授权不迁移真实业务或发布文章。

## 17. 第二阶段交接合同：小红书草稿箱

下一阶段第一轮以已保存且已审核的版本为输入，先验证一个明确账号、一次单篇草稿保存及重新打开；未审稿进入外部草稿箱须另行明确授权与策略，不能借草稿接收取消专业审核。先完成受支持方式的能力调查，再决定官方接口或经用户授权的本机浏览器方案。**当前未验证小红书官方API是否支持这个操作，不应把平台登录成功当草稿保存成功。**

第一阶段应交给第二阶段的不可变交付物：

| 字段 | 要求 |
|---|---|
| articleId / articleVersion | 精确指定已保存文章，不能读取“此刻表单上的最新值”替代 |
| title / body / tags | 可发布内容，不含内部构思、系统提示或审校日志 |
| images | 封面＋正文有序图片；900×1200，文件可读取 |
| approval | 明确该版本的专业审核记录；草稿接收策略与发布放行策略分别定义 |
| manifest / hashes | 记录图片顺序、内容及配置指纹，防止旧封面或跨版本混搭 |
| task / account / channel | 单独的草稿衔接任务及明确目标账号，不与内容生产任务混用 |

衔接幂等建议由 `articleId + articleVersion + channel + accountId + packageHash` 形成；已在执行/已保存时不重复递交。若只保存草稿，不得误点发布。完成的判据是目标账号草稿存在、可重新打开且图文顺序/正文与交付包一致，并留下回执；本机ZIP下载或页面提示成功均不足以替代回读。

分发状态应另设 `queued / transferring / draft_saved / needs_attention / published` 等域，不能复用“人工审核通过”表示“已发到小红书”。第三阶段再处理多账号切换、渠道分发、发布结果及运行管理，范围以BOSS后续确认为准。

## 18. 未完成事项与下一次修改纪律

| 优先级 | 未完成/持续项 | 不可混淆的验收条件 |
|---|---|---|
| P0 | 真正后台持久执行 | 关闭全部客户端后任务继续、换设备可查询；当前未部署 |
| P0 | 文字凭据服务端统一保管 | 换设备不重填、严格账号隔离、无明文泄漏、可轮换；当前仍本机Key |
| P0 | 同步同V分支/逐篇保存进一步改造 | 不能用相同V号覆盖另一份不同正文；当前主要是快照CAS＋防降版保护 |
| P1 | 稳定内容质量与家庭解析校准 | 真实新样本逐篇读感/准确性/实用性复核；结构完整不等于85分 |
| P1 | 设计审校一致性、预算与错误恢复 | 针对问题收敛，不制造主观返修、不以重跑冒充修复 |
| 下一阶段 | 小红书草稿箱保存/回读 | 指定账号、指定版本、幂等、安全保存草稿并重新打开 |

修改纪律：先复现、确定责任模块与实际执行位置，再补最小实现和有意义的回归。错误/疑似计费任务先保存原阶段与回执，勿自动从头重跑。不能为消除报错而取消专业解析、降低引文校验、删除历史备份或把“仍需处理”标成通过。

维护者更新这份手册时，同时更新机器基线、变更摘要、对应测试与实际部署证据；未验证项继续明示。功能第一阶段可以收口，已知技术边界必须随文档一起传递。