diff --git a/docs/agent-specs/2026-07-02-配置控制面阶段二-yudao配置中心-设计.md b/docs/agent-specs/2026-07-02-配置控制面阶段二-yudao配置中心-设计.md index 7a5c4a0b..eb903211 100644 --- a/docs/agent-specs/2026-07-02-配置控制面阶段二-yudao配置中心-设计.md +++ b/docs/agent-specs/2026-07-02-配置控制面阶段二-yudao配置中心-设计.md @@ -16,7 +16,7 @@ sot-impact: 修订 生成引擎运行时(SoT §5.2 管理面配置管理 / §5.8 - game-cloud huijing-module-bpm(审批,放量后)· huijing-module-system(操作日志 + 权限,yudao 原生)· game-module-aigc(生成配置治理落点)· huijing-module-infra(Nacos SCA 通路 + infra_config KV 参照) - game-admin/src/views/wanxiang(配置编辑面,阶段三消费) - commit hash:待收口填 -图清单: [图0 一图看懂, 图1 分工边界与四方职责, 图2 配置生命周期与双路激活, 图3 失败模式与兜底] +图清单: [图0 一图看懂(待补), 图1 配置中心分层与分工, 图2 双路激活编排, 图3 激活一致性状态机, 图4 漂移对账三态] --- # 配置控制面 · 阶段二:yudao 配置中心 · 功能设计 @@ -50,7 +50,7 @@ sot-impact: 修订 生成引擎运行时(SoT §5.2 管理面配置管理 / §5.8 ## 2 边界 -(图1 分工边界 SVG 待补) +![图 1 · 配置中心分层与分工](assets/cfgctl2-01-配置中心分层与分工.svg) 进控制面的判据沿用 SoT §5.8 的配置三类;本阶段只碰其中"热配置策略类"里属于**生成业务**的那部分,并给它加治理。 @@ -109,11 +109,13 @@ stateDiagram-v2 待审 --> 草稿: 驳回 ``` +![图 3 · 激活一致性状态机](assets/cfgctl2-03-激活一致性状态机.svg) + 几个关键点。**激活之前 Nacos 完全不被触碰**:草稿与版本行都是 yudao 库内数据,配置内容到"激活"才第一次离开治理库——这天然堵死了"草稿提前生效"的口子(Nacos 的配置是 publish 即被监听者读到的,预算/阈值若提前进 Nacos 就绕过了激活闸)。**激活是独立的闸**:它把选定版本的内容双路下发(见 §3.3),并把"当前激活版指针"指过去。**回滚就是重放激活**:取历史版本行的内容,走一遍激活动作,幂等。**归因与审计随生命周期自然沉淀**:定版记 creator 与时间,激活/回滚是一条 yudao 操作日志,diff 是两条版本行的就地比对——全是 yudao 原生能力,不新造。 ### 3.3 双路激活:PATCH 路 ⊕ Nacos 热读路 -(图2 配置生命周期与双路激活 SVG 待补) +![图 2 · 双路激活编排](assets/cfgctl2-02-双路激活编排.svg) 激活一个配置集,编排层从选定的版本行取内容,按旋钮性质分两路下发: @@ -166,7 +168,7 @@ flowchart LR ### 3.6 失败模式与兜底 -(图3 失败模式与兜底 SVG 待补) +![图 4 · 漂移对账三态](assets/cfgctl2-04-漂移对账三态.svg) 激活是一批跨系统的非原子写(PATCH Service + publish Nacos + 更新 yudao 指针),这里的失败模式要正面处理,不能让配置中心把生成链路带崩。 @@ -289,9 +291,10 @@ flowchart LR | 图 | 角色 | 状态 | |---|---|---| -| 图0 一图看懂 | §0 门面 SVG | 待 opus 子代理出图 | -| 图1 分工边界与四方职责 | §2/§3.5 SVG | 待出图 | -| 图2 配置生命周期与双路激活 | §3.2/§3.3 SVG(内联 Mermaid 事实源已在文) | 待出图 | -| 图3 失败模式与兜底 | §3.6 SVG(内联 Mermaid 事实源已在文) | 待出图 | +| 图0 一图看懂 | §0 门面 SVG | 待出图 | +| 图1 配置中心分层与分工 | §2 / §3.1 / §3.5 分工边界与四方职责 | 已出图 `assets/cfgctl2-01-配置中心分层与分工.svg` | +| 图2 双路激活编排 | §3.3 双路下发编排(内联 Mermaid 事实源已在文) | 已出图 `assets/cfgctl2-02-双路激活编排.svg` | +| 图3 激活一致性状态机 | §3.2 生命周期 + §3.6 ACTIVATING 恢复(内联 Mermaid 事实源已在文) | 已出图 `assets/cfgctl2-03-激活一致性状态机.svg` | +| 图4 漂移对账三态 | §3.6 配置漂移检测三态 | 已出图 `assets/cfgctl2-04-漂移对账三态.svg` | 文字 + Mermaid 为事实源,SVG 为派生视觉。 diff --git a/docs/agent-specs/assets/cfgctl2-01-配置中心分层与分工.svg b/docs/agent-specs/assets/cfgctl2-01-配置中心分层与分工.svg new file mode 100644 index 00000000..2ac90584 --- /dev/null +++ b/docs/agent-specs/assets/cfgctl2-01-配置中心分层与分工.svg @@ -0,0 +1,124 @@ + + + + + + + + + + + + 图 1 · 配置中心分层与分工(yudao 版本账本 ⊕ Nacos 生效下发) + 配置中心把职责劈两半、各用现货:yudao 管治理与版本账本(版本行落 MySQL),Nacos 管路 B 生效下发。谁改决定要不要治理;prompt 正文因 100KB 上限出 Nacos、进 MySQL 版本行。 + + 整图状态——实线 = 现行已落地(五步 2026-07-04 全落、mini-desktop 真机 smoke 验过) · 紫虚线 = 后续阶段(阶段三 UI / 阶段四观测 / 放量后 BPM 审批)。业务生成配置与基建配置在 Nacos 上以命名空间隔离。 + + yudao —— 治理与版本账本(权威) + 版本行 = 全量内容(含 prompt · MEDIUMTEXT)+ 元数据 + 当前激活版指针 · creator · 状态机 · 审批挂点 · 操作审计 · 激活编排 + ⊕ + + Nacos —— 路 B 生效下发通道 + publish 预算 / 门阈值到生效 dataId(按档隔离)· worker 长轮询热读 + 不承版本账本(生效 dataId 上的历史只是排障留痕、非权威) + + 分工边界 + + 基建配置 —— 不进本治理层(阶段〇已接,运维改即时热生效) + + 业务生成配置 —— 受治理版本化(本阶段治理对象) + + 例子 + + game-cloud Spring 配置 · Sentinel 流控规则 · RocketMQ 参数 · 服务发现 + + prompt · 模型 · 参数 · 软预算目标 · 门阈值档 + + 谁改 + + 运维 / 开发 + + 创始人 / 运营 + + 要不要治理 + + 不要 —— 即时热生效即可 + + 要 —— 版本 / 审计 / 审批 / 可回滚 + + 通路 + + Nacos SCA 原生(dataId 按应用名 · @RefreshScope 或重启) + + yudao 治理层(MySQL 版本行为账本)→ 激活时 PATCH Service、publish 生效 dataId(双路) + + 消费方 + + game-cloud 各 Java 服务 + + AgentScope Service(路 A PATCH)+ Python worker(路 B NacosHotConfig) + + 账本单点 · 投影两处 · 消费两路(权威 → 投影 → 消费) + + 账本单点(权威) + yudao MySQL 版本行 + 全量含 prompt · 当前激活版指针 + + 路 A 投影:AgentScope Service 的 Redis + + 路 B 投影:worker genconfig(NacosHotConfig) + + 消费:每 POST /chat 现装配读出(热) + + 消费:middleware 构造时读(软预算 / 门判) + + 权威 vs 投影 + 账本单点(MySQL 版本行)· 投影两处 + (Redis / Nacos dataId)· 漂移对账见图 4 + + + + + + prompt 正文为何出 Nacos、进 MySQL 版本行(创始人拍 B 时点名要解) + + ① 放不进 Nacos + 单配置默认上限 100KB;system_prompt 连 few-shot、 + 多角色随版本行增长向上限爬(现最大单条 14.7KB) + 把最勤改的旋钮放上限边缘,不如换地方 + + ② 定版要原子 + 版本行(元数据 + 全量内容)同库同事务一次落 + 内容一旦出库即成跨系统写、必漂移 + 治理层最高频动作不该是分布式事务 + + ③ diff 与检索要就地 + 版本 diff、按内容查历史都是版本行本地操作 + 内容在外部系统则每次 diff 都要来回取对象 + 两版 diff 在应用层做 + + 结论:prompt 正文列定 MySQL MEDIUMTEXT(16MB)、不落 Nacos 也不落 MinIO;Nacos 收窄为路 B 生效下发通道、不承版本账本。 + 图例: + + 业务生成配置 / 路 A(yudao · Redis) + + 基建 / 路 B 生效下发(Nacos) + + 关键约束 / 边界说明 + + 数据 + + 安全 + 版本账本 = 数据治理 · 权限 / 审批 = 安全 + 读这张图抓三点:① 配置中心两半 —— yudao 管治理与版本账本、Nacos 管路 B 生效下发,各用现货、不自建下发机制; + ② 谁改决定要不要治理 —— 运维 / 开发改基建配置走 Nacos SCA 原生,创始人 / 运营改业务生成配置走 yudao 受治理;③ prompt 正文因 100KB 上限、定版原子、就地 diff 三条,落 MySQL MEDIUMTEXT、不落 Nacos。 + 映射：本档 §3.1 配置中心两半 · §3.5 分工边界 · §附 图1 ｜ 状态：现(五步已落地 2026-07-04)+ 建(阶段三 UI / 阶段四观测 / 放量后 BPM)｜ 设计变动须同步本图 + diff --git a/docs/agent-specs/assets/cfgctl2-02-双路激活编排.svg b/docs/agent-specs/assets/cfgctl2-02-双路激活编排.svg new file mode 100644 index 00000000..a3213d20 --- /dev/null +++ b/docs/agent-specs/assets/cfgctl2-02-双路激活编排.svg @@ -0,0 +1,106 @@ + + + + + + + + + + + + 图 2 · 双路激活编排(sanity 前置 → 快照 → 双路下发 → 指针前移) + 激活一次 = 值域 sanity 前置拒发 → beginActivating 快照(单库事务)→ 路 A PATCH 与 路 B publish 并行下发 → 全成才 markVersionActivated 指针前移;任一步败即整批判未生效、立即补偿重推已成功路回上一激活版。 + + 整图状态——实线 = 现行已落地(步骤 3 双路激活 72973532、路 A 复数端点修复 22444fd5) · 红线 = 失败补偿路。跨系统非原子、投影写即被读:不承诺投影层原子,靠即时补偿收敛。 + + 触发 + yudao 选定一版本发起激活 + + ① sanity 值域前置拒发 + 预算正数落区间·单位固定 / 超时有下限 / max_tokens ＞ thinking + / 模型 type 配 credential / prompt 非空 —— 不过即拒、不下发 + + ② beginActivating 快照 + 下发前先把激活态落 ACTIVATING + (单库事务 · V30 持久中间态) + + + + 双路并行下发 + + 路 A · prompt / 模型 / 参数 —— PATCH 写 Service Redis(下一 POST 现装配即生效) + + PATCH /agent + system_prompt · 压缩比 · 截断 · max_iters + + PATCH /sessions + 模型 · type · credential · max_tokens · thinking + + AgentScope Redis + 当前配置投影 + + 下一 POST /chat + 现装配读出、热生效 + + + + + 路 B · 软预算目标 / 门阈值 —— publish Nacos 生效 dataId(worker 长轮询热读) + + publish 生效 dataId + 按档隔离 · 只发本档 + + NacosHotConfig + 长轮询推送热读进进程 + + genconfig 门面 + 热源投影 + + middleware 构造时读 + 软预算 / 门判取新值 + + + + + + + ④ 双路全成 → markVersionActivated 指针前移 → 状态转 ACTIVE + 当前激活版指针只在整批成功后前移;成组下发幂等,静默期只对下一批新生成生效 + + ✕ 任一步失败(某 PATCH 返错 / Nacos publish 超时 / Service 不可达) + → 整批判未生效(当前激活版指针不前移)→ 立即补偿:把已成功下发的那一路重推回上一激活版 → 标可重试(补偿与重放幂等) + + 任一步败 + + 静默期语义(为何并发几乎不撕裂) + 两路生效都落在「下一次生成」边界:路 A 的 Redis 在进 session 锁前读、 + 路 B 的 genconfig 在 middleware 构造时读,正跑的那局早已读过配置。唯一 + 撕裂窗口 = 激活自身中途失败(投影写即被读、无事务),靠即时补偿收敛。 + + 两处必须定死的下发口径 + 路 A:改任一模型参数都要从版本行组装完整 chat_model_config + (整体替换、顶层 exclude_unset 不深合并内部 parameters)。 + 路 B:生效 dataId 按档隔离(cheap_rmb_hard_limit / rmb_hard_limit),激活哪档只发哪档。 + 图例: + + 路 A(PATCH → Service Redis) + + 路 B(publish → Nacos 热读) + + 双路全成、指针前移 + + 失败 → 补偿重推回上一激活版 + + 可靠 + 读这张图抓三点:① 激活是独立的闸 —— sanity 校验拦住语义非法值(负预算等)、快照先落 ACTIVATING,再双路并行下发; + ② 权威只在双路全成后前移,任一步败即判未生效并立即补偿,不留「路 A 新、路 B 旧」的持续撕裂;③ 并发撕裂由静默期规避,机制级原子(epoch 戳)留放量后。 + 映射：本档 §3.3 双路激活 · §4 步骤 3 · tech-decisions §14(激活一致性落地形态)｜ 状态：现(72973532 / 22444fd5)· 机制级原子留放量后 ｜ 设计变动须同步本图 + diff --git a/docs/agent-specs/assets/cfgctl2-03-激活一致性状态机.svg b/docs/agent-specs/assets/cfgctl2-03-激活一致性状态机.svg new file mode 100644 index 00000000..a7012ca2 --- /dev/null +++ b/docs/agent-specs/assets/cfgctl2-03-激活一致性状态机.svg @@ -0,0 +1,85 @@ + + + + + + + + + + + + 图 3 · 激活一致性状态机(草稿 → 待审 → 激活中 → 已激活) + 配置集的生命周期。激活前 Nacos 完全不被触碰;ACTIVATING 是 V30 持久中间态,账本提交失败留在此态由 recoverActivating 幂等收口;恢复语义按失败点位分「向前执行到底」与「补偿回退」两支。 + + 整图状态——实线 = 现行已落地(治理子域 Flyway V29 / V30 · 步骤 1+2 3ae34de1) · 紫虚线 = 后续阶段。MVP 创始人角色由待审直接激活、审批自动通过;放量后打开 BPM 审批,同一状态机不改。 + + 草稿 + yudao 库内数据 + + 待审 + 版本行已落库 + + 激活中 ACTIVATING + V30 持久中间态 + + 已激活 + 当前激活版指针 + + 已归档 + 被取代归档 + 起点 ● + + + 定版 + + 审核通过·发起激活 + + 双路全成·指针前移 + + 被更新版本取代 + + recoverActivating 幂等向前收口 + 账本提交失败·留 ACTIVATING + + 回滚 = 取历史版本行·重放激活(幂等) + + 驳回 + + 编辑出新版本 + + 激活之前 Nacos 完全不被触碰 + —— 草稿与版本行都是 yudao 库内数据,内容到「激活」才第一次离开治理库,天然堵死「草稿提前生效」。 + 激活是独立的闸:把选定版内容双路下发,并把「当前激活版指针」指过去;回滚就是重放激活(幂等)。 + + ACTIVATING 的两种恢复语义(按失败点位分开、不混用) + + 向前执行到底(补提交指针) + 失败点位:三路投影(PATCH /agent · PATCH /sessions · publish Nacos) + 都已成功、只差最后前移指针或写审计时 MySQL 失败。 + → 投影既已是新版,recoverActivating 补提交指针、对齐账本。 + + 补偿回退(重推旧版) + 失败点位:某一路投影下发失败,双路没能全成。 + 此刻不能把半生效态留在投影层。 + → 补偿重推上一激活版回投影 + 回滚该激活尝试,收敛回旧版。 + 图例: + + 正常流转 / 回滚(幂等) + + 驳回 / 补偿回退 + + 留 ACTIVATING · 幂等向前收口 + + 编辑出新版本(回边) + 读这张图抓三点:① 状态机把「编辑中」与「已生效」用一道激活闸分开,激活前 Nacos 不被触碰、堵死草稿提前生效; + ② ACTIVATING 是持久中间态(V30),账本提交失败不回滚成前态、留在此态向前收口;③ 恢复按失败点位二选一 —— 投影全成则补提交指针、投影没全成则补偿重推旧版,绝不停在中间态。 + 映射：本档 §3.2 生命周期 · §3.6 ACTIVATING 恢复 · tech-decisions §14(激活一致性落地形态)｜ 状态：现(Flyway V29 / V30 · 3ae34de1)· 放量后接 BPM 审批 ｜ 设计变动须同步本图 + diff --git a/docs/agent-specs/assets/cfgctl2-04-漂移对账三态.svg b/docs/agent-specs/assets/cfgctl2-04-漂移对账三态.svg new file mode 100644 index 00000000..1e4e6b4f --- /dev/null +++ b/docs/agent-specs/assets/cfgctl2-04-漂移对账三态.svg @@ -0,0 +1,109 @@ + + + + + + + + + + + + 图 4 · 漂移对账三态(IN_SYNC / DRIFT / 不可达) + 配置中心为权威、Service 与 worker 为投影;对账拉投影比对当前激活版,判 IN_SYNC / DRIFT 逐项 / 不可达三态。对账是兜底闸(第一道防线是即时补偿),读带 8s 容忍窗避开 Nacos 收敛中间态。 + + 整图状态——实线 = 现行已落地(步骤 5 漂移对账 a8dd5e50 · 8s 容忍窗) · 紫虚线 = 阶段四观测补。env 覆盖压过激活值这类漂移从 game-cloud 侧看不见,当前对账探不到,挂阶段四 worker effective 端点。 + + 权威 · 当前激活版 + + 路 A 内容 + prompt / 模型 / 参数(PATCH 目标) + + 路 B 内容 + 软预算目标 / 门阈值(dataId 目标) + + 对账动作(激活后 + 定期) + 拉 Service /agent(列表端点按 id 过滤,无单个 GET /agent/{id}) + + /sessions 当前配置 → 比对权威路 A 内容 + 拉 worker 生效投影 → 比对权威路 B 内容 + (含 env 覆盖口径:实际生效值来自 env 而非激活版也算漂移) + + 读带 8s 容忍窗(+800ms 步进)· 避开 Nacos publish→read 收敛中间态 + + + 对账判定三态 + + IN_SYNC —— 投影 = 当前激活版 + + DRIFT(逐项)—— 某旋钮投影 ≠ 激活版 + 逐旋钮列出差异;含 env 覆盖压过激活值 + + 不可达 —— Service / worker 拉不到投影 + + + 漂移从哪来(四类) + + Service 重启 + Redis 未持久化丢配置、回落缺省 + + 绕过治理直改 + 有人直接改了 Redis / Nacos + + 激活部分失败 + 某次激活没补偿干净、留半生效 + + 机器遗留 env + env 压过了本该生效的激活值 + 篡改 → 检出 → 一键重推 → 收敛(闭环) + + 篡改 / 漂移发生 + 绕过治理或 env 覆盖 + + 对账检出 DRIFT + 逐项列出差异旋钮 + + 一键重推 + 重放激活把投影拉回激活版 + + 收敛回激活版 + 投影 = 权威、IN_SYNC + + + + + 对账在防线里的位置 + 对账是「配置中心为权威、Service 与 worker 为投影」这个定位 + 的兜底闸,但不是失败的第一道防线 —— 第一道是激活失败时 + 的即时补偿(见图 2);对账兜的是补偿没覆盖到的漂移。 + 一键重推 = 重放激活,幂等,可反复执行到收敛。 + + 当前盲区(诚实标 · 阶段四补) + 机器上遗留 env 覆盖压过激活值这类漂移,从 game-cloud 侧 + 看不见(env 只活在 worker 进程内),当前对账探不到。 + → 挂阶段四观测:worker 暴露一个 effective 配置端点, + 把真正生效值连同来源吐出来供对账。 + 图例: + + IN_SYNC / 收敛 + + DRIFT / 篡改 + + 不可达 + + 阶段四观测补(盲区) + + 可观测 + + 可靠 + 对账 = 可观测 · 一键重推 = 可靠 + 读这张图抓三点:① 权威是当前激活版、Service 与 worker 只是它的投影,对账拉投影比对权威、判三态; + ② Nacos publish→read 最终一致,对账读必须带 8s 容忍窗,别把传播延迟误判成漂移;③ env 覆盖的漂移当前探不到,是诚实标的盲区,由阶段四 worker effective 端点补齐。 + 映射：本档 §3.6 配置漂移检测 · §8 执行终局③ · tech-decisions §14③ ｜ 状态：现(a8dd5e50 · 8s 窗)+ 建(阶段四 env 覆盖对账)｜ 设计变动须同步本图 +