contentful-custom-app-enhancement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contentful Custom App Enhancement

Contentful自定义应用增强

Use this skill to turn a bug report, support note, or feature request into a small, reviewable improvement for an existing Contentful custom app.

Default to the user's app repository and workflow. Do not assume a specific repository convention, publication process, or review policy unless the user provides one.

When a comparable public Contentful Marketplace app or example in Contentful's public apps repository (

https://github.com/contentful/apps

) exists, use it as a best practice reference for App Framework patterns and UX polish without inheriting its release or distribution workflow.

使用本技能可将漏洞报告、支持说明或功能请求转化为现有Contentful自定义应用的小型、可评审改进方案。

默认遵循用户的应用代码库及工作流程。除非用户明确说明，否则不要假设特定的代码库规范、发布流程或评审规则。

当存在类似的公开Contentful Marketplace应用或Contentful公开应用代码库（

https://github.com/contentful/apps

）中的示例时，可将其作为App Framework模式和UX优化的最佳实践参考，但无需沿用其发布或分发流程。

Inputs

输入内容

Accept:

bug reports,
customer or editor feedback,
support tickets or issue links,
screenshots or screen recordings,
direct requests to change a known custom app,
partial notes about an App Framework behavior.

If the source material is incomplete, continue with local code and provided context when the risk is low. Ask a targeted question when the missing answer could change the user-facing behavior, data writes, authentication, or deployment path.

接受以下类型的输入：

漏洞报告,
客户或编辑器反馈,
支持工单或问题链接,
截图或录屏,
针对已知自定义应用的直接变更请求,
关于App Framework行为的部分说明。

若源材料不完整，在风险较低的情况下，可结合本地代码及提供的上下文继续操作。当缺失信息可能影响用户端行为、数据写入、身份验证或部署路径时，需提出针对性问题。

Workflow

工作流程

1. Build the Request Context

1. 构建请求上下文

Identify:

original request and affected users,
current app behavior versus expected behavior,
Contentful location and workflow affected,
space, environment, content type, field, locale, and role assumptions,
external service or credential dependencies,
evidence available locally and evidence still missing.

Separate confirmed facts from assumptions.

明确以下内容：

原始请求及受影响用户,
应用当前行为与预期行为的差异,
受影响的Contentful位置及工作流程,
关于空间、环境、内容类型、字段、区域设置和角色的假设,
外部服务或凭证依赖,
本地已有的证据及仍缺失的证据。

区分已确认事实与假设内容。

2. Inspect the Existing App

2. 检查现有应用

Before editing:

check repository status and avoid overwriting user changes,
inspect
```
package.json
```
, scripts, lockfile, and framework conventions,
locate the relevant app locations and SDK usage,
review existing tests and nearby components,
identify app definition, installation parameters, and deployment notes if they exist,
confirm whether the app uses App SDK, React Apps Toolkit, Forma 36, contentful-management, App Actions, Functions, or an external backend.

For a reusable checklist, use Enhancement checklist.

在编辑前：

检查代码库状态，避免覆盖用户的变更,
查看
```
package.json
```
、脚本、锁文件及框架规范,
定位相关的应用位置及SDK使用情况,
审阅现有测试及相关组件,
识别应用定义、安装参数及部署说明（若存在）,
确认应用是否使用App SDK、React Apps Toolkit、Forma 36、contentful-management、App Actions、Functions或外部后端服务。

如需可复用的检查清单，请使用增强检查清单。

3. Decide Whether the Change Is Small Enough

3. 判断变更是否足够小

Proceed with implementation when the change can plausibly be:

scoped to one app,
explained in one short PR,
validated locally or in a sandbox,
reviewed without broad product redesign,
implemented without risky migrations or secret-handling changes.

Pause and clarify when the request requires:

production data changes,
a new external auth model,
major content model redesign,
multi-app coordination,
new backend infrastructure,
unavailable Function or plan capabilities,
ambiguous editor behavior.

当变更满足以下条件时，可继续实施：

仅针对单个应用,
可通过一份简短PR说明,
可在本地或沙箱环境中验证,
无需进行广泛的产品重设计即可评审,
无需进行高风险迁移或变更密钥处理方式即可实现。

当请求涉及以下内容时，需暂停并澄清：

生产数据变更,
新的外部认证模型,
内容模型重大重设计,
多应用协同,
新的后端基础设施,
不可用的Function或计划功能,
模糊的编辑器行为。

4. Plan the Smallest Useful Change

4. 规划最小可用变更

Write a short plan before editing:

files or app locations likely to change,
data read/write behavior,
UI and validation updates,
tests or manual verification to run,
risks and rollback path.

Prefer improving the existing flow over replacing it.

在编辑前编写简短计划：

