跳到主要内容KWCode天工开物 · prolist返回项目库
查看仓库原始简介
一个能持续增强本地开源模型的cli，专门为本地部署模型优化的coding窗口。目前仍然处于mvp未能大规模测试和端到端跑通，欢迎指正🙏🏻🙏🏻🙏🏻
项目解读由 AI 根据历史资料整理，尚未经人工复核。仓库资料更新于 2026-09-08，与历史解读分开保留。
项目概览
KWCode（天工开物）是一个专为本地开源模型优化的 Coding Agent CLI 工具，由中国开发者 val1813（ValHuang）开发，MIT 协议开源。其核心定位是让 8B-30B 参数的小模型也能完成编程任务，数据不出网。
KWCode 采用确定性专家流水线架构，LLM 只负责任务分类和代码生成，文件定位、验证、调试等环节由确定性代码完成。内置 5 个确定性工具，支持 BM25+AST 调用图定位、三阶段重试、Debug Subagent 运行时调试、DAG 多任务编排、专家飞轮自动积累经验等功能。
项目支持 Windows/macOS/Linux 平台，Windows 原生运行，无需 WSL2。系统要求 Python 3.10+，支持任意 OpenAI 兼容 API。当前处于 MVP 阶段，AST 引擎主要支持 Python，社区规模较小。
解决什么问题
KWCode 主要解决本地开源小模型（8B-30B）在编程任务中面临的五大痛点：上下文爆炸、错误重复、不能调用工具、数据安全、代码定位靠猜。现有 Coding Agent 框架（如 Claude Code、Cursor）都是为强 LLM 设计的，本地小模型无法胜任。作者因公司代码不能传到海外服务器，且市面上的开源工具不支持 Windows 原生运行，从 2026 年初开始自研。
工作方式
KWCode 采用确定性专家流水线架构，核心思路是“LLM 只做分类和生成，确定性流水线做决策和验证”。系统由 5 个元专家组成：Gate（任务分类）、Locator（BM25+AST 调用图定位）、Generator（代码生成）、Verifier（语法检查+pytest）、Debugger（运行时调试），另有 Reviewer 进行需求对齐审查。领域知识通过 15 个 SKILL.md 文件注入，与执行代码彻底解耦。
核心能力
- 纯算法上下文压缩（头尾保留+中间关键词提取，<10ms）
- 三阶段重试+Reflection+Debug Subagent
- 内置 5 个确定性工具（read_file/write_file/run_bash/list_dir/git）
- BM25+AST 调用图两阶段定位，毫秒级，不调 LLM
- sys.settrace 非侵入式捕获运行时变量值
- DAG 多任务编排，支持并行与串行混合
- 专家飞轮自动积累经验，三道门验证后投产
- 模型能力自适应（<10B/10-30B/>30B 不同策略）
- 全部本地运行，零网络依赖（搜索增强可选）
- Windows 原生支持，无需 WSL2
使用前需要了解
- AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
- KWCode 面向数据合规要求高、只能使用本地小模型的场景。当前处于 MVP 阶段，未大规模测试，可能存在未知 bug。AST 引擎主要支持 Python，JS/TS/Java/Go 支持尚不完善。8B 模型的推理能力天花板明显，复杂跨文件架构设计超出能力范围。不支持实时协作，是单机 CLI 工具。不支持 MCP 等标准插件协议。搜索增强需要 Docker。飞轮需要一定使用量才能发挥作用。三阶段重试不保证 100% 修复成功。
KWCode · 天工开物
为什么做这个
本地模型跑 Coding Agent，有五个核心痛点
痛点一：上下文爆炸
小模型窗口只有 8K-32K。对话几轮后 context 塞满，模型开始胡说。现有工具没有上下文管理，用着用着就废了。
KWCode 解法：纯算法上下文压缩（头尾保留 + 中间关键词提取，<10ms），自动在 context 快满时压缩历史对话。你能一直聊下去，不会突然变傻。
痛点二：错误重复回复
小模型修 bug 失败后，用同样的方式再试一遍，三次机会全浪费在同一个错误上。
KWCode 解法：三阶段重试策略——第一次正常描述，第二次从错误信息出发，第三次最小化修改。每次重试前先做 Reflection（LLM 一句话分析上次为什么失败），绝不重复同样的错。失败模式还会记录到 PATTERN.md，下次遇到类似任务直接提高风险等级。
痛点三：不能调用工具
大部分本地 agent 框架只能生成代码文本，不能真正执行命令、读写文件、跑测试。生成的代码对不对，全靠人肉验证。
KWCode 解法：内置 5 个确定性工具（read_file / write_file / run_bash / list_dir / git），Generator 生成 patch 后 Verifier 自动执行语法检查 + pytest，失败立即重试。不是"建议你跑一下测试"，而是真的帮你跑了。
痛点四：数据安全
Claude Code、Cursor 把代码发到海外服务器。公司代码、内网项目走不通。
KWCode 解法：全部本地运行，代码不出你的电脑。模型跑在 Ollama，搜索跑在本地 SearXNG，统计数据存本地 SQLite。零网络依赖（搜索增强可选）。
痛点五：代码定位靠猜
现有工具把文件列表丢给 LLM 让它猜哪个文件相关。小模型猜错文件，后面全错。
KWCode 解法：BM25 + AST 调用图两阶段定位，毫秒级，不调 LLM。沿调用链追踪隐藏依赖，不靠猜。
核心技术原理
原理一：确定性专家流水线
理论来源：Agentless（ICSE 2025）——确定性流水线在 SWE-bench 上同时达到最高通过率和最低成本，优于复杂 agent 架构。
不让 LLM 自主决定下一步，而是走确定性的专家流水线：
用户输入
└─► Gate 任务分类，毫秒级路由
└─► Locator 精准定位文件和函数（BM25+调用图，不调LLM）
└─► Generator 只生成修改部分（从文件读original，LLM只写modified）
└─► Verifier 语法检查 + pytest 自动验证
└─► SearchAugmentor 失败时自动搜索补充信息
小模型只需要在极小的 context 里做一件明确的事。失误可以被及时发现和纠正，不会滚雪球。
原理二：BM25 + AST 调用图定位（核心差异化）
- CodeCompass（arXiv:2602.20048，2026）：258 次实验证明，隐藏依赖任务（G3类）图遍历准确率 99.4% vs BM25 76.2%，相差 23.2 个百分点
- KGCompass（arXiv:2503.21710，2025）：SWE-bench Lite 成功率 58.3%，89.7% 的成功定位来自多跳图遍历
什么是 G3 类任务：bug 所在的文件名和函数名，与错误描述没有任何关键词重叠，只能通过调用链追踪发现。这是真实项目里最常见、最难定位的一类 bug。
用户描述 "修复登录失败的 bug"
│
├─► 阶段1：BM25 关键词召回（毫秒级，不调 LLM）
│ 从代码库所有函数/类中，按关键词相关性
│ 召回 top-20 候选函数
│
└─► 阶段2：AST 调用图展开（毫秒级，不调 LLM）
对每个候选函数，沿调用图向上向下各展开 2 跳
发现那些名字和 bug 毫无关联但实际是根因的隐藏函数
结果：精准的相关函数集合，直接注入 Generator
技术实现：tree-sitter 多语言 AST + rank-bm25 + SQLite 调用图持久化。不需要 Neo4j，不需要 Docker，不需要 embedding 模型。
支持语言：Python（已完成）· JavaScript/TypeScript/Java/Go/Rust（规划中）
原理三：专家飞轮（越用越懂你的项目）
理论来源：EE-MCP（NeurIPS 2025）——从任务执行轨迹自动提取经验，验证可显著提升后续同类任务成功率。
第1天：15 个预置专家开箱即用
使用过程中，飞轮在后台静默积累：
同类任务成功 ≥5 次 → 触发专家草稿生成
回测门：新专家成功率 ≥ 原流水线
AB 测试门：10 次真实对比，提升 >10%
三道门全过 → 专家正式投产，弹出通知
一个月后：你的项目有了专属专家池
kwcode expert export SpringBootExpert
# → SpringBootExpert-1.0.0.kwx
kwcode expert install path/to/Vue3Expert.kwx
原理四：模型能力自适应
KWCode 是全球唯一针对本地小模型能力差异做自适应的 coding agent。
功能特性
代码能力
- BM25 + 调用图两阶段定位，G3 隐藏依赖准确率 99.4%（论文验证）
- Generator 只改必要部分，从文件读 original，LLM 只生成 modified
- 三阶段重试：正常描述 → 从错误出发 → 最小化修改，不重复同样的错
- Reflection 机制：第一次失败先分析根因再重试
流程控制
/plan 计划模式：显示执行步骤+风险等级（High/Medium/Low），确认后才动文件Checkpoint 快照：任务开始前自动备份，失败一键还原，降级建议KWCODE.md 项目规则：写项目约定，按任务类型分段注入，永远不忘
知识积累
- 三层记忆：PROJECT.md（项目结构）/ EXPERT.md（专家记录）/ PATTERN.md（失败模式）
- 非代码文件读取：PDF 需求文档 / Word 规范 / Markdown，BM25 匹配相关段落注入
- 失败模式记录：历史失败积累，/plan 时作为风险评估依据
搜索增强
- 默认 DuckDuckGo（零配置，pip install 就能用）
- 可选 SearXNG 自部署：
kwcode setup-search 一键安装，数据完全不出网
- 四级内容提取：trafilatura → newspaper3k → readabilipy → BeautifulSoup
- 并行搜索 + BM25 重排：结果质量优先
- 意图感知：代码/论文/包/debug 自动优化搜索词
Office 文档
- Excel：openpyxl 样式模板，深色表头，斑马纹，公式，冻结首行
- PPT：python-pptx，商务配色，三明治结构，不用默认白底
- Word：python-docx，中文首行缩进，规范字体，表格样式
价值可见
kwcode stats：完成任务数、节省时间估算、专属专家数- 飞轮通知：专家投产时弹出，显示成功率提升和速度对比
- 里程碑提醒：完成 50/100/200 个任务时自动汇报
中国本地化
与竞品对比
快速开始
系统要求
- Python 3.10+
- 任意 OpenAI 兼容 API（本地 Ollama / DeepSeek / 硅基流动 / Qwen 云端 等）
- Docker（可选，用于 SearXNG 搜索增强）
安装
# 安装 KWCode
pip install kwcode
# 国内加速：
pip install kwcode -i https://pypi.tuna.tsinghua.edu.cn/simple
# 启动
kwcode
/api default https://api.deepseek.com your-api-key
可选：安装搜索增强
需要 Docker Desktop 已安装并运行。会自动拉取 SearXNG 镜像（约 200MB）并启动容器。不装也能用，默认走 DuckDuckGo 搜索。
使用指南
交互模式（推荐）
> 修复登录验证失败的问题
> 写一个 FastAPI 登录接口，包含 JWT 认证
> 把 calculate_price 拆成更小的函数
单次执行
kwcode "修复登录验证失败的问题"
kwcode --plan "重构数据库连接层"
REPL 命令
/plan <任务> 计划模式，显示步骤和风险后再执行
/model qwen3:14b 切换模型
/api API 配置（见下方说明）
/experts 查看已注册专家
/memory 查看项目记忆
/init 初始化项目规则文件
/cd <路径> 切换项目目录
/help 显示帮助
接入任意 API
KWCode 支持任何 OpenAI 兼容的 API，包括 DeepSeek、Qwen 云端、硅基流动、零一万物、Groq 等。
/api temp https://api.deepseek.com your-api-key
/api temp https://api.siliconflow.cn/v1 your-api-key
/api default https://api.deepseek.com your-api-key
kwcode --ollama-url https://api.deepseek.com
项目规则文件
在项目根目录创建 KWCODE.md，写入你的项目约定：
## [all] 通用规则
- 测试框架：pytest
- 运行测试：pytest tests/ -v
## [bugfix] Bug修复规则
- 修复前先理解错误原因
- 不要改测试代码
## [codegen] 代码生成规则
- 变量命名用 snake_case
- 必须写 docstring
KWCode 启动时自动加载，按任务类型注入对应规则。
Office 文档生成
> 做一个季度销售报表 Excel，包含月份、销售额、环比增长
> 做一个项目汇报 PPT，商务风格，5页
> 写一份技术方案 Word，包含架构图描述和接口设计
专家管理
kwcode expert list # 查看所有专家
kwcode expert info BugFix # 查看专家详情
kwcode expert export BugFix # 导出为 .kwx 文件
kwcode expert install path/to/x.kwx # 安装外部专家
kwcode expert create MyExpert # 创建自定义专家
价值报告
显示过去 30 天的任务完成数、节省时间估算、最活跃专家。数据仅存本地。
开发者安装
git clone https://github.com/val1813/kwcode.git
cd kwcode
pip install -e ".[dev]"
python -m pytest kaiwu/tests/ -v --ignore=kaiwu/tests/bench_tasks
# 282 tests should pass
项目结构
kaiwu/
├── cli/main.py # CLI 入口，REPL，spinner，结果摘要
├── core/
│ ├── gate.py # LLM 任务分类
│ ├── orchestrator.py # 确定性流水线编排
│ ├── planner.py # /plan 计划模式 + 风险评估
│ ├── checkpoint.py # 文件快照（git stash / 文件复制）
│ ├── kwcode_md.py # KWCODE.md 规则加载
│ └── model_capability.py # 模型能力自适应
├── experts/
│ ├── locator.py # BM25 + 调用图定位
│ ├── generator.py # 代码生成（只改必要部分）
│ ├── verifier.py # 语法检查 + pytest
│ └── search_augmentor.py # 搜索增强 + BM25 重排
├── search/
│ ├── duckduckgo.py # SearXNG + DDG 并行搜索
│ ├── extraction_pipeline.py # 四级内容提取
│ └── intent_classifier.py # 意图感知分类
├── knowledge/doc_reader.py # PDF/Word/MD 文档读取
├── flywheel/ # 专家飞轮（轨迹→模式→生成→AB测试）
├── registry/ # 专家注册表 + .kwx 打包
├── memory/ # 三层记忆系统
├── ast_engine/ # tree-sitter AST + 调用图
├── notification/ # 飞轮通知
├── stats/ # 价值量化（SQLite）
└── llm/ # Ollama + llama.cpp 双后端
参考文献
- Agentless：Xia et al. ICSE 2025 — 确定性流水线优于复杂 agent
- CodeCompass：arXiv:2602.20048, 2026 — 图遍历 G3 任务 99.4% vs BM25 76.2%
- KGCompass：Yang et al. arXiv:2503.21710, 2025 — SWE-bench Lite 58.3%
- AgentCoder：Huang et al. EMNLP 2023 — 多专家分工验证
- EE-MCP：NeurIPS 2025 — 任务轨迹经验提取机制
- Agent Psychometrics：arXiv:2604.00594, 2026 — 任务特征预测 agent 成功率
参与贡献
KWCode 是中国开发者做的，也需要中国开发者一起来完善。
不管你在北京还是新加坡，在上海还是旧金山，只要你是华人开发者，都欢迎参与。
最需要的贡献
新增预置专家（最简单，编辑一个 YAML 文件）：
# 急需认领：
Vue3Expert / DjangoExpert / GoGinExpert / RustActixExpert
K8sExpert / DockerExpert / RedisExpert / MySQLExpert
kwcode expert create MyExpert
# 用自己真实项目测试 ≥5 个任务，跑通率 ≥80%
# 提 PR
语言支持扩展：PHP · C# · Kotlin · Swift · Dart（AST 调用图）
贡献流程
git clone https://github.com/val1813/kwcode.git
cd kwcode
pip install -e ".[dev]"
python -m pytest kaiwu/tests/ -v --ignore=kaiwu/tests/bench_tasks
git checkout -b feat/your-feature
# 开发 → 测试 → PR
Issues：Bug 报告、功能建议
Discussions：技术讨论、专家设计
License
如果 KWCode 对你有帮助，请给一个 ⭐
这不只是一个工具，是华人开发者社区共同的技术资产。
天工开物 · KWCode
09.08
