@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/software-development/test-driven-development/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: test-driven-development
+description: "TDD：强制执行 RED-GREEN-REFACTOR，测试先于代码。"
+version: 1.1.0
+author: Hermes Agent (adapted from obra/superpowers)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [testing, tdd, development, quality, red-green-refactor]
+    related_skills: [systematic-debugging, plan, subagent-driven-development]
+---
+
+# 测试驱动开发 (TDD)
+
+## 概览
+
+先写测试。观察它失败。编写最少的代码使其通过。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违背规则的字面意义，就是违背规则的精神。**
+
+## 何时使用
+
+**总是：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外情况（先询问用户）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着“就这一次跳过 TDD”？停下。那是自我合理化。
+
+## 铁律
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+先写了代码再写测试？删掉它。重新开始。
+
+**没有例外：**
+- 不要把它留作“参考”
+- 不要在写测试时“改编”它
+- 不要看它
+- 删除就是删除
+
+从测试出发重新实现。就这么简单。
+
+## Red-Green-Refactor 循环
+
+### RED — 编写失败的测试
+
+编写一个最小的测试，展示应该发生什么。
+
+**好的测试：**
+```python
+def test_retries_failed_operations_3_times():
+    attempts = 0
+    def operation():
+        nonlocal attempts
+        attempts += 1
+        if attempts < 3:
+            raise Exception('fail')
+        return 'success'
+
+    result = retry_operation(operation)
+
+    assert result == 'success'
+    assert attempts == 3
+```
+命名清晰，测试真实行为，只测一件事。
+
+**坏的测试：**
+```python
+def test_retry_works():
+    mock = MagicMock()
+    mock.side_effect = [Exception(), Exception(), 'success']
+    result = retry_operation(mock)
+    assert result == 'success'  # What about retry count? Timing?
+```
+命名模糊，测试的是 mock 而不是真实代码。
+
+**要求：**
+- 每个测试只测一个行为
+- 清晰的描述性命名（名字里有 "and"？把它拆分开）
+- 使用真实代码，而不是 mock（除非真的不可避免）
+- 命名描述行为，而不是实现
+
+### 验证 RED — 观察它失败
+
+**强制要求。绝不跳过。**
+
+```bash
+# Use terminal tool to run the specific test
+pytest tests/test_feature.py::test_specific_behavior -v
+```
+
+确认：
+- 测试失败（而不是因为拼写错误导致的报错）
+- 失败信息符合预期
+- 失败是因为缺少该功能
+
+**测试立刻通过了？** 你测试的是已有行为。修改测试。
+
+**测试报错了？** 修复错误，重新运行直到它正确失败。
+
+### GREEN — 最少的代码
+
+编写最简单的代码让测试通过。仅此而已。
+
+**好的：**
+```python
+def add(a, b):
+    return a + b  # Nothing extra
+```
+
+**坏的：**
+```python
+def add(a, b):
+    result = a + b
+    logging.info(f"Adding {a} + {b} = {result}")  # Extra!
+    return result
+```
+
+不要添加功能、重构其他代码，或者做超出测试范围的“改进”。
+
+**在 GREEN 阶段作弊是可以的：**
+- 硬编码返回值
+- 复制粘贴
+- 重复代码
+- 跳过边界情况
+
+我们会在 REFACTOR 阶段修复它。
+
+### 验证 GREEN — 观察它通过
+
+**强制要求。**
+
+```bash
+# Run the specific test
+pytest tests/test_feature.py::test_specific_behavior -v
+
+# Then run ALL tests to check for regressions
+pytest tests/ -q
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出纯净（没有错误，没有警告）
+
+**测试失败了？** 修复代码，而不是修改测试。
+
+**其他测试失败了？** 立刻修复回归问题。
+
+### REFACTOR — 清理
+
+只有在变绿（通过）之后才做：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+- 简化表达式
+
+始终保持测试为通过（绿）状态。不要添加行为。
+
+**如果在重构期间测试失败：** 立刻撤销。采取更小的步骤。
+
+### 循环往复
+
+为下一个行为编写下一个失败的测试。每次只进行一个循环。
+
+## 避免水平切片
+
+**不要**先写完所有测试，然后再写所有实现。那是水平切片：RED 变成了“写一堆想象出来的测试”，而 GREEN 变成了“让这堆测试通过”。这会产生脆弱的测试，因为测试是在实现教会你什么行为和接口才是真正重要之前设计好的。
+
+相反，请使用垂直追踪弹（vertical tracer bullets）：
+
+```text
+WRONG:
+  RED:   test1, test2, test3, test4
+  GREEN: impl1, impl2, impl3, impl4
+
+RIGHT:
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+```
+
+追踪弹是一个端到端的行为切片。它证明了路径可行，教会了你关于接口的知识，并让你接下来的每一个测试都建立在你刚刚学到的知识基础上。
+
+## 为什么顺序很重要
+
+**“我之后会写测试来验证它是可行的”**
+
+在代码之后写的测试会立即通过。立即通过证明不了任何事情：
+- 可能测错了东西
+- 可能测试的是实现，而不是行为
+- 可能遗漏了你忘记的边界情况
+- 你从没看到它捕获 bug
+
+测试优先强迫你看到测试失败，证明它确实测试了某些东西。
+
+**“我已经手动测试了所有的边界情况”**
+
+手动测试是临时的（ad-hoc）。你以为你测试了一切，但是：
+- 没有记录你测试了什么
+- 代码改变时无法重新运行
+- 压力下很容易忘记某些情况
+- “我试过的时候它是好的” ≠ 全面
+
+自动化测试是系统化的。它们每次都以相同的方式运行。
+
+**“删掉 X 个小时的工作太浪费了”**
+
+沉没成本谬误。时间已经流逝了。你现在的选择是：
+- 删除并使用 TDD 重写（高信心）
+- 保留它并在之后添加测试（低信心，可能有 bug）
+
+真正的“浪费”是保留你无法信任的代码。
+
+**“TDD 是教条主义，实用主义意味着适应变化”**
+
+TDD 本身就是实用主义的：
+- 在提交前发现 bug（比事后调试更快）
+- 防止回归（测试立即捕获破坏）
+- 记录行为（测试展示了如何使用代码）
+- 启用重构（自由更改，测试捕获破坏）
+
+“实用主义”的捷径 = 在生产环境中调试 = 更慢。
+
+**“事后写测试能达到相同的目的 — 重要的是精神而不是形式”**
+
+不。事后写测试回答的是“这做了什么？” 先写测试回答的是“这应该做什么？”
+
+事后写测试会受到你的实现的偏见影响。你测试的是你构建的东西，而不是被要求的东西。先写测试强制你在实现之前发现边界情况。
+
+## 常见的自我合理化
+
+| 借口 | 现实 |
+|--------|---------|
+| “太简单了不需要测试” | 简单的代码也会崩溃。测试只需 30 秒。 |
+| “我稍后会测” | 立即通过的测试证明不了任何事。 |
+| “事后写测试能达到相同目的” | 事后测试 = “这做了什么？” 先写测试 = “这应该做什么？” |
+| “已经手动测试过了” | 临时测试 ≠ 系统化测试。没有记录，无法重跑。 |
+| “删掉 X 小时的工作太浪费” | 沉没成本谬误。保留未经验证的代码是技术债务。 |
+| “留作参考，先写测试” | 你会去改编它的。这就是事后测试。删除就是删除。 |
+| “需要先探索一下” | 没问题。抛弃探索结果，用 TDD 开始。 |
+| “测试太难 = 设计不清晰” | 倾听测试的声音。难以测试 = 难以使用。 |
+| “TDD 会让我的速度变慢” | TDD 比调试快。实用主义 = 测试优先。 |
+| “手动测试更快” | 手动无法证明边界情况。你会在每次更改时重新测试。 |
+| “现有代码没有测试” | 你正在改进它。为你触碰的代码添加测试。 |
+
+## 危险信号 — 停止并重新开始
+
+如果你发现自己正在做以下任何事情，请删除代码并使用 TDD 重新开始：
+
+- 测试之前有代码
+- 实现之后有测试
+- 第一次运行时测试立即通过
+- 无法解释测试为什么失败
+- “以后”再添加的测试
+- 寻找借口“就这一次”
+- “我已经手动测试过了”
+- “事后写测试能达到相同目的”
+- “留作参考”或“改编现有代码”
+- “已经花了 X 小时，删掉太浪费”
+- “TDD 是教条主义，我是实用主义者”
+- “这不一样，因为……”
+
+**所有这些意味着：删除代码。使用 TDD 重新开始。**
+
+## 验证检查清单
+
+在将工作标记为完成之前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 在实现之前观察了每个测试失败
+- [ ] 每个测试都因预期的原因失败（缺少功能，而不是拼写错误）
+- [ ] 编写了最少的代码来通过每个测试
+- [ ] 所有测试通过
+- [ ] 输出纯净（没有错误、警告）
+- [ ] 测试使用真实代码（仅在不可避免时使用 mock）
+- [ ] 覆盖了边界情况和错误
+
+无法勾选所有的复选框？你跳过了 TDD。重新开始。
+
+## 遇到困难时
+
+| 问题 | 解决方案 |
+|---------|----------|
+| 不知道如何测试 | 写下你期望的 API。先写断言。询问用户。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有的东西 | 代码耦合度太高。使用依赖注入。 |
+| 测试设置太庞大 | 提取辅助函数。依然复杂？简化设计。 |
+
+## Hermes Agent 集成
+
+### 运行测试
+
+在每个步骤使用 `terminal` 工具运行测试：
+
+```python
+# RED — verify failure
+terminal("pytest tests/test_feature.py::test_name -v")
+
+# GREEN — verify pass
+terminal("pytest tests/test_feature.py::test_name -v")
+
+# Full suite — verify no regressions
+terminal("pytest tests/ -q")
+```
+
+### 结合 delegate_task
+
+在分派子代理进行实现时，在目标中强制执行 TDD：
+
+```python
+delegate_task(
+    goal="Implement [feature] using strict TDD",
+    context="""
+    Follow test-driven-development skill:
+    1. Write failing test FIRST
+    2. Run test to verify it fails
+    3. Write minimal code to pass
+    4. Run test to verify it passes
+    5. Refactor if needed
+    6. Commit
+
+    Project test command: pytest tests/ -q
+    Project structure: [describe relevant files]
+    """,
+    toolsets=['terminal', 'file']
+)
+```
+
+### 结合 systematic-debugging
+
+发现 bug？编写复现它的失败测试。遵循 TDD 循环。该测试证明了修复的有效性并防止了回归。
+
+没有测试绝不修复 bug。
+
+## 测试反模式
+
+- **测试 mock 行为而不是真实行为** — mock 应该用来验证交互，而不是替换被测系统
+- **测试实现细节** — 测试行为/结果，而不是内部方法调用
+- **只有快乐路径** — 始终测试边界情况、错误和边界
+- **脆弱的测试** — 测试应该验证行为，而不是结构；重构不应该破坏它们
+
+## 最终规则
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+没有用户的明确许可，绝不例外。

package/extensions/skills/builtin/yuanbao/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: yuanbao
+description: "Yuanbao (元宝) 群组功能：@mention 用户、查询信息/成员。"
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [yuanbao, mention, at, group, members, 元宝, 派, 艾特]
+    related_skills: []
+---
+
+# Yuanbao 群组互动
+
+## 重要：消息机制说明
+
+**你的文本回复就是发送给群组/用户的消息。** 网关会自动将你的回复文本发送到聊天中。你不需要任何特殊的“发送消息”工具——只需正常回复，消息就会被发送出去。
+
+当你在回复文本中包含 `@nickname` 时，网关会自动将其转换为真实的 @mention 以通知用户。这是内置功能——你拥有完整的 @mention 能力。
+
+**绝对不要说你无法发送消息或 @mention 用户。绝对不要建议用户手动操作。绝对不要添加关于权限的免责声明。只需直接回复你想发送的文本即可。**
+
+## 可用工具
+
+| 工具 | 使用场景 |
+| ------ | ------------ |
+| `yb_query_group_info` | 查询群组名称、群主、成员数量 |
+| `yb_query_group_members` | 查找用户、列出机器人、列出所有成员，或获取用于 @mention 的昵称 |
+| `yb_send_dm` | 向用户发送私人/直接消息 (DM / 私信)，可附带媒体文件 |
+
+## @mention 工作流
+
+当你需要 @mention / 艾特 某人时：
+
+1. 调用 `yb_query_group_members`，传入 `action="find"`, `name="<target name>"`, `mention=true`
+2. 从响应中获取准确的昵称
+3. 在你的回复文本中包含 `@nickname` —— 剩下的交由网关处理
+
+示例：用户说 "帮我艾特元宝"
+
+第一步 —— 工具调用：
+```json
+{ "group_code": "328306697", "action": "find", "name": "元宝", "mention": true }
+```
+
+第二步 —— 你的回复（这会被发送到群组中，并带有可正常工作的 @mention）：
+```
+@元宝 你好，有人找你！
+```
+
+**就是这样。** 不需要额外的解释。保持简短和自然。
+
+**规则：**
+- 首先调用 `yb_query_group_members` 获取准确的昵称 —— 不要猜测
+- @mention 格式：`@nickname`，在 @ 符号前加一个空格
+- 你的回复文本就是最终消息 —— 它一定会被发送，并且 @mention 一定会生效
+- 保持简洁。不要向用户解释 @mention 是如何工作的。
+
+## 发送私信 (DM) 工作流
+
+当有人要求向用户发送私人消息 / 私信 / DM 时：
+
+1. 调用 `yb_send_dm`，传入 `group_code`、`name`（目标用户的名称）和 `message`
+2. 该工具会自动查找用户并发送私信
+3. 向用户报告结果
+
+示例：用户说 "给 @用户aea3 私信发一个 hello"
+
+```json
+yb_send_dm({ "group_code": "535168412", "name": "用户aea3", "message": "hello" })
+```
+
+附带媒体的示例：用户说 "给 @用户aea3 私信发一张图片"
+
+```json
+yb_send_dm({
+  "group_code": "535168412",
+  "name": "用户aea3",
+  "message": "Here is the image",
+  "media_files": [{"path": "/tmp/photo.jpg"}]
+})
+```
+
+**规则：**
+- 从当前的 chat_id 中提取 `group_code`（例如 `group:535168412` → `535168412`）
+- 如果你已经知道 user_id，直接通过 `user_id` 参数传入即可跳过查找
+- 如果多个用户匹配该名称，工具会返回候选人列表 —— 请要求用户明确指定
+- 不要使用 `send_message` 工具发送 Yuanbao 私信 —— 请改用 `yb_send_dm`
+- 支持媒体：图片 (.jpg/.png/.gif/.webp/.bmp) 作为图片消息发送，其他文件作为文档发送
+
+## 查询群组信息
+
+```json
+yb_query_group_info({ "group_code": "328306697" })
+```
+
+## 查询成员
+
+| Action | 说明 |
+| -------- | ------------- |
+| `find` | 按名称搜索（部分匹配，不区分大小写） |
+| `list_bots` | 列出机器人和 Yuanbao AI 助手 |
+| `list_all` | 列出所有成员 |
+
+## 说明
+
+- `group_code` 来源于 chat_id：`group:328306697` → `328306697`
+- 群组在 Yuanbao 应用中被称为“派 (Pai)”
+- 成员角色：`user`, `yuanbao_ai`, `bot`

package/extensions/skills/optional/DESCRIPTION.md

@@ -0,0 +1,22 @@
+# 可选 Skills
+
+由 Nous Research 维护的官方 skills，**默认不激活**。
+
+这些 skills 随 hermes-agent 仓库一起发布，但在设置过程中不会被复制到 `~/.hermes/skills/`。可以通过 Skills Hub 发现它们：
+
+```bash
+hermes skills browse               # browse all skills, official shown first
+hermes skills browse --source official  # browse only official optional skills
+hermes skills search <query>       # finds optional skills labeled "official"
+hermes skills install <identifier> # copies to ~/.hermes/skills/ and activates
+```
+
+## 为什么是可选的？
+
+一些 skills 虽然有用，但并不是每个用户都广泛需要：
+
+- **小众集成** — 特定的付费服务、专用工具
+- **实验性功能** — 很有前景但尚未经过充分验证
+- **重量级依赖** — 需要复杂的设置（API keys、安装步骤）
+
+通过将它们设为可选，我们在为有需要的用户提供经过挑选和测试的官方 skills 的同时，也保持了默认 skill 集合的精简。

package/extensions/skills/optional/autonomous-ai-agents/DESCRIPTION.md

@@ -0,0 +1 @@
+可选的自主 AI agent 集成 —— 可委派执行独立编程任务的外部编码 agent CLI。

package/extensions/skills/optional/autonomous-ai-agents/antigravity-cli/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: antigravity-cli
+description: "操作 Antigravity CLI (agy)：plugins、auth、sandbox。"
+version: 0.2.0
+author: Tony Simons (asimons81), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Coding-Agent, Antigravity, CLI, Auth, Plugins, Sandbox]
+    related_skills: [grok, codex, claude-code, hermes-agent]
+---
+
+# Antigravity CLI (`agy`)
+
+Antigravity CLI 的操作指南，通过 `agy` 调用。所有 `agy` 命令都需通过 Hermes 的 `terminal` 工具运行；使用 `read_file` 检查其配置和日志。此技能包含参考和操作流程——它不封装任何网络 API，因此不需要从 Hermes 本身进行任何身份验证。
+
+## 何时使用
+
+- 安装、更新或对 `agy` 二进制文件进行冒烟测试
+- 驱动非交互式的 `agy --print` / `agy -p` 一次性执行
+- 调试 Antigravity 的 auth、sandbox、权限或插件状态
+- 读取 Antigravity 的设置、按键绑定、会话或日志
+
+## 心智模型
+
+Antigravity 分为两层——请将它们区分开，否则指南将出现错误：
+
+1. **Shell wrapper commands** —— 如 `agy help`、`agy install`、`agy plugin`、`agy update`、`agy changelog`。请通过 `terminal` 工具运行这些命令。
+2. **Interactive in-session slash commands** —— 如 `/config`、`/permissions`、`/skills`、`/agents` 等。它们仅存在于运行中的 `agy` TUI 会话内，而不是在 shell wrapper 上。
+
+`agy help` 显示的是 shell wrapper 表面，而**不是**会话内的 slash commands。
+
+## 前置条件
+
+- PATH 中需包含 `agy` 二进制文件。可通过 `terminal` 工具验证：`command -v agy && agy --version`。
+- 此技能不需要任何环境变量或 API keys —— Antigravity 通过 OS keyring / 浏览器登录自行管理其认证（参见下文的 Authentication）。
+
+## 如何运行
+
+通过 `terminal` 工具调用每一条 `agy` 命令。示例：
+
+```
+terminal(command="agy --version")
+terminal(command="agy help")
+terminal(command="agy plugin list")
+terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")
+```
+
+对于交互式多轮 TUI 会话，需使用 `pty=true` 启动 `agy`（并配合 tmux 进行捕获/监控），这与 `codex` / `claude-code` 技能使用的模式相同。对于一次性冒烟测试和脚本化提示，推荐使用 `agy --print`（非交互式）。
+
+要检查 Antigravity 自身的文件，请对下方 Core paths 中的路径使用 `read_file` —— 不要通过终端执行 `cat`。
+
+## 委派模式
+
+`agy` 是一个 Coding-agent backend，与 `codex` / `claude-code` 属于同一系列，因此适用相同的委派模式。当需要将实际工作（功能、修复、审查、二次意见）交给 Antigravity 而不仅仅是进行冒烟测试时，请使用这些模式。
+
+### 一次性执行（推荐用于脚本化提示和二次意见）
+
+```
+terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300)
+```
+
+`-p` 是非交互式的：它运行提示后即退出。使用 `--model` 选择引擎（运行 `agy models` 获取确切的显示字符串，例如 `'Gemini 3.1 Pro (High)'`、`'Claude Opus 4.6 (Thinking)'`）。使用可重复的 `--add-dir` 添加额外的上下文根目录。
+
+### 长时间/有边界的运行（测试、构建、多文件修改）
+
+将其放入后台运行并在完成时获取通知，这与 `codex` 技能的做法相同：
+
+```
+terminal(command="agy -p 'Implement the change described in TASK.md and run the tests' --dangerously-skip-permissions", workdir="/path/to/repo", background=true, notify_on_complete=true)
+# then: process(action="poll"/"log"/"wait", session_id=<id>)
+```
+
+### 交互式多轮（PTY + tmux）
+
+要进行对话式会话，需在 `pty=true` 下启动 `agy -i`（或直接使用 `agy`），并配合 tmux 进行 `capture-pane` / `send-keys`，这与 `codex` / `claude-code` 技能中记录的模式完全一致。之后可以使用 `--continue` / `-c` 或指定的 `--conversation <id>` 恢复会话。
+
+### 并行实例（批量处理子 issue / worktree 扇出）
+
+为每个任务创建一个 git worktree，并在其中（后台）启动一个独立的 `agy -p`，然后收集结果——这与 `codex` 技能用于批量修复 issue 的 worktree 扇出模式相同。请将并发量限制在机器和您的审查能力所能承受的范围内。
+
+### 输出 + 边界注意事项（与 Claude Code 不同）
+
+- `agy -p` 返回**纯文本** —— **没有 `--output-format json`**，也没有包含 `session_id` / cost / turn count 的 result envelope。请直接解析 stdout；不要期望获得 JSON 对象。
+- **没有 `--max-turns`**。打印运行受 **`--print-timeout`**（默认为 `5m`）限制。对于长时间任务可提高该值：`--print-timeout 20m`。请配合 `terminal` 的 `timeout=` 使用，以免外层调用提前中断运行。
+
+### 编排边界
+
+Antigravity 是一个 **worker execution backend 或第三方意见审查者** —— 它是运行任务的 agent/profile 所拥有的执行细节，**而不是**一个一等编排原语。不要将 `agy` 作为独立的卡片放在看板上，也不要将其视为协调层；应通过常规任务图路由工作，并让分配的 worker 选择 `agy`（对比 codex/claude-code/直接使用工具）作为其方法。仅当用户主动要求、当 worker 被配置为封装它、或者您希望使用 Gemini 家族交叉检查另一个 agent 的计划或 diff 时，才明确使用它。
+
+## Core paths
+
+- Binary / entrypoint: `agy`
+- App data dir: `~/.gemini/antigravity-cli/`
+- Settings file: `~/.gemini/antigravity-cli/settings.json`
+- Keybindings file: `~/.gemini/antigravity-cli/keybindings.json`
+- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`
+- Conversations: `~/.gemini/antigravity-cli/conversations/`
+- Brain artifacts: `~/.gemini/antigravity-cli/brain/`
+- History: `~/.gemini/antigravity-cli/history.jsonl`
+- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`
+
+## 快速 参考
+
+### Wrapper commands
+- `agy changelog`
+- `agy help`
+- `agy install`
+- `agy plugin` / `agy plugins`
+- `agy update`
+
+### Useful flags
+- `--add-dir`
+- `--continue` / `-c`
+- `--conversation`
+- `--dangerously-skip-permissions`
+- `--print` / `-p`
+- `--print-timeout`
+- `--prompt`
+- `--prompt-interactive` / `-i`
+- `--sandbox`
+- `--log-file`
+- `--version`
+
+### Plugin subcommands (`agy plugin --help`)
+- `list`, `import [source]`, `install <target>`, `uninstall <name>`,
+  `enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`,
+  `help`
+
+### 安装 flags (`agy install --help`)
+- `--dir`, `--skip-aliases`, `--skip-path`
+
+### In-session slash commands
+- **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`),
+  `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`
+- **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`,
+  `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`,
+  `/usage`, `/logout`, `/agents`
+- **Prompt helpers:** `@` 路径自动补全，`esc esc` 清除提示（非流式传输时），
+  `!` 直接运行终端命令，`?` 打开帮助
+
+## 设置和权限
+
+### 常见设置键 (`settings.json`)
+- `allowNonWorkspaceAccess`
+- `colorScheme`
+- `permissions.allow`
+- `trustedWorkspaces`
+
+### 权限模式
+`request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`.
+
+### Sandbox 行为
+- `enableTerminalSandbox` 是 `settings.json` 中的布尔值；默认为 `false`。
+- 启动时的覆盖项（`--sandbox`、`--dangerously-skip-permissions`）可以取代当前会话的持久化设置。
+
+## Authentication 行为
+
+- CLI 会优先尝试 OS 安全密钥环 (keyring)。
+- 如果没有保存的会话，它会回退到基于浏览器的 Google 登录。
+- 在本地它会打开默认浏览器；在 SSH 下它会打印一个授权 URL，并要求将 auth code 粘贴回来。
+- `/logout` 会移除保存的凭据。
+
+## 插件
+
+- Plugins 暂存在 `~/.gemini/antigravity-cli/plugins/<plugin_name>/` 下。
+- 它们可以打包 skills、agents、rules、MCP servers 和 hooks。
+- `agy plugin list` 返回没有导入的插件属于正常的空状态。
+
+## 陷阱
+
+- `agy help` 显示的是 wrapper commands，而不是交互式的 slash commands。
+- `agy --version` 是安全的非交互式版本检查；`agy version` 是交互式的，在没有真实 TTY 的情况下可能会失败。
+- 遇到失败时首先查看的地方：`~/.gemini/antigravity-cli/log/cli-*.log`（使用 `read_file` 读取）。
+- 不要将持久化的 JSON 设置与启动时的覆盖项混淆。
+- `~/.gemini/antigravity-cli/bin/agentapi` 是指向 `agy agentapi` 的一个轻量级 wrapper。
+- 在 WSL 上，token 存储是基于文件的，因此认证问题通常是本地文件 / 会话状态的问题，而不仅仅是浏览器的问题。
+- Workspace 身份可能取决于启动目录和 `.antigravitycli` 项目标记。
+- `agy -p` 仅打印纯文本 —— 没有 `--output-format json`，没有 result envelope。不要尝试从中解析出 JSON 对象（与 `claude-code` 不同）。
+- 使用 `--print-timeout`（默认为 `5m`）限制打印运行，而不是 `--max-turns`（`agy` 中不存在此参数）。
+
+## 验证
+
+确认安装真实可用，所有操作均通过 `terminal` 工具进行（使用 `read_file` 读取文件）：
+
+1. `terminal(command="command -v agy")`
+2. `terminal(command="agy --version")`
+3. `terminal(command="agy help")`
+4. `terminal(command="agy plugin list")`
+5. 对 `~/.gemini/antigravity-cli/settings.json` 使用 `read_file`
+6. 对最新的 `~/.gemini/antigravity-cli/log/cli-*.log` 使用 `read_file`
+7. 如有需要，对 `~/.gemini/antigravity-cli/keybindings.json` 使用 `read_file`
+
+## 支持 files
+
+- `references/cli-docs.md` — 包含入门、使用和功能文档的精简笔记。