Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
fix(pi): 披露门自愈一次(拦一次 + 递路标 + 记账)并把判定移到权限询问之前
Zhang Yunjinb5266dc8d606
diff --git a/docs/dev-rules/pi-harness.md b/docs/dev-rules/pi-harness.mdindex 296b93974d..210f940e20 100644--- a/docs/dev-rules/pi-harness.md+++ b/docs/dev-rules/pi-harness.md@@ -57,7 +57,11 @@ Cindy 以 `pi --mode rpc` spawn pi 二进制(JSONL/stdio),`translator.ts` 把 pi调用保留 600s 长预算。SSE response 按 event 增量消费,不等待 server 关闭持续流。Pi 模型侧始终只注册 `cindy_mcp_list_tools` 与 `cindy_mcp_call_tool` 两个稳定网关 schema;完整工具目录与input schema 留在 bridge 内部。先发现名称/描述,再按具体 server + tool 取单个 schema,- 未检查 schema 的调用在 bridge 内 fail closed,不会触达 MCP 或弹权限框。Host 审批、策略与变更捕获仍使用真实+ 未检查 schema 的调用在 bridge 内 fail closed,不会触达 MCP 或弹权限框。门按会话与+ 当前工具 schema 指纹记账:Pi 升级不再作废未变 schema 的披露,schema 真变动时门重新武装。+ 首次未披露的调用在**发起权限询问之前**被拦下——不弹权限框、不触达 MCP,回执指名该查的+ server/tool 并说明重发即可放行(模型补完 `cindy_mcp_list_tools` 后重发即通过,重发那次+ 正常过一次权限)。Host 审批、策略与变更捕获仍使用真实`mcp__<server>__<tool>` identity 和真实参数,不能退化成对网关包装器授权。Claude Code 与Codex 保持各自的直接 MCP 注册方式,不经过此 Pi 专属网关。配置新增、修改、禁用或删除对下一新建/重启会话生效;旧活动会话保留启动时 generation 快照至 close。diff --git a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.tsindex a11df57834..fb6769879f 100644--- a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts+++ b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts@@ -1624,13 +1624,13 @@ describe('cindy-bridge extension source', () => {);expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain("qualifiedName: 'mcp__' + serverName + '__' + toolName");expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('private readonly disclosedSchemas');- // 披露判定按 schema 指纹(Pi 升级不再整片失效)+ 按会话落盘;门本身保持上游的- // 严格 fail closed:未披露的调用被拦下、不触达 MCP、不记账。+ // 披露按 schema 指纹持有 + 自愈放行(2026-10-13 pi 升级后整片失效、模型反复+ // 撞墙后放弃的真机事故);权限/采集分类只认“解析成功”,不再按披露状态。expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('private schemaFingerprint(');expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('markSchemaDisclosed(call: ResolvedMcpGatewayCall)');- expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('mcpGateway.isSchemaDisclosed(resolvedGatewayCall)');- expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('Inspect this tool before execution');- expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('const gatewayCall = resolvedGatewayCall && mcpGateway.isSchemaDisclosed(resolvedGatewayCall)');+ expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('gateway tool auto-disclosed on first call');+ expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('const gatewayCall = resolvedGatewayCall;');+ expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('mcpGateway.isSchemaDisclosed(gatewayCall)');expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('permissionToolName = gatewayCall?.qualifiedName');expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain('permissionInput = gatewayCall?.args');expect(CINDY_BRIDGE_EXTENSION_SOURCE).toContain(diff --git a/packages/maker-core/src/agents/pi/__tests__/mcpDisclosureFingerprint.test.ts b/packages/maker-core/src/agents/pi/__tests__/mcpDisclosureFingerprint.test.tsindex 7df3623a94..25525ac207 100644--- a/packages/maker-core/src/agents/pi/__tests__/mcpDisclosureFingerprint.test.ts+++ b/packages/maker-core/src/agents/pi/__tests__/mcpDisclosureFingerprint.test.ts@@ -5,12 +5,8 @@ import { describe, expect, it } from 'vitest';import { CINDY_BRIDGE_EXTENSION_SOURCE } from '../cindy-bridge-source.js';// 把 CindyMcpGateway 从 bridge 源码里切出来,在 VM 中用桩件驱动。断言都走真实入口-// (register 后的 cindy_mcp_call_tool / cindy_mcp_list_tools),不直接调内部方法:披露门、-// MCP 请求次数、落盘与重载都在同一条路径上被验证。-//-// 本 PR 只治「披露记录整片失效」:判定按 schema 指纹、按会话落盘。门本身保持上游的-// 严格 fail closed —— 未披露的调用被拦下、不触达 MCP、不记账;模型显式 list_tools 后-// 才算披露,随后放行。+// (register 后的 cindy_mcp_call_tool),不直接调内部方法:披露门、自愈放行、MCP+// 请求次数、落盘与重载都在同一条路径上被验证。const source = CINDY_BRIDGE_EXTENSION_SOURCE;// 从工具名常量切到 CindyMcpGateway 类结束:register() 用到的常量与 helper 都在这段里,// 因此 register 后的 cindy_mcp_call_tool 走的是与生产同一条代码路径。@@ -66,8 +62,10 @@ function loadGateway(options: {// 锁文件独立于披露文件,由外部(另一实例或崩溃残留)直接写入;null = 不存在。const lockFile: { value: string | null } = { value: null };if (options.lockOwner !== undefined) lockFile.value = String(options.lockOwner);+// stale 回收槽:rename(lock→stale) 时锁内容搬到这里。const staleFile: { value: string | null } = { value: null };+const externalWrite = (value: DisclosedFile) => { disk.value = value; };const reclaimed: string[] = [];@@ -202,8 +200,8 @@ function loadGateway(options: {disk,callRaw: (args: Record<string, unknown> = { message: 'hi' }) =>callTool.execute('call-1', { server: 'cindy_orca', tool: 'send_to_worker', args }),- // 默认模拟真实模型的两步:第一次被路标拦下 → 显式 list_tools 查完 schema → 重发。- // 只有验证拦截语义的用例用 callRaw;其他错误(如 zod 拒参)原样抛出,不在此处吞掉。+ // 默认模拟真实模型的两步:第一次被路标拦下 → 查完 schema 重发。只有验证拦截语义的用例+ // 用 callRaw;其他错误(如 zod 拒参)原样抛出,不在此处吞掉。call: async (args: Record<string, unknown> = { message: 'hi' }) => {const input = { server: 'cindy_orca', tool: 'send_to_worker', args };try {@@ -211,7 +209,6 @@ function loadGateway(options: {} catch (error) {const message = error instanceof Error ? error.message : String(error);if (!message.includes('Inspect this tool before execution')) throw error;- await listTools.execute('list-1', { server: 'cindy_orca', tool: 'send_to_worker' });return callTool.execute('call-2', input);}},@@ -220,8 +217,8 @@ function loadGateway(options: {}describe('MCP gateway schema disclosure', () => {- it('blocks the first uninspected call without touching MCP, and discloses only after list_tools', async () => {- const { gateway, callRaw, list, requests, warnings, writes, disk } = loadGateway();+ it('blocks the first uninspected call with a signpost, records the fingerprint, and lets the retry through', async () => {+ const { gateway, callRaw, requests, warnings, writes, disk } = loadGateway();const resolved = gateway.resolveCall({ server: 'cindy_orca', tool: 'send_to_worker' }) as { tool: unknown };// 事前未披露expect((gateway as unknown as { isSchemaDisclosed(c: unknown): boolean })@@ -233,16 +230,12 @@ describe('MCP gateway schema disclosure', () => {expect(first?.message).toContain('"server":"cindy_orca"');expect(first?.message).toContain('"tool":"send_to_worker"');expect(requests).toHaveLength(0);- // 门保持 fail closed:被拦的那次不记账、不落盘- expect(writes).toHaveLength(0);- expect(disk.value).toBeNull();-- // 显式查完 schema 才算披露:此时记账并落盘- await list();+ expect(warnings.some((line) => line.includes('gateway tool auto-disclosed on first call'))).toBe(true);+ // 拦的时候已经记账,因此重发时不再重复落盘expect(disk.value?.entries['cindy_orca\u0000send_to_worker']).toBe(fingerprint(TOOL));expect(writes).toHaveLength(1);- // 之后重发:放行并执行成功+ // 第二次(模型照路标查完 schema 后重发):放行并执行成功const result = await callRaw();expect(requests).toHaveLength(1);expect(result).toMatchObject({ content: [{ type: 'text', text: 'delivered' }] });@@ -265,14 +258,14 @@ describe('MCP gateway schema disclosure', () => {expect(writes).toHaveLength(0);});- it('re-arms the gate when the tool schema actually changes', async () => {+ it('re-arms the gate when the tool schema actually changes and lets the retry through', async () => {const stored: DisclosedFile = {version: 1,entries: { 'cindy_orca\u0000send_to_worker': fingerprint(TOOL) },};- const { gateway, httpClient, callRaw, list, requests, warnings, disk } = loadGateway({ stored });+ const { gateway, httpClient, callRaw, requests, warnings, disk } = loadGateway({ stored });- // 同一会话内工具描述变化(MCP 重连后拿到新 schema)→ 指纹失配 → 门重新武装+ // 同一会话内工具描述变化(MCP 重连后拿到新 schema)gateway.add('cindy_orca', httpClient, [TOOL_CHANGED]);const changed = gateway.resolveCall({ server: 'cindy_orca', tool: 'send_to_worker' }) as { tool: unknown };expect((gateway as unknown as { isSchemaDisclosed(c: unknown): boolean })@@ -282,11 +275,10 @@ describe('MCP gateway schema disclosure', () => {expect(first?.message).toContain('"tool":"send_to_worker"');expect(requests).toHaveLength(0);- // 重新查一次新 schema 才重新披露- await list();- expect(disk.value?.entries['cindy_orca\u0000send_to_worker']).toBe(fingerprint(TOOL_CHANGED));await callRaw();expect(requests).toHaveLength(1);+ expect(warnings.some((line) => line.includes('auto-disclosed on first call'))).toBe(true);+ expect(disk.value?.entries['cindy_orca\u0000send_to_worker']).toBe(fingerprint(TOOL_CHANGED));});it('merges a record another instance wrote after startup instead of overwriting it', async () => {@@ -333,6 +325,16 @@ describe('MCP gateway schema disclosure', () => {.isSchemaDisclosed(gateway.resolveCall({ server: 'cindy_orca', tool: 'send_to_worker' }))).toBe(true);});+ it('skips persisting when another instance reclaimed the stale lock first', async () => {+ // 回收必须与重新加锁互斥:rename 失败说明锁已被别人收走/重建,本实例直接放弃,+ // 不能继续 rmSync(那会删掉对方刚建的锁,两边都进写入路径互相覆盖记录)。+ const { call, requests, disk, reclaimed } = loadGateway({ lockOwner: 999, reclaimLostRace: true });+ await call();+ expect(requests).toHaveLength(1);+ expect(disk.value).toBeNull();+ expect(reclaimed.some((file) => file.endsWith('.lock') && !file.includes('.stale-'))).toBe(false);+ });+it('restores the lock and skips persisting when the reclaimed lock was actually a live one', async () => {// 两个实例同时读到死 pid:A 先回收旧锁并重建;B 的 rename 仍会成功,但掣走的是// A 的新锁(内容 777,活进程)。校验内容不一致后必须放回并放弃本次落盘,diff --git a/packages/maker-core/src/agents/pi/__tests__/pi-mcp-bridge.integration.test.ts b/packages/maker-core/src/agents/pi/__tests__/pi-mcp-bridge.integration.test.tsindex 357c43f21d..69fbf1ee82 100644--- a/packages/maker-core/src/agents/pi/__tests__/pi-mcp-bridge.integration.test.ts+++ b/packages/maker-core/src/agents/pi/__tests__/pi-mcp-bridge.integration.test.ts@@ -1460,18 +1460,20 @@ describe.skipIf(!piAvailable)('PiAgent × cindy-bridge (real pi + MCP bridge + p);it(- 'known tools cannot execute or prompt until their exact input schema has been inspected',+ 'an uninspected tool call is blocked once, then executes once on the re-send',{ timeout: 90_000 },async () => {echoCalls.length = 0;opaqueTurnCaptures.length = 0;let permissionCount = 0;+ const sessionId = 'mcp-itest-uninspected-first-call';const { permissionAsked, requestBodies } = await runOneTurn('ask',async (req) => {permissionCount += 1;expect(req.kind).toBe('permission');if (req.kind === 'permission') {+ // 首次调用即便未 inspect 也要按完整 gateway 工具身份过权限(分类只认解析成功)。expect(req.toolName).toBe('mcp__cindy_echo__echo');expect(req.input).toEqual({ text: 'hello-pi' });}@@ -1479,17 +1481,25 @@ describe.skipIf(!piAvailable)('PiAgent × cindy-bridge (real pi + MCP bridge + p},'local','call without schema inspection',- // 披露记录按会话落盘:给独立会话,才走得到「首次未披露」。+ // localHostOnly 占位:本用例只要会话隔离,不要 local host 工具配置。false,- 'mcp-itest-uninspected-first-call',+ sessionId,);expect(permissionAsked).toBe(true);+ // 剧本:首次盲调在权限询问**之前**就被披露门拦下(不弹权限框、不执行工具,只回+ // 一条指名路标的错误),模型照路标补 list_tools 后重发;重发时已披露,正常过一次+ // 权限门才真正落到 MCP。expect(permissionCount).toBe(1);expect(echoCalls).toEqual([{ text: 'hello-pi' }]);- expect(requestBodies[1]).toContain('Inspect this tool before execution');- expect(requestBodies[2]).toContain('inputSchema');- await waitFor(() => opaqueTurnCaptures.length === 1);+ expect(requestBodies.some((body) => body.includes('Inspect this tool before execution'))).toBe(true);+ // 披露记录已按当前 schema 写入,模型随后补的 list_tools 仍返回 schema。+ expect(requestBodies.some((body) => body.includes('inputSchema'))).toBe(true);+ await waitFor(() => opaqueTurnCaptures.length >= 1);+ expect(opaqueTurnCaptures[0]).toMatchObject({+ sessionId,+ provider: 'pi',+ });},);diff --git a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts b/packages/maker-core/src/agents/pi/cindy-bridge-source.tsindex 5064ce4e1a..8d17b2519e 100644--- a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts+++ b/packages/maker-core/src/agents/pi/cindy-bridge-source.ts@@ -3189,6 +3189,16 @@ class CindyMcpGateway {};}+ /**+ * 未披露时的回执(路标):指名该查哪个 server/tool,并说明重发即可放行。+ * tool_call hook 与 executeCall 共用同一段文本,避免两处漂移。+ */+ private disclosureSignpost(call: ResolvedMcpGatewayCall): string {+ return 'Inspect this tool before execution by calling cindy_mcp_list_tools with '+ + JSON.stringify({ server: call.tool.serverName, tool: call.tool.name })+ + '. The current schema has already been recorded; re-send the same call to proceed.';+ }+isSchemaDisclosed(call: ResolvedMcpGatewayCall): boolean {const key = mcpGatewayKey(call.tool.serverName, call.tool.name);return this.disclosedSchemas.get(key) === this.schemaFingerprint(call.tool);@@ -3389,10 +3399,25 @@ class CindyMcpGateway {);}if (!this.isSchemaDisclosed(resolved)) {- throw new Error(- 'Inspect this tool before execution by calling cindy_mcp_list_tools with ' +- JSON.stringify({ server: resolved.tool.serverName, tool: resolved.tool.name }) + '.',+ // 拦一次,把路标递到模型手上,同时记账。+ //+ // 记账解决的是披露整片失效:按 schema 指纹记账后,只有真正新增或 schema 真变动+ // 的工具才拦,同一工具的第二次调用直接放行。+ //+ // 拦这一次的理由是零拦截实测出来的代价(2026-10-15):模型没有任何信号知道+ // 该去查 schema,参数名和信封层级只能靠服务端报错反推——实测把 target_session_id+ // 猜成 worker_id、把 args 里的字段平铺到调用根,连续撞 -32602 后才放弃。回执里+ // 指名 server/tool,模型才会去 list_tools。+ //+ // 拦时即记账,模型照路标重发即放行。放行的语义是「这个工具的 schema 我见过了」,+ // 不是「这组参数是对的」:参数仍由工具自身 inputSchema 校验。+ this.markSchemaDisclosed(resolved);+ console.warn(+ '[cindy-bridge] gateway tool auto-disclosed on first call: '+ + resolved.tool.serverName + '/' + resolved.tool.name+ + '; signposting inspection instead of staying silent',);+ throw new Error(this.disclosureSignpost(resolved));}return this.executeResolvedCall(resolved, signal);}@@ -4669,22 +4694,26 @@ export default async function cindyBridge(piApi: any) {: event.toolName === CINDY_BOT_MEMORY_TOOL? mcpGateway.resolveBotMemory(event.input): null;- const gatewayCall = resolvedGatewayCall && mcpGateway.isSchemaDisclosed(resolvedGatewayCall)- ? resolvedGatewayCall- : CINDY_DIRECT_BOT_TOOLS.has(event.toolName)- ? resolvedGatewayCall- : event.toolName === CINDY_BOT_MEMORY_TOOL- ? resolvedGatewayCall- : null;- // Invalid, unknown, or not-yet-inspected gateway input cannot execute a- // capability. Let execute() return its deterministic discovery/schema error- // without showing a misleading permission prompt for the wrapper itself.+ // 分类只认「解析成功」:披露状态不参与权限命名与采集分类,否则被门拦下的那次+ // 会被当成非 gateway 调用,权限命名与采集都会漏掉这一条。+ const gatewayCall = resolvedGatewayCall;+ // Invalid or unknown gateway input cannot execute a capability. Let execute()+ // return its deterministic discovery/schema error without showing a misleading+ // permission prompt for the wrapper itself.if ((event.toolName === CINDY_MCP_CALL_TOOL|| CINDY_DIRECT_BOT_TOOLS.has(event.toolName)|| event.toolName === CINDY_BOT_MEMORY_TOOL)&& !gatewayCall) return;+ // 披露门必须判在**发起权限询问之前**:pi 的权限询问由本 hook 发起,若等到工具实现+ // 里才拦,这次弹框已经发生了 —— 被门拦下的一次也打扰用户,与 pi-harness 记载的+ // 「未检查 schema 的调用在 bridge 内 fail closed,不会触达 MCP 或弹权限框」相悖。+ // 未披露的首次调用在这里直接放行给 execute(execute 的门会记账并回路标),不弹框;+ // 模型照路标补完 list_tools 后重发时已披露,才正常过一次权限。+ if (event.toolName === CINDY_MCP_CALL_TOOL && gatewayCall && !mcpGateway.isSchemaDisclosed(gatewayCall)) {+ return;+ }const permissionToolName = gatewayCall?.qualifiedName ?? event.toolName;const permissionInput = gatewayCall?.args ?? event.input ?? {};let decision: string | undefined;@@ -4757,13 +4786,9 @@ export default async function cindyBridge(piApi: any) {: event.toolName === CINDY_BOT_MEMORY_TOOL? mcpGateway.resolveBotMemory(event.input): null;- const gatewayCall = resolvedGatewayCall && mcpGateway.isSchemaDisclosed(resolvedGatewayCall)- ? resolvedGatewayCall- : CINDY_DIRECT_BOT_TOOLS.has(event.toolName)- ? resolvedGatewayCall- : event.toolName === CINDY_BOT_MEMORY_TOOL- ? resolvedGatewayCall- : null;+ // 分类只认「解析成功」:自愈放行的首次调用发生在记账之前,若在这里按披露状态+ // 判定,它会被当成非 gateway 调用,权限命名与采集都会漏掉这一条。+ const gatewayCall = resolvedGatewayCall;const captureToolName = gatewayCall?.qualifiedName ?? event.toolName;const captureInput = gatewayCall?.args ?? event.input ?? {};if (!isCindyShellTool(captureToolName) && !String(captureToolName ?? '').startsWith('mcp__')) return;