datocms-cma

DatoCMS 内容管理 API 技能

对 CMA 操作和脚本使用此工作流。若是寻求建议或代码说明，请跳过执行和设置。对于“发布它们”这类简短的后续请求，保留先前的 DatoCMS 任务、选定的路由、项目、环境和范围。

1. 设置前选择执行方式

已停用的 MCP 请求：不执行。 如果用户请求使用已停用／旧版 MCP，或报告旧的本地集成已无法正常工作，请回复：“该集成已停用。请使用当前 DatoCMS MCP 设置。”在最终答复中保留该链接。结束该任务，不要调用旧版或当前 DatoCMS 工具：当前可用的连接并不意味着可以擅自替换执行路径。不要探查、修复、重新安装或重新配置已停用的集成。除非用户改为请求 CLI 或当前 MCP，否则应先应用此停止条件，再遵循下方常规路径规则。仅凭连接／身份验证错误，不能判定集成已停用。

**只要 CLI 可用，就默认使用 CLI，即使 MCP 已连接也是如此。**只有在用户明确选择工具，或本次对话中已经使用某条路径时，才覆盖此规则。已安装或已通过身份验证的连接只代表可用，不代表工作流已确定。

只检查与任务相关且已暴露的能力。可用意味着现在就能使用，而不只是可以安装；不要运行启动连接检查，也不要扫描 MCP 客户端配置。

• **明确指定路径：**遵从用户对当前 MCP 或 CLI 的选择，包括在 CLI 可用时使用 MCP。后续请求沿用已确定的路径，除非用户更改。
• **路径锁定：**选定路径后，整个对话中的实时操作都应沿用该路径，即使后续请求涉及其他主题也是如此，直到用户明确切换。选择 MCP → 不要加载 datocms-cli，也不要为实时工作运行 CLI 命令，包括架构查询；选择 CLI → 不要加载 references/mcp.md，也不要调用 DatoCMS MCP 工具。下方的本地交付物仍沿用其工作流。
• **未指定偏好或尚未确定路径：**如果 CLI 和当前 MCP 均可用，选择 CLI。仅连接了 MCP 并不代表用户要求使用它。如果只有当前 MCP 可用，就选择 MCP，不要安装软件包、登录 CLI 或关联项目。如果只有 CLI 可用，就选择 CLI。
• **两者都尚未就绪：**说明此环境所缺少的前置条件。仅进行本地操作的 CLI 工作可能需要先设置 CLI；无法在本地执行的客户端则需要为实时操作提供受支持的项目连接。MCP 是可选项，并非所有技能的前置条件。
• **本地交付物：**迁移、仓库配置和应用代码仍使用其本地开发工作流。远程执行不能替代有版本控制的迁移，也不能创建所需的本地文件。对于应用／服务端或无人值守 CMA 代码，应检查并沿用现有客户端配置和生成的类型；只有在缺少必要设置时才添加。

选择路径后：

路径或交付物	按需加载
CLI 单次调用或端点文档	../datocms-cli/references/direct-cma-calls.md。
CLI 循环、分页、依赖调用，或本地化／区块／Structured Text 编辑	../datocms-cli/references/cma-script.md，了解 stdin／文件模式和运行时全局变量。
当前 MCP	references/mcp.md；已暴露的工具会提供其当前运行时约定。
所选 CLI 工作缺少前置条件	datocms-cli 设置工作流。关联前始终确认目标项目；仅凭推断得出的单一候选项目不代表用户同意。
自行构造客户端的代码（应用／服务端、CI、cron、共享的无人值守脚本）	references/client-setup-and-errors.md，了解软件包选择、令牌／环境变量配置和错误处理。

使用所选工具的当前文档了解方法签名、有效负载、身份验证、项目／环境选择和执行要求。共享参考资料中的 CLI 文档提示仅适用于 CLI 工作。MCP 任务不得因引用了其他资料而额外要求 CLI 前置条件。

2. 明确范围与 Schema 处理方式

复用已知的项目和环境。仅补充缺失的信息；如果目标或请求的操作存在歧义，请先询问。选择其他工具并不意味着获得更多操作权限、改用其他环境或发布内容。修改 Schema 需要 Schema 编辑权限（can_edit_schema）；直接修改主环境的 Schema 前，必须明确确认。

执行依赖 Schema 的修改前，请检查相关模型、字段、验证器和当前记录值。在 CLI 模式下，参阅 ../datocms-cli/references/schema-inspect.md 中针对性的 schema:inspect 指南；在 MCP 模式下，使用已提供的 Schema 工具。对于范围较窄的编辑，不要获取整个项目。

任务	处理方式
破坏性 Schema 变更：删除字段或模型、有数据损失的字段类型变更，或对记录执行 bulk_destroy	先通过 datocms-cli 在分叉的沙盒中执行迁移。未经用户明确且反复确认，绝不在主环境中执行。
可逆的 Schema 变更：添加或重命名字段或模型、修改验证器、调整字段集顺序	除非已确定方案，否则先询问用户是希望采用可审查的迁移，还是直接修改沙盒。若仓库使用迁移，或工作位于次要分支，优先使用迁移；直接修改适用于快速迭代沙盒。
明确要求一次性操作或选择不使用迁移	除非变更具有破坏性，否则按要求直接修改。不要反复建议迁移。
内容操作：发布/取消发布、删除单条记录、编辑字段、批量更新值、上传元数据	使用选定的方案；无需迁移。保留获准操作的记录、字段、区域设置和发布状态。
要求以版本化方式变更，并在多个环境中重放	遵循 datocms-cli 迁移指南并使用本地制品。

