ai-proj-helper/skills-core/ai-proj-plugin/skills/references/details.md

skills 详细内容

六、每日聚焦

6.1 查看今日任务

MCP 函数: mcp__ai-proj__get_daily_focus_tasks

参数:

参数	类型	必填	说明
date	string	❌	日期 (YYYY-MM-DD)
status	string	❌	状态筛选: active/completed/removed
priority	string	❌	优先级筛选
include_suggestions	boolean	❌	是否包含智能推荐

6.2 添加任务到今日聚焦

单个添加: mcp__ai-proj__add_daily_focus_task

参数:
- task_id (number) - 任务ID
- priority (string) - 优先级: critical/high/medium/low
- estimated_duration_minutes (number) - 预估时长
- notes (string) - 备注
- focus_date (string) - 聚焦日期

批量添加: mcp__ai-proj__batch_add_daily_focus_tasks

参数:
- task_ids (array) - 任务ID列表
- priority (string) - 统一优先级
- notes (string) - 统一备注
- focus_date (string)

快速添加当前任务: mcp__ai-proj__quick_add_current_task

参数:
- priority (string) - 优先级，默认high
- notes (string)
功能: 将当前正在进行的任务添加到今日聚焦

6.3 管理今日任务

更新: mcp__ai-proj__update_daily_focus_task

参数:
- id (number) - Daily Focus任务ID
- priority, estimated_duration_minutes, notes

移除: mcp__ai-proj__remove_daily_focus_task

参数: id (number)

完成: mcp__ai-proj__complete_daily_focus_task

参数: id (number)

聚焦并计时: mcp__ai-proj__focus_task_with_timer

参数:
- daily_focus_task_id (number)
- timer_description (string)

清理已完成: mcp__ai-proj__clear_completed_tasks

参数:
- date (string) - 日期
- confirm (boolean) - 必须设为true

6.4 统计与推荐

获取统计: mcp__ai-proj__get_daily_focus_stats

参数:
- date (string)
- period (string) - 统计周期: daily/weekly/monthly

获取任务推荐: mcp__ai-proj__get_task_recommendations

参数:
- date (string)
- limit (number) - 推荐数量
- exclude_existing (boolean) - 排除已存在任务
返回: 基于优先级、截止日期等的智能推荐

---

八、项目手册

8.1 查看手册列表

MCP 函数: mcp__ai-proj__list_manuals

参数:

参数	类型	必填	说明
projectId	number	✅	项目ID
status	string	❌	状态筛选: draft/published/archived
parentId	number	❌	父级手册ID（获取子级列表）
search	string	❌	搜索关键词（标题或描述）

自然语言示例:

• "查看项目手册列表"
• "列出已发布的手册"
• "查看手册 5 的子章节"

8.2 创建手册

MCP 函数: mcp__ai-proj__create_manual

参数:

参数	类型	必填	说明
projectId	number	✅	项目ID
title	string	✅	手册标题
content	string	❌	手册内容（Markdown格式）
description	string	❌	手册简介
parentId	number	❌	父级手册ID（用于创建子章节）
status	string	❌	状态: draft/published，默认draft

自然语言示例:

• "创建项目手册: API 开发规范"
• "在手册 5 下创建子章节: 接口设计规范"
• "创建并发布手册: 前端开发规范"

8.3 获取手册详情

MCP 函数: mcp__ai-proj__get_manual

参数: id (number) - 手册ID

返回: 完整的手册内容（Markdown格式）

自然语言示例:

• "查看手册 5 的内容"
• "显示 API 开发规范手册"

8.4 更新手册

MCP 函数: mcp__ai-proj__update_manual

参数:

参数	类型	必填	说明
id	number	✅	手册ID
title	string	❌	新标题
content	string	❌	新内容（Markdown格式）
description	string	❌	新简介
status	string	❌	新状态: draft/published/archived

自然语言示例:

• "更新手册 5 的内容"
• "发布手册 5"
• "归档手册 5"

8.5 搜索手册

MCP 函数: mcp__ai-proj__search_manuals

参数:

参数	类型	必填	说明
projectId	number	✅	项目ID
query	string	✅	搜索关键词

自然语言示例:

