Perry Coding Agents

核心用法

perry-coding-agents 是一套基于 Tailscale 网络的远程开发代理调度系统，允许用户在隔离的 Perry 工作空间中部署 AI 编码助手（OpenCode 或 Claude Code）执行开发任务。核心工作流遵循 "调度 → 设置唤醒回调 → 定时跟进 → 清理" 的四步模式。

主要操作模式：

• 单次任务：通过 SSH 直接执行 opencode run 'task' 或 claude 'task'
• 后台任务：使用 nohup 后台运行，配合 HTTP 唤醒回调通知完成状态
• 批量 PR 审查：并行创建多个工作空间，同时审查多个 PR
• 并行 Issue 修复：每个 Issue 独立工作空间，完成后自动推送并创建 PR

关键配置要点：

• 项目目录位于 ~/<workspace-name>，非 /workspace
• 需动态获取 Tailscale IP 作为唤醒地址（tailscale status --self --json）
• 必须设置 20 分钟后的 cron 备用检查作为故障保护
• Claude Code 需要 -t TTY 标志，OpenCode 提供 4096 端口 Web UI

显著优点

| 优势 | 说明 |

|------|------|

| **网络隔离安全** | 基于 Tailscale 的私有网络，工作空间仅对授权用户可见 |

| **资源弹性扩展** | 可按需创建/销毁工作空间，支持"Army Mode"并行处理 |

| **异步工作流** | 后台任务 + 唤醒回调实现真正的异步开发，无需阻塞等待 |

| **故障保护机制** | 强制 cron 备份检查，避免任务静默失败 |

| **多代理选择** | OpenCode（有 Web UI）与 Claude Code 按需切换 |

潜在缺点与局限性

1. 网络依赖性强：完全依赖 Tailscale 网络连通性，MagicDNS 在容器内不可用，需使用 IP 地址
2. 环境配置门槛：需预先配置 gateway 认证令牌、理解 wake callback 机制
3. SSH 非登录 shell 限制：命令需使用完整路径（/home/workspace/.opencode/bin/opencode），环境变量可能缺失
4. 调试复杂度：分布式故障排查需要检查多个节点（工作空间状态、代理进程、日志、网络连通性）
5. 令牌管理风险：Bearer Token 在 SSH 命令中传递，存在 shell 历史记录泄露风险

适合人群

• 需要并行处理多任务的开发者（批量 PR 审查、多 Issue 修复）
• 重视环境隔离的团队（敏感代码、不可信依赖测试）
• 追求异步工作流的用户（长时任务无需保持连接）
• 已部署 Tailscale + Perry 基础设施的组织

常规风险

| 风险等级 | 场景 | 缓解措施 |

|---------|------|---------|

| **中** | 唤醒回调失败导致任务状态未知 | 强制 cron 20分钟备份检查 |

| **中** | SSH 命令注入（变量未转义） | 使用单引号包裹任务，避免 `$` 扩展 |

| **低** | Token 泄露于 shell 历史 | 使用配置文件或环境变量注入 |

| **低** | 工作空间残留消耗资源 | 规则3：任务专属空间必须 `perry remove` |

| **低** | 网络分区导致无法连接工作空间 | `tailscale ping` 预检，备用 IP 直连 |

核心用法

本 Skill 提供完整的远程开发工作流，通过 Perry 平台将编码任务分发至基于 Tailscale 的隔离工作空间。核心能力包括：

1. 工作空间生命周期管理：创建 (perry start)、SSH 接入、清理 (perry remove)
2. 双代理任务调度：OpenCode（带 Web UI 4096 端口）用于标准开发，Claude Code（需 TTY）用于特定能力场景
3. 异步任务编排：支持 Wake Callback 机制 — 任务完成后通过本地 HTTP 回调通知，配合 cron 备份检查
4. 批量处理模式："Army Mode" 支持多 PR/多 Issue 的并行工作空间创建与结果聚合

显著优点

• 网络隔离安全：全程基于用户私有 Tailnet，无公网暴露
• 资源隔离：每个任务独立工作空间，避免环境冲突
• 自动化闭环：Wake Callback + 定时备份检查，减少人工等待
• 文档详尽：Quick Reference 表格、Troubleshooting、目录结构警示完整

潜在局限

• 依赖 Tailscale 网络：MagicDNS 在容器内不可用，需使用 IP 地址
• 无 HTTPS 传输：Wake Callback 使用 HTTP（端口 18789），虽在内网仍建议未来升级
• 凭证管理手动：Token 需用户自行配置，无内置密钥管理服务
• TTY 要求差异：Claude Code 必须 -t，OpenCode 可选，易混淆

适合人群

• 需要并行处理多 PR/Issue 的开发团队
• 追求隔离开发环境、避免本地污染的高级用户
• 已部署 Tailscale 网络的基础设施团队

常规风险

• SSH 命令误用：占位符 <name>、<projname> 若未正确替换可能导致操作错误目标
• Token 泄露：文档示例虽用占位符，但用户实际使用时可能硬编码于脚本
• 工作空间残留：未遵循 "创建即清理" 规则可能导致资源堆积
• Wake Callback 失败：网络波动时可能错过通知，依赖备份 cron 兜底