@zhin.js/agent 0.0.18 → 0.0.19

package/src/file-policy.ts

@@ -4,15 +4,61 @@
  * 防止 AI Agent 读写敏感文件（如 .env、密钥、证书等），
  * 并将 bash/grep/glob 等工具的命令注入风险降到最低。
  *
- * 三层防御:
- *  1. 敏感文件名/路径模式 — 阻止 .env、私钥、证书等
- *  2. 敏感目录 — 阻止 .ssh, .gnupg 等
- *  3. bash 环境变量泄漏 — 过滤 env/printenv/export 输出中的敏感值
+ * 四层防御:
+ *  1. 设备路径阻止 — 阻止 /dev/zero, /dev/stdin 等挂起进程的设备文件
+ *  2. 敏感文件名/路径模式 — 阻止 .env、私钥、证书等
+ *  3. 敏感目录 — 阻止 .ssh, .gnupg 等
+ *  4. bash 安全分类 — 环境变量泄漏 + 命令读写分类
  */
 
 import * as path from 'path';
 import * as os from 'os';
 
+// ── 设备路径阻止（参考 Claude Code FileReadTool BLOCKED_DEVICE_PATHS）──
+
+/**
+ * 会导致进程挂起的设备文件路径。
+ * 检查纯路径即可（无 I/O），安全设备如 /dev/null 不在此列。
+ */
+const BLOCKED_DEVICE_PATHS: ReadonlySet<string> = new Set([
+  // 无限输出 — 永远无法 EOF
+  '/dev/zero',
+  '/dev/random',
+  '/dev/urandom',
+  '/dev/full',
+  // 阻塞等待输入
+  '/dev/stdin',
+  '/dev/tty',
+  '/dev/console',
+  // 对读取无意义
+  '/dev/stdout',
+  '/dev/stderr',
+  // stdio fd 别名
+  '/dev/fd/0',
+  '/dev/fd/1',
+  '/dev/fd/2',
+]);
+
+/**
+ * 检测路径是否为被阻止的设备文件（含 Linux /proc/ fd 别名）。
+ */
+export function isBlockedDevicePath(filePath: string): boolean {
+  if (BLOCKED_DEVICE_PATHS.has(filePath)) return true;
+  // /proc/self/fd/0-2 和 /proc/<pid>/fd/0-2 是 Linux 的 stdio 别名
+  if (
+    filePath.startsWith('/proc/') &&
+    (filePath.endsWith('/fd/0') || filePath.endsWith('/fd/1') || filePath.endsWith('/fd/2'))
+  ) return true;
+  return false;
+}
+
+// ── 文件大小限制（参考 Claude Code FileEditTool MAX_EDIT_FILE_SIZE）──
+
+/** 读取文件最大字节数（256 MiB），防止 OOM */
+export const MAX_READ_FILE_SIZE = 256 * 1024 * 1024;
+/** 编辑文件最大字节数（1 GiB），防止 V8 字符串长度溢出 */
+export const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024;
+
 // ── 敏感文件名模式 ──────────────────────────────────────────────────
 
 /**
@@ -174,6 +220,108 @@ export function checkBashCommandSafety(command: string): { safe: boolean; reason
   return { safe: true };
 }
 
+// ── bash 命令读写分类（参考 Claude Code BashTool isSearchOrReadBashCommand）──
+
+/** 搜索类命令 */
+const BASH_SEARCH_COMMANDS: ReadonlySet<string> = new Set([
+  'find', 'grep', 'rg', 'ag', 'ack', 'locate', 'which', 'whereis',
+]);
+
+/** 读取/查看类命令 */
+const BASH_READ_COMMANDS: ReadonlySet<string> = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'wc', 'stat', 'file', 'strings',
+  'jq', 'awk', 'cut', 'sort', 'uniq', 'tr',
+]);
+
+/** 目录列出类命令 */
+const BASH_LIST_COMMANDS: ReadonlySet<string> = new Set([
+  'ls', 'tree', 'du',
+]);
+
+/** 语义中性命令 — 纯输出/状态命令，不影响管道是否只读 */
+const BASH_NEUTRAL_COMMANDS: ReadonlySet<string> = new Set([
+  'echo', 'printf', 'true', 'false', ':',
+]);
+
+export interface BashCommandClassification {
+  /** 是否为搜索命令 */
+  isSearch: boolean;
+  /** 是否为读取命令 */
+  isRead: boolean;
+  /** 是否为列出命令 */
+  isList: boolean;
+  /** 综合判断：命令是否只读（搜索/读取/列出） */
+  isReadOnly: boolean;
+}
+
+/**
+ * 对 bash 命令进行读/写分类。
+ *
+ * 对管道命令（如 `cat file | grep pattern`），所有非中性部分
+ * 都必须是搜索/读/列出类，整条命令才算只读。
+ *
+ * 参考 Claude Code BashTool `isSearchOrReadBashCommand`。
+ */
+export function classifyBashCommand(command: string): BashCommandClassification {
+  const trimmed = command.trim();
+  // 按管道和操作符拆分
+  const parts = trimmed.split(/\s*(?:\|\||&&|\||;)\s*/);
+
+  let hasSearch = false;
+  let hasRead = false;
+  let hasList = false;
+  let hasNonNeutral = false;
+
+  for (const part of parts) {
+    const baseCmd = part.trim().split(/\s+/)[0];
+    if (!baseCmd) continue;
+
+    // 跳过中性命令
+    if (BASH_NEUTRAL_COMMANDS.has(baseCmd)) continue;
+
+    hasNonNeutral = true;
+    if (BASH_SEARCH_COMMANDS.has(baseCmd)) hasSearch = true;
+    else if (BASH_READ_COMMANDS.has(baseCmd)) hasRead = true;
+    else if (BASH_LIST_COMMANDS.has(baseCmd)) hasList = true;
+    else {
+      // 包含非只读命令 → 整条命令不是只读
+      return { isSearch: false, isRead: false, isList: false, isReadOnly: false };
+    }
+  }
+
+  // 全部中性命令（如 echo "hi"）— 视为只读
+  if (!hasNonNeutral) {
+    return { isSearch: false, isRead: false, isList: false, isReadOnly: true };
+  }
+
+  return {
+    isSearch: hasSearch,
+    isRead: hasRead,
+    isList: hasList,
+    isReadOnly: hasSearch || hasRead || hasList,
+  };
+}
+
+// ── 文件 mtime 比对（参考 Claude Code FileEditTool stale detection）──
+
+/**
+ * 文件修改时间快照，用于检测编辑前是否被并发修改。
+ */
+export async function getFileMtime(filePath: string): Promise<number> {
+  const { default: fsPromises } = await import('fs/promises');
+  const stat = await fsPromises.stat(filePath);
+  return stat.mtimeMs;
+}
+
+/**
+ * 检查文件在读取后是否被修改。
+ * @returns true 表示文件已被修改（stale），应中止编辑
+ */
+export function isFileStale(savedMtime: number, currentMtime: number): boolean {
+  // 允许 1ms 的精度误差
+  return Math.abs(currentMtime - savedMtime) > 1;
+}
+
 // ── 命令参数转义 ────────────────────────────────────────────────────
 
 /**

package/src/index.ts

@@ -40,7 +40,11 @@ export { ZhinAgent } from './zhin-agent/index.js';
 export type { ZhinAgentConfig, OnChunkCallback } from './zhin-agent/index.js';
 
 export { PERM_MAP, DEFAULT_CONFIG as ZHIN_AGENT_DEFAULT_CONFIG, SECTION_SEP } from './zhin-agent/config.js';
-export { checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS } from './zhin-agent/exec-policy.js';
+export {
+  checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS,
+  isDangerousCommand, stripEnvVarPrefix, stripSafeWrappers, splitCompoundCommand, extractCommandName,
+  type ExecPolicyResult,
+} from './zhin-agent/exec-policy.js';
 export { collectRelevantTools, toAgentTool } from './zhin-agent/tool-collector.js';
 export { buildRichSystemPrompt, buildContextHint, buildEnhancedPersona, buildUserMessageWithHistory, contentToText } from './zhin-agent/prompt.js';
 export type { RichSystemPromptContext } from './zhin-agent/prompt.js';

package/src/init/create-zhin-agent.ts

@@ -50,6 +50,7 @@ export function createZhinAgentContext(refs: AIServiceRefs): void {
       const modelName = provider.models[0] || '';
       const fullConfig = { ...DEFAULT_CONFIG, ...agentConfig } as Required<import('../zhin-agent/config.js').ZhinAgentConfig>;
       const zhinTools = createBuiltinTools({
+        plugin,
         skillInstructionMaxChars: resolveSkillInstructionMaxChars(fullConfig, modelName),
         pluginSkillRootsResolver: () => collectPluginSkillSearchRoots(root),
       });

package/src/init/register-builtin-tools.ts

@@ -29,6 +29,7 @@ export function registerBuiltinTools(refs: AIServiceRefs): void {
     const fullCfg = { ...DEFAULT_CONFIG, ...agentCfg } as Required<import('../zhin-agent/config.js').ZhinAgentConfig>;
     const modelName = provider.models[0] || '';
     const builtinTools = createBuiltinTools({
+      plugin,
       skillInstructionMaxChars: resolveSkillInstructionMaxChars(fullCfg, modelName),
       pluginSkillRootsResolver: () => collectPluginSkillSearchRoots(root),
       skillFileLookup: (name: string) => {

package/src/zhin-agent/config.ts

@@ -94,7 +94,7 @@ export interface ZhinAgentConfig {
 }
 
 export const DEFAULT_CONFIG: Required<ZhinAgentConfig> = {
-  persona: 'You are a helpful AI assistant. You can use tools to help the user. Reply in the language specified in [User profile] (key: language or preferred_language), or in the same language as the user\'s message if not set.',
+  persona: 'You are Zhin, an intelligent IM bot assistant that helps users with tasks through conversation. Use tools available to you to assist the user. You are running inside the Zhin.js framework.',
   maxIterations: 5,
   timeout: 60_000,
   preExecTimeout: 10_000,

package/src/zhin-agent/exec-policy.ts

@@ -1,15 +1,24 @@
 /**
  * ZhinAgent 执行策略 — bash 命令的安全检查与工具包装
+ *
+ * 参考 Claude Code bashPermissions.ts 的纵深防御策略：
+ *   1. 危险命令黑名单  — 即使 full 模式也阻止解释器/提权命令
+ *   2. 环境变量前缀剥离 — `FOO=bar cmd` → 按 `cmd` 做白名单匹配
+ *   3. Safe wrapper 剥离 — `timeout 10 cmd` → 按 `cmd` 做匹配
+ *   4. 复合命令拆分   — `&&` `||` `;` 逐段独立检查，deny 优先
+ *   5. 只读命令自动放行 — 与 file-policy classifyBashCommand 集成
+ *   6. ask_user 集成  — execAsk=true 时返回需审批标记（而非无法交互的抛错）
  */
 
 import type { AgentTool } from '@zhin.js/core';
 import type { ZhinAgentConfig } from './config.js';
