[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Dicklesworthstone--agentic_coding_flywheel_setup":3,"tool-Dicklesworthstone--agentic_coding_flywheel_setup":64},[4,17,27,35,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,43,44,45,15,46,26,13,47],"数据工具","视频","插件","其他","音频",{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,46],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70612,"2026-04-05T11:12:22",[26,15,13,45],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":79,"owner_twitter":80,"owner_website":81,"owner_url":82,"languages":83,"stars":100,"forks":101,"last_commit_at":102,"license":103,"difficulty_score":23,"env_os":104,"env_gpu":105,"env_ram":105,"env_deps":106,"category_tags":120,"github_topics":121,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":127,"updated_at":128,"faqs":129,"releases":157},1413,"Dicklesworthstone\u002Fagentic_coding_flywheel_setup","agentic_coding_flywheel_setup","Bootstraps a fresh Ubuntu VPS into a complete multi-agent AI development environment in 30 minutes: coding agents, session management, safety tools, and coordination infrastructure","agentic_coding_flywheel_setup 是一款自动化部署工具，旨在将一台全新的 Ubuntu 云服务器在 30 分钟内转化为功能完备的多智能体 AI 开发环境。它解决了开发者在搭建复杂 AI 编程工作流时面临的配置繁琐、依赖管理困难以及多智能体协调架构缺失等痛点，让用户无需手动安装数十种工具即可快速就绪。\n\n该工具特别适合希望利用 AI 代理（如 Claude Code、Codex CLI、Gemini CLI）辅助编码的开发者、技术研究人员以及想要体验自动化编程但受限于环境搭建门槛的进阶用户。即使是初学者，也能通过其提供的交互式向导或一条命令，轻松拥有专业的云端开发底座。\n\n其核心技术亮点在于“幂等性”安装脚本，即使安装过程意外中断，重新运行也能自动从断点续传，确保部署稳定可靠。此外，它预置了包含会话管理、安全工具及协调基础设施在内的完整技术栈，并支持\"Vibe 模式”，通过优化 Shell 环境和启用高效标志，最大化开发流速。agentic_coding_flywheel_setup 真正实现了从“只有一台笔记本”到\"AI 代理在云端为你编写代码”的无缝跨越。","# Agentic Coding Flywheel Setup (ACFS)\n\n\u003Cdiv align=\"center\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_agentic_coding_flywheel_setup_readme_38f71d2a5256.webp\" alt=\"Agentic Coding Flywheel Setup (ACFS) - From zero to fully-configured agentic coding VPS in 30 minutes\">\n\u003C\u002Fdiv>\n\n![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVersion-0.6.0-bd93f9?style=for-the-badge)\n![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPlatform-Ubuntu%2025.10-6272a4?style=for-the-badge)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT%2BOpenAI%2FAnthropic%20Rider-blue-the-badge)\n![Shell](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FShell-Bash-ff79c6?style=for-the-badge)\n\n\u003Cp align=\"center\">\n \u003Cstrong>🌐 \u003Ca href=\"https:\u002F\u002Fagent-flywheel.com\">agent-flywheel.com\u003C\u002Fa>\u003C\u002Fstrong> — Interactive setup wizard for beginners\n\u003C\u002Fp>\n\n> **From zero to fully-configured agentic coding VPS in 30 minutes.**\n> A complete bootstrapping system that transforms a fresh Ubuntu VPS into a professional AI-powered development environment.\n\n\u003Cdiv align=\"center\" style=\"margin: 1.2em 0;\">\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cstrong>The Vision\u003C\u002Fstrong>\u003Cbr\u002F>\n \u003Csub>Beginner with laptop → Wizard → VPS → Agents coding for you\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n### Quick Install\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\nThe installer is **idempotent**—if interrupted, simply re-run it. It will automatically resume from the last completed phase without prompts.\n\n> **Production environments:** For stable, reproducible installs, pin to a tagged release or specific commit:\n> ```bash\n> # Preferred: use a tagged release (e.g., v0.5.0)\n> ACFS_REF=v0.5.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.5.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n>\n> # Alternative: pin to a specific commit SHA\n> ACFS_REF=abc1234 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fabc1234\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n> ```\n> Tagged releases are tested and stable. Setting `ACFS_REF` ensures all fetched scripts use the same version.\n\n---\n\n## TL;DR\n\n**ACFS** is a complete system for bootstrapping agentic coding environments:\n\n**Why you'd care:**\n- **Zero to Hero:** Takes complete beginners from \"I have a laptop\" to \"I have Claude\u002FCodex\u002FGemini agents writing code for me on a VPS\"\n- **One-Liner Magic:** A single `curl | bash` command installs 30+ tools, configures everything, and sets up three AI coding agents\n- **Vibe Mode:** Pre-configured for maximum velocity—passwordless sudo, dangerous agent flags enabled, optimized shell environment\n- **Battle-Tested Stack:** Includes the complete Dicklesworthstone stack (10 tools + utilities) for agent orchestration, coordination, and safety\n\n**What you get:**\n- Modern shell (zsh + oh-my-zsh + powerlevel10k)\n- All language runtimes (bun, uv\u002FPython, Rust, Go)\n- Three AI coding agents (Claude Code, Codex CLI, Gemini CLI)\n- Agent coordination tools (NTM, MCP Agent Mail, SLB)\n- Cloud CLIs (Vault, Wrangler, Supabase, Vercel)\n- And 20+ more developer tools\n\n---\n\n## The ACFS Experience\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph user [\"User's Machine\"]\n LAPTOP[\"Laptop\"]\n BROWSER[\"Browser\"]\n end\n\n subgraph wizard [\"Wizard Website\"]\n STEPS[\"13-Step Guide\"]\n end\n\n subgraph vps [\"Fresh VPS\"]\n UBUNTU[\"Ubuntu 25.10\"]\n INSTALLER[\"install.sh\"]\n CONFIGURED[\"Configured VPS\"]\n end\n\n subgraph agents [\"AI Agents\"]\n CLAUDE[\"Claude Code\"]\n CODEX[\"Codex CLI\"]\n GEMINI[\"Gemini CLI\"]\n end\n\n LAPTOP --> BROWSER\n BROWSER --> STEPS\n STEPS -->|SSH| UBUNTU\n UBUNTU --> INSTALLER\n INSTALLER --> CONFIGURED\n CONFIGURED --> CLAUDE\n CONFIGURED --> CODEX\n CONFIGURED --> GEMINI\n\n classDef user fill:#e3f2fd,stroke:#90caf9,stroke-width:2px\n classDef wizard fill:#fff8e1,stroke:#ffcc80,stroke-width:2px\n classDef vps fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px\n classDef agent fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px\n\n class LAPTOP,BROWSER user\n class STEPS wizard\n class UBUNTU,INSTALLER,CONFIGURED vps\n class CLAUDE,CODEX,GEMINI agent\n```\n\n### For Beginners\nACFS includes a **step-by-step wizard website** at [agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) that guides complete beginners through:\n1. Installing a terminal on their local machine\n2. Generating SSH keys (for secure access later)\n3. Renting a VPS from providers like OVH or Contabo\n4. Connecting via SSH with a password (initial setup)\n5. Running the installer (which sets up key-based access)\n6. Reconnecting securely with your SSH key\n7. Starting to code with AI agents\n\n### For Developers\nACFS is a **one-liner** that transforms any fresh Ubuntu VPS into a fully-configured development environment with modern tooling and three AI coding agents ready to go.\n\n### For Teams\nACFS provides a **reproducible, idempotent** setup that ensures every team member's VPS environment is identical—eliminating \"works on my machine\" for agentic workflows.\n\n---\n\n## Architecture & Design\n\nACFS is built around a **single source of truth**: the manifest file. Everything else—the installer scripts, doctor checks, website content—derives from this central definition. This architecture ensures consistency and makes the system easy to extend.\n\n### One-Page System Data Flow\n\n```mermaid\nflowchart TB\n %% User and website\n subgraph U[\"User (local machine)\"]\n Browser[\"Browser\"]\n Terminal[\"Terminal \u002F SSH client\"]\n end\n\n subgraph W[\"Wizard Website (Next.js 16) — apps\u002Fweb\"]\n Wizard[\"Wizard UI (\u002Fwizard\u002F*)\"]\n InstallRoute[\"GET \u002Finstall (302 redirect to raw install.sh)\"]\n WebState[\"State: URL params + localStorage\"]\n end\n\n %% Repo sources\n subgraph R[\"Repo (source)\"]\n Manifest[\"acfs.manifest.yaml\u003Cbr\u002F>Modules + install + verify + deps\"]\n Generator[\"packages\u002Fmanifest\u003Cbr\u002F>Parser (Zod) + generate.ts\"]\n Generated[\"scripts\u002Fgenerated\u002F* (reference)\u003Cbr\u002F>category installers + doctor_checks.sh\"]\n Installer[\"install.sh (production one-liner)\"]\n Lib[\"scripts\u002Flib\u002F*\u003Cbr\u002F>security \u002F doctor \u002F update \u002F services-setup\"]\n Configs[\"acfs\u002F*\u003Cbr\u002F>zshrc + tmux.conf + onboard lessons\"]\n Checksums[\"checksums.yaml\u003Cbr\u002F>sha256 for upstream installers\"]\n Tests[\"tests\u002Fvm\u002Ftest_install_ubuntu.sh\u003Cbr\u002F>Docker integration test\"]\n end\n\n %% Target VPS\n subgraph V[\"Target VPS (Ubuntu 25.10, auto-upgraded)\"]\n Run[\"Run install.sh\"]\n Verify[\"Verified upstream installers\u003Cbr\u002F>(security.sh + checksums.yaml)\"]\n AcfsHome[\"~\u002F.acfs\u002F\u003Cbr\u002F>configs + scripts + state.json\"]\n Commands[\"Commands\u003Cbr\u002F>acfs doctor \u002F acfs update \u002F acfs services-setup \u002F onboard\"]\n Tools[\"Installed tools\u003Cbr\u002F>bun\u002Fuv\u002Frust\u002Fgo + tmux\u002Frg\u002Fgh + vault + ...\"]\n Agents[\"Agent CLIs\u003Cbr\u002F>claude \u002F codex \u002F gemini\"]\n Stack[\"Stack tools\u003Cbr\u002F>ntm \u002F mcp_agent_mail \u002F ubs \u002F bv \u002F cass \u002F cm \u002F caam \u002F slb \u002F dcg \u002F ru\"]\n end\n\n %% Website guidance flow\n Browser --> Wizard\n Wizard --> WebState\n Wizard --> InstallRoute\n InstallRoute -->|redirects to| Installer\n\n %% How users fetch\u002Frun the installer\n Terminal -->|curl \u002F bash| Installer\n Terminal -->|SSH| Run\n\n %% Manifest-driven generation (reference today)\n Manifest --> Generator --> Generated\n Generated -.->|planned: install.sh calls generated install_all.sh| Installer\n\n %% Installer composition\n Lib --> Installer\n Configs --> Installer\n Checksums --> Installer\n Tests -->|validates| Installer\n\n %% VPS install results\n Installer --> Run\n Run --> Verify\n Verify --> Tools\n Verify --> Agents\n Verify --> Stack\n Run --> AcfsHome --> Commands\n```\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ SOURCE OF TRUTH │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ acfs.manifest.yaml │ │\n│ │ Tool Definitions • Install Commands • Verification Logic │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n │\n ┌─────────────────┴─────────────────┐\n ▼ ▼\n┌───────────────────────────────────┐ ┌───────────────────────────────────┐\n│ CODE GENERATION │ │ WIZARD WEBSITE │\n│ ┌─────────────────────────────┐ │ │ ┌─────────────────────────────┐ │\n│ │ TypeScript Parser (Zod) │ │ │ │ apps\u002Fweb\u002F (Next.js 16) │ │\n│ │ generate.ts │ │ │ │ agent-flywheel.com │ │\n│ └─────────────────────────────┘ │ │ └─────────────────────────────┘ │\n└───────────────────────────────────┘ └───────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────────────────┐\n│ GENERATED OUTPUTS (REFERENCE) │\n│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │\n│ │ scripts\u002Fgenerated\u002F │ │ doctor_checks.sh │ │ install_all.sh │ │\n│ │ 11 Category Scripts│ │ Verification Logic │ │ Master Installer │ │\n│ └────────────────────┘ └────────────────────┘ └────────────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────────────────┐\n│ INSTALLER │\n│ install.sh + scripts\u002Flib\u002F*.sh + checksums.yaml (SHA256 verification) │\n│ (scripts\u002Fgenerated\u002F* are sourced; execution is feature-flagged) │\n└───────────────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────────────────┐\n│ TARGET VPS │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ 30+ Tools │ │ zsh + p10k │ │ AI Agents │ │ ~\u002F.acfs\u002F │ │\n│ │ Installed │ │ Shell Config │ │ Claude\u002FCodex │ │ Configurations│ │\n│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n```\n\n### Why This Architecture?\n\n**Single Source of Truth**: The manifest file (`acfs.manifest.yaml`) defines every tool—its name, description, install commands, and verification logic. When you add or edit a tool in the manifest, the generator automatically updates the generated scripts and manifest-derived checks. The production one-liner installer (`install.sh`) is still hand-written today, so behavior changes may also require updating `install.sh` until full migration.\n\n**TypeScript + Zod Validation**: The manifest parser uses Zod schemas to validate the YAML at parse time. Typos, missing fields, and structural errors are caught immediately during generation—not at runtime on a user's VPS when the installer fails halfway through.\n\n**Generated Scripts**: Rather than hand-maintaining 11 category installer scripts and keeping them synchronized, the generator produces them from the manifest. This means:\n- A consistent, auditable view of manifest-defined install logic (some modules intentionally emit TODOs)\n- Consistent error handling and logging across all modules\n- A clear path toward future installer integration\n\n### Components\n\n| Component | Path | Technology | Purpose |\n|-----------|------|------------|---------|\n| **Manifest** | `acfs.manifest.yaml` | YAML | Single source of truth for all tools |\n| **Generator** | `packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts` | TypeScript\u002FBun | Produces installer scripts from manifest |\n| **Website** | `apps\u002Fweb\u002F` | Next.js 16 + Tailwind 4 | Step-by-step wizard for beginners |\n| **Installer** | `install.sh` | Bash | One-liner bootstrap script |\n| **Lib Scripts** | `scripts\u002Flib\u002F` | Bash | Modular installer functions |\n| **Generated Scripts** | `scripts\u002Fgenerated\u002F` | Bash | Auto-generated category installers (sourced by `install.sh`; execution is feature-flagged) |\n| **Configs** | `acfs\u002F` | Shell\u002FTmux configs | Files deployed to `~\u002F.acfs\u002F` |\n| **Onboarding** | `acfs\u002Fonboard\u002F` | Bash + Markdown | Interactive tutorial system |\n| **Checksums** | `checksums.yaml` | YAML | SHA256 hashes for upstream installers |\n\n---\n\n## The Manifest System\n\n`acfs.manifest.yaml` is the **single source of truth** for all tools installed by ACFS. It defines what gets installed, how to install it, and how to verify the installation worked.\n\n### Manifest Structure\n\n```yaml\nversion: \"1.0\"\nmeta:\n name: \"ACFS\"\n description: \"Agentic Coding Flywheel Setup\"\n version: \"0.1.0\"\n\nmodules:\n base.system:\n description: \"Base packages + sane defaults\"\n category: base\n install:\n - sudo apt-get update -y\n - sudo apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential\n verify:\n - curl --version\n - git --version\n - jq --version\n\n agents.claude:\n description: \"Claude Code\"\n category: agents\n install:\n - \"Install claude code via official method\"\n verify:\n - claude --version || claude --help\n```\n\nEach module specifies:\n- **description**: Human-readable name\n- **category**: Grouping for installer organization (base, shell, cli, lang, tools, db, cloud, agents, stack, acfs)\n- **install**: Commands to run (or descriptions that become TODOs)\n- **verify**: Commands that must succeed to confirm installation\n\n### The Generator Pipeline\n\nThe TypeScript generator (`packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts`) reads the manifest and produces:\n\n1. **Category Scripts** (`scripts\u002Fgenerated\u002Finstall_base.sh`, `install_agents.sh`, etc.)\n - One script per category with individual install functions\n - Consistent logging and error handling\n - Verification checks after each module\n\n2. **Doctor Checks** (`scripts\u002Fgenerated\u002Fdoctor_checks.sh`)\n - All verify commands extracted into a runnable health check\n - Tab-delimited format (to safely handle `||` in shell commands)\n - Reports pass\u002Ffail\u002Fskip for each module\n\n3. **Master Installer** (`scripts\u002Fgenerated\u002Finstall_all.sh`)\n - Sources all category scripts\n - Runs them in dependency order\n - Single entry point for running the generated installers\n\n> Note: The production one-liner installer (`install.sh`) defaults to the legacy implementations; generated installers are sourced and can be enabled per-category via feature flags during migration.\n\nTo regenerate after manifest changes:\n\n```bash\ncd packages\u002Fmanifest\nbun run generate # Generate scripts\nbun run generate:dry # Preview without writing\n```\n\n### Why TypeScript for Code Generation?\n\nShell can parse YAML with `yq`, but TypeScript + Zod offers:\n- **Type safety**: The parser knows the exact shape of a manifest\n- **Validation**: Zod catches malformed YAML with descriptive errors\n- **Transformation**: Complex logic (sorting by dependencies, escaping) is natural in TypeScript\n- **Consistency**: All generated code follows the same patterns\n\nThe generator itself is ~400 lines of TypeScript. The generated output is ~1000 lines of Bash across 13 files. The trade-off is clearly in favor of maintaining the generator.\n\n---\n\n## Security Verification\n\nACFS downloads and executes installer scripts from the internet. This is inherently risky—a compromised upstream could inject malicious code. The security verification system mitigates this risk.\n\n### How It Works\n\nThe `checksums.yaml` file contains SHA256 hashes for all upstream installer scripts:\n\n```yaml\n# checksums.yaml\ninstallers:\n bun:\n url: \"https:\u002F\u002Fbun.sh\u002Finstall\"\n sha256: \"a1b2c3d4...\"\n\n rust:\n url: \"https:\u002F\u002Fsh.rustup.rs\"\n sha256: \"e5f6a7b8...\"\n```\n\nThe security library (`scripts\u002Flib\u002Fsecurity.sh`) provides:\n\n1. **HTTPS Enforcement**: All installer URLs must use HTTPS. Non-HTTPS URLs fail immediately.\n\n2. **Checksum Verification**: Before executing a downloaded script, the system:\n - Downloads the content to memory\n - Calculates the SHA256 hash\n - Compares against the stored hash\n - Only executes if they match\n\n3. **Verification Modes**:\n ```bash\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --print # List all upstream URLs\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --verify # Verify all against saved checksums\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums # Generate new checksums.yaml\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --checksum URL # Calculate SHA256 of any URL\n ```\n\n### When Checksums Fail\n\nA checksum mismatch can mean:\n1. **Normal update**: The upstream maintainer released a new version\n2. **Potential compromise**: Someone modified the script maliciously\n\nThe verification report distinguishes these cases:\n- If multiple checksums fail simultaneously, investigate before updating\n- If a single checksum fails after a known release, update is likely safe\n\nTo update after verifying a legitimate upstream change:\n```bash\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums > checksums.yaml\ngit diff checksums.yaml # Review what changed\ngit commit -m \"chore: update upstream checksums\"\n```\n\n### Why This Approach?\n\nThe `curl | bash` pattern is controversial but practical. ACFS makes it safer by:\n- Verifying content before execution (not just transport via HTTPS)\n- Making checksums auditable in version control\n- Providing tools to detect and investigate changes\n- Failing closed (no execution on mismatch)\n\nThis is defense in depth—HTTPS protects transport, checksums protect content.\n\n---\n\n## The Installer\n\nThe installer is the heart of ACFS—a modular Bash script that transforms a fresh Ubuntu VPS into a fully-configured development environment.\n\n### Usage\n\nFull vibe mode (recommended for throwaway VPS):\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\nInteractive mode (asks for confirmation):\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash\n```\n\nSafe mode (no passwordless sudo, agent confirmations enabled):\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --mode safe\n```\n\n### Installer Modes\n\n| Mode | Passwordless Sudo | Agent Flags | Best For |\n|------|-------------------|-------------|----------|\n| **vibe** | Yes | `--dangerously-skip-permissions` | Throwaway VPS, maximum velocity |\n| **safe** | No | Standard confirmations | Production-like environments |\n\n### Installation Phases\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n A[\"Phase 1: User Normalization\u003Cbr\u002F>\u003Csmall>Create ubuntu user, migrate SSH keys\u003C\u002Fsmall>\"]\n B[\"Phase 2: APT Packages\u003Cbr\u002F>\u003Csmall>Essential system packages\u003C\u002Fsmall>\"]\n C[\"Phase 3: Shell Setup\u003Cbr\u002F>\u003Csmall>zsh, oh-my-zsh, powerlevel10k\u003C\u002Fsmall>\"]\n D[\"Phase 4: CLI Tools\u003Cbr\u002F>\u003Csmall>ripgrep, fzf, lazygit, etc.\u003C\u002Fsmall>\"]\n E[\"Phase 5: Language Runtimes\u003Cbr\u002F>\u003Csmall>bun, uv, rust, go\u003C\u002Fsmall>\"]\n F[\"Phase 6: AI Agents\u003Cbr\u002F>\u003Csmall>claude, codex, gemini\u003C\u002Fsmall>\"]\n G[\"Phase 7: Cloud Tools\u003Cbr\u002F>\u003Csmall>vault, wrangler, supabase, vercel\u003C\u002Fsmall>\"]\n H[\"Phase 8: Dicklesworthstone Stack\u003Cbr\u002F>\u003Csmall>ntm, dcg, ru, ubs, mcp_agent_mail, etc.\u003C\u002Fsmall>\"]\n I[\"Phase 9: Configuration\u003Cbr\u002F>\u003Csmall>Deploy acfs.zshrc, tmux.conf\u003C\u002Fsmall>\"]\n J[\"Phase 10: Verification\u003Cbr\u002F>\u003Csmall>acfs doctor\u003C\u002Fsmall>\"]\n\n A --> B --> C --> D --> E --> F --> G --> H --> I --> J\n\n classDef phase fill:#e8f5e9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n class A,B,C,D,E,F,G,H,I,J phase\n```\n\n### Key Properties\n\n| Property | Description |\n|----------|-------------|\n| **Idempotent** | Safe to re-run; skips already-installed tools |\n| **Checkpointed** | Phases resume automatically from `~\u002F.acfs\u002Fstate.json` |\n| **Pre-flight validated** | Run `scripts\u002Fpreflight.sh` to catch issues before install |\n| **Logged** | Colored output with progress indicators |\n| **Modular** | Each category is a separate sourceable script |\n\n### Resume Capability\n\nThe installer tracks progress in `~\u002F.acfs\u002Fstate.json`. If interrupted:\n- Re-run the same command—it resumes from the last completed phase\n- No prompts or confirmations needed (with `--yes`)\n- Already-installed tools are detected and skipped\n\nTo force a fresh reinstall of all tools:\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --force-reinstall\n```\n\n### Pre-Flight Check\n\nBefore running the full installer, validate your system:\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash -s -- --json\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash -s -- --format toon\n```\n\nThis checks:\n- OS compatibility (Ubuntu 22.04+; installer upgrades to 25.10)\n- Architecture (x86_64 or ARM64)\n- Memory and disk space (minimum 4GB RAM, 10GB free disk)\n- Network connectivity to required URLs\n- APT lock status\n- Potential conflicts (nvm, pyenv, existing ACFS)\n\n**Network checks performed:**\n| Check | What it verifies | Fix if failing |\n|-------|------------------|----------------|\n| DNS resolution | Can resolve github.com, raw.githubusercontent.com | Check `\u002Fetc\u002Fresolv.conf` or add `8.8.8.8` |\n| GitHub HTTPS | Can reach github.com:443 | Check firewall, proxy, or VPN settings |\n| Installer URLs | Raw GitHub, Homebrew, Oh-My-Zsh, Rust, etc. | May need to retry; transient failures OK |\n| APT mirrors | Default Ubuntu mirror reachable | Check `\u002Fetc\u002Fapt\u002Fsources.list` or try different mirror |\n\n**Common preflight failures:**\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| \"Cannot resolve github.com\" | DNS misconfigured | Add `nameserver 8.8.8.8` to `\u002Fetc\u002Fresolv.conf` |\n| \"Cannot reach github.com\" | Firewall blocking HTTPS | Allow outbound port 443 |\n| \"APT mirror slow or unreachable\" | Regional mirror down | Edit `\u002Fetc\u002Fapt\u002Fsources.list` to use `archive.ubuntu.com` |\n| \"APT lock held\" | Another apt process running | Wait for it to finish or `sudo kill \u003Cpid>` |\n| \"Insufficient disk space\" | Less than 10GB free | Clean up with `sudo apt autoremove` or expand disk |\n\n### Console Output\n\nThe installer uses semantic colors for progress visibility:\n\n```bash\n[1\u002F8] Installing essential packages... # Blue: progress steps\n Installing zsh, git, curl... # Gray: details\n⚠️ May take a few minutes # Yellow: warnings\n✖ Failed to install package # Red: errors\n✔ Shell setup complete # Green: success\n```\n\n### Automatic Ubuntu Upgrade\n\nACFS automatically upgrades Ubuntu to version **25.10** before installation when running on older versions. This ensures compatibility with the latest packages and optimal performance.\n\n**How it works:**\n1. Detects your current Ubuntu version\n2. Calculates the upgrade path (e.g., 24.04 → 25.04 → 25.10)\n3. Performs sequential `do-release-upgrade` operations\n4. Reboots after each upgrade (handled automatically)\n5. Resumes via systemd service after reboot\n6. Continues ACFS installation once at target version\n\n**Expected timeline:**\n- Each version hop takes 30-60 minutes\n- Full chain from 24.04 → 25.10 takes 1.5-3 hours\n- SSH sessions disconnect during reboots (reconnect to monitor)\n\n**To skip automatic upgrade:**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --skip-ubuntu-upgrade\n```\n\n**To specify a different target version:**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --target-ubuntu=25.04\n```\n\n**Monitoring upgrade progress:**\n```bash\n# Check current status\n\u002Fvar\u002Flib\u002Facfs\u002Fcheck_status.sh\n\n# View upgrade logs\njournalctl -u acfs-upgrade-resume -f\n\n# View detailed logs\ntail -f \u002Fvar\u002Flog\u002Facfs\u002Fupgrade_resume.log\n```\n\n**Important notes:**\n- Create a VM snapshot before upgrading (recommended but not required)\n- Upgrades cannot be undone without restoring from snapshot\n- The system will reboot multiple times automatically\n- EOL interim releases (like 24.10) may be skipped automatically if they are no longer offered by `do-release-upgrade`\n- Reconnect via SSH after each reboot to monitor progress\n\n---\n\n## The Update Command\n\nAfter installation, keeping tools current is handled by `acfs-update`. It provides a unified interface for updating all installed components.\n\n### Usage\n\n```bash\nacfs-update # Update apt, runtimes, shell, agents, and cloud CLIs\nacfs-update --stack # Include Dicklesworthstone stack tools\nacfs-update --agents-only # Only update coding agents\nacfs-update --runtime-only # Only update runtimes (bun, rust, uv, go)\nacfs-update --dry-run # Preview changes without making them\nacfs-update --yes --quiet # Automated\u002FCI mode with minimal output\n```\n\n### What Gets Updated\n\n| Category | Tools | Method |\n|----------|-------|--------|\n| **System** | apt packages | `apt update && apt upgrade` |\n| **Shell** | OMZ, P10K, plugins | `git pull` on each repo |\n| **Shell** | Atuin, Zoxide | Re-run upstream installers |\n| **Runtime** | Bun | `bun upgrade` |\n| **Runtime** | Rust | `rustup update stable` |\n| **Runtime** | uv (Python) | `uv self update` |\n| **Runtime** | Go | `apt upgrade` (if apt-managed) |\n| **Agents** | Claude Code | `claude update --channel latest` |\n| **Agents** | Codex, Gemini | `bun install -g @latest` |\n| **Cloud** | Wrangler, Vercel | `bun install -g @latest` |\n| **Cloud** | Supabase | GitHub release tarball (sha256 checksums) |\n| **Stack** | ntm, slb, ubs, dcg, ru, etc. | Re-run upstream installers |\n\n### Options\n\n**Category Selection:**\n```bash\n--apt-only Only update system packages\n--agents-only Only update coding agents\n--cloud-only Only update cloud CLIs\n--shell-only Only update shell tools (OMZ, P10K, plugins, Atuin, Zoxide)\n--runtime-only Only update runtimes (bun, rust, uv, go)\n--stack Include Dicklesworthstone stack (enabled by default)\n```\n\n**Skip Categories:**\n```bash\n--no-apt Skip apt updates\n--no-agents Skip agent updates\n--no-cloud Skip cloud CLI updates\n--no-shell Skip shell tool updates\n--no-runtime Skip runtime updates (bun, rust, uv, go)\n```\n\n**Behavior:**\n```bash\n--force Install missing tools (not just update existing)\n--dry-run Preview changes without making them\n--yes, -y Non-interactive mode (skip prompts)\n--quiet, -q Minimal output (only errors and summary)\n--verbose, -v Show detailed command output\n--abort-on-failure Stop on first failure (default: continue)\n```\n\n### Logs\n\nUpdate logs are automatically saved to `~\u002F.acfs\u002Flogs\u002Fupdates\u002F` with timestamps:\n```bash\n# View most recent log\ncat ~\u002F.acfs\u002Flogs\u002Fupdates\u002F$(ls -1t ~\u002F.acfs\u002Flogs\u002Fupdates | head -1)\n\n# Follow a running update\ntail -f ~\u002F.acfs\u002Flogs\u002Fupdates\u002F$(ls -1t ~\u002F.acfs\u002Flogs\u002Fupdates | head -1)\n```\n\n### Why Separate from the Installer?\n\nThe installer transforms a fresh VPS. The update command maintains an existing installation. Separating them allows:\n- **Focused updates**: Update just agents without touching system packages\n- **Dry-run previews**: See what would change before committing\n- **Skip flags**: Temporarily exclude categories that are working fine\n- **Stack control**: Stack updates are included by default; skip with `--no-stack`\n- **Automated updates**: Run via cron with `--yes --quiet`\n\n---\n\n## ACFS CLI Commands\n\nAfter installation, the `acfs` command provides a unified interface for managing your environment. Each subcommand is designed to be fast, informative, and scriptable.\n\n### Quick Reference\n\n```bash\nacfs info # Lightning-fast system overview\nacfs cheatsheet # Discover installed aliases\nacfs dashboard generate # Generate HTML status page\nacfs doctor # Health checks\nacfs newproj # Create a new project (TUI or CLI)\nacfs update # Update all tools\nacfs services-setup # Configure agent credentials\nacfs continue # View upgrade progress after reboot\n```\n\n### `acfs newproj` — New Project Wizard\n\nCreate a new project directory with ACFS defaults (git init, optional br\u002Fbeads, Claude settings, AGENTS.md).\nThe interactive wizard is recommended for beginners.\n\nInteractive wizard (recommended):\n```bash\nacfs newproj --interactive\nacfs newproj -i\nacfs newproj -i myapp # Prefill project name\n```\n\nThe wizard guides you through:\n- Project naming and location\n- Tech stack detection\u002Fselection\n- Feature selection (br\u002Fbeads, Claude settings, AGENTS.md, UBS ignore)\n- AGENTS.md customization preview\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>TUI Wizard Screenshots\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Welcome Screen:**\n```\n ╔═══════════════════════════════════════════════════════╗\n ║ ║\n ║ █████╗ ██████╗ ███████╗ ███████╗ ║\n ║ ██╔══██╗██╔════╝ ██╔════╝ ██╔════╝ ║\n ║ ███████║██║ █████╗ ███████╗ ║\n ║ ██╔══██║██║ ██╔══╝ ╚════██║ ║\n ║ ██║ ██║╚██████╗ ██║ ███████║ ║\n ║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚══════╝ ║\n ║ ║\n ║ Agentic Coding Flywheel Setup ║\n ║ ║\n ╚═══════════════════════════════════════════════════════╝\n\nThis wizard will help you set up a new project with:\n\n ✓ Project directory structure\n ✓ Git repository initialization\n ✓ AGENTS.md for AI coding assistants\n ✓ Beads issue tracking (optional)\n ✓ Claude Code settings (optional)\n```\n\n**Confirmation Screen:**\n```\n──────────────────── Review & Confirm ────────────────────\n Step 7 of 9\n\nPlease review your selections before creating the project.\n\nProject Summary\n──────────────────────────────────────────────────────────\n Name: myapp\n Location: \u002Fhome\u002Fuser\u002Fprojects\u002Fmyapp\n Tech: Node.js, TypeScript\n\nFeatures\n──────────────────────────────────────────────────────────\n ✓ Beads tracking\n ✓ Claude Code settings\n ✓ AGENTS.md\n ✓ UBS ignore\n\nFiles to Create\n──────────────────────────────────────────────────────────\nmyapp\u002F\n├── .git\u002F\n├── AGENTS.md\n├── .beads\u002F\n│ └── beads.db\n├── .claude\u002F\n│ └── settings.local.json\n├── .ubsignore\n├── README.md\n└── .gitignore\n\nOptions:\n [Enter\u002Fc] Create project\n [e] Edit selections (go back)\n [q\u002FEsc] Cancel\n```\n\n\u003C\u002Fdetails>\n\nCLI mode (automation):\n```bash\nacfs newproj myapp\nacfs newproj myapp \u002Fcustom\u002Fpath\nacfs newproj myapp --no-br\n```\n\nNotes:\n- The TUI uses gum when available (arrow keys, Space to toggle, Enter to confirm). Without gum, it falls back to numbered prompts.\n- Minimum terminal size: 60x15.\n- CLI mode skips existing AGENTS.md; the wizard overwrites it, so move it aside if you want to keep the old one.\n\n### `acfs info` — System Overview\n\nDisplays installation status in under 1 second by reading cached state (no verification).\n\n```bash\nacfs info # Terminal output (default)\nacfs info --json # JSON output for scripting\nacfs info --html # Self-contained HTML page\nacfs info --minimal # Just essentials (IP, key commands)\n```\n\nExample output:\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ACFS System Info ║\n╠══════════════════════════════════════════════════════════════╣\n║ Host: vps-12345.contabo.net ║\n║ IP: 192.168.1.100 ║\n║ User: ubuntu ║\n║ Uptime: 3 days, 4 hours ║\n║ ║\n║ Quick Commands: ║\n║ cc → Claude Code (dangerous mode) ║\n║ cod → Codex CLI (dangerous mode) ║\n║ gmi → Gemini CLI (yolo mode) ║\n║ ntm → Named Tmux Manager ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n**Design Philosophy:**\n- **Speed**: Must complete in \u003C1 second\n- **Read-only**: Never verifies or tests (that's doctor's job)\n- **Offline**: No network calls required\n- **Fallback**: Graceful degradation if data missing\n\n### `acfs cheatsheet` — Alias Discovery\n\nParses `~\u002F.acfs\u002Fzsh\u002Facfs.zshrc` to show all installed aliases and commands.\n\n```bash\nacfs cheatsheet # List all aliases\nacfs cheatsheet git # Filter by category or search term\nacfs cheatsheet --category Agents\nacfs cheatsheet --search docker\nacfs cheatsheet --json # JSON output for tooling\n```\n\nExample output:\n```\n╔═══════════════════════════════════════════════════════════════╗\n║ ACFS Cheatsheet ║\n╠═══════════════════════════════════════════════════════════════╣\n║ Agents ║\n║ cc → claude --dangerously-skip-permissions ║\n║ cod → codex --dangerously-bypass-approvals-and-sandbox ║\n║ gmi → gemini --yolo ║\n║ ║\n║ Git ║\n║ gs → git status ║\n║ gp → git push ║\n║ gl → git pull ║\n║ gco → git checkout ║\n║ ║\n║ Modern CLI ║\n║ ls → lsd --inode --long --all ║\n║ cat → bat ║\n║ grep → rg ║\n║ lg → lazygit ║\n╚═══════════════════════════════════════════════════════════════╝\n```\n\n### `acfs dashboard` — HTML Status Page\n\nGenerates a self-contained HTML dashboard and optionally serves it.\n\n```bash\nacfs dashboard generate # Generate ~\u002F.acfs\u002Fdashboard\u002Findex.html\nacfs dashboard generate --force # Force regeneration\nacfs dashboard serve # Serve on localhost:8080\nacfs dashboard serve --port 3000 # Custom port\nacfs dashboard serve --public # Bind to 0.0.0.0\n```\n\nThe dashboard provides:\n- System health at a glance\n- Tool versions and status\n- Quick command reference\n- Recent activity summary\n\n### `acfs services-setup` — Credential Configuration\n\nInteractive wizard for configuring AI agent credentials and cloud service logins.\n\n```bash\nacfs services-setup # Run full setup wizard\n```\n\nGuides you through:\n- **Claude Code**: API key configuration\n- **Codex CLI**: ChatGPT account login\n- **Gemini CLI**: Google account authentication\n- **GitHub CLI**: `gh auth login`\n- **Cloud CLIs**: Wrangler, Supabase, Vercel authentication\n\nAlso offers to install **DCG (Destructive Command Guard)**, a Claude Code hook that blocks destructive commands like `rm -rf \u002F`.\n\n### `acfs continue` — Upgrade Progress\n\nAfter an Ubuntu upgrade reboot, view installation progress:\n\n```bash\nacfs continue # Show current upgrade status\n```\n\nDisplays:\n- Original Ubuntu version\n- Target version\n- Current upgrade stage\n- Next steps after completion\n\n---\n\n## Learning Hub (Web)\n\nIn addition to the terminal-based onboarding, ACFS provides a comprehensive web-based Learning Hub at [agent-flywheel.com\u002Flearn](https:\u002F\u002Fagent-flywheel.com\u002Flearn).\n\n### Web Lessons\n\nThe Learning Hub provides interactive lessons with progress tracking:\n\n| # | Lesson | Duration | Topics |\n|---|--------|----------|--------|\n| 0 | Welcome & Overview | 5 min | What's installed, mental model |\n| 1 | Linux Navigation | 8 min | Filesystem structure, essential commands |\n| 2 | SSH & Persistence | 6 min | Secure connections, staying connected |\n| 3 | tmux Basics | 7 min | Sessions, windows, panes, survival |\n| 4 | Git Essentials | 10 min | Version control, dangerous operations |\n| 5 | GitHub CLI | 8 min | Issues, PRs, releases via `gh` |\n| 6 | Agent Commands | 10 min | Claude, Codex, Gemini usage |\n| 7 | NTM Command Center | 8 min | Session orchestration |\n| 8 | NTM Prompt Palette | 6 min | Quick command access |\n| 9 | The Flywheel Loop | 8 min | How all 10 tools work together |\n\n**Features:**\n- Progress tracking in localStorage\n- Code blocks with copy buttons\n- Expandable deep-dive sections\n- Practical exercises\n\n### Command Reference\n\nThe [Command Reference](https:\u002F\u002Fagent-flywheel.com\u002Flearn\u002Fcommands) documents every installed tool:\n\n| Category | Commands |\n|----------|----------|\n| **Agents** | `cc`, `cod`, `gmi` |\n| **Search** | `rg`, `fd`, `sg`, `fzf` |\n| **Git** | `lg`, `gh`, `git-lfs` |\n| **System** | `z`, `bat`, `lsd`, `atuin`, `tmux` |\n| **Stack** | `ntm`, `bv`, `am`, `cass`, `cm`, `ubs`, `slb`, `caam`, `dcg`, `ru` |\n| **Languages** | `bun`, `uv`, `cargo`, `go` |\n| **Cloud** | `wrangler`, `supabase`, `vercel`, `vault` |\n\n### Technical Glossary\n\nThe [Glossary](https:\u002F\u002Fagent-flywheel.com\u002Fglossary) defines 100+ technical terms with:\n\n- **One-liner**: Quick tooltip definition\n- **Full explanation**: Plain language description\n- **Analogy**: \"Think of it like...\"\n- **Why we use it**: Problem it solves\n- **Related terms**: For context\n\nExample entry:\n```\nRAM (Random Access Memory)\n├── Short: Fast temporary storage your computer uses while working\n├── Long: RAM is your computer's short-term memory...\n├── Analogy: Like your desk space while working\n├── Why: More RAM = run more programs simultaneously\n└── Related: vCPU, VPS, NVMe\n```\n\n### Flywheel Visualization\n\nThe [Flywheel page](https:\u002F\u002Fagent-flywheel.com\u002Fflywheel) visualizes tool interactions:\n\n```\nPlan (Beads) ──> Coordinate (Agent Mail) ──> Execute (NTM + Agents)\n ^ │\n │ v\n └──── Remember (CASS Memory) \u003C──── Scan (UBS) ┘\n```\n\n**Workflow Scenarios:**\n\n| Scenario | Description | Time |\n|----------|-------------|------|\n| Daily Parallel Progress | 3+ projects moving simultaneously | 3+ hours |\n| Agents Reviewing Agents | Cross-review before merging | 30 min |\n| Memory-Augmented Debugging | Past solutions for current bugs | 15 min |\n| Coordinated Feature Dev | Multiple agents, one feature | 2+ hours |\n\n### Tool Status Page\n\nThe [Tool Status page](https:\u002F\u002Fagent-flywheel.com\u002Ftools) provides a searchable catalog of all installed tools:\n\n- **Search & Filter**: Find tools by name, CLI command, features, or tech stack\n- **Category Browsing**: Filter by \"Flywheel Stack\" (core agentic tools) or \"Utilities\"\n- **Tool Details**: Each card shows the tool name, CLI command, GitHub stars, features, and tech stack\n- **Live Data**: Content is auto-generated from `acfs.manifest.yaml` — never manually edited\n\nThis page helps users discover tools they may not know about and understand how each fits into the agentic coding workflow.\n\n### Interactive Website Components\n\nThe wizard website includes specialized components for guiding beginners:\n\n**ConnectionCheck Component:**\nA prominent visual that helps users verify they're connected to their VPS before running commands:\n- Side-by-side comparison: \"Wrong (laptop)\" vs \"Right (VPS)\"\n- Terminal prompt examples for Windows, Mac, and Linux\n- Clear \"STOP!\" warning with color-coded styling\n\n**CommandCard Component:**\nCLI instruction cards with:\n- Syntax-highlighted code blocks\n- One-click copy button\n- Platform-specific variations (bash\u002Fzsh\u002FPowerShell)\n- Expandable explanations\n\n**Jargon Component (Responsive Technical Terms):**\nA sophisticated tooltip system that adapts to device capabilities:\n\n*Desktop behavior:*\n- Hover reveals floating tooltip with term definition\n- Radix UI Tooltip for accessible ARIA-compliant overlays\n- Viewport-aware positioning (auto-flips when near edges)\n- 200ms hover delay prevents tooltip spam\n\n*Mobile behavior:*\n- Tap opens bottom sheet drawer (Vaul library)\n- Full definition visible without tiny tap targets\n- Swipe-to-dismiss gesture support\n- Snap points for partial\u002Ffull expansion\n\n*Visual features:*\n- Gradient underline indicates tappable term\n- Each term gets unique gradient based on slug hash\n- Consistent color scheme with OKLCH tokens\n\n*Content structure per term:*\n```typescript\n{\n term: \"VPS\",\n short: \"Virtual Private Server - a remote computer you rent\",\n long: \"A VPS is your own slice of a powerful computer...\",\n analogy: \"Think of it like renting an apartment in a building\",\n whyWeUseIt: \"You get root access, dedicated resources...\",\n relatedTerms: [\"SSH\", \"Ubuntu\", \"RAM\"]\n}\n```\n\n**Confetti Celebration:**\nOn lesson completion:\n- Burst of celebratory confetti particles\n- Randomized encouraging messages\n- Special celebration for completing all lessons\n- Respects `prefers-reduced-motion` setting\n\n**Stepper Component:**\nMulti-step progress indicator:\n- Visual step-by-step progress\n- Clickable navigation\n- Completion checkmarks\n- Mobile-responsive design\n\n### Expanded Lesson Library\n\nThe Learning Hub includes specialized lessons for each tool in the Dicklesworthstone stack:\n\n| Lesson | Topics |\n|--------|--------|\n| **UBS (Bug Scanner)** | Scan workflow, severity levels, CI integration |\n| **Agent Mail** | Registration, messaging, file reservations |\n| **CASS (Session Search)** | Indexing, searching, cross-agent queries |\n| **CASS Memory (cm)** | Rule extraction, playbook management |\n| **Beads** | Issue tracking, graph metrics, priorities |\n| **SLB (Safety)** | Two-person rule, dangerous command approval |\n| **Prompt Engineering** | Effective prompts, context management |\n| **Real-World Case Study** | End-to-end feature development walkthrough |\n\nEach lesson includes:\n- Conceptual introduction\n- Practical commands with examples\n- Interactive exercises\n- Common pitfalls to avoid\n- Links to tool documentation\n\n---\n\n## Interactive Onboarding (TUI)\n\nAfter installation, users can learn the ACFS workflow through an interactive terminal-based tutorial. The onboarding TUI discovers lesson markdown files dynamically from `acfs\u002Fonboard\u002Flessons`, so the curriculum can grow as new tools and workflows are added without changing the launcher.\n\n### Running Onboarding\n\n```bash\nonboard # Launch interactive menu\nonboard status # Show completion status\nonboard --list # Alias for status\nonboard 3 # Jump to lesson 3\nonboard reset # Reset progress and start fresh\nonboard --reset # Alias for reset\n```\n\n### Lessons\n\nRun `onboard --help` to see the currently discovered lesson list. The curriculum currently spans Linux basics, SSH, tmux, agent login, NTM, the flywheel workflow, updating, Beads, RCH, and other ACFS tools. Because lessons are discovered by filename, adding a new `NN_name.md` file automatically extends the tutorial.\n\n### Progress Tracking\n\nProgress is saved in `~\u002F.acfs\u002Fonboard_progress.json`:\n\n```json\n{\n \"completed\": [0, 1, 2],\n \"current\": 3,\n \"started_at\": \"2024-12-20T10:30:00-05:00\"\n}\n```\n\nThe TUI shows completion status for each lesson and suggests the next one to take. Users can jump to any lesson or re-take completed ones.\n\n### Enhanced UX with Gum\n\nIf [Charmbracelet Gum](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fgum) is installed, the onboarding system uses it for enhanced terminal UI—selection menus, styled prompts, and better formatting. Without Gum, it falls back to simple numbered menus that work everywhere.\n\n---\n\n## Tools Installed\n\nACFS installs a comprehensive suite of **30+ tools** organized into categories:\n\n### Shell & Terminal UX\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **zsh** | `zsh` | Modern shell |\n| **oh-my-zsh** | - | zsh plugin framework |\n| **powerlevel10k** | - | Fast, customizable prompt |\n| **lsd** | `ls` (aliased) | Modern ls with icons |\n| **atuin** | `Ctrl+R` | Shell history with search |\n| **fzf** | `fzf` | Fuzzy finder |\n| **zoxide** | `z` | Smarter cd |\n| **direnv** | - | Directory-specific env vars |\n\n### Languages & Package Managers\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **bun** | `bun` | Fast JS\u002FTS runtime + package manager |\n| **uv** | `uv` | Fast Python package manager |\n| **Rust** | `cargo` | Rust toolchain |\n| **Go** | `go` | Go toolchain |\n\n### Dev Tools\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **tmux** | `tmux` | Terminal multiplexer |\n| **ripgrep** | `rg` | Fast recursive grep |\n| **ast-grep** | `sg` | Structural code search |\n| **lazygit** | `lg` (aliased) | Git TUI |\n| **GitHub CLI** | `gh` | GitHub auth, issues, PRs |\n| **Git LFS** | `git-lfs` | Large file support for Git |\n| **bat** | `cat` (aliased) | Cat with syntax highlighting |\n| **neovim** | `nvim` | Modern vim |\n| **jq** | `jq` | JSON processor |\n| **rsync** | `rsync` | Fast file sync\u002Fcopy |\n| **lsof** | `lsof` | Debug open files\u002Fports |\n| **dnsutils** | `dig` | DNS debugging |\n| **netcat** | `nc` | Network debugging |\n| **strace** | `strace` | Syscall tracing |\n\n### Networking\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **Tailscale** | `tailscale` | Zero-config mesh VPN |\n\n**Tailscale Integration:**\n\nTailscale provides secure, encrypted networking between your devices without complex firewall configuration:\n\n```bash\n# Authenticate and join your tailnet\ntailscale up\n\n# Check connection status\ntailscale status\n\n# Get your Tailscale IP\ntailscale ip\n\n# SSH over Tailscale (bypasses firewalls)\nssh ubuntu@your-vps.tailnet-name.ts.net\n```\n\nBenefits for agentic workflows:\n- **Firewall-free access**: Connect even when behind NAT or restrictive firewalls\n- **MagicDNS**: Access your VPS by hostname instead of IP\n- **SSH keys over Tailscale**: Use `tailscale ssh` for key-free authentication\n- **ACLs**: Fine-grained access control for team environments\n\n### AI Coding Agents\n\n| Agent | Command | Alias (Vibe Mode) |\n|-------|---------|-------------------|\n| **Claude Code** | `claude` | `cc` (dangerous mode) |\n| **Codex CLI** | `codex` | `cod` (dangerous mode) |\n| **Gemini CLI** | `gemini` | `gmi` (dangerous mode) |\n\n**Vibe Mode Aliases:**\n```bash\n# Claude Code with max memory (background tasks enabled by default)\nalias cc='NODE_OPTIONS=\"--max-old-space-size=32768\" claude --dangerously-skip-permissions'\n\n# Codex with bypass and dangerous filesystem access\nalias cod='codex --dangerously-bypass-approvals-and-sandbox'\n\n# Gemini with yolo mode\nalias gmi='gemini --yolo'\n```\n\n**Installation & Updates:**\nClaude Code should be installed and updated using its native mechanisms:\n- **Install:** ACFS uses the official native installer (`claude.ai\u002Finstall.sh`), checksum-verified via `checksums.yaml` (installs to `~\u002F.local\u002Fbin\u002Fclaude`)\n- **Update:** Use `claude update --channel latest` (built-in) or run `acfs update --agents-only`\n\nThis ensures proper authentication handling and avoids issues with alternative package manager builds. For Codex and Gemini, ACFS uses standard bun global package updates.\n\n### Cloud & Database\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **PostgreSQL 18** | `psql` | Database |\n| **HashiCorp Vault** | `vault` | Secrets management |\n| **Wrangler** | `wrangler` | Cloudflare CLI |\n| **Supabase CLI** | `supabase` | Supabase management |\n| **Vercel CLI** | `vercel` | Vercel deployment |\n\nVault is installed by default (skip with `--skip-vault`). ACFS installs the Vault **CLI** so you have a real secrets tool available early; it does not automatically configure a Vault server for you.\n\nSupabase networking note: some Supabase projects expose the **direct Postgres host over IPv6-only** (often on free tiers). If your VPS\u002Fnetwork is **IPv4-only**, use the Supabase **pooler** connection string instead (or upgrade\u002Fconfigure networking for direct IPv4).\n\n### Dicklesworthstone Stack (10 Tools)\n\nThe complete suite of tools for professional agentic workflows:\n\n| # | Tool | Command | Description |\n|---|------|---------|-------------|\n| 1 | **Named Tmux Manager** | `ntm` | Agent cockpit—spawn, orchestrate, monitor tmux sessions |\n| 2 | **MCP Agent Mail** | `am` | Agent coordination via mail-like messaging (Rust binary) |\n| 3 | **Ultimate Bug Scanner** | `ubs` | Bug scanning with guardrails |\n| 4 | **Beads Viewer** | `bv` | Task management TUI with graph analysis |\n| 5 | **Coding Agent Session Search** | `cass` | Unified agent history search |\n| 6 | **CASS Memory System** | `cm` | Procedural memory for agents |\n| 7 | **Coding Agent Account Manager** | `caam` | Agent auth switching |\n| 8 | **Simultaneous Launch Button** | `slb` | Two-person rule for dangerous commands |\n| 9 | **Destructive Command Guard** | `dcg` | Claude Code hook blocking dangerous git\u002Ffs commands |\n| 10 | **Repo Updater** | `ru` | Multi-repo sync + AI-driven commit automation |\n\n### Bundled Utilities\n\nAdditional productivity tools installed alongside the stack:\n\n| Tool | Command | Description |\n|------|---------|-------------|\n| **Get Image from Internet Link** | `giil` | Download images from iCloud, Dropbox, Google Photos for visual debugging |\n| **Chat Shared Conversation to File** | `csctf` | Convert AI share links (ChatGPT, Gemini, Claude) to Markdown\u002FHTML |\n\n---\n\n## Doctor Command\n\n`acfs doctor` performs comprehensive health checks on your installation:\n\n```bash\n$ acfs doctor\n\n╔══════════════════════════════════════════════════════════════╗\n║ ACFS Health Check ║\n╠══════════════════════════════════════════════════════════════╣\n║ Identity ║\n║ ✔ Running as ubuntu user ║\n║ ✔ Passwordless sudo enabled ║\n║ ║\n║ Workspace ║\n║ ✔ \u002Fdata\u002Fprojects exists ║\n║ ║\n║ Shell ║\n║ ✔ zsh installed ║\n║ ✔ oh-my-zsh installed ║\n║ ✔ powerlevel10k installed ║\n║ ✔ acfs.zshrc sourced ║\n║ ║\n║ Core Tools ║\n║ ✔ bun 1.2.16 ║\n║ ✔ uv 0.5.14 ║\n║ ✔ cargo 1.84.0 ║\n║ ✔ go 1.23.4 ║\n║ ✔ ripgrep 14.1.0 ║\n║ ✔ ast-grep 0.30.1 ║\n║ ║\n║ Agents ║\n║ ✔ claude 1.0.24 ║\n║ ✔ codex 0.1.2504252326 ║\n║ ✔ gemini 0.1.12 ║\n║ ║\n║ Cloud ║\n║ ✔ vault 1.18.3 ║\n║ ✔ wrangler 4.16.0 ║\n║ ✔ supabase 2.23.4 ║\n║ ✔ vercel 41.7.6 ║\n║ ║\n║ Dicklesworthstone Stack ║\n║ ✔ ntm 0.3.2 ║\n║ ✔ slb 0.2.1 ║\n║ ✔ ubs 0.1.8 ║\n║ ✔ bv 0.9.4 ║\n║ ✔ cass 0.4.2 ║\n║ ✔ cm 0.1.3 ║\n║ ✔ caam 0.2.0 ║\n║ ✔ dcg 0.1.0 ║\n║ ✔ ru 1.2.0 ║\n║ ⚠ mcp_agent_mail (not running) ║\n║ ║\n║ Utilities ║\n║ ✔ giil 3.0.0 ║\n║ ✔ csctf 1.0.0 ║\n╠══════════════════════════════════════════════════════════════╣\n║ Overall: 35\u002F36 checks passed ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n### Generated Doctor Checks\n\nDoctor checks are generated from the manifest (`scripts\u002Fgenerated\u002Fdoctor_checks.sh`) to keep verification logic close to `acfs.manifest.yaml`. The `acfs doctor` command automatically sources these generated checks to verify all manifest-defined tools.\n\n**How it works:**\n1. The manifest generator creates `doctor_checks.sh` with verify commands for each module\n2. `acfs doctor` sources this file and runs each verification check\n3. Failed checks display a **fix suggestion** with the exact command to reinstall\n\n**Example output with fix suggestion:**\n```\n ✗ tools.lazygit - Lazygit terminal UI not found\n Fix: acfs install --only tools.lazygit\n```\n\nThis architecture ensures doctor checks stay in sync with the installer—if a tool is in the manifest, it will be verified.\n\n### Options\n\n```bash\nacfs doctor # Interactive colorful output\nacfs doctor --json # Machine-readable JSON output\nacfs doctor --quiet # Exit code only (0=healthy, 1=issues)\nacfs doctor --deep # Run functional tests (auth, connections)\nacfs doctor --fix # Apply safe fixes for failed checks\nacfs doctor --dry-run # Preview fixes without applying\nacfs doctor --no-cache # Skip cache, run all checks fresh\n```\n\n### Deep Checks (`--deep`)\n\nThe `--deep` flag runs functional tests beyond binary existence:\n\n| Category | Checks |\n|----------|--------|\n| **Agent Auth** | Claude config, Codex OAuth, Gemini credentials |\n| **Database** | PostgreSQL connection, ubuntu role exists |\n| **Cloud CLIs** | `gh auth status`, `wrangler whoami`, Supabase\u002FVercel tokens |\n| **Vault** | `VAULT_ADDR` configured |\n\nDeep checks use 5-second timeouts to avoid hanging on network issues. Results are cached for 5 minutes to speed up repeated runs.\n\nExample output:\n```\nDeep Checks\n ✔ Claude auth configured\n ✔ PostgreSQL connection working\n ⚠ Codex not authenticated (run: codex login)\n ✔ GitHub CLI authenticated\n\n8\u002F9 functional tests passed in 3.2s\n```\n\n### Auto-Fix Mode (`--fix`)\n\nThe `--fix` flag automatically applies safe, deterministic fixes for common issues:\n\n```bash\nacfs doctor --fix # Apply safe fixes\nacfs doctor --fix --dry-run # Preview fixes without applying\n```\n\n#### Safe Auto-Fixers\n\nThese fixes are applied automatically when `--fix` is used:\n\n| Fix ID | Description | Undo Strategy |\n|--------|-------------|---------------|\n| `fix.path.ordering` | Prepend ACFS directories to PATH in .zshrc | Restore backup |\n| `fix.config.copy` | Copy missing ~\u002F.acfs config files | Remove copied file |\n| `fix.dcg.hook` | Install DCG pre-tool-use hook | Run `dcg uninstall` |\n| `fix.symlink.create` | Create missing tool symlinks | Remove symlink |\n| `fix.plugin.clone` | Clone missing zsh plugins | Remove cloned directory |\n| `fix.acfs.sourcing` | Add ACFS sourcing to .zshrc | Restore backup |\n\n#### Safety Guarantees\n\n- **Never deletes user files** — Only creates, modifies, or symlinks\n- **Backups before modify** — SHA256-verified backups of all modified files\n- **Idempotent** — Safe to run multiple times\n- **Logged** — All changes recorded to `~\u002F.local\u002Fshare\u002Facfs\u002Fdoctor.log`\n- **Reversible** — Every fix has an undo command\n\n#### Example Dry-Run Output\n\n```\nDRY-RUN: acfs doctor --fix\n\nWould apply the following fixes:\n\n [fix.path.ordering]\n Action: Prepend PATH directories to ~\u002F.zshrc\n File: ~\u002F.zshrc\n Backup: Yes (SHA256 verified)\n\n [fix.acfs.sourcing]\n Action: Add ACFS sourcing to .zshrc\n File: ~\u002F.zshrc\n Backup: Yes (SHA256 verified)\n\nFixes that require manual action:\n [shell.ohmyzsh]\n Status: FAIL\n Suggestion: curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fohmyzsh\u002Fohmyzsh\u002Fmaster\u002Ftools\u002Finstall.sh | bash\n\nSummary: 2 auto-fixes, 0 prompted, 1 manual\n```\n\n#### Manual-Only Fixes\n\nSome operations are never auto-fixed and instead provide suggestions:\n\n- Package manager operations (`apt install ...`)\n- Anything requiring sudo\n- File deletions\n- Complex shell configuration changes\n\n#### Undoing Changes\n\nAll changes made by `--fix` can be undone:\n\n```bash\nacfs undo --list # List all changes\nacfs undo chg_0001 # Undo specific change\nacfs undo --all # Undo all changes from last session\n```\n\n---\n\n## The Wizard Website\n\nThe wizard guides beginners through a **13-step journey** from \"I have a laptop\" to \"AI agents are coding for me\":\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ ACFS Wizard [Step 3\u002F13] │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌────────────────────────────────────────────────────────────────────────┐ │\n│ │ STEP 3: Generate SSH Key │ │\n│ │ ────────────────────────────────────────────────────────────────── │ │\n│ │ │ │\n│ │ Run this command in your terminal: │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │\n│ │ │ ssh-keygen -t ed25519 -C \"your-email@example.com\" [📋] │ │ │\n│ │ └─────────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ☐ I ran this command │ │\n│ │ │ │\n│ │ [← Previous] [Next Step →] │ │\n│ └────────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ Progress: ●●●○○○○○○○○○○ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Wizard Steps\n\n| Step | Title | What Happens |\n|------|-------|--------------|\n| 1 | **Choose Your OS** | Select Mac, Windows, or Linux (auto-detected) |\n| 2 | **Install Terminal** | Get a proper terminal application set up |\n| 3 | **Generate SSH Key** | Create an ed25519 key for VPS access |\n| 4 | **Rent a VPS** | Choose a VPS provider and plan |\n| 5 | **Create VPS Instance** | Launch your VPS and confirm SSH access |\n| 6 | **SSH Into Your VPS** | First connection with troubleshooting tips |\n| 7 | **Set Up Accounts** | Create accounts for the services you'll use |\n| 8 | **Pre-Flight Check** | Verify your VPS is ready before installing |\n| 9 | **Run Installer** | The `curl \\| bash` one-liner |\n| 10 | **Reconnect as Ubuntu** | Post-install reconnection |\n| 11 | **Verify Key Connection** | Reconnect using your SSH key and confirm it works |\n| 12 | **Status Check** | Run `acfs doctor` to verify |\n| 13 | **Launch Onboarding** | Start the interactive tutorial |\n\n### Key Features\n\n- **OS Detection:** Auto-detects Mac vs Windows for tailored instructions\n- **Copy-to-Clipboard:** One-click copy for all commands\n- **Progress Tracking:** localStorage persistence across browser sessions\n- **Confirmation Checkboxes:** \"I ran this command\" acknowledgments\n- **Troubleshooting:** Expandable help for common issues\n\n### Technology Stack\n\n```\nNext.js 16 (App Router)\n├── React 19\n├── Tailwind CSS 4 (OKLCH colors)\n├── shadcn\u002Fui components\n├── Radix UI primitives\n└── Lucide icons\n```\n\n**No backend required.** All state is stored in:\n- URL query parameters\n- localStorage (`agent-flywheel-user-os`, `agent-flywheel-vps-ip`, `agent-flywheel-wizard-completed-steps`)\n\n### Wizard State Management\n\nThe wizard uses **TanStack Query** for state management with optimistic updates and cross-tab synchronization:\n\n**Architecture:**\n```typescript\n\u002F\u002F Query-based state with localStorage persistence\nconst { data: steps } = useQuery({\n queryKey: ['wizardSteps', 'completed'],\n queryFn: getCompletedSteps, \u002F\u002F Reads from localStorage\n staleTime: 0, \u002F\u002F Always check for updates\n gcTime: Infinity, \u002F\u002F Never garbage collect\n});\n```\n\n**Optimistic Updates with Rollback:**\n```typescript\nconst mutation = useMutation({\n mutationFn: async (stepId) => {\n const newSteps = addCompletedStep(currentSteps, stepId);\n setCompletedSteps(newSteps); \u002F\u002F Persist to localStorage\n return newSteps;\n },\n onMutate: (stepId) => {\n \u002F\u002F Optimistically update cache immediately\n const previousSteps = queryClient.getQueryData(queryKey);\n queryClient.setQueryData(queryKey, addCompletedStep(baseSteps, stepId));\n return { previousSteps }; \u002F\u002F For rollback\n },\n onError: (_err, _stepId, context) => {\n \u002F\u002F Rollback on failure\n queryClient.setQueryData(queryKey, context.previousSteps);\n },\n});\n```\n\n**Cross-Tab Synchronization:**\nThe wizard maintains sync across browser tabs via two mechanisms:\n1. **Custom DOM events** for same-tab coordination between components\n2. **Storage events** for cross-tab updates when localStorage changes\n\n```typescript\n\u002F\u002F Same-tab: custom event dispatch\nwindow.dispatchEvent(new CustomEvent('acfs:wizard:completed-steps-changed', {\n detail: { steps }\n}));\n\n\u002F\u002F Cross-tab: storage event listener\nwindow.addEventListener('storage', (event) => {\n if (event.key === COMPLETED_STEPS_KEY) {\n queryClient.setQueryData(queryKey, getCompletedSteps());\n }\n});\n```\n\n**Safe localStorage Utilities:**\nAll localStorage access is wrapped in safe utilities that handle SSR, private browsing, and quota exceeded errors:\n\n```typescript\n\u002F\u002F Safe read (returns null on any error)\nexport function safeGetJSON\u003CT>(key: string): T | null;\n\n\u002F\u002F Safe write (returns boolean success)\nexport function safeSetJSON(key: string, value: unknown): boolean;\n\n\u002F\u002F URL preservation for state fallback\nexport function withCurrentSearch(path: string): string;\n```\n\nThis architecture ensures the wizard progress survives browser refreshes, works across tabs, and degrades gracefully when localStorage is unavailable.\n\n---\n\n## Configuration Files\n\nACFS deploys optimized configuration files to `~\u002F.acfs\u002F` on the target VPS.\n\n### `~\u002F.acfs\u002Fzsh\u002Facfs.zshrc`\n\nA comprehensive zsh configuration that's sourced by `~\u002F.zshrc`:\n\n**Oh-My-Zsh Plugins (14 total):**\n\n| Plugin | Category | What It Provides |\n|--------|----------|------------------|\n| `git` | VCS | 150+ git aliases (gs, gp, gl, gco, gcm, etc.) |\n| `sudo` | Shell | Double-tap Esc to prefix previous command with sudo |\n| `colored-man-pages` | Shell | Colorized man pages for better readability |\n| `command-not-found` | Shell | Suggests packages when command not found |\n| `docker` | Containers | Docker command completion and aliases |\n| `docker-compose` | Containers | docker-compose completion and aliases |\n| `python` | Lang | Python aliases (pyfind, pyclean, pygrep) |\n| `pip` | Lang | pip completion and cache management |\n| `tmux` | Terminal | tmux aliases (ta, tad, ts, tl, tkss) |\n| `tmuxinator` | Terminal | tmuxinator project completion |\n| `systemd` | System | systemctl aliases (sc-status, sc-start, sc-stop) |\n| `rsync` | Tools | rsync completion and common flag aliases |\n| `zsh-autosuggestions` | UX | Fish-like autosuggestions from history |\n| `zsh-syntax-highlighting` | UX | Real-time command syntax highlighting |\n\n> **Note**: `zsh-autosuggestions` and `zsh-syntax-highlighting` are custom plugins installed from GitHub. They must be listed last for optimal performance.\n\n**Path Configuration:**\n```bash\nexport PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.cargo\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002Fgo\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.bun\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.atuin\u002Fbin:$PATH\"\n```\n\n**Modern CLI Aliases:**\n```bash\nalias ls='lsd --inode --long --all'\nalias ll='lsd -l'\nalias tree='lsd --tree'\nalias cat='bat'\nalias grep='rg'\nalias vim='nvim'\nalias lg='lazygit'\n```\n\n**Tool Integrations:**\n```bash\n# Atuin (better shell history)\neval \"$(atuin init zsh)\"\n\n# Zoxide (smarter cd)\neval \"$(zoxide init zsh)\"\n\n# direnv (directory env vars)\neval \"$(direnv hook zsh)\"\n\n# fzf (fuzzy finder)\nsource \u002Fusr\u002Fshare\u002Fdoc\u002Ffzf\u002Fexamples\u002Fkey-bindings.zsh\n```\n\n**Shell Keybindings (Quality of Life):**\n\n| Keybind | Action | Notes |\n|---------|--------|-------|\n| `Ctrl+→` | Forward word | Navigate by word |\n| `Ctrl+←` | Backward word | Navigate by word |\n| `Alt+→` | Forward word | Alternative binding |\n| `Alt+←` | Backward word | Alternative binding |\n| `Ctrl+Backspace` | Delete word backward | Fast deletion |\n| `Ctrl+Delete` | Delete word forward | Fast deletion |\n| `Home` | Beginning of line | Works in all terminals |\n| `End` | End of line | Works in all terminals |\n| `Ctrl+R` | Atuin history search | Interactive fuzzy search |\n\n**Atuin History Bindings:**\nThe config forces Atuin bindings to load last (after OMZ plugins) ensuring `Ctrl+R` triggers Atuin's fuzzy history search rather than zsh's default:\n\n```bash\n# Forced at end of zshrc\nbindkey -e # Emacs mode\nbindkey -M emacs '^R' atuin-search\nbindkey -M viins '^R' atuin-search-viins\nbindkey -M vicmd '^R' atuin-search-vicmd\n```\n\n### `~\u002F.acfs\u002Ftmux\u002Ftmux.conf`\n\nA tmux configuration specifically optimized for NTM and multi-agent workflows:\n\n**Key Bindings:**\n```\nPrefix: Ctrl+a (not Ctrl+b - more ergonomic)\nSplit horizontal: | (preserves working directory)\nSplit vertical: - (preserves working directory)\nNavigate panes: h\u002Fj\u002Fk\u002Fl (vim-style)\nResize panes: H\u002FJ\u002FK\u002FL (repeatable with -r flag)\nReload config: r\nNew window: c (preserves working directory)\n```\n\n**Copy Mode (vim-style):**\n```\nEnter copy mode: prefix + [\nBegin selection: v\nRectangle selection: r\nCopy and exit: y\n```\n\n**Agent Workflow Optimizations:**\n\n| Setting | Value | Purpose |\n|---------|-------|---------|\n| `history-limit` | 50,000 | Extended scrollback for long agent sessions |\n| `escape-time` | 10ms | Faster key response (reduced from default 500ms) |\n| `focus-events` | on | Enables vim\u002Fneovim autoread in agent windows |\n| `detach-on-destroy` | off | NTM compatibility—don't detach when session ends |\n| `monitor-activity` | on | Track agent window activity |\n| `visual-activity` | off | Silent monitoring (no bell) |\n\n**Catppuccin-Inspired Theme:**\n```bash\n# Status bar (top position, less intrusive)\nstatus-style: bg=#1e1e2e, fg=#cdd6f4\n\n# Session indicator (blue accent)\nstatus-left: #[fg=#89b4fa,bold] #S\n\n# Active window highlight (pink accent)\nwindow-status-current-format: #[fg=#f5c2e7,bold] #I:#W\n\n# Pane borders\npane-border-style: fg=#313244\npane-active-border-style: fg=#89b4fa # Blue highlight\n```\n\n**Local Overrides:**\nThe config sources `~\u002F.tmux.conf.local` if it exists, allowing personal customizations without modifying ACFS defaults.\n\n---\n\n## Library Modules\n\nThe installer is organized into modular Bash libraries in `scripts\u002Flib\u002F`:\n\n### `logging.sh`\n\nColored console output utilities:\n\n```bash\nlog_step \"1\u002F8\" \"Installing packages...\" # Blue step indicator\nlog_detail \"Installing zsh...\" # Gray indented detail\nlog_success \"Complete\" # Green checkmark\nlog_warn \"May take a while\" # Yellow warning\nlog_error \"Failed\" # Red error\nlog_fatal \"Cannot continue\" # Red error + exit 1\n```\n\n### `security.sh`\n\nHTTPS enforcement and checksum verification:\n\n```bash\nenforce_https \"$url\" # Fail if not HTTPS\nverify_checksum \"$url\" \"$sha256\" \"$name\" # Verify before execute\nfetch_and_run \"$url\" \"$sha256\" \"$name\" # Verify + execute in one\n```\n\n### `os_detect.sh`\n\nOS detection and validation:\n\n```bash\ndetect_os() # Sets OS_ID, OS_VERSION, OS_CODENAME\nvalidate_os() # Checks for Ubuntu 25.10 (or upgrade path)\nis_fresh_vps() # Heuristic detection of fresh VPS\nget_arch() # Returns amd64\u002Farm64\nis_wsl() # Detects WSL\nis_docker() # Detects Docker container\n```\n\n### `user.sh`\n\nUser account normalization:\n\n```bash\nensure_user() # Creates ubuntu user if missing\nenable_passwordless_sudo() # Adds NOPASSWD to sudoers\nmigrate_ssh_keys() # Copies keys from root to ubuntu\nnormalize_user() # Full normalization sequence\n```\n\n### `update.sh`\n\nComponent update logic with version tracking and logging:\n\n```bash\nupdate_apt() # apt update\u002Fupgrade with lock detection\nupdate_bun() # bun upgrade with version tracking\nupdate_agents() # Claude, Codex, Gemini (version before\u002Fafter)\nupdate_cloud() # Wrangler, Supabase, Vercel (Supabase uses verified release tarball)\nupdate_rust() # rustup update stable\nupdate_uv() # uv self update\nupdate_go() # Go toolchain update\nupdate_shell() # OMZ, P10K, plugins, Atuin, Zoxide\nupdate_stack() # Dicklesworthstone stack tools\n\n# Features:\n# - Automatic logging to ~\u002F.acfs\u002Flogs\u002Fupdates\u002F\n# - Version tracking (before\u002Fafter for each tool)\n# - APT lock detection and warning\n# - Reboot-required detection for kernel updates\n# - Dry-run mode with --dry-run flag\n```\n\n### `gum_ui.sh`\n\nEnhanced terminal UI using Charmbracelet Gum:\n\n```bash\nprint_banner() # ASCII art ACFS banner\ngum_step\u002Fgum_detail # Styled output\ngum_success\u002Fwarn\u002Ferror # Colored messages\ngum_spin # Spinner for long operations\ngum_confirm # Yes\u002FNo prompt\ngum_choose # Selection menu\n```\n\nFalls back to basic echo if Gum is not installed.\n\n### `error_tracking.sh`\n\nSophisticated error collection and reporting:\n\n```bash\ntrack_error \"phase\" \"step\" \"error_message\"\ntrack_warning \"phase\" \"step\" \"warning_message\"\nget_error_report # Generate structured error report\nget_error_count # Count of tracked errors\nhas_errors # Boolean check for any errors\n```\n\nFeatures:\n- Collects errors without aborting execution\n- Associates errors with phase and step context\n- Generates end-of-run summary reports\n- Distinguishes warnings from errors\n\n### `state.sh`\n\nState machine management for installation progress (v3 schema):\n\n```bash\nstate_init # Initialize state file\nstate_get_phase # Current phase\nstate_set_phase \"phase_name\" # Set current phase\nstate_mark_complete \"phase_name\" # Mark phase complete\nstate_has_completed \"phase_name\" # Check if phase done\nstate_save # Persist to disk (atomic)\nstate_load # Load from disk\n```\n\nThe state file (`~\u002F.acfs\u002Fstate.json`) uses atomic writes to prevent corruption.\n\n### `contract.sh`\n\nRuntime contract validation for generated scripts:\n\n```bash\nacfs_require_contract \"module_id\" # Assert environment is ready\nacfs_check_contract # Non-fatal contract check\n```\n\nValidates that required environment variables and functions exist before execution:\n- `TARGET_USER`, `TARGET_HOME`, `MODE`\n- `ACFS_BOOTSTRAP_DIR`, `ACFS_LIB_DIR`\n- Logging functions: `log_detail`, `log_success`, etc.\n\n### `smoke_test.sh`\n\nPost-install verification that runs automatically after installation:\n\n```bash\nrun_smoke_test # Execute all smoke tests\n```\n\n**Critical Checks** (must pass):\n- Running as ubuntu user\n- Passwordless sudo enabled\n- Zsh is default shell\n- Core tools accessible (bun, uv, cargo)\n\n**Non-Critical Checks** (warnings only):\n- Agent authentication configured\n- Cloud CLIs authenticated\n- Optional tools installed\n\nExample output:\n```\n[Smoke Test]\n ✅ Running as ubuntu user\n ✅ Passwordless sudo enabled\n ✅ Zsh is default shell\n ✅ bun --version works\n ⚠️ Codex not authenticated (run: codex login)\n ✅ 8\u002F9 checks passed\n```\n\n### `session.sh`\n\nAgent session export functionality for sharing and replay:\n\n```bash\nsession_export \"claude-code\" \"session_id\" \"\u002Foutput\u002Fpath\"\nsession_list # List exportable sessions\nsession_validate \"\u002Fexport\u002Ffile.json\"\n```\n\nImplements the **Session Export Schema** for cross-agent sharing:\n\n```typescript\ninterface SessionExport {\n schema_version: 1;\n exported_at: string; \u002F\u002F ISO8601\n session_id: string;\n agent: \"claude-code\" | \"codex\" | \"gemini\";\n model: string;\n summary: string;\n duration_minutes: number;\n stats: {\n turns: number;\n files_created: number;\n files_modified: number;\n commands_run: number;\n };\n outcomes: Array\u003C{\n type: \"file_created\" | \"file_modified\" | \"command_run\";\n path?: string;\n description: string;\n }>;\n key_prompts: string[]; \u002F\u002F Notable prompts for learning\n sanitized_transcript: Array\u003C{\n role: \"user\" | \"assistant\";\n content: string;\n timestamp: string;\n }>;\n}\n```\n\n### `tailscale.sh`\n\nZero-config VPN setup for secure remote access:\n\n```bash\ninstall_tailscale # Install via official APT repo\nverify_tailscale # Check installation\ntailscale_status # Get connection status\n```\n\nTailscale provides:\n- **Secure mesh networking** between your devices\n- **SSH over Tailscale** for firewall-free access\n- **MagicDNS** for hostname-based addressing\n- **ACL-based access control**\n\nAfter installation, run `tailscale up` to authenticate and join your tailnet.\n\n### `ubuntu_upgrade.sh`\n\nMulti-reboot Ubuntu version upgrade automation:\n\n```bash\nstart_ubuntu_upgrade # Begin upgrade chain\ncheck_upgrade_status # Current upgrade state\nresume_upgrade_after_reboot # Continue after reboot\n```\n\nHandles the complex multi-step Ubuntu upgrade process:\n1. Detects current version\n2. Calculates upgrade path (e.g., 24.04 → 25.04 → 25.10)\n3. Performs sequential `do-release-upgrade` operations\n4. Installs systemd service for post-reboot resume\n5. Continues ACFS installation after reaching target\n\n---\n\n## MCP Agent Mail Integration\n\nACFS includes integration with **MCP Agent Mail** for multi-agent coordination:\n\n### What Agent Mail Provides\n\n- **Identities:** Each agent registers with a unique name\n- **Inbox\u002FOutbox:** Message-based communication between agents\n- **File Reservations:** Advisory leases to prevent agents from clobbering each other's work\n- **Searchable Threads:** Full-text search across all messages\n- **Git Persistence:** All artifacts stored in git for human auditability\n\n### Core Patterns\n\n**1. Register Identity:**\n```bash\n# In your agent, call:\nmcp.ensure_project(project_key=\"\u002Fdata\u002Fprojects\u002Fmy-project\")\nmcp.register_agent(project_key=..., program=\"claude-code\", model=\"opus-4.5\")\n```\n\n**2. Reserve Files Before Editing:**\n```bash\nmcp.file_reservation_paths(\n project_key=...,\n agent_name=\"BlueLake\",\n paths=[\"src\u002F**\"],\n ttl_seconds=3600,\n exclusive=true\n)\n```\n\n**3. Communicate:**\n```bash\nmcp.send_message(\n project_key=...,\n sender_name=\"BlueLake\",\n to=[\"GreenCastle\"],\n subject=\"Review needed\",\n body_md=\"Please review the auth changes...\"\n)\n```\n\n### Macros for Speed\n\nWhen speed matters more than fine-grained control:\n\n```bash\nmcp.macro_start_session(...) # Ensure project + register + fetch inbox\nmcp.macro_prepare_thread(...) # Align with existing thread\nmcp.macro_file_reservation_cycle(...) # Reserve + work + release\nmcp.macro_contact_handshake(...) # Request contact permissions\n```\n\n---\n\n## Destructive Command Guard (dcg)\n\n**dcg** is a high-performance Claude Code hook that blocks dangerous git and filesystem commands before they execute. Built in Rust for sub-millisecond latency, it provides mechanical enforcement of safety rules that instructions alone cannot guarantee.\n\n### Why dcg Exists\n\nOn December 17, 2025, an AI agent ran `git checkout --` on files containing hours of uncommitted work from a parallel coding session. The files were recovered via `git fsck --lost-found`, but the incident made one thing clear: instructions in `AGENTS.md` don't prevent execution. **dcg provides mechanical enforcement**.\n\n### What Gets Blocked\n\n| Category | Commands |\n|----------|----------|\n| **Git Reset** | `git reset --hard`, `git reset --merge` |\n| **File Discard** | `git checkout -- \u003Cfiles>`, `git restore \u003Cfiles>` |\n| **Force Push** | `git push --force` \u002F `-f` (allows `--force-with-lease`) |\n| **Clean** | `git clean -f` (allows `-n` dry-run) |\n| **Branch Delete** | `git branch -D` (allows `-d`) |\n| **Stash Loss** | `git stash drop`, `git stash clear` |\n| **Filesystem** | `rm -rf` (except temp directories) |\n\n### What Gets Allowed\n\nSafe variants are allowlisted:\n- `git checkout -b \u003Cbranch>` — Creates branch, doesn't touch files\n- `git restore --staged` — Only unstages, doesn't discard\n- `git clean -n` — Dry-run preview\n- `rm -rf \u002Ftmp\u002F...` — Temp directories are ephemeral\n\n### Installation\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fdestructive_command_guard\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n### Claude Code Configuration\n\nAdd to `~\u002F.claude\u002Fsettings.json`:\n\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [{\"type\": \"command\", \"command\": \"dcg\"}]\n }\n ]\n }\n}\n```\n\n### Modular Pack System\n\ndcg uses a modular pack system for extensibility. Enable additional packs in `~\u002F.config\u002Fdcg\u002Fconfig.toml`:\n\n```toml\n[packs]\nenabled = [\n \"database.postgresql\",\n \"containers.docker\",\n \"kubernetes\",\n]\n```\n\nAvailable packs: `database.*`, `containers.*`, `kubernetes.*`, `cloud.*`, `infrastructure.*`, `system.*`, `package_managers`.\n\n---\n\n## Repo Updater (ru)\n\n**ru** is a production-grade CLI tool for synchronizing collections of GitHub repositories and automating commit workflows across dirty repos with AI assistance.\n\n### Core Features\n\n- **Multi-repo sync**: Clone missing repos, pull updates, detect conflicts\n- **Agent sweep**: AI-driven commit automation across repositories with uncommitted changes\n- **AI code review**: Orchestrate Claude Code review sessions for open issues\u002FPRs\n- **Work-stealing queue**: Parallel execution with load-balanced workers\n- **NTM integration**: Session management via Named Tmux Manager\n\n### Quick Start\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Frepo_updater\u002Fmain\u002Finstall.sh?ru_cb=$(date +%s)\" | bash\n```\n\nInitialize configuration:\n\n```bash\n# Initialize configuration\nru init --example\n\n# Sync all repositories\nru sync\n\n# Check status without changes\nru status\n```\n\n### Agent Sweep Workflow\n\nThe `agent-sweep` command automates commits across dirty repositories:\n\n```bash\n# Preview repos to process\nru agent-sweep --dry-run\n\n# Full automation with AI\nru agent-sweep --parallel 4\n\n# Include release automation\nru agent-sweep --with-release\n```\n\n**Three-Phase Workflow:**\n1. **Planning**: Claude Code analyzes changes, generates commit message\n2. **Commit**: Validates plan, stages files, runs quality gates\n3. **Release**: (Optional) Creates version tag and GitHub release\n\n### Configuration\n\n```bash\n# ~\u002F.config\u002Fru\u002Fconfig\nPROJECTS_DIR=\u002Fdata\u002Fprojects\nLAYOUT=flat # flat|owner-repo|full\nUPDATE_STRATEGY=ff-only # ff-only|rebase|merge\nPARALLEL=4\n```\n\n**Repo list format** (`~\u002F.config\u002Fru\u002Frepos.d\u002Fpublic.txt`):\n```\nowner\u002Frepo\nowner\u002Frepo@develop # Pin to branch\nowner\u002Frepo as custom-name # Custom directory name\n```\n\n---\n\n## Get Image from Internet Link (giil)\n\n**giil** downloads full-resolution images from cloud photo shares to your terminal. Essential for remote debugging workflows where you need to analyze screenshots in SSH sessions.\n\n### Supported Platforms\n\n| Platform | Method | Speed |\n|----------|--------|-------|\n| **iCloud** | 4-tier capture strategy | 5-15s |\n| **Dropbox** | Direct curl download | 1-2s |\n| **Google Photos** | Network interception | 5-15s |\n| **Google Drive** | Multi-tier with auth detection | 5-15s |\n\n### Usage\n\n```bash\n# Basic download\ngiil \"https:\u002F\u002Fshare.icloud.com\u002Fphotos\u002F02cD9okNHvVd-uuDnPCH3ZEEA\"\n# Output: \u002Fcurrent\u002Fdir\u002Ficloud_20240115_143245.jpg\n\n# Download to specific directory\ngiil \"...\" --output ~\u002FDownloads\n\n# Get JSON metadata\ngiil \"...\" --json\n\n# Download all photos from album\ngiil \"...\" --all --output ~\u002Falbum\n```\n\n### Installation\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fgiil\u002Fmain\u002Finstall.sh?v=3.0.0\" | bash\n```\n\n### Visual Debugging Workflow\n\n1. Screenshot UI bug on iPhone\n2. Wait for iCloud sync to Mac\n3. Share via Photos.app → Copy iCloud Link\n4. Paste link into remote terminal running Claude Code\n5. `giil` fetches the image locally\n6. AI assistant analyzes the screenshot\n\n---\n\n## Chat Shared Conversation to File (csctf)\n\n**csctf** converts public AI conversation share links into clean, searchable Markdown and HTML transcripts. Perfect for archiving AI conversations, building knowledge bases, and sharing with teams.\n\n### Supported Providers\n\n| Provider | URL Pattern |\n|----------|------------|\n| **ChatGPT** | `chatgpt.com\u002Fshare\u002F*` |\n| **Gemini** | `gemini.google.com\u002Fshare\u002F*` |\n| **Grok** | `grok.com\u002Fshare\u002F*` |\n| **Claude** | `claude.ai\u002Fshare\u002F*` |\n\n### Usage\n\n```bash\n# Basic conversion\ncsctf https:\u002F\u002Fchatgpt.com\u002Fshare\u002F69343092-91ac-800b-996c-7552461b9b70\n# Creates: \u003Cslug>.md and \u003Cslug>.html\n\n# Markdown only\ncsctf \"...\" --md-only\n\n# Publish to GitHub Pages\ncsctf \"...\" --publish-to-gh-pages --yes\n\n# JSON metadata output\ncsctf \"...\" --json\n```\n\n### Installation\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fchat_shared_conversation_to_file\u002Fmain\u002Finstall.sh | bash\n```\n\n### Output Features\n\n- **Markdown**: Clean formatting with preserved code blocks and language hints\n- **HTML**: Zero-JavaScript static page with syntax highlighting\n- **Deterministic filenames**: `\u003Cslug>_YYYYMMDD.md` for reliable archival\n- **Collision handling**: Auto-increments suffix to avoid overwrites\n\n---\n\n## CI\u002FCD\n\nACFS uses GitHub Actions for continuous integration:\n\n### Installer Testing (`installer.yml`)\n\n```yaml\n# Runs on every push and PR\njobs:\n shellcheck:\n - Lints all bash scripts with ShellCheck\n\n integration:\n - Matrix tests across Ubuntu 24.04, 25.04, 25.10\n - Runs full installation in Docker\n - Verifies all tools installed correctly\n - Runs acfs doctor to confirm health\n```\n\nThis ensures the installer works on all supported Ubuntu versions and catches shell scripting issues early.\n\n### Website Deployment (`website.yml`)\n\n```yaml\n# Builds and deploys the Next.js wizard\njobs:\n build:\n - Type-check TypeScript\n - Run ESLint\n - Build production bundle\n\n deploy:\n - Deploy to Vercel (production)\n```\n\n### Automated Checksum + Drift Repair (`checksum-monitor.yml`)\n\nACFS automatically monitors upstream installers for changes, and also repairs generated artifact checksum drift:\n\n```yaml\n# Runs every 2 hours + on upstream changes\nschedule: \"0 *\u002F2 * * *\"\ntriggers:\n - Schedule (every 2 hours)\n - Webhook from upstream repos (repository_dispatch)\n - Pushes touching installer\u002Fchecksum\u002Fgenerator files\n```\n\n**How It Works:**\n\n1. **Verify Generated Artifact Drift**: Runs `scripts\u002Fcheck-manifest-drift.sh --json` to detect:\n - `ACFS_MANIFEST_SHA256` mismatches\n - internal script checksum drift (`scripts\u002Fgenerated\u002Finternal_checksums.sh`)\n2. **Auto-Repair Drift**: If drift is detected, runs `--fix` (regenerate + commit + push)\n3. **Verify Current Upstream Checksums**: Downloads all upstream installers, calculates SHA256\n4. **Detect Upstream Changes**: Compares against `checksums.yaml`\n5. **Categorize Tools**: Separates \"trusted\" tools (can auto-update) from others\n6. **Auto-Update Upstream Checksums**: Commits updated `checksums.yaml` when safe\n7. **Alert**: For non-trusted tool changes, creates GitHub issue for manual review\n\nThe monitor **fails closed** when verification returns fetch errors or skipped entries; it will not emit partial\u002Fplaceholder checksum updates.\n\n**Trusted Tools (Auto-Update Enabled):**\n- Dicklesworthstone stack tools (ntm, cass, cm, ubs, slb, dcg, caam, bv, agent-mail, ru)\n- These are maintained by the same author, so upstream changes are implicitly trusted\n\n**Non-Trusted Tools (Manual Review Required):**\n- Third-party installers (bun, uv, rust, oh-my-zsh, atuin, zoxide, nvm)\n- Changes trigger a GitHub issue with diff details for human review\n\nThis ensures:\n- **Security**: Third-party changes are reviewed before deployment\n- **Velocity**: Internal tool updates are deployed automatically\n- **Auditability**: All changes tracked via git commits\n\n**Upstream Repo Dispatch (Fast Path):**\n- ACFS-owned tool repos emit a `repository_dispatch` event (`upstream-changed`) when their `install.sh` changes or a release is published.\n- Requires a PAT secret named `ACFS_REPO_DISPATCH_TOKEN` in each tool repo (repo scope for this org\u002Fuser).\n- If dispatch fails, the 2-hour scheduled monitor still catches drift (but slower).\n\n### Production Smoke Tests (`production-smoke.yml`)\n\nValidates deployments on real environments:\n\n```yaml\n# Runs after deployment\njobs:\n smoke:\n - Fetches install.sh from production URL\n - Verifies checksum matches repository\n - Validates shell syntax\n - Confirms no uncommitted drift\n```\n\n### Installer Canary (Docker) (`installer-canary.yml`)\n\nRuns the **full installer end-to-end** inside fresh Ubuntu containers on a daily schedule.\n\n```yaml\nschedule: \"30 7 * * *\" # daily\njobs:\n canary:\n - Run tests\u002Fvm\u002Ftest_install_ubuntu.sh (vibe mode)\n - Uses ACFS_CHECKSUMS_REF=main for freshest hashes\n```\n\n### Playwright E2E Tests (`playwright.yml`)\n\nFull browser testing of the wizard website:\n\n```yaml\n# Runs on PR to main\nbrowsers:\n - Chromium\n - Firefox\n - WebKit\n - Mobile Chrome\n - Mobile Safari\n\ntests:\n - Wizard flow completion\n - Step navigation\n - Copy button functionality\n - Responsive design\n```\n\n---\n\n## VPS Providers\n\nACFS works on any Ubuntu VPS with SSH key login. Here are recommended providers optimized for multi-agent workloads.\n\n> **Why 48-64GB RAM?** Each AI coding agent uses ~2GB RAM. To run 10-20+ agents simultaneously, you need 48GB+ RAM. Don't bottleneck a $400+\u002Fmonth AI investment to save $20 on hosting.\n\n### Contabo (Best Value — Top Pick)\n\n| Plan | RAM | vCPU | Storage | Price | Notes |\n|------|-----|------|---------|-------|-------|\n| **Cloud VPS 50** | 64GB | 16 | 400GB NVMe | ~$56\u002Fmo (US) | **Recommended** — Best for serious multi-agent work |\n| Cloud VPS 40 | 48GB | 12 | 300GB NVMe | ~$36\u002Fmo (US) | Budget option, still comfortable |\n\n- Best specs-to-price ratio on the market\n- Month-to-month pricing, no commitment required\n- US datacenter pricing includes ~$10\u002Fmonth premium\n\n### OVH (Great Alternative)\n\n| Plan | RAM | vCore | Storage | Price | Notes |\n|------|-----|-------|---------|-------|-------|\n| **VPS-5** | 64GB | 16 | 320GB NVMe | ~$40\u002Fmo | **Recommended** — Great EU and US datacenters |\n| VPS-4 | 48GB | 12 | 240GB NVMe | ~$26\u002Fmo | Budget option |\n\n- Anti-DDoS included\n- Month-to-month, 5-15% discount for longer commitments\n- Typically faster activation than Contabo\n\n### Requirements\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| **OS** | Ubuntu 22.04+ (auto-upgraded) | Ubuntu 25.10 |\n| **RAM** | 32GB (tight) | 48-64GB |\n| **Storage** | 250GB NVMe SSD | 300GB+ NVMe SSD |\n| **CPU** | 12 vCPU | 16 vCPU |\n| **Price** | ~$26\u002Fmo | ~$40-56\u002Fmo |\n\n### Other Providers\n\nAny provider with Ubuntu VPS and SSH key login works. The wizard at [agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) has step-by-step guides.\n\n### Provider Setup Guides\n\nACFS includes detailed step-by-step guides for each supported provider in `scripts\u002Fproviders\u002F`:\n\n| Provider | Guide | Key Sections |\n|----------|-------|--------------|\n| **Contabo** | `contabo.md` | Account creation, plan selection, data center choice, SSH key setup |\n| **OVH** | `ovh.md` | Control panel navigation, instance configuration, networking |\n| **Hetzner** | `hetzner.md` | Project setup, firewall rules, console access |\n\nEach guide includes:\n- **Screenshots** for every step (in `scripts\u002Fproviders\u002Fscreenshots\u002F`)\n- **Pricing breakdowns** with recommendations\n- **Region selection** guidance (latency, privacy)\n- **SSH key** configuration specific to that provider\n- **Troubleshooting** for common provisioning issues\n\n**Provider Comparison:**\n\n| Aspect | Contabo | OVH | Hetzner |\n|--------|---------|-----|---------|\n| Best For | Maximum value | EU data residency | German engineering |\n| Provisioning | 1-3 hours | 5-30 minutes | 2-10 minutes |\n| Support | Email only | Phone + chat | 24\u002F7 ticket system |\n| Data Centers | EU, US, Asia | Global | EU only |\n| Payment | Monthly | Hourly or monthly | Hourly or monthly |\n\n**Recommendation Flow:**\n1. **Budget**: Contabo (best specs per dollar)\n2. **Speed**: Hetzner (instant provisioning)\n3. **Support**: OVH (phone support available)\n4. **Privacy**: Any EU provider (GDPR compliance)\n\n---\n\n## Project Structure\n\n```\nagentic_coding_flywheel_setup\u002F\n├── README.md # This file\n├── AGENTS.md # Development guidelines\n├── VERSION # Current version (0.2.0)\n├── install.sh # Main installer entry point\n├── acfs.manifest.yaml # Canonical tool manifest (510 lines)\n├── checksums.yaml # SHA256 hashes for upstream scripts\n├── package.json # Root monorepo config\n│\n├── apps\u002F\n│ └── web\u002F # Next.js 16 wizard website\n│ ├── app\u002F # App Router pages\n│ │ ├── layout.tsx # Root layout\n│ │ ├── page.tsx # Landing page\n│ │ └── wizard\u002F # Wizard step pages\n│ ├── components\u002F # UI components\n│ └── lib\u002F # Utilities\n│\n├── packages\u002F\n│ ├── manifest\u002F # Manifest parser + generator\n│ │ └── src\u002F\n│ │ ├── parser.ts # YAML parsing\n│ │ ├── schema.ts # Zod validation schemas\n│ │ ├── types.ts # TypeScript types\n│ │ ├── utils.ts # Helper functions\n│ │ └── generate.ts # Script generator\n│ ├── installer\u002F # Installer helper scripts\n│ └── onboard\u002F # Onboard TUI source\n│\n├── acfs\u002F # Files deployed to ~\u002F.acfs\u002F\n│ ├── zsh\u002F\n│ │ └── acfs.zshrc # Shell configuration\n│ ├── tmux\u002F\n│ │ └── tmux.conf # Tmux configuration\n│ └── onboard\u002F\n│ ├── onboard.sh # Onboarding TUI script\n│ └── lessons\u002F # Tutorial markdown (11 files)\n│\n├── scripts\u002F\n│ ├── lib\u002F # Installer bash libraries\n│ │ ├── logging.sh # Console output\n│ │ ├── security.sh # HTTPS + checksum verification\n│ │ ├── os_detect.sh # OS detection\n│ │ ├── user.sh # User management\n│ │ ├── zsh.sh # Shell setup\n│ │ ├── update.sh # Update command logic\n│ │ ├── gum_ui.sh # Enhanced UI\n│ │ ├── cli_tools.sh # Tool installation\n│ │ └── doctor.sh # Health checks\n│ ├── generated\u002F # Auto-generated from manifest\n│ │ ├── install_base.sh # Base packages\n│ │ ├── install_shell.sh # Shell tools\n│ │ ├── install_cli.sh # CLI tools\n│ │ ├── install_lang.sh # Language runtimes\n│ │ ├── install_agents.sh # AI coding agents\n│ │ ├── install_cloud.sh # Cloud CLIs\n│ │ ├── install_stack.sh # Dicklesworthstone stack\n│ │ ├── install_all.sh # Master installer\n│ │ └── doctor_checks.sh # Verification checks\n│ ├── providers\u002F # VPS provider guides\n│ │ ├── ovh.md\n│ │ ├── contabo.md\n│ │ └── hetzner.md\n│ └── sync\u002F\n│ └── sync_ntm_palette.sh # Sync NTM command palette\n│\n├── .github\u002F\n│ └── workflows\u002F\n│ ├── installer.yml # ShellCheck + Ubuntu matrix tests\n│ └── website.yml # Next.js build + deploy\n│\n└── tests\u002F\n └── vm\u002F\n └── test_install_ubuntu.sh # Docker integration test\n```\n\n---\n\n## Development\n\n### Website Development\n\n```bash\ncd apps\u002Fweb\nbun install # Install dependencies\nbun run dev # Dev server at http:\u002F\u002Flocalhost:3000\nbun run build # Production build\nbun run lint # Lint check\nbun run type-check # TypeScript check\n```\n\n### Manifest Development\n\n```bash\ncd packages\u002Fmanifest\nbun install # Install dependencies\nbun run generate # Generate installer scripts\nbun run generate:dry # Preview without writing files\n```\n\n### Installer Testing\n\n```bash\n# Local lint\nshellcheck install.sh scripts\u002Flib\u002F*.sh\n\n# Full installer integration test (Docker, same as CI)\n.\u002Ftests\u002Fvm\u002Ftest_install_ubuntu.sh\n```\n\n### Security Verification\n\n```bash\n# Print all upstream URLs\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --print\n\n# Verify all checksums\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --verify\n\n# Update checksums after reviewing upstream changes\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums > checksums.yaml\n```\n\n### Manifest Validation\n\nThe manifest parser includes comprehensive validation beyond basic schema checking:\n\n**Validation Error Codes:**\n\n| Code | Description |\n|------|-------------|\n| `MISSING_DEPENDENCY` | Module references non-existent dependency |\n| `DEPENDENCY_CYCLE` | Circular dependency detected (A→B→C→A) |\n| `PHASE_VIOLATION` | Module runs before its dependencies |\n| `FUNCTION_NAME_COLLISION` | Two modules generate same bash function |\n| `RESERVED_NAME_COLLISION` | Module uses reserved identifier |\n| `INVALID_VERIFIED_INSTALLER_RUNNER` | Runner not in allowlist (bash\u002Fsh only) |\n\n**Running Validation:**\n```bash\ncd packages\u002Fmanifest\nbun run validate # Full validation\nbun run validate --verbose # Show all checks\n```\n\n**Cycle Detection Algorithm:**\n```\nTarjan's strongly connected components (SCC):\n1. DFS with discovery\u002Flow-link tracking\n2. Identify SCCs with size > 1 as cycles\n3. Report cycle path for human debugging\n```\n\n### Test Harness\n\nACFS includes a comprehensive test harness (`tests\u002Fvm\u002Flib\u002Ftest_harness.sh`) for integration testing:\n\n```bash\n# Source the harness\nsource tests\u002Fvm\u002Flib\u002Ftest_harness.sh\n\n# Initialize test suite\nharness_init \"ACFS Installation Tests\"\n\n# Create test sections\nharness_section \"Phase 1: Base Packages\"\n\n# Run commands with automatic logging\nharness_run \"Installing curl\" apt install -y curl\n\n# Assert results\nharness_pass \"curl installed successfully\"\nharness_fail \"curl installation failed\"\nharness_skip \"Skipping optional test\"\n\n# Generate summary\nharness_summary # Outputs: 15 passed, 0 failed, 2 skipped\n```\n\n**Test Files:**\n\n| Test | Purpose |\n|------|---------|\n| `test_install_ubuntu.sh` | Full Docker-based installation |\n| `test_acfs_update.sh` | Update mechanism validation |\n| `bootstrap_offline_checks.sh` | Offline system readiness |\n| `resume_checks.sh` | State resume validation |\n| `selection_checks.sh` | Module selection unit tests |\n| `selection_e2e.sh` | End-to-end selection flow |\n\n**Running Tests:**\n```bash\n# Full Docker integration test\n.\u002Ftests\u002Fvm\u002Ftest_install_ubuntu.sh\n\n# Selection logic tests\n.\u002Ftests\u002Fvm\u002Fselection_checks.sh\n\n# Web E2E tests\n.\u002Ftests\u002Fweb\u002Frun_e2e.sh\n```\n\n### Sync Scripts\n\nSync scripts keep ACFS documentation aligned with upstream projects:\n\n```bash\n# Sync NTM command palette from upstream\n.\u002Fscripts\u002Fsync\u002Fsync_ntm_palette.sh\n\n# Check if update available (without downloading)\n.\u002Fscripts\u002Fsync\u002Fsync_ntm_palette.sh --check\n```\n\n**Current Sync Sources:**\n\n| Script | Source | Destination |\n|--------|--------|-------------|\n| `sync_ntm_palette.sh` | NTM repo `command_palette.md` | `acfs\u002Fonboard\u002Fdocs\u002Fntm\u002F` |\n\nAll sync scripts use the security library for HTTPS enforcement and content hashing.\n\n### Website Design System\n\nThe website uses a comprehensive design system (`apps\u002Fweb\u002Flib\u002Fdesign-tokens.ts`):\n\n**Color Tokens (OKLCH Color Space):**\n```typescript\n\u002F\u002F Perceptually uniform colors\ncolors: {\n cyan: \"oklch(0.75 0.18 195)\", \u002F\u002F Primary accent\n pink: \"oklch(0.7 0.2 330)\", \u002F\u002F Secondary accent\n purple: \"oklch(0.65 0.18 290)\", \u002F\u002F Tertiary\n success: \"oklch(0.72 0.19 145)\", \u002F\u002F Green\n warning: \"oklch(0.78 0.16 75)\", \u002F\u002F Yellow\n error: \"oklch(0.65 0.22 25)\", \u002F\u002F Red\n}\n```\n\n**Shadow Tokens:**\n```typescript\nshadows: {\n cardHover: \"0 20px 40px -12px oklch(0.75 0.18 195 \u002F 0.15)\",\n cardLifted: \"0 25px 50px -12px oklch(0.75 0.18 195 \u002F 0.2)\",\n primaryGlow: \"0 0 40px -8px oklch(0.75 0.18 195 \u002F 0.3)\",\n}\n```\n\n**Animation Presets:**\n```typescript\nanimations: {\n hover: { scale: 1.02, transition: { duration: 0.2 } },\n tap: { scale: 0.98 },\n fadeIn: { opacity: [0, 1], transition: { duration: 0.3 } },\n}\n```\n\n**Accessibility:**\n- Reduced motion support via `useReducedMotion` hook\n- Semantic HTML structure\n- ARIA labels on interactive elements\n- Keyboard navigation support\n\n### Requirements\n\n- **Runtime:** Bun (not npm\u002Fyarn\u002Fpnpm)\n- **Node:** Latest\n- **Shell:** Bash 5+\n\n---\n\n## FAQ\n\n### Why \"Vibe Mode\"?\n\nVibe mode is designed for **throwaway VPS environments** where velocity matters more than safety:\n- Passwordless sudo eliminates friction\n- Agent dangerous flags skip confirmation dialogs\n- Pre-configured aliases for maximum speed\n\n**Never use vibe mode on production or shared systems.**\n\n### Can I use this on my local machine?\n\nACFS is designed for fresh Ubuntu VPS instances. While you *could* run it locally:\n- It may conflict with existing configurations\n- It assumes root\u002Fsudo access\n- It's not designed for macOS or Windows\n\nFor local development, use the individual tools directly.\n\n### What if the installer fails?\n\nThe installer is **checkpointed**. Simply re-run it:\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\nIt will skip already-completed phases and resume where it left off.\n\n### How do I update tools?\n\nUse the built-in update command:\n```bash\nacfs update # Update all standard components\nacfs update --stack # Include Dicklesworthstone stack\nacfs update --agents-only # Just update AI agents\n```\n\n### How do I uninstall?\n\nThere's no uninstall script. To reset:\n1. Delete the VPS instance\n2. Create a new one\n3. Run the installer fresh\n\nThis is intentional—ACFS is designed for ephemeral VPS environments.\n\n### Can I customize which tools are installed?\n\nCurrently, ACFS installs the full suite. Future versions will support:\n- Manifest-based tool selection\n- Interactive mode for choosing components\n- Modular installation scripts\n\n---\n\n## Why ACFS Exists\n\n### The Problem: The Agentic Coding Barrier\n\nThe rise of AI coding agents (Claude Code, Codex CLI, Gemini CLI) has created a new paradigm in software development. These agents can write code, debug issues, and even architect solutions—but only if they have the right environment.\n\n**The barrier isn't the agents themselves.** It's the **hours of setup** required to create an environment where agents can actually be productive:\n\n```\n┌────────────────────────────────────────────────────────────────────────────┐\n│ TIME INVESTMENT WITHOUT ACFS │\n│ │\n│ VPS Setup ..................... 30-60 min │\n│ Shell Configuration ........... 20-30 min │\n│ Language Runtimes ............. 30-45 min │\n│ Dev Tools ..................... 20-30 min │\n│ Agent Installation ............ 15-30 min │\n│ Agent Configuration ........... 20-40 min │\n│ Coordination Tools ............ 30-60 min │\n│ Troubleshooting ............... 30-120 min │\n│ ───────────────────────────────────────── │\n│ TOTAL: 3-7 hours (and that's if everything works) │\n│ │\n│ TIME INVESTMENT WITH ACFS │\n│ │\n│ Run one command ............... 25-30 min │\n│ ───────────────────────────────────────── │\n│ TOTAL: 30 minutes │\n└────────────────────────────────────────────────────────────────────────────┘\n```\n\n**ACFS eliminates this barrier entirely.** One command, 30 minutes, fully configured.\n\n### The Deeper Problem: Beginners Can't Start\n\nFor experienced developers, the setup is tedious but doable. For beginners—the people who would benefit *most* from AI coding assistance—it's an insurmountable wall:\n\n- What's SSH? How do I generate keys?\n- What's a VPS? How do I rent one?\n- What's a terminal? Which one should I use?\n- How do I connect to a remote server?\n- What are all these tools and why do I need them?\n\nThe [wizard website at agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) solves this by providing:\n\n1. **Absolute beginner guidance** — Explains every concept in plain English\n2. **OS-specific instructions** — Detects Mac vs Windows, shows the right commands\n3. **Visual confirmations** — Checkboxes for each step, copy buttons for commands\n4. **Troubleshooting help** — Expandable sections for common problems\n5. **Progress persistence** — Resume where you left off across browser sessions\n\n---\n\n## The 10x Multiplier Effect\n\nACFS isn't just a collection of tools—it's a **carefully curated system** where each component amplifies the others. The value isn't additive; it's multiplicative.\n\n### Tool Synergy Model\n\n```\n ┌─────────────────┐\n │ PRODUCTIVITY │\n │ MULTIPLIER │\n └────────┬────────┘\n │\n ┌─────────────────────────────┼─────────────────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ ENVIRONMENT │ │ AGENTS │ │ COORDINATION │\n│ LAYER │ │ LAYER │ │ LAYER │\n├─────────────────┤ ├─────────────────┤ ├─────────────────┤\n│ • zsh + p10k │────────▶│ • Claude Code │────────▶│ • Agent Mail │\n│ • tmux │ │ • Codex CLI │ │ • NTM │\n│ • Modern CLI │ │ • Gemini CLI │ │ • SLB + DCG │\n│ • Language VMs │ │ │ │ • Beads Viewer │\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │ │ │\n │ Each layer enables │ Agents become more │\n │ the next layer │ powerful together │\n └─────────────────────────────┴─────────────────────────────┘\n```\n\n### Why These Specific Tools?\n\nEvery tool in ACFS earns its place through **concrete productivity gains**:\n\n| Tool | Individual Value | Synergy Value |\n|------|-----------------|---------------|\n| **tmux** | Persistent sessions | Agents can work while you're disconnected |\n| **NTM** | Organized sessions | One command spawns 10 agents in named windows |\n| **Agent Mail** | Message passing | Agents coordinate without conflicts |\n| **SLB** | Two-person rule | Dangerous operations require confirmation |\n| **DCG** | Command guardrails | Blocks destructive commands before execution |\n| **Beads Viewer** | Task tracking | Agents can see project state, avoid rework |\n| **atuin** | Shell history | Search commands across sessions, share patterns |\n| **zoxide** | Smart cd | `z proj` beats `cd ~\u002Fprojects\u002Fmy-long-name` |\n| **ripgrep** | Fast search | Agents find code 100x faster than grep |\n| **fzf** | Fuzzy finding | Interactive selection instead of typing paths |\n\n### The Compounding Effect\n\nA single agent with basic tooling is useful. Three agents with:\n- A shared project structure\n- Coordination via Agent Mail\n- Orchestration via NTM\n- Safety guardrails via SLB\n- DCG guard hook (blocks destructive commands before execution)\n- Task visibility via Beads\n\n...can accomplish in one day what would take a solo developer a week.\n\nTip: run `acfs services-setup` to configure logins, and enable DCG for destructive-command protection.\n\n**This is the flywheel effect in action.** Better tools → more capable agents → more code shipped → better understanding of what tools are needed → better tools.\n\n---\n\n## Design Algorithms & Decisions\n\nACFS implements several algorithmic patterns that ensure reliability and maintainability.\n\n### Idempotency Algorithm\n\nEvery installation function follows the **check-before-install** pattern:\n\n```bash\ninstall_tool() {\n if command_exists \"tool\"; then\n log_success \"tool already installed\"\n return 0\n fi\n\n # ... installation logic ...\n\n if command_exists \"tool\"; then\n log_success \"tool installed successfully\"\n return 0\n else\n log_error \"tool installation failed\"\n return 1\n fi\n}\n```\n\nThis guarantees:\n1. **Safe re-runs** — Running the installer twice doesn't break anything\n2. **Resume capability** — Failures don't require starting over\n3. **Declarative intent** — The end state is defined, not the transition\n\n### Checksum Verification Algorithm\n\nThe security system uses **content-addressable verification**:\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ VERIFICATION FLOW │\n│ │\n│ 1. Download script to memory (not disk) │\n│ 2. Calculate SHA256 of downloaded content │\n│ 3. Compare against stored hash in checksums.yaml │\n│ 4. If match → execute │\n│ 5. If mismatch → refuse execution, report discrepancy │\n│ │\n│ Key insight: We verify CONTENT, not just transport │\n│ (HTTPS only protects the channel, not the content at source) │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### Manifest-Driven Generation\n\nThe generator uses a **template expansion** pattern:\n\n1. **Parse** — Read YAML manifest, validate with Zod schemas\n2. **Transform** — Convert manifest entries to installation functions\n3. **Group** — Organize by category (base, shell, cli, lang, agents, etc.)\n4. **Generate** — Emit Bash scripts with consistent structure\n5. **Verify** — Generate doctor checks from verification commands\n\nThis ensures the manifest is the **single source of truth**—no drift between documentation, installer, and verification.\n\n### Code Generator Architecture\n\nThe manifest generator (`packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts`) is a sophisticated TypeScript program that transforms YAML into bash:\n\n**Input Processing:**\n```typescript\n\u002F\u002F 1. Parse YAML with validation\nconst manifest = parseManifestFile(MANIFEST_PATH); \u002F\u002F Zod-validated\n\n\u002F\u002F 2. Load checksums for verified installers\nconst checksums = parseYaml(readFileSync(CHECKSUMS_PATH));\n\n\u002F\u002F 3. Topological sort for dependency order\nconst sorted = sortModulesByInstallOrder(manifest.modules);\n```\n\n**Security-First Code Generation:**\n```typescript\n\u002F\u002F Shell-safe quoting (prevents command injection)\nfunction shellQuote(s: string): string {\n return `'${s.replace(\u002F'\u002Fg, \"'\\\\''\")}'`;\n}\n\n\u002F\u002F Allowlisted runners only (belt-and-suspenders)\nconst ALLOWED_RUNNERS = ['bash', 'sh'] as const;\n\n\u002F\u002F Verified installer pipe construction\nfunction buildVerifiedInstallerPipe(module: Module, checksums: Checksums): string {\n \u002F\u002F Generates: curl -fsSL \"$URL\" | verify_checksum \"$SHA256\" | bash\n}\n```\n\n**Output Structure:**\n```\nscripts\u002Fgenerated\u002F\n├── install_base.sh # Base system packages (apt)\n├── install_users.sh # User normalization (ubuntu user)\n├── install_filesystem.sh # Directory structure (\u002Fdata\u002Fprojects)\n├── install_shell.sh # zsh + oh-my-zsh + p10k\n├── install_cli.sh # ripgrep, tmux, fzf, lazygit, etc.\n├── install_network.sh # Tailscale\n├── install_lang.sh # bun, uv, rust, go\n├── install_tools.sh # ast-grep, atuin, zoxide\n├── install_agents.sh # claude, codex, gemini\n├── install_db.sh # PostgreSQL 18, Vault\n├── install_cloud.sh # wrangler, supabase, vercel\n├── install_stack.sh # Dicklesworthstone 10-tool stack + utilities\n├── install_acfs.sh # ACFS config deployment\n├── install_all.sh # Orchestration helper\n├── doctor_checks.sh # Health verification\n└── manifest_index.sh # Module metadata arrays\n```\n\n**Generated Script Structure:**\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\n# AUTO-GENERATED FROM acfs.manifest.yaml - DO NOT EDIT\n\ninstall_module_id() {\n acfs_require_contract \"module.id\" # Validate environment\n\n if run_installed_check \"module.id\"; then\n log_step \"module.id already installed\"\n return 0\n fi\n\n set_phase \"Installing module...\"\n run_as_target_shell \u003C\u003C'HEREDOC'\n # Installation commands from manifest\n HEREDOC\n\n verify_module \"module.id\" # Post-install checks\n}\n```\n\n**Regeneration:**\n```bash\ncd packages\u002Fmanifest\nbun run generate # Full regeneration\nbun run generate:dry # Preview without writing\n```\n\n### Generated Manifest Index\n\nThe generator produces `manifest_index.sh`, a comprehensive bash metadata file that provides programmatic access to manifest data at runtime:\n\n**Associative Arrays:**\n```bash\n# Module metadata lookup\ndeclare -A ACFS_MODULE_DESCRIPTION\nACFS_MODULE_DESCRIPTION[\"lang.bun\"]=\"Bun JavaScript\u002FTypeScript runtime...\"\nACFS_MODULE_DESCRIPTION[\"agents.claude\"]=\"Claude Code CLI agent...\"\n\n# Phase mapping (determines install order)\ndeclare -A ACFS_MODULE_PHASE\nACFS_MODULE_PHASE[\"base.apt\"]=\"1\"\nACFS_MODULE_PHASE[\"lang.bun\"]=\"3\"\nACFS_MODULE_PHASE[\"agents.claude\"]=\"5\"\n\n# Dependency relationships (space-separated)\ndeclare -A ACFS_MODULE_DEPENDENCIES\nACFS_MODULE_DEPENDENCIES[\"agents.claude\"]=\"lang.bun base.system\"\n\n# Generated function name mapping\ndeclare -A ACFS_MODULE_FUNCTION\nACFS_MODULE_FUNCTION[\"lang.bun\"]=\"install_lang_bun\"\n\n# Category grouping\ndeclare -A ACFS_MODULE_CATEGORY\nACFS_MODULE_CATEGORY[\"lang.bun\"]=\"lang\"\n\n# Default inclusion in install\ndeclare -A ACFS_MODULE_DEFAULT\nACFS_MODULE_DEFAULT[\"lang.bun\"]=\"true\"\nACFS_MODULE_DEFAULT[\"db.postgres18\"]=\"true\"\n```\n\n**Runtime Query Functions:**\n```bash\n# Get all modules in a category\nget_modules_by_category \"agents\" # Returns: agents.claude agents.codex agents.gemini\n\n# Check if module is default-installed\nis_default_module \"tools.vault\" # Returns: true\n\n# Get installation phase\nget_module_phase \"stack.ntm\" # Returns: 6\n```\n\n**Use Cases:**\n- `acfs doctor` queries module metadata for health checks\n- `install.sh --list-modules` displays available modules\n- `--skip \u003Cmodule>` validates module existence before skipping\n- `--only-phase \u003Cn>` uses phase mapping for selective installs\n\nThe manifest index bridges the TypeScript generator with bash runtime, enabling sophisticated module selection logic while keeping the bash scripts simple.\n\n### Progressive Disclosure in the Wizard\n\nThe wizard website implements **progressive disclosure** for complexity management:\n\n```\nLevel 1: Core instructions (visible by default)\n├── Copy this command\n├── Paste in terminal\n└── Press Enter\n\nLevel 2: Troubleshooting (expandable)\n├── \"Permission denied\" → fix instructions\n├── \"Command not found\" → prerequisites\n└── \"Connection refused\" → diagnostics\n\nLevel 3: Deep explanations (collapsible \"Beginner Guide\")\n├── What is SSH?\n├── What is a VPS?\n├── Why these specific steps?\n└── What happens under the hood?\n```\n\nThis allows beginners to get deep context when needed, while experts can skip straight to the commands.\n\n---\n\n## Multi-Agent Orchestration Model\n\nACFS is designed for **multi-agent workflows** where several AI coding agents work on the same project simultaneously.\n\n### The Coordination Problem\n\nWithout coordination, multiple agents cause chaos:\n- **File conflicts** — Two agents edit the same file\n- **Duplicated work** — Agents solve the same problem independently\n- **Communication gaps** — No visibility into what others are doing\n- **Safety risks** — Dangerous operations without oversight\n\n### The ACFS Solution Stack\n\n```\n┌───────────────────────────────────────────────────────────────────────────┐\n│ AGENT COORDINATION LAYER │\n│ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ Agent Mail │ │ NTM │ │ SLB + DCG │ │ Beads │ │\n│ │ (Messaging) │ │ (Sessions) │ │ (Safety) │ │ (Tasks) │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │ │\n│ │ ┌────────────┴────────────────┴────────────────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ FILE RESERVATION SYSTEM │ │\n│ │ │ │\n│ │ Agent A reserves: src\u002Fauth\u002F** │ │\n│ │ Agent B reserves: src\u002Fapi\u002F** │ │\n│ │ Agent C reserves: tests\u002F** │ │\n│ │ │ │\n│ │ → No conflicts, parallel progress │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n```\n\n### Agent Communication Patterns\n\n**1. Direct Messaging (Agent Mail)**\n```\nAgent A → Agent B: \"I finished the auth module, ready for API integration\"\nAgent B → Agent A: \"ACK, starting API integration with auth dependency\"\n```\n\n**2. Broadcast Updates (Thread Summaries)**\n```\nThread: \"Sprint 23 Tasks\"\n├── Agent A: \"Claimed user-registration feature\"\n├── Agent B: \"Claimed api-endpoints feature\"\n├── Agent C: \"Claimed test-coverage task\"\n└── All agents see project state\n```\n\n**3. File Reservations (Conflict Prevention)**\n```\nAgent A: reserve_paths([\"src\u002Fauth\u002F*\"], exclusive=true, ttl=3600)\nAgent B: reserve_paths([\"src\u002Fauth\u002F*\"]) → CONFLICT: held by Agent A\nAgent B: reserve_paths([\"src\u002Fapi\u002F*\"]) → GRANTED\n```\n\n### The NTM Orchestration Pattern\n\nNamed Tmux Manager (NTM) enables the **one-command swarm spawn**:\n\n```bash\n# Spawn 10 agents, each in a named tmux window\nntm spawn \\\n --count 10 \\\n --prefix \"agent-\" \\\n --command \"claude --dangerously-skip-permissions\"\n```\n\nResult:\n```\ntmux session: acfs-swarm\n├── agent-1: Claude working on auth\n├── agent-2: Claude working on api\n├── agent-3: Claude working on tests\n├── agent-4: Codex reviewing PRs\n├── agent-5: Gemini writing docs\n└── ...\n```\n\n---\n\n## Philosophy\n\n### The Flywheel\n\nThe \"Agentic Coding Flywheel\" is a virtuous cycle:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ │\n│ Better Environment → More Agent Productivity → │\n│ More Code Written → Better Understanding → │\n│ Better Prompts → Better Environment │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nACFS kicks off this flywheel by providing the **best possible starting environment** for agentic coding.\n\n### Design Principles\n\n1. **Beginner-Friendly, Expert-Fast:** The wizard guides beginners; the one-liner serves experts.\n\n2. **Vibe-First:** Optimize for velocity in throwaway environments. Safety features exist in safe mode.\n\n3. **Idempotent:** Re-run without fear. The installer handles already-installed tools gracefully.\n\n4. **Single Source of Truth:** The manifest defines everything. Installer scripts are generated from it.\n\n5. **Security by Default:** HTTPS enforcement, checksum verification, no blind `curl | bash`.\n\n6. **Modern Defaults:** Latest versions, modern tools, optimal configurations out of the box.\n\n---\n\n## The Vibe Coding Manifesto\n\n\"Vibe coding\" isn't just a catchy name—it's a philosophy about how humans and AI should collaborate on software development.\n\n### What Is Vibe Coding?\n\nVibe coding is the practice of **directing AI agents to write code while you focus on intent, architecture, and quality**. Instead of typing every line yourself, you:\n\n1. **Describe what you want** in natural language\n2. **Review and guide** the agent's output\n3. **Iterate rapidly** through multiple approaches\n4. **Ship faster** while maintaining quality\n\nThe \"vibe\" comes from the flow state you enter when you're no longer fighting syntax, boilerplate, or implementation details—you're just vibing with your AI partner.\n\n### The Three Laws of Vibe Coding\n\n**1. Velocity Over Ceremony**\n\nTraditional development is ceremony-heavy: create branch, write tests first, implement, refactor, write docs, create PR, wait for review, merge, deploy. Each step has friction.\n\nVibe coding inverts this: ship fast, iterate faster. The AI handles boilerplate while you focus on the 10% that requires human judgment.\n\n```\nTraditional: Think → Plan → Implement → Test → Document → Ship\nVibe: Describe → Generate → Verify → Ship → Iterate\n```\n\n**2. Throwaway Environments Enable Boldness**\n\nThe magic of vibe coding happens on **ephemeral VPS instances**. When your environment is disposable:\n- You can experiment without fear\n- Catastrophic failures are just \"rebuild the VPS\"\n- Agents can have dangerous permissions (they can't break what's disposable)\n- You focus on output, not on protecting your setup\n\nThis is why ACFS's \"vibe mode\" enables passwordless sudo and dangerous agent flags—on a $5\u002Fmonth throwaway VPS, there's nothing worth protecting.\n\n**3. Multi-Agent Is The Default**\n\nOne agent is useful. Three agents working in parallel are transformative.\n\nVibe coding assumes you'll run multiple agents simultaneously:\n- Claude for complex reasoning and architecture\n- Codex for rapid prototyping and refactoring\n- Gemini for documentation and research\n\nACFS provides the coordination layer (Agent Mail, NTM, SLB) that makes this practical.\n\n### The Anti-Patterns\n\nVibe coding is **NOT**:\n- Blindly accepting agent output without review\n- Abandoning tests and quality standards\n- Ignoring security on production systems\n- Treating agents as replacements for understanding\n\nThe goal is **augmented human judgment**, not abdicated human judgment.\n\n### When NOT to Vibe Code\n\n- Production systems with real users\n- Security-critical infrastructure\n- Anything involving credentials or secrets\n- Long-running servers (use safe mode)\n- Shared team environments (use coordination tools)\n\nVibe coding is for **greenfield development, prototyping, experimentation, and learning**. Use ACFS's safe mode for everything else.\n\n---\n\n## State Machine & Checkpoint System\n\nACFS implements a robust **checkpoint-based state machine** that enables reliable resume-from-failure. This section explains how it works under the hood.\n\n### State File Format\n\nProgress is tracked in `~\u002F.acfs\u002Fstate.json`:\n\n```json\n{\n \"schema_version\": 3,\n \"started_at\": \"2024-12-21T10:30:00Z\",\n \"last_updated\": \"2024-12-21T10:45:23Z\",\n \"mode\": \"vibe\",\n \"completed_phases\": [\"user_setup\", \"filesystem\", \"shell_setup\"],\n \"current_phase\": \"cli_tools\",\n \"current_step\": \"Installing ripgrep\",\n \"failed_phase\": null,\n \"failed_step\": null,\n \"failed_error\": null,\n \"skipped_phases\": [],\n \"phase_timings\": {\n \"user_setup\": 12,\n \"filesystem\": 8,\n \"shell_setup\": 145\n }\n}\n```\n\n### Phase State Transitions\n\nEach phase goes through a defined state machine:\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ PHASE STATE MACHINE │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ PENDING │────▶│ RUNNING │────▶│ COMPLETE │ │\n│ └──────────┘ └────┬─────┘ └──────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌──────────┐ ┌──────────┐ │\n│ │ │ FAILED │────▶│ RETRY │──┐ │\n│ │ └──────────┘ └──────────┘ │ │\n│ │ ▲ │ │\n│ │ └────────┘ │\n│ │ │\n│ └──────────────────────▶┌──────────┐ │\n│ (--skip flag) │ SKIPPED │ │\n│ └──────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Resume Logic\n\nWhen the installer runs, it follows this decision tree:\n\n```python\ndef should_run_phase(phase_id):\n state = load_state_file()\n\n if phase_id in state.completed_phases:\n return SKIP # Already done\n\n if phase_id in state.skipped_phases:\n return SKIP # User explicitly skipped\n\n if state.failed_phase == phase_id:\n if user_wants_retry():\n return RUN # Retry failed phase\n else:\n return ABORT # Don't continue past failure\n\n return RUN # Normal execution\n```\n\n### Atomic State Updates\n\nState file updates are **atomic** to prevent corruption from interrupted writes:\n\n```bash\n# Write to temp file first\necho \"$new_state\" > \"$state_file.tmp.$$\"\n\n# Atomic rename (POSIX guarantees this is atomic on same filesystem)\nmv \"$state_file.tmp.$$\" \"$state_file\"\n```\n\nThis ensures the state file is never partially written, even if the process is killed mid-update.\n\n### Recovery from Common Failures\n\n| Failure Type | Detection | Recovery |\n|--------------|-----------|----------|\n| Network timeout | curl exit code 28 | Retry with exponential backoff |\n| APT lock held | `\u002Fvar\u002Flib\u002Fdpkg\u002Flock` exists | Wait and retry up to 60s |\n| Disk full | df check before write | Abort with clear error |\n| Out of memory | OOM killer | Resume picks up from last phase |\n| SSH disconnect | N\u002FA (session dies) | Resume on reconnect |\n| Ctrl+C | Trap handler | Clean exit, state preserved |\n\n### Phase Timings & Performance\n\nThe state file tracks how long each phase takes. This enables:\n- Accurate progress estimation (\"Phase 4\u002F9, ~3 minutes remaining\")\n- Performance regression detection across ACFS versions\n- Identifying slow phases that need optimization\n\n---\n\n## Error Handling & Recovery Patterns\n\nACFS is designed to **fail gracefully and recover automatically**. This section documents the error handling patterns used throughout the codebase.\n\n### The Try-Step Pattern\n\nEvery installation step is wrapped in a `try_step` function that captures errors without aborting:\n\n```bash\ntry_step \"Installing ripgrep\" install_ripgrep\n```\n\nThis pattern provides:\n- **Context tracking**: Errors include step name, not just exit code\n- **Graceful continuation**: Non-critical failures don't abort the whole install\n- **Structured reporting**: Failures are collected and reported at the end\n\n### Network Resilience\n\nNetwork operations implement **exponential backoff with jitter**:\n\n```bash\nretry_with_backoff() {\n local max_attempts=5\n local delay=1\n\n for attempt in $(seq 1 $max_attempts); do\n if \"$@\"; then\n return 0\n fi\n\n # Exponential backoff: 1s, 2s, 4s, 8s, 16s\n # With jitter: ±25% randomization\n local jitter=$(( (RANDOM % 50 - 25) * delay \u002F 100 ))\n sleep $((delay + jitter))\n delay=$((delay * 2))\n done\n\n return 1\n}\n```\n\n### APT Lock Handling\n\nThe most common installation failure is APT lock contention (another process using apt):\n\n```bash\nwait_for_apt_lock() {\n local max_wait=60\n local waited=0\n\n while fuser \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend >\u002Fdev\u002Fnull 2>&1; do\n if [[ $waited -ge $max_wait ]]; then\n log_error \"APT lock held for >60s, aborting\"\n return 1\n fi\n log_detail \"Waiting for apt lock... (${waited}s)\"\n sleep 5\n waited=$((waited + 5))\n done\n\n return 0\n}\n```\n\n### Graceful Degradation\n\nWhen a non-critical tool fails to install, ACFS continues with a warning:\n\n```\nCategory: Critical → Failure aborts installation\n Standard → Failure logged, installation continues\n Optional → Failure noted, no warning\n\nExamples:\n Critical: bun, zsh, git (can't proceed without these)\n Standard: ast-grep, lazygit (nice to have, not blocking)\n Optional: atuin, zoxide (pure enhancements)\n```\n\n### The Error Report\n\nAt the end of installation (or on abort), ACFS generates a structured error report:\n\n```\n═══════════════════════════════════════════════════════════════════════════════\n INSTALLATION REPORT\n═══════════════════════════════════════════════════════════════════════════════\n\n Status: PARTIAL SUCCESS (8\u002F9 phases completed)\n\n ✓ Completed Phases:\n • User Setup (12s)\n • Filesystem (8s)\n • Shell Setup (2m 25s)\n • CLI Tools (4m 12s)\n • Languages (3m 45s)\n • Agents (1m 30s)\n • Cloud (2m 10s)\n • Stack (5m 20s)\n\n ✗ Failed Phase: Finalize\n Step: Configuring tmux\n Error: tmux.conf syntax error on line 42\n\n Suggested Fix:\n Check ~\u002F.acfs\u002Ftmux\u002Ftmux.conf for syntax errors\n Then run: curl ... | bash -s -- --yes --mode vibe --resume\n\n═══════════════════════════════════════════════════════════════════════════════\n```\n\n---\n\n## Troubleshooting Guide\n\nThis section covers common issues and their solutions. For quick debugging, start with `acfs doctor`.\n\n### Installation Fails Immediately\n\n**Symptom**: Installer exits within seconds of starting.\n\n**Common Causes & Solutions**:\n\n| Cause | Detection | Fix |\n|-------|-----------|-----|\n| Not running as root | \"Permission denied\" | `sudo bash` or use `sudo` in curl command |\n| Not Ubuntu | \"Unsupported OS\" | ACFS only supports Ubuntu 22.04+ |\n| No internet | \"curl: (6) Could not resolve host\" | Check DNS, try `ping google.com` |\n| Old bash | Syntax errors | Upgrade to bash 4+ |\n\n### Installation Failure Recovery\n\nWhen the installer fails mid-way through, it provides an **auto-resume hint** with a precise command to continue from where it left off.\n\n**What you'll see on failure:**\n\n```\n[ERROR] ACFS installation failed!\n\nTo debug:\n 1. Check the log: cat \u002Fvar\u002Flog\u002Facfs\u002Finstall.log\n 2. If installed, run: acfs doctor (try as ubuntu)\n\n╔══════════════════════════════════════════════════════════════╗\n║ To resume installation from this point: ║\n╚══════════════════════════════════════════════════════════════╝\n\n curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002F...\u002Finstall.sh | bash -s -- --resume --yes\n\n Failed phase: phase_9\n Failed step: install_stack\n```\n\n**Key features of the resume hint:**\n\n| Feature | Description |\n|---------|-------------|\n| **Pinned commit** | Uses exact SHA from original run for reproducibility |\n| **Preserved flags** | Includes all original flags (--skip-*, --mode, --strict) |\n| **Automatic detection** | Reads failed phase\u002Fstep from `~\u002F.acfs\u002Fstate.json` |\n| **Copyable command** | Ready to paste and run immediately |\n\n**Manual recovery steps:**\n\n1. **Review the error**:\n ```bash\n # Check the full log\n cat \u002Fvar\u002Flog\u002Facfs\u002Finstall.log | tail -50\n\n # Or search for ERROR\n grep -i error \u002Fvar\u002Flog\u002Facfs\u002Finstall.log\n ```\n\n2. **Run diagnostics**:\n ```bash\n # As the target user (ubuntu)\n acfs doctor\n\n # If running as root\n sudo -u ubuntu -i bash -lc 'acfs doctor'\n ```\n\n3. **Resume installation**:\n ```bash\n # Use the exact command from the failure output\n # Or use the generic resume command:\n curl -sSL https:\u002F\u002Facfs.sh | bash -s -- --resume --yes --mode vibe\n ```\n\n4. **Check state file** (advanced):\n ```bash\n # View current installation state\n cat ~\u002F.acfs\u002Fstate.json | jq .\n\n # See the stored resume hint\n jq '.resume_hint' ~\u002F.acfs\u002Fstate.json\n ```\n\n**Common failure scenarios:**\n\n| Scenario | Typical Cause | Recovery |\n|----------|---------------|----------|\n| Network timeout | Transient connectivity | Wait, then resume |\n| APT lock held | Unattended-upgrades | Wait 2-3 min, resume |\n| Disk full | Insufficient space | Free space, resume |\n| SSH disconnect | Session timeout | Reconnect, resume |\n| Tool install failed | Upstream unavailable | Check status, resume |\n\n### APT Lock Errors\n\n**Symptom**: `E: Could not get lock \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend`\n\n**Solutions**:\n\n1. **Wait for unattended-upgrades** (most common on fresh VPS):\n ```bash\n # Check what's holding the lock\n sudo lsof \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend\n\n # Wait for it to finish (usually 2-3 minutes on fresh VPS)\n # Then re-run installer\n ```\n\n2. **Kill stuck process** (if waiting doesn't help):\n ```bash\n sudo killall apt apt-get dpkg\n sudo dpkg --configure -a\n sudo apt-get update\n ```\n\n### Install Logs & Summary JSON\n\nEvery ACFS install run produces two artifacts for debugging and tooling:\n\n**Log File Location:**\n```\n~\u002F.acfs\u002Flogs\u002Finstall-YYYYMMDD_HHMMSS.log\n```\n\nThe log file captures all stderr output from the installer, with:\n- Header containing version, date, and mode\n- All progress messages and errors\n- ANSI colors stripped after completion\n- Footer with completion timestamp\n\n**Summary JSON Location:**\n```\n~\u002F.acfs\u002Flogs\u002Finstall_summary_YYYYMMDD_HHMMSS.json\n```\n\n**Summary JSON Schema (v1):**\n```json\n{\n \"schema_version\": 1,\n \"status\": \"success\", \u002F\u002F \"success\" or \"failure\"\n \"timestamp\": \"2026-01-27T...\", \u002F\u002F ISO 8601\n \"total_seconds\": 1200, \u002F\u002F Wall clock time\n \"environment\": {\n \"acfs_version\": \"0.9.0\",\n \"mode\": \"vibe\",\n \"ubuntu_version\": \"25.04\",\n \"target_user\": \"ubuntu\",\n \"target_home\": \"\u002Fhome\u002Fubuntu\"\n },\n \"phases\": [\n {\"id\": \"phase_0\", \"duration_seconds\": 5},\n {\"id\": \"phase_1\", \"duration_seconds\": 45},\n \u002F\u002F ... completed phases in order\n ],\n \"failure\": null, \u002F\u002F null on success, or:\n \u002F\u002F \"failure\": {\n \u002F\u002F \"phase\": \"phase_9\",\n \u002F\u002F \"step\": \"install_stack\",\n \u002F\u002F \"error\": \"curl failed with exit code 7\",\n \u002F\u002F \"resume_hint\": \"curl -sSL ... | bash -s -- --resume --yes\"\n \u002F\u002F }\n \"log_file\": \"\u002Fhome\u002Fubuntu\u002F.acfs\u002Flogs\u002Finstall-20260127_120000.log\"\n}\n```\n\n**Accessing logs:**\n```bash\n# Find the latest log\nls -lt ~\u002F.acfs\u002Flogs\u002Finstall-*.log | head -1\n\n# Find the latest summary\nls -lt ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | head -1\n\n# Parse summary JSON\njq . ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | head -1\n\n# Get failed phase (if any)\njq '.failure \u002F\u002F \"No failure\"' ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1\n\n# Get phase timings\njq '.phases[] | \"\\(.id): \\(.duration_seconds)s\"' ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1\n```\n\n**Sharing logs for support:**\n\n```bash\n# Create a support bundle (strips sensitive data)\nacfs support-bundle > support-bundle.txt\n\n# Or manually share (review for secrets first):\ncat ~\u002F.acfs\u002Flogs\u002Finstall-*.log | tail -200 # Last 200 lines\ncat ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1 # Latest summary\n```\n\n### Support Bundle Command\n\nThe `acfs support-bundle` command collects all diagnostic data into a single archive for troubleshooting.\n\n**Usage:**\n```bash\nacfs support-bundle [options]\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--verbose, -v` | Show detailed output during collection |\n| `--output, -o DIR` | Output directory (default: `~\u002F.acfs\u002Fsupport`) |\n| `--no-redact` | Disable secret redaction (WARNING: bundle may contain secrets) |\n| `--help, -h` | Show help |\n\n**Output files:**\n```\n~\u002F.acfs\u002Fsupport\u002F\u003Ctimestamp>\u002F # Unpacked bundle directory\n~\u002F.acfs\u002Fsupport\u002F\u003Ctimestamp>.tar.gz # Compressed archive (shareable)\n~\u002F.acfs\u002Fsupport\u002F\u003Ctimestamp>\u002Fmanifest.json # Bundle manifest\n```\n\n**What's collected:**\n\n| File | Description |\n|------|-------------|\n| `state.json` | Installation state and checkpoints |\n| `VERSION` | ACFS version |\n| `checksums.yaml` | Upstream verification checksums |\n| `logs\u002Finstall-*.log` | Recent install logs (up to 10) |\n| `logs\u002Finstall_summary_*.json` | Recent install summaries |\n| `doctor.json` | Health check results |\n| `versions.json` | Installed tool versions |\n| `environment.json` | OS, memory, disk, user info |\n| `os-release` | Linux distribution info |\n| `journal-acfs.log` | Systemd journal for ACFS services |\n| `config\u002F.zshrc` | Shell configuration |\n\n**Security & Redaction:**\n\nBy default, sensitive data is automatically redacted:\n\n| Pattern | Example | Redacted To |\n|---------|---------|-------------|\n| OpenAI API keys | `sk-abc123...` | `\u003CREDACTED:api_key>` |\n| AWS keys | `AKIAIOSFODNN...` | `\u003CREDACTED:aws_key>` |\n| GitHub tokens | `ghp_xxxx...` | `\u003CREDACTED:github_token>` |\n| Vault tokens | `hvs.xxxx...` | `\u003CREDACTED:vault_token>` |\n| Slack tokens | `xoxb-xxxx...` | `\u003CREDACTED:slack_token>` |\n| Bearer tokens | `Bearer xxx...` | `Bearer \u003CREDACTED:bearer>` |\n| JWTs | `eyJhbGc...` | `\u003CREDACTED:jwt>` |\n| Passwords | `\"password\": \"...\"` | `\"password\": \"\u003CREDACTED:password>\"` |\n\n**Example workflow:**\n\n```bash\n# Create support bundle\nacfs support-bundle\n\n# Output: ~\u002F.acfs\u002Fsupport\u002F20260127_120000.tar.gz\n\n# Share the archive when filing an issue\n# The archive is safe to share (secrets redacted)\n```\n\n**Disable redaction (use with caution):**\n```bash\n# WARNING: Bundle may contain API keys, tokens, and passwords\nacfs support-bundle --no-redact\n```\n\n**When to use:**\n- Installation failed and you need to share logs\n- Filing a GitHub issue about ACFS\n- Diagnosing tool installation problems\n- Sharing system state with support\n\n### Shell Not Changing to zsh\n\n**Symptom**: Still seeing bash prompt after install.\n\n**Solutions**:\n\n1. **Log out and back in** (the change happens at next login)\n\n2. **Manually set shell**:\n ```bash\n chsh -s $(which zsh)\n # Then log out and back in\n ```\n\n3. **Check shell was installed**:\n ```bash\n which zsh # Should show \u002Fusr\u002Fbin\u002Fzsh\n cat \u002Fetc\u002Fshells # zsh should be listed\n ```\n\n### Agent Authentication Issues\n\n**Claude Code**:\n```bash\n# Check auth status\nclaude --version\nls -la ~\u002F.claude\u002F # or ~\u002F.config\u002Fclaude\u002F\n\n# Re-authenticate\nclaude # Follow prompts\n```\n\n**Codex CLI**:\n```bash\n# Check auth status\ncodex --version\n\n# Re-authenticate (uses ChatGPT account, not API key)\ncodex login\n```\n\n**Gemini CLI**:\n```bash\n# Check auth status\ngemini --version\n\n# Re-authenticate\ngemini # Follow Google login flow\n```\n\n### \"Command Not Found\" After Install\n\n**Symptom**: `claude: command not found` even though install succeeded.\n\n**Solutions**:\n\n1. **Reload shell config**:\n ```bash\n source ~\u002F.zshrc\n # Or start a new shell\n exec zsh\n ```\n\n2. **Check PATH**:\n ```bash\n echo $PATH | tr ':' '\\n' | grep -E \"(bun|local|cargo)\"\n # Should include: ~\u002F.bun\u002Fbin, ~\u002F.local\u002Fbin, ~\u002F.cargo\u002Fbin\n ```\n\n3. **Manual path fix**:\n ```bash\n export PATH=\"$HOME\u002F.bun\u002Fbin:$HOME\u002F.local\u002Fbin:$HOME\u002F.cargo\u002Fbin:$PATH\"\n ```\n\n### Doctor Shows Missing Tools\n\n**Symptom**: `acfs doctor` shows failed checks for tools you expected to be installed.\n\n**Understanding doctor output:**\n\nDoctor checks are generated directly from the manifest, so they verify the exact same tools the installer provides. When a check fails, doctor shows a copy-pasteable fix command:\n\n```\n ✗ tools.lazygit - Lazygit terminal UI not found\n Fix: acfs install --only tools.lazygit\n```\n\n**Solutions**:\n\n1. **Re-run the specific module** (use the fix suggestion):\n ```bash\n acfs install --only tools.lazygit # Install just that tool\n acfs install --only lang.go # Install a language runtime\n acfs install --only stack.dcg # Install a stack tool\n ```\n\n2. **Re-run an entire phase** (for multiple failures in one category):\n ```bash\n acfs install --only-phase 4 # Re-run Phase 4: Tools\n acfs install --only-phase 8 # Re-run Phase 8: Stack\n ```\n\n3. **Run auto-fix mode** (applies safe, deterministic fixes):\n ```bash\n acfs doctor --fix\n acfs doctor --fix --dry-run # Preview fixes first\n ```\n\n**Note**: Doctor checks match the manifest verify commands exactly. If a tool was skipped during installation (e.g., using `--mode safe`), the check will fail. This is expected—run `acfs doctor` to see which tools are missing and decide which to install.\n\n### Tmux Configuration Errors\n\n**Symptom**: Tmux won't start or shows config errors.\n\n**Solutions**:\n\n1. **Check syntax**:\n ```bash\n tmux source-file ~\u002F.tmux.conf\n # Will show line number of any errors\n ```\n\n2. **Reset to ACFS defaults**:\n ```bash\n cp ~\u002F.acfs\u002Ftmux\u002Ftmux.conf ~\u002F.tmux.conf\n ```\n\n3. **Version mismatch** (old tmux, new config):\n ```bash\n tmux -V # Check version\n # ACFS config requires tmux 3.0+\n ```\n\n### Stack Tools Not Working\n\n**Symptom**: `ntm`, `slb`, `dcg`, etc. not found or erroring.\n\n**Solutions**:\n\n1. **Reinstall stack**:\n ```bash\n acfs update --stack --force\n ```\n\n2. **Check cargo install worked**:\n ```bash\n ls ~\u002F.cargo\u002Fbin\u002F # Should contain ntm, slb, ru, etc.\n ls ~\u002F.local\u002Fbin\u002F # dcg often installs here\n ```\n\n3. **Rust not in path**:\n ```bash\n source ~\u002F.cargo\u002Fenv\n ```\n\n### DCG Hook Issues\n\n**Symptom**: DCG isn't blocking commands or Claude reports hook errors.\n\n**Solutions**:\n\n1. **Run the built-in health check**:\n ```bash\n dcg doctor\n ```\n\n2. **Re-register the hook**:\n ```bash\n dcg install --force\n ```\n\n3. **Verify hook registration**:\n ```bash\n grep -n dcg ~\u002F.claude\u002Fsettings.json ~\u002F.config\u002Fclaude\u002Fsettings.json\n ```\n\n4. **Reinstall if binary is missing**:\n ```bash\n which dcg # Should return a path\n # If missing, reinstall:\n curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fdestructive_command_guard\u002Fmain\u002Finstall.sh\" | bash\n dcg install # Register hook after reinstall\n ```\n\n### Complete Reset\n\nWhen all else fails, the nuclear option:\n\n```bash\n# Save any important files first!\n\n# Backup ACFS state (recommended)\nts=\"$(date +%Y%m%d_%H%M%S)\"\n[ -d ~\u002F.acfs ] && mv ~\u002F.acfs ~\u002F.acfs.backup.\"$ts\"\n\n# Backup installed configs (optional)\nfor f in ~\u002F.zshrc ~\u002F.tmux.conf ~\u002F.p10k.zsh; do\n [ -f \"$f\" ] && mv \"$f\" \"$f\".backup.\"$ts\"\ndone\n\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe --force-reinstall\n```\n\n---\n\n## Security Threat Model\n\nACFS takes security seriously while acknowledging the inherent risks of `curl | bash` installation. This section documents our threat model and mitigations.\n\n### What We Protect Against\n\n| Threat | Mitigation |\n|--------|------------|\n| **Man-in-the-middle (MITM)** | HTTPS enforcement for all downloads |\n| **Compromised upstream scripts** | SHA256 checksum verification |\n| **Malicious package injection** | Official package sources only (apt, cargo, bun) |\n| **Credential exposure** | No credentials stored in scripts or configs |\n| **Privilege escalation** | Minimal sudo usage, explicit permission grants |\n| **Persistent backdoors** | Ephemeral VPS model; start fresh if concerned |\n\n### What We Don't Protect Against\n\n| Threat | Why Not | Mitigation |\n|--------|---------|------------|\n| **Compromised GitHub** | Would require GitHub-level breach | Use release tags, verify commits |\n| **Compromised upstream maintainers** | Can't verify humans | Trust + checksum verification |\n| **Zero-day in installed tools** | Beyond our control | Keep tools updated, follow CVEs |\n| **Physical VPS access** | Provider responsibility | Choose reputable providers |\n| **Vibe mode abuse** | By design for throwaway VPS | Use safe mode on important systems |\n\n### The `curl | bash` Debate\n\nThe `curl | bash` pattern is controversial. Critics argue:\n- You're executing arbitrary code from the internet\n- The download could be swapped mid-stream\n- You can't audit before executing\n\nOur response:\n1. **HTTPS** prevents mid-stream swapping\n2. **Checksums** verify content matches known-good versions\n3. **Ephemeral environments** limit blast radius\n4. **Open source** allows pre-audit of install.sh\n\nFor maximum security, you can:\n```bash\ncurl -fsSL \"https:\u002F\u002F...\" -o install.sh\nless install.sh\nbash install.sh --yes --mode vibe\n```\n\n### Checksum Verification Deep Dive\n\nEvery upstream installer we fetch is verified against known-good checksums:\n\n```yaml\n# checksums.yaml excerpt\ninstallers:\n bun:\n url: \"https:\u002F\u002Fbun.sh\u002Finstall\"\n sha256: \"a1b2c3d4e5f6...\"\n last_verified: \"2024-12-15\"\n notes: \"Official Bun installer\"\n```\n\nThe verification process:\n\n```\n1. Download script to memory (not disk)\n2. Calculate SHA256 of downloaded bytes\n3. Compare against stored checksum\n4. If match: execute\n5. If mismatch: abort with warning\n```\n\nA mismatch could mean:\n- Upstream released a new version (common, usually safe)\n- Upstream was compromised (rare, investigate before updating)\n\nOur update process:\n1. Monitor upstream releases\n2. Review changes in new installer versions\n3. Update checksums only after manual review\n4. Commit with descriptive message explaining what changed\n\n### Vibe Mode Security Implications\n\nVibe mode (`--mode vibe`) enables:\n- Passwordless sudo for ubuntu user\n- `--dangerously-skip-permissions` for Claude\n- `--dangerously-bypass-approvals-and-sandbox` for Codex\n- `--yolo` for Gemini\n\nThis is **intentionally insecure for velocity**. Use only on:\n- Throwaway VPS you don't care about\n- Non-production environments\n- Personal experimentation\n\nNever on:\n- Production servers\n- Shared team infrastructure\n- Systems with sensitive data\n- Long-running servers\n\n---\n\n## Comparison to Alternatives\n\nHow does ACFS compare to other ways of setting up a development environment?\n\n### vs. Manual Setup\n\n| Aspect | Manual | ACFS |\n|--------|--------|------|\n| Time | 3-7 hours | 30 minutes |\n| Consistency | Varies | Identical every time |\n| Documentation | Your memory | This README |\n| Resume on failure | Start over | Automatic |\n| Updates | Manual each tool | `acfs update` |\n\n**When to use manual**: When you need to understand every detail, or have highly specific requirements.\n\n### vs. Dotfiles Repos\n\n| Aspect | Dotfiles | ACFS |\n|--------|----------|------|\n| Scope | Configs only | Full tool installation |\n| Portability | Mac\u002FLinux | Ubuntu-focused |\n| Maintenance | DIY | Maintained project |\n| Agent focus | None | Core feature |\n\n**When to use dotfiles**: When you already have tools installed and just want configs.\n\n### vs. Nix\u002FNixOS\n\n| Aspect | Nix | ACFS |\n|--------|-----|------|\n| Reproducibility | Perfect | Good |\n| Learning curve | Steep | Gentle |\n| Rollback | Native | Manual |\n| Complexity | High | Low |\n| Adoption | Growing | Easy |\n\n**When to use Nix**: When you need perfect reproducibility and are willing to invest in learning Nix.\n\n### vs. DevContainers\n\n| Aspect | DevContainers | ACFS |\n|--------|--------------|------|\n| Isolation | Container | Full VPS |\n| Resource overhead | Container runtime | None |\n| IDE integration | VSCode-centric | Terminal-native |\n| Agent experience | Limited | Native |\n\n**When to use DevContainers**: When you want isolated project environments within an existing machine.\n\n### vs. Ansible\u002FTerraform\n\n| Aspect | Ansible\u002FTF | ACFS |\n|--------|------------|------|\n| Scope | Infrastructure | Development env |\n| Complexity | High | Low |\n| Audience | DevOps | Developers |\n| Learning curve | Steep | Gentle |\n\n**When to use Ansible\u002FTerraform**: When you're managing fleets of servers, not individual dev environments.\n\n### The ACFS Sweet Spot\n\nACFS is optimal when you need:\n- **Fast setup** of a complete agentic coding environment\n- **Fresh Ubuntu VPS** as your target\n- **AI coding agents** as primary tools\n- **Throwaway\u002Fephemeral** infrastructure mindset\n- **Minimal configuration** to get started\n\n---\n\n## The Dicklesworthstone Stack Philosophy\n\nThe 10-tool stack included in ACFS isn't random—each tool addresses a specific problem discovered through extensive multi-agent development experience.\n\n### The Problems\n\nRunning multiple AI coding agents simultaneously surfaces problems that don't exist with single-agent or no-agent development:\n\n1. **Session chaos**: Agents in random terminal windows, no organization\n2. **File conflicts**: Two agents editing the same file simultaneously\n3. **No communication**: Agents can't coordinate or share findings\n4. **Dangerous commands**: Agents running `git reset --hard` or `rm -rf` without oversight\n5. **Lost context**: No memory of what agents learned previously\n6. **Auth switching**: Different projects need different credentials\n7. **History fragmentation**: Agent conversations scattered across systems\n8. **No task visibility**: Hard to see what agents are working on\n9. **Repo sprawl**: Dozens of repos, hard to keep synced, uncommitted work everywhere\n10. **Visual debugging gaps**: Screenshots on phone, can't view in SSH terminal\n\n### The Solutions\n\nEach tool in the stack addresses specific problems:\n\n| # | Tool | Problem Solved | Philosophy |\n|---|------|----------------|------------|\n| 1 | **NTM** | Session chaos | Named sessions create order from chaos |\n| 2 | **Agent Mail** | No communication + file conflicts | Message-passing + file reservations |\n| 3 | **UBS** | Dangerous commands | Guardrails with intelligence |\n| 4 | **Beads Viewer** | No task visibility | Graph-based task dependencies |\n| 5 | **CASS** | History fragmentation | Unified search across all agents |\n| 6 | **CM** | Lost context | Procedural memory for agents |\n| 7 | **CAAM** | Auth switching | One command to switch identities |\n| 8 | **SLB** | Dangerous commands | Two-person rule for nuclear options |\n| 9 | **DCG** | Dangerous git\u002Ffs commands | Sub-millisecond Claude Code hook blocks destructive operations |\n| 10 | **RU** | Repo sprawl | Sync repos + AI-driven commit automation across dirty repos |\n\n**Bundled Utilities:**\n\n| Tool | Problem Solved | Philosophy |\n|------|----------------|------------|\n| **giil** | Visual debugging gaps | Download cloud images (iCloud, Dropbox, Google Photos) to terminal |\n| **csctf** | Knowledge capture | Convert AI chat shares to searchable Markdown\u002FHTML archives |\n\n### The Synergy Effect\n\nThese tools are designed to work together:\n\n```\nNTM spawns agents → Agents register with Agent Mail →\nAgent Mail reserves files → DCG blocks dangerous commands →\nUBS validates operations → Beads tracks tasks →\nCASS searches history → CM provides memory →\nCAAM manages auth → SLB gates nuclear operations →\nRU syncs repos and automates commits\n```\n\nNo single tool is transformative alone. Together, they enable workflows that would otherwise be impossible:\n\n- **10 agents working in parallel** without stepping on each other\n- **Continuous operation** across SSH disconnects\n- **Audit trails** for every agent action\n- **Coordination** without manual intervention\n- **Safety** without sacrificing velocity\n\n### Design Principles of the Stack\n\n1. **Unix Philosophy**: Each tool does one thing well\n2. **Composition**: Tools designed to pipe into each other\n3. **Terminal-First**: TUI over GUI, speed over polish\n4. **Agent-Native**: Built for AI, not adapted for AI\n5. **Git-Friendly**: All state is auditable in version control\n\n---\n\n## Advanced Configuration\n\nACFS supports various configuration mechanisms for advanced users.\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ACFS_HOME` | `~\u002F.acfs` | Configuration directory |\n| `ACFS_REF` | `main` | Git ref to install from (tag, branch, or commit SHA) |\n| `ACFS_CHECKSUMS_REF` | `main` (when pinned) \u002F `ACFS_REF` (when branch) | Ref used to fetch `checksums.yaml` |\n| `ACFS_LOG_DIR` | `\u002Fvar\u002Flog\u002Facfs` | Log directory |\n| `TARGET_USER` | `ubuntu` | User to configure |\n| `TARGET_HOME` | `\u002Fhome\u002F$TARGET_USER` | User home directory |\n\n**Examples:**\n```bash\n# Install from a tagged release (recommended for production)\nACFS_REF=v0.1.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.1.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n\n# Install from a specific branch (development\u002Ftesting)\nACFS_REF=feature\u002Fnew-tool curl -fsSL \"...\" | bash -s -- --yes --mode vibe\n\n# Install from a specific commit (reproducibility)\nACFS_REF=abc1234 curl -fsSL \"...\" | bash -s -- --yes --mode vibe\n\n# Pin installer version but use latest checksums (avoid stale hash mismatches)\nACFS_REF=v0.5.0 ACFS_CHECKSUMS_REF=main curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.5.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n```\n\n> **Tip:** Always match the URL path with `ACFS_REF` so the initial script and all subsequently fetched scripts come from the same ref.\n> **Tip:** For pinned installs (tags\u002FSHAs), checksums default to `main` to avoid stale installer hashes. Override with `ACFS_CHECKSUMS_REF` if you want checksums pinned to the same ref.\n\n### Complete Installer CLI Options\n\nThe installer supports extensive command-line customization:\n\n**Execution Control:**\n```bash\n--yes, -y # Skip all prompts (non-interactive)\n--dry-run # Simulate without making changes\n--print # Print what would be installed\n--mode vibe|safe # Installation mode (default: vibe)\n--interactive # Force interactive mode with prompts\n--strict # Abort on any error (vs. continue with warnings)\n--checksums-ref \u003Cref> # Fetch checksums.yaml from this ref (default: main for pinned tags\u002FSHAs)\n```\n\n**Resume & State:**\n```bash\n--resume # Resume from last checkpoint\n--force-reinstall # Ignore state, reinstall everything\n--reset-state # Clear state.json and start fresh\n```\n\n**Ubuntu Upgrade:**\n```bash\n--skip-ubuntu-upgrade # Don't upgrade Ubuntu version\n--target-ubuntu=25.10 # Specify target Ubuntu version\n--target-ubuntu 25.04 # Alternative syntax\n```\n\n**Skip Flags:**\n```bash\n--skip-postgres # Skip PostgreSQL 18\n--skip-vault # Skip HashiCorp Vault\n--skip-cloud # Skip Wrangler, Supabase, Vercel CLIs\n--skip-preflight # Skip pre-flight validation\n```\n\n### Module Selection\n\nFine-grained control over what gets installed using manifest-driven selection:\n\n```bash\n--list-modules # List available modules\n--print-plan # Show execution plan without running\n--only \u003Cmodule> # Only run specific module(s)\n--only-phase \u003Cphase> # Only run modules in a phase\n--skip \u003Cmodule> # Skip specific module(s)\n--no-deps # Don't auto-include dependencies (⚠️ advanced)\n```\n\n**Key behaviors:**\n- **Dependency closure:** `--only` automatically includes required dependencies (safe by default)\n- **Skip safety:** `--skip` fails early if it would break a required dependency chain\n- **Deterministic:** `--print-plan` shows exactly what will run, in what order\n\n**Examples:**\nOnly install agents (plus their dependencies):\n\n```bash\ncurl -fsSL \"...\" | bash -s -- --yes --only-phase agents\n```\n\nSkip PostgreSQL and Vault:\n\n```bash\ncurl -fsSL \"...\" | bash -s -- --yes --skip db.postgres18 --skip tools.vault\n```\n\nPreview what would run without executing:\n\n```bash\ncurl -fsSL \"...\" | bash -s -- --print-plan\n```\n\n> **Note:** Using `--no-deps` bypasses safety checks and may result in broken installs. Only use if you've already installed dependencies separately.\n\n### Custom Post-Install Hooks\n\nAdd custom steps by placing scripts in `~\u002F.acfs\u002Fhooks\u002F`:\n\n```bash\nmkdir -p ~\u002F.acfs\u002Fhooks\ncat > ~\u002F.acfs\u002Fhooks\u002Fpost-install.sh \u003C\u003C 'EOF'\n#!\u002Fbin\u002Fbash\n# Custom post-install steps\necho \"Running custom configuration...\"\n# Your commands here\nEOF\nchmod +x ~\u002F.acfs\u002Fhooks\u002Fpost-install.sh\n```\n\nACFS will execute `post-install.sh` after the main installation completes.\n\n### Override Tool Versions\n\nTo pin specific tool versions, set environment variables:\n\n```bash\nexport BUN_VERSION=\"1.1.0\"\nexport UV_VERSION=\"0.5.0\"\n# Then run installer\n```\n\nNote: Not all tools support version pinning. Check individual tool documentation.\n\n---\n\n## Future Roadmap\n\nACFS is actively developed. Here's what's coming:\n\n### Near-Term (Q1 2025)\n\n- [ ] **Full manifest-driven execution**: install.sh consumes generated scripts\n- [x] **Tailscale integration**: Zero-config VPN for secure remote access ✓\n- [x] **Services setup wizard**: Guide users through service account setup (`acfs services-setup`) ✓\n- [ ] **Interactive module selection**: Choose what to install via TUI\n\n### Mid-Term (Q2 2025)\n\n- [ ] **ARM64 optimization**: Native Apple Silicon and ARM VPS support\n- [ ] **Offline mode**: Pre-downloaded package bundles\n- [ ] **Team mode**: Shared configurations across team members\n- [ ] **Plugin system**: Third-party tool integrations\n\n### Long-Term (2025+)\n\n- [ ] **ACFS Cloud**: Managed VPS provisioning + ACFS install in one click\n- [ ] **IDE integrations**: VSCode\u002FCursor extensions for remote ACFS management\n- [ ] **Agent marketplace**: Pre-configured agent personalities and workflows\n- [ ] **Enterprise features**: SSO, audit logging, compliance\n\n---\n\n## Performance Benchmarks\n\nInstallation times vary by VPS provider and network conditions. Here are typical benchmarks:\n\n### Installation Time by Phase\n\n| Phase | Typical Duration | Notes |\n|-------|-----------------|-------|\n| User Setup | 10-15s | Fast, mostly checks |\n| Filesystem | 5-10s | Creating directories |\n| Shell Setup | 2-4 min | Oh-My-Zsh clone is slow |\n| CLI Tools | 3-5 min | Many apt packages |\n| Languages | 3-5 min | Rust compile takes longest |\n| Agents | 1-2 min | Fast bun installs |\n| Cloud | 1-2 min | Fast bun installs |\n| Stack | 4-6 min | Cargo installs |\n| Finalize | 30-60s | Config deployment |\n| **Total** | **15-25 min** | **Typical full install** |\n\n### Factors Affecting Speed\n\n| Factor | Impact | Optimization |\n|--------|--------|--------------|\n| Network latency | High | Choose VPS close to package mirrors |\n| Disk I\u002FO | Medium | SSD\u002FNVMe preferred |\n| CPU cores | Medium | More cores = faster compilation |\n| RAM | Low | 4GB is sufficient |\n| Provider | Variable | OVH and Contabo offer excellent value |\n\n### Resume Performance\n\nResuming from checkpoint is fast because completed phases are skipped:\n\n```\nFull install: 20 minutes\nResume from 50%: 10 minutes\nResume from 90%: 2 minutes\n```\n\n---\n\n## License\n\nMIT License (with OpenAI\u002FAnthropic Rider). See [LICENSE](LICENSE) for details.\n\n---\n\n## Links\n\n- **Website:** [agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) — Interactive wizard for beginners\n- **GitHub:** [Dicklesworthstone\u002Fagentic_coding_flywheel_setup](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup)\n- **Related Projects:**\n - [ntm](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fntm) - Named Tmux Manager\n - [beads_viewer](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer) - Task management TUI\n - [mcp_agent_mail](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fmcp_agent_mail) - Agent coordination\n - [cass](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search) - Agent session search\n - [dcg](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fdestructive_command_guard) - Destructive Command Guard\n - [ru](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frepo_updater) - Repo Updater\n\n---\n\n## About Contributions\n\nPlease don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n\n---\n\n\u003Cdiv align=\"center\">\n \u003Csub>Created by \u003Ca href=\"https:\u002F\u002Fx.com\u002Fdoodlestein\">Jeffrey Emanuel\u003C\u002Fa> (\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\">@Dicklesworthstone\u003C\u002Fa>) for the agentic coding community.\u003C\u002Fsub>\n\u003C\u002Fdiv>\n","# 代理式编码飞轮搭建方案（ACFS）\n\n\u003Cdiv align=\"center\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_agentic_coding_flywheel_setup_readme_38f71d2a5256.webp\" alt=\"代理式编码飞轮搭建方案（ACFS）——从零开始，30分钟内完成全配置的代理式编码 VPS\">\n\u003C\u002Fdiv>\n\n![版本](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F版本-0.6.0-bd93f9?style=for-the-badge)\n![平台](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F平台-Ubuntu%2025.10-6272a4?style=for-the-badge)\n![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F许可证-MIT%2BOpenAI%2FAnthropic%20Rider-blue-the-badge)\n![Shell](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FShell-Bash-ff79c6?style=for-the-badge)\n\n\u003Cp align=\"center\">\n \u003Cstrong>🌐 \u003Ca href=\"https:\u002F\u002Fagent-flywheel.com\">agent-flywheel.com\u003C\u002Fa>\u003C\u002Fstrong> — 面向初学者的交互式搭建向导\n\u003C\u002Fp>\n\n> **从零起步，30分钟内完成全配置的代理式编码 VPS。** \n> 一套完整的自建系统，可将全新的 Ubuntu VPS 转化为专业级的 AI 驱动开发环境。\n\n\u003Cdiv align=\"center\" style=\"margin: 1.2em 0;\">\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cstrong>愿景\u003C\u002Fstrong>\u003Cbr\u002F>\n \u003Csub>从笔记本电脑入门 → 向导 → VPS → 为您打造代理式编码工具\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n### 快速安装\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n该安装脚本具备**幂等性**——若中途中断，只需重新运行即可。它会自动从上一次已完成的步骤继续执行，无需再次提示。\n\n> **生产环境：** 为确保安装稳定且可重复，建议将安装脚本固定到某个已标记的发行版或特定提交：\n> ```bash\n> # 推荐方式：使用已标记的发行版（例如 v0.5.0）\n> ACFS_REF=v0.5.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.5.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n>\n> # 替代方案：固定到特定的提交 SHA\n> ACFS_REF=abc1234 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fabc1234\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n> ```\n> 已标记的发行版经过测试，稳定性可靠。通过设置 `ACFS_REF`，可确保所有下载的脚本均使用同一版本。\n\n---\n\n## 简要总结\n\n**ACFS** 是一套完整的代理式编码环境自建系统：\n\n**为什么值得关注：**\n- **从零到英雄：** 让完全的初学者从“我有一台笔记本电脑”一路成长为“我拥有 Claude\u002FCodex\u002FGemini 代理，在 VPS 上为我编写代码”\n- **单行命令魔法：** 仅需一条 `curl | bash` 命令，即可安装 30 多种工具，完成所有配置，并快速部署三个 AI 编码代理\n- **Vibe 模式：** 预配置以实现最大化的加速效率——免密码 sudo，启用危险代理标志，优化 Shell 环境\n- **经实战检验的完整栈：** 包含 Dicklesworthstone 的全套工具（10 种工具 + 实用程序），用于代理编排、协调与安全防护\n\n**您将获得：**\n- 现代 Shell（zsh + oh-my-zsh + powerlevel10k）\n- 所有语言运行时（bun、uv\u002FPython、Rust、Go）\n- 三个 AI 编码代理（Claude Code、Codex CLI、Gemini CLI）\n- 代理协调工具（NTM、MCP Agent Mail、SLB）\n- 云原生 CLI（Vault、Wrangler、Supabase、Vercel）\n- 还有 20 多种开发者工具\n\n---\n\n## ACFS 体验\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph 用户 [\"用户机器\"]\n LAPTOP[\"笔记本电脑\"]\n BROWSER[\"浏览器\"]\n end\n\n subgraph 向导 [\"向导网站\"]\n STEPS[\"13 步指南\"]\n end\n\n subgraph VPS [\"全新 VPS\"]\n UBUNTU[\"Ubuntu 25.10\"]\n INSTALLER[\"install.sh\"]\n CONFIGURED[\"已配置的 VPS\"]\n end\n\n subgraph 代理 [\"AI 代理\"]\n CLAUDE[\"Claude Code\"]\n CODEX[\"Codex CLI\"]\n GEMINI[\"Gemini CLI\"]\n end\n\n LAPTOP --> BROWSER\n BROWSER --> STEPS\n STEPS -->|SSH| UBUNTU\n UBUNTU --> INSTALLER\n INSTALLER --> CONFIGURED\n CONFIGURED --> CLAUDE\n CONFIGURED --> CODEX\n CONFIGURED --> GEMINI\n\n classDef 用户 fill:#e3f2fd,stroke:#90caf9,stroke-width:2px\n classDef 向导 fill:#fff8e1,stroke:#ffcc80,stroke-width:2px\n classDef VPS fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px\n classDef 代理 fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px\n\n class LAPTOP,BROWSER user\n class STEPS wizard\n class UBUNTU,INSTALLER,CONFIGURED vps\n class CLAUDE,CODEX,GEMINI agent\n```\n\n### 面向初学者\nACFS 在 [agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) 提供了一个**分步向导网站**，可引导完全的初学者完成以下步骤：\n1. 在本地机器上安装终端\n2. 生成 SSH 密钥（以便后续安全访问）\n3. 从 OVH 或 Contabo 等服务商租用 VPS\n4. 使用密码通过 SSH 连接（初始设置）\n5. 运行安装脚本（该脚本可完成基于密钥的访问配置）\n6. 使用 SSH 密钥安全地重新连接\n7. 开始使用 AI 代理进行编码\n\n### 面向开发者\nACFS 是一条**单行命令**，可将任何全新的 Ubuntu VPS 转化为功能完备的开发环境，配备现代化的工具和三个现成可用的 AI 编码代理。\n\n### 面向团队\nACFS 提供了一套**可重复、幂等**的搭建流程，确保每位团队成员的 VPS 环境完全一致——彻底消除“在我的机器上能正常运行”的顾虑，助力代理式工作流的高效开展。\n\n---\n\n## 架构与设计\n\nACFS 以**单一真理来源**为核心构建：即 manifest 文件。其他一切——安装脚本、检查工具、网站内容——均源自这一核心定义。这种架构确保了系统的统一性，并使系统易于扩展。\n\n### 一页式系统数据流\n\n```mermaid\nflowchart TB\n %% 用户与网站\n subgraph U[\"用户（本地机器）\"]\n Browser[\"浏览器\"]\n Terminal[\"终端 \u002F SSH 客户端\"]\n end\n\n subgraph W[\"向导网站（Next.js 16）——apps\u002Fweb\"]\n Wizard[\"向导 UI（\u002Fwizard\u002F*）\"]\n InstallRoute[\"GET \u002Finstall（302 重定向至原始安装脚本）\"]\n WebState[\"状态：URL 参数 + localStorage\"]\n end\n\n %% 仓库源码\n subgraph R[\"仓库（源码）\"]\n Manifest[\"acfs.manifest.yaml\u003Cbr\u002F>模块 + 安装 + 验证 + 依赖项\"]\n Generator[\"packages\u002Fmanifest\u003Cbr\u002F>解析器（Zod）+ generate.ts\"]\n Generated[\"scripts\u002Fgenerated\u002F*（参考）\u003Cbr\u002F>分类安装程序 + doctor_checks.sh\"]\n Installer[\"install.sh（生产级单行命令）\"]\n Lib[\"scripts\u002Flib\u002F*\u003Cbr\u002F>安全 \u002F 医生 \u002F 更新 \u002F 服务设置\"]\n Configs[\"acfs\u002F*\u003Cbr\u002F>zshrc + tmux.conf + 上机课程\"]\n Checksums[\"checksums.yaml\u003Cbr\u002F>上游安装程序的 SHA256 校验值\"]\n Tests[\"tests\u002Fvm\u002Ftest_install_ubuntu.sh\u003Cbr\u002F>Docker 集成测试\"]\n end\n\n %% 目标 VPS\n subgraph V[\"目标 VPS（Ubuntu 25.10，自动升级）\"]\n Run[\"运行 install.sh\"]\n Verify[\"已验证上游安装程序\u003Cbr\u002F>(security.sh + checksums.yaml)\"]\n AcfsHome[\"~\u002F.acfs\u002F\u003Cbr\u002F>配置文件 + 脚本 + state.json\"]\n Commands[\"命令\u003Cbr\u002F>acfs doctor \u002F acfs update \u002F acfs 服务设置 \u002F 上机课程\"]\n Tools[\"已安装的工具\u003Cbr\u002F>bun\u002Fuv\u002Frust\u002Fgo + tmux\u002Frg\u002Fgh + vault + ...\"]\n Agents[\"代理 CLI\u003Cbr\u002F>claude \u002F codex \u002F gemini\"]\n Stack[\"堆栈工具\u003Cbr\u002F>ntm \u002F mcp_agent_mail \u002F ubs \u002F bv \u002F cass \u002F cm \u002F caam \u002F slb \u002F dcg \u002F ru\"]\n end\n\n %% 网站引导流程\n Browser --> Wizard\n Wizard --> WebState\n Wizard --> InstallRoute\n InstallRoute -->|重定向至| Installer\n\n %% 用户如何获取并运行安装程序\n Terminal -->|curl \u002F bash| Installer\n Terminal -->|SSH| 运行\n\n %% 基于 manifest 的生成（今日参考）\n Manifest --> Generator --> Generated\n Generated -.->|计划：install.sh 调用 generated install_all.sh| Installer\n\n %% 安装程序的构成\n Lib --> Installer\n Configs --> Installer\n Checksums --> Installer\n Tests -->|验证| Installer\n\n %% VPS 安装结果\n Installer --> 运行\n Run --> Verify\n Verify --> 工具\n Verify --> 代理\n Verify --> 堆栈\n Run --> AcfsHome --> 命令\n```\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 真实来源 │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ acfs.manifest.yaml │ │\n│ │ 工具定义 • 安装命令 • 验证逻辑 │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n │\n ┌─────────────────┴─────────────────┐\n ▼ ▼\n┌───────────────────────────────────┐ ┌───────────────────────────────────┐\n│ 代码生成 │ │ 向导网站 │\n│ ┌─────────────────────────────┐ │ │ ┌─────────────────────────────┐ │\n│ │ TypeScript 解析器（Zod） │ │ │ │ apps\u002Fweb\u002F（Next.js 16） │ │\n│ │ generate.ts │ │ │ │ agent-flywheel.com │ │\n│ └─────────────────────────────┘ │ │ └─────────────────────────────┘ │\n└───────────────────────────────────┘ └───────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────────────────┐\n│ 生成输出（参考） │\n│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │\n│ │ scripts\u002Fgenerated\u002F │ │ doctor_checks.sh │ │ install_all.sh │ │\n│ │ 11 类别脚本│ │ 验证逻辑 │ │ 主要安装程序 │ │\n│ └────────────────────┘ └────────────────────┘ └────────────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────────────────┐\n│ 目标 VPS │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ 30 多种工具 │ │ zsh + p10k │ │ AI 代理 │ │ ~\u002F.acfs\u002F │ │\n│ │ 已安装的工具 │ │ Shell 配置 │ │ Claude\u002FCodex │ │ 配置文件 │ │\n│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n```\n\n### 为何采用这种架构？\n\n**单一真相来源**：`acfs.manifest.yaml` 文件定义了每一种工具——其名称、描述、安装命令以及验证逻辑。当您在清单中添加或编辑工具时，生成器会自动更新生成的脚本和基于清单生成的检查。如今，生产级单行命令安装程序（`install.sh`）仍由人工编写，因此，如果行为发生变更，可能也需要更新 `install.sh`，直到完成全面迁移。\n\n**TypeScript + Zod 验证**：清单解析器使用 Zod 模式来在解析时对 YAML 进行验证。拼写错误、缺失字段以及结构错误会在生成阶段立即被检测出来——而非在用户 VPS 的运行时，当安装程序在半途中失败时才被发现。\n\n**生成的脚本**：与其手动维护 11 个类别安装程序脚本并保持它们同步，生成器会从清单中自动生成这些脚本。这意味着：\n- 对于清单定义的安装逻辑，可以拥有统一且可审计的视图（部分模块故意留有 TODO 语句）\n- 所有模块的错误处理与日志记录保持一致\n- 为未来的安装程序集成铺平了清晰的道路\n\n### 组件\n\n| 组件 | 路径 | 技术 | 用途 |\n|-------|------|--------|---------|\n| **清单** | `acfs.manifest.yaml` | YAML | 作为所有工具的单一真相来源 |\n| **生成器** | `packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts` | TypeScript\u002FBun | 从清单中生成安装脚本 |\n| **网站** | `apps\u002Fweb\u002F` | Next.js 16 + Tailwind 4 | 面向初学者的分步向导 |\n| **安装器** | `install.sh` | Bash | 一条命令的启动脚本 |\n| **库脚本** | `scripts\u002Flib\u002F` | Bash | 模块化安装器函数 |\n| **生成的脚本** | `scripts\u002Fgenerated\u002F` | Bash | 自动生成的类别安装器（由 `install.sh` 提供源码；执行功能已启用特性标志） |\n| **配置文件** | `acfs\u002F` | Shell\u002FTmux 配置文件 | 部署至 `~\u002F.acfs\u002F` 的文件 |\n| **入门引导** | `acfs\u002Fonboard\u002F` | Bash + Markdown | 交互式教程系统 |\n| **校验和** | `checksums.yaml` | YAML | 上游安装器的 SHA256 校验和 |\n\n---\n\n## 清单系统\n\n`acfs.manifest.yaml` 是 ACFS 所安装的所有工具的**单一真相来源**。它定义了要安装哪些内容、如何安装，以及如何验证安装是否成功。\n\n### 清单结构\n\n```yaml\nversion: \"1.0\"\nmeta:\n name: \"ACFS\"\n description: \"Agentic 编程飞轮设置\"\n version: \"0.1.0\"\n\nmodules:\n base.system:\n description: \"基础软件包 + 合理的默认配置\"\n category: base\n install:\n - sudo apt-get update -y\n - sudo apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential\n verify:\n - curl --version\n - git --version\n - jq --version\n\n agents.claude:\n description: \"Claude 代码\"\n category: agents\n install:\n - \"通过官方方式安装 Claude 代码\"\n verify:\n - claude --version || claude --help\n```\n\n每个模块都指定：\n- **描述**：人类可读的名称\n- **类别**：用于组织安装器的分组（基础、Shell、CLI、语言、工具、数据库、云服务、代理、堆栈、ACFS）\n- **安装**：需要运行的命令（或将成为待办事项的说明）\n- **验证**：必须成功执行的命令，以确认安装是否成功\n\n### 生成器流水线\n\nTypeScript 生成器（`packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts`）会读取清单，并生成以下内容：\n\n1. **类别脚本**（`scripts\u002Fgenerated\u002Finstall_base.sh`、`install_agents.sh` 等）\n - 每个类别对应一个脚本，包含各自的安装功能\n - 日志记录与错误处理一致\n - 在每个模块之后执行验证检查\n\n2. **医生检查**（`scripts\u002Fgenerated\u002Fdoctor_checks.sh`）\n - 将所有验证命令提取为可运行的健康检查\n - 使用制表符分隔格式（以安全地处理 Shell 命令中的 `||`）\n - 为每个模块提供通过\u002F失败\u002F跳过的报告\n\n3. **主安装器**（`scripts\u002Fgenerated\u002Finstall_all.sh`）\n - 从所有类别脚本中获取源码\n - 按依赖顺序依次运行这些脚本\n - 作为运行生成的安装器的单一入口点\n\n> 注意：生产用的一条命令安装器（`install.sh`）默认采用旧版实现；生成的安装器则会根据类别来源，并在迁移过程中通过特性标志进行启用。\n\n若在清单发生变更后重新生成：\n\n```bash\ncd packages\u002Fmanifest\nbun run generate # 生成脚本\nbun run generate:dry # 预览，不写入文件\n```\n\n### 为什么选择 TypeScript 进行代码生成？\n\nShell 可以使用 `yq` 解析 YAML，但 TypeScript + Zod 提供了以下优势：\n- **类型安全**：解析器能够准确了解清单的精确结构\n- **验证**：Zod 会以清晰的错误提示捕捉格式不正确的 YAML\n- **转换**：复杂的逻辑（如按依赖排序、转义）在 TypeScript 中自然流畅\n- **一致性**：所有生成的代码遵循相同的模式\n\n生成器本身仅约 400 行 TypeScript 代码。生成的输出则多达 1000 行 Bash 代码，共 13 个文件。这种权衡显然更有利于保持生成器的稳定性。\n\n---\n\n## 安全验证\n\nACFS 会从互联网上下载并执行安装器脚本。这本身就存在风险——上游如果遭到入侵，可能会注入恶意代码。安全验证系统正是为了降低这种风险而设计的。\n\n### 工作原理\n\n`checksums.yaml` 文件中包含了所有上游安装器脚本的 SHA256 校验和：\n\n```yaml\n# checksums.yaml\ninstallers:\n bun:\n url: \"https:\u002F\u002Fbun.sh\u002Finstall\"\n sha256: \"a1b2c3d4...\"\n\n rust:\n url: \"https:\u002F\u002Fsh.rustup.rs\"\n sha256: \"e5f6a7b8...\"\n```\n\n安全库（`scripts\u002Flib\u002Fsecurity.sh`）提供了以下功能：\n\n1. **HTTPS 防护**：所有安装器 URL 必须使用 HTTPS。非 HTTPS 的 URL 会立即被拒绝。\n\n2. **校验和验证**：在执行下载的脚本之前，系统会：\n - 将内容下载到内存\n - 计算 SHA256 校验和\n - 与存储的校验和进行比对\n - 只有在校验和匹配时才执行脚本\n\n3. **验证模式**：\n ```bash\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --print # 列出所有上游 URL\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --verify # 对所有 URL 进行校验和验证\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums # 生成新的 checksums.yaml\n .\u002Fscripts\u002Flib\u002Fsecurity.sh --checksum URL # 计算任意 URL 的 SHA256 校验和\n ```\n\n### 校验和失败时的情况\n\n校验和不匹配可能意味着：\n1. **正常更新**：上游维护人员发布了新版本\n2. **潜在威胁**：有人恶意修改了脚本\n\n验证报告会区分这两种情况：\n- 若多个校验和同时失败，请在更新前进行深入调查\n- 若在已知版本发布后，单个校验和失败，则更新很可能安全\n\n若需在验证合法的上游变更后进行更新：\n```bash\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums > checksums.yaml\ngit diff checksums.yaml # 查看具体更改内容\ngit commit -m \"chore: 更新上游校验和\"\n```\n\n### 为何采用这种方式？\n\n`curl | bash` 的模式虽备受争议，但其实很实用。ACFS 通过以下方式使其更加安全：\n- 在执行前验证内容（而不仅仅是通过 HTTPS 进行传输）\n- 让校验和在版本控制中可审计\n- 提供工具来检测和调查变更\n- 在出现不匹配时直接失败，而非继续执行\n\n这是一种纵深防御策略——HTTPS 保护传输，校验和保护内容。\n\n---\n\n## 安装器\n\n安装器是 ACFS 的核心——一个模块化的 Bash 脚本，可将全新的 Ubuntu VPS 转化为一个完全配置好的开发环境。\n\n### 使用方法\n\n完整氛围模式（推荐用于一次性使用的 VPS）：\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n交互式模式（询问确认）：\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash\n```\n\n安全模式（无需密码的 sudo，且已启用代理确认）：\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --mode safe\n```\n\n### 安装模式\n\n| 模式 | 无密码 sudo | 代理标志 | 最适合场景 |\n|------|-------------------|-------------|----------|\n| **vibe** | 是 | `--dangerously-skip-permissions` | 一次性 VPS，追求极致速度 |\n| **safe** | 否 | 标准确认提示 | 适用于生产级环境 |\n\n### 安装阶段\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n A[\"第一阶段：用户规范化\u003Cbr\u002F>\u003Csmall>创建 Ubuntu 用户，迁移 SSH 密钥\u003C\u002Fsmall>\"]\n B[\"第二阶段：APT 包\u003Cbr\u002F>\u003Csmall>安装系统必备软件包\u003C\u002Fsmall>\"]\n C[\"第三阶段：Shell 配置\u003Cbr\u002F>\u003Csmall>zsh、Oh-My-Zsh、Powerlevel10k\u003C\u002Fsmall>\"]\n D[\"第四阶段：CLI 工具\u003Cbr\u002F>\u003Csmall>ripgrep、fzf、lazygit 等\u003C\u002Fsmall>\"]\n E[\"第五阶段：语言运行时\u003Cbr\u002F>\u003Csmall>bun、uv、Rust、Go\u003C\u002Fsmall>\"]\n F[\"第六阶段：AI 代理\u003Cbr\u002F>\u003Csmall>Claude、Codex、Gemini\u003C\u002Fsmall>\"]\n G[\"第七阶段：云工具\u003Cbr\u002F>\u003Csmall>Vault、Wrangler、Supabase、Vercel\u003C\u002Fsmall>\"]\n H[\"第八阶段：Dicklesworthstone 堆栈\u003Cbr\u002F>\u003Csmall>NTM、DCG、RU、UBS、MCP_Agent_Mail 等\u003C\u002Fsmall>\"]\n I[\"第九阶段：配置\u003Cbr\u002F>\u003Csmall>部署 acfs.zshrc、tmux.conf\u003C\u002Fsmall>\"]\n J[\"第十阶段：验证\u003Cbr\u002F>\u003Csmall>acfs doctor\u003C\u002Fsmall>\"]\n\n A --> B --> C --> D --> E --> F --> G --> H --> I --> J\n\n classDef phase fill:#e8f5e9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n class A,B,C,D,E,F,G,H,I,J phase\n```\n\n### 关键属性\n\n| 属性 | 描述 |\n|------|-------------|\n| **幂等性** | 可安全重复运行；可跳过已安装的工具 |\n| **已检查状态** | 各个阶段将自动从 `~\u002F.acfs\u002Fstate.json` 中恢复 |\n| **预检查通过** | 在安装前运行 `scripts\u002Fpreflight.sh` 脚本，以检测并修复潜在问题 |\n| **日志记录** | 输出带有彩色进度指示器 |\n| **模块化设计** | 每个类别都是一段独立且可复用的脚本 |\n\n### 恢复能力\n\n安装程序会将进度记录在 `~\u002F.acfs\u002Fstate.json` 中。若中途中断：\n- 重新执行同一命令——即可从上一个已完成的阶段继续执行\n- 无需提示或确认（使用 `--yes` 参数）\n- 已安装的工具会被自动检测并跳过。\n\n若需强制重新安装所有工具：\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --force-reinstall\n```\n\n### 预检查\n\n在运行完整安装程序之前，请先验证您的系统：\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash -s -- --json\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fpreflight.sh\" | bash -s -- --format toon\n```\n\n此脚本会检查以下内容：\n- 操作系统兼容性（Ubuntu 22.04+；安装程序升级至 25.10）\n- 架构类型（x86_64 或 ARM64）\n- 内存与磁盘空间（最低 4GB RAM，10GB 空闲磁盘）\n- 网络连接是否可达所需 URL\n- APT 锁定状态\n- 可能存在的冲突（nvm、pyenv、现有 ACFS）\n\n**网络检查结果：**\n| 检查项 | 检查内容 | 若失败则需解决 |\n|-------|------------------|----------------|\n| DNS 解析 | 是否能解析 github.com、raw.githubusercontent.com | 检查 `\u002Fetc\u002Fresolv.conf` 或添加 `8.8.8.8` |\n| GitHub HTTPS | 是否能访问 github.com:443 | 检查防火墙、代理或 VPN 设置 |\n| 安装程序 URL | GitHub、Homebrew、Oh-My-Zsh、Rust 等的原始仓库地址 | 可能需要重试；短暂故障可接受 |\n| APT 镜像 | 是否能访问默认的 Ubuntu 镜像 | 检查 `\u002Fetc\u002Fapt\u002Fsources.list` 或尝试其他镜像 |\n\n**常见预检查失败情况：**\n\n| 错误 | 原因 | 解决方案 |\n|-------|------------------|----------|\n| “无法解析 github.com” | DNS 配置错误 | 在 `\u002Fetc\u002Fresolv.conf` 中添加 `nameserver 8.8.8.8` |\n| “无法访问 github.com” | 防火墙阻止 HTTPS | 允许出站端口 443 |\n| “APT 镜像速度慢或无法访问” | 地区性镜像服务宕机 | 修改 `\u002Fetc\u002Fapt\u002Fsources.list` 为使用 `archive.ubuntu.com` |\n| “APT 锁定” | 其他 APT 进程正在运行 | 等待进程完成，或使用 `sudo kill \u003Cpid>` |\n| “磁盘空间不足” | 磁盘剩余空间少于 10GB | 使用 `sudo apt autoremove` 清理缓存，或扩展磁盘空间 |\n\n### 控制台输出\n\n安装程序采用语义化颜色来区分进度：\n\n```bash\n[1\u002F8] 正在安装必备软件包... # 蓝色：进度步骤\n 正在安装 zsh、git、curl... # 灰色：详细信息\n⚠️ 可能需要几分钟时间 # 黄色：警告\n✖ 安装软件包失败 # 红色：错误\n✔ Shell 配置已完成 # 绿色：成功\n```\n\n### 自动 Ubuntu 升级\n\n当 ACFS 在旧版本上运行时，会在安装前自动将 Ubuntu 升级至版本 **25.10**。此举可确保与最新软件包的兼容性，并获得最佳性能。\n\n**工作原理：**\n1. 检测当前使用的 Ubuntu 版本\n2. 计算升级路径（例如：24.04 → 25.04 → 25.10）\n3. 依次执行 `do-release-upgrade` 操作\n4. 每次升级后自动重启\n5. 重启后通过 systemd 服务继续运行\n6. 当达到目标版本时，继续进行 ACFS 的安装过程\n\n**预计时间表：**\n- 每个版本的升级耗时 30–60 分钟\n- 从 24.04 到 25.10 的完整升级链需时 1.5–3 小时\n- 重启期间 SSH 会话会断开（需重新连接以监控进度）\n\n**若要跳过自动升级：**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --skip-ubuntu-upgrade\n```\n\n**若要指定不同的目标版本：**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh\" | bash -s -- --yes --mode vibe --target-ubuntu=25.04\n```\n\n**监控升级进度：**\n```bash\n# 查看当前状态\n\u002Fvar\u002Flib\u002Facfs\u002Fcheck_status.sh\n\n# 查看升级日志\njournalctl -u acfs-upgrade-resume -f\n\n# 查看详细日志\ntail -f \u002Fvar\u002Flog\u002Facfs\u002Fupgrade_resume.log\n```\n\n**重要提示：**\n- 在升级前创建虚拟机快照（建议操作，但非必须）\n- 未通过快照恢复，升级将无法撤销\n- 系统会自动多次重启\n- 如果某些临时发布的版本（如 24.10）不再由 `do-release-upgrade` 提供，可能会被自动跳过\n- 每次重启后需通过 SSH 重新连接，以监控升级进度\n\n---\n\n## 更新命令\n\n安装完成后，工具的持续更新由 `acfs-update` 负责。它提供了一个统一的界面，用于更新所有已安装的组件。\n\n### 使用方法\n\n```bash\nacfs-update # 更新 APT、运行时、Shell、代理及云 CLI\nacfs-update --stack # 包含 Dicklesworthstone 堆栈工具\nacfs-update --agents-only # 仅更新编码代理\nacfs-update --runtime-only # 仅更新运行时（bun、Rust、uv、Go）\nacfs-update --dry-run # 预览变更，无需实际执行\nacfs-update --yes --quiet # 自动化\u002FCI 模式，输出极简\n```\n\n---\n\n### 总结\n\nACFS 通过自动化流程和模块化设计，确保了工具的高效安装与持续更新。无论是从基础的系统配置到高级的 AI 代理，ACFS 都能轻松应对各种需求。\n\n### 更新内容\n\n| 类别 | 工具 | 方法 |\n|------|------|------|\n| **系统** | apt 包 | `apt update && apt upgrade` |\n| **Shell** | OMZ、P10K、插件 | 每个仓库执行 `git pull` |\n| **Shell** | Atuin、Zoxide | 重新运行上游安装器 |\n| **运行时** | Bun | `bun upgrade` |\n| **运行时** | Rust | `rustup update stable` |\n| **运行时** | uv（Python） | `uv self update` |\n| **运行时** | Go | `apt upgrade`（若由 apt 管理） |\n| **代理** | Claude Code | `claude update --channel latest` |\n| **代理** | Codex、Gemini | `bun install -g @latest` |\n| **云服务** | Wrangler、Vercel | `bun install -g @latest` |\n| **云服务** | Supabase | GitHub 发布 tarball（sha256 校验码） |\n| **堆栈** | ntm、slb、ubs、dcg、ru 等 | 重新运行上游安装器 |\n\n### 选项\n\n**类别选择：**\n```bash\n--apt-only 仅更新系统包\n--agents-only 仅更新编码代理\n--cloud-only 仅更新云 CLI\n--shell-only 仅更新 Shell 工具（OMZ、P10K、插件、Atuin、Zoxide）\n--runtime-only 仅更新运行时（bun、rust、uv、go）\n--stack 包含 Dicklesworthstone 堆栈（默认启用）\n```\n\n**跳过某些类别：**\n```bash\n--no-apt 跳过 apt 更新\n--no-agents 跳过代理更新\n--no-cloud 跳过云 CLI 更新\n--no-shell 跳过 Shell 工具更新\n--no-runtime 跳过运行时更新（bun、rust、uv、go）\n```\n\n**行为：**\n```bash\n--force 安装缺失的工具（不只是更新现有工具）\n--dry-run 预览更改，无需实际执行\n--yes, -y 非交互式模式（跳过提示）\n--quiet, -q 最小化输出（仅显示错误和概要）\n--verbose, -v 显示详细的命令输出\n--abort-on-failure 在首次失败时停止（默认继续）\n```\n\n### 日志\n\n更新日志会自动保存至 `~\u002F.acfs\u002Flogs\u002Fupdates\u002F`，并附带时间戳：\n```bash\n# 查看最新日志\ncat ~\u002F.acfs\u002Flogs\u002Fupdates\u002F$(ls -1t ~\u002F.acfs\u002Flogs\u002Fupdates | head -1)\n\n# 监控正在运行的更新\ntail -f ~\u002F.acfs\u002Flogs\u002Fupdates\u002F$(ls -1t ~\u002F.acfs\u002Flogs\u002Fupdates | head -1)\n```\n\n### 为何要与安装器分开？\n\n安装器会将全新 VPS 进行改造；而更新命令则在原有安装基础上进行维护。将两者分开，可实现以下目标：\n- **专注更新**：仅更新代理，而不触碰系统包\n- **预览变更**：在提交更改前，先查看将要发生的变化\n- **跳过特定类别**：暂时排除那些运行良好的类别\n- **控制堆栈**：堆栈更新默认包含在内；若需跳过，可使用 `--no-stack`\n- **自动化更新**：通过 cron 任务执行，配合 `--yes --quiet` 使用\n\n---\n\n## ACFS 命令行工具\n\n安装完成后，`acfs` 命令为您的环境管理提供了一个统一的接口。每个子命令都经过精心设计，既快速又信息丰富，且支持脚本化操作。\n\n### 快速参考\n\n```bash\nacfs info # 极速系统概览\nacfs cheatsheet # 查看已安装的别名\nacfs dashboard generate # 生成 HTML 状态页面\nacfs doctor # 运行健康检查\nacfs newproj # 创建新项目（TUI 或 CLI）\nacfs update # 更新所有工具\nacfs services-setup # 配置代理凭据\nacfs continue # 在重启后查看升级进度\n```\n\n### `acfs newproj` — 新项目向导\n\n创建一个新项目目录，采用 ACFS 的默认配置（Git 初始化、可选的 br\u002Fbeads、Claude 设置、AGENTS.md）。\n建议初学者使用交互式向导。\n\n交互式向导（推荐使用）：\n```bash\nacfs newproj --interactive\nacfs newproj -i\nacfs newproj -i myapp # 预填项目名称\n```\n\n向导会引导您完成以下步骤：\n- 项目命名与位置\n- 技术栈检测\u002F选择\n- 功能选型（br\u002Fbeads、Claude 设置、AGENTS.md、UBS 忽略）\n- AGENTS.md 自定义预览\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>TUI 向导截图\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**欢迎界面：**\n```\n ╔═══════════════════════════════════════════════════════╗\n ║ ║\n ║ █████╗ ██████╗ ███████╗ ███████╗ ║\n ║ ██╔══██╗██╔════╝ ██╔════╝ ██╔════╝ ║\n ║ ███████║██║ █████╗ ███████║ ║\n ║ ██╔══██║██║ ██╔══╝ ╚════██║ ║\n ║ ██║ ██║╚██████╗ ██║ ███████║ ║\n ║ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚══════╝ ║\n ║ ║\n ║ Agentic Coding Flywheel 设置 ║\n ║ ║\n ╚═══════════════════════════════════════════════════════╝\n\n本向导将帮助您设置新项目：\n\n ✓ 项目目录结构\n ✓ Git 仓库初始化\n ✓ AGENTS.md 用于 AI 编程助手\n ✓ Beads 问题跟踪（可选）\n ✓ Claude Code 设置（可选）\n```\n\n**确认界面：**\n```\n──────────────────── 审核与确认 ────────────────────\n 第 7 步，共 9 步\n\n请在创建项目前仔细审核您的选择。\n\n项目概览\n──────────────────────────────────────────────────────────\n 名称： myapp\n 位置： \u002Fhome\u002Fuser\u002Fprojects\u002Fmyapp\n 技术： Node.js、TypeScript\n\n功能\n──────────────────────────────────────────────────────────\n ✓ Beads 跟踪\n ✓ Claude Code 设置\n ✓ AGENTS.md\n ✓ UBS 忽略\n\n需要创建的文件\n──────────────────────────────────────────────────────────\nmyapp\u002F\n├── .git\u002F\n├── AGENTS.md\n├── .beads\u002F\n│ └── beads.db\n├── .claude\u002F\n│ └── settings.local.json\n├── .ubsignore\n├── README.md\n└── .gitignore\n\n选项：\n [Enter\u002Fc] 创建项目\n [e] 编辑选择（返回上一步）\n [q\u002FEsc] 取消\n```\n\n\u003C\u002Fdetails>\n\nCLI 模式（自动化）：\n```bash\nacfs newproj myapp\nacfs newproj myapp \u002Fcustom\u002Fpath\nacfs newproj myapp --no-br\n```\n\n注意：\n- TUI 在可用时会使用“Gum”键盘快捷键（箭头键、空格键切换、Enter 键确认）。若无 Gum，系统会退回到数字提示。\n- 最小终端尺寸：60x15。\n- CLI 模式会跳过已存在的 AGENTS.md；向导会覆盖该文件，因此如果您希望保留旧版本，请将其移至一旁。\n\n### `acfs info` — 系统概览\n\n通过读取缓存状态（无需验证），可在不到1秒内显示安装状态。\n\n```bash\nacfs info # 默认终端输出\nacfs info --json # 用于脚本编写的 JSON 输出\nacfs info --html # 自包含的 HTML 页面\nacfs info --minimal # 仅提供基本信息（IP、关键命令）\n```\n\n示例输出：\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ACFS 系统信息 ║\n╠══════════════════════════════════════════════════════════════╣\n║ 主机：vps-12345.contabo.net ║\n║ IP：192.168.1.100 ║\n║ 用户：ubuntu ║\n║ 运行时间：3天4小时 ║\n║ ║\n║ 快速命令： ║\n║ cc → Claude Code（危险模式） ║\n║ cod → Codex CLI（危险模式） ║\n║ gmi → Gemini CLI（Yolo 模式） ║\n║ ntm → Named Tmux Manager ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n**设计理念：**\n- **速度**：必须在1秒内完成。\n- **只读**：绝不进行验证或测试（这属于医生的职责）。\n- **离线**：无需网络调用。\n- **容错**：若数据缺失，可实现优雅降级。\n\n### `acfs cheatsheet` — 别名发现\n\n解析 `~\u002F.acfs\u002Fzsh\u002Facfs.zshrc` 文件，展示所有已安装的别名和命令。\n\n```bash\nacfs cheatsheet # 列出所有别名\nacfs cheatsheet git # 根据类别或搜索词进行筛选\nacfs cheatsheet --category Agents\nacfs cheatsheet --search docker\nacfs cheatsheet --json # 用于工具开发的 JSON 输出\n```\n\n示例输出：\n```\n╔══════════════════════════════════════════════════════════════╗\n║ ACFS 别名表 ║\n╠══════════════════════════════════════════════════════════════╣\n║ 代理 ║\n║ cc → claude --dangerously-skip-permissions ║\n║ cod → codex --dangerously-bypass-approvals-and-sandbox ║\n║ gmi → gemini --yolo ║\n║ ║\n║ Git ║\n║ gs → git status ║\n║ gp → git push ║\n║ gl → git pull ║\n║ gco → git checkout ║\n║ ║\n║ 现代 CLI ║\n║ ls → lsd --inode --long --all ║\n║ cat → bat ║\n║ grep → rg ║\n║ lg → lazygit ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n### `acfs dashboard` — HTML 状态页面\n\n生成自包含的 HTML 状态页面，并可选择将其服务化。\n\n```bash\nacfs dashboard generate # 生成 ~\u002F.acfs\u002Fdashboard\u002Findex.html\nacfs dashboard generate --force # 强制重新生成\nacfs dashboard serve # 在本地主机 8080 上提供服务\nacfs dashboard serve --port 3000 # 自定义端口\nacfs dashboard serve --public # 绑定到 0.0.0.0\n```\n\n仪表板提供以下功能：\n- 系统健康状况一目了然\n- 工具版本与状态\n- 快速命令参考\n- 最近活动汇总\n\n### `acfs services-setup` — 凭证配置\n\n交互式向导，用于配置 AI 代理凭证及云服务登录信息。\n\n```bash\nacfs services-setup # 运行完整的设置向导\n```\n\n引导您完成以下步骤：\n- **Claude Code**：API 密钥配置\n- **Codex CLI**：ChatGPT 账户登录\n- **Gemini CLI**：Google 账户认证\n- **GitHub CLI**：`gh auth login`\n- **云 CLI**：Wrangler、Supabase、Vercel 认证\n\n此外，还提供安装 **DCG（破坏性指令守护器）** 的选项，该工具可拦截诸如 `rm -rf \u002F` 这类破坏性命令。\n\n### `acfs continue` — 升级进度\n\n在 Ubuntu 升级后重启系统时，查看安装进度：\n\n```bash\nacfs continue # 显示当前升级状态\n```\n\n显示内容包括：\n- 原始 Ubuntu 版本\n- 目标版本\n- 当前升级阶段\n- 完成后的下一步操作\n\n---\n\n## 学习中心（网页）\n\n除了基于终端的入门引导外，ACFS 还在 [agent-flywheel.com\u002Flearn](https:\u002F\u002Fagent-flywheel.com\u002Flearn) 提供了一个全面的网页学习中心。\n\n### 网页课程\n\n学习中心提供互动式课程，并具备进度追踪功能：\n\n| # | 课程 | 时长 | 课程主题 |\n|---|--------|----------|--------|\n| 0 | 欢迎与概述 | 5 分钟 | 介绍已安装的工具、思维模型 |\n| 1 | Linux 导航 | 8 分钟 | 文件系统结构、核心命令 |\n| 2 | SSH 与持久化 | 6 分钟 | 安全连接、保持持续连接 |\n| 3 | tmux 基础 | 7 分钟 | 会话、窗口、分屏、生存之道 |\n| 4 | Git 基础 | 10 分钟 | 版本控制、危险操作 |\n| 5 | GitHub CLI | 8 分钟 | 通过 `gh` 处理问题、PR、发布 |\n| 6 | 代理命令 | 10 分钟 | Claude、Codex、Gemini 的使用 |\n| 7 | NTM 命令中心 | 8 分钟 | 会话编排 |\n| 8 | NTM 提示符面板 | 6 分钟 | 快速访问命令 |\n| 9 | 飞轮循环 | 8 分钟 | 10 个工具如何协同工作 |\n\n**特点：**\n- 进度追踪存储于 localStorage 中\n- 代码块附带复制按钮\n- 可扩展的深度探索章节\n- 实践练习\n\n### 命令参考\n\n[命令参考](https:\u002F\u002Fagent-flywheel.com\u002Flearn\u002Fcommands) 文档记录了每一种已安装的工具：\n\n| 类别 | 命令 |\n|------|------|\n| **代理** | `cc`, `cod`, `gmi` |\n| **搜索** | `rg`, `fd`, `sg`, `fzf` |\n| **Git** | `lg`, `gh`, `git-lfs` |\n| **系统** | `z`, `bat`, `lsd`, `atuin`, `tmux` |\n| **堆栈** | `ntm`, `bv`, `am`, `cass`, `cm`, `ubs`, `slb`, `caam`, `dcg`, `ru` |\n| **语言** | `bun`, `uv`, `cargo`, `go` |\n| **云服务** | `wrangler`, `supabase`, `vercel`, `vault` |\n\n### 技术术语表\n\n[术语表](https:\u002F\u002Fagent-flywheel.com\u002Fglossary) 定义了 100 多个技术术语，包括：\n- **单行命令**：快速提示定义\n- **完整解释**：通俗易懂的语言描述\n- **类比**：“可以这样想……”\n- **为何使用**：它解决了什么问题\n- **相关术语**：为背景信息提供参考\n\n示例条目：\n```\nRAM（随机存取内存）\n├── 简称：计算机在工作时使用的快速临时存储\n├── 深入理解：RAM 是你电脑的短期记忆……\n├── 类比：就像你在工作时的桌面空间\n├── 为什么：更多 RAM 可以同时运行更多程序\n└── 相关术语：vCPU、VPS、NVMe\n```\n\n### 飞轮可视化\n\n[飞轮页面](https:\u002F\u002Fagent-flywheel.com\u002Fflywheel) 可以直观地展示工具之间的交互关系：\n\n```\n计划（珠子）——> 协调（代理邮件）——> 执行（NTM + 代理）\n ^ │\n │ v\n └──── 记忆（CASS 内存） \u003C──── 扫描（UBS） ┘\n```\n\n**工作流场景：**\n\n| 场景 | 描述 | 时间 |\n|------|-------|------|\n| 每日并行进展 | 3 个以上项目同时进行 | 3 小时以上 |\n| 代理审查代理 | 在合并前进行交叉审核 | 30 分钟 |\n| 增强记忆的调试 | 用于解决当前缺陷的过往方案 | 15 分钟 |\n| 协同功能开发 | 多个代理共同完成一项功能 | 2 小时以上 |\n\n### 工具状态页面\n\n[工具状态页面](https:\u002F\u002Fagent-flywheel.com\u002Ftools) 提供了一个可搜索的工具目录，其中列出了所有已安装的工具：\n\n- **搜索与筛选**：按名称、CLI 命令、功能或技术栈来查找工具\n- **分类浏览**：可根据“飞轮堆栈”（核心代理工具）或“实用工具”进行筛选\n- **工具详情**：每张卡片均显示工具名称、CLI 命令、GitHub 星标、功能以及技术栈\n- **实时数据**：内容由 `acfs.manifest.yaml` 自动生成——从未手动编辑\n\n该页面帮助用户发现自己可能尚未了解的工具，并了解每种工具在代理式编码工作流程中的具体位置。\n\n### 交互式网站组件\n\n向导网站内置了专门的组件，用于引导新手用户：\n\n**连接检查组件：**\n一个醒目的可视化界面，可帮助用户在运行命令前验证是否已成功连接到其 VPS：\n- 对比两者的侧边栏：“错误（笔记本电脑）” vs “正确（VPS）”\n- 提供适用于 Windows、Mac 和 Linux 的终端提示示例\n- 通过彩色样式清晰警示“STOP！”字样\n\n**命令卡片组件：**\n提供 CLI 指令卡片，具备以下功能：\n- 语法高亮的代码块\n- 一键复制按钮\n- 适用于不同平台的版本（bash\u002Fzsh\u002FPowerShell）\n- 可扩展的解释说明\n\n**术语组件（响应式技术术语）：** \n一套复杂的工具提示系统，能够根据设备能力灵活调整：\n\n*桌面端行为：*\n- 鼠标悬停时会弹出浮动工具提示，显示术语的定义\n- 使用 Radix UI 工具提示，实现无障碍的 ARIA 兼容覆盖层\n- 视口感知定位（靠近边缘时自动翻转）\n- 200ms 的悬停延迟，避免工具提示信息过载\n\n*移动端行为：*\n- 点击后会打开底部抽屉式菜单（Vaul 库）\n- 完整的术语定义无需依赖微小的点击目标即可查看\n- 支持滑动关闭手势\n- 提供对称点和全屏展开选项\n\n*视觉特征：*\n- 渐变下划线表示可点击的术语\n- 每个术语都会根据 slug 哈希赋予独特的渐变效果\n- 配色方案与 OKLCH 标记保持一致\n\n*术语内容结构：*\n```typescript\n{\n term: \"VPS\",\n short: \"虚拟专用服务器——一种您租用的远程计算机\",\n long: \"VPS 是您专属的一片强大计算机……\"\n}\n```\n\n**彩带庆祝：** \n在课程结束时：\n- 突然绽放大量庆祝彩带颗粒\n- 随机出现鼓励性留言\n- 特别为完成所有课程而举办的庆祝活动\n- 严格遵守 `prefers-reduced-motion` 设置\n\n**步进器组件：** \n多步骤进度指示器：\n- 以可视化方式逐步推进进度\n- 支持点击导航\n- 添加完成标记\n- 设计兼顾移动端需求\n\n### 扩展的课程库\n\n学习中心为迪克尔斯沃斯通堆栈中的每种工具都提供了专门的课程：\n\n| 课程 | 主题 |\n|------|-------|\n| **UBS（漏洞扫描器）** | 扫描工作流、严重等级、CI 集成 |\n| **代理邮件** | 注册、消息传递、文件预约 |\n| **CASS（会话搜索）** | 索引、搜索、跨代理查询 |\n| **CASS 内存（cm）** | 规则提取、剧本管理 |\n| **珠子** | 问题跟踪、图表指标、优先级 |\n| **SLB（安全）** | 两人规则、危险命令审批 |\n| **提示工程** | 有效提示、上下文管理 |\n| **现实案例研究** | 从头到尾的功能开发全流程演练 |\n\n每门课程均包含：\n- 概念介绍\n- 实践命令及示例\n- 互动练习\n- 常见的陷阱与注意事项\n- 工具文档链接\n\n---\n\n## 交互式入门指南（TUI）\n\n安装完成后，用户可通过交互式终端教程学习 ACFS 工作流。入门 TUI 会动态从 `acfs\u002Fonboard\u002Flessons` 中发现课程 Markdown 文件，因此随着新工具和新工作流的添加，课程体系也能随之不断扩展，而无需更改启动器本身。\n\n### 运行入门指南\n\n```bash\nonboard # 启动交互式菜单\nonboard status # 显示完成状态\nonboard --list # 简写形式，等同于 status\nonboard 3 # 跳转至第 3 课\nonboard reset # 重置进度，重新开始\nonboard --reset # 简写形式，等同于 reset\n```\n\n### 课程\n\n运行 `onboard --help` 可查看当前已发现的课程列表。目前，课程体系涵盖 Linux 基础、SSH、tmux、代理登录、NTM、飞轮工作流、更新、珠子、RCH 以及其他 ACFS 工具。由于课程是按文件名发现的，只需新增一个 `NN_name.md` 文件，教程便会自动扩展。\n\n### 进度追踪\n\n进度保存在 `~\u002F.acfs\u002Fonboard_progress.json` 中：\n\n```json\n{\n \"completed\": [0, 1, 2],\n \"current\": 3,\n \"started_at\": \"2024-12-20T10:30:00-05:00\"\n}\n```\n\nTUI 会显示每节课的完成状态，并提示用户接下来要学习哪一课。用户可以跳转至任意课程，也可以重新学习已完成的课程。\n\n### 通过 Gum 提升用户体验\n\n若已安装 [Charmbracelet Gum](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fgum)，入门系统会利用 Gum 来优化终端界面——包括选择菜单、样式化提示以及更出色的排版效果。若未安装 Gum，则系统会退回到简单的数字菜单，但依然能在任何地方正常运行。\n\n---\n\n## 已安装工具\n\nACFS 安装了一套全面的工具集合，共包含 **30 多种工具**，并按类别进行了整理：\n\n### Shell 与终端体验\n\n| 工具 | 命令 | 描述 |\n|------|------|-------------|\n| **zsh** | `zsh` | 现代 Shell |\n| **oh-my-zsh** | - | zsh 插件框架 |\n| **powerlevel10k** | - | 快速、可自定义的提示符 |\n| **lsd** | `ls`（别名） | 带图标的新一代 ls 命令 |\n| **atuin** | `Ctrl+R` | 带搜索功能的 Shell 历史记录 |\n| **fzf** | `fzf` | 模糊查找工具 |\n| **zoxide** | `z` | 更智能的 cd 命令 |\n| **direnv** | - | 目录特定的环境变量 |\n\n### 编程语言与包管理器\n\n| 工具 | 命令 | 描述 |\n|------|------|-------------|\n| **bun** | `bun` | 快速的 JS\u002FTS 运行时 + 包管理器 |\n| **uv** | `uv` | 快速的 Python 包管理器 |\n| **Rust** | `cargo` | Rust 工具链 |\n| **Go** | `go` | Go 工具链 |\n\n### 开发工具\n\n| 工具 | 命令 | 说明 |\n|------|---------|-------------|\n| **tmux** | `tmux` | 终端多路复用器 |\n| **ripgrep** | `rg` | 快速递归式 grep |\n| **ast-grep** | `sg` | 结构化代码搜索 |\n| **lazygit** | `lg`（别名）| Git TUI |\n| **GitHub CLI** | `gh` | GitHub 身份验证、问题、PR |\n| **Git LFS** | `git-lfs` | 适用于 Git 的大文件支持 |\n| **bat** | `cat`（别名）| 支持语法高亮的 cat 命令 |\n| **neovim** | `nvim` | 现代版 Vim |\n| **jq** | `jq` | JSON 处理器 |\n| **rsync** | `rsync` | 快速文件同步\u002F复制 |\n| **lsof** | `lsof` | 调试打开的文件\u002F端口 |\n| **dnsutils** | `dig` | DNS 调试 |\n| **netcat** | `nc` | 网络调试 |\n| **strace** | `strace` | 系统调用追踪 |\n\n### 网络相关\n\n| 工具 | 命令 | 说明 |\n|------|---------|-------------|\n| **Tailscale** | `tailscale` | 无需配置即可实现的网状 VPN |\n\n**Tailscale 集成：**\n\nTailscale 提供了一种安全且加密的网络连接方案，可在设备之间实现无缝通信，而无需复杂的防火墙配置：\n\n```bash\n# 身份验证并加入你的 tailnet\ntailscale up\n\n# 检查连接状态\ntailscale status\n\n# 获取你的 Tailscale IP 地址\ntailscale ip\n\n# 通过 Tailscale 进行 SSH 连接（绕过防火墙）\nssh ubuntu@your-vps.tailnet-name.ts.net\n```\n\n适用于代理型工作流的优势：\n- **无防火墙限制的访问**：即使身处 NAT 或受限的防火墙后，也能轻松连接。\n- **MagicDNS**：可通过主机名而非 IP 地址直接访问你的 VPS。\n- **通过 Tailscale 使用 SSH 密钥**：只需执行 `tailscale ssh` 即可实现免密认证。\n- **ACL 权限控制**：为团队环境提供细粒度的权限管理。\n\n### AI 编程代理\n\n| 代理 | 命令 | 别名（Vibe 模式） |\n|-------|---------|-------------------|\n| **Claude Code** | `claude` | `cc`（危险模式） |\n| **Codex CLI** | `codex` | `cod`（危险模式） |\n| **Gemini CLI** | `gemini` | `gmi`（危险模式） |\n\n**Vibe 模式别名：**\n```bash\n# Claude Code，使用最大内存（默认启用后台任务）\nalias cc='NODE_OPTIONS=\"--max-old-space-size=32768\" claude --dangerously-skip-permissions'\n\n# Codex，采用绕过机制并允许对文件系统进行危险操作\nalias cod='codex --dangerously-bypass-approvals-and-sandbox'\n\n# Gemini，采用 Yolo 模式\nalias gmi='gemini --yolo'\n```\n\n**安装与更新：**\nClaude Code 应通过其原生机制进行安装与更新：\n- **安装**：ACFS 使用官方原生安装器（`claude.ai\u002Finstall.sh`），并通过 `checksums.yaml` 进行校验（安装路径为 `~\u002F.local\u002Fbin\u002Fclaude`）。\n- **更新**：使用 `claude update --channel latest`（内置功能），或运行 `acfs update --agents-only`。\n\n这样可以确保正确的身份验证处理，并避免因其他包管理器构建而导致的问题。对于 Codex 和 Gemini，ACFS 采用标准的 Bun 全局包更新机制。\n\n### 云服务与数据库\n\n| 工具 | 命令 | 说明 |\n|------|---------|-------------|\n| **PostgreSQL 18** | `psql` | 数据库 |\n| **HashiCorp Vault** | `vault` | 密钥管理 |\n| **Wrangler** | `wrangler` | Cloudflare CLI |\n| **Supabase CLI** | `supabase` | Supabase 管理工具 |\n| **Vercel CLI** | `vercel` | Vercel 部署 |\n\nVault 默认已安装（可通过 `--skip-vault` 跳过）。ACFS 会安装 Vault 的 **CLI**，以便您能尽早使用真正的密钥管理工具；它不会自动为您配置 Vault 服务器。\n\nSupabase 网络注意事项：部分 Supabase 项目会公开 **仅支持 IPv6 的 Postgres 直连主机**（通常在免费套餐中可用）。如果您的 VPS 或网络仅支持 IPv4，请改用 Supabase 的 **池化** 连接字符串（或升级\u002F配置网络，以实现直接的 IPv4 连接）。\n\n### Dicklesworthstone 堆栈（10 个工具）\n\n专业代理型工作流的完整工具套件：\n\n| # | 工具 | 命令 | 说明 |\n|---|------|---------|-------------|\n| 1 | **命名 Tmux 管理器** | `ntm` | 代理控制台——启动、编排并监控 tmux 会话 |\n| 2 | **MCP 代理邮件** | `am` | 通过类似邮件的通讯方式实现代理协调（Rust 二进制程序） |\n| 3 | **终极漏洞扫描器** | `ubs` | 带有防护措施的漏洞扫描工具 |\n| 4 | **Beads 查看器** | `bv` | 带有图形分析功能的任务管理 TUI |\n| 5 | **编程代理会话搜索** | `cass` | 统一的代理历史搜索功能 |\n| 6 | **CASS 内存系统** | `cm` | 为代理提供程序化记忆功能 |\n| 7 | **编程代理账户管理器** | `caam` | 代理身份验证切换功能 |\n| 8 | **同时启动按钮** | `slb` | 为危险命令设置两人规则 |\n| 9 | **破坏性命令防护器** | `dcg` | 阻止 Claude Code 中危险的 Git\u002F文件操作指令 |\n| 10 | **仓库更新器** | `ru` | 多仓库同步 + AI 驱动的提交自动化功能 |\n\n### 扩展工具\n\n在堆栈之外额外安装的生产力工具：\n\n| 工具 | 命令 | 说明 |\n|------|---------|-------------|\n| **从互联网链接获取图片** | `giil` | 从 iCloud、Dropbox、Google Photos 下载图片，用于可视化调试 |\n| **将聊天对话分享至文件** | `csctf` | 将 AI 分享链接（如 ChatGPT、Gemini、Claude）转换为 Markdown\u002FHTML 格式 |\n\n---\n\n## 医生命令\n\n`acfs doctor` 会对您的安装进行全面的健康检查：\n\n```bash\n$ acfs doctor\n\n╔══════════════════════════════════════════════════════════════╗\n║ ACFS 健康检查 ║\n╠══════════════════════════════════════════════════════════════╣\n║ 身份信息 ║\n║ ✔ 以 ubuntu 用户身份运行 ║\n║ ✔ 已启用无密码 sudo ║\n║ ║\n║ 工作区 ║\n║ ✔ \u002Fdata\u002Fprojects 存在 ║\n║ ║\n║ Shell ║\n║ ✔ 安装了 zsh ║\n║ ✔ 安装了 oh-my-zsh ║\n║ ✔ 安装了 powerlevel10k ║\n║ ✔ 从 acfs.zshrc 获取配置 ║\n║ ║\n║ 核心工具 ║\n║ ✔ bun 1.2.16 ║\n║ ✔ uv 0.5.14 ║\n║ ✔ cargo 1.84.0 ║\n║ ✔ go 1.23.4 ║\n║ ✔ ripgrep 14.1.0 ║\n║ ✔ ast-grep 0.30.1 ║\n║ ║\n║ 代理 ║\n║ ✔ claude 1.0.24 ║\n║ ✔ codex 0.1.2504252326 ║\n║ ✔ gemini 0.1.12 ║\n║ ║\n║ 云服务 ║\n║ ✔ vault 1.18.3 ║\n║ ✔ wrangler 4.16.0 ║\n║ ✔ supabase 2.23.4 ║\n║ ✔ vercel 41.7.6 ║\n║ ║\n║ 迪克尔斯沃斯堆栈 ║\n║ ✔ ntm 0.3.2 ║\n║ ✔ slb 0.2.1 ║\n║ ✔ ubs 0.1.8 ║\n║ ✔ bv 0.9.4 ║\n║ ✔ cass 0.4.2 ║\n║ ✔ cm 0.1.3 ║\n║ ✔ caam 0.2.0 ║\n║ ✔ dcg 0.1.0 ║\n║ ✔ ru 1.2.0 ║\n║ ⚠ mcp_agent_mail（未运行） ║\n║ ║\n║ 实用工具 ║\n║ ✔ giil 3.0.0 ║\n║ ✔ csctf 1.0.0 ║\n╠══════════════════════════════════════════════════════════════╣\n║ 总体：35\u002F36 项检查通过 ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n### 生成的医生检查\n\n医生检查由清单文件（`scripts\u002Fgenerated\u002Fdoctor_checks.sh`）生成，以确保验证逻辑与 `acfs.manifest.yaml` 紧密衔接。`acfs doctor` 命令会自动加载这些生成的检查，以验证所有清单中定义的工具。\n\n**工作原理：**\n1. 清单生成器会为每个模块创建 `doctor_checks.sh` 文件，并附带相应的验证命令。\n2. `acfs doctor` 会加载该文件并运行每项验证检查。\n3. 对于失败的检查，系统会显示一条 **修复建议**，并提供具体的重新安装命令。\n\n**示例输出，附带修复建议：**\n```\n ✗ tools.lazygit - 未找到 Lazygit 终端界面\n 修复方法：acfs install --only tools.lazygit\n```\n\n这种架构确保医生检查与安装程序保持同步——只要工具已纳入清单，就会被逐一验证。\n\n### 选项\n\n```bash\nacfs doctor # 交互式彩色输出\nacfs doctor --json # 机器可读的 JSON 输出\nacfs doctor --quiet # 仅输出退出码（0 表示健康，1 表示存在问题）\nacfs doctor --deep # 运行功能测试（认证、连接）\nacfs doctor --fix # 对失败的检查应用安全修复方案\nacfs doctor --dry-run # 预览修复方案，无需实际执行\nacfs doctor --no-cache # 跳过缓存，重新运行所有检查\n```\n\n### 深度检查 (`--deep`)\n\n`--deep` 标志会运行超出二进制文件本身范围的功能测试：\n\n| 类别 | 检查内容 |\n|------|--------|\n| **代理认证** | Claude 配置、Codex OAuth、Gemini 凭证 |\n| **数据库** | PostgreSQL 连接、ubuntu 角色已存在 |\n| **云 CLI** | `gh auth status`、`wrangler whoami`、Supabase\u002FVercel 令牌 |\n| **Vault** | 已配置 `VAULT_ADDR` |\n\n深度检查采用 5 秒超时机制，以避免因网络问题导致卡顿。结果会缓存 5 分钟，以便加快重复运行的速度。\n\n示例输出：\n```\n深度检查\n ✔ Claude 认证已配置\n ✔ PostgreSQL 连接正常工作\n ⚠ Codex 未完成认证（需运行：codex login）\n ✔ GitHub CLI 已认证\n\n8\u002F9 项功能测试在 3.2 秒内通过\n```\n\n### 自动修复模式 (`--fix`)\n\n`--fix` 标志会自动为常见问题应用安全、确定性的修复措施：\n\n```bash\nacfs doctor --fix # 应用安全修复\nacfs doctor --fix --dry-run # 预览修复效果，无需实际执行\n```\n\n#### 安全的自动修复工具\n\n当使用 `--fix` 时，这些修复操作将自动执行：\n\n| 修复 ID | 说明 | 撤销策略 |\n|--------|-------|---------------|\n| `fix.path.ordering` | 将 ACFS 目录前置至 `.zshrc` 中的 PATH 环境变量 | 恢复备份 |\n| `fix.config.copy` | 复制缺失的 ~\u002F.acfs 配置文件 | 删除已复制的文件 |\n| `fix.dcg.hook` | 安装 DCG 使用前的预处理钩子 | 运行 `dcg uninstall` |\n| `fix.symlink.create` | 创建缺失的工具符号链接 | 删除符号链接 |\n| `fix.plugin.clone` | 克隆缺失的 zsh 插件 | 删除已克隆的目录 |\n| `fix.acfs.sourcing` | 将 ACFS 源代码添加至 `.zshrc` | 恢复备份 |\n\n#### 安全性保障\n\n- **绝不会删除用户文件** — 只会创建、修改或创建符号链接\n- **在修改前进行备份** — 对所有已修改的文件进行 SHA256 校验的备份\n- **幂等性** — 多次运行此命令均安全无虞\n- **记录日志** — 所有变更都会被记录到 `~\u002F.local\u002Fshare\u002Facfs\u002Fdoctor.log`\n- **可逆性** — 每一项修复都附带撤销命令\n\n#### 示例 Dry-Run 输出\n\n```\nDRY-RUN: acfs doctor --fix\n\n将应用以下修复措施：\n\n [fix.path.ordering]\n 操作：将 PATH 目录前置至 ~\u002F.zshrc\n 文件：~\u002F.zshrc\n 备份：是（已通过 SHA256 校验）\n\n [fix.acfs.sourcing]\n 操作：将 ACFS 源代码添加至 .zshrc\n 文件：~\u002F.zshrc\n 备份：是（已通过 SHA256 校验）\n\n需要手动操作的修复：\n [shell.ohmyzsh]\n 状态：失败\n 建议：curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fohmyzsh\u002Fohmyzsh\u002Fmaster\u002Ftools\u002Finstall.sh | bash\n\n总结：2 项自动修复，0 项提示，1 项需手动操作\n```\n\n#### 仅需手动操作的修复\n\n有些操作并不会自动修复，而是提供相关建议：\n\n- 包管理器操作（如 `apt install ...`）\n- 需要 sudo 权限的操作\n- 文件删除操作\n- 复杂的 shell 配置更改\n\n#### 撤销变更\n\n`--fix` 执行的所有变更均可撤销：\n\n```bash\nacfs undo --list # 列出所有变更\nacfs undo chg_0001 # 撤销特定变更\nacfs undo --all # 撤销上一会话中的所有变更\n```\n\n---\n\n## 向导网站\n\n向导会引导初学者完成一个**13 步旅程**，从“我有一台笔记本电脑”到“AI 代理正在为我编写代码”：\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ ACFS 向导 [第 3 步\u002F13] │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌────────────────────────────────────────────────────────────────────────┐ │\n│ │ 第 3 步：生成 SSH 密钥 │ │\n│ │ ────────────────────────────────────────────────────────────────── │ │\n│ │ │ │\n│ │ 在终端中运行此命令： │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │\n│ │ │ ssh-keygen -t ed25519 -C \"your-email@example.com\" [📋] │ │ │\n│ │ └─────────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ │ ☐ 我已运行此命令 │ │\n│ │ │ │\n│ │ [← 上一步] [下一步 →] │ │\n│ └────────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ 进度：●●●○○○○○○○○○○ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 向导步骤\n\n| 步骤 | 标题 | 发生了什么 |\n|------|-------|--------------|\n| 1 | **选择您的操作系统** | 选择 Mac、Windows 或 Linux（自动检测） |\n| 2 | **安装终端** | 设置一款合适的终端应用程序 |\n| 3 | **生成 SSH 密钥** | 为 VPS 访问创建 ed25519 密钥 |\n| 4 | **租用 VPS** | 选择 VPS 提供商并制定计划 |\n| 5 | **创建 VPS 实例** | 启动您的 VPS 并确认 SSH 访问权限 |\n| 6 | **SSH 登录 VPS** | 第一次连接，并获取故障排除技巧 |\n| 7 | **设置账户** | 为即将使用的各项服务创建账户 |\n| 8 | **飞行前检查** | 在安装前验证您的 VPS 是否已就绪 |\n| 9 | **运行安装程序** | 使用 `curl \\| bash` 的单行命令 |\n| 10 | **以 Ubuntu 身份重新连接** | 安装后重新连接 |\n| 11 | **验证密钥连接** | 使用您的 SSH 密钥重新连接，并确认其正常工作 |\n| 12 | **状态检查** | 运行 `acfs doctor` 进行验证 |\n| 13 | **启动入门教程** | 开始交互式教程 |\n\n### 关键功能\n\n- **操作系统检测**：自动识别 Mac 和 Windows，提供针对性的指导方案\n- **一键复制**：一键复制所有命令\n- **进度追踪**：在浏览器会话间持久化存储数据\n- **确认复选框**：对“我已运行此命令”的操作进行确认\n- **故障排除**：针对常见问题提供扩展式帮助\n\n### 技术栈\n\n```\nNext.js 16（App Router）\n├── React 19\n├── Tailwind CSS 4（OKLCH 颜色）\n├── shadcn\u002Fui 组件\n├── Radix UI 原生组件\n└── Lucide 图标\n```\n\n**无需后端支持。** 所有状态均存储于：\n- URL 查询参数\n- localStorage（`agent-flywheel-user-os`、`agent-flywheel-vps-ip`、`agent-flywheel-wizard-completed-steps`）\n\n### 向导状态管理\n\n向导采用 **TanStack Query** 进行状态管理，支持乐观更新与跨表格同步：\n\n**架构：**\n```typescript\n\u002F\u002F 基于查询的状态管理，结合 localStorage 持久化\nconst { data: steps } = useQuery({\n queryKey: ['wizardSteps', 'completed'],\n queryFn: getCompletedSteps, \u002F\u002F 从 localStorage 中读取数据\n staleTime: 0, \u002F\u002F 始终检查是否有更新\n gcTime: Infinity, \u002F\u002F 从不进行垃圾回收\n});\n```\n\n**乐观更新与回滚机制：**\n```typescript\nconst mutation = useMutation({\n mutationFn: async (stepId) => {\n const newSteps = addCompletedStep(currentSteps, stepId);\n setCompletedSteps(newSteps); \u002F\u002F 将更新持久化至 localStorage\n return newSteps;\n },\n onMutate: (stepId) => {\n \u002F\u002F 立即对缓存进行乐观更新\n const previousSteps = queryClient.getQueryData(queryKey);\n queryClient.setQueryData(queryKey, addCompletedStep(baseSteps, stepId));\n return { previousSteps }; \u002F\u002F 用于回滚\n },\n onError: (_err, _stepId, context) => {\n \u002F\u002F 失败时执行回滚操作\n queryClient.setQueryData(queryKey, context.previousSteps);\n },\n});\n```\n\n**跨表格同步：**\n向导通过两种机制实现浏览器标签页间的同步：\n1. **自定义 DOM 事件**，用于在组件间实现同标签页的协调。\n2. **存储事件**，当 localStorage 发生变化时触发跨标签页的更新。\n\n```typescript\n\u002F\u002F 同标签页：自定义事件分发\nwindow.dispatchEvent(new CustomEvent('acfs:wizard:completed-steps-changed', {\n detail: { steps }\n}));\n\n\u002F\u002F 跨标签页：存储事件监听器\nwindow.addEventListener('storage', (event) => {\n if (event.key === COMPLETED_STEPS_KEY) {\n queryClient.setQueryData(queryKey, getCompletedSteps());\n }\n});\n```\n\n**安全的 localStorage 工具：**\n所有对 localStorage 的访问都经过安全工具的封装，以应对 SSR、隐私浏览以及配额超限等异常情况：\n\n```typescript\n\u002F\u002F 安全读取（任何错误都会返回 null）\nexport function safeGetJSON\u003CT>(key: string): T | null;\n\n\u002F\u002F 安全写入（返回布尔值成功）\nexport function safeSetJSON(key: string, value: unknown): boolean;\n\n\u002F\u002F URL 保留，用于状态回退\nexport function withCurrentSearch(path: string): string;\n```\n\n该架构确保了向导进度能够持续保存，即使浏览器刷新，也能在不同标签页间正常运行，并在 localStorage 无法使用时优雅地降级。\n\n---\n\n## 配置文件\n\nACFS 会将优化后的配置文件部署到目标 VPS 的 `~\u002F.acfs\u002F` 目录中。\n\n### `~\u002F.acfs\u002Fzsh\u002Facfs.zshrc`\n\n一个全面的 zsh 配置文件，由 `~\u002F.zshrc` 源文件加载：\n\n**Oh-My-Zsh 插件（共 14 个）：**\n\n| 插件 | 类别 | 提供的功能 |\n|------------|----------|----------------------------------|\n| `git` | VCS | 150 多个 git 别名（gs、gp、gl、gco、gcm 等） |\n| `sudo` | Shell | 双击 Esc 键，即可在前一个命令前添加 sudo 前缀 |\n| `colored-man-pages` | Shell | 为阅读体验提供彩色的 man 页面 |\n| `command-not-found` | Shell | 当命令未找到时，可提示相关软件包 |\n| `docker` | Containers | Docker 命令补全及别名 |\n| `docker-compose` | Containers | docker-compose 命令补全及别名 |\n| `python` | Lang | Python 别名（pyfind、pyclean、pygrep） |\n| `pip` | Lang | pip 命令补全及缓存管理 |\n| `tmux` | Terminal | tmux 别名（ta、tad、ts、tl、tkss） |\n| `tmuxinator` | Terminal | tmuxinator 项目补全 |\n| `systemd` | System | systemctl 别名（sc-status、sc-start、sc-stop） |\n| `rsync` | Tools | rsync 命令补全及常用参数别名 |\n| `zsh-autosuggestions` | UX | 仿 Fish 风格的历史自动建议 |\n| `zsh-syntax-highlighting` | UX | 实时命令语法高亮 |\n\n> **注意**：`zsh-autosuggestions` 和 `zsh-syntax-highlighting` 是从 GitHub 安装的自定义插件。为了获得最佳性能，它们必须排在最后。\n\n**路径配置：**\n```bash\nexport PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.cargo\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002Fgo\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.bun\u002Fbin:$PATH\"\nexport PATH=\"$HOME\u002F.atuin\u002Fbin:$PATH\"\n```\n\n**现代 CLI 别名：**\n```bash\nalias ls='lsd --inode --long --all'\nalias ll='lsd -l'\nalias tree='lsd --tree'\nalias cat='bat'\nalias grep='rg'\nalias vim='nvim'\nalias lg='lazygit'\n```\n\n**工具集成：**\n```bash\n# Atuin（更优秀的 shell 历史记录）\neval \"$(atuin init zsh)\"\n\n# Zoxide（更智能的 cd 命令）\neval \"$(zoxide init zsh)\"\n\n# direnv（目录环境变量）\neval \"$(direnv hook zsh)\"\n\n# fzf（模糊查找工具）\nsource \u002Fusr\u002Fshare\u002Fdoc\u002Ffzf\u002Fexamples\u002Fkey-bindings.zsh\n```\n\n**Shell 键绑定（提升生活质量）：**\n\n| 键绑定 | 操作 | 注意事项 |\n|---------|--------|-------|\n| `Ctrl+→` | 向前跳转一个单词 | 通过单词进行导航 |\n| `Ctrl+←` | 向后跳转一个单词 | 通过单词进行导航 |\n| `Alt+→` | 向前跳转一个单词 | 替代绑定 |\n| `Alt+←` | 向后跳转一个单词 | 替代绑定 |\n| `Ctrl+Backspace` | 向后删除一个单词 | 快速删除 |\n| `Ctrl+Delete` | 向前删除一个单词 | 快速删除 |\n| `Home` | 行首 | 在所有终端中均有效 |\n| `End` | 行尾 | 在所有终端中均有效 |\n| `Ctrl+R` | Atuin 历史搜索 | 交互式模糊搜索 |\n\n**Atuin 历史绑定：**\n该配置强制 Atuin 的绑定在最后加载（在 OMZ 插件之后），确保 `Ctrl+R` 能触发 Atuin 的模糊历史搜索，而非 zsh 的默认行为：\n\n```bash\n# 强制置于 zshrc 结尾\nbindkey -e # Emacs 模式\nbindkey -M emacs '^R' atuin-search\nbindkey -M viins '^R' atuin-search-viins\nbindkey -M vicmd '^R' atuin-search-vicmd\n```\n\n### `~\u002F.acfs\u002Ftmux\u002Ftmux.conf`\n\n一款专为 NTM 和多代理工作流优化的 tmux 配置文件：\n\n**键绑定：**\n```\n前缀：Ctrl+a（不是 Ctrl+b——更符合人体工学）\n水平分割：| （保留工作目录）\n垂直分割：- （保留工作目录）\n导航窗格：h\u002Fj\u002Fk\u002Fl（vim 风格）\n调整窗格大小：H\u002FJ\u002FK\u002FL（可通过 -r 标志重复调整）\n重新加载配置：r\n新建窗口：c（保留工作目录）\n```\n\n**复制模式（vim 风格）：**\n```\n进入复制模式：前缀 + [\n开始选择：v\n矩形选择：r\n复制并退出：y\n```\n\n**代理工作流优化：**\n\n| 设置 | 值 | 用途 |\n|--------------|-------------|----------------|\n| `history-limit` | 50,000 | 为长时间代理会话扩展滚动回溯时间 |\n| `escape-time` | 10ms | 提升按键响应速度（从默认的 500ms 降低） |\n| `focus-events` | on | 在代理窗口中启用 vim\u002Fneovim 自动读取 |\n| `detach-on-destroy` | off | 与 NTM 兼容——在会话结束时不要断开连接 |\n| `monitor-activity` | on | 记录代理窗口的活动 |\n| `visual-activity` | off | 静默监控（无铃声） |\n\n**Catppuccin 风格主题：**\n```bash\n# 状态栏（位于顶部，更不突兀）\nstatus-style: bg=#1e1e2e, fg=#cdd6f4\n\n# 会话指示器（蓝色点缀）\nstatus-left: #[fg=#89b4fa,bold] #S\n\n# 活跃窗口高亮（粉色点缀）\nwindow-status-current-format: #[fg=#f5c2e7,bold] #I:#W\n\n# 面包边框\n面包边框样式：fg=#313244\n面包激活边框样式：fg=#89b4fa # 蓝色高亮\n```\n\n**本地覆盖：**\n如果存在 `~\u002F.tmux.conf.local` 配置文件，将自动加载该文件，从而在不修改 ACFS 默认配置的前提下，实现个人化自定义。\n\n---\n\n## 库模块\n\n安装程序被组织成模块化的 Bash 库，位于 `scripts\u002Flib\u002F` 目录下：\n\n### `logging.sh`\n\n用于彩色控制台输出的实用工具：\n\n```bash\nlog_step \"1\u002F8\" \"正在安装软件包...\" # 蓝色步骤指示器\nlog_detail \"正在安装 zsh...\" # 灰色缩进式详细信息\nlog_success \"安装完成\" # 绿色对勾\nlog_warn \"可能需要一些时间\" # 黄色警告\nlog_error \"安装失败\" # 红色错误\nlog_fatal \"无法继续\" # 红色错误 + 退出 1\n```\n\n### `security.sh`\n\n用于 HTTPS 执行与校验和验证：\n\n```bash\nenforce_https \"$url\" # 如果不是 HTTPS，则失败\nverify_checksum \"$url\" \"$sha256\" \"$name\" # 在执行前进行校验\nfetch_and_run \"$url\" \"$sha256\" \"$name\" # 一次性完成校验与执行\n```\n\n### `os_detect.sh`\n\n用于操作系统检测与验证：\n\n```bash\ndetect_os() # 设置 OS_ID、OS_VERSION、OS_CODENAME\nvalidate_os() # 检查是否为 Ubuntu 25.10（或升级路径）\nis_fresh_vps() # 基于启发式算法检测 VPS 是否为最新版本\nget_arch() # 返回 amd64\u002Farm64 架构\nis_wsl() # 检测 WSL\nis_docker() # 检测 Docker 容器\n```\n\n### `user.sh`\n\n用于用户账户的标准化处理：\n\n```bash\nensure_user() # 如果用户不存在，则创建 ubuntu 用户\nenable_passwordless_sudo() # 向 sudoers 添加 NOPASSWD 权限\nmigrate_ssh_keys() # 将密钥从 root 用户复制到 ubuntu 用户\nnormalize_user() # 完整的标准化流程\n```\n\n### `update.sh`\n\n组件更新逻辑，支持版本追踪与日志记录：\n\n```bash\nupdate_apt() # 使用 apt 更新\u002F升级，并添加锁定检测\nupdate_bun() # 使用 bun 进行版本追踪的升级\nupdate_agents() # 对 Claude、Codex、Gemini 等工具进行版本更新\nupdate_cloud() # 对 Wrangler、Supabase、Vercel 等工具进行更新（Supabase 使用经过验证的发布包）\nupdate_rust() # 使用 rustup 更新稳定版\nupdate_uv() # 自我更新 uv\nupdate_go() # 更新 Go 工具链\nupdate_shell() # 更新 OMZ、P10K、插件、Atuin、Zoxide 等工具\nupdate_stack() # 更新 Dicklesworthstone 的各类工具\n\n# 功能：\n# - 自动将日志记录到 ~\u002F.acfs\u002Flogs\u002Fupdates\u002F\n# - 版本追踪（每项工具的前后版本均会记录）\n# - apt 锁定检测与预警\n# - 内核更新需重启检测\n# - 提供 --dry-run 标志的干运行模式\n```\n\n### `gum_ui.sh`\n\n使用 Charmbracelet Gum 实现增强型终端界面：\n\n```bash\nprint_banner() # ASCII 章节式 ACFS 纪念标语\ngum_step\u002Fgum_detail # 样式化输出\ngum_success\u002Fwarn\u002Ferror # 多色提示信息\ngum_spin # 长时间操作时的旋转进度条\ngum_confirm # 是\u002F否提示\ngum_choose # 选择菜单\n```\n\n若未安装 Gum，则回退至基本的 `echo` 输出方式。\n\n### `error_tracking.sh`\n\n用于高级错误收集与报告：\n\n```bash\ntrack_error \"阶段\" \"步骤\" \"错误信息\"\ntrack_warning \"阶段\" \"步骤\" \"警告信息\"\nget_error_report # 生成结构化的错误报告\nget_error_count # 统计已跟踪的错误数量\nhas_errors # 判断是否存在任何错误\n```\n\n功能：\n- 在不中断执行的情况下收集错误\n- 将错误与阶段、步骤上下文关联起来\n- 生成运行结束后的汇总报告\n- 区分警告与错误\n\n### `state.sh`\n\n用于管理安装进度的状态机（v3 规范）：\n\n```bash\nstate_init # 初始化状态文件\nstate_get_phase # 当前阶段\nstate_set_phase \"阶段名称\" # 设置当前阶段\nstate_mark_complete \"阶段名称\" # 标记阶段已完成\nstate_has_completed \"阶段名称\" # 检查阶段是否已完成\nstate_save # 将状态持久化到磁盘（原子操作）\nstate_load # 从磁盘加载状态\n```\n\n状态文件（`~\u002F.acfs\u002Fstate.json`）采用原子写入机制，以防止数据损坏。\n\n### `contract.sh`\n\n用于生成脚本的运行时合约验证：\n\n```bash\nacfs_require_contract \"模块 ID\" # 确保环境已就绪\nacfs_check_contract # 非致命的合约检查\n```\n\n在执行前验证所需环境变量与函数是否已存在：\n- `TARGET_USER`、`TARGET_HOME`、`MODE`\n- `ACFS_BOOTSTRAP_DIR`、`ACFS_LIB_DIR`\n- 日志记录相关函数：`log_detail`、`log_success` 等。\n\n### `smoke_test.sh`\n\n安装后自动运行的验证测试：\n\n```bash\nrun_smoke_test # 执行所有冒烟测试\n```\n\n**关键检查**（必须通过）：\n- 以 ubuntu 用户身份运行\n- 启用无密码 sudo\n- zsh 作为默认 shell\n- 确保核心工具可用（bun、uv、cargo）\n\n**非关键检查**（仅显示警告）：\n- 已配置代理认证\n- 已通过云 CLI 认证\n- 可选工具已安装\n\n示例输出：\n```\n[冒烟测试]\n ✅ 以 ubuntu 用户身份运行\n ✅ 启用无密码 sudo\n ✅ zsh 作为默认 shell\n ✅ bun --version 有效\n ⚠️ Codex 未认证（需运行：codex login）\n ✅ 8\u002F9 项检查通过\n```\n\n### `session.sh`\n\n用于代理会话导出功能，便于共享与回放：\n\n```bash\nsession_export \"claude-code\" \"会话 ID\" \"\u002F输出路径\"\nsession_list # 列出可导出的会话\nsession_validate \"\u002F导出文件.json\"\n```\n\n实现了 **会话导出 Schema**，支持跨代理共享：\n\n```typescript\ninterface SessionExport {\n schema_version: 1;\n exported_at: string; \u002F\u002F ISO8601 格式\n session_id: string;\n agent: \"claude-code\" | \"codex\" | \"gemini\";\n model: string;\n summary: string;\n duration_minutes: number;\n stats: {\n turns: number;\n files_created: number;\n files_modified: number;\n commands_run: number;\n };\n outcomes: Array\u003C{\n type: \"file_created\" | \"file_modified\" | \"command_run\";\n path?: string;\n description: string;\n }>;\n key_prompts: string[]; \u002F\u002F 学习过程中重要的提示词\n sanitized_transcript: Array\u003C{ role: \"用户\" | \"助手\"; content: string; timestamp: string }>;\n}\n```\n\n### `tailscale.sh`\n\n用于零配置 VPN 设置，实现安全的远程访问：\n\n```bash\ninstall_tailscale # 通过官方 APT 仓库安装\nverify_tailscale # 检查安装是否成功\ntailscale_status # 获取连接状态\n```\n\nTailscale 提供以下功能：\n- 设备间的 **安全网格网络**\n- 通过 Tailscale 运行 SSH，实现无防火墙访问\n- 采用 **MagicDNS** 实现基于主机名的地址解析\n- 支持 **ACL 权限控制**\n\n安装完成后，运行 `tailscale up` 以完成认证并加入你的 Tailnet。\n\n### `ubuntu_upgrade.sh`\n\n多重启 Ubuntu 版本升级自动化：\n\n```bash\nstart_ubuntu_upgrade # 开始升级链\ncheck_upgrade_status # 检查当前升级状态\nresume_upgrade_after_reboot # 重启后继续升级\n```\n\n负责处理复杂且多步骤的 Ubuntu 升级流程：\n1. 检测当前版本\n2. 计算升级路径（例如：24.04 → 25.04 → 25.10）\n3. 依次执行 `do-release-upgrade` 操作\n4. 安装 systemd 服务，用于重启后恢复升级\n5. 在达到目标版本后，继续完成 ACFS 的安装过程\n\n---\n\n## MCP 代理邮件集成\n\nACFS 集成了 **MCP 代理邮件** 功能，实现多代理协同工作：\n\n### 代理邮件的功能\n\n- **身份标识**：每个代理都会使用唯一的名称进行注册\n- **收件箱\u002F发件箱**：基于消息的代理间通信\n- **文件预留**：通过文件预留机制，防止代理之间互相覆盖或冲突的工作内容\n- **可搜索的线程**：支持对所有消息进行全文检索\n- **Git 持久化**：将所有工件存储在 Git 中，便于人工审计\n\n### 核心模式\n\n**1. 注册身份**\n```bash\n# 在您的代理中调用：\nmcp.ensure_project(project_key=\"\u002Fdata\u002Fprojects\u002Fmy-project\")\nmcp.register_agent(project_key=..., program=\"claude-code\", model=\"opus-4.5\")\n```\n\n**2. 在编辑前预留文件**\n```bash\nmcp.file_reservation_paths(\n project_key=...,\n agent_name=\"BlueLake\",\n paths=[\"src\u002F**\"],\n ttl_seconds=3600,\n exclusive=true\n)\n```\n\n**3. 通信与协作**\n```bash\nmcp.send_message(\n project_key=...,\n sender_name=\"BlueLake\",\n to=[\"GreenCastle\"],\n subject=\"需审核\",\n body_md=\"请审阅权限变更...\"\n)\n```\n\n### 提升效率的宏操作\n\n当效率比精细控制更为重要时：\n\n```bash\nmcp.macro_start_session(...) # 确保项目、注册及收件箱的同步\nmcp.macro_prepare_thread(...) # 与现有线程保持一致\nmcp.macro_file_reservation_cycle(...) # 进行预留、工作与释放\nmcp.macro_contact_handshake(...) # 请求联系权限\n```\n\n---\n\n## 毁灭性命令防护器 (dcg)\n\n**dcg** 是一款高性能的 Claude Code 插件，能够在危险的 Git 和文件系统命令执行前对其进行拦截。该插件采用 Rust 编写，延迟低至亚毫秒级，能够以机械化的手段严格执行安全规则——而这些规则仅靠指令本身往往难以完全保障。\n\n### 为什么需要 dcg\n\n2025年12月17日，一名 AI 代理在并行编码会话中，对包含数小时未提交工作的文件执行了 `git checkout --` 命令。尽管这些文件通过 `git fsck --lost-found` 被成功恢复，但这次事件却清晰地表明：《AGENTS.md》中的指令并不能有效阻止命令的执行。**dcg 提供了机械化的安全保障**。\n\n### 可被拦截的命令类型\n\n| 类别 | 命令 |\n|------------|----------------|\n| **Git 重置** | `git reset --hard`、`git reset --merge` |\n| **文件丢弃** | `git checkout -- \u003Cfiles>`、`git restore \u003Cfiles>` |\n| **强制推送** | `git push --force` \u002F `-f`（允许使用 `--force-with-lease`） |\n| **清理** | `git clean -f`（支持 `-n` 试运行） |\n| **分支删除** | `git branch -D`（支持 `-d`） |\n| **stash 失效** | `git stash drop`、`git stash clear` |\n| **文件系统** | `rm -rf`（除临时目录外） |\n\n### 可被允许的命令\n\n安全变体已被列入白名单：\n- `git checkout -b \u003Cbranch>` — 创建新分支，不修改文件内容\n- `git restore --staged` — 仅取消暂存，不进行丢弃\n- `git clean -n` — 仅预览操作，无需实际执行\n- `rm -rf \u002Ftmp\u002F...` — 临时目录为短暂存在\n\n### 安装方法\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fdestructive_command_guard\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n### Claude Code 配置\n\n在 `~\u002F.claude\u002Fsettings.json` 中添加以下配置：\n\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [{\"type\": \"command\", \"command\": \"dcg\"}]\n }\n ]\n }\n}\n```\n\n### 模块化包系统\n\ndcg 采用模块化包系统，支持扩展功能。您可以在 `~\u002F.config\u002Fdcg\u002Fconfig.toml` 中启用更多包：\n\n```toml\n[packs]\nenabled = [\n \"database.postgresql\",\n \"containers.docker\",\n \"kubernetes\",\n]\n```\n\n可用包包括：`database.*`、`containers.*`、`kubernetes.*`、`cloud.*`、`infrastructure.*`、`system.*`、`package_managers`。\n\n---\n\n## 仓库更新器 (ru)\n\n**ru** 是一款生产级 CLI 工具，用于同步 GitHub 仓库集合，并借助 AI 助手自动完成脏仓库的提交工作流。\n\n### 核心功能\n\n- **多仓库同步**：克隆缺失的仓库，拉取更新，检测冲突\n- **代理扫面**：通过 AI 驱动的提交自动化，针对存在未提交更改的仓库进行操作\n- **AI 代码审查**：为开放问题\u002FPR 组织 Claude Code 审查会话\n- **工作窃取队列**：通过负载均衡的 Worker 实现并行执行\n- **NTM 集成**：通过 Named Tmux Manager 管理会话\n\n### 快速入门\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Frepo_updater\u002Fmain\u002Finstall.sh?ru_cb=$(date +%s)\" | bash\n```\n\n初始化配置：\n\n```bash\n# 初始化配置\nru init --example\n\n# 同步所有仓库\nru sync\n\n# 检查状态，无需任何更改\nru status\n```\n\n### 代理扫面工作流\n\n`agent-sweep` 命令可自动化处理脏仓库中的提交：\n\n```bash\n# 预览待处理的仓库\nru agent-sweep --dry-run\n\n# 全面自动化，结合 AI 助力\nru agent-sweep --parallel 4\n\n# 包含发布自动化\nru agent-sweep --with-release\n```\n\n**三阶段工作流：**\n1. **规划**：Claude Code 分析变更，生成提交信息\n2. **提交**：验证计划，对文件进行暂存，运行质量门限\n3. **发布**：（可选）创建版本标签，并发布到 GitHub\n\n### 配置说明\n\n```bash\n# ~\u002F.config\u002Fru\u002Fconfig\nPROJECTS_DIR=\u002Fdata\u002Fprojects\nLAYOUT=flat # flat|owner-repo|full\nUPDATE_STRATEGY=ff-only # ff-only|rebase|merge\nPARALLEL=4\n```\n\n**仓库列表格式**（`~\u002F.config\u002Fru\u002Frepos.d\u002Fpublic.txt`）：\n```\nowner\u002Frepo\nowner\u002Frepo@develop # 保留到分支\nowner\u002Frepo as custom-name # 自定义目录名\n```\n\n---\n\n## 从网络链接获取图片 (giil)\n\n**giil** 会从云端照片共享平台下载全分辨率图片至终端。对于需要在 SSH 会话中分析截图的远程调试工作流而言，这是一款不可或缺的工具。\n\n### 支持平台\n\n| 平台 | 方法 | 速度 |\n|------------|----------|--------|\n| **iCloud** | 四层抓取策略 | 5–15 秒 |\n| **Dropbox** | 直接通过 curl 下载 | 1–2 秒 |\n| **Google Photos** | 网络拦截 | 5–15 秒 |\n| **Google Drive** | 多层认证 + 授权检测 | 5–15 秒 |\n\n### 使用方法\n\n```bash\n# 基础下载\ngiil \"https:\u002F\u002Fshare.icloud.com\u002Fphotos\u002F02cD9okNHvVd-uuDnPCH3ZEEA\"\n# 输出：\u002Fcurrent\u002Fdir\u002Ficloud_20240115_143245.jpg\n\n# 下载至特定目录\ngiil \"...\" --output ~\u002FDownloads\n\n# 获取 JSON 元数据\ngiil \"...\" --json\n\n# 下载相册中的全部照片\ngiil \"...\" --all --output ~\u002Falbum\n```\n\n### 安装方法\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fgiil\u002Fmain\u002Finstall.sh?v=3.0.0\" | bash\n```\n\n### 可视化调试工作流程\n\n1. 在 iPhone 上截取 UI 错误的截图\n2. 等待 iCloud 同步至 Mac\n3. 通过 Photos.app 共享截图 → 复制 iCloud 链接\n4. 将链接粘贴到运行 Claude Code 的远程终端中\n5. `giil` 会将图片本地获取\n6. AI 助手对截图进行分析\n\n---\n\n## 聊天共享对话转为文件（csctf）\n\n**csctf** 可将公开的 AI 对话共享链接转换为整洁、可搜索的 Markdown 和 HTML 文本。非常适合用于归档 AI 对话、构建知识库，以及与团队分享。\n\n### 支持的提供商\n\n| 提供商 | URL 模式 |\n|----------|------------|\n| **ChatGPT** | `chatgpt.com\u002Fshare\u002F*` |\n| **Gemini** | `gemini.google.com\u002Fshare\u002F*` |\n| **Grok** | `grok.com\u002Fshare\u002F*` |\n| **Claude** | `claude.ai\u002Fshare\u002F*` |\n\n### 使用方法\n\n```bash\n# 基础转换\ncsctf https:\u002F\u002Fchatgpt.com\u002Fshare\u002F69343092-91ac-800b-996c-7552461b9b70\n# 生成：\u003Cslug>.md 和 \u003Cslug>.html\n\n# 仅生成 Markdown\ncsctf \"...\" --md-only\n\n# 发布至 GitHub Pages\ncsctf \"...\" --publish-to-gh-pages --yes\n\n# JSON 元数据输出\ncsctf \"...\" --json\n```\n\n### 安装\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fchat_shared_conversation_to_file\u002Fmain\u002Finstall.sh | bash\n```\n\n### 输出功能\n\n- **Markdown**：采用整洁的格式，保留代码块和语言提示。\n- **HTML**：无 JavaScript 的静态页面，支持语法高亮。\n- **确定性文件名**：使用 `\u003Cslug>_YYYYMMDD.md`，确保归档的可靠性。\n- **冲突处理**：自动递增后缀，避免覆盖。\n\n---\n\n## CI\u002FCD\n\nACFS 采用 GitHub Actions 进行持续集成：\n\n### 安装程序测试 (`installer.yml`)\n\n```yaml\n# 每次推送和 PR 都会运行\njobs:\n shellcheck:\n - 使用 ShellCheck 对所有 Bash 脚本进行 lint 检查\n\n integration:\n - 在 Ubuntu 24.04、25.04、25.10 上运行矩阵测试\n - 在 Docker 中完成完整安装\n - 验证所有工具是否正确安装\n - 运行 acfs doctor，确认系统健康状态\n\n这确保了安装程序可在所有受支持的 Ubuntu 版本上正常运行，并及早发现 Shell 脚本中的问题。\n\n### 网站部署 (`website.yml`)\n\n```yaml\n# 构建并部署 Next.js 向导\njobs:\n build:\n - 对 TypeScript 进行类型检查\n - 运行 ESLint\n - 构建生产版本的 Bundle\n\n deploy:\n - 部署至 Vercel（生产环境）\n```\n\n### 自动校验和 + 异常修复 (`checksum-monitor.yml`)\n\nACFS 会自动监控上游安装程序的变更，并针对生成的工件校验和偏差进行修复：\n\n```yaml\n# 每 2 小时运行一次，且在上游变更时触发\nschedule: \"0 *\u002F2 * * *\"\ntriggers:\n - 按计划定时运行（每 2 小时）\n - 从上游仓库发送 Webhook（repository_dispatch）\n - 接收涉及安装程序\u002F校验和\u002F生成器文件的推送\n\n**工作原理：**\n\n1. **检测生成工件的偏差**：运行 `scripts\u002Fcheck-manifest-drift.sh --json`，以检测：\n - `ACFS_MANIFEST_SHA256` 不匹配\n - 内部脚本校验和偏差（`scripts\u002Fgenerated\u002Finternal_checksums.sh`）\n2. **自动修复偏差**：若检测到偏差，执行 `--fix`（重新生成、提交并推送）\n3. **验证当前上游校验和**：下载所有上游安装程序，计算 SHA256 校验值\n4. **检测上游变更**：与 `checksums.yaml` 进行比对\n5. **分类工具**：将“可信”工具（可自动更新）与其他工具区分开来\n6. **自动更新上游校验和**：在安全的情况下，将更新后的 `checksums.yaml` 提交\n7. **提醒**：对于非可信工具的变更，会创建 GitHub 问题，供人工审核。\n\n当校验返回获取错误或出现跳过条目时，监控会**关闭并标记为已解决**；但不会发出部分或占位式的校验和更新。\n\n**可信工具（已启用自动更新）：**\n- Dicklesworthstone 堆栈工具（ntm、cass、cm、ubs、slb、dcg、caam、bv、agent-mail、ru）\n- 这些工具由同一作者维护，因此上游变更被默认视为可信。\n\n**非可信工具（需人工审核）：**\n- 第三方安装程序（bun、uv、rust、oh-my-zsh、atuin、zoxide、nvm）\n- 若有变更，会触发 GitHub 问题，并附带详细差异信息供人工审核。\n\n这确保了：\n- **安全性**：第三方变更在部署前经过审核\n- **效率**：内部工具更新可自动部署\n- **可审计性**：所有变更均可通过 Git 提交记录追踪\n\n**上游仓库调度（快速路径）：**\n- ACFS 所属的工具仓库会在其 `install.sh` 文件发生变更或发布新版本时，触发 `repository_dispatch` 事件。\n- 每个工具仓库都需要配置一个名为 `ACFS_REPO_DISPATCH_TOKEN` 的 PAT 密钥（该组织\u002F用户专属的仓库范围）。\n- 若调度失败，按计划运行的监控器仍能检测到偏差（不过速度会稍慢）。\n\n### 生产烟雾测试 (`production-smoke.yml`)\n\n验证部署至真实环境：\n\n```yaml\n# 在部署后运行\njobs:\n smoke:\n - 从生产 URL 获取 install.sh\n - 验证校验和是否与仓库一致\n - 检查 Shell 语法\n - 确认没有未提交的偏差\n```\n\n### 安装程序 Canary（Docker）(`installer-canary.yml`)\n\n每天定时运行完整的安装程序端到端测试，运行于全新的 Ubuntu 容器中。\n\n```yaml\nschedule: \"30 7 * * *\" # 每天运行\njobs:\n canary:\n - 运行 tests\u002Fvm\u002Ftest_install_ubuntu.sh（Vibe 模式）\n - 使用 ACFS_CHECKSUMS_REF=main，获取最新哈希值\n```\n\n### Playwright E2E 测试 (`playwright.yml`)\n\n对向导网站进行全面的浏览器测试：\n\n```yaml\n# 在 PR 到主分支上运行\nbrowsers:\n - Chromium\n - Firefox\n - WebKit\n - Mobile Chrome\n - Mobile Safari\n\ntests:\n - 检查向导流程的完成情况\n - 测试步骤导航\n - 检查复制按钮的功能\n - 确保响应式设计\n```\n\n---\n\n## VPS 提供商\n\nACFS 可在任何配备 SSH 密钥登录的 Ubuntu VPS 上运行。以下是针对多代理工作负载优化的推荐提供商。\n\n> **为什么需要 48–64GB RAM？** 每个 AI 编程代理大约需要 2GB RAM。若要同时运行 10–20 个以上的代理，至少需要 48GB 以上的内存。切勿因节省 20美元的托管费用而让价值 400+ 美元\u002F月的 AI 投资陷入瓶颈。\n\n### Contabo（性价比之选——首选）\n\n| 计划 | RAM | vCPU | 存储 | 价格 | 注意事项 |\n|------|-----|------|---------|-------|-------|\n| **云 VPS 50** | 64GB | 16 | 400GB NVMe | ~$56\u002F月（美国） | **推荐** — 最适合严肃的多代理工作 |\n| 云 VPS 40 | 48GB | 12 | 300GB NVMe | ~$36\u002F月（美国） | 适合预算有限的选项，但仍十分舒适 |\n\n- 市场上性价比最高\n- 按月计费，无需承诺期限\n- 美国数据中心定价包含约 10 美元\u002F月的额外溢价\n\n### OVH（绝佳替代方案）\n\n| 计划 | RAM | vCore | 存储 | 价格 | 注意事项 |\n|------|-----|-------|---------|-------|-------|\n| **VPS-5** | 64GB | 16 | 320GB NVMe | ~$40\u002F月 | **推荐** — 优秀的欧盟和美国数据中心 |\n| VPS-4 | 48GB | 12 | 240GB NVMe | ~$26\u002F月 | 适合预算有限的选项 |\n\n- 包含 Anti-DDoS 服务\n- 按月计费，长期承诺可享受 5–15% 的折扣\n- 启用速度通常比 Contabo 更快\n\n### 要求\n\n| 要求 | 最低 | 推荐 |\n|-------------|---------|-------------|\n| **操作系统** | Ubuntu 22.04+（自动升级） | Ubuntu 25.10 |\n| **RAM** | 32GB（较为紧张） | 48–64GB |\n| **存储** | 250GB NVMe SSD | 300GB+ NVMe SSD |\n| **CPU** | 12 vCPU | 16 vCPU |\n| **价格** | ~$26\u002F月 | ~$40–56\u002F月 |\n\n### 其他提供商\n\n任何拥有 Ubuntu VPS 且可使用 SSH 密钥登录的提供商均可正常运行。[agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) 提供的向导均附有分步指南。\n\n### 提供商设置指南\n\nACFS 在 `scripts\u002Fproviders\u002F` 目录下为每家支持的提供商提供了详尽的分步指南：\n\n| 提供商 | 指南 | 关键章节 |\n|----------|-------|--------------|\n| **Contabo** | `contabo.md` | 账户创建、套餐选择、数据中心选择、SSH 密钥配置 |\n| **OVH** | `ovh.md` | 控制面板导航、实例配置、网络设置 |\n| **Hetzner** | `hetzner.md` | 项目搭建、防火墙规则、控制台访问 |\n\n每份指南都包含：\n- 每一步的截图（位于 `scripts\u002Fproviders\u002Fscreenshots\u002F` 中）\n- 带有推荐方案的详细定价说明\n- 区域选择指南（考虑延迟和隐私问题）\n- 专属于该提供商的 SSH 密钥配置\n- 针对常见部署问题的故障排查指南\n\n**提供商对比：**\n\n| 项目 | Contabo | OVH | Hetzner |\n|--------|---------|-----|---------|\n| 最佳选择 | 最高性价比 | 欧洲数据存储 | 德国本地化工程 |\n| 部署时间 | 1–3 小时 | 5–30 分钟 | 2–10 分钟 |\n| 支持方式 | 仅提供电子邮件支持 | 电话 + 聊天 | 24\u002F7 工单系统 |\n| 数据中心 | 欧洲、美国、亚洲 | 全球覆盖 | 仅限欧洲 |\n| 支付方式 | 按月计费 | 按小时或按月计费 | 按小时或按月计费 |\n\n**推荐流程：**\n1. **预算**：Contabo（每美元能获得最佳配置）\n2. **速度**：Hetzner（即时部署）\n3. **支持**：OVH（提供电话客服支持）\n4. **隐私**：任意欧盟提供商（符合 GDPR 法规）\n\n---\n\n## 项目结构\n\n```\nagentic_coding_flywheel_setup\u002F\n├── README.md # 本文件\n├── AGENTS.md # 开发指南\n├── VERSION # 当前版本（0.2.0）\n├── install.sh # 主安装程序入口点\n├── acfs.manifest.yaml # 标准工具清单（共 510 行）\n├── checksums.yaml # 上游脚本的 SHA256 哈希值\n├── package.json # 根级单体仓库配置\n│\n├── apps\u002F\n│ └── web\u002F # Next.js 16 向导网站\n│ ├── app\u002F # 应用路由器页面\n│ │ ├── layout.tsx # 根布局\n│ │ ├── page.tsx # 登陆页\n│ │ └── wizard\u002F # 向导步骤页面\n│ ├── components\u002F # UI 组件\n│ └── lib\u002F # 工具库\n│\n├── packages\u002F\n│ ├── manifest\u002F # 清单解析器 + 生成器\n│ │ └── src\u002F\n│ │ ├── parser.ts # YAML 解析\n│ │ ├── schema.ts # Zod 验证模式\n│ │ ├── types.ts # TypeScript 类型\n│ │ ├── utils.ts # 辅助函数\n│ │ └── generate.ts # 脚本生成器\n│ ├── installer\u002F # 安装程序辅助脚本\n│ └── onboard\u002F # 操作员界面源代码\n│\n├── acfs\u002F # 部署至 ~\u002F.acfs 的文件\n│ ├── zsh\u002F\n│ │ └── acfs.zshrc # Shell 配置\n│ ├── tmux\u002F\n│ │ └── tmux.conf # Tmux 配置\n│ └── onboard\u002F\n│ ├── onboard.sh # 操作员界面脚本\n│ └── lessons\u002F # 教程 Markdown 文件（共 11 个文件）\n│\n├── scripts\u002F\n│ ├── lib\u002F # 安装程序 Bash 库\n│ │ ├── logging.sh # 控制台输出\n│ │ ├── security.sh # HTTPS + 哈希校验\n│ │ ├── os_detect.sh # 操作系统检测\n│ │ ├── user.sh # 用户管理\n│ │ ├── zsh.sh # Shell 设置\n│ │ ├── update.sh # 更新命令逻辑\n│ │ ├── gum_ui.sh # 增强型用户界面\n│ │ ├── cli_tools.sh # 工具安装\n│ │ └── doctor.sh # 健康检查\n│ ├── generated\u002F # 自动从清单生成\n│ │ ├── install_base.sh # 基础软件包\n│ │ ├── install_shell.sh # Shell 工具\n│ │ ├── install_cli.sh # CLI 工具\n│ │ ├── install_lang.sh # 语言运行时\n│ │ ├── install_agents.sh # AI 编码代理\n│ │ ├── install_cloud.sh # 云 CLI\n│ │ ├── install_stack.sh # Dicklesworthstone 堆栈\n│ │ ├── install_all.sh # 主安装程序\n│ │ └── doctor_checks.sh # 验证检查\n│ ├── providers\u002F # VPS 提供商指南\n│ │ ├── ovh.md\n│ │ ├── contabo.md\n│ │ └── hetzner.md\n│ └── sync\u002F\n│ └── sync_ntm_palette.sh # 同步 NTM 命令面板\n│\n├── .github\u002F\n│ └── workflows\u002F\n│ ├── installer.yml # ShellCheck + Ubuntu 矩阵测试\n│ └── website.yml # Next.js 构建 + 部署\n│\n└── tests\u002F\n └── vm\u002F\n └── test_install_ubuntu.sh # Docker 集成测试\n```\n\n---\n\n## 开发\n\n### 网站开发\n\n```bash\ncd apps\u002Fweb\nbun install # 安装依赖\nbun run dev # 开发服务器，地址为 http:\u002F\u002Flocalhost:3000\nbun run build # 生产环境构建\nbun run lint # 代码检查\nbun run type-check # TypeScript 检查\n```\n\n### 清单开发\n\n```bash\ncd packages\u002Fmanifest\nbun install # 安装依赖\nbun run generate # 生成安装程序脚本\nbun run generate:dry # 预览，无需写入文件\n```\n\n### 安装程序测试\n\n```bash\n# 本地代码检查\nshellcheck install.sh scripts\u002Flib\u002F*.sh\n\n# 全面的安装程序集成测试（Docker，与 CI 一致）\n.\u002Ftests\u002Fvm\u002Ftest_install_ubuntu.sh\n```\n\n### 安全验证\n\n```bash\n# 打印所有上游 URL\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --print\n\n# 校验所有哈希值\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --verify\n\n# 在审查上游变更后更新哈希值\n.\u002Fscripts\u002Flib\u002Fsecurity.sh --update-checksums > checksums.yaml\n```\n\n### 清单验证\n\n清单解析器不仅进行基本的 Schema 校验，还具备全面的验证功能：\n\n**验证错误代码：**\n\n| 代码 | 描述 |\n|------|-------------|\n| `MISSING_DEPENDENCY` | 模块引用了不存在的依赖项 |\n| `DEPENDENCY_CYCLE` | 发现循环依赖关系（A→B→C→A） |\n| `PHASE_VIOLATION` | 模块在依赖项之前运行 |\n| `FUNCTION_NAME_COLLISION` | 两个模块生成了相同的 Bash 函数 |\n| `RESERVED_NAME_COLLISION` | 模块使用了保留的标识符 |\n| `INVALID_VERIFIED_INSTALLER_RUNNER` | 运行器未列入白名单（仅支持 Bash\u002FShell） |\n\n**运行验证：**\n```bash\ncd packages\u002Fmanifest\nbun run validate # 全面验证\nbun run validate --verbose # 显示所有检查结果\n```\n\n**循环检测算法：**\n```\nTarjan 强连通分量（SCC）：\n1. 使用 DFS 进行发现与低链跟踪\n2. 找出规模大于 1 的 SCC，将其视为循环\n3. 为人工调试生成循环路径\n```\n\n### 测试框架\n\nACFS 提供了全面的测试框架（`tests\u002Fvm\u002Flib\u002Ftest_harness.sh`），用于集成测试：\n\n```bash\n# 加载测试框架\nsource tests\u002Fvm\u002Flib\u002Ftest_harness.sh\n\n# 初始化测试套件\nharness_init \"ACFS 安装测试\"\n\n# 创建测试模块\nharness_section \"阶段 1：基础软件包\"\n\n# 使用自动日志记录运行命令\nharness_run \"安装 curl\" apt install -y curl\n\n# 验证结果\nharness_pass \"curl 安装成功\"\nharness_fail \"curl 安装失败\"\nharness_skip \"跳过可选测试\"\n\n# 生成总结\nharness_summary # 输出：15 个通过，0 个失败，2 个被跳过\n```\n\n**测试文件：**\n\n| 测试 | 目的 |\n|------|---------|\n| `test_install_ubuntu.sh` | 全面的基于 Docker 的安装过程 |\n| `test_acfs_update.sh` | 更新机制验证 |\n| `bootstrap_offline_checks.sh` | 离线系统就绪性检查 |\n| `resume_checks.sh` | 状态恢复验证 |\n| `selection_checks.sh` | 模块选择单元测试 |\n| `selection_e2e.sh` | 端到端选择流程 |\n\n**运行测试：**\n```bash\n# 全面的 Docker 集成测试\n.\u002Ftests\u002Fvm\u002Ftest_install_ubuntu.sh\n\n# 选择逻辑测试\n.\u002Ftests\u002Fvm\u002Fselection_checks.sh\n\n# Web 端到端测试\n.\u002Ftests\u002Fweb\u002Frun_e2e.sh\n```\n\n### 同步脚本\n\n同步脚本确保 ACFS 文档与上游项目保持一致：\n\n```bash\n# 从上游同步 NTM 命令调色板\n.\u002Fscripts\u002Fsync\u002Fsync_ntm_palette.sh\n\n# 检查是否有可用更新（无需下载）\n.\u002Fscripts\u002Fsync\u002Fsync_ntm_palette.sh --check\n```\n\n**当前同步源：**\n\n| 脚本 | 源 | 目标 |\n|--------|--------|-------------|\n| `sync_ntm_palette.sh` | NTM 仓库 `command_palette.md` | `acfs\u002Fonboard\u002Fdocs\u002Fntm\u002F` |\n\n所有同步脚本均使用安全库进行 HTTPS 执行和内容哈希处理。\n\n### 网站设计系统\n\n网站采用一套完整的设计系统（`apps\u002Fweb\u002Flib\u002Fdesign-tokens.ts`）：\n\n**颜色令牌（OKLCH 色彩空间）：**\n```typescript\n\u002F\u002F 以感知统一的方式呈现色彩\ncolors: {\n cyan: \"oklch(0.75 0.18 195)\", \u002F\u002F 主要强调色\n pink: \"oklch(0.7 0.2 330)\", \u002F\u002F 辅助强调色\n purple: \"oklch(0.65 0.18 290)\", \u002F\u002F 三级强调色\n success: \"oklch(0.72 0.19 145)\", \u002F\u002F 绿色\n warning: \"oklch(0.78 0.16 75)\", \u002F\u002F 黄色\n error: \"oklch(0.65 0.22 25)\", \u002F\u002F 红色\n}\n```\n\n**阴影令牌：**\n```typescript\nshadows: {\n cardHover: \"0 20px 40px -12px oklch(0.75 0.18 195 \u002F 0.15)\",\n cardLifted: \"0 25px 50px -12px oklch(0.75 0.18 195 \u002F 0.2)\",\n primaryGlow: \"0 0 40px -8px oklch(0.75 0.18 195 \u002F 0.3)\",\n}\n```\n\n**动画预设：**\n```typescript\nanimations: {\n hover: { scale: 1.02, transition: { duration: 0.2 } },\n tap: { scale: 0.98 },\n fadeIn: { opacity: [0, 1], transition: { duration: 0.3 } },\n}\n```\n\n**无障碍支持：**\n- 通过 `useReducedMotion` 钩子减少运动支持\n- 语义化 HTML 结构\n- 在交互元素上添加 ARIA 标签\n- 提供键盘导航支持\n\n### 需求\n\n- **运行时环境：** Bun（而非 npm\u002Fyarn\u002Fpnpm）\n- **Node 版本：** 最新版本\n- **Shell：** Bash 5+\n\n---\n\n## 常见问题解答\n\n### 为什么是“Vibe 模式”？\n\nVibe 模式专为那些对速度更为看重、而对安全性要求相对较低的 **一次性 VPS 环境** 设计：\n- 无密码 sudo 可以大幅减少操作步骤中的摩擦\n- 代理危险标志会跳过确认对话框\n- 预配置的别名能够最大限度地提升运行速度\n\n**切勿在生产环境或共享系统中使用 Vibe 模式。**\n\n### 我可以在本地机器上使用吗？\n\nACFS 专为全新的 Ubuntu VPS 实例设计。虽然您*可以*在本地运行它：\n- 它可能会与现有配置产生冲突\n- 它默认需要 root 或 sudo 权限\n- 它并非专为 macOS 或 Windows 设计\n\n若需本地开发，请直接使用独立的工具。\n\n### 如果安装程序失败了怎么办？\n\n安装程序已进行了 **断点续传** 处理。只需重新运行即可：\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n它会跳过已完成的阶段，并从上次中断处继续执行。\n\n### 如何更新工具？\n\n使用内置的更新命令：\n```bash\nacfs update # 更新所有标准组件\nacfs update --stack # 包含 Dicklesworthstone 堆栈\nacfs update --agents-only # 仅更新 AI 代理\n```\n\n### 如何卸载？\n\n没有专门的卸载脚本。要重置环境：\n1. 删除 VPS 实例\n2. 创建一个新的实例\n3. 重新运行安装程序\n\n这是有意为之——ACFS 专为临时的 VPS 环境而设计。\n\n### 我可以自定义安装哪些工具吗？\n\n目前，ACFS 会安装全套工具。未来版本将支持：\n- 基于清单的工具选择\n- 交互式模式，方便用户自由选择组件\n- 模块化安装脚本\n\n---\n\n## 为什么有 ACFS？\n\n### 问题所在：Agentic 编程的壁垒\n\nAI 编程代理（如 Claude Code、Codex CLI、Gemini CLI）的兴起，为软件开发带来了全新的范式。这些代理不仅能编写代码、调试问题，甚至还能构建解决方案——但前提是它们必须拥有合适的运行环境。\n\n**问题的根源并不在于代理本身。** 而是创建一个能让代理真正高效工作的环境，往往需要耗费数小时的配置时间：\n\n```\n┌────────────────────────────────────────────────────────────────────────────┐\n│ 未使用 ACFS 的时间投入 │\n│ │\n│ VPS 配置 ..................... 30–60 分钟 │\n│ Shell 配置 ........... 20–30 分钟 │\n│ 语言运行时 ............. 30–45 分钟 │\n│ 开发工具 ........... 20–30 分钟 │\n│ 代理安装 ............ 15–30 分钟 │\n│ 代理配置 ........... 20–40 分钟 │\n│ 协调工具 ............ 30–60 分钟 │\n│ 故障排除 ............... 30–120 分钟 │\n│ ───────────────────────────────────────── │\n│ 总计：3–7 小时（且前提是所有环节都顺利进行） │\n│ │\n│ 使用 ACFS 的时间投入 │\n│ │\n│ 运行一条命令 ............... 25–30 分钟 │\n│ ───────────────────────────────────────── │\n│ 总计：30 分钟 │\n└────────────────────────────────────────────────────────────────────────────┘\n```\n\n**ACFS 完全消除了这一障碍。** 只需一条命令，30 分钟即可完成全部配置。\n\n### 更深层次的问题：初学者无从下手\n\n对于有经验的开发者来说，这一套设置虽然繁琐，但完全可行。然而，对于初学者——那些最需要AI编程辅助的人群而言，这却是一道难以逾越的障碍：\n\n- 什么是SSH？我该如何生成密钥？\n- 什么是VPS？我该如何租用一台？\n- 终端是什么？我该使用哪一个？\n- 如何连接到远程服务器？\n- 这些工具究竟是什么？为什么我需要它们？\n\n[agent-flywheel.com 的向导式网站](https:\u002F\u002Fagent-flywheel.com)通过以下方式解决了这一难题：\n\n1. **为初学者提供绝对清晰的指导**——用通俗易懂的语言讲解每一个概念。\n2. **针对不同操作系统提供详细说明**——自动识别是Mac还是Windows，并显示正确的命令。\n3. **直观的可视化操作**——每一步都配有复选框，命令操作则附带复制按钮。\n4. **提供故障排查与解决方案**——针对常见问题，专门设置了可扩展的章节。\n5. **持续记录进度**——在浏览器会话中，能够从上次中断处继续进行操作。\n\n---\n\n## 10倍的乘数效应\n\nACFS 不仅仅是一组工具的集合，而是一个经过精心设计的系统——每个组件都能相互放大、彼此赋能。其价值并非简单的相加，而是呈指数级增长。\n\n### 工具协同模型\n\n```\n ┌─────────────────┐\n │ 生产力 │\n │ 乘数 │\n └────────┬────────┘\n │\n ┌─────────────────────────────┼─────────────────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ 环境层 │ │ 代理层 │ │ 协调层 │\n│ 层次 │ │ 层次 │ │ 层次 │\n├─────────────────┤ ├─────────────────┤ ├─────────────────┤\n│ • zsh + p10k │────────▶│ • Claude Code │────────▶│ • 代理邮件 │\n│ • tmux │ │ • Codex CLI │ │ • NTM │\n│ • 现代 CLI │ │ • Gemini CLI │ │ • SLB + DCG │\n│ • 语言虚拟机 │ │ │ │ • Beads 查看器 │\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │ │ │\n │ 每一层都让彼此得以 │ 代理们得以更高效地 │\n │ 相互协作，共同提升能力 │ 联合发力，成就更大价值 │\n └─────────────────────────────┴─────────────────────────────┘\n```\n\n### 为何选择这些特定的工具？\n\nACFS 中的每一款工具，都是凭借其**实实在在的生产力提升**而脱颖而出的：\n\n| 工具 | 单个工具的价值 | 协同效应的价值 |\n|------|-----------------|---------------|\n| **tmux** | 持续运行的会话 | 代理们可以在你断开连接时依然高效工作 |\n| **NTM** | 有序的会话管理 | 一条命令即可在命名窗口中启动10个代理 |\n| **代理邮件** | 消息传递机制 | 代理们无需冲突就能实现高效协作 |\n| **SLB** | 两人协作规则 | 危险的操作必须经过确认 |\n| **DCG** | 命令防护机制 | 在命令执行前拦截并阻止破坏性指令 |\n| **Beads 查看器** | 任务追踪功能 | 代理们可以实时掌握项目进展，避免返工 |\n| **atuin** | 命令历史记录 | 在多个会话间轻松查找命令，共享操作模式 |\n| **zoxide** | 智能 CD | 使用 `z proj` 比使用 `cd ~\u002Fprojects\u002Fmy-long-name` 更加高效 |\n| **ripgrep** | 快速搜索 | 代理们比 grep 快10倍找到代码 |\n| **fzf** | 模糊匹配搜索 | 以交互式方式完成选择，而非手动输入路径 |\n\n### 复合效应的奇妙之处\n\n只需一名具备基础工具的代理，便已足够实用。而当三名代理协同工作时：\n- 共享统一的项目结构\n- 通过代理邮件实现协调\n- 通过 NTM 实现流程优化\n- 通过 SLB 设置安全防护机制\n- 通过 DCG 防止危险命令的误执行\n- 通过 Beads 提供任务视图，让代理们随时了解项目状态，避免重复劳动\n\n……在短短一天内，就能完成一位独立开发者一周才能完成的工作。\n\n小贴士：运行 `acfs services-setup` 来配置登录信息，并启用 DCG 以保护危险命令。\n\n**这就是飞轮效应的生动体现：更好的工具 → 更强大的代理 → 更多代码被交付 → 对工具需求的理解更加深入 → 更好的工具。**\n\n---\n\n## 设计算法与决策\n\nACFS 采用了多种算法模式，确保系统的可靠性与可维护性。\n\n### 幂等性算法\n\n每项安装功能都遵循“先检查再安装”的原则：\n\n```bash\ninstall_tool() {\n if command_exists \"tool\"; then\n log_success \"工具已安装\"\n return 0\n fi\n\n # ... 安装逻辑 ...\n\n if command_exists \"tool\"; then\n log_success \"工具安装成功\"\n return 0\n else\n log_error \"工具安装失败\"\n return 1\n fi\n}\n```\n\n这一设计保证了：\n1. **安全的重试机制**——两次运行安装程序并不会导致任何问题。\n2. **恢复能力**——即使出现失败，也不必从头开始。\n3. **声明式的意图表达**——最终状态被明确界定，而非仅停留在过渡阶段。\n\n### 校验和验证算法\n\n安全系统采用**内容寻址校验**的方式：\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 校验流程 │\n│ │\n│ 1. 将脚本下载至内存（而非磁盘） │\n│ 2. 计算下载内容的 SHA256 校验值 │\n│ 3. 与校验和文件中的存储哈希值进行对比 │\n│ 4. 若校验一致 → 执行 │\n│ 5. 若不一致 → 拒绝执行，并报告差异 │\n│ │\n│ 关键洞察：我们只对内容进行校验，而非单纯依赖传输过程 │\n│ （HTTPS 只能保护通信通道，无法保护源端的内容） │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### 指标驱动的生成\n\n生成器采用**模板扩展**的模式：\n\n1. **解析**——读取 YAML 清单，并使用 Zod 模式进行验证。\n2. **转换**——将清单条目转化为安装函数。\n3. **分类**——按类别进行整理（基础、Shell、CLI、语言、代理等）。\n4. **生成**——输出结构一致的 Bash 脚本。\n5. **验证**——通过校验命令生成完善的校验检查。\n\n这一设计确保了清单成为**唯一的真实来源**——文档、安装程序与校验结果之间不存在偏差。\n\n### 代码生成器架构\n\n`manifest` 生成器（`packages\u002Fmanifest\u002Fsrc\u002Fgenerate.ts`）是一个高度复杂的 TypeScript 程序，能够将 YAML 转换为 Bash：\n\n**输入处理：**\n```typescript\n\u002F\u002F 1. 解析 YAML 并进行验证\nconst manifest = parseManifestFile(MANIFEST_PATH); \u002F\u002F 使用 Zod 进行验证\n\n\u002F\u002F 2. 加载用于验证安装程序的校验和\nconst checksums = parseYaml(readFileSync(CHECKSUMS_PATH));\n\n\u002F\u002F 3. 对依赖关系进行拓扑排序\nconst sorted = sortModulesByInstallOrder(manifest.modules);\n```\n\n**以安全为先的代码生成：**\n```typescript\n\u002F\u002F 实现 Shell 安全的引号处理（防止命令注入）\nfunction shellQuote(s: string): string {\n return `'${s.replace(\u002F'\u002Fg, \"'\\\\''\")}'`;\n}\n\n\u002F\u002F 仅允许指定的运行器（严格管控）\nconst ALLOWED_RUNNERS = ['bash', 'sh'] as const;\n\n\u002F\u002F 构建经过验证的安装程序管道\nfunction buildVerifiedInstallerPipe(module: Module, checksums: Checksums): string {\n \u002F\u002F 生成的命令：curl -fsSL \"$URL\" | verify_checksum \"$SHA256\" | bash\n}\n```\n\n**输出结构：**\n```\nscripts\u002Fgenerated\u002F\n├── install_base.sh # 基础系统软件包（apt）\n├── install_users.sh # 用户规范化（Ubuntu 用户）\n├── install_filesystem.sh # 目录结构（\u002Fdata\u002Fprojects）\n├── install_shell.sh # zsh + oh-my-zsh + p10k\n├── install_cli.sh # ripgrep、tmux、fzf、lazygit 等\n├── install_network.sh # Tailscale\n├── install_lang.sh # bun、uv、rust、go\n├── install_tools.sh # ast-grep、atuin、zoxide\n├── install_agents.sh # claude、codex、gemini\n├── install_db.sh # PostgreSQL 18、Vault\n├── install_cloud.sh # wrangler、supabase、vercel\n├── install_stack.sh # Dicklesworthstone 10 工具栈 + 实用工具\n├── install_acfs.sh # ACFS 配置部署\n├── install_all.sh # 组织化辅助工具\n├── doctor_checks.sh # 健康检查\n└── manifest_index.sh # 模块元数据数组\n```\n\n**生成脚本结构：**\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\n# 自动从 acfs.manifest.yaml 生成 - 请勿编辑\n\ninstall_module_id() {\n acfs_require_contract \"module.id\" # 验证环境\n\n if run_installed_check \"module.id\"; then\n log_step \"module.id 已经安装\"\n return 0\n fi\n\n set_phase \"安装模块...\"\n run_as_target_shell \u003C\u003C'HEREDOC'\n # 从 manifest 中获取的安装命令\n HEREDOC\n\n verify_module \"module.id\" # 安装后检查\n}\n```\n\n**重新生成：**\n```bash\ncd packages\u002Fmanifest\nbun run generate # 全面重新生成\nbun run generate:dry # 预览，不进行写入\n```\n\n### 生成的 Manifest 索引\n\n生成器会生成 `manifest_index.sh`，这是一个全面的 Bash 元数据文件，可在运行时通过编程方式访问 manifest 数据：\n\n**关联数组：**\n```bash\n# 模块元数据查询\ndeclare -A ACFS_MODULE_DESCRIPTION\nACFS_MODULE_DESCRIPTION[\"lang.bun\"]=\"Bun JavaScript\u002FTypeScript 运行时...\"\n\nACFS_MODULE_DESCRIPTION[\"agents.claude\"]=\"Claude 代码 CLI 代理...\"\n\n# 阶段映射（决定安装顺序）\ndeclare -A ACFS_MODULE_PHASE\nACFS_MODULE_PHASE[\"base.apt\"]=\"1\"\nACFS_MODULE_PHASE[\"lang.bun\"]=\"3\"\nACFS_MODULE_PHASE[\"agents.claude\"]=\"5\"\n\n# 依赖关系（以空格分隔）\ndeclare -A ACFS_MODULE_DEPENDENCIES\nACFS_MODULE_DEPENDENCIES[\"agents.claude\"]=\"lang.bun base.system\"\n\n# 生成的函数名映射\ndeclare -A ACFS_MODULE_FUNCTION\nACFS_MODULE_FUNCTION[\"lang.bun\"]=\"install_lang_bun\"\n\n# 类别分组\ndeclare -A ACFS_MODULE_CATEGORY\nACFS_MODULE_CATEGORY[\"lang.bun\"]=\"lang\"\n\n# 默认包含在安装中\ndeclare -A ACFS_MODULE_DEFAULT\nACFS_MODULE_DEFAULT[\"lang.bun\"]=\"true\"\nACFS_MODULE_DEFAULT[\"db.postgres18\"]=\"true\"\n```\n\n**运行时查询函数：**\n```bash\n# 获取某个类别的所有模块\nget_modules_by_category \"agents\" # 返回：agents.claude agents.codex agents.gemini\n\n# 检查模块是否为默认安装\nis_default_module \"tools.vault\" # 返回：true\n\n# 获取安装阶段\nget_module_phase \"stack.ntm\" # 返回：6\n```\n\n**使用场景：**\n- `acfs doctor` 查询模块元数据，进行健康检查\n- `install.sh --list-modules` 显示可用的模块\n- `--skip \u003Cmodule>` 在跳过模块前验证其是否存在\n- `--only-phase \u003Cn>` 通过阶段映射实现选择性安装\n\n该 Manifest 索引将 TypeScript 生成器与 Bash 运行时无缝衔接，既实现了复杂的模块选择逻辑，又保持了 Bash 脚本的简洁性。\n\n### 向导中的渐进式披露\n\n向导网站采用 **渐进式披露** 的方式来管理复杂度：\n\n```\n级别 1：核心指令（默认可见）\n├── 复制此命令\n├── 将其粘贴到终端\n└── 按下回车键\n\n级别 2：故障排查（可展开）\n├── “权限被拒绝” → 修复说明\n├── “命令未找到” → 前提条件\n└── “连接被拒绝” → 诊断步骤\n\n级别 3：深入解析（可折叠的“新手指南”）\n├── 什么是 SSH？\n├── 什么是 VPS？\n├── 为什么选择这些特定步骤？\n└── 事情的幕后究竟如何运作？\n```\n\n这样，初学者在需要时可以获取深度背景信息，而专家则可以直接跳转到具体的命令操作。\n\n---\n\n## 多代理编排模型\n\nACFS 专为 **多代理工作流** 而设计，允许多个 AI 编码代理同时协作完成同一个项目。\n\n### 协调问题\n\n若缺乏协调，多个代理将导致混乱：\n- **文件冲突** — 两个代理同时编辑同一文件\n- **重复工作** — 各个代理独立解决相同的问题\n- **沟通鸿沟** — 无法实时了解其他代理的进展\n- **安全隐患** — 在缺乏监督的情况下执行危险操作\n\n简化后的中文：\n\n### ACFS 解决方案堆栈\n\n```\n┌───────────────────────────────────────────────────────────────────────────┐\n│ 代理协调层 │\n│ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ 代理邮件 │ │ NTM │ │ SLB + DCG │ │ Beads │ │\n│ │ (消息传递) │ │ (会话) │ │ (安全) │ │ (任务) │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │ │\n│ │ ┌────────────┴────────────────┴────────────────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ 文件预留系统 │ │\n│ │ │ │\n│ │ 代理 A 预留：src\u002Fauth\u002F** │ │\n│ │ 代理 B 预留：src\u002Fapi\u002F** │ │\n│ │ 代理 C 预留：tests\u002F** │ │\n│ │ │ │\n│ │ → 没有冲突，可并行推进 │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n└───────────────────────────────────────────────────────────────────────────┘\n```\n\n### 代理通信模式\n\n**1. 直接消息（代理邮件）**\n```\n代理 A → 代理 B：“我已完成 auth 模块，已准备好进行 API 集成”\n代理 B → 代理 A：“确认，开始与 auth 依赖进行 API 集成”\n```\n\n**2. 广播更新（线程摘要）**\n```\n线程：“Sprint 23 任务”\n├── 代理 A：“已申请用户注册功能”\n├── 代理 B：“已申请 API 端点功能”\n├── 代理 C：“已申请测试覆盖率任务”\n└── 所有代理均可查看项目状态\n```\n\n**3. 文件预留（冲突预防）**\n```\n代理 A：预留路径[“src\u002Fauth\u002F*”]，采用独占模式，有效期为 3600 秒\n代理 B：预留路径[“src\u002Fauth\u002F*”] → 冲突：已被代理 A 占用\n代理 B：预留路径[“src\u002Fapi\u002F*”] → 获得许可\n```\n\n### NTM 编排模式\n\n命名的 Tmux 管理器（NTM）实现了 **单命令式群集启动**：\n\n```bash\n# 启动 10 个代理，每个代理运行在命名的 tmux 窗口内\nntm spawn \\\n --count 10 \\\n --prefix \"agent-\" \\\n --command \"claude --dangerously-skip-permissions\"\n```\n\n结果：\n```\ntmux 会话：acfs-swarm\n├── agent-1：Claude 正在处理 auth\n├── agent-2：Claude 正在处理 api\n├── agent-3：Claude 正在处理 tests\n├── agent-4：Codex 正在审阅 PR\n├── agent-5：Gemini 正在撰写文档\n└── ...\n```\n\n---\n\n## 哲学\n\n### 飞轮效应\n\n“代理编码飞轮”是一个良性循环：\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ │\n│ 更好的环境 → 更高的代理生产力 → │\n│ 更多代码编写 → 更好的理解 → │\n│ 更好的提示 → 更好的环境 │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nACFS 通过提供**最佳的初始环境**来启动这一飞轮，助力代理编码。\n\n### 设计原则\n\n1. **初学者友好，专家高效**：向导引导初学者；单行命令则适合专家使用。\n\n2. **以氛围为核心**：在快速迭代的环境中优化效率。安全特性默认启用，且处于安全模式下。\n\n3. **幂等性**：无需担心重复执行。安装程序会优雅地处理已安装的工具。\n\n4. **单一真相来源**：清单定义了所有内容。安装脚本正是基于此清单生成的。\n\n5. **默认安全**：支持 HTTPS 加密、校验和验证，杜绝盲目的 `curl | bash`。\n\n6. **现代默认配置**：最新版本、现代化工具、开箱即用的最佳配置。\n\n---\n\n## Vibe 编码宣言\n\n“Vibe 编码”不仅仅是一个朗朗上口的名字——它是一种关于人类与 AI 如何协同开展软件开发的理念。\n\n### 什么是 Vibe 编码？\n\nVibe 编码是指**将 AI 代理引导去编写代码，而你专注于意图、架构和质量**。与其自己逐行输入代码，不如：\n\n1. **用自然语言描述你的需求**\n2. **审核并指导** 代理的输出\n3. **通过多种方案快速迭代**\n4. **更快交付**，同时保持高质量\n\n“Vibe”源自你进入的一种心流状态：不再纠结于语法、样板代码或实现细节——你只是与你的 AI 合作伙伴一同“心流”运转。\n\n### Vibe 编码的三条法则\n\n**1. 速度优先，而非仪式感**\n\n传统开发流程往往充斥着繁琐的仪式：创建分支、先写测试、实现、重构、写文档、创建 PR、等待评审、合并、部署。每一步都充满摩擦。\n\nVibe 编码则颠覆了这一模式：快速交付，更快速地迭代。AI 处理样板代码，而你只需专注于那 10% 需要人类判断的部分。\n\n```\n传统方式：思考 → 计划 → 实现 → 测试 → 文档 → 发布\nVibe 方式：描述 → 生成 → 核实 → 发布 → 迭代\n```\n\n**2. 临时环境激发大胆尝试**\n\nVibe 编码的魔力诞生于**临时的 VPS 实例**中。当你的环境是“一次性”的：\n- 你可以毫无顾虑地进行实验\n- 灾难性故障只需“重新搭建 VPS”\n- 代理可以拥有危险权限（但它们无法破坏那些“一次性”的东西）\n- 你专注于输出，而非保护你的环境\n\n这就是为什么 ACFS 的“Vibe 模式”允许无密码 sudo 和危险的代理标志——在每月仅需 5 美元的临时 VPS 上，根本无需担心任何需要保护的内容。\n\n**3. 多代理是默认选择**\n\n一个代理固然有用，但三个代理并行工作则更具变革性。\n\nVibe 编码假设你会同时运行多个代理：\n- Claude 用于复杂推理与架构设计\n- Codex 用于快速原型设计与重构\n- Gemini 用于文档撰写与研究\n\nACFS 提供了协调层（代理邮件、NTM、SLB），让这一切成为现实。\n\n### 反面案例\n\nVibe 编码绝不是：\n- 盲目接受代理输出而不加审核\n- 放弃测试与质量标准\n- 忽视生产系统的安全性\n- 将代理视为替代人类判断的工具\n\n我们的目标是**增强人类判断能力**，而非完全放弃人类判断。\n\n### 何时不应使用 Vibe 编码\n\n- 面向真实用户的生产系统\n- 对安全性要求极高的基础设施\n- 任何涉及凭证或机密信息的场景\n- 长期运行的服务器（请启用安全模式）\n- 共享团队环境（请使用协作工具）\n\nVibe 编码适用于**全新项目开发、原型设计、实验研究以及学习实践**。其他所有场景均建议使用 ACFS 的安全模式。\n\n---\n\n## 状态机与检查点机制\n\nACFS 实现了一套强大的**基于检查点的状态机**，能够确保在发生故障时实现可靠的恢复与继续执行。本节将为您详细讲解其工作原理及底层实现细节。\n\n### 状态文件格式\n\n进度信息存储于 `~\u002F.acfs\u002Fstate.json` 中：\n\n```json\n{\n \"schema_version\": 3,\n \"started_at\": \"2024-12-21T10:30:00Z\",\n \"last_updated\": \"2024-12-21T10:45:23Z\",\n \"mode\": \"vibe\",\n \"completed_phases\": [\"user_setup\", \"filesystem\", \"shell_setup\"],\n \"current_phase\": \"cli_tools\",\n \"current_step\": \"安装 ripgrep\",\n \"failed_phase\": null,\n \"failed_step\": null,\n \"failed_error\": null,\n \"skipped_phases\": [],\n \"phase_timings\": {\n \"user_setup\": 12,\n \"filesystem\": 8,\n \"shell_setup\": 145\n }\n}\n```\n\n### 状态机的阶段转换\n\n每个阶段都会经历一套预定义的状态机流程：\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 状态机阶段流程 │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ PENDING │────▶│ RUNNING │────▶│ COMPLETE │ │\n│ └──────────┘ └────┬─────┘ └──────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌──────────┐ ┌──────────┐ │\n│ │ │ FAILED │────▶│ RETRY │──┐ │\n│ │ └──────────┘ └──────────┘ │ │\n│ │ ▲ │ │\n│ │ └────────┘ │\n│ │ │\n│ └──────────────────────▶┌──────────┐ │\n│ (--skip flag) │ SKIPPED │ │\n│ └──────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 恢复逻辑\n\n当安装程序运行时，会依据以下决策树进行操作：\n\n```python\ndef should_run_phase(phase_id):\n state = load_state_file()\n\n if phase_id in state.completed_phases:\n return SKIP # 已经完成\n\n if phase_id in state.skipped_phases:\n return SKIP # 用户明确选择跳过\n\n if state.failed_phase == phase_id:\n if user_wants_retry():\n return RUN # 重试失败的阶段\n else:\n return ABORT # 不再继续执行失败的步骤\n\n return RUN # 正常执行\n```\n\n### 原子状态更新\n\n状态文件的更新是**原子化的**，以防止因中断写入而导致的数据损坏：\n\n```bash\n# 先将数据写入临时文件\necho \"$new_state\" > \"$state_file.tmp.$$\"\n\n# 原子重命名（POSIX 确保在同一文件系统上执行的重命名操作是原子的）\nmv \"$state_file.tmp.$$\" \"$state_file\"\n```\n\n这样可以确保状态文件始终完整且未被部分写入，即使进程在更新过程中被终止。\n\n### 从常见故障中恢复\n\n| 故障类型 | 检测方式 | 恢复方法 |\n|--------------|-----------|----------|\n| 网络超时 | curl 返回代码 28 | 通过指数递增的退避策略重试 |\n| APT 锁定 | `\u002Fvar\u002Flib\u002Fdpkg\u002Flock` 存在 | 等待并重试，最长可等待 60 秒 |\n| 磁盘满 | 在写入前执行 df 检查 | 以清晰的错误提示终止操作 |\n| 内存不足 | OOM killer 退出 | 从上次失败的阶段继续执行 |\n| SSH 断开连接 | 无直接解决方案（会话自动结束） | 重新建立连接后继续执行 |\n| Ctrl+C | 通过捕获处理程序 | 清理退出，同时保留状态 |\n\n### 阶段时间与性能\n\n状态文件会记录每个阶段的耗时。这使得：\n- 可以准确估算进度（例如：“第 4\u002F9 阶段，剩余约 3 分钟”）\n- 能够检测 ACFS 各个版本之间的性能回归情况\n- 识别出需要优化的慢速阶段\n\n---\n\n## 错误处理与恢复模式\n\nACFS 旨在实现**优雅失败并自动恢复**。本节将详细介绍代码库中所采用的错误处理模式。\n\n### “尝试-步骤”模式\n\n每一步安装操作都封装在 `try_step` 函数中，该函数能够在不终止整个过程的情况下捕获错误：\n\n```bash\ntry_step \"安装 ripgrep\" install_ripgrep\n```\n\n这种模式具有以下优势：\n- **上下文追踪**：错误信息不仅包含退出码，还附带了具体的步骤名称\n- **优雅延续**：非关键性错误不会导致整个安装过程终止\n- **结构化报告**：错误会被收集并统一汇总，在安装结束时进行汇报\n\n### 网络韧性\n\n网络操作采用了**指数递增的退避策略，并结合随机抖动**：\n\n```bash\nretry_with_backoff() {\n local max_attempts=5\n local delay=1\n\n for attempt in $(seq 1 $max_attempts); do\n if \"$@\"; then\n return 0\n fi\n\n \u002F\u002F 指数退避：1 秒、2 秒、4 秒、8 秒、16 秒\n \u002F\u002F 加入随机抖动：±25% 的随机范围\n local jitter=$(( (RANDOM % 50 - 25) * delay \u002F 100 ))\n sleep $((delay + jitter))\n delay=$((delay * 2))\n done\n\n return 1\n}\n```\n\n### APT 锁管理\n\n最常见的安装失败原因，往往是 APT 锁竞争（即有其他进程正在使用 apt）：\n\n```bash\nwait_for_apt_lock() {\n local max_wait=60\n local waited=0\n\n while fuser \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend >\u002Fdev\u002Fnull 2>&1; do\n if [[ $waited -ge $max_wait ]]; then\n log_error \"APT 锁已持有超过 60 秒，即将终止安装\"\n return 1\n fi\n log_detail \"等待 APT 锁... (${waited}s)\"\n sleep 5\n waited=$((waited + 5))\n done\n\n return 0\n}\n```\n\n### 优雅降级\n\n当某个非关键工具未能成功安装时，ACFS 会以警告的形式继续推进：\n\n```\n类别：关键 → 失败会终止安装\n 标准 → 失败被记录，安装将继续进行\n 可选 → 失败被提醒，但无需发出警告\n\n示例：\n 关键：bun、zsh、git（没有这些工具无法继续）\n 标准：ast-grep、lazygit（虽然有用，但不会阻塞）\n 可选：atuin、zoxide（纯粹的增强功能）\n```\n\n### 错误报告\n\n在安装过程的最后（或在安装中断时），ACFS 会生成一份结构化的错误报告：\n\n```\n═══════════════════════════════════════════════════════════════════════════════\n 安装报告\n═══════════════════════════════════════════════════════════════════════════════\n\n 状态：部分成功（已完成 8\u002F9 个阶段）\n\n ✓ 已完成的阶段：\n • 用户设置（12 秒）\n • 文件系统（8 秒）\n • Shell 设置（2 分 25 秒）\n • 命令行工具（4 分 12 秒）\n • 各种语言（3 分 45 秒）\n • 代理（1 分 30 秒）\n • 云服务（2 分 10 秒）\n • 系统堆栈（5 分 20 秒）\n\n ✗ 失败的阶段：最终确认\n 步骤：配置 tmux\n 错误：tmux.conf 在第 42 行存在语法错误\n\n 建议的修复方法：\n 检查 ~\u002F.acfs\u002Ftmux\u002Ftmux.conf 中是否存在语法错误\n 然后运行：curl ... | bash -s -- --yes --mode vibe --resume\n\n═══════════════════════════════════════════════════════════════════════════════\n```\n\n---\n\n## 故障排查指南\n\n本节将介绍常见问题及其解决方案。若需快速调试，请先尝试使用 `acfs doctor`。\n\n### 安装立即失败\n\n**症状**：安装程序在启动后几秒内即退出。\n\n**常见原因及解决方法**：\n\n| 原因 | 检测方式 | 解决方案 |\n|-------|-----------|-----|\n| 未以 root 用户身份运行 | “权限被拒绝” | 使用 `sudo bash`，或在 curl 命令中添加 `sudo` |\n| 未运行 Ubuntu | “不支持的 OS” | ACFS 仅支持 Ubuntu 22.04 及以上版本 |\n| 无网络连接 | “curl: (6) 无法解析主机” | 检查 DNS 设置，尝试执行 `ping google.com` |\n| Bash 版本过旧 | 语法错误 | 升级到 Bash 4 或更高版本 |\n\n### 安装失败后的恢复\n\n当安装程序在中途失败时，它会提供一个“自动恢复提示”，并附上一条精确的命令，帮助您从上次中断处继续安装。\n\n**失败时的显示内容**：\n\n```\n[ERROR] ACFS 安装失败！\n\n要进行故障排查：\n1. 查看日志：cat \u002Fvar\u002Flog\u002Facfs\u002Finstall.log\n2. 如果已安装，运行：acfs doctor（建议以 Ubuntu 用户身份运行）\n\n╔══════════════════════════════════════════════════════════════╗\n║ 要从当前点恢复安装： ║\n╚══════════════════════════════════════════════════════════════╝\n\n curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002F...\u002Finstall.sh | bash -s -- --resume --yes\n\n 失败的阶段：phase_9\n 失败的步骤：install_stack\n```\n\n**恢复提示的关键特性**：\n\n| 特性 | 描述 |\n|---------|-------------|\n| **固定提交哈希** | 使用原始运行的精确 SHA 哈希值，以确保可重复性 |\n| **保留所有标志** | 包含所有原始标志（--skip-*, --mode, --strict） |\n| **自动检测** | 从 `~\u002F.acfs\u002Fstate.json` 中读取失败的阶段\u002F步骤信息 |\n| **可复制的命令** | 准备好直接粘贴并立即运行 |\n\n**手动恢复步骤**：\n\n1. **查看错误信息**：\n ```bash\n # 查看完整日志\n cat \u002Fvar\u002Flog\u002Facfs\u002Finstall.log | tail -50\n\n # 或者搜索“ERROR”\n grep -i error \u002Fvar\u002Flog\u002Facfs\u002Finstall.log\n ```\n\n2. **运行诊断工具**：\n ```bash\n # 以目标用户（Ubuntu）身份运行\n acfs doctor\n\n # 如果以 root 用户身份运行\n sudo -u ubuntu -i bash -lc 'acfs doctor'\n ```\n\n3. **恢复安装**：\n ```bash\n # 使用与失败输出中完全一致的命令\n # 或者使用通用的恢复命令：\n curl -sSL https:\u002F\u002Facfs.sh | bash -s -- --resume --yes --mode vibe\n ```\n\n4. **查看状态文件**（高级功能）：\n ```bash\n # 查看当前的安装状态\n cat ~\u002F.acfs\u002Fstate.json | jq .\n\n # 查看存储的恢复提示\n jq '.resume_hint' ~\u002F.acfs\u002Fstate.json\n ```\n\n**常见失败场景**：\n\n| 场景 | 典型原因 | 恢复方法 |\n|----------|---------------|----------|\n| 网络超时 | 连接短暂中断 | 等待片刻，然后继续安装 |\n| APT 依赖锁定 | 未及时完成无人值守升级 | 等待 2–3 分钟，再继续安装 |\n| 磁盘空间不足 | 空间不足 | 释放磁盘空间，继续安装 |\n| SSH 连接断开 | 会话超时 | 重新建立连接，继续安装 |\n| 工具安装失败 | 上游服务不可用 | 检查状态，继续安装 |\n\n### APT 依赖锁定错误\n\n**症状**：`E: 无法获取锁 \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend`\n\n**解决方法**：\n\n1. **等待无人值守升级完成**（最常见于全新 VPS）：\n ```bash\n # 查看当前持有锁的进程\n sudo lsof \u002Fvar\u002Flib\u002Fdpkg\u002Flock-frontend\n\n # 等待该进程结束（通常在全新 VPS 上需要等待 2–3 分钟）\n # 然后重新运行安装程序\n ```\n\n2. **终止卡住的进程**（如果等待无效）：\n ```bash\n sudo killall apt apt-get dpkg\n sudo dpkg --configure -a\n sudo apt-get update\n ```\n\n### 安装日志与摘要 JSON\n\n每次 ACFS 安装都会生成两份文件，用于调试和工具管理：\n\n**日志文件位置**：\n```\n~\u002F.acfs\u002Flogs\u002Finstall-YYYYMMDD_HHMMSS.log\n```\n\n日志文件会记录安装程序的所有 stderr 输出，包含：\n- 标题，注明版本、日期和模式\n- 所有进度消息与错误信息\n- 完成后已去除 ANSI 颜色\n- 结尾部分包含完成时间戳\n\n**摘要 JSON 文件位置**：\n```\n~\u002F.acfs\u002Flogs\u002Finstall_summary_YYYYMMDD_HHMMSS.json\n```\n\n**摘要 JSON Schema（v1）**：\n```json\n{\n \"schema_version\": 1,\n \"status\": \"success\", \u002F\u002F “success” 或 “failure”\n \"timestamp\": \"2026-01-27T...\", \u002F\u002F ISO 8601\n \"total_seconds\": 1200, \u002F\u002F 实际运行时间\n \"environment\": {\n \"acfs_version\": \"0.9.0\",\n \"mode\": \"vibe\",\n \"ubuntu_version\": \"25.04\",\n \"target_user\": \"ubuntu\",\n \"target_home\": \"\u002Fhome\u002Fubuntu\"\n },\n \"phases\": [\n {\"id\": \"phase_0\", \"duration_seconds\": 5},\n {\"id\": \"phase_1\", \"duration_seconds\": 45},\n \u002F\u002F ... 已完成的各个阶段按顺序排列\n ],\n \"failure\": null, \u002F\u002F 成功时为 null，失败时为：\n \u002F\u002F \"failure\": {\n \u002F\u002F \"phase\": \"phase_9\",\n \u002F\u002F \"step\": \"install_stack\",\n \u002F\u002F \"error\": \"curl 失败，退出码为 7\",\n \u002F\u002F \"resume_hint\": \"curl -sSL ... | bash -s -- --resume --yes\"\n \u002F\u002F }\n \"log_file\": \"\u002Fhome\u002Fubuntu\u002F.acfs\u002Flogs\u002Finstall-20260127_120000.log\"\n}\n```\n\n**访问日志**：\n```bash\n# 查找最新日志\nls -lt ~\u002F.acfs\u002Flogs\u002Finstall-*.log | head -1\n\n# 查找最新摘要\nls -lt ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | head -1\n\n# 解析摘要 JSON\njq . ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | head -1\n\n# 获取失败的阶段（如果有）\njq '.failure \u002F\u002F \"无失败\"'. ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1\n\n# 获取各阶段的耗时\njq '.phases[] | \"\\(.id): \\(.duration_seconds)s\"' ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1\n```\n\n**分享日志以获取支持**：\n\n```bash\n# 创建支持包（去除敏感数据）\nacfs support-bundle > support-bundle.txt\n\n# 或者手动分享（在分享前先检查是否包含敏感信息）：\ncat ~\u002F.acfs\u002Flogs\u002Finstall-*.log | tail -200 # 最后 200 行\ncat ~\u002F.acfs\u002Flogs\u002Finstall_summary_*.json | tail -1 # 最新摘要\n```\n\n--- \n\n### 总结\n\n通过上述步骤，您可以轻松排查和解决 ACFS 安装过程中可能出现的各种问题，并获得准确的故障诊断与解决方案。\n\n### 支持包命令\n\n`acfs support-bundle` 命令会将所有诊断数据收集到一个单一的归档文件中，以便于进行故障排查。\n\n**用法：**\n```bash\nacfs support-bundle [选项]\n```\n\n**选项：**\n\n| 选项 | 描述 |\n|------|-------------|\n| `--verbose, -v` | 在收集过程中显示详细输出 |\n| `--output, -o DIR` | 输出目录（默认为 `~\u002F.acfs\u002Fsupport`） |\n| `--no-redact` | 禁用敏感信息的脱敏处理（警告：该包可能包含敏感信息） |\n| `--help, -h` | 显示帮助信息 |\n\n**输出文件：**\n```\n~\u002F.acfs\u002Fsupport\u002F\u003C时间戳>\u002F # 解压后的包目录\n~\u002F.acfs\u002Fsupport\u002F\u003C时间戳>.tar.gz # 压缩归档文件（可共享）\n~\u002F.acfs\u002Fsupport\u002F\u003C时间戳>\u002Fmanifest.json # 包清单文件\n```\n\n**收集的内容：**\n\n| 文件 | 描述 |\n|------|-------------|\n| `state.json` | 安装状态与检查点 |\n| `VERSION` | ACFS 版本 |\n| `checksums.yaml` | 上游验证校验和 |\n| `logs\u002Finstall-*.log` | 最近的安装日志（最多 10 条） |\n| `logs\u002Finstall_summary_*.json` | 最近的安装摘要 |\n| `doctor.json` | 健康检查结果 |\n| `versions.json` | 已安装的工具版本 |\n| `environment.json` | 操作系统、内存、磁盘及用户信息 |\n| `os-release` | Linux 发行版信息 |\n| `journal-acfs.log` | ACFS 服务的 systemd 日志 |\n| `config\u002F.zshrc` | Shell 配置 |\n\n**安全与脱敏：**\n\n默认情况下，敏感数据会自动进行脱敏处理：\n\n| 模式 | 示例 | 脱敏后内容 |\n|------|-------|-----------|\n| OpenAI API 密钥 | `sk-abc123...` | `\u003CREDACTED:api_key>` |\n| AWS 密钥 | `AKIAIOSFODNN...` | `\u003CREDACTED:aws_key>` |\n| GitHub 令牌 | `ghp_xxxx...` | `\u003CREDACTED:github_token>` |\n| Vault 令牌 | `hvs.xxxx...` | `\u003CREDACTED:vault_token>` |\n| Slack 令牌 | `xoxb-xxxx...` | `\u003CREDACTED:slack_token>` |\n| Bearer 令牌 | `Bearer xxx...` | `Bearer \u003CREDACTED:bearer>` |\n| JWT | `eyJhbGc...` | `\u003CREDACTED:jwt>` |\n| 密码 | `\"password\": \"...\"` | `\"password\": \"\u003CREDACTED:password>\"` |\n\n**示例工作流程：**\n\n```bash\n# 创建支持包\nacfs support-bundle\n\n# 输出：~\u002F.acfs\u002Fsupport\u002F20260127_120000.tar.gz\n\n# 在提交问题时分享归档文件\n# 该归档文件可安全共享（敏感信息已脱敏）\n```\n\n**禁用脱敏处理（请谨慎使用）：**\n```bash\n# 警告：该包可能包含 API 密钥、令牌及密码\nacfs support-bundle --no-redact\n```\n\n**适用场景：**\n- 安装失败且需要分享日志\n- 提交 GitHub 问题关于 ACFS\n- 诊断工具安装问题\n- 与支持团队共享系统状态\n\n### Shell 未切换至 zsh\n\n**症状：** 安装完成后仍显示 bash 提示符。\n\n**解决方案：**\n\n1. **登出并重新登录**（更改会在下次登录时生效）\n\n2. **手动设置 shell：**\n ```bash\n chsh -s $(which zsh)\n # 然后登出并重新登录\n ```\n\n3. **检查 shell 是否已安装：**\n ```bash\n which zsh # 应显示 \u002Fusr\u002Fbin\u002Fzsh\n cat \u002Fetc\u002Fshells # zsh 应被列出\n ```\n\n### 代理身份验证问题\n\n**Claude 代码：**\n```bash\n# 检查身份验证状态\nclaude --version\nls -la ~\u002F.claude\u002F # 或 ~\u002F.config\u002Fclaude\u002F\n\n# 重新进行身份验证\nclaude # 按照提示操作\n```\n\n**Codex CLI：**\n```bash\n# 检查身份验证状态\ncodex --version\n\n# 重新进行身份验证（使用的是 ChatGPT 账户，而非 API 密钥）\ncodex login\n```\n\n**Gemini CLI：**\n```bash\n# 检查身份验证状态\ngemini --version\n\n# 重新进行身份验证\ngemini # 按照 Google 登录流程操作\n```\n\n### 安装后出现“命令未找到”错误\n\n**症状：** 即使安装成功，仍然显示 `claude: 命令未找到`。\n\n**解决方案：**\n\n1. **重新加载 shell 配置：**\n ```bash\n source ~\u002F.zshrc\n # 或者启动一个新的 shell\n exec zsh\n ```\n\n2. **检查 PATH：**\n ```bash\n echo $PATH | tr ':' '\\n' | grep -E \"(bun|local|cargo)\"\n # 应包含：~\u002F.bun\u002Fbin、~\u002F.local\u002Fbin、~\u002F.cargo\u002Fbin\n ```\n\n3. **手动调整 PATH：**\n ```bash\n export PATH=\"$HOME\u002F.bun\u002Fbin:$HOME\u002F.local\u002Fbin:$HOME\u002F.cargo\u002Fbin:$PATH\"\n ```\n\n### Doctor 显示缺少工具\n\n**症状：** `acfs doctor` 显示对预期已安装的工具进行了检查失败。\n\n**理解 Doctor 的输出：**\n\nDoctor 的检查直接基于清单文件生成，因此它会验证与安装程序提供的工具完全一致。当某个检查失败时，Doctor 会显示一条可复制粘贴的修复命令：\n\n```\n ✗ tools.lazygit - Lazygit 终端界面未找到\n 修复方法：acfs install --only tools.lazygit\n```\n\n**解决方案：**\n\n1. **重新运行特定模块**（使用修复建议）：\n ```bash\n acfs install --only tools.lazygit # 只安装该工具\n acfs install --only lang.go # 安装语言运行时\n acfs install --only stack.dcg # 安装堆栈工具\n ```\n\n2. **重新运行整个阶段**（针对同一类别中的多个失败项）：\n ```bash\n acfs install --only-phase 4 # 重新运行第 4 阶段：工具\n acfs install --only-phase 8 # 重新运行第 8 阶段：堆栈\n ```\n\n3. **启用自动修复模式**（应用安全、确定性的修复措施）：\n ```bash\n acfs doctor --fix\n acfs doctor --fix --dry-run # 先预览修复效果\n ```\n\n**注意：** Doctor 的检查与清单文件中的验证命令完全一致。如果在安装过程中跳过了某个工具（例如使用了 `--mode safe`），检查将会失败。这是正常现象——请运行 `acfs doctor`，查看哪些工具缺失，并决定要安装哪些工具。\n\n### Tmux 配置错误\n\n**症状：** Tmux 无法启动，或显示配置错误。\n\n**解决方案：**\n\n1. **检查语法：**\n ```bash\n tmux source-file ~\u002F.tmux.conf\n # 将会显示任何错误的行号\n ```\n\n2. **重置为 ACFS 默认配置：**\n ```bash\n cp ~\u002F.acfs\u002Ftmux\u002Ftmux.conf ~\u002F.tmux.conf\n ```\n\n3. **版本不匹配（旧版 Tmux，新配置）：**\n ```bash\n tmux -V # 检查版本\n # ACFS 配置要求 Tmux 3.0+ 版本\n ```\n\n### 堆栈工具无法正常工作\n\n**症状：** `ntm`、`slb`、`dcg` 等工具未找到，或出现错误提示。\n\n**解决方案：**\n\n1. **重新安装堆栈：**\n ```bash\n acfs update --stack --force\n ```\n\n2. **检查 Cargo 安装是否成功：**\n ```bash\n ls ~\u002F.cargo\u002Fbin\u002F # 应包含 ntm、slb、ru 等工具\n ls ~\u002F.local\u002Fbin\u002F # dcg 通常会在此处安装\n ```\n\n3. **Rust 未在 PATH 中：**\n ```bash\n source ~\u002F.cargo\u002Fenv\n ```\n\n### DCG Hook 问题\n\n**症状：** DCG 未能阻止命令执行，或 Claude 报告的 Hook 错误。\n\n**解决方案：**\n\n1. **运行内置健康检查：**\n ```bash\n dcg doctor\n ```\n\n2. **重新注册 Hook：**\n ```bash\n dcg install --force\n ```\n\n3. **验证 Hook 注册情况：**\n ```bash\n grep -n dcg ~\u002F.claude\u002Fsettings.json ~\u002F.config\u002Fclaude\u002Fsettings.json\n ```\n\n4. **如果二进制文件缺失，重新安装：**\n ```bash\n which dcg # 应返回路径\n # 如果缺失，重新安装：\n curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fdestructive_command_guard\u002Fmain\u002Finstall.sh\" | bash\n dcg install # 重新安装后注册 Hook\n ```\n\n### 完全重置\n\n当其他方法均无效时，可以采取“核弹级”解决方案：\n\n```bash\n# 先保存好所有重要文件！\n\n# 备份 ACFS 状态（推荐）\nts=\"$(date +%Y%m%d_%H%M%S)\"\n[ -d ~\u002F.acfs ] && mv ~\u002F.acfs ~\u002F.acfs.backup.\"$ts\"\n\n# 备份已安装的配置（可选）\nfor f in ~\u002F.zshrc ~\u002F.tmux.conf ~\u002F.p10k.zsh; do\n [ -f \"$f\" ] && mv \"$f\" \"$f\".backup.\"$ts\"\ndone\n\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe --force-reinstall\n```\n\n---\n\n## 安全威胁模型\n\nACFS 严肃对待安全问题，同时也充分认识到 `curl | bash` 安装方式固有的风险。本节将详细阐述我们的威胁模型及相应的缓解措施。\n\n### 我们要防范哪些威胁？\n\n| 威胁 | 缓解措施 |\n|--------|------------|\n| **中间人攻击 (MITM)** | 对所有下载操作实施 HTTPS 验证 |\n| **上游脚本被攻破** | 使用 SHA256 校验和进行验证 |\n| **恶意软件包注入** | 仅使用官方提供的软件包源（apt、cargo、bun） |\n| **凭据泄露** | 脚本或配置文件中不存储任何凭据 |\n| **权限提升** | 仅以最低权限执行 sudo 操作，并明确授予所需权限 |\n| **持久性后门** | 采用临时 VPS 模式；若担心，可重新开始 |\n\n### 我们不防范哪些威胁？\n\n| 威胁 | 为什么不防范 | 缓解措施 |\n|--------|---------|------------|\n| **GitHub 被攻破** | 需要达到 GitHub 级别的安全漏洞 | 通过使用发布标签并验证提交内容 |\n| **上游维护者被攻破** | 无法对人类进行有效验证 | 依靠信任机制与校验和验证 |\n| **已安装工具中的零日漏洞** | 这些漏洞超出了我们的控制范围 | 保持工具最新，及时关注 CVE 报告 |\n| **物理访问 VPS** | 由服务提供商负责 | 选择信誉良好的服务商 |\n| **Vibe 模式被滥用** | 由于设计初衷是用于临时 VPS，因此在重要系统上应启用安全模式 |\n\n### 关于 `curl | bash` 的争论\n\n`curl | bash` 的使用方式颇具争议。批评者指出：\n- 你实际上是在从互联网上执行任意代码\n- 下载过程可能在传输途中被篡改\n- 在执行前无法进行审计\n\n我们的回应：\n1. **HTTPS** 可以有效防止传输过程中出现数据篡改\n2. **校验和** 可以确保下载内容与已知的“好版本”完全一致\n3. **临时环境** 可以将潜在的传播范围限制在最小范围内\n4. **开源社区** 允许对 install.sh 进行预先审核\n\n为了获得最高级别的安全性，您可以这样做：\n```bash\ncurl -fsSL \"https:\u002F\u002F...\" -o install.sh\nless install.sh\nbash install.sh --yes --mode vibe\n```\n\n### 校验和验证的深入解析\n\n我们所获取的每一个上游安装器都会经过校验和验证，以确保其内容与已知的“好版本”完全一致：\n\n```yaml\n# checksums.yaml 片段\ninstallers:\n bun:\n url: \"https:\u002F\u002Fbun.sh\u002Finstall\"\n sha256: \"a1b2c3d4e5f6...\"\n last_verified: \"2024-12-15\"\n notes: \"官方 Bun 安装器\"\n```\n\n校验流程如下：\n\n```\n1. 将脚本下载至内存（而非磁盘）\n2. 计算下载字节的 SHA256 校验和\n3. 将校验和与存储的校验和进行比对\n4. 若校验和匹配：则执行\n5. 若校验和不匹配：则发出警告并中止操作\n```\n\n校验不匹配可能意味着：\n- 上游发布了新版本（这种情况较为常见，通常无需担忧）\n- 上游遭受了攻击（这种情况较少见，但需在更新前进行调查）\n\n我们的更新流程如下：\n1. 监控上游的版本发布\n2. 审核新版本中包含的变更\n3. 仅在人工审核后更新校验和\n4. 在提交更新时附上详细的说明信息，清楚地说明发生了哪些变化\n\n### 校验和验证的深层考量\n\n我们所使用的每一种上游安装器都会经过校验和验证，以确保其内容与已知的“好版本”完全一致：\n\n```yaml\n# checksums.yaml 片段\ninstallers:\n bun:\n url: \"https:\u002F\u002Fbun.sh\u002Finstall\"\n sha256: \"a1b2c3d4e5f6...\"\n last_verified: \"2024-12-15\"\n notes: \"官方 Bun 安装器\"\n```\n\n校验流程如下：\n\n```\n1. 将脚本下载至内存（而非磁盘）\n2. 计算下载字节的 SHA256 校验和\n3. 将校验和与存储的校验和进行比对\n4. 若校验和匹配：则执行\n5. 若校验和不匹配：则发出警告并中止操作\n```\n\n校验不匹配可能意味着：\n- 上游发布了新版本（这种情况较为常见，通常无需担忧）\n- 上游遭受了攻击（这种情况较少见，但需在更新前进行调查）\n\n我们的更新流程如下：\n1. 监控上游的版本发布\n2. 审核新版本中包含的变更\n3. 仅在人工审核后更新校验和\n4. 在提交更新时附上详细的说明信息，清楚地说明发生了哪些变化\n\n### Vibe 模式的安全性考量\n\nVibe 模式（`--mode vibe`）具备以下功能：\n- 为 Ubuntu 用户提供无密码 sudo 权限\n- 为 Claude 提供 `--dangerously-skip-permissions` 选项\n- 为 Codex 提供 `--dangerously-bypass-approvals-and-sandbox` 选项\n- 为 Gemini 提供 `--yolo` 选项\n\n这种模式**在速度方面故意采取了不安全的设计**。请仅在以下场景中使用：\n- 用于临时 VPS，且您并不在意其安全性\n- 用于非生产环境\n- 用于个人实验\n\n切勿在以下场景中使用：\n- 生产服务器\n- 团队共享基础设施\n- 存有敏感数据的系统\n- 长期运行的服务器\n\n---\n\n## 与其他方案的对比\n\nACFS 与其他开发环境搭建方式相比如何？\n\n### 与手动搭建相比\n\n| 方面 | 手动搭建 | ACFS |\n|--------|--------|------|\n| 时间 | 3–7 小时 | 30 分钟 |\n| 一致性 | 不尽相同 | 每次都完全一致 |\n| 文档记录 | 依赖您的记忆 | 本 README 文件 |\n| 失败后的恢复能力 | 从头开始 | 自动恢复 |\n| 更新频率 | 每个工具都需要手动更新 | 使用 `acfs update` 即可 |\n\n**何时使用手动搭建**：当您需要深入了解每个细节，或者对某些特定需求有极高要求时。\n\n### 与 Dotfiles 仓库相比\n\n| 方面 | Dotfiles | ACFS |\n|--------|----------|------|\n| 范围 | 仅限配置文件 | 全部工具的安装 |\n| 便携性 | 适用于 Mac\u002FLinux | 更偏向 Ubuntu 环境 |\n| 维护成本 | 自主完成 | 项目本身由团队共同维护 |\n| 重点在于代理 | 无代理 | 作为核心功能 |\n\n**何时使用 Dotfiles**：当您已经安装了多种工具，只需配置一些必要的设置时。\n\n### 与 Nix\u002FNixOS 相比\n\n| 方面 | Nix | ACFS |\n|--------|-----|------|\n| 可重复性 | 完美 | 优秀 |\n| 学习曲线 | 较陡 | 温和 |\n| 恢复能力 | 本地化 | 手动 |\n| 复杂度 | 高 | 低 |\n| 采用率 | 逐渐提高 | 便捷 |\n\n**何时使用 Nix**：当您需要完美的可重复性，并且愿意投入时间学习 Nix 时。\n\n### 与 DevContainers 相比\n\n| 方面 | DevContainers | ACFS |\n|--------|--------------|------|\n| 隔离性 | 容器化 | 全部 VPS |\n| 资源开销 | 容器运行时 | 无 |\n| IDE 集成 | 以 VSCode 为中心 | 终端原生支持 |\n| 代理体验 | 有限 | 原生 |\n\n**何时使用 DevContainers**：当您希望在现有机器内部构建隔离的项目环境时。\n\n### 与 Ansible\u002FTerraform 相比\n\n| 方面 | Ansible\u002FTF | ACFS |\n|--------|------------|------|\n| 范围 | 基础设施 | 开发环境 |\n| 复杂度 | 高 | 低 |\n| 目标群体 | DevOps | 开发人员 |\n| 学习曲线 | 较陡 | 温和 |\n\n**何时使用 Ansible\u002FTerraform**：当您需要管理多台服务器，而非单独的开发环境时。\n\n### ACFS 的最佳应用场景\n\n当您需要以下条件时，ACFS 是最优选择：\n- 快速搭建一个完整的 agentic 编码环境\n- 以全新的 Ubuntu VPS 作为目标\n- 将 AI 编码代理作为主要工具\n- 采用“临时\u002F短暂”的基础设施思维\n- 在起步阶段只需进行最少的配置即可\n\n---\n\n## Dicklesworthstone Stack 理念\n\nACFS 中所包含的 10 个工具并非随意组合——每个工具都针对特定问题进行了优化，这些问题正是我们在长期的多代理开发实践中不断发现的。\n\n### 面临的问题\n\n同时运行多个 AI 编码代理，会暴露出单代理或无代理开发方式所不存在的问题：\n\n1. **会话混乱**：代理们分散在随机的终端窗口中，缺乏统一的组织管理。\n2. **文件冲突**：两个代理同时编辑同一文件。\n3. **缺乏沟通**：代理之间无法协调或共享彼此的发现结果。\n4. **危险命令**：代理们在没有监督的情况下执行 `git reset --hard` 或 `rm -rf` 等操作。\n5. **上下文丢失**：代理们无法记住之前学到的内容。\n6. **凭据切换**：不同项目需要不同的凭证。\n7. **历史碎片化**：代理间的对话分散在各个系统中。\n8. **任务难以追踪**：难以看清代理们正在处理的具体任务。\n9. **仓库管理混乱**：数十个仓库，难以保持同步，到处都是未提交的工作。\n10. **视觉调试的盲点**：手机上的截图，在 SSH 终端中却无法清晰查看。\n\n简化后的中文内容：\n\n### 解决方案\n\n堆栈中的每一种工具都针对特定的问题提供了解决方案：\n\n| 序号 | 工具 | 解决的问题 | 理念与哲学 |\n|------|------------|----------------------------------|------------------------------------|\n| 1 | **NTM** | 会话混乱问题 | 以命名会话为纽带，从混沌中创造秩序 |\n| 2 | **Agent Mail** | 无通信、文件冲突问题 | 消息传递 + 文件预留机制 |\n| 3 | **UBS** | 危险命令问题 | 带有智能约束的防护机制 |\n| 4 | **Beads Viewer** | 任务视图缺失问题 | 基于图形的任务依赖关系 |\n| 5 | **CASS** | 历史信息分散问题 | 在所有代理之间实现统一搜索 |\n| 6 | **CM** | 丢失上下文问题 | 为代理提供程序化记忆 |\n| 7 | **CAAM** | 身份切换问题 | 通过一条指令完成身份切换 |\n| 8 | **SLB** | 危险命令问题 | 采用两人制规则，确保核选项的安全性 |\n| 9 | **DCG** | 危险的 Git\u002F文件操作指令 | 通过亚毫秒级的 Claude Code 插件，阻止破坏性操作 |\n| 10 | **RU** | 仓库规模过大问题 | 实现仓库同步，并在脏乱的仓库中推动AI驱动的提交自动化 |\n\n**捆绑工具：**\n\n| 工具 | 解决的问题 | 理念与哲学 |\n|------------|----------------------------------|------------------------------------|\n| **giil** | 视觉化调试漏洞 | 将云端图片（如 iCloud、Dropbox、Google Photos）下载至终端 |\n| **csctf** | 知识捕获 | 将 AI 聊天记录转换为可搜索的 Markdown\u002FHTML 归档文件 |\n\n### 协同效应\n\n这些工具的设计理念是相互配合、协同工作：\n\n```\nNTM 启动代理 → 代理向 Agent Mail 注册 →\nAgent Mail 预留文件 → DCG 阻止危险命令 →\nUBS 验证操作 → Beads 跟踪任务 →\nCASS 搜索历史 → CM 提供记忆 →\nCAAM 管理身份验证 → SLB 管控核选项操作 →\nRU 实现仓库同步，并自动化提交流程\n```\n\n单凭某一个工具本身并不能带来颠覆性的改变；只有将它们有机结合，才能实现原本难以想象的工作流：\n\n- **10 个代理并行作业**，且彼此互不干扰\n- **持续运行**——即使 SSH 连接中断也能保持运作\n- **全面审计**——记录下每个代理的操作行为\n- **无需人工干预的协调**——实现高效协作\n- **安全可靠**——在提升效率的同时，依然保障安全\n\n### 堆栈的设计原则\n\n1. **Unix 理念**：每种工具都专注于自身擅长的领域。\n2. **模块化设计**：工具之间通过管道连接，形成有机的整体。\n3. **终端优先**：以 TUI 为主，追求速度而非界面的精致度。\n4. **代理原生**：专为 AI 设计，而非对 AI 进行“适配”。\n5. **Git 兼容**：所有状态均可通过版本控制进行审计。\n\n---\n\n## 高级配置\n\nACFS 支持多种配置方式，以满足高级用户的个性化需求。\n\n### 环境变量\n\n| 变量 | 默认值 | 说明 |\n|--------------|---------------|--------------------------------|\n| `ACFS_HOME` | `~\u002F.acfs` | 配置目录 |\n| `ACFS_REF` | `main` | 用于安装的 Git 引用（标签、分支或提交 SHA） |\n| `ACFS_CHECKSUMS_REF` | `main`（若已固定）\u002F `ACFS_REF`（若使用分支） | 用于获取 `checksums.yaml` 的引用 |\n| `ACFS_LOG_DIR` | `\u002Fvar\u002Flog\u002Facfs` | 日志目录 |\n| `TARGET_USER` | `ubuntu` | 配置用户 |\n| `TARGET_HOME` | `\u002Fhome\u002F$TARGET_USER` | 用户主目录 |\n\n**示例：**\n```bash\n# 从标签版安装（生产环境推荐）\nACFS_REF=v0.1.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.1.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n\n# 从特定分支安装（开发\u002F测试版）\nACFS_REF=feature\u002Fnew-tool curl -fsSL \"...\" | bash -s -- --yes --mode vibe\n\n# 从特定提交安装（实现可重复性）\nACFS_REF=abc1234 curl -fsSL \"...\" | bash -s -- --yes --mode vibe\n\n# 固定安装版本，但使用最新校验和（避免旧哈希冲突）\nACFS_REF=v0.5.0 ACFS_CHECKSUMS_REF=main curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.5.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n```\n\n> **提示：** 务必使 URL 路径与 `ACFS_REF` 一致，这样初始脚本以及后续所有获取的脚本都将来自同一个引用。\n> **提示：** 对于已固定版本的安装（如标签\u002FSHA），校验和默认设置为 `main`，以避免旧版安装的哈希冲突。若需将校验和固定到同一引用，可通过 `ACFS_CHECKSUMS_REF` 进行覆盖。\n\n### 完整安装器 CLI 选项\n\n安装器支持丰富的命令行自定义选项：\n\n**执行控制：**\n```bash\n--yes, -y # 忽略所有提示（非交互式模式）\n--dry-run # 模拟操作，不实际修改任何内容\n--print # 打印出即将安装的内容\n--mode vibe|safe # 安装模式（默认为 vibe）\n--interactive # 强制进入交互式模式，提示用户输入\n--strict # 发生错误时立即终止（而非继续显示警告）\n--checksums-ref \u003Cref> # 从该引用获取 checksums.yaml（默认为 main，适用于已固定标签\u002FSHA） |\n```\n\n**恢复与状态：**\n```bash\n--resume # 从上次检查点恢复\n--force-reinstall # 忽略当前状态，重新安装所有内容\n--reset-state # 清空 state.json，从头开始\n```\n\n**Ubuntu 升级：**\n```bash\n--skip-ubuntu-upgrade # 不升级 Ubuntu 版本\n--target-ubuntu=25.10 # 指定目标 Ubuntu 版本\n--target-ubuntu 25.04 # 替代语法\n```\n\n**跳过某些选项：**\n```bash\n--skip-postgres # 跳过 PostgreSQL 18\n--skip-vault # 跳过 HashiCorp Vault\n--skip-cloud # 跳过 Wrangler、Supabase、Vercel CLI\n--skip-preflight # 跳过预检验证\n```\n\n### 模块选择\n\n通过清单驱动的选型，可以精细控制安装的内容：\n\n```bash\n--list-modules # 列出可用模块\n--print-plan # 显示执行计划，无需实际运行\n--only \u003Cmodule> # 仅运行指定模块\n--only-phase \u003Cphase> # 仅运行某个阶段的模块\n--skip \u003Cmodule> # 跳过特定模块\n--no-deps # 不自动包含依赖项（⚠️ 高级用户适用）\n```\n\n**关键行为：**\n- **依赖关系闭包：** 使用 `--only` 时，系统会自动包含所需的依赖项（默认情况下安全无虞）。\n- **跳过安全检查：** 如果 `--skip` 会破坏必要的依赖链，则会提前失败。\n- **确定性：** 使用 `--print-plan` 可以精确地展示接下来要运行的内容及其执行顺序。\n\n**示例：**\n仅安装代理及其依赖项：\n```bash\ncurl -fsSL \"...\" | bash -s -- --yes --only-phase agents\n```\n\n跳过 PostgreSQL 和 Vault：\n```bash\ncurl -fsSL \"...\" | bash -s -- --yes --skip db.postgres18 --skip tools.vault\n```\n\n在不实际执行的情况下预览即将运行的内容：\n```bash\ncurl -fsSL \"...\" | bash -s -- --print-plan\n```\n\n> **注意：** 使用 `--no-deps` 会绕过安全检查，可能导致安装失败。仅在您已单独安装了依赖项的情况下才应使用此选项。\n\n### 自定义安装后钩子\n\n通过将脚本放置在 `~\u002F.acfs\u002Fhooks\u002F` 目录下，即可添加自定义步骤：\n\n```bash\nmkdir -p ~\u002F.acfs\u002Fhooks\ncat > ~\u002F.acfs\u002Fhooks\u002Fpost-install.sh \u003C\u003C 'EOF'\n#!\u002Fbin\u002Fbash\n# 自定义安装后步骤\necho \"运行自定义配置...\"\n# 在这里编写您的命令\nEOF\nchmod +x ~\u002F.acfs\u002Fhooks\u002Fpost-install.sh\n```\n\nACFS 会在主安装完成后执行 `post-install.sh` 脚本。\n\n### 覆盖工具版本\n\n要固定特定的工具版本，请设置环境变量：\n\n```bash\nexport BUN_VERSION=\"1.1.0\"\nexport UV_VERSION=\"0.5.0\"\n# 然后运行安装器\n```\n\n注意：并非所有工具都支持版本固定。请查阅各工具的官方文档以获取详细信息。\n\n---\n\n## 未来路线图\n\nACFS 正在积极开发中。以下是即将推出的功能：\n\n### 近期（2025年第一季度）\n\n- [ ] **完全基于清单驱动的执行**：install.sh 将自动解析并执行生成的脚本\n- [x] **Tailscale 集成**：无需配置即可实现安全的远程访问 VPN ✓\n- [x] **服务设置向导**：引导用户完成服务账号的设置（`acfs services-setup`） ✓\n- [ ] **交互式模块选择**：通过 TUI 选择要安装的内容\n\n### 中期（2025年第二季度）\n\n- [ ] **ARM64 优化**：支持原生 Apple Silicon 和 ARM VPS\n- [ ] **离线模式**：预先下载的软件包集合\n- [ ] **团队模式**：跨团队成员共享配置\n- [ ] **插件系统**：第三方工具的集成\n\n### 长期（2025年及以后）\n\n- [ ] **ACFS 云服务**：一键式管理 VPS 配置 + ACFS 安装\n- [ ] **IDE 集成**：为远程 ACFS 管理提供 VSCode 和 Cursor 扩展\n- [ ] **代理市场**：预配置的代理个性与工作流\n- [ ] **企业级功能**：单点登录、审计日志、合规性保障\n\n---\n\n## 性能基准\n\n安装时间会因 VPS 提供商和网络状况而异。以下是一些典型基准数据：\n\n### 各阶段安装时间\n\n| 阶段 | 典型耗时 | 备注 |\n|-------|-----------------|-------|\n| 用户设置 | 10–15 秒 | 快速，主要进行检查 |\n| 文件系统 | 5–10 秒 | 创建目录 |\n| Shell 设置 | 2–4 分钟 | Oh-My-Zsh 的克隆安装速度较慢 |\n| CLI 工具 | 3–5 分钟 | 需要安装大量 apt 包 |\n| 编程语言 | 3–5 分钟 | Rust 编译耗时最长 |\n| 代理 | 1–2 分钟 | Bun 安装速度快 |\n| 云服务 | 1–2 分钟 | Bun 安装速度较快 |\n| 构建栈 | 4–6 分钟 | Cargo 编译耗时较长 |\n| 最终完成 | 30–60 秒 | 配置部署 |\n| **总时长** | **15–25 分钟** | **典型完整安装** |\n\n### 影响速度的因素\n\n| 因素 | 影响 | 优化方案 |\n|--------|--------|--------------|\n| 网络延迟 | 较高 | 选择靠近软件包镜像的 VPS |\n| 磁盘 I\u002FO | 中等 | 建议使用 SSD 或 NVMe |\n| CPU 核心 | 中等 | 更多核心意味着更快的编译速度 |\n| 内存 | 低 | 4GB 即可满足需求 |\n| 提供商 | 可变 | OVH 和 Contabo 提供了极佳的性价比 |\n\n### 恢复性能\n\n从检查点恢复的速度非常快，因为已完成的阶段会被跳过：\n\n```\n完整安装：20 分钟\n从 50% 处恢复：10 分钟\n从 90% 处恢复：2 分钟\n```\n\n---\n\n## 许可证\n\nMIT 许可证（附带 OpenAI\u002FAnthropic Rider）。详情请参阅 [LICENSE](LICENSE)。\n\n---\n\n## 链接\n\n- **官网**：[agent-flywheel.com](https:\u002F\u002Fagent-flywheel.com) — 专为初学者设计的交互式向导\n- **GitHub**：[Dicklesworthstone\u002Fagentic_coding_flywheel_setup](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup)\n- **相关项目**：\n - [ntm](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fntm) — 名为 Tmux 管理器\n - [beads_viewer](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer) — 任务管理 TUI\n - [mcp_agent_mail](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fmcp_agent_mail) — 代理协调\n - [cass](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search) — 代理会话搜索\n - [dcg](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fdestructive_command_guard) — 毁灭性命令守护者\n - [ru](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frepo_updater) — 仓库更新器\n\n---\n\n## 关于贡献\n\n请不要误会，我并不接受任何外部项目的贡献。我根本没有足够的心理精力去审核所有内容，而且这些项目都是以我的名字命名的，因此一旦出现问题，我将承担全部责任；从我的角度来看，这种风险与回报的比值极其不均衡。此外，我还必须担心其他“利益相关方”，而这似乎对于那些我大多免费为自己打造的工具来说并不明智。如果您有任何问题或建议，欢迎随时提交，甚至可以提交 PR 来说明您提出的修复方案，但请知悉，我不会直接合并这些提交。相反，我会让 Claude 或 Codex 通过 `gh` 对提交内容进行审查，并独立决定是否以及如何处理这些提交。尤其是错误报告，我们非常欢迎。如果这冒犯了您，我深表歉意，但我希望避免浪费时间、伤害彼此的感情。我理解这与当前开源社区倡导的社区贡献精神并不完全一致，但这是我以目前的速度推进项目、同时保持理智的唯一方式。\n\n---\n\n\u003Cdiv align=\"center\">\n \u003Csub>由 \u003Ca href=\"https:\u002F\u002Fx.com\u002Fdoodlestein\">Jeffrey Emanuel\u003C\u002Fa>（\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\">@Dicklesworthstone\u003C\u002Fa>) 为代理编码社区打造。\u003C\u002Fsub>\n\u003C\u002Fdiv>","# Agentic Coding Flywheel Setup (ACFS) 快速上手指南\n\n**ACFS** 是一个一键式引导系统，能在 30 分钟内将全新的 Ubuntu VPS 转化为专业的 AI 驱动开发环境。它自动安装 30+ 种开发工具、配置现代 Shell 环境，并部署三个主流 AI 编程助手（Claude Code, Codex CLI, Gemini CLI）。\n\n## 1. 环境准备\n\n在开始之前，请确保你拥有以下环境和资源：\n\n* **目标服务器 (VPS)**：\n * **操作系统**：必须是 **Ubuntu 25.10**（官方推荐版本，脚本会自动处理升级）。\n * **权限**：拥有 `root` 权限或具备 `sudo` 权限的用户。\n * **网络**：服务器需能访问 GitHub 及各大包管理器源（若在国内部署，建议配置国内镜像源以提升下载速度，见下文提示）。\n* **本地机器**：\n * 任意操作系统（Windows\u002FMac\u002FLinux），仅需具备终端（Terminal）和 SSH 客户端。\n * 用于通过 SSH 连接 VPS 并执行安装命令。\n\n> **💡 国内用户加速提示**：\n> 由于该工具主要拉取 GitHub 资源和国际软件源，在中国大陆地区的 VPS 上运行时，建议先手动替换 `apt`、`pip`、`npm` 等包管理器为国内镜像（如阿里云、清华大学镜像站），以避免超时失败。本安装脚本本身暂不内置国内镜像切换逻辑。\n\n## 2. 安装步骤\n\n### 步骤一：登录 VPS\n使用 SSH 连接到你的全新 Ubuntu VPS：\n```bash\nssh root@your_vps_ip\n```\n\n### 步骤二：执行一键安装\n复制并运行以下命令。该命令会自动下载最新安装脚本并以“极速模式”（Vibe Mode）运行，无需交互式确认。\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n> **注意**：\n> * **断点续传**：安装程序是**幂等**的。如果因网络中断导致安装失败，只需**重新运行上述命令**，它会自动从上次完成的阶段继续，不会重复操作。\n> * **生产环境锁定版本**：若需确保环境绝对稳定可复现，建议指定特定版本标签（例如 v0.5.0）：\n> ```bash\n> ACFS_REF=v0.5.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.5.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n> ```\n\n### 步骤三：等待完成\n脚本将自动执行以下操作（全程约 10-30 分钟，取决于网络状况）：\n1. 更新系统并安装基础依赖。\n2. 配置 Zsh + Oh My Zsh + Powerlevel10k 主题。\n3. 安装语言运行时（Bun, Python\u002Fuv, Rust, Go）。\n4. 部署 AI 代理工具（Claude Code, Codex CLI, Gemini CLI）。\n5. 安装协作与云工具（NTM, Vault, Wrangler 等）。\n6. 配置 `~\u002F.acfs\u002F` 目录及相关环境变量。\n\n当看到安装成功的提示信息后，重启终端或运行 `source ~\u002F.zshrc` 使配置生效。\n\n## 3. 基本使用\n\n安装完成后，你的 VPS 已转变为全功能的 AI 编码工作站。\n\n### 验证环境\n检查核心工具是否就绪：\n```bash\n# 检查 AI 代理是否可用\nclaude --version\ncodex --version\ngemini --version\n\n# 检查开发工具链\nbun --version\nuv --version\nrustc --version\n\n# 运行健康检查（诊断工具）\nacfs doctor\n```\n\n### 开始 AI 编程\n你现在可以直接调用 AI 代理进行开发工作。例如，让 Claude 在当前目录创建一个新项目：\n\n```bash\n# 示例：让 Claude Code 辅助编写代码\nclaude code \"Create a simple hello world web server using Bun\"\n```\n\n或者使用协调工具管理多个代理任务：\n```bash\n# 查看可用的 ACFS 命令\nacfs --help\n```\n\n### 新手引导\n如果你是第一次接触此类工作流，可以运行内置的上手教程：\n```bash\nonboard\n```\n\n现在，你已经拥有了一个由 AI 代理驱动的专业开发环境，可以开始构建项目了。","刚毕业的全栈开发者小林想利用闲置预算租用一台 Ubuntu VPS，构建一个能 24 小时自动迭代代码的 AI 开发环境，但面对复杂的依赖配置感到无从下手。\n\n### 没有 agentic_coding_flywheel_setup 时\n- **环境搭建耗时极长**：手动安装 Node、Python、Rust 等运行时及配置 Zsh 主题，往往需要耗费整个下午甚至更久，期间极易因版本冲突报错。\n- **多智能体协调困难**：想要同时运行 Claude Code、Codex 和 Gemini 三个代理，需分别配置 API 密钥、权限和安全策略，缺乏统一的调度基础设施。\n- **安全与效率难以平衡**：为了安全不敢开启自动化所需的高权限，而手动配置 `sudo` 免密和危险标志又担心误操作导致系统崩溃。\n- **工具链碎片化**：需要单独寻找并安装云厂商 CLI（如 Vercel、Supabase）和会话管理工具，导致工作流割裂，无法形成闭环。\n\n### 使用 agentic_coding_flywheel_setup 后\n- **30 分钟一键就绪**：只需运行一条 `curl` 命令，即可自动完成所有语言运行时、现代 Shell 环境及 30+ 开发工具的安装与配置。\n- **预置多智能体协作**：自动部署并协调 Claude、Codex、Gemini 三大编码代理，内置 NTM 和 MCP Agent Mail 等工具，让智能体即刻开始协同写码。\n- **\"Vibe 模式”加速开发**：默认启用针对高流速开发优化的安全配置（如免密 sudo），在保障基础安全的前提下最大化自动化执行效率。\n- **完整生态集成**：一次性集成的 Dicklesworthstone 工具栈涵盖了从云端部署到本地会话管理的全流程，无需再为缺失组件四处搜索。\n\nagentic_coding_flywheel_setup 将原本数天的环境筹备工作压缩至半小时，让开发者能立即从“配置环境”转向“让 AI 代理自动编写代码”的核心价值创造中。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_agentic_coding_flywheel_setup_38f71d2a.webp","Dicklesworthstone","Jeff Emanuel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FDicklesworthstone_c96b6d22.jpg","Building in NY",null,"doodlestein","https:\u002F\u002Fwww.jeffreyemanuel.com\u002F","https:\u002F\u002Fgithub.com\u002FDicklesworthstone",[84,88,92,96],{"name":85,"color":86,"percentage":87},"TypeScript","#3178c6",65,{"name":89,"color":90,"percentage":91},"Shell","#89e051",34.1,{"name":93,"color":94,"percentage":95},"JavaScript","#f1e05a",0.6,{"name":97,"color":98,"percentage":99},"CSS","#663399",0.3,1369,163,"2026-04-05T03:37:47","NOASSERTION","Linux (Ubuntu 25.10)","未说明",{"notes":107,"python":108,"dependencies":109},"该工具是一个用于在全新 Ubuntu VPS 上快速搭建 AI 代理编码环境的自动化脚本。它不依赖本地 GPU，而是通过 SSH 连接远程服务器进行部署。支持一键安装 30+ 开发工具及三个 AI 编程代理（Claude Code, Codex CLI, Gemini CLI）。安装过程具有幂等性，中断后可重新运行自动续传。建议生产环境使用特定的发布标签或提交哈希以确保稳定性。","未说明 (自动安装 uv\u002FPython 运行时)",[110,111,112,113,114,115,116,117,118,119],"zsh","oh-my-zsh","powerlevel10k","bun","uv","Rust","Go","tmux","ripgrep","gh",[15],[122,123,124,125,126],"agentic-ai","agentic-workflow","agentmail","beads","bv","2026-03-27T02:49:30.150509","2026-04-06T05:27:03.234835",[130,135,139,144,148,153],{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},6490,"在 Ubuntu 上安装 ACFS 时遇到 'checksum mismatch for uv' 校验和不匹配错误怎么办？","该错误通常是由于网络问题或上游脚本更新导致本地校验和过期。解决方法如下：\n1. 如果是旧版本，尝试更新 ACFS 堆栈以获取最新的校验和文件：运行 `acfs update --stack`。\n2. 如果更新后仍失败，可能是临时网络波动，请检查网络连接 (`curl -I https:\u002F\u002Fgoogle.com`) 后重试安装。\n3. 维护者指出，在 ACFS v0.2.0+ 及更高版本中已优化相关逻辑，确保使用最新版本可避免此类问题。\n注意：不要手动跳过校验，这会导致安全风险。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fissues\u002F22",{"id":136,"question_zh":137,"answer_zh":138,"source_url":134},6491,"安装过程中出现 'do-release-upgrade failed' 或 locale 设置不支持的错误如何解决？","此问题通常由 Ubuntu 系统的 locale 配置缺失引起，导致升级脚本无法正确设置编码。解决步骤：\n1. 手动运行 `sudo locale-gen en_US.UTF-8` 和 `sudo update-locale LANG=en_US.UTF-8` 生成并设置正确的 locale。\n2. 重新登录 SSH 会话以确保环境变量生效。\n3. 再次运行安装程序，或手动执行 `sudo do-release-upgrade` 测试是否修复。\n评论中提到，直接在 gcloud SSH 会话中运行时可能因权限或环境问题失败，建议在标准用户环境下操作。",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},6492,"NTM Dashboard 显示 'context deadline exceeded' 错误且 tmux 响应缓慢怎么办？","这是由于 NTM 默认的超时时间过短（2 秒），在性能较低的 VPS 或 tmux 面板较多时无法及时获取数据。解决方案：\n1. 更新 NTM 到 v1.3.0 或更高版本，该版本已将会话数据获取超时从 2 秒增加到 8 秒，状态检测超时从 3 秒增加到 6 秒。\n2. 运行命令 `acfs update --stack` 自动更新整个堆栈。\n3. 如果暂时无法更新，可尝试在非 tmux 会话中（即直接 SSH 登录后）运行 NTM 命令作为临时规避方案。\n4. 运行 `acfs doctor --deep` 诊断 tmux 响应速度，确认是否为底层 tmux 服务问题。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fissues\u002F20",{"id":145,"question_zh":146,"answer_zh":147,"source_url":143},6493,"如何诊断 NTM Dashboard 连接问题是来自 ACFS 还是上游 NTM？","请在非 tmux 会话中（新建 SSH 连接）运行以下诊断命令：\n1. 检查版本：`ntm --version` 和 `tmux -V`。\n2. 测试 tmux 响应速度：运行 `time tmux list-sessions` 和 `time tmux list-panes -a`。如果耗时超过 1-2 秒，说明是 tmux 服务端本身的问题；如果低于 200ms 但 NTM 仍报错，则是 NTM 的 bug。\n3. 检查 socket 状态：`ls -la \u002Ftmp\u002Ftmux-*`。\n4. 运行深度诊断：`acfs doctor --deep`（该命令包含专门的 tmux 响应探针）。\n根据结果决定是重启 tmux 服务还是更新 NTM 组件。",{"id":149,"question_zh":150,"answer_zh":151,"source_url":152},6494,"运行 'ntm send' 时出现 'cass execution failed: unrecognized subcommand robot' 错误如何解决？","这是因为新版 CASS 改变了命令行参数格式（从 `cass robot \u003Ccmd>` 改为 `cass \u003Ccmd> --robot`），而旧版 NTM 仍在调用旧格式。解决方法：\n1. 更新 ACFS 到 v0.2.0+ 版本，该版本内置了兼容包装器（wrapper script），可自动转换命令格式。\n2. 运行 `acfs update --stack` 更新所有组件，确保 NTM 版本 >= 7ed3688。\n3. 更新后，`ntm send` 命令即可正常工作，无需再添加 `--no-cass-check` 参数。\n如果无法立即更新，临时解决方案是使用支持旧格式的 NTM 标签版本，或手动修改调用逻辑。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fissues\u002F15",{"id":154,"question_zh":155,"answer_zh":156,"source_url":134},6495,"ACFS 安装失败后如何查看日志并进行调试？","当安装失败时，请按以下步骤调试：\n1. 查看详细安装日志：`cat \u002Fvar\u002Flog\u002Facfs\u002Finstall.log`。\n2. 运行健康检查工具：`acfs doctor` 或更深入的 `acfs doctor --deep`。\n3. 检查系统资源：使用 `df -h` 确认磁盘空间充足，使用 `journalctl -xe` 查看系统级错误。\n4. 验证网络连通性：`curl -I https:\u002F\u002Fgoogle.com`。\n5. 安装程序支持多次重跑，修复上述问题后可直接重新运行安装脚本，它是幂等安全的。",[158,163,168,173,178,183],{"id":159,"version":160,"summary_zh":161,"released_at":162},106069,"v0.6.0","## Changes\n\n### Breaking Changes\n- Removed `bd` alias for `br` (beads_rust) - use `br` directly\n\n### New Features\n- **br alias guard**: Automatically removes stale `alias br='bun run'` from older ACFS versions\n - Uses `whence -p br` to detect binary vs alias (zsh-specific)\n - Ensures `br` command always points to beads_rust binary\n\n### Migrations\n- All `bd` references migrated to `br` across:\n - Shell config (acfs.zshrc)\n - Web app lessons and tutorials\n - Installer scripts (newproj, doctor, screens)\n - CLI flags (`--no-bd` → `--no-br`)\n - Environment variables (`AGENTS_ENABLE_BD` → `AGENTS_ENABLE_BR`)\n - State variables (`enable_bd` → `enable_br`)\n - Test suites\n\n### Bug Fixes\n- Fixed mock function in test_newproj_errors.bats using wrong function name\n- Fixed shellcheck SC1087 in test_new_tools_e2e.sh\n\n### Notes\n- Bead IDs (bd-XXXX) are preserved as historical identifiers\n- Upgrading users should re-source their shell or restart terminal","2026-02-02T23:37:07",{"id":164,"version":165,"summary_zh":166,"released_at":167},106070,"v0.5.0","# ACFS v0.5.0 - DCG & RU Integration Release\n\nThis release completes the integration of **DCG (Destructive Command Guard)** and **RU (Repo Updater)** as first-class citizens in the ACFS ecosystem, along with significant improvements to the onboarding experience, web application stability, and security.\n\n## Highlights\n\n### DCG (Destructive Command Guard) - Full Integration\n- Complete DCG integration across website, installer, and onboarding\n- New DCG lesson in onboarding TUI\n- DCG added to flywheel loop lesson and safety-tools-lesson\n- Comprehensive DCG test suite with 88+ passing tests\n- DCG doctor and update verification tests\n- Allow-once workflow tests\n- Pack configuration validation tests\n- DCG+SLB layered safety integration tests\n\n### RU (Repo Updater) - Full Integration\n- RU tool page added to learn section\n- RU lesson component with structural tests\n- E2E Playwright tests for RU pages\n- RU integrated into Installer CI workflow\n- Multi-repo sync and AI-driven commit automation documentation\n\n### Enhanced Onboarding TUI\n- **File locking for concurrent operations** - Prevents race conditions in progress tracking\n- **Dynamic lesson counts** - `NUM_LESSONS` derived from array length for maintainability\n- New lessons: RU and DCG\n- Updated certificate and help text with RU\u002FDCG skills\n- Lesson count properly updated from 9 to 11\n\n### Web Application Improvements\n- **Error boundary for lesson rendering** - Catches JavaScript errors and shows user-friendly recovery UI\n- **IPv6 zone ID validation security fix** - Rejects zone IDs (like `%eth0`) that are meaningless for remote VPS connections\n- `maxDelay` cap for stagger animations\n- Accessibility: Button respects `prefers-reduced-motion` setting\n- Tool page split into server and client components\n\n### Security Improvements\n- Category name validation in manifest to prevent injection\n- Checksum auto-updates for `uv` and `claude`\n- Error handling improvements in `acfs_chown_tree`\n- State write atomic error capture fixes\n\n### Test Infrastructure\n- Comprehensive DCG test suite\n- RU integration tests\n- E2E Playwright tests for DCG and RU pages\n- Unit tests for flywheel.ts\n- Improved test reliability and TTY handling\n\n## Bug Fixes\n- Fixed manifest cycle detection consolidation (removed duplicate implementation)\n- Removed unused `fallback_url` field from manifest schema\n- Fixed path normalization in `screen_directory.sh`\n- Fixed upgrade detection for LTS version format\n- Fixed nested hook structures in DCG removal\n- Various shell script reliability improvements\n\n## Breaking Changes\nNone - this release is backwards compatible.\n\n## Upgrade Instructions\n```bash\n# One-liner update\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Fscripts\u002Fupdate.sh | bash\n```\n\n## Contributors\n- Claude Opus 4.5 (AI Assistant)\n\n---\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fcompare\u002Fv0.4.0...v0.5.0","2026-01-11T18:42:00",{"id":169,"version":170,"summary_zh":171,"released_at":172},106071,"v0.4.0","## New Flywheel Tools\n\n### destructive_command_guard (dcg) - Tool #9\nRust-based Claude Code PreToolUse hook that blocks dangerous git\u002Ffs commands with sub-millisecond latency. Replaces the simpler Python-based approach.\n- Blocks: recursive deletions, force pushes, hard resets, etc.\n- Auto-bypass for confirmed intention\n- \u003C1ms hook latency via native Rust binary\n\n### repo_updater (ru) - Tool #10 \n17K-line Bash tool for multi-repo sync + AI-driven commit automation.\n- Batch sync multiple repos with smart stash handling\n- AI-powered commit message generation\n- Interactive commit review\u002Fediting\n\n## New Utilities\n\n### giil (Get Image from Internet Link)\nDownloads cloud-hosted images (iCloud, Dropbox, Google Photos) for visual debugging in SSH\u002Fheadless environments where clipboard isn't available.\n\n### csctf (Chat Shared Conversation to File)\nConverts AI chat share links (Claude, ChatGPT, Grok) to Markdown\u002FHTML archives with full formatting preservation.\n\n## Changes\n- Updated all documentation to reflect 10-tool stack\n- Added checksums for all 4 new installers (security.sh verified)\n- Regenerated installer scripts from manifest\n- Updated web app tool counts throughout\n\n## Full Changelog\nhttps:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fcompare\u002Fv0.3.0...v0.4.0","2026-01-08T08:01:50",{"id":174,"version":175,"summary_zh":176,"released_at":177},106072,"v0.3.0","## 🎉 ACFS v0.3.0 - TUI Wizard & Security Release\n\nThis release introduces a complete interactive TUI wizard for project creation, comprehensive test infrastructure, and includes a critical security fix.\n\n---\n\n## 🔒 Security\n\n### Critical Fix: Command Injection Vulnerability\n- **Fixed command injection in `validate_directory()`** - The previous implementation used `eval echo \"$dir\"` for tilde expansion, which could allow arbitrary command execution if a malicious path was entered\n- **New safe implementation** uses pattern matching for `~` and `~\u002Fpath` expansion without `eval`\n- Commit: `6c6e899`\n\n---\n\n## ✨ Features\n\n### Complete TUI Wizard for Project Creation\nThe `newproj` command now supports a full interactive TUI mode with 9 screens:\n\n| Screen | Description |\n|--------|-------------|\n| Welcome | Introduction with keyboard navigation hints |\n| Project Name | Input with real-time validation |\n| Directory | Path selection with tilde expansion |\n| Tech Stack | Auto-detection + manual selection |\n| Features | Toggle AGENTS.md, beads, Claude settings |\n| AGENTS.md Preview | Live preview with syntax highlighting |\n| Confirmation | Review all settings before creation |\n| Progress | Real-time creation progress |\n| Success | Summary with next steps |\n\n**Usage:**\n```bash\nnewproj --interactive # or -i\nnewproj myproject .\u002Fpath # CLI mode (non-interactive)\n```\n\n### Smart AGENTS.md Generation\n- **Tech stack detection** for Python, Node.js, Rust, Go, Ruby, PHP, Java\n- **Context-aware sections** based on detected technologies\n- **Best practices** tailored to each stack\n\n### Testing Infrastructure\n- **284 unit tests** using bats-core framework\n- **53 E2E tests** covering happy paths, navigation, and error recovery\n- **Expect-based TUI testing** for full interactive workflow verification\n- Test helpers: `verify_project_created`, `verify_feature_enabled`, screen matchers\n\n---\n\n## 🐛 Bug Fixes\n\n### TUI Wizard Fixes\n- Fixed ASCII box alignment in welcome screen\n- Fixed file tree rendering for nested paths\n- Fixed tech stack display name in confirmation screen\n- Added missing `.gitignore` to success screen\n- Fixed safe arithmetic increment to avoid `set -e` issues\n- Handle unconfigured git user gracefully\n\n### Test Suite Fixes\n- Fixed strict mode violations\n- Resolved flaky navigation test timing\n- Fixed test helper quoting issues\n\n### Other Fixes\n- Corrected SSH keepalive check in doctor\n- Fixed Claude auth and PostgreSQL role checks\n- Corrected `bd` install message in newproj\n\n---\n\n## 📚 Documentation\n\n- **TUI Wizard Design Document** with ASCII mockups\n- **Research findings** for terminal UI best practices\n- Comprehensive test README with usage examples\n\n---\n\n## 📦 Installation\n\n### Fresh Install (Recommended)\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n### Pin to v0.3.0\n```bash\nACFS_REF=v0.3.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.3.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n```\n\n### Update Existing Installation\n```bash\nacfs update --all\n```\n\n---\n\n## 📊 Commits Since v0.2.0\n\n| Type | Count |\n|------|-------|\n| Security | 1 |\n| Features | 11 |\n| Bug Fixes | 13 |\n| Documentation | 2 |\n| Chores | 1 |\n| **Total** | **28** |\n\n---\n\n## 🧪 Test Coverage\n\n```\nUnit Tests: 284 passing\nE2E Tests: 53 passing (16 with expect, 37 CLI-only)\n```\n\n---\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fcompare\u002Fv0.2.0...v0.3.0\n","2026-01-07T07:59:32",{"id":179,"version":180,"summary_zh":181,"released_at":182},106073,"v0.2.0","## 🎉 ACFS v0.2.0 - Documentation & Polish Release\n\nThis release focuses on comprehensive documentation, shell UX improvements, and agent configuration fixes. The README has been expanded by over 1,000 lines with detailed explanations of every system component.\n\n---\n\n## ✨ Features\n\n### Shell Experience Enhancements\n- **6 New Oh-My-Zsh Plugins** included by default:\n | Plugin | Purpose |\n |--------|---------|\n | `python` | Python aliases (pyfind, pyclean, pygrep) |\n | `pip` | pip completion and cache management |\n | `tmux` | tmux aliases (ta, tad, ts, tl, tkss) |\n | `tmuxinator` | tmuxinator project completion |\n | `systemd` | systemctl aliases (sc-status, sc-start) |\n | `rsync` | rsync completion and common flags |\n\n### Analytics\n- Comprehensive GA4 acquisition tracking\n- Diagnostic tools for analytics debugging\n\n---\n\n## 🐛 Bug Fixes\n\n### Agent Configuration\n- **Gemini CLI**: Fixed tmux compatibility issues with terminal detection\n- **Gemini CLI**: Corrected heredoc syntax and file ownership bugs\n- **jq Handling**: Fixed alternative operator (`\u002F\u002F`) treating `false` as falsy\n\n### CI\u002FCD\n- Resolved YAML lint warnings in workflow files\n- Fixed shellcheck issues in installer scripts\n- Corrected SSH key TTY handling for non-interactive environments\n\n### E2E Tests\n- Fixed strict mode violations in test suite\n- Resolved flaky navigation test timing issues\n\n---\n\n## 📚 Documentation\n\nThe README has been massively expanded with detailed technical documentation:\n\n### New Sections Added\n- **Tmux Configuration Deep Dive**: Agent workflow optimizations, vim-style copy mode, Catppuccin theme details\n- **Wizard State Management**: TanStack Query architecture with optimistic updates and cross-tab sync\n- **Generated Manifest Index**: Bash associative arrays for runtime module metadata\n- **Jargon Component**: Responsive tooltip system (desktop hover, mobile bottom sheet)\n- **Shell Keybindings**: Quality of life bindings reference table\n- **Learning Hub**: 10 interactive lessons with completion tracking\n- **CI\u002FCD Automation**: Checksum monitoring, production smoke tests, Playwright E2E\n- **Provider Guides**: Contabo, OVH, Hetzner comparison with recommendations\n- **Validation System**: Error codes, Tarjan's SCC algorithm for cycle detection\n- **Test Harness**: harness_* API documentation for integration testing\n\n### Documentation Stats\n- ~1,000+ new lines of documentation\n- 4 comprehensive README commits\n- Every major system component now documented\n\n---\n\n## 🔧 Maintenance\n\n- **refactor(cass)**: Removed obsolete robot wrapper code\n- **chore(security)**: Multiple upstream checksum auto-updates for cass, uv, cm\n\n---\n\n## 📦 Installation\n\n### Fresh Install (Recommended)\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --mode vibe\n```\n\n### Pin to v0.2.0\n```bash\nACFS_REF=v0.2.0 curl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fv0.2.0\u002Finstall.sh\" | bash -s -- --yes --mode vibe\n```\n\n### Update Existing Installation\n```bash\nacfs update --all\n```\n\n---\n\n## 📊 Commits Since v0.1.0\n\n| Type | Count |\n|------|-------|\n| Features | 2 |\n| Bug Fixes | 6 |\n| Documentation | 4 |\n| Refactoring | 1 |\n| Security\u002FChecksums | 7 |\n| **Total** | **19** |\n\n---\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup\u002Fcompare\u002Fv0.1.0...v0.2.0","2026-01-06T19:59:52",{"id":184,"version":185,"summary_zh":186,"released_at":187},106074,"v0.1.0","# ACFS v0.1.0 - Initial Release\n\nThe first public release of the Agentic Coding Flywheel Setup (ACFS) installer.\n\n## What is ACFS?\n\nACFS is a comprehensive installer for setting up an AI-powered development environment. It provides:\n\n- **Three-tier agent system**: Claude Code, Codex CLI, and Gemini CLI\n- **Named tmux manager (NTM)**: Agent cockpit for managing coding sessions\n- **Unified session search (CASS)**: Search across all agent session history\n- **Procedural memory (CM)**: Agent memory system for persistent context\n- **Auth switching (CAAM)**: Instant switching between different API keys\n- **Security guardrails (SLB)**: Two-person rule for dangerous commands\n- **Interactive onboarding**: Tutorial to get started quickly\n- **Self-healing `acfs doctor`**: Diagnose and fix issues automatically\n\n## Installation\n\n```bash\ncurl -fsSL https:\u002F\u002Fagent-flywheel.com\u002Finstall | bash\n```\n\n## Recent Fixes\n\n- **CASS wrapper installation**: Fixed detection of when the CASS robot compatibility wrapper needs to be installed (#25)\n- **CI workflow stability**: Fixed stderr corruption issues in checksum verification workflows\n- **Checksum verification**: Comprehensive E2E tests for the security checksum system\n- **Doctor improvements**: Added fix messages and headless authentication hints\n\n## Requirements\n\n- Ubuntu 24.04 or 25.04 (fresh install recommended)\n- At least 20GB free disk space\n- Internet connection for downloading tools\n\n## Documentation\n\nSee the [README](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fagentic_coding_flywheel_setup#readme) for full documentation.\n\n---\n\n🤖 Generated with [Claude Code](https:\u002F\u002Fclaude.com\u002Fclaude-code)","2026-01-03T19:26:04"]