docs-collaborator

Docs 协作者

创建、读取、编辑 monday.com 文档并添加评论。**这项技能提供的是能力，而非模板引擎。**每份文档都是由带类型的区块组成的流（标题、段落、列表、表格、代码、分隔线、通知框、布局、嵌入的看板 / 小组件 / 文档 / 图片 / 视频 / GIF）。下方列出的命名结构只是起点——可自由组合和扩展。各项独特能力（实时列值嵌入、行内提及、通知框、布局）适用于任何结构，无论是否已命名。

平台原生能力相较于纯 Markdown 编辑器的优势，体现在三个多数构建者会忽略的方面：行内提及用户 / 文档 / 看板、反映看板项目当前状态的实时列值嵌入，以及防止破坏文档区块图的闭环编辑模式。

核心限制——请先阅读

**绝不要编辑尚未读取的区块。**monday 的 update_doc API 基于区块 ID，而区块 ID 只能通过 read_docs 并设置 include_blocks: true 获取。跳过读取会导致操作引用不存在的 ID（静默失败），甚至更糟——复用其他文档中的 ID。闭环模式不可妥协：

1. 使用 read_docs 并设置 include_blocks: true，获取区块 ID、类型和位置。
2. 根据类型和位置或内容，确定目标区块。
3. 使用与目标区块类型相匹配的操作调用 update_doc（参见下方的路由规则）。

区块操作路由——容易忽略的关键点

每种区块类型允许的变更操作各不相同。选错操作是导致“调用成功，但文档显示异常”问题的头号原因。

目标区块类型	使用此操作	原因
text（任意子类型：NORMAL_TEXT、LARGE_TITLE、MEDIUM_TITLE、SMALL_TITLE、QUOTE）	编辑内容用 update_block；更改子类型（例如将段落升级为 H2）用 replace_block	子类型在创建时设定；update_block 无法更改
code	update_block	可就地编辑内容和语言
list_item（BULLETED_LIST、NUMBERED_LIST、CHECK_LIST）	编辑内容用 update_block；切换项目符号 / 编号 / 复选框列表用 replace_block	列表类型在创建时设定
divider	仅用 replace_block	没有可变属性
table	仅用 replace_block	行数 / 列数和列宽不可变；创建后无法通过 API 定位表格单元格内容——参见 references/rich-content.md 中的“Tables”
image	用 replace_block 替换来源	创建后 URL / asset_id 不可变
video	用 replace_block 替换来源	raw_url 创建后不可变
notice_box	用 replace_block 更改主题	主题不可变；内容存储在子区块中（参见 references/rich-content.md 中的“Notice boxes”）
layout	仅用 replace_block	完全无法通过 API 填充单元格内容——参见 references/rich-content.md 中的“Layouts”
BOARD 嵌入、WIDGET 嵌入、DOC 嵌入、GIPHY	仅用 delete_block	没有用于创建或修改这些区块类型的公开 API

**渲染问题——list_item + 通过 update_block 添加提及。**向原先仅包含文本的 list_item 添加行内提及时，update_block 可能会正确保存 mention blot（数据可确认），但部分客户端可能无法渲染提及标签（文本前缀位于提及之前的情况）。解决方法：使用包含相同 delta 的全新 list_item 调用 replace_block。同样的模式在 normal_text 区块中可以正确渲染；该问题似乎仅在更新 list_item 时出现。

各区块类型的详细说明和完整示例见 references/block-operations-matrix.md。进行任何复杂的结构编辑前，请先阅读。

工作流：创建文档

步骤 1：确定位置

monday 文档位于以下两个位置之一：

• 工作区（最常见）。需要 workspace_id。doc_kind 为可选项：public（默认）、private（仅创建者可见）、share（特定人员可见）。可选的 folder_id 用于将文档放入文件夹。
• 附加到条目。文档位于特定看板条目的文档类型列中。需要 item_id。如果用户选择了特定的文档列，则 column_id 为可选项；否则工具会自动创建一个列。

附加到条目的文档的单元格限制预检。 文档类型单元格每个只能存放一个文档，这是 API 的硬性限制。调用 create_doc location=item 之前，通过 get_board_items_page 并设置 columnIds: [<doc_col_id>] 对目标列进行预检，确认单元格是否已有内容。如果已有内容，请勿尝试创建，否则会因 CellLimitExceededException 失败。改为创建工作区级文档，并在新文档与现有附加文档之间添加双向 DOC 提及交叉链接。绝不要自动分离现有文档。

