@deployxai/dxc 0.1.0

package/docs/05-delivery-plan.md

@@ -0,0 +1,407 @@
+# 实施顺序与验收闸门
+
+更新日期：2026-07-27
+
+原则：每一阶段都形成可运行、可测试、可回退的纵向增量。没有通过当前闸门，不提前堆叠下一阶段业务。
+
+## P0：架构与仓库基线
+
+本阶段交付：
+
+- 项目背景、终态和 MVP 文档；
+- 领域模型、状态机和 API 边界；
+- 安全、支付、微信和生产变更边界；
+- 旧 `content-to-wechat` 行为契约；
+- 项目级 `AGENTS.md`；
+- 本地 Git 仓库。
+
+完成闸门：
+
+- 文档之间没有范围冲突；
+- 不包含真实凭据；
+- 没有生产变更；
+- Git 工作树清晰可复验。
+
+## P1：可运行工程骨架
+
+创建：
+
+```text
+package.json
+pnpm-workspace.yaml
+tsconfig.base.json
+eslint.config.*
+apps/cli
+apps/server
+apps/worker
+packages/contracts
+packages/config
+packages/workflow-state
+packages/security
+```
+
+实现：
+
+- Node.js 24 LTS/pnpm 版本约束；
+- `dxc version --json`；
+- `dxc doctor --json`；
+- `/health/live`；
+- `/health/ready`；
+- Zod 配置校验；
+- Pino 脱敏基线；
+- Vitest 测试基线；
+- `.env.example` 只含占位名称；
+- 本地开发说明。
+
+不得实现：
+
+- 真实微信请求；
+- 真实支付；
+- 生产连接串；
+- 部署脚本。
+
+完成闸门：
+
+- 全新目录可一条命令安装和测试；
+- 缺失配置时服务快速失败并只报告变量名；
+- 健康检查不会泄露配置值；
+- macOS 和 Windows 的 CLI 入口测试通过。
+
+## P2：内容契约与极简渲染
+
+创建：
+
+```text
+packages/renderer-wechat
+fixtures/renderer
+```
+
+实现：
+
+- frontmatter 和文章包 Schema；
+- Markdown token renderer；
+- `wechat-minimal@1` 与固定云端模板目录；
+- allowlist 清洗；
+- 表格、链接、分隔线、代码、引用、列表和图片规则；
+- 结构化 preflight；
+- `sourceHash/htmlHash`；
+- 黄金样例与旧工具对比报告。
+
+数据来源：
+
+- 只读本地 `content-to-wechat/scripts/render-markdown.js`；
+- `references/wechat-html-spec.md`；
+- 后续经明确授权后只读核对 `alivps` 旧服务器行为。
+
+完成闸门：
+
+- 旧规则覆盖的样例全部有黄金输出；
+- 输出没有 `<table>`、`<a>`、`href`、`class`、`id`、`style` 标签或脚本；
+- 相同输入和版本产生相同哈希；
+- 恶意 HTML/Markdown 安全样例被清洗；
+- 长度边界有测试；
+- 当前微信官方限制和测试号行为得到复核。
+
+## P3：Mongo、对象存储与异步骨架
+
+实现：
+
+- Mongo 仓储接口和索引声明；
+- 本机 Docker MongoDB 的 `dxc` 开发库接入；
+- 自动化测试使用随机命名的隔离测试库；
+- `jobs` 原子租约；
+- Worker 领取、心跳、退避和终态；
+- 对象存储端口和测试实现；
+- 审计事件；
+- 幂等 key 中间件。
+
+生产前只读核验：
+
+- `worker_vps` 现有 MongoDB 的认证、TLS/私网、版本、拓扑、备份和资源；
+- `dxc` 数据库最小权限账号、网络路径和恢复演练方案；
+- 目标对象存储供应商和生命周期；
+- `alivps`/`worker_vps` 的网络连通设计。
+
+完成闸门：
+
+- 两个 Worker 不会领取同一有效租约；
+- Worker 崩溃后任务可恢复；
+- 唯一索引阻止重复意图、支付和履约；
+- 无副本集事务时 Saga 能从每个中断点恢复。
+
+## P4：设备绑定与微信第三方平台授权
+
+实施说明（2026-07-27）：独立网站应用登录新增 `purpose=start`。用户主动执行
+`dxc setup`/`dxc auth start` 时，已关联微信恢复同一 owner，未关联微信明确创建新
+owner；严格的 `purpose=login` 仍只恢复已有映射。首次候选 user/tenant 由作用域化身份
+摘要确定性派生，并通过 Mongo 原子 bootstrap 避免并发产生孤立租户。旧 owner 仍可
+`link-wechat`，公众号授权仍不能接管已有租户。Server 只保存 openid/unionid 摘要并
+立即丢弃网站 OAuth token。设备 Token/刷新轮换和多设备索引边界不变。真实配置已经由
+用户准备，但本提交未读取、部署或现场验证；系统凭据存储、完整身份审计、边缘限流和
+真实新设备扫码仍是 P4 关闭前闸门。
+
+实现：
+
+- 设备密钥/会话；
+- 授权 session 和加密 state；
+- 微信回调原始 Body；
+- 签名/AES/AppID/重放验证；
+- component ticket；
+- component/authorizer token service；
+- 授权、撤销和权限变更；
+- ID 3 账号信息回读；
+- CLI `dxc wechat connect/accounts`。
+- CLI `dxc auth link-wechat/login/status/logout`；
+- 独立网站应用 `snsapi_login`、固定同域入口/回调与 openid/unionid 摘要映射；
+- 24 小时设备访问 Token、30 天刷新凭据、Ed25519 刷新签名和单次轮换；
+- 同 owner 多设备与旧单账号 bootstrap 原子认领保护；
+- Ed25519 规范公钥、短时挑战和设备持钥证明；
+- 首次扫码 bootstrap owner/tenant，设备会话与授权轮询 Token 分离；
+- 同租户多公众号和跨租户账号冲突保护；
+- `URL_READY → EXCHANGING → AUTHORIZED → BOUND` 授权 Saga：授权码先原子认领，加密授权结果先做可恢复检查点，再投影身份和公众号记录；`EXCHANGING` 不盲目重复调用 `api_query_auth`。
+
+测试：
+
+- 官方示例/自建假微信服务；
+- 重复 ticket；
+- 错误签名、错误 AppID、旧时间戳、重复 nonce；
+- 并发 token 刷新；
+- 撤销后立即拒绝新任务；
+- 授权回调并发、`AUTHORIZED` 中断恢复，以及 `EXCHANGING` 到期后要求重新扫码。
+- 个人微信关联、未关联拒绝、第二设备登录、`IDENTIFIED` 恢复检查点和刷新轮换重放；
+- Mongo 全新库初始化、旧设备索引迁移和同租户多设备集成。
+
+真实测试号联调需要单独批准并注入测试凭据。
+
+完成闸门：
+
+- 客户流程中从未要求 AppID/AppSecret；
+- 只出现 ID 3/11；
+- 多账号必须选择；
+- token 不出现在日志、错误或 API 返回；
+- 撤销链路可验证。
+
+## P5：云端文章、预览和确认
+
+实施说明（2026-07-30）：固定真实验证切片继续保留；首位用户通用路径已覆盖 Markdown、
+显式本地 PNG/JPEG 正文图片、素材目录采集、真实内容封面校验、短时同源上传、对象存储、
+云端固定模板目录权威渲染、右侧内置浏览器展示、严格
+CSP/no-store/noindex 预览、绑定 `snapshotHash + accountId` 的 `Approval` 和幂等草稿
+意图。预览响应包含到期倒计时，状态响应包含面向用户的中文说明。生产 S3 供应商已固定为独立
+阿里云 OSS 私有 bucket，但 Server、Worker 的真实内网上传/读取/删除探针和微信正文
+图片上传现场验证仍是发布闸门。完整 P3/P5 闸门仍未关闭。
+
+实现：
+
+- CLI 本地图片收集和路径边界；
+- 上传会话；
+- `ArticleSource`/`Asset`；
+- 云端 `RenderSnapshot`；
+- 手机样式预览；
+- 短时预览 token；
+- `Approval`；
+- 快照失效规则。
+
+完成闸门：
+
+- 预览 HTML 与交付 HTML 来自同一快照；
+- 修改任一输入会让旧确认失效；
+- 预览不可索引、不可执行脚本、过期不可访问；
+- CLI 和 Agent 能完整展示 errors/warnings。
+
+## P6：微信草稿纵向闭环
+
+受控纵向切片先实现：
+
+- 固定测试文章/封面和不可变 `snapshotHash`；
+- `draft-smoke-previews`、幂等意图和状态查询；
+- Worker 领取所有租户的任务，并对每项任务重新核对其租户、账号、ACTIVE 授权和 ID 11；
+- authorizer access token 读取/刷新；
+- 永久封面上传、一次 `draft/add` 和 `draft/get` 回读；
+- 全部 API 加密及签名校验：只对官方声明支持的公众号 JSON API 使用 RSA-SHA256-PSS + AES-256-GCM；第三方平台管理接口保持普通 HTTPS JSON；
+- 永久素材使用普通 HTTPS multipart，不添加 `Wechatmp-*`；这是已开启全部 API 安全的真实平台对二进制资源上传的已核验兼容例外；
+- 状态审计、`ASSET_UPLOAD_UNVERIFIED` / `CREATED_UNVERIFIED` 和无盲重试测试。
+
+该切片明确不包含正文图片、对象存储、通用文章/预览、额度/支付、自动 reconciliation（核验补偿）、素材上传不确定结果的自动对账、审计 outbox（发件箱）投影或自动下载新平台证书，也不包含正式发布/群发。轮换窗口可使用已配置旧证书和 Deprecated（即将弃用）签名头继续验签，但仍需人工及时更新证书文件。只有真实草稿创建与回读成功，才能记为这次联调通过；仍不能据此关闭完整 P6。
+
+联调结果（2026-07-26）：用户明确确认修正作者后的不可变快照，真实草稿创建成功，`draft/get` 对标题、作者、摘要和正文的回读校验全部通过，受控意图进入 `SUCCEEDED`。未执行正式发布或群发；完整 P6 仍保持未关闭。
+
+通用实现说明（2026-07-30）：Worker 从通用
+`wechat_draft_intents` 跨租户原子领取任务，从共享对象存储读取并复核不可变
+HTML/正文图片/封面哈希，逐张调用 `media/uploadimg` 并替换最终 HTML，按
+`tenantId + accountId + coverHash` 复用封面 MediaID，只调用一次 `draft/add` 并用
+`draft/get` 回读标题、作者、摘要和最终正文。Mongo 原子领取、并发隔离、中断恢复和
+审计有单元/本地 Mongo 集成覆盖。正文图片假服务闭环已通过，真实平台验证、
+通用多租户 lease/heartbeat、自动 reconciliation 和权益预留仍未实现。
+
+实现：
+
+- 微信客户端端口和假服务；
+- 正文图片上传；
+- 封面永久素材；
+- URL 替换；
+- 最终 preflight；
+- `draft/add`；
+- `draft/get`；
+- `DraftIntent`/`DraftDelivery`；
+- `CREATED_UNVERIFIED` 和 reconciliation；
+- 额度预留的测试替身；
+- CLI 状态查询和本地结果文件。
+
+完成闸门：
+
+- 正常路径完整回读；
+- 每个已知微信错误码有稳定分类；
+- `CREATING_DRAFT` 只有在已验签响应明确拒绝且能够证明未创建时才进入 `FAILED`；
+- `draft/add` 超时测试不产生盲重试；
+- 相同 idempotency key 不产生第二个草稿；
+- 明确提示用户去公众号后台人工复核和发布；
+- 代码不存在正式发布 API。
+
+## P7：WorkBuddy Skill 与 SkillPay
+
+### 7.1 平台可行性 Spike（尖峰验证）
+
+先用最小无业务端点验证：
+
+1. 商户入驻和微信商户号绑定；
+2. WorkBuddy 能识别 CLI/API 返回的 X402 支付字段；
+3. 支付后重试和查单；
+4. 固定期限权益是否符合 SkillHub 上架规则；
+5. 一个 Pay Skill 是否支持多个价格；
+6. 退款、结算和调用来源认证。
+
+未验证前不把月卡/年卡包装方式写死到核心领域。
+
+### 7.2 产品实现
+
+当前进度（2026-07-30）：`dxc-wechat-publisher@0.5.0` 已完成真实素材上传、右侧云端
+预览、明确确认、幂等创建和面向用户的进度查询；SkillPay、商品、订单、权益
+和扣费尚未实现。因此当前首位用户闭环不收费，不得宣称商业 P7 完成。
+
+实现：
+
+- `dxc-wechat-publisher`；
+- WorkBuddy adapter；
+- `Offering`、`PaymentOrder`、`Entitlement`、`CreditWallet`；
+- SkillPay X402；
+- 微信支付回调、查单和对账；
+- 单次/月卡/年卡；
+- 支付后自动继续同一个草稿意图；
+- 根据平台结果决定一个或三个 Pay Skills。
+
+完成闸门：
+
+- 有权益不支付；
+- 无权益只在确认草稿后支付；
+- 重复回调不重复发权益；
+- 支付成功但 Agent 中断后可以恢复；
+- 一次草稿不重复扣费；
+- SkillPay 不可用时保留清晰错误和后续适配器边界。
+
+## P8：封闭试用和生产准备
+
+只读核验和演练：
+
+- `alivps` 当前出口 IP、CPU、内存、磁盘、容器/进程和端口；
+- `worker_vps` Mongo；
+- `content.deployxai.com` 当前 Nginx 路由；
+- 备份/恢复；
+- 密钥轮换；
+- 支付对账；
+- 微信授权撤销；
+- 数据删除；
+- 灰度、回滚和版本兼容。
+
+需要用户另行决定并授权：
+
+1. 生产对象存储供应商/bucket；
+2. 生产 Secret/KMS Provider；
+3. Nginx 路由和实际部署窗口。
+
+生产变更必须单独执行，不与普通功能提交混在一起。
+
+## P9：MVP 后扩展
+
+按照真实需求按需增加：
+
+- `dxc-humanizer`
+- `dxc-style-writer`
+- `dxc-taste-curator`
+- `dxc-writing-framework`
+- `dxc-visual-designer`
+- 自动化任务和内容源
+
+扩展规则：
+
+- 只发布一个总控入口 `dxc-content-workflow`；不增加独立安装 Skill；
+- 新 Skill 先定义输入输出；
+- 尽量产出/修改用户可见 Markdown；
+- 不绕过发布快照和确认；
+- 不改变 MVP 微信发布主干；
+- 不因为未来自动化提前引入工作流引擎。
+- 抓取由通用 Agent 主编排并默认本地优先；DxC Cloud 不向第三方内容源发起研究抓取请求；每次运行记录 `executionLocation` 和 `dataTransit`；
+- Skill 声明能力与版本，`dxc` 提供或安装受控的本地工具包，不执行任意依赖安装脚本；
+- Agent 自动化可用时直接编排，不可用时由本地 Runner 承接；电脑离线时明确记录错过；
+- 登录态只交给已证明本机执行的适配器并按域名显式授权；DxC 不上传 Cookie、Token、原始页面和完整抓取缓存，Agent 宿主的数据处理边界单独披露；
+- 本地任务必须显式开启，具备并发锁、频率/资源上限、错过任务策略、暂停、通知和保留期限；
+- 页面按不可信输入处理；URL 逐跳拒绝本机、私网和云元数据地址，不能由抓取内容触发工具或命令；
+- 研究产物按统一阶段 contract 保存必要摘要与来源，用户确认观点不等于允许上传第三方全文；
+- 总控、八步产物路径、统一 checkpoint、本地画像和历史文章混合召回保持稳定；
+- 历史文章只显式导入到本地 SQLite；FTS5 与固定版本中文嵌入模型做混合召回，不上传历史全文，不把关键词模式冒充语义模式；
+- 已提供用户显式调用的本地 RSS、HTTP API 与公开 HTML 采集原语，以及公开来源注册、手动
+  检查、运行记录和增量去重；定时、热度计算和浏览器会话适配器仍待真实重复需求进入后实现。
+
+实施说明（2026-07-30）：`dxc-content-workflow@0.6.0` 和八个步骤 Skill 全部可调用并
+随 CLI 安装包一次分发。`available` 不再冒充成熟度；catalog 同时声明
+`implementationLevel`、`verificationLevel` 和 `knownGaps`。`ContentProfile`、
+`ContentProjectManifest`、
+轻量项目索引、v3 `StepCheckpoint` 和 `dxc knowledge` 本地混合召回保持可用；项目
+初始化会展示知识库状态并支持显式导入。v3 阶段确认绑定产物/渲染快照哈希、确认者和
+时间。总控是唯一隐式入口，每次从实际产物恢复并自动推进；普通内部阶段不要求人工
+确认，输入变化会使下游 contract 失效。已有正文仍可作为可信下游产物导入，但跳过步骤
+不能冒充专家 Skill 已运行。CLI 在接受等待或完成 checkpoint 前解析阶段 frontmatter，
+校验固定 Skill 版本、项目/工作流、实际输入哈希和各阶段必填字段；视觉阶段还校验真实
+图片文件。非空占位 Markdown 不能完成阶段。
+
+当前框架切片完成闸门：
+
+- 总控 Skill 可区分首次初始化、等待确认、失败/stale（失效）、下一步和完成；
+- 新会话可按文章标题定位项目，相同项目状态不依赖 Agent 对话即可从磁盘恢复；
+- 每个阶段保存实际输入、输出、摘要和等待用户的问题，上游变化会使下游阶段失效；
+- 画像和知识库使用用户私有权限，不输出绝对源路径；
+- “创业低谷”可通过语义向量召回只含“现金流快断了/克制扩张”的历史片段；
+- 缺失向量时混合查询明确失败，不静默退化；
+- 模型 ID、revision、q8 和 512 维契约固定，模型下载不包含文章正文；
+- catalog 中八个步骤均有 Skill、版本、必需/可选输入、真实确认点、实现等级、验证等级
+  和已知缺口声明；
+- 除总控外的八个步骤都禁止宿主隐式触发；
+- 每个阶段的 Markdown 元数据和 checkpoint 输入哈希会被机器校验，可支持新会话续跑。
+
+本地研究的建议顺序：
+
+1. 用户给定 URL/RSS，先由 `dxc source fetch html|rss|api` 输出可追溯的本地采集结果，再写
+   `dxc-content-stage@1` 研究产物；
+2. Agent Browser/Computer Use 的交互式当前页研究；
+3. `dxc-tool-browser-crawler` 本地可选工具包和 DxC 专用浏览器 Profile；
+4. 本地计划任务、暂停、失败记录和增量去重；
+5. 真实需求出现后再增加逐站适配器，不建设通用云爬虫平台。
+
+定时热点、指标时间序列、爆款证据与开源项目取舍见
+[研究监控、热点发现与爆款拆解设计](research-monitoring-design.md)。该能力位于八阶段
+之外，只向 `research` 阶段提供有界候选和证据。
+
+## 横向测试矩阵
+
+| 维度 | 最小覆盖 |
+|---|---|
+| 系统 | macOS、Windows、Linux Server |
+| Agent | WorkBuddy；Codex 做 CLI/Skill 兼容 |
+| 文章 | 中文、英文混排、代码、列表、引用、表格、链接 |
+| 图片 | PNG/JPG、缺失、过大、重复、越界路径 |
+| 账号 | 单账号、多账号、撤销、缺权限 |
+| 网络 | 超时、断开、重复响应、429、5xx |
+| 微信 | 图片失败、封面失败、草稿成功、草稿结果不确定、回读失败 |
+| 支付 | 无权益、有权益、重复回调、支付后中断、退款 |
+| 安全 | XSS、回调伪造、重放、跨租户 ID、日志泄露 |
+| 升级 | 旧 CLI、新 Server；任务中固定版本；回滚 |

