架构设计理念与核心哲学

.NET 生态系统提供原生 AI 编码智能体运行时

SharpClawCode 是一个专为 .NET 10 和 C# 13 生态系统设计的C# 原生编码智能体运行时（coding-agent ru与 Python 或 TypeScript 生态中大量涌现的 AI 编码助手不同，.NET 开发者长期以来缺乏一个真正意义上的原生、工程化的 AI 智能体基础设施。SharpClawCode 并非简单地将外部工具进行包装或移植，而是从头开始构建一个深度融入 .NET 技术栈的运行时环境，充分利用了 .NET 10 的最新特性，包括NativeAOT 编译支持、改进的异步编程模型、增强的依赖注入容器以及System.Text.Json的高性能序列化能力 。

该项目的核心目标用户群体具有明确的画像：希望获得 C# 编码智能体运行时而非拼凑临时脚本的开发团队；需要构建具有强机器可读输出的 AI 驱动 CLI 工具的开发者；以及需要 MCP（Model Context Protocol）集成、插件发现和权限感知工具执行的企业级产品。这种多维度的定位决定了其架构必须在灵活性、可扩展性和运营友好性之间取得精妙的平衡。项目描述中将其愿景概括为"think claude code meets opencode in C#"——即将 Claude Code 的强大交互能力与 OpenCode 的开放性相结合，并以 C# 的严谨性和性能优势重新实现 。

从技术生态位的角度审视，SharpClawCode 代表了 AI 开发工具从"脚本化"向"运行时化"的关键演进。早期的 AI 编码辅助多依赖于离散的工具调用或简单的 API 封装，开发者需要自行处理会话管理、状态持久化、权限控制和错误恢复等横切关注点。SharpClawCode 通过提供一个完整的运行时环境，将这些横切关注点内化为平台能力，使得开发者可以专注于业务逻辑的实现而非基础设施的搭建。这种转变类似于 Web 开发从 CGI 脚本向应用服务器的演进——前者每次请求都是独立的进程启动，后者则提供了持久的运行时上下文和丰富的中间件生态。

1.1.2 明确性、可测试性与运营可读性三大核心原则

SharpClawCode 的架构设计深受三大核心原则的指引：明确性（Explicitness）、可测试性（Testability）和运营可读性（Operational Legibility）。这三大原则不仅是设计理念的宣言，而是深度渗透到代码结构和运行时行为的每一个层面，形成了独特的工程文化。

明确性体现在所有关键操作都需要显式配置和授权，不存在隐式的"魔法"行为。工具注册采用IToolRegistry接口的显式注册模式，而非依赖反射或约定优于配置的发现机制；权限控制通过IPermissionPolicyEngine中明确定义的规则集进行判定，而非基于操作名称的字符串匹配；会话状态转换由显式的事件驱动，而非隐式的副作用。这种显式设计虽然增加了一定的配置负担，但极大地提升了系统的可预测性和调试友好性，使得开发者和运营人员能够准确地理解系统在任意时刻的行为状态 。

可测试性通过依赖注入、接口抽象和模块化设计得以实现。项目中的每一个核心组件都定义了清晰的接口契约，如ISessionStore、IModelProvider、IToolRegistry等，这些接口可以轻松地使用 mock 实现进行单元测试。项目还专门提供了SharpClaw.Code.MockProvider和SharpClaw.Code.ParityHarness等测试基础设施，支持确定性测试和端到端场景验证。DefaultTurnRunner的设计采用了纯函数式的核心逻辑与副作用分离的模式，将状态转换计算与状态持久化操作明确区分，使得核心的对话轮转逻辑可以在完全隔离的环境中进行单元测试 。

运营可读性反映了 SharpClawCode 对企业级部署场景的深刻理解。AI 编码智能体在生产环境中运行时，运营团队需要能够实时监控其状态、诊断问题和审计行为。为此，SharpClawCode 实现了结构化遥测系统，所有运行时事件都被规范化为结构化的事件对象，并通过IRuntimeEventPublisher发布到环形缓冲区。会话状态通过NDJSON 追加日志持久化，这种格式既人类可读又机器可解析。权限审批决策被记录并可以审计，工具执行的完整上下文都被保留。这些设计选择使得 SharpClawCode 不仅是一个开发工具，更是一个可以纳入标准 DevOps 实践的生产级系统 。

1.1.3 对比临时脚本方案的工程化优势

与开发者常用的临时脚本方案相比，SharpClawCode 提供了显著的工程化优势，这些优势在规模化部署和团队协作场景中尤为突出。

