skill-message-bridge 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# 贡献指南 / Contributing
+
+欢迎参与 MessageBridge 的共建。本项目**不限定单一渠道**，当前已实现飞书，欢迎社区补全钉钉、企微等其它渠道。
+
+We welcome contributions. The project supports multiple channels (Feishu implemented; DingTalk, WeCom, etc. welcome).
+
+---
+
+## 一、贡献流程 / How to Contribute
+
+### 目标
+- 代码、文档、单测符合规范，便于维护与 AI 协作。
+
+### 步骤
+1. Fork 本仓库，在个人 fork 上创建分支（如 `feature/dingtalk` 或 `fix/xxx`）。
+2. 修改后在本机运行 `npm run build:dist`（若有改 src）及现有测试（如 `node test-quick.js`）。
+3. 提交信息建议格式：`类型: 简短描述`（如 `feat: 钉钉发送与等待回复`、`docs: README 英文版`）。
+4. 向本仓库发起 Pull Request，描述变更与自测结果。
+5. 维护者 Review 后合并。
+
+### 验收标准
+- [ ] 新代码有对应单测或已通过现有测试。
+- [ ] 文档/README 如有涉及则同步更新（中英双语优先）。
+- [ ] PR 描述说明「做了什么、如何验证」。
+
+---
+
+## 二、新渠道接入 / Adding a New Channel
+
+### 目标
+- 在不破坏现有飞书能力的前提下，新增一个 IM 渠道（如钉钉、企微），实现「发消息」与「等回复」。
+
+### 步骤与可执行清单（供人工或 AI 逐条完成）
+
+- [ ] **1. 平台适配器**  
+  在 `src/platforms/` 下新增 `<channel>.ts`（参考 `feishu.ts`），实现：
+  - 获取 access token（或该渠道等价物）。
+  - 建立长连接/订阅（若需收消息）。
+  - `sendMessage(task)`：发送一条消息并返回消息 ID。
+  - 在收到用户消息时，调用 `messageQueue.resolveTask(taskId, { reply, replyUser })` 与队列对接。
+- [ ] **2. 注册适配器**  
+  在 `src/index.ts`（或统一平台注册处）根据 `platform` 参数选择对应 adapter，保持 `notify(params)` / `send(params)` 的 `platform` 入参生效。
+- [ ] **3. Turn 脚本**  
+  新增 `dist/<channel>-turn.js`（可参考 `feishu-turn.js`）：读环境变量、调 `notify({ message, timeout })`、stdout 最后一行为单行 JSON `{"status":"replied"|"timeout"|"error","reply":"...","replyUser":"?"}`。
+- [ ] **4. 环境变量**  
+  在 README 与本文档中说明新渠道所需环境变量（如 `DINGTALK_APP_KEY`、`DINGTALK_APP_SECRET`、会话 ID 等）。
+- [ ] **5. 单测**  
+  为该渠道增加至少 1 个可运行的测试（发送或 mock 收消息），保证 CI/本地 `npm test` 或等价命令可覆盖。
+- [ ] **6. 文档**  
+  - README「支持的渠道」中列出新渠道及配置说明（中英双语）。
+  - 本文档「新渠道接入」下可补充该渠道的简要说明或链接。
+
+### 验收标准
+- [ ] 新渠道可通过 `notify` 发消息并拿到用户回复（或 timeout）。
+- [ ] 新渠道的 turn 脚本可在项目根目录执行并输出约定 JSON。
+- [ ] 单测通过；README/CONTRIBUTING 已更新。
+
+---
+
+## 三、单测要求 / Testing
+
+- **新功能**：应有对应单测（发送、收回复、超时、错误处理等，可 mock 网络）。
+- **新渠道**：至少覆盖「发送成功」或「模拟收到回复」一条路径。
+- **运行方式**：在项目根目录执行 `node test-quick.js` 或 `npm test`（以 package.json 为准）；CI 可在此基础上增加流水线。
+- **单测写法**：可参考现有 `test-quick.js`、`test-complete.js`；保持用例独立、不依赖外部未 mock 的服务。
+
+---
+
+## 四、文档与 AI 友好 / Docs & AI-Friendly
+
+为方便人类与 AI 贡献者按步骤完成工作，文档约定如下：
+
+- **结构化**：每个主题包含「目标 / 步骤 / 验收标准」三块，便于按步骤执行并自检。
+- **可执行清单**：如「新渠道接入」采用 checkbox 列表，可逐条勾选完成。
+- **格式与示例**：目录命名、单测风格、PR 描述格式在本文档中给出示例，贡献者可按示例仿写。
+- **中英双语**：README、CONTRIBUTING 及与贡献者相关的说明尽量提供中英版本（可在同一文件中用标题分隔）。
+
+---
+
+## 五、给 AI 贡献者 / For AI Contributors
+
+本项目欢迎由 AI 按文档完成的贡献（代码、文档、单测）。建议：
+
+- **推荐起点**：从「新渠道接入」或「文档/README 中英双语补全」类 issue 或任务入手。
+- **必读文件**：`README.md`、`CONTRIBUTING.md`（本文）、`src/platforms/feishu.ts`、`src/index.ts`、`feishu-turn.js` / `dist/feishu-turn.js`。
+- **执行顺序**：按 CONTRIBUTING 中「步骤」与「可执行清单」逐条完成，并在 PR 中说明已完成项与验收结果。
+- **提交与 PR**：提交信息与 PR 描述请写清「做了什么、如何验证」，便于维护者 Review。
+
+---
+
+## 六、发布到 GitHub / Publishing to GitHub
+
+若你希望将本仓库发布到自己的 GitHub 账号下：
+
+1. 在本机安装 [GitHub CLI](https://cli.github.com/)：`sudo apt install -y gh`（或 `brew install gh` / 见官方文档）。
+2. 登录：`gh auth login`，按提示完成 GitHub 授权。
+3. 在**本项目目录**下（若尚未初始化 git）：
+   ```bash
+   git init
+   git add .
+   git commit -m "Initial commit"
+   gh repo create message-bridge --public --source=. --push
+   ```
+4. 若仓库已存在，则：`git remote add origin <your-repo-url>` 后 `git push -u origin main`。
+
+（此节仅作说明，不要求贡献者必须执行。）
+
+---
+
+## 发布到 npm / Publish to npm
+
+维护者可将本仓库发布为 npm 包，便于用户 `npm install skill-message-bridge` 或 `npx skill-message-bridge "..."` 使用。
+
+1. 在 [npmjs.com](https://www.npmjs.com/) 注册账号并登录；本机执行 `npm login`。
+2. 在仓库根目录执行 `npm run build:dist`（或由 `prepublishOnly` 自动执行），确认 `dist/` 已更新。
+3. 执行 `npm publish`（首次发布）；若使用 scope 如 `@hulk-yin/message-bridge`，需在 package.json 中改 `name` 并执行 `npm publish --access public`。
+4. 发布后用户可通过 `npm install skill-message-bridge` 安装；未发布前可从 GitHub 安装：`npm install github:hulk-yin/message-bridge`。
+
+---
+
+# English (summary)
+
+- **Contribution flow**: Fork → branch → implement & test → commit (message: `type: short desc`) → open PR with description and self-check.
+- **New channel**: Add adapter in `src/platforms/`, register in index, add turn script and env docs, add tests, update README (EN+ZH).
+- **Testing**: New code should have tests; new channels need at least one test covering send or mock reply.
+- **Docs**: Structured (goal / steps / acceptance), checklists, examples; bilingual (EN+ZH) preferred.
+- **AI contributors**: Start from "new channel" or "docs i18n"; read README, CONTRIBUTING, `src/platforms/feishu.ts`, `src/index.ts`, turn script; follow checklists and state completion in PR.

package/INSTALL.md

@@ -0,0 +1,140 @@
+# 安装为 Skill / Install as Skill
+
+本仓库可作为 **Skill** 被 Cursor、Codex、Claude Code 等 AI 编码环境加载，实现「会话切换到飞书/钉钉」、发消息、等回复等能力。支持 **npm 包** 与 **Git 克隆** 两种方式。
+
+This repo can be installed as a **skill** in Cursor, Codex, Claude Code, etc. You can use **npm** or **Git clone**.
+
+---
+
+## 方式一：npm 包 / Via npm
+
+适合：在任意 Node 项目里直接依赖、或通过 `npx` 调用，无需克隆仓库。Skill 描述（SKILL.md）会随包安装到 `node_modules/skill-message-bridge/`，部分环境可从该路径读取。
+
+### 安装
+
+```bash
+# 项目依赖
+npm install skill-message-bridge
+
+# 或全局（可随处运行 message-bridge-turn）
+npm install -g skill-message-bridge
+```
+
+### 使用
+
+```javascript
+// 在代码中
+const messageBridge = require("skill-message-bridge");
+const result = await messageBridge.notify({ message: "请确认", timeout: 60 });
+```
+
+```bash
+# 命令行单轮（发到飞书并等回复）
+npx skill-message-bridge "你要发的内容"
+# 或全局安装后
+skill-message-bridge "你要发的内容"
+```
+
+配置好环境变量 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_CHAT_ID` 后即可使用。若需在 Cursor/Codex 中作为「可加载的 skill」（含 SKILL.md 说明），需将 skill 目录指向 `node_modules/skill-message-bridge`，或同时用下面的 Git 方式安装 SKILL 到 `.cursor/skills/`。
+
+**发布状态**：包名 `skill-message-bridge`，发布到 npm 后可直接 `npm install`。当前若未发布，可用 `npm install github:hulk-yin/message-bridge` 从 GitHub 安装。
+
+---
+
+## 方式二：Git 克隆（完整 Skill）/ Via Git clone
+
+安装后，**所有命令均在 skill 目录（即本仓库根目录）执行**。适合需要完整 SKILL.md + 源码、或需改代码贡献的场景。
+
+### Cursor
+
+Cursor 从项目的 `.cursor/skills/<name>/` 或用户级 skills 目录加载 skill；本仓库包含 `SKILL.md` + 实现代码，**整仓克隆到 skill 目录即可**。
+
+### 方式一：项目内安装（仅当前项目可用）
+
+在**项目根目录**执行：
+
+```bash
+git clone https://github.com/hulk-yin/message-bridge.git .cursor/skills/message-bridge
+cd .cursor/skills/message-bridge && npm install && npm run build:dist
+```
+
+之后 Cursor 会识别 `.cursor/skills/message-bridge/SKILL.md`，实现代码即同目录下的 `index.js`、`dist/feishu-turn.js` 等；AI 执行 `npm run turn` 时在 **`.cursor/skills/message-bridge`** 下执行即可。
+
+### 方式二：用户级安装（所有项目可用）
+
+若希望所有 Cursor 项目都能用，可克隆到 Cursor 用户级 skills 目录（具体路径以 Cursor 文档为准，常见为 `~/.cursor/skills/` 或 Cursor 设置中的 “Skills path”）：
+
+```bash
+mkdir -p ~/.cursor/skills
+git clone https://github.com/hulk-yin/message-bridge.git ~/.cursor/skills/message-bridge
+cd ~/.cursor/skills/message-bridge && npm install && npm run build:dist
+```
+
+安装后**重启 Cursor** 或重新加载技能，配置好 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` / `FEISHU_CHAT_ID` 即可使用。
+
+---
+
+## Codex (OpenAI)
+
+Codex 使用 `$CODEX_HOME/skills`（默认 `~/.codex/skills`），通过 **skill-installer** 从 GitHub 安装。若你已安装 [skill-installer](https://github.com/openai/skills) 的脚本，在具备网络权限的环境执行：
+
+```bash
+# 从 Codex 的 skill-installer 目录执行（或把 install-skill-from-github.py 放到 PATH）
+scripts/install-skill-from-github.py --repo hulk-yin/message-bridge --path .
+```
+
+将安装到 `$CODEX_HOME/skills/message-bridge`，目录内包含 `SKILL.md` 与完整实现。安装后**重启 Codex** 以加载新 skill。需在 skill 目录执行 `npm install` 与 `npm run build:dist` 后，`npm run turn` 等命令才可用。
+
+若无法使用上述脚本，可手动克隆：
+
+```bash
+git clone https://github.com/hulk-yin/message-bridge.git "${CODEX_HOME:-$HOME/.codex}/skills/message-bridge"
+cd "${CODEX_HOME:-$HOME/.codex}/skills/message-bridge" && npm install && npm run build:dist
+```
+
+---
+
+## Claude Code / 其他环境
+
+只要该环境支持「从某目录加载 skill（读取 SKILL.md 或等价描述）」，即可将本仓库克隆到该目录：
+
+```bash
+# 将 <SKILLS_ROOT> 替换为环境的 skill 根目录
+git clone https://github.com/hulk-yin/message-bridge.git <SKILLS_ROOT>/message-bridge
+cd <SKILLS_ROOT>/message-bridge && npm install && npm run build:dist
+```
+
+约定：
+
+- **Skill 根目录** = 本仓库根目录 = 包含 `SKILL.md` 与 `package.json` 的目录。
+- 所有文档中的 `npm run turn`、`node dist/feishu-turn.js` 等命令，均在 **该目录** 下执行。
+- 环境变量 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_CHAT_ID` 需在运行前配置（或使用 `DITING_FEISHU_*`）。
+
+---
+
+## 安装后自检
+
+在 **skill 根目录**（即本仓库根）执行：
+
+```bash
+npm install
+npm run build:dist
+# 配置 FEISHU_* 后做一次快速测试（会真实发飞书）
+node test-quick.js
+```
+
+若测试通过，即可在 Cursor/Codex/Claude 中通过「会话切换到飞书」或对应指令使用本 skill。
+
+---
+
+## 小结
+
+| 方式 | 环境        | 安装方式 | 说明 |
+|------|-------------|----------|------|
+| **npm** | 任意 Node 项目 | `npm install skill-message-bridge` | 代码中 `require("skill-message-bridge")`；命令行 `npx skill-message-bridge "..."`；未发布前可用 `npm install github:hulk-yin/message-bridge` |
+| **Git** | Cursor 项目 | `git clone ... .cursor/skills/message-bridge` | 项目内 `.cursor/skills/message-bridge` |
+| **Git** | Cursor 全局 | `git clone ... ~/.cursor/skills/message-bridge` | `~/.cursor/skills/message-bridge` |
+| **Git** | Codex       | `install-skill-from-github.py --repo hulk-yin/message-bridge --path .` 或手动 clone | `$CODEX_HOME/skills/message-bridge` |
+| **Git** | 其他        | `git clone ... <SKILLS_ROOT>/message-bridge` | `<SKILLS_ROOT>/message-bridge` |
+
+**统一约定**：Git 方式下，实现与命令均以「本仓库根目录」为当前目录；npm 方式下，命令在安装目录 `node_modules/skill-message-bridge` 或通过 `npx` 运行。

package/README.md

@@ -0,0 +1,118 @@
+# MessageBridge
+
+AI 智能体的多渠道消息桥梁，实现「发消息」与「等回复」，支持与 AI 对话闭环。**当前已实现飞书；钉钉、企微等欢迎社区共建。**
+
+A multi-channel message bridge for AI agents: send messages and wait for replies. **Feishu is implemented; DingTalk, WeCom, etc. welcome community contributions.**
+
+---
+
+## 如何对接不同渠道 / Supported Channels
+
+| 渠道 Channel | 状态 Status | 说明 |
+|-------------|-------------|------|
+| 飞书 Feishu | ✅ 已实现 | 需配置 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` / `FEISHU_CHAT_ID`（或 `DITING_FEISHU_*`），长连接收消息。 |
+| 钉钉 DingTalk | 📌 待共建 | 接口形态类似：发消息 + 收回复；接入步骤见 [CONTRIBUTING.md](./CONTRIBUTING.md#二新渠道接入--adding-a-new-channel)。 |
+| 企微 WeCom | 📌 待共建 | 同上，欢迎按 CONTRIBUTING 清单提交适配。 |
+
+扩展新渠道：在 `src/platforms/` 增加适配器并实现「发消息 + 将用户回复回填到队列」，详见 [CONTRIBUTING](./CONTRIBUTING.md)。
+
+---
+
+## 参与共建 / Community
+
+欢迎补全其它 IM 渠道、补全文档与单测、或改进现有实现。请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)，按「新渠道接入」清单或「贡献流程」提 PR；**欢迎 AI 按文档参与贡献**（见 CONTRIBUTING「给 AI 贡献者」）。
+
+---
+
+## 快速开始 / Quick Start
+
+```bash
+# 1. 安装依赖
+npm install
+
+# 2. 配置环境变量（飞书示例，请替换为你的应用与群聊 ID）
+export FEISHU_APP_ID="your_app_id"
+export FEISHU_APP_SECRET="your_app_secret"
+export FEISHU_CHAT_ID="oc_xxx"
+
+# 3. 构建（若改过 src）
+npm run build:dist
+
+# 4. 运行测试
+node test-quick.js
+```
+
+## 功能特性
+
+✅ **消息发送** - 发送消息到飞书群聊  
+✅ **等待回复** - 发送消息并等待用户回复  
+✅ **实时接收** - WebSocket 长链接实时接收消息  
+✅ **超时处理** - 可配置超时时间  
+✅ **任务队列** - 支持多任务管理  
+
+## 使用示例
+
+```javascript
+const messageBridge = require("./index.js");
+
+// 发送消息并等待回复
+const result = await messageBridge.notify({
+  message: "需要你确认一下",
+  timeout: 60,
+});
+
+if (result.status === "replied") {
+  console.log("用户回复:", result.reply);
+}
+
+// 仅发送消息
+await messageBridge.send({
+  message: "任务完成！",
+});
+```
+
+## 文档 / Docs
+
+- [INSTALL.md](./INSTALL.md) - **安装为 Cursor / Codex / Claude Code Skill**（中英）
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - 贡献流程、新渠道接入、单测与 AI 友好说明（中英）
+- [SKILL.md](./SKILL.md) - 与 AI 技能/闭环使用相关的详细说明
+
+## 开发进度
+
+详细进度请查看 [PROGRESS.md](./PROGRESS.md)
+
+## 测试
+
+- `test.js` - 基础消息发送测试
+- `test-sdk.js` - SDK 功能测试
+- `test-ws-debug.js` - WebSocket 调试测试
+- `test-complete.js` - 完整功能测试
+- `test-quick.js` - 快速测试
+
+## 技术栈
+
+- Node.js
+- @larksuiteoapi/node-sdk
+- WebSocket 长链接
+
+## 作者
+
+7号智创 - "7号，启航！"
+
+## 许可 / License
+
+MIT
+
+---
+
+## 安装方式 / Install
+
+- **npm**：`npm install skill-message-bridge`（发布后）；未发布可 `npm install github:hulk-yin/message-bridge`。代码中 `require("skill-message-bridge")`，命令行 `npx skill-message-bridge "..."`。
+- **Skill（Cursor / Codex / Claude）**：见 **[INSTALL.md](./INSTALL.md)**，支持 Git 克隆到各环境 skill 目录或从 npm 安装后使用。
+
+## English (short)
+
+- **What**: Send messages and wait for user replies over IM (Feishu implemented; other channels welcome).
+- **Quick start**: `npm install` → set `FEISHU_APP_ID` / `FEISHU_APP_SECRET` / `FEISHU_CHAT_ID` → `npm run build:dist` → `node test-quick.js`.
+- **API**: `notify({ message, timeout })` returns `{ status: "replied"|"timeout"|"error", reply, replyUser }`; `send({ message })` for fire-and-forget.
+- **Contributing**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for new channels, tests, and AI-friendly checklists.

package/SKILL.md

@@ -0,0 +1,238 @@
+# MessageBridge Skill
+
+AI 智能体的消息桥梁，连接飞书/钉钉/企微，实现异步通知与确认。
+
+**实现位置**：本仓库根目录即为 skill 实现目录。安装到 Cursor/Codex/Claude 等后，所有命令（如 `npm run turn`、`node dist/feishu-turn.js`）均在**该 skill 目录**下执行，不依赖绝对路径。安装方式见 [INSTALL.md](./INSTALL.md)。
+
+## 功能
+
+- ✅ 发送消息到飞书群聊
+- ✅ 发送消息并等待用户回复
+- ✅ WebSocket 长链接实时接收
+- ✅ 超时处理
+- ✅ 任务队列管理
+
+## 使用方式
+
+### 1. 环境变量配置（本 skill 无其他外部依赖）
+
+```bash
+export FEISHU_APP_ID="cli_xxx"
+export FEISHU_APP_SECRET="xxx"
+export FEISHU_CHAT_ID="oc_xxx"
+```
+
+（也支持 `DITING_FEISHU_*` 命名，便于与使用 Diting 的项目共用同一套配置。）
+
+### 2. 在 Node.js 中使用
+
+```javascript
+const messageBridge = require("./index.js");
+
+// 发送消息并等待回复
+const result = await messageBridge.notify({
+  message: "需要你确认一下这个操作",
+  timeout: 60, // 60秒超时
+});
+
+if (result.status === "replied") {
+  console.log("用户回复:", result.reply);
+  console.log("回复用户:", result.replyUser);
+} else if (result.status === "timeout") {
+  console.log("超时未回复");
+}
+
+// 仅发送消息（不等待回复）
+await messageBridge.send({
+  message: "任务已完成！",
+});
+```
+
+### 3. 在 OpenClaw 中使用
+
+```javascript
+// 在其他 AI 智能体中调用
+const { notify, send } = require("@skills/message-bridge");
+
+// 发送通知并等待确认
+const result = await notify({
+  message: "检测到异常，是否继续？",
+  timeout: 120,
+});
+
+if (result.status === "replied" && result.reply.includes("继续")) {
+  // 用户确认继续
+  console.log("用户确认，继续执行");
+} else {
+  // 用户拒绝或超时
+  console.log("用户拒绝或超时，停止执行");
+}
+```
+
+## API
+
+### notify(params)
+
+发送消息并等待用户回复。
+
+**参数：**
+- `message` (string, 必需) - 消息内容
+- `timeout` (number, 可选) - 超时时间（秒），默认 60
+- `platform` (string, 可选) - 平台类型，默认 "feishu"
+- `userId` (string, 可选) - 用户 ID
+- `groupId` (string, 可选) - 群聊 ID
+
+**返回：**
+```javascript
+{
+  success: true,
+  status: "replied" | "timeout" | "error",
+  reply: "用户回复内容",
+  replyUser: "ou_xxx",
+  timestamp: "2026-02-10T09:00:00.000Z"
+}
+```
+
+### send(params)
+
+仅发送消息，不等待回复。
+
+**参数：**
+- `message` (string, 必需) - 消息内容
+- `platform` (string, 可选) - 平台类型，默认 "feishu"
+- `userId` (string, 可选) - 用户 ID
+- `groupId` (string, 可选) - 群聊 ID
+
+**返回：**
+```javascript
+{
+  success: true,
+  messageId: "om_xxx"
+}
+```
+
+## 使用场景
+
+### 1. 审批流程
+```javascript
+const result = await notify({
+  message: "检测到高风险操作，需要审批\n\n操作：删除生产数据库\n请回复「批准」或「拒绝」",
+  timeout: 300, // 5分钟
+});
+
+if (result.status === "replied" && result.reply === "批准") {
+  // 执行操作
+}
+```
+
+### 2. 异常告警
+```javascript
+await send({
+  message: "⚠️ 服务器 CPU 使用率超过 90%\n\n时间: " + new Date().toISOString(),
+});
+```
+
+### 3. 任务完成通知
+```javascript
+await send({
+  message: "✅ 数据备份完成\n\n文件数: 1234\n大小: 5.6GB",
+});
+```
+
+### 4. 交互式确认
+```javascript
+const result = await notify({
+  message: "发现 3 个待处理的问题，是否立即处理？",
+  timeout: 60,
+});
+
+if (result.status === "replied" && result.reply.includes("是")) {
+  // 处理问题
+}
+```
+
+## 配置要求
+
+### 飞书开放平台配置
+
+1. **创建企业自建应用**
+2. **开通权限：**
+   - `im:message` - 发送消息
+   - `im:message:send_as_bot` - 以机器人身份发送
+3. **事件订阅：**
+   - 订阅方式：选择「长连接」
+   - 订阅事件：`im.message.receive_v1`
+4. **发布应用**
+
+## 会话切换到飞书 = 飞书长周期对话闭环
+
+当调用方（如 Cursor AI）收到用户说**「会话切换到飞书」**时，应进入**你与 skill 的长周期对话环境**：非飞书渠道启动 → AI 的输出发到飞书 → 飞书用户回复 → AI 基于回复继续思考 → 结果再发飞书，循环执行；**仅**在用户说「结束」「切回」时退出，不设轮数上限，不主动结束则永远 loop。
+
+**单轮工具**（供 AI 循环调用）：
+
+```bash
+npm run turn -- "<AI 的回复内容>" 或 node dist/feishu-turn.js "<AI 的回复内容>"（需先 npm run build:dist）
+```
+
+- 把内容发到飞书并等待用户回复。
+- 输出单行 JSON：`{"status":"replied","reply":"用户回复", "replyUser":"?"}`；超时为 `"status":"timeout"`。
+- 超时秒数：`FEISHU_TURN_TIMEOUT`（秒，默认 3600；飞书回复可能数小时可设 86400）。单轮超时后不要退出闭环，发「等待超时，如需继续请直接回复」并再次等待。
+
+**闭环**：循环执行「AI 生成回复 → 调用 npm run turn 或 node dist/feishu-turn.js → 解析 reply → 再生成 → 再调用」；仅用户说「结束」/「切回」时退出，不设轮数上限，永远 loop。
+
+**为何会自动断掉**：闭环在 Cursor 单次回复里跑，有工具调用/上下文上限，跑一段时间就会结束当次回复。**解决**：要不依赖 Cursor 的持久对话，可运行常驻进程 `node feishu-conversation.js`（配置 AI_REPLY_URL 或 OPENAI_API_KEY），在飞书里一直聊直到你说结束；若继续用 Cursor 闭环，断掉后说「继续飞书」即恢复。
+
+## 可选：纯飞书端对话（feishu-conversation.js）
+
+不经过 Cursor、只在飞书里和机器人对话时，可单独运行：
+
+```bash
+node feishu-conversation.js   # 或 npm run conversation
+```
+
+需配置 **AI_REPLY_URL** 或 **OPENAI_API_KEY**（+ OPENAI_BASE_URL、OPENAI_MODEL）。飞书需已订阅 `im.message.receive_v1`（长连接）。
+
+## 测试
+
+```bash
+# 基础测试
+node test.js
+
+# 完整功能测试
+node test-complete.js
+
+# WebSocket 调试
+node test-ws-debug.js
+
+# 快速测试
+node test-quick.js
+```
+
+## 技术实现
+
+- **SDK**: `@larksuiteoapi/node-sdk`
+- **连接方式**: WebSocket 长链接
+- **消息格式**: JSON
+- **超时处理**: Promise + setTimeout
+
+## 限制
+
+- 当前仅支持飞书平台
+- 仅支持文本消息
+- 简单的消息匹配逻辑（按时间顺序）
+
+## 未来计划
+
+- [ ] 支持钉钉、企业微信
+- [ ] 支持富文本、卡片消息
+- [ ] 改进消息匹配逻辑（基于 message_id）
+- [ ] 支持多用户并发
+- [ ] 添加消息历史记录
+
+## 作者
+
+7号智创 - "7号，启航！"
+
+## 许可
+
+MIT

package/dist/feishu-turn.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * 飞书单轮：把「你的回复」发到飞书，等待用户回复，输出用户回复（供 AI 在闭环中循环调用）。
+ * 用法：node feishu-turn.js "你要发到飞书的内容"
+ *       或 echo "内容" | node feishu-turn.js
+ * 输出：单行 JSON {"status":"replied"|"timeout"|"error", "reply":"用户回复", "replyUser": "?"}
+ * 超时：FEISHU_TURN_TIMEOUT 秒，默认 3600（1 小时）；飞书回复可能较久甚至数小时时可设为 86400 等。
+ */
+const mb = require("./index.js");
+
+const timeout = parseInt(process.env.FEISHU_TURN_TIMEOUT || "3600", 10);
+
+function getMessage() {
+  const arg = process.argv[2];
+  if (arg !== undefined && arg !== "") return arg;
+  const fs = require("fs");
+  if (!process.stdin.isTTY) {
+    return fs.readFileSync(0, "utf8").trim();
+  }
+  return "";
+}
+
+async function main() {
+  const message = getMessage();
+  if (!message) {
+    console.log(JSON.stringify({ status: "error", reply: "", error: "empty message" }));
+    process.exit(1);
+  }
+
+  try {
+    const result = await mb.notify({ message, timeout });
+    const out = {
+      status: result.status || "error",
+      reply: result.reply || "",
+      replyUser: result.replyUser || "",
+    };
+    if (result.error) out.error = result.error;
+    console.log(JSON.stringify(out));
+    process.exit(result.status === "replied" ? 0 : 1);
+  } catch (err) {
+    console.log(JSON.stringify({ status: "error", reply: "", error: err.message }));
+    process.exit(1);
+  } finally {
+    mb.close();
+  }
+}
+
+main();

package/dist/index.js

@@ -0,0 +1,266 @@
+/**
+ * MessageBridge Skill - 完整实现（修复版）
+ * 
+ * 使用飞书 WebSocket 长链接实现消息发送和接收
+ */
+
+const lark = require("@larksuiteoapi/node-sdk");
+
+// 配置
+const config = {
+  appId: process.env.FEISHU_APP_ID || process.env.DITING_FEISHU_APP_ID || "",
+  appSecret: process.env.FEISHU_APP_SECRET || process.env.DITING_FEISHU_APP_SECRET || "",
+  chatId: process.env.FEISHU_CHAT_ID || process.env.DITING_FEISHU_CHAT_ID || "",
+};
+
+// 全局客户端
+let httpClient = null;
+let wsClient = null;
+let eventDispatcher = null;
+let isInitialized = false;
+
+// 待处理的任务队列
+const pendingTasks = new Map();
+
+/**
+ * 初始化 MessageBridge
+ */
+async function init() {
+  if (isInitialized) {
+    return;
+  }
+
+  console.log("[MessageBridge] 初始化...");
+
+  // 创建 HTTP 客户端
+  httpClient = new lark.Client({
+    appId: config.appId,
+    appSecret: config.appSecret,
+    appType: lark.AppType.SelfBuild,
+    domain: lark.Domain.Feishu,
+  });
+
+  // 创建事件处理器
+  eventDispatcher = new lark.EventDispatcher({}).register({
+    "im.message.receive_v1": async (data) => {
+      const message = data.message;
+      
+      try {
+        const content = JSON.parse(message.content);
+        const senderId = message.sender?.sender_id?.open_id || message.sender?.sender_id?.user_id || "unknown";
+        const text = content.text || "";
+        
+        console.log(`[MessageBridge] 收到消息: ${text} (from ${senderId})`);
+        
+        // 查找等待回复的任务
+        for (const [taskId, task] of pendingTasks.entries()) {
+          if (task.status === "pending") {
+            // 简单匹配：回复最近的任务
+            task.reply = text;
+            task.replyUser = senderId;
+            task.status = "resolved";
+            task.repliedAt = new Date();
+            
+            // 触发回调
+            if (task.resolve) {
+              task.resolve(task);
+            }
+            
+            console.log(`[MessageBridge] 任务 ${taskId} 已解决`);
+            break;
+          }
+        }
+      } catch (error) {
+        console.error("[MessageBridge] 处理消息失败:", error.message);
+      }
+      
+      return { code: 0 };
+    },
+  });
+
+  // 创建 WebSocket 客户端
+  wsClient = new lark.WSClient({
+    appId: config.appId,
+    appSecret: config.appSecret,
+    loggerLevel: lark.LoggerLevel.error, // 只显示错误
+  });
+
+  // 启动 WebSocket
+  wsClient.start({ eventDispatcher });
+
+  // 等待连接建立
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  isInitialized = true;
+  console.log("[MessageBridge] 初始化完成");
+}
+
+/**
+ * 发送消息并等待回复
+ */
+async function notify(params) {
+  const {
+    message,
+    platform = "feishu",
+    userId,
+    groupId,
+    timeout = 60, // 默认 60 秒超时
+  } = params;
+
+  // 确保已初始化
+  await init();
+
+  // 创建任务
+  const taskId = `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  const task = {
+    taskId,
+    message,
+    platform,
+    userId,
+    groupId,
+    timeout,
+    status: "pending",
+    createdAt: new Date(),
+    reply: null,
+    replyUser: null,
+    repliedAt: null,
+  };
+
+  pendingTasks.set(taskId, task);
+
+  try {
+    // 确定接收者类型和 ID
+    const targetId = groupId || config.chatId || userId;
+    const receiveIdType = groupId || config.chatId ? "chat_id" : "open_id";
+    
+    // 发送消息
+    console.log(`[MessageBridge] 发送消息 (${receiveIdType}): ${message}`);
+    const res = await httpClient.im.message.create({
+      params: {
+        receive_id_type: receiveIdType,
+      },
+      data: {
+        receive_id: targetId,
+        msg_type: "text",
+        content: JSON.stringify({ text: message }),
+      },
+    });
+
+    if (res.code !== 0) {
+      throw new Error(`发送失败: ${res.msg}`);
+    }
+
+    console.log(`[MessageBridge] 消息已发送: ${res.data.message_id}`);
+
+    // 等待回复
+    const result = await new Promise((resolve, reject) => {
+      task.resolve = resolve;
+      task.reject = reject;
+
+      // 超时处理
+      setTimeout(() => {
+        if (task.status === "pending") {
+          task.status = "timeout";
+          reject(new Error("Timeout waiting for reply"));
+        }
+      }, timeout * 1000);
+    });
+
+    // 清理任务
+    pendingTasks.delete(taskId);
+
+    return {
+      success: true,
+      reply: result.reply,
+      replyUser: result.replyUser,
+      timestamp: result.repliedAt?.toISOString(),
+      status: "replied",
+    };
+  } catch (error) {
+    // 清理任务
+    pendingTasks.delete(taskId);
+
+    if (error.message.includes("Timeout")) {
+      return {
+        success: true,
+        status: "timeout",
+        error: "Timeout waiting for user reply",
+      };
+    }
+
+    return {
+      success: false,
+      status: "error",
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * 仅发送消息，不等待回复
+ */
+async function send(params) {
+  const {
+    message,
+    platform = "feishu",
+    userId,
+    groupId,
+  } = params;
+
+  // 确保已初始化
+  await init();
+
+  try {
+    // 确定接收者类型和 ID
+    const targetId = groupId || config.chatId || userId;
+    const receiveIdType = groupId || config.chatId ? "chat_id" : "open_id";
+    
+    console.log(`[MessageBridge] 发送消息 (${receiveIdType}): ${message}`);
+    const res = await httpClient.im.message.create({
+      params: {
+        receive_id_type: receiveIdType,
+      },
+      data: {
+        receive_id: targetId,
+        msg_type: "text",
+        content: JSON.stringify({ text: message }),
+      },
+    });
+
+    if (res.code !== 0) {
+      throw new Error(`发送失败: ${res.msg}`);
+    }
+
+    console.log(`[MessageBridge] 消息已发送: ${res.data.message_id}`);
+
+    return {
+      success: true,
+      messageId: res.data.message_id,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * 关闭连接
+ */
+function close() {
+  if (wsClient) {
+    // WebSocket 客户端没有 close 方法，会自动管理
+    console.log("[MessageBridge] 关闭连接");
+  }
+  isInitialized = false;
+}
+
+module.exports = {
+  init,
+  notify,
+  send,
+  close,
+  name: "messageBridge",
+  description: "AI 智能体的消息桥梁，连接飞书/钉钉/企微，实现异步通知与确认",
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "skill-message-bridge",
+  "version": "0.1.0",
+  "description": "AI 智能体的消息桥梁，连接飞书/钉钉/企微，实现异步通知与确认",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "test": "node test.js",
+    "conversation": "node feishu-conversation.js",
+    "build:dist": "node scripts/copy-to-dist.js",
+    "turn": "node dist/feishu-turn.js",
+    "prepublishOnly": "npm run build:dist"
+  },
+  "bin": {
+    "skill-message-bridge": "dist/feishu-turn.js",
+    "message-bridge-turn": "dist/feishu-turn.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md",
+    "INSTALL.md",
+    "CONTRIBUTING.md"
+  ],
+  "keywords": [
+    "message-bridge",
+    "feishu",
+    "dingtalk",
+    "wecom",
+    "ai-agent",
+    "notification",
+    "skill",
+    "cursor",
+    "codex"
+  ],
+  "author": "7号智创",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hulk-yin/message-bridge.git"
+  },
+  "homepage": "https://github.com/hulk-yin/message-bridge#readme",
+  "dependencies": {
+    "@larksuiteoapi/lark-mcp": "^0.5.0",
+    "@larksuiteoapi/node-sdk": "^1.58.0",
+    "node-fetch": "^2.7.0",
+    "ws": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.0.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^5.0.0"
+  }
+}