@deployxai/dxc 0.1.0

package/docs/02-mvp-technical-design.md

@@ -0,0 +1,553 @@
+# MVP 技术方案
+
+更新日期：2026-07-30
+状态：架构基线；九个官方 Skill、跨会话自动续跑、本地内容记忆、身份、公众号绑定、
+通用云端预览和草稿回读闭环已实现；生产版本以发布后的健康检查和真实首位用户验收为
+准。显式本地正文图片、素材目录采集和 Agent 宿主视觉生产已经进入工作流；CLI 不内置
+生成服务或占位封面。权益和支付未实现。
+
+## 1. 目标与非目标
+
+### 1.1 唯一纵向闭环
+
+1. 用户在 WorkBuddy 安装 `dxc-content-workflow` 和 `dxc` CLI；自然语言隐式触发总控后，
+   总控从本地项目 contract 恢复并自动调用下游 Skill，最后交付步骤调用
+   `dxc-wechat-publisher`。
+2. CLI 完成环境检查，并创建短时设备绑定会话。
+3. 用户通过微信第三方平台官方页面扫码授权公众号。
+4. 用户在 Agent 中给出主题、参考材料或已有 Markdown；初始化同时展示本地知识库
+   状态并允许显式导入历史文章，总控自动推进研究、Brief、大纲、正文、标题、视觉生产
+   和审校。
+5. Agent 生成或选择实际内容封面和必要正文图片，CLI 只收集、校验和上传用户明确指定
+   的本地文件。
+6. 云端按已发布模板目录进行权威渲染、清洗和预检。
+7. Agent 在宿主右侧内置浏览器打开云端手机样式预览。
+8. 用户回到 Agent 明确确认目标公众号和当前快照。
+9. 云端检查订阅/额度；无权益时通过 WorkBuddy SkillPay 完成购买。
+10. Worker 上传正文图片和封面，创建微信草稿并回读核验。
+11. Agent 展示结果，CLI 保存本地结果，云端保留审计和可重试错误。
+
+### 1.2 明确不做
+
+- 自动扫描用户目录、云端研究抓取或 DxC 内置的第三方图片生成服务；
+- 通用 Agent 框架；
+- 知乎、头条、小红书等平台；
+- 正式发布、群发、粉丝和消息能力；
+- 模板商城、用户自定义 CSS 或模板管理界面；
+- 完整 Web 内容编辑器或管理后台；
+- 自动续费；
+- MCP；
+- Redis 或独立队列服务；
+- 扫描 PDF 的云端 OCR。
+
+## 2. 技术选型
+
+| 层 | MVP 选型 | 原因 |
+|---|---|---|
+| Monorepo | pnpm workspace | 单仓库共享契约，单人迭代成本低 |
+| 语言 | TypeScript strict | CLI、API、Worker 和共享契约统一 |
+| Node | Node.js 24 LTS | 当前 LTS，覆盖 macOS/Windows/服务器 |
+| CLI | Commander + 原生 `fetch` | 依赖少、跨平台、易输出 JSON |
+| 本地内容记忆 | `node:sqlite` + FTS5 + Tokenizers.js + ONNX Runtime Web/WASM | 用户文章留在本机，兼顾字面和中文语义召回；避免安装多平台原生推理包 |
+| API | Fastify | 启动轻、Schema/插件边界清晰 |
+| 运行时校验 | Zod | CLI/API/配置/事件统一校验 |
+| Mongo | 官方 MongoDB Node Driver | 避免 ODM 隐式行为，显式索引和状态更新 |
+| Markdown | `marked` + 自定义 token renderer | 与旧工具接近，便于建立行为兼容 |
+| HTML 清洗 | `sanitize-html` + 二次约束检查 | 使用明确 allowlist，避免字符串替换成为安全边界 |
+| 测试 | Vitest | TypeScript 单元、契约和黄金样例统一 |
+| 日志 | Pino JSON + 脱敏配置 | 结构化、Fastify 原生友好 |
+| 对象存储 | S3-compatible adapter | 供应商可替换，MVP 不把 URL 写死 |
+
+首版不引入前端框架。预览页由 API 服务输出一个最小 HTML 外壳，将经过清洗的文章 HTML 放入固定手机阅读容器。出现真实管理后台需求后，再单独选择前端方案。
+
+## 3. 仓库和组件
+
+```text
+apps/
+  cli/
+    src/
+  server/
+    src/
+  worker/
+    src/
+skills/
+  dxc-content-workflow/
+    SKILL.md
+    agents/
+    references/
+  dxc-title-write/
+  dxc-wechat-publisher/
+packages/
+  contracts/
+  config/
+  security/
+  renderer-wechat/
+  workflow-state/
+  wechat-client/
+  billing/
+  object-storage/
+fixtures/
+  renderer/
+  wechat/
+docs/
+```
+
+### 3.1 CLI
+
+CLI 不持有微信第三方平台密钥或 authorizer token。
+
+职责：
+
+- `doctor`：检查 Node、网络、版本、可写目录和可选工具；
+- `profile`：校验并保存版本化本地创作偏好；
+- `project`：初始化固定八步内容项目，以轻量本地索引跨会话定位项目，并通过包含
+  `inputs`、`outputs`、`metadata`、`waitingFor` 和结构化确认绑定的 v3 checkpoint
+  恢复进度；
+- `knowledge`：显式导入历史文章并执行本地关键词/语义混合召回；
+- `setup`：复用已有状态，顺序完成个人微信登录/明确注册和公众号绑定；
+- `auth`：显式首次注册、关联个人微信、登录、续期和管理 DxC 设备会话；
+- `wechat connect/accounts`：发起授权和查询账号；
+- `wechat draft preview/preview-refresh/create/status`：本地预检和显式素材采集；
+  上传正文、正文图片和封面；为 Agent 内置浏览器提供云端预览；提交不可变确认并查询
+  用户可理解的处理进展；
+- `skills install`：把九个受控官方 Skill 安装到 WorkBuddy、Codex 或显式目录；
+- 将机器结果写到 stdout JSON，将人类提示写到 stderr。
+
+本地只进行廉价且稳定的检查，例如阶段 frontmatter、固定 Skill 版本、输入哈希、图片
+真实性与体积、文章包和显而易见的摘要长度。最终微信兼容判定必须来自云端权威渲染。
+
+本地知识库是例外的纯本机能力：SQLite 保存文章分段、哈希和向量，固定 revision 的小型中文嵌入模型计算语义相似度，RRF 合并关键词与语义排名。它不决定发布合规，也不把历史全文上传云端。总控和各步骤边界见 [ADR-0005](decisions/0005-official-skill-orchestration-and-local-content-memory.md)。
+
+`dxc-content-workflow` 是唯一允许隐式调用的官方 Skill。每次调用先解析当前目录或项目
+标题，再以实际产物和 checkpoint 为真值循环推进。普通内部阶段完成后自动进入下一步；
+只有会改变路线的用户输入、最终内容选择、公众号选择、不可变快照确认或不可安全恢复
+错误才暂停。CLI 只提供确定性的状态、哈希和项目定位，不引入后台工作流引擎。
+
+### 3.2 Server
+
+一个 Fastify 服务承载：
+
+- 健康和配置就绪检查；
+- 设备会话和短时绑定；
+- 独立的网站应用微信登录、个人身份关联和新设备恢复；
+- 微信第三方平台授权发起、回调和授权事件；
+- 文章上传会话、权威渲染和预检；
+- 短时预览；
+- 目标账号、确认和草稿意图；
+- 权益、购买意图、SkillPay X402 和微信支付通知；
+- 查询任务和结果；
+- 管理性接口只在内部网络或强认证下开放。
+
+MVP 可以使用同一个 OCI 镜像，通过不同入口启动 Server 和 Worker。
+
+### 3.3 Worker
+
+Worker 领取 Mongo 中的租约任务：
+
+- 刷新/获取 authorizer access token；
+- 上传正文图片；
+- 上传或复用永久封面素材；
+- 替换正文图片 URL；
+- 执行最终 HTML 约束检查；
+- 调用 `draft/add`；
+- 调用 `draft/get` 回读；
+- 对可安全重试的错误退避；
+- 写入审计和最终结果。
+
+Worker 是唯一允许执行微信草稿副作用的组件。
+
+当前 Worker 保留 2026-07-26 固定测试意图兼容路径，并优先领取通用文章意图。通用路径
+从对象存储读取不可变 HTML、正文图片和封面，复核清单哈希、租户、公众号状态及 ID 11，
+上传或复用封面、逐张上传正文图片并替换逻辑 URL，只调用一次 `draft/add`，随后
+`draft/get` 回读。它仍由配置锁定一个首位用户租户，尚未成为带 heartbeat（心跳）的
+通用多租户 Job 租约系统。
+
+## 4. 身份、租户与公众号绑定
+
+### 4.1 MVP 身份
+
+MVP 不建设密码系统，但把用户登录和公众号授权明确拆开：
+
+1. 推荐首次运行 `dxc setup`：CLI 先完成设备持钥证明，再用个人微信 `start` 登录已有
+   owner，或在文案明确的首次流程中创建新 owner/tenant；
+2. 随后第三方平台管理员扫码把公众号绑定到当前租户；公众号授权不能创建或接管另一
+   个已有 owner；
+3. 新设备可以执行 `dxc auth start` 恢复已关联身份；严格的 `dxc auth login` 仍只接受
+   已关联身份，未关联时固定失败；
+4. 旧公众号 bootstrap 创建的 owner 仍可执行 `dxc auth link-wechat` 完成迁移；
+5. 同一未关联个人微信的并发 `start` 使用确定性候选 owner 和 Mongo 原子 bootstrap
+   收敛，不留下第二个随机租户；
+6. 个人登录只使用 `snsapi_login`，不保存微信 OAuth access/refresh token，只保存按
+   Website AppID 作用域派生的 openid/unionid 摘要；
+7. 设备访问 Token 有效 24 小时，30 天设备刷新凭据配合 Ed25519 签名完成单次轮换和
+   同一 `rotationId` 重放恢复。
+
+固定网站登录入口为 `https://content.deployxai.com/auth/wechat/login`，回调为
+`https://content.deployxai.com/callbacks/wechat/login`。它们不复用第三方平台事件/
+消息回调或 Component AppID/AppSecret。详细决策见
+[ADR-0006](decisions/0006-separate-wechat-user-login-from-account-authorization.md) 和
+[ADR-0007](decisions/0007-explicit-personal-wechat-start.md)。
+
+设备长期秘密优先保存在系统凭据存储中。当前 CLI 退化为用户目录中仅当前用户可读的 `0600` 文件，并明确提示风险；迁移到系统钥匙串不改变协议。团队、邮箱/手机/OIDC 和设备管理界面后续按真实需求增加。
+
+### 4.2 租户
+
+- 一个租户代表一个 DxC 内容空间，而不是固定等于一个公众号。
+- 一个租户可以授权多个公众号。
+- 一个公众号授权在同一时间只能归属一个有效租户绑定。
+- 所有业务集合都带 `tenantId`。
+- 设备、用户、公众号和支付身份通过显式关联表连接，不依赖 Agent 对话文本。
+
+## 5. 微信第三方平台链路
+
+### 5.1 权限
+
+MVP 只依赖：
+
+- ID 3：公众号账号信息服务；
+- ID 11：素材管理和草稿所需能力。
+
+ID 7 不进入授权请求和代码路径。
+
+### 5.2 票据和令牌
+
+```text
+component_verify_ticket
+  → component_access_token
+  → pre_auth_code
+  → authorization_code
+  → authorizer_refresh_token
+  → authorizer_access_token
+```
+
+实现规则：
+
+- 授权事件回调先验证 `msg_signature`、时间戳、nonce、解密结果 AppID 和重放窗口；
+- 保存最近有效的 component ticket，不记录明文日志；
+- component access token 和 authorizer access token 使用“提前刷新 + 单飞锁”；
+- authorizer refresh token 加密持久化；
+- 收到取消授权事件后立即标记 revoked，停止新任务并撤销本地会话访问；
+- 已进入微信副作用阶段的任务根据状态安全终止或核验，不能继续使用已撤销授权；
+- 微信调用通过授权账号自己的 authorizer token 完成，不使用客户 AppSecret。
+
+### 5.3 固定出口
+
+所有微信素材和草稿 API 从受控 Worker 出口发起。2026-07-26 已确认当前阶段 Server 位于 `alivps`，Worker 位于 `worker_vps`；Worker 通过只允许 `api.weixin.qq.com:443` 的私网 CONNECT 代理复用 `alivps` 固定出口。代理不缓存、不解密 TLS，且不把微信副作用转交给 Server。
+
+后续可以新增应用 ECS 并将 PM2/Node 从 `alivps` 迁走，但这是独立迁移阶段。当前生产 ECS 禁止依赖安装、TypeScript 编译、测试或镜像构建，只运行本地或 CI 已构建且完成哈希校验的产物。详细决策见 [ADR 0003](decisions/0003-staged-production-topology.md)。
+
+### 5.4 微信 API 加密与签名
+
+第三方平台开启“全部 API 加密及签名校验”时，Worker 必须遵循微信 API 安全协议：
+
+- 第三方平台管理接口 `api_component_token`、`api_create_preauthcode`、`api_query_auth`、`api_get_authorizer_info` 和 `api_authorizer_token` 按各自官方契约发送普通 HTTPS JSON，不添加 `Wechatmp-*` 请求头，也不要求响应提供安全协议签名头；
+- 支持 API 安全协议的公众号 JSON 接口先加入微信要求的安全字段，用 AES-256-GCM 加密正文，再用应用 RSA 私钥按 RSA-SHA256-PSS 签名；安全字段、AAD 和签名身份统一使用第三方平台 Component AppID，即使 query 中携带的是 authorizer access token；
+- RSA-PSS 使用 SHA-256 和 32 字节 salt（盐值）；JSON API 的签名覆盖不含 query 的完整 URL、Component AppID、时间戳和最终请求原文；
+- RSA 请求只发送 `Wechatmp-AppId`、`Wechatmp-TimeStamp` 和 `Wechatmp-Signature` 三个安全请求头，不发送 `Wechatmp-Serial`；
+- 收到响应后先按平台证书序列号选择证书并验证签名，验证成功后才解密和信任响应正文；
+- 资源上传使用普通 HTTPS `multipart/form-data`，不添加 `Wechatmp-*` 请求头。微信明确
+  说明资源上传类 API 不支持正文加密；真实平台已验证永久封面
+  `material/add_material`，正文图片 `media/uploadimg` 则已按 2026-07-30 官方契约完成
+  假服务测试、尚待真实公众号验证。该例外只适用于这两个明确列出的资源上传端点；
+- 任何私钥、对称密钥、序列号和证书路径只从安全环境配置读取，不进入数据库、日志或 Git。
+
+2026-07-26 在已开启“全部 API 加密及签名校验”的真实第三方平台上核验：`api_component_token` 对加密信封返回普通 JSON 且不带 `Wechatmp-*` 响应头，证明不能把 API 安全协议强制套到未声明支持的管理接口。另以同一 authorizer access token 探测 `batchget_material`：使用 authorizer AppID 签名时收到无安全响应头的明文 `40237`，改用 Component AppID 后收到可验签、可解密的成功响应。对 `material/add_material` 使用必定无效的空文件、零填充文件和截断 PNG 探测时，完整含零字节正文签名返回 `40234`，首个零字节之前的 multipart 前缀签名通过安全层后返回 `40097`；同一截断 PNG 完全不带 `Wechatmp-*` 时返回更具体的 `40113` 文件类型错误，证明普通 multipart 能被业务端正确解析。两次真实有效 PNG 的签名上传也都返回 `40097`，随后 `batchget_material` 的素材总数仍为 165、同名新增为 0。因此代码按端点显式选择传输协议：所有安全模式请求统一使用 Component AppID，不能按 access token 类型改变签名身份；`material/add_material` 则使用普通 HTTPS multipart。应用非对称密钥编号保留为本地受控配置，不进入 RSA 请求头；响应 `Wechatmp-Serial` 仍用于选择微信平台证书。对于安全模式端点完全缺少安全响应头的明文 `40230`–`40240`，客户端只保留错误码并将其视为确定性未执行；其他无签名整数错误码只作为不可验证诊断后缀保留，不驱动状态或重试。无签名成功或非 JSON 响应仍不可验证。API 安全材料仍不同于第三方平台事件回调的 Token/EncodingAESKey；两条协议不能混用。官方来源：
+
+- [API 签名加密指南](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/getting_started/api_signature.html)
+- [新增永久素材](https://developers.weixin.qq.com/doc/service/api/material/permanent/api_addmaterial)
+- [上传图文消息内图片](https://developers.weixin.qq.com/doc/service/api/material/permanent/api_uploadimg)
+- [新增草稿](https://developers.weixin.qq.com/doc/service/api/draftbox/draftmanage/api_draft_add)
+- [获取草稿](https://developers.weixin.qq.com/doc/service/api/draftbox/draftmanage/api_getdraft)
+
+## 6. 渲染、预检和预览
+
+### 6.1 固定云端模板目录
+
+云端目录当前提供既有 `wechat-minimal@1`，以及依据 WeMD（MIT）主题设计转写的十套
+受控模板：`wechat-academic-paper@1`、`wechat-aurora-glass@1`、`wechat-bauhaus@1`、
+`wechat-cyberpunk-neon@1`、`wechat-knowledge-base@1`、`wechat-luxury-gold@1`、
+`wechat-morandi-forest@1`、`wechat-neo-brutalism@1`、`wechat-receipt@1`、
+`wechat-sunset-film@1`。CLI 不展示或提交模板选项。Agent 可根据文章类型在 frontmatter
+写入 `dxc_wechat_template_hint`，作为首次预览的建议；最终选择只在短时预览页完成，服务端
+校验目录并生成新的不可变快照。
+
+模板是版本化样式令牌，不是用户可提交的 CSS。`wechat-minimal@1` 继续保留，以保证既有
+快照的 HTML 与哈希可复现；新增模板只能增加新 ID，不能改写已发布版本。
+
+兼容目标来自旧 `content-to-wechat`：
+
+- 所有关键样式内联；
+- 不输出 `<style>`、`class`、`id`、脚本或 iframe；
+- 表格转为段落/行式结构；
+- `<hr>` 转为带顶部边框的段落；
+- Markdown 外部链接去重并改成文末纯文本 URL；
+- 不输出 `<a>` 或 `href`；
+- 处理标题、段落、引用、列表、代码块和图片；
+- 图片先保持逻辑引用，交付阶段替换为微信 URL；
+- 检查渲染后 HTML 长度。
+
+旧实现的字符串替换逻辑只作为行为样例。新实现必须：
+
+1. 解析 Markdown token；
+2. 用模板 renderer 生成有限 HTML；
+3. 用 allowlist 清洗；
+4. 再做禁止标签/属性和长度扫描；
+5. 生成结构化 warnings/errors。
+
+### 6.2 不可变快照
+
+每个 `RenderSnapshot` 固定：
+
+- `sourceHash`
+- `assetManifestHash`
+- `templateId`
+- `rendererVersion`
+- `htmlHash`
+- `preflightResult`
+
+预览 URL 指向快照，不指向可变文章。用户在预览页切换模板时，服务端为同一原始快照记录
+最终选择并生成新的不可变快照；随后 CLI 仍以原始快照发起确认，服务端会解析为该最终快照。
+用户确认后生成绑定 `snapshotId + targetAccountId` 的 `Approval`。任何输入或模板选择变化都会使
+之前的确认不再适用。
+
+### 6.3 预览
+
+- 模仿微信公众号手机阅读宽度和基础字体；
+- 明确标注“高保真模拟，不保证与微信客户端逐像素一致”；
+- 短时签名 URL，默认 30 分钟；
+- 创建响应同时返回 `createdAt`、`expiresAt` 和 `expiresInSeconds`，CLI 明确展示剩余
+  时间；过期后重新生成链接时保留同一原始快照已记录的最终模板选择；
+- `Cache-Control: private, no-store`；
+- `X-Robots-Tag: noindex, nofollow`；
+- 严格 CSP，不加载第三方脚本；
+- 预览时可以展示权益状态，但草稿确认接口必须再次权威检查。
+
+### 6.4 已保留的固定真实验证切片
+
+在完整 P5/P6 前，本轮只验证一篇固定测试文章能否进入一个明确选择的已授权公众号草稿箱：
+
+1. Server 根据固定文章、标题、作者、摘要、评论开关、固定封面文件字节、模板和渲染器版本生成不可变 `snapshotHash`；
+2. CLI 展示目标公众号、固定文章预览元数据和快照哈希；
+3. 用户明确确认后，Server 以 `tenantId + idempotencyKeyHash` 创建一次草稿意图；
+4. 受控 Worker 通过特权调度仓储跨租户原子领取意图；任务必须携带 `tenantId`，领取后
+   再次按该租户核对目标账号、ACTIVE 授权、ID 11 权限和快照；
+5. Worker 刷新或读取 authorizer access token；仅当同一租户、同一账号已有字节完全一致（`coverHash` 相同）且确认上传成功的固定联调封面时，复用其永久 MediaID，否则上传一次永久封面；随后只调用一次 `draft/add`；
+6. 返回 media ID 后调用 `draft/get`，回读一致才进入 `SUCCEEDED`。
+
+该旧切片仍不接受任意文章上传，作为真实 API 安全和回归夹具保留；正式首位用户入口不再
+依赖它。
+
+### 6.5 首位用户通用文章闭环
+
+当前通用路径已经实现：
+
+1. Agent 视觉阶段实际生成或选择内容封面和正文图片并保存到显式项目素材目录；CLI
+   只读取用户明确指定的 Markdown、PNG/JPEG 文件，先做大小、metadata（元数据）与
+   本地预检；没有真实封面时停止并给出回到视觉阶段的处理建议；
+2. Server 发放同源、短时、哈希绑定的上传 URL，正文、正文图片和封面进入对象存储；
+3. Server 解析正文，按已选固定模板权威渲染并把不可变 HTML、素材清单哈希写入
+   对象存储和快照；
+4. `/previews/{token}` 以严格 CSP、no-store、noindex 返回同一快照、封面和 token
+   绑定的正文图片；
+5. Agent 把短时预览 URL 直接交给宿主右侧内置浏览器，不写入对话或项目产物；
+6. `Approval` 精确绑定 `tenantId + userId + snapshotId + snapshotHash + accountId`；
+7. 相同 `Idempotency-Key` 和请求返回同一草稿意图，不同请求固定冲突；
+8. Worker 从同一对象存储读取正文图片、封面和 HTML，复核哈希，调用正文图片上传接口
+   获得微信 HTTPS URL 并替换逻辑路径，再创建草稿并回读标题、作者、摘要和正文；
+9. 素材或草稿结果不确定时进入 `ASSET_UPLOAD_UNVERIFIED` 或
+   `CREATED_UNVERIFIED`，不盲目重试。
+
+当前限制是正文图片只接受显式本地 PNG/JPEG，且不自动裁切或压缩；权益/SkillPay 尚未
+成为草稿意图闸门；Worker 仍按配置锁定首位用户 `tenantId`。因此首位用户闭环可用，
+但完整多租户 P3、正文图片真实平台验证和商业 P7 仍未关闭。
+
+## 7. 图片与封面
+
+- CLI 根据 Markdown 和用户显式指定的非递归素材目录收集本地图片；不扫描其他目录，
+  文件读取拒绝符号链接，并对数量和体积设上限。
+- 正文图片只接受 PNG/JPEG，单张小于 1 MiB、单篇最多 20 张；封面不超过 5 MiB。
+- 上传前计算 SHA-256，内容寻址并去重。
+- 对象存储保存原始文件；当前不自动生成裁切或压缩变体。
+- 云端检查格式、像素、体积和宽高比。
+- 封面目标比例接近 2.35:1，并提供中心 1:1 安全区提示。
+- 视觉阶段必须生成或选择内容相关封面并保存到项目素材目录。CLI 的 `--cover auto`
+  只解析文章声明或 `cover.*`，不生成占位图。Agent 生成图片前仍须披露执行位置、数据
+  去向和可能的额度消耗。
+- 正文图片和封面上传微信是不同端点和不同素材语义，不能混用 media ID。
+- 对象存储 URL 不直接进入最终微信 HTML；必须替换为微信返回的正文图片 URL。
+
+## 8. MongoDB 与异步任务
+
+### 8.1 为什么 MVP 不需要独立队列
+
+草稿创建是低吞吐、长延迟、需要强幂等的任务。Mongo 已经是业务状态真值，可以用一个 `jobs` 集合实现：
+
+- `findOneAndUpdate` 原子领取；
+- `leaseOwner` + `leaseExpiresAt`；
+- `attempt` + `nextRunAt`；
+- Worker 心跳延长租约；
+- Worker 异常退出后租约到期可重新领取；
+- 终态任务不再领取。
+
+MVP 不依赖 change stream，也不要求 Redis。
+
+### 8.2 已确认的环境边界
+
+环境布局已经确认：
+
+- 本地开发连接本机 Docker MongoDB，使用独立 `dxc` 数据库；
+- 自动化测试使用隔离测试数据库，不连接生产；
+- 生产使用 `worker_vps` 上的现有 MongoDB，使用独立 `dxc` 数据库；
+- 应用仅通过 `DXC_MONGODB_URI` 和 `DXC_MONGODB_DATABASE` 读取连接配置，默认数据库名为 `dxc`；
+- 数据库口令和完整生产 URI 只进入安全环境配置，不写入 CLI 参数、代码、Git 或日志；
+- `ssh worker_vps` 是运维入口，不是应用运行时数据库协议；应用到 MongoDB 的实际网络链路须在部署前确定。
+
+生产启用前仍须只读核实：
+
+- 实例身份认证；
+- TLS 或受控私网链路；
+- 可恢复备份；
+- MongoDB 版本和单节点/副本集拓扑；
+- 磁盘、内存和连接数余量；
+- 最小权限账号只能访问 `dxc` 数据库；
+- 索引和 TTL 策略不会影响其他业务。
+
+跨集合流程使用幂等 Saga（补偿式事务）和唯一索引，不把 Mongo 副本集事务作为 MVP 硬依赖。
+
+## 9. 对象存储
+
+对象存储保存：
+
+- 上传的文章包；
+- 原始和规范化图片；
+- 渲染 HTML；
+- 预览所需快照；
+- 可选的短期诊断产物。
+
+数据库只保存对象 key、哈希、大小、媒体类型和生命周期，不保存永久公开 URL。
+
+MVP 使用 `ObjectStorage` 端口：
+
+```ts
+putObject()
+getObject()
+headObject()
+deleteObject()
+createSignedGetUrl()
+```
+
+实际供应商在部署前选择。测试使用内存/临时目录实现；生产不得依赖容器本地磁盘。
+
+## 10. SkillPay、微信支付和权益
+
+### 10.1 交互
+
+1. 渲染和预览免费。
+2. 用户确认创建草稿。
+3. Server 检查 `Entitlement` 和额度。
+4. 有权益：原子预留额度并接受任务。
+5. 无权益：返回单次/月卡/年卡选择。
+6. Agent 调用对应支付入口。
+7. DxC 创建微信支付订单和 SkillPay X402 预下单，向 Agent 返回支付触发信息。
+8. WorkBuddy 内置支付插件让用户确认。
+9. Agent 携带订单号重试；DxC 以支付回调或查单确认成功。
+10. DxC 幂等授予权益，然后重试同一个草稿意图。
+
+浏览器预览页不能假设会自动触发 SkillPay。支付动作回到 Agent；未来 Native 二维码支付页作为其他 Agent 的适配器。
+
+### 10.2 MVP 商品
+
+- `draft_credit`：一次草稿额度；
+- `pass_monthly`：购买后授予 30 天权益；
+- `pass_yearly`：购买后授予 365 天权益。
+
+月卡/年卡是固定期限预付权益，不是自动续费。
+
+SkillHub 上架前必须验证：
+
+- 一次 Pay Skill 调用是否允许授予固定期限权益；
+- 是否允许一个 Pay Skill 多价格/多 SKU；
+- CLI 输出的 402 Header/Body 能否被 WorkBuddy 稳定识别；
+- SkillHub 调用来源认证、结算、退款和审核规则。
+
+如果一个 Pay Skill 只有一个价格，保守包装为：
+
+- `dxc-draft-credit`
+- `dxc-pass-monthly`
+- `dxc-pass-yearly`
+
+用户主流程仍由 `dxc-wechat-publisher` 组织，不让用户理解内部支付适配器。
+
+### 10.3 扣费规则
+
+- 接受任务前预留额度；
+- 回读确认草稿存在后消费；
+- 明确失败时释放；
+- 结果不确定时冻结并进入核验；
+- 同一任务重试不重复扣费；
+- 任务在权益有效时被接受后，即使随后到期，也允许完成安全重试；
+- 支付订单成功但后续任务失败时，已购买的月卡/年卡仍有效；单次额度按失败类型释放。
+
+## 11. 部署拓扑
+
+2026-07-26 已确认的当前阶段组件放置方案如下：
+
+```mermaid
+flowchart LR
+    WB["WorkBuddy + dxc CLI"]
+    NG["content.deployxai.com<br/>现有 Nginx/HTTPS"]
+    API["DxC Server<br/>alivps"]
+    PX["受限 CONNECT 代理<br/>alivps / 固定出口"]
+    WK["DxC Worker<br/>worker_vps"]
+    MG["MongoDB<br/>worker_vps / 独立 dxc DB"]
+    OS["Object Storage"]
+    WX["微信开放平台<br/>公众号 API / 微信支付"]
+
+    WB --> NG
+    NG --> API
+    API <--> MG
+    API <--> OS
+    WK <--> MG
+    WK <--> OS
+    API <--> WX
+    WK --> PX
+    PX <--> WX
+```
+
+计划中的路由边界：
+
+- `/`、`/privacy/`、`/terms/`：继续由 `choir_site` 静态站点服务；
+- `/api/v1/*`：DxC API；
+- `/callbacks/wechat/*`：微信开放平台回调；
+- `/callbacks/wechat-pay/*`：微信支付通知；
+- `/authorize/*`：短时授权页面；
+- `/preview/*`：短时预览。
+
+这只是目标拓扑。修改 DNS、Nginx、证书或服务前必须另行获得明确授权。
+
+## 12. 可观测性
+
+MVP 最小可观测性：
+
+- `/health/live`：进程存活，不访问外部依赖；
+- `/health/ready`：配置结构、Mongo、对象存储的只读检查；
+- 每个请求、任务、草稿意图和支付订单有独立 ID；
+- 结构化日志默认脱敏；
+- 指标：请求错误、回调失败、token 刷新、任务积压、重试、草稿成功/不确定、支付对账异常；
+- 告警不包含文章正文、密钥或完整第三方响应。
+
+## 13. MVP 验收条件
+
+商业 MVP 只有在以下闭环全部通过后成立：
+
+- macOS 和 Windows 的 WorkBuddy 安装与 `dxc doctor`；
+- 一个测试公众号完整扫码授权、撤销和重新授权；
+- Markdown + 多张本地图片 + 封面完整预检；
+- 云端预览与最终 HTML 使用同一快照；
+- 有效订阅无支付提示；
+- 无权益时 WorkBuddy 能完成 SkillPay；
+- 同一个意图不会重复支付或重复创建草稿；
+- `draft/add` 成功后 `draft/get` 回读一致；
+- 模拟超时能够进入 `CREATED_UNVERIFIED` 并安全核验；
+- 所有日志和错误输出通过密钥/正文脱敏检查；
+- 未触碰 ID 7，未正式发布。