上表清晰地揭示了 SharpClawCode 在工程成熟度方面的全面领先。以会话管理为例，临时脚本通常是无状态的，每次执行都是独立的进程，无法维护跨调用的会话上下文，这使得多轮对话、增量代码修改和长期工作流难以实现。SharpClawCode 通过ConversationRuntime和持久会话存储解决了这一问题，会话状态可以在多次交互间保持，支持复杂的、有状态的编码工作流。在安全性方面，临时脚本往往缺乏系统性的权限控制，而 SharpClawCode 内置了完整的权限控制系统，包括IPermissionPolicyEngine规则引擎、IApprovalService批准服务，以及分级权限模式，所有权限决策都被记录到会话的审计日志中。这些工程化特性使得 SharpClawCode 成为构建企业级 AI 开发工具的理想选择，而非仅仅是个人效率工具 。

1.2 架构分层与模块化设计

1.2.1 协议层（SharpClaw.Code.Protocol）

1.2.1.1 DTOs、枚举、事件与命令结果定义

协议层作为 SharpClawCode 架构的最底层，承担着定义整个系统数据契约的核心职责。该层的设计遵循了"协议优先"的架构思想，即先定义清晰的数据契约，再在此基础上构建业务逻辑。SharpClaw.Code.Protocol项目包含了所有跨组件通信所需的 DTOs（数据传输对象）、枚举类型、事件定义和命令结果结构。这些 DTO 的设计注重不可变性和显式性，广泛采用 C# 9.0 引入的record类型，使得数据对象在创建后不可修改，通过with表达式生成变体，这天然地适合事件溯源模式中事件对象的不可变特性 。

事件定义是协议层的特别重要组成部分。SharpClawCode 采用事件溯源模式来记录会话状态变更，所有重大操作（如工具调用、权限审批、模型响应）都被建模为不可变事件。这些事件定义在协议层中，确保了从运行时到存储层再到遥测系统的全链路类型安全。命令结果结构则统一了各种操作的成功/失败表示，包括错误码、错误消息、重试建议等元数据，使得上层可以一致地处理操作结果。枚举类型涵盖了权限模式（readOnly、workspaceWrite、dangerFullAccess）、会话状态、提供者类型等关键领域概念，避免了魔法字符串的泛滥 。

1.2.1.2 JSON 源上下文与零 NuGet 依赖设计

协议层最显著的设计特征之一是其"零 NuGet 依赖"的声明。这一决策具有深远的架构影响：首先，它消除了版本冲突和供应链安全风险，上层模块无需担心协议层引入的依赖传递问题；其次，它使得协议层可以被最广泛地引用，包括那些对依赖有严格限制的环境；再次，它强制使用 .NET 原生能力而非第三方替代方案，确保了与 .NET 生态的深度集成和未来兼容性。

JSON 序列化通过ProtocolJsonContext实现，这是 .NET 的System.Text.Json源生成器（source generator）特性，能够在编译时生成序列化代码，避免了运行时的反射开销。这种手动管理 JSON 源上下文的方式虽然增加了维护负担——每次新增 DTO 类型都需要在序列化上下文中注册——但换取了显著的性能优势，特别是对于高频事件处理场景。源生成的序列化器具有与手写序列化代码相当的执行效率，同时支持 .NET 的NativeAOT 编译模式，这对于构建启动速度快、内存占用低的 CLI 工具和容器化服务至关重要 。

1.2.2 基础设施层（SharpClaw.Code.Infrastructure）

1.2.2.1 文件系统与路径抽象

基础设施层SharpClaw.Code.Infrastructure提供了运行时所依赖的所有底层服务抽象，其中文件系统与路径抽象是最核心的部分。在 AI 编码智能体的场景中，文件系统操作是最高频的操作之一——读取源代码、写入生成的文件、遍历项目目录、监控文件变更等。SharpClawCode 通过引入抽象接口（如IFileSystem或类似的抽象）将这些操作与具体实现解耦，为上层提供统一的接口。路径抽象特别关注了Windows 与 Unix 系统的路径分隔符差异、大小写敏感性差异以及特殊字符处理等问题，项目描述中明确提到了"deliberate attention to Windows-safe behavior"。

这种抽象带来了多重架构优势。在测试环境中，可以使用内存中的文件系统模拟替代真实的文件操作，使得测试更加快速、可靠且可重复。对于会话存储的测试，可以验证在各种文件系统异常（如权限不足、磁盘已满、文件被占用）下的行为，而无需实际制造这些条件。在容器化部署场景中，文件系统抽象使得 SharpClawCode 能够适应不同的存储后端，为将来支持非传统存储（如云存储、网络文件系统）预留了扩展点。这种设计遵循了"依赖倒置"原则，上层模块依赖于抽象接口而非具体实现，使得运行时可以根据部署环境灵活选择适配器 。

1.2.2.2 共享助手组件

基础设施层还包含了各类共享助手组件，这些组件为整个代码库提供了通用的功能支持。典型的共享助手包括：字符串处理工具（如路径拼接、命名规范化、代码块提取）、日期时间处理（统一的时间戳格式、时区处理）、加密辅助（API 密钥的安全存储、哈希计算）、HTTP 客户端工厂（统一的请求/响应处理、重试策略、超时配置）等。这些组件的设计遵循了单一职责原则和最小惊讶原则，每个助手类聚焦于一个明确的功能领域，API 设计直观且行为可预测 。

