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

package/templates/pm/README.md

@@ -0,0 +1,57 @@
+# templates/pm/ — pm 管理语义层场景模板目录
+
+本目录随包发布，存放 `tapd pm <domain> <scenario>` 场景的 pipeline 模板。
+S2 只交付框架（命令组 / 发现 / 别名 / 写闸门），**域场景模板由 S3-S6 各波次落盘到本目录**，
+框架侧零注册代码：yaml 文件放进来即被 `tapd pm --help` 分组、`tapd pm list` 与别名执行收录。
+
+## 文件命名约定（硬约束）
+
+```
+<domain>-<scenario>.yaml      例：risk-scan.yaml、scope-drift-check.yaml
+```
+
+- `<domain>` 必须是域表八键之一（小写）：
+  `integration | scope | schedule | cost | quality | communication | risk | stakeholder`
+  （对应软考高项第4版 第8/9/10/11/12/14/15/17 章；采购第16章、绩效第18章不设域，见设计文档 §2）
+- `<scenario>` 为场景 slug，允许连字符（如 `drift-check`）；别名解析按**首个 `-`** 拆分，因此域键不能含 `-`
+- 扩展名支持 `.yaml` / `.yml` / `.json`
+
+## frontmatter 字段
+
+```yaml
+name: risk-scan                  # 模板名，约定与文件名 stem 一致
+domain: risk                     # pm 层扩展字段：域键（执行前由 pm 层剥离，S1 严格 schema 不认识它）
+title: 风险扫描（软考第15章）       # help/list 展示
+write: false                     # 写闸门依据：含写步骤必须 true（S1 validate 强制）
+vars:                            # 变量缺省值，可被 pm flags 覆盖
+  iteration_id: ""
+steps: []                        # 与 S1 pipeline 模板完全同构（uses/expr/args/where/filter/depends_on）
+report: {}                       # format: markdown|text|json + template 插值
+```
+
+除 `domain` 外的全部字段与 `tapd pipeline` 模板 schema 一致（见 `src/pipeline/template.ts`）。
+
+## 可用 vars 与注入
+
+| 变量 | 来源 | 说明 |
+|------|------|------|
+| `${vars.iteration_id}` | `--iteration <id>`；缺省时 pm 自动探测：`tapd_get_iterations status=open`，过滤 `zzz-delete-me*`，按 startdate 取最新 | 迭代作用域，缺省注入到 vars |
+| workspace_id | 经 `defaultArgs` 兜底注入每个工具步骤（全局 `--workspace-id`），步骤 args 显式声明优先 | 无需在模板里写 |
+
+## 数据口径（模板内置，代码化的 skill 前置检查）
+
+- 迭代/需求/缺陷类步骤加 `filter: "!item.name.startsWith('zzz-delete-me')"`（缺陷用 title）
+- 比率类输出保留分母，不因过滤误导
+
+## 用户覆盖
+
+同名文件放 `~/.tapd/templates/pm/`（或 `TAPD_USER_TEMPLATES_DIR` 指定的根目录下的 `pm/`）即覆盖内置同名场景；
+`tapd pm list` 的 `source` 列标记来源。
+
+## 落盘自检
+
+```bash
+tapd pm list                       # 新场景应出现在清单
+tapd pm <domain> <scenario> --dry-run   # 计划预览 + 写闸门
+tapd pipeline validate <file>      # S1 静态校验（注意：含 domain 字段时请用 tapd pm 执行）
+```

package/templates/pm/communication-notify.yaml

