飞书技能（Feishu Skill）——面向 Feishu API 的 AI 工具扩展

一种渐进式可扩展的技能，专为 AI 工具设计，用以调用飞书能力。其核心理念是：按需实现，仅在需要时实现所需功能。

⚠️ 重要提醒：创建新脚本后

每次创建任意新脚本后，你必须立即更新 scripts/script_index.json。

若未及时更新索引，将导致以下问题：

• 后续 AI 查找无法发现该新脚本
• 相同功能被重复实现
• 其他使用本技能的 AI 工具产生混淆

必须执行的操作：向 scripts/script_index.json 中添加一条记录，包含字段：name、description、usage_hint、added_date、tags

设计理念

本技能专为 AI 工具设计，而非供人工手动使用。

当 AI 工具接收到涉及飞书的任务时，应遵循如下流程：

1. 优先检查已有脚本 —— 在 scripts/script_index.json 中搜索已实现的 API
2. 仅在必要时实现 —— 若无匹配项，则使用 Context7 查询飞书 OpenAPI 文档
3. 完成后加入索引 —— 实现并验证通过后，立即将其登记至索引中，避免未来重复开发

该方法可确保：

• 零冗余投入 —— 仅在真实需求出现时才实现对应 API
• 渐进式扩展 —— 技能随实际使用场景持续演进与丰富
• 高效查找 —— AI 工具可快速定位已有可用能力

快速开始

完成身份认证配置后，本技能即可开箱即用：

# 配置身份认证（一次性设置）
cd scripts/env
echo '{"app_id": "your_app_id", "app_secret": "your_app_secret"}' > app.json

AI 工作流

决策逻辑

当 AI 遇到飞书相关任务时，请遵循以下决策树：

步骤 1：检查索引文件

读取 scripts/script_index.json
按 description、tags 字段进行搜索

若找到匹配项：

• 运行 python3 script.py --help 查看参数说明
• 执行该脚本
• 返回结果

若未找到匹配项：

• 使用 Context7 查询飞书 API 文档：

  Library: open.feishu.cn / larksuite
  Query: "[具体需求，例如：如何获取群组成员列表]"
  

• 依据文档实现新的 Python 脚本
• 执行并测试
• 重要：更新 scripts/script_index.json 添加新脚本条目

若执行失败：

• 检查 API 返回的错误信息
• 通过 Context7 或查阅 references/doc_urls.txt 获取文档支持
• 修复脚本
• 重新测试

关键决策点

在“复用现有脚本”与“新建脚本”之间做选择时，请考虑以下因素：

• 是否存在语义匹配？ 即使参数名不同，只要功能等价，就应优先复用已有脚本
• 实现成本如何？ 简单的单次调用类 API → 可立即实现；复杂的多步调用工作流 → 应优先评估是否可复用已有脚本组合达成
• 能否基于现有脚本组合实现？ 某些新功能可通过多个已有脚本协同完成

技术参考

脚本索引格式

scripts/script_index.json 的结构如下：

{
  "version": "1.0",
  "last_updated": "2026-02-12T12:00:00Z",
  "scripts": [
    {
      "name": "get_group_members",
      "description": "获取指定群组的人员列表",
      "usage_hint": "python3 get_group_members.py ",
      "added_date": "2026-02-12",
      "tags": ["group", "member", "user"]
    }
  ]
}

AI 搜索依赖的关键字段：

• description：功能的人类可读描述
• tags：用于匹配的关键词数组（模糊匹配时优先使用此字段）

身份认证

配置文件：scripts/env/app.json