package/docs/README.md

@@ -0,0 +1,44 @@
+# DxC 文档索引
+
+本文档集是当前项目的架构和实施真值。
+
+| 文档 | 用途 |
+|---|---|
+| [00-project-context.md](00-project-context.md) | 历史背景、产品收敛过程和已确认决策 |
+| [01-north-star-architecture.md](01-north-star-architecture.md) | 终态产品、Skill/CLI/云端分层和扩展方向 |
+| [02-mvp-technical-design.md](02-mvp-technical-design.md) | 当前微信公众号 + WorkBuddy + SkillPay MVP |
+| [03-domain-state-api.md](03-domain-state-api.md) | 领域对象、Mongo 集合、状态机、HTTP/CLI 契约 |
+| [04-security-and-operations.md](04-security-and-operations.md) | 加密、密钥、租户、日志、回调、保留和生产边界 |
+| [05-delivery-plan.md](05-delivery-plan.md) | 分阶段实现、测试矩阵和上线闸门 |
+| [eight-stage-implementation-audit.md](eight-stage-implementation-audit.md) | 八阶段真实实现度、机器校验和剩余缺口 |
+| [research-monitoring-design.md](research-monitoring-design.md) | 定时热点、榜单采集、爆款拆解和本地 Runner 设计 |
+| [local-development.md](local-development.md) | 工程骨架、渲染和授权切片的安装、运行、验证和环境变量 |
+| [decisions/0001-initial-architecture.md](decisions/0001-initial-architecture.md) | 已接受的初始架构决策记录 |
+| [decisions/0002-mongodb-environment-boundary.md](decisions/0002-mongodb-environment-boundary.md) | 本地与生产 MongoDB 环境边界 |
+| [decisions/0003-staged-production-topology.md](decisions/0003-staged-production-topology.md) | Server、Worker、Mongo 和统一微信出口的阶段性生产拓扑 |
+| [decisions/0004-local-first-agent-research-runtime.md](decisions/0004-local-first-agent-research-runtime.md) | 用户电脑、通用 Agent、本地浏览器与研究抓取能力边界 |
+| [decisions/0005-official-skill-orchestration-and-local-content-memory.md](decisions/0005-official-skill-orchestration-and-local-content-memory.md) | 隐式总控、跨会话项目恢复、阶段 contract、本地画像与历史文章混合召回 |
+| [decisions/0006-separate-wechat-user-login-from-account-authorization.md](decisions/0006-separate-wechat-user-login-from-account-authorization.md) | 个人微信网站登录、公众号授权分离和设备会话续期 |
+| [decisions/0007-explicit-personal-wechat-start.md](decisions/0007-explicit-personal-wechat-start.md) | 显式首次注册、统一 setup 和同一微信并发收敛 |
+| [decisions/0008-end-to-end-content-workflow-continuity.md](decisions/0008-end-to-end-content-workflow-continuity.md) | Agent 视觉生产、本地素材、云端预览、知识库引导、CLI 和确认治理 |
+| [decisions/0009-versioned-cloud-template-catalog.md](decisions/0009-versioned-cloud-template-catalog.md) | 固定云端模板目录、快照绑定和 WeMD 复用边界 |
+| [todo-preview-local-first.md](todo-preview-local-first.md) | 云端预览、样式收费与 local-first 的待决产品边界 |
+| [first-user-guide.md](first-user-guide.md) | 第一个真实用户的安装、初始化、知识库、标题和草稿闭环 |
+| [workbuddy-first-user-runbook.md](workbuddy-first-user-runbook.md) | 交给 WorkBuddy 执行的本地安装与首位用户体验任务 |
+| [history/content-forge-prd-v0.2-summary.md](history/content-forge-prd-v0.2-summary.md) | North Star 原始 PRD 的本地历史摘要 |
+| [references/source-inventory.md](references/source-inventory.md) | 本轮使用的本地文件和官方网页索引 |
+| [references/legacy-content-to-wechat-contract.md](references/legacy-content-to-wechat-contract.md) | 旧技能可复用行为和不可复用实现 |
+| [references/renderer-compatibility-report.md](references/renderer-compatibility-report.md) | `wechat-minimal@1` 首轮实现、黄金样例和未完成验证闸门 |
+| [references/wemd-template-attribution.md](references/wemd-template-attribution.md) | WeMD MIT 模板设计来源、版本和复用范围 |
+| [references/wechat-renderer-platform-validation.md](references/wechat-renderer-platform-validation.md) | 微信官方限制与非生产公众号兼容性验证清单 |
+| [references/wechat-third-party-platform-setup.md](references/wechat-third-party-platform-setup.md) | 第三方平台字段、固定回调 URL、`.env.local` 和扫码验证步骤 |
+| [references/wechat-website-login-setup.md](references/wechat-website-login-setup.md) | 网站应用申请字段、固定登录 URL、环境变量和关联/登录步骤 |
+| [references/aliyun-oss-production-setup.md](references/aliyun-oss-production-setup.md) | DxC 专用私有 bucket、RAM 最小权限和 S3 兼容配置 |
+
+## 维护规则
+
+- MVP 行为变化优先更新 `02`、`03` 和测试。
+- 安全或生产边界变化必须更新 `04` 和 `AGENTS.md`。
+- 新平台能力、价格或官方限制必须记录核验日期和官方链接。
+- 历史文档只追加更正说明，不反向覆盖当前架构。
+- 代码实现与本文档冲突时先停止，明确更新架构或修正实现。

