@yuriai/web 0.2.27-beta.6 → 0.2.27-beta.8
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.
- package/README.md +8 -0
- package/dist/assets/{AgentAvatar-Bi1vvWPC.js → AgentAvatar-BJ42lGZD.js} +1 -1
- package/dist/assets/AssistantContactStatus-dtkObamV.js +3 -0
- package/dist/assets/{AssistantUnreadBadge-DdJyySwn.js → AssistantUnreadBadge-QwhBfXpC.js} +1 -1
- package/dist/assets/AssistantView-D7ryIKL0.js +1 -0
- package/dist/assets/{DiagramView-CI4bTtxy.js → DiagramView-ERrGEBDp.js} +1 -1
- package/dist/assets/{FadeInOnReveal-BB4qEnAn.js → FadeInOnReveal-Bu2GvaM9.js} +1 -1
- package/dist/assets/{GuiPluginSurface-CguxFUbM.js → GuiPluginSurface-MzQgEZNr.js} +1 -1
- package/dist/assets/{GuiPluginWindow-DOJ7wuRH.js → GuiPluginWindow-DZMmlQzx.js} +1 -1
- package/dist/assets/{Icon-t2xvbAyN.js → Icon-Dj4CCqCP.js} +1 -1
- package/dist/assets/{ImageLoadingPlaceholder-D1L13TK0.js → ImageLoadingPlaceholder-BnFXgUuO.js} +1 -1
- package/dist/assets/{LoadingImage-5rY_edNm.js → LoadingImage-PBnivDKv.js} +1 -1
- package/dist/assets/{MarkdownRenderer-BlGxjOei.js → MarkdownRenderer-BajF4gUU.js} +2 -2
- package/dist/assets/{MarkdownRendererImpl-cE-0AYRg.js → MarkdownRendererImpl-CfyXL4rg.js} +1 -1
- package/dist/assets/{MarkstreamRendererImpl-BZyqDl82.js → MarkstreamRendererImpl-BGadklK1.js} +1 -1
- package/dist/assets/{MobileDetailNavigation-tbfsMfB-.js → MobileDetailNavigation-DqajQdB4.js} +1 -1
- package/dist/assets/{MobileResizableSheet-BeRmT6_x.js → MobileResizableSheet-BvdUgwA3.js} +1 -1
- package/dist/assets/{MobileShareBridge-C3Equ3P_.js → MobileShareBridge-3oPoYnry.js} +2 -2
- package/dist/assets/{MobileTabPageHeader-DQRqAAEf.js → MobileTabPageHeader-B6cRyIRH.js} +1 -1
- package/dist/assets/{MultiRunWindow-CAM2XPII.js → MultiRunWindow-yhs0Ih5_.js} +1 -1
- package/dist/assets/{OnboardingScreen-4ftRerP5.js → OnboardingScreen-Bi1VWFQC.js} +1 -1
- package/dist/assets/{OverlayScrollbar-CF0PCvQz.js → OverlayScrollbar-BBDwGvGO.js} +1 -1
- package/dist/assets/{SettingsView-2tk4WH7R.js → SettingsView-BSf-SJUA.js} +15 -15
- package/dist/assets/{SettingsWindow-B9zbeJaW.js → SettingsWindow-BvSXVMTm.js} +1 -1
- package/dist/assets/{TerminalView-DfxvTHye.js → TerminalView-DhL01N7e.js} +1 -1
- package/dist/assets/{ToolOutputDialog-CrjDIhru.js → ToolOutputDialog-C8lnH4Ky.js} +1 -1
- package/dist/assets/{YuriLogo-QvS1ZEHi.js → YuriLogo-D8asj1CS.js} +1 -1
- package/dist/assets/{appThemeRegistry-Bb_DtiV9.js → appThemeRegistry-C-maYSdv.js} +1 -1
- package/dist/assets/{assistant-attachment-cache-B9iHLlm2.js → assistant-attachment-cache-B_qRvy-k.js} +1 -1
- package/dist/assets/{button-DinGM3tu.js → button-vXOdzd8x.js} +1 -1
- package/dist/assets/{capgoAdapter-DufzjXRs.js → capgoAdapter-DJ_h2x5D.js} +1 -1
- package/dist/assets/{collapsible-Bh1GLNYV.js → collapsible-DwDQs3Wa.js} +1 -1
- package/dist/assets/context-menu-BabBujQ-.js +1 -0
- package/dist/assets/{desktopRelayRestore-CoLLVJw8.js → desktopRelayRestore-D1UX7HW2.js} +1 -1
- package/dist/assets/{diagram-BmG-7Jb4.js → diagram-HwgrQxY5.js} +1 -1
- package/dist/assets/{dialog-BXssfGXA.js → dialog-Dnf626tb.js} +1 -1
- package/dist/assets/dropdown-menu.styles-CBc_a-Nv.js +1 -0
- package/dist/assets/{es-HP_Ise0X.js → es-BQkO-Odr.js} +1 -1
- package/dist/assets/feishu-Ct1ZxlzQ.svg +6 -0
- package/dist/assets/{fileMentionTouchSelection-DSl0tj2r.js → fileMentionTouchSelection-CKPnEetl.js} +1 -1
- package/dist/assets/{fileQueries-5a1jkme2.js → fileQueries-BeXkd3o6.js} +1 -1
- package/dist/assets/{fileReferenceActions-CGpBSFq4.js → fileReferenceActions-g7KZLi_G.js} +1 -1
- package/dist/assets/{fr-D0kJXJ6U.js → fr-C852roK5.js} +1 -1
- package/dist/assets/{gitApi-Wo0IZow9.js → gitApi-CVq5oKCd.js} +1 -1
- package/dist/assets/{gitApiHttp-De9liKnG.js → gitApiHttp-BYOIbYIh.js} +2 -2
- package/dist/assets/{gui-9enrif_1.js → gui-M_Rbwkyu.js} +1 -1
- package/dist/assets/host-BW3FEJdU.js +1 -0
- package/dist/assets/{image-loading-Dq1g_wpm.js → image-loading-D5UhMj7Z.js} +1 -1
- package/dist/assets/{input-v8-rVbo-.js → input-BtM712b1.js} +1 -1
- package/dist/assets/{insertionBoundaries-CZz7TWJv.js → insertionBoundaries-Dx3WAY6i.js} +1 -1
- package/dist/assets/{ja-BjHKXazE.js → ja-BqC39qK6.js} +1 -1
- package/dist/assets/{ko-Llwnl876.js → ko-BMaChAWh.js} +1 -1
- package/dist/assets/main-9uP2z1qT.js +2 -0
- package/dist/assets/main-Mey7bCWf.js +169 -0
- package/dist/assets/{markdownHeightCache-BVV2dktw.js → markdownHeightCache-Bf8iisO4.js} +1 -1
- package/dist/assets/{mcpQueries-BoBrB4a4.js → mcpQueries-DpXqegX5.js} +1 -1
- package/dist/assets/miniChat-DqZvVkme.js +2 -0
- package/dist/assets/mobile-DXAWjYcN.js +2 -0
- package/dist/assets/{mobileBackNavigation-DMSzAvb6.js → mobileBackNavigation-DZcI7aZg.js} +1 -1
- package/dist/assets/{multirun-BhWttsRQ.js → multirun-hzspPepd.js} +1 -1
- package/dist/assets/{native-DSvNnKAm.js → native-H7K64Ulc.js} +1 -1
- package/dist/assets/{native-config-DjdrW_9n.js → native-config-CddZtLQ1.js} +1 -1
- package/dist/assets/{persistence-CfrHIiIS.js → persistence-BT8045Ue.js} +1 -1
- package/dist/assets/{pl-BOd_idqn.js → pl-Ubs8p28T.js} +1 -1
- package/dist/assets/projectMeta-CEf0QPmD.js +1 -0
- package/dist/assets/{pt-BR-B8djxMsl.js → pt-BR-8rAOjJrs.js} +1 -1
- package/dist/assets/{queryRuntime-Dkpnq3Z1.js → queryRuntime-CTcigFdj.js} +1 -1
- package/dist/assets/react-DRe85o5s.js +1 -0
- package/dist/assets/readiness-Dyr7314z.js +1 -0
- package/dist/assets/{renderElectronMiniChatApp-N2r999Bf.js → renderElectronMiniChatApp-DoOq8Cuo.js} +2 -2
- package/dist/assets/{renderMobileApp-CU1ec6Ak.js → renderMobileApp-TTxtOb8b.js} +7 -7
- package/dist/assets/runtime-fetch-D0YWp3FJ.js +1 -0
- package/dist/assets/{runtime-file-download-CcNIVp7u.js → runtime-file-download-Cf1WxfeW.js} +1 -1
- package/dist/assets/{runtime-file-resource-6np6lzoV.js → runtime-file-resource-UJjHUF2C.js} +1 -1
- package/dist/assets/runtimeConfig-B8VHHNxj.js +2 -0
- package/dist/assets/runtimeEndpointReset-BC6XWntz.js +149 -0
- package/dist/assets/scheduledTaskNavigation-Zm87Nydi.js +1 -0
- package/dist/assets/sessionLookup-De53jDwM.js +1 -0
- package/dist/assets/{sortable-tabs-strip-yKyqsqut.js → sortable-tabs-strip-D4pVoodN.js} +1 -1
- package/dist/assets/speechSettingsQueries-RlCLMBtr.js +4 -0
- package/dist/assets/src-lE4uqaHS.css +2 -0
- package/dist/assets/{store-CUBymvAC.js → store-ME7oHni1.js} +2 -2
- package/dist/assets/{terminalApi-BblSkqch.js → terminalApi-BSaclMDJ.js} +1 -1
- package/dist/assets/{textarea-B39OCNPV.js → textarea-B98rsLs7.js} +1 -1
- package/dist/assets/{tooltip-d8TNN4lx.js → tooltip-B9810jbK.js} +1 -1
- package/dist/assets/{types-BqFQhQTt.js → types-DFf9vd1b.js} +1 -1
- package/dist/assets/{uk-BNd7CjVO.js → uk-LzwzUApL.js} +1 -1
- package/dist/assets/{useAppFontEffects-BVoVpJYO.js → useAppFontEffects-D2C1sBYM.js} +43 -43
- package/dist/assets/{useAssistantUIStore-Bp6TxG5E.js → useAssistantUIStore-TUN_ycy5.js} +1 -1
- package/dist/assets/{useDesktopWindowControlsLayout-CYx1LNO5.js → useDesktopWindowControlsLayout-BjKaHN0x.js} +1 -1
- package/dist/assets/{useEffectiveDirectory-D8FFE5Yn.js → useEffectiveDirectory-TEvyiQSC.js} +1 -1
- package/dist/assets/{useFontPreferences-BFyBjtQ6.js → useFontPreferences-BlhlCJCX.js} +1 -1
- package/dist/assets/{useMobileNavigationStore-BHMFeMjo.js → useMobileNavigationStore-DTvJV9s-.js} +6 -6
- package/dist/assets/useUIStore-DRx6OgCp.js +1 -0
- package/dist/assets/{useWorkerHighlightedLines-CPxG8Fya.js → useWorkerHighlightedLines-D093jNsH.js} +1 -1
- package/dist/assets/vendor-opencode-client-ZeOZ4Efz.js +23 -0
- package/dist/assets/{vendor-opencode-plugin-CgKz9Hcy.js → vendor-opencode-plugin-BBOP6WNx.js} +1 -1
- package/dist/assets/{vendor-solid-js-0T254UHG.js → vendor-solid-js-9wmPZH9g.js} +1 -1
- package/dist/assets/{zh-CN-BkTAEOZG.js → zh-CN-D-FVCeks.js} +1 -1
- package/dist/assets/{zh-TW-x8SfMzfc.js → zh-TW-B9iH_NXL.js} +1 -1
- package/dist/index.html +17 -17
- package/dist/mini-chat.html +17 -17
- package/dist/mobile.html +17 -17
- package/package.json +6 -1
- package/server/lib/assistants/DOCUMENTATION.md +13 -1
- package/server/lib/assistants/channels/DOCUMENTATION.md +291 -0
- package/server/lib/assistants/channels/PROTOCOLS.md +228 -0
- package/server/lib/assistants/channels/dingtalk-chat-adapter.js +633 -0
- package/server/lib/assistants/channels/dingtalk-chat-adapter.test.js +415 -0
- package/server/lib/assistants/channels/integration.test.js +44 -0
- package/server/lib/assistants/channels/routes.js +47 -0
- package/server/lib/assistants/channels/routes.test.js +105 -0
- package/server/lib/assistants/channels/runtime.js +867 -0
- package/server/lib/assistants/channels/runtime.test.js +723 -0
- package/server/lib/assistants/channels/sdk-adapters.js +371 -0
- package/server/lib/assistants/channels/sdk-adapters.test.js +367 -0
- package/server/lib/assistants/channels/store.js +246 -0
- package/server/lib/assistants/channels/store.test.js +286 -0
- package/server/lib/assistants/channels/transport.js +41 -0
- package/server/lib/assistants/channels/transport.test.js +23 -0
- package/server/lib/assistants/channels/wecom-chat-adapter.js +689 -0
- package/server/lib/assistants/channels/wecom-chat-adapter.test.js +109 -0
- package/server/lib/assistants/message-channel-origin.js +7 -0
- package/server/lib/assistants/routes.js +14 -1
- package/server/lib/assistants/weixin/DOCUMENTATION.md +89 -7
- package/server/lib/assistants/weixin/api.js +2 -0
- package/server/lib/assistants/weixin/chat-adapter.js +107 -0
- package/server/lib/assistants/weixin/chat-adapter.test.js +62 -0
- package/server/lib/assistants/weixin/inbound.js +147 -0
- package/server/lib/assistants/weixin/inbound.test.js +121 -0
- package/server/lib/assistants/weixin/media.js +79 -0
- package/server/lib/assistants/weixin/media.test.js +66 -0
- package/server/lib/assistants/weixin/runtime.js +89 -67
- package/server/lib/assistants/weixin/runtime.test.js +156 -4
- package/server/lib/assistants/weixin/store.js +8 -4
- package/server/lib/assistants/weixin/store.test.js +72 -0
- package/server/lib/assistants/weixin/toon.js +49 -0
- package/server/lib/assistants/weixin/toon.test.js +25 -0
- package/server/lib/github/DOCUMENTATION.md +9 -8
- package/server/lib/llm/bridge-plugin.bundle.js +188 -188
- package/server/lib/opencode/DOCUMENTATION.md +1 -1
- package/dist/assets/AssistantContactStatus-CWq-PDz6.js +0 -3
- package/dist/assets/AssistantView-Br1iETTs.js +0 -1
- package/dist/assets/context-menu-DpbkRkk1.js +0 -1
- package/dist/assets/host-FR_grJxM.js +0 -1
- package/dist/assets/main-Bp9HHqTr.js +0 -2
- package/dist/assets/main-DOwAfmxJ.js +0 -169
- package/dist/assets/miniChat-BJDgCrfF.js +0 -2
- package/dist/assets/mobile-GM9931J_.js +0 -2
- package/dist/assets/projectMeta-31PobC-M.js +0 -1
- package/dist/assets/react-B9v0P7kT.js +0 -1
- package/dist/assets/readiness-CYNnsekT.js +0 -1
- package/dist/assets/runtime-fetch-D4ja813o.js +0 -1
- package/dist/assets/runtimeConfig-Db7yfo6L.js +0 -2
- package/dist/assets/runtimeEndpointReset-DO5WVetV.js +0 -149
- package/dist/assets/scheduledTaskNavigation-Bsrhv3Ow.js +0 -1
- package/dist/assets/sessionLookup-DRVy7LM1.js +0 -1
- package/dist/assets/speechSettingsQueries-DU25rmGc.js +0 -4
- package/dist/assets/src-Bckdo2XS.css +0 -2
- package/dist/assets/useUIStore-BbYD420L.js +0 -1
- package/dist/assets/vendor-opencode-client-UL_TecvQ.js +0 -12
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# Enterprise message channels
|
|
2
|
+
|
|
3
|
+
Host-owned long-connection channel framework for enterprise platforms. It connects
|
|
4
|
+
one platform account to one existing Yuri Bot and reuses the Bot's normal contact
|
|
5
|
+
pipeline, tools and permissions. WeCom, Feishu and DingTalk wire behavior lives in
|
|
6
|
+
injected Chat SDK bridges (`sdk-adapters.js` and `dingtalk-chat-adapter.js`);
|
|
7
|
+
`runtime.js` and `store.js` own durable
|
|
8
|
+
storage, authorization, lifecycle and delivery semantics.
|
|
9
|
+
|
|
10
|
+
No public webhook, OAuth callback or platform protocol route is exposed here.
|
|
11
|
+
The shared runtime never constructs platform payloads, signs requests, refreshes
|
|
12
|
+
tokens or decides how a platform acknowledges a message. Those belong to the
|
|
13
|
+
adapter seam so a shared SDK can replace adapter internals without changing this
|
|
14
|
+
module.
|
|
15
|
+
|
|
16
|
+
## Chat adapter boundary
|
|
17
|
+
|
|
18
|
+
Platform implementations are supplied by the Host from a shared Chat SDK bridge.
|
|
19
|
+
Each `adapters[provider]` consumes a Chat SDK adapter internally;
|
|
20
|
+
the bridge is responsible for its dependency, protocol framing and reconnect
|
|
21
|
+
plumbing. This framework only sees `connect`/`send` and never imports the SDK,
|
|
22
|
+
registers SDK routes, or adds per-platform tables, queues or clocks.
|
|
23
|
+
|
|
24
|
+
Feishu reuses its existing Chat Adapter; WeCom and DingTalk implement the Chat SDK
|
|
25
|
+
Adapter interface over their official connection SDKs. The WeChat Bot
|
|
26
|
+
Adapter lives in `../weixin/chat-adapter.js` and is consumed by its existing
|
|
27
|
+
personal-channel runtime. Its QR authorization, typing, media behavior and private
|
|
28
|
+
database remain there. No second Chat state, lock or history engine is started.
|
|
29
|
+
SDK versions, ACK/ready evidence and platform limitations live in `PROTOCOLS.md`.
|
|
30
|
+
|
|
31
|
+
The seam is deliberately narrow so an SDK upgrade changes only the bridge:
|
|
32
|
+
|
|
33
|
+
- the framework owns Bot ownership, optional sender authorization, durable dedup,
|
|
34
|
+
bounded queues, transcript generation, lease and lifecycle;
|
|
35
|
+
- the adapter owns wire authentication, heartbeats, receipts, platform payloads
|
|
36
|
+
and target validation;
|
|
37
|
+
- both share one `{ connect, send }` contract and one `onMessage` receipt promise.
|
|
38
|
+
|
|
39
|
+
## Module map
|
|
40
|
+
|
|
41
|
+
- `store.js`: private SQLite binding, durable inbound receipts, ordered outbound
|
|
42
|
+
deliveries, routing targets and the process-owner lease.
|
|
43
|
+
- `runtime.js`: enablement policy, connect lifecycle, optional sender restriction,
|
|
44
|
+
bounded metadata projection, output reconciliation, dedup, retry/ambiguity and
|
|
45
|
+
shutdown.
|
|
46
|
+
- `routes.js`: authenticated settings/mutation routes behind the Host gate.
|
|
47
|
+
- `sdk-adapters.js`: vendor Chat Adapter bridges and provider registry.
|
|
48
|
+
- `dingtalk-chat-adapter.js`: Chat Adapter extension using the official Stream SDK.
|
|
49
|
+
- `wecom-chat-adapter.js`: Chat Adapter extension using the official WeCom SDK,
|
|
50
|
+
including platform-acknowledged sends rather than fire-and-forget writes.
|
|
51
|
+
- `transport.js`: bounded HTTP helpers for adapter-owned platform API calls;
|
|
52
|
+
platform sockets and protocol framing remain SDK-owned.
|
|
53
|
+
- `../weixin/toon.js`: reused JSON-only TOON encoder. Channel metadata does not
|
|
54
|
+
copy or fork it.
|
|
55
|
+
|
|
56
|
+
`service.channelPage()` is the internal bounded, ascending public-output seam. It
|
|
57
|
+
validates the Bot, uses the contact-store generation and returns only assistant
|
|
58
|
+
rows. It does not expose credentials or replace the contact execution engine.
|
|
59
|
+
|
|
60
|
+
## Runtime API
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
createAssistantChannelsRuntime({
|
|
64
|
+
directory, service, adapters, refreshAllowedRoots, env, clock, intervalMs,
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `status(assistantID, provider)` — sync read; validates the Bot first.
|
|
69
|
+
- `save(assistantID, provider, input)` — save configuration and connect.
|
|
70
|
+
- `transfer(assistantID, provider, input)` — explicitly move a local binding using
|
|
71
|
+
`{ sourceAssistantID, revision }`, without returning or re-entering its secret.
|
|
72
|
+
- `retry(assistantID, provider)` — explicit reconnect only.
|
|
73
|
+
- `disconnect(assistantID, provider)` — delete local configuration and queues.
|
|
74
|
+
- `forget(assistantID)` — delete every provider for a deleted Bot.
|
|
75
|
+
- `onTurnEvent(event)` — receipt completion from contact turn events.
|
|
76
|
+
- `close()` — drain channel work, release the lease and close SQLite.
|
|
77
|
+
|
|
78
|
+
`registerAssistantChannelRoutes(app, runtime)` registers:
|
|
79
|
+
|
|
80
|
+
| Method | Path | Behavior |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| GET | `/api/yuri/assistants/:assistantID/channels/:provider` | status |
|
|
83
|
+
| PUT | same | save + connect |
|
|
84
|
+
| POST | same `/retry` | reconnect without resending unknown output |
|
|
85
|
+
| POST | same `/transfer` | confirmed local rebind with source revision check |
|
|
86
|
+
| DELETE | same | disconnect |
|
|
87
|
+
|
|
88
|
+
Save input is `{ clientID, clientSecret?, ownerID?, language? }`. An omitted or empty
|
|
89
|
+
`ownerID` uses the platform's access scope without an additional Yuri sender filter;
|
|
90
|
+
a non-empty value restricts the channel to that private sender. The first save
|
|
91
|
+
requires `clientSecret`; an update with the same `clientID` and an empty or omitted
|
|
92
|
+
secret keeps the stored one. A new `clientID` requires a new secret.
|
|
93
|
+
Responses are `Cache-Control: no-store` and contain only safe error codes — no
|
|
94
|
+
upstream bodies, secrets or routing targets.
|
|
95
|
+
|
|
96
|
+
Status shape:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"provider": "wecom",
|
|
101
|
+
"status": "disabled|disconnected|connecting|connected|reconnecting|error",
|
|
102
|
+
"error": null,
|
|
103
|
+
"configured": true,
|
|
104
|
+
"clientID": "…",
|
|
105
|
+
"ownerID": "…",
|
|
106
|
+
"hasSecret": true,
|
|
107
|
+
"transport": "websocket"
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`clientID`, `ownerID` and `hasSecret` appear only when configured. The secret
|
|
112
|
+
itself never appears in any DTO, error, transcript, model context or log.
|
|
113
|
+
Unconfigured Bots may also receive `transferSources`: safe source Bot IDs, names,
|
|
114
|
+
client IDs and binding revisions for this provider. The UI uses the same move
|
|
115
|
+
button, warning and confirmation text as WeChat. It offers matching accounts
|
|
116
|
+
instead of telling users to manually unlink the other Bot first.
|
|
117
|
+
|
|
118
|
+
Transfer drains and stops the source lane under source/destination mutation locks,
|
|
119
|
+
then atomically moves credentials and rotates the epoch. It starts at the target
|
|
120
|
+
Bot's current transcript tip, preserves receipt IDs against replay, and discards
|
|
121
|
+
the old Bot's pending input and queued replies. Chat history and already-started
|
|
122
|
+
tasks are not moved or cancelled. Stale revisions, an occupied destination or
|
|
123
|
+
failed writes preserve the original binding and resume its receiver. Other
|
|
124
|
+
providers/accounts are untouched. The host lease still prevents taking a binding
|
|
125
|
+
from another process; this operation only moves a binding in this Host's store.
|
|
126
|
+
|
|
127
|
+
## Enablement policy
|
|
128
|
+
|
|
129
|
+
Before opening storage or creating a timer, the runtime resolves policy from its
|
|
130
|
+
environment. `NODE_ENV=development` or `YURI_ELECTRON_DEV=1/true` disables channels
|
|
131
|
+
by default. Only an explicit `YURI_CHANNELS_ENABLED=1/true` opts in; `0/false` or
|
|
132
|
+
an unrecognized non-empty value disables them in every environment. Production
|
|
133
|
+
defaults remain enabled.
|
|
134
|
+
|
|
135
|
+
A disabled runtime does not open/create SQLite, acquire a lease, poll, send or
|
|
136
|
+
mutate bindings. Status returns `disabled`; save, retry and disconnect fail with
|
|
137
|
+
`channel_disabled` (403). `forget` and `close` are no-ops, so development cannot
|
|
138
|
+
erase production channel credentials or delete their bindings.
|
|
139
|
+
|
|
140
|
+
## Adapter contract
|
|
141
|
+
|
|
142
|
+
Adapters are injected by provider key and must implement exactly:
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
{
|
|
146
|
+
connect({ config, signal, onReady, onMessage, onError }): Promise<void>,
|
|
147
|
+
send({ config, target, text, id, signal }): Promise<void>,
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- `config` is `{ clientID, clientSecret, ownerID, language }`.
|
|
152
|
+
- `connect` resolves or rejects only when that connection ends. It calls
|
|
153
|
+
`onReady()` after authentication and `onError(error)` for asynchronous transport
|
|
154
|
+
failures. Errors carry a safe `code`; `ambiguous` marks an indeterminate send.
|
|
155
|
+
The framework sends only while the latest connection reported `onReady`; a
|
|
156
|
+
transport error or connection end immediately closes that output lane.
|
|
157
|
+
- `onMessage(message)` must return a Promise that the adapter awaits before
|
|
158
|
+
acknowledging the platform. It persists a durable receipt; it does not wait for
|
|
159
|
+
model execution. A missing or overlong stable `id` is never admitted.
|
|
160
|
+
- Inbound shape:
|
|
161
|
+
`{ id, senderID, chatType: 'private'|'group', text, metadata?, target? }`.
|
|
162
|
+
- `send` receives the current config, the private `target` snapshot and a stable
|
|
163
|
+
delivery `id`. The adapter re-validates `target`; the framework never follows a
|
|
164
|
+
user-controlled URL. An abort after submission must reject with `ambiguous: true`
|
|
165
|
+
so the row becomes `unknown` instead of being retried.
|
|
166
|
+
- Adapters must honor `signal`; shutdown and disconnect abort platform I/O.
|
|
167
|
+
|
|
168
|
+
## Authorization and persistence
|
|
169
|
+
|
|
170
|
+
Only platform-delivered `private` messages with a valid sender identity may execute
|
|
171
|
+
tools. A saved non-empty `ownerID` adds an exact sender restriction. With an empty
|
|
172
|
+
ID, administrators must control access through the platform's Bot/application
|
|
173
|
+
availability and permissions. Group messages and messages without a valid sender
|
|
174
|
+
or stable platform ID are ignored. Receiving a message never saves an owner binding.
|
|
175
|
+
All allowed users share this Bot's existing context; this is not per-user isolation.
|
|
176
|
+
|
|
177
|
+
Account IDs, owner IDs and secrets are never truncated. An overlong value is a
|
|
178
|
+
`validation_error`; a changed `clientID` must supply its own secret rather than
|
|
179
|
+
silently reusing the previous account's credential. Changing the owner or account
|
|
180
|
+
starts the new binding at the current transcript tip, so replies produced while
|
|
181
|
+
the previous owner was disconnected are never leaked to the new destination. A
|
|
182
|
+
same-identity save keeps the existing watermark and durable receipts.
|
|
183
|
+
|
|
184
|
+
Bindings live under `<yuriDataDir>/channels/channel.sqlite`. The directory is 0700
|
|
185
|
+
and the database 0600, with SQLite secure-delete enabled. Secrets are **not
|
|
186
|
+
encrypted at rest**; the host OS user must protect the data directory and backups
|
|
187
|
+
(on Windows, OS ACLs remain necessary). The same `provider + clientID` maps to at
|
|
188
|
+
most one Bot in the data directory; a second Bot receives `account_in_use` (409).
|
|
189
|
+
Different enterprise accounts can bind different Bots, including multiple accounts
|
|
190
|
+
of the same provider. The personal-WeChat single-entry/rebind restriction belongs
|
|
191
|
+
only to `../weixin/` and never limits these enterprise bindings.
|
|
192
|
+
|
|
193
|
+
`target` is platform routing metadata (for example a reply handle or session
|
|
194
|
+
webhook). It is persisted only in this private database and per outbox row. It is
|
|
195
|
+
never added to model context, transcript text or HTTP DTOs. The framework replies
|
|
196
|
+
to the configured owner destination, or, without a binding, to the latest accepted
|
|
197
|
+
private sender. The runtime derives `target.userID` from the authenticated platform
|
|
198
|
+
sender, overriding any supplied routing field; queued output keeps its destination
|
|
199
|
+
snapshot. There is no push destination before the first accepted private message,
|
|
200
|
+
and earlier public output is not backfilled when a recipient first appears.
|
|
201
|
+
|
|
202
|
+
Inbound `metadata` is projected before storage: credential-shaped keys, media/file
|
|
203
|
+
references, URLs and raw event envelopes are dropped or replaced, nesting and
|
|
204
|
+
total size are bounded, and the result is encoded as TOON in an ordinary text part
|
|
205
|
+
labelled external content. This is a conservative projection, not proof that a
|
|
206
|
+
linked article or media body was read. Text is capped at 20,000 characters.
|
|
207
|
+
Internal `platform` and `chatType` labels are omitted from content metadata.
|
|
208
|
+
Ordinary text with only these labels remains one original text part, with no
|
|
209
|
+
TOON appendix; actual media/transcription descriptors retain their content hints.
|
|
210
|
+
|
|
211
|
+
## Shared three-provider state
|
|
212
|
+
|
|
213
|
+
One `channel` row exists per `(assistantID, provider)`. The three enterprise
|
|
214
|
+
providers share the same SQLite file, receipt table, outbox table and process
|
|
215
|
+
lease; there is no per-platform queue, worker, database or reconnect loop. Each
|
|
216
|
+
account still has one receiver and one serial input/output lane, so providers
|
|
217
|
+
cannot consume each other's queue or block each other's replies. Deleting a Bot
|
|
218
|
+
removes all three rows, receipts and deliveries in one transaction.
|
|
219
|
+
|
|
220
|
+
## Delivery semantics
|
|
221
|
+
|
|
222
|
+
- **Durability:** the receipt, private routing target and deduplicated stable ID
|
|
223
|
+
commit before `onMessage` resolves. IDs are namespaced by provider, client account
|
|
224
|
+
and owner, so platform replays and restarts cannot re-execute admitted tools.
|
|
225
|
+
- **Backpressure:** pending plus admitted receipts cap at 100; each pass admits at
|
|
226
|
+
most 20. Adapters may treat `backlog_full` as retryable and must not acknowledge.
|
|
227
|
+
A platform replay whose stable ID already has a durable receipt is acknowledged
|
|
228
|
+
without a new slot, even when the backlog is full.
|
|
229
|
+
- **Isolation:** each account has one receiver, one serial inbound worker and one
|
|
230
|
+
serial outbound scheduler. A slow Bot cannot block another account.
|
|
231
|
+
- **Output source:** all public assistant replies, including App-initiated and
|
|
232
|
+
background replies, come from `channelPage`. Binding starts at the current
|
|
233
|
+
contact tip, so previous history/greetings are not sent. Internal settle markers
|
|
234
|
+
are omitted; failures use a safe generic message.
|
|
235
|
+
All channels attached to the same Bot share its contact context, but replies
|
|
236
|
+
go only to the channel that admitted the original input. Its persisted contact
|
|
237
|
+
`turnID` is the reserved `channel:*`/`weixin:*` receipt ID, and exact receipt
|
|
238
|
+
ownership by binding epoch gates delivery; another channel never broadcasts it.
|
|
239
|
+
Only App/background turns without a channel origin are proactively pushed to
|
|
240
|
+
all eligible bound platforms. Selection never uses the latest conversation turn.
|
|
241
|
+
Each enterprise receipt keeps its own private reply target, so a later sender
|
|
242
|
+
cannot redirect an earlier reply. The inbox target column is added in place for
|
|
243
|
+
existing databases; legacy receipts without a target and without a fixed owner
|
|
244
|
+
are not guessed from the latest sender. The feed watermark still advances over
|
|
245
|
+
filtered replies. Channels are not separate conversation contexts.
|
|
246
|
+
- **Generation:** a transcript wipe changes `channelPage().generation`. Queued
|
|
247
|
+
output from the previous generation is deleted, and late async work is fenced by
|
|
248
|
+
epoch, lease and generation.
|
|
249
|
+
- **Unknown delivery:** a crash or abort during `sending`, or an ambiguous adapter
|
|
250
|
+
error, marks the row `unknown`. It is never automatically resent and status
|
|
251
|
+
reports `delivery_unknown`. `retry` only reconnects and does not clear it.
|
|
252
|
+
Definitively failed rows may be retried explicitly. The outbox is strictly
|
|
253
|
+
ordered: an `unknown` or `blocked` head is never bypassed, so later replies wait
|
|
254
|
+
until the owner disconnects and configures the channel again (or a blocked row
|
|
255
|
+
is explicitly retried). Saving the same account/owner preserves unknown rows;
|
|
256
|
+
disconnecting discards that channel's queued replies as well as its credentials.
|
|
257
|
+
- **Reconnect:** connection failures retry with 1–30 second capped exponential
|
|
258
|
+
backoff. Authentication failure and SDK `connection_replaced` become a sticky
|
|
259
|
+
`error` until an explicit save or retry, so bad credentials or mutual-kick loops
|
|
260
|
+
cannot hot-loop. Output is only attempted after `onReady`; a send failure never
|
|
261
|
+
marks the lane connected. While sticky, new inbound receipts are not admitted
|
|
262
|
+
and already durable but unadmitted work waits for an explicit reconnect.
|
|
263
|
+
- **Save and concurrency:** a save drains admitted inbound work and aborts the old
|
|
264
|
+
receiver under a per-channel mutation lock. Owner/account changes revalidate the
|
|
265
|
+
binding epoch after the wait; a conflict or failed write resumes the previous
|
|
266
|
+
receiver instead of stranding it. `retry` and `disconnect` share the same lock
|
|
267
|
+
and revalidate the epoch after draining.
|
|
268
|
+
- **Disconnect:** deletes local credentials, receipts and queued replies. It does
|
|
269
|
+
not cancel already admitted contact work; late output is fenced and discarded.
|
|
270
|
+
- **Bot deletion:** `forget(assistantID)` removes every provider's local binding
|
|
271
|
+
and queues for that Bot.
|
|
272
|
+
- **Shutdown:** `close()` stops new work, aborts platform I/O, awaits all tracked
|
|
273
|
+
channel operations, releases the process lease and only then closes SQLite. The
|
|
274
|
+
owning Host must close channels before `service.close()`.
|
|
275
|
+
- **Lease:** one process sharing the data directory owns channels for 60 seconds,
|
|
276
|
+
renewed each tick (default 2 seconds). Another enabled process cannot steal a
|
|
277
|
+
live account and responds `channel_in_use` until the lease expires.
|
|
278
|
+
|
|
279
|
+
## Not in this layer
|
|
280
|
+
|
|
281
|
+
Live typing/presence, platform media download, template cards, interactive
|
|
282
|
+
callbacks and per-provider protocol routing are intentionally absent. Those belong
|
|
283
|
+
to adapters or a shared SDK. This layer also does not promise server-side
|
|
284
|
+
exactly-once delivery or platform token revocation.
|
|
285
|
+
|
|
286
|
+
## Validation
|
|
287
|
+
|
|
288
|
+
Focused Vitest suite: `bunx vitest run --project @yuriai/web packages/web/server/lib/assistants/channels`.
|
|
289
|
+
It uses real SQLite and the real assistant service for the end-to-end
|
|
290
|
+
channel → Bot → durable reply path. Adapter wire tests live with their adapters and
|
|
291
|
+
do not prove real-account permissions, quotas or mobile rendering.
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# Enterprise channel protocol boundaries
|
|
2
|
+
|
|
3
|
+
This directory integrates the vendor-maintained Chat SDK adapters instead of
|
|
4
|
+
maintaining a second platform wire implementation. Platform framing, WebSocket
|
|
5
|
+
handshakes, protobuf, ping/pong and reconnect stay in the SDKs below; Yuri owns
|
|
6
|
+
authorization, projection, durable receipts, outbound ordering and error
|
|
7
|
+
classification.
|
|
8
|
+
|
|
9
|
+
## SDK inventory
|
|
10
|
+
|
|
11
|
+
| Provider | Package | Version | Role |
|
|
12
|
+
| --- | --- | --- | --- |
|
|
13
|
+
| Chat contract | `chat` | `4.44.0` | `Message` / `Author` / `Attachment` / `Adapter` / `NotImplementedError` |
|
|
14
|
+
| Feishu | `@larksuite/vercel-chat-adapter` | `0.3.0` | Chat SDK adapter wrapping `@larksuite/channel` |
|
|
15
|
+
| Feishu wire | `@larksuite/channel` | `0.7.1` | WebSocket long connection, 23-type normalization, resource download |
|
|
16
|
+
| WeCom | `@wecom/aibot-node-sdk` | `1.0.7` | Official smart-bot WebSocket and awaited send ACK; Yuri Chat Adapter extension |
|
|
17
|
+
| DingTalk | `dingtalk-stream` | `2.1.5` | Gateway open, WebSocket, ping/pong, subscription registration |
|
|
18
|
+
|
|
19
|
+
`@larksuite/channel` is a direct dependency of `packages/web` (`0.7.1`).
|
|
20
|
+
`sdk-adapters.js` imports `createLarkChannel`/`normalize` statically; there is no
|
|
21
|
+
runtime resolution fallback.
|
|
22
|
+
|
|
23
|
+
`transport.js` remains the owner of the small HTTP helpers
|
|
24
|
+
(`channelError`, `requestJSON`, `officialURL`). Channel adapters use
|
|
25
|
+
`requestJSON` for the two documented outbound REST calls and do **not** use the
|
|
26
|
+
removed `socketLoop`; no adapter opens a raw WebSocket or decodes protobuf.
|
|
27
|
+
|
|
28
|
+
## Feishu
|
|
29
|
+
|
|
30
|
+
Wire evidence: `@larksuite/channel@0.7.1` and
|
|
31
|
+
`@larksuiteoapi/node-sdk@1.76.0` (`lib/index.js`), plus the official Go SDK
|
|
32
|
+
`larksuite/oapi-sdk-go@v3_main` (`ws/client_transport.go`).
|
|
33
|
+
|
|
34
|
+
- Bootstrap: `POST https://open.feishu.cn/callback/ws/endpoint` with
|
|
35
|
+
`{AppID, AppSecret}`; response carries `URL` and
|
|
36
|
+
`ClientConfig {PingInterval, ReconnectCount, ReconnectInterval, ReconnectNonce}`.
|
|
37
|
+
The SDK dials the returned `wss://` URL; query holds `device_id`/`service_id`.
|
|
38
|
+
- Frames are `pbbp2.Frame` protobuf: `1 SeqID uint64`, `2 LogID uint64`,
|
|
39
|
+
`3 service int32`, `4 method int32`, `5 headers`, `6 payloadEncoding`,
|
|
40
|
+
`7 payloadType`, `8 payload`, `9 LogIDNew`; each header is
|
|
41
|
+
`1 key`/`2 value`. `method` is `0 control` / `1 data`.
|
|
42
|
+
- Heartbeat: control frame with header `type=ping`; `pong` payload is JSON that
|
|
43
|
+
updates interval/reconnect settings. `ping` frames received from the peer are
|
|
44
|
+
not answered by the client.
|
|
45
|
+
- Delivery ACK: the official dispatcher replies with the same frame headers plus
|
|
46
|
+
`biz_rt` and a JSON payload (`{code:200}`), and only after awaited handlers.
|
|
47
|
+
- Outbound: `POST /open-apis/im/v1/messages?receive_id_type=open_id` with
|
|
48
|
+
`msg_type: text`, `content: {"text": ...}`. `uuid` dedupes for one hour and is
|
|
49
|
+
capped at 50 characters (official API documentation); `outboundUuid()` keeps
|
|
50
|
+
short row IDs verbatim and hashes longer ones to 40 hex characters.
|
|
51
|
+
`tenant_access_token/internal` uses `{app_id, app_secret}` and caches until
|
|
52
|
+
`expire - 180s`.
|
|
53
|
+
|
|
54
|
+
ACK durability: the Chat adapter's normalized `message` path is not awaited by
|
|
55
|
+
the vendor dispatcher, so it cannot gate the ACK. `sdk-adapters.js` therefore
|
|
56
|
+
projects and persists through the public
|
|
57
|
+
`LarkChannel.onRawEvent('im.message.receive_v1')` hook. The hook is installed
|
|
58
|
+
from inside `channelFactory`, i.e. before the adapter calls `channel.connect()`,
|
|
59
|
+
so there is no unguarded boot window and no fallback path. The normalized
|
|
60
|
+
`message` handler registered by the vendor adapter is inert for Yuri (the raw
|
|
61
|
+
gate already owns delivery) and no private `_getChannel()` accessor is used.
|
|
62
|
+
|
|
63
|
+
The vendor dispatcher awaits the raw handler before replying, which is what
|
|
64
|
+
keeps the ACK behind the durable receipt. It also catches handler exceptions, so
|
|
65
|
+
a failed durable write cannot force a non-200 ACK frame; the bridge reports
|
|
66
|
+
`onError` instead, and the runtime aborts/reconnects that lane. Readiness is
|
|
67
|
+
re-armed from the channel's own `reconnected` event (`reconnecting` maps to
|
|
68
|
+
`network_error`), so a successful SDK reconnect never leaves `runtime.ready`
|
|
69
|
+
false.
|
|
70
|
+
|
|
71
|
+
`createLarkAdapter` disables the channel's own stale/dedup/lock/batch pipeline
|
|
72
|
+
(`safety.staleMessageWindowMs` maxed, `chatQueue` off, batch delays 0); Yuri owns
|
|
73
|
+
authorization and receipt dedupe.
|
|
74
|
+
|
|
75
|
+
Boundaries:
|
|
76
|
+
|
|
77
|
+
- Inbound text comes from the vendor normalization. Images/files/audio/video
|
|
78
|
+
are reported as bounded public descriptors (`type`, `name`, `durationMs`) with
|
|
79
|
+
`notDownloaded: true`; `file_key` is never projected or downloaded.
|
|
80
|
+
- The adapter's `Message.attachments` is empty today (the Chat adapter does not
|
|
81
|
+
bridge `NormalizedMessage.resources`), so descriptors are read from the
|
|
82
|
+
vendor's normalized `raw` payload. Acquiring bytes would require the vendor's
|
|
83
|
+
internal `downloadResource` API; Yuri does not do that.
|
|
84
|
+
- The vendor adapter auto-reconnects its WebSocket itself. Yuri's runtime must
|
|
85
|
+
not add a second reconnect loop for Feishu; the bridge maps the channel's
|
|
86
|
+
`reconnecting` event to `onError('network_error')` and its `reconnected`
|
|
87
|
+
event back to `onReady()`, so the UI does not stay `connected` during a gap and
|
|
88
|
+
does not stay `reconnecting` after a successful resume. A 1s monitor reads the
|
|
89
|
+
public `channel.getConnectionStatus()`; when the vendor exhausts its bounded
|
|
90
|
+
reconnect attempts and reports `state: 'failed'`, the bridge reports
|
|
91
|
+
`network_error` and returns from `connect()` so the runtime opens a fresh
|
|
92
|
+
adapter. The bridge deliberately does not map every channel `error` event to a
|
|
93
|
+
transport failure, because that event also covers non-fatal normalization and
|
|
94
|
+
meeting errors; doing so would revoke readiness on a healthy connection.
|
|
95
|
+
- Outbound never retries automatically. `requestJSON` marks HTTP 5xx/timeouts
|
|
96
|
+
during a send as ambiguous so the store records `delivery_unknown`.
|
|
97
|
+
- Aborting during `channel.connect()` is safe: the vendor's `disconnect()` is a
|
|
98
|
+
no-op before the handshake completes, so the bridge closes the channel again
|
|
99
|
+
once the aborted initialize settles. A canceled connect cannot leave a live
|
|
100
|
+
socket behind.
|
|
101
|
+
|
|
102
|
+
## WeCom smart bot
|
|
103
|
+
|
|
104
|
+
Wire evidence: official `https://github.com/WecomTeam/aibot-node-sdk`,
|
|
105
|
+
`src/client.ts` (`sendMessage`) and `src/ws.ts` (`sendReply`/ACK handling).
|
|
106
|
+
`wecom-chat-adapter.js` implements the Chat SDK contract over its public `WSClient`.
|
|
107
|
+
|
|
108
|
+
- The SDK owns the official WebSocket, authentication, heartbeat, reconnect and
|
|
109
|
+
request-ID ACK matching. No private `wsManager` fields or custom wire are used.
|
|
110
|
+
- `authenticated` establishes readiness; `disconnected`/`reconnecting` revoke it.
|
|
111
|
+
Re-authentication restores readiness. Authentication failure and replacement are
|
|
112
|
+
sticky errors; reconnect exhaustion returns control to Yuri's scheduler.
|
|
113
|
+
- Initialization has a deadline; abort closes the SDK connection and listeners.
|
|
114
|
+
- `sendMessage()` waits for the platform ACK. Only `errcode: 0` advances the
|
|
115
|
+
outbox as sent (platform accepted, not proof the user read it). Nonzero ACKs are
|
|
116
|
+
definite failures; timeout, cancellation or disconnection after submission are
|
|
117
|
+
`delivery_unknown` and are never automatically resent.
|
|
118
|
+
- A configured owner fixes the private recipient; otherwise the runtime's private
|
|
119
|
+
durable `target.userID` supplies it. Missing recipients fail before sending.
|
|
120
|
+
- Incoming messages preserve `msgid` for durable dedup, use standard Chat `Message`
|
|
121
|
+
and platform voice transcription, and drop groups/disallowed senders. Media
|
|
122
|
+
descriptors are explicitly `notDownloaded`; URLs and AES keys are not projected.
|
|
123
|
+
- Different credentials have independent live clients. The personal-WeChat
|
|
124
|
+
single-entry/rebind rule remains confined to `weixin/`.
|
|
125
|
+
- The previous community adapter was removed because black-box testing proved
|
|
126
|
+
its `postMessage()` resolved before ACK and ignored nonzero ACKs. Regression
|
|
127
|
+
tests now drive the official SDK against a local WebSocket server, including
|
|
128
|
+
successful consecutive sends, nonzero ACKs and cancellation.
|
|
129
|
+
|
|
130
|
+
## DingTalk
|
|
131
|
+
|
|
132
|
+
Wire evidence: `dingtalk-stream@2.1.5` `dist/client.mjs` and
|
|
133
|
+
`src/client.ts` of `open-dingtalk/dingtalk-stream-sdk-nodejs`; OpenAPI metadata
|
|
134
|
+
from `@alicloud/dingtalk@2.2.48` (`robot_1_0`, `oauth2_1_0`).
|
|
135
|
+
|
|
136
|
+
- Gateway: `POST https://api.dingtalk.com/v1.0/gateway/connections/open` with
|
|
137
|
+
`{clientId, clientSecret, ua, subscriptions}`; response `{endpoint, ticket}`
|
|
138
|
+
and the SDK dials `${endpoint}?ticket=...`.
|
|
139
|
+
- The SDK owns ping/pong, `SYSTEM/CONNECTED|REGISTERED|disconnect|KEEPALIVE`
|
|
140
|
+
and reconnect (disabled here with `autoReconnect: false`, because Yuri's
|
|
141
|
+
runtime owns reconnect).
|
|
142
|
+
- Readiness: `REGISTERED` is the only authenticated signal. `connect()` waits
|
|
143
|
+
for it with a `INIT_TIMEOUT_MS` deadline. The `onLost` hook and watchdog are
|
|
144
|
+
installed before `client.connect()`, so a disconnect during the handshake is
|
|
145
|
+
never missed. A socket that opens but never registers is reported as
|
|
146
|
+
`network_error`, never `connected`.
|
|
147
|
+
- Session ownership: `createDingtalkSdkAdapter` creates one independent
|
|
148
|
+
`DingTalkChatAdapter` per `clientID+clientSecret+ownerID`. There is no shared
|
|
149
|
+
`this.session` singleton, so multiple bots connect in parallel; a duplicate
|
|
150
|
+
live connect for the same config is rejected with `channel_in_use`. The live
|
|
151
|
+
session map never evicts an active session.
|
|
152
|
+
- Initialization is abortable and bounded. Aborting during the SDK's endpoint
|
|
153
|
+
request closes the session and a late `_connect()` is refused, so the
|
|
154
|
+
underlying socket/timers cannot outlive the aborted connect.
|
|
155
|
+
- CALLBACK ACK: `2.1.5` does not auto-ack callbacks. `socketCallBackResponse`
|
|
156
|
+
is called only after the Yuri delivery promise resolves; failures leave the
|
|
157
|
+
callback unacknowledged for the platform retry. Unauthorized/malformed frames
|
|
158
|
+
are acknowledged and dropped so they cannot retry forever.
|
|
159
|
+
- Outbound: `POST /v1.0/oauth2/accessToken` `{appKey, appSecret}` →
|
|
160
|
+
`{accessToken, expireIn}` (cached until `expireIn - 300s`), then
|
|
161
|
+
`POST /v1.0/robot/oToMessages/batchSend` with
|
|
162
|
+
`{robotCode, userIds: [userID], msgKey: 'sampleText', msgParam}` and
|
|
163
|
+
`x-acs-dingtalk-access-token`. The recipient is `config.ownerID` when configured,
|
|
164
|
+
otherwise the runtime-derived `target.userID`. `invalidStaffIdList`,
|
|
165
|
+
`flowControlledStaffIdList` and `filteredStaffIdList` are all treated as
|
|
166
|
+
definite failures. HTTP 5xx/timeouts during send are ambiguous.
|
|
167
|
+
- Threads: `dingtalk:private:<owner>` / `dingtalk:group:<conversationId>`.
|
|
168
|
+
`isDM()` is true only for the `private` prefix, so a group is never reported as
|
|
169
|
+
a DM. `postMessage` throws `NotImplementedError` for group threads and
|
|
170
|
+
`invalid_response` for any private thread that is not the configured owner.
|
|
171
|
+
- Postables: `renderFormatted`/`messageText` accept standard Chat shapes only —
|
|
172
|
+
string, `{raw}`, `{markdown}` and `{ast}` (via `stringifyMarkdown`). The
|
|
173
|
+
non-standard `{text}` field is not read.
|
|
174
|
+
- Projection: single chat only; `senderStaffId` (fallback `senderId`) must
|
|
175
|
+
equal `ownerID` when configured, and the bot's own `chatbotUserId` is rejected. `audio` uses
|
|
176
|
+
the platform's `recognition` text and marks `metadata.transcript =
|
|
177
|
+
'platform'`; audio without recognition is `notDownloaded` and carries **no**
|
|
178
|
+
invented transcript. `richText` is flattened to its text items. Other
|
|
179
|
+
non-text messages yield `notDownloaded: true` plus `mediaType` and a bounded
|
|
180
|
+
name. `sessionWebhook`, `robotCode`, `conversationId` and download codes are
|
|
181
|
+
never projected.
|
|
182
|
+
- Unsupported Chat methods (`editMessage`, `deleteMessage`, `fetchMessages`,
|
|
183
|
+
`fetchThread`, `addReaction`, `removeReaction`, `startTyping`) throw the Chat
|
|
184
|
+
SDK `NotImplementedError` instead of pretending to work. `handleWebhook`
|
|
185
|
+
returns 501; this adapter is long-connection only.
|
|
186
|
+
|
|
187
|
+
## Shared projection and logging
|
|
188
|
+
|
|
189
|
+
- Only `private`/single-chat messages with sender identities are delivered.
|
|
190
|
+
A non-empty `ownerID` restricts this to one sender; empty uses platform access
|
|
191
|
+
controls. Group messages, disallowed senders, bot/app senders and the bot's own
|
|
192
|
+
events are dropped before any download or metadata expansion. Bot context is
|
|
193
|
+
shared, not isolated per sender; administrators must verify platform availability.
|
|
194
|
+
- Inbound metadata is rebuilt from scratch with public fields only. Capability
|
|
195
|
+
or secret handles (Feishu `file_key`, WeCom `aeskey`/`response_url`, DingTalk
|
|
196
|
+
`sessionWebhook`/`robotCode`) are never copied, even when the vendor message
|
|
197
|
+
carries them.
|
|
198
|
+
- Media is never downloaded automatically; every media message is explicitly
|
|
199
|
+
marked `notDownloaded` rather than claiming the content was read.
|
|
200
|
+
- Logging: every vendor logger is replaced with an inert logger
|
|
201
|
+
(`noopLogger()`). Vendor log arguments are never formatted or forwarded, so
|
|
202
|
+
tokens, URLs, IDs, message content and upstream error bodies cannot reach Yuri
|
|
203
|
+
logs through SDK logger objects. SDK errors are mapped to
|
|
204
|
+
`auth_expired`/`invalid_response`/`network_error`/`connection_replaced`
|
|
205
|
+
without forwarding raw upstream messages.
|
|
206
|
+
|
|
207
|
+
## Known limits
|
|
208
|
+
|
|
209
|
+
- Feishu: one extra normalization per inbound message (the vendor pipeline also
|
|
210
|
+
normalizes). The vendor dispatcher swallows exceptions from raw handlers, so a
|
|
211
|
+
failed durable write cannot force a non-200 ACK frame; the bridge reports
|
|
212
|
+
`onError` and the runtime aborts the lane instead.
|
|
213
|
+
- Feishu: `uuid` is derived from the durable delivery row ID; if the same row is
|
|
214
|
+
re-sent with different text, the platform would dedupe it. Yuri never mutates
|
|
215
|
+
a queued row's text. Neither vendor SDK exposes an idempotent send, which is
|
|
216
|
+
why the bridge uses the documented HTTP call with `uuid`.
|
|
217
|
+
- WeCom: real tenant authentication, proactive-message permissions and actual
|
|
218
|
+
network reconnection remain unverified; local SDK/ACK tests are not tenant tests.
|
|
219
|
+
- DingTalk: no media download, no history fetch, and readiness depends on the
|
|
220
|
+
platform emitting `REGISTERED` within the bounded window. Abort cleanup patches
|
|
221
|
+
the SDK's internal `_connect` because `connect()` awaits an unabortable
|
|
222
|
+
endpoint request before creating the socket.
|
|
223
|
+
- These adapters were validated with unit fixtures and the real SDK runtime
|
|
224
|
+
packages (including the real `WeComFormatConverter`, Feishu `normalize`, Chat
|
|
225
|
+
`Message`/`stringifyMarkdown`, and a real `@agentor/chat-wecom@0.1.3` run over
|
|
226
|
+
an injected fake `WebSocket` for the ACK evidence), not with live
|
|
227
|
+
Feishu/WeCom/DingTalk tenants. Real-account authentication, delivery and
|
|
228
|
+
reconnect behavior still require manual verification.
|