@xihe-lab/tapd-cli 2.0.0-rc.1 → 2.0.0-rc.3

package/templates/pm/scope-baseline.yaml

@@ -0,0 +1,93 @@
+# 范围基线冻结（写场景：需求快照写入 TAPD 项目基线）—— 范围管理（软考高项第4版 第9章）
+# 场景: tapd pm scope baseline
+#   [--input '{"iteration_name":"自定义名(缺省取迭代名)"}'] --yes
+# 编排: 拉当前迭代需求快照(id/name/status/priority/label) → expr 摘要（含剔除风险项口径）
+#   → tapd_add_baseline(name=<迭代名>-基线-<今天>, baseline_date=今天(经 expr 计算), description=快照 JSON)
+# 口径: 快照过滤 zzz-delete-me*；度量分母剔除风险项（label 含 risk 或名称以【风险】开头），
+#   但快照本体全量入基线（冻结的是完整范围，风险项也是范围）
+name: scope-baseline
+domain: scope
+title: 范围基线冻结（当前迭代需求快照 → 项目基线，软考第9章）
+write: true
+unwrap: true
+vars:
+  iteration_id: ""
+  iteration_name: ""
+steps:
+  - id: iteration
+    uses: tapd_get_iterations
+    args:
+      id: "${vars.iteration_id}"
+      fields: "id,name,startdate,enddate,status"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  # 快照（只读，波次 1 与 iteration 并发）
+  - id: snapshot
+    uses: tapd_get_stories
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,status,priority,label"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  # 摘要 + 快照单行 JSON（供基线 description 落库）
+  - id: summary
+    expr: >-
+      (() => {
+      const rows = steps.snapshot.data || [];
+      const isRisk = x => String(x.label || '').indexOf('risk') >= 0 || String(x.name || '').indexOf('【风险】') === 0;
+      const scope = rows.filter(x => !isRisk(x));
+      const byStatus = {};
+      rows.forEach(x => {
+      const k = String(x.status || 'unknown');
+      byStatus[k] = (byStatus[k] || 0) + 1;
+      });
+      const statusRows = Object.keys(byStatus).sort().map(k => ({ status: k, count: byStatus[k] }));
+      return {
+      total: rows.length,
+      scopeTotal: scope.length,
+      riskExcluded: rows.length - scope.length,
+      statusLine: statusRows.map(r => r.status + '=' + r.count).join('，') || '（空）',
+      statusRows: statusRows,
+      snapshotJson: JSON.stringify(rows),
+      };
+      })()
+    depends_on: [snapshot]
+
+  # 基线名与基线日期（日期 = 今天，经 expr 计算生成）
+  - id: freeze_meta
+    expr: >-
+      (() => {
+      const it = (steps.iteration.data && steps.iteration.data[0]) || {};
+      const itName = it.name || vars.iteration_name || '未命名迭代';
+      return { itName: itName, name: itName + '-基线-' + today, date: today };
+      })()
+    depends_on: [iteration]
+
+  # 写步骤：冻结基线
+  - id: freeze
+    uses: tapd_add_baseline
+    args:
+      name: "${steps.freeze_meta.data.name}"
+      baseline_date: "${steps.freeze_meta.data.date}"
+      description: "范围基线快照（迭代 ${steps.freeze_meta.data.itName}，共 ${steps.summary.data.total} 项，剔除风险项后 ${steps.summary.data.scopeTotal} 项）｜快照JSON：${steps.summary.data.snapshotJson}"
+    depends_on: [snapshot, summary, freeze_meta]
+
+report:
+  format: markdown
+  template: |
+    # 范围基线已冻结 — ${steps.freeze_meta.data.name}
+
+    - 基线名称: ${steps.freeze_meta.data.name}
+    - 基线日期: ${steps.freeze_meta.data.date}（快照时点，expr 计算）
+    - 覆盖迭代: ${steps.freeze_meta.data.itName}
+    - 快照规模: ${steps.summary.data.total} 项需求（剔除风险项 ${steps.summary.data.riskExcluded} 后，范围口径 ${steps.summary.data.scopeTotal} 项）
+    - 状态分布: ${steps.summary.data.statusLine}
+
+    > 后续用 `tapd pm scope drift-check --input '{"baseline_date":"${steps.freeze_meta.data.date}"}'` 检测范围蔓延。
+
+    ## 需求快照（${steps.summary.data.total} 项）
+
+    | id | 名称 | 状态 | 优先级 |
+    | ---- | ---- | ---- | ---- |
+    ${steps.snapshot.data | rows id,name,status,priority}