@@ -0,0 +1,65 @@
+# 沟通管理 · 变更通知（含写步骤：tapd_create_comment，默认写闸门拦截，--yes 确认落库）
+# 用法: tapd pm communication notify --input '{"entry_type":"stories","entry_id":"1140...","message":"...","cc":"alice|bob"}' [--yes]
+#   等价: tapd pipeline run templates/pm/communication-notify.yaml --input '...' --yes
+# 措辞纪律: message 为纯文本时自动包一层 <p>（已含 HTML 标签则原样透传）；
+#   **措辞必须人审后 --yes 落库**——无 --yes 时仅输出将创建的评论预览，不触 API。
+# 富媒体（rc.2）: message 文本里可直接写 @昵称——服务端智能识别并触发通知（R4）；
+#   如需 at-who 角标/附件锚点/图片，先用 tapd_md_to_html 预转换（@昵称→at-who、
+#   [📎 名称](attach:<ws>/<id>)→附件锚点、--upload-images 顺带上传本地图片），
+#   再把得到的 HTML 整段作为 message 传入（已含 HTML 标签则本模板原样透传，不二次包裹）。
+#   关键通知场景建议同时填 cc（@ 校验/通知不依赖本地成员名单）。
+name: communication-notify
+domain: communication
+title: 变更通知（需求/缺陷/任务上留言并抄送；措辞必须人审后 --yes）
+write: true
+unwrap: true
+vars:
+  entry_type: "stories"
+  entry_id: ""
+  message: ""
+  cc: ""
+steps:
+  # ---- 本地整理：entry_type 归一化 + 纯文本包 <p>（不触 API、永不判写）----
+  - id: prep
+    expr: |-
+      (() => {
+        const raw = String(vars.message || '');
+        const isHtml = /^\s*<[a-z][a-z0-9]*\b/i.test(raw);
+        const alias = { story: 'stories', stories: 'stories', task: 'tasks', tasks: 'tasks', bug: 'bug', bug_remark: 'bug_remark' };
+        const type = alias[String(vars.entry_type || '').trim().toLowerCase()] || String(vars.entry_type || '').trim();
+        const cc = String(vars.cc || '').trim();
+        return {
+          ready: raw.trim() !== '' && String(vars.entry_id || '').trim() !== '',
+          entry_type: type,
+          entry_id: String(vars.entry_id || '').trim(),
+          description: isHtml ? raw : '<p>' + raw.trim() + '</p>',
+          cc: cc,
+          wrapped_label: isHtml ? '原文已是 HTML，未二次包裹' : '纯文本，已包 <p> 标签',
+          cc_label: cc || '（无）',
+          ready_label: raw.trim() !== '' && String(vars.entry_id || '').trim() !== '' ? '就绪' : '跳过（entry_id/message 为空）'
+        };
+      })()
+
+  # ---- 写步骤：创建评论 + 抄送（写闸门，--yes 后才执行）----
+  - id: comment
+    uses: tapd_create_comment
+    args:
+      entry_type: "${steps.prep.data.entry_type}"
+      entry_id: "${steps.prep.data.entry_id}"
+      description: "${steps.prep.data.description}"
+      cc: "${steps.prep.data.cc}"
+    where: "steps.prep.data.ready"
+    depends_on: [prep]
+
+report:
+  format: markdown
+  template: |
+    # 变更通知回执
+    - 对象: ${steps.prep.data.entry_type} #${steps.prep.data.entry_id}
+    - 状态: ${steps.prep.data.ready_label}（写操作，措辞必须人审后 --yes 才落库）
+    - 措辞处理: ${steps.prep.data.wrapped_label}
+    - 抄送: ${steps.prep.data.cc_label}
+    - 评论 ID: ${steps.comment.data.id}
+
+    ## 评论正文（预览与落库内容一致）
+    ${steps.prep.data.description}

package/templates/pm/communication-weekly.yaml

