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。

16.0 KB
Raw Blame
/**
 * 设备托管会话(StartSessionOptions.deviceHosted)的共用部分:Agent 在本机运行,任务、项目
 * 文件与命令在同账号另一台电脑上,工具经本机 loopback 隧道回到那台电脑执行。
 */
import { realpathSync } from 'node:fs';
import path from 'node:path';

import type { DeviceHostedLinkActivity, DeviceHostedSession, PiExtraSpawnConfig } from '../base-agent.js';

/** 交给 Pi 内 cindy-bridge 的托管配置(隧道地址、令牌、Agent 主机上的工作目录)。 */
export const DEVICE_HOSTED_PI_ENV = 'CINDY_PI_HOSTED';

/**
 * 链路往来写成一句诊断,附在托管会话关键 RPC 的超时错误里:分得清「请求一直在走、只是链路慢」
 * (回复数在涨、往返耗时长)、「某个请求卡住」(最早未回复的请求等了很久)与「链路上根本没有往来」。
 */
export function describeDeviceHostedLinkActivity(activity: DeviceHostedLinkActivity, now = Date.now()): string {
  const seconds = (ms: number) => `${(ms / 1000).toFixed(1)}s`;
  const parts = [`execution environment answered ${activity.execResponses}/${activity.execRequests} requests`];
  if (activity.execOldestPending) {
    parts.push(`oldest unanswered ${activity.execOldestPending.method} waiting ${seconds(activity.execOldestPending.waitedMs)}`);
  }
  if (activity.execRoundTripAvgMs !== undefined && activity.execRoundTripMaxMs !== undefined) {
    parts.push(`round trip avg ${seconds(activity.execRoundTripAvgMs)} max ${seconds(activity.execRoundTripMaxMs)}`);
  }
  parts.push(`peak in flight ${activity.execMaxInFlight}`);
  if (activity.httpInFlight > 0) parts.push(`${activity.httpInFlight} tool requests in flight`);
  parts.push(activity.lastActivityAt === null
    ? 'no link activity yet'
    : `last link activity ${seconds(Math.max(0, now - activity.lastActivityAt))} ago`);
  return parts.join(', ');
}

/**
 * 去掉结尾的斜杠。不用正则:`x+$` 这类模式在不可控输入上是多项式回溯(CodeQL
 * “Polynomial regular expression used on uncontrolled data”)。
 */
export function stripTrailingSlashes(url: string): string {
  let end = url.length;
  while (end > 0 && url.charCodeAt(end - 1) === 47) end -= 1;
  return url.slice(0, end);
}

export function deviceHostedPiEnvValue(hosted: DeviceHostedSession): string {
  return JSON.stringify({
    url: hosted.tunnelUrl,
    token: hosted.tunnelToken,
    cwd: hosted.workingDir,
    platform: hosted.platform,
    shell: hosted.shell,
    ...(hosted.mirrorRoot ? { mirrorRoot: hosted.mirrorRoot } : {}),
    // 受邀者会话:Pi 子代理据此同样不读本机的说明文件与技能。同账号的值保持原样。
    ...(hosted.guest ? { guest: true } : {}),
  });
}

/**
 * 受邀者会话自己的目录:虚拟工作区根的上一级(会话目录,里面是受邀者带来的项目与个人说明);
 * 旧协议没有虚拟工作区时就是本机影子目录。这一级之上属于本机用户。
 */
export function deviceHostedGuestSessionRoot(hosted: DeviceHostedSession, localWorkingDir: string): string {
  return hosted.mirrorRoot ? path.dirname(path.resolve(hosted.mirrorRoot)) : path.resolve(localWorkingDir);
}

/**
 * target 是否在 root 之内(含 root 本身)。同时按原路径与真实路径比较(符号链接、macOS 的
 * /var → /private/var);Windows 不区分大小写。
 */
export function isInsideDeviceHostedRoot(target: string, root: string, platform: NodeJS.Platform = process.platform): boolean {
  const variants = (value: string): string[] => {
    const resolved = path.resolve(value);
    let real = resolved;
    try {
      real = realpathSync.native(resolved);
    } catch {
      /* 不存在的路径按原样比较 */
    }
    return [...new Set([resolved, real])].map((item) => (platform === 'win32' ? item.toLowerCase() : item));
  };
  const roots = variants(root);
  return variants(target).some((candidate) => roots.some((base) => {
    const relative = path.relative(base, candidate);
    return relative === ''
      || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
  }));
}