• "搜索项目手册中包含 API 的文档"
• "查找数据库相关的手册"

---

十一、远程同步

11.1 任务同步

同步任务: mcp__ai-proj__sync_task

参数:
- taskId (number)
- direction (string) - to_remote/from_remote
- includeDocument (boolean) - 是否同步文档
- includeChildren (boolean) - 是否同步子任务

批量同步到远程: mcp__ai-proj__batch_sync_tasks_to_remote

参数:
- taskIds (array)
- includeDocuments (boolean)
- includeChildren (boolean)

获取同步状态: mcp__ai-proj__get_task_sync_status

参数: taskId (number)

获取远程同步状态: mcp__ai-proj__get_remote_sync_status

参数: taskId (number)
返回: 比较本地和远程版本差异

通过UUID获取任务: mcp__ai-proj__get_task_by_uuid

参数: uuid (string)
用途: 跨库同步场景

11.2 需求同步

同步需求到远程: mcp__ai-proj__sync_requirement_to_remote

参数:
- requirementId (number)
- includeHistory (boolean)
- includeComments (boolean)

从远程同步需求: mcp__ai-proj__sync_requirement_from_remote

参数:
- remoteRequirementId (number)
- includeHistory (boolean)
- includeComments (boolean)

批量同步需求: mcp__ai-proj__batch_sync_requirements_to_remote

参数:
- requirementIds (array)
- includeComments (boolean)

同步需求-任务关联: mcp__ai-proj__sync_requirement_task_links

参数:
- linkUUIDs (array) - 关联关系的UUID列表
- forceUpdate (boolean)

同步任务的需求关联: mcp__ai-proj__sync_task_links_to_remote

参数: taskId (number)

---

自然语言操作示例

任务管理

用户说	调用函数
"创建一个任务叫做登录功能开发"	create_task
"查看所有进行中的任务"	list_tasks
"开始任务 5069"	start_task
"完成任务 5069"	complete_task
"暂停任务 5069"	pause_task
"把任务 5069 移到项目2"	move_task
"给任务 5069 创建子任务: 数据库设计"	create_subtask

需求管理

用户说	调用函数
"创建需求: 用户权限管理"	create_requirement
"查看待审核的需求"	list_requirements
"提交需求 123 评审"	requirement_action (submit)
"批准需求 123"	requirement_action (approve)
"拒绝需求 123，原因是需求不完整"	requirement_action (reject)
"将任务 5069 关联到需求 123"	link_tasks_to_requirement

文档操作

用户说	调用函数
"为任务 5069 创建PRD文档"	create-and-attach
"查看任务 5069 的文档"	get_task_document
"更新任务 5069 的文档"	update_task_document
"导出任务 5069 的文档到文件"	export_task_document_to_file

计时与聚焦

用户说	调用函数
"开始计时任务 5069"	start_task_with_timer
"停止计时"	stop_timer
"查看今日任务"	get_daily_focus_tasks
"把任务 5069 添加到今日聚焦"	add_daily_focus_task
"生成今日工作报告"	get_daily_work_report

---

Google 日历集成配置

环境变量

生产环境需要配置以下环境变量（.env 文件）：

GOOGLE_CLIENT_ID=<你的Client ID>.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-<你的Client Secret>
GOOGLE_PROJECT_ID=<你的项目ID>
GOOGLE_REDIRECT_URL=https://ai.pipexerp.com/api/v1/auth/google/callback
GOOGLE_CALENDAR_SCOPES=https://www.googleapis.com/auth/calendar

获取 Google OAuth 凭据

1. 创建 Google Cloud 项目

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 记录项目 ID

2. 启用 API

1. 进入 APIs & Services → Library
2. 搜索并启用 Google Calendar API

3. 配置 OAuth 同意屏幕

1. 进入 APIs & Services → OAuth consent screen
2. 选择 External → 创建
3. 填写应用名称、支持邮箱
4. 添加 Scopes:
   • https://www.googleapis.com/auth/calendar
   • https://www.googleapis.com/auth/calendar.events
5. 添加测试用户（开发阶段）

4. 创建 OAuth 凭据

