This commit is contained in:
JWeBot Contributors
@@ -1,5 +1,237 @@
|
||||
# JWeBot
|
||||
|
||||
[中文](#中文说明) | [English](#english)
|
||||
|
||||
## 中文说明
|
||||
|
||||
JWeBot 是运行于 Linux 的单群微信自动回复系统。它通过本地 OCR
|
||||
观察选定的微信窗口，将消息写入持久化 Edge 账本，调用经过审核的命令插件，
|
||||
并通过带视觉确认的 GUI 发送链路回复。
|
||||
|
||||
当前版本：`alpha 0.6.0.1015`。
|
||||
|
||||
### 运行流程
|
||||
|
||||
```text
|
||||
微信窗口
|
||||
-> 自适应 XDamage 截图
|
||||
-> 本地 OCR 与群指纹校验
|
||||
-> 持久化 Edge 账本
|
||||
-> 已审核的本地插件
|
||||
-> DeepSeek 直接对话
|
||||
-> 可选云端智能体
|
||||
-> 带优先级的 GUI 队列
|
||||
-> 输入草稿、发送与视觉确认
|
||||
```
|
||||
|
||||
运行时绑定一个可见群聊。插件不能选择群聊、操作 GUI、读取环境密钥、
|
||||
打开任意网络连接、执行 shell 命令或直接访问 SQLite。
|
||||
|
||||
### 快速开始
|
||||
|
||||
运行环境：
|
||||
|
||||
- Linux 与 systemd 用户服务；
|
||||
- 已登录的桌面微信，以及 X11/VNC 显示会话 `:1`；
|
||||
- Python 3.9 或更新版本；
|
||||
- `xdotool`、`scrot`、`xclip`、OpenCV、Pillow、NumPy 和 RapidOCR；
|
||||
- Steam 功能所需的本机回环 Mihomo HTTP 代理。
|
||||
|
||||
创建并激活私有配置：
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py init personal --activate
|
||||
```
|
||||
|
||||
编辑 `~/.config/jwebot/profiles/personal/` 下的配置，然后重新激活并验证：
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py activate personal
|
||||
PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh
|
||||
```
|
||||
|
||||
服务读取激活时生成的配置，不直接读取源 profile。激活过程先校验配置，
|
||||
再原子生成以下文件：
|
||||
|
||||
```text
|
||||
~/.config/jwebot/current/generated/
|
||||
runtime.env
|
||||
root.env
|
||||
private-context.json
|
||||
notification.json
|
||||
manifest.json
|
||||
```
|
||||
|
||||
导入、脱敏导出、旧配置迁移、调试归档和 root 部署设置见
|
||||
[配置系统说明](config/README.md)；完整安装步骤见
|
||||
[从零部署指南](docs/runbooks/zero-to-running.md)。
|
||||
|
||||
### 常用命令
|
||||
|
||||
内置命令清单由经过审核的插件描述文件生成：
|
||||
|
||||
```text
|
||||
/功能列表
|
||||
/丢骰子 [NdM]
|
||||
/猜数字 开始 [上限]
|
||||
/石头剪刀布 [开始|加入|出|状态|结算|结束]
|
||||
/记住 内容
|
||||
/人物记忆 显示名
|
||||
/扫码排行
|
||||
/复读榜
|
||||
/查记录 关键词
|
||||
/状态
|
||||
/version
|
||||
/debug
|
||||
/steam [在线|游戏|全部|刷新]
|
||||
/steam时长 游戏名[、玩家名]
|
||||
```
|
||||
|
||||
Steam 时长查询允许省略空格，以兼容 OCR。指定玩家时使用明确的分隔符：
|
||||
|
||||
```text
|
||||
/steam 时长 Dota 2
|
||||
/steam时长Dota2
|
||||
/steam时长Dota2、玩家名
|
||||
/steam时长Dota2人=玩家名
|
||||
```
|
||||
|
||||
Steam 优先使用当前私有 profile 中的人物 SteamID 映射，显示对应的群内名称，
|
||||
并支持群内别名。配置了人物名单时，查询仅覆盖名单内账号；未配置名单时，
|
||||
才在运行时发现配置账号的公开好友列表。游戏名和玩家名支持模糊匹配；
|
||||
全员查询限制并发数，指定玩家只查询该账号的游戏库。所有 Steam 请求必须
|
||||
经过配置的本机回环代理。源码不包含真实 SteamID、人物名称、别名或固定名单。
|
||||
|
||||
### 独立配置
|
||||
|
||||
每个 profile 按插件配置包组织：
|
||||
|
||||
```text
|
||||
manifest.toml
|
||||
components/
|
||||
bot.toml
|
||||
providers.toml
|
||||
runtime.toml
|
||||
debug.toml
|
||||
notification.toml
|
||||
deployment.toml
|
||||
context/
|
||||
people.json
|
||||
secrets/
|
||||
runtime.env
|
||||
overrides/
|
||||
runtime.env
|
||||
root.env
|
||||
```
|
||||
|
||||
真实配置放在 Git 外：目录权限为 `0700`，文件权限为 `0600`。
|
||||
事故、调试、遥测和迁移后的 root 操作资料放在
|
||||
`~/.local/state/jwebot/profiles/<profile>/`。
|
||||
字段和配置流程见 [配置指南](docs/configuration-guide.md)。
|
||||
|
||||
### 插件与 SDK
|
||||
|
||||
公共 SDK 位于 `packages/jwebot-sdk/`，最小示例位于
|
||||
`examples/hello-command/`。插件注册在启动期完成，运行前冻结命令所有权。
|
||||
|
||||
创建插件：
|
||||
|
||||
```sh
|
||||
./tools/create-plugin.py weather-command /weather \
|
||||
--author example \
|
||||
--description "Query approved weather data" \
|
||||
--help-entry "/weather city"
|
||||
```
|
||||
|
||||
校验、打包并签名：
|
||||
|
||||
```sh
|
||||
./tools/validate-plugin.py extensions/friends/weather-command/plugin.toml
|
||||
./tools/package-plugin.py extensions/friends/weather-command --output /tmp/release
|
||||
./tools/sign-release.py /tmp/release/*.release.json \
|
||||
--private-key /protected/path/publisher \
|
||||
--publisher example
|
||||
```
|
||||
|
||||
签名完成后，按 [文档目录](docs/) 中的扩展发布与激活流程安装。
|
||||
|
||||
### 部署
|
||||
|
||||
新机器请按 [从零部署指南](docs/runbooks/zero-to-running.md) 操作。
|
||||
已有安装使用协调部署脚本；切换前会保留旧运行时、用户服务、生成配置、
|
||||
SQLite 状态和 systemd 服务结构：
|
||||
|
||||
```sh
|
||||
sudo ./deploy/scripts/deploy-jwebot-production.sh /path/to/JWeBot jwebot
|
||||
```
|
||||
|
||||
部署必须通过微信窗口就绪、队列清空、Edge 健康、SQLite 完整性和自适应
|
||||
录制服务重启稳定性检查。旧 OCR 服务保留安装，但保持禁用。
|
||||
|
||||
### 仓库结构
|
||||
|
||||
| 路径 | 用途 |
|
||||
|---|---|
|
||||
| `packages/jwebot-config/` | 配置校验、生成、导入导出、激活与旧配置迁移。 |
|
||||
| `packages/jwebot-sdk/` | 权限受限的公共插件接口。 |
|
||||
| `packages/jwebot-kernel/` | 路由、账本、策略、发布校验与 Edge 运行时。 |
|
||||
| `packages/jwebot-extension-host/` | 隔离运行已签名扩展的进程宿主。 |
|
||||
| `packages/jwebot-official-extensions/` | 已审核的命令引擎与生成适配器。 |
|
||||
| `extensions/official/` | 官方 service-profile 适配器。 |
|
||||
| `extensions/jwebot/` | 内置命令插件。 |
|
||||
| `extensions/friends/` | 贡献者插件目录。 |
|
||||
| `config/` | 公开模板与 schema，不存放真实配置。 |
|
||||
| `deploy/` | 初始化、协调部署与 systemd 单元。 |
|
||||
| `docs/` | 架构、SDK、配置与运行指南。 |
|
||||
| `tests/` | 单元、行为一致性、打包、安全与部署契约测试。 |
|
||||
| `tools/` | 校验、打包、签名、激活、隐私扫描与配置工具。 |
|
||||
|
||||
根目录 Python 文件是部署服务使用的兼容入口，实际实现位于 `packages/`。
|
||||
|
||||
### 项目进度
|
||||
|
||||
```text
|
||||
独立配置与私有资料迁移 [####################] 100%
|
||||
插件所有权与 SDK 边界 [####################] 100%
|
||||
Steam 状态与时长查询 [####################] 100%
|
||||
本地单元与行为一致性 [####################] 100%
|
||||
从零部署自动化 [################----] 80%
|
||||
跨发行版 staging 验证 [########------------] 40%
|
||||
```
|
||||
|
||||
进度描述仓库中已完成、可测试的交付内容。实际运行效果仍取决于目标桌面、
|
||||
微信版本、OCR 模型、代理和操作者提供的凭据。
|
||||
|
||||
### 验证与隐私
|
||||
|
||||
运行完整本地检查：
|
||||
|
||||
```sh
|
||||
PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh
|
||||
```
|
||||
|
||||
检查当前文件及全部 Git 对象历史：
|
||||
|
||||
```sh
|
||||
./tools/check-secrets.py
|
||||
./tools/check-secrets.py --history
|
||||
```
|
||||
|
||||
扫描器只报告类别、路径、行号、对象哈希和单向指纹，不输出匹配到的敏感值。
|
||||
不要提交已填写的 profile、生成环境、人物上下文、截图、OCR 历史、调试内容、
|
||||
事故归档、SQLite 文件、发布者私钥、API 密钥、SteamID 或真实主机路径。
|
||||
|
||||
仓库只提供公开模板与 schema。默认配置导出会脱敏；私有导出需要显式指定
|
||||
`--include-private`，导出结果应继续保存在 Git 外。
|
||||
|
||||
### 许可证
|
||||
|
||||
JWeBot 使用 Apache License 2.0，见 [LICENSE](LICENSE)。
|
||||
|
||||
---
|
||||
|
||||
## English
|
||||
|
||||
JWeBot is a single-group WeChat automation runtime for Linux. It observes one
|
||||
selected WeChat window through local OCR, routes messages through a durable
|
||||
Edge ledger, runs reviewed command plugins, and sends replies through a
|
||||
|
||||
Reference in New Issue
Block a user