input-kanban 0.0.1 → 0.0.2

package/README.en.md

@@ -0,0 +1,140 @@
+# Input Kanban
+
+[中文](README.md) | English
+
+Input Kanban is a local Codex orchestration dashboard. The recommended path is to install it from npm, run `input-kanban` inside the target repository, and use the browser UI to manage planning, worker execution, and final judging.
+
+## Recommended Usage
+
+### 1. Install
+
+```bash
+npm install -g input-kanban
+```
+
+Verify the installation:
+
+```bash
+input-kanban --help
+```
+
+### 2. Start in the Target Repository
+
+Enter the repository you want Codex to modify or inspect:
+
+```bash
+cd /path/to/your/repo
+input-kanban
+```
+
+By default, this starts a local server at:
+
+```text
+http://127.0.0.1:8787
+```
+
+Open that URL in your browser to use the dashboard.
+
+### 3. Start with an Explicit Repository
+
+If you do not want to `cd` into the target repository first, pass it explicitly:
+
+```bash
+input-kanban --repo /path/to/your/repo
+```
+
+## Common Startup Options
+
+```bash
+input-kanban --port 8787
+input-kanban --host 127.0.0.1
+input-kanban --runs-dir ~/.input-kanban/runs
+input-kanban --codex-bin codex
+input-kanban --open
+```
+
+Defaults:
+
+- target repository: the current directory where `input-kanban` is launched
+- host: `127.0.0.1`
+- port: `8787`
+- runs directory: `~/.input-kanban/runs`
+- Codex command: `codex`
+
+## Using the Dashboard
+
+1. Click `New Run`.
+2. Enter a label, target repository, and task description.
+3. Click `Create Run`.
+4. Click `Plan` to let the Codex planner generate batches and workers.
+5. Click `Dispatch` to run workers by batch barrier and concurrency limits.
+6. Inspect execution logs, final messages, error logs, and artifacts.
+7. After all batches complete, click `Final Judge`.
+8. Stop or archive a run when needed, or manually mark a confirmed failed/unknown worker as completed.
+
+## What It Is For
+
+- Split a larger Codex programming task into multiple workers.
+- Control execution order with batch barriers.
+- Observe each worker's local status, logs, and final response.
+- Run a final judge after all workers complete.
+- Keep local run records for debugging and recovery.
+
+## Runtime Data Location
+
+Runtime data is stored in the configured runs directory. The CLI default is:
+
+```text
+~/.input-kanban/runs
+```
+
+Each run roughly looks like this:
+
+```text
+runs/<runId>/
+├── task.md
+├── plan.json
+├── run_state.json
+├── planner/
+├── workers/<taskId>/
+└── judge/
+    ├── judge_input.json
+    └── verdict.json
+```
+
+These files are local run records and do not need to be committed to your application repository.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Codex CLI installed and configured.
+- The `codex` command works in your terminal, or `--codex-bin` points to the Codex executable.
+
+## Maintainer Development
+
+If you want to develop Input Kanban itself instead of using it as an end user:
+
+```bash
+git clone https://github.com/zhang3xing1/Input-Kanban.git
+cd Input-Kanban
+npm install
+npm start
+```
+
+For local CLI development:
+
+```bash
+npm link
+input-kanban --help
+```
+
+Run checks:
+
+```bash
+npm run check
+```
+
+## More Documentation
+
+- [Project guide](PROJECT_GUIDE.md)
+- [Environment variables](ENVIRONMENT.md)

package/README.md

@@ -1,54 +1,49 @@
 # Input Kanban
 
-Input Kanban is a lightweight local dashboard for splitting a Codex task into batches and workers, running them with `codex exec`, observing status, stopping or archiving runs, and performing a final judge pass.
+中文 | [English](README.en.md)
 
-For implementation details and agent-facing project context, see:
+Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然后在目标代码仓库里运行 `input-kanban`，用浏览器管理任务拆分、并发执行和最终验收。
 
-```text
-PROJECT_GUIDE.md
-```
+## 推荐使用方式
 
-For runtime environment variables, see:
+### 1. 安装
 
-```text
-ENVIRONMENT.md
+```bash
+npm install -g input-kanban
 ```
 
-## Features
+验证安装：
 
-- Static HTML dashboard with no frontend build step.
-- Node.js backend that can:
-  - create multiple runs;
-  - start a `codex exec` planner and materialize `plan.json`;
-  - safely retry planner runs before any worker or judge starts;
-  - detect `plan_empty` when the planner returns zero tasks;
-  - schedule workers by strict batch barriers and `batch.maxParallel`;
-  - generate `judge_input.json` before the final judge pass;
-  - start an independent `codex exec` final judge;
-  - aggregate PID, exit code, events, stderr, last message, artifacts, and Codex session IDs;
-  - stop runs, soft-archive runs, and manually mark failed or unknown workers as completed.
+```bash
+input-kanban --help
+```
 
-## CLI Usage
+### 2. 在目标仓库启动
 
-Run from the target repository directory:
+进入你希望 Codex 修改或检查的代码仓库：
 
 ```bash
+cd /path/to/your/repo
 input-kanban
 ```
 
-Or provide the target repository explicitly:
+默认会启动本地服务：
 
-```bash
-input-kanban --repo /path/to/repo
+```text
+http://127.0.0.1:8787
 ```
 
-Then open:
+打开浏览器访问这个地址即可使用看板。
 
-```text
-http://127.0.0.1:8787
+### 3. 指定目标仓库启动
+
+如果不想先 `cd` 到目标仓库，也可以显式指定：
+
+```bash
+input-kanban --repo /path/to/your/repo
 ```
 
-Common options:
+## 常用启动参数
 
 ```bash
 input-kanban --port 8787
