---
name: ai-proj
description: ai-proj 任务与需求管理。用于创建/查询/更新需求、任务、文档。当用户提到 ai-proj、任务管理、需求管理、REQ-XXX 相关操作时自动激活。
---
## 功能概述

| 模块 | 功能 |
|------|------|
| **任务管理** | 创建、查询、更新、删除任务，子任务管理 |
| **需求管理** | 需求全生命周期：草稿→评审→开发→完成 |
| **文档管理** | 任务文档的创建、编辑、同步 |
| **计时器** | 任务计时、时间追踪 |
| **每日聚焦** | 今日任务规划、智能推荐 |
| **工作笔记** | 知识管理、笔记搜索 |
| **远程同步** | 本地↔远程数据同步 |

---

## 快速开始

### 常用命令速查

```
# 任务操作
"创建任务: xxx"              → mcp__ai-proj__create_task
"查看任务列表"               → mcp__ai-proj__list_tasks
"开始任务 123"               → mcp__ai-proj__start_task
"完成任务 123"               → mcp__ai-proj__complete_task
"查找任务 xxx"               → mcp__ai-proj__find_task

# 需求操作
"创建需求: xxx"              → mcp__ai-proj__create_requirement
"查看需求列表"               → mcp__ai-proj__list_requirements
"提交需求 123 评审"          → mcp__ai-proj__requirement_action (submit)
"批准需求 123"               → mcp__ai-proj__requirement_action (approve)

# 文档操作
"为任务 123 创建文档"        → mcp__ai-proj__create-and-attach
"查看任务 123 的文档"        → mcp__ai-proj__get_task_document

# 今日聚焦
"查看今日任务"               → mcp__ai-proj__get_daily_focus_tasks
"添加任务到今日聚焦"         → mcp__ai-proj__add_daily_focus_task

# 计时器
"开始计时任务 123"           → mcp__ai-proj__start_task_with_timer
"停止计时"                   → mcp__ai-proj__stop_timer
```

---

## 一、任务管理

### 1.1 创建任务

**MCP 函数**: `mcp__ai-proj__create_task`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | ✅ | 任务标题 |
| projectId | number | ❌ | 项目ID，默认为1 |

**自然语言示例**:
- "创建任务: 实现用户登录功能"
- "新建一个任务叫做数据库优化"
- "在项目2中创建任务: API接口开发"

**返回示例**:
```json
{
  "id": 5069,
  "title": "实现用户登录功能",
  "status": "todo",
  "project_id": 1
}
```

### 1.2 查看任务列表

**MCP 函数**: `mcp__ai-proj__list_tasks`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| projectId | number | ❌ | 项目ID筛选 |
| status | array | ❌ | 状态筛选: draft/planning/todo/in_progress/testing/completed/cancelled/on_hold/suspended/blocked/archived |
| priority | array | ❌ | 优先级筛选: low/medium/high |
| search | string | ❌ | 搜索关键词 |
| page | number | ❌ | 页码，从1开始 |
| limit | number | ❌ | 每页数量，默认20，最大100 |
| sort_by | string | ❌ | 排序字段: created_at/updated_at/due_date/priority/title |
| sort_order | string | ❌ | 排序方向: asc/desc |
| response_mode | string | ❌ | 响应模式: minimal/compact/full |

**自然语言示例**:
- "查看所有任务"
- "列出进行中的任务"
- "查看高优先级任务"
- "搜索包含登录的任务"

### 1.3 查找任务

**MCP 函数**: `mcp__ai-proj__find_task`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ❌ | 任务ID（优先使用） |
| titlePattern | string | ❌ | 标题搜索关键词 |

**自然语言示例**:
- "查找任务 5069"
- "搜索任务名包含登录的"

### 1.4 获取任务详情

**MCP 函数**: `mcp__ai-proj__get_detailed_task_info`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | number | ✅ | 任务ID |

**返回**: 包含父任务、同级任务、子任务的格式化信息

### 1.5 更新任务

**MCP 函数**: `mcp__ai-proj__update_task`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ✅ | 任务ID |
| updates | object | ✅ | 更新字段 |

