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 CLIagy的工作区参数从已被新版 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 仍有三个不可妥协的约束应用托管的 Antigravity 会话必须从当前激活的 vault启动该 vault 必须是 Antigravity 会话中唯一暴露的工作区避免 Agent 越界读写其他目录必须保留 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 原文为权限模式传递参数语义Safe--sandboxtrue --toolPermissionproceed-in-sandbox启用沙箱工具调用在沙箱内放行Power User--sandboxfalse --toolPermissionalways-proceed关闭沙箱工具调用总是放行此外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是决策的直接代码体现其组装逻辑为先调用ensure_workspace_mcp_config写入临时 MCP 配置见下文通过command_target_avoiding_windows_cmd_shim解析出可执行文件Windows 上避免命中agy.cmd的 shim 问题追加参数--input-format text显式声明以文本格式交互和--add-dir vault_path根据permission_mode应用权限参数设置环境NO_COLOR1强制无色输出便于解析、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_configsrc-tauri/src/antigravity_config.rs的写入逻辑体现了临时但可叠加的设计在vault/.agents/目录下创建或读取mcp_config.json向mcpServers对象中插入名为tolaria的 server 条目由tolaria_node_mcp_server生成包含 node 启动命令与WS_UI_PORT9711等环境变量保留文件中已存在的其他 server测试workspace_mcp_config_preserves_other_servers验证了这一点避免覆盖用户或 Antigravity 自身已有的 MCP 配置若现有配置结构非法如mcpServers是数组而非对象直接报错拒绝启动避免生成损坏配置。权限映射的后续演进ADR-0159 修正了参数形态需要特别说明的是ADR-0151 的权限参数映射后来被 ADR-0159部分取代supersedes: 0151。原因是 Antigravity CLI 上游再次变更新版构建不定义--toolPermission且--sandbox是布尔开关而非--sandboxvalue赋值形式——继续传旧参数会再次导致flags provided but not defined。因此当前仓库代码的实际映射是权限模式当前代码传递参数Safe--sandbox布尔开关开启沙箱Power User--dangerously-skip-permissionsCLI 官方支持的无沙箱直通参数build_command中的apply_permission_flagssrc-tauri/src/antigravity_config.rs正是按此实现Safe 分支只追加--sandboxPower User 分支追加--dangerously-skip-permissions。这与 ADR-0151回避--dangerously-skip-permissions的原文表述存在演进关系——ADR-0159 在--add-dir决策保持不变的前提下依据 CLI 最新能力修订了权限直通方式并明确要求适配器测试必须拒绝重新引入不支持的 Antigravity 参数。这个演进链条本身就是很好的工程示范工作区参数--add-dir与权限参数是两条独立的契约线上游每次变化都通过新的 ADR 记录而不是在代码里静默改 flag。二进制发现与错误处理应用托管会话要能启动前提是找到agy可执行文件。antigravity_discovery.rssrc-tauri/src/antigravity_discovery.rs按三级顺序探测PATH 查找通过whichWindows 用where定位agy登录 shell 查找依次探测$SHELL、/bin/zsh、/bin/bash执行command -v agy获取路径覆盖 GUI 应用 PATH 不含 CLI 安装目录的常见情况常见安装位置兜底包括~/.local/bin/agy、Windows 的AppData/Local/agy/bin/agy.exe、npm/pnpm shimAppData/Roaming/npm/agy.cmd等、scoop shim、/opt/homebrew/bin/agy、Linuxbrew 路径等src-tauri/src/antigravity_discovery.rs。运行时错误处理位于antigravity_cli.rssrc-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 CLIrun_agent_stream_uses_supported_antigravity_workspace_flagsrc-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考