WuxianPi Rescue

WuxianPi Rescue 是救援插件、在线文档、版本评论和 Support MCP 的独立服务。首版由一个 Node 22 进程提供维修市场网站、HTTP API、静态插件包、SQLite 评论和 MCP。

本地运行

npm install
npm test
npm start

默认监听 127.0.0.1:20877，评论数据库位于 data/comments.db。生产容器将评论和发布内容分别保存到 /data/comments.db 与 /data/releases。

Related MCP server: Whoosh RAG MCP

发布插件

官方插件源文件位于 plugins/official/<pluginId>。构建时会：

1. 校验 Contract v1 和声明文件；

2. 拒绝符号链接及不安全路径；

3. 生成确定性 ZIP；

4. 计算 SHA-256；

5. 保留 public 中已有的历史版本和 ZIP；

6. 拒绝覆盖内容或 SHA-256 已变化的同版本发布；

7. 按 SemVer 稳定排序并生成 public/catalog.json。

资源包与插件包分开管理。资源使用破坏性升级后的 API V2 和持久化 /data/releases-v2；旧 /api/v1/resources、/resources.json 与 /resources/... 均已退役并返回 410 Gone。当前 wuxianpi.resource-update 4.0.0 只负责 APK 更新后的 Android 私有 service-manager 连接确认，不更新 WuxianPi 或 Termux 运行资源；首次安装仍由 wuxianpi.first-install 独立负责。

插件发布后不可覆盖同一版本。内容有任何变化都必须递增 manifest.json 的 version；完全相同的重复构建可以通过。

维修会话核心插件

wuxianpi.session-bootstrap 与 wuxianpi.session-runtime 是维修助手的两个核心插件。Bootstrap 必须在 APK 本地有 seed 版本，每个新对话只执行一次：读取冻结记忆、刷新市场、统一更新已安装且兼容的官方插件，然后原子切换活动集合。当前对话保持 Bootstrap N；本轮更新的 Bootstrap N+1 只在下一个对话启用。

Runtime 不刷新市场，也不能返回 Bootstrap。插件集合切换完成后，当前对话立即加载最新 Runtime，由它根据用户目的选择业务插件、完成操作、验证实际状态并写回记忆。因此 Runtime 版本 N+1 可以在同一对话生效。

插件 manifest 可声明 sessionRole（bootstrap、runtime 或 business）和 actions。actions 只描述顶部入口的标题、图标、显示条件、依赖和提示词；它们不会携带 shell 命令或新增宿主权限。点击入口创建或恢复普通维修对话，宿主仍执行本地 Bootstrap 后才处理提示词。

所有已安装且兼容的官方插件会在 Bootstrap 中作为一个事务更新：先下载并校验完整差异集合，再一次性切换 active index。任何成员失败时，上一套完整集合继续工作。未安装的业务插件不会被批量安装，Runtime 仅在任务需要时按显式说明安装。

npm run build

HTTP API

GET  /health
GET  /api/v1/plugins?q=
GET  /api/v1/plugins/:id
GET  /api/v1/plugins/:id/versions
GET  /api/v1/plugins/:id/comments?version=
POST /api/v1/plugins/:id/comments
POST /api/v1/comments/:id/replies
GET  /api/v2/resources
GET  /api/v2/resources/:id
GET  /api/v2/resource-sets/:id
GET  /resources-v2/:id/:version/:archive
GET  /plugins/:id/:version.zip
GET  /docs/raw/:id/:version/:path
POST /mcp

通过管理 API 发布插件

维修助手市场的插件发布不需要登录生产服务器。发布者在本地构建并测试后，使用管理 API 上传；服务端会校验 metadata、ZIP 实际大小、SHA-256 和归档内的 manifest.json，然后原子写入持久化 /data/releases。同一版本相同内容重复上传是幂等的，不同内容会返回 409，历史 ZIP 不会被覆盖或删除。

管理 API 只属于维修助手市场，不会同步其它市场：

GET  /api/v1/management/status
PUT  /api/v1/management/plugins/:pluginId/releases/:version
POST /api/v1/management/plugins/:pluginId/promote
PUT  /api/v2/management/resources/:resourceId/releases/:version
POST /api/v2/management/resources/:resourceId/promote
PUT  /api/v2/management/resource-sets/:resourceSetId/releases/:version
POST /api/v2/management/resource-sets/:resourceSetId/promote

生产环境通过 WUXIANPI_RESCUE_MANAGEMENT_TOKEN 启用接口。未配置 token 时写接口禁用；请求必须带 Authorization: Bearer <token>。Nginx 配置默认只允许本机、私网或 Tailscale 地址访问管理路径。

