Feature/project improvement plan#1
Merged
Merged
Conversation
- Phase 1: Engineering hardening (security, testing, CI, observability) - Phase 2: Feature closure (history comparison, runbook, fix loop, log analysis) - Phase 3: Intelligence upgrade (RCA timeline, Prometheus, compliance, multi-channel notify) - Phase 4: Production-ready (multi-cluster, change management, async, containerization) Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
- Add tools_registry.py: 14 tools registered as LangChain @tool functions - Add loop.py: ReAct Agent Loop with LangGraph + manual fallback - Add hybrid.py: Fast Path + Agent Loop hybrid architecture - Add design doc: docs/agent-loop-design.md Architecture: Fast Path (regex, <1ms) for simple commands, Agent Loop (LLM + multi-step tool use) for complex tasks. Supports automatic degradation when LLM is unavailable.
- Default mode: Agent Loop (LLM auto-selects tools, multi-step execution) - --classic flag: falls back to original router mode - keeper agent command: explicitly start Agent mode - Version bump to v0.5.0-dev - Add langgraph dependency to pyproject.toml - Stream callback support for real-time tool execution display
8-step plan to transform Keeper from router mode to Agent mode: - Step 1: Tool layer completion and testing - Step 2: Agent Loop engine hardening - Step 3: HybridAgent CLI integration - Step 4: System Prompt engineering - Step 5: Planning capability (show plan before execute) - Step 6: Safety control layer - Step 7: Memory and context enhancement - Step 8: E2E testing and documentation Timeline: ~16 days, 6 milestones
Agent Loop Architecture (类 Claude Code): - keeper/agent/tools_registry.py: 18 tools with @tool decorator + fallback - keeper/agent/loop.py: ReAct loop with LangGraph/manual dual mode - keeper/agent/hybrid.py: Fast Path + Agent Loop + graceful degradation - keeper/agent/safety.py: Command safety checker (whitelist/blacklist/confirm) - keeper/agent/planner.py: Execution plan templates + show-before-run - keeper/agent/memory.py: Cross-session persistent memory (JSON) Tests (96 passing): - tests/test_agent_tools.py: 15 tests (registry, safety, execution) - tests/test_agent_safety.py: 26 tests (dangerous/safe/write/destructive) - tests/test_agent_loop.py: 15 tests (init, history, data classes) - tests/test_agent_e2e.py: 25 tests (fast path, slash cmds, degradation, memory, planner) Key design decisions: - No hard dependency on langchain/langgraph (graceful fallback) - 4-level command safety: READ_ONLY → WRITE → DESTRUCTIVE → DANGEROUS - Slash commands: /clear /history /tools /mode - Degradation chain: Agent Loop → Classic Router → Error message
Classic mode improvements: - keeper/exceptions.py: 7 exception classes (KeeperError hierarchy) - keeper/validators.py: IP/hostname/port/command injection/path validation - keeper/utils/retry.py: Exponential backoff decorator with presets - keeper/utils/logger.py: Structured logging (JSON/text, configurable) - keeper/nlu/langchain_engine.py: LLM degradation mode (fallback to regex) - keeper/config.py: Added timeouts config section - .github/workflows/ci.yml: GitHub Actions CI (Python 3.9-3.12 matrix) Tests (190 total, all passing): - tests/test_validators.py: 30 tests - tests/test_nlu_fast_path.py: 44 tests - tests/test_agent_*: 96 tests
New modules: - keeper/storage/history.py: SQLite inspection history (save/query/cleanup) - keeper/tools/comparator.py: Historical diff analysis (MetricDiff, trend) - keeper/tools/capacity.py: Linear regression capacity prediction - keeper/runbook/models.py: Runbook/RunbookStep dataclasses - keeper/runbook/executor.py: YAML loader, variable render, sequential exec, expect check, rollback - keeper/runbook/templates/: disk_cleanup, service_restart, log_rotate - keeper/tools/snapshot.py: Pre-fix state snapshot (iptables, services, configs, network) - keeper/tools/log_analyzer.py: Error pattern aggregation + anomaly detection Tests: 227 total, all passing - tests/test_phase2.py: 37 tests covering all Phase 2 modules
Phase 3 - Intelligence Upgrade: - keeper/tools/timeline.py: Event timeline builder (system events, config changes) - keeper/knowledge/fault_patterns.yaml: 7 fault patterns (memory_leak, cpu_spike, disk_full, crash_loop, network, db_slow, ssl) - keeper/integrations/prometheus.py: Alertmanager client (alerts, silence, storm detection) - keeper/compliance/baseline.py: Config drift detector (3 builtin baselines) - keeper/compliance/cis/linux_basic.py: 15 CIS Benchmark checks (SSH, permissions, firewall, passwords) - keeper/notify/base.py: BaseNotifier abstract interface - keeper/notify/dingtalk.py: DingTalk webhook (HMAC signing + markdown) - keeper/notify/wecom.py: WeCom webhook (markdown) - keeper/notify/router.py: Level-based routing (critical→all, warning→feishu, info→none) Phase 4 - Production Features: - Dockerfile: Multi-stage build, python:3.11-slim, nmap/ssh/kubectl, non-root - docker-compose.yml: keeper CLI + keeper-api + prometheus + alertmanager - keeper/api/server.py: FastAPI REST API (7 endpoints, Bearer auth, CORS) - POST /api/v1/query (agent + classic mode) - GET /api/v1/status, /api/v1/history, /api/v1/tools, /api/v1/runbooks - POST /api/v1/runbook/run - GET /health All 4 phases of TASKS.md now complete.
Bug fixes: - tools_registry: ScannerTools.scan -> scan_ports, CertMonitor.check_domain -> check_domain_cert, LogTools.read_file -> query_file, K8sInspector static call, format_docker_containers add missing stats arg - loop: state_modifier -> prompt for langgraph 1.1.6 compatibility - loop: handle null content in _run_langgraph final message extraction - planner: fix head-10 typo -> head -10 - tests: fix tool invoke() calling convention for StructuredTool Orphaned modules integration: - safety.py: wire is_tool_auto_allowed check into manual ReAct loop - planner.py: inject plan template as LLM guidance in hybrid process - memory.py: integrate AgentMemory with auto-save and /memory command - hybrid.py: add _classify_input for task categorization Docs: - CLAUDE.md: update with Agent Loop architecture - FEATURES.md: complete feature inventory and user test guide (new) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…pectionHistory Also add FEATURES.md (feature inventory + user test guide) and TEST_REPORT.md (E2E test results table — 57 pass, 8 skip, 2 fixed). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
… tests P0 fixes: - loop/hybrid: change default tool_mode from "free" to "all" so LLM uses both structured tools (18) and free tools (5) instead of bare bash only - cli: keeper run now uses HybridAgent by default (--classic keeps old path) - hybrid: fix _classify_input keyword ordering — specific categories (security/fix) now checked before generic "inspect" P1 tests (70 new, all pass): - test_integration.py: 34 tests covering CLI, config load/save/roundtrip, HybridAgent init, Fast Path, degradation, classify, memory, audit, planner - test_tools_extended.py: 36 tests covering Network (ping/port/DNS/format), Scanner (PortInfo/ScanResult/risks/format), Docker (containers/stats/images/ inspect), SSH (config/hosts), RCA (collect/analyze/prompt/compare), Alert (healthy/cpu-triggered/dataclass), Notify (init/sign), Server tools Also fixed in this commit: - format_port_result/dns_format test data corrected to match real API - Scanner format_scan_result risk dict structure corrected - SSH get_hosts_from_file test corrected (filters 127.0.0.1, returns IPs only) - RCA top_cpu_processes field name corrected - Audit host filter test uses direct host param (not entities dict) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Initialize t_duration to 0 before the if/else block instead of using 't_duration' in dir() anti-pattern. This fixes the case where consecutive_same_tool >= 3 would leave t_duration undefined when constructing the ToolCall record. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…dit host - Runbook: register 3 independent @tool functions (runbook_disk_cleanup, runbook_service_restart, runbook_log_rotate). LLM now autonomously uses standardized runbooks instead of raw bash for disk cleanup, service restart, and log rotation. Tools in ALL_TOOLS: 18 → 21. - K8s: replace direct imports in all 6 k8s CLI commands with safe _get_k8s_modules() helper that shows friendly install prompt instead of Python traceback when kubernetes SDK is missing. - AlertEngine: auto-triggered inside inspect_server tool. After inspection, checks thresholds and appends alerts to report. (On healthy systems, no alerts shown — verified code injection.) - Audit: _log_audit now accepts host parameter. Host is auto-extracted from tool calls (inspect_server/ping_host/check_port/scan_ports) for correct per-host audit filtering. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
New streaming behavior: - LangGraph mode now uses agent.stream(stream_mode="updates") instead of blocking agent.invoke() — users see tool calls and results in real-time as the agent works - Structured event types: thinking → tool_call → tool_result → done - Tool results show success/failure status with colored output Error recovery: - Consecutive same-tool detection: warns after 3 identical calls, tells LLM to try different approach - LangGraph recursion_limit=50 prevents infinite loops - Stream exception → auto-fallback to blocking invoke() - Manual ReAct loop retains MAX_LOOPS=10 limit CLI changes: - stream_callback upgraded to handle dict events with typed rendering (tool_call=cyan, tool_result=green/red, warning=yellow, thinking=dim) - keeper run also gets streaming in Agent Loop mode - Backward compatible: old str callbacks still work via _emit() helper Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
CLI: No longer hard-exits on missing API key. Instead shows interactive setup wizard (_interactive_api_setup) where user can paste API key, base URL, and model directly. Falls through to degraded mode if skipped. Tools: Upgraded all error messages from bare errors to actionable guidance: - SSH: "Please ask user for credentials (key path, username, port, password)" - K8s: "Guide user to locate kubeconfig or install kubectl as fallback" - nmap: "Offer to run sudo apt/npm install nmap for user" - kubernetes SDK: "Suggest pip install kubernetes or use kubectl CLI" System Prompt: Added "自主服务原则" section teaching the LLM to: - Detect guidance responses vs errors - Ask users for missing config before giving up - Offer to install missing dependencies - Guide users step by step through setup Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…rvice flow - Add Agent mode architecture overview with streaming execution - Document 21 tools and Runbook standardized operations - Add self-service onboarding flow (interactive API key setup) - Add 4 deployment modes: CLI, Docker, K8s, Dev - Update command reference with all subcommands - Update tech stack and architecture diagram Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…docs - Remove AGENT_TASKS.md and TASKS.md (all tasks completed) - Update FEATURES.md with all 21 tools, streaming, error recovery, self-service guidance, Runbook, deployment modes - Update TEST_REPORT.md with latest results: 374 passed, 14 bugs fixed, new features added Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Bump version 0.5.0-dev → 1.0.0 across all files (pyproject.toml, CLI, API server, CLAUDE.md, README, FEATURES.md, TEST_REPORT.md) - install.sh: fix REPO_URL to use HTTPS (no SSH key required for public install) - pyproject.toml: add missing schedule>=1.2 dependency, add [api] optional deps (fastapi, uvicorn), update description - requirements.txt: sync with pyproject.toml, add all optional deps User install flow: curl -sSL https://.../install.sh | bash keeper # interactive API key setup keeper run 检查本机 # start using immediately Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1