459 lines
8.5 KiB
Markdown
459 lines
8.5 KiB
Markdown
# 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*
|
||
*作者：星枢*
|