项目介绍
AutoSteer
-lightgrey){kind=icon}
AutoSteer 是一个桌面应用程序，通过多工作区管理增强了你的 Claude Code 使用体验。它使用 Electron 构建，支持 macOS、Linux 和 Windows（通过 WSL），允许你在多个隔离的工作区中管理持久会话，并实现无缝上下文切换。
演示
https://github.com/user-attachments/assets/65219ff1-f600-412a-8a5f-fe7a1880704f
[!NOTE] 本项目与 Anthropic 无关，未得到 Anthropic 的认可或赞助。Claude 是 Anthropic, PBC 的商标。这是一个独立项目，使用 Claude。
功能
- 工作树优先架构 - 在隔离的工作区中组织项目，每个工作区具有独立的文件系统和上下文
- 持久会话 - 每个工作树保存并恢复对话，保持整个工作会话的上下文
- 多项目管理 - 在不同项目之间无缝切换，不会丢失状态或上下文
- 跨平台 - 原生支持 macOS、Linux 和 Windows（通过 WSL）
- 上下文保存 - 自动保存对话状态，让你从上次离开的地方继续
- 快速上下文切换 - 瞬间在工作树之间切换
- 令牌使用跟踪 - 监控每条消息和每个工作树的令牌使用情况和成本
- 状态面板 - 查看会话信息，管理 MCP 服务器，处理 MCP 认证
- 协议追踪查看器 - 检查详细的协议消息用于调试和理解代理行为
- 自定义斜杠命令 - 通过自定义命令模式扩展 Claude Code 功能（文件：src/commons/utils/slashCommandUtils.ts）
📦 安装
前提条件：必须先安装 Claude Code。
快速安装
从 发布页面 下载适用于你平台的最新版本：
- macOS：下载
.zip文件并解压到应用程序 - Linux：下载
.deb（Debian/Ubuntu）或.rpm（Fedora/RHEL） - Windows：通过 WSL2 安装
平台特定说明
有关包括 Windows 上 WSL2 设置在内的详细安装说明，请参阅 INSTALLATION.md
🚀 开始使用
# 启动 AutoSteer
autosteer
# 启动带有调试日志
autosteer --debug
启动后，在设置中配置你的偏好设置，并开始使用 AutoSteer 中的 Claude Code！
AutoSteer 在所有平台上将配置存储在 ~/.autosteer/。
🛠️ 开发
前提条件
- Node.js（v20 或更高版本）
- pnpm（v9 或更高版本）
- Git
- 平台特定构建工具：
- macOS：Xcode 命令行工具
- Linux：
build-essential包 - Windows：使用 WSL 和 Linux 构建工具
从源码构建
# 克隆仓库
git clone https://github.com/notch-ai/autosteer.git
cd autosteer
# 安装依赖
pnpm install
# 在开发模式下运行
pnpm dev
# 运行测试
pnpm test
# 构建应用
pnpm compile
# 打包分发
pnpm make
开发脚本
# 启动开发服务器
pnpm dev
# 运行单元测试
pnpm test:unit
# 运行集成测试
pnpm test:integration
# 运行所有测试
pnpm test
# 校验代码
pnpm lint
# 格式化代码
pnpm format
# 类型检查
pnpm typecheck
# 编译应用（TypeScript + Webpack）
pnpm compile
# 为当前平台打包应用
pnpm package
# 创建可分发的安装程序
pnpm make
项目结构
autosteer/
├── src/
│ ├── main/ # Electron 主进程
│ │ └── ipc/ # 进程间通信层
│ │ ├── handlers/ # 4 个合并的领域处理器
│ │ │ ├── claude.handlers.ts # 代理、MCP、斜杠命令操作
│ │ │ ├── project.handlers.ts # 文件、资源管理
│ │ │ ├── git.handlers.ts # Git 操作
│ │ │ └── system.handlers.ts # 终端、徽章、配置、日志、存储、更新
│ │ ├── utils/handlerFactory.ts # 可重用的错误处理、日志记录、验证
│ │ └── IpcRegistrar.ts # 集中的处理器注册
│ ├── features/ # 基于领域的特性组织
│ │ ├── chat/ # 聊天特性领域（15 个组件）
│ │ ├── monitoring/ # 监控特性领域（10 个组件）
│ │ ├── settings/ # 设置特性领域（4 个组件）
│ │ └── shared/ # 特性间共享的组件（48 个组件）
│ │ └── components/ # 按子域组织
│ │ ├── agent/
│ │ ├── git/
│ │ ├── layout/
│ │ ├── projects/
│ │ ├── session/
│ │ ├── tasks/
│ │ ├── terminal/
│ │ └── ui/
│ ├── components/ # 常见的 UI 层（shadcn/ui 原语）
│ ├── services/ # 应用服务
│ ├── stores/ # 状态管理（Zustand）
│ ├── hooks/ # React 钩子
│ ├── commons/
│ │ ├── utils/ # 实用函数
│ │ │ └── slash-commands/ # 斜杠命令实用工具
│ │ ├── contexts/ # React 上下文
│ │ ├── constants/ # 常量和配置
│ │ └── config/ # 主题和样式
│ ├── entities/ # 数据模型（轻量级清洁架构）
│ └── types/ # TypeScript 类型
├── assets/ # 应用图标和图像
├── tests/
│ ├── unit/ # 单元测试（目标覆盖率为 80%）
│ ├── integration/ # 集成测试
│ ├── component/ # Playwright 组件测试
│ └── factories/ # 测试数据工厂
├── scripts/ # 构建和发布脚本
└── playwright-component.config.ts # 组件测试配置
导入模式：@/features/[domain]/components/[Component]
🤝 贡献
我们欢迎贡献！请参阅我们的 贡献指南 获取详细信息。
贡献者快速入门
# 分叉并克隆
git clone https://github.com/YOUR_USERNAME/autosteer.git
cd autosteer
# 安装依赖
pnpm install
# 开始开发
pnpm dev
# 提交前运行测试
pnpm test
pnpm lint
pnpm typecheck
🧪 测试
运行测试
我们使用 Jest 进行单元/集成测试，使用 Playwright 进行组件/视觉测试：
# 运行所有测试
pnpm test
# 仅运行单元测试
pnpm test:unit
# 仅运行集成测试
pnpm test:integration
# 在监视模式下运行测试
pnpm test:watch
# 运行带有覆盖率报告的测试
pnpm test:coverage
测试覆盖率
关键测试文件涵盖关键功能：
- 实用工具：
tests/unit/commons/utils/slash-commands/slash_command_utils.test.ts- 自定义斜杠命令格式化 - 钩子：
tests/unit/hooks/useTerminalPool.test.ts- 终端池管理 - IPC 处理器：
tests/unit/main/ipc/handlers/- 合并的领域处理器 - 服务：
tests/unit/services/ClaudeCodeService.test.ts- 核心 Claude Code 集成 - 存储：
tests/unit/stores/core.test.ts- 状态管理 - 类型：
tests/unit/types/terminal.types.test.ts- 终端类型安全 - 实体：
tests/unit/entities/SessionBlock.test.ts- 数据模型验证
🔍 追踪文件格式
AutoSteer 为调试 SDK 消息流创建追踪文件。这些文件存储在 ~/.autosteer/traces/ 并使用 JSONL 格式（每行一个 JSON 对象）。
追踪文件位置
~/.autosteer/traces/{sessionId}.trace.jsonl
追踪条目格式
每个追踪条目是一个具有以下结构的 JSON 对象：
{
"timestamp": "2025-11-09T18:51:35.123Z", // ISO 8601 时间戳
"sessionId": "session-abc123", // 会话标识符
"direction": "to-claude" | "from-claude", // 消息方向
"rawMessage": { /* SDK 消息对象 */ }, // 完整的 SDK 消息
"sdkVersion": "^0.1.0", // SDK 版本
"correlationId": "550e8400-e29b-41d4", // 请求/响应关联
"sequenceNumber": 42 // 每个会话的单调序列号
}
追踪文件生命周期
- 创建：当 SDK 消息被记录时自动创建追踪文件
- 轮换：当文件超过 100MB 时进行轮换，带有时间戳后缀
- 清理：当项目被删除时自动删除追踪文件
- 手动清理：删除
~/.autosteer/traces/中的文件以释放磁盘空间
使用追踪文件
追踪文件可用于：
- 调试：检查发送和接收的确切 SDK 消息
- 性能分析：跟踪消息时间和顺序
- 错误调查：审查导致错误的消息流程
- SDK 更新：验证跨 SDK 版本的消息格式变化
示例追踪条目
{
"timestamp": "2025-11-09T18:51:35.123Z",
"sessionId": "session-abc123",
"direction": "from-claude",
"rawMessage": {
"type": "assistant",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "session-abc123",
"message": {
"role": "assistant",
"content": [{ "type": "text", "text": "Hello!" }]
}
},
"sdkVersion": "^0.1.0",
"correlationId": "550e8400-e29b-41d4",
"sequenceNumber": 42,
"messageType": "assistant",
"messageSubtype": null
}
🔄 SDK 迁移指南
概述
本指南帮助开发者处理 Anthropic Claude SDK 更新和 Pydantic 模型更改，而不会破坏现有的消息验证。
SDK 版本更新
当更新 @anthropic-ai/claude-agent-sdk 时：
-
检查破坏性变更
- 查看 SDK 发布说明中的破坏性变更
- 使用新 SDK 类型测试验证
- 如需更新 Pydantic 模型
-
更新 Zod 模式
- 位置：
src/services/MessageValidator.ts - 将模式匹配到新的 SDK 类型
- 维持向后兼容性，使用宽松验证
- 位置：
-
测试验证
pnpm test:unit -- MessageValidator.test.ts -
更新追踪文档
- 在 README 中记录新的消息类型
- 在
.sketchpad/claude_message_types.py中更新 Pydantic 模型
Pydantic 模型更改
添加新的消息类型
-
更新 Python 模型
- 将新的消息类型添加到
.sketchpad/claude_message_types.py - 遵循现有的 BaseModel 模式
- 添加到
SDKMessage联合类型
- 将新的消息类型添加到
-
更新 TypeScript 模式
- 在
MessageValidator.ts中添加相应的 Zod 模式 - 添加到区分联合
- 更新类型守卫
- 在
-
添加测试
- 为新的消息类型添加测试用例
- 测试严格的和宽松的验证
- 测试部分提取
示例：
// 添加到 MessageValidator.ts
const NewMessageTypeSchema = z.object({
type: z.literal('new_type'),
uuid: z.string().uuid(),
session_id: z.string(),
// ... 其他字段
});
处理破坏性的 SDK 更改
如果 SDK 更新破坏了验证：
-
识别破坏性变更
- 检查验证测试失败
- 查看追踪日志中的错误模式
- 比较旧版和新版消息结构
-
逐步更新模式
// 旧字段（已弃用但仍然支持） old_field: z.string().optional(), // 新字段（首选） new_field: z.string().optional(), -
添加迁移逻辑
- 处理旧版和新版格式
- 为弃用字段记录警告
- 逐步淘汰旧版格式
-
版本兼容性
- 在追踪日志中跟踪 SDK 版本
- 如需添加版本检查
- 文档版本要求
测试迁移
# 运行所有验证测试
pnpm test:unit -- MessageValidator
# 使用固定数据测试
pnpm test:integration -- message-validation
# 检查类型覆盖
pnpm typecheck
回滚策略
如果验证在生产环境中中断：
- 立即：回退到之前的 SDK 版本
- 短期：部署带有宽松验证的热修复
- 长期：修复模式并重新部署
最佳实践
- 始终在部署前使用真实的消息固定数据测试
- 至少维持两个 SDK 版本的向后兼容性
- 在 PR 描述中记录破坏性变更
- 使用宽松验证作为防止崩溃的后备
- 更新后监控追踪日志中的验证失败
🔒 安全
- 进程隔离：代理在单独的进程中运行
- 本地存储：所有数据都保留在你的机器上
- 无遥测：不收集或跟踪数据
🔧 故障排除
获取帮助
- 通过 GitHub Issues 报告错误
- 通过 讨论 请求功能
📄 许可
本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。