**updates 支持的字段**:
- `title`: 新标题
- `description`: 新描述
- `status`: 新状态 (draft/planning/todo/in_progress/testing/completed/cancelled/on_hold/suspended/blocked/archived)
- `priority`: 新优先级 (low/medium/high)
- `due_date`: 截止日期 (ISO 8601)
- `assignee_id`: 负责人ID

**自然语言示例**:
- "把任务 5069 的状态改为进行中"
- "更新任务 5069 的优先级为高"
- "修改任务 5069 的标题为: 新标题"

### 1.6 任务状态操作

**开始任务**: `mcp__ai-proj__start_task`
```
参数: id (number) - 任务ID
说明: 将任务状态改为 in_progress
```

**完成任务**: `mcp__ai-proj__complete_task`
```
参数: id (number) - 任务ID
说明: 将任务状态改为 completed
```

**暂停任务**: `mcp__ai-proj__pause_task`
```
参数: id (number) - 任务ID
说明: 将任务状态改为 on_hold
```

**删除任务**: `mcp__ai-proj__delete_task`
```
参数:
- id (number) - 任务ID
- force (boolean) - 是否强制删除（包含子任务）
```

### 1.7 子任务管理

**创建子任务**: `mcp__ai-proj__create_subtask`
```
参数:
- parentId (number) - 父任务ID
- title (string) - 子任务标题
```

**创建兄弟任务**: `mcp__ai-proj__create_sibling_task`
```
参数:
- siblingId (number) - 兄弟任务ID（参考任务）
- title (string) - 新任务标题
- description (string) - 任务描述
- priority (string) - 优先级: low/medium/high
- status (string) - 状态
```

**获取子任务**: `mcp__ai-proj__get_task_children`
```
参数: parentId (number) - 父任务ID
```

### 1.8 移动任务

**MCP 函数**: `mcp__ai-proj__move_task`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ✅ | 任务ID |
| targetProjectId | number | ✅ | 目标项目ID |

---

## 二、需求管理

### 2.1 创建需求

**MCP 函数**: `mcp__ai-proj__create_requirement`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | ✅ | 需求标题 |
| projectId | number | ✅ | 项目ID |
| description | string | ❌ | 需求描述 |
| priority | string | ❌ | 优先级: low/medium/high/urgent |
| category | string | ❌ | 类别: feature/bug/improvement/documentation/other |
| allowSelfApprove | boolean | ❌ | 允许自审批（自动审批时需设为 true） |

**创建需求必填清单**：
- [ ] `title` - 需求标题
- [ ] `projectId` - 所属项目（不要遗漏！）
- [ ] `priority` - 优先级
- [ ] `description` - 需求描述

> **注意**: 后端已实现默认截止日期：未填 `due_date` 时按优先级自动设置（urgent +1天、high +3天、medium +7天、low +14天）。MCP `create_requirement` 不支持 `due_date` 参数，如需自定义截止日期，创建后通过 REST API 更新。

**自然语言示例**:
- "创建需求: 用户权限管理功能"
- "新建一个高优先级需求: 性能优化"

### 2.2 查看需求列表

**MCP 函数**: `mcp__ai-proj__list_requirements`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_id | number | ❌ | 项目ID筛选 |
| status | array | ❌ | 状态筛选: draft/pending/reviewing/approved/rejected/archived |
| priority | array | ❌ | 优先级筛选 |
| category | array | ❌ | 类别筛选 |
| search | string | ❌ | 搜索关键词 |
| page | number | ❌ | 页码 |
| page_size | number | ❌ | 每页数量 |
| response_mode | string | ❌ | 响应模式: minimal/compact/full |

### 2.3 获取需求详情

**MCP 函数**: `mcp__ai-proj__get_requirement`

**参数**: `id` (number) - 需求ID

### 2.4 更新需求

**MCP 函数**: `mcp__ai-proj__update_requirement`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ✅ | 需求ID |
| updates | object | ✅ | 更新字段 |

