@zhin.js/core 1.0.32 → 1.0.34

package/src/ai/agent.ts

@@ -32,6 +32,7 @@ export function formatToolTitle(name: string, args?: Record<string, any>): strin
     case 'read_file': return a.file_path != null ? `read_file: ${a.file_path}` : name;
     case 'write_file': return a.file_path != null ? `write_file: ${a.file_path}` : name;
     case 'edit_file': return a.file_path != null ? `edit_file: ${a.file_path}` : name;
+    case 'list_dir': return a.path != null ? `list_dir: ${a.path}` : name;
     case 'web_search': return a.query != null ? `web_search: ${String(a.query).slice(0, 40)}` : name;
     case 'web_fetch': return a.url != null ? `web_fetch: ${String(a.url).slice(0, 50)}` : name;
     default: {
@@ -286,10 +287,21 @@ export class Agent {
       });
     }
 
+    let args: Record<string, unknown>;
     try {
-      const args = JSON.parse(toolCall.function.arguments);
-      this.emit('tool_call', tool.name, args);
+      args = JSON.parse(toolCall.function.arguments);
+    } catch {
+      return JSON.stringify({
+        error: 'Invalid tool arguments JSON',
+        tool: toolCall.function.name,
+        hint: '请检查工具参数格式后重试。',
+      });
+    }
+
+    logger.debug({ tool: toolCall.function.name, params: args }, 'Executing tool');
+    this.emit('tool_call', tool.name, args);
 
