write-feature-docs

Name: write-feature-docs
Author: warpdotdev

write-feature-docs

为新 Warp 功能起草完整的文档页面。你阅读功能的规范，通过自行研究代码库验证技术声明，向工程师呈现简洁的大纲供确认，然后生成完整的 MDX 草稿并在 warpdotdev/docs 中打开草稿 PR——标记文档团队进行审查。

工程师的工作是确认你无法从规范和代码中验证的内容——而不是进行完整的准确性审查、润色文字或了解文档约定。

工作流程

查找并阅读规范文件
研究代码库以验证技术声明——尽量减少工程师需要检查的内容
生成简洁的大纲并等待工程师确认
生成完整的 MDX 草稿
4.5. 尝试通过计算机使用捕获截图（如果可用）
在 warpdotdev/docs 中打开草稿 PR 并标记文档团队

步骤 1：查找并阅读规范

如果工程师未提供规范 ID，请询问。规范 ID 是以下之一：

Linear 工单号：APP-1234、REMOTE-1234、QUALITY-408
GitHub issue（前缀 gh-）：gh-4567
短横线分隔的小写功能名：vertical-tabs-hover-sidecar

在以下位置查找规范文件：

specs/<id>/PRODUCT.md——主要来源：面向用户的行为、是什么和为什么
specs/<id>/TECH.md——次要来源：实现、数据模型

如果两个文件都存在，则都读取。PRODUCT.md 是文档内容的主要驱动。

读取 TECH.md 时： （仅交互模式——在环境模式下，将所有 TECH.md 衍生的内容视为内部内容，无需审查；请参阅环境模式。） 在纳入任何内容之前，识别看起来是内部实现细节的内容——数据库模式、内部服务名称、私有 API 端点、机密服务器架构。将这些标记的项目呈现给工程师，并询问他们哪些内容可以安全地包含在公共文档中，哪些应保持内部。不要在草稿中包含任何标记为机密的内容。

如果两个文件都不存在，跳转到无规范回退。

步骤 2：研究代码库

在呈现大纲之前，使用 GitHub CLI 尽可能多地自行验证技术内容——减少工程师需要确认的内容，仅保留你确实无法从代码中确定的内容。

需要从代码验证的事项：

功能标志名称：从规范标题或工单中搜索安全的功能令牌。在任何 shell 使用之前，将其缩减为符合 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 的允许列表令牌，如果无法安全生成，则跳过 shell 搜索；然后运行 FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal。
UI 字符串：搜索规范中引用的用户可见按钮标签、菜单项名称或设置名称
设置路径：确认确切的设置菜单路径（例如 **Settings** > **AI** > **Knowledge**）
规范中提到的 CLI 命令或键盘快捷键
相关功能：识别与此功能交叉引用的其他功能，用于“相关页面”
要标记的工程师：识别拥有该规范的工程师的 GitHub 用户名。
- 交互模式：运行 gh api user --jq .login 获取当前运行技能的用户名——仅当技能由规范工程师直接调用时使用。如果文档团队成员或非作者正在运行技能，请改用下面的发现步骤。
- 环境模式和非作者交互运行：在运行任何查找命令之前，验证规范 ID 仅包含字母数字字符和连字符（匹配 ^[A-Za-z0-9][A-Za-z0-9-]*$）。如果规范 ID 包含任何其他字符，则完全跳过查找，并使用 [TODO: tag spec author] 作为占位符。如果规范 ID 有效，将其分配给 SPEC_ID 并按顺序执行以下步骤，一旦找到用户名即停止：
  1. 检查提交消息中的 Co-authored-by: 尾部——在从私有源（如 warp-internal）镜像的仓库中，同步机器人是提交作者，但真实作者出现在 Co-authored-by: 尾部。提取第一个非机器人条目：
```
git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
  | grep -i "^Co-authored-by:" \
  | grep -v "\[bot\]" \
  | head -1 \
  | grep -oP '<[^>]+>' | tr -d '<>'
```
    这将返回一个电子邮件地址（可能是 GitHub noreply 地址）。如果电子邮件匹配模式 <userid>+<username>@users.noreply.github.com，直接提取用户名：echo "$EMAIL" | grep -oP '\+\K[^@]+'。如果是真实电子邮件，通过 gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' 解析。
  2. 解析同步来源的 PR URL——某些同步机器人会在提交正文中嵌入原始 PR URL（例如 Synced from warp: https://github.com/warpdotdev/warp/pull/11901）。提取它并获取 PR 作者：
