GitHub - bastani-inc/atomic：用于软件工程的动态工作流，支持Pi扩展、自定义模型、MCP、子代理、工件、审查关卡和运行时中途引导。
GitHub - bastani-inc/atomic：用于软件工程的动态工作流，支持Pi扩展、自定义模型、MCP、子代理、工件、审查关卡和运行时中途引导。
Atomic 是编码代理（coding agent）的工作流层，为开发者提供可编程控制平面，用于复杂的工程工作。它是一个开源、模型无关的软件工程动态工作流方案——支持 Pi 扩展、自定义模型、MCP、子代理、工件和审查关卡。
- Node.js 24 LTS 或更新版本——Atomic 需要最新的 Node LTS 运行时。使用
node --version检查版本。 - 包管理器——使用 npm（随 Node 附带）、pnpm、Yarn 或 Bun。对于 Bun 安装或工作流编写示例，请使用 Bun 1.3.14 及以上版本。
- 模型提供方访问权限——启动后使用
/login登录。支持提供方订阅和 API。
使用 npm 安装：
npm install -g @bastani/atomic
使用 pnpm 安装：
pnpm add -g @bastani/atomic
使用 bun 安装：
bun add -g @bastani/atomic
Atomic 不需要包安装脚本。如果希望在 Atomic 安装期间禁用依赖生命周期脚本，可以在安装命令中添加 --ignore-scripts。
设置 API 密钥并启动会话：
export ANTHROPIC_API_KEY=sk-ant-...
atomic
或者登录到现有订阅：
atomic /login
然后选择一个提供方——Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等。
登录后，运行 /atomic 开始引导式入门，了解工作流、示例和下一步操作。
完整的提供方列表（API 密钥 + 订阅）请参见 提供方与模型。对于非交互式使用，atomic -p "" 将输出响应并退出。
⚠️ 工作流运行时将禁用代理许可检查，以便管道不会在提示时阻塞。请在 devcontainer、VM 或远程开发机器中运行自主工作流（autonomous workflow）——而不是您的宿主机。
⚠️ 临时工作流迁移说明：近期的工作流编写变更可能需要更新自定义工作流，特别是那些按注册名称或路径对象导入其他工作流的工作流。现在工作流导入使用标准的 TypeScript 模块导入，并将编译后的工作流定义传递给 .import(workflow, { as? })。如果现有工作流无法加载，请要求 Atomic 或您的编码代理根据[工作流导入指南]进行更新。
前提条件、Devcontainer
前提条件——安装 Node.js 24 LTS+、全局包管理器、模型提供方访问权限以及兼容的终端。请参见提供方与模型和终端设置。
Devcontainer / VM——推荐用于自主工作流。Atomic 可在任何安装了 Node.js 24 LTS+ 的标准 devcontainer 或 VM 镜像中运行；使用 npm install -g @bastani/atomic（或安装脚本）在容器内安装，并通过环境变量提供提供方凭证。
有关 SDK 和 RPC 的入口点，请参见编程使用指南。
Atomic 发布了一个代理可读的 .llms.txt。请让您当前的编码代理：按照 https://docs.bastani.ai/llms.txt 安装和设置 Atomic。
理解 Atomic 最快的方法是遵循内置的规范驱动开发循环：
研究代码库 -> 创建规范 -> 运行实现工作流 -> 审查工件
当您了解子系统或问题时，使用聚焦研究：
/skill:research-codebase how the rate limiter works in src/middleware/
Atomic 会调度专门的代理，将确凿的发现写入仓库，并留下可供将来运行重用的研究成果。
对于繁重的工作——迁移、大型重构、跨切面行为或任何涉及多个包的工作——运行仓库范围的深度研究：
/workflow deep-research-codebase prompt="Map every callsite of the legacy auth middleware so we can migrate to session-v2"
您也可以以对话方式调用工作流——例如，运行"deep research to map every callsite of the legacy auth middleware so we can migrate to session-v2"——如果您更愿意不使用斜杠命令的话。
deep-research-codebase 的作用类似于仓库索引过程：侦察代码库，展开并行的专业研究，汇总发现，并在 research/ 下编写持久的 Markdown 工件。这些研究将成为项目的共享记忆。
将研究成果转化为可实现的计划：
/skill:create-spec from research/docs/2026-03-rate-limit.md
如果您还不确定想要什么，可以先与 Atomic 进行头脑风暴：探索权衡方案，比较不同方法，然后要求它将选定的方向保存为规范。无论哪种方式，输出都是一个位于 specs/ 下的仓库原生工件，工程师可以在实现开始前进行审查。
以自然语言要求 Atomic 使用与工作范围匹配的工作流：
- 使用 goal 实现 specs/2026-03-rate-limit.md，运行聚焦的速率限制测试，在突发流量返回 429 并带有 Retry-After 头时完成。
- 运行 ralph 将 VS Code 桌面 Shell 从 Electron 移植到 Tauri/Rust，同时保留扩展加载、IPC、工作区状态和设置迁移。
当您能够确定工作范围、说明期望的确切结果并命名证明完成所需的验证时（例如特定测试、lint/类型检查命令、文档构建或可观察行为），使用 goal 处理小到中等范围的变更。它会保持运行有边界，在目标记录（goal ledger）中捕获收据，通过审查关卡进行门控，并在 complete、blocked 或 needs_human 状态下停止。
对于更大的迁移、广泛的重构和多包更改，继续使用 ralph，在其中您希望 Atomic 将提示转换为研究问题，首先研究代码库，通过子代理委派实现，进行审查和迭代。只有当您需要最终的拉取请求（pull request）阶段和报告时，才添加 create_pr=true。
编码代理对于本地编辑和短交互会话很有用。更大的机会在于自动化围绕它们的开发者工作流：研究、规划、实现、审查、发布准备、事件响应、迁移、QA、文档以及团队可以描述为可重复工程工作的任何内容。
Atomic 是一个用于开发者工作流的可编程控制平面。定义步骤、在需要时分支、并行运行阶段、隔离上下文、保存工件、调用工具、运行检查，并在下一个关键操作前停止等待人工批准。如果一个工作流很重要，Atomic 为您提供一种自动化、检查并扩展它的方式。
我们构建 Atomic 的目的是让您不再需要时刻监督编码代理。您无需观察每一步、在上下文漂移时重新提示、以及担心是否正确执行了检查，而是获得一个能够生成可检查工件并让您对结果充满信心的自动化工作流。
Atomic 的观点很简单：开发者应该拥有自己工作的自动化层。不要将重要的工程任务留给黑盒自主会话，然后希望代理遵循了正确的流程。让工作流明确、模型无关、可检查、可重复且可审计。
在以下情况下使用 Atomic：
- 需要进行研究、分阶段编辑、测试和审查的大型重构。
- 跨多个文件、包或服务的迁移。
- 规范驱动型特性开发，其中研究和计划应保存在仓库中。
- 需要复现、诊断、修复和验证的调试流程。
- 应成为持久团队记忆的代码库研究。
- 目前手动执行的重复序列：研究 -> 实现 -> 测试 -> 审查。
- 希望代理实际作为可执行工作流步骤遵循的 Markdown 指令、提示或检查清单。
Atomic 提供了三个顶层构建块：工作流、技能和专门的子代理。