可能变更的文件或应用位置,
数据读写行为,
UI及验证更新,
需运行的测试或手动验证步骤,
风险及回滚路径。

优先改进现有流程而非替换它。

5. Implement in the App's Existing Style

5. 按照应用现有风格实现

Reuse current framework, routing, hooks, components, and package manager.
Keep TypeScript precise and avoid broad
```
any
```
types.
Use Forma 36 for Contentful web app UI unless the app already uses another deliberate design system.
Preserve editor trust: show loading, empty, error, permission, and destructive action states when relevant.
Keep configuration UI explicit about what values are stored at installation versus instance scope.
Treat non-secret parameters as readable by space members.
When runtime locations need installation parameters, prefer
```
sdk.parameters.installation
```
. Do not add or preserve CMA app-installation reads in sidebar, field editor, entry editor, page, dialog, home, mount effects, render paths, or click handlers just to retrieve app configuration.
Do not expose tokens or private credentials in client code.
Keep changes narrow; avoid unrelated formatting, dependency churn, or refactors.

复用当前的框架、路由、钩子、组件及包管理器。
保持TypeScript类型精确，避免宽泛的
```
any
```
类型。
除非应用已使用其他明确的设计系统，否则使用Forma 36构建Contentful网页应用UI。
维护编辑器信任：在相关场景下显示加载、空状态、错误、权限及破坏性操作状态。
配置UI需明确区分安装范围与实例范围存储的值。
将非机密参数视为空间成员可读取的内容。
当运行时位置需要安装参数时，优先使用
```
sdk.parameters.installation
```
。不要在侧边栏、字段编辑器、条目编辑器、页面、对话框、首页、挂载效果、渲染路径或点击事件处理程序中添加或保留CMA app-installation读取操作，仅为获取应用配置。
不要在客户端代码中暴露令牌或私有凭证。
保持变更范围狭窄；避免无关的格式调整、依赖更新或重构。

6. Validate the Improvement

6. 验证改进效果

Run the closest available validation:

targeted unit or component tests,
typecheck,
lint or formatter check,
production build,
local dev server smoke test,
Contentful web app manual flow in a non-production space,
grep or ripgrep for
```
appInstallation.getForOrganization
```
,
```
appInstallation.get
```
, and
```
getForOrganization
```
when installation-parameter access is touched, confirming runtime config reads use
```
sdk.parameters.installation
```
or documenting why a CMA app-installation call remains,
App Action, Function, or backend endpoint test when the change touches server-side behavior.

When validation requires credentials or access the agent does not have, explain exactly what remains for the user to verify.

运行最接近的可用验证方式：

针对性的单元测试或组件测试,
类型检查,
代码检查或格式化检查,
生产构建,
本地开发服务器冒烟测试,
在非生产空间中手动测试Contentful网页应用流程,
当涉及安装参数访问时，使用grep或ripgrep搜索
```
appInstallation.getForOrganization
```
、
```
appInstallation.get
```
和
```
getForOrganization
```
，确认运行时配置读取使用
```
sdk.parameters.installation
```
，或记录为何仍需保留CMA app-installation调用,
当变更涉及服务器端行为时，测试App Action、Function或后端端点。

当验证需要代理不具备的凭证或访问权限时，需明确说明用户需要自行验证的内容。

7. Prepare Reviewable Output

7. 准备可评审的输出结果

If the user wants a commit or PR:

create a focused branch using the user's repo convention when known,
keep commits small and conventional,
do not stage unrelated local files,
include request context, implementation summary, validation, and open questions in the PR draft.

If the user only asked for the fix, end with:

context,
assessment,
implementation summary,
validation,
remaining risks or follow-up.

若用户需要提交commit或PR：

若已知用户的代码库规范，创建聚焦的分支,
保持提交内容简短且符合惯例,
不要暂存无关的本地文件,
在PR草稿中包含请求上下文、实现摘要、验证情况及未解决问题。

若用户仅要求修复问题，最终输出应包含：

上下文,
评估结果,
实现摘要,
验证情况,
剩余风险或后续工作。

Guardrails

约束规则

Do not force a code change when the better answer is product clarification.
Do not overfit one vague report without saying what is uncertain.
Do not widen the scope into a rewrite unless the user asks.
Do not assume app users have publication or distribution requirements unless they say so.
Do not claim Contentful plan features, SDK behavior, or API limits from memory when current official docs should be checked.

当更好的解决方案是产品澄清时，不要强制进行代码变更。
不要过度适配模糊的报告，需说明不确定的内容。
除非用户要求，否则不要将范围扩大为重写。
除非用户说明，否则不要假设应用用户有发布或分发需求。
当需要查询官方文档时，不要凭记忆声称Contentful计划功能、SDK行为或API限制。