AgentPM

调用 apm_task 工具时：

1. 参数验证：

   • 验证 action 参数（必填，且必须是有效操作之一）
   • 验证 projectRoot 参数（必填，且必须是绝对路径）
   • 验证特定操作所需的参数：
     • 对于 get_single：验证 id 参数（必填，且为非空字符串）
     • 对于 filter_by_status：验证 status 参数（必填，且必须是有效状态）
     • 对于 filter_by_priority：验证 priority 参数（必填，且必须是有效优先级）
   • 验证可选参数：file、withSubtasks 和 containsText

2. 获取任务：

   • 从指定位置读取任务文件（如果未提供，默认为 apm-artifacts/artifacts.json）
   • 从文件中提取任务列表

3. 执行操作：

   • 根据 action 参数执行相应操作：
     • get_all：返回所有任务，可按状态筛选
     • get_single：按 ID 返回指定任务
     • get_next：根据依赖关系和状态返回下一个要处理的任务
     • filter_by_status：返回按状态筛选的任务
     • filter_by_priority：返回按优先级筛选的任务

4. 特定操作的处理：

   • 对于 get_all 和 filter_by_status：
     • 如果指定了状态，则按状态筛选任务
     • 根据 withSubtasks 参数处理子任务
     • 计算摘要指标
   • 对于 get_single：
     • 解析任务 ID，以确定其是否为子任务
     • 查找指定的任务或子任务
   • 对于 get_next：
     • 排除已完成的任务
     • 如果指定了优先级和文本筛选条件，则应用这些条件
     • 检查依赖项是否已满足
     • 确定优先级并选择下一个任务
   • 对于 filter_by_priority：
     • 按优先级筛选任务
     • 根据 withSubtasks 参数处理子任务
     • 计算摘要指标

5. 响应格式化：

   • 返回结构化的 JSON 响应，其中包含：
     • 请求的任务数据
     • 成功状态和消息
     • 与查询相关的上下文信息
     • 时间戳和会话信息

6. 错误处理：

   • 处理验证错误（缺少必填字段、值无效）
   • 处理文件未找到错误
   • 处理任务未找到错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_task",
  "params": {
    "action": "get_all|get_single|get_next|filter_by_status|filter_by_priority",
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "id": "5",  // Required for get_single action
    "status": "pending|in-progress|done|deferred|cancelled",  // For get_all and filter_by_status actions
    "priority": "high|medium|low",  // For get_next and filter_by_priority actions
    "withSubtasks": true|false,
    "containsText": "optional search text"  // For get_next action
  }
}

JSON-RPC 响应

对于 get_all 和 filter_by_status 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "pending"
        },
        "message": "Found 5 tasks with status 'pending'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_all",
              "status": "pending",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

对于 get_single 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "task": {
            "id": "5",
            "title": "Implement Feature",
            "description": "Create the feature",
            "status": "pending",
            "priority": "high",
            "dependencies": ["3", "4"],
            "details": "Implementation details..."
          }
        },
        "message": "Found task: Implement Feature",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_single",
              "id": "5"
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

对于 get_next 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "nextTask": {
            "id": "2",
            "title": "Next Task",
            "description": "Description",
            "status": "pending",
            "priority": "high",
            "dependencies": []
          },
          "allTasks": [
            /* Array of all tasks */
          ]
        },
        "message": "Found next task: Next Task",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_next",
              "priority": "high",
              "containsText": null
            },
            "taskCount": 10,
            "readyTaskCount": 3,
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

对于 filter_by_priority 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "high"
        },
        "message": "Found 5 tasks with priority 'high'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "filter_by_priority",
              "priority": "high",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

调用 apm_task_modify 工具时：

1. 参数验证：

   • 验证 action 参数（必填，且必须是有效操作之一）
   • 验证 projectRoot 参数（必填，且必须是绝对路径）
   • 根据要执行的操作验证相应的专用参数
   • 验证 file 等可选参数

2. 执行操作：

   • 根据 action 参数执行相应操作：
     • create：使用指定属性创建新任务
     • update：使用新信息更新现有任务
     • update_status：更改一个或多个任务的状态
     • delete：从项目中移除任务
     • add_subtask：为现有任务添加子任务
     • remove_subtask：从任务中移除子任务
     • clear_subtasks：移除一个或多个任务的所有子任务
     • expand：使用 AI 将任务拆分为子任务
     • expand_all：使用 AI 将所有待处理任务拆分为子任务

