企业官网建设流程全解析

DeepChat Feishu/Lark 插件 MCP 工具路由指南：从 SKILL.md 到飞书文档、表格与多维表格的智能操作

【免费下载链接】deepchat🐬DeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat

本篇指南围绕 DeepChat 官方 Feishu/Lark 集成插件的feishu-tools技能文档（SKILL.md）展开，系统讲解该技能如何指导 Agent 将飞书/Lark 文档、电子表格、知识库等请求路由到插件暴露的 MCP 工具，并结合插件声明（plugin.json）、MCP 服务器引导实现（serve.mjs）与设置界面（settings/index.html）等仓库证据，说明其运行机制与配置方法。读完本文，你将理解该技能的行为约束、工具路由原则、预设（Preset）机制，以及认证失败时的排查路径。

一、技能文档在插件中的定位

feishu-tools是 DeepChat 官方 Feishu/Lark 插件（com.deepchat.plugins.feishu）向 Agent 暴露的"技能面"（Skill Surface）。它本身不实现任何飞书 API 调用逻辑，而是一份给 Agent 看的"路由与行为契约"：当用户提出与飞书/Lark 相关的请求时，Agent 依据该文档判断应该调用哪些 MCP 工具、以何种方式调用、何时需要向用户确认。

从插件声明可以看到三者如何被组织在一起：

• MCP 服务器：feishu-tools，以stdio传输方式由node ${plugin.root}/mcp/serve.mjs启动（plugin.json）；
• 技能注册：feishu-tools技能，scope: "agent"，路径指向skills/feishu-tools/SKILL.md（plugin.json）；
• 设置贡献：插件设置页面挂载在plugins分区，入口为settings/index.html，预加载类型声明为types/settings-preload.d.ts（plugin.json）。

技能文档的开头 frontmatter 还带有一个deepchatFeature: feishu-integration元数据标记，用于标注该技能归属于哪一类 DeepChat 功能特性；仓库中另一处使用同一机制的例子是计算机使用技能deepchatFeature: computer-use（cua/skills/computer-use/SKILL.md）。

二、frontmatter 元数据与技能身份

SKILL.md以 YAML frontmatter 开头：

name: feishu-tools description: Use the Feishu/Lark plugin MCP tools for Feishu documents, spreadsheets, knowledge content, and other matching workspace operations. metadata: deepchatFeature: feishu-integration

• name：技能唯一标识，与插件内skills[].id保持一致；
• description：向 Agent 描述技能的适用范围（文档、表格、知识内容等飞书工作台操作），这是 Agent 决定是否启用该技能的主要依据；
• metadata.deepchatFeature：内部特性归属标记。

从 DeepChat 的 SkillService 源码结构看，插件技能贡献会被校验其SKILL.md是否存在，缺失时会在日志中警告（src/main/skill/index.ts），说明SKILL.md是插件技能的事实标准入口文件。

三、运行时上下文（Runtime Context）

技能文档声明了三个由插件运行时注入的变量：

• Plugin id：${OWNER_PLUGIN_ID}，即com.deepchat.plugins.feishu；
• Plugin root：${PLUGIN_ROOT}，即插件安装目录（serve.mjs中通过join(__dirname, '..')解析得到）；
• Server id：feishu-tools，与 MCP 服务器 ID 一一对应。

这些上下文变量在技能文档中被占位符引用，实际值由 DeepChat 在加载技能时注入，Agent 可据此定位插件与服务器。

四、使用时机（When To Use）

技能文档明确了三类触发场景：

1. 文档类：用户要求读取、总结、搜索、创建、更新、追加或整理飞书/Lark 文档；
2. 电子表格类：用户要求检查或编辑飞书/Lark 的电子表格、Sheet、表格或类似结构化工作台数据；
3. 其他工件类：用户要求操作其他飞书/Lark 工件，且当前工具列表中存在名称或描述匹配的工具。

一句话概括：凡是与飞书/Lark 内容相关的请求，只要当前会话暴露了匹配工具，就直接调用，而不是反问用户。

五、必需行为（Required Behavior）：七条路由准则

技能文档给出七条硬性行为约束，这是整份文档的核心：

1. 以当前暴露的feishu-toolsMCP 工具为主要操作面：飞书/Lark 请求一律走当前会话可用的 MCP 工具，不另寻他路。
2. 以会话中的实时工具名与描述为准：服务器实际支持什么，以当前会话里工具列表呈现的名为准，技能文档不臆造工具。
3. 直接调用匹配工具：优先直接调用，而不是向用户询问"该如何调用插件"或"这是什么类型插件"。技能文档开篇也特别强调：不要要求用户把插件归类为 MCP 服务器、CLI 工具或其他插件类型。
4. URL 标识提取：用户给出飞书/Lark URL 时，若目标工具期望 id 或 token，应从中提取对应的文档、表格、电子表格或工作台标识。
5. 写操作谨慎确认：对于可能覆盖或追加内容的写操作，仅在目标工件或请求的变更存在歧义、或具有破坏性时才向用户确认。
6. 工具缺失时说明差距：若请求的操作在当前暴露的工具中找不到匹配项，应说明当前飞书预设（Preset）可能未包含该工具，并描述能力缺口。
7. 认证/配置错误引导：若工具调用返回认证或配置错误，应引导用户打开飞书插件设置，核对 App ID、App Secret、品牌（Brand）与预设（Preset）。

六、路由提示（Routing Hints）

技能文档为 Agent 提供了按域路由的启发式规则：

