zen-gitsync 2.17.24 → 2.17.26

package/src/ui/server/routes/workbench/memoryContext.js

@@ -0,0 +1,125 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 派发任务时注入给 Agent 的「记忆指针块」—— 让被派出去的 agent 知道
+// 本机有一份跨会话经验库、以及**怎么按预算的方式去读它**。
+//
+// ── 与 envContext 的关系（同一个位置，两件事）────────────────────────
+// envContext.js 讲的是"这台机器此刻的现场"（项目清单 / 看板 / 真相源路径），
+// 快照语义、每次都变；这里讲的是"这个仓库踩过的坑"，长期累积、很少变。
+// 两者都在 taskRunner.js 拼 prompt 时前置，注入失败都不该挡住任务执行。
+//
+// ── 为什么用"指针"而不是把索引内容塞进 prompt ───────────────────────
+// 把 INDEX.md 全文塞进 prompt 是最省事也最糟的做法：索引会随记忆增长线性膨胀，
+// 而**每次派发都要为每一条不相关的历史经验付 token**。塞路径 + 塞纪律（各 5~8 行），
+// 剩下的交给 Agent 自己的 read 工具按需取 —— 这正是"索引式摘要"这个需求的核心。
+//
+// ⚠️ 文案可以硬编码中文（与 envContext.js 同一口径）：这里是喂给模型的 prompt
+// 内容，不经过前端 $t()、不显示在界面上，也不该跟着界面语言变。
+//
+// 纯函数：只吃入参、不读文件、不做 IO。这样单测不用碰真实用户数据 ——
+// 与 envContext.js / promptParts.js 同一个理由。取数在 store.js。
+
+/** 指针块自身的体积上限（字节）。超了就是文案写飘了，Agent 读它比查索引还贵。 */
+export const MEMORY_BLOCK_MAX_BYTES = 2048;
+
+/** 状态标签：给 UI / 日志判断"这次注入了几层信息"，不参与 prompt 语义 */
+export const MEMORY_BLOCK_LEVEL = {
+  /** 记忆库不可用（目录不存在且铺种子失败）—— 完全不注入 */
+  NONE: 'none',
+  /** 库在，但没有本项目目录 —— 只给全局路径 */
+  GLOBAL_ONLY: 'global-only',
+  /** 库在且本项目目录在 —— 给全局 + 本项目两个路径 */
+  PROJECT: 'project',
+};
+
+/**
+ * 拼记忆指针块。
+ *
+ * @param {object}   input
+ * @param {string}   input.memoryDir  记忆库根目录（~/<pkg>/memory 的绝对路径）
+ * @param {string}   [input.projectIndexFile] 本项目索引绝对路径；空/不存在 → 只给全局那层
+ * @param {boolean}  [input.capture=true] 是否附上"收尾时怎么记"那一段。
+ *                    续聊轮可以关掉（同一场对话里第二、三轮再讲一遍捕获纪律是噪音）。
+ * @param {string}   [input.locale] 暂未使用；预留让文案随界面语言走（中文硬编码是
+ *                    当前口径，见文件头注释）
+ * @returns {{ block: string, level: string }} block 为 '' 表示不注入
+ */
+export function buildMemoryPointerBlock(input = {}) {
+  const {
+    memoryDir = '',
+    projectIndexFile = '',
+    capture = true,
+  } = input;
+
+  if (!memoryDir) return { block: '', level: MEMORY_BLOCK_LEVEL.NONE };
+
+  const lines = [
+    '## 跨会话记忆库（本机）',
+    '',
+    `本机有一份长期经验库，是**之前在这个仓库干活的 agent 留下的坑**。开工前先查，别重复踩：`,
+    '',
+    `- 全局索引：\`${memoryDir}/INDEX.md\`（项目清单 + 通用坑主题词）`,
+  ];
+
+  let level = MEMORY_BLOCK_LEVEL.GLOBAL_ONLY;
+  if (projectIndexFile) {
+    lines.push(`- **本项目索引：\`${projectIndexFile}\`** ← 先读这个`);
+    level = MEMORY_BLOCK_LEVEL.PROJECT;
+  } else {
+    lines.push('- 本项目还没有记忆库条目（首次在本仓库干活时会被自动建好）');
+  }
+
+  lines.push(
+    '',
+    '**怎么读（别烧 token）**：',
+    '',
+    '1. 用 read 工具读上面那个索引；',
+    '2. 索引里某条的关键词和当前任务**真正相关**时，才去读它指向的 `lessons/<topic>.md`；',
+    '3. 没命中就别读。**不要预加载全部 lessons，也不要读 `archive/`** —— ',
+    '   索引是给你做取舍的，不是让你通读的。',
+  );
+
+  if (capture) {
+    lines.push(
+      '',
+      '**收尾时（做完了、准备回复之前）自检一次**，四条里任意一条为"是"就记一条：',
+      '',
+      '1. 本轮卡住 ≥3 分钟，或走了 A→放弃→B→放弃→C 的反复路径；',
+      '2. 用错了工具 / 写错了文件 / grep 命中被构建产物淹没 / 探针假绿；',
+      '3. 用户纠正了你的方向、用法或命名；',
+      '4. 发现"看似绕路但更快"或"反直觉但正确"、且被验证有效的做法。',
+      '',
+      '记的时候：',
+      '',
+      '- 写"**以后怎么做**"，不写"我做了什么"（后者是 commit message 的活）；',
+      '- 单条 ≤25 行，形状 ` lessons/<topic>.md`：`# 一句话讲清坑是什么` / 现象根因 / `**How to apply:**`；',
+      '- 同主题**追加/改写已有文件**，不要新建近似重复的（先 read 一眼）；',
+      '- 跨仓库都成立 → 写 `${memoryDir}/GLOBAL.md`；只跟本仓库有关 → 写本项目 `lessons/`；',
+      `- 写完**必须在对应 INDEX.md 补一行** \`- [标题](lessons/<file>.md) — ≤100 字摘要\`。**没索引的记忆等于不存在。**`,
+      '- 四条全否 → 一条都别写。不要为沉淀而沉淀。',
+    );
+  }
+
+  let block = lines.join('\n');
+
+  // 文案哪天写飘了也不许把 prompt 撑大：超预算就砍掉捕获段（最长的可省部分），
+  // 召回指针本身必须留着 —— 那是这个块存在的全部理由。
+  if (Buffer.byteLength(block, 'utf8') > MEMORY_BLOCK_MAX_BYTES && capture) {
+    lines.length = lines.findIndex((l) => l.includes('收尾时'));
+    block = lines.join('\n').trimEnd();
+  }
+
+  return { block, level };
+}

