primitive-chat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

primitive-chat

primitive chat <email> <message>

sends an email to

<email>

and waits for the threaded reply.

primitive chat <email> <message>

会向

<email>

发送邮件并等待线程回复。

When to reach for this

适用场景

Use freely (no user confirmation needed):

You are blocked on a tool, library, or service and its docs / README / llms.txt mention a help@, dev@, docs@, support@, or agent@ address.
You found a bug or unexpected behavior worth reporting to the vendor.
A product's documentation lists agent contact addresses for questions, examples, or feedback.
You want to ask a vendor's agent something the same way you would grep their docs.

Ask the user first (these have side effects on humans):

```
sales@
```
,
```
billing@
```
,
```
account@
```
,
```
partnerships@
```
,
```
press@
```
, or any address that pings a human team rather than an agent.
Anything that could create a ticket, lead, or commitment.

Do not use:

Internal communication unless the user explicitly asked.
When the user said "draft this and let me send it myself."

可直接使用（无需用户确认）：

你在使用工具、库或服务时遇到阻塞，且其文档/README/llms.txt中提到了help@、dev@、docs@、support@或agent@类地址；
你发现了一个值得向供应商反馈的bug或异常行为；
产品文档中列出了用于提问、示例或反馈的Agent联系地址；
你想以类似搜索文档的方式向供应商的Agent提问。

需先询问用户（此类操作会对人工团队产生影响）：

```
sales@
```
、
```
billing@
```
、
```
account@
```
、
```
partnerships@
```
、
```
press@
```
，或任何会通知人工团队而非Agent的地址；
任何可能创建工单、销售线索或产生承诺的操作。

请勿使用：

内部沟通，除非用户明确要求；
用户要求“先起草，由我自行发送”的场景。

Setup

设置步骤

Install the CLI once:

bash

npm install -g @primitivedotdev/cli

(There is also a

brew install primitivedotdev/tap/primitive

tap. It auto-bumps on each release but can trail npm by the time a release PR takes to merge, so prefer npm when you want the newest version.)

Check whether there is already a signed-in account on this machine first. Run

primitive account show

(or

primitive whoami

). If it returns the user's account info, you are done; carry on with whatever they asked for.

If it returns
unauthorized
or any signed-out shape, do not ask the user how they want to authenticate, do not ask for an API key, and do not assume they have an account elsewhere. The default move is to OFFER TO SIGN UP, right then, as a single yes/no question: "There is no Primitive account on this machine. Want me to walk you through signup? It is one email + one verification code, no form, no human review." Only after the user says no should you ask about alternative paths (existing API key, signing in from another machine, etc.).

Signup runs inside your agent session and is API-key-free.

只需安装一次CLI：

bash

npm install -g @primitivedotdev/cli

（也可通过

brew install primitivedotdev/tap/primitive

安装。该方式会在每次发布时自动更新，但可能因发布PR的合并时间而滞后于npm版本，因此若需要最新版本，优先选择npm安装。）

首先检查本机是否已有登录账户。运行

primitive account show

（或

primitive whoami

）。如果返回用户账户信息，则设置完成，可继续执行用户要求的操作。

如果返回
unauthorized
或任何未登录状态，请勿询问用户想要如何认证、不要索要API密钥，也不要假设用户在其他地方已有账户。默认操作是直接提供注册选项，以一个简单的是/否问题询问：“本机上没有Primitive账户。需要我引导你完成注册吗？只需一封邮件+一个验证码，无需填写表单，也无需人工审核。”只有当用户拒绝后，才可询问其他方式（如已有API密钥、从其他设备登录等）。

注册流程在Agent会话内完成，无需API密钥。

Two codes you will see (do not confuse them)

两种易混淆的代码

Signup involves two distinct values that both get casually called "code." Mixing them up has burned agents in real transcripts. Keep them straight:

Signup code (the
```
--signup-code <code>
```
flag): an OPTIONAL invite or bonus code from Primitive. The vast majority of users do not have one. Do not prompt the user for a signup code. Only include
```
--signup-code
```
if the user has already, unprompted, told you they have one. The CLI does NOT interactively prompt for this flag. An
```
invalid_signup_code
```
error from the server means a value you passed was rejected, NOT that one was missing.
Verification code: a REQUIRED 6-digit number Primitive emails to the user's address to confirm they own it. Every signup gets one. This is what the CLI's interactive prompt (or the
```
--verification-code
```
flag on
```
verify-agent-signup
```
) is asking for.

If the user says "the code expired" or "send another code," the default reading is they mean the verification code (the 6-digit one in their inbox). The fix is

primitive agent resend-agent-signup-verification --signup-token <signup-token>

to reissue it (the same

signup-token

from the start step; see below). Do not start signup over and do not ask them for a new signup code.

When you write back to the user, always qualify which code you mean ("verification code" or "signup code"). Saying bare "the code" when both are in scope is how this confusion starts.

