flutter-mcp-boundary-audit

契约边界审计

技能 ID： flutter-mcp-boundary-audit——名称沿用历史命名；内容适用于任何代码仓库。同一工作流也适用于 MCP 技术栈、RPC 网关、插件注册表和 OpenAPI 风格的契约。

对于 mcp_flutter，使用此技能审计 Flutter 适配器的一致性： fmt_* 目录架构、CLI exec、VM 服务扩展网关、动态发现、 迁移器和使用方平台文档。在此处更改应用发现或 Flutter 桥接；如需更改规范的 IntentCall 注册表／会话语义、架构策略、平台投影或发布行为，请在上游更改。

查找分裂脑漏洞：客户端在列表、目录或文档中看到的内容 ≠ 运行时在调用时执行的规则，或者只有一个网关存在验证。

典型症状：

• 声明的 required 字段与调用接受的字段不同（空负载也能成功，错误的键会被忽略）
• Host／目录路径会验证；进程内或扩展路径不会（或反过来）
• 迁移器或代码生成器会使用空或宽松的架构占位符重写条目
• 同一逻辑能力注册了两次，但使用不同架构（列表与调用之间，或路径 A 与路径 B 之间）
• 过时文档声称“始终宽松”或“不进行验证”，而代码实际上会拒绝不符合条件的请求

何时运行

触发条件（通用）	审计重点
编写工具／处理程序，在注册时附加架构	编写 → 发现负载
在应用／运行时侧动态注册或注册插件	运行时在处理程序执行前进行验证
服务端注册表、转发／分发、目录 *_client_tool 助手	注册表列表 + 调用
Host 网关（VM 扩展、IPC、HTTP 代理）在委托给运行时之前	Host 在委托前验证；缺少架构时拒绝
进程内调用（invokeDirect、浏览器钩子、嵌入式桥接）	与列表使用相同架构；执行前验证
从带注解的源代码迁移条目／生成代码	保留架构，而非使用宽松回退方案
共享架构模块与重复定义	双路径一致性
桥接处理程序、非标量参数	编码格式（JSON、protobuf 等）与处理程序预期之间的一致性
平台／ADR／注册文档	过时声明与代码之间的一致性

当多个网关使用同一逻辑工具时，如果更改了 JSON Schema、OpenAPI 请求体、protobuf RPC 消息或 插件清单输入结构，也应运行此审计。

边界检查清单

针对每个已修改的工具或 RPC，追踪 编写 → 发现 → 验证 → 执行 的完整流程：