**updates 支持的字段**: title, description, priority, category, allow_self_approve

> **已知限制**: MCP `update_requirement` 工具**不支持**更新 `project_id` 和 `due_date` 字段。
> 如需更新这两个字段，必须直接调用后端 REST API：
> ```bash
> # Dev 环境
> curl -s -X PUT "http://localhost:8080/api/v1/requirements/{id}" \
>   -H "Content-Type: application/json" \
>   -H "X-API-Key: {TASK_API_TOKEN}" \
>   -d '{"project_id": 1, "due_date": "2026-02-27T00:00:00Z"}'
>
> # 生产环境
> curl -s -X PUT "https://ai.pipexerp.com/api/v1/requirements/{id}" \
>   -H "Content-Type: application/json" \
>   -H "X-API-Key: {SYNC_REMOTE_API_KEY}" \
>   -d '{"project_id": 1, "due_date": "2026-02-27T00:00:00Z"}'
> ```
> 注意：`due_date` 必须使用 RFC3339 格式（如 `2026-02-27T00:00:00Z`），`YYYY-MM-DD` 格式会返回 BAD_REQUEST。

### 2.5 需求工作流

**MCP 函数**: `mcp__ai-proj__requirement_action`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ✅ | 需求ID |
| action | string | ✅ | 操作类型: submit/approve/reject/withdraw/archive |
| reason | string | ❌ | 拒绝原因（reject时必填） |
| comment | string | ❌ | 批准意见 |

**工作流状态图**:
```
draft → [submit] → pending → [approve] → approved
                           → [reject]  → rejected
pending → [withdraw] → draft
approved → [archive] → archived
```

**自然语言示例**:
- "提交需求 123 进行评审"
- "批准需求 123"
- "拒绝需求 123，原因：需求不完整"
- "撤回需求 123"
- "归档需求 123"

### 2.6 需求-任务关联

**关联任务到需求**: `mcp__ai-proj__link_tasks_to_requirement`
```
参数:
- requirementId (number) - 需求ID
- taskIds (array) - 任务ID列表
- linkComment (string) - 关联备注
```

**取消关联**: `mcp__ai-proj__unlink_task_from_requirement`
```
参数:
- requirementId (number) - 需求ID
- taskId (number) - 任务ID
```

**获取需求关联的任务**: `mcp__ai-proj__get_requirement_tasks`
```
参数:
- requirementId (number) - 需求ID
- page, page_size - 分页参数
```

### 2.7 需求统计与历史

**获取统计**: `mcp__ai-proj__get_requirement_statistics`
```
参数: id (number) - 需求ID
返回: 关联任务数、完成率等统计信息
```

**获取历史**: `mcp__ai-proj__get_requirement_history`
```
参数: id (number), page, page_size
返回: 需求操作历史记录
```

---

## 三、文档管理

### 3.1 创建任务文档

**MCP 函数**: `mcp__ai-proj__create-and-attach`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | number | ✅ | 任务ID |
| content | string | ✅ | 文档内容（Markdown格式） |
| title | string | ❌ | 文档标题 |
| projectId | number | ❌ | 项目ID |

**自然语言示例**:
- "为任务 5069 创建PRD文档"
- "给任务 5069 添加开发计划文档"

### 3.2 追加文档内容

**MCP 函数**: `mcp__ai-proj__append-document-content`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | number | ✅ | 任务ID |
| documentId | number | ✅ | 文档ID |
| content | string | ✅ | 追加内容（Markdown） |
| projectId | number | ❌ | 项目ID |

### 3.3 获取文档

**获取元数据**: `mcp__ai-proj__get_task_document_meta`
```
参数: taskId (number)
返回: 文档元数据（不含完整内容，节省token）
```

**获取内容**: `mcp__ai-proj__get_task_document`
```
参数:
- taskId (number) - 任务ID
- projectId (number) - 项目ID
- maxLength (number) - 最大返回字符数
- offset (number) - 起始位置
```

**检查是否有文档**: `mcp__ai-proj__has_task_document`
```
参数: taskId (number), projectId (number)
返回: boolean
```