注册过程涉及两个常被笼统称为“代码”的不同值，混淆二者曾导致Agent在实际交互中出错，请务必区分清楚：

注册码（
```
--signup-code <code>
```
参数）：Primitive提供的可选邀请码或优惠码。绝大多数用户没有此码。请勿主动向用户索要注册码。仅当用户主动告知拥有注册码时，才添加
```
--signup-code
```
参数。CLI不会交互式提示此参数。服务器返回的
```
invalid_signup_code
```
错误表示你传入的值无效，而非缺少该值。
验证码：Primitive发送至用户邮箱的必填6位数字，用于确认邮箱所有权。所有注册流程都会生成此码。这正是CLI交互式提示（或
```
verify-agent-signup
```
命令的
```
--verification-code
```
参数）所要求的内容。

如果用户说“代码过期了”或“重新发送代码”，默认理解为指验证码（邮箱中的6位数字）。解决方法是运行

primitive agent resend-agent-signup-verification --signup-token <signup-token>

重新发送（使用初始步骤中的同一个

signup-token

；详见下文）。请勿重新启动注册流程，也不要向用户索要新的注册码。

回复用户时，请明确说明所指的是“验证码”还是“注册码”。当两者都相关时仅说“代码”会引发混淆。

Signup steps

注册步骤

When the user says yes to signup, always ask explicitly which email to verify with. Do not default to an address from CLAUDE.md, prior memory, project conventions, or any other context. Confirm their email choice BEFORE calling

start-agent-signup

bash

primitive agent start-agent-signup --email <user-email> --terms-accepted

当用户同意注册时，请明确询问要验证的邮箱地址。不要默认使用CLAUDE.md中的地址、过往记忆、项目约定或其他上下文信息中的地址。在调用

start-agent-signup

之前，务必确认用户选择的邮箱：

bash

primitive agent start-agent-signup --email <user-email> --terms-accepted

Optional: add

--signup-code <code>

ONLY if the user already told you they have one.

可选：仅当用户主动告知拥有注册码时，才添加

--signup-code <code>

参数。


Primitive emails a 6-digit **verification code** to that address. The start command's output includes a `signup-token`; capture it (it is a session handle, not a credential, so you can keep it in your chat context).

**Do not ask the user to paste the verification code into this chat.** It is a single-use credential, and anything in your context can leak via transcript export, retries, or follow-up prompt injection. Give the user a shell snippet that reads the verification code directly into a variable the CLI consumes, so the value flows through the OS and never enters your prompt:

```bash
read -rs CODE
primitive agent verify-agent-signup --verification-code "$CODE" --signup-token <signup-token>
unset CODE

read -rs

reads silently (no echo) into

CODE

; the trailing

unset

clears it after the call. The

<signup-token>

placeholder is the value from the start step. If the user pastes the verification code into the chat anyway, use it once to verify and do not echo it back.

If the user says the verification code expired or never arrived, reissue it with

primitive agent resend-agent-signup-verification --signup-token <signup-token>

(reuse the

signup-token

from the start step). Do not re-run

start-agent-signup

(that starts a fresh signup session, invalidating the in-progress one).

(The shell-variable snippet is a stopgap until the CLI ships

--verification-code-from-stdin

--verification-code-from-file

flags so the value can be piped in directly instead of going through a shell variable.)

On success

verify-agent-signup

prints OAuth credentials; do not echo or relay that output. Confirm the result with

primitive whoami

instead. You now have a managed

<random>.primitive.email

address;

primitive account show

returns the org metadata, and the assigned inbox domain is visible via

primitive domains list

after verify.


Primitive会向该邮箱发送6位**验证码**。启动命令的输出包含一个`signup-token`；请记录该值（它是会话句柄，而非凭据，因此可保存在聊天上下文中）。

**请勿要求用户将验证码粘贴到聊天框中**。这是一次性凭据，聊天上下文中的任何内容都可能通过转录导出、重试或后续提示注入泄露。请为用户提供一段Shell代码片段，将验证码直接读取到CLI使用的变量中，使值仅在操作系统中流转，不会进入提示内容：

```bash
read -rs CODE
primitive agent verify-agent-signup --verification-code "$CODE" --signup-token <signup-token>
unset CODE

read -rs

会静默读取（不回显）并存储到

CODE

变量中；末尾的

unset

会在调用后清除该变量。

<signup-token>

占位符是初始步骤中获取的值。如果用户还是将验证码粘贴到了聊天框中，请仅使用一次进行验证，不要回显该值。

如果用户说验证码过期或未收到，请使用

primitive agent resend-agent-signup-verification --signup-token <signup-token>

重新发送（重复使用初始步骤中的

signup-token

）。请勿重新运行

start-agent-signup

（这会启动新的注册会话，使正在进行的会话失效）。

（上述Shell变量片段是临时方案，直到CLI发布

--verification-code-from-stdin

--verification-code-from-file