如果用户未指定工作区，则通过 get_user_context 使用用户的主工作区。如果仍有歧义，只询问一次；不要在多个工作区之间自行猜测。

步骤 2：创建第 4 个文档前检查计划限制

Free 和 Basic 计划将每个账户的文档数量限制为 3 个。 在 Free / Basic 账户上调用 create_doc 之前，检查这是否会成为第 4 个文档。没有可直接查询文档数量的工具，因此实用的检查方式是：如果用户之前已达到此限制，或询问“我能创建超过 3 个文档吗？”，请提醒他们升级到 Standard+ 即可解除限制。将计划级别视为尚待确认的问题，而不要因此阻止创建调用；如果达到限制，平台本身会拒绝创建。

第 3 步：撰写正文——结构只是示例，不是限制

create_doc 接受一个 markdown 参数，导入时会将其解析为区块。正文保持精简，只包含几个章节；较长的正文请使用 add_markdown_content 追加（参见 references/errors.md）。当用户说明了使用场景时，可从以下常见结构中选择一种作为起点，然后自由扩展：

• 会议记录： 标题、日期、参会者（使用 @mentions）、议程要点、决策、行动项表格、后续跟进。
• 每周更新： 重点进展、关键指标、风险、下周计划。
• RFC： 问题、拟议解决方案、考虑过的替代方案、待解决问题、决策记录。
• 运行手册： 触发条件、前置条件、编号步骤、回滚步骤、升级路径。
• 复盘报告： 事件摘要、时间线、根本原因、进展顺利之处、存在的问题、行动项。

如果用户自创结构（“合作伙伴赋能页面”“AI 就绪度概览”“Q3 入职背景”），请灵活判断，组合章节、表格、提示框、嵌入内容等，而不是强行套用某个命名模板。这些差异化要素适用于任何结构。

被动模式与主动模式。 默认情况下，在嵌入内容和提及对象的位置使用可见的占位标记（_[embed: ...]_、_[mention: ...]_）。当用户提到具体项目、看板或人员名称时，切换到主动模式——配置真实的嵌入内容和提及对象——自行将名称解析为 ID（如果名称有歧义，只需询问一次，并提供最匹配的 3 个候选项），并说明选择了什么。在配置任何内容之前，请阅读 references/create-modes.md：其中介绍了标记格式、升级触发条件、名称到 ID 的解析流程和沟通约定。

需要注意的 Markdown 事项：

• Markdown 标题（#、##、###）分别映射为 LARGE_TITLE / MEDIUM_TITLE / SMALL_TITLE 区块。
• Markdown 表格可用，单元格会填入你提供的值。这是唯一能预先填充表格内容的方式。 创建后不支持通过单元格级 API 填充内容。
• Markdown 图片和链接可用。对于基于资源的图片（上传到 monday 的文件），请在创建后使用 update_doc，通过 create_block 和 block_type: "image"，再加上 asset_id 添加图片——Markdown 无法引用资源。
• Markdown 不支持 notice_box、layout、embed、带间距的分隔线、mention 或实时列值语法。创建文档后，请通过 update_doc 添加这些内容。

第 4 步：调用 create_doc

create_doc({
  doc_name: "<title>",
  location: "workspace",
  workspace_id: <id>,
  doc_kind: "public" | "private" | "share",  // optional
  folder_id: <id>,                            // optional
  markdown: "<full markdown body>"
})

对于关联到项目的文档（完成预检后）：

create_doc({
  doc_name: "<title>",
  location: "item",
  item_id: <id>,
  column_id: "<doc_column_id>",  // optional
  markdown: "<full markdown body>"
})

记录返回的 doc_id、object_id 和 doc_url。用户需要可分享或打开的 URL；doc_id 是后续每次编辑所用的主键。

第 5 步：添加丰富内容

提及、实时列值嵌入、提示框、布局和资源图片都需要后续调用 update_doc。主动模式下，使用第 3 步解析出的 ID 立即配置这些内容。被动模式下，保留占位标记——用户之后可通过指定项目来填充这些位置。参见 references/delta-format-cheatsheet.md 中的“常见模式”。

第 6 步：确认并建议后续步骤

用通俗语言确认文档名称、工作区和文档 URL，并说明所用模式（被动搭建或主动配置）。然后根据文档结构提出 2-3 个后续建议：

