npm package: @qq33357486/oh-my-task
Description: 文档驱动的 AI 编程协作系统 - 通过 MCP 工具管理任务
Latest version: 1.4.0

# oh-my-task

文档驱动的 AI 编程协作系统 - 通过 MCP 工具管理任务，解决 AI 上下文有限的问题。

## 功能特性

- **MCP 工具集**：18 个工具，通过 AI 助手完整管理任务生命周期
- **SOP（技能/智能体）**：任务执行流程标准化，支持经验积累和进化
- **文件存储**：SOP 存储在项目 `.omt/sops/` 目录，支持 Git 版本管理
- **REST API**：完整的任务管理接口，支持第三方集成
- **多层任务**：支持版本 → 任务 → 子任务的无限层级
- **团队协作**：API Key 认证，支持多用户，任务负责人分配
- **可视化**：Web 界面提供列表、看板、甘特图三种视图

## 快速开始

### 一键启动（推荐）

```bash
# 首次安装
npm install
cd web && npm install && cd ..
npm run db:init

# 一键启动前后端（自动清理端口，防止重复启动）
npm run dev:all
```

- 后端 API: http://localhost:3000
- 前端界面: http://localhost:5173

### 其他命令

```bash
npm run dev        # 只启动后端
npm run db:clean   # 清理乱码数据
npm run db:init    # 初始化/重置数据库
```

### Docker 部署（推荐）

```bash
docker-compose up -d
```

服务运行在 http://localhost:3000（前后端整合）

## MCP 配置

在你的 AI 助手（Claude Desktop / Cursor 等）中配置：

```json
{
  "mcpServers": {
    "oh-my-task": {
      "command": "npx",
      "args": ["tsx", "/path/to/oh-my-task/src/mcp/server.ts"],
      "env": {
        "OMT_SERVER_URL": "http://localhost:3000",
        "OMT_API_KEY": "omt-admin-key"
      }
    }
  }
}
```

## 核心概念

### SOP（技能/智能体）

SOP（Standard Operating Procedure）是执行同类任务时的标准化流程定义。

**存储位置**：`.omt/sops/{sop-id}.md`（Markdown 格式，支持 Git 管理）

**文件结构**：
```
项目目录/
├── .omt/
│   ├── rules.md           # 任务管理规则
│   └── sops/              # SOP 存储目录
│       ├── {sop-id-1}.md
│       └── {sop-id-2}.md
├── .omt.json              # 项目配置
└── ...
```

**SOP 内容**：

| 字段 | 说明 |
|------|------|
| 规则 | 执行任务时必须遵循的基本原则 |
| 流程 | 执行任务的标准步骤 |
| 强制 | 必须完成的事项 |
| 禁止 | 不允许做的事情 |
| 经验 | 任务完成后 AI 自动总结的经验 |

SOP 会在任务完成时自动进化，AI 会分析本次执行过程并追加经验。

### 任务状态（简化版）

| 状态 | 说明 | 触发工具 |
|------|------|----------|
| `planned` | 计划中 | 初始状态 |
| `in_progress` | 进行中 | `activate_task` |
| `done` | 完成 | `complete_task` |

状态流转：`planned → in_progress → done`

### 用户流程

```
创建版本 → 创建任务 → 激活任务（必须指定 SOP）
                              ↓
                    执行任务（自动读取 SOP）
                              ↓
                    完成任务（AI 分析并更新 SOP 经验）
```

## MCP 工具列表

### SOP 管理

| 工具 | 说明 |
|------|------|
| `create_sop` | 创建 SOP（技能/智能体），存储到 `.omt/sops/` 目录 |
| `list_sops` | 列出项目中的所有 SOP |
| `get_sop` | 获取 SOP 详情，包含所有规则、流程、强制、禁止和经验内容 |
| `update_sop` | 更新 SOP 内容（支持追加经验） |

### 版本管理

| 工具 | 说明 |
|------|------|
| `create_version` | 创建版本（任务的顶层容器） |
| `list_versions` | 查询项目的所有版本 |
| `archive_version` | 归档版本（标记删除并页面不再显示） |

### 任务管理

| 工具 | 说明 |
|------|------|
| `create_task` | 创建任务或子任务 |
| `list_tasks` | 查询任务列表，支持多种筛选 |
| `get_task` | 获取任务详情（含完整子任务树） |
| `get_task_context` | 获取任务完整上下文（需求、设计、当前情况、历史、子任务） |
| `get_my_tasks` | 获取当前用户负责的任务 |
| `get_next_task` | 获取下一个要做的任务 |
| `update_task` | 更新任务信息 |
| `update_task_doc` | 更新任务阶段文档（需求/设计/当前情况） |
| `activate_task` | 激活任务（状态→进行中，**必须指定 SOP**） |
| `complete_task` | 完成任务（状态→完成，**AI 分析并更新 SOP 经验**） |
| `assign_task` | 分配/变更任务负责人 |
| `delete_task` | 删除任务（软删除） |
| `add_task_note` | 添加任务备注 |

### 项目管理

| 工具 | 说明 |
|------|------|
| `init_project` | 初始化项目，创建 .omt.json 配置文件 |

