Metadata-Version: 2.4
Name: lark-to-trae
Version: 1.1.4
Summary: 通过手机飞书(Lark)远程操控 Trae IDE 里的 AI Agent — 消息双向桥接工具
Author: ZyanWan
License: MIT
Project-URL: Homepage, https://github.com/ZyanWan/Lark_to_Trae
Project-URL: Repository, https://github.com/ZyanWan/Lark_to_Trae
Project-URL: Issues, https://github.com/ZyanWan/Lark_to_Trae/issues
Keywords: feishu,lark,trae,ide,bridge,remote-control,ai-agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pygetwindow>=0.0.9
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyperclip>=1.8.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Lark → Trae 桥接工具

[![GitHub Repo](https://img.shields.io/badge/GitHub-ZyanWan%2FLark_to_Trae-green)](https://github.com/ZyanWan/Lark_to_Trae)
[![PyPI Version](https://img.shields.io/pypi/v/lark-to-trae)](https://pypi.org/project/lark-to-trae/)
[![Python Version](https://img.shields.io/pypi/pyversions/lark-to-trae)](https://pypi.org/project/lark-to-trae/)

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

**依赖：** [pyautogui](https://pypi.org/project/pyautogui/) · [pygetwindow](https://pypi.org/project/pygetwindow/) · [pyperclip](https://pypi.org/project/pyperclip/) · [psutil](https://pypi.org/project/psutil/) · [lark-cli](https://github.com/larksuite/cli)

---

## 它能做什么？

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

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

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

---

## 快速开始

### 安装

```bash
pip install lark-to-trae
```

### 前置条件

| 依赖 | 说明 |
|------|------|
| [Node.js](https://nodejs.org/) 16+ | 用于运行 lark-cli |
| [Trae IDE](https://trae.com/) | 目标 IDE，需能正常启动 |
| 飞书自建应用 Bot | 在[飞书开放平台](https://open.feishu.cn/app)创建 |

### 第一步：安装 lark-cli

[lark-cli](https://github.com/larksuite/cli) 是飞书官方 CLI 工具，本项目依赖它完成消息收发。

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

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

1. 进入[飞书开放平台](https://open.feishu.cn/app)，创建自建应用
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

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

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

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

### 第四步：初始化本工具

```bash
lark-to-trae --setup
```

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

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

```bash
lark-to-trae --calibrate
```

### 第五步：启动

```bash
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 窗口截图 |

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

```bash
# 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_to_trae_config.example.json)。

```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」来源标签 |

---

## 进阶用法

### 消息过滤

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

### 自定义回复指令

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

### 开机自启（Windows）

创建 `start_bridge.bat`：

```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](https://github.com/larksuite/cli)（`@larksuite/cli`）WebSocket 长连接，事件订阅 `im.message.receive_v1` |
| 窗口操控 | [pyautogui](https://pypi.org/project/pyautogui/) + [pygetwindow](https://pypi.org/project/pygetwindow/) 点击定位 + 键盘模拟 |
| 文本粘贴 | [pyperclip](https://pypi.org/project/pyperclip/) 剪贴板，支持中文 |
| 系统信息 | [psutil](https://pypi.org/project/psutil/) 进程和系统监控 |
| 打包 | [pyproject.toml](https://github.com/ZyanWan/Lark_to_Trae/blob/main/pyproject.toml) (PEP 517) |

---

## 开发

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

# 构建分发包
python -m build
```

---

## 许可证

[MIT](LICENSE)
