task-management

任务管理

在 monday.com 看板上创建、更新、分配和管理条目。在 monday.com 中，看板上的每一行都是一个“条目”——它可以代表任务、交易、Bug、内容，或任何工作单元。本技能介绍 monday.com API 所要求的正确列值格式——这是通过编程方式使用该平台时最常见的错误来源。

重要前提

创建或更新任何条目之前，务必先调用 get_board_info，以获取看板的列定义。你需要了解：

• 列 ID（例如 status、date4、person）
• 列类型（例如 status、date、people）
• 状态标签映射（例如哪个索引对应“Done”）
• 下拉列的允许值

如果跳过此步骤，列值写入可能会静默失败或设置错误的值。

工作流：创建条目

第 1 步：查找目标看板

如果用户指定了看板名称：

1. 使用看板名称调用 search 查找看板
2. 如果有多个结果，请与用户确认匹配项

如果用户未指定：

1. 调用 get_user_context 列出其看板
2. 询问要使用哪个看板

第 2 步：获取看板结构

使用看板 ID 调用 get_board_info。注意：

• 所有列的 ID 和类型
• 分组 ID 和名称（用于确定条目的位置）
• 状态标签选项（确切的标签字符串，例如“Working on it”和“Done”）

第 3 步：获取列类型详情（如有需要）

如果需要了解某种列类型的确切格式，请使用该列类型调用 get_column_type_info。此调用会返回 JSON 架构和验证规则。

第 4 步：创建条目

调用 create_item，并提供：

• boardId：目标看板 ID
• groupId：要放置条目的分组（来自第 2 步）
• itemName：条目名称
• columnValues：包含列值的 JSON 字符串（见下方格式指南）

第 5 步：确认并跟进

创建后：

• 用通俗语言说明完成了什么——不要叙述 API 调用过程
• 提供条目名称、看板名称，以及 MCP 工具返回的直接 URL
• 建议 2–3 个合乎逻辑的后续步骤，例如：
  • “要我给它分配负责人吗？”
  • “要设置截止日期吗？”
  • “要我把它拆分成子条目吗？”
  • “要添加评论补充背景信息吗？”

工作流：更新条目

第 1 步：定位条目

如果用户提供了条目名称但没有提供 ID：

1. 调用 get_board_info 了解看板结构
2. 使用搜索查询调用 get_board_items_page 查找条目
3. 将返回的名称与用户指定的目标名称进行交叉核对。 get_board_items_page 的 searchTerm 会按相关性排序，而不是严格筛选名称——找不到真正匹配项时，它仍会返回条目，并按部分匹配程度排序。写入前，请检查返回列表，查找完全匹配（不区分大小写）或近似匹配的名称。如果返回的条目名称都与目标不匹配，则应视为未找到结果，并转到第 4 步，即使响应不为空。
4. 如果有多个匹配结果，请在写入前与用户确认匹配项
5. 如果没有条目名称匹配，切勿静默失败，也不要写入排名最靠前但名称错误的条目。请用户确认名称、提供你找到的最接近匹配项，或提出列出看板上的条目

第 2 步：获取看板结构

如果尚未调用，请调用 get_board_info。写入值之前，必须知道列 ID 和类型。

第 3 步：更新列值

调用 change_item_column_values，并提供：

• boardId：看板 ID
• itemId：条目 ID
• columnValues：仅包含要更改列的 JSON 字符串

第 4 步：确认

用通俗语言说明更改内容：条目名称、更新了哪些字段以及新值。务必包含直接 URL。不要描述调用了哪些 API 工具。

何时使用 MCP UI 小组件

默认使用纯文本确认。用户要求分配工作，且需要从较长的队友列表中选择时，使用 show-assign——该小组件会呈现一个可供用户交互的人员选择器。如果是分配给单个人，且用户已指定负责人，只需通过 list_users_and_teams 查找用户 ID，然后直接写入，无需使用小组件。

不要使用 show-table 来确认单个创建或更新操作——纯文本加上条目 URL 更简洁。

列值格式指南

create_item 和 change_item_column_values 的 columnValues 参数是一个 JSON 字符串。每种列类型都要求使用特定格式。格式错误是导致操作失败的首要原因。

如需查看包含所有列类型的完整格式参考，请参阅 references/column-value-formats.md。

以下是最常见类型的速查表：

状态 - 使用 {"label": "Done"}，其中标签字符串必须与 get_board_info 返回的完全一致：

{"status_column_id": {"label": "Done"}}

日期 - 使用 {"date": "YYYY-MM-DD"}：

{"date_column_id": {"date": "2025-06-15"}}

人员 - 使用 {"personsAndTeams": [{"id": USER_ID, "kind": "person"}]}：