3. 文件操作：

   • 从指定位置读取任务文件（如果未提供，则默认为 apm-artifacts/artifacts.json）
   • 根据执行的操作更新任务数据
   • 将更新后的任务数据写回文件
   • 根据需要生成单独的任务文件（除非 skipGenerate 为 true）

4. AI 集成（适用于某些操作）：

   • 使用 Claude AI 拆分和更新任务
   • 可选择使用 Perplexity AI 执行基于研究的操作
   • 根据任务上下文生成智能子任务

5. 响应格式：

   • 返回结构化的 JSON 响应，其中包含：
     • 操作专用数据（任务、子任务等）
     • 成功消息
     • 面向用户的沟通指南
     • Agent 后续步骤说明

6. 错误处理：

   • 处理验证错误（缺少必填字段、值无效）
   • 处理文件未找到错误
   • 处理任务未找到错误
   • 处理 AI 服务错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_task_modify",
  "params": {
    "action": "create|update|update_status|delete|add_subtask|remove_subtask|clear_subtasks|expand|expand_all",
    "projectRoot": "/absolute/path/to/project",
    // Action-specific parameters
    // For create action
    "title": "Task Title",
    "description": "Task Description",
    "priority": "high|medium|low",
    "dependencies": "1,2,3",
    "details": "Implementation details",
    "testStrategy": "Test strategy",
    // For update action
    "id": "1",
    "prompt": "Update information",
    "research": true|false,
    "researchOnly": true|false,
    // For update_status action
    "id": "1",
    "status": "pending|in-progress|done|deferred|cancelled",
    // For delete action
    "id": "1",
    "confirm": true|false,
    // For add_subtask action
    "id": "1",
    "title": "Subtask Title",
    "description": "Subtask Description",
    "details": "Subtask details",
    "dependencies": "1.1,1.2",
    "status": "pending|in-progress|done|deferred|cancelled",
    "taskId": "2", // Existing task ID to convert to subtask
    "skipGenerate": true|false,
    // For remove_subtask action
    "id": "1.1",
    "convert": true|false,
    "skipGenerate": true|false,
    // For clear_subtasks action
    "id": "1", // Can be comma-separated for multiple tasks
    "all": true|false, // Clear subtasks from all tasks
    // For expand action
    "id": "1",
    "num": 3, // Number of subtasks to generate
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // For expand_all action
    "num": 3,
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // Common optional parameters
    "file": "optional/path/to/artifacts.json"
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          // Action-specific response data
          // For create action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For update action
          "task": {
            "id": "1",
            "title": "Updated Task Title",
            "description": "Updated Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Updated implementation details",
            "testStrategy": "Updated test strategy"
          },
          // For update_status action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "status": "done"
            }
          ],
          // For delete action
          "removedTask": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For add_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Subtask Title",
                "description": "Subtask Description",
                "status": "pending",
                "details": "Subtask details",
                "dependencies": []
              }
            ]
          },
          // For remove_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": []
          },
          // For clear_subtasks action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy"
            }
          ],
          // For expand action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Generated Subtask 1",
                "description": "Description for Generated Subtask 1",
                "status": "pending",
                "details": "Details for Generated Subtask 1",
                "dependencies": []
              },
              {
                "id": "1.2",
                "title": "Generated Subtask 2",
                "description": "Description for Generated Subtask 2",
                "status": "pending",
                "details": "Details for Generated Subtask 2",
                "dependencies": ["1.1"]
              },
              {
                "id": "1.3",
                "title": "Generated Subtask 3",
                "description": "Description for Generated Subtask 3",
                "status": "pending",
                "details": "Details for Generated Subtask 3",
                "dependencies": ["1.2"]
              }
            ]
          },
          // For expand_all action
          "expandedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy",
              "subtasks": [
                {
                  "id": "1.1",
                  "title": "Generated Subtask 1",
                  "description": "Description for Generated Subtask 1",
                  "status": "pending",
                  "details": "Details for Generated Subtask 1",
                  "dependencies": []
                },
                {
                  "id": "1.2",
                  "title": "Generated Subtask 2",
                  "description": "Description for Generated Subtask 2",
                  "status": "pending",
                  "details": "Details for Generated Subtask 2",
                  "dependencies": ["1.1"]
                },
                {
                  "id": "1.3",
                  "title": "Generated Subtask 3",
                  "description": "Description for Generated Subtask 3",
                  "status": "pending",
                  "details": "Details for Generated Subtask 3",
                  "dependencies": ["1.2"]
                }
              ]
            }
          ]
        },
        "message": "Action-specific success message",
        "userCommunication": {
          "message": "User-friendly message about the action result"
        },
        "agentInstructions": "Instructions for the AI agent on how to proceed"
      }
    }
  ]
}

