@deployxai/dxc 0.1.0

package/docs/00-project-context.md

@@ -0,0 +1,125 @@
+# 项目背景与已确认决策
+
+更新日期：2026-07-27
+
+## 1. 已确认的外部条件
+
+- 微信开放平台企业主体认证已完成。
+- “DeployX 内容工作台”微信公众号第三方平台申请已审核通过。
+- 独立的微信网站应用登录能力已经完成平台侧配置；真实 AppID/AppSecret 只存在于 Git
+  之外的安全环境，本仓库不记录其值。
+- 官方域名为 `content.deployxai.com`。
+- `content.deployxai.com` 是 DxC 的 API-only（仅 API）入口，不承载静态官网页面；HTTPS
+  入口将 API、登录授权、微信回调、预览和健康检查路由到 DxC Server，其他路径返回 `404`。
+- 已有 `content-to-wechat` 技能能够通过 `alivps` 完成微信适配渲染、预检、素材上传和草稿创建，可作为行为参考。
+- 本地开发环境已有 Docker MongoDB，DxC 使用独立 `dxc` 数据库，不依赖生产数据库进行开发或测试。
+- DxC 生产 MongoDB 已确定放在 `worker_vps` 的现有实例中，并使用独立 `dxc` 数据库、独立最小权限账号和独立备份策略。
+- 上述部署位置已经确定，但不代表已经授权生产建库或写入；认证、TLS/私网、备份、资源、版本和网络拓扑仍须在部署前只读核验。
+
+受控的公众号授权与固定草稿验证切片已经完成真实验证；当前代码又完成了显式个人微信
+首次注册、通用 Markdown+封面上传、云端不可变预览、确认和通用草稿 Worker，但尚未
+部署。真实凭据始终只在 Git 之外的安全环境中，本仓库不包含其值。
+
+## 2. 产品方向如何演进到当前结论
+
+### 2.1 最初 North Star（北极星愿景）
+
+分享页《博主内容生产系统（Content Forge for Bloggers）》描述了一个面向多博主的完整生产系统：
+
+- 热点和主动意图两种发起方式；
+- 研究、观点、大纲、写作、标题与视觉、发布六类角色；
+- 博主风格、品味、价值观、结构、数据源和平台配置；
+- 多个人工确认闸门；
+- 多平台草稿与分发。
+
+来源：
+
+`https://codebuddy.work/agents/share/AQJrGsUAQfUN57uxVO778ti7XTtpnP1YRgPw4hbdye8zA6Q9DsetIb2qAW-HDAy-?platform=workbuddy`
+
+该文档是长期愿景来源，不是 MVP 实施清单。原文中的以下内容已被后续决策覆盖：
+
+- 第一阶段不实现六类 Agent；
+- 第一阶段不支持其他内容平台；
+- 不让客户提交公众号 AppID/AppSecret；
+- 不把传统 Web 工作台作为首要用户入口；
+- 不在第一阶段正式发布。
+
+### 2.2 产品形态收敛
+
+DxC 被定义为 Agent Native（智能体原生）产品：
+
+- 用户的主要工作界面是 WorkBuddy、Codex 等 Agent；
+- 用户通过自然语言安装并触发 DxC；
+- 本地安装物是 `dxc` CLI、必要依赖和按需安装的 `dxc-*` Skills；
+- 云端提供微信第三方平台、权威渲染、预览、支付、任务和审计；
+- MVP 不需要 MCP。
+
+最终不是“一个 Web 编辑器加 AI 聊天框”，也不是“把所有能力塞进一个 Skill”，而是：
+
+> Agent 负责理解与协作，Skill 负责编排，CLI 负责确定性本地动作，云端负责秘密、状态和不可逆副作用。
+
+### 2.3 商业模式收敛
+
+WorkBuddy 是 MVP 的首发 Agent 平台，SkillHub 是首发分发渠道，SkillPay 是首选支付体验。
+
+计费产品同时保留：
+
+- 单次草稿额度；
+- 手动续费月卡；
+- 手动续费年卡。
+
+SkillPay 当前公开能力以按次调用和 X402 支付触发为主。因此：
+
+- 月卡/年卡由一次支付购买固定期限权益；
+- DxC 云端维护权益和到期时间；
+- MVP 不做自动续费；
+- 公开文档未证明的多价格/多 SKU 行为必须在商户联调阶段现场验证；
+- 若一个 Pay Skill 只能有一个固定价格，则使用多个 `dxc-*` Pay Skills；
+- 对 Codex 或无法识别 SkillPay 的 Agent，长期保留普通微信 Native 支付页适配器。
+
+## 3. 已锁定的产品决策
+
+| 主题 | 决策 |
+|---|---|
+| 首发平台 | WorkBuddy，保留 Codex 兼容边界 |
+| 用户界面 | Agent 对话为主；Web 只承载授权、预览和必要的支付/管理页 |
+| 本地运行时 | Node.js/TypeScript `dxc` CLI |
+| Skill 命名 | 所有机器名以 `dxc-` 开头 |
+| 内容工作流入口 | `dxc-content-workflow`；同时负责首次初始化和后续恢复，不另设安装 Skill |
+| 微信交付 Skill | `dxc-wechat-publisher`；只负责最后的预览、确认和草稿交付 |
+| 微信接入 | 微信开放平台第三方平台扫码授权 |
+| 用户登录 | 独立微信网站应用 `snsapi_login`；显式 `start` 可首次注册，普通 `login` 只恢复已关联 owner |
+| 微信权限 | ID 3 + ID 11；不使用 ID 7 |
+| 发布边界 | 创建草稿并回读；不正式发布、不群发 |
+| 权威渲染 | 云端 |
+| MVP 模板 | 云端固定版本目录：保留 `wechat-minimal@1`，并提供十套 WeMD MIT 设计派生模板；不支持用户 CSS |
+| 数据库 | MongoDB；本地 Docker、生产 `worker_vps`，均使用独立 `dxc` 数据库 |
+| 异步队列 | Mongo 原子租约队列；不引入 Redis |
+| 对象存储 | 通过适配器使用外部对象存储；供应商在部署前绑定 |
+| 支付 | WorkBuddy SkillPay 首选；DxC 云端维护订单与权益 |
+| 收费闸门 | 用户确认创建草稿之后 |
+| 订阅 | 30/365 天固定期限、手动续费 |
+| MCP | MVP 不需要 |
+| MarkItDown | 可选的本地导入工具，按需安装 |
+| 历史内容记忆 | CLI 本地 SQLite + FTS5 + 固定版本中文嵌入模型；显式导入，不同步历史全文 |
+| 入口边界 | `content.deployxai.com` 为 DxC API-only 入口；品牌/法律页面不由该域名承载 |
+
+## 4. MVP 的一句话边界
+
+> 将一个主题或一篇已有内容，自动推进为可确认、可预览、可审计的微信公众号草稿。
+
+当前已建立 `dxc-content-workflow`、本地画像、统一产物/checkpoint、历史文章混合召回
+和八个步骤 Skill。研究、Brief、大纲、正文、标题、视觉生产、审校和微信交付都使用
+同一线性 contract；视觉步骤由 Agent 宿主实际生成图片或选择用户明确指定的本地素材，
+正文图片会进入不可变快照和草稿。视觉阶段必须形成真实内容封面，CLI 不生成占位图。
+
+## 5. 产品原则
+
+1. 普通阶段自动推进，真实路线选择和外部副作用保留人工确认。
+2. 一个稳定主干，多个可选 Skills。
+3. 本地文件属于用户，云端保存发布所需的最小副本。
+4. 真实外部副作用必须幂等、可追溯、可恢复。
+5. 凭据永远不进入 Agent 上下文、CLI 参数、日志或 Git。
+6. 先复刻已验证的极简闭环，再增加模板和上游能力。
+7. 高频迭代不应破坏进行中的文章任务；每次任务固定协议、渲染器和模板版本。
+8. 历史文章由用户显式选择并保留在本机；语义召回必须带原文片段和可追溯哈希，不能把模型相似度当作事实。

