# Dev Toolkit Integrator

> 开发工具链集成操作指南：禅道+Jira+Wiki在迭代开发中的标准化操作流程、跨工具信息同步模板、状态流转规范。当用户说'创建禅道任务'、'写Wiki文档'、'Jira状态更新'、'需求怎么流转'、'Bug提单'、'迭代规划'、'发布版本'、'同步三个平台'时触发。核心特点：三工具联动模板、信息一次性录入多处复用、减少重复劳动、开发迭代全生命周期覆盖。

- Skill: `gaoqiongxie/dev-toolkit-integrator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaoqiongxie/dev-toolkit-integrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaoqiongxie/dev-toolkit-integrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaoqiongxie (https://skillmd.com/u/gaoqiongxie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gaoqiongxie/dev-toolkit-integrator

---


> **来源**: 自建（基于国内开发团队禅道+Jira+Wiki/Confluence/语雀的真实工作流）
>
> **发布时间**: 2026-05-28
>
> **理念**: "同一个需求，不要在三个工具里写三遍。写一次，同步三处。"

# 🔧 Dev Toolkit Integrator — 禅道·Jira·Wiki 三工具集成操作指南

开发迭代中，禅道管任务、Jira 管需求、Wiki 管文档——**这个 Skill 教你让它们说同一种语言**。

---

## 🎯 核心设计：一次录入，三处复用

```
信息源头          同步目标
─────────────────────────────────
Jira Epic/Story → 禅道需求/任务
禅道 Bug          → Jira Issue + Wiki 故障分析
Wiki 技术方案     → 禅道任务描述 + Jira 描述
代码 Commit       → 禅道任务关联 + Jira 状态更新
```

**统一信息单元（UIU: Unified Information Unit）**：

每个需求/任务/缺陷，都包含以下字段：

```yaml
uiu:
  id: "PROJ-001"                    # Jira Issue Key / 禅道编号
  title: "订单退款功能"              # 统一标题
  type: "需求/Bug/任务"              # 类型
  owner: "张三"                      # 负责人
  priority: "P0/P1/P2"              # 优先级
  status: "待开发/开发中/测试中/已上线" # 统一状态映射
  description: "..."                # 统一描述（Markdown）
  acceptance: "..."                 # 验收标准（Gherkin）
  related_docs:                     # 关联文档
    - "Wiki: 技术方案/订单退款"
    - "禅道: 任务 #1234"
    - "Jira: PROJ-001"
```

---

## 🏗️ 三工具分工与映射

| 维度 | 禅道 (ZenTao) | Jira | Wiki (Confluence/语雀/飞书) |
|------|---------------|------|---------------------------|
| **核心定位** | 国产项目管理+测试管理 | 敏捷需求+迭代跟踪 | 知识沉淀+文档协作 |
| **需求管理** | 产品-需求模块 | Epic → Story → Sub-task | 需求文档 PRD |
| **任务拆分** | 任务模块（开发/测试） | Sprint Board 任务卡 | 技术方案/拆分工时 |
| **缺陷跟踪** | Bug 模块（最常用） | Bug Issue Type | 故障复盘/根因分析 |
| **测试管理** | 用例+测试单+报表 | Zephyr/Xray 插件 | 测试报告/验收文档 |
| **迭代管理** | 产品-迭代 | Sprint + Board | 迭代计划/ retro |
| **报表统计** | 内置报表（燃尽图等） | Dashboard + JQL | 周报/月报/总结 |

### 状态映射表（关键！）

| 统一状态 | 禅道 | Jira | 说明 |
|----------|------|------|------|
| 待规划 | 草稿 | Backlog | 需求池，未排期 |
| 待开发 | 激活/进行中 | To Do | 已分配，未开始 |
| 开发中 | 进行中 | In Progress | 正在编码 |
| 待测试 | 已解决 | Ready for Test | 开发完成，提测 |
| 测试中 | 测试中 | In Testing | QA 测试中 |
| 已验收 | 已关闭 | Done | 测试通过 |
| 已上线 | 已关闭（加标签） | Closed | 生产验证通过 |
| 已驳回 | 已关闭（加原因） | Rejected | 需求变更/不做了 |

---

## 🔄 场景一：需求从 Jira 到禅道到 Wiki（正向流转）

**场景**：产品同学在 Jira 提了 Story，需要拆任务、写方案、同步禅道。

### Step 1: Jira 侧 — 需求澄清

```markdown
# Jira Story 模板