• “要我用 @mentions 标记参会者吗？”
• “要我嵌入项目看板中的实时状态吗？”
• “要我在顶部添加一个提示框，说明会议结果吗？”
• “要我把文档 URL 分享到 Slack 频道吗？”

工作流：读取文档

步骤 1：解析文档标识符

用户可能通过以下三种方式指定文档：

• doc_id（例如，41302579）——API 的主键，由 create_doc 和 read_docs 返回。
• object_id（例如，18411484379）——文档 URL 中的数字部分：https://monday.monday.com/docs/{object_id}。
• 文档名称或模糊引用（“Q3 复盘文档”）——通过 read_docs 并设置 type: "workspace_ids" 列出工作区中的文档，然后按名称匹配。

read_docs 具有容错性：如果使用 type: "ids" 调用它，但值实际上是 object_id，它会自动重试 object_ids。依赖这一机制，而不是猜测。

步骤 2：决定要读取的内容

有两种模式：

• content（默认）——返回文档的区块和／或 Markdown 投影。
  • 如果之后要进行任何编辑，include_blocks: true 是必填项。不要省略。
  • 使用 include_comments: true 获取所有评论和回复。使用 comments_limit 限制数量（默认值为 50）。
• version_history ——返回文档的编辑历史（还原点）。传入 object_id，而不是 id。对于“最近 N 次更改”请求，设置 version_history_limit；设置 include_diff: true 查看更改内容（速度较慢）。

步骤 3：使用已解析的提及和嵌入内容进行渲染，而不是使用占位符

API 的 blocks_as_markdown 投影会将提及渲染为 @{USER-XXX} 占位符，并将实时列值嵌入内容渲染为空白。对于“展示文档内容”的请求，这种渲染方式并不合适——用户打开文档时看到的是标签和实时信息块；文本渲染应与之保持一致。

对于“展示一下／里面有什么／读一下这个文档”之类的请求：将每个提及解析为显示名称，在成本较低时将嵌入内容解析为当前值，并添加一个列出内嵌非文本元素及其 ID 的表格。具体规则请阅读 references/read-rendering.md。

不要使用 show-table 展示文档内容——文档本身就是 UI。请在聊天中使用 Markdown 渲染。

工作流：编辑文档

步骤 1：先读取

使用 include_blocks: true 调用 read_docs。这是闭环操作的前置条件。记录每个区块的 id、type 和位置。

步骤 2：选择合适的操作

选择能完成任务的最简单操作：

• **在末尾添加新内容：**使用 add_markdown_content（无需区块 ID；支持文本、列表、表格和代码）。
• **添加基于资源的图片：**使用 create_block，并设置 block_type: "image" 和 asset_id（Markdown 不支持资源图片）。
• **就地编辑现有文本／代码／list_item 内容：**使用 update_block，并设置匹配的 block_content_type（text、code 或 list_item）。
• 更改区块的子类型（段落 -> H2、项目符号列表 -> 编号列表、INFO 通知 -> WARNING 通知）：使用 replace_block。子类型只能在创建时设置。
• **在精确位置插入区块：**使用 create_block，并设置 after_block_id。没有 before_block_id 操作——要在文档最顶部插入，唯一的方法是在文档的第一个区块之后插入。
• **删除：**使用 delete_block。对于 BOARD／WIDGET／DOC 嵌入／GIPHY 区块，这是唯一可用的操作。
• **评论：**使用 add_comment——正文为 HTML；通过 mentions_list 标记他人，而不是在正文中使用 @（请参阅 references/rich-content.md 中的“Comments”）。
• **重命名文档：**使用 set_name。

完整的类型到操作路由规则见 references/block-operations-matrix.md。

第 3 步：编写 delta_format（用于 text / code / list_item）

内容块的 update_block 和 create_block 都接受由插入操作组成的 delta_format 数组。每条 delta 都必须遵守以下三条规则：

1. 最后一条操作必须是 {insert: {text: "\n"}}。始终如此，没有例外。
2. 纯文本使用 {insert: {text: "..."}}，可选搭配 attributes（bold、italic、underline、strike、code、link、color、background）。
3. 两种非文本插入操作可实现差异化功能：
   • 提及：{insert: {mention: {id: <numeric-id>, type: "USER" | "DOC" | "BOARD"}}}。通过 list_users_and_teams 解析用户 ID（始终传入 name，以限定调用范围）。
   • 实时列值嵌入：{insert: {column_value: {item_id: <id>, column_id: "<column_id>"}}}。每次打开文档时，都会实时呈现该项该列的当前值。

