@zhin.js/core 1.1.34 → 1.1.37

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 (326) hide show
  1. package/README.md +84 -142
  2. package/lib/built/ai-access.d.ts +36 -0
  3. package/lib/built/ai-access.js +46 -0
  4. package/lib/built/ai-outbound/extensions/onebot-keyboard.d.ts +2 -0
  5. package/lib/built/ai-outbound/extensions/onebot-keyboard.js +67 -0
  6. package/lib/built/ai-outbound/extensions/qq-message.d.ts +3 -0
  7. package/lib/built/ai-outbound/extensions/qq-message.js +23 -0
  8. package/lib/built/ai-outbound/index.d.ts +8 -0
  9. package/lib/built/ai-outbound/index.js +8 -0
  10. package/lib/built/ai-outbound/parse.d.ts +13 -0
  11. package/lib/built/ai-outbound/parse.js +104 -0
  12. package/lib/built/ai-outbound/plain-mention-rewrite.d.ts +6 -0
  13. package/lib/built/ai-outbound/plain-mention-rewrite.js +37 -0
  14. package/lib/built/ai-outbound/prompt.d.ts +11 -0
  15. package/lib/built/ai-outbound/prompt.js +44 -0
  16. package/lib/built/ai-outbound/resolve.d.ts +4 -0
  17. package/lib/built/ai-outbound/resolve.js +64 -0
  18. package/lib/built/ai-outbound/structured-detect.d.ts +3 -0
  19. package/lib/built/ai-outbound/structured-detect.js +6 -0
  20. package/lib/built/ai-outbound/types.d.ts +49 -0
  21. package/lib/built/ai-outbound/types.js +5 -0
  22. package/lib/built/ai-trigger.d.ts +12 -17
  23. package/lib/built/ai-trigger.js +39 -70
  24. package/lib/built/common-adapter-tools.d.ts +33 -29
  25. package/lib/built/common-adapter-tools.js +79 -67
  26. package/lib/built/generated-qrcode.d.ts +24 -0
  27. package/lib/built/generated-qrcode.js +45 -0
  28. package/lib/built/generic-segment-mapper.d.ts +4 -0
  29. package/lib/built/generic-segment-mapper.js +190 -0
  30. package/lib/built/html-segment-fallback.d.ts +2 -5
  31. package/lib/built/html-segment-fallback.js +0 -16
  32. package/lib/built/html-to-text.d.ts +0 -1
  33. package/lib/built/html-to-text.js +15 -15
  34. package/lib/built/interactive-segments/action.d.ts +17 -0
  35. package/lib/built/interactive-segments/action.js +69 -0
  36. package/lib/built/interactive-segments/button-spec.d.ts +10 -0
  37. package/lib/built/interactive-segments/button-spec.js +21 -0
  38. package/lib/built/interactive-segments/index.d.ts +6 -0
  39. package/lib/built/interactive-segments/index.js +6 -0
  40. package/lib/built/interactive-segments/keyboard-segment.d.ts +10 -0
  41. package/lib/built/interactive-segments/keyboard-segment.js +11 -0
  42. package/lib/built/interactive-segments/onebot-keyboard.d.ts +6 -0
  43. package/lib/built/interactive-segments/onebot-keyboard.js +49 -0
  44. package/lib/built/interactive-segments/resolve.d.ts +14 -0
  45. package/lib/built/interactive-segments/resolve.js +109 -0
  46. package/lib/built/interactive-segments/types.d.ts +45 -0
  47. package/lib/built/interactive-segments/types.js +9 -0
  48. package/lib/built/login-assist.d.ts +43 -16
  49. package/lib/built/login-assist.js +113 -11
  50. package/lib/built/message-enrich.d.ts +32 -0
  51. package/lib/built/message-enrich.js +67 -0
  52. package/lib/built/outbound-media-utils.d.ts +9 -0
  53. package/lib/built/outbound-media-utils.js +62 -0
  54. package/lib/built/queue-im-field-contract.d.ts +7 -2
  55. package/lib/built/queue-im-field-contract.js +13 -4
  56. package/lib/built/rich-segments/markdown-to-text.d.ts +3 -0
  57. package/lib/built/rich-segments/markdown-to-text.js +27 -0
  58. package/lib/built/roles.d.ts +4 -5
  59. package/lib/built/roles.js +4 -5
  60. package/lib/built/segment-contract/assert.d.ts +7 -0
  61. package/lib/built/segment-contract/assert.js +39 -0
  62. package/lib/built/segment-contract/delivery.d.ts +5 -0
  63. package/lib/built/segment-contract/delivery.js +40 -0
  64. package/lib/built/segment-contract/image.d.ts +5 -0
  65. package/lib/built/segment-contract/image.js +10 -0
  66. package/lib/built/segment-contract/index.d.ts +10 -0
  67. package/lib/built/segment-contract/index.js +9 -0
  68. package/lib/built/segment-contract/json-schema.d.ts +28 -0
  69. package/lib/built/segment-contract/json-schema.js +128 -0
  70. package/lib/built/segment-contract/media.d.ts +12 -0
  71. package/lib/built/segment-contract/media.js +22 -0
  72. package/lib/built/segment-contract/mention.d.ts +10 -0
  73. package/lib/built/segment-contract/mention.js +26 -0
  74. package/lib/built/segment-contract/preview.d.ts +3 -0
  75. package/lib/built/segment-contract/preview.js +159 -0
  76. package/lib/built/segment-contract/text.d.ts +7 -0
  77. package/lib/built/segment-contract/text.js +34 -0
  78. package/lib/built/segment-contract/types.d.ts +58 -0
  79. package/lib/built/segment-contract/types.js +1 -0
  80. package/lib/built/segment-contract/validate.d.ts +229 -0
  81. package/lib/built/segment-contract/validate.js +172 -0
  82. package/lib/built/tool-access.d.ts +5 -0
  83. package/lib/built/tool-access.js +17 -0
  84. package/lib/built/user-interaction.d.ts +30 -0
  85. package/lib/built/user-interaction.js +244 -0
  86. package/lib/component.d.ts +0 -1
  87. package/lib/component.js +30 -14
  88. package/lib/errors.d.ts +2 -3
  89. package/lib/errors.js +4 -5
  90. package/lib/feature/adapter.d.ts +2 -0
  91. package/lib/feature/adapter.js +2 -0
  92. package/lib/feature/command.d.ts +2 -0
  93. package/lib/feature/command.js +2 -0
  94. package/lib/feature/component.d.ts +2 -0
  95. package/lib/feature/component.js +2 -0
  96. package/lib/feature/handler.d.ts +48 -0
  97. package/lib/feature/handler.js +26 -0
  98. package/lib/feature/middleware.d.ts +2 -0
  99. package/lib/feature/middleware.js +2 -0
  100. package/lib/im-scene.d.ts +29 -0
  101. package/lib/im-scene.js +75 -0
  102. package/lib/im-session-id.d.ts +39 -0
  103. package/lib/im-session-id.js +47 -0
  104. package/lib/index.d.ts +29 -36
  105. package/lib/index.js +27 -41
  106. package/lib/jsx-dev-runtime.d.ts +0 -1
  107. package/lib/jsx-dev-runtime.js +0 -1
  108. package/lib/jsx-runtime.d.ts +1 -1
  109. package/lib/jsx-runtime.js +0 -1
  110. package/lib/jsx.d.ts +19 -22
  111. package/lib/jsx.js +0 -1
  112. package/lib/message.d.ts +17 -12
  113. package/lib/message.js +16 -13
  114. package/lib/models/system-log.d.ts +0 -3
  115. package/lib/models/system-log.js +1 -9
  116. package/lib/models/user.d.ts +0 -3
  117. package/lib/models/user.js +1 -8
  118. package/lib/notice.d.ts +16 -60
  119. package/lib/notice.js +1 -4
  120. package/lib/plugin-runtime/im/contracts.d.ts +191 -0
  121. package/lib/plugin-runtime/im/contracts.js +169 -0
  122. package/lib/plugin-runtime/im/conversation-runtime.d.ts +19 -0
  123. package/lib/plugin-runtime/im/conversation-runtime.js +312 -0
  124. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +79 -0
  125. package/lib/plugin-runtime/im/endpoint-runtime.js +162 -0
  126. package/lib/plugin-runtime/im/im-runtime.d.ts +84 -0
  127. package/lib/plugin-runtime/im/im-runtime.js +201 -0
  128. package/lib/plugin-runtime/im/inbound-runtime.d.ts +31 -0
  129. package/lib/plugin-runtime/im/inbound-runtime.js +252 -0
  130. package/lib/plugin-runtime/im/index.d.ts +11 -0
  131. package/lib/plugin-runtime/im/index.js +9 -0
  132. package/lib/plugin-runtime/im/ingress-route.d.ts +10 -0
  133. package/lib/plugin-runtime/im/ingress-route.js +10 -0
  134. package/lib/plugin-runtime/im/interaction-runtime.d.ts +23 -0
  135. package/lib/plugin-runtime/im/interaction-runtime.js +181 -0
  136. package/lib/plugin-runtime/im/interactive-router.d.ts +17 -0
  137. package/lib/plugin-runtime/im/interactive-router.js +98 -0
  138. package/lib/plugin-runtime/im/login-assist-host.d.ts +6 -0
  139. package/lib/plugin-runtime/im/login-assist-host.js +6 -0
  140. package/lib/plugin-runtime/im/message-bus.d.ts +38 -0
  141. package/lib/plugin-runtime/im/message-bus.js +40 -0
  142. package/lib/plugin-runtime/im/message-dispatcher.d.ts +18 -0
  143. package/lib/plugin-runtime/im/message-dispatcher.js +107 -0
  144. package/lib/plugin-runtime/im/message-events.d.ts +26 -0
  145. package/lib/plugin-runtime/im/message-events.js +61 -0
  146. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +19 -0
  147. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +165 -0
  148. package/lib/plugin-runtime/im/outbound-renderer.d.ts +7 -0
  149. package/lib/plugin-runtime/im/outbound-renderer.js +70 -0
  150. package/lib/plugin-runtime/im/outbound-segments.d.ts +71 -0
  151. package/lib/plugin-runtime/im/outbound-segments.js +219 -0
  152. package/lib/plugin-runtime/im/public-api.d.ts +6 -0
  153. package/lib/plugin-runtime/im/public-api.js +6 -0
  154. package/lib/plugin-runtime/im/runtime-middleware.d.ts +3 -0
  155. package/lib/plugin-runtime/im/runtime-middleware.js +13 -0
  156. package/lib/request.d.ts +17 -62
  157. package/lib/request.js +0 -4
  158. package/lib/side-event/base.d.ts +51 -0
  159. package/lib/side-event/base.js +30 -0
  160. package/lib/side-event/dispatch.d.ts +15 -0
  161. package/lib/side-event/dispatch.js +140 -0
  162. package/lib/side-event/index.d.ts +4 -0
  163. package/lib/side-event/index.js +4 -0
  164. package/lib/side-event/normalize.d.ts +38 -0
  165. package/lib/side-event/normalize.js +111 -0
  166. package/lib/side-event/types.d.ts +23 -0
  167. package/lib/side-event/types.js +55 -0
  168. package/lib/system-event.d.ts +14 -0
  169. package/lib/system-event.js +7 -0
  170. package/lib/types.d.ts +35 -193
  171. package/lib/types.js +0 -1
  172. package/lib/utils.d.ts +81 -6
  173. package/lib/utils.js +54 -25
  174. package/package.json +94 -16
  175. package/lib/adapter.d.ts +0 -96
  176. package/lib/adapter.d.ts.map +0 -1
  177. package/lib/adapter.js +0 -217
  178. package/lib/adapter.js.map +0 -1
  179. package/lib/agent-prompt.d.ts +0 -37
  180. package/lib/agent-prompt.d.ts.map +0 -1
  181. package/lib/agent-prompt.js +0 -2
  182. package/lib/agent-prompt.js.map +0 -1
  183. package/lib/bot.d.ts +0 -38
  184. package/lib/bot.d.ts.map +0 -1
  185. package/lib/bot.js +0 -2
  186. package/lib/bot.js.map +0 -1
  187. package/lib/built/adapter-process.d.ts +0 -43
  188. package/lib/built/adapter-process.d.ts.map +0 -1
  189. package/lib/built/adapter-process.js +0 -81
  190. package/lib/built/adapter-process.js.map +0 -1
  191. package/lib/built/agent-preset.d.ts +0 -65
  192. package/lib/built/agent-preset.d.ts.map +0 -1
  193. package/lib/built/agent-preset.js +0 -80
  194. package/lib/built/agent-preset.js.map +0 -1
  195. package/lib/built/ai-trigger.d.ts.map +0 -1
  196. package/lib/built/ai-trigger.js.map +0 -1
  197. package/lib/built/command.d.ts +0 -68
  198. package/lib/built/command.d.ts.map +0 -1
  199. package/lib/built/command.js +0 -92
  200. package/lib/built/command.js.map +0 -1
  201. package/lib/built/common-adapter-tools.d.ts.map +0 -1
  202. package/lib/built/common-adapter-tools.js.map +0 -1
  203. package/lib/built/component.d.ts +0 -69
  204. package/lib/built/component.d.ts.map +0 -1
  205. package/lib/built/component.js +0 -99
  206. package/lib/built/component.js.map +0 -1
  207. package/lib/built/config.d.ts +0 -99
  208. package/lib/built/config.d.ts.map +0 -1
  209. package/lib/built/config.js +0 -355
  210. package/lib/built/config.js.map +0 -1
  211. package/lib/built/cron.d.ts +0 -75
  212. package/lib/built/cron.d.ts.map +0 -1
  213. package/lib/built/cron.js +0 -122
  214. package/lib/built/cron.js.map +0 -1
  215. package/lib/built/database.d.ts +0 -66
  216. package/lib/built/database.d.ts.map +0 -1
  217. package/lib/built/database.js +0 -100
  218. package/lib/built/database.js.map +0 -1
  219. package/lib/built/dispatcher.d.ts +0 -139
  220. package/lib/built/dispatcher.d.ts.map +0 -1
  221. package/lib/built/dispatcher.js +0 -361
  222. package/lib/built/dispatcher.js.map +0 -1
  223. package/lib/built/html-segment-fallback.d.ts.map +0 -1
  224. package/lib/built/html-segment-fallback.js.map +0 -1
  225. package/lib/built/html-to-text.d.ts.map +0 -1
  226. package/lib/built/html-to-text.js.map +0 -1
  227. package/lib/built/inbound-runner.d.ts +0 -23
  228. package/lib/built/inbound-runner.d.ts.map +0 -1
  229. package/lib/built/inbound-runner.js +0 -37
  230. package/lib/built/inbound-runner.js.map +0 -1
  231. package/lib/built/login-assist.d.ts.map +0 -1
  232. package/lib/built/login-assist.js.map +0 -1
  233. package/lib/built/mcp-mesh-registrar.d.ts +0 -9
  234. package/lib/built/mcp-mesh-registrar.d.ts.map +0 -1
  235. package/lib/built/mcp-mesh-registrar.js +0 -17
  236. package/lib/built/mcp-mesh-registrar.js.map +0 -1
  237. package/lib/built/message-filter.d.ts +0 -177
  238. package/lib/built/message-filter.d.ts.map +0 -1
  239. package/lib/built/message-filter.js +0 -241
  240. package/lib/built/message-filter.js.map +0 -1
  241. package/lib/built/permission.d.ts +0 -55
  242. package/lib/built/permission.d.ts.map +0 -1
  243. package/lib/built/permission.js +0 -112
  244. package/lib/built/permission.js.map +0 -1
  245. package/lib/built/prepend-quote-context.d.ts +0 -35
  246. package/lib/built/prepend-quote-context.d.ts.map +0 -1
  247. package/lib/built/prepend-quote-context.js +0 -131
  248. package/lib/built/prepend-quote-context.js.map +0 -1
  249. package/lib/built/queue-im-field-contract.d.ts.map +0 -1
  250. package/lib/built/queue-im-field-contract.js.map +0 -1
  251. package/lib/built/roles.d.ts.map +0 -1
  252. package/lib/built/roles.js.map +0 -1
  253. package/lib/built/runtime-io.d.ts +0 -10
  254. package/lib/built/runtime-io.d.ts.map +0 -1
  255. package/lib/built/runtime-io.js +0 -68
  256. package/lib/built/runtime-io.js.map +0 -1
  257. package/lib/built/schema-feature.d.ts +0 -78
  258. package/lib/built/schema-feature.d.ts.map +0 -1
  259. package/lib/built/schema-feature.js +0 -132
  260. package/lib/built/schema-feature.js.map +0 -1
  261. package/lib/built/skill.d.ts +0 -121
  262. package/lib/built/skill.d.ts.map +0 -1
  263. package/lib/built/skill.js +0 -152
  264. package/lib/built/skill.js.map +0 -1
  265. package/lib/built/tool.d.ts +0 -150
  266. package/lib/built/tool.d.ts.map +0 -1
  267. package/lib/built/tool.js +0 -383
  268. package/lib/built/tool.js.map +0 -1
  269. package/lib/command.d.ts +0 -42
  270. package/lib/command.d.ts.map +0 -1
  271. package/lib/command.js +0 -75
  272. package/lib/command.js.map +0 -1
  273. package/lib/component.d.ts.map +0 -1
  274. package/lib/component.js.map +0 -1
  275. package/lib/errors.d.ts.map +0 -1
  276. package/lib/errors.js.map +0 -1
  277. package/lib/index.d.ts.map +0 -1
  278. package/lib/index.js.map +0 -1
  279. package/lib/jsx-dev-runtime.d.ts.map +0 -1
  280. package/lib/jsx-dev-runtime.js.map +0 -1
  281. package/lib/jsx-runtime.d.ts.map +0 -1
  282. package/lib/jsx-runtime.js.map +0 -1
  283. package/lib/jsx.d.ts.map +0 -1
  284. package/lib/jsx.js.map +0 -1
  285. package/lib/message-quote.d.ts +0 -11
  286. package/lib/message-quote.d.ts.map +0 -1
  287. package/lib/message-quote.js +0 -91
  288. package/lib/message-quote.js.map +0 -1
  289. package/lib/message.d.ts.map +0 -1
  290. package/lib/message.js.map +0 -1
  291. package/lib/models/system-log.d.ts.map +0 -1
  292. package/lib/models/system-log.js.map +0 -1
  293. package/lib/models/user.d.ts.map +0 -1
  294. package/lib/models/user.js.map +0 -1
  295. package/lib/notice.d.ts.map +0 -1
  296. package/lib/notice.js.map +0 -1
  297. package/lib/plugin.d.ts +0 -258
  298. package/lib/plugin.d.ts.map +0 -1
  299. package/lib/plugin.js +0 -688
  300. package/lib/plugin.js.map +0 -1
  301. package/lib/prompt.d.ts +0 -118
  302. package/lib/prompt.d.ts.map +0 -1
  303. package/lib/prompt.js +0 -244
  304. package/lib/prompt.js.map +0 -1
  305. package/lib/request.d.ts.map +0 -1
  306. package/lib/request.js.map +0 -1
  307. package/lib/scheduler/scheduler.d.ts +0 -49
  308. package/lib/scheduler/scheduler.d.ts.map +0 -1
  309. package/lib/scheduler/scheduler.js +0 -352
  310. package/lib/scheduler/scheduler.js.map +0 -1
  311. package/lib/scheduler/types.d.ts +0 -71
  312. package/lib/scheduler/types.d.ts.map +0 -1
  313. package/lib/scheduler/types.js +0 -8
  314. package/lib/scheduler/types.js.map +0 -1
  315. package/lib/tool-zod.d.ts +0 -28
  316. package/lib/tool-zod.d.ts.map +0 -1
  317. package/lib/tool-zod.js +0 -98
  318. package/lib/tool-zod.js.map +0 -1
  319. package/lib/types-generator.d.ts +0 -6
  320. package/lib/types-generator.d.ts.map +0 -1
  321. package/lib/types-generator.js +0 -72
  322. package/lib/types-generator.js.map +0 -1
  323. package/lib/types.d.ts.map +0 -1
  324. package/lib/types.js.map +0 -1
  325. package/lib/utils.d.ts.map +0 -1
  326. package/lib/utils.js.map +0 -1
