@deployxai/dxc 0.1.0

package/docs/03-domain-state-api.md

@@ -0,0 +1,599 @@
+# 领域模型、状态机与接口
+
+更新日期：2026-07-30
+
+## 1. 领域对象
+
+### 1.1 身份与租户
+
+| 对象 | 关键字段 | 说明 |
+|---|---|---|
+| `Tenant` | `id`, `name`, `status`, `createdAt` | DxC 内容空间 |
+| `User` | `id`, `tenantId`, `role`, `status` | 为后续团队协作保留；MVP 可只有 owner |
+| `ExternalIdentity` | `provider`, `subjectHash`, `unionIdHash`, `userId` | 独立网站应用个人微信等身份映射；不保存原始 openid/unionid |
+| `DeviceBindingSession` | `challengeHash`, `publicKeyFingerprint`, `status`, `expiresAt` | 首次扫码前的短时设备持钥证明 |
+| `DeviceIdentity` | `tenantId`, `publicKey`, `status`, `lastSeenAt` | CLI 设备身份，不保存设备私钥 |
+| `DeviceSession` | `deviceId`, `tokenHash`, `refreshTokenHash`, `expiresAt`, `refreshExpiresAt`, `revokedAt` | 24 小时访问会话和 30 天可轮换刷新凭据 |
+
+### 1.2 微信
+
+| 对象 | 关键字段 | 说明 |
+|---|---|---|
+| `WechatAuthorizationSession` | `stateHash`, `deviceId`, `status`, `expiresAt` | 扫码授权的短时关联 |
+| `WechatLoginSession` | `purpose`, `stateHash`, `pollTokenHash`, `subjectHash`, `status` | `start`/`link`/`login` 个人微信状态；与公众号授权分离 |
+| `WechatAuthorization` | `tenantId`, `authorizerAppId`, `permissionSet`, `status` | 授权关系 |
+| `WechatCredentialEnvelope` | `ciphertext`, `iv`, `tag`, `keyVersion` | 加密的 refresh/access token |
+| `WechatAccount` | `tenantId`, `authorizerAppId`, `displayName`, `accountType` | 给用户选择的公众号信息 |
+| `ComponentTicket` | `ciphertext`, `receivedAt`, `expiresAt` | 平台级票据，非租户字段 |
+
+`WechatAuthorization` 和 `WechatAccount` 分开：授权关系可以撤销/重建，账号展示信息可以刷新并保留历史。
+
+### 1.3 内容与交付
+
+| 对象 | 关键字段 | 说明 |
+|---|---|---|
+| `ArticleSource` | `tenantId`, `title`, `sourceHash`, `coverHash`, `assetManifestHash`, `inlineAssets[]` | 用户上传的正文、封面和正文图片版本 |
+| `Asset` | `tenantId`, `sha256`, `kind`, `objectKey`, `mediaType`, `size` | 原始正文图片或封面 |
+| `RenderSnapshot` | `articleSourceId`, `templateId`, `rendererVersion`, `htmlHash`, `inlineAssets[]` | 绑定完整素材清单的不可变渲染结果 |
+| `PreflightResult` | `errors[]`, `warnings[]`, `metrics` | 结构化检查结果 |
+| `Approval` | `snapshotId`, `targetAccountId`, `approvedBy`, `approvedAt` | 用户对快照和账号的确认 |
+| `DraftIntent` | `approvalId`, `idempotencyKey`, `entitlementReservationId` | 一次创建草稿意图 |
+| `DraftDelivery` | `intentId`, `status`, `wechatMediaId`, `verification` | 微信副作用和回读结果 |
+| `Job` | `kind`, `resourceId`, `status`, `lease`, `attempt` | Mongo 异步任务 |
+| `AuditEvent` | `tenantId`, `actor`, `action`, `resource`, `metadata` | 追加式审计 |
+
+固定真实联调继续使用 `WechatDraftSmokeIntent`。正式首位用户路径已经使用
+`ArticleSource`、`RenderSnapshot`、`Approval` 和 `DraftIntent`；Worker 的特权调度仓储
+跨租户原子领取和有界恢复意图，领取后所有业务资源查询与状态转移仍显式包含任务自带的
+`tenantId`。独立的通用 `DraftDelivery` 和带 lease（租约）/heartbeat（心跳）的 `Job`
+仍未拆出。
+
+### 1.4 计费
+
+| 对象 | 关键字段 | 说明 |
+|---|---|---|
+| `Offering` | `code`, `durationDays`, `creditCount`, `status` | 单次/月卡/年卡商品 |
+| `PaymentOrder` | `tenantId`, `offeringCode`, `channel`, `outTradeNo`, `status` | 微信支付/SkillPay 订单 |
+| `PaymentEvent` | `orderId`, `sourceEventId`, `verifiedPayloadDigest` | 幂等支付事件 |
+| `Entitlement` | `tenantId`, `kind`, `validFrom`, `validUntil`, `status` | 固定期限权益 |
+| `CreditWallet` | `tenantId`, `granted`, `reserved`, `consumed` | 单次额度，单文档原子更新 |
+| `CreditReservation` | `walletId`, `intentId`, `status` | 预留、消费、释放、冻结 |
+| `UsageLedger` | `tenantId`, `eventType`, `referenceId`, `delta` | 不可变用量流水 |
+
+### 1.5 本地内容工作流
+
+以下对象只存在于用户设备，不进入 Mongo：
+
+| 对象 | 关键字段 | 说明 |
+|---|---|---|
+| `ContentProfile` | `questionnaireVersion`, `answers[]`, `profileId`, `updatedAt` | `~/.dxc/content-profile.json` 中的版本化创作偏好 |
+| `ContentProjectManifest` | `workflowId`, `projectId`, `artifacts`, `checkpointsDirectory` | 项目根目录 `dxc.project.json` |
+| `ContentProjectIndex` | `projectId`, `title`, `directory`, `updatedAt` | `~/.dxc/content-projects.json` 中的轻量恢复索引；不含文章正文 |
+| `StepCheckpoint` | `stage`, `status`, `inputs`, `outputs`, `waitingFor`, `confirmationBinding`, `execution` | 八个步骤统一使用的 v3 本地阶段 contract |
+| `StageArtifact` | `dxc.contract`, `workflowId`, `projectId`, `stage`, `skill`, `createdAt`, `artifactStatus`, `inputs[]` | 用户可读 Markdown 产物中的 `dxc-content-stage@1` 轻量元数据 |
+| `KnowledgeArticle` | `articleId`, `sourceLabel`, `contentSha256`, `chunkCount` | 显式导入的历史文章元数据 |
+| `KnowledgeChunk` | `chunkId`, `articleId`, `heading`, `body`, `chunkSha256`, `embedding` | 有界分段、FTS5 和本地向量真值 |
+| `KnowledgeHit` | `articleId`, `chunkId`, `snippet`, `lanes`, `rank` | 交给内容 Skill 的可追溯候选片段；不暴露会被误当置信度的模型分数 |
+
+`StepCheckpoint.status` 为 `running | awaiting-user | completed | failed | skipped`。v3
+contract 记录实际输入和输出的路径、大小与 SHA-256，并用 `metadata.summary` 和
+`waitingFor` 支持跨会话恢复。`confirmationBinding` 对真实确认结构化保存 `status`、
+`snapshotType`、`snapshotHash`、`requestedAt`、`confirmedAt` 和 `confirmedBy`；
+`awaiting-user` 和 `completed` 必须绑定非空输出。输出或输入缺失、变空或哈希改变时，
+读取结果为 `stale`，不能直接推进后续步骤。普通内部步骤完成不要求人工确认；真实用户
+决策缺少 `--confirm` 时保持 `awaiting-user` 并返回 guidance（引导），不会只抛出异常。
+完成确认时必须存在同类型、同哈希的上一条 pending（待确认）绑定；正文使用稳定的
+用户可见内容哈希，标题使用候选与最终选择的内容哈希，交付使用经过产物校验的
+`renderSnapshot.snapshotHash`。内容或已选标题变化后必须重新进入 `awaiting-user`。
+每个检查点同时记录 `executionLocation` 和 `dataTransit`，避免把 Agent 调用自动宣称为
+本机执行。v1/v2 只读兼容，下一次写入升级为 v3。
+
+`StageArtifact` 不替代 checkpoint，也不引入第二套复杂状态机。它让用户和新会话直接
+打开 Markdown 就能知道产物由哪个阶段生成、读取了哪些上游哈希。CLI 在接受
+`awaiting-user` 或 `completed` 前会解析其 frontmatter，核对固定 Skill 版本、项目、
+工作流、实际输入和阶段特有字段；视觉产物还要通过真实文件、格式、体积和哈希校验。
+checkpoint 仍是定位下一阶段、判断 stale 和恢复 `waitingFor` 的机器真值。
+
+## 2. Mongo 集合和核心索引
+
+建议集合：
+
+```text
+tenants
+users
+external_identities
+device_binding_sessions
+device_identities
+device_sessions
+wechat_login_sessions
+wechat_login_identities
+wechat_authorization_sessions
+wechat_authorizations
+wechat_accounts
+component_tickets
+articles
+assets
+render_snapshots
+approvals
+draft_intents
+draft_deliveries
+jobs
+offerings
+payment_orders
+payment_events
+entitlements
+credit_wallets
+credit_reservations
+usage_ledger
+audit_events
+wechat_draft_smoke_intents
+```
+
+必须建立的唯一/查询索引：
+
+- `wechat_login_identities(subjectHash)` unique；
+- `wechat_login_identities(unionIdHash)` partial unique；
+- `wechat_login_identities(tenantId, userId)` unique；
+- `wechat_login_sessions(stateHash)` 和 `(pollTokenHash)` unique，`cleanupAt` TTL；
+- `device_identities(publicKeyFingerprint)` 和 `(tenantId, installationId)` unique；`(tenantId, status)` 只做查询，不限制同租户多设备；
+- `device_sessions(tokenHash)` unique，`refreshTokenHash` partial unique，`cleanupAt` TTL；
+- `wechat_authorizations(authorizerAppId, status=active)` partial unique；
+- `assets(tenantId, sha256, kind)` unique；
+- `articles(tenantId, sourceHash, coverHash, assetManifestHash)` unique；
+- `render_snapshots(tenantId, sourceHash, assetManifestHash, templateId, rendererVersion)` unique；
+- `approvals(tenantId, snapshotId, targetAccountId, approvedAt)`；
+- `draft_intents(tenantId, idempotencyKey)` unique；
+- `draft_deliveries(tenantId, intentId)` unique；
+- `payment_orders(outTradeNo)` unique；
+- `payment_events(sourceEventId)` unique；
+- `credit_reservations(tenantId, intentId)` unique；
+- `jobs(status, nextRunAt, leaseExpiresAt)`；
+- `wechat_draft_smoke_intents(tenantId, idempotencyKeyHash)` unique；
+- `wechat_draft_smoke_intents(status, createdAt)`，供特权调度仓储跨租户原子领取固定测试意图；
+- `wechat_draft_smoke_intents(status, updatedAt)`，供特权调度仓储按固定批次恢复中断意图；
+- 领取后的授权、快照、素材、状态转移与审计查询仍显式包含任务自带的 `tenantId`；
+- 短时会话、预览和过期诊断对象使用 TTL 索引。
+
+所有面向租户的仓储方法必须接收 `TenantContext`，不允许调用者传一个可选 `tenantId`。
+
+## 3. 状态机
+
+### 3.1 微信授权会话
+
+```mermaid
+stateDiagram-v2
+    [*] --> CREATED
+    CREATED --> URL_READY
+    URL_READY --> EXCHANGING: 原子认领授权码
+    EXCHANGING --> AUTHORIZED: 加密授权结果已持久化
+    AUTHORIZED --> BOUND: 账号与租户绑定完成
+    CREATED --> EXPIRED
+    URL_READY --> EXPIRED
+    URL_READY --> CANCELLED
+    URL_READY --> FAILED
+    EXCHANGING --> FAILED: 明确失败或不确定结果到期
+    AUTHORIZED --> FAILED
+    BOUND --> [*]
+```
+
+`EXCHANGING` 是外部授权码消费的不可逆边界。只有成功持久化加密 access/refresh token、账号投影目标和租户目标后，才能进入 `AUTHORIZED`；此后的身份、账号和授权投影均从该检查点幂等恢复。若进程在微信返回后、检查点写入前中断，回调重放不得再次调用 `api_query_auth`，会话到期后进入 `FAILED` 并要求重新扫码。
+
+授权入口固定为 15 分钟。设备绑定在授权会话创建时延长到同一绝对截止时间，避免设备挑战的初始 10 分钟窗口提前截断扫码。成功交换授权码后，绑定与 `AUTHORIZED` 会话进入最长 24 小时的投影恢复窗口；写入顺序为“先延长匹配的绑定会话，再写 `AUTHORIZED` 检查点”。恢复窗口不是新的授权入口，过期后必须进入 `FAILED`，不得再创建身份、账号或设备会话。
+
+账号授权关系：
+
+```text
+ACTIVE → REFRESH_DEGRADED → ACTIVE
+ACTIVE → REVOKED
+ACTIVE → PERMISSION_CHANGED
+PERMISSION_CHANGED → ACTIVE | REVOKED
+```
+
+`REFRESH_DEGRADED` 表示当前 access token 可能仍可用但刷新失败；它不是立即删除授权的理由。`REVOKED` 禁止创建新任务。
+
+### 3.2 个人微信登录会话
+
+```text
+URL_READY → EXCHANGING → IDENTIFIED → SUCCEEDED
+        └──────────────→ FAILED
+        └──────────────→ EXPIRED
+```
+
+`purpose=link` 必须绑定当前有效设备会话；`purpose=login|start` 必须绑定尚未完成的设备
+持钥证明。`login` 只查找已有映射，没有映射时进入
+`FAILED/WECHAT_LOGIN_IDENTITY_NOT_LINKED`；用户显式触发的 `start` 才可为未关联身份创建
+owner，并用确定性候选 UUID + Mongo 原子 bootstrap 收敛并发请求。`EXCHANGING` 表示
+网站 OAuth code 已被原子认领；微信返回的 OAuth access/refresh token 只在内存中用于
+解析身份，随后立即丢弃。`IDENTIFIED` 只保存作用域化 SHA-256 身份摘要，是防止 code
+重放的恢复检查点。
+
+### 3.3 渲染与确认
+
+```text
+UPLOADED
+  → RENDERING
+  → PREFLIGHT_FAILED
+  → READY_FOR_PREVIEW
+  → APPROVED
+  → STALE
+```
+
+允许转换：
+
+- `PREFLIGHT_FAILED → RENDERING`：用户修复或渲染器重试；
+- `READY_FOR_PREVIEW → APPROVED`：用户确认；
+- `READY_FOR_PREVIEW/APPROVED → STALE`：源内容、素材、模板或渲染器发生变化；
+- `STALE` 不能创建草稿，必须产生新快照。
+
+### 3.4 草稿交付
+
+```mermaid
+stateDiagram-v2
+    [*] --> INTENT_CREATED
+    INTENT_CREATED --> ENTITLEMENT_REQUIRED
+    ENTITLEMENT_REQUIRED --> INTENT_CREATED: 权益已授予
+    INTENT_CREATED --> QUEUED: 权益预留成功
+    QUEUED --> PREPARING
+    PREPARING --> UPLOADING_ASSETS
+    UPLOADING_ASSETS --> CREATING_DRAFT
+    CREATING_DRAFT --> VERIFYING
+    CREATING_DRAFT --> FAILED: 已验签响应明确拒绝
+    CREATING_DRAFT --> CREATED_UNVERIFIED: 请求结果不确定
+    VERIFYING --> SUCCEEDED
+    VERIFYING --> CREATED_UNVERIFIED: 回读暂时失败
+    CREATED_UNVERIFIED --> VERIFYING: 核验任务
+    CREATED_UNVERIFIED --> NEEDS_MANUAL_REVIEW
+    PREPARING --> RETRY_WAIT
+    UPLOADING_ASSETS --> RETRY_WAIT
+    RETRY_WAIT --> QUEUED
+    PREPARING --> FAILED
+    UPLOADING_ASSETS --> FAILED
+    VERIFYING --> FAILED
+    FAILED --> [*]
+    SUCCEEDED --> [*]
+    NEEDS_MANUAL_REVIEW --> [*]
+```
+
+关键规则：
+
+- 进入 `CREATING_DRAFT` 后，网络超时不能直接重新调用 `draft/add`。
+- `CREATING_DRAFT → FAILED` 只允许用于已通过微信平台响应验签，且正文明确返回“未创建”的 API 拒绝。超时、断线、响应验签失败、证书序列号未知、响应解密失败或其他无法证明结果的情况必须进入 `CREATED_UNVERIFIED`。
+- `CREATED_UNVERIFIED` 的处理是回读、按内容指纹/时间窗口核验或人工处理。
+- 只有能证明微信没有创建草稿时，才允许同一意图重新创建。
+- `SUCCEEDED` 需要 `draft/get` 回读，至少核对 media ID、标题、作者、摘要和内容哈希/结构指标。
+
+受控单账号联调只使用以下状态子集：
+
+```text
+QUEUED
+  → PREPARING
+  → UPLOADING_ASSETS
+  → CREATING_DRAFT
+  → VERIFYING
+  → SUCCEEDED
+```
+
+旁路终态为 `FAILED`、`ASSET_UPLOAD_UNVERIFIED` 和 `CREATED_UNVERIFIED`。永久封面上传的结果无法确认时进入 `ASSET_UPLOAD_UNVERIFIED`，停止调用 `draft/add`；`draft/add` 或回读结果无法确认时进入 `CREATED_UNVERIFIED`。这个切片不提供自动 reconciliation（核验补偿）；出现任一未确认状态后必须停止再次提交，先由人工在公众号后台核对。
+
+### 3.5 Job
+
+```text
+QUEUED → RUNNING → SUCCEEDED
+              ↘ RETRY_WAIT → QUEUED
+              ↘ FAILED
+              ↘ DEAD
+```
+
+- `FAILED`：确定性业务失败，不再自动重试；
+- `DEAD`：达到重试上限或租约异常，需要人工；
+- Worker 只领取 `QUEUED` 且 `nextRunAt <= now` 的任务；
+- Worker 必须使用 compare-and-set（比较并更新）完成终态写入。
+
+### 3.6 支付订单
+
+```text
+CREATED
+  → PAYMENT_REQUIRED
+  → USER_AUTHORIZING
+  → PAID
+  → FULFILLED
+```
+
+旁路状态：
+
+- `EXPIRED`
+- `CLOSED`
+- `REFUND_PENDING`
+- `REFUNDED`
+- `PAID_UNFULFILLED`
+- `RECONCILIATION_REQUIRED`
+
+收到重复回调时返回成功，但不重复授予权益。Agent 声称支付成功不能推动状态；只有验签回调或服务端查单可以。
+
+### 3.7 额度预留
+
+```text
+RESERVED → CONSUMED
+RESERVED → RELEASED
+RESERVED → FROZEN → CONSUMED | RELEASED | MANUAL
+```
+
+`CREATED_UNVERIFIED` 对应 `FROZEN`，避免同一额度既被释放又对应一个可能已存在的草稿。
+
+## 4. HTTP API
+
+所有业务 API 使用 `/api/v1`，返回统一 envelope：
+
+```json
+{
+  "data": {},
+  "requestId": "req_...",
+  "error": null
+}
+```
+
+错误：
+
+```json
+{
+  "data": null,
+  "requestId": "req_...",
+  "error": {
+    "code": "ENTITLEMENT_REQUIRED",
+    "message": "需要购买权益后继续",
+    "retryable": false,
+    "details": {}
+  }
+}
+```
+
+`message` 给人看，Agent/CLI 只能按稳定 `code` 分支。
+
+### 4.1 健康和配置
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/health/live` | 进程存活 |
+| GET | `/health/ready` | 配置和依赖就绪，只返回分类状态 |
+| GET | `/api/v1/meta/compatibility` | CLI/协议/Skill 支持范围 |
+
+### 4.2 设备和身份
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/device-binding-sessions` | 创建设备绑定挑战 |
+| POST | `/api/v1/device-binding-sessions/{id}/proof` | 提交 Ed25519 持钥证明；签名同时绑定候选访问/刷新 Token 哈希，并取得短时绑定 Token |
+| GET | `/api/v1/device-sessions/current` | 查询当前设备、用户和租户 |
+| POST | `/api/v1/device-sessions/current/refresh-credential` | 老会话在仍有效时登记首个设备刷新凭据 |
+| POST | `/api/v1/device-sessions/refresh` | 刷新 Token + 设备签名轮换下一组访问/刷新 Token |
+| DELETE | `/api/v1/device-sessions/current` | 注销/撤销当前设备 |
+| POST | `/api/v1/auth/wechat/login-sessions` | 创建 `start`、`link` 或 `login` 个人微信会话 |
+| GET | `/api/v1/auth/wechat/login-sessions/{id}` | 使用独立 poll Token 查询个人关联/登录结果 |
+| GET | `/auth/wechat/login` | 同域个人微信登录发起页 |
+| GET | `/callbacks/wechat/login` | 网站应用 OAuth 回调 |
+
+设备访问会话有效期为 24 小时，设备刷新凭据有效期为 30 天。两个明文 Token 都只在 CLI 本机生成，Server 只保存 SHA-256；刷新同时要求设备 Ed25519 签名，并把下一组 Token 哈希和 `rotationId` 绑定到签名消息。同一轮请求可幂等重放恢复，其他旧刷新 Token 重放被拒绝。个人登录和公众号授权各自使用独立 poll Token，只能查询对应会话，不能调用设备、账号、预览、任务或草稿接口。
+
+设备会话撤销也取消由该设备发起、尚未投影完成的新增公众号授权。Server 在消费微信授权码前、形成 `AUTHORIZED` 检查点前及恢复投影前，按 session 固化的 `deviceSessionId + deviceId + tenantId + userId` 重新读取并校验未撤销且未过期的设备会话；失效时授权会话进入 `FAILED`，不调用或不继续投影微信副作用。首次设备绑定尚无既有设备会话，改由短时绑定会话和持钥证明约束。
+
+### 4.3 微信授权
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/wechat/authorization-sessions` | 创建第三方平台授权会话 |
+| GET | `/api/v1/wechat/authorization-sessions/{id}` | 查询授权状态 |
+| GET | `/api/v1/wechat/accounts` | 列出已授权账号 |
+| GET | `/api/v1/wechat/accounts/{id}` | 账号详情和权限 |
+| DELETE | `/api/v1/wechat/accounts/{id}/binding` | 在 DxC 停用绑定；提示用户同步从微信侧取消 |
+| GET | `/authorize/wechat/start` | 与第三方平台配置同域的授权发起页；验证短时加密入口后才展示微信官方授权链接 |
+| POST | `/callbacks/wechat/component-events` | ticket、授权、取消和权限变更回调 |
+| POST | `/callbacks/wechat/authorizers/{APPID}/callback` | 被授权公众号消息与事件回调 |
+| GET | `/authorize/wechat/callback` | 官方授权页面回跳 |
+
+回调不得使用设备会话鉴权；它们使用微信签名/AES 验证、重放保护和来源限制。
+
+旧版授权会话 Token 不再被解释为设备会话。身份版本上线后，旧 CLI 必须重新执行设备持钥证明和公众号扫码；`connect` 可识别精确旧会话文件并在成功后覆盖，但不会把旧 Token 发给 Server。Server 不提供把旧授权 Token 静默提升为设备 Token 的兼容路径。
+
+### 4.4 文章、渲染和预览
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/uploads` | 创建短时、哈希和媒体类型绑定的上传会话 |
+| PUT | `/api/v1/uploads/{id}/content?token=...` | 同源上传明确选择的正文、正文图片或封面；仍需设备会话 |
+| POST | `/api/v1/articles` | 用已完成的正文、封面和有界正文图片清单创建内容寻址文章版本 |
+| POST | `/api/v1/articles/{id}/render-snapshots` | 创建权威渲染快照 |
+| POST | `/api/v1/render-snapshots/{id}/preview-links` | 创建短时预览链接 |
+| GET | `/previews/{token}` | no-store、noindex、严格 CSP 的不可变预览 |
+| GET | `/previews/{token}/cover` | 同一预览 token 绑定的封面 |
+| GET | `/previews/{token}/assets/{index}` | 同一预览 token 和快照绑定的正文图片 |
+| POST | `/api/v1/render-snapshots/{id}/approvals` | 确认快照和目标账号 |
+
+当前首位用户切片使用短时同源上传 URL，由 Server 校验长度和 SHA-256 后写入对象存储；
+URL 的 origin（源）必须与配置的 API origin 相同。后续若改成对象存储预签名直传，不改变
+文章、快照和确认契约。
+
+### 4.5 草稿
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/draft-intents` | 创建幂等草稿意图 |
+| GET | `/api/v1/draft-intents/{id}` | 意图、交付状态、Worker 阶段和建议轮询间隔 |
+
+`POST /draft-intents` 必须携带 `Idempotency-Key`。同一个 key 和同一请求摘要返回相同
+资源；同 key 不同摘要返回 `PUBLISHING_IDEMPOTENCY_CONFLICT`。当前状态、微信 media ID
+和回读验证直接投影在 `DraftIntent`；独立 `DraftDelivery`、权益确认接口和自动
+reconcile（核验补偿）是后续阶段。
+
+受控单账号真实草稿联调使用以下临时纵向接口：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/wechat/draft-smoke-previews` | 为明确选择的账号返回固定测试文章和不可变 `snapshotHash` |
+| POST | `/api/v1/wechat/draft-smoke-intents` | 接收 `accountId + snapshotHash + confirmed=true`，以 `Idempotency-Key` 排队 |
+| GET | `/api/v1/wechat/draft-smoke-intents/{id}` | 查询固定测试草稿状态和脱敏结果 |
+
+这三个接口仍要求 DxC 设备会话并强制租户边界。它们不接受任意文章正文，不能绕过快照确认，也不是完整 P5/P6 API 的替代品。
+
+### 4.6 权益与支付（规划，尚未实现）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/v1/entitlements` | 当前期限和额度 |
+| GET | `/api/v1/offerings` | 可购买商品 |
+| POST | `/api/v1/purchase-intents` | 创建购买意图 |
+| POST | `/api/v1/purchase-intents/{id}/skillpay` | 生成 X402 支付触发 |
+| GET | `/api/v1/payment-orders/{id}` | 查询支付和履约状态 |
+| POST | `/callbacks/wechat-pay/transactions` | 微信支付通知 |
+
+SkillPay 路由可能返回 HTTP 402，并同时提供标准 Header 和 JSON Body。CLI 必须原样保留稳定支付字段，不能把它压扁成一段错误文本。
+
+## 5. CLI 命令契约
+
+当前已实现命令：
+
+```text
+dxc doctor --json
+dxc version --json
+dxc skills install --target <workbuddy|codex> [--force] [--json]
+dxc setup --server <https-url>
+
+dxc profile status --json
+dxc profile save --input <answers.json> --json
+
+dxc project init [--directory <directory>] --title <title> \
+  [--knowledge <files...>] [--lexical-only] --json
+dxc project resolve [title-or-project-id] [--directory <directory>] --json
+dxc project status [--directory <directory>] --json
+dxc project checkpoint <stage> \
+  --status <running|awaiting-user|completed|failed|skipped> \
+  --skill <dxc-skill> \
+  --skill-version <version|unknown> \
+  [--inputs <artifact,artifact>] \
+  --summary <stage-summary> \
+  [--waiting-for <user-question>] \
+  [--confirm] \
+  [--confirmed-by <actor>] \
+  [--confirmation-snapshot <sha256>] \
+  --execution-location <local-device|agent-hosted|unknown> \
+  --data-transit <local-only|agent-provider|dxc-cloud|unknown> \
+  --json
+
+dxc knowledge status --json
+dxc knowledge import <files...> --json
+dxc knowledge search <query> --mode <hybrid|lexical|semantic> --limit 8 --json
+dxc knowledge remove <article-id> --json
+
+dxc auth status
+dxc auth start --server <https-url>
+dxc auth link-wechat
+dxc auth login
+dxc auth logout
+
+dxc wechat connect --server <https-url>
+dxc wechat accounts
+
+dxc wechat draft preview \
+  --article <article.md> \
+  [--assets-directory <local-images>] \
+  [--cover <cover.png-or-jpeg|auto>] \
+  --account <account-id> \
+  --title <confirmed-title>
+dxc wechat draft preview-refresh \
+  --snapshot <snapshot-id> \
+  --snapshot-hash <snapshot-hash>
+dxc wechat draft create \
+  --account <account-id> \
+  --snapshot <snapshot-id> \
+  --snapshot-hash <snapshot-hash> \
+  --idempotency-key <stable-key> \
+  --confirm
+dxc wechat draft status <intent-id>
+
+dxc wechat draft smoke-preview --account <account-id>
+dxc wechat draft smoke-create \
+  --account <account-id> \
+  --snapshot <snapshot-hash> \
+  --idempotency-key <stable-key> \
+  --confirm
+dxc wechat draft smoke-status <intent-id>
+```
+
+所有草稿命令都显式要求 `--account`。即使只有一个公众号，Agent 也先展示后使用；多个
+公众号时必须让用户选择，不能静默复用上一次账号。
+
+`profile`、`project` 和 `knowledge` 已实现为纯本地命令，成功和失败都有稳定 JSON envelope（信封结构）。`knowledge import` 默认建立本地语义索引；只有用户明确使用 `--lexical-only` 时才省略向量。之后调用 `hybrid`/`semantic` 而索引不完整时返回 `DXC_KNOWLEDGE_SEMANTIC_NOT_READY`，不得静默退化。
+
+`project init` 会返回 `knowledgeBootstrap.articleCount/status/recommendedCommand`；空库时明确
+建议导入，但不会扫描目录或阻断继续。`project` 的 `init/resolve/status/checkpoint`
+统一使用 `--directory`，不接受目录位置参数。`draft create` 只接受 `--snapshot`；
+缺少多个必填项时一次返回完整列表。云端预览响应返回创建时间、到期时间和剩余秒数；
+草稿状态 API 为 v1 客户端兼容保留内部 `status`，并新增
+`progress.label/message/nextAction/pollAfterSeconds/terminal`。CLI 和 Agent 面向用户
+只展示 `progress`，不显示英文内部状态名。
+
+`billing`、`tools` 和独立 `article import` 命令尚未实现，不属于当前 CLI 契约。
+
+## 6. 稳定错误码
+
+MVP 至少定义：
+
+```text
+CONFIG_INVALID
+CLI_UPGRADE_REQUIRED
+AUTH_REQUIRED
+DEVICE_REVOKED
+DEVICE_REFRESH_UNAUTHORIZED
+WECHAT_LOGIN_IDENTITY_NOT_LINKED
+WECHAT_LOGIN_IDENTITY_CONFLICT
+WECHAT_AUTH_REQUIRED
+WECHAT_AUTH_REVOKED
+WECHAT_PERMISSION_MISSING
+ACCOUNT_SELECTION_REQUIRED
+ARTICLE_INVALID
+ASSET_NOT_FOUND
+ASSET_OUTSIDE_ROOT
+OCR_REQUIRED
+PREFLIGHT_FAILED
+SNAPSHOT_STALE
+APPROVAL_REQUIRED
+ENTITLEMENT_REQUIRED
+PAYMENT_REQUIRED
+PAYMENT_PENDING
+PAYMENT_VERIFICATION_FAILED
+IDEMPOTENCY_CONFLICT
+JOB_RETRYING
+DRAFT_CREATED_UNVERIFIED
+DRAFT_FAILED
+RATE_LIMITED
+EXTERNAL_UNAVAILABLE
+```
+
+纯本地命令另使用 `DXC_PROFILE_*`、`DXC_PROJECT_*` 和 `DXC_KNOWLEDGE_*` 命名空间；它们不会复用 HTTP 状态，也不会在错误消息中输出绝对路径、正文或模型输入。
+
+错误对象包含：
+
+- `code`
+- `message`
+- `retryable`
+- `retryAfterMs`（可选）
+- `requestId`
+- `details`（经过脱敏的结构化信息）
+
+## 7. 版本兼容
+
+每个请求携带：
+
+- `X-DxC-CLI-Version`
+- `X-DxC-Protocol-Version`
+- `X-DxC-Skill`
+- `X-DxC-Skill-Version`
+- `X-DxC-Installation-Id`
+
+Server 返回当前任务固定的：
+
+- `protocolVersion`
+- `rendererVersion`
+- `templateId`
+- `workflowVersion`
+
+服务端至少兼容稳定渠道当前和上一个协议版本。无法兼容时返回 `CLI_UPGRADE_REQUIRED`，不得在任务中途静默改变语义。