lark-kiro-bridge

v0.7.0

Published

a day ago

Bridge Feishu/Lark messenger with local Kiro CLI — streaming cards, per-chat sessions, named workspaces

0High
0Medium
0Low

walterhandsome

feishu lark kiro kiro-cli bridge bot ai-coding-agent

lark-kiro-bridge

把 Kiro CLI 接到飞书 / Lark — 在飞书里聊代码、跑命令、操作飞书自己。

🇨🇳 中文 | 🇺🇸 English

群里 @bot 或私聊机器人，消息直达本地 kiro-cli chat，回复以结构化卡片 + 流式打字光标实时刷新。每个 chat 独立 session，切目录不丢上下文。

核心价值：云端 AI 编程助手（Cursor / Copilot / Devin）碰不到你本机的项目目录，也没有飞书 API 调度能力。lark-kiro-bridge = 在飞书里跑本地命令 + 操作飞书自己，一个机器人解决两件事。

┌───────────────────────────────────────┐
│ 💬 Kiro                                │
├───────────────────────────────────────┤
│ ☕ 3 个工具调用 ▸ (folded)             │
│ ✅ Bash — lark-cli calendar +create…▾ │  ← 最新工具实时展开
│ ┌─────────────────────────────────┐   │
│ │ **Command** lark-cli calendar … │   │
│ │ **Output** {"ok": true, ...}    │   │
│ └─────────────────────────────────┘   │
│                                        │
│ 日程已创建成功 ✅                      │
│ 主题：测试                             │
│ 时间：今天 23:00 ~ 明天 00:00          │
│                                        │
│ ✍️ 正在输出     [ ⏹ 终止 ]            │
└───────────────────────────────────────┘

✨ 特性

🎴 结构化卡片 — 每次工具调用一个独立可折叠面板，多调用自动聚合，思考过程独立展示
⚡ 流式打字光标 — 飞书原生 streaming_mode，配合 footer 实时状态指示
🗂️ 工作区方案 B — 切目录不丢上下文：每个 (chat, cwd) 独立 Kiro session，自动续聊
🔘 按钮可点 — /model /help /status /ws list /config 全部可点击操作，0 命令记忆
📝 /config 飞书内表单 — 在飞书里改访问控制和偏好，即时生效，防自锁校验
🚄 rapid-fire 消息合并 — 200ms 内连发的多条短消息自动合并为一次 Kiro 调用，不再被前一条 abort
⏰ /cron 定时任务 — 标准 cron / shorthand / 中文关键词都接受；不识别时让 Kiro 自己翻译，二次确认后创建。"每天 9 点总结昨天的 commits" 一句话搞定
📅 /schedule new 可视化定时表单 — 不会写 cron 表达式的同学（HR / 销售 / 行政等）直接填表：小时、分钟、内容三个框搞定。底层和 /cron 共享存储
🧠 /steering 飞书内管理 Kiro 指令文件 — list/view/edit/new/rm，全局或项目 scope，飞书表单直接改，永久生效
🎤 语音输入 — 飞书发语音消息 → 自动转写（飞书 ASR）→ 喂给 Kiro，需 ffmpeg 和 ASR 权限
🛡️ 进程组 kill — detached: true + process.kill(-pid) 杀掉 kiro-cli 全部子孙
⏱ Idle Watchdog — 卡住自动 killTree，可全局 / per-chat 配置
🔐 三层访问控制 — 用户 / 群 / 管理员白名单，DM 永远豁免群白名单，不会把自己锁外面
🐧 跨平台守护 — macOS launchd / Linux systemd --user / Windows Task Scheduler，崩溃自动拉起，开机自启
🖥️ /ps /exit 进程管理 — 飞书内列出本机所有 bridge 进程，按按钮停止
📊 /doctor 自诊断 — 让 Kiro 看日志自己分析故障

🚀 快速上手

前置条件

macOS / Linux / Windows
Node.js ≥ 20
kiro-cli 已安装并登录
飞书账号（个人版即可，扫码自动创建应用）
可选：ffmpeg（用于语音输入转写，brew install ffmpeg / apt install ffmpeg）+ 飞书 ASR scope speech_to_text:speech（飞书免费版租户不支持）

30 秒上线 ⚡

# 1. 安装
npm i -g lark-kiro-bridge

# 2. 启动（首次会自动弹二维码 → 扫码同意 → 完成）
lark-kiro-bridge run

就这么简单——飞书 App 扫码同意后，bridge 自动创建应用、配好凭证、开通必要权限。

