From 51bff3ed73d0f773e6c5ede0ad2e475e97b39182 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E6=A2=93=E6=81=92?= <160735726+3361559784@users.noreply.github.com> Date: Mon, 27 Apr 2026 15:31:02 +0800 Subject: [PATCH] chore(agent): add computer-use-mcp agent governance (#1737) Co-authored-by-agent: Antigravity --- .github/ISSUE_TEMPLATE/ai-task.md | 49 ++++++++++++++++++++++++++ .github/copilot-instructions.md | 30 ++++++++++++++++ services/computer-use-mcp/AGENTS.md | 53 ++++++++++++++++++++++++++++- 3 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/ai-task.md create mode 100644 .github/copilot-instructions.md diff --git a/.github/ISSUE_TEMPLATE/ai-task.md b/.github/ISSUE_TEMPLATE/ai-task.md new file mode 100644 index 000000000..7b3a9e6c0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ai-task.md @@ -0,0 +1,49 @@ +--- +name: AI task +about: Narrow task suitable for Codex, Copilot, or another coding agent +title: "[AI task]: " +labels: ai-copilot-ok, ai-small +assignees: "" +--- + +## Task + +One narrow task. + +## Allowed scope + +- Files/directories: `` + +## Forbidden scope + +- Do not touch package files or lockfiles unless explicitly required. +- Do not touch unrelated services, docs, or agent configuration. +- Do not touch security-sensitive logic unless this issue is specifically about that boundary. +- Do not broaden into architecture cleanup. + +## Expected behavior + +Describe the expected behavior or evidence target. + +## Validation + +Run the narrowest relevant command first: + +```bash +pnpm -F exec vitest run +``` + +If runtime contracts changed, also run: + +```bash +pnpm -F typecheck +``` + +## Output required + +- Files changed +- Commands run +- Exit codes +- Relevant pass/fail output +- Remaining risks +- Keep / revert / split recommendation diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..f9804f4fc --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,30 @@ +# Copilot repository instructions + +This is the `moeru-ai/airi` pnpm monorepo. Prefer the smallest safe change and keep every task inside its stated scope. + +## General rules + +- Follow the root `AGENTS.md` instructions. +- Do not modify unrelated files. +- Do not mix documentation, agent configuration, and runtime logic changes in one patch. +- Do not change package files, lockfiles, or workspace configuration unless the task explicitly requires it. +- Preserve existing test style and helpers. +- Do not claim tests passed unless you actually ran them. +- Report exact commands, exit codes, and relevant pass/fail output. + +## Validation + +- Use package-scoped pnpm commands where possible. +- Run the narrowest relevant test first. +- Run typecheck if runtime contracts or exported types changed. +- Run affected package tests if shared logic changed. +- Run `git diff --check` before finalizing when possible. + +## Output format + +1. Confirmed facts +2. Files changed +3. Commands run +4. Test results +5. Remaining risks +6. Keep / revert / split recommendation diff --git a/services/computer-use-mcp/AGENTS.md b/services/computer-use-mcp/AGENTS.md index 30ae7d9c2..c4939b7e5 100644 --- a/services/computer-use-mcp/AGENTS.md +++ b/services/computer-use-mcp/AGENTS.md @@ -10,6 +10,31 @@ Scope: `services/computer-use-mcp/**` - `computer-use-mcp` owns execution primitives, workflow orchestration, terminal/browser/desktop surfaces, trace, audit, and safety checks. - Treat terminal, browser, editor, and desktop operations as one task system. Do not split them into disconnected demos. +## Agent Collaboration Policy + +This policy is scoped to `services/computer-use-mcp/**`. Do not copy it into the +monorepo-level `AGENTS.md` as a global AIRI rule: other packages may not have +the same runtime risk profile, Spark agent setup, or review workflow. + +Use `GPT-5.5 Controller + Spark / mini Read-only Worker Pool` as the default +shape for non-trivial work in this package. + +- GPT-5.5 owns problem boundaries, conflicting evidence resolution, patch decisions, verification commands, and final judgment. +- Spark agents should be used more aggressively for read-only parallel work: code-path exploration, test-gap discovery, current-diff review, CI failure triage, and PR-split planning. +- If Spark is unavailable or quota-exhausted, use the GPT-5.4-mini read-only fallback workers for the same exploration, test-gap, and diff-review roles. +- Spark output must include concrete file paths and evidence. Treat unsupported Spark claims as guesses, not facts. +- Spark and mini workers are read-only by default. Do not let them write runtime, verification gate, coding runner, MCP permission-boundary, action-executor, or critical state-machine code unless the user explicitly asks for a writer agent. +- The main thread must re-check Spark findings against code/tests before editing. Test and runtime logs outrank every model conclusion. +- Keep `.codex/` agent configuration decisions separate from business-code PRs unless the PR is explicitly about contributor workflow. +- Treat GitHub Copilot as an external worker pool only: external review, candidate PRs, test-gap issues, and documentation cleanup. Do not trust or merge Copilot output without GPT-5.5 review. +- Prefer Copilot `gpt-5.4-mini` with high effort for routine external-worker tasks. Escalate hard Copilot-side reviews to `gpt-5.3-codex` with high effort. +- Use Copilot GPT-5 mini and GPT-4.1 aggressively for low-risk, high-frequency external work: broad file triage, repeated search, test-gap brainstorming, docs consistency checks, low-risk cleanup proposals, and extra diff-review opinions. +- Keep Copilot GPT-5 mini / GPT-4.1 in plan/review mode by default. They can propose patches or commands, but GPT-5.5 must verify against repository facts before any local edit is made. +- Treat Gemini CLI as a local external research/review worker only: large-context impact scanning, diff review, test-failure log analysis, Copilot PR third-party review, and documentation/instruction consistency checks. +- Let Gemini CLI choose its model unless there is a task-specific reason to pin one. Use Gemini while its daily quota is available; if it is exhausted, route the external-worker task to Copilot instead. +- Do not let Gemini CLI edit the same worktree concurrently with Codex. If Gemini needs to write candidate code, use a separate worktree and require GPT-5.5 review before adopting any patch. +- Keep Copilot governance files, `.codex/` configuration, GitHub labels, and business/runtime changes in separate commits or PRs. + ## Current Status Snapshot Updated for the current terminal-lane-v2 workstream. @@ -18,13 +43,20 @@ The important truth is: - `exec` is already a real mainline surface. - `PTY` is no longer just a loose tool set; the workflow engine now has self-acquire support. -- The service-layer terminal E2Es are green. +- Service-layer terminal E2Es for the current lane are present and treated as the terminal proof line. - The AIRI chat terminal demo is now aligned with terminal lane v2 and no longer pre-creates PTY. - The desktop shell now distinguishes `pty_session` from `terminal_and_apps`. - AIRI chat self-acquire is now part of the strict release gate set, so PTY mainline support is no longer intentionally held back. Do not rely on compressed chat summaries to resume this work. Use this file as the handoff source of truth and update it when terminal-lane behavior changes materially. +For terminal-lane facts, treat this file in alignment with: + +- `README.md` +- `src/support-matrix.ts` +- `package.json` scripts +- implementation/tests for each referenced command or file + ## Terminal Lane v2: What Is Already Landed ### 1. Terminal surface model exists @@ -216,3 +248,22 @@ If those four facts are stale, the next agent will lose time re-deriving context - Keep provider-specific behavior in AIRI / `packages/stage-ui/**`. - Keep OS-executor and workflow orchestration logic here. - Do not expand this workstream into browser, native click/type/press, or VS Code productization until terminal lane is actually closed. + +## Agent Operating Guardrails + +- Keep changes narrow and evidence-backed. +- Keep documentation/config changes separate from runtime logic changes. +- Do not touch desktop overlay, Electron bridge, Chrome extension, MCP handler registration, workspace memory, verification gate, or shell guard unless the task explicitly requires it. +- Keep planning, archive eligibility, compaction text, provider message emission, and runner semantics separate unless evidence requires a cross-layer change. +- Prefer pure helpers for shared contracts. +- Add regression tests for boundary behavior. +- Do not broaden refactors without evidence. +- Do not treat parser-level coverage as proof that projected provider messages are valid; add projector-level tests when the final message shape is the contract. + +## Agent Report Checklist + +- Exact files changed. +- Exact test command. +- Exit code. +- Relevant pass/fail output. +- Remaining risks and why they are out of scope.