企业官网建设流程全解析

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体

导读

Warp 是一个以终端为起点的 agentic 开发环境，其开源仓库（README.md）采用了一套由 AI 智能体Oz深度参与的贡献模型：自动分诊（triage）、规格驱动开发（spec-driven development）、自动代码评审与 SME 复审。这篇指南以仓库根目录的CONTRIBUTING.md为骨架，完整梳理「提交 Issue → 获得就绪标签 → 编写 Spec PR / 代码 PR → 通过两阶段评审 → 合入 master」的每一步规则，并结合仓库内真实的 Spec 目录（如specs/GH408/）、skills-lock.json技能清单、.agents/skills/智能体上下文与script/下的工程脚本，说明这套流程背后的实现细节与验证手段。读完你不仅知道「怎么贡献」，更能理解「为什么贡献要先写 Spec、为什么评审由 Agent 自动触发」。

Warp 贡献模型与常见开源项目的差异

Warp 的贡献流程由 Oz 自动接管了分诊、Spec 编写辅助、实现与评审的一部分工作，因此与常规开源仓库相比有以下几点显著不同：

• 一切从 Issue 开始：讨论、范围界定与设计都发生在 Issue 上，PR 打开之前必须先有 Issue 作为锚点；仓库甚至要求 PR 必须关联 Issue（详见下文「无关联 Issue 的 PR」）。
• 功能请求与缺陷修复走不同通道：功能请求被ready-to-spec、ready-to-implement等就绪标签门禁，设计未定稿前不允许直接写代码；缺陷修复在报告可复现或可操作后可以直接提交代码 PR，除非范围或设计尚不清晰。
• 评审高度自动化：PR 一打开，Oz 就被自动指派并产出初审；Oz 批准后，会自动向 Warp 团队相关领域的主题专家（SME）请求复审，无需贡献者手动指定人类 reviewer。
• 规格（Spec）先行：较大的功能必须在写代码前先提交一个包含product spec与tech spec的 Spec PR，两个文档以specs/GH<issue号>/下的product.md与tech.md形式入库。

TL;DR：五条快速记住的规则

• 缺陷修复只要报告能从已有细节或维护者分诊中获得可操作性信息，就欢迎提交。
• 功能请求必须先被标记为ready-to-spec或ready-to-implement，PR 才会被接受。
• 标记为warp:reserved-internal的 Issue 由 Warp 团队内部处理，不开放贡献者 PR。
• Spec 是较大型问题开展技术与设计讨论的场所，代码写在前，Spec 必须先落库。
• Oz 自动分诊新 Issue 并评审公开 PR；实现类 PR 必须附带手工测试证据。

就绪标签：什么时候可以动手

Warp 团队在 Issue 就绪后施加以下标签之一，贡献者据此决定下一步动作：

任何人都可以认领带就绪标签的 Issue——就绪标签不是指派（assignment），最终通过正常评审流程择优合入。如果某个 Issue 长期未分诊或需要重新评估就绪状态，可以在评论中提及@oss-maintainers让团队介入。

贡献流程图

CONTRIBUTING.md用 Mermaid 流程图完整描述了从 Issue 到合入的闭环（贡献者负责的步骤为黄色，Warp 团队或 Oz 负责的步骤为蓝色）：

整个流程只有一条主路径：先有 Issue → 团队分诊打标签 → 按标签走 Spec PR 或代码 PR → Oz 初审 → SME 复审 → CI → 合入。自动分诊还可能在 Issue 上附加信息性标签（area:*、repro:*等），这些标签不影响就绪状态。

提交一个好的 Issue

提交前先在仓库的 Issue 列表搜索，避免重复；优先使用 Issue 模板。如果你已经在运行 Warp，最快的方式是输入/feedback命令——它会自动附带相关上下文（日志、环境信息）并打开一个公开 GitHub Issue。

缺陷报告清单

一个好的缺陷报告应包含：

• 清晰的标题 + 一段式问题总结；
• 复现步骤（尽量给出最小示例）；
• 期望行为 vs. 实际行为；
• Warp 版本与操作系统（可在Settings → About查看）；
• 相关日志、截图或屏幕录制。

