ai-proj-helper/skills-core/ai-proj-plugin/skills/SKILL.md

name, description

name	description
ai-proj	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接口开发"

返回示例:

{
  "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：

# 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

参数:

{
  "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 - "用户管理" 章节

快速参考：

# 生成密码哈希（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：

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