step-by-step

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Step by step

分步操作指南

The user is doing something for the first time that a regular would find obvious — creating a PAT, pointing a domain, wiring a CI secret. They don't want the theory. They want a numbered list they can run straight down, with every value filled in and every link clickable.

What you produce is a block: one handover message, sent whole, after which you stop and wait.

用户是第一次执行这些对于熟手来说显而易见的操作——比如创建PAT、配置域名、设置CI密钥。他们不需要理论讲解，只需要一份可以直接照着执行的编号列表，其中所有值都已填好，所有链接均可点击。

你需要产出一个操作块：一条完整的交接消息，发送后就等待用户反馈。

The block

操作块格式

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.

What makes it followable:

Every value is literal.
```
Token name: habits-context-sync
```
, not "give it a name". You already know the repo, the owner, the secret name — dig them out of the environment and fill them in. A placeholder is a decision handed back to the person who asked for help.
Every link is a full URL, as deep as the site goes.
```
https://github.com/settings/personal-access-tokens/new
```
, not "go to Settings → Developer settings". Where a page has no stable URL, give the click path from one that does.
Name the trap in the step it bites. "Resource owner: pick
```
Habits-Family
```
in the dropdown. Not your personal account." A wrong pick here stays silent until much later.
Say what happens by itself, so an unexpected field doesn't stall them: "(Metadata: Read-only gets added by itself.)"
Fold the fork into its step rather than splitting the list: "If it says pending approval: approve it yourself at
```
<url>
```
."
The last step is a test, with the result they should see.

Write screens, not systems: name the button they are looking at, in the words printed on it.

现在你需要：<即将执行的操作>

<一句话说明：完成此操作前，哪些内容处于阻塞状态。>

1. 打开 <完整URL>
2. <字段名称>: <需要输入的精确值>
3. <选项>: <需要选择的精确选项>。<若存在陷阱，此处说明>
...
N. 测试：<完整URL> → <需要点击的内容>

<操作成功后的预期结果>。完成后告知我，我会进行检查。

让操作流程易于遵循的要点：

所有值均为字面量。例如
```
Token name: habits-context-sync
```
，而不是“给它起个名字”。你需要从环境中找出仓库、所有者、密钥名称等信息并填入。使用占位符相当于把决策交还给求助的用户。
所有链接均为完整URL，直达目标页面。例如
```
https://github.com/settings/personal-access-tokens/new
```
，而不是“进入设置→开发者设置”。如果页面没有稳定URL，给出从稳定URL开始的点击路径。
在陷阱出现的步骤中明确指出。例如“资源所有者：在下拉菜单中选择
```
Habits-Family
```
，不要选你的个人账户。”此处选错的话，问题可能会在很久之后才显现。
说明自动生成的内容，避免用户因意外出现的字段而停滞：“（备注：Read-only会自动添加。）”
将分支操作融入对应步骤，而非拆分列表：“如果显示pending approval：请在
```
<url>
```
自行批准。”
最后一步是测试，并说明预期结果。

描述具体界面，而非抽象系统：说出用户要点击的按钮上的文字。

Process

流程步骤

1. Do your half first

1. 先完成你负责的部分

Everything reachable from the terminal, do it now — before writing a word of the block. What is left over is the part needing a browser, a dashboard, or a password. That leftover is also what gives you the opening line: what is now sitting inert until they act.

Done when: every remaining step genuinely needs a human.

所有可通过终端完成的操作，现在就执行——在编写操作块的任何内容之前。剩下的部分就是需要用户通过浏览器、控制台或输入密码完成的步骤。这部分剩余内容也会成为操作块的开头：即用户操作前处于停滞状态的内容。

完成标志：剩余的每一步确实需要人工操作。

2. Get the real procedure

2. 获取真实操作流程

Take the click path from a primary source — the vendor's current docs, or the page itself. Third-party UIs get renamed, and a remembered path sends the user hunting for a button that no longer exists. Take the values from the environment: git remotes,

.env

.env.example