启动后在飞书私聊机器人发「你好」，应该立即看到流式刷新的卡片。

想用已有的飞书应用？

如果你已经在飞书开放平台手动建过应用，想复用已有的 App ID/Secret：

lark-kiro-bridge init --manual
# 交互式输入 App ID 和 App Secret

或一行搞定：

lark-kiro-bridge init --app-id cli_xxx --app-secret xxx

飞书后台手动配置（订阅事件 im.message.receive_v1 + card.action.trigger）→ docs/FAQ.md

后台守护（推荐生产）

lark-kiro-bridge start          # 装平台原生服务并启动
lark-kiro-bridge status         # 看状态
lark-kiro-bridge restart        # 重启

平台映射：

| 平台 | 实现 | 服务定义路径 | |---|---|---| | macOS | launchd 用户代理 | ~/Library/LaunchAgents/ai.lark-kiro-bridge.bot.plist | | Linux | systemd 用户单元 | ~/.config/systemd/user/lark-kiro-bridge.service | | Windows | Task Scheduler ONLOGON | 任务名 LarkKiroBridge.Bot，启动器 ~/.lark-kiro-bridge/daemon-launcher.cmd |

Linux 想让 daemon 在用户登出后还跑（比如服务器场景），跑一次： loginctl enable-linger $USER

📖 飞书内的命令

日常命令（所有人）

| 命令 | 别名 | 作用 | |---|---|---| | /help | /h /? | 帮助卡片（可点按钮） | | /status | /s | 当前 cwd / session / watchdog | | /model [name] | /m | 查看 / 切换模型，按钮一键切 | | /new | /reset | 重置当前 cwd 下的 Kiro 会话 | | /stop | /abort | 停止正在跑的任务 | | /pwd | /cwd | 当前工作目录 | | /ws list | — | 列出命名工作区，按钮一键切 | | /timeout [N\|off] | /to | idle watchdog 阈值（分钟） | | /ps | — | 列出本机所有 bridge 进程 | | /steering | /memory /mem | 列出当前项目的 Kiro 指令文件（卡片+按钮） | | /cron | /schedule | 列出当前 chat 的定时任务（卡片+按钮） | | /doctor [描述] | — | 让 Kiro 看日志自诊断 |

管理员命令

| 命令 | 作用 | |---|---| | /config | 查看 / 编辑访问控制 + 偏好（飞书内表单，即时生效） | | /cd <path> | 切换工作目录（受 allowedRoots 限制） | | /ws save <name> | 把当前 cwd 存为命名工作区 | | /ws use <name> | 切到命名工作区 | | /ws remove <name> | 删除命名工作区 | | /steering edit/new/rm <name> | 编辑 / 新建 / 删除 steering 文件 | | /cron add <expr> <prompt> | 添加定时任务；expr 接受 cron / @daily / 每天9点 等 | | /cron rm/pause/resume/run <id> | 删除/暂停/恢复/手动跑指定任务 | | /schedule new | 弹一张表单卡片，0 cron 表达式建任务（小白入口；当前覆盖「每天 H:M」频率） | | /exit <id\|#> | 停止指定 bridge 进程（自己 / 他人） | | /reconnect | 强制重连飞书 WebSocket |

默认所有人都是管理员（access.admins 为空）。团队推广前请收紧。

响应规则：私聊全收；群里必须 @bot；@all 永不响应。

💡 使用场景

你: 删掉今天 23 点的会议
🤖 调 lark-cli calendar +agenda 找到日程 → 二次确认 → +delete

你: 整理一下上周的会议纪要发到产品群
🤖 lark-cli vc +list → 提取纪要 → 调 lark-cli message +send 到指定群

你: 把 portfolio 项目今天的改动 commit 一下
🤖 cd portfolio → git diff → 拆分 atomic commits → git push

你: 查一下张三的 open_id 顺便给他发个会议邀请
🤖 lark-cli contact +find 张三 → 拿到 open_id → 调 lark-cli calendar +create

你: [发了一张设计稿] 帮我评估技术可行性
🤖 自动下载图片 → @file 喂给 Kiro → 视觉分析 + 给出实现方案

⚙️ 配置

最小可用（自动生成）

lark-kiro-bridge init 写入 ~/.lark-kiro-bridge/config.json：

{
  "lark": {
    "appId": "cli_xxxxxxxxxxx",
    "appSecret": "xxxxxxxxxxxxxxxxxxxx"
  }
}

其他字段都有合理默认值。

完整配置参考

