OpenJoin Plugin：从需求到部署的 AI 全流程编码

OpenJoin Plugin：从需求到部署的 AI 全流程编码实践指南

如何用 6 大 Agent + 39 个 Skill，在 OpenCode 中实现需求分析→编码→测试→质检→部署的完整闭环？

背景

AI 编码工具的困境

2024 年以来，AI 编码工具爆发式增长——GitHub Copilot、Cursor、Claude Code、OpenCode 等产品让开发者体验到了「AI 写代码」的便利。但实际落地后，我们发现一个普遍问题：AI 擅长写代码片段，却不擅长完成工程交付。

具体表现为：

  • 需求阶段断裂：产品经理给出 Word 文档，开发者需要手动翻译成技术方案，AI 工具无法直接消费原始需求
  • 编码缺少约束：AI 生成的代码风格不一，缺少项目级规范约束，不同人用 AI 写出的代码质量参差不齐
  • 测试成为盲区：大部分 AI 编码工具只关注「写代码」，不关注「验证代码」，测试覆盖率甚至比手写还低
  • 质检流程缺失：AI 写的代码是否满足接口契约？是否符合业务逻辑？没有系统化的验证手段
  • 部署人工衔接：代码写完了，CI/CD 配置、发布说明、版本管理还得人工处理

这些问题的本质是：现有 AI 编码工具只解决了「编码」这一个环节，而软件工程是一个完整的生命周期。

为什么是 OpenCode + OpenJoin？

OpenCode 是一个开源 AI 编码 Agent，拥有 160K+ GitHub Stars。它不同于传统的代码补全工具，而是以 Agent 的形式自主完成开发任务——读文件、写代码、跑测试、执行命令，像一个不知疲倦的初级开发者。

OpenCode 提供了强大的扩展能力：Plugin 系统、Skill 机制、Agent 配置、Hook 钩子。这让定制化成为可能。

OpenJoin Plugin 正是基于这套扩展能力构建的。它的核心思路是：

与其让一个万能 AI 去做所有事，不如让多个专业 Agent 各司其职，通过编排协作完成全流程交付。

设计哲学

OpenJoin Plugin 的设计遵循三个原则：

1. 流程即代码（Process as Code）

每个开发阶段（需求→设计→编码→测试→质检→部署）都有对应的 Agent 和 Skill。SDD（Software Design Document）作为核心产物在上下游间传递，确保从需求到代码的可追溯性。

2. 质量内建（Quality Built-in）

不是写完代码再补测试，而是在编码流程中自动嵌入审查 + 单元测试循环。每个编码任务完成后，checklist 审查和单元测试并发执行，不通过则自动修复（最多 3 轮）。

3. 人机协作（Human-in-the-loop）

关键节点（SDD 确认、审查级别选择、部署检查）保留人工决策。AI 处理重复性工作，人负责验证和拍板。

前言

本文是 OpenJoin Plugin 的完整使用指南，面向已经在使用 OpenCode 的开发团队。将结合实际使用场景，详细介绍每个 Agent 的定位、核心 Skill 的用法，以及如何在项目中高效运用。

如果你还没有安装 OpenCode，请先访问 opencode.ai 了解基础用法，再回来阅读本文。

一、整体架构：Agent 编排体系

OpenJoin Plugin 的核心设计理念是分工协作。每个 Agent 负责一个明确的阶段，Agent 之间通过任务调度（Task Tool）实现上下游衔接：

Agent 类型 职责
需求分析Agent Primary PRD 生成、Word 文档转换
编码Agentic Primary 全流程编排，调度 8 个子 Agent
测试Agent Primary API 测试、前端 E2E 测试
质检Agent Primary 三维度代码走查
部署Agent Primary CI/CD 流水线 + 发布说明

其中编码Agentic是最复杂的编排器，内部调度 8 个子 Agent 完成编码全流程：

二、需求分析 Agent：让需求文档不再是负担

核心能力

需求分析 Agent 是整个流程的起点，支持三种输入方式：

  • 自然语言描述：直接告诉 Agent 你的需求，它会把模糊的描述转化为结构化的 PRD 文档
  • Word 文档导入：已有 .docx 格式的需求文档？直接丢给 Agent，自动完成格式标准化和模块拆分
  • 增量迭代：对已有模块生成增量需求文档，保持文档一致性

