admin

管理 - 本地机器伴侣（Alpha）

脚本路径解析：Claude Code 加载此文件时，会提供完整路径。以下所有 scripts/ 引用均相对于此文件所在目录。根据此文件的路径推导 SKILL_DIR，并在运行脚本时将其添加为前缀（例如，如果从 /path/to/skills/admin/SKILL.md 加载，则运行 /path/to/skills/admin/scripts/test-admin-profile.sh）。

---

配置文件检查 — 必须首先执行

执行任何操作前，先检查是否存在配置文件。没有配置文件就没有偏好设置、日志路径或状态。

Bash（WSL/Linux/macOS）：

scripts/test-admin-profile.sh

PowerShell（Windows）：

pwsh -NoProfile -File "scripts/Test-AdminProfile.ps1"

返回 JSON：{"exists":true|false,"path":"...","device":"...","platform":"..."}

如果 exists: false，则停止并先运行 TUI 设置访谈。 完整详情：references/profile-gate.md（发现、TUI 访谈、创建命令、故障排除）。

回退方案：脚本失败时

如果 Bash 和 PowerShell 测试脚本均失败（例如，shell 不可用、权限被拒绝、插件缓存中缺少脚本），请使用 Claude 原生工具直接检查：

1. 检查 satellite .env — 读取 ~/.admin/.env，获取 ADMIN_ROOT 和 ADMIN_DEVICE
2. 检查配置文件 JSON — 读取 $ADMIN_ROOT/profiles/$ADMIN_DEVICE.json
3. 如果两者均存在，则使用从这些文件中读取的值正常继续
4. 如果两者均不存在，则运行 TUI 设置访谈（参见 references/profile-gate.md）

---

关键：密钥和 .env

• 绝 NEVER 将有效的 .env 文件或凭据存储在任何技能文件夹中。
• .env.template 文件只能放在技能目录下的 assets/ 中。
• 将有效密钥存储在 ~/.admin/.env 中，并从该处引用。

密钥管理（v4.0 — 3 项目拆分）

密钥按信任边界分布在 3 个 Infisical 项目中，并采用文件夹层级结构：

项目	信任边界	内容
admin-operator	操作员	提供商密钥、大模型令牌、Cloudflare、Google 凭据
admin-runtime	运行时（受限范围）	Agent 机器人令牌、部署密码
customer-*	客户（隔离）	每位客户各自的 OpenClaw 配置

4 层模型：age 密钥 → 保管库（引导）→ Infisical Cloud（3 个项目）→ 生成的运行时文件

基于 URI 的访问（v4.0 新增）：

resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN"
secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN

旧版 CLI（仍可通过回退方案使用）：

secrets HCLOUD_TOKEN          # Falls back through: generated/.env → Infisical → vault → .env

运行时渲染：render-runtime.sh 从配置文件中解析所有 secretRefs/fileRefs，并写入 $ADMIN_ROOT/generated/.env，供不需要实时访问 Infisical 的脚本使用。

指南：references/secrets-architecture.md（完整模型）、references/infisical.md（设置）、references/vault-guide.md（回退方案）

架构

生态系统图

