Flutter AI Harness 如何让 Agent 参与软件开发全流程

Flutter AI Harness 如何让 Agent 参与软件开发全流程

AI 能生成代码，不等于 AI 已经能够参与软件工程。真正困难的部分，是让它理解项目边界、遵守执行流程、接受独立审查，并留下可以验证的结果。

项目地址：github.com/bladeofgod/...

先说结论：我想解决的不是"AI 会不会写代码"

最近几年，AI 编程工具的使用方式越来越自然：打开 Claude Code、Codex 或其他编码 Agent，进入项目目录，然后用一句话描述需求。

这对一次性修改非常有效。但当项目变成一个需要长期维护的真实工程时，问题很快就会出现：

• 项目架构和约束散落在文档、代码和个人记忆中，Agent 每次都要重新猜测上下文。
• 需求通常直接进入实现阶段，任务边界、依赖关系和验收标准没有被固定下来。
• 一个通用 Reviewer 既审查业务代码，又审查 Harness 自身，很容易出现职责重叠或遗漏。
• 测试、构建和安全审查常常变成实现完成后的补充动作，而不是任务的一部分。
• Agent 给出了"看起来合理"的结论，但没有留下足够的机器结果和失败原因供后续复核。

所以我开始尝试构建 Flutter AI Harness。

它不是一个给 Flutter 应用增加 AI 功能的 SDK，也不是一个封装了若干 Prompt 的工具箱。它是一套运行在代码仓库之上的 AI 工程制度和执行系统：让项目规则、Agent 角色、任务产物、Review 流程和质量门禁共同成为仓库的一部分。

Flutter Demo 只是这套制度的第一个被治理对象。真正可以复用的，是这套工程模型。

从提示词编程到系统化 Agent 协作

可以把 AI 参与软件开发的方式粗略分成三个阶段。

阶段	AI 的工作方式	工程上的主要问题
提示词编程	用户提问，AI 直接生成或修改代码	上下文依赖对话，过程和边界不稳定
多 Agent 协作	不同 Agent 分析、实现、测试或审查	角色可能存在，但缺少共同规则和统一产物
AI Harness	Agent 在项目契约和质量流程中协作	任务可追踪，职责可路由，结果可验证

这里的变化不只是"增加了几个 Agent"。真正的变化是：AI 的工作对象从一段代码，变成了一个有规则、有状态、有验收条件的工程任务。

在提示词编程中，用户通常关心的是：

请帮我实现一个拍摄入口。

在 Harness 中，同一个需求会被展开成一组明确的问题：

这个需求属于什么工作类型？
涉及哪些平台和模块？
它依赖哪些已有任务？
每一项验收条件如何验证？
哪些 Review Profile 需要参与？
是否改变了安全边界？
最终需要留下哪些机器证据？

这组问题不是为了增加流程负担，而是为了减少实现完成之后才发现范围、验证或职责不清的情况。

AI Harness 的基本模型

我对 Harness 的定义是：

一套运行在代码仓库之上的 AI 工程制度和执行系统。

它主要由下面几层组成：

AI Harness
├── 项目契约：架构边界、编码规则、安全策略
├── 工作流：规划、执行、Review、修复、归档、发版检查
├── 任务系统：任务卡、依赖、执行者、验收条件
├── Agent 系统：规划者、执行者、专业 Reviewer、安全 Reviewer
├── 质量门禁：静态检查、测试、构建、Evidence、CI
├── 工具适配：Claude Code、Codex 以及其他等价 Agent
└── 技术栈适配：Flutter / Dart、Android / Kotlin、iOS / Swift

这些层之间不是平行的配置文件，而是一个有先后关系的执行链：项目契约决定边界，任务卡决定范围，Agent 根据任务类型执行，Review 根据工作类型路由，质量门禁判断结果是否可以进入归档。

第一层：项目契约是 Agent 的共同事实源

如果项目规则只存在于聊天历史中，Agent 就无法稳定地复用这些规则。Harness 首先把重要约束放回代码仓库。

在当前项目中，CLAUDE.md 是权威项目契约，里面定义了：

• Workspace 和 Package 的依赖方向。
• Domain Entity、Transport、Fixture 和数据库 Row 的边界。
• Flutter、Android、iOS 的技术栈约定。
• Native Module、Bridge Adapter 和 Flutter Client 的关系。
• Agent、Command、Skill 和 Memory 的组织方式。
• 任务卡、Review、Security Review、Evidence 和归档的生命周期。

这里有一个容易被忽视的设计点：Codex 的 AGENTS.md 只是入口适配，不能覆盖 CLAUDE.md。Claude 和 Codex 可以有各自的工具适配，但项目规则必须有唯一事实源。

这样做的目的不是让所有 Agent 使用同一个工具，而是让不同工具读取同一套工程约束。

第二层：任务卡把需求变成可执行工作

自然语言需求通常太宽泛，不能直接作为长期工程的执行边界。Harness 使用任务卡固定任务的范围、依赖、执行者、工作类型和验收条件。

