codev / docs /architecture /design-philosophy.md

chenbhao

chore: rename VersperClaw to Codev, update org to chenbhao

96f34e3 about 1 month ago

preview code

Raw

History Blame Contribute Delete

19.1 kB

设计哲学与架构原则

本文档综合自 Dive into Claude Code (arXiv:2604.14228v1) 的架构分析以及 Codev 源代码的实际实现模式，旨在为面试准备和系统设计讨论提供参考。

Claude Code 的设计哲学源于五个核心人类价值，通过十三条设计原则转化为具体的架构决策。 Codev 在此基础上进行了多 Provider 和 Friend VRM 等扩展。

1. 五大核心价值 (Core Values)

Claude Code 的系统架构由五个根本性的人类价值驱动。这些价值不是事后总结，而是在架构设计之初就被确立为优先级排序的依据。

1.1 人类决策权威 (Human Decision Authority)

人类保留对所有系统行为的最终决定权。这一价值通过 主体层级结构 (principal hierarchy) 来实现：Anthropic（作为模型开发者）→ operators（组织管理员）→ users（终端用户）。

架构含义：

人类可以实时观察系统行为、批准或拒绝提议的操作、中断进行中的操作、并在事后审计所有操作记录。
当 Anthropic 发现用户批准 93% 的权限提示时，他们的反应不是增加更多警告，而是重新构建问题：通过在明确定义的边界（沙箱、auto-mode 分类器）内让代理自由工作，而非依赖用户逐操作审批（因为一旦习惯化，用户就会不加审查地批准）。
对应源文件：src/utils/permissions/permissions.ts、src/utils/permissions/PermissionMode.ts

1.2 安全、安全与隐私 (Safety, Security, and Privacy)

系统有义务保护人类、代码、数据和基础设施，即使人类疏忽或犯错。这与人类决策权威有本质区别：权威是关于人类的选择权，而安全是关于系统的保护义务。

架构含义：

威胁模型涵盖四种风险：过度热心行为、诚实错误、提示注入和模型失准。
实现为多层重叠安全机制（拒绝优先、分类器、沙箱、钩子），任何一层都能独立阻止危险操作。
对应源文件：src/utils/permissions/yoloClassifier.ts、src/tools/BashTool/shouldUseSandbox.ts

1.3 可靠执行 (Reliable Execution)

代理正确执行用户的实际意图，在长时间内保持一致性，并支持在执行完成前验证工作。

架构含义：

涵盖单轮正确性和长周期可靠性（跨上下文窗口边界、会话恢复、多代理委派）。
实现了 5 层压缩管道、优雅恢复机制（max_output_tokens 升级重试、auto-compact、 reactive compact）和自动断路器。
对应源文件：src/query.ts（queryLoop）、src/services/compact/autoCompact.ts

1.4 能力放大 (Capability Amplification)

系统显著提升开发者单位时间/成本的产出效率。Anthropic 内部调查显示约 27% 的任务属于 "如果没有工具就不会尝试的工作"——架构使全新的工作流成为可能，而不仅仅是加速现有流程。

架构含义：

系统的创造者将其描述为 "Unix 工具而非传统产品"——由最小、有用、可理解和可扩展的构建块组成。
投资于确定性基础设施（上下文管理、工具路由、恢复机制）而非决策框架（显式规划器或状态图），前提是日益强大的模型更受益于丰富的操作环境而非约束性框架。
对应源文件：src/tools/tools.ts（assembleToolPool）、src/query.ts（~88 行主循环）

1.5 上下文适应性 (Contextual Adaptability)

系统适配用户的特定上下文（项目、工具、约定、技能水平），并且关系随时间改善。

架构含义：

扩展架构（CLAUDE.md、skills、MCP、hooks、plugins）提供多层级可配置性，每层具有不同的上下文成本。
纵向数据显示人机关系是演化的：自动批准率从 <50 会话的 ~20% 增长到 750+ 会话的

40%。信任是"由模型、用户和产品共同构建的"。
对应源文件：src/context.ts、src/services/mcp/、src/utils/hooks/