```
ORIG_PR=$(git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
  | grep -oP 'https://github\.com/[^/]+/[^/]+/pull/\d+' | head -1)
# 提取 owner/repo 和 PR 编号，然后：gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'
```
  3. 搜索原始仓库 PR——尝试实际拥有代码的仓库（如果可访问，同时检查公共镜像和私有源）：
```
gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp-internal --state merged --json author --limit 1 --jq '.[0].author.login'
# 也尝试：gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp --state merged --json author --limit 1 --jq '.[0].author.login'
```
    跳过任何登录名包含 [bot] 的结果。
  4. 回退到提交作者电子邮件——仅当电子邮件不包含 [bot] 时：
```
EMAIL=$(git log --follow -1 --pretty=format:"%ae" -- "specs/${SPEC_ID}/PRODUCT.md")
```
    如果 ${EMAIL} 非空且无机器人，通过 gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' 解析为用户名。
  5. 如果所有步骤后仍未找到用户名，则在 PR 正文中使用 [TODO: tag spec author] 作为占位符。

对于你从代码验证的每个声明，将其标记为已确认。对于你无法验证的声明（代码中不存在的 UI 行为、产品意图、未发布功能的行为），在大纲中将其标记为 [UNVERIFIED]——这些是工程师需要关注的唯一内容。

步骤 3：生成并呈现大纲

生成简洁的大纲——无需散文。大纲显示你从研究中确认的内容以及确切需要工程师输入的内容。

以以下格式将大纲打印到终端：

📄 Docs outline for [功能名称]

PROPOSED PLACEMENT
  Section:  src/content/docs/<section>/   （例如 agent-platform/cloud-agents/）
  File:     <feature-name>.mdx
  URL:      docs.warp.dev/<path>/<feature-name>

CONTENT SECTIONS
  H1:  <功能名称>
  Opening paragraph: [你将撰写的 1 句描述]
  ## Key features — [要突出显示的 2-4 个能力作为要点]
  ## How it works — [概念模型：是什么和为什么，无步骤]
  ## <Usage section title> — [例如“创建环境”、“配置 X”]
      Prerequisites: [要列出的任何先决条件]
      Steps:
        1. [步骤描述]
        2. [步骤描述]
        3. [步骤描述]
        ...
  ## Related pages — [建议的交叉链接]

以上部分为默认值。根据功能调整大纲：如果功能不需要概念解释，则省略 ## How it works；如果功能有不同工作流，则添加多个使用部分；如果功能足够简单，则将 ## Key features 合并到开头段落中。

VERIFIED FROM CODEBASE ✅
  - [例如“功能标志：`my_feature_flag` 在 warp-internal 中确认”]
  - [例如“设置路径：确认为 Settings > AI > Agents > Permissions”]

NEEDS YOUR CONFIRMATION ⚠️
  - [例如“步骤 3——同步是自动触发还是需要手动操作？”]
  - [例如“在启用功能标志之前，‘Export’按钮是否可见？”]

打印大纲后，说：

“我已从代码库验证了能验证的内容。请检查上面标记 ⚠️ 的项目，并回复任何更正，或说‘looks good’继续。”

在继续之前等待工程师的回复。整合他们的反馈，然后起草。

步骤 4：生成 MDX 草稿

基于确认的大纲生成完整的 .mdx 文件。输出可直接放入 warpdotdev/docs。

模板结构

---
description: >-
  [1-2 句独立摘要。以用户收益开头。包含功能名称和一两个关键术语，以便作为搜索结果片段。]
---

# [功能名称]

[开头段落：功能的作用及其主要收益。
1-3 句。以用户能完成什么开头，而不是实现。]

:::note
[可选：读者需要预先了解的关键上下文——先决条件、限制或何时不使用此功能。如果不适用，删除此标注。]
:::

## Key features

* **功能 A** - 它的作用及其对用户的重要性。
* **功能 B** - 它的作用及其对用户的重要性。

## How it works

[概念部分：解释系统行为、数据流或架构。
在“如何”之前回答“是什么”和“为什么”。首次出现时定义任何新术语。此部分不要包含逐步过程——将概念和过程内容清晰分开。]

## [使用部分标题]

[过程部分：先说明任务动机，然后给出编号步骤。在告诉用户如何做之前，简要解释为什么用户要做这个。]

### Prerequisites

* **[先决条件]** - 它是什么以及在哪里获取。请参阅 [完整参考](link-here)。

### [任务名称——句子大小写，例如“使用 CLI 创建环境”]

1. 第一步。如果不明显，说明预期结果。
2. 第二步。
3. 第三步。

## Related pages

* [相关功能](../path/to/page.md)
* [更深入的指南](../path/to/guide.md)

样式规则——严格应用

这些约定来自 Warp 文档风格指南，必须遵循：

