@nextclaw/channel-plugin-feishu 0.2.29-beta.0 → 0.2.29-beta.1

package/dist/src/sheets-shared.js

@@ -0,0 +1,193 @@
+import { wwwDomain } from "./domains.js";
+import { assertLarkOk, json } from "./user-tool-helpers.js";
+//#region src/sheets-shared.ts
+const MAX_READ_ROWS = 200;
+const MAX_WRITE_ROWS = 5e3;
+const MAX_WRITE_COLS = 100;
+function parseSheetUrl(url) {
+	try {
+		const parsed = new URL(url);
+		const match = parsed.pathname.match(/\/sheets\/([^/?#]+)/);
+		if (!match) return null;
+		return {
+			token: match[1],
+			sheetId: parsed.searchParams.get("sheet") || void 0
+		};
+	} catch {
+		return null;
+	}
+}
+function resolveToken(params) {
+	if (params.spreadsheet_token) return { token: params.spreadsheet_token };
+	if (params.url) return parseSheetUrl(params.url);
+	return null;
+}
+function colLetter(n) {
+	let result = "";
+	let value = n;
+	while (value > 0) {
+		value -= 1;
+		result = String.fromCharCode(65 + value % 26) + result;
+		value = Math.floor(value / 26);
+	}
+	return result;
+}
+function flattenCellValue(cell) {
+	if (!Array.isArray(cell)) return cell;
+	if (cell.length > 0 && cell.every((segment) => segment && typeof segment === "object" && "text" in segment)) return cell.map((segment) => String(segment.text ?? "")).join("");
+	return cell;
+}
+async function resolveSheetRange(client, token, range, sheetId) {
+	if (range) return range;
+	if (sheetId) return sheetId;
+	const response = await client.invoke("feishu_sheet.info", (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts), { as: "user" });
+	assertLarkOk(response);
+	const firstSheet = response.data?.sheets?.[0];
+	if (!firstSheet?.sheet_id) throw new Error("Spreadsheet has no worksheets.");
+	return firstSheet.sheet_id;
+}
+async function handleCreate(client, payload) {
+	const createResponse = await client.invoke("feishu_sheet.create", (sdk, opts) => sdk.sheets.spreadsheet.create({ data: {
+		title: payload.title,
+		folder_token: payload.folder_token
+	} }, opts), { as: "user" });
+	assertLarkOk(createResponse);
+	const spreadsheet = createResponse.data?.spreadsheet;
+	const token = spreadsheet?.spreadsheet_token;
+	if (!token) return json({ error: "创建电子表格失败，未返回 spreadsheet_token。" });
+	const allRows = [...payload.headers ? [payload.headers] : [], ...payload.data ?? []];
+	if (allRows.length > 0) {
+		const sheetsResponse = await client.invoke("feishu_sheet.create", (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts), { as: "user" });
+		assertLarkOk(sheetsResponse);
+		const firstSheet = sheetsResponse.data?.sheets?.[0];
+		if (firstSheet?.sheet_id) {
+			const numCols = Math.max(...allRows.map((row) => row.length), 1);
+			const range = `${firstSheet.sheet_id}!A1:${colLetter(numCols)}${allRows.length}`;
+			await client.invokeByPath("feishu_sheet.create", `/open-apis/sheets/v2/spreadsheets/${token}/values`, {
+				method: "PUT",
+				body: { valueRange: {
+					range,
+					values: allRows
+				} },
+				as: "user"
+			});
+		}
+	}
+	return json({
+		spreadsheet_token: token,
+		title: spreadsheet?.title ?? payload.title,
+		url: `${wwwDomain(client.account.domain)}/sheets/${token}`
+	});
+}
+async function handleInfo(client, token) {
+	const [spreadsheetRes, sheetsRes] = await Promise.all([client.invoke("feishu_sheet.info", (sdk, opts) => sdk.sheets.spreadsheet.get({ path: { spreadsheet_token: token } }, opts), { as: "user" }), client.invoke("feishu_sheet.info", (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts), { as: "user" })]);
+	assertLarkOk(spreadsheetRes);
+	assertLarkOk(sheetsRes);
+	return json({
+		title: spreadsheetRes.data?.spreadsheet?.title,
+		spreadsheet_token: token,
+		url: `${wwwDomain(client.account.domain)}/sheets/${token}`,
+		sheets: (sheetsRes.data?.sheets ?? []).map((sheet) => ({
+			sheet_id: sheet.sheet_id,
+			title: sheet.title,
+			index: sheet.index,
+			row_count: sheet.grid_properties?.row_count,
+			column_count: sheet.grid_properties?.column_count
+		}))
+	});
+}
+async function handleRead(client, tokenInfo, payload) {
+	const range = await resolveSheetRange(client, tokenInfo.token, payload.range, payload.sheet_id ?? tokenInfo.sheetId);
+	const response = await client.invokeByPath("feishu_sheet.read", `/open-apis/sheets/v2/spreadsheets/${tokenInfo.token}/values/${encodeURIComponent(range)}`, {
+		method: "GET",
+		query: {
+			valueRenderOption: payload.value_render_option ?? "ToString",
+			dateTimeRenderOption: "FormattedString"
+		},
+		as: "user"
+	});
+	const values = (response.data?.valueRange?.values ?? []).map((row) => row.map(flattenCellValue));
+	return json({
+		range: response.data?.valueRange?.range,
+		values: values.slice(0, MAX_READ_ROWS),
+		...values.length > MAX_READ_ROWS ? {
+			truncated: true,
+			total_rows: values.length,
+			hint: `结果超过 ${MAX_READ_ROWS} 行，已截断。请缩小 range 后重试。`
+		} : {}
+	});
+}
+async function handleWrite(client, tokenInfo, payload) {
+	if ((payload.values?.length ?? 0) > MAX_WRITE_ROWS) return json({ error: `写入行数超过限制 ${MAX_WRITE_ROWS}` });
+	if ((payload.values ?? []).some((row) => row.length > MAX_WRITE_COLS)) return json({ error: `写入列数超过限制 ${MAX_WRITE_COLS}` });
+	const range = await resolveSheetRange(client, tokenInfo.token, payload.range, payload.sheet_id ?? tokenInfo.sheetId);
+	const response = await client.invokeByPath(payload.action === "write" ? "feishu_sheet.write" : "feishu_sheet.append", `/open-apis/sheets/v2/spreadsheets/${tokenInfo.token}/${payload.action === "write" ? "values" : "values_append"}`, {
+		method: payload.action === "write" ? "PUT" : "POST",
+		body: { valueRange: {
+			range,
+			values: payload.values
+		} },
+		as: "user"
+	});
+	const updates = response.data?.updates ?? response.data;
+	return json({
+		updated_range: updates?.updatedRange,
+		updated_rows: updates?.updatedRows,
+		updated_columns: updates?.updatedColumns,
+		updated_cells: updates?.updatedCells,
+		revision: updates?.revision
+	});
+}
+async function handleFind(client, token, payload) {
+	const response = await client.invoke("feishu_sheet.find", (sdk, opts) => sdk.sheets.spreadsheetSheet.find({
+		path: {
+			spreadsheet_token: token,
+			sheet_id: payload.sheet_id
+		},
+		data: {
+			find: payload.find,
+			find_condition: {
+				range: payload.range ? `${payload.sheet_id}!${payload.range}` : payload.sheet_id,
+				...payload.match_case !== void 0 ? { match_case: !payload.match_case } : {},
+				...payload.match_entire_cell !== void 0 ? { match_entire_cell: payload.match_entire_cell } : {},
+				...payload.search_by_regex !== void 0 ? { search_by_regex: payload.search_by_regex } : {},
+				...payload.include_formulas !== void 0 ? { include_formulas: payload.include_formulas } : {}
+			}
+		}
+	}, opts), { as: "user" });
+	assertLarkOk(response);
+	return json({
+		matched_cells: response.data?.find_result?.matched_cells ?? [],
+		matched_formula_cells: response.data?.find_result?.matched_formula_cells ?? []
+	});
+}
+async function handleExport(client, token, payload) {
+	const exportCreate = await client.invoke("feishu_sheet.export", (sdk, opts) => sdk.drive.exportTask.create({ data: {
+		file_extension: payload.file_extension,
+		token,
+		type: "sheet",
+		sub_id: payload.sheet_id
+	} }, opts), { as: "user" });
+	assertLarkOk(exportCreate);
+	const ticket = exportCreate.data?.ticket;
+	if (!ticket) return json({ error: "导出任务创建失败，未返回 ticket。" });
+	for (let i = 0; i < 30; i += 1) {
+		await new Promise((resolve) => setTimeout(resolve, 1e3));
+		const exportStatus = await client.invoke("feishu_sheet.export", (sdk, opts) => sdk.drive.exportTask.get({
+			path: { ticket },
+			params: { token }
+		}, opts), { as: "user" });
+		assertLarkOk(exportStatus);
+		const result = exportStatus.data?.result;
+		if (result?.job_status === 0) return json({
+			file_token: result.file_token,
+			file_name: result.file_name,
+			file_size: result.file_size,
+			file_extension: payload.file_extension
+		});
+		if ((result?.job_status ?? 0) >= 3) return json({ error: result?.job_error_msg ?? `导出失败 (status=${result?.job_status})` });
+	}
+	return json({ error: "导出任务超时，请稍后重试。" });
+}
+//#endregion
+export { handleCreate, handleExport, handleFind, handleInfo, handleRead, handleWrite, resolveToken };

package/dist/src/sheets.js

@@ -0,0 +1,95 @@
+import { StringEnum, createToolContext, handleInvokeError, registerTool } from "./user-tool-helpers.js";
+import { resolveRegisteredFeishuToolsConfig } from "./tool-account.js";
+import { handleCreate, handleExport, handleFind, handleInfo, handleRead, handleWrite, resolveToken } from "./sheets-shared.js";
+import { Type } from "@sinclair/typebox";
+//#region src/sheets.ts
+const SheetSchema = Type.Union([
+	Type.Object({
+		action: Type.Literal("info"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String())
+	}),
+	Type.Object({
+		action: Type.Literal("read"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String()),
+		range: Type.Optional(Type.String()),
+		sheet_id: Type.Optional(Type.String()),
+		value_render_option: Type.Optional(StringEnum([
+			"FormattedValue",
+			"UnformattedValue",
+			"Formula",
+			"ToString"
+		]))
+	}),
+	Type.Object({
+		action: Type.Literal("write"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String()),
+		range: Type.Optional(Type.String()),
+		sheet_id: Type.Optional(Type.String()),
+		values: Type.Array(Type.Array(Type.Any()))
+	}),
+	Type.Object({
+		action: Type.Literal("append"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String()),
+		range: Type.Optional(Type.String()),
+		sheet_id: Type.Optional(Type.String()),
+		values: Type.Array(Type.Array(Type.Any()))
+	}),
+	Type.Object({
+		action: Type.Literal("find"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String()),
+		sheet_id: Type.String(),
+		range: Type.Optional(Type.String()),
+		find: Type.String(),
+		match_case: Type.Optional(Type.Boolean()),
+		match_entire_cell: Type.Optional(Type.Boolean()),
+		search_by_regex: Type.Optional(Type.Boolean()),
+		include_formulas: Type.Optional(Type.Boolean())
+	}),
+	Type.Object({
+		action: Type.Literal("create"),
+		title: Type.String(),
+		folder_token: Type.Optional(Type.String()),
+		headers: Type.Optional(Type.Array(Type.Any())),
+		data: Type.Optional(Type.Array(Type.Array(Type.Any())))
+	}),
+	Type.Object({
+		action: Type.Literal("export"),
+		url: Type.Optional(Type.String()),
+		spreadsheet_token: Type.Optional(Type.String()),
+		sheet_id: Type.Optional(Type.String()),
+		file_extension: StringEnum(["xlsx", "csv"])
+	})
+]);
+function registerFeishuSheetsTools(api) {
+	if (!api.config) return;
+	if (!resolveRegisteredFeishuToolsConfig(api.config).sheets) return;
+	registerTool(api, {
+		name: "feishu_sheet",
+		label: "Feishu Sheet",
+		description: "按本人身份读取、写入、创建、查找和导出飞书电子表格。",
+		parameters: SheetSchema,
+		async execute(_toolCallId, params) {
+			const payload = params;
+			try {
+				const client = createToolContext(api, "feishu_sheet").toolClient();
+				if (payload.action === "create") return handleCreate(client, payload);
+				const tokenInfo = resolveToken(payload);
+				if (!tokenInfo?.token) return json({ error: "请传 spreadsheet_token 或 /sheets/TOKEN 形式的 url。" });
+				if (payload.action === "info") return handleInfo(client, tokenInfo.token);
+				if (payload.action === "read") return handleRead(client, tokenInfo, payload);
+				if (payload.action === "write" || payload.action === "append") return handleWrite(client, tokenInfo, payload);
+				if (payload.action === "find") return handleFind(client, tokenInfo.token, payload);
+				return handleExport(client, tokenInfo.token, payload);
+			} catch (error) {
+				return handleInvokeError(error, api);
+			}
+		}
+	}, { name: "feishu_sheet" });
+}
+//#endregion
+export { registerFeishuSheetsTools };

package/dist/src/streaming-card.js

@@ -0,0 +1,263 @@
+import { fetchWithSsrFGuard } from "./nextclaw-sdk/network-fetch.js";
+import "./nextclaw-sdk/feishu.js";
+//#region src/streaming-card.ts
+const tokenCache = /* @__PURE__ */ new Map();
+function resolveApiBase(domain) {
+	if (domain === "lark") return "https://open.larksuite.com/open-apis";
+	if (domain && domain !== "feishu" && domain.startsWith("http")) return `${domain.replace(/\/+$/, "")}/open-apis`;
+	return "https://open.feishu.cn/open-apis";
+}
+function resolveAllowedHostnames(domain) {
+	if (domain === "lark") return ["open.larksuite.com"];
+	if (domain && domain !== "feishu" && domain.startsWith("http")) try {
+		return [new URL(domain).hostname];
+	} catch {
+		return [];
+	}
+	return ["open.feishu.cn"];
+}
+async function getToken(creds) {
+	const key = `${creds.domain ?? "feishu"}|${creds.appId}`;
+	const cached = tokenCache.get(key);
+	if (cached && cached.expiresAt > Date.now() + 6e4) return cached.token;
+	const { response, release } = await fetchWithSsrFGuard({
+		url: `${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`,
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				app_id: creds.appId,
+				app_secret: creds.appSecret
+			})
+		},
+		policy: { allowedHostnames: resolveAllowedHostnames(creds.domain) },
+		auditContext: "feishu.streaming-card.token"
+	});
+	if (!response.ok) {
+		await release();
+		throw new Error(`Token request failed with HTTP ${response.status}`);
+	}
+	const data = await response.json();
+	await release();
+	if (data.code !== 0 || !data.tenant_access_token) throw new Error(`Token error: ${data.msg}`);
+	tokenCache.set(key, {
+		token: data.tenant_access_token,
+		expiresAt: Date.now() + (data.expire ?? 7200) * 1e3
+	});
+	return data.tenant_access_token;
+}
+function truncateSummary(text, max = 50) {
+	if (!text) return "";
+	const clean = text.replace(/\n/g, " ").trim();
+	return clean.length <= max ? clean : clean.slice(0, max - 3) + "...";
+}
+function mergeStreamingText(previousText, nextText) {
+	const previous = typeof previousText === "string" ? previousText : "";
+	const next = typeof nextText === "string" ? nextText : "";
+	if (!next) return previous;
+	if (!previous || next === previous) return next;
+	if (next.startsWith(previous)) return next;
+	if (previous.startsWith(next)) return previous;
+	if (next.includes(previous)) return next;
+	if (previous.includes(next)) return previous;
+	const maxOverlap = Math.min(previous.length, next.length);
+	for (let overlap = maxOverlap; overlap > 0; overlap -= 1) if (previous.slice(-overlap) === next.slice(0, overlap)) return `${previous}${next.slice(overlap)}`;
+	return `${previous}${next}`;
+}
+function resolveStreamingCardSendMode(options) {
+	if (options?.replyToMessageId) return "reply";
+	if (options?.rootId) return "root_create";
+	return "create";
+}
+/** Streaming card session manager */
+var FeishuStreamingSession = class {
+	client;
+	creds;
+	state = null;
+	queue = Promise.resolve();
+	closed = false;
+	log;
+	lastUpdateTime = 0;
+	pendingText = null;
+	updateThrottleMs = 100;
+	constructor(client, creds, log) {
+		this.client = client;
+		this.creds = creds;
+		this.log = log;
+	}
+	async start(receiveId, receiveIdType = "chat_id", options) {
+		if (this.state) return;
+		const apiBase = resolveApiBase(this.creds.domain);
+		const cardJson = {
+			schema: "2.0",
+			config: {
+				streaming_mode: true,
+				summary: { content: "[Generating...]" },
+				streaming_config: {
+					print_frequency_ms: { default: 50 },
+					print_step: { default: 1 }
+				}
+			},
+			body: { elements: [{
+				tag: "markdown",
+				content: "⏳ Thinking...",
+				element_id: "content"
+			}] }
+		};
+		if (options?.header) cardJson.header = {
+			title: {
+				tag: "plain_text",
+				content: options.header.title
+			},
+			template: options.header.template ?? "blue"
+		};
+		const { response: createRes, release: releaseCreate } = await fetchWithSsrFGuard({
+			url: `${apiBase}/cardkit/v1/cards`,
+			init: {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${await getToken(this.creds)}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({
+					type: "card_json",
+					data: JSON.stringify(cardJson)
+				})
+			},
+			policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+			auditContext: "feishu.streaming-card.create"
+		});
+		if (!createRes.ok) {
+			await releaseCreate();
+			throw new Error(`Create card request failed with HTTP ${createRes.status}`);
+		}
+		const createData = await createRes.json();
+		await releaseCreate();
+		if (createData.code !== 0 || !createData.data?.card_id) throw new Error(`Create card failed: ${createData.msg}`);
+		const cardId = createData.data.card_id;
+		const cardContent = JSON.stringify({
+			type: "card",
+			data: { card_id: cardId }
+		});
+		let sendRes;
+		const sendOptions = options ?? {};
+		const sendMode = resolveStreamingCardSendMode(sendOptions);
+		if (sendMode === "reply") sendRes = await this.client.im.message.reply({
+			path: { message_id: sendOptions.replyToMessageId },
+			data: {
+				msg_type: "interactive",
+				content: cardContent,
+				...sendOptions.replyInThread ? { reply_in_thread: true } : {}
+			}
+		});
+		else if (sendMode === "root_create") sendRes = await this.client.im.message.create({
+			params: { receive_id_type: receiveIdType },
+			data: Object.assign({
+				receive_id: receiveId,
+				msg_type: "interactive",
+				content: cardContent
+			}, { root_id: sendOptions.rootId })
+		});
+		else sendRes = await this.client.im.message.create({
+			params: { receive_id_type: receiveIdType },
+			data: {
+				receive_id: receiveId,
+				msg_type: "interactive",
+				content: cardContent
+			}
+		});
+		if (sendRes.code !== 0 || !sendRes.data?.message_id) throw new Error(`Send card failed: ${sendRes.msg}`);
+		this.state = {
+			cardId,
+			messageId: sendRes.data.message_id,
+			sequence: 1,
+			currentText: ""
+		};
+		this.log?.(`Started streaming: cardId=${cardId}, messageId=${sendRes.data.message_id}`);
+	}
+	async updateCardContent(text, onError) {
+		if (!this.state) return;
+		const apiBase = resolveApiBase(this.creds.domain);
+		this.state.sequence += 1;
+		await fetchWithSsrFGuard({
+			url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`,
+			init: {
+				method: "PUT",
+				headers: {
+					Authorization: `Bearer ${await getToken(this.creds)}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({
+					content: text,
+					sequence: this.state.sequence,
+					uuid: `s_${this.state.cardId}_${this.state.sequence}`
+				})
+			},
+			policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+			auditContext: "feishu.streaming-card.update"
+		}).then(async ({ release }) => {
+			await release();
+		}).catch((error) => onError?.(error));
+	}
+	async update(text) {
+		if (!this.state || this.closed) return;
+		const mergedInput = mergeStreamingText(this.pendingText ?? this.state.currentText, text);
+		if (!mergedInput || mergedInput === this.state.currentText) return;
+		const now = Date.now();
+		if (now - this.lastUpdateTime < this.updateThrottleMs) {
+			this.pendingText = mergedInput;
+			return;
+		}
+		this.pendingText = null;
+		this.lastUpdateTime = now;
+		this.queue = this.queue.then(async () => {
+			if (!this.state || this.closed) return;
+			const mergedText = mergeStreamingText(this.state.currentText, mergedInput);
+			if (!mergedText || mergedText === this.state.currentText) return;
+			this.state.currentText = mergedText;
+			await this.updateCardContent(mergedText, (e) => this.log?.(`Update failed: ${String(e)}`));
+		});
+		await this.queue;
+	}
+	async close(finalText) {
+		if (!this.state || this.closed) return;
+		this.closed = true;
+		await this.queue;
+		const pendingMerged = mergeStreamingText(this.state.currentText, this.pendingText ?? void 0);
+		const text = finalText ? mergeStreamingText(pendingMerged, finalText) : pendingMerged;
+		const apiBase = resolveApiBase(this.creds.domain);
+		if (text && text !== this.state.currentText) {
+			await this.updateCardContent(text);
+			this.state.currentText = text;
+		}
+		this.state.sequence += 1;
+		await fetchWithSsrFGuard({
+			url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`,
+			init: {
+				method: "PATCH",
+				headers: {
+					Authorization: `Bearer ${await getToken(this.creds)}`,
+					"Content-Type": "application/json; charset=utf-8"
+				},
+				body: JSON.stringify({
+					settings: JSON.stringify({ config: {
+						streaming_mode: false,
+						summary: { content: truncateSummary(text) }
+					} }),
+					sequence: this.state.sequence,
+					uuid: `c_${this.state.cardId}_${this.state.sequence}`
+				})
+			},
+			policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+			auditContext: "feishu.streaming-card.close"
+		}).then(async ({ release }) => {
+			await release();
+		}).catch((e) => this.log?.(`Close failed: ${String(e)}`));
+		this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
+	}
+	isActive() {
+		return this.state !== null && !this.closed;
+	}
+};
+//#endregion
+export { FeishuStreamingSession, mergeStreamingText };

package/dist/src/targets.js

@@ -0,0 +1,39 @@
+//#region src/targets.ts
+const CHAT_ID_PREFIX = "oc_";
+const OPEN_ID_PREFIX = "ou_";
+function stripProviderPrefix(raw) {
+	return raw.replace(/^(feishu|lark):/i, "").trim();
+}
+function normalizeFeishuTarget(raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) return null;
+	const withoutProvider = stripProviderPrefix(trimmed);
+	const lowered = withoutProvider.toLowerCase();
+	if (lowered.startsWith("chat:")) return withoutProvider.slice(5).trim() || null;
+	if (lowered.startsWith("group:")) return withoutProvider.slice(6).trim() || null;
+	if (lowered.startsWith("channel:")) return withoutProvider.slice(8).trim() || null;
+	if (lowered.startsWith("user:")) return withoutProvider.slice(5).trim() || null;
+	if (lowered.startsWith("dm:")) return withoutProvider.slice(3).trim() || null;
+	if (lowered.startsWith("open_id:")) return withoutProvider.slice(8).trim() || null;
+	return withoutProvider;
+}
+function resolveReceiveIdType(id) {
+	const trimmed = id.trim();
+	const lowered = trimmed.toLowerCase();
+	if (lowered.startsWith("chat:") || lowered.startsWith("group:") || lowered.startsWith("channel:")) return "chat_id";
+	if (lowered.startsWith("open_id:")) return "open_id";
+	if (lowered.startsWith("user:") || lowered.startsWith("dm:")) return trimmed.replace(/^(user|dm):/i, "").trim().startsWith(OPEN_ID_PREFIX) ? "open_id" : "user_id";
+	if (trimmed.startsWith(CHAT_ID_PREFIX)) return "chat_id";
+	if (trimmed.startsWith(OPEN_ID_PREFIX)) return "open_id";
+	return "user_id";
+}
+function looksLikeFeishuId(raw) {
+	const trimmed = stripProviderPrefix(raw.trim());
+	if (!trimmed) return false;
+	if (/^(chat|group|channel|user|dm|open_id):/i.test(trimmed)) return true;
+	if (trimmed.startsWith(CHAT_ID_PREFIX)) return true;
+	if (trimmed.startsWith(OPEN_ID_PREFIX)) return true;
+	return false;
+}
+//#endregion
+export { looksLikeFeishuId, normalizeFeishuTarget, resolveReceiveIdType };

package/dist/src/task-comment.js

@@ -0,0 +1,76 @@
+import { StringEnum, assertLarkOk, createToolContext, handleInvokeError, json, registerTool } from "./user-tool-helpers.js";
+import { Type } from "@sinclair/typebox";
+//#region src/task-comment.ts
+const CommentSchema = Type.Union([
+	Type.Object({
+		action: Type.Literal("create"),
+		task_guid: Type.String(),
+		content: Type.String(),
+		reply_to_comment_id: Type.Optional(Type.String())
+	}),
+	Type.Object({
+		action: Type.Literal("list"),
+		resource_id: Type.String(),
+		direction: Type.Optional(StringEnum(["asc", "desc"])),
+		page_size: Type.Optional(Type.Number()),
+		page_token: Type.Optional(Type.String())
+	}),
+	Type.Object({
+		action: Type.Literal("get"),
+		comment_id: Type.String()
+	})
+]);
+function registerFeishuTaskCommentTool(api) {
+	const { toolClient } = createToolContext(api, "feishu_task_comment");
+	registerTool(api, {
+		name: "feishu_task_comment",
+		label: "Feishu Task Comment",
+		description: "按本人身份创建、获取、列出任务评论。",
+		parameters: CommentSchema,
+		async execute(_toolCallId, params) {
+			const payload = params;
+			try {
+				const client = toolClient();
+				if (payload.action === "create") {
+					const response = await client.invoke("feishu_task_comment.create", (sdk, opts) => sdk.task.v2.comment.create({
+						params: { user_id_type: "open_id" },
+						data: {
+							content: payload.content,
+							resource_type: "task",
+							resource_id: payload.task_guid,
+							reply_to_comment_id: payload.reply_to_comment_id
+						}
+					}, opts), { as: "user" });
+					assertLarkOk(response);
+					return json({ comment: response.data?.comment });
+				}
+				if (payload.action === "get") {
+					const response = await client.invoke("feishu_task_comment.get", (sdk, opts) => sdk.task.v2.comment.get({
+						path: { comment_id: payload.comment_id },
+						params: { user_id_type: "open_id" }
+					}, opts), { as: "user" });
+					assertLarkOk(response);
+					return json({ comment: response.data?.comment });
+				}
+				const response = await client.invoke("feishu_task_comment.list", (sdk, opts) => sdk.task.v2.comment.list({ params: {
+					resource_type: "task",
+					resource_id: payload.resource_id,
+					direction: payload.direction,
+					page_size: payload.page_size,
+					page_token: payload.page_token,
+					user_id_type: "open_id"
+				} }, opts), { as: "user" });
+				assertLarkOk(response);
+				return json({
+					comments: response.data?.items ?? [],
+					has_more: response.data?.has_more ?? false,
+					page_token: response.data?.page_token
+				});
+			} catch (error) {
+				return handleInvokeError(error, api);
+			}
+		}
+	}, { name: "feishu_task_comment" });
+}
+//#endregion
+export { registerFeishuTaskCommentTool };

package/dist/src/task-shared.js

@@ -0,0 +1,13 @@
+import { parseTimeToTimestampMs } from "./user-tool-helpers.js";
+//#region src/task-shared.ts
+function normalizeTaskTime(input) {
+	if (!input) return void 0;
+	const ts = parseTimeToTimestampMs(input.timestamp);
+	if (!ts) throw new Error("任务时间字段必须是带时区的 ISO 8601 / RFC 3339 时间。");
+	return {
+		timestamp: ts,
+		is_all_day: input.is_all_day ?? false
+	};
+}
+//#endregion
+export { normalizeTaskTime };