package/templates/pm/scope-drift-check.yaml

@@ -0,0 +1,129 @@
+# 范围蔓延检测（纯只读，L0 直接执行）—— 范围管理（软考高项第4版 第9章）
+# 场景: tapd pm scope drift-check
+#   --input '{"baseline_date":"2026-09-01"}' [--iteration <id>]
+# 编排三路只读拉取（并发）:
+#   tapd_get_story_changes(limit=200, created>=基线)   —— 注意: 该工具 schema 不含 created
+#     参数（传了会在静态校验报错且运行期被丢弃），故拉最近 200 条按 created desc 排序后
+#     在 filter 里做 created>=baseline_date 的本地过滤（字符串日期前缀比较成立）
+#   tapd_get_stories(当前迭代)                          —— 新增清单 = created>=基线
+#   tapd_get_removed_stories(limit=200, deleted>=基线)  —— 同理本地过滤 deleted
+# 产出: 新增/字段变更/移除三清单 + 范围口径结论（剔除风险项：label 含 risk 或名称以【风险】开头）
+# 口径: 需求/回收站列表过滤 zzz-delete-me*；比率与清单计数保留分母
+name: scope-drift-check
+domain: scope
+title: 范围蔓延检测（对比基线：新增/字段变更/移除三清单，软考第9章）
+write: false
+unwrap: true
+vars:
+  iteration_id: ""
+  baseline_date: ""
+steps:
+  - id: changes
+    uses: tapd_get_story_changes
+    args:
+      limit: 200
+      order: "created desc"
+      fields: "id,story_id,field,value_before,value_after,author,created"
+    filter: "!vars.baseline_date || String(item.created || '').slice(0, 10) >= vars.baseline_date"
+
+  - id: current
+    uses: tapd_get_stories
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,owner,status,label,created"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: removed
+    uses: tapd_get_removed_stories
+    args:
+      limit: 200
+      fields: "id,name,owner,creator,deleted"
+    filter: "String(item.name || '').startsWith('zzz-delete-me') === false && (!vars.baseline_date || String(item.deleted || '').slice(0, 10) >= vars.baseline_date)"
+
+  - id: drift
+    expr: >-
+      (() => {
+      const cur = steps.current.data || [];
+      const chs = steps.changes.data || [];
+      const rem = steps.removed.data || [];
+      const bd = String(vars.baseline_date || '');
+      const byId = {};
+      cur.forEach(s => { byId[String(s.id)] = s; });
+      const isRisk = s => String(s.label || '').indexOf('risk') >= 0 || String(s.name || '').indexOf('【风险】') === 0;
+      const riskCount = cur.filter(isRisk).length;
+      const addedAll = cur.filter(s => !bd || String(s.created || '').slice(0, 10) >= bd);
+      const addedScope = addedAll.filter(s => !isRisk(s));
+      const addedRows = addedScope.map(s => ({ id: s.id, name: s.name, owner: s.owner, status: s.status, created: String(s.created || '').slice(0, 10) }));
+      if (addedAll.length > addedScope.length) {
+      addedRows.push({ id: '-', name: '（另有 ' + (addedAll.length - addedScope.length) + ' 项风险项新增，未计入范围口径）', owner: '-', status: '-', created: '-' });
+      }
+      if (addedRows.length === 0) {
+      addedRows.push({ id: '-', name: '（基线以来无新增需求）', owner: '-', status: '-', created: '-' });
+      }
+      const changeRows = chs.map(c => ({
+      story_id: c.story_id,
+      story: (byId[String(c.story_id)] || {}).name || '（迭代外/已移除需求）',
+      field: c.field,
+      from: c.value_before,
+      to: c.value_after,
+      author: c.author,
+      created: c.created,
+      }));
+      if (changeRows.length === 0) {
+      changeRows.push({ story_id: '-', story: '（基线以来无字段变更记录）', field: '-', from: '-', to: '-', author: '-', created: '-' });
+      }
+      const changedStories = {};
+      changeRows.forEach(r => { if (r.story_id !== '-') changedStories[String(r.story_id)] = true; });
+      const removedRows = rem.map(r => ({ id: r.id, name: r.name, owner: r.owner, deleted: String(r.deleted || '').slice(0, 10) }));
+      if (removedRows.length === 0) {
+      removedRows.push({ id: '-', name: '（基线以来无移除需求）', owner: '-', deleted: '-' });
+      }
+      const driftTotal = addedScope.length + changeRows.filter(r => r.story_id !== '-').length + rem.length;
+      return {
+      baselineDisplay: bd || '（未提供 baseline_date，按可拉取的全量记录展示）',
+      currentLine: '当前范围 ' + cur.length + ' 项（剔除风险项 ' + riskCount + ' 后，范围口径 ' + (cur.length - riskCount) + ' 项）',
+      addedCount: addedAll.length,
+      addedScopeCount: addedScope.length,
+      changeCount: changeRows.filter(r => r.story_id !== '-').length,
+      changedStoryCount: Object.keys(changedStories).length,
+      removedCount: rem.length,
+      driftTotal: driftTotal,
+      verdict: driftTotal === 0 ? '基线以来无范围变动，范围受控' : '检测到范围活动 ' + driftTotal + ' 处（新增 ' + addedScope.length + ' / 字段变更 ' + changeRows.filter(r => r.story_id !== '-').length + ' / 移除 ' + rem.length + '），请评审是否纳入基线变更',
+      addedRows: addedRows,
+      changeRows: changeRows,
+      removedRows: removedRows,
+      };
+      })()
+    depends_on: [changes, current, removed]
+
+report:
+  format: markdown
+  template: |
+    # 范围蔓延检测报告
+
+    - 对比基线: ${steps.drift.data.baselineDisplay}
+    - 迭代: id=${vars.iteration_id}｜${steps.drift.data.currentLine}
+    - 结论: ${steps.drift.data.verdict}
+
+    ## 一、基线后新增（范围口径 ${steps.drift.data.addedScopeCount}/${steps.drift.data.addedCount}）
+
+    | id | 名称 | 处理人 | 状态 | 创建日期 |
+    | ---- | ---- | ---- | ---- | ---- |
+    ${steps.drift.data.addedRows | rows id,name,owner,status,created}
+
+    ## 二、字段变更（${steps.drift.data.changeCount} 条记录，涉及 ${steps.drift.data.changedStoryCount} 个需求）
+
+    | 需求ID | 需求名 | 字段 | 原值 | 新值 | 变更人 | 时间 |
+    | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
+    ${steps.drift.data.changeRows | rows story_id,story,field,from,to,author,created}
+
+    ## 三、移除（${steps.drift.data.removedCount} 项）
+
+    | id | 名称 | 处理人 | 删除日期 |
+    | ---- | ---- | ---- | ---- |
+    ${steps.drift.data.removedRows | rows id,name,owner,deleted}
+
+    > 口径：新增=当前迭代内 created>=基线 的需求（风险项单列不计入口径）；变更记录取自
+    > story_changes（工具 schema 无 created 参数，按 created desc 拉 200 条后本地过滤）；
+    > 移除=回收站 deleted>=基线；全列表已过滤 zzz-delete-me*。

