# Agent 任务管理 CLI 工具实现方案

> 创建日期：2026-03-19
> 作者：星枢
> 用途：定义 CLI 工具的具体实现，供 Agent 调用

---

## 1. 概述

本文档定义用于任务管理的 CLI 工具，帮助执行 Agent（yunjiang、yunzhi、fengchi 等）与 Notion 任务看板交互，实现任务领取、执行、更新、验收等操作。

**核心原则**：
- 简单可靠：一条命令完成一个操作
- 幂等性：重复执行不产生副作用
- 可观测：输出关键日志，便于调试

---

## 2. 工具设计

### 2.1 命令结构

```bash
kanban <command> [options]
```

### 2.2 命令列表

| 命令 | 用途 | 示例 |
|------|------|------|
| `kanban list` | 列出任务 | `kanban list -s TODO -a yunjiang` |
| `kanban get` | 查看任务详情 | `kanban get <task-id>` |
| `kanban take` | 领取任务 | `kanban take <task-id>` |
| `kanban done` | 完成任务 | `kanban done <task-id> -r /path/to/report.md` |
| `kanban review` | 验收任务 | `kanban review <task-id> -r pass -m "验收说明"` |
| `kanban my-tasks` | 我的待办任务 | `kanban my-tasks` |
| `kanban pending-review` | 待我验收的任务 | `kanban pending-review` |

---

## 3. 详细命令定义

### 3.1 kanban list

列出符合条件的任务。

```bash
kanban list [options]
```

**选项**：

| 选项 | 缩写 | 说明 | 默认值 |
|------|------|------|--------|
| `--status` | `-s` | 任务状态 | 全部 |
| `--assignee` | `-a` | 执行者 | 全部 |
| `--priority` | `-p` | 优先级 | 全部 |
| `--limit` | `-l` | 返回数量限制 | 10 |

**示例**：

```bash
# 列出我（yunjiang）待执行的任务
kanban list -s TODO -a yunjiang

# 列出所有待验收的任务
kanban list -s "待验收"

# 列出优先级最高的任务（限制5条）
kanban list -s TODO -p 1 -l 5
```

**输出格式**：

```
ID          任务名                    状态      执行者      优先级
----------- ------------------------ -------- ----------- --------
abc123      配置 CI/CD 流水线         TODO     yunjiang    1
def456      修复登录 Bug             TODO     yunjiang    2
```

---

### 3.2 kanban get

查看单个任务的完整信息。

```bash
kanban get <task-id>
```

**示例**：

```bash
kanban get abc123
```

**输出格式**：

```
任务: 配置 CI/CD 流水线
ID: abc123
状态: TODO
优先级: 1
执行者: yunjiang
验收者: fengheng
验收标准:
  - CI 流水线运行成功
  - 测试覆盖率 > 80%
  - 部署到测试环境无报错
验收方式: 自动
依赖任务: def456 (已完成)
创建时间: 2026-03-18 10:00
```

---

### 3.3 kanban take

领取任务，将状态从 TODO 改为 进行中。

```bash
kanban take <task-id>
```

**示例**：

```bash
kanban take abc123
```

**输出**：

```
✅ 已领取任务: abc123
   状态: TODO → 进行中
```

**错误情况**：

```
❌ 任务已被其他人领取 (状态: 进行中, 执行者: yunzhi)
❌ 依赖任务未完成 (依赖: def456 状态: TODO)
```

---

### 3.4 kanban done

完成任务，将状态从 进行中 改为 待验收。

```bash
kanban done <task-id> [options]
```

**选项**：

| 选项 | 缩写 | 说明 | 必需 |
|------|------|------|------|
| `--report` | `-r` | Obsidian 报告文件路径 | 是 |

**示例**：

```bash
# 完成任务并提交报告
kanban done abc123 -r /Users/weishen/Obsidian/shenwei/reports/2026-03-19/ci-pipeline.md
```

**输出**：

```
✅ 任务完成: abc123
   状态: 进行中 → 待验收
   报告: /Users/weishen/Obsidian/shenwei/reports/2026-03-19/ci-pipeline.md
```

**错误情况**：

```
❌ 任务状态不是进行中，无法完成
❌ 报告文件不存在
```

---

### 3.5 kanban review

验收任务（供 fengheng 使用）。

```bash
kanban review <task-id> [options]
```

**选项**：

| 选项 | 缩写 | 说明 | 必需 |
|------|------|------|------|
| `--result` | `-r` | 验收结果：`pass` 或 `fail` | 是 |
| `--message` | `-m` | 验收说明或失败原因 | 否 |

**示例**：

```bash
# 验收通过
kanban review abc123 -r pass -m "CI 流水线运行成功，测试通过"

# 验收失败
kanban review abc123 -r fail -m "部署脚本有语法错误"
```

**输出**：

```
✅ 验收通过: abc123
   状态: 待验收 → 完成

❌ 验收失败: abc123
   状态: 待验收 → 需修复
   原因: 部署脚本有语法错误
```