## 标题
[模块] 一句话描述需求

## 描述
作为 [角色]，我希望 [功能]，以便 [价值]

## 验收标准（Gherkin）
Given [前提]
When [操作]
Then [结果]

## 优先级
P0 - 阻塞上线 / P1 - 迭代必须 / P2 - 有则更好

## 关联
- Wiki 需求文档: [链接]
- 设计稿: [链接]
-  Epic: [PROJ-xxx]
```

### Step 2: Wiki 侧 — 写技术方案

```markdown
# 技术方案：订单退款功能

## 需求来源
- Jira: PROJ-001
- 禅道需求: #1234
- 产品负责人: 李四

## 现状分析
[当前系统状态]

## 方案设计
[架构图/流程图]

## 接口变更
| 接口 | 变更类型 | 说明 |
|------|---------|------|
| POST /api/order/refund | 新增 | 创建退款 |

## 数据库变更
| 表 | 变更 | 脚本 |
|----|------|------|
| refund_record | 新增表 | V20260528__add_refund_record.sql |

## 任务拆分（同步禅道）
| 禅道任务 | 负责人 | 工时 | 依赖 |
|----------|--------|------|------|
| #5678 退款接口开发 | 张三 | 8h | 无 |
| #5679 退款单测 | 张三 | 4h | #5678 |
| #5680 集成测试 | 王五 | 4h | #5679 |

## 风险与回滚
[风险点 + 回滚方案]

## 审批
- [ ] 技术负责人
- [ ] 测试负责人
```

### Step 3: 禅道侧 — 拆任务+建迭代

**禅道操作清单**：

```
□ 产品 → 需求 → 关联 Jira Story（标题复制，描述贴 Wiki 链接）
□ 项目 → 迭代 → 建 Sprint（名称与 Jira Sprint 一致）
□ 项目 → 任务 → 按 Wiki 方案拆分任务
  ├── 类型：开发/测试/设计/文档
  ├── 关联需求：#1234
  ├── 预估工时：按 Wiki 方案填
  └── 负责人：指定到人
□ 项目 → 任务 → 设置任务依赖关系
```

### 信息同步检查表

```markdown
## 需求同步检查表

| 检查项 | 禅道 | Jira | Wiki | 状态 |
|--------|------|------|------|------|
| 标题一致 | #1234 | PROJ-001 | 订单退款功能 | ☐ |
| 描述链接互相关联 | 含 Wiki 链接 | 含 Wiki 链接 | 含 Jira+禅道编号 | ☐ |
| 负责人一致 | 张三 | 张三 | 张三 | ☐ |
| 优先级一致 | P1 | High | P1 | ☐ |
| 状态映射正确 | 进行中 | In Progress | - | ☐ |
```

---

## 🔄 场景二：Bug 从发现到关闭（全链路）

**场景**：测试发现 Bug，提禅道，同步 Jira，修复后写 Wiki 根因分析。

### Step 1: 禅道侧 — 提 Bug（信息最全）

```markdown
# 禅道 Bug 模板

## 标题
[模块] 一句话描述 Bug

## 重现步骤
1. 登录系统，进入订单管理
2. 选择订单 #20240528001
3. 点击"退款"按钮
4. 输入金额 99999
5. 点击确认

## 实际结果
系统报错 500，无友好提示

## 期望结果
提示"退款金额不能超过订单实付金额"

## 环境
- 分支: feat/refund-v2
- 版本: v2.3.1-beta
- 浏览器: Chrome 120
- 数据库: MySQL 8.0

## 截图/日志
[附件]

## 关联
- 禅道任务: #5678
- Jira: PROJ-001
- 发现人: 测试-王五
- 负责人: 开发-张三
```

### Step 2: Jira 侧 — 同步 Bug Issue

```markdown
# Jira Bug Issue

## 标题
[Bug] 退款金额校验缺失导致 500 错误

## 描述
[复制禅道描述]

## 标签
bug, backend, refund, P1