2. 十三条设计原则 (Design Principles)

五大价值通过十三条设计原则可操作化。每条原则回答一个生产级编码代理必须解决的重复性问题。下表总结了每条原则、其服务的价值、设计问题以及关键实现文件。

#	原则	服务价值	设计问题	关键实现
1	拒绝优先，人类升级 (Deny-first with human escalation)	Authority, Safety	未识别的操作应被允许、阻止还是升级给人类？	`permissions.ts` (deny 规则优先于 allow 规则)
2	渐进信任光谱 (Graduated trust spectrum)	Authority, Adaptability	固定权限层级还是随时间演进的光谱？	`PermissionMode.ts` (7 个模式: plan → default → acceptEdits → auto → dontAsk → bypassPermissions → bubble)
3	深度防御，分层机制 (Defense in depth with layered mechanisms)	Safety, Authority, Reliability	单一安全边界还是多个重叠的？	7 层独立机制 (pre-filter + deny-first + modes + classifier + sandbox + no-restore + hooks)
4	外化可编程策略 (Externalized programmable policy)	Safety, Authority, Adaptability	硬编码策略还是外化配置？	`CLAUDE.md` 层级, `hooks` 生命周期, `PermissionRule`
5	上下文作为稀缺资源，渐进管理 (Context as scarce resource with progressive management)	Reliability, Capability	绑定资源约束是什么？如何分级管理？	5 层压缩管道 (budget → snip → microcompact → collapse → auto-compact), `query.ts:365-453`
6	追加式持久状态 (Append-only durable state)	Reliability, Authority	可变状态、快照还是追加日志？	JSONL 会话转录 (`sessionStorage.ts`), 侧链文件
7	最小脚手架，最大操作平台 (Minimal scaffolding, maximal operational harness)	Capability, Reliability	投资于推理侧框架还是操作基础设施？	~88 行 queryLoop; ~98.4% 的代码为确定性基础设施
8	价值观优于规则 (Values over rules)	Capability, Authority	僵化的决策程序还是上下文的判断？	系统提示设计基于原则而非穷举规则
9	可组合的多机制扩展 (Composable multi-mechanism extensibility)	Capability, Adaptability	统一扩展 API 还是分层机制？	MCP + Plugins + Skills + Hooks 四种机制，上下文成本递增
10	可逆性加权风险评估 (Reversibility-weighted risk assessment)	Capability, Safety	所有操作相同监督还是更轻的只读/可逆操作？	read-only 工具并行执行, 写操作串行化
11	透明的基于文件的配置与记忆 (Transparent file-based configuration and memory)	Adaptability, Authority	不透明数据库、嵌入检索还是用户可见的文件？	`CLAUDE.md` 层级, auto-memory 文件, git 版本可控
12	隔离的子代理边界 (Isolated subagent boundaries)	Reliability, Safety, Capability	子代理共享父上下文还是隔离运行？	`AgentTool.tsx`, `runAgent.ts`, 侧链转录, 独立上下文窗口
13	优雅恢复与韧性 (Graceful recovery and resilience)	Reliability, Capability	错误时硬失败还是静默恢复？	max_output_tokens 升级 (3次)、reactive compact、fallback model、断路器

2.1 原则的可选设计家族

这些原则可以通过对比三种主流替代设计家族来理解：

基于规则的编排：LangGraph 等框架将决策逻辑编码为显式状态图（typed edges），选择脚手架而非最小平台。
容器隔离执行：SWE-Agent 和 OpenHands 依赖 Docker 隔离而非分层策略执行。
版本控制即安全：Aider 使用 Git 回滚作为主要安全机制而非拒绝优先评估。

Claude Code 的原则组合的独特之处在于：最小决策脚手架 + 分层策略执行 + 基于价值观的判断 + 拒绝优先默认 + 渐进上下文管理 + 可组合扩展。

2.2 值-原则-架构映射

每条价值通过其原则追踪到特定的架构决策：