package/docs/decisions/0001-initial-architecture.md

@@ -0,0 +1,57 @@
+# ADR-0001：DxC 初始架构
+
+日期：2026-07-25
+状态：Accepted（已接受）
+
+## 背景
+
+DxC 需要把已经验证的 `content-to-wechat` 发布能力做成可收费、可安装、可升级的多租户产品，同时保持未来向研究、写作风格、品味和自动化内容源扩展的能力。
+
+用户的主要工作环境是 WorkBuddy、Codex 等 Agent，而不是一个新的传统 Web 编辑器。
+
+## 决策
+
+1. 采用 Agent Native 产品形态。
+2. 本地使用 Node.js/TypeScript `dxc` CLI。
+3. 所有 Skills 使用 `dxc-` 前缀，MVP 主 Skill 为 `dxc-wechat-publisher`。
+4. MVP 不使用 MCP。
+5. 云端负责微信第三方平台凭据、权威渲染、预览、任务、支付、权益和审计。
+6. Markdown 到微信 HTML 只在云端进行权威渲染。
+7. MVP 使用固定、版本化的云端模板目录；该目录不接受用户 CSS 或任意 HTML。模板扩展的
+   具体约束见 ADR-0009。
+8. 使用 MongoDB 作为业务数据库和租约队列，不引入 PostgreSQL、Redis 或工作流引擎。
+9. 通过对象存储保存文章包、图片和渲染快照。
+10. WorkBuddy/SkillHub 是首发分发渠道，SkillPay 是首发支付适配器。
+11. 月卡/年卡由 DxC 维护固定期限权益，不假设 SkillPay 原生提供订阅。
+12. 微信只使用第三方平台扫码授权、ID 3 和 ID 11；MVP 只创建草稿。
+13. `choir_site` 继续承载静态官网和法律页面，与 SaaS 主应用分离。
+
+## 结果
+
+正面结果：
+
+- 用户可以直接在 Agent 中安装和工作；
+- Skills 可以独立扩展而不复制平台凭据和状态机；
+- 云端统一修复微信渲染和接口兼容；
+- 单人 MVP 只需维护一个主要语言和一个数据库；
+- 后续 Agent、平台和支付渠道可以通过适配器增加。
+
+代价：
+
+- 云端必须处理内容副本和更严格的隐私/安全要求；
+- WorkBuddy 的 SkillPay 细节需要真实联调；
+- CLI、Skill 和云端需要协议版本管理；
+- Mongo 队列要求我们自己实现租约、重试和死信运维；
+- 独立 Agent 之外的支付需要备用适配器。
+
+## 非决策
+
+以下是部署时绑定，不改变本 ADR：
+
+- 对象存储具体供应商；
+- Secret/KMS 具体供应商；
+- 容器运行时；
+- 生产 Mongo 是否为单节点或副本集；
+- Nginx 的最终反向代理细节。
+
+这些选择必须在生产只读核验和用户明确授权后完成。

