eve 中文教程 · 附录 A 术语与速查

A.1 概念对照

A.2 目录速查

agent/
├── agent.ts                    defineAgent：model / reasoning / compaction / limits / build
├── instructions.md             系统提示（或 instructions.ts、instructions/）
├── instrumentation/            遥测 provider，一文件一个
├── channels/                   eve.ts / slack.ts / discord.ts / web.ts / 自定义
├── connections/                MCP / OpenAPI，文件名 = 连接名
├── extensions/                 挂载扩展
├── hooks/                      事件订阅
├── skills/                     *.md 或 <name>/SKILL.md
├── lib/                        辅助代码，不进沙箱
├── memory/                     <slot>.ts，defineMemory
├── sandbox/
│   ├── sandbox.ts              defineSandbox
│   └── workspace/              → /workspace
├── tools/                      文件名 = 工具名
├── schedules/                  cron 任务
└── subagents/<name>/           完整 agent 根目录
evals/
├── evals.config.ts             必需
└── **/*.eval.ts

A.3 import 速查

A.4 常用代码片段

读当前调用者

const user = ctx.session.auth.current;
if (user?.principalType !== "user") throw new Error("需要登录用户");
const tenant = user.attributes.tenantId;

按输入决定审批

approval: ({ toolInput }) =>
  (toolInput?.amount ?? 0) > 1000 ? "user-approval" : "not-applicable",

沙箱跑命令并检查退出码

const r = await (await ctx.getSandbox()).run({ command: "python3 x.py" });
if (r.exitCode !== 0) throw new Error(r.stderr);

幂等键

`${ctx.session.id}:${ctx.callId}`

把大输出收窄给模型

toModelOutput(o) { return { type: "text", value: `共 ${o.total} 条，示例：${o.sample}` }; },

每轮重置状态

export default defineHook({
  events: { async "turn.started"() { state.update(() => initialState()); } },
});

只允许发起人审批

response: ({ request, response }) =>
  request.principal && response.principal.principalId === request.principal.principalId
    ? { status: "allowed" }
    : { status: "rejected" },

A.5 常见错误与含义

A.6 三张对照表

技能 / 工具 / 子代理

state / memory / connection

通道 / 连接

A.7 版本与文档

• 本文档对照 eve@0.81.x。eve 处于 beta，API 会变。
• 升级后先看 node_modules/eve/CHANGELOG.md。
• 本地文档在 node_modules/eve/docs/，与安装版本严格对齐，比 eve.dev 更可信。
• eve.dev 的 /llms.txt 是索引，/llms-full.txt 是全量。

文档与类型不一致时

核对方法：node_modules/eve/dist/src/**/*.d.ts 是最终事实来源。文档与类型冲突时，以类型为准，然后去 CHANGELOG 找是不是版本差异。

返回：教程目录 · 附录 B：事件与 CLI