Perry Coding Agents

核心用法

本技能提供在 Perry 工作区上调度 OpenCode 和 Claude Code 两大 AI 编码代理的完整工作流，核心模式为「调度 → 设置回调 → 完成通知」。主要流程：

1. 工作区管理：通过 perry start 创建隔离工作区（支持 Git 仓库克隆），任务完成后 perry remove 清理
2. 任务调度：支持 OpenCode（带 Web UI）和 Claude Code（需 TTY）两种代理，可交互式或后台运行
3. 智能通知：通过 Tailscale IP + 网关端口配置 wake 回调，任务完成自动通知；同时强制设置 20 分钟后 cron 兜底检查
4. 批量能力：支持「Army Mode」并行创建多个工作区处理 PR 审查或 issue 修复

显著优点

• 隔离安全：每个任务独立工作区，避免环境污染和代码冲突
• 弹性并行：可同时派发多个代理处理不同 PR/issue，提升吞吐
• 自动化闭环：wake 回调 + cron 兜底双保险，减少人工盯盘
• 双代理选择：OpenCode 适合标准开发任务（有 Web UI），Claude Code 适合特定场景

潜在局限

• 网络依赖：依赖 Tailscale 网络连通性，MagicDNS 在工作区内不生效，需使用 IP 地址
• 配置复杂度：需动态获取 tailnet IP、网关 token，wake 回调拼接易出错
• 资源开销：每个工作区独立容器，大批量任务需考虑宿主机资源
• 调试门槛：代理失败时需手动 SSH 检查日志，对使用者 CLI 熟练度有要求

适合人群

• 需要并行处理多 PR/多 issue 的开发团队
• 追求「fire and forget」自动化工作流的工程师
• 已部署 Perry + Tailscale 基础架构的用户

常规风险

• token 泄露：wake 回调需明文传递 Authorization token，存在日志泄露风险
• 任务失控：后台任务可能无限挂起，必须依赖 cron 兜底机制
• 权限边界：代理在隔离工作区内拥有完整文件系统权限，需确保代码仓库可信
• 网络单点：wake 回调依赖单一网关端口，网络分区时通知失效

核心用法

perry-coding-agents 是一套在 Perry 隔离工作空间上调度 AI 编码代理（OpenCode/Claude Code）的完整工作流指南。核心模式为 Dispatch → Schedule Follow-up → Done：先创建或复用工作空间，配置 Tailnet 唤醒回调，向代理分发任务（代码开发、PR 审查、Bug 修复等），设置 20 分钟后 cron 备份检查，最后接收完成通知并清理资源。

关键命令速览

• 创建空间：perry start <name> --clone <repo>
• 单任务：ssh -t workspace@<name> "opencode run 'task'"
• 后台任务：nohup opencode run 'task...curl wake callback' &
• PR 批量审查：并行创建多个 review-pr-XX 空间，dispatch 后统一收集结果

显著优点

1. 真正的异步开发：代理完成后通过 HTTP POST 主动唤醒，无需人工轮询
2. 批量并行能力：「Army Mode」支持同时审查多个 PR 或修复多个 Issue，显著提升团队吞吐
3. 安全隔离：每个任务运行在独立 Perry 容器，Tailnet 私有网络通信，无公网暴露
4. 双代理灵活选择：OpenCode 带 Web UI（:4096）适合长时任务；Claude Code 适合交互式诊断
5. 完善的兜底机制：cron 备份检查 + 手动故障排查指南，降低任务丢失风险

潜在缺点与局限性

1. 网络依赖重：完全依赖 Tailscale 网络，MagicDNS 在容器内不可用，需手动解析 IP
2. 配置门槛高：需预先配置 gateway token、理解 wake callback 机制，新手易在 SSH 参数或 curl 格式上出错
3. 无状态管理：文档未提及任务持久化或断点续传，长时任务若中断需手动恢复
4. Claude Code 限制：强制要求 TTY（-t），无法像 OpenCode 那样轻松后台化
5. Token 管理风险：虽文档使用占位符，但用户实际部署时若硬编码 token 到脚本即引入泄露风险

适合人群

• 平台/Infra 工程师：需要为团队搭建标准化 AI 编码工作流
• 开源维护者：需批量审查 PR、并行处理 Issue 的中大型项目
• 异步协作团队：跨时区工作，依赖「提交任务 → 次日收结果」模式

常规风险

• 网络故障导致唤醒失败：Tailnet IP 变动或网关不可达时，任务完成但通知丢失
• 资源泄漏：未遵循「task-specific 空间用后删除」规则，导致僵尸工作空间堆积
• 并发冲突：同一仓库多空间并行操作若未做好分支隔离，可能产生合并冲突

---

安全认证摘要（CLS-2026-0702-7A3F）

• 评分：95/100（S 级）
• 信任等级：T3（本地项目）
• 关键结论：纯 Markdown 文档，14 个代码示例均为标准 SSH/Shell 命令，无危险函数调用，无敏感信息硬编码。网络通信仅限于 Tailnet 内部私有地址（http://<tailnet-ip>:18789/api/wake）。通过 GDPR 数据最小化、敏感信息保护、权限合理性等全部合规检查。