ai-driver-engine开源框架，完美实现Harness，轻松简单无忧架构设计四层架构 Layer 1: 规则

架构设计

本文面向框架贡献者，描述 ADE 的内部架构和编译模型。源码

四层架构

┌─────────────────────────────────────────────────────────────────────┐
│                        AI Drive Engine                              │
│                    知识驱动的软件工厂                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Layer 4: 编排层（Orchestration）                                    │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │ autopilot — 一键全流程    retro — 度量与回顾                    │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↕ 调度                                  │
│  Layer 3: 流程层（Workflow）                                         │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  explore → plan → propose(N) → apply → review → verify        │  │
│  │                                          ↑        │           │  │
│  │                             investigate ←─┘ 失败    │           │  │
│  │                                                    ↓           │  │
│  │                                        archive → distill       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↕ 读写                                  │
│  Layer 2: 知识层（Knowledge）                                        │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  skills/          docs/            planning/                  │  │
│  │  可复用能力         LLM Wiki 知识库    需求孵化                  │  │
│  │  (how to do)      (what we know)    (what to do next)        │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↕ 约束                                  │
│  Layer 1: 规则层（Governance）                                       │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  AGENTS.md — AI 行为原则 · 工程规范 · 流程守卫                   │  │
│  │  engine.yaml — 项目配置 · 代码工程 · 知识加载策略                 │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  工具链：ade init / generate / migrate / doctor / skill / rule / agent / mcp / hook / metrics │
└─────────────────────────────────────────────────────────────────────┘

Layer 1: 规则层

AI 终端的行为边界，通过终端原生 rule 机制注入。

AGENTS.md — 瘦身为入口地图，只保留流程说明和项目配置
终端 rule 目录 — 框架规则编译到 .kiro/steering/ade-* 和 .claude/rules/ade-*
engine.yaml — 项目唯一配置文件：终端列表、代码工程、知识加载策略

编译流程

Rule 文件是 Markdown，可选 ADE 自定义 frontmatter：

---
ade:
  name: code-quality
  kiro:
    inclusion: fileMatch
    fileMatchPattern: ["**/*.ts", "**/*.java", "**/*.py"]
  claude-code:
    paths: ["**/*.ts", "**/*.java", "**/*.py"]
---

有 ade.name → 用作编译后的文件名；无则用源文件名
有 ade.kiro.inclusion → Kiro 编译时输出 steering inclusion frontmatter（always/fileMatch/manual/auto）
有 ade.claude-code.paths → Claude Code 编译时输出 paths: frontmatter
无终端子字段 → Kiro 输出纯 Markdown（默认 always），Claude 输出纯 Markdown

终端编译差异：

终端	输出路径	格式
Kiro	`.kiro/steering/ade-{name}.md`	有 `kiro` 配置时带 inclusion frontmatter，否则纯 Markdown
Claude Code	`.claude/rules/ade-{name}.md`	有 `paths` 时保留 frontmatter，否则纯 Markdown

编译行为：

cleanRules：每次 ade generate 先删除终端 rule 目录中所有 ade-*.md 文件，再重新编译
用户 rule：通过 symlink 同步到终端 rule 目录，不做内容转换
ade- 保留前缀：用户 rule 文件名不得以 ade- 开头

