zen-gitsync 2.17.29 → 2.17.30

package/src/ui/public/index.html

@@ -10,38 +10,38 @@
     <meta name="theme-color" content="#141820" media="(prefers-color-scheme: dark)" />
     <title>Zen GitSync</title>
     <!-- 字体改为自托管(@font-face 见 src/main.css),不再依赖 Google Fonts 外链 -->
-    <script type="module" crossorigin src="/assets/index-CKxygqdx.js"></script>
+    <script type="module" crossorigin src="/assets/index-BgO3-PhT.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
-    <link rel="modulepreload" crossorigin href="/assets/element-plus-D0R8BMj4.js">
+    <link rel="modulepreload" crossorigin href="/assets/element-plus-Cfu0ZUp9.js">
     <link rel="modulepreload" crossorigin href="/assets/monaco-DkJuNcCr.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-CCrjQw5C.js">
-    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-BKeZSroN.js">
-    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-Dk7WnZLB.js">
-    <link rel="modulepreload" crossorigin href="/assets/IconButton-Dl1cdP_x.js">
-    <link rel="modulepreload" crossorigin href="/assets/configStore-fJaic3kE.js">
-    <link rel="modulepreload" crossorigin href="/assets/socket-io-BFqQXqAp.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitStore-D9oF5nof.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-sxw_ye8l.js">
+    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-OGa67zj-.js">
+    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-Dg1c0l0q.js">
+    <link rel="modulepreload" crossorigin href="/assets/IconButton-DI4O8Y_p.js">
+    <link rel="modulepreload" crossorigin href="/assets/configStore-BrdhjW5U.js">
+    <link rel="modulepreload" crossorigin href="/assets/socket-io-TBtw0msS.js">
+    <link rel="modulepreload" crossorigin href="/assets/gitStore-BgvCpppG.js">
     <link rel="modulepreload" crossorigin href="/assets/fileIcon-B5p5pGN9.js">
-    <link rel="modulepreload" crossorigin href="/assets/flow-mindmap-Doi70WWn.js">
-    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-21uStCdd.js">
-    <link rel="modulepreload" crossorigin href="/assets/useThemeObserver-BvSA7RDh.js">
-    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-DpFTO5cg.js">
-    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-DXJO-G55.js">
-    <link rel="modulepreload" crossorigin href="/assets/toolsStore-C89takm3.js">
-    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-B3ZNTXnP.js">
-    <link rel="modulepreload" crossorigin href="/assets/vue-flow-5Aq2bwoG.js">
+    <link rel="modulepreload" crossorigin href="/assets/flow-mindmap-C_fqj8ZL.js">
+    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-NWN_GKkA.js">
+    <link rel="modulepreload" crossorigin href="/assets/useThemeObserver-qsxO0WJ7.js">
+    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-DeSPG5C-.js">
+    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-YaOsJZZI.js">
+    <link rel="modulepreload" crossorigin href="/assets/toolsStore-DrTCC32p.js">
+    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-ClQb9yY3.js">
+    <link rel="modulepreload" crossorigin href="/assets/vue-flow-Cjr_ADp5.js">
     <link rel="stylesheet" crossorigin href="/assets/element-plus-Qexo5hiM.css">
     <link rel="stylesheet" crossorigin href="/assets/monaco-B2lPvkrc.css">
     <link rel="stylesheet" crossorigin href="/assets/vendor-Bwl4dT-P.css">
-    <link rel="stylesheet" crossorigin href="/assets/SvgIcon-CDNsk4-Q.css">
-    <link rel="stylesheet" crossorigin href="/assets/IconButton-RlXqKOeu.css">
+    <link rel="stylesheet" crossorigin href="/assets/SvgIcon-BQ6bR7l0.css">
+    <link rel="stylesheet" crossorigin href="/assets/IconButton-W2X09OKH.css">
     <link rel="stylesheet" crossorigin href="/assets/flow-mindmap-BMpmHdqh.css">
