代理式编码飞轮搭建方案（ACFS）

🌐 agent-flywheel.com — 面向初学者的交互式搭建向导

从零起步，30分钟内完成全配置的代理式编码 VPS。
一套完整的自建系统，可将全新的 Ubuntu VPS 转化为专业级的 AI 驱动开发环境。

快速安装

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

该安装脚本具备幂等性——若中途中断，只需重新运行即可。它会自动从上一次已完成的步骤继续执行，无需再次提示。

生产环境： 为确保安装稳定且可重复，建议将安装脚本固定到某个已标记的发行版或特定提交：

# 推荐方式：使用已标记的发行版（例如 v0.5.0）
ACFS_REF=v0.5.0 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.5.0/install.sh" | bash -s -- --yes --mode vibe

# 替代方案：固定到特定的提交 SHA
ACFS_REF=abc1234 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/abc1234/install.sh" | bash -s -- --yes --mode vibe

已标记的发行版经过测试，稳定性可靠。通过设置 ACFS_REF，可确保所有下载的脚本均使用同一版本。

简要总结

ACFS 是一套完整的代理式编码环境自建系统：

为什么值得关注：

• 从零到英雄： 让完全的初学者从“我有一台笔记本电脑”一路成长为“我拥有 Claude/Codex/Gemini 代理，在 VPS 上为我编写代码”
• 单行命令魔法： 仅需一条 curl | bash 命令，即可安装 30 多种工具，完成所有配置，并快速部署三个 AI 编码代理
• Vibe 模式： 预配置以实现最大化的加速效率——免密码 sudo，启用危险代理标志，优化 Shell 环境
• 经实战检验的完整栈： 包含 Dicklesworthstone 的全套工具（10 种工具 + 实用程序），用于代理编排、协调与安全防护

您将获得：

• 现代 Shell（zsh + oh-my-zsh + powerlevel10k）
• 所有语言运行时（bun、uv/Python、Rust、Go）
• 三个 AI 编码代理（Claude Code、Codex CLI、Gemini CLI）
• 代理协调工具（NTM、MCP Agent Mail、SLB）
• 云原生 CLI（Vault、Wrangler、Supabase、Vercel）
• 还有 20 多种开发者工具

ACFS 体验

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    subgraph 用户 ["用户机器"]
        LAPTOP["笔记本电脑"]
        BROWSER["浏览器"]
    end

    subgraph 向导 ["向导网站"]
        STEPS["13 步指南"]
    end

    subgraph VPS ["全新 VPS"]
        UBUNTU["Ubuntu 25.10"]
        INSTALLER["install.sh"]
        CONFIGURED["已配置的 VPS"]
    end

    subgraph 代理 ["AI 代理"]
        CLAUDE["Claude Code"]
        CODEX["Codex CLI"]
        GEMINI["Gemini CLI"]
    end

    LAPTOP --> BROWSER
    BROWSER --> STEPS
    STEPS -->|SSH| UBUNTU
    UBUNTU --> INSTALLER
    INSTALLER --> CONFIGURED
    CONFIGURED --> CLAUDE
    CONFIGURED --> CODEX
    CONFIGURED --> GEMINI

    classDef 用户 fill:#e3f2fd,stroke:#90caf9,stroke-width:2px
    classDef 向导 fill:#fff8e1,stroke:#ffcc80,stroke-width:2px
    classDef VPS fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px
    classDef 代理 fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px

    class LAPTOP,BROWSER user
    class STEPS wizard
    class UBUNTU,INSTALLER,CONFIGURED vps
    class CLAUDE,CODEX,GEMINI agent

面向初学者

ACFS 在 agent-flywheel.com 提供了一个分步向导网站，可引导完全的初学者完成以下步骤：

1. 在本地机器上安装终端
2. 生成 SSH 密钥（以便后续安全访问）
3. 从 OVH 或 Contabo 等服务商租用 VPS
4. 使用密码通过 SSH 连接（初始设置）
5. 运行安装脚本（该脚本可完成基于密钥的访问配置）
6. 使用 SSH 密钥安全地重新连接
7. 开始使用 AI 代理进行编码

面向开发者

ACFS 是一条单行命令，可将任何全新的 Ubuntu VPS 转化为功能完备的开发环境，配备现代化的工具和三个现成可用的 AI 编码代理。

面向团队

ACFS 提供了一套可重复、幂等的搭建流程，确保每位团队成员的 VPS 环境完全一致——彻底消除“在我的机器上能正常运行”的顾虑，助力代理式工作流的高效开展。

架构与设计

ACFS 以单一真理来源为核心构建：即 manifest 文件。其他一切——安装脚本、检查工具、网站内容——均源自这一核心定义。这种架构确保了系统的统一性，并使系统易于扩展。

一页式系统数据流

flowchart TB
  %% 用户与网站
  subgraph U["用户（本地机器）"]
    Browser["浏览器"]
    Terminal["终端 / SSH 客户端"]
  end

  subgraph W["向导网站（Next.js 16）——apps/web"]
    Wizard["向导 UI（/wizard/*）"]
    InstallRoute["GET /install（302 重定向至原始安装脚本）"]
    WebState["状态：URL 参数 + localStorage"]
  end

  %% 仓库源码
  subgraph R["仓库（源码）"]
    Manifest["acfs.manifest.yaml<br/>模块 + 安装 + 验证 + 依赖项"]
    Generator["packages/manifest<br/>解析器（Zod）+ generate.ts"]
    Generated["scripts/generated/*（参考）<br/>分类安装程序 + doctor_checks.sh"]
    Installer["install.sh（生产级单行命令）"]
    Lib["scripts/lib/*<br/>安全 / 医生 / 更新 / 服务设置"]
    Configs["acfs/*<br/>zshrc + tmux.conf + 上机课程"]
    Checksums["checksums.yaml<br/>上游安装程序的 SHA256 校验值"]
    Tests["tests/vm/test_install_ubuntu.sh<br/>Docker 集成测试"]
  end

  %% 目标 VPS
  subgraph V["目标 VPS（Ubuntu 25.10，自动升级）"]
    Run["运行 install.sh"]
    Verify["已验证上游安装程序<br/>(security.sh + checksums.yaml)"]
    AcfsHome["~/.acfs/<br/>配置文件 + 脚本 + state.json"]
    Commands["命令<br/>acfs doctor / acfs update / acfs 服务设置 / 上机课程"]
    Tools["已安装的工具<br/>bun/uv/rust/go + tmux/rg/gh + vault + ..."]
    Agents["代理 CLI<br/>claude / codex / gemini"]
    Stack["堆栈工具<br/>ntm / mcp_agent_mail / ubs / bv / cass / cm / caam / slb / dcg / ru"]
  end

  %% 网站引导流程
  Browser --> Wizard
  Wizard --> WebState
  Wizard --> InstallRoute
  InstallRoute -->|重定向至| Installer

  %% 用户如何获取并运行安装程序
  Terminal -->|curl / bash| Installer
  Terminal -->|SSH| 运行

  %% 基于 manifest 的生成（今日参考）
  Manifest --> Generator --> Generated
  Generated -.->|计划：install.sh 调用 generated install_all.sh| Installer

  %% 安装程序的构成
  Lib --> Installer
  Configs --> Installer
  Checksums --> Installer
  Tests -->|验证| Installer

  %% VPS 安装结果
  Installer --> 运行
  Run --> Verify
  Verify --> 工具
  Verify --> 代理
  Verify --> 堆栈
  Run --> AcfsHome --> 命令

┌─────────────────────────────────────────────────────────────────────────────┐
│                            真实来源                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ acfs.manifest.yaml                                                  │    │
│  │ 工具定义 • 安装命令 • 验证逻辑                           │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│        代码生成            │   │        向导网站             │
│  ┌─────────────────────────────┐  │   │  ┌─────────────────────────────┐  │
│  │ TypeScript 解析器（Zod）     │  │   │  │ apps/web/（Next.js 16）      │  │
│  │ generate.ts                 │  │   │  │ agent-flywheel.com          │  │
│  └─────────────────────────────┘  │   │  └─────────────────────────────┘  │
└───────────────────────────────────┘   └───────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                     生成输出（参考）                          │
│  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐   │
│  │ scripts/generated/ │  │ doctor_checks.sh   │  │ install_all.sh     │   │
│  │ 11 类别脚本│  │ 验证逻辑 │  │ 主要安装程序 │   │
│  └────────────────────┘  └────────────────────┘  └────────────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                            目标 VPS                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ 30 多种工具    │  │ zsh + p10k   │  │ AI 代理    │  │ ~/.acfs/     │   │
│  │ 已安装的工具    │  │ Shell 配置 │  │ Claude/Codex │  │ 配置文件 │   │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘

为何采用这种架构？

单一真相来源：acfs.manifest.yaml 文件定义了每一种工具——其名称、描述、安装命令以及验证逻辑。当您在清单中添加或编辑工具时，生成器会自动更新生成的脚本和基于清单生成的检查。如今，生产级单行命令安装程序（install.sh）仍由人工编写，因此，如果行为发生变更，可能也需要更新 install.sh，直到完成全面迁移。

TypeScript + Zod 验证：清单解析器使用 Zod 模式来在解析时对 YAML 进行验证。拼写错误、缺失字段以及结构错误会在生成阶段立即被检测出来——而非在用户 VPS 的运行时，当安装程序在半途中失败时才被发现。

生成的脚本：与其手动维护 11 个类别安装程序脚本并保持它们同步，生成器会从清单中自动生成这些脚本。这意味着：

• 对于清单定义的安装逻辑，可以拥有统一且可审计的视图（部分模块故意留有 TODO 语句）
• 所有模块的错误处理与日志记录保持一致
• 为未来的安装程序集成铺平了清晰的道路

组件

清单系统

acfs.manifest.yaml 是 ACFS 所安装的所有工具的单一真相来源。它定义了要安装哪些内容、如何安装，以及如何验证安装是否成功。

清单结构

version: "1.0"
meta:
  name: "ACFS"
  description: "Agentic 编程飞轮设置"
  version: "0.1.0"

modules:
  base.system:
    description: "基础软件包 + 合理的默认配置"
    category: base
    install:
      - sudo apt-get update -y
      - sudo apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential
    verify:
      - curl --version
      - git --version
      - jq --version

  agents.claude:
    description: "Claude 代码"
    category: agents
    install:
      - "通过官方方式安装 Claude 代码"
    verify:
      - claude --version || claude --help

每个模块都指定：

• 描述：人类可读的名称
• 类别：用于组织安装器的分组（基础、Shell、CLI、语言、工具、数据库、云服务、代理、堆栈、ACFS）
• 安装：需要运行的命令（或将成为待办事项的说明）
• 验证：必须成功执行的命令，以确认安装是否成功

生成器流水线

TypeScript 生成器（packages/manifest/src/generate.ts）会读取清单，并生成以下内容：

1. 类别脚本（scripts/generated/install_base.sh、install_agents.sh 等）

   • 每个类别对应一个脚本，包含各自的安装功能
   • 日志记录与错误处理一致
   • 在每个模块之后执行验证检查

2. 医生检查（scripts/generated/doctor_checks.sh）

   • 将所有验证命令提取为可运行的健康检查
   • 使用制表符分隔格式（以安全地处理 Shell 命令中的 ||）
   • 为每个模块提供通过/失败/跳过的报告

3. 主安装器（scripts/generated/install_all.sh）

   • 从所有类别脚本中获取源码
   • 按依赖顺序依次运行这些脚本
   • 作为运行生成的安装器的单一入口点

注意：生产用的一条命令安装器（install.sh）默认采用旧版实现；生成的安装器则会根据类别来源，并在迁移过程中通过特性标志进行启用。

若在清单发生变更后重新生成：

cd packages/manifest
bun run generate        # 生成脚本
bun run generate:dry    # 预览，不写入文件

为什么选择 TypeScript 进行代码生成？

Shell 可以使用 yq 解析 YAML，但 TypeScript + Zod 提供了以下优势：

• 类型安全：解析器能够准确了解清单的精确结构
• 验证：Zod 会以清晰的错误提示捕捉格式不正确的 YAML
• 转换：复杂的逻辑（如按依赖排序、转义）在 TypeScript 中自然流畅
• 一致性：所有生成的代码遵循相同的模式

生成器本身仅约 400 行 TypeScript 代码。生成的输出则多达 1000 行 Bash 代码，共 13 个文件。这种权衡显然更有利于保持生成器的稳定性。

安全验证

ACFS 会从互联网上下载并执行安装器脚本。这本身就存在风险——上游如果遭到入侵，可能会注入恶意代码。安全验证系统正是为了降低这种风险而设计的。

工作原理

checksums.yaml 文件中包含了所有上游安装器脚本的 SHA256 校验和：

# checksums.yaml
installers:
  bun:
    url: "https://bun.sh/install"
    sha256: "a1b2c3d4..."

  rust:
    url: "https://sh.rustup.rs"
    sha256: "e5f6a7b8..."

安全库（scripts/lib/security.sh）提供了以下功能：

1. HTTPS 防护：所有安装器 URL 必须使用 HTTPS。非 HTTPS 的 URL 会立即被拒绝。

2. 校验和验证：在执行下载的脚本之前，系统会：

   • 将内容下载到内存
   • 计算 SHA256 校验和
   • 与存储的校验和进行比对
   • 只有在校验和匹配时才执行脚本

3. 验证模式：

   ./scripts/lib/security.sh --print              # 列出所有上游 URL
   ./scripts/lib/security.sh --verify             # 对所有 URL 进行校验和验证
   ./scripts/lib/security.sh --update-checksums   # 生成新的 checksums.yaml
   ./scripts/lib/security.sh --checksum URL       # 计算任意 URL 的 SHA256 校验和
   

校验和失败时的情况

校验和不匹配可能意味着：

1. 正常更新：上游维护人员发布了新版本
2. 潜在威胁：有人恶意修改了脚本

验证报告会区分这两种情况：

• 若多个校验和同时失败，请在更新前进行深入调查
• 若在已知版本发布后，单个校验和失败，则更新很可能安全

若需在验证合法的上游变更后进行更新：

./scripts/lib/security.sh --update-checksums > checksums.yaml
git diff checksums.yaml  # 查看具体更改内容
git commit -m "chore: 更新上游校验和"

为何采用这种方式？

curl | bash 的模式虽备受争议，但其实很实用。ACFS 通过以下方式使其更加安全：

• 在执行前验证内容（而不仅仅是通过 HTTPS 进行传输）
• 让校验和在版本控制中可审计
• 提供工具来检测和调查变更
• 在出现不匹配时直接失败，而非继续执行

这是一种纵深防御策略——HTTPS 保护传输，校验和保护内容。

安装器

安装器是 ACFS 的核心——一个模块化的 Bash 脚本，可将全新的 Ubuntu VPS 转化为一个完全配置好的开发环境。

使用方法

完整氛围模式（推荐用于一次性使用的 VPS）：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

交互式模式（询问确认）：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash

安全模式（无需密码的 sudo，且已启用代理确认）：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --mode safe

安装模式

安装阶段

graph TD
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    A["第一阶段：用户规范化<br/><small>创建 Ubuntu 用户，迁移 SSH 密钥</small>"]
    B["第二阶段：APT 包<br/><small>安装系统必备软件包</small>"]
    C["第三阶段：Shell 配置<br/><small>zsh、Oh-My-Zsh、Powerlevel10k</small>"]
    D["第四阶段：CLI 工具<br/><small>ripgrep、fzf、lazygit 等</small>"]
    E["第五阶段：语言运行时<br/><small>bun、uv、Rust、Go</small>"]
    F["第六阶段：AI 代理<br/><small>Claude、Codex、Gemini</small>"]
    G["第七阶段：云工具<br/><small>Vault、Wrangler、Supabase、Vercel</small>"]
    H["第八阶段：Dicklesworthstone 堆栈<br/><small>NTM、DCG、RU、UBS、MCP_Agent_Mail 等</small>"]
    I["第九阶段：配置<br/><small>部署 acfs.zshrc、tmux.conf</small>"]
    J["第十阶段：验证<br/><small>acfs doctor</small>"]

    A --> B --> C --> D --> E --> F --> G --> H --> I --> J

    classDef phase fill:#e8f5e9,stroke:#81c784,stroke-width:2px,color:#2e7d32
    class A,B,C,D,E,F,G,H,I,J phase

关键属性

恢复能力

安装程序会将进度记录在 ~/.acfs/state.json 中。若中途中断：

