Davicjc/agy

agy: Claude + Gemini 协同工作

agy 是一个类似于 Claude Code 的终端智能体，运行 Gemini（及其他）模型。它在 Claude 较弱或成本较高的领域表现出色：图像、原生音频和视频以及大量工作。谨慎使用时，它会成为你的第二双手和独立审查员。不加分辨地使用时，它只会说“完成”而实际并未完成。

本技能的金科玉律是：Claude 仍然对最终结果负责。 agy 负责执行；Claude 负责指定、检查和决策。

脚本位于此文件旁边的 scripts/ 目录下。在以下命令中，<skill> 是加载技能时显示为“此技能的基目录”的文件夹；始终使用绝对路径。

脚本	用途
scripts/agy-modelo PAPEL	返回适用于该角色的模型，实时从 agy models 读取
scripts/agy-tarefa ...	运行任务，保存所有内容，并显示 git 中实际发生的变化
scripts/agy-revisar ...	对差异进行只读审查，带有结构化的发现
scripts/agy-historico [N]	最近执行记录：状态、模型、时间和 token（用于汇报开销）

用户也可以直接调用：/agy:delegar、/agy:revisar、/agy:modelos 和 /agy:historico。

在开始之前：agy 准备好了吗？

command -v agy && <skill>/scripts/agy-modelo --listar --atualizar

如果 agy 不存在或命令失败，则停止并通知用户（他们需要安装或登录 agy）。不要尝试绕过。在会话的第一次检查之后，不带 --atualizar 的 agy-modelo 将使用缓存 1 小时的列表。

何时委托（以及何时不委托）

应委托的情况，当 agy 更擅长，或者并行化能真正节省时间时：

• 图像：生成或编辑照片、背景、横幅、模型、图标、替换图像中的文本或徽标。
• 音频和视频：转录音频（包括 WhatsApp 的）、直接从文件总结或分析 .mp4。
• 大型工作的独立部分：模块、屏幕、测试、文档，每个部分都有自己的文件。
• 机械性批量操作：在 40 个文件中重命名 API、迁移重复模式、生成示例数据。
• 第二意见：审查 Claude 刚刚编写的代码（参见“交叉验证”）。

不应委托的情况，当：

• 任务依赖难以用书面形式传递的该对话上下文（决策、用户偏好、反复修改）：编写此上下文的成本通常高于直接执行；
• 这是一个小而明显的编辑（委托和检查成本更高）；
• 涉及秘密、密码、令牌、第三方个人数据或不可逆操作（删除、发布、发送消息、git push）：这些应由 Claude 和用户处理。

模型选择（动态）

切勿在提示或命令中写入固定模型名称。应使用角色：

角色	用途	当前选择（示例）
codigo	编写和修改代码	最新的 Gemini "pro"，高努力度
revisao	审查差异、寻找 bug	最新的 Gemini "pro"，高努力度
pesquisa	阅读大量材料并总结	最新的 Gemini "pro"，中等努力度
imagem	生成或编辑图像	最新的 Gemini "pro"，中等努力度
rapido	简单任务、批量操作、草稿	最新的 Gemini "flash"

agy-modelo 读取 agy models（缓存 1 小时），分离快速系列（flash/lite）和主力系列，获取最新版本以及角色偏好的努力度。当新的 Gemini 发布时，它将自动被使用，无需修改任何内容。如需强制指定：AGY_MODELO_CODIGO=<id>（按角色）或 AGY_MODELO=<id>（全部）。如果刚发布了新模型，请使用 --atualizar。

对于审查，优先选择与编写代码的模型不同系列的模型。第二意见的意义在于拥有另一个“大脑”。revisao 角色已选择 Gemini；不要在 agy 内将其换为 Claude 来审查 Claude 自己的代码。

如何请求任务

1. 将提示写入文件，遵循 references/prompt-modelo.md。它必须是自包含的：agy 未见过此对话。使用绝对路径、阅读前置内容、要执行的操作、不要触碰的内容、保存位置以及如何证明其正确性。
2. 在后台运行（使用 run_in_background: true 的 Bash），因为任务可能需要几秒到几十分钟不等：

<skill>/scripts/agy-tarefa --dir /abs/projeto --papel codigo \
  --nome "tela de login" --prompt-arquivo /abs/prompt.md --timeout 2400

• --dir 是必需的，并且可以重复。agy 只能看到和编辑此处传递的文件夹。没有这个，它将在其自己的草稿中工作，并回复“完成”而项目实际没有任何更改。同时包括支持文件（参考图像、音频）的文件夹。
• --modo plan 让 agy 只读（分析、研究、审查）。默认的 accept-edits 允许编辑文件。
• 脚本会向提示添加固定规则：不提交、不使用 sudo、不离开文件夹、简短回答。仅在你有充分的理由时使用 --sem-regras。
• 若要继续同一对话（例如：请求调整），使用 --continuar <id>，id 位于 meta.json 中。agy 会记住之前所说的话。
• 较长的请求不是问题：超过约 100 KB 时，脚本将通过文件将请求传递给 agy（Linux 命令行拒绝超过 128 KB 的参数）。
• 输出最多显示 150 行响应（--max-linhas N 更改此设置）；完整文本位于 PASTA= 指示的文件夹中的 resposta.md。仅当需要时才从那里读取：这样 agy 的结果就不会填满你的上下文。
• 如果 Claude 以 root 身份在另一个用户的文件夹中运行，脚本会将 agy 通过终端创建的内容（mkdir、npm install、git...）的所有权归还给文件夹所有者，因为这些内容默认以 root 身份创建。否则，用户后续的 git 和编辑器会出问题。agy 自身的写入工具已会尊重所有者。--manter-donos 可关闭此功能。