缺陷经 Oz 的分诊 agent 或维护者确认为可操作后，可能被标记为ready-to-implement，随后即可认领并提交代码 PR。

功能请求清单

一个好的功能请求应先描述用户侧问题，再谈实现，包含：

• 用户需求或痛点，以及谁在经历它；
• 当前行为及其为何不足；
• 期望行为或工作流的草图（简短的示例或 mock 有帮助但不是必须）；
• 相关约束（兼容性、相关功能、已有先例等）。

功能请求是走 Spec 流程的通道：维护者在问题被理解、设计开放时施加ready-to-spec，下一步就是 Spec PR 而非代码 PR。

打开 Spec PR：product.md+tech.md

标记为ready-to-spec的 Issue 在写代码前必须先有 Spec。一个 Spec 由提交在specs/GH<issue-number>/下的两份短文档构成，仓库specs/目录下的真实例子可见specs/GH408/、specs/GH1063/、specs/GH1066/。

product.md（产品规格）

从消费者视角（用户、API 调用者、CLI 用户等）定义期望行为，不涉及实现细节。核心是一份编号的**可测试行为不变量（testable behavior invariants）**列表，覆盖：

• 主路径（happy path）；
• 用户可见状态；
• 输入与响应；
• 边界情况：空 / 错误 / 加载、取消、离线、权限拒绝、竞态、无障碍（accessibility）。

可选章节：问题陈述、目标 / 非目标（goals / non-goals）、Figma 链接、开放问题（open questions）。

以仓库中的specs/GH408/product.md为例，它针对「/open-file斜杠命令支持~展开」定义了：

• 现状问题：/open-file ~/foo.txt会被错误拼成/当前目录/~/foo.txt，永远报「File not found」；
• 目标：~展开到用户主目录，行为与 Cmd-O 打开文件面板一致；
• 非目标：不支持$HOME环境变量展开、不支持~otheruser语法、不改变自动补全路径逻辑；
• 边界情况：~单独出现应报「only works for files, not directories」错误；~/foo.txt:10:5行/列后缀需保留；带转义符的\~应先反转义再展开。

tech.md（技术规格）

这是落地到当前代码库的实现计划，必选章节包括：

• Context（背景）：当前系统状态与相关文件（带行号引用）；
• Proposed changes（拟议改动）：涉及的模块、新增类型 / API / 状态、数据流、权衡取舍；
• Testing and validation（测试与验证）：product spec 中的每条不变量如何被验证。

可选：端到端流程、Mermaid 图、风险、并行化、后续事项。

同样以specs/GH408/tech.md为例，它给出的实现非常收敛——只在app/src/terminal/input/slash_commands/mod.rs的路径解析链中加入一行shellexpand::tilde()，并逐个解释了PathBuf::join对绝对路径会整体替换 base 的行为，从而同时覆盖~路径、相对路径、绝对路径三种情况；风险部分还分析了$HOME未设置时shellexpand::tilde会原样返回输入的降级行为。

常用技能与版本锁定

Spec 写作技能来自warpdotdev/common-skills仓库，而不是直接写在本仓库内。本 checkout 通过根目录的skills-lock.json固定期望版本（其中记录了write-product-spec、write-tech-spec、implement-specs、review-pr、spec-driven-implementation等 30+ 技能及各自computedHash），bootstrap 脚本可以为你恢复它们：

./script/bootstrap # 默认安装或更新 common skills，需要时提示选择安装位置 ./script/bootstrap --install-common-skills-in-repo # 安装到本 checkout 的 .agents/skills/ ./script/bootstrap --install-common-skills-globally # 安装到 ~/.agents/skills/ WARP_COMMON_SKILLS_INSTALL_TARGET=project ./script/bootstrap # 非交互式选择 project 目标 WARP_COMMON_SKILLS_INSTALL_TARGET=global ./script/bootstrap # 非交互式选择 global 目标 ./script/bootstrap --skip-common-skills # 如果你自行管理 common skills，则跳过

安装完成后，/write-product-spec与/write-tech-spec技能可用于为你搭建 Spec 骨架。