package/src/ui/server/routes/workbench/memoryContext.test.js

@@ -0,0 +1,79 @@
+// memoryContext.js 的单测。
+//
+// 纯函数、不碰文件系统（见该文件头注释），所以直接喂入参断输出即可 ——
+// 与 envContext.test.js 同一个理由，也正是它要保持纯的原因。
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildMemoryPointerBlock,
+  MEMORY_BLOCK_MAX_BYTES,
+  MEMORY_BLOCK_LEVEL,
+} from './memoryContext.js';
+
+const DIR = '/home/u/.zen-gitsync/memory';
+const PIDX = `${DIR}/projects/my-repo/INDEX.md`;
+
+test('没有 memoryDir → 完全不注入', () => {
+  const { block, level } = buildMemoryPointerBlock({});
+  assert.equal(block, '');
+  assert.equal(level, MEMORY_BLOCK_LEVEL.NONE);
+});
+
+test('只有全局层：给全局索引路径，明说本项目还没有条目', () => {
+  const { block, level } = buildMemoryPointerBlock({ memoryDir: DIR });
+  assert.equal(level, MEMORY_BLOCK_LEVEL.GLOBAL_ONLY);
+  assert.ok(block.includes(`${DIR}/INDEX.md`));
+  assert.ok(block.includes('本项目还没有记忆库条目'));
+  // 捕获段里仍会出现 lessons/ —— Agent 收尾时要知道往哪儿写；
+  // 这里断言的是**不出现项目索引路径**（没有的路径给了就是骗 Agent）。
+  assert.ok(!block.includes(`${DIR}/projects/`));
+  assert.ok(!block.includes('本项目索引'));
+});
+
+test('有项目层：标为 PROJECT 并点名本项目索引', () => {
+  const { block, level } = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX });
+  assert.equal(level, MEMORY_BLOCK_LEVEL.PROJECT);
+  assert.ok(block.includes(PIDX));
+  assert.ok(!block.includes('本项目还没有记忆库条目'));
+});
+
+test('capture=false → 保留召回纪律、砍掉捕获纪律', () => {
+  const withCap = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX, capture: true });
+  const noCap = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX, capture: false });
+  assert.ok(withCap.block.includes('收尾时'));
+  assert.ok(!noCap.block.includes('收尾时'));
+  // 砍的只是长的那段，召回指针必须还在 —— 那才是这个块存在的理由
+  assert.ok(noCap.block.includes(PIDX));
+  assert.ok(noCap.block.length > 0);
+  assert.ok(Buffer.byteLength(noCap.block, 'utf8') < Buffer.byteLength(withCap.block, 'utf8'));
+});
+
+test('块本身不能超预算（这是它替代"索引全文进 prompt"的前提）', () => {
+  const { block } = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX });
+  assert.ok(
+    Buffer.byteLength(block, 'utf8') <= MEMORY_BLOCK_MAX_BYTES,
+    `块 ${Buffer.byteLength(block, 'utf8')}B 超过 ${MEMORY_BLOCK_MAX_BYTES}B 预算`
+  );
+});
+
+test('超预算时降级：砍捕获段、保住召回指针（不静默产出超大 prompt）', () => {
+  const { block } = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX, capture: true });
+  const recallAt = block.indexOf('不要预加载全部 lessons');
+  const captureAt = block.indexOf('收尾时');
+  assert.ok(recallAt > 0, '召回纪律必须在');
+  assert.ok(captureAt > recallAt, '捕获纪律必须排在召回纪律之后');
+});
+
+test('纪律里必须写死两条硬约束：懒加载 + 索引缺一不可', () => {
+  const { block } = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX });
+  assert.match(block, /不要预加载全部 lessons/);
+  assert.match(block, /archive/);
+  assert.match(block, /没索引的记忆等于不存在/);
+  assert.match(block, /以后怎么做/);
+});
+
+test('续接场景（capture 由调用方关掉）不产生空块', () => {
+  const { block } = buildMemoryPointerBlock({ memoryDir: DIR, projectIndexFile: PIDX, capture: false });
+  assert.ok(block.trim().length > 0);
+  assert.ok(block.includes(PIDX), '关掉捕获纪律不能把召回指针一起关掉');
+});

