主题
四、扩展平台
本章速览:读完后你会知道 —— ① 一个扩展从草稿到上线经历哪 5 关;② 调度器每 30 秒只做哪 3 件事;③ 一次运行如何被策略、能力网关与效果幂等约束;④ 系统扩展(晨报/提醒/日报…)为什么都是 14 个插件而不是 Java Job;⑤ 出问题后如何熔断、回滚与自愈。
一句话:把"定时/触发的自动化"从 Java 代码里搬到可安装、可审计、可回滚的插件体系。 2026-11 之后,晨报/晚报/关怀/提醒/周复盘/访谈邀请/线头提起等"主动能力"全部是扩展; 它们共享同一套触发器、运行、能力、策略、效果与自愈机制,而不是各自写一个
@Scheduled。
4.1 领域模型(24 张表)
| 概念 | 表 | 说明 |
|---|---|---|
| 包 / 版本 | extension_package + extension_version | 包是逻辑单元(key 唯一),版本是不可变快照(manifest + 代码 + 签名 + runtime 类型) |
| 草稿 | extension_draft | 作者编辑中的版本;validate → test → publish 三关 |
| 安装 | extension_installation | 每包一行:status(pending/active/paused/disabled)、active 版本、自检标记、禁用原因 |
| 触发器 | extension_trigger | schedule/once/webhook/manual;next_run_at(UTC)、认领、并发、重试、补投窗口、版本策略 |
| 运行 | extension_run + extension_run_event | 一次执行的 queued→running→succeeded/failed/skipped 全生命周期与事件流 |
| 能力 | extension_capability + extension_capability_call | 能力声明与每次调用的审计(谁、什么能力、参数摘要、结果、耗时) |
| 策略 | extension_policy_decision | 每次运行前的判定现场(全局开关/静默/预算/花费/频率),排查"为什么被拦" |
| 效果 | extension_effect | 运行产出的副作用意图(消息/写文章等),幂等键 + 重试 + 补偿标记 |
| 审批/授权 | extension_grant、extension_approval、extension_spend_grant、author_quota | HIGH 风险能力的人工授权、付费能力的当日花费授权、作者配额 |
| 预算 | extension_budget_ledger | 按插件/日/月记账(token、消息数) |
| 密钥 | extension_secret | 插件密钥(加密存储,不回显) |
| 自愈/状态 | extension_repair_attempt、extension_state、extension_test_plan、extension_registry_entry | 回滚尝试、运行状态快照、dry-run 记录、注册表条目 |
| 消息 | extension_message + extension_message_delivery、webhook_delivery | 扩展产出消息与投递、出站 webhook 投递记录 |
4.2 生命周期:从草稿到运行
平台表清单(现存 24 张)见 §7.2;生命周期只描述状态流转,不重复列字段。
draft(editing) ─validate─> ready ─test(dry-run)─> published(version 不可变)
│
install ──> installation(pending)
│ activate
▼
active ──pause──> paused
│ └──uninstall──> disabled
▼
trigger enabled → scheduler 认领 → run发布链(作者侧,通常由 AI 通过扩展 MCP 工具完成):
extension_draft_create/update:写 manifest 与代码;extension_validate:结构、契约、能力、权限、代码沙箱静态检查;extension_test:dry-run(录制模式)—— 不真实外呼、不提交 effect,返回将访问的 capability/host 清单与录制结果;extension_publish:生成不可变版本 + 签名(ExtensionArtifactSigner);extension_install/activate:安装先pending,自检通过后才能active(自检是安装级标记, 换版本必须重跑,防止"旧版本自检过、新版本直接启用")。
运行时类型:
| 类型 | 说明 | 现状 |
|---|---|---|
builtin | 后端内置 handler(Java),系统扩展用 | 14 个系统包在跑(9 个 handler + 5 个 builtin-service) |
builtin-service | 无 handler/触发器,只为能力健康看板承载判据(通知投递/链路探针/采集心跳/日报/提醒) | 用于"不是扩展但需要判据"的能力 |
pipeline | 声明式步骤(read → transform → effect) | 可用 |
script | 沙箱脚本(Node,cwd 受限、能力经网关) | 可用 |
agent | 交给微信桥 /agent 跑 DSH headless(含工具白名单、输出 schema、超时) | 未部署(见 13) |
(已移除)event 触发器 | 无事件源,永久拒绝创建 | 防止"显示启用、永不触发"的死触发器 |
4.3 触发器:调度器只做三件事
ExtensionTriggerScheduler 每 30 秒轮询:
- 取 due:
enabled=1 AND status=active AND next_run_at <= UTC now(按 UTC 比较, 因为时间统一存 UTC;用本地时间判会误报,审查 #83 踩过这个坑); - 认领:CAS 更新
claimed_by/claimed_until(next_run_at不变,防重复认领); - 异步执行:提交线程池 →
ExtensionRunService.execute。
ExtensionTriggerService 负责创建/更新/校验:
schedule必须有合法 cron(CronExpression.parse),once必须有onceAt,事件类型直接拒绝;- 时区默认
Asia/Hong_Kong,next_run_at统一转 UTC; catchUpMinutes(0–1440)决定"错过多久之内还补跑";concurrency(1–10)限制同触发器并发;maxAttempts(1–5)失败重试;versionPolicy=follow/pin决定跟最新版还是钉版本;- 改 cron/时区后立即重算
next_run_at,否则仍按旧时间跑(审查 #53 的教训); - 系统扩展的 seed 改了时间,会通过
updateSchedule收敛到已装触发器("manifest 会升级, 触发器不会"是同一类漂移问题)。
4.4 一次运行的完整管线
ExtensionRunService.execute 的步骤(读代码时按这个顺序看):
- 解析身份:
run_identity = trigger + scheduledAt (+ manual id);同 identity 已成功则直接返回 (幂等);同 identity 失败则 attempt+1 重试;dedup_key唯一索引兜底并发。 - 版本解析:
versionPolicy=follow取安装的 active 版本,pin取 pinned 版本; 签名校验(ArtifactSigner.verifyOrThrow)。 - 策略判定:
ExtensionPolicyService.beforeRun依次检查 全局熔断开关 → 安装是否 active → 静默时段(提醒管道豁免)→ 月度 token/消息预算 → 花费闸(manifest 含llm.*需当日授权)→ 每小时运行数上限 → 主动消息日限额。 判定结果与现场快照写extension_policy_decision;不允许则 run 记skipped并返回理由。 - 并发限制:同触发器活跃 run 数 ≥ concurrency → skipped(不排队堆积)。
- 执行:按 runtime 类型分派;能力网关是四层包装:
ScopedCapabilityGateway(manifest 声明范围)→GrantCheckedCapabilityGateway(HIGH 风险需授权) →AuditedCapabilityGateway(每次调用写 capability_call)→DefaultCapabilityGateway(真正实现)。 dry-run 用DryRunCapabilityGateway录制,不真实执行。 - 输出校验:结果必须符合
cosmos.extension/output.v1schema(builtin/agent 各有约束)。 - 效果提交:运行返回的 effect intents 先落
extension_effect(幂等键含 identity + 能力 + 序号), 由EffectApplier异步执行;deliver.message只写消息账本,真正投递交给通知链; 写内容类效果只允许草稿。 - 收尾:
succeeded/failed、run 事件、token 记账(失败不影响已成功状态)、 连续失败触发熔断暂停(pause_after_consecutive_failures)。
4.5 系统扩展与内置 handler
系统扩展(origin=system)由 SystemExtensionProvisioner 在启动时幂等种子: 包/版本/安装/触发器/能力声明缺什么补什么;seed 与线上配置漂移时以 seed 为准收敛 (cron 时间由配置键管理时走 scheduleOwnedByConfig,避免与监听器互相覆盖)。
| 包 | 能力(摘要) | 触发 | 设计要点 |
|---|---|---|---|
system.brief.morning/evening | 读日程/记忆/线头 + compose.resolve + deliver.message | 每天 07:40 / 22:30 | 晨晚报;预算/静默/去重;空产出给 skip 理由 |
system.care.checkin | 记忆检索 + 关怀记录 + 投递 | 每天 16:30 | 选材/去重窗口/静默时段;只记录不决定(3.5) |
system.reminder | reminder.pending.read + 预润色缓存 + 投递 | 每分钟 | 到点提醒;时间锚点不提前;润色失败发模板 |
system.digest.daily | llm.chat(或内置生成) | 每天 00:20(可配) | 每日总结;配置时间 → 触发器 cron 同步 |
system.weekly.review | 读一周数据 + compose + 投递 | 周日 20:30 | 周复盘 |
system.interview.invite | 读访谈候选 + compose + 投递 | 周日 20:30 | 访谈邀请(生活访谈 SOP 的触发点) |
system.open_loop.raise | 读线头 + compose + 投递 | 每天 09:30 | 提醒未了线头(受提及预算约束) |
system.feedback.judge | 读主动消息反馈 | 每小时 :15 | 反馈判定(有用/无用),回写 proactive_log |
system.capability.notify-delivery | —(builtin-service) | 无 | 只为能力健康看板提供"通知投递"判据 |
system.capability.ai-digest / daily-reminder / chain-probe / ingest-heartbeat | —(builtin-service) | 无 | 同上,分别给日报/提醒/链路探针/采集心跳承载判据 |
builtin handler 的公共约定(BuiltinOutputs / BuiltinExtensionHandler):
- 产出统一写成
slots.single(或结构化 slots),空产出用RuntimeResult.skip(title, reason); - 主动开关(
site.ai.proactive.enabled/site.ai.care.enabled/site.ai.digest.enabled) 在 handler 内读取并给出 skip 原因 —— 跳过必须有理由,不能静默; - 通知/消息类只调
deliver.message效果,不直接NotifyService(边界由架构闸守); - 每个 handler 有 golden case 测试(
SystemExtensionGoldenCaseTest42 条), 覆盖"正常/开关关/预算满/无候选/润色失败"等形态。
4.6 审批、密钥与花费
- HIGH 风险能力(发布文章、写记忆、生成图片等)安装/激活需人工授权:
extension_grant记录授权范围与版本;授权随版本变化失效(换代码 = 重新授权)。 - 花费闸:manifest 出现
llm.*即视为花钱能力;免费额度内放行,超出需"当日花费授权" (extension_spend_grant,次日失效);估算与实际用量写extension_budget_ledger。 - 密钥:
extension_secret加密存储;capability 里只暴露名字不暴露值; 前端只显示"已配置/未配置"。 - 作者配额:
extension_author_quota限制单作者可创建/发布的包数,防刷。
4.7 自愈、保留与熔断
| 机制 | 实现 | 行为 |
|---|---|---|
| 运行熔断 | ExtensionRunService 连续失败 ≥5(可配) | 暂停该触发器并记 pause_reason,避免每分钟刷失败 |
| 规则化自愈 | ExtensionRepairJob(每 15 分钟) | 熔断暂停的非系统插件回滚到"最后一个成功版本"并恢复;24h 内只回滚一次 |
| 修复升级 | ExtensionRepairEscalationJob(每 10 分钟) | 24h 内修复失败 ≥3 次 → 暂停安装 + 通知(按天去重) |
| 僵尸状态清理 | ExtensionRepairJob | 清"enabled 却带 pause_reason"的触发器;清"非 disabled 却带 disabled_reason"的安装(审查 #56/#83) |
| 保留 | ExtensionRetentionJob | run/run_event/capability_call 等按保留期分批物理删除 |
| 全局开关 | ExtensionKillSwitchService | 总开关:所有扩展运行在策略层被拒(global_kill_switch),用于失控时一键停 |
4.8 扩展 MCP 与观测
- 扩展 MCP(
POST /api/agent/extensions/mcp,40 工具):给 AI 一套"开发/安装/运行插件"的工具面; 40 个工具覆盖 search/get/draft/validate/test/publish/install/activate/pause/run/runs/effects/ trigger_* 等(附录 K 下半部分)。 - 观测:扩展中心页面直接读
extension_run/capability_call/policy_decision/effect;doctor.sh检查沙箱目录、令牌、挂载;extension-observe.sh提供命令行观测。
4.9 能力目录(为什么能力要先登记)
CapabilityCatalog 给每个能力声明四元属性:
| 属性 | 取值 | 用途 |
|---|---|---|
type | READ / EFFECT / INTERNAL / TRANSFORM | 决定是否产生副作用、是否需要审批 |
risk | LOW / MEDIUM / HIGH | HIGH 写能力需要人工授权 |
dataClass | PUBLIC / PRIVATE / SECRET | 与隐私分级/出网台账对齐 |
egress | true/false | 是否会把内容交给外部(模型/HTTP) |
systemOnly | true/false | 是否只允许系统扩展使用 |
CONTRACT_VERSION=1:manifest 声明的契约版本必须匹配;未登记的 dynamic 能力需要显式注册, 未实现的标记 markUnavailable(reason),校验器给出可读报错。48 项能力的完整清单见附录 N。