---
url: /docs/agentbuff-stack/development-plan.md
---
# AgentBuff Stack 开发迭代计划

编写日期：2026-10-09（北京时间）。代码基线：`5e711305`，模板版本 `0.3.0`。本计划细化[功能扩展路线](./feature-roadmap)，各轮状态均为待开发；之前的官网、案例、博客与生成器改造已经完成本地验收，不重复施工。

执行更新（2026-10-11）：I4 / I5 本地闭环已验收，I6 购买、验签、退款 / 争议对账与八连接并发已本地验收；订阅正常生命周期 / 到期权限 / 更新失败重投、原结账重试 / 八连接门禁 / 回跳归属已本地验，订阅旧通知当前状态同步与创建 / Checkout 保存故障已本地验；回跳完整保存校验及补丁生成 / 安装已本地验；带原请求标记的未知 Checkout 查找、提前过期 / 完成恢复及页面已本地验；年付首购页面、原年付请求重试及创建前价格核对已本地验；未标记旧未知请求的人工核查 / 关联、审计回滚及原用户恢复已本地验；真实沙箱仍待验；完整 I0—I16 范围与外部验收门槛保持。事实记录见[迭代记录](./iteration-progress)。下文基线与待开发描述保留为原计划。

执行更新（2026-10-11）：I12 用户任务邮件与站主运营通知已完成本地验收，真实外部投递仍待验；I13 品牌素材、实际邮件品牌与新站复制隔离，以及英文 / 西班牙语的首页、功能、价格三组公开页和语言 SEO 已本地验收。登录 / 注册 / 找回与重置、工作台首页、任务列表 / 详情、文件库、历史、积分 / 购买记录、成员 / 邀请 / 设置与管理后台的语言路径与认证回跳已本地验收；博客目录、两篇全文译文和分语言 RSS 已本地验收，账号验证 / 重置 / 验证码 / 邀请邮件已本地验收，任务邮件持久化语言已本地验收，营销确认邮件语言已本地验收，托管支付回站语言已本地验收，公开工具列表与 JSON / 文本完整交互已本地验收；I13 尚未整体完成。主预览仍使用已授权的 0012，后续可选结构只在一次性本地数据库验收。完整范围和外部验收要求不变，详见[迭代记录](./iteration-progress)。

## 1. 目标与交付方式

执行更新（2026-10-11，当前范围）：按用户要求继续模板与官网的本地迭代，暂不接真实产品、暂不发布云端。默认启用英文与简体中文；官网、产品公开页、认证 / 工作台 / 管理界面、相关邮件、20 篇核心使用指南及教程界面已完成双语本地验收，历史记录保留中文。中文持久化语言约束采用新的 0035 增量迁移，只在隔离测试验证；主预览库保持 0012。独立复制与关闭中文后的重新构建已验证；详细证据见[最新迭代记录](./iteration-progress)。原计划外部验收条件保留，当前双语交付不代表 I13 或完整 I0—I16 已完成。

建设可复制、可配置、可独立运行的通用独立站模板。先服务自己的英文产品，经过真实独立站验证后再出售。通用能力开发与产品选题可以并行；具体业务模型、参数、输出检查与定价由产品拥有。

继续使用 Astro、React、TanStack、Hono、tRPC、Better Auth、Drizzle、Cloudflare、Neon、Astryx / StyleX 和中文 VitePress 教程。官网、产品、工作台、API 与邮件保留已有职责。默认保留产品的三个 Worker，队列与定时入口先归 API Worker；确有独立资源或运行隔离需求再拆消费者。

每轮交付一条可以操作和检查的完整流程。代码、数据约束、配置诊断、界面、失败行为、行为测试和中文教程同时完成；每轮独立提交和验收。不以开关数量、页面数量或目录数量作为完成标准。

本次任务仅编写计划，不启用下表模块，不执行数据库迁移、云资源变更、部署或真实业务调用。

## 2. 已有能力与工程前置条件

| 基线 | 保留与复用 | 本轮计划需要处理的缺口 |
| --- | --- | --- |
| 官网与产品应用 | `apps/website`、`apps/web`、`apps/app` | 新模块在产品中运行，官网只展示核实后的状态 |
| 本地预览 | `preview.config.json`、`scripts/preview.py` | 当前 `local.ts` 是 Bun HTTP 入口，需要真实 Workers 本地资源与事件入口 |
| API 上下文 | `apps/api/lib/context.ts`、三个 API 入口 | 当前只有普通环境与数据库 / 认证上下文，新增资源绑定不能被环境校验覆盖掉 |
| 数据与权限 | Drizzle、PGlite、新鲜读写连接 | 新表导出、ID、索引、约束、跨账号与组织权限核查 |
| 积分账本 | `creditAccount`、`creditLedger`、`lib/credits.ts` | 当前方法自行开事务，需要支持任务创建与扣费在同一事务完成 |
| 账单 | Better Auth Stripe 插件及 `routers/billing.ts` | 保留订阅所有权，新增一次性积分购买，避免重复维护同一订阅状态 |
| 路由与导航 | `packages/core/routing.ts` | 新工作台路径同时更新边缘路由、导航与直接刷新验收 |
| 生成器 | `scripts/lib/create-site.ts`、`template.json` | 新增 bucket / queue 等名称和绑定不能残留源项目的资源指向 |
| 迁移规范 | 现有迁移、数据库说明 | 上游文档称单次压平，但当前已有 `0000` / `0001`；I0 必须确定本项目的增量迁移规范 |

