technical-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical writing

技术写作

Write accurate, task-focused documentation for eve. Treat developers and AI agents as readers: make each section easy to scan, retrieve, and act on without relying on unstated context.

为eve撰写准确、以任务为核心的文档。将开发者和AI Agent视为读者：确保每个章节易于浏览、检索和操作，无需依赖未明确说明的上下文。

Choose a workflow

选择工作流

For a new page or full rewrite, read references/writing-workflow.md.
For targeted or structural changes to existing pages, read references/editing-workflow.md.
Before finalizing any change, read references/review-framework.md.
For formatting and terminology, read references/style-rules.md.
For wording, voice, or AI-pattern concerns, read references/prose-quality.md.
For page structure, read references/content-types.md when the content type is unclear or changing.

如需创建新页面或完全重写，请阅读references/writing-workflow.md。
如需对现有页面进行针对性或结构性修改，请阅读references/editing-workflow.md。
在最终确定任何变更前，请阅读references/review-framework.md。
如需了解格式和术语规范，请阅读references/style-rules.md。
如需解决措辞、语气或AI模板化问题，请阅读references/prose-quality.md。
当内容类型不明确或需要变更时，请阅读references/content-types.md了解页面结构规范。

Verify before writing

写作前验证

Do not rely on training data for eve behavior. Use this source hierarchy:

Current source, public types, and tests in
```
packages/eve
```
Current CLI help and setup implementation
Existing pages under
```
docs/
```
Merged pull requests, changelogs, and release notes
Research plans under
```
research/
```
as proposed intent, not shipped behavior
Support evidence such as Slack threads or issues

Use support evidence to identify the reader's problem, not to establish product behavior. Verify commands, flags, API names, defaults, limitations, and examples against the current repository. For a docs-only change, also compare the implementation with the latest public release so the docs do not announce branch-only behavior. When docs accompany product code in the same change, state that dependency during review. If a claim cannot be verified, omit it or report the missing owner or source. Never leave

[VERIFY]

markers in a completed docs change.

不要依赖训练数据来了解eve的行为。请遵循以下来源优先级：

```
packages/eve
```
中的当前源码、公开类型和测试
当前CLI帮助和安装实现
```
docs/
```
目录下的现有页面
已合并的拉取请求、变更日志和版本说明
```
research/
```
目录下的研究计划（仅作为拟议意图，而非已发布的行为）
支持证据，如Slack线程或问题工单

使用支持证据来识别读者的问题，而非确定产品行为。对照当前仓库验证命令、标志、API名称、默认值、限制和示例。对于仅涉及文档的变更，还需将实现与最新公开版本进行对比，确保文档不会提前公布仅存在于分支中的功能。当文档变更与产品代码变更同步进行时，需在审阅时说明两者的依赖关系。如果某一内容无法验证，请省略该内容或报告缺失的负责人/来源。完成文档变更后，请勿留下

[VERIFY]

标记。

Follow eve conventions

遵循eve约定

Write
```
eve
```
lowercase, including headings and sentence starts when practical.
Use exact public names such as
```
defineAgent
```
,
```
eve dev
```
, and
```
eve add channel/slack
```
.
Distinguish the root agent, the built-in
```
agent
```
tool, declared subagents, and remote agents. They have different inheritance and execution semantics.
Distinguish eve connections from Vercel Connect, the model-facing
```
Workflow
```
tool from authored Vercel Workflows, and durable session state from sandbox filesystem or attachment storage.
Name diagnostic surfaces precisely: Vercel runtime logs, Agent Runs, OpenTelemetry,
```
eve logs
```
, and
```
eve traces
```
are not interchangeable.
Treat
```
docs/**
```
as published documentation. Update
```
docs/meta.json
```
when navigation changes.
Keep
```
.md
```
files framework-agnostic. Use MDX components only in
```
.mdx
```
files and only when nearby pages establish the convention.
Preserve published routes and heading anchors when possible. When moving a page, update authored links and add permanent redirects for old HTML and Markdown URLs.
Prefer TypeScript examples. Include imports and language labels, and verify examples against current exports.
Show only supported commands and flags. Check CLI help or the command implementation before documenting them.
Link to related pages with descriptive text. Include the critical fact locally because retrieved sections may be read without their links.
Do not document proposed behavior as shipped. Describe unsupported boundaries directly when they affect a user task.

