diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index a0b145117a..6031f3f70a 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -1,14 +1,16 @@
 # Terminology
 
+本表约定本仓库的中英术语统一译法。
+
 | English | 中文 | 备注 |
 |---|---|---|
 | ACP | ACP | |
 | AI | AI | 首次出现可写：人工智能（AI） |
 | API | API | |
-| CLI | CLI | |
-| Cordis | Cordis | |
-| Function Calling | Function Calling | |
-| HMR | HMR | |
+| CLI | CLI | 首次出现可写：命令行界面（CLI） |
+| Cordis | Cordis | 保留英文 |
+| Function Calling | Function Calling | 首次出现可写：Function Calling（函数调用） |
+| HMR | HMR | 首次出现可写：热模块替换（HMR） |
 | JSON Schema | JSON Schema | |
 | JSONL | JSONL | |
 | lint | lint | |
@@ -18,24 +20,24 @@
 | RAG | RAG | 首次出现可写：检索增强生成（RAG） |
 | SDK | SDK | |
 | SSE | SSE | |
-| agent | agent | 首次出现可写：agent（智能体）；不要译作：代理 |
+| agent | agent | 首次出现可写：agent（智能体） |
 | agent loop | agent loop | |
-| fiber | fiber | |
-| fixture | fixture | 首次出现可写：fixture（测试样例） |
-| fork | fork | 首次出现可写：fork（派生） |
-| harness | harness | 不要译作：测试框架、脚手架 |
-| manifest | 清单 | 指文件名或字段名时保留 `manifest` |
+| fiber | fiber | 首次出现可写：fiber（插件运行时） |
+| fixture | fixture | 首次出现可写：fixture（测试夹具）；指测试前置数据或环境 |
+| fork | fork | 保留英文 |
+| harness | harness | 保留英文 |
+| manifest | manifest | 首次出现可写：manifest（描述模块或工具元数据的文件） |
 | schema DSL | schema DSL | |
-| schema | schema | API/类型名保留 `schema`；一般 prose 可译为“模式” |
-| seam | seam | 首次出现可写：seam（扩展点）；不要译作：接缝 |
+| schema | schema | 保留英文 |
+| seam | seam | 首次出现可写：seam（扩展点） |
 | skill | skill | 首次出现可写：skill（技能） |
-| spawn | spawn | 首次出现可写：spawn（新建） |
+| spawn | spawn | 保留英文 |
 | steering | steering | 首次出现可写：steering（中途引导） |
-| subagent | subagent | 首次出现可写：subagent（子 agent）；不要译作：子代理 |
-| transcript | 交互记录 | |
-| waterfall | waterfall | 首次出现可写：waterfall（瀑布式事件）；不要译作：瀑布流 |
-| wire format | 协议格式 | |
-| adapter contract | 适配器契约 | |
+| subagent | subagent | 首次出现可写：subagent（子 agent） |
+| transcript | transcript | 首次出现可写：transcript（文本记录）；指会话渲染给用户或编辑器的完整文本，区别于事件日志（event log） |
+| waterfall | waterfall | 首次出现可写：waterfall（瀑布式事件） |
+| wire format | 协议格式 | 首次出现可写：协议格式（wire format） |
+| adapter contract | 适配器契约 | 首次出现可写：适配器契约（adapter contract） |
 | adapter | 适配器 | |
 | append-only | 仅追加 | |
 | artifact | 产物 | |
@@ -46,15 +48,15 @@
 | cancel | 取消 | |
 | checkpoint | 检查点 | |
 | chunk | 分片 | |
-| compaction | 压缩 | |
+| compaction | compaction | 首次出现可写：compaction（上下文压缩）；正文优先保留英文 |
 | consumer | 消费方 | |
 | content block | 内容块 | |
 | config | 配置 | |
 | context | 上下文 | |
-| context compaction | 上下文压缩 | |
+| context compaction | 上下文压缩 | 首次出现可写：上下文压缩（context compaction） |
 | coverage | 覆盖率 | |
 | crash recovery | 崩溃恢复 | |
-| dispose | 释放 | |
+| dispose | dispose | 首次出现可写：dispose（释放资源）；正文优先保留英文 |
 | durability | 持久性 | |
 | event log | 事件日志 | |
 | event | 事件 | |
@@ -65,24 +67,25 @@
 | foreground run | 前台运行 | |
 | hook | 钩子 | |
 | implementation | 实现 | |
-| inference | 推理 | |
+| inference | 推理（inference） | 每次提及时保留英文括注，避免与 reasoning 混淆 |
 | injection | 注入 | |
 | interface | 接口 | |
 | integration | 集成 | |
-| memory | 记忆 | 指 agent memory；不要译作：内存 |
+| memory | memory / 记忆 / 内存 | 按上下文区分：agent memory 译为“记忆”；resource/memory usage 译为“内存” |
 | message | 消息 | |
+| mod | 模组 | 区别于 module（模块）；plugin 译作「插件」 |
 | model provider | 模型提供方 | |
 | module | 模块 | |
 | permission | 权限 | |
 | persistence | 持久化 | |
 | pipeline | 流水线 | |
-| plugin | 模组 | 不要译作：插件 |
+| plugin | 插件 | mod 对应“模组” |
 | prompt | 提示词 | |
 | provider | 提供方 | |
 | provider-neutral | 提供方无关 | |
 | quality gate | 质量门禁 | |
 | registry | 注册表 | |
-| reasoning | 推理 | `reasoning_content` 译为“思考内容” |
+| reasoning | 推理（reasoning） | 需要和 inference 区分时保留英文括注；`reasoning_content` 译为“思考内容” |
 | replay | 回放 | |
 | resume | 恢复 | |
 | runtime | 运行时 | |