Appearance
平台能力现状（2026-09-15）—— 已落地 / 待开闸 / 后移
读者：人类工程师与 AI coding agent。读完应知道「现在能接什么、什么还不能对用户承诺」。 状态基准：2026-09-15。对照仓库
ai_developtip：平台能力实装波次（PE）代码面已收官；基座正式域名路径（PE3-7）已落盘；内容护栏 CG1+CG2（本地层 + LLM 裁决，影子模式）已合入（ADR-0064）；内容专栏 CB1~CB5（数据面→管理台→SSG 渲染→匿名 /blog 公共读取面→验收编排）已合入（ADR-0065）；站内信 IM1~IM4（单向通知全链 + 用户级 SSE + 三 SPA 消息中心 + 试点验收收官）已合入（ADR-0066）；品牌使能 BA1/BA3/BA4/BA5（品牌资料 per-realm 数据面 + 通用文件前门 + builder 品牌设置页 + ops realms 只读页 + 建租户勾选造册）已合入（ADR-0067/ADR-0068），BA6 真栈验收已收官（2026-09-15：本地等价栈 23/23 + ECS-B 21/21 + owner 人工主线五步全绿）。 契约：端点与字段以openapi.yaml为准。仓库内 openapi 部分路径仍是设计意向、可能滞后实装——照本文与各 how-to 的 curl 形状发请求；冲突时以实装行为为准并回报勘误。 不写过程资产：任务包 / 研讨 / 内部留言板不在对外树。欠账用本页内联，不链到仓内过程目录。
1. 现在就能用来孵化 SaaS 的
| 能力 | 你怎么用 | 入口 |
|---|---|---|
| 会话 Agent（多轮 SSE、选项卡、断连重拉、freeze→settle） | 模式 B 浏览器 JWT，或模式 A API-Key + 影子用户 | first-saas · cookbook · 协议 |
| 多模态（STT / TTS / 附件 / vision / 文生图） | 同一会话通道，按发布快照开关 | ai-agent 指引 §4 · cookbook §7~§11 |
知识库 Tier B（结构感知分块、父子检索、hybrid、chapter_path） | 建 KB → 绑到 Agent → 会话内 kb_search | 知识库检索 |
| 身份：OIDC + JIT + 多归属切换 | 模式 B 零自建用户表；跨域 RLS 硬隔离 | mode-b §3 |
| 多 realm + 品牌自托管边缘 | 一条产品线 = 一品牌域 + 一 realm + 一台自己的服务器 | 品牌自托管 |
| 钱包（域内合一）+ 流水项目归因 | 余额 tenant+user；operation_id 对账 | cookbook §12 · first-saas §5 |
| 终端用户读余额 / 流水 | saas_user 已含 billing:points:read 与 billing:ledger:read（2026-08-30 合入，旧文档里的「积分页 403」已过期） | GET /api/v1/billing/points/balance · .../ledger |
| 薄壳模板 | frontend/packages/web-saas-template + new-saas-app.mjs | mode-b |
使能路线不变：自营 / 孵化走模式 B；自带存量用户体系的外部二开走模式 A。代码级垂直通道冻结。
2. 代码已收口、对用户还不能承诺「已开闸」
这些是当前主线剩余工作。文档可以讲清形状，不要在产品文案里写成「已对终端用户开放」。
| 项 | 代码面 | 还缺什么 | 失败形态 |
|---|---|---|---|
| Google 登录 | realm 模板已有 google IdP 占位；一个 Google OAuth client 多条 redirect URI（基座 + 各品牌） | 海外节点可达 oauth2.googleapis.com；正式 TLD + TLS；把 client 凭据写入各 realm 并 enabled:true | 未启用时登录页没有 Google 按钮；KC 在大陆机房出站 Google 会失败 |
| PayPal 充值 | 渠道/币种列、USD 档位目录、adapter（httpx 零 SDK）、webhook POST /api/v1/billing/webhook/paypal、入账幂等 pp_cb:<capture_id> | 商家账号 + 外汇合规；live/sandbox 凭据入密钥库；POST /api/v1/payment/orders 的 trade_type=PAYPAL_WEB 仍 503 fail-closed | 无凭据 → webhook 503；未开闸下单 → 503 trade_type 'PAYPAL_WEB' is not enabled |
| 微信支付开闸 | JSAPI + Native 全链、wx_cb: 入账幂等、充值目录 wechat/CNY 四档 | 商户凭据入密钥库；真 1 分钱扫码 → 入账 → 退款 → 对账 | 无出站服务 → Native/JSAPI 503；开闸前模式 B 用运营 tenant_grant |
| 内容专栏 / Blog 公共阅读面（已验收，ADR-0065） | 数据面（专栏/文章/slug 301/配额 1000/RLS）+ Builder 管理台「内容」区 + 发布时 SSG 渲染（加固 markdown→整页 HTML 落库）+ 匿名 /blog/* 公共读取面（ETag 304 / 真 404 / 旧 slug 301 / sitemap·rss·llms·robots 按 SEO 政策生成 / 域名隔离）；网关与品牌边缘反代 + 边缘缓存已配置 | 验收收官（CB5：测试栈 + SGP 生产段均 13/13 全绿〔2026-09-12，生产段真证书 https://bhsl.cc〕）+ GSC/Bing 收录观察（DNS 权在租户侧）；全租户开放 = owner 决策点 | 全租户开放未开闸前不对终端用户承诺「博客已开放」；curl 全链见 Hello Agent §12，收录 runbook blog-seo-verification |
| 内容护栏（影子模式，ADR-0064） | 发布快照 content_guardrail.mode（off|shadow，缺席 = 平台默认 off，存量 Agent 零行为变化）；本地层 = PII 校验位规则（手机号 / 身份证校验码 / 银行卡 Luhn / 统一社会信用代码）+ 三级词表（block/mask/review）；模糊命中才升级 LLM 裁决（走 ModelRouter、平台侧归账不计租户账单、fail-open，平台开关 CONVERSATION_CONTENT_GUARDRAIL_ADJUDICATION_ENABLED 默认关）；命中只落 WORM 审计（content 类目 + 脱敏 excerpt，不落 PII 明文） | enforce 拦截 + 用户申诉 / 运营复审闭环（CG3，按影子期误判率达标后启用）；词表 DB 化 + web-ops 管理面；CN 完整词表绑定大陆回迁里程碑 | shadow 期只审计不拦截，内容如实放行——不要对用户承诺「内容审核已生效」 |
| 站内信 / 消息中心（已验收，ADR-0066） | 平台→用户单向通知全链：公告广播（inbox:manage，幂等键重放安全 / 每租户日 10 批 + 总量 10000 配额 / suspended 跳过 / WORM 审计不留正文）+ 用户收件箱（list/summary/已读/软删，inbox:read 仅本人）+ 用户级 SSE 实时推送（/api/v1/events/inbox，快照补位 + message_created 实时帧）+ 三 SPA 消息中心（铃铛红点/抽屉/已读）+ ops 发送台；appeal_result 消息类型已接 CG3 申诉事件缝（订户在位，事件源待 CG3） | 试点验收收官（IM4：本地等价栈 18/18 + ECS-B 真栈 9/9 + 人工主线判据 1~3 全绿〔2026-09-12〕；人工轮缺陷账 #377/#378/#380 已登记，#378 已修复）；CG3 裁决事件源排程对齐；平台开放全租户公告 = owner 决策点；用户间私信（IM5）延后池（触发 = 真实需求 + owner 拍板） | 全租户公告开放未开闸前不对终端用户承诺「已开放」；curl 全链见 Hello Agent §13；验收 runbook（docs/ops/im4-inbox-acceptance.md，仓内运维面，不入对外站） |
| 品牌资产自助（已验收，ADR-0067/ADR-0068） | brand_profiles per-realm 单行（七列全可空 + 回落链解析平台默认）+ 首例 realm 级 RLS 策略族（同 realm 全租户可读 / 仅运营租户可写 / 跨 realm fail-closed）+ 通用文件前门 `POST /api/v1/files:authorize | :commit（purpose 注册表代码驱动，brand-asset档收 png/jpeg/webp 禁 svg ≤2MB，sha256 顺序幂等）+ 品牌 APIGET/PATCH /api/v1/brand/profile（diff 审计 old/new）+ ops 建租户勾选「设为品牌运营租户」同事务造册（INSERT-or-409 不改派）+ web-ops /realms` 只读页（绑定租户数 / JWKS 探针 / 品牌完备度列）+ builder 品牌设置页 | 已验收（BA6：本地等价栈 23/23 + ECS-B 真栈 21/21 + owner 人工主线五步全绿〔2026-09-15〕；验收脚本 ba6-acceptance-testbed.sh + runbook docs/ops/ba6-brand-acceptance.md，仓内运维面）；博客品牌呈现 + 贴图上传（BA2）= owner 立项决策点；品牌 realm 真栈创建 = PE3-1 人工段 |
建设者侧入口：Builder 发布抽屉的「内容护栏」三态开关（平台默认 / off / 影子观察），或发布 API 的 conversation.content_guardrail 块（见 Hello Agent §10.1）。
充值目录已经按渠道×币种返回（GET /api/v1/billing/recharge-plans，公开、无需鉴权）。前端必须按自身渠道过滤，禁止硬编码价格。细节见 支付与充值。
3. 后移到「大陆回迁」的
初期 SaaS 主攻海外（海外节点 + 海外域名 + Google + PayPal）。下列能力代码骨架或 mock 段可能已在仓内，但产品排期整体后移，回迁条件 = 经营许可 / 备案 / 开放平台认证 / 商户号就绪后再复跑既有冒烟：
- 微信网页扫码登录（OIDC 桥）
- 微信小程序登录 / 支付 openid 绑定的完整运营闭环
- 微信真金扫码开闸（与 §2 微信支付开闸同一运维闸门，只是验收场在大陆）
- 手机号短信登录（更后，短信签名备案）
不要按「大陆微信生态已对外部开发者开放」来设计当前海外产品线。
4. 已知产品缺口（文档如实，平台当前做不到或需规避）
| 缺口 | 你怎么规避 |
|---|---|
| 非 LLM 模态注册 UI 缺单价字段 | API 注册 stt/tts/image_gen 时带上 unit_price/price_unit，否则首次调用 500 MODEL_USAGE_METADATA_MISSING |
| 轮次墙钟默认 60s 对画图 / SOP 太紧 | 发布时 turn_timeout_seconds ≥ 180 |
| STT 高峰 85s+ 无进度 UX | 前端按分钟级等待设计 |
| STT/TTS 供应商锁定 DashScope 协议族 | 语音模型 vendor 必须 dashscope |
| Token Plan 网关只服务 chat | 语音 / 画图另配经典按量 key，两把不可混用 |
| 会话钉死打开时的 Agent 版本 | 发新版后开新会话（换 client_conversation_key 或不传） |
cost_records 无租户自助查询端点 | 模型成本归因存在，对账目前走运营侧 |
仓库 openapi.yaml 与部分实装请求体不一致（Agent 注册/发布、KB 创建、users:provision） | 照各 how-to / cookbook 的 curl 形状；那些形状对齐活着的 FastAPI |
5. 给 AI coding agent 的一句话
先读 llms.txt 和本页 §1~§3，再按角色进 总索引。不要向用户承诺 Google / PayPal / 微信已经「能收款或能一键登录」，除非运维确认对应闸门已开。