@@ -0,0 +1,160 @@
+# 沟通管理 · 迭代周报数据稿（纯只读，L0 直接执行）
+# 用法: tapd pm communication weekly [--iteration <id>]
+#   等价: tapd pipeline run templates/pm/communication-weekly.yaml --iteration <id>
+# 多源聚合: 迭代 stories（状态分布 + 本周新增/关闭，近 7 天 changes 近似核对）
+#           + bugs 开闭 + tasks 进度 + timesheets 工时消耗 → markdown 数据稿到 stdout。
+# 人工补充「主观补充」段后，可选 tapd wiki create 落库（本模板不写任何对象）。
+name: communication-weekly
+domain: communication
+title: 迭代周报数据稿（多源聚合到 stdout，人工补充后可选 wiki 落库）
+write: false
+unwrap: true
+vars:
+  iteration_id: ""
+steps:
+  # ---- 迭代元信息 ----
+  - id: iteration
+    uses: tapd_get_iterations
+    args: { id: "${vars.iteration_id}", fields: "id,name,startdate,enddate,status" }
+
+  # ---- 统计窗口（近 7 天，本地计算不触 API）----
+  - id: window
+    expr: |-
+      (() => {
+        const weekStart = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 10);
+        return { today: today, week_start: weekStart };
+      })()
+
+  # ---- 需求（zzz 脏数据剔除 + 风险项剔除：label 含 risk 或名称以【风险】开头）----
+  - id: stories
+    uses: tapd_get_stories
+    args: { iteration_id: "${vars.iteration_id}", fields: "id,name,owner,status,priority_label,created,completed,label", limit: 200 }
+    filter: "!item.name.startsWith('zzz-delete-me') && !(String(item.label || '').includes('risk') || String(item.name).startsWith('【风险】'))"
+
+  # ---- 需求变更（workspace 级采样，仅用于「本周活跃需求」近似核对）----
+  - id: story_changes
+    uses: tapd_get_story_changes
+    args: { limit: 200, fields: "story_id,created,author" }
+    filter: "String(item.created || '').slice(0, 10) >= steps.window.data.week_start"
+    depends_on: [window]
+
+  # ---- 缺陷（开闭口径）----
+  - id: bugs
+    uses: tapd_get_bugs
+    args: { iteration_id: "${vars.iteration_id}", fields: "id,title,severity,current_owner,status,created,closed", limit: 200 }
+    filter: "!item.title.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')"
+
+  # ---- 工时（近 7 天，spentdate 时间查询；工时不分实体类型，与迭代弱耦合按窗口口径统计）----
+  - id: timesheets
+    uses: tapd_get_timesheets
+    args: { spentdate: ">= ${steps.window.data.week_start}", fields: "owner,spentdate,timespent,entity_type,entity_id", limit: 200 }
+    depends_on: [window]
+
+  # ---- 汇总（本地计算；一切比率保留分母）----
+  - id: weekly
+    expr: |-
+      (() => {
+        const day = v => String(v || '').slice(0, 10);
+        const doneStatus = s => ['done', 'closed', 'complete', 'completed'].includes(String(s || ''));
+        const ws = steps.window.data.week_start;
+        const byKey = (rows, key) => {
+          const out = {};
+          for (const r of rows) { const k = String(r[key] || '(未设置)'); out[k] = (out[k] || 0) + 1; }
+          return out;
+        };
+        const sd = steps.stories.data;
+        const doneStories = sd.filter(s => doneStatus(s.status)).length;
+        const changedIds = [...new Set(steps.story_changes.data.map(c => String(c.story_id || '')).filter(Boolean))];
+        const bd = steps.bugs.data;
+        const openBugs = bd.filter(b => !['closed', 'resolved', 'rejected'].includes(String(b.status || ''))).length;
+        const td = steps.tasks.data;
+        const doneTasks = td.filter(t => doneStatus(t.status)).length;
+        const perPerson = {};
+        for (const r of steps.timesheets.data) {
+          const who = String(r.owner || '(未设置)');
+          const e = perPerson[who] || (perPerson[who] = { owner: who, hours: 0, records: 0 });
+          e.hours += Number(r.timespent || 0);
+          e.records += 1;
+        }
+        const rows = Object.values(perPerson).sort((a, b) => b.hours - a.hours);
+        const totalHours = Math.round(rows.reduce((a, r) => a + r.hours, 0) * 100) / 100;
+        return {
+          iteration: (steps.iteration.data && steps.iteration.data[0]) || {},
+          window: steps.window.data,
+          stories: {
+            total: sd.length,
+            done: doneStories,
+            ratio: doneStories + '/' + sd.length,
+            by_status: byKey(sd, 'status'),
+            new_this_week: sd.filter(s => day(s.created) >= ws).length,
+            closed_this_week: sd.filter(s => s.completed && day(s.completed) >= ws).length,
+            changed_this_week: changedIds.length
+          },
+          bugs: {
+            total: bd.length,
+            open: openBugs,
+            ratio: (bd.length - openBugs) + '/' + bd.length,
+            new_this_week: bd.filter(b => day(b.created) >= ws).length,
+            closed_this_week: bd.filter(b => b.closed && day(b.closed) >= ws).length,
+            by_severity: byKey(bd, 'severity')
+          },
+          tasks: {
+            total: td.length,
+            done: doneTasks,
+            ratio: doneTasks + '/' + td.length,
+            not_started: td.filter(t => !doneStatus(t.status) && Number(t.progress || 0) === 0).length,
+            overdue: td.filter(t => !doneStatus(t.status) && t.due && day(t.due) < today).length,
+            avg_progress: td.length ? Math.round(td.reduce((a, t) => a + Number(t.progress || 0), 0) / td.length) : 0
+          },
+          timesheets: { hours: totalHours, people: rows.length, rows: rows }
+        };
+      })()
+    depends_on: [iteration, window, stories, story_changes, bugs, tasks, timesheets]
+
+report:
+  format: markdown
+  template: |
+    # 迭代周报（数据稿）
+    > 本稿由 `tapd pm communication weekly` 只读聚合生成，为**数据稿，人工补充后可选 wiki 落库**（如 `tapd wiki create`）。
+
+    - 迭代: ${steps.weekly.data.iteration.name}（${steps.weekly.data.iteration.startdate} ~ ${steps.weekly.data.iteration.enddate}）
+    - 统计窗口: ${steps.weekly.data.window.week_start} ~ ${steps.weekly.data.window.today}（近 7 天）
+
+    ## 需求
+    - 总数 ${steps.weekly.data.stories.total}，完成度 ${steps.weekly.data.stories.ratio}
+    - 状态分布: ${steps.weekly.data.stories.by_status | json}
+    - 本周新增 ${steps.weekly.data.stories.new_this_week} / 本周关闭 ${steps.weekly.data.stories.closed_this_week}（changes 近似核对: ${steps.weekly.data.stories.changed_this_week} 条需求在窗口内有变更记录）
+
+    ## 缺陷
+    - 总数 ${steps.weekly.data.bugs.total}，已关闭 ${steps.weekly.data.bugs.ratio}，现存未关闭 ${steps.weekly.data.bugs.open}
+    - 本周新增 ${steps.weekly.data.bugs.new_this_week} / 本周关闭 ${steps.weekly.data.bugs.closed_this_week}
+    - 严重度分布: ${steps.weekly.data.bugs.by_severity | json}
+
+    ## 任务
+    - 总数 ${steps.weekly.data.tasks.total}，完成 ${steps.weekly.data.tasks.ratio}，未启动 ${steps.weekly.data.tasks.not_started}，逾期未完成 ${steps.weekly.data.tasks.overdue}
+    - 平均进度 ${steps.weekly.data.tasks.avg_progress}%
+
+    ## 工时（近 7 天）
+    - 合计 ${steps.weekly.data.timesheets.hours} 小时 / ${steps.weekly.data.timesheets.people} 人
+    | 成员 | 工时(h) | 记录数 |
+    |------|---------|--------|
+    ${steps.weekly.data.timesheets.rows | rows owner,hours,records}
+
+    ## 口径脚注
+    - 统计范围: 迭代 ${vars.iteration_id}（需求/缺陷/任务按 iteration_id 归属；工时按 spentdate 落入近 7 天窗口，跨迭代工时不剔重）
+    - 过滤项: 标题 zzz-delete-me* 数据已剔除；范围类度量剔除风险项（label 含 risk 或名称以【风险】开头）
+    - 数据时间: ${steps.weekly.data.window.today}；「本周」= ${steps.weekly.data.window.week_start} 起（7 个自然日）
+    - 完成度定义: 需求 status ∈ {done, closed, complete, completed} 的数量 / 需求总数，分母保留不省略
+    - 局限: story_changes 为 workspace 级近 200 条采样，仅作「本周活跃需求」近似核对；周新增/关闭以需求 created/completed 字段为准
+
+    ## 主观补充
+    （以下由人工填写后再落库：本周亮点 / 风险与求助 / 下周计划）
+    - 亮点：
+    - 风险与求助：
+    - 下周计划：

