docs: rewrite pain points section — context overflow, retry loops, tool execution

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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 里做一件明确的事。失误可以被及时发现和纠正，不会滚雪球。

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 里做一件明确的事。失误可以被及时发现和纠正，不会滚雪球。