GitHub - skjjks/Remote-CLI: Ship code from Feishu. Terminal + Claude Code + OpenCode, all in chat.

Drive your dev box from Feishu — shell, Claude Code, opencode, file sync, all in chat cards.

在飞书里远程控制服务器、与 AI 编码助手对话、传输文件——就像把 VS Code Terminal + AI Copilot 装进了飞书。不需要 SSH 客户端，一个飞书就够了。

快速开始 · 功能特性 · 命令参考 · 架构设计 · 开发

🎬 使用场景

地铁上收到告警？ 打开飞书 → 发一条消息 → 服务器就在你手里。查日志、重启服务、让 AI 分析报错，全在聊天窗口完成。

✨ 功能特性

🤖 AI 双引擎

同时支持 Claude Code 和 opencode 两个 AI 编码助手，通过 SDK 获取结构化输出。

Claude Code 模式

你：帮我看下 src/index.ts 的错误处理

Claude：我来检查一下...
  📖 Read(src/index.ts)
  找到 3 个问题：
  1. handleCommand 缺少 try-catch
  2. Promise rejection 未捕获
  3. 错误日志缺少 stack trace

opencode 模式

你：!oc 优化这段代码的性能

opencode：正在分析...
  🔍 分析调用链路
  ⚡ 发现 3 处优化点：
  1. 重复的 await 可以并行
  2. 缓存未命中率过高
  3. JSON 序列化可以延迟

能力	说明
🔄 双后端切换	`!claude` / `!opencode` 随时切换
🎯 模型热切	`!model` 弹菜单卡点按钮切换；`!model sonnet` 也行
💼 会话菜单	`!list` / `!switch`（不带参）弹会话菜单卡，按钮切换或新建会话
⚡ 流式输出	AI 回复实时更新飞书卡片，不用等完整响应
🛡️ 工具权限	Claude 使用工具前弹出权限卡片——点 ✓ Allow / ✗ Deny 按钮，或继续输入数字。项目 `.claude/settings.local.json` 里 `permissions.allow` 白名单命中的命令会直接执行（SDK 行为）
💾 会话恢复	Bot 重启后自动恢复上次 AI 对话上下文
🔘 交互按钮	权限确认、文件覆盖等场景支持点按钮；老的「输入数字」方式依然保留

📁 文件传输

在飞书和服务器之间双向传输文件——发文件自动上传到服务器，!dl 把服务器文件发回飞书。

上传（飞书 → 服务器）

你：[发送 screenshot.png]

Bot：File saved
     Path: ~/uploads/screenshot.png
     Size: 245KB

下载（服务器 → 飞书）

你：!dl /tmp/report.pdf

Bot：[文件消息，可直接下载]

你：!dl /home/user/project/src

Bot：Packing directory...
     [src.tar.gz, 12MB]

能力	说明
📤 上传文件	在飞书直接发文件/图片，自动保存到服务器 `~/uploads/`
📥 下载文件	`!dl <path>` 把服务器文件发到飞书
📦 目录打包	`!dl <目录>` 自动打包为 tar.gz 下载
🖼️ 图片预览	图片文件以图片消息发送，飞书内直接预览
✏️ 在线编辑	`!edit <path>` 把文件加载进可编辑表单卡片，Save 原子写盘、Cancel 放弃（文件 ≤ 1000 字符，受飞书 `input` 组件硬上限）
⚠️ 冲突提醒	同名文件弹出卡片确认——点 Overwrite / Cancel 按钮，或输入数字

🖥️ 远程终端

在飞书聊天窗口发消息给 Bot，Bot 在服务器执行命令后以卡片形式返回结果——支持 vim、htop 等交互式程序。

能力	说明
⌨️ 命令执行	`!sh <command>` 执行任意 shell 命令
🖱️ 交互式程序	自动检测 vim / htop / nano，切换原始输入模式
⌨️ 快捷键	`!esc` `!enter` `!tab` `!ctrl+c` 等
📺 终端截图	`!screen` 截取终端画面为 PNG 图片，保留颜色和对齐
🎨 输出优化	ANSI 清理、语法高亮、错误标红、短输出优化
🔤 CJK 支持	自动检测系统字体，逐字符 fallback 渲染中文和特殊符号

_{!screen 把终端画面渲染成 PNG —— 颜色、对齐、CJK 一个不丢}

🃏 智能卡片

AI 回复以飞书卡片呈现，颜色区分后端，信息丰富一眼识别。

🟠 Claude
_{模型 · 路径 · token · 费用}

⚫ opencode
_{模型 · 路径 · token · 费用}

🔵 终端
_执行耗时

┌─────────────────────────────────────────────┐
│ 🟠 Claude · session-abc123 · Working...     │  ← 橙色 = Claude
├─────────────────────────────────────────────┤
│                                             │
│  我来帮你分析这段代码...                      │
│  📖 Read(src/config.ts)                     │
│  找到以下问题：                               │
│  1. getConfig() 缺少错误处理                 │
│                                             │
├─────────────────────────────────────────────┤
│ claude-opus-4-6 · /workspace/project        │
│ ↑12.3k ↓2.1k tokens · $0.05               │
└─────────────────────────────────────────────┘

🚀 快速开始

1️⃣ 创建飞书应用

在飞书开放平台创建应用：

应用能力 → 添加「机器人」
事件订阅 → 启用「WebSocket」模式
权限管理 → 添加以下权限：
  ✅ im:message              （接收和发送消息）
  ✅ im:message.receive_v1   （消息接收事件）
  ✅ im:resource             （上传和下载文件/图片）

2️⃣ 安装 & 配置

# 克隆并安装
git clone https://github.com/skjjks/Remote-CLI.git
cd Remote-CLI
npm install

# 创建配置
cp .env.example .env

编辑 .env，填入飞书应用凭据：

FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx

# 留空则允许所有人使用（首次部署推荐留空）
ALLOWED_USERS=

📋 完整配置项（点击展开）

变量	必填	说明	默认值
`FEISHU_APP_ID`	✅	飞书应用 App ID	—
`FEISHU_APP_SECRET`	✅	飞书应用 App Secret	—
`ALLOWED_USERS`	—	允许使用的用户 ID，逗号分隔	全部
`ANTHROPIC_API_KEY`	—	Anthropic API Key	—
`ANTHROPIC_BASE_URL`	—	API 代理地址	—
`TERMINAL_COLS`	—	终端宽度（列数）	`200`
`TERMINAL_ROWS`	—	终端高度（行数）	`24`
`CLAUDE_TIMEOUT`	—	Claude 响应超时（ms）	`300000`
`CLAUDE_DEFAULT_MODE`	—	权限模式 `default` / `auto`	`default`
`OPENCODE_TIMEOUT`	—	opencode 响应超时（ms）	`300000`
`UPLOAD_DIR`	—	文件上传保存目录	`~/uploads`

3️⃣ 启动

# 开发模式
npm run dev

# 生产部署（PM2 — 推荐）
npm run deploy

4️⃣ 验证

在飞书中给 Bot 发送：

!sh echo hello world

💡 收到 hello world 就说明一切就绪！

📖 命令参考

🤖 AI 交互

命令	说明
`!claude <prompt>`	发送消息给 Claude
`!opencode <prompt>`	发送消息给 opencode
`!oc <prompt>`	opencode 简写
`!model`	查看可用模型列表
`!model <name>`	切换模型
`!model reset`	恢复默认模型
直接发文字	发到当前 AI 会话

📁 文件传输

命令	说明
`!dl <path>`	下载服务器文件到飞书
`!download <path>`	同上（完整写法）
`!edit <path>`	在飞书卡片里编辑小文本文件（≤ 1000 字符）
直接发文件/图片	上传到服务器 `~/uploads/`

🖥️ 终端操作

命令	说明
`!sh <cmd>`	执行 shell 命令
`!screen` / `!sc`	终端截图（PNG 图片）
`!key <key>`	发送特殊键
`!esc` `!enter` `!tab`	快捷键
`!ctrl+c` `!ctrl+d`	Ctrl 组合键
`!up` `!down`	方向键
`!raw` / `!raw off`	原始输入模式

📋 会话管理

命令	说明
`!new` / `!new claude`	创建新会话
`!list`	列出当前会话
`!switch <id>`	切换会话
`!kill <id>`	终止会话
`!cd <path>`	切换 AI 工作目录
`!interrupt`	中断当前操作
`!history`	查看命令历史
`!whoami`	显示 User ID

🏗️ 架构设计

graph TB
    FS["<b>飞书 WebSocket</b><br/>实时消息推送"] --> Router["<b>消息路由</b><br/>index.ts"]

    Router --> TH["<b>终端处理</b><br/>handlers/terminal.ts"]
    Router --> AH["<b>AI 处理</b><br/>handlers/ai.ts"]
    Router --> SH["<b>会话处理</b><br/>handlers/session.ts"]
    Router --> FH["<b>文件处理</b><br/>handlers/file.ts"]

    TH --> TMUX["tmux"]
    AH --> AM["<b>AI Manager</b><br/>ai/manager.ts"]
    SH --> SM["<b>Session Manager</b><br/>terminal/session.ts"]

    AM --> CD["Claude SDK Driver"]
    AM --> OD["opencode SDK Driver"]

    CD --> CLI["Claude Code"]
    OD --> OC["opencode"]

    TMUX --> Shell["Shell"]

    Router --> Card["<b>Smart Card Builder</b><br/>bot/card.ts"]
    Card --> FS

    style FS fill:#4a9eff,color:#fff
    style Router fill:#722ed1,color:#fff
    style CD fill:#f5a623,color:#fff
    style OD fill:#8c8c8c,color:#fff
    style Card fill:#52c41a,color:#fff

