step-by-step

一步一步来

用户第一次做某件常客觉得显而易见的事——创建 PAT、指向域名、配置 CI 密钥。他们不想听理论，只想要一份可以按顺序直接操作的编号清单，其中每个值都已填写，每个链接都可以点击。

你要产出的是一个操作步骤块：一条完整发送的交接消息，发送后就停下来等待。

操作步骤块

Now you: <what they are about to do>

<One line: what sits blocked until this is done.>

1. Open <full URL>
2. <Field>: <the exact value to type>
3. <Choice>: <the exact option to pick>. <The trap, if there is one.>
...
N. Test it: <full URL> → <what to click>

<What they see if it worked.> Tell me and I check it.

让步骤易于执行的要点：

• 每个值都写具体。 Token name: habits-context-sync，而不是“给它起个名字”。你已经知道仓库、所有者和密钥名称——从环境中找出来并填好。占位符就是把决策推回给求助的人。
• 每个链接都给出完整 URL，并尽可能指向具体页面。 https://github.com/settings/personal-access-tokens/new，而不是“前往 Settings → Developer settings”。如果页面没有稳定的 URL，就给出从一个有稳定 URL 的页面开始的点击路径。
• 在会踩坑的步骤里说明陷阱。“资源所有者：在下拉菜单中选择 Habits-Family。不要选你的个人账户。”这里选错了，直到很久之后才会发现。
• 说明哪些事情会自动发生，避免意外出现的字段让用户卡住：“（会自动添加只读 Metadata 权限。）”
• 把分支情况写在对应步骤里，不要另起一份清单：“如果显示 pending approval：前往 <url> 自行批准。”
• 最后一步是测试，并说明用户应该看到什么结果。

写界面操作步骤，而不是系统说明：使用他们眼前按钮上的实际文字。

流程

1. 先完成你能做的部分

所有能通过终端完成的事，都现在做完——在写操作步骤块之前。剩下的部分才需要浏览器、控制面板或密码。剩下的部分也决定了开场白：此刻有哪些事情正等着用户采取行动。

完成标准： 剩下的每一步都确实需要人工操作。

2. 查明实际操作流程

从一手来源获取点击路径——供应商的最新文档，或页面本身。第三方界面的名称会变，凭记忆提供的路径会让用户找不到已不存在的按钮。从环境中获取具体值：git 远程地址、.env、.env.example、.github/workflows/*（每个 secrets.* 引用都对应着操作步骤块必须生成的一个值）。

如果无法确认当前界面，就说明这一点并询问用户看到了什么。每一步都必须能追溯到你查证过的信息。

完成标准： 每一步都有 URL 和具体值，并且你知道最终测试能够验证什么。

3. 展示路线，然后交接

操作流程	发送内容
不超过约 30 步，一次完成	一个操作步骤块。用编号清单列出路线。
超过约 30 步、中途需要等待，或需要分多次完成	先给出路线——每个部分占一行——然后只发送第 1 部分。

长流程应按衔接点切分，而不是按步骤数切分：每个部分都应是一项完整连贯的任务，并以用户可以检查的结果结束（“令牌已创建”“密钥已设置”“工作流运行成功”）。在表单填写到一半时结束就是糟糕的切分，即使刚好达到 30 步也一样。每个部分的标题都写成 现在由你操作（2/4）：配置密钥，并从 1 重新编号步骤。

然后停下来。每条消息只发送一个部分，等用户完成后再发送下一部分。

4. 处理反馈

无论用户反馈什么——已完成、遇到错误，或看到的界面与你描述的不符——都要先处理好，再继续下一部分。界面不匹配说明你的信息来源已过时：去查找当前的操作路径。

5. 验证结果

尽可能亲自运行最后的检查，让目标得到实际验证，而不是仅凭假设。

密钥

密钥应从显示它的页面直接进入使用它的字段。在操作步骤中：

• 为密钥单独设置一个步骤，明确写出确切的目标位置：密钥名称和设置 URL、.env 中对应的行，或密钥链条目。
• 在创建密钥的步骤中原样写明“不要把它粘贴到此聊天中”。这段对话会成为记录，而记录不是密钥存储。
• 在一次性值生成时标记它们：“现在复制，它只会显示一次。”

确认他们获取了正确的值时，检查某个属性——前缀、长度或末四位——而不是检查值本身。如果某个值必须传给你运行的工具，请使用不会将其打印出来的路径：通过 gh secret set NAME 提示输入，或使用 read -s。

如果密钥还是出现在聊天中：明确说明情况，让他们撤销并重新签发，然后继续使用新密钥。