diff --git a/docs/ANALYSIS_CN.md b/docs/ANALYSIS_CN.md new file mode 100644 index 0000000..e4f766a --- /dev/null +++ b/docs/ANALYSIS_CN.md @@ -0,0 +1,408 @@ +# Clawdinators 代码仓库技术方案分析 + +## 概述 + +Clawdinators 是一个双层架构的项目，它既是一个通用的 NixOS-on-AWS 基础设施即代码（IaC）参考实现，也是一个专门为运行 AI 编码代理（CLAWDINATOR agents）而设计的生产级部署系统。 + +## 核心定位 + +### 双层架构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CLAWDINATOR 层（特定应用） │ +│ Discord 网关 · GitHub 监控 · 蜂群记忆 · 个性化系统 │ +├─────────────────────────────────────────────────────────────────┤ +│ NixOS-on-AWS 层（通用基础设施） │ +│ AMI 管道 · OpenTofu 基础设施 · S3 引导 · agenix 密钥管理 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1. 通用层：NixOS-on-AWS 基础设施模式 + +这是一个**可重用的 NixOS 云部署模式**，适用于任何 AWS 工作负载： + +- **AMI 构建管道**：使用 nixos-generators 构建原始镜像，上传到 S3，导入为 AMI +- **OpenTofu 基础设施**：EC2 实例、S3 存储桶、IAM 角色、VM Import 服务角色 +- **引导流程**：实例启动时从 S3 拉取密钥，然后执行 `nixos-rebuild switch` +- **密钥管理**：使用 agenix 在 git 中加密密钥，在主机上解密到 `/run/agenix/*` + +### 2. 特定层：CLAWDINATOR AI 代理系统 + +基于通用层的特定应用实现，用于运行 AI 编码代理： + +- **Discord 网关**：在 `#clawdributors-test` 频道响应 +- **GitHub 集成**：监控 issues/PRs，通过 GitHub App 生成短期令牌 +- **蜂群记忆**：共享的 EFS 挂载，实现跨实例状态共享 +- **个性化系统**：SOUL.md、IDENTITY.md、工作区模板 +- **自动更新**：基于定时器的 flake 更新 + nixos-rebuild + +## 技术架构 + +### 系统组成 + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ nixos- │ │ S3 │ │ EC2 │ +│ generators │────▶│ (原始镜像) │────▶│ (AMI) │ +└──────────────┘ └──────────────┘ └──────────────┘ + │ │ + │ nix build │ launch + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ flake.nix │ │ CLAWDINATOR │ +│ + modules │ │ 实例 │ +└──────────────┘ └──────────────┘ + │ + ┌─────────────────┼─────────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ Discord │ │ GitHub │ │ EFS │ + │ 网关 │ │ 监控 │ │ (记忆) │ + └──────────┘ └──────────┘ └──────────┘ +``` + +### 部署流程 + +1. **构建**：nixos-generators 生成原始 NixOS 镜像 +2. **上传**：原始镜像上传到 S3 +3. **导入**：AWS VM Import 从 S3 对象创建 AMI +4. **启动**：OpenTofu 从 AMI 配置 EC2 实例 +5. **引导**：实例从 S3 下载密钥，运行 `nixos-rebuild switch` +6. **运行**：网关启动，连接到 Discord，监控 GitHub + +### 技术栈 + +#### 基础设施即代码 +- **Nix/NixOS**：声明式系统配置和包管理 +- **nixos-generators**：生成各种格式的 NixOS 镜像（raw、qcow2 等） +- **OpenTofu**：开源的 Terraform 替代品，用于 AWS 资源管理 +- **agenix**：基于 age 加密的 NixOS 密钥管理 + +#### 云平台 +- **AWS EC2**：虚拟机实例 +- **AWS S3**：镜像存储和引导包存储 +- **AWS EFS**：共享文件系统（用于蜂群记忆） +- **AWS IAM**：权限和角色管理 +- **AWS VM Import**：将磁盘镜像转换为 AMI + +#### 运行时 +- **openclaw/moltbot**：上游 AI 代理运行时 +- **Discord Gateway**：Discord 消息处理 +- **GitHub App**：GitHub API 集成，使用 JWT 认证 + +#### 开发工具 +- **devenv**：开发环境管理 +- **GitHub Actions**：CI/CD 管道 + +## 核心功能 + +### 1. 镜像构建与部署 + +#### 自动化 AMI 管道 +CI/CD 工作流（`.github/workflows/image-build.yml`）自动化整个流程： +1. 使用 Nix 构建 NixOS 镜像 +2. 上传到 S3 +3. 导入为 AMI +4. 通知部署就绪 + +#### 声明式配置 +所有配置都在 Git 中： +- `nix/hosts/clawdinator-1.nix` - 主机配置 +- `nix/modules/clawdinator.nix` - 服务模块 +- `infra/opentofu/aws/` - AWS 基础设施 + +### 2. 密钥管理 + +使用 agenix 实现安全的密钥管理： +- 密钥在 git 中加密存储 +- 使用 SSH 密钥进行加密/解密 +- 在主机启动时解密到 `/run/agenix/*` +- 永远不会将明文密钥提交到仓库 + +### 3. AI 代理系统 + +#### CLAWDINATOR 规格 +- 命名为 `CLAWDINATOR-{1..n}` +- 连接到 Discord，初始在 `#clawdributors-test` 频道 +- 临时性实例，但共享记忆（蜂群思维） +- 只响应维护者 +- 可以与 GitHub 交互（至少需要只读权限） +- 必须监控 GitHub issues + PRs，引导人工注意 +- 可以为维护者编写和运行代码 +- 可以自我修改和自我部署 + +#### 个性化系统 +- `SOUL.md` - 定义 CLAWDINATOR 的个性和行为模式 +- `IDENTITY.md` - 身份配置 +- `workspace/` - 代理工作区模板 +- `skills/` - 技能模块（lurk、triage、landpr、fleet） + +#### 蜂群记忆 +共享记忆系统允许多个实例协同工作： +- `/var/lib/clawd/memory` - 挂载的 EFS 共享存储 +- `memory/project.md` - 项目目标 +- `memory/ops.md` - 运维手册 +- `memory/discord.md` - Discord 上下文 + +### 4. GitHub 集成 + +#### GitHub App 认证 +- 使用 GitHub App 而非个人访问令牌 +- 通过 JWT 签名生成短期安装令牌 +- 系统定时器自动刷新令牌（`clawdinator-github-app-token.timer`） + +#### 监控能力 +- 监控 issues 和 Pull Requests +- 代码审查能力 +- PR 管理（审批、关闭、请求更改） + +### 5. 自动更新 + +系统通过 systemd 定时器自动更新： +1. `flake lock --update-input nix-openclaw` +2. `nixos-rebuild switch` +3. 网关使用新版本重启 + +## 仓库结构 + +``` +clawdinators/ +├── nix/ +│ ├── modules/ +│ │ └── clawdinator.nix # 主要的 NixOS 模块 +│ ├── hosts/ +│ │ ├── clawdinator-1.nix # 主机配置 +│ │ └── clawdinator-1-image.nix # 镜像构建配置 +│ └── tools/ +│ └── clawdinator-tools.nix # 工具包定义 +├── infra/ +│ └── opentofu/ +│ └── aws/ # S3 + IAM + VM Import + EC2 +├── scripts/ +│ ├── build-image.sh # 构建原始 NixOS 镜像 +│ ├── upload-image.sh # 上传到 S3 +│ ├── import-image.sh # 导入为 AMI +│ └── upload-bootstrap.sh # 上传密钥 + seeds +├── clawdinator/ +│ └── workspace/ # 代理工作区模板 +│ ├── SOUL.md +│ ├── IDENTITY.md +│ └── skills/ # 技能模块 +├── memory/ # 蜂群思维模板 +│ ├── project.md +│ ├── ops.md +│ └── discord.md +├── docs/ +│ ├── PHILOSOPHY.md # 哲学理念 +│ ├── ARCHITECTURE.md # 架构文档 +│ ├── SHARED_MEMORY.md # 共享记忆系统 +│ └── SECRETS.md # 密钥管理 +└── flake.nix # Nix flake 入口 +``` + +## 姊妹仓库 + +### 三仓库系统 + +| 仓库 | 角色 | +|------|------| +| [openclaw](https://github.com/openclaw/openclaw) | 上游运行时 + 网关 | +| [nix-openclaw](https://github.com/openclaw/nix-openclaw) | clawbot 的 Nix 打包 | +| [clawdinators](https://github.com/openclaw/clawdinators) | 基础设施、NixOS 配置、密钥连接、部署流程 | + +### 其他相关仓库 + +| 仓库 | 用途 | +|------|------| +| [clawhub](https://github.com/openclaw/clawhub) | 公共技能注册表 | +| [ai-stack](https://github.com/joshp123/ai-stack) | 公共代理默认配置 + 技能 | + +## 设计哲学 + +### 核心原则 + +1. **声明式优先**：CLAWDINATOR 可以用单条命令引导另一个 CLAWDINATOR +2. **禁止手动编辑主机**：仓库 + agenix 密钥是唯一真相来源 +3. **仅基于镜像**：无 SSH、无就地漂移、无宠物（cattle not pets） +4. **自动更新**：CLAWDINATOR 自我维护 + +### Moltbot 之禅 + +``` +美观优于丑陋 +显式优于隐式 +简单优于复杂 +复杂优于繁琐 +扁平优于嵌套 +稀疏优于密集 +可读性很重要 +特例不足以打破规则 +尽管实用性胜过纯粹性 +错误永远不应默默传递 +除非明确沉默 +面对歧义，拒绝猜测的诱惑 +应该有一种——最好只有一种——明显的方法来做 +``` + +## 使用场景 + +### 场景 1：NixOS 云部署学习 + +对于想要学习 NixOS-on-AWS 模式的人： +- 研究 AMI 构建管道 +- 学习如何使用 OpenTofu 管理云资源 +- 了解声明式基础设施 +- 参考 `nix/modules/clawdinator.nix` 学习 NixOS 模块编写 + +### 场景 2：AI 代理部署 + +对于 openclaw 维护者部署实际的 CLAWDINATOR： +- 24/7 监控 openclaw 仓库 +- 在 Discord 上响应维护者请求 +- 跨实例共享上下文（蜂群思维） +- 无需人工干预的自动更新 +- 一致的个性和能力 + +### 场景 3：基础设施即代码参考 + +对于云基础设施工程师： +- 完整的端到端 IaC 示例 +- Nix + OpenTofu 集成模式 +- 密钥管理最佳实践（agenix） +- CI/CD 自动化示例 + +## 关键优势 + +### 1. 零漂移保证 +- 每次部署都是新的 AMI +- 不可能有未记录的手动更改 +- 仓库是单一真相来源 + +### 2. 可复现性 +- 相同的配置 = 相同的系统 +- 所有依赖都被锁定（flake.lock） +- Nix 确保构建的确定性 + +### 3. 安全性 +- 密钥永远不会以明文形式出现在仓库中 +- 使用 SSH 密钥加密（agenix） +- GitHub App 令牌而非长期个人令牌 +- 定期自动令牌刷新 + +### 4. 可维护性 +- 声明式配置易于理解 +- 模块化架构 +- 清晰的关注点分离（通用 vs 特定） +- 自文档化的 Nix 配置 + +### 5. 自动化 +- CI/CD 管道自动构建和发布 +- 自动更新系统 +- 自动密钥刷新 +- 引导过程完全自动化 + +## 部署工作流 + +### 本地开发到生产的完整 SDLC + +1. **解密 AWS 凭证**（homelab admin）并导出 +2. **推送到 `main`** 触发 AMI 构建（`.github/workflows/image-build.yml`） +3. **监视 CI** 获取 AMI ID +4. **从新 AMI 重新部署**（实例替换） +5. **获取新 IP** 并 SSH 验证 +6. **部署后健康检查** + +### 关键命令 + +```bash +# 构建镜像 +nix build .#packages.x86_64-linux.clawdinator-image-system + +# 应用基础设施 +cd infra/opentofu/aws +tofu init +tofu apply + +# 获取最新 AMI +aws ec2 describe-images --region eu-central-1 --owners self \ + --filters "Name=tag:clawdinator,Values=true" \ + --query "Images | sort_by(@,&CreationDate)[-1].[ImageId,Name,CreationDate]" + +# 检查服务状态 +systemctl is-active clawdinator +systemctl is-active clawdinator-github-app-token.timer +``` + +## 安全考虑 + +### 必需的密钥 + +| 密钥 | 用途 | +|------|------| +| Discord bot token | 网关认证 | +| Anthropic API key | Claude 模型 | +| OpenAI API key | GPT/Codex 模型 | +| GitHub App private key | 短期安装令牌 | +| agenix host key | 实例上的解密 | + +### 引导包 + +引导服务在首次启动时从 S3 下载： +``` +s3://bucket/bootstrap/clawdinator-1/ +├── secrets/ # agenix 加密的文件 +├── repos/ # git 仓库 seeds +└── config.json # 实例元数据 +``` + +## 性能和可扩展性 + +### 多实例支持 +- 通过 EFS 共享文件系统支持多个实例 +- 每个实例都是独立的，但共享记忆 +- 可以水平扩展以处理更多负载 + +### 资源优化 +- Nix 存储去重 +- 声明式依赖管理 +- 最小化镜像大小 + +## 限制和注意事项 + +1. **AWS 专用**：当前实现仅支持 AWS（可扩展到其他云提供商） +2. **x86_64 优先**：主要针对 x86_64-linux（但支持 aarch64-linux） +3. **学习曲线**：需要 Nix 知识 +4. **区域特定**：EFS 在单一 AWS 区域内 + +## 未来方向 + +基于文档和代码，可能的增强方向： +1. 多区域支持 +2. 高可用性配置 +3. 更多云提供商（GCP、Azure） +4. 增强的监控和可观测性 +5. 额外的技能模块 + +## 总结 + +Clawdinators 是一个雄心勃勃的项目，它展示了： +- 如何使用 Nix 实现真正的声明式云基础设施 +- 如何构建可维护、可复现的 AI 代理系统 +- 如何实现零漂移、镜像化的部署 +- 如何将通用模式与特定应用优雅地分层 + +它既是一个生产级的 AI 代理部署系统，也是学习现代 DevOps 实践的优秀参考实现。通过严格的声明式方法和"cattle not pets"哲学，它展示了云原生基础设施的最佳实践。 + +## 参考资源 + +- [NixOS 官方文档](https://nixos.org/manual/nixos/stable/) +- [OpenTofu 文档](https://opentofu.org/docs/) +- [agenix 仓库](https://github.com/ryantm/agenix) +- [nixos-generators](https://github.com/nix-community/nixos-generators) +- [AWS VM Import 文档](https://docs.aws.amazon.com/vm-import/) + +--- + +*文档生成于 2026-02-04* +*基于 clawdinators 仓库代码和文档分析*