@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
@@ -9,3 +9,4 @@ export * from './service.js';
9
9
  export * from './inject.js';
10
10
  export * from './intent.js';
11
11
  export * from './llm-intent.js';
12
+ export * from './recall-index.js';
@@ -9,3 +9,4 @@ export * from './service.js';
9
9
  export * from './inject.js';
10
10
  export * from './intent.js';
11
11
  export * from './llm-intent.js';
12
+ export * from './recall-index.js';
@@ -4,23 +4,24 @@
4
4
  * 与 Knowledge grounding 同气质:不可信包装、不进 system、与指令分离。
5
5
  */
6
6
  import type { ContentBlock, Message } from '@octopi-agent/core/types.js';
7
- import type { SessionAttachment } from './types.js';
7
+ import type { AttachmentInjectPlan, SessionAttachment } from './types.js';
8
+ import type { AttachmentRecallHit } from './recall-index.js';
8
9
  export declare const ATTACHMENT_GROUNDING_SOURCE: "sessionAttachment";
9
10
  /** 默认空正文指令(§6.5) */
10
11
  export declare const DEFAULT_EMPTY_ATTACHMENT_PROMPT = "\uFF08\u4EC5\u9644\u4EF6\uFF0C\u65E0\u6587\u5B57\u6307\u4EE4\uFF09\u8BF7\u67E5\u770B\u6240\u9644\u6587\u4EF6\uFF1B\u82E5\u610F\u56FE\u4E0D\u660E\uFF0C\u5148\u7B80\u8981\u8BF4\u660E\u5185\u5BB9\u518D\u5411\u7528\u6237\u63D0\u95EE\u3002";
11
12
  export interface AttachmentInjectOptions {
12
13
  /** 全文阈值(字符);超过走结构 */
13
14
  fullTextMaxChars: number;
14
- /** 结构模式下每文件头几行 */
15
- headLines?: number;
15
+ /** 局部召回条数(默认 6) */
16
+ recallTopK?: number;
16
17
  /** 结构模式下每文件开头字符(默认 3500) */
17
18
  headChars?: number;
18
- /** 空正文模板 */
19
- emptyMessagePrompt?: string;
20
- /** 读取抽取文本 */
19
+ /** 读取抽取文本;maxChars 仅用于结构/全文注入,不用于召回索引 */
21
20
  readText: (attachmentId: string, maxChars: number) => string | null;
22
21
  /** 附件绝对地址(给 LLM) */
23
22
  absolutePath: (attachmentId: string) => string;
23
+ /** Session 私有索引查询;不得越出传入的附件范围 */
24
+ recall?: (query: string, attachmentIds: string[], limit: number) => Promise<AttachmentRecallHit[] | null>;
24
25
  }
