Copilot 扩展、MCP 与 Hook
Copilot 通过进程内模块注册读取业务上下文、接收窄范围工具与执行 Hook,通过外部 MCP client 使用独立服务。三种入口沿用宿主的参数、权限、审批和结果协议;本主题说明各自的接入方式与生命周期。
业务模块 Agent 扩展
Flow、设备、模板、图像和其他业务项目不能反向引用主程序中的 ICopilotTool。需要把模块状态或窄业务动作交给 Agent 时,在 UI 公共契约层使用 CopilotAgentExtensionRegistry.Shared.Register,并持有返回的 IDisposable。注册项包含稳定 SourceId、显示名、版本,以及 ContextProviders、Tools、ToolExecutionHooks 三类集合;至少提供一项上下文、工具或 Hook。页面、编辑器或插件卸载时释放句柄,相关注册和 Capability Catalog 来源随之撤销。注册表拒绝空扩展、重复来源、跨模块重复工具名、非法 Schema 和无界超时,桥接层还会报告与内置工具名冲突的能力并拒绝激活。
ICopilotModuleTool 是面向业务程序集的窄契约,不暴露模型 Profile、审批对象、会话 checkpoint 或完整 Agent 内部状态。模块只接收当前模式、用户目标、结构化参数、已采集上下文、搜索根和活动文档。只读模块工具映射成 ReadOnly + Idempotent + SharedRead;任何声明为 Write 的模块工具都由宿主强制映射成 High risk + Always approval + NonIdempotent + Exclusive,未收到 Agent Framework 对本次精确函数调用的原生批准时适配器直接拒绝,模块不能自行降低风险等级。
模块工具必须提供稳定名称、短说明和对象类型 JSON Schema。SourceVersion、工具类型、说明、安全元数据和 Schema 共同进入 Capability Catalog 指纹;模块升级、注销或语义改变会让旧 checkpoint 重新规划。动态上下文在 Agent 任务真正开始时从当前注册快照采集,适合窗口和编辑对象生命周期,不需要重建 Copilot 面板。EditTemplateJson、FlowEngineManager、ServiceManager、检测结果页面与任务调度器已完成实际接入:模板编辑器 Loaded 时注册当前模板 JSON 上下文提供者,Unloaded 时注销;Flow 和设备服务单例各自只注册一次提供者,但在每次相关请求开始时通过 UI Dispatcher 重新读取当前对象,不复用旧快照。Flow 上下文只在 Diagnose、明确 Flow 意图或 Flow 仍是当前软件表面时采集,运行消息只保留最近 6,000 字符并统一脱敏。结果页面和调度器窗口使用公共的 CopilotDynamicContextCoordinator<TSnapshot> 管理会话:同一模块只注册一个来源,多个窗口或 Page 之间跟随最近激活实例,异步采集完成前若页面已经切换则丢弃旧快照。纯页面来源在最后一个页面关闭后自动注销;调度器保留一个管理器级会话,使用户不打开任务窗口也能通过明确调度意图查询最新聚合状态,窗口会话只在激活时覆盖为当前任务或历史页。
设备扩展会跟踪主显示区当前选中的设备,也会跟随服务管理窗口中的设备选择;用户点名唯一设备时优先读取该对象。单设备上下文包含显式心跳观测、独立的 MQTT 缓存操作状态和最多 60 个简单配置字段;未观测的心跳为 Unknown,不因默认 false、时间戳或缓存操作状态推为离线/在线。底层 CLR 字段名先完成 SN、token、license 等脱敏,再使用本地化显示名;设备名称、代码、主题、摘要和日志仍经过第二层内联脱敏。未锁定单设备时先统计全部已知在线/已知离线/未知设备,再提供最多 60 项设备总览,不注入配置。设备重载、删除或切换显示面后旧对象不再被采集。当前阶段没有注册设备控制工具,原有 Live Context 继续负责 UI 位置摘要和用户显式附件,两者职责不同。
测量结果自动上下文继续跟随当前页面,提供汇总与选中项,固定 SourceId=measurement-results;有效详情页快照还从已有 registration token 一次取得完整 source_ref/expected_source_instance_id 对,便于直接调用正式 InspectLoadedBatchResults。历史列表、legacy 或无效/半对快照不提供该绑定;采集不会 Ensure 或重绑旧 rows。没有完整绑定时从全部已注册详情页目录发现,不以当前选择或批次 ID 猜关联。正式来源通过弱引用登记,单次 UI 投影前后复核注册集合、批次模型和结果对象集合;页面卸载、关闭或批次模型改变后旧来源不能转向新数据,历史附件引用也须由工具重验。工具不为查询创建页面、回查数据库或触发结果 handler。
业务菜单可以显式附加一次快照:流程右键“问 AI 分析当前流程”由 FlowEngineManager.AskCopilotFlowCommand 调用 FlowCopilotService.AskAboutCurrentFlow(),附带当前流程、选中或活动节点、节点参数及最近运行/失败证据;设备右键“问 Copilot”由 DeviceService.AskCopilotCommand 采集该设备的诊断上下文。两者经 CopilotBusinessContextCoordinator.DispatchDiagnosis 发起诊断请求,附加上下文本身不执行流程或控制设备。
图像右键“问 AI 分析当前图像”由 ZoomEditorToolContextMenu 采集 ImageViewConfig 属性、ROI/选区和标注摘要,再由 CopilotBusinessContextBuilder.BuildImageContextItem 构造结构化文本。该入口不附加图像像素,不能据此声称已观察像素或完成图像算法检测;这也不限制运行时的显式图片附件。
EditTemplateJson 的 Copilot 操作附加编辑器模式、模板/Schema 身份、JSON 语法状态和相对加载快照的修改状态。BuildCopilotSnapshotContextItem() 只保留当前 JSON 的前 16,000 字符并标记截断,不保证完整参数可供补丁计算。JSON validation 由 JsonHelper.IsValidJson 得出,不是 Schema 或业务参数验证;Unsaved changes 仅比较当前 JSON 与加载参数时 _loadedJsonSnapshot 的 Trim() 后文本,不查询数据库确认是否已保存。补丁的来源匹配和不自动保存边界见模板 JSON 预览与应用。本页已有 MCP/Hook 测试不证明这些菜单、WPF 编辑器快照或图像上下文的端到端行为。
/context 本地诊断会列出当前模块扩展来源、版本、上下文提供者数量、工具已激活/声明数量以及最多八个冲突或发布问题;输出有数量和单行长度上限,不调用模型,也不写入会话历史。模块工具名与内置工具冲突时,诊断会保留来源和原因,实际工具不会进入 Agent 工具面。
模块 DLL 在 ColorVision 进程内运行,与普通插件代码使用相同的信任边界;注册表不隔离其 Windows 身份、文件或网络访问。外部 MCP 使用独立连接与审批链,不能继承进程内注册带来的权限。通用 Shell 的 Job Object 和审批也不构成系统沙箱,其执行约束见工作区与 Shell 工具。
外部 MCP 工具发现
Copilot 使用官方 ModelContextProtocol.Core SDK 连接显式配置的 Streamable HTTP 服务。每次请求开始时发现工具,适配为 ICopilotTool 后再进入 Harness;外部工具不会绕过输入 Schema、调用次数、超时、并发闸门、生命周期事件、脱敏审计或审批机制。
- 当前只支持显式 Streamable HTTP 地址,不启动 stdio 命令或任意本地进程。
- 最多配置 8 个服务;单服务最多暴露 32 个工具,单请求最多合并 64 个外部工具。与内置工具重名时保留内置工具并记录诊断。
- 远程地址必须是 HTTPS;只有 loopback 允许 HTTP。URL 中不能嵌入用户名或密码。
- bearer token 只通过环境变量解析,配置文件不保存 token 值。
- 默认
approval将整个服务视为高风险、可写、非幂等能力,每次精确调用都经过ApprovalRequiredAIFunction的原生审批边界;人工或自动复核的决定规则见原生审批契约,配置服务不构成调用批准。 - 配置第五段可按远端工具精确名称建立白名单,并用
tool=approval/read-only覆盖服务默认策略;只要存在白名单,未列出的工具就不会进入 Harness。留空或*为兼容模式,会暴露服务发现的全部工具。 read-only是操作者对对应工具做出的显式信任声明;此时工具按只读、幂等能力进入共享读取闸门。远端返回的 tool annotations 只作为提示,不用于放宽本地权限。- 成功发现的协议
Tool定义进入最多 32 个服务项、每个服务最多 512 个定义、默认 TTL 5 分钟的进程内缓存;缓存键包含服务、地址和 bearer token 的不可逆指纹,不保存 token 明文。缓存命中时使用官方McpClientTool(McpClient, Tool, ...)构造路径绑定到本轮新连接,不复用或常驻旧会话。 - 若服务通过
ServerCapabilities.Tools.ListChanged声明支持工具列表变更,client lease 会注册notifications/tools/list_changed处理器;收到通知后立即使对应缓存失效,下一轮强制实时发现。处理器先于 client 释放,只在当前请求连接存续期间监听;TTL 和设置页Refresh Discovery仍是无活跃连接时的兜底。ColorVision 自带 MCP server 尚不能主动发送该通知,因此不会虚假声明此能力。 - SDK 的
McpClient只拥有会话 transport,不拥有外层HttpClientTransport;provider 必须保留外层 HTTP 所有者,并在运行时 lease 或诊断/失败清理中按通知处理器、client、外层 transport 的顺序有界释放,最后关闭其HttpClient包装器。 - 设置页
Refresh Discovery通过CopilotMcpToolProvider.RefreshDiscoveryAsync强制绕过缓存,顺序核查最多 8 个启用服务,保留单服务连接超时、分页和定义大小限制。诊断不会因运行时已合并 64 个工具而漏查后续服务;它只更新缓存/健康并及时释放各连接,不发布可调用工具或裁剪运行时 capability catalog。Agent 的DiscoverAsync仍限制单服务 32、单请求 64 个外部工具。实时发现会比较有界能力签名、保留或递增服务能力 revision 并发出进程内变更事件;健康快照标明本轮使用 live 还是 cached discovery,并在通知已使缓存失效时显示需要实时刷新。 - 进入运行时的 MCP JSON Schema 会传给模型;本地通过共享
CopilotToolInputContractValidator递归验证支持的嵌套对象、数组及字段约束,并限制参数总长度。声明不支持约束的工具不会暴露;本地输入校验失败时不发送tools/call。远端仍负责自己的权限与业务校验,本地 Schema 通过不证明远端操作可执行。共享规则见输入校验与无效调用。 - 工具发现会记录进程内健康快照,包括连接状态、发现数量和实际暴露数量;设置页只显示紧凑摘要,不把连接错误铺到主聊天区。
- 单个服务不可用只产生运行时诊断,不会终止 Agent 请求;普通聊天界面隐藏这类基础设施噪声。
写入或非幂等 MCP 调用进入 SDK 后,如果因传输错误、取消、响应损坏或结果解析失败而未取得可用的协议回复,适配器返回 OutcomeUnknown / tool_outcome_unknown,不能把本地请求结束理解为远端没有执行。结果只包含固定说明,不回显异常正文;模型输出与工具事件保留同一失败码,后续 checkpoint 禁止直接恢复工具任务,需重新规划并核对外部状态;无工具的 Finalize 仍可整理已有结果,详见显式有界重试。调用前已取消、未批准或本地参数无效时不会发送 tools/call;正常返回的 CallToolResult(含 isError)和有效 JSON-RPC 错误回复仍保留原有处理,不因失败本身被改判为未知。只读幂等工具也保留既有重试规则。
设置中的每行由名称、Streamable HTTP 地址、token 环境变量名、默认策略和工具白名单五段组成。下面只是配置格式示例,保存/发现/实际工具调用仍是分别授权的动作;不要把凭据值填进第三段:
lab | https://mcp.example.com/mcp | LAB_MCP_TOKEN | approval | get_status=read-only,apply_patch=approval官方 SDK 和传输说明见 Model Context Protocol C# SDK。入站 ColorVision MCP server 是另一条会话与确认链,见Local MCP,不要将外部 client 配置和本机 server token 混用。
Hook 扩展点
主程序内部通过 ICopilotToolExecutionHook 接入执行器;业务模块通过公共 ICopilotModuleToolExecutionHook 及注册项的 ToolExecutionHooks 接入,无需引用主程序 Agent 类型。模块 Hook 声明稳定名称、ToolNamePattern、顺序和 ExecutionMode,可观察匹配工具的调用上下文与执行结果。
| 模式与阶段 | 当前作用 |
|---|---|
Sync + BeforeExecuteAsync | 工具执行前的控制点。拒绝、异常、自行取消或超时会阻止本次工具执行,并保留对应失败状态 |
Sync + AfterExecuteAsync | 接收已产生的执行结果,用于记录和诊断。异常、取消或超时记入 Hook 状态,不把已经执行的业务结果改成未执行,也不提供回滚 |
Async + 前置/后置回调 | 有界后台通知;前置返回的拒绝决定和输出不会控制发起它的工具,后置输出也不改工具结果。回调可能重叠,实现必须处理并发 |
方法名中的 Async 表示返回异步任务,能否阻止工具取决于 ExecutionMode。不能把所有 BeforeExecuteAsync 都描述为审批或拒绝门禁。
需要在受保护调用的审批边界补充理由或拒绝时,实现 ICopilotModuleToolPermissionRequestHook。它只能保留原生确认流程或拒绝,不能替用户批准;执行上下文中的 FrameworkApprovalGranted 是宿主状态,不是模块可发放的授权。精确输入冻结和审批绑定见工具契约。
Hook 应保留真实工具结果,避免将回调完成当作业务成功;不要保存未脱敏参数。后置 Hook 的事件发布失败也不能据此重放已经完成的写入。相关失败记录应同时核对工具终态和 Hook 终态。
实现与验证入口
CopilotAgentExtensionRegistry:注册、同名冲突、来源版本及释放;业务实现入口为FlowCopilotService、CopilotDeviceContextProvider、EditTemplateJson,结果与调度上下文详见任务与内置工具。CopilotToolExecution.Hooks.cs:同步控制、后台通知与结果发布。
验收扩展时核对实际注册来源、作用域、工具返回及外部服务行为。
