dsh-dispatch-board 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.js CHANGED
@@ -5,14 +5,19 @@
5
5
  * 1. 在 webServer 上注册 /taskboard 前缀路由,用 Connection RPC 信封
6
6
  * ({type:'client-request', rpcId, method, payload} → {type:'server-response', rpcId, result})
7
7
  * 给浏览器端提供 snapshot / add-task / update-task / delete-task / dispatch-now /
8
- * set-config / archive-done / install-preset 八个端点;
8
+ * set-config / archive-done / install-preset / bind-main-session / clear-main-session /
9
+ * ensure-workspace-lead / upload-attachment / attachment 等端点;
9
10
  * 2. 持久化任务看板到 $DSH_HOME/storages/dsh-taskboard/board.json(原子写);
10
- * 3. 轮询「待开始」列:命中且目标主 Agent 空闲时,用 agent.followup() 推一条【任务看板】消息,
11
- * 主 Agent 据此派发子 Agent(本插件不直接起子 Agent——派单是主 Agent 的职责);
12
- * 4. 注册三个面向模型的工具:taskboard_list / taskboard_add / taskboard_update;
13
- * 5. 插件 bundle 自带两个模式声明(presets/taskboard.patch.yml 里的
11
+ * 3. 轮询「待开始」列(v0.2.0 默认 workspace-lead 模式):按任务工作区复用/懒创建常驻工作区组长
12
+ * (taskboard-dispatch 预设),用 agent.followup() 推一条【任务看板 · 待开始】消息;
13
+ * 组长据此派 taskboard-worker 子 Agent 干活并审核写回(本插件不直接起子 Agent);
14
+ * 4. 任务 done 且未汇报时,把完成回执合并成【任务看板 · 汇报】推给主会话(config.mainSessionId);
15
+ * 5. 注册三个面向模型的工具:taskboard_list / taskboard_add / taskboard_update;
16
+ * 6. 插件 bundle 自带两个模式声明(presets/taskboard.patch.yml 里的
14
17
  * @deepseek-ai/dsh-agent-preset 行:taskboard-dispatch 主 + taskboard-worker 执行者),
15
18
  * 随 Loader 组合加载;本文件只从 agentPresets 注册表读回实时状态给 UI。
19
+ * 7. v0.2.0 补充:工作区组长在直聊里被直接要求派活时,监听 tools/result 识别 subagent 派发、
20
+ * 监听 subagent/end 收尾,自动建 / 完结一条看板任务(§1.8;标准 tool-call 与 PTC 都覆盖)。
16
21
  *
17
22
  * 本文件顶层只 import node: 内建模块,不 import 任何 @deepseek-ai/*。
18
23
  * 原因:外部插件包的 profile node_modules 里没有 dsh-tools / dsh-llm,
@@ -22,10 +27,11 @@
22
27
  * 契约(字段/端点/状态机)以 docs/architecture.md 为唯一事实来源。
23
28
  */
24
29
 
30
+ import { Buffer } from 'node:buffer'
25
31
  import { randomUUID } from 'node:crypto'
26
32
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
27
33
  import { homedir } from 'node:os'
28
- import { dirname, join } from 'node:path'
34
+ import { dirname, join, resolve, sep } from 'node:path'
29
35
  import { fileURLToPath } from 'node:url'
30
36
 
31
37
  export const name = 'taskboard'
@@ -46,13 +52,53 @@ const RPC_CHANNEL = '/taskboard'
46
52
  const BOARD_VERSION = 1
47
53
  const STORAGE_DIRNAME = 'dsh-taskboard'
48
54
  const BOARD_FILENAME = 'board.json'
49
- const MAX_BODY_BYTES = 512 * 1024
55
+ export const MAX_BODY_BYTES = 512 * 1024
50
56
  const MIN_POLL_INTERVAL_MS = 5000
51
57
  const MAX_POLL_INTERVAL_MS = 300000
52
58
  const DEFAULT_POLL_INTERVAL_MS = 15000
53
59
  const DEFAULT_MAX_NOTIFICATIONS = 5
54
60
  const MAX_NOTE_CHARS = 4000
55
61
  const MAX_TITLE_CHARS = 200
62
+ /** 会话标题(主会话 / 工作区组长)最长字符数。 */
63
+ const SESSION_TITLE_MAX = 200
64
+ /** config.workspaceLeads 最多保存多少条工作区 → 组长映射(§2)。 */
65
+ const MAX_WORKSPACE_LEADS = 32
66
+ /** 完成回执每批最多合并多少条任务(§1.6)。 */
67
+ const MAX_RECEIPT_BATCH = 10
68
+ /** 完成回执里每条任务结论压成单行后的最大字符数(§1.6)。 */
69
+ const RECEIPT_RESULT_CHARS = 200
70
+
71
+ /* ------------------------------------------------------------------ *
72
+ * 粘贴图片附件(v0.2.0,§2.1)
73
+ * ------------------------------------------------------------------ */
74
+
75
+ const ATTACHMENT_DIRNAME = 'attachments'
76
+ const ATTACHMENT_INDEX_FILENAME = 'index.json'
77
+ const ATTACHMENT_INDEX_VERSION = 1
78
+ /** 解码后单张图片上限(§2.1)。 */
79
+ export const MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024
80
+ /** 单条任务 note 里最多几个不同附件引用(§2.1)。 */
81
+ export const MAX_TASK_ATTACHMENTS = 8
82
+ /** 允许的图片 MIME(与 DSH 附件服务 v1 白名单一致)。 */
83
+ export const ATTACHMENT_MEDIA_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
84
+ /** 上传端点单独放宽的请求体上限:base64 膨胀 4/3 + data URL 前缀 + JSON 外壳。 */
85
+ export const MAX_UPLOAD_BODY_BYTES = Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4 + 64 * 1024
86
+ const ATTACHMENT_EXTENSIONS = Object.freeze({ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' })
87
+ const ATTACHMENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
88
+ const ATTACHMENT_FILE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(png|jpg|webp|gif)$/
89
+ /** note 里的短引用:![image](attachment://<uuid>)。 */
90
+ const ATTACHMENT_REF_PATTERN = /!\[[^\]]*\]\(attachment:\/\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\)/g
91
+
92
+ /**
93
+ * §1.8 自动建任务的持久化标记:只有带这个标记的任务才会被 `subagent/end` 自动置 done。
94
+ * 轮询投递任务 / 人工任务恒为 null —— 组长把它们的 assignee 写成 worker 会话 id 也不会被宿主抢答。
95
+ */
96
+ export const LEAD_AUTO_MARK = 'lead-dispatch'
97
+ /**
98
+ * §1.8 in-flight 去重的陈旧窗口:组长名下「doing + notifiedAt」的轮询任务超过这个时长没有更新
99
+ * (worker 长跑 / 组长卡死)就不再挡住直聊派活——宁可多一条可见任务,也不让派活无声消失。
100
+ */
101
+ export const LEAD_IN_FLIGHT_TTL_MS = 30 * 60 * 1000
56
102
 
57
103
  /** 看板四列。顺序即 UI 列顺序。 */
58
104
  export const STATUSES = ['todo', 'doing', 'done', 'archived']
@@ -100,6 +146,41 @@ function trimmed(value, max) {
100
146
  return text.length > max ? text.slice(0, max) : text
101
147
  }
102
148
 
149
+ /** 丢掉被截断切开的图片引用尾巴(缺收尾 `)` / 缺 `]`,以及半个 `attachment://` 协议前缀)。 */
150
+ function stripPartialAttachmentRef(head) {
151
+ // 1) 引用 URL 被切断:`![alt](attachment://<uuid>` 没有收尾 `)`,整段丢掉。
152
+ const unclosedRef = /!\[[^\]]*\]\([^)]*$/.exec(head)
153
+ if (unclosedRef) return head.slice(0, unclosedRef.index)
154
+ // 2) 引用还没写到 `]`:`![ima`(截断点落在 alt / 协议前缀前段)。
155
+ const openRef = /!\[[^\]]*$/.exec(head)
156
+ if (openRef) return head.slice(0, openRef.index).replace(/\s+$/, '')
157
+ // 3) 兜底:尾巴是 `attachment://` 的半个协议前缀(裸引用,没走图片语法)。
158
+ const needle = 'attachment://'
159
+ for (let len = needle.length - 1; len >= 1; len -= 1) {
160
+ if (head.endsWith(needle.slice(0, len))) {
161
+ return head.slice(0, head.length - len).replace(/\s+$/, '')
162
+ }
163
+ }
164
+ // 4) 兜底:裸引用前缀完整、UUID 被切断(`see attachment://2222…-42`)——整段丢掉,
165
+ // 别把半截 id 留在 note / result 里变成坏链接;完整 UUID 照常保留。
166
+ const cutBareId = /attachment:\/\/[0-9a-f-]*$/.exec(head)
167
+ if (cutBareId && !ATTACHMENT_ID_PATTERN.test(cutBareId[0].slice(needle.length))) {
168
+ return head.slice(0, cutBareId.index).replace(/\s+$/, '')
169
+ }
170
+ return head
171
+ }
172
+
173
+ /**
174
+ * note / result 的 4000 字符截断(§2.1):**不得切出半截 `attachment://` 引用**。
175
+ * 截断点落在某个 `![...](attachment://<uuid>)` 内部时退到该引用开头再截——宁可少保留最后一个引用,
176
+ * 也不给详情浮层留坏链接(其余完整引用照常保留)。
177
+ */
178
+ export function truncateNote(text, max = MAX_NOTE_CHARS) {
179
+ const raw = typeof text === 'string' ? text.trim() : ''
180
+ if (raw.length <= max) return raw
181
+ return stripPartialAttachmentRef(raw.slice(0, max)).replace(/\s+$/, '')
182
+ }
183
+
103
184
  function isPlainObject(value) {
104
185
  return typeof value === 'object' && value !== null && !Array.isArray(value)
105
186
  }
@@ -152,14 +233,71 @@ export function createEmptyBoard() {
152
233
  pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
153
234
  maxNotifications: DEFAULT_MAX_NOTIFICATIONS,
154
235
  dispatchMode: DEFAULT_DISPATCH_MODE,
236
+ mainSessionId: null,
237
+ mainSessionTitle: '',
238
+ workspaceLeads: {},
155
239
  },
156
240
  tasks: [],
157
241
  }
158
242
  }
159
243
 
160
- /** 派发去处:新对话(默认)/ 回发起它的对话 / 自动挑空闲会话。 */
161
- export const DISPATCH_MODES = ['new', 'creator', 'auto']
162
- export const DEFAULT_DISPATCH_MODE = 'new'
244
+ /**
245
+ * 派发去处(v0.2.0):
246
+ * - workspace-lead(默认):按任务工作区投给该工作区的常驻组长(§1.5);
247
+ * - new / creator / auto:兼容旧模式(§1.7),已持久化的合法旧值原样保留。
248
+ */
249
+ export const DISPATCH_MODES = ['workspace-lead', 'new', 'creator', 'auto']
250
+ export const DEFAULT_DISPATCH_MODE = 'workspace-lead'
251
+
252
+ /**
253
+ * 规范化 config.workspaceLeads:普通对象,key 为工作区 id 或归一化 cwd;
254
+ * 条目要求 sessionId / cwd 均是非空字符串;非法条目丢弃;最多 32 条(按对象键顺序保留前 32)。
255
+ */
256
+ export function normalizeWorkspaceLeads(raw) {
257
+ const leads = {}
258
+ if (!isPlainObject(raw)) return leads
259
+ let kept = 0
260
+ for (const [key, value] of Object.entries(raw)) {
261
+ if (kept >= MAX_WORKSPACE_LEADS) break
262
+ if (typeof key !== 'string' || key === '') continue
263
+ if (!isPlainObject(value)) continue
264
+ const sessionId = typeof value.sessionId === 'string' ? value.sessionId.trim() : ''
265
+ const cwd = typeof value.cwd === 'string' ? value.cwd.trim() : ''
266
+ if (sessionId === '' || cwd === '') continue
267
+ leads[key] = {
268
+ sessionId,
269
+ title: trimmed(value.title, SESSION_TITLE_MAX),
270
+ cwd,
271
+ createdAt: typeof value.createdAt === 'string' ? value.createdAt : '',
272
+ }
273
+ kept += 1
274
+ }
275
+ return leads
276
+ }
277
+
278
+ /**
279
+ * 写一条工作区组长映射:键存在则原位更新;超过 32 条时优先淘汰对象键顺序末尾的旧键,
280
+ * 保证刚写入的新映射不会被下一次 normalizeConfig 丢弃(否则 tick 会每轮重复创建组长)。
281
+ */
282
+ export function putWorkspaceLead(leads, key, entry) {
283
+ const next = isPlainObject(leads) ? { ...leads } : {}
284
+ if (typeof key !== 'string' || key === '') return next
285
+ next[key] = entry
286
+ const keys = Object.keys(next)
287
+ while (keys.length > MAX_WORKSPACE_LEADS) {
288
+ let victim = ''
289
+ for (let i = keys.length - 1; i >= 0; i--) {
290
+ if (keys[i] !== key) {
291
+ victim = keys[i]
292
+ break
293
+ }
294
+ }
295
+ if (victim === '') break
296
+ delete next[victim]
297
+ keys.splice(keys.indexOf(victim), 1)
298
+ }
299
+ return next
300
+ }
163
301
 
164
302
  export function normalizeConfig(raw) {
165
303
  const config = isPlainObject(raw) ? raw : {}
@@ -176,6 +314,13 @@ export function normalizeConfig(raw) {
176
314
  Number.isFinite(maxNotifications) && maxNotifications >= 1 && maxNotifications <= 50
177
315
  ? Math.round(maxNotifications)
178
316
  : DEFAULT_MAX_NOTIFICATIONS,
317
+ // v0.2.0 完成回执收件人:未绑定 / 空白 = null。
318
+ mainSessionId: (() => {
319
+ const id = typeof config.mainSessionId === 'string' ? config.mainSessionId.trim() : ''
320
+ return id !== '' ? id : null
321
+ })(),
322
+ mainSessionTitle: trimmed(config.mainSessionTitle, SESSION_TITLE_MAX),
323
+ workspaceLeads: normalizeWorkspaceLeads(config.workspaceLeads),
179
324
  }
180
325
  }
