ishenwei/nexus

Fork 0

Files

billyshen e312026141 first build nexus

2026-03-23 20:57:45 +08:00

8.5 KiB

Raw Blame History

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

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

1. 概述

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

核心原则：

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

2. 工具设计

2.1 命令结构

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

列出符合条件的任务。

kanban list [options]

选项：

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

示例：

# 列出我（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

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

kanban get <task-id>

示例：

kanban get abc123

输出格式：

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

3.3 kanban take

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

kanban take <task-id>

示例：

kanban take abc123

输出：

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

错误情况：

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

3.4 kanban done

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

kanban done <task-id> [options]

选项：

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

示例：

# 完成任务并提交报告
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 使用）。

kanban review <task-id> [options]

选项：

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

示例：

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

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

输出：

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

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

3.6 kanban my-tasks

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

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 使用）。

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

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 依赖

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

5. Agent 集成方式

5.1 环境变量注入

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

export KANBAN_AGENT_ID="yunjiang"
kanban my-tasks

5.2 在 Agent 代码中调用

示例：yunjiang 执行任务后

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 调用（网络不稳定），实现指数退避重试：

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 安装依赖

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

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

8.2 配置

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

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

8.3 测试

# 测试 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 作者：星枢

8.5 KiB Raw Blame History Unescape Escape