共享助手组件的集中管理避免了代码重复和实现分歧。例如，HTTP 调用的重试逻辑在全系统中保持一致，避免了不同模块因自定义实现而导致的行为差异。在 .NET 10 环境下，这些组件充分利用了Span<T>、Memory<T>等现代内存管理原语，减少了不必要的内存分配。字符串操作优先使用StringBuilder和ReadOnlySpan<char>，异步操作正确地使用了ValueTask和IAsyncEnumerable，在热路径上减少了对象分配。这些微观层面的优化累积起来，对高频操作（如事件序列化、工具输出处理）的性能有显著影响。基础设施层的助手组件虽然不像核心运行时那样引人注目，但它们是 SharpClawCode 能够同时实现高性能和高可维护性的重要基石 。

1.2.3 核心运行时层（SharpClaw.Code.Runtime）

1.2.3.1 ConversationRuntime 与会话状态机

核心运行时层SharpClaw.Code.Runtime是 SharpClawCode 的心脏，其中ConversationRuntime类承担着协调整个对话流程的核心职责。它实现了基于状态机（state machine）的会话管理模型，将会话生命周期划分为明确的状态：初始化、等待输入、工具执行中、等待审批、完成、错误等。这种状态机设计使得运行时能够精确控制每个状态下的允许操作和转换条件，避免了非法状态转换导致的未定义行为。例如，在"等待审批"状态下，只有批准或拒绝操作是合法的，工具执行被阻塞；在"工具执行中"状态下，新的用户输入被排队而非立即处理 。

会话状态机的实现充分考虑了持久化和恢复需求。每个状态转换都被记录为不可变事件，这些事件构成了会话的完整历史。在系统崩溃或重启后，可以通过重放这些事件精确恢复到之前的状态。ConversationRuntime与ISessionStore和IEventStore接口协作，将状态持久化细节委托给存储层，自身专注于状态转换逻辑。这种关注点分离使得存储实现可以独立演进，从简单的文件系统存储切换到数据库存储时，无需修改运行时核心逻辑。状态机的设计还考虑了扩展性，新的状态和转换可以通过插件机制添加，支持自定义的工作流编排 。

1.2.3.2 DefaultTurnRunner 与操作诊断依赖注入

DefaultTurnRunner是执行单次对话回合（turn）的核心组件，它负责协调从接收用户输入到生成响应的完整流程。一个典型的回合包括：解析输入、确定所需工具、执行权限检查、调用模型提供者、处理工具调用请求、执行工具、收集结果、生成最终响应。DefaultTurnRunner通过依赖注入获取所有必要的协作组件，包括IToolRegistry、IModelProvider、IPermissionPolicyEngine、ITelemetryService等，这种设计使得各个步骤可以独立测试和替换。例如，在测试中可以将IModelProvider替换为DeterministicMockModelProvider，以获得确定性的测试行为 。

操作诊断（operation diagnostics）是DefaultTurnRunner的重要功能，它通过System.DiagnosticsAPI 和自定义的遥测事件，记录每个回合的详细执行信息。这包括：各步骤的耗时分解、模型 API 调用的延迟和 token 消耗、工具执行的成功/失败统计、权限审批的决策记录等。这些诊断信息对于性能优化、故障排查和用量审计都至关重要。依赖注入容器（默认使用 .NET 的IServiceProvider）确保了诊断组件可以被透明地注入到所有需要的位置，而无需修改业务代码。这种横切关注点的处理方式是 .NET 生态中的最佳实践，使得运行时既保持了核心业务逻辑的清晰，又具备了企业级的可观测性。

1.2.4 嵌入宿主 SDK（SharpClaw.Code）

1.2.4.1 SharpClawRuntimeHostBuilder 与 SharpClawRuntimeHost

SharpClaw.Code项目作为可嵌入的宿主 SDK，提供了将 SharpClawCode 运行时集成到自定义应用程序中的完整基础设施。SharpClawRuntimeHostBuilder遵循了 .NET 中常见的构建器模式（Builder Pattern），允许开发者通过流畅的 API 配置和构建运行时宿主。配置选项涵盖了所有关键方面：模型提供者选择、权限模式设置、会话存储后端、遥测配置、插件加载、MCP 服务器注册等。这种构建器模式使得宿主配置既类型安全又具有自文档化特性，IDE 的智能提示可以引导开发者完成配置 。

