核心用法
coding-agent 是一个代理编排技能，允许从 bash 环境中调用主流 AI 编码代理（Codex、Claude Code、Pi、OpenCode）完成复杂开发任务。核心工作模式包括：
1. 即时执行模式：根据目标代理类型选择正确的 PTY 配置——Codex/Pi/OpenCode 需 pty:true，Claude Code 使用 --print --permission-mode bypassPermissions 无需 PTY。
2. 后台会话模式：通过 background:true 启动长时间任务，配合 process action:log/poll/submit/kill 实现非阻塞监控与交互。
3. 安全评审工作流：强制使用临时 clone 或 git worktree 隔离评审环境，禁止在主仓库直接运行 PR 评审。
显著优点
- 多代理兼容：统一封装四家主流 CLI 编码工具，降低切换成本
- 执行模式矩阵：针对不同代理的 I/O 特性预置最优启动参数
- 后台可观测：完整的 session 生命周期管理，避免终端阻塞
- 评审隔离机制：通过临时目录/worktree 防止污染生产代码
- 结构化提示模板：内置任务分解与完成汇报规范，提升输出一致性
潜在缺点与局限性
- 外部依赖重：要求预装
claude、codex、opencode、pi任一可执行文件 - 权限模式风险：
bypassPermissions和--full-auto可能绕过人工确认 - PTY 复杂性：部分代理需伪终端交互，在 CI/无头环境可能失效
- 无内置回退：若目标代理未安装，技能无法自动降级或替代
- 网络与成本敏感：调用外部编码代理产生 API 费用且依赖网络稳定性
适合人群
- 需要并行处理多文件重构的大型项目维护者
- 希望自动化 PR 评审流程的 Tech Lead
- 构建"编码-测试-修复"循环的 DevOps 工程师
- 已订阅 Codex/Claude Code 等服务的付费用户
常规风险
| 风险类型 | 说明 |
|---------|------|
| 权限提升 | `bypassPermissions` 可能执行危险操作 |
| 目录污染 | 未隔离评审可能修改生产仓库 |
| 会话泄漏 | 后台进程未正确清理导致资源占用 |
| 成本失控 | `--full-auto` 循环可能消耗大量 token |
| 代理幻觉 | 多文件编辑可能引入未验证的破坏性变更 |
建议始终在无状态工作目录运行，对关键变更保留人工终审环节。