chore(skill): 清理全部 23 条历史校验警告

- 11 个超 20KB 的 SKILL.md 拆分，大章节移入 references/details.md - 7 处非标准字段（arguments/user_invocable）移入 metadata - 修 req-dev 4 条相对链接；validate 跳过行内代码避免 ![](...) 误报 - validate-skills.py: 23 warns -> 0 warns，0 errors
2026-10-31 22:21:07 +08:00
parent 7d47762303
commit 237631147a
29 changed files with 4013 additions and 3928 deletions
@@ -2,11 +2,6 @@
 name: ai-proj
 description: ai-proj 任务与需求管理。用于创建/查询/更新需求、任务、文档。当用户提到 ai-proj、任务管理、需求管理、REQ-XXX 相关操作时自动激活。
 ---
-
-# ai-proj MCP 技能
-
-通过 MCP (Model Context Protocol) 直接调用 ai-proj 服务，管理任务、需求和文档。
-
 ## 功能概述

 | 模块 | 功能 |
@@ -572,102 +567,6 @@ approved → [archive] → archived

 ---

-## 六、每日聚焦
-
-### 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) - 排除已存在任务
-返回: 基于优先级、截止日期等的智能推荐
-```
-
---
-
 ## 七、项目管理

 ### 7.1 查看项目列表
@@ -696,90 +595,6 @@ approved → [archive] → archived

 ---

-## 八、项目手册
-
-### 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 的文档"
- "查找数据库相关的手册"
-
---
-
 ## 九、报告与时间线

 ### 9.1 获取日报
@@ -830,83 +645,6 @@ approved → [archive] → archived

 ---

-## 十一、远程同步
-
-### 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)
-```
-
---
-
 ## 十二、开发工具

 ### 12.1 快速登录
@@ -919,52 +657,6 @@ approved → [archive] → archived

 ---

-## 自然语言操作示例
-
-### 任务管理
-
-| 用户说 | 调用函数 |
-|--------|----------|
-| "创建一个任务叫做登录功能开发" | `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` |
-
---
-
 ## 注意事项

 1. **项目ID默认值**: 大多数函数的 `projectId` 默认为 1
@@ -1013,229 +705,6 @@ go run /tmp/genhash.go

 ---

-## Google 日历集成配置
-
-### 环境变量
-
-生产环境需要配置以下环境变量（`.env` 文件）：
-
-```bash
-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](https://console.cloud.google.com/)
-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
-
-### 部署配置
-
-```bash
-# 更新生产环境配置
-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 日历集成需要以下表：
-
-```sql
-- 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 字段"请求数据格式错误"
-
-**症状**：
-```json
-{
-  "code": "BAD_REQUEST",
-  "message": "请求数据格式错误"
-}
-```
-
-**常见原因**：
-
-| 原因 | 解决方案 |
-|------|----------|
-| **description 内容过长** | API 可能有字段长度限制，逐步测试找到上限 |
-| **Markdown 特殊字符** | 检查是否有未转义的特殊字符（如反引号、引号） |
-| **JSON 转义问题** | 确保 JSON 字符串正确转义（尤其是换行符、引号） |
-| **多层嵌套的代码块** | Markdown 代码块中的反引号可能导致解析失败 |
-
-**正确的调试流程**：
-
-```python
-# ❌ 错误做法：直接简化内容
-"创建失败 → 简化 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：完整的需求 + 关联文档**
-```typescript
-// 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：分段创建需求描述**
-```typescript
-// 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 需求描述的格式建议
-
-**推荐的需求描述结构**（简洁版）：
-
-```markdown
 ## 核心方案
 1. 关键点 1（一句话）
 2. 关键点 2（一句话）
@@ -1246,139 +715,15 @@ await update_requirement({
 - 第2层：组件名（职责）
 - 第3层：组件名（职责）

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

-**详细内容放在关联文档**：
- 需求背景与业务价值
- 详细的技术方案
- 实施路线图与时间规划
- 风险评估与应对措施
- 验收标准
+## 详细内容

-**Markdown 格式注意事项**：
+以下章节已移到 [references/details.md](references/details.md)：

-```markdown
-✅ 安全的格式：
- 简单的标题（# ## ###）
- 无序列表（-）
- 有序列表（1. 2. 3.）
- 简单的表格
- 加粗（**text**）
-
-⚠️ 可能有问题的格式：
- 三重反引号代码块（```）
- HTML 标签
- 复杂的嵌套列表
- 大量的特殊字符
- 超长的单行文本
-```
-
-### 13.3 更新需求的最佳实践
-
-**使用 update_requirement 补充详细内容**：
-
-```typescript
-// 创建需求后，逐步更新描述
-await update_requirement({
-  id: 857,  // REQ-20260217-0001
-  updates: {
-    description: `
-      ## 需求背景
-
-      ### 当前问题
-      思源笔记仅提供 REST API 接口，AI 操作复杂...
-
-      ### 业务价值
-      为思源笔记添加 MCP 协议层支持，使其能够...
-
-      ## 技术方案
-
-      ### 架构设计
-      ...（详细内容）
-    `
-  }
-});
-```
-
-**测试长度限制**：
-
-```bash
-# 逐步增加内容，找到上限
-第1次: 200字  → 成功
-第2次: 500字  → 成功
-第3次: 1000字 → 成功
-第4次: 2000字 → 成功
-第5次: 5000字 → 失败 ← 找到上限
-
-结论: description 字段最大约 3000-4000 字
-```
-
-### 13.4 故障排查清单
-
-遇到 API 错误时，按以下步骤排查：
-
-**步骤 1：分析错误信息**
-```json
-{
-  "code": "BAD_REQUEST",
-  "message": "请求数据格式错误"
-}
-```
- [ ] 错误码是什么？（BAD_REQUEST / VALIDATION_ERROR / AUTH_FAILED）
- [ ] 错误信息是否有具体提示？
- [ ] 是哪个字段导致的错误？
-
-**步骤 2：检查参数格式**
- [ ] 必填参数是否都提供了？
- [ ] 参数类型是否正确？（number vs string）
- [ ] 枚举值是否在允许范围内？
- [ ] JSON 格式是否正确？
-
-**步骤 3：简化测试**
- [ ] 尝试最小化的参数集
- [ ] 逐个添加可选参数
- [ ] 找到导致错误的具体参数
-
-**步骤 4：查看后端日志**（如有权限）
-```bash
-# 生产环境日志
-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 字以内
- 详细内容使用关联文档
- 复杂格式改为纯文本
+- 六、每日聚焦
+- 八、项目手册
+- 十一、远程同步
+- 自然语言操作示例
+- Google 日历集成配置
+- 十三、最佳实践与故障排查
+- 实施周期