使用技巧

1. 描述需求时尽量具体

包含目标用户、核心功能、业务约束。模糊描述会导致生成的 PRD 缺少关键模块。

# 差的描述
做一个用户管理功能

# 好的描述
企业后台的用户管理模块，支持用户列表查询（分页、模糊搜索）、
新增用户（含角色分配）、编辑用户信息、禁用/启用账号。
角色包括：超级管理员、部门管理员、普通员工。
需要操作日志记录。

2. 善用 Word 导入加速

已有需求文档（.docx）可直接喂给 Agent，自动完成格式标准化 + 模块拆分。这是最快的方式，特别适合从产品经理那里接手的需求文档。

3. 增量迭代模式

对已有模块使用 ac-prd-generate 的增量模式，避免从零开始，保持与存量文档的一致性。

三、编码 Agentic：全流程编排的核心

前置条件（重要！）

编码流程启动前必须先执行 /ac-init 命令，生成以下文件：

  • rules.md — 通用编码规范
  • AGENTS.md — 项目级 Agent 指令
  • backend-rules.md — 后端专属规范（如有后端）
  • frontend-rules.md — 前端专属规范（如有前端）

如果缺少这些文件，编码 Agent 会直接拦截并提示你先初始化。

8 个子 Agent 各司其职

SDD 产物目录结构

编码流程的所有产物遵循三级目录规范：

.openjoin/sdd/                          ← sdd_root
├── rules.md                            ← 通用编码规范
├── AGENTS.md                           ← 项目 Agent 指令
├── backend-rules.md                    ← 后端规范
├── frontend-rules.md                   ← 前端规范
└── feature_v1.0.0/                     ← version_dir（版本目录）
    ├── task.yaml                       ← 编码任务列表
    ├── modules.yaml                    ← 模块清单
    ├── user-management/                ← module_dir（模块目录）
    │   ├── data-model.md               ← 数据模型
    │   ├── api-contract.md             ← 接口契约
    │   ├── spec.md                     ← 功能规格
    │   └── coding-tasks.yaml           ← 编码任务片段
    └── order-management/
        └── ...

编码执行循环

编码 Agentic 最强大的地方在于逐任务执行 + 两阶段审查：

while 存在 pending 任务：
  1. 收集「依赖已满足」的任务
  2. 按 parallel_group 分组执行（最大并发 3）
  3. 每个编码任务完成后：
     → 并发执行审查 + 单元测试
     → 全部 PASS → 标记 completed
     → 有 FAIL → 统一修复（最多 3 轮）
  4. 回到循环

关键使用技巧

1. 版本号规范

版本号用于构建版本目录，默认格式为 {项目简称}1.0.0.0。Agent 会在 SDD 生成前询问版本号，请提前准备好。

2. SDD 人工确认

全部 SDD 文档生成完成后，Agent 会拉起对话让你确认。务必逐模块检查数据模型和接口契约后再继续，避免后续返工。

3. 审查级别选择

首个编码任务审查前会询问级别：

  • 高级别：只审查会导致系统无法运行的问题（最快）
  • 高+中级别：审查系统运行 + 功能正确性（推荐）
  • 全部级别：六维度全面审查（最严格）

4. 断点续传

task.yaml 记录每个任务的状态（pending / in_progress / completed / failed）。如果中途断开，重新启动编码 Agent 后会自动识别 in_progress 任务，评估完成度后续编。

5. 存量项目保护（brownfield）

如果项目已有代码库，编码 Agentic 会自动启用「存量代码保护约束」：

  • 禁止修改存量文件，只允许创建新文件
  • 新增功能必须在新的类/文件中实现
  • 审查范围仅限新增代码
  • 与存量代码交互时，通过适配器模式隔离

四、测试 Agent：API + E2E 双轨测试

测试 Agent 是一个编排器，根据测试类型自动调度对应的子 Agent：

api-test-agent：后端 API 自动化测试

完整的 5 阶段流程：

  1. Schema 生成 — 从 API 文档自动提取接口定义
  2. 用例设计 — 自动生成正向/逆向/边界用例
  3. 测试数据构造 — 基于数据模型生成 SQL 测试数据
  4. 脚本执行 — pytest 驱动，Allure 报告
  5. 报告生成 — 结构化 Markdown 测试报告

