tako 文档 GitHub

MAF 最小审批回路(L1 tool guard 的 MAF 等价物)设计

状态:设计已批准(2026-09-26),待实施。 缘起:doc/09-设计了解.md §12 讨论的问题——Eino 的 resume 中段里,写入端 (adkrun 的 Targets)与读取端(guard 的 GetResumeContext)分居两文件、靠 checkpoint 的 ID↔︎地址映射与 ctx 公告板在运行时相遇。用户要求核对 MAF 是否有 对应功能;MAF 没有,故本设计在 maf/ 里补上这个功能,并按 MAF 自己的最地道 实践实现(不迁就与 Eino 的形状一致),实现后再做机制对比(落在 doc/10-MAF审批回路与Eino对照.md)。

1. 背景与前提(事实,可检验)

F1 — 本仓库 MAF 现状:连功能都没有。 maf/ 是 L2 任务规划的 MAF 对照,README 明说「只覆盖 L2(L1 守卫不在内)」(maf/README.md:8)。全目录 grep Resume|Interrupt|Checkpoint|Approval 零命中:没有守卫、没有中断、没有恢复。 README.md:49 自述「要持久化得自己序列化 TodoStore(L6 断点恢复时再处理)」。 所以 §12 的问题在 MAF 不是「解法不同」,而是「回路尚未存在」。前提确认:本设计 需要先给 MAF 补上 L1 的最小审批回路。

F2 — MAF 框架自带这条回路(API 已用反射探针逐一钉死,包 Microsoft.Agents.AI 1.22.0 / Microsoft.Extensions.AI 10.10.0):

F3 — 框架的审批不是 Eino 式 interrupt/resume。 没有执行图、没有 checkpoint, 是消息级请求-回执协议:跑完的响应把「待批请求」作为内容交给调用方,调用方 下一条消息把「回执」带回来,FICC 重建并执行被批的那次调用。「重入」由 FICC 的 重建机制完成,历史一致性(tool_calls 与结果配对)由框架保证。

F4 — Eino 侧的对照物(doc/09 §12 已述): 写入端 yk-tako-eino/internal/adkrun/turn.go:98-110(targets[point.ID]=decision), 读取端 yk-tako-eino/internal/guard/middleware.go:98-107(ownInterrupt + resumeDecision),钥匙是 point.ID + checkpoint 的 ID↔︎地址映射,公告板是 ctx。

F5 — 规则表是框架无关的,可移植。 yk-tako-eino/internal/guard/toolguard.go 的文件头自述「不含 Eino 依赖,规则本身与框架无关」,DefaultRules 10 条危险命令 规则瞄 shell 工具(bash/execute 的 command 参数),带 Severity、Excludes、 三模式(block / warn / require_approval)。Eino 入口默认 ModeApprove (cmd/yktako/main.go:49),/mode 可切。

2. 目标功能语义(与 Eino 对齐的三态)

前提:guard 规则表先在工具执行前扫参数,扫出命中清单(Finding)。按模式:

模式 命中 无命中
warn 命中任意规则:打印 ⚠️ 告警后放行 放行
block 命中达拦截级别(Critical/High):不执行,拦截文案作为工具结果回给模型(不打扰人);命中未达级别:放行 放行
require_approval(默认) 命中达拦截级别(Critical/High/Medium):暂停问人,批准→执行、拒绝→拒绝文案作为工具结果回给模型;命中未达级别:放行 放行

级别映射沿用 Eino blocking(toolguard.go:149-153):block 拦 Critical/High, require_approval 连 Medium 也拦,warn 不拦。

REPL 交互补两条(对齐 cmd/yktako/main.go:85-103):默认 require_approval; /mode block|warn|require_approval 切换。审批文案对齐 cmd/yktako/main.go:107-124(工具、参数、命中说明、批准执行?[y/N])。

3. 设计(已选定:全用 MAF 自带 approval 管线)

3.1 为什么是这条路(取舍回顾)

3.2 组件与文件改动

