minimal-agent 0.8.2 → 0.9.0

package/src/askBridge.js

@@ -46,6 +46,16 @@ export async function requestUserChoice(questions, signal) {
     // 非交互兜底
     return questions.map((q) => {
         const pick = q.options[0]?.label ?? '';
+        // 约定校验：askBridge.ts:25 JSDoc 说"把推荐项放在第一个，并在 label 末尾标「(推荐)」。
+        // 若首项 label 不含 "(推荐)"，stderr 注记一下——上游作者违反约定
+        // （用户被自动套上非推荐路径是糟糕的体验）
+        const firstOpt = q.options[0];
+        if (firstOpt && !firstOpt.label.includes('(推荐)')) {
+            try {
+                process.stderr.write(`[AskUserQuestion·非交互] "${q.header}" 首项 label "${firstOpt.label}" 不含「(推荐)」标记——非交互宿主会按首项兜底，违反 promptAssembly 里的提问克制约定\n`);
+            }
+            catch { /* ignore */ }
+        }
         try {
             process.stderr.write(`[AskUserQuestion·非交互] "${q.header}" 无 UI，自动选推荐项："${pick}"\n`);
         }

package/src/context/archive.js

@@ -51,6 +51,10 @@ export async function archiveCurrent(messages) {
     await mkdir(dir, { recursive: true });
     const id = new Date().toISOString().replace(/:/g, '-');
     const path = join(dir, `${id}.json`);
+    // 写入完整 messages（含 system）—— restoreArchive 期待原样还原以做 roundtrip
+    // 跳过判定单独用 nonSystem（空对话不归档）—— 这是有意分层的：
+    //   skip 判定 = "有没有用户/助手消息可归档"
+    //   write 内容 = "保留完整上下文供 /restore 还原"
     await writeFile(path, JSON.stringify({ updatedAt: Date.now(), messages }), 'utf8');
     return id;
 }

package/src/infra/verification.js

@@ -2,8 +2,6 @@
  * ============================================================
  *  src/infra/verification.ts —— 共享验证基础设施
  * ------------------------------------------------------------
- *  从 plugins/ralph-wiggum/src/verificationGate.ts 提升为共享模块。
- *
  *  支持四种检查器（跨平台）：
  *    - shell:<cmd>                跨平台 spawn（Windows 走 cmd /c, 其余 bash -c）
  *    - file_exists:<path>         fs.existsSync
@@ -11,8 +9,8 @@
  *    - test_count:<min>           跑 `bun test`，从 stdout 解析 "N pass"
  *
  *  消费者：
- *    - ralph-wiggum 插件（循环验证门）
  *    - workflow-runner 插件（verify 步骤类型）
+ *    - 工作流 YAML 的 type: verify 步骤
  *    - 未来任何需要声明式验证的插件或模块
  *
  *  设计原则：
@@ -59,7 +57,7 @@ function parseVerifyArg(arg) {
 /**
  * 从命令行参数字符串中提取所有 --verify 项。
  * 兼容两种调用方式：
- *   - ralph-loop 的 args 字符串：`"goal --verify 'shell:bun test'"`
+ *   - 工作流 / 命令的 args 字符串：`"goal --verify 'shell:bun test'"`
  *   - workflow verify 步骤的 checks 数组元素：`"shell:bun test"`
  */
 export function parseVerifyArgs(args) {
@@ -74,10 +72,25 @@ export function parseVerifyArgs(args) {
     }
     return checks;
 }
-/** 从单个 check 字符串解析（workflow verify 步骤用）。 */
+/** 从单个 check 字符串解析（workflow verify 步骤用）。
+ *  parseVerifyArg 是底层解析器；本函数保留独立名字是因为 verify.ts:14 直接 import 它。
+ *  parseVerifyArgs 用于从命令行参数字符串抓 --verify 项——两者职责不重叠。 */
 export function parseCheckString(raw) {
     return parseVerifyArg(raw);
 }
+/**
+ * 判断路径是否为绝对路径（POSIX / Windows drive / Windows UNC）。
+ *  - POSIX:    /usr/local/...
+ *  - Win drive: C:\Users\... 或 C:/foo
+ *  - UNC:       \\server\share\...
+ * 之前漏识别 UNC → 会被错误地拼上 workingDir 前缀，file_exists 永远查不到。
+ */
+function isAbsolutePath(file) {
+    return (file.startsWith('/') ||
+        file.startsWith('\\') || // 同时覆盖 \foo 和 \\server（前者非常规但兼容）
+        /^[A-Za-z]:[\\/]/.test(file) // C:\ 或 C:/
+    );
+}
 function runShell(command, timeout) {
     return new Promise((resolve) => {
         const isWin = process.platform === 'win32';
@@ -116,10 +129,8 @@ export async function verifyShell(command, timeout) {
     };
 }
 export function verifyFileExists(file) {
-    // 相对路径以 workingDir 为锚
-    const resolved = file.startsWith('/') || /^[A-Za-z]:/.test(file)
-        ? file
-        : `${getWorkingDir()}/${file}`;
+    // 相对路径以 workingDir 为锚（绝对路径识别含 UNC）
+    const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
     const exists = existsSync(resolved);
     return {
         check: { type: 'file_exists', file },
@@ -128,9 +139,7 @@ export function verifyFileExists(file) {
     };
 }
 export function verifyFileContains(file, pattern) {
-    const resolved = file.startsWith('/') || /^[A-Za-z]:/.test(file)
-        ? file
-        : `${getWorkingDir()}/${file}`;
+    const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
     try {
         const content = readFileSync(resolved, 'utf8');
         const regex = new RegExp(pattern);
@@ -150,7 +159,10 @@ export function verifyFileContains(file, pattern) {
     }
 }
 async function verifyTestCount(minCount) {
-    const r = await runShell(`bun test`, 60_000);
+    // 跨运行时：开发用 bun → bun test；npm 全局安装用 Node → npm test --silent
+    // 用 process.versions.bun 探测比 typeof Bun !== 'undefined' 更稳（不依赖全局类型）
+    const cmd = process.versions.bun ? 'bun test' : 'npm test --silent';
+    const r = await runShell(cmd, 60_000);
     const combined = `${r.stdout}\n${r.stderr}`;
     if (r.errored) {
         return {

package/src/llm/client.js

@@ -40,6 +40,87 @@ function isResponseFormatUnsupported(status, errText) {
         t.includes('not valid') ||
         t.includes('invalid'));
 }
+// ============================================================
+//  重试 + 超时（无网络重试 → 整条 IM 链卡死；这是 P0-1 的根治）
+// ------------------------------------------------------------
+//  背景：之前 fetch 直接 await，没有 timeout 也没有重试。
+//  后果：① 断网 1 帧流式 60+ chunk 报废；② 429/5xx 直接抛错；
+//  ③ 401/403 错误文案不带"key 失效"提示；④ gateway 桥接 stream-json 后
+//  子进程挂起会整条 IM 通道 dir 锁卡死。
+//
+//  设计：
+//   - 指数退避 200ms → 400 → 800 → 1600 → 3200（封顶 5 次）
+//   - 5xx / 408 / 425 / 429 / 网络错误全部重试
+//   - 401 / 403 / 404 等 4xx 不重试（重试无意义）+ 给清晰"key 失效"提示
+//   - 429 优先解析 Retry-After 头（秒），封顶 60s
+//   - AbortSignal.timeout 120s 兜底单次 fetch 时长
+//   - 用户 signal 触发的 abort 立即退出，不重试
+//   - 流式响应中途中断（reader.read reject）走同一个错误路径
+// ============================================================
+/** 单一 fetch 请求的超时（毫秒）。流式响应中途不发新 chunk 也算超时。 */
+const FETCH_TIMEOUT_MS = 120_000;
+const DEFAULT_RETRY = {
+    maxAttempts: 5,
+    baseDelayMs: 200,
+    maxDelayMs: 3200,
+};
+/** 可重试的 HTTP 状态码。4xx 除 408/425/429 外不重试（重试无意义）。 */
+function isRetryableStatus(status) {
+    return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
+}
+/** 鉴权类错误：明确告诉用户"key 失效/过期/无权访问"，避免重试无意义。 */
+function isClientAuthError(status) {
+    return status === 401 || status === 403;
+}
+/** 解析 Retry-After 头（秒数字符串），封顶 60s。无效/缺省返回 undefined。 */
+function parseRetryAfter(resp) {
+    const h = resp.headers.get('retry-after');
+    if (!h)
+        return undefined;
+    const sec = parseFloat(h);
+    if (!Number.isFinite(sec) || sec < 0)
+        return undefined;
+    return Math.min(sec * 1000, 60_000);
+}
+/** 可中断的 sleep：用户 signal 触发 abort 立刻 reject，不阻塞退出。 */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error('aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** 构造带诊断的 Error；401/403 走专属文案，避免"重试 5 次才发现是 key 失效"。 */
+function buildChatError(resp, body) {
+    const status = resp.status;
+    const head = `[${status} ${resp.statusText}]`;
+    if (isClientAuthError(status)) {
+        return new Error(`LLM 鉴权失败 ${head}：API key 可能失效、过期或无权访问 model "${resp.url.split('/').pop()}".\n` +
+            `请检查 .env / ~/.minimal-agent/config.json 的 MINIMAL_AGENT_API_KEY 与 provider 配置。\n` +
+            `原始错误：${body.slice(0, 500)}`);
+    }
+    return new Error(`LLM 请求失败 ${head}：${body.slice(0, 500)}`);
+}
+/**
+ * 把用户 signal 与超时 signal 组合，任一触发即 abort。
+ * AbortSignal.any 是 Node 20.3+ / Bun 内置，project engines.node=">=20" 满足。
+ */
+function combinedSignal(userSignal) {
+    const timeout = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    if (!userSignal)
+        return timeout;
+    return AbortSignal.any([userSignal, timeout]);
+}
 /**
  * 调用 LLM 并以流的形式 yield 事件。
  *
@@ -90,7 +171,7 @@ export async function* chat(args) {
     // response_format.type=json_schema，会回 400。已知不支持的 model 直接跳过，
     // 撞到 400 则退化重试（去掉 response_format，靠 prompt 内嵌 schema + 上层 extractJsonPayload 容错解析）。
     const rfKey = `${provider.baseURL}::${provider.model}`;
-    const wantResponseFormat = responseFormat !== undefined && !rfUnsupported.has(rfKey);
+    let wantResponseFormat = responseFormat !== undefined && !rfUnsupported.has(rfKey);
     const postChat = (withResponseFormat) => fetch(url, {
         method: 'POST',
         headers: {
@@ -110,9 +191,11 @@ export async function* chat(args) {
             // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
             response_format: withResponseFormat ? responseFormat : undefined,
         }),
-        signal,
+        // 用组合 signal：用户 signal 触发的 abort + 120s fetch 超时，任意一个先到即中断。
+        // （之前裸传 signal，fetch 永远不超时，gateway 桥接子进程挂死时 IM 链卡死——P0-1 根因）
+        signal: combinedSignal(signal),
     });
-    // 3. 发请求（fetch 在 Bun/Node 20+ 内置）
+    // 3. 发请求（fetch 在 Bun/Node 20+ 内置），带重试 + 超时
     const reqId = ++reqCounter;
     dlog('llm', `req#${reqId} POST →`, {
         model: provider.model,
@@ -120,24 +203,89 @@ export async function* chat(args) {
         msgs: cleanedMessages.length,
         tools: openaiTools.length,
     });
-    let resp = await postChat(wantResponseFormat);
-    // 4. 错误处理：先处理 "json_schema 不支持" 的退化重试，再翻译其它 HTTP 错误
-    if (!resp.ok) {
+    // 3a. 重试循环：每个 attempt 内部可能触发"response_format 不支持 → 去掉"的本地退化
+    //     （本地退化不算重试，仍属同一 attempt 的"拿到 200"路径的一部分）
+    //     只有"网络/超时/5xx/429"才跨 attempt 重试，4xx 业务错误直接抛
+    //     （401/403 走 buildChatError 的专属文案，不浪费 5 次重试）
+    let resp;
+    let lastErr;
+    for (let attempt = 1; attempt <= DEFAULT_RETRY.maxAttempts; attempt++) {
+        // 用户按 ESC/Ctrl+C 触发的 abort：立刻退出，不重试
+        if (signal?.aborted) {
+            throw new Error('aborted');
+        }
+        try {
+            resp = await postChat(wantResponseFormat);
+        }
+        catch (e) {
+            // 1) 用户主动 abort（signal.aborted 触发 AbortError）→ 立刻抛
+            if (signal?.aborted)
+                throw new Error('aborted');
+            // 2) AbortSignal.timeout 触发的超时（Fetch 120s 还没回）
+            // 3) 其它网络错误（ECONNRESET / fetch failed / DNS 失败）→ 全部按"可重试"处理
+            const err = e;
+            lastErr = new Error(`LLM 网络错误 [${err.name ?? 'NetworkError'}]：${err.message}`);
+            dlog('llm', `req#${reqId} attempt ${attempt} failed (network):`, err.message);
+            if (attempt >= DEFAULT_RETRY.maxAttempts)
+                break;
+            const delay = Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
+            dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts})`);
+            await sleep(delay, signal);
+            continue;
+        }
+        // resp.ok = true 直接跳出循环
+        if (resp.ok)
+            break;
+        // resp !ok：先看是不是 json_schema 不支持（本地退化路径，不算重试）
         const errText = await resp.text().catch(() => '');
         if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
             // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。
             rfUnsupported.add(rfKey);
             console.warn(`[minimal-agent] provider model "${provider.model}" 不支持 response_format.json_schema，` +
                 `已退化为 prompt 引导 + 容错解析（结构化输出的硬保证降级为尽力而为）。`);
-            resp = await postChat(false);
-            if (!resp.ok) {
-                const e2 = await resp.text().catch(() => '');
-                throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${e2.slice(0, 500)}`);
+            wantResponseFormat = false; // 本 attempt 内继续，关闭 response_format
+            // 在同一 attempt 内再发一次（不计重试）
+            try {
+                resp = await postChat(false);
+            }
+            catch (e) {
+                // 退化二次 fetch 也网络错：把错误外提到外层重试循环
+                const err = e;
+                lastErr = new Error(`LLM 网络错误 [${err.name ?? 'NetworkError'}]：${err.message}`);
+                dlog('llm', `req#${reqId} attempt ${attempt} fallback fetch failed:`, err.message);
+                if (signal?.aborted)
+                    throw new Error('aborted');
+                if (attempt >= DEFAULT_RETRY.maxAttempts)
+                    break;
+                const delay = Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
+                dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts})`);
+                await sleep(delay, signal);
+                continue;
             }
+            // 退化后 OK 或 仍 !ok 都走下面统一判断
+            if (resp.ok)
+                break;
         }
-        else {
-            throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${errText.slice(0, 500)}`);
+        // 4xx 业务错误：不重试，直接抛（401/403 走 buildChatError 专属文案）
+        if (!isRetryableStatus(resp.status)) {
+            throw buildChatError(resp, errText);
         }
+        // 5xx / 408 / 425 / 429：可重试
+        lastErr = buildChatError(resp, errText);
+        dlog('llm', `req#${reqId} attempt ${attempt} failed [${resp.status}]:`, errText.slice(0, 200));
+        if (attempt >= DEFAULT_RETRY.maxAttempts)
+            break;
+        // 429 优先用 Retry-After 头，否则走指数退避
+        const retryAfterMs = parseRetryAfter(resp);
+        const delay = retryAfterMs !== undefined
+            ? retryAfterMs
+            : Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
+        dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts}, retryAfter=${retryAfterMs ?? 'exp'})`);
+        await sleep(delay, signal);
+    }
+    // 5 次都没拿到 200：把最后一次的 Error 抛出去
+    if (!resp || !resp.ok) {
+        throw lastErr ?? new Error('LLM 请求失败：超过最大重试次数');
     }
     if (!resp.body) {
         throw new Error('LLM 响应没有 body（provider 可能不支持流式？）');

package/src/loop.js

@@ -76,12 +76,7 @@ export async function* runQuery(userInput, options) {
         expireOldEntries(sessionState?.microCompact);
         if (signal?.aborted) {
             // 中断标记帮助模型理解上下文
-            history.push({
-                role: 'user',
-                content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
-                timestamp: Date.now(),
-                id: crypto.randomUUID(),
-            });
+            pushInterruptMarker(history);
             // code='aborted'：让 `-p --output-format json` 把终结原因映射成 stop_reason='interrupted'
             yield { type: 'error', error: '已被用户中断', code: 'aborted' };
             return;
@@ -193,12 +188,7 @@ export async function* runQuery(userInput, options) {
         catch (e) {
             if (e.name === 'AbortError') {
                 // 用户主动中断：记录标记消息，不报红色错误
-                history.push({
-                    role: 'user',
-                    content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
-                    timestamp: Date.now(),
-                    id: crypto.randomUUID(),
-                });
+                pushInterruptMarker(history);
                 yield { type: 'interrupted' };
                 return;
             }
@@ -395,6 +385,19 @@ export async function* runQuery(userInput, options) {
     };
 }
 // ---------------- 辅助函数 ----------------
+/**
+ * 把"用户按下了 ESC/Ctrl+C 中断了任务"标记消息 push 到 history。
+ * 两处使用：① loop 入口 signal 检查后 ② chat AbortError 捕获后。
+ * 抽出来消除重复——同时保证两条路径写入的文案 + shape 完全一致。
+ */
+function pushInterruptMarker(history) {
+    history.push({
+        role: 'user',
+        content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
+}
 /** 把一条 tool_call_delta 合并到累积数组上 */
 function mergeToolCallDelta(acc, ev) {
     let slot = acc[ev.index];

package/src/plugins/pluginLoader.js

@@ -124,7 +124,8 @@ export async function loadPluginApi(pluginRoot) {
         return null;
     }
 }
-/** 测试用：重置加载器缓存。 */
+/** 测试用：重置加载器缓存 + 绿色版内置注册表。 */
 export function _resetPluginLoader() {
     loaderCache.clear();
+    builtinApis.clear();
 }

package/src/plugins/pluginRunner.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/plugins/pluginRunner.ts —— 框架级 slash-命令分发器
+ *  src/plugins/pluginRunner.ts —— 框架级 slash-激活分发器
  * ------------------------------------------------------------
  *  通用分发器，**不含任何插件特定逻辑**。
  *
@@ -9,7 +9,8 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 当普通问句喂给 runQuery（让 LLM 自己解释 / 未知命令）
+ *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
+ *          未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 import { discoverPlugins, resolveCommand, buildCommandInput, } from './commandRouter.js';
@@ -28,27 +29,14 @@ export async function* runWithPlugins(userInput, options) {
         });
         return;
     }
-    const manifests = await discoverPlugins();
+    // 确保插件已发现（resolveCommand 依赖 pluginCache）
+    await discoverPlugins();
     const matched = resolveCommand(userInput);
     if (!matched) {
-        // 提取命令名用于错误提示
-        const cmdName = userInput.trimStart().split(/\s+/)[0]; // "/workflow" 或 "/plan"
-        // 有插件但未命中该命令 → 明确提示可用命令
-        if (manifests.length > 0) {
-            const cmdList = manifests.flatMap((m) => m.commands.map((c) => `/${c.name}`)).join('、');
-            yield {
-                type: 'error',
-                error: `未找到命令 "${cmdName}"。已安装的插件命令：${cmdList || '（无）'}。`,
-            };
-        }
-        else {
-            // 无任何插件 → 告知用户
-            yield {
-                type: 'error',
-                error: `当前未安装任何插件。命令 "${cmdName}" 无法执行。`,
-            };
-        }
-        // fallback 到普通 TAOR 对话，用户可继续操作
+        // 未命中任何插件命令 → 静默透传 runQuery。
+        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
+        // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
+        // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
         yield* runQuery(userInput, {
             provider,
             history,

package/src/prompts/pluginList.js

@@ -28,17 +28,17 @@ export async function getPluginMetaList() {
  *
  * 风格对齐 skillList.formatSkillHint()：
  *   - 每个插件固定格式
- *   - 明确标注触发方式（"必须由用户输入 /xxx 触发"）
+ *   - 明确标注触发方式（"由用户通过 /xxx 激活"）
  *   - 无插件时返回空字符串（调用方自行决定是否追加）
  */
 export function formatPluginHint(plugins) {
     if (plugins.length === 0)
         return '';
     const lines = [
-        '# 可用插件（/命令）',
+        '# 可用插件（/激活）',
         '',
-        '以下是当前已安装的插件。**插件只能由用户通过 /xxx 命令触发——你绝对不能代替用户执行、模拟或建议使用插件功能**。',
-        '只有当用户明确询问"有哪些命令/插件可用"时，才列出以下内容。其他时候不要提及插件。',
+        '以下是当前已安装的插件。**插件只能由用户通过 /xxx 激活——你绝对不能代替用户执行、模拟或建议使用插件功能**。',
+        '只有当用户明确询问"有哪些可用插件/激活入口"时，才列出以下内容。其他时候不要提及插件。',
         '',
     ];
     for (const p of plugins) {
@@ -46,7 +46,7 @@ export function formatPluginHint(plugins) {
         lines.push(`- **描述**: ${p.description}`);
         if (p.commands.length > 0) {
             const cmdList = p.commands.map((c) => `\`/${c.name}\``).join('、');
-            lines.push(`- **命令**: ${cmdList}`);
+            lines.push(`- **激活**: ${cmdList}`);
         }
         lines.push('');
     }

package/src/prompts/promptAssembly.js

@@ -65,15 +65,15 @@ const CORE_IDENTITY = `# 思维与立场（核心：像专家一样独立思考
 3. **判不准边界就先确认**：一句话澄清"你是继续刚才的 X，还是开始新的？"，别默默假设。
 - 当前用户消息 + 紧邻的最近几条消息，权重永远高于更早历史；越早、越不相关的内容参考价值越低。
 
-# 上下文隔离（重要！工作流/命令执行完毕后的行为规则）
-- /plan、/workflow 等命令执行完后**自动回到普通对话模式**——下一条用户输入默认是全新任务。
+# 上下文隔离（重要！工作流/激活执行完毕后的行为规则）
+- /plan、/workflow 等激活执行完后**自动回到普通对话模式**——下一条用户输入默认是全新任务。
 - **只有当用户明确提到延续意图时**（"继续"、"接着做"、"按照计划执行"、"读一下 PLAN.md"、"修改刚才的结果"），才去关联之前的工作流产物（PLAN.md、生成的文件等）。
 - 用户提出全新任务时（如"帮我写个函数"、"这个bug怎么修"、"review 下代码"），**不要主动 Read 之前的 PLAN.md 或引用上次工作流的结果**——那是上一次的产出，与当前任务无关。
 - 当前目录可能存在之前 /plan 留下的 PLAN.md 文件：判断标准是**用户消息是否包含对之前产出的引用**？没有就当新任务处理。
 - 如果你不确定是新任务还是延续，优先按**新任务**处理——宁可多问一句也不要用旧上下文污染新工作。
 
 # 中断后调整（重要！）
-- 用户可能在上一步 /plan 或 /workflow 执行中途按 ESC/Ctrl+C 中断，然后立即输入调整指令（如"把第3步改成xxx"、"换个方向重新计划"）。
+- 用户可能在上一步 /plan 或 /workflow 激活中途按 ESC/Ctrl+C 中断，然后立即输入调整指令（如"把第3步改成xxx"、"换个方向重新计划"）。
 - **检测方法**：如果用户消息包含调整/修改/重做/换方向 等词 + 历史中有 /plan 或 /workflow 的痕迹 → 这是**中断后调整**，不是全新任务。
 - **小调整处理**：先 Read ./PLAN.md 了解当前计划状态，然后直接在当前 TAOR 对话中完成修改（Edit 写入 PLAN.md 或用工具产出新文件）。不需要重新跑 /plan 工作流。
 - **大改/重做处理**：如果用户要求完全重做或换方向，建议用户用 '/plan 新目标' 重新跑完整流程——这会覆盖旧的 PLAN.md 并从头开始。
@@ -206,38 +206,3 @@ export async function assembleBasePrompt(options) {
     }
     return parts.join('\n\n');
 }
-/**
- * 只生成 Layer 3（skill 列表）+ Layer 4（plugin 列表）的轻量提示词。
- *
- * 用于 workflow 的 llm 步骤（tools=[]，不能执行工具但需要知道能力边界，
- * 以便在输出文本中引用可用的 skill/plugin）。
- */
-export async function assembleCapabilityHint(cwd) {
-    const parts = [];
-    let hasContent = false;
-    // Layer 3: Skill 目录
-    const skills = await getSkillList();
-    const skillHint = formatSkillHint(skills);
-    if (skillHint) {
-        parts.push(skillHint);
-        hasContent = true;
-    }
-    // Layer 4: Plugin 目录（可选增量，异常时跳过）
-    try {
-        const plugins = await getPluginMetaList();
-        const pluginHint = formatPluginHint(plugins);
-        if (pluginHint) {
-            parts.push(pluginHint);
-            hasContent = true;
-        }
-    }
-    catch {
-        // 插件扫描失败不影响 skill hint
-    }
-    if (!hasContent)
-        return '';
-    return ('\n\n--- 能力参考 ---\n' +
-        '以下是你可用的技能和插件（本步骤不能直接调用工具，但编写计划/回答时应考虑它们的存在，必要时建议用户后续使用）：\n' +
-        parts.join('\n\n') +
-        '\n');
-}

package/src/prompts/skillList.js

@@ -91,7 +91,7 @@ export function formatSkillHint(skills) {
     }
     const lines = [];
     // ---- 标题段 ----
-    lines.push('# 可用技能（/命令）');
+    lines.push('# 可用技能（/激活）');
     lines.push('');
     lines.push('以下是当前可用的技能（**双源**：用户项目目录 + minimal-agent 包目录，同名时项目优先）。**当用户需求与某个技能的功能描述匹配时，你应该主动使用它**。');
     lines.push('在使用前，先用 Read 工具读取下方每个技能卡片里的 `**技能目录**` 路径 + `/SKILL.md` 了解完整流程。');

package/src/prompts/system.js

@@ -8,7 +8,6 @@
  *
  *  新代码请直接使用：
  *    - assembleBasePrompt()     → 完整 5 层基础内核
- *    - assembleCapabilityHint()  → 轻量版（仅 skill + plugin）
  * ============================================================
  */
 import { assembleBasePrompt } from './promptAssembly.js';

package/src/ui/AskQuestion.js

@@ -21,10 +21,27 @@ import { useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 /** description 过长截断到此长度，防止 live 区被超长文本撑爆。 */
 const DESC_MAX = 80;
+/**
+ * 提问上限——与 system prompt 里的"最多 4 题"硬性对齐。超出会：
+ *   - UI 截断到 4 题（仅前 4 题可答，后面的被静默丢弃）
+ *   - stderr 注记，提示上游（callers 应在调 AskUserQuestion 工具前自检）
+ * 这是防御层——理想情况是 tool 上游 Zod 校验就拦住。
+ */
+const MAX_QUESTIONS = 4;
 function clampDesc(s) {
     return s.length > DESC_MAX ? `${s.slice(0, DESC_MAX - 1)}…` : s;
 }
 export function AskQuestion({ questions, onAnswer, onCancel, }) {
+    // 硬限 4 题；超量截断并注记
+    const effectiveQuestions = questions.length > MAX_QUESTIONS
+        ? (() => {
+            try {
+                process.stderr.write(`[AskUserQuestion] 收到 ${questions.length} 题超过上限 ${MAX_QUESTIONS}，已截断\n`);
+            }
+            catch { /* ignore */ }
+            return questions.slice(0, MAX_QUESTIONS);
+        })()
+        : questions;
     // 当前进行到第几题
     const [questionIndex, setQuestionIndex] = useState(0);
     // 当前题高亮的选项下标（含末尾「其他」伪选项）
@@ -37,7 +54,7 @@ export function AskQuestion({ questions, onAnswer, onCancel, }) {
     const [textMode, setTextMode] = useState(false);
     // 文本子模式的累积草稿
     const [draft, setDraft] = useState('');
-    const current = questions[questionIndex];
+    const current = effectiveQuestions[questionIndex];
     const multi = current?.multiSelect === true;
     const options = current?.options ?? [];
     // 末尾「其他」伪选项占据下标 options.length，故列表总长 = options.length + 1
@@ -47,7 +64,7 @@ export function AskQuestion({ questions, onAnswer, onCancel, }) {
     function advance(answer) {
         const nextAnswers = [...answers, answer];
         const nextQ = questionIndex + 1;
-        if (nextQ >= questions.length) {
+        if (nextQ >= effectiveQuestions.length) {
             onAnswer(nextAnswers);
             return;
         }
@@ -166,7 +183,7 @@ export function AskQuestion({ questions, onAnswer, onCancel, }) {
     if (!current) {
         return (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "gray", children: "\uFF08\u65E0\u95EE\u9898\uFF09" }) }));
     }
-    const progress = `提问 (${questionIndex + 1}/${questions.length}) · ${current.header}`;
+    const progress = `提问 (${questionIndex + 1}/${effectiveQuestions.length}) · ${current.header}`;
     return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "cyan", bold: true, children: progress }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { children: current.question }) }), textMode ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "gray", children: "\u270F\uFE0F \u81EA\u7531\u8F93\u5165\uFF1A" }), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: draft || ' ' }) }), _jsx(Text, { color: "gray", children: "\u8F93\u5165\u540E Enter \u63D0\u4EA4 \u00B7 ESC \u8FD4\u56DE" })] })) : (_jsxs(Box, { flexDirection: "column", children: [options.map((opt, i) => {
                         const active = i === idx;
                         const box = multi ? (picked.has(i) ? '[x] ' : '[ ] ') : '';