link-cd

把 AI 测试结果或手工缺陷报告整理成 Bug 清单，并提交到禅道。

link-cd 提供跨平台命令行工具和 Codex Skill，适合需要在多个项目、多个前后端负责人之间分派缺陷的测试团队。配置一次项目，后续根据测试结果查重、选择负责人、批量提报，并记录每条 Bug 的编号和链接。

功能

• 项目绑定：按所选产品筛选关联项目，只有一个时自动选中；支持可选执行/迭代和实际测试版本。
• 负责人分派：按功能、组件配置责任人；无法确定时，由 Skill 展示候选并询问测试人员。
• 批量提报：整理复现步骤、预期结果、实际结果和证据，提示疑似重复 Bug。
• 提交恢复：记录逐条结果；提交中断后继续处理，结果不明时先核实。
• 截图证据：上传截图并关联 Bug，也可以给已提交的 Bug 补图。
• 共享登录：同一系统用户的多个项目复用 Token，不保存账号密码。
• 更新检测：检查 npm 最新版本，通过命令升级工具和 Skill。
• 回归验证：读取已有 Bug、生成回归报告，按授权关闭通过项或激活仍复现的原 Bug。

使用要求

• Node.js 20 或更高版本，以及 npm。
• Windows、macOS 或 Linux。
• 可以访问的禅道开源版 18.6 实例，账号具有对应产品、项目的访问和 Bug 创建权限。
• 使用 AI 工作流时需要 Codex 和可用的测试工具；单独使用 CLI 不需要 Codex。

当前适配目标是禅道 18.6，其他版本尚未验证。link-cd 负责报告整理与提报，测试执行由你已有的浏览器、接口或其他测试工具完成。

快速开始

1. 安装

npm install -g link-cd
link-cd --version

如果所用 npm 镜像尚未同步，可从官方 registry 安装：

npm install -g link-cd --registry=https://registry.npmjs.org/

2. 登录禅道

在本机终端运行，替换为你的禅道根地址；部署在子目录时保留该路径：

link-cd login --server https://zentao.example.com

按提示输入禅道账号和密码。也可以运行 link-cd login，在交互过程中填写或修改地址。登录成功后全局保存 Token，过期时重新登录即可。

3. 初始化业务项目

进入要测试的项目目录：

cd my-project
link-cd init

按提示选择产品。工具优先获取该产品关联的项目，只有一个可用项目时自动选中，多个时再询问；关联接口无权限或不支持时，退回普通项目列表并提示关联未验证。

之后选择可选的执行/迭代、测试版本，以及项目的前端、后端和测试人员。无需项目详情权限；迭代列表不可访问时跳过绑定。未绑定执行时，人员来自可访问的用户列表，由你标记项目分工；绑定执行后按其成员筛选。工具生成 .zentao/config.yaml，并安装全局 zentao-bugs Skill。

每个业务项目初始化一次。一个项目有多个前端、后端或不同功能负责人时，可以继续完善配置里的组件和功能分工。

列表支持输入关键词搜索：产品、项目、迭代和版本可按名称或 ID 筛选，人员可按姓名或账号筛选。用方向键移动、Enter 确认；人员多选时按空格勾选、Enter 完成，切换关键词会保留已选人员。按 Esc 或 Ctrl+U 清空搜索。

4. 在 Codex 中使用

在 Codex 打开初始化后的业务项目，输入：

使用 $zentao-bugs，根据刚才的测试结果整理 Bug 清单，提交已确认的应用缺陷；负责人不明确时让我选择。

也可以把测试与提报连起来：

测试订单查询和导出功能，然后使用 $zentao-bugs 整理结果并提交已确认的缺陷。

Skill 会根据项目配置准备清单，集中询问缺失信息、负责人或疑似重复项，再提交可处理的条目。如果只想生成草稿，可以说：

使用 $zentao-bugs 整理这份测试结果，先生成清单，等我确认后再提交。

若 Codex 没有识别到 Skill，运行 link-cd skill install，然后重新启动 Codex。

使用已有报告

CLI 接收符合报告格式的 JSON。让 AI 将已有测试结果转换为报告后，在项目目录运行：

link-cd validate report.json
link-cd prepare report.json

validate 检查格式；prepare 读取禅道数据，输出缺失字段、负责人候选和疑似重复项，不创建 Bug。确认清单并补齐选择后：

link-cd decide report.json --ids F-001,F-002 --assignee dev_account
link-cd submit report.json
link-cd status report.json

把 dev_account 换成真实禅道账号。submit 会创建符合提交条件的 Bug；成功条目返回编号与链接，未完成条目保留原因。