### 3.4 更新/删除文档

**更新文档**: `mcp__ai-proj__update_task_document`
```
参数:
- taskId (number) - 任务ID
- content (string) - 新内容
- title (string) - 新标题
- projectId (number)
```

**删除文档**: `mcp__ai-proj__delete_task_document`
```
参数: taskId (number), projectId (number)
```

### 3.5 文档同步

**导出到文件**: `mcp__ai-proj__export_task_document_to_file`
```
参数:
- taskId (number)
- projectId (number)
- overwrite (boolean) - 是否覆盖，默认true
导出位置: dev-plans 目录
```

**从文件导入**: `mcp__ai-proj__import_task_document_from_file`
```
参数:
- taskId (number)
- projectId (number)
- fileName (string) - 文件名
- updateIfNewer (boolean) - 仅当文件更新时导入
- forceOverwrite (boolean) - 强制覆盖
```

**批量同步**: `mcp__ai-proj__sync_task_documents`
```
参数:
- taskIds (array) - 任务ID列表
- direction (string) - 同步方向: export/import/both
- forceOverwrite (boolean)
- projectId (number)
```

---

## 四、工作笔记

### 4.1 创建工作笔记

**MCP 函数**: `mcp__ai-proj__create_work_note`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | ✅ | 笔记标题 |
| content | string | ✅ | 笔记内容（Markdown） |
| type | string | ❌ | 类型: markdown/text/html |
| tags | array | ❌ | 标签列表 |
| status | string | ❌ | 状态: draft/published/archived |
| visibility | string | ❌ | 可见性: private/team/public |

**创建并关联到任务**: `mcp__ai-proj__create-and-attach-work-note`
```
参数:
- taskId (number) - 任务ID
- content (string) - 笔记内容
- title (string) - 标题
```

### 4.2 查看/搜索笔记

**列出笔记**: `mcp__ai-proj__list_work_notes`
```
参数: page, limit, status, type
```

**搜索笔记**: `mcp__ai-proj__search_work_notes`
```
参数:
- query (string) - 搜索关键词
- tags (array) - 标签筛选
- limit (number)
```

**获取详情**: `mcp__ai-proj__get_work_note`
```
参数: id (number)
```

### 4.3 更新笔记

**MCP 函数**: `mcp__ai-proj__update_work_note`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | ✅ | 笔记ID |
| updates | object | ✅ | 更新字段 |

---

## 五、计时器

### 5.1 基本计时

**开始计时**: `mcp__ai-proj__start_timer`
```
参数:
- taskId (number) - 任务ID
- description (string) - 计时描述
```

**停止计时**: `mcp__ai-proj__stop_timer`
```
参数: taskId (number) - 可选，不指定则停止所有计时
```

**获取当前计时**: `mcp__ai-proj__get_current_timer`
```
无参数
返回: 当前正在进行的计时器信息
```

**获取活跃计时器**: `mcp__ai-proj__get_active_timers`
```
无参数
返回: 所有 running/paused 状态的计时器
```

### 5.2 智能计时

**启动任务并计时**: `mcp__ai-proj__start_task_with_timer`
```
参数:
- taskIdOrTitle (number|string) - 任务ID或标题（支持模糊匹配）
- timerDescription (string) - 计时描述
- projectId (number)
功能: 自动开始任务并启动计时器
```

**切换任务**: `mcp__ai-proj__switch_to_task`
```
参数:
- newTaskTitle (string) - 任务标题（支持模糊匹配）
- projectId (number)
功能: 停止当前计时，切换到新任务并开始计时
```

**自然语言示例**:
- "开始任务 登录功能开发 并计时"
- "切换到 API开发 任务"
- "停止计时"

---

## 七、项目管理

### 7.1 查看项目列表

**MCP 函数**: `mcp__ai-proj__list_projects`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | ❌ | 状态筛选: active/inactive/planning/on_hold/completed/cancelled/archived |
| search | string | ❌ | 搜索关键词 |
| page | number | ❌ | 页码 |
| pageSize | number | ❌ | 每页数量 |
| sortBy | string | ❌ | 排序字段: created_at/updated_at/name/priority |
| sortOrder | string | ❌ | 排序方向: asc/desc |

### 7.2 创建项目

**MCP 函数**: `mcp__ai-proj__create_project`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | ✅ | 项目名称 |
| description | string | ❌ | 项目描述 |

---

## 九、报告与时间线

### 9.1 获取日报

**MCP 函数**: `mcp__ai-proj__get_daily_work_report`

**参数**: `projectId` (number) - 项目ID，默认为1

**返回**: 今日工作报告，包含完成任务、进行中任务、时间统计等

### 9.2 获取任务时间线

**MCP 函数**: `mcp__ai-proj__get_task_timeline`

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | number | ✅ | 任务ID |
| projectId | number | ❌ | 项目ID |
| limit | number | ❌ | 记录数限制，默认20 |
| offset | number | ❌ | 偏移量 |

---

## 十、批量文档操作

### 10.1 批量创建文档

**MCP 函数**: `mcp__ai-proj__create_batch_documents`

**参数**:
```json
{
  "documents": [
    {
      "title": "文档标题",
      "content": "Markdown内容",
      "taskId": 5069,
      "attachToTask": true,
      "type": "markdown",
      "status": "draft",
      "tags": ["tag1", "tag2"],
      "relationType": "attachment"
    }
  ]
}
```

---

## 十二、开发工具

### 12.1 快速登录

**MCP 函数**: `mcp__ai-proj__dev_quick_login`

**参数**: `username` (string) - 用户名，默认qiudl

**说明**: 仅在开发环境(APP_ENV=development/dev)有效，自动获取JWT

---

## 注意事项

1. **项目ID默认值**: 大多数函数的 `projectId` 默认为 1
2. **响应模式**: 使用 `response_mode: minimal` 可减少返回数据量
3. **分页**: 大量数据请使用分页参数 `page` 和 `limit`
4. **状态流转**: 任务和需求都有状态机，注意状态转换规则
5. **同步方向**: 远程同步时注意 `to_remote` 和 `from_remote` 方向
6. **计时器**: 同一时间只能有一个活跃计时器

---

## 用户管理

> **重要**: 创建数据库用户时必须使用 bcrypt **cost 12** 进行密码哈希。

详细的用户管理流程请参考：
- **ops-tools/SKILL.md** - "AI-Proj 用户管理" 章节
- **ops-tools/ai-proj-deploy.md** - "用户管理" 章节

**快速参考**：
```bash
# 生成密码哈希（cost 12）
cd /path/to/new-ai-proj/backend
cat > /tmp/genhash.go << 'EOF'
package main
import ("fmt"; "golang.org/x/crypto/bcrypt")
func main() {
    hash, _ := bcrypt.GenerateFromPassword([]byte("密码"), 12)
    fmt.Println(string(hash))
}
EOF
go run /tmp/genhash.go
```

**常见错误**：使用 cost 10 生成的哈希无法登录（后端 DefaultCost=12）

**已创建的系统用户**：

| 用户名 | 邮箱 | user_type | role | 创建时间 |
|--------|------|-----------|------|----------|
| qiudl | qiudl@zhiyuncai.com | system | admin | - |
| jiaxiang | jiaxiang@joylodging.com | system | admin | 2026-01 |
| haiqing | haiqing@joylodging.com | system | admin | 2026-02 |

> 注意：密码信息不在文档中记录，如需重置请参考 ops-tools 技能文档

---

## 核心方案
1. 关键点 1（一句话）
2. 关键点 2（一句话）
3. 关键点 3（一句话）

## 技术架构
- 第1层：组件名（职责）
- 第2层：组件名（职责）
- 第3层：组件名（职责）


## 详细内容

以下章节已移到 [references/details.md](references/details.md)：

- 六、每日聚焦
- 八、项目手册
- 十一、远程同步
- 自然语言操作示例
- Google 日历集成配置
- 十三、最佳实践与故障排查
- 实施周期