企业官网建设流程全解析

Tolaria 中的 Antigravity CLI 工作区参数迁移：从--cwd到--add-dir的适配器演进

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

本文以 Tolaria 仓库的 ADR-0151 为核心，讲解桌面端 AI 面板如何将 Antigravity CLI（agy）的工作区参数从已被新版 CLI 废弃的--cwd迁移到--add-dir，并贯穿权限模式映射、MCP 配置注入与适配器测试的完整闭环。读完本文，你将掌握 Tolaria 为第三方 CLI Agent 适配器制定"命令参数契约"的方法论，以及当上游 CLI 破坏性变更时，如何通过 ADR 决策 + 源码实现 + 回归测试三者联动来安全演进。

背景：--cwd工作区方案为何失效

ADR-0147 首次为 Tolaria 引入了 Antigravity CLI 适配器。该决策将产品侧的本地 Agent id 定为antigravity（旧存储值gemini会在读取时归一化，见 src/lib/aiAgents.ts），并规定应用托管的 Antigravity 会话通过以下命令启动：

agy -p <prompt> --cwd <vault>

问题出在上游版本演进：新版 Antigravity CLI 构建已不再定义--cwd工作区参数，直接启动会得到如下报错：

flags provided but not defined: -cwd

新版 CLI 将--add-dir列为受支持的工作区目录参数。与此同时，Tolaria 仍有三个不可妥协的约束：

1. 应用托管的 Antigravity 会话必须从当前激活的 vault启动；
2. 该 vault 必须是 Antigravity 会话中唯一暴露的工作区，避免 Agent 越界读写其他目录；
3. 必须保留 ADR-0103 定义的 Safe / Power User 权限模式映射——权限模式在 Tolaria 中首先是产品契约，再按每个适配器保守地翻译成 CLI 参数。

这三个约束决定了迁移不是简单替换一个 flag，而是要在保持工作目录语义、MCP 配置注入和权限契约不变的前提下，仅调整"声明工作区"的方式。

决策：用--add-dir声明 Antigravity 工作区

ADR-0151 的决策非常明确：Tolaria 启动应用托管的 Antigravity 会话时，使用如下命令形态：

agy -p <prompt> --add-dir <vault>

同时保持两条语义不变：

• 子进程current_dir仍为 active vault 路径：即进程工作目录与显式工作区目录是同一个 vault，双保险确保 Agent 的运行根基就是当前笔记库；
• 启动前仍将临时 MCP 配置写入<vault>/.agents/mcp_config.json：让 Antigravity 会话通过 Tolaria 的 MCP server 访问 vault 内容。

权限模式的映射（按 ADR-0151 原文）为：

此外，Tolaria 依然坚决回避--dangerously-skip-permissions：即使 Power User 模式也不会使用该"跳过全部权限"的危险参数（注：这一条在后续 ADR-0159 中因 CLI 上游再次变更而有了新的处理方式，详见下文）。

源码实现：命令是如何被组装出来的

ADR-0151 的决策在 Rust 后端落地为两个模块：antigravity_config.rs负责组装命令，antigravity_cli.rs负责流式运行与错误格式化。

build_command：工作区参数与运行环境的组装

src-tauri/src/antigravity_config.rs 中的build_command是决策的直接代码体现，其组装逻辑为：

1. 先调用ensure_workspace_mcp_config写入临时 MCP 配置（见下文）；
2. 通过command_target_avoiding_windows_cmd_shim解析出可执行文件（Windows 上避免命中agy.cmd的 shim 问题）；
3. 追加参数--input-format text（显式声明以文本格式交互）和--add-dir <vault_path>；
4. 根据permission_mode应用权限参数；
5. 设置环境：NO_COLOR=1（强制无色输出，便于解析）、current_dir指向 vault 路径、stdin/stdout/stderr 分别挂接。

从源码可以看到一个关键细节：ADR-0151 决策文本中的-p <prompt>并非通过命令行参数传递。提示词实际由antigravity_cli.rs通过 stdin 喂给子进程——build_prompt将系统提示与用户消息拼装成System instructions: ...与User request: ...两块文本后写入 stdin（见 src-tauri/src/cli_agent_runtime.rs）。对应测试command_uses_stdin_prompt_transport_and_workspace_mcp_config明确断言：命令行中不得出现-p或消息正文，但必须出现--add-dir <vault>，且不得出现--cwd。

临时 MCP 配置的写入策略

write_workspace_mcp_config（src-tauri/src/antigravity_config.rs）的写入逻辑体现了"临时但可叠加"的设计：

• 在<vault>/.agents/目录下创建或读取mcp_config.json；
• 向mcpServers对象中插入名为tolaria的 server 条目（由tolaria_node_mcp_server生成，包含 node 启动命令与WS_UI_PORT=9711等环境变量）；
• 保留文件中已存在的其他 server（测试workspace_mcp_config_preserves_other_servers验证了这一点），避免覆盖用户或 Antigravity 自身已有的 MCP 配置；
• 若现有配置结构非法（如mcpServers是数组而非对象），直接报错拒绝启动，避免生成损坏配置。