{
  "lark": {
    "appId": "cli_xxxxxxxxxxx",
    "appSecret": "xxxxxxxxxxxxxxxxxxxx"
  },
  "kiro": {
    "binPath": "kiro-cli",
    "trustedTools": [
      "fs_read", "fs_write", "grep", "glob", "code",
      "execute_bash", "web_search", "web_fetch"
    ],
    "timeoutMs": 600000,
    "idleTimeoutMinutes": 5,
    "model": "claude-sonnet-4.6"
  },
  "workspace": {
    "defaultCwd": "/Users/you/Projects",
    "allowedRoots": ["/Users/you/Projects"]
  },
  "access": {
    "allowedUsers": [],
    "allowedChats": [],
    "admins": []
  },
  "preferences": {
    "requireMentionInGroup": true,
    "cardUpdateIntervalMs": 800,
    "logRetentionDays": 7
  }
}

trustedTools — Kiro 不询问就能调用的工具：

fs_read fs_write grep glob code — 文件读写、代码搜索
execute_bash — 跑 shell 命令（lark-cli / git / 等）。单人用安全；团队场景请评估
web_search web_fetch — 联网搜资料

access — 三层白名单，详见 SECURITY.md：

allowedUsers 为空 = 所有人允许
allowedChats 为空 = 所有 chat 允许
admins 为空 = 所有人都是管理员

workspace.allowedRoots — /cd 能去的根目录白名单，限制爆炸半径。

CLI

lark-kiro-bridge init                # 扫码创建飞书应用（首选）
lark-kiro-bridge init --manual       # 手动输入已有 App ID/Secret
lark-kiro-bridge init --app-id <id> --app-secret <s>   # 一行搞定（CI 友好）
lark-kiro-bridge run                 # 前台启动（首次自动跳扫码）
lark-kiro-bridge config-show         # 显示当前配置（脱敏）

lark-kiro-bridge start               # 装并起 daemon
lark-kiro-bridge stop                # 停 daemon
lark-kiro-bridge restart             # 重启
lark-kiro-bridge status              # 状态
lark-kiro-bridge unregister          # 卸载

lark-kiro-bridge ps                  # 列本机所有 bridge 进程
lark-kiro-bridge kill <id> [--force] # 杀掉某个进程

📚 进阶文档

| 文档 | 内容 | |---|---| | docs/ARCHITECTURE.md | 整体数据流、卡片渲染体系、工作目录方案 B、设计取舍 | | docs/FAQ.md | 常见疑问 + 故障排查（机器人不响应 / 200340 / 卡片卡死 / …） | | SECURITY.md | 安全策略、漏洞披露、加固指南 | | CHANGELOG.md | 版本变更日志 |

🤝 参与贡献

PR / Issue 都欢迎。开发流程：

git clone https://github.com/walterwang0x01/lark-kiro-bridge.git
cd lark-kiro-bridge
pnpm install
pnpm typecheck && pnpm lint && pnpm test    # 提交前必跑
pnpm build
node bin/lark-kiro-bridge.mjs run           # 本地跑（先 stop daemon）

代码规范：TypeScript strict / Biome lint / vitest 测试 / commit 用 conventional commits。

路线图

v0.2 ✅ 当前版（结构化卡片 + 按钮回调 + Slack-style 工具面板 + 扫码绑定 + 语音输入 ASR）
v0.3 ✅ /config 飞书内表单 + 三层访问控制（DM 豁免群白名单）+ rapid-fire 消息合并
v0.4 ✅ Linux systemd / Windows Task Scheduler 守护 + /ps /exit 飞书内进程管理
v0.5 ✅ /steering 飞书内管理 Kiro 指令文件（list/view/edit/new/rm，global/project scope）
v0.6 ✅ /cron 定时任务（cron / shorthand / 中文关键词；不识别让 Kiro 翻译并二次确认）
v0.7 ✅ /schedule new 可视化表单（小白入口，0 cron 心智）+ /selftest 健康检查 + 修飞书 form 200530 隐藏 bug
v1.0 服务器集中部署 / 多用户隔离 / Web 管理面板

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

lark-kiro-bridge

目录

✨ 特性

🚀 快速上手

前置条件

30 秒上线 ⚡

想用已有的飞书应用？

后台守护（推荐生产）

📖 飞书内的命令

日常命令（所有人）

管理员命令

💡 使用场景

⚙️ 配置

最小可用（自动生成）

完整配置参考

CLI

📚 进阶文档

🤝 参与贡献

路线图

📄 License