1. 进入 APIs & Services → Credentials
2. 点击 + CREATE CREDENTIALS → OAuth client ID
3. 选择 Web application
4. 配置:
   • Name: AI-Proj Web Client
   • Authorized JavaScript origins: https://ai.pipexerp.com
   • Authorized redirect URIs: https://ai.pipexerp.com/api/v1/auth/google/callback
5. 复制 Client ID 和 Client Secret

部署配置

# 更新生产环境配置
ssh tools_ai_proj "cd /home/ubuntu/apps/new-ai-proj && \
sed -i 's|GOOGLE_CLIENT_ID=.*|GOOGLE_CLIENT_ID=<CLIENT_ID>|' .env && \
sed -i 's|GOOGLE_CLIENT_SECRET=.*|GOOGLE_CLIENT_SECRET=<CLIENT_SECRET>|' .env && \
sed -i 's|GOOGLE_PROJECT_ID=.*|GOOGLE_PROJECT_ID=<PROJECT_ID>|' .env && \
docker restart ai_backend_prod"

数据库迁移

Google 日历集成需要以下表：

-- OAuth 状态表（CSRF 保护）
CREATE TABLE oauth_states (
    id SERIAL PRIMARY KEY,
    state VARCHAR(255) NOT NULL UNIQUE,
    user_id INTEGER NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 项目日历配置表
-- 见 migrations/20260210_01_project_calendar.sql

-- 日历 Webhook 表
-- 见 migrations/20260211_01_calendar_webhooks.sql

当前配置（2026-02）

配置项	值
Project ID	project-bfa64769-1595-4c41-964
Client ID	78721641513-...apps.googleusercontent.com
Redirect URL	https://ai.pipexerp.com/api/v1/auth/google/callback

注意: Client Secret 不在文档中记录，存储在生产环境 .env 文件中

---

十三、最佳实践与故障排查

13.1 创建需求的最佳实践

问题：description 字段"请求数据格式错误"

症状：

{
  "code": "BAD_REQUEST",
  "message": "请求数据格式错误"
}

常见原因：

原因	解决方案
description 内容过长	API 可能有字段长度限制，逐步测试找到上限
Markdown 特殊字符	检查是否有未转义的特殊字符（如反引号、引号）
JSON 转义问题	确保 JSON 字符串正确转义（尤其是换行符、引号）
多层嵌套的代码块	Markdown 代码块中的反引号可能导致解析失败

正确的调试流程：

# ❌ 错误做法：直接简化内容
"创建失败 → 简化 description → 成功"
问题：丢失了重要的需求细节

# ✅ 正确做法：找到根本原因
步骤 1: 测试空描述
  create_requirement(description="")
  → 是否成功？

步骤 2: 测试纯文本
  create_requirement(description="简单文本")
  → 是否成功？

步骤 3: 测试简单 Markdown
  create_requirement(description="# 标题\n\n内容")
  → 是否成功？

步骤 4: 逐步增加复杂度
  create_requirement(description="包含代码块的Markdown")
  create_requirement(description="包含表格的Markdown")
  create_requirement(description="完整的技术方案")
  → 找到临界点

步骤 5: 根据根因选择方案
  - 如果是长度限制 → 分段或使用附件
  - 如果是特殊字符 → 转义或替换
  - 如果是 Markdown → 简化格式或转纯文本

推荐方案：

方案 A：完整的需求 + 关联文档

// 1. 创建需求（简洁描述）
const req = await create_requirement({
  title: "思源笔记增加 MCP 协议层支持",
  description: "核心方案：创建独立的 siyuan-mcp-bridge 服务...",
  projectId: 162
});

// 2. 创建详细的技术方案文档
const doc = await create_requirement_document({
  requirementId: req.id,
  title: "技术方案详细设计",
  content: `
    # 需求背景
    ...（完整的技术方案，3000+ 字）

    # 架构设计
    ...

    # 实施路线图
    ...
  `
});

方案 B：分段创建需求描述

// 1. 创建需求（基本信息）
const req = await create_requirement({
  title: "思源笔记增加 MCP 协议层支持",
  description: "简短描述",
  projectId: 162
});

// 2. 更新需求（逐步添加内容）
await update_requirement({
  id: req.id,
  updates: {
    description: description_part1  // 添加背景
  }
});

await update_requirement({
  id: req.id,
  updates: {
    description: description_part1 + description_part2  // 添加架构
  }
});

经验总结

原则 1：业务优先于技术

• ❌ 为了创建成功而牺牲需求完整性
• ✅ 找到技术方案来满足业务需求

原则 2：追根溯源

• ❌ 基于假设快速妥协（"可能是太长了"）
• ✅ 通过调试找到真正的错误原因

原则 3：给用户选择权

• ❌ 自作主张简化内容
• ✅ 询问用户的偏好和优先级

原则 4：保留完整信息

• ❌ 简化后的需求缺少关键信息
• ✅ 通过关联文档保留详细内容

13.2 需求描述的格式建议

推荐的需求描述结构（简洁版）：

## 实施周期
X周（阶段1 + 阶段2 + 阶段3）

详细内容放在关联文档：

• 需求背景与业务价值
• 详细的技术方案
• 实施路线图与时间规划
• 风险评估与应对措施
• 验收标准

Markdown 格式注意事项：

✅ 安全的格式：
- 简单的标题（# ## ###）
- 无序列表（-）
- 有序列表（1. 2. 3.）
- 简单的表格
- 加粗（**text**）

⚠️ 可能有问题的格式：
- 三重反引号代码块（```）
- HTML 标签
- 复杂的嵌套列表
- 大量的特殊字符
- 超长的单行文本

13.3 更新需求的最佳实践

使用 update_requirement 补充详细内容：

// 创建需求后，逐步更新描述
await update_requirement({
  id: 857,  // REQ-20260217-0001
  updates: {
    description: `
      ## 需求背景

      ### 当前问题
      思源笔记仅提供 REST API 接口，AI 操作复杂...

      ### 业务价值
      为思源笔记添加 MCP 协议层支持，使其能够...

      ## 技术方案

      ### 架构设计
      ...（详细内容）
    `
  }
});

测试长度限制：

# 逐步增加内容，找到上限
第1次: 200字  → 成功
第2次: 500字  → 成功
第3次: 1000字 → 成功
第4次: 2000字 → 成功
第5次: 5000字 → 失败 ← 找到上限

结论: description 字段最大约 3000-4000 字

13.4 故障排查清单

遇到 API 错误时，按以下步骤排查：

步骤 1：分析错误信息

{
  "code": "BAD_REQUEST",
  "message": "请求数据格式错误"
}

• 错误码是什么？（BAD_REQUEST / VALIDATION_ERROR / AUTH_FAILED）
• 错误信息是否有具体提示？
• 是哪个字段导致的错误？

步骤 2：检查参数格式

• 必填参数是否都提供了？
• 参数类型是否正确？（number vs string）
• 枚举值是否在允许范围内？
• JSON 格式是否正确？

步骤 3：简化测试

• 尝试最小化的参数集
• 逐个添加可选参数
• 找到导致错误的具体参数

步骤 4：查看后端日志（如有权限）

# 生产环境日志
ssh tools_ai_proj "docker logs ai_backend_prod --tail 100"

# 开发环境日志
cd ~/coding/new-ai-proj/backend
tail -f logs/app.log

步骤 5：参考类似的成功案例

• 查看 SKILL.md 中的示例
• 查看之前成功的调用记录
• 对比参数差异

13.5 常见错误与解决方案

错误	可能原因	解决方案
BAD_REQUEST	参数格式错误	检查参数类型和 JSON 格式
VALIDATION_ERROR	参数验证失败	检查必填字段和枚举值
AUTH_FAILED	认证失败	检查 Token 是否过期
PERMISSION_DENIED	权限不足	检查用户角色和权限
NOT_FOUND	资源不存在	检查 ID 是否正确
INTERNAL_ERROR	服务器错误	查看后端日志排查

13.6 需求 description 长度测试记录

测试日期: 2026-02-17

长度	格式	结果	备注
~200字	简单文本	✅ 成功	核心方案3点
~3000字	完整 Markdown	❌ 失败	"请求数据格式错误"
待测试	1000字 Markdown	?	需要进一步测试
待测试	2000字 Markdown	?	需要进一步测试

建议：

• 需求描述控制在 1000 字以内
• 详细内容使用关联文档
• 复杂格式改为纯文本