# Agent 任务管理 CLI 工具实现方案 > 创建日期：2026-03-19 > 作者：星枢 > 用途：定义 CLI 工具的具体实现，供 Agent 调用 --- ## 1. 概述 本文档定义用于任务管理的 CLI 工具，帮助执行 Agent（yunjiang、yunzhi、fengchi 等）与 Notion 任务看板交互，实现任务领取、执行、更新、验收等操作。 **核心原则**： - 简单可靠：一条命令完成一个操作 - 幂等性：重复执行不产生副作用 - 可观测：输出关键日志，便于调试 --- ## 2. 工具设计 ### 2.1 命令结构 ```bash kanban [options] ``` ### 2.2 命令列表 | 命令 | 用途 | 示例 | |------|------|------| | `kanban list` | 列出任务 | `kanban list -s TODO -a yunjiang` | | `kanban get` | 查看任务详情 | `kanban get ` | | `kanban take` | 领取任务 | `kanban take ` | | `kanban done` | 完成任务 | `kanban done -r /path/to/report.md` | | `kanban review` | 验收任务 | `kanban review -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 ``` **示例**： ```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 ``` **示例**： ```bash kanban take abc123 ``` **输出**： ``` ✅ 已领取任务: abc123 状态: TODO → 进行中 ``` **错误情况**： ``` ❌ 任务已被其他人领取 (状态: 进行中, 执行者: yunzhi) ❌ 依赖任务未完成 (依赖: def456 状态: TODO) ``` --- ### 3.4 kanban done 完成任务，将状态从 进行中 改为 待验收。 ```bash kanban done [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 [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 ``` --- ## 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* *作者：星枢*