Homing（信鸽）🕊

AI 在家，结果必达。

在飞书里，驱动你家中那台电脑上的编码代理。

通勤路上想起一个问题，在飞书里给自己的 bot 发一句：「看下 gateway 最近频繁重启的原因」。

请求抵达你家中那台电脑，卡片随即开始更新：正在读取的文件、正在执行的命令、已用时长——与终端里是同一份过程，只是呈现在手机上。涉及修改文件时，它先给出一份计划等你确认，你浏览后点击【确认执行】才放开权限。

结果收敛回同一张卡片，标题变为「完成 · 23s」。

Homing 是一个常驻在你自己电脑上的网关，把终端交互翻译成聊天里的点按。代码、凭证、会话全部留在本机，没有任何共享服务端。

为什么你会喜欢它

你多半是在手机上、在路上、在会议间隙用它。而在这些场景下，输入文字的成本远高于点击——所以三件事都为「不打字」而设计。

过程看得见

任务跑起来后，卡片实时展示它正在做什么：读了哪个文件、执行了什么命令、已经花了多久。不是等几分钟，然后收到一整段文本。

操作点得动

切换目录、确认计划、回答选择题，全都是卡片上的按钮。终端里要输完整路径、ls 看目录、输编号选择，这里都是点一下。

带搜索框的卡片都有等价的文本路径，所以手机上飞书输入框不好用时，直接发 /cd 项目名 效果相同。

写操作可控

查询直接答。要改文件时，它先在物理只读模式下列出计划，等你确认。

这常被当作纯粹的安全机制，但日常价值在体验上：手机上浏览一份计划,就能决定放不放行，不必打开电脑审查 diff。相比在会话开始前就固定信任级别（全权限或只读），两段式把这个决定推迟到看见它将要执行什么之后——决策发生在信息最充分的时刻。

它还能做什么

消息管道 —— 发给 bot 的消息按你写的规则自动处理：模板回复、攒进日报、转发到 webhook 或另一个平台。

群消息简报 —— 以你自己的身份拉取群消息，用本机的编码代理提炼成结构化摘要（谁说了什么、待办、决策）。用你已有的订阅，不产生额外 API 费用。

不锁死在飞书 —— 聊天平台与编码代理各自封装在一层契约之后。飞书是深耕的那一面，卡片交互做得最完整；但 Telegram 是对等的第二实装，计划确认、目录切换、流式过程一个不少。接入新的只需写一个适配器并登记一行，领域层零改动（Telegram 就是这么接进来的）。

5 分钟跑起来

npm i -g homing-gateway && homing-gateway setup

交互式向导带完全部前置条件：环境自检 → 创建并绑定飞书应用（终端出二维码，扫一下就好，全程不用进开发者后台）→ 生成配置 → 可选接入 Telegram → 连通测试。最后一步可一键注册为系统服务，登录自启、崩溃自动重启。

全程幂等，中断后重跑会跳过已完成的步骤。

homing-gateway daemon install   # 注册为系统服务（登录自启 + 崩溃拉起）
homing-gateway daemon status    # 看状态；restart 重启，uninstall 摘掉

想先试试不装：npx homing-gateway setup 也能跑向导，但常驻服务必须全局安装——npx 的包在临时缓存里，清理后服务会指向一个消失的路径。daemon install 检测到这种情况会直接拒绝并提示。

只用 Telegram 也可以：向导第 2 步跳过飞书即可，不需要装 lark-cli、不需要飞书账号，也不需要公网 IP。

零依赖——只用 Node 内置模块（Node 20+），装下来不到 200KB，没有一个第三方包。

想改代码 / 贡献？ 走源码：

git clone https://github.com/roc-zjp/homing.git && cd homing && npm run setup

两条路共用同一份向导与数据目录（~/.lark-agent/），命令形式不同而已：源码下是 npm run setup / npm run daemon -- install。扩展见 扩展指南。

只响应你

它是你这台电脑的远程执行入口——任何能给 bot 发消息的人，都在以你的身份、你的额度、你的文件权限执行 AI 指令。所以准入是收紧的：

• 身份锁 —— 只响应配置里的那一个 owner，向导自动填好，无需手动查 id
• 陌生人拿不到东西 —— 发消息只会收到一个配对码，你在 IM 里 /pair <码> 批准后才能使用
• 写操作两段式 —— 默认先出计划等你确认；可信场景可用 /auto on 关掉
• 全部自托管 —— 会话、目录索引、凭证都在本机 ~/.lark-agent/，Web 控制台只绑回环 + 令牌 + Host 白名单

准入模型与各面现状见 部署与运维。

诚实的边界

• 它听不见你没拉它进去的聊天。 能收到的只有两处：私聊 bot、以及你把它拉进去的群。为了让群里不必每句都 @ 它，向导会申请「接收群聊中所有消息」权限——所以它所在的群，群里的话它都收得到。不在的群、你和别人的私聊，一概看不到。所以它是信息入口，不是聊天记录采集器；不想让它听见的群，别拉它进去。
• 一人一进程。 同一个 bot 的事件流只允许一个消费者，给同事用 = 同事自建一个 bot 跑自己的进程。
• 单用户假设。 已配对者的权限与 owner 基本相同，/cd 能到达文件系统任何位置。要真正多人共用，还缺目录隔离、per-user 会话隔离与用量记账。

文档

| 文档 | 内容 | |---|---| | 使用手册 | 两种用法、卡片交互、命令表、/cd 搜索、群简报 | | 配置 | config.json 全部字段 | | 部署与运维 | 后台常驻、目录与数据、排查、已知边界 | | 架构 | 数据流、逐文件分工、依赖分层与约束 | | 扩展 | 加命令 / 加规则动作 / 加卡片 / 换后端 / 接新 IM | | 卡片设计系统 | 语义色与组件词汇、5 屏视觉稿、改稿要点 | | 权限清单 | 飞书 scope 与凭证，照配即可复现 |

MIT © Roc

文档为中文。An English README is welcome as a PR.