@@ -0,0 +1,22 @@
1
+ import { isMediaRef } from './validate.js';
2
+ export { isMediaRef };
3
+ /** 入站段携带媒体引用的段类型(纯文本视图无法承载的信息)。 */
4
+ const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
5
+ /**
6
+ * 从入站 canonical 段收集媒体引用(image / audio / video / file)。
7
+ * 只认 canonical `data.media`;无媒体段时返回空数组(调用方无需特判 undefined)。
8
+ */
9
+ export function collectSegmentMedia(segments) {
10
+ if (!segments?.length)
11
+ return [];
12
+ const out = [];
13
+ for (const segment of segments) {
14
+ if (!segment || typeof segment.type !== 'string' || !MEDIA_SEGMENT_TYPES.has(segment.type)) {
15
+ continue;
16
+ }
17
+ const media = segment.data?.media;
18
+ if (isMediaRef(media))
19
+ out.push({ type: segment.type, media });
20
+ }
21
+ return out;
22
+ }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Canonical mention field readers (SSOT).
3
+ */
4
+ export declare function readMentionTarget(data: Record<string, unknown> | undefined): string;
5
+ export declare function readMentionName(data: Record<string, unknown> | undefined): string | undefined;
6
+ /** Resolve @ target from at / mention segment. */
7
+ export declare function readMentionSegmentTarget(seg: {
8
+ type: unknown;
9
+ data?: unknown;
10
+ }): string;
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Canonical mention field readers (SSOT).
3
+ */
4
+ export function readMentionTarget(data) {
5
+ if (!data)
6
+ return '';
7
+ const raw = data.target ?? data.user_id ?? data.qq ?? data.id;
8
+ if (raw === 'all')
9
+ return 'all';
10
+ return raw != null ? String(raw) : '';
11
+ }
12
+ export function readMentionName(data) {
13
+ if (!data)
14
+ return undefined;
15
+ const name = data.name ?? data.nickname ?? data.username;
16
+ return typeof name === 'string' && name.trim() ? name.trim() : undefined;
17
+ }
18
+ function isRecord(value) {
19
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
20
+ }
21
+ /** Resolve @ target from at / mention segment. */
22
+ export function readMentionSegmentTarget(seg) {
23
+ if (seg.type !== 'at' && seg.type !== 'mention')
24
+ return '';
25
+ return readMentionTarget(isRecord(seg.data) ? seg.data : undefined);
26
+ }
@@ -0,0 +1,3 @@
1
+ import type { SegmentBase } from './types.js';
2
+ /** Single canonical segment → compact human-readable preview for logs. */
3
+ export declare function formatSegmentPreview(item: SegmentBase): string;
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Canonical Segment[] log / debug preview (SSOT).
3
+ * @see docs/architecture/segment-content-model.md
4
+ */
5
+ import { htmlToFallbackText } from '../html-to-text.js';
6
+ import { readMentionName, readMentionTarget } from './mention.js';
7
+ import { isMediaRef } from './validate.js';
8
+ const PREVIEW_MAX = 80;
9
+ function clip(text, max = PREVIEW_MAX) {
10
+ const normalized = text.trim();
11
+ if (normalized.length <= max)
12
+ return normalized;
13
+ return `${normalized.slice(0, max)}…`;
14
+ }
15
+ function previewMedia(data) {
16
+ const media = isMediaRef(data.media) ? data.media : undefined;
17
+ if (!media)
18
+ return undefined;
19
+ if (media.kind === 'base64') {
20
+ const mime = media.mime_type ?? 'data';
21
+ return `base64:${mime}[${media.value.length}]`;
22
+ }
23
+ if (media.kind === 'path') {
24
+ const base = media.value.split(/[/\\]/).pop() ?? media.value;
25
+ return clip(base, 48);
26
+ }
27
+ return clip(media.value, 60);
28
+ }
29
+ function previewMediaSegment(type, data) {
30
+ const media = previewMedia(data);
31
+ const alt = typeof data.alt === 'string'
32
+ ? data.alt
33
+ : typeof data.name === 'string'
34
+ ? data.name
35
+ : undefined;
36
+ if (media && alt)
37
+ return `[${type}:${media} alt=${clip(alt, 24)}]`;
38
+ if (media)
39
+ return `[${type}:${media}]`;
40
+ return `[${type}]`;
41
+ }
42
+ /** Single canonical segment → compact human-readable preview for logs. */
43
+ export function formatSegmentPreview(item) {
44
+ const { type } = item;
45
+ const data = item.data ?? {};
46
+ switch (type) {
47
+ case 'text':
48
+ return typeof data.text === 'string' ? data.text : '';
49
+ case 'mention': {
50
+ const target = readMentionTarget(data);
51
+ if (target === 'all')
52
+ return '@all';
53
+ const name = readMentionName(data);
54
+ if (name)
55
+ return `@${name}`;
56
+ return `@${target}`;
57
+ }
58
+ case 'at': {
59
+ const target = readMentionTarget(data);
60
+ const name = readMentionName(data);
61
+ if (name)
62
+ return `@${name}`;
63
+ return `@${target}`;
64
+ }
65
+ case 'image':
66
+ case 'video':
67
+ case 'audio':
68
+ case 'voice':
69
+ case 'record':
70
+ case 'file':
71
+ return previewMediaSegment(type, data);
72
+ case 'face': {
73
+ const id = data.id ?? data.face_id;
74
+ const name = typeof data.name === 'string'
75
+ ? data.name
76
+ : typeof data.text === 'string'
77
+ ? data.text
78
+ : undefined;
79
+ if (id != null && name)
80
+ return `[face:${id} ${name}]`;
81
+ if (id != null)
82
+ return `[face:${id}]`;
83
+ if (name)
84
+ return `{face}(${name})`;
85
+ return '[face]';
86
+ }
87
+ case 'reply': {
88
+ const id = data.message_id ?? data.id;
89
+ return id ? `↩${id}` : '[reply]';
90
+ }
91
+ case 'forward': {
92
+ const id = data.forward_id ?? data.id;
93
+ const title = typeof data.title === 'string' ? data.title : undefined;
94
+ const count = Array.isArray(data.messages) ? data.messages.length : 0;
95
+ let out = `[forward${id ? `:${id}` : ''}`;
96
+ if (title)
97
+ out += ` ${clip(title, 32)}`;
98
+ if (count > 0)
99
+ out += ` ×${count}`;
100
+ return `${out}]`;
101
+ }
102
+ case 'link': {
103
+ const url = typeof data.url === 'string' ? data.url : '';
104
+ const text = typeof data.text === 'string' ? data.text : '';
105
+ if (text && url)
106
+ return clip(`${text} <${url}>`);
107
+ return clip(url || text || '[link]');
108
+ }
109
+ case 'dice':
110
+ return data.result != null ? `{dice}(${data.result})` : '{dice}';
111
+ case 'rps':
112
+ return data.result != null ? `{rps}(${data.result})` : '{rps}';
113
+ case 'html': {
114
+ if (typeof data.text === 'string' && data.text)
115
+ return clip(data.text);
116
+ if (typeof data.html === 'string') {
117
+ const stripped = htmlToFallbackText(data.html);
118
+ return stripped ? clip(`[html] ${stripped}`) : '[html]';
119
+ }
120
+ return '[html]';
121
+ }
122
+ case 'qrcode': {
123
+ const text = typeof data.text === 'string' ? data.text : '';
124
+ return text ? clip(`[qrcode] ${text}`) : '[qrcode]';
125
+ }
126
+ case 'markdown': {
127
+ const text = typeof data.content === 'string'
128
+ ? data.content
129
+ : typeof data.text === 'string'
130
+ ? data.text
131
+ : '';
132
+ return text ? clip(`[markdown] ${text}`) : '[markdown]';
133
+ }
134
+ case 'tts': {
135
+ const text = typeof data.text === 'string' ? data.text : '';
136
+ return text ? clip(`[tts] ${text}`) : '[tts]';
137
+ }
138
+ case 'keyboard': {
139
+ const rows = Array.isArray(data.rows)
140
+ ? data.rows.length
141
+ : Array.isArray(data.buttons)
142
+ ? data.buttons.length
143
+ : 0;
144
+ return rows > 0 ? `[keyboard:${rows}]` : '[keyboard]';
145
+ }
146
+ case 'thinking': {
147
+ const text = typeof data.text === 'string' ? data.text : '';
148
+ return text ? clip(`[thinking] ${text}`, 60) : '[thinking]';
149
+ }
150
+ case 'tool_call': {
151
+ const name = typeof data.name === 'string' ? data.name : 'tool';
152
+ return `[tool:${name}]`;
153
+ }
154
+ default:
155
+ if (typeof data.text === 'string' && data.text)
156
+ return `{${type}}(${clip(data.text)})`;
157
+ return `{${type}}`;
158
+ }
159
+ }
@@ -0,0 +1,7 @@
1
+ import type { Segment } from './types.js';
2
+ /**
3
+ * 提取纯文本视图:text 段原文拼接,mention/at 段渲染为 `@name`(无名回退
4
+ * `@target`,`all` → `@all`);其余段类型不产生文本(媒体 / 回复等结构化
5
+ * 信息经 `segments` 轨道消费,不污染命令输入)。
6
+ */
7
+ export declare function segmentsToPlainText(segments: readonly Segment[]): string;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Canonical Segment[] → 纯文本视图(SSOT)。
3
+ * 入站双轨:结构化段为唯一内部契约,纯文本视图供命令匹配 / AI 兜底消费。
4
+ * @see docs/architecture/segment-content-model.md
5
+ */
6
+ import { readMentionName, readMentionTarget } from './mention.js';
7
+ /**
8
+ * 提取纯文本视图:text 段原文拼接,mention/at 段渲染为 `@name`(无名回退
9
+ * `@target`,`all` → `@all`);其余段类型不产生文本(媒体 / 回复等结构化
10
+ * 信息经 `segments` 轨道消费,不污染命令输入)。
11
+ */
12
+ export function segmentsToPlainText(segments) {
13
+ let out = '';
14
+ for (const segment of segments) {
15
+ // Segment 含 SegmentBase 兜底成员,type 窄化不能联动窄化 data,统一按字典读
16
+ const data = segment.data;
17
+ if (segment.type === 'text') {
18
+ if (typeof data.text === 'string')
19
+ out += data.text;
20
+ continue;
21
+ }
22
+ if (segment.type === 'mention' || segment.type === 'at') {
23
+ const name = readMentionName(data);
24
+ if (name) {
25
+ out += `@${name}`;
26
+ continue;
27
+ }
28
+ const target = readMentionTarget(data);
29
+ if (target)
30
+ out += `@${target}`;
31
+ }
32
+ }
33
+ return out;
34
+ }
@@ -0,0 +1,58 @@
1
+ /** Canonical Segment SSOT lives in @zhin.js/im-contract. */
2
+ import type { MediaRef, SegmentBase } from '@zhin.js/im-contract';
3
+ export type { ForwardSegment, MediaRef, MentionSegment, ReplySegment, Segment, SegmentBase, TextSegment, } from '@zhin.js/im-contract';
4
+ /**
5
+ * 媒体引用占位(全框架唯一媒体表达)。
6
+ * kind=file:平台侧不透明文件引用(如 Telegram file_id、Milky resource_id),
7
+ * 非 URL/本地路径,消费方需经平台 API 解析。
8
+ */
9
+ export interface ImageSegment extends SegmentBase {
10
+ type: 'image';
11
+ data: {
12
+ media: MediaRef;
13
+ alt?: string;
14
+ };
15
+ }
16
+ export interface AudioSegment extends SegmentBase {
17
+ type: 'audio';
18
+ data: {
19
+ media: MediaRef;
20
+ duration?: number;
21
+ };
22
+ }
23
+ export interface VideoSegment extends SegmentBase {
24
+ type: 'video';
25
+ data: {
26
+ media: MediaRef;
27
+ duration?: number;
28
+ alt?: string;
29
+ };
30
+ }
31
+ export interface FileSegment extends SegmentBase {
32
+ type: 'file';
33
+ data: {
34
+ media: MediaRef;
35
+ name?: string;
36
+ };
37
+ }
38
+ export interface FaceSegment extends SegmentBase {
39
+ type: 'face';
40
+ data: {
41
+ id: string | number;
42
+ name?: string;
43
+ };
44
+ }
45
+ export interface DiceSegment extends SegmentBase {
46
+ type: 'dice';
47
+ data: {
48
+ result?: number;
49
+ };
50
+ }
51
+ export interface RpsSegment extends SegmentBase {
52
+ type: 'rps';
53
+ data: {
54
+ result?: number;
55
+ };
56
+ }
57
+ /** 规范态 segment(严格校验 text / mention / image / audio / video / file / reply / forward / face / dice / rps) */
58
+ export type LegacySpecificSegment = ImageSegment | AudioSegment | VideoSegment | FileSegment | FaceSegment | DiceSegment | RpsSegment;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,229 @@
1
+ import { Schema } from '@zhin.js/schema';
2
+ import type { Segment } from './types.js';
3
+ export { isMediaRef } from '@zhin.js/im-contract';
4
+ export declare const mediaRefSchema: Schema<{
5
+ kind?: any;
6
+ value?: string | undefined;
7
+ mime_type?: string | undefined;
8
+ file_name?: string | undefined;
9
+ size?: number | undefined;
10
+ }, {
11
+ kind?: any;
12
+ value?: string | undefined;
13
+ mime_type?: string | undefined;
14
+ file_name?: string | undefined;
15
+ size?: number | undefined;
16
+ }>;
17
+ export declare const textSegmentSchema: Schema<{
18
+ type?: "text" | undefined;
19
+ data?: {
20
+ text?: string | undefined;
21
+ } | undefined;
22
+ platform?: Record<string, any> | undefined;
23
+ }, {
24
+ type?: "text" | undefined;
25
+ data?: {
26
+ text?: string | undefined;
27
+ } | undefined;
28
+ platform?: Record<string, any> | undefined;
29
+ }>;
30
+ export declare const mentionSegmentSchema: Schema<{
31
+ type?: "mention" | undefined;
32
+ data?: {
33
+ target?: string | undefined;
34
+ name?: string | undefined;
35
+ } | undefined;
36
+ platform?: Record<string, any> | undefined;
37
+ }, {
38
+ type?: "mention" | undefined;
39
+ data?: {
40
+ target?: string | undefined;
41
+ name?: string | undefined;
42
+ } | undefined;
43
+ platform?: Record<string, any> | undefined;
44
+ }>;
45
+ export declare const imageSegmentSchema: Schema<{
46
+ type?: "image" | undefined;
47
+ data?: {
48
+ media?: {
49
+ kind?: any;
50
+ value?: string | undefined;
51
+ mime_type?: string | undefined;
52
+ file_name?: string | undefined;
53
+ size?: number | undefined;
54
+ } | undefined;
55
+ alt?: string | undefined;
56
+ } | undefined;
57
+ platform?: Record<string, any> | undefined;
58
+ }, {
59
+ type?: "image" | undefined;
60
+ data?: {
61
+ media?: {
62
+ kind?: any;
63
+ value?: string | undefined;
64
+ mime_type?: string | undefined;
65
+ file_name?: string | undefined;
66
+ size?: number | undefined;
67
+ } | undefined;
68
+ alt?: string | undefined;
69
+ } | undefined;
70
+ platform?: Record<string, any> | undefined;
71
+ }>;
72
+ export declare const audioSegmentSchema: Schema<{
73
+ type?: "audio" | undefined;
74
+ data?: {
75
+ media?: {
76
+ kind?: any;
77
+ value?: string | undefined;
78
+ mime_type?: string | undefined;
79
+ file_name?: string | undefined;
80
+ size?: number | undefined;
81
+ } | undefined;
82
+ duration?: number | undefined;
83
+ } | undefined;
84
+ platform?: Record<string, any> | undefined;
85
+ }, {
86
+ type?: "audio" | undefined;
87
+ data?: {
88
+ media?: {
89
+ kind?: any;
90
+ value?: string | undefined;
91
+ mime_type?: string | undefined;
92
+ file_name?: string | undefined;
93
+ size?: number | undefined;
94
+ } | undefined;
95
+ duration?: number | undefined;
96
+ } | undefined;
97
+ platform?: Record<string, any> | undefined;
98
+ }>;
99
+ export declare const videoSegmentSchema: Schema<{
100
+ type?: "video" | undefined;
101
+ data?: {
102
+ media?: {
103
+ kind?: any;
104
+ value?: string | undefined;
105
+ mime_type?: string | undefined;
106
+ file_name?: string | undefined;
107
+ size?: number | undefined;
108
+ } | undefined;
109
+ duration?: number | undefined;
110
+ alt?: string | undefined;
111
+ } | undefined;
112
+ platform?: Record<string, any> | undefined;
113
+ }, {
114
+ type?: "video" | undefined;
115
+ data?: {
116
+ media?: {
117
+ kind?: any;
118
+ value?: string | undefined;
119
+ mime_type?: string | undefined;
120
+ file_name?: string | undefined;
121
+ size?: number | undefined;
122
+ } | undefined;
123
+ duration?: number | undefined;
124
+ alt?: string | undefined;
125
+ } | undefined;
126
+ platform?: Record<string, any> | undefined;
127
+ }>;
128
+ export declare const fileSegmentSchema: Schema<{
129
+ type?: "file" | undefined;
130
+ data?: {
131
+ media?: {
132
+ kind?: any;
133
+ value?: string | undefined;
134
+ mime_type?: string | undefined;
135
+ file_name?: string | undefined;
136
+ size?: number | undefined;
137
+ } | undefined;
138
+ name?: string | undefined;
139
+ } | undefined;
140
+ platform?: Record<string, any> | undefined;
141
+ }, {
142
+ type?: "file" | undefined;
143
+ data?: {
144
+ media?: {
145
+ kind?: any;
146
+ value?: string | undefined;
147
+ mime_type?: string | undefined;
148
+ file_name?: string | undefined;
149
+ size?: number | undefined;
150
+ } | undefined;
151
+ name?: string | undefined;
152
+ } | undefined;
153
+ platform?: Record<string, any> | undefined;
154
+ }>;
155
+ export declare const replySegmentSchema: Schema<{
156
+ type?: "reply" | undefined;
157
+ data?: {
158
+ message_id?: string | undefined;
159
+ } | undefined;
160
+ platform?: Record<string, any> | undefined;
161
+ }, {
162
+ type?: "reply" | undefined;
163
+ data?: {
164
+ message_id?: string | undefined;
165
+ } | undefined;
166
+ platform?: Record<string, any> | undefined;
167
+ }>;
168
+ export declare const forwardSegmentSchema: Schema<{
169
+ type?: "forward" | undefined;
170
+ data?: {
171
+ forward_id?: string | undefined;
172
+ title?: string | undefined;
173
+ messages?: any[][] | undefined;
174
+ } | undefined;
175
+ platform?: Record<string, any> | undefined;
176
+ }, {
177
+ type?: "forward" | undefined;
178
+ data?: {
179
+ forward_id?: string | undefined;
180
+ title?: string | undefined;
181
+ messages?: any[][] | undefined;
182
+ } | undefined;
183
+ platform?: Record<string, any> | undefined;
184
+ }>;
185
+ export declare const faceSegmentSchema: Schema<{
186
+ type?: "face" | undefined;
187
+ data?: {
188
+ id?: any;
189
+ name?: string | undefined;
190
+ } | undefined;
191
+ platform?: Record<string, any> | undefined;
192
+ }, {
193
+ type?: "face" | undefined;
194
+ data?: {
195
+ id?: any;
196
+ name?: string | undefined;
197
+ } | undefined;
198
+ platform?: Record<string, any> | undefined;
199
+ }>;
200
+ export declare const diceSegmentSchema: Schema<{
201
+ type?: "dice" | undefined;
202
+ data?: {
203
+ result?: number | undefined;
204
+ } | undefined;
205
+ platform?: Record<string, any> | undefined;
206
+ }, {
207
+ type?: "dice" | undefined;
208
+ data?: {
209
+ result?: number | undefined;
210
+ } | undefined;
211
+ platform?: Record<string, any> | undefined;
212
+ }>;
213
+ export declare const rpsSegmentSchema: Schema<{
214
+ type?: "rps" | undefined;
215
+ data?: {
216
+ result?: number | undefined;
217
+ } | undefined;
218
+ platform?: Record<string, any> | undefined;
219
+ }, {
220
+ type?: "rps" | undefined;
221
+ data?: {
222
+ result?: number | undefined;
223
+ } | undefined;
224
+ platform?: Record<string, any> | undefined;
225
+ }>;
226
+ export declare const canonicalSegmentSchema: Schema<any, any>;
227
+ export declare const segmentArraySchema: Schema<any[], any[]>;
228
+ /** 严格 canonical 段校验(@zhin.js/schema validate-only) */
229
+ export declare function isStrictCanonicalSegment(value: unknown): value is Segment;