datocms-plugin-builder

DatoCMS Plugin Builder

默认采用增强模式。快速推进，聚焦检查，尽量少改动。完成第一轮摸底后，不要重复探索已知内容。

步骤 1：选择路径

A. 初步发现相关界面

当无法明确需要修改的界面时使用。

1. 阅读 package.json，确认项目使用 datocms-plugin-sdk。
2. 找到调用 connect() 的入口（src/main.tsx、src/index.tsx）。
3. 修改钩子前先检查现有的 connect() 调用。
4. 根据请求，确定最小修改范围：
   • 配置界面 / 插件参数
   • 字段扩展或手动字段扩展配置
   • 侧边栏面板、完整侧边栏、出口或自定义页面
   • 下拉操作或生命周期钩子
   • 模态框、检查器、资源源或上传侧边栏
   • 记录展示或结构化文本自定义
   • 插件相关的依赖、构建或类型修复
5. 只阅读修改路径上的直接相关内容：
   • connect() 入口文件
   • 要编辑的组件或辅助函数
   • 也需要修改的导入文件
6. 沿用现有的文件布局、命名和 UI 模式。

B. 快速后续修改

当上下文或直接检查代码已明确相关界面时使用。

1. 只重新查看涉及的渲染分支、组件和辅助函数。
2. 确认钩子组合、参数形状和权限需求仍然匹配。
3. 直接修改现有分支、组件或辅助函数。
4. 除非代码无法解答问题，否则跳过全面重新探索。

对于明确的小改动，不要重复完整的探索流程。

步骤 2：只有仓库无法解答时才提问

默认不提问。

只有在错误假设会显著改变行为，且无法从仓库中找到答案时才提问：

• 使用哪个 DatoCMS 界面
• 目标模型或字段范围
• 是否允许新增权限或外部依赖
• 工作流必须使用 SDK 辅助函数，还是必须调用浏览器 CMA

如果不存在插件项目，或用户想新建插件目录，请切换到 datocms-plugin-scaffold。

步骤 3：只加载所需参考资料

从项目代码入手。

对于第 2 天 / 第 3 天的维护模式，先加载 references/rapid-patterns.md。然后只加载所需界面的直接参考资料。

界面参考资料

• 配置界面 / 插件参数 -> references/config-screen.md
• 字段扩展 / 单字段配置 -> references/field-extensions.md
• 侧边栏面板 / 完整侧边栏 -> references/sidebar-panels.md
• 自定义页面 -> references/custom-pages.md
• 下拉操作 -> references/dropdown-actions.md
• 生命周期钩子 -> references/lifecycle-hooks.md
• 模态框 -> references/modals.md
• 出口 -> references/outlets.md
• 检查器 -> references/inspectors.md
• 资源源 -> references/asset-sources.md
• 上传侧边栏 / 面板 -> references/upload-sidebars.md
• 结构化文本自定义 -> references/structured-text.md
• 记录展示 -> references/record-presentation.md

按需加载

• 在连接或调整钩子、渲染切换、模态框流程或框架尺寸行为时，加载 references/connect-conventions.md
• 仅在字段扩展之外读取 ctx.formValues，或处理结构化文本 / 模块化内容值时，加载 references/form-values.md
• 添加或移除插件权限、使用 ctx.currentUserAccessToken，或发布受权限控制的 UI 分支时，加载 references/permissions.md
• 仅当较小范围的参考资料无法解答更深入的 SDK 或浏览器 CMA 问题时，加载 references/sdk-architecture.md

小改动无需加载整套参考资料。

第 4 步：尽量精简补丁

优先编辑现有声明、渲染分发逻辑、组件或辅助函数，而不是重新组织插件。

• 除非移动文件能降低整体复杂度或减少重复的表层胶水代码，否则不要移动文件。
• 只有在能缩小补丁，或能隔离被修改流程使用的共享规范化逻辑／浏览器 CMA 逻辑时，才添加新文件。
• 尽量减少依赖变更，只添加代码实际使用的包。
• 除非用户要求重新设计，否则保留现有 UI 风格。