调用 apm_task_generate 工具时：

1. 参数验证：

   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证可选参数：file 和 output

2. 任务读取：

   • 从指定位置读取任务文件（如果未提供，默认为 artifacts.json）
   • 如果未找到任务文件或文件为空，则返回错误

3. 目录准备：

   • 确保输出目录存在（如有需要则创建）
   • 如果未指定输出目录，则使用默认的 artifacts 目录

4. 文件生成流程：

   • 针对任务数据中的每项任务：
     • 根据任务详情生成 Markdown 文件
     • 包含所有任务属性（标题、描述、状态、依赖项等）
     • 如果存在子任务，则将其格式化为嵌套章节
     • 根据任务 ID 使用一致的命名约定
   • 为每个任务文件创建结构清晰、易于阅读的格式

5. 响应格式：

   • 返回结构化的 JSON 响应，其中包含：
     • 成功状态
     • 已生成的任务文件数量
     • artifacts 目录的路径
     • 任务文件的路径
     • 成功消息
     • 上下文信息（时间戳、任务数量）

6. 错误处理：

   • 处理文件未找到错误
   • 处理目录创建错误
   • 处理文件写入错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_task_generate",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "output": "optional/path/to/output/directory"
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "success": true,
          "taskCount": 10,
          "artifactsDir": "/path/to/project/apm-artifacts",
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Generated 10 task files in /path/to/project/apm-artifacts",
        "context": {
          "timestamp": "2023-06-15T10:30:00Z",
          "taskCount": 10
        }
      }
    }
  ]
}

调用 apm_project_brief_create 工具时：

1. 参数验证：

   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证可选参数：sessionId、input、stage、response、exportFormat 和 maxTasks

2. 会话处理：

   • 如果未提供 sessionId，则启动新的访谈会话
   • 如果提供了 sessionId，则继续现有的访谈会话
   • 在多次交互中保持状态

3. 访谈流程：

   • 引导用户完成包含多个阶段的结构化访谈：
     • 项目概述：项目用途和范围的基本信息
     • 目标和利益相关方：项目目标及相关参与方
     • 约束条件：限制、要求和边界
     • 技术：技术栈和工具
     • 时间线和阶段：项目计划及主要里程碑
     • 功能：详细的功能需求
     • 审核：最终确认和调整
   • 根据先前的回答提出与上下文相关的问题
   • 处理用户回答，整理出全面的项目简介

4. 任务生成：

   • 访谈完成后，根据项目简介生成任务
   • 创建具有适当依赖关系的结构化任务层级
   • 按阶段和功能组织任务
   • 根据 maxTasks 参数限制任务数量
   • 将任务保存到 artifacts.json 文件

5. 响应格式：

   • 对于新会话：返回用于跟踪访谈流程的操作 ID
   • 对于继续进行的会话：返回下一个问题或任务生成确认信息
   • 提供用户沟通指南和建议回复
   • 提供明确的后续步骤和命令

6. 错误处理：

   • 处理验证错误
   • 处理文件未找到错误
   • 处理访谈处理错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_project_brief_create",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "sessionId": "optional-session-id-for-continuing-interviews",
    "input": "optional/path/to/existing/brief.json",
    "stage": "project_overview|goals_and_stakeholders|constraints|technologies|timeline_and_phases|features|review",
    "response": "Your answer to the current interview question",
    "exportFormat": "json|markdown|text",
    "maxTasks": 10
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "message": "Project brief interview started",
        "nextAction": "check_operation_status",
        "checkStatusCommand": "apm_project_brief_status --operationId=project-brief-123456",
        "metadata": {
          "userCommunication": {
            "message": "I'm starting the project brief interview process.",
            "expectationType": "immediate",
            "suggestedResponse": "I'll start the project brief interview process. I'll ask you a series of questions to gather information about your project. Let's begin with understanding your project overview."
          }
        }
      }
    }
  ]
}

调用 apm_project_brief_status 工具时：

1. 参数验证：

   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证 operationId 参数（必填，非空字符串）

2. 状态检索：

   • 从 AsyncOperationManager 获取操作状态
   • 如果未找到该操作，则返回错误
   • 提供有关操作当前状态的详细信息

3. 进度报告：

   • 返回当前进度百分比（0-100）
   • 提供描述当前阶段的消息
   • 包含创建、更新和完成时间戳（如适用）

