@octopi-agent/engine 0.98.4 → 0.102.10

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.
Files changed (301) hide show
  1. package/dist/config-schema/agent.d.ts +35 -5
  2. package/dist/config-schema/agent.js +24 -4
  3. package/dist/config-schema/context.d.ts +6 -36
  4. package/dist/config-schema/context.js +4 -28
  5. package/dist/config-schema/engine.d.ts +57 -160
  6. package/dist/config-schema/engine.js +1 -5
  7. package/dist/config-schema/governance.d.ts +8 -1
  8. package/dist/config-schema/governance.js +8 -1
  9. package/dist/config-schema/models.d.ts +2 -8
  10. package/dist/config-schema/models.js +0 -2
  11. package/dist/config-schema/run.d.ts +2 -2
  12. package/dist/config-schema/run.js +2 -2
  13. package/dist/config-schema/shared.d.ts +0 -3
  14. package/dist/config-schema/shared.js +0 -2
  15. package/dist/config-schema/substrate.d.ts +14 -88
  16. package/dist/config-schema/substrate.js +22 -107
  17. package/dist/config.d.ts +45 -113
  18. package/dist/config.js +8 -2
  19. package/dist/harness/activation/dispatcher.js +7 -0
  20. package/dist/harness/activation/inbox.d.ts +3 -3
  21. package/dist/harness/activation/inbox.js +3 -3
  22. package/dist/harness/activation/runtime.js +13 -5
  23. package/dist/harness/activation/types.d.ts +2 -2
  24. package/dist/harness/agent/builder.d.ts +24 -3
  25. package/dist/harness/agent/builder.js +131 -27
  26. package/dist/harness/agent/config-bridge.js +9 -2
  27. package/dist/harness/agent/config-integrity.js +19 -2
  28. package/dist/harness/agent/wire-agent-builder.d.ts +11 -3
  29. package/dist/harness/agent/wire-agent-builder.js +26 -7
  30. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  31. package/dist/harness/capabilities/document/factory.js +1 -0
  32. package/dist/harness/capabilities/document/port.js +6 -3
  33. package/dist/harness/capabilities/document/types.d.ts +5 -0
  34. package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -1
  35. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +1 -1
  36. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +2 -2
  37. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  38. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  39. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  40. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  41. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  42. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +1 -1
  43. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +3 -3
  44. package/dist/harness/collaboration/delegation/child-run.d.ts +1 -1
  45. package/dist/harness/collaboration/delegation/child-run.js +4 -4
  46. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  47. package/dist/harness/collaboration/delegation/index.js +1 -1
  48. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  49. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  50. package/dist/harness/collaboration/delegation/service.d.ts +2 -0
  51. package/dist/harness/collaboration/delegation/service.js +2 -1
  52. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  53. package/dist/harness/collaboration/delegation/store.js +2 -1
  54. package/dist/harness/collaboration/delegation/types.d.ts +23 -2
  55. package/dist/harness/collaboration/delegation/types.js +22 -0
  56. package/dist/harness/collaboration/delegation/wiring.js +11 -1
  57. package/dist/harness/context/budget-allocator.d.ts +26 -18
  58. package/dist/harness/context/budget-allocator.js +67 -32
  59. package/dist/harness/context/capabilities/compact/engine.d.ts +0 -6
  60. package/dist/harness/context/capabilities/compact/engine.js +169 -121
  61. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  62. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  63. package/dist/harness/context/capabilities/compact/index.d.ts +5 -1
  64. package/dist/harness/context/capabilities/compact/index.js +4 -0
  65. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  66. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  67. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  68. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  69. package/dist/harness/context/capabilities/compact/types.d.ts +76 -11
  70. package/dist/harness/context/capabilities/compact/types.js +11 -1
  71. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  72. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  73. package/dist/harness/context/capabilities/summary/port.js +0 -1
  74. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  75. package/dist/harness/context/capabilities/summary/resolver.js +1 -6
  76. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  77. package/dist/harness/context/capabilities/summary/types.d.ts +3 -6
  78. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  79. package/dist/harness/context/context-size-ledger.js +236 -0
  80. package/dist/harness/context/default-context-engine.d.ts +195 -119
  81. package/dist/harness/context/default-context-engine.js +1241 -743
  82. package/dist/harness/context/index.d.ts +2 -2
  83. package/dist/harness/context/index.js +1 -1
  84. package/dist/harness/context/layer-types.d.ts +15 -0
  85. package/dist/harness/context/layer-types.js +14 -1
  86. package/dist/harness/context/layers.d.ts +14 -15
  87. package/dist/harness/context/layers.js +41 -11
  88. package/dist/harness/context/message-selector.d.ts +10 -8
  89. package/dist/harness/context/message-selector.js +49 -27
  90. package/dist/harness/context/summarize.d.ts +2 -2
  91. package/dist/harness/context/summarize.js +9 -2
  92. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  93. package/dist/harness/context/system-prompt-assembler.js +2 -1
  94. package/dist/harness/context/token-constants.d.ts +8 -6
  95. package/dist/harness/context/token-constants.js +8 -7
  96. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  97. package/dist/harness/context/token-estimate-fns.js +85 -66
  98. package/dist/harness/context/token-estimator.d.ts +27 -12
  99. package/dist/harness/context/token-estimator.js +120 -66
  100. package/dist/harness/context/token-segments.d.ts +88 -0
  101. package/dist/harness/context/token-segments.js +103 -0
  102. package/dist/harness/context/tool-result-aging.d.ts +6 -1
  103. package/dist/harness/context/tool-result-aging.js +16 -5
  104. package/dist/harness/context/tool-result-body.js +2 -0
  105. package/dist/harness/context/transform/anchors.d.ts +66 -0
  106. package/dist/harness/context/transform/anchors.js +125 -0
  107. package/dist/harness/context/transform/fold.d.ts +56 -0
  108. package/dist/harness/context/transform/fold.js +135 -0
  109. package/dist/harness/context/transform/migrate.d.ts +41 -0
  110. package/dist/harness/context/transform/migrate.js +69 -0
  111. package/dist/harness/context/transform/types.d.ts +129 -0
  112. package/dist/harness/context/transform/types.js +19 -0
  113. package/dist/harness/context/turn-envelope.d.ts +6 -3
  114. package/dist/harness/context/types.d.ts +127 -117
  115. package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
  116. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  117. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  118. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +1 -1
  119. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  120. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  121. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  122. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  123. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  124. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  125. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  126. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  127. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  128. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  129. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  130. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  131. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  132. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  133. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  134. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  135. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  136. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  137. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  138. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  139. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  140. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  141. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  142. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  143. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  144. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  145. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +83 -249
  146. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +88 -214
  147. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +43 -0
  148. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +61 -0
  149. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  150. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  151. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  152. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  153. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  154. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  155. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +50 -117
  156. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +316 -285
  157. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +23 -490
  158. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +85 -353
  159. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +41 -223
  160. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +138 -19
  161. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +15 -0
  162. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  163. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  164. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  165. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  167. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -8
  168. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  169. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  170. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  171. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +11 -2
  172. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  173. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  174. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  175. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  176. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  177. package/dist/harness/index.d.ts +12 -12
  178. package/dist/harness/index.js +7 -7
  179. package/dist/harness/knowledge/boot-config.d.ts +55 -0
  180. package/dist/harness/knowledge/boot-config.js +50 -0
  181. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  182. package/dist/harness/knowledge/client.d.ts +24 -2
  183. package/dist/harness/knowledge/client.js +19 -5
  184. package/dist/harness/knowledge/db.js +5 -0
  185. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  186. package/dist/harness/knowledge/describe-sample.js +58 -0
  187. package/dist/harness/knowledge/describe.d.ts +8 -0
  188. package/dist/harness/knowledge/describe.js +18 -2
  189. package/dist/harness/knowledge/engine-thread.js +6 -0
  190. package/dist/harness/knowledge/grounding.js +3 -1
  191. package/dist/harness/knowledge/http-app.js +35 -4
  192. package/dist/harness/knowledge/http-params.d.ts +18 -0
  193. package/dist/harness/knowledge/http-params.js +24 -0
  194. package/dist/harness/knowledge/index.d.ts +2 -0
  195. package/dist/harness/knowledge/index.js +1 -0
  196. package/dist/harness/knowledge/knowledge-serve-child.js +3 -0
  197. package/dist/harness/knowledge/purge.js +5 -2
  198. package/dist/harness/knowledge/query-service.d.ts +13 -2
  199. package/dist/harness/knowledge/query-service.js +4 -2
  200. package/dist/harness/knowledge/query-worker-client.d.ts +9 -1
  201. package/dist/harness/knowledge/query-worker-client.js +4 -2
  202. package/dist/harness/knowledge/query-worker.js +4 -2
  203. package/dist/harness/knowledge/read-http.js +5 -1
  204. package/dist/harness/knowledge/serve.d.ts +8 -7
  205. package/dist/harness/knowledge/serve.js +9 -0
  206. package/dist/harness/knowledge/source-store.js +26 -3
  207. package/dist/harness/knowledge/start-service-process.d.ts +15 -7
  208. package/dist/harness/knowledge/start-service-process.js +21 -9
  209. package/dist/harness/knowledge/types.d.ts +7 -0
  210. package/dist/harness/knowledge/writer-service.d.ts +37 -9
  211. package/dist/harness/knowledge/writer-service.js +120 -14
  212. package/dist/harness/knowledge/writer-worker-client.d.ts +10 -9
  213. package/dist/harness/knowledge/writer-worker-client.js +20 -2
  214. package/dist/harness/knowledge/writer-worker.js +9 -1
  215. package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
  216. package/dist/harness/memory/types.d.ts +6 -4
  217. package/dist/harness/memory/wisdom-formation.d.ts +14 -3
  218. package/dist/harness/memory/wisdom-formation.js +85 -22
  219. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  220. package/dist/harness/memory/wisdom-gates.js +59 -19
  221. package/dist/harness/memory/wisdom.js +9 -0
  222. package/dist/harness/observability/observer/hub.js +25 -15
  223. package/dist/harness/observability/observer/types.d.ts +10 -6
  224. package/dist/harness/run/agent/agent.d.ts +40 -21
  225. package/dist/harness/run/agent/agent.js +66 -13
  226. package/dist/harness/run/agent/index.d.ts +1 -1
  227. package/dist/harness/run/budget/budget.d.ts +28 -10
  228. package/dist/harness/run/budget/budget.js +38 -15
  229. package/dist/harness/run/model/index.d.ts +3 -1
  230. package/dist/harness/run/model/index.js +2 -1
  231. package/dist/harness/run/model/resolver.d.ts +4 -1
  232. package/dist/harness/run/model/resolver.js +36 -2
  233. package/dist/harness/run/model/run-scope.d.ts +2 -0
  234. package/dist/harness/run/model/run-scope.js +7 -0
  235. package/dist/harness/run/model/types.d.ts +22 -5
  236. package/dist/harness/run/model/types.js +3 -2
  237. package/dist/harness/run/model/window-truth.d.ts +37 -0
  238. package/dist/harness/run/model/window-truth.js +39 -0
  239. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  240. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  241. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  242. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  243. package/dist/harness/run/reliability/run-agent.d.ts +10 -4
  244. package/dist/harness/run/reliability/run-agent.js +137 -53
  245. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  246. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  247. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  248. package/dist/harness/run/run-scope.d.ts +37 -4
  249. package/dist/harness/run/runner.d.ts +44 -29
  250. package/dist/harness/run/runner.js +320 -102
  251. package/dist/harness/session/attachments/index.d.ts +1 -0
  252. package/dist/harness/session/attachments/index.js +1 -0
  253. package/dist/harness/session/attachments/inject.d.ts +21 -10
  254. package/dist/harness/session/attachments/inject.js +76 -24
  255. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  256. package/dist/harness/session/attachments/recall-index.js +219 -0
  257. package/dist/harness/session/attachments/service.d.ts +21 -0
  258. package/dist/harness/session/attachments/service.js +258 -139
  259. package/dist/harness/session/attachments/types.d.ts +6 -0
  260. package/dist/harness/session/transform-store.d.ts +136 -0
  261. package/dist/harness/session/transform-store.js +302 -0
  262. package/dist/harness/session/types.d.ts +2 -2
  263. package/dist/harness/shared/events/agent-event-map.d.ts +46 -13
  264. package/dist/harness/shared/events/agent-event-map.js +3 -2
  265. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  266. package/dist/harness/shared/types/agent-definition.d.ts +1 -2
  267. package/dist/index.d.ts +14 -17
  268. package/dist/index.js +7 -9
  269. package/dist/integration/observability/metrics.d.ts +6 -6
  270. package/dist/integration/observability/metrics.js +13 -13
  271. package/dist/integration/observability/observer-bridge.js +2 -2
  272. package/dist/integration/observability/trace-collector.d.ts +5 -5
  273. package/dist/integration/observability/trace-collector.js +34 -35
  274. package/dist/integration/observability/trace-events.d.ts +3 -3
  275. package/dist/integration/observability/trace-events.js +3 -3
  276. package/dist/integration/providers/anthropic.js +14 -1
  277. package/dist/integration/providers/openai.js +7 -1
  278. package/dist/integration/providers/usage.d.ts +1 -1
  279. package/dist/integration/providers/wire-dump.d.ts +1 -1
  280. package/dist/integration/storage/archive-manager.d.ts +6 -0
  281. package/dist/integration/storage/archive-manager.js +10 -0
  282. package/dist/integration/storage/jsonl.d.ts +1 -1
  283. package/dist/integration/storage/jsonl.js +18 -16
  284. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  285. package/dist/subsystems/wisdom-steward/formation/config.yaml +1 -0
  286. package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
  287. package/package.json +11 -14
  288. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  289. package/dist/harness/context/hybrid-compressor.js +0 -159
  290. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  291. package/dist/harness/context/llm-summarizer.js +0 -249
  292. package/dist/harness/context/smart-router.d.ts +0 -75
  293. package/dist/harness/context/smart-router.js +0 -118
  294. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  295. package/dist/harness/context/truncate-compressor.js +0 -107
  296. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  297. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  298. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  299. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  300. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  301. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -60,12 +60,22 @@ function deriveDisplayName(location) {
60
60
  return parts[parts.length - 1] || location || 'source';
61
61
  }