关联 Skill：api-auto-test、testcase-generator、test-executor、test-data-generator、ac-at-execution、ac-at-report-gen

e2e-test-agent：前端 E2E 测试

基于 Playwright 的真实浏览器自动化测试：

  • 从需求文档 + 接口文档自动生成测试用例
  • 在真实浏览器中逐用例执行
  • 每个用例附带截图证据
  • 纯测试模式，不修复代码

关联 Skill：frontend-e2e-test

使用建议

  • 编码完成后，可让编码 Agentic 自动触发测试，也可单独使用 @测试Agent
  • 提供 SDD 文档路径（spec.md + api-contract.md）能显著提升测试用例质量
  • API 测试需要后端服务已启动，E2E 测试需要前端服务已启动

五、质检 Agent：三维度代码走查

质检 Agent 从三个维度全面审查代码质量，只审查不修复：

质量轨

  • Skill：code-review-expert
  • 关注点：SOLID 原则违反、安全漏洞、性能瓶颈
  • 适合场景：对任意代码文件进行深度质量审查

技术轨

  • Skill：code-review-checklist
  • 关注点：API 契约一致性、字段完整性、编码规范
  • 适合场景：验证代码实现是否与 SDD 文档中的接口契约一致

业务轨

  • Skill：sdd-flow-link-json
  • 关注点：上下游链路核查、业务逻辑验证、需求符合性
  • 适合场景：确认实现是否覆盖了完整业务链路

使用方式

质检 Agent 有两种触发方式：

  1. 编码流程中自动触发 — 编码 Agentic 在每个编码任务完成后会自动调用
  2. 独立使用 — 通过 @质检Agent 直接唤起，指定审查范围即可

独立使用时的推荐命令：

@质检Agent 请审查 src/services/user-service.ts 文件，
对照 .openjoin/sdd/feature_v1.0.0/user-management/api-contract.md 中的接口契约

六、部署 Agent：一键发布

部署 Agent 负责 CI/CD 流水线触发和发布说明生成，执行流程：

Step 1: 更新 gitnexus 代码索引
    ↓
Step 2: 同步 API 契约（标注已有接口的源码文件与行号）
    ↓
Step 3: 创建/触发 CI/CD 流水线
    ↓
Step 4: 从 SDD 文档套件生成发布说明

关联 Skill：deploy-auto-entrypoint、cicd-deploy、release-notes

部署前检查清单

在触发部署前，请确认：

  • SDD 文档套件完整（spec.md + api-contract.md + data-model.md）
  • 编码任务全部 completed（task.yaml 中无 pending/in_progress）
  • 质检通过（无 FAIL 状态的审查报告）
  • 部署目标环境配置正确

七、典型工作流

场景一：全新项目开发

/ac-init → @需求分析Agent「描述需求」
→ 确认 PRD → @编码Agentic「开始编码」
→ @质检Agent「走查」→ @部署Agent「发布」

场景二：Word 需求文档开发

@需求分析Agent「导入 requirements.docx」
→ 确认 PRD → @编码Agentic
→ @测试Agent → @部署Agent

场景三：存量项目小需求

@编码Agentic（自动识别 brownfield 项目）
→ 存量保护约束自动启用
→ 增量编码，审查仅限新增代码

场景四：独立质检 / 测试

@质检Agent「指定代码范围」
或
@测试Agent「指定接口文档路径」

独立执行，无需走编码全流程。

写在最后

OpenJoin Plugin 的核心价值在于流程标准化和质量内建。通过 Agent 编排体系，将原本需要人工协调的需求分析、编码规范、测试覆盖、质量审查、部署发布等环节串联为自动化流水线。每个环节都有对应的 Skill 提供专业能力支撑，而 Agent 负责调度和上下文传递。

这并不意味着开发者被取代。相反，开发者可以在关键节点（如 SDD 确认、审查级别选择、部署检查）进行人工干预，确保产出的质量。AI 处理重复性工作，人负责决策和验证——这才是高效的人机协作模式。
如果有需要的请联系 openjonai-plugin@vip.qq.com，github地址：https://github.com/qitianfeng/openjoinai-plugin

posted @ 2026-06-01 21:49  ai一体化  阅读(2)  评论(0)    收藏  举报