-    <link rel="stylesheet" crossorigin href="/assets/previewSandbox-PYnM6Paz.css">
-    <link rel="stylesheet" crossorigin href="/assets/CommonDialog-w6EmBEXv.css">
-    <link rel="stylesheet" crossorigin href="/assets/FileDiffViewer-n5ea9qMe.css">
-    <link rel="stylesheet" crossorigin href="/assets/TemplateManager-DO7EPfj8.css">
+    <link rel="stylesheet" crossorigin href="/assets/previewSandbox-SqNQvuHv.css">
+    <link rel="stylesheet" crossorigin href="/assets/CommonDialog-Bzi5ISqT.css">
+    <link rel="stylesheet" crossorigin href="/assets/FileDiffViewer-B6zy6NiA.css">
+    <link rel="stylesheet" crossorigin href="/assets/TemplateManager-DiM3vrbf.css">
     <link rel="stylesheet" crossorigin href="/assets/vue-flow-CavUTEzp.css">
-    <link rel="stylesheet" crossorigin href="/assets/index-DVpFh9xE.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-BrIl1iaG.css">
   </head>
   <body>
     <div id="app"></div>

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

@@ -22,12 +22,12 @@
 // 2) **内置精选离线可用**。每个类型的 builtin 组是静态数据,不联网也有内容;
 //    联网来源失败时用户至少还能看到它们。内置条目的仓库与 npm 包名都经过实际校验,
 //    不是凭印象写的占位数据。
-// 3) **两个安装目标**。
-//    - project: <cwd>/.claude/skills/<id>/ 与 <cwd>/.mcp.json(项目级,生态通行约定)
+// 3) **两个安装目标**(路径常量都在 src/paths.js,与 g ai 读取端共用同一份)。
+//    - project: <cwd>/.zen-gitsync/ai/skills/<id>/ 与 <cwd>/.zen-gitsync/ai/mcp.json
 //    - global : ~/.zen-gitsync/ai/skills/<id>/ 与 ~/.zen-gitsync/ai/mcp.json
-//               (即「g ai 智能体」,对所有项目生效;路径常量在 src/paths.js)
-//    路径与 g ai 的读取端(src/cli/ai/skills.js、src/cli/ai/mcp.js)共用同一份常量,
-//    改这里不会出现"装了但读不到"。
+//               (即「g ai 智能体」,对所有项目生效)
+//    早先项目级写在 <cwd>/.claude/skills 与 <cwd>/.mcp.json —— 那是别家工具的约定目录,
+//    2026-09-30 按用户要求迁到自家目录,不再读写 .claude。
 // 4) 所有来自网络的值在落盘前都要过白名单校验(仓库名 / 包名 / 子路径),
 //    因为这些值最终会变成 git clone 与 npm install 的参数 —— 网络数据不可信。
 //
@@ -44,7 +44,7 @@ import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import open from 'open';
 import { asyncRoute, HttpError } from '../../utils/asyncRoute.js';