• 重新执行同一命令——即可从上一个已完成的阶段继续执行
• 无需提示或确认（使用 --yes 参数）
• 已安装的工具会被自动检测并跳过。

若需强制重新安装所有工具：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --force-reinstall

预检查

在运行完整安装程序之前，请先验证您的系统：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --json
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --format toon

此脚本会检查以下内容：

• 操作系统兼容性（Ubuntu 22.04+；安装程序升级至 25.10）
• 架构类型（x86_64 或 ARM64）
• 内存与磁盘空间（最低 4GB RAM，10GB 空闲磁盘）
• 网络连接是否可达所需 URL
• APT 锁定状态
• 可能存在的冲突（nvm、pyenv、现有 ACFS）

网络检查结果：

常见预检查失败情况：

控制台输出

安装程序采用语义化颜色来区分进度：

[1/8] 正在安装必备软件包...     # 蓝色：进度步骤
    正在安装 zsh、git、curl...           # 灰色：详细信息
⚠️ 可能需要几分钟时间                 # 黄色：警告
✖ 安装软件包失败               # 红色：错误
✔ Shell 配置已完成                    # 绿色：成功

自动 Ubuntu 升级

当 ACFS 在旧版本上运行时，会在安装前自动将 Ubuntu 升级至版本 25.10。此举可确保与最新软件包的兼容性，并获得最佳性能。

工作原理：

1. 检测当前使用的 Ubuntu 版本
2. 计算升级路径（例如：24.04 → 25.04 → 25.10）
3. 依次执行 do-release-upgrade 操作
4. 每次升级后自动重启
5. 重启后通过 systemd 服务继续运行
6. 当达到目标版本时，继续进行 ACFS 的安装过程

预计时间表：

• 每个版本的升级耗时 30–60 分钟
• 从 24.04 到 25.10 的完整升级链需时 1.5–3 小时
• 重启期间 SSH 会话会断开（需重新连接以监控进度）

若要跳过自动升级：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --skip-ubuntu-upgrade

若要指定不同的目标版本：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --target-ubuntu=25.04

监控升级进度：

# 查看当前状态
/var/lib/acfs/check_status.sh

# 查看升级日志
journalctl -u acfs-upgrade-resume -f

# 查看详细日志
tail -f /var/log/acfs/upgrade_resume.log

重要提示：

• 在升级前创建虚拟机快照（建议操作，但非必须）
• 未通过快照恢复，升级将无法撤销
• 系统会自动多次重启
• 如果某些临时发布的版本（如 24.10）不再由 do-release-upgrade 提供，可能会被自动跳过
• 每次重启后需通过 SSH 重新连接，以监控升级进度

更新命令

安装完成后，工具的持续更新由 acfs-update 负责。它提供了一个统一的界面，用于更新所有已安装的组件。

使用方法

acfs-update                  # 更新 APT、运行时、Shell、代理及云 CLI
acfs-update --stack          # 包含 Dicklesworthstone 堆栈工具
acfs-update --agents-only    # 仅更新编码代理
acfs-update --runtime-only   # 仅更新运行时（bun、Rust、uv、Go）
acfs-update --dry-run        # 预览变更，无需实际执行
acfs-update --yes --quiet    # 自动化/CI 模式，输出极简

总结

ACFS 通过自动化流程和模块化设计，确保了工具的高效安装与持续更新。无论是从基础的系统配置到高级的 AI 代理，ACFS 都能轻松应对各种需求。

更新内容

选项

类别选择：

--apt-only       仅更新系统包
--agents-only    仅更新编码代理
--cloud-only     仅更新云 CLI
--shell-only     仅更新 Shell 工具（OMZ、P10K、插件、Atuin、Zoxide）
--runtime-only   仅更新运行时（bun、rust、uv、go）
--stack          包含 Dicklesworthstone 堆栈（默认启用）

跳过某些类别：

--no-apt         跳过 apt 更新
--no-agents      跳过代理更新
--no-cloud       跳过云 CLI 更新
--no-shell       跳过 Shell 工具更新
--no-runtime     跳过运行时更新（bun、rust、uv、go）

行为：

--force            安装缺失的工具（不只是更新现有工具）
--dry-run          预览更改，无需实际执行
--yes, -y          非交互式模式（跳过提示）
--quiet, -q        最小化输出（仅显示错误和概要）
--verbose, -v      显示详细的命令输出
--abort-on-failure 在首次失败时停止（默认继续）

日志

更新日志会自动保存至 ~/.acfs/logs/updates/，并附带时间戳：

# 查看最新日志
cat ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

# 监控正在运行的更新
tail -f ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

为何要与安装器分开？

安装器会将全新 VPS 进行改造；而更新命令则在原有安装基础上进行维护。将两者分开，可实现以下目标：

• 专注更新：仅更新代理，而不触碰系统包
• 预览变更：在提交更改前，先查看将要发生的变化
• 跳过特定类别：暂时排除那些运行良好的类别
• 控制堆栈：堆栈更新默认包含在内；若需跳过，可使用 --no-stack
• 自动化更新：通过 cron 任务执行，配合 --yes --quiet 使用

ACFS 命令行工具

安装完成后，acfs 命令为您的环境管理提供了一个统一的接口。每个子命令都经过精心设计，既快速又信息丰富，且支持脚本化操作。

快速参考

acfs info                    # 极速系统概览
acfs cheatsheet              # 查看已安装的别名
acfs dashboard generate      # 生成 HTML 状态页面
acfs doctor                  # 运行健康检查
acfs newproj                 # 创建新项目（TUI 或 CLI）
acfs update                  # 更新所有工具
acfs services-setup          # 配置代理凭据
acfs continue                # 在重启后查看升级进度

acfs newproj — 新项目向导

创建一个新项目目录，采用 ACFS 的默认配置（Git 初始化、可选的 br/beads、Claude 设置、AGENTS.md）。 建议初学者使用交互式向导。

交互式向导（推荐使用）：

acfs newproj --interactive
acfs newproj -i
acfs newproj -i myapp         # 预填项目名称

向导会引导您完成以下步骤：

• 项目命名与位置
• 技术栈检测/选择
• 功能选型（br/beads、Claude 设置、AGENTS.md、UBS 忽略）
• AGENTS.md 自定义预览

    ╔═══════════════════════════════════════════════════════╗
    ║                                                       ║
    ║      █████╗  ██████╗ ███████╗ ███████╗                ║
    ║     ██╔══██╗██╔════╝ ██╔════╝ ██╔════╝                ║
    ║     ███████║██║      █████╗   ███████║                ║
    ║     ██╔══██║██║      ██╔══╝   ╚════██║                ║
    ║     ██║  ██║╚██████╗ ██║      ███████║                ║
    ║     ╚═╝  ╚═╝ ╚═════╝ ╚═╝      ╚══════╝                ║
    ║                                                       ║
    ║          Agentic Coding Flywheel 设置                ║
    ║                                                       ║
    ╚═══════════════════════════════════════════════════════╝

本向导将帮助您设置新项目：

  ✓ 项目目录结构
  ✓ Git 仓库初始化
  ✓ AGENTS.md 用于 AI 编程助手
  ✓ Beads 问题跟踪（可选）
  ✓ Claude Code 设置（可选）

──────────────────── 审核与确认 ────────────────────
                                              第 7 步，共 9 步

请在创建项目前仔细审核您的选择。

项目概览
──────────────────────────────────────────────────────────
  名称：       myapp
  位置：       /home/user/projects/myapp
  技术：       Node.js、TypeScript

功能
──────────────────────────────────────────────────────────
  ✓ Beads 跟踪
  ✓ Claude Code 设置
  ✓ AGENTS.md
  ✓ UBS 忽略

需要创建的文件
──────────────────────────────────────────────────────────
myapp/
├── .git/
├── AGENTS.md
├── .beads/
│   └── beads.db
├── .claude/
│   └── settings.local.json
├── .ubsignore
├── README.md
└── .gitignore

选项：
  [Enter/c]   创建项目
  [e]         编辑选择（返回上一步）
  [q/Esc]     取消

CLI 模式（自动化）：

acfs newproj myapp
acfs newproj myapp /custom/path
acfs newproj myapp --no-br

注意：

• TUI 在可用时会使用“Gum”键盘快捷键（箭头键、空格键切换、Enter 键确认）。若无 Gum，系统会退回到数字提示。
• 最小终端尺寸：60x15。
• CLI 模式会跳过已存在的 AGENTS.md；向导会覆盖该文件，因此如果您希望保留旧版本，请将其移至一旁。

acfs info — 系统概览

通过读取缓存状态（无需验证），可在不到1秒内显示安装状态。

acfs info                # 默认终端输出
acfs info --json         # 用于脚本编写的 JSON 输出
acfs info --html         # 自包含的 HTML 页面
acfs info --minimal      # 仅提供基本信息（IP、关键命令）

示例输出：

╔══════════════════════════════════════════════════════════════╗
║                    ACFS 系统信息                           ║
╠══════════════════════════════════════════════════════════════╣
║  主机：vps-12345.contabo.net                                  ║
║  IP：192.168.1.100                                            ║
║  用户：ubuntu                                                 ║
║  运行时间：3天4小时                                      ║
║                                                               ║
║  快速命令：                                              ║
║    cc    → Claude Code（危险模式）                       ║
║    cod   → Codex CLI（危险模式）                         ║
║    gmi   → Gemini CLI（Yolo 模式）                             ║
║    ntm   → Named Tmux Manager                                 ║
╚══════════════════════════════════════════════════════════════╝

设计理念：

• 速度：必须在1秒内完成。
• 只读：绝不进行验证或测试（这属于医生的职责）。
• 离线：无需网络调用。
• 容错：若数据缺失，可实现优雅降级。

acfs cheatsheet — 别名发现

解析 ~/.acfs/zsh/acfs.zshrc 文件，展示所有已安装的别名和命令。

acfs cheatsheet              # 列出所有别名
acfs cheatsheet git          # 根据类别或搜索词进行筛选
acfs cheatsheet --category Agents
acfs cheatsheet --search docker
acfs cheatsheet --json       # 用于工具开发的 JSON 输出

示例输出：

╔══════════════════════════════════════════════════════════════╗
║  ACFS 别名表                                               ║
╠══════════════════════════════════════════════════════════════╣
║  代理                                                        ║
║    cc   → claude --dangerously-skip-permissions                ║
║    cod  → codex --dangerously-bypass-approvals-and-sandbox     ║
║    gmi  → gemini --yolo                                        ║
║                                                                ║
║  Git                                                           ║
║    gs   → git status                                           ║
║    gp   → git push                                             ║
║    gl   → git pull                                             ║
║    gco  → git checkout                                         ║
║                                                                ║
║  现代 CLI                                                    ║
║    ls   → lsd --inode --long --all                             ║
║    cat  → bat                                                  ║
║    grep → rg                                                   ║
║    lg   → lazygit                                              ║
╚══════════════════════════════════════════════════════════════╝

acfs dashboard — HTML 状态页面

生成自包含的 HTML 状态页面，并可选择将其服务化。

acfs dashboard generate              # 生成 ~/.acfs/dashboard/index.html
acfs dashboard generate --force      # 强制重新生成
acfs dashboard serve                 # 在本地主机 8080 上提供服务
acfs dashboard serve --port 3000     # 自定义端口
acfs dashboard serve --public        # 绑定到 0.0.0.0

仪表板提供以下功能：

• 系统健康状况一目了然
• 工具版本与状态
• 快速命令参考
• 最近活动汇总

acfs services-setup — 凭证配置

交互式向导，用于配置 AI 代理凭证及云服务登录信息。

acfs services-setup          # 运行完整的设置向导

引导您完成以下步骤：

• Claude Code：API 密钥配置
• Codex CLI：ChatGPT 账户登录
• Gemini CLI：Google 账户认证
• GitHub CLI：gh auth login
• 云 CLI：Wrangler、Supabase、Vercel 认证

此外，还提供安装 DCG（破坏性指令守护器） 的选项，该工具可拦截诸如 rm -rf / 这类破坏性命令。

acfs continue — 升级进度

在 Ubuntu 升级后重启系统时，查看安装进度：

acfs continue                # 显示当前升级状态

显示内容包括：

• 原始 Ubuntu 版本
• 目标版本
• 当前升级阶段
• 完成后的下一步操作

学习中心（网页）

除了基于终端的入门引导外，ACFS 还在 agent-flywheel.com/learn 提供了一个全面的网页学习中心。

网页课程

学习中心提供互动式课程，并具备进度追踪功能：

特点：

• 进度追踪存储于 localStorage 中
• 代码块附带复制按钮
• 可扩展的深度探索章节
• 实践练习

命令参考

命令参考 文档记录了每一种已安装的工具：

技术术语表

术语表 定义了 100 多个技术术语，包括：

• 单行命令：快速提示定义
• 完整解释：通俗易懂的语言描述
• 类比：“可以这样想……”
• 为何使用：它解决了什么问题
• 相关术语：为背景信息提供参考

示例条目：

RAM（随机存取内存）
├── 简称：计算机在工作时使用的快速临时存储
├── 深入理解：RAM 是你电脑的短期记忆……
├── 类比：就像你在工作时的桌面空间
├── 为什么：更多 RAM 可以同时运行更多程序
└── 相关术语：vCPU、VPS、NVMe

飞轮可视化

飞轮页面 可以直观地展示工具之间的交互关系：

计划（珠子）——> 协调（代理邮件）——> 执行（NTM + 代理）
      ^                                              │
      │                                              v
      └──── 记忆（CASS 内存） <──── 扫描（UBS） ┘

工作流场景：

工具状态页面

工具状态页面 提供了一个可搜索的工具目录，其中列出了所有已安装的工具：

• 搜索与筛选：按名称、CLI 命令、功能或技术栈来查找工具
• 分类浏览：可根据“飞轮堆栈”（核心代理工具）或“实用工具”进行筛选
• 工具详情：每张卡片均显示工具名称、CLI 命令、GitHub 星标、功能以及技术栈
• 实时数据：内容由 acfs.manifest.yaml 自动生成——从未手动编辑

该页面帮助用户发现自己可能尚未了解的工具，并了解每种工具在代理式编码工作流程中的具体位置。

交互式网站组件

向导网站内置了专门的组件，用于引导新手用户：

连接检查组件： 一个醒目的可视化界面，可帮助用户在运行命令前验证是否已成功连接到其 VPS：

• 对比两者的侧边栏：“错误（笔记本电脑）” vs “正确（VPS）”
• 提供适用于 Windows、Mac 和 Linux 的终端提示示例
• 通过彩色样式清晰警示“STOP！”字样

命令卡片组件： 提供 CLI 指令卡片，具备以下功能：

• 语法高亮的代码块
• 一键复制按钮
• 适用于不同平台的版本（bash/zsh/PowerShell）
• 可扩展的解释说明

术语组件（响应式技术术语）：
一套复杂的工具提示系统，能够根据设备能力灵活调整：

桌面端行为：

• 鼠标悬停时会弹出浮动工具提示，显示术语的定义
• 使用 Radix UI 工具提示，实现无障碍的 ARIA 兼容覆盖层
• 视口感知定位（靠近边缘时自动翻转）
• 200ms 的悬停延迟，避免工具提示信息过载

移动端行为：

• 点击后会打开底部抽屉式菜单（Vaul 库）
• 完整的术语定义无需依赖微小的点击目标即可查看
• 支持滑动关闭手势
• 提供对称点和全屏展开选项

视觉特征：

• 渐变下划线表示可点击的术语
• 每个术语都会根据 slug 哈希赋予独特的渐变效果
• 配色方案与 OKLCH 标记保持一致

术语内容结构：

{
  term: "VPS",
  short: "虚拟专用服务器——一种您租用的远程计算机",
  long: "VPS 是您专属的一片强大计算机……"
}

彩带庆祝：
在课程结束时：

• 突然绽放大量庆祝彩带颗粒
• 随机出现鼓励性留言
• 特别为完成所有课程而举办的庆祝活动
• 严格遵守 prefers-reduced-motion 设置

步进器组件：
多步骤进度指示器：

• 以可视化方式逐步推进进度
• 支持点击导航
• 添加完成标记
• 设计兼顾移动端需求

扩展的课程库

学习中心为迪克尔斯沃斯通堆栈中的每种工具都提供了专门的课程：

每门课程均包含：

• 概念介绍
• 实践命令及示例
• 互动练习
• 常见的陷阱与注意事项
• 工具文档链接

交互式入门指南（TUI）

