mocode-ai 1.2.3 → 1.2.4

package/dist/agent/index.js

@@ -118,8 +118,9 @@ function writeToolHeader(tc) {
         }
         return;
     }
-    // sub-agent 组还在跑但普通/mutation 工具先来了：收口 sub-agent 组，并补一条分隔空行。
-    if (subAgentGroupId) {
+    // sub-agent 组还在跑，或组刚收口但尚未写入分隔空行时，
+    // 普通/mutation 工具先来了：先 flush 补一条分隔空行，避免摘要行粘在一起。
+    if (subAgentGroupId || subAgentGroupPendingSeparator) {
         flushToolBatch();
     }
     if (isMutationTool(tc.name)) {

package/dist/agent/spawn.js

@@ -74,6 +74,8 @@ export async function spawnAgent(opts) {
     const requested = opts.tools?.length ? new Set(opts.tools) : null;
     const readOnly = new Set(['read_file', 'glob', 'grep', 'web_search', 'web_fetch', 'use_skill', 'memory_search', 'memory_list']);
     toolsOverride = chatTools.filter((tool) => tool.function.name !== 'sub-agent' &&
+        // run_skill 会再次 spawn,禁止递归(避免 fork skill 里又 run_skill 套娃)。
+        tool.function.name !== 'run_skill' &&
         // plan_update 直写主会话 notes.md(不走 overlay),子代理不应改动主计划——统一排除。
         tool.function.name !== 'plan_update' &&
         (!requested || requested.has(tool.function.name)) &&
@@ -93,7 +95,11 @@ export async function spawnAgent(opts) {
     // 主屏实时渲染(子 agent 透明化):TUI 激活时把子 agent 内部步骤实时写入主内容区,
     // 复用 batch 折叠机制(mouse 点击摘要行可展开/收起)。TUI 未激活(host/非 TTY)时
     // 保持纯静默——只缓冲 transcript,不写屏,兼容嵌入宿主。
-    const live = isTuiActive();
+    //
+    // quiet 模式(供 run_skill 等 opaque workflow 用):不产可展开 batch,
+    // 只在首次工具调用时写一行「◐ 执行 skill…」,完成后替换为「● skill 完成: 摘要」。
+    const live = isTuiActive() && !opts.quiet;
+    const quiet = isTuiActive() && !!opts.quiet;
     let liveBatchId = null;
     const liveLayout = () => ({
         contentWrite: (s) => layout.contentWrite(s),
@@ -106,6 +112,16 @@ export async function spawnAgent(opts) {
     });
     /** 本批是否挂在主侧调用行下(挂上了就由主侧负责分隔空行,自己不能往 buffer 末尾追加)。 */
     let nested = false;
+    // quiet 模式:完全静默,不写任何行(连 spinner 都没有);
+    // 子 agent 的执行过程与结果只回灌为主 agent 的 run_skill 工具结果。
+    const ensureQuietLine = (_label) => {
+        if (!quiet)
+            return; // 静默:什么都不输出
+    };
+    const replaceQuietLine = (_status, _detail) => {
+        if (!quiet)
+            return; // 静默:什么都不输出
+    };
     const ensureLiveBatch = () => {
         if (!live || liveBatchId)
             return;
@@ -163,6 +179,7 @@ export async function spawnAgent(opts) {
             const summary = summarizeToolCall(tc.name, tc.arguments);
             writeBuf(`  ● ${tc.name}  ${summary}\n`);
             // 实时写入主内容区:子 agent 的每次工具调用累计到摘要行计数。
+            ensureQuietLine(opts.quietLabel ?? t('skill.executing', { name: opts.prompt.slice(0, 40) }));
             ensureLiveBatch();
             if (liveBatchId) {
                 batch.recordCall(liveBatchId, tc.name, summary);
@@ -198,6 +215,8 @@ export async function spawnAgent(opts) {
         onMaxSteps: () => {
             writeBuf(`  ● 达到最大步数(${maxSteps}),子 agent 停止。\n`);
             finishLiveBatch('failed');
+            if (quiet)
+                replaceQuietLine('failed', t('skill.maxSteps', { max: String(maxSteps) }));
         },
         onDone: (elapsedMs, usage) => {
             const tok = usage && usage.totalTokens
@@ -205,10 +224,15 @@ export async function spawnAgent(opts) {
                 : '';
             writeBuf(`  ✻ 子 agent 耗时 ${(elapsedMs / 1000).toFixed(1)}s${tok}\n`);
             finishLiveBatch('complete');
+            if (quiet) {
+                replaceQuietLine('complete', `${t('skill.complete')}  ${(elapsedMs / 1000).toFixed(1)}s${tok}`);
+            }
         },
         onAbort: () => {
             // 中断:子 agent 未完成,收尾批(不折叠——用户可能想看中断前做了什么)。
             finishLiveBatch('aborted');
+            if (quiet)
+                replaceQuietLine('aborted', t('skill.aborted'));
         },
         // onStepStart / onChatDone / onToolStart / onToolDone:子 agent 静默,无需 spinner 渲染。
         // abort 还原(history 还原 + 模式还原)由 core 的 abortRestore 处理,hooks 只管展示。

package/dist/context/pipeline.js

@@ -37,7 +37,7 @@ function tryParseArgs(raw) {
  * 仅作 encoder 软目标;最终裁剪仍由末尾 capToolResultForHistory 兜底,故两处常量偶有漂移不致命。
  */
 function budgetFor(name) {
-    if (name === 'use_skill')
+    if (name === 'use_skill' || name === 'run_skill')
         return MAX_SKILL_RESULT;
     if (name === 'memory_search')
         return MAX_MEMORY_RESULT;

package/dist/i18n/index.js

@@ -217,6 +217,10 @@ const zhCN = {
     'subagent.stateOff': '关闭',
     'subagent.changedOn': '已开启子 Agent；sub-agent 将从下一次模型请求起可用。',
     'subagent.changedOff': '已关闭子 Agent；sub-agent 已从模型工具表移除。',
+    'skill.executing': '执行 skill: {name}…',
+    'skill.complete': 'Skill 执行完成',
+    'skill.aborted': 'Skill 执行已中断',
+    'skill.maxSteps': 'Skill 达到最大步数({max})',
     'subagent.usage': '用法：/subagent on|off|status',
     'fe.status': '前端工具簇：{state}',
     'fe.stateOn': '开启',
@@ -472,6 +476,10 @@ const en = {
     'subagent.stateOff': 'disabled',
     'subagent.changedOn': 'Sub-agents enabled; sub-agent will be available from the next model request.',
     'subagent.changedOff': 'Sub-agents disabled; sub-agent has been removed from the model tool list.',
+    'skill.executing': 'Executing skill: {name}…',
+    'skill.complete': 'Skill complete',
+    'skill.aborted': 'Skill aborted',
+    'skill.maxSteps': 'Skill reached max steps ({max})',
     'subagent.usage': 'Usage: /subagent on|off|status',
     'fe.status': 'Frontend tools: {state}',
     'fe.stateOn': 'enabled',

package/dist/repl/index.js

@@ -26,7 +26,10 @@ import { computePruneStats } from '../context/relevance.js';
 import { formatArtifactTokenSources } from '../context/artifacts.js';
 import { manualCompact, contextState, newSessionId, saveSession, loadSession, listSessions, appendCurrentSessionRuntimeEvent, hashTraceValue, } from '../session/index.js';
 import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, getCurrentTurnId, } from '../rollback/index.js';
-import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
+import { listSkills, effectiveSystemPrompt, findSkill, } from '../skills/index.js';
+import { clearSkillActivation } from '../skills/activation.js';
+import { runSkill, renderSkillBody } from '../skills/runner.js';
+import { isSkillTrusted } from '../skills/trust.js';
 import { buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -50,6 +53,7 @@ function buildSlashCommands() {
         { name: '/clear', desc: d('commands.clear') },
         { name: '/context', desc: d('commands.context') },
         { name: '/skills', desc: d('commands.skills') },
+        { name: '/skill', desc: '执行某个 skill(/skill <name> [args-json])' },
         { name: '/compact', desc: d('commands.compact') },
         { name: '/resume', desc: d('commands.sessionResume') },
         { name: '/sessions', desc: d('commands.sessionBrowse') },
@@ -998,6 +1002,8 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             // 入口设定本轮初始模式(合成执行轮传 false→auto;用户轮传当前 mode)。
             // setAgentMode 触发 listener 重写 history[0];LLM 可在轮中调 switch_mode 切模式,runAgent 每步读实时值。
             setAgentMode(planMode ? 'plan' : 'auto');
+            // 新用户轮开始:清除上一轮 inline skill 的激活态(允许/disallowed 约束一 turn 有效)。
+            clearSkillActivation();
             // 运行中每步 chat() 返回后刷新状态行 context 用量条(用 fresh lastUsage / 估算),
             // 否则整轮冻结在轮首 refreshStatusBase 的值,「执行 grep」时 2k/1000k 不动。
             const result = await runAgent(history, userInput, signal, () => {
@@ -1455,9 +1461,69 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             else {
                 layout.contentWrite(`${ui.dim}已发现 ${skills.length} 个 skill:${ui.reset}\n`);
                 for (const s of skills) {
-                    layout.contentWrite(`  ${ui.accent}${s.name}${ui.reset}  ${ui.dim}${s.description}${ui.reset}\n`);
+                    const badges = [];
+                    if (s.context === 'fork')
+                        badges.push('fork');
+                    if (!s.modelInvocable)
+                        badges.push('manual-only');
+                    badges.push(s.origin);
+                    if (s.origin === 'project') {
+                        badges.push(isSkillTrusted(s) ? 'trusted' : 'untrusted');
+                    }
+                    const badgeStr = badges.length ? ` ${ui.dim}[${badges.join('|')}]${ui.reset}` : '';
+                    layout.contentWrite(`  ${ui.accent}${s.name}${ui.reset}${badgeStr}  ${ui.dim}${s.description}${ui.reset}\n`);
+                    if (s.allowedTools?.length) {
+                        layout.contentWrite(`    ${ui.dim}allowed: ${s.allowedTools.join(', ')}${ui.reset}\n`);
+                    }
+                    if (s.disallowedTools?.length) {
+                        layout.contentWrite(`    ${ui.dim}disallowed: ${s.disallowedTools.join(', ')}${ui.reset}\n`);
+                    }
+                    if (s.warnings.length) {
+                        layout.contentWrite(`    ${ui.dim}warnings: ${s.warnings.join('; ')}${ui.reset}\n`);
+                    }
+                }
+                layout.contentWrite(`${ui.dim}(用 use_skill 加载指令; fork 类用 run_skill 执行; 也支持 /skill <name> [args-json])${ui.reset}\n`);
+            }
+            continue;
+        }
+        // /skill <name> [args-json]:直接执行一个 skill(fork 走 run_skill,inline 打印渲染后正文)。
+        if (line === '/skill' || line.startsWith('/skill ')) {
+            const rest = line.slice('/skill'.length).trim();
+            const sp = rest.indexOf(' ');
+            const name = sp === -1 ? rest : rest.slice(0, sp);
+            const argStr = sp === -1 ? '' : rest.slice(sp + 1).trim();
+            if (!name) {
+                layout.contentWrite(`${ui.dim}用法: /skill <name> [args-json]${ui.reset}\n`);
+                continue;
+            }
+            let args;
+            if (argStr) {
+                try {
+                    args = JSON.parse(argStr);
+                }
+                catch {
+                    layout.contentWrite(`${ui.dim}args 不是合法 JSON,已忽略。${ui.reset}\n`);
+                }
+            }
+            const skill = findSkill(name);
+            if (!skill) {
+                layout.contentWrite(`错误:未找到 skill "${name}"。\n`);
+                continue;
+            }
+            if (skill.context === 'fork') {
+                layout.contentWrite(`${ui.dim}执行 fork skill "${name}"…${ui.reset}\n`);
+                const out = await runSkill({ name, args });
+                layout.contentWrite((out.status === 'success' ? '' : `[${out.status}] `) + out.output + '\n');
+            }
+            else {
+                const body = await renderSkillBody(skill, args);
+                if (body === null)
+                    layout.contentWrite(`错误:未找到 skill "${name}" 的正文。\n`);
+                else {
+                    // 仅预览:inline 正文未进入模型 history,不激活工具面约束;
+                    // 要让模型按此 skill 工作,请让它调 use_skill(name) 或在下条消息里提及该 skill。
+                    layout.contentWrite(`# Skill: ${name}(预览,模型尚未看到此内容)\n\n${body}\n`);
                 }
-                layout.contentWrite(`${ui.dim}(用 use_skill 工具加载某 skill 的完整指令)${ui.reset}\n`);
             }
             continue;
         }

package/dist/skills/activation.js

@@ -0,0 +1,26 @@
+// inline skill 激活态(设计 §3.6):use_skill 成功加载 inline skill 时置位,
+// 该 turn 内模型的 disallowed-tools 约束生效(constants.getRuntimeDisabledTools 消费)。
+// 一 turn 语义:下一次用户轮开始时由 repl 调 clearSkillActivation() 清除。
+//
+// 刻意不设 allowed 授权:inline 加载不过信任门禁,自动放行 confirm 级工具会让
+// 未信任的项目 skill 绕过权限确认。allowed-tools 只在 fork 模式下经 spawnAgent
+// 的工具白名单生效(runner.runSkill)。
+//
+// 叶子模块:仅依赖 toolmap(亦叶子),不引 tools/permissions/agent,避免环。
+import { mapSkillToolName } from './toolmap.js';
+let active = null;
+/** use_skill 成功加载 inline skill 时调用。 */
+export function activateSkill(skill) {
+    const disallowed = skill.disallowedTools?.map(mapSkillToolName).filter((t) => t != null);
+    active = {
+        name: skill.name,
+        disallowed: disallowed && disallowed.length ? new Set(disallowed) : null,
+    };
+}
+/** 用户新轮开始时清激活态。 */
+export function clearSkillActivation() {
+    active = null;
+}
+export function getActiveSkill() {
+    return active;
+}

package/dist/skills/builtin-skills.js

@@ -50,6 +50,11 @@ export const builtinSkills = [
         body: CODEGRAPH_BODY,
         dir: 'builtin',
         skillMdPath: 'builtin',
+        // 内置 skill:恒信任、内联、模型可自动触发。
+        context: 'inline',
+        modelInvocable: true,
+        origin: 'builtin',
+        warnings: [],
     },
 ];
 /** 内置 skill 名字集,供 discoverSkills 跳过/覆盖时使用。 */

package/dist/skills/discover.js

@@ -1,10 +1,11 @@
 // skills 发现子系统。
 // 仅依赖 node 标准库,是叶子模块:不依赖 config/agent/llm/tools,避免环。
 //
-// 约定:每个 skill 是一个目录 <skill-name>/SKILL.md,顶部 YAML frontmatter
-// (name / description 必需,version / license 可选)。元数据始终注入系统提示,
-// 正文由 use_skill 工具按需加载(渐进式披露)。
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+// 约定:每个 skill 是一个目录 <skill-name>/SKILL.md,顶部 YAML frontmatter。
+// 元数据始终注入系统提示,正文由 use_skill 工具按需加载(渐进式披露)。
+// frontmatter 兼容 Agent Skills 开放标准(name/description/allowed-tools/context/agent…),
+// 解析器是受限 YAML 子集(自写,不引 yaml 依赖),越界字段一律忽略 + 记 warning。
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { builtinSkillNames } from './builtin-skills.js';
@@ -39,10 +40,85 @@ export function resolveSkillsDirs() {
         path.join(process.cwd(), '.mocode', 'skills'),
     ];
 }
+/** 数组型 frontmatter 键(这些键的整行值按空白切分为 token 列表)。 */
+const ARRAY_KEYS = new Set(['allowed-tools', 'disallowed-tools']);
+/** 行内数组 / 方括号数组:按空白或逗号切分,去空。 */
+function splitList(s) {
+    return s
+        .split(/[\s,]+/)
+        .map((x) => x.trim())
+        .filter(Boolean);
+}
+/** 取标量值(数组值返回 undefined)。 */
+function scalar(meta, key) {
+    const v = meta[key];
+    return typeof v === 'string' ? v : undefined;
+}
+/** 取可能为数组的值,统一成 string[] | undefined。 */
+function asArray(meta, key) {
+    const v = meta[key];
+    if (Array.isArray(v))
+        return v.length ? v : undefined;
+    if (typeof v === 'string' && v)
+        return splitList(v);
+    return undefined;
+}
+function truthy(meta, key) {
+    const v = scalar(meta, key);
+    return v != null && (v.toLowerCase() === 'true' || v === '1');
+}
+function num(meta, key) {
+    const v = scalar(meta, key);
+    if (v == null)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** 去掉首尾配对引号(YAML 标量基本语义;`"use when: foo"` → `use when: foo`)。 */
+function unquote(s) {
+    if (s.length >= 2 && (s[0] === '"' || s[0] === "'") && s[s.length - 1] === s[0]) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+/** `context: fork` 或兼容别名 `mode: fork` → 'fork';其余 'inline'。 */
+function resolveContext(meta) {
+    if (scalar(meta, 'context') === 'fork')
+        return 'fork';
+    if (scalar(meta, 'mode') === 'fork')
+        return 'fork'; // 旧内部别名
+    return 'inline';
+}
+/** `agent:` 映射到 mocode 的 read/write 双态;未知值记 warning 并保守按 read。 */
+function resolveAgentMode(meta, warnings) {
+    const a = scalar(meta, 'agent');
+    if (!a)
+        return undefined;
+    const low = a.toLowerCase();
+    if (['explore', 'plan', 'research', 'read'].includes(low))
+        return 'read';
+    if (['general-purpose', 'write'].includes(low))
+        return 'write';
+    warnings.push(`未知 agent 值 "${a}",按 read(只读,保守)处理`);
+    return 'read';
+}
+/** 收集本轮不支持、已忽略的字段,用于 /skills 提示(不阻断加载)。 */
+function collectWarnings(meta) {
+    const warnings = [];
+    for (const k of ['hooks', 'model', 'effort', 'paths']) {
+        if (k in meta)
+            warnings.push(`字段 "${k}" 当前不支持,已忽略`);
+    }
+    return warnings;
+}
 /**
- * 极简 YAML frontmatter 解析(不引入 yaml 依赖)。
- * 仅支持单行键值:按首个冒号切 key/value,trim,去首尾配对引号。
- * 不支持块标量(| / >)与多行值——v1 限制(skill 的 description 实际多为单行)。
+ * 受限 YAML 子集解析(不引入 yaml 依赖)。
+ * 支持四种值形态:
+ *  - 标量 `key: value`
+ *  - 行内数组 `allowed-tools: a, b` / 方括号 `allowed-tools: [a, b]`
+ *  - 块序列(下一行起 `  - item`)
+ *  - 空格分隔字符串(标准形态 `allowed-tools: Read grep run_command`,仅数组型键)
+ * 其余(嵌套 map / 块标量)一律忽略,保持攻击面与维护成本可控。
  *
  * 返回 { meta, body }:无 frontmatter 时 meta 为空、body 为原文。
  */
@@ -70,7 +146,16 @@ export function parseFrontmatter(content) {
     if (!closed)
         return { meta, body: content }; // 无闭合:视为无 frontmatter
     i++; // 跳过闭 ---
-    for (const line of fmLines) {
+    const isListItem = (l) => {
+        const t = l.trim();
+        return t === '-' || t.startsWith('- ');
+    };
+    const itemText = (l) => {
+        const t = l.trim();
+        return t === '-' ? '' : t.slice(2).trim();
+    };
+    for (let k = 0; k < fmLines.length; k++) {
+        const line = fmLines[k];
         const trimmed = line.trim();
         if (trimmed === '' || trimmed.startsWith('#'))
             continue;
@@ -78,15 +163,30 @@ export function parseFrontmatter(content) {
         if (colon === -1)
             continue;
         const key = line.slice(0, colon).trim();
-        let value = line.slice(colon + 1).trim();
-        // 去首尾配对引号(" 或 ')
-        if (value.length >= 2 &&
-            ((value[0] === '"' && value[value.length - 1] === '"') ||
-                (value[0] === "'" && value[value.length - 1] === "'"))) {
-            value = value.slice(1, -1);
+        const value = line.slice(colon + 1).trim();
+        // 块序列:当前值为空且下一行是列表项
+        if (value === '' && k + 1 < fmLines.length && isListItem(fmLines[k + 1])) {
+            const arr = [];
+            let j = k + 1;
+            while (j < fmLines.length && isListItem(fmLines[j])) {
+                arr.push(itemText(fmLines[j]));
+                j++;
+            }
+            meta[key] = arr;
+            k = j - 1; // for 循环会再 +1
+            continue;
+        }
+        // 方括号数组
+        if (value.startsWith('[') && value.endsWith(']')) {
+            meta[key] = splitList(value.slice(1, -1));
+            continue;
+        }
+        // 数组型键:整行按空白切分为 token(标准形态 Bash(git:*) Read)
+        if (ARRAY_KEYS.has(key)) {
+            meta[key] = value ? splitList(value) : [];
+            continue;
         }
-        if (key)
-            meta[key] = value;
+        meta[key] = unquote(value);
     }
     const body = lines.slice(i).join('\n').replace(/^\n+/, '');
     return { meta, body };
@@ -99,6 +199,10 @@ export function parseFrontmatter(content) {
  */
 export function discoverSkills() {
     const dirs = resolveSkillsDirs();
+    // 记录本次发现的所有 SKILL.md 路径,供 skillsScanSignature 做廉价热重载探测
+    // (只 stat 已知文件,不每次全量重扫)。新增 skill 目录会改目录 mtime → 触发全量重扫。
+    const seenMdPaths = [];
+    const projDir = path.join(process.cwd(), '.mocode', 'skills');
     const byName = new Map();
     for (const dir of dirs) {
         let entries = [];
@@ -110,6 +214,8 @@ export function discoverSkills() {
         catch {
             continue; // 目录不存在或无权限,静默跳过
         }
+        // SKILLS_DIRS 自定义目录无法归类 project,统一按 user(免门禁)处理。
+        const origin = dir === projDir ? 'project' : 'user';
         for (const name of entries) {
             // 跳过内置 skill 同名目录(项目级用户版可放在 ~/.mocode/skills/<name>/
             // 覆盖内置版;cwd/.mocode/skills/<name>/ 也算项目级覆盖)。discoverSkills 按
@@ -122,19 +228,32 @@ export function discoverSkills() {
             try {
                 if (!existsSync(skillMdPath))
                     continue;
+                seenMdPaths.push(skillMdPath);
                 const content = readFileSync(skillMdPath, 'utf8');
-                const { meta } = parseFrontmatter(content);
-                const skillName = (meta.name || name).trim();
-                const description = (meta.description || '').trim();
+                const { meta, body } = parseFrontmatter(content);
+                const skillName = (scalar(meta, 'name') || name).trim();
+                const description = (scalar(meta, 'description') || '').trim();
                 if (!description)
                     continue; // 缺 description 跳过(它是最触发机制)
+                const warnings = collectWarnings(meta);
                 byName.set(skillName, {
                     name: skillName,
                     description,
-                    version: meta.version?.trim() || undefined,
-                    license: meta.license?.trim() || undefined,
+                    version: scalar(meta, 'version')?.trim() || undefined,
+                    license: scalar(meta, 'license')?.trim() || undefined,
                     dir: skillDir,
                     skillMdPath,
+                    // body 留空:用户/项目 skill 由 getSkillBody 走文件读取(保留热重载语义)。
+                    context: resolveContext(meta),
+                    agentMode: resolveAgentMode(meta, warnings),
+                    allowedTools: asArray(meta, 'allowed-tools'),
+                    disallowedTools: asArray(meta, 'disallowed-tools'),
+                    modelInvocable: !truthy(meta, 'disable-model-invocation'),
+                    maxSteps: num(meta, 'max-steps'),
+                    argumentHint: scalar(meta, 'argument-hint')?.trim() || undefined,
+                    whenToUse: scalar(meta, 'when_to_use')?.trim() || undefined,
+                    origin,
+                    warnings,
                 });
             }
             catch {
@@ -142,5 +261,32 @@ export function discoverSkills() {
             }
         }
     }
+    // 首次全量扫描后,把发现的 SKILL.md 路径交给热重载探测器,后续只 stat 这些已知文件。
+    lastKnownMdPaths = seenMdPaths;
     return Array.from(byName.values());
 }
+/** 上一次 discoverSkills 发现的 SKILL.md 路径;skillsScanSignature 复用,避免每次全量重扫。 */
+let lastKnownMdPaths = [];
+/** 供热重载签名计算:各 skills 目录 mtime + 已知 SKILL.md 的 mtime。
+ * 目录 mtime 变化(新增/删除 skill 目录)或任一已知文件变动 → 签名变更 → 重扫。
+ * 首轮 lastKnownMdPaths 为空时退化为只测目录 mtime(首轮 listSkills 后即填充)。 */
+export function skillsScanSignature() {
+    const parts = [];
+    for (const dir of resolveSkillsDirs()) {
+        try {
+            parts.push('D' + dir + statSync(dir).mtimeMs);
+        }
+        catch {
+            parts.push('D' + dir + 'x');
+        }
+    }
+    for (const p of lastKnownMdPaths) {
+        try {
+            parts.push('F' + p + statSync(p).mtimeMs);
+        }
+        catch {
+            parts.push('F' + p + 'x');
+        }
+    }
+    return parts.join('\0');
+}

package/dist/skills/index.js

@@ -5,13 +5,20 @@
 // 优先级:内置 skill < 用户/系统 skill < 项目级 skill(后注册覆盖先注册,
 // 项目级最后扫描,自然在 Map 中胜出)。同名用户 skill 完全替换内置版。
 import { existsSync, readFileSync } from 'node:fs';
-import { discoverSkills, parseFrontmatter } from './discover.js';
+import { discoverSkills, parseFrontmatter, skillsScanSignature, } from './discover.js';
 import { builtinSkills } from './builtin-skills.js';
 let cache = null;
+let cacheKey = null;
+/** 当前扫描签名(各 skills 目录 + 各 SKILL.md 的 mtime 拼接);用于热重载失效判断。 */
+function currentKey() {
+    return skillsScanSignature();
+}
 /** 已发现的 skill 列表(懒加载,首次调用触发扫描;启动期 repl 调一次)。
- * 合并策略:内置 skill 作兜底,discoverSkills 的输出(按目录优先级后写覆盖)优先生效。 */
+ * 合并策略:内置 skill 作兜底,discoverSkills 的输出(按目录优先级后写覆盖)优先生效。
+ * 热重载:签名变更(任一 SKILL.md 或目录被增删/改动)即重扫,无需重启。 */
 export function listSkills() {
-    if (cache !== null)
+    const key = currentKey();
+    if (cache !== null && cacheKey === key)
         return cache;
     const discovered = discoverSkills();
     const byName = new Map();
@@ -22,15 +29,25 @@ export function listSkills() {
     for (const skill of discovered)
         byName.set(skill.name, skill);
     cache = Array.from(byName.values());
+    cacheKey = key;
     return cache;
 }
+/** 强制下次 listSkills 重扫(外部触发热重载用)。 */
+export function invalidateSkillsCache() {
+    cache = null;
+    cacheKey = null;
+}
+/** 按名字取单个 skill(区分大小写;找不到返 null)。 */
+export function findSkill(name) {
+    return listSkills().find((s) => s.name === name) ?? null;
+}
 /**
  * 读取某 skill 的 SKILL.md 正文(去掉 frontmatter)。
  * 纯函数:找不到 / 读失败返 null(错误字符串交给调用方工具层生成)。
  * 内置 skill 直接返回 body 字段(无 fs 依赖)。
  */
 export function getSkillBody(name) {
-    const skill = listSkills().find((s) => s.name === name);
+    const skill = findSkill(name);
     if (!skill)
         return null;
     if (skill.body) {
@@ -49,12 +66,20 @@ export function getSkillBody(name) {
         return null;
     }
 }
-/** 拼进系统提示的 skill 段;无 skill 返空串(零行为变化)。 */
+/** 拼进系统提示的 skill 段;无 skill 返空串(零行为变化)。
+ * - disable-model-invocation: true 的 skill 不进列表(模型看不见,仅 /skill 可触发)。
+ * - context: fork 的 skill 追加 [fork] 徽标 + 一句调用指引,提示模型它可被「执行」而非「阅读」。 */
 export function buildSkillsSection() {
-    const skills = listSkills();
+    const skills = listSkills().filter((s) => s.modelInvocable);
     if (skills.length === 0)
         return '';
-    const lines = skills.map((s) => `- ${s.name}: ${s.description}`);
+    const lines = skills.map((s) => {
+        const badge = s.context === 'fork' ? ' [fork]' : '';
+        const hint = s.context === 'fork'
+            ? ' (call run_skill to execute it as an isolated workflow)'
+            : ' (call use_skill to load its instructions)';
+        return `- ${s.name}${badge}: ${s.description}${hint}`;
+    });
     return [
         '',
         '',

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {