@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.
Files changed (52) hide show
  1. package/.pi/extensions/feishu/index.ts +11 -0
  2. package/.pi/feishu/debug.pi.log +81 -0
  3. package/.pi/feishu/state.pi.json +12 -0
  4. package/README.md +210 -2
  5. package/package.json +57 -4
  6. package/src/adapters/pi/PiConversationRuntime.ts +1559 -0
  7. package/src/adapters/pi/index.ts +1169 -0
  8. package/src/adapters/pi/setup.ts +108 -0
  9. package/src/feishu/app-register.ts +50 -0
  10. package/src/feishu/ask.ts +388 -0
  11. package/src/feishu/attachment-processor.ts +198 -0
  12. package/src/feishu/attachments.ts +192 -0
  13. package/src/feishu/bridge-runtime.ts +129 -0
  14. package/src/feishu/bridge-store.ts +92 -0
  15. package/src/feishu/card-action-webhook.ts +141 -0
  16. package/src/feishu/card-actions.ts +241 -0
  17. package/src/feishu/card-builder.ts +277 -0
  18. package/src/feishu/cardkit-stream.ts +483 -0
  19. package/src/feishu/cards.ts +413 -0
  20. package/src/feishu/config.ts +427 -0
  21. package/src/feishu/daemon-spec.ts +43 -0
  22. package/src/feishu/debug.ts +51 -0
  23. package/src/feishu/dedupe-store.ts +150 -0
  24. package/src/feishu/delivery.ts +185 -0
  25. package/src/feishu/gateway-lock.ts +256 -0
  26. package/src/feishu/group-trigger.ts +128 -0
  27. package/src/feishu/image-send.ts +256 -0
  28. package/src/feishu/instance.ts +170 -0
  29. package/src/feishu/instances.ts +148 -0
  30. package/src/feishu/interactive-card.ts +236 -0
  31. package/src/feishu/learn-approval.ts +321 -0
  32. package/src/feishu/live-cards.ts +128 -0
  33. package/src/feishu/message-handler.ts +512 -0
  34. package/src/feishu/messages.ts +356 -0
  35. package/src/feishu/oversize-progress-card.ts +101 -0
  36. package/src/feishu/progress-channel.ts +154 -0
  37. package/src/feishu/progress-note.ts +371 -0
  38. package/src/feishu/prompt-timeout.ts +81 -0
  39. package/src/feishu/reply-card-options.ts +73 -0
  40. package/src/feishu/reply-card.ts +498 -0
  41. package/src/feishu/restart.ts +286 -0
  42. package/src/feishu/retry.ts +102 -0
  43. package/src/feishu/rich-text.ts +387 -0
  44. package/src/feishu/runtime-config.ts +286 -0
  45. package/src/feishu/runtime.ts +110 -0
  46. package/src/feishu/slash-commands.ts +239 -0
  47. package/src/feishu/thinking.ts +24 -0
  48. package/src/feishu/transport.ts +792 -0
  49. package/src/feishu/types.ts +183 -0
  50. package/src/feishu/ui-notify.ts +44 -0
  51. package/src/feishu/user-name.ts +121 -0
  52. package/src/feishu/workspace.ts +42 -0