SharpClawRuntimeHost则是构建完成的宿主实例，它管理运行时的生命周期，包括启动、运行、优雅关闭和资源释放。嵌入宿主 SDK 的设计使得 SharpClawCode 可以适应多种部署形态：对于简单的控制台应用，可以直接使用SharpClawRuntimeHostBuilder配置一个最小化运行时；对于 Web 应用，可以将宿主注册为IHostedService，与 ASP.NET Core 的生命周期管理集成；对于后台服务，可以使用WorkerServiceHost示例中展示的模式。SDK 提供了统一的IServiceCollection扩展方法，使得运行时服务可以方便地注册到现有的依赖注入容器中，避免了"框架入侵" 。

1.2.4.2 主机感知的运行时入口点设计

嵌入宿主 SDK 引入了"主机感知"（host-aware）的概念，这是区分独立 CLI 使用和嵌入式使用的关键机制。当 SharpClawCode 作为嵌入式服务运行时，它需要知道宿主应用程序的标识、租户上下文和运营需求。--host-id参数用于标识稳定的宿主实例，--tenant-id参数指定租户标识，这些标识被用于计量、事件信封和存储隔离。主机感知的运行时入口点会根据这些标识加载相应的配置、初始化隔离的存储空间，并在所有遥测事件中标注宿主和租户信息。这种设计使得单个 SharpClawCode 进程可以同时服务多个租户，而不会出现数据泄露或配置混淆 。

主机感知机制还影响了审批流程的行为。在嵌入式场景中，审批请求可以被路由到宿主应用程序的审批服务，而非在控制台中交互式提示。这使得 SharpClawCode 可以集成到企业的工作流系统中，审批决策可以由专门的审批引擎或人工通过 Web 界面做出。--storage-root参数允许宿主指定外部存储根目录，这对于容器化部署尤为重要，可以将持久化数据挂载到外部卷。--session-store参数支持在fileSystem和sqlite之间选择，宿主可以根据性能和可靠性需求做出选择。这些主机感知的入口点设计使得 SharpClawCode 能够从个人开发工具平滑过渡到企业级服务，而无需架构上的重大调整 。

1.3 关键架构模式

1.3.1 持久会话与事件溯源模式

持久会话（Durable Sessions）是 SharpClawCode 最具特色的架构模式之一，它将 AI 智能体的交互历史从易失的内存状态提升为持久化的、可查询的、可重放的资产。传统的聊天式 AI 工具通常将会话历史保存在内存中或简单的键值存储里，重启后丢失，且难以进行复杂的查询和分析。SharpClawCode 采用了事件溯源（Event Sourcing）模式，将会话的演变记录为不可变的事件序列，而非直接更新状态快照。每个事件代表会话中的一个重要事实：用户消息接收、模型响应生成、工具调用请求、工具执行结果、权限决策、错误发生等。事件以NDJSON（Newline Delimited JSON）格式追加写入事件存储，这种格式兼具人类可读性和机器处理效率 。

事件溯源模式带来了多重架构优势。首先是完整的审计能力，会话的完整历史被永久保留，任何时刻的状态都可以精确重建，这对于合规要求严格的行业（金融、医疗、政府）至关重要。其次是强大的查询能力，事件流可以被投影到不同的读模型中，支持多样化的查询需求——按时间范围查询、按事件类型过滤、按工具使用统计、按错误模式分析等。第三是并发处理能力，事件追加写入天然适合乐观并发控制，多个客户端可以同时向同一会话追加事件，通过版本号检测冲突。第四是模式演进灵活性，事件模式可以独立演进，旧事件通过上投影（Up-projection）转换为新格式，无需迁移历史数据。

快照机制（Snapshot）则解决了事件日志过长时的恢复性能问题。系统定期（或在特定触发条件下）将会话的当前状态持久化为快照文件，恢复时只需加载最新快照并重放此后的增量事件，将恢复时间从 O(n) 降低到 O(1)（快照加载）+ O(增量事件数)。快照格式采用压缩的二进制序列化，减少存储空间和加载时间。这种"快照 + 增量事件"的混合模式，使得 SharpClawCode 能够在保持完整历史的同时，实现高效的日常操作性能 。

1.3.2 权限感知的工具执行管道

权限感知（Permission-Aware）是 SharpClawCode 安全架构的核心原则，所有工具执行都必须通过权限检查管道。该管道由IPermissionPolicyEngine接口定义，它根据当前权限模式、操作类型、目标资源和用户历史决策，做出允许、拒绝或需要审批的判定。权限模式分为三级：readOnly（只读，禁止任何修改操作）、workspaceWrite（允许在工作区内写入，但禁止危险操作）、dangerFullAccess（完全访问，但仍需审批特别危险的操作）。这种分级设计使得用户可以根据任务性质选择合适的权限级别，在日常编码中使用较严格的模式，在明确需要时临时提升权限 。

