feat: add deliverable, resource, and wbs plan-table commands

Change-Id: Ib84e4678d1f69659bfc376a30c9996d62b9e721c
2026-09-14 20:26:39 +08:00 · 2026-05-20 19:43:11 +08:00
parent 3f5f90c979
commit 152870a46e
10 changed files with 522 additions and 6 deletions
@@ -8,6 +8,14 @@ versioned section on each npm release.

 ## [Unreleased]

+## [v1.0.5] - 2026-05-20
+
+### Added
+
+- New `deliverable` domain exposing the upstream `list_deliverables` MCP tool — `deliverable list` returns deliverables along with their root and source work items
+- New `resource` domain for Meegle's resource-library feature — `resource create` creates a resource template (resource instance) under a resource-library-enabled work item type, `resource meta-fields` lists the resource library configuration (resource fields and roles)
+- New `wbs` domain covering plan-table draft + instance workflows: `wbs list-draft-rows` / `wbs list-instance-rows` filter and project rows, `wbs create-draft` creates a new draft for a work item instance, `wbs edit-draft` applies one atomic operation to a single draft row (add / delete / restore / sort / rename / owner / schedule via `--params`), `wbs publish-draft` publishes a draft online, `wbs reset-draft` discards unpublished changes, `wbs get-draft-progress` polls async-operation progress, `wbs list-element-templates` lists element templates (resource nodes and tasks) from the flow resource library
+
 ## [v1.0.4] - 2026-05-19

 ### Fixed
@@ -13,7 +13,7 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 ## Why Meegle CLI?

 - **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output, `--dry-run` previews, and `--device-code` flows for non-TTY environments