181
326
 
@@ -188,16 +333,20 @@ function normalizeTask(raw, index) {
188
333
  return {
189
334
  id,
190
335
  title,
191
- note: trimmed(raw.note, MAX_NOTE_CHARS),
336
+ note: truncateNote(raw.note, MAX_NOTE_CHARS),
192
337
  status,
193
338
  source: raw.source === 'agent' ? 'agent' : 'user',
194
339
  sessionId: typeof raw.sessionId === 'string' && raw.sessionId !== '' ? raw.sessionId : null,
195
340
  // 最近一次投递给哪个会话(看板详情里「打开执行对话」用)。
196
341
  dispatchedSessionId: typeof raw.dispatchedSessionId === 'string' && raw.dispatchedSessionId !== '' ? raw.dispatchedSessionId : null,
197
342
  dispatchedSessionTitle: trimmed(raw.dispatchedSessionTitle, 200),
343
+ // v0.2.0 完成回执记账:null = 尚未把结论推给主会话;只在 board.json / Snapshot.tasks 出现。
344
+ reportedAt: asString(raw.reportedAt) || null,
345
+ // v0.2.0 自动建任务标记(§1.8):只有 'lead-dispatch' 合法,其它一律 null(= 普通任务)。
346
+ autoDispatch: raw.autoDispatch === LEAD_AUTO_MARK ? LEAD_AUTO_MARK : null,
198
347
  cwd: typeof raw.cwd === 'string' && raw.cwd !== '' ? raw.cwd : null,
199
348
  assignee: trimmed(raw.assignee, 200),
200
- result: trimmed(raw.result, MAX_NOTE_CHARS),
349
+ result: truncateNote(raw.result, MAX_NOTE_CHARS),
201
350
  createdAt: asString(raw.createdAt) || iso(Date.now()),
202
351
  updatedAt: asString(raw.updatedAt) || asString(raw.createdAt) || iso(Date.now()),
203
352
  startedAt: asString(raw.startedAt) || null,
@@ -289,6 +438,284 @@ export function commitBoard(state, filePath = boardPath()) {
289
438
  }
290
439
  }
291
440
 
441
+ /* ------------------------------------------------------------------ *
442
+ * 粘贴图片附件(v0.2.0,§2.1)
443
+ *
444
+ * 设计要点:
445
+ * - 优先复用 DSH 附件服务(ctx.attachments);服务不可用时退到本插件目录自建存储;
446
+ * - note 只存短引用 attachment://<uuid>,绝不存 base64(note 会进派单消息 / prompt);
447
+ * - id 是 randomUUID(不可猜);读取只按索引里的 id 查,不把用户输入拼进文件路径。
448
+ * ------------------------------------------------------------------ */
449
+
450
+ /** 附件目录:默认与 board.json 同级的 attachments/(即 $DSH_HOME/storages/dsh-taskboard/attachments)。 */
451
+ export function attachmentsDir() {
452
+ return join(dirname(boardPath()), ATTACHMENT_DIRNAME)
453
+ }
454
+
455
+ export function attachmentRef(id) {
456
+ return 'attachment://' + String(id)
457
+ }
458
+
459
+ /** 从 data URL 解出图片字节;校验 MIME 白名单、5 MB 上限与文件头。纯函数,便于单测。 */
460
+ export function decodeImageDataUrl(dataUrl) {
461
+ const text = typeof dataUrl === 'string' ? dataUrl.trim() : ''
462
+ const match = /^data:([a-z]+\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/]+={0,2})$/.exec(text)
463
+ if (!match) throw new BoardError('bad-request', '图片数据格式不合法:需要 data:<mime>;base64,<...>')
464
+ const mime = match[1].toLowerCase()
465
+ if (!ATTACHMENT_MEDIA_TYPES.includes(mime)) {
466
+ throw new BoardError('bad-request', '不支持的图片类型:' + mime + '(仅支持 png / jpeg / webp / gif)')
467
+ }
468
+ const base64 = match[2]
469
+ let bytes
470
+ try {
471
+ bytes = Buffer.from(base64, 'base64')
472
+ } catch {
473
+ throw new BoardError('bad-request', '图片 base64 解码失败')
474
+ }
475
+ // FileReader 产出的 data URL 是规范 base64;非规范形式(空白 / URL-safe 字符 / 多余填充)直接拒绝。
476
+ if (bytes.length === 0 || bytes.toString('base64') !== base64) {
477
+ throw new BoardError('bad-request', '图片 base64 不是规范编码')
478
+ }
479
+ if (bytes.length > MAX_ATTACHMENT_BYTES) {
480
+ throw new BoardError(
481
+ 'bad-request',
482
+ '图片超过大小上限:' + bytes.length + ' 字节(最多 ' + MAX_ATTACHMENT_BYTES + ' 字节 / 5 MB)',
483
+ { size: bytes.length, max: MAX_ATTACHMENT_BYTES },
484
+ )
485
+ }
486
+ const sniffed = sniffImageMime(bytes)
487
+ if (sniffed === '') throw new BoardError('bad-request', '无法识别的图片数据(文件头不是 png / jpeg / webp / gif)')
488
+ if (sniffed !== mime) throw new BoardError('bad-request', '图片内容与声明类型不一致:声明 ' + mime + ',实际 ' + sniffed)
489
+ return { mime, bytes }
490
+ }
491
+
492
+ /** 按 magic bytes 识别图片类型;识别不了返回空串。纯函数。 */
493
+ export function sniffImageMime(bytes) {
494
+ const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(0)
495
+ if (data.length >= 8 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47 && data[4] === 0x0d && data[5] === 0x0a && data[6] === 0x1a && data[7] === 0x0a) {
496
+ return 'image/png'
497
+ }
498
+ if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg'
499
+ if (data.length >= 6) {
500
+ const head = String.fromCharCode(data[0], data[1], data[2], data[3], data[4], data[5])
501
+ if (head === 'GIF87a' || head === 'GIF89a') return 'image/gif'
502
+ }
503
+ if (data.length >= 12) {
504
+ const riff = String.fromCharCode(data[0], data[1], data[2], data[3])
505
+ const webp = String.fromCharCode(data[8], data[9], data[10], data[11])
506
+ if (riff === 'RIFF' && webp === 'WEBP') return 'image/webp'
507
+ }
508
+ return ''
509
+ }
510
+
511
+ /** note 里不同附件引用的个数(同一 id 重复出现只算一个)。纯函数。 */
512
+ export function countAttachmentRefs(note) {
513
+ if (typeof note !== 'string' || note === '') return 0
514
+ const ids = new Set()
515
+ ATTACHMENT_REF_PATTERN.lastIndex = 0
516
+ let match
517
+ while ((match = ATTACHMENT_REF_PATTERN.exec(note)) !== null) ids.add(match[1])
518
+ return ids.size
519
+ }
520
+
521
+ /** `add-task` / `update-task` 的 note 校验:单任务最多 8 个不同附件引用(§2.1)。 */
522
+ export function assertNoteAttachments(note) {
523
+ if (typeof note !== 'string') return
524
+ const count = countAttachmentRefs(note)
525
+ if (count > MAX_TASK_ATTACHMENTS) {
526
+ throw new BoardError('bad-request', '一条任务最多 ' + MAX_TASK_ATTACHMENTS + ' 个图片附件(当前 ' + count + ' 个)', {
527
+ count,
528
+ max: MAX_TASK_ATTACHMENTS,
529
+ })
530
+ }
531
+ }
532
+
533
+ function attachmentIndexPath(dir) {
534
+ return join(dir, ATTACHMENT_INDEX_FILENAME)
535
+ }
536
+
537
+ /** 读索引:文件缺失 = 空索引;JSON / 结构损坏时标记 corrupt(读端点报 internal)。 */
538
+ function readAttachmentIndexState(dir) {
539
+ const file = attachmentIndexPath(dir)
540
+ if (!existsSync(file)) return { entries: {}, corrupt: false }
541
+ try {
542
+ const parsed = JSON.parse(readFileSync(file, 'utf8'))
543
+ if (!isPlainObject(parsed) || !isPlainObject(parsed.entries)) return { entries: {}, corrupt: true }
544
+ const entries = {}
545
+ for (const [id, entry] of Object.entries(parsed.entries)) {
546
+ if (!ATTACHMENT_ID_PATTERN.test(id) || !isPlainObject(entry)) continue
547
+ entries[id] = entry
548
+ }
549
+ return { entries, corrupt: false }
550
+ } catch {
551
+ return { entries: {}, corrupt: true }
552
+ }
553
+ }
554
+
555
+ /** 供 UI / 测试读取索引(只返回合法条目)。 */
556
+ export function loadAttachmentIndex(dir = attachmentsDir()) {
557
+ return readAttachmentIndexState(dir).entries
558
+ }
559
+
560
+ let attachmentWriteChain = Promise.resolve()
561
+
562
+ /** 串行化索引写:一次连贴多张图时 Promise.all 也不会互相覆盖。 */
563
+ function enqueueAttachmentWrite(task) {
564
+ const run = attachmentWriteChain.then(task, task)
565
+ attachmentWriteChain = run.then(
566
+ () => undefined,
567
+ () => undefined,
568
+ )
569
+ return run
570
+ }
571
+
572
+ function mapAttachmentServiceError(error) {
573
+ const code = error && typeof error.code === 'string' ? error.code : ''
574
+ const message = describeError(error)
575
+ if (code === 'ATTACHMENT_NOT_FOUND') return new BoardError('not-found', '附件不存在:' + message, { cause: code })
576
+ if (
577
+ /^(?:UNSUPPORTED_IMAGE_TYPE|INVALID_IMAGE_BASE64|INVALID_IMAGE|IMAGE_TYPE_MISMATCH|IMAGE_TOO_LARGE|IMAGES_TOO_LARGE|TOO_MANY_IMAGES|IMAGE_TOO_MANY_PIXELS|IMAGE_DIMENSION_TOO_LARGE)$/.test(
578
+ code,
579
+ )
580
+ ) {
581
+ return new BoardError('bad-request', '图片校验失败:' + message, { cause: code })
582
+ }
583
+ return new BoardError('internal', '附件存储失败:' + message, { cause: code })
584
+ }
585
+
586
+ /**
587
+ * 保存一张粘贴图片(异步)。
588
+ * @param {string} dataUrl `data:image/<png|jpeg|webp|gif>;base64,…`
589
+ * @param {{dir?:string, name?:string, attachmentsService?:object, now?:number}} [options]
590
+ * @returns {Promise<{id:string, ref:string, mime:string, size:number, name:string}>}
591
+ */
592
+ export async function saveAttachment(dataUrl, options = {}) {
593
+ const dir = typeof options.dir === 'string' && options.dir !== '' ? options.dir : attachmentsDir()
594
+ const name = trimmed(options.name, 200)
595
+ const now = typeof options.now === 'number' ? options.now : Date.now()
596
+ const { mime, bytes } = decodeImageDataUrl(dataUrl)
597
+ const id = randomUUID()
598
+ const service = options.attachmentsService
599
+ const entry = { id, mime, size: bytes.length, name, createdAt: iso(now), backend: 'local' }
600
+ if (service && typeof service.saveImages === 'function') {
601
+ let ref
602
+ try {
603
+ const refs = await service.saveImages([
604
+ { data: bytes, mediaType: mime, ...(name === '' ? {} : { name }) },
605
+ ])
606
+ ref = Array.isArray(refs) ? refs[0] : null
607
+ } catch (error) {
608
+ throw mapAttachmentServiceError(error)
609
+ }
610
+ if (!ref || typeof ref.attachmentId !== 'string' || ref.attachmentId === '') {
611
+ throw new BoardError('internal', '附件服务没有返回有效引用')
612
+ }
613
+ entry.backend = 'dsh'
614
+ entry.ref = ref
615
+ // 附件服务会按部署策略归一化(例如带 alpha 的 PNG 转 WebP):以服务返回的 ref 为准。
616
+ if (typeof ref.mediaType === 'string' && ATTACHMENT_MEDIA_TYPES.includes(ref.mediaType)) entry.mime = ref.mediaType
617
+ if (typeof ref.bytes === 'number' && ref.bytes > 0) entry.size = ref.bytes
618
+ } else {
619
+ const file = id + '.' + ATTACHMENT_EXTENSIONS[mime]
620
+ try {
621
+ mkdirSync(dir, { recursive: true })
622
+ const tmp = join(dir, file + '.tmp-' + process.pid)
623
+ writeFileSync(tmp, bytes)
624
+ renameSync(tmp, join(dir, file))
625
+ } catch (error) {
626
+ throw new BoardError('internal', '附件写盘失败:' + describeError(error))
627
+ }
628
+ entry.file = file
629
+ }
630
+ await enqueueAttachmentWrite(() => {
631
+ let state = readAttachmentIndexState(dir)
632
+ if (state.corrupt) {
633
+ // 索引损坏:保留现场(改名),从空索引继续,避免上传永远失败。
634
+ try {
635
+ renameSync(attachmentIndexPath(dir), attachmentIndexPath(dir) + '.corrupt-' + now)
636
+ } catch {
637
+ /* best-effort */
638
+ }
639
+ state = { entries: {}, corrupt: false }
640
+ }
641
+ state.entries[id] = entry
642
+ try {
643
+ mkdirSync(dir, { recursive: true })
644
+ writeJsonAtomic(attachmentIndexPath(dir), {
645
+ version: ATTACHMENT_INDEX_VERSION,
646
+ updatedAt: iso(now),
647
+ entries: state.entries,
648
+ })
649
+ } catch (error) {
650
+ throw new BoardError('internal', '附件索引写盘失败:' + describeError(error))
651
+ }
652
+ })
653
+ return { id, ref: attachmentRef(id), mime: entry.mime, size: entry.size, name }
654
+ }
655
+
656
+ /**
657
+ * 读取一张附件(异步)。id 只接受 UUID 形式,且必须命中本插件索引;
658
+ * 自建后端额外把解析后的绝对路径限制在附件目录内(§2.1)。
659
+ * @param {string} id
660
+ * @param {{dir?:string, attachmentsService?:object}} [options]
661
+ * @returns {Promise<{id:string, mime:string, size:number, dataUrl:string}>}
662
+ */
663
+ export async function readAttachment(id, options = {}) {
664
+ const raw = typeof id === 'string' ? id.trim() : ''
665
+ if (raw === '') throw new BoardError('bad-request', '缺少附件 id')
666
+ if (!ATTACHMENT_ID_PATTERN.test(raw)) throw new BoardError('bad-request', '附件 id 格式不合法')
667
+ const dir = typeof options.dir === 'string' && options.dir !== '' ? options.dir : attachmentsDir()
668
+ const state = readAttachmentIndexState(dir)
669
+ if (state.corrupt) throw new BoardError('internal', '附件索引损坏,无法读取')
670
+ const entry = state.entries[raw]
671
+ if (!entry) throw new BoardError('not-found', '附件不存在:' + raw, { id: raw })
672
+ const mime = typeof entry.mime === 'string' ? entry.mime : ''
673
+ if (!ATTACHMENT_MEDIA_TYPES.includes(mime)) throw new BoardError('internal', '附件索引损坏:MIME 不合法')
674
+ if (entry.backend === 'dsh') {
675
+ const service = options.attachmentsService
676
+ if (!service || typeof service.readImage !== 'function') {
677
+ throw new BoardError('internal', '附件服务不可用,无法读取已存储的图片')
678
+ }
679
+ let stored
680
+ try {
681
+ stored = await service.readImage(entry.ref)
682
+ } catch (error) {
683
+ throw mapAttachmentServiceError(error)
684
+ }
685
+ const data = stored && stored.data
686
+ if (!data || typeof data.byteLength !== 'number' || data.byteLength === 0) {
687
+ throw new BoardError('internal', '附件服务没有返回有效图片数据')
688
+ }
689
+ return {
690
+ id: raw,
691
+ mime,
692
+ size: data.byteLength,
693
+ dataUrl: 'data:' + mime + ';base64,' + Buffer.from(data).toString('base64'),
694
+ }
695
+ }
696
+ const file = typeof entry.file === 'string' ? entry.file : ''
697
+ if (!ATTACHMENT_FILE_PATTERN.test(file)) throw new BoardError('internal', '附件索引损坏:文件名不合法')
698
+ const base = resolve(dir)
699
+ const full = resolve(base, file)
700
+ const prefix = base.endsWith(sep) ? base : base + sep
701
+ // 防御性路径校验:正常文件名已在上面限死,这里再确认解析结果仍在附件目录内。
702
+ if (!full.startsWith(prefix)) {
703
+ throw new BoardError('bad-request', '附件路径非法')
704
+ }
705
+ let bytes
706
+ try {
707
+ bytes = readFileSync(full)
708
+ } catch {
709
+ throw new BoardError('not-found', '附件文件不存在:' + raw, { id: raw })
710
+ }
711
+ return {
712
+ id: raw,
713
+ mime,
714
+ size: bytes.length,
715
+ dataUrl: 'data:' + mime + ';base64,' + bytes.toString('base64'),
716
+ }
717
+ }
718
+
292
719
  /* ------------------------------------------------------------------ *
293
720
  * 任务操作(纯函数,便于单测)
294
721
  * ------------------------------------------------------------------ */