本地发布工具只接受显式的 --market rescue，默认上传后将版本 promote 为 latest；加 --no-promote 可只上传版本：

npm test
npm run build

WUXIANPI_RESCUE_MANAGEMENT_URL=https://wuxianpirescue.webefficacy.com \
WUXIANPI_RESCUE_MANAGEMENT_TOKEN='...' \
scripts/publish-market-via-api.sh \
  --market rescue \
  --plugin wuxianpi.first-install \
  --version 1.0.2

只做本地校验而不发送请求：

scripts/publish-market-via-api.sh --market rescue \
  --plugin wuxianpi.first-install --version 1.0.2 --dry-run

发布接口使用临时文件接收 ZIP，校验成功后才原子移动并更新 catalog。promote 只切换 latestVersion，因此可以在保留历史版本的前提下回滚：

curl -X POST \
  -H "Authorization: Bearer $WUXIANPI_RESCUE_MANAGEMENT_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"version":"1.0.1"}' \
  "$WUXIANPI_RESCUE_MANAGEMENT_URL/api/v1/management/plugins/wuxianpi.first-install/promote"

发布核心资源集合

APK 仓库中的 scripts/generate-resource-set-v2.sh 生成唯一的五资源组合、每个资源的发布 metadata 和 openhouse-core-stack manifest。All-in-One、Native 与市场上传必须使用这些相同字节，不能重新压缩：

cd /root/projects/smallphoneai/openhouseai-app-ai-web
scripts/generate-resource-set-v2.sh --check
jq . distribution/resources-v2/publish-manifest.json

先逐个上传但不 promote，完成测试机 plan/apply/rollback 后再提升资源，最后提升集合：

scripts/publish-resource-via-api.sh --market rescue \
  --resource openhouse-runtime \
  --version '0.1.0+pi.0.80.10' \
  --archive /path/to/runtime-aarch64.tgz \
  --metadata /path/to/metadata.json

scripts/publish-resource-set-via-api.sh --market rescue \
  --manifest /path/to/openhouse-core-stack.json \
  --promote

资源版本不可覆盖。相同版本相同 SHA 重传是幂等成功，不同 SHA 返回 409。单个压缩资源上限为 60 MiB；Nginx 仅对 /api/v2/management/ 放宽到 64 MiB。版本化下载支持 HEAD、Range、ETag 和不可变缓存。

发表评论：

{
  "version": "1.0.0",
  "authorType": "agent",
  "authorName": "WuxianPi Rescue",
  "clientId": "device-local-id",
  "content": "Android 14 环境实测通过",
  "rating": 5,
  "environment": { "android": "14", "termux": "0.118" }
}

MCP 支持 initialize、tools/list 和 tools/call，提供：

• search_plugins

• get_plugin

• read_plugin_document

• get_plugin_comments

Docker 部署

git clone https://github.com/jiwuyou/wuxianpi-rescue.git /opt/wuxianpi-rescue
mkdir -p /var/lib/wuxianpi-rescue
printf 'WUXIANPI_RESCUE_MANAGEMENT_TOKEN=...\n' > /opt/wuxianpi-rescue/deploy/.env
chmod 600 /opt/wuxianpi-rescue/deploy/.env
docker compose --env-file /opt/wuxianpi-rescue/deploy/.env -f /opt/wuxianpi-rescue/deploy/docker-compose.yml up -d --build

Compose 只把服务发布到宿主 127.0.0.1:20877。复制 deploy/nginx-wuxianpi-rescue.conf 到独立 Nginx vhost，申请证书后执行 nginx -t 并 reload。

Compose 启动时会把镜像内的 public/catalog.json 和插件 ZIP 迁移到 /data/releases（只补齐缺失文件，不覆盖已经发布的版本）。之后公共 /catalog.json、插件查询和下载都从该持久化目录读取；升级市场服务自身代码不会丢失已发布内容。deploy/deploy.sh 会显式读取 /opt/wuxianpi-rescue/deploy/.env（也可通过 MARKET_ENV_FILE 覆盖），仅用于升级市场服务代码和容器，不用于发布插件。

备份脚本会短暂停止 Rescue 服务，复制一致的 SQLite 数据库并打包持久化发布目录，然后恢复容器：

install -m 0755 deploy/backup-comments.sh /usr/local/sbin/wuxianpi-rescue-backup
/usr/local/sbin/wuxianpi-rescue-backup

可通过系统定时器或 cron 每日调用，默认保留 30 天；发布目录备份文件为 releases-*.tgz。