25
26
  export interface AttachmentInjectResult {
26
27
  /** 用户消息 content(含 FileBlock / 合成指令) */
@@ -49,14 +50,24 @@ export declare function buildAttachmentMessageContent(attachments: SessionAttach
49
50
  content: string | ContentBlock[];
50
51
  syntheticInstruction?: boolean;
51
52
  };
53
+ export interface AttachmentGroundingResult {
54
+ /** turn 侧不可信资料块;无附件为 null */
55
+ text: string | null;
56
+ /** 实际执行的局部召回命中数 */
57
+ recallHits: number;
58
+ /** 局部召回不可用/零命中后回退结构的附件 */
59
+ fallbackAttachmentIds: string[];
60
+ }
52
61
  /**
53
- * 构造 turn 侧附件资料块(不可信)
62
+ * 构造 turn 侧附件资料块(不可信)。
63
+ * 局部计划跨附件全局 top-k;召回不可用或零命中时逐附件回退结构。
54
64
  *
55
65
  * @param attachments - 参与本轮的附件
56
- * @param opts - 注入选项
57
- * @param planMode - 分层形态;缺省按体积自动
66
+ * @param opts - 注入与受限召回选项
67
+ * @param plan - LLM/确定性分流产生的完整计划;缺省按体积自动
68
+ * @returns 包装后的资料块及召回/降级观测信息
58
69
  */
59
- export declare function buildAttachmentGroundingText(attachments: SessionAttachment[], opts: AttachmentInjectOptions, planMode?: 'full' | 'structure_tools' | 'recall_tools' | 'overview_tools'): string | null;
70
+ export declare function buildAttachmentGroundingText(attachments: SessionAttachment[], opts: AttachmentInjectOptions, plan?: AttachmentInjectPlan): Promise<AttachmentGroundingResult>;
60
71
  /**
61
72
  * 空正文时的默认 user 文本(§6.5)
62
73
  *
@@ -47,16 +47,18 @@ export function buildAttachmentMessageContent(attachments, userText, opts) {
47
47
  };
48
48
  }
49
49
  /**
50
- * 构造 turn 侧附件资料块(不可信)
50
+ * 构造 turn 侧附件资料块(不可信)。
51
+ * 局部计划跨附件全局 top-k;召回不可用或零命中时逐附件回退结构。
51
52
  *
52
53
  * @param attachments - 参与本轮的附件
53
- * @param opts - 注入选项
54
- * @param planMode - 分层形态;缺省按体积自动
54
+ * @param opts - 注入与受限召回选项
55
+ * @param plan - LLM/确定性分流产生的完整计划;缺省按体积自动
56
+ * @returns 包装后的资料块及召回/降级观测信息
55
57
  */
56
- export function buildAttachmentGroundingText(attachments, opts, planMode) {
57
- if (attachments.length === 0)
58
- return null;
59
- const headLines = opts.headLines ?? 20;
58
+ export async function buildAttachmentGroundingText(attachments, opts, plan) {
59
+ if (attachments.length === 0) {
60
+ return { text: null, recallHits: 0, fallbackAttachmentIds: [] };
61
+ }
60
62
  const inventory = attachments
61
63
  .map((a, i) => {
62
64
  const abs = opts.absolutePath(a.id);
@@ -72,6 +74,46 @@ export function buildAttachmentGroundingText(attachments, opts, planMode) {
72
74
  inventory,
73
75
  '',
74
76
  ];
77
+ const recallCandidates = plan?.mode === 'recall_tools' && plan.focus?.trim() && opts.recall
78
+ ? attachments.filter((a) => a.kind !== 'image' &&
79
+ (a.parse?.chars ?? 0) > opts.fullTextMaxChars)
80
+ : [];
81
+ const recallCandidateIds = new Set(recallCandidates.map((a) => a.id));
82
+ const hitsByAttachment = new Map();
83
+ const fallbackAttachmentIds = [];
84
+ if (recallCandidates.length > 0 && plan?.focus && opts.recall) {
85
+ // targets 仅缩小本轮已选附件;不在其中/不存在的目标绝不扩大读取范围。
86
+ const requestedNames = new Set((plan.targets ?? []).map((name) => name.toLowerCase()));
87
+ const selected = requestedNames.size > 0
88
+ ? recallCandidates.filter((a) => requestedNames.has(a.name.toLowerCase()))
89
+ : recallCandidates;
90
+ const selectedIds = new Set(selected.map((a) => a.id));
91
+ for (const a of recallCandidates) {
92
+ if (!selectedIds.has(a.id))
93
+ fallbackAttachmentIds.push(a.id);
94
+ }
95
+ try {
96
+ const hits = selected.length > 0
97
+ ? await opts.recall(plan.focus, selected.map((a) => a.id), opts.recallTopK ?? 6)
98
+ : [];
99
+ if (hits) {
100
+ for (const hit of hits) {
101
+ if (!selectedIds.has(hit.attachmentId))
102
+ continue;
103
+ const group = hitsByAttachment.get(hit.attachmentId) ?? [];
104
+ group.push(hit);
105
+ hitsByAttachment.set(hit.attachmentId, group);
106
+ }
107
+ }
108
+ }
109
+ catch {
110
+ // 查询失败仅降级该组大附件为结构,不影响其余全文/路径注入。
111
+ }
112
+ for (const a of selected) {
113
+ if (!hitsByAttachment.has(a.id))
114
+ fallbackAttachmentIds.push(a.id);
115
+ }
116
+ }
75
117
  for (const a of attachments) {
76
118
  const abs = opts.absolutePath(a.id);
77
119
  parts.push(`## ${a.name}`);
@@ -81,38 +123,48 @@ export function buildAttachmentGroundingText(attachments, opts, planMode) {
81
123
  parts.push('');
82
124
  continue;
83
125
  }
84
- // 注意:readText 可能已截断,禁止用返回值 length 判断是否「大文件」
85
- const text = opts.readText(a.id, opts.fullTextMaxChars);
126
+ const hits = hitsByAttachment.get(a.id) ?? [];
127
+ if (hits.length > 0) {
128
+ parts.push(`以下是与局部焦点「${plan?.focus}」相关的关键词召回片段:`);
129
+ for (const hit of hits) {
130
+ parts.push(`### ${hit.symbol ? `${hit.symbol} · ` : ''}第 ${hit.startLine}-${hit.endLine} 行`);
131
+ parts.push(hit.text);
132
+ }
133
+ parts.push('路径: ' + abs);
134
+ parts.push('');
135
+ continue;
136
+ }
137
+ // readText 可能已截断,禁止用返回值 length 判断是否「大文件」。
138
+ const isLarge = (a.parse?.chars ?? 0) > opts.fullTextMaxChars;
139
+ // 小文件在混合计划中仍须全文;大文件的结构/全文按各自阈值读取。
140
+ const readLimit = isLarge ? Math.max(opts.fullTextMaxChars, opts.headChars ?? 3500) : opts.fullTextMaxChars;
141
+ const text = opts.readText(a.id, readLimit);
86
142
  if (!text) {
87
- parts.push(`(未解析或无可读文本;可用 file_read 深读)`);
143
+ parts.push('(未解析或无可读文本;可用 file_read 深读)');
88
144
  parts.push(`路径: ${abs}`);
89
145
  parts.push('');
90
146
  continue;
91
147
  }
92
- const declaredChars = a.parse?.chars ?? text.length;
93
- const isLarge = declaredChars > opts.fullTextMaxChars;
94
- const mode = planMode ?? (isLarge ? 'structure_tools' : 'full');
95
- if (mode === 'full') {
148
+ const mode = plan?.mode ?? (isLarge ? 'structure_tools' : 'full');
149
+ if (mode === 'full' || (!isLarge && !recallCandidateIds.has(a.id))) {
96
150
  parts.push(text);
97
- if (isLarge) {
98
- parts.push(`…(已达注入上限;完整内容请 file_read)`);
99
- }
100
- }
101
- else if (mode === 'recall_tools') {
102
- parts.push(text.split('\n').slice(0, headLines).join('\n'));
103
- parts.push(`…(局部焦点模式;深读用 file_read / knowledge_read)`);
151
+ if (isLarge)
152
+ parts.push('…(已达注入上限;完整内容请 file_read)');
104
153
  }
105
154
  else {
106
- // structure / overview:给足开头(而非仅几行),让「这文件是干嘛的」尽量不必再 read
107
155
  const headChars = Math.min(opts.headChars ?? 3500, text.length);
108
156
  parts.push(text.slice(0, headChars));
109
- parts.push(`…(结构/开头摘要;全文请 file_read)`);
157
+ parts.push('…(结构/开头摘要;全文请 file_read)');
110
158
  }
111
159
  parts.push(`路径: ${abs}`);
112
160
  parts.push('');
113
161
  }
114
162
  parts.push('</session-attachments>');
115
- return parts.join('\n');
163
+ return {
164
+ text: parts.join('\n'),
165
+ recallHits: [...hitsByAttachment.values()].reduce((n, hits) => n + hits.length, 0),
166
+ fallbackAttachmentIds,
167
+ };
116
168
  }
117
169
  /**
118
170
  * 空正文时的默认 user 文本(§6.5)
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Session 附件私有关键词投影 — 默认本地召回,不注册 Knowledge source。
3
+ *
4
+ * 原件与 manifest 是权威;本投影可由抽取文本重建,生命周期随 attachments root。
5
+ */
6
+ import type { SessionAttachment } from './types.js';
7
+ export interface AttachmentRecallChunk {
8
+ ordinal: number;
9
+ text: string;
10
+ startLine: number;
11
+ endLine: number;
12
+ symbol?: string;
13
+ }
14
+ export interface AttachmentRecallHit extends AttachmentRecallChunk {
15
+ attachmentId: string;
16
+ attachmentName: string;
17
+ score: number;
18
+ }
19
+ /**
20
+ * 有界、可重建的附件关键词索引;调用方负责传入同一 Session 的附件。
21
+ */
22
+ export declare class SessionAttachmentRecallIndex {
23
+ private readonly root;
24
+ private readonly path;
25
+ private readonly adapters;
26
+ constructor(root: string);
27
+ /**
28
+ * 用完整抽取文本覆盖单附件索引;不读取截断文本做索引。
29
+ *
30
+ * @param attachment - 已解析的附件登记
31
+ * @param text - 完整抽取文本
32
+ * @param sourcePath - 原附件逻辑路径,用于选择格式 adapter
33
+ */
34
+ upsert(attachment: SessionAttachment, text: string, sourcePath: string): Promise<void>;
35
+ /**
36
+ * 删除单附件的本地投影。
37
+ *
38
+ * @param attachmentId - 附件 id
39
+ */
40
+ remove(attachmentId: string): Promise<void>;
41
+ /** 删除整个 Session 的本地投影。 */
42
+ clear(): Promise<void>;
43
+ /**
44
+ * 从权威抽取文本完整重建投影。调用方须收集全部成功后原子替换。
45
+ *
46
+ * @param items - 附件与完整抽取文本;缺项表示该附件没有可索引文本
47
+ */
48
+ rebuild(items: Array<{
49
+ attachment: SessionAttachment;
50
+ text: string;
51
+ sourcePath: string;
52
+ }>): Promise<void>;
53
+ /**
54
+ * 仅查询已落盘投影;缺失/损坏/指纹不符返回 null,由注入层回退 structure_tools。
55
+ *
56
+ * @param query - LLM 分流给出的 focus 或用户正文
57
+ * @param attachments - 本轮可见附件;此处仅缩范围,不扩大权限
58
+ * @param limit - 全局 top-k 条数
59
+ * @returns 有完整有效索引时的关键词命中;不可召回时 null
60
+ */
61
+ search(query: string, attachments: SessionAttachment[], limit: number): Promise<AttachmentRecallHit[] | null>;
62
+ private load;
63
+ /** 首次创建允许空投影;已有文件损坏不得被当作空表覆盖。 */
64
+ private loadForWrite;
65
+ private read;
66
+ /** 正常代次只读 stat;变化时读全文验指纹,旧 manifest 缺代次不静默信任。 */
67
+ private matchesExtract;
68
+ private persist;
69
+ }
70
+ export declare function attachmentExtractHash(attachment: SessionAttachment, text: string): string;
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Session 附件私有关键词投影 — 默认本地召回,不注册 Knowledge source。
3
+ *
4
+ * 原件与 manifest 是权威;本投影可由抽取文本重建,生命周期随 attachments root。
5
+ */
6
+ import { createHash, randomUUID } from 'node:crypto';
7
+ import { existsSync, readFileSync, statSync } from 'node:fs';
8
+ import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
9
+ import { join } from 'node:path';
10
+ import { codeAdapter, FormatAdapterRegistry, markdownAdapter, textAdapter, } from '../../knowledge/adapters.js';
11
+ import { scoreKeywordCoverage, tokenizeKeywordDetail, } from '../../memory/sqlite/keyword-search.js';
12
+ const INDEX_FILE = '.recall-index.json';
13
+ const INDEX_VERSION = 1;
14
+ const MAX_INDEXED_CHARS = 25 * 1024 * 1024;
15
+ /**
16
+ * 有界、可重建的附件关键词索引;调用方负责传入同一 Session 的附件。
17
+ */
18
+ export class SessionAttachmentRecallIndex {
19
+ root;
20
+ path;
21
+ adapters = new FormatAdapterRegistry([
22
+ textAdapter,
23
+ markdownAdapter,
24
+ codeAdapter,
25
+ ]);
26
+ constructor(root) {
27
+ this.root = root;
28
+ this.path = join(root, INDEX_FILE);
29
+ }
30
+ /**
31
+ * 用完整抽取文本覆盖单附件索引;不读取截断文本做索引。
32
+ *
33
+ * @param attachment - 已解析的附件登记
34
+ * @param text - 完整抽取文本
35
+ * @param sourcePath - 原附件逻辑路径,用于选择格式 adapter
36
+ */
37
+ async upsert(attachment, text, sourcePath) {
38
+ if (text.length > MAX_INDEXED_CHARS) {
39
+ throw new Error('attachment extract exceeds local recall index limit');
40
+ }
41
+ const adapter = this.adapters.match(sourcePath) ?? textAdapter;
42
+ const next = await this.loadForWrite();
43
+ if (text.length === 0) {
44
+ delete next.attachments[attachment.id];
45
+ }
46
+ else {
47
+ next.attachments[attachment.id] = {
48
+ name: attachment.name,
49
+ fingerprint: attachmentExtractHash(attachment, text),
50
+ chunks: chunksForIndex(adapter, text, sourcePath),
51
+ };
52
+ }
53
+ await this.persist(next);
54
+ }
55
+ /**
56
+ * 删除单附件的本地投影。
57
+ *
58
+ * @param attachmentId - 附件 id
59
+ */
60
+ async remove(attachmentId) {
61
+ const next = await this.loadForWrite();
62
+ if (!(attachmentId in next.attachments))
63
+ return;
64
+ delete next.attachments[attachmentId];
65
+ await this.persist(next);
66
+ }
67
+ /** 删除整个 Session 的本地投影。 */
68
+ async clear() {
69
+ await rm(this.path, { force: true });
70
+ }
71
+ /**
72
+ * 从权威抽取文本完整重建投影。调用方须收集全部成功后原子替换。
73
+ *
74
+ * @param items - 附件与完整抽取文本;缺项表示该附件没有可索引文本
75
+ */
76
+ async rebuild(items) {
77
+ const next = { version: INDEX_VERSION, attachments: {} };
78
+ for (const { attachment, text, sourcePath } of items) {
79
+ if (text.length > MAX_INDEXED_CHARS) {
80
+ throw new Error('attachment extract exceeds local recall index limit');
81
+ }
82
+ if (text.length === 0)
83
+ continue;
84
+ const adapter = this.adapters.match(sourcePath) ?? textAdapter;
85
+ next.attachments[attachment.id] = {
86
+ name: attachment.name,
87
+ fingerprint: attachmentExtractHash(attachment, text),
88
+ chunks: chunksForIndex(adapter, text, sourcePath),
89
+ };
90
+ }
91
+ await this.persist(next);
92
+ }
93
+ /**
94
+ * 仅查询已落盘投影;缺失/损坏/指纹不符返回 null,由注入层回退 structure_tools。
95
+ *
96
+ * @param query - LLM 分流给出的 focus 或用户正文
97
+ * @param attachments - 本轮可见附件;此处仅缩范围,不扩大权限
98
+ * @param limit - 全局 top-k 条数
99
+ * @returns 有完整有效索引时的关键词命中;不可召回时 null
100
+ */
101
+ async search(query, attachments, limit) {
102
+ const tokens = tokenizeKeywordDetail(query);
103
+ if (tokens.all.length === 0 || attachments.length === 0 || limit <= 0)
104
+ return [];
105
+ const data = await this.load();
106
+ for (const attachment of attachments) {
107
+ const indexed = data.attachments[attachment.id];
108
+ if (!indexed || !this.matchesExtract(attachment, indexed.fingerprint))
109
+ return null;
110
+ }
111
+ const hits = [];
112
+ for (const attachment of attachments) {
113
+ const indexed = data.attachments[attachment.id];
114
+ for (const chunk of indexed.chunks) {
115
+ const score = scoreKeywordCoverage({ content: chunk.text, tags: [attachment.name, chunk.symbol ?? ''] }, tokens);
116
+ if (score > 0) {
117
+ hits.push({
118
+ ...chunk,
119
+ attachmentId: attachment.id,
120
+ attachmentName: attachment.name,
121
+ score,
122
+ });
123
+ }
124
+ }
125
+ }
126
+ return hits
127
+ .sort((a, b) => b.score - a.score ||
128
+ a.attachmentName.localeCompare(b.attachmentName) ||
129
+ a.ordinal - b.ordinal)
130
+ .slice(0, limit);
131
+ }
132
+ async load() {
133
+ if (!existsSync(this.path)) {
134
+ throw new Error('attachment recall index unavailable');
135
+ }
136
+ return this.read();
137
+ }
138
+ /** 首次创建允许空投影;已有文件损坏不得被当作空表覆盖。 */
139
+ async loadForWrite() {
140
+ if (!existsSync(this.path))
141
+ return { version: INDEX_VERSION, attachments: {} };
142
+ return this.read();
143
+ }
144
+ read() {
145
+ try {
146
+ const parsed = JSON.parse(readFileSync(this.path, 'utf8'));
147
+ if (!isIndexData(parsed))
148
+ throw new Error('invalid attachment recall index');
149
+ return parsed;
150
+ }
151
+ catch (err) {
152
+ throw new Error(`attachment recall index unavailable: ${err instanceof Error ? err.message : String(err)}`);
153
+ }
154
+ }
155
+ /** 正常代次只读 stat;变化时读全文验指纹,旧 manifest 缺代次不静默信任。 */
156
+ matchesExtract(attachment, indexedHash) {
157
+ const parse = attachment.parse;
158
+ if (!attachment.extractPath || !parse?.extractHash ||
159
+ parse.extractBytes == null || parse.extractMtimeMs == null || parse.extractCtimeMs == null) {
160
+ return false;
161
+ }
162
+ try {
163
+ const stat = statSync(join(this.root, attachment.extractPath));
164
+ if (stat.size !== parse.extractBytes)
165
+ return false;
166
+ if (stat.mtimeMs === parse.extractMtimeMs &&
167
+ stat.ctimeMs === parse.extractCtimeMs) {
168
+ return indexedHash === parse.extractHash;
169
+ }
170
+ const text = readFileSync(join(this.root, attachment.extractPath), 'utf8');
171
+ return indexedHash === attachmentExtractHash(attachment, text);
172
+ }
173
+ catch {
174
+ // 抽取文件缺失/不可读时没有权威依据,召回回退结构。
175
+ return false;
176
+ }
177
+ }
178
+ async persist(data) {
179
+ await mkdir(this.root, { recursive: true });
180
+ const tmp = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
181
+ await writeFile(tmp, JSON.stringify(data));
182
+ await rename(tmp, this.path);
183
+ }
184
+ }
185
+ /** Knowledge 的 codeAdapter 会跳过超长行;附件索引必须保留全部可检索文本。 */
186
+ function chunksForIndex(adapter, text, sourcePath) {
187
+ if (adapter.id !== 'code-tree' || !text.split('\n').some((line) => line.length > 2400)) {
188
+ return adapter.chunk(text, sourcePath).map((chunk) => ({
189
+ ordinal: chunk.ordinal,
190
+ text: chunk.text,
191
+ startLine: chunk.startLine,
192
+ endLine: chunk.endLine,
193
+ ...(chunk.symbol ? { symbol: chunk.symbol } : {}),
194
+ }));
195
+ }
196
+ return textAdapter.chunk(text, sourcePath);
197
+ }
198
+ export function attachmentExtractHash(attachment, text) {
199
+ return createHash('sha256')
200
+ .update(attachment.contentHash)
201
+ .update('\0')
202
+ .update(text)
203
+ .digest('hex');
204
+ }
205
+ function isIndexData(value) {
206
+ if (value == null || typeof value !== 'object')
207
+ return false;
208
+ const data = value;
209
+ if (data.version !== INDEX_VERSION || data.attachments == null || typeof data.attachments !== 'object') {
210
+ return false;
211
+ }
212
+ return Object.values(data.attachments).every((item) => typeof item.name === 'string' &&
213
+ typeof item.fingerprint === 'string' &&
214
+ Array.isArray(item.chunks) &&
215
+ item.chunks.every((chunk) => Number.isInteger(chunk.ordinal) &&
216
+ Number.isInteger(chunk.startLine) &&
217
+ Number.isInteger(chunk.endLine) &&
218
+ typeof chunk.text === 'string'));
219
+ }
@@ -56,6 +56,27 @@ export declare class SessionAttachmentService {
56
56
  * @throws 超限 / 类型不允许
57
57
  */
58
58
  save(sessionId: string, input: AttachmentUploadInput): Promise<SessionAttachment>;
59
+ /**
60
+ * 上传解析成功后默认建立 Session 私有关键词投影,不注册 Knowledge source。
61
+ * 索引是可重建降级面:失败不影响原件与抽取文本的保存。
62
+ */
63
+ private indexSavedAttachment;
64
+ /**
65
+ * 查询本轮附件的本地关键词召回;索引不可用由调用方回退 structure_tools。
66
+ *
67
+ * @param sessionId - 会话 id
68
+ * @param query - 局部检索焦点
69
+ * @param attachmentIds - 本轮已授权的附件范围
70
+ * @param limit - 全局 top-k
71
+ */
72
+ recall(sessionId: string, query: string, attachmentIds: string[], limit: number): Promise<import("./recall-index.js").AttachmentRecallHit[] | null>;
73
+ /**
74
+ * 从 manifest + 完整抽取文本重建本地投影;全部读取成功后才替换旧投影。
75
+ * 普通发送不调用此重路径,索引不可用时仍按 structure_tools 降级。
76
+ *
77
+ * @param sessionId - 会话 id
78
+ */
79
+ rebuildRecall(sessionId: string): Promise<void>;
59
80
  /**
60
81
  * 删除附件(原件 + 伴生 + manifest 条目)
61
82
  *