价值	驱动的原则	架构体现
人类决策权威	拒绝优先、渐进信任、追加状态、外部化策略、价值观优于规则	权限系统、审计日志、CLAUDE.md
安全与隐私	深度防御、拒绝优先、可逆性加权、外部化策略、隔离子代理	7 层安全、沙箱、分类器
可靠执行	稀缺上下文、追加状态、优雅恢复、隔离子代理、深度防御	压缩管道、JSONL 转录、断路器
能力放大	最小脚手架、可组合扩展、可逆性加权、上下文管理、优雅恢复	queryLoop、MCP、speculative 执行
上下文适应性	透明文件记忆、可组合扩展、渐进信任、外部化策略	CLAUDE.md 层级、skills、hooks

3. 架构权衡 (Architectural Trade-offs)

3.1 安全 vs 自主权 (Safety vs. Autonomy)

系统中最核心的张力：更高的自主权意味着更少的人类干预，但也意味着更大的风险。

Claude Code 的选择：通过渐进信任光谱来管理这种张力。用户从 plan 或 default 模式开始，随着时间向 acceptEdits → auto → bypassPermissions 演进。
权衡的体现：当命令超过 50 个子命令时，权限系统退回到通用审批提示而非逐子命令检查，因为逐子命令解析会导致 UI 冻结。这是安全与性能之间结构性张力的实例。
相关代码：src/utils/permissions/getNextPermissionMode.ts、 src/utils/permissions/PermissionMode.ts

3.2 上下文效率 vs 透明度 (Context Efficiency vs. Transparency)

压缩节省上下文但降低人类可读性。

Claude Code 的选择：5 层压缩管道，从轻量级（budget reduction、snip）到重量级（auto-compact），每层在成本和效果之间做出不同权衡。
权衡的体现：auto-compact 使用模型生成摘要来替代原始对话，但摘要丢失了原始细节。上下文折叠 (context collapse) 作为只读投影避免了这个问题，但增加了实现复杂度。追加式 JSONL 日志虽然保留完整可审计历史，但在恢复时不还原权限状态，牺牲了便利性以换取安全性。
相关代码：src/services/compact/（整个目录）、src/utils/sessionStorage.ts

3.3 简单 vs 可扩展 (Simplicity vs. Extensibility)

核心循环应该简单，但系统需要适应各种用例。

Claude Code 的选择：queryLoop() 是 ~~88 行的 while-true 循环。~~98.4% 的代码存在于周围的子系统中：安全、扩展、上下文管理、委派和持久化。
权衡的体现：为什么有四种扩展机制（MCP、plugins、skills、hooks）而不是一种？因为每种机制服务于不同的抽象级别和上下文成本。MCP 提供外部工具集成，plugins 打包组件，skills 注入领域指令，hooks 拦截生命周期。这种分层增加了概念复杂性，但允许在不同场景下使用适当的工具。
相关代码：src/query.ts、src/services/mcp/、src/plugins/、src/skills/、 src/utils/hooks/

3.4 对抗条件下的权限模型 (Permission Model Under Adversarial Conditions)

当用户（或劫持用户的提示注入）主动尝试规避安全措施时。

Claude Code 的应对：拒绝优先 + 深度防御的组合否认了单点失效。即使一个安全层被绕过（例如用户批准了恶意命令），其他层（沙箱、分类器、钩子）仍然可以拦截。
关键弱点：共享实现约束导致安全层之间存在共性失效模式。例如，权限系统和 UI 渲染共享主线程，当规则评估导致 UI 冻结时，两者同时失效。
相关代码：src/utils/permissions/permissions.ts、 src/utils/permissions/yoloClassifier.ts

4. Codev 与 Claude Code 的差异

Codev 以 Claude Code 为上游基础，进行了以下主要变更和扩展：

4.1 多 Provider 支持

