From 5765a4f32973e4cdaee2a3e58d6e0c78d64b5ae9 Mon Sep 17 00:00:00 2001 From: Val-sss <154882199@qq.com> Date: Tue, 28 Apr 2026 18:05:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20pain=20points=20section=20?= =?UTF-8?q?=E2=80=94=20context=20overflow,=20retry=20loops,=20tool=20execu?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 40 ++++++++++++++++++++++++++++------------ README_zh.md | 40 ++++++++++++++++++++++++++++------------ 2 files changed, 56 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index f3f27d6..9cd81fe 100644 --- a/README.md +++ b/README.md @@ -18,21 +18,37 @@ ## 为什么做这个 -### 中国开发者用 AI Coding 工具，有三道绕不开的墙 +### 本地模型跑 Coding Agent，有五个核心痛点 -**第一道：数据安全墙** +**痛点一：上下文爆炸** -Claude Code、Cursor、GitHub Copilot 把你的代码发到海外服务器。公司代码、内网项目、涉密工程，这条路根本走不通。国内访问这些工具本来就不稳定，一个任务跑到一半断连，体验极差。 +小模型窗口只有 8K-32K。对话几轮后 context 塞满，模型开始胡说。现有工具没有上下文管理，用着用着就废了。 -**第二道：小模型能力墙** +> KWCode 解法：**纯算法上下文压缩**（头尾保留 + 中间关键词提取，<10ms），自动在 context 快满时压缩历史对话。你能一直聊下去，不会突然变傻。 -本地部署开源模型是解法。DeepSeek、Qwen3、GLM 都能在自己电脑上跑。但这些 8B、14B 的模型在复杂任务上失误率高——所有主流 coding agent 框架都是为强模型设计的，把整个任务丢给一个 LLM 硬扛，强模型能扛，小模型就垮了。 +**痛点二：错误重复回复** -**第三道：代码定位墙** +小模型修 bug 失败后，用同样的方式再试一遍，三次机会全浪费在同一个错误上。 -现有工具找 bug 的方式是把文件列表丢给 LLM，让它猜哪个文件相关。对强模型勉强可以，对小模型是灾难。猜错文件，后面全错。 +> KWCode 解法：**三阶段重试策略**——第一次正常描述，第二次从错误信息出发，第三次最小化修改。每次重试前先做 Reflection（LLM 一句话分析上次为什么失败），绝不重复同样的错。失败模式还会记录到 PATTERN.md，下次遇到类似任务直接提高风险等级。 -**KWCode 为这三个问题，逐一给出工程解法。** +**痛点三：不能调用工具** + +大部分本地 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。沿调用链追踪隐藏依赖，不靠猜。 --- @@ -47,10 +63,10 @@ Claude Code、Cursor、GitHub Copilot 把你的代码发到海外服务器。公 ``` 用户输入 └─► Gate 任务分类，毫秒级路由 - └─► Locator 精准定位文件和函数 - └─► Generator 只生成修改部分 - └─► Verifier 语法 + pytest 验证 - └─► SearchAugmentor 失败时自动搜索 + └─► Locator 精准定位文件和函数（BM25+调用图，不调LLM） + └─► Generator 只生成修改部分（从文件读original，LLM只写modified） + └─► Verifier 语法检查 + pytest 自动验证 + └─► SearchAugmentor 失败时自动搜索补充信息 ``` 小模型只需要在极小的 context 里做一件明确的事。失误可以被及时发现和纠正，不会滚雪球。 diff --git a/README_zh.md b/README_zh.md index f3f27d6..9cd81fe 100644 --- a/README_zh.md +++ b/README_zh.md @@ -18,21 +18,37 @@ ## 为什么做这个 -### 中国开发者用 AI Coding 工具，有三道绕不开的墙 +### 本地模型跑 Coding Agent，有五个核心痛点 -**第一道：数据安全墙** +**痛点一：上下文爆炸** -Claude Code、Cursor、GitHub Copilot 把你的代码发到海外服务器。公司代码、内网项目、涉密工程，这条路根本走不通。国内访问这些工具本来就不稳定，一个任务跑到一半断连，体验极差。 +小模型窗口只有 8K-32K。对话几轮后 context 塞满，模型开始胡说。现有工具没有上下文管理，用着用着就废了。 -**第二道：小模型能力墙** +> KWCode 解法：**纯算法上下文压缩**（头尾保留 + 中间关键词提取，<10ms），自动在 context 快满时压缩历史对话。你能一直聊下去，不会突然变傻。 -本地部署开源模型是解法。DeepSeek、Qwen3、GLM 都能在自己电脑上跑。但这些 8B、14B 的模型在复杂任务上失误率高——所有主流 coding agent 框架都是为强模型设计的，把整个任务丢给一个 LLM 硬扛，强模型能扛，小模型就垮了。 +**痛点二：错误重复回复** -**第三道：代码定位墙** +小模型修 bug 失败后，用同样的方式再试一遍，三次机会全浪费在同一个错误上。 -现有工具找 bug 的方式是把文件列表丢给 LLM，让它猜哪个文件相关。对强模型勉强可以，对小模型是灾难。猜错文件，后面全错。 +> KWCode 解法：**三阶段重试策略**——第一次正常描述，第二次从错误信息出发，第三次最小化修改。每次重试前先做 Reflection（LLM 一句话分析上次为什么失败），绝不重复同样的错。失败模式还会记录到 PATTERN.md，下次遇到类似任务直接提高风险等级。 -**KWCode 为这三个问题，逐一给出工程解法。** +**痛点三：不能调用工具** + +大部分本地 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。沿调用链追踪隐藏依赖，不靠猜。 --- @@ -47,10 +63,10 @@ Claude Code、Cursor、GitHub Copilot 把你的代码发到海外服务器。公 ``` 用户输入 └─► Gate 任务分类，毫秒级路由 - └─► Locator 精准定位文件和函数 - └─► Generator 只生成修改部分 - └─► Verifier 语法 + pytest 验证 - └─► SearchAugmentor 失败时自动搜索 + └─► Locator 精准定位文件和函数（BM25+调用图，不调LLM） + └─► Generator 只生成修改部分（从文件读original，LLM只写modified） + └─► Verifier 语法检查 + pytest 自动验证 + └─► SearchAugmentor 失败时自动搜索补充信息 ``` 小模型只需要在极小的 context 里做一件明确的事。失误可以被及时发现和纠正，不会滚雪球。