zen-gitsync 2.16.51 → 2.17.1

package/src/ui/server/index.js

@@ -28,6 +28,7 @@ import { Server } from 'socket.io';
 import { spawn, exec } from 'child_process';
 import iconv from 'iconv-lite';
 import { createRequestLogger } from './middleware/requestLogger.js';
+import { migrateDataDir } from '../../dataDirMigration.js';
 import { createErrorHandler } from './middleware/errorHandler.js';
 import { registerUiSocketHandlers } from './socket/registerUiSocketHandlers.js';
 import { registerExecRoutes } from './routes/exec.js';
@@ -190,6 +191,14 @@ let recentPushStatus = {
 
 const showConsole = true;
 async function startUIServer(noOpen = false, savePort = false) {
+  // 数据目录布局迁移:把散在主目录的历史文件收进 ~/.zen-gitsync/(见 src/paths.js)。
+  // 必须早于任何数据读写 —— 尤其是下面的实例注册表(它要读 instances/ 目录)。
+  // 幂等 + 永不抛错,失败只是"这轮没搬成",下次启动重试。
+  const migrationReport = await migrateDataDir();
+  if (migrationReport.moved.length || migrationReport.cleaned.length) {
+    logger.info(`[dataDirMigration] 搬移 ${migrationReport.moved.length} 项、留档 ${migrationReport.cleaned.length} 项`);
+  }
+
   const app = express();
   const httpServer = createServer(app);
 

package/src/ui/server/routes/config.js

@@ -15,10 +15,10 @@
 import express from 'express';
 import { asyncRoute, HttpError } from '../utils/asyncRoute.js';
 import path from 'path';
-import os from 'os';
 import fs from 'fs/promises';
 import open from 'open';
 import logger from '../utils/logger.js';
+import { CONFIG_FILE } from '../../../paths.js';
 
 // 跳过的产物/资源/lock 文件(用 stat 一行带过,不打 patch)
 const SKIP_FILE_PATTERNS = [
@@ -345,7 +345,7 @@ export function registerConfigRoutes({
       
         res.json(config)
       } catch (error) {
-        const configPath = path.join(os.homedir(), '.git-commit-tool.json')
+        const configPath = CONFIG_FILE
         res.status(500).json({
           success: false,
           code: 'CONFIG_LOAD_FAILED',
@@ -396,7 +396,7 @@ export function registerConfigRoutes({
   // 检查系统配置文件格式
   app.get('/api/config/check-file-format', asyncRoute(async (req, res) => {
       try {
-        const configPath = path.join(os.homedir(), '.git-commit-tool.json');
+        const configPath = CONFIG_FILE;
       
         try {
           const data = await fs.readFile(configPath, 'utf-8');
@@ -428,16 +428,19 @@ export function registerConfigRoutes({
       }
     }));
 
-  // 使用系统默认程序打开配置文件 ~/.git-commit-tool.json
+  // 使用系统默认程序打开配置文件(~/.zen-gitsync/config.json)
   app.post('/api/config/open-file', asyncRoute(async (req, res) => {
       try {
-        const filePath = path.join(os.homedir(), '.git-commit-tool.json');
+        const filePath = CONFIG_FILE;
         try {
           // 检查文件是否存在，不存在也尝试让系统创建（可能会打开空文件）
           await fs.access(filePath);
         } catch (_) {
-          // 如果文件不存在，先创建一个最小结构，避免某些系统无法打开不存在的路径
+          // 如果文件不存在，先创建一个最小结构，避免某些系统无法打开不存在的路径。
+          // 注意:新路径是嵌套目录,首次打开时数据目录可能还没建(正常启动流程里由
+          // dataDirMigration 建好,这里是独立于迁移的兜底)。
           try {
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
             await fs.writeFile(filePath, '{}', 'utf-8');
           } catch (e) {
             // 创建失败不阻断打开尝试

package/src/ui/server/routes/git/aiDiffSummary.js

@@ -35,12 +35,12 @@
 
 import { createHash } from 'node:crypto';
 import fs from 'node:fs/promises';
-import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
 import { callLlmStream } from '../workbench/llmClient.js';
 import { ensureWithinCwd } from '../../utils/pathGuard.js';
 import { createThinkFilter } from '../../../../cli/ai/streamFilter.js';
+import { AI_DIFF_SUMMARIES_DIR } from '../../../../paths.js';
 
 // prompt 预算:diff 超过预算只保留头部并标注截断,防止 token 爆炸
 const MAX_FILE_DIFF_CHARS = 8000;
@@ -51,7 +51,7 @@ const MAX_UNTRACKED_FILES = 40;
 // 提示词或输出契约变化时递增，避免复用旧规则生成的说明。
 const SUMMARY_CACHE_VERSION = 1;
 const MAX_SUMMARY_CACHE_ENTRIES = 300;
-const SUMMARY_CACHE_DIR = path.join(os.homedir(), '.zen-gitsync', 'ai-diff-summaries');
+const SUMMARY_CACHE_DIR = AI_DIFF_SUMMARIES_DIR;
 
 function hashText(value) {
   return createHash('sha256').update(String(value || ''), 'utf8').digest('hex');

package/src/ui/server/routes/gitOps.js

@@ -33,6 +33,10 @@ import {
   assertGitConfigKey,
   assertGitConfigValue
 } from '../utils/gitArgs.js';
+import {
+  describeGitProcessFailure,
+  GIT_NOT_FOUND
+} from '../utils/gitExitCode.js';
 
 // 解析 push 的 remote 参数:不传 = 空数组(裸 push 走上游,历史行为);
 // 传了则结合当前分支与上游计算 refspec(详见 remotes.js 的 buildPushRefs)。
@@ -354,7 +358,26 @@ export function registerGitOpsRoutes({
       logger.info('推送成功，已设置推送状态标记');
       res.json({ success: true, message: stdout });
     } catch (error) {
-      res.status(error?.statusCode || 500).json({ success: false, error: error.message });
+      // PATH 里没有 git.exe：走 spawn 失败而不是退出码，单独给指引
+      if (error?.code === 'ENOENT') {
+        return res.status(500).json({ success: false, ...GIT_NOT_FOUND });
+      }
+      // HttpError(参数校验失败)走原样返回；只有 git 进程真的失败(error.code 是退出码)时
+      // 才做退出码翻译 —— 零输出时 error.message 只有 "Command failed: git push"。
+      if (typeof error?.code !== 'number' || error?.statusCode) {
+        return res.status(error?.statusCode || 500).json({ success: false, error: error.message });
+      }
+      const failure = describeGitProcessFailure({
+        code: error.code,
+        stdout: error.stdout,
+        stderr: error.stderr
+      });
+      res.status(500).json({
+        success: false,
+        error: failure.error,
+        errorCode: failure.errorCode,
+        exitCode: failure.exitCode
+      });
     }
   });
 
@@ -394,7 +417,24 @@ export function registerGitOpsRoutes({
       res.json({ success: true, message: stdout });
     } catch (error) {
       // assertGitRef 抛的是 HttpError(400),别吞成 500
-      res.status(error?.statusCode || 500).json({ success: false, error: error.message });
+      if (error?.code === 'ENOENT') {
+        return res.status(500).json({ success: false, ...GIT_NOT_FOUND });
+      }
+      if (typeof error?.code !== 'number' || error?.statusCode) {
+        return res.status(error?.statusCode || 500).json({ success: false, error: error.message });
+      }
+      // 与 /api/push 同理：git 进程级失败(含零输出的 NTSTATUS)翻成人话
+      const failure = describeGitProcessFailure({
+        code: error.code,
+        stdout: error.stdout,
+        stderr: error.stderr
+      });
+      res.status(500).json({
+        success: false,
+        error: failure.error,
+        errorCode: failure.errorCode,
+        exitCode: failure.exitCode
+      });
     }
   });
 
@@ -603,22 +643,31 @@ export function registerGitOpsRoutes({
             message: standardOutput || errorOutput || 'Push successful'
           });
         } else {
-          // 推送失败
+          // 推送失败。git 自己报错时 stderr 里有 `fatal: ...`，直接透传；
+          // 但进程**没跑起来**时 stdout/stderr 全空，退出码是 3221225794(0xC0000142)
+          // 这类 NTSTATUS —— 原样抛给用户等于什么都没说，必须翻译成人话。
           logger.error('推送失败:', errorOutput || standardOutput);
+          const failure = describeGitProcessFailure({
+            code,
+            stdout: standardOutput,
+            stderr: errorOutput
+          });
 
           // 添加到命令历史（失败情况）
           addCommandToHistory(
             pushCommandLabel,
             standardOutput,
             errorOutput,
-            errorOutput || standardOutput || `Push failed with code ${code}`,
+            failure.error,
             executionTime
           );
 
           sendProgress({
             type: 'complete',
             success: false,
-            error: errorOutput || standardOutput || `Push failed with code ${code}`
+            error: failure.error,
+            errorCode: failure.errorCode,
+            exitCode: failure.exitCode
           });
         }
         finish();
@@ -630,19 +679,26 @@ export function registerGitOpsRoutes({
         // 计算执行时间
         const executionTime = Date.now() - startTime;
 
+        // ENOENT = PATH 里没有 git.exe。这不是"推送失败"而是"根本没得推"，
+        // 给明确指引比抛 "spawn git ENOENT" 有用。
+        const failure = error?.code === 'ENOENT'
+          ? GIT_NOT_FOUND
+          : { errorCode: null, error: error.message };
+
         // 添加到命令历史（错误情况）
         addCommandToHistory(
           'git push --progress',
           '',
           '',
-          error.message,
+          failure.error,
           executionTime
         );
 
         sendProgress({
           type: 'complete',
           success: false,
-          error: error.message
+          error: failure.error,
+          errorCode: failure.errorCode
         });
         finish();
       });

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

@@ -27,16 +27,13 @@
 import fsp from 'fs/promises';
 import path from 'path';
 import { logger } from './shared.js';
+import { AGENT_SESSIONS_DIR } from '../../../../paths.js';
 
-// 数据目录：与 ai-split-sessions 平级
-export const AGENT_SESSIONS_DIR = path.join(
-  path.dirname(path.dirname(path.dirname(path.dirname(new URL(import.meta.url).pathname.replace(/^\//, ''))))),
-  '.zen-gitsync',
-  'agent-sessions'
-);
-// 上面路径在 Windows 下不可靠，改用 os.homedir
-import os from 'os';
-export const AGENT_SESSIONS_DIR_FIXED = path.join(os.homedir(), '.zen-gitsync', 'agent-sessions');
+// 数据目录：与 ai-split-sessions 平级，定义见 src/paths.js
+export { AGENT_SESSIONS_DIR };
+// 历史遗留别名:此前这里有个"从 import.meta.url 推路径"的错误实现(Windows 下不可靠),
+// 后来补了个 _FIXED 版本两套并存。现在统一到 paths.js 的单一常量。
+export const AGENT_SESSIONS_DIR_FIXED = AGENT_SESSIONS_DIR;
 
 export const MAX_AGENT_SESSIONS = 200;
 export const AGENT_SESSIONS_KEEP = 100;

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

@@ -20,6 +20,7 @@
 //   - mime → ext 与前端 el-upload accept 对齐
 //   - sanitizeExt 防路径穿越：未在白名单的后缀返回 fallback（默认 'bin'）
 
+import path from 'path';
 import fsp from 'fs/promises';
 import { IMAGES_DIR } from './shared.js';
 
@@ -74,3 +75,95 @@ export function resolveExt({ originalName, mime }) {
   if (fromName) return fromName;
   return null;
 }
+
+// ════════════════════════════════════════════════════════════════════════════
+// 派发附件暂存区
+//
+// 主 Agent 控制台要能在**任务被建出来之前**收附件（粘贴的截图 / 选的文件），
+// 而 §17 的上传端点都要求 taskId / subId 作为挂载点 —— 派发那一刻两者都还不存在。
+// 所以先落到这个暂存目录：文件名 `{attId}.{ext}`，不写任何 JSON，
+// 附件记录由前端持有；派发成功时服务端再把它 move 进 `_task-{taskId}/`。
+//
+// 目录名带下划线前缀是为了不和 `_task-{id}` / `{subId}` 撞名
+// （genId 形如 `mu55toof-2555ou`，不会以 `_` 开头）。
+// ════════════════════════════════════════════════════════════════════════════
+export const DISPATCH_STAGING_DIR = path.join(IMAGES_DIR, '_dispatch');
+
+/** genId 的实际形状；暂存区只认这种 id，挡掉 `../` 之类的路径穿越 */
+const ATT_ID_RE = /^[a-z0-9][a-z0-9-]{4,62}$/i;
+
+export function isSafeAttId(id) {
+  return typeof id === 'string' && ATT_ID_RE.test(id);
+}
+
+// 反向映射（raw 端点用）：暂存附件没有 JSON 记录，mime 只能从后缀推。
+// MIME_TO_EXT 里同一族只登记了规范后缀，白名单中的别名要单独补，
+// 否则 `a.jpeg` 会被当成 octet-stream 下载而不是 inline 显示。
+const EXT_TO_MIME = (() => {
+  const out = {};
+  for (const [mime, ext] of Object.entries(MIME_TO_EXT)) {
+    if (!out[ext]) out[ext] = mime;
+  }
+  const aliases = { jpeg: 'image/jpeg', markdown: 'text/markdown' };
+  for (const [ext, mime] of Object.entries(aliases)) {
+    if (!out[ext]) out[ext] = mime;
+  }
+  return out;
+})();
+
+export function mimeForExt(ext) {
+  return EXT_TO_MIME[String(ext || '').toLowerCase()] || 'application/octet-stream';
+}
+
+/**
+ * 暂存文件的绝对路径。
+ * id 与后缀都要过白名单/形状校验，任一不合法返回 null —— 路径完全由服务端拼，
+ * 前端只提供 id + ext，因此不存在把文件写到暂存区之外的可能。
+ */
+export function stagingPath(attId, ext) {
+  if (!isSafeAttId(attId)) return null;
+  const e = String(ext || '').toLowerCase();
+  if (!ALLOWED_EXTS.has(e)) return null;
+  return path.join(DISPATCH_STAGING_DIR, `${attId}.${e}`);
+}
+
+/** 按 id 在暂存区里找实际文件（删除 / 预览用，不需要前端提供 ext） */
+export async function findStagingFile(attId) {
+  if (!isSafeAttId(attId)) return null;
+  let names;
+  try {
+    names = await fsp.readdir(DISPATCH_STAGING_DIR);
+  } catch {
+    return null; // 目录还不存在 = 没有任何暂存文件
+  }
+  const hit = names.find(n => n.startsWith(attId + '.'));
+  return hit ? path.join(DISPATCH_STAGING_DIR, hit) : null;
+}
+
+/**
+ * 清理超时的暂存文件（用户粘了图却没派发就关页面 → 不留永久垃圾）。
+ * 进程启动时跑一次即可，不必定时器：暂存区的生命周期本来就是"几分钟内派发掉"。
+ */
+export async function cleanupDispatchStaging(maxAgeMs = 24 * 60 * 60 * 1000) {
+  let names;
+  try {
+    names = await fsp.readdir(DISPATCH_STAGING_DIR);
+  } catch {
+    return 0; // 目录不存在，没什么可清
+  }
+  const deadline = Date.now() - maxAgeMs;
+  let removed = 0;
+  for (const name of names) {
+    const full = path.join(DISPATCH_STAGING_DIR, name);
+    try {
+      const st = await fsp.stat(full);
+      if (!st.isFile() || st.mtimeMs >= deadline) continue;
+      await fsp.unlink(full);
+      removed++;
+    } catch { /* 单个文件出问题不该让整轮清理中断 */ }
+  }
+  if (removed > 0) {
+    try { await fsp.rmdir(DISPATCH_STAGING_DIR); } catch { /* 还有别的文件留在里面，留着目录 */ }
+  }
+  return removed;
+}

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

@@ -0,0 +1,100 @@
+// 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.
+//
+// 派发附件暂存区的纯函数单测。
+//
+// 这一层是**安全边界**：派发时前端只回传 { id, ext }，文件路径完全由服务端拼。
+// 所以"无论前端传什么，产物都不会跑出暂存目录"必须由断言钉死 ——
+// 一旦 stagingPath 的校验被放松，就等于开了一个任意文件读取/覆盖的口子。
+//
+// 只测纯函数，不碰真实文件系统：临时目录相关行为（findStagingFile / cleanup）
+// 由端到端验证覆盖，避免单测在用户真实的 ~/.zen-gitsync 里制造/删除文件。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+
+import {
+  DISPATCH_STAGING_DIR,
+  ALLOWED_EXTS,
+  isSafeAttId,
+  mimeForExt,
+  stagingPath,
+} from './attachmentUtils.js';
+
+test('stagingPath：合法 id + 白名单后缀 → 落在暂存目录内', () => {
+  const p = stagingPath('mu55toof-2555ou', 'png');
+  assert.equal(p, path.join(DISPATCH_STAGING_DIR, 'mu55toof-2555ou.png'));
+});
+
+test('stagingPath：大写后缀归一成小写', () => {
+  assert.equal(
+    stagingPath('mu55toof-2555ou', 'PNG'),
+    path.join(DISPATCH_STAGING_DIR, 'mu55toof-2555ou.png'),
+  );
+});
+
+test('stagingPath：id 含路径分隔符 / 上跳 / 空白一律拒绝', () => {
+  const bad = ['../../etc/passwd', 'a/b', 'a\\b', '..', '', 'x', 'a b', 'a/../b', 'a'.repeat(70)];
+  for (const id of bad) {
+    assert.equal(stagingPath(id, 'png'), null, `应拒绝 id=${JSON.stringify(id)}`);
+  }
+});
+
+test('stagingPath：后缀不在白名单一律拒绝（含可执行文件与拼接花招）', () => {
+  const bad = ['exe', 'sh', 'bat', '', '.', 'png/../evil', 'png.exe', '..'];
+  for (const ext of bad) {
+    assert.equal(stagingPath('mu55toof-2555ou', ext), null, `应拒绝 ext=${JSON.stringify(ext)}`);
+  }
+});
+
+test('stagingPath：任何输入下产物都不会跳出暂存目录', () => {
+  const ids = ['../../evil', '..\\..\\evil', '/abs', 'C:/windows/x', 'a'.repeat(100), 'a--b'];
+  const exts = ['png', 'jpg', 'pdf', '../../x', 'exe'];
+  for (const id of ids) {
+    for (const ext of exts) {
+      const p = stagingPath(id, ext);
+      if (p === null) continue;
+      assert.equal(path.dirname(p), DISPATCH_STAGING_DIR, `产物跑出了暂存目录：${p}`);
+    }
+  }
+});
+
+test('isSafeAttId：只放行 genId 形状', () => {
+  assert.ok(isSafeAttId('mu55toof-2555ou'));
+  assert.ok(isSafeAttId('abc12'));
+  assert.ok(!isSafeAttId('ab'), '太短');
+  assert.ok(!isSafeAttId('a'.repeat(70)), '太长');
+  assert.ok(!isSafeAttId('has space'));
+  assert.ok(!isSafeAttId('has/slash'));
+  assert.ok(!isSafeAttId('-leading-dash'), '不能以连字符开头');
+  assert.ok(!isSafeAttId(''));
+  assert.ok(!isSafeAttId(null));
+  assert.ok(!isSafeAttId(42));
+});
+
+test('mimeForExt：常见后缀给具体类型，未知回退 octet-stream', () => {
+  assert.equal(mimeForExt('png'), 'image/png');
+  assert.equal(mimeForExt('JPG'), 'image/jpeg');
+  assert.equal(mimeForExt('pdf'), 'application/pdf');
+  assert.equal(mimeForExt('exe'), 'application/octet-stream');
+  assert.equal(mimeForExt(''), 'application/octet-stream');
+});
+
+test('白名单与 mime 映射同源：每个允许的后缀都能反查出具体 mime', () => {
+  for (const ext of ALLOWED_EXTS) {
+    const m = mimeForExt(ext);
+    assert.ok(m && m !== 'application/octet-stream', `${ext} 没有对应的具体 mime`);
+  }
+});

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

@@ -0,0 +1,137 @@
+// 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 调度台发出去的指令，最终 prompt 只是用户原文
+// + 附件清单（拼装见 promptParts.js），cwd 之外的项目、看板进度、历史指令
+// 一概不在里面。于是用户问"我的项目有哪些"，Agent 只能就着当前目录猜 ——
+// 而数据其实全在本机，只是没人告诉它路径。
+//
+// 这里做两件事，缺一不可：
+//   1. 给**摘要** —— 项目清单 + 各列任务计数（顺着看板口径，一眼看到进度）；
+//   2. 给**真相源文件路径** —— 要细节自己去读。
+// 刻意不把 tasks.json 全文塞进 prompt：几十条任务、每条还挂着执行输出，
+// 既烧 token，又会把用户真正要办的那句话淹掉。
+//
+// ⚠️ 文案为什么可以是中文硬编码（与 orchestratorStore 的「服务端不写死中文」不冲突）：
+// 那一条约束针对的是**回给 UI 渲染的文案**，而这里是喂给模型的 prompt 内容，
+// 不经过前端 $t()，也不会显示在界面上。反过来说，它也不该跟着界面语言变 ——
+// 中文指令配中文上下文，模型理解得更稳。
+//
+// 纯函数：只吃入参、不读文件（文件读取在调用方 routes/workbench/index.js）。
+// 这样单测不用碰真实用户数据 —— 与 promptParts.js 同一个理由。
+// 统计口径复用 projectRegistry 的 summarizeProjectTasks：「任务算哪一列」
+// 全局只有这一个实现，看板怎么分列，这里就怎么统计。
+
+import { summarizeProjectTasks, canonicalProjectPath, TASK_COLUMNS } from './projectRegistry.js';
+
+/** 项目清单最多列几个：再多就该让 Agent 自己去读文件，而不是往 prompt 里堆 */
+export const ENV_CONTEXT_MAX_PROJECTS = 30;
+
+/**
+ * 列 key → 中文标签。**按 key 取名，不靠数组下标**：
+ * 顺序一律由 TASK_COLUMNS 决定，这里只负责"这列叫什么"。
+ * （上一轮去掉「评审中」列时，这份清单和下面的 `${s.todo}/${s.doing}/${s.done}` 是两处
+ *  各写各的，改一处漏一处 —— 现在两份都从 TASK_COLUMNS 推。）
+ */
+const COLUMN_LABELS = { todo: '待处理', doing: '进行中', done: '已完成' };
+
+/** 按 TASK_COLUMNS 的顺序取标签；缺标签时回落成 key 本身，
+ *  宁可让 Agent 看到 `todo` 也不要看到空段（空段会让列与标签整体错位）。 */
+const columnLabels = TASK_COLUMNS.map(k => COLUMN_LABELS[k] || k);
+
+/**
+ * 拼运行环境上下文块。
+ *
+ * @param {object}   input
+ * @param {string}   input.currentProjectPath 本次任务的工作目录（= Agent 的 cwd）
+ * @param {object[]} input.projects 项目条目（buildProjectEntries 的输出：{name, path, key}）
+ * @param {object[]} input.tasks    tasks.json 里的全部任务
+ * @param {object[]} input.jobs     执行记录（snapshotJobs() 的结果）
+ * @param {string}   input.tasksFile        真相源文件绝对路径（下面几个同理）
+ * @param {string}   input.jobsFile
+ * @param {string}   input.orchestratorFile
+ * @param {string}   input.configFile
+ * @param {number}   [input.maxProjects] 只影响列出条数，不影响合计统计
+ * @returns {string|null} 上下文块；没有任何项目可列时返回 null（调用方据此跳过注入）
+ */
+export function buildEnvContextBlock({
+  currentProjectPath = '',
+  projects = [],
+  tasks = [],
+  jobs = [],
+  tasksFile = '',
+  jobsFile = '',
+  orchestratorFile = '',
+  configFile = '',
+  maxProjects = ENV_CONTEXT_MAX_PROJECTS,
+} = {}) {
+  const list = Array.isArray(projects) ? projects.filter(p => p && p.key) : [];
+  if (list.length === 0) return null;
+
+  const stats = summarizeProjectTasks(
+    Array.isArray(tasks) ? tasks : [],
+    Array.isArray(jobs) ? jobs : [],
+  );
+
+  // 合计按全部任务算（含「未关联项目」那一桶），所以不能用 list 求和
+  const total = { total: 0 };
+  for (const key of TASK_COLUMNS) total[key] = 0;
+  for (const s of stats.values()) {
+    total.total += s.total;
+    for (const key of TASK_COLUMNS) total[key] += s[key] || 0;
+  }
+
+  const limit = Number.isFinite(maxProjects) && maxProjects > 0 ? Math.floor(maxProjects) : ENV_CONTEXT_MAX_PROJECTS;
+  const shown = list.slice(0, limit);
+  // 当前项目的比对**必须归一化后再比**：条目 key 是 canonicalProjectPath 的结果
+  // （Windows 形式小写 + 斜杠归一如 d:\ws\x），而调用方给的 currentProjectPath 是原始写法
+  // （盘符/目录段大小写都不一定一致）。直接拿 path 跟 key 比会永远不等 —— 同款口径分叉
+  // 在后端项目列表里已经制造过一次「同名项目分裂成两个」，这里不重蹈。
+  const currentKey = canonicalProjectPath(currentProjectPath);
+
+  const lines = [];
+  lines.push('[运行环境 · 由 zen-gitsync 多项目编排台自动注入，不是用户输入的内容]');
+  lines.push('');
+  lines.push(`当前任务所在项目（也是你的工作目录）: ${currentProjectPath || '(未指定)'}`);
+  lines.push('');
+  lines.push(`项目清单（共 ${list.length} 个；格式: 名称 | 路径 | ${columnLabels.join('/')}）:`);
+  for (const p of shown) {
+    const s = stats.get(p.key) || {};
+    const mark = currentKey && p.key === currentKey ? '  ← 当前' : '';
+    lines.push(`- ${p.name || p.key} | ${p.path} | ${TASK_COLUMNS.map(k => s[k] || 0).join('/')}${mark}`);
+  }
+  if (list.length > shown.length) {
+    lines.push(`- …还有 ${list.length - shown.length} 个未列出（读下面的文件可以看全）`);
+  }
+  lines.push('');
+  lines.push(
+    `看板任务概览：全部项目合计 ${total.total} 条 —— ` +
+    TASK_COLUMNS.map(k => `${COLUMN_LABELS[k]} ${total[k] || 0}`).join(' / '),
+  );
+  lines.push('');
+  lines.push('需要细节时直接读这些文件（本机绝对路径，你有读取权限，不必先问用户）:');
+  if (tasksFile) lines.push(`- ${tasksFile} —— 全部任务全文（标题/描述/子任务状态/报错/projectPath）`);
+  if (jobsFile) lines.push(`- ${jobsFile} —— 历次执行记录（状态与输出）`);
+  if (orchestratorFile) lines.push(`- ${orchestratorFile} —— 用户在调度台发过的指令流水`);
+  if (configFile) lines.push(`- ${configFile} —— 应用配置（projects / recentDirectories）`);
+  lines.push('');
+  lines.push(
+    '用户问到"我有哪些项目""某件事进展如何"这类问题时，先读上面的文件再回答；' +
+    '不要凭当前目录猜测，也不要回答"我看不到/无法访问"。',
+  );
+
+  return lines.join('\n');
+}