安装完成后，用户可通过交互式终端教程学习 ACFS 工作流。入门 TUI 会动态从 acfs/onboard/lessons 中发现课程 Markdown 文件，因此随着新工具和新工作流的添加，课程体系也能随之不断扩展，而无需更改启动器本身。

运行入门指南

onboard                # 启动交互式菜单
onboard status         # 显示完成状态
onboard --list         # 简写形式，等同于 status
onboard 3              # 跳转至第 3 课
onboard reset          # 重置进度，重新开始
onboard --reset        # 简写形式，等同于 reset

课程

运行 onboard --help 可查看当前已发现的课程列表。目前，课程体系涵盖 Linux 基础、SSH、tmux、代理登录、NTM、飞轮工作流、更新、珠子、RCH 以及其他 ACFS 工具。由于课程是按文件名发现的，只需新增一个 NN_name.md 文件，教程便会自动扩展。

进度追踪

进度保存在 ~/.acfs/onboard_progress.json 中：

{
  "completed": [0, 1, 2],
  "current": 3,
  "started_at": "2024-12-20T10:30:00-05:00"
}

TUI 会显示每节课的完成状态，并提示用户接下来要学习哪一课。用户可以跳转至任意课程，也可以重新学习已完成的课程。

通过 Gum 提升用户体验

若已安装 Charmbracelet Gum，入门系统会利用 Gum 来优化终端界面——包括选择菜单、样式化提示以及更出色的排版效果。若未安装 Gum，则系统会退回到简单的数字菜单，但依然能在任何地方正常运行。

已安装工具

ACFS 安装了一套全面的工具集合，共包含 30 多种工具，并按类别进行了整理：

Shell 与终端体验

编程语言与包管理器

开发工具

网络相关

Tailscale 集成：

Tailscale 提供了一种安全且加密的网络连接方案，可在设备之间实现无缝通信，而无需复杂的防火墙配置：

# 身份验证并加入你的 tailnet
tailscale up

# 检查连接状态
tailscale status

# 获取你的 Tailscale IP 地址
tailscale ip

# 通过 Tailscale 进行 SSH 连接（绕过防火墙）
ssh ubuntu@your-vps.tailnet-name.ts.net

适用于代理型工作流的优势：

• 无防火墙限制的访问：即使身处 NAT 或受限的防火墙后，也能轻松连接。
• MagicDNS：可通过主机名而非 IP 地址直接访问你的 VPS。
• 通过 Tailscale 使用 SSH 密钥：只需执行 tailscale ssh 即可实现免密认证。
• ACL 权限控制：为团队环境提供细粒度的权限管理。

AI 编程代理

Vibe 模式别名：

# Claude Code，使用最大内存（默认启用后台任务）
alias cc='NODE_OPTIONS="--max-old-space-size=32768" claude --dangerously-skip-permissions'

# Codex，采用绕过机制并允许对文件系统进行危险操作
alias cod='codex --dangerously-bypass-approvals-and-sandbox'

# Gemini，采用 Yolo 模式
alias gmi='gemini --yolo'

安装与更新： Claude Code 应通过其原生机制进行安装与更新：

• 安装：ACFS 使用官方原生安装器（claude.ai/install.sh），并通过 checksums.yaml 进行校验（安装路径为 ~/.local/bin/claude）。
• 更新：使用 claude update --channel latest（内置功能），或运行 acfs update --agents-only。

这样可以确保正确的身份验证处理，并避免因其他包管理器构建而导致的问题。对于 Codex 和 Gemini，ACFS 采用标准的 Bun 全局包更新机制。

云服务与数据库

Vault 默认已安装（可通过 --skip-vault 跳过）。ACFS 会安装 Vault 的 CLI，以便您能尽早使用真正的密钥管理工具；它不会自动为您配置 Vault 服务器。

Supabase 网络注意事项：部分 Supabase 项目会公开 仅支持 IPv6 的 Postgres 直连主机（通常在免费套餐中可用）。如果您的 VPS 或网络仅支持 IPv4，请改用 Supabase 的 池化 连接字符串（或升级/配置网络，以实现直接的 IPv4 连接）。

Dicklesworthstone 堆栈（10 个工具）

专业代理型工作流的完整工具套件：

扩展工具

在堆栈之外额外安装的生产力工具：

医生命令

acfs doctor 会对您的安装进行全面的健康检查：

$ acfs doctor

╔══════════════════════════════════════════════════════════════╗
║                    ACFS 健康检查                          ║
╠══════════════════════════════════════════════════════════════╣
║ 身份信息                                                      ║
║   ✔ 以 ubuntu 用户身份运行                                    ║
║   ✔ 已启用无密码 sudo                                      ║
║                                                               ║
║ 工作区                                                     ║
║   ✔ /data/projects 存在                                         ║
║                                                               ║
║ Shell                                                         ║
║   ✔ 安装了 zsh                                            ║
║   ✔ 安装了 oh-my-zsh                                        ║
║   ✔ 安装了 powerlevel10k                                       ║
║   ✔ 从 acfs.zshrc 获取配置                                     ║
║                                                               ║
║ 核心工具                                                    ║
║   ✔ bun 1.2.16                                                ║
║   ✔ uv 0.5.14                                                 ║
║   ✔ cargo 1.84.0                                              ║
║   ✔ go 1.23.4                                                 ║
║   ✔ ripgrep 14.1.0                                            ║
║   ✔ ast-grep 0.30.1                                           ║
║                                                               ║
║ 代理                                                        ║
║   ✔ claude 1.0.24                                             ║
║   ✔ codex 0.1.2504252326                                      ║
║   ✔ gemini 0.1.12                                             ║
║                                                               ║
║ 云服务                                                        ║
║   ✔ vault 1.18.3                                              ║
║   ✔ wrangler 4.16.0                                           ║
║   ✔ supabase 2.23.4                                           ║
║   ✔ vercel 41.7.6                                             ║
║                                                               ║
║ 迪克尔斯沃斯堆栈                                       ║
║   ✔ ntm 0.3.2                                                 ║
║   ✔ slb 0.2.1                                                 ║
║   ✔ ubs 0.1.8                                                 ║
║   ✔ bv 0.9.4                                                  ║
║   ✔ cass 0.4.2                                                ║
║   ✔ cm 0.1.3                                                  ║
║   ✔ caam 0.2.0                                                ║
║   ✔ dcg 0.1.0                                                 ║
║   ✔ ru 1.2.0                                                  ║
║   ⚠ mcp_agent_mail（未运行）                              ║
║                                                               ║
║ 实用工具                                                     ║
║   ✔ giil 3.0.0                                                ║
║   ✔ csctf 1.0.0                                               ║
╠══════════════════════════════════════════════════════════════╣
║ 总体：35/36 项检查通过                                  ║
╚══════════════════════════════════════════════════════════════╝

生成的医生检查

医生检查由清单文件（scripts/generated/doctor_checks.sh）生成，以确保验证逻辑与 acfs.manifest.yaml 紧密衔接。acfs doctor 命令会自动加载这些生成的检查，以验证所有清单中定义的工具。

工作原理：

1. 清单生成器会为每个模块创建 doctor_checks.sh 文件，并附带相应的验证命令。
2. acfs doctor 会加载该文件并运行每项验证检查。
3. 对于失败的检查，系统会显示一条 修复建议，并提供具体的重新安装命令。

示例输出，附带修复建议：

  ✗ tools.lazygit - 未找到 Lazygit 终端界面
    修复方法：acfs install --only tools.lazygit

这种架构确保医生检查与安装程序保持同步——只要工具已纳入清单，就会被逐一验证。

选项

acfs doctor              # 交互式彩色输出
acfs doctor --json       # 机器可读的 JSON 输出
acfs doctor --quiet      # 仅输出退出码（0 表示健康，1 表示存在问题）
acfs doctor --deep       # 运行功能测试（认证、连接）
acfs doctor --fix        # 对失败的检查应用安全修复方案
acfs doctor --dry-run    # 预览修复方案，无需实际执行
acfs doctor --no-cache   # 跳过缓存，重新运行所有检查

深度检查 (--deep)

--deep 标志会运行超出二进制文件本身范围的功能测试：

深度检查采用 5 秒超时机制，以避免因网络问题导致卡顿。结果会缓存 5 分钟，以便加快重复运行的速度。

示例输出：

深度检查
  ✔ Claude 认证已配置
  ✔ PostgreSQL 连接正常工作
  ⚠ Codex 未完成认证（需运行：codex login）
  ✔ GitHub CLI 已认证

8/9 项功能测试在 3.2 秒内通过

自动修复模式 (--fix)

--fix 标志会自动为常见问题应用安全、确定性的修复措施：

acfs doctor --fix             # 应用安全修复
acfs doctor --fix --dry-run   # 预览修复效果，无需实际执行

安全的自动修复工具

当使用 --fix 时，这些修复操作将自动执行：

安全性保障

• 绝不会删除用户文件 — 只会创建、修改或创建符号链接
• 在修改前进行备份 — 对所有已修改的文件进行 SHA256 校验的备份
• 幂等性 — 多次运行此命令均安全无虞
• 记录日志 — 所有变更都会被记录到 ~/.local/share/acfs/doctor.log
• 可逆性 — 每一项修复都附带撤销命令

示例 Dry-Run 输出

DRY-RUN: acfs doctor --fix

将应用以下修复措施：

  [fix.path.ordering]
    操作：将 PATH 目录前置至 ~/.zshrc
    文件：~/.zshrc
    备份：是（已通过 SHA256 校验）

  [fix.acfs.sourcing]
    操作：将 ACFS 源代码添加至 .zshrc
    文件：~/.zshrc
    备份：是（已通过 SHA256 校验）

需要手动操作的修复：
  [shell.ohmyzsh]
    状态：失败
    建议：curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh | bash

总结：2 项自动修复，0 项提示，1 项需手动操作

仅需手动操作的修复

有些操作并不会自动修复，而是提供相关建议：

• 包管理器操作（如 apt install ...）
• 需要 sudo 权限的操作
• 文件删除操作
• 复杂的 shell 配置更改

撤销变更

--fix 执行的所有变更均可撤销：

acfs undo --list      # 列出所有变更
acfs undo chg_0001    # 撤销特定变更
acfs undo --all       # 撤销上一会话中的所有变更

向导网站

向导会引导初学者完成一个13 步旅程，从“我有一台笔记本电脑”到“AI 代理正在为我编写代码”：

┌─────────────────────────────────────────────────────────────────────────────┐
│  ACFS 向导                                                   [第 3 步/13]  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  第 3 步：生成 SSH 密钥                                              │ │
│  │  ──────────────────────────────────────────────────────────────────    │ │
│  │                                                                        │ │
│  │  在终端中运行此命令：                                    │ │
│  │                                                                        │ │
│  │  ┌─────────────────────────────────────────────────────────────────┐  │ │
│  │  │ ssh-keygen -t ed25519 -C "your-email@example.com"         [📋] │  │ │
│  │  └─────────────────────────────────────────────────────────────────┘  │ │
│  │                                                                        │ │
│  │  ☐ 我已运行此命令                                                  │ │
│  │                                                                        │ │
│  │  [← 上一步]                                        [下一步 →]     │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
│  进度：●●●○○○○○○○○○○                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

向导步骤

关键功能

• 操作系统检测：自动识别 Mac 和 Windows，提供针对性的指导方案
• 一键复制：一键复制所有命令
• 进度追踪：在浏览器会话间持久化存储数据
• 确认复选框：对“我已运行此命令”的操作进行确认
• 故障排除：针对常见问题提供扩展式帮助

技术栈

Next.js 16（App Router）
├── React 19
├── Tailwind CSS 4（OKLCH 颜色）
├── shadcn/ui 组件
├── Radix UI 原生组件
└── Lucide 图标

无需后端支持。 所有状态均存储于：

• URL 查询参数
• localStorage（agent-flywheel-user-os、agent-flywheel-vps-ip、agent-flywheel-wizard-completed-steps）

向导状态管理

向导采用 TanStack Query 进行状态管理，支持乐观更新与跨表格同步：

架构：

// 基于查询的状态管理，结合 localStorage 持久化
const { data: steps } = useQuery({
  queryKey: ['wizardSteps', 'completed'],
  queryFn: getCompletedSteps,  // 从 localStorage 中读取数据
  staleTime: 0,                // 始终检查是否有更新
  gcTime: Infinity,            // 从不进行垃圾回收
});

乐观更新与回滚机制：

const mutation = useMutation({
  mutationFn: async (stepId) => {
    const newSteps = addCompletedStep(currentSteps, stepId);
    setCompletedSteps(newSteps);  // 将更新持久化至 localStorage
    return newSteps;
  },
  onMutate: (stepId) => {
    // 立即对缓存进行乐观更新
    const previousSteps = queryClient.getQueryData(queryKey);
    queryClient.setQueryData(queryKey, addCompletedStep(baseSteps, stepId));
    return { previousSteps };  // 用于回滚
  },
  onError: (_err, _stepId, context) => {
    // 失败时执行回滚操作
    queryClient.setQueryData(queryKey, context.previousSteps);
  },
});

跨表格同步： 向导通过两种机制实现浏览器标签页间的同步：

1. 自定义 DOM 事件，用于在组件间实现同标签页的协调。
2. 存储事件，当 localStorage 发生变化时触发跨标签页的更新。

// 同标签页：自定义事件分发
window.dispatchEvent(new CustomEvent('acfs:wizard:completed-steps-changed', {
  detail: { steps }
}));

// 跨标签页：存储事件监听器
window.addEventListener('storage', (event) => {
  if (event.key === COMPLETED_STEPS_KEY) {
    queryClient.setQueryData(queryKey, getCompletedSteps());
  }
});

安全的 localStorage 工具： 所有对 localStorage 的访问都经过安全工具的封装，以应对 SSR、隐私浏览以及配额超限等异常情况：

// 安全读取（任何错误都会返回 null）
export function safeGetJSON<T>(key: string): T | null;

// 安全写入（返回布尔值成功）
export function safeSetJSON(key: string, value: unknown): boolean;

// URL 保留，用于状态回退
export function withCurrentSearch(path: string): string;

该架构确保了向导进度能够持续保存，即使浏览器刷新，也能在不同标签页间正常运行，并在 localStorage 无法使用时优雅地降级。

配置文件

ACFS 会将优化后的配置文件部署到目标 VPS 的 ~/.acfs/ 目录中。

~/.acfs/zsh/acfs.zshrc

一个全面的 zsh 配置文件，由 ~/.zshrc 源文件加载：

Oh-My-Zsh 插件（共 14 个）：

注意：zsh-autosuggestions 和 zsh-syntax-highlighting 是从 GitHub 安装的自定义插件。为了获得最佳性能，它们必须排在最后。

路径配置：

export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"
export PATH="$HOME/.bun/bin:$PATH"
export PATH="$HOME/.atuin/bin:$PATH"

现代 CLI 别名：

alias ls='lsd --inode --long --all'
alias ll='lsd -l'
alias tree='lsd --tree'
alias cat='bat'
alias grep='rg'
alias vim='nvim'
alias lg='lazygit'

工具集成：

# Atuin（更优秀的 shell 历史记录）
eval "$(atuin init zsh)"

# Zoxide（更智能的 cd 命令）
eval "$(zoxide init zsh)"

# direnv（目录环境变量）
eval "$(direnv hook zsh)"

# fzf（模糊查找工具）
source /usr/share/doc/fzf/examples/key-bindings.zsh

Shell 键绑定（提升生活质量）：

Atuin 历史绑定： 该配置强制 Atuin 的绑定在最后加载（在 OMZ 插件之后），确保 Ctrl+R 能触发 Atuin 的模糊历史搜索，而非 zsh 的默认行为：

# 强制置于 zshrc 结尾
bindkey -e  # Emacs 模式
bindkey -M emacs '^R' atuin-search
bindkey -M viins '^R' atuin-search-viins
bindkey -M vicmd '^R' atuin-search-vicmd

~/.acfs/tmux/tmux.conf

一款专为 NTM 和多代理工作流优化的 tmux 配置文件：

键绑定：

前缀：Ctrl+a（不是 Ctrl+b——更符合人体工学）
水平分割：| （保留工作目录）
垂直分割：- （保留工作目录）
导航窗格：h/j/k/l（vim 风格）
调整窗格大小：H/J/K/L（可通过 -r 标志重复调整）
重新加载配置：r
新建窗口：c（保留工作目录）

复制模式（vim 风格）：

