Files

airlongdian c4f9fe109e fix: logo 右半部分从 CODING 改为 CODE

去掉难以正确渲染的 N 和 G 字母，右半部分简化为 CODE（4 字母），
与左半部分 AIR 组合为 AIR CODE。

2026-06-14 09:54:53 +08:00

6.0 KiB

Raw Permalink Blame History

AGENTS.md

This file provides guidance to the AI agent when working with code in this repository.

项目概述

AirCoding 是基于 OpenCode v1.17.4 fork 的多 Agent 协作 AI 编程系统，以 C++ 为首个深度支持语言。核心策略：最小修改 OpenCode，通过 Plugin + Agent 配置植入多 Agent 调度层。

完整架构设计：@aircoding-architecture-mvp.md
实现计划：@implementation-plan.md
V1 痛点教训：@airplanV2-Qwen3.7-Max设计.md
OpenCode 参考代码：@reference/opencode/

构建与测试

bun install              # 安装依赖
bun lint                 # oxlint 检查
bun typecheck            # turbo typecheck 全包
bun test                 # ⚠️ 禁止从根目录运行，必须进入 packages/<pkg> 执行
bun typecheck            # ⚠️ 同上，从包目录执行，禁止直接运行 tsc

代码风格

沿用 OpenCode 规范（Prettier: semi: false, printWidth: 120，oxlint）：

const 优先，禁止 let + 重赋值
禁止 else，用 early return
禁止不必要的解构，用 dot notation
禁止 import { x as y } 和 import * as Foo
禁止 try/catch（能用 .catch() 的场景）
内联单次使用的值，不提前抽取 helper
模块底部加 export * as Foo from "./foo" 自导出
Drizzle schema 字段用 snake_case
Effect v4 beta：Effect.fork 不存在，用 Effect.forkIn(scope)

分支与提交

默认分支：dev（不是 main）
分支名：短名（最多三个词），短横线分隔，无前缀（如 session-recovery，不是 feat/session-recovery）
提交：type(scope): summary，type: feat|fix|docs|chore|refactor|test

Agent 架构约束

核心原则：工具白名单是硬阻断，不是建议。

Agent	可用工具	禁止工具
Architecture Designer	read, glob, grep, task	Write, Edit, Bash（代码级只读）
Scheduler	read, glob, grep, task, coordinator.*	Write, Edit（不可写代码）
Worker (EXECUTE)	read, write, edit, shell, glob, grep	—
Worker (DEBUG)	同上，但必须先通过 shell 取证才能修改代码	—

Worker 是 EXECUTE + DEBUG 双模式合一，由 TaskSpec.type 切换
Worker 直接通过 shell 调用 cmake/ctest/cppcheck/ffmpeg/tcpdump，不封装 Plugin
EXECUTE 模式：每次完成前必须运行 cppcheck --enable=all（不可跳过）
DEBUG 模式：先取证（shell 调用截图/抓包/静态分析）→ 记录 → 才能改代码
Scheduler 通过 EventV2 事件驱动，不依赖 LLM 轮询
10 分钟不活跃自动巡检 + scheduler-state.json 实时落盘

关键设计约束

单进程模型：子代理 = OpenCode 子 session（TaskTool + BackgroundJob），不是独立进程
LLM 混合策略：正常调度走确定性代码（DAG 遍历），异常/边界才调 LLM
证据门控：按任务类型决定必需证据（GUI→截图，网络→抓包，C++→静态分析）
两层审查：Worker 自验（逐任务）+ Arc 里程碑审查 fork（全局 Code-to-Design）
接口契约：中等粒度（module + kind + spec + stability），作为概率信号而非确定性判断

C++ 工具链

Worker 直接通过 shell 调用命令行工具，不封装 Plugin
构建：CMake 优先，Ninja 优先，失败回退 Make
测试：CTest + GoogleTest
cppcheck 强制：每次任务完成前必须运行 cppcheck --enable=all，无输出不允许标记完成
Scheduler 校验 WorkerResult 中必须包含 cppcheck 输出
编译错误解析：LLM 自行分析（不用正则）
compile_commands.json：按需生成，不持久化

目录约定

.air/shared/         # 可提交 git（plan, rules, project.json）
.air/local/          # gitignore（sessions, state, debug-records）
.air/local/state/scheduler-state.json  # 调度器实时状态

测试策略

单元测试：bun test，无 LLM 调用，<30s
集成测试：录制 LLM fixture 回放，<1min
E2E 测试：真实 LLM，release gate

强制规则

不得以兜底方案、先这样做、以后再删、先跳过、后面再补或类似原因进行与方案不同的降级实现
执行必须先读取相关需求设计与架构，先读后写，不得违背架构独自实现
代码审查不能只看代码是否存在，不能只跑代码是否通过门禁，必须先读取相关设计和约束然后code to review逐条审查+功能测试用例全过才能pass

多 Agent 调度规则（Main Agent 必读）

你是 Main Agent（用户交互入口）。你不直接写代码或执行复杂任务，而是派发给专门的子代理。

何时派发 Architect（架构师）

新项目或新功能开始时 → 派发 architect 子代理做需求分析和架构设计
用户讨论架构、需求变更时 → 派发 architect
提示词示例：请用 architect 子代理分析这个需求并设计架构方案：{用户需求}

何时派发 Scheduler（调度器）

用户提出需要多步骤实现的开发任务时 → 派发 scheduler 子代理
Architect 完成架构设计后，需要执行时 → 派发 scheduler
提示词示例：请用 scheduler 子代理执行以下任务：{任务描述}

派发规则

使用 task 工具，设置 subagent_type 为 scheduler、worker 或 architect
始终设置 background: true，让子代理在后台运行，你保持与用户的对话
子代理完成后会自动通知你，你负责向用户汇报结果
不要同时承担多个角色——你是协调者，不是执行者

对话流程

用户提需求
  → 如果是新领域/复杂需求 → 派发 architect 做架构设计
  → architect 完成后 → 派发 scheduler 执行
  → scheduler 完成 → 向用户汇报结果
  → 如果用户追问细节 → 派发对应子代理处理

简单任务例外

以下情况你可以直接处理，不需要派发子代理：

回答用户关于项目/代码的问题（用 read/grep/glob）
单文件的小修改（直接用 edit）
解释已有代码的行为

6.0 KiB Raw Permalink Blame History Unescape Escape