acryldev/acryl · 上手攻略

  • 仓库：acryldev/acryl
  • 链接：https://github.com/acryldev/acryl
  • 分类：AI 编程 · Agent 开发环境 · 持久化工作区
  • 作者：Tom
  • 更新：2026-08-30

是什么

ACRYL（Agent Context Relay Yielding Lifecycles）是一个跨编码 agent 的持久化开发环境和上下文层。它的设计哲学是：agent 来来去去，项目上下文常驻。Claude Code、Codex、OpenCode、Gemini CLI、DeepSeek Harness 等 coding agent 可以作为可替换的 worker 接入 ACRYL，但工作区、任务、上下文、交接文档都由 ACRYL 统一拥有，而不是归 agent 所有。

换句话说：如果把 coding agent 想象成开发团队中的外包工程师，ACRYL 就是项目管理层——记录每个人的上下文、保留交接文档、维护任务状态，而 agent 只需要专心写代码。

⚠️ 注意：ACRYL 处于早期活跃开发阶段（v0.1.0），接口、工作流和打包方式可能在首个公开基础版本确立前发生变化，生产使用需谨慎。

解决什么问题

现有 coding agent 的共同问题是agent 退出后上下文丢失：

  • 同一个项目，今天用 Claude Code 修了一个 bug，明天换 Codex 来继续，两边没有共享的上下文。
  • agent session 结束后，历史对话、任务状态、代码理解都不跨 session 保留。
  • 每次新 session 开始，agent 都需要重新理解项目——随着 agent 越来越多，这个成本会指数增长。

ACRYL 的核心思路是：把工作区和上下文的所有权从 agent 那里剥离出来，交给 ACRYL。ACRYL 用 Cordis（一个元框架）管理生命周期、插件系统和服务注入，所有 agent 都通过统一的接口访问同一个持久的项目上下文。

快速安装

下载安装包（桌面应用）

平台 下载方式
macOS Apple Silicon DMG
macOS Intel DMG
Windows x64 Installer
Linux x64 / Debian DEB
Linux arm64 / Debian DEB

CLI（npm）

npm install -g acryldev

从源码构建（需要 Node.js ^22.19.0 或 >= 24.0.0）

git clone https://github.com/acryldev/acryl.git
cd acryl

# 初始化子模块
git submodule update --init --recursive

# 安装依赖（使用 corepack pnpm）
corepack pnpm install --frozen-lockfile

# 本地开发启动（隔离 ACRYL home）
corepack pnpm dev

# 构建生产包
corepack pnpm build

⚠️ Node.js 版本要求严格：不支持 v20、v21、v22.0–22.18，请确认 node --version。

核心概念

架构分层

ACRYL
 ├── Desktop UI / TUI / CLI    ← 三个入口
 ├── ACRYL capabilities         ← 业务能力层
 └── Cordis                     ← 底层运行时（插件生命周期、
                                  命名服务、可替换 provider、
                                  响应式依赖注入、事件拦截、
                                  可逆副作用、作用域组合）

Cordis 负责把 agents、context、tools、UI、memory、code graph 都当作可组合的能力（capability）而非硬编码子系统。

持久化 ACRYL 项目包含

  • 规范的事件流（canonical event stream）
  • 持久化的任务和产物（durable tasks & artifacts）
  • Agent 身份和 session 记录
  • 上下文投影（context projections）
  • 结构化交接文档（structured handoffs）
  • 工作区和检查点（workspaces & checkpoints）
  • Cordis 能力图

信任内核原则

信任内核应保持小而稳定。新功能通常作为版本化的能力包到达，可以被验证、激活、观察和回滚，而无需重写应用核心。

核心功能

开发画布（Development Canvas）

ACRYL 的主要工作界面，替代主内容区，提供一个可组合的工作区，支持：

  • 原生 PTY 终端
  • Coding agent sessions
  • 文件和编辑器
  • 浏览器标签页
  • 未来由 plugin 提供的工具和视图

多 Agent Provider 支持

