dsh-workplan 3.0.3 → 3.0.9
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/CHANGELOG.md +76 -0
- package/README.en.md +15 -7
- package/README.md +32 -20
- package/README.zh.md +8 -7
- package/client.js +181 -27
- package/docs/release-notes-3.0.3.md +7 -0
- package/docs/release-notes-3.0.9.md +7 -0
- package/lib/approval-gate.js +79 -3
- package/lib/client.js +181 -27
- package/lib/comm-format.js +6 -6
- package/lib/dept-journal.js +223 -6
- package/lib/{three-phase.js → five-step.js} +210 -134
- package/lib/host.js +316 -79
- package/lib/lessons.js +87 -19
- package/lib/llm-rules.js +25 -82
- package/lib/notice-ledger.js +238 -0
- package/lib/plan.js +275 -68
- package/lib/runtime.js +747 -161
- package/lib/understanding.js +85 -6
- package/lib/v3-contract.js +48 -15
- package/package.json +2 -3
- package/src/approval-gate.ts +77 -3
- package/src/client.ts +178 -24
- package/src/comm-format.ts +6 -6
- package/src/dept-journal.ts +219 -7
- package/src/{three-phase.ts → five-step.ts} +236 -169
- package/src/host.ts +316 -79
- package/src/lessons.ts +92 -19
- package/src/llm-rules.ts +30 -101
- package/src/notice-ledger.ts +251 -0
- package/src/plan.ts +276 -66
- package/src/runtime.ts +800 -159
- package/src/understanding.ts +100 -6
- package/src/v3-contract.ts +49 -16
package/src/comm-format.ts
CHANGED
|
@@ -12,9 +12,9 @@
|
|
|
12
12
|
*
|
|
13
13
|
* 设计约束:
|
|
14
14
|
* - 本模块只做「格式/结构」核验,不做语义真伪判断(F9 为提示词级诚信约束,
|
|
15
|
-
*
|
|
15
|
+
* 由五步证据门禁与人工复核兜底,这里不自动判);
|
|
16
16
|
* - 规范是纯数据,可序列化进提示词,也可独立校验,版本号随内容变更递增;
|
|
17
|
-
* -
|
|
17
|
+
* - 与既有门禁正交:解析失败、验收缺口、五步证据缺失仍由原门禁先拦,
|
|
18
18
|
* 本门禁只负责把「其它门禁都过了、但格式仍不合规」的 done 退回。
|
|
19
19
|
*/
|
|
20
20
|
|
|
@@ -95,10 +95,10 @@ export const COMM_FORMAT_SPEC = Object.freeze({
|
|
|
95
95
|
* 冻结条目,本次只增不改;两条新条目按接收者层级启用(见 check 的 tier)。
|
|
96
96
|
*/
|
|
97
97
|
Object.freeze({ id: 'F10', category: 'report',
|
|
98
|
-
description: '专家(第三层执行者)结果必须包含 report 对象,只允许 keyResults/keyInfo/importantInfo/leadRequirements
|
|
98
|
+
description: '专家(第三层执行者)结果必须包含 report 对象,只允许 keyResults/keyInfo/importantInfo/leadRequirements 四个字符串数组字段:keyResults / leadRequirements 各至少 1 条非空内容,keyInfo / importantInfo 可为空数组但字段必须存在,每数组最多 6 条、每条最多 200 字符,内部与跨字段不得出现重复表述',
|
|
99
99
|
rationale: '用户要求 7:专家成果必须非常精简地汇报给部门负责人,只要关键信息、关键成果、重要信息和负责人要求的东西,并以 JSON mode 结构化输出' }),
|
|
100
100
|
Object.freeze({ id: 'F11', category: 'report',
|
|
101
|
-
description: '部门负责人结果必须包含 departmentSummary 对象,只允许 keyResults/keyInfo/importantInfo/sources 四个字符串数组字段,keyResults 至少 1
|
|
101
|
+
description: '部门负责人结果必须包含 departmentSummary 对象,只允许 keyResults/keyInfo/importantInfo/sources 四个字符串数组字段,keyResults 至少 1 条非空,keyResults/keyInfo/importantInfo 每项最多 6 条、每条最多 200 字符;sources 最多 16 条且必须逐人覆盖本部门全部已派发专家,内部与跨字段不得出现重复表述',
|
|
102
102
|
rationale: '用户要求 8/10/11:部门负责人必须全面汇总全部专家汇报,汇总报告必须精简、禁止累赘重复,并以 JSON mode 结构化直接交回主 Agent' }),
|
|
103
103
|
]),
|
|
104
104
|
/*
|
|
@@ -161,7 +161,7 @@ export function checkCommFormatCompliance(
|
|
|
161
161
|
message: `status 字段缺失或取值非法("${String(parsed.status ?? '')}"),只能是 done / blocked / partial` })
|
|
162
162
|
}
|
|
163
163
|
|
|
164
|
-
// F3:
|
|
164
|
+
// F3: 五步证据齐全(planning / preparation / execution / verification)
|
|
165
165
|
const phases = parsed.phases
|
|
166
166
|
if (!phases || typeof phases !== 'object') {
|
|
167
167
|
violations.push({ ruleId: 'F3', category: 'phases',
|
|
@@ -231,7 +231,7 @@ export function checkCommFormatCompliance(
|
|
|
231
231
|
|
|
232
232
|
/*
|
|
233
233
|
* F10/F11(用户 2026-11-14 第 7、10、11 条):按接收者层级启用。
|
|
234
|
-
* 只拦 done 路径——受阻结果已有更针对性的诊断(F8
|
|
234
|
+
* 只拦 done 路径——受阻结果已有更针对性的诊断(F8/五步证据),
|
|
235
235
|
* 不再叠加精简性条目,避免一条 blocked 被反复退回在格式上。
|
|
236
236
|
*/
|
|
237
237
|
if (options.tier === 'expert' && parsed.status === 'done') {
|
package/src/dept-journal.ts
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
* 由 channel-expert 按契约 §3 实现)。
|
|
17
17
|
*/
|
|
18
18
|
import { randomBytes } from 'node:crypto'
|
|
19
|
-
import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
|
|
19
|
+
import { appendFileSync, chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, statSync, unlinkSync } from 'node:fs'
|
|
20
20
|
import { homedir } from 'node:os'
|
|
21
21
|
import { dirname, join } from 'node:path'
|
|
22
22
|
|
|
@@ -285,11 +285,12 @@ export function deptJournalPath(planId: string): string {
|
|
|
285
285
|
|
|
286
286
|
/**
|
|
287
287
|
* 追加一条留痕(契约 §2):先 validate,再 mkdirSync(recursive)+appendFileSync。
|
|
288
|
-
* 任何失败(校验不过 / planId 非法 /
|
|
288
|
+
* 任何失败(校验不过 / planId 非法 / 写盘失败 / 回读不一致)显式返回
|
|
289
|
+
* JOURNAL_WRITE_FAILED / JOURNAL_READBACK_FAILED,绝不静默。
|
|
289
290
|
*/
|
|
290
291
|
export function appendDeptMessage(
|
|
291
292
|
msg: unknown,
|
|
292
|
-
): { ok: true; path: string } | { ok: false; code: 'JOURNAL_WRITE_FAILED'; error: string } {
|
|
293
|
+
): { ok: true; path: string } | { ok: false; code: 'JOURNAL_WRITE_FAILED' | 'JOURNAL_READBACK_FAILED'; error: string } {
|
|
293
294
|
const verdict = validateDeptMessage(msg)
|
|
294
295
|
if (!verdict.ok) return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: verdict.error }
|
|
295
296
|
let path: string
|
|
@@ -299,25 +300,157 @@ export function appendDeptMessage(
|
|
|
299
300
|
return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: errorText(error) }
|
|
300
301
|
}
|
|
301
302
|
try {
|
|
302
|
-
|
|
303
|
-
|
|
303
|
+
/*
|
|
304
|
+
* [安全加固] 防符号链接投毒:journal 文件若是符号链接则跳过写入并告警——
|
|
305
|
+
* 绝不跟随链接把审计内容写到链接指向的任意路径;失败显式返回(绝不静默)。
|
|
306
|
+
* lstatSync 抛错(文件不存在等)属正常首写场景,交给 appendFileSync 处理。
|
|
307
|
+
*/
|
|
308
|
+
try {
|
|
309
|
+
if (lstatSync(path).isSymbolicLink()) {
|
|
310
|
+
console.warn(`dsh-workplan: journal 文件是符号链接,跳过写入 path=${path}`)
|
|
311
|
+
return {
|
|
312
|
+
ok: false,
|
|
313
|
+
code: 'JOURNAL_WRITE_FAILED',
|
|
314
|
+
error: `JOURNAL_WRITE_FAILED: journal 文件是符号链接,已跳过写入 path=${path}(防链接投毒)。`,
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
} catch {
|
|
318
|
+
/* 文件不存在(首写)或 lstat 失败:继续走正常写入,错误由 appendFileSync 显式上报。 */
|
|
319
|
+
}
|
|
320
|
+
mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
|
|
321
|
+
appendFileSync(path, `${JSON.stringify(verdict.value)}\n`, { encoding: 'utf8', mode: 0o600 })
|
|
322
|
+
try {
|
|
323
|
+
// 既有文件权限收紧为 0o600(best-effort;新建文件已由 mode 覆盖)。
|
|
324
|
+
chmodSync(path, 0o600)
|
|
325
|
+
} catch {
|
|
326
|
+
/* best-effort:权限收紧失败不阻断追加。 */
|
|
327
|
+
}
|
|
304
328
|
} catch (error) {
|
|
305
329
|
return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: errorText(error) }
|
|
306
330
|
}
|
|
331
|
+
/* [T3][回读校验] 写后读回比对关键字段(见下方 helper 注释),不一致绝不静默。 */
|
|
332
|
+
const readback = verifyJournalAppendReadback(path, verdict.value)
|
|
333
|
+
if (!readback.ok) return { ok: false, code: 'JOURNAL_READBACK_FAILED', error: readback.error }
|
|
307
334
|
return { ok: true, path }
|
|
308
335
|
}
|
|
309
336
|
|
|
337
|
+
/*
|
|
338
|
+
* [T3][回读校验] journal 追加写后读回。依据:reports/wp-member-expert-persist-call-T1.json
|
|
339
|
+
* 写盘点⑦(dept-journal.ts:290-308;2026-11-17 复核 mkdirSync:302、appendFileSync:303
|
|
340
|
+
* 无漂移)与 reports/wp-member-expert-storage-T1-storage.json(落盘路径
|
|
341
|
+
* <journalDir>/<planId>.jsonl,事件流追加、非整文件快照)。
|
|
342
|
+
* appendFileSync 成功后读回文件末尾窗口,JSON 解析后比对关键字段(v/id/planId/
|
|
343
|
+
* subtaskId/kind/ts/body 头 120 字摘要)。找不到匹配行 → 返回显式错误码
|
|
344
|
+
* JOURNAL_READBACK_FAILED(本模块「绝不静默」契约=显式错误码+处置指引,与
|
|
345
|
+
* JOURNAL_WRITE_FAILED 同口径;负责人硬性要求③的「抛显式错误」在本模块以
|
|
346
|
+
* 显式错误码实现,错误信息含文件路径与期望/实际摘要及指引:重试或让主 Agent
|
|
347
|
+
* 手动制定计划)。纯读校验、不写盘 → 幂等(硬性要求④)。
|
|
348
|
+
*
|
|
349
|
+
* [复审修复][O(n²)→O(窗口)] journal 默认永久保留,文件会涨到 MB 级;旧实现每次
|
|
350
|
+
* 追加后 readFileSync 整个文件逐行 parse,热路径每次请示/指示/完成/预估都全文件
|
|
351
|
+
* 重读。改为只读末尾一个窗口(JOURNAL_READBACK_WINDOW_BYTES):
|
|
352
|
+
* - O_APPEND 保证刚写入的行必在文件末尾;窗口 ≥ 单行最大体积(body ≤4000 字符 +
|
|
353
|
+
* data JSON ≤4000 字符,单 line 远小于 64KB)即可命中;
|
|
354
|
+
* - 窗口起点可能落在行中间 → 首行 parse 失败直接跳过该坏行继续;
|
|
355
|
+
* - 并发追加交错不会把新行挤出窗口(需同一瞬时有 64KB 更新行写入才会,
|
|
356
|
+
* 概率可忽略;且失败显式可重试)。
|
|
357
|
+
*/
|
|
358
|
+
function deptMessageKeyDigest(record: any): string {
|
|
359
|
+
return JSON.stringify({
|
|
360
|
+
v: record?.v,
|
|
361
|
+
id: record?.id,
|
|
362
|
+
planId: record?.planId,
|
|
363
|
+
subtaskId: record?.subtaskId,
|
|
364
|
+
kind: record?.kind,
|
|
365
|
+
ts: record?.ts,
|
|
366
|
+
bodyHead: String(record?.body ?? '').slice(0, 120),
|
|
367
|
+
})
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
/** 回读窗口字节数:64KB。单行最大体积(body 4000 + data JSON 4000 + 结构开销)远小于此。 */
|
|
371
|
+
const JOURNAL_READBACK_WINDOW_BYTES = 64 * 1024
|
|
372
|
+
|
|
373
|
+
/** 只读文件末尾一个窗口(按字节);文件小于窗口则全读。读失败由调用方捕获。 */
|
|
374
|
+
function readJournalTailWindow(path: string, windowBytes: number): string {
|
|
375
|
+
const { size } = statSync(path)
|
|
376
|
+
const start = Math.max(0, size - windowBytes)
|
|
377
|
+
const length = size - start
|
|
378
|
+
if (length <= 0) return ''
|
|
379
|
+
const buffer = Buffer.alloc(length)
|
|
380
|
+
const fd = openSync(path, 'r')
|
|
381
|
+
try {
|
|
382
|
+
let offset = 0
|
|
383
|
+
while (offset < length) {
|
|
384
|
+
const read = readSync(fd, buffer, offset, length - offset, start + offset)
|
|
385
|
+
if (read <= 0) break
|
|
386
|
+
offset += read
|
|
387
|
+
}
|
|
388
|
+
} finally {
|
|
389
|
+
closeSync(fd)
|
|
390
|
+
}
|
|
391
|
+
return buffer.toString('utf8')
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
function verifyJournalAppendReadback(
|
|
395
|
+
path: string,
|
|
396
|
+
expected: DeptMessage,
|
|
397
|
+
): { ok: true } | { ok: false; error: string } {
|
|
398
|
+
let text: string
|
|
399
|
+
try {
|
|
400
|
+
text = readJournalTailWindow(path, JOURNAL_READBACK_WINDOW_BYTES)
|
|
401
|
+
} catch (error) {
|
|
402
|
+
return {
|
|
403
|
+
ok: false,
|
|
404
|
+
error: `dsh-workplan: journal 回读校验读不到文件 path=${path}(${errorText(error)})。`
|
|
405
|
+
+ '请重试;若多次失败请让主 Agent 手动制定计划。',
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
const lines = text.split('\n').filter((line) => line.trim() !== '')
|
|
409
|
+
const want = deptMessageKeyDigest(expected)
|
|
410
|
+
/*
|
|
411
|
+
* 只扫末尾窗口:窗口首行可能被截断(窗口从行中间字节开始),parse 失败跳过该
|
|
412
|
+
* 坏行继续;新追加的行(digest 匹配)由 O_APPEND 保证在文件末尾、必在窗口内。
|
|
413
|
+
*/
|
|
414
|
+
for (const line of lines) {
|
|
415
|
+
let parsed: any = null
|
|
416
|
+
try {
|
|
417
|
+
parsed = JSON.parse(line)
|
|
418
|
+
} catch {
|
|
419
|
+
continue
|
|
420
|
+
}
|
|
421
|
+
if (deptMessageKeyDigest(parsed) === want) return { ok: true }
|
|
422
|
+
}
|
|
423
|
+
const tail = lines.slice(-5)
|
|
424
|
+
const actual = tail
|
|
425
|
+
.map((line) => {
|
|
426
|
+
try {
|
|
427
|
+
return deptMessageKeyDigest(JSON.parse(line))
|
|
428
|
+
} catch {
|
|
429
|
+
return '<不可解析行>'
|
|
430
|
+
}
|
|
431
|
+
})
|
|
432
|
+
.join(' | ')
|
|
433
|
+
return {
|
|
434
|
+
ok: false,
|
|
435
|
+
error: `dsh-workplan: journal 落盘回读校验失败 path=${path}:写入内容与读回内容关键字段不一致。`
|
|
436
|
+
+ `期望=${want.slice(0, 300)} 实际(末${tail.length}行)=${actual.slice(0, 300)}。`
|
|
437
|
+
+ '请重试;若多次失败请让主 Agent 手动制定计划。',
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
|
|
310
441
|
export interface DeptReadFilter {
|
|
311
442
|
kind?: DeptKind
|
|
312
443
|
since?: number
|
|
313
444
|
limit?: number
|
|
445
|
+
/** true=取最近 limit 条(尾部);默认 false=按追加序取最早 limit 条。 */
|
|
446
|
+
newest?: boolean
|
|
314
447
|
}
|
|
315
448
|
|
|
316
449
|
/**
|
|
317
450
|
* 按追加序回放留痕(契约 §2):
|
|
318
451
|
* - 文件不存在 → 空列表(ok:true);
|
|
319
452
|
* - 坏行(JSON 损坏或校验不过)计入 skipped,不静默吞;
|
|
320
|
-
* - kind/since 过滤后按 limit 截取:默认 500、上限 5000;
|
|
453
|
+
* - kind/since 过滤后按 limit 截取:默认 500、上限 5000;newest=true 取最近,否则取最早;
|
|
321
454
|
* - planId 非法或读盘失败 → 显式 JOURNAL_READ_FAILED。
|
|
322
455
|
*/
|
|
323
456
|
export function readDeptMessages(
|
|
@@ -369,5 +502,84 @@ export function readDeptMessages(
|
|
|
369
502
|
if (since !== null && message.ts < since) continue
|
|
370
503
|
matched.push(message)
|
|
371
504
|
}
|
|
372
|
-
return { ok: true, messages: matched.slice(0, limit), skipped }
|
|
505
|
+
return { ok: true, messages: filter?.newest ? matched.slice(-limit) : matched.slice(0, limit), skipped }
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* [3.0.6][第 2 批] 留痕目录的可选保留策略(默认关闭)。
|
|
510
|
+
*
|
|
511
|
+
* 审计证据不该被默认删除,所以本函数只在显式配置
|
|
512
|
+
* `journalRetentionDays > 0`(或环境变量
|
|
513
|
+
* `DSH_WORKPLAN_JOURNAL_RETENTION_DAYS`)时被调用。它只删除同时满足以下
|
|
514
|
+
* 条件的文件:目录里直接的 `.jsonl` 普通文件、文件名是合法 planId、
|
|
515
|
+
* mtime 早于保留天数。活跃计划会持续追加,mtime 保持新,因此不会被误删。
|
|
516
|
+
*
|
|
517
|
+
* 单次最多删 `maxFiles`(默认 200,上限 1000)个最旧文件,避免一次启动
|
|
518
|
+
* 长时间阻塞;删除失败不再静默跳过——逐个 console.warn 一行并收集进
|
|
519
|
+
* 返回值的 `errors[]`(ok 保持 true,兼容既有调用方)。
|
|
520
|
+
*
|
|
521
|
+
* [复审修复] `excludePlanIds`(可选):文件名(去 .jsonl)在集合内的一律
|
|
522
|
+
* 跳过删除,防「活跃但安静」(久无新消息、mtime 变旧)的计划被误删。
|
|
523
|
+
*/
|
|
524
|
+
export function pruneJournal(options: {
|
|
525
|
+
retentionDays: number
|
|
526
|
+
now?: number
|
|
527
|
+
maxFiles?: number
|
|
528
|
+
/** 活跃计划保护名单:journal 文件名(去 .jsonl)在集合内的跳过删除。 */
|
|
529
|
+
excludePlanIds?: ReadonlySet<string>
|
|
530
|
+
}): { ok: boolean; scanned: number; deleted: string[]; error?: string; errors?: string[] } {
|
|
531
|
+
const days = Number(options?.retentionDays)
|
|
532
|
+
if (!Number.isFinite(days) || days <= 0) return { ok: true, scanned: 0, deleted: [] }
|
|
533
|
+
const dir = resolveJournalDir()
|
|
534
|
+
let names: string[]
|
|
535
|
+
try {
|
|
536
|
+
names = readdirSync(dir)
|
|
537
|
+
} catch (error: any) {
|
|
538
|
+
if (error?.code === 'ENOENT') return { ok: true, scanned: 0, deleted: [] }
|
|
539
|
+
return { ok: false, scanned: 0, deleted: [], error: errorText(error) }
|
|
540
|
+
}
|
|
541
|
+
const now = Number.isFinite(options?.now) ? Number(options.now) : Date.now()
|
|
542
|
+
const cutoff = now - days * 24 * 60 * 60 * 1000
|
|
543
|
+
const maxFiles = Math.max(0, Math.min(1000, Math.trunc(options?.maxFiles ?? 200)))
|
|
544
|
+
const exclude = options?.excludePlanIds
|
|
545
|
+
const candidates: Array<{ name: string; path: string; mtimeMs: number }> = []
|
|
546
|
+
for (const name of names) {
|
|
547
|
+
if (!name.endsWith('.jsonl')) continue
|
|
548
|
+
const planId = name.slice(0, -'.jsonl'.length)
|
|
549
|
+
if (!PLAN_ID_PATTERN.test(planId)) continue
|
|
550
|
+
// 活跃但安静的保护名单:在册计划即使 mtime 超期也不删。
|
|
551
|
+
if (exclude?.has(planId)) continue
|
|
552
|
+
const path = join(dir, name)
|
|
553
|
+
try {
|
|
554
|
+
const stat = lstatSync(path)
|
|
555
|
+
// 只删普通文件;符号链接一律跳过(防越界删除)。
|
|
556
|
+
if (!stat.isFile() || stat.isSymbolicLink()) continue
|
|
557
|
+
if (stat.mtimeMs >= cutoff) continue
|
|
558
|
+
candidates.push({ name, path, mtimeMs: stat.mtimeMs })
|
|
559
|
+
} catch {
|
|
560
|
+
// 单个文件 stat 失败不影响其他文件,最后以 scanned 如实反映总数。
|
|
561
|
+
continue
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
candidates.sort((a, b) => a.mtimeMs - b.mtimeMs)
|
|
565
|
+
const deleted: string[] = []
|
|
566
|
+
const errors: string[] = []
|
|
567
|
+
for (const candidate of candidates.slice(0, maxFiles)) {
|
|
568
|
+
try {
|
|
569
|
+
unlinkSync(candidate.path)
|
|
570
|
+
deleted.push(candidate.name)
|
|
571
|
+
} catch (error) {
|
|
572
|
+
// 单个 unlink 失败不再静默:收集原因 + 逐条 warn(ok 保持 true 兼容)。
|
|
573
|
+
const reason = `${candidate.name}: ${errorText(error)}`
|
|
574
|
+
errors.push(reason)
|
|
575
|
+
console.warn(`dsh-workplan: journal 保留清理删除失败 ${reason} path=${candidate.path}`)
|
|
576
|
+
}
|
|
577
|
+
}
|
|
578
|
+
const result: { ok: boolean; scanned: number; deleted: string[]; error?: string; errors?: string[] } = {
|
|
579
|
+
ok: true,
|
|
580
|
+
scanned: names.length,
|
|
581
|
+
deleted,
|
|
582
|
+
}
|
|
583
|
+
if (errors.length > 0) result.errors = errors
|
|
584
|
+
return result
|
|
373
585
|
}
|