datocms-plugin-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DatoCMS Plugin Builder

DatoCMS 插件构建器

Default to augment mode. Move fast, inspect narrowly, and keep edits small. After the first grounding pass, stop rediscovering surfaces you already know.

默认使用增强模式。快速推进、聚焦检查、保持小幅修改。完成首次基础检查后，无需重复查看已熟悉的内容。

Step 1: Pick the path

步骤1：选择路径

A. Initial surface discovery

A. 初始内容范围探索

Use this when the touched surface is not yet obvious.

Read
```
package.json
```
and confirm the plugin uses
```
datocms-plugin-sdk
```
.
Find the entry file that calls
```
connect()
```
(
```
src/main.tsx
```
,
```
src/index.tsx
```
, or equivalent).
Inspect the existing
```
connect()
```
call before changing any hook.
From the user request, identify the smallest touched surface:
- config screen / plugin parameters
- field extension or manual field extension config
- sidebar panel, full sidebar, outlet, or custom page
- dropdown action or lifecycle hook
- modal, inspector, asset source, or upload sidebar
- record presentation or structured text customization
- dependency, build, or type fix around the plugin
Read only the direct path of the change:
- the
```
connect()
```
  entry file
- the component or helper being edited
- any imported file that must change too
Reuse the current file layout, naming, and UI patterns.

当修改范围尚不明确时使用此方法。

阅读
```
package.json
```
，确认插件使用
```
datocms-plugin-sdk
```
。
找到调用
```
connect()
```
的入口文件（如
```
src/main.tsx
```
、
```
src/index.tsx
```
或同类文件）。
在修改任何钩子之前，先检查现有的
```
connect()
```
调用。
根据用户需求，确定最小的修改范围：
- 配置界面 / 插件参数
- 字段扩展或手动字段扩展配置
- 侧边栏面板、完整侧边栏、Outlet或自定义页面
- 下拉操作或生命周期钩子
- 模态框、检查器、资源源或上传侧边栏
- 记录展示或结构化文本自定义
- 插件相关的依赖、构建或类型修复
仅阅读与修改直接相关的路径：
- ```
connect()
```
  入口文件
- 待编辑的组件或辅助函数
- 任何必须修改的导入文件
复用当前的文件布局、命名和UI模式。

B. Fast follow-up edit

B. 快速跟进修改

Use this when prior context or direct repo inspection already makes the surface obvious.

Re-open only the touched render branch, component, and helper.
Confirm the hook pair, parameter shape, and permission needs still match.
Patch the existing branch/component/helper directly.
Skip broad rediscovery unless the code stops answering the question.

Do not repeat full discovery for obvious small edits like label renames, config cleanup, option removal, one-hook wiring, modal copy tweaks, or validation adjustments.

当已有上下文或直接查看仓库后已明确修改范围时使用此方法。

仅重新打开涉及的渲染分支、组件和辅助函数。
确认钩子配对、参数结构和权限需求仍匹配。
直接修补现有的分支/组件/辅助函数。
除非代码无法解答问题，否则跳过全面的重新探索。

对于明显的小幅修改，如标签重命名、配置清理、选项移除、单钩子连接、模态框文案调整或验证规则修改，无需重复全面探索。

Step 2: Ask only if the repo cannot answer

步骤2：仅在仓库无法解答时提问

Ask zero questions by default.

Only ask when a wrong assumption would materially change behavior and the repo cannot resolve it, such as:

which DatoCMS surface to use
which model or field scope to target
whether a new permission or external dependency is allowed
whether the flow must stay inside SDK helpers or must use browser CMA calls

If no plugin project exists, or the user wants a brand-new plugin folder, switch to

datocms-plugin-scaffold

默认不提问。

仅当错误假设会实质性改变行为且仓库无法解决时才提问，例如：

使用哪个DatoCMS功能模块
针对哪个模型或字段范围
是否允许添加新权限或外部依赖
流程是否必须使用SDK辅助函数，还是必须调用浏览器端CMA

如果不存在插件项目，或用户需要全新的插件文件夹，请切换至

datocms-plugin-scaffold

