@bolloon/bolloon-agent 0.4.5 → 0.4.7

package/dist/agents/pi-sdk.js

@@ -201,6 +201,15 @@ export class PiAgentSession {
     currentSignal = null;
     /** Bootstrap SessionStart 拼的 system prompt 片段 (用完即清) */
     bootstrapAddition = '';
+    /** 2026-08-12 (Task3 认知卸载): 工具选择与认知卸载指南 — 注入 system prompt, 降低"模型不触发 write/edit/read"率. */
+    static TOOL_SELECTION_GUIDE = `【工具选择与认知卸载指南 (严格遵循)】
+- 写/改文件: 必须用 write_file / edit_file (不要用 terminal 拼字符串写文件).
+- 读文件: 用 read_file / read_directory / list_files.
+- 跑命令/查状态/装依赖/跑脚本: 用 terminal.
+- 执行 git 操作: 用 git_* 专用工具 (git_diff/git_commit/git_push/git_branch/git_log).
+- 查看/调用技能: 用 list_skills / use_skill.
+- 认知卸载: 当任务对你过大或反复失败时, 不要死磕 — 用 delegate_to_engine 把编码/复杂任务委派给外部引擎 (codex/claude-code/opencode), 或把目标拆小分步完成.
+- 每步只选一个最合适的工具, 先读后写, 写完验证 (跑 tsc/vitest 或读回文件).`;
     /** 当前 prompt 开始时间 (供 Stop hook 计算 durationMs) */
     promptStartTime = 0;
     /** 当前 channel id (由 getAgentForChannel / prompt 4 参注入, 供 hook / log 使用) */
@@ -1042,38 +1051,40 @@ export class PiAgentSession {
         }
         // M2.4: persona 缓存
         if (!this.cachedPersonaSection && this.persona) {
-            this.cachedPersonaSection = `
-角色描述: ${this.persona.description || '无'}
-性格特点: ${this.persona.personality || '无'}
-问候语: ${this.persona.greeting || '无'}
+            this.cachedPersonaSection = `
+角色描述: ${this.persona.description || '无'}
+性格特点: ${this.persona.personality || '无'}
+问候语: ${this.persona.greeting || '无'}
 `;
         }
-        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${this.cachedPersonaSection}
-当前工作目录: ${this.cwd}
-当前身份: ${this.identity.name} (${this.identity.did})
-${this.currentIntentHint}
-
-${this.getToolDefinitions()}
-
-工作模式:
-1. 理解用户自然语言请求
-2. 分析需要哪些工具来完成
-3. 按顺序调用工具并观察结果
-4. 根据观察结果决定下一步
-5. 最终给出完整回答
-
-重要 (一次命中要求):
-- 每次只调用一个工具
-- 仔细分析工具返回结果
-- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
-- 如果需要更多信息，继续调用工具
-
-【工具调用格式 (严格遵守, 否则系统无法解析)】
-- 你只能输出**一个**工具调用, 不要堆叠多个 invoke
-- 工具调用格式: {"name":"<tool_name>","input":{"arg1":"value1"}}
-- 用 markdown json code block 包裹: \`\`\`json\n{"name":"X","input":{...}}\n\`\`\`
-- 工具调用前可以简短思考 (1-2 句话), 但**不要写长篇 thinking** (会撞 max_tokens)
-- 工具调用后必须等结果, 不要在同一个回复里继续输出
+        const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${this.cachedPersonaSection}
+当前工作目录: ${this.cwd}
+当前身份: ${this.identity.name} (${this.identity.did})
+${this.currentIntentHint}
+
+${this.getToolDefinitions()}
+
+${PiAgentSession.TOOL_SELECTION_GUIDE}
+
+工作模式:
+1. 理解用户自然语言请求
+2. 分析需要哪些工具来完成
+3. 按顺序调用工具并观察结果
+4. 根据观察结果决定下一步
+5. 最终给出完整回答
+
+重要 (一次命中要求):
+- 每次只调用一个工具
+- 仔细分析工具返回结果
+- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
+- 如果需要更多信息，继续调用工具
+
+【工具调用格式 (严格遵守, 否则系统无法解析)】
+- 你只能输出**一个**工具调用, 不要堆叠多个 invoke
+- 工具调用格式: {"name":"<tool_name>","input":{"arg1":"value1"}}
+- 用 markdown json code block 包裹: \`\`\`json\n{"name":"X","input":{...}}\n\`\`\`
+- 工具调用前可以简短思考 (1-2 句话), 但**不要写长篇 thinking** (会撞 max_tokens)
+- 工具调用后必须等结果, 不要在同一个回复里继续输出
 - <final gen> 只在**真完成所有任务**时输出, 不要在工具调用前/中输出${this.judgmentGateAddition}${this.contextHintAddition}`;
         // 2026-06-15: 把 currentOnStream 传给 loop, 让 step-timeline 在 pivot 循环里也能 emit step_start/done
         //   之前 loop.execute() 不接 streamCallback, 导致 step-timeline 只能看到老 runReActLoop 路径
@@ -1265,10 +1276,10 @@ ${this.getToolDefinitions()}
             }
             // M2.4: persona section 缓存 — persona 在 loadPersona() 时一次设定, 此后不变
             if (!this.cachedPersonaSection && this.persona) {
-                this.cachedPersonaSection = `
-角色描述: ${this.persona.description || '无'}
-性格特点: ${this.persona.personality || '无'}
-问候语: ${this.persona.greeting || '无'}
+                this.cachedPersonaSection = `
+角色描述: ${this.persona.description || '无'}
+性格特点: ${this.persona.personality || '无'}
+问候语: ${this.persona.greeting || '无'}
 `;
             }
             const personaSection = this.cachedPersonaSection;
@@ -1286,26 +1297,28 @@ ${this.getToolDefinitions()}
                     .join('\n');
                 loopProgressSection = `\n【本轮循环进度】你已完成以下 ${loopActionLog.length} 个动作, 这是连续执行的同一轮任务:\n${actionLines}\n请基于已有结果继续推进, 不要重复执行上面已成功的动作. 全部完成后用 <final gen> 结束.\n`;
             }
-            const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
-当前工作目录: ${this.cwd}
-当前身份: ${this.identity.name} (${this.identity.did})
-${refineContext}
-${this.currentIntentHint}
-${loopProgressSection}
-
-${toolDefs}
-
-工作模式:
-1. 理解用户自然语言请求
-2. 分析需要哪些工具来完成
-3. 按顺序调用工具并观察结果
-4. 根据观察结果决定下一步
-5. 最终给出完整回答
-
-重要:
-- 每次只调用一个工具
-- 仔细分析工具返回结果
-- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
+            const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
+当前工作目录: ${this.cwd}
+当前身份: ${this.identity.name} (${this.identity.did})
+${refineContext}
+${this.currentIntentHint}
+${loopProgressSection}
+
+${toolDefs}
+
+${PiAgentSession.TOOL_SELECTION_GUIDE}
+
+工作模式:
+1. 理解用户自然语言请求
+2. 分析需要哪些工具来完成
+3. 按顺序调用工具并观察结果
+4. 根据观察结果决定下一步
+5. 最终给出完整回答
+
+重要:
+- 每次只调用一个工具
+- 仔细分析工具返回结果
+- 当任务完成时，必须在回答末尾添加 <final gen> 标记表示结束
 - 如果需要更多信息，继续调用工具${this.judgmentGateAddition}${this.contextHintAddition}`;
             // 3 个恢复机制 (Claude Code 论文 9-step pipeline 内部):
             //   1. max output token 升级 (最多 3 次, 每次 maxOutputTokens 翻倍)
@@ -2376,37 +2389,37 @@ ${toolDefs}
     getDefaultResponse(input) {
         const operationsRef = PiAgentSession.getOperationsReference();
         if (operationsRef) {
-            return `收到了: "${input}"
-
-我是一个判断力处理智能体，支持自然语言交互。
-
-可用操作（直接说出即可）:
-${this.extractOperationsFromRef(operationsRef)}
-
-示例请求:
-  - "读取 src/index.ts 文件"
-  - "总结一下 README.md"
-  - "查看当前连接了哪些节点"
+            return `收到了: "${input}"
+
+我是一个判断力处理智能体，支持自然语言交互。
+
+可用操作（直接说出即可）:
+${this.extractOperationsFromRef(operationsRef)}
+
+示例请求:
+  - "读取 src/index.ts 文件"
+  - "总结一下 README.md"
+  - "查看当前连接了哪些节点"
   - "向 QmABC... 发送测试消息"`;
         }
-        return `收到了: "${input}"
-
-我是一个判断力处理智能体，支持自然语言交互。
-
-可用操作（直接说出即可）:
-  - "读取 README.md" - 读取并分析文档
-  - "总结文档" - 总结文档内容
-  - "改进文档，按照X要求" - 改进文档
-  - "查看节点" - 查看已连接的对等节点
-  - "向X发送消息Y" - 向对等节点发送消息
-  - "广播消息X" - 广播消息到所有节点
-  - "查看身份" - 查看当前智能体身份
-  - "查看日志" - 查看最近操作日志
-
-示例请求:
-  - "读取 src/index.ts 文件"
-  - "总结一下 README.md"
-  - "查看当前连接了哪些节点"
+        return `收到了: "${input}"
+
+我是一个判断力处理智能体，支持自然语言交互。
+
+可用操作（直接说出即可）:
+  - "读取 README.md" - 读取并分析文档
+  - "总结文档" - 总结文档内容
+  - "改进文档，按照X要求" - 改进文档
+  - "查看节点" - 查看已连接的对等节点
+  - "向X发送消息Y" - 向对等节点发送消息
+  - "广播消息X" - 广播消息到所有节点
+  - "查看身份" - 查看当前智能体身份
+  - "查看日志" - 查看最近操作日志
+
+示例请求:
+  - "读取 src/index.ts 文件"
+  - "总结一下 README.md"
+  - "查看当前连接了哪些节点"
   - "向 QmABC... 发送测试消息"`;
     }
     extractOperationsFromRef(ref) {
@@ -2431,13 +2444,13 @@ ${this.extractOperationsFromRef(operationsRef)}
             }
         }
         return operationLines.length > 0 ? operationLines.join('\n') :
-            `  - "读取 README.md" - 读取并分析文档
-  - "总结文档" - 总结文档内容
-  - "改进文档，按照X要求" - 改进文档
-  - "查看节点" - 查看已连接的对等节点
-  - "向X发送消息Y" - 向对等节点发送消息
-  - "广播消息X" - 广播消息到所有节点
-  - "查看身份" - 查看当前智能体身份
+            `  - "读取 README.md" - 读取并分析文档
+  - "总结文档" - 总结文档内容
+  - "改进文档，按照X要求" - 改进文档
+  - "查看节点" - 查看已连接的对等节点
+  - "向X发送消息Y" - 向对等节点发送消息
+  - "广播消息X" - 广播消息到所有节点
+  - "查看身份" - 查看当前智能体身份
   - "查看日志" - 查看最近操作日志`;
     }
     async suggestRename(messages) {

package/dist/agents/process-runner.js

@@ -0,0 +1,105 @@
+/**
+ * process-runner.ts — 后台进程管理 (2026-08-12, TaskD)
+ *
+ * 借鉴 hermes terminal_tool: 长期运行命令不应阻塞对话.
+ *   - foreground: 命令结束立即返回 (即使超时设长, 不 sleep 阻塞)
+ *   - background: spawn 后台执行, 返回 session_id, 用 process(action=poll/wait/kill) 管理
+ *   - 禁止 nohup/setsid/trailing '&' — 用 background 让系统跟踪进程
+ *
+ * 进程注册表: 模块级 Map<sessionId, {proc, cmd, startedAt, output[]}>, 供 process 工具查询.
+ */
+import { spawn } from 'child_process';
+import * as path from 'path';
+const sessions = new Map();
+let seq = 0;
+function genId() {
+    seq++;
+    return `proc-${Date.now().toString(36)}-${seq}`;
+}
+/**
+ * 后台启动一个 shell 命令. 立即返回 session 记录 (不阻塞).
+ * 命令字符串经调用方 (runTerminalCommand) 护栏检查.
+ */
+export function spawnBackground(raw, cwd = process.cwd()) {
+    const id = genId();
+    const session = { id, cmd: raw.slice(0, 300), cwd, startedAt: Date.now(), exitCode: null, status: 'running', output: '', proc: null };
+    sessions.set(id, session);
+    // Windows 用 cmd /c; POSIX 用 /bin/sh -c
+    const shell = process.platform === 'win32' ? 'cmd' : '/bin/sh';
+    const shellArgs = process.platform === 'win32' ? ['/c', raw] : ['-c', raw];
+    try {
+        const proc = spawn(shell, shellArgs, { cwd, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, windowsHide: true });
+        session.proc = proc;
+        proc.stdout.on('data', (d) => { session.output = (session.output + d.toString()).slice(-16000); });
+        proc.stderr.on('data', (d) => { session.output = (session.output + d.toString()).slice(-16000); });
+        proc.on('close', (code) => { session.exitCode = code; session.status = 'exited'; });
+        proc.on('error', (e) => { session.status = 'error'; session.error = e.message; });
+    }
+    catch (e) {
+        session.status = 'error';
+        session.error = e?.message;
+    }
+    return session;
+}
+/** 查询后台进程状态 (不阻塞). 返回脱敏视图. */
+export function pollSession(id) {
+    const s = sessions.get(id);
+    if (!s)
+        return { ok: false, found: false };
+    return {
+        ok: true,
+        found: true,
+        session: {
+            id: s.id, cmd: s.cmd, startedAt: s.startedAt, exitCode: s.exitCode,
+            status: s.status, output: s.output.slice(-4000), error: s.error,
+        },
+    };
+}
+/** 等待后台进程结束 (最多 timeoutMs). 返回最终状态. */
+export async function waitSession(id, timeoutMs = 30000) {
+    const s = sessions.get(id);
+    if (!s)
+        return { ok: false, error: `未知 session ${id}` };
+    if (s.status !== 'running') {
+        return { ok: true, session: { id: s.id, status: s.status, exitCode: s.exitCode, output: s.output.slice(-4000) } };
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && s.status === 'running') {
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    return {
+        ok: s.status !== 'running',
+        session: { id: s.id, status: s.status, exitCode: s.exitCode, output: s.output.slice(-4000), timedOut: s.status === 'running' },
+    };
+}
+/** 杀死后台进程. 返回是否已终止. */
+export function killSession(id) {
+    const s = sessions.get(id);
+    if (!s)
+        return { ok: false, reason: `未知 session ${id}` };
+    if (s.status !== 'running' || !s.proc) {
+        return { ok: true, reason: `进程已 ${s.status}` };
+    }
+    try {
+        if (process.platform === 'win32')
+            s.proc.kill('SIGTERM');
+        else
+            s.proc.kill('SIGTERM');
+        s.status = 'killed';
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: `kill 失败: ${e?.message}` };
+    }
+}
+/** 列出所有后台进程 */
+export function listSessions() {
+    return Array.from(sessions.values()).map((s) => ({ id: s.id, cmd: s.cmd, status: s.status, exitCode: s.exitCode }));
+}
+/** session id 合法性 (防注入) */
+export function isValidSessionId(id) {
+    return /^proc-[a-z0-9]+-\d+$/.test(id || '');
+}
+export function sessionIdFromPath(p) {
+    return path.basename(String(p || '').trim());
+}

package/dist/agents/skill-organizer.js

@@ -143,25 +143,25 @@ export async function scanLeftoverSkills(opts = {}) {
 // ───────────────────────── B. 经验进化 (LLM 完整总结) ─────────────────────────
 /** 把候选的工具调用记录扩写成完整经验 — LLM prompt (结构化 JSON 输出) */
 export function buildEvolvePrompt(c) {
-    return `你是经验总结专家。下面是 Bolloon 智能体在一轮运行中连续成功调用的工具记录 (已运行 ${c.runs || 1} 次)。
-
-工具记录:
-名称: ${c.name}
-描述: ${c.description}
-原始记录:
-${String(c.body || '').slice(0, 4000)}
-
-请把这份"工具调用记录"扩写成一份完整的、可复用的经验文档, 要求:
-1. name: 一个简短的小写英文名 (字母数字连字符, 概括这套操作)
-2. description: 一句话描述 (什么场景用)
-3. body: 完整经验正文, 按以下结构:
-   ## 背景 — 这套操作在什么场景下用, 解决什么问题
-   ## 触发条件 — 什么信号/需求出现时应该使用
-   ## 流程 — 具体步骤 (保留原始工具名), 每步说明目的
-   ## 注意事项 — 易错点 / 边界情况 / 已知坑
-   ## 验证 — 怎么确认结果正确
-
-只输出一个 JSON 对象, 不要任何其他文字:
+    return `你是经验总结专家。下面是 Bolloon 智能体在一轮运行中连续成功调用的工具记录 (已运行 ${c.runs || 1} 次)。
+
+工具记录:
+名称: ${c.name}
+描述: ${c.description}
+原始记录:
+${String(c.body || '').slice(0, 4000)}
+
+请把这份"工具调用记录"扩写成一份完整的、可复用的经验文档, 要求:
+1. name: 一个简短的小写英文名 (字母数字连字符, 概括这套操作)
+2. description: 一句话描述 (什么场景用)
+3. body: 完整经验正文, 按以下结构:
+   ## 背景 — 这套操作在什么场景下用, 解决什么问题
+   ## 触发条件 — 什么信号/需求出现时应该使用
+   ## 流程 — 具体步骤 (保留原始工具名), 每步说明目的
+   ## 注意事项 — 易错点 / 边界情况 / 已知坑
+   ## 验证 — 怎么确认结果正确
+
+只输出一个 JSON 对象, 不要任何其他文字:
 {"name": "...", "description": "...", "body": "..."}`;
 }
 /** 解析 LLM 返回的 JSON (容错: 剥 markdown 代码块, 取第一个 {...}) */

package/dist/agents/skill-writer.js

@@ -266,9 +266,21 @@ export async function writeRunEndSkillCandidates(steps, source, minOk = 2) {
         return { wrote: false, reason: `成功工具不足 (${okSteps.length} < ${minOk})` };
     }
     const toolNames = okSteps.map((s) => s.name).slice(0, 5).join(', ');
-    const body = `## 背景\n本轮对话连续成功调用了 ${okSteps.length} 个工具: ${toolNames}.\n\n` +
-        `## 流程\n${okSteps.map((s) => `1. 调用 ${s.name}${s.output ? ': ' + String(s.output).slice(0, 120) : ''}`).join('\n')}\n\n` +
-        `## 注意事项\n- 工具名以 list_skills / get_operation_logs 的实际注册名为准\n- 沉淀为正式 skill 前请人工确认流程可复用\n`;
+    // 2026-08-12 (Task5): 让 run-end 候选 body 更可复用 — 结构化呈现调用链 + 每步作用 + 适用场景.
+    const stepLines = okSteps.map((s, i) => {
+        const out = s.output ? String(s.output).replace(/\s+/g, ' ').slice(0, 140) : '';
+        return `${i + 1}. **${s.name}**${out ? ` — ${out}` : ''}`;
+    }).join('\n');
+    const body = `## 适用场景\n用户请求需要连续执行工具序列: ${toolNames}.\n\n` +
+        `## 调用链\n${stepLines}\n\n` +
+        `## 流程要点\n${okSteps.map((s, i) => {
+            // 2026-08-12 (Task5 优化): 用真实输出提炼每步作用, 避免千篇一律的"调用 X 获取下一步输入".
+            const out = s.output ? String(s.output).replace(/\s+/g, ' ').trim() : '';
+            const clue = out && out.length > 30 ? out.slice(0, 60) + '…' : (out || '完成');
+            return `- 第 ${i + 1} 步 ${s.name}: ${clue}`;
+        }).join('\n')}\n\n` +
+        `## 如何验证\n- 涉及改代码: 跑 tsc + vitest 确认无错; 涉及写文件: read_file 读回校验.\n` +
+        `- 沉淀为正式 skill 前请人工确认流程可复用, 再 list_skill_candidates / promote_skill 转正\n`;
     // 2026-08-08: 稳定签名 + 固定文件名 → 同一套工具反复跑时合并更新到同一个候选 (runs++)
     const signature = toolSignature(okSteps);
     const candName = `auto-${signature}`;

package/dist/agents/workflow-pivot-loop.js

@@ -193,6 +193,16 @@ export class WorkflowPivotLoop {
      *   传原生 tools + tool_choice auto → LLM 返回结构化 tool_calls.
      */
     buildOpenAITools() {
+        // 2026-08-12 (Task3 认知卸载): 核心编码工具加强 description, 提升模型触发率.
+        const USAGE_HINT = {
+            write_file: '写/创建文件用此工具 (改代码首选). ',
+            edit_file: '修改文件指定内容用此工具 (改代码首选). ',
+            read_file: '读取文件内容用此工具. ',
+            read_directory: '列目录用此工具. ',
+            list_files: '列出文件用此工具. ',
+            terminal: '跑 shell 命令/脚本/装依赖/查状态用此工具 (不要用它写文件). ',
+            delegate_to_engine: '任务过大或复杂时委派给外部编码引擎 (认知卸载). ',
+        };
         const out = [];
         for (const [name, tool] of this.tools) {
             const params = tool.parameters || {};
@@ -207,7 +217,7 @@ export class WorkflowPivotLoop {
                 type: 'function',
                 function: {
                     name,
-                    description: tool.description || name,
+                    description: (USAGE_HINT[name] || '') + (tool.description || name),
                     parameters: { type: 'object', properties, required },
                 },
             });
@@ -866,8 +876,8 @@ export class WorkflowPivotLoop {
         //   完整重装只在 iter=1 和 compact 之后两次
         const lines = fullSystemPrompt.split('\n');
         const identityLine = lines.find((l) => l.includes('你是') && !l.includes('(续)')) ?? '';
-        return `[continuation] 你的 persona + tools + judgments 已在首轮 messageHistory 中.
-${identityLine ? identityLine + '\n' : ''}当前 step 别再读 persona 全文, 继续推进任务即可.
+        return `[continuation] 你的 persona + tools + judgments 已在首轮 messageHistory 中.
+${identityLine ? identityLine + '\n' : ''}当前 step 别再读 persona 全文, 继续推进任务即可.
 > <final gen> 只在真完成时输出.`;
     }
     /**

package/dist/agents/write-staging.js

@@ -0,0 +1,85 @@
+/**
+ * write-staging.ts — 写操作准备阶段适配 (2026-08-12, TaskC)
+ *
+ * 借鉴 hermes write_approval.py 的 staging gate: 写操作先 stage (暂存) 再 commit,
+ * 保留完整 payload (可重放/回滚) 用于审计与撤销 — 但不强制人工审批 (bolloon 是自主 agent,
+ * 写操作直接提交, 只是保留 stage 记录做"准备阶段"审计, 不打断自主循环).
+ *
+ * 设计:
+ *   - 每次 write_file / edit_file 写盘前, 记录一条 stage 到 ~/.bolloon/write-log/<ts>-<rand>.json
+ *   - stage 记录含: 相对路径 / 绝对路径 / action (create|overwrite|edit) / 变更前内容快照 / 变更意图 / 时间
+ *   - 提供 listStagedWrites / undoLastWrite (撤销最近一次写) / getStagedWrite
+ *   - 失败静默 (写日志不影响工具主路径)
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const home = () => process.env.HOME || os.homedir() || '/tmp';
+export function writeLogDir(homeDir = home()) {
+    return path.join(homeDir, '.bolloon', 'write-log');
+}
+/** 生成唯一 stage id */
+function genId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+}
+/**
+ * 写前暂存: 记录一次写操作 (准备阶段). 返回记录; 失败静默返回 null.
+ * @param relPath 相对路径
+ * @param beforeContent 变更前内容 (读盘或空)
+ * @param afterContent 变更后内容
+ * @param action 动作类型
+ */
+export async function stageWrite(relPath, beforeContent, afterContent, action, cwd = process.cwd(), homeDir = home()) {
+    try {
+        const id = genId();
+        const absPath = path.resolve(cwd, relPath);
+        const rec = { id, absPath, relPath, action, beforeContent, afterContent, createdAt: Date.now() };
+        const dir = writeLogDir(homeDir);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, `${id}.json`), JSON.stringify(rec, null, 2), 'utf-8');
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+/** 列出最近的暂存写记录 (新→旧) */
+export async function listStagedWrites(homeDir = home()) {
+    const dir = writeLogDir(homeDir);
+    let files;
+    try {
+        files = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files.filter(f => f.endsWith('.json')).sort().reverse()) {
+        try {
+            out.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf-8')));
+        }
+        catch { /* 坏文件跳过 */ }
+    }
+    return out;
+}
+/** 撤销最近一次写 (若文件内容仍等于 afterContent → 恢复 beforeContent). 返回是否撤销. */
+export async function undoLastWrite(homeDir = home()) {
+    const staged = await listStagedWrites(homeDir);
+    if (staged.length === 0)
+        return { ok: false, reason: '无暂存写记录' };
+    const rec = staged[0];
+    try {
+        // 仅当文件未被后续修改 (内容仍 = afterContent) 时才安全撤销
+        const current = await fs.readFile(rec.absPath, 'utf-8').catch(() => null);
+        if (current === rec.afterContent) {
+            await fs.writeFile(rec.absPath, rec.beforeContent, 'utf-8');
+            // 清理该 stage 记录
+            await fs.rm(path.join(writeLogDir(homeDir), `${rec.id}.json`), { force: true }).catch(() => { });
+            return { ok: true };
+        }
+        return { ok: false, reason: '文件已被后续修改, 跳过撤销' };
+    }
+    catch (e) {
+        return { ok: false, reason: `撤销失败: ${e?.message}` };
+    }
+}

package/dist/bollharness/src/scripts/deploy-guard.js

@@ -104,17 +104,17 @@ function checkRsync(cmd) {
 function block(reason, host = null) {
     let guidance;
     if (host === PROD_IP) {
-        guidance = `请使用标准部署流程：
-  后端: bash scripts/deploy.sh --yes
-  Demo 正式: bash scripts/deploy-demo.sh <name> --channel prod --yes
-  Demo 内测: bash scripts/deploy-demo.sh <name> --channel preview --yes
-  Edge/Nginx: bash scripts/deploy-edge.sh --yes
+        guidance = `请使用标准部署流程：
+  后端: bash scripts/deploy.sh --yes
+  Demo 正式: bash scripts/deploy-demo.sh <name> --channel prod --yes
+  Demo 内测: bash scripts/deploy-demo.sh <name> --channel preview --yes
+  Edge/Nginx: bash scripts/deploy-edge.sh --yes
 详见 Bolloon.md Development Commands。`;
     }
     else if (BRIDGE_VPS_HOSTS.includes(host ?? "")) {
-        guidance = `Bridge VPS 必须走 git pull 更新路径：
-  ssh root@${host} 'sudo -u boll git -C /opt/boll pull --ff-only'
-  scp/rsync 直传会重新制造 orphan worktree。
+        guidance = `Bridge VPS 必须走 git pull 更新路径：
+  ssh root@${host} 'sudo -u boll git -C /opt/boll pull --ff-only'
+  scp/rsync 直传会重新制造 orphan worktree。
   详见 docs/issues/guard-20260408-0445-bridge-vps-orphan-worktree.md。`;
     }
     else {

package/dist/bollharness-integration/context-router-judgment.js

@@ -253,9 +253,9 @@ export async function generateJudgmentInjection(filePath, gate, options = {}) {
     const header = gate === 3
         ? '# Plan Freeze - Decision Principles'
         : `# Gate ${gate} - Active Judgments`;
-    return `${header}
-# Path: ${filePath}
-# Confidence: ${(result.confidence * 100).toFixed(0)}%
-
+    return `${header}
+# Path: ${filePath}
+# Confidence: ${(result.confidence * 100).toFixed(0)}%
+
 ${result.contextYaml}`;
 }