mocode-ai 1.2.2 → 1.2.4

package/dist/skills/runner.js

@@ -1,43 +1,201 @@
-// 可执行 skill runner:把 skill 的「工作流」封装成隔离子 agent 执行。
-// 对齐 Claude Code Agent Skills 的 context: fork 模型——skill 内容成为驱动子 agent
-// 的 prompt(协议/操作规范),子 agent 用受控工具子集在隔离上下文里执行,结果摘要回灌。
+// skill 执行内核(L2-①/②/③):占位符渲染 + 动态命令注入 + fork 子 agent 执行。
+// 被 use_skill(inline 渲染 / fork 引导)与 run_skill(fork 执行)共用。
 //
-// 依赖:agent/spawn.ts 的 spawnAgent(已具备隔离 history / 工具白名单 / maxSteps /
-// read-write overlay / abort 透传 / usage 统计),这里只做「渲染 + 参数映射」,不重复造执行器。
+// 设计要点(对齐 docs/skill-system-design.md §3.3–3.5):
+//  - 不为 scripts/ 做任何新机制:作者用 ${SKILL_DIR} 拼出绝对路径,模型自行 run_command。
+//  - 不为参数做 shell 插值:参数渲染进 prompt 文本,落到命令行时是模型写 run_command,
+//    走既有 denylist + 权限确认。转义器本身就是注入面,不写它比写对它更安全。
+//  - !`cmd` 注入仅在非 project 或已信任 skill 上允许;单 skill 最多 4 处,单处输出截 4KB。
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { getSkillBody, findSkill } from './index.js';
+import { isSkillTrusted, ensureSkillTrust } from './trust.js';
+import { mapSkillTools } from './toolmap.js';
 import { spawnAgent } from '../agent/spawn.js';