.github/workflows/*

(every

secrets.*

reference names a value the block has to produce).

Where you cannot confirm the current UI, say so and ask them what they see. Every step traces to something you checked.

Done when: every step has its URL and its literal values, and you know what the final test proves.

从官方来源获取点击路径——比如供应商的最新文档，或者页面本身。第三方UI可能会更名，凭记忆给出的路径会让用户找不到已不存在的按钮。从环境中获取具体值：git远程仓库、

.env

、

.env.example

、

.github/workflows/*

（所有

secrets.*

引用的名称都是操作块需要生成的值）。

如果无法确认当前UI的情况，请告知用户并询问他们看到的内容。每一步都必须有可验证的依据。

完成标志：每一步都有对应的URL和字面量值，且你清楚最终测试要验证的内容。

3. Show the route, then hand over

3. 展示整体流程，再移交操作

The procedure	What you send
Up to ~30 steps, one sitting	One block. Its numbered list is the route.
Over ~30 steps, or a wait in the middle, or more than one sitting	The route first — one line per part — then part 1 alone.

Cut a long procedure on its seams, not on the step count: each part is one coherent job that ends on something they can check ("the token exists", "the secret is set", "the workflow ran green"). A part that ends mid-form is a bad cut even at exactly 30 steps. Head each one

Now you (2 of 4): wire the secret

, and number its steps from 1 again.

Then stop. One part per message, with the next one held back until this one lands.

操作流程	你需要发送的内容
约30步以内，可一次性完成	一个操作块。其中的编号列表就是完整流程。
超过约30步，或中途需要等待，或需分多次完成	先发送整体流程概述——每个部分一句话描述——然后单独发送第一部分。

按照操作的逻辑分界点拆分长流程，而非单纯按步数：每个部分都是一个连贯的任务，结束时用户可以进行验证（比如“已生成令牌”、“已设置密钥”、“工作流执行成功”）。即使刚好30步，如果拆分后某部分在表单中途结束，也是不合理的拆分。每个部分开头标注

现在你需要（第2部分/共4部分）：配置密钥

，并将该部分的步骤重新从1开始编号。

然后停止发送。每次只发送一个部分，等待用户完成后再发送下一部分。

4. Take the report

4. 接收反馈

Whatever comes back — done, an error, a screen that doesn't match your description — settle it before the next part. A mismatched screen means your source went stale: go find the current path.

无论用户返回什么结果——完成、出错、界面与你的描述不符——都要先解决这些问题，再进行下一部分。界面不符说明你的来源已过时：需要重新查找当前的操作路径。

5. Prove it

5. 验证结果

Run the closing check yourself wherever you can reach it, so the goal ends up demonstrated rather than assumed.

只要你能访问到相关内容，就自行完成最终检查，确保目标确实达成，而非仅假设完成。

Secrets

密钥处理

A secret travels from the page that shows it straight to the field that consumes it. In the block:

Give it its own step, naming the exact destination: the secret name and the settings URL, the
```
.env
```
line, the keychain entry.
Write "don't paste it into this chat" into the step that creates it, in those words. This conversation becomes a transcript, and a transcript is not a secret store.
Flag one-shot values where they are produced: "Copy it now, it is shown once."

To confirm they captured the right value, check a property — its prefix, its length, its last four characters — never the value itself. Where a value has to reach a tool you run, use a path that never prints it:

gh secret set NAME

prompting for it, or

read -s

If a secret lands in the chat anyway: say so plainly, have them revoke and reissue it, and carry on with the new one.

密钥从显示它的页面直接传输到使用它的字段。在操作块中：

为密钥单独设置一步，明确指出精确的目标位置：密钥名称和设置URL、
```
.env
```
中的行、密钥链条目。
在创建密钥的步骤中写入“不要将其粘贴到此聊天窗口”，就用这句话。本次对话会成为记录，而记录并非密钥存储工具。
在生成一次性值时标注：“现在复制它，只会显示一次。”

为确认用户获取了正确的值，检查其属性——比如前缀、长度、最后四位字符——绝不要检查值本身。如果值需要传递到你运行的工具中，使用不会打印值的方式：比如

gh secret set NAME

提示输入，或

read -s

。

如果密钥不慎出现在聊天窗口中：直接告知用户，让他们撤销并重新生成，然后使用新的密钥继续操作。