示例和完整的属性表见 references/delta-format-cheatsheet.md。

第 4 步：谨慎批量执行操作

update_doc 一次调用最多接受 25 项操作，按顺序执行，遇到第一项失败时即停止。需要注意以下四点：

• 创建提示框并嵌套内容需要分两次调用。 同一次调用中创建的 notice_box，不能在该次调用的后续操作中通过 parent_block_id 引用。先创建 notice_box 并记录返回的 ID，再调用一次 update_doc 来嵌套子项。
• 位置依赖。 如果操作 B 引用了操作 A 创建的块的位置，建议分两次调用。数组中途失败会使文档处于部分更新状态。
• 检测对同一块的冲突。 如果同一次调用（或同一轮用户交互）中的多项操作针对同一个 block_id，应在执行前向用户说明冲突——观察到的行为是“最后写入者胜出”。示例：update_block 向段落 X 添加提及，之后的另一个 update_block 完全替换段落 X。第二项操作会生效，提及将丢失。
• 评论锚点位于 delta 中。 当块中有锚定评论时，读取响应会在相关文本插入项上显示 attributes.comments: [<update_id>, ...]。update_block 会替换整个 delta_format，因此直接重写会使评论脱离该块（评论本身仍保留在底层项上，但会失去与该块的关联）。要在编辑时保留锚定评论，请在新 delta 中相应的文本插入项上加入 comments 属性。

第 5 步：验证并确认

完成重要编辑后，使用 include_blocks: true 重新读取，以确认各块已按预期写入。用通俗语言确认更改内容和文档 URL。不要叙述 API 调用过程。

富内容：表格、提示框、布局、提及、实时嵌入、评论

实时列值嵌入是差异化功能：它能让文档与看板中的实际数据保持同步。添加这些元素前，请先阅读 references/rich-content.md。其中介绍了表格限制、提示框嵌套、布局、提及类型、实时列值嵌入和评论。

智能默认值

用户未指定所有值时：

• 工作区：通过 get_user_context 获取用户的主要工作区。说明此默认值。如果可能存在多个工作区，只询问一次。
• doc_kind：public（平台默认值）。
• 文件夹：无（工作区根目录）。
• 文档结构：如果用户说明了用途（“会议记录”“RFC”“每周更新”），就以相应结构为起点搭建框架，并根据用户的具体要求扩展。如果用户自行设计结构，则自行判断并编排，无需使用模板。
• 模式：默认使用被动框架（占位标记）。仅当出现基于名称的意图信号时，才升级为主动模式（实际嵌入 / 提及 / 交叉链接）。
• 主动模式下的嵌入和提及：在配置前说明解析出的选择及理由，并提供覆盖默认选择的选项。

在回复中说明每一项默认值，以便用户进行调整。

写入前验证前置条件

• 文档存在： 写入前，已对目标 ID 成功调用 read_docs。
• 区块 ID 有效： 操作数组中的每个 block_id 都来自最近一次 read_docs 调用。
• 提及所用的用户 ID： 通过 list_users_and_teams 解析（始终使用 name 或 userIds 筛选条件）。
• 嵌入所用的条目 ID 和列 ID： 写入前通过 get_board_info 和 get_board_items_page 确认二者。状态列 ID 始终特定于看板（例如 color_mm2x25ey），绝不能使用通用字面值 "status"。
• 工作区存在： 如果用户指定了工作区但未提供 ID，则调用 list_workspaces。
• 附加到条目的文档的单元格容量： 在调用 create_doc location=item 前，通过 get_board_items_page 对目标文档列进行预检（参见步骤 1）。
• 主动模式下的空数据回退： 如果用户的意图引用了一个没有任何已设置值的列（例如，用户提到“最高优先级”，但 Priority 列完全为空），请勿擅自选择。检测到空状态后，告知用户（“所有条目均未设置 Priority 值”），提供有明确理由的回退启发式方案（“改为根据 Status 和 Due Date 的接近程度进行选择”），并提供覆盖此方案的选项。

写入前检测重复内容

在执行任何 create_block、add_markdown_content、add_comment 或会替换内容的 update_block 操作前，请将拟写入的内容与文档中的现有区块进行比较。 默认跳过并报告匹配项；向用户提供选项；绝不悄悄创建重复内容。

按区块类型使用以下匹配启发式规则：