-import { AI_SKILLS_DIR, AI_MCP_FILE } from '../../../../paths.js';
+import { AI_SKILLS_DIR, AI_MCP_FILE, projectSkillsDir, projectMcpFile } from '../../../../paths.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -634,6 +634,7 @@ function normalizeTarget(value) {
 /**
  * 把 target + type 翻译成落盘位置。
  * 项目级与全局级的 skill 目录形状刻意保持一致,读取端才能共用一套解析逻辑。
+ * 路径常量统一来自 paths.js —— 这里改了、g ai 那边没改,就会出现"装了但读不到"。
  */
 function targetPaths({ type, target, cwd }) {
   if (target === 'global') {
@@ -641,9 +642,10 @@ function targetPaths({ type, target, cwd }) {
       ? { root: AI_SKILLS_DIR, file: '', label: 'g ai 智能体' }
       : { root: '', file: AI_MCP_FILE, label: 'g ai 智能体' };
   }
+  const label = path.basename(cwd) || cwd;
   return type === 'skill'
-    ? { root: path.join(cwd, '.claude', 'skills'), file: '', label: path.basename(cwd) || cwd }
-    : { root: '', file: path.join(cwd, '.mcp.json'), label: path.basename(cwd) || cwd };
+    ? { root: projectSkillsDir(cwd), file: '', label }
+    : { root: '', file: projectMcpFile(cwd), label };
 }
 
 // ── 已安装扫描 ────────────────────────────────────────────────
@@ -715,10 +717,10 @@ async function installedMcpsIn(file, target) {
 async function listInstalled({ type, cwd }) {
   const items = [];
   if (type === 'skill') {
-    if (cwd) items.push(...await installedSkillsIn(path.join(cwd, '.claude', 'skills'), 'project'));
+    if (cwd) items.push(...await installedSkillsIn(projectSkillsDir(cwd), 'project'));
     items.push(...await installedSkillsIn(AI_SKILLS_DIR, 'global'));
   } else {
-    if (cwd) items.push(...await installedMcpsIn(path.join(cwd, '.mcp.json'), 'project'));
+    if (cwd) items.push(...await installedMcpsIn(projectMcpFile(cwd), 'project'));
     items.push(...await installedMcpsIn(AI_MCP_FILE, 'global'));
   }
   return items;

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

@@ -69,6 +69,13 @@ async function exists(target) {
   return await fs.stat(target).then(() => true).catch(() => false);
 }
 
+// 项目级扩展的落盘位置。这里**写死字面量**而不是 import paths.js 的常量 ——
+// 契约就是"装在哪儿",常量漂了必须在这几条断言上炸出来。
+// (2026-09-30 之前是 <cwd>/.claude/skills 与 <cwd>/.mcp.json,已迁到自家目录)
+const PROJECT_AI = path.join(sandboxProject, '.zen-gitsync', 'ai');
+const PROJECT_SKILLS = path.join(PROJECT_AI, 'skills');
+const PROJECT_MCP = path.join(PROJECT_AI, 'mcp.json');
+
 test('catalog: 只查内置来源时完全离线,并保留按来源分组的形状', async () => {
   const { call } = harness();
   const { status, payload } = await call('GET /api/agent/marketplace/catalog', {
@@ -144,7 +151,7 @@ test('sources: 拒绝未知类型', async () => {
   assert.equal(payload.success, false);
 });
 
-test('install skill: 项目级落到 <cwd>/.claude/skills,全局级落到 ~/.zen-gitsync/ai/skills', async () => {
+test('install skill: 项目级落到 <cwd>/.zen-gitsync/ai/skills,全局级落到 ~/.zen-gitsync/ai/skills', async () => {
   const { call } = harness();
   const content = '---\nname: demo\n description: x\n---\n# demo\n';
   const body = { type: 'skill', item: { id: 'demo-skill', name: 'demo', content } };
@@ -153,7 +160,9 @@ test('install skill: 项目级落到 <cwd>/.claude/skills,全局级落到 ~/.zen
     body: { ...body, target: 'project', cwd: sandboxProject },
   });
   assert.equal(project.status, 200);
-  assert.ok(await exists(path.join(sandboxProject, '.claude', 'skills', 'demo-skill', 'SKILL.md')));
+  assert.ok(await exists(path.join(PROJECT_SKILLS, 'demo-skill', 'SKILL.md')));
+  // 反向自证:项目级不再碰 .claude(那是别家工具的目录,装进去会让人以为有依赖)
+  assert.equal(await exists(path.join(sandboxProject, '.claude')), false, '不该在项目里建 .claude');
 
   const global = await call('POST /api/agent/marketplace/install', {
     body: { ...body, target: 'global', cwd: sandboxProject },
@@ -182,7 +191,7 @@ test('install skill: 没有仓库也没有正文时拒绝,不产生空目录', a
   });
   assert.equal(status, 400);
   assert.match(payload.error, /没有可安装的仓库地址/);
-  assert.equal(await exists(path.join(sandboxProject, '.claude', 'skills', 'useless')), false);
+  assert.equal(await exists(path.join(PROJECT_SKILLS, 'useless')), false);
 });
 
 test('install skill: 仓库名与子路径都要过白名单', async () => {
@@ -220,7 +229,7 @@ test('install mcp: 写入目标文件、补齐 name/description,并把 ${project
   });
 
   assert.equal(status, 200);
-  const file = path.join(sandboxProject, '.mcp.json');
+  const file = PROJECT_MCP;
   const config = JSON.parse(await fs.readFile(file, 'utf8'));
   const server = config.mcpServers['mcp-fake-fs'];
   assert.ok(server, '应写入 mcpServers');
@@ -232,12 +241,12 @@ test('install mcp: 写入目标文件、补齐 name/description,并把 ${project
 
 test('install mcp: 非法包名被拒绝,且不写出配置文件', async () => {
   const { call } = harness();
-  const before = await exists(path.join(sandboxProject, '.mcp.json'));
+  const before = await exists(PROJECT_MCP);
   const { status } = await call('POST /api/agent/marketplace/install', {
     body: { type: 'mcp', target: 'project', cwd: sandboxProject, item: { id: 'evil', package: 'pkg; rm -rf /' } },
   });
   assert.equal(status, 400);
-  if (!before) assert.equal(await exists(path.join(sandboxProject, '.mcp.json')), false);
+  if (!before) assert.equal(await exists(PROJECT_MCP), false);
 });
 
 test('install mcp: 只有远程端点时用 mcp-remote 桥接,而不是报错或装出一个无效配置', async () => {
@@ -291,7 +300,7 @@ test('uninstall: 只删指定目标的那一份,另一份保留', async () => {
     query: { target: 'project', cwd: sandboxProject },
   });
   assert.equal(status, 200);
-  assert.equal(await exists(path.join(sandboxProject, '.claude', 'skills', 'demo-skill')), false);
+  assert.equal(await exists(path.join(PROJECT_SKILLS, 'demo-skill')), false);
   assert.ok(await exists(path.join(AI_SKILLS_DIR, 'demo-skill', 'SKILL.md')), '全局那份不应被连坐删掉');
 });
 
@@ -302,7 +311,7 @@ test('uninstall: MCP 从配置里摘掉对应键,保留其他 server', async ()
     query: { target: 'project', cwd: sandboxProject },
   });
   assert.equal(status, 200);
-  const config = JSON.parse(await fs.readFile(path.join(sandboxProject, '.mcp.json'), 'utf8'));
+  const config = JSON.parse(await fs.readFile(PROJECT_MCP, 'utf8'));
   assert.equal(Object.prototype.hasOwnProperty.call(config.mcpServers, 'mcp-fake-fs'), false);
   assert.ok(await exists(AI_MCP_FILE), '全局配置文件应保持不变');
 });
@@ -327,7 +336,7 @@ test('uninstall: 未安装的条目返回 404', async () => {
   assert.equal(status, 404);
 });
 
-test('install: 项目不存在时拒绝,不会把 .claude/skills 建到奇怪的地方', async () => {
+test('install: 项目不存在时拒绝,不会把 .zen-gitsync/ai/skills 建到奇怪的地方', async () => {
   const { call } = harness();
   const missing = path.join(sandboxProject, 'no-such-dir');
   const { status, payload } = await call('POST /api/agent/marketplace/install', {

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

@@ -153,6 +153,22 @@ export function buildEnvContextBlock({
     lines.push('');
   }
 
+  // ── 对话流渲染：正文里嵌的图 ────────────────────────────────────────────
+  //
+  // 与「克隆优先 SSH」同类：行为约定、不需要取数，所以取不到 board 时也照给。
+  //
+  // 为什么非写不可：执行器是在本机干活的，让它"展示一张图"时它会去 Read 那张图、
+  // 然后**在正文里贴一条本机路径**（或者把路径塞进代码块）—— 而对话流是 markdown
+  // 渲染，屏幕上只有一行字（用户实测 2026-09-30：图读出来了、描述得挺准、就是没有图）。
+  // 这条告诉它写成 `![](路径)`；后端据此开了一个「仓库内的图片」端点
+  // （workbench/jobImage.js），前端负责把路径重写成那个 URL（utils/localImageSrc.ts）。
+  lines.push(compact
+    ? '对话流渲染：正文里写 `![说明](图片绝对路径)` 用户才能看到图（图片须在本任务仓库内）；只贴路径，用户看到的是一行字。'
+    : '对话流渲染：想让用户**看到**图，就在回答正文里写 Markdown 图片 `![说明](图片绝对路径)` —— '
+      + '图片须位于本任务仓库内（把截图 / 图表存进去再引用），界面会自动加载渲染。'
+      + '只贴路径、或把路径放进代码块，用户看到的只是一行字。');
+  lines.push('');
+
   if (compact) {
     // 引导语替掉整段用户偏好，但**点名**那条行为约定：偏好本身不重述（前文有），
     // 可"有这么一条"得让模型看得见，否则克隆仓库时它会退回 https。

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

@@ -252,6 +252,23 @@ test('注入块带上「克隆优先 SSH」这条用户偏好', () => {
   assert.match(block, /Permission denied \(publickey\)/);
 });
 
+// ── 对话流渲染：正文里嵌的图 ──────────────────────────────────────────────
+//
+// 执行器"展示一张图"的默认写法是贴一条本机路径（它 Read 了那张图，描述得也挺准），
+// 而对话流是 markdown 渲染 —— 用户屏幕上只有一行字。这条提示是唯一能让 Agent 知道
+// "写 ![](路径) 才看得见"的地方，所以两种模式都得带上，且必须点明"仓库内"这个前提
+// （后端端点只服务仓库内的图片，写成仓库外的路径会 403）。
+test('注入块要求 Agent 用 markdown 图片语法展示图，且说明图片须在仓库内', () => {
+  const board = boardOf({ recentDirs: ['D:\\ws\\a'], tasks: [] });
+  for (const [name, block] of [['完整版', build({ board })], ['精简版', build({ board, compact: true })]]) {
+    assert.match(block, /对话流渲染/, `${name}缺少对话流渲染提示`);
+    assert.match(block, /!\[说明\]\(图片绝对路径\)/, `${name}没给出可照抄的写法`);
+    assert.match(block, /仓库内/, `${name}没说清图片必须落在仓库内`);
+    // 只贴路径这个反例要点出来：模型最可能的做法就是它
+    assert.match(block, /只贴路径/, `${name}没点出"只贴路径看不到图"`);
+  }
+});
+
 test('真相源清单来自唯一的 TRUTH_FILES（四个路径一个不落，且不多写）', () => {
   const block = build({ board: boardOf({ recentDirs: ['D:\\ws\\a'], tasks: [] }) });
   const listed = block.split('\n').filter(l => l.startsWith('- ') && l.includes(' —— ') && l.includes('json'));

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

@@ -74,6 +74,12 @@ import {
   findStagingFile,
   cleanupDispatchStaging,
 } from './attachmentUtils.js';
+import {
+  resolveJobImagePath,
+  isInsideRoot,
+  IMAGE_PATH_ERRORS,
+  IMAGE_PATH_STATUS,
+} from './jobImage.js';
 import {
   DEFAULT_INSTRUCTION,
   readInstruction,
@@ -933,6 +939,84 @@ ${subSummaries.map((s, i) => `\n### [${i + 1}] ${s.name} (${s.root})\n${s.summar
     res.json({ success: true, job: serializeJob(j, taskMap) });
   }));
 
+  // GET /api/workbench/jobs/:id/image?path=…  —— 正文内嵌图片（模型写 ![说明](本机路径)）
+  //
+  // 为什么要有这个端点：执行器在本机干活，"展示一张图"最自然的写法是贴一条本机路径，
+  // 而对话流是 markdown 渲染 —— `<img src="c:\ws\repo\docs\a.png">` 在浏览器里永远是
+  // 裂图。前端把这类路径重写成这个 URL（utils/localImageSrc.ts，两处对话流共用）。
+  //
+  // 权限边界 =「这个 job 所属仓库内的图片文件」（判定见 jobImage.js）：
+  //   · 后缀过 IMAGE_EXTS 白名单；路径必须落在仓库根内（`..` 穿越在那里就挡掉了）；
+  //   · 这里**再按 realpath 校验一次** —— lexical 判定挡不住仓库里一个指向外部的
+  //     符号链接，而仓库内容很可能是从网上 clone 来的；
+  //   · 响应带 nosniff + CSP(sandbox)：同上前提下，一份恶意 SVG 被直接在浏览器里
+  //     打开时，它的脚本不能跑在本应用的源上（<img> 里本来就不会执行，这里防的是直接访问）。
+  app.get('/api/workbench/jobs/:id/image', asyncRoute(async (req, res) => {
+    const id = req.params.id;
+    // 优先内存；退回「磁盘历史 ∪ 别的实例正在跑」的合并表 —— 看板上能看到、日志也能
+    // 在本实例渲染的 job，它的图不该因为"不是这个进程起的"就裂掉（与 GET /jobs/:id 同源）。
+    let job = jobs.get(id);
+    if (!job) {
+      await refreshJobsFromDisk();
+      job = mergedJobs().get(id);
+    }
+    if (!job) throw new HttpError(404, 'job 不存在');
+
+    const tasksData = await readJson(TASKS_FILE, { tasks: [] });
+    const task = (tasksData.tasks || []).find(t => t.id === job.taskId);
+    const root = resolveTaskRepoPath(
+      task,
+      typeof getCurrentProjectPath === 'function' ? getCurrentProjectPath() : '',
+    );
+
+    const resolved = resolveJobImagePath({ root, requested: req.query.path });
+    if (!resolved.ok) {
+      throw new HttpError(
+        IMAGE_PATH_STATUS[resolved.reason] || 400,
+        IMAGE_PATH_ERRORS[resolved.reason] || '图片路径不合法',
+      );
+    }
+
+    let realFile;
+    try {
+      realFile = await fsp.realpath(resolved.absPath);
+    } catch {
+      throw new HttpError(404, '图片不存在（模型给的路径在本机读不到）');
+    }
+    let realRoot;
+    try {
+      realRoot = await fsp.realpath(root);
+    } catch {
+      realRoot = root; // 仓库根都没了的话，下面那次 stat 也会失败，不必在这里另报一种错
+    }
+    if (!isInsideRoot(realRoot, realFile)) {
+      throw new HttpError(IMAGE_PATH_STATUS['outside-root'], IMAGE_PATH_ERRORS['outside-root']);
+    }
+
+    let stat;
+    try {
+      stat = await fsp.stat(realFile);
+    } catch {
+      throw new HttpError(404, '图片不存在（模型给的路径在本机读不到）');
+    }
+    if (!stat.isFile()) throw new HttpError(404, '路径不是一个文件');
+    // 与附件同一个上限：正文里嵌一张 20MB 以上的图只会把页面拖死
+    if (stat.size > MAX_IMAGE_BYTES) {
+      throw new HttpError(413, `图片超过 ${MAX_IMAGE_BYTES / 1024 / 1024}MB，未加载`);
+    }
+
+    // mime 按**后缀**给（不读文件头）：后缀已过白名单，且这条内容只喂给 <img>
+    res.set('Content-Type', resolved.mime);
+    res.set('Content-Length', String(stat.size));
+    res.set('Content-Disposition', 'inline');
+    res.set('Cache-Control', 'private, max-age=300');
+    res.set('X-Content-Type-Options', 'nosniff');
+    res.set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+    const stream = fs.createReadStream(realFile);
+    stream.on('error', () => res.end());
+    stream.pipe(res);
+  }));
+
   app.delete('/api/workbench/jobs/:id', asyncRoute(async (req, res) => {
     const id = req.params.id;
     let removed = false;

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

@@ -0,0 +1,141 @@
+// 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.
+//
+// 正文内嵌图片的路径判定（模型在回答里写 `![说明](图片路径)`）。
+//
+// ── 为什么需要服务端做中转 ────────────────────────────────────────────────
+//
+// 执行器（claude / opencode / codex）是在本机干活的，"展示一张图"对它来说最自然的
+// 写法就是把刚截的图 / 刚读的 png 的**本机路径**贴出来。而对话流是 markdown 渲染：
+// `<img src="c:\ws\repo\docs\a.png">` 在浏览器里永远是裂图 —— 那个地址不在页面能
+// 够到的世界里。用户实测（2026-09-30）：让 Agent"展示一张图片"，它把截图读进上下文、
+// 描述得挺准，但屏幕上只有一行字和一条路径。
+//
+// 于是：前端把这类本地路径重写成 `/api/workbench/jobs/:id/image?path=…`
+// （utils/localImageSrc.ts），服务端按「这个 job 所属仓库」去取文件 —— 本文件是
+// 那个端点的**路径判定**部分，读盘在 index.js 的路由里。
+//
+// ── 权限边界刻意收在"仓库内的图片" ────────────────────────────────────────
+//
+//   · 后缀必须过 IMAGE_EXTS 白名单（附件用的同一份，别再另起一份 —— 两份白名单
+//     分叉时不会报错，只会让某一类图在正文里裂、在附件里正常）；
+//   · 解析后的绝对路径必须落在仓库根内（`..` 穿越在这里被挡掉）。
+//
+// 判定写成**纯函数**（不碰 fs）：跨平台路径比较（盘符大小写、`..`、UNC、混用斜杠）
+// 是最容易写错又最难在集成测试里覆盖的一块，单独可测。真正的读盘那一步还会按
+// realpath 再校验一次（挡仓库里指向外部的符号链接），见 index.js。
+
+import path from 'path';
+import { IMAGE_EXTS, mimeForExt } from './attachmentUtils.js';
+
+/**
+ * 失败原因 → HTTP 状态码。
+ * 放在这里而不是路由里 switch：端点只负责把 reason 映射出去，
+ * 免得"哪些原因算 4xx 的哪一种"在两处各写一遍。
+ */
+export const IMAGE_PATH_STATUS = {
+  'no-root': 400,
+  'empty': 400,
+  'bad-ext': 415,
+  'outside-root': 403,
+};
+
+/** 失败原因 → 给前端/用户的文案 */
+export const IMAGE_PATH_ERRORS = {
+  'no-root': '无法确定任务所属仓库路径',
+  'empty': 'path 不能为空',
+  'bad-ext': '只支持图片文件（png / jpg / jpeg / gif / webp / bmp / svg）',
+  'outside-root': '图片必须位于任务所属仓库内',
+};
+
+/**
+ * 规整模型给出来的路径写法。
+ *
+ * 模型写路径的几种常见包裹方式都要认（否则同一条路径有时能渲染、有时不能）：
+ *   `<c:\ws\a.png>`（markdown 允许尖括号包住含空格的目标）、`` `c:\ws\a.png` ``、
+ *   `"c:\ws\a.png"`、`file:///c:/ws/a.png`。
+ * 返回空串表示"这个值不值得再往下解析"（空 / 含 NUL）。
+ *
+ * @param {unknown} requested
+ * @returns {string} 规整后的路径；不可用时为空串
+ */
+export function normalizeImagePath(requested) {
+  let p = typeof requested === 'string' ? requested.trim() : '';
+  if (!p) return '';
+  // NUL 字节是路径里的经典绕过手法（`a.png\0.txt`），直接判死
+  if (p.includes('\0')) return '';
+  for (const [open, close] of [['<', '>'], ['`', '`'], ['"', '"'], ["'", "'"]]) {
+    if (p.length > open.length + close.length && p.startsWith(open) && p.endsWith(close)) {
+      p = p.slice(open.length, p.length - close.length).trim();
+      break;
+    }
+  }
+  if (/^file:\/\//i.test(p)) {
+    p = p.replace(/^file:\/\//i, '');
+    // file:///C:/a.png → /C:/a.png，那个多余的斜杠会让 win32 把盘符当相对目录
+    if (/^\/[a-zA-Z]:[\\/]/.test(p)) p = p.slice(1);
+  }
+  return p.trim();
+}
+
+/** 路径后缀（小写，不含点）；没有后缀返回空串 */
+export function imageExtOf(p) {
+  const m = String(p || '').toLowerCase().match(/\.([a-z0-9]+)$/);
+  return m ? m[1] : '';
+}
+
+/**
+ * `abs` 是否真的落在 `root` 目录**内部**（不含 root 自己）。
+ *
+ * 用 `path.relative` 而不是 `startsWith(root)`：字符串前缀会把 `D:\ws\repo-old`
+ * 当成 `D:\ws\repo` 里的路径。win32 上 relative 还会把盘符大小写归一，
+ * 所以 `d:\ws\repo` 与 `D:\WS\REPO\x.png` 能正确判成父子关系。
+ */
+export function isInsideRoot(root, abs) {
+  const r = path.resolve(String(root || ''));
+  const a = path.resolve(String(abs || ''));
+  if (!r || !a) return false;
+  const rel = path.relative(r, a);
+  if (!rel) return false; // 等于根目录本身 —— 那是目录不是文件
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * 把请求里的 path 解析成「仓库内的一张图片」。
+ *
+ * 相对路径按仓库根解析（模型常常写 `docs/screenshots/a.png` —— 它的 cwd 就是仓库根，
+ * 对它来说这就是一个够用的地址；到我们这边得补上根）。
+ *
+ * @param {object} input
+ * @param {string} input.root       任务所属仓库绝对路径
+ * @param {unknown} input.requested 请求里的原始 path（查询串已由 express 解码）
+ * @returns {{ok: true, absPath: string, ext: string, mime: string}
+ *          | {ok: false, reason: keyof typeof IMAGE_PATH_ERRORS}}
+ */
+export function resolveJobImagePath({ root = '', requested = '' } = {}) {
+  const base = typeof root === 'string' ? root.trim() : '';
+  if (!base) return { ok: false, reason: 'no-root' };
+
+  const rel = normalizeImagePath(requested);
+  if (!rel) return { ok: false, reason: 'empty' };
+
+  const ext = imageExtOf(rel);
+  if (!ext || !IMAGE_EXTS.has(ext)) return { ok: false, reason: 'bad-ext' };
+
+  // 绝对路径原样用，相对路径挂到仓库根下
+  const absPath = path.resolve(base, rel);
+  if (!isInsideRoot(base, absPath)) return { ok: false, reason: 'outside-root' };
+
+  return { ok: true, absPath, ext, mime: mimeForExt(ext) };
+}