@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.20

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 (44) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +9 -0
  3. package/README.md +48 -2
  4. package/package.json +141 -4
  5. package/src/action-designer.ts +250 -0
  6. package/src/attachment-url.ts +195 -0
  7. package/src/auth/index.ts +6 -0
  8. package/src/auth/qrcode.ts +519 -0
  9. package/src/auth/types.ts +261 -0
  10. package/src/display-style.ts +250 -0
  11. package/src/editor-frame.ts +623 -0
  12. package/src/editor-session.ts +1214 -0
  13. package/src/editor-testing.ts +838 -0
  14. package/src/editor.ts +1641 -0
  15. package/src/frame-transport.ts +491 -0
  16. package/src/frontend-routes.ts +99 -0
  17. package/src/hooks.ts +48 -0
  18. package/src/host-caps.ts +93 -0
  19. package/src/i18n.ts +238 -0
  20. package/src/im-panel.ts +132 -0
  21. package/src/image-tools.ts +91 -0
  22. package/src/index.ts +118 -0
  23. package/src/interactive-session.ts +94 -0
  24. package/src/nahida-im.ts +391 -0
  25. package/src/nahida-ws.ts +23 -0
  26. package/src/org-directory.ts +78 -0
  27. package/src/oz-realtime.ts +144 -0
  28. package/src/page.ts +404 -0
  29. package/src/print.ts +393 -0
  30. package/src/surface.ts +281 -0
  31. package/src/theme-mocks.ts +140 -0
  32. package/src/theme.ts +125 -0
  33. package/src/ui-fixtures/confirm.ts +16 -0
  34. package/src/ui-fixtures/entity-picker.ts +24 -0
  35. package/src/ui-fixtures/expression-editor.ts +52 -0
  36. package/src/ui-fixtures/image-cropper.ts +23 -0
  37. package/src/ui-fixtures/index.ts +16 -0
  38. package/src/ui-fixtures/org-tri-picker.ts +19 -0
  39. package/src/ui-fixtures/prompt.ts +19 -0
  40. package/src/ui-fixtures/record-picker.ts +17 -0
  41. package/src/ui-fixtures/template-picker.ts +13 -0
  42. package/src/ui-mocks.ts +250 -0
  43. package/src/ui.ts +479 -0
  44. package/src/workflow-designer.ts +475 -0