62
62
  function toCatalogItem(source, extras) {
63
+ const human = source.description?.trim();
64
+ const generated = source.generatedDescription?.trim();
63
65
  return {
64
66
  id: source.id,
65
67
  displayName: source.displayName,
66
68
  kind: source.kind,
67
69
  status: statusBucket(source.status),
68
- description: source.description?.trim() || source.generatedDescription?.trim() || undefined,
70
+ description: human || generated || undefined,
71
+ // 信任分级(human > llm > heuristic);blocked_secret 的文本是启发式,归 heuristic 档
72
+ ...(human
73
+ ? { descriptionSource: 'human' }
74
+ : generated
75
+ ? {
76
+ descriptionSource: source.generatedDescriptionSource === 'llm' ? 'llm' : 'heuristic',
77
+ }
78
+ : {}),
69
79
  scopeLevel: source.scopeRef.level,
70
80
  scaleLabel: scaleLabel(source, extras?.fileCount),
71
81
  location: source.location,
@@ -93,6 +103,9 @@ function rowToSource(row) {
93
103
  displayName: String(row.display_name),
94
104
  description: row.description == null ? undefined : String(row.description),
95
105
  generatedDescription: row.generated_description == null ? undefined : String(row.generated_description),
106
+ generatedDescriptionSource: row.generated_description_source == null
107
+ ? undefined
108
+ : String(row.generated_description_source),
96
109
  catalogPriority: row.catalog_priority == null ? undefined : Number(row.catalog_priority),
97
110
  hiddenFromCatalog: Number(row.hidden_from_catalog) === 1,
98
111
  authRef: row.auth_ref == null ? undefined : String(row.auth_ref),
@@ -138,6 +151,7 @@ export class KnowledgeSourceStore {
138
151
  displayName,
139
152
  description: input.description,
140
153
  generatedDescription: input.generatedDescription,
154
+ generatedDescriptionSource: input.generatedDescriptionSource,
141
155
  catalogPriority: input.catalogPriority,
142
156
  hiddenFromCatalog: input.hiddenFromCatalog ?? false,
143
157
  authRef: input.authRef,
@@ -181,6 +195,13 @@ export class KnowledgeSourceStore {
181
195
  : patch.generatedDescription,
182
196
  }
183
197
  : {}),
198
+ ...(patch.generatedDescriptionSource !== undefined
199
+ ? {
200
+ generatedDescriptionSource: patch.generatedDescriptionSource === null
201
+ ? undefined
202
+ : patch.generatedDescriptionSource,
203
+ }
204
+ : {}),
184
205
  ...(patch.catalogPriority !== undefined ? { catalogPriority: patch.catalogPriority } : {}),
185
206
  ...(patch.hiddenFromCatalog !== undefined
186
207
  ? { hiddenFromCatalog: patch.hiddenFromCatalog }
@@ -617,9 +638,10 @@ export class KnowledgeSourceStore {
617
638
  .prepare(`INSERT INTO knowledge_sources (
618
639
  id, kind, location, scope_level, scope_key, sync_json, status, coverage,
619
640
  errors_json, display_name, description, generated_description,
641
+ generated_description_source,
620
642
  catalog_priority, hidden_from_catalog, auth_ref, network_json, discover_json,
621
643
  last_polled_at, created_at, updated_at
622
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
644
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
623
645
  ON CONFLICT(id) DO UPDATE SET
624
646
  kind=excluded.kind,
625
647
  location=excluded.location,
@@ -632,6 +654,7 @@ export class KnowledgeSourceStore {
632
654
  display_name=excluded.display_name,
633
655
  description=excluded.description,
634
656
  generated_description=excluded.generated_description,
657
+ generated_description_source=excluded.generated_description_source,
635
658
  catalog_priority=excluded.catalog_priority,
636
659
  hidden_from_catalog=excluded.hidden_from_catalog,
637
660
  auth_ref=excluded.auth_ref,
@@ -639,6 +662,6 @@ export class KnowledgeSourceStore {
639
662
  discover_json=excluded.discover_json,
640
663
  last_polled_at=excluded.last_polled_at,
641
664
  updated_at=excluded.updated_at`)
642
- .run(source.id, source.kind, source.location, source.scopeRef.level, source.scopeRef.key, JSON.stringify(source.sync), source.status, source.coverage ?? null, JSON.stringify(source.errors ?? []), source.displayName, source.description ?? null, source.generatedDescription ?? null, source.catalogPriority ?? null, source.hiddenFromCatalog ? 1 : 0, source.authRef ?? null, source.network ? JSON.stringify(source.network) : null, source.discover ? JSON.stringify(source.discover) : null, source.lastPolledAt ?? null, source.createdAt, source.updatedAt);
665
+ .run(source.id, source.kind, source.location, source.scopeRef.level, source.scopeRef.key, JSON.stringify(source.sync), source.status, source.coverage ?? null, JSON.stringify(source.errors ?? []), source.displayName, source.description ?? null, source.generatedDescription ?? null, source.generatedDescriptionSource ?? null, source.catalogPriority ?? null, source.hiddenFromCatalog ? 1 : 0, source.authRef ?? null, source.network ? JSON.stringify(source.network) : null, source.discover ? JSON.stringify(source.discover) : null, source.lastPolledAt ?? null, source.createdAt, source.updatedAt);
643
666
  }
644
667
  }
@@ -14,19 +14,20 @@
14
14
  import { type ChildProcess } from 'node:child_process';
15
15
  import type { KnowledgeServiceToken } from './http-app.js';
16
16
  import type { DocumentCapabilityConfig } from '../capabilities/document/factory.js';
17
+ import type { KnowledgeBootEmbed, KnowledgeBootIngest, KnowledgeBootRetriever } from './boot-config.js';
17
18
  export interface KnowledgeServiceProcessOptions {
18
19
  dbPath: string;
19
20
  port?: number;
20
21
  host?: string;
21
22
  tokens: KnowledgeServiceToken[];
22
23
  documentConfig?: DocumentCapabilityConfig | null;
23
- embed?: {
24
- enabled?: boolean;
25
- embedBatch?: number;
26
- embedMinIntervalMs?: number;
27
- embedConcurrency?: number;
28
- embedSecretPolicy?: 'allow' | 'redact' | 'skip';
29
- };
24
+ embed?: KnowledgeBootEmbed;
25
+ /** Ingest 调参(knowledge.load / index.queue / index.files) */
26
+ ingest?: KnowledgeBootIngest;
27
+ /** 检索调参(knowledge.keywordWeight / autoInject / hint / index.hybridKeyword) */
28
+ retriever?: KnowledgeBootRetriever;
29
+ /** false = 索引稳定后不自动生成 generatedDescription(knowledge.catalog.autoDescribe) */
30
+ autoDescribe?: boolean;
30
31
  sqliteVecExtensionPath?: string;
31
32
  embeddingModels?: {
32
33
  providers?: Record<string, unknown>;
@@ -40,6 +41,13 @@ export interface KnowledgeServiceProcessHandle {
40
41
  /** 发 close 并等待退出;超时 SIGTERM */
41
42
  stop(): Promise<void>;
42
43
  }
44
+ /**
45
+ * 组装 boot 文件内容 — Gateway 调参面 → Service 子进程的唯一交接面(纯函数,可单测锁 hop)。
46
+ *
47
+ * @param opts - 进程启动选项(与 startKnowledgeService 同构 + embeddingModels)
48
+ * @returns boot JSON 对象(与 knowledge-serve-child 的 BootFile 同构)
49
+ */
50
+ export declare function buildKnowledgeServiceBootFile(opts: KnowledgeServiceProcessOptions): Record<string, unknown>;
43
51
  /**
44
52
  * 在独立子进程启动 Knowledge HTTP Service。
45
53
  *
@@ -33,25 +33,37 @@ function childNodeEnv() {
33
33
  return env;
34
34
  }
35
35
  /**
36
- * 在独立子进程启动 Knowledge HTTP Service。
36
+ * 组装 boot 文件内容 — Gateway 调参面 → Service 子进程的唯一交接面(纯函数,可单测锁 hop)。
37
37
  *
38
- * @param opts - 与 startKnowledgeService 同构 + embeddingModels(子进程内重建 provider)
39
- * @returns child + 端口 + stop
38
+ * @param opts - 进程启动选项(与 startKnowledgeService 同构 + embeddingModels)
39
+ * @returns boot JSON 对象(与 knowledge-serve-child 的 BootFile 同构)
40
40
  */
41
- export async function startKnowledgeServiceProcess(opts) {
42
- const entry = fileURLToPath(resolveWorkerUrl('./knowledge-serve-child.js', import.meta.url));
43
- const bootDir = await mkdtemp(join(tmpdir(), 'octopi-kn-boot-'));
44
- const bootPath = join(bootDir, 'boot.json');
45
- await writeFile(bootPath, JSON.stringify({
41
+ export function buildKnowledgeServiceBootFile(opts) {
42
+ return {
46
43
  dbPath: opts.dbPath,
47
44
  host: opts.host,
48
45
  port: opts.port ?? 18280,
49
46
  tokens: opts.tokens,
50
47
  documentConfig: opts.documentConfig ?? null,
51
48
  embed: opts.embed,
49
+ ingest: opts.ingest,
50
+ retriever: opts.retriever,
51
+ autoDescribe: opts.autoDescribe,
52
52
  sqliteVecExtensionPath: opts.sqliteVecExtensionPath,
53
53
  embeddingModels: opts.embeddingModels ?? null,
54
- }), 'utf8');
54
+ };
55
+ }
56
+ /**
57
+ * 在独立子进程启动 Knowledge HTTP Service。
58
+ *
59
+ * @param opts - 与 startKnowledgeService 同构 + embeddingModels(子进程内重建 provider)
60
+ * @returns child + 端口 + stop
61
+ */
62
+ export async function startKnowledgeServiceProcess(opts) {
63
+ const entry = fileURLToPath(resolveWorkerUrl('./knowledge-serve-child.js', import.meta.url));
64
+ const bootDir = await mkdtemp(join(tmpdir(), 'octopi-kn-boot-'));
65
+ const bootPath = join(bootDir, 'boot.json');
66
+ await writeFile(bootPath, JSON.stringify(buildKnowledgeServiceBootFile(opts)), 'utf8');
55
67
  // @types/node 的 ForkOptions 未声明 windowsHide 等字段,运行时有效
56
68
  // execPath 必须保持 process.execPath:Electron 下换捆绑 node 会切断 IPC
57
69
  const forkOpts = {
@@ -20,6 +20,8 @@ export interface KnowledgeScopeRef {
20
20
  /** global: 'global';project: projectKey;session: sessionId */
21
21
  key: string;
22
22
  }
23
+ /** generatedDescription 生成方(信任分级 human > llm > heuristic) */
24
+ export type KnowledgeGeneratedDescriptionSource = 'heuristic' | 'llm' | 'blocked_secret';
23
25
  export type KnowledgeSourceStatus = 'pending' | 'discovering' | 'partial' | 'ready' | 'error' | 'disabled' | 'removed';
24
26
  export type KnowledgeSourceKind = 'workspace' | 'directory' | 'file' | 'url' | 'connector';
25
27
  export interface KnowledgeSourceSync {
@@ -72,6 +74,8 @@ export interface KnowledgeSource {
72
74
  description?: string;
73
75
  /** 自动描述(可被 description 覆盖) */
74
76
  generatedDescription?: string;
77
+ /** 自动描述生成方(信任分级:llm 优于 heuristic;blocked_secret=抽样含密钥形态,未外发) */
78
+ generatedDescriptionSource?: KnowledgeGeneratedDescriptionSource;
75
79
  catalogPriority?: number;
76
80
  hiddenFromCatalog?: boolean;
77
81
  /** CredentialStore 凭证名(密钥不进本库) */
@@ -94,6 +98,7 @@ export type KnowledgeSourceInput = {
94
98
  displayName?: string;
95
99
  description?: string;
96
100
  generatedDescription?: string;
101
+ generatedDescriptionSource?: KnowledgeGeneratedDescriptionSource;
97
102
  catalogPriority?: number;
98
103
  hiddenFromCatalog?: boolean;
99
104
  status?: KnowledgeSourceStatus;
@@ -107,6 +112,8 @@ export type KnowledgeSourcePatch = Partial<Pick<KnowledgeSource, 'location' | 's
107
112
  displayName?: string | null;
108
113
  description?: string | null;
109
114
  generatedDescription?: string | null;
115
+ /** 传 null 可清除(与 generatedDescription 同清) */
116
+ generatedDescriptionSource?: KnowledgeGeneratedDescriptionSource | null;
110
117
  authRef?: string | null;
111
118
  network?: KnowledgeSourceNetwork | null;
112
119
  discover?: KnowledgeSourceDiscover | null;
@@ -12,6 +12,7 @@ import { KnowledgeIngest, type IngestProgressEvent } from './ingest.js';
12
12
  import type { KnowledgeSource } from './types.js';
13
13
  import type { KnowledgeJobControlState } from './job-control-state.js';
14
14
  import type { DocumentCapabilityConfig } from '../capabilities/document/factory.js';
15
+ import type { KnowledgeBootEmbed, KnowledgeBootIngest } from './boot-config.js';
15
16
  import type { EmbeddingProvider } from '../memory/sqlite/embedding.js';
16
17
  export interface WriteIdentity {
17
18
  tenantId: string;
@@ -33,6 +34,25 @@ export interface WriteDescribeResult {
33
34
  generatedDescription: string;
34
35
  source: string;
35
36
  }
37
+ /** gateway 代生成(B 方案)的抽样出 Service 边界形态:密钥扫描在此把关 */
38
+ export type WriteDescribeSampleResult = {
39
+ blocked: false;
40
+ meta: {
41
+ displayName: string;
42
+ kind: string;
43
+ location: string;
44
+ };
45
+ sample: string;
46
+ } | {
47
+ blocked: true;
48
+ secretHits: string[];
49
+ };
50
+ /** describe 写入口(gateway 回写 LLM 描述) */
51
+ export interface WriteDescribeInput {
52
+ description: string;
53
+ /** 缺省 'llm'(写入口的调用方是 gateway 的 LLM describe 流程) */
54
+ source?: 'llm' | 'heuristic';
55
+ }
36
56
  export interface WriteReprocessResult {
37
57
  queued: number;
38
58
  alreadyActive: number;
@@ -69,7 +89,11 @@ export interface KnowledgeWriteService {
69
89
  id: string;
70
90
  purgedFiles: number;
71
91
  }>;
72
- describeSource(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeResult | null>;
92
+ describeSource(identity: WriteIdentity, sourceId: string, input?: WriteDescribeInput): Promise<WriteDescribeResult | null>;
93
+ /** 抽样出 Service 边界(gateway 代生成取素材);密钥命中即封锁不外发 */
94
+ describeSample(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeSampleResult | null>;
95
+ /** 待 LLM 升级的源(heuristic/legacy 归因且无人工描述),供 gateway boot sweep */
96
+ listDescribePending(identity: WriteIdentity): Promise<string[]>;
73
97
  reindexSource(sourceId: string): Promise<void>;
74
98
  /** 按路径强制重解析(中止态自动 resume) */
75
99
  reprocessFiles(sourceId: string, paths: string[]): Promise<WriteReprocessResult>;
@@ -112,13 +136,11 @@ export interface LocalWriteDeps {
112
136
  embeddingProvider?: EmbeddingProvider | null;
113
137
  /** source.authRef 解析(SEC-3c consumer 绑定强制) */
114
138
  credentials?: import('../governance/credentials/store.js').CredentialStore | null;
115
- embed?: {
116
- enabled?: boolean;
117
- embedBatch?: number;
118
- embedMinIntervalMs?: number;
119
- embedConcurrency?: number;
120
- embedSecretPolicy?: 'allow' | 'redact' | 'skip';
121
- } | null;
139
+ embed?: KnowledgeBootEmbed | null;
140
+ /** Ingest 调参(knowledge.load / index.queue / index.files) */
141
+ ingest?: KnowledgeBootIngest | null;
142
+ /** false = 索引稳定后不自动生成 generatedDescription(knowledge.catalog.autoDescribe) */
143
+ autoDescribe?: boolean;
122
144
  }
123
145
  /** 进程内唯一写者(测试 / :memory:)。 */
124
146
  export declare class LocalKnowledgeWriteService implements KnowledgeWriteService {
@@ -156,7 +178,11 @@ export declare class LocalKnowledgeWriteService implements KnowledgeWriteService
156
178
  id: string;
157
179
  purgedFiles: number;
158
180
  }>;
159
- describeSource(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeResult | null>;
181
+ describeSource(identity: WriteIdentity, sourceId: string, input?: WriteDescribeInput): Promise<WriteDescribeResult | null>;
182
+ describeSample(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeSampleResult | null>;
183
+ listDescribePending(identity: WriteIdentity): Promise<string[]>;
184
+ /** 启发式/封锁描述生成(无 describePort:Service 侧永不含 LLM 出网,B 方案拍板) */
185
+ private describeWithSample;
160
186
  private assertSourceOwner;
161
187
  reindexSource(sourceId: string): Promise<void>;
162
188
  reprocessFiles(sourceId: string, paths: string[]): Promise<WriteReprocessResult>;
@@ -192,5 +218,7 @@ export declare class LocalKnowledgeWriteService implements KnowledgeWriteService
192
218
  sourceVisibleToGateway(sourceId: string, gatewayId: string): Promise<boolean>;
193
219
  startIngestRuntime(): Promise<void>;
194
220
  onProgress(cb: (evt: IngestProgressEvent) => void): () => void;
221
+ /** Writer 自产事件(describe-pending 等);归属补齐口径与 IngestProgressEvent 一致 */
222
+ private emitProgress;
195
223
  dispose(): Promise<void>;
196
224
  }
@@ -8,7 +8,9 @@ import { KnowledgeSourceStore } from './source-store.js';
8
8
  import { KnowledgeIndexStore } from './index-store.js';
9
9
  import { MembershipStore } from './membership-store.js';
10
10
  import { KnowledgeIngest } from './ingest.js';
11
- import { generateKnowledgeDescription } from './describe.js';
11
+ import { generateKnowledgeDescription, normalizeGeneratedDescription, } from './describe.js';
12
+ import { assembleDescribeSample, DESCRIBE_SAMPLE_MAX_CHARS } from './describe-sample.js';
13
+ import { scanSecretShapes } from './secret-scan.js';
12
14
  /** 进程内唯一写者(测试 / :memory:)。 */
13
15
  export class LocalKnowledgeWriteService {
14
16
  deps;
@@ -29,6 +31,7 @@ export class LocalKnowledgeWriteService {
29
31
  documentConfig: deps.documentConfig ?? null,
30
32
  embeddingProvider: embed?.enabled === false ? null : (deps.embeddingProvider ?? null),
31
33
  credentials: deps.credentials ?? null,
34
+ ...(deps.ingest ?? {}),
32
35
  ...(embed?.embedBatch != null ? { embedBatch: embed.embedBatch } : {}),
33
36
  ...(embed?.embedMinIntervalMs != null ? { embedMinIntervalMs: embed.embedMinIntervalMs } : {}),
34
37
  ...(embed?.embedConcurrency != null ? { embedConcurrency: embed.embedConcurrency } : {}),
@@ -185,19 +188,68 @@ export class LocalKnowledgeWriteService {
185
188
  this.sources.remove(sourceId);
186
189
  return { id: sourceId, purgedFiles: purged.length };
187
190
  }
188
- async describeSource(identity, sourceId) {
191
+ async describeSource(identity, sourceId, input) {
189
192
  await this.assertSourceOwner(identity, sourceId);
190
193
  const src = this.sources.get(sourceId);
191
194
  if (!src)
192
195
  return null;
193
- const paths = this.db.raw
194
- .prepare('SELECT logical_path FROM knowledge_memberships WHERE source_id = ? ORDER BY logical_path LIMIT 20')
195
- .all(sourceId);
196
- const sample = paths.map((p) => p.logical_path).join('\n') || src.location;
197
- const r = await generateKnowledgeDescription(src, sample, { enabled: true });
198
- this.sources.update(sourceId, { generatedDescription: r.description });
196
+ if (input?.description != null) {
197
+ // 写入口(B 方案回写):调用方是 gateway 的 LLM describe 流程;内容在出 Service 前过密钥扫描,
198
+ // 但描述会进系统提示 catalog 行——写入侧强制单行归一(防多行注入伪造 catalog 行)
199
+ const text = normalizeGeneratedDescription(input.description);
200
+ if (!text) {
201
+ throw Object.assign(new Error('description empty'), { code: 'bad_request' });
202
+ }
203
+ const source = input.source === 'heuristic' ? 'heuristic' : 'llm';
204
+ this.sources.update(sourceId, {
205
+ generatedDescription: text,
206
+ generatedDescriptionSource: source,
207
+ });
208
+ return { generatedDescription: text, source };
209
+ }
210
+ const r = await this.describeWithSample(src);
211
+ this.sources.update(sourceId, {
212
+ generatedDescription: r.description,
213
+ generatedDescriptionSource: r.source === 'disabled' ? 'heuristic' : r.source,
214
+ });
199
215
  return { generatedDescription: r.description, source: r.source };
200
216
  }
217
+ async describeSample(identity, sourceId) {
218
+ await this.assertSourceOwner(identity, sourceId);
219
+ const src = this.sources.get(sourceId);
220
+ if (!src)
221
+ return null;
222
+ const sample = assembleDescribeSample(this.db, sourceId);
223
+ // 密钥形态封锁:命中即不外发样本(fail-safe,同 generateKnowledgeDescription 口径)
224
+ const secretHits = scanSecretShapes(sample);
225
+ if (secretHits.length > 0)
226
+ return { blocked: true, secretHits };
227
+ return {
228
+ blocked: false,
229
+ meta: { displayName: src.displayName, kind: src.kind, location: src.location },
230
+ sample,
231
+ };
232
+ }
233
+ async listDescribePending(identity) {
234
+ // 待升级 = 有启发式/legacy 自动描述、无人工描述、归因非 llm(legacy NULL 视为 heuristic)
235
+ const rows = this.db.raw
236
+ .prepare(`SELECT id FROM knowledge_sources
237
+ WHERE generated_description IS NOT NULL
238
+ AND description IS NULL
239
+ AND (generated_description_source IS NULL OR generated_description_source = 'heuristic')
240
+ AND status NOT IN ('removed', 'disabled')
241
+ AND (registered_by IS NULL OR registered_by = '' OR registered_by = ?)`)
242
+ .all(identity.gatewayId);
243
+ return rows.map((r) => r.id);
244
+ }
245
+ /** 启发式/封锁描述生成(无 describePort:Service 侧永不含 LLM 出网,B 方案拍板) */
246
+ describeWithSample(src) {
247
+ const sample = assembleDescribeSample(this.db, src.id);
248
+ return generateKnowledgeDescription(src, sample, {
249
+ enabled: true,
250
+ sampleChars: DESCRIBE_SAMPLE_MAX_CHARS,
251
+ });
252
+ }
201
253
  async assertSourceOwner(identity, sourceId) {
202
254
  const row = this.db.raw
203
255
  .prepare('SELECT registered_by FROM knowledge_sources WHERE id = ?')
@@ -311,17 +363,41 @@ export class LocalKnowledgeWriteService {
311
363
  async startIngestRuntime() {
312
364
  const { sources, ingest } = this;
313
365
  ingest.onSourceSettled = (sourceId) => {
366
+ // catalog.autoDescribe=false:索引稳定后不自动生成 generatedDescription(v0.51.5 语义)
367
+ if (this.deps.autoDescribe === false)
368
+ return;
314
369
  void (async () => {
315
370
  try {
316
371
  const src = sources.get(sourceId);
317
372
  if (!src || src.description?.trim())
318
373
  return;
319
- const paths = this.db.raw
320
- .prepare('SELECT logical_path FROM knowledge_memberships WHERE source_id = ? ORDER BY logical_path LIMIT 20')
321
- .all(sourceId);
322
- const sample = paths.map((p) => p.logical_path).join('\n') || src.location;
323
- const r = await generateKnowledgeDescription(src, sample, { enabled: true });
324
- sources.update(sourceId, { generatedDescription: r.description });
374
+ // llm 归因是更高信任档:settle 不降级、不重发(B 方案 2026-11-02)
375
+ if (src.generatedDescriptionSource === 'llm')
376
+ return;
377
+ const r = await this.describeWithSample(src);
378
+ const source = r.source === 'disabled' ? 'heuristic' : r.source;
379
+ // startReconciler 每 15s 对稳态源反复触发本钩子(ingest.ts):文本与归因都
380
+ // 无变化则不写不发,掐断「每 tick 重发 describe-pending → gateway 每 tick
381
+ // LLM 升级」成本环。归因必须参与比较——blocked_secret 与 heuristic 共享同一
382
+ // 启发式文本,只比文本会让「封锁→清洁」的归因回退永远卡死(评审 P1-1)
383
+ if (src.generatedDescription === r.description &&
384
+ src.generatedDescriptionSource === source) {
385
+ return;
386
+ }
387
+ sources.update(sourceId, {
388
+ generatedDescription: r.description,
389
+ generatedDescriptionSource: source,
390
+ });
391
+ // B 方案(2026-11-02 拍板):LLM 描述由 gateway 代生成。
392
+ // 启发式落库即发升级信号;blocked_secret(抽样含密钥形态)不发——素材不得外发。
393
+ if (source === 'heuristic') {
394
+ this.emitProgress({
395
+ type: 'source',
396
+ sourceId,
397
+ status: 'describe-pending',
398
+ detail: 'llm upgrade eligible',
399
+ });
400
+ }
325
401
  }
326
402
  catch {
327
403
  /* describe 失败不影响索引 */
@@ -349,6 +425,36 @@ export class LocalKnowledgeWriteService {
349
425
  this.progressCbs.delete(cb);
350
426
  };
351
427
  }
428
+ /** Writer 自产事件(describe-pending 等);归属补齐口径与 IngestProgressEvent 一致 */
429
+ emitProgress(evt) {
430
+ let out = evt;
431
+ if (evt.sourceId && evt.registeredBy === undefined) {
432
+ try {
433
+ const row = this.db.raw
434
+ .prepare('SELECT tenant_id, registered_by, visibility FROM knowledge_sources WHERE id = ?')
435
+ .get(evt.sourceId);
436
+ if (row) {
437
+ out = {
438
+ ...evt,
439
+ tenantId: row.tenant_id,
440
+ registeredBy: row.registered_by,
441
+ visibility: row.visibility,
442
+ };
443
+ }
444
+ }
445
+ catch {
446
+ /* 源已删时保持原事件;SSE 侧按无归属放行到 fallback */
447
+ }
448
+ }
449
+ for (const cb of this.progressCbs) {
450
+ try {
451
+ cb(out);
452
+ }
453
+ catch {
454
+ /* SSE 订阅方异常不得打断 describe */
455
+ }
456
+ }
457
+ }
352
458
  async dispose() {
353
459
  this.progressCbs.clear();
354
460
  this.ingest.dispose();
@@ -1,8 +1,9 @@
1
- import type { KnowledgeWriteService, WriteIdentity, WriteAbortStats, WriteResumeStats, WriteRegisterResult, WriteDescribeResult, WriteReprocessResult } from './writer-service.js';
1
+ import type { KnowledgeWriteService, WriteIdentity, WriteAbortStats, WriteResumeStats, WriteRegisterResult, WriteDescribeResult, WriteDescribeInput, WriteDescribeSampleResult, WriteReprocessResult } from './writer-service.js';
2
2
  import type { KnowledgeSource } from './types.js';
3
3
  import type { KnowledgeJobControlState } from './job-control-state.js';
4
4
  import type { IngestProgressEvent } from './ingest.js';
5
5
  import type { DocumentCapabilityConfig } from '../capabilities/document/factory.js';
6
+ import type { KnowledgeBootEmbed, KnowledgeBootIngest } from './boot-config.js';
6
7
  export interface WorkerWriteStartOptions {
7
8
  dbPath: string;
8
9
  documentConfig?: DocumentCapabilityConfig | null;
@@ -11,13 +12,11 @@ export interface WorkerWriteStartOptions {
11
12
  providers?: Record<string, unknown>;
12
13
  embedding?: unknown;
13
14
  } | null;
14
- embed?: {
15
- enabled?: boolean;
16
- embedBatch?: number;
17
- embedMinIntervalMs?: number;
18
- embedConcurrency?: number;
19
- embedSecretPolicy?: 'allow' | 'redact' | 'skip';
20
- } | null;
15
+ embed?: KnowledgeBootEmbed | null;
16
+ /** Ingest 调参(knowledge.load / index.queue / index.files) */
17
+ ingest?: KnowledgeBootIngest | null;
18
+ /** false = 索引稳定后不自动生成 generatedDescription(knowledge.catalog.autoDescribe) */
19
+ autoDescribe?: boolean;
21
20
  testEmbeddingStub?: boolean;
22
21
  timeoutMs?: number;
23
22
  }
@@ -64,7 +63,9 @@ export declare class WorkerWriteService implements KnowledgeWriteService {
64
63
  id: string;
65
64
  purgedFiles: number;
66
65
  }>;
67
- describeSource(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeResult | null>;
66
+ describeSource(identity: WriteIdentity, sourceId: string, input?: WriteDescribeInput): Promise<WriteDescribeResult | null>;
67
+ describeSample(identity: WriteIdentity, sourceId: string): Promise<WriteDescribeSampleResult | null>;
68
+ listDescribePending(identity: WriteIdentity): Promise<string[]>;
68
69
  reindexSource(sourceId: string): Promise<void>;
69
70
  reprocessFiles(sourceId: string, paths: string[]): Promise<WriteReprocessResult>;
70
71
  reprocessByFilter(sourceId: string, filter?: {
@@ -93,6 +93,8 @@ export class WorkerWriteService {
93
93
  sqliteVecExtensionPath: opts.sqliteVecExtensionPath,
94
94
  embeddingModels: opts.embeddingModels ?? null,
95
95
  embed: opts.embed ?? null,
96
+ ingest: opts.ingest ?? null,
97
+ autoDescribe: opts.autoDescribe,
96
98
  testEmbeddingStub: opts.testEmbeddingStub ?? false,
97
99
  },
98
100
  env: process.env,
@@ -225,9 +227,25 @@ export class WorkerWriteService {
225
227
  this.rethrow(e);
226
228
  }
227
229
  }
228
- async describeSource(identity, sourceId) {
230
+ async describeSource(identity, sourceId, input) {
229
231
  try {
230
- return (await this.call('describeSource', { identity, sourceId }));
232
+ return (await this.call('describeSource', { identity, sourceId, input }));
233
+ }
234
+ catch (e) {
235
+ this.rethrow(e);
236
+ }
237
+ }
238
+ async describeSample(identity, sourceId) {
239
+ try {
240
+ return (await this.call('describeSample', { identity, sourceId }));
241
+ }
242
+ catch (e) {
243
+ this.rethrow(e);
244
+ }
245
+ }
246
+ async listDescribePending(identity) {
247
+ try {
248
+ return (await this.call('listDescribePending', { identity }));
231
249
  }
232
250
  catch (e) {
233
251
  this.rethrow(e);
@@ -46,6 +46,8 @@ async function main() {
46
46
  documentConfig: boot.documentConfig ?? null,
47
47
  embeddingProvider: embeddingProvider,
48
48
  embed: boot.embed ?? null,
49
+ ingest: boot.ingest ?? null,
50
+ autoDescribe: boot.autoDescribe,
49
51
  });
50
52
  write.onProgress((evt) => {
51
53
  port.postMessage({ type: 'progress', evt });
@@ -105,7 +107,13 @@ async function main() {
105
107
  data = await write.removeSource(identity, String(args.sourceId));
106
108
  break;
107
109
  case 'describeSource':
108
- data = await write.describeSource(identity, String(args.sourceId));
110
+ data = await write.describeSource(identity, String(args.sourceId), args.input);
111
+ break;
112
+ case 'describeSample':
113
+ data = await write.describeSample(identity, String(args.sourceId));
114
+ break;
115
+ case 'listDescribePending':
116
+ data = await write.listDescribePending(identity);
109
117
  break;
110
118
  case 'reindexSource':
111
119
  await write.reindexSource(String(args.sourceId));
@@ -31,6 +31,15 @@ export class SqliteWisdomStore {
31
31
  const now = Date.now();
32
32
  const status = resolveInitialWisdomStatus(input);
33
33
  const id = AgentDatabase.generateId('wis');
34
+ const insertRow = () => {
35
+ this.db.raw
36
+ .prepare(`INSERT INTO wisdom (
37
+ id, statement, rationale, scenario_json, effect_json, status, confidence, priority,
38
+ derived_from_json, exceptions_json, counterevidence_json, outcomes_json,
39
+ origin, kind, superseded_by, created_at, updated_at
40
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
41
+ .run(id, input.statement.trim(), input.rationale?.trim() || null, JSON.stringify(input.scenario), JSON.stringify(input.effect), status, clamp01(input.confidence ?? defaultConfidence(status, input.origin ?? 'distilled')), input.priority ?? defaultPriority(status, input.origin ?? 'distilled'), JSON.stringify(input.derivedFrom), JSON.stringify(input.exceptions ?? []), JSON.stringify([]), JSON.stringify(emptyOutcomes()), input.origin ?? 'distilled', input.kind, null, now, now);
42
+ };
34
43
  if (input.supersedesId) {
35
44
  const prev = this.getSync(input.supersedesId);
36
45
  if (!prev) {
@@ -40,17 +49,32 @@ export class SqliteWisdomStore {
40
49
  message: `supersedesId=${input.supersedesId}`,
41
50
  };
42
51
  }
43
- this.db.raw
44
- .prepare(`UPDATE wisdom SET status = 'superseded', superseded_by = ?, updated_at = ? WHERE id = ?`)
45
- .run(id, now, prev.id);
52
+ // 取代目标必须存活(retired/superseded 已退出主题);factory 是人格级预设,
53
+ // 只经人工通道更换,不许炼制回路静默取代(否则 govern 的出厂保护被绕过)
54
+ if (prev.status === 'retired' || prev.status === 'superseded' || prev.origin === 'factory') {
55
+ return {
56
+ action: 'rejected',
57
+ reason: 'supersedes_target_invalid',
58
+ message: `supersedes_target=${prev.status}/${prev.origin}`,
59
+ };
60
+ }
61
+ // 旧条目改写与新条目写入同事务:避免 INSERT 失败留下「已 superseded 但无继任者」悬挂链
62
+ this.db.raw.exec('BEGIN IMMEDIATE');
63
+ try {
64
+ this.db.raw
65
+ .prepare(`UPDATE wisdom SET status = 'superseded', superseded_by = ?, updated_at = ? WHERE id = ?`)
66
+ .run(id, now, prev.id);
67
+ insertRow();
68
+ this.db.raw.exec('COMMIT');
69
+ }
70
+ catch (err) {
71
+ this.db.raw.exec('ROLLBACK');
72
+ throw err;
73
+ }
74
+ }
75
+ else {
76
+ insertRow();
46
77
  }
47
- this.db.raw
48
- .prepare(`INSERT INTO wisdom (
49
- id, statement, rationale, scenario_json, effect_json, status, confidence, priority,
50
- derived_from_json, exceptions_json, counterevidence_json, outcomes_json,
51
- origin, kind, superseded_by, created_at, updated_at
52
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
53
- .run(id, input.statement.trim(), input.rationale?.trim() || null, JSON.stringify(input.scenario), JSON.stringify(input.effect), status, clamp01(input.confidence ?? defaultConfidence(status, input.origin ?? 'distilled')), input.priority ?? defaultPriority(status, input.origin ?? 'distilled'), JSON.stringify(input.derivedFrom), JSON.stringify(input.exceptions ?? []), JSON.stringify([]), JSON.stringify(emptyOutcomes()), input.origin ?? 'distilled', input.kind, null, now, now);
54
78
  return {
55
79
  action: input.supersedesId ? 'superseded' : 'created',
56
80
  id,
@@ -68,6 +92,7 @@ export class SqliteWisdomStore {
68
92
  return pickForInjection(entries, query.text ?? '', {
69
93
  coreMaxItems: query.coreMaxItems,
70
94
  scenarioMaxItems: query.scenarioMaxItems,
95
+ trialMaxItems: query.trialMaxItems,
71
96
  includeTrial: query.includeTrial,
72
97
  });
73
98
  }