<p align="center">
  <img src="assets/ubw-header.svg" width="720" alt="UBW — Universal Brute Workpack" />
</p>

<h2 align="center">Plus 不够用，Pro 又用不完？</h2>
<p align="center">接上自己的模型 API，把 Codex 额度留给核心任务。</p>

<p align="center">
  <a href="#能做什么">功能介绍</a> ·
  <a href="#接入">快速接入</a> ·
  <a href="skills/ubw/SKILL.md">配套 Skill</a> ·
  <a href="https://github.com/haoyun18881-beep/universal-brute-workpack/issues">反馈问题</a>
</p>

<p align="center">
  <a href="https://github.com/haoyun18881-beep/universal-brute-workpack/stargazers"><img src="https://img.shields.io/github/stars/haoyun18881-beep/universal-brute-workpack?style=flat&amp;color=86ad94" alt="GitHub Stars" /></a>
  <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520.3-567c65?style=flat" alt="Node.js ≥20.3" /></a>
  <a href="skills/ubw/SKILL.md"><img src="https://img.shields.io/badge/Codex-Skill-172321?style=flat" alt="Codex Skill" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-567c65?style=flat" alt="Apache-2.0 License" /></a>
</p>

<p align="center"><b>读文件 · 查资料 · 审代码</b><br />自选模型分担，Codex 复核交付。</p>
<p align="center">如果用得上，欢迎点个 Star ⭐</p>

---
UBW 是一个 MCP 服务。Codex 分配任务、限定目录，用户自主配置的大模型通过 API 只负责调用只读工具，返回报告与证据。联网搜索通过配置的搜索服务完成。

Plus 额度不够用，又用不完 Pro？UBW 支持接入自选模型 API，分担读取、搜索和代码审查等任务，让原本交给 Codex 子 Agent 的只读工作走自定义模型的 API 计费。Codex 负责判断、修改和交付，把订阅额度留给核心任务。

更多用法，欢迎探索，也欢迎提交 Issue 或 PR。

![通过 UBW 接入自选模型 API，分担读文件、查资料和审代码的工作，把 Codex 订阅额度留给判断、修改和交付。](assets/ubw-api-choice.png)

![UBW 任务分工：将代码审查、文件检索和资料搜索交给外部模型，Codex 额度节省目标 30%，外部 API 按量计费。](assets/ubw-delegation.png)

## 能做什么

- 列目录、找文件、搜索文本、读取文件、查看 Git 差异。
- 搜索公开网页，保留来源链接。
- 查看进度、补充指令、暂停、恢复和取消任务。
- 保存阶段结果；失联或预算耗尽时暂停。

不提供文件写入、Shell 执行或子 Agent 派生。

## 接入

需要 **Node.js ≥ 20.3**、DeepSeek API Key；读取 Git 差异需要 Git。

复制 [配置示例](config/universal-brute-workpack.example.json)，将 `roots` 设为允许读取的项目目录：

```json
{
  "roots": ["D:/projects/example"],
  "search": { "backend": "deepseek" }
}
```

MCP 客户端配置：

```json
{
  "mcpServers": {
    "ubw": {
      "command": "node",
      "args": ["D:/tools/ubw/src/bridge.js"],
      "env": {
        "UBW_CONFIG": "D:/config/ubw.json",
        "DEEPSEEK_API_KEY": "<API_KEY>"
      }
    }
  }
}
```

路径改为实际位置。密钥保存在本机配置或环境变量中，不提交到仓库。

## 配套 Skill

[ubw](skills/ubw/SKILL.md)：任务委派、进度跟进和结果复核。使用时将 skills/ubw 目录放入宿主的 Skill 目录。

## 工具

| 工具 | 用途 |
| --- | --- |
| `delegate.start` | 分配任务，指定目录、预算和联网权限 |
| `delegate.inspect` | 查看进度并续租，可等待状态变化 |
| `delegate.control` | 补充指令、暂停、恢复、取消 |
| `delegate.result` | 获取完整任务的报告或当前阶段结果 |

读取的文件内容会发送到 DeepSeek API。联网任务需设置 `allowNetwork: true`；官方搜索另计 API 用量。

默认租约为 120 秒，需在到期前调用 `delegate.inspect`。任务记录含文件摘录和报告，保存在 `~/.ubw/tasks`；重启后保持暂停。Token 预算用于停止后续请求，不是账户金额上限。

## 开发

```sh
npm test
npm run doctor
```

已通过 Windows / Node.js 26 的本地模拟测试。真实 API 联调尚未完成。

## 许可证

[Apache-2.0](LICENSE)

欢迎按需修改和扩展，也欢迎提交 Issue 或 PR。