## 使用示例

### 1. 初始化项目

```
用户: 初始化项目，名字叫"寒冬将至"
AI: [调用 init_project] 项目初始化成功！
    已创建：.omt.json、.omt/rules.md、.omt/sops/
```

### 2. 创建版本和任务

```
用户: 创建版本"v1.0"，然后添加任务：寒冬套装、寒冬通行证、寒冬礼包
AI: [调用 create_version] 版本创建成功！
    [调用 create_task x3] 3个任务已创建
```

### 3. 激活任务（必须指定 SOP）

```
用户: 开始做寒冬套装
AI: [调用 activate_task，不传 sop_id]
    
    ⚠️ 激活任务需要指定 SOP。
    
    现有 SOP：
    - 前端组件开发 (ID: xxx)
    - 后端 API 开发 (ID: yyy)
    
    请选择：
    1. 使用某个已有 SOP
    2. 创建新 SOP
    3. 不需要 SOP
    
用户: 用前端组件开发
AI: [调用 activate_task，sop_id=xxx] 
    
    任务已激活！
    
    📚 已关联 SOP: 前端组件开发
    
    ## 规则
    1. 遵循项目代码规范
    ...
```

### 4. 完成任务（自动更新 SOP）

```
用户: 寒冬套装做完了
AI: [调用 complete_task]
    
    任务已完成！✅
    
    📚 此任务关联了 SOP「前端组件开发」
    
    请分析本次任务执行过程，是否要将经验追加到 SOP？
    
用户: 好的，经验是：组件命名要有意义，props 要有默认值
AI: [调用 update_sop，append_experience="..."] 
    经验已追加到 SOP，文件已更新：.omt/sops/xxx.md
```

### 5. 归档版本

```
用户: v1.0 已经发布了，归档吧
AI: [调用 archive_version] 版本已归档！📦
    版本: v1.0
    已归档任务数: 5
```

## API 文档

所有 API 需要认证头：
```
Authorization: Bearer <api_key>
```

默认管理员 API Key: `omt-admin-key`

### 用户 API
- `GET /api/users` - 用户列表（管理员）
- `GET /api/users/me` - 当前用户
- `POST /api/users` - 创建用户（管理员）

### 项目 API
- `GET /api/projects` - 项目列表
- `POST /api/projects` - 创建项目
- `GET /api/projects/:id` - 项目详情

### SOP API
- `GET /api/sops` - SOP 列表（需要 `project_id` 和 `project_path`）
- `POST /api/sops` - 创建 SOP
- `GET /api/sops/:id` - SOP 详情
- `PUT /api/sops/:id` - 更新 SOP
- `DELETE /api/sops/:id` - 删除 SOP

### 版本 API
- `GET /api/versions` - 版本列表
- `POST /api/versions` - 创建版本
- `GET /api/versions/:id` - 版本详情
- `PUT /api/versions/:id` - 更新版本
- `POST /api/versions/:id/archive` - 归档版本
- `DELETE /api/versions/:id` - 删除版本

### 任务 API
- `GET /api/tasks` - 任务列表（支持筛选）
- `POST /api/tasks` - 创建任务
- `GET /api/tasks/:id` - 任务详情（含子任务树）
- `PUT /api/tasks/:id` - 更新任务
- `DELETE /api/tasks/:id` - 删除任务（软删除）
- `GET /api/tasks/:id/history` - 任务历史
- `POST /api/tasks/:id/history` - 添加备注
- `GET /api/tasks/:id/context` - 获取任务完整上下文（断点续传）
- `PUT /api/tasks/:id/doc` - 更新任务阶段文档
- `POST /api/tasks/:id/activate` - 激活任务
- `POST /api/tasks/:id/complete` - 完成任务

## 项目结构

```
oh-my-task/
├── src/                    # 后端源码
│   ├── api/                # REST API
│   │   ├── routes/         # 路由（tasks, sops, versions, users, projects）
│   │   └── middleware/     # 认证中间件
│   ├── mcp/                # MCP Server
│   │   ├── server.ts       # MCP 服务器入口
│   │   └── tools/          # MCP 工具实现
│   ├── services/           # 业务逻辑层
│   ├── db/                 # 数据库（SQLite）
│   └── types/              # TypeScript 类型定义
├── web/                    # 前端源码 (React + Vite)
│   └── src/
│       ├── pages/          # 页面组件
│       ├── api.ts          # API 客户端
│       └── App.tsx         # 根组件
├── data/                   # SQLite 数据库文件
└── 文档区/                 # 项目文档
```

## 设计理念

1. **文档驱动**：任务信息存储在数据库，AI 通过 MCP 工具精准读取，避免大量上下文
2. **断点续传**：新对话可通过 `get_task_context` 一次性获取任务的需求、设计、当前情况，快速恢复上下文
3. **SOP 进化**：任务完成时 AI 自动分析并追加经验，SOP 持续进化
4. **文件存储**：SOP 存储在项目目录，支持 Git 版本管理
5. **状态简化**：只有 3 个状态，流程更清晰

## License

MIT