Add diagnosis playbook skills

2026-07-06 08:35:54 +08:00
parent 88e0a6c944
commit 6ccfd33ec5
23 changed files with 1002 additions and 75 deletions
@@ -0,0 +1,82 @@
+# Design
+
+## Architecture
+
+```text
+src/main/resources/skills/
+  -> SKILL.md files
+  -> ClasspathSkillRegistry bean
+      -> loads classpath skills
+      -> backs official read_skill
+  -> PlannerSkillMetadataHook
+      -> adds planner-only skill metadata messages
+      -> does not expose read_skill
+  -> SkillsAgentHook
+      -> adds official read_skill ToolCallback for Executor / single-agent Chat
+      -> adds SkillsInterceptor prompt augmentation outside Planner
+  -> ChatService / AiOpsService
+      -> Planner receives metadata only
+      -> Executor and single-agent Chat receive official skill hook
+      -> Verifier remains isolated
+```
+
+## Skill Contract
+
+Each skill folder contains a `SKILL.md` with YAML frontmatter:
+
+```yaml
+---
+name: diagnose-mysql-connection-pool
+description: ...
+---
+```
+
+The body contains:
+
+- Trigger conditions.
+- Required evidence.
+- Recommended tool order.
+- Query construction hints.
+- Stop conditions and low-confidence behavior.
+- Report requirements.
+- Eval anchor when one exists.
+
+## Prompt Injection
+
+Planner agents receive a project-local `PlannerSkillMetadataHook` message that contains skill names and descriptions only. The message also requires `selected_skill`, `selection_reason`, and an ordered `plan` in the Planner output.
+
+`SkillsAgentHook` provides `SkillsInterceptor`, which injects the official compact skill section containing skill names, descriptions, and loading instructions into model requests for:
+
+- Chat Executor prompt.
+- AIOps Executor prompt.
+- Single-agent Chat prompt.
+
+Planner prompts are not augmented by `SkillsAgentHook`, so Planner cannot receive the official `read_skill` tool. Verifier prompt is not augmented.
+
+## Tool Exposure
+
+Spring AI Alibaba's official `ReadSkillTool` exposes:
+
+```java
+read_skill(skill_name)
+```
+
+The tool returns the full `SKILL.md` body for a known skill or a structured error for missing skills.
+
+`read_skill` is supplied by `SkillsAgentHook`, not by local `methodTools`. Planner selects a skill from metadata and writes the selection into `planner_plan`; Executor reads the selected skill before executing scenario-specific evidence collection.
+
+## Trace Behavior
+
+`read_skill` is a guidance tool, not an evidence tool. It does not write `tool_invocation` because the existing eval and verifier treat evidence tools as factual data sources. Actual diagnostic evidence must still come from `lookup_knowledge`, `query_logs`, `query_metrics`, and alert tools.
+
+## Fallback
+
+If a skill is not found or cannot be read:
+
+- The tool returns a structured text error.
+- The agent must fall back to generic Executor prompt behavior.
+- It must not invent playbook content.
+
+## Alibaba Skills Integration
+
+The implementation uses `spring-ai-alibaba-agent-framework:1.1.2.0`, where `SkillsAgentHook` lives in `com.alibaba.cloud.ai.graph.agent.hook.skills` and `ClasspathSkillRegistry` lives in `com.alibaba.cloud.ai.graph.skills.registry.classpath`.