文件 改动 内容
maf/src/Guard.cs 新增 Severity/Rule/Mode/Finding/Engine(Guard、ShouldBlock、Configure、Mode)+ DefaultRules 10 条移植(含 commentLine/Excludes 语义)+ FormatFindings(对齐 Eino formatFindings,≤5 条,带 snippet/remediation)
maf/src/BasicTools.cs 修改 加假 shell 工具 execute(string command):不真执行,返回「(演示用假 shell)将执行:<命令>」类回执
maf/Program.cs 修改 ① execute 注册时用 ApprovalRequiredAIFunction 包一层;② builder 链追加 UseToolApproval(new ToolApprovalAgentOptions { AutoApprovalRules = [guardRule] }),追加位置在最内层(贴近 ChatClientAgent),保持 Nudge 最外不破坏「一轮」语义;③ REPL 增审批回路与 /mode 命令
maf/tests/YkTako.MafL2.Tests.csproj + maf/tests/GuardEngineTests.cs 新增 xunit 2.4.2(本地缓存,离线可还原)单测规则引擎:命中/排除/三模式/片段截取,不打模型
maf/README.md 修改 状态行标注限定解冻;机制映射表、文件列表、实测记录各补一条
doc/10-MAF审批回路与Eino对照.md 新增 实现记录 + MAF vs Eino 逐点对比(最终版)

3.3 自动批准规则(规则引擎的落点)

guardRule(ctx):
    call      = ctx.FunctionCallContent            // execute 调用
    findings  = engine.Guard(call.Name, ParseArgs(call.Arguments))
    if engine.Mode() == warn:
        if findings 非空: 打印 ⚠️ FormatFindings(...)
        return true                                 // warn:一律自动批,放行
    return !engine.ShouldBlock(findings)            // 无阻断命中:自动批;
                                                    // 有阻断命中:不批,留给 REPL

推导:AutoApprovalRules 只能「批或跳过」,不能拒绝——所以放行路径全部在这里 消化(用户不可见);需要拦或问人的调用由规则返回 false,冒泡到 REPL。

3.4 REPL 审批回路(写入端)

response = agent.RunAsync(input, session)
loop:
    pending = response.Messages 里 RequiresConfirmation 为真的 ToolApprovalRequestContent
    if pending 为空: break
    replies = []
    for req in pending:
        call = req.ToolCall as FunctionCallContent
        findings = engine.Guard(call.Name, ParseArgs(call.Arguments))
        if engine.Mode() == block && engine.ShouldBlock(findings):
            (approved, reason) = (false, FormatFindings(findings, "工具调用被安全策略拦截(command guard)"))
        else if !engine.ShouldBlock(findings):
            (approved, reason) = (true, "")     // 兜底:自动批准上限路径也可能 surfaced 非阻断请求,
                                                // 此时不打扰人(与 Eino「未达级别直接放行」一致)
        else:
            (approved, reason) = 问人(⏸️ 人工审批:工具/参数/命中说明;y/N)
        replies.Add(req.CreateResponse(approved, reason))
    response = agent.RunAsync(new ChatMessage(ChatRole.User, replies), session)   // 只回执,不回放用户输入
print response.Text

说明:TAA 一次只 surfaced 一个请求(其余排队),loop 自然逐个走完;FICC 对批准 的重建调用执行、对拒绝的生成失败工具结果,模型在同一个 RunAsync 内继续。

3.5 数据流与 §12 对照(初步;实现后 doc/10 给实测版)

模型输出 FunctionCallContent(execute, call_id)
  → FICC:检出 ApprovalRequiredAIFunction → 换成 ToolApprovalRequestContent
           {RequestId = ComposeApprovalRequestId(call_id)}
  → TAA:查 guardRule
       ├─ 无阻断命中 → collected response 注入 → 重入 inner → FICC 重建调用并执行 → 模型继续
       └─ 阻断命中   → 写 session.StateBag 的 SurfacedApprovalRequests → 返回 REPL
REPL:问人或按 block 直接拒 → CreateResponse → 作为新 user 消息回传
  → TAA:BindApprovalResponses 按 RequestId 绑定(快照比对,防伪造)
  → FICC:批准→重建执行;拒绝→失败工具结果给模型

4. 偏离与风险(反例优先)

5. 测试与验证

6. 范围外(本设计不做)