kaiwu

# Tool List ## cl-kaiwu v0.2 - Super Smart Plugin for Claude Code/Codex/Cursor with Embedded DeepSeek ## Efficacy Demonstration <img width="1376" height="388" alt="image" src="https://github.com/user-attachments/assets/6a340d12-0b81-45c4-8a60-90166e5fa68c" /> <img width="1272" height="1396" alt="image" src="https://github.com/user-attachments/assets/85174b8a-9f17-47e8-8199-638e0d31ebd3" /> ------------------------------ ## Core Advantages: 1. Model Equality --- Regardless of the model's cost, all models can achieve the same quality and efficiency. 2. Token Savings --- Comprehensive testing shows a 20%-60% reduction in token usage depending on the task and relevance to China. 3. Cross-Session Understanding --- AI can understand you, predict your next question, and maintain session continuity. 4. Enhanced Performance Over Time --- The more you use it, the more intelligent and error-free it becomes. ----------------------------- ## Contact Information For any issues, please contact me via QQ: 154882199 or email: valhuang@kaiwucl.com ## Development Background **Initial Thoughts on Developing a Plugin:** - Claude Code's Opus is too expensive. - Ordinary models often encounter errors and repeat mistakes. - I aimed to create a DeepSeek-based solution for Chinese users. Despite significant investment, the initial attempt failed. I then focused on creating a plugin for coding software that integrates DeepSeek. ## Key Features ### 7 MCP Tools | Tool | Function | DeepSeek Invocation | |------|------|:---:| | `kaiwu_context` | Handles project context, creates/updates sessions | ✗ | | `kaiwu_plan` | Generates structured planning for coding tasks (steps + trap warnings) | ✓ | | `kaiwu_lessons` | Three-layer error diagnosis (local precise → local fuzzy → DeepSeek) | Only third layer | | `kaiwu_record` | Records successful experiences and lessons learned, automatically extracts | ✓ | | `kaiwu_condense` | Session management + context compression (init/compress/inject/anchor) | ✓ (during compression) | | `kaiwu_scene` | Detects task scenes, returns coding specifications | Only LLM fallback | | `kaiwu_profile` | Returns user programming habit portrait | ✗ | ### Three-Layer Error Diagnosis ``` Error Input ├─ Layer 1: ErrorKB Precise Match (fingerprint, millisecond-level, 0 token) ├─ Layer 2: ErrorKB Fuzzy Match (keyword, millisecond-level, 0 token) └─ Layer 3: DeepSeek Analysis (consumes tokens, solution automatically written) → Next identical error directly hits Layer 1, no API call ``` ### 19 Coding Scenes web · react · dataviz · python_script · backend_api · data_analysis · web_scraping · shell_script · copywriting · game_dev · test_case · database · code_review · docx · pdf · pptx · xlsx · china_deploy · wechat_pay ### Enhanced Over Time - DeepSeek automatically refines experiences and stores them in the database after each successful task. - Solutions to new errors are automatically stored in the error database. - Similar tasks leverage historical experiences, injecting few-shot examples to improve success rates. ## Installation ### 1. Install Package ```bash pip install git+https://github.com/v289986095-sketch/kaiwu.git ``` Or clone locally and install: ```bash git clone https://github.com/v289986095-sketch/kaiwu.git cd kaiwu pip install . ``` ### 2. Configure DeepSeek API Key ```bash # Interactive configuration (recommended, automatically detects API format) kaiwu config # Or set directly via command line kaiwu config set providers.deepseek.api_key sk-your-api-key ``` Free registration: [platform.deepseek.com](https://platform.deepseek.com) (new users receive 5 million tokens) ### 3. Install to Coding Tools ```bash # Install to all detected platforms kaiwu install # Or specify a platform kaiwu install --platform claude-code kaiwu install --platform cursor kaiwu install --platform vscode kaiwu install --platform codex ``` This step will: - Generate platform-specific configuration files (CLAUDE.md / .cursor/rules/ / copilot-instructions.md / AGENTS.md) - Register MCP Server to platform configuration ### 4. Start MCP Server ```bash kaiwu serve # Or python -m kaiwu ``` ## Supported Platforms | Platform | Configuration File Fallback | MCP Server Enhancement | |------|:-----------:|:--------------:| | **Claude Code** | CLAUDE.md | ✓ Native Support | | **Cursor** | .cursor/rules/ | ✓ Supports MCP | | **VS Code Copilot** | copilot-instructions.md | ✓ Through Extension | | **OpenAI Codex** | AGENTS.md | Planned | ## Two-Tier Architecture: 1. **Configuration File Fallback** (Zero Threshold) — Even without starting MCP Server, rules are injected into AI context. 2. **MCP Server Enhancement** (Complete Capability) — DeepSeek real-time planning, experience retrieval, error diagnosis. ## Usage After installation, AI coding tools automatically discover and use kaiwu's 7 tools: ### Scenario 1: New Task AI tool automatically calls `kaiwu_plan` for planning suggestions: ```json { "steps": [ {"seq": 1, "action": "Read existing routing file", "reason": "Understand existing API structure"}, {"seq": 2, "action": "Define Pydantic request model", "reason": "Type safety"} ], "trap_warnings": [ "CORS configuration is placed in app-level middleware, not in individual routing", "Chinese Windows note encoding='utf-8'" ], "confidence": 0.85 } ``` ### Scenario 2: Encountering an Error AI tool calls `kaiwu_lessons` for diagnosis: ```json { "root_cause": "UnicodeEncodeError: Chinese Windows default GBK encoding", "fix_suggestion": "Add sys.stdout.reconfigure(encoding='utf-8', errors='replace')", "confidence": 0.95, "source": "local_exact" } ``` ### Scenario 3: Task Completion AI tool calls `kaiwu_record` to record experiences for future similar tasks. ## Configuration Configuration file located at `~/.kaiwu/config.toml`: ```toml [providers.deepseek] api_key = "sk-your-api-key" base_url = "https://api.deepseek.com/v1" # Can be changed to relay address model = "deepseek-chat" api_format = "openai" ``` ### Environment Variables ```bash DEEPSEEK_API_KEY=sk-xxx # Prioritizes config.toml DEEPSEEK_BASE_URL=https://... # Prioritizes config.toml KAIWU_HOME=~/.kaiwu # Data directory ``` ### CLI Commands ```bash kaiwu serve # Start MCP Server kaiwu config # Interactive configuration wizard kaiwu install # Install to coding tools kaiwu toggle # One-click switch (compare on/off effects) kaiwu stats # View experience/error database statistics kaiwu data show # View local data overview kaiwu data delete # Delete all local data kaiwu data export # Export data as JSON ``` ## Data Storage All data stored in `~/.kaiwu/` directory: ``` ~/.kaiwu/ ├── config.toml # Configuration file ├── error_kb.json # Error knowledge base ├── experiences.json # Experience database ├── scene_enrichments.json # Scene enhancement content ├── profile.json # User portrait ├── usage.json # Usage statistics ├── sessions/ # Session records └── kaiwu.log # Running log ``` ## DeepSeek API Key AI enhancement features (intelligent planning, error analysis, experience refinement) require DeepSeek API Key: 1. Visit [platform.deepseek.com](https://platform.deepseek.com) to register an account 2. Go to 'API Keys' page, click 'Create API Key' 3. New users receive 5 million tokens free 4. Recharge starts at ¥2, daily usage about ¥0.1/day ## Project Structure ``` cl-kaiwu/ ├── pyproject.toml # Project configuration ├── README.md ├── kaiwu/ # Core package │ ├── __init__.py │ ├── __main__.py # python -m kaiwu entry │ ├── cli.py # Command-line tool │ ├── server.py # MCP Server (7 tools) │ ├── config.py # Configuration management │ ├── planner.py # kaiwu_plan implementation │ ├── lessons.py # kaiwu_lessons implementation │ ├── recorder.py # kaiwu_record implementation │ ├── condenser.py # kaiwu_condense implementation │ ├── context.py # kaiwu_context implementation │ ├── scene.py # Scene detection │ ├── profile.py # User portrait │ ├── session.py # Session management │ ├── task_classifier.py # Task classifier │ ├── llm_client.py # LLM client │ ├── privacy.py # Privacy desensitization │ ├── hooks.py # Rule engine │ ├── quota.py # Usage statistics │ ├── wizard.py # Configuration wizard │ ├── storage/ │ │ ├── error_kb.py # Error knowledge base │ │ └── experience.py # Experience database │ ├── knowledge/ │ │ ├── loader.py # Knowledge base loader │ │ ├── china_kb.md # Chinese developer knowledge base │ │ ├── python_compat.md # Python compatibility │ │ ├── deps_pitfalls.md # Dependency pitfalls │ │ └── tool_priming.md # MCP tool invocation guidance │ └── scenes/ # 19 scene specifications │ ├── web.md │ ├── react.md │ ├── ... │ └── wechat_pay.md ├── data/ │ ├── rules.json # Rule engine configuration (16 rules) │ ├── error_kb.json # Pre-set error database (125 errors) │ └── experience.json # Pre-set experience database (43 seeds) ``` ## Technology Stack - **MCP Framework**: mcp[cli] (FastMCP) - **DeepSeek Invocation**: openai SDK (compatible interface) - **Storage**: JSON files (~/.kaiwu/) - **CLI**: click + rich - **Logging**: loguru - **Python**: >=3.10 Dependencies are minimal (no litellm), installation < 30 seconds. ## Acknowledgments This project draws inspiration from the following open-source projects and academic achievements (only borrowing architectural concepts, not copying code): - **SWE-Exp Three-Layer Experience Database** — Design concept: precise match → fuzzy match → LLM analysis, automatic experience rewriting - **[mem0](https://github.com/mem0ai/mem0)** (Apache 2.0) — Experience database four-state decision (ADD/UPDATE/DELETE/NONE), comparison before writing - **[MCP Protocol](https://modelcontextprotocol.io/)** (MIT) — Model Context Protocol, tool registration and invocation framework ### AI-Generated Content Statement The following content was assisted by Claude (Anthropic) and reviewed by humans before being included in the project: - `kaiwu/scenes/*.md` — 19 coding scene specifications - `kaiwu/knowledge/*.md` — Chinese developer knowledge base, Python compatibility guide, dependency pitfalls collection, tool guidance - `data/error_kb.json` — Pre-set error knowledge base (125 common errors + solutions) - `data/experience.json` — Pre-set experience database (43 seed experiences) These contents are based on AI's general knowledge and do not include direct copying of third-party copyright materials. ## License **Apache License 2.0** — See [LICENSE](LICENSE) You can freely use, modify, and distribute all code and data in this project. ### Contributor Agreement (CLA) When submitting code or data to this project (Pull Request), you need to sign the [Contributor License Agreement (CLA)](CLA.md). Core terms of CLA: - You retain all rights to your contributions - You grant the project maintainers the right to use community-contributed experience databases, error databases, and knowledge databases in cloud services - This enables us to integrate community-contributed data when launching cloud synchronization and community sharing features > Personal use, modification, and distribution are not affected by CLA; CLA only applies to scenarios where contributions are submitted to this repository.