-/** 子 agent(Explore/Plan 等)类型 → 只读/写模式。缺省按 read 保守处理。 */
-const AGENT_READ_MODE = new Set(['explore', 'plan', 'read', 'research']);
+import { runCommandRaw } from '../tools/builtins/run-command.js';
+/** 把 raw ChangeSet 折成 ToolOutcome 需要的 ChangeSetSummary(哈希缺失位填 null,仅用于展示)。 */
+function toChangeSetSummary(cs) {
+    return {
+        id: cs.id,
+        changedFiles: cs.changes.map((c) => c.path),
+        changes: cs.changes.map((c) => ({
+            path: c.path,
+            operation: c.operation,
+            beforeHash: null,
+            afterHash: null,
+        })),
+    };
+}
+const MAX_INJECTIONS = 4;
+const MAX_INJECTION_OUTPUT = 4096;
+const INJECT_TIMEOUT = 10_000;
+/** fork 子 agent 收到的协议头:明确它是「执行某个 skill」,并要求最终给一句话摘要。 */
+const SKILL_PROTOCOL_HEADER = `You are executing a packaged skill workflow. Follow the instructions below literally and completely. When done, end your reply with a concise summary of what you did, the files changed, and any issues. Do not ask the user questions unless blocked.`;
+/** 把 $ARGUMENTS / $1..$9 / ${SKILL_DIR} 渲染进正文。 */
+function substituteArgs(body, args, skillDir) {
+    const values = args && typeof args === 'object' ? Object.values(args) : [];
+    return body.replace(/\$(?:ARGUMENTS|(\d)|\{SKILL_DIR\})/g, (_m, digit) => {
+        if (digit != null) {
+            const idx = Number(digit) - 1;
+            const v = values[idx];
+            return v === undefined ? '' : typeof v === 'string' ? v : JSON.stringify(v);
+        }
+        return skillDir;
+    });
+}
+/** 执行 !`cmd` 注入:逐个跑命令,用 fenced 输出替换;失败降级为提示而非中断。 */
+async function injectCommands(body, skillDir, signal) {
+    const re = /!`([^`]+)`/g;
+    let count = 0;
+    const out = [];
+    let m;
+    while ((m = re.exec(body)) !== null && count < MAX_INJECTIONS) {
+        count++;
+        const cmd = m[1];
+        let replacement;
+        try {
+            const res = await runCommandRaw(cmd, INJECT_TIMEOUT, signal, skillDir);
+            if (res.status === 'denied') {
+                replacement = `(command denied: ${res.output})`;
+            }
+            else if (res.status === 'timed_out') {
+                replacement = '(command timed out)';
+            }
+            else if (res.status === 'aborted') {
+                replacement = '(command aborted)';
+            }
+            else {
+                const text = res.output.length > MAX_INJECTION_OUTPUT
+                    ? res.output.slice(0, MAX_INJECTION_OUTPUT) + '\n…(truncated)'
+                    : res.output;
+                replacement = text.trim() || '(no output)';
+            }
+        }
+        catch (e) {
+            replacement = `(command failed: ${e instanceof Error ? e.message : String(e)})`;
+        }
+        out.push({ full: m[0], replacement: '```\n' + replacement + '\n```' });
+    }
+    let result = body;
+    for (const { full, replacement } of out) {
+        result = result.replace(full, replacement);
+    }
+    return result;
+}
+/**
+ * 渲染 skill 正文(占位符 + 可选命令注入)。
+ * 非 project 或已信任的 project skill 才执行注入;否则先尝试一次性确认,未通过则跳过注入。
+ * 返回 null 表示正文缺失(调用方生成「未找到」错误)。
+ */
+export async function renderSkillBody(skill, args, signal) {
+    const raw = getSkillBody(skill.name);
+    if (raw === null)
+        return null;
+    let body = substituteArgs(raw, args, skill.dir);
+    if (/!`[^`]+`/.test(body)) {
+        // 非 project 恒信任;project 依次查信任记录、再弹一次性确认。
+        // ensureSkillTrust 的 true 覆盖 'trusted'(已记录)与 'once'(仅本次)两种,直接据此注入。
+        const trusted = skill.origin !== 'project' || isSkillTrusted(skill) || (await ensureSkillTrust(skill));
+        if (trusted) {
+            body = await injectCommands(body, skill.dir, signal);
+        }
+        else {
+            // 未信任:清掉注入标记,避免把未授权命令留在提示里。
+            body = body.replace(/!`[^`]+`/g, '_(command injection skipped: skill not trusted)_');
+        }
+    }
+    return body;
+}
+/** 把 SpawnResult 转成 ToolOutcome,汇总/计费/变更集透传,不丢回滚信息。 */
+function toOutcome(res) {
+    const status = res.status === 'completed' ? 'success' : res.status === 'aborted' ? 'aborted' : 'error';
+    return {
+        status,
+        code: res.status === 'completed' ? 'OK'
+            : res.status === 'aborted' ? 'ABORTED'
+                : 'EXECUTION_ERROR',
+        retryable: false,
+        output: res.summary ?? (res.status === 'failed' ? '(skill failed with no output)' : ''),
+        changeSet: res.changeSet ? toChangeSetSummary(res.changeSet) : undefined,
+        usage: res.usage,
+    };
+}
+/** 读取 skill 目录内附属文件(L2 渐进式披露);越界 / 不存在 / 过大返 null。 */
+export function readSkillFile(skill, file, maxBytes) {
+    // 归一为绝对路径,并强制留在 skill.dir 内(禁止 ../ 逃逸)。
+    const base = resolve(skill.dir);
+    const abs = resolve(base, file);
+    if (abs !== base && !abs.startsWith(base + sep))
+        return null;
+    if (!existsSync(abs))
+        return null;
+    try {
+        if (statSync(abs).size > maxBytes)
+            return `(file too large: ${file})`;
+        return readFileSync(abs, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** 能产生副作用的 mocode 工具;用于在未显式声明 agent: 时推断 fork 子 agent 的模式。 */
+const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'run_command']);
 /**
- * 把参数渲染进 skill 正文:替换 $ARGUMENTS / ${} / $1 / ${1} 等占位符。
- * 仅替换存在的占位符,无占位符正文原样返回(兼容纯文本 skill)。
+ * fork 子 agent 模式:`agent:` 显式声明优先;否则按工具面推断——
+ * 未声明 allowed-tools(完整工具集)或白名单含写工具 → 'write',纯只读白名单 → 'read'。
+ * 避免写类 skill 因缺省字段被静默降级为只读。
+ * 导出仅供 scripts/check-skills.ts 离线断言。
  */
-export function renderBody(skill, args) {
-    const body = skill.body?.trim() || '';
-    if (!body)
-        return body;
-    const arg = args ?? {};
-    const named = JSON.stringify(arg, null, 2) || '{}';
-    const positional = Array.isArray(arg)
-        ? arg.map((v) => String(v))
-        : (Object.values(arg).map((v) => String(v)));
-    const at = (i) => positional[i] ?? '';
-    return body
-        .replace(/\$ARGUMENTS\b/gi, named)
-        .replace(/\$\{?(\d+)\}?/g, (_m, idx) => at(Number(idx) - 1))
-        .replace(/\$\{ARGUMENTS\}/gi, named);
+export function resolveSpawnMode(skill, tools) {
+    if (skill.agentMode)
+        return skill.agentMode;
+    if (tools === null || tools.some((t) => WRITE_TOOLS.has(t)))
+        return 'write';
+    return 'read';
 }
 /**
- * fork 执行:把 skill 作为隔离子 agent 的协议,派生受控子 agent 执行其工作流。
- * skill.allowed_tools → 工具白名单;skill.agent → 只读/写模式;args 序列化进用户 prompt。
+ * 执行一个 skill(无论 inline 还是 fork 都走隔离子 agent,保证「可执行」语义统一):
+ *  - 找不到 → UNKNOWN_TOOL 语义 error
+ *  - 执行面门禁(ensureSkillTrust)未过 → denied
+ *  - 渲染正文 → spawnAgent(白名单工具 / mode / maxSteps / signal)
+ *  - 子 agent 摘要回灌为 output,usage / changeSet 透传
  */
-export async function runSkillForked(skill, args, ctx) {
-    const rendered = renderBody(skill, args);
-    const mode = skill.agent && AGENT_READ_MODE.has(skill.agent.trim().toLowerCase()) ? 'read' : 'write';
-    return spawnAgent({
-        prompt: `Execute the "${skill.name}" skill workflow now. Follow its protocol exactly, use the available tools, and when done return a concise summary of what you did, key findings, any files changed, and blockers.\n\n--- Skill protocol ---\n\n${rendered || '(skill body is empty; follow the skill contract described in the list above)'}`,
-        tools: skill.allowed_tools,
-        mode,
+export async function runSkill(a, ctx) {
+    const name = String(a.name ?? '').trim();
+    if (!name) {
+        return { status: 'error', code: 'INVALID_ARGUMENTS', retryable: false, output: '错误:缺少 skill 名。' };
+    }
+    const skill = findSkill(name);
+    if (!skill) {
+        return { status: 'error', code: 'UNKNOWN_TOOL', retryable: false, output: `错误:未找到 skill "${name}"。` };
+    }
+    if (!(await ensureSkillTrust(skill))) {
+        return {
+            status: 'denied',
+            code: 'PERMISSION_DENIED',
+            retryable: false,
+            output: `拒绝:skill "${name}" 未获信任,已取消执行。`,
+        };
+    }
+    let body = await renderSkillBody(skill, a.args, ctx?.signal);
+    if (body === null) {
+        return { status: 'error', code: 'UNKNOWN_TOOL', retryable: false, output: `错误:未找到 skill "${name}" 的正文。` };
+    }
+    const { tools, unknown } = mapSkillTools(skill.allowedTools);
+    if (unknown.length) {
+        // 仅记到正文前导,模型可感知哪些 allowed-tools 被忽略(不阻断执行)。
+        body = `> 注意:以下 allowed-tools 无法映射到 mocode 工具,已忽略: ${unknown.join(', ')}\n\n` + body;
+    }
+    const res = await spawnAgent({
+        prompt: SKILL_PROTOCOL_HEADER + '\n\n' + body,
+        tools: tools ?? undefined,
+        mode: resolveSpawnMode(skill, tools),
+        maxSteps: skill.maxSteps,
         signal: ctx?.signal,
-        context: args ? `Skill arguments:\n${JSON.stringify(args, null, 2)}` : undefined,
+        context: a.context,
+        systemPromptSuffix: `You are executing the "${skill.name}" skill. SKILL_DIR=${skill.dir}`,
+        quiet: true, // fork skill 是 opaque workflow,不产可展开 batch
+        quietLabel: `执行 ${skill.name}…`,
     });
+    return toOutcome(res);
 }

package/dist/skills/toolmap.js

@@ -0,0 +1,56 @@
+// skill 工具名映射(叶子模块,零依赖,避免激活态/runner 与 tools/constants 之间的循环依赖)。
+// 把 Agent Skills 开放标准里的工具 token 归一为 mocode 工具名。
+//
+// 关键约束:只做「名字翻译」,绝不把 `Bash(git:*)` 的括号内容当作命令白名单——
+// mocode 的权限是 run_command 粒度(permissions/index.ts 的 permissionFingerprint),
+// 不解析 shell 前缀。`Bash(git:*)` 在 mocode 里等同于「允许子 agent 用 run_command」,
+// 具体命令仍走 denylist + 沙箱。
+/** 标准 token(大小写不敏感)→ mocode 工具名。带括号的 `Bash(...)` 也按 Bash 前缀归并。
+ * 同时接受 mocode 原生工具名(write_file / web_fetch…),即标准名与原生名两种写法。 */
+const TOKEN_MAP = [
+    { re: /^read(_file)?$/i, tool: 'read_file' },
+    { re: /^grep$/i, tool: 'grep' },
+    { re: /^glob$/i, tool: 'glob' },
+    { re: /^bash$/i, tool: 'run_command' }, // Bash(...) 也落到 run_command
+    { re: /^run_command$/i, tool: 'run_command' },
+    { re: /^write(_file)?$/i, tool: 'write_file' },
+    { re: /^edit(_file)?$/i, tool: 'edit_file' },
+    { re: /^web_?search$/i, tool: 'web_search' },
+    { re: /^web_?fetch$/i, tool: 'web_fetch' },
+    { re: /^use_skill$/i, tool: 'use_skill' },
+    { re: /^run_skill$/i, tool: 'run_skill' },
+    { re: /^memory_search$/i, tool: 'memory_search' },
+    { re: /^memory_list$/i, tool: 'memory_list' },
+];
+/** 把单个标准 token 映射成 mocode 工具名;未知 token 返 null(调用方记 warning + 忽略)。 */
+export function mapSkillToolName(token) {
+    const t = token.trim();
+    if (!t)
+        return null;
+    // 去掉可能的括号后缀(Bash(git:*) → Bash)
+    const base = t.replace(/\(.*\)$/, '').trim();
+    for (const { re, tool } of TOKEN_MAP) {
+        if (re.test(base))
+            return tool;
+    }
+    return null;
+}
+/** 把 allowed-tools / disallowed-tools 的 token 列表映射为 mocode 工具名集合;
+ * 未知 token 收集到 unknown 返回,供调用方记 warning。返回 null 表示未声明(不约束)。 */
+export function mapSkillTools(tokens) {
+    if (!tokens || tokens.length === 0)
+        return { tools: null, unknown: [] };
+    const tools = [];
+    const unknown = [];
+    for (const tk of tokens) {
+        const mapped = mapSkillToolName(tk);
+        if (mapped) {
+            if (!tools.includes(mapped))
+                tools.push(mapped);
+        }
+        else {
+            unknown.push(tk);
+        }
+    }
+    return { tools: tools.length ? tools : null, unknown };
+}

package/dist/skills/trust.js

@@ -0,0 +1,134 @@
+// skill 信任门禁(执行面的安全前置)。
+// 来源策略:
+//  - builtin:恒信任(随 mocode 发布)。
+//  - user(~/.claude|.mocode/skills):免门禁(用户自己放的)。
+//  - project(<cwd>/.mocode/skills):很可能来自 git clone,首次使用执行面时一次性确认;
+//    记录 sha256(SKILL.md + scripts/** + references/**),内容变更 → 失效重问。
+//
+// 非 TTY(管道 / CI / host 嵌入)严格失败关闭:未信任的 project skill 执行面一律拒绝,
+// 对齐 Snyk 关于注册表 skill 携带恶意载荷的数据(设计文档 §1.4)。
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { promptIntervention } from '../ui/intervention.js';
+import * as layout from '../ui/layout.js';
+const TRUST_PATH = join(homedir(), '.mocode', 'skill-trust.json');
+let trustCache = null;
+function loadTrust() {
+    if (trustCache)
+        return trustCache;
+    try {
+        const parsed = JSON.parse(readFileSync(TRUST_PATH, 'utf8'));
+        trustCache = parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        trustCache = {};
+    }
+    return trustCache;
+}
+function saveTrust(rec) {
+    trustCache = rec;
+    try {
+        mkdirSync(dirname(TRUST_PATH), { recursive: true });
+        writeFileSync(TRUST_PATH, JSON.stringify(rec, null, 2));
+    }
+    catch {
+        // 写入失败(权限 / 只读 home)不阻断,仅本次会话内存态生效。
+    }
+}
+/** 递归收集目录下所有文件(绝对路径)。 */
+function collectFiles(dir, out) {
+    let ents;
+    try {
+        ents = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of ents) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            collectFiles(p, out);
+        else
+            out.push(p);
+    }
+}
+/** 计算 skill 内容哈希(SKILL.md + scripts/** + references/**)。 */
+export function computeSkillHash(skill) {
+    const h = createHash('sha256');
+    const files = [skill.skillMdPath];
+    for (const sub of ['scripts', 'references']) {
+        const d = join(skill.dir, sub);
+        if (existsSync(d))
+            collectFiles(d, files);
+    }
+    files.sort();
+    for (const f of files) {
+        try {
+            h.update(f + '\0');
+            h.update(readFileSync(f));
+        }
+        catch {
+            // 单文件读失败:跳过该项(哈希覆盖其余内容,足够检测变更)。
+        }
+    }
+    return h.digest('hex');
+}
+/** 该 skill 当前是否已受信任(内容未变)。非 project 来源恒 true。 */
+export function isSkillTrusted(skill) {
+    if (skill.origin !== 'project')
+        return true;
+    const rec = loadTrust()[skill.name];
+    if (!rec)
+        return false;
+    return rec.hash === computeSkillHash(skill);
+}
+function recordTrust(skill) {
+    const rec = loadTrust();
+    rec[skill.name] = { hash: computeSkillHash(skill), trustedAt: Date.now() };
+    saveTrust(rec);
+}
+/**
+ * 面向用户的信任确认。非 TTY 直接拒绝(失败关闭)。
+ * 返回 'trusted'(记录哈希) / 'once'(仅本次) / 'deny'。
+ */
+export async function promptTrust(skill) {
+    if (!layout.isActive())
+        return 'deny';
+    const res = await promptIntervention({
+        type: 'choice',
+        title: `信任并运行 skill "${skill.name}"?`,
+        detail: `${skill.dir}\n` +
+            `该 skill 配置了执行面(fork / scripts / allowed-tools)。首次执行需确认;` +
+            `其 SKILL.md / scripts / references 内容变更后将重新询问。`,
+        options: [
+            { label: '信任并运行', detail: '记录内容哈希,今后自动信任' },
+            { label: '仅本次运行', detail: '本会话执行一次,不记录' },
+            { label: '拒绝', detail: '不执行' },
+        ],
+        allowCustom: false,
+    });
+    if (res.action === 'cancelled')
+        return 'deny';
+    const v = res.value ?? '拒绝';
+    if (v.startsWith('信任')) {
+        recordTrust(skill);
+        return 'trusted';
+    }
+    if (v.startsWith('仅本次'))
+        return 'once';
+    return 'deny';
+}
+/**
+ * 执行面前的信任检查:已信任返回 true;未信任则弹确认。
+ * 非 project / 已信任 → true;未信任 project 在非 TTY → false;用户拒绝 → false。
+ */
+export async function ensureSkillTrust(skill) {
+    if (skill.origin !== 'project')
+        return true;
+    if (isSkillTrusted(skill))
+        return true;
+    const decision = await promptTrust(skill);
+    return decision !== 'deny';
+}

package/dist/tools/builtins/index.js

@@ -11,6 +11,7 @@ import { grepTool } from './grep.js';
 import { webSearchTool } from './web-search.js';
 import { webFetchTool } from './web-fetch.js';
 import { useSkillTool } from './use-skill.js';
+import { runSkillTool } from './run-skill.js';
 import { askHumanTool } from './ask-human.js';
 import { planUpdateTool } from './plan-update.js';
 import { memorySaveTool } from './memory-save.js';
@@ -60,6 +61,7 @@ const CAPABILITIES = {
     web_search: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
     web_fetch: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
     use_skill: { effect: 'read', concurrency: 'serial' },
+    run_skill: { effect: 'process', concurrency: 'serial', delegatesResourceLocks: true, supportsAbort: true },
     ask_human: { effect: 'read', concurrency: 'serial' },
     // plan_update 只写内部 notes.md(session 工作面),不作为用户代码 mutation 追踪/回滚/diff;
     // 串行即可(调用不频繁),固定资源键让并发调用排队。
@@ -94,6 +96,7 @@ const rawBuiltinTools = [
     webSearchTool,
     webFetchTool,
     useSkillTool,
+    runSkillTool,
     askHumanTool,
     planUpdateTool,
     ..._memoryTools,

package/dist/tools/builtins/run-skill.js

@@ -0,0 +1,42 @@
+import { runSkill } from '../../skills/runner.js';
+// ---------- run_skill ----------
+// 唯一新增的常驻工具(L2-①):把某个 skill 作为隔离工作流(fork 子 agent)执行并返回摘要。
+// 无论装 100 个还是 1000 个 skill,常驻工具表只多这 1 个。上下文 / 工具面 / 副作用 / 中断
+// 全部由 spawnAgent 现成能力承接(设计 §3.4)。
+export const runSkillTool = {
+    name: 'run_skill',
+    description: 'Execute a skill as an isolated workflow (forked sub-agent) and return its summary. ' +
+        'Use for skills marked [fork] in the skill list. Args are rendered into the skill body.',
+    parameters: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Name of the skill to execute (see the skill list in the system prompt).',
+            },
+            args: {
+                type: 'object',
+                description: 'Arguments rendered into the skill body ($ARGUMENTS, $1..$9). Optional.',
+            },
+            context: {
+                type: 'string',
+                description: 'Optional extra context/facts to inject into the sub-agent (authoritative; not rediscovered).',
+            },
+        },
+        required: ['name'],
+    },
+    risk: 'confirm',
+    capabilities: {
+        effect: 'process',
+        concurrency: 'serial',
+        delegatesResourceLocks: true, // 与 sub-agent 一致:锁由内层工具取,避免父子自锁
+        supportsAbort: true,
+    },
+    async execute(args, ctx) {
+        return runSkill({
+            name: String(args.name ?? ''),
+            args: args.args,
+            context: typeof args.context === 'string' ? args.context : undefined,
+        }, ctx);
+    },
+};

package/dist/tools/builtins/use-skill.js

@@ -1,10 +1,21 @@
-import { getSkillBody } from '../../skills/index.js';
+import { findSkill } from '../../skills/index.js';
+import { renderSkillBody, readSkillFile } from '../../skills/runner.js';
+import { activateSkill } from '../../skills/activation.js';
 // ---------- use_skill ----------
 // 模型按需加载某 skill 的 SKILL.md 正文(渐进式披露第②层)。
 // 系统提示里已列出可用 skill 的 name + description(何时用),模型据此决定调用。
+//
+// 设计 §3.3 升级:
+//  - args:渲染 $ARGUMENTS / $1..$9 / ${SKILL_DIR}
+//  - file:读 skill 目录内附属文件(L2 披露,jail 约束)
+//  - context: fork 的 skill 不返回正文,改为引导调 run_skill(隔离白做才是真隔离)
+//  - inline skill 成功加载后激活会话级工具面约束(allowed/disallowed-tools)
+const MAX_SKILL_FILE = 200_000;
 export const useSkillTool = {
     name: 'use_skill',
-    description: 'Load the full SKILL.md instructions for a given skill. See the skill list in the system prompt for when to use each.',
+    description: 'Load the full SKILL.md instructions for a given skill. See the skill list in the system prompt for when to use each. ' +
+        'Supports args (renders $ARGUMENTS / $1.. / ${SKILL_DIR}) and file (reads a bundled reference file). ' +
+        'For skills marked [fork], this returns a guide to call run_skill instead of loading the body inline.',
     parameters: {
         type: 'object',
         properties: {
@@ -12,16 +23,43 @@ export const useSkillTool = {
                 type: 'string',
                 description: 'Name of the skill to load (see the skill list in the system prompt, or the /skills command)',
             },
+            args: {
+                type: 'object',
+                description: 'Arguments rendered into the skill body ($ARGUMENTS, $1..$9). Optional.',
+            },
+            file: {
+                type: 'string',
+                description: 'Optional bundled file inside the skill directory to read (e.g. references/api.md). Subject to jail bounds.',
+            },
         },
         required: ['name'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         const name = String(args.name ?? '').trim();
         if (!name)
             return '错误:缺少 skill 名。用 /skills 查看可用 skill 列表。';
-        const body = getSkillBody(name);
-        if (body === null)
+        const skill = findSkill(name);
+        if (!skill)
             return `错误:未找到 skill "${name}"。用 /skills 查看可用 skill 列表。`;
+        // fork skill:不把正文读进主上下文,引导走 run_skill。
+        if (skill.context === 'fork') {
+            return (`# Skill: ${name}\n\n` +
+                `该 skill 以隔离工作流(fork)形式执行。请勿在此加载其正文——调用 ` +
+                `\`run_skill({ name: "${name}"${Object.keys(args.args ?? {}).length ? ', args: {...}' : ''} })\` ` +
+                `即可在隔离子 agent 中执行并返回摘要。`);
+        }
+        // file 优先:L2 渐进式披露
+        if (typeof args.file === 'string' && args.file.trim()) {
+            const content = readSkillFile(skill, args.file.trim(), MAX_SKILL_FILE);
+            if (content === null)
+                return `错误:无法读取 skill "${name}" 的文件 "${args.file}"(不存在 / 越界 / 过大)。`;
+            return `# Skill: ${name} · ${args.file}\n\n${content}`;
+        }
+        const body = await renderSkillBody(skill, args.args, ctx?.signal);
+        if (body === null)
+            return `错误:未找到 skill "${name}" 的正文。用 /skills 查看可用 skill 列表。`;
+        // 激活 inline skill 的工具面约束(allowed/disallowed),本轮内生效。
+        activateSkill(skill);
         return `# Skill: ${name}\n\n${body}`;
     },
 };

