baxian 1.2.47 → 1.2.49

package/README.md

@@ -1,21 +1,145 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/logo/baxian.png" alt="baxian logo" width="96">
+
 # baxian
 
-AI agent orchestration.
+**Your AI agent team — Dev agents build, QA agents review, every change ships reviewed.**
+
+**English** · [简体中文](https://github.com/baxian-ai/baxian/blob/main/README.zh-CN.md)
+
+[Quick start](#quick-start) · [Features](#features) · [The workflow](#the-workflow) · [How it works](#how-it-works) · [Configuration](#configuration)
+
+[![npm](https://img.shields.io/npm/v/baxian)](https://www.npmjs.com/package/baxian)
+[![CI](https://github.com/baxian-ai/baxian/actions/workflows/test.yml/badge.svg)](https://github.com/baxian-ai/baxian/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/baxian-ai/baxian/blob/main/LICENSE)
+
+<img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/screenshots/dashboard.webp" alt="baxian dashboard — a live terminal wall of Dev and QA agents" width="920">
+
+</div>
+
+## 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.
+
+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.
+
+## 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 findings are structured (`critical` / `major` / `minor`, file and line), Dev responses are per-finding (`fix` / `reject` with rationale and commit), and rounds repeat until the verdict is `approve`.
+- **Reviews happen on real GitHub pull requests** — branch-per-task, automatic PR creation, review polling through the `gh` CLI; with `merge: "auto"`, baxian merges the PR itself once you confirm the approved task.
+- **Built-in server review mode (fallback)** — set `review.mode: "server"` to run the review loop through the server's own protocol when a PR is not an option.
+- **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.
+- **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.
+- **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.
+
+<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.
+
+## How it works
 
-## Install
+```
+   Browser (React + xterm.js)
+        │  REST + WebSocket
+        ▼
+   baxian server (Node + Fastify)
+   task state · review rounds · GitHub poller
+        │  tmux send-keys / capture-pane
+        ├────────────────┐
+        ▼                ▼ SSH
+   local tmux        remote tmux (any host)
+   dev-1 · qa-1      dev-2 · qa-2
+```
+
+The server owns all state (tasks, review rounds, agent bindings) and drives agents by injecting prompts into their tmux panes and watching the output. Agents never talk to each other directly — the server relays review requests and feedback between the Dev and QA sides.
+
+## 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**, and the **GitHub CLI** (`gh`, authenticated) if you use the GitHub integration
+
+## Quick start
 
 ```sh
 npm install -g baxian
+baxian
 ```
 
-## Run
+Open <http://localhost:3000>. The first run creates `~/.baxian/config.json` for you.
+
+Then, in the console:
+
+1. **New project** — point it at a git repository.
+2. **Add agents** — a Dev/QA pair (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.
+
+### CLI
 
 ```sh
-baxian
+baxian                    # start the server (default command)
+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 task create -p <project> -t "title" -a <dev-id> [-d "description"]
+baxian task list -p <project>
+```
+
+## Configuration
+
+baxian reads `./baxian.json` from the working directory first, then falls back to `~/.baxian/config.json` (`baxian start -c <path>` overrides both). A minimal configuration:
+
+```json
+{
+  "review": { "rounds": 10 },
+  "server": { "port": 3000, "host": "127.0.0.1" },
+  "host": [
+    { "id": "worker-01", "hostname": "worker-01.internal", "user": "agent" }
+  ],
+  "project": [
+    {
+      "id": "my-project",
+      "repo": "https://github.com/your-org/your-repo.git",
+      "merge": null,
+      "agent": [
+        [
+          { "id": "dev-1", "runtime": "claude-code", "role": "dev", "mode": "local", "workdir": "/path/to/repo" },
+          { "id": "qa-1",  "runtime": "codex",       "role": "qa",  "mode": "local", "workdir": "/path/to/repo" }
+        ]
+      ]
+    }
+  ]
+}
 ```
 
-First run auto-creates `~/.baxian/config.json`.
+Each inner array in `agent` is one group — a Dev/QA pair that works 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.
+
+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.mode` | `github` (default): reviews on real pull requests; `server`: built-in protocol for PR-less setups; can be set per project |
+| `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[].agent[][].mode` + `host` | `local`, or `remote` with a host id for SSH-managed agents |
 
 ## License
 
-Apache-2.0
+[Apache-2.0](https://github.com/baxian-ai/baxian/blob/main/LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,145 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/logo/baxian.png" alt="baxian logo" width="96">
+
+# baxian
+
+**你的 AI agent 团队——Dev agent 负责实现，QA agent 负责评审，每处改动过审后才交付。**
+
+[English](https://github.com/baxian-ai/baxian/blob/main/README.md) · **简体中文**
+
+[快速开始](#快速开始) · [功能特性](#功能特性) · [工作流](#工作流) · [工作原理](#工作原理) · [配置](#配置)
+
+[![npm](https://img.shields.io/npm/v/baxian)](https://www.npmjs.com/package/baxian)
+[![CI](https://github.com/baxian-ai/baxian/actions/workflows/test.yml/badge.svg)](https://github.com/baxian-ai/baxian/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/baxian-ai/baxian/blob/main/LICENSE)
+
+<img src="https://raw.githubusercontent.com/baxian-ai/baxian/main/assets/screenshots/dashboard.webp" alt="baxian 控制台——Dev 与 QA agent 的实时终端墙" width="920">
+
+</div>
+
+## 为什么是 baxian
+
+baxian 给每个 **Dev agent** 配一个独立的 **QA agent**：Dev 实现并提交 pull request，QA 以旁观者视角评审，「评审意见 → 修复」的循环自动推进，直到改动被通过。
+
+baxian 是 **tmux 原生**的。一个 agent 就是 tmux session 里的一个交互式 Claude Code 或 Codex 会话——浏览器里看到的终端就是真实的 pane，随时可以在 shell 里 `tmux attach` 进同一个会话。关掉浏览器，舰队照常干活。
+
+## 功能特性
+
+- **终端墙** —— 控制台内嵌每个 agent 的实时终端（WebSocket 推流、xterm.js 渲染）。点击任意窗格即可向真实会话输入，无需切换窗口就能看清每个 agent 在做什么。
+- **自动评审循环** —— QA 评审意见结构化（`critical` / `major` / `minor`，附文件与行号），Dev 逐条回应（`fix` / `reject` 并说明理由与提交），一轮轮推进直到结论为 `approve`。
+- **评审发生在真实的 GitHub PR 上** —— 每任务一个分支、自动建 PR、通过 `gh` CLI 轮询评审动态；项目设置 `merge: "auto"` 时，任务通过并经你确认后由 baxian 代为合并 PR。
+- **内置 server 评审模式（备选）** —— 不便走 PR 的场景可设 `review.mode: "server"`，评审循环走 server 自有协议。
+- **Spec 人审门禁（可选）** —— 项目配置 `specApproval: "human"` 后，走规格稿路线的任务在 QA 通过规格稿时停驻在 `spec-ready`，等你签字确认才开始编码。
+- **本地与远程 agent** —— agent 可以跑在任何 SSH 可达的机器上，远端 tmux 会话由 baxian 代管。
+- **不需要 API key** —— agent 运行的是交互式 Claude Code / Codex CLI，凭证只有你已有的订阅账号。
+- **周边体验** —— 双语界面（English / 简体中文）、任务完成浏览器通知、向 agent 终端直接上传图片，以及可选的像素风 agent 宠物。
+
+## 工作流
+
+1. 在 Web 控制台**创建任务**（也可以在命令行用 `baxian task create`）。
+2. **Dev agent** 接手：开分支、实现、测试、提 pull request。
+3. **QA agent** 独立评审 diff，提交评审意见。
+4. Dev agent 逐条回应——修复，或说明理由拒绝——然后推送。
+5. 循环直到 **approve**。你确认结果后 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 带着提交的逐条回应。
+
+## 工作原理
+
+```
+   浏览器（React + xterm.js）
+        │  REST + WebSocket
+        ▼
+   baxian server（Node + Fastify）
+   任务状态 · 评审轮次 · GitHub poller
+        │  tmux send-keys / capture-pane
+        ├────────────────┐
+        ▼                ▼ SSH
+   本地 tmux         远程 tmux（任意主机）
+   dev-1 · qa-1      dev-2 · qa-2
+```
+
+server 持有全部状态（任务、评审轮次、agent 绑定），通过向 tmux pane 注入 prompt、观察输出来驱动 agent。agent 之间从不直接通信——Dev 与 QA 之间的评审请求和反馈都由 server 中转。
+
+## 环境要求
+
+> - **Node.js ≥ 22.13**
+> - 每台跑 agent 的机器（本地与远程）都装有 **tmux**
+> - **Claude Code**（`claude`）和/或 **Codex**（`codex`）CLI 已安装并登录
+> - **git**；若使用 GitHub 集成，还需已认证的 **GitHub CLI**（`gh`）
+
+## 快速开始
+
+```sh
+npm install -g baxian
+baxian
+```
+
+打开 <http://localhost:3000>。首次运行会自动创建 `~/.baxian/config.json`。
+
+然后在控制台里：
+
+1. **新建项目** —— 指向一个 git 仓库。
+2. **添加 agent** —— 一对 Dev/QA（例如 Claude Code 当 Dev、Codex 当 QA），各自的工作目录里放一份仓库的 clone。
+3. **新建任务** —— 描述你要做什么；Dev agent 接手后，评审循环自动接管。
+
+### CLI
+
+```sh
+baxian                    # 启动 server（默认命令）
+baxian status             # 查看所有 agent 状态
+baxian attach <agent-id>  # 接入 agent 的 tmux 会话（本地或远程）
+baxian stop <agent-id>    # 打断一个 agent
+baxian task create -p <project> -t "标题" -a <dev-id> [-d "描述"]
+baxian task list -p <project>
+```
+
+## 配置
+
+baxian 优先读取工作目录下的 `./baxian.json`，找不到时回退到 `~/.baxian/config.json`（`baxian start -c <path>` 可覆盖两者）。最小配置：
+
+```json
+{
+  "review": { "rounds": 10 },
+  "server": { "port": 3000, "host": "127.0.0.1" },
+  "host": [
+    { "id": "worker-01", "hostname": "worker-01.internal", "user": "agent" }
+  ],
+  "project": [
+    {
+      "id": "my-project",
+      "repo": "https://github.com/your-org/your-repo.git",
+      "merge": null,
+      "agent": [
+        [
+          { "id": "dev-1", "runtime": "claude-code", "role": "dev", "mode": "local", "workdir": "/path/to/repo" },
+          { "id": "qa-1",  "runtime": "codex",       "role": "qa",  "mode": "local", "workdir": "/path/to/repo" }
+        ]
+      ]
+    }
+  ]
+}
+```
+
+`agent` 里的每个内层数组是一个分组——协作同一仓库的一对 Dev/QA；`host` 只在使用远程 agent 时需要。更完整的示例（含远程 agent）见 [`baxian.json.example`](https://github.com/baxian-ai/baxian/blob/main/baxian.json.example)。这些配置也都能在 Web 控制台里修改（项目、agent、主机、语言、通知）——需要重启 server 的改动，界面会明确提示。
+
+常用配置项：
+
+| 配置项 | 作用 |
+| --- | --- |
+| `language` | 界面语言，`en-US`（默认）或 `zh-CN` |
+| `review.rounds` | 评审轮数上限，超过后任务标记为 `max_rounds` 暂停 |
+| `review.mode` | `github`（默认）：评审走真实 PR；`server`：无 PR 场景的内置协议；可按项目单独设置 |
+| `server.token` | 保护 API 与 Web 控制台的 Bearer token |
+| `project[].merge` | `"auto"`：任务通过并经你确认后，由 baxian 代为合并 PR；`null`：手动合并 |
+| `project[].specApproval` | `"human"`：QA 通过规格稿后停驻 `spec-ready` 等你确认；`null`（默认）：QA 通过即进入编码 |
+| `project[].agent[][].mode` + `host` | `local` 本地运行，或 `remote` 配主机 id 走 SSH 代管 |
+
+## 许可证
+
+[Apache-2.0](https://github.com/baxian-ai/baxian/blob/main/LICENSE)