docs: 默认 README 改为中文，英文改为 README.en.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
AirCoding
141
README.en.md
Normal file
141
README.en.md
Normal file
@@ -0,0 +1,141 @@
|
|||||||
|
<p align="center">
|
||||||
|
<h1 align="center">AirCoding</h1>
|
||||||
|
</p>
|
||||||
|
<p align="center">Deterministic Multi-Agent AI Coding System</p>
|
||||||
|
<p align="center">
|
||||||
|
<a href="http://git.airlongdian.fun/admin/AirCoding"><img alt="Gitea" src="https://img.shields.io/badge/Gitea-AirCoding-blue?style=flat-square" /></a>
|
||||||
|
<a href="http://git.airlongdian.fun/admin/AirCoding/releases/tag/0.1.0"><img alt="Release" src="https://img.shields.io/badge/release-0.1.0-green?style=flat-square" /></a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="README.md">简体中文</a> |
|
||||||
|
<a href="README.en.md">English</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
AirCoding is a semi-automated development agent I built based on my own workflow. Its main goal is to solve Vibe Coding's core problems — poor code quality and high model requirements — through an engineering-driven approach. The aim is to use low-cost models concurrently to complete small to medium-sized projects.
|
||||||
|
|
||||||
|
This idea has just barely gotten off the ground. Due to time constraints, the Alpha release is a fork of opencode with direct modifications. It's still constrained by opencode's framework and far from the ideal design. Bugs are plenty — I'll fix them as I find them. It works well enough for now.
|
||||||
|
|
||||||
|
When I have more free time, I'll need to build an agent from scratch. The current framework imposes too many limitations.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Acknowledgments
|
||||||
|
|
||||||
|
Thanks to Player Xiao Zhang for calling me while I was on the toilet, which cleared my mind.
|
||||||
|
|
||||||
|
Thanks to Mr. Ran, Mr. Ze, Mr. Ding, and Mr. Zhe for enduring a 10-game losing streak in League of Legends while playing with me. This is the power of friendship and bonds — I'm going to find an Evolution Crystal to super-evolve as repayment.
|
||||||
|
|
||||||
|
Thanks in advance to Mr. Fan Xiaowen, who is currently researching Go for building agent frameworks. I plan to steal his work once he's done (doge).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
The following is AI-generated.
|
||||||
|
|
||||||
|
## ## OOvveerrvviieeww
|
||||||
|
|
||||||
|
Core design principles:
|
||||||
|
|
||||||
|
- **Tool whitelist as hard gate**: Agent capabilities are enforced at the code level, not by prompt suggestion
|
||||||
|
- **Deterministic scheduling first**: Normal flow runs through a DAG state machine; LLM is consulted only for exceptions and edge cases
|
||||||
|
- **Two-layer review**: Worker self-verification + Reviewer Code-to-Design audit
|
||||||
|
- **Evidence-gated debugging**: cppcheck mandatory (C++ projects); must collect evidence before modifying code (DEBUG mode)
|
||||||
|
- **Anti-fallback**: Scheduler and Executor are forbidden from using "for now", "temporary solution", or any downgrade pattern to replace the design spec
|
||||||
|
- **Mandatory Reviewer**: Reviewer is not optional — every Worker output goes through a three-layer review (Code-to-Design → Static Analysis → Test Verification) before it can pass
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
User → Main Agent (aircoding) → dispatches
|
||||||
|
│
|
||||||
|
├─→ Architect (architecture planner)
|
||||||
|
│ Outputs: plan.md + task-graph.json + ADR + C4 docs
|
||||||
|
│
|
||||||
|
└─→ Scheduler (scheduling engine)
|
||||||
|
│ coordinator_tick: deterministic DAG scheduler
|
||||||
|
│
|
||||||
|
├─→ Worker (executor / debugger)
|
||||||
|
│ EXECUTE: write code → compile → test → cppcheck
|
||||||
|
│ DEBUG: collect evidence → record → fix → verify
|
||||||
|
│
|
||||||
|
└─→ Reviewer (code reviewer)
|
||||||
|
Code-to-Design review against plan.md
|
||||||
|
Three mandatory layers:
|
||||||
|
1. Line-by-line Code-to-Design table
|
||||||
|
2. Static analysis (security / correctness / compliance)
|
||||||
|
3. Test / build verification
|
||||||
|
```
|
||||||
|
|
||||||
|
## Agent Permission Matrix
|
||||||
|
|
||||||
|
| Agent | Allowed Tools | Denied Tools |
|
||||||
|
|-------|--------------|--------------|
|
||||||
|
| aircoding (Main) | read, glob, grep, task, question, web, coordinator_status, coordinator_tick | write, edit, bash |
|
||||||
|
| Scheduler | read, glob, grep, task, coordinator_* | write, edit, bash |
|
||||||
|
| Worker | read, write, edit, bash, glob, grep | task |
|
||||||
|
| Architect | read, glob, grep, task, edit/write (.air/shared/plan/**) | bash, source file write |
|
||||||
|
| Reviewer | read, glob, grep | write, edit, bash, task |
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
### Binary (Linux x64)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Download release
|
||||||
|
wget http://git.airlongdian.fun/admin/AirCoding/releases/download/0.1.0/AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
||||||
|
tar xzf AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
||||||
|
cd AirCoding-Alpha-0.1.0 && ./install.sh
|
||||||
|
|
||||||
|
aircoding --version # → 0.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
The binary installs to `~/.aircoding/` and does not conflict with opencode (`~/.opencode/`).
|
||||||
|
|
||||||
|
### Build from Source
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bun install # install dependencies
|
||||||
|
bun typecheck # type check (29 packages, all pass)
|
||||||
|
cd packages/opencode && OPENCODE_VERSION="0.1.0" OPENCODE_CHANNEL="aircoding" bun run script/build.ts --single --skip-embed-web-ui
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Convention
|
||||||
|
|
||||||
|
```
|
||||||
|
.air/shared/plan/plan.md # architecture plan (Architect output)
|
||||||
|
.air/shared/plan/task-graph.json # task graph (Architect output, Scheduler reads)
|
||||||
|
.air/shared/plan/docs/ADR-*.md # architecture decision records
|
||||||
|
.air/shared/plan/docs/c4/ # C4 model docs
|
||||||
|
.air/local/state/scheduler-state.json # scheduler state (realtime persistence)
|
||||||
|
.air/local/debug/debug-log.md # debug log
|
||||||
|
```
|
||||||
|
|
||||||
|
## Design Docs
|
||||||
|
|
||||||
|
Detailed design documents are in `docs/`:
|
||||||
|
|
||||||
|
- [Architecture Design MVP](docs/aircoding-architecture-mvp.md)
|
||||||
|
- [V2 Implementation Plan](docs/implementation-plan.md)
|
||||||
|
- [V2 Design (detailed)](docs/airplanV2-Qwen3.7-Max设计.md)
|
||||||
|
- [V1 Baseline](docs/baselineV1.md)
|
||||||
|
- [Agent Constraints](docs/AGENTS.md)
|
||||||
|
- [Integration Notes](docs/INTEGRATION.md)
|
||||||
|
|
||||||
|
## Key Constraints (Iron Rules)
|
||||||
|
|
||||||
|
See `CLAUDE.md` for the full constraint specification. Summary:
|
||||||
|
|
||||||
|
1. **Scheduler**: No fallback implementations. Must fully follow design specs. If the design doesn't cover a scenario, dispatch Architect to update the design first — never self-adjudicate in code.
|
||||||
|
2. **Executor (Worker)**: No "get it working first / fix later" downgrades. Compile → test → cppcheck all mandatory. Fallback language in output = auto-FAIL.
|
||||||
|
3. **Reviewer**: Mandatory, not optional. "Tests pass" / "function exists" / "build passed" are not valid reasons to PASS. Must produce a line-by-line Code-to-Design table. Coordinator code gates enforce this deterministically.
|
||||||
|
4. **Architect loop prevention**: Milestone review has a 2-per-phase / 5-global dispatch budget with `milestone_satisfied` gate to prevent infinite architect dispatch loops.
|
||||||
|
|
||||||
|
## Acknowledgments
|
||||||
|
|
||||||
|
Forked from [OpenCode](https://github.com/anomalyco/opencode) v1.17.4.
|
||||||
140
README.md
140
README.md
@@ -1,93 +1,95 @@
|
|||||||
<p align="center">
|
<p align="center">
|
||||||
<h1 align="center">AirCoding</h1>
|
<h1 align="center">AirCoding</h1>
|
||||||
</p>
|
</p>
|
||||||
<p align="center">Deterministic Multi-Agent AI Coding System</p>
|
<p align="center">确定性优先、LLM 为辅的多 Agent 协作半自动并发 AI 编程系统</p>
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<a href="http://git.airlongdian.fun/admin/AirCoding"><img alt="Gitea" src="https://img.shields.io/badge/Gitea-AirCoding-blue?style=flat-square" /></a>
|
<a href="http://git.airlongdian.fun/admin/AirCoding"><img alt="Gitea" src="https://img.shields.io/badge/Gitea-AirCoding-blue?style=flat-square" /></a>
|
||||||
<a href="http://git.airlongdian.fun/admin/AirCoding/releases/tag/0.1.0"><img alt="Release" src="https://img.shields.io/badge/release-0.1.0-green?style=flat-square" /></a>
|
<a href="http://git.airlongdian.fun/admin/AirCoding/releases/tag/0.1.0"><img alt="Release" src="https://img.shields.io/badge/release-0.1.0-green?style=flat-square" /></a>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<a href="README.md">English</a> |
|
<a href="README.md">简体中文</a> |
|
||||||
<a href="README.zh.md">简体中文</a>
|
<a href="README.en.md">English</a>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Overview
|
## ## 概概述述
|
||||||
|
|
||||||
AirCoding is a semi-automated development agent I built based on my own workflow. Its main goal is to solve Vibe Coding's core problems — poor code quality and high model requirements — through an engineering-driven approach. The aim is to use low-cost models concurrently to complete small to medium-sized projects.
|
AirCoding 是我基于自己工作流做的一个半自动开发 Agent ，其主要目的在于以工程化的思路解决 Vibe Coding 交付代码差、对模型性能要求高的问题，旨在用低成本的模型并发完成中小项目开发。
|
||||||
|
|
||||||
This idea has just barely gotten off the ground. Due to time constraints, the Alpha release is a fork of opencode with direct modifications. It's still constrained by opencode's framework and far from the ideal design. Bugs are plenty — I'll fix them as I find them. It works well enough for now.
|
目前这个想法刚刚搓通，而且因为时间问题，Alpha版本是 fork opencode 直接改的，受限于opencode的框架还没能完全实现理想的设计，bug估计也不少，发现一个改一个先凑合用吧。
|
||||||
|
|
||||||
When I have more free time, I'll need to build an agent from scratch. The current framework imposes too many limitations.
|
等多会闲下来还是得自己从头搓 Agent ，现有方案制约太大了。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Acknowledgments
|
## 致谢
|
||||||
|
|
||||||
Thanks to Player Xiao Zhang for calling me while I was on the toilet, which cleared my mind.
|
感谢玩家小张在我拉屎时和我打电话，令我思路畅通。
|
||||||
|
|
||||||
Thanks to Mr. Ran, Mr. Ze, Mr. Ding, and Mr. Zhe for enduring a 10-game losing streak in League of Legends while playing with me. This is the power of friendship and bonds — I'm going to find an Evolution Crystal to super-evolve as repayment.
|
感谢mr冉，mr泽，mr丁，mr哲打LOL时被我坑到十连败，这就是友情和羁绊的力量啊，我准备找个进化水晶超进化一下以示报答。
|
||||||
|
|
||||||
Thanks in advance to Mr. Fan Xiaowen, who is currently researching Go for building agent frameworks. I plan to steal his work once he's done (doge).
|
提前感谢 mr樊小文 ，因为他最近在研究 go 语言搓 Agent 框架，我准备等他做完偷来用（doge
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
The following is AI-generated.
|
以下为 AI 生成
|
||||||
|
|
||||||
## ## OOvveerrvviieeww
|
## 概述
|
||||||
|
|
||||||
Core design principles:
|
AirCoding 是一个**确定性调度为主、LLM 为辅**的多 Agent 协作编程框架，C++ 为首个深度支持语言。
|
||||||
|
|
||||||
- **Tool whitelist as hard gate**: Agent capabilities are enforced at the code level, not by prompt suggestion
|
核心设计原则：
|
||||||
- **Deterministic scheduling first**: Normal flow runs through a DAG state machine; LLM is consulted only for exceptions and edge cases
|
|
||||||
- **Two-layer review**: Worker self-verification + Reviewer Code-to-Design audit
|
|
||||||
- **Evidence-gated debugging**: cppcheck mandatory (C++ projects); must collect evidence before modifying code (DEBUG mode)
|
|
||||||
- **Anti-fallback**: Scheduler and Executor are forbidden from using "for now", "temporary solution", or any downgrade pattern to replace the design spec
|
|
||||||
- **Mandatory Reviewer**: Reviewer is not optional — every Worker output goes through a three-layer review (Code-to-Design → Static Analysis → Test Verification) before it can pass
|
|
||||||
|
|
||||||
## Architecture
|
- **工具白名单是硬阻断**：每层 Agent 的能力由代码级权限控制，不依赖 Prompt 约束
|
||||||
|
- **确定性调度优先**：正常流程走 DAG 状态机，异常和边界才调 LLM
|
||||||
|
- **两层审查**：Worker 自验 + Reviewer Code-to-Design 审查
|
||||||
|
- **证据门控**：cppcheck 强制（C++ 项目），取证后才能改代码（DEBUG 模式）
|
||||||
|
- **禁降级兜底**：调度器和执行器严禁以「先这样」「先跑通」「以后再改」「for now」「temporary solution」等任何理由使用降级方案代替设计实现
|
||||||
|
- **审查器强制调用**：审查器不可跳过、不可默认通过，必须逐行对照设计方案后，再经静态审查和测试验证，全部通过才能放行
|
||||||
|
|
||||||
|
## 架构
|
||||||
|
|
||||||
```
|
```
|
||||||
User → Main Agent (aircoding) → dispatches
|
用户 → Main Agent (aircoding) → 协调派发
|
||||||
│
|
│
|
||||||
├─→ Architect (architecture planner)
|
├─→ Architect（架构规划器）
|
||||||
│ Outputs: plan.md + task-graph.json + ADR + C4 docs
|
│ 产出：plan.md + task-graph.json + ADR + C4 文档
|
||||||
│
|
│
|
||||||
└─→ Scheduler (scheduling engine)
|
└─→ Scheduler（调度引擎）
|
||||||
│ coordinator_tick: deterministic DAG scheduler
|
│ coordinator_tick 确定性 DAG 调度
|
||||||
│
|
│
|
||||||
├─→ Worker (executor / debugger)
|
├─→ Worker（执行器 / 调试器）
|
||||||
│ EXECUTE: write code → compile → test → cppcheck
|
│ EXECUTE: 写代码 → 编译 → 测试 → cppcheck
|
||||||
│ DEBUG: collect evidence → record → fix → verify
|
│ DEBUG: 取证 → 记录 → 修复 → 验证
|
||||||
│
|
│
|
||||||
└─→ Reviewer (code reviewer)
|
└─→ Reviewer（代码审查器）
|
||||||
Code-to-Design review against plan.md
|
对照 plan.md 做 Code-to-Design 审查
|
||||||
Three mandatory layers:
|
三层强制流程：
|
||||||
1. Line-by-line Code-to-Design table
|
1. Code-to-Design 逐行对照表
|
||||||
2. Static analysis (security / correctness / compliance)
|
2. 静态审查（安全性 / 正确性 / 合规性）
|
||||||
3. Test / build verification
|
3. 测试 / 构建验证
|
||||||
```
|
```
|
||||||
|
|
||||||
## Agent Permission Matrix
|
## Agent 权限矩阵
|
||||||
|
|
||||||
| Agent | Allowed Tools | Denied Tools |
|
| Agent | 可用工具 | 禁止工具 |
|
||||||
|-------|--------------|--------------|
|
|-------|---------|---------|
|
||||||
| aircoding (Main) | read, glob, grep, task, question, web, coordinator_status, coordinator_tick | write, edit, bash |
|
| aircoding (Main) | read, glob, grep, task, question, web, coordinator_status, coordinator_tick | write, edit, bash |
|
||||||
| Scheduler | read, glob, grep, task, coordinator_* | write, edit, bash |
|
| Scheduler | read, glob, grep, task, coordinator_* | write, edit, bash |
|
||||||
| Worker | read, write, edit, bash, glob, grep | task |
|
| Worker | read, write, edit, bash, glob, grep | task |
|
||||||
| Architect | read, glob, grep, task, edit/write (.air/shared/plan/**) | bash, source file write |
|
| Architect | read, glob, grep, task, edit/write (.air/shared/plan/**) | bash, 源代码文件写 |
|
||||||
| Reviewer | read, glob, grep | write, edit, bash, task |
|
| Reviewer | read, glob, grep | write, edit, bash, task |
|
||||||
|
|
||||||
## Install
|
## 安装
|
||||||
|
|
||||||
### Binary (Linux x64)
|
### 二进制（Linux x64）
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Download release
|
# 下载发布包
|
||||||
wget http://git.airlongdian.fun/admin/AirCoding/releases/download/0.1.0/AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
wget http://git.airlongdian.fun/admin/AirCoding/releases/download/0.1.0/AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
||||||
tar xzf AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
tar xzf AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
||||||
cd AirCoding-Alpha-0.1.0 && ./install.sh
|
cd AirCoding-Alpha-0.1.0 && ./install.sh
|
||||||
@@ -95,47 +97,47 @@ cd AirCoding-Alpha-0.1.0 && ./install.sh
|
|||||||
aircoding --version # → 0.1.0
|
aircoding --version # → 0.1.0
|
||||||
```
|
```
|
||||||
|
|
||||||
The binary installs to `~/.aircoding/` and does not conflict with opencode (`~/.opencode/`).
|
二进制安装到 `~/.aircoding/`，与 opencode（`~/.opencode/`）互不冲突。
|
||||||
|
|
||||||
### Build from Source
|
### 从源码构建
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun install # install dependencies
|
bun install # 安装依赖
|
||||||
bun typecheck # type check (29 packages, all pass)
|
bun typecheck # 类型检查（29 包，全部通过）
|
||||||
cd packages/opencode && OPENCODE_VERSION="0.1.0" OPENCODE_CHANNEL="aircoding" bun run script/build.ts --single --skip-embed-web-ui
|
cd packages/opencode && OPENCODE_VERSION="0.1.0" OPENCODE_CHANNEL="aircoding" bun run script/build.ts --single --skip-embed-web-ui
|
||||||
```
|
```
|
||||||
|
|
||||||
## Directory Convention
|
## 目录约定
|
||||||
|
|
||||||
```
|
```
|
||||||
.air/shared/plan/plan.md # architecture plan (Architect output)
|
.air/shared/plan/plan.md # 架构方案（Architect 产出）
|
||||||
.air/shared/plan/task-graph.json # task graph (Architect output, Scheduler reads)
|
.air/shared/plan/task-graph.json # 任务图（Architect 产出，Scheduler 执行）
|
||||||
.air/shared/plan/docs/ADR-*.md # architecture decision records
|
.air/shared/plan/docs/ADR-*.md # 架构决策记录
|
||||||
.air/shared/plan/docs/c4/ # C4 model docs
|
.air/shared/plan/docs/c4/ # C4 模型文档
|
||||||
.air/local/state/scheduler-state.json # scheduler state (realtime persistence)
|
.air/local/state/scheduler-state.json # 调度器状态（实时落盘）
|
||||||
.air/local/debug/debug-log.md # debug log
|
.air/local/debug/debug-log.md # 调试记录
|
||||||
```
|
```
|
||||||
|
|
||||||
## Design Docs
|
## 设计文档
|
||||||
|
|
||||||
Detailed design documents are in `docs/`:
|
详细设计文档在 `docs/` 目录：
|
||||||
|
|
||||||
- [Architecture Design MVP](docs/aircoding-architecture-mvp.md)
|
- [架构设计 MVP](docs/aircoding-architecture-mvp.md)
|
||||||
- [V2 Implementation Plan](docs/implementation-plan.md)
|
- [V2 实现计划](docs/implementation-plan.md)
|
||||||
- [V2 Design (detailed)](docs/airplanV2-Qwen3.7-Max设计.md)
|
- [V2 设计（详细）](docs/airplanV2-Qwen3.7-Max设计.md)
|
||||||
- [V1 Baseline](docs/baselineV1.md)
|
- [V1 基线](docs/baselineV1.md)
|
||||||
- [Agent Constraints](docs/AGENTS.md)
|
- [Agent 约束规则](docs/AGENTS.md)
|
||||||
- [Integration Notes](docs/INTEGRATION.md)
|
- [集成说明](docs/INTEGRATION.md)
|
||||||
|
|
||||||
## Key Constraints (Iron Rules)
|
## 约束铁律
|
||||||
|
|
||||||
See `CLAUDE.md` for the full constraint specification. Summary:
|
详见 `CLAUDE.md`。摘要：
|
||||||
|
|
||||||
1. **Scheduler**: No fallback implementations. Must fully follow design specs. If the design doesn't cover a scenario, dispatch Architect to update the design first — never self-adjudicate in code.
|
1. **调度器**：禁止降级兜底，必须完全遵循设计方案。设计未覆盖的场景先派 Architect 更新设计，不得在代码中自行裁决。
|
||||||
2. **Executor (Worker)**: No "get it working first / fix later" downgrades. Compile → test → cppcheck all mandatory. Fallback language in output = auto-FAIL.
|
2. **执行器**：禁止以「先跑通」「以后再改」「以后补上」「for now」「fix later」等理由使用简化实现。编译→测试→cppcheck 三步不可跳过。输出含降级措辞直接 FAIL。
|
||||||
3. **Reviewer**: Mandatory, not optional. "Tests pass" / "function exists" / "build passed" are not valid reasons to PASS. Must produce a line-by-line Code-to-Design table. Coordinator code gates enforce this deterministically.
|
3. **审查器**：强制调用，不可跳过。「测试 pass」「函数存在」「build 通过」不得作为 PASS 依据。必须输出 Code-to-Design 逐行对照表。代码门确定性执行此规则。
|
||||||
4. **Architect loop prevention**: Milestone review has a 2-per-phase / 5-global dispatch budget with `milestone_satisfied` gate to prevent infinite architect dispatch loops.
|
4. **防无限循环**：Architect 里程碑审查设有 每阶段2次 / 全局5次 的派发预算 + `milestone_satisfied` 门控，防止 Scheduler 和 Architect 之间无限循环。
|
||||||
|
|
||||||
## Acknowledgments
|
## 致谢
|
||||||
|
|
||||||
Forked from [OpenCode](https://github.com/anomalyco/opencode) v1.17.4.
|
基于 [OpenCode](https://github.com/anomalyco/opencode) v1.17.4 fork。
|
||||||
|
|||||||
143
README.zh.md
143
README.zh.md
@@ -1,143 +0,0 @@
|
|||||||
<p align="center">
|
|
||||||
<h1 align="center">AirCoding</h1>
|
|
||||||
</p>
|
|
||||||
<p align="center">确定性优先、LLM 为辅的多 Agent 协作半自动并发 AI 编程系统</p>
|
|
||||||
<p align="center">
|
|
||||||
<a href="http://git.airlongdian.fun/admin/AirCoding"><img alt="Gitea" src="https://img.shields.io/badge/Gitea-AirCoding-blue?style=flat-square" /></a>
|
|
||||||
<a href="http://git.airlongdian.fun/admin/AirCoding/releases/tag/0.1.0"><img alt="Release" src="https://img.shields.io/badge/release-0.1.0-green?style=flat-square" /></a>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<a href="README.md">English</a> |
|
|
||||||
<a href="README.zh.md">简体中文</a>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ## 概概述述
|
|
||||||
|
|
||||||
AirCoding 是我基于自己工作流做的一个半自动开发 Agent ，其主要目的在于以工程化的思路解决 Vibe Coding 交付代码差、对模型性能要求高的问题，旨在用低成本的模型并发完成中小项目开发。
|
|
||||||
|
|
||||||
目前这个想法刚刚搓通，而且因为时间问题，Alpha版本是 fork opencode 直接改的，受限于opencode的框架还没能完全实现理想的设计，bug估计也不少，发现一个改一个先凑合用吧。
|
|
||||||
|
|
||||||
等多会闲下来还是得自己从头搓 Agent ，现有方案制约太大了。
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 致谢
|
|
||||||
|
|
||||||
感谢玩家小张在我拉屎时和我打电话，令我思路畅通。
|
|
||||||
|
|
||||||
感谢mr冉，mr泽，mr丁，mr哲打LOL时被我坑到十连败，这就是友情和羁绊的力量啊，我准备找个进化水晶超进化一下以示报答。
|
|
||||||
|
|
||||||
提前感谢 mr樊小文 ，因为他最近在研究 go 语言搓 Agent 框架，我准备等他做完偷来用（doge
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
以下为 AI 生成
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
AirCoding 是一个**确定性调度为主、LLM 为辅**的多 Agent 协作编程框架，C++ 为首个深度支持语言。
|
|
||||||
|
|
||||||
核心设计原则：
|
|
||||||
|
|
||||||
- **工具白名单是硬阻断**：每层 Agent 的能力由代码级权限控制，不依赖 Prompt 约束
|
|
||||||
- **确定性调度优先**：正常流程走 DAG 状态机，异常和边界才调 LLM
|
|
||||||
- **两层审查**：Worker 自验 + Reviewer Code-to-Design 审查
|
|
||||||
- **证据门控**：cppcheck 强制（C++ 项目），取证后才能改代码（DEBUG 模式）
|
|
||||||
- **禁降级兜底**：调度器和执行器严禁以「先这样」「先跑通」「以后再改」「for now」「temporary solution」等任何理由使用降级方案代替设计实现
|
|
||||||
- **审查器强制调用**：审查器不可跳过、不可默认通过，必须逐行对照设计方案后，再经静态审查和测试验证，全部通过才能放行
|
|
||||||
|
|
||||||
## 架构
|
|
||||||
|
|
||||||
```
|
|
||||||
用户 → Main Agent (aircoding) → 协调派发
|
|
||||||
│
|
|
||||||
├─→ Architect（架构规划器）
|
|
||||||
│ 产出：plan.md + task-graph.json + ADR + C4 文档
|
|
||||||
│
|
|
||||||
└─→ Scheduler（调度引擎）
|
|
||||||
│ coordinator_tick 确定性 DAG 调度
|
|
||||||
│
|
|
||||||
├─→ Worker（执行器 / 调试器）
|
|
||||||
│ EXECUTE: 写代码 → 编译 → 测试 → cppcheck
|
|
||||||
│ DEBUG: 取证 → 记录 → 修复 → 验证
|
|
||||||
│
|
|
||||||
└─→ Reviewer（代码审查器）
|
|
||||||
对照 plan.md 做 Code-to-Design 审查
|
|
||||||
三层强制流程：
|
|
||||||
1. Code-to-Design 逐行对照表
|
|
||||||
2. 静态审查（安全性 / 正确性 / 合规性）
|
|
||||||
3. 测试 / 构建验证
|
|
||||||
```
|
|
||||||
|
|
||||||
## Agent 权限矩阵
|
|
||||||
|
|
||||||
| Agent | 可用工具 | 禁止工具 |
|
|
||||||
|-------|---------|---------|
|
|
||||||
| aircoding (Main) | read, glob, grep, task, question, web, coordinator_status, coordinator_tick | write, edit, bash |
|
|
||||||
| Scheduler | read, glob, grep, task, coordinator_* | write, edit, bash |
|
|
||||||
| Worker | read, write, edit, bash, glob, grep | task |
|
|
||||||
| Architect | read, glob, grep, task, edit/write (.air/shared/plan/**) | bash, 源代码文件写 |
|
|
||||||
| Reviewer | read, glob, grep | write, edit, bash, task |
|
|
||||||
|
|
||||||
## 安装
|
|
||||||
|
|
||||||
### 二进制（Linux x64）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 下载发布包
|
|
||||||
wget http://git.airlongdian.fun/admin/AirCoding/releases/download/0.1.0/AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
|
||||||
tar xzf AirCoding-Alpha-0.1.0-linux-x64.tar.gz
|
|
||||||
cd AirCoding-Alpha-0.1.0 && ./install.sh
|
|
||||||
|
|
||||||
aircoding --version # → 0.1.0
|
|
||||||
```
|
|
||||||
|
|
||||||
二进制安装到 `~/.aircoding/`，与 opencode（`~/.opencode/`）互不冲突。
|
|
||||||
|
|
||||||
### 从源码构建
|
|
||||||
|
|
||||||
```bash
|
|
||||||
bun install # 安装依赖
|
|
||||||
bun typecheck # 类型检查（29 包，全部通过）
|
|
||||||
cd packages/opencode && OPENCODE_VERSION="0.1.0" OPENCODE_CHANNEL="aircoding" bun run script/build.ts --single --skip-embed-web-ui
|
|
||||||
```
|
|
||||||
|
|
||||||
## 目录约定
|
|
||||||
|
|
||||||
```
|
|
||||||
.air/shared/plan/plan.md # 架构方案（Architect 产出）
|
|
||||||
.air/shared/plan/task-graph.json # 任务图（Architect 产出，Scheduler 执行）
|
|
||||||
.air/shared/plan/docs/ADR-*.md # 架构决策记录
|
|
||||||
.air/shared/plan/docs/c4/ # C4 模型文档
|
|
||||||
.air/local/state/scheduler-state.json # 调度器状态（实时落盘）
|
|
||||||
.air/local/debug/debug-log.md # 调试记录
|
|
||||||
```
|
|
||||||
|
|
||||||
## 设计文档
|
|
||||||
|
|
||||||
详细设计文档在 `docs/` 目录：
|
|
||||||
|
|
||||||
- [架构设计 MVP](docs/aircoding-architecture-mvp.md)
|
|
||||||
- [V2 实现计划](docs/implementation-plan.md)
|
|
||||||
- [V2 设计（详细）](docs/airplanV2-Qwen3.7-Max设计.md)
|
|
||||||
- [V1 基线](docs/baselineV1.md)
|
|
||||||
- [Agent 约束规则](docs/AGENTS.md)
|
|
||||||
- [集成说明](docs/INTEGRATION.md)
|
|
||||||
|
|
||||||
## 约束铁律
|
|
||||||
|
|
||||||
详见 `CLAUDE.md`。摘要：
|
|
||||||
|
|
||||||
1. **调度器**：禁止降级兜底，必须完全遵循设计方案。设计未覆盖的场景先派 Architect 更新设计，不得在代码中自行裁决。
|
|
||||||
2. **执行器**：禁止以「先跑通」「以后再改」「以后补上」「for now」「fix later」等理由使用简化实现。编译→测试→cppcheck 三步不可跳过。输出含降级措辞直接 FAIL。
|
|
||||||
3. **审查器**：强制调用，不可跳过。「测试 pass」「函数存在」「build 通过」不得作为 PASS 依据。必须输出 Code-to-Design 逐行对照表。代码门确定性执行此规则。
|
|
||||||
4. **防无限循环**：Architect 里程碑审查设有 每阶段2次 / 全局5次 的派发预算 + `milestone_satisfied` 门控，防止 Scheduler 和 Architect 之间无限循环。
|
|
||||||
|
|
||||||
## 致谢
|
|
||||||
|
|
||||||
基于 [OpenCode](https://github.com/anomalyco/opencode) v1.17.4 fork。
|
|
||||||
Reference in New Issue
Block a user