📦 核心模块详情

模块	路径	职责
消息路由	`src/index.ts`	飞书消息分发、命令解析
AI 驱动	`src/ai/drivers/`	Claude SDK / opencode SDK 适配
AI 管理	`src/ai/manager.ts`	统一接口、会话生命周期
终端处理	`src/handlers/terminal.ts`	shell 命令、交互检测、快捷键、终端截图
终端截图	`src/terminal/screenshot.ts`	ANSI 解析、字体管理、Canvas 渲染 PNG
卡片构建	`src/bot/card.ts`	飞书卡片模板、ANSI 清理、语法高亮
飞书客户端	`src/bot/feishu.ts`	API 封装、WebSocket 消息收发
会话持久化	`src/terminal/session.ts`	会话存储、重连、24h 自动清理
文件传输	`src/handlers/file.ts`	双向文件传输、目录打包、冲突检测、`!edit` 表单卡
二进制检测	`src/terminal/binary-detector.ts`	NUL + 控制字节启发式判断是否二进制

🚢 生产部署

PM2 部署（推荐）

# 首次部署
npm run deploy

# 日常操作
npm run pm2:status    # 查看状态
npm run pm2:logs      # 查看日志
npm run pm2:restart   # 重启
npm run pm2:stop      # 停止

# 开机自启
pm2 startup && pm2 save

前置条件

依赖	用途
Node.js >= 18	运行环境
tmux	终端会话管理
飞书开放平台应用	Bot + WebSocket
Claude Code CLI	Claude（可选）
opencode	opencode（可选）

🛠️ 开发

npm test              # 运行测试 (297 tests)
npm run test:watch    # 监听模式
npm run lint          # 代码检查
npm run build         # 构建

📁 项目结构

src/
  index.ts                  # 入口 + 消息路由
  config.ts                 # 环境变量配置
  state.ts                  # 共享状态
  ai/
    manager.ts              # AI 会话管理器
    shared.ts               # 共享工具函数
    types.ts                # 接口定义
    drivers/
      claude-sdk.ts         # Claude Agent SDK 驱动
      opencode-sdk.ts       # opencode SDK 驱动
  bot/
    card.ts                 # 飞书卡片构建
    feishu.ts               # 飞书 API 客户端
  handlers/
    ai.ts                   # AI 命令处理
    terminal.ts             # 终端命令处理
    session.ts              # 会话管理命令
    file.ts                 # 文件上传下载处理
  terminal/
    tmux.ts                 # tmux 封装
    session.ts              # 会话持久化
    interactive.ts          # 交互式程序检测
    ansi-parser.ts          # ANSI SGR 转义码解析
    fonts.ts                # 系统字体检测与逐字符路由
    screenshot.ts           # 终端截图渲染 (Canvas → PNG)
    binary-detector.ts      # 二进制文件启发式判断（NUL + 控制字节）

Made with ❤️ for Feishu

_{MIT License · Built with TypeScript · Powered by Claude Code & opencode}

Name		Name	Last commit message	Last commit date
docs/images		docs/images
src		src
tests		tests
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ecosystem.config.js		ecosystem.config.js
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

🎬 使用场景

✨ 功能特性

🤖 AI 双引擎

📁 文件传输

🖥️ 远程终端

🃏 智能卡片

🚀 快速开始

1️⃣ 创建飞书应用

2️⃣ 安装 & 配置

3️⃣ 启动

4️⃣ 验证

📖 命令参考

🤖 AI 交互

📁 文件传输

🖥️ 终端操作

📋 会话管理

🏗️ 架构设计

🚢 生产部署

PM2 部署（推荐）

前置条件

🛠️ 开发

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎬 使用场景

✨ 功能特性

🤖 AI 双引擎

📁 文件传输

🖥️ 远程终端

🃏 智能卡片

🚀 快速开始

1️⃣ 创建飞书应用

2️⃣ 安装 & 配置

3️⃣ 启动

4️⃣ 验证

📖 命令参考

🤖 AI 交互

📁 文件传输

🖥️ 终端操作

📋 会话管理

🏗️ 架构设计

🚢 生产部署

PM2 部署（推荐）

前置条件

🛠️ 开发

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages