dsh-dev-plan-presets 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +341 -2
- package/client.js +1096 -0
- package/cordis.patch.yml +22 -0
- package/detail.md +192 -0
- package/docs/flow-redesign.md +403 -0
- package/guard.js +364 -0
- package/icon.svg +12 -0
- package/index.js +703 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +53 -4
- package/preset.js +485 -0
- package/scripts/test-harness.mjs +290 -0
- package/scripts/verify-presets.mjs +1650 -0
- package/settings.js +174 -0
- package/test/plugin.test.mjs +1468 -0
package/guard.js
ADDED
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 子代理模型守门(吸收 dsh-subagent-model-pin 的核心能力)。
|
|
3
|
+
*
|
|
4
|
+
* 语义:
|
|
5
|
+
* - 只管理子代理:有 parentSession 或 origin=subagent 的 Agent;主会话永不 select、永不 reject。
|
|
6
|
+
* - 创建时按 modelGuardMode 决定:pin=选中目标路由;audit=只记录 would-pin;off=什么都不做。
|
|
7
|
+
* - 每个被管理的子代理挂 agent/pre-step 守卫,逐步核对即将发请求的 modelSelection;
|
|
8
|
+
* pin + killOnViolation 时在发请求前 reject、cancel 子代理并通知父会话;audit 只记录。
|
|
9
|
+
* - honorExplicit=true 时,创建时检测到子代理被显式指定了非父级路由就不钉、也不挂守卫,
|
|
10
|
+
* 避免“说尊重却仍然打断”的自相矛盾。
|
|
11
|
+
* - 审计只记录路由、事件与 agent id,不记录任何凭据。
|
|
12
|
+
*
|
|
13
|
+
* 本文件不 import Node 内置模块,也不 import @deepseek-ai/*,便于单测。
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import { routeMatches, routeOf } from './settings.js'
|
|
17
|
+
import { PRESET_ID } from './preset.js'
|
|
18
|
+
|
|
19
|
+
const MAX_TEXT = 240
|
|
20
|
+
const shortId = (value) => (typeof value === 'string' ? value.slice(0, 12) : '')
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* 判断一个 session header 是否代表子代理。
|
|
24
|
+
* @param {{ parentSession?: string, origin?: string } | undefined} header
|
|
25
|
+
*/
|
|
26
|
+
export function isSubagentHeader(header) {
|
|
27
|
+
if (!header || typeof header !== 'object') return false
|
|
28
|
+
// fork 主对话也会带 parentSession(delegationDepth:0、无 origin),不能据此当子代理。
|
|
29
|
+
if (header.origin === 'subagent') return true
|
|
30
|
+
const depth = header.delegationDepth
|
|
31
|
+
return typeof depth === 'number' && Number.isFinite(depth) && depth > 0
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** 取父会话对象;拿不到就返回 undefined(调用方应跳过守门,避免误伤)。 */
|
|
35
|
+
const parentSessionOf = (ctx, agent) => {
|
|
36
|
+
try {
|
|
37
|
+
const parentId = agent?.session?.header?.parentSession
|
|
38
|
+
if (!parentId) return undefined
|
|
39
|
+
return ctx.get('agents')?.get?.(parentId)?.session
|
|
40
|
+
} catch {
|
|
41
|
+
return undefined
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* 读取会话当前 preset:优先 agentPresets.presetForSession(session)(含已不在 roster 的历史选择),
|
|
47
|
+
* 回退 session.header.agentPreset。拿不到时返回 undefined,调用方必须跳过守门。
|
|
48
|
+
*/
|
|
49
|
+
export function presetOfSession(ctx, session) {
|
|
50
|
+
if (!session) return undefined
|
|
51
|
+
try {
|
|
52
|
+
const registry = ctx.get('agentPresets')
|
|
53
|
+
if (typeof registry?.presetForSession === 'function') {
|
|
54
|
+
const preset = registry.presetForSession(session)
|
|
55
|
+
if (typeof preset === 'string' && preset.length > 0) return preset
|
|
56
|
+
}
|
|
57
|
+
} catch {
|
|
58
|
+
/* 回退 header */
|
|
59
|
+
}
|
|
60
|
+
const fromHeader = session?.header?.agentPreset
|
|
61
|
+
return typeof fromHeader === 'string' && fromHeader.length > 0 ? fromHeader : undefined
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* 默认守门范围:只管理父会话 preset=dev-plan 的子代理;guardAllSubagents=true 时恢复全局。
|
|
66
|
+
* 父会话或 preset 无法可靠判断时返回 false(宁可跳过,也不误伤其他插件)。
|
|
67
|
+
*/
|
|
68
|
+
export function shouldGuardAgent(ctx, agent, settings) {
|
|
69
|
+
if (settings?.guardAllSubagents === true) return true
|
|
70
|
+
const parent = parentSessionOf(ctx, agent)
|
|
71
|
+
if (!parent) return false
|
|
72
|
+
return presetOfSession(ctx, parent) === PRESET_ID
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const parentRouteOf = (ctx, agent) => {
|
|
76
|
+
try {
|
|
77
|
+
const parentId = agent?.session?.header?.parentSession
|
|
78
|
+
if (!parentId) return undefined
|
|
79
|
+
const parent = ctx.get('agents')?.get?.(parentId)
|
|
80
|
+
const current = parent?.model?.current?.()
|
|
81
|
+
if (!current?.provider || !current?.model) return undefined
|
|
82
|
+
return { provider: current.provider, model: current.model }
|
|
83
|
+
} catch {
|
|
84
|
+
return undefined
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const notifyParent = (ctx, agent, text) => {
|
|
89
|
+
try {
|
|
90
|
+
const parentId = agent?.session?.header?.parentSession
|
|
91
|
+
if (!parentId) return
|
|
92
|
+
const parent = ctx.get('agents')?.get?.(parentId)
|
|
93
|
+
if (typeof parent?.inject !== 'function') return
|
|
94
|
+
parent.inject({
|
|
95
|
+
content: [{ type: 'text', text }],
|
|
96
|
+
source: { kind: 'dev-plan-presets' },
|
|
97
|
+
})
|
|
98
|
+
} catch {
|
|
99
|
+
/* 通知失败不能反过来破坏守门 */
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const describeRoute = (route) =>
|
|
104
|
+
route && route.provider && route.model ? `${route.provider}/${route.model}` : '(unknown)'
|
|
105
|
+
|
|
106
|
+
const stopChild = (ctx, agent, reason, hooks) => {
|
|
107
|
+
try {
|
|
108
|
+
if (typeof agent?.cancel === 'function') agent.cancel({ kind: 'user' })
|
|
109
|
+
} catch {
|
|
110
|
+
/* ignore */
|
|
111
|
+
}
|
|
112
|
+
notifyParent(
|
|
113
|
+
ctx,
|
|
114
|
+
agent,
|
|
115
|
+
`⚠️ [dev-plan-presets] 子代理 ${shortId(agent?.id)} ${reason},已中止。`,
|
|
116
|
+
)
|
|
117
|
+
hooks?.audit?.('stopped', { agent: shortId(agent?.id), reason })
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const recordViolation = (hooks, agent, got, want, detail) => {
|
|
121
|
+
const entry = {
|
|
122
|
+
at: new Date().toISOString(),
|
|
123
|
+
agent: shortId(agent?.id),
|
|
124
|
+
session: shortId(agent?.session?.id),
|
|
125
|
+
from: describeRoute(got),
|
|
126
|
+
want: describeRoute(want),
|
|
127
|
+
text: String(detail).slice(0, MAX_TEXT),
|
|
128
|
+
}
|
|
129
|
+
try {
|
|
130
|
+
hooks?.recordViolation?.(entry)
|
|
131
|
+
} catch {
|
|
132
|
+
/* ignore */
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const violationText = (got, want) =>
|
|
137
|
+
`越界使用模型 ${describeRoute(got)}(应为 ${describeRoute(want)})`
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* 给一个子代理装逐步守卫。
|
|
141
|
+
* 监听器注册在 agent.ctx 上,但**返回值必须由插件自己的生命周期持有**:
|
|
142
|
+
* agent 作用域销毁和插件卸载两边都会调用同一个幂等 disposer。
|
|
143
|
+
* @returns 幂等卸载函数;注册失败时返回 undefined。
|
|
144
|
+
*/
|
|
145
|
+
const installStepGuard = (ctx, agent, settings, hooks, target) => {
|
|
146
|
+
let stopped = false
|
|
147
|
+
let active = true
|
|
148
|
+
const handler = async (payload, next) => {
|
|
149
|
+
const decision = await next()
|
|
150
|
+
try {
|
|
151
|
+
if (decision?.kind === 'reject') return decision
|
|
152
|
+
if (settings.modelGuardMode === 'off') return decision
|
|
153
|
+
if (stopped) return { kind: 'reject' }
|
|
154
|
+
const got = payload?.modelSelection
|
|
155
|
+
if (routeMatches(got, target)) return decision
|
|
156
|
+
const detail = violationText(got, target)
|
|
157
|
+
recordViolation(hooks, agent, got, target, detail)
|
|
158
|
+
hooks?.audit?.('violation', {
|
|
159
|
+
agent: shortId(agent?.id),
|
|
160
|
+
from: describeRoute(got),
|
|
161
|
+
want: describeRoute(target),
|
|
162
|
+
})
|
|
163
|
+
if (settings.modelGuardMode === 'pin' && settings.killOnViolation) {
|
|
164
|
+
stopped = true
|
|
165
|
+
stopChild(ctx, agent, detail, hooks)
|
|
166
|
+
return { kind: 'reject' }
|
|
167
|
+
}
|
|
168
|
+
return decision
|
|
169
|
+
} catch {
|
|
170
|
+
return decision
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
let off
|
|
174
|
+
try {
|
|
175
|
+
off = agent.ctx.on('agent/pre-step', handler)
|
|
176
|
+
} catch (error) {
|
|
177
|
+
hooks?.warn?.(`无法为子代理 ${shortId(agent?.id)} 安装模型守卫:${String(error?.message ?? error)}`)
|
|
178
|
+
return undefined
|
|
179
|
+
}
|
|
180
|
+
const dispose = () => {
|
|
181
|
+
if (!active) return
|
|
182
|
+
active = false
|
|
183
|
+
try {
|
|
184
|
+
if (typeof off === 'function') off()
|
|
185
|
+
} catch {
|
|
186
|
+
/* ignore */
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
// agent 作用域销毁时也释放;插件总 disposer 会先/后调用同一个 dispose,靠 active 幂等。
|
|
190
|
+
try {
|
|
191
|
+
if (typeof agent.ctx.effect === 'function') agent.ctx.effect(() => dispose)
|
|
192
|
+
} catch {
|
|
193
|
+
/* 没有 effect 时至少还有插件总 disposer */
|
|
194
|
+
}
|
|
195
|
+
return dispose
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* 处理一个 agent/created 事件。导出以便单测直接调用。
|
|
200
|
+
* @param {any} ctx
|
|
201
|
+
* @param {any} agent
|
|
202
|
+
* @param {import('./settings.js').DEFAULT_SETTINGS} settings
|
|
203
|
+
* @param {{ recordViolation?: Function, audit?: Function, warn?: Function }} hooks
|
|
204
|
+
* @param {{ provider: string, model: string, reasoningEffort?: string }} [target]
|
|
205
|
+
*/
|
|
206
|
+
export function onAgentCreated(ctx, agent, settings, hooks = {}, target = routeOf(settings)) {
|
|
207
|
+
if (!agent || settings.modelGuardMode === 'off') return
|
|
208
|
+
const header = agent.session?.header
|
|
209
|
+
// 主会话在这里被挡掉:没有父会话,也不是 origin=subagent。
|
|
210
|
+
if (!isSubagentHeader(header)) return
|
|
211
|
+
|
|
212
|
+
// 默认只守 dev-plan 父会话派出的子代理;判断不了父会话 preset 时不守门。
|
|
213
|
+
if (settings.guardAllSubagents !== true) {
|
|
214
|
+
const parent = parentSessionOf(ctx, agent)
|
|
215
|
+
const preset = parent ? presetOfSession(ctx, parent) : undefined
|
|
216
|
+
if (preset !== PRESET_ID) {
|
|
217
|
+
if (preset === undefined) {
|
|
218
|
+
hooks?.audit?.('guard-skip-unknown-parent-preset', {
|
|
219
|
+
agent: shortId(agent?.id),
|
|
220
|
+
parentFound: Boolean(parent),
|
|
221
|
+
})
|
|
222
|
+
}
|
|
223
|
+
return
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
const mode = settings.modelGuardMode
|
|
228
|
+
const current = (() => {
|
|
229
|
+
try {
|
|
230
|
+
return agent.model?.current?.()
|
|
231
|
+
} catch {
|
|
232
|
+
return undefined
|
|
233
|
+
}
|
|
234
|
+
})()
|
|
235
|
+
|
|
236
|
+
if (mode === 'audit') {
|
|
237
|
+
const dispose = installStepGuard(ctx, agent, settings, hooks, target)
|
|
238
|
+
hooks?.audit?.('would-pin', {
|
|
239
|
+
agent: shortId(agent?.id),
|
|
240
|
+
from: describeRoute(current),
|
|
241
|
+
want: describeRoute(target),
|
|
242
|
+
})
|
|
243
|
+
return dispose
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const parentRoute = parentRouteOf(ctx, agent)
|
|
247
|
+
const explicit = Boolean(
|
|
248
|
+
current &&
|
|
249
|
+
parentRoute &&
|
|
250
|
+
(current.provider !== parentRoute.provider || current.model !== parentRoute.model),
|
|
251
|
+
)
|
|
252
|
+
if (explicit && settings.honorExplicit) {
|
|
253
|
+
hooks?.audit?.('skip-explicit', {
|
|
254
|
+
agent: shortId(agent?.id),
|
|
255
|
+
from: describeRoute(current),
|
|
256
|
+
want: describeRoute(target),
|
|
257
|
+
})
|
|
258
|
+
return
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
// pin:守卫必须在 select 尝试之前装好。这样即使 select 不存在/抛错且 kill=false,
|
|
262
|
+
// 后续 pre-step 仍能记录越界,而不是变成完全不设防。
|
|
263
|
+
const dispose = installStepGuard(ctx, agent, settings, hooks, target)
|
|
264
|
+
|
|
265
|
+
// 已经在目标路由上:保留守卫防后续漂移即可。
|
|
266
|
+
if (routeMatches(current, target)) {
|
|
267
|
+
hooks?.audit?.('already', { agent: shortId(agent?.id), want: describeRoute(target) })
|
|
268
|
+
return dispose
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
const model = agent.model
|
|
272
|
+
if (typeof model?.select !== 'function') {
|
|
273
|
+
const detail = '当前 DSH 不支持 agent.model.select,无法钉住子代理路由'
|
|
274
|
+
recordViolation(hooks, agent, current, target, detail)
|
|
275
|
+
if (settings.killOnViolation) stopChild(ctx, agent, detail, hooks)
|
|
276
|
+
return dispose
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
try {
|
|
280
|
+
model.select({ ...target })
|
|
281
|
+
hooks?.audit?.('pinned', {
|
|
282
|
+
agent: shortId(agent?.id),
|
|
283
|
+
from: describeRoute(current),
|
|
284
|
+
want: describeRoute(target),
|
|
285
|
+
})
|
|
286
|
+
} catch (error) {
|
|
287
|
+
const detail = `钉住子代理路由失败:${String(error?.message ?? error)}`
|
|
288
|
+
recordViolation(hooks, agent, current, target, detail)
|
|
289
|
+
if (settings.killOnViolation) stopChild(ctx, agent, detail, hooks)
|
|
290
|
+
}
|
|
291
|
+
return dispose
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* 安装全局 agent/created 监听,并跟踪每个子代理的 step guard。
|
|
296
|
+
* 总 disposer 同时解绑事件监听和所有已装守卫:插件 HMR/卸载后旧设置不能继续拦截仍运行的 agent。
|
|
297
|
+
* @returns 幂等总卸载函数。
|
|
298
|
+
*/
|
|
299
|
+
export function installModelGuard(ctx, settings, hooks = {}) {
|
|
300
|
+
if (settings.modelGuardMode === 'off') return () => {}
|
|
301
|
+
const target = routeOf(settings)
|
|
302
|
+
const steps = new Map()
|
|
303
|
+
let active = true
|
|
304
|
+
|
|
305
|
+
const release = (agent) => {
|
|
306
|
+
const dispose = steps.get(agent)
|
|
307
|
+
if (dispose === undefined) return
|
|
308
|
+
steps.delete(agent)
|
|
309
|
+
try {
|
|
310
|
+
dispose()
|
|
311
|
+
} catch {
|
|
312
|
+
/* ignore */
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
const listener = (payload) => {
|
|
317
|
+
const agent = payload?.agent
|
|
318
|
+
try {
|
|
319
|
+
const dispose = onAgentCreated(ctx, agent, settings, hooks, target)
|
|
320
|
+
if (typeof dispose === 'function' && agent && typeof agent === 'object') {
|
|
321
|
+
release(agent)
|
|
322
|
+
steps.set(agent, dispose)
|
|
323
|
+
}
|
|
324
|
+
} catch (error) {
|
|
325
|
+
hooks?.warn?.(`模型守门处理 agent 失败:${String(error?.message ?? error)}`)
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
const disposedListener = (payload) => {
|
|
329
|
+
try {
|
|
330
|
+
release(payload?.agent)
|
|
331
|
+
} catch {
|
|
332
|
+
/* ignore */
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
const offs = []
|
|
337
|
+
try {
|
|
338
|
+
offs.push(ctx.on('agent/created', listener))
|
|
339
|
+
offs.push(ctx.on('agent/disposed', disposedListener))
|
|
340
|
+
} catch (error) {
|
|
341
|
+
hooks?.warn?.(`无法注册模型守门:${String(error?.message ?? error)}`)
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
return () => {
|
|
345
|
+
if (!active) return
|
|
346
|
+
active = false
|
|
347
|
+
for (const off of offs) {
|
|
348
|
+
try {
|
|
349
|
+
if (typeof off === 'function') off()
|
|
350
|
+
} catch {
|
|
351
|
+
/* ignore */
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
const pending = [...steps.values()]
|
|
355
|
+
steps.clear()
|
|
356
|
+
for (const dispose of pending) {
|
|
357
|
+
try {
|
|
358
|
+
dispose()
|
|
359
|
+
} catch {
|
|
360
|
+
/* ignore */
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
}
|
|
364
|
+
}
|
package/icon.svg
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Dev plan presets: a plan sheet with a read-only eye and a sealed pen">
|
|
2
|
+
<rect x="1" y="1" width="62" height="62" rx="14" fill="#101828"/>
|
|
3
|
+
<rect x="10" y="9" width="30" height="44" rx="4" fill="#1f2a3d" stroke="#3fbf9f" stroke-width="1.5"/>
|
|
4
|
+
<rect x="15" y="16" width="20" height="2.4" rx="1.2" fill="#3fbf9f"/>
|
|
5
|
+
<rect x="15" y="22" width="15" height="2.4" rx="1.2" fill="#3fbf9f" opacity="0.7"/>
|
|
6
|
+
<rect x="15" y="28" width="18" height="2.4" rx="1.2" fill="#3fbf9f" opacity="0.45"/>
|
|
7
|
+
<circle cx="45" cy="24" r="8.5" fill="#101828" stroke="#e6edf6" stroke-width="1.6"/>
|
|
8
|
+
<circle cx="45" cy="24" r="3" fill="#e6edf6"/>
|
|
9
|
+
<path d="M37.5 35.5 L50 48" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
|
|
10
|
+
<path d="M36.2 34.2 L38.8 36.8" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
|
|
11
|
+
<path d="M49 47 L52.5 50.5" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
|
|
12
|
+
</svg>
|