工具 - 工作项

工作项是 Almirant 中工作的基本单位。它们可以是 task、story、feature、epic 或 idea 类型，并组织在看板列中。本节介绍可通过 MCP 创建、查询、更新和管理工作项的所有工具。

工作项状态

工作项没有显式的 status 字段。其状态由所在的看板列决定（例如 "Backlog"、"In Progress"、"Done"）。

查询

`list_work_items`

列出工作项，支持分页和可选筛选条件。如果 MCP 会话中配置了 projectId，则会自动按该项目筛选。

参数：

名称	类型	必填	描述
page	number	否	页码（默认值：1）
limit	number	否	每页项目数（默认值：50，最大值：100）
search	string	否	按标题或描述搜索
projectId	string (UUID)	否	按项目筛选（回退使用会话值）
boardId	string (UUID)	否	按看板筛选
boardColumnId	string (UUID)	否	按看板列筛选
parentId	string (UUID)	否	按父项筛选（功能或史诗的子项）
type	string	否	按类型筛选：`epic`、`feature`、`story`、`task`、`idea`
priority	string	否	按优先级筛选：`low`、`medium`、`high`、`urgent`
assignee	string	否	按负责人筛选

示例：

{
  "boardId": "b1234567-89ab-cdef-0123-456789abcdef",
  "type": "task",
  "priority": "high"
}

响应：