标题

所有标题使用句子大小写：仅大写第一个单词和专有功能名称
专有功能名称保持其大小写：“Agent Mode”、“Warp Drive”、“Oz”、“Command Palette”
✅ ## How it works — ❌ ## How It Works
✅ ## Agent Mode settings — ❌ ## Agent mode settings

列表

粗体术语 + 破折号 + 描述：* **Term** - Description
切勿使用冒号：❌ * **Term**: Description

UI 元素和路径

按钮、链接、菜单项使用粗体：Click **Save**，而不是 Click `Save`
设置路径中的每个段使用粗体，> 保持普通：**Settings** > **AI** > **Knowledge**

语态和语气

第二人称：“you can”、“allows you to”
主动语态：“Warp indexes your codebase”——而不是“your codebase is indexed”
避免“simple”、“easy”、“just”——这些轻视读者的体验
描述工作原理使用现在时；指令使用祈使句

Frontmatter 描述

编写为可作为搜索结果片段的独立摘要
以用户收益开头，包含功能名称和关键术语
✅ Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.
❌ This page describes environments.

标注语法（Astro Starlight）

:::note — 补充上下文、提示
:::caution — 注意事项、限制
:::danger — 破坏性或不可逆操作
:::tip — 有用的提示和最佳实践

哪些内容保留为 [TODO: docs reviewer — ...] 占位符

计算机使用未通过质量门、不可用或功能尚未发布时的截图
视频/GIF 嵌入
功能尚未发布时的确切设置路径
最终 URL 路径（文档团队确认放置位置）
工程师确认后仍未验证的任何行为

步骤 4.5：通过计算机使用捕获截图（如果可用）

生成草稿后，尝试使用计算机使用为任何 [TODO: docs reviewer — screenshot needed] 占位符捕获截图。此步骤是可选的——仅当 computer_use 工具可用时才运行。如果计算机使用不可用，则保留所有占位符。

决定尝试哪些截图

仅尝试满足所有以下条件的截图：

功能已发布（不在功能标志后或未发布）
UI 状态可以通过编程方式可靠导航到
占位符指定了具体的 UI 表面（不模糊，如“展示功能工作状态”）

跳过需要账户特定状态、特定数据或会暴露敏感信息内容的截图。

捕获前设置

在拍摄任何截图之前：

以一致的窗口大小启动 Warp（使用 warp-internal-computer-use 技能获取启动指导）
导航到相关 UI 表面或触发相关功能状态
等待所有动画完成且 UI 完全稳定
关闭不属于所记录功能的无关弹出窗口、通知或提示
关闭与此截图无关的任何侧边栏面板或窗格
验证没有敏感数据可见：检查令牌、API 密钥、私有仓库名称、客户工作区数据、电子邮件地址或个人身份信息。如果有任何可见，不要拍摄截图。

捕获协议：预测 → 捕获 → 验证 → 重试一次

这是一个结构化的自我验证循环。不要跳过它——它是防止错误状态、错误裁剪和错误框架捕获的主要保障。

步骤 1：在捕获前陈述预期

在拍摄任何截图之前，写出你期望看到的内容：

CAPTURE EXPECTATION
  Subject:            [正在记录的特定 UI 元素或表面]
  Expected elements:  [2-3 个必须可见的特定内容——例如面板标题、按钮、特定设置]
  Expected state:     [UI 状态——例如“设置面板打开”、“模态框可见”、“功能激活并显示输出”]
  Must not contain:   [任何不得可见的内容——例如敏感数据、无关弹出窗口、加载旋转器]

步骤 2：捕获

拍摄截图。

步骤 3：查看并根据预期验证

使用计算机使用查看捕获的图像，然后对照预期进行检查：

陈述的主题是否可见且清晰为焦点？
所有预期元素是否存在？
UI 是否处于预期状态（不是过渡或加载状态）？
不得包含的内容是否可见？
文本在目标显示宽度下是否清晰可读？

如果全部通过 → 进入质量门。

如果任何失败 → 再尝试一次：重新导航到 UI 状态，等待更长时间让 UI 稳定，然后重新捕获并重新验证。

如果第二次尝试也失败 → 丢弃截图并保留 [TODO: docs reviewer — screenshot] 占位符。不要包含你无法验证的截图。

步骤 4：质量门——包含前的最终检查

[ ] 截图中的文本在目标显示尺寸下清晰可读
[ ] 记录的 UI 元素清晰为焦点——未被埋没、裁剪或遮挡
[ ] 无敏感数据可见（令牌、私有仓库、个人信息、客户数据）
[ ] UI 处于稳定、非加载状态——无旋转器、骨架屏幕或过渡状态
[ ] 截图与捕获前陈述的预期匹配
[ ] 截图在目标渲染宽度下看起来合理，不模糊或过大

