Orca 工程规范全解：AGENTS.md 如何约束一个三端并行的 Electron 多智能体开发环境

Orca 工程规范全解：AGENTS.md 如何约束一个三端并行的 Electron 多智能体开发环境

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca

Orca 的仓库根目录 AGENTS.md 是一份面向 AI 协作与人类贡献者共同的工程宪法：它规定设计系统取舍、代码风格边界、验证命令，以及跨平台、SSH、Git 兼容性等高风险区域的硬性约束。本篇以该文档为骨架逐节展开，并结合 package.json、src/shared/child-process/run-process.ts、src/shared/wsl-login-shell-command.ts 等源码印证每条规则背后的真实实现，读完你会掌握 Orca 的完整验证链路（pnpm tc/pnpm test/ oxlint 体系）、Windows/WSL/Linux 三平台的进程与命令边界，以及 Git 能力探测与远程线协议兼容的设计原则。

项目背景：Orca 是什么，为什么需要这份规范

Orca 的定位是"管理并行智能体舰队的 ADE（Agent Development Environment）"——package.json 中描述为Next-gen IDE for parallel agentic development，支持在用户自己的订阅上运行任意编码智能体，覆盖桌面、移动端与远程运行时。这意味着它的代码同时运行在三类宿主上：

• 原生桌面宿主：Electron 主进程（src/main/，含 369 个文件的daemon/、316 个文件的ssh/、198 个文件的github/等模块）；
• WSL 发行版：通过wsl.exe执行用户环境中的 Git 与 shell；
• SSH 远程主机：通过 src/main/ssh/ 的通道执行远端工作。

加上独立的 mobile/ Expo 工程与 cloud/ 中继服务，同一个仓库内并存 Electron、浏览器、Node、移动、云五类运行时。AGENTS.md 的绝大多数条款——跨平台行为、远程线兼容、Git 二进制兼容——正是为这种"一仓多宿主"结构而写：它们不是风格偏好，而是防止在 A 宿主上验证通过的改动在 B 宿主上崩溃的护栏。

设计系统：token 唯一真源与解析顺序

AGENTS.md 开篇即声明设计系统规则：所有 UI 工作（布局、颜色、字体、间距、组件选型、UX 行为）必须遵循 docs/STYLEGUIDE.md；颜色与排版 token 以 src/renderer/src/assets/main.css 为唯一真源（canonical source），组件基元取自src/renderer/src/components/ui/下的 shadcn primitives；禁止在已有 token 覆盖该角色时新造颜色值、字号或阴影层级。当 STYLEGUIDE.md 未覆盖某场景时，按该文档最后一节的解析顺序（resolution order）处理。

这与依赖声明互相印证：package.json 的 devDependencies 中包含shadcn、tailwindcss、radix-ui、class-variance-authority、tailwind-merge，说明 Orca 的组件体系正是 Tailwind v4 + Radix + shadcn 的 token 驱动方案。对贡献者的实操含义是：改 UI 前先在 main.css 中检索是否已有对应 token，而不是新增硬编码值。

紧随其后的Electron UI Validation条款规定：渲染后 Orca UI 的验证应使用$electronskill 与 Playwright CDP，禁止使用 computer-use 做 Orca UI 验证。这与 tests/playwright.config.ts 中的electron-headless/electron-headful两个 project 对应——仓库中大量test:e2e:*脚本（如 package.json 的test:e2e定义）都显式指定--project electron-headless，即通过 CDP 协议直接驱动 Electron 渲染进程，而非像素级操作模拟。

代码风格四条军规

AGENTS.md 的 Style 部分给出四条规则，每一条都有对应的机械化检查。

先复用，再重写（Reuse Before Reimplementing）

任何规模的改动——函数、组件、IPC 通道、状态 store 乃至整个子系统——动手前先检查是否已有实现（或近乎满足的实现）；有则扩展或泛化，没有才从零写。且检查必须与成本相称：琐碎代码快速搜一下即可，构建重要模块前必须认真检索。这条规则直击多宿主仓库的通病：src/main/ipc/已有 978 个文件，src/shared/有 1761 个文件，不先检索几乎必然写出平行实现。

注释只写非显然的 WHY

不写冗长注释、不解释显然内容、不逐行走读代码（"WHY not HOW"），能一句话说清就不写两行。在 src/shared/child-process/run-process.ts 中可以看到该规范的执行样本：常量PROCESS_EXIT_GRACE_MS上方用一段"Why give up at all"解释为何要放弃等待子进程退出，但全部聚焦动机而非机制。

禁止禁用 max-lines