Cloudflare 支持通过 Wrangler 本地运行 R2 和 Queues；队列本地运行也有并发能力限制。因此 I0 的运行链路必须先实测，不能仅给 Bun 入口加一个绑定类型就视为完成。[R2 官方说明](https://developers.cloudflare.com/r2/api/workers/workers-api-usage/)、[Queues 本地开发](https://developers.cloudflare.com/queues/configuration/local-development/)。

## 3. 迭代顺序与里程碑

实施记录与当前未完成项见[持续迭代记录](./iteration-progress)。计划仍覆盖 I0— I16，局部验收不代表完整模板已交付。

版本号是拟定的发布节点，只有对应验收通过后才更新 `template.json`。云端验收缺失时保留明确的本地状态，不发布“生产可用”结论。

| 里程碑 | 迭代 | 可检查的交付结果 | 发布条件 |
| --- | --- | --- | --- |
| 0.4 文件基础 | I0— I2 | 真实本地资源、上传 → 查看 → 下载 → 删除 | 隔离、清理及生成站回归通过 |
| 0.5 任务基础 | I3— I5 | 限流、队列执行、结果交付、积分预扣与返还 | 故障与重复处理验收通过 |
| 0.6 商业与模型 | I6— I7 | 积分购买、订阅验收、一个真实模型处理器 | 沙箱支付与真实模型证据齐全，否则标记接入待验收 |
| 0.7 账号与运营 | I8— I10 | 账号与团队完整流程、管理员、可选 API Key | 权限、封禁、撤销与审计回归通过 |
| 0.8 增长与语言 | I11— I14 | 转化、订阅、通知、多语言、可选客服与联盟营销 | 关闭 / 启用及外部服务验收清楚区分 |
| 发布候选版本 | I15 | 独立站部署、备份恢复、费用与运行记录 | 云端完整流程和升级验证通过 |
| 1.0 模板交付 | I16 | 第二个独立产品复用与对外分发准备 | 两站边界验证与交付文档通过；销售安排独立确定 |

主依赖链：I0 → I1 → I2 → I3 → I4 → I5 → I6。I7 依赖任务及收费规则；I8 可在文件闭环后独立推进；I9 依赖任务、账本和账号；I10 依赖执行保护与账号；增长迭代消费已经稳定的事件。当前首个开发交付包为 **I0— I2**。

不预排未经验证的日历截止日期。每轮开始前把工作拆成可合并提交，记录预计投入、外部依赖和风险；结束记录实际投入及返工原因。I0— I2 完成后依据实际速度估计剩余阶段。等待凭据、外部验收和产品选题分别记录，不计作代码开发完成。

## 4. 每轮详细任务

### I0：本地资源、配置与迁移规则

**目标：** 文件和后台任务使用真实本地运行链路，已有认证、邮件捕获及预览隔离继续可用。

* 在当前版本的 Wrangler / Workers 模拟环境中验证 R2 读写、队列事件和定时处理入口；先做最小运行验证再确定预览启动方式，新增内部端口统一进入 `preview.config.json`。
* 统一资源绑定类型与运行时注入；`worker.ts`、`dev.ts`、`local.ts` 的环境校验与资源处理有明确分工，普通字段和 `R2Bucket` / `Queue` 等对象分别处理。
* API Worker 组合 `fetch`、`queue`、`scheduled` 入口，保留 Hono 的请求处理、权限与错误行为；事件消费者独立调用业务服务，不通过伪造登录 HTTP 请求执行任务。
* 保留本地邮件捕获；新运行模式不允许把本地邮件静默转为外部发送。本地资源默认独立持久化，重启后可恢复，生成站不共享状态目录。
* 将本项目后续迁移确定为增量历史，更新与现状冲突的贡献说明；保留已发布迁移，生成站不修改已应用迁移。迁移生成与执行区分。
* 统一模块三种运行状态：关闭、启用但缺配置、已配置但服务故障。新增模块完成后才加入公开配置契约，不提前批量放入不可运行的选项。

**代码位置：** `apps/api/{worker,dev,local}.ts`、`lib/{context,env}.ts`、`scripts/preview.py`、预览配置、相关 Wrangler 配置、数据库规范和生成器。

**验收：** 两个新生成站的本地 R2 互不相见；队列发送触发消费者；定时处理可手动触发；认证与捕获邮件回归通过；关闭资源模块仍可启动；没有连接远程资源。只有本地并发模拟通过不能宣称线上并发验证完成。

### I1：私有文件 API 与元数据

**依赖：** I0。

* 新增文件表，建议字段为 `id`、`userId`、`objectKey`、原始名称、检测类型、字节数、状态、用途、校验摘要、过期时间及创建 / 更新时间。对象 key 唯一；用户、状态和过期时间支持必要查询索引。
* 首版采用登录用户个人文件，与现有个人结果历史一致。工作台说明归属；切换组织不会改变文件所有权。团队共享文件后续另设实际权限契约，不预埋未使用的多态所有者系统。
* 元数据采用 tRPC；二进制上传、预览和下载采用 Hono HTTP 路由。先做经服务端校验的受限上传与读取，优先 R2 原生绑定；暂不为了直传引入 S3 凭据和签名体系。
* 首版演示允许 PNG、JPEG、UTF-8 文本和 JSON，小文件上限建议为 5 MiB，这是产品初始策略而非平台额度。各限制从完成的配置读取；文件名、后缀与客户端 MIME 都不能单独决定实际类型。
* 状态包含 `uploading`、`ready`、`deleting`、`failed`；数据库与对象存储没有共同事务，明确写对象前后的失败补偿与恢复路径。
* 每次读写从会话解析所有者并查新鲜数据，不接受客户端传来的 userId 或任意对象 key 作为授权。私有下载设置适当缓存策略；未知与可执行内容默认作为附件下载。
* 文件操作具有大小 / 数量限制和请求频率保护；先实现必要保护，再在 I3 统一到任务侧策略。

**接口草案：** `files.list`、`files.get`、`files.remove`；`POST /api/files`、`GET /api/files/:id/content`。最终命名在实现前固定，避免同一动作维护两套写入口。

**验收：** 合法文件上传后字节与摘要一致；其他用户不能列出、读取或删除；无会话、超限、伪装类型和非法文本拒绝；R2 写入失败不形成可下载记录；对象缺失呈现明确状态。

### I2：文件工作台、清理与资源复制

**2026-10-11 补充验收：** 已完成 320 / 390 像素与浅深主题四种组合、实际浏览器上传 / 预览 / 原件下载 / 永久删除、任务占用拒绝及解除占用后的原位键盘重试。修复预览 / 取消 / 失败 / 删除成功时的焦点恢复，列表刷新较慢的情况也有回归证据。两个生成站已有文件与隔离验收；真实云端、真机与完整 I0—I16 目标继续保留，见[文件教程](./files-storage)。

**依赖：** I1。

* 在 `apps/app/routes/(app)/files.tsx` 提供上传进度、文件列表、大小、状态、查看、下载、删除、过期提示和空状态。上传百分比只代表传输，不能代表后台处理百分比。
* 更新工作台导航、`APP_PATHS` 和边缘路由验收；进入文件页、刷新与登录回跳都正确。
* 定时清理过期对象、超时上传与失败删除；按批次处理，重复执行不重复扣减配额。为清理保留可排查记录。
* 并发上传的额度检查需要数据库原子预留与释放，不能通过“先查总量再写文件”绕过上限。文件被任务引用后的保留与删除规则在 I4 扩展。
* 更新生成器的 R2 名称、绑定占位与本地资源路径；不复制源项目资源 ID，生成后需要重新配置生产资源。
* 交付 `文件与存储` 中文教程：类型 / 大小策略、本地预览、私有访问、清理与故障处理。

**验收：** 浏览器走完上传 → 查看 → 下载 → 删除；并发上传不超额；清理失败后可恢复；320 / 390 像素和浅深主题可用；生成两个站运行同一流程且资源隔离。

### I3：执行限制与 Turnstile

**2026-10-11 补充：** 已修复当前 workerd 下 Siteverify 的重定向模式兼容性，实际文件入口验证缺失 / 超长 token、动作 / 域名、重放、503 / 非法结构、外站重定向拒绝和十秒超时，无效验证不写文件、配额或 R2。共享函数五种动作测试、关闭模块的原上传 / 私有读取 / 删除 / 清理已回归；真实 widget 和云端仍待，见[中文教程](./execution-security)。

**依赖：** I0；文件保护在 I1 / I2 已存在，本轮扩展到任务和未来付费接口。

* 定义各操作限制：上传、提交任务、查询、下载与外部 API，登录用户、访客采用各自策略。收费任务首版只接受登录用户。
* 使用可核对的原子计数或预留策略。起步按现有 PostgreSQL 条件更新 / 唯一约束实现和测负载；有真实性能证据后再迁到专用存储，不先叠加多种限流后端。
* Turnstile 前端交互与服务端验证一起交付，检查预期 action / hostname；缺凭据、失效 token、服务异常有明确结果。关闭时不加载脚本；登录认证已有的限制继续保留。
* 返回稳定错误码和重试提示，客户端避免连续自动提交；跨项目配置不共享计数。

**验收：** 并发绕过按钮仍受服务端限制；批量请求逐项受约束；无效验证不能触发任务 / 扣费；验证服务故障不会静默放行已要求验证的操作；本地测试与真实验证码验收分开记录。

### I4：任务生命周期与可靠投递

**依赖：** I2、I3。

* 新增任务表和必要执行记录，保存所有者、处理器 ID / 版本、输入文件引用、参数、请求幂等键、状态、尝试次数、领取租约、结果引用、错误分类与时间。`userId + requestKey` 唯一。
* 使用明确状态：`pending`、`queued`、`running`、`retry_wait`、`reconciling`、`succeeded`、`failed`、`canceled`。把任务阶段与进度百分比分开，首版不伪造连续百分比。
* 创建数据库任务后发送队列；投递失败保留待发送记录，定时处理补投。处理“消息先消费、生产者还没更新投递状态”的竞争，不能把迟到的投递标记覆盖任务终态。
* 消费者原子领取租约并使用领取版本保护写回；重复消息、旧消费者和已完成任务不能再次发布结果。重启和租约过期后按规则恢复。
* 仅可重试错误使用有限重试；死信、超时和处理中失联均可核查。手动重试创建明确的新尝试，遵守次数与权限限制。
* 外部服务可能已成功但响应丢失时进入 `reconciling`。支持供应商查询 / 幂等键时据此对账，无法确认时暂停自动重试；不承诺所有外部操作都能严格只执行一次。
* 取消尚未执行任务立即终止；已发起的外部调用先记录取消请求，依据真实供应商能力停止或继续对账。取消不是立即退款的同义词。
* 文件引用有保留规则：输入被运行任务占用时拒绝删除或延后删除；输出文件只在成功完成后成为用户可下载结果。
* 使用确定性文本文件规范化处理器验收实际输入、队列、输出文件和下载；同步 JSON 工具继续保留同步执行。

Cloudflare Queues 默认至少投递一次，幂等与结果去重必须由应用完成。[官方投递保证](https://developers.cloudflare.com/queues/reference/delivery-guarantees/)。

**界面与接口：** `tasks.submit/list/get/cancel/retry`、任务列表 / 详情，真实状态轮询、断线恢复、输入与结果文件链接。

**验收：** 创建成功而消息发送失败可补投；重复与并发消费只留下一个有效结果；旧租约不能覆盖新结果；超时、重试耗尽和死信可恢复；刷新浏览器不丢任务；跨账号访问拒绝。

### I5：任务收费与账本事务

**依赖：** I4。现有免费客户端工具保持免费。

* 明确积分语义：`balance` 表示可用积分，预扣即减少可用余额；每个收费任务对应固定报价快照与预扣记录，成功后标为结算，失败按规则一次性返还。
* 改造现有积分方法的事务边界：任务创建、余额锁定、预扣账本与待投递状态在同一个事务完成。外部队列和模型调用在事务提交后执行。
* 保留现有账户与账本唯一事件约束，增加必要任务关联 / 结算记录；不另建第二套积分账户。稳定事件键关联预扣与返还。
* 终态更新与返还一致提交；成功 / 失败 / 取消并发时只有一个最终结算决定。重试沿用原预扣，不每次重试再扣用户。
* 前端先展示服务端报价与余额，用户确认后提交。请求重复返回原任务；同一幂等键携带不同参数时报冲突，不覆盖原任务。
* 供应商结果仍不确定时保持预扣与对账状态，运营人员有明确处理路径，不能一面退款一面继续产生有效收费结果。

**验收：** 并发请求不会负余额；任务插入失败不扣积分；余额不足不创建可执行任务；重试不再次扣费；重复终态不重复退款；管理员尚未完成时保留可核对的只读记录与本地诊断路径。

### I6：积分包与订阅完整流程

**依赖：** I5；需要 Stripe 沙箱与测试商品才能完成外部验收。

* 在产品价格配置增加类型明确的积分包，包含 SKU、整数最小货币单位金额、币种、积分数量与真实 Price ID。由同一配置生成购买卡片和服务端商品映射。
* 从服务端创建 Checkout，只信任服务端商品与会话用户；支付完成页查询购买状态，不依据 URL 成功标记发放积分。
* 新增购买记录与支付事件去重记录；验签、校验模式 / 商品 / 金额 / 币种 / 归属后，购买终态和积分发放在同一个事务完成。延迟支付只在实际成功后发放。
* 事件写入与业务处理可安全重试；不同事件指向同一支付对象时仍不能重复发放。退款与争议事件可关联原购买，不能按到达顺序覆盖新状态。
* 退款积分已被使用时，不强行将当前非负余额改成负数。先进入人工核查状态并限制进一步收费使用，显示原因，待明确业务规则后处理差额；部分退款有独立数量与账目规则。
* 保留 Better Auth 对已有订阅的状态维护，完善购买、试用结束、续费失败、取消、到期与门户回跳验收。积分包先属于个人；组织订阅不自动变成组织积分池或给个人重复发额度。
* 锁定当前已安装 Stripe / Better Auth 插件的接口与事件职责，避免一次事件同时由两个处理器维护同一订阅或发放同一权益。

Stripe 事件可能重复且不保证顺序，因此回调去重与状态核对是必要验收项。[Stripe Webhook 文档](https://docs.stripe.com/webhooks)。

**验收：** 错误签名拒绝；重复 / 乱序 / 处理失败再投递无重复积分；延迟成功与失败正确；退款和争议可核对；个人 / 组织账单权限正确。凭据未提供时记录“沙箱待验收”，不把本地签名测试当真实支付。

### I7：一个真实 AI 处理器与成本记录

**依赖：** I4；收费接入依赖 I5 / I6。

* 先根据真实产品的输入与输出选择一个模型服务。SDK 和模型版本在接入时核对官方资料，不预先铺设多个供应商、模型路由器和全能 AI Playground。
* 请求只在服务端发起；模型密钥、预算和供应商回调配置不进入 core 或页面。公开的处理器目录只描述产品能力与输入约束。
* 每次执行记录供应商请求 ID、模型版本、用量和可核实成本；未知成本留空，不写成零。输入内容的保存目的、时长与结果清理有配置。
* 对结果做格式、尺寸或结构检查，必要时使用真实输入人工验收质量；质量失败按确定规则进入失败 / 退款路径，不能只检查 HTTP 200。
* 处理超时、限流、余额不足、拒绝生成、坏结果和供应商回调乱序；无法确认的调用沿用 `reconciling`。
* 如果当前没有可用凭据或产品尚未选定，文件与任务能力可发布本地版本，AI 保持待接入；演示处理器不会标成真实模型。

**验收：** 一组固定真实输入记录输出、耗时、失败率与费用来源；完成预览和下载；密钥不出现在客户端产物或日志；不确定结果不会自动重复造成成本。

### I8：账号与团队操作完整性

**当前状态：进行中。** 第一阶段已补齐团队邀请、捕获邮件、重发 / 取消、接受 / 拒绝、过期与再次邀请。邀请和成员变更共用组织行锁，八连接竞争与工作区切换期间的原团队绑定已验收。第二阶段已落实套餐人数的实际写入限制，并完成角色编辑、移除及退出界面；8 个独立连接的邀请接受和可信插件新增成员竞争均只允许最后一个名额被使用一次。第三阶段已完成原子所有者转移的独立确认，八连接竞争、原生 Worker 第二步故障回滚和转移后退出已验收。第四阶段已完成会话列表、单个 / 批量撤销、当前设备保留与近期登录后的设置页回跳；真实 Worker 与浏览器已验收。第五阶段已接入通行密钥添加入口、列表、改名 / 删除确认，签名协议、八连接删除和最后登录方式回滚已本地验收；真实邮件、OAuth / 通行密钥设备环境尚待验收。具体证据见[持续迭代记录](./iteration-progress)。

**依赖：** I0；无需等待真实模型。

* 补齐组织邀请创建、邮件、接受 / 拒绝、取消、过期与再次邀请；处理现有 `invitation(organizationId, email)` 唯一约束对再次邀请的限制。
* 角色编辑、移除、退出与所有者转移分别授权；最后一名 owner 不能被移除或降级。已失去成员资格的旧会话不能继续访问组织数据。
* 补齐 Passkey 添加、命名、列表和撤销，以及会话列表与撤销。删除最后一种可用登录方式前，确保用户仍有可验证的恢复路径。
* 邀请、恢复与安全邮件复用现有发送入口，提供中文维护说明和英文用户文案；本地捕获与真实邮箱验收区分。
* OAuth / Passkey 在真实浏览器与第三方环境验收，不把登录按钮出现当流程成功。

**验收：** 过期、已使用、被取消和错误身份的邀请拒绝；角色变更立即影响接口权限；Owner 边界正确；撤销会话 / Passkey 后实际访问或登录失败；现有注册与恢复仍正常。

### I9：站点管理员与操作审计

**当前进度：** 前五阶段角色、明确初始化、封禁 / 解封、用户搜索、任务 / 财务记录、带原因积分调整、任务恢复、主动支付对账与审计已本地验收；旧结账人工关联、按对象 / 执行者 / 原请求及完成记录检索已本地验收，默认保留历史；生产模式初始化 / 恢复命令已本地验收；真实远程环境及本站保留 / 归档安排待验。详见[管理员教程](./admin-audit)和[迭代记录](./iteration-progress)。I9 不标记完成。

**依赖：** I5、I8；支付排查界面依赖 I6。

* 站点角色与组织角色分开。按已安装 Better Auth 的能力确定管理员集成和数据映射；新增插件表或字段时更新 ID 映射及迁移。
* 首个管理员通过受控初始化步骤明确指定，不能把第一个注册用户或任意组织 owner 自动提升为站点管理员。
* 增加服务端管理员过程与 `/admin` 路由，提供用户搜索、封禁 / 解封、任务与支付状态、积分账本和失败原因查看；默认不展示用户原始输入。
* 积分调整必须有原因并通过同一账本服务执行；重试 / 对账操作复用既有任务与结算规则，管理员也不能绕过扣费或退款幂等。
* 新增操作审计记录，保存执行者、动作、对象、必要变更和时间；审计失败时涉及权益变更的操作不能部分完成。
* 封禁应影响现有会话与后续 API Key 调用，同时定义已经运行任务的处理方式。后台前端菜单隐藏只负责呈现。

**验收：** 普通用户、团队 admin 无法调用站点管理员 API；权限撤销及时生效；封禁用户不能继续新建收费任务；积分调整和恢复操作有可核对审计；列表分页不会泄漏全量私有内容。

### I10：可选用户 API Key

**2026-10-10 状态：** 创建 / 一次性展示 / 列表 / 改名 / 有效期 / 撤销与实际个人文件、任务 API 已本地验收，默认关闭。签发 UUID、封禁、双层限额、原账本和任务版本重试保留统一边界。0013 仅在独立数据库验收，主库未应用；真实云端 / 第三方调用待验，见[教程](./api-keys)。不将本地结果冒充完整 I0—I16 交付。

**依赖：** I3、I8，封禁与管理流程依赖 I9。

* 接入 Better Auth API Key 插件前核对当前安装版本、包、生成 schema、ID 和客户端接口；不与站主环境密钥混用。
* 增加创建、一次性展示、名称 / 前缀列表、过期和撤销界面；不自行保存可恢复明文密钥。作用域先覆盖真正公开的文件 / 任务接口，拒绝管理、支付和身份配置操作。
* 外部 API 明确版本、鉴权、请求幂等和错误码，不把全部 tRPC 管理接口直接暴露为可用能力。Key 解析出的用户仍需执行业务限制与所有权检查。
* 基于 Key 和账户限制请求与收费使用；撤销、过期、封禁及权限变化对后续请求生效。
* 默认关闭。没有对外 API 需求的产品仍只用浏览器会话，关闭后 API Key 路由和设置页不可用。

**验收：** 缺失、撤销、过期或错误作用域拒绝；普通 Key 不能调用管理员操作；调用任务的积分与会话请求一致；明文只展示一次且不进入日志。

### I11：转化事件、候补名单与营销订阅

**2026-10-11 状态：进行中。** 第一阶段已完成公开匿名表单、独立用途同意、确认邮件、主动确认 / 退订、并发去重及定时失败恢复；真实本地 Worker / PostgreSQL 和浏览器已验收。第二阶段的联系人 / 主题同步、SDK 签名回调、全局阻止与后台失败恢复也已在实际本地 Worker / PostgreSQL 验收。公开工具的明确同意、浏览器尝试 / 成功 / 下载报告、并发去重、保留清理与故障隔离也已本地验收，见[工具使用事件](./tool-usage-events)。个人账号独立选择、实际任务开始 / 成功、附件下载与已验证积分包确认，以及确认页去重和定时恢复已本地验收，见[服务端事件](./server-activity-events)。名单、同步与使用报告默认关闭；0014—0025 的可选增量未应用主库。个人订阅账单的已签名回调、完整付款分配核查、续费 / 确认页去重与漏回调恢复已本地验收；团队独立 owner / admin 选择、成员只读、角色变化保护、共享账单去重与续费恢复也已在实际本地 Worker / PostgreSQL 和浏览器验收；真实 Stripe / Resend 环境和真实投递仍需推进，见[订阅教程](./marketing-subscriptions)。

**依赖：** 文件 / 任务事件依赖 I2 / I4，收入事件依赖 I6；订阅表单可独立开发。

* 定义真实发生的事件：开始、成功、下载发起、购买确认。浏览器触发下载不证明用户最终保存；页面访问不代表使用或收入。
* 服务端购买事件与前端确认页去重，默认不记录输入、文件内容、邮箱和完整带参 URL。统计启用与同意策略有明确配置，默认不在私有工作台加载营销脚本。
* 候补名单与营销订阅区分账号；新增订阅状态、确认 token、同意时间 / 来源及退订时间，确认与退订链接可过期或幂等重用。
* 默认采用已有 Resend 邮件能力；当前 API 契约在实现时核对，不照搬旧 Audience 字段。注册和营销同意分别记录，恢复邮件不受营销退订影响。
* 处理重复邮箱、确认失败、退订、提供商异常和退订状态同步；联系人同步故障不会阻塞账号或任务。

**验收：** 重复提交不会重复创建有效订阅；未确认状态不作为订阅成功；退订实际生效；匿名候补名单不强制登录；捕获邮件可检查，真实投递状态单独验收。

### I12：任务通知与站主通知

**2026-10-11 状态：进行中。** 第一阶段个人任务邮件已本地验；第二阶段加入独立 Discord 站主渠道、任务 / 已发放积分包 / 核实个人与团队账单、漏回调恢复及管理员投递列表，实际本地 Worker / Queue / R2、受控付款和捕获故障已验，桌面及手机浅深主题已检查。0020 / 0021 尚未应用正常主库，两个渠道默认关闭。真实供应商、云端维护及既有外部门槛仍按完整范围推进，见[个人邮件](./task-notifications)与[站主通知](./operator-notifications)。

**依赖：** I4、I6、I11。

* 用户通知首版提供站内任务状态与可选完成 / 失败邮件；站主通知首版提供一种明确配置的运营 Webhook，二者的接收者与内容策略分开。
* 从已提交的任务 / 支付结果生成通知投递记录，稳定事件键去重，有限重试与失败列表；通知失败不撤回已经成功的结果或支付权益。
* 通知只发送必要事件与内部详情链接，不附原始文件、提示词或外部服务密钥。目标地址来自站主服务配置，不能由普通用户传任意 Webhook URL。
* 优先沿用已有 Queues 与邮件入口，不创建第二套通知任务引擎。第三方不支持幂等且发送结果不确定时保留可排查状态，不承诺绝对无重复邮件。

**验收：** 重复业务事件不创建重复通知记录；投递失败可重试和查看；没有配置时明确关闭；恶意接收地址不进入任意网络请求路径；业务成功不依赖通知成功。

### I13：多语言与品牌素材

**依赖：** I8— I12 的主要用户文案稳定后。

* 默认继续英文单语言。以一个真实第二语言验证完整路径，维护教程仍中文；先记录译文负责人或译文来源，不生成无内容的语言目录。
* 建立共享语言配置与实际译文，Astro 公共页、React 工作台、邮件按各自入口消费；使用与当前框架适配的机制，不为采用 next-intl 迁移到 Next.js。
* 默认语言无前缀，其他语言采用固定前缀；工作台语言前缀同步处理边缘路由、登录回跳、API origin、静态资产及直接刷新。语言不改变租户和权限。
* canonical、hreflang、sitemap 与真实翻译内容对应，缺翻译采用明确回退或不发布策略；不发布空语言页。
* 品牌 Logo、favicon、OG 图片、社交链接和任务文案有清楚配置入口，保留哑光浅深主题、焦点状态和减少动画偏好。

**验收：** 英文单语言构建和多语言构建都通过；无错域名、死链接与重复 canonical；登录 / 任务 / 邮件语言可预测；两种视口和主题验收；生成器不残留原品牌素材。

### I14：可选客服与联盟营销

**2026-10-11 状态：进行中。** 客服首版选用 Crisp，默认关闭；联系页主动加载、SDK 窗口打开事件确认、脚本失败 / 超时回退、迟到会话保护及新站重置已本地验收。实际浏览器使用受控的本地 SDK 协议，未访问真实供应商；工具页和工作台只提供联系入口，英 / 西双语共用页面。配置、Cookie / 会话边界及真实工作区待验项目见[客服教程](./support-chat)。Rewardful 签名回调、佣金 / 退款与结算复核、登录后的个人 / 团队推荐绑定后端已本地验收，默认关闭。0027—0033 只在一次性验收库应用，主预览保持 0012；真实 Worker 重启恢复和 PostgreSQL 权限锁已验。公开采集与个人 / 团队设置已受控本地验收；新购买首次结账冻结、共享客户创建与实际重启恢复已本地验收；具体订单 / 佣金联查、管理员证据、带原因 / 审计的安全人工复核及有界漏回调补查已受控本地验收，真实结算继续验证，不能把后端元数据绑定当作完整计佣，见[联盟教程](./affiliates)。

联盟后台首版选用 Rewardful，默认关闭：原始字节验签、事件去重、当前佣金 / 结算与 Stripe Charge / 退款核查、有限重试及实际 Worker 重启恢复已本地验收。0026 只在独立验收库应用，正常主库仍为 0012。结算的供应商 `paid` 保留为历史观察，退款或核查失败标记待复核，不宣称银行到账，见[中文教程](./affiliates)。公开采集、明确选择与 Stripe Customer `referral` 元数据绑定已受控本地验收。新积分包和个人 / 团队订阅已接原支付幂等、首次参数冻结与共享客户创建，保留 `client_reference_id` 的既有归属；具体订单 / 佣金联查及退款复核已接独立证据队列和只读管理页面；人工复核和有界漏回调补查已接原维护入口，真实供应商验收仍待做。

**依赖：** I6、I11、I13。

* 客服选一个真实供应商，提供启用配置、必要 ID、按需加载与联系页回退；关闭时不加载第三方请求，任务输入不自动进入聊天上下文。
* 联盟营销选一个真实供应商，明确推荐归因、支付元数据、过期、重复事件、退款撤销与结算核查。前端放脚本只能标记接入，完整计佣需真实流程验收。
* 默认关闭；切换供应商发生实际需求后再确定公共接口。没有账号或测试能力时保持“外部验收待做”，不放虚假的佣金面板。

**验收：** 开关与实际网络加载一致；缺配置报告字段；推荐支付、重复事件、退款有可追踪记录；提供商异常不阻塞工具交付。

### I15：生产验收、运行成本与恢复

**2026-10-11 升级补充：** 已发布的 0012 原 Worker 在独立库完成实际账号 / 私有文件 / 收费任务，再应用完整增量历史；末尾故障整批回滚、重复迁移、新 Worker 使用原会话补投在途任务及切回旧 Worker 已验收。旧字段摘要、原迁移和业务数据保持；默认关闭可选模块与本地固定样本的证据不能代替云端升级、其他历史版本或产品自定义处理器，见[升级教程](./template-upgrades)。

**2026-10-11 状态：进行中。** 测试 / 正式环境的存储、队列、死信和十五分钟维护已分别声明；可执行资源清单、环境隔离检查及目标域名产物检查已接发布脚本 / 持续集成，生成站存储名与 Terraform 对齐。当前仅离线验证，不创建云资源、不迁移远程数据库、不上传 Worker；完整数据库归档、同一快照数据核对和独立空库恢复已在实际本地 PostgreSQL 验证；冻结文件对象检查点、独立空桶恢复和原私有结果下载已受控本地验证；本机归档的保留预览、人工清理与保留归档实际恢复已验；认证版本密钥、实际重启重新登录和基础密钥邮件用途已本地验收；数据库受限应用角色、SCRAM 认证、环境连接隔离、授权事务回滚、密码变更及新凭据恢复原任务已本地验收，见[角色教程](./database-roles)；真实云端流程、用量、对象与完整恢复仍待验收，见[部署教程](./deployment)及[恢复教程](./backup-restore)。

**依赖：** 要发布的模块已完成本地验收；需要明确的测试 / 生产环境安排。

* 编写可执行的资源与绑定清单：Workers、Hyperdrive、R2、队列、定时入口、Neon、邮箱、Stripe、模型；资源创建与代码部署的职责保持清楚。
* 先做独立测试环境，核对域名、Cookie、CORS、私有文件、邮件链接和支付模式。使用真实服务验证队列并发、失败恢复及资源限制，本地模拟不能替代。
* 按选定计划核算存储、请求、数据库、队列和模型费用；记录日期、来源及实际用量，免费额度不作为成本永远为零的保证。
* 做数据库备份与恢复、对象保留 / 删除验证、任务中断恢复与支付对账。升级采用兼容数据变更，版本回退不依赖删除用户数据或重写已应用迁移。
* 密钥轮换与操作权限安排写入维护步骤，不在模板生成时分发真实密钥；生产账号、资源、付费行为与发布由明确环境请求执行。

**验收：** 在测试环境完成注册 → 上传 → 收费任务 → 预览 → 下载及失败返还；恢复后能核对文件、任务、账本与购买；记录负载与费用，保留具体限制。

### I16：第二个独立产品与模板分发

**2026-10-11 分发准备：** 新增开发源码归档、来源提交与文件摘要清单、工作区直接依赖声明和中文安装教程，复用原新站生成器。实际打包 / 解压、逐文件核对、私有文件排除与再次生成已验收；这不是完整依赖许可审计或正式销售发布。真实两站、服务成本与生产验收仍保持原依赖，见[交付教程](./distribution)。

**2026-10-11 依赖补充：** 安装后可导出 Bun 实际依赖版本 / 许可标签，分别记录全部与生产范围，并关联锁文件摘要、工具和平台。机器路径等字段移除，已有报告保留；未知标签需读随包原文核查。此资料用于分发核对，不等同完整授权审计或构建产物清单。

**依赖：** 第一真实产品完成可交付与云端验收。

* 依据本项目新词研究规则选择真实任务，保存社区 / 查询 / 竞品证据；需求与订阅持续性分别验证，不把模板能力演示当市场需求。
* 第一个和第二个产品使用独立仓库、数据库、资源、域名与模板 revision。优先选择不同交付形态验证复用边界，例如同步本地任务与异步文件任务；这只是验证结构，不是具体产品推荐。
* 记录每站复用模块、自定义代码、迁移步骤、构建与运行成本。只有出现真实两处消费者的能力再回收到共享代码，保持产品业务可直接定位。
* 新站生成、从生成站再次生成、已有站升级各走一遍；检查密钥、缓存、官网案例和源站资源 ID 均未混入。
* 完善分发包、依赖与许可证说明、配置教程、升级说明、故障排查和真实案例。模板价格、授权方案、购买流程和支持范围另行确定，不复用演示站订阅充当模板销售。

**验收：** 两站独立运行；可指出共用与自定义代码；生成和升级证据完整；官网只展示真实上线站点；销售状态与实际交付一致。

## 5. 代码结构与数据演进

建议模块靠近实际消费者，目录在实现时按职责增长：

```text
packages/core/          公开模块配置、处理器描述、跨端任务契约
packages/ui/            通用展示组件、设计变量、可访问交互
apps/api/routers/       files、tasks、purchases、admin 等元数据过程
apps/api/lib/           storage、tasks、credits、payment 等服务
apps/api/worker.ts      HTTP、队列、定时入口组合
apps/app/routes/        文件、任务、购买、设置、管理界面
apps/email/             事务、安全、订阅与任务邮件
db/schema/              文件、任务、购买、通知与必要授权表
scripts/                配置诊断、资源预览、独立产品生成
docs/agentbuff-stack/   中文模块教程与验收记录
```

目录不代表强制创建对应包。服务没有第二处真实调用时可以留在业务文件；有真实跨入口事务或运行需求后再拆。资源绑定可放一个类型模块，但不得把所有业务访问包装成抽象平台。

数据采用本项目既有 snake\_case 映射、前缀 ID、带时区时间、schema 导出和数据库驱动无关类型。文件、任务与账本采用真实唯一约束保障幂等；授权、余额、终态与支付状态读取新鲜连接。

文件删除、账号删除和财务审计的保留目的不同。到 I6 / I9 新增购买与审计表时明确数据保留和删除策略；既有数据库约定若与必要账目保留冲突，先记录具体理由并同步规范，不能无声地级联删掉对账证据。

配置先增加当前轮真正实现的字段。公共限制是展示与共享契约，服务端仍强制执行；密钥与私有资源在 API 环境 / 绑定中。模块关闭时隐藏导航只是呈现，直接 API 访问也必须有明确拒绝行为。

## 6. 提交、验证与发布标准

每轮可按三个可构建提交组织：数据与服务 → 实际界面和配置 → 验收与教程。测试随相关行为代码加入，不能推迟到最后提交；同一功能没有完成用户流程之前不更新官网为已交付。

| 修改类型 | 必做验证 | 证据 |
| --- | --- | --- |
| 数据与权限 | PGlite 跑实际迁移；约束、跨用户 / 组织、并发与事务 | 命令、结果、故障案例 |
| Worker 与事件 | Workers 本地运行；绑定、队列、定时和重启恢复 | 本地资源与状态记录 |
| 页面与交互 | 浏览器主流程、浅深主题、320 / 390 像素、键盘、直接 URL 刷新 | 截图、下载结果和实际状态 |
| 生成器 | 两个干净新站；安装、配置、构建、隔离、重复生成 | 模板 revision 与验收记录 |
| 支付 / 邮件 / AI | 本地边界测试加真实测试环境流程 | 模式、日期、请求 / 事件标识、结果与成本来源 |
| 文档和配置 | 构建、死链接、字段文档与缺配置诊断 | 构建日志和诊断结果 |

按变更运行最小覆盖检查；涉及认证 / 权限 / 账本 / 支付时运行对应完整回归，里程碑运行全仓测试。常用命令：

```sh
bun typecheck
bun web:check
bun website:check
bun run test -- --run
bun lint
bun format:check
bun preview:build
bun docs:build
```

每份迭代验收记录包含：代码 revision、计划状态、实现范围、数据与配置变化、测试命令、浏览器证据、已知限制、外部待验收、下一项关键验证。所有“待开发 / 本地可用 / 接口已接入 / 外部已验收”状态以对应证据更新。

## 7. 开发任务单与当前待办

每轮采用下列任务单，便于接续开发与避免范围漂移：

```text
迭代编号 / 负责人 / 开始日期：
目标与用户可操作流程：
依赖与进入条件：
需要修改的文件 / 数据 / 配置：
按顺序执行的子任务：
异常、权限、幂等与恢复规则：
本地验收：
外部验收及所需环境：
生成站与升级影响：
完成证据 / revision / 已知限制：
下一轮进入条件：
```

I0— I2 的独立生成站和文件流程已完成本地验收。当前推进 I14：已知佣金 / 结算的带原因人工复核与请求 / 终态审计已接原维护入口，有界漏回调补查与进度 / 审计已受控本地验收，下一项补真实供应商环境验证。I15 云端运行与 I16 第二独立产品仍按原依赖推进；完整状态和证据见[迭代记录](./iteration-progress)，不以本地协议验收替代真实外部交付。