lark-to-trae 1.1.5

通过手机飞书(Lark)远程操控 Trae IDE 里的 AI Agent — 消息双向桥接工具

Lark → Trae 桥接工具

用手机飞书远程操控 Trae IDE 里的 AI Agent — 在外面也能让 AI 帮你写代码、操作文件、查资料，结果自动推送回手机

依赖： pyautogui · pygetwindow · pyperclip · psutil · lark-cli

---

它能做什么？

┌─────────────┐                        ┌───────────────────┐
│   手机飞书    │  ←→  飞书服务器  ←→  lark-cli  │     Trae IDE       │
│   (你)      │       (WebSocket)        │   (AI Agent)        │
└─────────────┘                        └───────────────────┘

• 手机发消息 → 自动注入到 Trae 聊天输入框 → AI 收到并处理
• AI 处理完毕 → 通过 lark-cli 发送结果/截图回你的手机飞书
• 自动确认收到消息
• 自动附加回复指令，新对话的 AI 也知道怎么回结果
• 支持飞书 post 格式（多行/换行正确显示）
• 一键截取 Trae 窗口画面并发送

适用场景：在外面时需要 Trae 帮你处理任务、不方便开电脑打字、远程让 AI 执行操作并把结果推送回手机。

---

快速开始

安装

pip install lark-to-trae

前置条件

依赖	说明
Node.js 16+	用于运行 lark-cli
Trae IDE	目标 IDE，需能正常启动
飞书自建应用 Bot	在飞书开放平台创建

第一步：安装 lark-cli

lark-cli 是飞书官方 CLI 工具，本项目依赖它完成消息收发。

npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g

第二步：在飞书开放平台创建 Bot

1. 进入飞书开放平台，创建自建应用
2. 在「应用功能」→「机器人」中开启机器人能力
3. 配置事件订阅：
   • 订阅方式选择「长连接」
   • 添加事件：im.message.receive_v1（接收消息）
4. 申请权限（「权限管理」→「开通权限」）：
   • im:message.p2p_msg:readonly — 读取用户发给机器人的私信
   • im:message.p2p_msg — （旧版权限，与上一个二选一）
   • im:message.group_at_msg:readonly — 读取群聊中 @ 机器人的消息（可选）
5. 点击「创建版本」并发布

第三步：配置 lark-cli

# 配置应用凭证（交互引导，按提示输入 App ID 和 App Secret）
lark-cli config init --new

# 登录授权（--recommend 自动选择常用权限范围）
lark-cli auth login --recommend

# 确认登录状态
lark-cli auth status

第四步：初始化本工具

lark-to-trae --setup

按提示完成：自动探测 lark-cli 路径、配置 Bot profile、校准 Trae 输入框坐标。

如果跳过坐标校准，之后可单独运行：

lark-to-trae --calibrate

第五步：启动

lark-to-trae

看到以下输出说明启动成功：

[时间] ℹ️ Lark → Trae 桥接脚本 启动
[时间] ℹ️   模式: ACTIVE (注入+发送)
[时间] ℹ️ 找到 Trae 窗口: 'xxx - Trae CN'
[时间] ℹ️ 监听中... (Ctrl+C 停止)

替代启动方式：python -m lark_to_trae

---

使用方式

监听模式

命令	说明
lark-to-trae	正式模式（监听 + 注入 + 确认 + 回复指令）
lark-to-trae --dry-run	仅监听（不注入，只打印消息）

初始化与调试

命令	说明
lark-to-trae --setup	首次设置向导
lark-to-trae --calibrate	校准 Trae 输入框坐标
lark-to-trae --set-pos <x> <y>	手动设置输入框坐标
lark-to-trae --test-inject "文本"	测试注入到 Trae
lark-to-trae --detect	探测 Trae 窗口和坐标信息

AI 处理完后发回结果

命令	说明
lark-to-trae --reply "结果"	发文字回复到飞书
lark-to-trae --screenshot	截取 Trae 窗口保存本地
lark-to-trae --screenshot --reply "说明"	截图+文字一起发回飞书（最常用）
lark-to-trae --reply --image "图片.png"	发已有图片到飞书

其他

命令	说明
lark-to-trae --config	显示当前配置
lark-to-trae --force	跳过环境检查强制启动
lark-to-trae --help	显示帮助

