first build nexus

2026-03-23 20:57:45 +08:00
parent acb58c5684
commit e312026141
400 changed files with 52448 additions and 0 deletions
--- a/openclaw/xingshu/Agent任务管理CLI工具实现方案.md
+++ b/openclaw/xingshu/Agent任务管理CLI工具实现方案.md
@@ -0,0 +1,458 @@
+# 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*
+*作者：星枢*