# wechat-codex

[![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-Rust%20%E9%87%8D%E5%86%99-orange.svg)](#项目状态)
[![Built for Codex CLI](https://img.shields.io/badge/built%20for-Codex%20CLI-10a37f.svg)](https://developers.openai.com/codex)

**把微信变成你本地 Codex CLI 的手机前端。**

`wechat-codex` 是一个本地桥接器，目标是让你直接通过微信给自己电脑上的 Codex 发任务、看结果、切换上下文，并且把状态、队列和安全边界都稳稳地放在本机。

[English](README.md)

## 这个项目为什么值得做

大多数 AI 编码产品默认你坐在电脑前。

但真实场景不是这样：

- 通勤路上想看一下仓库状态
- 想在手机上先把任务派出去，回到电脑再接管
- 想让 Codex 跑在自己的机器上，而不是在别人的 SaaS 盒子里
- 想要的是一个本地、可检查、可恢复的桥，而不是再套一层网页壳

`wechat-codex` 解决的就是这个问题。

## 它和普通 Demo 的区别

- **微信就是交互界面**：不需要额外装一个 AI 手机 App
- **Codex 本地运行**：你的代码、你的文件、你的环境
- **不是一次性脚本**：按长期驻留 daemon 的标准设计
- **SQLite 是唯一真相源**：任务、状态、确认流、审计都能落盘
- **安全边界明确**：sandbox、确认、审计、状态机都显式建模
- **工程取向很克制**：单二进制、少边界、无聊但稳

## 项目状态

这个仓库现在处于 **Rust 重写期**。

### 现在已经成立的事实

- 旧的 Node/TypeScript 实现已经从仓库移除
- 新的 Rust 代码库已经成为唯一主线
- 目前已经落下的核心部分包括：
  - CLI 骨架
  - SQLite schema 与仓储线程
  - 持久化任务队列模型
  - `/status` 运行态摘要
  - 队列 drain 主链
  - Codex runner 边界
  - `launchctl/systemctl` 服务接管代码
  - `ilink` 扫码绑定与文本消息收发主链
  - `ilink` 图片/语音/文件/视频附件下载、解密和本地落盘主链
  - `/help` `/status` `/model` `/cwd` `/sandbox` `/confirm` 命令流
  - 持久化确认流、allowlist、`PartialSent`
  - maintenance / retention 清理逻辑

### 现在还不能宣称的事情

- 还**不是**生产可用版本
- 非文本附件的真实理解效果还需要实机验证
- 实机 service 安装、长期运行、真实回复链路还需要联调验证
- npm wrapper 已经在仓库里搭出来了，但还没有正式发布到 registry
- 这不是一个“已经上线的成品”，而是一个正在快速成形的本地 agent runtime

如果你现在 star，这更像是在关注一个认真做本地微信 × Codex 运行时的项目，而不是给一个包装过的 Demo 点赞。

## 产品方向

Rust 版被明确当成一个**新项目**来做，不是旧 daemon 的兼容升级。

已经锁定的关键决策：

- 新服务名
- 新默认数据目录
- 不自动导入旧数据
- 单账号、单机、FIFO 串行模型
- SQLite 持久化状态
- 高风险动作有持久化确认流
- 目标服务形态是 `launchd + systemd`

## 架构图

```text
WeChat API
   |
   v
wechat_io -----> queue -----> codex_runner
   |               |              |
   |               v              v
   |----------> state_repo <------|
                   |
                   v
                SQLite

security_audit <--- wechat_io / queue / codex_runner / state_repo
```

## 核心设计原则

- **本地优先**：真正有价值的执行必须发生在你的机器上
- **显式优先于魔法**：挂了也要能解释为什么挂
- **单用户优先**：不为了“以后也许平台化”提前把系统做复杂
- **队列语义优先**：任务入队时就冻结上下文
- **boring tech 优先**：Rust + SQLite + subprocess 已经足够强

## 当前 CLI 形态

Rust 二进制正在收敛到下面这组命令：

```bash
wechat-codex setup
wechat-codex daemon-run
wechat-codex service install
wechat-codex service start
wechat-codex service stop
wechat-codex service restart
wechat-codex service status
wechat-codex logs
wechat-codex status
wechat-codex maintenance
```

当前代码里还加了一个临时 `enqueue-test` 调试命令，用于开发阶段验证队列主链。

## 当前数据模型重点

Rust 重写已经围绕下面这些持久化表展开：

- `jobs`
- `runtime_state`
- `settings`
- `confirmations`
- `audit_events`
- `actors`

最关键的建模思想是：

- `jobs` 是**不可变执行快照**
- `runtime_state` 是**当前运行摘要**

这两类数据不能混着放。

## 开发方式

### 依赖

- Rust stable
- 本机已安装 Codex CLI
- 一个可以做 WeChat 桥接开发的环境

### 编译

```bash
cd rust
cargo build
```

### 格式检查

```bash
cd rust
cargo fmt --check
```

### 测试

```bash
cd rust
env GIT_CONFIG_GLOBAL=/dev/null HTTP_PROXY= HTTPS_PROXY= ALL_PROXY= cargo test
```

## 本地联调

### 1. 先做一次 setup

```bash
cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev setup
```

`setup` 现在默认会直接走 `ilink` 扫码绑定，并把 `bot token`、账号信息和同步游标写入 `config.json`。后续 `daemon-run / service start` 会自动读取，不再需要你每次手工 export 一堆变量。

### 2. 启动 daemon

```bash
cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev daemon-run
```

### 3. 安装成系统服务

```bash
cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev service install
cargo run -- --data-dir /tmp/wechat-codex-rs-dev service start
```

### 4. npm 安装

```bash
npm install -g wechat-codex
wechat-codex doctor
wechat-codex setup
```

这层只是一个很薄的 Node wrapper，真正执行的仍然是 Rust 二进制。正式发布后的安装会在 `postinstall` 阶段从 GitHub Releases 下载当前平台的预编译二进制。

如果你现在操作的是一个还没正式发版的源码仓库，仍然应该优先使用 `cargo run`，或者先手动构建 `rust/Cargo.toml`。

### 5. 可选环境变量覆盖

绝大部分配置都会保存在 `config.json`，环境变量现在主要用于覆盖或高级开关：

```bash
export WECHAT_CODEX_ENABLE_DANGER=1
export WECHAT_CODEX_DAEMON_POLL_INTERVAL_SECS=2
```

### 6. 当前关键环境变量

- `WECHAT_CODEX_ALLOWLIST`
- `WECHAT_CODEX_ILINK_BASE_URL`
- `WECHAT_CODEX_ILINK_BOT_TOKEN`
- `WECHAT_CODEX_ILINK_BOT_ID`
- `WECHAT_CODEX_DAEMON_POLL_INTERVAL_SECS`
- `WECHAT_CODEX_REPLY_CHUNK_CHARS`
- `WECHAT_CODEX_ENABLE_DANGER`
- `WECHAT_CODEX_CONFIRMATION_RETENTION_DAYS`
- `WECHAT_CODEX_JOB_RETENTION_DAYS`
- `WECHAT_CODEX_AUDIT_RETENTION_DAYS`
- `WECHAT_CODEX_INBOUND_RETENTION_DAYS`

### 7. 调试用本地 mock bridge

仓库里仍然保留了本地 `http://` mock server，主要用于开发兜底：

```bash
cd /Users/monkeyin/projects/wechat-codex
python3 scripts/mock_wechat_server.py
```

如果走这条兼容路径，旧变量仍然有效：

- `WECHAT_CODEX_WECHAT_POLL_URL`
- `WECHAT_CODEX_WECHAT_REPLY_URL`
- `WECHAT_CODEX_WECHAT_API_TOKEN`

## 分发

理想中的安装体验是：

```bash
npm install -g wechat-codex
wechat-codex setup
wechat-codex service start
```

现在的正式发布路径是：

- 推送 tag：`vX.Y.Z`
- GitHub Actions 为各平台构建 Rust 二进制
- 将压缩包上传到 GitHub Releases
- 再发布 npm 包，安装时自动下载对应平台二进制

本地源码安装仍然支持，但默认发布面已经改成 `npm install -g wechat-codex`。

## 路线图

- 真实微信协议适配
- service 实机安装和长期运行验收
- 中断恢复和 supervisor 联调
- 更完整的状态/审计查询面
- 一键安装体验
- 面向使用者和贡献者的完整文档

## 这个项目适合谁

如果你符合下面几类，这个项目会很对味：

- 本来就大量使用微信
- 希望 Codex 跑在自己机器上
- 在意可检查、可解释、可恢复的本地状态
- 不喜欢把 AI 工作流全部托管给第三方平台

## 贡献方向

当前最有价值的贡献不是“多做几个花哨功能”，而是：

- 运行时正确性
- 队列与恢复语义
- 安全模型评审
- 服务管理
- 文档和运维体验

如果要参与，建议先读当前设计文档：

- [Rust 重写设计文档](docs/designs/rust-rewrite.md)

## License

[MIT](LICENSE)