小写书写
```
eve
```
，包括标题和句首（在可行的情况下）。
使用准确的公开名称，如
```
defineAgent
```
、
```
eve dev
```
和
```
eve add channel/slack
```
。
区分根Agent、内置
```
agent
```
工具、已声明的子Agent和远程Agent。它们具有不同的继承和执行语义。
区分eve连接与Vercel Connect、面向模型的
```
Workflow
```
工具与已创建的Vercel Workflows，以及持久会话状态与沙箱文件系统或附件存储。
精准命名诊断工具：Vercel运行时日志、Agent Runs、OpenTelemetry、
```
eve logs
```
和
```
eve traces
```
不可互换。
将
```
docs/**
```
视为已发布的文档。当导航发生变更时，更新
```
docs/meta.json
```
。
保持
```
.md
```
文件与框架无关。仅在
```
.mdx
```
文件中使用MDX组件，且仅在邻近页面已建立该约定时使用。
尽可能保留已发布的路由和标题锚点。移动页面时，更新所有相关链接，并为旧HTML和Markdown URL添加永久重定向。
优先使用TypeScript示例。包含导入语句和语言标签，并对照当前导出内容验证示例。
仅记录受支持的命令和标志。在记录前，请检查CLI帮助或命令实现。
使用描述性文本链接到相关页面。在本地包含关键信息，因为读者可能会单独阅读检索到的章节而不查看链接。
不要将拟议行为记录为已发布功能。当未支持的边界影响用户任务时，请直接说明。

Write for the task

为任务写作

Lead each page and section with the answer or outcome.
Address the reader as
```
you
```
; use imperative verbs for steps.
Prefer active voice, present tense, concrete nouns, and consistent terms.
Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit and leave strong prose alone.
Keep one page focused on one primary job. Add a section to an existing page when it already owns the task.
Put the happy path before alternatives and failure modes.
Add troubleshooting where observed failures cluster around a workflow. Use symptoms, verified causes, and concrete next checks.
Write self-contained sections. Repeat the full noun in key statements instead of relying on ambiguous pronouns.
Use specific limits and behavior only when the repository or an authoritative platform source supports them.

每个页面和章节开头直接给出答案或预期结果。
使用
```
你
```
称呼读者；步骤使用祈使动词。
优先使用主动语态、现在时、具体名词和一致的术语。
保留作者所支持的含义、细微差别和不确定性。仅进行必要的修改，保留优质的原文内容。
每个页面聚焦于一项核心任务。若现有页面已涵盖该任务，可将内容添加至该页面的对应章节。
先描述正常流程，再介绍替代方案和失败场景。
在故障集中出现的工作流附近添加故障排除内容。使用症状、已验证的原因和具体的后续检查步骤。
编写独立完整的章节。在关键陈述中重复完整名词，避免依赖模糊的代词。
仅当仓库或权威平台来源提供支持时，才使用具体的限制和行为描述。

Avoid common failures

避免常见错误

Do not invent flags, registry entries, connectors, workarounds, or platform guarantees.
Do not turn one product request into a new page. First decide whether the gap belongs to docs, product, or both.
Do not duplicate broad guides when a focused section or cross-link resolves the problem.
Do not rewrite clear prose merely to match a personal preference.
Do not manufacture examples, opinions, reactions, or specificity to make prose sound more human.
Do not use promotional language, rhetorical questions, filler, or claims that a task is easy, simple, or quick.
Do not use
```
we
```
unless describing a deliberate Vercel or eve team action.

不要虚构标志、注册表条目、连接器、解决方法或平台保证。
不要将单个产品需求转化为新页面。首先确定该缺口属于文档、产品还是两者共有。
当聚焦的章节或交叉链接可解决问题时，不要重复编写宽泛的指南。
不要仅仅为了符合个人偏好而重写清晰的原文。
不要编造示例、观点、反应或细节来让文本听起来更“人性化”。
不要使用宣传性语言、反问句、填充内容或声称某项任务“简单”“快捷”的表述。
除非描述Vercel或eve团队的刻意行动，否则不要使用“我们”。

Finish the change

完成变更

Re-read every changed page in full.
Verify each new technical claim against its source.
Search for contradictory statements and affected cross-links.
Run the review workflow.
Check changed prose against the prose-quality reference when wording changed materially.
Run
```
pnpm docs:check
```
when preparing to push, unless the user requests earlier validation.

完整重读所有已修改的页面。
对照来源验证每个新的技术声明。
搜索矛盾的表述和受影响的交叉链接。
执行审阅工作流。
当措辞发生重大变化时，对照prose-quality参考文档检查修改后的文本。
准备推送时运行
```
pnpm docs:check
```
，除非用户要求提前验证。