---

项目结构

lark_to_trae/                        # 项目根目录
├── pyproject.toml                    # 打包元数据、依赖、入口点
├── README.md                         # 本文件
├── LICENSE                           # MIT 许可证
├── .gitignore
├── requirements.txt                  # pip install -r requirements.txt
├── lark_to_trae_config.example.json  # 配置模板
└── lark_to_trae/                    # Python 包
    ├── __init__.py                   # 版本号 + 公共 API
    ├── __main__.py                   # python -m 支持
    ├── config.py                     # 配置管理 / 环境检测 / setup 向导
    ├── trae_controller.py            # TraeController：窗口查找、注入、截图
    ├── lark_listener.py              # LarkListener：lark-cli event consume 封装
    ├── bridge.py                     # FeishuToTraeBridge：主桥接编排
    ├── reply.py                      # 回复功能
    └── cli.py                        # CLI 参数路由

运行时生成的数据文件（位于 ~/.lark-to-trae/）：

文件	内容
lark_to_trae_config.json	个人配置（路径、坐标、bot 名）
_pending_message.json	最新消息的发送者信息
trae_screenshot_*.png	Trae 窗口截图

可通过环境变量自定义数据目录：

# Windows
set LARK_TO_TRAE_HOME=D:\my-data

# Linux/MacOS
export LARK_TO_TRAE_HOME=/path/to/data

---

配置详解

首次运行 --setup 后会生成 lark_to_trae_config.json，参考模板见 lark_to_trae_config.example.json。

{
  "lark_cli_path": "",
  "bot_profile": "",
  "input_fixed_pos": null,
  "allowed_senders": [],
  "message_prefix": "",
  "auto_reply_confirm": true,
  "auto_enter": true,
  "add_source_tag": true
}

字段	类型	说明
lark_cli_path	string	lark-cli 路径，自动探测，可手动填写
bot_profile	string	lark-cli 中创建的 bot profile 名称
input_fixed_pos	object/null	输入框坐标，{"x": 100, "y": 200}，通过 --calibrate 校准
allowed_senders	array	白名单 open_id 列表，空=接收所有人
message_prefix	string	消息前缀过滤，非空时只处理带此前缀的消息
auto_reply_confirm	bool	收到消息后是否自动回"已收到"
auto_enter	bool	注入后是否自动按回车发送
add_source_tag	bool	是否在消息前附加「来自飞书 xxx」来源标签

---

进阶用法

消息过滤

{
  "allowed_senders": ["ou_你的open_id"],
  "message_prefix": "/trae "
}

自定义回复指令

修改配置中的 reply_instruction 字段即可。设为空字符串可关闭。

开机自启（Windows）

创建 start_bridge.bat：

@echo off
lark-to-trae

放入 Win+R → shell:startup。

---

故障排查

问题	解决
收不到消息	确认用 bot profile、发给 Bot 本人、开放平台已发布版本、事件订阅已配置
注入失败	运行 --detect 检查窗口，--calibrate 重校坐标
中文注入丢失	pip install pyperclip 确保安装，注意窗口焦点
AI 不回复	确认 reply_instruction 不为空，注入消息含回复指引
消息循环	已内置 sender_type==app 过滤，确认使用最新版
截图发送失败	更新到最新版，已修复句柄泄漏
首次启动报环境问题	运行 lark-to-trae --setup 完成初始化

---

安全注意事项

1. 配置安全：lark_to_trae_config.json 含个人信息，勿提交到公开仓库
2. 执行权限：给 Bot 发消息 = 拥有你电脑 AI 的操作能力
3. 建议：配置 allowed_senders 白名单 + message_prefix 前缀过滤

---

技术栈

组件	技术
飞书通信	lark-cli（@larksuite/cli）WebSocket 长连接，事件订阅 im.message.receive_v1
窗口操控	pyautogui + pygetwindow 点击定位 + 键盘模拟
文本粘贴	pyperclip 剪贴板，支持中文
系统信息	psutil 进程和系统监控
打包	pyproject.toml (PEP 517)

---

开发

# 克隆后以开发模式安装
pip install -e .

# 构建分发包
python -m build

---

许可证

MIT