权限映射的后续演进：ADR-0159 修正了参数形态

需要特别说明的是：ADR-0151 的权限参数映射后来被 ADR-0159部分取代（supersedes: "0151"）。原因是 Antigravity CLI 上游再次变更：新版构建不定义--toolPermission，且--sandbox是布尔开关而非--sandbox=<value>赋值形式——继续传旧参数会再次导致"flags provided but not defined"。

因此当前仓库代码的实际映射是：

build_command中的apply_permission_flags（src-tauri/src/antigravity_config.rs）正是按此实现：Safe 分支只追加--sandbox，Power User 分支追加--dangerously-skip-permissions。这与 ADR-0151"回避--dangerously-skip-permissions"的原文表述存在演进关系——ADR-0159 在--add-dir决策保持不变的前提下，依据 CLI 最新能力修订了权限直通方式，并明确要求"适配器测试必须拒绝重新引入不支持的 Antigravity 参数"。

这个演进链条本身就是很好的工程示范：工作区参数（--add-dir）与权限参数是两条独立的契约线，上游每次变化都通过新的 ADR 记录，而不是在代码里静默改 flag。

二进制发现与错误处理

应用托管会话要能启动，前提是找到agy可执行文件。antigravity_discovery.rs（src-tauri/src/antigravity_discovery.rs）按三级顺序探测：

1. PATH 查找：通过which（Windows 用where）定位agy；
2. 登录 shell 查找：依次探测$SHELL、/bin/zsh、/bin/bash，执行command -v agy获取路径，覆盖 GUI 应用 PATH 不含 CLI 安装目录的常见情况；
3. 常见安装位置兜底：包括~/.local/bin/agy、Windows 的AppData/Local/agy/bin/agy.exe、npm/pnpm shim（AppData/Roaming/npm/agy.cmd等）、scoop shim、/opt/homebrew/bin/agy、Linuxbrew 路径等（src-tauri/src/antigravity_discovery.rs）。

运行时错误处理位于antigravity_cli.rs（src-tauri/src/antigravity_cli.rs）：子进程 stderr 若命中auth、api key、login、oauth、token、unauthorized等关键词，会被判定为认证/安装类问题，返回面向用户的恢复性提示"Runagyin your terminal to finish install and sign-in, then retry in Tolaria"；其余情况截取 stderr 前 3 行展示。stdout 则被逐行解析为 AI 面板的文本增量事件，会话 id 统一以antigravity-为前缀。

测试如何锁定参数契约

ADR-0151 的 Consequences 明确要求"适配器测试必须拒绝重新引入--cwd或遗漏--add-dir的回归"。仓库中的 Rust 单元测试用伪造的agy可执行脚本（shell 脚本解析参数）验证了这一点，无需真实安装 Antigravity CLI：

• run_agent_stream_uses_supported_antigravity_workspace_flag（src-tauri/src/antigravity_cli.rs）：伪造脚本若收到--cwd、--toolPermission*或--sandbox=<值>格式即报"flags provided but not defined"并退出；若未收到--add-dir同样失败。只有当参数组合完全符合 ADR-0151/0159 契约时才输出 "Antigravity accepted flags"——测试通过即证明当前适配器参数与上游 CLI 兼容；
• command_uses_stdin_prompt_transport_and_workspace_mcp_config：断言--add-dir <vault>存在、--cwd不存在、--sandbox以布尔形式（而非--sandbox=）传入、current_dir等于 vault、.agents/mcp_config.json已生成；
• power_user_command_uses_antigravity_permission_bypass_flag：断言 Power User 模式追加--dangerously-skip-permissions且不出现--sandbox/--toolPermission。

此外还有针对 MCP 配置健壮性的测试（保留已有 server、拒绝非法结构），以及发现模块对 Windows shim 优先、跨平台安装路径的覆盖。这套测试即"参数契约的可执行化"——上游一旦再次改动 flag，跑一次测试即可第一时间暴露回归。

影响与后续演进边界

综合 ADR-0151 与后续决策，可以总结该迁移带来的确定影响：

• 兼容性恢复：拒绝--cwd的 Antigravity CLI 版本可以在 Tolaria AI 面板中正常启动会话；
• 工作区收敛：active vault 同时是子进程工作目录与 Antigravity 显式工作区，确保 Agent 只以当前笔记库为操作边界；
• 契约可测试：任何重新引入--cwd或移除--add-dir的改动都会被测试拦截；
• 演进有记录：未来 Antigravity CLI 工作区参数再变化时，应通过新的 ADR 决策并同步更新测试，而不是在代码中静默替换 flag——ADR-0159 对权限参数的修订正是这一流程的实例。

对于希望接入其他 CLI Agent 的开发者，本 ADR 连同 ADR-0147、ADR-0103 构成了一套可复用的适配器设计模式：用 ADR 固化产品契约，用源码模块隔离命令组装，用伪造二进制测试锁定参数形态，从而在第三方 CLI 快速迭代的环境中保持应用托管会话的稳定与安全。

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria