一套可落地的飞书机器人方案：支持多 Skill 前缀触发、用户级权限控制、Skill 上传管理与统一执行治理。

一、项目背景

在很多企业内部场景里，飞书机器人常常只做“单能力问答”，很快会遇到三个问题：

1. 能力扩展慢：每增加一个能力都要改代码、发版本。

2. 权限不可控：不同用户是否能调用某个 Skill 缺乏精细化管理。

3. 输出不稳定：接入 LLM/CLI 后，回答格式容易混杂 SQL、执行痕迹等技术细节。

本项目围绕这三个问题，构建了一套“飞书交互 + 多 Skill 管理 + 用户权限治理”的统一架构。

二、核心目标

本方案重点实现了以下能力：

• 飞书长连接订阅事件，实时接收用户消息。

• 多 Skill 路由：通过前缀（如 alert,log）动态触发对应 Skill。

• 用户权限管控：支持“飞书用户绑定系统用户 + 用户级 Skill 授权/禁用”。

• Skill 管理：支持注册、启停、默认策略、压缩包上传解压并自动注册。

• 统一执行链路：通过通用执行器调用 Skill，并统一清洗回复内容，提升可读性。

三、整体处理逻辑（端到端）

1. 消息接入层（飞书）

• 采用飞书事件订阅（长连接）模式接收 im.message.receive_v1。

• 事件进入后先做去重，再异步处理，避免重复消费与阻塞。

2. 指令解析与路由

• 支持两种调用方式：

  • 显式调用：/skill <skill_name> <input>

  • 前缀触发：<trigger_prefix> <input>（如 alert 最近一年告警）

• 前缀映射来自数据库 skill_registry.trigger_prefix，可动态管理，无需写死代码。

3. 权限判定

• 从飞书事件中获取 open_id。

• 在 feishu_user_map 中映射为系统 user_id。

• 再校验：

  • Skill 是否启用（skill_registry.enabled）

  • 用户是否显式授权（user_skill_permission.allowed）

  • 若无显式记录，按 allow_by_default 决策

  • 若存在软删除记录，默认拒绝（防止删除后仍被放行）

4. Skill 执行

• 使用统一执行器调用 Skill（可插拔）。

• 支持处理中的进度反馈（回复 + 更新消息），提升交互体验。

5. 输出治理

• 对 Skill 结果统一清洗，去除技术噪声：

  • SQL 片段

  • 查询条件解释

  • CLI 执行痕迹（如 Ran ...、Worked for ...）

  • Markdown 符号在飞书 text 中的原样展示问题

• 最终只返回面向业务用户的可读文本。

四、数据模型设计（权限与管理）

feishu_user_map

用于飞书用户与系统用户绑定。

• feishu_open_id

• user_id

• deleted_at（软删除）

skill_registry

用于 Skill 元数据与路由策略管理。

• skill_name

• display_name

• description

• trigger_prefix（前缀触发关键字段）

• skill_dir（技能包解压目录）

• enabled

• allow_by_default

• deleted_at

user_skill_permission

用于用户级 Skill 权限。

• user_id

• skill_name

• allowed

• deleted_at

五、Skill 管理能力 – 可插拔

项目支持通过压缩包上传 Skill：

• 上传 zip 文件（包含 SKILL.md）

• 服务端安全解压（防路径穿越）

• 解压到固定目录（基于 CODEX_HOME/skills）

• 自动写入 skill_registry（与 upsert 关联）

• 立即生效并可被前缀触发

这使得 Skill 扩展从“改代码发版”变为“上传配置化接入”。

六、飞书交互体验优化点

• 回复形式：优先以“回复原消息”方式返回，语义更清晰。

• 流式反馈：先返回“处理中”，再更新同一条消息，最终替换为结果。

• 权限友好提示：未绑定时直接返回 feishu_open_id，便于管理员快速绑定。

七、关键价值总结

这套方案的核心价值是把“能力扩展、权限治理、交互体验”统一到了一个可运维框架里：

• 对业务：问答体验稳定、结果可读。

• 对研发：Skill 可插拔，接入成本低。

• 对管理：用户权限可控，风险边界清晰。

• 对平台：飞书入口统一，能力可以持续增长。

八、效果展示

1. 无 Skill 权限提示

说明：当用户没有对应 Skill 使用权限时，系统会在飞书会话中直接返回拒绝提示，避免越权调用。

2. 只读数据库查询数据

说明：数据库类 Skill 仅允许只读查询，返回经过清洗后的业务结果，不暴露执行细节和底层 SQL 过程信息。

3. Loki 告警平台日志查询

说明：日志类 Skill 支持在飞书中直接按自然语言触发 Loki 查询，实现告警平台日志的快速检索与反馈。

4. Skill 技能管理

说明：平台侧支持统一维护 Skill 元数据与状态，包括启停、触发前缀、默认授权策略等关键配置。

5. 平台用户 Skill 权限管理

说明：支持按用户维度配置 Skill 使用权限，结合飞书用户绑定，实现“谁可以调用哪些 Skill”的精细化控制。

九、结语

从“单一机器人”到“可治理的 Skill 平台”，关键不只是接上 LLM，而是建立一条完整、可控、可扩展的工程链路。 飞书作为入口，Skill 作为能力单元，权限与管理作为治理底座，这就是本项目的核心实践路径。