DeepChat Feishu/Lark 插件 MCP 工具路由指南从 SKILL.md 到飞书文档、表格与多维表格的智能操作【免费下载链接】deepchatDeepChat - 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.mdplugin.json设置贡献插件设置页面挂载在plugins分区入口为settings/index.html预加载类型声明为types/settings-preload.d.tsplugin.json。技能文档的开头 frontmatter 还带有一个deepchatFeature: feishu-integration元数据标记用于标注该技能归属于哪一类 DeepChat 功能特性仓库中另一处使用同一机制的例子是计算机使用技能deepchatFeature: computer-usecua/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-integrationname技能唯一标识与插件内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.feishuPlugin root${PLUGIN_ROOT}即插件安装目录serve.mjs中通过join(__dirname, ..)解析得到Server idfeishu-tools与 MCP 服务器 ID 一一对应。这些上下文变量在技能文档中被占位符引用实际值由 DeepChat 在加载技能时注入Agent 可据此定位插件与服务器。四、使用时机When To Use技能文档明确了三类触发场景文档类用户要求读取、总结、搜索、创建、更新、追加或整理飞书/Lark 文档电子表格类用户要求检查或编辑飞书/Lark 的电子表格、Sheet、表格或类似结构化工作台数据其他工件类用户要求操作其他飞书/Lark 工件且当前工具列表中存在名称或描述匹配的工具。一句话概括凡是与飞书/Lark 内容相关的请求只要当前会话暴露了匹配工具就直接调用而不是反问用户。五、必需行为Required Behavior七条路由准则技能文档给出七条硬性行为约束这是整份文档的核心以当前暴露的feishu-toolsMCP 工具为主要操作面飞书/Lark 请求一律走当前会话可用的 MCP 工具不另寻他路。以会话中的实时工具名与描述为准服务器实际支持什么以当前会话里工具列表呈现的名为准技能文档不臆造工具。直接调用匹配工具优先直接调用而不是向用户询问该如何调用插件或这是什么类型插件。技能文档开篇也特别强调不要要求用户把插件归类为 MCP 服务器、CLI 工具或其他插件类型。URL 标识提取用户给出飞书/Lark URL 时若目标工具期望 id 或 token应从中提取对应的文档、表格、电子表格或工作台标识。写操作谨慎确认对于可能覆盖或追加内容的写操作仅在目标工件或请求的变更存在歧义、或具有破坏性时才向用户确认。工具缺失时说明差距若请求的操作在当前暴露的工具中找不到匹配项应说明当前飞书预设Preset可能未包含该工具并描述能力缺口。认证/配置错误引导若工具调用返回认证或配置错误应引导用户打开飞书插件设置核对 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-mcp0.5.1并按下述方式传参serve.mjsconst 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 registryserve.mjs便于内网环境安装。当凭证缺失时serve.mjs会退化为警告服务器serve.mjs在initialize响应中返回提示文案tools/list只暴露一个名为feishu_configure的占位工具tools/call一律返回错误提示——这正好与技能文档第 7 条认证错误引导遥相呼应。九、设置界面与预设选项插件设置页settings/index.html将上述配置可视化Brandfeishu国内版或lark国际版index.htmlApp ID形如cli_xxxx的自建应用凭证index.htmlApp Secret密码输入框index.htmlMCP Preset工具预设下拉框可选值如下index.html预设值含义preset.default默认推荐覆盖绝大多数场景preset.light轻量工具集preset.im.defaultIM / 消息域preset.base.defaultBase / 数据库多维表格域preset.doc.default文档域preset.task.default任务域preset.calendar.default日历域保存时前端校验 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等方法。十、典型使用链路与排查路径综合以上机制一个典型的飞书操作链路如下用户给出飞书文档/表格 URL 或直接描述操作意图Agent 依据feishu-tools技能的 When To Use 判断属于文档/表格/其他工件域Agent 依据 Routing Hints 在当前会话暴露的工具中选择名称/描述匹配的工具需要 id/token 时从用户提供的 URL 中提取工件标识Required Behavior 第 4 条对覆盖/追加类写操作仅当存在歧义或破坏性时才向用户二次确认若当前预设未暴露目标工具如实说明能力缺口第 6 条若工具调用报认证/配置错误引导用户打开插件设置核对 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 工具面 预设机制三者协作关系的最佳入口。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepChat Feishu/Lark 插件 MCP 工具路由指南：从 SKILL.md 到飞书文档、表格与多维表格的智能操作
DeepChat Feishu/Lark 插件 MCP 工具路由指南从 SKILL.md 到飞书文档、表格与多维表格的智能操作【免费下载链接】deepchatDeepChat - 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.mdplugin.json设置贡献插件设置页面挂载在plugins分区入口为settings/index.html预加载类型声明为types/settings-preload.d.tsplugin.json。技能文档的开头 frontmatter 还带有一个deepchatFeature: feishu-integration元数据标记用于标注该技能归属于哪一类 DeepChat 功能特性仓库中另一处使用同一机制的例子是计算机使用技能deepchatFeature: computer-usecua/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-integrationname技能唯一标识与插件内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.feishuPlugin root${PLUGIN_ROOT}即插件安装目录serve.mjs中通过join(__dirname, ..)解析得到Server idfeishu-tools与 MCP 服务器 ID 一一对应。这些上下文变量在技能文档中被占位符引用实际值由 DeepChat 在加载技能时注入Agent 可据此定位插件与服务器。四、使用时机When To Use技能文档明确了三类触发场景文档类用户要求读取、总结、搜索、创建、更新、追加或整理飞书/Lark 文档电子表格类用户要求检查或编辑飞书/Lark 的电子表格、Sheet、表格或类似结构化工作台数据其他工件类用户要求操作其他飞书/Lark 工件且当前工具列表中存在名称或描述匹配的工具。一句话概括凡是与飞书/Lark 内容相关的请求只要当前会话暴露了匹配工具就直接调用而不是反问用户。五、必需行为Required Behavior七条路由准则技能文档给出七条硬性行为约束这是整份文档的核心以当前暴露的feishu-toolsMCP 工具为主要操作面飞书/Lark 请求一律走当前会话可用的 MCP 工具不另寻他路。以会话中的实时工具名与描述为准服务器实际支持什么以当前会话里工具列表呈现的名为准技能文档不臆造工具。直接调用匹配工具优先直接调用而不是向用户询问该如何调用插件或这是什么类型插件。技能文档开篇也特别强调不要要求用户把插件归类为 MCP 服务器、CLI 工具或其他插件类型。URL 标识提取用户给出飞书/Lark URL 时若目标工具期望 id 或 token应从中提取对应的文档、表格、电子表格或工作台标识。写操作谨慎确认对于可能覆盖或追加内容的写操作仅在目标工件或请求的变更存在歧义、或具有破坏性时才向用户确认。工具缺失时说明差距若请求的操作在当前暴露的工具中找不到匹配项应说明当前飞书预设Preset可能未包含该工具并描述能力缺口。认证/配置错误引导若工具调用返回认证或配置错误应引导用户打开飞书插件设置核对 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-mcp0.5.1并按下述方式传参serve.mjsconst 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 registryserve.mjs便于内网环境安装。当凭证缺失时serve.mjs会退化为警告服务器serve.mjs在initialize响应中返回提示文案tools/list只暴露一个名为feishu_configure的占位工具tools/call一律返回错误提示——这正好与技能文档第 7 条认证错误引导遥相呼应。九、设置界面与预设选项插件设置页settings/index.html将上述配置可视化Brandfeishu国内版或lark国际版index.htmlApp ID形如cli_xxxx的自建应用凭证index.htmlApp Secret密码输入框index.htmlMCP Preset工具预设下拉框可选值如下index.html预设值含义preset.default默认推荐覆盖绝大多数场景preset.light轻量工具集preset.im.defaultIM / 消息域preset.base.defaultBase / 数据库多维表格域preset.doc.default文档域preset.task.default任务域preset.calendar.default日历域保存时前端校验 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等方法。十、典型使用链路与排查路径综合以上机制一个典型的飞书操作链路如下用户给出飞书文档/表格 URL 或直接描述操作意图Agent 依据feishu-tools技能的 When To Use 判断属于文档/表格/其他工件域Agent 依据 Routing Hints 在当前会话暴露的工具中选择名称/描述匹配的工具需要 id/token 时从用户提供的 URL 中提取工件标识Required Behavior 第 4 条对覆盖/追加类写操作仅当存在歧义或破坏性时才向用户二次确认若当前预设未暴露目标工具如实说明能力缺口第 6 条若工具调用报认证/配置错误引导用户打开插件设置核对 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 工具面 预设机制三者协作关系的最佳入口。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