package/src/ui/server/routes/workbench/orchestratorPrompt.test.js

@@ -24,8 +24,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
-import { resolveDispatchPrompt, normalizeOrchestrator } from './orchestratorStore.js';
-import { MAX_DEFAULT_PROMPT_CHARS } from './shared.js';
+import { resolveDispatchPrompt, normalizeOrchestrator, withInstructionPreview } from './orchestratorStore.js';
+import { MAX_DEFAULT_PROMPT_CHARS, INSTRUCTION_PREVIEW_CHARS } from './shared.js';
 
 /** 造一份最小可用的编排状态（字段与 normalizeOrchestrator 的输出对齐） */
 function stateWith({ defaultPrompt = '', projectPrompts = {} } = {}) {
@@ -157,3 +157,48 @@ test('normalizeOrchestrator：指令的 promptSource 只认白名单，脏值归
   });
   assert.deepEqual(s.instructions.map(i => i.promptSource), ['both', 'global', '', '']);
 });
+
+// ── 指令流水的「下发预览」截断（2026-09-29）────────────────────────────
+//
+// 指令上限从 4000 放宽到 100000 之后，唯一会先崩的是**5s 轮询**：
+// /api/workbench/orchestrator 每轮下发 state.instructions 整份（200 条上限），
+// 不截就是 200 × 100000 = 20MB 一轮。
+//
+// 关键在"截哪一份"：落盘那份（orchestrator.json）与任务正文（task.desc）必须完整 ——
+// 指令流水的意义就是"我说过什么"能被翻到，而 Agent 侧的真相源清单指着那个文件。
+// 所以这里守的是"只截下发、且如实标出被截过"。
+
+test('withInstructionPreview：超长正文截到预览上限并标出已截断', () => {
+  const long = 'x'.repeat(INSTRUCTION_PREVIEW_CHARS + 500);
+  const r = withInstructionPreview({ id: 'a', text: long, status: 'accepted' });
+  assert.equal(r.text.length, INSTRUCTION_PREVIEW_CHARS);
+  assert.equal(r.textTruncated, true);
+  // 其余字段一个都不能丢：前端要靠 status / projectPath / targetSource 渲染这行
+  assert.equal(r.id, 'a');
+  assert.equal(r.status, 'accepted');
+});
+
+test('withInstructionPreview：没超长时原样返回，且不误标截断', () => {
+  const short = '一句话指令';
+  const r = withInstructionPreview({ id: 'a', text: short });
+  assert.equal(r.text, short);
+  assert.equal(r.textTruncated, false);
+  // 恰好等于上限不算超（截断口是 >）
+  const atLimit = withInstructionPreview({ id: 'b', text: 'y'.repeat(INSTRUCTION_PREVIEW_CHARS) });
+  assert.equal(atLimit.textTruncated, false);
+  assert.equal(atLimit.text.length, INSTRUCTION_PREVIEW_CHARS);
+});
+
+test('withInstructionPreview：不改传入的记录（落盘那份必须还是完整的）', () => {
+  const long = 'z'.repeat(INSTRUCTION_PREVIEW_CHARS + 10);
+  const original = { id: 'a', text: long };
+  withInstructionPreview(original);
+  assert.equal(original.text.length, INSTRUCTION_PREVIEW_CHARS + 10, '截断只发生在返回的新对象上');
+});
+
+test('withInstructionPreview：脏输入不炸（缺 text / null / 非对象）', () => {
+  assert.deepEqual(withInstructionPreview({ id: 'a' }), { id: 'a', text: '', textTruncated: false });
+  assert.equal(withInstructionPreview(null).text, '');
+  assert.equal(withInstructionPreview(undefined).text, '');
+  assert.equal(withInstructionPreview({ text: 123 }).text, '');
+});

