diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..3e98cd1
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,67 @@
+# AgentEvalTool
+
+智能体质量评估平台的领域词汇表。评估 AI 数字员工 / AI 助手的服务质量：向被评智能体发送消息、收集回复、按规则打分并生成报告。
+
+## Language
+
+**评测对象（Target / EvalTarget）**:
+被评估的智能体本身。每个被评智能体只有一个可访问地址，评测对象与其通道连接信息一一对应（不区分测试/生产等多环境部署）。
+_Avoid_: 被测系统、机器人、环境
+
+**平台类型（Platform）**:
+被评智能体的产品形态分类（AI 数字员工 / AI 助手），意图是未来据此选择评测策略；目前仅作分类标签，不参与任何评测逻辑。
+_Avoid_: 产品线、渠道
+
+**通道（Channel）**:
+向评测对象收发消息的技术接入协议（tutu-api / openclaw / http）。通道决定"怎么连"，与平台类型（"是什么形态"）相互独立。
+_Avoid_: 接口、连接器
+
+**期望（Expectation）**:
+用例层面的业务意图描述：智能体应当如何回应（意图、必含/禁含关键词、时延上限）。表达"想要什么"，与评估规则（"怎么判定"）叠加生效，不是规则的替代品。
+_Avoid_: 断言、预期结果
+
+**评估规则（EvalRule）**:
+对单轮回复的可执行判定标准（keyword_match / response_time / llm_score），产出通过与否和得分。用例的唯一正式判定机制。
+_Avoid_: 校验器、断言
+
+**连通用例（Connectivity Case）**:
+不配置任何规则与期望的用例，仅验证消息能发出且收到回复，收到即通过。合法用法，但报告中应与判定型用例区分标注，避免稀释通过率。
+_Avoid_: 空用例、无效用例
+
+**场景（Scenario）**:
+一组评测用例的集合，定义一次评测的"考纲"——考察哪些能力维度。场景是对比报告的可比性单位：同场景的两次运行即可比，无论具体对话内容是否相同。
+_Avoid_: 测试集、题库
+
+**用例（Case）**:
+场景内的单个考察项，分单轮（single）、多轮（multi_turn）、动态（dynamic）三类。静态用例题目固定；动态用例只固定考察意图（prompt），每次运行由 AI 现场生成对话消息。
+_Avoid_: 测试点、题目
+
+**对比报告（Compare Report）**:
+同一场景（同版本考纲）下两次运行的逐项对照。可比性来自"同考纲"而非"同考卷"——动态用例题目不同不影响可比。跨场景对比无意义，系统拒绝。
+_Avoid_: 差异报告
+
+**场景版本（Scenario Version）**:
+场景考纲的版本标识。仅考纲字段（用例集、模型绑定、LLM 配置）变更时递增；名称、描述、标签等元数据编辑不升版。（决策见 ADR-0001，尚未实现）
+_Avoid_: 修订号
+
+**评测运行（Run / EvalRun）**:
+一次"评测对象 × 场景"的完整执行记录，含触发来源（手动 / AI 助手 / CLI）、逐轮对话与全部判定结果。
+_Avoid_: 任务、作业、测试
+
+**轮次（Turn）**:
+一次完整的问答往返：向评测对象发出一条消息并收到其回复。不是单方向的一条消息——`turns: 3` 表示 3 个问答对。
+_Avoid_: 消息、回合（round 仅作代码内索引名）
+
+**通过率（Pass Rate）**:
+通过用例数 ÷ 全部用例数。刻意采用服务视角：通道故障、超时等执行失败同样计为不通过——用户视角里"没回复"就是质量问题，不从分母中剔除。（决策见 ADR-0002）
+_Avoid_: 成功率、达标率
+
+## 模型配置
+
+**模型能力（Capability）**:
+供给侧属性：一个已接入模型本身能干什么（对话 / 向量 / 审核）。描述模型，不描述评测流程。
+_Avoid_: 功能、类型
+
+**模型用途（Purpose）**:
+需求侧属性：评测流程中的角色岗位（出题 generator / 判卷 judge / 向量 embedding / 审核 moderation）。场景通过模型绑定为每个岗位指派一个具备相应能力的模型；一个对话能力模型可同时胜任出题与判卷两个岗位。
+_Avoid_: 能力、角色（role 留给对话消息的 role 字段）
diff --git a/docs/adr/0001-scenario-versioning-for-comparability.md b/docs/adr/0001-scenario-versioning-for-comparability.md
new file mode 100644
index 0000000..0a528c6
--- /dev/null
+++ b/docs/adr/0001-scenario-versioning-for-comparability.md
@@ -0,0 +1,14 @@
+# 场景版本化：对比报告的可比性以场景版本为准
+
+场景可编辑，导致同一 scenario_id 的两次运行可能基于不同"考纲"（用例集、规则、模型绑定），v0.4 的"同场景即可对比"约束不够严格。决定引入场景版本：仅考纲字段（cases / model_bindings / llm_config）变更时递增版本号，名称、描述、标签等元数据编辑不升版；对比报告要求同场景且同版本才严格可比。
+
+## Considered Options
+
+- 任何编辑都升版 — 被否：改描述错字也会断开可比性，过于粗暴
+- Run 快照考纲指纹比对（无版本号字段）— 被否：无显式版本号，用户无法在 UI 上直观选择"同一版"的运行
+- 交集对齐 + 单边标注 — 被否：掩盖考纲漂移，对比结论可信度存疑
+
+## Consequences
+
+- 数据模型需加 scenario version 字段，Run 需记录所用版本（v0.5 实施项，尚未实现）
+- 动态用例每次运行题目不同不影响可比性——可比性单位是"同考纲"（同场景同版本），不是"同考卷"
diff --git a/docs/adr/0002-pass-rate-includes-execution-failures.md b/docs/adr/0002-pass-rate-includes-execution-failures.md
new file mode 100644
index 0000000..a07818f
--- /dev/null
+++ b/docs/adr/0002-pass-rate-includes-execution-failures.md
@@ -0,0 +1,12 @@
+# 通过率含执行失败：故障也是质量问题
+
+用例失败有两类原因：智能体回答不达标（规则判负）和通道故障/超时（执行失败）。决定通过率分母不剔除执行失败——评测采用最终用户视角，"没收到回复"与"回复不合格"同样是服务质量不达标。
+
+## Considered Options
+
+- 分母排除执行失败、单独计执行失败率 — 被否：会让基础设施故障期间的报告显得"质量正常"，掩盖用户实际感受到的不可用
+- 报告仅做拆分提示、分母不变 — 部分吸收：报告可以展示失败原因拆分，但通过率口径不变
+
+## Consequences
+
+- 网络抖动会拉低通过率——这是刻意的，不要"修复"；排查时看报告中的错误明细区分原因