package/templates/pm/stakeholder-map.yaml

@@ -0,0 +1,121 @@
+# 干系人管理 · 参与矩阵（纯只读，L0 直接执行）
+# 用法: tapd pm stakeholder map [--iteration <id>] [--input '{"skip_users":true}']
+#   等价: tapd pipeline run templates/pm/stakeholder-map.yaml --iteration <id>
+# 数据源: tapd_get_workspace_users + 迭代 stories/tasks（owner/cc/participator 字段）
+# 权限降级: users 接口可能 403（需要 users::_get 权限）——此时执行会在 users 步骤报
+#   STEP_FAILED 并给出 API 错误；带 --input '{"skip_users":true}' 重跑即降级为仅从
+#   存量 owner/cc/participator 字段反推矩阵（无名单零参与分析）。
+#   实现注记: 聚合步骤用 steps['users'] 方括号取数、刻意不建硬依赖——引擎对
+#   「上游非 ok 即连锁跳过」，users 步骤被 where 跳过时若建了依赖会连带跳过聚合，
+#   降级路径就断了。
+# 沉默口径（简化版）: 人员名下存在「未完成且 progress=0 且 due 已过」的任务 → 标沉默；
+#   users 名单可用时另列「零参与名单成员」（在册但未出现在任何参与字段）。
+name: stakeholder-map
+domain: stakeholder
+title: 干系人参与矩阵（人×参与对象数×角色视角；users 接口可能 403（权限），此时报告降级为仅从存量 owner 字段反推）
+write: false
+unwrap: true
+vars:
+  iteration_id: ""
+  skip_users: false
+steps:
+  # ---- 项目成员名单（403 风险步骤；skip_users=true 时跳过走降级）----
+  - id: users
+    uses: tapd_get_workspace_users
+    args: { fields: "user,role_id,email" }
+    where: "!vars.skip_users"
+
+  # ---- 迭代需求（保留风险项：风险 owner 属于必须沟通的干系人）----
+  - id: stories
+    uses: tapd_get_stories
+    args: { iteration_id: "${vars.iteration_id}", fields: "id,name,owner,cc,participator,status", limit: 200 }
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  # ---- 迭代任务（沉默判定数据源）----
+  - id: tasks
+    uses: tapd_get_tasks
+    args: { iteration_id: "${vars.iteration_id}", fields: "id,name,owner,status,progress,due", limit: 200 }
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  # ---- 聚合：人 × 参与对象数 × 角色视角（本地计算）----
+  - id: matrix
+    expr: |-
+      (() => {
+        const names = v => String(v || '').split(/[;；,，|]/).map(s => s.trim()).filter(Boolean);
+        const doneStatus = s => ['done', 'closed', 'complete', 'completed'].includes(String(s || ''));
+        const people = new Map();
+        const touch = (who, kind) => {
+          if (!who) return;
+          const p = people.get(who) || { name: who, story_owner: 0, story_cc: 0, story_partner: 0, task_owner: 0, blocked_tasks: 0, blocked_names: [] };
+          p[kind] += 1;
+          people.set(who, p);
+        };
+        for (const s of steps.stories.data) {
+          for (const w of names(s.owner)) touch(w, 'story_owner');
+          for (const w of names(s.cc)) touch(w, 'story_cc');
+          for (const w of names(s.participator)) touch(w, 'story_partner');
+        }
+        for (const t of steps.tasks.data) {
+          for (const w of names(t.owner)) {
+            touch(w, 'task_owner');
+            const stale = !doneStatus(t.status) && Number(t.progress || 0) === 0 && Boolean(t.due) && String(t.due).slice(0, 10) < today;
+            if (stale) {
+              const p = people.get(w);
+              p.blocked_tasks += 1;
+              p.blocked_names.push(String(t.name || t.id || '(未命名)'));
+            }
+          }
+        }
+        const rows = [...people.values()].map(p => ({
+          name: p.name,
+          story_owner: p.story_owner,
+          story_cc: p.story_cc,
+          story_partner: p.story_partner,
+          task_owner: p.task_owner,
+          blocked_tasks: p.blocked_tasks,
+          blocked_names: p.blocked_names,
+          objects: p.story_owner + p.story_cc + p.story_partner + p.task_owner,
+          silent_label: p.blocked_tasks > 0 ? '是（' + p.blocked_names.join('、') + '）' : ''
+        }));
+        rows.sort((a, b) => b.objects - a.objects || a.name.localeCompare(b.name));
+
+        const rosterRaw = steps['users'] && Array.isArray(steps['users'].data) ? steps['users'].data : [];
+        const roster = [...new Set(rosterRaw.map(u => String((u && (u.user || u.name)) || '').trim()).filter(Boolean))];
+        const involved = new Set(rows.map(r => r.name));
+        const idleMembers = roster.filter(n => !involved.has(n));
+        const silentRows = rows.filter(r => r.blocked_tasks > 0);
+        return {
+          users_loaded: rosterRaw.length > 0,
+          roster_size: rosterRaw.length,
+          people: rows,
+          silent_count: silentRows.length,
+          silent_lines: silentRows.length
+            ? silentRows.map(r => '- ' + r.name + '（停滞任务: ' + r.blocked_names.join('、') + '）').join('\n')
+            : '-（无：迭代内没有「任务 progress=0 且 due 已过」的负责人）',
+          idle_lines: idleMembers.length
+            ? idleMembers.map(n => '- ' + n).join('\n')
+            : '-（无：名单成员均出现在 owner/cc/participator 字段中）',
+          users_note: rosterRaw.length > 0
+            ? '名单接口可用，共 ' + rosterRaw.length + ' 人'
+            : '降级模式：users 未加载（接口可能 403 或已声明 skip_users），本矩阵仅从存量 owner/cc/participator 字段反推，无名单零参与分析'
+        };
+      })()
+    depends_on: [stories, tasks]
+
+report:
+  format: markdown
+  template: |
+    # 干系人参与矩阵
+    - 迭代: ${vars.iteration_id}
+    - 名单: ${steps.matrix.data.users_note}
+    - 计入口径: 出现在迭代需求/任务的 owner、cc、participator 字段即计入；「参与对象数」为四类视角去重前合计
+
+    | 人员 | 需求负责 | 需求关注(cc) | 需求参与 | 任务负责 | 停滞任务 | 参与对象数 | 沉默标记 |
+    |------|---------|-------------|---------|---------|---------|-----------|---------|
+    ${steps.matrix.data.people | rows name,story_owner,story_cc,story_partner,task_owner,blocked_tasks,objects,silent_label}
+
+    ## 沉默干系人（有 owner 任务但 progress=0 且 due 已过）
+    ${steps.matrix.data.silent_lines}
+
+    ## 零参与名单成员（名单在册但未出现在任何参与字段）
+    ${steps.matrix.data.idle_lines}

