Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(pi): 披露门自愈一次(拦一次 + 递路标 + 记账)并把判定移到权限询问之前

Zhang Yunjinb5266dc8d606
diff --git a/docs/dev-rules/pi-harness.md b/docs/dev-rules/pi-harness.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;