zen-gitsync 2.16.51 → 2.17.1

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

@@ -27,7 +27,7 @@
 //
 // 设计要点：
 //   - 路径归一与前端 utils/path.ts 的 canonicalProjectPath 必须**逐字一致**
-//     （盘符转大写 + Windows 斜杠归一）；两边口径一旦分叉，
+//     （Windows 形式转小写 + 斜杠归一）；两边口径一旦分叉，
 //     同一个目录会在两侧落到不同 key 上，表现为项目凭空分裂成两个。
 //   - 任务落在哪一列由 deriveTaskColumn 统一推导，是纯函数、单测覆盖；
 //     前端不重复实现这套规则，避免两边口径漂移。
@@ -36,27 +36,41 @@
 import { probeDirectoryGitStates } from '../../utils/directoryGitState.js';
 
 /** 看板列，数组顺序即列顺序 */
-export const TASK_COLUMNS = ['todo', 'doing', 'review', 'done'];
+export const TASK_COLUMNS = ['todo', 'doing', 'done'];
 
 /** 没有关联任何项目的任务归到这个 key（与前端 useWorkbenchProjectGroups 一致） */
 export const NO_PROJECT_KEY = '__no_project__';
 
 /**
  * 项目路径归一。与前端 src/ui/client/src/utils/path.ts 的 canonicalProjectPath 同口径：
- * Windows 形式（带盘符）→ 盘符转大写 + 反斜杠归一；其余（POSIX）原样返回。
+ * Windows 形式（带盘符）→ 转小写 + 反斜杠归一；其余（POSIX）原样返回。
  *
  * 为什么必须归斜杠：常用目录允许用户手输，同一个目录会同时存在 `D:/ws/proj`
  * 与 `D:\ws\proj` 两种写法。文件系统不区分，字符串比较却会 ——
  * 于是项目列表里出现两个同名项目（实测 article-generator 就是如此）。
  * 归一是修一个看得见的重复项，不是顺手清理。
  *
- * 刻意**不**做去尾斜杠 / 全小写 / 展开 `..`：那会把比较规则变得依赖文件系统语义，
- * 而这里只承诺"同一目录的常见书写差异归一到同一个 key"。
+ * 为什么必须归**大小写**（2026-09-18 补，同一类问题的第二张脸）：
+ * 只归斜杠治不了目录段的大小写。`recentDirectories` 存的是用户输入时的**原始写法**
+ * （`saveRecentDirectory` 只用 normalizeProjectPath 做去重比较，落盘仍写原串），
+ * 而任务的 `projectPath` 来自别处 —— 于是同一个目录会以 `c:\users\xuze3`
+ * （常用目录里手输的小写盘符）和 `C:\Users\xuze3`（任务带出来的）两种形态并存，
+ * 拿到两个 key、渲染成两条项目行。
+ *
+ * 关键在于**小写化必须做进 key 本身**，而不是在每处比较之前各自归一：key 会被拿去
+ * `stats.get(key)` 精确查表、比 `← 当前` 标记、比派发目标、比前端选中的项目 ——
+ * 只要有一处忘了先归一，同一目录就又会裂成两条。统一收在这里，调用方拿到的 key
+ * 天然可跨写法相等比较。（Windows 文件系统不区分大小写，小写化不会把两个真目录并成一个；
+ * 与之对应的 config.js 项目键 `normalizeProjectPath` 也是全小写的，方向一致。）
+ *
+ * 刻意**不**做去尾斜杠 / 展开 `..` / 解析符号链接：那会把比较规则变得依赖文件系统语义。
+ * 小写化是这条底线上唯一的例外，但它是**纯字符串**操作（只看 `X:` 这个形状，不看
+ * process.platform），没有引入任何 fs 依赖 —— 底线还在。
  */
 export function canonicalProjectPath(p) {
   const s = String(p || '').trim();
   if (!/^[a-zA-Z]:/.test(s)) return s;
-  return s.replace(/^([a-z])(?=:)/, (m) => m.toUpperCase()).replace(/\//g, '\\');
+  return s.replace(/\//g, '\\').toLowerCase();
 }
 
 /** 目录名（项目显示名），路径为空时返回空串而不是兜底文案（文案归前端 i18n 管） */
@@ -116,14 +130,14 @@ export function latestJob(jobsForTask) {
  *   1. 有 job 处于 running/pending，或子任务状态是 running → `doing`
  *   2. 有子任务且全部 done → `done`
  *   3. 有子任务但没全 done：
- *        - 动过（有 done 的子任务 / 执行过 / 有 error 的子任务）→ `review`（跑过但没收尾，等你确认或继续）
+ *        - 动过（有 done 的子任务 / 执行过 / 有 error 的子任务）→ `todo`
  *        - 完全没动过 → `todo`
  *   4. 没子任务（简单任务，或还没拆分的复杂任务）：
  *        - 从没执行过 → `todo`
- *        - 最近一条 job 是 done → `done`；其余终态（error/cancelled）→ `review`
+ *        - 最近一条 job 是 done → `done`；其余终态（error/cancelled）→ `todo`
  *
- * 之所以不把 error 单列一列：列是"任务处于哪个阶段"，error 是"这一轮执行失败了"，
- * 失败的任务同样需要人看一眼，归到 `review`，具体错误在前端卡片上另有标记。
+ * error/cancelled 不再单列：列表示任务是否仍待处理，错误是这一轮执行的结果，
+ * 具体错误继续通过卡片标记和任务详情展示。
  */
 export function deriveTaskColumn(task, jobsForTask = []) {
   const subs = Array.isArray(task && task.subtasks) ? task.subtasks : [];
@@ -135,19 +149,18 @@ export function deriveTaskColumn(task, jobsForTask = []) {
   if (subs.length > 0) {
     const doneCount = subs.filter(s => s && s.status === 'done').length;
     if (doneCount === subs.length) return 'done';
-    const touched = doneCount > 0 || jobs.length > 0 || subs.some(s => s && s.status === 'error');
-    return touched ? 'review' : 'todo';
+    return 'todo';
   }
 
   if (jobs.length === 0) return 'todo';
   const last = latestJob(jobs);
-  return last && last.status === 'done' ? 'done' : 'review';
+  return last && last.status === 'done' ? 'done' : 'todo';
 }
 
 /** 空统计，避免各处手写零值 */
 function emptyStats() {
   return {
-    total: 0, todo: 0, doing: 0, review: 0, done: 0,
+    total: 0, todo: 0, doing: 0, done: 0,
     progress: 0, runningJobs: 0, errorSubtasks: 0, lastActiveAt: null,
   };
 }
@@ -203,7 +216,13 @@ export function summarizeProjectTasks(tasks, jobs) {
 
 /**
  * 合并最近目录与任务里的 projectPath，得到去重后的项目条目。
- * path 取"首次出现的写法"（先最近目录、后任务），前端可以直接拿它跟其它列表对齐。
+ * path 取"首次出现的写法"（先最近目录内部按原顺序、再任务），前端可以直接拿它跟其它列表对齐。
+ *
+ * ⚠️ "首次出现"要显式实现，不能靠 `map.set` 覆盖：常用目录里同一个目录
+ * 出现两种写法是常态（`c:\users\xuze3` 与 `C:\Users\xuze3`），
+ * 无脑 set 会让**最后一条**写法覆盖前面那条 —— 既违背上面这句约定
+ * （界面上的路径会随常用目录顺序来回跳），也会把先命中过的 fromTasks 抹掉，
+ * 让 `source` 从 'both' 退化成 'recent'。
  *
  * @param {{ recentDirs?: string[], tasks?: object[] }} input
  * @returns {Array<{ path: string, key: string, name: string, source: 'recent'|'task'|'both' }>}
@@ -213,7 +232,9 @@ export function buildProjectEntries({ recentDirs = [], tasks = [] } = {}) {
   for (const dir of recentDirs) {
     const key = canonicalProjectPath(dir);
     if (!key) continue;
-    map.set(key, { path: String(dir).trim(), key, inRecent: true, fromTasks: false });
+    const hit = map.get(key);
+    if (hit) hit.inRecent = true; // 同一目录的第二种写法：只并入来源，不覆盖 path
+    else map.set(key, { path: String(dir).trim(), key, inRecent: true, fromTasks: false });
   }
   for (const t of tasks) {
     const key = canonicalProjectPath(t && t.projectPath);

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

@@ -40,15 +40,27 @@ const job = (id, taskId, status, startedAt, endedAt = null) => ({
 
 // ── 路径归一 ────────────────────────────────────────────────────────
 
-test('canonicalProjectPath: 盘符转大写 + Windows 斜杠归一（与前端同口径）', () => {
-  assert.equal(canonicalProjectPath('e:\\workspace\\x'), 'E:\\workspace\\x');
-  assert.equal(canonicalProjectPath('  D:/ws/y  '), 'D:\\ws\\y');
+test('canonicalProjectPath: Windows 形式转小写 + 斜杠归一（与前端同口径）', () => {
+  assert.equal(canonicalProjectPath('e:\\workspace\\x'), 'e:\\workspace\\x');
+  assert.equal(canonicalProjectPath('E:\\Workspace\\X'), 'e:\\workspace\\x');
+  assert.equal(canonicalProjectPath('  D:/ws/y  '), 'd:\\ws\\y');
   // 同一目录的两种斜杠写法必须落到同一个 key，否则项目列表里出现重复项
   // （实测 article-generator 就同时存在于 D:/... 与 D:\... 两种常用目录里）
   assert.equal(canonicalProjectPath('D:/ws/y'), canonicalProjectPath('D:\\ws\\y'));
-  // POSIX 路径原样返回，不能被改写成反斜杠
+  // 目录段大小写也必须归一：常用目录里手输的 c:\users\xuze3 与任务带出的
+  // C:\Users\xuze3 是同一个目录，旧口径只转盘符 → 左栏两条同名项目。
+  assert.equal(
+    canonicalProjectPath('C:\\Users\\xuze3'),
+    canonicalProjectPath('c:\\users\\xuze3'),
+  );
+  // 小写化是**纯字符串**规则，只看 `X:` 这个形状，不看 process.platform ——
+  // 所以 Windows 形态的断言在任何平台上都成立（POSIX 上跑测试也守得住）。
+  assert.equal(canonicalProjectPath('C:\\Users\\xuze3'), 'c:\\users\\xuze3');
+  // POSIX 路径原样返回，**不能**被小写化，也不能被改写成反斜杠：
+  // /home/Me/A 与 /home/me/a 是两个真目录，归一就是数据错误
   assert.equal(canonicalProjectPath('/home/me/proj'), '/home/me/proj');
   assert.equal(canonicalProjectPath('/home/me/proj/nested'), '/home/me/proj/nested');
+  assert.equal(canonicalProjectPath('/home/Me/A'), '/home/Me/A');
   assert.equal(canonicalProjectPath(''), '');
   assert.equal(canonicalProjectPath(null), '');
 });
@@ -84,16 +96,16 @@ test('deriveTaskColumn: 有 job 在跑或子任务 running 就是进行中', ()
 
 test('deriveTaskColumn: 子任务全部完成才算已完成', () => {
   assert.equal(deriveTaskColumn({ subtasks: [sub('s1', 'done'), sub('s2', 'done')] }, []), 'done');
-  // 一半完成 → 跑过但没收尾，落在评审中
-  assert.equal(deriveTaskColumn({ subtasks: [sub('s1', 'done'), sub('s2', 'todo')] }, []), 'review');
+  // 一半完成 → 仍待处理，错误与进度由卡片标记展示
+  assert.equal(deriveTaskColumn({ subtasks: [sub('s1', 'done'), sub('s2', 'todo')] }, []), 'todo');
   // 有子任务报错也算"需要人看一眼"
-  assert.equal(deriveTaskColumn({ subtasks: [sub('s1', 'error'), sub('s2', 'todo')] }, []), 'review');
+  assert.equal(deriveTaskColumn({ subtasks: [sub('s1', 'error'), sub('s2', 'todo')] }, []), 'todo');
 });
 
 test('deriveTaskColumn: 无子任务的任务只能看执行记录', () => {
   assert.equal(deriveTaskColumn({ subtasks: [], type: 'simple' }, [job('j1', 't1', 'done', '2026-01-01T00:00:00Z')]), 'done');
-  assert.equal(deriveTaskColumn({ subtasks: [], type: 'simple' }, [job('j1', 't1', 'cancelled', '2026-01-01T00:00:00Z')]), 'review');
-  assert.equal(deriveTaskColumn({ subtasks: [], type: 'simple' }, [job('j1', 't1', 'error', '2026-01-01T00:00:00Z')]), 'review');
+  assert.equal(deriveTaskColumn({ subtasks: [], type: 'simple' }, [job('j1', 't1', 'cancelled', '2026-01-01T00:00:00Z')]), 'todo');
+  assert.equal(deriveTaskColumn({ subtasks: [], type: 'simple' }, [job('j1', 't1', 'error', '2026-01-01T00:00:00Z')]), 'todo');
 });
 
 test('latestJob 按 startedAt 取最新的一条', () => {
@@ -107,7 +119,7 @@ test('latestJob 按 startedAt 取最新的一条', () => {
 
 // ── 项目合并去重 ────────────────────────────────────────────────────
 
-test('buildProjectEntries: 最近目录与任务路径取并集去重，盘符大小写归一', () => {
+test('buildProjectEntries: 最近目录与任务路径取并集去重，大小写与斜杠都归一', () => {
   const entries = buildProjectEntries({
     recentDirs: ['e:\\ws\\proj-a', 'D:\\ws\\proj-b'],
     tasks: [
@@ -118,10 +130,43 @@ test('buildProjectEntries: 最近目录与任务路径取并集去重，盘符
   });
   const byKey = new Map(entries.map(e => [e.key, e]));
   assert.equal(entries.length, 3);
-  assert.equal(byKey.get('E:\\ws\\proj-a').source, 'both');
-  assert.equal(byKey.get('D:\\ws\\proj-b').source, 'recent');
-  assert.equal(byKey.get('D:\\ws\\proj-c').source, 'task');
-  assert.equal(byKey.get('D:\\ws\\proj-c').name, 'proj-c');
+  assert.equal(byKey.get('e:\\ws\\proj-a').source, 'both');
+  assert.equal(byKey.get('d:\\ws\\proj-b').source, 'recent');
+  assert.equal(byKey.get('d:\\ws\\proj-c').source, 'task');
+  assert.equal(byKey.get('d:\\ws\\proj-c').name, 'proj-c');
+  // path 保留首次出现的原始写法（前端要拿它跟其它列表对齐、也要显示出来），
+  // 只有 key 被归一 —— 别顺手把 path 也小写了
+  assert.equal(byKey.get('d:\\ws\\proj-b').path, 'D:\\ws\\proj-b');
+});
+
+test('buildProjectEntries: 目录段大小写不同也是同一个项目（旧口径会裂成两条）', () => {
+  // 复现现场：常用目录里手输的小写盘符（saveRecentDirectory 落盘原始串）
+  // + 任务带出的 C:\Users\xuze3 —— 旧口径只转盘符，这里会得到两条 "xuze3"。
+  const entries = buildProjectEntries({
+    recentDirs: ['c:\\users\\xuze3'],
+    tasks: [{ id: 't1', projectPath: 'C:\\Users\\xuze3' }],
+  });
+  assert.equal(entries.length, 1, '同一目录的不同大小写写法不应分裂成两个项目');
+  assert.equal(entries[0].key, 'c:\\users\\xuze3');
+  assert.equal(entries[0].source, 'both', '应当被认成"既在常用目录、又有任务"，而不是两个项目');
+  assert.equal(entries[0].name, 'xuze3');
+  // 项目行只认这个 key 的任务，key 分叉会连带把任务计数拆到两行上去
+  const stats = summarizeProjectTasks(
+    [{ id: 't1', projectPath: 'C:\\Users\\xuze3', subtasks: [] }],
+    [],
+  );
+  assert.equal(stats.get('c:\\users\\xuze3').total, 1);
+  assert.equal(stats.size, 1);
+
+  // 常用目录里同一个目录也可能历史累积出两种写法。此时只留**首次**那条：
+  // 否则界面上的路径会随常用目录的顺序跳变，`source` 也会从 both 退化掉。
+  const dup = buildProjectEntries({
+    recentDirs: ['C:\\Users\\xuze3', 'c:/users/xuze3'],
+    tasks: [{ id: 't1', projectPath: 'c:\\users\\xuze3' }],
+  });
+  assert.equal(dup.length, 1);
+  assert.equal(dup[0].path, 'C:\\Users\\xuze3', 'path 应取首次出现的写法');
+  assert.equal(dup[0].source, 'both', '重复的第二种写法不该抹掉已命中的来源');
 });
 
 test('summarizeProjectTasks: 按项目汇总列数量、进度、活跃执行与最后活跃时间', () => {
@@ -139,7 +184,7 @@ test('summarizeProjectTasks: 按项目汇总列数量、进度、活跃执行与
   ];
   const stats = summarizeProjectTasks(tasks, jobs);
 
-  const a = stats.get('D:\\a');
+  const a = stats.get('d:\\a');
   assert.equal(a.total, 2);
   assert.equal(a.done, 1);
   assert.equal(a.doing, 1);
@@ -148,7 +193,7 @@ test('summarizeProjectTasks: 按项目汇总列数量、进度、活跃执行与
   // 最后活跃时间要把 job 的起止也算进来（任务体本身可能很久没改）
   assert.equal(a.lastActiveAt, '2026-01-04T00:00:00Z');
 
-  const b = stats.get('D:\\b');
+  const b = stats.get('d:\\b');
   assert.equal(b.total, 1);
   assert.equal(b.todo, 1);
   assert.equal(b.progress, 0);
@@ -163,7 +208,7 @@ test('decorateTaskForBoard: 只回卡片需要的字段', () => {
     attachments: [{ id: 'at1' }],
     createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-02T00:00:00Z',
   }, []);
-  assert.equal(card.column, 'review');
+  assert.equal(card.column, 'todo');
   assert.equal(card.type, 'complex');
   assert.equal(card.subtaskCount, 2);
   assert.equal(card.subtaskDoneCount, 1);

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

@@ -25,12 +25,17 @@ import fsp from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import logger from '../../utils/logger.js';
+import { DATA_DIR } from '../../../../paths.js';
 
 // ── 数据目录与持久化文件路径 ─────────────────────────────────
-// 全部存在用户主目录 ~/.zen-gitsync/ 下，跨项目共享
-export const DATA_DIR = path.join(os.homedir(), '.zen-gitsync');
+// 全部存在用户主目录 ~/.zen-gitsync/ 下，跨项目共享。
+// 目录本身定义在 src/paths.js(全部数据路径的唯一真相源)，这里只在其下拼文件名。
+export { DATA_DIR };
 export const PROMPTS_FILE = path.join(DATA_DIR, 'prompts.json');
 export const TASKS_FILE = path.join(DATA_DIR, 'tasks.json');
+// 应用主配置（projects / recentDirectories / models …）。这里只用来把**路径**告诉 Agent，
+// 让它需要时自己读 —— 服务端不在这个流程里解析配置内容。
+export const CONFIG_FILE = path.join(DATA_DIR, 'config.json');
 export const IMAGES_DIR = path.join(DATA_DIR, 'workbench-images');
 export const INSTRUCTION_FILE = path.join(DATA_DIR, 'ai-instruction.json');
 export const SUBTASK_INSTRUCTION_FILE = path.join(DATA_DIR, 'ai-subtask-instruction.json');

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

@@ -0,0 +1,260 @@
+// 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.
+//
+// 「这条指令该落到哪个项目」—— 全局唯一实现。
+//
+// 在调度台上敲一条指令时，用户不必先选项目：落到哪由这里决定。四级优先级，
+// 从「最确定的意图」往下退：
+//
+//   1. explicit —— 调用方明确指定（用户在左栏选中了具体项目）。
+//      显式意图永远最优先，不做任何"更聪明"的覆盖，否则用户会发现
+//      「我明明选了它，却派到别处去了」。
+//   2. mention  —— 指令原文里点名的项目（名字或完整路径）。纯字符串匹配，
+//      零延迟零成本，覆盖「给 article-generator 加个功能」这类绝大多数写法。
+//   3. agent    —— 交给模型判断。只有前两级都没命中才走这里（要等一次网络往返）；
+//      失败、超时、编了个不存在的路径 —— 一律静默降级，绝不阻塞派发。
+//   4. default  —— 都没命中，用调用方给的默认项目（应用当前项目）。
+//
+// 返回值里的 source 是给 UI 用的：让界面能如实说明「这个落点是怎么来的」。
+// 判错了的时候，用户至少知道该怪谁 —— 是模型猜的，还是压根没识别出来。
+//
+// 纯逻辑 + 单次可注入的模型调用，单测不碰网络（见 targetResolver.test.js）。
+
+import { canonicalProjectPath, projectName } from './projectRegistry.js';
+import { callLlmJson } from './llmClient.js';
+
+/** 落点来源。UI 按它选文案，服务端不写死任何面向界面的中文 */
+export const TARGET_SOURCE = {
+  EXPLICIT: 'explicit',
+  MENTION: 'mention',
+  AGENT: 'agent',
+  DEFAULT: 'default',
+};
+
+export const TARGET_SOURCES = Object.values(TARGET_SOURCE);
+
+/** 算作「词内字符」的集合：出现在 token 两侧就说明它只是某个长词的一部分 */
+const WORD_CHAR = /[a-z0-9_-]/i;
+
+/**
+ * 在 text 里找 token 的「成词」出现位置，找不到返回 -1。
+ *
+ * 为什么非要卡边界：项目名经常互为前缀 —— 清单里同时有 `claw-management`
+ * 与 `claw-management-api`、`claw-sdd` 与 `claw-sdd-project`。
+ * 光用 includes/indexOf，指令里写 `claw-management-api` 会先命中 `claw-management`，
+ * 改动就落到隔壁项目去了。
+ */
+export function indexOfToken(text, token) {
+  const needle = String(token || '');
+  if (!needle) return -1;
+  const hay = String(text || '').toLowerCase();
+  const low = needle.toLowerCase();
+  let from = 0;
+  for (;;) {
+    const i = hay.indexOf(low, from);
+    if (i < 0) return -1;
+    const before = i > 0 ? hay[i - 1] : '';
+    const after = i + low.length < hay.length ? hay[i + low.length] : '';
+    if (!WORD_CHAR.test(before) && !WORD_CHAR.test(after)) return i;
+    from = i + 1;
+  }
+}
+
+/**
+ * 规则匹配：指令原文里点名的项目。
+ *
+ * 优先级：完整路径（rank 3）> 项目名成词出现（rank 2）。
+ * 同级里取「匹配到的 token 更长」的那个 —— 更长即更具体，
+ * 用来压住 `claw-management` / `claw-management-api` 这类同族名。
+ *
+ * @param {string} text           指令原文
+ * @param {object[]} projects     buildProjectEntries 的输出（{name, path, key}）
+ * @returns {{ project: object, matched: string } | null}
+ */
+export function matchProjectMention(text, projects) {
+  const src = String(text || '');
+  if (!src) return null;
+  const list = (Array.isArray(projects) ? projects : []).filter(p => p && p.key && p.path);
+  if (!list.length) return null;
+
+  const lower = src.toLowerCase();
+  let best = null;
+
+  for (const p of list) {
+    const path = String(p.path || '').trim();
+    const name = String(p.name || projectName(path)).trim();
+
+    let matched = '';
+    let rank = 0;
+    if (path && lower.includes(path.toLowerCase())) {
+      // 完整路径是最强信号：肯把路径敲全的人不会是在打比方
+      matched = path;
+      rank = 3;
+    } else if (name && indexOfToken(lower, name) >= 0) {
+      matched = name;
+      rank = 2;
+    }
+    if (!matched) continue;
+
+    if (!best || rank > best.rank || (rank === best.rank && matched.length > best.matched.length)) {
+      best = { project: p, matched, rank };
+    }
+  }
+
+  return best ? { project: best.project, matched: best.matched } : null;
+}
+
+/**
+ * 让模型判断落点（第 3 级）。
+ *
+ * 只在规则匹配不到时调用。返回的路径**必须是清单里真实存在的那一条**：
+ * 模型编出来的路径一律当作"没判断出来"。宁可退到默认项目，
+ * 也不能凭空造一个不存在的工作目录 —— 那会让派发在下一步直接报「项目目录不存在」，
+ * 用户看到的是"派发失败"，比"派到默认项目"难懂得多。
+ *
+ * @returns {{ project: object, reason: string } | null}
+ */
+export async function pickProjectByAgent({
+  text,
+  projects,
+  model,
+  timeoutMs = 15000,
+  // 注入点：单测靠它替换掉真实网络调用（默认就是 callLlmJson）
+  callJson = callLlmJson,
+} = {}) {
+  const list = (Array.isArray(projects) ? projects : []).filter(p => p && p.key && p.path);
+  if (!model || !list.length) return null;
+
+  const catalogue = list
+    .map((p, i) => `${i + 1}. ${p.name || projectName(p.path)} | ${p.path}`)
+    .join('\n');
+
+  const prompt = `你在「多项目编排台」里做一次路由判断：用户刚发了一条指令，请判断它应该在下面哪个项目里执行。
+
+可选项目（序号. 名称 | 绝对路径）：
+${catalogue}
+
+指令原文：
+"""
+${String(text || '').slice(0, 2000)}
+"""
+
+判断规则：
+1. 指令直接提到某个项目名或路径 —— 选它。
+2. 指令描述的内容明显属于某个项目（例如"修一下文章生成器的导出"对应 article-generator，如果它在上面）—— 选它。
+3. 只要不能确定，就返回空字符串。**不要猜**：猜错的代价是把改动做到错误的仓库里，比退到默认项目严重得多。
+
+只返回 JSON：
+{
+  "projectPath": "选中的项目绝对路径，必须是上面列出的路径原样复制；不确定就填空字符串",
+  "reason": "一句话说明依据"
+}`;
+
+  const out = await callJson(model, prompt, { timeoutMs });
+  const picked = canonicalProjectPath(out && out.projectPath ? out.projectPath : '');
+  if (!picked) return null;
+  const hit = list.find(p => p.key === picked);
+  if (!hit) return null;
+  return { project: hit, reason: String((out && out.reason) || '').slice(0, 200) };
+}
+
+/**
+ * 解析指令的落点项目。
+ *
+ * @param {object}   input
+ * @param {string}   input.text         指令原文
+ * @param {object[]} input.projects     候选项目（{name, path, key}）
+ * @param {string}   input.explicitPath 调用方显式指定的路径（空 = 没指定，走判断）
+ * @param {string}   input.defaultPath  兜底路径（一般是应用当前项目）
+ * @param {function} [input.getModel]   懒取模型配置。**只有真的要走第 3 级时才会被调用** ——
+ *                                      常见情况（指令里点名了项目）不该为读一次 config 付成本
+ * @param {number}   [input.agentTimeoutMs]
+ * @param {function} [input.onAgentError] 模型判断失败时的回调（调用方记日志用）。
+ *                                        不抛错：判断失败不该让整条指令派不出去
+ * @param {function} [input.pickByAgent]  注入点：单测替换第 3 级，避免真发网络请求
+ * @returns {Promise<{ path: string, name: string, source: string, matched: string, reason: string }>}
+ */
+export async function resolveInstructionTarget({
+  text = '',
+  projects = [],
+  explicitPath = '',
+  defaultPath = '',
+  getModel = null,
+  agentTimeoutMs = 15000,
+  onAgentError = null,
+  pickByAgent = pickProjectByAgent,
+} = {}) {
+  const list = (Array.isArray(projects) ? projects : [])
+    .filter(p => p && p.key && p.path)
+    .map(p => ({ ...p, name: p.name || projectName(p.path) }));
+  const byKey = new Map(list.map(p => [p.key, p]));
+
+  // ── 1. 显式指定 ──────────────────────────────────────────────────
+  const explicit = String(explicitPath || '').trim();
+  if (explicit) {
+    const hit = byKey.get(canonicalProjectPath(explicit));
+    return {
+      path: hit ? hit.path : explicit,
+      name: hit ? hit.name : projectName(explicit),
+      source: TARGET_SOURCE.EXPLICIT,
+      matched: '',
+      reason: '',
+    };
+  }
+
+  // ── 2. 指令原文里点名 ────────────────────────────────────────────
+  const mention = matchProjectMention(text, list);
+  if (mention) {
+    return {
+      path: mention.project.path,
+      name: mention.project.name,
+      source: TARGET_SOURCE.MENTION,
+      matched: mention.matched,
+      reason: '',
+    };
+  }
+
+  // ── 3. 模型判断 ──────────────────────────────────────────────────
+  if (typeof getModel === 'function') {
+    try {
+      const model = await getModel();
+      if (model) {
+        const picked = await pickByAgent({ text, projects: list, model, timeoutMs: agentTimeoutMs });
+        if (picked) {
+          return {
+            path: picked.project.path,
+            name: picked.project.name,
+            source: TARGET_SOURCE.AGENT,
+            matched: '',
+            reason: picked.reason,
+          };
+        }
+      }
+    } catch (err) {
+      if (typeof onAgentError === 'function') onAgentError(err);
+    }
+  }
+
+  // ── 4. 默认项目 ──────────────────────────────────────────────────
+  const fallback = String(defaultPath || '').trim();
+  const def = byKey.get(canonicalProjectPath(fallback));
+  const defPath = def ? def.path : fallback;
+  return {
+    path: defPath,
+    name: def ? def.name : projectName(defPath),
+    source: TARGET_SOURCE.DEFAULT,
+    matched: '',
+    reason: '',
+  };
+}