一个类似pi的rust agent，依靠精炼优雅的设计以较低的行数实现了较多的功能和丰富的可扩展性

项目地址: github.com/whatevertogo/astrcodey
求大佬赏个实习给我吧

一个用 Rust 构建的 AI 编码代理平台。

AstrCode 是一个全栈 AI agent，完全使用 Rust 从零开始构建，共 21 个 crate，约 5.5 万行代码，外加一个 React + TypeScript Web 前端（约 4800 行代码）。它包含一个带有工具执行功能的代理循环、一个基于流式 SSE 的多提供商 LLM 层（支持 Anthropic、OpenAI 和 Google GenAI）、一个插件/钩子扩展系统（支持通过 FFI 和 WASM 进行原生扩展加载）、一个带有自动压缩功能的上下文窗口管理、一个用于自动化基准测试的评估框架，以及多种接口：终端 UI、Web 前端、Tauri 桌面应用程序、HTTP/SSE API 和 ACP（代理客户端协议）适配器。支持mcp，skill，子agent，子agent类型扩展，以及常用的agent工具

核心设计

Agent 循环

Agent 循环（astrcode-session）采用分阶段流水线模式：

1. 准备上下文 — 检查 token 预算，必要时触发自动压缩
2. 构建 Provider 请求 — 分发钩子、组装消息、MCP 工具发现
3. 流式接收 LLM 响应 — SSE 解析、UTF-8 安全解码、事件累积
4. 执行工具 — 并行批量执行，支持 pre/post 钩子，结果持久化
5. 循环或返回 — 有工具调用则回到步骤 1；纯文本回复则终止

Agent 支持运行模式切换（Code / Plan）。Plan 模式下只暴露只读工具和计划管理工具，通过 Exit Gate（自审清单 + 必填 heading 校验）控制退出条件，计划 Artifact 持久化到 <session>/plan/plan.md。模式指令通过 BeforeProviderRequest 注入，不影响 system prompt 的 KV 缓存。

ToolPipeline 结构体负责工具预处理、并行调度和结果持久化。SharedTurnContext 携带会话级标识。consume_llm_stream 返回 StreamOutcome 枚举（Complete | ToolCalls），让循环体读起来是一组线性排列的命名阶段。

LLM Provider 层

astrcode-ai 支持多个 Provider — Anthropic（原生 Messages API）、OpenAI 兼容（Chat Completions + Responses API）、Google GenAI。核心组件：

• Utf8StreamDecoder — 跨 TCP chunk 处理多字节 UTF-8 边界和坏字节恢复
• SseLineReader — 通用 SSE 行缓冲（可供所有 Provider 复用）
• RetryPolicy — 针对 429/5xx 错误的指数退避重试（带抖动）

上下文窗口管理

当对话历史接近模型的上下文限制 83.5% 时，astrcode-context 触发自动压缩：

1. 默认使用 LLM 生成结构化 9 段摘要（自动压缩和手动压缩均走此路径）
2. LLM 调用失败（网络错误、解析错误、超时等）时自动降级为确定性规则摘要
3. 压缩记录持久化为快照，用于调试
4. 压缩后自动恢复最近读取的文件和 Agent/Skill/Tool 状态

工具执行

工具以并行批量方式执行（最多 5 个并发）。执行管线：

1. 预处理 — 解析 JSON 参数（支持修复格式不正确的 LLM 输出）、检查可见性、分发 PreToolUse 钩子
2. 执行 — 通过 JoinSet 并行批量执行，串行工具会先刷新当前批次
3. 提交 — 分发 PostToolUse 钩子、持久化大结果、执行消息字符预算、发射事件

大型工具结果自动持久化到磁盘，替换为预览摘要以保持在消息字符预算内。

扩展系统

扩展系统（astrcode-extensions）是架构核心支柱，而非附属功能：

• Extension trait — 每个扩展声明钩子订阅、贡献工具和斜杠命令、处理生命周期事件
• Hook 模式 — Blocking（可修改输入/输出）、NonBlocking（fire-and-forget）、Advisory（仅观察）
• 快捷键注册 — 扩展通过 Registrar::keybinding() 注册键盘快捷键（如 Shift+Tab 切换模式）
• 状态栏项 — 扩展贡献状态栏条目（如当前模式指示器），通过 StatusItemUpdate 通知动态更新
• 原生扩展加载 — 通过 libloading + FFI 从磁盘加载 .dll/.so 扩展，支持全局（~/.astrcode/extensions/）和项目级（.astrcode/extensions/）目录
• WASM 扩展运行时 — 基于 wasmtime 的沙箱化扩展执行，提供 host-guest 协议用于工具注册和事件处理
• 扩展运行时 — 带深度限制的会话派生、工具注册队列、优先级分派

ACP 适配器

ACP 适配器（astrcode-server::acp）将标准 Agent Client Protocol 桥接到 astrcode 内部的命令/广播架构：

• 基于 stdio 的 JSON-RPC 服务器，实现 Initialize / NewSession / Prompt / Cancel
• 通过 broadcast channel 实时流式转发事件为 ACP SessionNotification
• 利用 completion oneshot 实现 turn 生命周期的确定性事件刷新
• 为 IDE 插件和编辑器集成设计

运行模式

TUI 参考

键盘快捷键：

斜杠命令：

插件扩展可在运行时注册额外的斜杠命令和快捷键。

发行

每个版本标签自动触发 GitHub Release，提供 Linux、macOS、Windows（x86_64 + aarch64）的预编译二进制文件。每周一自动发布 patch 版本。

致谢

本项目借鉴了以下开源项目的设计思想和工程实践：

• Claude Code — 工具执行管线、系统提示词设计
• OpenCode — 前后端分离（HTTP/SSE + JSON-RPC）参考了 OpenCode 的架构。
• Codex CLI — TUI 布局和终端 UI 设计借鉴了 Codex 在终端中渲染 Agent 交互的方式。

License

AGPL-3.0