4. 用户沟通指南：

   • 对于正在运行的操作，提供建议回复，方便向用户同步进度
   • 对于已完成的操作，建议后续步骤
   • 对于失败的操作，说明出错原因和后续处理方式

5. 响应格式：

   • 返回包含以下内容的结构化 JSON 响应：
     • 操作 ID
     • 当前状态（pending、running、completed、failed）
     • 进度百分比
     • 状态消息
     • 时间戳（创建、更新、完成）
     • 用户沟通指南

6. 错误处理：

   • 处理未找到操作的情况
   • 处理状态检索期间发生的内部错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_project_brief_status",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "operationId": "project-brief-123456"
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "status": "running",
        "progress": 65,
        "message": "Generating tasks",
        "createdAt": "2023-06-15T10:30:00Z",
        "updatedAt": "2023-06-15T10:30:05Z",
        "completedAt": null,
        "metadata": {
          "operationType": "task-generation",
          "userCommunication": {
            "message": "Task generation is in progress.",
            "expectationType": "long_wait",
            "estimatedTimeSeconds": 180,
            "suggestedResponse": "The task generation is in progress (65% complete).\n\nWhile we wait, here's what's happening behind the scenes:\n- The AI is analyzing your project requirements\n- It's identifying key components, features, and dependencies\n- It will create a structured task breakdown with proper sequencing\n- Tasks will be saved to the apm-artifacts directory, along with an overall project brief.\n\nYou can ask me to \"check status\" anytime if you'd like an update, or we can discuss other aspects of your project while we wait."
          }
        }
      }
    }
  ]
}

调用 apm_project_brief_result 工具时：

1. 参数验证：

   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证 operationId 参数（必填，且必须是非空字符串）

2. 结果检索：

   • 从 AsyncOperationManager 获取操作结果
   • 如果结果不可用（操作尚未完成或未找到），则返回错误
   • 如果操作失败，则返回错误

3. 结果处理：

   • 从操作结果中提取生成的任务
   • 包含已保存工件的文件路径
   • 提供会话信息，以便执行后续操作
   • 为用户提供后续步骤建议

4. 响应格式：

   • 返回结构化 JSON 响应，其中包含：
     • 操作 ID 和状态
     • 生成的任务及其标题、描述、优先级和详情
     • 已保存工件的文件路径（artifacts.json、项目简报 Markdown 文件）
     • 会话信息（sessionId、projectBriefUri、interviewStateUri）
     • 后续操作建议和命令
     • 用户沟通指南

5. 错误处理：

   • 处理未找到操作的情况
   • 处理操作仍在运行的情况
   • 处理操作失败的情况
   • 返回包含上下文信息的标准化错误响应

6. 用户指南：

   • 为用户提供清晰的后续步骤
   • 建议用于查看和管理生成任务的命令
   • 包含说明结果的用户友好消息

JSON-RPC 请求

{
  "method": "apm_project_brief_result",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "operationId": "project-brief-123456"
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "status": "completed",
        "message": "Task generation completed successfully",
        "tasks": [
          {
            "id": "1",
            "title": "Set up project infrastructure",
            "description": "Initialize the project repository and set up basic infrastructure",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Create the repository, set up CI/CD, and configure development environment"
          }
        ],
        "tasksPath": "/path/to/project/apm-artifacts/artifacts.json",
        "markdownPath": "/path/to/project/apm-artifacts/project-brief.md",
        "sessionId": "session-123456",
        "projectBriefUri": "resource://project-brief-123456",
        "interviewStateUri": "resource://interview-state-123456",
        "nextAction": "view_tasks",
        "suggestedCommand": "apm_get_tasks",
        "userCommunication": {
          "message": "I've successfully generated tasks based on your project brief. You can now view and manage these tasks using the task management tools.",
          "expectationType": "immediate",
          "suggestedResponse": "Great! I've generated a set of tasks based on your project requirements. These tasks have been saved to your project directory and are ready for you to work on. You can view them using the 'apm_get_tasks' command. Would you like to see the tasks now?"
        }
      }
    }
  ]
}

调用 apm_dependencies 工具时：

1. 参数验证：

   • 验证 action 参数（必填，必须是有效操作之一）
   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证特定操作的参数：
     • 对于 add 和 remove：验证 id 和 dependsOn 参数（必填，且不能为空字符串）
   • 验证可选参数：file

2. 任务检索：

   • 从指定位置读取任务文件（如果未提供，则默认为 apm-artifacts/artifacts.json）
   • 从文件中提取任务列表

