AgileHero
官方从你的智能体中运行敏捷工作空间：创建和移动卡片、梳理史诗、规划路线图、开展回顾会议、绘制白板并编写维基页面。
你可以用 AgileHero MCP 做什么？
-
通过 OAuth 连接 — 将
https://mcp.agilehero.io/mcp添加到任何 MCP 客户端，并使用您的 AgileHero 账户登录，无需 API 密钥。 -
跨项目搜索 — 让您的助手使用全局全文
search工具按内容查找卡片、史诗或维基页面。 -
管理卡片和史诗 — 通过 或 读取完整的卡片或史诗详情，包括描述、清单、标签和评论。
-
安全编辑维基页面 — 预览更改，然后使用返回的令牌应用更改。
-
创建和转换白板 — 使用 绘制图表，或将便签转换为待办事项。
-
运行回顾会议 — 使用 列出现有回顾，或创建新的回顾。
托管 MCP 服务器
npx add-mcp 'https://mcp.agilehero.io/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
AgileHero 内置了一个 MCP 服务器：只需将 URL 添加到任何支持 MCP 的 AI 助手中，使用您的 AgileHero 账户登录，它就能以您的权限操作您的项目——涵盖看板、待办事项、史诗、Wiki、白板、回顾和路线图等 49 个工具。本参考文档由服务器自身生成，因此始终是最新的。
初次使用？从 AI 代理概览 开始，或直接跳到下方的 连接您的客户端。此服务器上的所有富文本均为 AgileHero 标记语言 (AHM)——一种严格、经过验证的 XML 方言，专为让代理永不破坏人类内容而设计。想编写脚本而不是连接助手？REST API 参考 使用相同的 OAuth 登录方式。
连接您的 AI 客户端
连接意味着两件事：将端点 URL 添加到您的客户端，然后在客户端要求时使用您的 AgileHero 账户登录。无需创建或粘贴密钥。连接后，客户端以您的身份操作，拥有与您完全相同的权限；每个已连接的客户端都会列在应用中的 设置 → AI 客户端 下，您可以随时撤销其访问权限。观察者无法使用 MCP 服务器：您作为观察者的工作区不会列出，其中的所有内容都会显示为未找到。
端点
https://mcp.agilehero.io/mcp
传输方式
Streamable HTTP (POST)
登录
您的 AI 客户端会打开浏览器窗口；批准一次，随时可在设置 → AI 客户端中撤销。
Claude Code
在终端中运行一次；Claude Code 会将服务器存储在您的用户级配置中，并通过浏览器完成登录。
claude mcp add --transport http --scope user agilehero https://mcp.agilehero.io/mcp
- 所有标志必须位于服务器名称之前。
- 然后在 Claude Code 会话中运行
/mcp并选择 Authenticate（或运行claude mcp login agilehero），并在浏览器中批准登录。
验证： 运行 claude mcp list — agilehero 应显示为已连接。如果显示“需要身份验证”，请运行 claude mcp login agilehero。
Claude Code 文档 · 已于 2026-09-15 对照供应商文档验证
VS Code (GitHub Copilot)
在工作区中添加 .vscode/mcp.json，或运行“MCP: Open User Configuration”以应用于所有工作区。服务器首次启动时会打开浏览器窗口进行登录。
.vscode/mcp.json
{
"servers": {
"agilehero": {
"type": "http",
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- “type”: “http” 是必需的——缺少它，VS Code 会将 URL 视为要运行的命令。
验证： 运行“MCP: List Servers”，启动 agilehero，在浏览器中完成登录，并检查其工具是否出现在 Chat 视图中。
VS Code (GitHub Copilot) 文档 · 已于 2026-09-15 对照供应商文档验证
Codex
从终端添加，然后登录——该配置由 Codex CLI、IDE 扩展和 ChatGPT 桌面应用共享。
codex mcp add agilehero --url https://mcp.agilehero.io/mcp
codex mcp login agilehero
- Codex 不会自行启动登录——添加服务器后请运行
codex mcp login agilehero。
验证： 运行 codex mcp list — agilehero 应显示为已认证；然后让 Codex 列出您的 AgileHero 项目。
Codex 文档 · 已于 2026-09-15 对照供应商文档验证
Zed
添加到 settings.json，或使用 设置 → AI → MCP 服务器 → 添加远程服务器；Zed 会提示您登录。
~/.config/zed/settings.json
{
"context_servers": {
"agilehero": {
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- 省略 headers——Zed 仅在未配置 Authorization 头时才启动登录。
验证： 重启 Zed，在浏览器中按提示批准登录，然后让它列出您的 AgileHero 项目——首次成功调用即确认连接。
Zed 文档 · 已于 2026-09-15 对照供应商文档验证
GitHub Copilot CLI
添加到 ~/.copilot/mcp-config.json，或仓库内的 .mcp.json。
~/.copilot/mcp-config.json
{
"mcpServers": {
"agilehero": {
"type": "http",
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- 需要 GitHub Copilot CLI 1.0.83 或更高版本（支持 Client ID Metadata Document）。
- Copilot CLI 会在服务器首次请求时打开登录；您也可以在会话中运行
/mcp auth agilehero。
验证： 在 Copilot CLI 中运行 /mcp — agilehero 应显示为已连接并带有其工具。
GitHub Copilot CLI 文档 · 已于 2026-09-15 对照供应商文档验证
Claude（网页、桌面、Cowork）
将 AgileHero 添加为自定义连接器并登录；该连接器可在 Claude 网页版、Claude Desktop、Cowork 和移动应用中使用。
Settings → Connectors → Add custom connector
Name: AgileHero
URL: https://mcp.agilehero.io/mcp
Sign in now
- 当 Claude Code 使用同一 Claude 账户登录时，该连接器也会出现在其中。
- 免费计划：一个自定义连接器。团队和企业版：由所有者添加连接器，每位成员使用自己的 AgileHero 账户登录。
验证： 开始新聊天——AgileHero 会列在连接器下，让 Claude 列出您的 AgileHero 项目即可正常工作。
Claude（网页、桌面、Cowork）文档 · 已于 2026-09-15 对照供应商文档验证
ChatGPT
在开发者模式下创建连接器并使用 OAuth 登录。
Settings → Connectors → Create (Developer mode)
Name: AgileHero
MCP server URL: https://mcp.agilehero.io/mcp
Authentication: OAuth
- 适用于启用开发者模式的 Plus、Pro、Business、Enterprise 和 Edu 计划；在工作区中，管理员或所有者可为成员发布连接器。
验证： 启用 AgileHero 连接器打开新聊天，并让 ChatGPT 列出您的 AgileHero 项目。
ChatGPT 文档 · 已于 2026-09-15 对照供应商文档验证
其他客户端
任何支持带 Client ID Metadata Document 的 OAuth 的 MCP 客户端：将端点添加为远程（Streamable HTTP）服务器，并在浏览器中批准登录。
Transport: Streamable HTTP
URL: https://mcp.agilehero.io/mcp
Authentication: OAuth (sign in when the client asks)
- 仅支持静态令牌或头的客户端无法连接——AgileHero 仅使用 OAuth 登录。
验证： 重启客户端，在浏览器中按提示批准登录，然后让它列出您的 AgileHero 项目——首次成功调用即确认连接。
其他客户端文档 · 已于 2026-09-15 对照供应商文档验证
尚不支持
这些客户端尚无法登录 AgileHero。其中大多数缺乏对 Client ID Metadata Documents 的支持，即 AgileHero 使用的 OAuth 客户端注册方法（当前 MCP 推荐）；我们会定期重新检查供应商文档，一旦符合条件便会将客户端升级。
Cursor尚未支持
Cursor 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Cursor 文档 · 已于 2026-09-15 对照供应商文档验证
OpenCode尚未支持
OpenCode 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
OpenCode 文档 · 已于 2026-09-15 对照供应商文档验证
Gemini CLI尚未支持
Gemini CLI 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Gemini CLI 文档 · 已于 2026-09-15 对照供应商文档验证
Cline尚未支持
Cline 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Cline 文档 · 已于 2026-09-15 对照供应商文档验证
Google Antigravity尚未支持
Google Antigravity 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Google Antigravity 文档 · 已于 2026-09-15 对照供应商文档验证
Amp尚未支持
Amp 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Amp 文档 · 已于 2026-09-15 对照供应商文档验证
Raycast AI尚未支持
Raycast AI 尚不支持 Client ID Metadata Documents（其 OAuth 登录需要 Dynamic Client Registration 或预注册客户端），因此目前无法连接 AgileHero。
Raycast AI 文档 · 已于 2026-09-15 对照供应商文档验证
Kiro尚未支持
Kiro 使用您提供的 Client ID Metadata Document URL 登录，而 AgileHero 尚未为其托管 Client ID Metadata Document。
Kiro 文档 · 已于 2026-09-15 对照供应商文档验证
Warp尚未支持
Warp 尚不支持用户添加服务器的 OAuth 登录，因此目前无法连接 AgileHero。
Warp 文档 · 已于 2026-09-15 对照供应商文档验证
JetBrains AI Assistant尚未支持
JetBrains AI Assistant 不支持远程服务器的 OAuth 登录，且 mcp-remote 桥接需要托管的客户端文档——AgileHero 尚未为其托管 Client ID Metadata Document。
JetBrains AI Assistant 文档 · 已于 2026-09-15 对照供应商文档验证
Continue尚未支持
Continue 不支持 Streamable HTTP 服务器的 OAuth 登录，且 mcp-remote 桥接需要托管的客户端文档——AgileHero 尚未为其托管 Client ID Metadata Document。
Continue 文档 · 已于 2026-09-15 对照供应商文档验证
服务器说明
每个 MCP 客户端在初始化时都会收到以下约定：
AgileHero MCP 服务器。
每个 id 参数和响应中的每个 id 都是短 uid——始终使用 list/get/search 工具返回的 uid，切勿自行编造。大多数工具需要项目 uid——请先调用 list_projects 以发现工作区和项目。优先使用 search（全文搜索，涵盖所有内容类型）而非 search_cards（标题子串搜索，单个项目）。
对于更新工具，集合字段请优先使用 add_*/remove_* 增量字段（增量式、安全）；普通集合字段（assigned_to、labels、checklists、cards_relations、links、attachments）会替换先前状态，且不能与其增量字段组合使用。清单项格式为 { description, checked }。使用 list_cards / list_epics 上的 updated_since 来获取变更。
使用 move_card（而非 update_card）来更改卡片的列表或位置；空的 list_id 表示待办事项。
Wiki、白板、回顾和路线图工具要求项目所在工作区为 Pro 或试用计划。白板元素写入为批量工具，且为全有或全无；元素 uid 来自 get_whiteboard。回顾项使用 add_retro_items 和 move_retro_item 管理（move_card 会拒绝回顾卡片）。
每日限制：工具调用按用户按工作区计量——免费计划每天 500 次，Pro 或试用计划每天 5,000 次，UTC 时间 00:00 重置。get_ahm_spec 和 list_projects 不计入限制（任何无法归属于单个工作区的调用也不计入，如无范围搜索）。超出限制后，工具将返回每日限制错误，直到重置或升级。
所有富文本（Wiki 页面、卡片/史诗描述、评论）均为 AgileHero 标记语言 (AHM)——严格 XML，绝非 markdown 或 HTML；在编写任何内容前请先调用一次 get_ahm_spec。富文本编辑按设计分为两步：preview_wiki_page_update / preview_description_update（后果 + preview_token），然后使用匹配的更新工具并携带该令牌。
完整工具文档：https://agilehero.io/docs/mcp
AHM 规范：https://agilehero.io/docs/mcp/agilehero-markup
工具（49 个）
list_projects只读
列出令牌用户可访问的每个工作区和项目，以便代理解析大多数其他工具所需的项目 uid。在不知道项目 uid 时请首先调用此工具——切勿要求用户粘贴 uid。返回工作区（uid、名称、计划、您的角色）及其项目（uid、名称、url）。Pro 支柱工具（wiki、metrics）需要工作区计划为 pro 或试用。
search只读
该产品的全局全文搜索（OpenSearch）：卡片、史诗、维基页面和项目，匹配标题、描述、评论、清单项和附件文件名，按相关度排序并带有近期加权。使用此功能可按内容查找任何内容（“我们讨论迁移的那张卡片”）；search_cards 仅用于在单个项目内进行标题子字符串查找。每个结果都带有类型、可操作的 uid（卡片用于 get_card/update_card，史诗用于 get_epic，wiki_pages 用于 show_wiki_page，项目用于 project_id 参数）、深层链接 url，以及 <mark> 高亮的片段，显示匹配原因。可选地使用 project_id 或 assigned_to_me 限定范围。使用 page/per_page 分页；total_count 是完整匹配数。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| query | string | 是 | 自由文本搜索查询 |
| project_id | string | 可选的项目 uid，用于限定搜索范围 | |
| assigned_to_me | boolean | 仅返回分配给令牌用户的结果 | |
| page | integer | 页码（默认 1） | |
| per_page | integer | 每页结果数，1-50（默认 20） |
get_card只读
完整读取一张卡片：其 AgileHero Markup 描述（含块 id）及 description_version（preview_description_update / update_description 这两个输入所接受的），列表位置、史诗、标签、指派者、报告者、类型、估算、截止日期、清单、链接、附件、相关卡片和线程评论。仅接受卡片 uid——没有 project_id 参数。卡片 uid 来自 list_cards、search 或 search_cards。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 卡片的唯一标识符 |
get_epic只读
完整读取一个史诗：其 AgileHero Markup 描述（含块 id）及 description_version（preview_description_update / update_description 这两个输入所接受的）、名称、编号、颜色、开始/结束日期、指派者、清单、链接、附件、其上的每张卡片（uid、编号、标题及其列表及类别——null 列表 = 待办——按看板顺序排列，因此这是列出史诗所有卡片并查看哪些是待办、进行中或已完成的方式）以及线程评论。仅接受史诗 uid——没有 project_id 参数。史诗 uid 来自 list_epics 或 search。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 史诗的唯一标识符 |
list_wiki_pathsPro · wiki只读
按显示顺序列出项目的整个 wiki 树——每个文件夹和页面及其 uid、名称、类型（页面或文件夹）和 parent_id——以便代理可以解析 show_wiki_page 接受的页面 uid，并为 create_wiki_page 选择 parent_id。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
show_wiki_pagePro · wiki只读
以 AgileHero Markup (AHM) 格式检索 wiki 页面及其 document_version。内容是 AHM，而非 markdown——块 id、<discussion> 锚点和 <image/>/<attachment/> 引用是文档的一部分；编辑前请阅读 get_ahm_spec。通过 preview_wiki_page_update 然后 update_wiki_page 进行编辑，使用此处返回的块 id 和 document_version。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 页面路径的唯一标识符 |
get_ahm_spec只读
AgileHero Markup (AHM) v1.0 规范——AgileHero 接受的唯一富文本格式（markdown 和 HTML 均被拒绝）。在编写或编辑任何富文本（wiki 页面、卡片/史诗描述、评论）之前，请阅读此规范一次：词汇、属性、转义规则和一个工作示例。网页上的相同文本：https://agilehero.io/docs/mcp/agilehero-markup
create_wiki_pagePro · wiki
使用 AgileHero Markup (AHM) 内容创建 wiki 页面（可选地在文件夹内）。内容必须包裹在 <agile-hero-markup version="1.0"> 中——markdown 和 HTML 均被拒绝；请先阅读 get_ahm_spec。返回新页面的 uid、url、document_version 和内容。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
| name | string | 是 | 页面标题 |
| parent_id | string | 可选的文件夹 uid（来自 list_wiki_paths） | |
| content | string | 页面正文为 AHM；省略则创建空页面 |
preview_wiki_page_updatePro · wiki只读
每次 wiki 页面更新的必需第一步：验证操作并返回服务器计算的结果（添加/删除/更改的块、将被永久删除的文件、将失去锚点的团队讨论、可能的 markdown 警告）以及 update_wiki_page 所需的 preview_token。不修改任何内容。操作按块寻址（replace_block / insert_after / delete_block / move_block），内容为 AHM——请先阅读 get_ahm_spec，并从 show_wiki_page 获取块 id 和 document_version。保存前请审查结果：列出的文件删除或讨论取消锚点仅在用户要求时才可接受。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 页面路径 uid |
| document_version | string | 是 | 来自 show_wiki_page——证明新鲜度 |
| operations | array of object | 是 | 按顺序应用于不断演变的文档 |
update_wiki_pagePro · wiki破坏性
将先前预览的更新应用于 wiki 页面。需要 preview_wiki_page_update 中的 preview_token，用于确切这些操作和此 document_version——设计上无法不预览就保存。每次保存都会创建一个页面版本，用户可在应用中回滚。返回更新后的页面（AHM + 新 document_version）和已应用的结果。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 页面路径 uid |
| document_version | string | 是 | 预览所基于的版本 |
| operations | array of object | 是 | 已预览的确切操作 |
| preview_token | string | 是 | 来自 preview_wiki_page_update |
preview_description_update只读
每次卡片或史诗描述编辑的必需第一步：验证块操作并返回服务器计算的结果以及 update_description 所需的 preview_token。不修改任何内容。内容为 AgileHero Markup（AHM，描述表面：无表格、颜色、对齐、讨论或文件附件）——请先阅读 get_ahm_spec；块 id 和 document_version 来自 get_card / get_epic。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| resource_type | enum: card | epic | 是 | |
| id | string | 是 | 卡片或史诗 uid |
| document_version | string | 是 | 来自 get_card / get_epic |
| operations | array of object | 是 | 按顺序应用于不断演变的描述 |
update_description破坏性
将先前预览的描述更新应用于卡片或史诗。需要 preview_description_update 中的 preview_token，用于确切这些操作和此 document_version——设计上无法不预览就保存。返回更新后的描述（AHM + 新 document_version）。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| resource_type | enum: card | epic | 是 | |
| id | string | 是 | 卡片或史诗 uid |
| document_version | string | 是 | 预览所基于的版本 |
| operations | array of object | 是 | 已预览的确切操作 |
| preview_token | string | 是 | 来自 preview_description_update |
list_whiteboardsPro · whiteboard只读
列出项目的白板（uid、名称、元素数量、url）。使用 get_whiteboard 读取看板的元素。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
create_whiteboardPro · whiteboard
在项目上创建空白白板。使用 create_whiteboard_elements 添加内容。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
| name | string | 是 | 白板名称 |
get_whiteboardPro · whiteboard只读
将白板读取为紧凑的文本表示：看板边界加上每个元素一行——“<type> <uid> 位于 <x>,<y> 大小 <w>x<h> [颜色] [父级 <frame-uid>] [链接 <card|epic> <uid>] \"文本\"”，连接器为“连接器 <uid> <from> -> <to>”。此处的元素 uid 是每个白板写入工具所接受的句柄。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 白板的唯一标识符 |
create_whiteboard_elementsPro · whiteboard
在一次事务性调用中创建最多 100 个白板元素（全有或全无，一个实时事件）。原生大小、颜色和文本位置由服务器端应用——通常只需提供类型 + 文本（+ 颜色）。省略 x/y 则元素自动排列（默认网格；arrange: row|column|grid，origin_x/origin_y/gap 用于调整）；提供 x/y 可完全控制。框架通过 parent_id（现有框架 uid）或 parent_ref（本次调用中较早框架的 ref）包含元素。连接器通过 uid（source_id/target_id）或批次 ref（source_ref/target_ref）绑定元素——绝不使用坐标；锚点由 UI 计算。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一标识符 |
| elements | array of object | 是 | 按数组顺序创建——refs 仅向后解析 |
| arrange | enum: grid | row | column | 无显式 x/y 的元素的布局（默认 grid） | |
| origin_x | number | 自动排列起始 x（默认 100） | |
| origin_y | number | 自动排列起始 y（默认 100） | |
| gap | number | 自动排列间距，以 px 为单位（默认 20） |
create_whiteboard_diagramPro · whiteboard
从语义图在白板上绘制图表（流程图、流程、依赖图）——节点、边、可选组，无坐标：服务器执行分层自上而下的布局，使用原生大小，并返回按您的节点 id 键控的已创建元素 uid。放置在现有看板内容下方。事务性（全有或全无，一个实时事件）。最多 20 个节点——将较大的流程拆分为两个图表。保持形状简单（矩形），除非语义需要（菱形 = 决策，跑道形 = 开始/结束，圆柱形 = 数据存储）。使用 update_whiteboard_elements 编辑结果——布局不会再次运行。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一标识符 |
| title | string | 图表标题（框架标题，或使用组时的标题） | |
| nodes | array of object | 是 | |
| edges | array of object | ||
| groups | array of object | ||
| origin_x | number | 可选的左上角 x；默认在现有内容下方 | |
| origin_y | number | 可选的左上角 y；默认在现有内容下方 |
update_whiteboard_elementsPro · whiteboard
Update 最多 100 个白板元素，一次调用全有或全无：移动（x/y）、调整大小、重新分层（z_index）、修改文本、重新着色、重新设置父级（parent_id — 一个框架 uid，或 "" 以解除关联），以及连接器的箭头/路径/标签。元素 uid 来自 get_whiteboard；元素类型不能更改。仅更改提供的字段 — 不相关的属性会被保留。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一标识符 |
| updates | array of object | 是 |
delete_whiteboard_elementsPro · whiteboarddestructive
在一个事务性调用中删除最多 100 个白板元素。删除框架或思维导图节点会将其子元素释放到画布上（它们不会被删除 — 如需一并删除，请显式包含它们的 uid）。连接到已删除元素的连接器不会被移除，并会悬空。元素 uid 来自 get_whiteboard。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一标识符 |
| ids | array of string | 是 | 要删除的元素 uid |
review_whiteboardPro · whiteboardread-only
对白板运行确定性质量检查：可能溢出其元素的文本、明显重叠的元素、具有未绑定或悬空端点的连接器、UI 调色板之外的颜色、偏离网格的位置，以及其父级已被删除的元素。仅供参考 — 发现结果是建议，而非错误，带有发现结果的白板可能正是用户想要的。在绘制后使用以进行合理性检查，最多修复一次，不要为了追求空报告而循环。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 白板的唯一标识符 |
convert_whiteboard_elementPro · whiteboard
将白板元素转换为积压工作项：将便签转换为卡片或史诗，或将框架转换为史诗（框架的便签子元素成为该史诗上的卡片；已转换的子元素会被重新分配，而不是复制）。该元素保留在画布上，并链接到其转换后的内容 — get_whiteboard 会显示该链接。一个元素只能转换一次。便签/框架文本成为标题，除非您传入一个。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 元素 uid（一个 sticky_note 或 frame，来自 get_whiteboard） |
| to | enum: card | epic | 是 | 要创建的内容 |
| title | string | 卡片标题 / 史诗名称；默认为元素的文本 | |
| list_id | string | 仅卡片：目标列表 uid；省略则放入积压工作 | |
| color | string | 仅史诗：十六进制颜色；默认为元素的颜色 |
convert_mind_mapPro · whiteboard
将思维导图转换为积压工作项，并带有逐节点映射：根节点可以成为新的史诗（角色 "epic"）或附加到现有的史诗（角色 "existing_epic" + target_epic_id）；其他节点成为该史诗上的卡片（角色 "card"）或项目标签（角色 "label" — 树中卡片节点上方的标签节点将应用于该卡片）；角色 "skip" 忽略某个节点。将 ROOT 元素 uid 作为 id 传入，并将每个要转换的节点放入 nodes（未列出的节点将被忽略）。每个节点只能转换一次：已转换的节点会预先被拒绝 — 请在不包含它们的情况下重新提交。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | ROOT 思维导图节点 uid（来自 get_whiteboard） |
| nodes | array of object | 是 | |
| target_epic_id | string | 史诗 uid，当根节点角色为 "existing_epic" 时必填 |
list_retrospectivesPro · retrospectivesread-only
列出项目的回顾：工作区支持时列出新模型回顾和健康检查，否则列出经典回顾板。新模型条目具有 uid、名称、类型（retro | health_check）、状态（open | live | closed）、日期（starts_on；健康检查为 closes_on）、当前阶段、模板、引导者 uid、其创建的操作数量以及 url；响应还会添加项目的 open_actions_count。使用 get_retrospective 获取完整信息。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
create_retrospectivePro · retrospectives
创建回顾：工作区支持时创建新模型回顾，否则创建经典回顾板；响应为 get_retrospective 返回的回顾（包含其列及其 uid），因此 add_retro_items 可以立即跟进。新模型回顾来自模板（默认 went_well），立即可用于记录笔记，并且您为引导者；可选：焦点、匿名性（默认：模板的）、participant_ids（一个“选定成员”回顾；省略则默认为所有具有写入权限的项目成员）、check_in 和反馈问题类型，以及投票。引导者在应用中启动它并运行其阶段。经典板仅接受名称、日期和 previous_retrospective_id，并拒绝新模型参数。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
| name | string | 是 | 回顾名称 |
| template | enum: went_well | start_stop_continue | four_ls | mad_sad_glad | kalm | daki | starfish | plus_delta | sailboat | rose_thorn_bud | wrap | hot_air_balloon | three_pigs | project_retro | postmortem | kudos_lessons | 模板键；默认 went_well | |
| starts_on | string | 日期，ISO-8601（YYYY-MM-DD）；默认为今天 | |
| starts_at | string | starts_on 的已弃用别名 | |
| focus | string | 此回顾的主题，显示在其名称下方 | |
| anonymity | enum: anonymous | optional | named | 谁显示在笔记上：anonymous、optional（作者可以添加其姓名）或 named | |
| participant_ids | array of string | 参与者的用户 uid（list_project_users）；您始终是其中之一 | |
| check_in | enum: safety | mood | esvp | one_word | 签到问题（默认 safety） | |
| feedback | enum: roti | pulse | one_word | 结束反馈问题（默认 roti） | |
| votes | object | 投票设置：budget（auto | fixed | unlimited）、per_person（1-20）、max_per_topic（1-10） | |
| previous_retrospective_id | string | 仅经典板：较早回顾的 uid，其“操作”列显示为“过去的操作” |
get_retrospectivePro · retrospectivesread-only
按您可能看到的方式读取回顾：工作区支持时读取新模型回顾或健康检查，否则读取经典回顾板。新模型回顾返回设置、阶段（当前阶段、计时器、进度）、包含主题（笔记组，带 uid）的列（带 uid）、签到和反馈统计、您剩余的投票、讨论队列和暂存主题、提案、操作（其创建的操作以及项目的未结操作）以及（一旦关闭）其摘要。隐私遵循房间规则：在揭示之前，您只能看到自己的笔记（每列统计每个人的数量）、仅命名笔记上的作者、仅在投票揭示后才显示投票总数。健康检查返回其维度和参与情况、开放时您自己的评分，以及关闭后每个维度的汇总。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 回顾 uid（来自 list_retrospectives） |
add_retro_itemsPro · retrospectives
以您自己的身份向回顾添加项目，一次添加多个：工作区支持时在新模型回顾上添加笔记，否则在经典回顾板上添加卡片。每个项目为 { column, text, recipient_id? }：column 是列标题（不区分大小写）或来自 get_retrospective 的 uid；text 最多 1000 个字符（经典板上为 255 个）；recipient_id（被感谢队友的用户 uid）在新模型 kudos 列中为必填，在经典板上被拒绝。新模型笔记会开启自己的主题，其他人会在笔记揭示后看到；仅在回顾开放记录笔记或处于“写入”阶段时才能记录笔记，否则调用将被拒绝，并返回代码 wrong_stage 和当前阶段。部分失败：有效的项目会被添加，无效的项目会按索引报告 — 请检查“failed”数组。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| retrospective_id | string | 是 | 回顾 uid |
| items | array of object | 是 |
move_retro_itemPro · retrospectives
移动回顾项目：工作区支持时在新模型回顾上重新分组笔记，否则在经典回顾板上将卡片移动到另一列。新模型，仅限“分组”阶段：topic_id 将笔记放入该主题（笔记组）；column（标题或 uid）使其成为该列中自己的主题，位于该列主题中的 position 位置（省略则放在最后）。传入 expected_updated_at（来自 get_retrospective 的笔记主题 updated_at），如果在此期间有人重新分组，则会被拒绝并返回代码 stale。在“分组”阶段之外，调用将被拒绝，并返回代码 wrong_stage 和当前阶段；kudos 和其他笔记永远不会混合。经典板仅接受 column 和 position（position 省略 = 顶部）。需要 Pro 版或试用版工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 来自 get_retrospective 的笔记 uid（经典板：项目 uid） |
| topic_id | string | 目标主题 uid；省略 column | |
| column | string | 目标列标题或 uid | |
| position | integer | 目标列中的索引（0 = 第一个） | |
| expected_updated_at | string | 上次读取的笔记主题 updated_at（冲突检查） |
list_project_usersread-only
列出项目的成员 — 标准项目为每个工作区成员；私有项目为创建者、工作区所有者和管理员，以及任何显式添加的人员 — 以便代理可以解析被分配者 uid，而不是猜测姓名。返回每个成员的 uid、全名、电子邮件和工作区角色（owner、admin、member 或 observer）。这些 uid 是 create_card、update_card、create_epic、update_epic 和 create_roadmap_slot 中 assigned_to 所接受的值。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
list_board_listsread-only
列出项目看板的列表，以便代理可以解析有效的 move_card 目标。按显示顺序返回每个活动列表及其 uid（可用作 move_card 目标）和显示名称。积压工作作为可选项包含在内，其 id 为空字符串。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
list_epicsread-only
列出项目的史诗，以便代理可以解析 get_epic 和卡片分配所需的史诗 uid。按显示顺序（位置升序）返回每个史诗及其 uid、编号、名称、描述（Markdown）、颜色、开始/结束日期和卡片数量。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
| updated_since | string | 仅返回记录在此 ISO-8601 日期或日期时间之后更改的史诗。注意：集合编辑（清单、链接）可能不会更新史诗的更改时间；名称/日期/描述编辑始终会更新。 |
list_labelsread-only
列出项目的标签，以便代理可以重用现有分类法，而不是在卡片写入时创建近似重复项。按显示顺序（位置升序）返回每个标签及其 uid、名称和位置。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
list_cards只读
按看板显示顺序（列顶部优先，即放置位置降序——与产品界面显示的顺序相同）列出一个看板列表中的卡片，或在省略或传入空 list_id 时列出项目积压中的卡片。筛选条件以 AND 组合：epic_id、label_id、assigned_user_id 和 reporter_id 接受 uid（未知 uid 不匹配任何内容）；due_date 保留到期日早于或等于给定日期的卡片。返回足以执行操作的卡片摘要（uid、标题、列表 + 位置、史诗、标签、指派对象、报告人、到期日），可直接用于 get_card / move_card / update_card，支持分页（limit 默认 50，最大 100）和 offset；total_count 为完整筛选后的计数。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
| list_id | string | 要读取的列表 uid；省略或传入空字符串以读取积压 | |
| epic_id | string | 仅返回所选列表或积压中属于此史诗（史诗 uid）的卡片；要跨所有列表列出某史诗的所有卡片，请使用 get_epic | |
| label_id | string | 仅返回带有此标签（标签 uid）的卡片 | |
| assigned_user_id | string | 仅返回指派给此用户（用户 uid）的卡片 | |
| reporter_id | string | 仅返回由此用户（用户 uid）报告（创建）的卡片 | |
| due_date | string | 仅返回到期日早于或等于此日期（ISO-8601，例如 2026-06-10）的卡片 | |
| updated_since | string | 仅返回记录在此 ISO-8601 日期或日期时间之后发生变更的卡片——即“自上次运行以来发生了什么变化”的筛选条件。注意：对附加集合（标签、清单、链接）的编辑可能不会更新卡片的变更时间；标题/描述/标量编辑始终会更新。 | |
| limit | integer | 页面大小，1-100（默认 50） | |
| offset | integer | 要跳过的卡片数量（默认 0） |
search_cards只读
在单个项目（看板和积压）内按标题子串搜索卡片，与产品内项目内实时卡片搜索完全一致（数据库对卡片标题进行不区分大小写的子串匹配——不搜索描述和评论；如需跨所有内容类型进行全文搜索，请使用搜索工具），按创建时间最新优先排序。返回足以执行操作的卡片摘要（uid、标题、列表放置 + 位置、史诗、标签、指派对象、报告人、到期日）；无匹配的查询返回空卡片数组，而非错误。支持分页（limit 默认 50，最大 100）和 offset；total_count 为完整匹配计数。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
| query | string | 是 | 要与卡片标题匹配的文本（不区分大小写的子串） |
| limit | integer | 页面大小，1-100（默认 50） | |
| offset | integer | 要跳过的匹配卡片数量（默认 0） |
list_attention_cardsPro · 指标只读
列出项目看板上需要关注的卡片——与产品“指标”页面中的列表相同。类型：stuck（停留在某列、非积压/已完成、超过 7 天未移动；最久未移动的优先）、blocking（其他卡片被其阻塞的未完成卡片）、overdue（到期日在未来 7 天内或已过期；最早到期优先）。kind 选择单个列表或“all”（默认）。可选按指派对象 uid 或字面量“unassigned”筛选。每个请求的区块返回可直接用于 get_card / move_card / update_card 的卡片摘要，上限为 limit，并包含完整 total_count。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
| kind | enum: stuck | blocking | overdue | all | 要返回的关注列表（默认“all”= 每个列表作为独立区块） | |
| assignee_id | string | 仅返回指派给此用户 uid 的卡片，或“unassigned”以返回无指派对象的卡片 | |
| limit | integer | 每个区块的最大卡片数，1-100（默认 50） |
get_metrics_summaryPro · 指标只读
一次性获取项目看板上需要关注的卡片计数：overdue_cards_count、blocking_cards_count 和 stuck_cards_count——与 list_attention_cards 的定义相同，后者返回每个计数背后的卡片。此操作开销低；可先调用此接口以决定是否值得深入查看。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符（uid） |
list_roadmap_slotsPro · 路线图只读
列出项目路线图中与日期窗口重叠的槽位（默认：本月起至未来五个月）。一个槽位在两个日期之间安排一个史诗，并可携带指派对象；一个史诗可持有多个槽位，包括重叠——这是设计使然。最多返回 200 个槽位——若达到上限请缩小窗口。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
| start_date | string | 窗口开始日期，ISO-8601（YYYY-MM-DD）；默认：本月月初 | |
| end_date | string | 窗口结束日期，ISO-8601；默认：start_date + 6 个月 |
create_roadmap_slotPro · 路线图
在项目路线图上安排一个史诗：一个从 start_date 到 end_date 的槽位，可选带指派对象。一个史诗可持有多个槽位，且允许重叠——这是设计使然；若您打算扩展现有槽位而非新增，请先检查 list_roadmap_slots。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 项目的唯一标识符 |
| epic_id | string | 是 | 史诗 uid（来自 list_epics）；必须属于此项目 |
| start_date | string | 是 | ISO-8601（YYYY-MM-DD） |
| end_date | string | 是 | ISO-8601；允许与 start_date 同一天 |
| assigned_to | array of string | 要指派的用户 uid（项目成员——参见 list_project_users） |
update_roadmap_slotPro · 路线图
更新路线图槽位：重新安排或调整大小（start_date/end_date）、将其移至同一项目的另一个史诗（epic_id），或设置其指派对象。仅更改提供的字段，但 assigned_to 除外——它会替换完整的指派对象集合——请先读取槽位并发送所有应保留的人员。槽位 uid 来自 list_roadmap_slots。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 路线图槽位 uid |
| epic_id | string | 新的史诗 uid（同一项目） | |
| start_date | string | ISO-8601（YYYY-MM-DD） | |
| end_date | string | ISO-8601 | |
| assigned_to | array of string | 替换所有指派对象（用户 uid，项目成员）；[] 表示清空 |
delete_roadmap_slotPro · 路线图破坏性
永久删除路线图槽位（及其指派对象链接）。此操作无法撤销——路线图槽位没有回收站。史诗本身不受影响；如需重新安排，请优先使用 update_roadmap_slot。需要 Pro 或试用工作区。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 路线图槽位 uid（来自 list_roadmap_slots） |
create_label
按名称在项目上创建新标签。如果已存在同名标签（不区分大小写），则返回现有标签而不创建近似重复项。新标签追加到显示顺序的末尾。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 标签所属的项目 uid |
| name | string | 是 |
create_card
在项目的看板上创建卡片。仅 project_id 和 title 为必填。省略 list_id 将卡片放入积压；省略 position 将加入队列末尾（move_card 记录了位置约定）。description 使用 AgileHero Markup——绝不用 markdown 或 HTML；请先阅读 get_ahm_spec。epic_id 和指派对象 uid 必须已存在（list_epics、list_project_users），而尚不存在的标签名称会在项目上创建。estimation 是斐波那契复杂度（0/1/2/3/5/8/13），而非时间估算。清单、链接、附件和卡片关系均可在同一次调用中提供。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | 卡片所属的项目 uid（卡片创建在项目的看板上） |
| list_id | string | 列表 uid；省略则放入积压 | |
| position | integer | ||
| type | enum: story | bug | chore | research | ||
| title | string | 是 | |
| description | string | AgileHero Markup（AHM）——绝不用 markdown 或 HTML；请先阅读 get_ahm_spec。描述表面：不支持表格、颜色、对齐或讨论。 | |
| epic_id | string | 史诗 uid；必须已存在于项目上 | |
| estimation | enum: 0 | 1 | 2 | 3 | 5 | 8 | 13 | 复杂度估算（故事点，斐波那契刻度），而非时间估算 | |
| due_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 指派对象用户 uid，可通过 list_project_users 发现 | |
| labels | array of string | 标签名称；未知名称会在项目上创建 | |
| checklists | array of object | 每个 { name, items: [{ description, checked }] }；items 保持提供的顺序 | |
| cards_relations | array of object | 每个 { type, target_card_id（同一看板上的卡片 uid） } | |
| links | array of object | 每个 { url, description } | |
| attachments | array of object | 每个 { url, name }；文件从 url 获取 |
update_card破坏性
按 uid 更新现有卡片。对于集合，优先使用 add_*/remove_* 增量字段（安全增量编辑：add_labels、remove_assignees、add_checklist_items、check_items 等）；普通集合字段（labels、assigned_to、checklists、cards_relations、links、attachments）会破坏性地替换先前状态，且不能与其增量字段组合使用。使用 move_card 更改列表或位置，使用 preview_description_update / update_description 编辑描述。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
| type | enum: story | bug | chore | research | ||
| title | string | ||
| epic_id | string | ||
| estimation | enum: 0 | 1 | 2 | 3 | 5 | 8 | 13 | 复杂度估算（故事点，斐波那契数列），不是时间估算 | |
| due_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 负责人用户 uid，可通过 list_project_users 获取；替换卡片的负责人 | |
| labels | array of string | 标签名称；未知名称会在项目中创建；替换卡片的标签 | |
| checklists | array of object | 每个 { name, items: [{ description, checked }] }；条目保持提供的顺序；替换卡片的检查清单 | |
| cards_relations | array of object | 每个 { type, target_card_id（同一看板上的卡片 uid）}；替换卡片的关系 | |
| links | array of object | 每个 { url, description }；替换卡片的链接 | |
| attachments | array of object | 每个 { url, name }；文件从 url 获取；替换卡片的附件 | |
| add_labels | array of string | 按名称添加标签（未知名称会创建）；保留现有标签 | |
| remove_labels | array of string | 按名称移除标签（不区分大小写）；不存在的名称无操作 | |
| add_assignees | array of string | 按用户 uid 添加负责人；保留现有负责人 | |
| remove_assignees | array of string | 按用户 uid 移除负责人；不存在的 uid 无操作 | |
| add_checklist_items | array of object | 追加条目：每个 { checklist, description, checked? } — 如果指定的检查清单不存在则创建 | |
| check_items | array of object | 将条目标记为完成，按指定检查清单中的精确描述匹配 | |
| uncheck_items | array of object | 将条目标记为未完成（匹配方式与 check_items 相同） | |
| remove_checklist_items | array of object | 删除条目；不存在的条目无操作 | |
| add_relations | array of object | 添加关系；保留现有关系 | |
| remove_relations | array of object | 移除匹配的关系；不存在的关系无操作 | |
| add_links | array of object | 添加链接：每个 { url, description? }；保留现有链接 | |
| remove_links | array of string | 按精确 url 移除链接；不存在的 url 无操作 |
delete_card（破坏性操作）
按 uid 软删除卡片：它会从看板和所有列表中消失，与其他卡片的关系被移除，任何相关的估算会话被停用，链接到它的白板元素被取消链接。它所属的 epic 不会被删除。通过 MCP 无法恢复删除。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
move_card
将卡片移动到不同的列表（或更改其在同一列表中的位置）。只有看板上的卡片可以移动；回顾板上的卡片会被拒绝。将 list_id 传为空字符串可将卡片移动到看板待办事项（backlog）。列表从上到下显示，最高位置在顶部，因此位置 0 是列表的底部。省略 position 参数时，在待办事项（backlog）、to_do 和 in_progress 列表中卡片将加入队列末尾（底部，位置 0），在 done 列表中则加入顶部。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
| list_id | string | 是 | 目标列表 uid；空字符串表示移动到待办事项（仅限看板） |
| position | integer | 在目标中的位置：0 是底部，最高位置是顶部。必须在 0 和目标中已有其他卡片数量之间。省略时，在待办事项（backlog）、to_do 和 in_progress 列表中卡片加入队列末尾（位置 0），在 done 列表中则加入顶部。 |
create_epic
在项目上创建 epic。只有 project_id 和 name 是必填的。description 使用 AgileHero Markup — 绝不是 markdown 或 HTML；请先阅读 get_ahm_spec。负责人 uid 来自 list_project_users。检查清单、链接和附件可以在同一次调用中提供。返回新的 epic uid — 即 create_card / update_card 接受的 epic_id，以及 create_roadmap_slot 调度的对象。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| project_id | string | 是 | epic 所属的项目 uid |
| name | string | 是 | |
| description | string | AgileHero Markup (AHM) — 绝不是 markdown 或 HTML；请先阅读 get_ahm_spec。描述表面：不支持表格、颜色、对齐或讨论。 | |
| color | string | 十六进制颜色，如 #0060F0 | |
| start_date | string | ISO-8601 日期 | |
| end_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 负责人用户 uid，可通过 list_project_users 获取 | |
| checklists | array of object | 每个 { name, items: [{ description, checked }] }；条目保持提供的顺序 | |
| links | array of object | 每个 { url, description } | |
| attachments | array of object | 每个 { url, name }；文件从 url 获取 |
update_epic（破坏性操作）
按 uid 更新现有 epic；仅更改提供的字段。对于集合，优先使用 add_*/remove_* 增量字段（安全的增量编辑）；普通集合字段（assigned_to、checklists、links、attachments）会破坏性地替换先前状态，且不能与其增量字段组合使用。使用 preview_description_update / update_description 编辑描述。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | Epic uid |
| name | string | ||
| color | string | 十六进制颜色，如 #0060F0 | |
| start_date | string | ISO-8601 日期 | |
| end_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 负责人用户 uid，可通过 list_project_users 获取；替换 epic 的负责人 | |
| checklists | array of object | 每个 { name, items: [{ description, checked }] }；替换 epic 的检查清单 | |
| links | array of object | 每个 { url, description }；替换 epic 的链接 | |
| attachments | array of object | 每个 { url, name }；文件从 url 获取；替换 epic 的附件 | |
| add_assignees | array of string | 按用户 uid 添加负责人；保留现有负责人 | |
| remove_assignees | array of string | 按用户 uid 移除负责人；不存在的 uid 无操作 | |
| add_checklist_items | array of object | 追加条目：每个 { checklist, description, checked? } — 如果指定的检查清单不存在则创建 | |
| check_items | array of object | 将条目标记为完成，按指定检查清单中的精确描述匹配 | |
| uncheck_items | array of object | 将条目标记为未完成（匹配方式与 check_items 相同） | |
| remove_checklist_items | array of object | 删除条目；不存在的条目无操作 | |
| add_links | array of object | 添加链接：每个 { url, description? }；保留现有链接 | |
| remove_links | array of string | 按精确 url 移除链接；不存在的 url 无操作 |
delete_epic（破坏性操作）
按 uid 软删除 epic。其卡片不会被删除 — 它们会留在看板上，与 epic 解除关联。epic 的路由图槽位会被永久删除（槽位调度 epic，没有 epic 则无意义），链接到 epic 的白板元素会被取消链接。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | Epic uid |
create_comment
向卡片或 epic 添加评论。提供 card_id 或 epic_id 中的一个（且仅一个）。内容使用 AgileHero Markup（AHM，评论表面：不支持表格、媒体、颜色、对齐或讨论）— 绝不是 markdown 或 HTML；请先阅读 get_ahm_spec。评论归属于此客户端所代表的已登录用户，并出现在后续的 get_card / get_epic 响应中。评论无法通过 MCP 编辑；delete_comment 可删除您自己的评论（通过删除 + 重新发布来纠正错误）。传入 parent_comment_id 可回复现有评论。线程只有一层深度：回复一条回复时，新评论会附加到该回复的线程根，因此不要尝试嵌套回复。父评论必须位于同一卡片或 epic 上 — 来自其他位置的 uid 会被拒绝。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| card_id | string | 要评论的卡片 uid（与 epic_id 互斥） | |
| epic_id | string | 要评论的 epic uid（与 card_id 互斥） | |
| content | string | 是 | 评论正文，使用 AgileHero Markup (AHM) |
| parent_comment_id | string | 可选，同一卡片或 epic 上评论的 uid，用于回复。省略则为顶级评论。回复一条回复会规范化为该回复的线程根（线程只有一层深度）。 |
delete_comment（破坏性操作）
删除您发布的评论（评论归属于此客户端所代表的已登录用户 — 其他人的评论无法删除）。纠正模式是删除 + 使用 create_comment 发布更正后的评论。已删除但有回复的评论在其线程中仍以墓碑形式可见。评论 uid 来自 get_card / get_epic。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| id | string | 是 | 评论 uid |