admin (core)
  ├── 9 satellite skills: devops, oci, hetzner, contabo, digital-ocean, vultr, linode, coolify, kasm
  ├── 7 agents: profile-validator, docs-agent, verify-agent, tool-installer, ops-bot, server-provisioner, deployment-coordinator
  ├── Profile system: ~/.admin/.env (satellite) → $ADMIN_ROOT/profiles/*.json (+ GitHub sync)
  └── Secrets: 3 Infisical projects (operator/runtime/customer) → vault (fallback) → .env (legacy)

数据流

Satellite .env (bootstrap)  →  profile.json (device config)  →  Agent decisions
        ↓                              ↓                              ↓
  ADMIN_ROOT, DEVICE,          tools, servers, prefs,          Session logs
  PLATFORM, SECRETS_BACKEND    secretRefs, fileRefs            (~/.admin/logs/)
        ↓                              ↓
  generated/.env (pre-rendered) → Infisical (3 projects) → vault.age → .env

• Satellite .env（~/.admin/.env）：每台设备的引导配置。指向 ADMIN_ROOT，并配置密钥后端。
• 根目录 .env（$ADMIN_ROOT/.env）：仅用于引导（ADMIN_ROOT、ADMIN_DEVICE、ADMIN_PLATFORM、ADMIN_SECRETS_BACKEND）。
• 配置文件 JSON（$ADMIN_ROOT/profiles/{DEVICE}.json）：完整的设备配置，包含 secretRefs（URI 指针）和 fileRefs。
• 项目配置（$ADMIN_ROOT/config/infisical-projects.json）：项目 slug → ID 映射。
• 生成文件（$ADMIN_ROOT/generated/.env、compat.env）：预先解析的密钥，供不需要实时访问 Infisical 的脚本使用。

Agent 名单

Agent	模型	角色	工具
profile-validator	haiku	JSON 验证、只读健康检查	Read, Bash, Glob
docs-agent	haiku	文件 I/O 文档更新	Read, Write, Glob, Grep
verify-agent	sonnet	系统健康检查，不使用 Write	Read, Bash, Glob, Grep
tool-installer	sonnet	根据配置文件偏好安装软件	Read, Write, Bash, AskUserQuestion
ops-bot	sonnet	多步骤操作（迁移、导入、批量配置）	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
server-provisioner	sonnet	跨云服务商配置云 VM	Read, Write, Bash, AskUserQuestion
deployment-coordinator	sonnet	端到端应用部署（Coolify、KASM）	Read, Write, Bash, AskUserQuestion

所有 Agent 都会将 profile gate 作为第一步运行。协作模式请参阅 references/agent-teams.md。

卫星依赖关系图

admin (core) ─── required by all satellites
  │
  ├── devops ─── required by provider + app skills
  │     │
  │     ├── oci, hetzner, contabo, digital-ocean, vultr, linode
  │     │        (provision servers)
  │     │              │
  │     └── coolify, kasm
  │           (deploy apps TO provisioned servers)
  │
  └── Profile system provides: server inventory, SSH keys, credentials (via vault)

• admin：核心配置文件、日志记录、工具安装。所有功能都依赖它。
• devops：服务器清单、SSH、部署协调。所有基础设施都依赖它。
• 服务商技能（oci、hetzner 等）：配置 VM。彼此独立。
• 应用技能（coolify、kasm）：将应用部署到服务器。需要服务商技能已配置的服务器。

任务资格判定（必须执行）

• 如果任务涉及远程服务器/VPS/云服务，请停止并移交给 devops。
• 如果任务是本地计算机管理，请继续。
• 如果情况不明确，请先提出澄清问题，再继续。

任务路由

任务	参考资料
安装工具/软件包	references/{platform}.md
Windows 管理	references/windows.md
WSL 管理	references/wsl.md
macOS/Linux 管理	references/unix.md
MCP 服务管理	references/mcp.md
技能注册表	references/skills-registry.md
密钥 / Infisical 设置	references/infisical.md
Vault（age 加密）	references/vault-guide.md
配置文件同步（GitHub）	references/remote-profile.md
远程服务器/云服务	→ 使用 devops 技能
devadmin 入门 / 迁移	references/devadmin-onboarding.md (/adopt-devadmin)
技能错误升级处理	references/escalation-policy.md

根据配置文件调整（始终检查偏好设置）

• Python：preferences.python.manager（uv/pip/conda/poetry）
• Node：preferences.node.manager（npm/pnpm/yarn/bun）
• 软件包：preferences.packages.manager（scoop/winget/choco/brew/apt）

未经检查偏好设置，切勿建议安装命令。

软件包安装工作流（所有平台）

1. 检测环境（Windows/WSL/Linux/macOS）
2. 通过 profile gate 加载配置文件
3. 检查工具是否已安装（profile.tools）
4. 使用首选软件包管理器
5. 记录操作

日志记录（必须执行）

使用共享辅助工具记录每项操作。

Bash — 参数：MESSAGE LEVEL（INFO|WARN|ERROR|OK）：

source scripts/log-admin-event.sh
log_admin_event "Installed ripgrep" "OK"

PowerShell — 参数：-Message -Level（INFO|WARN|ERROR|OK）：

pwsh -NoProfile -File "scripts/Log-AdminEvent.ps1" -Message "Installed ripgrep" -Level OK

注意：没有 -Tool、-Action、-Status 或 -Details 参数。请使用 -Message 并提供描述性字符串。

脚本 / 参考资料

• 核心脚本：scripts/（配置文件、日志记录、问题、AGENTS.md）
• MCP 脚本：scripts/mcp-*
• 技能注册表脚本：scripts/skills-*
• 参考资料：references/*.md

---

快速指引

• 跨平台指南：references/cross-platform.md
• Shell 检测：references/shell-detection.md
• 设备配置文件：references/device-profiles.md
• PowerShell 提示：references/powershell-commands.md
• Infisical 密钥：references/infisical.md
• 远程配置文件同步：references/remote-profile.md
• devadmin 入门/迁移：references/devadmin-onboarding.md（运行 /adopt-devadmin）