diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
new file mode 100644
index 0000000000..a0b145117a
--- /dev/null
+++ b/docs/i18n/terminology.md
@@ -0,0 +1,110 @@
+# Terminology
+
+| English | 中文 | 备注 |
+|---|---|---|
+| ACP | ACP | |
+| AI | AI | 首次出现可写：人工智能（AI） |
+| API | API | |
+| CLI | CLI | |
+| Cordis | Cordis | |
+| Function Calling | Function Calling | |
+| HMR | HMR | |
+| JSON Schema | JSON Schema | |
+| JSONL | JSONL | |
+| lint | lint | |
+| loader | loader | |
+| LLM | LLM | 首次出现可写：大语言模型（LLM） |
+| MCP | MCP | |
+| RAG | RAG | 首次出现可写：检索增强生成（RAG） |
+| SDK | SDK | |
+| SSE | SSE | |
+| agent | agent | 首次出现可写：agent（智能体）；不要译作：代理 |
+| agent loop | agent loop | |
+| fiber | fiber | |
+| fixture | fixture | 首次出现可写：fixture（测试样例） |
+| fork | fork | 首次出现可写：fork（派生） |
+| harness | harness | 不要译作：测试框架、脚手架 |
+| manifest | 清单 | 指文件名或字段名时保留 `manifest` |
+| schema DSL | schema DSL | |
+| schema | schema | API/类型名保留 `schema`；一般 prose 可译为“模式” |
+| seam | seam | 首次出现可写：seam（扩展点）；不要译作：接缝 |
+| skill | skill | 首次出现可写：skill（技能） |
+| spawn | spawn | 首次出现可写：spawn（新建） |
+| steering | steering | 首次出现可写：steering（中途引导） |
+| subagent | subagent | 首次出现可写：subagent（子 agent）；不要译作：子代理 |
+| transcript | 交互记录 | |
+| waterfall | waterfall | 首次出现可写：waterfall（瀑布式事件）；不要译作：瀑布流 |
+| wire format | 协议格式 | |
+| adapter contract | 适配器契约 | |
+| adapter | 适配器 | |
+| append-only | 仅追加 | |
+| artifact | 产物 | |
+| block | 块 | |
+| background task | 后台任务 | |
+| backend | 后端 | |
+| capability | 能力 | |
+| cancel | 取消 | |
+| checkpoint | 检查点 | |
+| chunk | 分片 | |
+| compaction | 压缩 | |
+| consumer | 消费方 | |
+| content block | 内容块 | |
+| config | 配置 | |
+| context | 上下文 | |
+| context compaction | 上下文压缩 | |
+| coverage | 覆盖率 | |
+| crash recovery | 崩溃恢复 | |
+| dispose | 释放 | |
+| durability | 持久性 | |
+| event log | 事件日志 | |
+| event | 事件 | |
+| event stream | 事件流 | |
+| executor | 执行器 | |
+| extension | 扩展 | |
+| finish reason | 结束原因 | |
+| foreground run | 前台运行 | |
+| hook | 钩子 | |
+| implementation | 实现 | |
+| inference | 推理 | |
+| injection | 注入 | |
+| interface | 接口 | |
+| integration | 集成 | |
+| memory | 记忆 | 指 agent memory；不要译作：内存 |
+| message | 消息 | |
+| model provider | 模型提供方 | |
+| module | 模块 | |
+| permission | 权限 | |
+| persistence | 持久化 | |
+| pipeline | 流水线 | |
+| plugin | 模组 | 不要译作：插件 |
+| prompt | 提示词 | |
+| provider | 提供方 | |
+| provider-neutral | 提供方无关 | |
+| quality gate | 质量门禁 | |
+| registry | 注册表 | |
+| reasoning | 推理 | `reasoning_content` 译为“思考内容” |
+| replay | 回放 | |
+| resume | 恢复 | |
+| runtime | 运行时 | |
+| sandbox | 沙箱 | |
+| service | 服务 | |
+| session | 会话 | |
+| session event | 会话事件 | |
+| snapshot | 快照 | |
+| spine | 主干 | |
+| step | 步骤 | |
+| stream | 流 | |
+| streaming | 流式输出 | |
+| system prompt | 系统提示词 | |
+| taxonomy | 分类体系 | |
+| token usage | token 用量 | |
+| thinking | thinking | API 字段保留；模型模式译为“思考” |
+| tool | 工具 | |
+| tool call | 工具调用 | |
+| tool result | 工具结果 | |
+| tool schema | 工具 schema | |
+| toolkit | 工具包 | |
+| turn | 轮次 | |
+| typecheck | 类型检查 | |
+| vocabulary | 词汇 | |
+| workflow | 工作流 | |