进入复制模式：前缀 + [
开始选择：v
矩形选择：r
复制并退出：y

代理工作流优化：

Catppuccin 风格主题：

# 状态栏（位于顶部，更不突兀）
status-style: bg=#1e1e2e, fg=#cdd6f4

# 会话指示器（蓝色点缀）
status-left: #[fg=#89b4fa,bold] #S

# 活跃窗口高亮（粉色点缀）
window-status-current-format: #[fg=#f5c2e7,bold] #I:#W

# 面包边框
面包边框样式：fg=#313244
面包激活边框样式：fg=#89b4fa  # 蓝色高亮

本地覆盖： 如果存在 ~/.tmux.conf.local 配置文件，将自动加载该文件，从而在不修改 ACFS 默认配置的前提下，实现个人化自定义。

库模块

安装程序被组织成模块化的 Bash 库，位于 scripts/lib/ 目录下：

logging.sh

用于彩色控制台输出的实用工具：

log_step "1/8" "正在安装软件包..."  # 蓝色步骤指示器
log_detail "正在安装 zsh..."           # 灰色缩进式详细信息
log_success "安装完成"                    # 绿色对勾
log_warn "可能需要一些时间"              # 黄色警告
log_error "安装失败"                        # 红色错误
log_fatal "无法继续"                      # 红色错误 + 退出 1

security.sh

用于 HTTPS 执行与校验和验证：

enforce_https "$url"                     # 如果不是 HTTPS，则失败
verify_checksum "$url" "$sha256" "$name" # 在执行前进行校验
fetch_and_run "$url" "$sha256" "$name"   # 一次性完成校验与执行

os_detect.sh

用于操作系统检测与验证：

detect_os()      # 设置 OS_ID、OS_VERSION、OS_CODENAME
validate_os()    # 检查是否为 Ubuntu 25.10（或升级路径）
is_fresh_vps()   # 基于启发式算法检测 VPS 是否为最新版本
get_arch()       # 返回 amd64/arm64 架构
is_wsl()         # 检测 WSL
is_docker()      # 检测 Docker 容器

user.sh

用于用户账户的标准化处理：

ensure_user()              # 如果用户不存在，则创建 ubuntu 用户
enable_passwordless_sudo() # 向 sudoers 添加 NOPASSWD 权限
migrate_ssh_keys()         # 将密钥从 root 用户复制到 ubuntu 用户
normalize_user()           # 完整的标准化流程

update.sh

组件更新逻辑，支持版本追踪与日志记录：

update_apt()       # 使用 apt 更新/升级，并添加锁定检测
update_bun()       # 使用 bun 进行版本追踪的升级
update_agents()    # 对 Claude、Codex、Gemini 等工具进行版本更新
update_cloud()     # 对 Wrangler、Supabase、Vercel 等工具进行更新（Supabase 使用经过验证的发布包）
update_rust()      # 使用 rustup 更新稳定版
update_uv()        # 自我更新 uv
update_go()        # 更新 Go 工具链
update_shell()     # 更新 OMZ、P10K、插件、Atuin、Zoxide 等工具
update_stack()     # 更新 Dicklesworthstone 的各类工具

# 功能：
# - 自动将日志记录到 ~/.acfs/logs/updates/
# - 版本追踪（每项工具的前后版本均会记录）
# - apt 锁定检测与预警
# - 内核更新需重启检测
# - 提供 --dry-run 标志的干运行模式

gum_ui.sh

使用 Charmbracelet Gum 实现增强型终端界面：

print_banner()           # ASCII 章节式 ACFS 纪念标语
gum_step/gum_detail      # 样式化输出
gum_success/warn/error   # 多色提示信息
gum_spin                 # 长时间操作时的旋转进度条
gum_confirm              # 是/否提示
gum_choose               # 选择菜单

若未安装 Gum，则回退至基本的 echo 输出方式。

error_tracking.sh

用于高级错误收集与报告：

track_error "阶段" "步骤" "错误信息"
track_warning "阶段" "步骤" "警告信息"
get_error_report                    # 生成结构化的错误报告
get_error_count                     # 统计已跟踪的错误数量
has_errors                          # 判断是否存在任何错误

功能：

• 在不中断执行的情况下收集错误
• 将错误与阶段、步骤上下文关联起来
• 生成运行结束后的汇总报告
• 区分警告与错误

state.sh

用于管理安装进度的状态机（v3 规范）：

state_init                          # 初始化状态文件
state_get_phase                     # 当前阶段
state_set_phase "阶段名称"        # 设置当前阶段
state_mark_complete "阶段名称"    # 标记阶段已完成
state_has_completed "阶段名称"    # 检查阶段是否已完成
state_save                          # 将状态持久化到磁盘（原子操作）
state_load                          # 从磁盘加载状态

状态文件（~/.acfs/state.json）采用原子写入机制，以防止数据损坏。

contract.sh

用于生成脚本的运行时合约验证：

acfs_require_contract "模块 ID"   # 确保环境已就绪
acfs_check_contract                 # 非致命的合约检查

在执行前验证所需环境变量与函数是否已存在：

• TARGET_USER、TARGET_HOME、MODE
• ACFS_BOOTSTRAP_DIR、ACFS_LIB_DIR
• 日志记录相关函数：log_detail、log_success 等。

smoke_test.sh

安装后自动运行的验证测试：

run_smoke_test                      # 执行所有冒烟测试

关键检查（必须通过）：

• 以 ubuntu 用户身份运行
• 启用无密码 sudo
• zsh 作为默认 shell
• 确保核心工具可用（bun、uv、cargo）

非关键检查（仅显示警告）：

• 已配置代理认证
• 已通过云 CLI 认证
• 可选工具已安装

示例输出：

[冒烟测试]
  ✅ 以 ubuntu 用户身份运行
  ✅ 启用无密码 sudo
  ✅ zsh 作为默认 shell
  ✅ bun --version 有效
  ⚠️ Codex 未认证（需运行：codex login）
  ✅ 8/9 项检查通过

session.sh

用于代理会话导出功能，便于共享与回放：

session_export "claude-code" "会话 ID" "/输出路径"
session_list                        # 列出可导出的会话
session_validate "/导出文件.json"

实现了 会话导出 Schema，支持跨代理共享：

interface SessionExport {
  schema_version: 1;
  exported_at: string;              // ISO8601 格式
  session_id: string;
  agent: "claude-code" | "codex" | "gemini";
  model: string;
  summary: string;
  duration_minutes: number;
  stats: {
    turns: number;
    files_created: number;
    files_modified: number;
    commands_run: number;
  };
  outcomes: Array<{
    type: "file_created" | "file_modified" | "command_run";
    path?: string;
    description: string;
  }>;
  key_prompts: string[];            // 学习过程中重要的提示词
  sanitized_transcript: Array<{ role: "用户" | "助手"; content: string; timestamp: string }>;
}

tailscale.sh

用于零配置 VPN 设置，实现安全的远程访问：

install_tailscale                   # 通过官方 APT 仓库安装
verify_tailscale                    # 检查安装是否成功
tailscale_status                    # 获取连接状态

Tailscale 提供以下功能：

• 设备间的 安全网格网络
• 通过 Tailscale 运行 SSH，实现无防火墙访问
• 采用 MagicDNS 实现基于主机名的地址解析
• 支持 ACL 权限控制

安装完成后，运行 tailscale up 以完成认证并加入你的 Tailnet。

ubuntu_upgrade.sh

多重启 Ubuntu 版本升级自动化：

start_ubuntu_upgrade                # 开始升级链
check_upgrade_status                # 检查当前升级状态
resume_upgrade_after_reboot         # 重启后继续升级

负责处理复杂且多步骤的 Ubuntu 升级流程：

1. 检测当前版本
2. 计算升级路径（例如：24.04 → 25.04 → 25.10）
3. 依次执行 do-release-upgrade 操作
4. 安装 systemd 服务，用于重启后恢复升级
5. 在达到目标版本后，继续完成 ACFS 的安装过程

MCP 代理邮件集成

ACFS 集成了 MCP 代理邮件 功能，实现多代理协同工作：

代理邮件的功能

• 身份标识：每个代理都会使用唯一的名称进行注册
• 收件箱/发件箱：基于消息的代理间通信
• 文件预留：通过文件预留机制，防止代理之间互相覆盖或冲突的工作内容
• 可搜索的线程：支持对所有消息进行全文检索
• Git 持久化：将所有工件存储在 Git 中，便于人工审计

核心模式

1. 注册身份

# 在您的代理中调用：
mcp.ensure_project(project_key="/data/projects/my-project")
mcp.register_agent(project_key=..., program="claude-code", model="opus-4.5")

2. 在编辑前预留文件

mcp.file_reservation_paths(
    project_key=...,
    agent_name="BlueLake",
    paths=["src/**"],
    ttl_seconds=3600,
    exclusive=true
)

3. 通信与协作

mcp.send_message(
    project_key=...,
    sender_name="BlueLake",
    to=["GreenCastle"],
    subject="需审核",
    body_md="请审阅权限变更..."
)

提升效率的宏操作

当效率比精细控制更为重要时：

mcp.macro_start_session(...)      # 确保项目、注册及收件箱的同步
mcp.macro_prepare_thread(...)     # 与现有线程保持一致
mcp.macro_file_reservation_cycle(...)  # 进行预留、工作与释放
mcp.macro_contact_handshake(...)  # 请求联系权限

毁灭性命令防护器 (dcg)

dcg 是一款高性能的 Claude Code 插件，能够在危险的 Git 和文件系统命令执行前对其进行拦截。该插件采用 Rust 编写，延迟低至亚毫秒级，能够以机械化的手段严格执行安全规则——而这些规则仅靠指令本身往往难以完全保障。

为什么需要 dcg

2025年12月17日，一名 AI 代理在并行编码会话中，对包含数小时未提交工作的文件执行了 git checkout -- 命令。尽管这些文件通过 git fsck --lost-found 被成功恢复，但这次事件却清晰地表明：《AGENTS.md》中的指令并不能有效阻止命令的执行。dcg 提供了机械化的安全保障。

可被拦截的命令类型

可被允许的命令

安全变体已被列入白名单：

• git checkout -b <branch> — 创建新分支，不修改文件内容
• git restore --staged — 仅取消暂存，不进行丢弃
• git clean -n — 仅预览操作，无需实际执行
• rm -rf /tmp/... — 临时目录为短暂存在

安装方法

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash

Claude Code 配置

在 ~/.claude/settings.json 中添加以下配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "dcg"}]
      }
    ]
  }
}

模块化包系统

dcg 采用模块化包系统，支持扩展功能。您可以在 ~/.config/dcg/config.toml 中启用更多包：

[packs]
enabled = [
    "database.postgresql",
    "containers.docker",
    "kubernetes",
]

可用包包括：database.*、containers.*、kubernetes.*、cloud.*、infrastructure.*、system.*、package_managers。

仓库更新器 (ru)

ru 是一款生产级 CLI 工具，用于同步 GitHub 仓库集合，并借助 AI 助手自动完成脏仓库的提交工作流。

核心功能

• 多仓库同步：克隆缺失的仓库，拉取更新，检测冲突
• 代理扫面：通过 AI 驱动的提交自动化，针对存在未提交更改的仓库进行操作
• AI 代码审查：为开放问题/PR 组织 Claude Code 审查会话
• 工作窃取队列：通过负载均衡的 Worker 实现并行执行
• NTM 集成：通过 Named Tmux Manager 管理会话

快速入门

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash

初始化配置：

# 初始化配置
ru init --example

# 同步所有仓库
ru sync

# 检查状态，无需任何更改
ru status

代理扫面工作流

agent-sweep 命令可自动化处理脏仓库中的提交：

# 预览待处理的仓库
ru agent-sweep --dry-run

# 全面自动化，结合 AI 助力
ru agent-sweep --parallel 4

# 包含发布自动化
ru agent-sweep --with-release

三阶段工作流：

1. 规划：Claude Code 分析变更，生成提交信息
2. 提交：验证计划，对文件进行暂存，运行质量门限
3. 发布：（可选）创建版本标签，并发布到 GitHub

配置说明

# ~/.config/ru/config
PROJECTS_DIR=/data/projects
LAYOUT=flat                   # flat|owner-repo|full
UPDATE_STRATEGY=ff-only       # ff-only|rebase|merge
PARALLEL=4

仓库列表格式（~/.config/ru/repos.d/public.txt）：

owner/repo
owner/repo@develop            # 保留到分支
owner/repo as custom-name     # 自定义目录名

从网络链接获取图片 (giil)

giil 会从云端照片共享平台下载全分辨率图片至终端。对于需要在 SSH 会话中分析截图的远程调试工作流而言，这是一款不可或缺的工具。

支持平台

使用方法

# 基础下载
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"
# 输出：/current/dir/icloud_20240115_143245.jpg

# 下载至特定目录
giil "..." --output ~/Downloads

# 获取 JSON 元数据
giil "..." --json

# 下载相册中的全部照片
giil "..." --all --output ~/album

安装方法

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

可视化调试工作流程

1. 在 iPhone 上截取 UI 错误的截图
2. 等待 iCloud 同步至 Mac
3. 通过 Photos.app 共享截图 → 复制 iCloud 链接
4. 将链接粘贴到运行 Claude Code 的远程终端中
5. giil 会将图片本地获取
6. AI 助手对截图进行分析

聊天共享对话转为文件（csctf）

csctf 可将公开的 AI 对话共享链接转换为整洁、可搜索的 Markdown 和 HTML 文本。非常适合用于归档 AI 对话、构建知识库，以及与团队分享。

支持的提供商

使用方法

# 基础转换
csctf https://chatgpt.com/share/69343092-91ac-800b-996c-7552461b9b70
# 生成：<slug>.md 和 <slug>.html

# 仅生成 Markdown
csctf "..." --md-only

# 发布至 GitHub Pages
csctf "..." --publish-to-gh-pages --yes

# JSON 元数据输出
csctf "..." --json

安装

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/chat_shared_conversation_to_file/main/install.sh | bash

输出功能

• Markdown：采用整洁的格式，保留代码块和语言提示。
• HTML：无 JavaScript 的静态页面，支持语法高亮。
• 确定性文件名：使用 <slug>_YYYYMMDD.md，确保归档的可靠性。
• 冲突处理：自动递增后缀，避免覆盖。

CI/CD

ACFS 采用 GitHub Actions 进行持续集成：

安装程序测试 (installer.yml)

# 每次推送和 PR 都会运行
jobs:
  shellcheck:
    - 使用 ShellCheck 对所有 Bash 脚本进行 lint 检查

  integration:
    - 在 Ubuntu 24.04、25.04、25.10 上运行矩阵测试
    - 在 Docker 中完成完整安装
    - 验证所有工具是否正确安装
    - 运行 acfs doctor，确认系统健康状态

这确保了安装程序可在所有受支持的 Ubuntu 版本上正常运行，并及早发现 Shell 脚本中的问题。

### 网站部署 (`website.yml`)

```yaml
# 构建并部署 Next.js 向导
jobs:
  build:
    - 对 TypeScript 进行类型检查
    - 运行 ESLint
    - 构建生产版本的 Bundle

  deploy:
    - 部署至 Vercel（生产环境）

自动校验和 + 异常修复 (checksum-monitor.yml)

ACFS 会自动监控上游安装程序的变更，并针对生成的工件校验和偏差进行修复：

# 每 2 小时运行一次，且在上游变更时触发
schedule: "0 */2 * * *"
triggers:
  - 按计划定时运行（每 2 小时）
  - 从上游仓库发送 Webhook（repository_dispatch）
  - 接收涉及安装程序/校验和/生成器文件的推送

**工作原理：**

1. **检测生成工件的偏差**：运行 `scripts/check-manifest-drift.sh --json`，以检测：
   - `ACFS_MANIFEST_SHA256` 不匹配
   - 内部脚本校验和偏差（`scripts/generated/internal_checksums.sh`）
2. **自动修复偏差**：若检测到偏差，执行 `--fix`（重新生成、提交并推送）
3. **验证当前上游校验和**：下载所有上游安装程序，计算 SHA256 校验值
4. **检测上游变更**：与 `checksums.yaml` 进行比对
5. **分类工具**：将“可信”工具（可自动更新）与其他工具区分开来
6. **自动更新上游校验和**：在安全的情况下，将更新后的 `checksums.yaml` 提交
7. **提醒**：对于非可信工具的变更，会创建 GitHub 问题，供人工审核。

当校验返回获取错误或出现跳过条目时，监控会**关闭并标记为已解决**；但不会发出部分或占位式的校验和更新。

**可信工具（已启用自动更新）：**
- Dicklesworthstone 堆栈工具（ntm、cass、cm、ubs、slb、dcg、caam、bv、agent-mail、ru）
- 这些工具由同一作者维护，因此上游变更被默认视为可信。

**非可信工具（需人工审核）：**
- 第三方安装程序（bun、uv、rust、oh-my-zsh、atuin、zoxide、nvm）
- 若有变更，会触发 GitHub 问题，并附带详细差异信息供人工审核。

这确保了：
- **安全性**：第三方变更在部署前经过审核
- **效率**：内部工具更新可自动部署
- **可审计性**：所有变更均可通过 Git 提交记录追踪

**上游仓库调度（快速路径）：**
- ACFS 所属的工具仓库会在其 `install.sh` 文件发生变更或发布新版本时，触发 `repository_dispatch` 事件。
- 每个工具仓库都需要配置一个名为 `ACFS_REPO_DISPATCH_TOKEN` 的 PAT 密钥（该组织/用户专属的仓库范围）。
- 若调度失败，按计划运行的监控器仍能检测到偏差（不过速度会稍慢）。

### 生产烟雾测试 (`production-smoke.yml`)

验证部署至真实环境：

```yaml
# 在部署后运行
jobs:
  smoke:
    - 从生产 URL 获取 install.sh
    - 验证校验和是否与仓库一致
    - 检查 Shell 语法
    - 确认没有未提交的偏差