+import { classifyBashCommand } from '../file-policy.js';
 
 // ── 预设命令白名单 ──────────────────────────────────────────────────
 
-const PRESET_READONLY = ['ls', 'cat', 'pwd', 'date', 'whoami', 'grep', 'find', 'head', 'tail', 'wc'];
-const PRESET_NETWORK = [...PRESET_READONLY, 'curl', 'wget', 'ping', 'dig'];
-const PRESET_DEVELOPMENT = [...PRESET_NETWORK, 'npm', 'npx', 'node', 'git', 'gh', 'python', 'python3', 'pip', 'pnpm', 'yarn'];
+const PRESET_READONLY = ['ls', 'cat', 'pwd', 'date', 'whoami', 'grep', 'find', 'head', 'tail', 'wc', 'stat', 'file'];
+const PRESET_NETWORK = [...PRESET_READONLY, 'curl', 'wget', 'ping', 'dig', 'nslookup', 'host'];
+const PRESET_DEVELOPMENT = [...PRESET_NETWORK, 'npm', 'npx', 'node', 'git', 'gh', 'python', 'python3', 'pip', 'pnpm', 'yarn', 'tsc', 'bun'];
 
 export const EXEC_PRESETS: Record<string, string[]> = {
   readonly: PRESET_READONLY,
@@ -17,6 +26,122 @@ export const EXEC_PRESETS: Record<string, string[]> = {
   development: PRESET_DEVELOPMENT,
 };
 
+// ── 危险命令黑名单（参考 Claude Code DANGEROUS_COMMANDS）──────────────
+
+/**
+ * 即使在 full 模式下也会被阻止的危险命令。
+ * 这些命令可以执行任意代码、提权或造成不可逆破坏。
+ */
+const DANGEROUS_COMMANDS: ReadonlySet<string> = new Set([
+  // 提权
+  'sudo', 'su', 'doas',
+  // Shell 元命令 — 可执行任意代码
+  'eval', 'exec',
+  // 系统级破坏
+  'dd', 'mkfs', 'fdisk', 'parted',
+  // 进程注入
+  'gdb', 'strace', 'ltrace', 'ptrace',
+  // 环境注入（敏感变量可被设置）
+  'export',
+]);
+
+/**
+ * 检查命令是否在危险黑名单中。
+ */
+export function isDangerousCommand(cmdName: string): boolean {
+  return DANGEROUS_COMMANDS.has(cmdName);
+}
+
+// ── 环境变量前缀剥离（参考 Claude Code stripEnvVars）──────────────
+
+/**
+ * 剥离命令前面的 `KEY=value` 环境变量前缀。
+ * 例如 `FOO=bar BAZ=1 curl http://...` → `curl http://...`
+ *
+ * 只剥离安全的 key=value 对，不剥离含特殊字符的值（可能是注入）。
+ */
+export function stripEnvVarPrefix(command: string): string {
+  // env 前缀环境变量格式: WORD=VALUE (VALUE 可以被引号或不含空格的字符串)
+  return command.replace(
+    /^(\s*[A-Za-z_][A-Za-z0-9_]*=(('[^']*'|"[^"]*"|[^\s;|&]*))\s*)+/,
+    '',
+  ).trim();
+}
+
+// ── Safe wrapper 剥离（参考 Claude Code stripSafeWrappers）──────────
+
+/**
+ * Safe wrapper 命令列表 — 这些命令本身是安全的"包装器"，
+ * 真正需要检查的是它们后面的实际命令。
+ */
+const SAFE_WRAPPERS: ReadonlySet<string> = new Set([
+  'timeout', 'time', 'nice', 'nohup', 'ionice', 'stdbuf', 'unbuffer',
+]);
+
+/**
+ * 剥离命令前面的 safe wrapper（如 `timeout 10`、`nice -n 5`）。
+ * 只剥离 wrapper + 它的标志/参数（数字、-flag 形式），直到遇到实际命令。
+ */
+export function stripSafeWrappers(command: string): string {
+  let remaining = command.trim();
+  let changed = true;
+  // 防止无限循环，最多剥离 5 层
+  let maxIter = 5;
+  while (changed && maxIter-- > 0) {
+    changed = false;
+    const tokens = remaining.split(/\s+/);
+    if (tokens.length < 2) break;
+    if (SAFE_WRAPPERS.has(tokens[0])) {
+      // 跳过 wrapper 本身和它的参数（-flag 或纯数字/duration）
+      let i = 1;
+      while (i < tokens.length && /^(-[A-Za-z0-9]|[0-9]+[smhd]?$)/.test(tokens[i])) {
+        i++;
+      }
+      if (i < tokens.length) {
+        remaining = tokens.slice(i).join(' ');
+        changed = true;
+      }
+    }
+  }
+  return remaining;
+}
+
+// ── 复合命令拆分（参考 Claude Code compound command checking）──────
+
+/**
+ * 将复合命令按 `&&`, `||`, `;` 拆分为独立子命令。
+ * 管道 `|` 不拆分 — 管道中的只读性由 classifyBashCommand 判断。
+ *
+ * 注意：不处理 subshell `$(...)` 和反引号 — 这些场景由危险黑名单覆盖。
+ */
+export function splitCompoundCommand(command: string): string[] {
+  // 按 &&, ||, ; 拆分，保留管道作为整体
+  return command.split(/\s*(?:&&|\|\||;)\s*/).map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * 从命令字符串中提取实际的可执行程序名。
+ * 先剥离环境变量前缀和 safe wrapper。
+ */
+export function extractCommandName(command: string): string {
+  const stripped = stripSafeWrappers(stripEnvVarPrefix(command));
+  // 取第一个非管道 token
+  const name = stripped.split(/[\s|]/)[0] || '';
+  return name;
+}
+
+// ── 策略检查结果 ────────────────────────────────────────────────────
+
+export interface ExecPolicyResult {
+  allowed: boolean;
+  /** 如果不允许，拒绝原因 */
+  reason?: string;
+  /** 如果需要用户确认（execAsk=true 且命令不在白名单但也不在黑名单） */
+  needsApproval?: boolean;
+}
+
+// ── 核心检查函数 ────────────────────────────────────────────────────
+
 /**
  * Resolves the effective allowlist by merging preset commands with custom allowlist.
  */
@@ -29,21 +154,34 @@ export function resolveExecAllowlist(config: Required<ZhinAgentConfig>): string[
 }
 
 /**
- * Check if a bash command is allowed under the current exec policy.
- * Throws an Error when the command is denied.
+ * 检查单条子命令是否允许执行。
+ * 内部函数 — 不做复合命令拆分。
  */
-export function checkExecPolicy(config: Required<ZhinAgentConfig>, command: string): void {
-  const security = config.execSecurity ?? 'deny';
-  if (security === 'full') return;
-  if (security === 'deny') {
-    throw new Error('当前配置禁止执行 Shell 命令（execSecurity=deny）。如需开放请在配置中设置 ai.agent.execSecurity。');
+function checkSingleCommand(
+  cmdName: string,
+  fullSubCommand: string,
+  allowlist: string[],
+  security: string,
+  execAsk: boolean,
+): ExecPolicyResult {
+  // 1. 危险黑名单 — 任何模式都拒绝
+  if (isDangerousCommand(cmdName)) {
+    return { allowed: false, reason: `拒绝执行危险命令「${cmdName}」— 该命令可提权或执行任意代码。` };
   }
-  // allowlist
-  const list = resolveExecAllowlist(config);
-  const cmd = (command || '').trim();
-  // 提取命令的第一个 token（实际可执行程序名）进行白名单匹配
-  const cmdName = cmd.split(/[\s;|&]/)[0];
-  const allowed = list.some(pattern => {
+
+  // 2. full 模式 — 通过黑名单后全部放行
+  if (security === 'full') {
+    return { allowed: true };
+  }
+
+  // 3. 只读命令自动放行（与 file-policy classifyBashCommand 集成）
+  const classification = classifyBashCommand(fullSubCommand);
+  if (classification.isReadOnly) {
+    return { allowed: true };
+  }
+
+  // 4. 白名单匹配
+  const allowed = allowlist.some(pattern => {
     try {
       const re = new RegExp(`^${pattern}$`);
       return re.test(cmdName);
@@ -51,18 +189,78 @@ export function checkExecPolicy(config: Required<ZhinAgentConfig>, command: stri
       return cmdName === pattern;
     }
   });
-  if (!allowed) {
-    const ask = config.execAsk;
-    throw new Error(
-      ask
-        ? '该命令不在允许列表中，需要审批后执行。当前版本请将命令加入 ai.agent.execAllowlist 或联系管理员。'
-        : '该命令不在允许列表中，已被拒绝执行。可将允许的命令模式加入 ai.agent.execAllowlist。',
-    );
+
+  if (allowed) {
+    return { allowed: true };
   }
+
+  // 5. 需审批或拒绝
+  if (execAsk) {
+    return {
+      allowed: false,
+      needsApproval: true,
+      reason: `命令「${cmdName}」不在允许列表中，需要用户确认后执行。`,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: `命令「${cmdName}」不在允许列表中，已被拒绝。可将命令加入 ai.agent.execAllowlist 或改用 execPreset。`,
+  };
+}
+
+/**
+ * Check if a bash command is allowed under the current exec policy.
+ * 支持复合命令拆分、环境变量剥离、safe wrapper 剥离、只读自动放行。
+ *
+ * @returns ExecPolicyResult — 允许/拒绝/需审批
+ */
+export function checkExecPolicy(config: Required<ZhinAgentConfig>, command: string): ExecPolicyResult {
+  const security = config.execSecurity ?? 'deny';
+  if (security === 'deny') {
+    return { allowed: false, reason: '当前配置禁止执行 Shell 命令（execSecurity=deny）。如需开放请在配置中设置 ai.agent.execSecurity。' };
+  }
+
+  const allowlist = resolveExecAllowlist(config);
+  const execAsk = config.execAsk ?? false;
+  const cmd = (command || '').trim();
+
+  if (!cmd) {
+    return { allowed: false, reason: '命令为空' };
+  }
+
+  // 拆分复合命令 — 每段独立检查，deny 优先
+  const subCommands = splitCompoundCommand(cmd);
+  let pendingApproval: ExecPolicyResult | null = null;
+
+  for (const sub of subCommands) {
+    const cmdName = extractCommandName(sub);
+    if (!cmdName) continue;
+
+    const result = checkSingleCommand(cmdName, sub, allowlist, security, execAsk);
+
+    // deny 立即返回（deny > ask 优先级）
+    if (!result.allowed && !result.needsApproval) {
+      return result;
+    }
+
+    // 记录第一个需要审批的
+    if (!result.allowed && result.needsApproval && !pendingApproval) {
+      pendingApproval = result;
+    }
+  }
+
+  // 有需要审批的段
+  if (pendingApproval) {
+    return pendingApproval;
+  }
+
+  return { allowed: true };
 }
 
 /**
  * Wrap `bash` tools with exec policy enforcement.
+ * 当 execAsk=true 且命令需审批时，返回提示信息而非抛错。
  */
 export function applyExecPolicyToTools(config: Required<ZhinAgentConfig>, tools: AgentTool[]): AgentTool[] {
   return tools.map(t => {
@@ -72,7 +270,14 @@ export function applyExecPolicyToTools(config: Required<ZhinAgentConfig>, tools:
       ...t,
       execute: async (args: Record<string, any>) => {
         const cmd = args?.command != null ? String(args.command) : '';
-        checkExecPolicy(config, cmd);
+        const result = checkExecPolicy(config, cmd);
+        if (!result.allowed) {
+          if (result.needsApproval) {
+            // 返回可读消息让 AI 用 ask_user 向用户确认
+            return `⚠️ ${result.reason}\n请使用 ask_user 工具询问用户是否允许执行此命令。`;
+          }
+          throw new Error(result.reason!);
+        }
         return original(args);
       },
     };