# omp-wechatClawbot

**Repository Path**: futurelei/omp-wechat-clawbot

## Basic Information

- **Project Name**: omp-wechatClawbot
- **Description**: 链接omp和wechat-clawbot（python的iLink接口）的项目仓库，简单运行扫描二维码即可链接omp和wechat的clawbot
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wechat-omp-bot

通过微信（iLink）远程驱动 [Oh My Pi](https://github.com/oh-my-pi)（`omp`）编码智能体：
微信扫码登录 → 直接发消息 → 消息作为 prompt 转发给 `omp --mode rpc` 会话执行 → 智能体回复回传到微信。

每个微信用户拥有**独立的、可续传的** omp 会话（`--session-dir` + `-c` 恢复），机器人重启后对话历史不丢。

## 特性

- 终端渲染二维码，微信扫码即登录（`wechatbot-sdk`），iLink 会话过期自动重登
- **多 omp 会话路由（特色）**：每个微信用户可有多个命名任务会话，按会话名+描述
  自动切换（强信号直切 / 弱信号确认），任务隔离互不干扰
- 每条非指令消息 = 一条 omp prompt，自带工具权限（读写工作目录、执行命令等）
- **自然语言技能**：子串 / jieba 关键词 / ternlight 语义（英文）三级匹配，20+ 本地命令零 token
- 回复脚注：供应商/模型 + 入/出/缓存 token + 费用（含缓存计价），本地命令标注“不消耗 token”
- **文件 + 图片 RAG**：发 txt/docx/pptx/pdf/图片 → 自动提取/OCR → 切块建索引 → 追问注入回答
- outbox 文件投递：按日期分目录，机器人生成文件自动发到微信
- **媒体处理**：发视频/音频 → ffmpeg 加速/截取/转格式/拼接，结果自动回传微信
- 会话运维：热重载技能 `/reload`、上下文压缩 `/compact`、模型切换 `/model`、组件安装 `/install`
- 退出零残留：SIGTERM/SIGKILL 后 omp/ternlight 子进程自动清理（PDEATHSIG + 进程组）

## 架构

```mermaid
graph LR
    A[微信] -->|扫码登录/消息| B[bot.py<br/>wechatbot-sdk]
    B -->|prompt/回复| C[omp_rpc.py<br/>JSONL over stdio]
    C -->|spawn 子进程| D[omp --mode rpc × N<br/>每用户每会话一个]
    D -->|agent 事件流| C
    B -->|最终文本| A
```

`omp_rpc.py` 是 `omp --mode rpc` 协议的最小实现：`ready` 帧握手 → `prompt` 命令 → 订阅
`agent_start` / `message_update`(text_delta) / `agent_end` 事件 → 聚合文本返回。
会话布局：`~/.wechat-omp-bot/sessions/<user>/`（默认会话）+ `<user>/<name>/`（命名任务会话），
每个会话独立 omp 进程（进程级隔离）。

## 系统要求

| 平台 | 支持 | 说明 |
|---|---|---|
| **Linux（含 WSL2）** | ✅ 推荐 | 开发与测试环境；退出清理用内核 PDEATHSIG、后台常驻可用 systemd |
| macOS | ⚠️ 可用 | 功能正常；退出清理退化为 stdin 管道关闭兜底（无 PDEATHSIG） |
| Windows | ❌ 不支持 | 子进程 `preexec_fn` 不受支持，建议 WSL2 运行 |

软件要求：Python ≥ 3.9、[omp](https://omp.sh)（已认证）、ffmpeg（可选，媒体处理）、Bun（可选，语义匹配）。
运行时数据都在 `~/.wechat-omp-bot/`（会话/索引/日志），仓库内无状态写入（outbox 已 gitignore）。

## 安装

从零开始的完整部署（含 omp 安装认证、扫码、后台常驻、FAQ）见 [**DEPLOY.md**](DEPLOY.md)。

要求：Python ≥ 3.9、已安装并配置好认证的 [omp](https://omp.sh)（`omp -p "hi"` 能跑通）。

```bash
pip install -r requirements.txt          # 国内可用: -i https://pypi.tuna.tsinghua.edu.cn/simple
python3 bot.py                           # 终端出现二维码，微信扫码
```

媒体处理（发视频/音频后的加速/截取/转格式/拼接）需要 ffmpeg（可选，不装则其它功能不受影响）：

```bash
apt install ffmpeg        # Debian/Ubuntu；macOS: brew install ffmpeg
```

扫码后凭证存于 `~/.wechatbot/credentials.json`，下次运行直接登录。

## 使用

### 命令速查（全部本地命令，零 token）

| 分类 | 命令 | 用法 |
|---|---|---|
| 基础 | `/ping` `/help` | 连通性测试 / 帮助（含自然语言技能清单） |
| 会话 | `/sessions` | 会话列表（任务名 + 描述 + 消息数，→ 当前） |
| 会话 | `/session new <任务名> [描述]` | 新建并切换命名会话 |
| 会话 | `/session switch <名>` · `rm <名>` · `desc <名> <描述>` | 切换 / 删除 / 改描述 |
| 会话 | `/status` | 当前会话模型/消息数/上下文占用/自动压缩 |
| 会话 | `/restart` · `/reload` · `/compact` · `/new` · `/stop` | 重启进程 / 热重载技能 / 压缩上下文 / 清空 / 中止 |
| 模型 | `/model [供应商/模型ID]` | 查看当前模型与已认证供应商，或切换 |
| 记账 | `/usage [today\|yesterday\|YYYY-MM-DD]` | 按日期查询 token 消耗与费用 |
| 记账 | `/stats` | 各项目 token 排名（转接 omp stats） |
| 技能 | `/skills` | omp 技能清单（已加载 + 已安装） |
| 技能 | `/skillhub <关键词>` | 让智能体查 SkillHub 安装指引（走 LLM） |
| 分享 | `/share` | 当前会话网页版只读快照链接（浏览器查看） |
| 分享 | `/collab` | 实时共享说明（omp TUI 功能，含手动步骤） |
| 文件 | `/files` · `/clear_files` · `/outbox` | 已索引文件 / 清空文件库 / 待投递文件 |
| 媒体 | `/video [操作]` | ffmpeg 处理 inbox 视频/音频（加速/截取/转格式/拼接） |
| 组件 | `/install [ocr\|semantic]` | 可选组件状态与安装 |

给机器人发消息：

| 输入 | 行为 |
|---|---|
| `把 README 翻译成英文并写入 docs/` | 转发给 omp 智能体执行 |
| `生成一份周报存成 pdf 发给我` | 智能体把文件写入 `outbox/`，机器人自动通过微信发送 |
| **发文件（txt/word/ppt/pdf）** | 自动解读、切块、建索引，之后可追问文件内容 |
| **发图片（含截图/拍照）** | OCR 识别文字并索引（rapidocr，CPU 本地），可追问图片内容 |
| `/ping` | `pong` |
| `/status` | 当前会话模型、消息数、是否处理中 |
| `/sessions` | 会话列表（任务名 + 描述 + 消息数） |
| `/session new <任务名> [描述]` | 新建并切换到命名会话 |
| `/session switch <名>` / `rm <名>` | 切换 / 删除会话 |
| `/model [供应商/模型ID]` | 查看/切换模型 |
| `/new` | 清空当前会话历史，重新开始 |
| `/stop` | 中止正在执行的任务 |
| `/usage [today\|yesterday\|YYYY-MM-DD]` | 按日期查询 token 消耗（本地，含费用） |
| `/stats` | 各项目 token 消耗排名，转接 `omp stats`（本地） |
| `/files` | 已索引文件列表 |
| `/clear_files` | 清空文件库（本地） |
| `/install` | 可选组件状态与安装（ocr / semantic） |
| `/help` | 所有本地命令汇总 |

所有 `/` 命令均为**本地命令**，不调用 LLM、不消耗 token（回复末尾有标注）；
直接发消息才走 LLM。

### 会话路由（多任务隔离）

每个微信用户可以有多个**命名会话**（任务），互不干扰、各自续传：

```
/session new ppt 帮用户做PPT        # 新建并切换到「ppt」会话
/session new 翻译 处理翻译任务       # 又一个任务
/sessions                          # 列出：任务名 + 描述 + 消息数（→ 当前）
/session switch ppt                # 切回 PPT 任务
/session rm 翻译                   # 删除会话
```

- 会话按任务隔离（实测：A 会话记住的暗号 B 会话不知道），每个会话独立 omp 进程
- 会话名支持中文（目录名安全编码，显示/匹配用 meta.json 里的原始名）
- 每条消息路由到**当前会话**（`~/.wechat-omp-bot/sessions/<user>/current.txt` 持久化，
  机器人重启不丢）；`/status` `/model` `/compact` 等命令作用于当前会话
- 默认 `default` 会话兼容旧数据，路径不变；`/usage` 可按会话统计（`/sessions` 显示每会话消息数）
- 自然语言也能触发："新建会话 ppt" → `/session new ppt`、"会话列表" → `/sessions`

#### 自然语言会话路由（自动切换 + 确认）

不用记命令，消息会**按会话名 + 描述**自动匹配目标会话：

- **强信号**（含"切到/换到/切换到"等动词）→ 直接切换并执行，如"切到 ppt 会话帮我做个封面"
- **弱信号**（提到会话名/描述但无切换动词）→ 先**确认**：
  "检测到会话「ppt」（帮用户做PPT）与你的请求相关。要在其中执行吗？
  回复『确认』；不想切换直接说任务内容。"
  回复"确认"/"在ppt做" → 切换并执行原请求；"不用" → 留在当前会话
- 已在目标会话时不会重复提示；确认等待 10 分钟内有效

例如在"翻译"会话中直接说"帮我做一份PPT"，机器人会询问是否切到「ppt」会话。

### 自然语言技能匹配（模糊 + 轻量语义 RAG）

除了精确的 `/` 命令，自然语言也能触发本地技能，三级匹配（全部本地、零 token）：

1. **子串**：别名命中即触发，如“看看今天的用量”→“/usage”、“清空会话”→“/new”
2. **关键词**：jieba 分词后关键词覆盖率 ≥ 50%，如“这个月花了多少token”→“/usage”
3. **语义**：**ternlight**（7MB WASM 三元量化嵌入模型，CPU 本地运行，无 GPU/无 API）
   cosine 相似度。仅用于非中文消息（ternlight 的 BERT 以英文为中心，中文嵌入
   实测为噪声，中文走子串/关键词层）；`/new`、`/stop` 等破坏性技能需要更高
   相似度（0.6）才会触发，避免误伤

语义引擎实现：`vendor/ternlight/server.mjs`（Bun 子进程，JSONL over stdio，
与 omp RPC 同款模式），Python 侧 `embedder.py` 桥接；Bun 缺失时自动降级为
纯关键词匹配。匹配命中时回复脚注标注“模糊匹配/语义匹配 + 分数”。

### 回复脚注

每条 LLM 回复末尾的分割线下显示：`供应商/模型 | 入/出/缓存/合计 tokens | 费用`。
token 数与费用来自 omp 实时返回（含缓存计价，费用为 USD，可配人民币近似汇率），
不依赖任何价格表。本地命令回复标注“本地命令 · 不消耗 token”。

### 文件解读与轻量 RAG

给机器人直接发文件（**txt / docx / pptx / pdf**）或**图片**（png/jpg，需 OCR 组件），自动完成：

1. **提取**：txt 直接解码；docx/pptx 解析 OpenXML 抽取文本；pdf 提取文本层（`pypdf`）
2. **切块**：段落感知分块（~450 字符/块，≈ ternlight 单次嵌入 128 token 上限内），相邻重叠 64 字符
3. **索引**：英文块用 ternlight 嵌入（384 维）存 SQLite（`~/.wechat-omp-bot/bot_files.db`），中文块存纯文本（中文嵌入实测为噪声）
4. **检索**：混合检索——中文用 jieba 分词词频打分，英文关键词 + ternlight 余弦相似度
5. **回答**：提问时 top-k 相关块注入 omp 会话，基于文件内容回答

索引完成后回复“已索引 xxx：N 字 / M 块”，之后直接问“报告里第三季度营收是多少”即可。
老格式（.doc/.ppt/.xls）与无文字图片会提示无法解读。`/files` 查看、`/clear_files` 清空。

#### 可选组件（按需安装）

以下组件不装也能跑核心功能，未安装时收到对应请求会直接提示，发 `/install` 确认安装：

| 组件 | 功能 | 未安装时的行为 |
|---|---|---|
| OCR（rapidocr_onnxruntime） | 图片文字识别 | 发图片提示"发送 /install ocr 安装" |
| 语义匹配（ternlight + bun） | 英文自然语言技能匹配 | 自动降级关键词匹配，不打断使用 |

`/install` 无参数显示组件状态；`/install ocr`、`/install semantic` 自动安装
（pip 走 `PIP_INDEX_URL`，默认清华源），安装后即时生效、无需重启。
自然语言"安装ocr"也会触发。

#### 上下文连贯

上传文件/图片后，问题处理分两级：具体关键词问题走块检索注入；**检索未命中时自动注入
文件库概览**（文件名 + 上传时间 + 首块，标注"用户上传"），所以“**图片里说了什么**”
“**我发了什么**”“**你想要我干啥**”这类指代问法都能联系到上传的内容回答。
概览同时告知 omp：用户上传的内容来自微信，**不是机器人生成的 outbox 文件**，
避免把两者搞混。

### 媒体处理（视频/音频 → ffmpeg）

发**视频**或**音频文件**（mp4/mov/mp3/wav 等）→ 存入媒体 inbox → 发操作指令：

| 指令示例 | 效果 |
|---|---|
| `加速1.5倍` / `减速` / `放慢两倍` | 变速（视频画面+音频同步，支持中文数字） |
| `截取10-20秒` / `截取前30秒` | 分切片段（精确到秒） |
| `转成mp3` / `转mp4` / `提取音频` | 转格式（mp3/mp4/wav/flac/mov/gif/m4a） |
| `拼接合并` | 按上传时间顺序拼接全部 inbox 文件 |

处理结果自动发回微信（走 outbox 投递）。`/video` 查看 inbox 列表，`/video clear` 清空。
语音消息（微信 silk 私有编码）暂不支持，提示说明。

### 文件投递（outbox）

告诉智能体"生成/导出一个文件给我"，它会按系统提示把文件写入 `outbox/` 下
**当天日期子目录**（`outbox/2026-08-02/xxx.pdf`，YYYY-MM-DD），目录规则同时写有
`outbox/README.md` 供智能体直接阅读。任务结束后机器人自动把新文件通过微信发给你
（图片/视频按扩展名发送为对应类型，其余作为文件），发送后删除文件并清理空日期目录。
超过 `OMP_BOT_MAX_FILE_MB`（默认 20MB）的文件会跳过并保留。
`/outbox` 可本地查看待投递文件（自然语言"outbox里有什么"也能触发）。

## 配置（环境变量）

| 变量 | 默认 | 说明 |
|---|---|---|
| `OMP_CWD` | 项目目录 | omp 智能体工作目录 |
| `OMP_BOT_DATA` | `~/.wechat-omp-bot` | 每用户会话目录根 |
| `OMP_BIN` | `omp` | omp 可执行文件 |
| `OMP_BOT_TIMEOUT` | `600` | 单次 prompt 超时（秒），超时先回部分内容 |
| `OMP_BOT_MAX_REPLY` | `2000` | 微信单条回复最大字符数，超出截断 |
| `OMP_BOT_MAX_FILE_MB` | `20` | outbox 单文件大小上限（MB），超出跳过 |
| `OMP_BOT_CNY_RATE` | `7.2` | 费用的人民币近似汇率（仅显示用；`None` 关闭） |
| `OMP_BOT_LOG` | `INFO` | 日志级别（DEBUG/INFO/WARNING/ERROR） |

安全提示：消息会以 `--auto-approve`（yolo）模式驱动 omp，智能体可以读写/执行
`OMP_CWD` 下的任何内容。仅给自己或可信的微信号使用。

## 项目结构

```
bot.py        # 入口：微信登录 + 消息路由 + 指令 + 回复脚注
omp_rpc.py    # omp --mode rpc 最小 JSONL 客户端 + 会话管理器
ledger.py     # token/费用记账（bot_stats.db）+ omp stats.db 合并查询
ingest.py     # 文件解读 + 切块 + 混合检索（bot_files.db）
skills.py     # 本地技能注册表 + 自然语言路由
embedder.py   # ternlight 语义嵌入桥（Bun 子进程）
vendor/ternlight/  # ternlight 嵌入服务（bun install 安装）
requirements.txt
```

机器人自身用量实时写入 `~/.wechat-omp-bot/bot_stats.db`；`/usage`、`/stats` 同时
合并 omp 官方统计 `~/.omp/stats.db`（覆盖你手动使用 omp 的用量）。
上传文件的索引存 `~/.wechat-omp-bot/bot_files.db`。

## 许可证

MIT