@@ -0,0 +1,256 @@
1
+ /**
2
+ * 飞书「发图片」能力 —— 之前桥接只会收图,不会发图。
3
+ *
4
+ * 触发方式:模型在正文里写 `![说明](/绝对/路径.png)`(或相对工作区路径),
5
+ * 回复收尾时扫出来逐张上传并发送。这样 agent 生成/截图后不用让用户回电脑找文件。
6
+ *
7
+ * 飞书侧两步:
8
+ * 1. POST /open-apis/im/v1/images(multipart,image_type=message)→ image_key
9
+ * 2. POST /open-apis/im/v1/messages,msg_type=image,content={"image_key":...}
10
+ * 需要的应用权限:「上传图片」(im:resource)。
11
+ */
12
+ import { existsSync, readFileSync, statSync } from "node:fs";
13
+ import { extname, isAbsolute, resolve } from "node:path";
14
+ import { debugLog } from "./debug.ts";
15
+
16
+ /** 能发出去的图片扩展名(飞书 image 消息支持的类型) */
17
+ const SUPPORTED_IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"]);
18
+
19
+ /** 单张上限:飞书上传接口限制 10MB,超了直接跳过,不发报错卡 */
20
+ const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
21
+
22
+ /** 一轮最多发几张 —— 防止正文里一堆路径把消息刷屏 */
23
+ export const MAX_LOCAL_IMAGES_PER_TURN = 5;
24
+
25
+ export type LocalImageRef = { path: string; alt?: string };
26
+
27
+ /**
28
+ * 发图目标。
29
+ *
30
+ * `replyInThread` 只在**话题群**为 true:飞书的 reply 接口默认把回复挂在群主消息流里,
31
+ * 不带 `reply_in_thread` 的图片会跑到话题外,用户在自己的话题里根本看不到
32
+ * (2026-10-29 实测:文字卡片在话题内、图却落在群里,用户连问两次「图你没发我」)。
33
+ */
34
+ export type ImageTarget = { replyToMessageId?: string; chatId?: string; replyInThread?: boolean };
35
+
36
+ /**
37
+ * 从正文里抽出「本地图片」引用。
38
+ *
39
+ * 只认 markdown 图片语法 `![alt](path)`,且 path 必须是本地文件、扩展名受支持、大小不超限。
40
+ * http(s) / data: 链接一律跳过(那些飞书自己能渲染或根本不存在)。
41
+ * 相对路径按 cwd 解析。
42
+ */
43
+ export function extractLocalImages(text: string, cwd: string): LocalImageRef[] {
44
+ if (!text) return [];
45
+ const refs: LocalImageRef[] = [];
46
+ const seen = new Set<string>();
47
+ const re = /!\[([^\]]*)\]\(\s*([^)\s]+?)(?:\s+"[^"]*")?\s*\)/g;
48
+ let match: RegExpExecArray | null;
49
+ while ((match = re.exec(text)) !== null) {
50
+ const rawPath = match[2]?.trim();
51
+ if (!rawPath) continue;
52
+ // 网络图片 / data URI 不归这里管
53
+ if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath)) continue;
54
+ const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
55
+ if (seen.has(abs)) continue;
56
+ if (!SUPPORTED_IMAGE_EXT.has(extname(abs).toLowerCase())) continue;
57
+ if (!existsSync(abs)) continue;
58
+ try {
59
+ if (statSync(abs).size > MAX_IMAGE_BYTES) continue;
60
+ } catch {
61
+ continue;
62
+ }
63
+ seen.add(abs);
64
+ refs.push({ path: abs, alt: match[1] || undefined });
65
+ }
66
+ return refs;
67
+ }
68
+
69
+ /**
70
+ * 把正文里的「本地图片语法」降级成文字说明。
71
+ *
72
+ * 飞书卡片(CardKit)的 markdown 解析器会把 `![](/本地/路径.png)` 当成卡片图片元素,
73
+ * 而卡片图片只认 image_key —— 传本地路径会整张卡的更新被拒:
74
+ * code 200570 `card contains invalid image keys`
75
+ * 结果是正文永远停在上一次成功的快照,用户看到的是「回复中」,而图片本身已单独发出去。
76
+ * 图片由 flushLocalImages 单独发消息,所以卡片正文里只需留一句「(图片见下)」。
77
+ *
78
+ * 只动本地路径;http(s) / data: 链接原样保留,交回飞书自己处理。
79
+ */
80
+ export function stripLocalImageMarkdown(text: string): string {
81
+ if (!text) return "";
82
+ return text.replace(
83
+ /!\[([^\]]*)\]\(\s*([^)\s]+?)(?:\s+"[^"]*")?\s*\)/g,
84
+ (all: string, alt: string, rawPath: string) => {
85
+ const p = String(rawPath ?? "").trim();
86
+ if (!p) return all;
87
+ if (/^[a-z][a-z0-9+.-]*:/i.test(p)) return all;
88
+ const caption = String(alt ?? "").trim();
89
+ return caption ? `(图片见下:${caption})` : "(图片见下)";
90
+ },
91
+ );
92
+ }
93
+
94
+ /** 上传失败时的重试次数与退避基数(只对网络类错误重试) */
95
+ const UPLOAD_MAX_ATTEMPTS = 3;
96
+ const UPLOAD_RETRY_DELAY_MS = 300;
97
+
98
+ function sleep(ms: number) {
99
+ return new Promise((resolve) => setTimeout(resolve, ms));
100
+ }
101
+
102
+ /**
103
+ * 网络抖动才值得重试;权限不足 / 参数错这类重试也没用,直接放弃。
104
+ */
105
+ function isRetryableUploadError(message: string): boolean {
106
+ return /EPIPE|ECONNRESET|ETIMEDOUT|socket hang up|timeout|other side closed/i.test(message);
107
+ }
108
+
109
+ /**
110
+ * 上传一张本地图片,返回 image_key(失败返回 undefined,不抛)。
111
+ *
112
+ * **必须整块读成 Buffer 再交 SDK**:用 `createReadStream` 时网络一抖动 SDK 写流就抛
113
+ * `write EPIPE`,图被静默丢弃、用户侧只看到「没收到图」(2026-11-02 实测:同一份凭据用
114
+ * Buffer 直传图片接口 `code=0` 成功,而桥接这条路径日志里只有 `feishu.image.upload.error`)。
115
+ */
116
+ export async function uploadImage(client: any, filePath: string): Promise<string | undefined> {
117
+ let buffer: Buffer;
118
+ try {
119
+ buffer = readFileSync(filePath);
120
+ } catch (error) {
121
+ debugLog("feishu.image.read.error", {
122
+ filePath,
123
+ error: error instanceof Error ? error.message : String(error),
124
+ });
125
+ return undefined;
126
+ }
127
+ for (let attempt = 1; attempt <= UPLOAD_MAX_ATTEMPTS; attempt += 1) {
128
+ try {
129
+ const res = await client.im.image.create({
130
+ data: { image_type: "message", image: buffer },
131
+ });
132
+ const imageKey = res?.data?.image_key ?? res?.image_key;
133
+ if (!imageKey) {
134
+ debugLog("feishu.image.upload.empty_key", { filePath, attempt });
135
+ return undefined;
136
+ }
137
+ return String(imageKey);
138
+ } catch (error) {
139
+ const message = error instanceof Error ? error.message : String(error);
140
+ debugLog("feishu.image.upload.error", { filePath, attempt, error: message });
141
+ if (attempt >= UPLOAD_MAX_ATTEMPTS || !isRetryableUploadError(message)) return undefined;
142
+ await sleep(UPLOAD_RETRY_DELAY_MS * attempt);
143
+ }
144
+ }
145
+ return undefined;
146
+ }
147
+
148
+ /**
149
+ * 上传并发送一张本地图片。
150
+ *
151
+ * target.replyToMessageId 优先(挂在回复链上,和文字对得上),否则平铺发到 chatId。
152
+ * 返回新消息 ID;任一步失败返回 undefined —— 图片发不出去不该让整轮回复失败。
153
+ */
154
+ export async function sendLocalImage(
155
+ client: any,
156
+ target: ImageTarget,
157
+ filePath: string,
158
+ ): Promise<string | undefined> {
159
+ const imageKey = await uploadImage(client, filePath);
160
+ if (!imageKey) return undefined;
161
+ const content = JSON.stringify({ image_key: imageKey });
162
+ try {
163
+ if (target.replyToMessageId) {
164
+ const res = await client.im.message.reply({
165
+ path: { message_id: target.replyToMessageId },
166
+ data: {
167
+ msg_type: "image",
168
+ content,
169
+ // 话题群必须显式声明,否则图落在群主消息流、话题里看不到
170
+ ...(target.replyInThread ? { reply_in_thread: true } : {}),
171
+ },
172
+ });
173
+ return res?.data?.message_id as string | undefined;
174
+ }
175
+ if (target.chatId) {
176
+ const res = await client.im.message.create({
177
+ params: { receive_id_type: "chat_id" },
178
+ data: { receive_id: target.chatId, msg_type: "image", content },
179
+ });
180
+ return res?.data?.message_id as string | undefined;
181
+ }
182
+ } catch (error) {
183
+ debugLog("feishu.image.send.error", {
184
+ filePath,
185
+ error: error instanceof Error ? error.message : String(error),
186
+ });
187
+ }
188
+ return undefined;
189
+ }
190
+
191
+ /** 发图需要的最小 transport 面(与 ReplyCardTransport 的两个可选方法同形) */
192
+ export type LocalImageTransport = {
193
+ replyLocalImage?(
194
+ messageId: string,
195
+ filePath: string,
196
+ replyInThread?: boolean,
197
+ ): Promise<string | undefined>;
198
+ sendLocalImage?(chatId: string, filePath: string): Promise<string | undefined>;
199
+ };
200
+
201
+ /**
202
+ * 把正文里的本地图片挨张发出去,返回实际发出的张数。
203
+ *
204
+ * 规则:`done` 与 `stopped` 都发,只有 `failed` 不发。
205
+ * - `stopped` 必须发:中断时模型已经把 `![](路径)` 写进正文,用户看得到文字却看不到图,
206
+ * 会被当成「图没发」——2026-11-06 中断事故里 5 张设计稿全丢,用户连续追问两次。
207
+ * - `failed` 不发但落 `local_image_dropped` 日志(带 count/paths),丢失可查。
208
+ * 抽成 free function 是为了别把 reply-card.ts 顶过 500 行硬上限。
209
+ */
210
+ export async function flushLocalImages(input: {
211
+ body: string;
212
+ status: "done" | "failed" | "stopped";
213
+ target: ImageTarget;
214
+ transport: LocalImageTransport;
215
+ cwd?: string;
216
+ }): Promise<number> {
217
+ if (input.status === "failed") {
218
+ // 失败轮次的正文不作数,图不发;但必须留一条可查记录,
219
+ // 否则「正文里明明写了图、结果一张没发」只能靠猜(2026-11-06 断线事故复盘)。
220
+ const dropped = extractLocalImages(input.body, input.cwd ?? process.cwd());
221
+ if (dropped.length > 0) {
222
+ debugLog("feishu.reply_card.local_image_dropped", {
223
+ status: input.status,
224
+ count: dropped.length,
225
+ paths: dropped.map((ref) => ref.path),
226
+ });
227
+ }
228
+ return 0;
229
+ }
230
+ const refs = extractLocalImages(input.body, input.cwd ?? process.cwd());
231
+ if (refs.length === 0) return 0;
232
+ const picked = refs.slice(0, MAX_LOCAL_IMAGES_PER_TURN);
233
+ debugLog("feishu.reply_card.local_images", { count: picked.length, total: refs.length });
234
+ let sent = 0;
235
+ for (const ref of picked) {
236
+ try {
237
+ const id = input.target.replyToMessageId
238
+ ? await input.transport.replyLocalImage?.(
239
+ input.target.replyToMessageId,
240
+ ref.path,
241
+ input.target.replyInThread,
242
+ )
243
+ : input.target.chatId
244
+ ? await input.transport.sendLocalImage?.(input.target.chatId, ref.path)
245
+ : undefined;
246
+ if (id) sent += 1;
247
+ debugLog("feishu.reply_card.local_image_sent", { path: ref.path, messageId: id });
248
+ } catch (error) {
249
+ debugLog("feishu.reply_card.local_image_error", {
250
+ path: ref.path,
251
+ error: error instanceof Error ? error.message : String(error),
252
+ });
253
+ }
254
+ }
255
+ return sent;
256
+ }
@@ -0,0 +1,170 @@
1
+ import { createHash } from "node:crypto";
2
+ import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
5
+
6
+ /**
7
+ * 实例数据目录与卡片回调端口的解析。
8
+ *
9
+ * **实例目录跟着工作区走**:默认就是工作区自己的 `<工作区根>/.pi/feishu`,
10
+ * 不存在「全局实例」——每个工作区的配置、状态、桥接路由、去重记录、日志、附件收件箱
11
+ * 都落在自己目录里,互不干扰。`FEISHU_DATA_DIR` 仍可作为显式覆盖(少数要把数据
12
+ * 放到别处的场景),优先级高于默认值。
13
+ *
14
+ * 0.6.0 之前默认是全局的 `~/.pi/agent/feishu`(见 `LEGACY_GLOBAL_ROOT_DIR`),已废弃;
15
+ * 升级时由 `config.ts` 的 `migrateLegacyGlobalInstance()` 负责把属于本工作区的那份搬过来。
16
+ *
17
+ * 刻意**不**跟着工作区走的东西:连接锁(见 `gateway-lock.ts`)。
18
+ * 锁按 appId 全局互斥是护栏,不是缺陷——飞书长连接是集群模式、不广播,
19
+ * 同一个机器人的事件只会随机推给其中一条连接,两个工作区共用同一个 appId
20
+ * 会互相抢连接、并让消息随机落到错误的工作区。
21
+ * 所以多开的前提仍是「一个工作区一个机器人(各自的 appId)」。
22
+ */
23
+
24
+ /** 工作区本地实例目录名(相对工作区根目录):`<工作区>/.pi/feishu`。 */
25
+ export const WORKSPACE_INSTANCE_SUBPATH = join(".pi", "feishu");
26
+
27
+ /** 0.6.0 之前的全局实例目录,仅为「搬迁旧数据 / 打提示」保留。 */
28
+ export const LEGACY_GLOBAL_ROOT_DIR = join(homedir(), ".pi", "agent", "feishu");
29
+
30
+ /** 卡片回调端口区间:3001 是历史上 Pi 的固定端口,实例一律从 3003 起派生。 */
31
+ const INSTANCE_PORT_BASE = 3003;
32
+ const INSTANCE_PORT_SPAN = 97;
33
+
34
+ /** 展开开头的 `~` / `~/`;其余原样交给 path.resolve 处理。 */
35
+ function expandHome(input: string): string {
36
+ if (input === "~") return homedir();
37
+ if (input.startsWith("~/")) return join(homedir(), input.slice(2));
38
+ return input;
39
+ }
40
+
41
+ /** 工作区本地实例目录:`<工作区>/.pi/feishu`(绝对路径)。 */
42
+ export function workspaceInstanceDir(cwd: string = process.cwd()): string {
43
+ return join(resolve(cwd), WORKSPACE_INSTANCE_SUBPATH);
44
+ }
45
+
46
+ /** 显式指定的实例目录(环境变量 `FEISHU_DATA_DIR`);未设或纯空白返回 `undefined`。 */
47
+ export function explicitInstanceDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
48
+ const raw = env.FEISHU_DATA_DIR?.trim();
49
+ if (!raw) return undefined;
50
+ return resolve(expandHome(raw));
51
+ }
52
+
53
+ /**
54
+ * 实例数据目录:显式指定优先,否则跟着工作区走,**永远有值**。
55
+ * 相对路径按传入的 cwd 解析;daemon 场景请保证 cwd 就是工作区根目录。
56
+ */
57
+ export function resolveInstanceDir(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): string {
58
+ return explicitInstanceDir(env) ?? workspaceInstanceDir(cwd);
59
+ }
60
+
61
+ /** Feishu 数据根目录(= 实例数据目录)。 */
62
+ export function resolveRootDir(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): string {
63
+ return resolveInstanceDir(env, cwd);
64
+ }
65
+
66
+ /**
67
+ * 卡片回调默认端口:按「实例目录 + base」稳定派生到 3003-3099。
68
+ * 同一工作区每次启动得到同一个端口(飞书后台的回调地址只需配一次),
69
+ * 不同工作区互不相同;base 只影响派生结果(Pi 传 3001)。
70
+ * 派生在区间内存在理论碰撞,需要精确控制时用 `FEISHU_CARD_ACTION_WEBHOOK_PORT`
71
+ * 显式指定(显式值优先级更高)。
72
+ */
73
+ export function instanceWebhookPort(base: number, env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): number {
74
+ const dir = resolveInstanceDir(env, cwd);
75
+ const digest = createHash("sha1").update(`${dir}:${base}`).digest();
76
+ return INSTANCE_PORT_BASE + (digest.readUInt16BE(0) % INSTANCE_PORT_SPAN);
77
+ }
78
+
79
+ /** 目录比较用的归一化:先展开 `~` 再取 realpath(软链、`/tmp` vs `/private/tmp` 视为同一处);
80
+ * 目录不存在时退回字面 resolve,保证纯函数在任何环境下都给出确定结果。 */
81
+ export function normalizeDir(dir: string): string {
82
+ const expanded = resolve(expandHome(dir));
83
+ try {
84
+ return realpathSync(expanded);
85
+ } catch {
86
+ return expanded;
87
+ }
88
+ }
89
+
90
+ /** 两个路径是否属于同一个工作区:相等,或一个是另一个的父目录(允许在子目录里启动 pi)。 */
91
+ export function sameWorkspace(a: string, b: string): boolean {
92
+ const na = normalizeDir(a);
93
+ const nb = normalizeDir(b);
94
+ if (na === nb) return true;
95
+ const inside = (parent: string, child: string) => {
96
+ const rel = relative(parent, child);
97
+ return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
98
+ };
99
+ return inside(na, nb) || inside(nb, na);
100
+ }
101
+
102
+ /**
103
+ * 是否「这份机器人属于别的工作区」——自动启动前的保险。
104
+ *
105
+ * 三条件同时成立才算:
106
+ * 1. 没设 `FEISHU_ALLOW_FOREIGN_WORKSPACE=1`;
107
+ * 2. 能拿到 owner 的 cwd(连接锁当前 owner,或属主工作区记录 owner-workspace.json);
108
+ * 3. owner 的 cwd 与本进程 cwd 不属于同一个工作区。
109
+ *
110
+ * 含义:这份配置对应的机器人**正在被另一个工作区使用**。飞书长连接是集群模式、不广播,
111
+ * 两个工作区共用同一个 appId 会互相抢连接,并让消息随机落到错的工作区,
112
+ * 因此调用方应拒绝自动启动,改为提示用户配一个自己的自建应用。
113
+ *
114
+ * 判据有两个来源,任一指向别的工作区就算外来:
115
+ * 1. 连接锁当前 owner 的 cwd(锁被持时有效);
116
+ * 2. 属主工作区记录(`owner-workspace.json`)——锁空闲时靠它才能分辨归属。
117
+ *
118
+ * 确需在本目录临时接管时,设 `FEISHU_ALLOW_FOREIGN_WORKSPACE=1` 显式放行,
119
+ * 或在本目录手动 `/feishu restart`(手动命令不受本保护限制,并会更新属主记录)。
120
+ */
121
+ export function isForeignWorkspace(
122
+ ownerCwd: string | undefined | null,
123
+ cwd: string = process.cwd(),
124
+ env: NodeJS.ProcessEnv = process.env,
125
+ recordedOwnerCwd?: string | null,
126
+ ): boolean {
127
+ if (env.FEISHU_ALLOW_FOREIGN_WORKSPACE === "1") return false;
128
+ const owners = [ownerCwd, recordedOwnerCwd].filter((value): value is string => Boolean(value?.trim()));
129
+ if (owners.length === 0) return false;
130
+ return owners.some((owner) => !sameWorkspace(owner, cwd));
131
+ }
132
+
133
+ /** 属主工作区记录文件名(放在实例根目录下):标明这份实例属于哪个工作区。 */
134
+ export const OWNER_WORKSPACE_FILE = "owner-workspace.json";
135
+
136
+ /** 属主工作区记录文件的完整路径。 */
137
+ export function ownerWorkspacePath(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): string {
138
+ return join(resolveRootDir(env, cwd), OWNER_WORKSPACE_FILE);
139
+ }
140
+
141
+ /** 读任意一份属主记录文件(缺文件 / 格式不对 / 字段为空都返回 `undefined`,不抛错)。 */
142
+ export function readOwnerWorkspaceAt(file: string): string | undefined {
143
+ try {
144
+ const parsed = JSON.parse(readFileSync(file, "utf8")) as { cwd?: unknown };
145
+ return typeof parsed.cwd === "string" && parsed.cwd.trim() ? parsed.cwd : undefined;
146
+ } catch {
147
+ return undefined;
148
+ }
149
+ }
150
+
151
+ /**
152
+ * 读当前实例的属主工作区记录。
153
+ * 这份记录是「外来工作区保护」在锁空闲时的唯一判据:连接锁只记录了*当前*持有者,
154
+ * 而记录记的是这份配置**长期属于谁**。
155
+ */
156
+ export function readOwnerWorkspace(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): string | undefined {
157
+ return readOwnerWorkspaceAt(ownerWorkspacePath(env, cwd));
158
+ }
159
+
160
+ /** 把当前目录认领为属主工作区(连接成功后调用;写失败只意味着少了这道保险,不影响主流程)。 */
161
+ export function writeOwnerWorkspace(cwd: string = process.cwd(), env: NodeJS.ProcessEnv = process.env): void {
162
+ try {
163
+ const file = ownerWorkspacePath(env, cwd);
164
+ mkdirSync(dirname(file), { recursive: true });
165
+ const payload = { cwd: normalizeDir(cwd), updatedAt: new Date().toISOString() };
166
+ writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
167
+ } catch {
168
+ // 忽略:记录写不进去也不该阻断连接
169
+ }
170
+ }
@@ -0,0 +1,148 @@
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
+ import { WORKSPACE_INSTANCE_SUBPATH } from "./instance.ts";
4
+ import type { Domain, FeishuConfig, GroupPolicy } from "./types.ts";
5
+
6
+ /**
7
+ * 一个工作区内「多个机器人」的实例目录约定。
8
+ *
9
+ * 架构基线不变(见 `instance.ts` 的说明):**一个实例目录 = 一个自建应用 = 一个 daemon**。
10
+ * 这份文件只负责「实例目录 ↔ 实例名」的映射与枚举,让 TUI 能在一个工作区里
11
+ * 建/列/启停多个机器人,而不需要把单例的 `loadConfig()` / `FeishuTransport` 改成多例。
12
+ *
13
+ * 目录约定(都在工作区根下):
14
+ * - 默认实例:`<工作区>/.pi/feishu`,名字 `default`
15
+ * - 其它实例:`<工作区>/.pi/feishu-<name>`
16
+ *
17
+ * 为什么不放在一个 daemon 里跑多连接:飞书长连接是集群模式不广播,
18
+ * 每个 appId 一条连接、一把网关锁、一个回调端口;分进程是最小改动且故障隔离。
19
+ */
20
+
21
+ export const DEFAULT_INSTANCE_NAME = "default";
22
+ export const INSTANCE_DIR_PREFIX = "feishu-";
23
+
24
+ const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,30}$/;
25
+ /** 这些名字会跟默认实例的目录撞车或与「feishu-」前缀语义混淆,禁止使用。 */
26
+ const RESERVED_NAMES = new Set([DEFAULT_INSTANCE_NAME, "config", "state", "bridge", "dedupe", "daemon", "debug"]);
27
+
28
+ export type InstanceConfig = Partial<FeishuConfig> & { appId?: string; appSecret?: string };
29
+
30
+ export type InstanceSummary = {
31
+ name: string;
32
+ dir: string;
33
+ configPath: string;
34
+ configured: boolean;
35
+ appId?: string;
36
+ appSecret?: string;
37
+ domain: Domain;
38
+ groupPolicy?: GroupPolicy;
39
+ autoStart: boolean;
40
+ webhookPort?: number;
41
+ };
42
+
43
+ /** 实例名合法性:小写字母/数字/连字符,首字符必须是字母或数字。 */
44
+ export function isValidInstanceName(name: string): boolean {
45
+ return NAME_PATTERN.test(name) && !RESERVED_NAMES.has(name);
46
+ }
47
+
48
+ /** 实例名 → 实例目录(默认实例是 `.pi/feishu`,其余是 `.pi/feishu-<name>`)。 */
49
+ export function instanceDirForName(workspaceRoot: string, name: string = DEFAULT_INSTANCE_NAME): string {
50
+ const root = resolve(workspaceRoot);
51
+ if (name === DEFAULT_INSTANCE_NAME) return join(root, WORKSPACE_INSTANCE_SUBPATH);
52
+ const dirName = `${INSTANCE_DIR_PREFIX}${name}`;
53
+ return join(root, ".pi", dirName);
54
+ }
55
+
56
+ /** 实例目录 → 实例名;不是本工作区约定内的实例目录时返回 `undefined`。 */
57
+ export function instanceNameFromDir(workspaceRoot: string, dir: string): string | undefined {
58
+ const root = resolve(workspaceRoot);
59
+ const target = resolve(dir);
60
+ if (target === join(root, WORKSPACE_INSTANCE_SUBPATH)) return DEFAULT_INSTANCE_NAME;
61
+ const prefix = `${join(root, ".pi")}/`;
62
+ if (!target.startsWith(prefix)) return undefined;
63
+ const dirName = target.slice(prefix.length);
64
+ if (!dirName.startsWith(INSTANCE_DIR_PREFIX)) return undefined;
65
+ const name = dirName.slice(INSTANCE_DIR_PREFIX.length);
66
+ return isValidInstanceName(name) ? name : undefined;
67
+ }
68
+
69
+ export function instanceConfigPath(dir: string): string {
70
+ return join(dir, "config.pi.json");
71
+ }
72
+
73
+ /**
74
+ * 读任意实例目录的配置(**纯读**,与模块级 `ROOT_DIR` 无关)。
75
+ * 不存在 / 解析失败 / 缺 appId 或 appSecret 时返回 `undefined`。
76
+ */
77
+ export function readInstanceConfig(dir: string): InstanceConfig | undefined {
78
+ const path = instanceConfigPath(dir);
79
+ if (!existsSync(path)) return undefined;
80
+ let parsed: unknown;
81
+ try {
82
+ parsed = JSON.parse(readFileSync(path, "utf8"));
83
+ } catch {
84
+ return undefined;
85
+ }
86
+ if (!parsed || typeof parsed !== "object") return undefined;
87
+ const cfg = parsed as InstanceConfig;
88
+ const appId = typeof cfg.appId === "string" ? cfg.appId.trim() : "";
89
+ const appSecret = typeof cfg.appSecret === "string" ? cfg.appSecret.trim() : "";
90
+ if (!appId || !appSecret) return undefined;
91
+ return { ...cfg, appId, appSecret };
92
+ }
93
+
94
+ /** 只读 appId(连接锁按 appId 区分,判归属时不需要 secret)。 */
95
+ export function readInstanceAppId(dir: string): string | undefined {
96
+ return readInstanceConfig(dir)?.appId;
97
+ }
98
+
99
+ /**
100
+ * 枚举工作区里所有实例(含未配置的目录)。
101
+ * 排序:默认实例在首位,其余按名字。
102
+ */
103
+ export function listInstances(workspaceRoot: string = process.cwd()): InstanceSummary[] {
104
+ const root = resolve(workspaceRoot);
105
+ const piDir = join(root, ".pi");
106
+ const found: InstanceSummary[] = [];
107
+ const names = new Set<string>([DEFAULT_INSTANCE_NAME]);
108
+
109
+ let entries: string[] = [];
110
+ try {
111
+ entries = readdirSync(piDir, { withFileTypes: true })
112
+ .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
113
+ .map((entry) => entry.name);
114
+ } catch {
115
+ entries = [];
116
+ }
117
+ for (const entry of entries) {
118
+ if (!entry.startsWith(INSTANCE_DIR_PREFIX)) continue;
119
+ const name = entry.slice(INSTANCE_DIR_PREFIX.length);
120
+ if (isValidInstanceName(name)) names.add(name);
121
+ }
122
+
123
+ for (const name of names) {
124
+ const dir = instanceDirForName(root, name);
125
+ const cfg = readInstanceConfig(dir);
126
+ const configured = Boolean(cfg);
127
+ // 未配置的目录只有真的存在才算一个实例(否则「default 从未 setup」也会列出来)
128
+ if (!configured && !existsSync(dir)) continue;
129
+ found.push({
130
+ name,
131
+ dir,
132
+ configPath: instanceConfigPath(dir),
133
+ configured,
134
+ appId: cfg?.appId,
135
+ appSecret: cfg?.appSecret,
136
+ domain: (cfg?.domain as Domain) || "feishu",
137
+ groupPolicy: cfg?.groupPolicy,
138
+ autoStart: cfg?.autoStart !== false,
139
+ webhookPort: typeof cfg?.cardActionWebhookPort === "number" ? cfg.cardActionWebhookPort : undefined,
140
+ });
141
+ }
142
+
143
+ return found.sort((a, b) => {
144
+ if (a.name === DEFAULT_INSTANCE_NAME) return -1;
145
+ if (b.name === DEFAULT_INSTANCE_NAME) return 1;
146
+ return a.name.localeCompare(b.name);
147
+ });
148
+ }