pi-courier 0.1.11 → 0.1.13

package/README.md

@@ -82,7 +82,7 @@ It walks you through, prompting for each value (defaults in brackets; press Ente
 
 ```
 === pi-courier 首次配置向导 ===
-将生成 ~/.pi/msg-bridge.json(权限 600)
+将生成 ~/.pi/pi-courier.json(权限 600)
 
 Matrix homeserver URL (如 https://matrix.example.com):   ← 输入,如 https://matrix.example.com
 获取 token 方式 [1=用户名密码登录, 2=粘贴已有 token] (1):  ← 1 或 2(Enter 默认 1)
@@ -94,14 +94,14 @@ Matrix homeserver URL (如 https://matrix.example.com):   ← 输入,如 https:/
 启用 E2EE 加密? [y/N]:                                  ← y/n(非加密房间也选 y 无妨)
 pi 工作目录 [默认 /home/you/Projects]:                   ← Enter 或输入其他目录
 
-✅ 配置已写入 ~/.pi/msg-bridge.json
+✅ 配置已写入 ~/.pi/pi-courier.json
    账号: @test3:...
    信任用户: @barry:...
    E2EE: 开启
    工作目录: /home/you/Projects
 ```
 
-The wizard verifies the token and writes `~/.pi/msg-bridge.json`. To skip the wizard, create that file manually — the format is in the [FAQ](#4-faq).
+The wizard verifies the token and writes `~/.pi/pi-courier.json`. To skip the wizard, create that file manually — the format is in the [FAQ](#4-faq).
 
 ### Step 2 — Start it
 
@@ -116,7 +116,7 @@ Startup success looks like:
 ```
 ✅ Matrix connected as @test3:... (2 rooms, E2EE enabled)
 ✅ pi RPC connected (model: deepseek-v4-flash, session: 019f...)
-🚀 msg-bridge standalone ready. Waiting for messages...
+🚀 pi-courier ready. Waiting for messages...
 ```
 
 ### Step 3 — Use it from Matrix
@@ -124,7 +124,7 @@ Startup success looks like:
 **First contact (one-time pairing):**
 
 1. **DM the bot** from your account and send any message
-2. The bot is not yet a trusted user, so the bridge prints a challenge code in its log (`pi-courier logs` or `journalctl --user -u pi-msg-bridge -f`):
+2. The bot is not yet a trusted user, so the bridge prints a challenge code in its log (`pi-courier logs` or `journalctl --user -u pi-courier -f`):
 
 ```
 🔐 Challenge code for @barry: 138949
@@ -230,7 +230,7 @@ A: Since v0.1.1 the bridge passes `--continue` to pi, resuming the most recent s
 **Q: Element (web client) intercepts `/`-prefixed messages?**
 A: Prefix with `//` to send a literal slash (`//compact` sends `/compact`).
 
-**Q: What exactly is in `~/.pi/msg-bridge.json`?**
+**Q: What exactly is in `~/.pi/pi-courier.json`?**
 A: The wizard-generated config. Example:
 
 ```json

package/README.zh-CN.md

@@ -82,7 +82,7 @@ pi-courier setup
 
 ```
 === pi-courier 首次配置向导 ===
-将生成 ~/.pi/msg-bridge.json(权限 600)
+将生成 ~/.pi/pi-courier.json(权限 600)
 
 Matrix homeserver URL (如 https://matrix.example.com):   ← 输入,如 https://matrix.example.com
 获取 token 方式 [1=用户名密码登录, 2=粘贴已有 token] (1):  ← 1 或 2(回车默认 1)
@@ -94,14 +94,14 @@ Matrix homeserver URL (如 https://matrix.example.com):   ← 输入,如 https:/
 启用 E2EE 加密? [y/N]:                                  ← y/n(非加密房间选 y 也没问题)
 pi 工作目录 [默认 /home/你/Projects]:                    ← 回车或输入其他目录
 
-✅ 配置已写入 ~/.pi/msg-bridge.json
+✅ 配置已写入 ~/.pi/pi-courier.json
    账号: @test3:...
    信任用户: @barry:...
    E2EE: 开启
    工作目录: /home/你/Projects
 ```
 
-向导会验证 token 并写入 `~/.pi/msg-bridge.json`。不想用向导的话,手动创建这个文件也行 —— 格式见[常见问题](#4-常见问题)。
+向导会验证 token 并写入 `~/.pi/pi-courier.json`。不想用向导的话,手动创建这个文件也行 —— 格式见[常见问题](#4-常见问题)。
 
 ### 第 2 步 —— 启动
 
@@ -116,7 +116,7 @@ pi-courier enable     # 安装 systemd 服务:开机自启 + 立即启动
 ```
 ✅ Matrix connected as @test3:... (2 rooms, E2EE enabled)
 ✅ pi RPC connected (model: deepseek-v4-flash, session: 019f...)
-🚀 msg-bridge standalone ready. Waiting for messages...
+🚀 pi-courier ready. Waiting for messages...
 ```
 
 ### 第 3 步 —— 在 Matrix 里使用
@@ -124,7 +124,7 @@ pi-courier enable     # 安装 systemd 服务:开机自启 + 立即启动
 **首次接触(一次性配对):**
 
 1. 用你的账号**给 bot 发私聊消息**(随便发什么都行)
-2. 此时你还不是 trusted user,bridge 会在日志里打印验证码(`pi-courier logs` 或 `journalctl --user -u pi-msg-bridge -f`):
+2. 此时你还不是 trusted user,bridge 会在日志里打印验证码(`pi-courier logs` 或 `journalctl --user -u pi-courier -f`):
 
 ```
 🔐 Challenge code for @barry: 138949
@@ -227,7 +227,7 @@ A: 0.1.1 起 bridge 会给 pi 传 `--continue`,按 workdir 恢复最近会话。
 **Q: Element(网页客户端)拦截 `/` 开头的消息?**
 A: 用 `//` 转义发送字面文本(如 `//compact` 会发出 `/compact`)。
 
-**Q: `~/.pi/msg-bridge.json` 里到底有什么?**
+**Q: `~/.pi/pi-courier.json` 里到底有什么?**
 A: 向导生成的配置,示例:
 
 ```json

package/deploy/docker/Dockerfile

@@ -0,0 +1,72 @@
+# pi-courier — Matrix → pi 桥接服务
+#
+# 构建: docker compose build(只构建,不运行)
+# 运行: docker compose up -d(见 docker-compose.yml 与 README.md)
+#
+# 说明:
+#  - 基于 node:24-slim(避开 Node 20 与 pi 的 undici 不兼容问题;glibc 标准
+#    环境保证 agent 的 bash 工具与宿主行为一致)
+#  - 多阶段构建:builder 层装依赖后丢弃(npm 缓存/构建垃圾不进最终镜像),
+#    runtime 只带 node_modules + 运行时工具 → 体积约省 200-300MB
+#  - defaults/ 预置 LLM 三件套模板(entrypoint 首次启动自动拷贝到 /root/.pi/agent)
+#  - 构建期间 npm 会从 GitHub Releases 下载 E2EE 原生库(约 21MB),
+#    网络受限时用 --build-arg HTTPS_PROXY/HTTP_PROXY 传代理
+
+# ============================== builder ======================================
+FROM node:24-slim AS builder
+
+ARG HTTPS_PROXY=
+ARG HTTP_PROXY=
+ENV https_proxy=${HTTPS_PROXY} \
+    http_proxy=${HTTP_PROXY}
+
+# 仅需要 ca-certificates(npm install 走 https;git 由 runtime 层负责)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安装 pi 与 pi-courier(pi 先装,pi-courier 的 peer 依赖即满足);
+# 安装后清 npm 缓存(此层最终不会进入 runtime 镜像)
+RUN npm install -g @earendil-works/pi-coding-agent pi-courier \
+    && npm cache clean --force
+
+# ============================== runtime ======================================
+FROM node:24-slim
+
+ARG HTTPS_PROXY=
+ARG HTTP_PROXY=
+ENV https_proxy=${HTTPS_PROXY} \
+    http_proxy=${HTTP_PROXY}
+
+# 系统依赖:
+#  - git:pi 的 bash 工具 / `pi install` 需要(slim 基础镜像没有)
+#  - ca-certificates:HTTPS 证书
+#  - curl:排查网络问题用(可选)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 只带 node_modules,然后在 runtime 重建 bin 符号链接
+# (docker COPY 会把符号链接解引用成普通文件,导致相对 import 解析错误,
+#  所以不能直接 COPY /usr/local/bin/pi)
+COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -s /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js /usr/local/bin/pi \
+    && ln -s /usr/local/lib/node_modules/pi-courier/dist/cli.js /usr/local/bin/pi-courier
+
+# 验证安装(失败则构建失败)
+RUN pi --version \
+    && pi-courier help >/dev/null 2>&1 \
+    && echo "OK: node $(node --version), pi + pi-courier installed"
+
+# 默认配置模板 + 首次启动初始化脚本
+COPY defaults/ /opt/pi-courier/defaults/
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# 进程存活检查:pid 1 即 entrypoint exec 的 pi-courier run 主进程(kill -0 无需额外工具)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD kill -0 1 || exit 1
+
+# entrypoint:首次启动把模板拷进 /root/.pi/agent;随后前台运行主进程
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["pi-courier", "run"]

package/deploy/docker/README.md

@@ -0,0 +1,114 @@
+# pi-courier Docker 部署说明
+
+在 VPS 上用 Docker 部署 pi-courier(Matrix → pi 桥接服务)。
+
+## 目录结构
+
+```
+deploy/docker/
+├── Dockerfile            # 镜像构建(装 pi + pi-courier + 默认配置模板)
+├── docker-compose.yml    # 编排(数据卷 ./data ↔ 容器 /root/.pi)
+├── entrypoint.sh         # 首次启动:自动把默认配置模板拷入数据目录
+├── defaults/             # 模板源(构建进镜像 /opt/pi-courier/defaults/)
+│   └── agent/
+│       ├── models.json   # 完整模型数据(24 模型,开箱即用)
+│       ├── auth.json     # API key 占位(唯一需要你填的文件)
+│       └── settings.json # 默认 provider + 模型
+└── data/                 # 运行时数据(自动创建;含 key/token,已 gitignore)
+    └── agent/            # 首次启动自动从模板填充
+```
+
+## 部署步骤
+
+### 1. 准备
+
+```bash
+# VPS 上安装 Docker + Compose 插件(若未安装)
+# Debian/Ubuntu:
+curl -fsSL https://get.docker.com | sh
+sudo apt-get install -y docker-compose-plugin
+```
+
+```bash
+# 获取项目文件
+git clone https://github.com/Hi-Barry/pi-courier.git && cd pi-courier/deploy/docker
+```
+
+### 2. 构建(只构建,不运行)
+
+```bash
+# 如果 VPS 需要代理访问外网(GitHub 下载 21MB E2EE 库),先导出:
+# export HTTPS_PROXY=http://<host>:<port>
+# export HTTP_PROXY=http://<host>:<port>
+
+docker compose build
+```
+
+### 3. 配置(只需填 API key)
+
+首次启动会自动把模板拷入 `./data/agent/`。先启动一次容器完成初始化,再填 key:
+
+```bash
+docker compose up -d        # 启动(entrypoint 自动初始化 ./data/agent/)
+docker exec pi-courier ls /root/.pi/agent   # 确认模板已拷入
+```
+
+然后编辑宿主 `./data/agent/auth.json`,把占位的 `sk-你的key` 换成真实 API key:
+
+```bash
+# data/agent/auth.json
+{ "opencode-go": { "type": "api_key", "key": "sk-真实key" } }
+```
+
+> 默认 provider 是 `opencode-go` / `deepseek-v4-flash`(settings.json)。用其他 provider 的话,改 settings.json 并确认 models.json 里有对应模型。
+
+### 4. Matrix 配置(向导)
+
+```bash
+docker exec -it pi-courier pi-courier setup
+```
+
+按提示输入:homeserver → token(密码登录或粘贴)→ 信任用户 → E2EE → workdir。写入容器内 `/root/.pi/pi-courier.json`(宿主 `./data/pi-courier.json`)。
+
+```bash
+docker compose restart      # 让 Matrix 配置生效
+docker logs pi-courier      # 应看到 ✅ Matrix connected + ✅ pi RPC connected (model: deepseek-v4-flash)
+```
+
+### 5. 使用
+
+- 给 bot 发消息 → 查看验证码: `docker logs pi-courier` → 回复验证码配对
+- 查看日志: `docker logs -f pi-courier`(或 `docker exec pi-courier pi-courier logs --level debug`)
+- 重启: `docker compose restart`
+- 停止: `docker compose down`(数据保留在 ./data)
+
+### 6. 升级
+
+```bash
+# 方式 A:容器内自更新(npm 全局方式)
+docker exec pi-courier pi-courier update
+
+# 方式 B:重建镜像
+git pull && docker compose build && docker compose up -d
+```
+
+### 7. 映射宿主机项目目录(可选)
+
+让 pi 在容器里直接操作宿主机上的代码:
+
+1. compose 里取消注释 `- ./projects:/root/Projects`
+2. 配置 `workdir` 指向容器内路径(`docker exec -it pi-courier pi-courier setup` 的 workdir 填 `/root/Projects/<你的项目>`)
+3. 宿主机代码放 `./projects/<你的项目>`
+
+## 常见问题
+
+| 问题 | 解决 |
+|---|---|
+| 构建很慢 / 卡在下载 | 构建期网络问题,设 `export HTTPS_PROXY` 再 build |
+| 启动显示 `model: unknown` | `./data/agent/auth.json` 没填 key,或 settings.json 的模型不在 models.json |
+| 发消息没有回复 | 按顺序查:`docker logs` 看 Matrix 连接、pi RPC 连接、模型是否 unknown |
+| `M_BAD_JSON: device_id does not match` | 重登录过,删 `./data/msg-bridge-matrix-crypto` 重启 |
+| 加密房间解不开新消息 | bot 无交叉签名,改用非加密房间 |
+| 会话重启丢失 | 0.1.1+ 自动 `--continue`,确认 `./data` 卷没被删 |
+| 想用新配置 | 改 `./data/pi-courier.json` → `docker compose restart` |
+| workdir 文件丢失(容器重建后) | 未映射 projects 卷;取消注释 `- ./projects:/root/Projects` |

package/deploy/docker/data/.gitignore

@@ -0,0 +1,4 @@
+# 运行时数据目录(容器 /root/.pi 的宿主挂载点)
+# 包含用户的 API key / token,禁止提交进 git
+*
+!.gitignore

package/deploy/docker/defaults/agent/auth.json

@@ -0,0 +1 @@
+{ "opencode-go": { "type": "api_key", "key": "sk-你的key" } }