chandao

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SKILL: chandao (禅道)

SKILL: ZenTao

让 AI Agent 通过自然语言操作禅道系统。基于

scripts/*.js

（Node.js 脚本）调用 ZenTao RESTful API v2。

Enable AI Agents to operate the ZenTao system via natural language. Based on

scripts/*.js

(Node.js scripts) to call ZenTao RESTful API v2.

Quick Start

bash

undefined

bash

undefined

配置环境变量

Configure environment variables

export CHANDAO_URL="https://your-zentao.com" export CHANDAO_ACCOUNT="your_account" export CHANDAO_PASSWORD="your_password"

验证配置

Verify configuration

node scripts/auth.js --action list-products

基本用法

Basic usage

node scripts/<module>.js --action <action> [--args]

undefined

node scripts/<module>.js --action <action> [--args]

undefined

Security Guidelines

Never expose
```
CHANDAO_ACCOUNT
```
or
```
CHANDAO_PASSWORD
```
in chat, files, code, or logs.
All API calls must go through scripts — never call the ZenTao API directly.
Never read
```
.env
```
files or environment variables containing credentials in conversation output.
认证由
```
auth.js
```
自动管理（首次请求自动登录、本地 Token 文件缓存、401 自动刷新）。

Never expose
```
CHANDAO_ACCOUNT
```
or
```
CHANDAO_PASSWORD
```
in chat, files, code, or logs.
All API calls must go through scripts — never call the ZenTao API directly.
Never read
```
.env
```
files or environment variables containing credentials in conversation output.
Authentication is automatically managed by
```
auth.js
```
(auto-login on first request, local Token file caching, auto-refresh on 401).

How to Execute

首次使用 — 确认环境变量
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
已配置

验证 —

node scripts/auth.js --action list-products

匹配意图 — 从下方「意图识别规则」匹配用户自然语言。

执行 — 调用对应

scripts/<module>.js --action <action> [--args]

。

First-time use — Confirm environment variables
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
are configured

Verify —

node scripts/auth.js --action list-products

Intent matching — Match user natural language with the "Intent Recognition Rules" below.

Execute — Call the corresponding

scripts/<module>.js --action <action> [--args]

脚本列表

Script List

脚本	模块	操作
`auth.js`	认证	`login` / `get-token` / `list-products`
`product.js`	产品	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`project.js`	项目	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`story.js`	需求	`list` / `get` / `create` / `update` / `close` / `activate` / `change` / `delete`
`task.js`	任务	`list` / `get` / `create` / `update` / `start` / `finish` / `close` / `activate` / `delete`
`execution.js`	执行	`list` / `get` / `create` / `update` / `start` / `suspend` / `close` / `link-products` / `delete`
`bug.js`	Bug	`list` / `get` / `create` / `update` / `resolve` / `close` / `activate` / `delete`
`testcase.js`	测试用例	`list` / `get` / `create` / `update` / `delete`

Script	Module	Operations
`auth.js`	Authentication	`login` / `get-token` / `list-products`
`product.js`	Product	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`project.js`	Project	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`story.js`	Story	`list` / `get` / `create` / `update` / `close` / `activate` / `change` / `delete`
`task.js`	Task	`list` / `get` / `create` / `update` / `start` / `finish` / `close` / `activate` / `delete`
`execution.js`	Execution	`list` / `get` / `create` / `update` / `start` / `suspend` / `close` / `link-products` / `delete`
`bug.js`	Bug	`list` / `get` / `create` / `update` / `resolve` / `close` / `activate` / `delete`
`testcase.js`	Test Case	`list` / `get` / `create` / `update` / `delete`

通用选项

Common Options

```
--dry-run
```
— 预览操作结果，不实际执行（所有写操作）
```
--limit <N>
```
— 每页数量，默认 20，最大 1000（所有列表操作）
```
--page <N>
```
— 页码，从 1 开始（所有列表操作）
```
--yes
```
— 确认删除，不加则只提示不执行（所有 delete 操作）

```
--dry-run
```
— Preview operation results without actual execution (all write operations)
```
--limit <N>
```
— Number of items per page, default 20, max 1000 (all list operations)
```
--page <N>
```
— Page number, starts from 1 (all list operations)
```
--yes
```
— Confirm deletion, without this flag it only prompts but doesn't execute (all delete operations)

意图识别规则

Intent Recognition Rules

环境配置

Environment Configuration

"配置禅道" / "设置禅道" / "找不到禅道" → 引导配置
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
"登录失败" / "认证失败" / "401" → 提示检查环境变量中的账号密码
"查产品" / "产品列表" / "有哪些产品" →
```
node scripts/product.js --action list
```

"产品详情" / "看看产品 X" →

node scripts/product.js --action get --id <id>

"创建产品" / "新建产品" →

node scripts/product.js --action create --name <name>

"更新产品" / "修改产品" / "编辑产品" →
```
node scripts/product.js --action update --id <id>
```

"删除产品" →

node scripts/product.js --action delete --id <id>

"项目集的产品" / "项目集 N 的产品" →

node scripts/product.js --action list-by-program --program N

"Configure ZenTao" / "Set up ZenTao" / "Cannot find ZenTao" → Guide user to configure
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
"Login failed" / "Authentication failed" / "401" → Prompt user to check account and password in environment variables
"Query products" / "Product list" / "What products are there" →
```
node scripts/product.js --action list
```

"Product details" / "Check product X" →

node scripts/product.js --action get --id <id>

"Create product" / "New product" →

node scripts/product.js --action create --name <name>

"Update product" / "Modify product" / "Edit product" →
```
node scripts/product.js --action update --id <id>
```

"Delete product" →

node scripts/product.js --action delete --id <id>

"Products in program" / "Products in program N" →

node scripts/product.js --action list-by-program --program N

产品透传参数

Product Pass-through Parameters

用户关键词	提取字段	取值
正常	`--type`	`normal`
多分支	`--type`	`branch`
多平台	`--type`	`platform`
公开	`--acl`	`open`
私有	`--acl`	`private`

User Keyword	Extracted Field	Value
Normal	`--type`	`normal`
Multi-branch	`--type`	`branch`
Multi-platform	`--type`	`platform`
Public	`--acl`	`open`
Private	`--acl`	`private`

项目管理

Project Management

"查项目" / "项目列表" / "有哪些项目" →
```
node scripts/project.js --action list
```

"项目详情" / "看看项目 X" →

node scripts/project.js --action get --id <id>

"创建项目" / "新建项目" →

node scripts/project.js --action create --name <name> --model <model> --begin <date> --end <date>

"更新项目" / "修改项目" / "编辑项目" →
```
node scripts/project.js --action update --id <id>
```

"删除项目" →

node scripts/project.js --action delete --id <id>

"项目集的项目" / "项目集 N 的项目" →

node scripts/project.js --action list-by-program --program N

"Query projects" / "Project list" / "What projects are there" →
```
node scripts/project.js --action list
```

"Project details" / "Check project X" →

node scripts/project.js --action get --id <id>

"Create project" / "New project" →

node scripts/project.js --action create --name <name> --model <model> --begin <date> --end <date>

"Update project" / "Modify project" / "Edit project" →
```
node scripts/project.js --action update --id <id>
```

"Delete project" →

node scripts/project.js --action delete --id <id>

"Projects in program" / "Projects in program N" →

node scripts/project.js --action list-by-program --program N

项目透传参数

Project Pass-through Parameters

用户关键词	提取字段	取值
敏捷 / Scrum	`--model`	`scrum`
瀑布 / Waterfall	`--model`	`waterfall`
看板 / Kanban	`--model`	`kanban`
融合敏捷 / Agile Plus	`--model`	`agileplus`
融合瀑布 / Waterfall Plus	`--model`	`waterfallplus`

User Keyword	Extracted Field	Value
Agile / Scrum	`--model`	`scrum`
Waterfall	`--model`	`waterfall`
Kanban	`--model`	`kanban`
Agile Plus	`--model`	`agileplus`
Waterfall Plus	`--model`	`waterfallplus`

通用更新规则

Common Update Rules

⚠️ 所有更新操作前必须先获取当前值 禅道 API 的 PUT 请求会将未包含的字段重置为默认值（如优先级会从2变成3）。

正确流程（脚本内部已自动实现）：

先
```
GET /<module>/<id>
```
获取当前值
保留需要保持不变的字段值
只修改需要更新的字段
将所有字段一起发送更新请求

影响范围：

story update

、

task update

、

execution update

、

bug update

、

product update

、

project update

、

testcase update

等所有 update 操作。

详见：

references/pitfalls.md

第 23 条

⚠️ Must get current values before all update operations ZenTao API's PUT request will reset fields not included to default values (e.g., priority will change from 2 to 3).

Correct Flow (automatically implemented in scripts):

First
```
GET /<module>/<id>
```
to get current values
Keep values of fields that need to remain unchanged
Only modify fields that need to be updated
Send all fields together in the update request

Affected Scope:

story update

task update

execution update

bug update

product update

project update

testcase update

and all other update operations.

See Details: Item 23 in

references/pitfalls.md

⭐ 重要：一次性创建原则

⭐ Important: One-time Creation Principle

🎯 核心原则：上下文参数一次性传递，避免先创建后更新

当用户提供的自然语言中包含多个参数时，必须在创建时一次性传入所有已知参数，而不是先创建再更新。

❌ 错误做法（两次API调用）：

bash

undefined

🎯 Core Principle: Pass all context parameters at once, avoid create-then-update

When user's natural language contains multiple parameters, must pass all known parameters during creation, instead of creating first then updating.

❌ Wrong Approach (two API calls):

bash

undefined

第1次：只传必填参数创建

1st call: Create with only required parameters

node scripts/execution.js --action create --project 11 --name "迭代39" --begin 2026-06-01 --end 2026-06-15

node scripts/execution.js --action create --project 11 --name "Sprint 39" --begin 2026-06-01 --end 2026-06-15

第2次：再更新补充其他参数

2nd call: Update to add other parameters

node scripts/execution.js --action update --id 39 --products 21 --lifetime short


**✅ 正确做法**（一次API调用）：
```bash

node scripts/execution.js --action update --id 39 --products 21 --lifetime short


**✅ Correct Approach** (one API call):
```bash

一次性传入所有参数

Pass all parameters at once

node scripts/execution.js --action create
--project 11
--name "迭代39"
--begin 2026-06-01
--end 2026-06-15
--products 21
--lifetime short


**适用场景**：
- ✅ 创建迭代时已知产品、负责人、类型等 → 创建时全部传入
- ✅ 创建需求时已知模块、优先级、来源等 → 创建时全部传入
- ✅ 创建任务时已知指派人、预估时间、关联故事等 → 创建时全部传入
- ✅ 创建Bug时已知严重程度、影响版本、关联执行等 → 创建时全部传入

**原因**：
1. 🚀 **减少API调用**：1次 vs 2次，提升效率
2. 📊 **数据一致性**：避免中间状态
3. ⚡ **用户体验**：一次性完成，无需等待二次更新
4. 🔒 **避免错误**：减少更新操作中可能遇到的字段重置问题

**Agent执行规则**：
> 📌 从用户指令中提取所有可用参数后，**立即组装完整命令执行创建**，不要分步操作。

node scripts/execution.js --action create
--project 11
--name "Sprint 39"
--begin 2026-06-01
--end 2026-06-15
--products 21
--lifetime short


**Applicable Scenarios**:
- ✅ When creating a sprint, product, owner, type, etc. are known → Pass all during creation
- ✅ When creating a story, module, priority, source, etc. are known → Pass all during creation
- ✅ When creating a task, assignee, estimated time, linked story, etc. are known → Pass all during creation
- ✅ When creating a bug, severity, affected version, linked execution, etc. are known → Pass all during creation

**Reasons**:
1. 🚀 **Reduce API Calls**: 1 vs 2, improve efficiency
2. 📊 **Data Consistency**: Avoid intermediate states
3. ⚡ **User Experience**: Complete in one go, no need to wait for secondary update
4. 🔒 **Avoid Errors**: Reduce field reset issues that may occur during update operations

**Agent Execution Rules**:
> 📌 After extracting all available parameters from user's instruction, **immediately assemble the complete command and execute creation**, do not operate step by step.

模糊指令处理

Fuzzy Instruction Handling

"看下项目" / "查看项目" / "项目详情" 未提供 ID → 追问用户："请提供项目 ID"
"更新项目" / "修改项目" 未提供 ID → 追问用户："请提供项目 ID"
"删除项目" 未提供 ID → 追问用户："请提供项目 ID"

"Check project" / "View project" / "Project details" without providing ID → Ask user: "Please provide the project ID"
"Update project" / "Modify project" without providing ID → Ask user: "Please provide the project ID"
"Delete project" without providing ID → Ask user: "Please provide the project ID"

需求管理

Story Management

"列出需求" / "需求列表" →
```
node scripts/story.js --action list
```

"项目 N 的需求" →

node scripts/story.js --action list --project N

"执行 N 的需求" →

node scripts/story.js --action list --execution N

"需求详情" / "查看需求" →

node scripts/story.js --action get --id <id>

"创建需求" / "新增需求" →

node scripts/story.js --action create --product <id> --title <title>

"更新需求" / "修改需求" →

node scripts/story.js --action update --id <id>

"激活需求" / "重新打开需求" →

node scripts/story.js --action activate --id <id>

"关闭需求" →

node scripts/story.js --action close --id <id> --reason done

"变更需求" →

node scripts/story.js --action change --id <id> --reviewer <account>

⚠️ 重要：spec/verify 字段格式要求

需求描述（
```
--spec
```
）和验收标准（
```
--verify
```
）字段必须使用 HTML 格式
不可使用 Markdown 格式（如
```
# 标题
```
、
```
**粗体**
```
、
```
- 列表
```
）

应使用 HTML 标签（如

<h2>标题</h2>

、

<strong>粗体</strong>

、

<ul><li>列表</li></ul>

）

"List stories" / "Story list" →
```
node scripts/story.js --action list
```

"Stories in project N" →

node scripts/story.js --action list --project N

"Stories in execution N" →

node scripts/story.js --action list --execution N

"Story details" / "View story" →

node scripts/story.js --action get --id <id>

"Create story" / "New story" →

node scripts/story.js --action create --product <id> --title <title>

"Update story" / "Modify story" →

node scripts/story.js --action update --id <id>

"Activate story" / "Reopen story" →

node scripts/story.js --action activate --id <id>

"Close story" →

node scripts/story.js --action close --id <id> --reason done

"Change story" →

node scripts/story.js --action change --id <id> --reviewer <account>

⚠️ Important: Format Requirements for spec/verify Fields

Story description (
```
--spec
```
) and acceptance criteria (
```
--verify
```
) fields must use HTML format
Markdown format is not allowed (e.g.,
```
# Title
```
,
```
**Bold**
```
,
```
- List
```
)

Use HTML tags instead (e.g.,

<h2>Title</h2>

<strong>Bold</strong>

<ul><li>List</li></ul>

)

需求透传参数

Story Pass-through Parameters

用户关键词	提取字段	取值
功能	`--category`	`feature`
接口	`--category`	`interface`
性能	`--category`	`performance`
安全	`--category`	`safe`
体验	`--category`	`experience`
改进	`--category`	`improve`
客户	`--source`	`customer`
用户	`--source`	`user`

User Keyword	Extracted Field	Value
Feature	`--category`	`feature`
Interface	`--category`	`interface`
Performance	`--category`	`performance`
Security	`--category`	`safe`
Experience	`--category`	`experience`
Improvement	`--category`	`improve`
Customer	`--source`	`customer`
User	`--source`	`user`

任务管理

Task Management

"列出任务" / "任务列表" →

node scripts/task.js --action list --execution <id>

"任务详情" / "查看任务" →

node scripts/task.js --action get --id <id>

"创建任务" / "新建任务" →

node scripts/task.js --action create --execution <id> --name <name>

"开始任务" / "认领" →

node scripts/task.js --action start --id <id>

"完成任务" →

node scripts/task.js --action finish --id <id> --consumed <hours>

"关闭任务" →

node scripts/task.js --action close --id <id>

"激活任务" →

node scripts/task.js --action activate --id <id>

"删除任务" →

node scripts/task.js --action delete --id <id>

"List tasks" / "Task list" →

node scripts/task.js --action list --execution <id>

"Task details" / "View task" →

node scripts/task.js --action get --id <id>

"Create task" / "New task" →

node scripts/task.js --action create --execution <id> --name <name>

"Start task" / "Claim task" →

node scripts/task.js --action start --id <id>

"Finish task" →

node scripts/task.js --action finish --id <id> --consumed <hours>

"Close task" →

node scripts/task.js --action close --id <id>

"Activate task" →

node scripts/task.js --action activate --id <id>

"Delete task" →

node scripts/task.js --action delete --id <id>

任务透传参数

Task Pass-through Parameters

用户关键词	提取字段	取值
开发	`--type`	`devel`
测试	`--type`	`test`
设计	`--type`	`design`
讨论	`--type`	`discuss`
界面/UI	`--type`	`ui`

User Keyword	Extracted Field	Value
Development	`--type`	`devel`
Testing	`--type`	`test`
Design	`--type`	`design`
Discussion	`--type`	`discuss`
UI/Interface	`--type`	`ui`

迭代/执行管理

Execution/Sprint Management

"列出执行" / "迭代列表" →

node scripts/execution.js --action list [--project N] [--status all|undone|wait|doing]

"执行详情" / "查看迭代" →

node scripts/execution.js --action get --id <id>

"创建执行" / "新建迭代" →

node scripts/execution.js --action create --project <id> --name <name> --begin <date> --end <date> [--products <ids>]

"更新执行" / "修改执行" / "编辑执行" →

node scripts/execution.js --action update --id <id> [--products <ids>]

"启动执行" / "启动迭代" →

node scripts/execution.js --action start --id <id>

"暂停执行" / "暂停迭代" →

node scripts/execution.js --action suspend --id <id>

"关闭执行" / "关闭迭代" →

node scripts/execution.js --action close --id <id>

"删除执行" / "删除迭代" →

node scripts/execution.js --action delete --id <id>

⚠️ 关联产品说明：
✅ 推荐方式：在
create
或
update
时使用
--products
参数关联产品
❌ 不支持：
link-products
动作（禅道 API 返回 403 权限错误）
📝 关联规则：迭代必须先关联项目，只能关联项目已关联的产品
示例：
node scripts/execution.js --action create --project 11 --name "迭代" --begin 2026-06-01 --end 2026-06-15 --products 21

"List executions" / "Sprint list" →

node scripts/execution.js --action list [--project N] [--status all|undone|wait|doing]

"Execution details" / "View sprint" →

node scripts/execution.js --action get --id <id>

"Create execution" / "New sprint" →

node scripts/execution.js --action create --project <id> --name <name> --begin <date> --end <date> [--products <ids>]

"Update execution" / "Modify execution" / "Edit execution" →

node scripts/execution.js --action update --id <id> [--products <ids>]

"Start execution" / "Start sprint" →

node scripts/execution.js --action start --id <id>

"Suspend execution" / "Suspend sprint" →

node scripts/execution.js --action suspend --id <id>

"Close execution" / "Close sprint" →

node scripts/execution.js --action close --id <id>

"Delete execution" / "Delete sprint" →

node scripts/execution.js --action delete --id <id>

⚠️ Product Association Notes:
✅ Recommended Method: Use
--products
parameter to associate products during
create
or
update
❌ Not Supported:
link-products
action (ZenTao API returns 403 permission error)
📝 Association Rules: Sprint must first be associated with a project, and can only associate products that the project has already associated
Example:
node scripts/execution.js --action create --project 11 --name "Sprint" --begin 2026-06-01 --end 2026-06-15 --products 21

执行透传参数

Execution Pass-through Parameters

用户关键词	提取字段	取值
敏捷 / Scrum	`--type`	`sprint`
看板 / Kanban	`--type`	`kanban`
短期	`--lifetime`	`short`
长期	`--lifetime`	`long`
运维	`--lifetime`	`ops`
公开	`--acl`	`open`
私有	`--acl`	`private`

User Keyword	Extracted Field	Value
Agile / Scrum	`--type`	`sprint`
Kanban	`--type`	`kanban`
Short-term	`--lifetime`	`short`
Long-term	`--lifetime`	`long`
Ops	`--lifetime`	`ops`
Public	`--acl`	`open`
Private	`--acl`	`private`

Bug 管理

Bug Management

"Bug 列表" / "列出 Bug" →
```
node scripts/bug.js --action list
```

"产品 N 的 Bug" →

node scripts/bug.js --action list --product N

"项目 N 的 Bug" →

node scripts/bug.js --action list --project N

"执行下的 Bug" / "迭代 Bug" / "执行 N 的 bug" →
```
node scripts/bug.js --action list --execution <id>
```

"Bug 详情" / "查看 Bug N" →

node scripts/bug.js --action get --id <id>

"创建 Bug" / "报 Bug" →

node scripts/bug.js --action create --product <id> --title <title>

"修改 Bug" / "编辑 Bug" / "更新 Bug" →
```
node scripts/bug.js --action update --id <id>
```

"解决 Bug N" →

node scripts/bug.js --action resolve --id <id> --resolution <resolution>

"关闭 Bug N" →

node scripts/bug.js --action close --id <id>

"重新打开 Bug N" / "激活 Bug N" →

node scripts/bug.js --action activate --id <id> --openedBuild <version|trunk>

"删除 Bug N" →

node scripts/bug.js --action delete --id <id>

（需用户确认）

"Bug list" / "List bugs" →
```
node scripts/bug.js --action list
```

"Bugs in product N" →

node scripts/bug.js --action list --product N

"Bugs in project N" →

node scripts/bug.js --action list --project N

"Bugs in execution" / "Sprint bugs" / "Bugs in execution N" →
```
node scripts/bug.js --action list --execution <id>
```

"Bug details" / "View bug N" →

node scripts/bug.js --action get --id <id>

"Create bug" / "Report bug" →

node scripts/bug.js --action create --product <id> --title <title>

"Modify bug" / "Edit bug" / "Update bug" →

node scripts/bug.js --action update --id <id>

"Resolve bug N" →

node scripts/bug.js --action resolve --id <id> --resolution <resolution>

"Close bug N" →

node scripts/bug.js --action close --id <id>

"Reopen bug N" / "Activate bug N" →

node scripts/bug.js --action activate --id <id> --openedBuild <version|trunk>

"Delete bug N" →
```
node scripts/bug.js --action delete --id <id>
```
(requires user confirmation)

Bug 透传参数

Bug Pass-through Parameters

用户关键词	提取字段	取值
代码错误	`--type`	`codeerror`
配置	`--type`	`config`
安装	`--type`	`install`
安全	`--type`	`security`
性能	`--type`	`performance`
已解决	`--resolution`	`fixed`
设计如此	`--resolution`	`bydesign`
无法重现	`--resolution`	`notrepro`
严重/紧急	`--severity`	`1`
高	`--severity`	`2`
中	`--severity`	`3`
低	`--severity`	`4`

User Keyword	Extracted Field	Value
Code error	`--type`	`codeerror`
Configuration	`--type`	`config`
Installation	`--type`	`install`
Security	`--type`	`security`
Performance	`--type`	`performance`
Fixed	`--resolution`	`fixed`
By design	`--resolution`	`bydesign`
Cannot reproduce	`--resolution`	`notrepro`
Critical/Emergency	`--severity`	`1`
High	`--severity`	`2`
Medium	`--severity`	`3`
Low	`--severity`	`4`

史诗管理

Epic Management

史诗模块暂未实现，后续可按需添加。

Epic module is not implemented yet, can be added later as needed.

测试管理

Test Management

"测试用例列表" →
```
node scripts/testcase.js --action list
```

"产品 N 的用例" →

node scripts/testcase.js --action list --product N

"项目 N 的测试用例" →

node scripts/testcase.js --action list --project N

"执行 N 的测试用例" →

node scripts/testcase.js --action list --execution N

"测试用例详情" / "查看用例 N" →

node scripts/testcase.js --action get --id <id>

"创建测试用例" →

node scripts/testcase.js --action create --product <id> --title <title> --steps '...'

"修改测试用例" / "编辑用例" →

node scripts/testcase.js --action update --id <id>

"删除测试用例" / "删除用例 N" →
```
node scripts/testcase.js --action delete --id <id>
```
（需用户确认）

⚠️ 重要：测试用例步骤与预期格式要求

测试用例必须包含步骤（
--steps
），步骤中通过
```
expect
```
字段指定预期
步骤和预期均使用纯文本，禁止使用 HTML 和 Markdown

--steps

格式：

[{"step": "步骤1", "expect": "期望1", "type": "step"}, ...]

```
type
```
仅支持
```
step
```

"Test case list" →
```
node scripts/testcase.js --action list
```

"Test cases in product N" →

node scripts/testcase.js --action list --product N

"Test cases in project N" →

node scripts/testcase.js --action list --project N

"Test cases in execution N" →

node scripts/testcase.js --action list --execution N

"Test case details" / "View test case N" →

node scripts/testcase.js --action get --id <id>

"Create test case" →

node scripts/testcase.js --action create --product <id> --title <title> --steps '...'

"Modify test case" / "Edit test case" →

node scripts/testcase.js --action update --id <id>

"Delete test case" / "Delete test case N" →
```
node scripts/testcase.js --action delete --id <id>
```
(requires user confirmation)

⚠️ Important: Format Requirements for Test Case Steps and Expectations

Test cases must include steps (
--steps
), with expectations specified via the
```
expect
```
field in steps
Both steps and expectations use plain text, HTML and Markdown are prohibited

--steps

format:

[{"step": "Step 1", "expect": "Expectation 1", "type": "step"}, ...]

```
type
```
only supports
```
step
```

项目集管理

Program Management

项目集模块暂未实现，后续可按需添加。

Program module is not implemented yet, can be added later as needed.

发布/版本

Release/Version

发布/版本模块暂未实现，后续可按需添加。

Release/version module is not implemented yet, can be added later as needed.

系统管理

System Management

系统管理模块暂未实现，后续可按需添加。

System management module is not implemented yet, can be added later as needed.

Bug 修复工作流（重要！用户纠正过）

Bug Fix Workflow (Important! Corrected by User)

修复完 Bug 后必须立即更新禅道状态，不要等所有 Bug 都修完再批量处理。

bash

undefined

Must update ZenTao status immediately after fixing a bug, do not wait until all bugs are fixed to process in batches.

bash

undefined

修复完一个 Bug 后，立即执行：

After fixing a bug, execute immediately:

node scripts/bug.js --action resolve --id <id> --resolution fixed


**正确流程**：
1. 读取 Bug 列表，逐个修复
2. 每修完一个 → 编译测试 → 立即 `bug resolve`
3. 全部修完后提交代码、打版本

node scripts/bug.js --action resolve --id <id> --resolution fixed


**Correct Flow**:
1. Read bug list, fix one by one
2. After fixing each one → Compile and test → Immediately execute `bug resolve`
3. After all are fixed, submit code and tag version

错误处理

Error Handling

情况	处理
未配置环境变量	提示配置 `CHANDAO_URL` / `CHANDAO_ACCOUNT` / `CHANDAO_PASSWORD`
登录失败	提示检查环境变量中的账号密码是否正确
无数据	"暂无数据"
网络错误	友好提示，不暴露内部细节
`--dry-run` 输出	展示将要执行的操作，询问用户是否确认
HTTP 403	检查用户角色和模块权限，详见 Pitfalls

Scenario	Handling
Environment variables not configured	Prompt user to configure `CHANDAO_URL` / `CHANDAO_ACCOUNT` / `CHANDAO_PASSWORD`
Login failure	Prompt user to check if account and password in environment variables are correct
No data	"No data available"
Network error	Friendly prompt, do not expose internal details
`--dry-run` output	Show the operation to be executed, ask user for confirmation
HTTP 403	Check user role and module permissions, see Pitfalls

关键警告摘要

Key Warning Summary

详细说明见 references/pitfalls.md

⚠️ API v2 创建接口参数名必须带
```
ID
```
后缀（如
```
executionID
```
），否则返回 403
⚠️ Bug 状态流转必须用专用端点（
```
bug resolve/close/activate
```
），
```
bug update --status
```
无效
⚠️ Bug 解决建议传
```
--assigned-to
```
（否则清空指派人）和
```
--resolved-build
```
⚠️
```
story close
```
必须传
```
--reason
```
（枚举：done/subdivided/duplicate/postponed/willnotdo/cancel/bydesign）
⚠️
```
story change
```
必须传
```
--reviewer
```
⚠️
```
task finish
```
必须传
```
--consumed
```
⚠️
```
execution create
```
用
```
--project
```
（不是
```
--product
```
）
⚠️
```
bug list
```
没有
```
--pri
```
参数

⚠️

project create

必填

name

model

begin

end

，

model

取值

scrum

waterfall

kanban

agileplus

waterfallplus

⚠️
```
project create/update
```
的
```
model
```
字段与
```
execution
```
的
```
type
```
是不同概念，不要混淆

⚠️

execution create

必填

project

name

begin

end

，支持

lifetime

days

products

plans

PO

QD

PM

RD

acl

等扩展字段

⚠️
```
execution update
```
必填
```
name
```
+
```
begin
```
+
```
end
```
，
```
--project
```
用于修改所属项目
⚠️ 所有
```
delete
```
命令需要
```
--yes
```
确认
⚠️ 403 错误可能是参数名错误、用户无角色、或角色缺少模块权限
⚠️ spec/verify 字段必须使用 HTML 格式：需求描述（
```
--spec
```
）和验收标准（
```
--verify
```
）字段必须使用 HTML 格式，不可使用 Markdown
⚠️ PUT 请求会重置未包含字段为默认值：禅道 API 的 PUT 请求会将未包含在请求体中的字段重置为默认值。更新操作前必须先获取当前值，再合并用户指定的字段。详见
```
references/pitfalls.md
```
第 23 条

See details in references/pitfalls.md

⚠️ API v2 creation interface parameter names must have
```
ID
```
suffix (e.g.,
```
executionID
```
), otherwise returns 403
⚠️ Bug status transitions must use dedicated endpoints (
```
bug resolve/close/activate
```
),
```
bug update --status
```
is invalid
⚠️ It is recommended to pass
```
--assigned-to
```
when resolving bugs (otherwise assignee will be cleared) and
```
--resolved-build
```
⚠️
```
story close
```
must pass
```
--reason
```
(enum: done/subdivided/duplicate/postponed/willnotdo/cancel/bydesign)
⚠️
```
story change
```
must pass
```
--reviewer
```
⚠️
```
task finish
```
must pass
```
--consumed
```
⚠️
```
execution create
```
uses
```
--project
```
(not
```
--product
```
)
⚠️
```
bug list
```
does not have
```
--pri
```
parameter

⚠️

project create

requires

name

model

begin

end

model

values are

scrum

waterfall

kanban

agileplus

waterfallplus

⚠️
```
model
```
field in
```
project create/update
```
is a different concept from
```
type
```
in
```
execution
```
, do not confuse them

⚠️

execution create

requires

project

name

begin

end

, supports extended fields like

lifetime

days

products

plans

PO

QD

PM

RD

acl

⚠️
```
execution update
```
requires
```
name
```
+
```
begin
```
+
```
end
```
,
```
--project
```
is used to modify the associated project
⚠️ All
```
delete
```
commands require
```
--yes
```
confirmation
⚠️ 403 errors may be caused by incorrect parameter names, user has no role, or role lacks module permissions
⚠️ spec/verify fields must use HTML format: Story description (
```
--spec
```
) and acceptance criteria (
```
--verify
```
) fields must use HTML format, Markdown is not allowed
⚠️ PUT requests reset unincluded fields to default values: ZenTao API's PUT request will reset fields not included in the request body to default values. Must get current values before update operations, then merge user-specified fields. See Item 23 in
```
references/pitfalls.md
```

Core References

Topic	Description	Reference
Setup & Config	安装与环境配置	setup.md
API Pitfalls	禅道 API 踩坑记录（23 条）	pitfalls.md
Help & FAQ	常见问题解答	help.md
API Fields	v2 API 必填参数速查	zentao-v2-api-fields.md
API Quirks	API v2 常见坑点	zentao-api-v2-quirks.md
Permissions	权限与角色问题	zentao-api-permissions.md
Product API	产品管理命令	commands-product.md
Project API	项目管理命令	commands-project.md
Story API	需求管理命令	commands-story.md
Task API	任务管理命令	commands-task.md
Execution API	执行/迭代管理命令	commands-execution.md
Bug API	Bug 管理命令	commands-bug.md
Test API	测试用例管理命令	commands-test.md

Topic	Description	Reference
Setup & Config	Installation and environment configuration	setup.md
API Pitfalls	ZenTao API pitfalls (23 items)	pitfalls.md
Help & FAQ	Frequently asked questions	help.md
API Fields	v2 API required parameters quick reference	zentao-v2-api-fields.md
API Quirks	Common pitfalls of API v2	zentao-api-v2-quirks.md
Permissions	Permissions and role issues	zentao-api-permissions.md
Product API	Product management commands	commands-product.md
Project API	Project management commands	commands-project.md
Story API	Story management commands	commands-story.md
Task API	Task management commands	commands-task.md
Execution API	Execution/sprint management commands	commands-execution.md
Bug API	Bug management commands	commands-bug.md
Test API	Test case management commands	commands-test.md

脚本架构

Script Architecture

scripts/
├── auth.js         # 共享 HTTP + Token 认证 + 工具函数（所有脚本依赖）
├── product.js      # 产品 CRUD
├── project.js      # 项目 CRUD
├── story.js        # 需求 CRUD + 生命周期
├── task.js         # 任务 CRUD + 生命周期
├── execution.js    # 执行 CRUD + 生命周期
├── bug.js          # Bug CRUD + 生命周期
└── testcase.js     # 测试用例 CRUD

scripts/
├── auth.js         # Shared HTTP + Token authentication + utility functions (all scripts depend on this)
├── product.js      # Product CRUD
├── project.js      # Project CRUD
├── story.js        # Story CRUD + lifecycle
├── task.js         # Task CRUD + lifecycle
├── execution.js    # Execution CRUD + lifecycle
├── bug.js          # Bug CRUD + lifecycle
└── testcase.js     # Test Case CRUD