Skip to content

四、扩展平台 ​

本章速览:读完后你会知道 —— ① 一个扩展从草稿到上线经历哪 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_triggerschedule/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_quotaHIGH 风险能力的人工授权、付费能力的当日花费授权、作者配额
预算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 工具完成):

  1. extension_draft_create/update:写 manifest 与代码;
  2. extension_validate:结构、契约、能力、权限、代码沙箱静态检查;
  3. extension_test:dry-run(录制模式)—— 不真实外呼、不提交 effect,返回将访问的 capability/host 清单与录制结果;
  4. extension_publish:生成不可变版本 + 签名(ExtensionArtifactSigner);
  5. 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 秒轮询:

  1. 取 due:enabled=1 AND status=active AND next_run_at <= UTC now(按 UTC 比较, 因为时间统一存 UTC;用本地时间判会误报,审查 #83 踩过这个坑);
  2. 认领:CAS 更新 claimed_by/claimed_until(next_run_at 不变,防重复认领);
  3. 异步执行:提交线程池 → 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 的步骤(读代码时按这个顺序看):

  1. 解析身份:run_identity = trigger + scheduledAt (+ manual id);同 identity 已成功则直接返回 (幂等);同 identity 失败则 attempt+1 重试;dedup_key 唯一索引兜底并发。
  2. 版本解析:versionPolicy=follow 取安装的 active 版本,pin 取 pinned 版本; 签名校验(ArtifactSigner.verifyOrThrow)。
  3. 策略判定:ExtensionPolicyService.beforeRun 依次检查 全局熔断开关 → 安装是否 active → 静默时段(提醒管道豁免)→ 月度 token/消息预算 → 花费闸(manifest 含 llm.* 需当日授权)→ 每小时运行数上限 → 主动消息日限额。 判定结果与现场快照写 extension_policy_decision;不允许则 run 记 skipped 并返回理由。
  4. 并发限制:同触发器活跃 run 数 ≥ concurrency → skipped(不排队堆积)。
  5. 执行:按 runtime 类型分派;能力网关是四层包装: ScopedCapabilityGateway(manifest 声明范围)→ GrantCheckedCapabilityGateway(HIGH 风险需授权) → AuditedCapabilityGateway(每次调用写 capability_call)→ DefaultCapabilityGateway(真正实现)。 dry-run 用 DryRunCapabilityGateway 录制,不真实执行。
  6. 输出校验:结果必须符合 cosmos.extension/output.v1 schema(builtin/agent 各有约束)。
  7. 效果提交:运行返回的 effect intents 先落 extension_effect(幂等键含 identity + 能力 + 序号), 由 EffectApplier 异步执行;deliver.message 只写消息账本,真正投递交给通知链; 写内容类效果只允许草稿。
  8. 收尾: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.reminderreminder.pending.read + 预润色缓存 + 投递每分钟到点提醒;时间锚点不提前;润色失败发模板
system.digest.dailyllm.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 测试(SystemExtensionGoldenCaseTest 42 条), 覆盖"正常/开关关/预算满/无候选/润色失败"等形态。

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)
保留ExtensionRetentionJobrun/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 给每个能力声明四元属性:

属性取值用途
typeREAD / EFFECT / INTERNAL / TRANSFORM决定是否产生副作用、是否需要审批
riskLOW / MEDIUM / HIGHHIGH 写能力需要人工授权
dataClassPUBLIC / PRIVATE / SECRET与隐私分级/出网台账对齐
egresstrue/false是否会把内容交给外部(模型/HTTP)
systemOnlytrue/false是否只允许系统扩展使用

CONTRACT_VERSION=1:manifest 声明的契约版本必须匹配;未登记的 dynamic 能力需要显式注册, 未实现的标记 markUnavailable(reason),校验器给出可读报错。48 项能力的完整清单见附录 N。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。