baxian 2.0.11 → 2.0.12

package/README.md

@@ -20,33 +20,33 @@
 
 ## Why baxian
 
-baxian pairs every **Dev agent** with an independent **QA agent**: the Dev implements and opens a pull request, the QA reviews it with fresh eyes, and the loop of findings and fixes runs automatically until the change is approved.
+Coding agents are fast; the bottleneck is checking their work. baxian pairs every **Dev agent** with an independent **QA agent**: the Dev implements and opens a pull request, the QA reviews it with fresh eyes, and findings and fixes go back and forth automatically until the change is approved. You step in for the sign-offs: approving the plan when you've required that, and confirming the final result.
 
-baxian is **tmux-native**. An agent is just an interactive Claude Code or Codex session inside a tmux session — the terminal you see in the browser is the real pane, the same one you can `tmux attach` to from a shell. Close the browser and the fleet keeps working.
+An agent is an interactive CLI — **Claude Code, Codex, OpenCode, or Qoder CLI** — running inside a tmux session. The terminal you see in the browser is that same session: `baxian attach <agent-id>` (or `tmux attach -t '=<agent-id>'` on the agent's machine) drops you into it, and closing the browser stops nothing.
 
 ## Features
 
-- **Terminal wall** — the dashboard embeds every agent's live terminal (streamed over WebSocket, rendered with xterm.js). Click a pane to type into the real session; no context switching to find out what an agent is doing.
-- **Automated review loop** — QA publishes findings on the pull request, Dev resolves each with a fix and commit or a concrete rejection rationale, and QA rechecks until the verdict is `approve`.
-- **Reviews happen on real pull requests** — branch-per-task, automatic GitHub PR creation, and review polling through `gh` (install and authenticate it separately); with `merge: "auto"`, baxian merges the PR itself once you confirm the approved task.
-- **Human spec gate (optional)** — with `specApproval: "human"` on a project, a task that starts with a spec parks at `spec-ready` once QA approves the spec, and coding waits for your sign-off.
+- **Terminal wall** — the dashboard shows every agent's live terminal. Click a pane to type into the real session; what every agent is doing is always one glance away.
+- **Automated review loop** — QA posts findings on the pull request, Dev fixes each one or rejects it with a reason, QA re-checks — until the verdict is approve.
+- **Real pull requests** — each task gets its own branch and PR on your Git platform (GitHub built-in; other platforms via plugins), so reviews live where your team already works. With `merge: "auto"`, baxian merges the approved PR once you confirm.
+- **Plan approval (optional)** — a task can start with a written plan instead of code. QA reviews the plan the same way, and with `specApproval: "human"` coding waits for your sign-off.
 - **Local & remote agents** — run agents on any machine reachable over SSH; baxian manages the remote tmux sessions for you.
-- **No API keys** — agents run the interactive Claude Code / Codex CLIs, so your existing subscriptions are the only credentials involved.
+- **Model credentials stay in your CLIs** — baxian stores no model keys and configures none of its own; each agent uses whatever auth its CLI already has. Repository access (git plus your platform's CLI — `gh` for GitHub) is a separate prerequisite — see Requirements.
 - **Quality of life** — bilingual UI (English / 简体中文), browser notifications when tasks finish, image upload straight into an agent's terminal, and optional pixel-art agent pets.
 
 ## The workflow
 
-1. **Create a task** in the web console (or from the command line with `baxian task create`).
-2. A **Dev agent** takes it: branch, implementation, tests, pull request.
-3. A **QA agent** reviews the diff independently and submits findings.
-4. The Dev agent answers every finding — fixing or rejecting with a rationale — and pushes.
-5. Repeat until **approve**. You confirm the result, and the PR gets merged — by baxian itself if the project sets `merge: "auto"`, otherwise by hand.
+1. **Create a task** in the web console (or with `baxian task create`).
+2. A **Dev agent** picks it up: branch, implementation, tests, pull request.
+3. A **QA agent** reviews the diff independently and posts findings.
+4. The Dev agent answers every finding — a fix and a commit, or a reasoned rejection — and pushes.
+5. Repeat until **approve**. You confirm the result, and the PR is merged — by baxian if the project sets `merge: "auto"`, otherwise by hand.
 
 <p align="center">
 <img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/screenshots/task-detail.webp" alt="Task detail — status, PR, and the full review record" width="820">
 </p>
 
-Every round is recorded and browsable — the QA review with its findings, and the Dev responses with their commits.
+Every round is recorded and browsable — QA's findings and Dev's responses, each with its commits.
 
 ## How it works
 
@@ -63,16 +63,17 @@ Every round is recorded and browsable — the QA review with its findings, and t
    dev-1 · qa-1      dev-2 · qa-2
 ```
 
-The server owns task and agent-binding state, drives agents through their tmux panes, and follows review feedback through the platform pull request.
+The server keeps task state, drives each agent by typing into its tmux pane, and follows review activity on the pull request of your Git platform.
 
 ## Requirements
 
 > - **Node.js ≥ 22.13**
 > - **tmux** on every machine that runs agents (local and remote)
-> - **Claude Code** (`claude`) and/or **Codex** (`codex`) CLI installed and logged in
-> - **git** with repository read/write credentials, and an authenticated **GitHub CLI** (`gh`). For private HTTPS repositories, run `gh auth setup-git` on every agent host.
+> - The CLI of every runtime your agents use, installed and working on each machine that runs such an agent — signed in where its provider requires that: **Claude Code** (`claude`), **Codex** (`codex`), **OpenCode** (`opencode`), **Qoder CLI** (`qodercli`). One host running several runtimes needs each of their CLIs.
+> - **git** access to your repository on every agent machine — push access for Dev agents; read is enough for QA. For private HTTPS repositories on GitHub, run `gh auth setup-git` on every agent host.
+> - For projects on the built-in GitHub driver: an authenticated **GitHub CLI** (`gh`) on every agent machine (Dev opens PRs, QA posts reviews) and on the server, where it needs write access to the repository (it polls reviews, merges and closes PRs). Projects on a plugin platform follow that plugin's CLI and auth requirements instead.
 >
-> The CLI must be authenticated on every machine that runs agents, and on the server itself: the server calls it to poll reviews, merge, and close PRs, while agents call it to open PRs and post comments.
+> `baxian check <project>` checks tmux, the CLI binaries, git access, and platform CLI auth (`gh` for GitHub) for every agent. Static checks can't see everything — confirm yourself that each agent CLI starts and works with its configured model, that QA's platform credentials may write PR reviews, and that Dev's git credential can actually push (a read-only deploy key still passes the read probe).
 
 ## Quick start
 
@@ -85,9 +86,9 @@ Open <http://localhost:3000>. The first run creates `~/.baxian/baxian.json` for
 
 Then, in the console:
 
-1. **New project** — point it at a git repository.
-2. **Add agents** — an Agent Team (for example Claude Code as Dev, Codex as QA), each with a working directory containing a clone of the repo.
-3. **New task** — describe what you want; the Dev agent picks it up and the review loop takes over.
+1. **New project** — point it at a repository on GitHub, or on any platform added by an installed plugin.
+2. **Add agents** — an Agent Team (for example Claude Code as Dev, Codex as QA), each with a working directory that holds a clone of the repo.
+3. **New task** — describe what you want; the Dev agent takes it from there.
 
 ### CLI
 
@@ -97,13 +98,18 @@ baxian --home <dir>       # use a separate instance home (or set BAXIAN_HOME)
 baxian status             # status of all agents
 baxian attach <agent-id>  # attach to an agent's tmux session, local or remote
 baxian stop <agent-id>    # interrupt an agent
+baxian check <project>    # preflight a project's agents (--fix installs missing tmux)
 baxian task create -p <project> -t "title" -a <dev-id> [-d "description"]
 baxian task list -p <project>
+baxian task cancel <task-id>
+baxian plugin install <pkg> [--registry <url>]  # download a platform plugin package (e.g. an internal Git platform); restart to activate
+baxian plugin status          # installed platform plugins and whether they load
+baxian plugin uninstall <pkg> # remove a platform plugin; repositories only it recognized stop validating
 ```
 
 ## Configuration
 
-baxian reads `<home>/baxian.json`, where `<home>` defaults to `~/.baxian`. Override the instance home with `baxian --home <dir>` or `BAXIAN_HOME`; the CLI option takes precedence. The working directory is never searched for configuration. A minimal configuration:
+baxian reads exactly one file: `<home>/baxian.json`, where `<home>` defaults to `~/.baxian` (override with `baxian --home <dir>` or `BAXIAN_HOME`; the CLI option wins). A minimal configuration:
 
 ```json
 {
@@ -128,17 +134,17 @@ baxian reads `<home>/baxian.json`, where `<home>` defaults to `~/.baxian`. Overr
 }
 ```
 
-Each inner array in `agent` is one Agent Team — a Dev agent and a QA agent that work the repo together. `host` is only needed for remote agents. See [`baxian.json.example`](https://github.com/baxian-ai/baxian/blob/main/baxian.json.example) for a fuller example including remote agents. Everything is also editable from the web console (projects, agents, hosts, language, notifications) — the UI tells you when a change needs a server restart.
+Each inner array in `agent` is one Agent Team — a Dev and a QA that work the repo together. `runtime` accepts `claude-code`, `codex`, `opencode`, or `qodercli`; `host` is only needed for remote agents. See [`baxian.json.example`](https://github.com/baxian-ai/baxian/blob/main/baxian.json.example) for a fuller example including remote agents. Projects, agents, and hosts can also be managed from the web console (along with UI language and notifications), and it tells you when a change needs a server restart; the remaining options are edited in the file.
 
 Useful options:
 
 | Key | What it does |
 | --- | --- |
 | `language` | UI language, `en-US` (default) or `zh-CN` |
-| `review.rounds` | Cap on review rounds before a task is parked as `max_rounds` |
+| `review.rounds` | Review-round cap; when a change would still need another round past it, the task pauses as `max_rounds` |
 | `server.token` | Bearer token protecting the API and web console |
-| `project[].merge` | `"auto"`: baxian merges the PR itself once you confirm the approved task; `null`: merge by hand |
-| `project[].specApproval` | `"human"`: after QA approves a spec, park at `spec-ready` for your sign-off; `null` (default): QA approval moves straight to coding |
+| `project[].merge` | `"auto"`: baxian merges the approved PR once you confirm; `null`: merge by hand |
+| `project[].specApproval` | `"human"`: a plan needs your approval before coding starts (the web console preselects this); `null` or omitted in the file: coding starts as soon as QA approves the plan |
 | `project[].agent[][].mode` + `host` | `local`, or `remote` with a host id for SSH-managed agents |
 
 ## License

package/README.zh-CN.md

@@ -20,33 +20,33 @@
 
 ## 为什么是 baxian
 
-baxian 给每个 **Dev agent** 配一个独立的 **QA agent**：Dev 实现并提交 pull request，QA 以旁观者视角评审，「评审意见 → 修复」的循环自动推进，直到改动被通过。
+AI 写代码很快，瓶颈在于检查它写得对不对。baxian 给每个 **Dev agent** 配一个独立的 **QA agent**：Dev 实现并提交 pull request，QA 以旁观者视角评审，「评审意见 → 修复」自动往返，直到改动通过。需要你出手的是签字环节：启用方案确认时批准方案，最后确认结果。
 
-baxian 是 **tmux 原生**的。一个 agent 就是 tmux session 里的一个交互式 Claude Code 或 Codex 会话——浏览器里看到的终端就是真实的 pane，随时可以在 shell 里 `tmux attach` 进同一个会话。关掉浏览器，舰队照常干活。
+agent 本体是一个交互式 CLI——**Claude Code、Codex、OpenCode 或 Qoder CLI**——跑在 tmux 会话里。浏览器里看到的终端就是那个真实会话：用 `baxian attach <agent-id>`（或在 agent 所在机器上 `tmux attach -t '=<agent-id>'`）就能进到同一个会话；关掉浏览器，agent 照常干活。
 
 ## 功能特性
 
-- **终端墙** —— 控制台内嵌每个 agent 的实时终端（WebSocket 推流、xterm.js 渲染）。点击任意窗格即可向真实会话输入，无需切换窗口就能看清每个 agent 在做什么。
-- **自动评审循环** —— QA 在 pull request 上发布评审意见，Dev 逐条修复并给出提交，或说明拒绝理由，再由 QA 复审，循环直到结论为 `approve`。
-- **评审发生在真实的 PR 上** —— 每任务一个分支、自动创建 GitHub PR，并通过 `gh`（需另行安装并认证）轮询评审动态；项目设置 `merge: "auto"` 时，任务通过并经你确认后由 baxian 代为合并 PR。
-- **Spec 人审门禁（可选）** —— 项目配置 `specApproval: "human"` 后，走规格稿路线的任务在 QA 通过规格稿时停驻在 `spec-ready`，等你签字确认才开始编码。
+- **终端墙** —— 控制台展示每个 agent 的实时终端，点击任意窗格就能直接输入；每个 agent 在做什么，一眼可见。
+- **自动评审循环** —— QA 在 pull request 上提出评审意见，Dev 逐条修复或说明理由拒绝，QA 复审——循环直到结论为通过。
+- **真实的 pull request** —— 每个任务一个分支、一个 Git 平台上的 PR（内置 GitHub，其他平台走插件），评审就发生在团队日常工作的地方。项目设置 `merge: "auto"` 时，任务通过并经你确认后由 baxian 代为合并。
+- **方案确认（可选）** —— 任务可以先产出方案再动手写码，方案同样经过 QA 评审；配置 `specApproval: "human"` 后，方案要等你批准才开始开发。
 - **本地与远程 agent** —— agent 可以跑在任何 SSH 可达的机器上，远端 tmux 会话由 baxian 代管。
-- **不需要 API key** —— agent 运行的是交互式 Claude Code / Codex CLI，凭证只有你已有的订阅账号。
+- **模型凭证不经 baxian** —— baxian 不保存、也不重复配置任何模型凭证；agent 用的就是各 CLI 已有的认证与模型配置。仓库访问（git 与所选平台的 CLI，GitHub 为 `gh`）另有要求，见环境要求。
 - **周边体验** —— 双语界面（English / 简体中文）、任务完成浏览器通知、向 agent 终端直接上传图片，以及可选的像素风 agent 宠物。
 
 ## 工作流
 
-1. 在 Web 控制台**创建任务**（也可以在命令行用 `baxian task create`）。
+1. 在 Web 控制台**创建任务**（也可以用 `baxian task create`）。
 2. **Dev agent** 接手：开分支、实现、测试、提 pull request。
-3. **QA agent** 独立评审 diff，提交评审意见。
-4. Dev agent 逐条回应——修复，或说明理由拒绝——然后推送。
-5. 循环直到 **approve**。你确认结果后 PR 被合并——项目设了 `merge: "auto"` 就由 baxian 代劳，否则手动合并。
+3. **QA agent** 独立评审 diff，提出评审意见。
+4. Dev agent 逐条回应——修复并提交，或说明理由拒绝——然后推送。
+5. 循环直到**通过**。你确认结果后 PR 被合并——项目设了 `merge: "auto"` 就由 baxian 代劳，否则手动合并。
 
 <p align="center">
 <img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/screenshots/task-detail.webp" alt="任务详情——状态、PR 与完整评审记录" width="820">
 </p>
 
-每一轮都有记录、可回看——QA 的评审意见，以及 Dev 带着提交的逐条回应。
+每一轮都有记录、可回看——QA 的评审意见和 Dev 的逐条回应，以及对应的提交。
 
 ## 工作原理
 
@@ -63,16 +63,17 @@ baxian 是 **tmux 原生**的。一个 agent 就是 tmux session 里的一个交
    dev-1 · qa-1      dev-2 · qa-2
 ```
 
-server 持有任务和 agent 绑定状态，通过 tmux pane 驱动 agent，并从平台 PR 跟进评审反馈。
+server 记录任务状态，通过向 tmux pane 输入来驱动 agent，并在所用 Git 平台的 PR 上跟进评审动态。
 
 ## 环境要求
 
 > - **Node.js ≥ 22.13**
 > - 每台跑 agent 的机器（本地与远程）都装有 **tmux**
-> - **Claude Code**（`claude`）和/或 **Codex**（`codex`）CLI 已安装并登录
-> - 已配置仓库读写凭据的 **git**，以及已认证的 **GitHub CLI**（`gh`）。私有 HTTPS 仓库需在每台 agent 主机上执行 `gh auth setup-git`。
+> - 每个 agent 所选 runtime 的 CLI 都已在其所在机器安装、并能正常运行（provider 需要认证的先完成认证）：**Claude Code**（`claude`）、**Codex**（`codex`）、**OpenCode**（`opencode`）、**Qoder CLI**（`qodercli`）；同一台机器跑多种 runtime，就要装齐对应的全部 CLI
+> - 每台 agent 机器都能用 **git** 访问仓库——Dev agent 需要推送权限，QA 只读即可。GitHub 私有 HTTPS 仓库需在每台 agent 主机上执行 `gh auth setup-git`。
+> - 使用内置 GitHub 驱动的项目：每台 agent 机器上已认证的 **GitHub CLI**（`gh`）——Dev 用它开 PR、QA 用它发评审；server 本机的 `gh` 需要仓库写权限（轮询评审、合并与关闭 PR）。使用插件平台的项目改为遵循对应插件的 CLI 与认证要求。
 >
-> 该 CLI 需要在每台跑 agent 的机器上、以及 server 本机都完成认证：server 用它轮询评审、合并与关闭 PR，agent 用它开 PR 与发评论。
+> 运行 `baxian check <project>` 可检查各 agent 的 tmux、CLI 二进制、git 访问与平台 CLI 登录（GitHub 为 `gh`）。静态检查无法覆盖一切，请自行确认：各 agent CLI 能以所配模型正常启动、QA 的平台凭证可发布 PR review、Dev 的 git 凭证确实能 push（只读 deploy key 也能通过读探测）。
 
 ## 快速开始
 
@@ -85,9 +86,9 @@ baxian
 
 然后在控制台里：
 
-1. **新建项目** —— 指向一个 git 仓库。
+1. **新建项目** —— 指向一个 GitHub 仓库，或任何已装插件所支持平台上的仓库。
 2. **添加 agent** —— 一个 Agent Team（例如 Claude Code 当 Dev、Codex 当 QA），各自的工作目录里放一份仓库的 clone。
-3. **新建任务** —— 描述你要做什么；Dev agent 接手后，评审循环自动接管。
+3. **新建任务** —— 描述你要做什么，剩下的交给 Dev agent。
 
 ### CLI
 
@@ -97,13 +98,18 @@ baxian --home <dir>       # 使用独立实例 home（也可设置 BAXIAN_HOME
 baxian status             # 查看所有 agent 状态
 baxian attach <agent-id>  # 接入 agent 的 tmux 会话（本地或远程）
 baxian stop <agent-id>    # 打断一个 agent
+baxian check <project>    # 逐项检查项目内各 agent 的环境（--fix 自动安装缺失的 tmux）
 baxian task create -p <project> -t "标题" -a <dev-id> [-d "描述"]
 baxian task list -p <project>
+baxian task cancel <task-id>
+baxian plugin install <pkg> [--registry <url>]  # 下载平台插件包（如内部 Git 平台），重启 server 生效
+baxian plugin status          # 查看已安装平台插件及其加载状态
+baxian plugin uninstall <pkg> # 卸载平台插件；仅它识别的仓库地址将不再通过校验
 ```
 
 ## 配置
 
-baxian 固定读取 `<home>/baxian.json`，`<home>` 默认为 `~/.baxian`。可通过 `baxian --home <dir>` 或 `BAXIAN_HOME` 覆盖实例 home，CLI 参数优先；工作目录中的配置不会被隐式发现。最小配置：
+baxian 只读取一个配置文件：`<home>/baxian.json`，`<home>` 默认为 `~/.baxian`（可用 `baxian --home <dir>` 或 `BAXIAN_HOME` 覆盖，CLI 参数优先）。最小配置：
 
 ```json
 {
@@ -128,17 +134,17 @@ baxian 固定读取 `<home>/baxian.json`，`<home>` 默认为 `~/.baxian`。可
 }
 ```
 
-`agent` 里的每个内层数组是一个 Agent Team——协作同一仓库的一个 Dev agent 加一个 QA agent；`host` 只在使用远程 agent 时需要。更完整的示例（含远程 agent）见 [`baxian.json.example`](https://github.com/baxian-ai/baxian/blob/main/baxian.json.example)。这些配置也都能在 Web 控制台里修改（项目、agent、主机、语言、通知）——需要重启 server 的改动，界面会明确提示。
+`agent` 里的每个内层数组是一个 Agent Team——协作同一仓库的一个 Dev 加一个 QA。`runtime` 可选 `claude-code`、`codex`、`opencode`、`qodercli`；`host` 只在使用远程 agent 时需要。更完整的示例（含远程 agent）见 [`baxian.json.example`](https://github.com/baxian-ai/baxian/blob/main/baxian.json.example)。项目、agent、主机也可以在 Web 控制台里创建和管理（界面语言与通知同样在控制台设置），需要重启 server 的改动界面会明确提示；其余配置项直接编辑配置文件。
 
 常用配置项：
 
 | 配置项 | 作用 |
 | --- | --- |
 | `language` | 界面语言，`en-US`（默认）或 `zh-CN` |
-| `review.rounds` | 评审轮数上限，超过后任务标记为 `max_rounds` 暂停 |
+| `review.rounds` | 评审轮数上限；最后允许的一轮之后仍需修改时，任务以 `max_rounds` 暂停 |
 | `server.token` | 保护 API 与 Web 控制台的 Bearer token |
-| `project[].merge` | `"auto"`：任务通过并经你确认后，由 baxian 代为合并 PR；`null`：手动合并 |
-| `project[].specApproval` | `"human"`：QA 通过规格稿后停驻 `spec-ready` 等你确认；`null`（默认）：QA 通过即进入编码 |
+| `project[].merge` | `"auto"`：任务通过并经你确认后由 baxian 合并 PR；`null`：手动合并 |
+| `project[].specApproval` | `"human"`：方案需你批准后才开始开发（Web 控制台新建项目时默认选中）；配置文件中省略或填 `null`：QA 通过方案即开始开发 |
 | `project[].agent[][].mode` + `host` | `local` 本地运行，或 `remote` 配主机 id 走 SSH 代管 |
 
 ## 许可证

package/dist/agent/manager.js

@@ -5,8 +5,8 @@ import { join, normalize } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createSignalToken, PASSIVE_VERDICT_WATCH } from './phase-signal.js';
 import { tmuxInstallHint } from './preflight.js';
-import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, TASK_OWNER_ROLES, effectiveTaskReviewRound, isSpecStagePhase, isTaskOpen, repoIdentityKey, taskAttentionGeneration, taskGenerationGuard, taskReviewRound, taskMatchesGeneration, } from '../shared/index.js';
-import { buildProjectDriver, buildProjectPromptContext, makeDriverExec, } from '../platform/driver-host.js';
+import { BRANCH_PREFIX, isValidBranchName, PHASE_EXPECTED_STATUS, PHASE_REQUIRES_AGENT_BOUND_TO_TASK, TASK_TERMINAL_STATUSES as TERMINAL_STATUSES, TASK_ACTIVE_STATUS_SET as ACTIVE_TASK_STATUSES, TASK_OWNER_ROLES, effectiveTaskReviewRound, isSpecStagePhase, isTaskOpen, taskAttentionGeneration, taskGenerationGuard, taskReviewRound, taskMatchesGeneration, } from '../shared/index.js';
+import { buildProjectDriver, buildProjectPromptContext, makeDriverExec, repoIdentityKey, } from '../platform/driver-host.js';
 import { DriverOpError, safeDriverErrorText, validateCommentBody, } from '../platform/types.js';
 import { versionTimeOf } from '../platform/row-schema.js';
 import { checkOpenPrBinding, checkPrBinding } from '../platform/pr-binding.js';