核心用法
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 需要
-tTTY 标志，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 直连 |