如果任何项目失败，丢弃截图并保留 [TODO: docs reviewer — screenshot] 占位符。

每次截图最多尝试次数：2。 如果两次都失败，继续。

尺寸——选择最接近的标准宽度

全宽（默认）——全窗口捕获、广泛的产品表面、周围上下文重要的布局
~375px——窄 UI 表面：弹出框、命令菜单、侧边窗格、下拉菜单、聚焦的交互流程
~300–350px——紧密裁剪的控件、芯片、按钮、工具提示、小菜单

在调整尺寸前裁剪不必要的空白空间。保持同一部分中截图序列的宽度一致。

放置——在 MDX 中插入截图的位置

插入每个截图：

紧接在介绍其显示的 UI 或状态的段落之后
靠近配置说明——显示用户做出选择的设置面板或菜单
靠近状态或结果说明——显示帮助用户识别成功的完成状态或输出
在视觉功能页面的开头——尽早使用宽泛的定向截图

不要为过程中的每一步添加截图。仅在视觉确实有助于理解时添加。

MDX 格式

<figure>
  <img
    src="[从此 MDX 文件到 src/assets/<section>/<feature-name>-<ui-state>.png 的相对路径——计算 MDX 文件的目录深度并使用那么多 ../ 级别；例如 3 级深度 → ../../../assets/<section>/...]"
    alt="[描述性替代文本：图像显示的内容，而不仅仅是‘screenshot’]"
  />
  <figcaption>[标题：完整句子，≤10 个单词，引导而非指示，无营销语言，句子大小写，以句号结尾。]</figcaption>
</figure>

替代文本规则：

描述图像显示的内容，而不仅仅是“screenshot”
✅ alt="Agent permissions settings with 'Always allow' selected for file reads"
❌ alt="screenshot" 或 alt=""

标题规则：

引导读者——描述显示的内容，而不是要做什么
完整句子，理想情况下 ≤10 个单词，绝不超过约 20 个单词
无营销语言（避免“easily”、“quickly”、“powerful”、“at a glance”）
不要重复正文——标题提供上下文，而不是回声
不要列出所有可见内容——命名主题
✅ <figcaption>The Environments page in the Oz web app.</figcaption>
❌ <figcaption>Click the toast to jump to the agent’s session.</figcaption>（过程性——将其放在正文中）

文件命名： 小写、连字符、描述性——例如 agent-mode-permissions-panel.png

文件位置： 将 PNG 保存到 warpdotdev/docs 中的 src/assets/<section>/（Astro 会自动优化它们）。

步骤 5：打开草稿 PR

生成草稿后，自动将其提交到 warpdotdev/docs：

将 warpdotdev/docs 克隆到临时目录（如果可用，使用本地克隆）
将 MDX 文件写入 src/content/docs/<proposed-section>/<filename>.mdx

在 src/sidebar.ts 的相应部分下添加占位符条目。示例：

// [TODO: docs reviewer — confirm placement]
{ label: '<功能名称>', link: '/<section>/<feature-name>/' },

在新分支 docs/<spec-id>-feature-draft 上提交并推送
将 PR 正文写入临时文件，然后使用 --body-file 打开草稿 PR。PR 描述必须包括：
- 功能名称和规范 ID
- 原始规范 PR 的链接
- 草稿中所有 [UNVERIFIED] 和 [TODO] 项目的列表，供审查者注意
使用任何可用的文件写入方法（文件创建工具、Python open() 调用或带有引用 heredoc 的 shell cat）将正文写入 /tmp/pr-body.md，然后将其传递给 gh：
```
gh pr create --draft --body-file /tmp/pr-body.md ...
```
切勿内联传递 PR 正文（通过 --body "..."、echo 或直接通过管道传递给 gh 的 printf）。Shell 字符串插值会在字符串到达 gh 之前展开反引号、$vars 和 [ ] 通配符模式，从而破坏包含这些字符的任何 markdown。先写入文件可避免所有对内容的 shell 解释。

在 PR 正文的“Docs outline”部分中，对代理验证的项目使用纯项目符号（-），而不是 - [x] 复选框。仅将 - [ ] 复选框保留给“需要审查的项目”部分，以便审查者确切知道哪些项目需要他们操作。
在 PR 正文中，使用步骤 2 中找到的用户名通知规范作者：
- 如果找到有效的 GitHub 用户名：包括 /cc @<engineer-handle>
- 如果产生了回退占位符：包括文字文本 [TODO: tag spec author]——不要将其包裹在 /cc @ 中，因为那会产生格式错误的提及
  请求 @rachaelrenk 和 @hongyi-chen 审查。