## 关联
- Blocks: PROJ-001
- Related: 禅道 Bug #4567
```

### Step 3: 修复后 — Wiki 写根因分析

```markdown
# 故障复盘：退款金额越界导致 500

## 基本信息
| 项 | 值 |
|----|----|
| 禅道 Bug | #4567 |
| Jira | BUG-089 |
| 发现时间 | 2026-05-28 |
| 修复时间 | 2026-05-28 |
| 影响范围 | 退款功能 |
| 是否线上 | ☐ 是 ☑ 否（测试环境发现） |

## 根因分析
1. **直接原因**: Service 层缺少金额上限校验
2. **技术原因**: 入参校验只做了 @NotNull，没做 @Max
3. **流程原因**: Code Review 时未识别此边界条件

## 修复方案
- Commit: `fix: 添加退款金额上限校验`
- 文件: OrderService.java
- 方案: 校验 amount <= actualPayAmount

## 预防措施
- [ ] 补充同类接口的金额校验检查
- [ ] Code Review 检查清单增加"金额边界"
- [ ] 集成测试用例补充越界场景

## 经验教训
[教训]
```

### Step 4: 禅道+Jira 状态同步

```
禅道: Bug #4567 → 已解决 → 已关闭（验证通过）
Jira: BUG-089 → In Progress → Resolved → Closed
```

---

## 🔄 场景三：迭代规划（三工具联动）

**场景**：新 Sprint 开始，需要在三个平台同步建迭代、排任务。

### 三工具同步操作

```markdown
# Sprint 2026S13 迭代规划

## 基本信息（三平台一致）
- 名称: 2026S13（5.27-6.9）
- 目标: 完成退款功能 + 账户安全升级
- 人数: 5人（3开发 + 1测试 + 1产品）
- 工时: 10天 × 5人 × 6h = 300h

## Jira 侧
□ 创建 Sprint 2026S13
□ 从 Backlog 拉 Story 到 Sprint
□ 设置 Sprint 目标
□ 启动 Sprint

## 禅道侧
□ 产品 → 迭代 → 建迭代 2026S13
□ 关联需求到迭代
□ 项目 → 任务 → 按人分配
□ 设置任务起止时间

## Wiki 侧
□ 创建"2026S13 迭代计划"页面
□ 包含：目标/人员/Story列表/风险/里程碑
□  retro 模板预创建
```

---

## 🔄 场景四：版本发布（三工具收尾）

### 发布前检查清单

```markdown
# 版本发布检查清单 v2.4.0

## 禅道侧
□ 所有 Bug 已关闭
□ 所有任务已关闭
□ 测试单通过率 100%
□ 迭代状态：已完成

## Jira 侧
□ Sprint 已关闭
□ 所有 Story Done
□ Release 已创建
□ 版本号：v2.4.0

## Wiki 侧
□ 发布说明已编写
□ 变更日志已更新
□ 操作手册已更新
□ 回滚方案已确认

## 代码侧
□ main 分支已打 tag v2.4.0
□ CHANGELOG.md 已更新
□ 数据库迁移脚本已确认
```

### Wiki 发布说明模板

```markdown
# v2.4.0 发布说明

## 发布概要
- 版本号: v2.4.0
- 发布时间: 2026-06-10
- 禅道迭代: 2026S13
- Jira Release: v2.4.0

## 新增功能
| 功能 | 禅道需求 | Jira | 负责人 |
|------|---------|------|--------|
| 订单退款 | #1234 | PROJ-001 | 张三 |

## 修复缺陷
| Bug | 禅道 | Jira | 严重级别 |
|-----|------|------|---------|
| 退款越界 500 | #4567 | BUG-089 | P1 |

## 技术变更
- 数据库: 新增 refund_record 表
- 接口: 新增 POST /api/order/refund
- 配置: 无变更

## 回滚方案
如有异常，回滚至 v2.3.2，执行回滚脚本 rollback_v2.4.0.sql

