@bolloon/bolloon-agent 0.5.4 → 0.5.5

package/dist/agents/pi-sdk-tools.js

@@ -2,6 +2,7 @@ import * as fs from 'fs/promises';
 import { loadWalletTool } from './wallet-tools.js';
 import * as fsSync from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { currentPackageRoot } from '../utils/version-info.js';
 import { documentReader } from '../documents/reader.js';
 import { p2pNetwork } from '../network/p2p.js';
@@ -10,7 +11,9 @@ import { checkWritePath } from './shell-guard.js';
 import { p2pDocumentTools } from './p2p-document-tools.js';
 import { runSelfImproveLoop } from './pi-sdk-session-factory.js';
 import { getMinimax } from '../constraints/index.js';
-import { delegateToEngine } from '../external-engines/delegate.js';
+import { delegateToEngine, buildDelegateCommand } from '../external-engines/delegate.js';
+import { spawnBackground } from './process-runner.js';
+import { DELEGATE_ENV_MARK } from './background-notices.js';
 // 2026-09-13: 下一代工具集 (人机问答 / 精确补丁 / 桌面操作 / 技能分享)
 import { userQuestions, DEFAULT_QUESTION_TIMEOUT_MS } from './user-questions.js';
 import { registerPatchTools } from './patch-tool.js';
@@ -62,6 +65,13 @@ async function detectRunner(candidates) {
     }
     return null;
 }
