功能扩展路线：对照 MkSaaS

核对日期：2026-10-09（北京时间）。基线为 AgentBuff Stack 324d1ff1 的代码和当前公开文档。本页是后续实施范围与验收要求，不表示未开发模块已交付；当前状态以模块总览和能力清单为准。

具体代码位置、数据变更、依赖、异常处理和逐轮验收，见开发迭代计划。

1. 技术选择与目标

目标是让模板覆盖常用独立站功能，复制后按需启用。通用文件、任务、支付与运营能力可以先建设，不要求先选定一个具体关键词产品；具体模型、任务参数和定价仍由产品决定。

MkSaaS 的公开技术栈包含 Next.js、Drizzle、Better Auth、Resend、Stripe、AI SDK、国际化和组件库。我们的对应选择如下；这不是更换框架的计划。

职责	AgentBuff Stack 的选择	实施边界
公开内容与 SEO	Astro 静态页面	官网与产品分别构建，正文可直接阅读
登录后的工作台	React + TanStack Router / Query	保留既有会话守卫与数据缓存
业务 API	Hono + tRPC + Zod	输入校验、权限和业务限制在服务端
数据	PostgreSQL / Neon + Drizzle	保留 Hyperdrive 的新鲜读写与缓存读边界
身份认证	Better Auth	扩展已有认证，不另建平行账号系统
视觉系统	Astryx + StyleX + 共享变量	官网与产品复用通用组件，不增加第二套主题系统
邮件	React Email + Resend	事务邮件与营销订阅分开
支付	先完善已有 Stripe 集成	第二个供应商有实际需求后再扩展
文件与任务	R2 + Queues + 数据库任务状态	这是我们的实施选择，不是从 MkSaaS 文档推断其具备完整任务系统
维护教程	VitePress，中文	与面向最终用户的产品帮助内容分开

2. 功能差异与完整交付要求

能力	当前代码边界	下一步交付
身份认证	密码、OTP、恢复本地可用；OAuth / Passkey 有集成	第三方验收；Passkey 添加、列表、撤销及会话管理
团队	创建、切换、成员搜索与分页可用	邀请投递与接受、角色编辑、成员移除；区分站点管理员与团队管理员
用户文件	只有可选 R2 基础设施配置，没有文件 API 与工作台	上传、列表、查看、下载、删除、配额与保留期；头像公开资产与私有任务文件分别定义访问规则
异步任务	未实现	提交、状态、结果、重试、超时、取消与失败记录
积分	有原子账本和内部增减方法	预扣、成功结算、失败返还；重复提交、重复消费均不会重复扣费
支付	Stripe 订阅插件已有；真实沙箱尚未验收	一次性积分包、购买状态、签名回调、重复事件处理、退款对账；再补齐订阅完整流程
AI	无业务模型接入	服务端处理器、超时、版本与用量记录；输出由具体产品校验，不公开模型密钥
验证码与限制	业务 Turnstile 与限流未实现	前后端验证闭环、用户 / 访客限制、超限提示；上传和付费调用分别设限
用户管理	没有站点管理员角色或管理路由	用户查询与封禁、任务排查、积分审计；所有写操作有服务端授权与审计记录
API 密钥	没有用户 API Key 表与接口	创建、一次性展示、列表、撤销、有效期、作用域、调用限制；不能复用浏览器会话保护外部 API
统计与转化	Cloudflare 公开页统计已接；公开工具浏览器使用报告已本地验收，均默认关闭	公开工具独立同意、并发去重、开始 / 成功 / 下载发起见教程；工作台实际任务 / 附件下载、已验证积分包确认与确认页去重已本地验收，需账号独立同意，见服务端教程；个人订阅账单已接当前付款核查、续费去重与恢复；团队独立选择、权限保护、账单去重与恢复已本地验；真实外部环境仍待验
邮件订阅与候补名单	I11 表单与同步已本地验收，默认关闭	已交付独立同意、确认 / 退订、联系人 / 主题最新状态同步、签名退订回调及失败重试；继续转化事件与真实外部验收
通知	I12 个人邮件与站主频道分别默认关闭	邮件选择 / 投递列表，站主任务 / 已核实付款与管理员回执、有限重试；真实外部与云端待验，见个人邮件及站主通知
多语言	默认产品英文，教程中文；可选西班牙语公开六页、账号入口、工作台首页及任务 / 文件 / 历史 / 积分与购买记录 / 成员 / 邀请 / 设置 / 管理后台已本地验；真实字典 / 切换 / 认证回跳、公开页 SEO 与明确英文回退已交付	工具列表与 JSON / 文本完整交互已交付；博客、实际邮件语言及人工审校；中文教程
客服与联盟营销	Crisp 客服及 Rewardful 核查 / 推荐绑定后端本地已验，默认关闭	联系页与真实工作区见客服教程；联盟验签、当前资源 / 退款、个人 / 团队绑定及有限恢复见联盟教程，公开采集与设置已本地验收；完整支付归因和真实结算继续验收
页面与内容	官网、产品博客、静态 SEO、配置化品牌素材已本地验收；见品牌教程	真实条款与品牌素材外部显示验收；按真实用途增加任务页，不建设万能页面生成器

