@suwenguang/pi-feishu-bridge 0.0.0-stage → 0.6.2
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/.pi/extensions/feishu/index.ts +11 -0
- package/.pi/feishu/debug.pi.log +81 -0
- package/.pi/feishu/state.pi.json +12 -0
- package/README.md +210 -2
- package/package.json +57 -4
- package/src/adapters/pi/PiConversationRuntime.ts +1559 -0
- package/src/adapters/pi/index.ts +1169 -0
- package/src/adapters/pi/setup.ts +108 -0
- package/src/feishu/app-register.ts +50 -0
- package/src/feishu/ask.ts +388 -0
- package/src/feishu/attachment-processor.ts +198 -0
- package/src/feishu/attachments.ts +192 -0
- package/src/feishu/bridge-runtime.ts +129 -0
- package/src/feishu/bridge-store.ts +92 -0
- package/src/feishu/card-action-webhook.ts +141 -0
- package/src/feishu/card-actions.ts +241 -0
- package/src/feishu/card-builder.ts +277 -0
- package/src/feishu/cardkit-stream.ts +483 -0
- package/src/feishu/cards.ts +413 -0
- package/src/feishu/config.ts +427 -0
- package/src/feishu/daemon-spec.ts +43 -0
- package/src/feishu/debug.ts +51 -0
- package/src/feishu/dedupe-store.ts +150 -0
- package/src/feishu/delivery.ts +185 -0
- package/src/feishu/gateway-lock.ts +256 -0
- package/src/feishu/group-trigger.ts +128 -0
- package/src/feishu/image-send.ts +256 -0
- package/src/feishu/instance.ts +170 -0
- package/src/feishu/instances.ts +148 -0
- package/src/feishu/interactive-card.ts +236 -0
- package/src/feishu/learn-approval.ts +321 -0
- package/src/feishu/live-cards.ts +128 -0
- package/src/feishu/message-handler.ts +512 -0
- package/src/feishu/messages.ts +356 -0
- package/src/feishu/oversize-progress-card.ts +101 -0
- package/src/feishu/progress-channel.ts +154 -0
- package/src/feishu/progress-note.ts +371 -0
- package/src/feishu/prompt-timeout.ts +81 -0
- package/src/feishu/reply-card-options.ts +73 -0
- package/src/feishu/reply-card.ts +498 -0
- package/src/feishu/restart.ts +286 -0
- package/src/feishu/retry.ts +102 -0
- package/src/feishu/rich-text.ts +387 -0
- package/src/feishu/runtime-config.ts +286 -0
- package/src/feishu/runtime.ts +110 -0
- package/src/feishu/slash-commands.ts +239 -0
- package/src/feishu/thinking.ts +24 -0
- package/src/feishu/transport.ts +792 -0
- package/src/feishu/types.ts +183 -0
- package/src/feishu/ui-notify.ts +44 -0
- package/src/feishu/user-name.ts +121 -0
- package/src/feishu/workspace.ts +42 -0
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
import type { FeishuAttachment } from "./types.ts";
|
|
2
|
+
|
|
3
|
+
const INTERACTIVE_CARD_FALLBACK = "[Interactive Card]";
|
|
4
|
+
|
|
5
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
6
|
+
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
function readCardTemplateVariables(parsed: Record<string, unknown>): Map<string, string> {
|
|
10
|
+
const variables = new Map<string, string>();
|
|
11
|
+
const candidates = [parsed.variables, parsed.template_variable, parsed.template_variables];
|
|
12
|
+
for (const candidate of candidates) {
|
|
13
|
+
if (!isRecord(candidate)) continue;
|
|
14
|
+
for (const [key, value] of Object.entries(candidate)) {
|
|
15
|
+
if (typeof value === "string") variables.set(key, value);
|
|
16
|
+
else if (value != null && typeof value !== "object") variables.set(key, String(value));
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
return variables;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function applyCardTemplateVariables(text: string, variables: Map<string, string>): string {
|
|
23
|
+
if (variables.size === 0) return text;
|
|
24
|
+
return text.replace(/\$\{([A-Za-z0-9_.-]+)\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (match, a, b) => {
|
|
25
|
+
const variableName = typeof a === "string" ? a : b;
|
|
26
|
+
return variables.get(variableName) ?? match;
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function pushText(parts: string[], value: unknown, variables: Map<string, string>) {
|
|
31
|
+
if (typeof value !== "string") return;
|
|
32
|
+
const text = applyCardTemplateVariables(value, variables).trim();
|
|
33
|
+
if (text) parts.push(text);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function extractFromTextObject(textObj: unknown, variables: Map<string, string>): string | undefined {
|
|
37
|
+
if (!isRecord(textObj)) return undefined;
|
|
38
|
+
if (typeof textObj.content === "string") return applyCardTemplateVariables(textObj.content, variables);
|
|
39
|
+
if (typeof textObj.text === "string") return applyCardTemplateVariables(textObj.text, variables);
|
|
40
|
+
return undefined;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** 递归抽取卡片元素中的可读文本,并收集图片附件 */
|
|
44
|
+
export function extractInteractiveElementText(
|
|
45
|
+
element: unknown,
|
|
46
|
+
variables: Map<string, string>,
|
|
47
|
+
attachments: FeishuAttachment[],
|
|
48
|
+
depth = 0,
|
|
49
|
+
): string[] {
|
|
50
|
+
if (depth > 12 || !isRecord(element)) return [];
|
|
51
|
+
const parts: string[] = [];
|
|
52
|
+
const tag = typeof element.tag === "string" ? element.tag : "";
|
|
53
|
+
|
|
54
|
+
if (tag === "img" || tag === "image") {
|
|
55
|
+
const key = typeof element.img_key === "string" ? element.img_key : typeof element.image_key === "string" ? element.image_key : undefined;
|
|
56
|
+
if (key) attachments.push({ kind: "image", fileKey: key });
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
if (tag === "div" || tag === "markdown" || tag === "lark_md" || tag === "plain_text" || tag === "note") {
|
|
60
|
+
const direct = extractFromTextObject(element.text, variables);
|
|
61
|
+
if (direct) parts.push(direct);
|
|
62
|
+
if (typeof element.content === "string") pushText(parts, element.content, variables);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
if (tag === "button") {
|
|
66
|
+
const label = extractFromTextObject(element.text, variables);
|
|
67
|
+
if (label) parts.push(`[按钮] ${label}`);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
if (tag === "column_set" && Array.isArray(element.columns)) {
|
|
71
|
+
for (const column of element.columns) {
|
|
72
|
+
parts.push(...extractInteractiveElementText(column, variables, attachments, depth + 1));
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (Array.isArray(element.elements)) {
|
|
77
|
+
for (const child of element.elements) {
|
|
78
|
+
parts.push(...extractInteractiveElementText(child, variables, attachments, depth + 1));
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
if (Array.isArray(element.fields)) {
|
|
82
|
+
for (const field of element.fields) {
|
|
83
|
+
if (!isRecord(field)) continue;
|
|
84
|
+
const fieldText = extractFromTextObject(field.text, variables);
|
|
85
|
+
if (fieldText) parts.push(fieldText);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// schema 2.0 / 嵌套容器兜底
|
|
90
|
+
for (const key of ["body", "header", "card"]) {
|
|
91
|
+
if (isRecord(element[key])) {
|
|
92
|
+
parts.push(...extractInteractiveElementText(element[key], variables, attachments, depth + 1));
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return parts;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function readHeaderTitle(parsed: Record<string, unknown>, variables: Map<string, string>): string | undefined {
|
|
100
|
+
const header = isRecord(parsed.header) ? parsed.header : undefined;
|
|
101
|
+
if (!header) return undefined;
|
|
102
|
+
const title = extractFromTextObject(header.title, variables);
|
|
103
|
+
const subtitle = extractFromTextObject(header.subtitle, variables);
|
|
104
|
+
return [title, subtitle].filter(Boolean).join(" — ") || undefined;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function readElementArrays(parsed: Record<string, unknown>): unknown[][] {
|
|
108
|
+
const arrays: unknown[][] = [];
|
|
109
|
+
const body = isRecord(parsed.body) ? parsed.body : undefined;
|
|
110
|
+
for (const candidate of [parsed.elements, body?.elements]) {
|
|
111
|
+
if (Array.isArray(candidate)) arrays.push(candidate);
|
|
112
|
+
}
|
|
113
|
+
for (const candidate of [parsed.i18n_elements, body?.i18n_elements]) {
|
|
114
|
+
if (!isRecord(candidate)) continue;
|
|
115
|
+
// 优先中文
|
|
116
|
+
for (const locale of ["zh_cn", "en_us", ...Object.keys(candidate)]) {
|
|
117
|
+
const localeElements = candidate[locale];
|
|
118
|
+
if (Array.isArray(localeElements)) arrays.push(localeElements);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
return arrays;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* 将飞书 interactive 卡片 JSON 转为 agent 可读纯文本。
|
|
126
|
+
* 失败时返回 fallback,避免静默丢消息。
|
|
127
|
+
*/
|
|
128
|
+
export function extractTextFromInteractiveCard(
|
|
129
|
+
content: string,
|
|
130
|
+
options?: { maxChars?: number },
|
|
131
|
+
): { text: string; attachments: FeishuAttachment[] } {
|
|
132
|
+
const attachments: FeishuAttachment[] = [];
|
|
133
|
+
let parsed: unknown;
|
|
134
|
+
try {
|
|
135
|
+
parsed = JSON.parse(content || "{}");
|
|
136
|
+
} catch {
|
|
137
|
+
const fallback = content?.trim() ? content.trim().slice(0, options?.maxChars ?? 8000) : INTERACTIVE_CARD_FALLBACK;
|
|
138
|
+
return { text: fallback, attachments };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
// 部分事件 content 包一层 { type, data: { card } } 或 { card }
|
|
142
|
+
if (isRecord(parsed)) {
|
|
143
|
+
if (parsed.type === "interactive" && isRecord(parsed.card)) parsed = parsed.card;
|
|
144
|
+
else if (isRecord(parsed.card)) parsed = parsed.card;
|
|
145
|
+
else if (isRecord(parsed.data) && isRecord((parsed.data as Record<string, unknown>).card)) {
|
|
146
|
+
parsed = (parsed.data as Record<string, unknown>).card;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
if (!isRecord(parsed)) {
|
|
151
|
+
return { text: INTERACTIVE_CARD_FALLBACK, attachments };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const variables = readCardTemplateVariables(parsed);
|
|
155
|
+
const parts: string[] = [];
|
|
156
|
+
const header = readHeaderTitle(parsed, variables);
|
|
157
|
+
if (header) parts.push(header);
|
|
158
|
+
|
|
159
|
+
for (const elements of readElementArrays(parsed)) {
|
|
160
|
+
for (const element of elements) {
|
|
161
|
+
parts.push(...extractInteractiveElementText(element, variables, attachments));
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// 再扫一遍整棵树,防止 schema 变体漏抽
|
|
166
|
+
if (!parts.length) {
|
|
167
|
+
parts.push(...extractInteractiveElementText(parsed, variables, attachments));
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
let text = parts.map((p) => p.trim()).filter(Boolean).join("\n").trim();
|
|
171
|
+
if (!text) {
|
|
172
|
+
// 最后兜底:截断原始 JSON,便于排查
|
|
173
|
+
const raw = JSON.stringify(parsed);
|
|
174
|
+
text = `${INTERACTIVE_CARD_FALLBACK}\n${raw.slice(0, 1500)}`;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
const maxChars = options?.maxChars ?? 12000;
|
|
178
|
+
if (text.length > maxChars) text = `${text.slice(0, maxChars)}\n…(truncated)`;
|
|
179
|
+
return { text, attachments };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** 将任意消息类型 content 尽量解析为文本(用于父消息展开) */
|
|
183
|
+
export function extractTextFromMsgType(
|
|
184
|
+
msgType: string,
|
|
185
|
+
content: string,
|
|
186
|
+
botOpenId?: string,
|
|
187
|
+
): { text: string; attachments: FeishuAttachment[] } {
|
|
188
|
+
const attachments: FeishuAttachment[] = [];
|
|
189
|
+
if (msgType === "interactive") {
|
|
190
|
+
return extractTextFromInteractiveCard(content);
|
|
191
|
+
}
|
|
192
|
+
try {
|
|
193
|
+
const json = JSON.parse(content || "{}");
|
|
194
|
+
if (msgType === "text") {
|
|
195
|
+
let text = String(json.text || "");
|
|
196
|
+
if (botOpenId) text = text.replace(new RegExp(`@?${botOpenId}`, "g"), "");
|
|
197
|
+
return { text: text.trim(), attachments };
|
|
198
|
+
}
|
|
199
|
+
if (msgType === "post") {
|
|
200
|
+
const post = json.post || json;
|
|
201
|
+
const locale = post.zh_cn || post.en_us || Object.values(post).find((v) => isRecord(v) && Array.isArray((v as any).content));
|
|
202
|
+
const parts: string[] = [];
|
|
203
|
+
if (isRecord(locale)) {
|
|
204
|
+
if (typeof locale.title === "string" && locale.title.trim()) parts.push(locale.title.trim());
|
|
205
|
+
for (const para of (locale.content as unknown[]) || []) {
|
|
206
|
+
if (!Array.isArray(para)) continue;
|
|
207
|
+
for (const elem of para) {
|
|
208
|
+
if (!isRecord(elem)) continue;
|
|
209
|
+
if ((elem.tag === "text" || elem.tag === "a") && typeof elem.text === "string") parts.push(elem.text);
|
|
210
|
+
if (elem.tag === "at") parts.push(`@${typeof elem.user_name === "string" ? elem.user_name : "user"}`);
|
|
211
|
+
if ((elem.tag === "img" || elem.tag === "image") && typeof elem.image_key === "string") {
|
|
212
|
+
attachments.push({ kind: "image", fileKey: elem.image_key });
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
return { text: parts.join("").trim(), attachments };
|
|
218
|
+
}
|
|
219
|
+
if (msgType === "image" && typeof json.image_key === "string") {
|
|
220
|
+
attachments.push({ kind: "image", fileKey: json.image_key });
|
|
221
|
+
return { text: "", attachments };
|
|
222
|
+
}
|
|
223
|
+
if (msgType === "file" && typeof json.file_key === "string") {
|
|
224
|
+
attachments.push({
|
|
225
|
+
kind: "file",
|
|
226
|
+
fileKey: json.file_key,
|
|
227
|
+
fileName: typeof json.file_name === "string" ? json.file_name : undefined,
|
|
228
|
+
});
|
|
229
|
+
return { text: "", attachments };
|
|
230
|
+
}
|
|
231
|
+
} catch {
|
|
232
|
+
// fallthrough
|
|
233
|
+
}
|
|
234
|
+
return { text: content?.trim() ? content.trim().slice(0, 2000) : `[${msgType}]`, attachments };
|
|
235
|
+
}
|
|
236
|
+
|
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 进化审批(飞书「审批」应用 v4)——「/learn 应用」落地前的授权通道。
|
|
3
|
+
*
|
|
4
|
+
* 背景:进化(改 `.pi/` 下的规范与代码)不再靠「只能在某个平台做」来限制,
|
|
5
|
+
* 而是靠**飞书审批**:任何人都可以发起进化,但改动必须等审批通过后才落地。
|
|
6
|
+
* 审批是飞书审批应用里的真实审批单,审批人在飞书里点「通过 / 驳回」。
|
|
7
|
+
*
|
|
8
|
+
* 分工:
|
|
9
|
+
* - 本模块只管「审批单」这一件事:查定义拿表单控件 → 创建实例 → 查询状态 → 返回终态。
|
|
10
|
+
* - 「谁在哪个会话发起」由适配器层(PiConversationRuntime)负责,本模块不碰会话。
|
|
11
|
+
*
|
|
12
|
+
* 调用形态(重要):
|
|
13
|
+
* - `create()` 只建单、**立即返回实例号**,不轮询;`query()` 只查一次状态。
|
|
14
|
+
* 工具侧对应两个工具(submit / status),避免把「等审批人点」挂在一次工具调用上。
|
|
15
|
+
* - `request()` 是**旧调用形态**(建单 + 轮询到终态),仅为兼容保留;新代码不要再走它——
|
|
16
|
+
* 审批人要多久才点没有上限,一个 execute 里 await 到超时会把整轮对话卡死。
|
|
17
|
+
*
|
|
18
|
+
* 关键设计:审批人与表单结构都在**审批定义**里,不在代码里。
|
|
19
|
+
* 所以必须先 GET 定义拿到表单控件 id,再按它构造 form,才能适配任意自建审批。
|
|
20
|
+
*/
|
|
21
|
+
import { randomUUID } from "node:crypto";
|
|
22
|
+
import type { LearnApprovalConfig } from "./types.ts";
|
|
23
|
+
|
|
24
|
+
/** 审批状态(对外统一口径;未知值一律按在途处理,避免误判成「已通过」) */
|
|
25
|
+
export type LearnApprovalStatus = "PENDING" | "APPROVED" | "REJECTED" | "CANCELED" | "TIMEOUT";
|
|
26
|
+
|
|
27
|
+
/** 等审批的默认超时:10 分钟(查询式询问,一个实例超时不影响 feishu_ask 的等待) */
|
|
28
|
+
export const LEARN_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
|
|
29
|
+
|
|
30
|
+
/** 轮询间隔默认 5 秒(审批查询接口限频 100 次/分钟,够用) */
|
|
31
|
+
export const LEARN_APPROVAL_POLL_MS = 5 * 1000;
|
|
32
|
+
|
|
33
|
+
/** 可承载候选点正文的控件类型,按优先级排列:多行文本最适合放清单,其次单行输入 */
|
|
34
|
+
const TEXT_WIDGET_TYPES = ["textarea", "input"];
|
|
35
|
+
|
|
36
|
+
export type LearnApprovalResult = {
|
|
37
|
+
status: LearnApprovalStatus;
|
|
38
|
+
/** 审批实例 code,用于人工排查 */
|
|
39
|
+
instanceCode?: string;
|
|
40
|
+
/** 补充说明(超时/失败原因) */
|
|
41
|
+
detail?: string;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/** 「只提交」的结果:要么拿到实例号,要么给出为什么没建出来的原因 */
|
|
45
|
+
export type LearnApprovalSubmitResult = {
|
|
46
|
+
ok: boolean;
|
|
47
|
+
/** 已受理时的审批实例 code;后续 query() 用同一个号续查 */
|
|
48
|
+
instanceCode?: string;
|
|
49
|
+
/** ok=false 时的原因(拿不到发起人 / 定义缺控件 / 接口失败) */
|
|
50
|
+
detail?: string;
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/** 只用到 request 方法,便于单测注入 fake */
|
|
54
|
+
export interface LearnApprovalApi {
|
|
55
|
+
request(args: { url: string; method: string; params?: unknown; data?: unknown }): Promise<any>;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* 飞书实例 status → 本模块状态。
|
|
60
|
+
* 飞书取值:PENDING / APPROVED / REJECTED / CANCELED / DELETED。
|
|
61
|
+
* 认不出的值按 PENDING 处理:宁可继续等,也不能把「不知道」当成「已批准」。
|
|
62
|
+
*/
|
|
63
|
+
export function mapInstanceStatus(raw: unknown): LearnApprovalStatus {
|
|
64
|
+
const value = String(raw ?? "").trim().toUpperCase();
|
|
65
|
+
if (value === "APPROVED") return "APPROVED";
|
|
66
|
+
if (value === "REJECTED") return "REJECTED";
|
|
67
|
+
if (value === "CANCELED" || value === "CANCELLED" || value === "DELETED") return "CANCELED";
|
|
68
|
+
return "PENDING";
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* 从审批定义里挑一个能填正文的文本控件。
|
|
73
|
+
*
|
|
74
|
+
* 飞书返回的定义里 `form` 是一段 JSON 字符串,形如
|
|
75
|
+
* `{"widgets":[{"id":"widget1","type":"textarea",...}]}`;
|
|
76
|
+
* 但不同版本/不同建法可能直接给数组,这里两种都认。
|
|
77
|
+
*/
|
|
78
|
+
export function pickFormWidget(definition: any): { id: string; type: string } | undefined {
|
|
79
|
+
const widgets = parseWidgets(definition);
|
|
80
|
+
if (!widgets.length) return undefined;
|
|
81
|
+
// 按 TEXT_WIDGET_TYPES 的优先级挑:textarea 优先于 input,都不匹配才退第一个控件
|
|
82
|
+
let chosen: any;
|
|
83
|
+
for (const type of TEXT_WIDGET_TYPES) {
|
|
84
|
+
chosen = widgets.find((w) => String(w?.type ?? "").toLowerCase() === type);
|
|
85
|
+
if (chosen) break;
|
|
86
|
+
}
|
|
87
|
+
chosen = chosen ?? widgets[0];
|
|
88
|
+
const id = String(chosen?.id ?? "").trim();
|
|
89
|
+
if (!id) return undefined;
|
|
90
|
+
return { id, type: String(chosen?.type ?? "textarea") };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** 把定义里的 form 字段解析成控件数组(容错:JSON 字符串 / 数组 / {widgets:[]} 都认) */
|
|
94
|
+
function parseWidgets(definition: any): any[] {
|
|
95
|
+
const raw = definition?.form ?? definition?.data?.form;
|
|
96
|
+
let parsed: any = raw;
|
|
97
|
+
if (typeof raw === "string") {
|
|
98
|
+
try {
|
|
99
|
+
parsed = JSON.parse(raw);
|
|
100
|
+
} catch {
|
|
101
|
+
return [];
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
if (Array.isArray(parsed)) return parsed;
|
|
105
|
+
if (Array.isArray(parsed?.widgets)) return parsed.widgets;
|
|
106
|
+
return [];
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* 构造创建审批实例所需的 form 字段。
|
|
111
|
+
*
|
|
112
|
+
* 飞书要求 form 是**压缩后的 JSON 字符串**,不是对象。
|
|
113
|
+
* 控件类型沿用定义里的原类型,避免类型不匹配被拒。
|
|
114
|
+
*/
|
|
115
|
+
export function buildInstanceForm(widget: { id: string; type: string }, body: string): string {
|
|
116
|
+
return JSON.stringify([{ id: widget.id, type: widget.type, value: body }]);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** 把审批结果转成给模型看的文本(模型据此决定是否动手) */
|
|
120
|
+
export function formatApprovalOutcome(result: LearnApprovalResult): string {
|
|
121
|
+
const code = result.instanceCode ? `(审批实例 ${result.instanceCode})` : "";
|
|
122
|
+
switch (result.status) {
|
|
123
|
+
case "APPROVED":
|
|
124
|
+
return `审批已通过${code}:可以按被授权的候选点落地。落地完成后必须物理删除对应反馈文件。`;
|
|
125
|
+
case "REJECTED":
|
|
126
|
+
return `审批被驳回${code}:一个字都不要改。等审批人说明原因。`;
|
|
127
|
+
case "CANCELED":
|
|
128
|
+
return `审批已被撤回/删除${code}:一个字都不要改。`;
|
|
129
|
+
case "TIMEOUT":
|
|
130
|
+
// 超时 ≠ 否决:单子大概率还在飞书里等审批人点。重发会造出第二张单(uuid 幂等键只防网络重试),
|
|
131
|
+
// 所以这里只让模型「拿实例号续查」,绝不放行。
|
|
132
|
+
return `等待审批超时${code}:${result.detail ?? "审批人未在超时前处理"}。`
|
|
133
|
+
+ `实例可能仍在审批中,**不要重发**,隔一会儿用 feishu_learn_approval_status 传同一实例号续查;`
|
|
134
|
+
+ "拿到 APPROVED 之前一个字都不要改。";
|
|
135
|
+
default:
|
|
136
|
+
return `审批仍在进行中${code}:不要动手,隔一会儿用 feishu_learn_approval_status 传同一实例号续查;`
|
|
137
|
+
+ `PENDING 不等于通过,一个字都不要改。${result.detail ? `(${result.detail})` : ""}`;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** 把「只提交」的结果转成给模型看的文本(模型据此知道去续查,而不是等着或动手) */
|
|
142
|
+
export function formatSubmitOutcome(result: LearnApprovalSubmitResult): string {
|
|
143
|
+
if (!result.ok || !result.instanceCode) {
|
|
144
|
+
return `提交进化审批失败:${result.detail ?? "未知原因"}。一个字都不要改,把原因告诉用户。`;
|
|
145
|
+
}
|
|
146
|
+
return `审批已提交(审批实例 ${result.instanceCode}):请在飞书里点「通过」。`
|
|
147
|
+
+ "拿到 APPROVED 之前一个字都不要改;"
|
|
148
|
+
+ "结果用 feishu_learn_approval_status 传这个实例号续查,不要重复提交(重复提交会造出第二张单)。";
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
export interface LearnApprovalClientDeps {
|
|
152
|
+
api: LearnApprovalApi;
|
|
153
|
+
config: LearnApprovalConfig;
|
|
154
|
+
/** 注入 sleep,单测时可把轮询加速 */
|
|
155
|
+
sleep?: (ms: number) => Promise<void>;
|
|
156
|
+
now?: () => number;
|
|
157
|
+
log?: (event: string, data?: unknown) => void;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
export class LearnApprovalClient {
|
|
161
|
+
private readonly api: LearnApprovalApi;
|
|
162
|
+
private readonly config: LearnApprovalConfig;
|
|
163
|
+
private readonly sleep: (ms: number) => Promise<void>;
|
|
164
|
+
private readonly now: () => number;
|
|
165
|
+
private readonly log: (event: string, data?: unknown) => void;
|
|
166
|
+
private widget: { id: string; type: string } | undefined;
|
|
167
|
+
|
|
168
|
+
constructor(deps: LearnApprovalClientDeps) {
|
|
169
|
+
this.api = deps.api;
|
|
170
|
+
this.config = deps.config;
|
|
171
|
+
this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
172
|
+
this.now = deps.now ?? (() => Date.now());
|
|
173
|
+
this.log = deps.log ?? (() => {});
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
private get timeoutMs() {
|
|
177
|
+
return (this.config.timeoutSec ?? LEARN_APPROVAL_TIMEOUT_MS / 1000) * 1000;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
private get pollMs() {
|
|
181
|
+
return (this.config.pollIntervalSec ?? LEARN_APPROVAL_POLL_MS / 1000) * 1000;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** 查审批定义拿表单控件(缓存:审批定义很少变,每次都查会白吃限频) */
|
|
185
|
+
private async resolveWidget(): Promise<{ id: string; type: string }> {
|
|
186
|
+
if (this.widget) return this.widget;
|
|
187
|
+
const res = await this.api.request({
|
|
188
|
+
url: `/open-apis/approval/v4/approvals/${encodeURIComponent(this.config.approvalCode)}`,
|
|
189
|
+
method: "GET",
|
|
190
|
+
});
|
|
191
|
+
const widget = pickFormWidget(res?.data ?? res);
|
|
192
|
+
if (!widget) {
|
|
193
|
+
throw new Error(
|
|
194
|
+
"审批定义里找不到可填写的文本控件:请在飞书审批后台给该审批加一个「多行文本」控件后重试。",
|
|
195
|
+
);
|
|
196
|
+
}
|
|
197
|
+
this.widget = widget;
|
|
198
|
+
return widget;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* 只提交:查定义 → 建实例 → **立即返回实例号,不轮询、不等待**。
|
|
203
|
+
* 失败一律以 ok=false + detail 返回(不抛错),让上层把原因原样讲给用户。
|
|
204
|
+
*/
|
|
205
|
+
async create(input: { body: string; applicantOpenId: string }): Promise<LearnApprovalSubmitResult> {
|
|
206
|
+
const applicant = String(input.applicantOpenId ?? "").trim();
|
|
207
|
+
if (!applicant) {
|
|
208
|
+
return { ok: false, detail: "拿不到发起人的 open_id,无法发起审批。" };
|
|
209
|
+
}
|
|
210
|
+
let widget: { id: string; type: string };
|
|
211
|
+
try {
|
|
212
|
+
widget = await this.resolveWidget();
|
|
213
|
+
} catch (error) {
|
|
214
|
+
return { ok: false, detail: error instanceof Error ? error.message : String(error) };
|
|
215
|
+
}
|
|
216
|
+
let created: any;
|
|
217
|
+
try {
|
|
218
|
+
created = await this.api.request({
|
|
219
|
+
url: "/open-apis/approval/v4/instances",
|
|
220
|
+
method: "POST",
|
|
221
|
+
data: {
|
|
222
|
+
approval_code: this.config.approvalCode,
|
|
223
|
+
open_id: applicant,
|
|
224
|
+
form: buildInstanceForm(widget, input.body),
|
|
225
|
+
// 幂等键:同一 uuid 只会生成一个实例(重复提交返回 60012),避免网络重试造出两张单
|
|
226
|
+
uuid: randomUUID(),
|
|
227
|
+
},
|
|
228
|
+
});
|
|
229
|
+
} catch (error) {
|
|
230
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
231
|
+
this.log("feishu.learn_approval.create_failed", { applicant, error: message });
|
|
232
|
+
return { ok: false, detail: `创建审批实例失败:${message}` };
|
|
233
|
+
}
|
|
234
|
+
const instanceCode = String(created?.data?.instance_code ?? created?.instance_code ?? "").trim();
|
|
235
|
+
if (!instanceCode) {
|
|
236
|
+
return { ok: false, detail: `创建审批实例失败:${summarize(created)}` };
|
|
237
|
+
}
|
|
238
|
+
this.log("feishu.learn_approval.created", { instanceCode, applicant });
|
|
239
|
+
return { ok: true, instanceCode };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* 只查一次状态:给「提交后用实例号续查」用,**不轮询、不阻塞**。
|
|
244
|
+
* 查询失败按在途(PENDING)返回——「查不到」绝不等于「已通过」。
|
|
245
|
+
*/
|
|
246
|
+
async query(instanceCode: string): Promise<LearnApprovalResult> {
|
|
247
|
+
const code = String(instanceCode ?? "").trim();
|
|
248
|
+
if (!code) {
|
|
249
|
+
return { status: "PENDING", detail: "缺少审批实例号,无法查询。" };
|
|
250
|
+
}
|
|
251
|
+
try {
|
|
252
|
+
const res = await this.api.request({
|
|
253
|
+
url: `/open-apis/approval/v4/instances/${encodeURIComponent(code)}`,
|
|
254
|
+
method: "GET",
|
|
255
|
+
});
|
|
256
|
+
const status = mapInstanceStatus(res?.data?.status ?? res?.status);
|
|
257
|
+
this.log("feishu.learn_approval.queried", { instanceCode: code, status });
|
|
258
|
+
return { status, instanceCode: code };
|
|
259
|
+
} catch (error) {
|
|
260
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
261
|
+
this.log("feishu.learn_approval.query_failed", { instanceCode: code, error: message });
|
|
262
|
+
return { status: "PENDING", instanceCode: code, detail: `查询审批状态失败:${message}` };
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* 【旧形态,保留兼容】发起一次进化审批并轮询到终态。
|
|
268
|
+
* 新代码请用 create() + query():本方法会把调用方卡在等待上(最长 timeoutSec 秒)。
|
|
269
|
+
* 返回 APPROVED 才允许落地;其余一律不许动文件。
|
|
270
|
+
*/
|
|
271
|
+
async request(input: { body: string; applicantOpenId: string }): Promise<LearnApprovalResult> {
|
|
272
|
+
const applicant = String(input.applicantOpenId ?? "").trim();
|
|
273
|
+
if (!applicant) {
|
|
274
|
+
return { status: "CANCELED", detail: "拿不到发起人的 open_id,无法发起审批。" };
|
|
275
|
+
}
|
|
276
|
+
const created = await this.create(input);
|
|
277
|
+
if (!created.ok || !created.instanceCode) {
|
|
278
|
+
throw new Error(created.detail ?? "创建审批实例失败");
|
|
279
|
+
}
|
|
280
|
+
return this.poll(created.instanceCode);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/** 轮询审批状态直到终态或超时 */
|
|
284
|
+
private async poll(instanceCode: string): Promise<LearnApprovalResult> {
|
|
285
|
+
const deadline = this.now() + this.timeoutMs;
|
|
286
|
+
while (this.now() < deadline) {
|
|
287
|
+
await this.sleep(this.pollMs);
|
|
288
|
+
let status: LearnApprovalStatus;
|
|
289
|
+
try {
|
|
290
|
+
const res = await this.api.request({
|
|
291
|
+
url: `/open-apis/approval/v4/instances/${encodeURIComponent(instanceCode)}`,
|
|
292
|
+
method: "GET",
|
|
293
|
+
});
|
|
294
|
+
status = mapInstanceStatus(res?.data?.status ?? res?.status);
|
|
295
|
+
} catch (error) {
|
|
296
|
+
// 单次查询失败不结束等待:审批可能已经通过,下一个周期再拿
|
|
297
|
+
this.log("feishu.learn_approval.poll_failed", {
|
|
298
|
+
instanceCode,
|
|
299
|
+
error: error instanceof Error ? error.message : String(error),
|
|
300
|
+
});
|
|
301
|
+
continue;
|
|
302
|
+
}
|
|
303
|
+
this.log("feishu.learn_approval.poll", { instanceCode, status });
|
|
304
|
+
if (status !== "PENDING") return { status, instanceCode };
|
|
305
|
+
}
|
|
306
|
+
return {
|
|
307
|
+
status: "TIMEOUT",
|
|
308
|
+
instanceCode,
|
|
309
|
+
detail: `超过 ${Math.round(this.timeoutMs / 1000)} 秒仍未审批`,
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
function summarize(res: any): string {
|
|
315
|
+
try {
|
|
316
|
+
const text = JSON.stringify(res);
|
|
317
|
+
return text.length > 300 ? `${text.slice(0, 300)}…` : text;
|
|
318
|
+
} catch {
|
|
319
|
+
return String(res);
|
|
320
|
+
}
|
|
321
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 「进行中」卡片的进程级登记表 + 进程退出收尾。
|
|
3
|
+
*
|
|
4
|
+
* 背景(2026-10-14 生产事故):重启桥接 daemon 时进程被 SIGTERM 直接终结,
|
|
5
|
+
* 没有任何人给那张「回复中」的卡片收尾,飞书侧就永久停在「正在回复…」——
|
|
6
|
+
* 用户以为任务还在跑,其实进程早就没了。
|
|
7
|
+
* 「延迟到回复发完再重启」只能降低概率(回复没写完照样被杀),
|
|
8
|
+
* 收尾才是确定性兜底:退出前把在册卡片翻成「已停止」并写明原因。
|
|
9
|
+
*/
|
|
10
|
+
import type { ReplyCardFinalStatus } from "./card-builder.ts";
|
|
11
|
+
import { debugLog } from "./debug.ts";
|
|
12
|
+
|
|
13
|
+
/** 收尾只需用到这两个成员,避免为此依赖具体的 ReplyCard 实现 */
|
|
14
|
+
export type LiveCardSink = {
|
|
15
|
+
readonly runId: string;
|
|
16
|
+
finish(status: ReplyCardFinalStatus, note?: string): Promise<void>;
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
/** 默认文案:必须让用户知道「不是卡住了,是服务重启了,重发即可」 */
|
|
20
|
+
export const INTERRUPTED_NOTE = "服务重启中,本轮回复已中断,请重发这条消息";
|
|
21
|
+
|
|
22
|
+
const live = new Set<LiveCardSink>();
|
|
23
|
+
|
|
24
|
+
export function registerLiveCard(sink: LiveCardSink): void {
|
|
25
|
+
live.add(sink);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function unregisterLiveCard(sink: LiveCardSink): void {
|
|
29
|
+
live.delete(sink);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function liveCardCount(): number {
|
|
33
|
+
return live.size;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** 只测试用:清空登记表,避免用例之间互相污染 */
|
|
37
|
+
export function resetLiveCards(): void {
|
|
38
|
+
live.clear();
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function withTimeout(task: Promise<unknown>, ms: number): Promise<boolean> {
|
|
42
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
43
|
+
try {
|
|
44
|
+
await Promise.race([
|
|
45
|
+
task,
|
|
46
|
+
new Promise((_, reject) => {
|
|
47
|
+
timer = setTimeout(() => reject(new Error(`卡片收尾超时(${ms}ms)`)), ms);
|
|
48
|
+
}),
|
|
49
|
+
]);
|
|
50
|
+
return true;
|
|
51
|
+
} catch (error) {
|
|
52
|
+
debugLog("feishu.live_cards.finish_error", {
|
|
53
|
+
error: error instanceof Error ? error.message : String(error),
|
|
54
|
+
});
|
|
55
|
+
return false;
|
|
56
|
+
} finally {
|
|
57
|
+
if (timer) clearTimeout(timer);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* 把在册卡片全部收尾,返回成功条数。
|
|
63
|
+
*
|
|
64
|
+
* 先清册再收尾:收尾回调里可能又触发事件,重复进入会互相打架。
|
|
65
|
+
* 单张卡超时/报错都不影响其他卡(退出路径上宁可少收一张,不能挂住不退)。
|
|
66
|
+
*/
|
|
67
|
+
export async function finishLiveCards(
|
|
68
|
+
note: string = INTERRUPTED_NOTE,
|
|
69
|
+
timeoutMs = 2500,
|
|
70
|
+
): Promise<number> {
|
|
71
|
+
const pending = [...live];
|
|
72
|
+
live.clear();
|
|
73
|
+
if (pending.length === 0) return 0;
|
|
74
|
+
console.error(`[feishu] 进程退出前收尾在册卡片 ${pending.length} 张`);
|
|
75
|
+
const results = await Promise.all(
|
|
76
|
+
pending.map((card) => withTimeout(card.finish("stopped", note), timeoutMs)),
|
|
77
|
+
);
|
|
78
|
+
const ok = results.filter(Boolean).length;
|
|
79
|
+
debugLog("feishu.live_cards.finished_on_exit", { total: pending.length, ok, note });
|
|
80
|
+
return ok;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export type ExitFlushOptions = {
|
|
84
|
+
note?: string;
|
|
85
|
+
timeoutMs?: number;
|
|
86
|
+
exit?: (code: number) => void;
|
|
87
|
+
terminate?: boolean;
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
/** 信号处理逻辑,抽成纯函数便于单测(不必真给进程发信号) */
|
|
91
|
+
export function createExitHandler(options: ExitFlushOptions = {}): () => void {
|
|
92
|
+
const { note = INTERRUPTED_NOTE, timeoutMs = 2500, exit = (code) => process.exit(code), terminate = true } = options;
|
|
93
|
+
return () => {
|
|
94
|
+
void (async () => {
|
|
95
|
+
try {
|
|
96
|
+
await finishLiveCards(note, timeoutMs);
|
|
97
|
+
} catch (error) {
|
|
98
|
+
// 退出路径上绝不向上抛:抛出去就没人调 exit 了,进程会变成杀不死的僵尸
|
|
99
|
+
debugLog("feishu.live_cards.exit_flush_failed", {
|
|
100
|
+
error: error instanceof Error ? error.message : String(error),
|
|
101
|
+
});
|
|
102
|
+
} finally {
|
|
103
|
+
if (terminate) exit(0);
|
|
104
|
+
}
|
|
105
|
+
})();
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
let installed = false;
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* 挂 SIGTERM / SIGINT 收尾(**只挂一次**:扩展模块可能被同进程重复加载)。
|
|
113
|
+
*
|
|
114
|
+
* 注意 `process.on(signal)` 会取消默认终止行为,所以 handler 里必须自己 exit;
|
|
115
|
+
* createExitHandler 用 finally 保证这一点。
|
|
116
|
+
*/
|
|
117
|
+
export function installExitFlush(options: ExitFlushOptions & { signals?: NodeJS.Signals[] } = {}): void {
|
|
118
|
+
if (installed) return;
|
|
119
|
+
installed = true;
|
|
120
|
+
const { signals = ["SIGTERM", "SIGINT"], ...rest } = options;
|
|
121
|
+
const handler = createExitHandler(rest);
|
|
122
|
+
for (const signal of signals) {
|
|
123
|
+
process.on(signal, () => {
|
|
124
|
+
console.error(`[feishu] 收到 ${signal},开始退出收尾`);
|
|
125
|
+
handler();
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
}
|