{"person_column_id": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}}

文本 - 纯字符串值：

{"text_column_id": "Some text value"}

数字 - 仅包含数字的纯字符串：

{"numbers_column_id": "42"}

电子邮件 - 使用 {"email": "...", "text": "..."}：

{"email_column_id": {"email": "[email protected]", "text": "Contact"}}

电话 - 使用 {"phone": "...", "countryShortName": "..."}：

{"phone_column_id": {"phone": "+15551234567", "countryShortName": "US"}}

下拉菜单 - 使用 {"labels": ["Option 1", "Option 2"]}：

{"dropdown_column_id": {"labels": ["High Priority"]}}

时间线 - 使用 {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}：

{"timeline_column_id": {"from": "2025-06-01", "to": "2025-06-30"}}

链接 - 使用 {"url": "...", "text": "..."}；text 为必填项（如果没有标签，则重复填写 URL）：

{"link_column_id": {"url": "https://example.com", "text": "Example"}}

复选框 - 使用 {"checked": "true"}；取消勾选时使用 {"checked": "false"} 或 null。单独使用 true / false 会失败：

{"checkbox_column_id": {"checked": "true"}}

电子邮件、电话和链接不能使用纯字符串，否则会失败——请始终发送对象。

一次更新多个列

将多个列更新合并到一个 JSON 字符串中：

{
  "status": {"label": "Working on it"},
  "date4": {"date": "2025-06-15"},
  "person": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]},
  "text0": "Implementation notes here"
}

创建子项

要创建子项，请调用 create_item，并将 parentItemId 参数设为父项的 ID。子项会创建在父项的子项看板上。

注意：子项看板有自己的列结构。设置列值前，请对该子项看板调用 get_board_info，以获取列定义。

添加评论

要为某个条目添加评论或更新内容，请调用 create_update，并提供：

• itemId：条目 ID
• body：评论文本（支持基本 HTML：<b>、<i>、<a>、<ul>、<li>）

常见模式

标记为已完成： 从 get_board_info 获取看板的“已完成”状态标签，然后调用 change_item_column_values，并传入 {"status_column_id": {"label": "Done"}}。确认状态更改后，检查看板是否有匹配的终结分组（Done、Closed、Completed、Resolved、Fixed、Won、Lost、Archived），以及条目是否尚未位于其中。如果符合条件，将此操作作为下一步提供：“还要我把它移到 Done 分组吗？”不要自动移动——有些看板会有意让条目保留在原分组中，而不论其状态如何，所以务必先询问。

重新分配： 从 list_users_and_teams 获取新人员的用户 ID，然后使用人员列格式调用 change_item_column_values。

批量创建和更新： 使用 create_items（每次调用最多 20 个条目；每个条目可自行选择分组、父项或模板条目）和 update_items（每次调用最多更新 40 项，可跨看板）。每个条目会单独成功或失败，因此请读取每项结果，只重试失败的条目。对于单个条目，请使用 create_item / change_item_column_values。

移至分组： MCP 工具包没有直接的“移动条目”工具（move_object 用于看板 / 文件夹 / 概览，而非条目）。请使用 all_monday_api 和 move_item_to_group mutation：mutation { move_item_to_group (item_id: <ID>, group_id: "<GROUP_ID>") { id } }。不要用带 duplicateFromItemId 的 create_item 来移动条目——这会创建副本，并让原条目留在原处。

将条目复制到其他分组： 使用带 duplicateFromItemId 的 create_items 会忽略 groupId——副本始终会进入源条目所在的分组。请先复制，再用 move_item_to_group 移动每个副本。复制响应会将名称报告为 " (copy)"，即使已应用了新名称也是如此，因此在告知用户名称前，请先重新读取该条目。

智能默认值

用户未指定所有值时：

• 状态：默认使用第一个非已完成标签（通常是 "Not Started" 或 "Working on it"）——通过 get_board_info 检查看板标签的顺序。请在回复中说明采用了哪个默认值。
• 分组：按以下顺序选择分组。(1) 如果某个分组名称符合待办模式（不区分大小写：To Do、Todo、Backlog、New、Open、Not Started、Inbox、Lead、Triage），则使用该分组。(2) 否则，使用最靠前的非终结分组。终结分组是指名称符合已完成模式的分组（不区分大小写：Done、Closed、Completed、Complete、Verified、Resolved、Fixed、Won、Lost、Archived、Cancelled、Canceled）。(3) 如果所有分组都是终结分组，请询问用户要使用哪个分组，不要自行猜测。有些 monday 看板会在 API 返回结果中将 "Done" 作为第一个分组，因此不要盲目使用 groups[0]。务必说明使用了哪个分组，以便用户提出更改。
• 人员：如果已知用户身份，且看板有人员列，请询问是否要将其分配给该用户。未经询问，不要自动分配。