打开 Spec PR 的步骤

1. 新增specs/GH<issue-number>/product.md和specs/GH<issue-number>/tech.md（示例见specs/GH408/，更多可浏览整个specs/目录）；
2. 把该 PR 作为产品与技术讨论的主阵地；
3. Spec 获批后，实现一般继续在同一 PR 上推进；个别情况（例如大 Spec 单独合入以便拆分实现）可迁移到链接的后续 PR。

打开代码 PR：就绪后的实操清单

对标记为ready-to-implement的 Issue：

1. 从master切分支；
2. 实现改动并添加测试（见下文「测试」一节）；
3. 推送前先运行./script/presubmit并修复所有失败；
4. 使用 PR 模板打开 PR（.github/pull_request_template.md），并添加 changelog 条目（CHANGELOG-NEW-FEATURE、CHANGELOG-IMPROVEMENT或CHANGELOG-BUG-FIX；仅文档或重构类改动可省略）；
5. PR 保持聚焦单个逻辑改动，并在进入评审前合并master。

不需要手动请求 reviewer：Oz 自动指派给指向就绪 Issue 的 PR 并产出初审；Oz 批准后自动向合适的 Warp 团队 SME 请求复审。推送处理 Oz 反馈的改动后，在 PR 上评论/warp-agent-review请求重新评审——每个 PR 最多三次；若流程卡住或需要更多评审，在 PR 上提及@oss-maintainers升级给团队。维护者请求改动的 PR，需要再次请求/warp-agent-review并通过后，Oz 才会自动发起 re-review。

必须包含手工测试证据：小型、孤立、可视化的改动应附before/after 截图；较大、广泛或交互式改动还应附带解说的屏幕录制。

无关联 Issue 的 PR

仓库要求 PR 关联 Issue（因为 Issue 是范围界定、就绪标签与 Spec 阶段的落点）。若你提前打开了 PR：

1. 先搜索关联 Issue——由于 Issue 量大，功能或缺陷通常已有对应 Issue。找到后在 PR 描述中链接它，理想情况下该 Issue 已由维护者施加就绪标签；
2. 若未找到，则新建 Issue 描述你的 PR 解决了什么，等待维护者审阅 Issue 与关联 PR 后施加就绪标签，以解锁最终检查；
3. 确保 PR 通过代码评审并包含相关测试，这能提高被优先审阅的信号。

使用 Coding Agent：允许但要求「以人对话」

你可以用任何编码 Agent（Warp 内置 Agent、Claude Code、Codex、Gemini CLI 等）实现贡献，也可以完全不用。本仓库为 Agent 提供了可读上下文：

• .agents/skills/下的技能（支持这些格式的 harness 都能读取）；
• specs/下的规格；
• 根目录的AGENTS.md。

如果你希望由Oz 云端 Agent代为实现一个就绪 Issue，在 Issue 上提及@oss-maintainers请求即可。获批的请求使用免费的 Oz 积分运行——你无需自建 Oz 账户或为算力付费。

同时要注意：虽然实现可以交给编码 Agent，但仓库期望贡献者以个人身份与团队协作——不要用 OpenClaw 之类的 Agent 代替你与团队对话。维护者始终以人类身份与你交流，请同样以人类身份回应。

两阶段评审机制

所有 PR 都经过两阶段评审：

1. Oz 评审：PR 打开时 Oz 自动被指派并产出第一份评审，检查正确性、风格、测试覆盖，以及与关联 Issue 和 Spec 的一致性；
2. Warp 团队评审：仅在 Oz批准之后，PR 才会被路由给 Warp 团队主题专家做最终人工评审。尚未被 Oz 批准的 PR 不会被分配给团队成员。

任何阶段都无需手动请求 reviewer。处理完 Oz 反馈后评论/warp-agent-review（每 PR 最多三次）请求 re-review；卡住或需更多评审时提及@oss-maintainers。

陈旧 PR 的自动关闭机制

若评审（Oz 或维护者）给 PR 留下changes requested后长期无动静，自动化会在 7 天与 10 天时发布提醒，第 10 天的提醒即最终警告；约14 天无活动后自动关闭（且一定先发过最终警告）。该机制仅针对处于活跃 requested-changes 评审状态的外部贡献者 PR。