无规范回退

如果 specs/<id>/PRODUCT.md 和 specs/<id>/TECH.md 不存在，在采访工程师之前先研究代码库。

研究步骤：

在 warpdotdev/warp-internal（或根据上下文为 warp-server）中搜索功能名称和相关术语：gh search code "<feature-name>" --repo warpdotdev/warp-internal
阅读最相关的源文件以了解功能的作用
检查不同 ID 下的规范文件：gh api repos/warpdotdev/warp-internal/contents/specs
审查与功能相关的最近合并的 PR：gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10

研究后， 尽可能构建完整的图景，然后仅针对你无法从代码中填补的具体空白使用 ask_user_question——而不是作为广泛的采访。具体地提出问题：“我在 app/src/ai/ 中找到了该功能。根据代码，我理解如下：[摘要]。我无法确定这两件事：[具体问题]。”

根据你的研究和工程师的针对性回答构建大纲，然后在起草前进入步骤 3（大纲确认）。

环境模式（由 scan-new-specs 调用）

当此技能由 scan-new-specs 而非工程师直接调用时，它在环境模式下运行——没有交互式终端会话，因此大纲确认步骤必须以不同方式处理。

在环境模式下：

正常完成步骤 1 和 2（阅读规范、研究代码库）
跳过交互式大纲确认。 而是将大纲直接嵌入 PR 描述中作为检查清单：

## Docs outline (auto-generated)

The following outline was generated from the spec. **<engineer-review-request>: please review and check off each item, or leave a comment with corrections.** Use `@<engineer-handle>` when a valid handle was found; otherwise use `[TODO: tag spec author]` without an `@` prefix.

### Content structure
- [ ] H1: `<feature name>`
- [ ] Opening paragraph describes: [your 1-sentence summary]
- [ ] Key features section covers: [which capabilities]
- [ ] How it works section covers: [the conceptual model]
- [ ] `## <Usage section>` with steps: [numbered list]
- [ ] Related pages: [suggested cross-links]

### Items needing engineer verification ⚠️
- [ ] [UNVERIFIED item 1 — e.g. "Does this trigger automatically or require manual action?"]
- [ ] [UNVERIFIED item 2]

### Verified from codebase ✅
- [What was confirmed, e.g. "Feature flag: `my_feature` in warp-internal"]

生成完整的 MDX 草稿（步骤 4），但有以下约束：在环境模式下，不要起草任何源自 TECH.md 的内容。 没有工程师在场确认哪些是机密的，因此任何仅来自 TECH.md 的细节（实现内部、数据模型、服务器架构、私有 API 细节）都必须替换为 [TODO: engineer to verify — pulled from TECH.md, confirm this is safe to publish]。只有 PRODUCT.md 内容和代码库验证的事实可以在未经确认的情况下安全起草。
尝试截图（步骤 4.5）——如果计算机使用可用，为任何截图占位符运行预测然后验证的捕获协议。在草稿中包含通过质量门的任何截图。
正常打开草稿 PR（步骤 5）——在将大纲检查清单嵌入 PR 描述之前，将步骤 2 中找到的工程师用户名替换为 <engineer-handle>
不要向终端发布任何交互式消息；所有输出应进入 PR

你可能还喜欢

blucli

385Kresearch-knowledge

BluOS CLI (blu) for discovery, playback, grouping, and volume.

steipete

获取

agent-architecture-audit

237Kresearch-knowledge

Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature.

affaan-m

获取

triaging-issues

102Kresearch-knowledge

Triages GitHub issues by routing to oncall teams, applying labels, and closing questions. Use when processing new PyTorch issues or when asked to triage an issue.

pytorch

获取

继续探索

浏览 research-knowledge 热门 Skills 最近更新

write-feature-docs

相关 Skills

write-feature-docs

工作流程

步骤 1：查找并阅读规范

步骤 2：研究代码库

步骤 3：生成并呈现大纲

步骤 4：生成 MDX 草稿

模板结构

样式规则——严格应用

步骤 4.5：通过计算机使用捕获截图（如果可用）

决定尝试哪些截图

捕获前设置

捕获协议：预测 → 捕获 → 验证 → 重试一次

尺寸——选择最接近的标准宽度

放置——在 MDX 中插入截图的位置

MDX 格式

步骤 5：打开草稿 PR

无规范回退

环境模式（由 scan-new-specs 调用）

相关技能

你可能还喜欢

blucli

agent-architecture-audit

triaging-issues

继续探索