如果有可用的同级指南，请自行加载；不要让用户在不同技能之间来回奔波。如果无法在此处生成本地交付物，请说明缺少的本地能力，而不是悄然改用远程修改。

3. 仅加载相关工作流

方法文档提供 API 形状；这些参考资料介绍 DatoCMS 编辑工作流和注意事项。只查询当前正在构建的操作所需的方法详情。如果所选工具已返回相关指南，请直接复用，而不要重复加载。后续操作中，不要预先加载所有参考资料，也不要重新读取未更改的参考资料。

任务	参考资料
记录生命周期、发布、引用	references/records.md
上传和资源元数据	references/uploads.md
直接修改架构	references/schema.md
筛选（包括创建者审查）、查询、集合分页	references/filtering-and-pagination.md；即使已安装的 SDK 接受宽泛对象，也要在此处检查筛选运算符。
本地化字段和语言环境回填	references/localization.md；添加或回填语言环境时，还要参阅 references/editing-records.md。
Modular Content、Single Block、块遍历	references/editing-records.md
创建／更新／回填 Structured Text 记录	参阅 references/editing-records.md 了解 CMA 适配；参阅 ../datocms-structured-text/references/document-model.md，以及其中有关编辑或转换的参考资料，了解 DAST 操作。
环境操作	references/environments.md
角色、令牌、协作者	references/access-control.md
所请求的迁移脚本	references/migration-patterns.md，以及 datocms-cli 迁移指南
本地生成的 CMA 类型	references/type-generation.md
原始方法、高级客户端行为、平台限制	references/client-types-and-behaviors.md
项目设置、维护模式、订阅限制、用量	references/project-settings-and-usage.md
Webhook／构建触发器、调度／工作流、菜单、插件、已保存筛选器、上传轨道／标签、审计日志	references/resource-gotchas.md 中的对应章节

只有当任务涉及多个主题时才组合参考资料：例如，本地化 Structured Text 编辑需要本地化和编辑指南。不要仅仅因为内容操作使用了脚本，就加载迁移或类型生成指南。

4. 构建操作

• 使用所选运行时的已认证客户端、可用辅助工具和脚本形式。不要将 CLI 全局配置、导入语句或文件模式约定移植到其他运行时。构建客户端时，从环境变量读取凭据，切勿从聊天内容或硬编码字符串中获取；仅使用所需的最低权限，并在适用时明确指定沙盒环境。
• 优先使用简化 API。只有在任务需要 JSON:API 负载或关系元数据时，才使用原始方法。可用时，使用 listPagedIterator() 配合 for await...of 完整遍历集合。对于 nested: true 的 items，将 perPage 保持在 ≤ 30（默认值）：API 会拒绝更大的分页；迭代器不会自动调低该值。嵌套记录：自身字段会被展平（record.title），嵌入的区块字段仍保留在 block.attributes 下。
• 对本地化内容、区块或 Structured Text 的编辑，使用一个脚本读取当前记录，然后进行转换（CLI 模式下使用 cma:script）。需要时获取嵌套区块，并使用类型化区块辅助工具。保留无关字段、本地化内容、区块、链接和上传元数据；避免根据不完整读取结果重建整条记录。
• 对于 Structured Text，遵循编辑参考中的文本往返、类型化节点／区块修改，然后追加到根节点的顺序。除非要求替换，否则保留现有区块的身份和引用。
• 在记录调用和辅助工具中使用精确的项目类型。优先使用类型推断和类型守卫；绝不使用 any、unknown 或掩盖类型不匹配的类型断言。提供的项目类型无需本地生成步骤。只有需要自身类型模块的本地代码才遵循类型生成指南。
• 在操作边界使用所选运行时的功能处理 API 错误，包括运行时提供的 ApiError 和 TimeoutError。准确报告身份验证和权限错误；不要通过其他途径绕过这些错误。超时或缺少写入响应意味着操作结果不确定：任何重试前先检查最终状态，绝不要通过其他途径或工具重放该写入。
• 对于长时间运行的脚本，使用所选运行时的输出功能报告进度和最终总数。

5. 验证并报告

使用相同的项目、环境和授权范围进行验证。将已保存的字段／节点值与原始读取内容的独立快照进行比较；对象应使用深度相等比较。对象身份和序列化后的更新负载无法证明内容得到保留。嵌套读取会将区块 ID 和部分更新扩展为完整对象。检查所请求的更改、无关内容、本地化内容、链接和发布状态。发布需要单独授权。根据所选运行时契约验证脚本类型、辅助工具、分页和错误处理。

报告实际执行和验证的内容，包括部分完成或结果不确定的情况。对于本地代码交付物，应区分验证与实时执行。只有当该交付物或所选途径需要本地 CLI 设置时，缺少本地 CLI 设置才相关。

其他任务

CLI 配置、迁移、模式生成、CLI 环境工作流、入门导入、插件管理、多项目同步和 CI/CD，请使用 datocms-cli。当用户希望规划或逐步完成设置（迁移加发布、多项目同步、向项目导入内容、webhook／构建触发器）时，请使用 datocms-setup。对于纯 DAST 构建、检查、编辑和转换，请在任何项目设置之前使用 datocms-structured-text；如果 CMA 操作会持久化文档，则将其与此技能结合使用（日常记录操作无需使用它）。GraphQL 内容读取请使用 datocms-cda，框架代码请使用 datocms-frontend-integrations，插件开发请使用 datocms-plugin，不涉及实现的建模决策请使用 datocms-content-modeling。

缺少同级参考资料 → 从 datocms/agent-skills 安装该技能，或更新完整技能包。