## 验证方式
1. 登录测试环境
2. 执行退款流程
3. 检查监控告警
```

---

## 📝 常用操作速查

### 禅道速查

| 操作 | 路径 | 快捷键/技巧 |
|------|------|------------|
| 提 Bug | 测试 → Bug → 提Bug | 批量创建用"批量添加" |
| 建任务 | 项目 → 任务 → 建任务 | 用"批量添加"拆任务 |
| 更新状态 | 任务详情 → 开始/完成/关闭 | 看板视图拖拽 |
| 关联需求 | 任务 → 相关需求 → 关联 | 自动带需求描述 |
| 生成报表 | 项目 → 统计 → 燃尽图 | 导出 Excel |

### Jira 速查

| 操作 | 路径 | JQL 示例 |
|------|------|---------|
| 查我的任务 | 搜索 → 高级 | `assignee = currentUser() AND status != Closed` |
| Sprint 规划 | Backlog → 拖拽 | - |
| 状态流转 | 看板拖拽 / 详情页按钮 | - |
| 批量操作 | 搜索结果 → 批量操作 | 最多 100 条 |
| 生成报表 | 项目 → 报告 | 燃尽图、速度图、累积流 |

### Wiki 速查

| 操作 | 路径 | 模板 |
|------|------|------|
| 写技术方案 | 空间 → 创建 → 页面 | 见本 Skill 技术方案模板 |
| 写迭代计划 | 空间 → 创建 → 页面 | 见迭代规划模板 |
| 故障复盘 | 空间 → 创建 → 页面 | 见 Bug 复盘模板 |
| 发布说明 | 空间 → 创建 → 页面 | 见发布说明模板 |
| 同步更新 | 编辑 → 更新关联链接 | 确保三工具链接互相关联 |

---

## 💡 自动化建议（进阶）

### 用 Git Commit 触发状态更新

```bash
# Commit message 规范
feat(PROJ-001): 添加退款金额校验

- 校验 amount <= actualPayAmount
- 关联禅道任务 #5678
- Closes BUG-089
```

**配合 CI 脚本**：
- 解析 Commit 中的 Jira Key → 自动更新 Jira 状态为 "In Progress"
- 解析 Commit 中的禅道任务号 → 自动更新禅道任务为 "进行中"
- 解析 "Closes" → 自动更新关联 Bug 为 "已解决"

### 用 PR 模板强制信息完整

```markdown
# PR 模板

## 关联
- Jira: [ ]
- 禅道任务: [ ]
- 禅道 Bug: [ ]
- Wiki 技术方案: [ ]

## 变更
[描述]

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
```

---

## 🚀 快速入口

```
"创建禅道任务" → 禅道任务模板 + 关联需求/Bug
"写Wiki文档" → 技术方案/迭代计划/复盘/发布说明模板
"Jira状态更新" → 状态映射 + 批量操作
"需求怎么流转" → Jira→Wiki→禅道正向流转
"Bug提单" → 禅道Bug模板 + Jira同步 + Wiki根因分析
"迭代规划" → 三工具同步建Sprint
"发布版本" → 发布检查清单 + Wiki发布说明
"同步三个平台" → 信息同步检查表
```

---

## 🆚 与现有 Skill 的关系

| Skill | 关系 | 协作场景 |
|-------|------|---------|
| **backend-change-flow** | 前置 | 开发变更前，用本 Skill 在禅道/Jira 创建任务，再用 backend-change-flow 开发 |
| **solo-parallel-dev** | 互补 | 并行开发多个 feature 时，用本 Skill 管理各 feature 在三工具中的任务 |
| **create-pr** | 后置 | 代码完成后，PR 中关联禅道/Jira/Wiki，形成完整链路 |
| **quality-gate** | 后置 | 提交前检查是否关联了三工具的对应 Issue |
| **openspec-sdd** | 前置 | 需求澄清后，用本 Skill 把 Gherkin 验收标准同步到 Jira + 禅道 + Wiki |

**最佳实践链**：
```
openspec-sdd（需求澄清）
  → dev-toolkit-integrator（同步到禅道/Jira/Wiki）
  → backend-change-flow（编码开发）
  → quality-gate（提交检查）
  → create-pr（生成 PR，关联三工具）
  → dev-toolkit-integrator（更新状态/写复盘/发版本）
```

---

> "工具是手段，不是目的。三工具集成的终极目标，是让信息只写一次，让状态一眼可见，让复盘有据可查。"