From 3dfe3dbe536d0f1bb4693d77749308a130fdef0c Mon Sep 17 00:00:00 2001
From: aruo <40362743+zyongxin@users.noreply.github.com>
Date: Mon, 6 Jul 2026 10:43:21 +0800
Subject: [PATCH] Update devflow glossary for skills

---
 .gitignore                  |  1 -
 devflow/glossary/CONTEXT.md | 47 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 5423a75..dcb8b93 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,7 +49,6 @@ uploads/
 
 ### Temp Scripts ###
 *.sh
-*.py
 
 ### docker
 /volumes
diff --git a/devflow/glossary/CONTEXT.md b/devflow/glossary/CONTEXT.md
index e1307c9..b5cd1fb 100644
--- a/devflow/glossary/CONTEXT.md
+++ b/devflow/glossary/CONTEXT.md
@@ -105,4 +105,49 @@
 - 枚举类型在数据库中存储为 VARCHAR，JPA 使用 `@Enumerated(EnumType.STRING)` + `columnDefinition = "VARCHAR"`
 - JPA ddl-auto 使用 `validate` 模式，表结构修改必须通过 Flyway 迁移脚本
 - Redis 会话 TTL 由调用方指定，不同场景使用不同过期时间（短诊断 5 分钟，长会话 1 小时）
-- Repository 查询方法遵循 Spring Data JPA 命名约定，复杂查询使用 `@Query`
\ No newline at end of file
+- Repository 查询方法遵循 Spring Data JPA 命名约定，复杂查询使用 `@Query`
+
+## Diagnosis Playbook Skills
+
+### Diagnosis Playbook Skill
+- 定义：项目内可版本化的诊断流程包，存放在 `src/main/resources/skills/{skill-name}/SKILL.md`。
+- 使用场景：把高频故障诊断流程从大 prompt / 知识库文档中抽出，形成可审查、可复用、可按需加载的 playbook。
+- 边界：skill 只定义排查 workflow、证据顺序、停止条件、低置信度行为和报告规则；事实性知识仍放在 `knowledge_base/`，事实证据仍来自 evidence tools。
+
+### SkillRegistry
+- 定义：Spring AI Alibaba Agent Framework 的 skill 元数据和正文读取入口。本项目使用 `ClasspathSkillRegistry` 从 classpath `skills/` 加载 skill。
+- 使用场景：统一提供 skill `name` / `description` 元数据，并支撑 Executor 通过官方 `read_skill` 读取完整 `SKILL.md`。
+- 当前约束：`SkillConfig.SingleSkillRegistry` 临时只暴露 active skill `diagnose-mysql-connection-pool`，用于验证单 skill 流程和避免一次性注入全部 skill。
+
+### PlannerSkillMetadataHook
+- 定义：项目本地 hook，只向 Planner 注入结构化 `skill_catalog` 元数据。
+- 使用场景：Planner 根据 skill `name` / `description` 选择 `selected_skill`，输出 `selection_reason` 和执行计划。
+- 边界：Planner 不暴露官方 `read_skill` 工具，不读取完整 `SKILL.md`；Planner 只能选择 skill，不能执行 skill。
+
+### SkillsAgentHook
+- 定义：Spring AI Alibaba 官方 skill hook，会同时注入官方 Skills System prompt，并暴露 `read_skill` 工具。
+- 使用场景：只挂到 Executor 和 single-agent Chat；Executor 根据 `planner_plan.selected_skill` 读取完整 playbook 后再调用证据工具。
+- 边界：不要挂到 Planner，否则 Planner 会获得 `read_skill` 工具并可能读取完整 skill；Verifier 也不能挂该 hook。
+
+### read_skill
+- 定义：官方 skill 读取工具，参数为 `skill_name`，返回对应 `SKILL.md` 正文。
+- 使用场景：Executor 在执行场景化诊断前读取 Planner 选中的 playbook。
+- 边界：`read_skill` 是流程指导工具，不是事实证据工具；不应作为诊断事实写入 `tool_invocation` 证据链。
+
+### Evidence Tools
+- 定义：产生可验证诊断事实的工具集合，包括 `lookup_knowledge`、`query_logs`、`query_metrics`、告警/Prometheus 工具等。
+- 使用场景：Executor 按 skill workflow 调用 evidence tools 收集事实，`tool_invocation` 记录这些事实证据。
+- 边界：最终诊断结论必须被 evidence tools 支撑，不能仅由 skill 正文支撑。
+
+### Verifier Skill Isolation
+- 定义：Chat Verifier 与 skill 系统隔离，只校验 Executor 答案和 `tool_trace_summary`。
+- 使用场景：防止 Verifier 把 playbook 指令当作事实证据；Verifier 只判断已有证据是否支持结论。
+- 边界：Verifier 不接收 `skill_catalog`，不暴露 `read_skill`，不读取 `SKILL.md`。
+
+## Diagnosis Playbook Business Rules
+
+- Planner 只看 skill metadata，输出 `selected_skill`、`selection_reason` 和 plan。
+- Executor 才能调用 `read_skill(selected_skill)`，并且读取 skill 后仍必须调用 evidence tools。
+- Skill 正文不得替代 `lookup_knowledge`、日志、指标或告警数据。
+- Verifier 只基于 `tool_trace_summary` 校验事实，不基于 skill 正文校验事实。
+- 当前阶段保留单 active skill 白名单：`diagnose-mysql-connection-pool`。