审批流程（Approval Flow）是权限管道的关键组成部分。当操作需要审批时，系统会生成审批请求，包含操作的完整上下文（工具名称、参数、影响范围、风险等级）。在交互式模式下，用户会收到清晰的提示并可以做出批准/拒绝/修改的决定；在自动化模式下，审批可以被路由到外部服务或根据预设规则自动处理。--auto-approve参数允许用户预先批准特定类型的操作（如shell、network、promptRead），而--auto-approve-budget参数则限制了自动批准的次数上限，防止无限循环或滥用。所有审批决策都被记录到会话日志中，形成完整的审计追踪。这种设计使得 SharpClawCode 能够在提供便利性的同时，保持对关键操作的严格控制 。

1.3.3 提供者抽象与多模型解耦

提供者抽象（Provider Abstraction）是 SharpClawCode 实现多模型支持的关键架构模式。IModelProvider接口定义了与语言模型交互的统一契约，包括：发送对话请求、处理流式响应、支持工具调用、管理模型能力查询等。所有具体的模型提供者（Anthropic、OpenAI、本地模型等）都实现这一接口，使得上层运行时无需关心底层使用的是哪个模型。这种抽象带来了显著的灵活性：用户可以在不同模型间无缝切换，比较它们的性能和质量；运行时可以根据任务性质自动选择最合适的模型；新模型的集成只需实现一个接口，无需修改现有代码 。

AnthropicProvider和OpenAiCompatibleProvider是两个主要的内置实现。AnthropicProvider针对 Anthropic 的 Claude 系列模型进行了优化，支持其特有的功能如扩展思考模式。OpenAiCompatibleProvider则是一个通用实现，支持所有兼容 OpenAI API 的端点，包括 OpenAI 官方的 GPT 系列、Azure OpenAI、以及众多第三方兼容服务。特别值得注意的是"本地运行时配置文件"（local runtime profiles）机制，它允许用户注册和管理多个本地模型端点（如 Ollama、llama.cpp），使得开发者可以在完全离线的环境中使用 AI 编码功能。提供者解析器（resolver）负责根据配置和运行时条件选择最合适的提供者实例，而身份验证预检查（auth preflight）机制确保在发起实际请求前，所有必要的认证信息已经准备就绪。这种彻底的解耦使得 SharpClawCode 能够适应快速变化的模型生态，而核心运行时保持稳定 。

1.3.4 结构化遥测与可观测性设计

结构化遥测（Structured Telemetry）是 SharpClawCode 实现运营可读性的关键技术。IRuntimeEventPublisher接口定义了事件发布契约，所有运行时组件都可以通过这一接口发布事件，而无需关心事件的消费方式。事件被定义为强类型对象，包含时间戳、来源组件、事件类型、详细载荷等结构化字段。这种设计区别于简单的日志文本，使得事件可以被程序化处理：过滤、聚合、关联分析、触发告警等。事件发布采用异步模式，避免阻塞主执行流程 。

环形缓冲区（Ring Buffer）是遥测系统的核心数据结构，它在内存中维护最近 N 个事件的循环队列。这种设计具有 O(1) 的写入复杂度，不会随着事件数量增长而变慢，也不会无限制地消耗内存。当缓冲区满时，最旧的事件被覆盖，这种"滑动窗口"模式非常适合实时监控场景。IRuntimeEventPersistence接口定义了可选的持久化策略，事件可以被写入本地文件、发送到 Webhook、导出到外部监控系统，或根据配置丢弃。使用跟踪（Usage Tracking）功能记录了模型调用的详细指标：输入输出 token 数、响应延迟、成本估算等，这些数据对于成本控制和性能优化至关重要。整个遥测系统的设计遵循了"默认开启、最小开销、灵活导出"的原则，确保在开发、测试和生产环境中都能提供适当的可观测性水平 。

2. 核心子系统详解

2.1 会话管理系统（SharpClaw.Code.Sessions）

2.1.1 ISessionStore 与 IEventStore 接口设计

会话管理系统的核心是两个精心设计的接口：ISessionStore和IEventStore。ISessionStore负责会话元数据的 CRUD 操作，包括创建新会话、查询现有会话、更新会话状态、删除会话等。它处理的是会话的"静态"信息，如会话 ID、创建时间、最后活动时间、当前状态、关联的工作区等。IEventStore则专注于事件的持久化，提供追加写入（append-only write）和事件查询能力。这种接口分离使得两种存储可以独立优化和扩展：会话元数据适合用关系型数据库或键值存储，而事件日志则适合用追加优化的存储（如文件系统或专用日志数据库）。两个接口都设计为异步操作，返回Task或IAsyncEnumerable，确保不会阻塞 I/O 线程 。

接口设计充分考虑了实现多样性。ISessionStore支持按多种条件查询会话：按 ID 精确查找、按工作区列出、按时间范围筛选、按状态过滤等。这为构建会话管理 UI 和自动化清理任务提供了基础。IEventStore支持按会话 ID 和时间范围读取事件，支持正向和反向遍历，支持流式读取大量事件而无需一次性加载到内存。这些接口方法都接受取消令牌（CancellationToken），支持长时间操作的取消。接口还定义了并发控制语义，明确在并发修改时的行为预期，这对于多用户场景尤为重要。内置实现包括基于文件系统的FileSystemSessionStore和FileSystemEventStore，以及基于 SQLite 的SqliteSessionStore和SqliteEventStore，用户可以通过--session-store参数选择 。