一个简化的任务卡示例如下：

---
executor: task-executor
platforms: [flutter]
workKinds: [flutter, quality-gate]
blockedBy: []
---

# 增加客服服务媒体发送入口

## 范围

- 在客服服务页面接入拍摄和相册入口。
- 复用已有媒体资源模型，不在页面层解析平台传输对象。

## 验收条件

- 拍摄完成后可以进入结果预览页面。
- 用户确认后可以发送媒体消息。
- 失败时页面保留可理解的错误状态。

## 验证

- 运行相关 Dart / Flutter 测试。
- 对真实设备能力保留人工验证项。

任务卡不是为了限制 Agent 的创造力，而是为了回答"这次到底要完成什么"。当需求跨越 Flutter、Android、iOS 或 Bridge 时，通常会在规划阶段拆成多个有依赖关系的任务，而不是让一个 Agent 在所有层中自由穿行。

第三层：Agent 按职责参与，而不是共享一个模糊角色

Agent 的名称不应该只是角色扮演。每个角色都需要有明确的职责、工具范围、停止条件和输出契约。

当前 Harness 将普通 Review 按任务的 workKinds 路由到不同 Profile：

工作类型	普通 Review Profile
Flutter、Dart Client、Native、Bridge Adapter、Integration、Quality Gate	Code Reviewer
Harness Command、Agent、Validator、Fixture、Evidence、Adapter	Harness Reviewer
Capability / Wire Contract，或独立的文档、规划任务	Contract Reviewer

Security Review 仍然是独立维度。只有任务标记了安全审查，或者实际 diff 改变了信任边界、敏感数据流、原生能力、供应链或 Agent 权限时，它才加入流程。

这解决了一个实际问题：普通的代码 Review 主要负责工程实现质量；Harness 架构本身的流程、Validator、Fixture 和 Evidence 规则，应由 Harness Reviewer 审查；跨 Runtime 的结构化契约，则由 Contract Reviewer 负责。

一个 Reviewer 不应该因为"看起来更通用"，就包办所有类型的审查。

一次任务是怎样完成的

以"在客服服务页面接入拍摄和媒体发送"为例，一次完整执行大致会经历以下阶段。

1. 先分析，不急着写代码

Agent 先读取项目契约、相关架构文档、已有任务和当前改动，确认这个需求涉及哪些层：

客服服务页面
  → Flutter Feature
  → Dart Client
  → Bridge Adapter
  → Android / iOS Native Module

这一步的重点是识别边界，而不是马上生成一个能运行的页面。

2. 生成任务卡并明确依赖

如果需求涉及多端能力，规划阶段会将它拆成多个任务。例如：

Capability Contract
        ↓
Android Native Module ──┐
                        ├── Bridge Adapter
iOS Native Module ──────┘
        ↓
Flutter Client
        ↓
Feature UI / Integration

每张任务卡都应该有自己的范围和验收条件。一个任务可以依赖另一个任务，但不应该把所有实现和验证塞进同一张卡里。

3. Agent 根据任务边界执行

执行者只处理任务卡声明的范围。它可以读取需要的上下文，修改允许的文件，运行目标技术栈的检查，并在结果中说明哪些条件已验证、哪些只能人工或外部环境验证。

这意味着"无法使用工具验证"不等于任务不能执行。验收条件可以明确标记为自动化、Review、人工、外部或暂未验证；Harness 要求的是诚实记录验证方式，而不是强行给每件事情编造一个自动化 Gate。

4. 独立 Review 和必要的 Security Review

实现完成后，Review 不直接继承执行者的结论。Reviewer 根据任务声明的工作类型重新检查：

• 实际 diff 是否超出任务范围。
• 架构边界和契约是否被破坏。
• 测试是否覆盖了任务声明的行为。
• 失败路径、资源生命周期和错误处理是否完整。
• Review 结论是否有对应的实现和验证依据。

如果任务改变了权限、文件访问、原生能力、外部输入或 Agent 工具权限，则再触发独立 Security Review。

5. 记录 Evidence，最后才归档

Evidence 不是一个神奇的"证据工具"，而是正式自动化 Gate 产生的机器验证摘要，例如命令、工具版本、退出码、稳定结果和脱敏输出摘要。

它的作用是回答：

这条验收条件由什么验证？
验证是在什么环境中完成的？
命令是否成功？
失败时根因是什么？
后续是否重新验证过？

真实设备拍摄、系统权限弹窗、视觉效果等内容，不能因为没有自动化 Evidence 就被伪装成已通过。它们应该保留为人工或外部验证项。

只有任务、Review、Security Review、Evidence 和必要的实现摘要全部满足要求，任务才进入归档。

为什么不应该每次都全量重跑

Harness 的目标不是把所有检查都做一遍，而是让检查和变更影响面保持一致。