- **Broad Coverage** — 13 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project, attachments) and 40+ commands mapping to Meegle's core capabilities
+- **Broad Coverage** — 16 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project, attachments, deliverables, resource library, WBS plan tables) and 50+ commands mapping to Meegle's core capabilities
 - **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` for complex payloads like `fields[]` — pick the right granularity per call
 - **Flexible Output** — `json` / `table` / `ndjson` / `raw`, with `--select` dot-path projection for piping to other tools
 - **Secure by Default** — OS keychain credential storage, `${VAR}` env-var templating so secrets never land in config files, multi-profile switching for staging / prod
@@ -34,6 +34,9 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 | 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
 | 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
 | 📎 [Attachments](#attachment--attachments)         | Two-stage upload/download protocol — `prepare-*` basic commands plus `+upload` / `+download` end-to-end shortcuts |
+| 📦 [Deliverables](#deliverable--deliverables)      | List deliverables with their root and source work items                                        |
+| 🧩 [Resource Library](#resource--resource-library) | Create resource templates, inspect resource library configuration                              |
+| 🗓️ [WBS Plan Tables](#wbs--wbs-plan-tables)        | List draft / published plan rows, create / edit / publish / reset drafts, query draft progress, list element templates |
 | 🔐 [Auth & Config](#authentication)                | OAuth login, device-code flow, multi-profile config, env-var injection                         |
 | 🔗 [URL Parsing](#url--url-parsing)                | Offline decode of Meegle / Feishu Project URLs into `url_kind` + structured fields             |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
@@ -254,6 +257,32 @@ The agent consults the skill, picks the right `meegle` commands, and runs them f
 | `attachment +upload` | End-to-end upload: preprocess + signed HTTP POST(s); returns the resulting `file_token` and file metadata |
 | `attachment +download` | End-to-end download: preprocess + signed HTTP GET(s) + atomic write — for `file_url`s embedded in `workitem get` / `comment list` responses |

+### deliverable — Deliverables
+
+| Command | Description |
+|---------|-------------|
+| `deliverable list` | List deliverables with their root and source work items |
+
+### resource — Resource Library
+
+| Command | Description |
+|---------|-------------|
+| `resource create` | Create a resource template (resource instance) under a resource-library-enabled work item type |
+| `resource meta-fields` | List resource library configuration (resource fields and roles) |
+
+### wbs — WBS Plan Tables
+
+| Command | Description |
+|---------|-------------|
+| `wbs list-draft-rows` | List rows in a WBS draft, filtered by query and projected to selected fields |
+| `wbs list-instance-rows` | List rows in a published WBS instance, filtered by query and projected to selected fields |
+| `wbs create-draft` | Create a new WBS draft for a work item instance |
+| `wbs edit-draft` | Apply one atomic operation to a single draft row (add / delete / restore / sort / rename / owner / schedule); operation type via `--params` |
+| `wbs publish-draft` | Publish a WBS draft online |
+| `wbs reset-draft` | Reset a draft to match the published instance, discarding unpublished changes |
+| `wbs get-draft-progress` | Get the execution progress of a WBS draft operation (create / edit / publish) |
+| `wbs list-element-templates` | List element templates (resource nodes and tasks) from the flow resource library |
+
 ### auth — Authentication

 | Command | Description |
@@ -13,7 +13,7 @@
 ## 为什么选择 Meegle CLI？

 - **Agent 友好** — 附带一份 [AI Agent Skill](#ai-agent-skill)，一条命令即可把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、`--dry-run` 预览、`--device-code` 无 TTY 流程
- **覆盖完整** — 13 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间、附件），40+ 命令映射到 Meegle 核心能力
+- **覆盖完整** — 16 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间、附件、交付物、资源库、WBS 计划表），50+ 命令映射到 Meegle 核心能力
 - **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
 - **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
 - **默认安全** — 凭证存进系统 keychain、`${VAR}` 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod
@@ -34,6 +34,9 @@
 | 👥 [团队与用户](#team--user--人员域)               | 列出团队、团队成员、搜索用户、查看当前登录身份                                           |
 | 🗂️ [空间](#project--空间域)                        | 按关键词搜索空间                                                                         |
 | 📎 [附件](#attachment--附件域)                     | 两段式上传/下载协议 —— `prepare-*` 基础命令 + `+upload` / `+download` 端到端快捷命令     |
+| 📦 [交付物](#deliverable--交付物域)                | 列出交付物及所属根工作项、来源工作项                                                     |
+| 🧩 [资源库](#resource--资源库)                     | 创建资源模板、查看资源库配置                                                             |
+| 🗓️ [WBS 计划表](#wbs--wbs-计划表)                  | 查询草稿 / 已发布计划行、创建 / 编辑 / 发布 / 重置草稿、查询草稿进度、列流程资源库元素   |
 | 🔐 [认证与配置](#认证)                             | OAuth 登录、Device Code 流程、多 profile 配置、环境变量注入                              |
 | 🔗 [URL 解析](#url--url-解析)                      | 离线解析飞书项目 / Meegle URL，输出 `url_kind` + 结构化字段                              |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用             |
@@ -254,6 +257,32 @@ Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--
 | `attachment +upload` | 端到端上传：预处理 + 签名 HTTP POST，返回 `file_token` 与文件元信息 |
 | `attachment +download` | 端到端下载：预处理 + 签名 HTTP GET + 原子写文件，用于消费 `workitem get` / `comment list` 返回的 `file_url` |

+### deliverable — 交付物域
+
+| 命令 | 说明 |
+|------|------|
+| `deliverable list` | 列出交付物及其根工作项、来源工作项 |
+
+### resource — 资源库
+
+| 命令 | 说明 |
+|------|------|
+| `resource create` | 在启用资源库的工作项类型下创建资源模板（资源实例） |
+| `resource meta-fields` | 查看资源库配置（资源字段、资源角色） |
+
+### wbs — WBS 计划表
+
+| 命令 | 说明 |
+|------|------|
+| `wbs list-draft-rows` | 在计划表草稿中按条件筛选行并返回指定字段 |
+| `wbs list-instance-rows` | 在已发布的线上计划表实例中按条件筛选行并返回指定字段 |
+| `wbs create-draft` | 为指定工作项实例创建新的计划表草稿 |
+| `wbs edit-draft` | 对计划表草稿单行执行一次原子操作（新增 / 删除 / 恢复 / 排序 / 改名 / 改负责人 / 改排期），操作类型通过 `--params` 指定 |
+| `wbs publish-draft` | 将编辑完成的草稿发布到线上 |
+| `wbs reset-draft` | 将草稿重置为线上实例状态，放弃所有未发布的修改 |
+| `wbs get-draft-progress` | 查询计划表草稿操作（创建 / 编辑 / 发布）的执行进度 |
+| `wbs list-element-templates` | 列出流程资源库中的资源节点与资源任务模板 |
+
 ### auth — 认证域

 | 命令 | 说明 |
@@ -71,6 +71,23 @@ var fallbackTable = map[string]fallbackEntry{
 	// attachment (2)
 	"upload_file":      {resource: "attachment", method: "prepare-upload", description: "Preprocess an attachment upload — returns the signed URL + multipart plan"},
 	"get_download_url": {resource: "attachment", method: "prepare-download", description: "Preprocess an attachment download — returns the signed URL + multipart plan"},
+
+	// deliverable (1)
+	"list_deliverables": {resource: "deliverable", method: "list", description: "List deliverables with their root and source work items"},
+
+	// resource — resource library (2)
+	"create_resource_work_item":        {resource: "resource", method: "create", hasFields: true, description: "Create a resource template (resource instance) under a resource-library-enabled work item type"},
+	"get_resource_work_item_type_conf": {resource: "resource", method: "meta-fields", description: "List resource library configuration (resource fields and roles)"},
+
+	// wbs — plan tables (8)
+	"list_wbs_draft_rows":              {resource: "wbs", method: "list-draft-rows", description: "List rows in a WBS draft, filtered by query and projected to selected fields"},
+	"list_wbs_instance_rows":           {resource: "wbs", method: "list-instance-rows", description: "List rows in a published WBS instance, filtered by query and projected to selected fields"},
+	"edit_wbs_draft":                   {resource: "wbs", method: "edit-draft", description: "Apply one atomic operation to a single WBS draft row (add/delete/restore/sort/rename/owner/schedule); operation type via --params"},
+	"create_wbs_draft":                 {resource: "wbs", method: "create-draft", description: "Create a new WBS draft for a work item instance"},
+	"publish_wbs_draft":                {resource: "wbs", method: "publish-draft", description: "Publish a WBS draft online"},
+	"reset_wbs_draft":                  {resource: "wbs", method: "reset-draft", description: "Reset a WBS draft to match the published instance, discarding unpublished changes"},
+	"get_wbs_draft_operation_progress": {resource: "wbs", method: "get-draft-progress", description: "Get the execution progress of a WBS draft operation (create/edit/publish)"},
+	"list_element_template":            {resource: "wbs", method: "list-element-templates", description: "List element templates (resource nodes and tasks) from the flow resource library"},
 }

 func MapTool(tool types.ToolDefinition) types.MappedCommand {
@@ -78,6 +78,20 @@ var fallbackTests = []struct {
 	{"search_project_info", "project", "search"},
 	// user (1)
 	{"search_user_info", "user", "search"},
+	// deliverable (1)
+	{"list_deliverables", "deliverable", "list"},
+	// resource (2)
+	{"create_resource_work_item", "resource", "create"},
+	{"get_resource_work_item_type_conf", "resource", "meta-fields"},
+	// wbs (8)
+	{"list_wbs_draft_rows", "wbs", "list-draft-rows"},
+	{"list_wbs_instance_rows", "wbs", "list-instance-rows"},
+	{"edit_wbs_draft", "wbs", "edit-draft"},
+	{"create_wbs_draft", "wbs", "create-draft"},
+	{"publish_wbs_draft", "wbs", "publish-draft"},
+	{"reset_wbs_draft", "wbs", "reset-draft"},
+	{"get_wbs_draft_operation_progress", "wbs", "get-draft-progress"},
+	{"list_element_template", "wbs", "list-element-templates"},
 }

 func TestFallbackTable(t *testing.T) {
@@ -96,8 +110,8 @@ func TestFallbackTable(t *testing.T) {
 }

 func TestFallbackTableCount(t *testing.T) {
-	if len(fallbackTable) != 37 {
-		t.Errorf("expected 37 fallback entries, got %d", len(fallbackTable))
+	if len(fallbackTable) != 48 {
+		t.Errorf("expected 48 fallback entries, got %d", len(fallbackTable))
 	}
 }

@@ -1,6 +1,6 @@
 {
  "name": "@lark-project/meegle",
-  "version": "1.0.4",
+  "version": "1.0.5",
  "description": "Agent-First CLI for Meegle (Lark Project)",
  "license": "MIT",
  "homepage": "https://github.com/larksuite/meegle-cli#readme",
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+
+# verify-ipd-commands.sh
+#
+# Verifies the 11 IPD MCP commands added by feat/ipd-mcp-cli-commands:
+#   deliverable list
+#   resource create / meta-fields
+#   wbs list-draft-rows / list-instance-rows / create-draft / edit-draft
+#       / publish-draft / reset-draft / get-draft-progress
+#       / list-element-templates
+#
+# Three phases (no backend mutation):
+#   1. availability — `<cmd> --help` exits 0 (proves dynamic-discovery + mapper wired)
+#   2. schema       — `meegle inspect <res>.<sub>` prints required/optional params
+#   3. dry-run      — `<cmd> --dry-run` returns the normalized backend payload
+#                     so the caller can eyeball it against the MCP tool's input
+#                     schema (printed in the same block).
+#
+# Pure smoke test. End-to-end CLI-vs-MCP structural comparison lives in
+# `test/crosstest/ipd_test.go` (requires real auth + project access).
+
+set -euo pipefail
+
+ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." &>/dev/null && pwd -P)"
+cd "$ROOT"
+
+BIN="${BIN:-./dist/meegle}"
+PROJECT_KEY="${PROJECT_KEY:-664474a4fac0ad797f358562}"   # crosstest default project
+WORK_ITEM_TYPE="${WORK_ITEM_TYPE:-story}"
+WORK_ITEM_ID_DEFAULT="${WBS_TEST_WORK_ITEM_ID:-0000000000}"
+
+# Build only if missing — fast no-op on repeat runs.
+if [ ! -x "$BIN" ]; then
+    echo "==> Building $BIN"
+    make build >/dev/null
+fi
+
+# Each row:  <resource> <sub> | <MCP tool>            | <dry-run-args>
+#
+# Mutating commands omit a dry-run args column so they only get availability +
+# schema checks (we never want to accidentally create / publish / reset against
+# a real workitem from a smoke test). Use `--params @file.json` manually when
+# you need to send real payloads.
+SPEC=$(cat <<EOF
+deliverable list                 | list_deliverables                | --project-key=$PROJECT_KEY
+resource create                  | create_resource_work_item        |
+resource meta-fields             | get_resource_work_item_type_conf | --project-key=$PROJECT_KEY --work-item-type-key=$WORK_ITEM_TYPE
+wbs list-draft-rows              | list_wbs_draft_rows              | --project-key=$PROJECT_KEY --work-item-id=$WORK_ITEM_ID_DEFAULT
+wbs list-instance-rows           | list_wbs_instance_rows           | --project-key=$PROJECT_KEY --work-item-id=$WORK_ITEM_ID_DEFAULT
+wbs create-draft                 | create_wbs_draft                 |
+wbs edit-draft                   | edit_wbs_draft                   |
+wbs publish-draft                | publish_wbs_draft                |
+wbs reset-draft                  | reset_wbs_draft                  |
+wbs get-draft-progress           | get_wbs_draft_operation_progress |
+wbs list-element-templates       | list_element_template            | --project-key=$PROJECT_KEY --work-item-type=$WORK_ITEM_TYPE --element-type=node
+EOF
+)
+
+# Pretty printer.
+hr() { printf '%.0s─' {1..80}; echo; }
+# Trim leading + trailing whitespace from $1.
+trim() { local s="$1"; s="${s#"${s%%[![:space:]]*}"}"; s="${s%"${s##*[![:space:]]}"}"; printf '%s' "$s"; }
+ok=0; fail=0; skipped_dry=0
+declare -a failures=()
+
+phase1_availability() {
+    echo "Phase 1 — availability (--help exits 0, proves dynamic discovery + mapper)"
+    hr
+    while IFS='|' read -r cmd _ _; do
+        cmd="$(trim "$cmd")"
+        if "$BIN" $cmd --help >/dev/null 2>&1; then
+            printf "  ✓ %-32s\n" "$cmd"
+            ok=$((ok+1))
+        else
+            printf "  ✗ %-32s [help FAIL]\n" "$cmd"
+            fail=$((fail+1))
+            failures+=("availability: $cmd")
+        fi
+    done <<< "$SPEC"
+    echo
+}
+
+phase2_schema() {
+    echo "Phase 2 — schema introspection (CLI flags + MCP tool name)"
+    hr
+    while IFS='|' read -r cmd mcp _; do
+        cmd="$(trim "$cmd")"
+        mcp="$(trim "$mcp")"
+        res="${cmd%% *}"
+        sub="${cmd#* }"
+        echo "  [$cmd]   →   MCP tool: $mcp"
+        if ! "$BIN" inspect "${res}.${sub}" 2>&1 | sed 's/^/    /'; then
+            failures+=("schema: $cmd")
+            fail=$((fail+1))
+        fi
+        echo
+    done <<< "$SPEC"
+}
+
+phase3_dryrun() {
+    echo "Phase 3 — dry-run payload (only for commands with safe read-only defaults)"
+    hr
+    while IFS='|' read -r cmd mcp args; do
+        cmd="$(trim "$cmd")"
+        mcp="$(trim "$mcp")"
+        args="$(trim "$args")"
+        if [ -z "$args" ]; then
+            printf "  ⊘ %-32s [skipped: mutating or needs WBS-enabled workitem]\n" "$cmd"
+            skipped_dry=$((skipped_dry+1))
+            continue
+        fi
+        if out=$("$BIN" $cmd $args --dry-run --format json 2>&1); then
+            printf "  ✓ %-32s [dry-run OK]\n" "$cmd"
+            # Show the request shape — what would be sent to MCP tool $mcp.
+            echo "$out" | sed 's/^/      /' | head -20
+            ok=$((ok+1))
+        else
+            printf "  ✗ %-32s [dry-run FAIL]\n" "$cmd"
+            echo "$out" | sed 's/^/      /' | head -10
+            fail=$((fail+1))
+            failures+=("dry-run: $cmd")
+        fi
+        echo
+    done <<< "$SPEC"
+}
+
+phase1_availability
+phase2_schema
+phase3_dryrun
+
+echo
+hr
+echo "Summary"
+echo "  ok       : $ok"
+echo "  failed   : $fail"
+echo "  dry-skip : $skipped_dry  (mutating / needs WBS-enabled workitem)"
+if [ "$fail" -gt 0 ]; then
+    echo
+    echo "Failures:"
+    printf '  - %s\n' "${failures[@]}"
+    echo
+    echo "For end-to-end CLI-vs-MCP structural comparison run:"
+    echo "  go test -tags=crosstest ./test/crosstest/ -run TestIPDCrossTest -v"
+    exit 1
+fi
+
+echo
+echo "All ${ok} checks passed."
+echo
+echo "Next: run the structural-compare crosstest against a live MCP server:"
+echo "  go test -tags=crosstest ./test/crosstest/ -run TestIPDCrossTest -v"
@@ -235,6 +235,44 @@ description: |

 ---

+## Deliverable 交付物域
+
+> 单命令小域，参数表见 [references/misc.md](references/misc.md)。
+
+### deliverable list
+查看交付物详情及其根工作项 / 来源工作项。可按工作项 ID 列表过滤。
+
+---
+
+## Resource 资源库
+
+> 资源库（资源模板）管理。`resource create` 创建资源实例；查看资源库的字段 / 角色配置用 `resource meta-fields`。详细参数表见 [references/misc.md](references/misc.md)。
+
+### resource create
+在已启用资源库的工作项类型下创建资源模板（资源实例）。创建前先调 `resource meta-fields` 取字段 / 角色配置。
+
+---
+
+## WBS 计划表
+
+> 计划表（WBS）有 **草稿（draft）** 与 **已发布实例（instance）** 两套数据模型。常见编辑流程：`create-draft` → 多次 `edit-draft` → `publish-draft`；放弃改动用 `reset-draft`。详细参数表与 `edit-draft` 的 operation 子类型见 [references/wbs.md](references/wbs.md)。
+
+### wbs list-draft-rows
+在计划表草稿中按条件筛选行。常用筛选字段：`wbs_name`、`wbs_parent_id`、`wbs_owner_in_charge`、`wbs_states_doing`。详见 [references/wbs.md](references/wbs.md)。
+
+### wbs list-instance-rows
+在已发布的线上计划表实例中按条件筛选行。参数同 `wbs list-draft-rows`。
+
+### wbs edit-draft
+对计划表草稿单行执行一次原子操作。操作类型（新增 / 删除 / 恢复 / 排序 / 改名 / 改负责人 / 改排期）通过 `operation` 参数指定，结构见 [references/wbs.md](references/wbs.md)。
+> ⚠️ **前置**：草稿不存在时先调 `wbs create-draft`，再 `edit-draft`。判断方法：直接 `wbs list-draft-rows` 报"草稿不存在"类错误即视为缺失草稿。
+
+### wbs publish-draft
+将编辑完成的草稿发布到线上。
+> ⚠️ 全量发布前必须用**固定话术**二次确认："本人及协同者的全部编辑内容均会被发布，请确认是否全量发布？"；部分发布（传入 `uuid_strings_list`）无需二次确认。
+
+---
+
 ## 其它低频域

 度量图表、子任务、关系定义查询的命令参数表见 [references/misc.md](references/misc.md)：
@@ -242,6 +280,7 @@ description: |
 - **Chart 度量域** — `chart get` / `chart list`
 - **SubTask 子任务域** — `subtask update`（create/update/confirm/rollback）
 - **Relation 关系域** — `relation list` / `relation meta-definitions`
+- **WBS 计划表 · 辅助命令** — `wbs create-draft` / `wbs reset-draft` / `wbs get-draft-progress` / `wbs list-element-templates`（见 [references/wbs.md](references/wbs.md)）

 ---

@@ -1,6 +1,6 @@
 # 其它低频命令

-低频/单命令小域的参数表汇总。涵盖团队、图表、子任务、关系、评论查询、工时记录。
+低频/单命令小域的参数表汇总。涵盖团队、图表、子任务、关系、评论查询、工时记录、交付物、资源库、WBS 辅助命令。

 ---

@@ -101,3 +101,82 @@
 | --project-key | string | 是 | 空间 key |
 | --work-item-type | string | 是 | 工作项类型 |
 | --work-item-id | string | 是 | 工作项 ID |
+
+---
+
+## 交付物
+
+### deliverable list
+查看交付物详情及其所属根工作项 / 来源工作项。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --project-key | string | 是 | 空间 key |
+| --work-item-ids | string[] | 否 | 工作项 ID 列表；URL 自动解析；提供名称需先调 `workitem get` 拿 ID |
+
+---
+
+## 资源库
+
+### resource create
+在已启用资源库的工作项类型下创建资源模板（资源实例）。先调 `resource meta-fields` 取字段 / 角色配置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --project-key | string | 是 | 空间 key |
+| --work-item-type-key | string | 是 | 工作项类型 key 或名称；失败时先调 `workitem meta-types` |
+| --fields | object[] | 否 | 资源字段列表，每项含字段 key 与字段值 |
+| --roles | object[] | 否 | 角色人员；为空则不指定 |
+| --template-id | string | 否 | 工作流模板 ID 或名称；未传则取该工作项类型的第一个流程模板 |
+
+### resource meta-fields
+查看资源库的字段 / 角色配置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --project-key | string | 是 | 空间 key |
+| --work-item-type-key | string | 是 | 工作项类型 key 或名称 |
+
+---
+
+## WBS 辅助命令
+
+> 计划表（WBS）的核心查询 / 编辑 / 发布命令见 [wbs.md](wbs.md)。本节仅收 4 个辅助命令：草稿生命周期管理（create-draft / reset-draft）、异步操作进度查询（get-draft-progress）、流程资源库元素查询（list-element-templates）。
+
+### wbs create-draft
+为指定工作项实例创建新的计划表草稿。当需要编辑计划表但当前不存在草稿时，先调本工具创建草稿，再配合 `wbs edit-draft` 进行编辑。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --work-item-id | string | 是 | 工作项 ID，单值；URL 自动解析 |
+| --project-key | string | 是 | 空间 key |
+
+### wbs reset-draft
+将草稿重置为线上实例状态，**放弃所有未发布的修改**。不传 `uuids` 时全量重置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --work-item-id | string | 是 | 工作项 ID |
+| --project-key | string | 是 | 空间 key |
+| --uuids | string[] | 否 | 要重置的行 uuid 列表；为空则全量重置 |
+
+### wbs get-draft-progress
+查询计划表草稿异步操作（create / edit / publish / reset）的执行进度。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --project-key | string | 是 | 空间 key |
+| --work-item-id | string | 是 | 工作项 ID 或名称 |
+| --op-type | string | 是 | 操作类型：`create` / `edit` / `publish` / `reset` |
+| --operation-id | string | 是 | 操作 ID（由 create-draft / edit-draft / publish-draft / reset-draft 返回） |
+
+### wbs list-element-templates
+列出流程资源库中的资源节点（node）或资源任务（task）模板。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --element-type | string | 是 | 资源库类型：`node` 或 `task` |
+| --project-key | string | 是 | 空间 key |
+| --work-item-type | string | 是 | 工作项类型 key 或名称 |
+| --page-size | number | 否 | 页大小 |
+| --page-no | number | 否 | 页码 |
@@ -0,0 +1,148 @@
+# WBS 计划表
+
+计划表（Work Breakdown Structure）有两套数据模型：
+
+- **草稿（draft）** — 当前用户的可编辑副本。`wbs create-draft` 创建、`wbs edit-draft` 单行原子编辑、`wbs publish-draft` 发布、`wbs reset-draft` 放弃修改。
+- **实例（instance）** — 已发布的线上版本。只读，用 `wbs list-instance-rows` 查询。
+
+**常见流程**：`create-draft` → 多次 `edit-draft` → `publish-draft`。
+
+**辅助命令**（创建草稿 / 重置 / 进度 / 模板）请见 [misc.md](misc.md)。
+
+---
+
+## 共用查询能力（draft / instance）
+
+`wbs list-draft-rows` 与 `wbs list-instance-rows` 参数完全一致，仅查询的数据集不同——前者查当前用户的草稿，后者查线上实例。**禁止混用**：例如先用 `list-draft-rows` 取行 uuid，后续递归 / 编辑也必须继续用草稿系列命令。
+
+### condition_query 支持字段
+
+筛选行用 `condition_query`（object）。**仅支持以下字段**：
+
+| 字段 | 含义 | 取值 |
+|------|------|------|
+| `wbs_name` | 行名称 / 任务名称 / 排期项名称 / 子项名称 | string |
+| `wbs_parent_id` | 父级 uuid（用于查子级 / 下级 / 子任务 / 子项） | uuid |
+| `wbs_belong_status` | 所属状态 / 阶段（计划 / 开发 / 验证 / 发布等） | string |
+| `wbs_states_doing` | 当前状态 / 任务状态 | `not_started` / `doing` / `finished` |
+| `wbs_role` | 角色（可多人） | string |
+| `wbs_owner_in_charge` | 负责人 / 责任人（可多人） | userkey；查"我负责的"先调 `user search` 取 userkey |
+| `wbs_delay_label` | 延期标识 | `delay` / `normal` |
+| `wbs_milestone_node_type` | 节点类型 | `milestone` / `normal_node` / `key_path_node` |
+| `wbs_deletable` | 允许删除节点 | bool |
+
+**递归查子级 SOP**：用户提到"子级 / 所有子 / 下级"时，先按条件筛出目标行取 `uuid`，再用 `wbs_parent_id` + `In` 查直接子级（多个 uuid 逗号分隔），再以下一层 uuid 继续递归直到无子级。**全流程必须使用同一工具**（草稿就一直草稿，实例就一直实例）。
+
+### row_field_list 返回字段控制
+
+`row_field_list`（string[]）按需指定返回字段。为空时默认返回 `base.*` + `meta.uuid`；`["_all"]` 返回全量字段。
+
+| 通配符 | 包含字段 |
+|--------|----------|
+| `meta.*` | `uuid`、`parent_id`、所属工作项信息等 |
+| `base.*` | `name`（行名）、`owners`（负责人）、`start_time` / `end_time`（实际开始 / 完成时间）、`schedule`（排期）、`schedule_dependency`（排期依赖）、`union_deliveries`（交付物）、`process_status`（当前状态） |
+| `node_extra.*` | 普通节点扩展：里程碑、所属状态、节点唯一 id `state_key`、前序节点等 |
+| `sub_instance_extra.*` | 子实例扩展：拆解模式 `dismantle_mode` |
+
+**查工作项字段 / 节点字段**：先用 `workitem meta-fields` 判断是否为工作项字段、用 `workflow meta-node-fields` 判断是否为节点字段；再从计划表行中取对应 `workitem_id` / `state_key`，基于这些 ID 继续查字段值。
+
+### wbs list-draft-rows
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --work-item-id | string | 是 | 工作项 ID（**字符串**）；URL 自动解析；名称需先调 `workitem get` |
+| --project-key | string | 是 | 空间 key |
+| --condition-query | object | 否 | 筛选条件，仅支持上表字段 |
+| --need-structure | boolean | 否 | 是否返回树状层级。默认 `false`；查 / 编辑子级时设为 `true` |
+| --page-no | number | 否 | 页号，从 1 开始；返回 `has_more` 时需翻页 |
+| --page-size | number | 否 | 页大小，1–50，默认 25。超过 1000 行需分页合并 |
+| --row-field-list | string[] | 否 | 见上表 |
+
+### wbs list-instance-rows
+
+参数与 `wbs list-draft-rows` 完全一致，仅查询数据集不同（线上已发布实例）。
+
+---
+
+## wbs edit-draft
+
+对计划表草稿单行执行**一次原子操作**。操作类型通过 `operation`（object）参数指定。一次调用只能执行一种操作类型；批量编辑请循环调用。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --work-item-id | string | 是 | 工作项 ID |
+| --project-key | string | 是 | 空间 key |
+| --operation | object | 是 | 操作对象，结构因操作类型而异 |
+
+### operation 结构
+
+`operation` 是一个对象，统一形如：
+
+```json
+{
+  "operation_type": "<动作 PascalCase>",
+  "operation_value": {
+    "<动作 snake_case>": { /* 动作特定字段 */ }
+  }
+}
+```
+
+常见操作类型（按动作分类）：
+
+| 动作 | operation_type | operation_value 子 key | 用途 |
+|------|----------------|------------------------|------|
+| 新增 | `AddTaskRow` | `add_task_row` | 在指定父行下新增一行任务 |
+| 删除 | （delete）| —— | 删除一行（及其子级） |
+| 恢复 | （restore）| —— | 撤销删除 |
+| 排序 | （sort）| —— | 调整行在同级中的位置 |
+| 改名 | （rename）| —— | 修改 `name` |
+| 改负责人 | （owner）| —— | 修改 `owners` |
+| 改排期 | （schedule）| —— | 修改 `schedule` 或 `start_time` / `end_time` |
+
+> 上表只有 `AddTaskRow` 一行的字段名是经验证的。其余动作的 `operation_type` 字符串和 `operation_value` 子 key 未公开 schema，使用前请先在测试环境跑一遍取得真实结构，或向 IPD 后端确认；遇到 4xx 报错时优先怀疑这两个名字。
+
+**示例：在 `parent_uuid` 下新增一行任务**
+
+```json
+{
+  "operation_type": "AddTaskRow",
+  "operation_value": {
+    "add_task_row": {
+      "parent_uuid": "<上级行 uuid，来自 list-draft-rows>",
+      "name": "新任务名"
+    }
+  }
+}
+```
+
+调用后响应里 `change_uuids[0]` 是新行的 uuid，可直接拿去做下一步 `edit-draft`（如改排期）或 `publish-draft` 的部分发布。
+
+**建议工作流**：
+1. `wbs list-draft-rows` 取目标行 / 父行的 `uuid` 与当前字段值
+2. 调 `wbs edit-draft` 一次执行一种操作
+3. 如调用返回了 `operation_id`，先用 `wbs get-draft-progress` 轮询完成再进行下一次编辑——多个 `edit-draft` 并发或不等异步完成就连发可能丢操作
+4. 全部改完用 `wbs publish-draft` 发布
+
+---
+
+## wbs publish-draft
+
+将编辑完成的草稿发布到线上。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| --project-key | string | 是 | 空间 key |
+| --work-item-id | string | 是 | 工作项 ID |
+| --uuid-strings-list | string[] | 否 | 要发布的行 uuid 列表。**部分发布**：传 uuid 列表，无需二次确认。**全量发布**：不传此字段（或传 `["_all"]`），必须先用以下**固定话术**二次确认，用户同意后才执行 |
+
+### 全量发布二次确认（固定话术）
+
+> 本人及协同者的全部编辑内容均会被发布，请确认是否全量发布？
+
+部分发布（传入 `uuid_strings_list`）**不需要**二次确认，直接执行。
+
+---
+
+## 异步操作进度
+
+`wbs create-draft` / `wbs edit-draft` / `wbs publish-draft` / `wbs reset-draft` 返回 `operation_id` 后，需用 `wbs get-draft-progress` 轮询进度。参数表见 [misc.md](misc.md#wbs-辅助命令)。