绝不添加任何形式的max-lines禁用（eslint-disable max-lines、oxlint-disable max-lines或行级变体），也绝不修改 mobile/.oxlintrc.json 中按文件放宽max-lines的值。配套的机械化实现是 ratchet（棘轮）机制：config/max-lines-baseline.txt 的头部注释明确写着——

This is a RATCHET: the list may only SHRINK. Do NOT add entries to get CI green — split the oversized file instead (AGENTS.md → "Do Not Disable Max Lines").

即基线清单只允许缩短、不允许变长，超限文件必须拆分而非豁免。CI 侧由pnpm check:max-lines-ratchet（对应 config/scripts/check-max-lines-ratchet.mjs）与--prune参数（仅移除失效条目）执行。同类的棘轮还有check:ts-nocheck-ratchet与check:runtime-electron-ratchet，在 package.json 的lint脚本中串联执行。

文件命名：拒绝 helpers / utils / common

禁止用helpers、utils、common、misc等零信息命名，文件应按其实际内容命名，优先具体领域概念（tab-group-state.ts、terminal-orphan-cleanup.ts）而非泛化角色（tabs-helpers.ts、terminal-utils.ts）。文档给出的诊断法值得注意："当你想叫helpers时，这个文件多半承担了多个职责，应该拆分；或者代码里藏着一个更好的名字，能描述这些函数真正操作的对象。"从src/shared/child-process/目录的实际命名可以验证该规范落地：bounded-output-sink.ts、process-tree-termination.ts、retryable-process-exit-proof.ts——每个文件名都是其职责的精确陈述。

此外文档要求类型声明优先.ts而非.d.ts（该节在原文中仅有标题，具体判据留待 STYLEGUIDE 与仓库惯例）。

验证变更的标准链路

AGENTS.md 给出三条日常验证命令，全部可在 package.json 中逐一对应：