/**
 * 受邀者(另一个账号)的会话:Claude Code 会沿工作目录逐级向上加载 CLAUDE.md 与规则文件,
 * 会话目录(虚拟工作区根的上一级)之外的那几级属于本机用户,例如家目录里的 CLAUDE.md,
 * 一律排除。同时给出 `/` 分隔与本机分隔两种写法(Claude Code 用 picomatch 匹配绝对路径)。
 */
export function deviceHostedGuestClaudeMdExcludes(hosted: DeviceHostedSession): string[] {
  if (!hosted.guest || !hosted.mirrorRoot) return [];
  const sessionRoot = path.dirname(path.resolve(hosted.mirrorRoot));
  const slash = (value: string) => value.split(path.sep).join('/');
  const out = new Set<string>();
  for (let dir = path.dirname(sessionRoot); ; dir = path.dirname(dir)) {
    for (const file of [path.join(dir, 'CLAUDE.md'), path.join(dir, 'CLAUDE.local.md'), path.join(dir, '.claude', 'CLAUDE.md')]) {
      out.add(slash(file));
      out.add(file);
    }
    out.add(`${slash(path.join(dir, '.claude', 'rules'))}/**`);
    if (path.dirname(dir) === dir) break;
  }
  return [...out];
}

/** 隧道上某个 MCP 服务的地址。 */
export function deviceHostedMcpUrl(hosted: DeviceHostedSession, name: string): string {
  return `${stripTrailingSlashes(hosted.tunnelUrl)}/mcp/${encodeURIComponent(name)}`;
}

/** Pi 的 MCP 桥配置:全部指向隧道,令牌是本任务的隧道令牌。 */
export function deviceHostedPiMcpBridge(hosted: DeviceHostedSession): NonNullable<PiExtraSpawnConfig['mcpBridge']> {
  return {
    token: hosted.tunnelToken,
    servers: hosted.mcpServers.map((name) => ({ name, url: deviceHostedMcpUrl(hosted, name) })),
  };
}

/** 设备托管时顶替 Claude Code 自带文件与命令工具的 Cindy MCP 服务名。 */
export const DEVICE_HOSTED_EXEC_MCP_SERVER = 'cindy_exec';
/** 顶替的工具名(与自带工具同名)。 */
export const DEVICE_HOSTED_EXEC_TOOL_NAMES = ['Bash', 'BashOutput', 'KillShell', 'Read', 'Write', 'Edit', 'NotebookEdit'] as const;
/**
 * 只在受邀者会话里由任务所在电脑提供的顶替工具:自带的 WebFetch 对受邀者关闭,改在受邀者电脑上
 * 抓取。受邀者电脑上的 Cindy 较旧时不提供,所以不写进给模型的说明,只用于权限按自带工具判定。
 */
export const DEVICE_HOSTED_GUEST_EXEC_TOOL_NAMES = ['WebFetch'] as const;
/** 设备托管时关掉的 Claude Code 自带工具:它们只能操作本机,项目不在这里。 */
export const DEVICE_HOSTED_DISALLOWED_CLAUDE_TOOLS = [
  'Bash', 'BashOutput', 'KillShell', 'Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit',
  'Glob', 'Grep', 'LS', 'PowerShell', 'EnterWorktree', 'ExitWorktree',
] as const;

/**
 * 受邀者(供应商分享的另一个账号)会话可用的 Claude Code 自带工具,经 SDK `tools` 交给
 * Claude Code:名单之外的自带工具在会话里根本不存在,Claude Code 升级新增的工具也不会自动
 * 开放给受邀者。Agent 程序以本机用户的身份在本机运行,其余自带工具都直接作用于本机或本机
 * 用户:其他会话(ListAgents / SendMessage)、本机用户的 claude.ai 账号(Artifact、
 * RemoteTrigger、DesignSync 等)、本机文件与命令(Monitor、SendUserFile 等)、本机网络(WebFetch)。
 * 文件、命令与 WebFetch 由 cindy_exec 回到受邀者电脑执行(MCP 工具不受 `tools` 限制)。
 */
export const DEVICE_HOSTED_GUEST_CLAUDE_TOOLS = [
  // 子代理。隔离选项另由 deviceHostedGuestAgentDenial 拦下。
  'Agent',
  // 只作用于会话自身:提问、计划模式、待办与后台任务、延迟加载的工具、技能、结果卡片、定时唤醒。
  'AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode',
  'TodoWrite', 'TaskCreate', 'TaskGet', 'TaskList', 'TaskUpdate', 'TaskStop', 'TaskOutput',
  'ToolSearch', 'Skill', 'ReportFindings', 'ScheduleWakeup', 'CronCreate', 'CronDelete', 'CronList',
  // 只连本会话配置的 MCP 服务,设备托管时都经隧道回到受邀者电脑。
  'ListMcpResourcesTool', 'ReadMcpResourceTool',
  // 由模型服务方执行,不经本机网络。
  'WebSearch',
] as const;

/**
 * 受邀者会话里子代理的隔离选项:worktree 在本机建 git worktree,remote 用本机用户的 claude.ai
 * 账号开云端任务,都不允许。返回拒绝原因;其他调用返回 null。
 */
export function deviceHostedGuestAgentDenial(toolName: string, input: unknown): string | null {
  if (toolName !== 'Agent' && toolName !== 'Task') return null;
  const isolation = input && typeof input === 'object' ? (input as { isolation?: unknown }).isolation : undefined;
  if (isolation === undefined || isolation === null) return null;
  return 'Subagent isolation is not available in this task. Start the subagent without the isolation option.';
}

const EXEC_PREFIX = `mcp__${DEVICE_HOSTED_EXEC_MCP_SERVER}__`;

/** `mcp__cindy_exec__Bash` → `Bash`;不是顶替工具时返回 null。 */
export function deviceHostedBuiltinToolName(toolName: string): string | null {
  if (!toolName.startsWith(EXEC_PREFIX)) return null;
  const name = toolName.slice(EXEC_PREFIX.length);
  return (DEVICE_HOSTED_EXEC_TOOL_NAMES as readonly string[]).includes(name)
    || (DEVICE_HOSTED_GUEST_EXEC_TOOL_NAMES as readonly string[]).includes(name)
    ? name
    : null;
}

/** `Bash` → `mcp__cindy_exec__Bash`。 */
export function deviceHostedExecToolName(builtin: string): string {
  return `${EXEC_PREFIX}${builtin}`;
}

/**
 * 给模型的环境说明:模型只看到 Agent 主机上的虚拟工作区路径;执行端平台与 shell 保留真实值。
 */
export function deviceHostedEnvironmentNote(hosted: DeviceHostedSession, _localWorkingDir: string): string {
  const lines = [
    '# Workspace',
    `The current workspace is \`${hosted.workingDir}\` (${hosted.platform}, shell: ${hosted.shell}${hosted.osVersion ? `, ${hosted.osVersion}` : ''}).`,
    `File and shell tools operate in this workspace. Use paths under \`${hosted.workingDir}\`; relative paths resolve against it.`,
  ];
  if (hosted.extraDirs.length || hosted.writableDirs.length) {
    lines.push(`Additional workspace directories: ${[...new Set([...hosted.extraDirs, ...hosted.writableDirs])].map((dir) => `\`${dir}\``).join(', ')}.`);
  }
  lines.push(`Is a git repository: ${hosted.isGitRepo ? 'yes' : 'no'}.`);
  if (hosted.personalInstructions?.trim()) {
    lines.push('', "# The user's personal instructions", hosted.personalInstructions.trim());
  }
  return lines.join('\n');
}

/** Claude Code 版:说明文件与命令工具由 Cindy 工具顶替。 */
export function deviceHostedClaudeNote(hosted: DeviceHostedSession, localWorkingDir: string): string {
  const tools = DEVICE_HOSTED_EXEC_TOOL_NAMES.map((name) => deviceHostedExecToolName(name)).join(', ');
  return [
    deviceHostedEnvironmentNote(hosted, localWorkingDir),
    `File and shell tools are provided as ${tools}. Use them wherever these instructions mention Bash, Read, Write, Edit or NotebookEdit; search files with Bash (rg, find).`,
  ].join('\n');
}

/**
 * 子代理的工具限制(设备托管)。本机任务里 Claude Code 按子代理定义收窄自带工具;顶替成 Cindy
 * 工具后 SDK 不再按名字收窄(MCP 工具一律放行),这里按同样的定义判一次:
 *  - 自带的只读子代理(Explore / Plan)不能写文件;
 *  - 自定义子代理写了 tools 时只能用列出的工具,写了 disallowedTools 时不能用列出的工具;
 *  - 参数化条目(如 `Bash(git diff:*)`)只覆盖范围内的调用:必须按本次 `input.command` 判定,
 *    不能当成整个工具的放行 —— 否则被 MCP 顶替后子代理可执行任意命令,与本机不一致。
 * 不认识的子代理不额外限制(与本机一致:没有定义就继承全部工具)。
 */
export interface DeviceHostedAgentToolRule {
  tools?: string[];
  disallowedTools?: string[];
}

/** 本次顶替工具调用的参数(参数化工具规则按它收窄范围)。 */
export interface DeviceHostedToolCall {
  /** Bash 本次执行的命令;没有命令(BashOutput / KillShell 或拿不到参数)时缺省。 */
  command?: string;
}

const READ_ONLY_BUILTIN_AGENTS: Record<string, DeviceHostedAgentToolRule> = {
  Explore: { disallowedTools: ['Write', 'Edit', 'NotebookEdit'] },
  Plan: { disallowedTools: ['Write', 'Edit', 'NotebookEdit'] },
};

/** 子代理定义文件(Markdown + frontmatter)里的名字与工具规则;没有 frontmatter 时返回 null。 */
export function parseClaudeAgentToolRule(markdown: string): { name: string; rule: DeviceHostedAgentToolRule } | null {
  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
  if (!match) return null;
  const fields = new Map<string, string>();
  for (const line of match[1].split(/\r?\n/)) {
    const field = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line);
    if (field) fields.set(field[1], field[2].trim());
  }
  const name = fields.get('name')?.replace(/^["']|["']$/g, '');
  if (!name) return null;
  const list = (value: string | undefined) => value
    ?.replace(/^\[|\]$/g, '')
    .split(',')
    .map((item) => item.trim().replace(/^["']|["']$/g, ''))
    .filter(Boolean);
  const tools = list(fields.get('tools'));
  const disallowedTools = list(fields.get('disallowedTools') ?? fields.get('disallowed-tools'));
  return {
    name,
    rule: {
      ...(tools && tools.length ? { tools } : {}),
      ...(disallowedTools && disallowedTools.length ? { disallowedTools } : {}),
    },
  };
}

/** 子代理能否用某个顶替工具(自带工具名)。BashOutput / KillShell 跟随 Bash 的非参数化条目。 */
export function deviceHostedSubagentAllows(
  agentType: string,
  builtin: string,
  customRules: ReadonlyMap<string, DeviceHostedAgentToolRule>,
  call?: DeviceHostedToolCall,
): boolean {
  const rule = customRules.get(agentType) ?? READ_ONLY_BUILTIN_AGENTS[agentType];
  if (!rule) return true;
  const name = builtin === 'BashOutput' || builtin === 'KillShell' ? 'Bash' : builtin;
  const coversTool = (tool: string) => tool === name || tool === builtin || tool === deviceHostedExecToolName(builtin);
  /** 参数化条目只约束 Bash 命令本身;BashOutput / KillShell 不执行命令,不被它覆盖。 */
  const entryCovers = (entry: string, side: 'allow' | 'deny'): boolean => {
    const split = splitToolEntry(entry);
    if (!coversTool(split.tool)) return false;
    if (split.scope === null) return true;
    if (builtin !== 'Bash') return false;
    const verdict = toolScopeVerdict(split.scope, call);
    // allow 侧只有证明确在范围内才放行;deny 侧拿不准就拦(fail-closed)。
    return side === 'allow' ? verdict === 'match' : verdict !== 'no-match';
  };
  if (rule.disallowedTools?.some((entry) => entryCovers(entry, 'deny'))) return false;
  if (rule.tools && !rule.tools.some((entry) => entry === '*' || entryCovers(entry, 'allow'))) return false;
  return true;
}

/** `Bash(git diff:*)` → 工具名 `Bash` + 参数范围 `git diff:*`;不是参数化条目时 scope 为 null。 */
function splitToolEntry(entry: string): { tool: string; scope: string | null } {
  const open = entry.indexOf('(');
  if (open <= 0 || !entry.endsWith(')')) return { tool: entry, scope: null };
  return { tool: entry.slice(0, open), scope: entry.slice(open + 1, -1) };
}

type ScopeVerdict = 'match' | 'no-match' | 'unknown';

/**
 * 参数化条目的范围与本次命令的匹配:`:*` 结尾按前缀匹配(与 Claude Code 同语义的保守
 * 实现),其余整串精确匹配。范围为空、含不移植的通配符或拿不到本次命令时返回 unknown,
 * 由调用方按 allow / deny 侧各自的安全方向解释。
 */
function toolScopeVerdict(scope: string, call: DeviceHostedToolCall | undefined): ScopeVerdict {
  const spec = scope.trim();
  const command = call?.command?.trim();
  if (!spec || !command) return 'unknown';
  if (spec.endsWith(':*')) {
    const prefix = spec.slice(0, -2).trim();
    if (!prefix) return 'unknown';
    return command === prefix || command.startsWith(prefix) ? 'match' : 'no-match';
  }
  if (/[?*[\]{}]/.test(spec)) return 'unknown';
  return command === spec ? 'match' : 'no-match';
}