package/templates/pm/cost-report.yaml

@@ -0,0 +1,74 @@
+# 工时执行报告（软考第11章 成本管理，纯只读 L0，类比 EVM）
+# 数据源：迭代 tasks（effort/effort_completed/remain/exceed/owner）+ tapd_get_timesheets
+# （spentdate 按迭代区间时间查询，校验填报完整性）
+# 用法: tapd pm cost report [--iteration <id>] [--dry-run]
+#       可用 --input '{"date_from":"2026-09-01","date_to":"2026-09-11"}' 覆盖填报窗口
+name: cost-report
+domain: cost
+title: 工时执行报告（effort/exceed 聚合 + timesheets 完整性校验，类比 EVM）
+write: false
+unwrap: true
+vars:
+  iteration_id: ""
+  date_from: ""
+  date_to: ""
+steps:
+  - id: iteration
+    uses: tapd_get_iterations
+    args:
+      id: "${vars.iteration_id}"
+      fields: "id,name,startdate,enddate,status"
+
+  - id: tasks
+    uses: tapd_get_tasks
+    args:
+      iteration_id: "${vars.iteration_id}"
+      fields: "id,name,owner,status,effort,effort_completed,remain,exceed"
+      limit: 200
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: window
+    expr: "(() => { const it = (steps.iteration.data ?? [])[0] ?? {}; const vf = String(vars.date_from ?? ''), vt = String(vars.date_to ?? ''); const from = vf !== '' ? vf : (String(it.startdate ?? '').slice(0, 10) || today); const to = vt !== '' ? vt : (String(it.enddate ?? '').slice(0, 10) || today); return { from: from, to: to, range: from + '~' + to }; })()"
+    depends_on: [iteration]
+
+  - id: timesheets
+    uses: tapd_get_timesheets
+    args:
+      spentdate: "${steps.window.data.range}"
+      fields: "entity_type,entity_id,owner,timespent,spentdate"
+      limit: 200
+    depends_on: [window]
+
+  - id: cost
+    expr: "(() => { const arr = v => Array.isArray(v) ? v : (v && Array.isArray(v.data) ? v.data : []); const num = v => { const n = Number(v); return Number.isFinite(n) ? n : 0; }; const ownerOf = v => { const s = String(v ?? '').trim(); return s === '' ? '(未分派)' : s; }; const r2 = n => Math.round(n * 100) / 100; const t = arr(steps.tasks.data); const ts = arr(steps.timesheets.data); const byOwner = {}; const ensure = o => { if (!byOwner[o]) byOwner[o] = { owner: o, tasks: 0, effort: 0, effortCompleted: 0, remain: 0, exceed: 0, timespent: 0 }; return byOwner[o]; }; let budget = 0, used = 0, remain = 0, exceed = 0; for (const k of t) { const r = ensure(ownerOf(k.owner)); r.tasks++; r.effort += num(k.effort); r.effortCompleted += num(k.effort_completed); r.remain += num(k.remain); r.exceed += num(k.exceed); budget += num(k.effort); used += num(k.effort_completed); remain += num(k.remain); exceed += num(k.exceed); } for (const w of ts) { ensure(ownerOf(w.owner)).timespent += num(w.timespent); } const ownerRows = Object.values(byOwner).map(r => ({ owner: r.owner, tasks: r.tasks, effort: r2(r.effort), effortCompleted: r2(r.effortCompleted), remain: r2(r.remain), exceed: r2(r.exceed), timespent: r2(r.timespent), rate: r.effort > 0 ? r2(r.effortCompleted) + '/' + r2(r.effort) : '0/0' })).sort((a, b) => b.effort - a.effort); const ac = ts.reduce((a, w) => a + num(w.timespent), 0); const filledEntities = new Set(ts.filter(w => String(w.entity_type) === 'task').map(w => String(w.entity_id))); const noSheet = t.filter(k => num(k.effort) > 0 && !filledEntities.has(String(k.id))); const missingOwners = ownerRows.filter(r => r.effort > 0 && r.timespent === 0).map(r => ({ owner: r.owner, effort: r.effort, tasks: r.tasks })); const totalsRows = [{ label: '预算 BAC = Σeffort', hours: r2(budget) }, { label: '已耗 EV = Σeffort_completed', hours: r2(used) }, { label: '剩余 = Σremain', hours: r2(remain) }, { label: '超支 = Σexceed', hours: r2(exceed) }, { label: '填报 AC = Σtimespent(区间内)', hours: r2(ac) }, { label: '偏差 CV = EV - AC', hours: r2(used - ac) }, { label: 'CPI = EV/AC', hours: ac > 0 ? r2(used / ac) + '（' + r2(used) + '/' + r2(ac) + '）' : 'n/a（分母为 0）' }]; return { totals: { budget: r2(budget), used: r2(used), remain: r2(remain), exceed: r2(exceed), ac: r2(ac), cv: r2(used - ac), window: steps.window.data, taskCount: t.length, sheetCount: ts.length, missingOwnerCount: missingOwners.length, missingTaskCount: noSheet.length }, totalsRows: totalsRows, ownerRows: ownerRows, missingOwners: missingOwners, missingTasks: noSheet.slice(0, 20).map(k => ({ id: String(k.id), name: k.name, owner: ownerOf(k.owner), effort: num(k.effort) })) }; })()"
+    depends_on: [iteration, tasks, window, timesheets]
+
+report:
+  format: markdown
+  template: |
+    # 工时执行报告 — ${steps.iteration.data.0.name}（${steps.iteration.data.0.startdate} ~ ${steps.iteration.data.0.enddate}）
+
+    - 任务 ${steps.cost.data.totals.taskCount} 个（已剔除 zzz-delete-me* 测试数据）；工时填报记录 ${steps.cost.data.totals.sheetCount} 条，窗口 ${steps.cost.data.totals.window.from} ~ ${steps.cost.data.totals.window.to}
+
+    ## 总量（EVM 类比）
+    | 指标 | 工时(h) |
+    |---|---|
+    ${steps.cost.data.totalsRows | rows label,hours}
+
+    ## 按 owner 分解
+    | 处理人 | 任务数 | 预算(h) | 已耗 EV(h) | 剩余(h) | 超支(h) | 填报 AC(h) | 完成率 EV/预算 |
+    |---|---|---|---|---|---|---|---|
+    ${steps.cost.data.ownerRows | rows owner,tasks,effort,effortCompleted,remain,exceed,timespent,rate}
+
+    ## 填报缺失名单（owner 级：有预算任务但区间零填报，共 ${steps.cost.data.totals.missingOwnerCount} 人）
+    | 处理人 | 名下任务预算(h) | 任务数 |
+    |---|---|---|
+    ${steps.cost.data.missingOwners | rows owner,effort,tasks}
+
+    ## 任务级缺失（effort>0 且窗口内无该任务填报，共 ${steps.cost.data.totals.missingTaskCount} 个，至多列 20）
+    | id | 任务 | 处理人 | 预算(h) |
+    |---|---|---|---|
+    ${steps.cost.data.missingTasks | rows id,name,owner,effort}
+
+    ---
+    口径：预算=Σ任务 effort；已耗(EV)=Σ effort_completed；剩余=Σ remain；超支=Σ exceed；填报(AC)=区间内 timesheets 的 timespent 合计（spentdate 用 TAPD 时间区间查询「起~止」，limit 200 超限截断不翻页）；完成率与 CPI 均保留分母（如 9/12）；owner 级缺失 = 该人名下任务 effort>0 但区间零填报记录；任务级缺失 = 任务 effort>0 且区间内无 entity_type=task、entity_id=该任务的填报记录（以任务表 effort 口径为准，不与 timesheet 交叉折算）。

