[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-940":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":14,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},940,"kwcode","val1813\u002Fkwcode","val1813","一个能持续增强本地开源模型的cli，专门为本地部署模型优化的coding窗口。目前仍然处于mvp未能大规模测试和端到端跑通，欢迎指正🙏🏻🙏🏻🙏🏻",null,"Python",645,93,4,9,0,3,6,52,9.92,false,"master",true,[],"2026-06-12 02:00:20","# KWCode · 天工开物\n\n\u003Cdiv align=\"center\">\n\n**中国开发者的本地 Coding Agent**\n\n*数据不出网 · Windows 打开就能用 · 越用越懂你的项目*\n\n[![License: Apache-2.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-green.svg)](LICENSE)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10+-blue.svg)](https:\u002F\u002Fpython.org)\n[![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPlatform-Windows%20%7C%20Mac%20%7C%20Linux-lightgrey.svg)]()\n[![Multi-Platform Tests](https:\u002F\u002Fgithub.com\u002Fval1813\u002Fkwcode\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fval1813\u002Fkwcode\u002Factions\u002Fworkflows\u002Ftest.yml)\n[![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVersion-1.6.1-blue.svg)]()\n\n\u003C\u002Fdiv>\n\n---\n\n> **v1.6.1 已发布！** 架构收敛：删除冗余Expert类，纯确定性机制驱动pipeline。安装命令：\n>\n> ```bash\n> pip install kwcode\n> # 国内加速\n> pip install kwcode -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> ```\n\n---\n\n## 更新日志\n\n| 日期 | 内容 |\n|------|------|\n| 05-07 | **v1.6.1** 架构收敛：删除WholeFileImplExpert\u002FDependencyFixExpert，纯确定性机制驱动pipeline。Generator增强(upstream_constraints注入system prompt + retry_hint携带上次代码 + tier=small填空框架)。License改为Apache-2.0。513 tests green |\n| 05-07 | **v1.6.0** MoE确定性架构：GapDetector(11种GapType,零LLM) + ExecutionStateTracker(回归检测) + EnvProber(工具链\u002F依赖自动修复) + Gate确定性优先路由 + 63个专项诊断测试 |\n| 05-06 | **v1.5.1** Hashline锚点编辑(61%输出token减少) + AdaptThink自适应推理(easy→off\u002Fhard→4096) + Fast\u002FSlow双阶段(首次fast失败升级slow) + 三飞轮(策略统计\u002F用户模式\u002FSKILL提炼) + 匿名遥测(opt-in, HMAC防护) + 审计日志(`kwcode log`) + model命令 + model_capability全量接入(tier检测→ctx自适应→prompt约束) + 缩进对齐修复 |\n| 05-06 | **v1.5.0** SearchSubagent隔离搜索(独立context窗口+并行读取) + UpstreamManifest跨文件契约(AST提取签名\u002F常量，零LLM) + PENCIL式context压缩 + Verifier跨文件一致性检查 + orchestrator run()拆分(410→253行) + CLI拆分(1861→173行) + ruff\u002Fmypy配置 |\n| 05-06 | **v1.4.0** 多语言AST支持(Go\u002FTS\u002FRust\u002FJava + ast-grep预定义模板) + FastAPI Server(SSE端口7355) + Textual TUI(`kwcode --tui`) + VSCode插件(薄客户端) + 多语言Verifier(jest\u002Fgo test\u002Fcargo test\u002Fmvn test) |\n| 05-06 | **v1.3.0** EventBus事件总线 + ToolGateway权限隔离 + 错误策略路由(按error_type切换重试序列) + 认知门控(patch行数递减检测) + 3层渐进压缩 + Plan自动触发 + Worktree并行隔离 + Speculative Prefetch + SearchRouter意图感知搜索(arxiv\u002FS2\u002FGitHub\u002FPyPI\u002FOpen-Meteo零key) + Wink自修复监控 |\n| 05-06 | **v1.1.0** 熔断器+智能重试(syntax\u002Fimport快速熔断+scope缩小) + Gate置信度 + Verifier结构化错误 + Experience Replay(BM25历史轨迹) + Session多轮连贯 + Locator精准裁剪 |\n| 04-30 | 三层上下文架构 + SSH持久会话 + Gate\u002F路由优化 + PCED-Lite多源聚合 + 搜索site:自动限定 + qwen3:8b 20题真实验证 + 13项bug修复 |\n| 04-29 | 5元专家体系定稿 + 15个SKILL.md渐进加载 + DAG多任务编排 + Debug Subagent + Token预算\u002FGuardrails\u002F可观测性 |\n\n详细变更见 [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## 为什么做这个\n\n现有 coding agent 框架（Claude Code、Cursor、OpenCode）都是给强 LLM 设计的——靠模型的强推理能力调用工具、自主决策、完成任务。本地开源模型（8B-30B）做不到这些，会出错，会有幻觉。\n\nKWCode 的思路不同：**LLM 只做分类和生成，确定性流水线做决策和验证。** 专家系统承载领域知识，飞轮从使用中自动积累经验。小模型只需要在极小的 context 里做一件明确的事。\n\n### 本地模型跑 Coding Agent 的五个核心痛点\n\n**痛点一：上下文爆炸**\n\n小模型窗口只有 8K-32K。对话几轮后 context 塞满，模型开始胡说。\n\n> KWCode 解法：**纯算法上下文压缩**（3层渐进压缩：70%裁剪tool冗余→85%压缩中间轮次→95%摘要化早期对话，\u003C10ms），自动在 context 快满时分级压缩历史对话。\n\n**痛点二：错误重复**\n\n小模型修 bug 失败后，用同样的方式再试一遍，三次机会全浪费在同一个错误上。\n\n> KWCode 解法：**错误策略路由 + 认知门控 + Wink自修复**——按error_type切换重试序列（syntax→熔断\u002Fimport→确定性修复\u002Fruntime→先debug\u002Fpatch_apply→重新定位）；patch行数递减检测边际收益递减自动停止；Wink监控偏离行为注入课程纠正。\n\n**痛点三：不能调用工具**\n\n大部分本地 agent 框架只能生成代码文本，不能真正执行命令、读写文件、跑测试。\n\n> KWCode 解法：**内置 5 个确定性工具**（read_file \u002F write_file \u002F run_bash \u002F list_dir \u002F git），Generator 生成 patch 后 Verifier 自动执行语法检查 + pytest，失败立即重试。\n\n**痛点四：数据安全**\n\nClaude Code、Cursor 把代码发到海外服务器。公司代码、内网项目走不通。\n\n> KWCode 解法：**全部本地运行**，代码不出你的电脑。模型跑在本地，搜索跑在本地 SearXNG，统计数据存本地 SQLite。零网络依赖（搜索增强可选）。\n\n**痛点五：代码定位靠猜**\n\n现有工具把文件列表丢给 LLM 让它猜哪个文件相关。小模型猜错文件，后面全错。\n\n> KWCode 解法：**BM25 + AST 调用图**两阶段定位，毫秒级，不调 LLM。沿调用链追踪隐藏依赖，不靠猜。\n\n---\n\n## 核心技术原理\n\n### 原理一：确定性专家流水线 + 5 元专家体系\n\n**理论来源**：\n- Agentless（ICSE 2025）——确定性流水线优于复杂 agent\n- GitHub Copilot Atomic Skills（2025）——5 原子能力组合出所有复杂任务\n- MoE Routing Geometry（arXiv:2604.09780）——专家按能力分，不按领域分\n\nKWCode 的 5 个元专家（原子能力层，固定不变）：\n\n```\n用户输入\n  └─► Gate          任务分类，毫秒级路由 + 领域知识匹配\n        └─► Locator     精准定位文件和函数（BM25+调用图，不调LLM）\n              └─► Generator  只生成修改部分 + 领域知识注入（SKILL.md Level 2）\n                    └─► Verifier   语法检查 + pytest 自动验证\n                          └─► Debugger   失败时捕获运行时变量值（sys.settrace）\n                                └─► Reviewer   需求对齐审查（LLM对比意图vs变更）\n```\n\n15 个领域知识（SKILL.md 注入层，可扩展，不改变流水线）：\nBugFix · FastAPI · TestGen · API · DeepSeekAPI · Docstring · MyBatis · Office(3) · Refactor · SpringBoot · SQLOpt · TypeHint · UniApp · **Golang · TypeScript · Rust · Java**\n\n### 原理二：BM25 + AST 调用图定位\n\n**理论来源**：\n- CodeCompass（arXiv:2602.20048，2026）：图遍历 G3 任务准确率 **99.4%** vs BM25 **76.2%**\n- KGCompass（arXiv:2503.21710，2025）：SWE-bench Lite 成功率 **58.3%**\n\n**两阶段检索**：\n\n```\n用户描述 \"修复登录失败的 bug\"\n  ├─► 阶段1：BM25 关键词召回（毫秒级，不调 LLM）\n  └─► 阶段2：AST 调用图展开（毫秒级，不调 LLM）\n        沿调用链追踪隐藏依赖\n```\n\n技术实现：`tree-sitter` 多语言 AST + `ast-grep` 预定义模板查询 + `rank-bm25` + `SQLite` 调用图持久化。支持 Python\u002FJavaScript\u002FTypeScript\u002FGo\u002FRust\u002FJava（可选依赖 `pip install kwcode[multilang]`）。\n\n### 原理三：Debug Subagent（运行时调试）\n\n**理论来源**：Debug2Fix（Microsoft，ICML 2026）——弱模型 + 交互式调试器 > 强模型裸跑。GPT-5 + Debug2Fix 匹配 Claude Sonnet 基线性能。\n\n```\nVerifier 失败\n  └─► LLM 决定断点位置和要检查的变量\n        └─► sys.settrace 非侵入式捕获运行时变量值\n              └─► 真实调试数据注入下一轮 Generator retry\n```\n\n不用交互式 PDB，不修改源文件。用 `sys.settrace` 在目标行捕获变量值，失败时 fallback 到 `pytest --tb=long` 获取完整堆栈。\n\n### 原理四：DAG 多任务编排\n\n**理论来源**：LLMCompiler（ICML 2024）——任务分解 + 并行调度显著提升复杂任务完成率。\n\nKWCode 实现了轻量 DAG 调度器（零新依赖，ThreadPoolExecutor + Kahn 拓扑排序）：\n\n```\n\u002Fmulti task1 ; task2 ; task3          ← 全部并行\n\u002Fmulti task1 -> task2 -> task3        ← 串行链\n\u002Fmulti                                ← 交互式混合\n  + 给函数add加注释                     (并行)\n  + 给函数sub加注释                     (并行)\n  + >给修改后的代码写测试                (串行，依赖上面两个)\n```\n\n### 原理五：专家飞轮 + Prompt 自动优化\n\n**理论来源**：\n- EE-MCP（NeurIPS 2025）——从任务轨迹自动提取经验\n- SICA（arXiv:2504.15228）——自我改进编码代理\n- Reflexion——失败模式持久化\n\n```\n使用过程中，飞轮在后台静默积累：\n  同类任务成功 ≥5 次 → 触发专家草稿生成\n  回测门：新专家成功率 ≥ 原流水线\n  AB 测试门：10 次真实对比，提升 >10%\n  三道门全过 → 专家正式投产\n\nPrompt Optimizer（可选，需 Anthropic API key）：\n  分析成功轨迹 → 生成经验规则 → 追加到专家 YAML system_prompt\n  下次同类任务 Generator 拿到更准确的领域知识\n```\n\n### 原理六：Reflexion 持久化\n\n失败不白费。每次任务完成后（成功\u002F失败），结构化记录到 `REFLECTION.md`：\n\n```\n## bugfix 失败模式\n- [2026-04-29] JWT验证失败 → 根因：token过期时间单位错误\n\n## codegen 注意事项\n- [2026-04-29] FastAPI路由 → 注意：必须include_router\n```\n\n`\u002Fplan` 时自动读取历史 Reflection 作为风险提示，避免重蹈覆辙。\n\n### 原理七：模型能力自适应\n\n| 模型规模 | 自动策略 |\n|---------|---------|\n| \u003C10B（qwen3:8b） | 强制计划确认 · 任务范围≤2文件 · 第1次失败触发搜索 |\n| 10-30B（qwen3:14b） | 可选计划 · 任务范围≤4文件 · 第2次失败触发搜索 |\n| >30B（qwen3:72b） | 宽松策略 · 任务范围≤8文件 · 自动处理复杂任务 |\n\n### 原理八：SearchSubagent 隔离搜索 + 跨文件契约（v1.5.0）\n\n**理论来源**：WarpGrep（隔离搜索子代理减少context rot 70%）；CGM（图结构注入注意力，Qwen2.5-72B达43% SWE-bench Lite）；PENCIL（生成后擦除中间状态）；SWE-ContextBench（上下文质量 > 模型参数量）\n\n```\nSearchSubagent（独立context窗口）：\n  搜索中间状态永远不进入Generator工作记忆\n  并行文件读取：ThreadPoolExecutor，8个并发\n  只返回精确结果：{file, start_line, end_line, content}\n\nUpstreamManifest（跨文件契约追踪）：\n  确定性AST提取：函数签名 + 常量 + import依赖\n  Generator prompt注入跨文件约束，模型不用猜接口\n  Verifier前置检查：参数数量\u002F常量一致性（零LLM）\n\nPENCIL式压缩：\n  子任务完成 → 只保留签名\u002F常量\u002F文件路径\u002F测试状态\n  下游子任务拿到结构化摘要，不是完整推理链\n```\n\n### 原理九：EventBus 统一事件系统（v1.3.0）\n\n**理论来源**：Event Sourcing（Martin Fowler）；CC 27 个 hook 事件（arXiv:2604.14228）；Codified Context append-only 日志（arXiv:2602.20478）\n\n```\n所有模块通过 EventBus 发射事件：\n  专家层 → emit(\"reading_file\", {path}) → CLI 追加式渲染\n  重试层 → emit(\"circuit_break\", {reason}) → 用户可见\n  搜索层 → emit(\"search_solution\", {msg}) → 实时反馈\n\nappend-only 日志支持 replay\u002F时间旅行调试\n```\n\n### 原理十：错误策略路由 + 认知门控（v1.3.0）\n\n**理论来源**：Turn-Control Strategies（arXiv:2510.16786）动态预算比固定预算好 12-24%；SpecEyes（arXiv:2603.23483）认知门控\n\n```\n错误类型 → 专用重试序列：\n  syntax    → [generator, verifier]（1次后熔断）\n  import    → [import_fixer, verifier]（确定性修复，不调LLM）\n  runtime   → [debugger, generator, verifier]（先debug再修）\n  patch_apply → [locator, generator, verifier]（重新定位）\n  assertion → [generator, verifier]（2次后搜索）\n  contract_violation → [locator, generator, verifier]（跨文件契约冲突）\n\n认知门控：patch行数持续递减 → 边际收益递减 → 自动停止\nWink监控：scope_creep\u002Frepetitive_fix\u002Fpatch_miss → 注入纠正hint\n```\n\n### 原理十一：ToolGateway 权限隔离（v1.3.0）\n\n**理论来源**：CC 工具沙箱隔离（arXiv:2604.14228）；deny-first 权限模型\n\n```\n专家层（只做生成，输出 patch 结构）\n  ↓\nToolGateway（权限白名单 + 文件缓存 + 脏标记 + 事件emit）\n  ↓\nexecutor.py（实际执行 read_file \u002F write_file \u002F run_bash）\n\n每个专家只能调用白名单内的工具：\n  locator:   [read_file, list_dir]\n  generator: [read_file]（只读，不写）\n  verifier:  [apply_patch, write_file, run_bash]\n```\n\n---\n\n## 功能特性\n\n### 代码能力\n- BM25 + 调用图两阶段定位，G3 隐藏依赖准确率 99.4%（论文验证）\n- Generator 只改必要部分，从文件读 original，LLM 只生成 modified\n- 错误策略路由：按 error_type 切换重试序列，不重复同样的错\n- 认知门控：patch 行数递减检测边际收益递减，自动停止无效重试\n- Wink 自修复：检测 scope creep \u002F 原地打转 \u002F patch 失败，注入纠正\n- Speculative Prefetch：Locator 完成后后台预读文件，减少 Generator IO 等待\n- Cross-Encoder 搜索结果重排（可选，`pip install kwcode[rerank]`）\n\n### 多任务执行\n- `\u002Fmulti` 命令：串行（依赖链）+ 并行（独立任务）混合执行\n- DAG 拓扑排序 + ThreadPoolExecutor 并行调度\n- Worktree 隔离：并行任务在独立工作目录执行，避免文件冲突\n- 依赖上下文自动注入：前置任务结果传递给后续任务\n\n### 流程控制\n- `\u002Fplan 计划模式`：显示执行步骤+风险等级（High\u002FMedium\u002FLow），确认后才动文件\n- `Plan 自动触发`：hard 任务自动生成执行计划，不打断用户\n- `Checkpoint 快照`：任务开始前自动备份，失败一键还原\n- `KWCODE.md 项目规则`：写项目约定，按任务类型分段注入\n\n### 知识积累\n- 三层记忆：PROJECT.md \u002F EXPERT.md \u002F PATTERN.md\n- Reflexion 持久化：REFLECTION.md 结构化记录失败模式和注意事项\n- 非代码文件读取：PDF \u002F Word \u002F MD，BM25 匹配相关段落注入\n\n### 搜索增强\n- SearchRouter 意图感知路由：按任务类型选最精准搜索源\n- 零 key 默认可用：arXiv API \u002F Semantic Scholar \u002F GitHub REST \u002F PyPI JSON \u002F Open-Meteo\n- 错误驱动搜索：按失败类型精准触发（import→立刻搜\u002Fruntime→debug后搜\u002Fassertion→2次后搜）\n- 可选 SearXNG 自部署：`kwcode setup-search` 一键安装\n- 可选 Tavily key：通用搜索质量提升（1000次\u002F月免费）\n- 四级内容提取 + BM25 重排 + Cross-Encoder 精排\n\n### Office 文档\n- Excel \u002F PPT \u002F Word 生成\n\n### 多模态图片处理\n- `\u002Fpaste` 命令：从剪贴板粘贴图片\n- `\u002Fimage \u003Cpath>` 命令：添加图片文件\n- 图片分析：代码截图、UI设计图、文档表格\n- 基于图片的代码生成：UI截图→HTML\u002FCSS、错误截图→修复代码\n- 支持格式：PNG、JPG、JPEG、GIF、WebP、BMP\n- 安装：`pip install kwcode[multimodal]`\n\n**Vision API 配置**（使用前必配）：\n\n```bash\n# 设置环境变量（支持任何兼容 Anthropic Messages API 的服务）\nexport KWCODE_VISION_API_URL=\"https:\u002F\u002Fyour-provider.com\u002Fv1\u002Fmessages\"\nexport KWCODE_VISION_API_KEY=\"your-api-key\"\nexport KWCODE_VISION_MODEL=\"your-multimodal-model\"\n```\n\n支持的 Vision 模型示例：\n- OpenAI: `gpt-4o` (需通过代理转换为 Anthropic Messages API 格式)\n- Anthropic: `claude-sonnet-4-20250514` (endpoint: `https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages`)\n- 小米 MiMo: `mimo-v2-omni` (Anthropic 格式代理)\n- 本地模型: Ollama 多模态模型（通过 Ollama 兼容 endpoint）\n\n> **注意**：模型必须支持图片输入（多模态），纯文本模型无法处理图片任务。\n\n### 价值可见\n- `kwcode stats`：完成任务数、节省时间估算\n- 飞轮通知：专家投产时弹出\n- 里程碑提醒：完成 50\u002F100\u002F200 个任务时自动汇报\n\n### 中国本地化\n\n| 场景 | CC \u002F Hermes | KWCode |\n|------|------------|--------|\n| Windows 运行 | 仅 WSL2 \u002F 云端 | cmd\u002FPowerShell 原生 |\n| 搜索增强 | DDG\u002FBrave（被墙） | SearXNG 自部署 \u002F DDG fallback |\n| 推荐模型 | GPT \u002F Claude | DeepSeek · Qwen3 · GLM |\n| 中文交互 | 英文为主 | 全中文 |\n\n---\n\n## 与竞品对比\n\n| 功能 | Claude Code | Hermes | KWCode |\n|------|------------|--------|--------|\n| 数据安全 | ❌ 代码上传云端 | ✅ 本地 | ✅ 本地 |\n| Windows 原生 | ✅ | ❌ 仅 WSL2 | ✅ |\n| 小模型专家流水线 | ❌ | ❌ | ✅ 独有 |\n| 运行时调试（Debug Subagent） | ❌ | ❌ | ✅ 独有 |\n| 多任务串并行 | ❌ | ❌ | ✅ 独有 |\n| AST 调用图定位 | ❌ | ❌ | ✅ 独有 |\n| 专家飞轮 + Prompt 自动优化 | ❌ | ❌ | ✅ 独有 |\n| \u002Fplan 风险评估 | ✅ | ❌ | ✅ |\n| Checkpoint 回滚 | ✅ | ❌ | ✅ |\n| 价值量化仪表盘 | ❌ | ❌ | ✅ 独有 |\n| 开源 | ❌ | ✅ MIT | ✅ MIT |\n\n---\n\n## 快速开始\n\n### 系统要求\n\n- Python 3.10+\n- 任意 OpenAI 兼容 API（本地模型 \u002F DeepSeek \u002F 硅基流动 \u002F Qwen 云端 等）\n- Docker（可选，用于 SearXNG 搜索增强）\n\n| 使用方式 | 说明 |\n|---------|------|\n| 本地模型 | 安装本地推理引擎，拉取 qwen3:8b 等模型 |\n| 云端 API | `\u002Fapi default https:\u002F\u002Fapi.deepseek.com your-key`，无需本地显卡 |\n\n本地模型显存参考：\n\n| 显存 | 推荐模型 |\n|------|---------|\n| 4GB | gemma3:4b |\n| 8GB | qwen3:8b |\n| 16GB | qwen3:14b |\n| 24GB+ | qwen3:30b-a3b |\n\n**macOS 用户注意**：Apple Silicon (M1\u002FM2\u002FM3\u002FM4) 使用统一内存架构，无需单独显卡显存。推荐使用 [Ollama](https:\u002F\u002Follama.com) 本地运行模型，原生支持 Apple Silicon。\n\n### 安装\n\n#### macOS 安装\n\n```bash\n# 1. 安装 Python（如果尚未安装）\nbrew install python@3.12\n\n# 2. 安装 KWCode\npip3 install kwcode\n\n# 国内加速：\npip3 install kwcode -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n\n# 3. （推荐）安装 Ollama 用于本地模型\nbrew install ollama\nollama pull qwen3:8b\n\n# 4. 启动\nkwcode\n```\n\n**Apple Silicon 兼容性**：KWCode 完全支持 Apple Silicon (M1\u002FM2\u002FM3\u002FM4) Mac。GPU 信息显示为 \"Apple Silicon GPU\"，系统会自动检测统一内存。\n\n#### Windows \u002F Linux 安装\n\n```bash\n# 安装 KWCode\npip install kwcode\n\n# 国内加速：\npip install kwcode -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n\n# 可选：Cross-Encoder 搜索重排\npip install kwcode[rerank]\n\n# 可选：多语言 AST 支持（Go\u002FTS\u002FRust\u002FJava）\npip install kwcode[multilang]\n\n# 可选：TUI 界面\npip install kwcode[tui]\n\n# 可选：HTTP Server（供 VSCode 插件连接）\npip install kwcode[server]\n\n# 全部安装\npip install kwcode[full]\n\n# 启动\nkwcode\n```\n\n首次启动会引导你配置模型连接，按提示操作即可。\n\n用云端 API 不需要本地显卡：\n```\n\u002Fapi default https:\u002F\u002Fapi.deepseek.com your-api-key\n```\n\n### 可选：安装搜索增强\n\n```bash\nkwcode setup-search\n```\n\n需要 Docker Desktop 已安装并运行。会自动拉取 SearXNG 镜像并启动容器。不装也能用，默认走 DuckDuckGo 搜索。\n\n---\n\n## 使用指南\n\n### 交互模式（推荐）\n\n```bash\nkwcode\n```\n\n进入 REPL，直接输入任务描述：\n\n```\n > 修复登录验证失败的问题\n > 写一个 FastAPI 登录接口，包含 JWT 认证\n > 把 calculate_price 拆成更小的函数\n```\n\n### 多任务模式\n\n```\n > \u002Fmulti 给函数add加注释 ; 给函数sub加注释 ; 给函数mul加注释\n```\n\n三个任务并行执行。用 `->` 表示串行依赖：\n\n```\n > \u002Fmulti 重构extract_data函数 -> 给新函数写测试\n```\n\n交互式输入（`>` 前缀表示依赖前面的任务）：\n\n```\n > \u002Fmulti\n  + 给函数add加注释\n  + 给函数sub加注释\n  + >给修改后的代码写测试\n```\n\n### 单次执行\n\n```bash\nkwcode \"修复登录验证失败的问题\"\nkwcode --plan \"重构数据库连接层\"\nkwcode --tui                          # TUI 界面\nkwcode serve                          # 启动 HTTP server（端口 7355）\n```\n\n### REPL 命令\n\n```\n\u002Fplan \u003C任务>          计划模式，显示步骤和风险后再执行\n\u002Fmulti               多任务模式（串行+并行）\n\u002Fmodel qwen3:14b     切换模型\n\u002Fapi                 API 配置\n\u002Fexperts             查看已注册专家\n\u002Fmemory              查看项目记忆\n\u002Finit                初始化项目规则文件\n\u002Fcd \u003C路径>           切换项目目录\n\u002Fpaste               从剪贴板粘贴图片\n\u002Fimage \u003C路径>        添加图片文件\n\u002Fhelp                显示帮助\n```\n\n### 接入任意 API\n\nKWCode 支持任何 OpenAI 兼容的 API，包括 DeepSeek、Qwen 云端、硅基流动、零一万物、Groq 等。\n\n```\n\u002Fapi temp https:\u002F\u002Fapi.deepseek.com your-api-key      # 临时切换\n\u002Fapi default https:\u002F\u002Fapi.deepseek.com your-api-key   # 永久保存\n\u002Fapi show                                            # 查看当前配置\n```\n\n### 项目规则文件\n\n在项目根目录创建 `KWCODE.md`，写入你的项目约定：\n\n```markdown\n## [all] 通用规则\n- 测试框架：pytest\n- 运行测试：pytest tests\u002F -v\n\n## [bugfix] Bug修复规则\n- 修复前先理解错误原因\n- 不要改测试代码\n\n## [codegen] 代码生成规则\n- 变量命名用 snake_case\n- 必须写 docstring\n```\n\nKWCode 启动时自动加载，按任务类型注入对应规则。\n\n---\n\n## 开发者安装\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fval1813\u002Fkwcode.git\ncd kwcode\npip install -e \".[dev]\"\npython -m pytest kaiwu\u002Ftests\u002F -v --ignore=kaiwu\u002Ftests\u002Fbench_tasks\n# 424 tests should pass\n```\n\n### 项目结构\n\n```\nkaiwu\u002F\n├── cli\u002Fmain.py              # CLI 入口，REPL，\u002Fmulti 命令\n├── core\u002F\n│   ├── gate.py              # LLM 任务分类\n│   ├── orchestrator.py      # 确定性流水线编排\n│   ├── task_compiler.py     # DAG 多任务调度器\n│   ├── planner.py           # \u002Fplan 计划模式 + 风险评估\n│   ├── checkpoint.py        # 文件快照\n│   └── model_capability.py  # 模型能力自适应\n├── experts\u002F\n│   ├── locator.py           # [元专家] BM25 + 调用图定位\n│   ├── generator.py         # [元专家] 代码生成（只改必要部分）\n│   ├── verifier.py          # [元专家] 多语言语法检查 + 测试\n│   ├── debug_subagent.py    # [元专家] 运行时调试（sys.settrace）\n│   ├── reviewer.py          # [元专家] 需求对齐审查\n│   ├── search_augmentor.py  # 搜索增强 + BM25 + CE 重排\n│   └── vision_expert.py     # [元专家] 多模态图片处理\n├── server\u002F\n│   ├── app.py               # FastAPI + SSE 事件流（端口 7355）\n│   ├── pipeline_factory.py  # 共享 pipeline 构建\n│   └── models.py            # Pydantic 请求\u002F响应模型\n├── tui\u002F\n│   └── app.py               # Textual TUI（文件树 + 事件流）\n├── ast_engine\u002F\n│   ├── parser.py            # tree-sitter 多语言 AST\n│   ├── ast_grep_engine.py   # ast-grep 预定义模板查询\n│   ├── language_detector.py # 项目语言检测\n│   └── graph_builder.py     # SQLite 调用图持久化\n├── search\u002F\n│   ├── search_router.py     # 意图感知搜索路由\n│   ├── duckduckgo.py        # SearXNG + DDG 并行搜索\n│   └── intent_classifier.py # 意图感知分类\n├── flywheel\u002F\n│   ├── trajectory_collector.py  # 轨迹记录\n│   ├── pattern_detector.py      # 模式检测（Gate 1）\n│   ├── ab_tester.py             # 三道门验证\n│   └── prompt_optimizer.py      # SKILL.md 领域知识自动优化\n├── memory\u002F\n│   └── pattern_md.py        # PATTERN.md + REFLECTION.md\n├── builtin_experts\u002F         # 19 个 SKILL.md 领域知识目录\n├── registry\u002F                # 专家注册表（加载 SKILL.md）\n└── stats\u002F                   # 价值量化（SQLite）\n\nextension\u002F                   # VSCode 插件（薄客户端）\n├── src\u002Fextension.ts         # 插件入口\n├── src\u002Fserver-client.ts     # SSE 客户端\n├── src\u002Fpanel.ts             # Webview 面板\n└── package.json\n```\n\n---\n\n## 参考文献\n\n| 论文\u002F项目 | 来源 | KWCode 中的应用 |\n|-----------|------|----------------|\n| **Agentless** | Xia et al., ICSE 2025 | 确定性流水线优于复杂 agent，KWCode 整体架构基于此思路 |\n| **CodeCompass** | arXiv:2602.20048, 2026 | 图遍历 G3 任务 99.4%，KWCode 的 AST 调用图定位直接借鉴 |\n| **KGCompass** | Yang et al., arXiv:2503.21710, 2025 | 多跳图遍历定位，验证了调用图展开的有效性 |\n| **Debug2Fix** | Garg & Huang (Microsoft), ICML 2026 | 弱模型+调试器 > 强模型裸跑，KWCode 的 Debug Subagent 直接实现此论文思路 |\n| **LLMCompiler** | Kim et al., ICML 2024 | DAG 任务分解+并行调度，KWCode 的 TaskCompiler 借鉴其调度思想（自研轻量实现） |\n| **EE-MCP** | NeurIPS 2025 | 任务轨迹经验提取，KWCode 飞轮的轨迹→模式→专家生成流程借鉴此机制 |\n| **SICA** | arXiv:2504.15228, 2025 | 自我改进编码代理，KWCode 的 Prompt Optimizer 借鉴其自我优化循环 |\n| **Self-Play** | arXiv:2502.14948, 2025 | 自博弈提升代码能力，飞轮 AB 测试门的设计参考 |\n| **Reflexion** | Shinn et al., NeurIPS 2023 | 失败模式持久化+重试时注入，KWCode 的 REFLECTION.md 直接实现 |\n| **AgentCoder** | Huang et al., EMNLP 2023 | 多专家分工验证，KWCode 的 Gate→专家流水线参考此分工模式 |\n| **Agent Psychometrics** | arXiv:2604.00594, 2026 | 任务特征预测 agent 成功率，KWCode 的模型能力自适应参考此研究 |\n| **TRUSTEE** | 2026 | 8B 模型可靠 tool calling 验证，KWCode 的 Gate 设计参考 |\n| **Dive into Claude Code** | arXiv:2604.14228, 2026 | ToolGateway 分层、EventBus 27 事件、5 层压缩管道、Worktree 隔离 |\n| **Wink** | arXiv:2602.17037, 2026 | Wink 自修复监控；失败类型分类（Drift\u002FReasoning\u002FTool） |\n| **ARCS** | arXiv:2504.20434, 2026 | 搜索前置于生成（retrieval-before-generation），按失败类型精准触发 |\n| **Speculative Actions** | arXiv:2510.04371 | Speculative Prefetch，下一步预测准确率 55% |\n| **SpecEyes** | arXiv:2603.23483 | 认知门控熔断，基于答案可分性检测边际收益递减 |\n| **OPENDEV** | arXiv:2603.05344 | 渐进上下文压缩，token 使用率分级触发 |\n| **Codified Context** | arXiv:2602.20478 | EventBus append-only 日志，跨 session 三层记忆 |\n| **Turn-Control Strategies** | arXiv:2510.16786 | 错误策略路由，动态预算比固定预算好 12-24% |\n| **CodeScout** | arXiv:2603.05744 | 问题陈述增强，输入质量是关键瓶颈 |\n\n### 借鉴的开源项目\n\n| 项目 | 借鉴点 |\n|------|--------|\n| **Claude Code** (Anthropic) | CLAUDE.md 项目规则文件 → KWCode 的 KWCODE.md；Checkpoint 文件快照机制；\u002Fplan 计划模式；ToolGateway 权限隔离；EventBus 事件系统 |\n| **Hermes** (Anthropic) | REPL 交互模式、MEMORY.md 记忆系统的交互设计 |\n| **OpenHands V1** (All Hands AI) | Agent delegation 任务分解思路、Context Condensation 上下文压缩、LLM-based 集成测试回检 |\n| **OpenCode** | 本地模型 coding agent 的产品形态参考；早期版本曾作为执行层底座探索 |\n| **SearXNG** | 零 API key 的本地搜索引擎，KWCode 集成为搜索后端 |\n| **rank-bm25** | BM25Plus 算法实现，用于代码定位和搜索结果重排 |\n| **tree-sitter** | 多语言 AST 解析，用于调用图构建 |\n| **sentence-transformers** | Cross-Encoder 模型，用于搜索结果精排（可选依赖） |\n\n### 设计决策的来源\n\n以下关键设计决策来自项目早期的架构讨论和实验：\n\n- **不用 ReAct 循环，用确定性流水线**：小模型在 ReAct 循环里容易失控，确定性流水线每步输入输出格式固定，LLM 只在 Generator 出现一次\n- **专家是 SKILL.md 知识载体，不是 Python 类**：早期实验过 Python 专家（ExpertBase 继承体系），发现把领域知识和执行逻辑混在一起方向错误，回退到 SKILL.md 渐进式加载\n- **不用 LoRA 训练专家**：早期实验证明 LoRA 效果差、换模型要重训，改为 SKILL.md 内容自动进化\n- **任务拆分不枚举模板**：参考 OpenHands V1 的 agent delegation，复杂任务让 LLM 一次性输出 DAG JSON，失败退化为单任务\n- **专家约束越严格越好**：不是教 8B 模型做什么，是限制它只能在什么范围内做。约束越严格，犯错空间越小\n\n---\n\n## 参与贡献\n\n**KWCode 是中国开发者做的，欢迎贡献代码。** 详细规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n### 快速开始\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fval1813\u002Fkwcode.git\ncd kwcode\npip install -e \".[dev]\"\npython -m pytest kaiwu\u002Ftests\u002F -v --ignore=kaiwu\u002Ftests\u002Fbench_tasks\n# 全部绿才能提 PR\n```\n\n### 架构红线（违反即拒绝）\n\n| 红线 | 说明 |\n|------|------|\n| RED-1 | Gate 必须输出结构化 JSON，不得字符串解析 |\n| RED-2 | LLM 只做分类和生成，不得让 LLM 决定流水线下一步 |\n| RED-3 | 每个专家独立上下文，不继承上一个专家的对话历史 |\n| RED-4 | 新增依赖必须离线可用 |\n| RED-5 | 重试次数必须有硬上限 |\n\n**一票否决**：向量数据库、企业级安全库、需要云服务的依赖、多 Agent 并行框架、自动修改 Gate 路由规则。\n\n### 最欢迎的贡献\n\n| 类型 | 说明 |\n|------|------|\n| 新增专家 | 创建 `kaiwu\u002Fbuiltin_experts\u002F\u003Cname>\u002FSKILL.md`，最简单的贡献方式 |\n| Bug 修复 | 附复现步骤和测试用例 |\n| 多语言 AST | JS\u002FTS\u002FGo\u002FRust\u002FJava 调用图支持（✅ v1.4.0 已实现） |\n| 性能优化 | Locator 定位速度、ContextPruner 压缩质量 |\n\n急需认领的专家：Vue3 · React · Django · FastAPI · Go Gin · Rust Actix · K8s · Docker · MySQL · Redis\n\n### PR 要求\n\n1. **测试全绿**：`python -m pytest kaiwu\u002Ftests\u002F --ignore=kaiwu\u002Ftests\u002Fbench_tasks`\n2. **新功能必须有测试**（改 core\u002Fexperts\u002Fflywheel 目录时）\n3. **新增依赖需说明**用途和离线可用性\n4. **改 Gate\u002FOrchestrator 逻辑**请先开 Issue 讨论\n\n完整 PR 模板和代码风格规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n---\n\n## License\n\nMIT\n","KWCode 是一个专为本地开源模型优化设计的编码助手CLI工具，旨在通过持续增强本地部署的模型来提高开发效率。其核心功能包括上下文压缩、错误策略路由以及认知门控等机制，以解决小规模模型在处理复杂任务时遇到的问题如上下文溢出和重复错误。该工具采用Python编写，并支持Windows、Mac和Linux平台，特别适合需要在本地环境中高效利用有限资源进行软件开发的场景。尽管目前仍处于MVP阶段，但已显示出对于提升本地模型性能的强大潜力。",2,"2026-06-11 02:40:22","CREATED_QUERY"]