package/dist/tools/constants.js

@@ -1,5 +1,6 @@
 /** 工具共享的截断 / 上限 / 忽略规则。 */
 import { isMemoryEnabled, isSubAgentEnabled, isFrontendToolsEnabled } from '../config/index.js';
+import { getActiveSkill } from '../skills/activation.js';
 export const MAX_FILE_LINES = 2000;
 export const MAX_OUTPUT = 20000;
 export const MAX_RESULTS = 100;
@@ -56,6 +57,7 @@ export const PLAN_DISABLED_TOOLS = new Set([
     'memory_update',
     'memory_forget',
     'sub-agent',
+    'run_skill', // fork 子 agent 执行面;plan 模式不应派生子工作流
 ]);
 /**
  * 按当前 isMemoryEnabled() 现算 plan 模式应屏蔽的工具。
@@ -89,5 +91,11 @@ export function getRuntimeDisabledTools() {
         for (const name of FRONTEND_TOOLS)
             disabled.add(name);
     }
+    // inline skill 激活态的 disallowed-tools:即便模型幻觉调用也执行不了(设计 §3.6)。
+    const active = getActiveSkill();
+    if (active?.disallowed) {
+        for (const name of active.disallowed)
+            disabled.add(name);
+    }
     return disabled;
 }

package/dist/ui/intervention.js

@@ -210,7 +210,7 @@ export async function promptIntervention(req) {
             layout.resetScroll();
         else
             layout.repaintViewport();
-        // 恢复走时计时器(RUNNING 态):面板期间 stopTurnTimer 停了心跳,退出后恢复状态行 200ms 刷新。
+        // 恢复走时计时器(RUNNING 态):面板期间 stopTurnTimer 停了心跳,退出后恢复状态行 80ms 刷新。
         layout.startTurnTimerIfRunning();
     }
     function onKey(_str, key) {
@@ -339,7 +339,7 @@ export async function promptIntervention(req) {
     return new Promise((res, rej) => {
         resolve = res;
         try {
-            // 进入面板:停 spinner(避免 onFrame 覆盖)+ 停走时计时器(避免 drawStatusBar 200ms 心跳
+            // 进入面板:停 spinner(避免 onFrame 覆盖)+ 停走时计时器(避免 drawStatusBar 80ms 心跳
             // 把真光标拉到 runningCaretPos 覆盖 paintInput 的正确光标位)+ 禁鼠标框选(防拖拽 viewport 重画覆盖菜单)+ 回尾(若用户正滚动回看)
             Spinner.pauseCurrent();
             layout.stopTurnTimer();