Provider 状态
Claude Code ✅ 支持
Codex ✅ 支持
OpenCode ✅ 支持
Pi ✅ 支持
Gemini CLI ✅ 支持
DeepSeek Harness 原生 agent ✅ 支持
ACP 兼容 agent ✅ 支持
PTY / CLI agent ✅ 支持
其他未知 agent ✅（可发现 ACRYL 存在并接入）

插件化能力系统

所有功能都基于 Cordis 能力系统：context tools、memory providers、code graph providers、workflow providers、UI contributions 都可以作为独立插件添加、替换、观察和回滚，无需修改内核。

DeepSeek Harness 的角色

ACRYL 从 DeepSeek Harness 继承了大量架构思路（持久 session 事件、能力接缝、agent 运行时服务、PTY、沙盒、web UI 组合），但 ACRYL 是独立项目，deepseek-harness/ 以只读子模块形式 pinned 在项目中，不与 ACRYL 的开发分支合并。ACRYL 与 DeepSeek 无附属关系。

典型适用场景

  1. 多 agent 接力开发：今天 Claude Code 写前端架构，明天 Codex 补充后端测试，两者共享同一个 ACRYL 项目上下文，不需要重复传递代码理解。
  2. 持久化 code review 跟踪：每次 agent 对代码的修改、决定、发现都以结构化方式记录在 ACRYL 中，后续任何 agent 或人类都可以查询这些历史。
  3. 团队 AI 辅助开发规范：通过 Cordis 的 capability system，团队可以定义哪些工具/上下文访问权限属于哪个 agent，打造符合安全要求的 AI 开发环境。
  4. 跨 session 的任务连续性：开发者下班，agent session 结束；第二天回来 ACRYL 恢复所有任务状态，不需要从零描述项目。

坑与注意

  • ⚠️ v0.1.0 早期版本：官方明确警告接口和工作流可能在首个公开基础版本确立前变化，不要在重要项目里依赖当前 API 的稳定性。
  • ⚠️ Node.js 版本强约束：只支持 ^22.19.0 或 >= 24.0.0，不支持 v20、v21 和 22.0–22.18，需要提前确认环境。
  • submodule 依赖：从源码构建需要 git submodule update --init --recursive，首次 clone 时间较长。
  • 开发模式隔离：运行 corepack pnpm dev 会用独立的 DSH_HOME=~/.dsh-acryl 和独立的 Electron userData 目录，与已安装的 ACRYL 应用隔离——这是有意设计，便于安全测试新功能。
  • Quit 已有 DSH Desktop 实例：启动本地图形开发环境前，需要先退出已安装的 DSH Desktop 实例，避免竞争桌面资源或进程端口。
  • deepseek-harness 子模块只读：不要在 ACRYL 特性分支里编辑 deepseek-harness/ 子模块；更新 pin 需单独走 corepack pnpm upstream:update 流程。

与同类对比

工具 持久化上下文 跨 agent 共享 能力插件系统 状态
ACRYL ✅ ACRYL 拥有 ✅ 统一工作区 ✅ Cordis v0.1.0 早期
Claude Code ❌ agent 私有 ❌ ❌ 稳定
DeepSeek Harness ✅（session 级） 部分 ✅ 稳定
OpenCode ❌ agent 私有 ❌ ❌ 稳定
Cursor 项目级，非跨 agent ❌ ❌ 稳定

ACRYL 的差异化在于上下文所有权明确归平台所有而非 agent，且基于 Cordis 的能力系统天然支持多 agent 接入——这是其他单 agent 工具没有的设计。

一句话推荐结论

如果你在团队中同时使用多个 coding agent，或者项目需要跨 session 保持开发上下文，ACRYL 把"持久化工作区所有权"从 agent 手里接管过来、用 Cordis 能力系统管理插件的这个设计，是目前开源领域里最有规模的跨 agent 开发连续性方案——虽然 v0.1.0 还在早期，但架构思路值得关注，现在即可下载试用。

来源：GitHub README（v0.1.0）、AGENTS.md、docs/onboarding/；⚠️ 版本和接口信息以 README 最新状态为准，v0.1.0 早期版本可能有变化。