@zhin.js/core 1.9.0 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/lib/built/interaction-messages.d.ts +1 -1
  2. package/lib/built/interactive-segments/resolve.js +12 -0
  3. package/lib/built/interactive-segments/types.d.ts +6 -0
  4. package/lib/built/roles.d.ts +33 -6
  5. package/lib/built/roles.js +27 -15
  6. package/lib/built/segment-contract/json-schema.js +1 -0
  7. package/lib/built/user-interaction.js +3 -0
  8. package/lib/plugin-runtime/im/ambient-switch.d.ts +49 -0
  9. package/lib/plugin-runtime/im/ambient-switch.js +70 -0
  10. package/lib/plugin-runtime/im/contracts.d.ts +58 -0
  11. package/lib/plugin-runtime/im/contracts.js +21 -1
  12. package/lib/plugin-runtime/im/conversation-runtime.js +12 -2
  13. package/lib/plugin-runtime/im/host/database-console-sql.js +1 -1
  14. package/lib/plugin-runtime/im/im-runtime.d.ts +9 -1
  15. package/lib/plugin-runtime/im/im-runtime.js +10 -0
  16. package/lib/plugin-runtime/im/inbound-outcome-ledger.d.ts +117 -0
  17. package/lib/plugin-runtime/im/inbound-outcome-ledger.js +329 -0
  18. package/lib/plugin-runtime/im/inbound-runtime.d.ts +6 -1
  19. package/lib/plugin-runtime/im/inbound-runtime.js +268 -21
  20. package/lib/plugin-runtime/im/inbound-spine.d.ts +20 -3
  21. package/lib/plugin-runtime/im/inbound-spine.js +107 -7
  22. package/lib/plugin-runtime/im/index.d.ts +5 -1
  23. package/lib/plugin-runtime/im/index.js +3 -0
  24. package/lib/plugin-runtime/im/interaction-runtime.d.ts +8 -0
  25. package/lib/plugin-runtime/im/interaction-runtime.js +45 -14
  26. package/lib/plugin-runtime/im/message-diagnostics.d.ts +16 -0
  27. package/lib/plugin-runtime/im/message-diagnostics.js +12 -0
  28. package/lib/plugin-runtime/im/message-dispatcher.d.ts +6 -0
  29. package/lib/plugin-runtime/im/message-dispatcher.js +6 -1
  30. package/lib/plugin-runtime/im/message-outcome.d.ts +97 -0
  31. package/lib/plugin-runtime/im/message-outcome.js +125 -0
  32. package/lib/plugin-runtime/im/outbound-segments.js +1 -1
  33. package/package.json +15 -15