---

### 3.6 kanban my-tasks

查看当前 Agent 待执行的任务（快捷命令）。

```bash
kanban my-tasks
```

**实现逻辑**：等同于 `kanban list -s TODO -a <当前Agent-ID>`

**输出**：

```
🎯 你有 2 个待执行任务：

[1] 配置 CI/CD 流水线 (优先级: 1)
    ID: abc123
    验收标准: CI 运行成功, 覆盖率 > 80%

[2] 修复登录 Bug (优先级: 2)
    ID: def456
    验收标准: 登录流程无报错
```

---

### 3.7 kanban pending-review

查看待当前 Agent 验收的任务（快捷命令，供 fengheng 使用）。

```bash
kanban pending-review
```

**实现逻辑**：等同于 `kanban list -s "待验收" -a fengheng`

---

## 4. 实现架构

### 4.1 目录结构

```
/opt/kanban/
├── bin/
│   └── kanban                    # 主入口脚本
├── src/
│   ├── __init__.py
│   ├── cli.py                    # CLI 参数解析
│   ├── notion_client.py          # Notion API 封装
│   ├── obsidian_client.py        # Obsidian 操作封装
│   └── config.py                 # 配置管理
├── config/
│   └── config.yaml               # 配置文件
└── reports/                      # 报告输出目录（可选）
```

### 4.2 配置文件 config.yaml

```yaml
notion:
  api_key: "secret_xxxxxxxxxxxxx"
  database_id: "xxxxxxxxxxxxx"

obsidian:
  vault_path: "/Users/weishen/Obsidian/shenwei"
  reports_folder: "reports"

agent:
  # 当前 Agent ID，由启动时注入
  id: "yunjiang"
```

### 4.3 依赖

```txt
# requirements.txt
pyyaml>=6.0
requests>=2.28.0
python-dotenv>=1.0.0
click>=8.0.0
```

---

## 5. Agent 集成方式

### 5.1 环境变量注入

通过环境变量传递当前 Agent ID：

```bash
export KANBAN_AGENT_ID="yunjiang"
kanban my-tasks
```

### 5.2 在 Agent 代码中调用

**示例：yunjiang 执行任务后**

```python
import subprocess
import os

def execute_and_report(task_id, report_path):
    # 1. 执行任务（业务逻辑）...
    result = do_task(task_id)
    
    # 2. 生成报告
    with open(report_path, 'w') as f:
        f.write(f"# 任务执行报告\n\n{result}")
    
    # 3. 调用 CLI 更新 Notion
    subprocess.run([
        'kanban', 'done', task_id,
        '--report', report_path
    ], env={**os.environ, 'KANBAN_AGENT_ID': 'yunjiang'})
```

---

## 6. 错误处理

### 6.1 错误码

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1 | 参数错误 |
| 2 | Notion API 错误 |
| 3 | 任务状态不合法 |
| 4 | 文件不存在 |
| 5 | 权限不足 |

### 6.2 重试机制

对于 Notion API 调用（网络不稳定），实现指数退避重试：

```python
def call_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except requests.exceptions.RequestException as e:
            if i == max_retries - 1:
                raise
            time.sleep(2 ** i)  # 1s, 2s, 4s
```

---

## 7. 日志

### 7.1 日志级别

| 级别 | 用途 |
|------|------|
| ERROR | 操作失败 |
| WARNING | 警告（可继续） |
| INFO | 关键操作（默认） |
| DEBUG | 调试信息 |

### 7.2 日志格式

```
2026-03-19 07:30:00 [INFO] kanban done abc123 - task completed
2026-03-19 07:30:01 [ERROR] kanban take def456 - dependency not met
```

### 7.3 日志文件

```
/var/log/kanban/kanban.log
```

---

## 8. 部署步骤

### 8.1 安装依赖

```bash
# 安装 Python 依赖
pip install -r requirements.txt

# 确保在 PATH 中
export PATH="/opt/kanban/bin:$PATH"
```

### 8.2 配置

```bash
# 复制配置模板
cp config/config.yaml.example config/config.yaml

# 编辑配置
vim config/config.yaml
# 填入 Notion API Key 和 Database ID
```

### 8.3 测试

```bash
# 测试 list 命令
kanban list -s TODO

# 测试获取任务
kanban get <task-id>
```

---

## 9. 待实现功能

- [ ] Notion API 封装（notion_client.py）
- [ ] CLI 参数解析（cli.py）
- [ ] 配置文件管理（config.py）
- [ ] Obsidian 报告模板
- [ ] 日志系统
- [ ] 错误处理与重试
- [ ] 单元测试

---

## 10. 相关文档

- [[Agent任务管理系统设计]] - 整体架构设计
- [[星枢调度Agent列表]] - Agent 职责定义
- Notion API 官方文档：https://developers.notion.com/

---

*最后更新：2026-03-19*
*作者：星枢*
