feat(agent): implement Harness Engineering Phase 2-5 blueprint

- Add task transition CLI and API for Context Flush & Hot Swap - Enforce strict bash-only tool policy for Base Agents - Inject into system prompt for self-retrying loop - Implement Goal node updates on transitions - Add P0 Execute pre-approval block (Human-in-the-loop) - Track token metrics to billing.log

feat(agent): implement Harness Engineering Phase 2-5 blueprint
- Add task transition CLI and API for Context Flush & Hot Swap - Enforce strict bash-only tool policy for Base Agents - Inject into system prompt for self-retrying loop - Implement Goal node updates on transitions - Add P0 Execute pre-approval block (Human-in-the-loop) - Track token metrics to billing.log
yibo
1 parent b15d8570
Showing 7 changed files with 285 additions and 2 deletions
bin/lemon.js
data/system/templates/_registry.json
data/system/templates/base/agent.md
data/system/templates/base/config.json
docs/system-design/25-harness-engineering-improvements.md
server/routes/agent-chat.js
server/services/goals.js
@@ -167,6 +167,15 @@ async function run() {
       });
       console.log(JSON.stringify(res.data, null, 2));
     }
+    else if (command === 'task transition') {
+      const { values } = parseArgs({ args: args.slice(2), options: {
+        agentId: { type: 'string' }, phase: { type: 'string' }, artifact: { type: 'string', default: '' }
+      }});
+      const res = await request('POST', `/agent/${values.agentId}/task/transition`, {
+        phase: values.phase, artifact: values.artifact
+      });
+      console.log(JSON.stringify(res.data, null, 2));
+    }
     else if (command === 'pipeline create') {
       const { values } = parseArgs({ args: args.slice(2), options: {
         companyId: { type: 'string' }, file: { type: 'string' }
@@ -16,5 +16,14 @@
     "benchmarkScore": 95,
     "trainedAt": "2026-03-25",
     "usedCount": 6
+  },
+  {
+    "id": "base",
+    "name": "标准基座员工",
+    "type": "specialist",
+    "description": "严格遵循四阶段执行规范的基础执行员工",
+    "benchmarkScore": 90,
+    "trainedAt": "2026-03-26",
+    "usedCount": 0
   }
 ]
 \ No newline at end of file
+# Base Agent (Standard Corporate Employee)
+
+## 身份定位
+你是 LemonBoss 企业网络中的一名 **标准基座员工 (Base Agent)**。
+在你收到上级派发的任何 Task 时，你绝对不能“一气呵成、随地大小写代码或写产出”。你被赋予了严厉的生命周期“四段式法则”：`Research` -> `Plan` -> `Execute` -> `Verify`。
+
+## 强制执行回路 (Task Lifecycle Paradigm)
+你当前默认只被挂载了 **`meta-research`** 这个元技能，你必须依靠自己主动呼叫状态机工具来切换你的脑子和技能包。请严格按照下述单节点法则推进你的干活流程：
+
+### 阶段一：RESEARCH（调研）->你当前所处的阶段！
+1. **不要猜测，去寻找**：动用一切读取工具看懂上级给你的任务，去硬盘里找背景文件。
+3. **斩断记忆（Context Flush）**：写完后，运行 `node bin/lemon.js task transition --agentId <你自己ID> --phase plan --artifact 你的_research.md路径`。**绝不要自己在当前对话里直接去出规划！必须呼叫此命令行让系统清空你的记忆并给你换上 Plan 技能！**
+
+### 阶段二：PLAN（规划）
+*(当你成功跳过防线来到这里时，你将失去 `meta-research`，获得 `meta-plan`)*
+1. 读你的 `_research.md`。
+3. 运行 `node bin/lemon.js task transition --agentId <你自己ID> --phase execute --artifact 你的_plan.md路径`。
+
+### 阶段三：EXECUTE（执行）
+*(系统给你换上 `meta-execute` 技能时，你才会拥有修改核心文件的破坏性权限)*
+2. 运行 `node bin/lemon.js task transition --agentId <你自己ID> --phase verify`。
+
+### 阶段四：VERIFY（验证）
+*(系统给你换上 `meta-verify` 技能，你的任务是自己检测自己跑的代码或跑分)*
+1. 如果失败，将原因定入本地 `_lessons.md`，用工具打回上一阶段。
+2. 如果确信真的 PASS，才可以向上级（老板）调用归档终结命令 `report_task({status: "PASS"})`。
+
+⚠️ **警告：未经四步走流转直接汇报 `PASS` 或写代码的行为将被视为严重违规记录！**
+{
+  "type": "specialist",
+  "status": "idle",
+  "cli": {
+    "toolPolicy": {
+      "mode": "restricted",
+      "allowedTools": ["bash", "read_file", "str_replace"]
+    }
+  }
+}
+# 25. Harness Engineering Improvements (Agent 上下文与生命周期优化)
+
+## 1. 背景与目标 (Background & Objectives)
+
+随着 LemonBoss 架构从单体 Agent 演进为多租户下的“数字代理公司（Corporate OS）”，我们的宏观阵法（层级汇报、跨部门协作、OKR 分解）已初具规模（参考之前的相关系统设计）。然而，基于对前沿 Harness Engineering 最佳实践的深度反思，单个 Agent 节点在处理长链路复杂任务时，依然面临**“上下文衰减（Context Decay）”**、**“信息污染（Noise Pollution）”**、以及**“试错成本高昂（High Trial Cost）”**三大核心痛点。
+
+为了确保底层每一个“数字员工”即使在超长命名的商业运营中也不会发生注意力弥散（Attention Decay），我们提出以下补充重构计划。该计划的核心思想是：**做精信息喂食、隔离决策上下文、构建自查闭环。**
+
+---
+
+## 2. 核心改进计划 (Core Improvement Plans)
+
+### 改进点一：将四阶段分解固化为基座 Agent 的四大元技能 (Meta-Skills Integration)
+**现状痛点**：当前单个 session 会承载一个 Agent 从“思考规划”到“调用执行”直至“修复 Bug”的全生命周期。后期 Session Prompt 过长（超过甜区限度），导致关键指令被稀释，且执行边界模糊。
+**改进策略**：我们将 `Research` -> `Plan` -> `Execute` -> `Verify` 不仅作为宏观规范，而是**实际固化为基座 Agent (Base Agent) 标准配备的四大元技能包（Meta-Skills）**。
+1. **按需装载独立技能树 (Dynamic Skill Invocation)**：在底层设定中，为每一个 Base Agent 提供四个相互独立的元技能引擎接口。每次面临新任务，代理根据自身所处的流转阶段，主动调用加载专属的技能包（如只调用 `skill_plan` 去出方案）。
+2. **基于技能切换的 Context Flush（上下文切断与防污染）**：一旦当前阶段的技能执行完毕（例如调用 Planner 技能产出了 `architecture.md`），该 Session 生命周期强制结束归档。当进入下一环节调起 `skill_execute` 技能时，新开一条绝对干净的 Session，只传入上一步确定的干货文件，彻底断绝跨阶段的幻觉与信息污染。
+
+### 改进点二：实施“事前阻断阀”管理 (Human/Master pre-approval)
+**现状痛点**：人类往往在 Agent 完全做错产出一堆无效代码后（即事后）去执行 Code Review，纠错成本极高。
+**改进策略**：
+1. **杠杆前置审查**：当 CEO 或 CTO 这类管理层 Agent 产出“规划文档（Plan / Architecture）”后，系统强制挂起该节点的 `status`。
+2. **等待放行命令**：必须由 Master（人类用户） 或高阶 Validator/Innovator Review 批准该规划文档。一旦驳回，重做 Plan；一旦批准，才能生成下游子任务清单（Task Spawning）并消耗算力。以一行 Plan 的纠正，避免百行代码的错误生成。
+
+### 改进点三：渐进式披露与去工具化 (Progressive Disclosure & Minimized Tools)
+**现状痛点**：为了提供强大的功能，在 `tools.md` 或 System Prompt 里塞入海量工具说明与技能细则，导致模型注意力过载或陷入决策瘫痪（Decision Paralysis）。
+**改进策略**：
+1. **多级目录动态按需加载**：确立三级机制：
+   - Level 1 (`CLAUDE.md` / `identity.md`)：只讲最最核心的存活元规则和找资料入口。
+   - Level 2 (`SKILL.md`)：作为外挂组件引擎，只有触发特定领域关键词，引擎才将其注给 Agent `system_prompt`。一旦切走任务则将其卸载（Unload）。
+   - Level 3 (`references`)：基于 RAG 工具被动按需调取日志或全量文件。
+2. **修剪泛洪工具群**：将非必须的复杂组合 API 下架。退守“最强的万能扳手”：赋予 Agent 沙盒受控的终端执行与代码编写权（如受限的 Python 解释器或 `bash`），让 Agent 现写代码去满足需求，而非提供写死上百个微工具集。
+
+### 改进点四：单体自治理的“微小自反思闭环” (Micro Self-Verification)
+**现状痛点**：完全依赖事后外置的角色（如 `QA-Judge` 或者遭遇硬报错再触发反馈），链路长且对中控要求高。
+**改进策略**：
+1. **植入 Local Verify Hook**：规定在下级执行类 Agent 调用 `report_task` 汇报 `status: PASS` 之前，必须调用自身的沙箱测试或执行一次自我反思的 `verify` 工具。
+2. **Autoresearch Error Loop**：为底层 Agent 本地增加 `_lessons.md`（试错经验暂存区）。在执行重试（Retry）循环时，如果不通过，先强制写一条经验记录到 `_lessons.md` 中。下次 retry 带上本条经验执行，避免单次死循环卡点。此级循环不惊动顶层的 Innovator（FDE），实现“兵不烦将”。
+
+### 改进点五：引入算力经济学观测 (Cost & Profiling Observability)
+**现状痛点**：对“系统表现和行为”透明（有 Logs），但对“运营成本”无感知，不符合 Corporate OS（企业组织）要求。
+**改进策略**：
+1. 建立 `logs/billing` 观测维度：在 `pipeline_runs` 和 `audit` 同级，加入 Token 消耗监测系统。
+2. 精确计算每一次交接任务“花费的 API 计价预估”。给 CEO 提供财务数据维度支持，帮助甄别“能力较弱导致长耗时高频失败”的节点，为其发起汰换重构提供商业依据。
+
+---
+
+## 3. 落地 Roadmap (Implementation Roadmap)
+
+| 阶段 | 里程碑 (Milestones) | 涉及模块 (Modules) | 预期时间 |
+|------|----------------|----------------|----------|
+| **Phase 1** | **微观验证引入**：在现有节点中强制引入自我校验 (Local Verify)，以及局部 `_lessons.md`。 | `agent-chat.js`, 基础 `templates/` 补充设定 | P1 优先 |
+| **Phase 2** | **四大元技能装配与重构**：为 Base Agent 植装并切分 `Research/Plan/Execute/Verify` 四大独立技能入口，支持阶段流转中的 Context Flush。 | `memory-service.js`, `boss-meta-capabilities`, `master-session` | P1 优先 |
+| **Phase 3** | **事前阻断流程化**：集成规划节点停摆拦截，接入前端 UI 以获得 Human/Master 的手动 Approved 后才能唤醒下游。 | `schema/goals`, Web UI 组件 | P2 规划 |
+| **Phase 4** | **重置工具与按需挂载**：清理多余的工具并实施 `SKILL.md` 动态路由加载机制，提高上下文利用率甜区表现。 | `skill-registry/service`, 工具池整理 | P2 规划 |
+| **Phase 5** | **经济学审计引入**：Token 数理追踪统计埋点，提供可视化报表支持（Cost Tracker Dashboard）。 | `logger/billing_service` | P3 未来探讨 |
+
+> **最后修订记录:**
+> - 本规划文档由对行业 Harness Engineering 原理和 LemonBoss 特性对比后的工程反思形成，将指导未来一至两个大版本的演进。
@@ -352,6 +352,14 @@ function buildSystemPrompt(agentDir, userMessage) {
     }
     parts.push('---\n\n# 我的核心主技能 (执行准则)\n\n' + mainSkill.trim());
   }
+
+  // ── Phase 1 / Micro-Verify: 当前局部任务的试错经验池 `_lessons.md` ──
+  // 当 Agent 遇到棘手的坑或执行报错时，要求它总结并写入 _lessons.md。
+  // 通过在此处注入，它下次 retry 时便能带着前车之鉴，避免死循环。
+  const localLessons = loadFile(agentDir, 'workspace/_lessons.md');
+  if (localLessons.trim()) {
+    parts.push('---\n\n## ⚠️ 本地试错防坑经验 (_lessons.md)\n不要重复踩下面的坑，仔细阅读并绕开：\n\n' + localLessons.trim());
+  }
   const skills = loadFile(agentDir, '.claude/skills/skills.md');
   if (skills.trim()) parts.push('---\n\n' + skills.trim());
@@ -1287,6 +1295,158 @@ router.post(&#39;/task/report&#39;, (req, res) =&gt; {
 });
 // ═══════════════════════════════════════
