内容
# AI 任务管理系统
**一个数据库。三类接口。零同步头痛。**
智能代理通过 **MCP** 进行计划和执行。人类在 **网页仪表盘** 中审查进度。脚本和调试会话使用 **stdlib CLI**。每个界面都读取和写入同一个 SQLite 文件 — 因此，您的代理可以将工作分解为子任务，而您可以在浏览器中实时查看树状结构的更新。
为以下团队而设计：智能代理执行工作，人类保持在环中。
---
## 选择您的路径
| 您是… | 从这里开始 | 为什么 |
|----------|------------|-----|
| **智能代理** （Cursor，Claude Desktop，远程工作者） | [快速入门 — MCP](#快速入门-mcp-智能代理) | 工作流工具，严格的生命周期验证，读取提示，可固定游戏手册 |
| **人类审查者** | [快速入门 — 网页仪表盘](#快速入门-网页仪表盘) | 任务树，文档中心，审计追踪，代理管理 |
| **脚本编写者/调试者** | [快速入门 — CLI](#快速入门-cli-备用) | 纯stdlib，JSON无处不在，无服务器进程 |
| **大规模运行无头代理** | [任务编排器SDK](#任务编排器sdk) | 通过Cursor CLI逐步遍历子任务树 |
---
## 目录
- [为什么存在](#为什么存在)
- [功能](#功能)
- [架构](#架构)
- [快速入门 — MCP（智能代理）](#快速入门-mcp-智能代理)
- [快速入门 — 网页仪表盘](#快速入门-网页仪表盘)
- [快速入门 — CLI（备用）](#快速入门-cli-备用)
- [Docker部署](#docker部署)
- [文档模型](#文档模型)
- [严格的生命周期规则](#严格的生命周期规则)
- [项目结构](#项目结构)
- [MCP工具和资源](#mcp工具和资源)
- [CLI参考](#cli参考)
- [代理技能](#代理技能)
- [任务编排器SDK](#任务编排器sdk)
- [开发](#开发)
- [许可证](#许可证)
---
## 为什么存在
大多数任务跟踪器将智能代理视为事后才考虑的因素 — 一个REST API拼凑在一起，没有生命周期防护措施，没有结构化文档，没有审计跟踪记录 *谁* 更改了 *什么*。
该系统颠覆了这一点：
- **智能代理拥有一个一流的MCP服务器**，配备工作流工具（`session_context` → `task_begin_work` → `task_record_progress` → `task_complete`），验证捕获粗糙的交接，并提供补救提示，当出现问题时。
- **人类拥有一个仪表盘**，渲染相同的任务树，Markdown文档和审计日志 — 无需导出/导入操作。
- **所有人共享一个SQLite数据库**（`server/task_manager.db`）。轻量级，可移植，可检查。
结果：结构化的智能代理工作，人类可以真正信任和审查。
---
## 功能
### 核心数据模型
- **项目** — 创建，更新，存档，恢复和跟踪完成进度
- **有序任务树** — 根任务和带有分数索引排序的嵌套子任务
- **六种任务状态** — `pending`，`in_progress`，`completed`，`blocked`，`failed`，`cancelled`
- **三个Markdown文档槽** — `spec`，`progress`和`closure`在每个项目和任务上
- **评论** — 时间戳，追加日志记录在项目和任务上
- **审计日志** — 字段级变更历史记录，包含代理名称和主管理员
### MCP智能代理体验
- **29种MCP工具** — CRUD加上复合工作流工具和丰富的读取路径
- **工作流工具** — `session_context`，`task_begin_work`，`task_record_progress`，`task_complete`
- **严格验证** — 需要`initial_spec`，工作前规格，父节点完成阻止，强制阻挡者/失败/关闭字段
- **引导响应** — 读取和突变时的`warnings`，`next_steps`；验证错误时的`remediation`
- **静态资源** — 可固定游戏手册和文档模板（`taskmgr://…` URI）
- **多代理** — 通过读取工具上的可选`api_key`共享项目
- **服务器指令** — 在MCP连接时注入游戏手册
### 网页仪表盘
- **首页** — 创建项目，搜索和筛选（活动/存档/全部），最近活动动态，注册代理
- **项目视图** — 可折叠任务树，实时搜索，状态筛选芯片
- **任务详情** — 面包屑导航，内联文档，HTMX驱动的评论，状态更新
- **文档中心** — 所有项目和任务文档的只读视图，按任务树分组
- **文档编辑器** — 使用实时预览（marked.js + DOMPurify）编写Markdown；视图在服务器端渲染（Python Markdown + Bleach）
- **审计页面** — 每个项目和代理的活动历史记录，分页
- **管理员** — 代理注册，密钥重新颁发，密码更改
### 代理治理
- **代理注册** — 使用API密钥注册代理（每个变更的审计身份）
- **可移植技能** — 用于Cursor和其他运行时的即插即用`skill/task-management/`（MCP优先）
---
## 架构
```mermaid
flowchart TB
subgraph clients [客户端]
MCP["MCP服务器\nmcp_server.py\n29种工具 + 4种资源"]
WEB["网页仪表盘\nFastAPI :8000"]
CLI["CLI\ncli.py\nstdlib，无服务器"]
end
subgraph data [数据层]
DB[("SQLite\ntask_manager.db")]
end
MCP --> DB
WEB --> DB
CLI --> DB
```
**文档类型**流经每个接口：
```
项目
├── spec → 计划和验收标准（在MCP创建时需要）
├── progress → 工作日志（永远不会覆盖spec）
└── closure → 完成时的摘要
任务（每个）
├── spec / progress / closure
└── 子任务（有序，嵌套）
```
**典型的代理会话：**
```
session_context → task_begin_work → task_record_progress → task_complete
```
---
## 快速入门 — MCP（智能代理）
### 1. 安装依赖项
```bash
cd server
python3 -m pip install -r requirements.txt
python3 cli.py db init # 仅第一次运行 — 创建task_manager.db
```
### 2. 注册并持久化您的API密钥
```bash
# 一次性 — 或在IDE中使用MCP工具agent_onboard
python3 cli.py agent onboard --name my-agent --master "您的姓名"
```
将返回的`api_key`保存在**存储库外部**，例如`~/.config/task-manager/credentials.json`。将其连接到您的MCP客户端环境中，以便上下文重置不会丢失身份验证：
```json
{
"mcpServers": {
"task-manager": {
"command": "python3",
"args": ["/绝对路径/到/server/mcp_server.py"],
"env": {
"TM_API_KEY": "tm_<您的密钥>"
}
}
}
}
```
参见 [skill/task-management/SKILL.md](skill/task-management/SKILL.md) 以获取完整的密钥防护措施。
### 3. 启动服务器
**标准输入输出** （Cursor，Claude Desktop — 子进程）：
```bash
python3 mcp_server.py
```
**HTTP/SSE** （远程代理）：
```bash
python3 mcp_server.py --http --port 8000
```
| 端点 | 目的 |
|----------|---------|
| `GET /sse` | 服务器发送事件流 |
| `POST /messages?session_id=…` | JSON-RPC消息 |
| `POST /mcp` | 可流式HTTP（无状态） |
### 4. 固定MCP资源（推荐）
在MCP主机上附加这些只读资源以获取稳定的会话上下文：
| URI | 内容 |
|-----|---------|
| `taskmgr://reference/playbook` | 代理游戏手册和生命周期规则 |
| `taskmgr://templates/spec` | `initial_spec` 骨架 |
| `taskmgr://templates/progress` | 进度文档骨架 |
| `taskmgr://templates/closure` | 闭包文档骨架 |
### 5. 运行您的第一个会话
```
1. session_context → 列出项目
2. session_context project_id=<id> → 可用任务，快照
3. task_begin_work task_id=<id> → 规格 + 评论，设置为in_progress
4. task_record_progress → 会话发现
5. task_complete task_id=<id> closure_note=… → 闭包 + 已完成
```
使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行测试：
```bash
npx @modelcontextprotocol/inspector http://localhost:8000/sse
```
> **端口冲突：** MCP HTTP和仪表盘都默认为端口`8000`。在另一个端口上运行一个，例如`python3 mcp_server.py --http --port 8001`或`uvicorn dashboard.app:app --port 8080`。
---
## 快速入门 — 网页仪表盘
```bash
cd server
python3 -m pip install -r requirements.txt
python3 dashboard/app.py
```
打开 **http://localhost:8000** 并登录：
| 字段 | 默认值 |
|-------|---------|
| 用户名 | `admin` |
| 密码 | `admin` |
在首次登录后，在 **设置** 下更改密码。
### 关键页面
| 页面 | URL | 描述 |
|------|-----|-------------|
| 首页 | `/` | 创建项目，搜索/筛选网格，活动动态，代理 |
| 项目 | `/projects/{id}` | 带有搜索和状态筛选器的任务树 |
| 任务详情 | `/tasks/{id}` | 面包屑，文档，评论，状态更新 |
| 所有文档 | `/projects/{id}/docs` | 项目和任务文档的只读中心 |
| 文档编辑器 | `/projects/{id}/doc` 或 `/tasks/{id}/doc` | 查看或编辑单个文档 |
| 审计日志 | `/projects/{id}/audit` | 项目和任务变更历史 |
| 代理 | `/admin/agents` | 已注册代理；重新颁发密钥 |
| 设置 | `/admin/settings` | 更改管理员密码 |
---
## 快速入门 — CLI（备用）
纯Python标准库 — 无服务器进程。适用于 **人类**，**调试** 和 **脚本**，当MCP未使用时。Cursor中的代理应优先使用MCP（验证，提示，工作流工具）。
```bash
cd server
python3 cli.py db init
export TM_API_KEY="tm_..." # 变更需要
python3 cli.py project create "构建身份验证系统" --desc "基于JWT的身份验证（40+字符）"
python3 cli.py task create <PROJECT_ID> "研究选项" --desc "..."
python3 cli.py project list --pretty
```
每个命令都发出 **JSON** 到stdout。传递`--pretty`以获取格式化输出。
> **注意：** CLI不强制执行所有MCP验证规则（例如，需要`initial_spec`）。新的代理驱动工作应通过MCP进行。
---
## Docker部署
将MCP服务器作为容器运行，并带有持久化数据库卷。
```bash
docker build -t task-manager .
docker run -d --name task-manager -p 8000:8000 -v tm-data:/data task-manager
```
代理连接到 `http://<host>:8000/sse`。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `TM_DB_PATH` | `/data/task_manager.db` | SQLite数据库路径 |
| `TM_API_KEY` | — | 服务器进程的可选默认API密钥 |
### Docker Compose
```yaml
services:
task-manager:
build: .
ports:
- "8000:8000"
volumes:
- tm-data:/data
restart: unless-stopped
volumes:
tm-data:
```
```bash
docker compose up -d
```
---
## 文档模型
每个项目和任务都有三个独立的Markdown文档：
| 类型 | 何时编写 | 目的 |
|------|---------------|---------|
| **spec** | 创建时（`initial_spec`在MCP创建时） | `## 目标`，`## 验收标准` |
| **progress** | 每个工作会话 | 发现和状态日志 |
| **closure** | 完成时 | 已交付内容的`## 摘要` |
**规则**
- 规格在创建时编写一次。如果需求变更，请添加 **注释** — 不要用进度覆盖规格。
- 使用 `task_record_progress`（MCP）或 `doc_type=progress` 进行持续更新。
- 使用 `task_complete` 或 `doc_type=closure` 在标记为完成之前。
有效MCP示例： [skill/task-management/references/examples.md](skill/task-management/references/examples.md)
---
## 严格的生命周期规则
在MCP API上强制执行（无退出选项）：
| 转换/操作 | 要求 |
|---------------------|-------------|
| `project_create` / `task_create` | 需要`initial_spec`（包括子任务），至少80个字符，目标 + 验收标准 |
| `in_progress` | 必须存在规格文档（`task_begin_work` 或 `task_update`） |
| `blocked` | `blocker_reason`（至少20个字符） |
| `failed` | `failure_reason` |
| `completed` | 闭包文档或`closure_note`；在子任务活动时，父节点被阻止 |
| 删除/存档 | 在适用情况下，需要`reason` |
验证错误返回 `remediation` 步骤。优先使用工作流工具而不是手动状态更改。
---
## 项目结构
```
ai-task-management/
├── Dockerfile
├── README.md
├── AGENTS.md # Cursor Cloud代理的说明
├── server/
│ ├── schema.sql
│ ├── db.py
│ ├── cli.py # 标准库CLI（JSON输出）
│ ├── mcp_server.py # MCP服务器（标准输入输出 + HTTP/SSE）
│ ├── mcp_instructions.py # 连接时的服务器指令
│ ├── mcp_resources.py # 静态游戏手册 + 模板
│ ├── mcp_validation.py # 严格的生命周期验证
│ ├── mcp_workflows.py # session_context, task_begin_work, …
│ ├── mcp_tool_descriptions.py
│ ├── mcp_read_hints.py / mcp_response_hints.py / mcp_enrich.py
│ ├── migrate_project_mcp.py # 将本地项目推送到远程MCP
│ ├── requirements.txt
│ ├── dashboard/ # FastAPI + Jinja2 + Tailwind
│ └── tests/ # pytest（db, cli, mcp_*, dashboard）
├── sdk/
│ └── task_orchestrator/ # 顺序子任务编排器
└── skill/
└── task-management/ # 便携式MCP优先代理技能
├── SKILL.md
└── references/
```
---
## MCP工具和资源
### 工作流工具（从这里开始）
| 工具 | 目的 |
|------|---------|
| `session_context` | 会话定位 — 项目，`available_tasks`，可选任务焦点 |
| `task_begin_work` | 开始任务 — 规格，评论，`in_progress` |
| `task_record_progress` | 进度文档 + 可选评论 |
| `task_complete` | 闭包 + 已完成（如果有活动子任务，则阻止） |
### 所有工具（29）
| 类别 | 工具 |
|----------|-------|
| **工作流** | `session_context`，`task_begin_work`，`task_record_progress`，`task_complete` |
| **项目** | `project_create`，`project_list`，`project_get`，`project_snapshot`，`project_update`，`project_archive`，`project_restore`，`project_delete` |
| **任务** | `task_create`，`task_list`，`task_get`，`task_tree`，`task_subtree`，`task_update`，`task_move`，`task_delete` |
| **文档** | `doc_project_get`，`doc_project_update`，`doc_task_get`，`doc_task_update` |
| **评论** | `comment_add`，`comment_list` |
| **代理和审计** | `agent_onboard`，`agent_list`，`audit_log_get` |
### 资源（4，只读）
`taskmgr://reference/playbook` · `taskmgr://templates/spec` · `taskmgr://templates/progress` · `taskmgr://templates/closure`
完整参数和设置： [skill/task-management/references/reference.md](skill/task-management/references/reference.md)
---
## CLI参考
| 领域 | 命令 |
|--------|----------|
| **数据库** | `db init` · `db path` |
| **项目** | `project create` · `list` · `get` · `update` · `delete` |
| **任务** | `task create` · `list` · `get` · `tree` · `subtree` · `update` · `move` · `delete` |
| **文档** | `doc project get/set` · `doc task get/set` |
| **评论** | `comment add` · `list` · `delete` |
| **代理** | `agent onboard` · `list` · `audit` · `audit-log` |
```bash
python3 cli.py --help
python3 cli.py task create --help
```
---
## 代理技能
便携式技能适用于Cursor和其他代理运行时 — **MCP优先**，带有上下文重置的API密钥防护措施：
```bash
cp -r skill/task-management/ ~/.cursor/skills/task-management/
```
| 文件 | 内容 |
|------|----------|
| [SKILL.md](skill/task-management/SKILL.md) | 会话工作流，严格规则，密钥持久性 |
| [references/examples.md](skill/task-management/references/examples.md) | MCP有效示例 |
| [references/reference.md](skill/task-management/references/reference.md) | 设置，工具，CLI备用 |
---
## 任务编排器SDK
在大型任务树中，以 **一个子任务一步** 运行无头代理。每个调用都传递一个任务ID — 代理通过MCP从TM获取上下文。
```bash
cd sdk && python3 -m pip install -e .
# 预览工作计划
task-orchestrator plan --task <ROOT_TASK_ID> --config examples/orchestrator.yaml --pretty
# 干燥运行 — 在.tm-runs/中写入提示而不调用代理
task-orchestrator run --task <ROOT_TASK_ID> --config examples/orchestrator.yaml --dry-run
# 完整运行
task-orchestrator run --task <ROOT_TASK_ID> --config examples/orchestrator.yaml --pretty
```
遍历模式（`depth_first`，`direct_children`，`flatten`），失败策略（`stop`，`pause`，`continue`）和 `.tm-runs/` 下的运行日志 — 参见 [sdk/README.md](sdk/README.md)。
---
## 开发
```bash
cd server
python3 -m pip install -r requirements.txt
# 初始化真实数据库（CLI子进程测试使用）
python3 cli.py db init
# 运行测试（大多数套件使用隔离的测试数据库）
python3 -m pytest
# 仅MCP测试
python3 -m pytest tests/test_mcp_*.py -q
# 带有重载的仪表盘（如果MCP HTTP在8000端口，则使用端口8080）
uvicorn dashboard.app:app --reload --port 8080 --app-dir .
# 在编辑Tailwind源代码后重建仪表盘CSS
cd dashboard && npm install && npm run build:css
```
**SDK测试：**
```bash
cd sdk
python3 -m pip install -e ".[dev]"
python3 -m pytest tests/ -v
```
测试涵盖数据层、CLI、MCP验证/工作流/资源和仪表盘UI。 如有需要，请设置`TM_DB_PATH`以指向不同的SQLite文件。
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器