批量操作

在单次请求中创建或更新 5 个及以上条目时：

• 使用 create_items / update_items 批量处理，而不是每个条目单独调用一次
• 处理完所有条目后，提供数量摘要和看板链接
• 不要逐一列出每个条目；应说“已在 Marketing 看板上创建 12 个条目”，并附上看板 URL
• 如果有条目失败，请单独报告失败数量和原因

对于批量破坏性操作（3 次及以上可能难以撤销的更新），请在执行前向用户确认。

在尚无子项的看板上批量创建子项。 子项看板会在创建第一个子项时延迟创建；在看板创建之前发送批量请求，可能会间歇性地因缺少列而失败。先单独使用 create_item（带 parentItemId）创建第一个子项，再对该子项看板调用 get_board_info 以获取列 ID，然后使用 create_items 批量创建其余子项。

批量操作中的下拉菜单和状态标签。 复用 get_board_info 返回的现有标签字符串，确保完全一致。只有在用户确实需要新标签时，才设置 createLabelsIfMissing: true。对于下拉菜单列，批量请求中的每个条目都会创建一次新标签：如果 3 个条目都设置了 createLabelsIfMissing: true，并使用新标签“Beta”，该列上就会出现 3 个“Beta”标签。先创建一个使用新标签的条目，然后再批量处理其余条目，且不设置 createLabelsIfMissing（此时该标签已存在）。状态列不会以这种方式重复创建标签，但仍要确保每个条目中的新标签拼写完全相同。

错误预防与补救

1. 始终先调用 get_board_info ——切勿猜测列 ID 或状态标签
2. 使用完全一致的状态标签字符串 ——“Working on it”，而不是“working on it”（区分大小写）
3. 写入前检查列类型 ——status 列和 color 列使用不同格式
4. 将 columnValues 字符串化 ——该参数要求 JSON 字符串，而非 JSON 对象
5. 验证人员 ID ——分配人员前，使用 list_users_and_teams 获取有效的用户 ID。始终传入 name 参数（如果已知，则传入 userIds）以限定查询范围。不带参数调用 list_users_and_teams 会返回整个账户的用户列表，在大型租户中会超出令牌限制。如果用户提供了电子邮件地址，先按本地部分作为姓名搜索（例如，对 [email protected] 搜索“alex.po”）；如果没有匹配项，请让用户提供该人员的显示名称

MCP 调用失败时，不要直接转发原始错误。请诊断问题并提出解决方法：

• “此看板上找不到状态标签‘Done!’。看板使用的是‘Done’（没有感叹号）。要使用这个标签吗？”
• “人员 ID 12345 不属于你的账户。要我列出可选用户，供你选择正确的人吗？”
• “此看板的访问被拒绝——它是私密看板，且你尚未订阅。要我请所有者添加你，还是改选其他看板？”

写入工具失败，但读取正常。 如果工具列表中缺少写入工具（create_item、create_items、update_items、change_item_column_values、create_column、create_board），或者在刚刚成功读取的看板上调用这些工具时返回“Resource not found”、USER_UNAUTHORIZED 或 403，请原样重试一次。如果再次失败，请停止操作——不要循环重试，也不要对同一看板尝试其他写入工具。告知用户连接器会话已失去写入权限，请他们断开并重新连接 monday.com 连接器，并提出可通过 submit_bug_or_feature_request 提交反馈。

缺少预期看板，或工作区为空。 调用 get_user_context，并告知用户当前连接的账户。使用相同电子邮件地址登录多个 monday 账户的用户，通常会连错账户；重新连接并选择正确账户即可解决。

使用的工具

• get_user_context - 查找用户的看板
• search - 按名称查找看板
• get_board_info - 获取看板结构、列 ID、状态标签（写入前必须调用）
• get_column_type_info - 获取详细的列类型架构和验证规则
• get_board_items_page - 按名称或筛选条件查找项目
• create_item - 创建新项目或子项目
• create_items - 一次调用最多创建 20 个项目或子项目
• change_item_column_values - 更新现有项目的列值
• update_items - 一次调用最多更新 40 个项目，可跨看板
• create_update - 为项目添加评论
• all_monday_api - 在项目组之间移动项目时调用 move_item_to_group mutation
• list_users_and_teams - 查询人员列所需的用户 ID
• submit_bug_or_feature_request - 报告重试后仍持续失败的写入工具
• show-assign（按需）- 用户从多位团队成员中选择时显示人员选择器小组件

其他资源

• references/column-value-formats.md - monday.com 所有列类型的完整列值格式参考