工作项
代理无法执行“改进应用”。它需要具体、范围明确且验收标准清晰的工作。工作项是将意图转化为可执行规格的方式。没有这种结构，代理只能临场发挥。有了它，代理能确切知道该做什么，以及何时完成。
工作项是 Almirant 的基本工作单位。它们代表需要规划、执行和完成的任何工作内容：从高级别史诗到具体的技术任务。
类型和层级
Almirant 将工作组织为四级层级：
Epic
└── Feature
└── Story
└── Task
| 类型 | 级别 | 用途 | 示例 |
|---|---|---|---|
| Epic | 1 | 高级别战略目标 | “完整认证系统” |
| Feature | 2 | 史诗内的具体功能 | “使用 Google OAuth 登录” |
| Story | 3 | 从用户视角出发的需求 | “作为用户，我希望使用 Google 账号登录” |
| Task | 4 | 可执行的技术工作单元 | “在后端实现 OAuth 回调” |
何时使用各类型
- Epic：当目标涵盖多个功能并需要数周或多个冲刺时。史诗是最高层级的规划单元。
- Feature：当你描述用户可感知的完整功能时。一个功能可以包含多个用户故事。
- Story：当你从用户视角描述具体需求时。用户故事通常在一个冲刺内完成。
- Task：当你描述具体且范围明确的技术操作时。任务是 AI 直接实施的层级。
父子关系
每个工作项都可以包含用于建立层级关系的 parentId。看板视图可以按父项对项目分组，从而便于在功能或史诗层级查看进度。
字段
| 字段 | 类型 | 描述 | 必填 |
|---|---|---|---|
title | string | 工作项的描述性标题 | 是 |
description | string | 详细描述，支持 Markdown | 否 |
type | enum | 类型：epic、feature、story、task | 是 |
priority | enum | 优先级：urgent、high、medium、low、none | 否 |
boardColumnId | uuid | 该项所在看板的列 | 是 |
parentId | uuid | 父工作项（用于层级关系） | 否 |
taskId | string | 自动生成的可读标识符（例如 A-T-37、MC-S-1） | 自动 |
dueDate | date | 交付截止日期 | 否 |
estimatedHours | number | 预计工作小时数 | 否 |
tags | array | 用于分类该项的标签 | 否 |
metadata | object | 丰富元数据（AI 上下文、技术备注） | 否 |
archived_at | timestamp | 归档日期（如已归档） | 否 |
可读标识符（taskId）
每个工作项都会根据项目和类型自动获得唯一且可读的标识符。示例：
A-T-37-- 项目 A 的第 37 个任务。MC-S-1-- 项目 MC 的第 1 个用户故事。A-E-3-- 项目 A 的第 3 个史诗。
该标识符在整个界面和 MCP 工具中使用，可在无需 UUID 的情况下引用项。
分配
一个工作项可以有多个受分配人，每个人具有特定角色：
| 角色 | 描述 |
|---|---|
| responsible | 负责完成该项的人员 |
| collaborator | 为工作作出贡献的人员 |
| reviewer | 负责审查结果的人员 |
同一个项可同时具有一名负责人、多个协作者和一名或多名审查者。
状态：从列推导
关键概念
工作项没有 status 字段。状态直接从该项所在看板的列推导得出：
- 如果列具有
in_progress语义角色，该项为“进行中”。 - 如果列具有
isDone = true，该项为“已完成”。 - 如果列具有
isDefault = true，新项会进入该列。
在列之间移动项会隐式改变其状态。
操作
创建工作项
创建工作项有多种方式：
- 从看板创建 -- 单击任意列的“+”按钮。该项会直接创建在该列中。
- 从列表视图创建 -- 使用“新建项”按钮，然后选择类型、看板和列。
- 通过 MCP 创建 -- 使用
create_work_item、create_task、create_story、create_feature或create_epic工具。
编辑工作项
- 内联编辑 -- 单击看板中某项的标题，直接编辑。
- 详情模态框 -- 单击卡片以打开完整详情，可在其中编辑所有字段。
- Markdown 描述 -- 描述字段支持完整 Markdown，且可借助 AI 格式化。
在列之间移动
- 拖放 -- 在 Kanban 视图中将卡片从一列拖至另一列。
- 通过 MCP -- 使用
move_work_item或batch_move_work_items工具，以编程方式移动一个或多个项。
将某项移至 isDone = true 的列时，该项被视为已完成。
分配和取消分配
在详情模态框中，选择用户及其角色（responsible、collaborator、reviewer）以添加或移除受分配人。
附件（attachments）
工作项支持存储在 S3 中的附件。可从详情模态框上传图片、文档、截图或任何相关文件。
归档
工作项不会被删除，而是被归档。归档会在 archived_at 中设置时间戳。已归档项不再显示于主视图中，但会保留供历史参考。
要归档某项：
- 打开工作项详情。
- 选择 归档。
- 该项会从看板中消失，但仍可在归档视图中查看。
详情视图
工作项详情视图包括：
- 所有可编辑字段（标题、描述、类型、优先级、受分配人、日期）。
- 事件历史记录 -- 该项所有变更的记录。
- AI 会话 -- AI 与该项交互的历史记录，包括每次会话的成本。
- 关联文档 -- 指向相关文档的链接。
- 依赖关系 -- 与其他工作项的依赖关系。
- 附件 -- 上传到该项的文件。
- 评论和备注。
批量操作
你可以从列表视图中选择多个项并执行批量操作：
- 移至另一列。
- 更改优先级。
- 分配给用户。
- 归档。
已保存视图和筛选器
工作项视图的筛选器会保存在 URL 中，因此可以共享已应用筛选器的链接。可按以下条件筛选：
- 类型（epic、feature、story、task）。
- 优先级。
- 受分配人。
- 标签。
- 列。
你还可以按父项对项目分组，以便在列表视图中查看层级。
AI 功能
工作项直接集成了 AI 功能：
- AI 文本格式化 -- AI 可以格式化并改进项的描述。
- 语音听写 -- 通过语音听写描述或评论，AI 会将其转录。
- Copy as prompt -- 将项的上下文复制为提示词，以便在 IDE 中使用。
- 带成本跟踪的 AI 会话 -- 每次与某项的 AI 交互都会记录其关联成本。
开发者指南
开发者指南
MCP 工具
创建
| 工具 | 描述 | 主要参数 |
|---|---|---|
create_work_item | 创建任意类型的工作项 | title, type, boardId, columnId, description, priority, parentId |
create_task | 创建任务的快捷方式 | title, boardId, description, priority, parentId |
create_story | 创建用户故事的快捷方式 | title, boardId, description, priority, parentId |
create_feature | 创建功能的快捷方式 | title, boardId, description, priority, parentId |
create_epic | 创建史诗的快捷方式 | title, boardId, description, priority |
查询
| 工具 | 描述 | 主要参数 |
|---|---|---|
list_work_items | 列出带筛选条件的工作项 | boardId, type, priority, assigneeId, parentId, columnId |
更新
| 工具 | 描述 | 主要参数 |
|---|---|---|
update_work_item | 更新工作项字段 | workItemId、要更新的字段 |
move_work_item | 将项移至另一列 | workItemId, columnId |
batch_move_work_items | 将多个项移至一个列 | workItemIds, columnId |
resolve_work_items | 将项标记为已解决（移至 done 列） | workItemIds |
complete_ai_task | 完成 AI 任务并将其移至 done | workItemId, summary |
示例：通过 MCP 创建任务
Tool: create_task
Parametros:
title: "Implementar endpoint de autenticacion"
boardId: "uuid-del-board"
description: "Crear el endpoint POST /api/auth/login con validacion JWT"
priority: "high"
parentId: "uuid-de-la-story-padre"
示例：批量移动项
Tool: batch_move_work_items
Parametros:
workItemIds: ["uuid-1", "uuid-2", "uuid-3"]
columnId: "uuid-columna-done"
示例：列出看板中已筛选的项
Tool: list_work_items
Parametros:
boardId: "uuid-del-board"
type: "task"
priority: "high"