+    try {
       // 带超时的工具执行
       const result = await Promise.race([
         tool.execute(args),
@@ -303,6 +315,7 @@ export class Agent {
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
       logger.warn(`工具 ${toolCall.function.name} 执行失败: ${errorMsg}`);
+      logger.error({ tool: toolCall.function.name, params: args, err: error }, 'Tool execution failed');
       // 向 AI 提供结构化的错误信息和恢复提示
       return JSON.stringify({
         error: errorMsg,

package/src/ai/bootstrap.ts

@@ -24,10 +24,10 @@ const logger = new Logger(null, 'Bootstrap');
 // 常量
 // ============================================================================
 
-/** 支持的引导文件名 */
+/** 支持的引导文件名（顺序：SOUL → AGENTS → TOOLS） */
 export const BOOTSTRAP_FILENAMES = [
-  'AGENTS.md',
   'SOUL.md',
+  'AGENTS.md',
   'TOOLS.md',
 ] as const;
 
@@ -104,6 +104,52 @@ function getDataDir(workspaceDir?: string): string {
   return path.join(cwd, 'data');
 }
 
+/**
+ * 获取文件制长期记忆目录（data/memory），不存在则创建
+ */
+export function getMemoryDir(workspaceDir?: string): string {
+  const dir = path.join(getDataDir(workspaceDir), 'memory');
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function todayDate(): string {
+  return new Date().toISOString().split('T')[0];
+}
+
+/**
+ * 读取文件制长期记忆 + 当日笔记，拼成注入 system prompt 的字符串（与 miniclawd 一致）
+ * 同步读取，供 buildRichSystemPrompt 等同步调用
+ */
+export function getFileMemoryContext(workspaceDir?: string): string {
+  const memoryDir = getMemoryDir(workspaceDir);
+  const parts: string[] = [];
+
+  const memoryFile = path.join(memoryDir, 'MEMORY.md');
+  if (fs.existsSync(memoryFile)) {
+    try {
+      const longTerm = fs.readFileSync(memoryFile, 'utf-8').trim();
+      if (longTerm) parts.push('## Long-term Memory\n' + longTerm);
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  const todayFile = path.join(memoryDir, `${todayDate()}.md`);
+  if (fs.existsSync(todayFile)) {
+    try {
+      const today = fs.readFileSync(todayFile, 'utf-8').trim();
+      if (today) parts.push("## Today's Notes\n" + today);
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  return parts.length > 0 ? parts.join('\n\n') : '';
+}
+
 /**
  * 加载工作区引导文件
  *

package/src/ai/builtin-tools.ts

@@ -3,12 +3,12 @@
  *
  * 借鉴 OpenClaw/MicroClaw 的实用工具设计，为 ZhinAgent 提供：
  *
- * 文件工具:  read_file, write_file, edit_file, glob, grep
+ * 文件工具:  read_file, write_file, edit_file, list_dir, glob, grep
  * Shell:     bash
  * 网络:      web_search, web_fetch
  * 计划:      todo_read, todo_write
  * 记忆:      read_memory, write_memory (AGENTS.md)
- * 技能:      activate_skill
+ * 技能:      activate_skill, install_skill
  * 会话:      session_status, compact_session
  * 技能发现:  工作区 skills/ 目录自动扫描
  * 引导文件:  SOUL.md, TOOLS.md, AGENTS.md 自动加载
@@ -37,39 +37,67 @@ function getDataDir(): string {
   return dir;
 }
 
+/** 展开路径中的 ~ 为实际 home 目录 */
+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;
+}
+
+/** 将 Node 文件错误转为 miniclawd 风格的结构化短句，便于模型区分并重试 */
+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)}`;
+}
+
 // ============================================================================
 // 工具工厂函数
 // ============================================================================
 
+export interface BuiltinToolsOptions {
+  /** Max chars for skill instruction extraction (model-size-aware) */
+  skillInstructionMaxChars?: number;
+}
+
 /**
  * 创建所有内置系统工具
  */
-export function createBuiltinTools(): ZhinTool[] {
+export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
   const DATA_DIR = getDataDir();
+  const skillMaxChars = options?.skillInstructionMaxChars ?? 4000;
 
   const tools: ZhinTool[] = [];
 
-  // ── read_file ──
+  // ── read_file（清晰描述 + 强关键词） ──
   tools.push(
     new ZhinTool('read_file')
-      .desc('读取文件内容（带行号，支持 offset/limit 分页）')
-      .keyword('读文件', '查看', '打开', 'cat', 'read')
+      .desc('读取指定路径的文件内容。用于查看、打开或读取任意文本文件。')
+      .keyword('读文件', '读取文件', '查看文件', '打开文件', '文件内容', 'read file', 'read', 'cat', '查看', '打开')
       .tag('file', 'read')
       .kind('file')
-      .param('file_path', { type: 'string', description: '文件路径（绝对或相对）' }, true)
-      .param('offset', { type: 'number', description: '起始行号（0-based，默认 0）' })
-      .param('limit', { type: 'number', description: '最大读取行数（默认全部）' })
+      .param('file_path', { type: 'string', description: '要读取的文件路径（绝对路径或相对项目根目录）' }, true)
+      .param('offset', { type: 'number', description: '起始行号（0-based，可选，默认从第 1 行开始）' })
+      .param('limit', { type: 'number', description: '最多读取行数（可选，默认全部）' })
       .execute(async (args) => {
         try {
-          const content = await fs.promises.readFile(args.file_path, 'utf-8');
+          const fp = expandHome(args.file_path);
+          const stat = await fs.promises.stat(fp);
+          if (!stat.isFile()) return `Error: Not a file: ${fp}`;
+          const content = await fs.promises.readFile(fp, 'utf-8');
           const lines = content.split('\n');
           const offset = args.offset ?? 0;
           const limit = args.limit ?? lines.length;
           const sliced = lines.slice(offset, offset + limit);
           const numbered = sliced.map((line: string, i: number) => `${offset + i + 1} | ${line}`).join('\n');
-          return `File: ${args.file_path} (${lines.length} lines, showing ${offset + 1}-${Math.min(offset + limit, lines.length)})\n${numbered}`;
-        } catch (e: any) {
-          return `Error: ${e.message}`;
+          return `File: ${fp} (${lines.length} lines, showing ${offset + 1}-${Math.min(offset + limit, lines.length)})\n${numbered}`;
+        } catch (e: unknown) {
+          return nodeErrToFileMessage(e, args.file_path, 'read');
         }
       }),
   );
@@ -77,48 +105,79 @@ export function createBuiltinTools(): ZhinTool[] {
   // ── write_file ──
   tools.push(
     new ZhinTool('write_file')
-      .desc('创建或覆盖文件（自动创建目录）')
-      .keyword('写文件', '创建文件', '保存', 'write')
+      .desc('向指定路径写入内容，创建或覆盖文件；若目录不存在会自动创建。')
+      .keyword('写文件', '写入文件', '创建文件', '保存文件', 'write file', 'write', '保存', '创建')
       .tag('file', 'write')
       .kind('file')
-      .param('file_path', { type: 'string', description: '文件路径' }, true)
-      .param('content', { type: 'string', description: '写入内容' }, true)
+      .param('file_path', { type: 'string', description: '要写入的文件路径' }, true)
+      .param('content', { type: 'string', description: '要写入的完整内容' }, true)
       .execute(async (args) => {
         try {
-          await fs.promises.mkdir(path.dirname(args.file_path), { recursive: true });
-          await fs.promises.writeFile(args.file_path, args.content, 'utf-8');
-          return `✅ Wrote ${Buffer.byteLength(args.content)} bytes to ${args.file_path}`;
-        } catch (e: any) {
-          return `Error: ${e.message}`;
+          const fp = expandHome(args.file_path);
+          await fs.promises.mkdir(path.dirname(fp), { recursive: true });
+          await fs.promises.writeFile(fp, args.content, 'utf-8');
+          return `✅ Wrote ${Buffer.byteLength(args.content)} bytes to ${fp}`;
+        } catch (e: unknown) {
+          return nodeErrToFileMessage(e, args.file_path, 'write');
         }
       }),
   );
 
-  // ── edit_file ──
+  // ── edit_file（old_text 必须精确匹配） ──
   tools.push(
     new ZhinTool('edit_file')
-      .desc('查找并替换文件内容（old_string 必须唯一匹配）。注意：old_string 应包含完整的行内容（含前后文），不要只匹配单个数字或单词')
-      .keyword('编辑', '修改', '替换', 'edit')
+      .desc('在文件中查找并替换一段文本。old_string 必须在文件中精确存在且唯一；建议包含完整行或足够上下文以避免重复匹配。')
+      .keyword('编辑文件', '修改文件', '替换内容', '查找替换', 'edit file', 'edit', '修改', '替换')
       .tag('file', 'edit')
       .kind('file')
-      .param('file_path', { type: 'string', description: '文件路径' }, true)
-      .param('old_string', { type: 'string', description: '要替换的原文（必须在文件中唯一出现，建议包含完整行）' }, true)
-      .param('new_string', { type: 'string', description: '替换后的文本（必须是替换 old_string 后的完整内容）' }, true)
+      .param('file_path', { type: 'string', description: '要编辑的文件路径' }, true)
+      .param('old_string', { type: 'string', description: '文件中要替换的原文（必须与文件内容完全一致）' }, true)
+      .param('new_string', { type: 'string', description: '替换后的新文本' }, true)
       .execute(async (args) => {
         try {
-          const content = await fs.promises.readFile(args.file_path, 'utf-8');
+          const fp = expandHome(args.file_path);
+          const content = await fs.promises.readFile(fp, 'utf-8');
           const count = content.split(args.old_string).length - 1;
-          if (count === 0) return `Error: old_string not found in ${args.file_path}. Use read_file to check current content first.`;
-          if (count > 1) return `Error: old_string matches ${count} locations (must be unique). Include more context to make it unique.`;
+          if (count === 0) return `Error: old_string not found in file. Make sure it matches exactly.`;
+          if (count > 1) return `Warning: old_string appears ${count} times. Please provide more context to make it unique.`;
           const newContent = content.replace(args.old_string, args.new_string);
-          await fs.promises.writeFile(args.file_path, newContent, 'utf-8');
+          await fs.promises.writeFile(fp, newContent, 'utf-8');
 
-          // 返回修改前后的差异上下文，帮助 AI 确认修改正确
           const oldLines = args.old_string.split('\n');
           const newLines = args.new_string.split('\n');
-          return `✅ Edited ${args.file_path}\n--- before ---\n${oldLines.slice(0, 5).join('\n')}${oldLines.length > 5 ? '\n...' : ''}\n--- after ---\n${newLines.slice(0, 5).join('\n')}${newLines.length > 5 ? '\n...' : ''}`;
-        } catch (e: any) {
-          return `Error: ${e.message}`;
+          return `✅ Edited ${fp}\n--- before ---\n${oldLines.slice(0, 5).join('\n')}${oldLines.length > 5 ? '\n...' : ''}\n--- after ---\n${newLines.slice(0, 5).join('\n')}${newLines.length > 5 ? '\n...' : ''}`;
+        } catch (e: unknown) {
+          return nodeErrToFileMessage(e, args.file_path, 'edit');
+        }
+      }),
+  );
+
+  // ── list_dir（列出目录内容，便于 AI 匹配「列表」「目录」「ls」） ──
+  tools.push(
+    new ZhinTool('list_dir')
+      .desc('列出指定目录下的文件和子目录名称。用于查看目录结构、有哪些文件。')
+      .keyword('列目录', '列出目录', '目录列表', '查看目录', 'list directory', 'list dir', 'ls', 'dir', '目录内容', '有哪些文件')
+      .tag('file', 'list')
+      .kind('file')
+      .param('path', { type: 'string', description: '要列出的目录路径（绝对或相对项目根目录）' }, true)
+      .execute(async (args) => {
+        try {
+          const dirPath = path.resolve(process.cwd(), expandHome(args.path));
+          const stat = await fs.promises.stat(dirPath);
+          if (!stat.isDirectory()) {
+            return `Error: Not a directory: ${args.path}`;
+          }
+          const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+          if (entries.length === 0) {
+            return `Directory ${args.path} is empty`;
+          }
+          const lines: string[] = [];
+          for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            lines.push((e.isDirectory() ? '[DIR]  ' : '       ') + e.name);
+          }
+          return lines.join('\n');
+        } catch (e: unknown) {
+          return nodeErrToFileMessage(e, args.path, 'list');
         }
       }),
   );
@@ -126,8 +185,8 @@ export function createBuiltinTools(): ZhinTool[] {
   // ── glob ──
   tools.push(
     new ZhinTool('glob')
-      .desc('按 glob 模式查找文件（如 **/*.ts）')
-      .keyword('查找文件', '搜索文件', '文件列表', 'ls', 'find')
+      .desc('按 glob 模式查找匹配的文件路径（如 **/*.ts）。用于按模式找文件，而非列出目录。')
+      .keyword('glob', '查找文件', '按模式找文件', 'find', '匹配文件')
       .tag('file', 'search')
       .kind('file')
       .param('pattern', { type: 'string', description: 'Glob 模式（如 **/*.ts）' }, true)
@@ -203,14 +262,15 @@ export function createBuiltinTools(): ZhinTool[] {
       }),
   );
 
-  // ── web_search ──
+  // ── web_search（搜索网页，返回标题、URL、摘要） ──
   tools.push(
     new ZhinTool('web_search')
-      .desc('通过 DuckDuckGo 搜索网页，返回标题、URL 和摘要（零依赖）')
-      .keyword('搜索', '网上', '谷歌', '百度', '查询', 'search')
+      .desc('在互联网上搜索，返回匹配的标题、URL 和摘要片段。用于查资料、找网页。')
+      .keyword('搜索', '网上搜', '网页搜索', '搜索引擎', 'search', 'google', '百度', '查询', '搜一下')
       .tag('web', 'search')
-      .param('query', { type: 'string', description: '搜索关键词' }, true)
-      .param('limit', { type: 'number', description: '最大结果数（默认 5）' })
+      .kind('web')
+      .param('query', { type: 'string', description: '搜索关键词或完整查询语句' }, true)
+      .param('limit', { type: 'number', description: '返回结果数量（默认 5，建议 1–10）' })
       .execute(async (args) => {
         try {
           const limit = args.limit ?? 5;
@@ -265,14 +325,14 @@ export function createBuiltinTools(): ZhinTool[] {
       }),
   );
 
-  // ── web_fetch ──
+  // ── web_fetch（抓取 URL 并提取正文） ──
   tools.push(
     new ZhinTool('web_fetch')
-      .desc('抓取网页内容（去除 HTML 标签，最大 20KB）')
-      .keyword('抓取', '网页', 'fetch', 'url', '链接')
+      .desc('抓取指定 URL 的网页内容并提取正文（去除广告等），返回可读文本。用于读文章、获取网页内容。')
+      .keyword('抓取网页', '打开链接', '获取网页', '读网页', 'fetch', 'url', '链接内容', '网页内容')
       .tag('web', 'fetch')
       .kind('web')
-      .param('url', { type: 'string', description: 'URL 地址' }, true)
+      .param('url', { type: 'string', description: '要抓取的完整 URL（需 http 或 https）' }, true)
       .execute(async (args) => {
         try {
           const response = await fetch(args.url, {
@@ -413,7 +473,7 @@ export function createBuiltinTools(): ZhinTool[] {
               const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
               // 5.3 可执行环境检查：若 SKILL 声明了 deps，再次检查；缺失则在返回内容中提示
               const depWarning = await checkSkillDeps(fullContent);
-              const instructions = extractSkillInstructions(args.name, fullContent);
+              const instructions = extractSkillInstructions(args.name, fullContent, skillMaxChars);
               return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
             }
           }
@@ -424,6 +484,51 @@ export function createBuiltinTools(): ZhinTool[] {
       }),
   );
 
+  // ── install_skill（从 URL 下载并安装技能） ──
+  tools.push(
+    new ZhinTool('install_skill')
+      .desc('从 URL 下载 SKILL.md 并安装到本地 skills/ 目录。用户要求加入/安装/下载某个技能时使用')
+      .keyword('安装技能', '下载技能', '加入', '添加技能', 'install', 'skill', 'join', '学会', '学习技能')
+      .tag('skill', 'install')
+      .kind('skill')
+      .param('url', { type: 'string', description: 'SKILL.md 文件的完整 URL（如 https://example.com/skill.md）' }, true)
+      .execute(async (args) => {
+        try {
+          const response = await fetch(args.url, {
+            headers: { 'User-Agent': 'Mozilla/5.0 (compatible; ZhinBot/1.0)' },
+            signal: AbortSignal.timeout(15000),
+          });
+          if (!response.ok) return `Error: HTTP ${response.status} ${response.statusText}`;
+          const content = await response.text();
+
+          const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+          if (!fmMatch) return 'Error: 无效的 SKILL.md 文件（缺少 frontmatter）';
+
+          let yaml: any;
+          try {
+            yaml = await import('yaml');
+            if (yaml.default) yaml = yaml.default;
+          } catch {
+            return 'Error: 无法加载 yaml 解析器';
+          }
+
+          const metadata = yaml.parse(fmMatch[1]);
+          if (!metadata?.name) return 'Error: SKILL.md 缺少 name 字段';
+
+          const skillName: string = metadata.name;
+          const skillDir = path.join(process.cwd(), 'skills', skillName);
+          await fs.promises.mkdir(skillDir, { recursive: true });
+          const skillPath = path.join(skillDir, 'SKILL.md');
+          await fs.promises.writeFile(skillPath, content, 'utf-8');
+
+          logger.info(`技能已安装: ${skillName} → ${skillPath}`);
+          return `✅ 技能「${skillName}」已安装到 ${skillPath}。现在可以用 activate_skill("${skillName}") 激活它。`;
+        } catch (e: any) {
+          return `Error: ${e.message}`;
+        }
+      }),
+  );
+
   logger.info(`已创建 ${tools.length} 个内置系统工具`);
   return tools;
 }
@@ -463,12 +568,11 @@ async function checkSkillDeps(content: string): Promise<string> {
  * 只保留 frontmatter（工具列表）和执行规则，去掉示例、测试场景等冗余内容
  * 这样可以大幅减少 token 占用，让小模型能有足够空间继续调用工具
  */
-function extractSkillInstructions(name: string, content: string): string {
+function extractSkillInstructions(name: string, content: string, maxBodyLen: number = 4000): string {
   const lines: string[] = [];
   lines.push(`Skill '${name}' activated. 请立即根据以下指导执行工具调用：`);
   lines.push('');
 
-  // 1. 提取 frontmatter 中的 tools 列表
   const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
   if (fmMatch) {
     const fmContent = fmMatch[1];
@@ -480,12 +584,23 @@ function extractSkillInstructions(name: string, content: string): string {
     }
   }
 
-  // 2. 提取执行指导：优先 "## 执行规则"，否则尝试 "## Workflow" / "## Instructions" / "## 使用说明"，再否则用正文（去掉 frontmatter）
-  const rulesMatch = content.match(/## 执行规则[\s\S]*?(?=\n## [^\s]|$)/);
-  const workflowMatch = content.match(/## (?:Workflow|Instructions|使用说明)[\s\S]*?(?=\n## [^\s]|$)/);
   const bodyAfterFm = fmMatch && fmMatch.index !== undefined
     ? content.slice(fmMatch.index + fmMatch[0].length).replace(/^\s+/, '')
     : content;
+
+  // Priority: "## 快速操作" / "## Quick Actions" summary for small models
+  const quickActionsMatch = bodyAfterFm.match(/## (?:快速操作|Quick\s*Actions)[\s\S]*?(?=\n## [^\s]|$)/i);
+  if (quickActionsMatch && maxBodyLen <= 2000) {
+    lines.push(quickActionsMatch[0].trim());
+    lines.push('');
+    lines.push('## 立即行动');
+    lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
+    return lines.join('\n');
+  }
+
+  const rulesMatch = content.match(/## 执行规则[\s\S]*?(?=\n## [^\s]|$)/);
+  const workflowMatch = content.match(/## (?:Workflow|Instructions|使用说明)[\s\S]*?(?=\n## [^\s]|$)/);
+
   if (rulesMatch) {
     lines.push(rulesMatch[0].trim());
     lines.push('');
@@ -493,19 +608,36 @@ function extractSkillInstructions(name: string, content: string): string {
     lines.push(workflowMatch[0].trim());
     lines.push('');
   } else if (bodyAfterFm.trim()) {
-    // 无上述标题时使用正文（去除 frontmatter 后）作为指导
     const firstH2 = bodyAfterFm.match(/\n## [^\s]/);
-    const main = firstH2 ? bodyAfterFm.slice(0, firstH2.index).trim() : bodyAfterFm.trim();
-    if (main) {
+    const intro = firstH2 ? bodyAfterFm.slice(0, firstH2.index).trim() : bodyAfterFm.trim();
+
+    const quickStartMatch = bodyAfterFm.match(/## (?:快速开始|Quick\s*Start|Getting\s*Started)[\s\S]*?(?=\n## [^\s]|$)/i);
+    const authMatch = bodyAfterFm.match(/## (?:认证|Authentication|Auth)[\s\S]*?(?=\n## [^\s]|$)/i);
+
+    if (quickStartMatch || (intro.length < 200 && bodyAfterFm.length > intro.length)) {
       lines.push('## 指导');
-      lines.push(main);
+      lines.push(intro);
+      lines.push('');
+      const extra: string[] = [];
+      if (quickStartMatch) extra.push(quickStartMatch[0].trim());
+      if (authMatch) extra.push(authMatch[0].trim());
+      if (extra.length > 0) {
+        const joined = extra.join('\n\n');
+        lines.push(joined.length > maxBodyLen ? joined.slice(0, maxBodyLen) + '\n...(truncated)' : joined);
+      } else {
+        const rest = bodyAfterFm.slice(intro.length).trim();
+        lines.push(rest.length > maxBodyLen ? rest.slice(0, maxBodyLen) + '\n...(truncated)' : rest);
+      }
+      lines.push('');
+    } else if (intro) {
+      lines.push('## 指导');
+      lines.push(intro);
       lines.push('');
     }
   }
 
-  // 3. 添加强制执行提醒
   lines.push('## 立即行动');
-  lines.push('你现在必须根据用户的原始请求，立即调用上述工具。不要描述步骤，直接执行 tool_calls。');
+  lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
 
   return lines.join('\n');
 }
@@ -514,7 +646,7 @@ function extractSkillInstructions(name: string, content: string): string {
 // 技能发现
 // ============================================================================
 
-interface SkillMeta {
+export interface SkillMeta {
   name: string;
   description: string;
   keywords?: string[];
@@ -522,12 +654,18 @@ interface SkillMeta {
   /** SKILL.md frontmatter 中声明的关联工具名列表 */
   toolNames?: string[];
   filePath: string;
+  /** 是否常驻注入 system prompt（frontmatter always: true） */
+  always?: boolean;
+  /** 当前环境是否满足依赖（bins/env） */
+  available?: boolean;
+  /** 缺失的依赖描述（如 "CLI: ffmpeg", "ENV: API_KEY"） */
+  requiresMissing?: string[];
 }
 
 /**
  * 扫描技能目录，发现 SKILL.md 技能文件
- * 加载顺序：Workspace（cwd/skills）> Local（~/.zhin/skills）> Bundled（data/skills），同名技能先发现者优先
- * 支持平台/依赖兼容性过滤
+ * 加载顺序：Workspace（cwd/skills）> Local（~/.zhin/skills）> Bundled（data/skills），同名先发现者优先
+ * 支持平台/依赖兼容性过滤。内置技能由 create-zhin 在创建项目时写入 skills/summarize 等。
  */
 export async function discoverWorkspaceSkills(): Promise<SkillMeta[]> {
   const skills: SkillMeta[] = [];
@@ -596,21 +734,25 @@ export async function discoverWorkspaceSkills(): Promise<SkillMeta[]> {
           }
         }
 
-        // 依赖检查
-        const deps = compat.deps || metadata.deps;
-        if (deps && Array.isArray(deps)) {
-          let missing = false;
-          for (const dep of deps) {
-            try {
-              await execAsync(`which ${dep} 2>/dev/null`);
-            } catch {
-              logger.debug(`Skipping skill '${metadata.name}' (missing dep: ${dep})`);
-              missing = true;
-              break;
-            }
+        // 依赖检查：支持 metadata.requires.bins / requires.env 或 compat.deps / metadata.deps
+        const requiresBins: string[] = metadata.requires?.bins || compat.deps || metadata.deps || [];
+        const requiresEnv: string[] = metadata.requires?.env || [];
+        const binsToCheck = Array.isArray(requiresBins) ? requiresBins : [];
+        const envToCheck = Array.isArray(requiresEnv) ? requiresEnv : [];
+        const requiresMissing: string[] = [];
+        for (const bin of binsToCheck) {
+          try {
+            await execAsync(`which ${bin} 2>/dev/null`);
+          } catch {
+            requiresMissing.push(`CLI: ${bin}`);
           }
-          if (missing) continue;
         }
+        for (const envKey of envToCheck) {
+          if (!process.env[envKey]) {
+            requiresMissing.push(`ENV: ${envKey}`);
+          }
+        }
+        const available = requiresMissing.length === 0;
 
         if (seenNames.has(metadata.name)) {
           logger.debug(`Skill '${metadata.name}' 已由先序目录加载，跳过: ${skillMdPath}`);
@@ -625,6 +767,9 @@ export async function discoverWorkspaceSkills(): Promise<SkillMeta[]> {
           tags: [...(metadata.tags || []), 'workspace-skill'],
           toolNames: Array.isArray(metadata.tools) ? metadata.tools : [],
           filePath: skillMdPath,
+          always: Boolean(metadata.always),
+          available,
+          requiresMissing: requiresMissing.length > 0 ? requiresMissing : undefined,
         });
         logger.debug(`Skill发现成功: ${metadata.name}, tools: ${JSON.stringify(metadata.tools || [])}`);
       } catch (e) {
@@ -639,3 +784,66 @@ export async function discoverWorkspaceSkills(): Promise<SkillMeta[]> {
 
   return skills;
 }
+
+/**
+ * 获取 frontmatter 中 always: true 的技能名列表（用于常驻注入 system prompt）
+ */
+export function getAlwaysSkillNames(skills: SkillMeta[]): string[] {
+  return skills.filter(s => s.always && s.available).map(s => s.name);
+}
+
+/**
+ * 去除 frontmatter，返回正文
+ */
+function stripFrontmatter(content: string): string {
+  const match = content.match(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/);
+  if (match) {
+    return content.slice(match[0].length).trim();
+  }
+  return content.trim();
+}
+
+/**
+ * 加载 always 技能的正文内容并拼接为「Active Skills」段
+ */
+export async function loadAlwaysSkillsContent(skills: SkillMeta[]): Promise<string> {
+  const always = skills.filter(s => s.always && s.available);
+  if (always.length === 0) return '';
+  const parts: string[] = [];
+  for (const s of always) {
+    try {
+      const content = await fs.promises.readFile(s.filePath, 'utf-8');
+      const body = stripFrontmatter(content);
+      parts.push(`### Skill: ${s.name}\n\n${body}`);
+    } catch (e) {
+      logger.warn(`Failed to load always skill ${s.name}: ${(e as Error).message}`);
+    }
+  }
+  return parts.join('\n\n---\n\n');
+}
+
+/** 转义 XML 特殊字符 */
+function escapeXml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/**
+ * 构建技能列表的 XML 摘要，供 model 区分可用/不可用及缺失依赖
+ */
+export function buildSkillsSummaryXML(skills: SkillMeta[]): string {
+  if (skills.length === 0) return '';
+  const lines = ['<skills>'];
+  for (const s of skills) {
+    const available = s.available !== false;
+    lines.push(`  <skill available="${available}">`);
+    lines.push(`    <name>${escapeXml(s.name)}</name>`);
+    lines.push(`    <description>${escapeXml(s.description)}</description>`);
+    lines.push(`    <location>${escapeXml(s.filePath)}</location>`);
+    if (!available && s.requiresMissing && s.requiresMissing.length > 0) {
+      lines.push(`    <requires>${escapeXml(s.requiresMissing.join(', '))}</requires>`);
+    }
+    lines.push('  </skill>');
+  }
+  lines.push('</skills>');
+  return lines.join('\n');
+}