zen-gitsync 2.17.8 → 2.17.10

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

@@ -0,0 +1,306 @@
+// 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.
+//
+// Skill / MCP 广场后端的回归测试。
+//
+// 重点钉住三类容易悄悄坏掉的行为:
+//   1) 安装目标落盘位置(项目级 vs g ai 全局级)—— 路径一旦漂移,
+//      前端显示"已安装"而 g ai 读不到,是最难排查的一类 bug;
+//   2) 网络数据落盘前的白名单校验(仓库名 / 包名 / 子路径 / 路径穿越);
+//   3) 单个来源抓取失败不能影响其他来源(按来源分组的核心承诺)。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// ── 沙箱 ──────────────────────────────────────────────────────
+// paths.js 在模块加载时就用 os.homedir() 求值,必须在 import 之前改环境变量。
+// HOMEDRIVE/HOMEPATH 是 Windows 上 os.homedir() 的另一条取值路径,必须删掉,
+// 否则 USERPROFILE 改了也不生效。
+const sandboxHome = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mp-home-'));
+const sandboxProject = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mp-project-'));
+process.env.USERPROFILE = sandboxHome;
+process.env.HOME = sandboxHome;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const { registerAgentMarketplaceRoutes } = await import('./agentMarketplace.js');
+const { AI_SKILLS_DIR, AI_MCP_FILE } = await import('../../../../paths.js');
+
+// ── 测试脚手架:把注册的 handler 抓出来直接调 ──────────────────
+function harness(currentProject = sandboxProject) {
+  const handlers = new Map();
+  const app = {
+    get(route, handler) { handlers.set(`GET ${route}`, handler); },
+    post(route, handler) { handlers.set(`POST ${route}`, handler); },
+    delete(route, handler) { handlers.set(`DELETE ${route}`, handler); },
+  };
+  registerAgentMarketplaceRoutes({ app, getCurrentProjectPath: () => currentProject });
+
+  const call = async (key, { query = {}, body = {}, params = {} } = {}) => {
+    const handler = handlers.get(key);
+    assert.ok(handler, `未注册路由: ${key}`);
+    let payload = null;
+    let status = 200;
+    const res = {
+      status(code) { status = code; return this; },
+      json(data) { payload = data; return this; },
+    };
+    await handler({ method: key.split(' ')[0], path: key.split(' ')[1], query, body, params }, res);
+    return { status, payload };
+  };
+  return { call };
+}
+
+async function exists(target) {
+  return await fs.stat(target).then(() => true).catch(() => false);
+}
+
+test('catalog: 只查内置来源时完全离线,并保留按来源分组的形状', async () => {
+  const { call } = harness();
+  const { status, payload } = await call('GET /api/agent/marketplace/catalog', {
+    query: { type: 'skill', sources: 'builtin', cwd: sandboxProject },
+  });
+
+  assert.equal(status, 200);
+  assert.equal(payload.success, true);
+  assert.equal(payload.groups.length, 1, '指定单个来源时只应返回该组');
+
+  const [group] = payload.groups;
+  assert.equal(group.id, 'builtin');
+  assert.equal(group.status, 'ok');
+  assert.ok(group.items.length > 0, '内置精选不能是空列表(否则离线时广场全空)');
+
+  // 内置条目必须带可安装信息,否则前端会给出一个必然失败的按钮
+  for (const item of group.items) {
+    assert.ok(item.installable, `${item.name} 应可安装`);
+    assert.ok(item.repository || item.package, `${item.name} 缺少仓库或包名`);
+  }
+});
+
+test('catalog: 未指定来源时返回全部来源,每个来源是独立的一组', async () => {
+  const { call } = harness();
+  const { payload } = await call('GET /api/agent/marketplace/catalog', {
+    query: { type: 'mcp', sources: 'builtin', cwd: sandboxProject },
+  });
+  const ids = payload.groups.map(group => group.id);
+  assert.deepEqual(ids, ['builtin']);
+
+  // 不带 sources 时应覆盖该类型的全部来源定义
+  const { payload: all } = await call('GET /api/agent/marketplace/sources', { query: { type: 'mcp' } });
+  assert.ok(all.sources.length >= 4, 'MCP 至少应有 4 个来源');
+  assert.equal(all.sources[0].id, 'builtin');
+});
+
+test('sources: 拒绝未知类型', async () => {
+  const { call } = harness();
+  const { status, payload } = await call('GET /api/agent/marketplace/sources', { query: { type: 'plugin' } });
+  assert.equal(status, 400);
+  assert.equal(payload.success, false);
+});
+
+test('install skill: 项目级落到 <cwd>/.claude/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 } };
+
+  const project = await call('POST /api/agent/marketplace/install', {
+    body: { ...body, target: 'project', cwd: sandboxProject },
+  });
+  assert.equal(project.status, 200);
+  assert.ok(await exists(path.join(sandboxProject, '.claude', 'skills', 'demo-skill', 'SKILL.md')));
+
+  const global = await call('POST /api/agent/marketplace/install', {
+    body: { ...body, target: 'global', cwd: sandboxProject },
+  });
+  assert.equal(global.status, 200);
+  assert.ok(await exists(path.join(AI_SKILLS_DIR, 'demo-skill', 'SKILL.md')));
+  // 全局级必须先解析到 paths.js 的常量,而不是某个自己拼的路径
+  assert.equal(global.payload.item.dir, path.join(AI_SKILLS_DIR, 'demo-skill'));
+});
+
+test('install skill: 重复安装同一目标返回 409', async () => {
+  const { call } = harness();
+  const install = () => call('POST /api/agent/marketplace/install', {
+    body: { type: 'skill', target: 'project', cwd: sandboxProject, item: { id: 'dup-skill', content: '---\nname: d\n---\n' } },
+  });
+  assert.equal((await install()).status, 200);
+  const second = await install();
+  assert.equal(second.status, 409);
+  assert.match(second.payload.error, /已安装/);
+});
+
+test('install skill: 没有仓库也没有正文时拒绝,不产生空目录', async () => {
+  const { call } = harness();
+  const { status, payload } = await call('POST /api/agent/marketplace/install', {
+    body: { type: 'skill', target: 'project', cwd: sandboxProject, item: { id: 'useless', name: 'useless' } },
+  });
+  assert.equal(status, 400);
+  assert.match(payload.error, /没有可安装的仓库地址/);
+  assert.equal(await exists(path.join(sandboxProject, '.claude', 'skills', 'useless')), false);
+});
+
+test('install skill: 仓库名与子路径都要过白名单', async () => {
+  const { call } = harness();
+  const cases = [
+    { id: 'bad-repo-1', repository: 'https://evil.example.com/a/b' },
+    { id: 'bad-repo-2', repository: '../../etc' },
+    { id: 'bad-repo-3', repository: 'owner' },
+  ];
+  for (const item of cases) {
+    const { status } = await call('POST /api/agent/marketplace/install', {
+      body: { type: 'skill', target: 'project', cwd: sandboxProject, item },
+    });
+    assert.equal(status, 400, `${JSON.stringify(item)} 应被拒绝`);
+  }
+});
+
+test('install mcp: 写入目标文件、补齐 name/description,并把 ${project} 展开成真实路径', async () => {
+  const { call } = harness();
+  const { status, payload } = await call('POST /api/agent/marketplace/install', {
+    body: {
+      type: 'mcp',
+      target: 'project',
+      cwd: sandboxProject,
+      // 用 builtin 里带 ${project} 占位符的形态,但包名换成不会真去下载的名字
+      item: {
+        id: 'mcp-fake-fs',
+        name: 'Fake FS',
+        description: '测试用',
+        package: '@modelcontextprotocol/server-filesystem',
+        args: ['-y', '@modelcontextprotocol/server-filesystem', '${project}'],
+        envKeys: ['SOME_TOKEN'],
+      },
+    },
+  });
+
+  assert.equal(status, 200);
+  const file = path.join(sandboxProject, '.mcp.json');
+  const config = JSON.parse(await fs.readFile(file, 'utf8'));
+  const server = config.mcpServers['mcp-fake-fs'];
+  assert.ok(server, '应写入 mcpServers');
+  assert.equal(server.command, 'npx');
+  assert.equal(server.args[2], sandboxProject, '${project} 必须被替换成项目真实路径');
+  assert.deepEqual(server.requiredEnv, ['SOME_TOKEN']);
+  assert.equal(payload.item.file, file);
+});
+
+test('install mcp: 非法包名被拒绝,且不写出配置文件', async () => {
+  const { call } = harness();
+  const before = await exists(path.join(sandboxProject, '.mcp.json'));
+  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);
+});
+
+test('install mcp: 只有远程端点时用 mcp-remote 桥接,而不是报错或装出一个无效配置', async () => {
+  const { call } = harness();
+  const { status } = await call('POST /api/agent/marketplace/install', {
+    body: {
+      type: 'mcp',
+      target: 'global',
+      cwd: sandboxProject,
+      item: { id: 'remote-only', name: 'Remote', remoteUrl: 'https://example.com/mcp', transport: 'remote' },
+    },
+  });
+  assert.equal(status, 200);
+  const config = JSON.parse(await fs.readFile(AI_MCP_FILE, 'utf8'));
+  const server = config.mcpServers['remote-only'];
+  assert.equal(server.command, 'npx');
+  assert.deepEqual(server.args, ['-y', 'mcp-remote', 'https://example.com/mcp']);
+  assert.equal(server.transport, 'remote');
+});
+
+test('install mcp: 既没有包也没有远程端点时拒绝', async () => {
+  const { call } = harness();
+  const { status } = await call('POST /api/agent/marketplace/install', {
+    body: { type: 'mcp', target: 'project', cwd: sandboxProject, item: { id: 'nothing', name: 'Nothing' } },
+  });
+  assert.equal(status, 422);
+});
+
+test('installed: 同时列出项目级与全局级,并标明 target', async () => {
+  const { call } = harness();
+  const { status, payload } = await call('GET /api/agent/marketplace/installed', {
+    query: { type: 'skill', cwd: sandboxProject },
+  });
+  assert.equal(status, 200);
+  const ids = payload.items.map(item => `${item.target}:${item.id}`);
+  assert.ok(ids.includes('project:demo-skill'));
+  assert.ok(ids.includes('global:demo-skill'));
+
+  const { payload: mcpPayload } = await call('GET /api/agent/marketplace/installed', {
+    query: { type: 'mcp', cwd: sandboxProject },
+  });
+  const mcpIds = mcpPayload.items.map(item => `${item.target}:${item.id}`);
+  assert.ok(mcpIds.includes('project:mcp-fake-fs'));
+  assert.ok(mcpIds.includes('global:remote-only'));
+});
+
+test('uninstall: 只删指定目标的那一份,另一份保留', async () => {
+  const { call } = harness();
+  const { status } = await call('DELETE /api/agent/marketplace/item/:type/:id', {
+    params: { type: 'skill', id: 'demo-skill' },
+    query: { target: 'project', cwd: sandboxProject },
+  });
+  assert.equal(status, 200);
+  assert.equal(await exists(path.join(sandboxProject, '.claude', 'skills', 'demo-skill')), false);
+  assert.ok(await exists(path.join(AI_SKILLS_DIR, 'demo-skill', 'SKILL.md')), '全局那份不应被连坐删掉');
+});
+
+test('uninstall: MCP 从配置里摘掉对应键,保留其他 server', async () => {
+  const { call } = harness();
+  const { status } = await call('DELETE /api/agent/marketplace/item/:type/:id', {
+    params: { type: 'mcp', id: 'mcp-fake-fs' },
+    query: { target: 'project', cwd: sandboxProject },
+  });
+  assert.equal(status, 200);
+  const config = JSON.parse(await fs.readFile(path.join(sandboxProject, '.mcp.json'), 'utf8'));
+  assert.equal(Object.prototype.hasOwnProperty.call(config.mcpServers, 'mcp-fake-fs'), false);
+  assert.ok(await exists(AI_MCP_FILE), '全局配置文件应保持不变');
+});
+
+test('uninstall: 路径穿越形态的 id 被拒绝', async () => {
+  const { call } = harness();
+  for (const id of ['..', '../..', 'a/../../b', 'a\\b']) {
+    const { status } = await call('DELETE /api/agent/marketplace/item/:type/:id', {
+      params: { type: 'skill', id: encodeURIComponent(id) },
+      query: { target: 'project', cwd: sandboxProject },
+    });
+    assert.equal(status, 400, `id=${id} 应被拒绝`);
+  }
+});
+
+test('uninstall: 未安装的条目返回 404', async () => {
+  const { call } = harness();
+  const { status } = await call('DELETE /api/agent/marketplace/item/:type/:id', {
+    params: { type: 'skill', id: 'never-installed' },
+    query: { target: 'global', cwd: sandboxProject },
+  });
+  assert.equal(status, 404);
+});
+
+test('install: 项目不存在时拒绝,不会把 .claude/skills 建到奇怪的地方', async () => {
+  const { call } = harness();
+  const missing = path.join(sandboxProject, 'no-such-dir');
+  const { status, payload } = await call('POST /api/agent/marketplace/install', {
+    body: { type: 'skill', target: 'project', cwd: missing, item: { id: 'x', content: '---\nname: x\n---\n' } },
+  });
+  assert.equal(status, 400);
+  assert.match(payload.error, /项目目录不存在/);
+});

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