package/templates/triage-bugs.yaml

@@ -0,0 +1,49 @@
+# 缺陷分诊（含写步骤，默认 dry-run 闸门，--yes 确认落库）
+# 规则分配：按 vars.owners 轮询（round-robin）把未分派缺陷分给候选处理人
+# 用法: tapd pipeline run triage-bugs --input '{"severity":"1","owners":["alice","bob"]}' --yes
+name: triage-bugs
+title: 缺陷分诊（批量查缺陷 → 规则分配 → 评论分诊摘要）
+write: true
+unwrap: true
+vars:
+  severity: ""
+  owners: []
+steps:
+  - id: bugs
+    uses: tapd_get_bugs
+    args:
+      status: new
+      fields: "id,title,severity,current_owner,status"
+
+  - id: triaged
+    expr: "steps.bugs.data.filter(b => (!vars.severity || b.severity === vars.severity) && !b.current_owner)"
+    depends_on: [bugs]
+
+  - id: assignment
+    expr: "(() => { const pick = i => vars.owners[i % Math.max(vars.owners.length, 1)]; return { count: steps.triaged.data.length, plan: steps.triaged.data.map((b, i) => ({ id: b.id, current_owner: pick(i) })), display: steps.triaged.data.map((b, i) => ({ id: b.id, title: b.title, assignee: pick(i) })) }; })()"
+    depends_on: [triaged]
+
+  - id: assign
+    uses: tapd_batch_update_bugs
+    args:
+      bugs: "${steps.assignment.data.plan | json}"
+    where: "steps.assignment.data.count > 0 && vars.owners.length > 0"
+    depends_on: [assignment]
+
+  - id: triage-comment
+    uses: tapd_create_comment
+    args:
+      entry_type: bug
+      entry_id: "${steps.triaged.data.0.id}"
+      description: "【分诊摘要】本轮共分派 ${steps.assignment.data.count} 个缺陷（round-robin → ${vars.owners | json}）"
+    where: "steps.assignment.data.count > 0"
+    depends_on: [assign]
+
+report:
+  format: markdown
+  template: |
+    # 缺陷分诊报告
+    - 候选处理人: ${vars.owners | json}
+    - 查询缺陷: ${steps.bugs.data.length} 个，其中待分诊 ${steps.assignment.data.count} 个
+    - 分派计划:
+    ${steps.assignment.data.display | rows id,title,assignee}