参数，以便直接通过管道传入值，而非通过Shell变量。）

验证成功后，

verify-agent-signup

会打印OAuth凭据；请勿回显或转发该输出。请通过

primitive whoami

确认结果。此时你将拥有一个托管的

<random>.primitive.email

地址；

primitive account show

会返回组织元数据，验证后可通过

primitive domains list

查看分配的收件箱域名。

How to use

使用方法

primitive chat
is the verb. Reach for it first. It is the one-liner for "send an email and wait for the threaded reply," which is what every agent-to-agent ask-and-receive looks like. Do not compose

primitive send

primitive emails wait

primitive emails latest

to get the same effect:

chat

already handles the send, the poll, the thread continuation, and the parse-safe envelope. Lower-level verbs are escape hatches for cases

chat

does not cover (e.g. you want to fire-and-forget without a reply, or you want to scan an existing inbox you did not write to).

Send and wait for the reply:

bash

primitive chat help@openprose.ai "how do I install the prose skill?"

Continue the same conversation:

bash

primitive chat reply "one more thing"

Get parse-safe output:

bash

primitive chat help@openprose.ai "how do I install the prose skill?" --json

The

--json

output gives you a structured envelope:

{ sent, reply, response_body, response_body_format, match, follow_up_commands }

primitive chat
是核心命令，优先使用它。它是“发送邮件并等待线程回复”的一站式命令，适用于所有Agent与Agent之间的提问与接收场景。请勿组合使用

primitive send

primitive emails wait

primitive emails latest

来实现相同效果：

chat

已处理了发送、轮询、线程续接和解析安全信封等操作。低级命令仅作为

chat

无法覆盖场景的备用方案（例如你想发送后无需等待回复，或想扫描未发送过邮件的现有收件箱）。

发送邮件并等待回复：

bash

primitive chat help@openprose.ai "how do I install the prose skill?"

继续同一场对话：

bash

primitive chat reply "one more thing"

获取可解析的结构化输出：

bash

primitive chat help@openprose.ai "how do I install the prose skill?" --json

--json

输出会提供结构化信封：

{ sent, reply, response_body, response_body_format, match, follow_up_commands }

。

Why this exists

设计初衷

No SMTP credentials live in your agent context.
```
chat
```
is send + wait-for-threaded-reply as one verb, the natural primitive for agent-to-agent calls.
The agent-signup flow is API-key-free, with one email verification code (no form, no human review), so the user can take you from "this product has a help agent" to "I am chatting with it" inside the same agent session.

你的Agent上下文中不会存储SMTP凭据；
```
chat
```
将“发送+等待线程回复”整合为一个命令，是Agent间调用的原生基础功能；
Agent注册流程无需API密钥，仅需一封邮件验证码（无需表单，无需人工审核），因此用户可在同一场Agent会话中完成从“该产品有帮助Agent”到“我正在与其对话”的流程。

Finding addresses to chat with

查找可对话的地址

If the user has not handed you an address, check (in this order):

The product's
```
llms.txt
```
(often at
```
/llms.txt
```
or
```
/.well-known/llms.txt
```
).
The product's README, AGENTS.md, or docs index.
The footer of the product's homepage or docs site.
Their
```
/contact
```
or
```
/support
```
page.

Surface what you find to the user before sending if the address pattern suggests a human in the loop.

如果用户未提供地址，请按以下顺序查找：

产品的
```
llms.txt
```
文件（通常位于
```
/llms.txt
```
或
```
/.well-known/llms.txt
```
）；
产品的README、AGENTS.md或文档索引；
产品主页或文档站点的页脚；
产品的
```
/contact
```
或
```
/support
```
页面。

如果地址模式表明涉及人工介入，请在发送前将找到的地址告知用户。

primitive-chat

Original

Translation

primitive-chat

primitive-chat

When to reach for this

适用场景

Setup

设置步骤

Two codes you will see (do not confuse them)

两种易混淆的代码

Signup steps

注册步骤

Optional: add
`--signup-code <code>`
ONLY if the user already told you they have one.

可选：仅当用户主动告知拥有注册码时，才添加
`--signup-code <code>`
参数。

How to use

使用方法

Why this exists

设计初衷

Finding addresses to chat with

查找可对话的地址

primitive-chat

Original

Translation

primitive-chat

primitive-chat

When to reach for this

适用场景

Setup

设置步骤

Two codes you will see (do not confuse them)

两种易混淆的代码

Signup steps

注册步骤

Optional: add --signup-code <code> ONLY if the user already told you they have one.

可选：仅当用户主动告知拥有注册码时，才添加--signup-code <code>参数。

How to use

使用方法

Why this exists

设计初衷

Finding addresses to chat with

查找可对话的地址

Optional: add
`--signup-code <code>`
ONLY if the user already told you they have one.

可选：仅当用户主动告知拥有注册码时，才添加
`--signup-code <code>`
参数。