• 文档域：优先选择名称或描述中包含docs、docx、wiki、knowledge的工具；
• 表格域：优先选择名称或描述中包含sheets、spreadsheets、tables、bitable 类结构的工具；
• 任务/日历/IM 域：当当前预设暴露了对应领域的专用工具时，优先使用领域匹配的飞书/Lark 工具。

这条规则的落地依赖"预设"机制——不同预设暴露不同工具集合，因此路由结果会随预设变化。

七、重要约束：预设决定工具可用性

技能文档最后强调：

Tool availability depends on the current Feishu preset. The skill should guide tool choice, not invent unsupported tool names.

工具可用性取决于当前飞书预设，技能只负责"指导选型"，绝不"发明"不存在的工具名。这正是第 6 条行为（能力缺口说明）的底层原因：任何被请求但不在当前预设中的工具，Agent 都应如实说明，而不是硬编一个名字去调用。

八、源码佐证：MCP 服务器如何落地预设与配置

serve.mjs是理解上述机制的钥匙。它按以下顺序解析配置：

const config = loadConfig() // 读取插件根目录 config.json const appId = config?.appId || process.env.FEISHU_APP_ID || '' const appSecret = config?.appSecret || process.env.FEISHU_APP_SECRET || '' const brand = config?.brand || process.env.FEISHU_BRAND || 'feishu' const preset = config?.preset || ''

配置来源优先级为：config.json中的字段 > 同名环境变量 > 空值（serve.mjs）。

当appId与appSecret均已配置时，服务器会通过npx拉起官方 MCP 包@larksuiteoapi/lark-mcp@0.5.1，并按下述方式传参（serve.mjs）：

const args = ['-y', LARK_MCP_PACKAGE, 'mcp', '-a', appId, '-s', appSecret] if (brand === 'lark') { args.push('--domain', 'https://open.larksuite.com') } if (preset) { args.push('-t', preset) }

即：-a传 App ID、-s传 App Secret、brand === 'lark'时切换到 Lark 国际版域名、preset非空时通过-t指定工具预设。另外还支持REGISTRY_OVERRIDE环境变量覆盖 npm registry（serve.mjs），便于内网环境安装。

当凭证缺失时，serve.mjs会退化为"警告服务器"（serve.mjs）：在initialize响应中返回提示文案，tools/list只暴露一个名为feishu_configure的占位工具，tools/call一律返回错误提示——这正好与技能文档第 7 条（认证错误引导）遥相呼应。

九、设置界面与预设选项

插件设置页（settings/index.html）将上述配置可视化：

• Brand：feishu（国内版）或lark（国际版）（index.html）；
• App ID：形如cli_xxxx的自建应用凭证（index.html）；
• App Secret：密码输入框（index.html）；
• MCP Preset：工具预设下拉框，可选值如下（index.html）：

保存时，前端校验 App ID 与 App Secret 非空，随后通过invokeAction('config.set', ...)写入brand、preset、appId、appSecret，并提示"保存成功，重启 MCP 服务器后生效"（assets/index.js）。设置页还实时展示插件启用状态与feishu-tools服务器的运行状态（Running / Stopped / Error / Disabled），错误信息会直接展示在页面上（assets/index.js）。

配置读取同样走设置页：invokeAction('config.get')回填表单（assets/index.js）。设置桥接 API 的类型由types/settings-preload.d.ts声明，包含getPluginId、getStatus、enable、disable、invokeAction等方法。

十、典型使用链路与排查路径

综合以上机制，一个典型的飞书操作链路如下：

1. 用户给出飞书文档/表格 URL 或直接描述操作意图；
2. Agent 依据feishu-tools技能的 When To Use 判断属于文档/表格/其他工件域；
3. Agent 依据 Routing Hints 在当前会话暴露的工具中选择名称/描述匹配的工具；
4. 需要 id/token 时，从用户提供的 URL 中提取工件标识（Required Behavior 第 4 条）；
5. 对覆盖/追加类写操作，仅当存在歧义或破坏性时才向用户二次确认；
6. 若当前预设未暴露目标工具，如实说明能力缺口（第 6 条）；
7. 若工具调用报认证/配置错误，引导用户打开插件设置核对 App ID、App Secret、Brand、Preset（第 7 条）。

排查认证问题时，可对照 serve.mjs 的配置解析优先级检查：插件设置是否已保存、环境变量FEISHU_APP_ID/FEISHU_APP_SECRET是否与config.json冲突、brand是否与账号所属区域（飞书国内版 vs Lark 国际版）匹配、所选预设是否包含目标工具。修改配置后需重启 MCP 服务器使其生效——这也是设置界面保存后的明确提示，与技能文档中"打开设置并核对参数"的引导形成了完整的闭环。

十一、设计要点总结

feishu-tools技能文档的设计体现了三个关键原则：

• 契约分离：技能只描述"如何路由"，工具实现完全交给 MCP 服务器（serve.mjs引导的lark-mcp），两者解耦、各自演进；
• 以实时工具清单为准：Agent 不依赖技能文档中硬编码的工具名，而是以会话中实际暴露的工具为唯一事实来源，避免工具集随预设变化时产生幻觉调用；
• 配置可追溯：从 frontmatter 元数据、插件声明、MCP 引导脚本到设置界面，全链路均有仓库内文件可查，认证失败时用户能在设置页一步定位问题。

对于需要在 DeepChat 中集成飞书/Lark 工作台的开发者，这份技能文档既是 Agent 的路由手册，也是理解"插件技能 + MCP 工具面 + 预设机制"三者协作关系的最佳入口。

【免费下载链接】deepchat🐬DeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat