KWCode · 天工开物

中国开发者的本地 Coding Agent

数据不出网 · Windows 打开就能用 · 越用越懂你的项目

v1.0.7 已发布，可测试使用！ 感谢各位试用提报优化建议。安装命令：

pip install kwcode
# 国内加速
pip install kwcode -i 

更新日志

| 日期 | 内容 | |------|------| | 04-30 | 三层上下文架构 + SSH持久会话 + Gate/路由优化 + PCED-Lite多源聚合 + 搜索site:自动限定 + qwen3:8b 20题真实验证 + 13项bug修复 | | 04-29 | 5元专家体系定稿 + 15个SKILL.md渐进加载 + DAG多任务编排 + Debug Subagent + Token预算/Guardrails/可观测性 |

详细变更见 CHANGELOG.md

为什么做这个

现有 coding agent 框架（Claude Code、Cursor、OpenCode）都是给强 LLM 设计的——靠模型的强推理能力调用工具、自主决策、完成任务。本地开源模型（8B-30B）做不到这些，会出错，会有幻觉。

KWCode 的思路不同：LLM 只做分类和生成，确定性流水线做决策和验证。 专家系统承载领域知识，飞轮从使用中自动积累经验。小模型只需要在极小的 context 里做一件明确的事。

本地模型跑 Coding Agent 的五个核心痛点

痛点一：上下文爆炸

小模型窗口只有 8K-32K。对话几轮后 context 塞满，模型开始胡说。

KWCode 解法：纯算法上下文压缩（头尾保留 + 中间关键词提取， KWCode 解法：三阶段重试 + Reflection + Debug Subagent——第一次正常描述，第二次从错误信息出发（注入运行时调试数据），第三次最小化修改。每次重试前先做 Reflection（LLM 分析上次为什么失败）+ Debug Subagent（sys.settrace 捕获真实变量值），绝不重复同样的错。

痛点三：不能调用工具

大部分本地 agent 框架只能生成代码文本，不能真正执行命令、读写文件、跑测试。

KWCode 解法：内置 5 个确定性工具（read_file / write_file / run_bash / list_dir / git），Generator 生成 patch 后 Verifier 自动执行语法检查 + pytest，失败立即重试。

痛点四：数据安全

Claude Code、Cursor 把代码发到海外服务器。公司代码、内网项目走不通。

KWCode 解法：全部本地运行，代码不出你的电脑。模型跑在本地，搜索跑在本地 SearXNG，统计数据存本地 SQLite。零网络依赖（搜索增强可选）。

痛点五：代码定位靠猜

现有工具把文件列表丢给 LLM 让它猜哪个文件相关。小模型猜错文件，后面全错。

KWCode 解法：BM25 + AST 调用图两阶段定位，毫秒级，不调 LLM。沿调用链追踪隐藏依赖，不靠猜。

核心技术原理

原理一：确定性专家流水线 + 5 元专家体系

理论来源：

• Agentless（ICSE 2025）——确定性流水线优于复杂 agent
• GitHub Copilot Atomic Skills（2025）——5 原子能力组合出所有复杂任务
• MoE Routing Geometry（arXiv:2604.09780）——专家按能力分，不按领域分

KWCode 的 5 个元专家（原子能力层，固定不变）：

用户输入
  └─► Gate          任务分类，毫秒级路由 + 领域知识匹配
        └─► Locator     精准定位文件和函数（BM25+调用图，不调LLM）
              └─► Generator  只生成修改部分 + 领域知识注入（SKILL.md Level 2）
                    └─► Verifier   语法检查 + pytest 自动验证
                          └─► Debugger   失败时捕获运行时变量值（sys.settrace）
                                └─► Reviewer   需求对齐审查（LLM对比意图vs变更）

15 个领域知识（SKILL.md 注入层，可扩展，不改变流水线）： BugFix · FastAPI · TestGen · API · DeepSeekAPI · Docstring · MyBatis · Office(3) · Refactor · SpringBoot · SQLOpt · TypeHint · UniApp

原理二：BM25 + AST 调用图定位

理论来源：

• CodeCompass（arXiv:2602.20048，2026）：图遍历 G3 任务准确率 99.4% vs BM25 76.2%
• KGCompass（arXiv:2503.21710，2025）：SWE-bench Lite 成功率 58.3%

两阶段检索：

用户描述 "修复登录失败的 bug"
  ├─► 阶段1：BM25 关键词召回（毫秒级，不调 LLM）
  └─► 阶段2：AST 调用图展开（毫秒级，不调 LLM）
        沿调用链追踪隐藏依赖

技术实现：tree-sitter 多语言 AST + rank-bm25 + SQLite 调用图持久化。

原理三：Debug Subagent（运行时调试）

理论来源：Debug2Fix（Microsoft，ICML 2026）——弱模型 + 交互式调试器 > 强模型裸跑。GPT-5 + Debug2Fix 匹配 Claude Sonnet 基线性能。

Verifier 失败
  └─► LLM 决定断点位置和要检查的变量
        └─► sys.settrace 非侵入式捕获运行时变量值
              └─► 真实调试数据注入下一轮 Generator retry

不用交互式 PDB，不修改源文件。用 sys.settrace 在目标行捕获变量值，失败时 fallback 到 pytest --tb=long 获取完整堆栈。

原理四：DAG 多任务编排

理论来源：LLMCompiler（ICML 2024）——任务分解 + 并行调度显著提升复杂任务完成率。