302 lines
7.5 KiB
Markdown
302 lines
7.5 KiB
Markdown
# 飞书 Agent 配置指南
|
||
|
||
> 让你的个人电脑变成飞书机器人的大脑，随时随地通过飞书对话控制你的电脑。
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [前置条件](#前置条件)
|
||
2. [方案选择](#方案选择)
|
||
3. [企业用户配置](#企业用户配置)
|
||
4. [个人用户配置](#个人用户配置)
|
||
5. [项目配置](#项目配置)
|
||
6. [运行与测试](#运行与测试)
|
||
7. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
### 必需环境
|
||
|
||
- Python 3.8+
|
||
- 本项目完整代码
|
||
- LLM API 密钥（Claude/OpenAI 等，已在 `llmcore/mykeys` 中配置）
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pip install lark-oapi
|
||
```
|
||
|
||
---
|
||
|
||
## 方案选择
|
||
|
||
| 你的情况 | 推荐方案 | 预计耗时 |
|
||
| ------------------ | -------------------------- | --------- |
|
||
| 公司已有飞书企业版 | [企业用户配置](#企业用户配置) | 5-10分钟 |
|
||
| 个人用户/学习测试 | [个人用户配置](#个人用户配置) | 10-15分钟 |
|
||
|
||
---
|
||
|
||
## 企业用户配置
|
||
|
||
> 适用于：你的公司使用飞书，你有权限创建应用或联系管理员审批
|
||
|
||
### 步骤 1：创建应用
|
||
|
||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||
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：
|
||
|
||
```python
|
||
# 临时运行一次，获取 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}")
|
||
|
||
# ... 或者查看 frontends/fsapp.py 运行时的日志输出
|
||
```
|
||
|
||
---
|
||
|
||
## 个人用户配置
|
||
|
||
> 适用于：没有企业飞书账号，想个人测试使用
|
||
|
||
### 步骤 1：创建测试企业
|
||
|
||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||
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. 提交后，进入 [飞书管理后台](https://feishu.cn/admin)
|
||
3. 「工作台」→「应用审核」→ 通过你的应用
|
||
|
||
### 步骤 7：在飞书客户端使用
|
||
|
||
1. 下载 [飞书客户端](https://www.feishu.cn/download)
|
||
2. 登录你的测试企业账号
|
||
3. 搜索你创建的机器人名称
|
||
4. 开始对话！
|
||
|
||
---
|
||
|
||
## 项目配置
|
||
|
||
### 配置飞书凭证
|
||
|
||
编辑项目根目录的 `mykey.py`，添加：
|
||
|
||
```python
|
||
# 飞书应用凭证
|
||
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 密钥：
|
||
|
||
```python
|
||
# 示例：Claude API
|
||
claude_config = {
|
||
'apikey': 'sk-ant-xxxxx',
|
||
'apibase': 'https://api.anthropic.com',
|
||
'model': 'claude-sonnet-4-20250514'
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 运行与测试
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
cd /path/to/pc-agent-loop
|
||
python frontends/fsapp.py
|
||
```
|
||
|
||
### 预期输出
|
||
|
||
```
|
||
==================================================
|
||
飞书 Agent 已启动（长连接模式）
|
||
App ID: cli_xxxxxxxxxxxxxxxx
|
||
等待消息...
|
||
==================================================
|
||
```
|
||
|
||
### 测试对话
|
||
|
||
1. 打开飞书客户端
|
||
2. 找到你的机器人
|
||
3. 发送：`你好`
|
||
4. 等待回复（首次可能需要几秒）
|
||
|
||
---
|
||
|
||
## 可用命令
|
||
|
||
在与机器人对话时，可以使用以下特殊命令：
|
||
|
||
| 命令 | 说明 |
|
||
| ---- | ---- |
|
||
| `/new` | 开始新对话，清除当前上下文 |
|
||
| `/stop` | 中止当前正在执行的任务 |
|
||
| `/restore <关键词>` | 恢复之前的对话上下文（根据关键词搜索历史记录） |
|
||
|
||
### 命令示例
|
||
|
||
```
|
||
/new # 清空对话，重新开始
|
||
/stop # 停止正在运行的任务
|
||
/restore 昨天的任务 # 恢复包含"昨天的任务"关键词的历史对话
|
||
```
|
||
|
||
### 消息显示说明
|
||
|
||
- ⏳ 表示任务正在执行中
|
||
- 消息会实时更新，无需等待完成
|
||
- 超长回复会自动分段发送
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 提示「应用未发布」或「无权限」
|
||
|
||
**A:** 确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。
|
||
|
||
### Q: 发送消息后没有回复
|
||
|
||
**A:** 检查：
|
||
|
||
1. `frontends/fsapp.py` 是否在运行
|
||
2. 终端是否有错误日志
|
||
3. LLM API 密钥是否配置正确
|
||
|
||
### Q: 提示「invalid app_id」
|
||
|
||
**A:** 检查 `mykey.py` 中的 `fs_app_id` 是否正确复制（包含 `cli_` 前缀）
|
||
|
||
### Q: 如何获取自己的 Open ID？
|
||
|
||
**A:** 运行 `frontends/fsapp.py` 后给机器人发消息，查看终端日志中的 `open_id`
|
||
|
||
### Q: 能否多人同时使用？
|
||
|
||
**A:** 不能。一个应用只能有一个长连接，连接到一台电脑。每个人需要创建自己的应用。
|
||
|
||
---
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
你的飞书 ←→ 飞书云 ←→ 长连接 ←→ frontends/fsapp.py ←→ Agent ←→ 你的电脑
|
||
↑
|
||
运行在你电脑上
|
||
```
|
||
|
||
- 消息通过飞书云转发到你电脑上运行的 `frontends/fsapp.py`
|
||
- Agent 处理请求后，通过飞书 API 回复消息
|
||
- **你的电脑必须保持运行** `frontends/fsapp.py` 才能响应消息
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
- 自定义 Agent 行为：编辑 `assets/sys_prompt.txt`
|
||
- 添加新工具：编辑 `assets/tools_schema.json`
|
||
- 查看日志：运行时观察终端输出
|
||
|
||
---
|
||
|
||
*文档版本：v1.1 | 更新日期：2026-03-07*
|
||
|
||
**v1.1 更新内容：**
|
||
- 新增「可用命令」章节（/new, /stop, /restore）
|
||
- 新增消息显示说明（⏳ 进行中标记、实时更新等）
|