• 只有你自己的活动能重置计时器：推送分支（包括 force-push）或评论 PR；维护者评论不会重置，因为球在你这边；
• 想保持 PR 开放就推送更新或回复；已关闭的 PR 可在你准备好后重新打开（reopen 并推送，或请维护者 reopen）；
• 维护者可施加no-autoclose标签豁免（例如 PR 被团队阻塞时）。

开发环境搭建与快速上手

完整工程指南见README.md与AGENTS.md。快速开始：

./script/bootstrap # 平台相关的环境搭建 cargo run # 构建并运行 Warp ./script/presubmit # fmt、clippy 与测试

本地直接运行应用可用./script/run（详见AGENTS.md）。

测试要求

大多数代码改动都需要测试：

手工测试

凡是能手工测试的改动都必须手工测试（几乎所有改动都能）。小型、孤立、可视化的改动附before/after 截图；较大、广泛或交互式改动还应附带解说的屏幕录制。

自动化测试

• 缺陷修复应包含能在修复前捕获该 bug 的回归测试；
• 算法或非平凡逻辑需要单元测试；
• 用户可见流程在可被端到端方式驱动时，应尽可能在crates/integration/下覆盖。标准是高质量覆盖你交付的改动——在 Agent 驱动的开发模式下，期望的是更多的集成测试，而不仅仅是 P0 路径的覆盖率。值得上线的流程通常也值得写一个集成测试。

运行单元测试：cargo nextest run。

以~展开功能为例，仓库在app/src/terminal/input_tests.rs中实现了test_open_slash_command_expands_tilde：它在$HOME下创建一个真实临时文件，把会话工作目录模拟到系统临时目录（故意与主目录不同），然后设置输入/open-file ~/warp_tilde_test_file.txt并触发input_enter，最后断言输入缓冲被清空（表示文件成功找到并打开）——这正是 tech spec 中「Unit test 应验证~展开优先于 cwd 拼接」的落地证据。对应的实现位于app/src/terminal/input/slash_commands/mod.rs的open_file_command_path，其解析链路依次是：CleanPathResult::with_line_and_column_number剥离:line:col后缀 →session.shell_family().unescape反转义 →shellexpand::tilde展开~→ 与current_dirjoin 并 normalize。Cmd-O 打开文件面板（app/src/search/command_palette/files/data_source.rs）同样调用shellexpand::tilde，这正是两条路径行为一致性的实现基础。

代码风格规范

• ./script/format --check与cargo clippy --workspace --all-targets --all-features --tests -- -D warnings必须通过；
• 优先使用 import 而非路径限定符、内联格式化参数（println!("{x}")）、穷尽式match而非_通配符；
• 完整风格指南（包括 WarpUI 模式与终端模型加锁规则）见AGENTS.md。

分支与提交约定

• 分支名以你的句柄为前缀，例如alice/fix-parser；
• 提交信息要说明what 与 why，而不仅是 what。

行为准则、安全与帮助

• 项目采用 Contributor Covenant，违规可发送至 warp-coc at warp.dev；
• 安全漏洞披露策略与私密报告渠道见SECURITY.md，不要在公开 Issue 中提交安全漏洞；
• 与其他贡献者和 Warp 团队在#oss-contributors频道交流（新用户需先加入 Warp Slack 社区）；可浏览 Warp 文档或直接打开 GitHub Issue 报告 bug 与功能请求。

小结

Warp 的贡献流程本质上是一条「规格驱动的 Agent 协作流水线」：Issue 承担范围界定，标签承担就绪门禁，Spec 承担设计共识，Oz 承担分诊与初审，SME 承担最终人工把关，skills-lock.json与script/脚本把规格写作、验证与 CI 固化到可重复执行的工程基础设施中。对贡献者而言，最关键的三个动作是：在 Issue 上对齐问题 → 等待正确的就绪标签 → 带着规格与手工测试证据提交 PR。理解这套模型，比照搬通用开源贡献套路更能在 Warp 仓库中高效落地你的改动。

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体