。

Step 3: Load only the needed references

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

Start from project code.

For day-2/day-3 maintenance patterns, load

references/rapid-patterns.md

first. Then load only the direct surface reference you need.

从项目代码开始。

对于日常维护模式，先加载

references/rapid-patterns.md

。然后仅加载所需的直接功能模块参考资料。

Surface references

功能模块参考资料

Config screen / plugin parameters ->
```
references/config-screen.md
```
Field extension / per-field config ->
```
references/field-extensions.md
```
Sidebar panel / full sidebar ->
```
references/sidebar-panels.md
```
Custom page ->
```
references/custom-pages.md
```
Dropdown actions ->
```
references/dropdown-actions.md
```
Lifecycle hooks ->
```
references/lifecycle-hooks.md
```
Modal ->
```
references/modals.md
```
Outlets ->
```
references/outlets.md
```
Inspector ->
```
references/inspectors.md
```
Asset source ->
```
references/asset-sources.md
```
Upload sidebar / panel ->
```
references/upload-sidebars.md
```
Structured text customization ->
```
references/structured-text.md
```
Record presentation ->
```
references/record-presentation.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
```
Outlet ->
```
references/outlets.md
```
检查器 ->
```
references/inspectors.md
```
资源源 ->
```
references/asset-sources.md
```
上传侧边栏 / 面板 ->
```
references/upload-sidebars.md
```
结构化文本自定义 ->
```
references/structured-text.md
```
记录展示 ->
```
references/record-presentation.md
```

Load conditionally

条件加载

```
references/connect-conventions.md
```
when wiring or adjusting hooks, render switches, modal flows, or frame sizing behavior
```
references/form-values.md
```
only when reading
```
ctx.formValues
```
outside field extensions, or when touching Structured Text / modular content values
```
references/permissions.md
```
when adding or removing plugin permissions, using
```
ctx.currentUserAccessToken
```
, or shipping permission-gated UI branches
```
references/sdk-architecture.md
```
only when the smaller references do not answer a deeper SDK or browser CMA question

Do not load the whole reference set for a small patch.

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

不要为小幅补丁加载全部参考资料。

Step 4: Patch minimally

步骤4：最小化补丁修改

Prefer editing the existing declaration, render switch, component, or helper over reorganizing the plugin.

Do not move files unless it reduces total complexity or removes repeated surface glue.
Add a new file only when it keeps the patch smaller or isolates shared normalization / browser-CMA work used by the touched flow.
Keep dependency changes minimal and only add packages that the code actually uses.
Preserve the existing UI style unless the user asked for a redesign.

Keep these guardrails:

Inspect the existing
```
connect()
```
call before adding hooks.
Keep exactly one top-level
```
connect()
```
call.
Update declaration, render, execute, and package permissions together when a flow needs them.
Wrap rendered UI in
```
<Canvas ctx={ctx}>
```
; use
```
noAutoResizer
```
only for pages, inspectors, and full-width sidebars.
Use
```
switch
```
for ID-dispatched render hooks.
Use
```
import type { ... }
```
for SDK types.
Guard
```
ctx.item
```
before reading record data.
Use
```
get(ctx.formValues, ctx.fieldPath)
```
in field extensions; use the localized-value patterns from
```
references/form-values.md
```
elsewhere.
Use
```
useDeepCompareEffect
```
instead of
```
useEffect
```
when depending on
```
ctx
```
object properties.
Keep
```
ctx.openModal()
```
parameters and
```
ctx.resolve()
```
values JSON-serializable.
Normalize stored plugin parameters at the read/save boundary instead of rewriting the whole screen.

Use

ctx.setParameters()

directly in

renderManualFieldExtensionConfigScreen

Do not create editor field extensions for modular content, single block, or structured text fields; use addon extensions instead.
Prefer
```
datocms-react-ui
```
and small local components for standard controls, spacing, and layout.
Introduce heavier custom UI only for tool-like interactions that standard components do not express cleanly.
Keep plugin screens and modals compact; avoid dashboard-style layouts, nested panels, decorative sections, or over-architecture.
Use browser CMA flows only when SDK helpers are not enough; keep permission changes and runtime guards aligned.

