dsh-cot-anchor 0.4.1 → 0.4.3

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,26 @@
1
+ /**
2
+ * 单插件 trace 运行时胶水(四包同源;与 lib/trace.js 同为内联,不跨包 import)。
3
+ *
4
+ * configHash 取「实际生效配置」:由各插件在 settings 合并完成后调用
5
+ * setTraceConfig(...) 注入(优先级 env > 持久化 settings.json > 默认值),
6
+ * 每次注入即 append 一条配置变更史(TRC-R8)。
7
+ */
8
+ import { readFileSync } from "node:fs";
9
+ import { createTraceSink } from "./trace.js";
10
+
11
+ const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
12
+ let liveConfig = Object.freeze({ plugin: pkg.name, version: pkg.version, defaultsApplied: true });
13
+
14
+ /** 本插件唯一的 trace 出口;订阅回调与判定发射点共用同一实例。 */
15
+ export const trace = createTraceSink({
16
+ plugin: pkg.name,
17
+ pluginVersion: pkg.version,
18
+ effectiveConfig: () => liveConfig
19
+ });
20
+
21
+ /** 注入生效配置并重算 configHash(写一条变更史,确定性去重)。 */
22
+ export function setTraceConfig(effectiveConfig) {
23
+ liveConfig = Object.freeze({ ...(effectiveConfig ?? {}) });
24
+ trace.recordConfigChange();
25
+ return trace.configHash;
26
+ }
package/lib/trace.js ADDED
@@ -0,0 +1,292 @@
1
+ /**
2
+ * DSH trace 契约底座 —— 四包内联同源副本(TRC-R4/R5/R6/R7/R8/R9/R19/R25)。
3
+ *
4
+ * 为什么内联:四包 package.json 的 exports 是封闭白名单,跨包 import
5
+ * `dsh-derive-watcher/lib/trace.js` 必抛 ERR_PACKAGE_PATH_NOT_EXPORTED。
6
+ * 本文件由 D:/dsh/_b1scratch/trace-build/trace.js 复制到四包 lib/ 下,
7
+ * 四份必须 sha256 一致;不得改成共享包。
8
+ *
9
+ * 写入路径:session.append("trace/<category>", data, { ignorable: true })。
10
+ * 顶层只允许内核补的 ignorable / seq / time,所有业务字段进 data。
11
+ * 三处内核补丁 marker 是未知 trace/* 能被写入/读出的唯一依据。
12
+ */
13
+ import { createHash } from "node:crypto";
14
+ import { appendFileSync, mkdirSync } from "node:fs";
15
+ import { homedir } from "node:os";
16
+ import { join } from "node:path";
17
+
18
+ /** 改字段模板、脱敏边界或指标口径时递增(TRC-R25)。 */
19
+ export const TRACE_VERSION = 1;
20
+
21
+ /** data 固定 12 键;payload 固定 8 键,unclassified 是唯一允许的第 9 键。 */
22
+ export const DATA_KEYS = Object.freeze([
23
+ "traceVersion", "plugin", "pluginVersion", "runId", "groupId", "sessionId",
24
+ "turn", "step", "sourceEventSeq", "ts", "configHash", "payload"
25
+ ]);
26
+ export const PAYLOAD_KEYS = Object.freeze([
27
+ "rule", "matched", "values", "thresholds", "inputHash", "inputRef",
28
+ "comparedIds", "reason"
29
+ ]);
30
+ export const CATEGORIES = Object.freeze([
31
+ "scan", "decision", "action", "outcome", "invocation"
32
+ ]);
33
+
34
+ /** evidenceSeq 四类语义 + 保留原有 step 命名,共 5 个枚举值(TRC-R7)。 */
35
+ export const SEQ_NAMESPACES = Object.freeze([
36
+ "counter", "step", "session", "stall", "external"
37
+ ]);
38
+
39
+ /** 宿主未提供 turn/step 时的显式哨兵:必填键不得为 null,也不伪造真实步序。 */
40
+ export const UNKNOWN_POSITION = -1;
41
+
42
+ const DEFAULT_CONFIG_ROOT = join(homedir(), ".dsh", "trace");
43
+ const SHA256_PREFIX = "sha256:";
44
+
45
+ /** 按键名排序(递归)序列化,展开默认值后的生效配置才参与 hash。 */
46
+ function sortedClone(value) {
47
+ if (Array.isArray(value)) return value.map(sortedClone);
48
+ if (value !== null && typeof value === "object") {
49
+ const out = {};
50
+ for (const key of Object.keys(value).sort()) out[key] = sortedClone(value[key]);
51
+ return out;
52
+ }
53
+ return value === undefined ? null : value;
54
+ }
55
+
56
+ /** 脱敏:只写摘要,inputRef 恒为 null(TRC-R19 冻结)。 */
57
+ export function hashInput(text) {
58
+ return SHA256_PREFIX + createHash("sha256").update(String(text ?? "")).digest("hex");
59
+ }
60
+
61
+ /** @returns {"sha256:<hex>"} 生效配置的确定性 hash(TRC-R8)。 */
62
+ export function computeConfigHash(effectiveConfig) {
63
+ const canonical = JSON.stringify(sortedClone(effectiveConfig ?? {}));
64
+ return SHA256_PREFIX + createHash("sha256").update(canonical).digest("hex");
65
+ }
66
+
67
+ function dayStamp(now = new Date()) {
68
+ return now.getFullYear() + "-" + String(now.getMonth() + 1).padStart(2, "0")
69
+ + "-" + String(now.getDate()).padStart(2, "0");
70
+ }
71
+
72
+ /** 按日分片 append-only JSONL(骨架复用 auto-memory/evidence-store.js)。 */
73
+ function appendJsonl(root, fileName, record) {
74
+ try {
75
+ mkdirSync(root, { recursive: true });
76
+ appendFileSync(join(root, fileName), JSON.stringify(record) + "\n", "utf8");
77
+ return true;
78
+ } catch (error) {
79
+ try { console.warn(`[trace] append-jsonl-failed ${fileName}: ${error?.message ?? error}`); } catch { /* ignore */ }
80
+ return false;
81
+ }
82
+ }
83
+
84
+ /**
85
+ * 创建单插件的 trace 出口。
86
+ * @param {object} options
87
+ * @param {string} options.plugin 插件 id
88
+ * @param {string} options.pluginVersion 插件版本
89
+ * @param {object|Function} [options.effectiveConfig] 生效配置(env > settings.json > defaults 合并结果)
90
+ * @param {string} [options.configRoot] 变更史 / 降级 sidecar 落盘根
91
+ * @param {Function} [options.log] 结构化日志行输出
92
+ */
93
+ export function createTraceSink(options = {}) {
94
+ const {
95
+ plugin,
96
+ pluginVersion,
97
+ effectiveConfig = {},
98
+ configRoot = process.env.DSH_TRACE_CONFIG_ROOT || DEFAULT_CONFIG_ROOT,
99
+ log = (line) => console.warn(line)
100
+ } = options;
101
+ const resolveConfig = typeof effectiveConfig === "function"
102
+ ? effectiveConfig
103
+ : () => effectiveConfig;
104
+
105
+ const runId = process.env.DSH_TRACE_RUN_ID ?? null;
106
+ const groupId = process.env.DSH_TRACE_GROUP_ID ?? null;
107
+ /** sessionId -> { session, lastSeq, lastTurn, lastStep };只记录非 trace/* 的上游事件。 */
108
+ const bindings = new Map();
109
+ /** 最近一次 bind 的 sessionId:判定点未显式带 sessionId 时的唯一回退(多会话下仍以显式值为准)。 */
110
+ let lastBoundSessionId = null;
111
+ const recordedConfigKeys = new Set();
112
+ let configHash = computeConfigHash(resolveConfig());
113
+ let missingWarned = false;
114
+
115
+ function warnMissing(detail) {
116
+ if (missingWarned) return;
117
+ missingWarned = true;
118
+ try { log(`TRACE_CONFIG_MISSING ${detail}`); } catch { /* ignore */ }
119
+ }
120
+ if (runId === null || groupId === null) {
121
+ warnMissing(`plugin=${plugin} runId=${runId} groupId=${groupId}`);
122
+ }
123
+
124
+ /** 变更史:启动时写一条,保证每条 decision 的 hash 可回溯(TRC-R8)。 */
125
+ function recordConfigChange() {
126
+ const current = computeConfigHash(resolveConfig());
127
+ configHash = current;
128
+ const key = `${dayStamp()}:${plugin}:${current}`;
129
+ if (recordedConfigKeys.has(key)) return current;
130
+ const ok = appendJsonl(configRoot, `config-history-${dayStamp()}.jsonl`, {
131
+ ts: new Date().toISOString(), plugin, configHash: current, config: sortedClone(resolveConfig())
132
+ });
133
+ if (ok) recordedConfigKeys.add(key);
134
+ return current;
135
+ }
136
+ recordConfigChange();
137
+
138
+ /**
139
+ * session/event 订阅回调里调用:登记会话句柄与上游事件 seq。
140
+ * trace/* 自产事件不覆盖 lastSeq,否则 sourceEventSeq 会指向上一条 trace(自引用,join 失效)。
141
+ */
142
+ function bind(session, event) {
143
+ if (typeof event?.type === "string" && event.type.startsWith("trace/")) return null;
144
+ const sid = session?.id ?? event?.data?.sessionId ?? null;
145
+ if (!sid) { warnMissing(`plugin=${plugin} session-id-unavailable`); return null; }
146
+ const prev = bindings.get(sid) ?? { session: null, lastSeq: null, lastTurn: null, lastStep: null };
147
+ if (session && typeof session.append === "function") prev.session = session;
148
+ if (Number.isInteger(event?.seq)) prev.lastSeq = event.seq;
149
+ const data = event?.data ?? {};
150
+ if (Number.isFinite(data.turn)) prev.lastTurn = data.turn;
151
+ if (Number.isFinite(data.step)) prev.lastStep = data.step;
152
+ bindings.set(sid, prev);
153
+ lastBoundSessionId = sid;
154
+ return prev;
155
+ }
156
+
157
+ /** 缺失降级:完整落到 sidecar,不得只 try/catch 吞掉(TRC-R25)。 */
158
+ function degrade(data, reason) {
159
+ appendJsonl(configRoot, `trace-degraded-${dayStamp()}.jsonl`, {
160
+ type: "trace/invocation",
161
+ ts: new Date().toISOString(),
162
+ reason,
163
+ data: { ...data, payload: { ...data.payload, reason } }
164
+ });
165
+ warnMissing(`plugin=${plugin} ${reason}`);
166
+ }
167
+
168
+ /**
169
+ * dsh-session.append 用 snapshotJsonValue 做无损 JSON 校验:undefined / NaN /
170
+ * -0 / BigInt / 函数 / 异类对象一律整条拒收。判定逻辑已经跑完,values 与
171
+ * thresholds 只是观测快照,这里统一走一次 JSON 往返把不可序列化值洗掉,
172
+ * 保证事件能落盘;顶层 12 键与 payload 8 键由 emit 显式构造,不受影响。
173
+ */
174
+ function jsonSafe(value) {
175
+ try {
176
+ const text = JSON.stringify(value);
177
+ return text === undefined ? null : JSON.parse(text);
178
+ } catch { return null; }
179
+ }
180
+
181
+ function appendTrace(session, type, data) {
182
+ const safeData = jsonSafe(data);
183
+ if (safeData === null) {
184
+ degrade(data, "append-failed: data-not-json-safe");
185
+ return false;
186
+ }
187
+ try {
188
+ session.append(type, safeData, { ignorable: true });
189
+ return true;
190
+ } catch (error) {
191
+ const message = String(error?.message ?? error);
192
+ if (message.includes("cannot reenter")) {
193
+ // dsh-session 的 publish 期间禁止再 append;延迟到 publish 结束后重发(TRC-R9)。
194
+ queueMicrotask(() => {
195
+ try { session.append(type, safeData, { ignorable: true }); }
196
+ catch (retryError) { degrade(data, `append-retry-failed: ${String(retryError?.message ?? retryError)}`); }
197
+ });
198
+ return true;
199
+ }
200
+ degrade(data, `append-failed: ${message}`);
201
+ return false;
202
+ }
203
+ }
204
+
205
+ /**
206
+ * 发一条 trace 事件。类别非法时按 TRC-R5 兜底成 invocation + unclassified。
207
+ * @param {string} category scan|decision|action|outcome|invocation
208
+ * @param {object} spec 判定上下文
209
+ */
210
+ function emit(category, spec = {}) {
211
+ const known = CATEGORIES.includes(category);
212
+ const resolved = known ? category : "invocation";
213
+ const unclassified = !known || spec.unclassified === true;
214
+ const sid = spec.sessionId ?? lastBoundSessionId ?? null;
215
+ const binding = sid !== null ? bindings.get(sid) : null;
216
+ const session = binding?.session ?? null;
217
+
218
+ const values = { ...(spec.values ?? {}) };
219
+ if (spec.evidenceSeq !== undefined && spec.evidenceSeq !== null) values.evidenceSeq = spec.evidenceSeq;
220
+ if (spec.seqNamespace !== undefined && spec.seqNamespace !== null) {
221
+ if (SEQ_NAMESPACES.includes(spec.seqNamespace)) values.seqNamespace = spec.seqNamespace;
222
+ else {
223
+ values.seqNamespace = null;
224
+ try { log(`[trace] unknown seqNamespace ${spec.seqNamespace}`); } catch { /* ignore */ }
225
+ }
226
+ }
227
+
228
+ const payload = {
229
+ rule: spec.rule ?? null,
230
+ matched: spec.matched === true,
231
+ values,
232
+ thresholds: spec.thresholds ?? {},
233
+ inputHash: spec.inputHash ?? null,
234
+ inputRef: null,
235
+ comparedIds: Array.isArray(spec.comparedIds) ? spec.comparedIds : [],
236
+ reason: unclassified ? "unclassified" : (spec.reason ?? null)
237
+ };
238
+ if (unclassified) payload.unclassified = true;
239
+
240
+ const turn = Number.isFinite(spec.turn) ? spec.turn
241
+ : (Number.isFinite(binding?.lastTurn) ? binding.lastTurn : UNKNOWN_POSITION);
242
+ const step = Number.isFinite(spec.step) ? spec.step
243
+ : (Number.isFinite(binding?.lastStep) ? binding.lastStep : UNKNOWN_POSITION);
244
+ const sourceEventSeq = Number.isInteger(spec.sourceEventSeq)
245
+ ? spec.sourceEventSeq
246
+ : (Number.isInteger(binding?.lastSeq) ? binding.lastSeq : null);
247
+
248
+ const data = {
249
+ traceVersion: TRACE_VERSION,
250
+ plugin,
251
+ pluginVersion,
252
+ runId,
253
+ groupId,
254
+ sessionId: sid,
255
+ turn,
256
+ step,
257
+ sourceEventSeq,
258
+ ts: new Date().toISOString(),
259
+ configHash,
260
+ payload
261
+ };
262
+
263
+ const type = `trace/${resolved}`;
264
+ if (!session || typeof session.append !== "function") {
265
+ // session 不可用:无法 append 时写 sidecar 并显式告警,绝不静默丢弃。
266
+ degrade(data, "session-unavailable");
267
+ return data;
268
+ }
269
+ if (sourceEventSeq === null) {
270
+ // 上游 seq 缺失:仍要发 invocation 留痕,不得只 try/catch 吞掉。
271
+ appendTrace(session, "trace/invocation", {
272
+ ...data,
273
+ payload: { ...payload, reason: "session-unavailable" }
274
+ });
275
+ }
276
+ appendTrace(session, type, data);
277
+ return data;
278
+ }
279
+
280
+ return {
281
+ plugin,
282
+ pluginVersion,
283
+ runId,
284
+ groupId,
285
+ get configHash() { return configHash; },
286
+ bind,
287
+ emit,
288
+ recordConfigChange,
289
+ hashInput,
290
+ getBinding: (sid) => bindings.get(sid) ?? null
291
+ };
292
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-cot-anchor",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "思考锚点:从模型上一段思考中提取已确立结论,在工具结果后注入,减少重复推导;并可识别打转与伪工具调用",
5
5
  "keywords": [
6
6
  "dsh",
@@ -250,7 +250,21 @@ if (mode === "check") {
250
250
 
251
251
  // ---- apply ----------------------------------------------------------------
252
252
  if (applied) {
253
- log("✓ 目标内核已处于移植状态,不重复补丁(幂等)。");
253
+ // TRC-R14:已移植 ≠ 字段已就位。旧模板缺 detector/阈值时增量注入,不重复移植。
254
+ const OLD_TAKEN = `\t\t\t\t\t\t\tbudgetState: { ...budgetState }\n\t\t\t\t\t\t}, { ignorable: true });`;
255
+ const NEW_TAKEN = `\t\t\t\t\t\t\tbudgetState: { ...budgetState },\n\t\t\t\t\t\t\tdetector: cutDecision.detector ?? cutDecision.cutClass ?? "heuristic",\n\t\t\t\t\t\t\tthresholds: { budgetKey, budgetTotal: budgetState.total }\n\t\t\t\t\t\t}, { ignorable: true });`;
256
+ if (source.includes(OLD_TAKEN)) {
257
+ writeFileSync(TARGET, source.split(OLD_TAKEN).join(NEW_TAKEN), "utf8");
258
+ const upgradeSyntaxError = syntaxCheck(TARGET);
259
+ if (upgradeSyntaxError !== null) {
260
+ writeFileSync(TARGET, source, "utf8");
261
+ log(`✗ 增量注入语法校验失败,已回滚:${upgradeSyntaxError}`);
262
+ process.exit(1);
263
+ }
264
+ log("✓ 已移植:增量补 detector/阈值(不重复移植)");
265
+ process.exit(0);
266
+ }
267
+ log("✓ 目标内核已处于移植状态且字段已就位(幂等)。");
254
268
  log(" 内核升级或需要重跑本脚本前,必须先执行:node apply-softcut-port.mjs --revert");
255
269
  log(" 若内核已被包管理器整体覆盖(无移植标记),直接重新 apply 即可,但需通过下方版本/哈希自检。");
256
270
  process.exit(0);
@@ -971,6 +985,9 @@ const AGENT_LOOP_BLOCKS = [
971
985
  },
972
986
  {
973
987
  name: 'p5-soft-cut-taken',
988
+ // TRC-R14:已打旧模板的内核走 PRESENT_MARKER 分支,用 upgrade pair 补字段而非跳过。
989
+ oldClose: `\t\t\t\t\t\t\tbudgetState: { ...budgetState }\n\t\t\t\t\t\t}, { ignorable: true });`,
990
+ newClose: `\t\t\t\t\t\t\tbudgetState: { ...budgetState },\n\t\t\t\t\t\t\tdetector: cutDecision.detector ?? cutDecision.cutClass ?? "heuristic",\n\t\t\t\t\t\t\tthresholds: { budgetKey, budgetTotal: budgetState.total }\n\t\t\t\t\t\t}, { ignorable: true });`,
974
991
  find: L(
975
992
  '\t\t\t\t\tsoftCutDecision = cutDecision;',
976
993
  '\t\t\t\t\tbudgetState[budgetKey] += 1;',
@@ -990,7 +1007,9 @@ const AGENT_LOOP_BLOCKS = [
990
1007
  '\t\t\t\t\t\t\tstep,',
991
1008
  '\t\t\t\t\t\t\tcutClass: cutDecision.cutClass ?? "heuristic",',
992
1009
  '\t\t\t\t\t\t\tbudgetKey,',
993
- '\t\t\t\t\t\t\tbudgetState: { ...budgetState }',
1010
+ '\t\t\t\t\t\t\tbudgetState: { ...budgetState },',
1011
+ '\t\t\t\t\t\t\tdetector: cutDecision.detector ?? cutDecision.cutClass ?? "heuristic",',
1012
+ '\t\t\t\t\t\t\tthresholds: { budgetKey, budgetTotal: budgetState.total }',
994
1013
  '\t\t\t\t\t\t}, { ignorable: true });',
995
1014
  '\t\t\t\t\t\tthis.dispatch.emit("agent/soft-cut-taken", {',
996
1015
  '\t\t\t\t\t\t\tturn,',
@@ -998,6 +1017,8 @@ const AGENT_LOOP_BLOCKS = [
998
1017
  '\t\t\t\t\t\t\tcutClass: cutDecision.cutClass ?? "heuristic",',
999
1018
  '\t\t\t\t\t\t\tbudgetKey,',
1000
1019
  '\t\t\t\t\t\t\tbudgetState: { ...budgetState },',
1020
+ '\t\t\t\t\t\t\tdetector: cutDecision.detector ?? cutDecision.cutClass ?? "heuristic",',
1021
+ '\t\t\t\t\t\t\tthresholds: { budgetKey, budgetTotal: budgetState.total },',
1001
1022
  '\t\t\t\t\t\t\tevidenceSeq: takenEvent.seq',
1002
1023
  '\t\t\t\t\t\t});',
1003
1024
  '\t\t\t\t\t} catch {',