package/docs/decisions/0002-mongodb-environment-boundary.md

@@ -0,0 +1,42 @@
+# ADR-0002：MongoDB 环境边界
+
+日期：2026-07-25
+
+状态：已接受
+
+## 背景
+
+DxC 的业务状态和 MVP 异步租约队列均使用 MongoDB。用户已经确认：
+
+- 本地已有 Docker MongoDB；
+- 生产 MongoDB 位于用户自己的 `worker_vps`；
+- DxC 只需在每个环境使用独立数据库。
+
+需要将“实例可以复用”与“业务数据可以混用”明确分开，同时避免本地开发依赖生产环境。
+
+## 决策
+
+1. 本地开发连接本机 Docker MongoDB，数据库名为 `dxc`。
+2. 自动化测试使用随机命名的隔离数据库，例如 `dxc_test_<runId>`，并只清理本次测试创建的数据库。
+3. 生产连接 `worker_vps` 上的现有 MongoDB，数据库名为 `dxc`。
+4. 生产使用只能访问 `dxc` 数据库的最小权限账号，不复用其他应用账号，不访问其他数据库或集合。
+5. 应用通过 `DXC_MONGODB_URI` 和 `DXC_MONGODB_DATABASE` 获取配置；完整 URI 和口令不得进入 Git、日志、CLI 参数或 Agent 上下文。
+6. `ssh worker_vps` 只作为运维入口。应用运行时使用正常 MongoDB 驱动连接，具体采用 TLS、私网或其他受控网络路径，在部署前现场核实。
+7. 生产建库、创建账号、创建索引、配置备份或执行数据写入，仍属于生产变更，必须另行获得明确授权。
+8. MVP 不要求副本集事务或 change stream；使用单文档原子更新、唯一索引和幂等 Saga。
+
+## 结果
+
+- 本地开发可以完全脱离生产环境运行；
+- 复用现有 MongoDB 实例，减少 MVP 运维组件；
+- DxC 与同实例上的其他业务保持权限和命名空间隔离；
+- 后续若迁移到独立 MongoDB 实例，只需更换安全环境配置，不改变领域代码。
+
+## 生产启用前检查
+
+- MongoDB 版本和单节点/副本集拓扑；
+- 身份认证和最小权限账号；
+- TLS 或受控私网链路；
+- 磁盘、内存、连接数和容量余量；
+- 备份频率、保留周期和隔离恢复演练；
+- `dxc` 索引、TTL 和任务租约对实例负载的影响。