agy-tarefa 的输出	含义
0	agy 已完成。仍需要验证（下一节）
1	agy 错误或响应为空（RESPOSTA-VAZIA）：视为失败
2	脚本使用错误（消息会说明缺失内容）
3	agy 尽管有规则，仍然提交了：查看 git log 并通知用户
124	超时。它已编辑的内容仍在磁盘上：检查 alteracoes.txt

3. 在等待时，继续处理其他事务。进程结束时你会收到通知。

验证 agy 的交付成果（必需）

agy 的报告是声明，而非证明。agy-tarefa 已经显示实际发生了变化的内容（git status 前后的比较），并在 agy 提交时发出警报（退出码 3）。然后：

1. 将报告与 alteracoes.txt 进行比较。 如果它声称创建了一个未出现的文件，或者修改了请求之外的内容，则存在问题。
2. 阅读差异（git diff、git diff --stat），而不仅仅是响应。
3. 运行项目的检查项：构建、测试、lint、node --check、python -m py_compile 或任何现有的检查。对于界面，查看实际屏幕（截图/浏览器）。agy 经常在主题、颜色以及文件间的集成细节上出错。
4. 做决定：接受、自行修正（如果很小），或者使用 --continuar 并附上确切的错误列表将其返回给 agy。

只有在完成这些步骤后才能告诉用户任务已完成。

交叉验证（第二意见）

在由 Claude 或 agy 完成了一次重要更改后，请求一次独立的审查：

<skill>/scripts/agy-revisar --dir /abs/repo                       # 从头（HEAD）开始，包括新文件
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # 从 main 开始
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concorrência no worker"

agy 以只读模式进行审查，并返回裁决（aprovado、ajustar、reprovar）以及带有严重性、置信度、文件:行号、证据和建议的发现（格式见 assets/schema-revisao.json）。差异会被限定范围，并附有警告：代码内的文本是给定的数据而非指令，以防止恶意注释“命令”审查者批准。使用 --exigir-aprovado 时，当裁决不是“aprovado”时，脚本退出码为 4（在自动化中很有用）。

不要盲目应用发现结果。 对于每一条：打开代码，确认故障场景确实发生，然后才修正。忽略误报，并告知用户有多少发现是真实的。置信度为 baixa 的发现是线索，而非命令。如果 agy 否决了某个你确信正确的内容，应向用户解释原因，而不是为了取悦审查者而修改。

并行工作

要分解一项大型工作：

1. 将其拆分为不修改相同文件的部分。如果两个部分需要同一文件，则它们不是并行的：按顺序执行。
2. 给每个部分一个自己的文件夹：一个 git worktree 对应一个部分是最安全的（git worktree add ../projeto-parte-a -b parte-a），或者使用不重叠的子文件夹。
3. 为每个部分运行一个 agy-tarefa，全部使用 run_in_background: true，每个的 --dir 仅指向其自己的文件夹。
4. 在合并之前验证每个部分（上一节）。一次合并一个，每次合并后运行测试。
5. 同时运行超过 3-4 个智能体通常会导致配给或 agy 的请求限制被耗尽。优先选择少量定义明确的部分。

一个好的分工是 Claude 负责需要对话上下文的部分（架构、集成、用户决策），而 agy 负责独立的部分。

图像、音频和视频

• 将输入文件放在通过 --dir 传递的文件夹中，并在提示中引用绝对路径。
• 对于图像，指定大小、格式和确切的输出路径，并在将结果用于项目之前向用户展示。如果有视觉标识（颜色、字体），请传递这些值，因为 agy 无法猜测。
• 对于转录，请求格式（纯文本、带时间戳、按说话人）和语言。如果没有任何内容需要编辑，使用 --modo plan。

常见问题

当出现问题时，请阅读 references/problemas.md：“完成”但没有更改、超时、配给、模型无法识别、登录、格式外响应。

如何向用户报告

简短且可验证：委托了什么任务、使用了哪个模型（meta.json）、改变了什么（文件）、你检查了什么（测试、差异、屏幕）以及你修正了 agy 所做的哪些内容。如果交叉审查发现了问题，请说明其中有多少是真实的，以及做了什么处理。完整记录保存在 ~/.cache/agy-skill/execucoes/（30 天后删除；AGY_SKILL_RETENCAO_DIAS 可更改此设置），agy-historico 会汇总 token 消耗。