package/src/ui/server/routes/workbench/orchestratorStore.js

@@ -39,6 +39,7 @@ import {
   ORCHESTRATOR_REPORTS_FILE,
   MAX_ORCHESTRATOR_INSTRUCTIONS,
   MAX_DEFAULT_PROMPT_CHARS,
+  INSTRUCTION_PREVIEW_CHARS,
   MAX_PROGRESS_REPORTS,
   PROGRESS_REPORT_INTERVALS_MS,
   DEFAULT_PROGRESS_REPORT_INTERVAL_MS,
@@ -245,6 +246,27 @@ export function resolveDispatchPrompt(state, projectPath) {
   return { text, source };
 }
 
+/**
+ * 把一条指令流水压成「可以每 5 秒下发」的形状：正文只留开头 INSTRUCTION_PREVIEW_CHARS 字。
+ *
+ * 为什么需要它：指令正文上限已放宽到十万字（MAX_INSTRUCTION_CHARS），而
+ * /api/workbench/orchestrator 是 5s 轮询、下发 state.instructions 整份（200 条）。
+ * 不截就是 200 × 100000 = 20MB 一轮。
+ *
+ * 只压**下发**：落盘那份（orchestrator.json）与任务正文（task.desc）都保持完整，
+ * 指令流水的意义就是"我说过什么"能被翻到。附 textTruncated 让前端能如实说"已截断"，
+ * 而不是让用户以为当初就只写了这么多。
+ *
+ * @param {object} it orchestratorStore 的指令记录
+ * @returns {object} 新对象（不改原记录 —— 落盘那份必须还是完整的）
+ */
+export function withInstructionPreview(it) {
+  const src = it && typeof it === 'object' ? it : {};
+  const text = typeof src.text === 'string' ? src.text : '';
+  const truncated = text.length > INSTRUCTION_PREVIEW_CHARS;
+  return { ...src, text: truncated ? text.slice(0, INSTRUCTION_PREVIEW_CHARS) : text, textTruncated: truncated };
+}
+
 /** 追加一条人类干预指令记录，返回写入后的那条记录 */
 export async function appendInstruction(entry) {
   return serialize(async () => {
@@ -508,12 +530,18 @@ export function buildActivityFeed({ jobs = [], tasks = [], instructions = [] } =
 
   for (const it of Array.isArray(instructions) ? instructions : []) {
     if (!it || !it.id) continue;
+    // 正文只带**开头一段**进活动流：这条流跟着 5s 轮询下发（截断口径见
+    // withInstructionPreview）。落盘那份不截 —— 完整原文在 orchestrator.json 与
+    // task.desc 里，要全文的人去那两个地方拿。
+    const preview = withInstructionPreview(it);
     rows.push({
       id: `ins:${it.id}`,
       kind: 'user',
       at: it.at,
       instructionId: it.id,
-      text: it.text || '',
+      text: preview.text,
+      // 前端据此显示"已截断"，而不是让人以为指令本来就那么短
+      textTruncated: preview.textTruncated,
       taskId: it.taskId || null,
       instructionStatus: it.status || 'created',
       reason: it.reason || '',

package/src/ui/server/routes/workbench/runExternalTurn.js

@@ -40,6 +40,7 @@
 import { spawn, execFile } from 'child_process';
 import { logger } from './shared.js';
 import { engineLabel } from './agentEngines.js';
+import { isPlanToolName } from '../../../../cli/ai/tools.js';
 import {
   createToolCallTracker,
   createClaudeEventHandler,
@@ -181,7 +182,11 @@ export async function runExternalTurn({
       const id = u.id || '';
       if (id && !announced.has(id)) {
         announced.add(id);
-        send({ type: 'tool_call_start', toolCallId: id, name: u.name, argsPreview: u.argsPreview || '' });
+        // 计划类工具额外带完整参数：外部引擎里 claude 的 TodoWrite / opencode 的
+        // todowrite 就是计划，前端要靠原始 steps 渲染清单，而 argsPreview 是摘要。
+        // 只给计划类发全文，与内置 g ai 那条链路（agentChat.js）保持同一口径。
+        const planArgs = isPlanToolName(u.name) ? (u.arguments || '') : undefined;
+        send({ type: 'tool_call_start', toolCallId: id, name: u.name, argsPreview: u.argsPreview || '', arguments: planArgs });
       }
       if (u.status !== 'running') {
         send({

package/src/ui/server/routes/workbench/shared.js

@@ -102,6 +102,31 @@ export const TRUTH_FILES = {
 // 就不会出现"派发时写进去了、回头在编辑器里一保存又被悄悄截掉"。
 export const MAX_DEFAULT_PROMPT_CHARS = 4000;
 
+// 派发指令正文长度上限。
+//
+// 2026-09-29 从 4000 放宽到 100000：执行侧走的是 claude / opencode / codex，
+// 上下文窗口早已是百万级，而 prompt 是**经 stdin 喂进去**的（见 taskRunner 的
+// launchXxxRun），不受 Windows 命令行 32K 上限约束。4000 是模型上下文还小的时候
+// 定的，现在它卡住的不是模型，是"粘一份完整报错日志 / 一整段需求"这种最普通的用法。
+//
+// 十万字不是"随便多大都行"，它同时要落在三份存储里（见下方各自的注释）：
+//   · tasks.json 的 task.desc —— 一次执行真正用的正文
+//   · jobs.json 的 job.prompt —— 保留策略 500 条 / 256MB 兜底
+//   · orchestrator.json 的指令流水 —— 200 条上限
+// 真正会让界面卡住的不是这三份，而是**轮询下发**（INSTRUCTION_PREVIEW_CHARS 那道口子）。
+export const MAX_INSTRUCTION_CHARS = 100000;
+
+// 指令流水进 5s 轮询 / 活动流时的正文上限。
+//
+// 为什么单独一道：/api/workbench/orchestrator 每 5 秒把 state.instructions 与活动流
+// 整份下发（MAX_ORCHESTRATOR_INSTRUCTIONS = 200 条）。指令放宽到十万字之后，
+// 不截就是 200 × 100000 = 20MB 一轮 —— 界面先卡住，而"卡住"和"上限"毫无关系。
+//
+// 只截**下发**这一份，不截落盘：流水存在的意义就是"我说过什么"能被翻到，
+// 落盘那份必须完整（Agent 侧的真相源清单也指着 orchestrator.json）。
+// 任务正文本身更不截 —— 完整正文在 task.desc 里，流水这条只是同一句话的旁证。
+export const INSTRUCTION_PREVIEW_CHARS = 2000;
+
 // 子项目识别 / 文件扫描时需要跳过的目录
 export const SKIP_DIRS = new Set([
   'node_modules', 'dist', 'build', '.next', '.nuxt', '__pycache__',
@@ -117,12 +142,13 @@ export const MANIFEST_FILES = [
   'Gemfile', 'pubspec.yaml'
 ];
 
-// 附件大小 / 数量限制
+// 附件大小限制（**数量不限**）
 // 单文件 20MB：4K 屏截图（PNG）5–15MB 是常态，卡在 5MB 会让"随手截一张就超"。
 // 真正需要小体积的是图片，由前端上传前压缩保证（见 useWorkbenchAttachments.ts），
 // 这里只做最后一道兜底，避免超大 body 把内存吃光。
+// 数量曾经按 9 个封顶，2026-09-29 按需求放开：一次要交十几张截图 / 一堆日志是常态，
+// 封顶只会逼人分批建任务。数量放开后单文件上限成了唯一的内存关口，所以它必须留着。
 export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;       // 单个附件最大 20MB
-export const MAX_ATTACHMENTS_PER_TASK = 9;             // 一个任务最多挂 9 个附件
 
 // ── 时间 / ID 工具 ─────────────────────────────────────────
 export function nowIso() {

package/src/ui/server/routes/workbench/taskRunner.js

@@ -45,6 +45,7 @@ import {
 } from './shared.js';
 import { buildAttachmentBlock } from './pdfText.js';
 import { composePromptBody } from './promptParts.js';
+import { buildMemoryPointerBlock } from './memoryContext.js';
 import {
   jobs,
   cancelledJobs,
@@ -52,6 +53,11 @@ import {
   flushJobsSaveNow,
   scheduleActiveJobsSave,
 } from './jobStore.js';
+// MEMORY_DIR 在 paths.js（路径唯一真相源），projectIndexFile 在 memory/store.js ——
+// 两个模块各取一处，别图省事都从 store.js 拿：store.js 没有 re-export MEMORY_DIR，
+// 混着写会在**链接期**就炸（node --check 查不出来，得靠动态 import 或真跑单测）。
+import { MEMORY_DIR } from '../../../../paths.js';
+import { projectIndexFile } from '../../../../memory/store.js';
 
 // ── 运行环境上下文的提供者 ────────────────────────────────────────────────
 // 为什么用注入而不是在这里直接读：拼这份上下文要「最近目录」（在 configManager 上），
@@ -86,6 +92,23 @@ async function resolveEnvContext(repoPath) {
   }
 }
 
+/**
+ * 取本仓库的记忆索引路径。
+ *
+ * **只读不建** —— 与 resolveEnvContext 同一原则：拼 prompt 是锦上添花，
+ * 记忆库不存在就只给全局那层，让 Agent 收尾时自己建（它有文件工具，也有那个动机）。
+ * 在这里建目录等于"读一次就产生一次副作用"，派发任务不该有这种语义。
+ */
+function resolveProjectMemoryIndex(repoPath) {
+  if (!repoPath) return '';
+  try {
+    return projectIndexFile(repoPath);
+  } catch (err) {
+    logger.warn(`[workbench] 记忆索引路径解析失败，本次不注入项目层: ${err.message}`);
+    return '';
+  }
+}
+
 // 用 detached 进程跑 claude；进程退出时回填状态。
 // 返回 { pid, child }：调用方可以监听 child.stdout/stderr 实时收集输出。
 // 不再走 cmd /k 弹窗——claude -p 是非交互模式，输出通过 stdout pipe 实时回传
@@ -885,13 +908,33 @@ export async function runSingleSubtask(task, sub, repoPath, branch, options) {
     }
   }
 
-  // ── 运行环境上下文：项目清单 + 看板概览 + 真相源文件路径 ──
-  // 拼在**最前面**、任务正文压尾：
-  // 越靠后离模型的注意力中心越近，用户真正要办的那句话必须在最后一屏。
-  // task.envContext === false 可以单任务关掉（默认开 —— 老任务不迁移也一并受益）。
+  // ── 两块「背景」都拼在最前面，任务正文压尾 ──
+  // 顺序刻意是 [环境上下文 → 记忆指针 → 任务正文]：
+  //   · 越靠后离模型的注意力中心越近，**用户真正要办的那句话必须在最后一屏**；
+  //   · 记忆块夹在两块之间，不能放末尾 —— 放末尾等于把"背景"讲成了"当前任务"，
+  //     Agent 会以为这轮用户要求它去整理记忆库。
+  // 两块都可用 `task.<key> === false` 单任务关掉（默认开 —— 老任务不迁移也一并受益）。
+  const prefixBlocks = [];
+
   if (task.envContext !== false) {
     const envBlock = await resolveEnvContext(repoPath);
-    if (envBlock) prompt = `${envBlock}\n\n---\n\n${prompt}`;
+    if (envBlock) prefixBlocks.push(envBlock);
+  }
+
+  if (task.memoryContext !== false) {
+    const memBlock = buildMemoryPointerBlock({
+      memoryDir: MEMORY_DIR,
+      // 首次在某仓库干活时目录还不存在 —— 这时不给项目路径，块里会明说
+      // "本项目还没有条目"，Agent 收尾时自己建。
+      projectIndexFile: resolveProjectMemoryIndex(repoPath),
+      // 续聊轮不再重复讲捕获纪律：同一场对话里讲第二遍纯属噪音。
+      capture: !resumeSessionId,
+    }).block;
+    if (memBlock) prefixBlocks.push(memBlock);
+  }
+
+  if (prefixBlocks.length > 0) {
+    prompt = `${prefixBlocks.join('\n\n---\n\n')}\n\n---\n\n${prompt}`;
   }
 
   const jobId = genId();

package/src/utils/selfUpdatePolicy.js

@@ -105,19 +105,41 @@ export function nextPollIntervalMs({ elapsedMs, fastWindowMs, fastIntervalMs, sl
  * 与"EPERM(文件被占)"分不清 —— 两者的处理方式完全相反(一个只能等,一个要杀实例)。
  * 汇总成 `E404 ×8 / ETARGET ×2` 这样一行,下一次事故就不用再靠猜。
  *
+ * v2.17.25 实测教训(优先级为什么长这样):registry 还没就绪(E404)的每一轮
+ * 输出里都附带 `npm warn cleanup Failed to remove ... EPERM` —— 那是 npm 删旧
+ * 全局目录没删干净的动作噪声,不是失败根因。按旧的"EPERM 子串优先"判法被
+ * 误判成文件占用,导致每轮反复停实例 + 强删全局目录。所以:
+ *   ① npm 自己报了 `npm error code <CODE>` 行 → 以它为最终裁决;
+ *   ② 没有 code 行 → 只在 **error 行**里找文件占用类(warn 行永远不算);
+ *   ③ 还没有 → 才对全文兜底(兼容只截到 warn cleanup 的残缺输出)。
+ *
  * @param {string} output - npm install 的 stdout+stderr
- * @returns {string} E404 | ETARGET | EPERM | EBUSY | ENOTFOUND | ETIMEDOUT | ENETUNREACH | '其他'
+ * @returns {string} E404 | ETARGET | EPERM | ENOTFOUND | ETIMEDOUT | ENETUNREACH | 其他 | npm 原生未识别短码
  */
 export function classifyInstallError(output) {
   const s = String(output || '')
   if (!s) return '其他'
-  // 顺序有讲究:E404 / ETARGET 是"registry 还没就绪",EPERM / EBUSY 是"文件被占",
-  // 两类混在一起时优先报前者(它是自更新这一段的主题),但两者都会各自计数。
-  if (/EPERM|EBUSY|operation not permitted|Failed to remove/i.test(s)) return 'EPERM'
+  // ① npm 的裁决码行,如 `npm error code E404`
+  const codeLine = s.match(/^\s*npm (?:error|ERR!) code ([A-Z0-9_]+)\b/m)
+  if (codeLine) return normalizeErrCode(codeLine[1])
+  // ② error 行里的文件占用类(warn 行不算 —— 那是清理噪声)
+  const errorLines = s.split(/\r?\n/).filter((l) => /^\s*npm (?:error|ERR!)/.test(l))
+  if (errorLines.some((l) => /EPERM|EBUSY|operation not permitted|Failed to remove/i.test(l))) return 'EPERM'
+  // ③ 全文兜底:registry 类优先(它是自更新这一段的主题),文件占用类殿后
   if (/\bETARGET\b/.test(s)) return 'ETARGET'
   if (/\bE404\b|404 Not Found/i.test(s)) return 'E404'
   if (/\bENOTFOUND\b/.test(s)) return 'ENOTFOUND'
   if (/\bETIMEDOUT\b|timed out/i.test(s)) return 'ETIMEDOUT'
   if (/\bENETUNREACH\b|ECONNRESET|ECONNREFUSED/i.test(s)) return 'ENETUNREACH'
+  if (/EPERM|EBUSY|operation not permitted|Failed to remove/i.test(s)) return 'EPERM'
   return '其他'
 }
+
+// npm 原生错误码 → 本脚本的对账短码。EBUSY 与 EPERM 同属"文件被占"一类
+// (处置完全相同:杀实例 + 清目录),合并进同一个桶方便 errorTally 汇总;
+// 没见过的码原样返回,别硬塞 —— 归错桶比归不出来更误导。
+function normalizeErrCode(code) {
+  if (code === 'EBUSY') return 'EPERM'
+  if (code === 'ECONNRESET' || code === 'ECONNREFUSED') return 'ENETUNREACH'
+  return code
+}

package/src/utils/selfUpdatePolicy.test.js

@@ -189,6 +189,24 @@ test('classifyInstallError: EPERM / EBUSY → 文件被占(和"还没就绪"完
   assert.equal(classifyInstallError('npm error EBUSY: resource busy or locked'), 'EPERM')
 })
 
+test('classifyInstallError: npm 的 code 行是最终裁决(v2.17.25 实测回归)', () => {
+  // v2.17.25 真实形态:registry 还没就绪(E404)的每一轮都附带 npm warn cleanup EPERM
+  // (删旧全局目录的噪声)。旧判法按"EPERM 子串优先"误判成文件占用,
+  // 导致每轮反复停实例 + 强删全局目录。有 code 行时必须以它为准。
+  const notReady = [
+    'npm warn cleanup Failed to remove some directories: EPERM',
+    'npm error code E404',
+    'npm error 404 Not Found - GET https://registry.npmjs.org/zen-gitsync/-/zen-gitsync-2.17.25.tgz - Not found',
+  ].join('\n')
+  assert.equal(classifyInstallError(notReady), 'E404')
+  // npm 自己裁决成文件占用 → 才允许走"杀实例 + 清目录"
+  assert.equal(classifyInstallError('npm error code EPERM\nnpm error rename EPERM: operation not permitted'), 'EPERM')
+  // EBUSY 与 EPERM 同属"文件被占",归进同一个桶
+  assert.equal(classifyInstallError('npm error code EBUSY\nnpm error resource busy or locked'), 'EPERM')
+  // 没见过的码原样返回,不硬塞进既有短码
+  assert.equal(classifyInstallError('npm error code EAI_AGAIN\nnpm error getaddrinfo EAI_AGAIN'), 'EAI_AGAIN')
+})
+
 test('classifyInstallError: 网络类与空输入不炸,各有短码', () => {
   assert.equal(classifyInstallError('npm error code ENOTFOUND registry.npmjs.org'), 'ENOTFOUND')
   assert.equal(classifyInstallError('npm error code ETIMEDOUT'), 'ETIMEDOUT')
@@ -198,7 +216,8 @@ test('classifyInstallError: 网络类与空输入不炸,各有短码', () => {
   assert.equal(classifyInstallError('some unknown failure'), '其他')
 })
 
-test('classifyInstallError: 两类同时出现时优先报文件占用(它是唯一要"动手"的那类)', () => {
-  const mixed = 'npm error code E404\nnpm error EPERM: operation not permitted'
+test('classifyInstallError: 无 code 行时,error 行里的文件占用类仍优先于 registry 类', () => {
+  // 两条都是 error 行、又没有裁决 code 行 → 文件占用是唯一要"动手"的那类,优先报
+  const mixed = 'npm error E404 Not Found - GET https://...\nnpm error EPERM: operation not permitted'
   assert.equal(classifyInstallError(mixed), 'EPERM')
 })