Dev Pipeline

Dev Pipeline - 版本化开发流水线

概述

与 version-manager 和 project-manager 深度集成，提供标准化的开发流程。

集成关系

dev-pipeline
    │
    ├── calls ──► version-manager
    │               - version-check
    │               - version-prepare
    │               - version-validate
    │               - version-archive
    │
    ├── calls ──► project-manager
    │               - project-update
    │               - project-changelog
    │
    └── calls ──► Claude Opus 4.6 (via oracle)
                    - analyze
                    - write
                    - review
                    - fix

工作流程

init → analyze → [pending_confirm] → confirm → write → review → (fix → review) → deploy → seal
  │                           ↑                                              │
  └──── version-prepare ──────┘                                              └──── version-archive
                                                            project-update
                                                            project-changelog

📋 命令规范

init [--from ]

初始化新版本开发任务。

# 自动检测最新版本作为基础
dev-pipeline init v1.3.5
指定基础版本
dev-pipeline init v1.3.5 --from v1.3.4

执行： 1. version-check - 检查当前状态 2. version-prepare - 准备代码 3. project-update --version --status "🟢 迭代中" - 更新看板 4. 创建版本目录结构和文档

analyze

执行架构分析。

dev-pipeline analyze

功能：

Opus Prompt 规范：

你是一个资深全栈架构师。请基于需求文档，生成详细的开发执行方案。
【输出格式要求】
必须按以下结构输出 Markdown：
项目开发方案
1. 需求理解
业务目标
核心业务流程
关键技术特性
2. 技术架构
整体架构图（ASCII）
技术选型表格
目录结构设计
3. 数据库设计
完整的 SQL 建表语句
索引设计
外键约束
4. API 接口设计
每个接口的 Method/Path
Request/Response 格式（JSON Schema）
错误码定义
5. 任务清单（关键！必须可被解析）
阶段一：基础设施（P0）
| 任务ID | 任务名称 | 优先级 | 依赖 | 预估工时 | 输出文件 |
|--------|---------|--------|------|---------|----------|
| T001 | 项目初始化 | P0 | 无 | 2h | package.json, .gitignore |
| T002 | 数据库模块 | P0 | T001 | 3h | shared/db.js |
阶段二：xxx（P0）
...
6. 风险评估
技术风险表格
缓解措施
【要求】
1. 所有 SQL 语句必须完整可执行
2. API 设计必须包含完整的请求/响应示例
3. 任务清单必须包含具体的输出文件列表
4. 任务ID格式：T001, T002, ...

confirm / revise

dev-pipeline confirm           # 确认方案，进入编码阶段
dev-pipeline revise "修改意见"  # 根据反馈重新分析

write [--task-id ]

编写代码 - 核心功能，必须严格规范返回格式。

dev-pipeline write              # 写入当前任务
dev-pipeline write --task-id T001  # 写入指定任务

#### 🎯 Opus Prompt 规范（关键！）

你是一个专业的高级软件工程师。请基于开发计划，编写高质量的代码。
当前任务：[TASK_ID] [TASK_NAME]
📁 文件输出格式（必须严格遵守）
对于每个需要创建的文件，必须按以下格式输出：
FILE: [相对路径]
操作类型: [create | overwrite | append]
描述: [该文件的用途说明]

示例输出：
FILE: package.json
操作类型: create
描述: Node.js 项目配置文件

FILE: src/server.js
操作类型: create
描述: Express 服务器入口

app.listen(3000, () => { console.log('Server running on port 3000'); });

⚠️ 格式规则
1. 每个文件必须以 ### FILE: 路径 开头
2. 操作类型必须明确：
   - create - 新建文件（文件不存在）
   - overwrite - 覆盖文件（文件已存在，需要替换）
   - append - 追加内容（在文件末尾添加）
3. 代码块必须完整：包含所有必要的导入、配置、实现
4. 路径使用相对路径：相对于项目根目录
5. 不要省略任何文件：任务要求的所有文件都必须输出
📋 任务要求
基于以下开发计划生成代码：
[DEV_PLAN.md 内容]
当前任务详情：
任务ID: [TASK_ID]
任务名称: [TASK_NAME]
输出文件: [FILE_LIST]
依赖任务: [DEPENDENCIES]
请生成完整可运行的代码。