@@ -0,0 +1,167 @@
+// CLI(`g ai`)与 Web 智能体面板之间**共享口径**的一致性守卫。
+//
+// 为什么需要：同一套逻辑在本仓库反复出现"两边各写一份"的历史 ——
+//   路径归一   : projectRegistry.js ↔ 前端 utils/path.ts
+//   智能体提示词: agent.js(zh/en) ↔ agentChat.js(zh/en)，共四处
+//   上下文准备  : CLI 已改成「条数/字符双预算 + 丢弃项摘录成梗概」，
+//                Web 侧还停在「按条数硬切 40 + 纯 splice 丢弃」，而且它的 splice 是
+//                **原地**改 session.messages —— 聊久了模型失忆，磁盘上的会话记录还被永久削掉一截
+//   LLM 传输    : Web 侧自带的 streamChatOnce 不拦"流被截断但 tool_calls 已部分到达"，
+//                半截的参数有可能被拿去执行
+// 这类分叉的失效方式是「**不报错，两个入口表现不一样**」，很难被发现。所以这里不验证
+// 模型行为（也没法验），只钉住三件事：压缩/传输逻辑各只有一份实现、两个入口都必须走它、
+// 口径参数不许在调用点各自硬写。谁要是想再抄一份，就会撞上下面的第三条测试。
+//
+// 共享模块：src/cli/ai/context.js（上下文）、src/cli/ai/transport.js（传输）
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SRC_ROOT = path.resolve(here, '..', '..', '..', '..');
+const SHARED_DIR = path.resolve(SRC_ROOT, 'cli', 'ai');
+
+const CONTEXT_FILE = path.join(SHARED_DIR, 'context.js');
+const TRANSPORT_FILE = path.join(SHARED_DIR, 'transport.js');
+
+// 两个入口。CLI 侧的循环在 turn.js，Web 侧在 agentChat.js。
+const ENTRY_POINTS = [
+  { label: 'CLI(g ai) turn.js', file: path.join(SHARED_DIR, 'turn.js') },
+  { label: 'Web 智能体面板 agentChat.js', file: path.join(here, 'agentChat.js') },
+];
+
+// 每条共享口径:模块 + 导出名 + 调用点的额外要求
+const SHARED = [
+  {
+    what: '上下文准备',
+    module: CONTEXT_FILE,
+    exported: 'prepareRequestMessages',
+    // 预算只留在共享模块里,调用点必须把 locale 传进去(旧图片占位符要分语言)
+    mustPass: [/locale/],
+    mustNotPass: [/maxMessages/, /maxChars/],
+  },
+  {
+    what: 'LLM 传输',
+    module: TRANSPORT_FILE,
+    exported: 'streamChatOnce',
+  },
+];
+
+const SCAN_EXT = /\.(js|mjs|cjs|ts)$/;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', 'public']);
+
+function walk(dir, acc = []) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return acc; }
+  for (const name of entries) {
+    const full = path.join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name) || name.startsWith('.')) continue;
+      walk(full, acc);
+    } else if (SCAN_EXT.test(name)) acc.push(full);
+  }
+  return acc;
+}
+
+/** 取出 `name(...)` 的实参文本（够用的括号配对，调用点都很简单）。 */
+function callArgs(src, name) {
+  const at = src.indexOf(name + '(');
+  if (at < 0) return null;
+  let depth = 0;
+  for (let i = at + name.length; i < src.length; i++) {
+    if (src[i] === '(') depth++;
+    else if (src[i] === ')') { depth--; if (depth === 0) return src.slice(at + name.length + 1, i); }
+  }
+  return '';
+}
+
+const importLineFor = (src, name) => src.split(/\r?\n/)
+  .find(l => /^import\s/.test(l) && new RegExp(`\\b${name}\\b`).test(l));
+
+test('两个入口都从同一份共享模块导入,并真的用它', () => {
+  for (const { what, module, exported } of SHARED) {
+    for (const { label, file } of ENTRY_POINTS) {
+      const src = readFileSync(file, 'utf8');
+      const line = importLineFor(src, exported);
+      assert.ok(line, `${label} 没有导入 ${exported}（${what}）：必须收敛到共享模块`);
+      const spec = /from\s*['"]([^'"]+)['"]/.exec(line)?.[1];
+      assert.ok(spec, `${label} 的 import 语句里找不到模块路径`);
+      assert.equal(
+        path.resolve(path.dirname(file), spec),
+        module,
+        `${label} 从别处导入了 ${exported}：两个入口必须用同一份实现`,
+      );
+      // 除了 import 那行之外还得真的出现在别处（被调用、被赋值给变量都算）
+      const body = src.split(/\r?\n/).filter(l => l !== line).join('\n');
+      assert.match(body, new RegExp(`\\b${exported}\\b`), `${label} 导入了 ${exported} 却没用`);
+    }
+  }
+});
+
+test('口径参数只在共享模块里定义,调用点不许自己硬写', () => {
+  const { mustPass = [], mustNotPass = [] } = SHARED[0];
+  for (const { label, file } of ENTRY_POINTS) {
+    const args = callArgs(readFileSync(file, 'utf8'), 'prepareRequestMessages');
+    assert.ok(args !== null, `${label} 没有调用 prepareRequestMessages`);
+    for (const re of mustPass) assert.match(args, re, `${label} 的调用漏了 ${re}（旧图片占位符会退化成中文）`);
+    for (const re of mustNotPass) {
+      assert.doesNotMatch(
+        args,
+        re,
+        `${label} 自己指定了预算（${re}）：预算口径必须留在 context.js，否则两侧又会慢慢漂开`,
+      );
+    }
+  }
+});
+
+test('压缩与传输逻辑在生产代码里各只有一处实现', () => {
+  // 这些是"再分叉一次"会留下的脚印：本地函数定义与本地上限常量。
+  // 只认定义（const/function），不认注释里的提及 —— 注释提到历史是正常的。
+  const PRIMITIVES = [
+    { what: '本地 sanitizeMessages 定义', re: /function\s+sanitizeMessages\s*\(/ },
+    { what: '本地 stripStaleImages 定义', re: /function\s+stripStaleImages\s*\(/ },
+    { what: '本地历史裁剪函数', re: /function\s+trimHistory\s*\(/ },
+    { what: '本地历史条数上限常量', re: /const\s+MAX_HISTORY_MESSAGES\s*=/ },
+    { what: '本地请求副本构造函数', re: /function\s+buildRequestMessages\s*\(/ },
+    { what: '本地 LLM 传输函数', re: /function\s+streamChatOnce\s*\(/ },
+    { what: '本地 LLM 超时常量', re: /const\s+LLM_TIMEOUT_MS\s*=/ },
+  ];
+  const owners = new Set([CONTEXT_FILE, TRANSPORT_FILE]);
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (owners.has(file) || /\.test\./.test(file)) continue;
+    const src = readFileSync(file, 'utf8');
+    for (const { what, re } of PRIMITIVES) {
+      if (re.test(src)) offenders.push(`${what} → ${path.relative(SRC_ROOT, file)}`);
+    }
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    '检测到第二份压缩/传输实现。CLI 与 Web 必须共用 src/cli/ai/ 下的共享模块，不要各写一遍 —— ' +
+      '这条链路的失效方式是"不报错但两个入口表现不一样"，很难被发现。\n' +
+      offenders.join('\n'),
+  );
+});
+
+test('共享模块本身必须导出这些口径', () => {
+  const expectations = [
+    [CONTEXT_FILE, ['prepareRequestMessages', 'sanitizeMessages', 'stripStaleImages', 'buildRequestMessages']],
+    [TRANSPORT_FILE, ['streamChatOnce', 'httpFailure']],
+  ];
+  for (const [file, names] of expectations) {
+    const src = readFileSync(file, 'utf8');
+    for (const name of names) {
+      assert.match(
+        src,
+        new RegExp(`(export function|function) ${name}\\s*\\(`),
+        `${path.basename(file)} 不再定义 ${name}`,
+      );
+    }
+  }
+});

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

@@ -25,6 +25,8 @@ import path from 'node:path';
 import { asyncRoute, HttpError } from '../../utils/asyncRoute.js';
 import { agentSessionStore } from './agentSessionStore.js';
 import { runAgentTurn } from './agentChat.js';
+import { registerAgentMarketplaceRoutes } from './agentMarketplace.js';
+import { createProjectListProvider } from './projectTool.js';
 import { nowIso } from './shared.js';
 
 const { genSessionId, autoTitle, read: readSession, write: writeSession, delete: deleteSession, listMeta: listSessionsMeta, enforceRetention, rename: renameSession } = agentSessionStore;
@@ -45,6 +47,56 @@ function sessionBelongsTo(sessionCwd, projectCwd) {
   return Boolean(project && s === project);
 }
 
+// An ask_user call keeps its chat SSE request open until this map receives the
+// matching response. The entry is removed on every completion or disconnect.
+const pendingAgentQuestions = new Map();
+
+function interactionKey(sessionId, interactionId) {
+  return `${String(sessionId)}:${String(interactionId)}`;
+}
+
+export function waitForAgentAnswer({ sessionId, interactionId, question, options, allowFreeText, send, signal }) {
+  const key = interactionKey(sessionId, interactionId);
+  return new Promise((resolve) => {
+    let settled = false;
+    const cleanup = () => {
+      pendingAgentQuestions.delete(key);
+      signal?.removeEventListener?.('abort', onAbort);
+    };
+    const settle = (answer) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(answer);
+    };
+    const onAbort = () => settle('Cancelled by user; the question was not answered.');
+
+    pendingAgentQuestions.set(key, {
+      question,
+      options,
+      allowFreeText,
+      settle,
+    });
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    send({ type: 'ask_user', interactionId, question, options, allowFreeText });
+    if (signal?.aborted) onAbort();
+  });
+}
+
+export function submitAgentAnswer({ sessionId, interactionId, answer }) {
+  const key = interactionKey(sessionId, interactionId);
+  const pending = pendingAgentQuestions.get(key);
+  if (!pending) return { ok: false, status: 404, error: 'No pending question for this session.' };
+
+  const value = String(answer || '').trim();
+  if (!value) return { ok: false, status: 400, error: 'Answer cannot be empty.' };
+  if (!pending.allowFreeText && pending.options.length > 0 && !pending.options.includes(value)) {
+    return { ok: false, status: 400, error: 'Choose one of the listed options.' };
+  }
+  pending.settle(value);
+  return { ok: true };
+}
+
 /**
  * 注册智能体路由。
  * @param {Object} deps
@@ -54,6 +106,13 @@ function sessionBelongsTo(sessionCwd, projectCwd) {
  */
 export function registerAgentRoutes({ app, getCurrentProjectPath, configManager }) {
 
+  registerAgentMarketplaceRoutes({ app, getCurrentProjectPath });
+
+  // list_projects 的数据源。在这里建一次、复用:它要读最近目录(配置)、tasks.json
+  // 与看板统计,这些依赖只有本层拿得到 —— 与 taskRunner 的 setEnvContextProvider 同理。
+  // 不给它加缓存:agent 一轮里最多问一两次,而"项目状态"本来就要现读才准。
+  const listProjects = createProjectListProvider({ configManager, getCurrentProjectPath });
+
   // ════════════════════════════════════════════════════════════════════════
   // §1. 会话列表
   // ════════════════════════════════════════════════════════════════════════
@@ -93,6 +152,22 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
     res.json({ success: true, session });
   }));
 
+  // Submit the answer for an ask_user tool call while its SSE request is paused.
+  app.post('/api/agent/respond', async (req, res) => {
+    const sessionId = String(req.body?.sessionId || '').trim();
+    const interactionId = String(req.body?.interactionId || '').trim();
+    if (!sessionId || !interactionId) {
+      return res.status(400).json({ success: false, error: 'Missing sessionId or interactionId.' });
+    }
+    const result = submitAgentAnswer({
+      sessionId,
+      interactionId,
+      answer: req.body?.answer,
+    });
+    if (!result.ok) return res.status(result.status).json({ success: false, error: result.error });
+    return res.json({ success: true });
+  });
+
   // ════════════════════════════════════════════════════════════════════════
   // §5. SSE 流式聊天（含工具调用循环）
   // ════════════════════════════════════════════════════════════════════════
@@ -225,7 +300,17 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         locale,
         signal: abortController.signal,
         send,
-        onChild: (child) => { activeChild = child; }
+        onChild: (child) => { activeChild = child; },
+        askUser: (args, meta = {}) => waitForAgentAnswer({
+          sessionId: session.sessionId,
+          interactionId: meta.interactionId,
+          question: args.question,
+          options: Array.isArray(args.options) ? args.options : [],
+          allowFreeText: args.allowFreeText !== false,
+          send,
+          signal: abortController.signal,
+        }),
+        listProjects
       });
 
       if (aborted) {

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

@@ -1,7 +1,56 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
-import { registerAgentRoutes } from './agentRoutes.js';
+import { registerAgentRoutes, waitForAgentAnswer } from './agentRoutes.js';
+
+test('agent respond resolves a pending ask_user question and validates answers', async () => {
+  let respondHandler;
+  const app = {
+    get() {},
+    delete() {},
+    put() {},
+    post(route, handler) {
+      if (route === '/api/agent/respond') respondHandler = handler;
+    }
+  };
+  registerAgentRoutes({
+    app,
+    getCurrentProjectPath: () => path.resolve('active-project'),
+    configManager: null
+  });
+
+  const sent = [];
+  const pending = waitForAgentAnswer({
+    sessionId: 'session-test',
+    interactionId: 'call-test',
+    question: 'Pick one',
+    options: ['A', 'B'],
+    allowFreeText: false,
+    send: event => sent.push(event),
+  });
+  await new Promise(resolve => setImmediate(resolve));
+  assert.deepEqual(sent, [{ type: 'ask_user', interactionId: 'call-test', question: 'Pick one', options: ['A', 'B'], allowFreeText: false }]);
+
+  let statusCode = 200;
+  let responseBody;
+  const response = {
+    status(code) { statusCode = code; return this; },
+    json(body) { responseBody = body; return body; },
+  };
+  await respondHandler({ body: { sessionId: 'session-test', interactionId: 'call-test', answer: 'C' } }, response);
+  assert.equal(statusCode, 400);
+  assert.equal(responseBody.success, false);
+
+  statusCode = 200;
+  await respondHandler({ body: { sessionId: 'session-test', interactionId: 'call-test', answer: 'B' } }, response);
+  assert.equal(statusCode, 200);
+  assert.deepEqual(responseBody, { success: true });
+  assert.equal(await pending, 'B');
+
+  await respondHandler({ body: { sessionId: 'session-test', interactionId: 'call-test', answer: 'B' } }, response);
+  assert.equal(statusCode, 404);
+  assert.equal(responseBody.success, false);
+});
 
 test('agent chat rejects a cwd that differs from the active server project', async () => {
   let chatHandler;