Platform Adaptation

Platform Adaptation

If your harness appears here, read its reference file for special instructions:

• Codex: references/codex-tools.md
• Pi: references/pi-tools.md
• Antigravity: references/antigravity-tools.md

该文件本身还要求：**任何回复或动作之前（包括澄清性提问）都必须先检查是否有适用技能**；若技能带检查清单（checklist），则“create a todo per item”——这正是后文任务工件机制在 Antigravity 上落地的直接来源。

## 二、核心动作 → 工具映射表

原文档的第一张表是整个映射的最小核心，完整继承如下：

| 技能请求的动作 | Antigravity CLI 对应工具 |
|----------------------|----------------------|
| 派生子代理（`Subagent (general-purpose):` 模板） | `invoke_subagent`，配合内置 `TypeName`：全功能工作用 `self`，只读调研用 `research` |
| 任务跟踪（“create a todo”“mark complete”） | **任务工件（task artifact）**——用 `write_to_file` 写入并附 `IsArtifact: true`、`ArtifactType: "task"`（见下文“任务跟踪”）。**不是** `manage_task`——后者管理的是后台进程 |

注意第一行的 `Subagent (general-purpose):` 前缀并非 agy 特有格式，而是 Superpowers 技能里的通用派生模板。例如 [dispatching-parallel-agents 技能](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/dispatching-parallel-agents/SKILL.md?utm_source=gitcode_repo_files) 的并行示例：

```text
Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
# All three run concurrently.

在 Antigravity 上，这些 “general-purpose” 子代理就翻译成对 invoke_subagent 的调用，并按下文规则选择 TypeName。

三、子代理调度：invoke_subagent 与 self / research 两种内置类型

Antigravity 的 invoke_subagent 通过内置 TypeName 区分子代理的能力面，映射文档给出的选择标准是任务是否需要写入权限：

• self：全功能子代理，能力与主代理相当，用于需要改文件、跑命令的实现类工作（例如 subagent-driven-development 中的 implementer、requesting-code-review 中的审查者）；
• research：只读子代理，用于调研、定位问题、收集信息等不产生副作用的任务。

这个二分法与 Superpowers 的技能设计天然契合：技能文本里“派生一个子代理去调查 X”这类动作，在 agy 上应优先选 research；只有当动作明确包含“修改/创建/修复”时才选 self。

集成测试 把这条规则固化成了断言（第 32–36 行）：映射文档必须同时出现反引号包裹的 `self` 与 `research`，否则测试失败：

grep -q '`self`' "$MAPPING" \
  || fail "mapping does not document the built-in 'self' subagent type"
grep -q '`research`' "$MAPPING" \
  || fail "mapping does not document the built-in 'research' subagent type"

也就是说，这两种内置类型是 Antigravity 集成的受测契约——如果未来文档删改了它们，CI 会立刻捕获。

四、任务跟踪：用 task 工件代替 todo 工具

这是 Antigravity 映射中最容易踩坑的部分，原文档的结论先摆出来：

Antigravity has no todo tool (manage_task manages background processes — list/kill/status/send_input — it is not a checklist).

逐点拆解：

4.1 manage_task 是进程管理工具，不是清单工具

manage_task 的四个子操作是 list / kill / status / send_input——语义上全是“管理后台进程”。技能文本里的 “create a todo”“mark complete” 绝不能映射到它，否则 agent 会拿进程管理 API 当检查清单用，行为完全跑偏。

4.2 task 工件机制：参数与编辑方式

原文档给出的正确做法是维护一个 task 工件（task artifact）：一份 markdown 检查清单，用 write_to_file 保存，且必须携带以下元数据参数：

• IsArtifact: true
• ArtifactMetadata.ArtifactType: "task"

随着任务推进，用 replace_file_content 或 multi_replace_file_content 就地编辑该工件（而不是反复整文件重写）。集成测试 第 27–30 行、38–40 行分别断言了 write_to_file、replace_file_content、invoke_subagent 三个工具名以及“task artifact”机制必须出现在映射文档中：

for tool in write_to_file replace_file_content invoke_subagent; do
  grep -q "$tool" "$MAPPING" \
    || fail "mapping does not document the '$tool' tool"
done

grep -qE 'ArtifactType.*task|task. artifact' "$MAPPING" \
  || fail "mapping does not document task tracking as a 'task' artifact"

4.3 工件的使用纪律：它是唯一的真相源

原文档对工件生命周期有明确要求，这四点值得原样继承：

1. 开始时创建：任何多步任务一开始，就用 task 工件列出计划中的每一个步骤；
2. 完成即勾选：每完成一步，立即编辑工件把对应条目改为 - [x]；
3. 计划变化即更新：checklist 与计划保持一致；
4. 长对话中重读：工件是“还剩什么”的 source of truth——对话变长之后，每开始一个新步骤之前先重新读一遍工件。

最后一条是针对 LLM 上下文衰减的针对性设计：会话越长，模型对早期计划细节的记忆越不可靠，重读工件成本极低却能强制刷新状态。这个纪律与 using-superpowers 中“技能带 checklist 时逐项建 todo”的规则一脉相承——在 Antigravity 上，“todo” 的物理载体就是这份 task 工件。

五、映射如何被加载：安装、引导与指针链路

工具映射写得再好，模型得先看到它才有用。Superpowers 在 Antigravity 上的加载链路如下（依据 README 的 Antigravity 一节 与 移植指南）：

1. 安装：按 README 官方命令，用 agy 自己的插件安装器安装本仓库插件（命令形式为 agy plugin install <Superpowers 仓库 URL>，具体 URL 以 README 为准）；更新时重新执行同一条命令即可（“Reinstall with the same command to update”）。
2. 引导（bootstrap）：Antigravity 会运行插件的 session-start hook，因此 Superpowers 从第一条消息起就处于激活状态——这正是 移植指南 Part 2 强调的“硬性前提：自动的会话开始注入”，也是它区别于“伪移植”的验收标准。
3. 技能发现：agy plugin install 会把仓库的 skills/ 目录整体拷入安装位置。移植指南 Step 5 将 Antigravity 归入“有原生技能发现、但没有 Skill 加载工具”一类（与 pi 并列），此时读取 SKILL.md 就是被认可的加载机制——using-superpowers 技能在会话开始时进入上下文后，agent 依据其 “Platform Adaptation” 一节顺藤摸瓜读到 references/antigravity-tools.md，映射链路闭合。
4. 指针受测：测试脚本 第 42–44 行还专门断言 SKILL.md 的 Platform Adaptation 必须引用 antigravity-tools.md：

grep -q "antigravity-tools.md" "$SKILL" \
  || fail "SKILL.md Platform Adaptation does not reference antigravity-tools.md"

这条断言保护的就是第 3 步的“顺藤摸瓜”路径——指针一旦丢失，映射文档就成了死文件。

另外，发布说明 记录该集成曾通过标准验收测试端到端验证：在干净会话中发送 “Let's make a react todo list”，brainstorming 技能必须在任何代码之前自动触发——这也是移植指南 Part 3 定义的“完成定义”中的强制验收项，Antigravity 同样适用。

六、本地运行验证

集成测试是纯静态检查（只 grep 文档，不要求安装 agy），可以在仓库内直接运行 tests/antigravity/run-tests.sh：

bash tests/antigravity/run-tests.sh

它会遍历执行目录下所有 test-*.sh，当前唯一成员即 test-antigravity-tools.sh。全部通过时的输出为：

PASS: Antigravity tool mapping valid (subagent dispatch, task artifact, SKILL.md link)
=== All Antigravity tests passed ===