#### 📥 解析逻辑

write 命令的解析器会： 1. 读取 Opus 返回的文本 2. 使用正则匹配 ### FILE: (.*) 提取文件路径 3. 提取操作类型（create/overwrite/append） 4. 提取代码块内容（`` 之间的内容） 5. 根据操作类型写入文件： - create: 检查文件不存在，创建新文件 - overwrite: 直接覆盖现有文件 - append: 在文件末尾追加内容 6. 更新 .state.json 中的任务状态

review

执行代码审查。

dev-pipeline review

#### 🎯 Opus Prompt 规范

你是一个严格的代码审查员。请对以下代码进行全面审查。
📋 审查报告格式（必须严格遵守）

⚠️ 评分规则
总分 >= 7.0：✅ 通过
总分 < 7.0 或有 🔴 严重问题：❌ 不通过
📁 审查文件列表
[列出需要审查的文件路径和内容]

1. 提取评分表格，计算总分 2. 检查是否有 🔴 严重问题 3. 生成审查报告文件：versions/vX.X.X/docs/REVIEW_TASK_[ID].md 4. 更新任务状态： - 通过：review_passed - 不通过：needs_fix

fix

修复代码问题。

dev-pipeline fix

#### 🎯 Opus Prompt 规范

你是一个专业的高级软件工程师。请根据审查报告修复代码问题。
审查报告
[REVIEW_TASK_XXX.md 内容]
📁 修复输出格式
与 write 命令相同，使用：
FILE: [路径]

操作类型: [overwrite | append]
修复说明: [修复了什么问题]

⚠️ 要求
1. 必须解决所有 🔴 严重问题
2. 尽可能解决 🟡 警告
3. 保留原有代码结构，只做必要修改
4. 每个修改都要有明确的修复说明

dev-pipeline deploy

执行： 1. version-validate - 验证代码完整性 2. 红线检查（文件大小差异>20%停止） 3. 备份线上代码 4. 部署 5. project-update --status "🟢 已部署"

seal

封版归档。

dev-pipeline seal

执行： 1. version-archive - 归档全量代码 2. project-update --version --status "🟢 已封版" - 更新看板 3. project-changelog release --version - 标记发布 4. 更新 .state.json

📊 状态机

{
  "version": "v1.3.5",
  "status": "writing",
  "current_task": "T001",
  "architecture_confirmed": true,
  "tasks": [...]
}

| 状态 | 说明 | 可执行命令 | |------|------|-----------| | initialized | 刚初始化 | analyze | | pending_confirm | 分析完成，等待确认 | confirm, revise | | confirmed | 已确认 | write | | writing | 编码中 | - | | written | 编码完成 | review | | review_passed | 审查通过 | write(下一任务) / deploy | | needs_fix | 需要修复 | fix | | all_done | 所有任务完成 | deploy | | deployed | 已部署 | seal | | sealed | 已封版 | - |

⚙️ 配置

.dev-pipeline/config.json：

{
  "project": {
    "name": "gemini-agent",
    "repo_path": "."
  },
  "oracle": {
    "model": "claude-opus-4-6",
    "engine": "op46"
  },
  "output": {
    "encoding": "utf-8",
    "lineEnding": "lf"
  }
}

🔒 安全规则

1. init 时必须 version-prepare - 确保代码来源正确 2. deploy 时必须 version-validate - 确保代码完整性 3. seal 时必须 version-archive - 确保全量归档 4. 所有状态变更必须通过 project-update - 确保看板同步

🤖 Sub-agent 协作模式（推荐）