@@ -58,83 +53,42 @@ input-kanban --codex-bin codex
 input-kanban --open
 ```
 
-## Development
-
-```bash
-npm start
-```
-
-For local CLI development:
-
-```bash
-npm link
-input-kanban
-```
+默认值：
 
-## Workflow
-
-1. Click `New Run`, then enter a label, target repo, max parallel value, and task text.
-2. Click `Create Run`.
-3. Click `Plan` to start the planner:
-   - planner uses `codex exec --json --sandbox read-only`;
-   - output is stored under `runs/<runId>/planner/`.
-4. When planning succeeds, `plan.json` is created and the worker list is shown.
-5. Click `Dispatch` to start workers according to batch barriers and `batch.maxParallel`.
-6. The page polls status every 3 seconds.
-7. After all batches complete, click `Final Judge` to run the final judge pass.
-
-The current UI labels are localized, but the project documentation is written in English for easier agent consumption.
-
-## Planner Output Format
-
-The preferred planner response is a JSON object with `batches`. The older `tasks` shape is also supported.
-
-```json
-{
-  "batches": [
-    {
-      "id": "batch-1",
-      "name": "first batch name",
-      "maxParallel": 3,
-      "tasks": [
-        {
-          "id": "T-01",
-          "name": "short name",
-          "prompt": "complete worker prompt",
-          "sandbox": "workspace-write",
-          "expectedArtifacts": ["tmp/example-result.json"]
-        }
-      ]
-    }
-  ],
-  "finalJudgeRequired": true
-}
-```
+- 目标仓库：启动 `input-kanban` 时的当前目录
+- host：`127.0.0.1`
+- port：`8787`
+- runs 目录：`~/.input-kanban/runs`
+- Codex 命令：`codex`
 
-The backend extracts the first JSON object from `last_message.md`. If the planner succeeds but returns zero tasks, the run is marked `plan_empty` and can be planned again before any worker or judge starts.
+## 在看板里如何使用
 
-## Status Sources
+1. 点击 `新建任务批次`。
+2. 输入批次名称、目标仓库和任务说明。
+3. 点击 `创建批次`。
+4. 点击 `拆分任务`，让 Codex planner 生成 batches 和 workers。
+5. 点击 `派发执行`，按 batch barrier 和并发限制运行 workers。
+6. 查看执行日志、最终回复、错误日志和产物。
+7. 所有 batch 完成后，点击 `汇总验收`。
+8. 必要时可以停止或归档 run，也可以手动标记已确认完成的失败/未知 worker。
 
-Worker status is primarily determined from local state:
+## 它适合做什么
 
-- Node child process tracking
-- `exit_code`
-- `events.jsonl`
-- `stderr.log`
-- `last_message.md`
-- expected artifacts
+- 把一个较大的 Codex 编程任务拆成多个 worker。
+- 按批次阻塞关系控制执行顺序。
+- 在本地观察每个 worker 的状态、日志和最终回复。
+- 在所有 worker 完成后，让 final judge 汇总验收。
+- 保留本地运行记录，便于排查和恢复。
 
-Codex App Server is an auxiliary source only:
+## 运行数据保存位置
 
-- the backend starts `codex app-server --stdio`;
-- it calls `thread/list`;
-- it matches sessions using prompt markers:
-  - `ORCHESTRATOR_RUN_ID`
-  - `ORCHESTRATOR_TASK_ID`
+运行数据会保存到 runs 目录。CLI 默认位置是：
 
-A Codex App Server `notLoaded` state does not mean a worker failed. The local process, exit code, logs, and artifacts remain the source of truth.
+```text
+~/.input-kanban/runs
+```
 
-## Runtime Directory
+每个 run 大致结构如下：
 
 ```text
 runs/<runId>/
@@ -148,10 +102,39 @@ runs/<runId>/
     └── verdict.json
 ```
 
-The development `runs/` directory is gitignored. For CLI usage, the default runtime directory is `~/.input-kanban/runs`.
+这些文件是本地运行记录，不需要提交到你的业务仓库。
 
-## Checks
+## 使用前提
+
+- 已安装 Node.js 20 或更高版本。
+- 已安装并配置可用的 Codex CLI。
+- `codex` 命令能在终端中正常运行，或通过 `--codex-bin` 指定 Codex 可执行文件路径。
+
+## 维护者开发
+
+如果你要开发 Input Kanban 本身，而不是作为用户使用：
+
+```bash
+git clone https://github.com/zhang3xing1/Input-Kanban.git
+cd Input-Kanban
+npm install
+npm start
+```
+
+本地 CLI 开发：
+
+```bash
+npm link
+input-kanban --help
+```
+
+检查：
 
 ```bash
 npm run check
 ```
+
+## 更多文档
+
+- [项目实现说明](PROJECT_GUIDE.md)
+- [环境变量](ENVIRONMENT.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-kanban",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "bin": {
     "input-kanban": "bin/input-kanban.js"
@@ -16,6 +16,7 @@
     "src",
     "public",
     "README.md",
+    "README.en.md",
     "PROJECT_GUIDE.md",
     "ENVIRONMENT.md"
   ],

package/public/index.html

@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Codex 编排看板</title>
+  <title>Input 看板</title>
   <style>
     :root { --bg:#0b1220; --panel:#111827; --panel-2:#0f172a; --line:#334155; --line-strong:#64748b; --text:#e2e8f0; --muted:#94a3b8; --blue:#2563eb; --green:#166534; --red:#991b1b; --gray:#475569; --orange:#b45309; }
     body { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 0; background: var(--bg); color: var(--text); }
@@ -82,7 +82,7 @@
   </style>
 </head>
 <body>
-<header><h1>Codex 编排看板</h1></header>
+<header><h1>Input 看板</h1></header>
 <main>
   <div class="sidebar">
     <section>