六种资产的编译路径

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  框架资产（framework/）                    终端原生格式                       │
│  ─────────────────────                    ──────────────                     │
│                                                                             │
│  rules/*.md ─────────────────────────→  .kiro/steering/ade-*.md             │
│    · 按终端转换 frontmatter               .claude/rules/ade-*.md             │
│                                                                             │
│  skills/*/SKILL.md ──────────────────→  .kiro/skills/ade-*/SKILL.md         │
│    · name rewrite + frontmatter inject    .claude/skills/ade-*/SKILL.md     │
│                                                                             │
│  hooks/hooks.yaml ───────────────────→  .kiro/agents/ade-hooks.json         │
│    · 事件名映射 + 脚本拷贝                .claude/settings.json (hooks)      │
│                                                                             │
│  agents/agents.yaml ─────────────────→  .kiro/agents/ade-agent-*.json       │
│    · tools 名映射                         .claude/agents/ade-*.md            │
│                                                                             │
│  mcp/mcp.yaml ───────────────────────→  .kiro/settings/mcp.json             │
│    · condition 过滤                       .claude/settings.json (mcpServers) │
│                                                                             │
│  commands/commands.yaml ─────────────→  .kiro/skills/ade-*（复用 skill）     │
│                                         .claude/commands/ade-*.md            │
│                                                                             │
│  templates/agents.md.hbs ────────────→  AGENTS.md（AI 的规则入口）            │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  用户资产                                                                    │
│  ────────                                                                   │
│  skills/* ───── symlink ─────────────→  .kiro/skills/*                      │
│  skills/remote/* ── symlink ─────────→  .kiro/skills/*                      │
│  rules/* ────── symlink ─────────────→  .kiro/steering/*                    │
│                                                                             │
│  ade- 前缀保留给框架，用户资产禁止使用                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Layer 2: 知识层

三类知识资产，各有明确职责：

资产	位置	职责	示例
可复用能力	终端 `ade-*` skills（框架）、`skills/`（用户）	HOW TO DO	编码规范、Git 操作、测试模式
结构化知识	`docs/`	WHAT WE KNOW	API 文档、业务规则、架构设计
需求孵化	`planning/`	WHAT TO DO NEXT	场景评估、优先级矩阵

LLM Wiki 知识库

docs/ 采用 LLM Wiki 模式：AI 在摄入时编译知识，而非查询时重新推导。

docs/
├── raw/                    # 第一层：不可变原始资料（AI 只读）
├── wiki/                   # 第二层：AI 编译产出（AI 读写）
│   ├── index.md            #   内容目录（导航入口）
│   ├── log.md              #   操作日志（append-only）
│   └── {category}/         #   维度目录
└── README.md

第三层是 Schema——wiki-ops rule 和 engine.yaml 的 knowledge 配置。

三个操作：Ingest（摄入）、Query（查询）、Lint（健康检查）。

Wiki 页面规范：

---
title: Pipeline 编排模式
sources:
  - codebases/ai-drive-engine/src/commands/generate.ts
related:
  - "[[workflow-subagents]]"
updated: 2026-04-27
---

知识自动流入路径

时刻	产生什么	流入 wiki 的路径
propose	需求分析、方案设计	distill 时从 openspec artifacts 摄入
apply	技术决策、踩坑经验	distill 时从代码 diff 和 apply-log 摄入
review	代码审查发现的模式	review 建议摄入 wiki
archive → distill	以上所有的汇总	主要自动摄入点
用户主动	外部文章、调研	放入 raw/ → 告诉 AI "摄入"

Layer 3: 流程层

流程定义

正常流程：
  explore → plan → propose(N) → apply → review → verify → archive → distill
                    ↑
              一个需求拆出多个提案

失败分支：
  verify 失败 → investigate → 修复 → 重置 verify 为 pending

随时可用：
  explore（思考伙伴，任何阶段都可以进入）

Skill 契约

Skill	触发	输入	输出
explore	"探索/讨论 XX"	任意上下文	思考记录
plan	"规划 XX 版本"	业务需求描述	版本需求文档 + 提案拆分清单
propose	"创建 XX 提案"	单个需求	proposal.md + design.md + tasks.md
apply	"实施 XX 任务"	proposal + tasks	代码变更 + task checkbox
review	apply 完成后	git diff + design.md	审查报告 + 自动修复
verify	review 通过后	代码变更	构建结果 + E2E 测试结果
investigate	verify 失败时	错误信息 + 代码上下文	根因分析 + 修复
archive	verify 通过后	完成的变更	归档 + 触发 distill
distill	archive 触发	变更 artifacts + 代码 diff	docs 更新 + skills 沉淀建议

SKILL.md 格式

---
name: local-env-doctor
description: "开发环境诊断与服务管理..."
triggers: ["环境检查", "诊断", "doctor"]
version: 1.0.0
metadata:
  scope: core
---

字段	必填	作用
`name`	✅	Skill 唯一标识，编译时被 rewrite 为 `ade-{name}`
`description`	✅	AI 匹配意图的依据，第一句是能力总结
`triggers`	❌	触发关键词列表
`version`	❌	版本号
`requires`	❌	前置 skill 依赖
`on_success`	❌	成功后自动触发的下一个 skill
`metadata.scope`	❌	作用域（core 等），用于 scope 过滤

Skill 终端差异化配置

Skill 源码目录中可选 skill.config.yaml：

compile:
  claude-code:
    frontmatter:
      disable-model-invocation: true

编译器读取后按终端注入对应字段到 SKILL.md frontmatter。标准字段受保护不被覆盖。skill.config.yaml 不会被复制到编译产物中。

References 渐进式加载

Workflow skill 的流程增强内容存放在 references/ 目录：

framework/skills/workflow/apply/
├── SKILL.md
├── skill.config.yaml
└── references/
    └── ade-workflow-integration.md

SKILL.md 中通过标准文件引用指向 references，AI 按需读取。

框架 Skill vs 用户 Skill vs 远程 Skill

维度	框架 Skill	用户 Skill	远程 Skill
位置	`framework/skills/`	项目根 `skills/`	`skills/remote/`
管理方式	`ade generate` 全量覆盖	用户自行维护	`ade skill pull` 声明式同步
编译方式	拷贝 + name rewrite + frontmatter inject	symlink	symlink
命名前缀	`ade-`（自动添加）	无前缀（禁止 `ade-`）	无前缀（禁止 `ade-`）

Layer 4: 编排层

采用 Supervisor + Sequential Pipeline + Blackboard 模式：

Supervisor：autopilot skill，管理流水线状态，路由节点
Sequential Pipeline：propose → apply → review → verify → archive → distill → retro
Blackboard：.ai-state/ 目录，所有 agent 通过文件共享状态

Pipeline 节点定义

每个节点在 pipeline.yaml 中声明 mode/inputs/outputs：

节点	mode	fallback	inputs	outputs
propose	skill	—	（无）	proposal.md, design.md, tasks.md
apply	skill	—	tasks.md, design.md	tasks.md（更新 checkbox）
review	subagent	skill	design.md, tasks.md	review-report-{change}.md
verify	subagent	skill	tasks.md	verify-report-{change}.md
archive	skill	—	change 目录	archive 目录
distill	skill	—	archive 目录	docs/
retro	subagent	—	events.jsonl	retro-{change}.md

Workflow Subagents

Subagent	对应 Workflow	职责	Model
retro-agent	retro	读日志生成回顾报告	haiku
review-scanner	review	代码扫描+自动修复	sonnet
verify-runner	verify	构建+测试+自动修复	sonnet

节点分类标准：输入明确、输出明确、不需要用户决策、可后台运行 → 适合 subagent。subagent 输出有 blocked 项时回退到 fallback skill 在主会话处理。

Pipeline State

.ai-state/pipeline-state.json 记录流水线状态：

{
  "change": "feature-name",
  "currentNode": "review",
  "nodes": {
    "propose": { "status": "completed" },
    "apply":   { "status": "completed" },
    "review":  { "status": "running", "agent": "review-scanner" }
  }
}

状态枚举：pending → running → completed / failed / blocked

Error Recovery

场景	策略
subagent 报告 blocked	主会话处理判断项，完成后 → completed
subagent 报告 failed	进入 investigate，修复后重置为 pending
inputs 不就绪	暂停，报告缺失项

状态总线

.ai-state/ 目录是流程层和编排层的数据基础。

.ai-state/
├── session.md              # 会话断点（AI 自动维护）
├── pipeline-state.json     # 流水线状态（autopilot 维护）
├── events.jsonl            # 所有 workflow 事件（会话结束时批量写入）
├── session-log.jsonl       # 会话度量（独立）
├── review-report-*.md      # subagent 产出
├── verify-report-*.md      # subagent 产出
└── metrics/                # retro skill 读写

写入机制：skill 执行过程中不写日志，会话结束时一次性 flush 到 events.jsonl（最多 2 次 tool call）。

用户可通过 ade metrics 命令直接查看四维度量概览（效率/质量/知识复利/流程纪律），无需进入 AI 会话。

设计原则：

写入是副作用，不影响主流程
文件丢失不影响任何 skill 运行
纯文本，git 可追踪，终端无关

终端适配

所有资产通过 ade generate 编译到终端原生目录，使用 ade- 前缀标识。

资产	Kiro	Claude Code
Skill	`.kiro/skills/ade-*`	`.claude/skills/ade-*`
Rule	`.kiro/steering/ade-*.md`	`.claude/rules/ade-*.md`
Agent	`.kiro/agents/ade-*.json`	`.claude/agents/ade-*.md`
Hook	`.kiro/agents/ade-hooks.json`	`.claude/settings.json` hooks
MCP	`.kiro/settings/mcp.json`	`.claude/settings.json` mcpServers
Command	`.kiro/skills/ade-*`（复用 skill）	`.claude/commands/ade-*.md`

Hook 分发

hooks.yaml 格式：

hooks:
  - name: post-write-lint
    event: PostToolUse
    matcher: "Write|Edit"
    type: command
    command: "hooks/scripts/lint.sh"
    timeout: 30

handler 类型：command、http、prompt、agent、mcp_tool。

事件映射：

hooks.yaml 事件名	Kiro 映射	Claude Code
SessionStart	AgentSpawn	SessionStart
UserPromptSubmit	UserPromptSubmit	UserPromptSubmit
PreToolUse	PreToolUse	PreToolUse
PostToolUse	PostToolUse	PostToolUse
Stop	Stop	Stop

Kiro 支持 5 个事件，Claude Code 支持 28 个事件。不支持的事件在 ade generate 时自动跳过。

Agent 分发

agents.yaml 格式：

agents:
  - name: code-reviewer
    description: "Reviews code"
    model: sonnet
    tools: [Read, Grep, Glob]
    prompt: |
      You are a senior code reviewer.
    overrides:
      kiro:
        allowedTools: [read]

Kiro 工具名映射：Read→read, Write/Edit→write, Bash→shell, Glob→glob, Grep→grep。

MCP 编译

servers:
  - name: graphify
    command: python3
    args: ["-m", "graphify.serve", "docs/raw/graphify-out/graph.json"]
    condition: "docs/raw/graphify-out/graph.json"

框架 server 加 ade- 前缀，用户 server 原样保留
condition 文件不存在时静默跳过
Kiro 的 mcp.json 如果是 symlink，跳过编译

Command 编译（斜杠命令）

commands:
  - name: generate
    description: "编译框架文件到终端目录。"
    prompt: |
      执行 `ade generate` 编译框架文件到终端目录。

终端	输出格式	输出路径
Kiro	SKILL.md（prompt skill）	`.kiro/skills/ade-{name}/SKILL.md`
Claude Code	Markdown	`.claude/commands/ade-{name}.md`

变更管理（OpenSpec）

框架使用 OpenSpec 作为变更管理引擎。

openspec/
├── config.yaml          # 项目上下文、schema 配置
├── changes/             # 活跃变更
│   ├── <change-name>/
│   │   ├── proposal.md  # 做什么、为什么
│   │   ├── design.md    # 怎么做
│   │   └── tasks.md     # 实施步骤（checkbox 驱动）
│   └── archive/         # 已归档变更
└── specs/               # 长期规格文档

ADE 的 workflow skill 通过调用 openspec CLI 与之交互：

propose skill → openspec new change + openspec instructions
apply skill → openspec status --json 读取任务状态
archive skill → openspec archive 归档变更

CLI 工具链

命令	作用
`ade init`	创建项目：engine.yaml → generate → 目录骨架
`ade generate`	编译 AGENTS.md + 同步 .ade/ + 分发资产到终端
`ade migrate`	跨版本迁移 + generate
`ade doctor`	健康检查：配置、hash、完整性、所有资产格式校验
`ade add-codebase`	关联代码工程（git submodule）
`ade skill list`	列出所有 skill（含 size、tokens、描述）
`ade skill pull`	根据 engine.yaml 配置拉取远程 skill
`ade skill push <name>`	将远程 skill 的本地改动推送 MR 到源仓库
`ade rule list`	列出所有 rule（含 size、tokens）
`ade agent list`	列出所有 agent（含 model、tools、描述）
`ade mcp list`	列出所有 MCP server（声明源 + 终端编译状态）
`ade hook list`	列出所有 hook（事件、类型、matcher）

项目目录结构

my-project/
├── AGENTS.md                  # 编译产物，AI 的规则入口
├── engine.yaml                # 项目配置（唯一需要手动维护的配置）
├── .ade/                      # 框架文件（ade generate 管理）
│   ├── ETHOS.md
│   └── GUIDE.md
├── rules/                     # 用户自定义规范
├── skills/                    # 用户自定义 skill
│   └── remote/                #   远程 skill（ade skill pull 管理）
├── mcp/                       # 用户 MCP server 声明
│   └── mcp.yaml
├── openspec/                  # 变更管理（OpenSpec）
├── docs/                      # 知识库（LLM Wiki 模式）
│   ├── raw/                   #   不可变原始资料（AI 只读）
│   └── wiki/                  #   AI 编译的结构化知识（AI 读写）
├── codebases/                 # 代码工程（git submodule）
├── planning/                  # 需求孵化
├── e2e-tests/                 # E2E 自动化测试
├── scripts/verify/            # 验证脚本
├── .ai-state/                 # 状态总线
└── .kiro/                     # Kiro 适配层