@@ -0,0 +1,93 @@
1
+ // 平台级 hostCaps 白名单裁剪(SEC-012)。
2
+ //
3
+ // 契约原文:"host caps 必须按 surface 白名单裁剪,未声明能力在运行时不可见"。
4
+ // "不可见"不是"读到 undefined"——那样插件仍可能写出 `bridge.admin?.retryFailedActivity(...)`
5
+ // 这种"侥幸通过 optional chaining 静默跳过"的代码,问题在运行时被悄悄吞掉,难以定位配置错误。
6
+ // 本实现改用 Proxy:未声明的键在 `in`/`Object.keys`/JSON 序列化等场景里确实不可见(ownKeys 不
7
+ // 会枚举出来),但一旦插件代码主动访问该键(`bridge.admin`),立即抛出携带能力名的
8
+ // WorkflowCapabilityError——插件作者能在开发期第一时间发现"这个 surface 没声明这个能力",
9
+ // 而不是等到点某个按钮时才发现回调是 undefined。
10
+ //
11
+ // pruneBridgeByCaps / WorkflowCapabilityError 等符号是平台级能力裁剪(宿主 UI 服务、KimpoAI /
12
+ // IM 悬浮窗、动作设计器等共用),不专属流程插件;名字里的 Workflow 是历史命名,作为公开导出名保留。
13
+
14
+ import { INTERACTIVE_SESSION_CAPABILITY } from './interactive-session';
15
+
16
+ /** SEC-012:本模块所有"未声明能力访问"异常的固定错误码,供插件侧 catch 时做机器判断。 */
17
+ export const WORKFLOW_CAPABILITY_ERROR_CODE = 'SEC-012';
18
+
19
+ /**
20
+ * 未声明能力访问异常。错误码 SEC-012 固定,供插件/宿主日志按码检索
21
+ * (与宿主其它安全类错误码惯例一致)。
22
+ */
23
+ export class WorkflowCapabilityError extends Error {
24
+ /** 固定错误码 SEC-012(等于 WORKFLOW_CAPABILITY_ERROR_CODE),供 catch 时按码判断(SDK 1.1.0-tp.19 起)。 */
25
+ readonly code = WORKFLOW_CAPABILITY_ERROR_CODE;
26
+ /** 触发异常的能力键(namespace 拼接后的完整 hostCaps 条目)。 */
27
+ readonly capability: string;
28
+
29
+ constructor(capability: string) {
30
+ super(`${WORKFLOW_CAPABILITY_ERROR_CODE}: workflow host capability "${capability}" not declared in hostCaps for this surface`);
31
+ this.name = 'WorkflowCapabilityError';
32
+ this.capability = capability;
33
+ }
34
+ }
35
+
36
+ export interface PruneBridgeByCapsOptions {
37
+ /**
38
+ * 能力键命名空间前缀(不含末尾 '.')。SurfaceCreateInput.hostCaps 是整个 surface 的扁平能力
39
+ * 键列表(可能混有非 workflow 能力),故 workflow bridge 域名(definition/task/taskCenter/
40
+ * instance/admin)在 hostCaps 里以 `${namespace}.${key}` 形式出现,避免裸键与其它能力面撞名。
41
+ * 缺省 'workflow',即 hostCaps 需要形如 'workflow.definition' 才能放行 bridge.definition。
42
+ */
43
+ namespace?: string;
44
+ }
45
+
46
+ /**
47
+ * pruneBridgeByCaps —— 按 hostCaps 白名单裁剪 bridge 对象的规范实现。
48
+ *
49
+ * 用法(宿主接线处,非插件侧):
50
+ * ```ts
51
+ * const prunedWorkflowBridge = pruneBridgeByCaps(fullWorkflowHostBridge, surfaceHostCaps);
52
+ * // 插件访问 prunedWorkflowBridge.definition:
53
+ * // hostCaps 含 'workflow.definition' → 拿到真实的 WorkflowDefinitionBridge
54
+ * // hostCaps 不含该键 → 立即抛 WorkflowCapabilityError('workflow.definition')
55
+ * ```
56
+ *
57
+ * 只裁剪对象的**一层自有键**(bridge 各域的方法内部不做递归裁剪——域一旦放行即整体可用,
58
+ * 与"按域授权"的粒度保持一致,避免过度设计成方法级白名单)。
59
+ */
60
+ export function pruneBridgeByCaps<T extends object>(
61
+ bridge: T,
62
+ hostCaps: readonly string[],
63
+ options?: PruneBridgeByCapsOptions
64
+ ): T {
65
+ const namespace = options?.namespace ?? 'workflow';
66
+ const prefix = namespace ? `${namespace}.` : '';
67
+ const allowed = new Set(hostCaps);
68
+ const capabilityForKey = (key: string): string =>
69
+ key === 'interactiveSession' ? INTERACTIVE_SESSION_CAPABILITY : `${prefix}${key}`;
70
+ // theme(宿主设计数值)常驻可见,不需要在 hostCaps 声明,不参与裁剪。
71
+ const isAllowedKey = (key: string): boolean => key === 'theme' || allowed.has(capabilityForKey(key));
72
+
73
+ return new Proxy(bridge, {
74
+ get(target, prop, receiver) {
75
+ if (typeof prop === 'symbol') return Reflect.get(target, prop, receiver);
76
+ if (!isAllowedKey(prop)) {
77
+ throw new WorkflowCapabilityError(capabilityForKey(prop));
78
+ }
79
+ return Reflect.get(target, prop, receiver);
80
+ },
81
+ has(target, prop) {
82
+ if (typeof prop === 'symbol') return Reflect.has(target, prop);
83
+ return isAllowedKey(prop) && Reflect.has(target, prop);
84
+ },
85
+ ownKeys(target) {
86
+ return Reflect.ownKeys(target).filter((key) => typeof key === 'string' && isAllowedKey(key));
87
+ },
88
+ getOwnPropertyDescriptor(target, prop) {
89
+ if (typeof prop === 'symbol' || !isAllowedKey(prop)) return undefined;
90
+ return Reflect.getOwnPropertyDescriptor(target, prop);
91
+ }
92
+ }) as T;
93
+ }
package/src/i18n.ts ADDED
@@ -0,0 +1,238 @@
1
+ // i18n 契约与两级查找 helper(插件自带语言包 → 宿主中央语言包两级兜底)。
2
+ //
3
+ // 角色分工:
4
+ // - HostI18n:宿主注入给插件前端的多语言能力(响应式 locale + 中央包查询 + 切换订阅)。
5
+ // 宿主在 EditorHostBridge.i18n / surface hostBridge['i18n'] 上提供;插件只消费、不自建语言探测。
6
+ // - createPluginI18n:插件侧四级查找链的参考实现(零依赖,纯 TS):
7
+ // ① 插件自带语言包[当前 locale] —— 权威源,随 UMD 同构建打包
8
+ // ② 宿主 HostI18n.t —— 兜两类:管理员上传补充的插件缺失 locale、公共词表
9
+ // ③ 插件自带语言包[默认 locale] —— 文案兜底
10
+ // ④ key 原样返回 —— 开发期醒目暴露漏翻
11
+ //
12
+ // 低耦合红线:第 ② 级对宿主 key 的依赖仅限「冻结公共词表」(COMMON_VOCABULARY),
13
+ // 插件业务文本一律自带;清单外 key 不得指望宿主中央包里"碰巧有"。
14
+ //
15
+ // 两种挂载档下第 ② 级的取值来源(1.1.0-tp.18 起口径一致):
16
+ // - 同源档(官方插件):HostI18n.t 直接查宿主已合并中央包;
17
+ // - 沙箱档(第三方前端,iframe):宿主中央包不整体进框架;宿主在握手 / 切语言时按 FRAME_I18N_* 规则
18
+ // 为本插件裁出只读词条快照(当前 locale 的 COMMON_VOCABULARY、`backend.err.plugin.*`、本插件命名空间
19
+ // `<namespace>.*`),框架内 HostI18n.t 只查这份快照(见 frame-transport.ts)。命名空间须等于插件 ID
20
+ // 或以「插件 ID.」开头,否则宿主只给前两类;其他插件与宿主私有键一律不下发。需要支持该快照的宿主,
21
+ // 老宿主上沙箱档第 ② 级恒未命中(t 返回 ''),查找链照常回落 ③④。
22
+
23
+ /** 多语言文本对象(与宿主 utils/localize.LocalizedText 对齐);string 为旧版单语言兼容。 */
24
+ export type LocalizedText = string | Record<string, string>;
25
+
26
+ /** 只读响应式 locale 引用:结构兼容 Vue Ref<string>,SDK 侧不依赖 Vue。 */
27
+ export interface HostLocaleRef {
28
+ readonly value: string;
29
+ }
30
+
31
+ /** 语言下拉选项(label 为展示名,key 为 BCP-47 locale code)。 */
32
+ export interface HostLocaleOption {
33
+ label: string;
34
+ key: string;
35
+ }
36
+
37
+ /**
38
+ * 只读响应式时区引用:
39
+ * value 为 IANA 时区名(如 "Asia/Shanghai"),结构与 HostLocaleRef 一致、兼容 Vue Ref<string>。
40
+ * 宿主来源 = 宿主应用状态里的响应式 `timezone`(已含"服务端偏好→浏览器时区→Asia/Shanghai"三级兜底链);
41
+ * 插件侧只读消费,不自行持久化。
42
+ */
43
+ export interface HostTimezoneRef {
44
+ readonly value: string;
45
+ }
46
+
47
+ /**
48
+ * HostI18n 是宿主注入给插件前端的多语言能力面。
49
+ *
50
+ * 契约要点:
51
+ * - locale:当前语言(BCP-47 连字符,如 "zh-CN");宿主传入 Vue ref,插件可直接 watch。
52
+ * - t(key):查宿主 vue-i18n 已合并中央包(system 无前缀 / backend、插件 ns 带前缀)。
53
+ * **缺 key 时返回 ''**(不返回 key 本身),使插件侧查找链能识别 miss 并继续回退。
54
+ * - resolve(value):解析 LocalizedText 多语言对象(manifest name 等宿主下发结构)。
55
+ * - onLocaleChange(cb):订阅语言切换,返回取消函数;插件卸载时必须调用取消,防泄漏。
56
+ * - availableLocales / switchLocale(**可选**字段,非破坏性追加):
57
+ * 宿主本就持有全局语言下拉的选项列表与切换动作,开放给插件,使登录页等场景可以画出真正能用的语言切换 UI,
58
+ * 而不是只读 locale + 视觉占位。老宿主实现(未升级到本字段)该两项为 undefined,
59
+ * 插件侧必须判空后再决定是否渲染可交互的切换入口(不可假设一定存在)。
60
+ */
61
+ export interface HostI18n {
62
+ locale: HostLocaleRef;
63
+ t(key: string, params?: Record<string, unknown>): string;
64
+ resolve(value: LocalizedText | null | undefined): string;
65
+ onLocaleChange(cb: (locale: string) => void): () => void;
66
+ /** 当前宿主支持切换的语言选项;未提供切换能力的宿主可不注入(插件侧需判空)。 */
67
+ availableLocales?: HostLocaleOption[];
68
+ /** 主动切换宿主语言(会持久化 + 驱动 locale 更新 + 触发 onLocaleChange 订阅)。 */
69
+ switchLocale?(locale: string): void | Promise<void>;
70
+ }
71
+
72
+ /**
73
+ * 冻结公共词表(低耦合红线的机器可读形态)。
74
+ * 宿主承诺不重命名清单内 key;插件第 ② 级回退仅允许依赖此清单 + err.plugin.* 全族。
75
+ * 变更本清单 = 契约变更,须同步方案文档并通知所有插件。
76
+ */
77
+ export const COMMON_VOCABULARY = [
78
+ 'common.confirm',
79
+ 'common.cancel',
80
+ 'common.save',
81
+ 'common.delete',
82
+ 'common.edit',
83
+ 'common.search',
84
+ 'common.loading',
85
+ 'common.empty',
86
+ 'common.success',
87
+ 'common.failed'
88
+ ] as const;
89
+
90
+ /** err.plugin.* 框架级错误族前缀(公共词表的第二部分,整族冻结)。 */
91
+ export const ERR_PLUGIN_PREFIX = 'err.plugin.';
92
+
93
+ /**
94
+ * 沙箱档词条快照的放行规则(宿主裁剪与 SDK 文档同口径;宿主 sandboxedSurfaceHost 镜像本函数)。
95
+ * hostKey 是宿主中央包 key(toHostKey 映射后的形态):
96
+ * - COMMON_VOCABULARY 原样 key;
97
+ * - `backend.err.plugin.` 开头的 key;
98
+ * - `<namespace>.` 开头的 key,且 namespace 等于 pluginId 或以 `${pluginId}.` 开头(防冒用他人命名空间)。
99
+ */
100
+ export function isFrameI18nKeyAllowed(hostKey: string, pluginId: string, namespace?: string): boolean {
101
+ if (!hostKey) return false;
102
+ if ((COMMON_VOCABULARY as readonly string[]).includes(hostKey)) return true;
103
+ if (hostKey.startsWith(`backend.${ERR_PLUGIN_PREFIX}`)) return true;
104
+ const ns = frameI18nNamespace(pluginId, namespace);
105
+ return !!ns && hostKey.startsWith(`${ns}.`);
106
+ }
107
+
108
+ /**
109
+ * 沙箱档可下发词条的插件命名空间:manifest `i18n.namespace` 等于插件 ID 或以「插件 ID.」开头时取它,
110
+ * 未声明时取插件 ID;声明了别的命名空间(可能冒用其他插件或宿主的 key)时返回 '',只下发公共词表与 err.plugin.*。
111
+ */
112
+ export function frameI18nNamespace(pluginId: string, namespace?: string): string {
113
+ const id = String(pluginId ?? '').trim();
114
+ if (!id) return '';
115
+ const ns = String(namespace ?? '').trim();
116
+ if (!ns) return id;
117
+ return ns === id || ns.startsWith(`${id}.`) ? ns : '';
118
+ }
119
+
120
+ /** 把 locale 归一为 BCP-47 连字符小写语言+大写地区(zh_CN / zh-cn → zh-CN)。 */
121
+ export function normalizePluginLocale(locale: string | null | undefined): string {
122
+ if (!locale) return '';
123
+ const parts = String(locale).replace(/_/g, '-').split('-');
124
+ if (parts.length === 1) return parts[0].toLowerCase();
125
+ return `${parts[0].toLowerCase()}-${parts.slice(1).join('-').toUpperCase()}`;
126
+ }
127
+
128
+ /** {name} 占位插值:与 vue-i18n named interpolation 的最小交集,保持两级实现观感一致。 */
129
+ function interpolate(text: string, params?: Record<string, unknown>): string {
130
+ if (!params) return text;
131
+ return text.replace(/\{(\w+)\}/g, (m, name: string) => {
132
+ const v = params[name];
133
+ return v === undefined || v === null ? m : String(v);
134
+ });
135
+ }
136
+
137
+ export interface PluginI18nOptions {
138
+ /** locale -> 扁平点分 key 文案表(import 自插件 frontend/locales/*.json,构建期打包)。 */
139
+ messages: Record<string, Record<string, string>>;
140
+ /** 插件默认语言(查找链第 ③ 级;与 manifest.i18n.default_locale 一致)。 */
141
+ defaultLocale: string;
142
+ /** 宿主注入的 HostI18n;缺席(老宿主/单测)时降级为 ①③④ 纯本地链。 */
143
+ host?: HostI18n;
144
+ /**
145
+ * 插件 i18n namespace(= manifest.i18n.namespace,缺省 plugin_id)。
146
+ * 第 ② 级查自身 key 时按 `<namespace>.<key>` 映射到中央包(管理员补 locale 场景);
147
+ * 不传则第 ② 级仅公共词表可查。
148
+ */
149
+ namespace?: string;
150
+ }
151
+
152
+ export interface PluginI18n {
153
+ /** 四级链取文案。 */
154
+ t(key: string, params?: Record<string, unknown>): string;
155
+ /** 当前 locale(已归一)。 */
156
+ getLocale(): string;
157
+ /** 订阅 locale 变化(宿主切语言时触发);返回取消函数。 */
158
+ onChange(cb: (locale: string) => void): () => void;
159
+ /** 无宿主注入时手动设定 locale(dev/单测通道;有宿主时以宿主为准,此调用被忽略)。 */
160
+ setLocale(locale: string): void;
161
+ /** 释放宿主订阅;插件 deactivate 时调用。 */
162
+ dispose(): void;
163
+ }
164
+
165
+ /** 把插件视角的 key 映射为宿主中央包 key(namespace 前缀规则与宿主中央包合并规则一致)。 */
166
+ function toHostKey(key: string, namespace?: string): string | null {
167
+ // 公共词表:system 命名空间无前缀,原样查。
168
+ if ((COMMON_VOCABULARY as readonly string[]).includes(key)) return key;
169
+ // err.plugin.* 族:落在 backend 命名空间,中央包带 "backend." 前缀。
170
+ if (key.startsWith(ERR_PLUGIN_PREFIX)) return `backend.${key}`;
171
+ // 插件自身 key:仅在声明了 namespace 时可查中央包(管理员补 locale 场景)。
172
+ if (namespace) return `${namespace}.${key}`;
173
+ return null;
174
+ }
175
+
176
+ /**
177
+ * createPluginI18n —— 插件前端两级(四步)查找链的参考实现。
178
+ * 插件不要自行实现该链(保证全家行为一致);Vue 响应式由插件侧薄包一层 ref + onChange。
179
+ */
180
+ export function createPluginI18n(options: PluginI18nOptions): PluginI18n {
181
+ const messages: Record<string, Record<string, string>> = {};
182
+ for (const [loc, table] of Object.entries(options.messages || {})) {
183
+ messages[normalizePluginLocale(loc)] = table || {};
184
+ }
185
+ const defaultLocale = normalizePluginLocale(options.defaultLocale) || 'zh-CN';
186
+ const host = options.host;
187
+ const namespace = options.namespace;
188
+
189
+ let current = normalizePluginLocale(host?.locale?.value) || defaultLocale;
190
+ const listeners = new Set<(locale: string) => void>();
191
+
192
+ const applyLocale = (next: string) => {
193
+ const norm = normalizePluginLocale(next);
194
+ if (!norm || norm === current) return;
195
+ current = norm;
196
+ listeners.forEach(cb => cb(current));
197
+ };
198
+
199
+ // 有宿主时跟随宿主切换;unsubscribe 由 dispose 释放。
200
+ const unsubscribe = host ? host.onLocaleChange(applyLocale) : undefined;
201
+
202
+ const t = (key: string, params?: Record<string, unknown>): string => {
203
+ // ① 插件自带语言包[当前 locale]
204
+ const own = messages[current]?.[key];
205
+ if (own !== undefined) return interpolate(own, params);
206
+ // ② 宿主中央包(管理员补 locale + 公共词表);宿主契约缺 key 返回 '',
207
+ // 防御性兼容"返回 key 本身"的实现,两者都视为 miss。
208
+ if (host) {
209
+ const hostKey = toHostKey(key, namespace);
210
+ if (hostKey) {
211
+ const fromHost = host.t(hostKey, params);
212
+ if (fromHost && fromHost !== hostKey) return fromHost;
213
+ }
214
+ }
215
+ // ③ 插件自带语言包[默认 locale]
216
+ const fallback = messages[defaultLocale]?.[key];
217
+ if (fallback !== undefined) return interpolate(fallback, params);
218
+ // ④ key 原样返回:开发期醒目暴露漏翻(有意不做"就近顶替")。
219
+ return key;
220
+ };
221
+
222
+ return {
223
+ t,
224
+ getLocale: () => current,
225
+ onChange: (cb: (locale: string) => void) => {
226
+ listeners.add(cb);
227
+ return () => listeners.delete(cb);
228
+ },
229
+ setLocale: (locale: string) => {
230
+ if (host) return; // 有宿主时语言唯一来源是宿主
231
+ applyLocale(locale);
232
+ },
233
+ dispose: () => {
234
+ unsubscribe?.();
235
+ listeners.clear();
236
+ }
237
+ };
238
+ }
@@ -0,0 +1,132 @@
1
+ /**
2
+ * im-panel.ts —— IM 面板插件(surfaceType='im-panel')的公开契约(1.1.0-tp.5 起)。
3
+ *
4
+ * 链路:插件前端。宿主在认证后页面常驻外壳里按「IM 提供者」设置挂载唯一一个 im-panel surface,
5
+ * 窗口显隐由宿主控制(不销毁组件、不断 WS)。
6
+ *
7
+ * 两种挂载档:
8
+ * - 同源档(只限官方签名包):插件自己画浮窗(position: fixed),宿主按下表注入同步对象;
9
+ * - 沙箱档(第三方一律如此):宿主画浮窗外壳(右下角固定尺寸 + 标题条 + 收起按钮),插件组件铺满 iframe 即可;
10
+ * bridge 上的方法全部变成返回 Promise 的远程调用,订阅类方法(ws.subscribe / ws.onStateChange 等)
11
+ * 返回 `Promise<() => void>`,用 `disposerOf()`(from '@kimposoft/plugin-sdk/frame')统一成同步退订;
12
+ * `im.time.currentTimezone()` 与 `locale` 是挂载时快照;语言切换请用 `i18n`(HostI18n)跟随。
13
+ *
14
+ * 沙箱档开放的 bridge 键(宿主再按 manifest host_caps 裁剪,未声明即不可见):
15
+ * im / ws / log / logger / i18n / locale / message / navigate / org / assets / notifyUnreadMaybeChanged /
16
+ * openDesktopApp / clearPendingConvId / theme。
17
+ * 不开放:imWindowState(改由 props.visible / props.pendingConvId 与 collapse 事件代替)、编辑权移交三件套
18
+ * (edit-session)、宿主中央语言包 t、宿主 UI 服务总线 ui.*、通用 request。
19
+ */
20
+ import type { NahidaImClient, NahidaLogger } from './nahida-im';
21
+ import type { NahidaWSClient } from './nahida-ws';
22
+ import type { OrgDirectoryClient } from './org-directory';
23
+ import type { HostI18n } from './i18n';
24
+ import type { HostTheme } from './theme';
25
+ import { definePluginSurface, type SurfaceCreateInput, type SurfaceMountResult } from './surface';
26
+
27
+ /** im-panel 的 surface 类型常量。 */
28
+ export const IM_PANEL_SURFACE_TYPE = 'im-panel';
29
+
30
+ /** 沙箱档宿主为 im-panel 组装的 bridge 白名单键(与宿主沙箱档实现同口径)。 */
31
+ export const IM_PANEL_FRAME_BRIDGE_KEYS = [
32
+ 'im',
33
+ 'ws',
34
+ 'log',
35
+ 'logger',
36
+ 'i18n',
37
+ 'locale',
38
+ 'message',
39
+ 'navigate',
40
+ 'org',
41
+ 'assets',
42
+ 'notifyUnreadMaybeChanged',
43
+ 'openDesktopApp',
44
+ 'clearPendingConvId',
45
+ 'theme'
46
+ ] as const;
47
+
48
+ /** 宿主提示条(同源档同步、沙箱档异步,返回值可忽略)。 */
49
+ export interface ImPanelMessageClient {
50
+ success(content: string): unknown;
51
+ warning(content: string): unknown;
52
+ error(content: string): unknown;
53
+ info(content: string): unknown;
54
+ }
55
+
56
+ /**
57
+ * im-panel 宿主桥(host_caps → 键:im→im、ws→ws、log→log / logger、i18n→i18n / locale、message→message、
58
+ * navigation→navigate、org→org、asset→assets、unread-notify→notifyUnreadMaybeChanged、desktop-app→openDesktopApp)。
59
+ * 全部可选:宿主按声明裁剪,读取未声明的键可能抛错,请包 try/catch(见模板 bridge.ts)。
60
+ */
61
+ export interface ImPanelHostBridge {
62
+ im?: NahidaImClient;
63
+ ws?: NahidaWSClient;
64
+ /** 结构化日志(与 im.logger 同形),进宿主 IM 日志通道。 */
65
+ logger?: NahidaLogger;
66
+ /** 扁平日志口。 */
67
+ log?(level: 'debug' | 'info' | 'warn' | 'error', message: string, extra?: unknown): unknown;
68
+ /** 宿主语言能力:沙箱档跟随宿主实时切换(tp.5 起沙箱档提供;同源档官方宿主不提供)。 */
69
+ i18n?: HostI18n;
70
+ /** 当前语言(BCP-47),挂载时快照。 */
71
+ locale?: string;
72
+ message?: ImPanelMessageClient;
73
+ /** 站内深链跳转(宿主校验,跳转后收起浮窗)。 */
74
+ navigate?(link: string): unknown;
75
+ org?: OrgDirectoryClient;
76
+ assets?: NahidaImClient['assets'];
77
+ /** 本地推进已读后通知宿主刷新顶栏未读数。 */
78
+ notifyUnreadMaybeChanged?(): unknown;
79
+ /** 打开 / 安装桌面客户端(桌面壳内不注入)。 */
80
+ openDesktopApp?(): unknown;
81
+ /** 消费完 props.pendingConvId 后清空宿主的待打开会话。 */
82
+ clearPendingConvId?(): unknown;
83
+ /** 宿主设计数值(常驻只读,用 readHostTheme 读取)。 */
84
+ theme?: HostTheme;
85
+ }
86
+
87
+ /**
88
+ * 宿主传给 im-panel 组件的 props。沙箱档里 visible / pendingConvId 随宿主状态同步;
89
+ * 组件 emit('collapse') 即请求宿主收起浮窗(两种挂载档都生效)。
90
+ */
91
+ export interface ImPanelSurfaceProps {
92
+ userId: string;
93
+ hostBridge?: ImPanelHostBridge;
94
+ /** 浮窗当前是否展开(沙箱档提供)。 */
95
+ visible?: boolean;
96
+ /** 通知卡片点开的待打开会话 ID(沙箱档提供;消费后调用 hostBridge.clearPendingConvId)。 */
97
+ pendingConvId?: string | null;
98
+ }
99
+
100
+ /** 从 createSurface 入参取 im-panel bridge:契约字段 input.hostBridge 优先,回落 input.props.hostBridge。 */
101
+ export function resolveImPanelHostBridge(input: SurfaceCreateInput): ImPanelHostBridge | undefined {
102
+ const props = (input.props ?? {}) as Record<string, unknown>;
103
+ return (input.hostBridge ?? props.hostBridge) as ImPanelHostBridge | undefined;
104
+ }
105
+
106
+ /**
107
+ * defineImPanelSurface —— IM 面板专用的 definePluginSurface:两种挂载档写法一致,沙箱档自动启动框架运行时。
108
+ * 非 im-panel 挂载点调用时抛错;工厂拿到已解析好的 hostBridge 与 userId。
109
+ *
110
+ * @example
111
+ * ```ts
112
+ * export const createSurface = defineImPanelSurface(({ hostBridge, userId }) => ({
113
+ * component: ImPanel,
114
+ * props: { hostBridge, userId }
115
+ * }));
116
+ * ```
117
+ */
118
+ export function defineImPanelSurface(
119
+ factory: (ctx: { input: SurfaceCreateInput; hostBridge: ImPanelHostBridge | undefined; userId: string }) => SurfaceMountResult
120
+ ): (input: SurfaceCreateInput) => SurfaceMountResult {
121
+ return definePluginSurface((input: SurfaceCreateInput) => {
122
+ if ((input.surfaceType as string) !== IM_PANEL_SURFACE_TYPE) {
123
+ throw new Error(`defineImPanelSurface: unsupported surface ${String(input.surfaceType)}`);
124
+ }
125
+ const props = (input.props ?? {}) as Record<string, unknown>;
126
+ return factory({
127
+ input,
128
+ hostBridge: resolveImPanelHostBridge(input),
129
+ userId: typeof props.userId === 'string' ? props.userId : ''
130
+ });
131
+ });
132
+ }
@@ -0,0 +1,91 @@
1
+ // 图片工具前端契约(host ↔ editor 插件):宿主内置「图片裁切/调整」通用弹窗能力,
2
+ // 供各编辑器插件经 hostBridge.imageTools 复用。本文件只产出裁切/压缩参数(自然像素坐标 +
3
+ // 压缩档位),不产出像素——真正的像素级压缩权威在宿主后端图片处理,前端仅采集意图。
4
+
5
+ /**
6
+ * 裁切矩形,自然像素坐标。
7
+ *
8
+ * 坐标系契约(前后端统一,2026-07-14 定案;2026-08-12 增补翻转档):crop 相对「原图先按
9
+ * flipHorizontal 水平镜像、再按 rotateDegree 顺时针旋转之后」的图像坐标系(90°/270° 时宽高
10
+ * 互换)。对应宿主后端 custom 档的处理顺序为「先镜像 → 再旋转 → 最后按 crop 裁切」。
11
+ *
12
+ * 「先镜像后旋转」不是随意选定的顺序,而是与前端取数源 vue-advanced-cropper 对齐:该库给底图
13
+ * 施加的 CSS 变换串是 `rotate(θdeg) scaleX(±1) scaleY(±1)`,CSS transform 按从右到左作用,
14
+ * 故实际顺序即「先翻转、后旋转」;且其 flip() 会同步重算 coordinates/visibleArea,
15
+ * getResult().coordinates 天然落在「翻转+旋转后」的图像坐标系里,前端无需做坐标反算。
16
+ */
17
+ export interface ImageCropRect {
18
+ x: number;
19
+ y: number;
20
+ width: number;
21
+ height: number;
22
+ }
23
+
24
+ /** 压缩档位,与宿主后端三档对齐。 */
25
+ export type ImageCompressMode = 'lossless' | 'visually_lossless' | 'custom';
26
+
27
+ /**
28
+ * 基本模式三档(面向最终用户的傻瓜档位,2026-07-14 新增)。弹窗内部会把用户在「基本」态选中的
29
+ * 档位映射为 ImageCropperResult 的底层 mode/quality/format 字段,调用方无需感知映射细节。
30
+ * - original:不改变画质,仅清除隐私信息(EXIF 等)。
31
+ * - optimized:视觉无损,大幅减小体积(默认推荐档)。
32
+ * - extreme:体积优先,画质轻微下降。
33
+ */
34
+ export type ImageBasicMode = 'original' | 'optimized' | 'extreme';
35
+
36
+ export interface ImageCropperOptions {
37
+ /** 图片来源:二选一。 */
38
+ file?: File;
39
+ src?: string;
40
+ /** 固定比例预设,如 [1, 4/3, 16/9];空=自由裁切。 */
41
+ aspectRatioPresets?: number[];
42
+ /** 默认压缩档,缺省 visually_lossless。仅影响「高级」态的默认选中值。 */
43
+ defaultMode?: ImageCompressMode;
44
+ /** 是否展示压缩档位选择区,缺省 true。 */
45
+ showCompressPanel?: boolean;
46
+ /** 是否展示「高级模式」入口,缺省 true;false 时仅基本三档可用(如 kimposheet 试点)。 */
47
+ showAdvancedMode?: boolean;
48
+ /**
49
+ * 是否展示基本/高级画质选项,缺省 true。头像等由业务端固定输出质量的场景传 false,
50
+ * 此时只保留裁切画布和几何工具,不让用户选择最终编码质量。
51
+ */
52
+ showQualityOptions?: boolean;
53
+ /** 基本模式默认选中档,缺省 'optimized'。 */
54
+ defaultBasicMode?: ImageBasicMode;
55
+ /** 固定裁切比例(如 1、16/9);设置后裁切框锁定该比例且隐藏比例预设选择。 */
56
+ aspectRatio?: number;
57
+ /** 指定输出分辨率:锁定裁切比例为 width/height,并在结果中强制 targetWidth/targetHeight。 */
58
+ resolution?: { width: number; height: number };
59
+ /** 弹窗标题覆盖(i18n 已翻译文案由调用方传入;缺省用内置标题)。 */
60
+ title?: string;
61
+ }
62
+
63
+ export interface ImageCropperResult {
64
+ /** null = 用户未裁切(全图)。 */
65
+ crop: ImageCropRect | null;
66
+ rotateDegree: 0 | 90 | 180 | 270;
67
+ /**
68
+ * 水平镜像(左右翻转),缺省 false。随裁剪弹窗的翻转按钮加入契约。
69
+ *
70
+ * 只设「水平」一个布尔量即可表达全部 8 种朝向:垂直翻转 = 水平镜像后再转 180°
71
+ * (F_v = R(180)∘F_h),故弹窗里的「上下翻转」按钮由前端归一化成 flipHorizontal + rotateDegree
72
+ * 两个既有字段下发,契约面不再单开垂直档。与 rotateDegree 的作用顺序见 ImageCropRect 头注释。
73
+ */
74
+ flipHorizontal?: boolean;
75
+ mode: ImageCompressMode;
76
+ /** custom 档参数。 */
77
+ quality?: number;
78
+ format?: 'webp' | 'jpeg' | 'png';
79
+ /** 目标长边(等比缩),0/缺省=不限制。 */
80
+ targetMaxSide?: number;
81
+ /** 指定输出宽度(仅 options.resolution 场景),与 targetHeight 成对出现。 */
82
+ targetWidth?: number;
83
+ /** 指定输出高度(仅 options.resolution 场景),与 targetWidth 成对出现。 */
84
+ targetHeight?: number;
85
+ }
86
+
87
+ /** 宿主注入给插件的图片工具能力(挂 EditorHostBridge.imageTools)。 */
88
+ export interface ImageToolsClient {
89
+ /** 打开裁切弹窗;用户取消返回 null。 */
90
+ openCropper?(options: ImageCropperOptions): Promise<ImageCropperResult | null>;
91
+ }
package/src/index.ts ADDED
@@ -0,0 +1,118 @@
1
+ // @kimposoft/plugin-sdk —— Kimpo 插件前端契约的唯一真相来源。
2
+ // 宿主前端与各插件都依赖本包,彼此不互相 import,依赖单向无环。
3
+ // 与 Go 侧 SDK 对称:editor ↔ direction/editor,hooks ↔ direction/hooks。
4
+ export * from './editor';
5
+ export * from './hooks';
6
+ // 通用 surface 挂载契约(SurfaceType / SurfaceCreateInput / SurfaceMountResult / definePluginSurface)。
7
+ export * from './surface';
8
+ // 平台交互会话:资源绑定、Host 自动续租、插件零凭据的统一生命周期 handle。
9
+ export * from './interactive-session';
10
+ // 宿主 UI 服务总线(平台级 ui.* 能力域):表达式编辑器 / 通讯录选人器等常用界面由宿主渲染一次,
11
+ // 插件经 createHostUi(hostBridge) 命令式唤起,零 UI 代码。不属任何插件分类独占。
12
+ export * from './ui';
13
+ // 宿主 UI 服务总线 mock 工厂:createMockHostUi / createMockHostUiBridge,供插件在自己的
14
+ // playground / 单测里不启动宿主也能把交互跑通(confirm/cancel/not-wired 三档,用法见
15
+ // ui-mocks.ts 头注释)。
16
+ export * from './ui-mocks';
17
+ // 宿主设计数值(theme 能力)契约面:RGB / HostThemeTokens / HostTheme 类型 +
18
+ // readHostTheme / toCss 读取函数;只有类型与函数,不含任何数值常量。
19
+ export * from './theme';
20
+ // theme 能力 mock 工厂:createMockHostTheme(可手动触发变化,数值仅测试用),供插件单测 / playground 使用。
21
+ export * from './theme-mocks';
22
+ // 宿主 UI 服务总线四个服务的请求/结果夹具(纯 JSON、零函数),插件写测试可直接 import,
23
+ // 不必自己造一份合法的 request/result。
24
+ export * from './ui-fixtures';
25
+ // 多语言契约与两级查找 helper(HostI18n / createPluginI18n / COMMON_VOCABULARY),
26
+ // 插件自带语言包 miss 时回落宿主中央语言包。
27
+ export * from './i18n';
28
+ // page-slot 页面级插件契约(模板历史记录列表页):
29
+ // TemplateRecordsPageProps / PageRecordListClient / PageNavigationClient / PagePermissionClient。
30
+ export * from './page';
31
+ // 字段展示样式格式化纯函数:formatDisplayStyleValue / isDateTimeDisplayStyle /
32
+ // isNumericDisplayStyle,口径逐档对齐表格编辑器填报态单元格,供记录列表等其他消费方复用。
33
+ export * from './display-style';
34
+ // 附件值 → 地址纯函数:parseAttachmentItems / attachmentItemUrls / attachmentItemsSummary /
35
+ // isImageItem / isAttachmentField / isImageField / isImageDisplayStyle,表格编辑器候选、历史记录页、宿主内置
36
+ // 回退视图与视图设计器预览共用,各处不得自行拼接宿主图片 / 附件端点;地址自动携带查询上下文读票据(qt)。
37
+ export * from './attachment-url';
38
+ // 登录页插件(auth.login slot)前端契约:AuthKind / LoginMethod / LoginPageProps / LoginOutcome /
39
+ // AuthErrorCode / AuthLoginHostBridge / definePluginLoginSurface / QrCodeRenderer,
40
+ // 使用说明见 SDK 第三方指南 docs/third-party/auth-and-hooks.md。
41
+ export * from './auth';
42
+ // 图片工具前端契约:ImageCropRect / ImageCompressMode / ImageCropperOptions /
43
+ // ImageCropperResult / ImageToolsClient,挂 EditorHostBridge.imageTools。
44
+ export * from './image-tools';
45
+ // 组织架构取人前端契约(IM 前端插件等使用):OrgDept / OrgMember /
46
+ // OrgDirectoryClient,插件不碰组织表,薄封装宿主既有 IAM 接口。
47
+ export * from './org-directory';
48
+ // 消息与即时通讯引擎(消息引擎)正式分域业务契约与资产上传/鉴权预览能力。
49
+ // 根入口已有编辑器历史 AssetClient,故 IM 资产客户端在根入口显式别名;
50
+ // `@kimposoft/plugin-sdk/nahida-im` 子入口仍按正式契约导出 AssetClient 原名。
51
+ export type {
52
+ AssetClient as NahidaAssetClient,
53
+ AssetDownloadDescriptor,
54
+ AssetOpenDescriptor,
55
+ AssetPreviewKind,
56
+ AssetUploadInput,
57
+ AssetUploadTask,
58
+ NahidaAssetReference,
59
+ NahidaBusinessCard,
60
+ NahidaBusinessCardAction,
61
+ NahidaClientError,
62
+ NahidaConversation,
63
+ NahidaConversationClient,
64
+ NahidaConversationKind,
65
+ NahidaCursorPage,
66
+ NahidaCursorPageRequest,
67
+ NahidaErrorCode,
68
+ NahidaGroupClient,
69
+ NahidaGroupMember,
70
+ NahidaId,
71
+ NahidaImClient,
72
+ NahidaJsonObject,
73
+ NahidaJsonPrimitive,
74
+ NahidaJsonValue,
75
+ NahidaLogger,
76
+ NahidaMemberRole,
77
+ NahidaMemberSource,
78
+ NahidaMentionAll,
79
+ NahidaMentions,
80
+ NahidaMentionUser,
81
+ NahidaMessage,
82
+ NahidaMessageClient,
83
+ NahidaMessageContent,
84
+ NahidaMessageKind,
85
+ NahidaMessagePage,
86
+ NahidaNotificationClient,
87
+ NahidaOffsetPage,
88
+ NahidaPreferenceClient,
89
+ NahidaDndPreference,
90
+ NahidaCategoryPreference,
91
+ NahidaNotificationCategory,
92
+ NahidaPresenceClient,
93
+ NahidaPresenceMode,
94
+ NahidaPresenceStatus,
95
+ NahidaReaction,
96
+ NahidaSearchClient,
97
+ NahidaSequence,
98
+ NahidaSystemNotification,
99
+ NahidaTimeClient,
100
+ NahidaTimestamp,
101
+ NahidaUserSearchHit
102
+ } from './nahida-im';
103
+ // 消息引擎 WS 长连接前端契约:NahidaWSState /
104
+ // NahidaWSClient,插件经此复用宿主已持有的 WS 单例,不再自建独立连接。
105
+ export * from './nahida-ws';
106
+ export * from './oz-realtime';
107
+ // 平台级 hostCaps 白名单裁剪(SEC-012):WorkflowCapabilityError / pruneBridgeByCaps 等符号
108
+ // 是宿主 UI 服务、KimpoAI / IM 悬浮窗、动作设计器共用的平台级能力裁剪(非流程插件专属)。
109
+ export * from './host-caps';
110
+ // manifest capabilities.frontend.routes 的类型与自检。
111
+ export * from './frontend-routes';
112
+
113
+ // iframe 沙箱挂载档框架侧传输层
114
+ export * from './frame-transport';
115
+
116
+ // 打印方案 B 档前端契约:PrintModeBuildSpecContext / PrintJobSpec 类型与 definePrintModeBuildSpec
117
+ // (在沙箱框架内登记 buildSpec,宿主经框架桥 expose 调用)。
118
+ export * from './print';