Merge pull request #1 from Tweakzx/feature/agent-extensibility

Feature/agent extensibility

Author: Tweakzx

cpu.prof

@@ -374,6 +374,54 @@ func generateActionPreview(action *K8sAction) *models.ActionPreview {
 
 ---
 
+## 工具系统架构
+
+工具系统为 K8s 操作提供统一的抽象层：
+
+### 工具接口
+```go
+type Tool interface {
+    Name() string
+    Description() string
+    Category() string
+    Parameters() []Parameter
+    DangerLevel() DangerLevel
+    Execute(ctx context.Context, args map[string]interface{}) (Result, error)
+}
+```
+
+### 注册表模式
+工具注册表支持动态发现和路由：
+- 工具通过 `registry.Register(tool)` 自注册
+- LLM 可通过 `registry.GetLLMDescriptions()` 查询可用工具
+- 工具通过 `registry.Execute(ctx, name, args)` 执行
+
+### 处理器模式
+资源处理器连接 K8s API 和工具：
+- 每种资源类型一个处理器（deployment、pod、service 等）
+- 每个处理器定义操作（create、get、scale、delete）
+- 处理器自动将其操作注册为工具
+
+### 子图
+可复用的工作流片段，用于复杂操作（计划中的实现）：
+- 子图将封装多步骤工作流，如日志获取、Pod 执行和诊断
+- 接口定义在 `pkg/workflow/subgraph.go`
+- 具体实现将在后续阶段开发
+
+### 上下文管理
+ContextManager 维护对话历史：
+- 跟踪上次操作、资源、命名空间
+- 通过 CheckpointerManager 持久化到 SQLite
+- 为 LLM 提供格式化的上下文
+
+### 迁移策略
+新工具系统设计用于渐进式采用：
+- 工具注册表和处理器与现有代码路径共存
+- 按资源类型逐步迁移
+- 无需功能标志 - 根据操作/资源类型自动路由
+
+---
+
 ## 扩展性设计
 
 ### 1. 插件化节点

docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# Migration Guide: Agent Extensibility
+
+## Overview
+
+This guide explains how to migrate existing K8s operations to the new tool system.
+
+## Architecture Changes
+
+### Before (Direct Code Paths)
+```go
+// Intent parser directly calls K8s client
+if intent.Action == "create" && intent.Resource == "deployment" {
+    // Direct K8s client call
+    deployment := &appsv1.Deployment{...}
+    client.Create(deployment)
+}
+```
+
+### After (Tool System)
+```go
+// Intent parser routes through tool registry
+toolName := fmt.Sprintf("%s_%s", intent.Action, intent.Resource)
+result, err := registry.Execute(ctx, toolName, args)
+```
+
+## Migration Steps
+
+### Step 1: Create Handler
+```go
+// pkg/k8s/handlers/myresource.go
+type MyResourceHandler struct {
+    *BaseHandler
+}
+
+func NewMyResourceHandler(clientset kubernetes.Interface) *MyResourceHandler {
+    base := NewBaseHandler(clientset, "myresource")
+    base.ops = []Operation{...}
+    return &MyResourceHandler{BaseHandler: base}
+}
+```
+
+### Step 2: Register Handler
+```go
+// In agent initialization
+handler := NewMyResourceHandler(clientset)
+err := handler.RegisterTools(deps.ToolRegistry)
+```
+
+### Step 3: Enable Routing
+Note: The tool system is designed to coexist with existing code paths. Once handlers are registered, operations will automatically route through the tool registry based on the action and resource type.
+
+## Architecture Evolution
+
+The new tool system is being incrementally adopted:
+- Phase 1: Tool registry and handler abstraction (completed)
+- Phase 2: Sub-graph integration (in progress)
+- Phase 3: Context-aware routing (planned)
+
+During migration, both old and new code paths remain available, allowing for gradual adoption per resource type.
+
+## Testing
+
+Verify migration:
+1. Run unit tests: `go test ./pkg/k8s/handlers/...`
+2. Run integration tests: `go test ./test/integration/...`
+3. Test in development environment

docs/MIGRATION.md

@@ -1,5 +1,26 @@
 # K8s Wizard Development Roadmap
 
+## Completed
+
+- [x] Tool system with Registry pattern
+- [x] Resource handler abstraction
+- [x] Prompt loader with YAML templates
+- [x] Sub-graph interface for reusable workflows
+- [x] ContextManager for conversation tracking
+
+## In Progress
+
+- [ ] Migration of all existing resources to handlers
+- [ ] Sub-graph implementation (logs, exec, diagnostics)
+
+## Future
+
+- [ ] Additional resource handlers (StatefulSet, DaemonSet, ConfigMap, Secret)
+- [ ] Advanced sub-graphs (multi-pod workflows, deployment strategies)
+- [ ] Enhanced context awareness (cross-session context, semantic search)
+
+---
+
 ## 📊 Current Status (v0.1.0)
 
 ### ✅ Implemented Features
@@ -219,25 +240,25 @@ AI monitors cluster and suggests:
 ## 📅 Timeline
 
 ```
-2025 Q1 (v0.2.0)
+2026 Q1 (v0.2.0)
 ├── Session Management
 ├── Streaming Response
 ├── Markdown Rendering
 └── Safety Confirmation
 
-2025 Q2 (v0.3.0)
+2026 Q2 (v0.3.0)
 ├── Logs Support
 ├── Exec Support
 ├── Describe Support
 └── Extended Resources
 
-2025 Q3 (v0.4.0)
+2026 Q3 (v0.4.0)
 ├── YAML Editor
 ├── Templates
 ├── History
 └── Multi-cluster
 
-2025 Q4 (v0.5.0)
+2026 Q4 (v0.5.0)
 ├── Authentication
 ├── Audit Logging
 ├── Metrics
@@ -301,5 +322,5 @@ AI monitors cluster and suggests:
 
 ---
 
-*Last Updated: 2025-03-01*
+*Last Updated: 2026-03-15*
 *Version: 0.1.1*