{
  "workItems": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implement OAuth authentication",
      "type": "task",
      "priority": "high",
      "assignee": "javier",
      "boardId": "b1234567-...",
      "boardColumnId": "col-003",
      "columnName": "In Progress",
      "parentId": "wi-feature-01",
      "projectId": "550e8400-..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

`resolve_work_items`

将工作项标识符（如 "A-T-37" 这样的可读任务 ID 或 UUID）解析为完整对象。可选择将非任务项递归展开为其叶子任务。

参数：

名称	类型	必填	描述
ids	string[]	是	混合标识符列表（如 `A-T-37`、`A-F-12` 等任务 ID 或 UUID）
includeLeafTasks	boolean	否	当为 `true`（默认值）时，递归将非任务项解析为叶子任务
maxDepth	number	否	最大递归深度（默认值：3，最大值：10）

示例：

{
  "ids": ["A-T-37", "A-F-12", "550e8400-e29b-41d4-a716-446655440000"],
  "includeLeafTasks": true
}

响应：

{
  "inputIds": ["A-T-37", "A-F-12", "550e8400-..."],
  "notFound": [],
  "items": [
    {
      "id": "wi-001",
      "taskId": "A-T-37",
      "title": "Implement login",
      "type": "task",
      "resolvedFrom": ["A-T-37"]
    },
    {
      "id": "wi-003",
      "taskId": "A-T-40",
      "title": "Validate tokens",
      "type": "task",
      "resolvedFrom": ["A-F-12"]
    }
  ]
}

`get_work_item_events`

获取工作项的事件历史记录（变更日志）。包括创建、更新、列移动、AI 会话和评论事件。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	工作项 ID
eventType	string	否	按类型筛选：`created`、`updated`、`moved`、`deleted`、`attachment_added`、`attachment_removed`、`ai_session`、`comment`
limit	number	否	最大事件数（默认值：50，最大值：200）

示例：

{
  "workItemId": "wi-001",
  "eventType": "moved",
  "limit": 20
}

响应：

{
  "workItemId": "wi-001",
  "taskId": "A-T-37",
  "title": "Implement login",
  "totalEvents": 3,
  "events": [
    {
      "eventType": "moved",
      "data": {
        "fromColumn": "To Do",
        "toColumn": "In Progress"
      },
      "createdAt": "2025-02-01T10:30:00.000Z"
    }
  ]
}

创建

`create_work_item`

创建工作项，并可完全控制看板、列、类型和项目。必须显式指定 boardId 和 boardColumnId。

参数：

名称	类型	必填	描述
title	string	是	工作项标题
description	string	否	详细描述
type	string	是	类型：`epic`、`feature`、`story`、`task`、`idea`
priority	string	否	优先级：`low`、`medium`、`high`、`urgent`
boardId	string (UUID)	是	将创建该项的看板
boardColumnId	string (UUID)	是	初始列
projectId	string (UUID)	否	项目（回退使用 MCP 会话值）
assignee	string	否	负责人的名称或标识符
parentId	string (UUID)	否	父工作项的 ID
metadata	object	否	任意元数据（例如 `{ definitionOfDone: "..." }`）

示例：

{
  "title": "Implement login endpoint",
  "description": "Create POST /api/auth/login endpoint with JWT validation",
  "type": "task",
  "priority": "high",
  "boardId": "b1234567-89ab-cdef-0123-456789abcdef",
  "boardColumnId": "col-001",
  "parentId": "wi-feature-01"
}

`create_task`

用于创建任务的快捷方式。强制使用 type=task，并自动选择项目的默认看板和 "Backlog" 列。要求在 MCP 会话中配置 projectId。

参数：

名称	类型	必填	描述
title	string	是	任务标题
description	string	否	详细描述
priority	string	否	优先级：`low`、`medium`、`high`、`urgent`
parentId	string (UUID)	否	父工作项的 ID
metadata	object	否	任意元数据

示例：

{
  "title": "Add email validation",
  "priority": "medium",
  "parentId": "wi-feature-01"
}

`create_story`

用于创建用户故事的快捷方式。强制使用 type=story，并自动选择看板和 "Backlog" 列。

参数：

名称	类型	必填	描述
title	string	是	用户故事标题
description	string	否	详细描述
priority	string	否	优先级：`low`、`medium`、`high`、`urgent`
parentId	string (UUID)	否	父功能的 ID
metadata	object	否	任意元数据

示例：

{
  "title": "As a user I want to sign in with Google",
  "priority": "high",
  "parentId": "wi-feature-01"
}

`create_feature`

用于创建功能的快捷方式。强制使用 type=feature，并自动选择看板和 "Backlog" 列。

参数：

名称	类型	必填	描述
title	string	是	功能标题
description	string	否	详细描述
priority	string	否	优先级：`low`、`medium`、`high`、`urgent`
parentId	string (UUID)	否	父史诗的 ID
metadata	object	否	任意元数据

示例：

{
  "title": "Authentication system",
  "description": "OAuth authentication with Google and email/password",
  "priority": "high"
}

`create_epic`

用于创建史诗的快捷方式。强制使用 type=epic，并自动选择看板和 "Backlog" 列。

参数：

名称	类型	必填	描述
title	string	是	史诗标题
description	string	否	详细描述
priority	string	否	优先级：`low`、`medium`、`high`、`urgent`
metadata	object	否	任意元数据

示例：

{
  "title": "Epic: Security and authentication",
  "description": "All authentication and authorization flows for the platform",
  "priority": "urgent"
}

更新和移动

`update_work_item`

更新现有工作项的字段。仅修改提供的字段。元数据会与现有值合并，而非覆盖。

参数：

名称	类型	必填	描述
id	string (UUID)	是	工作项 ID
title	string	否	新标题
description	string	否	新描述
type	string	否	新类型：`epic`、`feature`、`story`、`task`、`idea`
priority	string	否	新优先级：`low`、`medium`、`high`、`urgent`
assignee	string	否	新负责人
boardColumnId	string (UUID)	否	移动到另一列
parentId	string (UUID) 或 null	否	新父项（使用 `null` 取消关联）
metadata	object	否	要与现有值合并的元数据

示例：

{
  "id": "wi-001",
  "priority": "urgent",
  "metadata": {
    "definitionOfDone": "Unit tests + integration tests passing"
  }
}

`move_work_item`

将工作项移动到不同的看板列。根据目标列自动管理 AI 处理标志。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	要移动的工作项 ID
boardColumnId	string (UUID)	是	目标列的 ID
isAutoSync	boolean	否	当移动由级联同步导致时为 `true`（默认值：`false`）
setAiProcessing	boolean	否	无论目标列为何，均强制设置 `isAiProcessing=true`
aiProvider	string	否	AI 提供商（`openai`、`anthropic`）。与 `setAiProcessing` 结合使用时，会设置提供商元数据

示例：

{
  "workItemId": "wi-001",
  "boardColumnId": "col-003",
  "setAiProcessing": true,
  "aiProvider": "anthropic"
}

AI 标志自动行为

移动到 In Progress 时：自动启用 isAiProcessing=true
移动到 Review 或 Done 时：自动禁用 isAiProcessing=false
使用 setAiProcessing=true 时：无论列为何，均强制设置该标志

`batch_move_work_items`

通过单个操作将多个工作项移动到目标列。可选择为所有已移动项设置 AI 处理标志。

参数：

名称	类型	必填	描述
workItemIds	string[] (UUID)	是	要移动的工作项 ID 列表
boardColumnId	string (UUID)	是	目标列的 ID
setAiProcessing	boolean	否	为所有项启用 `isAiProcessing=true`
aiProvider	string	否	要记录到元数据中的 AI 提供商

示例：

{
  "workItemIds": ["wi-001", "wi-002", "wi-003"],
  "boardColumnId": "col-003",
  "setAiProcessing": true,
  "aiProvider": "anthropic"
}

响应：

{
  "movedCount": 3,
  "items": [ ... ],
  "note": "batch_move_work_items uses bulk update and does not run cascade/position logic"
}

`delete_work_item`

按 ID 永久删除工作项。

参数：

名称	类型	必填	描述
id	string (UUID)	是	要删除的工作项 ID

示例：

{
  "id": "wi-001"
}

响应：

{
  "deleted": true,
  "id": "wi-001"
}

实现提示词

`generate_work_item_prompt`

生成包含项目上下文（技术栈、仓库、同级任务、看板流转）的实现提示词。该提示词由 AI 生成，并保存在工作项的元数据中。

参数：

名称	类型	必填	描述
id	string (UUID)	是	工作项 ID

示例：

{
  "id": "wi-001"
}

响应：

{
  "prompt": "## Project context\n...\n## Task\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implement login",
    "type": "task",
    "projectName": "My Project",
    "siblingsCount": 4,
    "hasParent": true
  },
  "savedToDb": true
}