为解决 main session token 累积问题，dev-pipeline 支持通过 sessions_spawn` 在子 agent 中执行，main session 仅作为调度者。

架构

Main Session (调度者)
    │ 发送任务上下文
    ▼
sessions_spawn --task "dev-pipeline analyze" \
               --agent-id skill-runner \
               --mode run
    │
    ▼
Skill Runner Agent (执行者)
    │ 执行 heavy-lifting 任务
    │ 调用 Claude Opus、读写文件
    │
    ▼
返回结构化结果
    │
    ▼
Main Session (接收摘要，决策下一步)

优势

Main Session 调用示例

# 1. 初始化版本（轻量，可直接执行）
dev-pipeline init v1.3.5
2. 架构分析（重型任务，交给子 agent）
sessions_spawn \
  --task "cd /path/to/project && dev-pipeline analyze" \
  --agent-id skill-runner \
  --mode run \
  --run-timeout-seconds 350
子 agent 返回：
{
  "status": "pending_confirm",
  "action": "analyze",
  "summary": "架构分析完成，生成 DEV_PLAN.md，包含 12 个任务",
  "details": { "tasks_count": 12, "file": "versions/v1.3.5/docs/DEV_PLAN.md" }
}
[用户确认方案]
3. 代码编写（重型任务，交给子 agent）
sessions_spawn \
  --task "cd /path/to/project && dev-pipeline confirm && dev-pipeline write" \
  --agent-id skill-runner \
  --mode run \
  --run-timeout-seconds 600
4. 代码审查（重型任务，交给子 agent）
sessions_spawn \
  --task "cd /path/to/project && dev-pipeline review" \
  --agent-id skill-runner \
  --mode run \
  --run-timeout-seconds 350
5. 部署（轻量，可直接执行）
dev-pipeline deploy
6. 封版（轻量，可直接执行）
dev-pipeline seal

子 agent 返回格式

子 agent 必须返回 JSON 格式的执行结果：

{
  "status": "success|error|pending_confirm|review_passed|needs_fix",
  "action": "analyze|write|review|fix|deploy|seal",
  "summary": "中文执行摘要（不超过 1000 字）",
  "details": {
    "files_created": ["path/to/file1.js", "path/to/file2.js"],
    "files_modified": [],
    "review_score": 8.5,
    "critical_issues": 0,
    "output_preview": "关键输出片段（不超过 500 字符）"
  },
  "next_action": "需要 main session 决策的下一步",
  "logs": "/path/to/detailed.log"
}

任务分类建议

| 任务类型 | 推荐执行方式 | 原因 | |---------|------------|------| | init | Main session | 轻量，需要确认项目根目录 | | analyze | Sub-agent | 调用 Opus，返回大量内容 | | confirm | Main session | 只是状态变更 | | write | Sub-agent | 调用 Opus，生成大量代码 | | review | Sub-agent | 调用 Opus，分析大量代码 | | fix | Sub-agent | 调用 Opus，修复代码 | | deploy | Main session | 需要 SSH 权限，可能需确认 | | seal | Main session | 轻量状态变更 |

配置 Sub-agent 环境

子 agent 需要预装：

进阶：Persistent Sub-agent

对于需要连续迭代的开发流程，可启动持久化子 agent：

# 启动持久化 skill-runner
sessions_spawn \
  --label "dev-helper-v1.3.5" \
  --agent-id skill-runner \
  --mode session
然后多次发送任务
sessions_send --label "dev-helper-v1.3.5" --message "执行 analyze"
sessions_send --label "dev-helper-v1.3.5" --message "执行 write"
完成后销毁
sessions_send --label "dev-helper-v1.3.5" --message "exit"

📝 完整开发流程示例

传统模式（Main session 执行）

dev-pipeline init v1.3.5
...
dev-pipeline analyze  # ← token 累积点
dev-pipeline confirm
dev-pipeline write    # ← token 累积点
dev-pipeline review   # ← token 累积点
dev-pipeline deploy
dev-pipeline seal

Sub-agent 协作模式（推荐）

# 轻量任务：Main session
dev-pipeline init v1.3.5
重型任务：Sub-agent
sessions_spawn --task "dev-pipeline analyze" --agent-id skill-runner --mode run
Main: 接收摘要，等待用户确认
sessions_spawn --task "dev-pipeline write" --agent-id skill-runner --mode run
Main: 接收文件列表
sessions_spawn --task "dev-pipeline review" --agent-id skill-runner --mode run
Main: 接收评分和审查结论
轻量任务：Main session
dev-pipeline deploy
dev-pipeline seal