遵守以下要求：

• 添加钩子前检查现有的 connect() 调用。
• 顶层 connect() 调用必须且只能有一个。
• 当流程需要时，同时更新声明、渲染、执行和包权限。
• 用 <Canvas ctx={ctx}> 包裹渲染的 UI；仅在页面、检查器和全宽侧边栏中使用 noAutoResizer。
• 对按 ID 分发的渲染钩子使用 switch。
• 对 SDK 类型使用 import type { ... }。
• 读取记录数据前，先检查 ctx.item。
• 在字段扩展中使用 get(ctx.formValues, ctx.fieldPath)；其他位置使用 references/form-values.md 中的本地化值模式。
• 当依赖 ctx 对象属性时，使用 useDeepCompareEffect，而不是 useEffect。
• 确保 ctx.openModal() 的参数和 ctx.resolve() 的值可序列化为 JSON。
• 在读取／保存边界规范化已存储的插件参数，而不是重写整个屏幕。
• 在 renderManualFieldExtensionConfigScreen 中直接使用 ctx.setParameters()。
• 不要为模块化内容、单个区块或结构化文本字段创建编辑器字段扩展；应改用附加组件扩展。
• 对标准控件、间距和布局，优先使用 datocms-react-ui 和小型本地组件。
• 只有在标准组件无法清晰表达类似工具的交互时，才引入更复杂的自定义 UI。
• 保持插件屏幕和模态框简洁；避免仪表板式布局、嵌套面板、装饰性分区或过度架构设计。
• 仅当 SDK 辅助工具不足时才使用浏览器 CMA 流程；确保权限变更与运行时检查保持一致。

维护捷径

• 配置屏幕编辑：只规范化一次参数，保持保存逻辑精简；除非表单确实适合使用 react-final-form，否则使用普通本地状态。
• 资源来源 + 模态框：将 assetSources / renderAssetSource 作为主流程，仅在专注处理某个子步骤时使用模态框，最后调用 ctx.select()。
• 上传侧边栏 + 模态框：让侧边栏仅提供信息或单个操作，打开模态框进行专注编辑，并返回最精简的载荷。
• 高度／调整大小：优先信任 <Canvas ctx={ctx}>；首次绘制时设置 initialHeight，仅在异步内容或自定义布局变化需要时使用 ResizeObserver + ctx.updateHeight()。
• 从插件 UI 使用浏览器 CMA：优先使用 SDK 辅助工具；插件必须直接创建上传内容或记录时，使用 @datocms/cma-client-browser 和 ctx.currentUserAccessToken。
• 添加权限：只添加代码路径实际使用的权限，并确保 package.json、运行时检查和用户可见的操作入口保持一致。

第 5 步：用最精简的有效检查进行验证

运行现有验证中最轻量且能有效覆盖变更的一项：

• 对代码变更，默认运行仓库现有的构建脚本（npm run build、pnpm build 等）
• 如果项目已有最相关的测试或类型检查命令，则运行该命令
• 如果依赖发生变更，验证前使用仓库的包管理器安装依赖

如果仓库没有合适的脚本，则运行最接近的现有构建、类型检查或 lint 命令。

报告：

1. 你做了哪些更改
2. 你运行了什么
3. 仍需进行的一项 DatoCMS 手动检查

这项手动检查应与修改涉及的部分相符：配置保存流程、模态框解析流程、资源／上传选择流程、权限控制分支，或异步内容加载后的调整大小行为。

跨技能路由

• 从零开始创建插件 -> datocms-plugin-scaffold
• DatoCMS 插件原生界面设计、布局重设样式或设计系统对齐 -> datocms-plugin-design-system
• 在 iframe 中使用插件内嵌浏览器 CMA -> 留在此技能中
• 在插件 iframe 外编写独立的 CMA 脚本或处理 schema -> datocms-cma
• 在插件外处理前端预览、Content Link 或缓存标签 -> datocms-frontend-integrations