contributing

为 Cloudflare 文档做贡献

这是对 Cloudflare 文档仓库进行任何更改时要加载的唯一技能。它本身不包含具体细节，而是会引导你查阅适用于当前任务的参考资料。阅读与你的任务相符的参考资料，然后遵照执行。

不要猜测规范。以下参考资料是本仓库对内容编写、结构组织和验证方式的权威依据。

规范性参考资料优先于相互冲突的本地惯例，尤其是在产品分区名称、文件夹和排序方面。

基本规则

以下规则适用于所有任务。

• 这是一个开源公共仓库。 切勿在本仓库的页面、代码示例、提交、拉取请求、评论或其他任何位置放入 Cloudflare 私有信息、密钥、凭据、内部 URL 或环境变量值。如果对某项内容是否可以安全发布有任何疑问——哪怕只是轻微疑虑——请停止并询问用户。
• 从最新的 production 分支创建分支。 开始工作前，先从最新的 production 提交创建分支（运行 git fetch origin，然后从 origin/production 创建分支），除非用户要求使用其他基准分支。本仓库的默认分支是 production，不是 main。
• 切勿自动提交或推送。 修改文件后，询问用户是否要提交并推送。未经用户明确要求，不要运行 git commit 或 git push。

开始前：收集上下文

如果源材料过于简略或含糊，请暂停并在写作前询问用户。你需要掌握足够的信息，才能准确写作，而不只是排版良好。请询问缺少的信息：

• 事实依据——用于核实行为的 PR、RFC、工程规范、API 架构、现有页面或产品负责人。不要编造技术说明。
• 产品和功能领域——涉及哪个 Cloudflare 产品，以及更改属于该产品的哪个部分。
• 受众和意图——谁会阅读内容，以及他们想要做什么（快速入门、查找信息、遵循流程或理解概念）。
• 可用情况——计划的可用性（Free/Pro/Business/Enterprise）和生命周期状态（GA、Beta、Alpha）。
• 范围——这是新建页面、编辑内容、重组结构，还是添加变更日志条目。

如果用户已经提供了明确的规范或 PR，则无需再追问，直接继续。

任务索引

找到你的任务并阅读所列参考资料。除非路径前缀为 .agents/，否则路径均相对于此技能目录。

你的任务	阅读
编写或编辑文档页面	references/writing-docs.md（编写工作流——从这里开始）
决定使用哪种 pcx_content_type 和页面结构	references/content-types.md
决定如何呈现数据／使用哪个组件	references/choosing-components.md
决定页面归属、重定向和复用方式	references/information-architecture.md
查找写作和格式规则	.agents/references/style-guide.md（权威指南）和 .agents/references/procedures.md（分步说明）
查找组件的属性和示例	.agents/references/components.md
添加或编辑变更日志条目	references/changelog.md
审核文档／在 PR 中提出建议	references/reviewing-docs.md

references/writing-docs.md 中的编写工作流将这些步骤串联起来：收集背景信息 → 确定页面归属 → 选择内容类型 → 按照风格指南起草 → 为每部分数据选择组件 → 验证。

完成前进行验证

每次更改内容后都要运行验证。根据你的环境选择命令集——完整构建仅限本地运行。

pnpm run check              # Type-check: validates frontmatter schemas + Astro types
pnpm run build              # Full build: validates MDX parsing, image paths, internal links — LOCAL ONLY (times out in CI)
pnpm run format             # Auto-fix Prettier formatting on edited files

在 CI（CI=true）中，跳过 pnpm run build；仅运行 pnpm run check、pnpm run lint 和 pnpm run format:core:check。

如果修改了 public/__redirects，还要运行：

pnpm exec tsm bin/validate-redirects.ts

始终对你修改过的文件运行 pnpm run format——CI 会因内容格式不正确而失败。