例如，一次只修改了 Harness Validator 的报告格式，不应该重新运行所有 Flutter UI 测试；一次只修复 Android 原生资源释放，也不应该让所有无关的文档 Fixture 重新执行。

当前模型区分两种运行方式：

• 聚焦验证：修复轮只运行受影响的 Fixture、Gate、Review Profile 和安全维度。
• 完整回归：候选归档、CI、make check 和发版检查时执行无过滤的全量门禁。

这是一种更接近工程实践的折中：开发过程保持反馈速度，最终交付仍然有完整回归作为底线。

同样的原则也适用于历史报告。归档后的 Review、Security Review 和 Evidence 是不可变快照。后续修改同一个文件时，应该创建新的任务、报告和实现摘要，而不是回写历史记录去适配当前工作树。

Flutter 只是第一个被治理对象

虽然仓库名称中有 Flutter，但 Harness 的核心并不依赖 Flutter。

Flutter、Android 和 iOS 只是当前的参考实现，用来验证跨 Runtime 工程的复杂问题：

• Flutter Client 如何调用平台能力。
• Android 和 iOS 如何分别实现 Native Module。
• Bridge Adapter 如何遵守统一的 Wire Contract。
• Host 如何只负责装配，不承载业务状态机。
• 多端任务如何拆分、依赖和验收。

换成 Web、Node.js、Go、Java 或 Python 时，项目仍然可以复用同一类 Harness 能力：项目契约、任务卡、Agent 路由、Review 流程、Evidence 约束和质量门禁。

变化的只是技术栈适配层：执行命令、代码 Reviewer 的检查重点、构建工具、测试工具和平台边界。

如何把 Harness 接入另一个项目

接入时，不应该先把 Flutter Demo 复制过去。正确的思路是：把当前仓库作为参考输入，在目标项目中生成一套属于目标项目自己的工程契约和适配。

已有项目

Agent 先只读审计：

• 当前技术栈和依赖。
• 现有架构和模块边界。
• 项目指令、测试、CI 和构建方式。
• 工作区中已经存在的改动。

然后输出采用方案，列出计划新增或修改的文件、验证命令、冲突和未决问题，等待用户批准。

空目录

空目录并不意味着 Agent 可以自行选择 Flutter、React 或后端技术栈。应该先讨论：

• 产品目标和交付形态。
• 目标平台和部署方式。
• 团队已有能力。
• 性能、数据、安全和维护约束。
• 预期的质量和发布要求。

技术栈确认之后，Agent 才能提出初始化方案。这样 Harness 约束的是工程过程，而不是把某一种技术栈强加给所有项目。

采用计划得到批准后，才进入实现阶段：保留目标项目已有规则，只引入有真实消费者的能力，并复用目标工程自己的测试、构建和 CI。

这套方法不是什么

为了避免误解，也需要明确几个边界。

不是让 Agent 完全替代开发者

人仍然负责产品目标、技术取舍、风险接受和高影响决策。Agent 负责在已确认的边界内推进工作，并提供可审查的结果。

不是增加越多流程越专业

没有真实消费者的抽象、没有实际用途的 Gate、只为生成 Evidence 而新增的工具，都会增加维护成本。Harness 也必须遵循最小化原则。

不是所有事情都必须自动化

自动化测试、静态检查和构建适合交给机器；产品判断、真实设备交互和某些视觉验收可能需要人工完成。关键是把验证方式说清楚，不把未验证结论写成通过。

不是把聊天记录当作工程资产

真正重要的结论应该落到项目契约、任务卡、Review、Evidence 和文档中。对话可以帮助完成工作，但不能成为唯一的事实来源。

我从实践中得到的几个结论

第一，AI 编程的瓶颈很快会从"生成代码的速度"转向"管理上下文和验证结果的能力"。

第二，Agent 的数量不是关键。职责边界、输入输出和停止条件，比"拥有多少个专家 Agent"更重要。

第三，任务卡不是管理流程的形式主义。它决定了一个需求是否有清晰的范围、依赖和完成定义。

第四，Review、Evidence 和 Security Review 必须区分。代码质量、Harness 规则、跨端契约和安全边界虽然相互关联，但不应该由同一个模糊角色全部判断。

第五，Harness 自身也需要被审查。否则它很容易从"帮助工程"变成"制造更多工程文件的流程系统"。

最后

我并不认为 AI Harness 已经解决了 AI 软件开发中的所有问题。它更像是一种工程组织方式：把原本只存在于个人经验和对话上下文中的规则，逐步变成仓库内可读取、可执行、可审查的资产。

Flutter AI Harness 的第一个目标，不是证明 Agent 能在一夜之间生成多少页面，而是验证这样一件事：

当 Agent 参与需求分析、任务拆解、代码实现、测试、Review 和归档时，是否可以通过明确的制度，让整个过程更加稳定、透明和可复用？

如果这个问题成立，那么 Flutter 只是起点。下一步可以把同样的工程模型带到更多语言、平台和团队中。

项目地址：Flutter AI Harness