Skip to content

README.zh.md

Latest commit

 

History

History
244 lines (169 loc) · 6.99 KB

README.zh.md

File metadata and controls

244 lines (169 loc) · 6.99 KB

English | 中文 | 日本語

invoke-opencode-acp

一个用于 Claude Code CLI 的技能，通过将复杂任务委托给 OpenCode 子代理，节省数千个 token。

注意：这是一个 Claude Code CLI 工具的技能，不是独立应用程序。你必须安装 Claude Code 才能使用它。

要求：此技能需要 OpenCode（通过 ACP 协议）和 Node.js 才能运行。

这个技能做什么

将复杂任务委托给独立的 AI 代理（OpenCode），通过 ACP 协议实现，避免主 Claude 对话消耗过多的 token。

想象一下，这就像雇佣了一位专业承包商：你提供目标，他们独立完成工作，你得到结果，而无需所有那些会填充对话历史来回交流。

收益

大幅节省 Token

  • 不使用此技能：主 Claude 读取每个文件 → 分析 → 编辑 → 重复。每次迭代消耗数千 token。
  • 使用此技能：发送目标给子代理 → 子代理独立工作 → 获得最终结果。只有摘要进入你的对话。

典型节省：复杂任务可减少 50-90% 的 token。

重要权衡

如何实现节省：OpenCode 子代理使用免费 tokens 调用替代模型（如 GLM-4.7、Qwen），而不是你付费的 Claude tokens。

这意味着：

  • ✅ Token 节省：子代理工作完全免费
  • ⚠️ 能力权衡：替代模型的推理能力低于 Claude
  • ⚠️ 质量差异：结果可能不够精细，需要审查

最佳适用场景：

  • 代码重构和格式化（直接明了）
  • 文档更新和生成
  • 测试代码生成
  • 需求明确的 Bug 修复
  • 批量文件操作

考虑替代方案的场景：

  • 复杂的架构决策
  • 细致的代码审查
  • 敏感的逻辑更改
  • 需要深度领域专业知识的任务

更快的任务完成

  • 主 Claude 保持响应，可处理其他任务
  • 子代理并行工作
  • 子任务无上下文窗口限制

更适合复杂工作流

完美适用于：

  • 多文件重构："为所有 Python 文件添加类型提示"
  • 批量操作："更新所有文档文件"
  • 代码审查："审查整个代码库的安全问题"
  • Git 工作流："使用这些更改创建拉取请求"

工作原理

  1. 你描述任务（一句话就足够了）
  2. OpenCode 子代理接收你的目标并独立工作
  3. 结果保存到文件（不是你的对话）
  4. 你在主对话中获得简洁摘要

子代理可以读取文件、进行编辑、运行测试等——就像一个完整的开发者——而不会消耗你主对话的上下文。

安装

前置要求

你需要安装三个东西：

  1. Claude Code CLI（如果正在使用，应该已经安装）
  2. OpenCode CLI（npm install -g opencode）
  3. Node.js（大多数系统自带）

快速安装

# 1. 安装 OpenCode（如果尚未安装）
npm install -g opencode

# 2. 将技能复制到 Claude
cp -r skills/invoke-opencode-acp ~/.claude/skills/

# 3. 验证是否工作（可选）
node ~/.claude/skills/invoke-opencode-acp/tests/test_acp_client.js

验证安装

检查 OpenCode 是否已安装：

opencode --version

检查技能是否存在：

ls ~/.claude/skills/invoke-opencode-acp/SKILL.md

使用方法

只需告诉 Claude 你想要完成什么：

"重构此项目中的所有 Python 文件以使用类型提示"

Claude 将委托任务给 OpenCode 子代理并返回结果。

超时指南（OpenCode 较慢）：

  • 简单任务（数学、简短答案）：至少 180 秒（3 分钟）
  • 中等任务（单个文件，约 100 行）：至少 600 秒（10 分钟）
  • 复杂任务（多文件、重构）：至少 1800 秒（30 分钟）

示例任务：

  • "重构整个代码库"
  • "使用新的安装说明更新 README.md"
  • "为所有 Python 文件添加类型提示"
  • "对代码库运行安全审计"

真实示例

示例 1：大型重构

你的请求："为项目中所有 Python 文件添加类型提示"

不使用此技能：

  • Claude 读取每个文件（10,000 token）
  • Claude 编辑每个文件（15,000 token）
  • Claude 验证更改（8,000 token）
  • 总计：约 33,000 token 消耗

使用此技能：

  • 你发送目标（50 token）
  • 子代理独立工作（对话中 0 token）
  • 你获得摘要（200 token）
  • 总计：约 250 token 消耗

节省：99% token 减少！

示例 2：代码审查

你的请求："审查整个代码库的安全漏洞"

不使用此技能：

  • Claude 读取每个源文件（25,000 token）
  • Claude 分析和记录（12,000 token）
  • 总计：约 37,000 token

使用此技能：

  • 目标 + 摘要（~300 token）
  • 总计：约 300 token

节省：99% token 减少！

示例 3：批量文档更新

你的请求："更新所有 .md 文件以包含新的许可证页眉"

不使用此技能：

  • Claude 读取 20 个 markdown 文件（15,000 token）
  • Claude 编辑每个文件（20,000 token）
  • 总计：约 35,000 token

使用此技能：

  • 目标 + 摘要（~250 token）
  • 总计：约 250 token

节省：99% token 减少！

何时使用

✅ 使用此技能：

  • 影响 2+ 个文件的任务
  • 重构或结构调整
  • 批量操作（在许多文件中查找和替换）
  • 整个代码库的代码审查
  • 需要研究和分析的多步骤任务
  • Git 工作流（提交、推送、拉取请求）

❌ 不使用：

  • 单文件快速编辑
  • 简单文本替换
  • 需要与主对话集成的任务

与其他方案的区别

vs. 普通 Claude 任务

方面 普通 Claude 使用 invoke-opencode-acp
上下文使用 完整文件内容 仅目标
Token 消耗 高（数千） 低（数百）
你的对话 显示所有步骤 仅显示结果
速度 顺序 并行
最适用于 简单任务 复杂任务

vs. 其他解决方案

  • Claude Projects：仍使用主上下文窗口（token 有限）
  • 手动委托：需要复制粘贴，无自动化
  • invoke-opencode-acp：自动化委托，最小化上下文使用

故障排除

"opencode command not found"

npm install -g opencode

"Skill not enabled"

  • 检查技能是否在 ~/.claude/skills/invoke-opencode-acp/ 中
  • 重启 Claude Code
  • 在 Claude Code 设置中启用

任务超时

  • 增加 -t 参数的值
  • 参见使用方法中的超时指南
  • OpenCode 可能较慢，特别是复杂任务

技术细节（供好奇者）

此技能使用 ACP（Agent Control Protocol）与 OpenCode 通信。它：

  1. 在后台启动 OpenCode
  2. 创建专用会话
  3. 发送你的任务目标
  4. 过滤内部"思考"（无需查看推理过程）
  5. 仅返回关键结果

与复杂任务节省的 token 相比，~6 秒的初始化开销可以忽略不计。

许可证

MIT License - 详见 LICENSE。

English version: README.md 日本語版本：README.ja.md