2.1.2 文件支持的快照机制

快照机制（Snapshot）是解决事件日志过长时恢复性能问题的关键技术。当会话积累了大量事件（数千甚至数万条）时，从头开始重放所有事件会变得缓慢。ISessionStore接口定义了快照的保存和加载操作，其实现需要保证快照与事件日志的一致性——快照必须对应于某个确切的事件序号，确保不会遗漏或重复事件。快照的触发策略是可配置的，可以基于事件数量（每 N 个事件）、时间间隔（每 M 分钟）或显式请求（用户或程序触发）。快照格式选择了与事件日志相同的 NDJSON 风格，保持了一致性和可读性 。

快照文件包含了会话的所有状态：对话历史、工具执行记录、用户偏好、检查点、待办事项等。快照的创建采用了写时复制（copy-on-write）或临时文件 + 原子重命名的策略，确保即使在快照过程中发生崩溃，也不会产生不一致的状态。快照还用于会话共享功能：创建共享链接时，可以基于快照生成一个自包含的会话视图，接收者无需访问完整的事件历史。快照文件的管理（清理过期快照、压缩、迁移）由存储实现负责，对上层透明。这种设计使得 SharpClawCode 能够在保持完整事件历史的同时，提供高效的日常操作性能。

2.1.3 NDJSON 追加日志的不可变事件存储

NDJSON（Newline Delimited JSON）是 SharpClawCode 事件存储的核心格式选择。每条事件是一个独立的 JSON 对象，占一行，事件之间用换行符分隔。这种格式具有多重优势：首先，它是真正的追加写入友好，无需读取或修改现有内容，只需在文件末尾添加新行，这在所有文件系统上都具有最佳性能；其次，它是流式处理的理想格式，可以使用IAsyncEnumerable逐行读取和解析，无需一次性加载整个文件；再次，它是人类可读的，开发者可以直接用文本编辑器或命令行工具（如tail、grep、jq）查看和分析事件日志；最后，它与大数据生态良好集成，可以轻松导入到 Elasticsearch、Splunk 等日志分析平台 。

不可变性（Immutability）是事件存储的核心原则。一旦写入，事件记录永远不会被修改或删除。这种设计简化了并发控制（无需锁机制来防止写入冲突），提高了可靠性（不会因为意外覆盖而丢失数据），并使得缓存和复制更加安全。如果需要"修正"历史，可以通过写入补偿事件（compensating events）来实现，而非直接修改原始记录。存储实现需要处理日志文件的滚动（rollover）：当单个文件过大时，创建新文件，同时维护一个索引或清单来跟踪文件序列。对于高吞吐量场景，可以考虑按日期或大小自动分片。NDJSON 格式的选择体现了 SharpClawCode 在性能、可靠性和可操作性之间的审慎平衡。

2.2 权限控制系统（SharpClaw.Code.Permissions）

2.2.1 IPermissionPolicyEngine 与规则引擎

权限控制系统的核心是IPermissionPolicyEngine接口，它定义了权限评估的统一入口。该接口接收操作上下文（包括操作类型、目标资源、当前权限模式、用户身份等），返回评估结果：允许（Allow）、拒绝（Deny）或需要审批（RequireApproval）。引擎内部实现了基于规则的评估逻辑，规则可以来自多个来源：硬编码的系统默认规则、配置文件中的自定义规则、工作区特定的规则、运行时动态加载的规则。规则具有优先级和覆盖语义，高优先级规则可以覆盖低优先级规则。这种设计使得权限策略既具有确定性（系统默认保护），又具有灵活性（用户和组织可以自定义）。

规则引擎的实现考虑了性能和可维护性。规则被编译为高效的评估结构（如决策树或状态机），避免每次评估时都解析规则文本。规则可以包含条件表达式，基于操作上下文动态评估，例如"允许删除文件，但仅限于obj/和bin/目录"。规则引擎还支持规则集的版本管理，当规则变更时，可以追踪变更历史和影响范围。IPermissionPolicyEngine的实现是单例的，被所有需要权限检查的组件共享，确保策略的一致性。对于复杂的企业场景，规则引擎可以扩展为调用外部策略决策点（PDP），集成现有的身份和访问管理（IAM）系统。这种可扩展性使得 SharpClawCode 能够适应从个人开发者到大型企业的各种权限管理需求。

2.2.2 IApprovalService 与会话批准内存