`get_work_item_prompt`

获取之前生成并存储在工作项元数据中的实现提示词。

参数：

名称	类型	必填	描述
id	string (UUID)	是	工作项 ID

示例：

{
  "id": "wi-001"
}

响应：

{
  "prompt": "## Project context\n...",
  "context": {
    "workItemId": "wi-001",
    "taskId": "A-T-37",
    "title": "Implement login",
    "type": "task"
  },
  "generatedAt": "2025-02-01T10:00:00.000Z"
}

审查和验证流程

`complete_review`

完成工作项的代码审查。如果审查通过，该项将移至 Testing；如果失败，则返回 In Progress。审查元数据存储在工作项中。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	工作项 ID
result	string	是	结果：`pass`（移至 Testing）或 `fail`（移至 In Progress）
summary	string	是	审查摘要
issues	string[]	否	发现的问题列表（当 `result=fail` 时相关）
reviewedFiles	string[]	否	已审查的文件列表

示例：

{
  "workItemId": "wi-001",
  "result": "pass",
  "summary": "Clean code, tests passing, meets definition of done",
  "reviewedFiles": ["src/auth/login.ts", "src/auth/login.test.ts"]
}

`complete_validation`

以原子方式完成任务验证：将通过的任务移至目标列（通常为 To Document），清除 AI 标志，合并文档和测试结果元数据，并记录 AI 会话。如果误传入 Validating 列，而看板中存在 To Document 列，该工具会重定向至 To Document。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	工作项 ID
toDocumentColumnId	string (UUID)	否	验证通过结果的目标列。优先使用看板的 `To Document` 列
validatingColumnId	string (UUID)	否	旧版目标别名。如果指向 `Validating`，该工具会尝试重定向到 `To Document`
documentation	object	否	文档元数据（参见下方子对象）
documentation.summary	string	否	已验证内容的摘要
documentation.screenshots	string[]	否	附加屏幕截图的 URL
documentation.mermaidDiagrams	string[]	否	Mermaid 图表字符串
documentation.changelogEntry	string	否	变更日志条目
testResults	object	否	测试结果（参见下方子对象）
testResults.passed	number	否	通过的测试数
testResults.failed	number	否	失败的测试数
testResults.testFiles	string[]	否	测试文件路径
model	string	是	使用的 AI 模型（例如 `claude-opus-4-6`）
provider	string	否	AI 提供商（默认值：`anthropic`）
totalTokens	number	是	消耗的令牌总数
durationMs	number	否	会话时长（毫秒）
taskId	string	否	可读的任务 ID（例如 `A-T-37`）

示例：

{
  "workItemId": "wi-001",
  "toDocumentColumnId": "col-to-document",
  "documentation": {
    "summary": "Google login verified end-to-end",
    "screenshots": ["/api/work-items/wi-001/attachments/local?key=screenshot.png"]
  },
  "testResults": {
    "passed": 12,
    "failed": 0,
    "testFiles": ["src/auth/__tests__/login.test.ts"]
  },
  "model": "claude-opus-4-6",
  "provider": "anthropic",
  "totalTokens": 45000,
  "durationMs": 120000
}

`complete_ai_task`

以原子方式完成任务上的 AI 工作：移至 Review，清除 AI 标志，设置 userActions，并记录令牌消耗的会话。无需再分别调用 move_work_item + update_work_item + record_ai_session。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	工作项 ID
reviewColumnId	string (UUID)	是	Review 列的 ID
userActions	string	否	用户应验证的手动步骤 Markdown 列表
model	string	是	使用的 AI 模型（例如 `claude-opus-4-6`）
provider	string	否	提供商（默认值：`openai`）
totalTokens	number	是	消耗的令牌总数
durationMs	number	否	会话时长（毫秒）
sessionType	string	否	会话类型（默认值：`implement`）
taskId	string	否	可读的任务 ID（例如 `A-T-37`）

