feat: add architecture.md

Author: qorzj

README-en.md

@@ -98,6 +98,14 @@ Skills are discovered from these locations, in priority order:
 - `deepseek-v4-flash`
 - Any other OpenAI-compatible model
 
+## Architecture and Benchmarks
+
+In ["Better Models: Worse Tools"](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/), Armin Ronacher argues that tool schemas are not "neutral": models (LLMs) inherit tool-use habits formed during training and reinforcement learning, so they may perform well in one mainstream harness but become unstable with a different tool shape. This is the architectural starting point for Deep Code: it is tuned specifically for DeepSeek, so the harness itself can stay aligned with DeepSeek's behavior.
+
+Deep Code's gains come from the combined effect of tool constraints, context management, Agent Skills, permission policy, and other architectural decisions. The [deepcode-qrcode-benchmark](https://github.com/qorzj/deepcode-qrcode-benchmark) project shows that on a real and challenging Python requirement, Deep Code + DeepSeek + `/plan` mode has an effectiveness advantage over Claude Code + DeepSeek.
+
+> See also: [Deep Code Architecture](docs/architecture_en.md)
+
 ## FAQ
 
 ### Does Deep Code have a VSCode extension?

README-zh_CN.md

@@ -97,6 +97,13 @@ Skills 会按以下优先级扫描：
 - `deepseek-v4-flash`
 - 任何其他 OpenAI 兼容模型
 