报告包含稳定的 report_id、发现 ID、测试环境、统计结果和 findings。应用缺陷需包含复现步骤、预期、实际结果、复现情况及证据。环境故障、测试脚本问题和待确认项保留在报告中，不直接当作应用缺陷提交。

随包提供报告格式 schemas/qa-report.schema.json、样例 examples/ai-test-report.json 和进阶指南 NODE.md。样例标记为 example: true，不会作为真实测试结果提交。

常用命令

| 命令 | 用途 | | --- | --- | | link-cd login | 登录或重新登录，可交互修改禅道地址 | | link-cd init | 绑定项目并安装 Skill | | link-cd status --verify | 验证当前登录是否有效 | | link-cd prepare report.json | 生成提报计划，不创建 Bug | | link-cd submit report.json | 提交可处理的缺陷 | | link-cd status report.json | 查看各条提交结果 | | link-cd reconcile report.json | 核实结果不明的提交 | | link-cd evidence report.json --ids F-001 | 给已有 Bug 补充截图 | | link-cd doctor | 检查本机 Token 存储和锁机制 | | link-cd logout | 清除当前登录配置在本机保存的 Token | | link-cd update --check | 检查是否有新版本 | | link-cd update | 升级工具并同步 Skill |

完整参数可以用 link-cd --help 或 link-cd <命令> --help 查看。

重新绑定项目时使用 link-cd init --force。命令会先备份配置，并用本次选择刷新人员、前端/后端组件、测试版本和候选受理人；功能规则、其他目标别名、自定义字段及提交模式等团队设置会保留。未勾选人员会清空该角色的旧分工，“暂不指定”版本会清空旧版本。

回归与关闭 Bug

从 0.4.0 起支持已有 Bug 的回归流程。在 Codex 中可以说：

使用 $zentao-bugs 回归当前项目已修复的 Bug，通过的关闭，仍复现的激活并指派给修复人；环境阻塞的保留状态。

只要求回归测试时，Skill 先生成结果清单；明确要求关闭或激活时，才更新对应状态。测试使用现有工具，并记录实际版本、步骤和证据。

也可以使用 CLI：

link-cd regression list
link-cd regression start --ids 123,456

start 返回待填写报告路径，保留原 Bug 快照。将真实回归结果填写到报告后：

link-cd regression prepare regression.json
link-cd regression apply regression.json --close-passed --activate-failed
link-cd regression status regression.json
link-cd regression reconcile regression.json

把 regression.json 换成实际报告路径。默认筛选当前目标的已解决、解决方案为 fixed 的 Bug；关闭只处理已验证通过且仍为 resolved/fixed 的条目。失败时更新原 Bug，不重复提单。环境阻塞、证据缺失和回归期间状态变化都会保留待处理状态。激活负责人优先采用原修复人，无有效账号时询问选择。

关闭与激活开关可分别使用，账号需要对应的 bug-close / bug-activate 权限。结果不明时先核实操作历史中的报告标识；继续同一份报告，不重发已完成条目。截图写入回归备注作为内联图片，普通文件和视频保留本地。详见随包提供的 NODE.md。

配置与登录存储

项目配置位于 .zentao/config.yaml，记录产品、项目、人员、组件、功能和默认提报规则，可由团队共享。账号密码和 Token 不写入项目配置。个人报告、证据与提交台账应放在 .zentao/.local/；初始化时会添加 Git 忽略规则。

Token 保存于当前系统用户的全局目录，多个项目可以引用同一登录配置。Windows 使用 DPAPI 加密；macOS/Linux 使用仅当前用户可访问的文件权限保护，Token 文件本身不加密。

需要连接多个禅道实例时，用 --profile 区分登录配置：

link-cd --profile team-a login --server https://zentao.example.com
link-cd --profile team-a init

中断恢复与使用边界

部分提交失败后，保留原报告 ID、发现 ID 和本地台账，修正问题后继续使用同一份报告。状态为 submitting 或 submission_unknown 时，先运行 reconcile。无法唯一确认结果时，需要核对禅道中的记录，避免重复创建。

查重结果是候选，疑似重复需要选择关联已有 Bug 或仍然新建。负责人不明确时不会凭空猜测；在 Codex 中由 Skill 组织选择，直接使用 CLI 时用 decide 保存决定。

PNG、JPEG、GIF、BMP、WebP 截图支持上传。视频和普通文件保留本地，标记为 local_only，需要另行处理。连接、权限或登录问题会暂停后续提交，已完成的结果仍可查询。

更新

link-cd update --check
link-cd update

工具从官方 npm registry 检测更新。普通命令每天最多在后台检查一次，有新版本时提示，不自动升级；后台查询失败不影响当前操作。升级保留全局登录、项目配置和报告台账。