package/templates/pm/integration-close.yaml

@@ -0,0 +1,118 @@
+# 结项检查与关闭（写场景）—— 整合管理（软考高项第4版 第8章）
+# 场景: tapd pm integration close
+# ⚠ 请先读 dry-run 报告确认无未完成项再加 --yes（不加 --yes 时本模板被写闸门拦截，只出检查报告预览）
+# 编排: 只读扫描（迭代内未完成需求/任务清单）→ 结项检查报告 → tapd_update_iteration(status=done)
+# 口径: 完成态 = resolved/closed/done 或已填 completed；任务完成态 = done；列表过滤 zzz-delete-me*
+name: integration-close
+domain: integration
+title: 结项检查与关闭（写场景：请先读 dry-run 报告确认无未完成项再加 --yes，软考第8章）
+write: true
+unwrap: true
+vars:
+  iteration_id: ""
+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，并发）----
+  - id: stories
+    uses: tapd_get_stories
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,owner,status,completed"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: tasks
+    uses: tapd_get_tasks
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,owner,status,due"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: scan
+    expr: >-
+      (() => {
+      const stories = steps.stories.data || [];
+      const tasks = steps.tasks.data || [];
+      const it = (steps.iteration.data && steps.iteration.data[0]) || {};
+      const DONE = ['resolved', 'closed', 'done'];
+      const isDoneStory = x => DONE.indexOf(String(x.status || '').toLowerCase()) >= 0 || Boolean(x.completed);
+      const openStories = stories.filter(x => !isDoneStory(x));
+      const openTasks = tasks.filter(x => String(x.status || '').toLowerCase() !== 'done');
+      const blockers = openStories.length + openTasks.length;
+      return {
+      itName: it.name || '（未找到迭代，请检查 --iteration）',
+      itRange: (it.startdate || '?') + ' ~ ' + (it.enddate || '?'),
+      storyTotal: stories.length,
+      openStoryCount: openStories.length,
+      openStoryRows: openStories.length > 0
+      ? openStories.map(x => ({ id: x.id, name: x.name, owner: x.owner, status: x.status }))
+      : [{ id: '-', name: '（无未完成需求）', owner: '-', status: '-' }],
+      taskTotal: tasks.length,
+      openTaskCount: openTasks.length,
+      openTaskRows: openTasks.length > 0
+      ? openTasks.map(x => ({ id: x.id, name: x.name, owner: x.owner, status: x.status }))
+      : [{ id: '-', name: '（无未完成任务）', owner: '-', status: '-' }],
+      blockers: blockers,
+      verdict: blockers === 0 ? '无未完成项，可结项' : '存在 ' + blockers + ' 个未完成项——请勿加 --yes，先处理或移交',
+      };
+      })()
+    depends_on: [iteration, stories, tasks]
+
+  # ---- 写步骤（双保险：无 --yes 时被写闸门拦截；--yes 后仍由扫描结果门控——
+  #      还有未完成项（blockers>0）时 where 为假，写步骤跳过不落库）----
+  - id: close
+    uses: tapd_update_iteration
+    args:
+      id: "${vars.iteration_id}"
+      status: done
+    where: "steps.scan.data.blockers === 0"
+    depends_on: [scan]
+
+  - id: close_ref
+    expr: >-
+      (() => {
+      const r = steps.close.data || {};
+      const inner = r.Iteration || r.iteration || r;
+      return {
+      id: String(inner.id || vars.iteration_id),
+      closeLine: '已执行，迭代 ' + (inner.id || vars.iteration_id) + ' 现状态: ' + (inner.status || 'done'),
+      };
+      })()
+    depends_on: [close]
+
+report:
+  format: markdown
+  template: |
+    # 结项检查报告 — ${steps.scan.data.itName}
+
+    - 迭代: ${steps.scan.data.itRange}（id=${vars.iteration_id}）
+    - 扫描结论: ${steps.scan.data.verdict}
+    - 需求: 共 ${steps.scan.data.storyTotal} 项，未完成 ${steps.scan.data.openStoryCount}
+    - 任务: 共 ${steps.scan.data.taskTotal} 个，未完成 ${steps.scan.data.openTaskCount}
+
+    > ⚠ 本场景含写步骤 tapd_update_iteration(status=done)。请先读 dry-run 计划与扫描结论
+    > 确认无未完成项再加 --yes；双保险：不加 --yes 时写闸门拦截（仅计划预览），
+    > 加了 --yes 但扫描仍有未完成项时，写步骤按 where 门控自动跳过，不落库。
+
+    ## 未完成需求（${steps.scan.data.openStoryCount} 项）
+
+    | id | 名称 | 处理人 | 状态 |
+    | ---- | ---- | ---- | ---- |
+    ${steps.scan.data.openStoryRows | rows id,name,owner,status}
+
+    ## 未完成任务（${steps.scan.data.openTaskCount} 个）
+
+    | id | 名称 | 处理人 | 状态 |
+    | ---- | ---- | ---- | ---- |
+    ${steps.scan.data.openTaskRows | rows id,name,owner,status}
+
+    ## 关闭结果
+
+    - tapd_update_iteration(id=${vars.iteration_id}, status=done)：${steps.close_ref.data.closeLine}

