核心用法
OpenCode-CLI-Controller 是一个本地 API 编排工具，充当用户与 OpenCode CLI 之间的"超级调度者"。它通过 REST API 与运行在 127.0.0.1:4099 的本地 OpenCode 服务器通信，将用户的自然语言指令转化为结构化的开发任务。
使用流程遵循七步标准工作流：验证服务器健康 → 更新提供商缓存 → 创建/选择项目 → 创建会话 → 发送任务指令 → 智能监控进度 → 获取变更摘要。Skill 提供丰富的 Bash 脚本封装（如 send_message.sh、monitor_session.sh、get_diff.sh 等），屏蔽底层 curl 调用的复杂性。
关键设计理念是"Orchestrator 而非 Executor"——Agent 不直接读写代码文件，而是通过 API 指挥 OpenCode 完成所有编码、调试和质量检查。Agent 仅使用 ls 确认文件存在，真正的代码验证由 OpenCode 负责，Agent 只需监控状态变化并报告 diff 摘要。
支持多提供商切换（OpenCode、Anthropic、Gemini 等）、多阶段开发模式（Plan → Build → Review）、实时事件流监控与智能轮询三种任务跟踪策略，以及完善的状态持久化机制。
显著优点
1. 极致的本地安全性：所有网络通信严格限制在 localhost，无外部数据外泄风险，零第三方依赖，供应链攻击面为零。
2. 清晰的责任分离："Orchestrator 模式"彻底区分了"指挥"与"执行"，避免 Agent 越权直接修改代码，降低误操作风险。
3. 高效的 Token 管理：提供 Standard（批量等待后汇报）与 Real-time（实时事件流）两种监控模式，用户可按任务复杂度灵活选择，节省不必要的 Token 消耗。
4. 丰富的自动化脚本：12 个封装脚本覆盖完整开发生命周期，从提供商选择到状态管理，大幅降低使用门槛。
5. 透明的审计能力：通过 get_diff.sh 获取变更摘要（如 src/App.tsx (+120/-0)），不读取具体代码即可掌握项目演进。
潜在缺点与局限性
1. 强依赖本地环境：必须预先安装并运行 OpenCode CLI 服务器（端口 4099），且初始化需等待 10-15 秒，对新手配置门槛较高。
2. HTTP 非加密通信：本地 API 使用明文 HTTP，虽在 localhost 场景风险可控，但若误配置为 0.0.0.0 暴露至局域网则存在安全隐患。
3. 功能边界限制：Agent 被明确禁止直接读取代码文件进行验证，某些需要 Agent 深度介入代码审查的场景可能受限。
4. Bash 依赖：要求系统预装 curl、jq，Windows 用户需借助 WSL 或 Git Bash 环境。
5. 无内置身份验证：默认假设受信任的本地环境，多用户共享机器时需注意 ./state/ 目录的权限隔离。
适合的目标群体
- AI 辅助开发实践者：希望将编码任务完全委托给 OpenCode，自己专注于需求定义与进度把控的开发者。
- 多项目并行管理者：需要同时管理多个 OpenCode 会话、快速切换项目上下文的技术负责人。
- 本地隐私敏感用户：拒绝代码数据上云，坚持完全本地化 AI 开发的团队。
- 自动化工作流构建者：希望将 OpenCode CLI 集成到 CI/CD 或自定义脚本中的 DevOps 工程师。
使用风险
性能风险：智能监控的指数退避算法（2s→30s）设计合理，但若任务异常挂起，可能产生较长等待时间；建议为关键任务设置超时机制。
配置风险：config.json 中的 PROJECTS_BASE_DIR 若指向系统敏感目录，可能导致意外文件操作；建议严格限定在项目专用路径。
依赖风险：OpenCode CLI 本身的版本兼容性可能影响 API 行为，建议定期执行 opencode update 保持同步。
并发风险：文档强调"每个会话属于一个项目目录"，混用可能导致状态混乱；多 Agent 同时操作同一项目时缺乏内置锁机制，需人工协调。