+/**
+ * 技能文件路径(账本/快照用) —— 与 skill-writer 的落盘规则一致: <root>/<name>/SKILL.md ✓
+ */
+function skillFilePath(name, scope) {
+    const root = scope === 'project' ? path.join(process.cwd(), '.bolloon', 'skills') : path.join(os.homedir(), '.bolloon', 'skills');
+    return path.join(root, name, 'SKILL.md');
+}
 export async function runCodeSnippet(opts) {
     const code = String(opts.code ?? '').trim();
     if (!code)
@@ -196,7 +206,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('summarize_document', {
         name: 'summarize_document',
-        description: '总结文档内容，分析并生成摘要',
+        description: '读一篇文档并生成摘要. 只想要摘要 ⇒ 这个; 想按你的要求改写 ⇒ improve_document; 想自己读原文 ⇒ read_document.',
         parameters: { path: '文件路径 (必填)', context: '可选, 总结上下文提示' },
         execute: async (args) => {
             try {
@@ -223,7 +233,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('improve_document', {
         name: 'improve_document',
-        description: '根据要求改进文档内容',
+        description: '按你的要求**改写**已有文档 (保留原意、改表达). 纯改写 ⇒ 用这个; 只想要摘要 ⇒ summarize_document; 全新写一份 ⇒ write_file.',
         parameters: { path: '文件路径 (必填)', requirements: '改进要求 (必填)' },
         execute: async (args) => {
             try {
@@ -251,7 +261,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('list_peers', {
         name: 'list_peers',
-        description: '列出已连接的对等节点',
+        description: '列**已连接**的 P2P 对等节点. 想找远端可发消息的 channel ⇒ list_remote_channels; 想看好友申请 ⇒ list_pending_friend_requests.',
         parameters: {},
         execute: async () => {
             const peers = p2pNetwork.getPeers();
@@ -263,7 +273,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('send_message', {
         name: 'send_message',
-        description: '向指定对等节点发送消息',
+        description: '给**一个**指定节点发消息 (需要它的 peerId). 不知道发谁 ⇒ 先 list_peers; 要广播 ⇒ broadcast_message.',
         parameters: { peer_id: '对等节点ID', message: '消息内容' },
         execute: async (args) => {
             try {
@@ -277,7 +287,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('broadcast_message', {
         name: 'broadcast_message',
-        description: '向所有对等节点广播消息',
+        description: '向**所有**已连接节点广播一条消息. 只发给某一个 ⇒ send_message; 发到某个远程 channel ⇒ send_to_remote_channel. 广播面广, 别拿它当日常通知用.',
         parameters: { message: '消息内容' },
         execute: async (args) => {
             try {
@@ -375,7 +385,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('p2p_broadcast', {
         name: 'p2p_broadcast',
-        description: '广播消息到所有连接的 P2P 节点',
+        description: '把一个 p2p channel 的地址**广播**给已连接节点. 单点发消息用 send_message, 别广播.',
         parameters: { message: '消息内容', type: '可选, 消息类型标签 (默认 agent-broadcast)' },
         execute: async (args) => {
             const msg = String(args.message || '').trim();
@@ -609,6 +619,8 @@ export function registerBuiltinTools(ctx) {
         }
     });
     // delegate_to_engine — 把编码任务委派给本机已安装的其他 AI 编码智能体 CLI
+    //   2026-10-01: **它是同步等待** (默认 120s 超时, 超时杀进程) ⇒ 长活别用它 ✗ —
+    //     要"起完就走、以后回来收"的长任务 ⇒ `terminal(background:true)` + `process poll/wait/kill` ✓(今天已给后台进程加了落盘/懒恢复 ✓)。
     // (codex / claude-code / opencode / openclaw / hermes). 它们必须已安装且可达 PATH.
     // 实验 API 引擎 (experiment:xxx) 是供应商不是 CLI, 不支持委派, 工具会提示改用 import.
     ctx.tools.set('delegate_to_engine', {
@@ -618,7 +630,9 @@ export function registerBuiltinTools(ctx) {
             engine: "引擎 id: codex / claude-code / opencode / openclaw / hermes (实验 API 不支持委派)",
             prompt: '派发的任务描述 (作为单参数传给该引擎 CLI)',
             model: '可选, 强制指定模型 (如 deepseek/deepseek-v4-flash), 需引擎支持',
-            cwd: '可选, 工作目录, 默认当前目录'
+            cwd: '可选, 工作目录, 默认当前目录',
+            timeoutMs: '可选, 等待上限毫秒(默认 120000=2 分钟, 超时会**终止**该引擎进程). 小活给 20000~30000, 大活别用委派(见描述)',
+            background: '可选, **默认 true** —— 起完就走(后台 session), 结果会在完成后的**下一轮自动回灌**给你; 想拿完整输出用 process poll <session>。只有确实要"现在就等它的结果"才传 false'
         },
         execute: async (args) => {
             const engine = String(args.engine || '').trim();
@@ -633,14 +647,44 @@ export function registerBuiltinTools(ctx) {
             // correlationId 幂等去重 (同一 agent 重复 correlation 只应出现一次)
             const ownerDid = ctx.identity?.did || 'unknown';
             const correlationId = `delegate:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+            // 2026-10-01 (用户: 「开展子智能体后，bolloon 没有回归」/「还是卡住了，学 hermes」):
+            //   **默认后台** ✓ —— 起完立刻返回(带 session id), 父智能体继续干别的 ✓;
+            //   它跑完的结果由 background-notices 在下一轮**自动回灌** ✓ ⇒ 不再"卡满 120s 然后白干" ✗。
+            const wantBackground = String(args.background ?? '') !== 'false'; // 默认 true(起完就走 ✓)
+            if (wantBackground) {
+                try {
+                    const cmd = await buildDelegateCommand(engine, prompt, { ...(model ? { model } : {}), ...(cwd ? { cwd } : {}) });
+                    if (cmd) {
+                        const shellCmd = `${DELEGATE_ENV_MARK} ${JSON.stringify(cmd.cliPath)} ${cmd.args.map((a) => JSON.stringify(a)).join(' ')}`;
+                        const sess = spawnBackground(shellCmd, cmd.cwd);
+                        return {
+                            success: true,
+                            output: `🚀 已在**后台**起 ${engine} (session ${sess.id}) —— 你可以继续干别的 ✓。`
+                                + `\n它跑完的结果会**自动回灌**到下一轮(或随时 \`process poll ${sess.id}\` 取完整输出; \`process kill ${sess.id}\` 可停)。`
+                                + `\n❗别在原地等它, 也别重复发同一条委派。`
+                        };
+                    }
+                }
+                catch {
+                    /* 造不出命令/起不来 ⇒ 退回下面的同步委派 ✓ */
+                }
+            }
+            const timeoutMs = Number(args.timeoutMs) || undefined;
             const result = await delegateToEngine(engine, prompt, {
                 cwd: cwd || undefined,
                 ...(model ? { model } : {}),
+                ...(timeoutMs ? { timeoutMs } : {}),
                 ownerDid,
                 correlationId,
             });
             if (!result.success) {
-                return { success: false, error: result.error, output: result.output };
+                // 2026-10-01 (用户: 「开展子智能体后，bolloon 没有回归」):
+                //   实测体验 = 卡整整 2 分钟(默认超时)然后**白干**(进程被杀、活丢了) ✗ ⇒ 这里把话说清、给出可操作下一步 ✓
+                const timedOut = /超时/.test(String(result.error || ''));
+                const hint = timedOut
+                    ? '\n⇒ 这不是"坏了", 是**该换法**: ① 拆成更小的委派(每次 ≤ 1~2 分钟); ② 或改用 `terminal(background:true)` 起长活, 再用 `process poll/wait/kill` 管(后台进程能一直活着, 不会因为超时被丢 ✓); ③ 别在原样重试同一条委派。'
+                    : '';
+                return { success: false, error: `${result.error}${hint}`, output: result.output };
             }
             const handleLine = result.handle
                 ? `\n[delegate handle] contractVersion=${result.handle.contractVersion} delegateId=${result.handle.delegateId} ownerDid=${result.handle.ownerDid} correlationId=${result.handle.correlationId ?? '-'} capability=${result.handle.capability.slice(0, 16)}...`
@@ -653,7 +697,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('get_identity', {
         name: 'get_identity',
-        description: '获取当前智能体身份信息',
+        description: '取当前智能体身份 (名称 + DID). 结果在**同一会话内恒定** —— 问过一次就够了, 重复调用不会变; 要改身份用 set_persona.',
         parameters: {},
         execute: async () => {
             const id = ctx.identity;
@@ -665,7 +709,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('set_persona', {
         name: 'set_persona',
-        description: '更新智能体的 persona 信息',
+        description: '设置**当前 agent** 的人格(名称/描述/性格). 只在用户明确要求改人格时用; 查身份用 get_identity.',
         parameters: { persona_json: 'Persona JSON 对象' },
         execute: async (args) => {
             try {
@@ -691,7 +735,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('get_operation_logs', {
         name: 'get_operation_logs',
-        description: '获取约束层的操作日志',
+        description: '取约束层(护栏)的操作日志: 最近哪些动作被拦、按什么规则拦的. 排查"我明明做了却没生效"时先看这里.',
         parameters: {},
         execute: async () => {
             const logs = ctx.constraintLayer.getLogs();
@@ -707,7 +751,7 @@ export function registerBuiltinTools(ctx) {
     // 文件系统工具
     ctx.tools.set('list_files', {
         name: 'list_files',
-        description: '列出目录中的文件',
+        description: '列目录 (看**有哪些**文件). 只需要**找**特定文件 ⇒ glob_files; 要在文件**内容**里搜 ⇒ grep_files; 要读某个文件内容 ⇒ read_file.',
         parameters: { path: '目录路径（可选，默认为当前目录）' },
         execute: async (args) => {
             try {
@@ -726,7 +770,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('read_directory', {
         name: 'read_directory',
-        description: '读取目录内容，返回文件列表和目录结构',
+        description: '列一个目录下的条目(含子目录). 只要文件名清单 ⇒ list_files; 按通配找 ⇒ glob_files.',
         parameters: { path: '目录路径（可选，默认为当前目录）' },
         execute: async (args) => {
             try {
@@ -803,9 +847,93 @@ export function registerBuiltinTools(ctx) {
     // 2026-08-10: terminal — 灵活终端写命令 (用户要求: bolloon 自己写命令进 terminal, 少围栏).
     //   2026-08-12 (Task2): 支持 commands 数组并行执行; 与 shell_exec 统一走 runTerminalCommand.
     //   与 shell_exec 的区别: 直接接受完整 shell 命令字符串, 更适合模型自主写命令.
+    // 2026-10-01 (优化 #2 v1): **工具发现** —— 125 个工具不可能都记住, 给一个"按关键词找工具"的入口。
+    // 空关键词只回**分类索引**(名称清单), 有关键词才回"名称+用途摘要" ⇒ 不刷屏。
+    // 2026-10-01 (用户: 「skills 教训学习, bolloon 有吗, 从 hermes 触发的方法是什么, 学一下」):
+    //   **实测缺口**: `skill-loader` 把 1300 个技能**注册**进注册表 ✓, 但 `describeSkill` 只 import 从没调用 ✗
+    //   ⇒ 技能**描述从不进提示** ⇒ 模型不知道它们存在 ⇒ 技能触发链**断在这里** ✗。
+    //   她那边的做法: 启动自动装载 + 按**描述**在提示里露面 + 需要时用 `skill_view` 读全文 ✓。
+    //   bolloon 有 1300 个(她百来号) ⇒ 全量注入会撑爆提示 ✗ ⇒ 改成**两个发现工具**(和 `list_tools` 同一思路 ✓)。
+    ctx.tools.set('list_skills', {
+        name: 'list_skills',
+        description: '用于**找技能**: 给关键词(中文/英文都行)⇒ 返回已装载技能的名字+说明(≤20 条); 不给关键词 ⇒ 先给总数与前若干条. 找到后用 read_skill 读全文再照做.',
+        parameters: { keyword: '可选: 关键词(名字或说明里出现的词); 省略则给概览' },
+        async execute(args) {
+            const kw = String(args?.keyword ?? '').trim().toLowerCase();
+            const all = typeof ctx.listSkills === 'function' ? ctx.listSkills() : [];
+            if (!all.length)
+                return { success: true, output: '(当前没有装载技能)' };
+            if (!kw) {
+                return { success: true, output: `已装载 ${all.length} 个技能. 前 20 个:\n` + all.slice(0, 20).map((s) => `- ${s.name}: ${String(s.description || '').slice(0, 80)}`).join('\n') + '\n\n用 list_skills {keyword:"…"} 找具体的.' };
+            }
+            const hits = all.filter((s) => `${s.name} ${s.description || ''}`.toLowerCase().includes(kw));
+            if (!hits.length)
+                return { success: true, output: `没有技能匹配 "${kw}"(共 ${all.length} 个). 换个更短的词试试.` };
+            return { success: true, output: hits.slice(0, 20).map((s) => `- ${s.name}: ${String(s.description || '').slice(0, 100)}`).join('\n') + (hits.length > 20 ? `\n…还有 ${hits.length - 20} 个` : '') };
+        },
+    });
+    ctx.tools.set('read_skill', {
+        name: 'read_skill',
+        description: '用于**读技能全文**(先 list_skills 找名字). 按里面的步骤/判据做事, 别只读个大概就动手; 内容长的会截断.',
+        parameters: { name: '技能名(必填, 来自 list_skills)' },
+        async execute(args) {
+            const name = String(args?.name ?? '').trim();
+            if (!name)
+                return { success: false, error: '缺 name; 先用 list_skills 找' };
+            let body = null;
+            try {
+                body = ctx.getSkillBody ? await ctx.getSkillBody(name) : null;
+            }
+            catch {
+                body = null;
+            }
+            if (!body)
+                return { success: false, error: `没有这个技能: ${name}(用 list_skills 看有哪些)` };
+            const clipped = body.length > 8000 ? body.slice(0, 8000) + `\n…[已截断, 原文 ${body.length} 字符]` : body;
+            // 2026-10-01: 用量遥测(旁挂文件 ✓ 绝不写进用户 SKILL.md ✗)—— best-effort, 失败不影响本次读取 ✓
+            try {
+                const { bumpUsage } = await import('./skill-health.js');
+                bumpUsage(name);
+            }
+            catch { /* best-effort */ }
+            return { success: true, output: clipped };
+        },
+    });
+    ctx.tools.set('list_tools', {
+        name: 'list_tools',
+        description: '找不到该用哪个工具时用这个: 给关键词(如 "文件"/"钱包"/"群" / "grep")⇒ 返回匹配工具的名字+用途摘要; 不给关键词 ⇒ 回全部分类索引. 你**先** list_tools 摸清工具, 再动手.',
+        parameters: { keyword: '可选: 关键词 (工具名或用途里出现的词); 省略则回分类索引' },
+        async execute(args) {
+            const kw = String(args?.keyword ?? '').trim().toLowerCase();
+            const all = [...ctx.tools.entries()].map(([name, t]) => ({ name, desc: String(t?.description ?? '') }));
+            if (!kw) {
+                const groups = {};
+                for (const { name } of all) {
+                    const k = /wallet|chain|token|balance|tx|polymarket|safe|x402/.test(name) ? '链上/钱包'
+                        : /^(read|list|glob|grep|search)/.test(name) || /file|dir|doc/.test(name) ? '读/找文件'
+                            : /^(write|edit|mkdir|move|delete|copy|patch)/.test(name) ? '写/改文件'
+                                : /task|plan|todo|goal|run/.test(name) ? '任务/计划'
+                                    : /peer|channel|friend|send|broadcast|group|inbox|p2p/.test(name) ? 'P2P/沟通'
+                                        : /web|fetch|http|url/.test(name) ? '网络'
+                                            : '其它';
+                    (groups[k] ||= []).push(name);
+                }
+                const lines = Object.entries(groups).map(([k, v]) => `- ${k} (${v.length}): ${v.slice(0, 14).join(' ')}${v.length > 14 ? ' …' : ''}`);
+                return { success: true, output: `共 ${all.length} 个工具, 按类:\n${lines.join('\n')}\n\n用 list_tools {keyword:"…"} 查具体用途.` };
+            }
+            const hits = all.filter((t) => t.name.toLowerCase().includes(kw) || t.desc.toLowerCase().includes(kw));
+            if (!hits.length)
+                return { success: true, output: `没有工具匹配 "${kw}". 试试更短的词, 或 list_tools 不带关键词看分类.` };
+            return { success: true, output: hits.slice(0, 20).map((t) => `- ${t.name}: ${t.desc.replace(/\s+/g, ' ').slice(0, 90)}`).join('\n') };
+        },
+    });
     ctx.tools.set('terminal', {
         name: 'terminal',
-        description: '执行完整 shell 命令 (支持管道/重定向/写文件/跑脚本). 护栏只挡高危破坏操作 (sudo/格式化/rm -rf 根目录/写 ~/.bolloon 数据), 其余灵活放行. 适合: 写 HTML 文件、跑 python/node 脚本、查系统状态、装依赖. 多条命令用 commands 数组并行执行. 长命令 (服务器/构建/后台任务) 设 background=true 后台执行不阻塞对话. 也可直接传 code+language 自动写脚本执行 (便捷代码运行: python/js/ts/shell/html).',
+        description: '执行 shell 命令 (管道/重定向/跑脚本/装依赖/查系统状态). '
+            + '**上手前先看一眼这张对照表 —— 下面这些"终端习惯"都有专用工具, 用它们比敲 shell 更稳(有护栏、结果可核对)**: '
+            + 'grep/rg ⇒ grep_files · find/ls ⇒ glob_files / list_files · cat/head/tail ⇒ read_file · '
+            + 'sed/awk ⇒ edit_file · echo > 文件 / cat <<EOF ⇒ write_file(要一次性生成大量代码 ⇒ execute_code) · '
+            + 'curl 取网页正文 ⇒ fetch_url. 造文件请优先用 write_file / execute_code. 护栏只挡高危破坏操作 (sudo/格式化/rm -rf 根目录/写 ~/.bolloon 数据), 其余灵活放行. 适合: 写 HTML 文件、跑 python/node 脚本、查系统状态、装依赖. 多条命令用 commands 数组并行执行. 长命令 (服务器/构建/后台任务) 设 background=true 后台执行不阻塞对话. 也可直接传 code+language 自动写脚本执行 (便捷代码运行: python/js/ts/shell/html).',
         parameters: { command: '完整 shell 命令 (可选, 如: echo "<html>" > /tmp/site/index.html && ls /tmp/site)', commands: '可选: 多条命令数组 (并行执行), 每条独立字符串', code: '可选: 一段代码, 传 code+language 时自动写脚本执行 (便捷代码运行)', language: '可选: code 的语言 (python/js/ts/shell/html), 默认自动', timeoutMs: '超时毫秒, 默认 30000', background: '可选: true 后台执行, 立即返回 session_id (用 process 工具 poll/wait/kill)' },
         execute: async (args) => {
             const timeoutMs = Number(args.timeoutMs) || 30000;
@@ -826,10 +954,25 @@ export function registerBuiltinTools(ctx) {
     //   长命令不阻塞对话: terminal(background=true) 启动 → process 工具轮询/等待/终止.
     ctx.tools.set('process', {
         name: 'process',
-        description: '管理后台进程 (terminal background=true 启动的). action: poll(查状态, 不阻塞) / wait(等结束, 最多 timeoutMs) / kill(终止) / list(列全部). 长期运行命令的阻塞问题用它解决.',
+        description: '管理后台进程与常驻服务. action: poll(查状态, 不阻塞) / wait(等结束, 最多 timeoutMs) / kill(终止) / list(列全部 shell 后台进程) / **services(列常驻服务: 社交心跳·P2P·OrbitDB 群聊·文档接收)** / **service(启停某个常驻服务, 需 name + op)**. 长期运行命令与去中心化交流进程都用它管.',
         parameters: { session_id: '后台进程 session_id (必填, poll/wait/kill 用)', action: 'poll | wait | kill | list (默认 poll)', timeoutMs: 'wait 模式等待上限毫秒, 默认 30000' },
         execute: async (args) => {
             const action = String(args.action || 'poll').trim().toLowerCase();
+            // 2026-10-01 (用户: 「process 也要可以管理群聊和去中心化交流进程」):
+            //   services ⇒ 看常驻服务(社交心跳/P2P/OrbitDB 群聊/文档接收); service ⇒ 启停(只对真能启停的放行)
+            if (action === 'services') {
+                return { success: true, output: ctx.managedServices ? ctx.managedServices.describe() : '(没有注册常驻服务)' };
+            }
+            if (action === 'service') {
+                const nm = String(args.name || '').trim();
+                const op = String(args.op || '').trim().toLowerCase();
+                if (!nm || (op !== 'start' && op !== 'stop'))
+                    return { success: false, error: 'action=service 需要 name + op(start|stop)' };
+                if (!ctx.managedServices)
+                    return { success: false, error: '本进程没有注册常驻服务' };
+                const r = await ctx.managedServices.control(nm, op);
+                return r.ok ? { success: true, output: r.output } : { success: false, error: r.output };
+            }
             try {
                 const { pollSession, waitSession, killSession, listSessions, isValidSessionId } = await import('./process-runner.js');
                 if (action === 'list') {
@@ -879,15 +1022,19 @@ export function registerBuiltinTools(ctx) {
     // write_file / edit_file / git_*
     ctx.tools.set('write_file', {
         name: 'write_file',
-        description: '写入一个文件. 路径必须在白名单. 大文件 (> 100KB) 会被拒. 命中护栏黑名单会拒.',
-        parameters: { path: '相对路径 (必填, 相对 cwd)', content: '文件内容 (必填)' },
+        description: '写入**一个**文件 (整文件覆盖). 路径须在白名单内, 命中护栏黑名单会拒. '
+            + '**要写大量代码时按这个分工**: 一个文件 ⇒ 就用本工具(单文件上限 2MB) · '
+            + '**多个文件 / 要生成成套代码** ⇒ 用 execute_code 一次写完(一次调用写 N 个文件, 不逐个来回) · '
+            + '别用 terminal 的 heredoc/echo 来造文件(容易转义出错、也看不出写了什么).',
+        parameters: { path: '相对路径 (必填, 相对 cwd)', content: '文件内容 (必填; 单文件上限 2MB)' },
         execute: async (args) => {
             const relPath = String(args.path || '').trim();
             const content = String(args.content ?? '');
             if (!relPath)
                 return { success: false, error: 'path 必填' };
-            if (content.length > 100_000)
-                return { success: false, error: `内容过大 (${content.length} > 100000 字节), 请分块写` };
+            // 2026-10-01: 上限 100KB → 2MB —— 原来的上限让"写一个大文件"只能分块, 反而促成了碎片化的多次调用
+            if (content.length > 2_000_000)
+                return { success: false, error: `内容过大 (${content.length} > 2000000 字节): 请用 execute_code 在脚本里分块写, 或拆成多个文件` };
             const pathResult = checkWritePath(relPath);
             if (!pathResult.allowed) {
                 return { success: false, error: `路径被护栏拒: ${pathResult.reason}` };
@@ -1089,7 +1236,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('mkdir', {
         name: 'mkdir',
-        description: '创建一个或多个目录. 自动 mkdir -p.',
+        description: '新建一个目录(可带 -p 建多级). 只是**列**目录用 list_files / read_directory, 别用这个.',
         parameters: { path: '目录路径 (必填, 相对 cwd)' },
         execute: async (args) => {
             const relPath = String(args.path || '').trim();
@@ -1151,7 +1298,7 @@ export function registerBuiltinTools(ctx) {
                 const { promisify } = await import('util');
                 const pExecFile = promisify(execFile);
                 const argv = ['-rn', '--include=' + (args.filePattern || '*'), pattern, searchPath];
-                const { stdout, stderr } = await pExecFile('grep', argv, { cwd: ctx.cwd, maxBuffer: 1024 * 1024 });
+                const { stdout, stderr } = await pExecFile('grep', argv, { cwd: ctx.cwd, maxBuffer: 32 * 1024 * 1024 });
                 const lines = stdout.split('\n').filter(Boolean).slice(0, 50);
                 return { success: true, output: `🔍 grep "${pattern}" in ${searchPath} (${args.filePattern || '*'}, 最多 50 行):\n${lines.join('\n')}${lines.length === 50 ? '\n... (truncated)' : ''}` };
             }
@@ -1464,7 +1611,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('update_task', {
         name: 'update_task',
-        description: '更新任务的某一步状态.',
+        description: '更新任务的某一步 (标记 done/blocked + 备注). 改**整条计划**(目标/加步骤) ⇒ 用计划类工具; 只是查进度 ⇒ get_task.',
         parameters: { task_id: '任务 id', step_id: '步骤 id', status: '新状态', result_summary: '可选', error: '可选' },
         execute: async (args) => {
             const taskId = String(args.task_id || '').trim();
@@ -1498,7 +1645,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('get_task', {
         name: 'get_task',
-        description: '查任务的当前状态和步骤进度.',
+        description: '查一个任务的当前状态与步骤进度. 要看**每一步的细节输出** ⇒ get_operation_logs; 想改状态 ⇒ update_task.',
         parameters: { task_id: '任务 id (必填)' },
         execute: async (args) => {
             const taskId = String(args.task_id || '').trim();
@@ -1530,7 +1677,7 @@ export function registerBuiltinTools(ctx) {
     });
     ctx.tools.set('list_tasks', {
         name: 'list_tasks',
-        description: '列出最近 N 个任务 (默认 10).',
+        description: '列任务清单(默认只看未完成). 要看某个任务的步骤 ⇒ get_task; 想看执行细节 ⇒ get_operation_logs.',
         parameters: { limit: '可选, 默认 10' },
         execute: async (args) => {
             const limit = Number(args.limit) || 10;
@@ -1682,10 +1829,22 @@ export function registerBuiltinTools(ctx) {
                         triggers = t.map(String);
                 }
                 catch { /* triggers 解析失败忽略 */ }
+                // 2026-10-01: 变更前先留快照(覆盖已有技能时才有内容 ✓)+ 记"谁建的"(决定自审有没有资格治理它 ✓)
+                const { captureSkillBefore, appendLedger, currentWriteOrigin } = await import('./skill-ledger.js');
+                const { markCreatedBy } = await import('./skill-health.js');
+                const before = captureSkillBefore(skillFilePath(name, args.scope === 'project' ? 'project' : 'user'));
                 const r = await createSkill(name, String(args.description || ''), body, {
                     scope: args.scope === 'project' ? 'project' : 'user',
                     triggers,
                 });
+                if (r.ok) {
+                    const after = captureSkillBefore(r.path);
+                    appendLedger({ origin: currentWriteOrigin(), tool: 'create_skill', skill: name, file: r.path, beforeSha: before.beforeSha, beforeBytes: undefined, afterSha: after.beforeSha, bytesBefore: before.bytesBefore, bytesAfter: after.bytesBefore });
+                    try {
+                        markCreatedBy(name, currentWriteOrigin());
+                    }
+                    catch { /* best-effort */ }
+                }
                 return r.ok
                     ? { success: true, output: `✅ skill '${name}' 已写入 ${r.path}` }
                     : { success: false, error: r.error };
@@ -1708,9 +1867,15 @@ export function registerBuiltinTools(ctx) {
         execute: async (args) => {
             try {
                 const { updateSkill } = await import('./skill-writer.js');
+                const { reviewMayTouch, captureSkillBefore, appendLedger, currentWriteOrigin } = await import('./skill-ledger.js');
                 const name = String(args.name || '').trim();
                 if (!name)
                     return { success: false, error: 'name 必填' };
+                // 2026-10-01 **写来源隔离**: 自审只许治理自己造出来的技能 ✓ —— 用户点名要的归用户 ✓
+                const may = reviewMayTouch(name);
+                if (!may.ok)
+                    return { success: false, error: `拒绝(写来源隔离): ${may.reason}` };
+                const before = captureSkillBefore(skillFilePath(name, 'user'));
                 let triggers;
                 try {
                     const t = JSON.parse(String(args.triggers || '[]'));
@@ -1724,6 +1889,10 @@ export function registerBuiltinTools(ctx) {
                     body: args.body ? String(args.body) : undefined,
                     triggers,
                 });
+                if (r.ok) {
+                    const after = captureSkillBefore(r.path || skillFilePath(name, 'user'));
+                    appendLedger({ origin: currentWriteOrigin(), tool: 'update_skill', skill: name, file: r.path || skillFilePath(name, 'user'), beforeSha: before.beforeSha, afterSha: after.beforeSha, bytesBefore: before.bytesBefore, bytesAfter: after.bytesBefore });
+                }
                 return r.ok
                     ? { success: true, output: `✅ skill '${name}' 已更新 ${r.path}` }
                     : { success: false, error: r.error };
@@ -3364,7 +3533,7 @@ export function registerBuiltinTools(ctx) {
     // execute_code — 独立代码执行工具 (与 terminal 的 code 便捷路径同源, 这里给独立入口)
     ctx.tools.set('execute_code', {
         name: 'execute_code',
-        description: '写一段代码并执行, 拿回 stdout/stderr/退出码。适合计算、数据处理、试算法、快速验证想法。支持 python / js / ts / shell / html。需要多步 shell 操作用 terminal; 需要长期进程用 terminal background=true。',
+        description: '写一段代码并执行, 拿回 stdout/stderr/退出码。适合: 计算 · 数据处理 · 试算法 · 快速验证想法 · **一次生成大量代码**(在脚本里循环写多个文件 —— 这是"成套代码/多文件"的**推荐路径**, 一次调用顶几十次 write_file)。支持 python / js / ts / shell / html。需要多步 shell 操作用 terminal; 需要长期进程用 terminal background=true。',
         parameters: {
             code: '要执行的代码 (必填)',
             language: '语言: python | js | ts | shell (默认 python)',
@@ -3532,7 +3701,7 @@ export function registerWalletTools(ctx) {
     });
     ctx.tools.set('wallet_import', {
         name: 'wallet_import',
-        description: '导入已有 EVM 钱包 (用助记词或私钥)',
+        description: '从文件导入 EVM 钱包到本机台账(私钥值不会回显). 新建钱包 ⇒ 用创建类工具, 别拿它当通用入口.',
         parameters: { mnemonic: '可选, 12/15/18/21/24 词助记词', privateKey: '可选, 0x 开头的私钥' },
         execute: async (args) => {
             try {
@@ -3561,7 +3730,7 @@ export function registerWalletTools(ctx) {
     });
     ctx.tools.set('wallet_get_balance', {
         name: 'wallet_get_balance',
-        description: '查 EVM 钱包 ETH 余额.',
+        description: '查 EVM 钱包 ETH 余额. 想看**全部**资产/代币 ⇒ 用钱包总览类工具; 想转账 ⇒ 转账工具.',
         parameters: { address: '0x 开头的 EVM 地址 (必填)', rpcUrl: '可选 RPC URL (默认 eth.llamarpc.com)' },
         execute: async (args) => {
             try {
@@ -3612,7 +3781,7 @@ export function registerWalletTools(ctx) {
     });
     ctx.tools.set('wallet_transfer_token', {
         name: 'wallet_transfer_token',
-        description: '用 EVM 钱包转 ERC20 token.',
+        description: '转 ERC20 代币到指定地址(要合约地址+金额). 转**原生币**(ETH)用另一个工具; 先确认链和余额.',
         parameters: { privateKey: '私钥 (必填)', tokenAddress: 'ERC20 合约地址 (必填)', to: '接收地址 (必填)', amount: 'token 数量', decimals: '可选 token decimals', rpcUrl: '可选 RPC URL' },
         execute: async (args) => {
             try {
@@ -3656,7 +3825,7 @@ export function registerWalletTools(ctx) {
     // Polymarket
     ctx.tools.set('polymarket_list_markets', {
         name: 'polymarket_list_markets',
-        description: '列出 Polymarket 预测市场.',
+        description: '列 Polymarket 预测市场(可按分类/状态筛). 查某个市场的**价格/盘口** ⇒ 用对应详情工具.',
         parameters: { limit: '可选 数量 (默认 50)', offset: '可选 偏移', closed: '可选 是否只显示已关闭' },
         execute: async (args) => {
             try {
@@ -3679,7 +3848,7 @@ export function registerWalletTools(ctx) {
     });
     ctx.tools.set('polymarket_get_market', {
         name: 'polymarket_get_market',
-        description: '获取单个 Polymarket 市场的详情.',
+        description: '查某个 Polymarket 市场的详情(题目/结算/盘口). 只是**列**市场 ⇒ polymarket_list_markets.',
         parameters: { marketId: '市场 ID (必填)' },
         execute: async (args) => {
             try {
@@ -3950,7 +4119,7 @@ export function registerWalletTools(ctx) {
     // Safe
     ctx.tools.set('safe_deploy', {
         name: 'safe_deploy',
-        description: '部署 Safe 多签钱包.',
+        description: '部署 Gnosis Safe 多签钱包 (建钱包/加签名人). 只是**查**多签状态别用这个.',
         parameters: { owners: 'JSON 数组 owner 地址 (必填)', threshold: '需要几个签名 (必填)' },
         execute: async (args) => {
             try {