ai-dev-orchestrator 开源：用 18 状态状态机编排 AI 编码智能体

An orchestration platform for AI coding agents. You define the workflow, and the orchestrator runs it: dispatching agents to roles, enforcing governance gates, collecting artifacts, and recovering from failures. Everything runs locally.

Why

AI coding agents work best with structure. Without it, they skip steps, ignore review feedback, and produce inconsistent results. This orchestrator gives them a finite state machine to follow, quality gates to pass, and a review loop that catches what they miss.

Capabilities

Deterministic workflows. An 18-state FSM drives each run from intake to done. Fork/join for parallel workers. Governance gates between phases enforce iteration limits, quality thresholds, and required reviews.

25 built-in roles. Requirements Analyst, Planner, Implementer, seven specialized reviewers (static, security, performance, design, adversarial, docs, UX), Verifier, Judge, and more. Each role gets its own prompt template, model assignment, and artifact ownership.

Agent runners. Dispatches work through Claude Code, Cursor, Codex, and OpenCode CLIs, each with its own model roster. Runner-specific execution logic handles output parsing, retries, and protocol adaptation for each vendor CLI.

Artifact system. Immutable, versioned, SHA-256 checksummed. 34 schema-validated types. A dependency graph tracks staleness and impact across artifacts.

Recovery. Atomic checkpoint writes. Append-only journal. State reconstruction from journal when a checkpoint corrupts. SIGTERM/SIGINT handling, crash recovery, lock protocol.

Dashboard. React UI for monitoring runs, browsing artifacts, inspecting findings, and viewing token usage per role.

Quickstart

node --version  # >= 22
pnpm --version  # >= 11

pnpm install
pnpm link:cli

CLI

ai dashboard             # Open web dashboard

ai init                  # Set up ~/.ai/ configuration
ai run <source>          # Start a workflow run
ai status [runId]        # Current state and progress
ai list                  # Past runs with status
ai inspect [runId]       # Detailed run information
ai artifacts [runId]     # Artifact inventory

ai resume [runId]        # Resume an interrupted run
ai retry <runId>         # Retry from failure state
ai abort [runId]         # Abort a running run
ai kill                  # Kill all active processes

ai approve [runId]       # Approve a human gate
ai answer [runId]        # Answer clarification questions
ai permit [runId]        # Grant/deny permission requests

ai validate              # Check config without running
ai config show           # Display merged configuration
ai version               # Version, commit SHA, build info

All commands accept --json for machine-readable output and --verbose for detail. run, resume, and retry also accept --repo <path>.

Architecture

Hexagonal (ports & adapters) with strict layering enforced by Turborepo boundary tags. Lower layers cannot import from higher layers.

Layer	Packages
Foundation	`schemas`, `utils`, `build-config`
Contracts	`ports`, `agent-protocol`, `test-utils`
Domain	`artifacts`, `agent-adapters`, `dependency-graph`, `execution-analytics`, `governance`, `journal`, `policy-engine`, `project-context`, `prompt-engine`, `role-system`, `run-manifest`, `runner`, `specification`
Infrastructure	`core`, `recovery`
Orchestration	`workflow`
Application	`config-templates`, `dashboard-server`, `dashboard`
Composition	`cli`

26 packages in a pnpm/Turborepo monorepo. See docs/system-overview.md for the full breakdown.

Development

Command	What it does
`pnpm lint`	ESLint across all packages
`pnpm typecheck`	TypeScript type checking
`pnpm test:unit`	Unit tests
`pnpm test:unit:coverage`	Unit tests with coverage report
`pnpm test:integration`	Integration tests
`pnpm coverage:merge`	Union per-package coverage blobs (unit + integration) into one report
`pnpm test:scripts`	Tests for the `scripts/` tooling
`pnpm test:results:merge`	Merge per-package JUnit into one report (needs `CI=true`)
`pnpm build:prod`	Production build
`pnpm build:dev`	Development build (sourcemaps)
`pnpm format`	Prettier formatting
`pnpm format:check`	Check formatting
`pnpm knip`	Detect unused files, deps, exports
`pnpm syncpack:check`	Check dependency version consistency
`pnpm publint`	Validate package.json exports

Pre-commit hooks are tiered by staged file type. Commits touching only docs or CI config (.md, docs/, .github/, .husky/, .vscode/) run lint-staged (ESLint + Prettier) and format:check. Any other commit — including any change under a package's src/, even a .md or .yaml data file — runs all twelve checks: lint-staged, typecheck, lint, format, syncpack, build, publint, knip, unit tests with coverage, script tests, integration tests, and e2e tests. CI prepares one Turbo package filter for all checks: * for shared/root changes, or changed packages and downstream dependents for package changes. Package manifest changes also run syncpack and publint. See CONTRIBUTING.md for the full development workflow.

Documentation

System Overview — architecture, packages, runtime layout
Contributing Guide — branch naming, commits, CI/CD, coding standards
Architecture Docs — full specification index

License

MIT