contentful-custom-app-enhancement

Contentful 自定义应用增强

使用此技能，将 Bug 报告、支持备注或功能请求转化为对现有 Contentful 自定义应用的小型、易于评审的改进。

默认使用用户的应用代码库和工作流。除非用户提供相关信息，否则不要假设特定的代码库约定、发布流程或评审政策。

如果 Contentful Marketplace 中存在类似的公开应用，或 Contentful 公开应用代码库（https://github.com/contentful/apps）中存在相关示例，请将其作为 App Framework 模式和 UX 润色的最佳实践参考，但不要照搬其发布或分发工作流。

输入

接受以下内容：

• Bug 报告，
• 客户或编辑反馈，
• 支持工单或 Issue 链接，
• 屏幕截图或屏幕录制，
• 针对已知自定义应用的直接更改请求，
• 关于 App Framework 行为的不完整备注。

如果源材料不完整，且风险较低，请结合本地代码和已提供的上下文继续处理。如果缺失的信息可能影响面向用户的行为、数据写入、身份验证或部署路径，请提出有针对性的问题。

工作流

1. 梳理请求背景

识别以下信息：

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

将已确认的事实与假设分开。

2. 检查现有应用

编辑前：

• 检查代码库状态，避免覆盖用户的更改，
• 检查 package.json、脚本、锁文件和框架约定，
• 定位相关应用位置并检查 SDK 的使用情况，
• 查看现有测试和相邻组件，
• 确认应用定义、安装参数和部署说明是否存在，
• 确认应用使用的是 App SDK、React Apps Toolkit、Forma 36、contentful-management、App Actions、Functions 还是外部后端。

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

3. 判断改动是否足够小

如果改动有望做到以下几点，即可继续实施：

• 限定在一个应用内，
• 可在一个简短的 PR 中说明，
• 可在本地或沙盒中验证，
• 无需大范围产品重新设计即可评审，
• 无需进行高风险迁移或更改密钥处理方式即可实现。

如果请求涉及以下内容，请暂停并澄清：

• 更改生产数据，
• 新的外部身份验证模式，
• 大幅重新设计内容模型，
• 协调多个应用，
• 新建后端基础设施，
• 当前不可用的 Function 或计划功能，
• 模糊不清的编辑器行为。

4. 规划最小且有用的改动

编辑前编写简短计划，说明：

• 可能需要更改的文件或应用位置，
• 数据读取/写入行为，
• UI 和验证更新，
• 要运行的测试或手动验证，
• 风险和回滚路径。

优先改进现有流程，而不是将其替换。

5. 遵循应用现有的风格实现

• 复用现有的框架、路由、钩子、组件和包管理器。
• 保持 TypeScript 类型精确，避免宽泛的 any 类型。
• 除非应用已采用其他经过审慎选择的设计系统，否则 Contentful Web 应用 UI 应使用 Forma 36。
• 维护编辑器信任：在适用时显示加载、空内容、错误、权限和破坏性操作状态。
• 在配置 UI 中明确说明哪些值存储在安装级别，哪些存储在实例级别。
• 将非机密参数视为空间成员可读取的信息。
• 当运行时位置需要安装参数时，优先使用 sdk.parameters.installation。不要仅为读取应用配置，就在侧边栏、字段编辑器、条目编辑器、页面、对话框、主页、挂载副作用、渲染路径或点击处理程序中添加或保留 CMA 应用安装读取。
• 不要在客户端代码中暴露令牌或私有凭证。
• 控制改动范围；避免无关的格式调整、依赖变更或重构。

6. 验证改进

运行最贴近的可用验证：

• 针对性单元测试或组件测试，
• 类型检查，
• lint 或格式检查，
• 生产构建，
• 本地开发服务器冒烟测试，
• 在非生产空间中手动测试 Contentful Web 应用流程，
• 在涉及安装参数访问时，使用 grep 或 ripgrep 搜索 appInstallation.getForOrganization、 appInstallation.get 和 getForOrganization，确认运行时配置读取使用 sdk.parameters.installation，或说明为何仍保留 CMA 应用安装调用，
• 如果改动涉及服务端行为，则测试 App Action、Function 或后端端点。

如果验证需要 Agent 无法获取的凭证或访问权限，请准确说明用户还需要验证哪些内容。

7. 准备便于审查的交付内容

如果用户希望创建提交或 PR：

• 如果已知用户的仓库约定，则按该约定创建专注于本次改动的分支，
• 保持提交精简且符合常规规范，
• 不要暂存无关的本地文件，
• 在 PR 草稿中包含请求背景、实现概要、验证情况和未解决的问题。

如果用户只要求修复，结束时说明：

• 背景，
• 评估，
• 实现概要，
• 验证情况，
• 剩余风险或后续事项。

防护准则

• 如果更好的做法是先澄清产品需求，不要强行修改代码。
• 不要针对含糊的单一报告过度调整而不说明哪些情况尚不确定。
• 除非用户提出要求，否则不要将范围扩大到重写。
• 除非用户明确提出，否则不要假设应用用户有发布或分发要求。
• 如果应查阅当前官方文档，不要凭记忆断言 Contentful 套餐功能、SDK 行为或 API 限制。

相关技能

• contentful-custom-app-from-scratch - 设计并构建新的自定义应用。
• contentful-api - 具体的 REST 和 GraphQL API 示例。
• contentful-migration - 内容模型迁移脚本。
• contentful-guide - Contentful 概念和 API 路由。