安装程序 Canary（Docker）(installer-canary.yml)

每天定时运行完整的安装程序端到端测试，运行于全新的 Ubuntu 容器中。

schedule: "30 7 * * *" # 每天运行
jobs:
  canary:
    - 运行 tests/vm/test_install_ubuntu.sh（Vibe 模式）
    - 使用 ACFS_CHECKSUMS_REF=main，获取最新哈希值

Playwright E2E 测试 (playwright.yml)

对向导网站进行全面的浏览器测试：

# 在 PR 到主分支上运行
browsers:
  - Chromium
  - Firefox
  - WebKit
  - Mobile Chrome
  - Mobile Safari

tests:
  - 检查向导流程的完成情况
  - 测试步骤导航
  - 检查复制按钮的功能
  - 确保响应式设计

VPS 提供商

ACFS 可在任何配备 SSH 密钥登录的 Ubuntu VPS 上运行。以下是针对多代理工作负载优化的推荐提供商。

为什么需要 48–64GB RAM？ 每个 AI 编程代理大约需要 2GB RAM。若要同时运行 10–20 个以上的代理，至少需要 48GB 以上的内存。切勿因节省 20美元的托管费用而让价值 400+ 美元/月的 AI 投资陷入瓶颈。

Contabo（性价比之选——首选）

• 市场上性价比最高
• 按月计费，无需承诺期限
• 美国数据中心定价包含约 10 美元/月的额外溢价

OVH（绝佳替代方案）

• 包含 Anti-DDoS 服务
• 按月计费，长期承诺可享受 5–15% 的折扣
• 启用速度通常比 Contabo 更快

要求

其他提供商

任何拥有 Ubuntu VPS 且可使用 SSH 密钥登录的提供商均可正常运行。agent-flywheel.com 提供的向导均附有分步指南。

提供商设置指南

ACFS 在 scripts/providers/ 目录下为每家支持的提供商提供了详尽的分步指南：

每份指南都包含：

• 每一步的截图（位于 scripts/providers/screenshots/ 中）
• 带有推荐方案的详细定价说明
• 区域选择指南（考虑延迟和隐私问题）
• 专属于该提供商的 SSH 密钥配置
• 针对常见部署问题的故障排查指南

提供商对比：

推荐流程：

1. 预算：Contabo（每美元能获得最佳配置）
2. 速度：Hetzner（即时部署）
3. 支持：OVH（提供电话客服支持）
4. 隐私：任意欧盟提供商（符合 GDPR 法规）

项目结构

agentic_coding_flywheel_setup/
├── README.md                     # 本文件
├── AGENTS.md                     # 开发指南
├── VERSION                       # 当前版本（0.2.0）
├── install.sh                    # 主安装程序入口点
├── acfs.manifest.yaml            # 标准工具清单（共 510 行）
├── checksums.yaml                # 上游脚本的 SHA256 哈希值
├── package.json                  # 根级单体仓库配置
│
├── apps/
│   └── web/                      # Next.js 16 向导网站
│       ├── app/                  # 应用路由器页面
│       │   ├── layout.tsx        # 根布局
│       │   ├── page.tsx          # 登陆页
│       │   └── wizard/           # 向导步骤页面
│       ├── components/           # UI 组件
│       └── lib/                  # 工具库
│
├── packages/
│   ├── manifest/                 # 清单解析器 + 生成器
│   │   └── src/
│   │       ├── parser.ts         # YAML 解析
│   │       ├── schema.ts         # Zod 验证模式
│   │       ├── types.ts          # TypeScript 类型
│   │       ├── utils.ts          # 辅助函数
│   │       └── generate.ts       # 脚本生成器
│   ├── installer/                # 安装程序辅助脚本
│   └── onboard/                  # 操作员界面源代码
│
├── acfs/                         # 部署至 ~/.acfs 的文件
│   ├── zsh/
│   │   └── acfs.zshrc            # Shell 配置
│   ├── tmux/
│   │   └── tmux.conf             # Tmux 配置
│   └── onboard/
│       ├── onboard.sh            # 操作员界面脚本
│       └── lessons/              # 教程 Markdown 文件（共 11 个文件）
│
├── scripts/
│   ├── lib/                      # 安装程序 Bash 库
│   │   ├── logging.sh            # 控制台输出
│   │   ├── security.sh           # HTTPS + 哈希校验
│   │   ├── os_detect.sh          # 操作系统检测
│   │   ├── user.sh               # 用户管理
│   │   ├── zsh.sh                # Shell 设置
│   │   ├── update.sh             # 更新命令逻辑
│   │   ├── gum_ui.sh             # 增强型用户界面
│   │   ├── cli_tools.sh          # 工具安装
│   │   └── doctor.sh             # 健康检查
│   ├── generated/                # 自动从清单生成
│   │   ├── install_base.sh       # 基础软件包
│   │   ├── install_shell.sh      # Shell 工具
│   │   ├── install_cli.sh        # CLI 工具
│   │   ├── install_lang.sh       # 语言运行时
│   │   ├── install_agents.sh     # AI 编码代理
│   │   ├── install_cloud.sh      # 云 CLI
│   │   ├── install_stack.sh      # Dicklesworthstone 堆栈
│   │   ├── install_all.sh        # 主安装程序
│   │   └── doctor_checks.sh      # 验证检查
│   ├── providers/                # VPS 提供商指南
│   │   ├── ovh.md
│   │   ├── contabo.md
│   │   └── hetzner.md
│   └── sync/
│       └── sync_ntm_palette.sh   # 同步 NTM 命令面板
│
├── .github/
│   └── workflows/
│       ├── installer.yml         # ShellCheck + Ubuntu 矩阵测试
│       └── website.yml           # Next.js 构建 + 部署
│
└── tests/
    └── vm/
        └── test_install_ubuntu.sh # Docker 集成测试

开发

网站开发

cd apps/web
bun install           # 安装依赖
bun run dev           # 开发服务器，地址为 http://localhost:3000
bun run build         # 生产环境构建
bun run lint          # 代码检查
bun run type-check    # TypeScript 检查

清单开发

cd packages/manifest
bun install           # 安装依赖
bun run generate      # 生成安装程序脚本
bun run generate:dry  # 预览，无需写入文件

安装程序测试