3. 执行操作：

   • 根据 action 参数执行相应操作：
     • add：添加两个任务之间的依赖关系
     • remove：移除两个任务之间的依赖关系
     • validate：检查依赖项问题（循环引用、缺失依赖项）
     • fix：自动修复依赖项问题

4. 特定操作的处理：

   • 对于 add：
     • 查找将依赖其他任务的任务
     • 查找被依赖的任务
     • 检查依赖关系是否已存在
     • 如果依赖关系不存在，则添加
     • 验证依赖项，确保不存在循环引用
   • 对于 remove：
     • 查找依赖其他任务的任务
     • 检查依赖关系是否存在
     • 如果依赖关系存在，则移除
   • 对于 validate：
     • 检查循环依赖
     • 检查缺失依赖项
     • 返回验证结果
   • 对于 fix：
     • 移除缺失的依赖项以修复问题
     • 通过打破循环来修复循环依赖
     • 返回修复结果

5. 文件操作：

   • 在内存中更新任务数据
   • 将更新后的任务写回文件
   • 生成单个任务文件

6. 响应格式化：

   • 返回结构化的 JSON 响应，其中包含：
     • 特定操作的数据（任务、依赖任务、验证结果、修复结果）
     • 成功状态和消息
     • 操作的上下文信息
     • 时间戳和会话信息

7. 错误处理：

   • 处理验证错误（缺少必填字段、值无效）
   • 处理文件未找到错误
   • 处理任务未找到错误
   • 处理循环依赖错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_dependencies",
  "params": {
    "action": "add|remove|validate|fix",
    "projectRoot": "/absolute/path/to/project",
    // Action-specific parameters
    // For add and remove actions
    "id": "1",
    "dependsOn": "2",
    // Common optional parameters
    "file": "optional/path/to/artifacts.json"
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          // Action-specific response data
          // For add action
          "task": {
            "id": "1",
            "title": "Task 1",
            "description": "Description for Task 1",
            "status": "pending",
            "priority": "high",
            "dependencies": ["2"]
          },
          "dependencyTask": {
            "id": "2",
            "title": "Task 2",
            "description": "Description for Task 2",
            "status": "pending",
            "priority": "medium",
            "dependencies": []
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Added dependency: Task 1 now depends on task 2",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "taskId": "1",
            "dependsOn": "2",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

对于 validate 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "validationResults": {
            "circularDependencies": [
              {
                "taskId": "1",
                "path": ["1", "3", "2", "1"]
              }
            ],
            "missingDependencies": [
              {
                "taskId": "4",
                "missingDependencies": ["999"]
              }
            ],
            "valid": false
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Dependency issues detected",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "timestamp": "2023-06-15T10:30:00Z",
            "validationResults": {
              "circularDependencies": [
                {
                  "taskId": "1",
                  "path": ["1", "3", "2", "1"]
                }
              ],
              "missingDependencies": [
                {
                  "taskId": "4",
                  "missingDependencies": ["999"]
                }
              ],
              "valid": false
            }
          }
        }
      }
    }
  ]
}

对于 fix 操作：

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "fixResults": {
            "circularDependenciesFixed": [
              {
                "taskId": "2",
                "removedDependencies": ["1"]
              }
            ],
            "missingDependenciesFixed": [
              {
                "taskId": "4",
                "removedDependencies": ["999"]
              }
            ],
            "fixesApplied": true
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Dependency issues fixed",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "timestamp": "2023-06-15T10:30:00Z",
            "fixResults": {
              "circularDependenciesFixed": [
                {
                  "taskId": "2",
                  "removedDependencies": ["1"]
                }
              ],
              "missingDependenciesFixed": [
                {
                  "taskId": "4",
                  "removedDependencies": ["999"]
                }
              ],
              "fixesApplied": true
            }
          }
        }
      }
    }
  ]
}

调用 apm_complexity_node 工具时：

1. 参数验证：

   • 验证 projectRoot 参数（必填，必须是绝对路径）
   • 验证可选参数：file、output、markdownOutput、threshold、model 和 research
   • 为可选参数应用默认值：
     • output："apm-artifacts/resources/reports/task-complexity-report.json"
     • markdownOutput："apm-artifacts/resources/reports/task-complexity-report.md"
     • threshold：5（复杂度 ≥ 5 的任务将被建议拆分）
     • research：false（是否使用 Perplexity AI 进行基于研究的分析）