+//  POST /api/agent/:agentId/task/transition — 强制流转与记忆断舍离 (Context Flush)
+// ═══════════════════════════════════════
+router.post('/:agentId/task/transition', (req, res) => {
+  try {
+    const { phase, artifact } = req.body;
+    const agentId = req.params.agentId;
+    const agentDir = getAgentDir(agentId);
+    if (!fs.existsSync(agentDir)) return res.status(404).json({ error: 'Agent not found' });
+
+    console.log(`[TaskTransition] 🔄 ${agentId} 正在跨越阶段至: ${phase}`);
+
+    // 1. 查找当前的活动会话 ID
+    let activeConvId = null;
+    let sessionKey = null;
+    for (const [k, v] of sessions.entries()) {
+      if (v.agentId === agentId) {
+        activeConvId = v.convId;
+        sessionKey = k;
+        break;
+      }
+    }
+
+    // 2. Phase 3 核心: 事前阻断阀 (Human-in-the-loop)
+    // 拦截 P0 任务由 plan -> execute 的跳转，强制挂起并申请 Master 审批
+    if (phase === 'execute' && activeConvId && activeConvId.startsWith('task-')) {
+       const taskId = activeConvId.substring(5);
+       const taskMeta = loadTaskMeta(taskId);
+       if (taskMeta && taskMeta.priority === 'P0') {
+           console.log(`[TaskTransition] 🛑 拦截 P0 任务进入 Execute，挂起等待人类审批 (taskId: ${taskId})`);
+
+           // 更新 OKR 节点状态为 pending_approval
+           if (taskMeta.goalId && taskMeta.nodeId) {
+               try {
+                   goalsService.updateNode(taskMeta.goalId, taskMeta.nodeId, { status: 'pending_approval' });
+               } catch (err) {}
+           }
+
+           // 通知 Master 审批
+           setImmediate(() => {
+               const masterMsg = `[⚠️ 事前审批请求]\n你的下属 ${agentId} 已经完成了 P0 级任务 ${taskId} 的规划阶段。\n现在它正准备加载大威力执行权限 (Execute) 落地方案。\n\n请你阅读其产生的 ${artifact || '_plan.md'}，并在确认无误后通过指令手动放行它。`;
+               const http = require('http');
+               const postData = JSON.stringify({ message: masterMsg, conversationId: `approval-${taskId}` });
+               const options = {
+                   hostname: 'localhost', port: 3000,
+                   path: `/api/agent/master/chat`,
+                   method: 'POST',
+                   headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) },
+               };
+               const chatReq = http.request(options, () => {});
+               chatReq.on('error', () => {});
+               chatReq.write(postData);
+               chatReq.end();
+           });
+
+           // 掐断当前进程使其休眠，等待重新唤醒
+           const v = sessions.get(sessionKey);
+           if (v && v.protocol) v.protocol.disconnect();
+           sessions.delete(sessionKey);
+
+           return res.json({ success: true, message: '已拦截。该任务为 P0 级别，必须等待 Master 审批放行后才能进入执行环节！' });
+       }
+    }
+
+    // 若未被阻断，更新 OKR 为进行中子状态 (如 researching, executing等)
+    if (activeConvId && activeConvId.startsWith('task-')) {
+       const taskId = activeConvId.substring(5);
+       const taskMeta = loadTaskMeta(taskId);
+       if (taskMeta && taskMeta.goalId && taskMeta.nodeId) {
+           try {
+               const subStatus = phase === 'research' ? 'researching' : phase === 'plan' ? 'planning' : phase === 'execute' ? 'executing' : phase === 'verify' ? 'verifying' : 'in_progress';
+               goalsService.updateNode(taskMeta.goalId, taskMeta.nodeId, { status: subStatus });
+           } catch (err) {}
+       }
+    }
+
+    // 3. Hot Swap 动态换脑: 把 main_skill 替换为 meta-* 技能
+    const sourceSkill = path.resolve(__dirname, `../../data/system/skills/meta-${phase}/SKILL.md`);
+    const targetSkill = path.join(agentDir, '.claude', 'skills', 'main_skill', 'SKILL.md');
+    if (fs.existsSync(sourceSkill)) {
+      if (!fs.existsSync(path.dirname(targetSkill))) fs.mkdirSync(path.dirname(targetSkill), { recursive: true });
+      fs.copyFileSync(sourceSkill, targetSkill);
+      console.log(`[TaskTransition] 🧠 ${agentId} 动态技能树已切换为 meta-${phase}`);
+    }
+
+    // 4. Context Flush 记忆断舍离: 掐断当前运行中的 ACP 进程，清空历史消息
+    if (sessionKey) {
+      const v = sessions.get(sessionKey);
+      if (v && v.protocol) v.protocol.disconnect();
+      sessions.delete(sessionKey);
+    }
+
+    if (activeConvId) {
+      const dir = getConvDir(agentId, activeConvId);
+      // 清空长周期的幻觉来源
+      fs.writeFileSync(path.join(dir, 'history.json'), '[]', 'utf-8');
+      logMessageChunk(agentId, activeConvId, `\n\n[SYSTEM] 🛑 Context Flush 触发！记忆已断开，阶段切换至 ${phase}\n\n`);
+
+      // 3. 构建起步上下文: 告诉 Agent 它的前序成就
+      let artifactContent = '';
+      if (artifact) {
+         // artifact 可能带有 'workspace/' 前缀，尝试解析
+         const possiblePaths = [
+           path.join(agentDir, artifact),
+           path.join(agentDir, path.basename(artifact)),
+           path.join(agentDir, 'workspace', path.basename(artifact))
+         ];
+         for (const p of possiblePaths) {
+           if (fs.existsSync(p)) {
+             artifactContent = fs.readFileSync(p, 'utf-8');
+             break;
+           }
+         }
+      }
+
+      const flushMsg = `【系统指令：强制状态切换】
+你的生命周期已成功切入新阶段：**${phase.toUpperCase()}**。
+你之前的对话记忆已被完全抹除防范幻觉，你的系统技能已获得 ${phase} 的授权限制。
+
+${artifactContent ? `这是上一阶段你或你的前置节点留下的交付物（Artifact），你必须严格参照此文件行动，不再另行发散：\n\n\`\`\`\n${artifactContent}\n\`\`\`` : ''}
+
+请开始你的新阶段工作！`;
+
+      // 写入一条用户指令开启新的清爽对话
+      appendHistory(agentId, activeConvId, {
+        role: 'user', content: flushMsg, messageId: `msg-${Date.now()}-flush`, timestamp: new Date().toISOString()
+      });
+
+      // 4. 发送唤醒指令让他立刻基于新脑子行动
+      setImmediate(() => {
+        const http = require('http');
+        const postData = JSON.stringify({ message: "请确认你已收到系统的新阶段挂载指令，并立即执行你当前阶段本分的任务！", conversationId: activeConvId });
+        const options = {
+          hostname: 'localhost', port: 3000,
+          path: `/api/agent/${agentId}/chat`,
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) },
+        };
+        const chatReq = http.request(options, () => {});
+        chatReq.on('error', () => {});
+        chatReq.write(postData);
+        chatReq.end();
+      });
+    }
+
+    res.json({ success: true, message: `已成功进行 Context Flush 并切换至 ${phase} 阶段` });
+  } catch (err) {
+    console.error('[TaskTransition] Error:', err.message);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ═══════════════════════════════════════
 //  POST /api/agent/task/reject — COO 质量门控：驳回任务
 // ═══════════════════════════════════════
@@ -1534,6 +1694,13 @@ router.post(&#39;/:agentId/chat&#39;, async (req, res) =&gt; {
         } else if (event.method === 'session/result') {
           if (event.params?.cost_usd) {
             sendSSE('session_cost', { cost: event.params.cost_usd, duration: event.params.duration_ms });
+            // Phase 5: Economic Audit - 记录账单 (Token Profiling)
+            try {
+              const billingDir = path.resolve(__dirname, '../../data/logs');
+              if (!fs.existsSync(billingDir)) fs.mkdirSync(billingDir, { recursive: true });
+              const billingEntry = `${new Date().toISOString()} | Agent: ${agentId} | Conv: ${convId} | Cost: $${event.params.cost_usd.toFixed(6)} | Duration: ${event.params.duration_ms}ms\n`;
+              fs.appendFileSync(path.join(billingDir, 'billing.log'), billingEntry, 'utf-8');
+            } catch (err) {}
           }
           if (!fullOutput && event.params?.result) {
             fullOutput = event.params.result;
@@ -319,7 +319,7 @@ class GoalsService {
       let nodesText = '';
       for (const [nodeId, node] of Object.entries(goal.nodes)) {
-        if (node.owner === agentId && (node.status === 'in_progress' || node.status === 'pending')) {
+        if (node.owner === agentId && node.status !== 'done' && node.status !== 'failed') {
           if (!hasActiveNodes) {
              const progress = this._calcProgress(goal);
              combinedText += `\n\n## 🎯 当前参与的目标\n\n`;
@@ -385,7 +385,8 @@ class GoalsService {
     const total = leafIds.length;
     const done = leafIds.filter(id => nodes[id].status === 'done').length;
-    const inProgress = leafIds.filter(id => nodes[id].status === 'in_progress').length;
+    const inProgressStates = ['in_progress', 'researching', 'planning', 'executing', 'verifying', 'pending_approval'];
+    const inProgress = leafIds.filter(id => inProgressStates.includes(nodes[id].status)).length;
     const pending = total - done - inProgress;
     // 按 owner 分组