当权限引擎判定操作需要审批时，IApprovalService接口负责管理审批流程。该接口定义了审批请求的创建、查询、响应和记录操作。在交互式模式下，审批请求被呈现给用户，等待人工决策；在自动化模式下，审批请求可以被路由到外部服务或根据预设规则自动处理。会话批准内存（Session Approval Memory）是一个重要特性，它记录了当前会话中用户已经做出的审批决策，对于类似的后续操作可以自动应用之前的决策，避免重复提示。例如，如果用户批准了"在src/目录下创建文件"，后续在相同目录的创建操作可以自动获得批准 。

批准内存的设计需要平衡便利性和安全性。它是有作用域的（scoped），通常限定于特定会话、特定工作区和特定时间窗口。敏感操作（如执行 shell 命令、修改配置文件）的批准记忆有更短的过期时间。用户可以随时查看和清除批准记忆，/session命令提供了相关管理功能。--auto-approve-budget参数从全局角度限制了自动批准的总次数，作为安全网防止无限循环或恶意利用。所有批准决策，无论是人工还是自动，都被记录到事件日志中，形成完整的审计追踪。IApprovalService的实现可以替换为自定义版本，例如集成企业的工作流系统，使得审批请求通过邮件、Slack 或专门的审批平台处理 。

2.2.3 分级权限模式：提示读取、工具执行、文件操作

SharpClawCode 实现了精细的分级权限模式，将操作划分为多个类别，每个类别可以独立配置权限级别。主要操作类别包括：

上表展示了 SharpClawCode 的分级权限体系。每个类别可以配置为：始终允许、始终拒绝、需要审批、或根据上下文动态决定。这种细粒度控制使得用户可以为不同场景定制最合适的安全策略。例如，在日常编码中，可以允许文件读取和提示查询，但需要审批文件写入和 shell 执行；在自动化 CI/CD 场景中，可以预先批准特定脚本和目录的操作。权限检查是上下文感知的，不仅考虑操作类型，还考虑目标资源的路径、内容敏感性、操作影响范围等因素。例如，写入.env文件或secrets.json会比写入普通源代码文件触发更严格的审查。这种上下文感知能力通过可扩展的评估规则实现，组织可以添加自定义规则来反映特定的安全策略 。

2.3 模型提供者系统（SharpClaw.Code.Providers）

2.3.1 IModelProvider 统一抽象接口

IModelProvider是 SharpClawCode 与语言模型交互的统一抽象，它定义了所有模型操作的标准契约。核心方法包括：SendAsync发送对话请求并获取完整响应、StreamAsync获取流式响应片段、GetCapabilitiesAsync查询模型能力（如是否支持工具调用、最大上下文长度、支持的输出格式）、GetTokenCountAsync估算文本的 token 数量。接口设计充分考虑了异步编程模式，所有方法都返回Task或IAsyncEnumerable，支持取消和超时。接口还定义了配置契约，使得运行时可以从配置文件中自动实例化和配置提供者，无需硬编码 。

IModelProvider的设计目标是彻底解耦上层运行时与具体模型实现。运行时只依赖于接口，不关心底层是 Claude、GPT、本地 Llama 还是其他模型。这种解耦使得：比较不同模型的表现变得容易，只需切换配置即可；新模型的集成无需修改运行时代码；混合使用多个模型（如用轻量模型做路由决策，用强力模型做复杂生成）成为可能；故障转移和负载均衡可以在提供者层实现，对上层透明。接口还定义了健康检查方法，运行时可以定期检测提供者的可用性，在提供者故障时自动切换到备用选项。这种设计使得 SharpClawCode 能够适应快速变化的 AI 模型生态，而核心运行时保持稳定 。

2.3.2 AnthropicProvider 实现与配置

AnthropicProvider是IModelProvider针对 Anthropic Claude 系列模型的专用实现。它完整支持 Claude API 的所有功能，包括：多轮对话、工具使用（function calling）、流式响应、扩展思考模式（extended thinking）等。实现针对 Claude 的 API 格式进行了优化，正确处理其特有的字段和语义。配置通过SharpClaw:Providers:Anthropic节进行，包括：API 密钥、基础 URL（支持智能体或自定义端点）、默认模型 ID、请求超时、重试策略等。API 密钥支持从环境变量、配置文件或运行时密钥管理服务获取，避免硬编码敏感信息 。

AnthropicProvider还实现了 Anthropic 特有的功能适配。例如，Claude 的扩展思考模式需要在请求中特殊标注，响应中包含思考过程和普通响应两部分，提供者实现负责正确解析和呈现。Claude 的工具调用格式与 OpenAI 略有不同，提供者负责转换为统一内部表示。对于 Anthropic 的提示缓存（prompt caching）功能，提供者实现了智能的缓存点插入策略，优化长对话的延迟和成本。错误处理也针对 Anthropic API 的特定错误码进行了优化，区分可重试错误（如速率限制）和不可重试错误（如无效参数），采取不同的恢复策略。这种深度适配使得 SharpClawCode 能够充分发挥 Claude 模型的能力，同时保持与其他模型的统一接口 。

