dsh-dispatch-board 0.1.3 → 0.2.1

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,58 @@ 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
+ * 归档保留期(§1.2 / §2):`archived` 任务在归档满 30 分钟后由宿主自动从看板删除,
72
+ * 不需要用户手动点「删除」。判定见 `pruneArchivedTasks()`。
73
+ */
74
+ export const ARCHIVE_RETENTION_MS = 30 * 60 * 1000
75
+
76
+ /* ------------------------------------------------------------------ *
77
+ * 粘贴图片附件(v0.2.0,§2.1)
78
+ * ------------------------------------------------------------------ */
79
+
80
+ const ATTACHMENT_DIRNAME = 'attachments'
81
+ const ATTACHMENT_INDEX_FILENAME = 'index.json'
82
+ const ATTACHMENT_INDEX_VERSION = 1
83
+ /** 解码后单张图片上限(§2.1)。 */
84
+ export const MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024
85
+ /** 单条任务 note 里最多几个不同附件引用(§2.1)。 */
86
+ export const MAX_TASK_ATTACHMENTS = 8
87
+ /** 允许的图片 MIME(与 DSH 附件服务 v1 白名单一致)。 */
88
+ export const ATTACHMENT_MEDIA_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
89
+ /** 上传端点单独放宽的请求体上限:base64 膨胀 4/3 + data URL 前缀 + JSON 外壳。 */
90
+ export const MAX_UPLOAD_BODY_BYTES = Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4 + 64 * 1024
91
+ const ATTACHMENT_EXTENSIONS = Object.freeze({ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' })
92
+ const ATTACHMENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
93
+ 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)$/
94
+ /** note 里的短引用:![image](attachment://<uuid>)。 */
95
+ 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
96
+
97
+ /**
98
+ * §1.8 自动建任务的持久化标记:只有带这个标记的任务才会被 `subagent/end` 自动置 done。
99
+ * 轮询投递任务 / 人工任务恒为 null —— 组长把它们的 assignee 写成 worker 会话 id 也不会被宿主抢答。
100
+ */
101
+ export const LEAD_AUTO_MARK = 'lead-dispatch'
102
+ /**
103
+ * §1.8 in-flight 去重的陈旧窗口:组长名下「doing + notifiedAt」的轮询任务超过这个时长没有更新
104
+ * (worker 长跑 / 组长卡死)就不再挡住直聊派活——宁可多一条可见任务,也不让派活无声消失。
105
+ */
106
+ export const LEAD_IN_FLIGHT_TTL_MS = 30 * 60 * 1000
56
107
 
57
108
  /** 看板四列。顺序即 UI 列顺序。 */
58
109
  export const STATUSES = ['todo', 'doing', 'done', 'archived']
@@ -100,6 +151,41 @@ function trimmed(value, max) {
100
151
  return text.length > max ? text.slice(0, max) : text
101
152
  }
102
153
 
154
+ /** 丢掉被截断切开的图片引用尾巴(缺收尾 `)` / 缺 `]`,以及半个 `attachment://` 协议前缀)。 */
155
+ function stripPartialAttachmentRef(head) {
156
+ // 1) 引用 URL 被切断:`![alt](attachment://<uuid>` 没有收尾 `)`,整段丢掉。
157
+ const unclosedRef = /!\[[^\]]*\]\([^)]*$/.exec(head)
158
+ if (unclosedRef) return head.slice(0, unclosedRef.index)
159
+ // 2) 引用还没写到 `]`:`![ima`(截断点落在 alt / 协议前缀前段)。
160
+ const openRef = /!\[[^\]]*$/.exec(head)
161
+ if (openRef) return head.slice(0, openRef.index).replace(/\s+$/, '')
162
+ // 3) 兜底:尾巴是 `attachment://` 的半个协议前缀(裸引用,没走图片语法)。
163
+ const needle = 'attachment://'
164
+ for (let len = needle.length - 1; len >= 1; len -= 1) {
165
+ if (head.endsWith(needle.slice(0, len))) {
166
+ return head.slice(0, head.length - len).replace(/\s+$/, '')
167
+ }
168
+ }
169
+ // 4) 兜底:裸引用前缀完整、UUID 被切断(`see attachment://2222…-42`)——整段丢掉,
170
+ // 别把半截 id 留在 note / result 里变成坏链接;完整 UUID 照常保留。
171
+ const cutBareId = /attachment:\/\/[0-9a-f-]*$/.exec(head)
172
+ if (cutBareId && !ATTACHMENT_ID_PATTERN.test(cutBareId[0].slice(needle.length))) {
173
+ return head.slice(0, cutBareId.index).replace(/\s+$/, '')
174
+ }
175
+ return head
176
+ }
177
+
178
+ /**
179
+ * note / result 的 4000 字符截断(§2.1):**不得切出半截 `attachment://` 引用**。
180
+ * 截断点落在某个 `![...](attachment://<uuid>)` 内部时退到该引用开头再截——宁可少保留最后一个引用,
181
+ * 也不给详情浮层留坏链接(其余完整引用照常保留)。
182
+ */
183
+ export function truncateNote(text, max = MAX_NOTE_CHARS) {
184
+ const raw = typeof text === 'string' ? text.trim() : ''
185
+ if (raw.length <= max) return raw
186
+ return stripPartialAttachmentRef(raw.slice(0, max)).replace(/\s+$/, '')
187
+ }
188
+
103
189
  function isPlainObject(value) {
104
190
  return typeof value === 'object' && value !== null && !Array.isArray(value)
105
191
  }
@@ -152,14 +238,71 @@ export function createEmptyBoard() {
152
238
  pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
153
239
  maxNotifications: DEFAULT_MAX_NOTIFICATIONS,
154
240
  dispatchMode: DEFAULT_DISPATCH_MODE,
241
+ mainSessionId: null,
242
+ mainSessionTitle: '',
243
+ workspaceLeads: {},
155
244
  },
156
245
  tasks: [],
157
246
  }
158
247
  }
159
248
 
160
- /** 派发去处:新对话(默认)/ 回发起它的对话 / 自动挑空闲会话。 */
161
- export const DISPATCH_MODES = ['new', 'creator', 'auto']
162
- export const DEFAULT_DISPATCH_MODE = 'new'
249
+ /**
250
+ * 派发去处(v0.2.0):
251
+ * - workspace-lead(默认):按任务工作区投给该工作区的常驻组长(§1.5);
252
+ * - new / creator / auto:兼容旧模式(§1.7),已持久化的合法旧值原样保留。
253
+ */
254
+ export const DISPATCH_MODES = ['workspace-lead', 'new', 'creator', 'auto']
255
+ export const DEFAULT_DISPATCH_MODE = 'workspace-lead'
256
+
257
+ /**
258
+ * 规范化 config.workspaceLeads:普通对象,key 为工作区 id 或归一化 cwd;
259
+ * 条目要求 sessionId / cwd 均是非空字符串;非法条目丢弃;最多 32 条(按对象键顺序保留前 32)。
260
+ */
261
+ export function normalizeWorkspaceLeads(raw) {
262
+ const leads = {}
263
+ if (!isPlainObject(raw)) return leads
264
+ let kept = 0
265
+ for (const [key, value] of Object.entries(raw)) {
266
+ if (kept >= MAX_WORKSPACE_LEADS) break
267
+ if (typeof key !== 'string' || key === '') continue
268
+ if (!isPlainObject(value)) continue
269
+ const sessionId = typeof value.sessionId === 'string' ? value.sessionId.trim() : ''
270
+ const cwd = typeof value.cwd === 'string' ? value.cwd.trim() : ''
271
+ if (sessionId === '' || cwd === '') continue
272
+ leads[key] = {
273
+ sessionId,
274
+ title: trimmed(value.title, SESSION_TITLE_MAX),
275
+ cwd,
276
+ createdAt: typeof value.createdAt === 'string' ? value.createdAt : '',
277
+ }
278
+ kept += 1
279
+ }
280
+ return leads
281
+ }
282
+
283
+ /**
284
+ * 写一条工作区组长映射:键存在则原位更新;超过 32 条时优先淘汰对象键顺序末尾的旧键,
285
+ * 保证刚写入的新映射不会被下一次 normalizeConfig 丢弃(否则 tick 会每轮重复创建组长)。
286
+ */
287
+ export function putWorkspaceLead(leads, key, entry) {
288
+ const next = isPlainObject(leads) ? { ...leads } : {}
289
+ if (typeof key !== 'string' || key === '') return next
290
+ next[key] = entry
291
+ const keys = Object.keys(next)
292
+ while (keys.length > MAX_WORKSPACE_LEADS) {
293
+ let victim = ''
294
+ for (let i = keys.length - 1; i >= 0; i--) {
295
+ if (keys[i] !== key) {
296
+ victim = keys[i]
297
+ break
298
+ }
299
+ }
300
+ if (victim === '') break
301
+ delete next[victim]
302
+ keys.splice(keys.indexOf(victim), 1)
303
+ }
304
+ return next
305
+ }
163
306
 
164
307
  export function normalizeConfig(raw) {
165
308
  const config = isPlainObject(raw) ? raw : {}
@@ -176,6 +319,13 @@ export function normalizeConfig(raw) {
176
319
  Number.isFinite(maxNotifications) && maxNotifications >= 1 && maxNotifications <= 50
177
320
  ? Math.round(maxNotifications)
178
321
  : DEFAULT_MAX_NOTIFICATIONS,
322
+ // v0.2.0 完成回执收件人:未绑定 / 空白 = null。
323
+ mainSessionId: (() => {
324
+ const id = typeof config.mainSessionId === 'string' ? config.mainSessionId.trim() : ''
325
+ return id !== '' ? id : null
326
+ })(),
327
+ mainSessionTitle: trimmed(config.mainSessionTitle, SESSION_TITLE_MAX),
328
+ workspaceLeads: normalizeWorkspaceLeads(config.workspaceLeads),
179
329
  }
180
330
  }
181
331
 
@@ -188,16 +338,20 @@ function normalizeTask(raw, index) {
188
338
  return {
189
339
  id,
190
340
  title,
191
- note: trimmed(raw.note, MAX_NOTE_CHARS),
341
+ note: truncateNote(raw.note, MAX_NOTE_CHARS),
192
342
  status,
193
343
  source: raw.source === 'agent' ? 'agent' : 'user',
194
344
  sessionId: typeof raw.sessionId === 'string' && raw.sessionId !== '' ? raw.sessionId : null,
195
345
  // 最近一次投递给哪个会话(看板详情里「打开执行对话」用)。
196
346
  dispatchedSessionId: typeof raw.dispatchedSessionId === 'string' && raw.dispatchedSessionId !== '' ? raw.dispatchedSessionId : null,
197
347
  dispatchedSessionTitle: trimmed(raw.dispatchedSessionTitle, 200),
348
+ // v0.2.0 完成回执记账:null = 尚未把结论推给主会话;只在 board.json / Snapshot.tasks 出现。
349
+ reportedAt: asString(raw.reportedAt) || null,
350
+ // v0.2.0 自动建任务标记(§1.8):只有 'lead-dispatch' 合法,其它一律 null(= 普通任务)。
351
+ autoDispatch: raw.autoDispatch === LEAD_AUTO_MARK ? LEAD_AUTO_MARK : null,
198
352
  cwd: typeof raw.cwd === 'string' && raw.cwd !== '' ? raw.cwd : null,
199
353
  assignee: trimmed(raw.assignee, 200),
200
- result: trimmed(raw.result, MAX_NOTE_CHARS),
354
+ result: truncateNote(raw.result, MAX_NOTE_CHARS),
201
355
  createdAt: asString(raw.createdAt) || iso(Date.now()),
202
356
  updatedAt: asString(raw.updatedAt) || asString(raw.createdAt) || iso(Date.now()),
203
357
  startedAt: asString(raw.startedAt) || null,
@@ -289,6 +443,284 @@ export function commitBoard(state, filePath = boardPath()) {
289
443
  }
290
444
  }
291
445
 
446
+ /* ------------------------------------------------------------------ *
447
+ * 粘贴图片附件(v0.2.0,§2.1)
448
+ *
449
+ * 设计要点:
450
+ * - 优先复用 DSH 附件服务(ctx.attachments);服务不可用时退到本插件目录自建存储;
451
+ * - note 只存短引用 attachment://<uuid>,绝不存 base64(note 会进派单消息 / prompt);
452
+ * - id 是 randomUUID(不可猜);读取只按索引里的 id 查,不把用户输入拼进文件路径。
453
+ * ------------------------------------------------------------------ */
454
+
455
+ /** 附件目录:默认与 board.json 同级的 attachments/(即 $DSH_HOME/storages/dsh-taskboard/attachments)。 */
456
+ export function attachmentsDir() {
457
+ return join(dirname(boardPath()), ATTACHMENT_DIRNAME)
458
+ }
459
+
460
+ export function attachmentRef(id) {
461
+ return 'attachment://' + String(id)
462
+ }
463
+
464
+ /** 从 data URL 解出图片字节;校验 MIME 白名单、5 MB 上限与文件头。纯函数,便于单测。 */
465
+ export function decodeImageDataUrl(dataUrl) {
466
+ const text = typeof dataUrl === 'string' ? dataUrl.trim() : ''
467
+ const match = /^data:([a-z]+\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/]+={0,2})$/.exec(text)
468
+ if (!match) throw new BoardError('bad-request', '图片数据格式不合法:需要 data:<mime>;base64,<...>')
469
+ const mime = match[1].toLowerCase()
470
+ if (!ATTACHMENT_MEDIA_TYPES.includes(mime)) {
471
+ throw new BoardError('bad-request', '不支持的图片类型:' + mime + '(仅支持 png / jpeg / webp / gif)')
472
+ }
473
+ const base64 = match[2]
474
+ let bytes
475
+ try {
476
+ bytes = Buffer.from(base64, 'base64')
477
+ } catch {
478
+ throw new BoardError('bad-request', '图片 base64 解码失败')
479
+ }
480
+ // FileReader 产出的 data URL 是规范 base64;非规范形式(空白 / URL-safe 字符 / 多余填充)直接拒绝。
481
+ if (bytes.length === 0 || bytes.toString('base64') !== base64) {
482
+ throw new BoardError('bad-request', '图片 base64 不是规范编码')
483
+ }
484
+ if (bytes.length > MAX_ATTACHMENT_BYTES) {
485
+ throw new BoardError(
486
+ 'bad-request',
487
+ '图片超过大小上限:' + bytes.length + ' 字节(最多 ' + MAX_ATTACHMENT_BYTES + ' 字节 / 5 MB)',
488
+ { size: bytes.length, max: MAX_ATTACHMENT_BYTES },
489
+ )
490
+ }
491
+ const sniffed = sniffImageMime(bytes)
492
+ if (sniffed === '') throw new BoardError('bad-request', '无法识别的图片数据(文件头不是 png / jpeg / webp / gif)')
493
+ if (sniffed !== mime) throw new BoardError('bad-request', '图片内容与声明类型不一致:声明 ' + mime + ',实际 ' + sniffed)
494
+ return { mime, bytes }
495
+ }
496
+
497
+ /** 按 magic bytes 识别图片类型;识别不了返回空串。纯函数。 */
498
+ export function sniffImageMime(bytes) {
499
+ const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(0)
500
+ 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) {
501
+ return 'image/png'
502
+ }
503
+ if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg'
504
+ if (data.length >= 6) {
505
+ const head = String.fromCharCode(data[0], data[1], data[2], data[3], data[4], data[5])
506
+ if (head === 'GIF87a' || head === 'GIF89a') return 'image/gif'
507
+ }
508
+ if (data.length >= 12) {
509
+ const riff = String.fromCharCode(data[0], data[1], data[2], data[3])
510
+ const webp = String.fromCharCode(data[8], data[9], data[10], data[11])
511
+ if (riff === 'RIFF' && webp === 'WEBP') return 'image/webp'
512
+ }
513
+ return ''
514
+ }
515
+
516
+ /** note 里不同附件引用的个数(同一 id 重复出现只算一个)。纯函数。 */
517
+ export function countAttachmentRefs(note) {
518
+ if (typeof note !== 'string' || note === '') return 0
519
+ const ids = new Set()
520
+ ATTACHMENT_REF_PATTERN.lastIndex = 0
521
+ let match
522
+ while ((match = ATTACHMENT_REF_PATTERN.exec(note)) !== null) ids.add(match[1])
523
+ return ids.size
524
+ }
525
+
526
+ /** `add-task` / `update-task` 的 note 校验:单任务最多 8 个不同附件引用(§2.1)。 */
527
+ export function assertNoteAttachments(note) {
528
+ if (typeof note !== 'string') return
529
+ const count = countAttachmentRefs(note)
530
+ if (count > MAX_TASK_ATTACHMENTS) {
531
+ throw new BoardError('bad-request', '一条任务最多 ' + MAX_TASK_ATTACHMENTS + ' 个图片附件(当前 ' + count + ' 个)', {
532
+ count,
533
+ max: MAX_TASK_ATTACHMENTS,
534
+ })
535
+ }
536
+ }
537
+
538
+ function attachmentIndexPath(dir) {
539
+ return join(dir, ATTACHMENT_INDEX_FILENAME)
540
+ }
541
+
542
+ /** 读索引:文件缺失 = 空索引;JSON / 结构损坏时标记 corrupt(读端点报 internal)。 */
543
+ function readAttachmentIndexState(dir) {
544
+ const file = attachmentIndexPath(dir)
545
+ if (!existsSync(file)) return { entries: {}, corrupt: false }
546
+ try {
547
+ const parsed = JSON.parse(readFileSync(file, 'utf8'))
548
+ if (!isPlainObject(parsed) || !isPlainObject(parsed.entries)) return { entries: {}, corrupt: true }
549
+ const entries = {}
550
+ for (const [id, entry] of Object.entries(parsed.entries)) {
551
+ if (!ATTACHMENT_ID_PATTERN.test(id) || !isPlainObject(entry)) continue
552
+ entries[id] = entry
553
+ }
554
+ return { entries, corrupt: false }
555
+ } catch {
556
+ return { entries: {}, corrupt: true }
557
+ }
558
+ }
559
+
560
+ /** 供 UI / 测试读取索引(只返回合法条目)。 */
561
+ export function loadAttachmentIndex(dir = attachmentsDir()) {
562
+ return readAttachmentIndexState(dir).entries
563
+ }
564
+
565
+ let attachmentWriteChain = Promise.resolve()
566
+
567
+ /** 串行化索引写:一次连贴多张图时 Promise.all 也不会互相覆盖。 */
568
+ function enqueueAttachmentWrite(task) {
569
+ const run = attachmentWriteChain.then(task, task)
570
+ attachmentWriteChain = run.then(
571
+ () => undefined,
572
+ () => undefined,
573
+ )
574
+ return run
575
+ }
576
+
577
+ function mapAttachmentServiceError(error) {
578
+ const code = error && typeof error.code === 'string' ? error.code : ''
579
+ const message = describeError(error)
580
+ if (code === 'ATTACHMENT_NOT_FOUND') return new BoardError('not-found', '附件不存在:' + message, { cause: code })
581
+ if (
582
+ /^(?: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(
583
+ code,
584
+ )
585
+ ) {
586
+ return new BoardError('bad-request', '图片校验失败:' + message, { cause: code })
587
+ }
588
+ return new BoardError('internal', '附件存储失败:' + message, { cause: code })
589
+ }
590
+
591
+ /**
592
+ * 保存一张粘贴图片(异步)。
593
+ * @param {string} dataUrl `data:image/<png|jpeg|webp|gif>;base64,…`
594
+ * @param {{dir?:string, name?:string, attachmentsService?:object, now?:number}} [options]
595
+ * @returns {Promise<{id:string, ref:string, mime:string, size:number, name:string}>}
596
+ */
597
+ export async function saveAttachment(dataUrl, options = {}) {
598
+ const dir = typeof options.dir === 'string' && options.dir !== '' ? options.dir : attachmentsDir()
599
+ const name = trimmed(options.name, 200)
600
+ const now = typeof options.now === 'number' ? options.now : Date.now()
601
+ const { mime, bytes } = decodeImageDataUrl(dataUrl)
602
+ const id = randomUUID()
603
+ const service = options.attachmentsService
604
+ const entry = { id, mime, size: bytes.length, name, createdAt: iso(now), backend: 'local' }
605
+ if (service && typeof service.saveImages === 'function') {
606
+ let ref
607
+ try {
608
+ const refs = await service.saveImages([
609
+ { data: bytes, mediaType: mime, ...(name === '' ? {} : { name }) },
610
+ ])
611
+ ref = Array.isArray(refs) ? refs[0] : null
612
+ } catch (error) {
613
+ throw mapAttachmentServiceError(error)
614
+ }
615
+ if (!ref || typeof ref.attachmentId !== 'string' || ref.attachmentId === '') {
616
+ throw new BoardError('internal', '附件服务没有返回有效引用')
617
+ }
618
+ entry.backend = 'dsh'
619
+ entry.ref = ref
620
+ // 附件服务会按部署策略归一化(例如带 alpha 的 PNG 转 WebP):以服务返回的 ref 为准。
621
+ if (typeof ref.mediaType === 'string' && ATTACHMENT_MEDIA_TYPES.includes(ref.mediaType)) entry.mime = ref.mediaType
622
+ if (typeof ref.bytes === 'number' && ref.bytes > 0) entry.size = ref.bytes
623
+ } else {
624
+ const file = id + '.' + ATTACHMENT_EXTENSIONS[mime]
625
+ try {
626
+ mkdirSync(dir, { recursive: true })
627
+ const tmp = join(dir, file + '.tmp-' + process.pid)
628
+ writeFileSync(tmp, bytes)
629
+ renameSync(tmp, join(dir, file))
630
+ } catch (error) {
631
+ throw new BoardError('internal', '附件写盘失败:' + describeError(error))
632
+ }
633
+ entry.file = file
634
+ }
635
+ await enqueueAttachmentWrite(() => {
636
+ let state = readAttachmentIndexState(dir)
637
+ if (state.corrupt) {
638
+ // 索引损坏:保留现场(改名),从空索引继续,避免上传永远失败。
639
+ try {
640
+ renameSync(attachmentIndexPath(dir), attachmentIndexPath(dir) + '.corrupt-' + now)
641
+ } catch {
642
+ /* best-effort */
643
+ }
644
+ state = { entries: {}, corrupt: false }
645
+ }
646
+ state.entries[id] = entry
647
+ try {
648
+ mkdirSync(dir, { recursive: true })
649
+ writeJsonAtomic(attachmentIndexPath(dir), {
650
+ version: ATTACHMENT_INDEX_VERSION,
651
+ updatedAt: iso(now),
652
+ entries: state.entries,
653
+ })
654
+ } catch (error) {
655
+ throw new BoardError('internal', '附件索引写盘失败:' + describeError(error))
656
+ }
657
+ })
658
+ return { id, ref: attachmentRef(id), mime: entry.mime, size: entry.size, name }
659
+ }
660
+
661
+ /**
662
+ * 读取一张附件(异步)。id 只接受 UUID 形式,且必须命中本插件索引;
663
+ * 自建后端额外把解析后的绝对路径限制在附件目录内(§2.1)。
664
+ * @param {string} id
665
+ * @param {{dir?:string, attachmentsService?:object}} [options]
666
+ * @returns {Promise<{id:string, mime:string, size:number, dataUrl:string}>}
667
+ */
668
+ export async function readAttachment(id, options = {}) {
669
+ const raw = typeof id === 'string' ? id.trim() : ''
670
+ if (raw === '') throw new BoardError('bad-request', '缺少附件 id')
671
+ if (!ATTACHMENT_ID_PATTERN.test(raw)) throw new BoardError('bad-request', '附件 id 格式不合法')
672
+ const dir = typeof options.dir === 'string' && options.dir !== '' ? options.dir : attachmentsDir()
673
+ const state = readAttachmentIndexState(dir)
674
+ if (state.corrupt) throw new BoardError('internal', '附件索引损坏,无法读取')
675
+ const entry = state.entries[raw]
676
+ if (!entry) throw new BoardError('not-found', '附件不存在:' + raw, { id: raw })
677
+ const mime = typeof entry.mime === 'string' ? entry.mime : ''
678
+ if (!ATTACHMENT_MEDIA_TYPES.includes(mime)) throw new BoardError('internal', '附件索引损坏:MIME 不合法')
679
+ if (entry.backend === 'dsh') {
680
+ const service = options.attachmentsService
681
+ if (!service || typeof service.readImage !== 'function') {
682
+ throw new BoardError('internal', '附件服务不可用,无法读取已存储的图片')
683
+ }
684
+ let stored
685
+ try {
686
+ stored = await service.readImage(entry.ref)
687
+ } catch (error) {
688
+ throw mapAttachmentServiceError(error)
689
+ }
690
+ const data = stored && stored.data
691
+ if (!data || typeof data.byteLength !== 'number' || data.byteLength === 0) {
692
+ throw new BoardError('internal', '附件服务没有返回有效图片数据')
693
+ }
694
+ return {
695
+ id: raw,
696
+ mime,
697
+ size: data.byteLength,
698
+ dataUrl: 'data:' + mime + ';base64,' + Buffer.from(data).toString('base64'),
699
+ }
700
+ }
701
+ const file = typeof entry.file === 'string' ? entry.file : ''
702
+ if (!ATTACHMENT_FILE_PATTERN.test(file)) throw new BoardError('internal', '附件索引损坏:文件名不合法')
703
+ const base = resolve(dir)
704
+ const full = resolve(base, file)
705
+ const prefix = base.endsWith(sep) ? base : base + sep
706
+ // 防御性路径校验:正常文件名已在上面限死,这里再确认解析结果仍在附件目录内。
707
+ if (!full.startsWith(prefix)) {
708
+ throw new BoardError('bad-request', '附件路径非法')
709
+ }
710
+ let bytes
711
+ try {
712
+ bytes = readFileSync(full)
713
+ } catch {
714
+ throw new BoardError('not-found', '附件文件不存在:' + raw, { id: raw })
715
+ }
716
+ return {
717
+ id: raw,
718
+ mime,
719
+ size: bytes.length,
720
+ dataUrl: 'data:' + mime + ';base64,' + bytes.toString('base64'),
721
+ }
722
+ }
723
+
292
724
  /* ------------------------------------------------------------------ *
293
725
  * 任务操作(纯函数,便于单测)
294
726
  * ------------------------------------------------------------------ */
@@ -315,13 +747,15 @@ export function addTask(state, input, now = Date.now()) {
315
747
  const task = {
316
748
  id: nextTaskId(state),
317
749
  title,
318
- note: trimmed(input.note, MAX_NOTE_CHARS),
750
+ note: truncateNote(input.note, MAX_NOTE_CHARS),
319
751
  status: 'todo',
320
752
  source: input.source === 'agent' ? 'agent' : 'user',
321
753
  // 仅记录「哪个会话创建的」,不参与派发路由(派发永远是主 Agent 全自动)。
322
754
  sessionId: typeof input.sessionId === 'string' && input.sessionId !== '' ? input.sessionId : null,
323
755
  dispatchedSessionId: null,
324
756
  dispatchedSessionTitle: '',
757
+ reportedAt: null,
758
+ autoDispatch: null,
325
759
  cwd: typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : null,
326
760
  assignee: '',
327
761
  result: '',
@@ -368,9 +802,14 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
368
802
  task.startedAt = stamp
369
803
  task.finishedAt = null
370
804
  task.archivedAt = null
805
+ // 返工 / 重开:下次再 done 要重新生成完成回执(§1.6 重置规则)。
806
+ task.reportedAt = null
371
807
  } else if (patch.status === 'done') {
372
808
  task.finishedAt = stamp
809
+ // 新的完成一定还没汇报过;已汇报过的历史结论只在 done→archived 时保留。
810
+ task.reportedAt = null
373
811
  } else if (patch.status === 'archived') {
812
+ // done→archived 不改 reportedAt:不会重发历史回执。
374
813
  task.archivedAt = stamp
375
814
  } else if (patch.status === 'todo') {
376
815
  // 回到待开始:重新排队派发,清掉上一轮的派发记账。
@@ -380,6 +819,9 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
380
819
  task.notifiedAt = null
381
820
  task.notificationCount = 0
382
821
  task.assignee = ''
822
+ task.reportedAt = null
823
+ // 重新排队后由轮询投递、归组长审核:不再是「宿主自动任务」,别再被 subagent/end 自动 done(§1.8)。
824
+ task.autoDispatch = null
383
825
  }
384
826
  }
385
827
  if (patch.title !== undefined) {
@@ -387,8 +829,8 @@ export function applyTaskUpdate(state, id, patch, now = Date.now()) {
387
829
  if (title === '') throw new BoardError('bad-request', '标题不能为空')
388
830
  task.title = title
389
831
  }
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)
832
+ if (patch.note !== undefined) task.note = truncateNote(patch.note, MAX_NOTE_CHARS)
833
+ if (patch.result !== undefined) task.result = truncateNote(patch.result, MAX_NOTE_CHARS)
392
834
  if (patch.assignee !== undefined) task.assignee = trimmed(patch.assignee, 200)
393
835
  if (patch.lastError !== undefined) task.lastError = trimmed(patch.lastError, 500)
394
836
  if (patch.clearError === true) task.lastError = ''
@@ -418,6 +860,73 @@ export function deleteTask(state, id) {
418
860
  return task
419
861
  }
420
862
 
863
+ /** 解析一个 ISO 时间字段;缺失 / 非字符串 / 不可解析都返回 null。 */
864
+ function timeOrNull(value) {
865
+ if (typeof value !== 'string') return null
866
+ const text = value.trim()
867
+ if (text === '') return null
868
+ const ms = Date.parse(text)
869
+ return Number.isFinite(ms) ? ms : null
870
+ }
871
+
872
+ /**
873
+ * 任务的归档时间(§1.2):优先 `archivedAt`,缺失 / 不可解析时回退 `updatedAt` → `createdAt`。
874
+ * 三个都不可用 → null(调用方保守保留,不删)。
875
+ */
876
+ export function archiveTimeOf(task) {
877
+ if (!isPlainObject(task)) return null
878
+ for (const field of ['archivedAt', 'updatedAt', 'createdAt']) {
879
+ const ms = timeOrNull(task[field])
880
+ if (ms !== null) return ms
881
+ }
882
+ return null
883
+ }
884
+
885
+ /**
886
+ * 归档保留期清理(§1.2 / §2):把「归档满 retentionMs」的任务从 state.tasks 移除。纯函数。
887
+ *
888
+ * - 只处理 `status === 'archived'`;`todo` / `doing` / `done` 一律不动;
889
+ * - 归档时间见 `archiveTimeOf()`(`archivedAt` → `updatedAt` → `createdAt`);
890
+ * 三个字段都不可解析时**保守保留**——宁可留一条,也不把时间坏掉的任务误删;
891
+ * - `now - archivedAt >= retentionMs` 即删除(满 30 分钟,边界即删);
892
+ * - **不回退 `state.nextId`**:已删除任务的 id 不复用,避免旧引用指到新任务上;
893
+ * - 原地改写 `state.tasks`(保持数组引用不变),未过期任务保持原顺序。
894
+ *
895
+ * @param {object} state 看板状态
896
+ * @param {number} [now] 当前时间(ms)
897
+ * @param {number} [retentionMs] 保留期(默认 `ARCHIVE_RETENTION_MS`)
898
+ * @returns {{removed:number, ids:string[]}} 删除数量与被删任务 id(board 顺序)
899
+ */
900
+ export function pruneArchivedTasks(state, now = Date.now(), retentionMs = ARCHIVE_RETENTION_MS) {
901
+ const outcome = { removed: 0, ids: [] }
902
+ if (!isPlainObject(state) || !Array.isArray(state.tasks)) return outcome
903
+ const ttl = Number.isFinite(Number(retentionMs)) && Number(retentionMs) >= 0 ? Number(retentionMs) : ARCHIVE_RETENTION_MS
904
+ const kept = []
905
+ for (const task of state.tasks) {
906
+ if (!isPlainObject(task) || task.status !== 'archived') {
907
+ kept.push(task)
908
+ continue
909
+ }
910
+ const archivedAt = archiveTimeOf(task)
911
+ if (archivedAt === null) {
912
+ kept.push(task)
913
+ continue
914
+ }
915
+ if (now - archivedAt >= ttl) {
916
+ outcome.ids.push(task.id)
917
+ outcome.removed += 1
918
+ continue
919
+ }
920
+ kept.push(task)
921
+ }
922
+ if (outcome.removed > 0) {
923
+ // 原地替换内容:其它持有 state.tasks 引用的地方(快照 / 轮询)不会看到旧数组。
924
+ state.tasks.length = 0
925
+ for (const task of kept) state.tasks.push(task)
926
+ }
927
+ return outcome
928
+ }
929
+
421
930
  /* ------------------------------------------------------------------ *
422
931
  * 派单:候选选择 / 目标 Agent / 消息构造
423
932
  * ------------------------------------------------------------------ */
@@ -472,7 +981,7 @@ function idNumber(id) {
472
981
  * 历史/冷会话唤醒不了就等(creator-cold);
473
982
  * 2. 任务指定了工作区(task.cwd,平台看板创建的)→ 优先找**同一工作区**的空闲会话;
474
983
  * 找不到就等(workspace-offline / workspace-busy),不改派到别的工作区(除非 force);
475
- * 3. 都没有 → 优先「派单看板模式」的空闲 root Agent;再退化到任意空闲 root Agent;
984
+ * 3. 都没有 → 优先「任务看板 · 工作区组长(自动)」的空闲 root Agent;再退化到任意空闲 root Agent;
476
985
  * 4. 完全没有会话 → agent-busy / no-live-agent。
477
986
  * @returns {{agent: object|null, reason: string}}
478
987
  */
@@ -520,6 +1029,86 @@ export function resolveTargetAgent(agentsService, task = null, presetOf = header
520
1029
  return { agent: null, reason: 'no-live-agent' }
521
1030
  }
522
1031
 
1032
+ /**
1033
+ * 任务工作区的 key(§1.5 第 3 步):命中 workspaceRegistry 用工作区 id,
1034
+ * 否则用归一化 cwd。key 同时是 config.workspaceLeads 的键与 snapshot.leads.workspaces[].key。
1035
+ */
1036
+ /**
1037
+ * 归档会话 id 集合(v0.2.0 兜底):workspaceRegistry.archivedSessionIds。
1038
+ * 归档会话会被 archived-session-gate 拒绝模型步进,组长/主会话被归档后必须视为不可用。
1039
+ * 服务缺失(headless / 单测)时返回空集合。
1040
+ */
1041
+ export function archivedSessionIdSet(rt) {
1042
+ try {
1043
+ const registry = serviceOf(rt && rt.ctx, 'workspaceRegistry')
1044
+ const ids = registry && Array.isArray(registry.archivedSessionIds) ? registry.archivedSessionIds : []
1045
+ return new Set(ids.filter((id) => typeof id === 'string' && id !== ''))
1046
+ } catch {
1047
+ return new Set()
1048
+ }
1049
+ }
1050
+
1051
+ /**
1052
+ * 工作区组长会话失效(被归档)时,把它名下「进行中」的任务重排回待开始,
1053
+ * 交给新组长重新接单;done / archived 任务不动。
1054
+ * @returns {number} 重排的任务数
1055
+ */
1056
+ export function requeueTasksOfLead(state, sessionId, now = Date.now()) {
1057
+ if (!state || !Array.isArray(state.tasks)) return 0
1058
+ if (typeof sessionId !== 'string' || sessionId === '') return 0
1059
+ const stamp = iso(now)
1060
+ let requeued = 0
1061
+ for (const task of state.tasks) {
1062
+ if (!task || task.status !== 'doing' || task.dispatchedSessionId !== sessionId) continue
1063
+ task.status = 'todo'
1064
+ task.startedAt = null
1065
+ task.finishedAt = null
1066
+ task.notifiedAt = null
1067
+ task.notificationCount = 0
1068
+ task.assignee = ''
1069
+ task.dispatchedSessionId = null
1070
+ task.dispatchedSessionTitle = ''
1071
+ // 重排回 todo = 回到轮询队列、归新组长审核:清掉自动任务标记(§1.8),不再被宿主自动 done。
1072
+ task.autoDispatch = null
1073
+ task.lastError = '工作区组长会话已归档,任务已重新排队,将投给新的组长'
1074
+ task.updatedAt = stamp
1075
+ requeued += 1
1076
+ }
1077
+ return requeued
1078
+ }
1079
+
1080
+ /** 删除一个工作区组长映射;返回是否发生了变化。 */
1081
+ function dropWorkspaceLeadMapping(rt, key) {
1082
+ const config = normalizeConfig(rt.state.config)
1083
+ if (!Object.prototype.hasOwnProperty.call(config.workspaceLeads, key)) return false
1084
+ const next = { ...config.workspaceLeads }
1085
+ delete next[key]
1086
+ config.workspaceLeads = next
1087
+ rt.state.config = config
1088
+ return true
1089
+ }
1090
+
1091
+ export function workspaceKeyForCwd(ctx, cwd) {
1092
+ const workspaceId = workspaceIdForCwd(ctx, cwd)
1093
+ if (workspaceId !== '') return workspaceId
1094
+ return normalizePathForCompare(cwd)
1095
+ }
1096
+
1097
+ /**
1098
+ * 从 config(或 workspaceLeads 对象)里取工作区 key 对应的组长映射。
1099
+ * 不存在 / 条目缺 sessionId 或 cwd → null(normalizeConfig 已丢弃非法条目,这里再兜一层)。
1100
+ */
1101
+ export function selectWorkspaceLead(leadsOrConfig, key) {
1102
+ const leads =
1103
+ isPlainObject(leadsOrConfig) && isPlainObject(leadsOrConfig.workspaceLeads) ? leadsOrConfig.workspaceLeads : leadsOrConfig
1104
+ if (!isPlainObject(leads) || typeof key !== 'string' || key === '') return null
1105
+ const entry = leads[key]
1106
+ if (!isPlainObject(entry)) return null
1107
+ if (typeof entry.sessionId !== 'string' || entry.sessionId === '') return null
1108
+ if (typeof entry.cwd !== 'string' || entry.cwd === '') return null
1109
+ return entry
1110
+ }
1111
+
523
1112
  /** 从一个会话 id 解析它的工作区(cwd):先查 live Agent,再查 live Session。 */
524
1113
  export function resolveSessionCwd(ctx, sessionId) {
525
1114
  if (!sessionId || typeof sessionId !== 'string') return null
@@ -802,7 +1391,15 @@ function errorPayload(error) {
802
1391
  return { ok: false, error: { code: 'internal', message: describeError(error), details: {} } }
803
1392
  }
804
1393
 
805
- async function handleHttp(rt, req, res) {
1394
+ /**
1395
+ * 请求体上限(纯函数,§3):只有 `upload-attachment` 放宽到约 7 MB(base64 膨胀 4/3),
1396
+ * 其它端点保持 512 KB——避免把大图传成通用入口。
1397
+ */
1398
+ export function bodyLimitFor(endpoint) {
1399
+ return endpoint === 'upload-attachment' ? MAX_UPLOAD_BODY_BYTES : MAX_BODY_BYTES
1400
+ }
1401
+
1402
+ export async function handleHttp(rt, req, res) {
806
1403
  if (!req || !res) return
807
1404
  if (req.method !== 'POST') return sendPlain(res, 405, 'method not allowed')
808
1405
  if (!isLoopbackRequest(req)) return sendPlain(res, 403, 'forbidden: loopback only')
@@ -813,7 +1410,8 @@ async function handleHttp(rt, req, res) {
813
1410
  const endpoint = endpointFromUrl(typeof req.url === 'string' ? req.url : '/')
814
1411
  let rpcId = null
815
1412
  try {
816
- const body = await readRequestBody(req)
1413
+ // 图片上传的 base64 会膨胀 4/3:只给这个端点放宽,其它端点保持 512 KB 上限。
1414
+ const body = await readRequestBody(req, bodyLimitFor(endpoint))
817
1415
  const envelope = parseRpcEnvelope(body)
818
1416
  rpcId = envelope.rpcId
819
1417
  if (endpoint !== '' && envelope.method !== endpoint) {
@@ -938,8 +1536,151 @@ export function listWorkspaces(rt) {
938
1536
  return rows
939
1537
  }
940
1538
 
1539
+ /** 绝对路径(/ 或 \ 开头,或 Windows 盘符 X:\ / X:/)——taskboard_add 的 workspace 直接当 cwd 用。 */
1540
+ export function isAbsoluteWorkspacePath(value) {
1541
+ return typeof value === 'string' && (/^[\\/]/.test(value) || /^[A-Za-z]:[\\/]/.test(value))
1542
+ }
1543
+
1544
+ /**
1545
+ * taskboard_add.workspace 解析(§4.4):
1546
+ * - 绝对路径 → 原样返回,不查注册表;
1547
+ * - 其它字符串 → workspaceRegistry 行依次匹配 id 精确、title 精确(大小写不敏感)、path 归一化比较,
1548
+ * 返回命中行的 path;
1549
+ * - 解析不到 → 返回 ''(调用方抛「未知工作区:…」)。
1550
+ */
1551
+ export function resolveWorkspaceTarget(value, workspaces) {
1552
+ const text = typeof value === 'string' ? value.trim() : ''
1553
+ if (text === '') return ''
1554
+ if (isAbsoluteWorkspacePath(text)) return text
1555
+ const rows = (Array.isArray(workspaces) ? workspaces : []).filter(
1556
+ (row) => row && typeof row.path === 'string' && row.path !== '',
1557
+ )
1558
+ for (const row of rows) {
1559
+ if (typeof row.id === 'string' && row.id === text) return row.path
1560
+ }
1561
+ const lowered = text.toLowerCase()
1562
+ for (const row of rows) {
1563
+ if (typeof row.title === 'string' && row.title !== '' && row.title.toLowerCase() === lowered) return row.path
1564
+ }
1565
+ const want = normalizePathForCompare(text)
1566
+ if (want !== '') {
1567
+ for (const row of rows) {
1568
+ if (normalizePathForCompare(row.path) === want) return row.path
1569
+ }
1570
+ }
1571
+ return ''
1572
+ }
1573
+
1574
+ /**
1575
+ * 结论压成单行:折叠所有空白(Markdown 换行 / 列表 / 表格),截前 200 字(§1.6 完成回执)。
1576
+ */
1577
+ export function flattenResultLine(text, max = RECEIPT_RESULT_CHARS) {
1578
+ const flat = typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : ''
1579
+ return flat.length > max ? flat.slice(0, max) : flat
1580
+ }
1581
+
1582
+ /** 完成回执正文(§1.6):一条 followup 消息汇总一批任务结论,要求主会话向用户汇总。 */
1583
+ export function buildReceiptText(tasks, now = Date.now()) {
1584
+ const rows = Array.isArray(tasks) ? tasks : []
1585
+ const lines = ['【任务看板 · 汇报】以下 ' + rows.length + ' 条任务已完成:']
1586
+ for (const task of rows) {
1587
+ const summary = flattenResultLine(task && task.result)
1588
+ lines.push('- ' + task.id + ' ' + task.title + ':' + (summary === '' ? '(无结论)' : summary))
1589
+ }
1590
+ lines.push('')
1591
+ lines.push('请向用户汇总以上结论,不要重复执行任务。')
1592
+ lines.push('看板时间:' + iso(now))
1593
+ return lines.join('\n')
1594
+ }
1595
+
1596
+ /**
1597
+ * 未汇报的完成任务(§1.6):status==='done' 且 reportedAt 为空;按 updatedAt 升序,
1598
+ * 相同按 id 数字序;最多 limit 条(默认 10)。
1599
+ */
1600
+ export function selectReceiptTasks(state, limit = MAX_RECEIPT_BATCH) {
1601
+ if (!state || !Array.isArray(state.tasks)) return []
1602
+ const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.round(Number(limit)) : MAX_RECEIPT_BATCH
1603
+ return state.tasks
1604
+ .filter((task) => task && task.status === 'done' && !task.reportedAt)
1605
+ .sort((a, b) => {
1606
+ const at = Date.parse(a.updatedAt)
1607
+ const bt = Date.parse(b.updatedAt)
1608
+ const left = Number.isFinite(at) ? at : 0
1609
+ const right = Number.isFinite(bt) ? bt : 0
1610
+ if (left !== right) return left - right
1611
+ return idNumber(a.id) - idNumber(b.id)
1612
+ })
1613
+ .slice(0, cap)
1614
+ }
1615
+
1616
+ function liveAgentOf(agents, sessionId) {
1617
+ if (!agents || typeof agents.get !== 'function') return undefined
1618
+ if (typeof sessionId !== 'string' || sessionId === '') return undefined
1619
+ try {
1620
+ return agents.get(sessionId)
1621
+ } catch {
1622
+ return undefined
1623
+ }
1624
+ }
1625
+
1626
+ /** 主会话运行时视图(§3.1.1 MainSessionRef);config.mainSessionId 为空时返回 null。 */
1627
+ export function buildMainSessionRef(config, agents, archived = new Set()) {
1628
+ const cfg = normalizeConfig(config)
1629
+ if (!cfg.mainSessionId) return null
1630
+ const agent = liveAgentOf(agents, cfg.mainSessionId)
1631
+ const live = !!agent
1632
+ const busy = live && agent.status === 'running'
1633
+ const title = live ? sessionTitle(agent) || cfg.mainSessionTitle : cfg.mainSessionTitle
1634
+ return { sessionId: cfg.mainSessionId, title: title || '', live, busy, archived: archived.has(cfg.mainSessionId) }
1635
+ }
1636
+
1637
+ /** 组长条上的工作区展示名:优先注册表 title,其次 cwd 尾段,best-effort。 */
1638
+ function workspaceLabelFor(key, cwd, workspaces) {
1639
+ const rows = Array.isArray(workspaces) ? workspaces : []
1640
+ for (const row of rows) {
1641
+ if (row && typeof row.id === 'string' && row.id === key) {
1642
+ return typeof row.title === 'string' && row.title !== '' ? row.title : baseName(cwd)
1643
+ }
1644
+ }
1645
+ const want = normalizePathForCompare(cwd)
1646
+ if (want !== '') {
1647
+ for (const row of rows) {
1648
+ if (row && typeof row.path === 'string' && normalizePathForCompare(row.path) === want) {
1649
+ return typeof row.title === 'string' && row.title !== '' ? row.title : baseName(cwd)
1650
+ }
1651
+ }
1652
+ }
1653
+ return baseName(cwd)
1654
+ }
1655
+
1656
+ /** 工作区组长运行时视图(snapshot.leads.workspaces,§3.2):按 config.workspaceLeads 的对象键顺序。 */
1657
+ export function buildWorkspaceLeadRefs(config, agents, workspaces, archived = new Set()) {
1658
+ const cfg = normalizeConfig(config)
1659
+ const rows = []
1660
+ for (const [key, entry] of Object.entries(cfg.workspaceLeads)) {
1661
+ const agent = liveAgentOf(agents, entry.sessionId)
1662
+ const live = !!agent
1663
+ const busy = live && agent.status === 'running'
1664
+ const title = live ? sessionTitle(agent) || entry.title : entry.title
1665
+ rows.push({
1666
+ key,
1667
+ label: workspaceLabelFor(key, entry.cwd, workspaces),
1668
+ cwd: entry.cwd,
1669
+ sessionId: entry.sessionId,
1670
+ title: title || '',
1671
+ live,
1672
+ busy,
1673
+ archived: archived.has(entry.sessionId),
1674
+ })
1675
+ }
1676
+ return rows
1677
+ }
1678
+
941
1679
  export function buildSnapshot(rt, now = Date.now(), preset = rt.presetInfo || null) {
942
1680
  const config = normalizeConfig(rt.state.config)
1681
+ const agentsService = rt.ctx && typeof rt.ctx.get === 'function' ? rt.ctx.get('agents') : undefined
1682
+ const workspaces = listWorkspaces(rt)
1683
+ const archivedLeads = archivedSessionIdSet(rt)
943
1684
  return {
944
1685
  version: BOARD_VERSION,
945
1686
  revision: Number(rt.state.revision) || 0,
@@ -956,23 +1697,34 @@ export function buildSnapshot(rt, now = Date.now(), preset = rt.presetInfo || nu
956
1697
  lastSkipReason: rt.poll.lastSkipReason || null,
957
1698
  },
958
1699
  agents: listAgents(rt),
959
- workspaces: listWorkspaces(rt),
1700
+ workspaces,
1701
+ // v0.2.0:组长 / 主会话运行时视图(组长条用;revision 不变也会变)。
1702
+ leads: {
1703
+ main: buildMainSessionRef(rt.state.config, agentsService, archivedLeads),
1704
+ workspaces: buildWorkspaceLeadRefs(rt.state.config, agentsService, workspaces, archivedLeads),
1705
+ },
960
1706
  preset,
1707
+ // v0.2.0:组长直聊派活自动建任务的运行时视图(不落盘,§1.8)。
1708
+ leadAuto: normalizeLeadAuto(rt.leadAuto),
961
1709
  boardPath: rt.filePath,
962
1710
  pluginVersion: PLUGIN_VERSION,
963
1711
  now: iso(now),
964
1712
  }
965
1713
  }
966
1714
 
1715
+ /** 不读写看板状态的端点:不需要每次请求前对齐 board.json。 */
1716
+ const BOARD_FREE_ENDPOINTS = new Set(['session-info', 'install-preset', 'upload-attachment', 'attachment'])
1717
+
967
1718
  async function dispatchRpc(rt, method, payload) {
968
1719
  // 每次请求前都对齐盘上状态:另一个进程(例如同时开着的测试实例)可能刚改过,
969
1720
  // 读也要对齐,否则界面会一直显示旧内存状态(表现为「点了归档还是已完成」)。
970
- if (method !== 'session-info' && method !== 'install-preset') reloadBoardIfStale(rt)
1721
+ if (!BOARD_FREE_ENDPOINTS.has(method)) reloadBoardIfStale(rt)
971
1722
  switch (method) {
972
1723
  case 'snapshot':
973
1724
  return buildSnapshot(rt, Date.now(), await refreshPresetInfo(rt))
974
1725
  case 'add-task': {
975
1726
  // 从哪个对话加的,就记下那个会话与工作区:派发时优先回这个对话执行。
1727
+ if (typeof payload.note === 'string') assertNoteAttachments(payload.note)
976
1728
  let cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : resolveSessionCwd(rt.ctx, payload.sessionId)
977
1729
  if (!cwd) cwd = await resolveSessionCwdViaQuery(rt.ctx, payload.sessionId)
978
1730
  const task = addTask(rt.state, { ...payload, cwd })
@@ -984,8 +1736,11 @@ async function dispatchRpc(rt, method, payload) {
984
1736
  const rest = {}
985
1737
  for (const key of Object.keys(payload)) if (key !== 'id' && key !== 'patch') rest[key] = payload[key]
986
1738
  const patch = isPlainObject(payload.patch) ? payload.patch : rest
1739
+ if (typeof patch.note === 'string') assertNoteAttachments(patch.note)
987
1740
  const task = applyTaskUpdate(rt.state, id, patch)
988
1741
  commitBoard(rt.state, rt.filePath)
1742
+ // 任务刚变成 done(或从 done 重开):顺手尝试 flush 完成回执(§1.6 flush 时机)。
1743
+ await flushReceipts(rt)
989
1744
  return { task }
990
1745
  }
991
1746
  case 'delete-task': {
@@ -1010,11 +1765,34 @@ async function dispatchRpc(rt, method, payload) {
1010
1765
  if (archived > 0) commitBoard(rt.state, rt.filePath)
1011
1766
  return { archived }
1012
1767
  }
1768
+ case 'bind-main-session': {
1769
+ // v0.2.0:把会话绑定为主会话(完成回执收件人);不要求当前在线(历史会话也能先绑)。
1770
+ return bindMainSession(rt, payload.sessionId)
1771
+ }
1772
+ case 'clear-main-session': {
1773
+ // v0.2.0:解除绑定(幂等)。
1774
+ return clearMainSession(rt)
1775
+ }
1776
+ case 'ensure-workspace-lead': {
1777
+ // v0.2.0:确保 cwd 所属工作区有可用常驻组长(复用 → 唤醒 → 必要时创建并修复映射)。
1778
+ return ensureWorkspaceLead(rt, payload.cwd)
1779
+ }
1013
1780
  case 'session-info': {
1014
1781
  // 给 client 用:冷会话(历史会话)不在 snapshot.agents 里,也能拿到它的工作区做提示。
1015
1782
  const cwd = resolveSessionCwd(rt.ctx, payload.sessionId) || (await resolveSessionCwdViaQuery(rt.ctx, payload.sessionId))
1016
1783
  return { sessionId: typeof payload.sessionId === 'string' ? payload.sessionId : null, cwd }
1017
1784
  }
1785
+ case 'upload-attachment': {
1786
+ // v0.2.0:粘贴图片上传。优先复用 DSH 附件服务(ctx.attachments),缺失时自建存储(§2.1)。
1787
+ return saveAttachment(payload.dataUrl, {
1788
+ name: payload.name,
1789
+ attachmentsService: serviceOf(rt.ctx, 'attachments'),
1790
+ })
1791
+ }
1792
+ case 'attachment': {
1793
+ // v0.2.0:按随机 id 读取附件,返回可给 <img src> 的 data URL。
1794
+ return readAttachment(payload.id, { attachmentsService: serviceOf(rt.ctx, 'attachments') })
1795
+ }
1018
1796
  case 'install-preset': {
1019
1797
  // 兼容旧客户端:0.2.2 起预设随 bundle 安装,这个端点只刷新状态、不再写盘。
1020
1798
  const preset = await refreshPresetInfo(rt, true)
@@ -1032,6 +1810,10 @@ async function dispatchRpc(rt, method, payload) {
1032
1810
  const SKIP_TEXT = {
1033
1811
  'poll-disabled': '轮询已暂停',
1034
1812
  'agent-busy': '目标会话正在运行,稍后再派',
1813
+ // v0.2.0 工作区组长路由(§1.5 跳过原因表;Client 用 poll.skip.<reason> 做 i18n)。
1814
+ 'lead-busy': '工作区组长正在运行,等它空下来再派',
1815
+ 'lead-unavailable': '工作区组长不可用:稍后重试,或在看板点「创建组长」',
1816
+ 'lead-no-workspace': '无法解析任务的工作区:请从目标工作区的会话里重新加这条任务',
1035
1817
  'creator-busy': '创建这条任务的对话正在运行,等它空下来再派',
1036
1818
  'creator-cold': '创建这条任务的对话还没激活(历史会话):在那边发一条消息,任务就会回到该对话执行;急的话点「立即派发」',
1037
1819
  'workspace-busy': '这条任务所属工作区的对话正在忙,等它空下来再派',
@@ -1100,10 +1882,163 @@ async function createDispatchSession(rt, task) {
1100
1882
  }
1101
1883
  }
1102
1884
 
1885
+ /** 取服务(ctx.get 在不完整测试 / 非 Web profile 里可能没有)。 */
1886
+ function serviceOf(ctx, name) {
1887
+ try {
1888
+ return ctx && typeof ctx.get === 'function' ? ctx.get(name) : undefined
1889
+ } catch {
1890
+ return undefined
1891
+ }
1892
+ }
1893
+
1894
+ /**
1895
+ * 拿 live Agent;没有就尝试 sessionController.resolveAgent 唤醒。
1896
+ * 工作区组长路由用(§1.5),与旧模式 reviveSessionAgent 的区别:不做 5 分钟负缓存,
1897
+ * 组长偶尔被关掉后能马上恢复。
1898
+ */
1899
+ async function resolveAgentForSession(rt, sessionId) {
1900
+ const live = liveAgentOf(serviceOf(rt.ctx, 'agents'), sessionId)
1901
+ if (live) return live
1902
+ const controller = serviceOf(rt.ctx, 'sessionController')
1903
+ if (!controller || typeof controller.resolveAgent !== 'function') return null
1904
+ try {
1905
+ const result = await controller.resolveAgent(sessionId)
1906
+ if (result && result.agent) return result.agent
1907
+ if (result && result.error) {
1908
+ console.warn('[taskboard] 唤醒会话 ' + sessionId + ' 失败:' + (result.error.code || 'unknown'))
1909
+ }
1910
+ } catch (error) {
1911
+ console.warn('[taskboard] 唤醒会话 ' + sessionId + ' 异常:' + describeError(error))
1912
+ }
1913
+ return null
1914
+ }
1915
+
1916
+ /**
1917
+ * 创建一个工作区常驻组长(§1.5 第 5 步 / §3.1.1):
1918
+ * 按 cwd 所属工作区创建 taskboard-dispatch 会话(解析不到 workspaceId 时退回 cwd),
1919
+ * 成功后写 config.workspaceLeads 并 commitBoard。一个工作区最多一个组长。
1920
+ * @returns {Promise<{entry?: object, agent?: object|null, error?: BoardError}>}
1921
+ */
1922
+ async function createWorkspaceLeadSession(rt, cwd, key, now = Date.now()) {
1923
+ const controller = serviceOf(rt.ctx, 'sessionController')
1924
+ if (!controller || typeof controller.create !== 'function') {
1925
+ return { error: new BoardError('internal', '无法创建工作区组长:sessionController 不可用') }
1926
+ }
1927
+ // 优先按工作区分组创建;失败(例如工作区创建被拒)退回按 cwd 创建,不丢任务。
1928
+ const workspaceId = workspaceIdForCwd(rt.ctx, cwd)
1929
+ let created = null
1930
+ if (workspaceId !== '') {
1931
+ try {
1932
+ created = await controller.create({ workspaceId, agentPreset: DISPATCH_PRESET_ID })
1933
+ } catch (error) {
1934
+ console.warn('[taskboard] 按工作区创建工作区组长失败,退回按 cwd 创建:' + describeError(error))
1935
+ created = null
1936
+ }
1937
+ }
1938
+ if (!created) {
1939
+ try {
1940
+ created = await controller.create({ cwd, agentPreset: DISPATCH_PRESET_ID })
1941
+ } catch (error) {
1942
+ return { error: new BoardError('internal', '无法创建工作区组长:' + describeError(error)) }
1943
+ }
1944
+ }
1945
+ const sessionId = created && typeof created.sessionId === 'string' ? created.sessionId : ''
1946
+ if (sessionId === '') return { error: new BoardError('internal', '无法创建工作区组长:没有拿到会话 id') }
1947
+ const agent = await resolveAgentForSession(rt, sessionId)
1948
+ const config = normalizeConfig(rt.state.config)
1949
+ const entry = { sessionId, title: agent ? sessionTitle(agent) : '', cwd, createdAt: iso(now) }
1950
+ config.workspaceLeads = putWorkspaceLead(config.workspaceLeads, key, entry)
1951
+ rt.state.config = config
1952
+ commitBoard(rt.state, rt.filePath)
1953
+ console.log('[taskboard] 工作区组长已创建:' + key + ' → ' + sessionId)
1954
+ return { entry, agent }
1955
+ }
1956
+
1957
+ /** 修复已有映射里为空的 title / cwd(§3.1.1 第 2 步),有改动才落盘。 */
1958
+ function repairWorkspaceLeadMapping(rt, mapping, key, cwd, agent) {
1959
+ let changed = false
1960
+ const next = { ...mapping }
1961
+ if (next.title === '' && agent) {
1962
+ const title = sessionTitle(agent)
1963
+ if (title !== '') {
1964
+ next.title = title
1965
+ changed = true
1966
+ }
1967
+ }
1968
+ if (next.cwd === '' && typeof cwd === 'string' && cwd !== '') {
1969
+ next.cwd = cwd
1970
+ changed = true
1971
+ }
1972
+ if (!changed) return
1973
+ const config = normalizeConfig(rt.state.config)
1974
+ config.workspaceLeads = { ...config.workspaceLeads, [key]: next }
1975
+ rt.state.config = config
1976
+ commitBoard(rt.state, rt.filePath)
1977
+ }
1978
+
1979
+ /** 组装 LeadRef(§3.1.1):live/busy 来自 live Agent,title 优先 live 标题、其次持久化映射。 */
1980
+ function leadRefFrom(key, mapping, agent, archived = false) {
1981
+ const live = !!agent
1982
+ const busy = live && agent.status === 'running'
1983
+ const title = (live ? sessionTitle(agent) : '') || (mapping && mapping.title) || ''
1984
+ return {
1985
+ key,
1986
+ cwd: (mapping && mapping.cwd) || '',
1987
+ sessionId: (mapping && mapping.sessionId) || '',
1988
+ title: title || '',
1989
+ live,
1990
+ busy,
1991
+ archived,
1992
+ }
1993
+ }
1994
+
1995
+ /**
1996
+ * 归档保留期清理的落地版(§1.2 / §2):调纯函数 `pruneArchivedTasks`,
1997
+ * **有删除才** `commitBoard`(revision +1);没删除不动盘、不改 revision。
1998
+ *
1999
+ * 调用点:
2000
+ * - `runTick` 在 `pollEnabled` 判断**之前**——轮询暂停时归档也要按时清理;
2001
+ * - `apply()` 启动时清一次(宿主停机期间到期的归档不必等第一个 tick)。
2002
+ * 全程不抛:清理失败只告警,绝不影响派发 / 完成回执。
2003
+ * @returns {number} 删除的任务数
2004
+ */
2005
+ function pruneArchivedBoard(rt, now = Date.now()) {
2006
+ let outcome
2007
+ try {
2008
+ outcome = pruneArchivedTasks(rt.state, now)
2009
+ } catch (error) {
2010
+ console.warn('[taskboard] 归档清理失败:' + describeError(error))
2011
+ return 0
2012
+ }
2013
+ if (outcome.removed === 0) return 0
2014
+ const saved = commitBoard(rt.state, rt.filePath)
2015
+ console.log(
2016
+ '[taskboard] 已删除 ' + outcome.removed + ' 条归档满 30 分钟的任务:' + outcome.ids.join(', ') +
2017
+ (saved.saved ? '' : '(写盘失败,仅在内存中删除)'),
2018
+ )
2019
+ return outcome.removed
2020
+ }
2021
+
2022
+ /**
2023
+ * 轮询派单入口。每次 tick 末尾都会尝试 flush 一次完成回执(§1.6):
2024
+ * 回执投递不占用派发名额(未绑定主会话 / 主会话忙或离线时是 no-op)。
2025
+ */
1103
2026
  export async function tick(rt, options = {}) {
2027
+ const result = await runTick(rt, options)
2028
+ try {
2029
+ await flushReceipts(rt)
2030
+ } catch (error) {
2031
+ console.warn('[taskboard] 完成回执 flush 失败:' + describeError(error))
2032
+ }
2033
+ return result
2034
+ }
2035
+
2036
+ async function runTick(rt, options = {}) {
1104
2037
  reloadBoardIfStale(rt)
1105
2038
  const now = Date.now()
1106
2039
  rt.poll.lastRunAt = iso(now)
2040
+ // 归档清理(§1.2)必须在 pollEnabled 判断之前:暂停派发时归档仍要按时删除。
2041
+ pruneArchivedBoard(rt, now)
1107
2042
  const config = normalizeConfig(rt.state.config)
1108
2043
  if (!config.pollEnabled && !options.taskId) {
1109
2044
  rt.poll.lastSkipReason = 'poll-disabled'
@@ -1121,13 +2056,22 @@ export async function tick(rt, options = {}) {
1121
2056
  return { dispatched: false, reason: 'no-candidate' }
1122
2057
  }
1123
2058
  }
1124
- const agents = typeof rt.ctx.get === 'function' ? rt.ctx.get('agents') : undefined
2059
+ const agents = serviceOf(rt.ctx, 'agents')
2060
+
2061
+ // v0.2.0 默认:按任务工作区投给该工作区的常驻组长(§1.5)。绝不每任务新建会话。
2062
+ if (config.dispatchMode === 'workspace-lead') {
2063
+ const picked = await pickWorkspaceLeadTarget(rt, candidates, config, agents, options, now)
2064
+ if (!picked) return { dispatched: false, reason: rt.poll.lastSkipReason || 'lead-unavailable' }
2065
+ return deliverBoardTask(rt, picked.task, picked.agent, now)
2066
+ }
2067
+
2068
+ // 兼容模式(new / creator / auto,§1.7):沿用旧路由。
1125
2069
  const presetOf = (agent) => sessionPresetOfContext(rt.ctx, agent)
1126
2070
 
1127
2071
  // 逐条试:某个任务的目标会话正忙时跳过它,继续看下一条,避免「一个忙会话挡住整列任务」。
1128
2072
  let task = null
1129
2073
  let resolved = { agent: null, reason: null }
1130
- const mode = config.dispatchMode || 'new'
2074
+ const mode = config.dispatchMode
1131
2075
  for (const candidate of candidates) {
1132
2076
  // 默认「派发到新对话」:在任务工作区新建一个派单模式会话,任务不会被塞进别人的对话里。
1133
2077
  if (mode === 'new') {
@@ -1167,20 +2111,28 @@ export async function tick(rt, options = {}) {
1167
2111
  break
1168
2112
  }
1169
2113
  if (!task) return { dispatched: false, reason: rt.poll.lastSkipReason || 'no-live-agent' }
1170
- const sessionId = agentSessionId(resolved.agent)
2114
+ return deliverBoardTask(rt, task, resolved.agent, now)
2115
+ }
2116
+
2117
+ /**
2118
+ * 投递一条任务给目标 Agent(旧模式 / 工作区组长共用):
2119
+ * followup + sessions.flush 成功后置 doing、记通知与 dispatchedSession*、清 lastError。
2120
+ */
2121
+ async function deliverBoardTask(rt, task, agent, now) {
2122
+ const sessionId = agentSessionId(agent)
1171
2123
  // 创建时没能解析出工作区(会话还没 live)→ 投递前从目标会话补一次,派发文本就能带上工作目录。
1172
2124
  if (!task.cwd) {
1173
- const cwd = sessionCwd(resolved.agent)
2125
+ const cwd = sessionCwd(agent)
1174
2126
  if (cwd) task.cwd = cwd
1175
2127
  }
1176
2128
  const message = createBoardUserMessage(buildDispatchText(task, now))
1177
2129
  try {
1178
- resolved.agent.followup(message)
2130
+ agent.followup(message)
1179
2131
  // 关键:等 inbox splice 落盘再记账,否则重启会丢消息但 notificationCount 已 +1。
1180
2132
  // 官方 dsh-schedule 的投递路径同样在 followup 之后 await sessions.flush。
1181
2133
  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)
2134
+ const sessions = serviceOf(rt.ctx, 'sessions')
2135
+ if (sessions && typeof sessions.flush === 'function') await sessions.flush(agent.session)
1184
2136
  } catch (flushError) {
1185
2137
  console.warn('[taskboard] 会话 flush 失败(消息已入队):' + describeError(flushError))
1186
2138
  }
@@ -1204,16 +2156,578 @@ export async function tick(rt, options = {}) {
1204
2156
  }
1205
2157
  rt.poll.lastDispatchAt = iso(now)
1206
2158
  rt.poll.lastDispatchSessionId = sessionId
1207
- rt.poll.lastDispatchSessionTitle = sessionTitle(resolved.agent)
2159
+ rt.poll.lastDispatchSessionTitle = sessionTitle(agent)
1208
2160
  task.dispatchedSessionId = sessionId
1209
- task.dispatchedSessionTitle = sessionTitle(resolved.agent) || ''
2161
+ task.dispatchedSessionTitle = sessionTitle(agent) || ''
1210
2162
  rt.poll.lastDispatchTaskId = task.id
1211
2163
  rt.poll.lastSkipReason = null
1212
2164
  commitBoard(rt.state, rt.filePath)
1213
2165
  return { dispatched: true, sessionId, task: { ...task } }
1214
2166
  }
1215
2167
 
2168
+ /** RPC `bind-main-session`(§3.1.1):绑定完成回执收件人;不要求会话当前在线。 */
2169
+ export async function bindMainSession(rt, sessionId) {
2170
+ if (typeof sessionId !== 'string' || sessionId.trim() === '') {
2171
+ throw new BoardError('bad-request', 'sessionId 必须是非空字符串')
2172
+ }
2173
+ const id = sessionId.trim()
2174
+ const config = normalizeConfig(rt.state.config)
2175
+ const agents = serviceOf(rt.ctx, 'agents')
2176
+ const title = sessionTitle(liveAgentOf(agents, id))
2177
+ config.mainSessionId = id
2178
+ // 尽力取 live Agent 标题;取不到保留原值 / 空串。
2179
+ if (title !== '') config.mainSessionTitle = title
2180
+ rt.state.config = config
2181
+ commitBoard(rt.state, rt.filePath)
2182
+ return { main: buildMainSessionRef(config, agents, archivedSessionIdSet(rt)) }
2183
+ }
2184
+
2185
+ /** RPC `clear-main-session`(§3.1.1):解除绑定,幂等。 */
2186
+ export async function clearMainSession(rt) {
2187
+ const config = normalizeConfig(rt.state.config)
2188
+ config.mainSessionId = null
2189
+ config.mainSessionTitle = ''
2190
+ rt.state.config = config
2191
+ commitBoard(rt.state, rt.filePath)
2192
+ return { ok: true }
2193
+ }
2194
+
2195
+ /**
2196
+ * RPC `ensure-workspace-lead`(§3.1.1):确保 cwd 所属工作区有可用常驻组长。
2197
+ * 复用已有映射(顺手修复 title/cwd)→ 唤醒冷会话 → 失败则创建新组长替换失效映射。
2198
+ */
2199
+ export async function ensureWorkspaceLead(rt, cwd) {
2200
+ if (typeof cwd !== 'string' || cwd.trim() === '') {
2201
+ throw new BoardError('bad-request', 'cwd 必须是非空字符串')
2202
+ }
2203
+ const target = cwd.trim()
2204
+ const now = Date.now()
2205
+ const key = workspaceKeyForCwd(rt.ctx, target)
2206
+ if (key === '') throw new BoardError('bad-request', '无法从 cwd 解析工作区')
2207
+ const config = normalizeConfig(rt.state.config)
2208
+ let mapping = selectWorkspaceLead(config, key)
2209
+ const agents = serviceOf(rt.ctx, 'agents')
2210
+ // 组长会话被归档 → 视为失效映射:删除它、重排其 doing 任务,随后创建新组长替换。
2211
+ if (mapping && archivedSessionIdSet(rt).has(mapping.sessionId)) {
2212
+ dropWorkspaceLeadMapping(rt, key)
2213
+ requeueTasksOfLead(rt.state, mapping.sessionId, now)
2214
+ commitBoard(rt.state, rt.filePath)
2215
+ console.warn('[taskboard] 工作区组长会话已归档,创建新组长替换:' + key)
2216
+ mapping = null
2217
+ config.workspaceLeads = normalizeConfig(rt.state.config).workspaceLeads
2218
+ }
2219
+ if (mapping) {
2220
+ let agent = liveAgentOf(agents, mapping.sessionId)
2221
+ if (!agent) agent = await resolveAgentForSession(rt, mapping.sessionId)
2222
+ if (agent) {
2223
+ repairWorkspaceLeadMapping(rt, mapping, key, target, agent)
2224
+ return { lead: leadRefFrom(key, mapping, agent) }
2225
+ }
2226
+ // 已有映射但唤醒失败:create 新组长替换(tick 不自动重建,修复走这里)。
2227
+ console.log('[taskboard] 工作区组长 ' + key + ' 唤醒失败,创建新组长替换映射')
2228
+ }
2229
+ const created = await createWorkspaceLeadSession(rt, target, key, now)
2230
+ if (created.error) throw created.error
2231
+ // 会话已创建但 agent 还没物化时照样返回 LeadRef(live=false),UI 状态点会显示离线并可重试。
2232
+ return { lead: leadRefFrom(key, created.entry, created.agent) }
2233
+ }
2234
+
2235
+ /**
2236
+ * 完成回执 flush(§1.6):把 status==='done' && reportedAt=null 的任务合并成一条
2237
+ * 「【任务看板 · 汇报】」消息投给主会话(≤10 条/批,updatedAt 升序)。
2238
+ * 主会话未绑定 / 离线 / 忙 → 本轮不发、不唤醒;投递失败只告警,不写 reportedAt。
2239
+ */
2240
+ export async function flushReceipts(rt, now = Date.now()) {
2241
+ if (!rt || !rt.state) return { sent: false, reason: 'no-state' }
2242
+ if (rt.flushingReceipts) return { sent: false, reason: 'in-flight' }
2243
+ const config = normalizeConfig(rt.state.config)
2244
+ if (!config.mainSessionId) return { sent: false, reason: 'no-main-session' }
2245
+ // 主会话被归档:归档门会拒绝它的模型步进,别投递也别记账(§1.6)。
2246
+ if (archivedSessionIdSet(rt).has(config.mainSessionId)) return { sent: false, reason: 'main-archived' }
2247
+ const batch = selectReceiptTasks(rt.state, MAX_RECEIPT_BATCH)
2248
+ if (batch.length === 0) return { sent: false, reason: 'no-receipt' }
2249
+ const agent = liveAgentOf(serviceOf(rt.ctx, 'agents'), config.mainSessionId)
2250
+ if (!agent) return { sent: false, reason: 'main-offline' }
2251
+ if (agent.status !== 'idle') return { sent: false, reason: 'main-busy' }
2252
+ rt.flushingReceipts = true
2253
+ try {
2254
+ const stamp = iso(now)
2255
+ const message = createBoardUserMessage(buildReceiptText(batch, now))
2256
+ try {
2257
+ agent.followup(message)
2258
+ // 与派发路径一致:等 inbox splice 落盘再记账,避免重启后消息丢了但 reportedAt 已写。
2259
+ try {
2260
+ const sessions = serviceOf(rt.ctx, 'sessions')
2261
+ if (sessions && typeof sessions.flush === 'function') await sessions.flush(agent.session)
2262
+ } catch (flushError) {
2263
+ console.warn('[taskboard] 回执会话 flush 失败(消息已入队):' + describeError(flushError))
2264
+ }
2265
+ } catch (error) {
2266
+ console.warn('[taskboard] 完成回执投递失败:' + describeError(error))
2267
+ return { sent: false, reason: 'followup-failed' }
2268
+ }
2269
+ for (const task of batch) task.reportedAt = stamp
2270
+ commitBoard(rt.state, rt.filePath)
2271
+ return { sent: true, count: batch.length, sessionId: config.mainSessionId }
2272
+ } finally {
2273
+ rt.flushingReceipts = false
2274
+ }
2275
+ }
2276
+
2277
+ /**
2278
+ * 工作区组长路由(§1.5):解析任务 cwd → 工作区 key → 复用/创建常驻组长。
2279
+ * 绝不 createDispatchSession(每任务新建),也绝不跨工作区改派。
2280
+ * @returns {Promise<{ok:true, agent:object, key:string}|{ok:false, reason:string}>}
2281
+ */
2282
+ async function routeWorkspaceLead(rt, task, config, agents, options, now) {
2283
+ let cwd = typeof task.cwd === 'string' && task.cwd !== '' ? task.cwd : null
2284
+ if (!cwd) {
2285
+ // 任务创建时没解析出工作区(会话还没 live / 历史任务)→ 从创建会话补一次。
2286
+ cwd = resolveSessionCwd(rt.ctx, task.sessionId) || (await resolveSessionCwdViaQuery(rt.ctx, task.sessionId))
2287
+ if (cwd) task.cwd = cwd
2288
+ }
2289
+ if (!cwd) return { ok: false, reason: 'lead-no-workspace' }
2290
+ const key = workspaceKeyForCwd(rt.ctx, cwd)
2291
+ if (key === '') return { ok: false, reason: 'lead-no-workspace' }
2292
+ let mapping = selectWorkspaceLead(config, key)
2293
+ // 组长会话被归档(归档门会拒绝它的模型步进)→ 视为失效:删映射、重排它名下 doing
2294
+ // 任务,本轮直接进入「懒创建」分支换一个新组长(§1.5)。绝不 unarchive 用户的归档动作。
2295
+ if (mapping && archivedSessionIdSet(rt).has(mapping.sessionId)) {
2296
+ dropWorkspaceLeadMapping(rt, key)
2297
+ requeueTasksOfLead(rt.state, mapping.sessionId, now)
2298
+ commitBoard(rt.state, rt.filePath)
2299
+ console.warn('[taskboard] 工作区组长会话已归档,重建:' + key)
2300
+ mapping = null
2301
+ config.workspaceLeads = normalizeConfig(rt.state.config).workspaceLeads
2302
+ }
2303
+ if (mapping) {
2304
+ // 已有映射:live → 判忙闲;没有 live → 尝试唤醒(tick 绝不自动重建已有映射)。
2305
+ let agent = liveAgentOf(agents, mapping.sessionId)
2306
+ if (!agent) agent = await resolveAgentForSession(rt, mapping.sessionId)
2307
+ if (!agent) return { ok: false, reason: 'lead-unavailable' }
2308
+ // force(立即派发)时组长忙也把消息排进它的下一轮,与旧模式 creator-busy 的 force 语义一致。
2309
+ if (agent.status !== 'idle' && options.force !== true) return { ok: false, reason: 'lead-busy' }
2310
+ return { ok: true, agent, key }
2311
+ }
2312
+ // 没有映射 → 懒创建本工作区的常驻组长(一个工作区一个,不是每任务一个)。
2313
+ const created = await createWorkspaceLeadSession(rt, cwd, key, now)
2314
+ if (created.error) {
2315
+ console.warn('[taskboard] ' + created.error.message)
2316
+ return { ok: false, reason: 'lead-unavailable' }
2317
+ }
2318
+ // 让本轮后续候选也能看到刚写入的映射,避免同一工作区在同一个 tick 里重复创建组长。
2319
+ if (created.entry) config.workspaceLeads = putWorkspaceLead(config.workspaceLeads, key, created.entry)
2320
+ if (!created.agent) return { ok: false, reason: 'lead-unavailable' }
2321
+ if (created.agent.status !== 'idle' && options.force !== true) return { ok: false, reason: 'lead-busy' }
2322
+ return { ok: true, agent: created.agent, key }
2323
+ }
2324
+
2325
+ /** workspace-lead 模式的候选遍历:组长忙/不可用时写原因并继续下一条候选,成功即结束本轮(每轮最多 1 条)。 */
2326
+ async function pickWorkspaceLeadTarget(rt, candidates, config, agents, options, now) {
2327
+ for (const candidate of candidates) {
2328
+ const cwdBefore = candidate.cwd
2329
+ const route = await routeWorkspaceLead(rt, candidate, config, agents, options, now)
2330
+ if (route.ok) return { task: candidate, agent: route.agent }
2331
+ rt.poll.lastSkipReason = route.reason
2332
+ const text = skipText(route.reason)
2333
+ let changed = candidate.cwd !== cwdBefore
2334
+ if (text !== '' && candidate.lastError !== text) {
2335
+ candidate.lastError = text
2336
+ candidate.updatedAt = iso(now)
2337
+ changed = true
2338
+ }
2339
+ if (changed) commitBoard(rt.state, rt.filePath)
2340
+ }
2341
+ return null
2342
+ }
2343
+
1216
2344
  /** 唤醒失败缓存:同一会话 5 分钟内不重复尝试 resume。 */
2345
+ /* ------------------------------------------------------------------ *
2346
+ * 组长直聊派活 → 自动建看板任务(§1.8)
2347
+ *
2348
+ * 用户可以直接打开工作区组长会话要求它派活(不经过轮询投递):组长 subagent 派 worker 时看板上
2349
+ * 本来没有任务,闭环就断了。这里用两条**事件监听**补一条任务(不改任何工具定义):
2350
+ * - tools/result(观察事件)→ `exec.name === 'subagent'` 成功返回 {kind:'activation', subagentId} 且
2351
+ * 调用方是工作区组长 → 建一条 doing 任务(assignee = worker 会话 id,autoDispatch = 'lead-dispatch');
2352
+ * - subagent/end(生命周期事件)→ 按 assignee 找回**带标记的**任务,worker completed 就置 done +
2353
+ * result 并 flush 完成回执;其它 / 缺省 stopReason 只写**任务** lastError、任务保持 doing。
2354
+ * 轮询投递任务没有标记(notifiedAt 非空),宿主绝不自动收尾——那是组长审核 + 打回的范围。
2355
+ *
2356
+ * 标准 tool-call 与 PTC(run_code)都经过同一个 ToolExecutionPipeline,因此挂钩对两种模式等价;
2357
+ * 绕过 tools 管线直调 ctx.subagents.startActivation() 的第三方插件不覆盖(§1.8 适用边界)。
2358
+ * 建任务 / 回写失败只记 leadAuto.lastError(只装挂钩自身异常),绝不阻断派发。
2359
+ * ------------------------------------------------------------------ */
2360
+
2361
+ /** 组长直聊派活挂钩的运行时视图(不落盘,进 Snapshot.leadAuto)。 */
2362
+ export function createLeadAutoState(now = Date.now()) {
2363
+ return {
2364
+ enabled: false,
2365
+ created: 0,
2366
+ deduped: 0,
2367
+ completed: 0,
2368
+ skipped: 0,
2369
+ lastError: '',
2370
+ lastErrorAt: null,
2371
+ lastTaskId: null,
2372
+ lastWorkerSessionId: null,
2373
+ updatedAt: iso(now),
2374
+ }
2375
+ }
2376
+
2377
+ function counterOf(value) {
2378
+ const num = Number(value)
2379
+ return Number.isFinite(num) ? Math.max(0, Math.round(num)) : 0
2380
+ }
2381
+
2382
+ /** 规范化 Snapshot.leadAuto:老 runtime / 缺字段也能安全读取。 */
2383
+ export function normalizeLeadAuto(raw) {
2384
+ const source = isPlainObject(raw) ? raw : {}
2385
+ return {
2386
+ enabled: source.enabled === true,
2387
+ created: counterOf(source.created),
2388
+ deduped: counterOf(source.deduped),
2389
+ completed: counterOf(source.completed),
2390
+ skipped: counterOf(source.skipped),
2391
+ lastError: trimmed(source.lastError, 500),
2392
+ lastErrorAt: asString(source.lastErrorAt) || null,
2393
+ lastTaskId: asString(source.lastTaskId) || null,
2394
+ lastWorkerSessionId: asString(source.lastWorkerSessionId) || null,
2395
+ updatedAt: asString(source.updatedAt) || null,
2396
+ }
2397
+ }
2398
+
2399
+ function ensureLeadAuto(rt) {
2400
+ if (!isPlainObject(rt.leadAuto)) rt.leadAuto = createLeadAutoState()
2401
+ return rt.leadAuto
2402
+ }
2403
+
2404
+ /** 挂钩失败统一入口:只记 lastError + console.warn,绝不抛出(§1.8 失败不阻断派发)。 */
2405
+ function recordLeadAutoError(rt, message, now = Date.now()) {
2406
+ const auto = ensureLeadAuto(rt)
2407
+ auto.lastError = trimmed(message, 500)
2408
+ auto.lastErrorAt = iso(now)
2409
+ auto.updatedAt = iso(now)
2410
+ console.warn('[taskboard] ' + auto.lastError)
2411
+ }
2412
+
2413
+ /** worker 会话 id(= 任务 assignee)对应的**宿主自动建**任务:同一 worker 只建一条(§1.8 去重)。 */
2414
+ export function findTaskByWorker(state, workerSessionId) {
2415
+ const id = trimmed(workerSessionId, 200)
2416
+ if (!state || !Array.isArray(state.tasks) || id === '') return null
2417
+ for (let i = state.tasks.length - 1; i >= 0; i--) {
2418
+ const task = state.tasks[i]
2419
+ if (!task || task.assignee !== id) continue
2420
+ // 只认带标记的任务:轮询投递任务的 assignee 也可能被组长写成 worker 会话 id,
2421
+ // 那是组长审核的对象,绝不能被宿主自动收尾(§1.8 完成回写)。
2422
+ if (task.autoDispatch !== LEAD_AUTO_MARK) continue
2423
+ return task
2424
+ }
2425
+ return null
2426
+ }
2427
+
2428
+ /** 这条任务是不是 §1.8 挂钩自动建的(只有它们才允许 `subagent/end` 自动置 done)。 */
2429
+ export function isLeadAutoTask(task) {
2430
+ return isPlainObject(task) && task.autoDispatch === LEAD_AUTO_MARK
2431
+ }
2432
+
2433
+ /**
2434
+ * 该组长名下「轮询投递」的进行中任务(= 它正在处理看板任务,别为同一次派发再建一条)。
2435
+ * 只看 notifiedAt 非空的任务:宿主自动建的直聊任务 notifiedAt 为 null,不会挡住下一次直聊派活。
2436
+ * 超过 `LEAD_IN_FLIGHT_TTL_MS` 没有更新(worker 长跑 / 组长卡死)视为陈旧、不再挡住直聊派活(§1.8)。
2437
+ */
2438
+ export function findLeadInFlightTask(state, leadSessionId, now = Date.now()) {
2439
+ const id = typeof leadSessionId === 'string' ? leadSessionId.trim() : ''
2440
+ if (!state || !Array.isArray(state.tasks) || id === '') return null
2441
+ const hit =
2442
+ state.tasks.find(
2443
+ (task) => task && task.status === 'doing' && task.dispatchedSessionId === id && asString(task.notifiedAt) !== '',
2444
+ ) || null
2445
+ if (!hit) return null
2446
+ const stamp = Date.parse(asString(hit.updatedAt) || asString(hit.startedAt) || asString(hit.notifiedAt))
2447
+ if (Number.isFinite(stamp) && now - stamp > LEAD_IN_FLIGHT_TTL_MS) return null
2448
+ return hit
2449
+ }
2450
+
2451
+ /** subagent 工具的 prompt 入参取文本(字符串或 ContentBlock[],防御式)。 */
2452
+ export function subagentPromptText(args) {
2453
+ if (!isPlainObject(args)) return ''
2454
+ const prompt = args.prompt
2455
+ if (typeof prompt === 'string') return prompt
2456
+ if (!Array.isArray(prompt)) return ''
2457
+ return prompt
2458
+ .map((block) => (block && block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
2459
+ .filter((text) => text !== '')
2460
+ .join('\n')
2461
+ }
2462
+
2463
+ /** 派发摘要里的第一行:跳过纯装饰行(分隔线),去掉行首 Markdown 标记(`#` / `- ` / `* ` / `> `)。 */
2464
+ export function firstDispatchLine(text) {
2465
+ const source = typeof text === 'string' ? text : ''
2466
+ if (source === '') return ''
2467
+ for (const raw of source.split(/\r?\n/)) {
2468
+ const line = raw.trim()
2469
+ if (line === '' || /^[\s#>*+\-=_]+$/.test(line)) continue
2470
+ return line.replace(/^(?:#{1,6}\s+|[-*+>]\s+)/, '').trim()
2471
+ }
2472
+ return ''
2473
+ }
2474
+
2475
+ /** 自动建任务的标题:description → prompt 第一行 → 「worker <尾 8>」。 */
2476
+ export function leadTaskTitle(args, childId = '') {
2477
+ const description = isPlainObject(args) ? trimmed(args.description, MAX_TITLE_CHARS) : ''
2478
+ if (description !== '') return description
2479
+ const line = trimmed(firstDispatchLine(subagentPromptText(args)), MAX_TITLE_CHARS)
2480
+ if (line !== '') return line
2481
+ const tail = trimmed(childId, 200).slice(-8)
2482
+ return tail === '' ? 'worker' : 'worker ' + tail
2483
+ }
2484
+
2485
+ /** subagent/end 里的最终回答文本(写进任务 result)。 */
2486
+ export function workerResultText(info) {
2487
+ const blocks = info && info.lastAssistantMessage
2488
+ if (!Array.isArray(blocks)) return ''
2489
+ const text = blocks
2490
+ .map((block) => (block && block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
2491
+ .filter((part) => part !== '')
2492
+ .join('\n')
2493
+ .trim()
2494
+ return truncateNote(text, MAX_NOTE_CHARS)
2495
+ }
2496
+
2497
+ /**
2498
+ * cwd → 工作区注册表里的规范 path(§1.8 建任务的 workspace):
2499
+ * `workspaceIdForCwd` 命中时用 registry 的 `path`,让看板的工作区过滤与注册表一致;
2500
+ * 命中不了(没注册表 / 不属于任何工作区)就原样返回 cwd。
2501
+ */
2502
+ export function workspacePathForCwd(ctx, cwd) {
2503
+ const raw = typeof cwd === 'string' ? cwd : ''
2504
+ const id = workspaceIdForCwd(ctx, raw)
2505
+ if (id === '') return raw
2506
+ try {
2507
+ const registry = serviceOf(ctx, 'workspaceRegistry')
2508
+ const list = registry && typeof registry.list === 'function' ? registry.list() : []
2509
+ const hit = Array.isArray(list)
2510
+ ? list.find((workspace) => workspace && workspace.id === id && typeof workspace.path === 'string' && workspace.path !== '')
2511
+ : undefined
2512
+ if (hit) return hit.path
2513
+ } catch {
2514
+ /* 退回原 cwd */
2515
+ }
2516
+ return raw
2517
+ }
2518
+
2519
+ /**
2520
+ * tools/result 命中「工作区组长成功派出 worker」时建一条看板任务(§1.8)。
2521
+ * 只做副作用:永不抛出(失败只记 leadAuto.lastError),不阻断派发。
2522
+ * @param {{agent:object, childId:string, args?:object}} input
2523
+ * @returns {{created:boolean, reason?:string, taskId?:string, task?:object}}
2524
+ */
2525
+ export function handleSubagentDispatch(rt, input, now = Date.now()) {
2526
+ const auto = ensureLeadAuto(rt)
2527
+ try {
2528
+ const agent = input && input.agent
2529
+ const childId = trimmed(input && input.childId, 200)
2530
+ if (!agent || childId === '') {
2531
+ auto.skipped += 1
2532
+ auto.updatedAt = iso(now)
2533
+ return { created: false, reason: 'skipped' }
2534
+ }
2535
+ // 只认工作区组长(taskboard-dispatch)的派发:普通会话派子 Agent 不进看板。
2536
+ if (sessionPresetOfContext(rt.ctx, agent) !== DISPATCH_PRESET_ID) {
2537
+ auto.skipped += 1
2538
+ auto.updatedAt = iso(now)
2539
+ return { created: false, reason: 'not-lead' }
2540
+ }
2541
+ reloadBoardIfStale(rt)
2542
+ const existing = findTaskByWorker(rt.state, childId)
2543
+ if (existing) {
2544
+ auto.deduped += 1
2545
+ auto.updatedAt = iso(now)
2546
+ return { created: false, reason: 'dedup-worker', taskId: existing.id }
2547
+ }
2548
+ const sessionId = agentSessionId(agent) || ''
2549
+ const inFlight = findLeadInFlightTask(rt.state, sessionId, now)
2550
+ if (inFlight) {
2551
+ // 组长正在处理轮询投递来的看板任务(且未陈旧):这次 subagent 就是那条任务的 worker,别再建一条。
2552
+ auto.deduped += 1
2553
+ auto.updatedAt = iso(now)
2554
+ return { created: false, reason: 'lead-task-in-flight', taskId: inFlight.id }
2555
+ }
2556
+ const args = input && input.args
2557
+ const title = leadTaskTitle(args, childId)
2558
+ const note = truncateNote(subagentPromptText(args), MAX_NOTE_CHARS)
2559
+ // workspace = 组长当前工作区(cwd 映射:header.cwd → sessions 服务 → 派发入参 cwd),
2560
+ // 命中工作区注册表时用注册表的规范 path(workspaceIdForCwd,§1.8)。
2561
+ const rawCwd = sessionCwd(agent) || resolveSessionCwd(rt.ctx, sessionId) || (isPlainObject(args) ? asString(args.cwd) : '')
2562
+ const cwd = workspacePathForCwd(rt.ctx, rawCwd)
2563
+ const task = addTask(rt.state, { title, note, source: 'agent', sessionId, cwd }, now)
2564
+ applyTaskUpdate(rt.state, task.id, { status: 'doing', assignee: childId }, now)
2565
+ // 持久化标记:只有带这个标记的任务才允许 subagent/end 自动收尾(§1.8 / §2)。
2566
+ task.autoDispatch = LEAD_AUTO_MARK
2567
+ task.dispatchedSessionId = sessionId || null
2568
+ task.dispatchedSessionTitle = sessionTitle(agent)
2569
+ task.lastError = ''
2570
+ task.updatedAt = iso(now)
2571
+ const saved = commitBoard(rt.state, rt.filePath)
2572
+ auto.created += 1
2573
+ auto.lastTaskId = task.id
2574
+ auto.lastWorkerSessionId = childId
2575
+ auto.updatedAt = iso(now)
2576
+ if (saved && saved.saved === false) {
2577
+ // 写盘失败不删任务(内存仍是真源),只记错误,派发照常继续。
2578
+ recordLeadAutoError(rt, '看板写盘失败(任务只在内存里):' + (saved.error || ''), now)
2579
+ } else {
2580
+ console.log('[taskboard] 组长直聊派活已建任务:' + task.id + ' ← worker 会话 ' + childId)
2581
+ }
2582
+ return { created: true, taskId: task.id, task: { ...task } }
2583
+ } catch (error) {
2584
+ recordLeadAutoError(rt, '自动建看板任务失败:' + describeError(error), now)
2585
+ return { created: false, reason: 'error', error: describeError(error) }
2586
+ }
2587
+ }
2588
+
2589
+ /**
2590
+ * subagent/end:worker 结束 → **宿主自动建的任务**置 done + result(§1.8),并 flush 完成回执(§1.6)。
2591
+ * 只认带 `autoDispatch === 'lead-dispatch'` 标记的任务:轮询投递任务的 assignee 也可能被组长写成 worker
2592
+ * 会话 id,那是组长审核的对象,宿主绝不抢先置 done(否则组长来不及取证、也无法打回)。
2593
+ * `stopReason` 只认精确的 'completed':缺字段 / 未知值一律按非 completed 处理(保持 doing + 写 lastError)。
2594
+ * 非 completed 只写**任务** lastError(`leadAuto.lastError` 只记挂钩自身异常);找不到任务直接忽略。
2595
+ */
2596
+ export async function handleSubagentEnd(rt, info, now = Date.now()) {
2597
+ const auto = ensureLeadAuto(rt)
2598
+ try {
2599
+ const childId = trimmed(info && info.id, 200)
2600
+ if (childId === '') {
2601
+ auto.skipped += 1
2602
+ auto.updatedAt = iso(now)
2603
+ return { updated: false, reason: 'skipped' }
2604
+ }
2605
+ reloadBoardIfStale(rt)
2606
+ const task = findTaskByWorker(rt.state, childId)
2607
+ if (!task) {
2608
+ // 不是宿主建的自动任务(例如组长审核时派去跑命令的验证子 Agent,
2609
+ // 或轮询投递任务的 worker——那条任务的 autoDispatch 为 null)。
2610
+ auto.skipped += 1
2611
+ auto.updatedAt = iso(now)
2612
+ return { updated: false, reason: 'no-task' }
2613
+ }
2614
+ if (!isLeadAutoTask(task) || asString(task.notifiedAt) !== '') {
2615
+ // 兜底:findTaskByWorker 已经过滤过,这里再挡一层,确保轮询任务(notifiedAt 非空)永不被自动 done。
2616
+ auto.skipped += 1
2617
+ auto.updatedAt = iso(now)
2618
+ return { updated: false, reason: 'not-auto', taskId: task.id }
2619
+ }
2620
+ const result = workerResultText(info)
2621
+ // 缺字段 / 空串 / 未知值一律按非 completed 处理(绝不静默置 done):文案里缺省写 unknown。
2622
+ const rawStopReason = asString(info && info.stopReason).trim()
2623
+ const stopReason = rawStopReason === '' ? 'unknown' : rawStopReason
2624
+ const wasDoing = task.status === 'doing'
2625
+ if (stopReason !== 'completed') {
2626
+ if (!wasDoing) {
2627
+ // 组长已审(done)或任务不在这两个状态:worker 的失败不推翻结论,也不改状态。
2628
+ auto.skipped += 1
2629
+ auto.updatedAt = iso(now)
2630
+ return { updated: false, reason: 'worker-' + stopReason, taskId: task.id }
2631
+ }
2632
+ const detail = result === '' ? '没有返回结论' : flattenResultLine(result, RECEIPT_RESULT_CHARS)
2633
+ task.lastError = trimmed('worker 结束(' + stopReason + '):' + detail, 500)
2634
+ task.updatedAt = iso(now)
2635
+ commitBoard(rt.state, rt.filePath)
2636
+ // 只写任务 lastError;leadAuto.lastError 语义是「挂钩自身失败原因」,不装派发结果。
2637
+ auto.lastTaskId = task.id
2638
+ auto.updatedAt = iso(now)
2639
+ console.warn('[taskboard] ' + task.lastError)
2640
+ return { updated: false, reason: 'worker-' + stopReason, taskId: task.id }
2641
+ }
2642
+ if (task.status !== 'doing' && task.status !== 'done') {
2643
+ auto.skipped += 1
2644
+ auto.updatedAt = iso(now)
2645
+ return { updated: false, reason: 'status-' + task.status, taskId: task.id }
2646
+ }
2647
+ const patch = {}
2648
+ if (result !== '') patch.result = result
2649
+ // doing → done;已是 done(组长先审完 / 同一 worker 再次结束)就只刷新 result。
2650
+ if (wasDoing) patch.status = 'done'
2651
+ if (Object.keys(patch).length === 0) {
2652
+ auto.skipped += 1
2653
+ auto.updatedAt = iso(now)
2654
+ return { updated: false, reason: 'no-change', taskId: task.id }
2655
+ }
2656
+ applyTaskUpdate(rt.state, task.id, patch, now)
2657
+ task.lastError = ''
2658
+ task.updatedAt = iso(now)
2659
+ commitBoard(rt.state, rt.filePath)
2660
+ // 只在真正的 doing→done 时计数;第二次结束只刷 result,不算又一次完成。
2661
+ if (wasDoing) auto.completed += 1
2662
+ auto.lastTaskId = task.id
2663
+ auto.lastWorkerSessionId = childId
2664
+ auto.updatedAt = iso(now)
2665
+ if (!wasDoing) {
2666
+ // 只刷新了 result:不重发回执(reportedAt 不变),flush 也不会把它再挑出来。
2667
+ return { updated: true, taskId: task.id, status: task.status, refreshed: true }
2668
+ }
2669
+ // 沿用 §1.6 完成回执链路(主会话未绑定 / 离线 / 忙时是 no-op)。
2670
+ try {
2671
+ await flushReceipts(rt, now)
2672
+ } catch (error) {
2673
+ console.warn('[taskboard] 完成回执 flush 失败:' + describeError(error))
2674
+ }
2675
+ return { updated: true, taskId: task.id, status: task.status }
2676
+ } catch (error) {
2677
+ recordLeadAutoError(rt, 'worker 完成回写失败:' + describeError(error), now)
2678
+ return { updated: false, reason: 'error', error: describeError(error) }
2679
+ }
2680
+ }
2681
+
2682
+ /**
2683
+ * 注册 §1.8 的两条事件挂钩。只挂监听、不需要任何服务就绪;
2684
+ * `{ global: true }` 跳过 Cordis 的 scope 过滤(carrier 按调用 Agent 过滤),事件量极小,
2685
+ * 真正的过滤在 handler 里按预设 / assignee 做。监听器由插件 fiber 自动回收。
2686
+ * 注意:第三参 `{ global: true }` 是**必需**的(少了就收不到事件),单测必须断言它。
2687
+ * @returns {boolean} 是否注册成功
2688
+ */
2689
+ export function registerLeadAutoHooks(ctx, rt) {
2690
+ if (!ctx || typeof ctx.on !== 'function') {
2691
+ console.warn('[taskboard] ctx.on 不可用,跳过组长直聊派活挂钩')
2692
+ return false
2693
+ }
2694
+ ctx.on(
2695
+ 'tools/result',
2696
+ (exec, result) => {
2697
+ try {
2698
+ // §1.8 命中条件(三个条件缺一不可,避免别的工具输出里恰好带 subagentId 就误建任务):
2699
+ // exec.name === 'subagent' + 非错误结果 + value 是 {kind:'activation', subagentId}。
2700
+ if (!exec || exec.name !== 'subagent') return
2701
+ if (!result || result.isError === true) return
2702
+ const value = result.value
2703
+ if (!isPlainObject(value) || value.kind !== 'activation') return
2704
+ const childId = typeof value.subagentId === 'string' ? value.subagentId.trim() : ''
2705
+ if (childId === '') return
2706
+ const agent = exec.agent
2707
+ if (!agent) return
2708
+ handleSubagentDispatch(rt, { agent, childId, args: exec.arguments })
2709
+ } catch (error) {
2710
+ recordLeadAutoError(rt, '组长直聊派活挂钩失败:' + describeError(error))
2711
+ }
2712
+ },
2713
+ { global: true },
2714
+ )
2715
+ ctx.on(
2716
+ 'subagent/end',
2717
+ (info) => {
2718
+ Promise.resolve()
2719
+ .then(() => handleSubagentEnd(rt, info))
2720
+ .catch((error) => recordLeadAutoError(rt, 'worker 完成挂钩失败:' + describeError(error)))
2721
+ },
2722
+ { global: true },
2723
+ )
2724
+ const auto = ensureLeadAuto(rt)
2725
+ auto.enabled = true
2726
+ auto.updatedAt = iso(Date.now())
2727
+ return true
2728
+ }
2729
+
2730
+ /** 冷会话唤醒失败的负缓存时长(5 分钟)。 */
1217
2731
  const REVIVE_RETRY_MS = 5 * 60 * 1000
1218
2732
 
1219
2733
  /**
@@ -1400,7 +2914,7 @@ export const TASK_ONE_OUTPUT_SCHEMA = {
1400
2914
  * 注册三个模型工具。宿主级注册 = 全局可见(所有预设的 Agent 都能用),
1401
2915
  * 这也是「非派单模式也能往看板里塞任务」的实现方式。
1402
2916
  */
1403
- function registerTools(toolCtx, rt) {
2917
+ export function registerTools(toolCtx, rt) {
1404
2918
  const tools = toolCtx.tools
1405
2919
  if (!tools || typeof tools.register !== 'function') {
1406
2920
  console.warn('[taskboard] tools 服务不可用,跳过模型工具注册')
@@ -1439,7 +2953,8 @@ function registerTools(toolCtx, rt) {
1439
2953
  name: 'taskboard_add',
1440
2954
  description:
1441
2955
  '往任务看板添加一条待开始任务。用户口述的需求、你自己拆出来的后续任务都可以加进看板,' +
1442
- '轮询器会把它派给主 Agent。title 必填,note 写验收标准或补充信息。',
2956
+ '轮询器会把它派给任务所属工作区的常驻组长。title 必填,note 写验收标准或补充信息;' +
2957
+ 'workspace 可选(工作区 id / 名称 / 绝对路径),用于从主会话往其它工作区派任务。',
1443
2958
  parameters: {
1444
2959
  type: 'object',
1445
2960
  additionalProperties: false,
@@ -1447,6 +2962,10 @@ function registerTools(toolCtx, rt) {
1447
2962
  properties: {
1448
2963
  title: { type: 'string', description: '任务标题(一句话,必填)' },
1449
2964
  note: { type: 'string', description: '备注:背景、范围、验收标准' },
2965
+ workspace: {
2966
+ type: 'string',
2967
+ description: '可选:任务所属工作区(工作区 id / 名称 / 绝对路径),省略则用当前会话工作区',
2968
+ },
1450
2969
  },
1451
2970
  },
1452
2971
  output: {
@@ -1456,6 +2975,7 @@ function registerTools(toolCtx, rt) {
1456
2975
  execute(args, exec) {
1457
2976
  const title = trimmed(args && args.title, MAX_TITLE_CHARS)
1458
2977
  if (title === '') throw new Error('title 不能为空')
2978
+ if (typeof (args && args.note) === 'string') assertNoteAttachments(args.note)
1459
2979
  let sessionId = null
1460
2980
  let cwd = null
1461
2981
  try {
@@ -1468,6 +2988,13 @@ function registerTools(toolCtx, rt) {
1468
2988
  } catch {
1469
2989
  /* 非 agent 调用时忽略 */
1470
2990
  }
2991
+ // v0.2.0:workspace 参数(§4.4)——绝对路径直接用,否则按注册表 id / 名称 / 路径解析。
2992
+ const workspaceArg = trimmed(args && args.workspace, 500)
2993
+ if (workspaceArg !== '') {
2994
+ const resolved = resolveWorkspaceTarget(workspaceArg, listWorkspaces(rt))
2995
+ if (resolved === '') throw new Error('未知工作区:' + workspaceArg)
2996
+ cwd = resolved
2997
+ }
1471
2998
  const task = addTask(rt.state, { title, note: args && args.note, source: 'agent', sessionId, cwd })
1472
2999
  commitBoard(rt.state, rt.filePath)
1473
3000
  return Promise.resolve({ task: taskBrief(task) })
@@ -1494,15 +3021,18 @@ function registerTools(toolCtx, rt) {
1494
3021
  schema: TASK_ONE_OUTPUT_SCHEMA,
1495
3022
  render: (_args, value) => renderTaskOne('已更新任务 ', value.task),
1496
3023
  },
1497
- execute(args) {
3024
+ async execute(args) {
1498
3025
  if (!args || !args.id) throw new Error('缺少任务 id')
1499
3026
  const patch = {}
1500
3027
  for (const key of ['status', 'result', 'assignee', 'note']) {
1501
3028
  if (args[key] !== undefined) patch[key] = args[key]
1502
3029
  }
3030
+ if (typeof patch.note === 'string') assertNoteAttachments(patch.note)
1503
3031
  const task = applyTaskUpdate(rt.state, args.id, patch)
1504
3032
  commitBoard(rt.state, rt.filePath)
1505
- return Promise.resolve({ task: taskBrief(task) })
3033
+ // 任务刚变成 done(或从 done 重开):顺手尝试 flush 完成回执(§1.6 flush 时机)。
3034
+ await flushReceipts(rt)
3035
+ return { task: taskBrief(task) }
1506
3036
  },
1507
3037
  })
1508
3038
  console.log('[taskboard] 模型工具已注册:taskboard_list / taskboard_add / taskboard_update')
@@ -1523,13 +3053,19 @@ export function apply(ctx) {
1523
3053
  presetInfo: null,
1524
3054
  presetInfoAt: 0,
1525
3055
  reviveFailures: new Map(),
3056
+ // 完成回执 flush 的并发保护:tick / RPC / 工具可能同时触发,避免同一批任务重复投递。
3057
+ flushingReceipts: false,
1526
3058
  poll: {
1527
3059
  running: false,
1528
3060
  lastRunAt: null,
1529
3061
  lastDispatchAt: null,
3062
+ lastDispatchTaskId: null,
1530
3063
  lastDispatchSessionId: null,
3064
+ lastDispatchSessionTitle: null,
1531
3065
  lastSkipReason: null,
1532
3066
  },
3067
+ // 组长直聊派活自动建任务(§1.8)的运行时计数 / 最近错误。
3068
+ leadAuto: createLeadAutoState(),
1533
3069
  }
1534
3070
 
1535
3071
  try {
@@ -1541,6 +3077,10 @@ export function apply(ctx) {
1541
3077
  console.warn('[taskboard] 读取看板失败,从空板开始:' + describeError(error))
1542
3078
  }
1543
3079
 
3080
+ // 启动时清一次过期归档(§1.2):宿主停机期间到期的归档不必等第一个 tick。
3081
+ // 只在真的有删除时写盘(pruneArchivedBoard 内部判断),因此没有副作用地复用同一路径。
3082
+ pruneArchivedBoard(runtime, Date.now())
3083
+
1544
3084
  // 模式状态:agentPresets 服务就绪后读名单(预设本身由 bundle patch 声明,不在这里安装)。
1545
3085
  // 预设行的激活是异步的,所以前几次读不到不算失败——最多重试 3 次再告警。
1546
3086
  try {
@@ -1623,4 +3163,14 @@ export function apply(ctx) {
1623
3163
  } catch (error) {
1624
3164
  console.warn('[taskboard] tools 服务注入失败:' + describeError(error))
1625
3165
  }
3166
+
3167
+ // 组长直聊派活 → 自动建看板任务(§1.8):只挂事件监听,不依赖任何服务就绪;
3168
+ // 监听器由插件 fiber 自动回收,失败也不阻断派发(只记 leadAuto.lastError)。
3169
+ try {
3170
+ if (registerLeadAutoHooks(ctx, runtime)) {
3171
+ console.log('[taskboard] 组长直聊派活挂钩已注册:tools/result + subagent/end')
3172
+ }
3173
+ } catch (error) {
3174
+ console.warn('[taskboard] 组长直聊派活挂钩注册失败:' + describeError(error))
3175
+ }
1626
3176
  }