mocode-ai 1.2.2 → 1.2.4

package/dist/agent/core.js

@@ -337,9 +337,20 @@ export async function runAgentCore(opts) {
                 const modelStartedAt = Date.now();
                 const provider = safeProviderId(requestBaseURL);
                 emitTrace('model_start', { model: requestModel, provider });
-                const dynamicSystemSuffix = historyRebuilt
-                    ? '## Post-compaction recovery\nContext was compacted before this request. Re-establish the current objective and unresolved work from retained evidence or the session note, avoid repeating completed investigation, and re-read exact file context before any dependent edit.'
-                    : '';
+                // 动态注入(仅追加到 system 末尾,不触碰 staticBody 前缀 → 不破坏 prompt 缓存):
+                //  - 开场分析:仅主线(step===0 且 !suppressOpeningAnalysis)注入——即"用户发一个任务后,
+                //    agent 第一次模型调用"。子代理经 spawn.ts 传 suppressOpeningAnalysis:true 排除。
+                //  - historyRebuilt:compact 恢复步;要求重新锚定目标。两者可叠加但互不串扰。
+                //  .filter(Boolean) 保证空段不产生多余空行;后续 step 均为空串 → system 前缀稳定命中缓存。
+                //  安全保证:此段只拼进 requestHistory(新建对象),绝不回写 history[0],故不会跨 step/跨 turn 残留。
+                const dynamicSystemSuffix = [
+                    (!opts.suppressOpeningAnalysis && step === 0)
+                        ? '## Opening analysis\nBegin your FIRST response of this turn with a brief analysis of the request and your planned approach (1-3 sentences, no filler), THEN start tool calls. This opening is the only place where pre-tool prose is expected; after it, work quietly with no narration between tool calls.'
+                        : '',
+                    historyRebuilt
+                        ? '## Post-compaction recovery\nContext was compacted before this request. Re-establish the current objective and unresolved work from retained evidence or the session note, avoid repeating completed investigation, and re-read exact file context before any dependent edit.'
+                        : '',
+                ].filter(Boolean).join('\n\n');
                 const systemMessage = history[0];
                 const requestHistory = dynamicSystemSuffix
                     && systemMessage?.role === 'system'

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 只管展示。
@@ -225,6 +249,7 @@ export async function spawnAgent(opts) {
         maxSteps,
         toolsOverride,
         contextState: localContextState,
+        suppressOpeningAnalysis: true, // 子代理不注入「开场分析」:仅主线面对用户的首次响应用
         onToolOutcome: (tool, args) => {
             if (tool === 'read_file' && typeof args.path === 'string')
                 readSet.add(args.path);

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 [
         '',
         '',