dsh-workplan 2.3.9 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,373 @@
1
+ /**
2
+ * [2.5.4][T5] 部门消息留痕(journal)——用户决策 D5/D6 的持久化底座。
3
+ *
4
+ * 唯一权威契约:_t5_channel_20261112/00-contract-v1.md(FROZEN,T5 负责人冻结)。
5
+ * 本文件严格实现契约 §1 消息结构与 §2 冻结导出;其他人只 import 不改。
6
+ * 任何字段/语义变更必须经 T5 负责人重新冻结,不得私改。
7
+ *
8
+ * 设计纪律(契约 §2/§6):
9
+ * - 纯函数 + 同步 fs,不依赖 harness 服务,不 import runtime/plan(避免环);
10
+ * 落盘模式参照 src/lessons.ts(JSONL 追加写、容错读取、坏行不静默吞)。
11
+ * - fail-closed:未知 kind/role、缺字段、超限一律拒(validateDeptMessage)。
12
+ * - 一切失败显式返回(JOURNAL_WRITE_FAILED / JOURNAL_READ_FAILED),绝不静默;
13
+ * planId 只允许 [A-Za-z0-9_-]{1,120},非法抛 INVALID_PLAN_ID(防路径穿越)。
14
+ * - 目录 env DSH_WORKPLAN_JOURNAL_DIR || ~/.dsh/workplan/journal;文件 <planId>.jsonl。
15
+ * - 本模块只负责留痕的写/读/校验,不做任何投递与状态判定(路由归 runtime.ts,
16
+ * 由 channel-expert 按契约 §3 实现)。
17
+ */
18
+ import { randomBytes } from 'node:crypto'
19
+ import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
20
+ import { homedir } from 'node:os'
21
+ import { dirname, join } from 'node:path'
22
+
23
+ /** 接口版本(契约 §1:字面量 1)。 */
24
+ export const DEPT_MESSAGE_VERSION = 1
25
+
26
+ export type DeptRole = 'root' | 'head' | 'expert' | 'member'
27
+ export type DeptKind =
28
+ | 'dispatch'
29
+ | 'instruction'
30
+ | 'escalation'
31
+ | 'estimate'
32
+ | 'completion'
33
+ | 'need'
34
+ | 'receipt'
35
+
36
+ /** 7 种关键沟通(frozen 数组,契约 §1/§2;日常闲聊不属于任何 kind,不入库)。 */
37
+ export const DEPT_MESSAGE_KINDS: readonly DeptKind[] = Object.freeze([
38
+ 'dispatch',
39
+ 'instruction',
40
+ 'escalation',
41
+ 'estimate',
42
+ 'completion',
43
+ 'need',
44
+ 'receipt',
45
+ ])
46
+
47
+ /**
48
+ * 角色枚举(frozen 数组,契约 §1/§2)。
49
+ *
50
+ * [3.0.0][用户要求 9] 部门组员角色已取消:新写入只使用 root/head/expert。
51
+ * `member` 保留在枚举里仅用于**读取历史 journal**(append-only 历史记录不可
52
+ * 追溯改写,拒绝读取会让旧会话的回放直接失败);现有代码不再产生该值。
53
+ */
54
+ export const DEPT_ROLES: readonly DeptRole[] = Object.freeze([
55
+ 'root',
56
+ 'head',
57
+ 'expert',
58
+ 'member',
59
+ ])
60
+
61
+ export interface DeptEndpoint {
62
+ sessionId: string
63
+ role: DeptRole
64
+ /** expert/member 必填成员名;root/head 可选。 */
65
+ member?: string
66
+ }
67
+
68
+ export interface DeptDelivery {
69
+ status: 'sent' | 'failed'
70
+ messageId?: string
71
+ code?: string
72
+ error?: string
73
+ latencyMs?: number
74
+ }
75
+
76
+ export interface DeptMessage {
77
+ /** 接口版本,字面量 1。 */
78
+ v: 1
79
+ /** makeDeptMessageId() 生成,形如 msg-<ts36>-<rand6>,≤80 字符。 */
80
+ id: string
81
+ /** 创建时刻 epoch ms,>0 且 ≤8.64e15。 */
82
+ ts: number
83
+ /** 非空,≤120。 */
84
+ planId: string
85
+ /** 部门负责人所在计划行 ID(如 T5);root↔head 消息同样用 head 行 ID。 */
86
+ subtaskId: string
87
+ kind: DeptKind
88
+ from: DeptEndpoint
89
+ to: DeptEndpoint
90
+ /** 人类可读正文 ≤4000 字符,清洗控制字符。 */
91
+ body: string
92
+ /** kind 专属结构化载荷(JSON ≤4000 字符),语义见契约 §1/§5。 */
93
+ data?: Record<string, unknown>
94
+ delivery: DeptDelivery
95
+ }
96
+
97
+ /* —— 契约 §1 的边界常量(私有;数值全部来自冻结契约,不得私改) —— */
98
+ const MAX_ID_CHARS = 80
99
+ const MAX_TS = 8.64e15
100
+ const MAX_PLAN_ID_CHARS = 120
101
+ /** subtaskId 契约未给上限;取与 planId 同宽的防御边界(行 ID 形如 T5/R1-2,远小于此)。 */
102
+ const MAX_SUBTASK_ID_CHARS = 120
103
+ const MAX_SESSION_ID_CHARS = 200
104
+ const MAX_MEMBER_CHARS = 80
105
+ const MAX_BODY_CHARS = 4000
106
+ const MAX_DATA_JSON_CHARS = 4000
107
+ const MAX_DELIVERY_MESSAGE_ID_CHARS = 200
108
+ const MAX_DELIVERY_CODE_CHARS = 80
109
+ const MAX_DELIVERY_ERROR_CHARS = 4000
110
+ const DEFAULT_READ_LIMIT = 500
111
+ const MAX_READ_LIMIT = 5000
112
+ const PLAN_ID_PATTERN = /^[A-Za-z0-9_-]{1,120}$/
113
+
114
+ function isRecord(value: unknown): value is Record<string, unknown> {
115
+ return !!value && typeof value === 'object' && !Array.isArray(value)
116
+ }
117
+
118
+ /** 与 lessons.ts 同口径:去掉不可见控制字符,保留 \t \n \r。 */
119
+ function cleanBody(value: string): string {
120
+ return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
121
+ }
122
+
123
+ function errorText(error: unknown): string {
124
+ const text = error instanceof Error ? error.message : String(error)
125
+ return text.slice(0, 500)
126
+ }
127
+
128
+ function isNonEmptyString(value: unknown, maxChars: number): value is string {
129
+ return typeof value === 'string' && value.trim().length > 0 && value.length <= maxChars
130
+ }
131
+
132
+ /**
133
+ * 生成消息 id:msg-<ts36>-<rand6>(契约 §1)。
134
+ * now 非法(缺省/非有限/越界)时回退 Date.now();总长恒 ≤80。
135
+ */
136
+ export function makeDeptMessageId(now?: number): string {
137
+ const ts = typeof now === 'number' && Number.isFinite(now) && now > 0 && now <= MAX_TS
138
+ ? Math.floor(now)
139
+ : Date.now()
140
+ return `msg-${ts.toString(36)}-${randomBytes(3).toString('hex')}`
141
+ }
142
+
143
+ function validateEndpoint(value: unknown, label: string): DeptEndpoint | string {
144
+ if (!isRecord(value)) return `${label} 必须是对象`
145
+ const sessionId = value.sessionId
146
+ if (!isNonEmptyString(sessionId, MAX_SESSION_ID_CHARS)) {
147
+ return `${label}.sessionId 必填且 ≤${MAX_SESSION_ID_CHARS} 字符`
148
+ }
149
+ const role = value.role
150
+ if (typeof role !== 'string' || !DEPT_ROLES.includes(role as DeptRole)) {
151
+ return `${label}.role 非法(期望 ${DEPT_ROLES.join('/')})`
152
+ }
153
+ const member = value.member
154
+ const needsMember = role === 'expert' || role === 'member'
155
+ if (needsMember && !isNonEmptyString(member, MAX_MEMBER_CHARS)) {
156
+ return `${label}.member 必填(expert/member 角色)且 ≤${MAX_MEMBER_CHARS} 字符`
157
+ }
158
+ if (member !== undefined && !isNonEmptyString(member, MAX_MEMBER_CHARS)) {
159
+ return `${label}.member 若提供必须非空且 ≤${MAX_MEMBER_CHARS} 字符`
160
+ }
161
+ const endpoint: DeptEndpoint = { sessionId, role: role as DeptRole }
162
+ if (member !== undefined) endpoint.member = member as string
163
+ return endpoint
164
+ }
165
+
166
+ function validateDelivery(value: unknown): DeptDelivery | string {
167
+ if (!isRecord(value)) return 'delivery 必须是对象'
168
+ const status = value.status
169
+ if (status !== 'sent' && status !== 'failed') {
170
+ return 'delivery.status 非法(期望 sent/failed)'
171
+ }
172
+ const delivery: DeptDelivery = { status }
173
+ if (value.messageId !== undefined) {
174
+ if (!isNonEmptyString(value.messageId, MAX_DELIVERY_MESSAGE_ID_CHARS)) {
175
+ return `delivery.messageId 若提供必须非空且 ≤${MAX_DELIVERY_MESSAGE_ID_CHARS} 字符`
176
+ }
177
+ delivery.messageId = value.messageId
178
+ }
179
+ if (value.code !== undefined) {
180
+ if (!isNonEmptyString(value.code, MAX_DELIVERY_CODE_CHARS)) {
181
+ return `delivery.code 若提供必须非空且 ≤${MAX_DELIVERY_CODE_CHARS} 字符`
182
+ }
183
+ delivery.code = value.code
184
+ }
185
+ if (value.error !== undefined) {
186
+ if (typeof value.error !== 'string' || value.error.length > MAX_DELIVERY_ERROR_CHARS) {
187
+ return `delivery.error 若提供必须是字符串且 ≤${MAX_DELIVERY_ERROR_CHARS} 字符`
188
+ }
189
+ delivery.error = value.error
190
+ }
191
+ if (value.latencyMs !== undefined) {
192
+ if (typeof value.latencyMs !== 'number' || !Number.isFinite(value.latencyMs) || value.latencyMs < 0) {
193
+ return 'delivery.latencyMs 若提供必须是 ≥0 的有限数字'
194
+ }
195
+ delivery.latencyMs = value.latencyMs
196
+ }
197
+ return delivery
198
+ }
199
+
200
+ /**
201
+ * 契约 §2 的唯一校验入口(fail-closed):未知 kind/role、缺字段、超限一律拒。
202
+ * 通过时返回白名单归一化后的 DeptMessage(body 已清洗控制字符)。
203
+ */
204
+ export function validateDeptMessage(
205
+ value: unknown,
206
+ ): { ok: true; value: DeptMessage } | { ok: false; error: string } {
207
+ const fail = (error: string) => ({ ok: false as const, error: `INVALID_MESSAGE: ${error}` })
208
+ if (!isRecord(value)) return fail('消息必须是对象')
209
+ if (value.v !== DEPT_MESSAGE_VERSION) return fail(`v 必须为 ${DEPT_MESSAGE_VERSION}`)
210
+ if (!isNonEmptyString(value.id, MAX_ID_CHARS)) return fail(`id 必填且 ≤${MAX_ID_CHARS} 字符`)
211
+ const ts = value.ts
212
+ if (typeof ts !== 'number' || !Number.isFinite(ts) || ts <= 0 || ts > MAX_TS) {
213
+ return fail('ts 必须是 >0 且 ≤8.64e15 的有限 epoch ms')
214
+ }
215
+ if (!isNonEmptyString(value.planId, MAX_PLAN_ID_CHARS)) {
216
+ return fail(`planId 必填且 ≤${MAX_PLAN_ID_CHARS} 字符`)
217
+ }
218
+ if (!isNonEmptyString(value.subtaskId, MAX_SUBTASK_ID_CHARS)) {
219
+ return fail(`subtaskId 必填且 ≤${MAX_SUBTASK_ID_CHARS} 字符`)
220
+ }
221
+ const kind = value.kind
222
+ if (typeof kind !== 'string' || !DEPT_MESSAGE_KINDS.includes(kind as DeptKind)) {
223
+ return fail(`kind 非法(期望 ${DEPT_MESSAGE_KINDS.join('/')})`)
224
+ }
225
+ const from = validateEndpoint(value.from, 'from')
226
+ if (typeof from === 'string') return fail(from)
227
+ const to = validateEndpoint(value.to, 'to')
228
+ if (typeof to === 'string') return fail(to)
229
+ if (typeof value.body !== 'string') return fail('body 必须是字符串')
230
+ if (value.body.length > MAX_BODY_CHARS) return fail(`body 超限(≤${MAX_BODY_CHARS} 字符)`)
231
+ const body = cleanBody(value.body)
232
+ let data: Record<string, unknown> | undefined
233
+ if (value.data !== undefined) {
234
+ if (!isRecord(value.data)) return fail('data 若提供必须是对象')
235
+ let json: string
236
+ try {
237
+ json = JSON.stringify(value.data)
238
+ } catch {
239
+ return fail('data 必须可 JSON 序列化')
240
+ }
241
+ if (typeof json !== 'string' || json.length > MAX_DATA_JSON_CHARS) {
242
+ return fail(`data JSON 超限(≤${MAX_DATA_JSON_CHARS} 字符)`)
243
+ }
244
+ data = value.data
245
+ }
246
+ const delivery = validateDelivery(value.delivery)
247
+ if (typeof delivery === 'string') return fail(delivery)
248
+ const message: DeptMessage = {
249
+ v: DEPT_MESSAGE_VERSION,
250
+ id: value.id,
251
+ ts,
252
+ planId: value.planId,
253
+ subtaskId: value.subtaskId,
254
+ kind: kind as DeptKind,
255
+ from,
256
+ to,
257
+ body,
258
+ delivery,
259
+ }
260
+ if (data !== undefined) message.data = data
261
+ return { ok: true, value: message }
262
+ }
263
+
264
+ /** 留痕目录:env DSH_WORKPLAN_JOURNAL_DIR || ~/.dsh/workplan/journal(契约 §2)。 */
265
+ function resolveJournalDir(): string {
266
+ const override = typeof process.env.DSH_WORKPLAN_JOURNAL_DIR === 'string'
267
+ ? process.env.DSH_WORKPLAN_JOURNAL_DIR.trim()
268
+ : ''
269
+ if (override) return override
270
+ return join(homedir(), '.dsh', 'workplan', 'journal')
271
+ }
272
+
273
+ /**
274
+ * 留痕文件路径:<目录>/<planId>.jsonl。
275
+ * planId 只允许 [A-Za-z0-9_-]{1,120};非法抛显式错误 INVALID_PLAN_ID(防路径穿越)。
276
+ */
277
+ export function deptJournalPath(planId: string): string {
278
+ if (typeof planId !== 'string' || !PLAN_ID_PATTERN.test(planId)) {
279
+ throw new Error(
280
+ `INVALID_PLAN_ID: planId 只允许 [A-Za-z0-9_-]{1,120},收到 ${JSON.stringify(String(planId)).slice(0, 100)}`,
281
+ )
282
+ }
283
+ return join(resolveJournalDir(), `${planId}.jsonl`)
284
+ }
285
+
286
+ /**
287
+ * 追加一条留痕(契约 §2):先 validate,再 mkdirSync(recursive)+appendFileSync。
288
+ * 任何失败(校验不过 / planId 非法 / 写盘失败)显式返回 JOURNAL_WRITE_FAILED,绝不静默。
289
+ */
290
+ export function appendDeptMessage(
291
+ msg: unknown,
292
+ ): { ok: true; path: string } | { ok: false; code: 'JOURNAL_WRITE_FAILED'; error: string } {
293
+ const verdict = validateDeptMessage(msg)
294
+ if (!verdict.ok) return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: verdict.error }
295
+ let path: string
296
+ try {
297
+ path = deptJournalPath(verdict.value.planId)
298
+ } catch (error) {
299
+ return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: errorText(error) }
300
+ }
301
+ try {
302
+ mkdirSync(dirname(path), { recursive: true })
303
+ appendFileSync(path, `${JSON.stringify(verdict.value)}\n`, 'utf8')
304
+ } catch (error) {
305
+ return { ok: false, code: 'JOURNAL_WRITE_FAILED', error: errorText(error) }
306
+ }
307
+ return { ok: true, path }
308
+ }
309
+
310
+ export interface DeptReadFilter {
311
+ kind?: DeptKind
312
+ since?: number
313
+ limit?: number
314
+ }
315
+
316
+ /**
317
+ * 按追加序回放留痕(契约 §2):
318
+ * - 文件不存在 → 空列表(ok:true);
319
+ * - 坏行(JSON 损坏或校验不过)计入 skipped,不静默吞;
320
+ * - kind/since 过滤后按 limit 截取:默认 500、上限 5000;
321
+ * - planId 非法或读盘失败 → 显式 JOURNAL_READ_FAILED。
322
+ */
323
+ export function readDeptMessages(
324
+ planId: string,
325
+ filter?: DeptReadFilter,
326
+ ):
327
+ | { ok: true; messages: DeptMessage[]; skipped: number }
328
+ | { ok: false; code: 'JOURNAL_READ_FAILED'; error: string } {
329
+ let path: string
330
+ try {
331
+ path = deptJournalPath(planId)
332
+ } catch (error) {
333
+ return { ok: false, code: 'JOURNAL_READ_FAILED', error: errorText(error) }
334
+ }
335
+ if (!existsSync(path)) return { ok: true, messages: [], skipped: 0 }
336
+ let text: string
337
+ try {
338
+ text = readFileSync(path, 'utf8')
339
+ } catch (error) {
340
+ return { ok: false, code: 'JOURNAL_READ_FAILED', error: errorText(error) }
341
+ }
342
+ const kind = filter?.kind
343
+ const since = typeof filter?.since === 'number' && Number.isFinite(filter.since)
344
+ ? filter.since
345
+ : null
346
+ const rawLimit = Number(filter?.limit)
347
+ const limit = Number.isFinite(rawLimit) && rawLimit > 0
348
+ ? Math.min(Math.floor(rawLimit), MAX_READ_LIMIT)
349
+ : DEFAULT_READ_LIMIT
350
+ const matched: DeptMessage[] = []
351
+ let skipped = 0
352
+ for (const line of text.split('\n')) {
353
+ const trimmed = line.trim()
354
+ if (!trimmed) continue
355
+ let parsed: unknown
356
+ try {
357
+ parsed = JSON.parse(trimmed)
358
+ } catch {
359
+ skipped += 1
360
+ continue
361
+ }
362
+ const verdict = validateDeptMessage(parsed)
363
+ if (!verdict.ok) {
364
+ skipped += 1
365
+ continue
366
+ }
367
+ const message = verdict.value
368
+ if (kind !== undefined && message.kind !== kind) continue
369
+ if (since !== null && message.ts < since) continue
370
+ matched.push(message)
371
+ }
372
+ return { ok: true, messages: matched.slice(0, limit), skipped }
373
+ }