Skip to content

Latest commit

 

History

History
301 lines (203 loc) · 7.39 KB

SETUP_FEISHU.md

File metadata and controls

301 lines (203 loc) · 7.39 KB

飞书 Agent 配置指南

让你的个人电脑变成飞书机器人的大脑，随时随地通过飞书对话控制你的电脑。

📋 目录

  1. 前置条件
  2. 方案选择
  3. 企业用户配置
  4. 个人用户配置
  5. 项目配置
  6. 运行与测试
  7. 常见问题

前置条件

必需环境

  • Python 3.8+
  • 本项目完整代码
  • LLM API 密钥（Claude/OpenAI 等，已在 llmcore/mykeys 中配置）

安装依赖

pip install lark-oapi

方案选择

你的情况 推荐方案 预计耗时
公司已有飞书企业版 企业用户配置 5-10分钟
个人用户/学习测试 个人用户配置 10-15分钟

企业用户配置

适用于：你的公司使用飞书，你有权限创建应用或联系管理员审批

步骤 1：创建应用

  1. 访问 飞书开放平台
  2. 登录你的企业飞书账号
  3. 点击右上角「创建应用」→「企业自建应用」
  4. 填写应用信息：
    • 应用名称：我的Agent助手（可自定义）
    • 应用描述：个人AI助手
    • 应用图标：可选

步骤 2：添加机器人能力

  1. 进入应用详情页
  2. 左侧菜单选择「添加应用能力」
  3. 找到「机器人」，点击「添加」
  4. 配置机器人信息（可保持默认）

步骤 3：配置权限

  1. 左侧菜单「权限管理」→「API 权限」
  2. 搜索并开通以下权限：
    • im:message - 获取与发送单聊、群组消息
    • im:message:send_as_bot - 以应用身份发送消息
    • contact:user.id:readonly - 获取用户 ID

步骤 4：获取凭证

  1. 左侧菜单「凭证与基础信息」
  2. 记录以下信息：
    • App ID：cli_xxxxxxxx
    • App Secret：xxxxxxxxxxxxxxxx

步骤 5：发布应用

  1. 左侧菜单「版本管理与发布」
  2. 点击「创建版本」
  3. 填写版本信息，提交审核
  4. 联系企业管理员审批（或自己是管理员直接审批）

步骤 6：获取你的 Open ID

  1. 应用审批通过后，在飞书中搜索你的机器人
  2. 给机器人发送任意消息
  3. 运行以下代码获取你的 Open ID：
# 临时运行一次，获取 open_id
import lark_oapi as lark
from lark_oapi.api.im.v1 import *

client = lark.Client.builder().app_id("你的APP_ID").app_secret("你的APP_SECRET").build()

# 监听消息，打印发送者的 open_id
def handle(data):
    print(f"你的 Open ID: {data.event.sender.sender_id.open_id}")

# ... 或者查看 fsapp.py 运行时的日志输出

个人用户配置

适用于：没有企业飞书账号，想个人测试使用

步骤 1：创建测试企业

  1. 访问 飞书开放平台
  2. 使用个人手机号注册/登录
  3. 点击右上角头像 →「创建测试企业」
  4. 填写企业名称（如：我的测试工作区）
  5. 创建完成后，你就是这个测试企业的管理员

步骤 2：创建应用

与企业用户步骤相同

  1. 点击「创建应用」→「企业自建应用」
  2. 填写应用信息

步骤 3：添加机器人能力

  1. 进入应用详情页
  2. 「添加应用能力」→「机器人」→「添加」

步骤 4：配置权限

  1. 「权限管理」→「API 权限」
  2. 开通权限：
    • im:message
    • im:message:send_as_bot
    • contact:user.id:readonly

步骤 5：获取凭证

  1. 「凭证与基础信息」
  2. 复制 App ID 和 App Secret

步骤 6：发布应用（测试企业可自审批）

  1. 「版本管理与发布」→「创建版本」
  2. 提交后，进入 飞书管理后台
  3. 「工作台」→「应用审核」→ 通过你的应用

步骤 7：在飞书客户端使用

  1. 下载 飞书客户端
  2. 登录你的测试企业账号
  3. 搜索你创建的机器人名称
  4. 开始对话！

项目配置

配置飞书凭证

编辑项目根目录的 mykey.py，添加：

# 飞书应用凭证
fs_app_id = "cli_xxxxxxxxxxxxxxxx"      # 替换为你的 App ID
fs_app_secret = "xxxxxxxxxxxxxxxx"       # 替换为你的 App Secret

# 允许使用的用户 Open ID 列表（可选，留空则允许所有人）
fs_allowed_users = [
    "ou_xxxxxxxxxxxxxxxxxxxxxxxx",       # 你的 Open ID
]

确认 LLM 配置

确保 llmcore/mykeys 中已配置 LLM API 密钥：

# 示例：Claude API
claude_config = {
    'apikey': 'sk-ant-xxxxx',
    'apibase': 'https://api.anthropic.com',
    'model': 'claude-sonnet-4-20250514'
}

运行与测试

启动服务

cd /path/to/pc-agent-loop
python fsapp.py

预期输出

==================================================
飞书 Agent 已启动（长连接模式）
App ID: cli_xxxxxxxxxxxxxxxx
等待消息...
==================================================

测试对话

  1. 打开飞书客户端
  2. 找到你的机器人
  3. 发送：你好
  4. 等待回复（首次可能需要几秒）

可用命令

在与机器人对话时，可以使用以下特殊命令：

命令 说明
/new 开始新对话，清除当前上下文
/stop 中止当前正在执行的任务
/restore <关键词> 恢复之前的对话上下文（根据关键词搜索历史记录）

命令示例

/new                    # 清空对话，重新开始
/stop                   # 停止正在运行的任务
/restore 昨天的任务      # 恢复包含"昨天的任务"关键词的历史对话

消息显示说明

  • ⏳ 表示任务正在执行中
  • 消息会实时更新，无需等待完成
  • 超长回复会自动分段发送

常见问题

Q: 提示「应用未发布」或「无权限」

A: 确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。

Q: 发送消息后没有回复

A: 检查：

  1. fsapp.py 是否在运行
  2. 终端是否有错误日志
  3. LLM API 密钥是否配置正确

Q: 提示「invalid app_id」

A: 检查 mykey.py 中的 fs_app_id 是否正确复制（包含 cli_ 前缀）

Q: 如何获取自己的 Open ID？

A: 运行 fsapp.py 后给机器人发消息，查看终端日志中的 open_id

Q: 能否多人同时使用？

A: 不能。一个应用只能有一个长连接，连接到一台电脑。每个人需要创建自己的应用。

架构说明

你的飞书 ←→ 飞书云 ←→ 长连接 ←→ fsapp.py ←→ Agent ←→ 你的电脑
                              ↑
                         运行在你电脑上
  • 消息通过飞书云转发到你电脑上运行的 fsapp.py
  • Agent 处理请求后，通过飞书 API 回复消息
  • 你的电脑必须保持运行 fsapp.py 才能响应消息

下一步

  • 自定义 Agent 行为：编辑 assets/sys_prompt.txt
  • 添加新工具：编辑 assets/tools_schema.json
  • 查看日志：运行时观察终端输出

文档版本：v1.1 | 更新日期：2026-03-07

v1.1 更新内容：

  • 新增「可用命令」章节（/new, /stop, /restore）
  • 新增消息显示说明（⏳ 进行中标记、实时更新等）