diff --git a/docs/design/19-toolchain-context-layers.md b/docs/design/19-toolchain-context-layers.md
index 949a81d..fec21e7 100644
--- a/docs/design/19-toolchain-context-layers.md
+++ b/docs/design/19-toolchain-context-layers.md
@@ -69,6 +69,7 @@
 - **获取完整上下文** → 用 Gitea API 拉取 Issue 详情和评论，不要只看 Mail 里的快照
 
 ### Gitea API 速查
+> 其中 `{owner}/{repo}` 替换为实际仓库，如 `sanguo/sanguo_moziplus_v2`
 - Issue 详情: GET /api/v1/repos/{owner}/{repo}/issues/{number}
 - Issue 评论: GET /api/v1/repos/{owner}/{repo}/issues/{number}/comments
 - PR diff: GET /api/v1/repos/{owner}/{repo}/pulls/{number}.diff
@@ -193,6 +194,8 @@ AGENT_IDS = {
 }
 
 # 前缀映射：@张飞 → zhangfei-dev
+# 中文名映射：Agent 在 Gitea Issue 评论中可能用中文名 @mention
+# 英文短名映射：Agent 可能用不带 -dev/-infra 后缀的短名
 AGENT_ALIAS = {
     "张飞": "zhangfei-dev",
     "关羽": "guanyu-dev",
@@ -311,6 +314,13 @@ async def _handle_issue_comment(payload):
 
 具体改动在 `_send_mail()` 函数或其调用处：工具链路由调用 `_send_mail` 时传入 `performative="request"`。
 
+**⚠️ 验证要点**：改为 request 后，Agent spawn prompt 变为 "请处理以下请求"，需确认：
+1. Agent 不再把工具链 Mail 当纯通知忽略
+2. Agent 能正确处理「已阅型」工具链事件（如 CI 失败通知——不需要回复，但需要知道）
+3. 对已关闭 PR/Issue 的延迟通知，Agent 不会尝试去处理
+
+验证方法：部署后发一条 Issue 指派 Mail，观察 Agent 行为是否符合预期。
+
 ---
 
 ## 五、完整改动清单