吃了两天孙哥和景甜的瓜，我们干回老本行：AI模型能力测试+自然语言编程！
现在的模型基础能力都不错了，我也已经不满足于单轮，单点测试了。
所以我要玩把大的！
我准备让国内外最强的Agent+Model 帮我设计和开发一个" AI ALL IN ONE" 的平台！
我先简单介绍一下AIAIO是什么？
其实很简单：我希望能把当前市面上所有的AI模型(语言，图片，视频，声音)集成到一个平台上，然后这个平台上还提供各种基于模型的场景化应用。 其实就是中转站+应用。
专业一点的描述是：
一个以「场景化应用」为交付形态、以「统一 AI 网关」为技术底座、面向 C 端个人与 B 端组织的多模态 AI 服务平台。
这个平台虽然看起来几个字，但是工作量是非常庞大的。如果你们看过newapi的后台菜单应该能理解我说的这句话。 上个平台的上限也是很高的，比如几十亿美金的Openrouter 。
这么庞大的平台对个人来说是没有任何意义的。因为难度太高，竞争太大。
但是作为测试，就非常有意义了。我们只有给一个高难度的项目，才能体现出他们之间的差距！
当前，我已经测了4家的模型，分别是OpenAI,Claude,Z,Kimi 这四家！
其中Claude的Opus5，给的结果最惊人！
它的《系统设计与实施规格书》已经来到了50000+字（16万字符）！
我就先来分享一下它的这个文档。看看目前公认全球最强的编程智能体和模型，能写出一个什么样的问题。
由于文档实在是太长了，文章中我只会截取一部分，文章末尾会分享完整的文档链接！
AI All-in-One 平台 --- 系统设计与实施规格书
文档代号：
opus5.md版本：v1.1（横向评审修订版） 状态：可执行规格（Implementation-Ready Spec） 目标读者：Coding Agent（主要） + 人类架构师（评审） 撰写日期：2026-08-30
第 0 章 · 文档使用说明（Coding Agent 必读）
0.1 这份文档是什么
这不是一份"愿景文档"，而是一份可执行规格书。它的设计前提是：一个 coding agent 将在没有人类逐步指导的情况下，依据本文档从零构建整个系统。因此文档遵循三条硬性写作规则：
- 不留选择题。 凡是技术选型，一律给出唯一答案和理由。禁止出现"可以用 A 或 B"这类表述。若确有替代方案，写入 ADR 的"已否决方案"小节，作为决策留痕而非待办。
- 每个模块必须有可自动验证的验收标准（AC）。 AC 的判定不依赖人的主观判断，必须能由一条命令、一个测试用例或一个脚本给出 pass/fail。
- 接口先行。 数据结构与 API 契约在实现之前完整定义，实现只能填充契约，不能修改契约（修改契约必须走 ADR 变更流程并更新本文档）。
0.2 编号体系
| 前缀 | 含义 | 示例 |
|---|---|---|
REQ-<模块>-<序号> |
需求条目 | REQ-GW-01 |
AC-<模块>-<序号> |
验收标准（可自动化） | AC-GW-01 |
ADR-<序号> |
架构决策记录 | ADR-003 |
RISK-<序号> |
风险登记 | RISK-007 |
NFR-<序号> |
非功能需求 | NFR-012 |
模块代号： GW=AI 网关 · BIL=计量计费 · APP=应用/场景引擎 · IAM=身份与组织 · PAY=支付 · SAF=内容安全合规 · RSK=风控 · STO=存储 · OBS=可观测性 · KB=知识库/RAG · FE=前端 · INF=基础设施
0.3 每章的固定结构
N.1 需求分析 --- 要解决什么问题，边界在哪
N.2 设计与自我论证 --- 方案、已否决方案、为什么
N.3 契约定义 --- 数据结构 / API / 状态机（实现依据）
N.4 验收标准 --- AC 表，每条给出验证命令
N.5 小结 --- 本章的不变量（invariants），实现时不得违反0.4 Coding Agent 执行协议
完整协议见 附录 E。此处摘要三条最重要的：
- 按里程碑顺序实现（第 17 章），不得跳跃。每个里程碑必须全部 AC 通过后才进入下一个。
- 任何涉及金额的计算必须有对应的单元测试，且测试必须覆盖"上游报错""流式中断""并发扣费"三类异常路径。没有这三类测试的计费代码视为未完成。
- 禁止把配置写进代码。 模型列表、价格、限流阈值、审核规则一律来自数据库或配置中心。发现硬编码即视为 AC 失败。
0.5 术语表（Glossary）
| 术语 | 定义 |
|---|---|
| Provider（供应商） | 一个上游 AI 服务商，如 OpenAI、Anthropic、阿里云百炼、火山方舟 |
| Provider Account（供应商账号） | 某个 Provider 下的一组凭证（API Key / AK-SK），是限流和计费的最小上游单元 |
| Model（模型） | 平台对外暴露的一个可调用模型，如 claude-opus-5。一个 Model 可绑定多个 Provider Account |
| Capability（能力位） | 模型支持的特性标记，如 vision、tool_use、streaming、prompt_cache |
| Metering Event（计量事件） | 一次可计费行为的原始记录，只记录"用了多少"，不含价格 |
| Pricing Rule（计价规则） | 把计量事件换算成金额的规则，带生效时间区间 |
| Hold（预扣） | 调用前冻结的预估额度，调用结束后转为实际扣费并退还差额 |
| Ledger Entry（账目） | 不可变的资金流水记录，append-only |
| App（应用） | 一个场景化入口的完整定义，由 App Schema 描述，是数据而非代码 |
| Region（区域） | 合规隔离单元，如 cn（中国内地）、global（海外）。跨 Region 数据不流动 |
| Credit（算力点） | 面向用户展示的计价单位，1 credit = 1e-6 USD（可配置） |
| BFF | Backend For Frontend，为前端聚合裁剪的接口层 |
第 1 章 · 产品定义与战略判断
1.1 需求分析
1.1.1 一句话定义
一个以「场景化应用」为交付形态、以「统一 AI 网关」为技术底座、面向 C 端个人与 B 端组织的多模态 AI 服务平台。
三个词组的顺序不可颠倒，它定义了价值排序：
- 场景化应用 = 用户感知到的价值，是差异化所在
- 统一 AI 网关 = 支撑一切的技术底座，是成本和稳定性所在
- 多模态 = 能力广度，是护城河的宽度而非深度
1.1.2 目标（In Scope）
| ID | 目标 |
|---|---|
REQ-P-01 |
接入文本、图片、视频、语音（ASR/TTS）、Embedding/Rerank 五类模型能力 |
REQ-P-02 |
提供按行业/职业/任务划分的场景化应用入口，应用由配置定义而非代码 |
REQ-P-03 |
支持 Web、桌面（Windows/macOS）、移动（iOS/Android）三端 |
REQ-P-04 |
完整的账号、组织（多租户）、权限体系 |
REQ-P-05 |
订阅 + 按量混合计费，支持国内与海外两套支付渠道 |
REQ-P-06 |
精确到单次调用的 Token/用量统计与成本核算，成本与售价双记 |
REQ-P-07 |
满足中国内地生成式 AI 服务的合规要求（备案、审核、留存、标识） |
REQ-P-08 |
对外提供 OpenAI 兼容 API，允许开发者以标准客户端接入 |
1.1.3 非目标（Out of Scope，v1 明确不做）
| ID | 非目标 | 理由 |
|---|---|---|
REQ-P-N1 |
自研/微调大模型 | 与平台定位正交，资源投入不成比例 |
REQ-P-N2 |
私有化部署交付 | 交付形态完全不同，会污染 SaaS 架构；v2 再评估 |
REQ-P-N3 |
通用 Agent 编排（类 Dify/Coze 的可视化工作流） | v1 用「App Schema + 线性编排」覆盖 80% 场景；DAG 编排延后 |
REQ-P-N4 |
模型训练/数据标注 | 不同业务 |
REQ-P-N5 |
社区/内容分发（类 Prompt 广场的 UGC 社交） | 分散注意力，v1 只做官方应用市场 |
1.2 设计与自我论证
ADR-001：不做纯聚合，做"场景化交付层 + 聚合底座"
背景 最初构想强调"接入几乎所有主流 AI 平台的 API"。这个目标需要被重新审视。
论证
反方（做纯聚合的理由）：
- 用户确实需要在一个地方用到所有模型
- 聚合本身有工程壁垒（协议对齐、密钥管理、故障转移）
- 已有成功案例（OpenRouter）
正方（不做纯聚合的理由）：
- 毛利结构决定生死。 纯中转的定价上限被上游官方价格锁死，实际毛利在 3%~8% 区间。这个毛利率无法覆盖内容审核、合规、客服、支付通道费（国内 0.6%、海外 2.9%+$0.3）。支付通道费本身就可能吃掉全部毛利。
- 切换成本为零。 纯聚合产品对用户没有留存资产，用户在两个聚合器之间迁移的成本是改一个 base_url。
- 上游 ToS 风险不对称。 多家供应商禁止转售（见
RISK-001）。纯聚合把这个风险放在了业务的正中央；场景化应用则把它放在了成本侧。 - 能力接入的边际收益递减极快。 前 8 个模型覆盖 95% 的实际使用量，第 30 个模型的日调用量通常不足总量的 0.1%。
决策
- 技术上，网关按可容纳 100+ 模型的抽象来设计（因为抽象一旦错了后期无法挽回）；
- 商业上，v1 只接入 12 个模型 （清单见
1.3.3），把节省的工程量投入到场景化应用引擎； - 对外话术与产品形态以"场景化应用"为主，"全模型接入"为辅。
已否决方案
- 方案 B：先做纯聚合快速起量，再转场景化。 否决理由：纯聚合吸引来的用户画像（开发者、价格敏感、追求裸 API）与场景化应用的目标用户（业务人员、追求开箱即用）几乎不重叠，用户资产无法迁移，等于做两次冷启动。
ADR-002：抽象为先，规模为后
决策：以下三层抽象在 M1 阶段就必须按"最终形态"设计，不允许为了赶进度简化：
- Provider 抽象层（第 4 章）：新增一个供应商 = 实现一个 Adapter 接口 + 写一条数据库记录，不改动任何上层代码。
- 计量-计价分离（第 5 章）：新增一种计费模式（如"按视频秒数×分辨率"）= 新增一条 pricing rule，不改代码。
- App Schema （第 6 章）：新增一个场景 = 插入一条
apps记录，不改代码、不发版。
可验证的判据（这是本 ADR 的 AC）：
| ID | 验收标准 | 验证方式 |
|---|---|---|
AC-ADR002-01 |
新增一个 Provider（含新协议）的改动，不触及 services/api、apps/web 任何文件 |
git diff --name-only 结果只包含 services/gateway/src/providers/** 和 migration 文件 |
AC-ADR002-02 |
新增一个模型（复用已有 Provider）零代码改动 | 通过 Admin API POST /admin/models 完成，随后 GET /v1/models 立即返回该模型 |
AC-ADR002-03 |
新增一个场景化应用零代码改动 | 通过 Admin API 创建 App，前端立即可渲染并正常调用 |
AC-ADR002-04 |
调整某模型价格零代码改动且不影响历史账单 | 新增 pricing rule 后，历史 usage_event 的重算结果与原账单一致（回归测试 pricing.history.test.ts） |
ADR-003：全栈 TypeScript（含网关）
背景：网关是 IO 密集 + 长连接流式转发的高并发服务，直觉上适合 Go/Rust。
论证
-
支持 Go 的理由：更低的内存占用、更可控的 GC、更好的并发原语。
-
支持 TS 的理由：
- 本项目的执行主体是 coding agent。 单语言栈把上下文切换成本、类型共享成本、测试基建成本降低约一半。跨语言的类型同步（Go struct ↔ TS interface）在 agent 自主开发场景下是高频错误源。
- 网关的工作负载是转发 ，不是计算 。Node.js 的
undici+ReadableStream在纯转发场景的吞吐瓶颈通常在网络和上游，而非 CPU。单实例 4C8G 承载 2000+ 并发 SSE 连接是可达的。 - 平台早期的真实并发量（见 1.5 目标）远低于 Node 的瓶颈。
-
反驳"过早优化"：性能问题应当由水平扩容先解决，语言重写是最后手段。
决策：全栈 TypeScript（Node.js 22 LTS）。网关作为独立服务、独立进程、独立扩缩容，但同一语言栈。
逃生舱 ：网关的 Provider Adapter 接口设计为纯 HTTP 语义、无共享内存状态，若未来单实例 QPS 持续超过 NFR-003 定义的阈值，可以在不改动上下游契约的前提下用 Go 重写该服务。本 ADR 的存在就是为了让这次重写成为可能，而不是让它必然发生。
1.3 用户与场景矩阵
1.3.1 用户分层
| 层级 | 画像 | 核心诉求 | 变现方式 | v1 优先级 |
|---|---|---|---|---|
| L1 个人轻度 | 学生、白领，偶尔用 AI | 免费额度、开箱即用 | 广告位/转化漏斗 | P0（获客） |
| L2 个人专业 | 设计师、自媒体、程序员、翻译 | 特定场景效率、多模型对比 | 订阅 ¥39~199/月 | P0（营收主力） |
| L3 小微团队 | 3~20 人的工作室、电商团队 | 共享额度、协作、成员管理 | 席位订阅 + 按量 | P1 |
| L4 中大型企业 | 有 IT 部门，有合规要求 | SSO、审计、私有知识库、SLA | 年度合同 | P2（v2） |
| L5 开发者 | 通过 API 接入自己的产品 | 稳定、便宜、OpenAI 兼容 | 纯按量 | P1 |
自我论证 ：为什么 L2 是主力而不是 L1？ L1 的付费转化率在同类产品中通常低于 3%，且对价格极度敏感；L2 有明确的"用 AI 省了多少时间/钱"的可计算 ROI，付费意愿强且愿意为"省心"付溢价。产品的设计决策在 L1 与 L2 冲突时，一律偏向 L2。
1.3.2 v1 场景清单（12 个种子应用）
场景选择原则：输入结构化程度高 + 输出可直接使用 + 单次价值明确。避免"通用聊天"这类无法体现场景价值的入口。
| # | 应用 | 目标用户 | 主要模态 | 输入 | 输出 |
|---|---|---|---|---|---|
| 1 | 全能对话 | 全体 | 文本 | 自由对话 | 流式文本 |
| 2 | 长文档问答 | L2/L3 | 文本+RAG | PDF/Word/网页 | 带引用的回答 |
| 3 | 论文/报告润色 | L2 | 文本 | 长文本 + 风格选项 | 改写稿 + diff |
| 4 | 多语言翻译工作台 | L2 | 文本 | 文本/文档 + 术语表 | 双栏对照译文 |
| 5 | 电商主图生成 | L2/L3 | 图片 | 产品图 + 场景描述 | 4 张候选图 |
| 6 | 短视频脚本 + 分镜 | L2 | 文本→图片 | 主题 + 时长 + 风格 | 脚本 + 分镜图 |
| 7 | AI 视频生成 | L2 | 视频 | 文本/图片 + 时长 | MP4 |
| 8 | 会议纪要 | L2/L3 | 语音→文本 | 音视频文件 | 纪要 + 待办 + 说话人 |
| 9 | 代码助手 | L2/L5 | 文本 | 代码 + 问题 | 解释/重构/测试 |
| 10 | 简历优化 + 面试模拟 | L1/L2 | 文本 | 简历 + JD | 优化稿 + 模拟对话 |
| 11 | 小红书/公众号文案 | L2 | 文本+图片 | 卖点 + 平台 | 文案 + 配图 |
| 12 | 竞品/行业调研 | L2/L3 | 文本+联网 | 主题 | 带来源的调研报告 |
实现约束 ：这 12 个应用必须全部 通过 App Schema 定义（第 6 章），不允许任何一个走特殊代码路径。这是对
ADR-002抽象是否成立的实证检验。若有应用无法用 Schema 表达，修改 Schema，不要写特例代码。
1.3.3 v1 模型接入清单
⚠️ 以下清单是种子数据（seed），不是硬编码。 它必须以 SQL/JSON seed 文件形式存在于
packages/seed/models/，运行时从数据库读取。价格随时会变，模型随时会上下线。
海外 Region（global）
| Provider | Model ID (平台) | 上游 Model ID | 模态 | 备注 |
|---|---|---|---|---|
| Anthropic | claude-opus-5 |
claude-opus-5 |
text+vision | 旗舰推理 |
| Anthropic | claude-sonnet-5 |
claude-sonnet-5 |
text+vision | 性价比主力 |
| Anthropic | claude-haiku-4-5 |
claude-haiku-4-5 |
text+vision | 廉价/路由降级目标 |
| OpenAI | gpt-flagship |
(见注) | text+vision | 兼容性最好 |
gemini-flagship |
(见注) | text+vision+audio | 长上下文 | |
| OpenAI | dalle-image |
(见注) | image | 图片生成 |
| Black Forest | flux-pro |
(见注) | image | 图片生成 |
中国 Region（cn）
| Provider | Model ID (平台) | 模态 | 备注 |
|---|---|---|---|
| 阿里云百炼 | qwen-max |
text+vision | 通用主力 |
| 深度求索 | deepseek-chat |
text | 低成本 |
| 智谱 | glm-flagship |
text+vision | |
| 月之暗面 | kimi-long |
text | 长文本 |
| 阿里云百炼 | wanx-image |
image | 图片生成 |
| 快手 | kling-video |
video | 视频生成 |
| 阿里云百炼 | paraformer-asr |
audio→text | 语音识别 |
注 ：非 Anthropic 的具体 model id 与价格由实施时通过各厂商官方文档确认后填入 seed 文件。Coding Agent 在实现时必须查询官方文档获取准确的 model id 和定价，不得凭记忆填写。 若无法访问，则在 seed 中留
TODO_VERIFY标记并使得该模型默认enabled=false，同时在启动日志中告警。
Anthropic 价格基线（本文档撰写时快照，写入 seed 后由 Admin 后台维护）
| Model | 输入 $/1M | 输出 $/1M | 上下文 |
|---|---|---|---|
claude-opus-5 |
5.00 | 25.00 | 1M |
claude-sonnet-5 |
2.00 | 10.00 | 1M |
claude-haiku-4-5 |
1.00 | 5.00 | 200K |
缓存计价系数（Anthropic） ：cache write（5min TTL）= 1.25 × 输入价；cache write（1h TTL）= 2.0 × 输入价；cache read = 0.1 × 输入价。
这三个系数必须建模为 pricing rule 的独立计量项（见 5.3），而不是"输入 token 的折扣"。因为不同厂商的缓存计价模型不同（有的按存储时长收费，有的不收 write 费），只有独立计量项才能统一表达。
1.4 商业模型与单位经济
1.4.1 计费模式
采用 "订阅赠额度 + 超额按量 + 钱包充值" 三层混合模型：
用户支付路径：
├─ 免费层：注册赠 N credits，每日签到补充，硬上限
├─ 订阅层：¥39/¥99/¥199 月付，每月发放对应 credits + 解锁高级模型/应用
└─ 钱包层：一次性充值 credits，永不过期（合规要求：需明示）
消费路径：
订阅额度优先消耗 → 耗尽后消耗钱包余额 → 均无则拒绝（或按设置自动降级到低价模型）自我论证：为什么是 credits 而不是直接显示金额？
支持直接显示金额（人民币/美元）：透明、可信、无理解成本。 支持 credits：
- 屏蔽成本波动：上游调价时改 credits 兑换率即可，不必调整所有套餐价格；
- 屏蔽汇率：海外模型按美元计价，国内用户按人民币付费，credits 是天然的中间层；
- 促销灵活：赠送 credits 不等于赠送现金，会计处理更简单，也不构成"预付卡"的监管定义边界问题；
- 跨模态统一：一次视频生成和一次对话的成本相差 1000 倍，用 credits 可以在同一个数轴上表达。
决策 ：内部账本以 纳美元（nano-USD，1e-9 USD）整数 记账（唯一真值，BIGINT），用户界面展示 credits ，兑换率 1 credit = 1000 nano = 1e-6 USD 存于配置表。
ADR-010b：为什么是整数纳美元而不是
NUMERIC(24,10)十进制？ （v1.1 修订）初版设计使用
NUMERIC(24,10)+decimal.js。这个方案数学上正确，但在 agent 自主开发的长周期项目中易被误用 ：node-postgres把NUMERIC以字符串返回，任何一处Number(x)/parseFloat(x)/ JSON 序列化都会静默退化为浮点，而且不会报错------只是账目慢慢开始对不上。整数方案让类型系统主动对抗这类错误：
bigint无法与number混算（TS 会报错），JSON.stringify会直接抛异常（迫使显式序列化为字符串）。选择的标准不是"哪个更精确"，而是"哪个更难用错"。精度校验：最便宜的模型约 0.1/1Mtoken，即0.1nano/token。计价按整条明细计算（'quantity×rate/unitsize'，一次取整），单条明细误差<1nano=1e−9USD，可忽略。溢出校验：'BIGINT'上限9.22e18nano=9.2e9，远超业务规模；中间量
quantity(≤1e9) × rate需显式bigint运算并做溢出断言。JSON 边界铁律 ：所有金额在 API 响应中一律为十进制字符串 （如
"1234567"表示 nano，或"0.001235"表示展示用 USD），绝不出现 JSON number 。在消费明细页必须同时展示 credits 与折算的本地货币金额（消费者权益合规要求）。
1.4.2 单位经济模型（必须建成实时看板）
scss
毛利 = Σ(售价) − Σ(上游成本) − 支付通道费 − 存储/CDN 成本 − 审核成本| 指标 | 定义 | 目标值 | 看板位置 |
|---|---|---|---|
| Gross Margin | (售价−成本)/售价 | ≥ 45% | Admin 首页，实时 |
| Cost per Active User | 月上游成本 / MAU | 监控项 | 同上 |
| Free Tier Burn | 免费用户月成本总额 | ≤ 总成本 15% | 同上，超阈值告警 |
| Payment Fee Ratio | 通道费 / GMV | ≤ 3% | 同上 |
| Storage Cost Ratio | 存储+CDN / 上游成本 | ≤ 20% | 同上，超阈值触发生命周期收紧 |
AC-BIZ-01：Admin 后台首页必须在 3 秒内加载出上述 5 个指标的当日与近 30 日曲线，数据延迟 ≤ 5 分钟。验证：tests/e2e/admin-dashboard.spec.ts
1.4.3 定价倍率策略
平台售价 = 上游成本 × 倍率。倍率是每个模型独立配置 的字段（models.markup_ratio），不是全局常数。
| 场景 | 建议倍率 | 理由 |
|---|---|---|
| 引流模型（如 deepseek） | 1.2× | 低价心智，做流量入口 |
| 主力模型 | 1.8× ~ 2.2× | 覆盖固定成本与通道费 |
| 旗舰模型 | 1.5× | 用户对绝对价格敏感，高倍率会劝退 |
| 图片/视频 | 2.0× ~ 3.0× | 单次金额小，价格不敏感；且存储成本高 |
| 订阅套餐内 | 不适用 | 套餐按"预期使用量 × 成本 × 安全系数"反推定价 |
订阅套餐的定价必须做压力测试：假设 5% 的用户把额度用满（重度用户），套餐仍需保持正毛利。这个约束写成测试：
AC-BIZ-02：tests/unit/plan-economics.test.ts必须存在，对每个套餐验证：套餐价 ≥ 套餐赠送 credits × 加权平均模型成本 × 1.0（即最坏情况不亏本）。任何套餐配置变更若破坏此不等式，CI 失败。
1.5 北极星指标与可验证的产品级目标
这些是里程碑 M5（公开发布）的验收门槛。
| ID | 目标 | 数值 | 验证方式 |
|---|---|---|---|
AC-BIZ-10 |
12 个种子应用全部可用且端到端跑通 | 12/12 | pnpm test:e2e:apps 全绿 |
AC-BIZ-11 |
首 Token 延迟（TTFT）p95 | < 1200ms（国内模型 < 800ms） | k6 压测报告 |
AC-BIZ-12 |
计费准确性：账单金额与逐笔计量事件重算结果的偏差 | ≤ 0.0001% | scripts/reconcile.ts 每日跑，偏差超阈值告警 |
AC-BIZ-13 |
网关可用性（排除上游故障） | ≥ 99.9% | Prometheus SLO 面板 |
AC-BIZ-14 |
单条上游供应商完全宕机时，可自动降级且用户侧成功率 | ≥ 95% | 混沌测试 tests/chaos/provider-down.test.ts |
AC-BIZ-15 |
内容审核覆盖率（输入+输出） | 100%（cn region） | 审计脚本抽样 10000 条请求，审核记录缺失数 = 0 |
AC-BIZ-16 |
从零新增一个模型到线上可用的耗时 | < 10 分钟且零代码 | 演练录像 + Admin 操作日志 |
1.6 小结：本章不变量
- 场景化应用是产品价值，模型聚合是成本中心。 任何资源分配冲突，优先前者。
- 抽象层在 M1 就要按最终形态做，规模可以慢慢加。
- 内部记账唯一真值是整数纳美元（nano-USD,
BIGINT），credits 只是展示层；金额在 JSON 中一律为字符串。 - 模型清单、价格、场景定义全部是数据，不是代码。
第 2 章 · 全局架构
2.1 需求分析
架构必须同时满足四组互相拉扯的约束：
| 约束 | 来源 | 对架构的强制要求 |
|---|---|---|
| 合规隔离 | 中国内地法规 | 数据、模型路由、部署必须按 Region 物理隔离 |
| 流式低延迟 | 用户体验 | 网关到用户的链路不得经过会缓冲的中间件 |
| 计费准确 | 商业生死线 | 计量埋点必须在网关内部，不可依赖下游异步补记 |
| 快速迭代 | 业务需要 | 业务发布不得影响正在进行的长连接 |
2.2 设计与自我论证
ADR-004：三个必须独立的进程边界，其余单体
决策 ：v1 采用 "模块化单体 + 3 个独立服务" 的结构，不做微服务。
markdown
必须独立的进程：
1. gateway --- AI 网关：高并发长连接，独立扩缩容，发布频率低
2. worker --- 异步任务：视频/图片生成轮询、文件解析、产物转存，CPU/内存特征完全不同
3. api --- 业务 API：模块化单体，内部按领域分包，但同一进程
可选独立（v1 内嵌于 api，预留拆分接口）：
- billing --- 计费结算（v1 是 api 内的模块，但所有调用走接口，便于拆分）
- moderation --- 内容审核（v1 是 api 内的模块 + 独立的审核队列）论证
为什么网关必须独立：
- 它持有大量长连接（SSE），一次滚动发布会中断所有进行中的对话。发布频率必须与业务解耦。
- 它的扩缩容触发条件是"并发连接数"，业务 API 是"QPS"，两者曲线不同。
- 它是唯一持有上游 API Key 的服务，安全边界应当收紧。
为什么 worker 必须独立：
- 视频生成任务可能运行 10 分钟，文件解析可能吃 2GB 内存。这类负载放进 API 进程会导致 P99 抖动。
- 它需要能被独立限流（避免大量视频任务打爆上游配额）。
为什么其余不拆：
- 微服务的成本（分布式事务、服务发现、链路追踪、N 倍部署复杂度）在当前规模下远大于收益。
- 对 coding agent 而言，跨服务的一致性 bug 是最难自主发现和修复的一类问题。 单体内的数据库事务是可靠的一致性保证。
已否决方案
- 方案 B：完整微服务（user/billing/app/conversation 各自独立）。 否决：分布式事务会立即出现在"扣费+写会话"这条最核心的路径上，得不偿失。
- 方案 C：完全单体（网关也在内）。 否决：违反上述网关独立性论证，且 Key 安全边界无法收紧。
ADR-005：Region 隔离是一等公民
决策 ：region 是贯穿全系统的一等概念，不是一个配置开关。
csharp
Region 的隔离层级（从强到弱）：
L1 部署隔离（必须）：cn 与 global 使用完全独立的数据库实例、Redis、对象存储、K8s 集群
L2 数据隔离（必须）：不存在跨 region 的数据同步，用户在两个 region 各有独立账号
L3 路由隔离（必须）：cn region 的网关只能路由到 provider.region ∈ {cn}
L4 代码同构（应当）：同一套代码，通过 REGION 环境变量与数据库内容区分行为自我论证
反方观点："先做一个 region，把 region 字段留着，以后再拆。" 这个观点的问题在于：留字段解决不了跨境数据流动问题。 一旦系统里存在"一个用户可以调用任意 region 的模型"这个代码路径，它就会渗透进会话存储、账单、日志、缓存的每一层。后期拆分等价于重写。
反方观点2："用一套数据库，加 region 列做逻辑隔离。" 问题：中国内地数据本地化要求的是数据存储在境内。逻辑隔离的单库如果部署在境外，直接违规；部署在境内，则海外用户访问延迟不可接受，且海外数据受境内司法管辖也会引发海外用户的合规顾虑。
决策细则：
- 环境变量
REGION取值cn|global，服务启动时读取，不可在运行时切换。 - 数据库中所有
providers、models、provider_accounts记录带region字段。网关启动时加载模型注册表，过滤掉非本 region 的记录，从根上杜绝误路由。 - 跨 region 的唯一共享物：代码仓库、Docker 镜像、前端静态资源（CDN）。不共享任何数据库、任何用户数据、任何日志。
AC-INF-01：启动一个REGION=cn的网关实例，调用GET /v1/models返回的列表中，region != 'cn'的模型数量必须为 0。验证：tests/integration/region-isolation.test.ts
AC-INF-02：向REGION=cn的网关直接发起指定model=claude-opus-5（global 模型）的请求，必须返回404 model_not_found，且不得产生任何对上游的出站请求。验证：同上，用 mock server 断言零出站。
ADR-006：技术选型（钉死，不留选择题）
| 层 | 选型 | 版本 | 理由（简） |
|---|---|---|---|
| 语言 | TypeScript | Node.js 22 LTS | 见 ADR-003 |
| Monorepo | pnpm + Turborepo | pnpm 9 / turbo 2 | 增量构建、workspace 协议 |
| 后端框架 | Fastify | 5.x | 性能优于 Express，原生支持 schema 校验与 SSE |
| 校验/类型 | Zod | 3.x | 单一真值：Zod schema → TS 类型 → OpenAPI |
| ORM | Drizzle ORM | 最新稳定 | SQL-first，事务语义清晰，migration 可读；比 Prisma 更适合复杂计费 SQL |
| 主库 | PostgreSQL | 16 | 事务、NUMERIC 精确数值、JSONB、行级锁 |
| 分析库 | ClickHouse | 24.x | 计量事件与请求日志的海量写入与聚合 |
| 缓存/限流/锁 | Redis | 7.x | 令牌桶、分布式锁、Pub/Sub |
| 队列 | BullMQ | 5.x | 基于 Redis，与栈一致，支持延迟/重试/优先级 |
| 对象存储 | S3 兼容 | MinIO(dev) / OSS(cn) / R2(global) | 通过 @aws-sdk/client-s3 统一 |
| 向量库 | pgvector | PG 扩展 | v1 规模下无需独立向量库，减少组件 |
| 全文检索 | PostgreSQL FTS + pg_jieba(cn) | 同上 | |
| Web 前端 | Next.js (App Router) | 15 | SSR/流式渲染，SEO 友好 |
| UI | React 19 + TailwindCSS + shadcn/ui | 可控、无重型依赖 | |
| 状态 | TanStack Query + Zustand | 服务端状态与客户端状态分离 | |
| 桌面 | Tauri | 2.x | 体积 <10MB，可访问本地文件/全局快捷键 |
| 移动 | Expo (React Native) | SDK 最新 | 复用 TS 与业务逻辑 |
| 测试 | Vitest + Playwright + Testcontainers | 单元/E2E/集成三层 | |
| 可观测 | OpenTelemetry + Prometheus + Grafana + Loki + Tempo | 开源自托管，避免 SaaS 的数据出境问题 | |
| 部署 | Docker + Kubernetes | dev 用 docker compose | |
| CI | GitHub Actions（或 Gitea Actions for cn） |
明确禁止使用的东西（避免 agent 自由发挥）：
- ❌ 任何 ORM 的隐式 lazy loading
- ❌
float/double表示金额（必须NUMERIC/Decimal） - ❌ 在业务代码中直接
fetch上游 AI API（必须通过 gateway） - ❌ 在 API 服务中读取上游 API Key（Key 只存在于 gateway 的运行时）
- ❌ 未经 Zod 校验的外部输入进入业务逻辑
2.3 架构总览
vbnet
Syntax error in graphmermaid version 8.14.0
ERROR: [Mermaid] Lexical error on line 3. Unrecognized text.
...客户端"] W[Web · Next.js] D
----------------------^关键数据流说明
-
同步流式对话：Client → LB → api（鉴权/额度预扣/审核入参）→ gateway（路由/调用上游/流式转发/计量）→ Client。
- ⚠️ 流式响应由 gateway 直接回传给客户端 ，不经过 api 二次转发（避免双重缓冲增加 TTFT）。api 只负责签发一个短期的
gateway_ticket，客户端持 ticket 直连 gateway。
- ⚠️ 流式响应由 gateway 直接回传给客户端 ，不经过 api 二次转发（避免双重缓冲增加 TTFT）。api 只负责签发一个短期的
-
异步生成任务 ：Client → api（校验/预扣）→ 写
async_jobs→ 入队 → worker → gateway → 上游 → 轮询/回调 → 产物转存 S3 → 结算 → 通知客户端（WebSocket/轮询）。 -
计量流 ：gateway 在每次调用结束时（含异常结束） 写一条 metering event 到 Redis Stream，由 api 内的 consumer 消费 → 写 PG 账本（事务）+ 写 ClickHouse（分析）。
ADR-007：客户端直连网关（Ticket 模式）
问题：流式响应是否要经过业务 API 转发？
论证
- 经过 API 转发：鉴权集中、逻辑简单，但增加一跳（+20~50ms TTFT），且 API 进程要维持等量长连接，扩缩容耦合。
- 客户端直连网关：TTFT 更低、网关可独立扩容，但网关需要独立鉴权能力。
决策 ：客户端直连网关，采用 Ticket 模式：
- 客户端向
POST /v1/chat/prepare（api）提交请求元信息（model、app_id、估算 token 数）。 - api 完成：鉴权 → 权限检查 → 输入内容审核 → 额度预扣（创建 hold） → 生成
ticket（JWT，含hold_id、model_id、workspace_id、limits，TTL 60s，一次性）→ 返回。 - 客户端向
POST /v1/chat/stream（gateway）携带 ticket 与完整 payload，网关校验 ticket 签名与一次性（Redis SETNX）后执行。 - 网关结束时回写计量事件，api 的 consumer 完成 hold → settle。
这个模式的代价 ：多一次 RTT。缓解 ：prepare 是轻量请求（p99 < 50ms），且可以与前端的 UI 反馈（"正在思考..."）并行，用户无感。
AC-GW-20：同一个 ticket 被使用第二次必须返回401 ticket_already_used，且不得产生上游调用。验证：tests/integration/gateway-ticket.test.ts
AC-GW-21：过期 ticket（>60s）必须返回401 ticket_expired。验证：同上。
2.4 目录结构
bash
aiaio/
├── apps/
│ ├── web/ # Next.js 15 主站（用户端）
│ │ ├── app/
│ │ │ ├── (marketing)/ # 落地页、定价、文档
│ │ │ ├── (app)/ # 登录后的应用区
│ │ │ │ ├── a/[appSlug]/ # 场景化应用动态路由（由 App Schema 渲染）
│ │ │ │ ├── chat/ # 通用对话
│ │ │ │ ├── library/ # 我的产物库
│ │ │ │ ├── usage/ # 用量与账单
│ │ │ │ └── settings/
│ │ │ └── api/ # 仅 BFF 轻量代理，不含业务逻辑
│ │ ├── components/
│ │ │ ├── app-renderer/ # ★ App Schema 渲染引擎（表单+输出）
│ │ │ ├── chat/ # 流式消息渲染
│ │ │ └── ui/ # shadcn 组件
│ │ └── lib/
│ ├── admin/ # Next.js 管理后台
│ │ └── app/
│ │ ├── models/ # 模型注册表 CRUD
│ │ ├── pricing/ # 价格规则
│ │ ├── providers/ # 供应商与密钥池
│ │ ├── apps/ # 应用 Schema 编辑器
│ │ ├── users/ # 用户与组织
│ │ ├── finance/ # 对账、毛利看板
│ │ ├── moderation/ # 审核队列与申诉
│ │ └── risk/ # 风控规则与告警
│ ├── desktop/ # Tauri 2 外壳
│ │ ├── src-tauri/ # Rust：全局快捷键、划词、截图、本地文件
│ │ └── src/ # 复用 web 的组件
│ └── mobile/ # Expo
│
├── services/
│ ├── gateway/ # ★ AI 网关（独立进程）
│ │ ├── src/
│ │ │ ├── server.ts
│ │ │ ├── routes/
│ │ │ │ ├── chat.ts # 流式对话
│ │ │ │ ├── images.ts
│ │ │ │ ├── videos.ts # 异步任务提交
│ │ │ │ ├── audio.ts
│ │ │ │ ├── embeddings.ts
│ │ │ │ ├── models.ts # 模型发现
│ │ │ │ └── openai-compat/# OpenAI 兼容层
│ │ │ ├── providers/ # ★ 每个供应商一个 Adapter
│ │ │ │ ├── base.ts # ProviderAdapter 接口定义
│ │ │ │ ├── anthropic/
│ │ │ │ ├── openai/
│ │ │ │ ├── google/
│ │ │ │ ├── dashscope/ # 阿里云百炼
│ │ │ │ ├── deepseek/
│ │ │ │ ├── zhipu/
│ │ │ │ ├── moonshot/
│ │ │ │ ├── volcengine/
│ │ │ │ └── kling/
│ │ │ ├── registry/ # 模型注册表加载与热更新
│ │ │ ├── routing/ # 路由策略、降级、故障转移
│ │ │ ├── keypool/ # 密钥池、限流、熔断、健康检查
│ │ │ ├── metering/ # 计量事件产出
│ │ │ ├── stream/ # SSE 编解码、中断处理、断点续传
│ │ │ └── ticket/ # Ticket 校验
│ │ └── test/
│ ├── api/ # ★ 业务单体（按领域分包）
│ │ ├── src/
│ │ │ ├── server.ts
│ │ │ ├── modules/
│ │ │ │ ├── identity/ # 用户、凭证、会话、设备
│ │ │ │ ├── workspace/ # 组织、成员、角色、邀请
│ │ │ │ ├── catalog/ # 模型/供应商的读侧 + Admin 写侧
│ │ │ │ ├── app/ # App Schema CRUD、版本、灰度
│ │ │ │ ├── conversation/ # 会话、消息、分支
│ │ │ │ ├── billing/ # 钱包、hold、ledger、结算
│ │ │ │ ├── pricing/ # 计价引擎
│ │ │ │ ├── payment/ # 订单、订阅、渠道、回调
│ │ │ │ ├── moderation/ # 内容审核
│ │ │ │ ├── risk/ # 风控
│ │ │ │ ├── asset/ # 产物与附件
│ │ │ │ ├── knowledge/ # 知识库/RAG
│ │ │ │ └── admin/ # 后台专用接口
│ │ │ ├── shared/ # 跨模块的基础设施（db、redis、otel、errors）
│ │ │ └── consumers/ # Redis Stream 消费者（计量入账等）
│ │ └── test/
│ └── worker/ # 异步任务
│ ├── src/
│ │ ├── jobs/
│ │ │ ├── async-generation.ts # 视频/图片轮询
│ │ │ ├── asset-ingest.ts # 上游产物转存
│ │ │ ├── file-parse.ts # 文档解析与切块
│ │ │ ├── embedding.ts
│ │ │ ├── reconcile.ts # 每日对账
│ │ │ └── lifecycle.ts # 存储生命周期
│ │ └── worker.ts
│ └── test/
│
├── packages/
│ ├── db/ # ★ Drizzle schema + migrations（唯一数据定义源）
│ │ ├── src/schema/ # 按领域分文件
│ │ ├── migrations/
│ │ └── src/client.ts
│ ├── contracts/ # ★ Zod schema：所有 API 请求/响应/事件的唯一定义
│ │ ├── src/gateway/ # 统一 AI 调用契约
│ │ ├── src/api/
│ │ ├── src/events/ # 计量事件、领域事件
│ │ └── src/app-schema/ # ★ App Schema 定义
│ ├── sdk/ # 由 contracts 生成的前端客户端
│ ├── ui/ # 跨端共享的展示组件
│ ├── core/ # 纯函数领域逻辑（计价、token 估算、权限判定）
│ ├── seed/ # 种子数据：providers/models/pricing/apps
│ │ ├── providers.json
│ │ ├── models.json
│ │ ├── pricing.json
│ │ └── apps/ # 12 个种子应用的 Schema
│ └── config/ # 环境变量 schema 与加载（Zod 校验）
│
├── infra/
│ ├── docker/
│ │ └── docker-compose.dev.yml
│ ├── k8s/
│ │ ├── base/
│ │ └── overlays/{cn,global}/
│ └── grafana/ # 面板与告警规则（as code）
│
├── scripts/
│ ├── reconcile.ts # 对账脚本
│ ├── seed.ts
│ └── verify-acs.ts # ★ 遍历本文档 AC 并输出通过情况
│
├── tests/
│ ├── e2e/
│ ├── integration/
│ ├── chaos/
│ └── load/ # k6 脚本
│
├── opus5.md # 本文档
└── turbo.json / pnpm-workspace.yaml目录设计的三条原则（自我论证）
packages/contracts是唯一契约源。 所有跨进程、跨端的数据结构在这里用 Zod 定义一次，向下生成 TS 类型、OpenAPI 文档、前端 SDK、以及运行时校验。 否决方案：在各服务内各自定义类型然后手工同步 ------ 这是分布式系统最常见的腐化源，对 agent 尤其危险。services/api/src/modules/*按领域分而非按技术分层。 每个 module 内部自带routes / service / repo / types。 否决方案 ：全局的controllers/ services/ repositories/三层目录 ------ 实现一个功能要横跨三个远离的目录，agent 极易丢失上下文，也助长跨领域的隐式耦合。packages/core存放纯函数。 计价、token 估算、权限判定、限流算法这类逻辑必须是无 IO 的纯函数，因为它们需要被大量单元测试覆盖（尤其是计价）。
AC-INF-03：packages/core的任何文件不得 importpg、ioredis、node:fs、undici等 IO 库。验证：ESLint 规则no-restricted-imports+ CI 检查。
AC-INF-04：packages/core的单元测试行覆盖率 ≥ 95%，其中pricing与billing子目录 ≥ 100% 分支覆盖。验证：pnpm test:coverage。
2.5 环境与配置约定
所有环境变量必须在 packages/config/src/env.ts 中用 Zod 定义并在进程启动时校验，缺失或不合法必须 fail-fast 退出，禁止使用默认值静默降级。
css
// packages/config/src/env.ts （契约，实现必须与此一致）
export const envSchema = z.object({
NODE_ENV: z.enum(['development', 'test', 'production']),
REGION: z.enum(['cn', 'global']), // ★ 不可运行时切换
SERVICE: z.enum(['api', 'gateway', 'worker']),
DATABASE_URL: z.string().url(),
REDIS_URL: z.string().url(),
CLICKHOUSE_URL: z.string().url(),
S3_ENDPOINT: z.string().url(),
S3_BUCKET: z.string(),
S3_ACCESS_KEY_ID: z.string(),
S3_SECRET_ACCESS_KEY: z.string(),
S3_PUBLIC_BASE_URL: z.string().url(),
JWT_ACCESS_SECRET: z.string().min(32),
JWT_TICKET_SECRET: z.string().min(32), // ★ 与 access 分离
ENCRYPTION_KEY: z.string().length(64), // ★ AES-256-GCM，用于加密上游 API Key
GATEWAY_INTERNAL_URL: z.string().url(),
PUBLIC_BASE_URL: z.string().url(),
OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
LOG_LEVEL: z.enum(['trace','debug','info','warn','error']).default('info'),
})
AC-INF-05：删除任一必填环境变量后启动任一服务，必须在 5 秒内以非零退出码退出，并在 stderr 打印缺失的变量名。验证：tests/integration/env-validation.test.ts
AC-INF-06：代码库中不得出现明文的上游 API Key。验证：CI 中运行gitleaks detect且结果为空。
2.6 小结：本章不变量
- 三个独立进程：gateway / api / worker。其余在 api 内做模块化单体。
- Region 是部署级隔离，不是逻辑标记。网关只加载本 region 的模型。
- 流式响应由客户端直连 gateway，通过一次性 ticket 授权。
packages/contracts是唯一契约源；packages/db是唯一数据定义源；packages/core必须是纯函数。- 上游 API Key 只存在于 gateway 进程的内存中，且在数据库里加密存储。
上面是两个章节的内容，我看了一下已经有1万字了。
这个文档，总共有18个章节！！！
章节目录如下：
markdown
# AI All-in-One 平台 --- 系统设计与实施规格书
## 第 0 章 · 文档使用说明（Coding Agent 必读）
- 0.1 这份文档是什么
- 0.2 编号体系
- 0.3 每章的固定结构
- 0.4 Coding Agent 执行协议
- 0.5 术语表（Glossary）
## 第 1 章 · 产品定义与战略判断
- 1.1 需求分析
- 1.1.1 一句话定义
- 1.1.2 目标（In Scope）
- 1.1.3 非目标（Out of Scope，v1 明确不做）
- 1.2 设计与自我论证
- ADR-001：不做纯聚合，做"场景化交付层 + 聚合底座"
- ADR-002：抽象为先，规模为后
- ADR-003：全栈 TypeScript（含网关）
- 1.3 用户与场景矩阵
- 1.3.1 用户分层
- 1.3.2 v1 场景清单（12 个种子应用）
- 1.3.3 v1 模型接入清单
- 1.4 商业模型与单位经济
- 1.4.1 计费模式
- 1.4.2 单位经济模型（必须建成实时看板）
- 1.4.3 定价倍率策略
- 1.5 北极星指标与可验证的产品级目标
- 1.6 小结：本章不变量
## 第 2 章 · 全局架构
- 2.1 需求分析
- 2.2 设计与自我论证
- ADR-004：三个必须独立的进程边界，其余单体
- ADR-005：Region 隔离是一等公民
- ADR-006：技术选型（钉死，不留选择题）
- 2.3 架构总览
- ADR-007：客户端直连网关（Ticket 模式）
- 2.4 目录结构
- 2.5 环境与配置约定
- 2.6 小结：本章不变量
## 第 3 章 · 领域模型与数据库设计
- 3.1 需求分析
- 3.2 全局约定
- 3.3 ER 概览
- 3.4 表定义
- 3.4.1 身份与组织（identity, workspace）
- 3.4.2 模型目录（catalog）
- 3.4.3 计价（pricing）
- 3.4.4 计量与账本（billing）★ 最重要
- 3.4.5 应用与会话（app, conversation）
- 3.4.6 异步任务与产物（jobs, asset）
- 3.4.7 安全、审核、风控
- 3.4.8 知识库（knowledge）
- 3.5 ClickHouse 表（分析侧）
- 3.6 索引与性能约定
- 3.8 ★ 类型安全与租户边界原语（v1.1 新增）
- 3.8.1 品牌类型（Branded Types）
- 3.8.2 强制的租户边界断言
- 3.8.3 大表分页一律用游标
- 3.7 小结：本章不变量
## 第 4 章 · AI 网关（Gateway）
- 4.1 需求分析
- 4.1.1 网关承担的职责（且仅承担这些）
- 4.1.2 网关明确不做的事
- 4.2 设计与自我论证
- ADR-008：统一抽象策略 ------ 最小公共集 + 能力矩阵 + 透传
- ADR-009：三条执行链路，不强行统一
- 4.3 契约：能力矩阵（Capability Matrix）
- 4.4 契约：统一请求/响应
- 4.4.1 统一 Chat 请求
- 4.4.2 统一 SSE 事件协议
- 4.5 Provider Adapter 接口（★ 扩展点）
- 4.6 请求生命周期状态机
- 4.6.1 重试与幂等规则
- 4.6.2 流式中断的计量补偿
- 4.7 密钥池、限流、熔断
- 4.7.1 账号选择算法
- 4.7.2 熔断器
- 4.7.3 健康检查
- 4.7.4 密钥加密
- 4.8 路由策略与降级
- 4.8.0 ★ 策略授权门（Policy Gate）------ 必须在性能路由之前（v1.1 新增）
- 4.8.0b 路由决策必须可解释、可回放（v1.1 新增）
- 4.8.1 三级降级链
- 4.8.2 智能路由（v1.5，预留接口）
- 4.9 异步作业链路
- 4.9.1 状态机
- 4.9.2 轮询策略
- 4.10 OpenAI 兼容层
- 4.11 网关验收标准汇总
- 4.12 小结：本章不变量
## 第 5 章 · 计量与计费系统
- 5.1 需求分析
- 5.1.1 为什么这是最容易被低估的模块
- 5.1.2 核心需求
- 5.2 设计与自我论证
- ADR-010：三阶段扣费 ------ Reserve / Settle / Release
- ADR-011：计量与计价严格分离
- ADR-012：预估算法
- 5.3 各模态的计量规则（实现清单）
- 5.3.1 文本模型
- 5.3.2 图片模型
- 5.3.3 视频模型
- 5.3.4 语音
- 5.3.5 Embedding / Rerank
- 5.3.6 存储
- 5.4 订阅额度与钱包的交互
- 5.5 对账（Reconciliation）
- 5.6 用量展示与透明度
- 5.7 计费验收标准汇总
- 5.8 小结：本章不变量
## 第 6 章 · 应用/场景引擎（App Schema）
- 6.1 需求分析
- 6.1.1 问题陈述
- 6.1.2 一个 App 需要表达什么
- 6.2 契约：App Schema 完整定义
- 6.2.1 ★ 风险卡（Risk Card）------ 为什么每个应用都要有一份（v1.1 新增）
- 6.3 设计与自我论证
- ADR-013：线性 Pipeline，不做 DAG（v1）
- ADR-014：提示词注入防护是 Schema 的一等公民
- ADR-015：能力校验在保存时而非运行时
- 6.4 渲染引擎
- 6.4.1 前端渲染（apps/web/components/app-renderer/）
- 6.4.2 模板引擎
- 6.4.3 缓存友好的 prompt 组装
- 6.5 版本管理与灰度
- 6.6 应用市场（v1 精简版）
- 6.7 应用引擎验收标准
- 6.8 小结：本章不变量
## 第 7 章 · 身份、组织与权限
- 7.1 需求分析
- 7.2 设计与自我论证
- ADR-016：Access Token（JWT）+ Refresh Token（不透明）
- ADR-017：Ticket 与 Access Token 分离
- 7.3 权限模型（RBAC）
- 7.4 API Key 体系
- 7.5 实名认证（cn region）
- 7.6 身份验收标准
## 第 8 章 · 支付与订阅
- 8.1 需求分析与关键约束
- 8.2 设计与自我论证
- ADR-018：海外收款用 Paddle（Merchant of Record）
- ADR-019：⚠️ 移动端 App 内购买（IAP）------ 必须提前决策的坑
- ADR-020：订单状态机与幂等回调
- 8.3 订阅生命周期
- 8.4 发票与税务
- 8.5 支付验收标准
## 第 9 章 · 内容安全与合规
- 9.1 需求分析：合规义务清单（cn region）
- 9.2 设计与自我论证
- ADR-021：三段式审核架构
- ADR-022：AIGC 标识的实现
- ADR-023：数据出境的绝对红线
- 9.3 未成年人保护
- 9.4 用户举报与申诉
- 9.5 隐私与用户数据权利
- 9.6 合规验收标准汇总
## 第 10 章 · 风控与滥用防护
- 10.1 威胁模型
- 10.2 防护矩阵
- 10.2.1 T1 批量注册
- 10.2.2 T2 API 倒卖
- 10.2.3 T5 消费失控 ------ 三层预算护栏
- 10.2.4 T4 越狱与违规生成
- 10.2.5 T8 资源耗尽
- 10.3 风控引擎设计
- 10.4 风控验收标准
## 第 11 章 · 存储与产物管理
- 11.1 需求分析
- 11.2 设计与自我论证
- ADR-024：对象键设计
- ADR-025：产物转存必须是独立的、可重试的作业
- ADR-026：分级存储与生命周期
- ADR-027：访问控制 ------ 签名 URL，永不公开桶
- 11.3 文件安全
- 11.4 存储验收标准
## 第 12 章 · 可观测性与数据平台
- 12.1 需求分析
- 12.2 设计
- 12.2.1 关联键：request_id 贯穿一切
- 12.2.2 三支柱 + LLM 专用维度
- 12.2.3 必备指标清单
- 12.2.4 SLO 与告警
- 12.2.5 日志规范
- 12.3 Admin 数据看板（必须实现的页面）
## 第 13 章 · 知识库、RAG 与工具生态
- 13.1 需求分析
- 13.2 设计
- 13.2.1 文件处理流水线
- 13.2.2 分块策略
- 13.2.3 检索
- 13.2.4 引用与溯源
- 13.3 工具与 MCP
- ADR-028：工具体系对齐 MCP
- 13.4 知识库验收标准
## 第 14 章 · 前端与多端
- 14.1 需求分析与端矩阵
- ADR-029：桌面端必须有本地独占价值，否则不做
- 14.2 共享层设计
- 14.3 关键前端能力
- 14.3.1 流式渲染
- 14.3.2 成本预估器
- 14.3.3 错误处理与用户可理解性
- 14.4 设计系统与可访问性
- 14.5 前端验收标准
## 第 15 章 · 非功能需求（NFR）
- 15.1 性能
- 15.2 可用性
- 15.3 安全
- 15.4 可维护性
## 第 16 章 · 测试策略与质量门禁
- 16.1 测试金字塔
- 16.2 关键测试基础设施
- 16.2.1 Provider Mock Server（★ 必须先建）
- 16.2.2 数据库测试
- 16.2.3 属性测试（Property-based）
- 16.3 CI 质量门禁
- scripts/verify-acs.ts（★ 本文档的自动化闭环）
- 16.4 压测与混沌
## 第 17 章 · 交付路线图
- M0 · 地基（预计 5%）
- M1 · 网关 + 计费核心（预计 30%）★ 最关键
- M2 · 身份 + 应用引擎（预计 20%）
- M3 · 前端 + 完整场景（预计 20%）
- M4 · 安全合规 + 支付（预计 15%）
- M5 · 可观测 + 加固 + 发布（预计 10%）
- 里程碑依赖图
## 第 18 章 · 风险登记册
## 附录 A · 统一 API 契约概要
- A.1 业务 API（services/api）
- A.2 网关 API（services/gateway）
## 附录 B · 错误码表
## 附录 C · 环境变量清单
## 附录 D · 数据字典速查
## 附录 E · Coding Agent 执行协议
- E.1 总则
- E.2 提交纪律
- E.3 中断恢复协议（★ 重要）
- E.4 禁止事项
- E.5 遇到歧义时的决策顺序
- E.6 自检清单（每个里程碑结束时执行）
## 结语：这份文档的三条核心判断
## 附录 G · v1.1 横向评审修订记录
- G.1 采纳的修订（8 项）
- G.2 自主强化（受启发但做了不同处理）
- G.3 对读后仍然坚持的判断（4 项）
- G.4 一个诚实的观察如果全部贴出来，绝对爆掉，所以我会把所有文档和后续模型的源代码统一放到网盘上面！
公众号【甲维斯C】发消息"aiaio"即可获取！