2. 获取任务：

   • 从指定位置读取任务文件（如果未提供，则默认为 artifacts.json）
   • 从文件中提取任务列表
   • 筛选任务，仅包含状态不是“done”且不是“cancelled”的任务
   • 跳过已有子任务的任务（因为这些任务已拆分）

3. 任务分析流程：

   • 对每项任务：
     • 计算基本复杂度因素：
       • 描述长度（0-0.2 分）
       • 详情长度（0-0.2 分）
       • 依赖项数量（0-0.2 分）
       • 优先级因素（高：0.2，中：0.1，低：0 分）
       • 技术术语数量（0-0.2 分）
     • 如果启用了 research，则使用 Perplexity AI 增强分析
     • 使用 Claude AI 按 1-10 的等级分析复杂度
     • 根据复杂度建议子任务数量
     • 生成拆分提示词和命令

4. 生成报告：

   • 创建复杂度报告，包含：
     • 特定任务的分析（ID、标题、复杂度评分、建议的子任务）
     • 用于拆分复杂任务的提示词
     • 执行任务拆分的命令
     • 元数据（生成时间戳、阈值、任务数量、平均复杂度）
   • 确保输出目录存在
   • 将 JSON 报告写入指定的输出路径
   • 将报告整理为易读的 Markdown 文档
   • 将 Markdown 报告写入指定的 Markdown 输出路径

5. 响应格式：

   • 返回结构化的 JSON 响应，包含：
     • 完整的复杂度报告数据
     • 格式化后的 Markdown 报告字符串
     • JSON 和 Markdown 报告的输出文件路径
     • 任务分析统计信息（已分析的任务数、发现的复杂任务数）
     • 与用户沟通的指导
     • 后续步骤的 Agent 指令

6. 错误处理：

   • 处理找不到文件的错误
   • 处理目录创建错误
   • 处理文件写入错误
   • 返回包含上下文信息的标准化错误响应

JSON-RPC 请求

{
  "method": "apm_complexity_node",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "output": "apm-artifacts/resources/reports/task-complexity-report.json",
    "markdownOutput": "apm-artifacts/resources/reports/task-complexity-report.md",
    "threshold": 5,
    "model": "optional-model-name",
    "research": false
  }
}

JSON-RPC 响应

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "report": {
            "tasks": [
              {
                "taskId": "15",
                "title": "Implement GraphQL API Integration",
                "complexity": 8,
                "recommendedSubtasks": 6,
                "expansionPrompt": "Break down the implementation...",
                "expansionCommand": "apm_task_modify_node --action=expand --id=15 --num=6"
              }
            ],
            "metadata": {
              "generated": "2025-04-24T14:40:04.508Z",
              "threshold": 5,
              "totalTasks": 4,
              "averageComplexity": 7
            }
          },
          "formattedReport": "# Task Complexity Analysis Report\n\n## Report Summary\n\n- **Generated:** 4/24/2025, 7:40:04 AM\n- **Complexity Threshold:** 5\n- **Total Tasks Analyzed:** 4\n- **Average Complexity:** 7.0\n\n## Task Analysis\n\n### 🔴 Task 15: Implement GraphQL API Integration\n\n- **Complexity Score:** **8/10 ⚠️\n- **Recommended Subtasks:** 6\n- **Action Required:** This task should be broken down into subtasks\n- **Expansion Command:** `apm_task_modify_node --action=expand --id=15 --num=6`\n\n**Expansion Guidance:**\nBreak down the implementation of the GraphQL API integration...\n\n---\n\n## Recommendations\n\nThe following tasks should be prioritized for breakdown:\n\n- Task 15: Implement GraphQL API Integration (Complexity: 8/10)\n",
          "jsonOutputPath": "/path/to/project/apm-artifacts/resources/reports/task-complexity-report.json",
          "markdownOutputPath": "/path/to/project/apm-artifacts/resources/reports/task-complexity-report.md",
          "tasksAnalyzed": 4,
          "complexTasks": 1
        },
        "message": "Analyzed 4 tasks and identified 1 complex task that should be broken down.",
        "userCommunication": {
          "message": "I've analyzed your project tasks and identified which ones might benefit from being broken down into subtasks. Here's the complexity report:\n\n# Task Complexity Analysis Report\n\n...",
          "expectationType": "immediate"
        },
        "agentInstructions": "The complexity analysis is complete. The report has been formatted for display and saved as both JSON and Markdown. You can suggest using 'apm_task_modify_node' with the 'expand' action for tasks with high complexity scores."
      }
    }
  ]
}