Claude Code 内置仅支持 Anthropic API，而 Codev 通过 Provider 代理架构支持 OpenAI、Groq、DeepSeek 以及所有兼容 OpenAI 的 API。
实现模式：src/server/proxy/handler.ts 实现双路由决策——
- 1P Anthropic 路径：直接调用 Anthropic SDK
- 3P Provider 路径：通过协议转换器（anthropicToOpenaiChat.ts → upstream API → openaiChatToAnthropic.ts）
架构影响：代理层引入额外的延迟和错误处理复杂度，但使得系统不受单一供应商限制。

4.2 Friend VRM 系统

同进程 VRM 伴侣服务，使用 3D 虚拟角色（VRM 格式）作为交互界面。
实现模式：src/friend/FriendService.ts 是单例服务，与 React 组件通过 subscribe() / subscribeToInbound() 模式同步。使用 SSE 广播将表情/TTS 推送到 VRM 前端。
关键组件：
- Silero VAD：WASM 推理（src/friend/voice/vad-service.ts），通过 onnxruntime-web 实现机器学习级语音活动检测
- 进程内音频捕获：cpal Rust 库（替代传统的 arecord/parecord 子进程）
- TTS 引擎：Edge TTS（默认）和 Qwen TTS（DashScope API）
架构意义：展示了如何将 Claude Code 的扩展机制（钩子 + 工具）用于非开发场景，将编码代理转变为通用对话代理。

4.3 移除 ant-internal 模块

移除了 Anthropic 内部使用的模块（feature flags、内部 API），使代码对社区完全可用。
src/query/transitions.ts 等文件使用代理桩 (proxy stub) 替代缺少的内部模块，通过 bun:bundle 的 DCE 在构建时消除。

4.4 社区贡献

onnxruntime-web WASM VAD：首个在生产级 CLI 工具中集成基于 ML 的语音活动检测。
同进程 Friend 服务：无需独立后台服务器子进程，简化了部署架构。

5. 关键架构模式 (Key Architecture Patterns)

5.1 单一主循环模式 (Single Main Loop)

实现：queryLoop() 是 src/query.ts 中的 AsyncGenerator，约 88 行核心控制逻辑（while-true），周围 ~98.4% 的代码是确定性基础设施。

循环结构（简化的伪代码）：

while (true) {
  1. 解构状态 (destructure state)
  2. 压缩管道 (5 shapers: budget → snip → microcompact → collapse → auto-compact)
  3. 调用模型 (for await over deps.callModel)
  4. 工具派发 (StreamingToolExecutor 或 runTools)
  5. 收集结果 → 更新状态 → 继续或终止
}

架构意义：

生成器模式实现了流式输出，同时保持单一同步控制流。
七个"继续点"（continue sites）各自通过一次整体对象赋值（而不是逐个字段变更）来更新状态，保持了不变性的简单性。
所有入口（交互式 CLI、headless CLI、SDK、IDE 集成）汇聚到同一个 queryLoop，只有 UI/渲染层不同。

5.2 追加日志模式 (Append-Only Log Pattern)

实现：src/utils/sessionStorage.ts 将会话转录存储为 JSONL 文件（每行一个 JSON 事件）。

核心选择：

状态变更使用追加写入而非原地修改
子代理对话存储在单独的侧链文件中（sessionStorage.ts:247），避免膨胀父上下文
恢复/复刻操作从事务重建会话状态（conversationRecovery.ts）

架构意义：

写前日志 (Write-Ahead Log) 风格使得审计、调试和恢复成为一等公民。
但不在恢复时还原会话级权限——这是一个有意的设计选择，牺牲便利以换取安全（防止权限状态被意外恢复）。

5.3 分层安全模式 (Layered Security Pattern)

实现：7 层独立安全机制：

层	机制	源文件	作用时机
1	工具预过滤	`tools.ts` (filterToolsByDenyRules)	模型调用前
2	拒绝优先规则	`permissions.ts` (toolMatchesRule)	工具派发时
3	权限模式约束	`PermissionMode.ts`	模式切换时
4	Auto-mode 分类器	`yoloClassifier.ts`	auto 模式下
5	Shell 沙箱	`shouldUseSandbox.ts`	Bash 执行前
6	恢复时不恢复权限	`conversationRecovery.ts`	会话恢复时
7	Hook 拦截	`types/hooks.ts`	工具生命周期各点

