147 lines
4.8 KiB
Markdown
147 lines
4.8 KiB
Markdown
---
|
||
name: zentao
|
||
description: 禅道 Bug 管理集成 — 查询/创建/更新 Bug 与备注。在归档(archive)、验收(acceptance)、测试(test)流程中自动触发，也可手动调用 /zentao。遵守 AGENTS.md Bug 状态管理铁律。
|
||
triggers:
|
||
- /zentao
|
||
- archive 完成后自动回写备注
|
||
- acceptance 通过后自动更新状态
|
||
- playwright-test 完成后自动回写测试结果
|
||
---
|
||
|
||
# 禅道集成技能（开源版）
|
||
|
||
> 服务器: https://zentao.gentronhealth.com
|
||
> API 基址: https://zentao.gentronhealth.com/api.php/v1
|
||
> 文档: https://zentao.gentronhealth.com/api.php/v1/index.html
|
||
|
||
## 🔒 铁律（必须硬编码到所有操作中）
|
||
|
||
来自 AGENTS.md：
|
||
|
||
```
|
||
铁律A: 人类提的 Bug → 只加备注，不改状态，不改分配
|
||
铁律B: 智能体提的 Bug → 可改分配 + 加备注
|
||
铁律C: 已关闭/已解决的 Bug → 不再处理（只读查询）
|
||
铁律D: 任何修改前先 GET 一次，确认状态和提出人
|
||
```
|
||
|
||
**判定提出人**：`openedBy` 字段。
|
||
- 若 `openedBy` 是 `admin`/`chenqi` 等人类账号 → 铁律A
|
||
- 若 `openedBy` 是 `agent-bot`/`qodercn` 等智能体账号 → 铁律B
|
||
- 若 `status` ∈ {`closed`, `resolved`} → 铁律C
|
||
|
||
## 📦 配置（首次使用前必填）
|
||
|
||
在 `D:/his/.qoder/skills/zentao/.env` 中填入：
|
||
```
|
||
ZENTAO_URL=https://zentao.gentronhealth.com
|
||
ZENTAO_TOKEN=<从禅道「个人设置 → API接口」获取>
|
||
ZENTAO_PRODUCT_ID=<产品浏览页 URL 中的数字>
|
||
ZENTAO_DEFAULT_EXECUTION=<默认执行 ID，可选>
|
||
ZENTAO_AGENT_ACCOUNT=qodercn # 智能体自身账号，用于铁律B判定
|
||
```
|
||
|
||
获取 Token：登录 → 右上角用户名 → 「个人设置」 → 「API接口」 → 新增 Token。
|
||
|
||
## 🔧 可用操作
|
||
|
||
### 1. 查询 Bug
|
||
```bash
|
||
python .qoder/skills/zentao/scripts/zentao_client.py get <bug_id>
|
||
```
|
||
返回 JSON：`id, title, status, openedBy, assignedTo, severity, pri, steps`。
|
||
**每次修改前必须先 `get` 一次**，确认铁律适用。
|
||
|
||
### 2. 添加备注（最安全操作，所有 Bug 通用）
|
||
```bash
|
||
python .qoder/skills/zentao/scripts/zentao_client.py comment <bug_id> "备注内容"
|
||
```
|
||
备注会自动加上前缀 `[QoderCN @ 2026-06-15 HH:MM]`。
|
||
**归档/验收/测试完成后必须调用此命令回写结果**。
|
||
|
||
### 3. 创建 Bug（智能体提的 Bug）
|
||
```bash
|
||
python .qoder/skills/zentao/scripts/zentao_client.py create \
|
||
--title "xxx" --steps "复现步骤..." --severity 2 --pri 2 \
|
||
--assignedTo zhangsan --module 0
|
||
```
|
||
`openedBy` 将自动设为 `ZENTAO_AGENT_ACCOUNT`。
|
||
|
||
### 4. 更新 Bug（受铁律约束）
|
||
```bash
|
||
python .qoder/skills/zentao/scripts/zentao_client.py update <bug_id> \
|
||
--status resolved --resolution fixed --assignedTo lisi
|
||
```
|
||
**脚本内置铁律检查**：
|
||
- 若 `openedBy` 是人类 → 拒绝修改 `status`/`assignedTo`，只允许 `comment`
|
||
- 若 Bug 已关闭/已解决 → 拒绝任何写操作
|
||
|
||
### 5. 批量查询
|
||
```bash
|
||
python .qoder/skills/zentao/scripts/zentao_client.py list \
|
||
--status active --assignedTo zhangsan --limit 20
|
||
```
|
||
|
||
## 🔄 自动嵌入流程
|
||
|
||
### 归档后（chenlin-archive 完成）
|
||
```
|
||
[chenlin 完成归档]
|
||
↓
|
||
[zentao] 自动触发:
|
||
1. 获取 Bug 信息（get <id>）
|
||
2. 添加归档备注：「已归档，commit: abc1234，分支: develop」
|
||
3. 若为智能体提的 Bug → 更新状态为 resolved
|
||
4. 若为人类提的 Bug → 仅加备注，等待人类手动关闭
|
||
```
|
||
|
||
### 验收通过后（acceptance 完成）
|
||
```
|
||
[huatuo 验收通过]
|
||
↓
|
||
[zentao] 自动触发:
|
||
1. 添加验收备注：「验收通过，证据: [测试报告路径]」
|
||
2. 按铁律更新状态
|
||
```
|
||
|
||
### 测试完成后（playwright-test 完成）
|
||
```
|
||
[zhangfei 测试通过]
|
||
↓
|
||
[zentao] 自动触发:
|
||
1. 添加测试备注：「Playwright 回归通过，X/Y 用例全过，报告: [路径]」
|
||
```
|
||
|
||
## 🛡️ 安全与审计
|
||
|
||
- 所有写操作记录到 `D:/his/.qoder/skills/zentao/audit.log`，格式：
|
||
```
|
||
[ISO时间] [操作人] [动作] [bug_id] [结果] [摘要]
|
||
```
|
||
- Token 不打印到 stdout，不从 git 提交（已加入 `.gitignore`）
|
||
- 写操作失败时返回非零退出码 + JSON 错误，便于上层捕获
|
||
|
||
## 🧪 手动调用示例
|
||
|
||
```
|
||
/zentao get 318
|
||
/zentao comment 318 "后端编译通过，前端 lint 通过，待验收"
|
||
/zentao list --status active --assignedTo chenqi
|
||
/zentao create --title "登录页验证码刷新失效" --steps "1. 打开登录页 2. 点击验证码 3. ..." --severity 2
|
||
```
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
| 陷阱 | 说明 |
|
||
|------|------|
|
||
| 修改人类提的 Bug 状态 | 触发铁律A，脚本会拒绝执行 |
|
||
| 操作已关闭 Bug | 触发铁律C，只允许 `get` |
|
||
| Token 过期 | 禅道 Token 默认有效期 1 年，过期需重新生成 |
|
||
| 开源版 vs 企业版 API 差异 | 本技能仅适配开源版，企业版需另行适配 |
|
||
|
||
## 📋 依赖
|
||
|
||
- Python 3.8+
|
||
- `requests` 库（`pip install requests`）
|
||
- 网络可达 `zentao.gentronhealth.com`
|