---
url: /docs/agentbuff-stack/feature-roadmap.md
---
# 功能扩展路线：对照 MkSaaS

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

具体代码位置、数据变更、依赖、异常处理和逐轮验收，见[开发迭代计划](./development-plan)。

## 1. 技术选择与目标

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

MkSaaS 的公开[技术栈](https://mksaas.com/zh/docs)包含 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 公开页统计已接；公开工具浏览器使用报告已本地验收，均默认关闭 | 公开工具独立同意、并发去重、开始 / 成功 / 下载发起见[教程](./tool-usage-events)；工作台实际任务 / 附件下载、已验证积分包确认与确认页去重已本地验收，需账号独立同意，见[服务端教程](./server-activity-events)；个人订阅账单已接当前付款核查、续费去重与恢复；团队独立选择、权限保护、账单去重与恢复已本地验；真实外部环境仍待验 |
| 邮件订阅与候补名单 | I11 表单与同步已本地验收，默认关闭 | 已交付独立同意、确认 / 退订、联系人 / 主题最新状态同步、签名退订回调及失败重试；继续转化事件与真实外部验收 |
| 通知 | I12 个人邮件与站主频道分别默认关闭 | 邮件选择 / 投递列表，站主任务 / 已核实付款与管理员回执、有限重试；真实外部与云端待验，见[个人邮件](./task-notifications)及[站主通知](./operator-notifications) |
| 多语言 | 默认产品英文，教程中文；可选西班牙语公开六页、账号入口、工作台首页及任务 / 文件 / 历史 / 积分与购买记录 / 成员 / 邀请 / 设置 / 管理后台已本地验；真实字典 / 切换 / 认证回跳、公开页 SEO 与明确英文回退已交付 | 工具列表与 JSON / 文本完整交互已交付；博客、实际邮件语言及人工审校；[中文教程](./languages) |
| 客服与联盟营销 | Crisp 客服及 Rewardful 核查 / 推荐绑定后端本地已验，默认关闭 | 联系页与真实工作区见[客服教程](./support-chat)；联盟验签、当前资源 / 退款、个人 / 团队绑定及有限恢复见[联盟教程](./affiliates)，公开采集与设置已本地验收；完整支付归因和真实结算继续验收 |
| 页面与内容 | 官网、产品博客、静态 SEO、配置化品牌素材已本地验收；见[品牌教程](./brand-assets) | 真实条款与品牌素材外部显示验收；按真实用途增加任务页，不建设万能页面生成器 |

以上是代码和文档对照，不是本轮重新执行所有模块的验收。参考页面：[存储](https://mksaas.com/zh/docs/storage)、[支付](https://mksaas.com/zh/docs/payment)、[AI](https://mksaas.com/zh/docs/ai)、[用户管理](https://mksaas.com/zh/docs/usermanagement)、[API 密钥](https://mksaas.com/zh/docs/apikeys)。

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

## 3. 实施批次

### 第一批：文件能力

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

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

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

### 第二批：任务与执行保护

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

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

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

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

### 第三批：收费与积分闭环

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

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

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

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

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

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

### 第五批：增长与本地化

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

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

参考：[统计](https://mksaas.com/zh/docs/analytics)、[邮件订阅](https://mksaas.com/zh/docs/newsletter)、[通知](https://mksaas.com/zh/docs/notification)、[验证码](https://mksaas.com/zh/docs/captcha)、[国际化](https://mksaas.com/zh/docs/i18n)、[客服](https://mksaas.com/zh/docs/chatbox)、[联盟营销](https://mksaas.com/zh/docs/affiliates)。

## 4. 配置与代码约束

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

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

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

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

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