# OMP Kanban

**Repository Path**: CZXyee/omp-kanban

## Basic Information

- **Project Name**: OMP Kanban
- **Description**: 使用 OMP Kanban 在 [OMP](https://github.com/can1357/oh-my-pi) 中统一管理任务的创建、评估、运行、审查和归档，用 Markdown + Git 持久化每个阶段的事实。使用多 Session/Subagent 的 lease、fencing 和 run barrier 保障并发。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OMP Kanban

使用 OMP Kanban 在 [OMP](https://github.com/can1357/oh-my-pi)中统一管理任务的创建、评估、运行、审查和归档，用 Markdown + Git 持久化每个阶段的事实。使用多 Session/Subagent 的 lease、fencing 和 run barrier 保障并发。

我们目标是减少任务执行过程中的人工介入，明确 preparation → evaluation → execution → review → archived。例如我们 preparation → evaluation，evaluation 介入提供更多上下文，或干脆让 Agent 从 preparation 执行至 review 直接进行评估。Agent 执行期间，结合自动的时间估计，尽量让任务执行期间不管，卸载心智负担，做到流水线 drain。

![kanban](public/kanban.png)

![卡片编辑](public/卡片编辑.png)



## 立即开始

- Windows x64
- PowerShell
- OMP

克隆仓库后，在仓库根目录启动 OMP：

```powershell
git clone <本仓库地址>
cd Prj-2608-omp-kanban
omp
```

### 1. 一句话安装

在 OMP 中输入：

```text
安装 OMP Kanban。
```

仓库内的 `.agents/skills/omp-kanban-setup` 会让 Agent 执行全局安装脚本并验证结果。安装目标为当前 OMP 用户的 Agent 目录，不复制本仓库的 `.kanban/` 数据。完成后退出并重启 OMP。

### 2. 初始化并打开看板

重启后可在任意项目目录中启动 OMP，并输入：

```text
/kanban init
/kanban
```

现在可以直接创建任务并让 Agent 推进：

```text
创建任务：修复登录超时问题，优先级 high。
```

```text
处理准备区优先级最高的任务：完成评估后自动执行，验证通过后移入审查。
```

默认看板保存在当前项目的 `.kanban/`，任务和配置可以随 Git 提交；临时运行状态不会进入 Git。

### 3. 一句话卸载

需要卸载时，从本仓库根目录启动 OMP 并输入：

```text
卸载 OMP Kanban。
```

Agent 只删除当前 OMP 用户目录中的 `extensions/omp-kanban/` 和 `skills/omp-kanban/`。已有项目的 `.kanban/` 数据保持不变；完成后退出并重启 OMP。

<details>
<summary>手动安装、更新或卸载</summary>

```powershell
./scripts/global-kanban.ps1 -Action install
./scripts/global-kanban.ps1 -Action install -Force
./scripts/global-kanban.ps1 -Action uninstall
```

安装脚本会在仓库缺少 `.omp/bin/kanban-md.exe` 时自动下载并校验固定版本的 `kanban-md`，无需先运行依赖安装命令。

</details>

<details>
<summary>使用自定义看板目录</summary>

在启动 OMP 前设置相对项目根目录或绝对路径：

```powershell
$env:OMP_KANBAN_DIR = ".team-kanban"
omp
```

</details>

## 使用

### 推荐工作方式

把看板作为 Agent 的持久任务队列，而不是要求人手工维护每次状态变化。用户负责创建目标、调整优先级和作出必要决策；其余阶段默认由 Agent 推进：

```text
处理准备区优先级最高的任务：自动完成评估，门禁满足后领取并执行，验证通过后移入评审。
```

```text
审查 #12；满足验收要求则以 completed 归档，否则记录问题并退回评估。
```

Agent 会在一个工作流中完成上下文收集、coding 时间估算、资源声明、claim、Session/Subagent 协调、验证、评审交接和状态回写。只有范围或风险取舍、评审结论、取消任务、失联 worktree 处置等需要真实判断时，才请求人工介入。

### 1. 打开看板

在 OMP 中执行：

```text
/kanban
```

看板不存在时，Extension 会先询问是否初始化；确认后再打开 TUI。以下写法等价：

```text
/kanban tui
/kanban open
```

常用 TUI 操作：

| 按键               | 操作                        |
| ------------------ | --------------------------- |
| 方向键或 `h/j/k/l` | 切换列和选择卡片            |
| `c`                | 创建卡片                    |
| `e`                | 编辑卡片                    |
| `E`                | 使用外部编辑器打开 Markdown |
| `m`                | 选择目标状态                |
| `+` / `-`          | 提高或降低优先级            |
| `s` / `S`          | 切换排序字段 / 顺序         |
| `/`                | 搜索                        |
| `q`                | 退出                        |

TUI 适合创建卡片、调整优先级，以及在 `preparation` 和 `evaluation` 之间整理任务。不要在 TUI 或直接 CLI 中绕过 Agent，把卡片推进执行、评审或处理带 lease 的卡片。

### 2. 创建和整理任务

人工可以在 TUI 中创建卡片，也可以直接告诉 Agent：

```text
创建一张卡片：为领取冲突增加用户可见提示，优先级 high。
```

每张卡片是一份 Markdown 文件，拥有永久稳定的数字 ID。引用任务时使用 `#ID`，不要依赖文件名或路径。

看板固定流程：

```text
preparation → evaluation → execution → review → archived
```

| 状态          | 使用者看到的含义                                           |
| ------------- | ---------------------------------------------------------- |
| `preparation` | 新任务、描述补充、优先级排序                               |
| `evaluation`  | Agent 收集代码上下文、确认范围、识别资源并估算 coding 时间 |
| `execution`   | 已领取并执行，受 lease 和 run barrier 保护                 |
| `review`      | 实现已经交接，等待人工或 Agent 评审                        |
| `archived`    | 任务已结束，不再参与日常调度                               |

归档结果由标签区分：`outcome-completed`、`outcome-abandoned`、`outcome-failed`。

### 3. 让 Agent 评估任务

使用自然语言即可：

```text
评估准备区优先级最高的任务。
```

Agent 在一分钟内只读取需求和少量直接相关文件，主动给出一个粗粒度 Agent coding estimate、置信度和一句依据，不运行测试或提前实现。估时表示从开始编码到结果可进入 `review` 的最可能墙钟时间，不包含等待用户、人工评审和外部依赖。

允许的档位为 `10m`、`20m`、`30m`、`45m`、`1h`、`1.5h`、`2h`、`3h`、`4h`、`1d`。Agent 通过 `evaluate` 将卡片移入 `evaluation` 并把单一 estimate 写入卡片；不输出时间范围。执行中发现任务量级变化时，只有跨越档位才覆盖 estimate。

### 4. 领取并执行

```text
领取并执行卡片 #12；可以独立完成的部分并行处理。
```

执行前，Coordinator 会创建：

- 当前 Session 持有的 lease；
- 单调递增的 `generation` fencing token；
- 本次执行的 `runId`；
- 预期参加本次 run 的主 Session/Subagent 列表；
- 与其他卡片进行冲突检查的资源声明。

同一 run 可以包含多个 Subagent。只有该 run 的所有活跃 Session 都进入终态，run barrier 才会变为 ready。项目中无关 Session 不会阻塞当前任务。

### 5. 检查结果并进入评审

```text
检查 #12 的 run；所有 Session 完成后移入评审，并给出验证证据和剩余风险。
```

只有持有当前 lease 的 Coordinator，且 `cardId`、`runId`、`generation` 和卡片 hash 全部匹配时，才能 finalize。实现成功后通常进入 `review`；执行结果不满足要求时可以退回 `evaluation`。

### 6. 归档

评审通过：

```text
将 #12 以 completed 结果归档。
```

取消任务：

```text
将 #12 以 abandoned 结果归档，并记录原因。
```

不可恢复失败：

```text
将 #12 以 failed 结果归档，并保留失败摘要。
```

### 7. Session 失联后的恢复

过期 lease 不会被普通 `claim` 自动抢占。应让 Agent 先检查旧 Session 和 worktree，再显式恢复：

```text
检查 #12 的旧 Session 和 worktree；确认处置结果后恢复该卡片继续执行。
```

`recover` 必须记录 worktree 处置摘要。新 run 成功建立后，旧 run 才会被 supersede；恢复中途失败会尝试恢复旧 claimant 和 lease。

### 查询和终端使用

OMP 内可直接查询：

```text
/kanban list       # 未归档卡片
/kanban archived    # 已归档卡片，仅查询
/kanban sessions   # Session registry
```

维护清理：

```text
/kanban clean runtime    # 重置临时协调状态和 generation fencing
/kanban clean activity   # 清空 activity.jsonl
/kanban clean all        # 同时执行上述两项；/kanban clean 与此相同
```

所有清理都要求交互确认。`runtime` 和 `all` 在存在活跃 lease、run 或其他 Session 时拒绝执行；当前 Session 登记会保留。清理不删除 `config.yml`、`.gitignore` 或 `tasks/`，但重置 fencing 后旧 generation 不再保留，因此只能在确认没有执行中任务时使用。

脱离 OMP 的只读查询：

```powershell
./scripts/kanban.ps1 list --compact
./scripts/kanban.ps1 show 12
./scripts/kanban.ps1 list --archived --table
./scripts/kanban.ps1 board
./scripts/kanban.ps1 metrics
```

完整的 `/kanban` 子命令、Agent tool actions、20 个上游 CLI 命令及参数边界见 [命令参考](docs/commands.md)。

> Agent 必须通过 `kanban` 工具修改卡片，不能直接编辑 `.kanban/tasks/*.md`。直接执行 `kanban-md edit/move/archive` 不会创建或校验 OMP runtime lease，只适用于明确不受协调保护的人工整理操作。