package/docs/decisions/0003-staged-production-topology.md

@@ -0,0 +1,33 @@
+# ADR 0003：分阶段生产拓扑与统一微信出口
+
+- 状态：Accepted
+- 日期：2026-07-26
+
+## 背景
+
+当前 `alivps` 有固定公网入口和已加入微信白名单的出口，资源为 2 核、约 2 GiB 内存。`worker_vps` 承载生产 MongoDB，具备私网地址但没有可用公网出口。用户确认当前阶段将 Server 和 Worker 分开部署，并希望入站、出站均保持单一公网边界；后续再将 PM2/Node 从 `alivps` 迁移到独立应用 ECS。
+
+现场核验还发现 `alivps` 没有 Swap，服务器端依赖安装/构建曾触发 OOM。构建产物不能继续在生产 ECS 生成。
+
+## 决策
+
+当前阶段：
+
+1. `alivps` 运行 Nginx、`dxc-server` 和一个受限 Squid CONNECT 代理；
+2. `worker_vps` 运行 `dxc-worker` 和 MongoDB 独立 `dxc` 数据库；
+3. Server 与 Worker 通过 Mongo 原子租约队列传递任务，不以 HTTP 互相代发微信副作用；
+4. Worker 仅通过私网代理访问 `api.weixin.qq.com:443`；
+5. 代理只接受 `worker_vps` 私网 IP、CONNECT 方法、443 端口和精确微信 API 域名；
+6. 代理不缓存、不解密 TLS，使用 128 MiB 内存和 0.25 核 CPU 硬上限；
+7. 所有构建在本地或 CI 完成，生产 ECS 只接收已构建、已校验的发布产物。
+
+后续阶段可以新增应用 ECS，将 `dxc-server` 从 `alivps` 迁走。届时统一出口改用受控代理或带固定 EIP 的 NAT Gateway，属于独立迁移，不阻塞当前微信草稿验证。
+
+## 后果
+
+- 微信入站继续只有 `content.deployxai.com`；
+- Server 和 Worker 对微信呈现同一个固定公网出口；
+- Worker 仍是素材上传和 `draft/add` 的唯一执行者；
+- 代理故障只影响微信外部调用，不改变 Mongo 中的任务真值；
+- CONNECT 只能按主机和端口限制，允许的微信 API 路径继续由 `@dxc/wechat-client` 的显式方法集合约束；
+- `alivps` 仍是当前阶段的单点边缘节点，后续迁移再处理可用性提升。