步骤	问题	查看位置（你的仓库）
编写	规范输入架构是否传递到了注册／描述符类型（没有在工具包／桥接包装器中丢失）？	编写层／入口模型／代码生成器输出
编写	桥接工具是否为旧版处理程序一致地编码非标量参数？	桥接辅助函数、适配器层
发现	动态注册是否发送完整的 inputSchema（而非 {} 或隐式 any）？	应用注册 API、清单生成器
发现	宿主列出／目录工具公开的架构是否与运行时注册表中的一致？	列出工具处理程序与应用注册
服务注册表	注册表意图／元数据是否使用真实架构，而非宽松的占位符？	注册表构建器、MCP 工具 → 意图映射
验证（注册表）	forward／dispatch 是否在调用 execute 前进行验证？	注册表转发路径
验证（宿主网关）	宿主网关是否在委托前进行验证？架构缺失时是否默认拒绝？	网关实现
验证（运行时）	运行时回调是否在处理程序前进行验证？	服务扩展／进程内钩子
验证（线路）	如果线路参数是字符串／映射，在接收线路格式的路径上，是否会在严格验证前进行强制转换？	强制转换模块与仅宿主端的类型化 JSON
验证（进程内）	直接调用是否在 execute 前进行验证？	进程内入口调用
验证（CLI）	CLI exec／目录命令是否使用与 MCP 列表相同的架构？	CLI 分发与服务端工具
执行	生产代码中是否存在未经 validate 就调用 .execute(／分发处理程序的情况？	搜索（见下文）
迁移器	迁移是否保留源架构中的原始类型／必需项／additionalProperties？	迁移器、代码生成
文档	平台／注册文档是否与实际的默认拒绝行为一致？	平台文档、ADR

网关差异

同一个逻辑工具可能经由不同网关流转——每个网关都必须在架构和验证顺序上保持一致：

Authoring (entry / descriptor)
    ├─► Runtime registration ──► extension/callback ──► handler
    ├─► In-process register (WebMCP / embedded) ──► invokeDirect
    └─► Host list/catalog ──► catalog invoke ──► host gateway ──► runtime

网关角色	必须在何者之前验证	架构缺失时是否失败？
运行时回调（扩展、插件钩子）	处理程序	是（生产工具）
注册表转发	execute／处理程序	是
宿主网关（代理到运行时）	委托调用	是
进程内调用	execute	是
目录／fmt_*／CLI 包装器	转发到运行时	是（与列表相同）
CLI exec	命令分发	是

危险信号： 验证只在测试中、只在目录路径上或只在列表时执行，而不在你的修改实际使用的路径上执行。

线路强制转换（适用时）

有些技术栈在线路上传递字符串键映射（VM 服务扩展、类型较宽松的 JSON-RPC）。请区分以下事项：

机制	作用
按架构强制转换	在严格架构验证前，将线路字符串中的属性值强制转换为对应类型
处理程序端线路解析器	处理程序仍读取原始线路映射时可选使用
出站线路编码	处理程序参数 → 线路安全表示

如果只在一侧添加强制转换，请重新审计宿主网关与运行时回调——期望类型化 JSON 的宿主不得假定运行时已完成强制转换，反之亦然。

双路径一致性

一个逻辑能力通常会存在两次：

路径	典型作用	列出／调用
运行时／应用动态路径	在运行中的应用或插件宿主中注册	扩展名称、动态注册表
宿主目录	服务端 MCP 工具、CLI 别名、OpenAPI 路由	在线路上传递带前缀或不带前缀的名称

对于每个共享工具，请比较：

• required 键
• additionalProperties: false（或等效的严格性）
• 仅宿主端字段（例如 connection）是否只存在于某一路径
• 属性类型／枚举
• 默认值和强制转换行为

请在平台契约文档中记录有意的差异（不要只记录在测试中）。

危险信号搜索

从仓库根目录运行。根据你的语言和包布局调整 glob。

# Empty or permissive advertised schemas (JSON Schema style)
rg "inputSchema:\s*const\s*\{\s*'type':\s*'object'" --glob "*.dart" -g '!test/fixtures/**' -g '!**/after_*.dart'
rg '"type"\s*:\s*"object"\s*,\s*\}' --glob "*.{dart,ts,js,json,yaml}"
rg "_emptyObjectSchema|additionalProperties:\s*true" --glob "*.{dart,ts,js}"

# OpenAPI / generic permissive bodies
rg "additionalProperties:\s*true" --glob "*.{yaml,yml,json}"
rg "schema:\s*\{\s*\}" --glob "*.{yaml,yml}"

# Execute without validate (review each hit; exclude tests/fixtures)
rg "\.execute\(" --glob "*.{dart,ts,js}" | rg -v "validate|test/|_test\.|\.test\."

# Direct invoke bypass
rg "invokeDirect|invoke_direct|directInvoke" --glob "*.{dart,ts,js}"
# Manual review: validate appears before execute on each path

# Permissive registry placeholders
rg "emptyObjectSchema|empty_object_schema|placeholder.*schema|inputSchemaFrom" --glob "*.{dart,ts,js}"

# Migrator stripping schemas
rg "inputSchema|input_schema" --glob "*migrate*"

# Duplicate registration (e.g. JS + native)
rg "registerTool|register_tool" --glob "*.{dart,ts,js}"

# Stale “always permissive” docs
rg -i "permissive|additionalProperties:\s*true|no validation|accepts anything" --glob "*.md"

# Bridge / JSON args
rg "jsonEncode|JSON\.encode|serialize.*argument" --glob "*{bridge,entry,adapter}*"

完成适配你的仓库后，添加项目专属的模式。

端到端验证

运行你自己的集成测试，覆盖工具列出 + 无效调用（不要限定为某个特定应用路径）。

检查清单：

1. 列出工具／资源（或 OpenAPI GET）时，会显示预期的 required 和严格的 additionalProperties。
2. 缺少 required 字段时调用工具 → 返回结构化失败（ok: false、4xx 或验证错误），并且发生在处理程序产生副作用之前。
3. 在架构为严格模式时，传入额外属性 → 同样的失败模式。
4. 如果存在双路径，在目录和运行时注册名称上都重复验证。

可选：编写架构一致性单元测试，比较共享模块与重复定义（无需设备）。

报告模板

## Finding: [title]
- **Severity**: P0 | P1 | P2
- **Boundary**: authoring | discovery | validation | execute
- **Gateway**: runtime-callback | registry | in-process | host-gateway | cli | migrator | docs
- **Files**: ...
- **Symptom**: clients/docs see X; runtime does Y
- **Fix**: ...
- **Proof**: test name or grep command

跟踪记录（可选）

如果你的仓库使用 superpowers／tracker 或强化计划，请在那里或以 issue 的形式记录新发现——除非发生回归，否则不要重新打开已完成的事项。

适配你的仓库

审计前，请填写此映射（保存在审计记录或 PR 描述中）：

角色	你的代码位置	备注
定义	例如入口模型、OpenAPI 规范、@Tool 注解	规范架构的定义位置
发现	例如 registerDynamics、插件清单、MCP tools/list	客户端读取的内容
注册表／目录	例如动态注册表、服务端工具表	列出与调用的入口
宿主网关	例如 VM 扩展代理、API 网关、sidecar	委派前是否验证？
运行时回调	例如服务扩展、插件宿主 RPC	处理程序运行前是否验证？
进程内调用	例如 WebMCP、嵌入式 JS 桥接	是否与 tools/list 相同？
CLI	例如 exec、带前缀与不带前缀的别名	是否使用与 MCP 相同的架构？
共享架构模块	例如 interaction_input_schemas、OpenAPI components	是否为单一事实来源？
迁移器／代码生成	例如 migrate agent-entries	是否保留 required／properties？
平台文档	例如 INTENTCALL_PLATFORM.md、README 契约章节	是否与 fail-closed 代码一致？

检查清单

• 映射工具注册路径（定义 → 发现）。
• 映射列出网关与调用网关；列出每一跳。
• 映射架构表示形式（JSON Schema maps、OpenAPI、protobuf、Dart ObjectSchema 等）。
• 添加 2–3 条仓库专属的危险信号搜索（宽松占位符、你的调用辅助函数名称）。
• 找出双路径工具；注明共享模块或记录有意的拆分。
• 针对你接触的每个网关，运行集成测试或手动验证一个严格模式工具。

深入参考

完整示例（mcp_flutter）、文件映射和回归模式：reference.md

相关技能（mcp_flutter）

仅在此单体仓库中工作时：

• flutter-mcp-toolkit-custom-tools — 编写入口
• flutter-mcp-toolkit-intentcall-migration — 迁移 agent-entries
• flutter-mcp-toolkit-maintain-web — WebMCP／进程内调用
• flutter-mcp-cli-runtime-validation — 运行时 validate-runtime