架构意义：

任何单层都不能完全信任——深度防御假设每层都可能失效，但多层同时失效的概率降低。
层之间共享实现约束（例如，超过 50 个子命令的命令退回到通用审批，因为逐子命令解析导致 UI 冻结）。

5.4 渐进式上下文管理 (Progressive Context Management)

实现：5 层压缩管道，每层有不同成本效益比：

Budget Reduction (工具结果大小限制)
  → Snip (轻量级历史修剪)
    → Microcompact (细粒度缓存感知压缩)
      → Context Collapse (只读投影，不改变存储)
        → Auto-compact (模型生成的语义摘要，最后手段)

决策顺序：更早、更轻量的层先运行。只有当前置层不足以将上下文降到阈值以下时，才触发更重的层。

架构意义：

没有单一压缩策略能应对所有类型的上下文压力。
Budget 针对单个工具输出溢出；Snip 处理时间深度；Microcompact 应对缓存开销； Context Collapse 管理超长历史；Auto-compact 执行语义压缩。
同样的稀缺性思维体现在其他子系统：CLAUDE.md 懒加载、延迟工具模式、子代理仅返回摘要。

5.5 流式工具执行 (Streaming Tool Execution)

实现：src/services/tools/StreamingToolExecutor.ts

工具在模型流式响应时就开始执行（不是等待完整响应）
只读操作可以并行执行；写操作（如 Bash 命令）串行化
兄弟终止控制器：当任何 Bash 工具出错时立即终止其他进行中的子进程
结果按工具发出顺序缓冲和发射，即使并行执行也保持顺序一致性

架构意义：

介于完全串行派发和激进推测执行（如 PASTE）之间的中间方案
在延迟降低和实现简单性之间取得平衡

6. 延伸阅读

Dive into Claude Code (arXiv:2604.14228v1): 对本文档所基于的原始架构分析论文
Anthropic Safe Agents Framework: 安全代理设计的原则文档
Claude Code 官方文档: https://code.claude.com/docs/
Codev 源代码: /home/yuki/Code/Agent/Codev/src/
- 核心循环: src/query.ts
- 权限系统: src/utils/permissions/
- 压缩管道: src/services/compact/
- 扩展机制: src/services/mcp/, src/utils/hooks/
- 状态持久化: src/utils/sessionStorage.ts
- 多 Provider: src/server/proxy/
- Friend VRM: src/friend/

文档版本: v1.0 — 2026-06-22 作者: 基于 Claude Code 设计哲学论文和 Codev 源代码综合分析

设计哲学与架构原则

1. 五大核心价值 (Core Values)

1.1 人类决策权威 (Human Decision Authority)

1.2 安全、安全与隐私 (Safety, Security, and Privacy)

1.3 可靠执行 (Reliable Execution)

1.4 能力放大 (Capability Amplification)

1.5 上下文适应性 (Contextual Adaptability)

2. 十三条设计原则 (Design Principles)

2.1 原则的可选设计家族

2.2 值-原则-架构 映射

3. 架构权衡 (Architectural Trade-offs)

3.1 安全 vs 自主权 (Safety vs. Autonomy)

3.2 上下文效率 vs 透明度 (Context Efficiency vs. Transparency)

3.3 简单 vs 可扩展 (Simplicity vs. Extensibility)

3.4 对抗条件下的权限模型 (Permission Model Under Adversarial Conditions)

4. Codev 与 Claude Code 的差异

4.1 多 Provider 支持

4.2 Friend VRM 系统

4.3 移除 ant-internal 模块

4.4 社区贡献

5. 关键架构模式 (Key Architecture Patterns)

5.1 单一主循环模式 (Single Main Loop)

5.2 追加日志模式 (Append-Only Log Pattern)

5.3 分层安全模式 (Layered Security Pattern)

5.4 渐进式上下文管理 (Progressive Context Management)

5.5 流式工具执行 (Streaming Tool Execution)

6. 延伸阅读

2.2 值-原则-架构映射