优先编辑现有的声明、渲染切换、组件或辅助函数，而非重新组织插件。

除非能降低整体复杂度或消除重复的功能模块粘合代码，否则不要移动文件。
仅当能缩小补丁范围或隔离修改流程中使用的共享规范化/浏览器端CMA工作时，才添加新文件。
最小化依赖变更，仅添加代码实际使用的包。
除非用户要求重新设计，否则保留现有UI风格。

遵循以下约束：

添加钩子前，先检查现有的
```
connect()
```
调用。
保持恰好一个顶层
```
connect()
```
调用。
当流程需要时，同步更新声明、渲染、执行和包权限。
将渲染的UI包裹在
```
<Canvas ctx={ctx}>
```
中；仅对页面、检查器和全宽侧边栏使用
```
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流程；保持权限变更和运行时约束一致。

Maintenance shortcuts

维护快捷方式

Config screen edits: normalize parameters once, keep save logic narrow, and use plain local state unless the form truly earns
```
react-final-form
```
.
Asset source + modal: keep
```
assetSources
```
/
```
renderAssetSource
```
as the main path, use a modal only for a focused sub-step, and finish with
```
ctx.select()
```
.
Upload sidebar + modal: keep the sidebar informational or single-action, open a modal for the focused edit, and resolve a minimal payload back.
Height / resizing: trust
```
<Canvas ctx={ctx}>
```
first; add
```
initialHeight
```
for first paint and use
```
ResizeObserver
```
+
```
ctx.updateHeight()
```
only when async or custom layout changes require it.
Browser CMA from plugin UI: prefer SDK helpers first; when the plugin must create uploads or records directly, use
```
@datocms/cma-client-browser
```
with
```
ctx.currentUserAccessToken
```
.
Permission additions: add only the permissions the code path actually uses, then keep
```
package.json
```
, runtime guards, and user-visible affordances in sync.

配置界面编辑：仅规范化一次参数，保持保存逻辑聚焦，除非表单确实需要
```
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
```
、运行时约束和用户可见功能同步。

Step 5: Verify with the smallest useful check

步骤5：用最小有效检查验证

Run the lightest existing verification that meaningfully covers the change:

the repo's existing build script (
```
npm run build
```
,
```
pnpm build
```
, etc.) by default for code changes
the most relevant test or typecheck command if the project already has one
install dependencies with the repo's package manager before verifying if dependencies changed

If the repo has no suitable script, run the closest existing build, typecheck, or lint command instead.

Report:

what you changed
what you ran
the one manual DatoCMS check that still matters

That manual check should match the touched surface: the config save path, the modal resolve path, the asset/upload selection flow, the permission-gated branch, or the resizing behavior after async content loads.

运行最轻量化的现有验证，确保能覆盖修改内容：

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

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

报告内容：

修改的内容
运行的命令
仍需手动检查的DatoCMS功能点

手动检查应与修改范围匹配：配置保存路径、模态框解析路径、资源/上传选择流程、权限 gated 分支，或异步内容加载后的调整大小行为。

Cross-skill routing

跨技能路由

New plugin from scratch ->
```
datocms-plugin-scaffold
```
Native DatoCMS plugin UI design, layout restyling, or design-system alignment ->
```
datocms-plugin-design-system
```
Plugin-embedded browser CMA usage inside the iframe -> stay in this skill
Standalone CMA scripts or schema work outside the plugin iframe ->
```
datocms-cma
```
Front-end preview, Content Link, or cache-tag work outside the plugin ->
```
datocms-frontend-integrations
```

从零开发新插件 ->
```
datocms-plugin-scaffold
```
原生DatoCMS插件UI设计、布局重设计或设计系统对齐 ->
```
datocms-plugin-design-system
```
在iframe内使用插件嵌入的浏览器端CMA -> 保留在本技能中
插件iframe外的独立CMA脚本或架构工作 ->
```
datocms-cma
```
插件外的前端预览、内容链接或缓存标签工作 ->
```
datocms-frontend-integrations
```