2.3.3 OpenAiCompatibleProvider 与本地运行时配置文件

OpenAiCompatibleProvider是一个通用实现，支持所有兼容 OpenAI API 格式的端点。这包括：OpenAI 官方 API、Azure OpenAI、Google Gemini（通过 OpenAI 兼容模式）、以及大量本地部署方案如Ollama、llama.cpp、vLLM、TGI等。这种广泛的兼容性使得 SharpClawCode 可以灵活部署在各种环境中，从完全离线的本地开发到企业级云端服务。配置通过SharpClaw:Providers:OpenAiCompatible节进行，除了标准的 API 密钥和基础 URL 外，还支持"本地运行时配置文件"（local runtime profiles）机制 。

本地运行时配置文件是一个特别重要的特性，它允许用户注册和管理多个本地模型端点。每个配置文件包含：端点 URL、认证模式（无认证、API 密钥、自定义头）、默认模型 ID、模型发现端点、嵌入模型配置等。SharpClawCode 可以自动探测这些端点的健康状态和可用模型，在--models命令中呈现。对于 Ollama 等支持模型拉取和管理的平台，还可以实现模型的自动下载和更新。本地配置文件使得开发者可以轻松在 Claude/GPT 等云端模型和本地模型之间切换，根据任务性质、隐私要求和成本考虑选择最合适的选项。例如，敏感代码分析可以在本地模型上完成，而复杂的架构设计可以调用云端大模型。这种混合云-边缘的部署模式是 SharpClawCode 架构灵活性的重要体现 。

2.3.4 解析器与身份验证预检查机制

解析器（Parser）组件负责将不同提供者的响应格式统一转换为 SharpClawCode 的内部表示。尽管 OpenAI 兼容 API 有标准格式，各实现仍存在差异：字段命名可能不同、嵌套结构可能有变化、扩展字段可能不兼容。解析器通过可配置的映射规则处理这些差异，确保运行时收到一致的输入。对于流式响应，解析器需要处理分块传输的复杂性，正确组装部分 JSON 对象，处理跨块边界的情况。解析器还负责提取元数据，如 token 使用量、模型 ID、响应 ID 等，这些信息用于计费和审计。解析错误的处理也是重要考量，当收到意外格式时，解析器应优雅降级，记录错误并尝试提取可用信息，而非完全失败 。

身份验证预检查（Auth Pre-check）机制在发送实际 API 请求前验证认证凭据的有效性。这包括：检查 API 密钥格式是否正确、测试密钥是否具有必要的权限、验证网络连通性、检查配额和速率限制状态。预检查避免了浪费 token 在注定失败的请求上，特别是在自动化场景中，可以快速发现问题并切换到备用提供者。预检查的结果被缓存（带有 TTL），避免每次请求都重复验证，但在遇到认证错误时会立即失效刷新。对于需要令牌刷新的认证方案（如 OAuth），预检查还负责在过期前主动刷新。这些机制共同确保了模型交互的可靠性和效率，是生产级 AI 系统不可或缺的组成部分 。

2.4 工具执行框架（SharpClaw.Code.Tools）

2.4.1 IToolRegistry 与 IToolExecutor 双核心

工具执行框架围绕IToolRegistry和IToolExecutor两个核心接口构建，采用了注册表-执行器分离的设计模式。IToolRegistry负责工具的发现、注册和元数据管理。它维护一个工具目录，每个工具条目包含：唯一标识符、显示名称、描述、参数模式（JSON Schema）、返回类型、权限要求、所属类别等。工具可以来自多个来源：内置工具（如文件操作、shell 执行、Git 操作）、插件提供的工具、MCP 服务器暴露的工具、以及工作区特定的自定义工具。注册表支持动态更新，工具可以在运行时添加或移除，无需重启系统。查询接口支持按类别浏览、按名称搜索、按能力筛选，为构建工具选择 UI 和自动化工具链提供了基础 。

IToolExecutor负责实际执行工具调用。它接收工具调用请求（包含工具 ID 和参数），进行参数验证、权限检查、执行调用、处理结果，并返回标准化的执行结果。执行器是异步的，支持长时间运行的工具（如编译、测试套件执行）。它实现了超时控制、取消支持、资源限制（如内存、CPU 时间）等保护机制。执行器还负责捕获和标准化错误输出，将各种工具的错误格式转换为统一的错误结构，便于上层处理。IToolRegistry和IToolExecutor的分离使得工具的发现和执行可以独立扩展：可以添加新的工具来源而不改变执行逻辑，可以优化执行引擎而不影响工具注册。这种双核心设计是工具框架灵活性和可维护性的关键 。

2.4.2 内置工具集与插件工具智能体模式

SharpClawCode 提供了丰富的内置工具集，覆盖日常开发的主要需求：