story (v2)

CRITICAL — 开始前 MUST 先用 Read 工具读取 [../zentao-shared/SKILL.md](../zentao-shared/SKILL.md)，其中包含认证、环境变量配置、错误处理和状态值定义。

Commands

• [story list](./references/zentao-story-list.md) — 列出产品下的需求列表
• [story get](./references/zentao-story-get.md) — 获取需求详情
• [story create](./references/zentao-story-create.md) — 创建新需求
• [story update](./references/zentao-story-update.md) — 更新需求信息
• [story change](./references/zentao-story-change.md) — 变更需求
• [story delete](./references/zentao-story-delete.md) — 删除需求
• [story close](./references/zentao-story-close.md) — 关闭需求

Story Lifecycle

需求在 ZenTao 中有明确的生命周期状态：

draft → active → changed → closed
         ↑         ↓
         └─────────┘ (可重新激活)

Valid Status Transitions

Story Status Values

Priority Levels

注意：优先级 0 通常表示未设置优先级。

Story Types

Story Stage Values

使用前可先运行 zentao-cli story --help 查看完整选项。

Common Use Cases

1. 查看产品下的所有需求

# 列出产品 1 下的所有需求
zentao-cli story list --product 1

# 只看活跃的需求
zentao-cli story list --product 1 --status active

2. 查看特定需求详情

# 获取需求详情（包含描述、预估工时、阶段等）
zentao-cli story get 123

3. 创建新需求

# 基础创建
zentao-cli story create --title "用户登录功能" --product 1 --pri 1

# 完整创建（带类型和预估工时）
zentao-cli story create --title "用户注册功能" --product 1 --pri 1 --type feature --estimate 8

4. 更新需求状态

# 关闭需求
zentao-cli story update 123 --status closed

# 更新优先级
zentao-cli story update 123 --pri 2

# 变更需求状态并指派
zentao-cli story update 123 --status changed --assigned-to developer-name

5. 按项目筛选需求

# 查看项目 1 下的所有需求
zentao-cli story list --product 1 --project 1

Examples

# 列出产品 1 下的所有需求
zentao-cli story list --product 1

# 只看活跃的需求
zentao-cli story list --product 1 --status active

# 获取需求详情
zentao-cli story get 123

# 创建新需求
zentao-cli story create --title "用户登录功能" --product 1 --pri 1

# 关闭需求
zentao-cli story update 123 --status closed

Output Fields

Gotchas

1. Story ID vs Title：创建需求后返回的是需求 ID（数字），而不是 title，后续操作需要使用 ID。

1. Status Transition：只有符合状态转换规则的状态变更才会被接受：

- draft → active：提交审核 - active → changed/closed：审核动作 - 错误的转换会返回错误

1. Version for Updates：更新需求时建议提供 version 字段以实现乐观锁，避免并发更新冲突。

1. Estimate Unit：--estimate 参数的单位是小时（hours）。

1. Type vs Category：Story 有 type（story type）和隐含的 category（需求类型），两者可能不同，根据实际业务选择。

1. Closed Story Reactivation：已关闭的需求可以通过设置为 active 重新激活。

1. Product Required：创建需求时 --product 参数是必需的，且需求必须归属于某个产品。