@modesto_ma/dsh-channels 0.5.0-beta.2 → 0.5.0-beta.3

package/lib/index.js

@@ -3400,26 +3400,72 @@ const SEND_FILE_REQUIREMENT = {
 	level: "optional",
 	purpose: "上传图片/文件，让模型用 feishu_send_file 把生成的文件发给用户"
 };
-/** Wiki read needs (`feishu_wiki_list` / `feishu_wiki_read`). */
-const WIKI_READ_REQUIREMENTS = [{
-	anyOf: ["wiki:wiki", "wiki:wiki:readonly"],
+/** Spreadsheet and Base read needs, shared by the wiki read and write sets. */
+const SHEET_BASE_READ_REQUIREMENTS = [{
+	anyOf: [
+		"sheets:spreadsheet",
+		"sheets:spreadsheet:readonly",
+		"sheets:spreadsheet:read"
+	],
 	level: "optional",
-	purpose: "浏览知识库节点（feishu_wiki_list / feishu_wiki_read）"
+	purpose: "读取知识库电子表格（feishu_wiki_sheet_read）"
 }, {
-	anyOf: ["docx:document", "docx:document:readonly"],
+	anyOf: [
+		"bitable:app",
+		"bitable:app:readonly",
+		"base:record:read"
+	],
 	level: "optional",
-	purpose: "读取知识库中的文档内容（feishu_wiki_read）"
+	purpose: "读取知识库多维表格（feishu_wiki_base_read）"
 }];
+/** Wiki read needs (`feishu_wiki_list` / `feishu_wiki_read` and the sheet/base read tools). */
+const WIKI_READ_REQUIREMENTS = [
+	{
+		anyOf: ["wiki:wiki", "wiki:wiki:readonly"],
+		level: "optional",
+		purpose: "浏览知识库节点（feishu_wiki_list / feishu_wiki_read）"
+	},
+	{
+		anyOf: ["docx:document", "docx:document:readonly"],
+		level: "optional",
+		purpose: "读取知识库中的文档内容（feishu_wiki_read）"
+	},
+	...SHEET_BASE_READ_REQUIREMENTS
+];
 /** Wiki write needs (`feishu_wiki_create` / `feishu_wiki_edit`). */
-const WIKI_WRITE_REQUIREMENTS = [{
-	anyOf: ["wiki:wiki"],
-	level: "optional",
-	purpose: "在知识库中新建节点（feishu_wiki_create）"
-}, {
-	anyOf: ["docx:document"],
-	level: "optional",
-	purpose: "写入与修改知识库文档内容（feishu_wiki_create / feishu_wiki_edit）"
-}];
+const WIKI_WRITE_REQUIREMENTS = [
+	{
+		anyOf: ["wiki:wiki"],
+		level: "optional",
+		purpose: "在知识库中新建节点（feishu_wiki_create）"
+	},
+	{
+		anyOf: ["docx:document"],
+		level: "optional",
+		purpose: "写入与修改知识库文档内容（feishu_wiki_create / feishu_wiki_edit）"
+	},
+	{
+		anyOf: ["sheets:spreadsheet", "sheets:spreadsheet:write_only"],
+		level: "optional",
+		purpose: "写入知识库电子表格（feishu_wiki_sheet_edit）"
+	},
+	{
+		anyOf: ["bitable:app", "base:record:create"],
+		level: "optional",
+		purpose: "新增知识库多维表格记录（feishu_wiki_base_edit）"
+	},
+	{
+		anyOf: ["bitable:app", "base:record:update"],
+		level: "optional",
+		purpose: "修改本应用创建的多维表格中的记录（feishu_wiki_base_edit）"
+	},
+	{
+		anyOf: ["bitable:app", "base:record:delete"],
+		level: "optional",
+		purpose: "删除本应用创建的多维表格中的记录（feishu_wiki_base_edit）"
+	},
+	...SHEET_BASE_READ_REQUIREMENTS
+];
 /** Group receive needs while ordinary group messages require an @ mention. */
 const MENTION_GROUP_REQUIREMENTS = [{
 	anyOf: ["im:message.group_at_msg:readonly", "im:message.group_msg"],
@@ -3548,6 +3594,14 @@ function thrownError(error) {
 	if (code === void 0 && msg === void 0) return new FeishuApiError(error instanceof Error ? error.message : String(error));
 	return new FeishuApiError([code === void 0 ? void 0 : `code=${code}`, msg].filter(Boolean).join(" "), code);
 }
+/**
+* One Feishu OpenAPI call: unwraps `data` and maps a transport error or a
+* non-zero `code` to {@link FeishuApiError}.
+*
+* @param request The SDK's generic request.
+* @param input Method, URL, query, and body.
+* @returns The response `data`.
+*/
 async function call(request, input) {
 	let response;
 	try {
@@ -3574,6 +3628,12 @@ function wikiNode(raw, where) {
 		...raw.url === void 0 || raw.url === "" ? {} : { url: raw.url }
 	};
 }
+/**
+* Encode one URL path segment.
+*
+* @param value Raw segment.
+* @returns The encoded segment.
+*/
 function segment(value) {
 	return encodeURIComponent(value);
 }
@@ -3618,13 +3678,13 @@ function createWikiApi(request) {
 				...data.has_more === true && data.page_token !== void 0 && data.page_token !== "" ? { pageToken: data.page_token } : {}
 			};
 		},
-		async createDocxNode(spaceId, parentNodeToken, title) {
+		async createNode(spaceId, parentNodeToken, title, objType) {
 			const url = `/open-apis/wiki/v2/spaces/${segment(spaceId)}/nodes`;
 			return wikiNode((await call(request, {
 				method: "POST",
 				url,
 				data: {
-					obj_type: "docx",
+					obj_type: objType,
 					node_type: "origin",
 					title,
 					...parentNodeToken === void 0 ? {} : { parent_node_token: parentNodeToken }
@@ -3695,6 +3755,292 @@ function createWikiApi(request) {
 	};
 }
 //#endregion
+//#region src/feishu/wiki/base-api.ts
+/**
+* Feishu Base (多维表格) calls used by the wiki base tools, made with the app
+* identity (tenant access token).
+*
+* Everything goes through `base/v3/bases/:base_token/...` (the legacy
+* `bitable/v1` API is not used). Record reads return a column matrix that
+* this module turns into one field map per record; record writes take flat
+* maps keyed by field name or field id. Writes carry no precondition, are
+* applied asynchronously (a read straight after a write may not show it), and
+* must not run in parallel on one table.
+*
+* @module dsh-channels/feishu/wiki/base-api
+*/
+function stringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+function ignoredFieldsOf(value) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((item) => {
+		if (typeof item !== "object" || item === null) return [];
+		const { name, id, reason } = item;
+		const label = typeof name === "string" && name !== "" ? name : typeof id === "string" ? id : "?";
+		return [typeof reason === "string" && reason !== "" ? `${label}: ${reason}` : label];
+	});
+}
+function recordPage(raw, where) {
+	const names = stringArray(raw.fields) ?? [];
+	const ids = stringArray(raw.record_id_list) ?? [];
+	const rows = Array.isArray(raw.data) ? raw.data : [];
+	if (rows.length !== ids.length) throw new FeishuApiError(`${where}: record ids and rows differ in length`);
+	return {
+		records: ids.map((recordId, index) => {
+			const row = rows[index];
+			if (!Array.isArray(row) || row.length !== names.length) throw new FeishuApiError(`${where}: row ${index} does not match the field list`);
+			return {
+				recordId,
+				fields: Object.fromEntries(names.map((name, column) => [name, row[column] ?? null]))
+			};
+		}),
+		hasMore: raw.has_more === true,
+		...typeof raw.rev === "number" ? { rev: raw.rev } : {},
+		...typeof raw.timezone === "string" && raw.timezone !== "" ? { timezone: raw.timezone } : {},
+		ignoredFields: ignoredFieldsOf(raw.ignored_fields)
+	};
+}
+/**
+* {@link BaseApi} over the SDK's generic authenticated request.
+*
+* @param request `Client.request` of the connected SDK client.
+* @returns The API.
+*/
+function createBaseApi(request) {
+	const tablePath = (baseToken, tableId) => `/open-apis/base/v3/bases/${segment(baseToken)}/tables/${segment(tableId)}`;
+	return {
+		async listTables(baseToken) {
+			const data = await call(request, {
+				method: "GET",
+				url: `/open-apis/base/v3/bases/${segment(baseToken)}/tables`,
+				params: {
+					offset: 0,
+					limit: 300
+				}
+			});
+			return (Array.isArray(data.tables) ? data.tables : Array.isArray(data.items) ? data.items : []).flatMap((item) => {
+				if (typeof item !== "object" || item === null) return [];
+				const { id, table_id, name, table_name } = item;
+				const tableId = typeof id === "string" ? id : typeof table_id === "string" ? table_id : void 0;
+				if (tableId === void 0) return [];
+				return [{
+					tableId,
+					name: typeof name === "string" ? name : typeof table_name === "string" ? table_name : ""
+				}];
+			});
+		},
+		async listFields(baseToken, tableId) {
+			const data = await call(request, {
+				method: "GET",
+				url: `${tablePath(baseToken, tableId)}/fields`,
+				params: {
+					offset: 0,
+					limit: 300
+				}
+			});
+			return (Array.isArray(data.fields) ? data.fields : Array.isArray(data.items) ? data.items : []).flatMap((item) => {
+				if (typeof item !== "object" || item === null) return [];
+				const { id, field_id, name, field_name, type, ...properties } = item;
+				const fieldId = typeof id === "string" ? id : typeof field_id === "string" ? field_id : void 0;
+				if (fieldId === void 0) return [];
+				return [{
+					fieldId,
+					name: typeof name === "string" ? name : typeof field_name === "string" ? field_name : "",
+					type: typeof type === "string" ? type : "not_support",
+					properties
+				}];
+			});
+		},
+		async listRecords(baseToken, tableId, query) {
+			const url = `${tablePath(baseToken, tableId)}/records`;
+			const params = new URLSearchParams({
+				offset: String(query.offset),
+				limit: String(query.limit)
+			});
+			for (const field of query.fields ?? []) params.append("field_id", field);
+			if (query.viewId !== void 0) params.set("view_id", query.viewId);
+			if (query.filter !== void 0) params.set("filter", JSON.stringify(query.filter));
+			if (query.sort !== void 0) params.set("sort", JSON.stringify(query.sort));
+			return recordPage(await call(request, {
+				method: "GET",
+				url: `${url}?${params.toString()}`
+			}), url);
+		},
+		async searchRecords(baseToken, tableId, search) {
+			const url = `${tablePath(baseToken, tableId)}/records/search`;
+			return recordPage(await call(request, {
+				method: "POST",
+				url,
+				data: {
+					keyword: search.keyword,
+					search_fields: search.searchFields,
+					...search.fields === void 0 ? {} : { select_fields: search.fields },
+					...search.viewId === void 0 ? {} : { view_id: search.viewId },
+					...search.filter === void 0 ? {} : { filter: search.filter },
+					...search.sort === void 0 ? {} : { sort: search.sort },
+					offset: search.offset,
+					limit: search.limit
+				}
+			}), url);
+		},
+		async createRecords(baseToken, tableId, records) {
+			return stringArray((await call(request, {
+				method: "POST",
+				url: `${tablePath(baseToken, tableId)}/records/batch_create`,
+				data: { create_records: records }
+			})).record_id_list) ?? [];
+		},
+		async updateRecords(baseToken, tableId, updates) {
+			return ignoredFieldsOf((await call(request, {
+				method: "POST",
+				url: `${tablePath(baseToken, tableId)}/records/batch_update`,
+				data: { update_records: updates }
+			})).ignored_fields);
+		},
+		async deleteRecords(baseToken, tableId, recordIds) {
+			await call(request, {
+				method: "POST",
+				url: `${tablePath(baseToken, tableId)}/records/batch_delete`,
+				data: { record_id_list: recordIds }
+			});
+		}
+	};
+}
+//#endregion
+//#region src/feishu/wiki/sheet-api.ts
+/**
+* Feishu spreadsheet (电子表格) calls used by the wiki sheet tools, made with
+* the app identity (tenant access token).
+*
+* Everything goes through the `sheet_ai/v2` tool endpoints: `POST
+* spreadsheets/:token/tools/invoke_read` (or `invoke_write`) with body
+* `{tool_name, input}`, where `input` is a JSON string that also carries
+* `excel_id`, and the result is the JSON string `data.output`. Read tools sent
+* to `invoke_write` (or the reverse) are rejected by the gateway. Writes carry
+* no base revision and no idempotency key; callers check the workbook
+* revision before writing.
+*
+* @module dsh-channels/feishu/wiki/sheet-api
+*/
+function invokePath(token, kind) {
+	return `/open-apis/sheet_ai/v2/spreadsheets/${segment(token)}/tools/invoke_${kind}`;
+}
+async function invoke(request, token, kind, toolName, input) {
+	const data = await call(request, {
+		method: "POST",
+		url: invokePath(token, kind),
+		data: {
+			tool_name: toolName,
+			input: JSON.stringify({
+				excel_id: token,
+				...input
+			})
+		}
+	});
+	if (typeof data.output !== "string" || data.output === "") return {};
+	let output;
+	try {
+		output = JSON.parse(data.output);
+	} catch (error) {
+		throw new FeishuApiError(`${toolName}: output is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (Array.isArray(output)) return { sheets: output };
+	if (typeof output !== "object" || output === null) throw new FeishuApiError(`${toolName}: output is not an object`);
+	return output;
+}
+function optionalString(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+function optionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function sheetInfo(raw, position) {
+	const sheetId = optionalString(raw.sheet_id);
+	if (sheetId === void 0) return void 0;
+	const rowCount = optionalNumber(raw.row_count);
+	const columnCount = optionalNumber(raw.column_count);
+	return {
+		sheetId,
+		title: optionalString(raw.title) ?? optionalString(raw.sheet_name) ?? "",
+		index: optionalNumber(raw.index) ?? position,
+		resourceType: optionalString(raw.resource_type) ?? "sheet",
+		hidden: raw.hidden === true || raw.is_hidden === true,
+		...rowCount === void 0 ? {} : { rowCount },
+		...columnCount === void 0 ? {} : { columnCount }
+	};
+}
+function cellOf(value) {
+	if (value === null) return {};
+	if (typeof value === "string" && value.startsWith("=")) return { formula: value };
+	return { value };
+}
+/**
+* {@link SheetApi} over the SDK's generic authenticated request.
+*
+* @param request `Client.request` of the connected SDK client.
+* @returns The API.
+*/
+function formulaError(raw) {
+	if (typeof raw !== "object" || raw === null) return [];
+	const entry = raw;
+	const cell = optionalString(entry.cell);
+	if (cell === void 0) return [];
+	const formula = optionalString(entry.formula);
+	const errorType = optionalString(entry.error_type);
+	const detail = optionalString(entry.detail);
+	return [{
+		cell,
+		...formula === void 0 ? {} : { formula },
+		...errorType === void 0 ? {} : { errorType },
+		...detail === void 0 ? {} : { detail }
+	}];
+}
+function createSheetApi(request) {
+	return {
+		async workbook(token) {
+			const output = await invoke(request, token, "read", "get_workbook_structure", {});
+			const sheets = (Array.isArray(output.sheets) ? output.sheets : []).flatMap((raw, position) => {
+				const info = typeof raw === "object" && raw !== null ? sheetInfo(raw, position) : void 0;
+				return info === void 0 ? [] : [info];
+			});
+			const revision = optionalNumber(output.revision);
+			return {
+				...revision === void 0 ? {} : { revision },
+				sheets
+			};
+		},
+		async readCsv(token, read) {
+			const output = await invoke(request, token, "read", "get_range_as_csv", {
+				sheet_id: read.sheetId,
+				range: read.range,
+				max_chars: read.maxChars,
+				max_rows: 1e9,
+				skip_hidden: false
+			});
+			const actualRange = optionalString(output.actual_range);
+			const currentRegion = optionalString(output.current_region);
+			const warning = optionalString(output.warning_message);
+			return {
+				csv: typeof output.annotated_csv === "string" ? output.annotated_csv : "",
+				...actualRange === void 0 ? {} : { actualRange },
+				...currentRegion === void 0 ? {} : { currentRegion },
+				hasMore: output.has_more === true,
+				...warning === void 0 ? {} : { warning }
+			};
+		},
+		async writeCells(token, write) {
+			const output = await invoke(request, token, "write", "set_cell_range", {
+				sheet_id: write.sheetId,
+				range: write.range,
+				cells: write.rows.map((row) => row.map(cellOf)),
+				...write.allowOverwrite === false ? { allow_overwrite: false } : {}
+			});
+			return { formulaErrors: (Array.isArray(output.formula_errors) ? output.formula_errors : []).flatMap(formulaError) };
+		}
+	};
+}
+//#endregion
 //#region src/feishu-channel.ts
 /**
 * Thin wrapper over the official SDK's `createLarkChannel` high-level module.
@@ -3888,6 +4234,8 @@ var LarkChannelAdapter = class {
 	dmMode;
 	slashCommands;
 	wiki;
+	sheets;
+	bases;
 	constructor(options) {
 		this.channel = createLarkChannel({
 			appId: options.appId,
@@ -3906,7 +4254,10 @@ var LarkChannelAdapter = class {
 		this.dmMode = options.dmMode;
 		const rawClient = this.channel.rawClient;
 		this.slashCommands = slashCommandApi(async (input) => await rawClient.request(input));
-		this.wiki = createWikiApi(async (input) => await rawClient.request(input));
+		const wikiRequest = async (input) => await rawClient.request(input);
+		this.wiki = createWikiApi(wikiRequest);
+		this.sheets = createSheetApi(wikiRequest);
+		this.bases = createBaseApi(wikiRequest);
 	}
 	onMessage(handler) {
 		return this.channel.on("message", (message) => {
@@ -9921,6 +10272,112 @@ var WikiConsent = class {
 		})) entry.resolve(outcome);
 	}
 };
+const FAILURE_REASONS = {
+	TOOL_DISABLED: "知识库工具已在插件配置中关闭",
+	ROUTE_NOT_FOUND: "当前会话没有绑定飞书话题，无法确定授权人",
+	NOT_AUTHORIZED: "当前话题的发起人不在知识库白名单中；请管理员发送 /auth wiki add @该用户 后重试",
+	CHANNEL_UNAVAILABLE: "飞书连接当前不可用，请稍后重试",
+	INVALID_REFERENCE: "无法识别的知识库引用：请传知识库节点链接 https://<租户>.feishu.cn/wiki/<node_token>、node_token，或知识空间链接 https://<租户>.feishu.cn/wiki/space/<space_id>",
+	INVALID_OPERATION: "操作参数不正确",
+	OUTSIDE_ROOTS: "该位置不在插件配置的知识库范围（wikiRoots）内，不能访问",
+	NOT_FOUND: "知识库节点不存在或已被删除",
+	NO_ACCESS: "机器人对该知识库节点没有访问权限；请知识库管理员把应用（或包含机器人的群）加为该空间成员",
+	UNSUPPORTED_TYPE: "这个工具不支持该类型的节点：飞书文档（docx）用 feishu_wiki_read / feishu_wiki_edit，电子表格（sheet）用 feishu_wiki_sheet_read / feishu_wiki_sheet_edit，多维表格（bitable）用 feishu_wiki_base_read / feishu_wiki_base_edit；其他类型暂不支持",
+	NOT_OWNED: "只能修改由本应用创建（所有者是本应用）的文档",
+	REVISION_CONFLICT: "文档在你读取之后被修改过；请重新用 feishu_wiki_read 读取最新内容，基于新的 revision_id 再修改",
+	CONSENT_DENIED: "话题发起人拒绝了这次知识库操作",
+	CONSENT_EXPIRED: "话题发起人没有在授权卡有效期内确认，已自动拒绝",
+	CONSENT_UNAVAILABLE: "授权卡发送失败，无法征得话题发起人同意，已取消操作",
+	PERMISSION_DENIED: "飞书拒绝调用：应用缺少知识库或文档权限（wiki:wiki、docx:document），请管理员在开发者后台开通并发布版本",
+	CONTENT_FAILED: "文档已创建，但写入内容失败",
+	EDIT_FAILED: "修改失败",
+	EDIT_PARTIAL: "飞书报告操作只部分生效；已停止后续操作，请用 feishu_wiki_read 读取最新内容核验后再继续",
+	API_FAILED: "飞书接口调用失败",
+	ABORTED: "已取消"
+};
+function failure(code, reason) {
+	return {
+		ok: false,
+		code,
+		reason: reason ?? FAILURE_REASONS[code]
+	};
+}
+function parseArgs(tool, schema, rawArgs) {
+	const parsed = schema.safeParse(rawArgs);
+	if (parsed.success) return parsed.data;
+	const issue = parsed.error.issues[0];
+	const where = issue === void 0 || issue.path.length === 0 ? "arguments" : issue.path.join(".");
+	throw new Error(`${tool}: invalid ${where}: ${issue?.message ?? "invalid arguments"}`);
+}
+/** Run one gated call body, mapping thrown Feishu errors to failures. */
+async function guarded$1(deps, tool, body) {
+	try {
+		return await body();
+	} catch (error) {
+		const mapped = failureOf(error);
+		if (mapped.code === "API_FAILED") deps.warn("dsh-channels: %s failed: %s", tool, mapped.reason);
+		return mapped;
+	}
+}
+/** Feishu codes: node missing/deleted, no resource access, missing app scope. */
+const NOT_FOUND_CODES = /* @__PURE__ */ new Set([
+	131005,
+	131012,
+	131013,
+	131014,
+	131016
+]);
+const NO_ACCESS_CODES = /* @__PURE__ */ new Set([
+	131006,
+	1770032,
+	1770002
+]);
+const PERMISSION_CODES = /* @__PURE__ */ new Set([99991672, 99991679]);
+function failureOf(error) {
+	const detail = describeError(error);
+	if (error instanceof FeishuApiError && error.code !== void 0) {
+		if (NOT_FOUND_CODES.has(error.code)) return failure("NOT_FOUND", `${FAILURE_REASONS.NOT_FOUND}（${detail}）`);
+		if (NO_ACCESS_CODES.has(error.code)) return failure("NO_ACCESS", `${FAILURE_REASONS.NO_ACCESS}（${detail}）`);
+		if (PERMISSION_CODES.has(error.code)) return failure("PERMISSION_DENIED", `${FAILURE_REASONS.PERMISSION_DENIED}（${detail}）`);
+	}
+	return failure("API_FAILED", `${FAILURE_REASONS.API_FAILED}：${detail}`);
+}
+function consentFailure(outcome) {
+	switch (outcome) {
+		case "allowed": return;
+		case "denied": return failure("CONSENT_DENIED");
+		case "expired": return failure("CONSENT_EXPIRED");
+		case "cancelled": return failure("ABORTED");
+		case "unavailable": return failure("CONSENT_UNAVAILABLE");
+	}
+}
+/** Whether the app owns a node: Feishu reports the bot open_id as the owner. */
+function ownedByApp(node, botOpenId) {
+	return botOpenId !== void 0 && botOpenId !== "" && node.owner === botOpenId;
+}
+/** A node's web link; falls back to the first root's origin. */
+function nodeUrl(roots, node) {
+	if (node.url !== void 0) return node.url;
+	const first = roots[0];
+	return `${first === void 0 ? "https://feishu.cn" : new URL(first.link).origin}/wiki/${node.nodeToken}`;
+}
+/** One-line clipped preview with Markdown control characters neutralized. */
+function preview(value, max = 80) {
+	const flat = value.replace(/\s+/gu, " ").trim().replace(/([[\]()*_`~<>])/gu, "\\$1");
+	return flat.length <= max ? flat : `${flat.slice(0, max)}…`;
+}
+/** A fenced preview of the first characters of a content. */
+function previewBlock(content) {
+	return `\`\`\`\n${(content.length <= 300 ? content : `${content.slice(0, 300)}\n…`).replace(/```/gu, "`​``")}\n\`\`\``;
+}
+function display(value) {
+	return typeof value === "string" ? preview(value, 120) : "?";
+}
+/** Readable, bounded text for a thrown value. */
+function describeError(error) {
+	const cleaned = (error instanceof FeishuApiError ? error.detail : error instanceof Error ? error.message : String(error)).replace(/[\u0000-\u001f\u007f]+/gu, " ").trim();
+	return cleaned.length <= 300 ? cleaned : `${cleaned.slice(0, 300)}…`;
+}
 //#endregion
 //#region src/feishu/wiki/links.ts
 /**
@@ -9985,99 +10442,1040 @@ function parseWikiRootLink(link) {
 		}
 	};
 	return {
-		ok: false,
-		error: "not-a-wiki-link"
+		ok: false,
+		error: "not-a-wiki-link"
+	};
+}
+/**
+* Parse every configured root. Callers validate the config first, so an
+* invalid entry here is a programming error.
+*
+* @param links Validated `wikiRoots` entries.
+* @returns The parsed roots, in configuration order.
+*/
+function parseWikiRoots(links) {
+	return links.map((link) => {
+		const parsed = parseWikiRootLink(link);
+		if (!parsed.ok) throw new Error(`dsh-channels: invalid wikiRoots entry ${link}: ${WIKI_ROOT_LINK_ERRORS[parsed.error]}`);
+		return parsed.root;
+	});
+}
+/**
+* Parse a model-supplied reference: a wiki node link, a docx link, a space
+* link, or a bare node token.
+*
+* @param input Raw tool argument.
+* @returns The reference, or `undefined` when it names nothing recognizable.
+*/
+function parseWikiRef(input) {
+	const trimmed = input.trim();
+	if (TOKEN_PATTERN.test(trimmed)) return {
+		kind: "node",
+		token: trimmed
+	};
+	let url;
+	try {
+		url = new URL(trimmed);
+	} catch {
+		return;
+	}
+	if (url.protocol !== "https:") return void 0;
+	const segments = url.pathname.split("/").filter((segment) => segment !== "");
+	if (segments[0] === "wiki" && segments.length === 3 && segments[1] === "space" && SPACE_ID_PATTERN.test(segments[2])) return {
+		kind: "space",
+		spaceId: segments[2]
+	};
+	if (segments.length === 2 && TOKEN_PATTERN.test(segments[1])) {
+		if (segments[0] === "wiki" && segments[1] !== "space") return {
+			kind: "node",
+			token: segments[1]
+		};
+		if (segments[0] === "docx") return {
+			kind: "docx",
+			token: segments[1]
+		};
+	}
+}
+//#endregion
+//#region src/feishu/wiki/scope.ts
+/**
+* Longest parent chain walked for a node root. Feishu limits wiki depth well
+* below this; a longer chain is treated as outside.
+*/
+const MAX_PARENT_DEPTH = 64;
+/**
+* Find the configured root containing `node`.
+*
+* @param api Wiki endpoints (for parent lookups).
+* @param roots Configured roots.
+* @param node The node to check.
+* @returns The containing root, or `undefined` when none contains it.
+*/
+async function containingRoot(api, roots, node) {
+	for (const root of roots) if (root.kind === "space" && root.spaceId === node.spaceId) return { root };
+	const nodeRoots = roots.filter((root) => root.kind === "node");
+	if (nodeRoots.length === 0) return void 0;
+	const byToken = new Map(nodeRoots.map((root) => [root.nodeToken, root]));
+	let current = node;
+	for (let depth = 0; depth <= MAX_PARENT_DEPTH; depth += 1) {
+		const match = byToken.get(current.nodeToken);
+		if (match !== void 0) return { root: match };
+		if (current.parentNodeToken === void 0) return void 0;
+		current = await api.getNode(current.parentNodeToken, "wiki");
+	}
+}
+/**
+* Whether a whole space (its top level) is inside the roots: only a space
+* root covers a space's top level.
+*
+* @param roots Configured roots.
+* @param spaceId The space.
+* @returns True when a space root names it.
+*/
+function spaceIsRoot(roots, spaceId) {
+	return roots.some((root) => root.kind === "space" && root.spaceId === spaceId);
+}
+//#endregion
+//#region src/feishu/wiki/base-tools.ts
+/**
+* Wiki Base (多维表格) tools: `feishu_wiki_base_read` (switch
+* `feishuTools.wikiRead`) and `feishu_wiki_base_edit` (switch
+* `feishuTools.wikiWrite`).
+*
+* Both run through the same gates as the docx tools (whitelist, `wikiRoots`
+* containment, consent cards). Reading shares the docx read grant per Session
+* and document. Editing changes records only (no table or field structure):
+* on a base the app owns it may create, update, and delete records; on any
+* other base it may only create records, so existing data written by people
+* is never changed. Every edit asks on a consent card. Feishu offers no
+* revision precondition for record writes, and applies them asynchronously.
+*
+* @module dsh-channels/feishu/wiki/base-tools
+*/
+/** Model-facing tool names; stable across releases (session history references them). */
+const WIKI_BASE_READ_TOOL_NAME = "feishu_wiki_base_read";
+const WIKI_BASE_EDIT_TOOL_NAME = "feishu_wiki_base_edit";
+/** Record page size bounds of `feishu_wiki_base_read`. */
+const READ_DEFAULT_LIMIT = 50;
+const READ_MAX_LIMIT = 200;
+/** Records of each operation shown on a consent card. */
+const CARD_PREVIEW_RECORDS = 3;
+const refSchema$2 = z.string().trim().min(1).max(2048);
+const nameSchema = z.string().trim().min(1).max(200);
+const recordIdSchema = z.string().trim().min(1).max(64);
+const fieldMapSchema = z.record(z.string().min(1).max(200), z.unknown()).refine((map) => Object.keys(map).length > 0, "至少包含一个字段");
+const wikiBaseReadArgsSchema = z.object({
+	doc: refSchema$2,
+	table: nameSchema.optional(),
+	filter: z.object({
+		logic: z.enum(["and", "or"]).optional(),
+		conditions: z.array(z.array(z.unknown()).min(2).max(3)).min(1).max(50)
+	}).strict().optional(),
+	sort: z.array(z.object({
+		field: nameSchema,
+		desc: z.boolean().optional()
+	}).strict()).min(1).max(10).optional(),
+	keyword: z.string().trim().min(1).max(200).optional(),
+	search_fields: z.array(nameSchema).min(1).max(20).optional(),
+	fields: z.array(nameSchema).min(1).max(100).optional(),
+	view_id: nameSchema.optional(),
+	offset: z.number().int().min(0).optional(),
+	limit: z.number().int().min(1).max(READ_MAX_LIMIT).optional()
+}).strict();
+const baseOperationSchema = z.discriminatedUnion("command", [
+	z.object({
+		command: z.literal("create"),
+		records: z.array(fieldMapSchema).min(1).max(200)
+	}).strict(),
+	z.object({
+		command: z.literal("update"),
+		records: z.array(z.object({
+			record_id: recordIdSchema,
+			fields: fieldMapSchema
+		}).strict()).min(1).max(200)
+	}).strict(),
+	z.object({
+		command: z.literal("delete"),
+		record_ids: z.array(recordIdSchema).min(1).max(200)
+	}).strict()
+]);
+const wikiBaseEditArgsSchema = z.object({
+	doc: refSchema$2,
+	table: nameSchema,
+	operations: z.array(baseOperationSchema).min(1).max(10)
+}).strict();
+const READ_DESCRIPTION$2 = `读取知识库中的飞书多维表格（bitable）。doc 传知识库节点链接或 node_token。第一次读取某个多维表格会在话题里弹出授权卡，由话题发起人确认，确认后本话题内再次读取不再询问；等待期间不要重复调用。不传 table 时只返回数据表列表；传 table（table_id 或表名）时返回字段列表和记录。filter 形如 {"logic":"and","conditions":[["状态","intersects",["进行中"]],["金额",">=",100],["备注","non_empty"]]}，运算符有 == != > >= < <= intersects（包含）disjoint（不包含）empty non_empty；日期条件用 "ExactDate(2026-08-07)"，日期不支持 >=。sort 形如 [{"field":"更新时间","desc":true}]；keyword 为关键词搜索，search_fields 指定搜索的字段（默认主字段）；fields 只返回指定字段。分页用 offset/limit（limit 默认 ${READ_DEFAULT_LIMIT}，最多 ${READ_MAX_LIMIT}），has_more 为 true 时用 next_offset 继续。writable 说明能做哪些修改：all 表示可增改删记录（本应用创建的表），create 表示只能新增记录，none 表示不能修改。`;
+const EDIT_DESCRIPTION$2 = `修改知识库中飞书多维表格（bitable）某个数据表的记录。先用 feishu_wiki_base_read 读取字段列表，按字段名写入。operations 按顺序执行（最多 10 个，每个最多 200 条记录）：create（records 为字段名→值的对象数组）、update（records 为 {record_id, fields} 数组，只改给出的字段）、delete（record_ids）。本应用创建的多维表格可以增改删；其他多维表格只能新增记录，不能修改或删除已有记录。不会修改数据表和字段结构。单元格取值：文本为字符串；数字为数字；单选/多选为选项名数组（如 ["进行中"]，单选也是数组）；日期为 "2026-03-24 10:00" 或毫秒时间戳；复选框为布尔；人员为 [{"id":"ou_xxx"}]；关联为 [{"id":"rec_xxx"}]；null 清空。公式、查找引用、创建时间等字段只读。写入是异步生效的，立刻读取可能还看不到。每次修改都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。`;
+const REF_DESCRIPTION$2 = "知识库节点链接 https://<租户>.feishu.cn/wiki/<node_token> 或 node_token";
+const TABLE_PROPERTY = {
+	type: "string",
+	description: "数据表 table_id 或表名"
+};
+const FIELD_MAP_PROPERTY = {
+	type: "object",
+	description: "字段名（或字段 id）→ 值",
+	additionalProperties: true
+};
+const READ_PARAMETERS$2 = {
+	type: "object",
+	properties: {
+		doc: {
+			type: "string",
+			description: REF_DESCRIPTION$2
+		},
+		table: {
+			...TABLE_PROPERTY,
+			description: "数据表 table_id 或表名；不传只列出数据表"
+		},
+		filter: {
+			type: "object",
+			properties: {
+				logic: {
+					type: "string",
+					enum: ["and", "or"]
+				},
+				conditions: {
+					type: "array",
+					items: {
+						type: "array",
+						description: "[字段, 运算符, 值]；empty / non_empty 不带值"
+					}
+				}
+			},
+			required: ["conditions"],
+			additionalProperties: false
+		},
+		sort: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					field: { type: "string" },
+					desc: { type: "boolean" }
+				},
+				required: ["field"],
+				additionalProperties: false
+			}
+		},
+		keyword: {
+			type: "string",
+			description: "关键词搜索"
+		},
+		search_fields: {
+			type: "array",
+			items: { type: "string" },
+			description: "keyword 搜索的字段，默认主字段"
+		},
+		fields: {
+			type: "array",
+			items: { type: "string" },
+			description: "只返回这些字段"
+		},
+		view_id: {
+			type: "string",
+			description: "按视图读取（应用视图的筛选与排序）"
+		},
+		offset: {
+			type: "integer",
+			minimum: 0
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: READ_MAX_LIMIT
+		}
+	},
+	required: ["doc"],
+	additionalProperties: false
+};
+const EDIT_PARAMETERS$2 = {
+	type: "object",
+	properties: {
+		doc: {
+			type: "string",
+			description: REF_DESCRIPTION$2
+		},
+		table: TABLE_PROPERTY,
+		operations: {
+			type: "array",
+			minItems: 1,
+			maxItems: 10,
+			items: {
+				type: "object",
+				properties: {
+					command: {
+						type: "string",
+						enum: [
+							"create",
+							"update",
+							"delete"
+						]
+					},
+					records: {
+						type: "array",
+						maxItems: 200,
+						description: "create：字段映射数组；update：{record_id, fields} 数组",
+						items: {
+							type: "object",
+							properties: {
+								record_id: { type: "string" },
+								fields: FIELD_MAP_PROPERTY
+							},
+							additionalProperties: true
+						}
+					},
+					record_ids: {
+						type: "array",
+						maxItems: 200,
+						items: { type: "string" },
+						description: "delete 的记录 id"
+					}
+				},
+				required: ["command"],
+				additionalProperties: false
+			}
+		}
+	},
+	required: [
+		"doc",
+		"table",
+		"operations"
+	],
+	additionalProperties: false
+};
+async function baseTarget(kit, context, doc) {
+	const bases = context.bases;
+	if (bases === void 0) return failure("CHANNEL_UNAVAILABLE");
+	const ref = parseWikiRef(doc);
+	if (ref === void 0) return failure("INVALID_REFERENCE");
+	const node = await kit.containedNode(context, ref);
+	if ("ok" in node) return node;
+	if (node.objType !== "bitable") return failure("UNSUPPORTED_TYPE", `${failure("UNSUPPORTED_TYPE").reason}（该节点类型：${node.objType}）`);
+	return {
+		context,
+		bases,
+		node,
+		url: nodeUrl(context.roots, node)
+	};
+}
+function writableOf(kit, target) {
+	if (!kit.writeEnabled()) return "none";
+	return ownedByApp(target.node, target.context.botOpenId) ? "all" : "create";
+}
+function pickTable(tables, wanted) {
+	const match = tables.find((table) => table.tableId === wanted) ?? tables.find((table) => table.name === wanted);
+	if (match !== void 0) return match;
+	return `找不到数据表「${wanted}」；可用数据表：${tables.map((table) => `${table.name}（${table.tableId}）`).join("、") || "无"}`;
+}
+function fieldView(field) {
+	return {
+		...field.properties,
+		field_id: field.fieldId,
+		name: field.name,
+		type: field.type
+	};
+}
+async function read$1(kit, sessionId, rawArgs, signal) {
+	const args = parseArgs(WIKI_BASE_READ_TOOL_NAME, wikiBaseReadArgsSchema, rawArgs);
+	const gate = kit.gate(sessionId, WIKI_BASE_READ_TOOL_NAME);
+	if (!gate.ok) return gate;
+	return await guarded$1(kit, WIKI_BASE_READ_TOOL_NAME, async () => {
+		const target = await baseTarget(kit, gate.context, args.doc);
+		if ("ok" in target) return target;
+		const denied = await kit.readConsent(sessionId, target.context, target.node, signal);
+		if (denied !== void 0) return denied;
+		if (signal.aborted) return failure("ABORTED");
+		const token = target.node.objToken;
+		const tables = await target.bases.listTables(token);
+		const base = {
+			ok: true,
+			title: target.node.title,
+			node_token: target.node.nodeToken,
+			url: target.url,
+			tables: tables.map((table) => ({
+				table_id: table.tableId,
+				name: table.name
+			})),
+			writable: writableOf(kit, target)
+		};
+		if (args.table === void 0) return base;
+		const table = pickTable(tables, args.table);
+		if (typeof table === "string") return failure("INVALID_OPERATION", table);
+		const fields = await target.bases.listFields(token, table.tableId);
+		const offset = args.offset ?? 0;
+		const query = {
+			...args.filter === void 0 ? {} : { filter: args.filter },
+			...args.sort === void 0 ? {} : { sort: args.sort },
+			...args.fields === void 0 ? {} : { fields: args.fields },
+			...args.view_id === void 0 ? {} : { viewId: args.view_id },
+			offset,
+			limit: args.limit ?? READ_DEFAULT_LIMIT
+		};
+		let page;
+		if (args.keyword === void 0) page = await target.bases.listRecords(token, table.tableId, query);
+		else {
+			const primary = fields[0]?.name;
+			const searchFields = args.search_fields ?? (primary === void 0 ? [] : [primary]);
+			if (searchFields.length === 0) return failure("INVALID_OPERATION", "keyword 搜索需要 search_fields");
+			page = await target.bases.searchRecords(token, table.tableId, {
+				...query,
+				keyword: args.keyword,
+				searchFields
+			});
+		}
+		return {
+			...base,
+			table_id: table.tableId,
+			fields: fields.map(fieldView),
+			records: page.records.map((record) => ({
+				record_id: record.recordId,
+				fields: record.fields
+			})),
+			has_more: page.hasMore,
+			...page.hasMore ? { next_offset: offset + page.records.length } : {},
+			...page.timezone === void 0 ? {} : { timezone: page.timezone },
+			...page.ignoredFields.length === 0 ? {} : { ignored_fields: page.ignoredFields }
+		};
+	});
+}
+function json(value) {
+	return preview(JSON.stringify(value) ?? "null", 120);
+}
+function cardLines$1(operations, tableName) {
+	const lines = operations.map((operation, index) => {
+		const n = `${index + 1}.`;
+		switch (operation.command) {
+			case "create": {
+				const sample = operation.records.slice(0, CARD_PREVIEW_RECORDS).map((record) => `　${json(record)}`);
+				const more = operation.records.length > CARD_PREVIEW_RECORDS ? [`　…（共 ${operation.records.length} 条）`] : [];
+				return [
+					`${n} 新增 ${operation.records.length} 条记录`,
+					...sample,
+					...more
+				].join("\n");
+			}
+			case "update": {
+				const sample = operation.records.slice(0, CARD_PREVIEW_RECORDS).map((record) => `　${preview(record.record_id, 40)}：${json(record.fields)}`);
+				const more = operation.records.length > CARD_PREVIEW_RECORDS ? [`　…（共 ${operation.records.length} 条）`] : [];
+				return [
+					`${n} 修改 ${operation.records.length} 条记录`,
+					...sample,
+					...more
+				].join("\n");
+			}
+			case "delete": return `${n} ⚠️ 删除 ${operation.record_ids.length} 条记录：${preview(operation.record_ids.join("、"), 160)}`;
+		}
+	});
+	return [
+		`**数据表**：${preview(tableName, 60)}`,
+		`**将执行 ${operations.length} 个操作**`,
+		...lines
+	];
+}
+async function edit$1(kit, sessionId, rawArgs, signal) {
+	const args = parseArgs(WIKI_BASE_EDIT_TOOL_NAME, wikiBaseEditArgsSchema, rawArgs);
+	const gate = kit.gate(sessionId, WIKI_BASE_EDIT_TOOL_NAME);
+	if (!gate.ok) return gate;
+	return await guarded$1(kit, WIKI_BASE_EDIT_TOOL_NAME, async () => {
+		const target = await baseTarget(kit, gate.context, args.doc);
+		if ("ok" in target) return target;
+		const { node, bases } = target;
+		if (writableOf(kit, target) !== "all") {
+			const changing = args.operations.find((operation) => operation.command !== "create");
+			if (changing !== void 0) return failure("NOT_OWNED", `这个多维表格不是本应用创建的，只能新增记录，不能${changing.command === "update" ? "修改" : "删除"}已有记录（所有者：${node.owner ?? "未知"}）`);
+		}
+		const table = pickTable(await bases.listTables(node.objToken), args.table);
+		if (typeof table === "string") return failure("INVALID_OPERATION", table);
+		const denied = await kit.consent(sessionId, target.context, "edit", {
+			title: node.title,
+			url: target.url,
+			location: await kit.locationOf(target.context.api, node),
+			details: cardLines$1(args.operations, table.name)
+		}, signal);
+		if (denied !== void 0) return denied;
+		const created = [];
+		const ignored = [];
+		let updated = 0;
+		let deleted = 0;
+		for (const [index, operation] of args.operations.entries()) {
+			if (signal.aborted) return {
+				...failure("ABORTED", `已取消；前 ${index} 个操作已执行`),
+				applied: index
+			};
+			try {
+				switch (operation.command) {
+					case "create":
+						created.push(...await bases.createRecords(node.objToken, table.tableId, operation.records));
+						break;
+					case "update":
+						ignored.push(...await bases.updateRecords(node.objToken, table.tableId, Object.fromEntries(operation.records.map((record) => [record.record_id, record.fields]))));
+						updated += operation.records.length;
+						break;
+					case "delete":
+						await bases.deleteRecords(node.objToken, table.tableId, operation.record_ids);
+						deleted += operation.record_ids.length;
+						break;
+				}
+			} catch (error) {
+				const reason = failureOf(error).reason;
+				return {
+					...failure("EDIT_FAILED", `第 ${index + 1} 个操作失败：${reason}；前 ${index} 个操作已执行`),
+					applied: index
+				};
+			}
+		}
+		return {
+			ok: true,
+			title: node.title,
+			node_token: node.nodeToken,
+			url: target.url,
+			table_id: table.tableId,
+			applied: args.operations.length,
+			created_record_ids: created,
+			updated,
+			deleted,
+			ignored_fields: [...new Set(ignored)]
+		};
+	});
+}
+/** The Base tool family. */
+const BASE_TOOL_SPECS = [{
+	name: WIKI_BASE_READ_TOOL_NAME,
+	access: "read",
+	description: READ_DESCRIPTION$2,
+	parameters: READ_PARAMETERS$2,
+	execute: read$1,
+	presentCall: (args) => `读取知识库多维表格：${display(args.doc)}`
+}, {
+	name: WIKI_BASE_EDIT_TOOL_NAME,
+	access: "write",
+	description: EDIT_DESCRIPTION$2,
+	parameters: EDIT_PARAMETERS$2,
+	execute: edit$1,
+	presentCall: (args) => `修改知识库多维表格：${display(args.doc)}`
+}];
+//#endregion
+//#region src/feishu/wiki/a1.ts
+/**
+* A1 notation helpers for the wiki sheet tools: column letters, single cells,
+* and rectangle end rows. Ranges never carry a sheet prefix (`Sheet1!`); the
+* sub-sheet is selected separately.
+*
+* @module dsh-channels/feishu/wiki/a1
+*/
+/** Largest column the helpers accept (`ZZZ`). */
+const MAX_COLUMN = 18278;
+/** Largest row the helpers accept. */
+const MAX_ROW = 1e7;
+/**
+* Column letters to a 1-based index (`A` → 1, `AA` → 27).
+*
+* @param letters Column letters, any case.
+* @returns The index, or undefined when invalid or beyond `ZZZ`.
+*/
+function columnIndex(letters) {
+	if (!/^[A-Za-z]{1,3}$/u.test(letters)) return void 0;
+	let index = 0;
+	for (const char of letters.toUpperCase()) index = index * 26 + (char.charCodeAt(0) - 64);
+	return index <= MAX_COLUMN ? index : void 0;
+}
+/**
+* A 1-based column index to letters (1 → `A`, 27 → `AA`).
+*
+* @param index Column index, at least 1.
+* @returns The letters.
+*/
+function columnLetters(index) {
+	let letters = "";
+	let rest = index;
+	while (rest > 0) {
+		const digit = (rest - 1) % 26;
+		letters = String.fromCharCode(65 + digit) + letters;
+		rest = Math.floor((rest - 1) / 26);
+	}
+	return letters;
+}
+/**
+* Parse one cell (`B3`).
+*
+* @param value Cell reference.
+* @returns The position, or undefined when it is not a single valid cell.
+*/
+function parseCell(value) {
+	const match = /^([A-Za-z]{1,3})([1-9]\d{0,7})$/u.exec(value.trim());
+	if (match === null) return void 0;
+	const column = columnIndex(match[1] ?? "");
+	const row = Number(match[2]);
+	return column === void 0 || row > MAX_ROW ? void 0 : {
+		column,
+		row
+	};
+}
+/**
+* The rectangle that starts at `start` and spans `rows` × `columns` cells.
+*
+* @param start Top-left cell.
+* @param rows Row count, at least 1.
+* @param columns Column count, at least 1.
+* @returns The range (`B3:D10`).
+*/
+function rectangle(start, rows, columns) {
+	return `${columnLetters(start.column)}${start.row}:${columnLetters(start.column + columns - 1)}${start.row + rows - 1}`;
+}
+/**
+* Last row of a range (`A1:B5` → 5, `C7` → 7); undefined for whole-column ranges (`A:C`).
+*
+* @param range A1 range.
+* @returns The row, or undefined.
+*/
+function rangeEndRow(range) {
+	const end = range.split(":").at(-1) ?? "";
+	const match = /(\d+)$/u.exec(end.trim());
+	return match === null ? void 0 : Number(match[1]);
+}
+/**
+* Whether a range is plain A1 (`A1`, `A1:F30`, `A:C`, `3:5`) without a sheet prefix.
+*
+* @param range Candidate range.
+* @returns True when acceptable.
+*/
+function isA1Range(range) {
+	return /^(?:[A-Za-z]{1,3}\d{0,8}|\d{1,8})(?::(?:[A-Za-z]{1,3}\d{0,8}|\d{1,8}))?$/u.test(range);
+}
+//#endregion
+//#region src/feishu/wiki/sheet-tools.ts
+/**
+* Wiki spreadsheet (电子表格) tools: `feishu_wiki_sheet_read` (switch
+* `feishuTools.wikiRead`) and `feishu_wiki_sheet_edit` (switch
+* `feishuTools.wikiWrite`).
+*
+* Both run through the same gates as the docx tools (whitelist, `wikiRoots`
+* containment, consent cards). Reading shares the docx read grant per Session
+* and document. Editing writes cell values and formulas only (no styles,
+* charts, or row/column structure), only on spreadsheets the app owns, and
+* only when the workbook revision still equals the one the model read, checked
+* before and after the consent card; Feishu offers no revision precondition on
+* the write itself.
+*
+* @module dsh-channels/feishu/wiki/sheet-tools
+*/
+/** Model-facing tool names; stable across releases (session history references them). */
+const WIKI_SHEET_READ_TOOL_NAME = "feishu_wiki_sheet_read";
+const WIKI_SHEET_EDIT_TOOL_NAME = "feishu_wiki_sheet_edit";
+/** Most cells one `feishu_wiki_sheet_edit` call may write in total. */
+const WIKI_SHEET_EDIT_MAX_CELLS = 5e4;
+/** Read size bounds (characters of CSV returned to the model). */
+const READ_DEFAULT_CHARS = 2e4;
+const READ_MAX_CHARS = 1e5;
+/** CSV characters requested when only the data extent of a sheet is needed. */
+const EXTENT_PROBE_CHARS = 2e3;
+/** CSV characters per page while scanning below the first data region for later rows. */
+const EXTENT_SCAN_CHARS = 2e5;
+/** Pages the append row scan reads before giving up. */
+const EXTENT_SCAN_PAGES = 20;
+/** Scan bounds when the workbook does not report the grid size. */
+const MAX_SCAN_COLUMN = 18278;
+const MAX_SCAN_ROW = 1e7;
+/** Rows of each written block shown on a consent card. */
+const CARD_PREVIEW_ROWS = 3;
+const refSchema$1 = z.string().trim().min(1).max(2048);
+const sheetSchema = z.string().trim().min(1).max(200);
+const cellValueSchema = z.union([
+	z.string().max(5e4),
+	z.number().finite(),
+	z.boolean(),
+	z.null()
+]);
+const valuesSchema = z.array(z.array(cellValueSchema).min(1).max(1e3)).min(1).max(1e4);
+const wikiSheetReadArgsSchema = z.object({
+	doc: refSchema$1,
+	sheet: sheetSchema.optional(),
+	range: z.string().trim().min(1).max(40).refine(isA1Range, "需要不带子表前缀的 A1 范围，例如 A1:F30").optional(),
+	max_chars: z.number().int().min(1e3).max(READ_MAX_CHARS).optional()
+}).strict();
+const sheetOperationSchema = z.discriminatedUnion("command", [z.object({
+	command: z.literal("write"),
+	sheet: sheetSchema.optional(),
+	start_cell: z.string().trim().min(2).max(12),
+	values: valuesSchema
+}).strict(), z.object({
+	command: z.literal("append"),
+	sheet: sheetSchema.optional(),
+	start_column: z.string().trim().min(1).max(3).optional(),
+	values: valuesSchema
+}).strict()]);
+const wikiSheetEditArgsSchema = z.object({
+	doc: refSchema$1,
+	revision_id: z.number().int().min(0),
+	operations: z.array(sheetOperationSchema).min(1).max(20)
+}).strict();
+const READ_DESCRIPTION$1 = `读取知识库中的飞书电子表格（sheet）。doc 传知识库节点链接或 node_token。第一次读取某个表格会在话题里弹出授权卡，由话题发起人确认，确认后本话题内再次读取不再询问；等待期间不要重复调用。返回 sheets（子表列表）；sheet 传子表 sheet_id 或标题选择子表，只有一个可见子表时可省略，有多个而未指定时只返回子表列表。range 为不带子表前缀的 A1 范围（如 A1:F30、A:C），省略时读整张子表。内容为 CSV（显示值），每行前缀 [row=N] 是真实行号，引用行号时以它为准，不要自己数行。max_chars 默认 ${READ_DEFAULT_CHARS}；has_more 为 true 时表示被截断，从 actual_range 末行之后接着读。返回的 revision_id 用于 feishu_wiki_sheet_edit；editable 表示能否修改（只有本应用创建的表格可以修改）。`;
+const EDIT_DESCRIPTION$1 = `修改知识库中由本应用创建的飞书电子表格（sheet）的单元格值。先用 feishu_wiki_sheet_read 读取，把读到的 revision_id 原样传入；表格在此之后被改过会被拒绝，需要重新读取。operations 按顺序执行（最多 20 个，合计不超过 ${WIKI_SHEET_EDIT_MAX_CELLS} 个单元格）：write（从 start_cell 如 B3 开始写入二维数组 values）、append（在子表现有数据的最后一行之后追加 values，start_column 默认 A；目标单元格非空时失败，不会覆盖）。返回 formula_errors 时，这些公式没有编译成功、已按文本写入，需要修正后重写。values 每个元素是一行；单元格可以是字符串、数字、布尔或 null（null 表示保持原值不变）；以 = 开头的字符串作为公式写入。数字、金额、百分比（0.4 表示 40%）写成数字；编号、前导零、身份证号写成字符串。不会修改样式、图表、行列结构。sheet 传子表 sheet_id 或标题，只有一个可见子表时可省略。每次修改都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。`;
+const REF_DESCRIPTION$1 = "知识库节点链接 https://<租户>.feishu.cn/wiki/<node_token> 或 node_token";
+const SHEET_PROPERTY = {
+	type: "string",
+	description: "子表 sheet_id 或标题；只有一个可见子表时可省略"
+};
+const VALUES_PROPERTY = {
+	type: "array",
+	description: "二维数组，每个元素是一行；单元格为字符串、数字、布尔或 null（保持原值），以 = 开头的字符串是公式",
+	items: {
+		type: "array",
+		items: { type: [
+			"string",
+			"number",
+			"boolean",
+			"null"
+		] }
+	}
+};
+const READ_PARAMETERS$1 = {
+	type: "object",
+	properties: {
+		doc: {
+			type: "string",
+			description: REF_DESCRIPTION$1
+		},
+		sheet: SHEET_PROPERTY,
+		range: {
+			type: "string",
+			description: "不带子表前缀的 A1 范围，如 A1:F30；省略读整张子表"
+		},
+		max_chars: {
+			type: "integer",
+			minimum: 1e3,
+			maximum: READ_MAX_CHARS,
+			description: `返回 CSV 的字符上限，默认 ${READ_DEFAULT_CHARS}`
+		}
+	},
+	required: ["doc"],
+	additionalProperties: false
+};
+const EDIT_PARAMETERS$1 = {
+	type: "object",
+	properties: {
+		doc: {
+			type: "string",
+			description: REF_DESCRIPTION$1
+		},
+		revision_id: {
+			type: "integer",
+			description: "feishu_wiki_sheet_read 返回的 revision_id"
+		},
+		operations: {
+			type: "array",
+			minItems: 1,
+			maxItems: 20,
+			items: {
+				type: "object",
+				properties: {
+					command: {
+						type: "string",
+						enum: ["write", "append"]
+					},
+					sheet: SHEET_PROPERTY,
+					start_cell: {
+						type: "string",
+						description: "write 的起始单元格，如 B3"
+					},
+					start_column: {
+						type: "string",
+						description: "append 的起始列，默认 A"
+					},
+					values: VALUES_PROPERTY
+				},
+				required: ["command", "values"],
+				additionalProperties: false
+			}
+		}
+	},
+	required: [
+		"doc",
+		"revision_id",
+		"operations"
+	],
+	additionalProperties: false
+};
+async function sheetTarget(kit, context, doc) {
+	const sheets = context.sheets;
+	if (sheets === void 0) return failure("CHANNEL_UNAVAILABLE");
+	const ref = parseWikiRef(doc);
+	if (ref === void 0) return failure("INVALID_REFERENCE");
+	const node = await kit.containedNode(context, ref);
+	if ("ok" in node) return node;
+	if (node.objType !== "sheet") return failure("UNSUPPORTED_TYPE", `${failure("UNSUPPORTED_TYPE").reason}（该节点类型：${node.objType}）`);
+	return {
+		context,
+		sheets,
+		node,
+		url: nodeUrl(context.roots, node)
+	};
+}
+function sheetView(sheet) {
+	return {
+		sheet_id: sheet.sheetId,
+		title: sheet.title,
+		index: sheet.index,
+		resource_type: sheet.resourceType,
+		hidden: sheet.hidden,
+		...sheet.rowCount === void 0 ? {} : { row_count: sheet.rowCount },
+		...sheet.columnCount === void 0 ? {} : { column_count: sheet.columnCount }
 	};
 }
-/**
-* Parse every configured root. Callers validate the config first, so an
-* invalid entry here is a programming error.
-*
-* @param links Validated `wikiRoots` entries.
-* @returns The parsed roots, in configuration order.
-*/
-function parseWikiRoots(links) {
-	return links.map((link) => {
-		const parsed = parseWikiRootLink(link);
-		if (!parsed.ok) throw new Error(`dsh-channels: invalid wikiRoots entry ${link}: ${WIKI_ROOT_LINK_ERRORS[parsed.error]}`);
-		return parsed.root;
+/** The named grid sheet, the only visible grid sheet, or why neither applies. */
+function pickSheet(workbook, wanted) {
+	const grids = workbook.sheets.filter((sheet) => sheet.resourceType === "sheet");
+	if (wanted !== void 0) {
+		const match = workbook.sheets.find((sheet) => sheet.sheetId === wanted) ?? workbook.sheets.find((sheet) => sheet.title === wanted);
+		if (match === void 0) return `找不到子表「${wanted}」；可用子表：${sheetList(workbook)}`;
+		if (match.resourceType !== "sheet") return `子表「${match.title}」是 ${match.resourceType}，不是单元格表格，不能按单元格读写`;
+		return match;
+	}
+	const visible = grids.filter((sheet) => !sheet.hidden);
+	if (visible.length === 1 && visible[0] !== void 0) return visible[0];
+	return `表格有多个子表，请用 sheet 指定：${sheetList(workbook)}`;
+}
+function sheetList(workbook) {
+	return workbook.sheets.map((sheet) => `${sheet.title}（${sheet.sheetId}）`).join("、") || "无";
+}
+function wholeSheetRange(sheet) {
+	return sheet.rowCount !== void 0 && sheet.columnCount !== void 0 && sheet.rowCount > 0 && sheet.columnCount > 0 ? `A1:${columnLetters(sheet.columnCount)}${sheet.rowCount}` : "A:ZZZ";
+}
+async function read(kit, sessionId, rawArgs, signal) {
+	const args = parseArgs(WIKI_SHEET_READ_TOOL_NAME, wikiSheetReadArgsSchema, rawArgs);
+	const gate = kit.gate(sessionId, WIKI_SHEET_READ_TOOL_NAME);
+	if (!gate.ok) return gate;
+	return await guarded$1(kit, WIKI_SHEET_READ_TOOL_NAME, async () => {
+		const target = await sheetTarget(kit, gate.context, args.doc);
+		if ("ok" in target) return target;
+		const denied = await kit.readConsent(sessionId, target.context, target.node, signal);
+		if (denied !== void 0) return denied;
+		if (signal.aborted) return failure("ABORTED");
+		const workbook = await target.sheets.workbook(target.node.objToken);
+		const base = {
+			ok: true,
+			title: target.node.title,
+			node_token: target.node.nodeToken,
+			url: target.url,
+			...workbook.revision === void 0 ? {} : { revision_id: workbook.revision },
+			sheets: workbook.sheets.map(sheetView),
+			editable: kit.writeEnabled() && ownedByApp(target.node, target.context.botOpenId)
+		};
+		const sheet = pickSheet(workbook, args.sheet);
+		if (typeof sheet === "string") {
+			if (args.sheet !== void 0) return failure("INVALID_OPERATION", sheet);
+			return {
+				...base,
+				warning: sheet,
+				content: ""
+			};
+		}
+		const csv = await target.sheets.readCsv(target.node.objToken, {
+			sheetId: sheet.sheetId,
+			range: args.range ?? wholeSheetRange(sheet),
+			maxChars: args.max_chars ?? READ_DEFAULT_CHARS
+		});
+		return {
+			...base,
+			sheet_id: sheet.sheetId,
+			...csv.actualRange === void 0 ? {} : { actual_range: csv.actualRange },
+			...csv.currentRegion === void 0 ? {} : { current_region: csv.currentRegion },
+			has_more: csv.hasMore,
+			...csv.warning === void 0 ? {} : { warning: csv.warning },
+			content: csv.csv
+		};
 	});
 }
-/**
-* Parse a model-supplied reference: a wiki node link, a docx link, a space
-* link, or a bare node token.
-*
-* @param input Raw tool argument.
-* @returns The reference, or `undefined` when it names nothing recognizable.
-*/
-function parseWikiRef(input) {
-	const trimmed = input.trim();
-	if (TOKEN_PATTERN.test(trimmed)) return {
-		kind: "node",
-		token: trimmed
+/** Rows padded with `null` (unchanged) to one rectangle. */
+function rectangular(values) {
+	const columns = Math.max(...values.map((row) => row.length));
+	return {
+		rows: values.map((row) => [...row, ...Array(columns - row.length).fill(null)]),
+		columns
 	};
-	let url;
-	try {
-		url = new URL(trimmed);
-	} catch {
-		return;
+}
+function plan(workbook, operations) {
+	const planned = [];
+	let cells = 0;
+	for (const [index, operation] of operations.entries()) {
+		const where = `第 ${index + 1} 个操作（${operation.command}）`;
+		const sheet = pickSheet(workbook, operation.sheet);
+		if (typeof sheet === "string") return failure("INVALID_OPERATION", `${where}：${sheet}`);
+		let start;
+		if (operation.command === "write") {
+			start = parseCell(operation.start_cell);
+			if (start === void 0) return failure("INVALID_OPERATION", `${where}：start_cell 需要单个单元格，例如 B3`);
+		} else {
+			const column = parseCell(`${operation.start_column ?? "A"}1`);
+			if (column === void 0) return failure("INVALID_OPERATION", `${where}：start_column 需要列字母，例如 A`);
+			start = column;
+		}
+		const { rows, columns } = rectangular(operation.values);
+		cells += rows.length * columns;
+		if (cells > 5e4) return failure("INVALID_OPERATION", `一次最多写入 ${WIKI_SHEET_EDIT_MAX_CELLS} 个单元格，请拆成多次调用`);
+		planned.push({
+			operation,
+			sheet,
+			start,
+			rows,
+			columns
+		});
 	}
-	if (url.protocol !== "https:") return void 0;
-	const segments = url.pathname.split("/").filter((segment) => segment !== "");
-	if (segments[0] === "wiki" && segments.length === 3 && segments[1] === "space" && SPACE_ID_PATTERN.test(segments[2])) return {
-		kind: "space",
-		spaceId: segments[2]
-	};
-	if (segments.length === 2 && TOKEN_PATTERN.test(segments[1])) {
-		if (segments[0] === "wiki" && segments[1] !== "space") return {
-			kind: "node",
-			token: segments[1]
+	return planned;
+}
+function cardLines(planned) {
+	const lines = planned.map((write, index) => {
+		const size = `${write.rows.length} 行 × ${write.columns} 列`;
+		const where = write.operation.command === "write" ? `写入子表「${preview(write.sheet.title, 40)}」的 ${rectangle(write.start, write.rows.length, write.columns)}（${size}）` : `在子表「${preview(write.sheet.title, 40)}」末尾追加 ${size}（从 ${columnLetters(write.start.column)} 列开始）`;
+		const sample = write.rows.slice(0, CARD_PREVIEW_ROWS).map((row) => `　${preview(row.map((cell) => cell === null ? "" : String(cell)).join(" | "), 80)}`);
+		const more = write.rows.length > CARD_PREVIEW_ROWS ? [`　…（共 ${write.rows.length} 行）`] : [];
+		return [
+			`${index + 1}. ${where}`,
+			...sample,
+			...more
+		].join("\n");
+	});
+	return [`**将执行 ${planned.length} 个操作**`, ...lines];
+}
+/** First empty row after the sheet's data (1 for an empty sheet), or undefined when it cannot be determined. */
+async function appendRow(sheets, token, sheet) {
+	const probe = await sheets.readCsv(token, {
+		sheetId: sheet.sheetId,
+		range: wholeSheetRange(sheet),
+		maxChars: EXTENT_PROBE_CHARS
+	});
+	const region = probe.currentRegion ?? (probe.hasMore ? void 0 : probe.actualRange);
+	let last = region === void 0 ? probe.csv.trim() === "" && !probe.hasMore ? 0 : void 0 : rangeEndRow(region);
+	if (last === void 0) return void 0;
+	const lastColumn = columnLetters(sheet.columnCount !== void 0 && sheet.columnCount > 0 ? sheet.columnCount : MAX_SCAN_COLUMN);
+	const lastRow = sheet.rowCount !== void 0 && sheet.rowCount > 0 ? sheet.rowCount : MAX_SCAN_ROW;
+	let from = last + 1;
+	for (let page = 0; from <= lastRow; page++) {
+		if (page === EXTENT_SCAN_PAGES) return void 0;
+		const scan = await sheets.readCsv(token, {
+			sheetId: sheet.sheetId,
+			range: `A${from}:${lastColumn}${lastRow}`,
+			maxChars: EXTENT_SCAN_CHARS
+		});
+		last = Math.max(last, lastFilledRow(scan.csv));
+		if (!scan.hasMore) break;
+		const end = scan.actualRange === void 0 ? void 0 : rangeEndRow(scan.actualRange);
+		if (end === void 0 || end < from) return void 0;
+		from = end + 1;
+	}
+	return last + 1;
+}
+/** Largest `[row=N]` whose record has a non-empty cell, or 0. */
+function lastFilledRow(csv) {
+	let last = 0;
+	for (const match of csv.matchAll(/^\[row=(\d+)\] ?(.*)$/gmu)) if (/[^,\s"]/u.test(match[2] ?? "")) last = Math.max(last, Number(match[1]));
+	return last;
+}
+async function edit(kit, sessionId, rawArgs, signal) {
+	const args = parseArgs(WIKI_SHEET_EDIT_TOOL_NAME, wikiSheetEditArgsSchema, rawArgs);
+	const gate = kit.gate(sessionId, WIKI_SHEET_EDIT_TOOL_NAME);
+	if (!gate.ok) return gate;
+	return await guarded$1(kit, WIKI_SHEET_EDIT_TOOL_NAME, async () => {
+		const target = await sheetTarget(kit, gate.context, args.doc);
+		if ("ok" in target) return target;
+		const { node, sheets } = target;
+		if (!ownedByApp(node, target.context.botOpenId)) return failure("NOT_OWNED", `${failure("NOT_OWNED").reason}（该表格所有者：${node.owner ?? "未知"}）`);
+		const workbook = await sheets.workbook(node.objToken);
+		if (workbook.revision !== void 0 && workbook.revision !== args.revision_id) return {
+			...failure("REVISION_CONFLICT", `${failure("REVISION_CONFLICT").reason}（读取时 ${args.revision_id}，当前 ${workbook.revision}）`),
+			revision_id: workbook.revision
 		};
-		if (segments[0] === "docx") return {
-			kind: "docx",
-			token: segments[1]
+		const planned = plan(workbook, args.operations);
+		if (!Array.isArray(planned)) return planned;
+		const denied = await kit.consent(sessionId, target.context, "edit", {
+			title: node.title,
+			url: target.url,
+			location: await kit.locationOf(target.context.api, node),
+			details: cardLines(planned)
+		}, signal);
+		if (denied !== void 0) return denied;
+		const after = await sheets.workbook(node.objToken);
+		if (after.revision !== void 0 && after.revision !== args.revision_id) return {
+			...failure("REVISION_CONFLICT", `${failure("REVISION_CONFLICT").reason}（等待授权期间表格被修改）`),
+			revision_id: after.revision
 		};
-	}
-}
-//#endregion
-//#region src/feishu/wiki/scope.ts
-/**
-* Longest parent chain walked for a node root. Feishu limits wiki depth well
-* below this; a longer chain is treated as outside.
-*/
-const MAX_PARENT_DEPTH = 64;
-/**
-* Find the configured root containing `node`.
-*
-* @param api Wiki endpoints (for parent lookups).
-* @param roots Configured roots.
-* @param node The node to check.
-* @returns The containing root, or `undefined` when none contains it.
-*/
-async function containingRoot(api, roots, node) {
-	for (const root of roots) if (root.kind === "space" && root.spaceId === node.spaceId) return { root };
-	const nodeRoots = roots.filter((root) => root.kind === "node");
-	if (nodeRoots.length === 0) return void 0;
-	const byToken = new Map(nodeRoots.map((root) => [root.nodeToken, root]));
-	let current = node;
-	for (let depth = 0; depth <= MAX_PARENT_DEPTH; depth += 1) {
-		const match = byToken.get(current.nodeToken);
-		if (match !== void 0) return { root: match };
-		if (current.parentNodeToken === void 0) return void 0;
-		current = await api.getNode(current.parentNodeToken, "wiki");
-	}
-}
-/**
-* Whether a whole space (its top level) is inside the roots: only a space
-* root covers a space's top level.
-*
-* @param roots Configured roots.
-* @param spaceId The space.
-* @returns True when a space root names it.
-*/
-function spaceIsRoot(roots, spaceId) {
-	return roots.some((root) => root.kind === "space" && root.spaceId === spaceId);
+		const written = [];
+		const formulaErrors = [];
+		for (const [index, write] of planned.entries()) {
+			if (signal.aborted) return {
+				...failure("ABORTED", `已取消；前 ${index} 个操作已执行`),
+				applied: index
+			};
+			try {
+				let start = write.start;
+				if (write.operation.command === "append") {
+					const row = await appendRow(sheets, node.objToken, write.sheet);
+					if (row === void 0) return {
+						...failure("EDIT_FAILED", `第 ${index + 1} 个操作失败：无法确定子表「${write.sheet.title}」的数据末行，请改用 write 指定 start_cell；前 ${index} 个操作已执行`),
+						applied: index
+					};
+					start = {
+						column: write.start.column,
+						row
+					};
+				}
+				const range = rectangle(start, write.rows.length, write.columns);
+				const result = await sheets.writeCells(node.objToken, {
+					sheetId: write.sheet.sheetId,
+					range,
+					rows: write.rows,
+					...write.operation.command === "append" ? { allowOverwrite: false } : {}
+				});
+				written.push({
+					sheet_id: write.sheet.sheetId,
+					range
+				});
+				for (const error of result.formulaErrors) formulaErrors.push({
+					sheet_id: write.sheet.sheetId,
+					cell: error.cell,
+					...error.formula === void 0 ? {} : { formula: error.formula },
+					...error.errorType === void 0 ? {} : { error_type: error.errorType },
+					...error.detail === void 0 ? {} : { detail: error.detail }
+				});
+			} catch (error) {
+				const reason = failureOf(error).reason;
+				return {
+					...failure("EDIT_FAILED", `第 ${index + 1} 个操作失败：${reason}；前 ${index} 个操作已执行`),
+					applied: index
+				};
+			}
+		}
+		const revision = await sheets.workbook(node.objToken).then((final) => final.revision, (error) => {
+			kit.warn("dsh-channels: reading the revision after %s failed: %s", WIKI_SHEET_EDIT_TOOL_NAME, describeError(error));
+		});
+		return {
+			ok: true,
+			title: node.title,
+			node_token: node.nodeToken,
+			url: target.url,
+			applied: planned.length,
+			written,
+			...revision === void 0 ? {} : { revision_id: revision },
+			...formulaErrors.length === 0 ? {} : { formula_errors: formulaErrors }
+		};
+	});
 }
+/** The spreadsheet tool family. */
+const SHEET_TOOL_SPECS = [{
+	name: WIKI_SHEET_READ_TOOL_NAME,
+	access: "read",
+	description: READ_DESCRIPTION$1,
+	parameters: READ_PARAMETERS$1,
+	execute: read,
+	presentCall: (args) => `读取知识库表格：${display(args.doc)}`
+}, {
+	name: WIKI_SHEET_EDIT_TOOL_NAME,
+	access: "write",
+	description: EDIT_DESCRIPTION$1,
+	parameters: EDIT_PARAMETERS$1,
+	execute: edit,
+	presentCall: (args) => `修改知识库表格：${display(args.doc)}`
+}];
 //#endregion
 //#region src/feishu/wiki/tools.ts
 /**
@@ -10110,8 +11508,6 @@ const WIKI_EDIT_TOOL_NAME = "feishu_wiki_edit";
 const MAX_TITLE_CHARS = 200;
 /** Longest content one create/edit operation may carry (characters). */
 const MAX_CONTENT_CHARS = 2e5;
-/** Characters of each content shown on a consent card. */
-const PREVIEW_CHARS = 300;
 const refSchema = z.string().trim().min(1).max(2048);
 const blockIdSchema = z.string().trim().min(1).max(128);
 const contentSchema = z.string().max(MAX_CONTENT_CHARS);
@@ -10138,6 +11534,11 @@ const wikiReadArgsSchema = z.object({
 const wikiCreateArgsSchema = z.object({
 	parent: refSchema,
 	title: z.string().trim().min(1).max(MAX_TITLE_CHARS),
+	type: z.enum([
+		"docx",
+		"sheet",
+		"bitable"
+	]).optional(),
 	content: contentSchema.optional(),
 	format: formatSchema.optional()
 }).strict();
@@ -10181,29 +11582,6 @@ const wikiEditArgsSchema = z.object({
 	format: formatSchema.optional(),
 	operations: z.array(wikiEditOperationSchema).min(1).max(20)
 }).strict();
-const FAILURE_REASONS = {
-	TOOL_DISABLED: "知识库工具已在插件配置中关闭",
-	ROUTE_NOT_FOUND: "当前会话没有绑定飞书话题，无法确定授权人",
-	NOT_AUTHORIZED: "当前话题的发起人不在知识库白名单中；请管理员发送 /auth wiki add @该用户 后重试",
-	CHANNEL_UNAVAILABLE: "飞书连接当前不可用，请稍后重试",
-	INVALID_REFERENCE: "无法识别的知识库引用：请传知识库节点链接 https://<租户>.feishu.cn/wiki/<node_token>、node_token，或知识空间链接 https://<租户>.feishu.cn/wiki/space/<space_id>",
-	INVALID_OPERATION: "编辑操作参数不完整",
-	OUTSIDE_ROOTS: "该位置不在插件配置的知识库范围（wikiRoots）内，不能访问",
-	NOT_FOUND: "知识库节点不存在或已被删除",
-	NO_ACCESS: "机器人对该知识库节点没有访问权限；请知识库管理员把应用（或包含机器人的群）加为该空间成员",
-	UNSUPPORTED_TYPE: "目前只支持读取和修改飞书文档（docx）；表格、多维表格等类型暂不支持",
-	NOT_OWNED: "只能修改由本应用创建（所有者是本应用）的文档",
-	REVISION_CONFLICT: "文档在你读取之后被修改过；请重新用 feishu_wiki_read 读取最新内容，基于新的 revision_id 再修改",
-	CONSENT_DENIED: "话题发起人拒绝了这次知识库操作",
-	CONSENT_EXPIRED: "话题发起人没有在授权卡有效期内确认，已自动拒绝",
-	CONSENT_UNAVAILABLE: "授权卡发送失败，无法征得话题发起人同意，已取消操作",
-	PERMISSION_DENIED: "飞书拒绝调用：应用缺少知识库或文档权限（wiki:wiki、docx:document），请管理员在开发者后台开通并发布版本",
-	CONTENT_FAILED: "文档已创建，但写入内容失败",
-	EDIT_FAILED: "修改失败",
-	EDIT_PARTIAL: "飞书报告操作只部分生效；已停止后续操作，请用 feishu_wiki_read 读取最新内容核验后再继续",
-	API_FAILED: "飞书接口调用失败",
-	ABORTED: "已取消"
-};
 const OUTPUT_SCHEMA = {
 	type: "object",
 	properties: {
@@ -10214,9 +11592,16 @@ const OUTPUT_SCHEMA = {
 	required: ["ok"]
 };
 const LIST_DESCRIPTION = "浏览飞书知识库（只能访问插件配置的知识库范围 wikiRoots）。不传 parent 时列出可访问的根（知识空间或节点）；传 parent（知识库节点链接、node_token，或知识空间链接）时列出它的直接子节点，has_child 为 true 的节点可以继续往下浏览。结果分页，带 page_token 时用它取下一页。返回的 node_token 可直接传给其他知识库工具。";
-const READ_DESCRIPTION = "读取知识库中的一篇飞书文档（docx）。doc 传知识库节点链接或 node_token。第一次读取某篇文档会在话题里弹出授权卡，由话题发起人确认，确认后本话题内再次读取同一篇不再询问；等待期间不要重复调用。scope 默认 full（整篇）；大文档先用 outline 看目录，再用 section（start_block_id 为标题块 id）、range（start/end_block_id）或 keyword（关键词，支持 a|b）读取局部；max_depth 在 outline 中表示标题层级上限。format 默认 markdown；xml 为飞书文档 XML（类 HTML 标签：<p> <h1>-<h6> <ul>/<ol><li> <pre><code> <table> <callout> 等），只有 xml 读取会给每个块带上 id 属性（block id），需要按块修改时用 xml 读取。返回的 revision_id 用于 feishu_wiki_edit；editable 表示这篇文档能否被修改（只有本应用创建的文档可以修改）。";
-const CREATE_DESCRIPTION = "在知识库中新建一篇飞书文档（docx）。parent 传父节点（知识库节点链接或 node_token）或知识空间链接（建在空间顶层），必须位于插件配置的知识库范围内；新文档本身也可以作为目录，之后把它的 node_token 作为 parent 在下面继续新建子文档。title 为标题；content 为正文（可选，不要在正文里重复标题）。format 默认 markdown；xml 为飞书文档 XML（类 HTML 标签：<p> <h1>-<h6> <ul>/<ol><li> <pre><code> <table> <callout> 等），只有 xml 读取会给每个块带上 id 属性（block id），需要按块修改时用 xml 读取。每次新建都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。";
+const READ_DESCRIPTION = "读取知识库中的一篇飞书文档（docx；电子表格用 feishu_wiki_sheet_read，多维表格用 feishu_wiki_base_read）。doc 传知识库节点链接或 node_token。第一次读取某篇文档会在话题里弹出授权卡，由话题发起人确认，确认后本话题内再次读取同一篇不再询问；等待期间不要重复调用。scope 默认 full（整篇）；大文档先用 outline 看目录，再用 section（start_block_id 为标题块 id）、range（start/end_block_id）或 keyword（关键词，支持 a|b）读取局部；max_depth 在 outline 中表示标题层级上限。format 默认 markdown；xml 为飞书文档 XML（类 HTML 标签：<p> <h1>-<h6> <ul>/<ol><li> <pre><code> <table> <callout> 等），只有 xml 读取会给每个块带上 id 属性（block id），需要按块修改时用 xml 读取。返回的 revision_id 用于 feishu_wiki_edit；editable 表示这篇文档能否被修改（只有本应用创建的文档可以修改）。";
+const CREATE_DESCRIPTION = "在知识库中新建一篇飞书文档（docx，默认）、电子表格（type=sheet）或多维表格（type=bitable）。parent 传父节点（知识库节点链接或 node_token）或知识空间链接（建在空间顶层），必须位于插件配置的知识库范围内；新节点本身也可以作为目录，之后把它的 node_token 作为 parent 在下面继续新建子节点。title 为标题；content 为文档正文（仅 docx，可选，不要在正文里重复标题），电子表格和多维表格建好后是空白的，再用 feishu_wiki_sheet_edit / feishu_wiki_base_edit 写入。format 默认 markdown；xml 为飞书文档 XML（类 HTML 标签：<p> <h1>-<h6> <ul>/<ol><li> <pre><code> <table> <callout> 等），只有 xml 读取会给每个块带上 id 属性（block id），需要按块修改时用 xml 读取。每次新建都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。";
 const EDIT_DESCRIPTION = `修改知识库中由本应用创建的飞书文档（docx）。先用 feishu_wiki_read 读取（按块修改时用 format=xml 拿到 block id），把读到的 revision_id 原样传入；文档在此之后被他人改过会被拒绝，需要重新读取。operations 按顺序执行（最多 20 个）：append（文末追加 content）、insert_after（在 block_id 之后插入 content）、replace（用 content 替换 block_id，或同一父块下 start_block_id 到 end_block_id 的连续块）、delete（删除 block_id，或 start_block_id 到 end_block_id）、str_replace（把文本 pattern 替换为 content，content 为空表示删除）、overwrite（清空后用 content 重写整篇，会丢失评论与不支持的内容，尽量少用）。替换和删除会使涉及的旧 block id 失效，同一个块的多处修改请合并成一次 replace。format 默认 markdown；xml 为飞书文档 XML（类 HTML 标签：<p> <h1>-<h6> <ul>/<ol><li> <pre><code> <table> <callout> 等），只有 xml 读取会给每个块带上 id 属性（block id），需要按块修改时用 xml 读取。每次修改都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。`;
+const CREATE_TYPE_LABELS = {
+	docx: "飞书文档",
+	sheet: "电子表格",
+	bitable: "多维表格"
+};
+/** The spreadsheet and Base tool families, mounted with the docx tools under the same switches. */
+const FAMILY_SPECS = [...SHEET_TOOL_SPECS, ...BASE_TOOL_SPECS];
 /**
 * The wiki tool runtime: mounts the enabled tools into Agent scopes and runs
 * each call through the gates in the module contract.
@@ -10234,7 +11619,16 @@ var WikiToolRuntime = class {
 	enabledTools() {
 		const config = this.deps.config();
 		if (config.wikiRoots.length === 0) return [];
-		return [...config.feishuTools.wikiRead ? [WIKI_LIST_TOOL_NAME, WIKI_READ_TOOL_NAME] : [], ...config.feishuTools.wikiWrite ? [WIKI_CREATE_TOOL_NAME, WIKI_EDIT_TOOL_NAME] : []];
+		const family = (access) => FAMILY_SPECS.filter((spec) => spec.access === access).map((spec) => spec.name);
+		return [...config.feishuTools.wikiRead ? [
+			WIKI_LIST_TOOL_NAME,
+			WIKI_READ_TOOL_NAME,
+			...family("read")
+		] : [], ...config.feishuTools.wikiWrite ? [
+			WIKI_CREATE_TOOL_NAME,
+			WIKI_EDIT_TOOL_NAME,
+			...family("write")
+		] : []];
 	}
 	/**
 	* Register the enabled tools inside one Agent scope; same mount policy as
@@ -10291,6 +11685,16 @@ var WikiToolRuntime = class {
 			},
 			presentResult: (_args, value) => presentWikiResult(value)
 		};
+		const spec = FAMILY_SPECS.find((candidate) => candidate.name === name);
+		if (spec !== void 0) return {
+			...base,
+			name,
+			description: spec.description,
+			parameters: spec.parameters,
+			execute: async (rawArgs, exec) => await spec.execute(this, sessionId, rawArgs, exec.signal),
+			presentCall: (args) => spec.presentCall(args),
+			isConcurrencySafe: () => false
+		};
 		switch (name) {
 			case WIKI_LIST_TOOL_NAME: return {
 				...base,
@@ -10343,6 +11747,8 @@ var WikiToolRuntime = class {
 			context: {
 				route,
 				api,
+				...channel.sheets === void 0 ? {} : { sheets: channel.sheets },
+				...channel.bases === void 0 ? {} : { bases: channel.bases },
 				roots: parseWikiRoots(this.deps.config().wikiRoots),
 				botOpenId: channel.botOpenId()
 			}
@@ -10372,6 +11778,26 @@ var WikiToolRuntime = class {
 		return label;
 	}
 	/** `空间 / 父节点` for a node (one parent lookup). */
+	async readConsent(sessionId, context, node, signal) {
+		if (this.deps.consent.hasReadGrant(sessionId, node.objToken)) return void 0;
+		const denied = await this.consent(sessionId, context, "read", {
+			title: node.title,
+			url: nodeUrl(context.roots, node),
+			location: await this.locationOf(context.api, node),
+			details: []
+		}, signal);
+		if (denied === void 0) this.deps.consent.grantRead(sessionId, node.objToken);
+		return denied;
+	}
+	grantRead(sessionId, documentId) {
+		this.deps.consent.grantRead(sessionId, documentId);
+	}
+	writeEnabled() {
+		return this.deps.config().feishuTools.wikiWrite;
+	}
+	warn(message, ...args) {
+		this.deps.warn(message, ...args);
+	}
 	async locationOf(api, node) {
 		const space = await this.spaceName(api, node.spaceId);
 		if (node.parentNodeToken === void 0) return space;
@@ -10466,16 +11892,8 @@ var WikiToolRuntime = class {
 			if ("ok" in node) return node;
 			if (node.objType !== "docx") return failure("UNSUPPORTED_TYPE", `${FAILURE_REASONS.UNSUPPORTED_TYPE}（该节点类型：${node.objType}）`);
 			const url = nodeUrl(context.roots, node);
-			if (!this.deps.consent.hasReadGrant(sessionId, node.objToken)) {
-				const denied = await this.consent(sessionId, context, "read", {
-					title: node.title,
-					url,
-					location: await this.locationOf(context.api, node),
-					details: []
-				}, exec.signal);
-				if (denied !== void 0) return denied;
-				this.deps.consent.grantRead(sessionId, node.objToken);
-			}
+			const denied = await this.readConsent(sessionId, context, node, exec.signal);
+			if (denied !== void 0) return denied;
 			if (exec.signal.aborted) return failure("ABORTED");
 			const format = args.format ?? "markdown";
 			const document = await context.api.fetchDocument(node.objToken, {
@@ -10523,9 +11941,11 @@ var WikiToolRuntime = class {
 				parentUrl = nodeUrl(context.roots, parent);
 				location = `${await this.spaceName(context.api, spaceId)} / ${parent.title === "" ? parent.nodeToken : parent.title}`;
 			}
+			const type = args.type ?? "docx";
 			const format = args.format ?? "markdown";
 			const content = args.content === void 0 || args.content.trim() === "" ? void 0 : args.content;
-			const details = content === void 0 ? ["**内容**：空文档"] : [`**内容预览**（${format === "xml" ? "XML" : "Markdown"}，共 ${content.length} 字）\n${previewBlock(content)}`];
+			if (type !== "docx" && content !== void 0) return failure("INVALID_OPERATION", "content 只用于飞书文档；新建电子表格或多维表格后，用 feishu_wiki_sheet_edit / feishu_wiki_base_edit 写入数据");
+			const details = type !== "docx" ? [`**类型**：${CREATE_TYPE_LABELS[type]}（空白）`] : content === void 0 ? ["**内容**：空文档"] : [`**内容预览**（${format === "xml" ? "XML" : "Markdown"}，共 ${content.length} 字）\n${previewBlock(content)}`];
 			const denied = await this.consent(sessionId, context, "create", {
 				title: args.title,
 				...parentUrl === void 0 ? {} : { url: parentUrl },
@@ -10534,9 +11954,9 @@ var WikiToolRuntime = class {
 			}, exec.signal);
 			if (denied !== void 0) return denied;
 			if (exec.signal.aborted) return failure("ABORTED");
-			const node = await context.api.createDocxNode(spaceId, parentToken, args.title);
+			const node = await context.api.createNode(spaceId, parentToken, args.title, type);
 			const url = nodeUrl(context.roots, node);
-			this.deps.consent.grantRead(sessionId, node.objToken);
+			this.grantRead(sessionId, node.objToken);
 			if (content === void 0) return {
 				ok: true,
 				title: node.title || args.title,
@@ -10656,72 +12076,6 @@ var WikiToolRuntime = class {
 		});
 	}
 };
-function failure(code, reason) {
-	return {
-		ok: false,
-		code,
-		reason: reason ?? FAILURE_REASONS[code]
-	};
-}
-function parseArgs(tool, schema, rawArgs) {
-	const parsed = schema.safeParse(rawArgs);
-	if (parsed.success) return parsed.data;
-	const issue = parsed.error.issues[0];
-	const where = issue === void 0 || issue.path.length === 0 ? "arguments" : issue.path.join(".");
-	throw new Error(`${tool}: invalid ${where}: ${issue?.message ?? "invalid arguments"}`);
-}
-/** Run one gated call body, mapping thrown Feishu errors to failures. */
-async function guarded$1(deps, tool, body) {
-	try {
-		return await body();
-	} catch (error) {
-		const mapped = failureOf(error);
-		if (mapped.code === "API_FAILED") deps.warn("dsh-channels: %s failed: %s", tool, mapped.reason);
-		return mapped;
-	}
-}
-/** Feishu codes: node missing/deleted, no resource access, missing app scope. */
-const NOT_FOUND_CODES = /* @__PURE__ */ new Set([
-	131005,
-	131012,
-	131013,
-	131014,
-	131016
-]);
-const NO_ACCESS_CODES = /* @__PURE__ */ new Set([
-	131006,
-	1770032,
-	1770002
-]);
-const PERMISSION_CODES = /* @__PURE__ */ new Set([99991672, 99991679]);
-function failureOf(error) {
-	const detail = describeError(error);
-	if (error instanceof FeishuApiError && error.code !== void 0) {
-		if (NOT_FOUND_CODES.has(error.code)) return failure("NOT_FOUND", `${FAILURE_REASONS.NOT_FOUND}（${detail}）`);
-		if (NO_ACCESS_CODES.has(error.code)) return failure("NO_ACCESS", `${FAILURE_REASONS.NO_ACCESS}（${detail}）`);
-		if (PERMISSION_CODES.has(error.code)) return failure("PERMISSION_DENIED", `${FAILURE_REASONS.PERMISSION_DENIED}（${detail}）`);
-	}
-	return failure("API_FAILED", `${FAILURE_REASONS.API_FAILED}：${detail}`);
-}
-function consentFailure(outcome) {
-	switch (outcome) {
-		case "allowed": return;
-		case "denied": return failure("CONSENT_DENIED");
-		case "expired": return failure("CONSENT_EXPIRED");
-		case "cancelled": return failure("ABORTED");
-		case "unavailable": return failure("CONSENT_UNAVAILABLE");
-	}
-}
-/** Whether the app owns a node: Feishu reports the bot open_id as the owner. */
-function ownedByApp(node, botOpenId) {
-	return botOpenId !== void 0 && botOpenId !== "" && node.owner === botOpenId;
-}
-/** A node's web link; falls back to the first root's origin. */
-function nodeUrl(roots, node) {
-	if (node.url !== void 0) return node.url;
-	const first = roots[0];
-	return `${first === void 0 ? "https://feishu.cn" : new URL(first.link).origin}/wiki/${node.nodeToken}`;
-}
 /** Map one validated operation to a `docs_ai` update, or the reason it is incomplete. */
 function updateRequestOf(operation, format) {
 	switch (operation.command) {
@@ -10796,23 +12150,6 @@ function operationLines(operations) {
 function blockRangeLabel(operation) {
 	return operation.block_id !== void 0 ? `块 \`${operation.block_id}\`` : `块 \`${operation.start_block_id ?? "?"}\` 到 \`${operation.end_block_id ?? "?"}\``;
 }
-/** One-line clipped preview with Markdown control characters neutralized. */
-function preview(value, max = 80) {
-	const flat = value.replace(/\s+/gu, " ").trim().replace(/([[\]()*_`~<>])/gu, "\\$1");
-	return flat.length <= max ? flat : `${flat.slice(0, max)}…`;
-}
-/** A fenced preview of the first characters of a content. */
-function previewBlock(content) {
-	return `\`\`\`\n${(content.length <= PREVIEW_CHARS ? content : `${content.slice(0, PREVIEW_CHARS)}\n…`).replace(/```/gu, "`​``")}\n\`\`\``;
-}
-function display(value) {
-	return typeof value === "string" ? preview(value, 120) : "?";
-}
-/** Readable, bounded text for a thrown value. */
-function describeError(error) {
-	const cleaned = (error instanceof FeishuApiError ? error.detail : error instanceof Error ? error.message : String(error)).replace(/[\u0000-\u001f\u007f]+/gu, " ").trim();
-	return cleaned.length <= 300 ? cleaned : `${cleaned.slice(0, 300)}…`;
-}
 function isValue(value) {
 	return typeof value === "object" && value !== null && typeof value.ok === "boolean";
 }
@@ -10850,6 +12187,8 @@ function presentWikiResult(value) {
 	if (!isValue(value)) return "知识库工具结果不可用";
 	if (!value.ok) return `失败（${value.code}）：${value.reason}`;
 	if ("items" in value) return `列出 ${value.items.length} 项`;
+	if ("records" in value && value.records !== void 0) return `已读取《${value.title}》（${value.records.length} 条记录）`;
+	if ("tables" in value) return `已读取《${value.title}》（${value.tables.length} 个数据表）`;
 	if ("content" in value) return `已读取《${value.title}》（${value.content.length} 字）`;
 	if ("applied" in value) return `已修改《${value.title}》（${value.applied} 个操作）`;
 	return `已新建《${value.title}》`;
@@ -10926,11 +12265,20 @@ const CREATE_PARAMETERS = {
 		},
 		title: {
 			type: "string",
-			description: "文档标题"
+			description: "标题"
+		},
+		type: {
+			type: "string",
+			enum: [
+				"docx",
+				"sheet",
+				"bitable"
+			],
+			description: "节点类型：docx 飞书文档（默认）、sheet 电子表格、bitable 多维表格"
 		},
 		content: {
 			type: "string",
-			description: "正文（可选）"
+			description: "文档正文（仅 docx，可选）"
 		},
 		format: FORMAT_PROPERTY
 	},
@@ -13514,6 +14862,8 @@ const ATTACHMENT_STORE_MODES = ["native", "archive"];
 const DEFAULT_ATTACHMENT_FETCH_MAX_BYTES = 100 * 1024 * 1024;
 /** Default whole-call timeout of `feishu_attachment_fetch` (120 s). */
 const DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS = 12e4;
+/** Largest delay Node's `setTimeout` honors (2^31 − 1 ms, about 24.8 days); longer delays fire at once. */
+const MAX_TIMER_DELAY_MS = 2147483647;
 /** Default per-image byte cap for trigger-message prefetch (20 MiB). */
 const DEFAULT_PREFETCH_IMAGE_MAX_BYTES = 20 * 1024 * 1024;
 /** Default total byte budget for one trigger-message image prefetch (50 MiB). */
@@ -13712,10 +15062,12 @@ const configSchema = z.object({
 	*   fetch (1–50). A message with more attachments is refused with a readable
 	*   reason so the model can retry per `file_key`.
 	* - `attachmentFetchMaxBytes`: total download budget of one tool call
-	*   (default 100 MiB). Files stream to the native attachment library, so the
-	*   limit is enforced while streaming rather than buffered first.
-	* - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s). On expiry
-	*   the in-flight download is cancelled and reported per attachment.
+	*   (default 100 MiB, no upper bound). Files stream to the native attachment
+	*   library, so the limit is enforced while streaming rather than buffered
+	*   first, and multi-GiB files need only disk space.
+	* - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s, at most
+	*   {@link MAX_TIMER_DELAY_MS}). On expiry the in-flight download is
+	*   cancelled and reported per attachment.
 	* - `topicMessages` (default on): register `feishu_topic_messages` in
 	*   channel sessions so the model can read the quoted message / earlier
 	*   topic messages on demand and authorize their attachments for fetch.
@@ -13735,14 +15087,21 @@ const configSchema = z.object({
 	*   `im:resource` (or `im:resource:upload`) scope; without it a call returns
 	*   a readable failure and the turn continues.
 	*
-	* - `wikiRead` (default off): register `feishu_wiki_list` and
-	*   `feishu_wiki_read` so the model can browse the wiki nodes under
-	*   `wikiRoots` and read docx documents there. Needs `wiki:wiki` (or
-	*   `wiki:wiki:readonly`) and `docx:document` (or `docx:document:readonly`).
-	* - `wikiWrite` (default off): register `feishu_wiki_create` and
-	*   `feishu_wiki_edit` so the model can create docx documents under
-	*   `wikiRoots` and edit documents this app owns. Needs `wiki:wiki` and
-	*   `docx:document`.
+	* - `wikiRead` (default off): register `feishu_wiki_list`,
+	*   `feishu_wiki_read`, `feishu_wiki_sheet_read`, and
+	*   `feishu_wiki_base_read` so the model can browse the wiki nodes under
+	*   `wikiRoots` and read docx documents, spreadsheets, and Bases there.
+	*   Needs `wiki:wiki` (or `wiki:wiki:readonly`), `docx:document` (or
+	*   `docx:document:readonly`), `sheets:spreadsheet` (or a read-only
+	*   spreadsheet scope), and `bitable:app` (or a read-only Base scope).
+	* - `wikiWrite` (default off): register `feishu_wiki_create`,
+	*   `feishu_wiki_edit`, `feishu_wiki_sheet_edit`, and
+	*   `feishu_wiki_base_edit` so the model can create docx documents,
+	*   spreadsheets, and Bases under `wikiRoots`, edit documents and
+	*   spreadsheets this app owns, and change records of Bases this app owns
+	*   (other Bases accept new records only). Needs `wiki:wiki`,
+	*   `docx:document`, `sheets:spreadsheet`, and `bitable:app` (or the
+	*   matching write-only scopes).
 	*
 	* The wiki tools act with the app identity and are mounted only while
 	* `wikiRoots` is non-empty. Each call is limited to topics whose owner is
@@ -13755,8 +15114,8 @@ const configSchema = z.object({
 	feishuTools: z.object({
 		attachmentFetch: z.boolean().default(true),
 		attachmentFetchMaxResources: z.number().int().min(1).max(50).default(10),
-		attachmentFetchMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024).default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
-		attachmentFetchTimeoutMs: z.number().int().min(1e3).max(6e5).default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
+		attachmentFetchMaxBytes: z.number().int().min(1).default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
+		attachmentFetchTimeoutMs: z.number().int().min(1e3).max(MAX_TIMER_DELAY_MS).default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
 		topicMessages: z.boolean().default(true),
 		topicMessagesTimeoutMs: z.number().int().min(1e3).max(12e4).default(DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS),
 		sendFile: z.boolean().default(true),
@@ -17467,16 +18826,15 @@ const FIELD_META = {
 	},
 	"feishuTools.attachmentFetchMaxBytes": {
 		label: "单次取回字节预算（字节）",
-		help: "一次工具调用的总下载字节预算（默认 104857600 = 100 MiB）；文件流式写入原生库，不整文件缓冲。",
+		help: "一次工具调用的总下载字节预算（默认 104857600 = 100 MiB，不设上限）；文件流式写入原生库，不整文件缓冲，几 GiB 的文件只占磁盘。",
 		min: 1,
-		max: 1024 * 1024 * 1024,
 		step: 1
 	},
 	"feishuTools.attachmentFetchTimeoutMs": {
 		label: "单次取回超时（ms）",
-		help: "一次 feishu_attachment_fetch 的整段超时（默认 120000 ms，1000–600000）；到期取消下载并逐项报告可读原因。",
+		help: "一次 feishu_attachment_fetch 的整段超时（默认 120000 ms，最小 1000，最大 2147483647 ≈ 24.8 天）；到期取消下载并逐项报告可读原因。大文件请按带宽同步调大。",
 		min: 1e3,
-		max: 6e5,
+		max: MAX_TIMER_DELAY_MS,
 		step: 1e3
 	},
 	"feishuTools.topicMessages": {
@@ -17496,11 +18854,11 @@ const FIELD_META = {
 	},
 	"feishuTools.wikiRead": {
 		label: "启用知识库读取工具",
-		help: "让模型浏览「知识库范围」内的知识库节点并读取 docx 文档（feishu_wiki_list / feishu_wiki_read），以应用身份访问。需开通 wiki:wiki（或 wiki:wiki:readonly）与 docx:document（或 docx:document:readonly）权限。只有话题所有者是管理员或在知识库白名单（/auth wiki add @成员）中才能使用；打开文档前会在授权卡上征得话题所有者同意，每个话题一次。知识库范围为空时不挂载。对新会话生效。"
+		help: "让模型浏览「知识库范围」内的知识库节点，并读取 docx 文档、电子表格和多维表格（feishu_wiki_list / feishu_wiki_read / feishu_wiki_sheet_read / feishu_wiki_base_read），以应用身份访问。需开通 wiki:wiki、docx:document、sheets:spreadsheet、bitable:app 权限（或对应的只读权限）。只有话题所有者是管理员或在知识库白名单（/auth wiki add @成员）中才能使用；打开文档前会在授权卡上征得话题所有者同意，每个话题一次。知识库范围为空时不挂载。对新会话生效。"
 	},
 	"feishuTools.wikiWrite": {
 		label: "启用知识库写入工具",
-		help: "让模型在「知识库范围」内新建 docx 文档，并编辑本应用拥有的文档（feishu_wiki_create / feishu_wiki_edit），以应用身份访问；每次新建或编辑都需话题所有者在审批卡上同意。需开通 wiki:wiki 与 docx:document 权限；使用条件同读取工具（管理员或知识库白名单）。知识库范围为空时不挂载。对新会话生效。"
+		help: "让模型在「知识库范围」内新建 docx 文档、电子表格和多维表格，编辑本应用拥有的文档和电子表格，增改删本应用拥有的多维表格记录、向其他多维表格新增记录（feishu_wiki_create / feishu_wiki_edit / feishu_wiki_sheet_edit / feishu_wiki_base_edit），以应用身份访问；每次新建或编辑都需话题所有者在审批卡上同意。需开通 wiki:wiki、docx:document、sheets:spreadsheet、bitable:app 权限；使用条件同读取工具（管理员或知识库白名单）。知识库范围为空时不挂载。对新会话生效。"
 	},
 	wikiRoots: {
 		label: "知识库范围（wikiRoots）",