示例：

{
  "workItemId": "wi-001",
  "reviewColumnId": "col-004",
  "userActions": "- Verify that login redirects to /dashboard\n- Check that the token is saved in cookies",
  "model": "claude-opus-4-6",
  "provider": "anthropic",
  "totalTokens": 85000,
  "durationMs": 300000,
  "taskId": "A-T-37"
}

响应：

{
  "completed": true,
  "workItemId": "wi-001",
  "movedTo": "Review",
  "sessionId": "session-uuid",
  "estimatedCost": "$0.1275",
  "totalTokens": 85000
}

推荐用法

完成任务的 AI 实现时，请使用 complete_ai_task。这是结束工作周期的最高效方式：一次工具调用即可移动项目、清除标志并记录成本。

附件

`upload_work_item_attachment`

从本地文件路径向工作项上传附件。专为 AI 工具设计（例如附加 Playwright 截图）。

参数：

名称	类型	必填	描述
workItemId	string (UUID)	是	工作项 ID
filePath	string	是	绝对路径或相对仓库路径（允许：`/tmp/*` 或工作目录下的路径）
fileName	string	否	要存储的文件名（默认值：路径的基本名称）
mimeType	string	否	MIME 类型（默认值：根据名称推断）
uploadedBy	string	否	上传者标签
metadata	object	否	附件元数据（例如 `{ kind: "review-screenshot", page: "/boards" }`）
deleteAfterUpload	boolean	否	上传后删除本地文件（默认值：`true`）

示例：

{
  "workItemId": "wi-001",
  "filePath": "/tmp/screenshot-login.png",
  "metadata": {
    "kind": "review-screenshot",
    "page": "/sign-in"
  }
}

高级上下文

`get_implement_context`

将标识符解析为待处理的叶子任务，按列状态分类，并包含看板映射、批次内依赖关系和预计算的执行波次。

参数：

名称	类型	必填	描述
ids	string[]	是	要实现的任务 ID/UUID 列表
projectId	string (UUID)	否	项目 ID（默认值：MCP 会话）

示例：

{
  "ids": ["A-T-37", "A-T-38", "A-F-12"]
}

`get_ideation_context`

获取构思上下文：按关键词查找相关工作项、潜在父项和动态看板配置。

参数：

名称	类型	必填	描述
keywords	string[]	是	搜索关键词
projectId	string (UUID)	否	项目 ID（默认值：MCP 会话）
limit	number	否	结果数量上限（默认值：20，最大值：50）

示例：

{
  "keywords": ["authentication", "OAuth", "login"]
}

`get_review_context`

获取任务或功能的完整审查上下文：项目详情、路由列、依赖关系、同级项和可审查的子项。

参数：

名称	类型	必填	描述
taskId	string	是	任务标识符（UUID 或如 `A-T-37` 的 taskId）
featureReview	boolean	否	当为 `true` 时，包含可用于功能/史诗审查的子项

示例：

{
  "taskId": "A-T-37",
  "featureReview": false
}

`get_validate_context`

将标识符解析为叶子任务，按看板列分类（Review 中可审查、Testing 中可测试，其他情况跳过），并包含带有 Validating 列的看板映射和父项摘要。

参数：

名称	类型	必填	描述
ids	string[]	是	要验证的任务 ID/UUID 列表
projectId	string (UUID)	否	项目 ID（默认值：MCP 会话）

示例：

{
  "ids": ["A-T-37", "A-T-38"]
}

查询​

list_work_items​

resolve_work_items​

get_work_item_events​

创建​

create_work_item​

create_task​

create_story​

create_feature​

create_epic​

更新和移动​

update_work_item​

move_work_item​

batch_move_work_items​

delete_work_item​

实现提示词​

generate_work_item_prompt​

get_work_item_prompt​

审查和验证流程​

complete_review​

complete_validation​

complete_ai_task​

附件​

upload_work_item_attachment​

高级上下文​

get_implement_context​

get_ideation_context​

get_review_context​

get_validate_context​

查询

`list_work_items`

`resolve_work_items`

`get_work_item_events`

创建

`create_work_item`

`create_task`

`create_story`

`create_feature`

`create_epic`

更新和移动

`update_work_item`

`move_work_item`

`batch_move_work_items`

`delete_work_item`

实现提示词

`generate_work_item_prompt`

`get_work_item_prompt`

审查和验证流程

`complete_review`

`complete_validation`

`complete_ai_task`

附件

`upload_work_item_attachment`

高级上下文

`get_implement_context`

`get_ideation_context`

`get_review_context`

`get_validate_context`