@@ -315,13 +742,15 @@ export function addTask(state, input, now = Date.now()) {
315
742
  const task = {
316
743
  id: nextTaskId(state),
317
744
  title,
318
- note: trimmed(input.note, MAX_NOTE_CHARS),
745
+ note: truncateNote(input.note, MAX_NOTE_CHARS),
319
746
  status: 'todo',
320
747
  source: input.source === 'agent' ? 'agent' : 'user',
321
748
  // 仅记录「哪个会话创建的」,不参与派发路由(派发永远是主 Agent 全自动)。
322
749
  sessionId: typeof input.sessionId === 'string' && input.sessionId !== '' ? input.sessionId : null,
323
750
  dispatchedSessionId: null,
324
751
  dispatchedSessionTitle: '',
752
+ reportedAt: null,
753
+ autoDispatch: null,
325
754
  cwd: typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : null,
326
755
  assignee: '',
327
756
  result: '',
@@ -368,9 +797,14 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
368
797
  task.startedAt = stamp
369
798
  task.finishedAt = null
370
799
  task.archivedAt = null
800
+ // 返工 / 重开:下次再 done 要重新生成完成回执(§1.6 重置规则)。
801
+ task.reportedAt = null
371
802
  } else if (patch.status === 'done') {
372
803
  task.finishedAt = stamp
804
+ // 新的完成一定还没汇报过;已汇报过的历史结论只在 done→archived 时保留。
805
+ task.reportedAt = null
373
806
  } else if (patch.status === 'archived') {
807
+ // done→archived 不改 reportedAt:不会重发历史回执。
374
808
  task.archivedAt = stamp
375
809
  } else if (patch.status === 'todo') {
376
810
  // 回到待开始:重新排队派发,清掉上一轮的派发记账。
@@ -380,6 +814,9 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
380
814
  task.notifiedAt = null
381
815
  task.notificationCount = 0
382
816
  task.assignee = ''
817
+ task.reportedAt = null
818
+ // 重新排队后由轮询投递、归组长审核:不再是「宿主自动任务」,别再被 subagent/end 自动 done(§1.8)。
819
+ task.autoDispatch = null
383
820
  }
384
821
  }
385
822
  if (patch.title !== undefined) {
@@ -387,8 +824,8 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
387
824
  if (title === '') throw new BoardError('bad-request', '标题不能为空')
388
825
  task.title = title
389
826
  }
390
- if (patch.note !== undefined) task.note = trimmed(patch.note, MAX_NOTE_CHARS)
391
- if (patch.result !== undefined) task.result = trimmed(patch.result, MAX_NOTE_CHARS)
827
+ if (patch.note !== undefined) task.note = truncateNote(patch.note, MAX_NOTE_CHARS)
828
+ if (patch.result !== undefined) task.result = truncateNote(patch.result, MAX_NOTE_CHARS)
392
829
  if (patch.assignee !== undefined) task.assignee = trimmed(patch.assignee, 200)
393
830
  if (patch.lastError !== undefined) task.lastError = trimmed(patch.lastError, 500)
394
831
  if (patch.clearError === true) task.lastError = ''
@@ -472,7 +909,7 @@ function idNumber(id) {
472
909
  * 历史/冷会话唤醒不了就等(creator-cold);
473
910
  * 2. 任务指定了工作区(task.cwd,平台看板创建的)→ 优先找**同一工作区**的空闲会话;
474
911
  * 找不到就等(workspace-offline / workspace-busy),不改派到别的工作区(除非 force);
475
- * 3. 都没有 → 优先「派单看板模式」的空闲 root Agent;再退化到任意空闲 root Agent;
912
+ * 3. 都没有 → 优先「任务看板 · 工作区组长(自动)」的空闲 root Agent;再退化到任意空闲 root Agent;
476
913
  * 4. 完全没有会话 → agent-busy / no-live-agent。
477
914
  * @returns {{agent: object|null, reason: string}}
478
915
  */
@@ -520,6 +957,86 @@ export function resolveTargetAgent(agentsService, task = null, presetOf = header
520
957
  return { agent: null, reason: 'no-live-agent' }
521
958
  }
522
959
 
960
+ /**
961
+ * 任务工作区的 key(§1.5 第 3 步):命中 workspaceRegistry 用工作区 id,
962
+ * 否则用归一化 cwd。key 同时是 config.workspaceLeads 的键与 snapshot.leads.workspaces[].key。
963
+ */
964
+ /**
965
+ * 归档会话 id 集合(v0.2.0 兜底):workspaceRegistry.archivedSessionIds。
966
+ * 归档会话会被 archived-session-gate 拒绝模型步进,组长/主会话被归档后必须视为不可用。
967
+ * 服务缺失(headless / 单测)时返回空集合。
968
+ */
969
+ export function archivedSessionIdSet(rt) {
970
+ try {
971
+ const registry = serviceOf(rt && rt.ctx, 'workspaceRegistry')
972
+ const ids = registry && Array.isArray(registry.archivedSessionIds) ? registry.archivedSessionIds : []
973
+ return new Set(ids.filter((id) => typeof id === 'string' && id !== ''))
974
+ } catch {
975
+ return new Set()
976
+ }
977
+ }
978
+
979
+ /**
980
+ * 工作区组长会话失效(被归档)时,把它名下「进行中」的任务重排回待开始,
981
+ * 交给新组长重新接单;done / archived 任务不动。
982
+ * @returns {number} 重排的任务数
983
+ */
984
+ export function requeueTasksOfLead(state, sessionId, now = Date.now()) {
985
+ if (!state || !Array.isArray(state.tasks)) return 0
986
+ if (typeof sessionId !== 'string' || sessionId === '') return 0
987
+ const stamp = iso(now)
988
+ let requeued = 0
989
+ for (const task of state.tasks) {
990
+ if (!task || task.status !== 'doing' || task.dispatchedSessionId !== sessionId) continue
991
+ task.status = 'todo'
992
+ task.startedAt = null
993
+ task.finishedAt = null
994
+ task.notifiedAt = null
995
+ task.notificationCount = 0
996
+ task.assignee = ''
997
+ task.dispatchedSessionId = null
998
+ task.dispatchedSessionTitle = ''
999
+ // 重排回 todo = 回到轮询队列、归新组长审核:清掉自动任务标记(§1.8),不再被宿主自动 done。
1000
+ task.autoDispatch = null
1001
+ task.lastError = '工作区组长会话已归档,任务已重新排队,将投给新的组长'
1002
+ task.updatedAt = stamp
1003
+ requeued += 1
1004
+ }
1005
+ return requeued
1006
+ }
1007
+
1008
+ /** 删除一个工作区组长映射;返回是否发生了变化。 */
1009
+ function dropWorkspaceLeadMapping(rt, key) {
1010
+ const config = normalizeConfig(rt.state.config)
1011
+ if (!Object.prototype.hasOwnProperty.call(config.workspaceLeads, key)) return false
1012
+ const next = { ...config.workspaceLeads }
1013
+ delete next[key]
1014
+ config.workspaceLeads = next
1015
+ rt.state.config = config
1016
+ return true
1017
+ }
1018
+
1019
+ export function workspaceKeyForCwd(ctx, cwd) {
1020
+ const workspaceId = workspaceIdForCwd(ctx, cwd)
1021
+ if (workspaceId !== '') return workspaceId
1022
+ return normalizePathForCompare(cwd)
1023
+ }
1024
+
1025
+ /**
1026
+ * 从 config(或 workspaceLeads 对象)里取工作区 key 对应的组长映射。
1027
+ * 不存在 / 条目缺 sessionId 或 cwd → null(normalizeConfig 已丢弃非法条目,这里再兜一层)。
1028
+ */
1029
+ export function selectWorkspaceLead(leadsOrConfig, key) {
1030
+ const leads =
1031
+ isPlainObject(leadsOrConfig) && isPlainObject(leadsOrConfig.workspaceLeads) ? leadsOrConfig.workspaceLeads : leadsOrConfig
1032
+ if (!isPlainObject(leads) || typeof key !== 'string' || key === '') return null
1033
+ const entry = leads[key]
1034
+ if (!isPlainObject(entry)) return null
1035
+ if (typeof entry.sessionId !== 'string' || entry.sessionId === '') return null
1036
+ if (typeof entry.cwd !== 'string' || entry.cwd === '') return null
1037
+ return entry
1038
+ }
1039
+
523
1040
  /** 从一个会话 id 解析它的工作区(cwd):先查 live Agent,再查 live Session。 */
524
1041
  export function resolveSessionCwd(ctx, sessionId) {
525
1042
  if (!sessionId || typeof sessionId !== 'string') return null
@@ -802,7 +1319,15 @@ function errorPayload(error) {
802
1319
  return { ok: false, error: { code: 'internal', message: describeError(error), details: {} } }
803
1320
  }
804
1321
 
805
- async function handleHttp(rt, req, res) {
1322
+ /**
1323
+ * 请求体上限(纯函数,§3):只有 `upload-attachment` 放宽到约 7 MB(base64 膨胀 4/3),
1324
+ * 其它端点保持 512 KB——避免把大图传成通用入口。
1325
+ */
1326
+ export function bodyLimitFor(endpoint) {
1327
+ return endpoint === 'upload-attachment' ? MAX_UPLOAD_BODY_BYTES : MAX_BODY_BYTES
1328
+ }
1329
+
1330
+ export async function handleHttp(rt, req, res) {
806
1331
  if (!req || !res) return
807
1332
  if (req.method !== 'POST') return sendPlain(res, 405, 'method not allowed')
808
1333
  if (!isLoopbackRequest(req)) return sendPlain(res, 403, 'forbidden: loopback only')
@@ -813,7 +1338,8 @@ async function handleHttp(rt, req, res) {
813
1338
  const endpoint = endpointFromUrl(typeof req.url === 'string' ? req.url : '/')
814
1339
  let rpcId = null
815
1340
  try {
816
- const body = await readRequestBody(req)
1341
+ // 图片上传的 base64 会膨胀 4/3:只给这个端点放宽,其它端点保持 512 KB 上限。
1342
+ const body = await readRequestBody(req, bodyLimitFor(endpoint))
817
1343
  const envelope = parseRpcEnvelope(body)
818
1344
  rpcId = envelope.rpcId
819
1345
  if (endpoint !== '' && envelope.method !== endpoint) {
@@ -938,8 +1464,151 @@ export function listWorkspaces(rt) {
938
1464
  return rows
939
1465
  }
940
1466
 
1467
+ /** 绝对路径(/ 或 \ 开头,或 Windows 盘符 X:\ / X:/)——taskboard_add 的 workspace 直接当 cwd 用。 */
1468
+ export function isAbsoluteWorkspacePath(value) {
1469
+ return typeof value === 'string' && (/^[\\/]/.test(value) || /^[A-Za-z]:[\\/]/.test(value))
1470
+ }
1471
+
1472
+ /**
1473
+ * taskboard_add.workspace 解析(§4.4):
1474
+ * - 绝对路径 → 原样返回,不查注册表;
1475
+ * - 其它字符串 → workspaceRegistry 行依次匹配 id 精确、title 精确(大小写不敏感)、path 归一化比较,
1476
+ * 返回命中行的 path;
1477
+ * - 解析不到 → 返回 ''(调用方抛「未知工作区:…」)。
1478
+ */
1479
+ export function resolveWorkspaceTarget(value, workspaces) {
1480
+ const text = typeof value === 'string' ? value.trim() : ''
1481
+ if (text === '') return ''
1482
+ if (isAbsoluteWorkspacePath(text)) return text
1483
+ const rows = (Array.isArray(workspaces) ? workspaces : []).filter(
1484
+ (row) => row && typeof row.path === 'string' && row.path !== '',
1485
+ )
1486
+ for (const row of rows) {
1487
+ if (typeof row.id === 'string' && row.id === text) return row.path
1488
+ }
1489
+ const lowered = text.toLowerCase()
1490
+ for (const row of rows) {
1491
+ if (typeof row.title === 'string' && row.title !== '' && row.title.toLowerCase() === lowered) return row.path
1492
+ }
1493
+ const want = normalizePathForCompare(text)
1494
+ if (want !== '') {
1495
+ for (const row of rows) {
1496
+ if (normalizePathForCompare(row.path) === want) return row.path
1497
+ }
1498
+ }
1499
+ return ''
1500
+ }
1501
+
1502
+ /**
1503
+ * 结论压成单行:折叠所有空白(Markdown 换行 / 列表 / 表格),截前 200 字(§1.6 完成回执)。
1504
+ */
1505
+ export function flattenResultLine(text, max = RECEIPT_RESULT_CHARS) {
1506
+ const flat = typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : ''
1507
+ return flat.length > max ? flat.slice(0, max) : flat
1508
+ }
1509
+
1510
+ /** 完成回执正文(§1.6):一条 followup 消息汇总一批任务结论,要求主会话向用户汇总。 */
1511
+ export function buildReceiptText(tasks, now = Date.now()) {
1512
+ const rows = Array.isArray(tasks) ? tasks : []
1513
+ const lines = ['【任务看板 · 汇报】以下 ' + rows.length + ' 条任务已完成:']
1514
+ for (const task of rows) {
1515
+ const summary = flattenResultLine(task && task.result)
1516
+ lines.push('- ' + task.id + ' ' + task.title + ':' + (summary === '' ? '(无结论)' : summary))
1517
+ }
1518
+ lines.push('')
1519
+ lines.push('请向用户汇总以上结论,不要重复执行任务。')
1520
+ lines.push('看板时间:' + iso(now))
1521
+ return lines.join('\n')
1522
+ }
1523
+
1524
+ /**
1525
+ * 未汇报的完成任务(§1.6):status==='done' 且 reportedAt 为空;按 updatedAt 升序,
1526
+ * 相同按 id 数字序;最多 limit 条(默认 10)。
1527
+ */
1528
+ export function selectReceiptTasks(state, limit = MAX_RECEIPT_BATCH) {
1529
+ if (!state || !Array.isArray(state.tasks)) return []
1530
+ const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.round(Number(limit)) : MAX_RECEIPT_BATCH
1531
+ return state.tasks
1532
+ .filter((task) => task && task.status === 'done' && !task.reportedAt)
1533
+ .sort((a, b) => {
1534
+ const at = Date.parse(a.updatedAt)
1535
+ const bt = Date.parse(b.updatedAt)
1536
+ const left = Number.isFinite(at) ? at : 0
1537
+ const right = Number.isFinite(bt) ? bt : 0
1538
+ if (left !== right) return left - right
1539
+ return idNumber(a.id) - idNumber(b.id)
1540
+ })
1541
+ .slice(0, cap)
1542
+ }
1543
+
1544
+ function liveAgentOf(agents, sessionId) {
1545
+ if (!agents || typeof agents.get !== 'function') return undefined
1546
+ if (typeof sessionId !== 'string' || sessionId === '') return undefined
1547
+ try {
1548
+ return agents.get(sessionId)
1549
+ } catch {
1550
+ return undefined
1551
+ }
1552
+ }
1553
+
1554
+ /** 主会话运行时视图(§3.1.1 MainSessionRef);config.mainSessionId 为空时返回 null。 */
1555
+ export function buildMainSessionRef(config, agents, archived = new Set()) {
1556
+ const cfg = normalizeConfig(config)
1557
+ if (!cfg.mainSessionId) return null
1558
+ const agent = liveAgentOf(agents, cfg.mainSessionId)
1559
+ const live = !!agent
1560
+ const busy = live && agent.status === 'running'
1561
+ const title = live ? sessionTitle(agent) || cfg.mainSessionTitle : cfg.mainSessionTitle
1562
+ return { sessionId: cfg.mainSessionId, title: title || '', live, busy, archived: archived.has(cfg.mainSessionId) }
1563
+ }
1564
+
1565
+ /** 组长条上的工作区展示名:优先注册表 title,其次 cwd 尾段,best-effort。 */
1566
+ function workspaceLabelFor(key, cwd, workspaces) {
1567
+ const rows = Array.isArray(workspaces) ? workspaces : []
1568
+ for (const row of rows) {
1569
+ if (row && typeof row.id === 'string' && row.id === key) {
1570
+ return typeof row.title === 'string' && row.title !== '' ? row.title : baseName(cwd)
1571
+ }
1572
+ }
1573
+ const want = normalizePathForCompare(cwd)
1574
+ if (want !== '') {
1575
+ for (const row of rows) {
1576
+ if (row && typeof row.path === 'string' && normalizePathForCompare(row.path) === want) {
1577
+ return typeof row.title === 'string' && row.title !== '' ? row.title : baseName(cwd)
1578
+ }
1579
+ }
1580
+ }
1581
+ return baseName(cwd)
1582
+ }
1583
+
1584
+ /** 工作区组长运行时视图(snapshot.leads.workspaces,§3.2):按 config.workspaceLeads 的对象键顺序。 */
1585
+ export function buildWorkspaceLeadRefs(config, agents, workspaces, archived = new Set()) {
1586
+ const cfg = normalizeConfig(config)
1587
+ const rows = []
1588
+ for (const [key, entry] of Object.entries(cfg.workspaceLeads)) {
1589
+ const agent = liveAgentOf(agents, entry.sessionId)
1590
+ const live = !!agent
1591
+ const busy = live && agent.status === 'running'
1592
+ const title = live ? sessionTitle(agent) || entry.title : entry.title
1593
+ rows.push({
1594
+ key,
1595
+ label: workspaceLabelFor(key, entry.cwd, workspaces),
1596
+ cwd: entry.cwd,
1597
+ sessionId: entry.sessionId,
1598
+ title: title || '',
1599
+ live,
1600
+ busy,
1601
+ archived: archived.has(entry.sessionId),
1602
+ })
1603
+ }
1604
+ return rows
1605
+ }
1606
+
941
1607
  export function buildSnapshot(rt, now = Date.now(), preset = rt.presetInfo || null) {
942
1608
  const config = normalizeConfig(rt.state.config)
1609
+ const agentsService = rt.ctx && typeof rt.ctx.get === 'function' ? rt.ctx.get('agents') : undefined
1610
+ const workspaces = listWorkspaces(rt)
1611
+ const archivedLeads = archivedSessionIdSet(rt)
943
1612
  return {
944
1613
  version: BOARD_VERSION,
945
1614
  revision: Number(rt.state.revision) || 0,
@@ -956,23 +1625,34 @@ export function buildSnapshot(rt, now = Date.now(), preset = rt.presetInfo || nu
956
1625
  lastSkipReason: rt.poll.lastSkipReason || null,
957
1626
  },
958
1627
  agents: listAgents(rt),
959
- workspaces: listWorkspaces(rt),
1628
+ workspaces,
1629
+ // v0.2.0:组长 / 主会话运行时视图(组长条用;revision 不变也会变)。
1630
+ leads: {
1631
+ main: buildMainSessionRef(rt.state.config, agentsService, archivedLeads),
1632
+ workspaces: buildWorkspaceLeadRefs(rt.state.config, agentsService, workspaces, archivedLeads),
1633
+ },
960
1634
  preset,
1635
+ // v0.2.0:组长直聊派活自动建任务的运行时视图(不落盘,§1.8)。
1636
+ leadAuto: normalizeLeadAuto(rt.leadAuto),
961
1637
  boardPath: rt.filePath,
962
1638
  pluginVersion: PLUGIN_VERSION,
963
1639
  now: iso(now),
964
1640
  }
965
1641
  }
966
1642
 
1643
+ /** 不读写看板状态的端点:不需要每次请求前对齐 board.json。 */
1644
+ const BOARD_FREE_ENDPOINTS = new Set(['session-info', 'install-preset', 'upload-attachment', 'attachment'])
1645
+
967
1646
  async function dispatchRpc(rt, method, payload) {
968
1647
  // 每次请求前都对齐盘上状态:另一个进程(例如同时开着的测试实例)可能刚改过,
969
1648
  // 读也要对齐,否则界面会一直显示旧内存状态(表现为「点了归档还是已完成」)。
970
- if (method !== 'session-info' && method !== 'install-preset') reloadBoardIfStale(rt)
1649
+ if (!BOARD_FREE_ENDPOINTS.has(method)) reloadBoardIfStale(rt)
971
1650
  switch (method) {
972
1651
  case 'snapshot':
973
1652
  return buildSnapshot(rt, Date.now(), await refreshPresetInfo(rt))
974
1653
  case 'add-task': {
975
1654
  // 从哪个对话加的,就记下那个会话与工作区:派发时优先回这个对话执行。
1655
+ if (typeof payload.note === 'string') assertNoteAttachments(payload.note)
976
1656
  let cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : resolveSessionCwd(rt.ctx, payload.sessionId)
977
1657
  if (!cwd) cwd = await resolveSessionCwdViaQuery(rt.ctx, payload.sessionId)
978
1658
  const task = addTask(rt.state, { ...payload, cwd })
@@ -984,8 +1664,11 @@ async function dispatchRpc(rt, method, payload) {
984
1664
  const rest = {}
985
1665
  for (const key of Object.keys(payload)) if (key !== 'id' && key !== 'patch') rest[key] = payload[key]
986
1666
  const patch = isPlainObject(payload.patch) ? payload.patch : rest
1667
+ if (typeof patch.note === 'string') assertNoteAttachments(patch.note)
987
1668
  const task = applyTaskUpdate(rt.state, id, patch)
988
1669
  commitBoard(rt.state, rt.filePath)
1670
+ // 任务刚变成 done(或从 done 重开):顺手尝试 flush 完成回执(§1.6 flush 时机)。
1671
+ await flushReceipts(rt)
989
1672
  return { task }
990
1673
  }
991
1674
  case 'delete-task': {
@@ -1010,11 +1693,34 @@ async function dispatchRpc(rt, method, payload) {
1010
1693
  if (archived > 0) commitBoard(rt.state, rt.filePath)
1011
1694
  return { archived }
1012
1695
  }
1696
+ case 'bind-main-session': {
1697
+ // v0.2.0:把会话绑定为主会话(完成回执收件人);不要求当前在线(历史会话也能先绑)。
1698
+ return bindMainSession(rt, payload.sessionId)
1699
+ }
1700
+ case 'clear-main-session': {
1701
+ // v0.2.0:解除绑定(幂等)。
1702
+ return clearMainSession(rt)
1703
+ }
1704
+ case 'ensure-workspace-lead': {
1705
+ // v0.2.0:确保 cwd 所属工作区有可用常驻组长(复用 → 唤醒 → 必要时创建并修复映射)。
1706
+ return ensureWorkspaceLead(rt, payload.cwd)
1707
+ }
1013
1708
  case 'session-info': {
1014
1709
  // 给 client 用:冷会话(历史会话)不在 snapshot.agents 里,也能拿到它的工作区做提示。
1015
1710
  const cwd = resolveSessionCwd(rt.ctx, payload.sessionId) || (await resolveSessionCwdViaQuery(rt.ctx, payload.sessionId))
1016
1711
  return { sessionId: typeof payload.sessionId === 'string' ? payload.sessionId : null, cwd }
1017
1712
  }
1713
+ case 'upload-attachment': {
1714
+ // v0.2.0:粘贴图片上传。优先复用 DSH 附件服务(ctx.attachments),缺失时自建存储(§2.1)。
1715
+ return saveAttachment(payload.dataUrl, {
1716
+ name: payload.name,
1717
+ attachmentsService: serviceOf(rt.ctx, 'attachments'),
1718
+ })
1719
+ }
1720
+ case 'attachment': {
1721
+ // v0.2.0:按随机 id 读取附件,返回可给 <img src> 的 data URL。
1722
+ return readAttachment(payload.id, { attachmentsService: serviceOf(rt.ctx, 'attachments') })
1723
+ }
1018
1724
  case 'install-preset': {
1019
1725
  // 兼容旧客户端:0.2.2 起预设随 bundle 安装,这个端点只刷新状态、不再写盘。
1020
1726
  const preset = await refreshPresetInfo(rt, true)
@@ -1032,6 +1738,10 @@ async function dispatchRpc(rt, method, payload) {
1032
1738
  const SKIP_TEXT = {
1033
1739
  'poll-disabled': '轮询已暂停',
1034
1740
  'agent-busy': '目标会话正在运行,稍后再派',
1741
+ // v0.2.0 工作区组长路由(§1.5 跳过原因表;Client 用 poll.skip.<reason> 做 i18n)。
1742
+ 'lead-busy': '工作区组长正在运行,等它空下来再派',
1743
+ 'lead-unavailable': '工作区组长不可用:稍后重试,或在看板点「创建组长」',
1744
+ 'lead-no-workspace': '无法解析任务的工作区:请从目标工作区的会话里重新加这条任务',
1035
1745
  'creator-busy': '创建这条任务的对话正在运行,等它空下来再派',
1036
1746
  'creator-cold': '创建这条任务的对话还没激活(历史会话):在那边发一条消息,任务就会回到该对话执行;急的话点「立即派发」',
1037
1747
  'workspace-busy': '这条任务所属工作区的对话正在忙,等它空下来再派',
@@ -1100,7 +1810,131 @@ async function createDispatchSession(rt, task) {
1100
1810
  }
1101
1811
  }
1102
1812
 
1813
+ /** 取服务(ctx.get 在不完整测试 / 非 Web profile 里可能没有)。 */
1814
+ function serviceOf(ctx, name) {
1815
+ try {
1816
+ return ctx && typeof ctx.get === 'function' ? ctx.get(name) : undefined
1817
+ } catch {
1818
+ return undefined
1819
+ }
1820
+ }
1821
+
1822
+ /**
1823
+ * 拿 live Agent;没有就尝试 sessionController.resolveAgent 唤醒。
1824
+ * 工作区组长路由用(§1.5),与旧模式 reviveSessionAgent 的区别:不做 5 分钟负缓存,
1825
+ * 组长偶尔被关掉后能马上恢复。
1826
+ */
1827
+ async function resolveAgentForSession(rt, sessionId) {
1828
+ const live = liveAgentOf(serviceOf(rt.ctx, 'agents'), sessionId)
1829
+ if (live) return live
1830
+ const controller = serviceOf(rt.ctx, 'sessionController')
1831
+ if (!controller || typeof controller.resolveAgent !== 'function') return null
1832
+ try {
1833
+ const result = await controller.resolveAgent(sessionId)
1834
+ if (result && result.agent) return result.agent
1835
+ if (result && result.error) {
1836
+ console.warn('[taskboard] 唤醒会话 ' + sessionId + ' 失败:' + (result.error.code || 'unknown'))
1837
+ }
1838
+ } catch (error) {
1839
+ console.warn('[taskboard] 唤醒会话 ' + sessionId + ' 异常:' + describeError(error))
1840
+ }
1841
+ return null
1842
+ }
1843
+
1844
+ /**
1845
+ * 创建一个工作区常驻组长(§1.5 第 5 步 / §3.1.1):
1846
+ * 按 cwd 所属工作区创建 taskboard-dispatch 会话(解析不到 workspaceId 时退回 cwd),
1847
+ * 成功后写 config.workspaceLeads 并 commitBoard。一个工作区最多一个组长。
1848
+ * @returns {Promise<{entry?: object, agent?: object|null, error?: BoardError}>}
1849
+ */
1850
+ async function createWorkspaceLeadSession(rt, cwd, key, now = Date.now()) {
1851
+ const controller = serviceOf(rt.ctx, 'sessionController')
1852
+ if (!controller || typeof controller.create !== 'function') {
1853
+ return { error: new BoardError('internal', '无法创建工作区组长:sessionController 不可用') }
1854
+ }
1855
+ // 优先按工作区分组创建;失败(例如工作区创建被拒)退回按 cwd 创建,不丢任务。
1856
+ const workspaceId = workspaceIdForCwd(rt.ctx, cwd)
1857
+ let created = null
1858
+ if (workspaceId !== '') {
1859
+ try {
1860
+ created = await controller.create({ workspaceId, agentPreset: DISPATCH_PRESET_ID })
1861
+ } catch (error) {
1862
+ console.warn('[taskboard] 按工作区创建工作区组长失败,退回按 cwd 创建:' + describeError(error))
1863
+ created = null
1864
+ }
1865
+ }
1866
+ if (!created) {
1867
+ try {
1868
+ created = await controller.create({ cwd, agentPreset: DISPATCH_PRESET_ID })
1869
+ } catch (error) {
1870
+ return { error: new BoardError('internal', '无法创建工作区组长:' + describeError(error)) }
1871
+ }
1872
+ }
1873
+ const sessionId = created && typeof created.sessionId === 'string' ? created.sessionId : ''
1874
+ if (sessionId === '') return { error: new BoardError('internal', '无法创建工作区组长:没有拿到会话 id') }
1875
+ const agent = await resolveAgentForSession(rt, sessionId)
1876
+ const config = normalizeConfig(rt.state.config)
1877
+ const entry = { sessionId, title: agent ? sessionTitle(agent) : '', cwd, createdAt: iso(now) }
1878
+ config.workspaceLeads = putWorkspaceLead(config.workspaceLeads, key, entry)
1879
+ rt.state.config = config
1880
+ commitBoard(rt.state, rt.filePath)
1881
+ console.log('[taskboard] 工作区组长已创建:' + key + ' → ' + sessionId)
1882
+ return { entry, agent }
1883
+ }
1884
+
1885
+ /** 修复已有映射里为空的 title / cwd(§3.1.1 第 2 步),有改动才落盘。 */
1886
+ function repairWorkspaceLeadMapping(rt, mapping, key, cwd, agent) {
1887
+ let changed = false
1888
+ const next = { ...mapping }
1889
+ if (next.title === '' && agent) {
1890
+ const title = sessionTitle(agent)
1891
+ if (title !== '') {
1892
+ next.title = title
1893
+ changed = true
1894
+ }
1895
+ }
1896
+ if (next.cwd === '' && typeof cwd === 'string' && cwd !== '') {
1897
+ next.cwd = cwd
1898
+ changed = true
1899
+ }
1900
+ if (!changed) return
1901
+ const config = normalizeConfig(rt.state.config)
1902
+ config.workspaceLeads = { ...config.workspaceLeads, [key]: next }
1903
+ rt.state.config = config
1904
+ commitBoard(rt.state, rt.filePath)
1905
+ }
1906
+
1907
+ /** 组装 LeadRef(§3.1.1):live/busy 来自 live Agent,title 优先 live 标题、其次持久化映射。 */
1908
+ function leadRefFrom(key, mapping, agent, archived = false) {
1909
+ const live = !!agent
1910
+ const busy = live && agent.status === 'running'
1911
+ const title = (live ? sessionTitle(agent) : '') || (mapping && mapping.title) || ''
1912
+ return {
1913
+ key,
1914
+ cwd: (mapping && mapping.cwd) || '',
1915
+ sessionId: (mapping && mapping.sessionId) || '',
1916
+ title: title || '',
1917
+ live,
1918
+ busy,
1919
+ archived,
1920
+ }
1921
+ }
1922
+
1923
+ /**
1924
+ * 轮询派单入口。每次 tick 末尾都会尝试 flush 一次完成回执(§1.6):
1925
+ * 回执投递不占用派发名额(未绑定主会话 / 主会话忙或离线时是 no-op)。
1926
+ */
1103
1927
  export async function tick(rt, options = {}) {
1928
+ const result = await runTick(rt, options)
1929
+ try {
1930
+ await flushReceipts(rt)
1931
+ } catch (error) {
1932
+ console.warn('[taskboard] 完成回执 flush 失败:' + describeError(error))
1933
+ }
1934
+ return result
1935
+ }
1936
+
1937
+ async function runTick(rt, options = {}) {
1104
1938
  reloadBoardIfStale(rt)
1105
1939
  const now = Date.now()
1106
1940
  rt.poll.lastRunAt = iso(now)
@@ -1121,13 +1955,22 @@ export async function tick(rt, options = {}) {
1121
1955
  return { dispatched: false, reason: 'no-candidate' }
1122
1956
  }
1123
1957
  }
1124
- const agents = typeof rt.ctx.get === 'function' ? rt.ctx.get('agents') : undefined
1958
+ const agents = serviceOf(rt.ctx, 'agents')
1959
+
1960
+ // v0.2.0 默认:按任务工作区投给该工作区的常驻组长(§1.5)。绝不每任务新建会话。
1961
+ if (config.dispatchMode === 'workspace-lead') {
1962
+ const picked = await pickWorkspaceLeadTarget(rt, candidates, config, agents, options, now)
1963
+ if (!picked) return { dispatched: false, reason: rt.poll.lastSkipReason || 'lead-unavailable' }
1964
+ return deliverBoardTask(rt, picked.task, picked.agent, now)
1965
+ }
1966
+
1967
+ // 兼容模式(new / creator / auto,§1.7):沿用旧路由。
1125
1968
  const presetOf = (agent) => sessionPresetOfContext(rt.ctx, agent)
1126
1969
 
1127
1970
  // 逐条试:某个任务的目标会话正忙时跳过它,继续看下一条,避免「一个忙会话挡住整列任务」。
1128
1971
  let task = null
1129
1972
  let resolved = { agent: null, reason: null }
1130
- const mode = config.dispatchMode || 'new'
1973
+ const mode = config.dispatchMode
1131
1974
  for (const candidate of candidates) {
1132
1975
  // 默认「派发到新对话」:在任务工作区新建一个派单模式会话,任务不会被塞进别人的对话里。
1133
1976
  if (mode === 'new') {
@@ -1167,20 +2010,28 @@ export async function tick(rt, options = {}) {
1167
2010
  break
1168
2011
  }
1169
2012
  if (!task) return { dispatched: false, reason: rt.poll.lastSkipReason || 'no-live-agent' }
1170
- const sessionId = agentSessionId(resolved.agent)
2013
+ return deliverBoardTask(rt, task, resolved.agent, now)
2014
+ }
2015
+
2016
+ /**
2017
+ * 投递一条任务给目标 Agent(旧模式 / 工作区组长共用):
2018
+ * followup + sessions.flush 成功后置 doing、记通知与 dispatchedSession*、清 lastError。
2019
+ */
2020
+ async function deliverBoardTask(rt, task, agent, now) {
2021
+ const sessionId = agentSessionId(agent)
1171
2022
  // 创建时没能解析出工作区(会话还没 live)→ 投递前从目标会话补一次,派发文本就能带上工作目录。
1172
2023
  if (!task.cwd) {
1173
- const cwd = sessionCwd(resolved.agent)
2024
+ const cwd = sessionCwd(agent)
1174
2025
  if (cwd) task.cwd = cwd
1175
2026
  }
1176
2027
  const message = createBoardUserMessage(buildDispatchText(task, now))
1177
2028
  try {
1178
- resolved.agent.followup(message)
2029
+ agent.followup(message)
1179
2030
  // 关键:等 inbox splice 落盘再记账,否则重启会丢消息但 notificationCount 已 +1。
1180
2031
  // 官方 dsh-schedule 的投递路径同样在 followup 之后 await sessions.flush。
1181
2032
  try {
1182
- const sessions = typeof rt.ctx.get === 'function' ? rt.ctx.get('sessions') : undefined
1183
- if (sessions && typeof sessions.flush === 'function') await sessions.flush(resolved.agent.session)
2033
+ const sessions = serviceOf(rt.ctx, 'sessions')
2034
+ if (sessions && typeof sessions.flush === 'function') await sessions.flush(agent.session)
1184
2035
  } catch (flushError) {
1185
2036
  console.warn('[taskboard] 会话 flush 失败(消息已入队):' + describeError(flushError))
1186
2037
  }
@@ -1204,16 +2055,578 @@ export async function tick(rt, options = {}) {
1204
2055
  }
1205
2056
  rt.poll.lastDispatchAt = iso(now)
1206
2057
  rt.poll.lastDispatchSessionId = sessionId
1207
- rt.poll.lastDispatchSessionTitle = sessionTitle(resolved.agent)
2058
+ rt.poll.lastDispatchSessionTitle = sessionTitle(agent)
1208
2059
  task.dispatchedSessionId = sessionId
1209
- task.dispatchedSessionTitle = sessionTitle(resolved.agent) || ''
2060
+ task.dispatchedSessionTitle = sessionTitle(agent) || ''
1210
2061
  rt.poll.lastDispatchTaskId = task.id
1211
2062
  rt.poll.lastSkipReason = null
1212
2063
  commitBoard(rt.state, rt.filePath)
1213
2064
  return { dispatched: true, sessionId, task: { ...task } }
1214
2065
  }
1215
2066
 
2067
+ /** RPC `bind-main-session`(§3.1.1):绑定完成回执收件人;不要求会话当前在线。 */
2068
+ export async function bindMainSession(rt, sessionId) {
2069
+ if (typeof sessionId !== 'string' || sessionId.trim() === '') {
2070
+ throw new BoardError('bad-request', 'sessionId 必须是非空字符串')
2071
+ }
2072
+ const id = sessionId.trim()
2073
+ const config = normalizeConfig(rt.state.config)
2074
+ const agents = serviceOf(rt.ctx, 'agents')
2075
+ const title = sessionTitle(liveAgentOf(agents, id))
2076
+ config.mainSessionId = id
2077
+ // 尽力取 live Agent 标题;取不到保留原值 / 空串。
2078
+ if (title !== '') config.mainSessionTitle = title
2079
+ rt.state.config = config
2080
+ commitBoard(rt.state, rt.filePath)
2081
+ return { main: buildMainSessionRef(config, agents, archivedSessionIdSet(rt)) }
2082
+ }
2083
+
2084
+ /** RPC `clear-main-session`(§3.1.1):解除绑定,幂等。 */
2085
+ export async function clearMainSession(rt) {
2086
+ const config = normalizeConfig(rt.state.config)
2087
+ config.mainSessionId = null
2088
+ config.mainSessionTitle = ''
2089
+ rt.state.config = config
2090
+ commitBoard(rt.state, rt.filePath)
2091
+ return { ok: true }
2092
+ }
2093
+
2094
+ /**
2095
+ * RPC `ensure-workspace-lead`(§3.1.1):确保 cwd 所属工作区有可用常驻组长。
2096
+ * 复用已有映射(顺手修复 title/cwd)→ 唤醒冷会话 → 失败则创建新组长替换失效映射。
2097
+ */
2098
+ export async function ensureWorkspaceLead(rt, cwd) {
2099
+ if (typeof cwd !== 'string' || cwd.trim() === '') {
2100
+ throw new BoardError('bad-request', 'cwd 必须是非空字符串')
2101
+ }
2102
+ const target = cwd.trim()
2103
+ const now = Date.now()
2104
+ const key = workspaceKeyForCwd(rt.ctx, target)
2105
+ if (key === '') throw new BoardError('bad-request', '无法从 cwd 解析工作区')
2106
+ const config = normalizeConfig(rt.state.config)
2107
+ let mapping = selectWorkspaceLead(config, key)
2108
+ const agents = serviceOf(rt.ctx, 'agents')
2109
+ // 组长会话被归档 → 视为失效映射:删除它、重排其 doing 任务,随后创建新组长替换。
2110
+ if (mapping && archivedSessionIdSet(rt).has(mapping.sessionId)) {
2111
+ dropWorkspaceLeadMapping(rt, key)
2112
+ requeueTasksOfLead(rt.state, mapping.sessionId, now)
2113
+ commitBoard(rt.state, rt.filePath)
2114
+ console.warn('[taskboard] 工作区组长会话已归档,创建新组长替换:' + key)
2115
+ mapping = null
2116
+ config.workspaceLeads = normalizeConfig(rt.state.config).workspaceLeads
2117
+ }
2118
+ if (mapping) {
2119
+ let agent = liveAgentOf(agents, mapping.sessionId)
2120
+ if (!agent) agent = await resolveAgentForSession(rt, mapping.sessionId)
2121
+ if (agent) {
2122
+ repairWorkspaceLeadMapping(rt, mapping, key, target, agent)
2123
+ return { lead: leadRefFrom(key, mapping, agent) }
2124
+ }
2125
+ // 已有映射但唤醒失败:create 新组长替换(tick 不自动重建,修复走这里)。
2126
+ console.log('[taskboard] 工作区组长 ' + key + ' 唤醒失败,创建新组长替换映射')
2127
+ }
2128
+ const created = await createWorkspaceLeadSession(rt, target, key, now)
2129
+ if (created.error) throw created.error
2130
+ // 会话已创建但 agent 还没物化时照样返回 LeadRef(live=false),UI 状态点会显示离线并可重试。
2131
+ return { lead: leadRefFrom(key, created.entry, created.agent) }
2132
+ }
2133
+
2134
+ /**
2135
+ * 完成回执 flush(§1.6):把 status==='done' && reportedAt=null 的任务合并成一条
2136
+ * 「【任务看板 · 汇报】」消息投给主会话(≤10 条/批,updatedAt 升序)。
2137
+ * 主会话未绑定 / 离线 / 忙 → 本轮不发、不唤醒;投递失败只告警,不写 reportedAt。
2138
+ */
2139
+ export async function flushReceipts(rt, now = Date.now()) {
2140
+ if (!rt || !rt.state) return { sent: false, reason: 'no-state' }
2141
+ if (rt.flushingReceipts) return { sent: false, reason: 'in-flight' }
2142
+ const config = normalizeConfig(rt.state.config)
2143
+ if (!config.mainSessionId) return { sent: false, reason: 'no-main-session' }
2144
+ // 主会话被归档:归档门会拒绝它的模型步进,别投递也别记账(§1.6)。
2145
+ if (archivedSessionIdSet(rt).has(config.mainSessionId)) return { sent: false, reason: 'main-archived' }
2146
+ const batch = selectReceiptTasks(rt.state, MAX_RECEIPT_BATCH)
2147
+ if (batch.length === 0) return { sent: false, reason: 'no-receipt' }
2148
+ const agent = liveAgentOf(serviceOf(rt.ctx, 'agents'), config.mainSessionId)
2149
+ if (!agent) return { sent: false, reason: 'main-offline' }
2150
+ if (agent.status !== 'idle') return { sent: false, reason: 'main-busy' }
2151
+ rt.flushingReceipts = true
2152
+ try {
2153
+ const stamp = iso(now)
2154
+ const message = createBoardUserMessage(buildReceiptText(batch, now))
2155
+ try {
2156
+ agent.followup(message)
2157
+ // 与派发路径一致:等 inbox splice 落盘再记账,避免重启后消息丢了但 reportedAt 已写。
2158
+ try {
2159
+ const sessions = serviceOf(rt.ctx, 'sessions')
2160
+ if (sessions && typeof sessions.flush === 'function') await sessions.flush(agent.session)
2161
+ } catch (flushError) {
2162
+ console.warn('[taskboard] 回执会话 flush 失败(消息已入队):' + describeError(flushError))
2163
+ }
2164
+ } catch (error) {
2165
+ console.warn('[taskboard] 完成回执投递失败:' + describeError(error))
2166
+ return { sent: false, reason: 'followup-failed' }
2167
+ }
2168
+ for (const task of batch) task.reportedAt = stamp
2169
+ commitBoard(rt.state, rt.filePath)
2170
+ return { sent: true, count: batch.length, sessionId: config.mainSessionId }
2171
+ } finally {
2172
+ rt.flushingReceipts = false
2173
+ }
2174
+ }
2175
+
2176
+ /**
2177
+ * 工作区组长路由(§1.5):解析任务 cwd → 工作区 key → 复用/创建常驻组长。
2178
+ * 绝不 createDispatchSession(每任务新建),也绝不跨工作区改派。
2179
+ * @returns {Promise<{ok:true, agent:object, key:string}|{ok:false, reason:string}>}
2180
+ */
2181
+ async function routeWorkspaceLead(rt, task, config, agents, options, now) {
2182
+ let cwd = typeof task.cwd === 'string' && task.cwd !== '' ? task.cwd : null
2183
+ if (!cwd) {
2184
+ // 任务创建时没解析出工作区(会话还没 live / 历史任务)→ 从创建会话补一次。
2185
+ cwd = resolveSessionCwd(rt.ctx, task.sessionId) || (await resolveSessionCwdViaQuery(rt.ctx, task.sessionId))
2186
+ if (cwd) task.cwd = cwd
2187
+ }
2188
+ if (!cwd) return { ok: false, reason: 'lead-no-workspace' }
2189
+ const key = workspaceKeyForCwd(rt.ctx, cwd)
2190
+ if (key === '') return { ok: false, reason: 'lead-no-workspace' }
2191
+ let mapping = selectWorkspaceLead(config, key)
2192
+ // 组长会话被归档(归档门会拒绝它的模型步进)→ 视为失效:删映射、重排它名下 doing
2193
+ // 任务,本轮直接进入「懒创建」分支换一个新组长(§1.5)。绝不 unarchive 用户的归档动作。
2194
+ if (mapping && archivedSessionIdSet(rt).has(mapping.sessionId)) {
2195
+ dropWorkspaceLeadMapping(rt, key)
2196
+ requeueTasksOfLead(rt.state, mapping.sessionId, now)
2197
+ commitBoard(rt.state, rt.filePath)
2198
+ console.warn('[taskboard] 工作区组长会话已归档,重建:' + key)
2199
+ mapping = null
2200
+ config.workspaceLeads = normalizeConfig(rt.state.config).workspaceLeads
2201
+ }
2202
+ if (mapping) {
2203
+ // 已有映射:live → 判忙闲;没有 live → 尝试唤醒(tick 绝不自动重建已有映射)。
2204
+ let agent = liveAgentOf(agents, mapping.sessionId)
2205
+ if (!agent) agent = await resolveAgentForSession(rt, mapping.sessionId)
2206
+ if (!agent) return { ok: false, reason: 'lead-unavailable' }
2207
+ // force(立即派发)时组长忙也把消息排进它的下一轮,与旧模式 creator-busy 的 force 语义一致。
2208
+ if (agent.status !== 'idle' && options.force !== true) return { ok: false, reason: 'lead-busy' }
2209
+ return { ok: true, agent, key }
2210
+ }
2211
+ // 没有映射 → 懒创建本工作区的常驻组长(一个工作区一个,不是每任务一个)。
2212
+ const created = await createWorkspaceLeadSession(rt, cwd, key, now)
2213
+ if (created.error) {
2214
+ console.warn('[taskboard] ' + created.error.message)
2215
+ return { ok: false, reason: 'lead-unavailable' }
2216
+ }
2217
+ // 让本轮后续候选也能看到刚写入的映射,避免同一工作区在同一个 tick 里重复创建组长。
2218
+ if (created.entry) config.workspaceLeads = putWorkspaceLead(config.workspaceLeads, key, created.entry)
2219
+ if (!created.agent) return { ok: false, reason: 'lead-unavailable' }
2220
+ if (created.agent.status !== 'idle' && options.force !== true) return { ok: false, reason: 'lead-busy' }
2221
+ return { ok: true, agent: created.agent, key }
2222
+ }
2223
+
2224
+ /** workspace-lead 模式的候选遍历:组长忙/不可用时写原因并继续下一条候选,成功即结束本轮(每轮最多 1 条)。 */
2225
+ async function pickWorkspaceLeadTarget(rt, candidates, config, agents, options, now) {
2226
+ for (const candidate of candidates) {
2227
+ const cwdBefore = candidate.cwd
2228
+ const route = await routeWorkspaceLead(rt, candidate, config, agents, options, now)
2229
+ if (route.ok) return { task: candidate, agent: route.agent }
2230
+ rt.poll.lastSkipReason = route.reason
2231
+ const text = skipText(route.reason)
2232
+ let changed = candidate.cwd !== cwdBefore
2233
+ if (text !== '' && candidate.lastError !== text) {
2234
+ candidate.lastError = text
2235
+ candidate.updatedAt = iso(now)
2236
+ changed = true
2237
+ }
2238
+ if (changed) commitBoard(rt.state, rt.filePath)
2239
+ }
2240
+ return null
2241
+ }
2242
+
1216
2243
  /** 唤醒失败缓存:同一会话 5 分钟内不重复尝试 resume。 */
2244
+ /* ------------------------------------------------------------------ *
2245
+ * 组长直聊派活 → 自动建看板任务(§1.8)
2246
+ *
2247
+ * 用户可以直接打开工作区组长会话要求它派活(不经过轮询投递):组长 subagent 派 worker 时看板上
2248
+ * 本来没有任务,闭环就断了。这里用两条**事件监听**补一条任务(不改任何工具定义):
2249
+ * - tools/result(观察事件)→ `exec.name === 'subagent'` 成功返回 {kind:'activation', subagentId} 且
2250
+ * 调用方是工作区组长 → 建一条 doing 任务(assignee = worker 会话 id,autoDispatch = 'lead-dispatch');
2251
+ * - subagent/end(生命周期事件)→ 按 assignee 找回**带标记的**任务,worker completed 就置 done +
2252
+ * result 并 flush 完成回执;其它 / 缺省 stopReason 只写**任务** lastError、任务保持 doing。
2253
+ * 轮询投递任务没有标记(notifiedAt 非空),宿主绝不自动收尾——那是组长审核 + 打回的范围。
2254
+ *
2255
+ * 标准 tool-call 与 PTC(run_code)都经过同一个 ToolExecutionPipeline,因此挂钩对两种模式等价;
2256
+ * 绕过 tools 管线直调 ctx.subagents.startActivation() 的第三方插件不覆盖(§1.8 适用边界)。
2257
+ * 建任务 / 回写失败只记 leadAuto.lastError(只装挂钩自身异常),绝不阻断派发。
2258
+ * ------------------------------------------------------------------ */
2259
+
2260
+ /** 组长直聊派活挂钩的运行时视图(不落盘,进 Snapshot.leadAuto)。 */
2261
+ export function createLeadAutoState(now = Date.now()) {
2262
+ return {
2263
+ enabled: false,
2264
+ created: 0,
2265
+ deduped: 0,
2266
+ completed: 0,
2267
+ skipped: 0,
2268
+ lastError: '',
2269
+ lastErrorAt: null,
2270
+ lastTaskId: null,
2271
+ lastWorkerSessionId: null,
2272
+ updatedAt: iso(now),
2273
+ }
2274
+ }
2275
+
2276
+ function counterOf(value) {
2277
+ const num = Number(value)
2278
+ return Number.isFinite(num) ? Math.max(0, Math.round(num)) : 0
2279
+ }
2280
+
2281
+ /** 规范化 Snapshot.leadAuto:老 runtime / 缺字段也能安全读取。 */
2282
+ export function normalizeLeadAuto(raw) {
2283
+ const source = isPlainObject(raw) ? raw : {}
2284
+ return {
2285
+ enabled: source.enabled === true,
2286
+ created: counterOf(source.created),
2287
+ deduped: counterOf(source.deduped),
2288
+ completed: counterOf(source.completed),
2289
+ skipped: counterOf(source.skipped),
2290
+ lastError: trimmed(source.lastError, 500),
2291
+ lastErrorAt: asString(source.lastErrorAt) || null,
2292
+ lastTaskId: asString(source.lastTaskId) || null,
2293
+ lastWorkerSessionId: asString(source.lastWorkerSessionId) || null,
2294
+ updatedAt: asString(source.updatedAt) || null,
2295
+ }
2296
+ }
2297
+
2298
+ function ensureLeadAuto(rt) {
2299
+ if (!isPlainObject(rt.leadAuto)) rt.leadAuto = createLeadAutoState()
2300
+ return rt.leadAuto
2301
+ }
2302
+
2303
+ /** 挂钩失败统一入口:只记 lastError + console.warn,绝不抛出(§1.8 失败不阻断派发)。 */
2304
+ function recordLeadAutoError(rt, message, now = Date.now()) {
2305
+ const auto = ensureLeadAuto(rt)
2306
+ auto.lastError = trimmed(message, 500)
2307
+ auto.lastErrorAt = iso(now)
2308
+ auto.updatedAt = iso(now)
2309
+ console.warn('[taskboard] ' + auto.lastError)
2310
+ }
2311
+
2312
+ /** worker 会话 id(= 任务 assignee)对应的**宿主自动建**任务:同一 worker 只建一条(§1.8 去重)。 */
2313
+ export function findTaskByWorker(state, workerSessionId) {
2314
+ const id = trimmed(workerSessionId, 200)
2315
+ if (!state || !Array.isArray(state.tasks) || id === '') return null
2316
+ for (let i = state.tasks.length - 1; i >= 0; i--) {
2317
+ const task = state.tasks[i]
2318
+ if (!task || task.assignee !== id) continue
2319
+ // 只认带标记的任务:轮询投递任务的 assignee 也可能被组长写成 worker 会话 id,
2320
+ // 那是组长审核的对象,绝不能被宿主自动收尾(§1.8 完成回写)。
2321
+ if (task.autoDispatch !== LEAD_AUTO_MARK) continue
2322
+ return task
2323
+ }
2324
+ return null
2325
+ }
2326
+
2327
+ /** 这条任务是不是 §1.8 挂钩自动建的(只有它们才允许 `subagent/end` 自动置 done)。 */
2328
+ export function isLeadAutoTask(task) {
2329
+ return isPlainObject(task) && task.autoDispatch === LEAD_AUTO_MARK
2330
+ }
2331
+
2332
+ /**
2333
+ * 该组长名下「轮询投递」的进行中任务(= 它正在处理看板任务,别为同一次派发再建一条)。
2334
+ * 只看 notifiedAt 非空的任务:宿主自动建的直聊任务 notifiedAt 为 null,不会挡住下一次直聊派活。
2335
+ * 超过 `LEAD_IN_FLIGHT_TTL_MS` 没有更新(worker 长跑 / 组长卡死)视为陈旧、不再挡住直聊派活(§1.8)。
2336
+ */
2337
+ export function findLeadInFlightTask(state, leadSessionId, now = Date.now()) {
2338
+ const id = typeof leadSessionId === 'string' ? leadSessionId.trim() : ''
2339
+ if (!state || !Array.isArray(state.tasks) || id === '') return null
2340
+ const hit =
2341
+ state.tasks.find(
2342
+ (task) => task && task.status === 'doing' && task.dispatchedSessionId === id && asString(task.notifiedAt) !== '',
2343
+ ) || null
2344
+ if (!hit) return null
2345
+ const stamp = Date.parse(asString(hit.updatedAt) || asString(hit.startedAt) || asString(hit.notifiedAt))
2346
+ if (Number.isFinite(stamp) && now - stamp > LEAD_IN_FLIGHT_TTL_MS) return null
2347
+ return hit
2348
+ }
2349
+
2350
+ /** subagent 工具的 prompt 入参取文本(字符串或 ContentBlock[],防御式)。 */
2351
+ export function subagentPromptText(args) {
2352
+ if (!isPlainObject(args)) return ''
2353
+ const prompt = args.prompt
2354
+ if (typeof prompt === 'string') return prompt
2355
+ if (!Array.isArray(prompt)) return ''
2356
+ return prompt
2357
+ .map((block) => (block && block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
2358
+ .filter((text) => text !== '')
2359
+ .join('\n')
2360
+ }
2361
+
2362
+ /** 派发摘要里的第一行:跳过纯装饰行(分隔线),去掉行首 Markdown 标记(`#` / `- ` / `* ` / `> `)。 */
2363
+ export function firstDispatchLine(text) {
2364
+ const source = typeof text === 'string' ? text : ''
2365
+ if (source === '') return ''
2366
+ for (const raw of source.split(/\r?\n/)) {
2367
+ const line = raw.trim()
2368
+ if (line === '' || /^[\s#>*+\-=_]+$/.test(line)) continue
2369
+ return line.replace(/^(?:#{1,6}\s+|[-*+>]\s+)/, '').trim()
2370
+ }
2371
+ return ''
2372
+ }
2373
+
2374
+ /** 自动建任务的标题:description → prompt 第一行 → 「worker <尾 8>」。 */
2375
+ export function leadTaskTitle(args, childId = '') {
2376
+ const description = isPlainObject(args) ? trimmed(args.description, MAX_TITLE_CHARS) : ''
2377
+ if (description !== '') return description
2378
+ const line = trimmed(firstDispatchLine(subagentPromptText(args)), MAX_TITLE_CHARS)
2379
+ if (line !== '') return line
2380
+ const tail = trimmed(childId, 200).slice(-8)
2381
+ return tail === '' ? 'worker' : 'worker ' + tail
2382
+ }
2383
+
2384
+ /** subagent/end 里的最终回答文本(写进任务 result)。 */
2385
+ export function workerResultText(info) {
2386
+ const blocks = info && info.lastAssistantMessage
2387
+ if (!Array.isArray(blocks)) return ''
2388
+ const text = blocks
2389
+ .map((block) => (block && block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
2390
+ .filter((part) => part !== '')
2391
+ .join('\n')
2392
+ .trim()
2393
+ return truncateNote(text, MAX_NOTE_CHARS)
2394
+ }
2395
+
2396
+ /**
2397
+ * cwd → 工作区注册表里的规范 path(§1.8 建任务的 workspace):
2398
+ * `workspaceIdForCwd` 命中时用 registry 的 `path`,让看板的工作区过滤与注册表一致;
2399
+ * 命中不了(没注册表 / 不属于任何工作区)就原样返回 cwd。
2400
+ */
2401
+ export function workspacePathForCwd(ctx, cwd) {
2402
+ const raw = typeof cwd === 'string' ? cwd : ''
2403
+ const id = workspaceIdForCwd(ctx, raw)
2404
+ if (id === '') return raw
2405
+ try {
2406
+ const registry = serviceOf(ctx, 'workspaceRegistry')
2407
+ const list = registry && typeof registry.list === 'function' ? registry.list() : []
2408
+ const hit = Array.isArray(list)
2409
+ ? list.find((workspace) => workspace && workspace.id === id && typeof workspace.path === 'string' && workspace.path !== '')
2410
+ : undefined
2411
+ if (hit) return hit.path
2412
+ } catch {
2413
+ /* 退回原 cwd */
2414
+ }
2415
+ return raw
2416
+ }
2417
+
2418
+ /**
2419
+ * tools/result 命中「工作区组长成功派出 worker」时建一条看板任务(§1.8)。
2420
+ * 只做副作用:永不抛出(失败只记 leadAuto.lastError),不阻断派发。
2421
+ * @param {{agent:object, childId:string, args?:object}} input
2422
+ * @returns {{created:boolean, reason?:string, taskId?:string, task?:object}}
2423
+ */
2424
+ export function handleSubagentDispatch(rt, input, now = Date.now()) {
2425
+ const auto = ensureLeadAuto(rt)
2426
+ try {
2427
+ const agent = input && input.agent
2428
+ const childId = trimmed(input && input.childId, 200)
2429
+ if (!agent || childId === '') {
2430
+ auto.skipped += 1
2431
+ auto.updatedAt = iso(now)
2432
+ return { created: false, reason: 'skipped' }
2433
+ }
2434
+ // 只认工作区组长(taskboard-dispatch)的派发:普通会话派子 Agent 不进看板。
2435
+ if (sessionPresetOfContext(rt.ctx, agent) !== DISPATCH_PRESET_ID) {
2436
+ auto.skipped += 1
2437
+ auto.updatedAt = iso(now)
2438
+ return { created: false, reason: 'not-lead' }
2439
+ }
2440
+ reloadBoardIfStale(rt)
2441
+ const existing = findTaskByWorker(rt.state, childId)
2442
+ if (existing) {
2443
+ auto.deduped += 1
2444
+ auto.updatedAt = iso(now)
2445
+ return { created: false, reason: 'dedup-worker', taskId: existing.id }
2446
+ }
2447
+ const sessionId = agentSessionId(agent) || ''
2448
+ const inFlight = findLeadInFlightTask(rt.state, sessionId, now)
2449
+ if (inFlight) {
2450
+ // 组长正在处理轮询投递来的看板任务(且未陈旧):这次 subagent 就是那条任务的 worker,别再建一条。
2451
+ auto.deduped += 1
2452
+ auto.updatedAt = iso(now)
2453
+ return { created: false, reason: 'lead-task-in-flight', taskId: inFlight.id }
2454
+ }
2455
+ const args = input && input.args
2456
+ const title = leadTaskTitle(args, childId)
2457
+ const note = truncateNote(subagentPromptText(args), MAX_NOTE_CHARS)
2458
+ // workspace = 组长当前工作区(cwd 映射:header.cwd → sessions 服务 → 派发入参 cwd),
2459
+ // 命中工作区注册表时用注册表的规范 path(workspaceIdForCwd,§1.8)。
2460
+ const rawCwd = sessionCwd(agent) || resolveSessionCwd(rt.ctx, sessionId) || (isPlainObject(args) ? asString(args.cwd) : '')
2461
+ const cwd = workspacePathForCwd(rt.ctx, rawCwd)
2462
+ const task = addTask(rt.state, { title, note, source: 'agent', sessionId, cwd }, now)
2463
+ applyTaskUpdate(rt.state, task.id, { status: 'doing', assignee: childId }, now)
2464
+ // 持久化标记:只有带这个标记的任务才允许 subagent/end 自动收尾(§1.8 / §2)。
2465
+ task.autoDispatch = LEAD_AUTO_MARK
2466
+ task.dispatchedSessionId = sessionId || null
2467
+ task.dispatchedSessionTitle = sessionTitle(agent)
2468
+ task.lastError = ''
2469
+ task.updatedAt = iso(now)
2470
+ const saved = commitBoard(rt.state, rt.filePath)
2471
+ auto.created += 1
2472
+ auto.lastTaskId = task.id
2473
+ auto.lastWorkerSessionId = childId
2474
+ auto.updatedAt = iso(now)
2475
+ if (saved && saved.saved === false) {
2476
+ // 写盘失败不删任务(内存仍是真源),只记错误,派发照常继续。
2477
+ recordLeadAutoError(rt, '看板写盘失败(任务只在内存里):' + (saved.error || ''), now)
2478
+ } else {
2479
+ console.log('[taskboard] 组长直聊派活已建任务:' + task.id + ' ← worker 会话 ' + childId)
2480
+ }
2481
+ return { created: true, taskId: task.id, task: { ...task } }
2482
+ } catch (error) {
2483
+ recordLeadAutoError(rt, '自动建看板任务失败:' + describeError(error), now)
2484
+ return { created: false, reason: 'error', error: describeError(error) }
2485
+ }
2486
+ }
2487
+
2488
+ /**
2489
+ * subagent/end:worker 结束 → **宿主自动建的任务**置 done + result(§1.8),并 flush 完成回执(§1.6)。
2490
+ * 只认带 `autoDispatch === 'lead-dispatch'` 标记的任务:轮询投递任务的 assignee 也可能被组长写成 worker
2491
+ * 会话 id,那是组长审核的对象,宿主绝不抢先置 done(否则组长来不及取证、也无法打回)。
2492
+ * `stopReason` 只认精确的 'completed':缺字段 / 未知值一律按非 completed 处理(保持 doing + 写 lastError)。
2493
+ * 非 completed 只写**任务** lastError(`leadAuto.lastError` 只记挂钩自身异常);找不到任务直接忽略。
2494
+ */
2495
+ export async function handleSubagentEnd(rt, info, now = Date.now()) {
2496
+ const auto = ensureLeadAuto(rt)
2497
+ try {
2498
+ const childId = trimmed(info && info.id, 200)
2499
+ if (childId === '') {
2500
+ auto.skipped += 1
2501
+ auto.updatedAt = iso(now)
2502
+ return { updated: false, reason: 'skipped' }
2503
+ }
2504
+ reloadBoardIfStale(rt)
2505
+ const task = findTaskByWorker(rt.state, childId)
2506
+ if (!task) {
2507
+ // 不是宿主建的自动任务(例如组长审核时派去跑命令的验证子 Agent,
2508
+ // 或轮询投递任务的 worker——那条任务的 autoDispatch 为 null)。
2509
+ auto.skipped += 1
2510
+ auto.updatedAt = iso(now)
2511
+ return { updated: false, reason: 'no-task' }
2512
+ }
2513
+ if (!isLeadAutoTask(task) || asString(task.notifiedAt) !== '') {
2514
+ // 兜底:findTaskByWorker 已经过滤过,这里再挡一层,确保轮询任务(notifiedAt 非空)永不被自动 done。
2515
+ auto.skipped += 1
2516
+ auto.updatedAt = iso(now)
2517
+ return { updated: false, reason: 'not-auto', taskId: task.id }
2518
+ }
2519
+ const result = workerResultText(info)
2520
+ // 缺字段 / 空串 / 未知值一律按非 completed 处理(绝不静默置 done):文案里缺省写 unknown。
2521
+ const rawStopReason = asString(info && info.stopReason).trim()
2522
+ const stopReason = rawStopReason === '' ? 'unknown' : rawStopReason
2523
+ const wasDoing = task.status === 'doing'
2524
+ if (stopReason !== 'completed') {
2525
+ if (!wasDoing) {
2526
+ // 组长已审(done)或任务不在这两个状态:worker 的失败不推翻结论,也不改状态。
2527
+ auto.skipped += 1
2528
+ auto.updatedAt = iso(now)
2529
+ return { updated: false, reason: 'worker-' + stopReason, taskId: task.id }
2530
+ }
2531
+ const detail = result === '' ? '没有返回结论' : flattenResultLine(result, RECEIPT_RESULT_CHARS)
2532
+ task.lastError = trimmed('worker 结束(' + stopReason + '):' + detail, 500)
2533
+ task.updatedAt = iso(now)
2534
+ commitBoard(rt.state, rt.filePath)
2535
+ // 只写任务 lastError;leadAuto.lastError 语义是「挂钩自身失败原因」,不装派发结果。
2536
+ auto.lastTaskId = task.id
2537
+ auto.updatedAt = iso(now)
2538
+ console.warn('[taskboard] ' + task.lastError)
2539
+ return { updated: false, reason: 'worker-' + stopReason, taskId: task.id }
2540
+ }
2541
+ if (task.status !== 'doing' && task.status !== 'done') {
2542
+ auto.skipped += 1
2543
+ auto.updatedAt = iso(now)
2544
+ return { updated: false, reason: 'status-' + task.status, taskId: task.id }
2545
+ }
2546
+ const patch = {}
2547
+ if (result !== '') patch.result = result
2548
+ // doing → done;已是 done(组长先审完 / 同一 worker 再次结束)就只刷新 result。
2549
+ if (wasDoing) patch.status = 'done'
2550
+ if (Object.keys(patch).length === 0) {
2551
+ auto.skipped += 1
2552
+ auto.updatedAt = iso(now)
2553
+ return { updated: false, reason: 'no-change', taskId: task.id }
2554
+ }
2555
+ applyTaskUpdate(rt.state, task.id, patch, now)
2556
+ task.lastError = ''
2557
+ task.updatedAt = iso(now)
2558
+ commitBoard(rt.state, rt.filePath)
2559
+ // 只在真正的 doing→done 时计数;第二次结束只刷 result,不算又一次完成。
2560
+ if (wasDoing) auto.completed += 1
2561
+ auto.lastTaskId = task.id
2562
+ auto.lastWorkerSessionId = childId
2563
+ auto.updatedAt = iso(now)
2564
+ if (!wasDoing) {
2565
+ // 只刷新了 result:不重发回执(reportedAt 不变),flush 也不会把它再挑出来。
2566
+ return { updated: true, taskId: task.id, status: task.status, refreshed: true }
2567
+ }
2568
+ // 沿用 §1.6 完成回执链路(主会话未绑定 / 离线 / 忙时是 no-op)。
2569
+ try {
2570
+ await flushReceipts(rt, now)
2571
+ } catch (error) {
2572
+ console.warn('[taskboard] 完成回执 flush 失败:' + describeError(error))
2573
+ }
2574
+ return { updated: true, taskId: task.id, status: task.status }
2575
+ } catch (error) {
2576
+ recordLeadAutoError(rt, 'worker 完成回写失败:' + describeError(error), now)
2577
+ return { updated: false, reason: 'error', error: describeError(error) }
2578
+ }
2579
+ }
2580
+
2581
+ /**
2582
+ * 注册 §1.8 的两条事件挂钩。只挂监听、不需要任何服务就绪;
2583
+ * `{ global: true }` 跳过 Cordis 的 scope 过滤(carrier 按调用 Agent 过滤),事件量极小,
2584
+ * 真正的过滤在 handler 里按预设 / assignee 做。监听器由插件 fiber 自动回收。
2585
+ * 注意:第三参 `{ global: true }` 是**必需**的(少了就收不到事件),单测必须断言它。
2586
+ * @returns {boolean} 是否注册成功
2587
+ */
2588
+ export function registerLeadAutoHooks(ctx, rt) {
2589
+ if (!ctx || typeof ctx.on !== 'function') {
2590
+ console.warn('[taskboard] ctx.on 不可用,跳过组长直聊派活挂钩')
2591
+ return false
2592
+ }
2593
+ ctx.on(
2594
+ 'tools/result',
2595
+ (exec, result) => {
2596
+ try {
2597
+ // §1.8 命中条件(三个条件缺一不可,避免别的工具输出里恰好带 subagentId 就误建任务):
2598
+ // exec.name === 'subagent' + 非错误结果 + value 是 {kind:'activation', subagentId}。
2599
+ if (!exec || exec.name !== 'subagent') return
2600
+ if (!result || result.isError === true) return
2601
+ const value = result.value
2602
+ if (!isPlainObject(value) || value.kind !== 'activation') return
2603
+ const childId = typeof value.subagentId === 'string' ? value.subagentId.trim() : ''
2604
+ if (childId === '') return
2605
+ const agent = exec.agent
2606
+ if (!agent) return
2607
+ handleSubagentDispatch(rt, { agent, childId, args: exec.arguments })
2608
+ } catch (error) {
2609
+ recordLeadAutoError(rt, '组长直聊派活挂钩失败:' + describeError(error))
2610
+ }
2611
+ },
2612
+ { global: true },
2613
+ )
2614
+ ctx.on(
2615
+ 'subagent/end',
2616
+ (info) => {
2617
+ Promise.resolve()
2618
+ .then(() => handleSubagentEnd(rt, info))
2619
+ .catch((error) => recordLeadAutoError(rt, 'worker 完成挂钩失败:' + describeError(error)))
2620
+ },
2621
+ { global: true },
2622
+ )
2623
+ const auto = ensureLeadAuto(rt)
2624
+ auto.enabled = true
2625
+ auto.updatedAt = iso(Date.now())
2626
+ return true
2627
+ }
2628
+
2629
+ /** 冷会话唤醒失败的负缓存时长(5 分钟)。 */
1217
2630
  const REVIVE_RETRY_MS = 5 * 60 * 1000
1218
2631
 
1219
2632
  /**
@@ -1306,7 +2719,7 @@ function startPolling(rt) {
1306
2719
  * 模型工具
1307
2720
  * ------------------------------------------------------------------ */
1308
2721
 
1309
- const TASK_LIST_OUTPUT_SCHEMA = {
2722
+ export const TASK_LIST_OUTPUT_SCHEMA = {
1310
2723
  type: 'object',
1311
2724
  additionalProperties: false,
1312
2725
  required: ['count', 'tasks'],
@@ -1332,14 +2745,22 @@ const TASK_LIST_OUTPUT_SCHEMA = {
1332
2745
  },
1333
2746
  }
1334
2747
 
1335
- function taskBrief(task) {
2748
+ /**
2749
+ * 三个模型工具共用的任务摘要(taskboard_list 的 tasks[] / taskboard_add / taskboard_update 的 task)。
2750
+ *
2751
+ * 这里的键必须全部在 output.schema 里声明:dsh tools 管线在 execute() 成功返回之后才校验 canonical
2752
+ * output,而两个 output.schema 都是 additionalProperties:false 的封闭契约——多带一个未声明字段就会抛
2753
+ * ToolOutputError(INVALID_TOOL_OUTPUT),此时 execute() 的副作用(写盘 / 状态迁移)已经生效,
2754
+ * 模型侧却只看到调用失败。UI 专用字段(dispatchedSessionId / sessionId / cwd 等)由 buildSnapshot()
2755
+ * 的完整任务对象提供,不要加进 taskBrief。回归测试见 test/host.test.mjs。
2756
+ */
2757
+ export function taskBrief(task) {
1336
2758
  return {
1337
2759
  id: task.id,
1338
2760
  title: task.title,
1339
2761
  status: task.status,
1340
2762
  note: task.note || '',
1341
2763
  assignee: task.assignee || '',
1342
- dispatchedSessionId: task.dispatchedSessionId || null,
1343
2764
  result: task.result || '',
1344
2765
  updatedAt: task.updatedAt,
1345
2766
  }
@@ -1366,7 +2787,7 @@ function renderTaskOne(prefix, task) {
1366
2787
  return [{ type: 'text', text: lines.join('\n') }]
1367
2788
  }
1368
2789
 
1369
- const TASK_ONE_OUTPUT_SCHEMA = {
2790
+ export const TASK_ONE_OUTPUT_SCHEMA = {
1370
2791
  type: 'object',
1371
2792
  additionalProperties: false,
1372
2793
  required: ['task'],
@@ -1392,7 +2813,7 @@ const TASK_ONE_OUTPUT_SCHEMA = {
1392
2813
  * 注册三个模型工具。宿主级注册 = 全局可见(所有预设的 Agent 都能用),
1393
2814
  * 这也是「非派单模式也能往看板里塞任务」的实现方式。
1394
2815
  */
1395
- function registerTools(toolCtx, rt) {
2816
+ export function registerTools(toolCtx, rt) {
1396
2817
  const tools = toolCtx.tools
1397
2818
  if (!tools || typeof tools.register !== 'function') {
1398
2819
  console.warn('[taskboard] tools 服务不可用,跳过模型工具注册')
@@ -1431,7 +2852,8 @@ function registerTools(toolCtx, rt) {
1431
2852
  name: 'taskboard_add',
1432
2853
  description:
1433
2854
  '往任务看板添加一条待开始任务。用户口述的需求、你自己拆出来的后续任务都可以加进看板,' +
1434
- '轮询器会把它派给主 Agent。title 必填,note 写验收标准或补充信息。',
2855
+ '轮询器会把它派给任务所属工作区的常驻组长。title 必填,note 写验收标准或补充信息;' +
2856
+ 'workspace 可选(工作区 id / 名称 / 绝对路径),用于从主会话往其它工作区派任务。',
1435
2857
  parameters: {
1436
2858
  type: 'object',
1437
2859
  additionalProperties: false,
@@ -1439,6 +2861,10 @@ function registerTools(toolCtx, rt) {
1439
2861
  properties: {
1440
2862
  title: { type: 'string', description: '任务标题(一句话,必填)' },
1441
2863
  note: { type: 'string', description: '备注:背景、范围、验收标准' },
2864
+ workspace: {
2865
+ type: 'string',
2866
+ description: '可选:任务所属工作区(工作区 id / 名称 / 绝对路径),省略则用当前会话工作区',
2867
+ },
1442
2868
  },
1443
2869
  },
1444
2870
  output: {
@@ -1448,6 +2874,7 @@ function registerTools(toolCtx, rt) {
1448
2874
  execute(args, exec) {
1449
2875
  const title = trimmed(args && args.title, MAX_TITLE_CHARS)
1450
2876
  if (title === '') throw new Error('title 不能为空')
2877
+ if (typeof (args && args.note) === 'string') assertNoteAttachments(args.note)
1451
2878
  let sessionId = null
1452
2879
  let cwd = null
1453
2880
  try {
@@ -1460,6 +2887,13 @@ function registerTools(toolCtx, rt) {
1460
2887
  } catch {
1461
2888
  /* 非 agent 调用时忽略 */
1462
2889
  }
2890
+ // v0.2.0:workspace 参数(§4.4)——绝对路径直接用,否则按注册表 id / 名称 / 路径解析。
2891
+ const workspaceArg = trimmed(args && args.workspace, 500)
2892
+ if (workspaceArg !== '') {
2893
+ const resolved = resolveWorkspaceTarget(workspaceArg, listWorkspaces(rt))
2894
+ if (resolved === '') throw new Error('未知工作区:' + workspaceArg)
2895
+ cwd = resolved
2896
+ }
1463
2897
  const task = addTask(rt.state, { title, note: args && args.note, source: 'agent', sessionId, cwd })
1464
2898
  commitBoard(rt.state, rt.filePath)
1465
2899
  return Promise.resolve({ task: taskBrief(task) })
@@ -1486,15 +2920,18 @@ function registerTools(toolCtx, rt) {
1486
2920
  schema: TASK_ONE_OUTPUT_SCHEMA,
1487
2921
  render: (_args, value) => renderTaskOne('已更新任务 ', value.task),
1488
2922
  },
1489
- execute(args) {
2923
+ async execute(args) {
1490
2924
  if (!args || !args.id) throw new Error('缺少任务 id')
1491
2925
  const patch = {}
1492
2926
  for (const key of ['status', 'result', 'assignee', 'note']) {
1493
2927
  if (args[key] !== undefined) patch[key] = args[key]
1494
2928
  }
2929
+ if (typeof patch.note === 'string') assertNoteAttachments(patch.note)
1495
2930
  const task = applyTaskUpdate(rt.state, args.id, patch)
1496
2931
  commitBoard(rt.state, rt.filePath)
1497
- return Promise.resolve({ task: taskBrief(task) })
2932
+ // 任务刚变成 done(或从 done 重开):顺手尝试 flush 完成回执(§1.6 flush 时机)。
2933
+ await flushReceipts(rt)
2934
+ return { task: taskBrief(task) }
1498
2935
  },
1499
2936
  })
1500
2937
  console.log('[taskboard] 模型工具已注册:taskboard_list / taskboard_add / taskboard_update')
@@ -1515,13 +2952,19 @@ export function apply(ctx) {
1515
2952
  presetInfo: null,
1516
2953
  presetInfoAt: 0,
1517
2954
  reviveFailures: new Map(),
2955
+ // 完成回执 flush 的并发保护:tick / RPC / 工具可能同时触发,避免同一批任务重复投递。
2956
+ flushingReceipts: false,
1518
2957
  poll: {
1519
2958
  running: false,
1520
2959
  lastRunAt: null,
1521
2960
  lastDispatchAt: null,
2961
+ lastDispatchTaskId: null,
1522
2962
  lastDispatchSessionId: null,
2963
+ lastDispatchSessionTitle: null,
1523
2964
  lastSkipReason: null,
1524
2965
  },
2966
+ // 组长直聊派活自动建任务(§1.8)的运行时计数 / 最近错误。
2967
+ leadAuto: createLeadAutoState(),
1525
2968
  }
1526
2969
 
1527
2970
  try {
@@ -1615,4 +3058,14 @@ export function apply(ctx) {
1615
3058
  } catch (error) {
1616
3059
  console.warn('[taskboard] tools 服务注入失败:' + describeError(error))
1617
3060
  }
3061
+
3062
+ // 组长直聊派活 → 自动建看板任务(§1.8):只挂事件监听,不依赖任何服务就绪;
3063
+ // 监听器由插件 fiber 自动回收,失败也不阻断派发(只记 leadAuto.lastError)。
3064
+ try {
3065
+ if (registerLeadAutoHooks(ctx, runtime)) {
3066
+ console.log('[taskboard] 组长直聊派活挂钩已注册:tools/result + subagent/end')
3067
+ }
3068
+ } catch (error) {
3069
+ console.warn('[taskboard] 组长直聊派活挂钩注册失败:' + describeError(error))
3070
+ }
1618
3071
  }