package/templates/pm/integration-health.yaml

@@ -0,0 +1,155 @@
+# 迭代健康盘（纯只读，L0 直接执行）—— 整合管理（软考高项第4版 第8章）
+# 场景: tapd pm integration health
+#   ≡ tapd pipeline run templates/pm/integration-health.yaml --iteration <id>
+# 口径:
+#   时间消耗% = (今天-开始)/(结束-开始)，截断到 [0,100]
+#   完成度%   = 已完成需求占比，分母剔除风险项（label 含 risk 或名称以【风险】开头）
+#               完成态 = resolved/closed/done（resolved+end，兼容常见工作流别名）
+#   红旗     = 时间-完成偏差>20% / 逾期任务 / 未解缺陷 / 迭代到期仍有未完成需求
+#   一切比率保留分母（如 8/15），迭代/需求/任务/缺陷列表均过滤 zzz-delete-me*
+name: integration-health
+domain: integration
+title: 迭代健康盘（时间%vs完成度%对比 + 红旗清单，软考第8章）
+write: false
+unwrap: true
+vars:
+  iteration_id: ""
+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')"
+
+  - id: stories
+    uses: tapd_get_stories
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,owner,status,priority_label,label,completed"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: tasks
+    uses: tapd_get_tasks
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,name,owner,status,due,progress"
+    filter: "!item.name.startsWith('zzz-delete-me')"
+
+  - id: bugs
+    uses: tapd_get_bugs
+    args:
+      iteration_id: "${vars.iteration_id}"
+      limit: 200
+      fields: "id,title,severity,current_owner,status"
+    filter: "!item.title.startsWith('zzz-delete-me')"
+
+  # 聚合：本地计算，不触 API。dayNum 为纯 JS 民用日序数（沙箱无 Date，只许 Math/String）
+  - id: health
+    expr: >-
+      (() => {
+      const stories = steps.stories.data || [];
+      const tasks = steps.tasks.data || [];
+      const bugs = steps.bugs.data || [];
+      const it = (steps.iteration.data && steps.iteration.data[0]) || {};
+      const dayNum = s => {
+      const p = String(s || '').split('-').map(Number);
+      if (p.length !== 3 || p.some(x => Number.isNaN(x))) return null;
+      const m = p[1];
+      const d = p[2];
+      const yy = m <= 2 ? p[0] - 1 : p[0];
+      const era = Math.floor(yy / 400);
+      const yoe = yy - era * 400;
+      const mp = (m + 9) % 12;
+      const doy = Math.floor((153 * mp + 2) / 5) + d - 1;
+      const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+      return era * 146097 + doe - 719468;
+      };
+      const t = dayNum(today);
+      const s0 = dayNum(it.startdate);
+      const e0 = dayNum(it.enddate);
+      let timePct = null;
+      if (s0 !== null && e0 !== null && e0 > s0) {
+      timePct = Math.round(Math.min(Math.max((t - s0) / (e0 - s0), 0), 1) * 100);
+      }
+      const DONE = ['resolved', 'closed', 'done'];
+      const BUG_CLOSED = ['resolved', 'verified', 'closed', 'rejected'];
+      const isRisk = x => String(x.label || '').indexOf('risk') >= 0 || String(x.name || '').indexOf('【风险】') === 0;
+      const isDone = x => DONE.indexOf(String(x.status || '').toLowerCase()) >= 0 || Boolean(x.completed);
+      const scope = stories.filter(x => !isRisk(x));
+      const doneList = scope.filter(isDone);
+      const donePct = scope.length > 0 ? Math.round(doneList.length / scope.length * 100) : null;
+      const overdue = tasks.filter(x => x.due && String(x.due).slice(0, 10) < today && String(x.status || '').toLowerCase() !== 'done');
+      const openBugs = bugs.filter(x => BUG_CLOSED.indexOf(String(x.status || '').toLowerCase()) < 0);
+      const notDone = scope.filter(x => !isDone(x));
+      const flags = [];
+      if (timePct !== null && donePct !== null && timePct - donePct > 20) {
+      flags.push({ item: '进度滞后', detail: '时间消耗 ' + timePct + '% 高于完成度 ' + donePct + '%（偏差 ' + (timePct - donePct) + 'pp，阈值 20%）' });
+      }
+      if (overdue.length > 0) {
+      flags.push({ item: '逾期任务', detail: overdue.length + '/' + tasks.length + ' 个任务逾期未完（如 #' + overdue[0].id + ' ' + overdue[0].name + '）' });
+      }
+      if (openBugs.length > 0) {
+      flags.push({ item: '未解缺陷', detail: '未解决缺陷 ' + openBugs.length + '/' + bugs.length + ' 个（sev1=' + openBugs.filter(b => String(b.severity) === '1').length + '）' });
+      }
+      if (e0 !== null && t > e0 && notDone.length > 0) {
+      flags.push({ item: '到期未完', detail: '迭代已于 ' + it.enddate + ' 到期，仍有 ' + notDone.length + ' 个需求未完成' });
+      }
+      let timeDisplay = '迭代缺少起止日期，无法计算';
+      if (timePct !== null) {
+      const tail = e0 !== null && t > e0 ? '已超期 ' + (t - e0) + ' 天' : '距结束还剩 ' + (e0 - t) + ' 天';
+      timeDisplay = timePct + '%（' + tail + '）';
+      }
+      const riskCount = stories.length - scope.length;
+      const realFlags = flags.slice();
+      if (realFlags.length === 0) flags.push({ item: '-', detail: '无红旗（时间/任务/缺陷/到期四路扫描均通过）' });
+      return {
+      itName: it.name || '（未找到迭代，请检查 --iteration）',
+      itRange: (it.startdate || '?') + ' ~ ' + (it.enddate || '?'),
+      itStatus: it.status || '?',
+      today: today,
+      statusLabel: realFlags.length === 0 ? '绿（健康）' : '红（' + realFlags.length + ' 项红旗）',
+      timeDisplay: timeDisplay,
+      doneDisplay: donePct === null ? '无有效需求范围' : doneList.length + '/' + scope.length + '（' + donePct + '%）',
+      riskNote: '分母剔除风险项 ' + riskCount + ' 个：label 含 risk 或名称以【风险】开头',
+      storyLine: stories.length + ' 项（范围口径 ' + scope.length + '）',
+      taskLine: tasks.length + ' 个（逾期 ' + overdue.length + '）',
+      bugLine: bugs.length + ' 个（未解决 ' + openBugs.length + '）',
+      flagSummary: realFlags.length === 0 ? '无' : realFlags.length + ' 项，见下表',
+      flags: flags,
+      notDoneCount: notDone.length,
+      notDoneRows: notDone.length > 0
+      ? notDone.map(x => ({ id: x.id, name: x.name, owner: x.owner, status: x.status }))
+      : [{ id: '-', name: '（范围内需求已全部完成）', owner: '-', status: '-' }],
+      };
+      })()
+    depends_on: [iteration, stories, tasks, bugs]
+
+report:
+  format: markdown
+  template: |
+    # 迭代健康盘 — ${steps.health.data.itName}
+
+    - 迭代: ${steps.health.data.itRange}（status=${steps.health.data.itStatus}）
+    - 报告日期: ${steps.health.data.today}｜总体状态: ${steps.health.data.statusLabel}
+    - 时间消耗: ${steps.health.data.timeDisplay}
+    - 完成度: ${steps.health.data.doneDisplay}（${steps.health.data.riskNote}）
+    - 需求: ${steps.health.data.storyLine}｜任务: ${steps.health.data.taskLine}｜缺陷: ${steps.health.data.bugLine}
+    - 红旗: ${steps.health.data.flagSummary}
+
+    ## 红旗清单
+
+    | 类别 | 说明 |
+    | ---- | ---- |
+    ${steps.health.data.flags | rows item,detail}
+
+    ## 未完成需求（范围口径 ${steps.health.data.notDoneCount} 项）
+
+    | id | 名称 | 处理人 | 状态 |
+    | ---- | ---- | ---- | ---- |
+    ${steps.health.data.notDoneRows | rows id,name,owner,status}
+
+    > 口径脚注（对齐 tapd-pm skill 11-performance 剧本A）：完成度只统计范围口径
+    > （剔除 label 含 risk / 名称【风险】前缀）；完成态 = resolved+end；比率均保留分母。