# 本地代码检查
shellcheck install.sh scripts/lib/*.sh

# 全面的安装程序集成测试（Docker，与 CI 一致）
./tests/vm/test_install_ubuntu.sh

安全验证

# 打印所有上游 URL
./scripts/lib/security.sh --print

# 校验所有哈希值
./scripts/lib/security.sh --verify

# 在审查上游变更后更新哈希值
./scripts/lib/security.sh --update-checksums > checksums.yaml

清单验证

清单解析器不仅进行基本的 Schema 校验，还具备全面的验证功能：

验证错误代码：

运行验证：

cd packages/manifest
bun run validate              # 全面验证
bun run validate --verbose    # 显示所有检查结果

循环检测算法：

Tarjan 强连通分量（SCC）：
1. 使用 DFS 进行发现与低链跟踪
2. 找出规模大于 1 的 SCC，将其视为循环
3. 为人工调试生成循环路径

测试框架

ACFS 提供了全面的测试框架（tests/vm/lib/test_harness.sh），用于集成测试：

# 加载测试框架
source tests/vm/lib/test_harness.sh

# 初始化测试套件
harness_init "ACFS 安装测试"

# 创建测试模块
harness_section "阶段 1：基础软件包"

# 使用自动日志记录运行命令
harness_run "安装 curl" apt install -y curl

# 验证结果
harness_pass "curl 安装成功"
harness_fail "curl 安装失败"
harness_skip "跳过可选测试"

# 生成总结
harness_summary # 输出：15 个通过，0 个失败，2 个被跳过

测试文件：

运行测试：

# 全面的 Docker 集成测试
./tests/vm/test_install_ubuntu.sh

# 选择逻辑测试
./tests/vm/selection_checks.sh

# Web 端到端测试
./tests/web/run_e2e.sh

同步脚本

同步脚本确保 ACFS 文档与上游项目保持一致：

# 从上游同步 NTM 命令调色板
./scripts/sync/sync_ntm_palette.sh

# 检查是否有可用更新（无需下载）
./scripts/sync/sync_ntm_palette.sh --check

当前同步源：

所有同步脚本均使用安全库进行 HTTPS 执行和内容哈希处理。

网站设计系统

网站采用一套完整的设计系统（apps/web/lib/design-tokens.ts）：

颜色令牌（OKLCH 色彩空间）：

// 以感知统一的方式呈现色彩
colors: {
  cyan:    "oklch(0.75 0.18 195)",   // 主要强调色
  pink:    "oklch(0.7 0.2 330)",     // 辅助强调色
  purple:  "oklch(0.65 0.18 290)",   // 三级强调色
  success: "oklch(0.72 0.19 145)",   // 绿色
  warning: "oklch(0.78 0.16 75)",    // 黄色
  error:   "oklch(0.65 0.22 25)",    // 红色
}

阴影令牌：

shadows: {
  cardHover: "0 20px 40px -12px oklch(0.75 0.18 195 / 0.15)",
  cardLifted: "0 25px 50px -12px oklch(0.75 0.18 195 / 0.2)",
  primaryGlow: "0 0 40px -8px oklch(0.75 0.18 195 / 0.3)",
}

动画预设：

animations: {
  hover: { scale: 1.02, transition: { duration: 0.2 } },
  tap: { scale: 0.98 },
  fadeIn: { opacity: [0, 1], transition: { duration: 0.3 } },
}

无障碍支持：

• 通过 useReducedMotion 钩子减少运动支持
• 语义化 HTML 结构
• 在交互元素上添加 ARIA 标签
• 提供键盘导航支持

需求

• 运行时环境： Bun（而非 npm/yarn/pnpm）
• Node 版本： 最新版本
• Shell： Bash 5+

常见问题解答

为什么是“Vibe 模式”？

Vibe 模式专为那些对速度更为看重、而对安全性要求相对较低的 一次性 VPS 环境 设计：

• 无密码 sudo 可以大幅减少操作步骤中的摩擦
• 代理危险标志会跳过确认对话框
• 预配置的别名能够最大限度地提升运行速度

切勿在生产环境或共享系统中使用 Vibe 模式。

我可以在本地机器上使用吗？

ACFS 专为全新的 Ubuntu VPS 实例设计。虽然您可以在本地运行它：

• 它可能会与现有配置产生冲突
• 它默认需要 root 或 sudo 权限
• 它并非专为 macOS 或 Windows 设计

若需本地开发，请直接使用独立的工具。

如果安装程序失败了怎么办？

安装程序已进行了 断点续传 处理。只需重新运行即可：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

它会跳过已完成的阶段，并从上次中断处继续执行。

如何更新工具？

使用内置的更新命令：

acfs update                  # 更新所有标准组件
acfs update --stack          # 包含 Dicklesworthstone 堆栈
acfs update --agents-only    # 仅更新 AI 代理

如何卸载？

没有专门的卸载脚本。要重置环境：

1. 删除 VPS 实例
2. 创建一个新的实例
3. 重新运行安装程序

这是有意为之——ACFS 专为临时的 VPS 环境而设计。

我可以自定义安装哪些工具吗？

目前，ACFS 会安装全套工具。未来版本将支持：

• 基于清单的工具选择
• 交互式模式，方便用户自由选择组件
• 模块化安装脚本

为什么有 ACFS？

问题所在：Agentic 编程的壁垒

AI 编程代理（如 Claude Code、Codex CLI、Gemini CLI）的兴起，为软件开发带来了全新的范式。这些代理不仅能编写代码、调试问题，甚至还能构建解决方案——但前提是它们必须拥有合适的运行环境。

问题的根源并不在于代理本身。 而是创建一个能让代理真正高效工作的环境，往往需要耗费数小时的配置时间：

┌────────────────────────────────────────────────────────────────────────────┐
│  未使用 ACFS 的时间投入                                               │
│                                                                              │
│  VPS 配置 ..................... 30–60 分钟                                   │
│  Shell 配置 ........... 20–30 分钟                                   │
│  语言运行时 ............. 30–45 分钟                                   │
│  开发工具 ........... 20–30 分钟                                   │
│  代理安装 ............ 15–30 分钟                                   │
│  代理配置 ........... 20–40 分钟                                   │
│  协调工具 ............ 30–60 分钟                                   │
│  故障排除 ............... 30–120 分钟                                  │
│  ─────────────────────────────────────────                                   │
│  总计：3–7 小时（且前提是所有环节都顺利进行）                          │
│                                                                              │
│  使用 ACFS 的时间投入                                               │
│                                                                              │
│  运行一条命令 ............... 25–30 分钟                                   │
│  ─────────────────────────────────────────                                   │
│  总计：30 分钟                                                           │
└────────────────────────────────────────────────────────────────────────────┘

ACFS 完全消除了这一障碍。 只需一条命令，30 分钟即可完成全部配置。

更深层次的问题：初学者无从下手

对于有经验的开发者来说，这一套设置虽然繁琐，但完全可行。然而，对于初学者——那些最需要AI编程辅助的人群而言，这却是一道难以逾越的障碍：

• 什么是SSH？我该如何生成密钥？
• 什么是VPS？我该如何租用一台？
• 终端是什么？我该使用哪一个？
• 如何连接到远程服务器？
• 这些工具究竟是什么？为什么我需要它们？

agent-flywheel.com 的向导式网站通过以下方式解决了这一难题：

1. 为初学者提供绝对清晰的指导——用通俗易懂的语言讲解每一个概念。
2. 针对不同操作系统提供详细说明——自动识别是Mac还是Windows，并显示正确的命令。
3. 直观的可视化操作——每一步都配有复选框，命令操作则附带复制按钮。
4. 提供故障排查与解决方案——针对常见问题，专门设置了可扩展的章节。
5. 持续记录进度——在浏览器会话中，能够从上次中断处继续进行操作。

10倍的乘数效应

ACFS 不仅仅是一组工具的集合，而是一个经过精心设计的系统——每个组件都能相互放大、彼此赋能。其价值并非简单的相加，而是呈指数级增长。

工具协同模型

                              ┌─────────────────┐
                              │   生产力  │
                              │   乘数  │
                              └────────┬────────┘
                                       │
         ┌─────────────────────────────┼─────────────────────────────┐
         │                             │                             │
         ▼                             ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  环境层    │         │    代理层       │         │  协调层   │
│  层次      │         │    层次        │         │  层次      │
├─────────────────┤         ├─────────────────┤         ├─────────────────┤
│ • zsh + p10k    │────────▶│ • Claude Code   │────────▶│ • 代理邮件   │
│ • tmux          │         │ • Codex CLI     │         │ • NTM           │
│ • 现代 CLI    │         │ • Gemini CLI    │         │ • SLB + DCG     │
│ • 语言虚拟机  │         │                 │         │ • Beads 查看器  │
└─────────────────┘         └─────────────────┘         └─────────────────┘
         │                             │                             │
         │    每一层都让彼此得以            │    代理们得以更高效地                │
         │    相互协作，共同提升能力        │    联合发力，成就更大价值        │
         └─────────────────────────────┴─────────────────────────────┘

为何选择这些特定的工具？

ACFS 中的每一款工具，都是凭借其实实在在的生产力提升而脱颖而出的：

复合效应的奇妙之处

只需一名具备基础工具的代理，便已足够实用。而当三名代理协同工作时：

• 共享统一的项目结构
• 通过代理邮件实现协调
• 通过 NTM 实现流程优化
• 通过 SLB 设置安全防护机制
• 通过 DCG 防止危险命令的误执行
• 通过 Beads 提供任务视图，让代理们随时了解项目状态，避免重复劳动

……在短短一天内，就能完成一位独立开发者一周才能完成的工作。

小贴士：运行 acfs services-setup 来配置登录信息，并启用 DCG 以保护危险命令。

这就是飞轮效应的生动体现：更好的工具 → 更强大的代理 → 更多代码被交付 → 对工具需求的理解更加深入 → 更好的工具。

设计算法与决策

ACFS 采用了多种算法模式，确保系统的可靠性与可维护性。

幂等性算法

每项安装功能都遵循“先检查再安装”的原则：

install_tool() {
    if command_exists "tool"; then
        log_success "工具已安装"
        return 0
    fi

    # ... 安装逻辑 ...

    if command_exists "tool"; then
        log_success "工具安装成功"
        return 0
    else
        log_error "工具安装失败"
        return 1
    fi
}

这一设计保证了：

1. 安全的重试机制——两次运行安装程序并不会导致任何问题。
2. 恢复能力——即使出现失败，也不必从头开始。
3. 声明式的意图表达——最终状态被明确界定，而非仅停留在过渡阶段。

校验和验证算法

安全系统采用内容寻址校验的方式：

┌─────────────────────────────────────────────────────────────────────────┐
│  校验流程                                                       │
│                                                                          │
│  1. 将脚本下载至内存（而非磁盘）                               │
│  2. 计算下载内容的 SHA256 校验值                               │
│  3. 与校验和文件中的存储哈希值进行对比                           │
│  4. 若校验一致 → 执行                                                   │
│  5. 若不一致 → 拒绝执行，并报告差异                           │
│                                                                          │
│  关键洞察：我们只对内容进行校验，而非单纯依赖传输过程              │
│  （HTTPS 只能保护通信通道，无法保护源端的内容）                │
└─────────────────────────────────────────────────────────────────────────┘

指标驱动的生成

生成器采用模板扩展的模式：

1. 解析——读取 YAML 清单，并使用 Zod 模式进行验证。
2. 转换——将清单条目转化为安装函数。
3. 分类——按类别进行整理（基础、Shell、CLI、语言、代理等）。
4. 生成——输出结构一致的 Bash 脚本。
5. 验证——通过校验命令生成完善的校验检查。

这一设计确保了清单成为唯一的真实来源——文档、安装程序与校验结果之间不存在偏差。

代码生成器架构

manifest 生成器（packages/manifest/src/generate.ts）是一个高度复杂的 TypeScript 程序，能够将 YAML 转换为 Bash：

输入处理：

// 1. 解析 YAML 并进行验证
const manifest = parseManifestFile(MANIFEST_PATH);  // 使用 Zod 进行验证

// 2. 加载用于验证安装程序的校验和
const checksums = parseYaml(readFileSync(CHECKSUMS_PATH));

// 3. 对依赖关系进行拓扑排序
const sorted = sortModulesByInstallOrder(manifest.modules);

以安全为先的代码生成：

// 实现 Shell 安全的引号处理（防止命令注入）
function shellQuote(s: string): string {
  return `'${s.replace(/'/g, "'\\''")}'`;
}

// 仅允许指定的运行器（严格管控）
const ALLOWED_RUNNERS = ['bash', 'sh'] as const;

// 构建经过验证的安装程序管道
function buildVerifiedInstallerPipe(module: Module, checksums: Checksums): string {
  // 生成的命令：curl -fsSL "$URL" | verify_checksum "$SHA256" | bash
}

输出结构：

scripts/generated/
├── install_base.sh        # 基础系统软件包（apt）
├── install_users.sh       # 用户规范化（Ubuntu 用户）
├── install_filesystem.sh  # 目录结构（/data/projects）
├── install_shell.sh       # zsh + oh-my-zsh + p10k
├── install_cli.sh         # ripgrep、tmux、fzf、lazygit 等
├── install_network.sh     # Tailscale
├── install_lang.sh        # bun、uv、rust、go
├── install_tools.sh       # ast-grep、atuin、zoxide
├── install_agents.sh      # claude、codex、gemini
├── install_db.sh          # PostgreSQL 18、Vault
├── install_cloud.sh       # wrangler、supabase、vercel
├── install_stack.sh       # Dicklesworthstone 10 工具栈 + 实用工具
├── install_acfs.sh        # ACFS 配置部署
├── install_all.sh         # 组织化辅助工具
├── doctor_checks.sh       # 健康检查
└── manifest_index.sh      # 模块元数据数组

生成脚本结构：

#!/usr/bin/env bash
# 自动从 acfs.manifest.yaml 生成 - 请勿编辑

install_module_id() {
    acfs_require_contract "module.id"  # 验证环境

    if run_installed_check "module.id"; then
        log_step "module.id 已经安装"
        return 0
    fi

    set_phase "安装模块..."
    run_as_target_shell <<'HEREDOC'
        # 从 manifest 中获取的安装命令
    HEREDOC

    verify_module "module.id"  # 安装后检查
}

重新生成：

cd packages/manifest
bun run generate           # 全面重新生成
bun run generate:dry       # 预览，不进行写入

生成的 Manifest 索引

生成器会生成 manifest_index.sh，这是一个全面的 Bash 元数据文件，可在运行时通过编程方式访问 manifest 数据：

关联数组：

# 模块元数据查询
declare -A ACFS_MODULE_DESCRIPTION
ACFS_MODULE_DESCRIPTION["lang.bun"]="Bun JavaScript/TypeScript 运行时..."

ACFS_MODULE_DESCRIPTION["agents.claude"]="Claude 代码 CLI 代理..."

# 阶段映射（决定安装顺序）
declare -A ACFS_MODULE_PHASE
ACFS_MODULE_PHASE["base.apt"]="1"
ACFS_MODULE_PHASE["lang.bun"]="3"
ACFS_MODULE_PHASE["agents.claude"]="5"

# 依赖关系（以空格分隔）
declare -A ACFS_MODULE_DEPENDENCIES
ACFS_MODULE_DEPENDENCIES["agents.claude"]="lang.bun base.system"

# 生成的函数名映射
declare -A ACFS_MODULE_FUNCTION
ACFS_MODULE_FUNCTION["lang.bun"]="install_lang_bun"

# 类别分组
declare -A ACFS_MODULE_CATEGORY
ACFS_MODULE_CATEGORY["lang.bun"]="lang"

# 默认包含在安装中
declare -A ACFS_MODULE_DEFAULT
ACFS_MODULE_DEFAULT["lang.bun"]="true"
ACFS_MODULE_DEFAULT["db.postgres18"]="true"

运行时查询函数：

# 获取某个类别的所有模块
get_modules_by_category "agents"  # 返回：agents.claude agents.codex agents.gemini

# 检查模块是否为默认安装
is_default_module "tools.vault"   # 返回：true

# 获取安装阶段
get_module_phase "stack.ntm"      # 返回：6

使用场景：

• acfs doctor 查询模块元数据，进行健康检查
• install.sh --list-modules 显示可用的模块
• --skip <module> 在跳过模块前验证其是否存在
• --only-phase <n> 通过阶段映射实现选择性安装

该 Manifest 索引将 TypeScript 生成器与 Bash 运行时无缝衔接，既实现了复杂的模块选择逻辑，又保持了 Bash 脚本的简洁性。

向导中的渐进式披露

向导网站采用 渐进式披露 的方式来管理复杂度：

级别 1：核心指令（默认可见）
├── 复制此命令
├── 将其粘贴到终端
└── 按下回车键

级别 2：故障排查（可展开）
├── “权限被拒绝” → 修复说明
├── “命令未找到” → 前提条件
└── “连接被拒绝” → 诊断步骤

级别 3：深入解析（可折叠的“新手指南”）
├── 什么是 SSH？
├── 什么是 VPS？
├── 为什么选择这些特定步骤？
└── 事情的幕后究竟如何运作？

这样，初学者在需要时可以获取深度背景信息，而专家则可以直接跳转到具体的命令操作。

多代理编排模型

ACFS 专为 多代理工作流 而设计，允许多个 AI 编码代理同时协作完成同一个项目。

协调问题

若缺乏协调，多个代理将导致混乱：

• 文件冲突 — 两个代理同时编辑同一文件
• 重复工作 — 各个代理独立解决相同的问题
• 沟通鸿沟 — 无法实时了解其他代理的进展
• 安全隐患 — 在缺乏监督的情况下执行危险操作

简化后的中文：

ACFS 解决方案堆栈

┌───────────────────────────────────────────────────────────────────────────┐
│                         代理协调层                           │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ 代理邮件  │  │    NTM      │  │  SLB + DCG  │  │   Beads     │       │
│  │ (消息传递) │  │ (会话)    │  │ (安全)    │  │ (任务)    │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
│         │                │                │                │               │
│         │   ┌────────────┴────────────────┴────────────────┘               │
│         │   │                                                              │
│         ▼   ▼                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │                      文件预留系统                          │ │
│  │                                                                        │ │
│  │  代理 A 预留：src/auth/**                                         │ │
│  │  代理 B 预留：src/api/**                                          │ │
│  │  代理 C 预留：tests/**                                            │ │
│  │                                                                        │ │
│  │  →  没有冲突，可并行推进                                     │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘

代理通信模式

1. 直接消息（代理邮件）

代理 A → 代理 B：“我已完成 auth 模块，已准备好进行 API 集成”
代理 B → 代理 A：“确认，开始与 auth 依赖进行 API 集成”

2. 广播更新（线程摘要）

线程：“Sprint 23 任务”
├── 代理 A：“已申请用户注册功能”
├── 代理 B：“已申请 API 端点功能”
├── 代理 C：“已申请测试覆盖率任务”
└── 所有代理均可查看项目状态

3. 文件预留（冲突预防）

代理 A：预留路径[“src/auth/*”]，采用独占模式，有效期为 3600 秒
代理 B：预留路径[“src/auth/*”] → 冲突：已被代理 A 占用
代理 B：预留路径[“src/api/*”] → 获得许可

NTM 编排模式

命名的 Tmux 管理器（NTM）实现了 单命令式群集启动：

# 启动 10 个代理，每个代理运行在命名的 tmux 窗口内
ntm spawn \
  --count 10 \
  --prefix "agent-" \
  --command "claude --dangerously-skip-permissions"

结果：

tmux 会话：acfs-swarm
├── agent-1：Claude 正在处理 auth
├── agent-2：Claude 正在处理 api
├── agent-3：Claude 正在处理 tests
├── agent-4：Codex 正在审阅 PR
├── agent-5：Gemini 正在撰写文档
└── ...

哲学

飞轮效应

“代理编码飞轮”是一个良性循环：

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│    更好的环境 → 更高的代理生产力 →               │
│    更多代码编写 → 更好的理解 →                   │
│    更好的提示 → 更好的环境                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

ACFS 通过提供最佳的初始环境来启动这一飞轮，助力代理编码。

设计原则

1. 初学者友好，专家高效：向导引导初学者；单行命令则适合专家使用。

2. 以氛围为核心：在快速迭代的环境中优化效率。安全特性默认启用，且处于安全模式下。

3. 幂等性：无需担心重复执行。安装程序会优雅地处理已安装的工具。

4. 单一真相来源：清单定义了所有内容。安装脚本正是基于此清单生成的。

5. 默认安全：支持 HTTPS 加密、校验和验证，杜绝盲目的 curl | bash。

6. 现代默认配置：最新版本、现代化工具、开箱即用的最佳配置。

Vibe 编码宣言

“Vibe 编码”不仅仅是一个朗朗上口的名字——它是一种关于人类与 AI 如何协同开展软件开发的理念。

什么是 Vibe 编码？

Vibe 编码是指将 AI 代理引导去编写代码，而你专注于意图、架构和质量。与其自己逐行输入代码，不如：

1. 用自然语言描述你的需求
2. 审核并指导 代理的输出
3. 通过多种方案快速迭代
4. 更快交付，同时保持高质量

“Vibe”源自你进入的一种心流状态：不再纠结于语法、样板代码或实现细节——你只是与你的 AI 合作伙伴一同“心流”运转。

Vibe 编码的三条法则

1. 速度优先，而非仪式感

传统开发流程往往充斥着繁琐的仪式：创建分支、先写测试、实现、重构、写文档、创建 PR、等待评审、合并、部署。每一步都充满摩擦。

Vibe 编码则颠覆了这一模式：快速交付，更快速地迭代。AI 处理样板代码，而你只需专注于那 10% 需要人类判断的部分。

传统方式：思考 → 计划 → 实现 → 测试 → 文档 → 发布
Vibe 方式：描述 → 生成 → 核实 → 发布 → 迭代

2. 临时环境激发大胆尝试

Vibe 编码的魔力诞生于临时的 VPS 实例中。当你的环境是“一次性”的：

• 你可以毫无顾虑地进行实验
• 灾难性故障只需“重新搭建 VPS”
• 代理可以拥有危险权限（但它们无法破坏那些“一次性”的东西）
• 你专注于输出，而非保护你的环境

这就是为什么 ACFS 的“Vibe 模式”允许无密码 sudo 和危险的代理标志——在每月仅需 5 美元的临时 VPS 上，根本无需担心任何需要保护的内容。

3. 多代理是默认选择

一个代理固然有用，但三个代理并行工作则更具变革性。

Vibe 编码假设你会同时运行多个代理：

• Claude 用于复杂推理与架构设计
• Codex 用于快速原型设计与重构
• Gemini 用于文档撰写与研究

ACFS 提供了协调层（代理邮件、NTM、SLB），让这一切成为现实。

反面案例

Vibe 编码绝不是：

• 盲目接受代理输出而不加审核
• 放弃测试与质量标准
• 忽视生产系统的安全性
• 将代理视为替代人类判断的工具

我们的目标是增强人类判断能力，而非完全放弃人类判断。

何时不应使用 Vibe 编码

• 面向真实用户的生产系统
• 对安全性要求极高的基础设施
• 任何涉及凭证或机密信息的场景
• 长期运行的服务器（请启用安全模式）
• 共享团队环境（请使用协作工具）

Vibe 编码适用于全新项目开发、原型设计、实验研究以及学习实践。其他所有场景均建议使用 ACFS 的安全模式。

状态机与检查点机制

ACFS 实现了一套强大的基于检查点的状态机，能够确保在发生故障时实现可靠的恢复与继续执行。本节将为您详细讲解其工作原理及底层实现细节。

状态文件格式

进度信息存储于 ~/.acfs/state.json 中：

{
  "schema_version": 3,
  "started_at": "2024-12-21T10:30:00Z",
  "last_updated": "2024-12-21T10:45:23Z",
  "mode": "vibe",
  "completed_phases": ["user_setup", "filesystem", "shell_setup"],
  "current_phase": "cli_tools",
  "current_step": "安装 ripgrep",
  "failed_phase": null,
  "failed_step": null,
  "failed_error": null,
  "skipped_phases": [],
  "phase_timings": {
    "user_setup": 12,
    "filesystem": 8,
    "shell_setup": 145
  }
}

状态机的阶段转换

每个阶段都会经历一套预定义的状态机流程：

┌─────────────────────────────────────────────────────────────────────────────┐
│  状态机阶段流程                                                         │
│                                                                              │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐                             │
│  │ PENDING  │────▶│ RUNNING  │────▶│ COMPLETE │                             │
│  └──────────┘     └────┬─────┘     └──────────┘                             │
│       │                │                                                     │
│       │                ▼                                                     │
│       │          ┌──────────┐     ┌──────────┐                              │
│       │          │  FAILED  │────▶│  RETRY   │──┐                           │
│       │          └──────────┘     └──────────┘  │                           │
│       │                                ▲        │                           │
│       │                                └────────┘                           │
│       │                                                                      │
│       └──────────────────────▶┌──────────┐                                  │
│          (--skip flag)        │ SKIPPED  │                                  │
│                               └──────────┘                                  │
└─────────────────────────────────────────────────────────────────────────────┘

恢复逻辑

当安装程序运行时，会依据以下决策树进行操作：

def should_run_phase(phase_id):
    state = load_state_file()

    if phase_id in state.completed_phases:
        return SKIP  # 已经完成

    if phase_id in state.skipped_phases:
        return SKIP  # 用户明确选择跳过

    if state.failed_phase == phase_id:
        if user_wants_retry():
            return RUN  # 重试失败的阶段
        else:
            return ABORT  # 不再继续执行失败的步骤

    return RUN  # 正常执行

原子状态更新

状态文件的更新是原子化的，以防止因中断写入而导致的数据损坏：

# 先将数据写入临时文件
echo "$new_state" > "$state_file.tmp.$$"

# 原子重命名（POSIX 确保在同一文件系统上执行的重命名操作是原子的）
mv "$state_file.tmp.$$" "$state_file"

这样可以确保状态文件始终完整且未被部分写入，即使进程在更新过程中被终止。

从常见故障中恢复

阶段时间与性能

状态文件会记录每个阶段的耗时。这使得：

• 可以准确估算进度（例如：“第 4/9 阶段，剩余约 3 分钟”）
• 能够检测 ACFS 各个版本之间的性能回归情况
• 识别出需要优化的慢速阶段

错误处理与恢复模式

ACFS 旨在实现优雅失败并自动恢复。本节将详细介绍代码库中所采用的错误处理模式。

“尝试-步骤”模式

每一步安装操作都封装在 try_step 函数中，该函数能够在不终止整个过程的情况下捕获错误：

try_step "安装 ripgrep" install_ripgrep

这种模式具有以下优势：

• 上下文追踪：错误信息不仅包含退出码，还附带了具体的步骤名称
• 优雅延续：非关键性错误不会导致整个安装过程终止
• 结构化报告：错误会被收集并统一汇总，在安装结束时进行汇报

网络韧性

网络操作采用了指数递增的退避策略，并结合随机抖动：

retry_with_backoff() {
    local max_attempts=5
    local delay=1

    for attempt in $(seq 1 $max_attempts); do
        if "$@"; then
            return 0
        fi

        // 指数退避：1 秒、2 秒、4 秒、8 秒、16 秒
        // 加入随机抖动：±25% 的随机范围
        local jitter=$(( (RANDOM % 50 - 25) * delay / 100 ))
        sleep $((delay + jitter))
        delay=$((delay * 2))
    done

    return 1
}

APT 锁管理

最常见的安装失败原因，往往是 APT 锁竞争（即有其他进程正在使用 apt）：

wait_for_apt_lock() {
    local max_wait=60
    local waited=0

    while fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1; do
        if [[ $waited -ge $max_wait ]]; then
            log_error "APT 锁已持有超过 60 秒，即将终止安装"
            return 1
        fi
        log_detail "等待 APT 锁... (${waited}s)"
        sleep 5
        waited=$((waited + 5))
    done

    return 0
}

优雅降级

当某个非关键工具未能成功安装时，ACFS 会以警告的形式继续推进：

类别：关键 → 失败会终止安装
          标准 → 失败被记录，安装将继续进行
          可选 → 失败被提醒，但无需发出警告

示例：
  关键：bun、zsh、git（没有这些工具无法继续）
  标准：ast-grep、lazygit（虽然有用，但不会阻塞）
  可选：atuin、zoxide（纯粹的增强功能）

错误报告

在安装过程的最后（或在安装中断时），ACFS 会生成一份结构化的错误报告：

═══════════════════════════════════════════════════════════════════════════════
  安装报告
═══════════════════════════════════════════════════════════════════════════════

  状态：部分成功（已完成 8/9 个阶段）

  ✓ 已完成的阶段：
    • 用户设置（12 秒）
    • 文件系统（8 秒）
    • Shell 设置（2 分 25 秒）
    • 命令行工具（4 分 12 秒）
    • 各种语言（3 分 45 秒）
    • 代理（1 分 30 秒）
    • 云服务（2 分 10 秒）
    • 系统堆栈（5 分 20 秒）

  ✗ 失败的阶段：最终确认
    步骤：配置 tmux
    错误：tmux.conf 在第 42 行存在语法错误

  建议的修复方法：
    检查 ~/.acfs/tmux/tmux.conf 中是否存在语法错误
    然后运行：curl ... | bash -s -- --yes --mode vibe --resume

═══════════════════════════════════════════════════════════════════════════════

故障排查指南

本节将介绍常见问题及其解决方案。若需快速调试，请先尝试使用 acfs doctor。

安装立即失败

症状：安装程序在启动后几秒内即退出。

常见原因及解决方法：

安装失败后的恢复

当安装程序在中途失败时，它会提供一个“自动恢复提示”，并附上一条精确的命令，帮助您从上次中断处继续安装。

失败时的显示内容：

[ERROR] ACFS 安装失败！

要进行故障排查：
1. 查看日志：cat /var/log/acfs/install.log
2. 如果已安装，运行：acfs doctor（建议以 Ubuntu 用户身份运行）

╔══════════════════════════════════════════════════════════════╗
║  要从当前点恢复安装：                     ║
╚══════════════════════════════════════════════════════════════╝

  curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/.../install.sh | bash -s -- --resume --yes

  失败的阶段：phase_9
  失败的步骤：install_stack

恢复提示的关键特性：

手动恢复步骤：

1. 查看错误信息：

   # 查看完整日志
   cat /var/log/acfs/install.log | tail -50
   
   # 或者搜索“ERROR”
   grep -i error /var/log/acfs/install.log
   

2. 运行诊断工具：

   # 以目标用户（Ubuntu）身份运行
   acfs doctor
   
   # 如果以 root 用户身份运行
   sudo -u ubuntu -i bash -lc 'acfs doctor'
   

3. 恢复安装：

   # 使用与失败输出中完全一致的命令
   # 或者使用通用的恢复命令：
   curl -sSL https://acfs.sh | bash -s -- --resume --yes --mode vibe
   

4. 查看状态文件（高级功能）：

   # 查看当前的安装状态
   cat ~/.acfs/state.json | jq .
   
   # 查看存储的恢复提示
   jq '.resume_hint' ~/.acfs/state.json
   

常见失败场景：

APT 依赖锁定错误

症状：E: 无法获取锁 /var/lib/dpkg/lock-frontend

解决方法：

1. 等待无人值守升级完成（最常见于全新 VPS）：

   # 查看当前持有锁的进程
   sudo lsof /var/lib/dpkg/lock-frontend
   
   # 等待该进程结束（通常在全新 VPS 上需要等待 2–3 分钟）
   # 然后重新运行安装程序
   

2. 终止卡住的进程（如果等待无效）：

   sudo killall apt apt-get dpkg
   sudo dpkg --configure -a
   sudo apt-get update
   

安装日志与摘要 JSON

每次 ACFS 安装都会生成两份文件，用于调试和工具管理：

日志文件位置：

~/.acfs/logs/install-YYYYMMDD_HHMMSS.log

日志文件会记录安装程序的所有 stderr 输出，包含：

• 标题，注明版本、日期和模式
• 所有进度消息与错误信息
• 完成后已去除 ANSI 颜色
• 结尾部分包含完成时间戳

摘要 JSON 文件位置：

~/.acfs/logs/install_summary_YYYYMMDD_HHMMSS.json

摘要 JSON Schema（v1）：

{
  "schema_version": 1,
  "status": "success",           // “success” 或 “failure”
  "timestamp": "2026-01-27T...", // ISO 8601
  "total_seconds": 1200,         // 实际运行时间
  "environment": {
    "acfs_version": "0.9.0",
    "mode": "vibe",
    "ubuntu_version": "25.04",
    "target_user": "ubuntu",
    "target_home": "/home/ubuntu"
  },
  "phases": [
    {"id": "phase_0", "duration_seconds": 5},
    {"id": "phase_1", "duration_seconds": 45},
    // ... 已完成的各个阶段按顺序排列
  ],
  "failure": null,               // 成功时为 null，失败时为：
  // "failure": {
  //   "phase": "phase_9",
  //   "step": "install_stack",
  //   "error": "curl 失败，退出码为 7",
  //   "resume_hint": "curl -sSL ... | bash -s -- --resume --yes"
  // }
  "log_file": "/home/ubuntu/.acfs/logs/install-20260127_120000.log"
}

访问日志：

# 查找最新日志
ls -lt ~/.acfs/logs/install-*.log | head -1

# 查找最新摘要
ls -lt ~/.acfs/logs/install_summary_*.json | head -1

# 解析摘要 JSON
jq . ~/.acfs/logs/install_summary_*.json | head -1

# 获取失败的阶段（如果有）
jq '.failure // "无失败"'. ~/.acfs/logs/install_summary_*.json | tail -1

# 获取各阶段的耗时
jq '.phases[] | "\(.id): \(.duration_seconds)s"' ~/.acfs/logs/install_summary_*.json | tail -1

分享日志以获取支持：

# 创建支持包（去除敏感数据）
acfs support-bundle > support-bundle.txt

# 或者手动分享（在分享前先检查是否包含敏感信息）：
cat ~/.acfs/logs/install-*.log | tail -200  # 最后 200 行
cat ~/.acfs/logs/install_summary_*.json | tail -1  # 最新摘要

总结

通过上述步骤，您可以轻松排查和解决 ACFS 安装过程中可能出现的各种问题，并获得准确的故障诊断与解决方案。

支持包命令

acfs support-bundle 命令会将所有诊断数据收集到一个单一的归档文件中，以便于进行故障排查。

用法：

acfs support-bundle [选项]

选项：

输出文件：

~/.acfs/support/<时间戳>/          # 解压后的包目录
~/.acfs/support/<时间戳>.tar.gz    # 压缩归档文件（可共享）
~/.acfs/support/<时间戳>/manifest.json  # 包清单文件

收集的内容：

安全与脱敏：

默认情况下，敏感数据会自动进行脱敏处理：

示例工作流程：

# 创建支持包
acfs support-bundle

# 输出：~/.acfs/support/20260127_120000.tar.gz

# 在提交问题时分享归档文件
# 该归档文件可安全共享（敏感信息已脱敏）

禁用脱敏处理（请谨慎使用）：

# 警告：该包可能包含 API 密钥、令牌及密码
acfs support-bundle --no-redact

适用场景：

• 安装失败且需要分享日志
• 提交 GitHub 问题关于 ACFS
• 诊断工具安装问题
• 与支持团队共享系统状态

Shell 未切换至 zsh

症状： 安装完成后仍显示 bash 提示符。

解决方案：

1. 登出并重新登录（更改会在下次登录时生效）

2. 手动设置 shell：

   chsh -s $(which zsh)
   # 然后登出并重新登录
   

3. 检查 shell 是否已安装：

   which zsh  # 应显示 /usr/bin/zsh
   cat /etc/shells  # zsh 应被列出
   

代理身份验证问题

Claude 代码：

# 检查身份验证状态
claude --version
ls -la ~/.claude/  # 或 ~/.config/claude/

# 重新进行身份验证
claude  # 按照提示操作

Codex CLI：

# 检查身份验证状态
codex --version

# 重新进行身份验证（使用的是 ChatGPT 账户，而非 API 密钥）
codex login

Gemini CLI：

# 检查身份验证状态
gemini --version

# 重新进行身份验证
gemini  # 按照 Google 登录流程操作

安装后出现“命令未找到”错误

症状： 即使安装成功，仍然显示 claude: 命令未找到。

解决方案：

1. 重新加载 shell 配置：

   source ~/.zshrc
   # 或者启动一个新的 shell
   exec zsh
   

2. 检查 PATH：

   echo $PATH | tr ':' '\n' | grep -E "(bun|local|cargo)"
   # 应包含：~/.bun/bin、~/.local/bin、~/.cargo/bin
   

3. 手动调整 PATH：

   export PATH="$HOME/.bun/bin:$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
   

Doctor 显示缺少工具

症状： acfs doctor 显示对预期已安装的工具进行了检查失败。

理解 Doctor 的输出：

Doctor 的检查直接基于清单文件生成，因此它会验证与安装程序提供的工具完全一致。当某个检查失败时，Doctor 会显示一条可复制粘贴的修复命令：

  ✗ tools.lazygit - Lazygit 终端界面未找到
    修复方法：acfs install --only tools.lazygit

解决方案：

1. 重新运行特定模块（使用修复建议）：

   acfs install --only tools.lazygit   # 只安装该工具
   acfs install --only lang.go         # 安装语言运行时
   acfs install --only stack.dcg       # 安装堆栈工具
   

2. 重新运行整个阶段（针对同一类别中的多个失败项）：

   acfs install --only-phase 4   # 重新运行第 4 阶段：工具
   acfs install --only-phase 8   # 重新运行第 8 阶段：堆栈
   

3. 启用自动修复模式（应用安全、确定性的修复措施）：

   acfs doctor --fix
   acfs doctor --fix --dry-run  # 先预览修复效果
   

注意： Doctor 的检查与清单文件中的验证命令完全一致。如果在安装过程中跳过了某个工具（例如使用了 --mode safe），检查将会失败。这是正常现象——请运行 acfs doctor，查看哪些工具缺失，并决定要安装哪些工具。

Tmux 配置错误

症状： Tmux 无法启动，或显示配置错误。

解决方案：

1. 检查语法：

   tmux source-file ~/.tmux.conf
   # 将会显示任何错误的行号
   

2. 重置为 ACFS 默认配置：

   cp ~/.acfs/tmux/tmux.conf ~/.tmux.conf
   

3. 版本不匹配（旧版 Tmux，新配置）：

   tmux -V  # 检查版本
   # ACFS 配置要求 Tmux 3.0+ 版本
   

堆栈工具无法正常工作

症状： ntm、slb、dcg 等工具未找到，或出现错误提示。

解决方案：

1. 重新安装堆栈：

   acfs update --stack --force
   

2. 检查 Cargo 安装是否成功：

   ls ~/.cargo/bin/  # 应包含 ntm、slb、ru 等工具
   ls ~/.local/bin/  # dcg 通常会在此处安装
   

3. Rust 未在 PATH 中：

   source ~/.cargo/env
   

DCG Hook 问题

症状： DCG 未能阻止命令执行，或 Claude 报告的 Hook 错误。

解决方案：

1. 运行内置健康检查：

   dcg doctor
   

2. 重新注册 Hook：

   dcg install --force
   

3. 验证 Hook 注册情况：

   grep -n dcg ~/.claude/settings.json ~/.config/claude/settings.json
   

4. 如果二进制文件缺失，重新安装：

   which dcg  # 应返回路径
   # 如果缺失，重新安装：
   curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh" | bash
   dcg install  # 重新安装后注册 Hook
   

完全重置

当其他方法均无效时，可以采取“核弹级”解决方案：

# 先保存好所有重要文件！

# 备份 ACFS 状态（推荐）
ts="$(date +%Y%m%d_%H%M%S)"
[ -d ~/.acfs ] && mv ~/.acfs ~/.acfs.backup."$ts"

# 备份已安装的配置（可选）
for f in ~/.zshrc ~/.tmux.conf ~/.p10k.zsh; do
  [ -f "$f" ] && mv "$f" "$f".backup."$ts"
done

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe --force-reinstall

安全威胁模型

ACFS 严肃对待安全问题，同时也充分认识到 curl | bash 安装方式固有的风险。本节将详细阐述我们的威胁模型及相应的缓解措施。

我们要防范哪些威胁？

我们不防范哪些威胁？

关于 curl | bash 的争论

curl | bash 的使用方式颇具争议。批评者指出：

• 你实际上是在从互联网上执行任意代码
• 下载过程可能在传输途中被篡改
• 在执行前无法进行审计

我们的回应：

1. HTTPS 可以有效防止传输过程中出现数据篡改
2. 校验和 可以确保下载内容与已知的“好版本”完全一致
3. 临时环境 可以将潜在的传播范围限制在最小范围内
4. 开源社区 允许对 install.sh 进行预先审核

为了获得最高级别的安全性，您可以这样做：

curl -fsSL "https://..." -o install.sh
less install.sh
bash install.sh --yes --mode vibe

校验和验证的深入解析

我们所获取的每一个上游安装器都会经过校验和验证，以确保其内容与已知的“好版本”完全一致：

# checksums.yaml 片段
installers:
  bun:
    url: "https://bun.sh/install"
    sha256: "a1b2c3d4e5f6..."
    last_verified: "2024-12-15"
    notes: "官方 Bun 安装器"

校验流程如下：

1. 将脚本下载至内存（而非磁盘）
2. 计算下载字节的 SHA256 校验和
3. 将校验和与存储的校验和进行比对
4. 若校验和匹配：则执行
5. 若校验和不匹配：则发出警告并中止操作

校验不匹配可能意味着：

• 上游发布了新版本（这种情况较为常见，通常无需担忧）
• 上游遭受了攻击（这种情况较少见，但需在更新前进行调查）

我们的更新流程如下：

1. 监控上游的版本发布
2. 审核新版本中包含的变更
3. 仅在人工审核后更新校验和
4. 在提交更新时附上详细的说明信息，清楚地说明发生了哪些变化

校验和验证的深层考量

我们所使用的每一种上游安装器都会经过校验和验证，以确保其内容与已知的“好版本”完全一致：

# checksums.yaml 片段
installers:
  bun:
    url: "https://bun.sh/install"
    sha256: "a1b2c3d4e5f6..."
    last_verified: "2024-12-15"
    notes: "官方 Bun 安装器"

校验流程如下：

1. 将脚本下载至内存（而非磁盘）
2. 计算下载字节的 SHA256 校验和
3. 将校验和与存储的校验和进行比对
4. 若校验和匹配：则执行
5. 若校验和不匹配：则发出警告并中止操作

校验不匹配可能意味着：

• 上游发布了新版本（这种情况较为常见，通常无需担忧）
• 上游遭受了攻击（这种情况较少见，但需在更新前进行调查）

我们的更新流程如下：

1. 监控上游的版本发布
2. 审核新版本中包含的变更
3. 仅在人工审核后更新校验和
4. 在提交更新时附上详细的说明信息，清楚地说明发生了哪些变化

Vibe 模式的安全性考量

Vibe 模式（--mode vibe）具备以下功能：

• 为 Ubuntu 用户提供无密码 sudo 权限
• 为 Claude 提供 --dangerously-skip-permissions 选项
• 为 Codex 提供 --dangerously-bypass-approvals-and-sandbox 选项
• 为 Gemini 提供 --yolo 选项

这种模式在速度方面故意采取了不安全的设计。请仅在以下场景中使用：

• 用于临时 VPS，且您并不在意其安全性
• 用于非生产环境
• 用于个人实验

切勿在以下场景中使用：

• 生产服务器
• 团队共享基础设施
• 存有敏感数据的系统
• 长期运行的服务器

与其他方案的对比

ACFS 与其他开发环境搭建方式相比如何？

与手动搭建相比

何时使用手动搭建：当您需要深入了解每个细节，或者对某些特定需求有极高要求时。

与 Dotfiles 仓库相比

何时使用 Dotfiles：当您已经安装了多种工具，只需配置一些必要的设置时。

与 Nix/NixOS 相比

何时使用 Nix：当您需要完美的可重复性，并且愿意投入时间学习 Nix 时。

与 DevContainers 相比

何时使用 DevContainers：当您希望在现有机器内部构建隔离的项目环境时。

与 Ansible/Terraform 相比

何时使用 Ansible/Terraform：当您需要管理多台服务器，而非单独的开发环境时。

ACFS 的最佳应用场景

当您需要以下条件时，ACFS 是最优选择：

• 快速搭建一个完整的 agentic 编码环境
• 以全新的 Ubuntu VPS 作为目标
• 将 AI 编码代理作为主要工具
• 采用“临时/短暂”的基础设施思维
• 在起步阶段只需进行最少的配置即可

Dicklesworthstone Stack 理念

ACFS 中所包含的 10 个工具并非随意组合——每个工具都针对特定问题进行了优化，这些问题正是我们在长期的多代理开发实践中不断发现的。

面临的问题

同时运行多个 AI 编码代理，会暴露出单代理或无代理开发方式所不存在的问题：

1. 会话混乱：代理们分散在随机的终端窗口中，缺乏统一的组织管理。
2. 文件冲突：两个代理同时编辑同一文件。
3. 缺乏沟通：代理之间无法协调或共享彼此的发现结果。
4. 危险命令：代理们在没有监督的情况下执行 git reset --hard 或 rm -rf 等操作。
5. 上下文丢失：代理们无法记住之前学到的内容。
6. 凭据切换：不同项目需要不同的凭证。
7. 历史碎片化：代理间的对话分散在各个系统中。
8. 任务难以追踪：难以看清代理们正在处理的具体任务。
9. 仓库管理混乱：数十个仓库，难以保持同步，到处都是未提交的工作。
10. 视觉调试的盲点：手机上的截图，在 SSH 终端中却无法清晰查看。

简化后的中文内容：

解决方案

堆栈中的每一种工具都针对特定的问题提供了解决方案：

捆绑工具：

协同效应

这些工具的设计理念是相互配合、协同工作：

NTM 启动代理 → 代理向 Agent Mail 注册 →
Agent Mail 预留文件 → DCG 阻止危险命令 →
UBS 验证操作 → Beads 跟踪任务 →
CASS 搜索历史 → CM 提供记忆 →
CAAM 管理身份验证 → SLB 管控核选项操作 →
RU 实现仓库同步，并自动化提交流程

单凭某一个工具本身并不能带来颠覆性的改变；只有将它们有机结合，才能实现原本难以想象的工作流：

• 10 个代理并行作业，且彼此互不干扰
• 持续运行——即使 SSH 连接中断也能保持运作
• 全面审计——记录下每个代理的操作行为
• 无需人工干预的协调——实现高效协作
• 安全可靠——在提升效率的同时，依然保障安全

堆栈的设计原则

1. Unix 理念：每种工具都专注于自身擅长的领域。
2. 模块化设计：工具之间通过管道连接，形成有机的整体。
3. 终端优先：以 TUI 为主，追求速度而非界面的精致度。
4. 代理原生：专为 AI 设计，而非对 AI 进行“适配”。
5. Git 兼容：所有状态均可通过版本控制进行审计。

高级配置

ACFS 支持多种配置方式，以满足高级用户的个性化需求。

环境变量

示例：

# 从标签版安装（生产环境推荐）
ACFS_REF=v0.1.0 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.1.0/install.sh" | bash -s -- --yes --mode vibe

# 从特定分支安装（开发/测试版）
ACFS_REF=feature/new-tool curl -fsSL "..." | bash -s -- --yes --mode vibe

# 从特定提交安装（实现可重复性）
ACFS_REF=abc1234 curl -fsSL "..." | bash -s -- --yes --mode vibe

# 固定安装版本，但使用最新校验和（避免旧哈希冲突）
ACFS_REF=v0.5.0 ACFS_CHECKSUMS_REF=main curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.5.0/install.sh" | bash -s -- --yes --mode vibe

提示： 务必使 URL 路径与 ACFS_REF 一致，这样初始脚本以及后续所有获取的脚本都将来自同一个引用。 提示： 对于已固定版本的安装（如标签/SHA），校验和默认设置为 main，以避免旧版安装的哈希冲突。若需将校验和固定到同一引用，可通过 ACFS_CHECKSUMS_REF 进行覆盖。

完整安装器 CLI 选项

安装器支持丰富的命令行自定义选项：

执行控制：

--yes, -y              # 忽略所有提示（非交互式模式）
--dry-run              # 模拟操作，不实际修改任何内容
--print                # 打印出即将安装的内容
--mode vibe|safe       # 安装模式（默认为 vibe）
--interactive          # 强制进入交互式模式，提示用户输入
--strict               # 发生错误时立即终止（而非继续显示警告）
--checksums-ref <ref>  # 从该引用获取 checksums.yaml（默认为 main，适用于已固定标签/SHA） |

恢复与状态：

--resume               # 从上次检查点恢复
--force-reinstall      # 忽略当前状态，重新安装所有内容
--reset-state          # 清空 state.json，从头开始

Ubuntu 升级：

--skip-ubuntu-upgrade           # 不升级 Ubuntu 版本
--target-ubuntu=25.10           # 指定目标 Ubuntu 版本
--target-ubuntu 25.04           # 替代语法

跳过某些选项：

--skip-postgres        # 跳过 PostgreSQL 18
--skip-vault           # 跳过 HashiCorp Vault
--skip-cloud           # 跳过 Wrangler、Supabase、Vercel CLI
--skip-preflight       # 跳过预检验证

模块选择

通过清单驱动的选型，可以精细控制安装的内容：

--list-modules           # 列出可用模块
--print-plan             # 显示执行计划，无需实际运行
--only <module>          # 仅运行指定模块
--only-phase <phase>     # 仅运行某个阶段的模块
--skip <module>          # 跳过特定模块
--no-deps                # 不自动包含依赖项（⚠️ 高级用户适用）

关键行为：

• 依赖关系闭包： 使用 --only 时，系统会自动包含所需的依赖项（默认情况下安全无虞）。
• 跳过安全检查： 如果 --skip 会破坏必要的依赖链，则会提前失败。
• 确定性： 使用 --print-plan 可以精确地展示接下来要运行的内容及其执行顺序。

示例： 仅安装代理及其依赖项：

curl -fsSL "..." | bash -s -- --yes --only-phase agents

跳过 PostgreSQL 和 Vault：

curl -fsSL "..." | bash -s -- --yes --skip db.postgres18 --skip tools.vault

在不实际执行的情况下预览即将运行的内容：

curl -fsSL "..." | bash -s -- --print-plan

注意： 使用 --no-deps 会绕过安全检查，可能导致安装失败。仅在您已单独安装了依赖项的情况下才应使用此选项。

自定义安装后钩子

通过将脚本放置在 ~/.acfs/hooks/ 目录下，即可添加自定义步骤：

mkdir -p ~/.acfs/hooks
cat > ~/.acfs/hooks/post-install.sh << 'EOF'
#!/bin/bash
# 自定义安装后步骤
echo "运行自定义配置..."
# 在这里编写您的命令
EOF
chmod +x ~/.acfs/hooks/post-install.sh

ACFS 会在主安装完成后执行 post-install.sh 脚本。

覆盖工具版本

要固定特定的工具版本，请设置环境变量：

export BUN_VERSION="1.1.0"
export UV_VERSION="0.5.0"
# 然后运行安装器

注意：并非所有工具都支持版本固定。请查阅各工具的官方文档以获取详细信息。

未来路线图

ACFS 正在积极开发中。以下是即将推出的功能：

近期（2025年第一季度）

• 完全基于清单驱动的执行：install.sh 将自动解析并执行生成的脚本
• Tailscale 集成：无需配置即可实现安全的远程访问 VPN ✓
• 服务设置向导：引导用户完成服务账号的设置（acfs services-setup） ✓
• 交互式模块选择：通过 TUI 选择要安装的内容

中期（2025年第二季度）

• ARM64 优化：支持原生 Apple Silicon 和 ARM VPS
• 离线模式：预先下载的软件包集合
• 团队模式：跨团队成员共享配置
• 插件系统：第三方工具的集成

长期（2025年及以后）

• ACFS 云服务：一键式管理 VPS 配置 + ACFS 安装
• IDE 集成：为远程 ACFS 管理提供 VSCode 和 Cursor 扩展
• 代理市场：预配置的代理个性与工作流
• 企业级功能：单点登录、审计日志、合规性保障

性能基准

安装时间会因 VPS 提供商和网络状况而异。以下是一些典型基准数据：

各阶段安装时间

影响速度的因素

恢复性能

从检查点恢复的速度非常快，因为已完成的阶段会被跳过：

完整安装：20 分钟
从 50% 处恢复：10 分钟
从 90% 处恢复：2 分钟

许可证

MIT 许可证（附带 OpenAI/Anthropic Rider）。详情请参阅 LICENSE。

链接

• 官网：agent-flywheel.com — 专为初学者设计的交互式向导
• GitHub：Dicklesworthstone/agentic_coding_flywheel_setup
• 相关项目：
  • ntm — 名为 Tmux 管理器
  • beads_viewer — 任务管理 TUI
  • mcp_agent_mail — 代理协调
  • cass — 代理会话搜索
  • dcg — 毁灭性命令守护者
  • ru — 仓库更新器

关于贡献

请不要误会，我并不接受任何外部项目的贡献。我根本没有足够的心理精力去审核所有内容，而且这些项目都是以我的名字命名的，因此一旦出现问题，我将承担全部责任；从我的角度来看，这种风险与回报的比值极其不均衡。此外，我还必须担心其他“利益相关方”，而这似乎对于那些我大多免费为自己打造的工具来说并不明智。如果您有任何问题或建议，欢迎随时提交，甚至可以提交 PR 来说明您提出的修复方案，但请知悉，我不会直接合并这些提交。相反，我会让 Claude 或 Codex 通过 gh 对提交内容进行审查，并独立决定是否以及如何处理这些提交。尤其是错误报告，我们非常欢迎。如果这冒犯了您，我深表歉意，但我希望避免浪费时间、伤害彼此的感情。我理解这与当前开源社区倡导的社区贡献精神并不完全一致，但这是我以目前的速度推进项目、同时保持理智的唯一方式。

Agentic Coding Flywheel Setup (ACFS) 快速上手指南

ACFS 是一个一键式引导系统，能在 30 分钟内将全新的 Ubuntu VPS 转化为专业的 AI 驱动开发环境。它自动安装 30+ 种开发工具、配置现代 Shell 环境，并部署三个主流 AI 编程助手（Claude Code, Codex CLI, Gemini CLI）。

1. 环境准备

在开始之前，请确保你拥有以下环境和资源：

• 目标服务器 (VPS)：
  • 操作系统：必须是 Ubuntu 25.10（官方推荐版本，脚本会自动处理升级）。
  • 权限：拥有 root 权限或具备 sudo 权限的用户。
  • 网络：服务器需能访问 GitHub 及各大包管理器源（若在国内部署，建议配置国内镜像源以提升下载速度，见下文提示）。
• 本地机器：
  • 任意操作系统（Windows/Mac/Linux），仅需具备终端（Terminal）和 SSH 客户端。
  • 用于通过 SSH 连接 VPS 并执行安装命令。

💡 国内用户加速提示： 由于该工具主要拉取 GitHub 资源和国际软件源，在中国大陆地区的 VPS 上运行时，建议先手动替换 apt、pip、npm 等包管理器为国内镜像（如阿里云、清华大学镜像站），以避免超时失败。本安装脚本本身暂不内置国内镜像切换逻辑。

2. 安装步骤

步骤一：登录 VPS

使用 SSH 连接到你的全新 Ubuntu VPS：

ssh root@your_vps_ip

步骤二：执行一键安装

复制并运行以下命令。该命令会自动下载最新安装脚本并以“极速模式”（Vibe Mode）运行，无需交互式确认。

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

注意：

• 断点续传：安装程序是幂等的。如果因网络中断导致安装失败，只需重新运行上述命令，它会自动从上次完成的阶段继续，不会重复操作。
• 生产环境锁定版本：若需确保环境绝对稳定可复现，建议指定特定版本标签（例如 v0.5.0）：

ACFS_REF=v0.5.0 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.5.0/install.sh" | bash -s -- --yes --mode vibe

步骤三：等待完成

脚本将自动执行以下操作（全程约 10-30 分钟，取决于网络状况）：

1. 更新系统并安装基础依赖。
2. 配置 Zsh + Oh My Zsh + Powerlevel10k 主题。
3. 安装语言运行时（Bun, Python/uv, Rust, Go）。
4. 部署 AI 代理工具（Claude Code, Codex CLI, Gemini CLI）。
5. 安装协作与云工具（NTM, Vault, Wrangler 等）。
6. 配置 ~/.acfs/ 目录及相关环境变量。

当看到安装成功的提示信息后，重启终端或运行 source ~/.zshrc 使配置生效。

3. 基本使用

安装完成后，你的 VPS 已转变为全功能的 AI 编码工作站。

验证环境

检查核心工具是否就绪：

# 检查 AI 代理是否可用
claude --version
codex --version
gemini --version

# 检查开发工具链
bun --version
uv --version
rustc --version

# 运行健康检查（诊断工具）
acfs doctor

开始 AI 编程

你现在可以直接调用 AI 代理进行开发工作。例如，让 Claude 在当前目录创建一个新项目：

# 示例：让 Claude Code 辅助编写代码
claude code "Create a simple hello world web server using Bun"

或者使用协调工具管理多个代理任务：

# 查看可用的 ACFS 命令
acfs --help

新手引导

如果你是第一次接触此类工作流，可以运行内置的上手教程：

onboard

现在，你已经拥有了一个由 AI 代理驱动的专业开发环境，可以开始构建项目了。