{
  "app_id": "cli_xxxxxxxxxxxxxxxx",
  "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

获取凭证方式：

1. 登录飞书开放平台
2. 新建或选择一个应用
3. 在应用详情页中获取 App ID 和 App Secret

Token 管理：get_token.py 负责 Token 全生命周期管理：

• 在有效期内自动缓存
• 到期前 5 分钟自动刷新
• 缓存文件路径：scripts/env/token_cache.json

脚本模板

实现新 API 时，请使用以下模板：

#!/usr/bin/env python3
"""
[完整功能描述]

Usage:
    python3 script.py   [options]

Parameters:
    param1: 参数说明
    param2: 参数说明

Options:
    --page-size: 分页大小（默认值：20）
    --page-token: 分页 token

Output:
    JSON 格式输出：
    {
      "code": 0,
      "msg": "success",
      "data": { ... }
    }

References:
    Feishu API: https://open.feishu.cn/document/...
"""

import sys
import json
import subprocess
from pathlib import Path
import requests

# 配置
TOKEN_SCRIPT = Path(__file__).parent / "get_token.py"
BASE_URL = "https://open.feishu.cn"

def get_token():
    """获取飞书 access token"""
    result = subprocess.run(
        [sys.executable, str(TOKEN_SCRIPT)],
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout.strip()

def api_function(param1, param2, token, **kwargs):
    """API 调用函数"""
    headers = {"Authorization": f"Bearer {token}"}
    # ... 实现 API 调用
    pass

def main():
    # 处理 --help
    if "--help" in sys.argv or "-h" in sys.argv:
        print(__doc__)
        return

    # 解析必需参数
    if len(sys.argv) < 3:
        print(__doc__, file=sys.stderr)
        sys.exit(1)

    param1 = sys.argv[1]
    param2 = sys.argv[2]
    kwargs = {}

    # 解析可选参数
    for i in range(3, len(sys.argv)):
        if sys.argv[i].startswith("--"):
            key = sys.argv[i][2:].replace("-", "_")
            i += 1
            if i < len(sys.argv):
                kwargs[key] = sys.argv[i]

    # 获取 token
    token = get_token()

    # 调用 API
    result = api_function(param1, param2, token, **kwargs)

    # 输出 JSON
    print(json.dumps(result, indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()

开发规范：

1. ⚠️ 重要：创建任何新脚本后，你必须立即更新 scripts/script_index.json
2. 完整编写 docstring，包含 Usage、Parameters、Options、Output 等部分
3. 支持 --help 参数
4. 统一使用 get_token.py 进行身份认证
5. 输出标准 JSON 格式
6. 妥善处理异常，并提供友好的错误提示

📋 新脚本创建核对清单

实现新 API 时，你必须完成以下全部步骤：

• 使用 Context7 查询 API 文档
• 按照模板创建 Python 脚本
• 测试脚本执行（确认返回正确 JSON）
• ⚠️ 更新 scripts/script_index.json ← 切勿遗漏！
• 将 API 文档 URL 保存至 references/doc_urls.txt

使用 Context7 查询飞书 API

实现新 API 时，应通过 Context7 查询飞书文档：

Library ID: open.feishu.cn / larksuite
查询示例：
- "如何获取群组成员列表"
- "发送消息到飞书群组的 API 使用方法"
- "飞书文档操作的 OpenAPI"

为何选用 Context7？

• 提供最新、权威的 API 文档
• 含代码示例与完整参数说明
• 比手动网页搜索更高效
• 显著减少试错成本

示例

AI 任务示例 1：获取群组成员列表

用户请求：“获取群组 oc_xxxxxxxxxxxxx 的成员列表”

AI 决策过程：

1. 搜索 scripts/script_index.json → 找到匹配项：get_group_members
2. 执行：python3 scripts/get_group_members.py oc_xxxxxxxxxxxxx
3. 返回结果

AI 任务示例 2：新增 API 能力

用户请求：“从群组中删除一条消息”

AI 决策过程：

1. 搜索 scripts/script_index.json → 无匹配项
2. Context7 查询：“飞书删除消息 API”
3. 获取文档，确认存在 message/delete 接口
4. 实现 delete_message.py 脚本
5. 测试执行
6. ⛔ 关键步骤：在 scripts/script_index.json 中添加新条目 —— 此步不可跳过！
7. 返回结果

为何第 6 步至关重要：

• 若跳过，后续 AI 将无法在索引中查到 delete_message.py
• 将引发重复开发：相同功能被再次实现
• 违背“渐进式扩展”的核心设计哲学

参考资料

• 飞书开放平台
• 飞书 API 文档
• DEVELOPMENT.md —— 详细的开发指南