格式化统一为pnpm format（底层是oxfmt --write .）。值得注意 package.json 中lint-staged配置：提交时对!(cloud)/**的 ts/tsx/js/json/css 文件依次执行oxlint、oxlint --config config/oxlint-react-doctor.json（React 专项规则）、oxfmt --write，即风格规则在钩子层就已强制执行，而engines.node = 24、packageManager = pnpm@12.0.0则框定了验证环境的前提。

跨平台约束：从规范条文到源码实现

AGENTS.md 篇幅最重的部分。核心前提是：Orca 面向 macOS、Linux、Windows 三端，所有平台相关行为必须藏在运行时检查之后。文档逐条列出约束，以下结合源码展开。

键盘快捷键：平台探测 + CmdOrCtrl

永不硬编码e.metaKey；用平台检查（如navigator.userAgent.includes('Mac')）在 Mac 上选metaKey、在 Linux/Windows 上选ctrlKey；Electron 菜单 accelerator 一律用CmdOrCtrl。UI 显示层同理：Mac 显示⌘/⇧，其他平台显示Ctrl+/Shift+。

文件路径：永远用 path 工具

使用path.join或 Electron/Node 的路径工具，绝不假设/或\分隔符。

Windows 子进程：runProcess / spawnProcess 是唯一入口

这是 AGENTS.md 中证据链最完整的一条：Windows 子进程必须经 src/shared/child-process/ 的runProcess/spawnProcess启动，永不直接child_process。其承诺是：固定windowsHide、拒绝shell: true、编码.cmd/.bat参数，使CommandLineToArgvW与cmd.exe都无法篡改参数；且"一个 ratchet 测试会对任何新的直接 import 失败"。

run-process.ts 的resolveSpawn函数把三条承诺全部落实，且注释解释了"为什么"：

• windowsHide: true无条件开启——因为 Orca 主进程是 GUI 子系统、不拥有控制台，任何它启动的控制台子系统子进程都会抢出一个可见的 conhost 黑窗抢占前台，"那一刻敲进 Orca 终端的按键会落进黑盒里"；
• shell: false硬编码——shell: true会无转义拼接参数（Node 官方警告 DEP0190），并静默使windowsHide失效；
• .cmd/.bat程序被重定向为ComSpec（cmd.exe）+buildWindowsCmdShimCommandLine构造的单条命令行，并置windowsVerbatimArguments: true——因为 Node 出于 CVE-2024-27980 缓解拒绝在无 shell 下 spawn.cmd，必须自己拼命令行才能既保住参数完整又藏住控制台。

边界由 src/shared/child-process/child-process-import-boundary.test.ts 守护，这正是文档所说的"任何新直接 import 都会让 ratchet 测试失败"的实现。

Windows 进程枚举：一张表取代七个 PowerShell 读者

AGENTS.md 规定：读取进程表必须走 src/main/windows/windows-process-table.ts，永不 forkpowershell.exe，并指向 docs/reference/windows-process-enumeration.md。

该模块的头部注释（windows-process-table.ts）给出了完整的动机与实测数据：此前有七个独立读者各自 forkpowershell.exe跑Get-CimInstance Win32_Process（外加已被 Windows 11 24H2 移除的wmic回退），后果是 PowerShell 转录策略录下约 289 GB / 140 万个文件（扫描约每 2 秒一次）、组策略或 AV 拦截把"查询不可用"误读为"无证据"从而让 PTY 进程树存活过自己的拆除、以及约 700 ms 的单次成本随终端面板数线性放大。改为本模块后，用 Toolhelp32 快照在同一问题域上无子进程作答：在 Windows 11（1050 进程）实测 p50/p95 为15.9 / 17.5 ms（pid+ppid+name）、30.6 / 33.7 ms（加 memory+commandLine），而 PowerShell CIM 是706 / 723 ms。从源码结构看，该模块通过 optionalDependency@vscode/windows-process-tree的getAllProcesses完成快照，这正是 AGENTS.md 该条目的量化支撑。

Windows EDR 行为姿态

在 docs/reference/windows-edr-posture.md 之前，不要添加-ExecutionPolicy Bypass、-EncodedCommand、带转义自由文本的cmd.exe /c、按操作 spawn 解释器、或运行时Add-Type编译——行为型 EDR 对每一项单独评分，"已签名"并不能豁免。这条约束的含义是：任何看似无害的 Windows 脚本形态变化都会改变终端用户的 EDR 评分，改动前必须先读参考文档。

WSL 命令：--exec与登录 shell 围栏

AGENTS.md 要求：argv 必须用buildWslExecArgs构造（永远--exec——因为在--之后，wsl.exe会在每个参数里展开$name，静默改写脚本）；对需要解析 stdout 的命令用buildWslCapturedLoginShellCommand加围栏，因为交互式登录 shell 会把发行版 banner 打到 stdout。

两个函数在 src/shared/wsl-login-shell-command.ts 中实现，源码注释给出了具体失效模式：

• buildWslExecArgs（L15-L20）返回['-d', distro?, '--exec', ...shellArgs]。注释举例：wsl.exe -- /usr/bin/printf %s '$HOME'会打印出/home/you，因为wsl.exe在参数进入 guest 前就做了环境变量展开——awk '{print $2}'这类脚本会被悄悄改掉，"我们这边再怎么转义都不可靠"；而--exec跳过该预处理，argv 原样通过。
• buildWslCapturedLoginShellCommand（L71 起）则解决相反方向的问题：bash/zsh 必须交互式（-ilc）才能让 PATH 匹配用户自己的终端（nvm/mise/asdf 都装在只有交互式 shell 才读的 rc 文件里），但交互式 shell 又跑 rc/motd，stock Ubuntu 会把"以管理员运行"的提示写到stdout。方案是生成一次性 nonce 围栏标记__ORCA_WSL_CAPTURE_BEGIN_<nonce>__/__ORCA_WSL_CAPTURE_END_<nonce>__，调用方按标记切片取真正的载荷。nonce 每次调用随机生成（注释说明：cat一个恰好引用了固定标记的文件会截断文件内容，一次性 nonce 是唯一能同时保证标记不在前置 rc 输出与后置数据中的写法）。

shell 选择逻辑也值得注意：先getent passwd查用户真实 shell，bash/zsh/ksh/mksh/ash 用-ilc，sh/dash 用-lc（避免 dash 下交互模式的噪音），找不到则逐级回退到/bin/sh -lc。

Linux 原生模块：glibc 地板 2.31

Linux 原生模块保持 glibc 地板为Ubuntu 20.04 / glibc 2.31。风险机制：在新版 runner 上从源码编译的模块可能引用地板版本上不存在的符号版本，导致应用在老系统上启动即崩。详见 docs/reference/linux-glibc-compatibility.md；打包流程若发现某个打包原生二进制需要更新的 glibc 会直接失败——对应脚本 config/scripts/verify-linux-glibc-floor.cjs。Windows 侧的 setup/issue 脚本同理：runner 是.cmd批处理文件（除非脚本以#!开头），永不从用户的终端 shell 偏好推导，也永不在 Git Bash 面板里用裸cmd.exe /c启动.cmd（MSYS 会改写/c），细节见 docs/reference/windows-setup-shell.md。

SSH 执行边界：失联不是死亡

AGENTS.md 规定：所有变更必须考虑 SSH 场景，不要假设只有本地执行。在改动任何"上报、停止或列出远端工作"的代码前，先读 docs/reference/ssh-execution-boundary.md，其核心原则是：

1. 执行宿主拥有一切接触执行的东西——判断、状态、清理都归执行宿主所有；
2. 失联永不是进程死亡的证据——verdict 词汇表只有三个词：live/unverifiable/exited，且不允许同义词。

这条规则对实现的影响可以从src/shared/child-process/的测试文件名读出影子：retryable-process-exit-proof.ts、close-process-registry.ts等模块处理的是"如何证明进程真的退了"而非"进程大概还在"，与unverifiable语义一脉相承。

工作区形态：folder workspace 与 git worktree 并存

"所有变更必须同时考虑 folder workspace 与 git worktree，不要假设每个 workspace 都是 git worktree。"Orca 的 workspace 抽象既覆盖 git worktree（src/main/git/，266 个文件）也覆盖普通文件夹工作区，任何依赖.git元数据存在的代码路径都必须为文件夹形态留出路。

远程线兼容：新旧版本混合是常态

客户端与远端 Orca 服务器独立升级，混合版本是正常状态。改动任何成对客户端与宿主交换的内容（RPC 参数、流帧、任一侧发布的内容）前，须遵循 docs/reference/remote-wire-compatibility.md。文档给出三条精确的兼容判据：

• 新增可选字段是安全的——旧解码器忽略未知字段即可；
• 新增流 opcode 必须走能力协商（capability negotiation）——因为旧解码器会静默丢弃未知 opcode，不协商就发帧等于丢数据且无人报错；
• 改变宿主发布的内容，即使线格式不变也会触达旧客户端——内容语义是隐式协议的一部分。

Git 二进制兼容：2.25 基线与能力缓存

Orca 在原生、WSL、SSH 三类宿主上运行用户自己的Git 二进制，版本可能各不相同。AGENTS.md 规定以Git 2.25为核心工作流基线，细则见 docs/reference/git-compatibility.md。新增或改动 Git 命令时须遵守五条：

1. 查清每个子命令与选项的引入版本；对更新的行为保留基线兼容回退或安全降级；
2. 使用GitCapabilityCache并配窄的"不支持"错误谓词，让重复操作不再重试已知无效的命令；不要只信git --version——simple-git之类的封装并不消除宿主版本差异；
3. 能力状态按执行 Git 的宿主隔离：原生、WSL 发行版、SSH provider、relay 连接各自一份。测试须覆盖首次回退、后续缓存调用、并发探测、宿主隔离四个维度；
4. 保持 PR CI 中的真二进制兼容契约最新：采用新 Git 特性时，加上版本边界，让首选命令与回退命令都针对代表性 Git 发行版运行；
5. 保留以全局选项开头的命令形态，如子命令前的-c（worktree-create fetch 使用的 auto-maintenance 抑制依赖它）。

Git 扫描安全：拒绝 ref × tree 扇出

三条操作性规则，直指大规模仓库上的性能陷阱：

• 永不枚举全部 ref 后对每个 ref 各跑一次git ls-tree -r或git show——这种 ref × tree 扇出可能在下游sort -u或检索取得进展前保留数 GB 输出；
• 源码检索优先rg；查历史或 ref 时用命名 ref、显式 namespace/path、--max-count与有界输出，不要把无界--all扫描当作首选诊断；
• 仓库级命令限定在当前仓库与 worktree；确需无界扫描时，先测量 ref 数量、说明代价、取得确认再执行。

提供者兼容与 CLI 限流

最后两条横向约束：GitLab 与其他支持的 git provider 必须与 GitHub 同等对待——provider 特定行为放在显式检查之后，通用 review 概念禁用 GitHub-only 命名（对应仓库中gitlab/、bitbucket/、gitea/、azure-devops/、github/五个并行的 provider 模块）；留意用户ghCLI 的 API 速率限制——批量请求、避免不必要调用，且所有代码、命令、脚本必须同时兼容 macOS、Linux、Windows。

结语：把规范变成可执行的护栏

AGENTS.md 的真正价值不在条文本身，而在每条条文几乎都对应一个机械化检查：max-lines规则对应 config/max-lines-baseline.txt 与check:max-lines-ratchet；child_process直接 import 禁令对应 child-process-import-boundary.test.ts；glibc 地板对应 verify-linux-glibc-floor.cjs；Git 2.25 基线对应 PR CI 中的真二进制兼容契约。对新贡献者的最佳路径是：先通读 AGENTS.md 与其引用的 docs/reference/ 系列文档，按"先检索复用 → 遵循 token 与命名规范 →pnpm tc/pnpm test/check:code-quality:changed三步验证"的闭环工作，并始终用"这条改动在 WSL、SSH 宿主、旧版客户端上是否依然成立"作为自检问题。

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca