qwen-code MCP 模型可见 Payload 过滤可逆别名机制与组件边界解析【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读在基于 MCPModel Context Protocol的 AI Coding Agent 架构中模型 API 路由有时会拒绝文本对话历史中出现已知厂商术语的请求。本文聚焦 qwen-code 仓库中的MCP_MODEL_PAYLOAD_FILTER设计设计文档见 docs/design/mcp-payload-filter.md深入讲解其目标、术语清单、无状态十六进制 Token 编码机制以及它在cua-driverRust与mobile-mcpTypeScript两个组件中的落地边界。读完本文你将掌握该过滤开关的配置方式、可逆别名的工作原理、哪些数据会被转换而哪些会被原样保留以及它为何不会影响应用、窗口、设备、包的真实操作能力。背景为什么需要模型可见的文本过滤cua-driver桌面端计算机使用驱动和 mobile-mcp移动端设备操作服务在运行时会向模型返回大量文本化 MCP Payload例如已安装应用的名称如com.alibaba.qwen窗口标题、进程名、包名、路径如/Applications/Alibaba Cloud/Qwen.app设备、模拟器与应用的列表、权限描述、健康状态信息。部分模型 API 路由会拒绝对话历史中出现这些已知厂商术语的请求导致 Agent 无法继续工作。然而这些本机值又是操作应用、窗口、设备、包所必需的——不能简单删除或模糊化。该设计的目标由此明确防止 cua-driver 和 mobile-mcp 在文本化 MCP Payload 中返回已知厂商术语同时保留操作应用、窗口、设备、包所需的真实本机值。实现方式不是删改数据而是对匹配文本进行可逆的别名化模型侧看到的是安全 Token将 Token 原样作为工具参数返回给同一个 MCP 服务器后服务器在工具校验与执行之前将其解码回真实值。开关与作用域默认关闭的 Opt-in 特性过滤是显式开启的默认关闭。在 MCP 服务器环境中设置MCP_MODEL_PAYLOAD_FILTER1对于拒绝这些术语的 API 路由开启后文本 Payload 会被过滤其他路由上的用户保留原始 Payload不受任何影响。开关判定非常严格。在 cua-driver 的 Rust 实现中model_payload.rs 通过std::env::var_os(MCP_MODEL_PAYLOAD_FILTER)读取并仅当值严格等于字符串1时才启用测试filter_opt_in_requires_exact_one验证了、0、01、true、TRUE、yes、 1等值均不启用过滤。在 mobile-mcp 侧server.ts 中的PayloadFilteredMcpServer子类同样用process.env.MCP_MODEL_PAYLOAD_FILTER 1判断只有命中时才用包装 Transport 替换原始 Transport否则原样连接。过滤术语表ASCII、中文与分隔符变体设计文档与两侧实现Rust 常量表与 TypeScript 正则源共同定义了同一套术语清单。ASCII 术语不区分大小写cua-driver 的 ASCII_TERMS 与 mobile-mcp 的FILTERED_TERM_SOURCES完全对应类别术语模型/服务品牌qwen、qianwen、tongyi、bailian、modelscope、damo、wanx、maxcompute、qoder、lingma云厂商品牌alibaba、aliyun、aliyuncs、alicloud、dashscope、alipay、antfin、antgroup协作/通讯应用yuque、dingtalk、taobao、tmall共 21 个 ASCII 术语匹配时使用 ASCII 大小写不敏感比较Rust 侧eq_ignore_ascii_caseTS 侧正则gi标志。中文术语精确匹配共 14 个见 CHINESE_TERMS通义、千问、阿里、百炼、魔搭、达摩、灵码、万相、支付宝、蚂蚁、语雀、钉钉、淘宝、天猫。分隔符变体多词名称对于由两部分拼成的名称还匹配带有分隔符的变体例如q-wen、dash_scope、ali cloud、qian-wen、ant_group。Rust 侧由 SEPARATOR_PATTERNS 定义 8 组二元模式q/wen、dash/scope、ali/baba、ali/yun、ali/cloud、tong/yi、qian/wen、ant/group允许中间出现-、_、空格或无分隔符。mobile-mcp 侧则在正则中直接用[-_ ]?表达同样语义并在匹配时使用最长匹配策略避免ali与alibaba等重叠词互相干扰。编码机制无状态 Token 与 UTF-8 十六进制往返这是整个设计的核心每个被匹配到的子串被替换为一个无状态 TokenToken 内嵌该子串的 UTF-8 十六进制字节。两个组件使用各自独立的前缀实现上不互通但机制一致组件Token 前缀Token 形态示例qwen→71 77 65 6Ecua-driverRust__cuaf___cuaf_7177656E__mobile-mcpTypeScript__mcp_ref___mcp_ref_7177656E__以 cua-driver 的 encode_text / decode_text 为例编码从左到右扫描输入命中过滤术语或已存在的 Token 前缀时将该子串的原始 UTF-8 字节逐个转为大写十六进制写入前缀 hex __其余字符原样复制。push_token使用0123456789ABCDEF十六进制表。解码查找TOKEN_PREFIX提取其后到__之间的十六进制串按两字节一组还原为 UTF-8 字节无效 Token 保持字面原文测试leaves_invalid_tokens_literal验证__cuaf___、__cuaf_0__、__cuaf_ZZ__、__cuaf_FF__均原样返回。解码是单遍的一个字面量 Token 前缀被转义后作为数据恢复不会被二次解释测试escapes_a_literal_token_prefix。选择这种设计而非会话内映射表的关键收益无状态不维护 session map进程重启后 App/包/路径的往返依然成立可读性被过滤的 App 名周围文本保持可读Token 只占匹配部分可恢复模型把该值原样返回给同一 MCP 服务器时工具校验与执行前就能还原出精确的原始子串。组件边界两个方向的接入点设计文档明确了两侧模型可见边界的接入点仓库源码与之完全对应。cua-driverRustResponse 与 Request 双向接入在 protocol.rs 中出站方向Response::ok与Response::error是直接 stdio、HTTP、daemon-proxy MCP 响应共用的模型可见边界。ok_with_filter在启用时对整个 result 调用model_payload::encode_valueprotocol.rserror_with_filter对错误 message 调用encode_textprotocol.rs。入站方向Request::tool_call在派发工具之前解码工具名与参数——先对arguments整体执行decode_value再对工具name执行decode_textprotocol.rs。两个方向都只在MCP_MODEL_PAYLOAD_FILTER1时应用转换is_enabled()每次调用时实时读取环境变量。mobile-mcpTypeScriptTransport 包装层在 payload-filter.ts 中PayloadFilteringTransport是一个包装 Transport出站send()对每条消息调用encodePayloadMessage只转换params、result、error三个字段transformMessage入站onmessage处理器先decodePayloadMessage再交给 SDK 进行 schema 校验键冲突防护若解码导致对象键折叠恶意 Payload 可制造别名让两个键塌缩成一个PayloadKeyCollisionError会被捕获若消息带id则向客户端回一个-32602Invalid paramsJSON-RPC 错误否则交给onerror处理。而 server.ts 中的PayloadFilteredMcpServer在connect()时根据环境变量决定启用则new PayloadFilteringTransport(transport)否则直接使用原始 Transport。因此 stdio、SSE、内存测试及未来新增 Transport 全部自动获得同样的过滤能力。遍历规则与边界保护过滤以递归方式作用于 JSON 结构具体规则Rust 侧 transform_valueTS 侧transformPayload字符串编码/解码其文本数组递归处理每个元素对象键和值都递归转换type为image或audio的对象其data字段被标记为不透明逐字节原样保留不参与文本过滤Rust 与 TS 两侧实现一致但该对象的其他字段如annotations、文本描述仍会转换null、布尔、数字不处理。两条硬性边界JSON-RPCid与method永不转换——它们不参与往返转换会破坏协议寻址键冲突即报错解码过程中若两个不同的键被还原为同一个键Qwen: 1与__cuaf_5177656E__: 2解码后都变成QwenRust 侧decode_value返回错误TS 侧抛PayloadKeyCollisionError——拒绝这类输入而不是静默丢弃其中一个值。非目标与适用限制设计文档明确划定了过滤的边界这些限制在实现中同样成立不做重命名不会重命名已安装的应用、进程、bundle、npm 包、签名身份、仓库或分发 URL不碰非模型可见输出stderr、遥测telemetry、构建日志不会被转换不保证 OCR 场景图片字节被保留因此基于 OCR 的过滤不在文本 Payload保证范围内别名只在回家时解码别名只有在返回给同一个 MCP 组件时才会被还原为本地值把别名传给 shell 或另一个 MCP 服务器不会恢复本地值mobile-mcp README 也做了同样说明。配置示例在移动端 MCP 服务器上开启过滤以 mobile-mcp 为例READMEpackages/mobile-mcp/README.md给出在 MCP 客户端配置中针对特定路由开启过滤的方式{ mcpServers: { mobile-mcp: { command: npx, args: [qwen-code/mobile-mcp], env: { MCP_MODEL_PAYLOAD_FILTER: 1 } } } }对于 cua-driver在服务器进程环境中导出MCP_MODEL_PAYLOAD_FILTER1即可见 packages/cua-driver/README.md文档明确该开关默认关闭、不会改变直接 SDK 契约。只有在模型 API 路由会拒绝这些术语时再开启其他场景保持默认即可获得原始 Payload。验证与测试从单元到真实协议交互设计文档列出的验证清单在仓库中均有对应实现。cua-driverRust 单元测试model_payload.rs 内置了完整测试套件filters_every_canonical_term_case_insensitively每个 ASCII 术语含全大写变体与每个中文术语都做编码→解码往返断言filters_supported_separator_variants对 8 组模式覆盖空分隔符、-、_、空格四种变体以及DaSh_ScOpE、QIAN-WEN、Ant Group混合写法preserves_surrounding_text_and_multiple_matches验证Open Q-Wen in 阿里 Cloud, then inspect Dash_Scope.编码后首尾文本保留、过滤词消失、解码后完全还原recursively_transforms_keys_and_values_but_not_media_data验证对象键被转换、image/audio的data字节保留、注解字段仍被过滤decoding_rejects_object_key_collisions验证键冲突返回错误filters_driver_identity_from_observed_windows_apps_and_tree_shapes用真实观察到的qwen-cua-driver.exe形态text content、structuredContent 中的 windows/apps/processes验证编码后序列化结果中不再包含qwen且解码后与原文一致safe_text_is_borrowed_and_unchanged不包含过滤词的文本走零拷贝Cow::Borrowed路径性能不受影响。mobile-mcp端到端协议测试test/server-payload-filter.test.ts 使用InMemoryTransport 真实 MCP Client 验证两条主路径禁用时payload_unfiltered_probe的描述与结果原样保留证明默认边界不被改变启用时覆盖initialize、tools/list、成功响应text 与 structuredContent、错误响应、schema 校验失败、图片 data 保留、mobile_list_apps/mobile_launch_app真实工具链路的完整往返——尤其验证了客户端用encodeFilteredText(Q-Wen)传入参数时服务端在 schema 校验superRefine之前已将其解码为Q-Wen原始值即先解码、后校验、再执行的顺序成立。小结MCP 模型可见 Payload 过滤是 qwen-code 为适配对厂商术语敏感的模型 API 路由而设计的一套可逆、无状态、默认关闭的文本净化方案。它通过MCP_MODEL_PAYLOAD_FILTER1一键启用用内嵌 UTF-8 十六进制字节的 Token 替换 21 个 ASCII 术语、14 个中文术语及 8 组多词分隔符变体递归作用于对象键与文本值同时逐字节保留图片/音频data、永不触碰 JSON-RPCid与method。在 cua-driver 侧Response::ok/error与Request::tool_call构成双向过滤边界在 mobile-mcp 侧PayloadFilteringTransport统一包装 stdio、SSE 与内存传输。理解这一机制就能在需要时安全地为指定路由开启过滤同时确信应用、包名、路径等真实操作值始终能够无损往返。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考