以上是代码和文档对照，不是本轮重新执行所有模块的验收。参考页面：存储、支付、AI、用户管理、API 密钥。

尤其需要区分：MkSaaS 的 API 密钥模块是用户调用产品 API 的凭据管理；我们现有的 .env 校验处理的是站主服务配置，两者不能互相替代。MkSaaS 的通知文档介绍站主渠道通知；我们的用户任务通知是额外需求。

3. 实施批次

第一批：文件能力

在 API 增加文件路由与 R2 绑定，数据库保存对象归属、类型、大小、状态和过期时间，工作台增加文件列表与上传入口。先支持明确列出的输入格式，限制参数可由产品调整。

用户文件默认私有。通过文件记录授权读取和删除，不接受客户端指定他人对象 key。若采用直传，上传授权、上传完成确认和实际对象校验必须一起实现。上传、删除及过期清理的中断状态可恢复，不能仅因请求失败就遗失对象记录。

验收：本地存储模拟可用；跨账号访问拒绝；超限与类型不符拒绝；上传、查看、下载、删除形成真实闭环。资源配置与本地演示分别记录；没有真实 R2 验收时标为本地可用。

第二批：任务与执行保护

引入 Queues 和数据库任务记录。状态由服务端维护，工作台展示实际进度阶段与结果。先用确定性文件处理任务验收队列、结果文件与重试，不用假 AI 成功结果冒充模型接入。

提交幂等键与任务关联，队列消息只携带必要标识。处理器明确哪些错误可重试，设置次数上限与失败恢复；取消请求不承诺撤销已经执行的第三方操作。同步任务继续使用同步路径。

同批增加任务提交限流和可选 Turnstile 验证。收费业务不能等待增长模块完成后才保护资源。

验收：重复投递不会重复执行有效交付；重试耗尽进入明确失败；失联任务可检测；状态查询按归属授权；浏览器刷新后可继续查看真实状态。

第三批：收费与积分闭环

复用 apps/api/lib/credits.ts，将账本事件关联任务和支付事件；预扣、结算和失败返还必须与终态规则一致。先交付一次性积分包，再验收已有订阅的购买、续费、取消与权益变化。

支付凭据不进入公共配置。价格配置分别表达展示金额、币种、周期、积分数量和真实商品 ID；金额单位保持一致，核对第三方实际价格。权益由验签后的支付事件写入，不根据成功页参数发放。

验收：重复回调只发放一次；无效签名拒绝；余额不足拒绝；任务失败只返还一次；退款与争议具有明确对账策略。真实支付仍需单独沙箱验收。

第四批：账号与运营完整性

完成组织邀请与角色操作、Passkey 凭据管理；新增站点管理员授权、用户管理、任务排查及账本审计。API Key 单独作为可选模块，为明确对外开放的接口增加作用域和限额，避免为了后台页面创建不需要的外部 API。

验收：普通用户无法调用管理员接口；组织权限不自动提升为站点管理员；封禁与撤销凭据的实际访问行为可验证；敏感修改具有审计记录。

第五批：增长与本地化

先补转化事件、候补名单和营销订阅，再加入任务邮件、站主通知、多语言、客服与联盟营销。第三方增长脚本按页面用途和启用状态加载，私有工作台不默认承载营销追踪。

多语言保持单语言站可以正常构建；新增语言需要真实译文。候补名单无需强制创建产品账号。营销订阅与账号注册各自记录同意和状态。

参考：统计、邮件订阅、通知、验证码、国际化、客服、联盟营销。

4. 配置与代码约束

公共能力配置继续从 packages/core/website.ts 进入；服务凭据在 API 环境校验，资源在 Worker 绑定中定义。官网的模块状态只表达已经核实的交付程度，不决定产品运行权限。

新增模块交付完整行为后再加入可启用配置。一个模块的关闭、缺配置和服务故障是不同状态：关闭时页面和 API 明确不可用；启用但缺必要配置应报告具体字段；运行故障给用户明确结果并保留可排查记录。

服务端逻辑首先放在实际使用的 API 路由与服务文件。UI 只复用展示组件，不能导入数据库、计费或模型实现。任务状态等确实跨端使用的契约进入 core；出现第二个真实消费者后再提取共享能力。

不预建全能插件注册器、抽象支付网关或泛化模型引擎。首先实现一个真实提供商，随后按第二个使用场景确定最小接口。保留现有 Better Auth 订阅与账本的单一数据来源。

每批交付代码、配置诊断、必要行为测试、中文教程与验收记录。数据库迁移文件随代码提交；执行迁移、部署、真实发信和真实收费另行按环境安排。