@@ -0,0 +1,125 @@
1
+ /** Outcome codes (ADR 0061 §1.1–§1.6). Snake case, append-only. @public */
2
+ export const MESSAGE_OUTCOMES = Object.freeze([
3
+ // §1.1 replied
4
+ 'replied', 'command_replied', 'handler_replied', 'interaction_answered', 'suggested', 'refused',
5
+ // §1.2 not executed, explained in chat
6
+ 'invalid_input', 'permission_denied', 'rate_limited', 'approval_denied', 'approval_timeout', 'approval_unavailable',
7
+ 'tool_failed_reported', 'model_timeout', 'model_error', 'budget_exhausted',
8
+ // §1.3 no reply by design
9
+ 'not_addressed', 'feature_disabled', 'ambient_silent', 'model_silent', 'merged', 'superseded', 'cleared',
10
+ 'interaction_consumed',
11
+ // §1.4 filtered by policy
12
+ 'filtered_by_policy', 'media_rejected',
13
+ // §1.5 replay only
14
+ 'ignored_self', 'ignored_bot', 'dropped_duplicate', 'dropped_unready', 'dropped_dedup_error', 'dropped_retired',
15
+ // §1.6 failures
16
+ 'delivery_failed', 'internal_error', 'unrecorded',
17
+ ]);
18
+ /** Where an outcome was decided (ADR 0061 §2 `stage`). @public */
19
+ export const MESSAGE_OUTCOME_STAGES = Object.freeze([
20
+ 'ingress', 'interaction', 'middleware', 'handlers', 'command', 'suggestion', 'agent_gate', 'ambient',
21
+ 'admission', 'model', 'tool', 'delivery',
22
+ ]);
23
+ const TIER = Object.freeze({
24
+ internal_error: 9,
25
+ delivery_failed: 8,
26
+ model_timeout: 7, model_error: 7, budget_exhausted: 7,
27
+ approval_denied: 6, approval_timeout: 6, approval_unavailable: 6,
28
+ tool_failed_reported: 5,
29
+ refused: 4, permission_denied: 4, rate_limited: 4, invalid_input: 4, filtered_by_policy: 4,
30
+ replied: 3, command_replied: 3, handler_replied: 3, interaction_answered: 3, suggested: 3,
31
+ not_addressed: 2, feature_disabled: 2, ambient_silent: 2, model_silent: 2, merged: 2, superseded: 2, cleared: 2,
32
+ interaction_consumed: 2, media_rejected: 2, ignored_self: 2, ignored_bot: 2, dropped_duplicate: 2,
33
+ dropped_unready: 2, dropped_dedup_error: 2, dropped_retired: 2,
34
+ unrecorded: 0,
35
+ });
36
+ /** Priority rank (higher wins). `internal_error` > `delivery_failed` > model > approval > tool > refusals > replies > silent > `unrecorded`. @public */
37
+ export function messageOutcomePriority(outcome) {
38
+ return TIER[outcome] ?? 0;
39
+ }
40
+ /** Outcomes with no chat reply that are sampled per conversation (ADR 0061 §2). @public */
41
+ export const QUIET_MESSAGE_OUTCOMES = new Set([
42
+ 'not_addressed', 'ignored_bot', 'ignored_self', 'dropped_duplicate',
43
+ ]);
44
+ const REPLY = Object.freeze({ 9: 'throttled', 8: 'throttled' });
45
+ const NO_REPLY = new Set([
46
+ 'not_addressed', 'feature_disabled', 'ambient_silent', 'model_silent', 'merged', 'superseded', 'interaction_consumed',
47
+ 'filtered_by_policy', 'media_rejected', 'ignored_self', 'ignored_bot', 'dropped_duplicate', 'dropped_unready',
48
+ 'dropped_dedup_error', 'dropped_retired',
49
+ ]);
50
+ const REPLAY_ONLY = new Set([
51
+ 'ignored_self', 'ignored_bot', 'dropped_duplicate', 'dropped_unready', 'dropped_dedup_error', 'dropped_retired',
52
+ ]);
53
+ const ADMIN_ONLY = new Set(['feature_disabled', 'unrecorded']);
54
+ /** Default visibility of a code (ADR 0061 §1 tables); callers may narrow it per reason. @public */
55
+ export function defaultOutcomeVisibility(outcome, addressed = false) {
56
+ if (REPLAY_ONLY.has(outcome)) {
57
+ // §1.5: a sender who addressed the bot during a restart / outage is told to send again.
58
+ return addressed && (outcome === 'dropped_unready' || outcome === 'dropped_dedup_error' || outcome === 'dropped_retired')
59
+ ? 'sender' : 'replay';
60
+ }
61
+ return ADMIN_ONLY.has(outcome) ? 'admin' : 'sender';
62
+ }
63
+ /** Default `reply` of a code (ADR 0061 §1 tables). @public */
64
+ export function defaultOutcomeReply(outcome) {
65
+ if (outcome === 'unrecorded')
66
+ return 'no';
67
+ return REPLY[TIER[outcome]] ?? (NO_REPLY.has(outcome) ? 'no' : 'yes');
68
+ }
69
+ const tpl = (senderZh, senderEn, adminZh, adminEn) => Object.freeze({ sender: Object.freeze({ 'zh-CN': senderZh, en: senderEn }), admin: Object.freeze({ 'zh-CN': adminZh, en: adminEn }) });
70
+ /** Placeholders a template may use; each maps to a record field. @public */
71
+ export const MESSAGE_OUTCOME_PLACEHOLDERS = Object.freeze(['command', 'owner', 'reason', 'stage', 'turnId', 'errorId', 'mergedInto', 'detail']);
72
+ /** @public */
73
+ export const MESSAGE_OUTCOME_TEMPLATES = Object.freeze({
74
+ replied: tpl('已回复。', 'Replied.', '由 Agent 回复,回合 {turnId}。', 'Replied by the agent, turn {turnId}.'),
75
+ command_replied: tpl('已执行指令 {command}。', 'Ran command {command}.', '指令 {command}(插件 {owner})。', 'Command {command} (plugin {owner}).'),
76
+ handler_replied: tpl('已由插件处理。', 'Handled by a plugin.', '由插件 {owner} 的 {stage} 回复。', 'Replied by {owner} ({stage}).'),
77
+ interaction_answered: tpl('已作为对等待中提问的回答。', 'Taken as your answer to a pending question.', '提问方 {owner}。', 'Prompt by {owner}.'),
78
+ suggested: tpl('没有这条指令,已提示相近的指令。', 'No such command; suggested a close one.', '近似匹配提示,来自 {owner}。', 'Near-match suggestion from {owner}.'),
79
+ refused: tpl('插件拒绝了这次请求。', 'The plugin declined.', 'UserFacingError 来自 {owner}({stage})。', 'UserFacingError from {owner} ({stage}).'),
80
+ invalid_input: tpl('指令参数不对,已回复用法。', 'Wrong arguments; usage was sent.', '指令 {command} 参数校验失败。', 'Command {command} failed validation.'),
81
+ permission_denied: tpl('你没有权限执行这条指令。', 'You are not allowed to run this command.', '指令 {command} 缺少权限({reason})。', 'Command {command} denied ({reason}).'),
82
+ rate_limited: tpl('太频繁或正忙,这次没有处理,请稍后再试。', 'Too frequent or busy; not processed this time.', '限流:{reason}。', 'Limited: {reason}.'),
83
+ approval_denied: tpl('需要确认的操作被拒绝了,没有执行。', 'The action needing approval was declined and did not run.', '审批被拒绝:{detail}。', 'Approval declined: {detail}.'),
84
+ approval_timeout: tpl('等确认超时了,操作没有执行。', 'Approval timed out; the action did not run.', '审批超时:{detail}。', 'Approval timed out: {detail}.'),
85
+ approval_unavailable: tpl('这个操作需要有人确认,但现在没有可确认的渠道,没有执行。', 'This action needs approval but no one can approve it here; it did not run.', '无审批通道({reason})。', 'No approval channel ({reason}).'),
86
+ tool_failed_reported: tpl('有一步操作失败了,回复里已说明。', 'A step failed; the reply says so.', '工具失败:{detail}。', 'Tool failed: {detail}.'),
87
+ model_timeout: tpl('模型服务没有响应,这次没回上,请稍后再试。', 'The model did not respond; please try again later.', '模型超时({reason})。', 'Model timed out ({reason}).'),
88
+ model_error: tpl('模型服务出错了,这次没回上,请稍后再试。', 'The model service failed; please try again later.', '模型失败({reason})。', 'Model failed ({reason}).'),
89
+ budget_exhausted: tpl('这件事步骤太多,做到一半停下了。', 'Too many steps; stopped partway.', '超出预算 {reason}。', 'Budget {reason} exceeded.'),
90
+ not_addressed: tpl('这条消息没有 @ 我,也不是指令,本群我只在被 @ 时回复。', 'You did not mention me and it is not a command; here I only answer when mentioned.', '未点名、未匹配指令,本群不插话({reason})。', 'Not addressed, no command, no interjection here ({reason}).'),
91
+ feature_disabled: tpl('这里没有开启相关功能。', 'That feature is not enabled here.', '功能在此处关闭({reason})。', 'Feature disabled here ({reason}).'),
92
+ ambient_silent: tpl('我判断这句不需要我插话。', 'I decided not to chime in.', '旁听判定不插话({reason})。', 'Ambient judge declined ({reason}).'),
93
+ model_silent: tpl('我看了,但这次决定不回复。', 'I read it but chose not to reply.', '回合 {turnId} 完成但没有输出。', 'Turn {turnId} completed with no output.'),
94
+ merged: tpl('和你前后几句合在一起回复了。', 'Answered together with your other messages.', '合入回合 {mergedInto}。', 'Merged into turn {mergedInto}.'),
95
+ superseded: tpl('你很快又发了新消息,按新消息处理了。', 'You sent a newer message; that one was handled instead.', '被新消息顶替({reason})。', 'Superseded ({reason}).'),
96
+ cleared: tpl('已清空上下文。', 'Context cleared.', '已清空上下文。', 'Context cleared.'),
97
+ interaction_consumed: tpl('刚才在等一个提问的回答,这句被当成了回答。', 'I was waiting for an answer to a question and took this as it.', '被等待中的提问吃掉,提问方 {owner}({reason})。', 'Captured by a pending prompt of {owner} ({reason}).'),
98
+ filtered_by_policy: tpl('机器人在这里暂停回复或无法发言。', 'The bot is paused or cannot speak here.', '被策略过滤({reason})。', 'Filtered by policy ({reason}).'),
99
+ media_rejected: tpl('你发的媒体我读不了,只看了文字部分。', 'I could not read your media; only the text was used.', '媒体被拒({reason})。', 'Media rejected ({reason}).'),
100
+ ignored_self: tpl('机器人自己发出的消息回显。', 'Echo of the bot\'s own message.', '机器人自己发出的消息回显。', 'Echo of the bot\'s own message.'),
101
+ ignored_bot: tpl('来自其他机器人,只记录。', 'From another bot; recorded only.', '来自其他机器人({reason}),只记录。', 'From another bot ({reason}); recorded only.'),
102
+ dropped_duplicate: tpl('同一条消息已由另一个端点处理。', 'Already handled by another endpoint.', '同一条消息已由另一个端点处理。', 'Already handled by another endpoint.'),
103
+ dropped_unready: tpl('机器人刚才在重启或暂时不可用,请再发一次。', 'The bot was restarting or unavailable; please send it again.', '场地成员尚未上报自身 ID,消息未处理:{detail}。', 'Venue members not ready: {detail}.'),
104
+ dropped_dedup_error: tpl('机器人刚才暂时不可用,请再发一次。', 'The bot was briefly unavailable; please send it again.', '去重存储出错,按失败关闭丢弃:{detail}。', 'Dedup store failed closed: {detail}.'),
105
+ dropped_retired: tpl('机器人刚才在重启,请再发一次。', 'The bot was restarting; please send it again.', '实例正在重载 / 关闭,消息未被接纳。', 'Instance reloading or stopping.'),
106
+ delivery_failed: tpl('回复已经生成,但发到平台时失败了。', 'The reply was ready but the platform rejected it.', '发送失败({reason})。', 'Delivery failed ({reason}).'),
107
+ internal_error: tpl('处理时出错了,已记录(错误号 {errorId})。', 'Something went wrong; logged as {errorId}.', '{stage} 抛出异常({reason}),插件 {owner}:{detail}', '{stage} threw ({reason}), plugin {owner}: {detail}'),
108
+ unrecorded: tpl('这条消息的处理结果没有记录下来。', 'No outcome was recorded.', '没有结局记录,最后阶段 {stage};这是框架缺陷,请报告。', 'No outcome recorded, last stage {stage}; a framework bug.'),
109
+ });
110
+ /**
111
+ * Renders the human-readable reason of a record for one audience. Missing placeholders read as
112
+ * `—`; `detail` and `errorId` are only filled for the `admin` audience with `includeDetail`.
113
+ * @public
114
+ */
115
+ export function formatMessageOutcome(record, options) {
116
+ const template = MESSAGE_OUTCOME_TEMPLATES[record.outcome] ?? MESSAGE_OUTCOME_TEMPLATES.unrecorded;
117
+ const locale = options.locale === 'en' ? 'en' : 'zh-CN';
118
+ const text = template[options.audience][locale];
119
+ return text.replace(/\{(\w+)\}/gu, (_match, name) => {
120
+ if ((name === 'detail' || name === 'errorId') && options.audience === 'admin' && !options.includeDetail)
121
+ return '—';
122
+ const value = name === 'stage' ? record.lastStage ?? record.stage : record[name];
123
+ return typeof value === 'string' && value ? value : '—';
124
+ });
125
+ }
@@ -169,7 +169,7 @@ export function applyOutboundInteractivePolicy(payload, policy, remember) {
169
169
  const data = item.data;
170
170
  const remembered = remember?.(effectiveKeyboardFallbackMap(data));
171
171
  const map = remembered && typeof remembered === 'object' && !Array.isArray(remembered) ? remembered : undefined;
172
- const projected = map ? { ...data, fallback: { hint: data.fallback?.hint ?? '', map } } : data;
172
+ const projected = map ? { ...data, fallback: { ...data.fallback, hint: data.fallback?.hint ?? '', map } } : data;
173
173
  return { type: 'text', data: { text: renderKeyboardAsText(projected, map) } };
174
174
  });
175
175
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/core",
3
- "version": "1.9.0",
3
+ "version": "1.11.0",
4
4
  "description": "Zhin机器人核心框架",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -52,21 +52,21 @@
52
52
  ],
53
53
  "dependencies": {
54
54
  "qrcode": "^1.5.4",
55
- "@zhin.js/adapter": "1.3.1",
56
- "@zhin.js/command": "1.3.0",
57
- "@zhin.js/database": "1.2.1",
58
- "@zhin.js/handler": "1.1.18",
59
- "@zhin.js/component": "1.1.19",
60
- "@zhin.js/im-contract": "1.2.0",
61
- "@zhin.js/kernel": "1.1.7",
62
- "@zhin.js/logger": "1.2.0",
63
- "@zhin.js/middleware": "1.1.19",
64
- "@zhin.js/permission": "1.2.2",
65
- "@zhin.js/plugin-runtime": "1.3.0",
66
- "@zhin.js/schedule-feature": "1.1.18",
55
+ "@zhin.js/adapter": "1.3.3",
56
+ "@zhin.js/command": "1.4.0",
57
+ "@zhin.js/component": "1.2.0",
58
+ "@zhin.js/database": "1.2.2",
59
+ "@zhin.js/handler": "1.1.20",
60
+ "@zhin.js/im-contract": "1.3.0",
61
+ "@zhin.js/kernel": "1.3.0",
62
+ "@zhin.js/logger": "1.3.0",
63
+ "@zhin.js/middleware": "1.1.20",
64
+ "@zhin.js/permission": "1.2.3",
65
+ "@zhin.js/plugin-runtime": "1.4.0",
66
+ "@zhin.js/schedule-feature": "1.1.19",
67
67
  "@zhin.js/schema": "1.1.7",
68
- "@zhin.js/jsx": "1.1.14",
69
- "@zhin.js/feature-kit": "1.1.18"
68
+ "@zhin.js/jsx": "1.1.15",
69
+ "@zhin.js/feature-kit": "1.1.19"
70
70
  },
71
71
  "devDependencies": {
72
72
  "@types/node": "^26.1.2",