@zhin.js/agent 0.0.17 → 0.0.19

package/src/discover-tools.ts

@@ -0,0 +1,302 @@
+/**
+ * 文件化 Tool 发现（*.tool.md 文件扫描与构建）
+ *
+ * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
+ * 同名先发现者优先
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { Logger, type Plugin, type ToolParametersSchema } from '@zhin.js/core';
+import { getDataDir } from './discovery-utils.js';
+
+const logger = new Logger(null, 'builtin-tools');
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+export interface ToolParamShorthand {
+  type: string;
+  description?: string;
+  required?: boolean;
+  enum?: string[];
+  default?: any;
+}
+
+export interface ToolMeta {
+  name: string;
+  description: string;
+  /** 简写参数定义（frontmatter 格式） */
+  parameters?: Record<string, ToolParamShorthand>;
+  /** 命令配置 */
+  command?: {
+    pattern?: string;
+    alias?: string[];
+    examples?: string[];
+  };
+  platforms?: string[];
+  scopes?: string[];
+  permissionLevel?: string;
+  tags?: string[];
+  keywords?: string[];
+  kind?: string;
+  hidden?: boolean;
+  /** handler 文件路径（相对于 .tool.md） */
+  handler?: string;
+  /** *.tool.md 文件的绝对路径 */
+  filePath: string;
+  /** body 内容（无 handler 时作为 prompt 模板） */
+  templateBody?: string;
+}
+
+// ============================================================================
+// 目录收集
+// ============================================================================
+
+/**
+ * 从根插件树收集：根插件与直接子插件包目录下的 `tools/`
+ */
+export function collectPluginToolSearchRoots(root: Plugin | null | undefined): string[] {
+  if (!root) return [];
+  const dirs: string[] = [];
+  const push = (d: string) => { if (d && !dirs.includes(d)) dirs.push(d); };
+  const fromPlugin = (p: Plugin) => {
+    if (!p?.filePath) return;
+    const dir = path.dirname(p.filePath);
+    push(path.join(dir, 'tools'));
+    const dirName = path.basename(dir);
+    if (dirName === 'src' || dirName === 'lib') {
+      push(path.join(path.dirname(dir), 'tools'));
+    }
+  };
+  fromPlugin(root);
+  for (const child of root.children || []) fromPlugin(child);
+  return dirs;
+}
+
+/**
+ * 获取所有 tool 搜索目录（标准目录 + 插件包 tools/）
+ */
+export function getToolSearchDirectories(root?: Plugin | null): string[] {
+  const list = [
+    path.join(process.cwd(), 'tools'),
+    path.join(os.homedir(), '.zhin', 'tools'),
+    path.join(getDataDir(), 'tools'),
+  ];
+  for (const d of collectPluginToolSearchRoots(root ?? undefined)) {
+    if (!list.includes(d)) list.push(d);
+  }
+  return list;
+}
+
+// ============================================================================
+// 发现
+// ============================================================================
+
+/**
+ * 扫描 tools/ 目录，发现 *.tool.md 文件
+ */
+export async function discoverWorkspaceTools(root?: Plugin | null): Promise<ToolMeta[]> {
+  const tools: ToolMeta[] = [];
+  const seenNames = new Set<string>();
+  const toolDirs = getToolSearchDirectories(root);
+
+  for (const toolsDir of toolDirs) {
+    if (!fs.existsSync(toolsDir)) continue;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(toolsDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      let toolMdPath: string | undefined;
+      if (entry.isFile() && entry.name.endsWith('.tool.md')) {
+        toolMdPath = path.join(toolsDir, entry.name);
+      } else if (entry.isDirectory()) {
+        const nested = path.join(toolsDir, entry.name, `${entry.name}.tool.md`);
+        if (fs.existsSync(nested)) toolMdPath = nested;
+      }
+      if (!toolMdPath) continue;
+
+      try {
+        const content = await fs.promises.readFile(toolMdPath, 'utf-8');
+        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
+        if (!match) {
+          logger.debug(`Tool文件 ${toolMdPath} 没有有效的frontmatter格式`);
+          continue;
+        }
+
+        let jsYaml: any;
+        try {
+          jsYaml = await import('js-yaml');
+          if (jsYaml.default) jsYaml = jsYaml.default;
+        } catch (e) {
+          logger.warn(`Unable to import js-yaml module: ${e}`);
+          continue;
+        }
+
+        const metadata = jsYaml.load(match[1]);
+        if (!metadata || !metadata.name || !metadata.description) {
+          logger.debug(`Tool文件 ${toolMdPath} 缺少必需的 name/description 字段`);
+          continue;
+        }
+
+        if (seenNames.has(metadata.name)) {
+          logger.debug(`Tool '${metadata.name}' 已由先序目录加载，跳过: ${toolMdPath}`);
+          continue;
+        }
+        seenNames.add(metadata.name);
+
+        const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, '').trim();
+
+        tools.push({
+          name: metadata.name,
+          description: metadata.description,
+          parameters: metadata.parameters || undefined,
+          command: metadata.command || undefined,
+          platforms: metadata.platforms,
+          scopes: metadata.scopes,
+          permissionLevel: metadata.permissionLevel,
+          tags: metadata.tags || [],
+          keywords: metadata.keywords || [],
+          kind: metadata.kind,
+          hidden: metadata.hidden,
+          handler: metadata.handler,
+          filePath: toolMdPath,
+          templateBody: !metadata.handler && body ? body : undefined,
+        });
+        logger.debug(`Tool发现成功: ${metadata.name}`);
+      } catch (e) {
+        logger.warn(`Failed to parse tool.md in ${toolMdPath}:`, e);
+      }
+    }
+  }
+  return tools;
+}
+
+// ============================================================================
+// 构建
+// ============================================================================
+
+function shorthandToSchema(params: Record<string, ToolParamShorthand>): ToolParametersSchema {
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+  for (const [key, param] of Object.entries(params)) {
+    properties[key] = {
+      type: param.type || 'string',
+      description: param.description || key,
+    };
+    if (param.enum) properties[key].enum = param.enum;
+    if (param.default !== undefined) properties[key].default = param.default;
+    if (param.required) required.push(key);
+  }
+  return { type: 'object', properties, required: required.length > 0 ? required : undefined };
+}
+
+async function loadToolHandler(handlerPath: string, toolMdPath: string): Promise<((args: any, context?: any) => any) | undefined> {
+  const resolved = path.resolve(path.dirname(toolMdPath), handlerPath);
+  if (!fs.existsSync(resolved)) {
+    logger.warn(`Tool handler 文件不存在: ${resolved}`);
+    return undefined;
+  }
+  const ext = path.extname(resolved).toLowerCase();
+
+  // Python script handler: spawn subprocess, pass args via JSON stdin, return stdout
+  if (ext === '.py') {
+    return async (args: any) => {
+      const input = JSON.stringify(args);
+      const pythonBin = process.env.PYTHON_BIN || 'python3';
+      try {
+        const result = await new Promise<string>((resolve, reject) => {
+          const child = spawn(pythonBin, [resolved], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 30_000,
+          });
+          let stdout = '';
+          let stderr = '';
+          child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+          child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+          child.on('close', (code) => {
+            if (stderr) logger.debug(`[Python handler] ${resolved} stderr: ${stderr.trim()}`);
+            if (code !== 0) reject(new Error(`Python exited with code ${code}: ${stderr.trim()}`));
+            else resolve(stdout.trim());
+          });
+          child.on('error', reject);
+          child.stdin.write(input);
+          child.stdin.end();
+        });
+        return result;
+      } catch (e: any) {
+        return `Error running Python handler: ${e.message ?? String(e)}`;
+      }
+    };
+  }
+
+  // JS/TS handler: ESM import
+  try {
+    const fileUrl = `file://${resolved}?t=${Date.now()}`;
+    const mod = await import(fileUrl);
+    const fn = mod.default || mod;
+    if (typeof fn !== 'function') {
+      logger.warn(`Tool handler 未导出函数: ${resolved}`);
+      return undefined;
+    }
+    return fn;
+  } catch (e) {
+    logger.warn(`Tool handler 加载失败 (${resolved}): ${e instanceof Error ? e.message : String(e)}`);
+    return undefined;
+  }
+}
+
+function buildTemplateExecute(body: string): (args: Record<string, any>) => string {
+  return (args: Record<string, any>) => body.replace(/\{\{(\w+)\}\}/g, (_, k) => {
+    const val = args[k];
+    return val !== undefined && val !== null ? String(val) : '';
+  });
+}
+
+/**
+ * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
+ */
+export async function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null> {
+  let execute: ((args: any, context?: any) => any) | undefined;
+
+  if (meta.handler) {
+    execute = await loadToolHandler(meta.handler, meta.filePath);
+    if (!execute) return null;
+  } else if (meta.templateBody) {
+    execute = buildTemplateExecute(meta.templateBody);
+  } else {
+    logger.warn(`Tool '${meta.name}' 既没有 handler 也没有模板 body，跳过`);
+    return null;
+  }
+
+  const parameters = meta.parameters
+    ? shorthandToSchema(meta.parameters)
+    : { type: 'object' as const, properties: {} };
+
+  return {
+    name: meta.name,
+    description: meta.description,
+    parameters,
+    execute,
+    tags: meta.tags,
+    keywords: meta.keywords,
+    platforms: meta.platforms,
+    scopes: meta.scopes as any,
+    permissionLevel: meta.permissionLevel as any,
+    hidden: meta.hidden,
+    kind: meta.kind,
+    command: meta.command ? {
+      pattern: meta.command.pattern,
+      alias: meta.command.alias,
+      examples: meta.command.examples,
+    } : undefined,
+  };
+}