+## 架构和基准测试
+
+Armin Ronacher 在[《更好的模型，更糟的工具》](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/)中指出，工具 schema 不是「中立的」：模型（LLM）会继承训练和强化学习中形成的工具使用习惯，因此可能在某个主流 harness 中表现很好，却在另一套工具形态下变得不稳定。这正是 Deep Code 的架构出发点：只为 DeepSeek 量身调优，从而让 harness 本身持续贴合 DeepSeek 的行为特点。
+
+Deep Code 的收益来自于工具约束、上下文管理、Agent Skills 和权限策略等多项设计叠加后的结果。[deepcode-qrcode-benchmark](https://github.com/qorzj/deepcode-qrcode-benchmark) 项目展示了在一个真实且有难度的 Python 需求上，Deep Code + DeepSeek + `/plan` 模式相较 Claude Code + DeepSeek 的组合具有效果优势。
+
+> 详见：[Deep Code 架构](docs/architecture.md)
 
 ## 常见问题
 

README.md

@@ -97,6 +97,13 @@ Skills 会按以下优先级扫描：
 - `deepseek-v4-flash`
 - 任何其他 OpenAI 兼容模型
 
+## 架构和基准测试
+
+Armin Ronacher 在[《更好的模型，更糟的工具》](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/)中指出，工具 schema 不是「中立的」：模型（LLM）会继承训练和强化学习中形成的工具使用习惯，因此可能在某个主流 harness 中表现很好，却在另一套工具形态下变得不稳定。这正是 Deep Code 的架构出发点：只为 DeepSeek 量身调优，从而让 harness 本身持续贴合 DeepSeek 的行为特点。
+
+Deep Code 的收益来自于工具约束、上下文管理、Agent Skills 和权限策略等多项设计叠加后的结果。[deepcode-qrcode-benchmark](https://github.com/qorzj/deepcode-qrcode-benchmark) 项目展示了在一个真实且有难度的 Python 需求上，Deep Code + DeepSeek + `/plan` 模式相较 Claude Code + DeepSeek 的组合具有效果优势。
+
+> 详见：[Deep Code 架构](docs/architecture.md)
 
 ## 常见问题
 

docs/architecture.md

@@ -0,0 +1,49 @@
+# Deep Code 架构：围绕DeepSeek模型构建的harness
+
+Coding Agent的质量不是由模型单独决定的，而是模型(LLM)与其执行框架(harness)共同构成的系统决定的。
+
+Deep Code的终极目标：在智能编码任务上，Deep Code 应当以比“Claude Code + DeepSeek”这套组合更低的成本，取得更好的效果。实现路径不是幻想用一个通用框架让所有模型都表现最佳，而是不断将框架适配最新的 DeepSeek 模型，让模型看到的工具形态、上下文布局、安全规则和恢复路径，都契合它实际的行为方式。
+
+## 这个目标为什么可行
+
+Armin Ronacher 的文章[《更好的模型，更糟的工具》](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/)指出了一个值得重视的事实：工具 schema 并非「中立」。模型不会把工具模式当作纯粹的抽象约定来遵守，而是带着训练和强化学习过程中形成的使用习惯去接触它。如果某个厂商主要针对一种主流框架训练模型，那么模型可能会非常擅长那个框架的工具生态，却在面对形态不同的工具时意外地不可靠。能力更强的模型可能形成更强的习惯，而更强的习惯会让它更排斥陌生的工具。
+
+这一观察正是 Deep Code 设计的核心依据。Claude Code 是一个为 Anthropic 模型优化的闭源框架，没有理由把 DeepSeek 当作头等对象来对待。而 Deep Code 的选择则是成为 DeepSeek 生态的一部分，它应该为 DeepSeek 量身调优，而不仅仅是“兼容”。
+
+## 核心设计一：通过 snippet 修复工具调用
+
+传统编辑工具往往要求模型提供文件路径以及大段的 `old_string` 和 `new_string`。这看起来直接，但在真实应用场景中，会有多种典型失败：模型可能编辑过时了的文件视图，匹配到错误的重复块，错误地带上行号，丢失缩进，过度替换，或者生成转义错误的 JSON。结果要么是工具调用失败，要么更糟，甚至产生一个看上去合理、实际错误的文件改动。
+
+Deep Code 给出的方案是片段(snippet)系统。`read` 工具除了返回文件内容，还会在文本文件上维护一个会话本地的文件状态，并在元数据中返回 `snippet_id`。`edit` 工具随后将这个 `snippet_id` 作为必填参数。片段携带了文件路径、行范围、预览、版本和范围类型信息。
+
+这重塑了编辑的约定：文件必须先被读过才能编辑，片段必须在当前会话中，文件自读取后未被改动，替换只在片段范围内搜索，非唯一匹配会返回候选片段而不是直接猜测，批量替换可以要求声明预期出现次数。
+
+这是一种理解模型行为、而非放任模型的修复策略。它不强求模型在压力下保持完美，而是让正确操作更容易表达，同时让框架掌握足以发现歧义的局部信息。在接口校验上它保持严格，但在编码智能体常见的、可恢复的文本错误上又给予宽容，使智能体在意图清晰时可以继续向前推进。
+
+内置工具有意保持少而精：`bash`、`read`、`write`、`edit`、`AskUserQuestion`、`UpdatePlan` 和 `WebSearch`，外部 MCP 工具则动态挂载。这是一个刻意的设计决定，它降低了模式的不确定性，让权限分析变得可行，也给了模型一套可预期、可重复的操作语言。
+
+## 核心设计二：缓存感知的上下文管理
+
+第二个核心设计是用上下文缓存控制成本。DeepSeek 的上下文缓存默认启用，当后续请求完全复用了已缓存的前缀单元，就能命中缓存，并在返回值中给出缓存命中与未命中的token数。这是一套尽力而为的系统，但它确实奖励那些稳定的重复前缀。
+
+Deep Code 的会话架构正是围绕这一特性设计的，而且不需要用户刻意配合。系统提示、工具文档、默认技能、运行时上下文和项目说明，这些稳定内容都被放在易变的用户内容之前。会话消息以 JSONL 持久化，并能被一致地重放。工具调用与工具结果的配对在转换时会被修复，包括中断的工具调用，以保证发回给模型的对话始终保持结构有效。
+
+## 核心设计三：以Agent Skills为核心的上下文工程
+
+一个编码智能体不该把所有的知识都塞进上下文里，那样会污染上下文、推高成本，还会削弱指令的优先级。与此同时，很多任务又确实需要可复用的知识：代码审查流程、领域约定、框架特定模式等等。Agent Skills就是在这些知识真正需要时，按需加载的机制。
+
+自动匹配同样借助了模型本身：系统将候选技能的名称和描述发给模型，由模型返回应匹配的技能。已加载的技能不会重复加载，技能也可以声明不参与隐式调用。这一设计让基础框架保持精干，同时又允许丰富的任务特定行为，也使得技能得以跨工具移植。
+
+更深层的架构含义是，技能并非传统意义上的插件，而是被结构化的上下文。它让框架来决定何时把指令、示例、模板、脚本和参考文件引入对话。对于泛化能力强但并非完美的模型来说，这恰恰是最合适的抽象：让默认环境保持干净，在真正能产生帮助的时刻，再注入精准的先验知识。
+
+## 核心设计四：基于副作用分类的权限系统
+
+智能编码必然伴随真实的副作用：读写文件、运行 Shell 命令、访问网络、调用外部工具。一个只提供“全自动模式”的框架不安全，事事弹窗询问又太慢。Deep Code 的创新是引入基于副作用分类的作用域策略。
+
+权限系统定义了具体的作用域，例如目录内外的读、写、删除，Git 日志的查询与修改，网络，MCP 等。`bash` 工具要求模型声明本次操作的副作用，文件工具则根据路径直接分类。
+
+这不仅仅是安全功能，它本身就是智能体质量的一部分。权限给模型提供了一个可预测的操作边界，低风险工作可以快速推进，高风险动作则会停下来。它也让命令行为变得可审查：一条命令不只是待执行的文本，而是文本、所声明的副作用以及策略决策的组合。
+
+## 基准测试
+
+Deep Code 的优势并非来自某个单点妙招，而是源自一系列决策的叠加效应。[deepcode-qrcode-benchmark](https://github.com/qorzj/deepcode-qrcode-benchmark)项目展示了在一个真实且有难度的Python需求上，Deep Code+DeepSeek+`/plan`模式的组合总是能够胜过Claude Code+DeepSeek的组合。

docs/architecture_en.md

@@ -0,0 +1,49 @@
+# Deep Code Architecture: A Harness Built Around the DeepSeek Model
+
+The quality of a Coding Agent is not determined by the model alone. It is determined by the system formed by the model (LLM) and its execution framework (harness).
+
+Deep Code's ultimate goal is this: on intelligent coding tasks, Deep Code should achieve better results than the "Claude Code + DeepSeek" combination, while costing less. The path to that goal is not to imagine that one generic framework can make every model perform at its best. Instead, it is to continuously adapt the framework to the latest DeepSeek models, so that the tool shapes, context layout, safety rules, and recovery paths seen by the model all match how it actually behaves.
+
+## Why This Goal Is Feasible
+
+Armin Ronacher's article ["Better Models: Worse Tools"](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/) points out an important fact: tool schemas are not "neutral." Models do not treat tool schemas as pure abstract contracts to follow. They approach them with usage habits formed during training and reinforcement learning. If a vendor primarily trains a model against one mainstream framework, the model may become very good at that framework's tool ecosystem, yet unexpectedly unreliable when facing tools with a different shape. A more capable model may form stronger habits, and stronger habits can make it more resistant to unfamiliar tools.
+
+This observation is the core basis for Deep Code's design. Claude Code is a closed-source framework optimized for Anthropic models, and it has no reason to treat DeepSeek as a first-class target. Deep Code makes a different choice: it becomes part of the DeepSeek ecosystem. It should be tuned specifically for DeepSeek, not merely be "compatible" with it.
+
+## Core Design 1: Repairing Tool Calls Through Snippets
+
+Traditional editing tools often require the model to provide a file path plus large `old_string` and `new_string` payloads. That looks straightforward, but in real-world scenarios it has many typical failure modes: the model may edit a stale view of a file, match the wrong repeated block, accidentally include line numbers, lose indentation, over-replace text, or generate JSON with incorrect escaping. The result is either a failed tool call or, worse, a plausible-looking but actually incorrect file change.
+
+Deep Code's solution is the snippet system. In addition to returning file contents, the `read` tool maintains session-local file state for text files and returns a `snippet_id` in metadata. The `edit` tool then requires this `snippet_id` as a mandatory parameter. A snippet carries the file path, line range, preview, version, and scope type.
+
+This reshapes the editing contract: a file must be read before it can be edited; the snippet must exist in the current session; the file must not have changed since it was read; replacement is searched only within the snippet's scope; non-unique matches return candidate snippets instead of guessing; and bulk replacement can require declaring the expected number of occurrences.
+
+This is a repair strategy that understands model behavior rather than indulging it. It does not require the model to stay perfect under pressure. Instead, it makes the correct operation easier to express while giving the framework enough local information to detect ambiguity. It remains strict at the interface validation layer, but is tolerant of common, recoverable text mistakes made by coding agents, allowing the agent to keep moving forward when the intent is clear.
+
+The built-in tools are intentionally small and focused: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, `UpdatePlan`, and `WebSearch`, while external MCP tools are mounted dynamically. This is a deliberate design decision. It reduces schema uncertainty, makes permission analysis feasible, and gives the model a predictable and repeatable action language.
+
+## Core Design 2: Cache-Aware Context Management
+
+The second core design is using context caching to control cost. DeepSeek's context cache is enabled by default. When a later request fully reuses a cached prefix unit, it can hit the cache, and the response reports the number of cache-hit and cache-miss tokens. This is a best-effort system, but it does reward stable repeated prefixes.
+
+Deep Code's session architecture is designed around this property, without requiring users to cooperate manually. Stable content such as the system prompt, tool documentation, default skills, runtime context, and project instructions is placed before volatile user content. Session messages are persisted as JSONL and can be replayed consistently. Tool-call and tool-result pairings are repaired during conversion, including interrupted tool calls, so the conversation sent back to the model always remains structurally valid.
+
+## Core Design 3: Context Engineering Centered on Agent Skills
+
+A coding agent should not stuff all knowledge into its context. Doing so pollutes the context, raises cost, and weakens instruction priority. At the same time, many tasks do require reusable knowledge: code review workflows, domain conventions, framework-specific patterns, and so on. Agent Skills are the mechanism for loading this knowledge on demand, exactly when it is needed.
+
+Automatic matching also uses the model itself: the system sends candidate skill names and descriptions to the model, and the model returns the skills that should match. Already-loaded skills are not loaded again, and skills can declare that they should not participate in implicit invocation. This design keeps the base framework lean while allowing rich task-specific behavior, and it also makes skills portable across tools.
+
+The deeper architectural meaning is that skills are not plugins in the traditional sense. They are structured context. They let the framework decide when to introduce instructions, examples, templates, scripts, and reference files into the conversation. For models with strong but imperfect generalization, this is exactly the right abstraction: keep the default environment clean, and inject precise prior knowledge only at the moment when it is truly helpful.
+
+## Core Design 4: A Permission System Based on Side-Effect Classification
+
+Intelligent coding inevitably involves real side effects: reading and writing files, running shell commands, accessing the network, and calling external tools. A framework that only provides a "fully automatic mode" is unsafe, while prompting for everything is too slow. Deep Code's innovation is to introduce a scope policy based on side-effect classification.
+
+The permission system defines concrete scopes, such as reading, writing, and deleting inside or outside the working directory; querying and mutating Git history; network access; MCP; and so on. The `bash` tool requires the model to declare the side effects of the current operation, while file tools are classified directly based on their paths.
+
+This is not merely a safety feature. It is itself part of agent quality. Permissions give the model a predictable operating boundary: low-risk work can proceed quickly, while high-risk actions stop for confirmation. It also makes command behavior auditable: a command is not just text waiting to be executed, but a combination of text, declared side effects, and a policy decision.
+
+## Benchmark
+
+Deep Code's advantage does not come from a single clever trick. It comes from the compounding effect of a series of decisions. The [deepcode-qrcode-benchmark](https://github.com/qorzj/deepcode-qrcode-benchmark) project shows that on a real and challenging Python requirement, the combination of Deep Code + DeepSeek + `/plan` mode can consistently outperform the combination of Claude Code + DeepSeek.