package/docs/01-north-star-architecture.md

@@ -0,0 +1,234 @@
+# 终态产品与架构
+
+更新日期：2026-07-26
+
+## 1. 终态产品
+
+DxC 的终态是运行在用户 Agent 环境中的个人内容操作系统：
+
+- Agent 知道用户当前的文章、目标平台、历史偏好和任务上下文；
+- 用户用自然语言触发工作，而不是在多个传统后台之间搬运内容；
+- 用户拥有自己的 Markdown、素材、风格、品味和写作框架；
+- 云端托管必须集中处理的授权、令牌、预览、对象、异步任务和审计；
+- 各项内容能力以 `dxc-*` Skills 独立演进。
+
+长期能力可以沿内容主干逐步增加：
+
+```text
+内容源
+  → dxc-content-workflow（总控）
+  → dxc-topic-scout
+  → dxc-research
+  → dxc-taste-curator
+  → dxc-writing-framework
+  → dxc-style-writer
+  → dxc-humanizer
+  → dxc-visual-designer
+  → dxc-wechat-publisher
+```
+
+这是一张能力地图，不是要求每篇文章必须经过所有步骤。每个 Skill 有独立输入输出契约，用户可以从任何已有产物进入主干。
+
+## 2. 分层架构
+
+```mermaid
+flowchart TB
+    U["用户"]
+    H["Agent Host<br/>WorkBuddy / Codex / 未来宿主"]
+    S["dxc-* Skills<br/>意图、步骤、确认、宿主适配"]
+    C["dxc CLI / Local Runner<br/>确定性工具、校验、证据、上传、状态"]
+    B["Agent Browser / 本地浏览器适配器<br/>公开页面 / 授权登录态"]
+    F["用户工作区<br/>Markdown / 图片 / 风格 / 品味 / 框架"]
+    A["DxC Cloud API<br/>身份、授权、文章快照、权益、审计"]
+    R["Render & Preview<br/>权威渲染、清洗、预检、手机预览"]
+    W["Worker<br/>图片、封面、微信草稿、回读、重试"]
+    D["MongoDB + Object Storage"]
+    X["外部平台<br/>微信开放平台 / 微信支付 / SkillPay"]
+
+    U --> H
+    H --> S
+    S --> C
+    H --> B
+    S --> B
+    B --> F
+    C <--> F
+    C <--> A
+    A --> R
+    A --> W
+    A <--> D
+    R <--> D
+    W <--> D
+    A <--> X
+    W <--> X
+```
+
+### 2.1 Agent Host
+
+宿主负责：
+
+- 对话、文件选择和用户确认；
+- Skill 安装、发现和调用；
+- 按宿主能力调用 Browser/Computer Use，并明确显示工具的本机、宿主管理或远程执行位置；
+- 在 WorkBuddy 中承接 SkillPay 支付交互；
+- 展示 CLI 的结构化结果。
+
+宿主不是业务真值。不同 Agent 的上下文格式、工具名和 UI 不能渗入领域模型。
+
+### 2.2 `dxc-*` Skills
+
+Skill 负责：
+
+- 判断何时触发一项内容能力；
+- 组织 CLI/API 调用顺序；
+- 向用户解释检查结果和风险；
+- 在不可逆动作前取得确认；
+- 对不同 Agent 宿主做薄适配。
+
+Skill 不负责：
+
+- 保存长期 token；
+- 实现复杂 Markdown 渲染；
+- 直接拼接微信 API 请求；
+- 维护队列和支付账本；
+- 把多步状态仅保存在对话上下文中。
+- 临时安装未经锁定的爬虫依赖或把浏览器凭据交给云端。
+
+因此，未来扩展主要用 Skills 承载是足够的，但前提是稳定能力继续由 CLI 和云端提供。DxC 不需要自建一个通用 Agent 框架。
+
+### 2.3 `dxc` CLI
+
+CLI 是本地可重复执行的工具层：
+
+- 检测环境和版本；
+- 管理本地登录/设备会话；
+- 读取 Markdown、图片和可选导入文件；
+- 做快速本地校验；
+- 上传内容包；
+- 打开授权和预览 URL；
+- 轮询任务状态；
+- 将结果写入用户工作区。
+- 保存版本化创作偏好、项目清单和统一步骤 checkpoint；
+- 显式导入历史文章，并提供本地关键词/语义混合召回；
+- 为 Agent 提供公开来源、RSS、用户授权本地浏览器会话所需的确定性适配器；
+- 保存来源、时间、抽取器版本、内容哈希和本地自动化运行记录；
+- 按能力清单调用版本化的可选抓取工具包。
+
+CLI 必须支持 `--json`，供 Agent 稳定调用。自然语言文案可以变化，机器字段不能随意变化。
+
+研究抓取采用“Agent 主编排、本地优先”边界：Agent 可使用宿主 Browser/Computer Use；可重复任务由本地 Runner 或宿主可靠自动化执行。每次运行记录 `executionLocation` 和 `dataTransit`；只有明确为 `local-device` 且数据路径经用户接受的适配器才能读取登录态。DxC CLI/Cloud 不上传 Cookie、Token、原始页面、截图或全文，但 Agent 宿主的数据处理仍受其自身政策约束。Skill 只声明 `source.fetch.*`、`browser.page.capture.authenticated@1`、`research.pack.write@1` 等能力，不携带任意安装脚本。完整决策见 [ADR-0004](decisions/0004-local-first-agent-research-runtime.md)。
+
+本地内容记忆与研究抓取分开：用户显式导入自己的历史文章后，CLI 用 SQLite 保存文章/分段真值、FTS5 做字面召回、固定 revision 的本地中文嵌入模型做语义召回，再用 RRF 合并排名。它不自动监听目录、不上传历史全文，也不负责判断某个片段必然是“案例”或“金句”。完整决策见 [ADR-0005](decisions/0005-official-skill-orchestration-and-local-content-memory.md)。
+
+### 2.4 用户工作区
+
+用户拥有以下内容：
+
+- Markdown 母稿；
+- 原始图片和封面；
+- 可选的 `dxc.project.json`；
+- `artifacts/` 中八类可见产物和 `.dxc/checkpoints/` 中的本地执行状态；
+- 写作风格、品味、框架和偏好文件；
+- 发布结果和审计摘要的本地副本。
+
+用户级创作画像和历史文章数据库默认位于 `~/.dxc/`，不放进文章项目或 Git。DxC 升级不得覆盖用户内容。云端只保存完成服务所需的副本，并遵循保留期限。
+
+### 2.5 云端
+
+云端集中处理：
+
+- DxC 设备/用户/租户身份；
+- 微信第三方平台回调和令牌生命周期；
+- 权威渲染、清洗和预检；
+- 短时预览；
+- 异步素材与草稿任务；
+- SkillPay/微信支付和权益；
+- 多租户隔离、审计、撤销和删除。
+
+这些能力不能放到本地，因为平台密钥不能下发、回调需要公网稳定入口、固定出口 IP 需要集中管理，且服务端升级可以统一修复渲染和平台兼容问题。
+
+DxC Server、Worker 和其他 DxC Cloud 组件不向第三方内容源发起研究抓取请求，不建设共享抓取 IP 池，也不集中保存第三方站点 Cookie。云端只接收用户另行确认的研究包最小投影、Brief 或文章；第三方 Agent 宿主是否远程处理页面内容必须另行向用户披露。改变这一边界必须新增 ADR。
+
+## 3. 稳定契约
+
+终态架构围绕几个稳定中间产物和本地控制契约演进：
+
+1. `ContentProfile`：版本化的本地创作偏好，不含凭据。
+2. `ContentProjectManifest`：文章项目、固定步骤顺序和产物路径。
+3. `StepCheckpoint`：步骤状态、产物哈希、执行位置、数据去向和人工确认。
+4. `KnowledgeHit`：有界历史片段及文章/分段 ID、章节和哈希。
+5. `ContentBrief`：上游不同来源归一化后的内容命题。
+6. `ArticleSource`：用户可编辑的 Markdown 与元数据。
+7. `RenderSnapshot`：固定源内容、模板和渲染器版本的不可变结果。
+8. `Approval`：用户对特定快照和目标账号的明确确认。
+9. `DeliveryIntent`：请求向某个平台执行一次副作用。
+10. `DeliveryResult`：平台 ID、回读结果和可审计错误。
+
+当前发布 MVP 从 `ArticleSource` 开始；上游框架已经固定前四类本地契约，但不代表各内容 Skill 已实现。未来热点、研究和写作 Skills 产生或修改 `ContentBrief`/`ArticleSource`，不改变微信发布主干。
+
+## 4. 云端渲染为何是长期正确边界
+
+云端渲染带来的直接收益：
+
+- 所有 Agent、Windows 和 macOS 得到一致结果；
+- 可以修复微信兼容问题而不等待所有 CLI 升级；
+- 可以增加新模板并对每次结果固定版本；
+- 预览与最终提交使用同一 HTML；
+- 服务端可以执行统一清洗、长度和图片检查；
+- 不把复杂、易漂移的平台规则散落在多个 Skills 中。
+
+模板扩展方式：
+
+- MVP 使用固定、版本化的云端模板目录；不提供模板市场或用户 CSS；
+- 模板是版本化代码和样式令牌，不是任意用户 CSS；
+- 新模板必须有黄金样例、回归测试和兼容说明；
+- 已确认的文章永远固定原模板版本；
+- 模板市场和用户模板不进入当前路线。
+
+## 5. 安装与升级
+
+目标安装体验：
+
+> 用户在 Agent 中提供官方安装链接并说“安装 DeployX 内容工作台”，Agent 阅读版本化安装说明，安装 `dxc` CLI 和 `dxc-content-workflow`，执行 `dxc doctor`，随后由总控 Skill 初始化偏好、可选历史内容记忆和公众号绑定。
+
+升级分三层：
+
+- 云端：兼容性变更可即时发布，但 API 必须向后兼容受支持的 CLI 协议。
+- Skill：WorkBuddy 通过 SkillHub 版本管理；其他宿主由 CLI 同步官方 Skill。
+- CLI：使用带校验和的版本清单，支持 `preview` 和 `stable` 渠道、原子替换和回滚。
+
+频繁迭代阶段默认使用 `preview` 渠道，但：
+
+- 不在发布流程中途升级；
+- 每个任务记录 CLI、Skill、协议、模板和渲染器版本；
+- 用户风格、品味和框架文件永不被升级覆盖；
+- 强制升级只用于安全或协议完全不兼容的版本。
+
+## 6. 可选文件导入
+
+Markdown 是稳定母稿。其他格式先转换成可编辑 Markdown，再进入云端渲染。
+
+Microsoft MarkItDown 作为可选本地工具：
+
+- `.md`：直接处理；
+- `.docx`、文本型 `.pdf`：用户同意后在隔离环境按需安装 MarkItDown；
+- 扫描 PDF：返回 `OCR_REQUIRED`，MVP 不自动上传云端 OCR；
+- 插件和远程 URL 默认禁用；
+- 转换结果必须保存为用户可查看、可修改的 `.md`。
+
+MarkItDown 不是 CLI 基础依赖，缺少时不影响普通 Markdown 发布。
+
+## 7. 未来平台扩展
+
+未来每个平台通过独立发布适配器和 Skill 接入：
+
+- 共享 `ArticleSource`、`RenderSnapshot`、`Approval` 和审计协议；
+- 平台渲染、限制、授权和发布状态机独立；
+- 不为了未来平台提前抽象一个“万能发布 API”；
+- 只有第二个平台进入实现时，才从微信实现中提取真正共享的部分。
+
+微信公众号正式发布可以作为未来能力，但必须：
+
+- 单独申请并核验 ID 7；
+- 使用新的 Skill/动作和更强确认；
+- 与草稿创建权限和审计分离；
+- 不改变 MVP “用户到公众号后台手动发布”的承诺。