28 — AI 插件分层重构:执行进度与对照基线¶
配套 26 — AI 插件分层(目标架构)与 27 — 现状行为冻结清单(不变量与测试缺口)。
本文是长期维护的执行记录:已完成内容、当前状态、遗留问题、下一步计划。 每次提交前更新,作为"改动是否仍在既定轨道上"的唯一对照。
工作分支:
refactor/ai-layer-boundaries(主干迁移)→fix/ai-behavior-backlog(行为修正、包边界收口与标记订正)。 硬约束:只换实现写法,不改可观测行为;每步以全量测试回归;提交粒度 = 一个工作流。
一、对照基线(重构前的测试快照)¶
在 master(提交 5d5281f)上执行:
go test ./builtin/ai/... -count=1
go test ./builtin/ai/... -count=1 -v
| 指标 | 数值 |
|---|---|
| 结果 | ok |
| 通过用例 | 526 |
| 失败用例 | 0 |
| 跳过用例 | 1(TestRetrievalContractLive,需 REMILIA_EMBED_TEST_URL) |
| 包耗时 | 约 10–15s(冷跑 ≈ 28s) |
⚠️ 基线是回归标准:任何一次提交后,上述数字与结果都不得劣化。 若某次改动导致用例数变化,必须在本文记录原因(新增用例属预期增量)。
二、工作流与状态¶
状态图例:✅ 完成 · 🚧 进行中 · ⏳ 未开始
| # | 工作流(对应 26 迁移顺序) | 目标 | 状态 |
|---|---|---|---|
| 1 | 能力端口(Capability) | 消除 toolSource → *Plugin,工具只依赖最小端口 |
✅ |
| 2 | 动作描述(Action) | ActionSpec + ActionPolicy + SelectionClass |
✅ |
| 3 | 调用器(Invoker) | FuncInvoker / CommandInvoker / SkillInvoker |
✅ |
| 4a | 结果收敛(Result) | typed Err 退役 isToolErrorResult 字符串判定 |
✅ 已由 C1 交付(见第十五节) |
| 4b | 输出捕获退役评估 | captureSender 依赖 vevent/engine;评估完成:附件在回合级捕获,整段退役不可行 |
✅ 已裁决:不退役(见 L6) |
| 5 | 检索骨架(Retrieval) | RetrievalCore:三个消费者共享分词/向量获取/排序/截断骨架 |
✅ |
| 6 | 上下文管线(Context) | Provider + Builder(未引入 Fragment/Snapshot 类型,见第二十一节) | ✅ |
| 7 | 选择与决策(Selection + Decision) | Candidate Discovery / Retrieval / Selection / Stability + needAction gate |
✅(闸门已收紧:纯社交判否,need_action_gate 可回退) |
| 8 | 代理状态(Agent State) | Plan / Todo / Reminder / PendingImage / Interrupt 的逻辑归属与持久化分离 | ✅ |
| 9 | Jev | 二级决策器(仅处理规则无法判定的歧义决策) | ⏳ 按需(真实需求出现再做) |
| F | 冻结用例(27 §H) | 现状契约的可执行断言 | ✅ 20/20(17 契约 + 3 负向) |
三、已完成:能力端口(Capability)¶
提交:refactor(ai): 工具能力端口化,消除工具上下文对插件实例的反向依赖
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/capability.go(新增) |
定义 memoryPort / todoPort / reminderPort / reminderSchedulerPort 四个最小端口与请求级 capabilitySet;组合根 (*Plugin).toolCapabilities();withCapabilities / capabilitiesFromContext |
builtin/ai/toolctx.go |
toolSource 移除 p *Plugin 字段,只保留身份与平台发送器 |
builtin/ai/execute.go |
executeTool 注入 p.toolCapabilities() |
builtin/ai/memorytool.go |
三个工具改依赖 caps.Memory |
builtin/ai/todotool.go |
四个工具改依赖 caps.Todos |
builtin/ai/remindtool.go |
set_reminder 依赖 caps.Scheduler,list/cancel 依赖 caps.Reminders |
builtin/ai/testutil_test.go |
新增 toolCtxForTest 辅助(装配身份 + 能力端口) |
builtin/ai/capability_test.go(新增) |
端口装配与 nil 安全回归测试 |
| 三个工具测试文件 | 上下文构造改为 toolCtxForTest |
设计要点¶
- 端口是最小职责:只读/取消提醒(
reminderPort)与创建提醒(reminderSchedulerPort)刻意分开, 因为创建需要捕获平台发送器。 - 组合根隔离:
pluginReminderScheduler是唯一仍持有*Plugin的适配器, 它位于装配边界,工具侧完全看不到插件实例。 - nil 安全:
toolCapabilities()只在具体管理器非 nil 时赋值端口, 避免"类型化 nil 指针 → 非 nil 接口"导致工具降级分支失效(有专项测试守护)。
验证¶
go build ./builtin/ai/...、go vet ./builtin/ai/...通过。go test ./builtin/ai/... -count=1→ok,无失败。- 新增
TestToolCapabilitiesNilSafety/TestToolCapabilitiesComposition/TestCapabilitiesContextRoundTrip通过。
行为影响¶
无。工具的错误文案、降级条件、返回值与改动前逐字一致; 仅上下文中的能力获取方式由"插件实例"改为"注入端口"。
四、遗留问题¶
| # | 问题 | 状态 |
|---|---|---|
| L1 | loopToolSender(sendtool.go)仍持有 *Plugin |
可接受:它已在窄接口 ToolSender 之后,属装配层 |
| L2 | 27 的 §H 冻结用例 | 已完成:20/20 全部落地(17 契约 + 3 负向,见第十四节与第二十一节) |
| L3 | ActionSpec 命名需与 platform.Capabilities / plugin.TryService 区隔 |
✅ 已裁决:定名 ActionSpec(工作流 2,见第十三节) |
| L4 | 结果收敛(4a)会改变"命令/Skill 正常输出恰好以 错误: 开头"的归类 |
✅ 已由 C1 交付(见第十五节) |
| L5 | 审批被拒文案"工具已被用户拒绝执行"当前不算失败(无 错误: 前缀) |
属既有行为,保持不动 |
| L6 | 附件在回合级而非工具级捕获,ActionResult 暂不含 Attachments |
记录:4b 的退役范围因此收窄 |
| L7 | builtin/knowledgebase/retrieve.go 自行实现 tokenize / tokenOverlap / tokenJaccard(已复用 ai.CosineSimilarity) |
✅ 已实施:导出 ai.TokenizeText / TokenOverlap / TokenJaccard 并删除本地实现(见第二十节) |
| L8 | needAction 闸门恒为真(不抑制可选动作) |
✅ 已实施(见修订记录 v26):纯社交寒暄判否、进行中计划判真,纯算法下沉 decision.NeedAction;“纯知识问答”无法本地判别,不纳入判定 |
已裁决事项¶
- ~~Q1~~(已裁决):保留兼容兜底,保持现有可观测行为。
退役
错误:前缀判定不作为迁移的一部分,转入"行为修正待办"。 - ~~Q2~~(已解决):
ActionSpec/ActionPolicy已引入,并以选择、执行闸门、 协议序列化为真实消费者,符合不变量 9。
四之二、行为修正待办(与迁移分离)¶
原则:不把"架构收敛"和"行为修正"混在一起。 迁移只换写法; 行为修正单列,等迁移完成后再作为明确变更实施。这样回归出现差异时, 一定是迁移实现的问题,而不是"顺便改了一个旧行为"。
| # | 待修正行为 | 现状(本次保持不变) | 期望(后续实施) | 决策 |
|---|---|---|---|---|
| C1 | 失败判定依赖 错误: 字符串前缀 |
isToolErrorResult 按前缀判定;命令/Skill 正常输出若以 错误: 开头会被判为失败;审批被拒文案不算失败 |
改用 ActionResult.Err 类型判定 |
✅ 已实施(见第十五节) |
| C2 | 空运行时上下文节的处理不对称 | include_runtime_context=true 且 context_fields 排除全部字段时:非预算路径输出"只有标题的空节";预算路径在装入其它非空节时丢弃该节 |
两条路径统一为不输出空节 | ✅ 已实施(见第十六节) |
| C3 | 历史检索同分排序无确定次序 | 历史消息检索的两次排序都只按分数降序(同分不设次序);工具选择与记忆检索同分时分别按工具名、事实文本升序 | 统一为确定性次序 | ✅ 已实施(见第十七节) |
| C4 | 群聊窗口的开关在两条路径上不一致 | context_group_messages=0 表示关闭:非预算路径据此关闭;预算路径不受该开关约束,按默认 10 条纳入 |
两路径统一遵循同一开关 | ✅ 已实施(见第十八节) |
| C5 | send_to 的审批门被判定两次 |
execOneTool 先按审批模式判定,再把结果注入 loopToolSender.sendToAllowed,SendTo 内再次判定(防嵌套 Skill 绕过) |
收敛为单一闸门(26 迁移表目标) | ✅ 已实施(见第十九节,授权单一来源、行为保持) |
两项均不阻塞迁移:C1 不实现(保持前缀判定);C2 在上下文管线 Provider 化时 逐字保留差异(含"只有标题的空节")。 C3 迁移期曾由
rankByScore(..., nil)显式承接,现已按第十七节统一为确定性次序。C5 已按"授权单一来源、行为保持"落定(见第十九节); L7 已按"导出
ai检索原语"落定(见第二十节)。行为修正待办 C1–C5 与 L7 全部完成。
五、下一步¶
- 工作流 8(代理状态):Plan / Todo / Reminder / PendingImage / Interrupt 的逻辑归属, 与持久化 schema 分离(逻辑归属≠持久化 schema)。
- 逐步补 27 §H 余下冻结用例(B1/B2 来源解析顺序与命令占位串)。
- 迁移完成后再统一评估行为修正待办 C1–C5(错误前缀判定、空节、同分次序、
群聊开关、
send_to双重审批)与 L8(收紧needAction)。
工作流推进顺序(已确认):检索骨架 → 上下文管线 → 选择与决策 → 代理状态, 后者消费前者,依赖关系最干净。
六、已完成:调用器(Invoker)¶
提交:refactor(ai): 拆分动作调用器,三种执行语义各自承载
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/invoker.go(新增) |
ActionResult{Text, Err};invoker 接口;funcInvoker / skillInvoker / commandInvoker;toolFailureText |
builtin/ai/execute.go |
executeTool 改为"解析来源 + 施加闸门",执行委托给对应调用器;移除行内错误格式化 |
builtin/ai/invoker_test.go(新增) |
三类调用器的成功/失败/超时文案与回退语义回归测试 |
设计要点¶
- 三种语义各自承载:普通动作真执行、命令走合成事件、Skill 启动子代理循环,
不再由同一个
Execute字段假装一致。 - 解析与执行分离:来源解析顺序(Skill(owner) → Skill(system) → real command → Execute)
与权限闸门仍留在
executeTool,调用器只负责"调用并产出结果"。 - 串行化不内移:真实命令路径的
realCmdMu加锁仍在调用方,避免调用器承担并发职责。 ActionResult.Err只表示失败语义:底层错误链已格式化进Text,不额外暴露。
行为影响¶
无。失败/超时/权限/未找到的文案与改动前逐字一致;RecordToolCall 的调用位置与次数不变;
真实命令路径"捕获为空则回退"的语义不变。
验证¶
go build/go vet通过;go test ./builtin/ai/... -count=1→ok。- 新增 6 个调用器用例通过。
七、已完成:动作描述(Action)¶
提交:refactor(ai): 引入动作描述与策略,拆分"类别"与"必保"双重语义
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/action.go(新增) |
SelectionClass(Optional/Baseline/Mandatory);ActionSpec;ActionPolicy;actionSpecOf / actionPolicyOf / selectionClassOf;keepsWhenNoAction |
builtin/ai/select.go |
相关度打分改用动作描述;必保判定改用保留级别 |
builtin/ai/execute.go |
工具级权限校验改用动作策略 |
builtin/ai/process.go |
执行前权限预检、AlwaysRequireApproval 判定改用动作策略 |
builtin/ai/tool.go |
OpenAI / Anthropic 协议序列化改用动作描述 |
builtin/ai/action_test.go(新增) |
映射等价性、无损派生、序列化消费者、内置规划工具保留级别 |
设计要点¶
- 拆开双重语义:类别(
ActionSpec.Categories)回答"这是什么"; 保留级别(ActionPolicy.Selection)回答"该不该留下"。 "空类别视为通用"只由selectionClassOf定义一次,不再散落在选择逻辑里。 - 无新存储、纯派生:
Action由Tool保真派生,注册表仍存Tool; 等消费者稳定后再迁移存储(新抽象只增不减,可独立回滚)。 - 保留级别三分:
Optional/Baseline/Mandatory。Baseline与Mandatory在"本轮无需主动动作"时都必须保留—— 这为后续needAction闸门预留了正确语义(对应 26 §3.10)。
行为影响¶
无。保留级别映射与旧 isGeneralTool 逐一等价(有等价性断言守护);
权限、审批、协议序列化取值逐字段不变。
验证¶
go build/go vet通过;go test ./builtin/ai/... -count=1→ok。- 新增 6 个用例通过。
八、已完成:冻结用例(27 §H 第一批)¶
提交:test(ai): 补齐现状行为冻结用例(选择语义/指标/权重/持久化/前缀边界)
新增 builtin/ai/freeze_test.go,把 27 §H 中缺失且高价值的契约变成可执行断言:
| 用例 | 覆盖 |
|---|---|
TestSelectBypassWhenToolsWithinMax |
A1 短路阈值:不超上限且无 embedding 时原样返回 |
TestMandatoryMayExceedSelectMax |
A2/A9 默认保留级别不受 ToolSelectMax 约束 |
TestBudgetDoesNotDropMandatory |
A7 预算不回收默认保留级别 |
TestMetricsDescriptorsRegistered |
G2 指标族名与标签集合只增不改 |
TestToolSelectMaxConfigCompat |
G1 旧配置键语义 |
TestRetrievalWeightsFrozen |
C1 权重与门槛常量 |
TestSessionPersistenceSchemaSnapshot |
G3/G4 持久化字段集合、且当前无版本字段(round-trip 见 TestAgentStatePersistenceRoundTrip) |
TestToolSetGenerationStableOnRepeatedCandidate |
N5/A13 集合代数稳定 |
TestToolSetChangeCreatesDistinctToolsBytes |
D4/N4 前缀字节边界(不断言 Provider 缓存) |
已由既有测试覆盖、无需重复的项¶
| 契约 | 既有用例 |
|---|---|
| A3 空类别视为通用 | TestIsGeneralTool、TestSelectionClassMapping |
| A6 embedding 结果缓存 | TestSelectToolsForTurnCacheHit |
| A10/A12 单调并集、回访保持、字节稳定 | TestToolSetStickyGrowsMonotonicallyAndKeepsOnRevisit、TestToolSetStickyIsByteStableAcrossRepeatTurns |
| A11/N2 可用集收缩立即生效 | TestToolSetStickyNeverExceedsAvailable |
| A12 空闲衰减 | TestToolSetStickyDecaysIdleFillers |
| D1–D3 稳定前缀与动态上下文后置 | TestPromptPrefixStableAcrossTurns、TestInjectDynamicContextAttachesToLastUserMessage |
| G3 持久化 round-trip | TestSessionToRecordRoundTrip、TestSessionRecordJSONRoundTrip |
当时仍待补的条目(已全部交付,保留作历史记录)¶
下表是本节当时的缺口清单:
N3、B5、B1/B2均已在第十四节随冻结用例补齐(§H 20/20)交付,不再是未完成项。
| 契约 | 当时的阻塞原因 | 交付位置 |
|---|---|---|
N3 NeedAction=false 保留基线动作 |
needAction 闸门属选择与决策工作流 |
TestDecideTurnActionsRetainsStickyWhenNoAction(第十四节) |
| B5 工具错误前缀 | 与 Q1 结果收敛同时处理 | TestToolResultFailureIsTyped(第十五节) |
| B1/B2 来源解析顺序、命令占位串 | 与调用器工作流的补充用例一起 | TestExecuteToolResolutionOrder / TestCommandToolExecuteIsPlaceholder(第十四节) |
对照基线更新¶
go test ./builtin/ai/... -count=1 -v → 550 通过 / 0 失败 / 1 跳过(基线 526 + 新增 24)。
九、已完成:检索骨架(Retrieval)¶
提交:refactor(ai): 抽取检索骨架,三个消费者共用分词/向量/排序原语
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/retrieval.go(新增) |
scoreEmbedW;tokenizeText / tokenOverlap / jaccardSimilarity(自 select.go 迁入);semanticCosine;retrievalScore;semanticFallbackLog + acquireSemanticVectors;rankByScore;topK |
builtin/ai/select.go |
移除已迁出的分词/重叠度原语;打分改用 semanticCosine + retrievalScore;向量获取改用 acquireSemanticVectors;排序改用 rankByScore |
builtin/ai/rag.go |
两次排序与 Top-K 改用 rankByScore / topK;语义项改用 retrievalScore;embedRAGTexts 委托 acquireSemanticVectors |
builtin/ai/memory.go |
匿名打分结构收敛为 memoryScored;语义项改用 retrievalScore;排序与截断改用 rankByScore / topK;向量获取改用 acquireSemanticVectors |
builtin/ai/retrieval_test.go(新增) |
骨架契约用例 9 例 |
设计要点¶
- 共享算法骨架,不共享领域模型:
retrieval.go只提供 tokenize / 重叠度 / 语义权重 / 向量获取 / 排序 / 截断原语;候选来源、入选门槛与筛选策略仍留在 各自消费者中(工具:关键词+热用门槛与预算;历史:ragKeywordMinScore预筛与 语义兜底;记忆:signal <= 0门槛与出现次数加成)。 - 排序语义显式化:
rankByScore的tieBreak参数把"同分如何定序"变成调用点 的显式选择。工具/记忆传确定性 tie-break;历史检索传nil,保持既有的 "同分不设次序"(记录为 C3,不在迁移中修正)。 - 降级路径集中一处:
acquireSemanticVectors统一"文本批量嵌入 → 查询嵌入"的 顺序与失败降级(文本失败返回nil,nil;查询失败保留已取到的文本向量)。 三个消费者的降级日志文案逐字传入,日志输出不变。 - 按需嵌入语义不变:调用点仍先判
Enabled()再构建候选文本切片, 避免 embedding 关闭时产生无谓分配(性能不倒退)。
行为影响¶
无。要点与验证方式:
- 数值逐位一致:语义项由
keyword + cosine×scoreEmbedW组合;无语义信号时retrievalScore(x, 0) == x精确成立(有专项断言)。 - 非稳定排序保留:
rankByScore(..., nil)与旧sort.Slice纯分数比较器 在同一输入上产生相同序列(有专项断言);历史检索仍不做 tie-break。 - 向量获取语义一致:
Enabled()判定、文本→查询的调用顺序、缓存复用次数、 失败时的返回值形状均不变(以"embedding 调用次数"断言,见 A6 冻结要求)。 - 超时不变:历史/记忆仍为 10s;工具选择仍不设内层超时(直接用请求上下文)。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 559 通过 / 0 失败 / 1 跳过 (上一基线 550 + 新增 9);包耗时 ~10s,与基线持平。
十、已完成:上下文管线(Context)¶
提交:refactor(ai): 动态上下文 Provider 化,节序/预算装配收敛到单一管线
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/context_pipeline.go(新增) |
dynamicContextSource(节点来源/Provider)、dynamicContextSources(节序与参与条件声明)、budgetParticipates / fit / render、buildDynamicContext、buildDynamicContextBudgeted |
builtin/ai/handler.go |
移除内联的 buildDynamicContext(节序、标题、开关散落在函数体里) |
builtin/ai/budget.go |
移除内联的 buildDynamicContextBudgeted;文件职责收窄为预算原语(estimateTextTokens / fitSection / promptReserveTokens) |
builtin/ai/context_pipeline_test.go(新增) |
节序、空节不对称(C2)、群聊开关不对称(C4)契约用例 |
设计要点¶
- Provider 只管"我能提供什么":每个节声明标题、参与条件、正文生成与注入上限;
节序、预算编排、标题拼接、最终串联由 Builder 统一负责。
原先的开关与标题在两条路径各写一遍,现在只在
dynamicContextSources声明一次。 - 正文惰性求值:节未参与时不求值——群聊查询、记忆检索、历史检索都不会发生,
与改动前一致。群聊的"机器人回复去重集合"用
sync.OnceValue按需构建、只构建一次 (预算缩减最多重建一次正文,去重集合在重建间复用)。 - 预算策略显式声明:
shrink=true走fitSection按比例缩量(按上限构建一次, 超预算按"估算用量/预算"缩量重建一次,仍超则按预算截断,见Source.KeepTail) (群聊/记忆/历史);shrink=false走单次估测(运行时上下文)。 - 既有不对称显式承接:
budgetEnabled只用于表达"预算路径与配置路径参与条件不同" 的群聊窗口(C4);运行时上下文的空节差异由emitWhenEmpty+ 预算策略共同表达(C2)。
行为影响¶
无。除全量测试外,另用差分对拍验证:把改动前的两个装配函数原样复制一份, 在「运行时开关 × 字段白名单 × 群聊条数 × RAG 条数 × 记忆上限 × 是否含历史 × 是否含记忆 × 预算窗口」共 3456 组配置下逐字节比较,输出完全一致 (对拍脚本为一次性验证,未进入提交)。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 562 通过 / 0 失败 / 1 跳过 (上一基线 559 + 新增 3);包耗时 ~10s,与基线持平。
新发现并记录¶
- C4:
context_group_messages=0在预算路径上不生效(按默认 10 条纳入), 与文档"0 = 关闭"不一致。属既有行为,本次保留并加测试锁定。 - C2 精确化:预算路径整体为空时会回退到配置路径,此时空运行时节仍会出现; 即"预算路径丢弃空节"只在装入其它非空节时可见。
十一、已完成:选择与决策(Selection + Decision)¶
提交:refactor(ai): 回合动作决策分层,候选发现/选择/稳定与无需动作闸门收敛
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/decision.go(新增) |
actionCandidates(候选发现:注册表 + 用户 Skill → 群策略 → RBAC);decideTurnActions(决策入口);retainedActions / retainedAction(无需主动动作时的保留集);needAction(闸门) |
builtin/ai/process.go |
工具筛选三处内联逻辑收敛为一次 decideTurnActions(ctx, session, needAction) |
builtin/ai/select.go |
必保判定改用 retainedAction,与保留集共用同一判据 |
builtin/ai/decision_test.go(新增) |
闸门保守性、保留集、N3 稳定集合不清空、过滤语义(E4)、候选来源 |
设计要点¶
- 决策链单一入口:候选发现 → 选择(
selectToolsForTurn)→ 稳定策略 (stabilizeToolSet)。群策略与 RBAC 的过滤条件、日志文案与顺序均未改变。 - 保留判据收敛一处:
retainedAction(默认保留级别 或 会话已用)同时服务 选择路径的必保集与闸门关闭时的保留集,避免两处语义漂移。 - 闸门只抑制"可选挑选":
needAction=false时保留默认保留级别、会话已用与 稳定集合(sticky),不挑选可选动作、不读写选择缓存——缓存读写一并跳过, 避免把收敛后的集合缓存成后续回合的复用结果。 - 闸门当前保守恒真:
needAction()返回 true,即不抑制,保持既有工具集行为。 收紧判定属行为变更,记入 L8。
行为影响¶
无。生产路径上 needAction() 恒为真,decideTurnActions 等价于原来的
「候选发现 + selectToolsForTurn」;retainedAction 与旧内联判据逐一等价。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 567 通过 / 0 失败 / 1 跳过 (上一基线 562 + 新增 5);包耗时 ~10s,与基线持平。
新记录¶
- C5:
send_to审批门被判定两次(execOneTool判定 +sendToAllowed运行时 再判定)。收敛为单一闸门会改变审批语义,属行为变更,本次保留。
十二、已完成:代理状态(Agent State)¶
提交:refactor(ai): 代理状态归属成表,持久化边界与内存态以守卫用例钉死
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/agentstate.go(新增) |
agentStateClass(落库 / 会话内存 / 进程级内存)与 agentStateInventory() 归属表;agentStateInfrastructure() 声明并发原语豁免 |
builtin/ai/agentstate_test.go(新增) |
归属表与结构体字段的对应关系、分类与承载形态一致性、落库并集 = 持久化 schema、Session 字段全覆盖、非落库字段不进入 JSON、持久化往返语义 |
设计要点¶
- 逻辑归属 ≠ 持久化 schema:归属表只回答"这项状态是什么、跨重启是否保留",
不改变任何存储。落库仍由
toRecord/toSession与json:"-"标签共同决定。 - 归属表即持久化边界的事实来源:落库类目的
Record并集必须恰为sessionRecord的字段集合;新增列却忘记登记会被测试拦下(G3/G4)。 - 会话内存态不得序列化:非落库的
Session字段必须是未导出或显式json:"-"。 - 豁免名单只放并发原语:
mu/turnMu由agentStateInfrastructure()豁免(该声明现已与守卫用例同址于agentstate_test.go,见 29 §十), 守卫用例校验其类型必须是sync.Mutex,防止借豁免夹带真实状态。 - 新增状态必被登记:
Session上每个字段要么在归属表里,要么在豁免名单里; 临时加一个未登记字段会让用例立刻失败(已用临时字段验证过守卫有效)。
行为影响¶
无。归属表是纯声明,不参与运行时;json:"-" 标签、sessionRecord 字段集合与
toRecord / toSession 的序列化语义均未改动。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 574 通过 / 0 失败 / 1 跳过 (上一基线 567 + 新增 7);包耗时 ~10s,与基线持平。- G3/G4(GAP-10)至此完全覆盖:字段集合快照 +
toRecord → toSession往返语义。
边界裁决¶
本工作流只修边界,不引入运行时抽象:归属表没有一个"必须由生产代码消费"的
自然消费者(Session 已为每项状态提供访问器),因此不为了架构对称再造一层包装。
这与"没有真实消费者就不要为抽象而抽象"是同一原则。
十三、收口阶段:范围与裁决¶
主干迁移(工作流 1–8)已完成,此后不再扩大架构改动。收口只做两件事:
- 补完冻结用例:
F由 9/17 补到 17/17(27 §H 余下条目),随后全量回归; - 确认迁移无意外变化:回归数字与文案、排序、字节口径均与基线一致。
遗留项裁决¶
| # | 结论 | 说明 |
|---|---|---|
| L1 | 保持现状 | loopToolSender 已在窄接口 ToolSender 之后,属装配层;与"核心能力依赖整个 Plugin"是两回事 |
| L2 | 本阶段处理 | 补完 §H 余下条目 |
| L3 | 定名 ActionSpec |
与 platform.Capabilities(平台能力集合)、plugin.TryService(插件服务)语义层次不同,无需为避嫌改名 |
| L4 | ✅ 已由 C1 交付 | isToolErrorResult 已退役,失败判定改用 ActionResult.Err(见第十五节) |
| L5 | 保持现状 | 审批被拒文案不算失败,属既有行为 |
| L6 | 保持现状 | 附件为回合级捕获,ActionResult 不承载附件 |
| L7 | 后续候选 | 跨包检索 API 清理,独立课题(已由第二十节落地) |
| L8 | 保持现状(后由 v26 收紧) | needAction 恒真是兼容实现,收紧属独立行为变更 |
行为修正待办不变¶
行为修正:当时决定不在收口阶段实施(后续已逐个完成)¶
C1–C5 当时一律不在收口阶段实施:它们是五个彼此独立的行为变更,逐个开独立变更
(建议按影响面 C1 → C2/C3 → C4 → C5),避免与迁移回归混在一起难以归因。
后续状态:该安排已执行完毕——C1 至 C5 分别在第十五、十六、十七、十八、十九节逐项实施,行为修正待办清零。本节保留作历史记录。
契约表述勘误(仅文档,不改行为)¶
- A13 / §H-6 原文写作"同一组工具以不同输入顺序给出 → 输出名称升序一致"。
实际冻结语义是:输出顺序跟随输入顺序(
selectToolsForTurn按输入下标排序), 跨请求字节稳定由ToolRegistry.List()的名称升序保证。补测试时按实际语义冻结。
十四、已完成:冻结用例补全(收口)¶
提交:test(ai): 补齐选择与稳定 / 执行语义 / 前缀缓存冻结用例
把 27 §H 余下条目补齐到 17/17(§H 含负向不变量用例共 20 条,口径见第二十一节); 全部为新增测试,本轮收口生产代码零改动。
| §H | 用例 | 覆盖 |
|---|---|---|
| 3 | TestEmptyCategoryIsMandatory |
A3/GAP-4 空 Categories 与显式 general 同判必保 |
| 5 | TestEmbeddingCacheNoReembed |
A6 同 query 不重复嵌入(按调用次数断言) |
| 6 | TestToolSetDeterministicOrdering |
A13/N4 注册表名称升序、输出跟随输入顺序、字节稳定 |
| 7 | TestCommandToolExecuteIsPlaceholder |
B2 命令工具占位执行,无副作用 |
| 8 | TestExecuteToolResolutionOrder |
B1 owner Skill > 系统 Skill > 真实命令 > 自身 Execute |
| 9 | TestCaptureSenderAttachmentsMerged |
B6/GAP-8 正文与附件都不丢,附件合并而非覆盖 |
| 10 | TestToolResultErrorPrefix |
B5 错误前缀判定与正常结果判假 |
| 11 | TestSkillLoopNonStreaming |
B8/F6 非流式循环 + 可见工具构成 |
| 12 | TestDynamicContextChangeKeepsPrefix |
D3/N1/N6/GAP-5 动态内容不进稳定前缀 |
| 13 | TestToolSetChangeCreatesDistinctPrefix |
D4/GAP-6 ToolSet 变化产生新前缀边界 |
| 17 | TestSessionPersistenceSchemaSnapshot |
G3/G4/GAP-10 字段集合 + 无版本字段(round-trip 见 TestAgentStatePersistenceRoundTrip) |
测试侧仅新增一个夹具 fakeEventProcessor(冒充引擎事件处理器,模拟真实命令
路径),其余复用既有 mockProvider / toolSet / toolsRequestBytes。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 584 通过 / 0 失败 / 1 跳过。- 收口阶段的提交只包含
*_test.go与docs/,生产代码未改动。
结论¶
主干迁移(工作流 1–8)与冻结用例(17/17)均已收口,builtin/ai 的分层重构到此为止。
C1–C5 与 L7 作为独立变更另行开展;L1 / L5 / L6 / L8 保持现状。
十五、行为修正 C1:类型化失败判定¶
提交:fix(ai): 失败判定改用类型化错误,退役结果文本前缀推断
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/execute.go |
新增 executeToolResult(返回 ActionResult,携带失败语义);executeTool 退化为文本视图包装 |
builtin/ai/process.go |
toolExecResult 增加 err;重试预算、反思引导、计划展示、调用追踪全部改用 err != nil 判定 |
builtin/ai/retry.go |
删除 isToolErrorResult;文件头说明改为类型化判定 |
builtin/ai/retry_test.go、builtin/ai/freeze_execute_test.go |
前缀断言替换为类型化断言 |
语义边界(刻意区分)¶
- 调用本身失败(
Err非空):工具不存在、权限不足、回调返回错误、技能执行失败、执行超时。 - 调用成功但正文像错误(
Err为空):正文逐字回填,不再计入失败预算。 - 审批被拒(
Err为空):与既有行为一致——用户已拒绝的动作不需要模型"重试"。
需要留意的连带影响¶
create_plan / update_plan_step 的校验类文案(如"错误: 计划至少需要 2 个步骤")
历来以 nil error 正常返回,此前仅因文本前缀被判为失败;按类型化语义它们现在
不再消耗重试预算(模型仍能看到文案并在下一轮自我纠正)。若希望这类校验继续
计入失败,应另开变更让工具返回真实错误,而不是恢复前缀推断。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 584 通过 / 0 失败 / 1 跳过。- 冻结清单 §H-10(
TestToolResultErrorPrefix)已被本变更取代,替换为TestToolResultFailureIsTyped;其余 16 项不受影响(原用例断言的前缀文案 仍由新用例逐字冻结)。
十六、行为修正 C2:空运行时上下文节¶
提交:fix(ai): 空运行时上下文章节两条路径统一不输出
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/context_pipeline.go |
退役 emitWhenEmpty 字段;空正文一律跳过,两路径一致 |
builtin/ai/context_pipeline_test.go |
TestRuntimeSectionEmptinessDiffersBetweenPaths → TestRuntimeSectionEmptyDroppedOnBothPaths,断言两路径都不产生只有标题的空节 |
语义边界¶
- 仅统一空正文的处理:
include_runtime_context=true且context_fields排除全部字段时,配置路径与预算路径都不再输出"只有标题的空节"。 - 群聊窗口开关不对称(C4)继续保留:本次 Provider 化抽取只收敛空节语义,
预算路径仍以
budgetEnabled承接既有不对称,留待 C4 单独处理。
验证¶
go test ./builtin/ai/... -count=1 -v→ 584 通过 / 0 失败 / 1 跳过(用例数不变,仅改名)。
十七、行为修正 C3:历史检索同分确定性¶
提交:fix(ai): 历史检索同分采用确定性次序
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/rag.go |
新增 ragHitTieBreak;两处 rankByScore 由 nil 改为该次序 |
builtin/ai/rag_test.go |
新增 TestRAGHitTieBreakNewerFirst(纯排序)与 TestBuildRAGContextTieBreakNewerFirst(完整路径) |
语义边界¶
- 仅在分数完全相等时生效,分数不同者次序不变。
- 次序规则:较新的消息优先;同一时刻按
EventID升序;再按内容升序兜底。 - 与工具选择(工具名升序)、记忆检索(事实文本升序)保持"同分确定性"的一致性, 具体排序键仍各自贴合领域(本次不改动工具/记忆)。
验证¶
go test ./builtin/ai/... -count=1 -v→ 586 通过 / 0 失败 / 1 跳过(新增 2 个用例)。
十八、行为修正 C4:群聊窗口开关两路径统一¶
提交:fix(ai): 群聊窗口开关对两条上下文路径一致
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/context_pipeline.go |
退役 budgetEnabled 字段与 budgetParticipates,两路径共用 participates;群聊节参与条件统一为 context_group_messages > 0 |
builtin/ai/context_pipeline_test.go |
TestGroupSectionGatingDiffersBetweenPaths → TestGroupSectionHonorsSwitchOnBothPaths(关闭/开启两态两路径一致) |
语义边界¶
context_group_messages = 0现在对预算路径同样表示"关闭":预算路径不再按 默认 10 条纳入群聊窗口。context_group_messages > 0时两条路径行为不变(均按该条数纳入,预算路径 可继续按预算缩减)。- 受影响的下游:预算路径关闭群聊后若其余节为空,预算装配返回空串并回退到 配置路径;由于配置路径同样关闭群聊,最终动态上下文为空——与"关闭"语义一致。
验证¶
go build ./...通过。go test ./builtin/ai/... -count=1 -v→ 586 通过 / 0 失败 / 1 跳过。
十九、行为修正 C5:审批门成为 SendTo 授权的唯一来源¶
提交:refactor(ai): 审批门收敛为 SendTo 授权的唯一来源
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/process.go |
新增 toolApprovalDecision 与 decideToolApproval:审批判定与 SendTo 授权同源;execOneTool 只消费该结论 |
builtin/ai/sendtool.go |
注释明确 sendToAllowed 由审批门一次性授予,SendTo 只消费、不重新推导 |
builtin/ai/approval_test.go |
新增 TestDecideToolApprovalSingleSource |
语义边界(行为保持)¶
- 授权判定只有一处:
decideToolApproval按生效审批模式判定、必要时发起审批, 并返回{allowed, rejectText, sendToGranted};execOneTool不再自行推导sendToAllowed。 - 可观测行为零变化:
sendToGranted与迁移前的needApproval取值等价 (拒绝路径提前返回),SendTo的拒绝文案、审批消息、发送结果全部逐字保持。 - 嵌套 Skill 防护保留:嵌套 Skill 内的工具调用不经
decideToolApproval, 拿到的是未授权 sender,仍无法绕过审批直接SendTo。
后续(见第二十三节):
decideToolApproval迁入decision.go并与 RBAC 预检合并为decideToolInvocation,本节描述的语义与文案全部保持。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai/通过。go test ./builtin/ai/... -count=1 -v→ 587 通过 / 0 失败 / 1 跳过。
二十、遗留项 L7:知识库复用 AI 检索原语¶
提交:refactor(knowledgebase): 复用 AI 插件导出的检索原语
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/retrieval.go |
导出 TokenizeText / TokenOverlap / TokenJaccard(薄封装包内 tokenizeText / tokenOverlap / jaccardSimilarity,与既有 CosineSimilarity 同风格) |
builtin/knowledgebase/retrieve.go |
删除本地 tokenize / tokenOverlap / tokenJaccard,改调 ai.*;移除 unicode、unicode/utf8 导入 |
builtin/ai/retrieval_test.go |
新增 TestExportedRetrievalPrimitives 冻结导出原语与包内骨架等价 |
builtin/knowledgebase/knowledgebase_test.go |
TestTokenize → TestTokenizeText,改断共享原语 |
语义边界(行为保持)¶
- 两份分词实现在 ASCII 单词切分、连续汉字二元组、孤立汉字单字、token 计数上等价; 本次只消除重复实现,不改变关键词兜底打分、去重阈值与排序结果。
- 未新增独立包:
knowledgebase本就依赖builtin/ai(复用ai.CosineSimilarity), 导出薄封装即可完成复用,符合"不因抽象而抽象"。 - 包内调用点仍走未导出的
tokenizeText等,导出面仅 3 个符号。
验证¶
go build ./...、go vet ./builtin/ai/... ./builtin/knowledgebase/...、gofmt -l通过。go test ./builtin/ai/... -count=1 -v→ 588 通过 / 0 失败 / 1 跳过。go test ./builtin/knowledgebase/... -count=1 -v→ 18 通过 / 0 失败 / 1 跳过。
二十一、遗留项登记(对照 26 目标,避免重复发现)¶
对 26 目标分层逐条核对后的已知未交付项(G-A 已交付,保留行以记录闭环)。均为知情延期或收窄交付, 不是回归;后续若要推进,各自开独立变更,不并入迁移。
| # | 26 目标 | 现状 | 为什么保留 | 后续动作 |
|---|---|---|---|---|
| G-A | memory_query 降级为 Retrieval / Context(26 §四映射表) |
✅ 已实施(见第二十二节):不再是模型可见动作,检索由上下文管线承担 | — | — |
| G-B | Policy 作为 Decision 子层统一评估(26 §3.3 / §四"评估在 Decision") | ✅ 已实施(见第二十三节):decideToolInvocation 统一 RBAC + 审批,执行路径只消费结论 |
— | — |
| G-C | 命令目录 / Skill 运行器抽成 Capability 端口(26 §四) | ✅ 已实施(见第二十四节):commandCatalogPort / skillRunnerPort,调用器不再依赖插件实例 |
— | — |
| G-D | Action 取代 Tool 成为内部存储,Execute 只存在于 Invoker(26 不变量 1/11) |
✅ 已实施(见第二十五节):注册表内部只存动作视图,管线(选择/稳定/序列化/策略)不见 Execute |
— | — |
| G-E | Context Provider → Fragment → Builder → Snapshot(26 §3.6) |
交付 Provider(dynamicContextSource)+ Builder;无 Fragment / Snapshot 类型 |
不变量 9:无消费者不为抽象而抽象;节间不需要独立寻址 | 出现"跨 Provider 片段级重排/去重"需求时再引入 |
另有两项已裁决保留的既有行为,不属本表:
captureSender未退役(L6,4b 范围收窄)、needAction恒真(L8;已由 v26 收紧为纯社交判否,可用need_action_gate=always回退)。
检索契约实测(关闭原验证盲区)¶
27 §十四 判据 4 要求"设置 REMILIA_EMBED_TEST_URL 后 embedding 契约测试全绿"。
已用本地 OpenAI 兼容 embedding 服务(Qwen3-Embedding-0.6B-Q8_0.gguf,1024 维)实测:
$env:REMILIA_EMBED_TEST_URL = "http://10.0.0.20:8080/v1"
$env:REMILIA_EMBED_TEST_MODEL = "Qwen3-Embedding-0.6B-Q8_0.gguf"
go test ./builtin/ai/ -run TestRetrievalContractLive -count=1 -v
| 检索 | 纯关键词 | +embedding(scoreEmbedW=2) |
|---|---|---|
| 工具选择 Top1 / R@5 / MRR | 54.2% / 66.7% / 0.607 | 91.7% / 100% / 0.958 |
| RAG 关键词预筛保留正确文档 | 2/6 | 语义兜底找回 4/4 |
| 记忆正确事实入 Top-3 | 0/2 | 2/2 |
- 断言"embedding 不劣于纯关键词"通过;权重扫描
w=0.5…3.0指标持平, 说明scoreEmbedW=2落在平台区,无需调整。 - 设置环境变量后全量基线为 589 通过 / 0 失败 / 0 跳过(原 SKIP 项转为通过)。
二十二、遗留项 G-A:memory_query 降级为检索¶
提交:fix(ai): 记忆检索降级为上下文注入,退役 memory_query 动作
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/memorytool.go |
移除 memory_query 动作(含 memoryQueryToolName、memoryToolMaxLimit、memoryToolLimit);memory_forget 的说明与文案改为引用注入的记忆条目 / /ai memory |
builtin/ai/memorytool_test.go |
TestMemoryTools_AddQueryForget → TestMemoryTools_AddForget;删除 TestMemoryToolLimit;新增 TestMemoryQueryIsRetrievalNotAction |
builtin/ai/capability.go |
memoryPort 注释同步(检索由上下文管线消费) |
可观测行为变化(本次是行为变更,非纯迁移)¶
- 工具集组成变了:模型可见工具不再包含
memory_query;长期记忆的general(Baseline) 必保项由 3 个减为 2 个,ToolSet 也随之变化——这是本次预期的行为变更。 - 检索能力由 Context 承担:
buildMemoryContextN每轮按最后一条用户消息检索 (用户记忆 + 群记忆,Top-N 注入)。用户显式问"你还记得…"时,该消息本身就是检索查询, 事实仍会进入模型视野(由TestMemoryQueryIsRetrievalNotAction冻结)。 - 失去的能力:模型不能再以自选查询词做一次针对性检索。若后续确需该能力, 应作为 Decision 触发的 Retrieval 请求重新设计(当前无消费者,不提前造,见不变量 9)。
memory_add/memory_forget的写入、删除与去重语义未变;/ai memory用户侧命令未变。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai通过。go test ./builtin/ai/... -count=1 -v(带REMILIA_EMBED_TEST_URL)→ 589 通过 / 0 失败 / 0 跳过。
二十三、遗留项 G-B:调用策略评估收敛到 Decision¶
提交:refactor(ai): 调用策略评估收敛到决策层
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/decision.go |
新增 toolInvocationDecision 与 decideToolInvocation(唯一评估点:RBAC → 审批);迁入 needsApproval / approvalModeFor;文件头说明决策同时回答"发给模型什么"与"这次调用是否放行" |
builtin/ai/process.go |
execOneTool 改为消费 decideToolInvocation 的结论(删除内联 RBAC 预检与 decideToolApproval / toolApprovalDecision / approvalModeFor);effectiveApprovalMode / effectiveApprovalTimeout 仍留在配置解析处 |
builtin/ai/approval.go |
移除 needsApproval(迁入决策层);审批交互本身(发起 / 解析 / 按钮 / 文本命令)原样保留 |
builtin/ai/decision_test.go |
迁入并冻结 TestNeedsApproval、TestApprovalModeFor;TestDecideToolApprovalSingleSource → TestDecideToolInvocationSingleSource 并新增"声明权限但无权"子用例 |
builtin/ai/approval_test.go |
移出策略评估类用例,只保留审批交互契约 |
语义边界(行为保持)¶
- 唯一评估点:RBAC 与审批在
decideToolInvocation内按既有顺序(先权限后审批) 判定,返回{allowed, rejectText, err, sendToGranted};执行路径不再自行推导策略。 - 拒绝语义分工不变:权限不足带
err(计入重试预算),审批被拒不带err(不消耗重试预算)——与迁移前逐字一致。 - SendTo 授权同源:
sendToGranted仍只由审批门放行时授予,SendTo只消费、 不重新推导(C5 结论保持);嵌套 Skill 内调用不经此处,仍拿不到授权。 - 纵深防御保留:
execute.go内的权限校验与 RBAC 预过滤未删除。 - 执行路径不认识业务策略:
execOneTool只做"计数 → 消费决策 → 执行 → 追踪"。
验证¶
go build ./...、go vet ./builtin/ai/...通过。go test ./builtin/ai/... -count=1 -v(带REMILIA_EMBED_TEST_URL)→ 589 通过 / 0 失败 / 0 跳过,与迁移前基线一致。
二十四、遗留项 G-C:命令目录 / Skill 运行器抽成能力端口¶
提交:refactor(ai): 命令目录与技能运行器抽成能力端口
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/invoker.go |
新增 commandCatalogPort / skillRunnerPort 两个最小端口与 pluginCommandCatalog / pluginSkillRunner 适配器;commandInvoker 由持 *Plugin 改为持端口,skillInvoker 的 run 函数字段改为端口 |
builtin/ai/execute.go |
在装配点构造两个适配器并注入调用器(与 capabilitySet 同一处装配) |
builtin/ai/invoker_test.go |
新增 stubSkillRunner 端口桩,技能调用器契约不再需要构造插件实例;命令调用器用例改用真实适配器 |
语义边界(行为保持)¶
- 端口只描述一件事:命令端口回答"这个动作名对应哪条真实命令、跑完说了什么", 技能端口回答"把这个 Skill 跑完并给出最终文本"。命令表、合成事件、平台同步器、 子代理 Prompt / 工具集 / 轮次仍全部留在装配侧。
- 回退语义不变:命令端口返回空文本仍表示"无对应真实命令",调用方照旧回退到 普通动作路径;串行化(syncer 非线程安全)仍由调用方加锁。
- 不进入
capabilitySet:这两个端口是执行路径的依赖,刻意不暴露给工具回调, 避免工具获得"跑命令 / 跑技能"的能力而扩大工具侧能力面。 - 失败文案逐字不变:技能失败文本、命令捕获文本、错误与
Err语义均未改动。
验证¶
go build ./...、go vet ./builtin/ai/...、gofmt -l builtin/ai通过。go test ./builtin/ai/... -count=1 -v(带REMILIA_EMBED_TEST_URL)→ 589 通过 / 0 失败 / 0 跳过,与迁移前基线一致。
二十五、遗留项 G-D:Action 取代 Tool 成为内部存储¶
提交:refactor(ai): 动作与执行载荷分离,注册表改存动作视图
改动范围¶
| 文件 | 改动 |
|---|---|
builtin/ai/action.go |
新增 Action(Spec + Policy)与保真派生 actionOf / actionsOf;文件头补"动作是什么"与"动作怎么执行"的类型边界说明 |
builtin/ai/tool.go |
ToolRegistry 内部由 map[string]Tool 改为 map[string]registeredAction(动作视图 + 执行载荷);新增 Action / Actions(管线视图),Get / List 保留为执行视图(registeredAction.tool() 逐字段还原);协议序列化改读 ActionSpec |
builtin/ai/select.go |
打分、token 估算、选择缓存与 selectToolsForTurn 改以 Action 为输入输出(日志文案逐字保留) |
builtin/ai/toolset.go |
稳定策略(stabilizeToolSet / mergeToolSet / 名称解析)改以 Action 为输入输出 |
builtin/ai/decision.go |
候选发现、保留判定、权限与审批评估均读 Action(reg.Action),needsApproval 改收 Action |
builtin/ai/execute.go、grouppolicy.go、embedding.go、provider.go、subcommand.go、process.go |
权限/群策略过滤、嵌入文本、ChatRequest.Tools 与单轮调用改以 Action 传递;buildUserSkillTools → userSkillActions(只产出描述与策略) |
| 测试文件 | action_test.go 新增 TestRegistryRoundTripsActionAndTool 冻结两种视图保真;其余用例同步改用动作视图 |
语义边界(行为保持)¶
- 注册表是唯一持有
Execute的地方:选择、稳定、协议序列化与策略评估读的都是 动作视图(描述 + 策略),执行载荷只在Get/List还原——管线在类型层面拿不到执行入口。 - 派生保真:
actionOf是actionSpecOf/actionPolicyOf的合成,registeredAction.tool()是其逆;"注册 →Get逐字段等于注册值"由新增用例冻结,投影丢字段即失败。 - 协议层零变化:
toOpenAITools/toAnthropicTools的字段与顺序未变,取值改为 动作描述后一一对应,模型看到的 tools 段字节稳定。 - 选择与稳定行为不变:打分权重、token 估算公式、缓存键与回退、稳定集合合并与 排序全部沿用,降级与选择日志文案逐字保留。
- 用户 Skill 视图更诚实:
userSkillActions只产出模型可见描述;执行载荷由skillReg在调用时按名称解析(skillInvoker)。这与迁移前的实际执行路径一致—— 旧闭包里的IncrementUsage在生产路径上不可达(executeToolResult先按名称解析 Skill,且 Skill 子循环的工具列表来自 Skill 自身声明,均不经候选列表的Execute)。
后续补正(见 29-ai-package-boundaries.md v28):计数展示本身是真实消费方,因此 不是删掉计数而是补回线:
executeSkill入口恢复IncrementUsage(ownerID, name)记账。
验证¶
go build ./...、go vet ./...、gofmt -l builtin/ai通过。go test ./builtin/ai/... -count=1 -v(带REMILIA_EMBED_TEST_URL)→ 590 通过 / 0 失败 / 0 跳过(较上一基线 +1,为新增的保真用例)。go test ./... -count=1全仓回归通过。
修订记录¶
| 版本 | 修订 |
|---|---|
| v1 | 建立记录:对照基线(526/0/1)、工作流清单、能力端口完成详情 |
| v2 | 记录调用器工作流完成;新增待确认事项(Q1 归类、Q2 抽象引入时机)与遗留项 L4–L6 |
| v3 | 记录行为修正待办(C1/C2)与工作流推进顺序;记录检索骨架完成(C3 同分排序不对称、L7 跨包分词重复);基线更新至 559/0/1 |
| v4 | 记录上下文管线完成(Provider/Builder 分层、差分对拍 3456 组一致);新增 C4 群聊开关不对称、精确化 C2 描述;基线更新至 562/0/1 |
| v5 | 记录选择与决策分层完成(候选发现/选择/稳定 + 保守闸门);新增 C5 双重审批、L8 闸门收紧;基线更新至 567/0/1 |
| v6 | 记录代理状态完成(归属表 + 持久化边界守卫用例,G3/G4 全覆盖);基线更新至 574/0/1 |
| v7 | 进入收口阶段:裁决 L1–L8(L2 收口、L3 定名 ActionSpec、其余保持)、C1–C5 不实施、A13/§H-6 表述勘误;目标 F 17/17 |
| v8 | 收口完成:冻结用例补齐到 17/17(含 §H 3/5/6/7/8/9/10/11/12/13 新增、17 改名);基线更新至 584/0/1;主干迁移结束 |
| v9 | 行为修正 C1 实施:失败判定改用 ActionResult.Err,退役 isToolErrorResult;记录计划校验类文案不再计入失败预算的连带影响 |
| v10 | 行为修正 C2 实施:两条路径统一不输出空运行时上下文节,退役 emitWhenEmpty;群聊开关不对称(C4)继续保留 |
| v11 | 行为修正 C3 实施:历史检索同分采用确定性次序(较新优先,事件 ID/内容兜底);基线更新至 586/0/1 |
| v12 | 行为修正 C4 实施:群聊窗口开关对两条上下文路径一致,退役 budgetEnabled |
| v13 | 记录 C5 / L7 的待确认取舍(安全回退与公开 API 面),暂停实施等待确认 |
| v14 | 行为修正 C5 实施:审批门收敛为 SendTo 授权的唯一来源(行为保持,嵌套 Skill 防护不变);基线更新至 587/0/1 |
| v15 | 遗留项 L7 实施:导出 ai.TokenizeText / TokenOverlap / TokenJaccard,knowledgebase 复用并删除重复实现;基线更新至 588/0/1(知识库 18/0/1) |
| v16 | C1–C5 与 L7 全部完成,行为修正待办清空 |
| v17 | 对照 26 目标收口文档:新增第二十一节遗留项登记(G-A~G-E)与验证盲区;工作流表补 Jev 行、修正工作流 6 交付口径与冻结用例数(20/20);27 同步用例现名与条数口径 |
| v18 | 关闭检索验证盲区:本地 embedding 服务实测契约测试通过(工具选择 Top1 54.2%→91.7%、RAG 兜底 4/4、记忆 0/2→2/2);带环境变量基线 589/0/0 |
| v19 | 遗留项 G-A 实施:memory_query 降级为上下文检索,不再作为模型可见动作(预期行为变更);G-A 标记闭环 |
| v20 | 遗留项 G-B 实施:调用策略评估(RBAC + 审批)收敛到 Decision(decideToolInvocation),执行路径只消费结论;基线保持 589/0/0 |
| v21 | 遗留项 G-C 实施:命令目录与技能运行器抽成能力端口,调用器不再依赖插件实例;基线保持 589/0/0 |
| v22 | 遗留项 G-D 实施:注册表改存动作视图,Action 成为管线内部货币、Execute 仅经执行视图取出;新增保真用例;基线更新至 590/0/0 |
| v23 | 代码组织收口(详见 29-ai-package-boundaries.md v28):删除 6 个生产不可达的导出名(含 executeTool / extractAndStore)、恢复 IncrementUsage 调用,上文“不可达”记录已被后续补正取代;新基线:./builtin/ai/ 565 / 0 失败、./builtin/ai/... 710 / 0 失败 |
| v24 | 状态标记订正(仅文档,无代码改动):工作流 4a/4b、L3/L4 与第十三节裁决表原写“⏸ 待办”,实际已由 C1 与工作流 2 交付;第八节「仍待补」表三行(N3/B5/B1,B2)已在第十四节随 §H 20/20 补齐;第十三节“行为修正待办不变”补后续已完成的注记。修正后全文无“已完成却标为待办”的标记 |
| v25 | 重构后架构评审的收尾修正(详见 CHANGELOG「Unreleased」):① 计划注入改挂 RoleUser 尾部消息(原中段 RoleSystem 被 Anthropic 丢弃,计划对 Claude 不可见);② 命令执行失败语义闭环(RunCommand 返回 (string, error)、空文本为合法结果、来源解析改显式 Pattern);③ 统一 runtime.Invoker 契约并补齐命令/Skill 的工具调用指标;④ 上下文预算权威化(新增 promptctx.BuildWindowed,预算路径不再回退非预算路径);⑤ Tool.Selection 显式化(类型 *SelectionClass,nil 按类别派生,new(SelectionMandatory) 显式声明(Go 1.26+ new(表达式));不引入零值哨兵,Optional/Baseline/Mandatory 数值保持 0/1/2 与 v1.65.0 一致,SelectionMandatory 从此可达);⑥ needAction(ctx, session) 签名化(仍保守恒真,为收紧判定预留输入);⑦ session 去除对 toolkit 的逆流依赖(缓存策略常量迁至 retrieval,SelectionCache.Tools 迁至 decision);⑧ GrantsSendTo 声明式绑定 SendTo 授权(授权 = 动作声明 ∧ 审批放行),审批目标预解析同源改读 ActionPolicy.GrantsSendTo(不再按 send_to 名字硬编码);⑨ 稳定策略变更判定改与 st.Names 比对,可用集收缩如实归因为 shrink。本行所述修正超出本文第十三节“C1–C5 不实施”的原始裁决范围,属评审后新增,第十二节的 L8 描述(needAction 闸门)相应更新为“签名已预留输入、仍保守恒真” |
| v26 | L8 实施:needAction 闸门真正收紧。纯算法(isSocialOnly 白名单 + 计划优先)下沉到 builtin/ai/decision/needaction.go(NeedAction(query, planActive)),装配侧 (*Plugin).needAction 只取 ctx.GetMessageContent() 与会话 PlanSnapshot()(Active && HasPending)并委托之;判定保守——只有“整条消息都是社交寒暄”才判否,掺杂任何其它文字或带回复/提及装饰的消息都判真,“纯知识问答”不纳入。新增配置键 need_action_gate(默认 auto,always 恢复恒开即旧行为);G1 冻结表补该行(新增键,不改旧键语义)。判否轮次跳过检索/嵌入、只保留默认保留级别与会话已用,属行为变更(CHANGELOG 已标 ⚠️) |