package/docs/decisions/0004-local-first-agent-research-runtime.md

@@ -0,0 +1,71 @@
+# ADR-0004：本地优先的 Agent 研究与抓取运行时
+
+日期：2026-07-26
+
+状态：Accepted（已接受）
+
+## 背景
+
+DxC 的长期价值不只在发布，而在选题、热点发现、研究、观点提炼和个人化写作。目标用户已经在 WorkBuddy、Codex 等通用 Agent 环境中工作，并拥有本机网络、本地文件以及经本人登录的浏览器会话。
+
+如果由 DxC 云端集中抓取，会引入共享出口 IP、代理池、集中 Cookie 保管、第三方全文留存、反爬对抗和更高的合规风险，也无法充分利用 Agent 的 Browser/Computer Use 与用户本地浏览器能力。
+
+## 决策
+
+1. 研究和抓取默认由通用 Agent 在用户电脑或宿主管理的工具环境中执行，不使用 DxC Server/Worker 的生产出口。每次运行必须记录并向用户展示 `executionLocation: local-device | agent-hosted | unknown` 和 `dataTransit: local-only | agent-provider | unknown`；不能把“由 Agent 调用”自动等同于“在本机执行”。
+2. Skill 负责询问主题、来源、频率、输出和人工确认，并声明所需的版本化能力；Skill 不包含任意 `npm install`、`pip install` 或远程 Shell 安装脚本。
+3. `dxc` CLI 提供公开 HTML、RSS、正文抽取、链接发现、内容哈希、增量去重、证据落盘和本地任务记录等确定性能力。
+4. Playwright、Puppeteer、站点适配器等重型或专用工具作为可选的版本化本地工具包。首次安装必须向用户展示来源、版本、体积、权限和数据去向，并校验签名清单与 SHA-256、写入锁文件。工具包不得运行任意安装脚本，必须支持回滚、卸载、浏览器/Profile 缓存清理和权限撤销。
+5. Agent 可通过 Browser/Computer Use 执行交互式研究和一次性抓取；可重复自动化优先调用相同契约下的本地 Runner。Agent 宿主提供可靠自动化时可以直接调度，否则退化为 `launchd`、Windows 任务计划程序或 `systemd timer`。Agent 是主编排者，`dxc`/Runner 只是确定性能力提供者。
+6. 需要登录态的自动化只允许使用明确报告为 `local-device` 且 `dataTransit` 经用户接受的适配器，并默认使用用户授权的 DxC 专用浏览器 Profile 或逐域名授权的本地浏览器桥接。登录和验证码由用户本人完成；能力只输出页面证据，不输出 Cookie、Token、密码、请求头或原始 Profile 路径，这些凭据不得进入 Skill、Agent 提示、DxC 日志或任务参数。
+7. DxC CLI 和 DxC Cloud 默认不上传原始页面、截图、完整正文和抓取缓存。Agent 宿主或模型提供方是否会处理页面内容，取决于其自身运行位置和数据政策，必须在首次使用对应能力时向用户说明。只有用户确认后的 `research-pack`、`ContentBrief`、`ArticleSource` 或发布所需内容进入 DxC Cloud。
+8. 每个抓取任务必须由用户显式开启，不能静默注册开机自启；必须有域名白名单、频率和资源上限、并发锁、错过任务策略、暂停/删除能力、失败通知、保留期限、本地运行记录、来源 URL、抓取时间、抽取器版本和内容哈希。
+9. 不内置指纹伪装、验证码绕过、付费墙绕过、权限提升或隐蔽高频抓取。真实 IP 和真实登录态不会消除站点条款、版权、账号风控或本机安全责任。
+10. DxC Server、Worker 和其他 DxC Cloud 组件不得向第三方内容源发起研究抓取请求。DxC Cloud 继续只承担必须集中的身份、微信授权令牌、权威渲染、支付、草稿副作用和云端审计，只接收用户确认后的最小派生产物。未来若要改变这一不变量，必须新增 ADR。
+11. 页面正文始终是不可信数据，不能改变 Agent/Skill 指令、调用工具、读取凭据或触发命令。URL 抓取只允许 `http/https`，逐跳校验重定向和 DNS，默认拒绝本机、私网、链路本地和云元数据地址，防止本地 SSRF（服务端请求伪造）。
+
+## 能力契约
+
+Skill 依赖按能力和版本声明，例如：
+
+```yaml
+requires:
+  dxc: ">=0.2 <0.3"
+  capabilities:
+    - source.fetch.public-html@1
+    - research.pack.write@1
+  optionalTools:
+    - dxc-tool-browser-crawler@1
+```
+
+Skill 不依赖具体 Agent 的工具名。`browser.page.capture.authenticated@1` 可以由已证明本机执行的 Browser、Computer Use、本地 Playwright/Puppeteer 或未来浏览器桥接适配，但只输出规范化页面证据，不能暴露浏览器 session（会话）材料。公开来源可以使用 `browser.page.capture.public@1`，并允许 `local-device`、`agent-hosted` 或用户明确同意的 `unknown` 执行位置。
+
+所有抓取适配器输出同一个 envelope（信封结构），但不承诺证据质量相同。至少记录 `captureMethod`、`executionLocation`、`dataTransit`、完整/部分标记、抽取器及版本、原始内容哈希、抽取结果哈希和已知限制。
+
+`research-pack@1` 分为两个投影：
+
+- 本地完整包：可以引用本地缓存、截图和完整抽取结果，路径不进入云端；
+- 云端最小投影：只含来源元数据、必要短摘录、观点、证据引用和哈希。用户确认研究结论不自动等于授权上传第三方全文。
+
+实施说明（2026-07-29）：当前自动内容链路先以
+`dxc-content-stage@1 / stage: research` 的用户可见 Markdown 保存必要摘要、来源和
+角度候选，不上传 DxC Cloud，也不实现上述双投影传输。`research-pack@1` 保留为未来
+真的需要云端最小投影时的能力契约，不能冒充当前已上线能力。
+
+## 后果
+
+正面结果：
+
+- 不需要 DxC 自建共享 IP 池或集中保管用户站点凭据；
+- 能利用用户本地网络、登录态、文件和 Agent 工具；
+- DxC 不接收原始研究材料；Agent 宿主的数据流向对用户可见；
+- 上游 Skills 可以围绕同一个研究包稳定组合；
+- 抓取组件可以独立升级，不污染发布主干。
+
+代价和限制：
+
+- 用户电脑关机、休眠或 Agent 不常驻时，任务不能保证准点执行；
+- 不同宿主的浏览器能力和权限模型不同，需要能力探测和降级；
+- 直接复用用户默认浏览器 Profile 有并发锁、配置损坏和权限过大的风险，因此不是默认方案；
+- 登录、验证码、会话过期和站点结构变化仍需要用户介入；
+- 本地执行降低云端基础设施风险，但不消除用户账号、版权和站点规则风险。