区块类型	匹配启发式规则
text / heading / quote / code	delta 文本完全相同且子类型相同
list_item	文本完全相同、列表类型相同且相邻（将多条项目符号列表作为一个整体匹配）
notice_box	主题相同且子区块文本相同
table	维度相同且单元格内容相同
mention	同一位置的 user_id 相同
column_value embed	同一位置的 item_id 和 column_id 相同
comment	正文文本相同且锚点相同（默认排除——见下文）

发现匹配项后的技能行为：

1. 默认：跳过并报告。 “<position> 处已存在 X。为避免重复，跳过。”
2. 提供选项（不得擅自选择）：
   • (a) 跳过——保留现有内容，不做任何操作
   • (b) 重复添加——按请求继续，接受内容冗余
   • (c) 替换——删除现有内容并重新创建
   • (d) 移动——仅当新请求明确指定位置（“放在顶部 / 底部 / X 之后”），且该位置与匹配项的现有位置冲突时提供

以下情况属于正常重复，不应触发重复检测：

• 评论默认排除，仅设短暂的防抖窗口。相同评论正文在 60 秒内提交到相同范围（文档或区块），几乎可以确定是重复提交或网络重试；超过 60 秒则视为合法操作（例如合法的重新审查、情绪呼应）。
• 列表中相邻且样式相同的区块——这是预期结构，不属于重复。
• 不同父级下重复的章节名称（例如，两个不同 H2 标题下都有“Action Items” H3）。

将此重复检测规则应用于技能中的每条写入路径。

提供错误及解决方法

调用失败时，请告知用户出错原因及修复方法。常见失败及其解决方法（格式错误或过时的区块 ID、架构不匹配、单次调用中的嵌套、单元格限制、空白嵌入、计划限制、不支持的区块类型、孤立的评论锚点）见 references/errors.md。

对破坏性操作保持谨慎

以下操作需要明确确认：

• 一次调用中删除 3 个或更多区块。
• 删除其父级中唯一的内容区块（这会删除父级的唯一内容；父级仍会作为空壳保留）。
• 删除 notice_box、表格或布局——子项不会自动删除，而会变成孤立项。请先删除子项，或接受其孤立状态。
• 批量执行 replace_block 操作（每次替换都包含删除和创建，且不可撤销）。
• 重命名存在有效外部引用的文档（Slack 消息、其他文档、项目更新）。

单个区块编辑、单个区块创建和单条评论无需额外确认——用户已经提出了请求。

何时使用 MCP UI 小组件

文档本身就是 UI。请勿使用 show-table 或 show-chart 来展示文档内容。确认事项使用纯文本，摘要使用 Markdown。

使用通俗语言，不要使用原始 JSON

不要告诉用户“我先调用了 read_docs，再通过 update_block 操作调用了 update_doc。”请用通俗语言说明更改内容：“已将新版升级联系人更新到操作手册的第二段。”务必附上文档 URL。

使用的工具

• get_user_context - 确定用户的主工作区
• list_workspaces - 未提供工作区时，按名称查找工作区
• create_doc - 在工作区中或附加到某个项目上创建文档；创建时会将 Markdown 正文导入为区块
• read_docs - 获取一个或多个文档（内容模式）或版本历史；编辑前必须设置 include_blocks: true；获取评论线程时设置 include_comments: true
• update_doc - 按顺序执行操作：set_name、add_markdown_content、update_block、create_block、delete_block、replace_block、add_comment
• list_users_and_teams - 解析提及所需的用户 ID 和 mentions_list（始终传入 name 或 userIds 进行范围限定）
• get_board_info - 在写入实时列值嵌入内容前验证列 ID；为活动模式嵌入配置预检看板结构
• get_board_items_page - 在写入实时列值嵌入内容前验证项目 ID；为附加到项目的创建操作预检文档列单元格；在活动模式下将项目名称解析为 ID
• search - 在活动模式下按名称模糊查找文档或看板

其他资源

• references/block-operations-matrix.md - 各区块类型允许的操作、注意事项和示例负载。
• references/create-modes.md - 被动脚手架槽位标记、活动模式触发条件、名称到 ID 的解析，以及沟通约定。
• references/rich-content.md - 表格、提示框、布局、提及、实时列值嵌入内容和评论。
• references/read-rendering.md - 读取文档时如何呈现提及、嵌入内容和行内元素。
• references/errors.md - 常见故障及其补救方法。
• references/delta-format-cheatsheet.md - delta_format 插入操作、属性、提及、column_value 嵌入内容、终止符规则、常见模式，以及被动模式槽位标记格式。