package/src/discovery-utils.ts

@@ -0,0 +1,96 @@
+/**
+ * 发现模块共用的工具函数
+ *
+ * 被 builtin-tools / discover-skills / discover-agents / discover-tools 共同依赖，
+ * 独立出来以避免循环导入。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { Plugin } from '@zhin.js/core';
+
+/** 将 unknown 错误转为字符串 */
+export function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** 获取 data/ 目录路径，自动创建 */
+export function getDataDir(): string {
+  const dir = path.join(process.cwd(), 'data');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** 展开路径中的 ~ 为实际 home 目录 */
+export function expandHome(p: string): string {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/** Workspace / ~/.zhin / data 下 skills 根目录（与 activate_skill 扫描顺序一致的前缀） */
+export function buildStandardSkillDirs(): string[] {
+  return [
+    path.join(process.cwd(), 'skills'),
+    path.join(os.homedir(), '.zhin', 'skills'),
+    path.join(getDataDir(), 'skills'),
+  ];
+}
+
+/**
+ * 从根插件树收集：根插件与**直接子插件**包目录下的 `skills/`（其下为 `<name>/SKILL.md`）
+ */
+export function collectPluginSkillSearchRoots(root: Plugin | null | undefined): string[] {
+  if (!root) return [];
+  const dirs: string[] = [];
+  const push = (d: string) => {
+    if (d && !dirs.includes(d)) dirs.push(d);
+  };
+  const fromPlugin = (p: Plugin) => {
+    if (!p?.filePath) return;
+    const dir = path.dirname(p.filePath);
+    push(path.join(dir, 'skills'));
+    // Also check package root when filePath is under src/ or lib/
+    const dirName = path.basename(dir);
+    if (dirName === 'src' || dirName === 'lib') {
+      push(path.join(path.dirname(dir), 'skills'));
+    }
+  };
+  fromPlugin(root);
+  for (const child of root.children || []) {
+    fromPlugin(child);
+  }
+  return dirs;
+}
+
+/**
+ * 技能发现与 activate_skill 查找共用：标准目录 + 已加载插件包 skills/
+ */
+export function getSkillSearchDirectories(root?: Plugin | null): string[] {
+  const list = [...buildStandardSkillDirs()];
+  for (const d of collectPluginSkillSearchRoots(root ?? undefined)) {
+    if (!list.includes(d)) list.push(d);
+  }
+  return list;
+}
+
+export function mergeSkillDirsWithResolver(resolver?: () => string[]): string[] {
+  const list = [...buildStandardSkillDirs()];
+  for (const d of resolver?.() ?? []) {
+    if (d && !list.includes(d)) list.push(d);
+  }
+  return list;
+}
+
+/** 将 Node 文件错误转为 miniclawd 风格的结构化短句，便于模型区分并重试 */
+export function nodeErrToFileMessage(err: unknown, filePath: string, kind: 'read' | 'write' | 'edit' | 'list'): string {
+  const e = err as NodeJS.ErrnoException;
+  if (e?.code === 'ENOENT') {
+    if (kind === 'list') return `Error: Directory not found: ${filePath}`;
+    return `Error: File not found: ${filePath}`;
+  }
+  if (e?.code === 'EACCES') return `Error: Permission denied: ${filePath}`;
+  const action = kind === 'read' ? 'reading file' : kind === 'write' ? 'writing file' : kind === 'edit' ? 'editing file' : 'listing directory';
+  return `Error ${action}: ${e?.message ?? String(err)}`;
+}

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

@@ -5,7 +5,8 @@
 import * as path from 'path';
 import { getPlugin, Scheduler, getScheduler, setScheduler, type MessageType, type SendOptions } from '@zhin.js/core';
 import { ZhinAgent } from '../zhin-agent/index.js';
-import { collectPluginSkillSearchRoots, createBuiltinTools } from '../builtin-tools.js';
+import { createBuiltinTools } from '../builtin-tools.js';
+import { collectPluginSkillSearchRoots } from '../discovery-utils.js';
 import { resolveSkillInstructionMaxChars, DEFAULT_CONFIG } from '../zhin-agent/config.js';
 import { PersistentCronEngine, setCronManager } from '../cron-engine.js';
 import type { AIServiceRefs } from './shared-refs.js';
@@ -49,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),
       });