@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/skills/analyze-product-dependencies/scripts/validation-helpers.mjs

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+export function load(fileArg, label) {
+  const path = resolve(fileArg);
+  try { return { path, text: readFileSync(path, "utf8") }; }
+  catch (error) { throw new Error(`Cannot read ${label} ${path}: ${error.message}`); }
+}
+
+export function metadata(text, name) {
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return fm.match(new RegExp(`^${escaped}:[ \\t]*["']?([^"'\\r\\n]+)["']?[ \\t]*$`, "m"))?.[1].trim();
+}
+
+export function canonical(title) {
+  return title.replace(/^\d+(?:\.\d+)*[.、]?[ \t]*/, "").trim();
+}
+
+export function headings(text, level) {
+  const prefix = "#".repeat(level);
+  const matches = [...text.matchAll(new RegExp(`^${prefix}\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({ title: match[1].trim(), text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
+}
+
+export function section(text, level, title) {
+  return headings(text, level).find((item) => canonical(item.title) === title)?.text;
+}
+
+export function assertHeadings(text, level, required, errors, owner) {
+  for (const title of required) {
+    const found = headings(text, level).filter((item) => canonical(item.title) === title);
+    if (found.length !== 1) errors.push(`${owner} must contain exactly one ${title} heading.`);
+    else if (!found[0].text.split(/\r?\n/).slice(1).some((line) => line.trim() && !/^\|?[-:| ]+\|?$/.test(line.trim()))) {
+      errors.push(`${owner} section ${title} must not be empty.`);
+    }
+  }
+}
+
+export function storyBlocks(text, prefix) {
+  if (!text) return [];
+  const matches = [...text.matchAll(new RegExp(`^###\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({ id: match[1], text: text.slice(match.index, matches[index + 1]?.index ?? text.length) }));
+}
+
+export function outputSpecBlocks(text, prefix) {
+  return storyBlocks(text, prefix);
+}
+
+export function acceptanceBlocks(story, prefix) {
+  const matches = [...story.text.matchAll(new RegExp(`^####\\s+(${prefix}-\\d{3,})\\s+(.+)$`, "gm"))];
+  return matches.map((match, index) => ({
+    id: match[1],
+    text: story.text.slice(match.index, matches[index + 1]?.index ?? story.text.length),
+  }));
+}
+
+export function validateAcceptance(block, owner, errors) {
+  const labels = ["Given", "When", "Then", "异常场景"];
+  const positions = labels.map((label) => ({ label, index: block.search(new RegExp(`^${label}[：:]`, "m")) }));
+  for (const item of positions) if (item.index < 0) errors.push(`${owner} is missing ${item.label}.`);
+  if (positions.some((item) => item.index < 0)) return;
+  const counts = positions.map((item, index) => {
+    const end = positions[index + 1]?.index ?? block.length;
+    return (block.slice(item.index, end).match(/^-\s+\S.+$/gm) ?? []).length;
+  });
+  if (counts[0] < 1 || counts[1] < 1 || counts[2] < 2 || counts[3] < 1) {
+    errors.push(`${owner} must contain at least 1 Given, 1 When, 2 Then, and 1 exception bullet.`);
+  }
+  if (counts.reduce((sum, count) => sum + count, 0) < 6) errors.push(`${owner} must contain at least six concrete bullets.`);
+  if (!/(?:不得|不应|禁止|保留|恢复|重试|兜底|回滚|disabled)/.test(block)) {
+    errors.push(`${owner} must include an observable protection or recovery result.`);
+  }
+}
+
+export function containsUnresolvedBlockingPriority(block) {
+  if (!block) return false;
+  return block.split(/\r?\n/).slice(1).some((line) => {
+    const plain = line.trim().replace(/^[-*+]\s*/, "").replace(/^\[[ xX]\]\s*/, "");
+    if (!/\bP[01]\b/.test(plain)) return false;
+    if (/^(?:不存在|没有|无)(?:任何)?(?:尚未|未)?(?:解决|确认|关闭|完成)?(?:的)?\s*P[01]\b/.test(plain)) return false;
+    if (/^P[01]\b/.test(plain)) return true;
+    return /(?:pending(?:-blocking)?|unresolved|未解决|未确认|待确认|未决|阻塞)/i.test(plain);
+  });
+}
+
+export function scopeIncludes(upstream, selected) {
+  if (upstream === "both") return ["frontend", "backend", "both"].includes(selected);
+  return upstream === selected;
+}
+
+export function field(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.match(new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.+)$`, "m"))?.[1].trim().replace(/[。.]$/, "");
+}
+
+export function fieldBlock(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^-[ \\t]*${escaped}[：:][ \\t]*(.*)$`, "m").exec(text);
+  if (!match) return "";
+  const lineEnd = text.indexOf("\n", match.index);
+  const rest = lineEnd < 0 ? "" : text.slice(lineEnd + 1);
+  const next = rest.search(/^-\s*[^\r\n：:]+[：:]/m);
+  return `${match[1]}\n${rest.slice(0, next < 0 ? rest.length : next)}`.trim();
+}
+
+export function tableValue(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.match(new RegExp(`^\\|[ \\t]*${escaped}[ \\t]*\\|[ \\t]*([^|]+)\\|`, "m"))?.[1].trim();
+}
+
+export function apiBlocks(text) {
+  const details = section(text, 2, "API 详情") ?? "";
+  const matches = [...details.matchAll(/^###\s+(API-\d{3,})\s+(.+)$/gm)];
+  return matches.map((match, index) => ({ id: match[1], title: match[2].trim(), text: details.slice(match.index, matches[index + 1]?.index ?? details.length) }));
+}
+
+export function print(label, path, errors) {
+  if (errors.length) {
+    console.error(`${label} validation failed (${errors.length}):`);
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  console.log(`${label} validation passed: ${path}`);
+}
+
+export function validateArtifactLocation(artifact, errors, expectedName) {
+  const requirementId = metadata(artifact.text, "requirement_id");
+  const projectRootValue = metadata(artifact.text, "project_root");
+  if (!requirementId || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(requirementId)) {
+    errors.push("requirement_id must use lowercase letters, digits, and single hyphens.");
+    return;
+  }
+  if (!projectRootValue) {
+    errors.push("project_root is required.");
+    return;
+  }
+  const projectRoot = resolve(dirname(artifact.path), projectRootValue);
+  if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+    errors.push(`project_root does not resolve to an existing directory: ${projectRoot}`);
+    return;
+  }
+  const expected = resolve(join(projectRoot, "docs", "product-analysis", requirementId));
+  if (dirname(artifact.path) !== expected) errors.push(`Artifact must be located under ${expected}.`);
+  if (expectedName && basename(artifact.path) !== expectedName) errors.push(`Artifact filename must be ${expectedName}.`);
+}

package/skills/analyze-product-requirements/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: analyze-product-requirements
+description: 将自然语言需求或现有需求文档整理为冻结的澄清前分析、按需澄清记录和完整 Product Requirement，按 frontend、backend 或 both 范围生成精简用户故事、逐故事输出规范与 Given/When/Then 验收标准。用于需求分析、需求澄清、PRD 或用户故事拆分。
+---
+
+# Analyze Product Requirements
+
+IRON LAW：`product-analysis.md` 只能生成一次。首次写入成功后，其正文、frontmatter 和文件路径在当前 requirement 的整个生命周期内都不可变；后续轮次禁止编辑、覆盖、追加、格式化、移动或删除该文件。澄清决策只能写入 `requirement-clarification.md`，并通过重新生成合并到 `product-requirement.md`。原始需求同样只读。
+
+本 skill 只定义需求，不分析完整代码依赖或生成实现代码。可对用户提供的仓库做定向事实搜索，但不得输出文件级影响分析。
+
+## 输入与产物
+
+- 必填：自然语言需求或原始需求文档路径。
+- 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认 `both`。
+- 可选：代码仓库、知识库、历史需求、API 文档、设计规范、业务规则、`project_root`、`requirement_id` 和 `output_dir`。
+- 默认目录：`<project-root>/docs/product-analysis/<requirement-id>/`。
+- 固定产物：该目录内的 `product-analysis.md`、`requirement-clarification.md`、`product-requirement.md`。
+
+## Workflow
+
+- [ ] Step 0：确认输入与写入边界 ⛔ BLOCKING
+  - [ ] 原始需求必须足以识别业务目标；输入文件只读。
+  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时为 `both`，非法值或冲突的多个值必须停止。
+  - [ ] 在生成前明确回显“分析范围：frontend | backend | both”；三个产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
+  - [ ] 确定项目根：显式 `project_root` > 仓库根 > 当前项目根。
+  - [ ] 确定 requirement ID：显式值 > 需求标题 slug > `YYYYMMDD-<summary-slug>`；仅小写字母、数字和单连字符。
+  - [ ] 确定目录：显式 `output_dir` 必须等于项目根下 `docs/product-analysis/<requirement-id>`；否则使用该默认目录。
+  - [ ] 创建目录，三个产物写入同一目录；元数据使用同一 `requirement_id` 和相对 `project_root: ../../..`。
+  - [ ] 输出路径不得与原始需求路径相同；已有目录来源不同则停止，不得混写。
+  - [ ] 目标目录已有 `product-analysis.md` 时，验证同源后只读加载并跳过 Step 1；无论 pending 或 complete，都不得对该文件执行任何写操作。
+  - [ ] 已有同源 pending 任务只能继续更新 Clarification 和 Product Requirement；如 Product Analysis 需要更正，停止当前 requirement，使用新的 `requirement_id` 和目录重新开始。其他产物覆盖先确认。
+- [ ] Step 1：一次性生成并冻结 Product Analysis ⚠️ REQUIRED
+  - [ ] 读取 `references/product-analysis-schema.md`。
+  - [ ] 区分明确需求、推断需求和待确认问题。
+  - [ ] 如提供仓库，只定向搜索可验证事实并记录 `CODE-FACT-*` 证据。
+  - [ ] 仅按 target 生成精简故事骨架和逐故事初步输出规范：`frontend` 只生成 `FE-US-*`，`backend` 只生成 `BE-US-*`，`both` 才生成两端。
+  - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。
+  - [ ] 有问题时使用 `ready-for-clarification`；无问题时使用 `no-clarification-required`。
+  - [ ] 写入前完成全部分析内容，只允许一次创建；写入成功即冻结，当前及后续澄清轮次不得再调用写工具处理该路径。
+- [ ] Step 2：建立澄清决策树 ⚠️ REQUIRED
+  - [ ] 读取 `references/clarification-and-knowledge.md` 和 `references/requirement-clarification-schema.md`。
+  - [ ] 有问题时列出 3–6 个顶层 `BR-*` 分支，按依赖排序，从最基础分支开始。
+  - [ ] 每轮先给推荐答案和理由，只问一个主要问题；可合并同一决策分支内紧密耦合的子项，但不得混合无关分支。
+  - [ ] 用户回答后先复核当前回答是否足以形成明确、唯一、可执行且可验收的最终决策；不得仅因用户已经回答就标记为 confirmed。
+  - [ ] 回答不完整、存在多种合理解释、依赖未定义概念、与原始需求或已有决策冲突，或无法自然合并到范围、规则、输出规范和 AC 时，当前问题仍未解决；下一轮必须优先针对该回答的具体模糊点继续澄清，不得跳到其他分支。
+  - [ ] 后续追问必须指出上一轮回答中仍不明确的内容，并收窄为可直接确认的决策点；不得原样重复上一轮问题。
+  - [ ] 当前回答明确后，再重新识别其他剩余模糊点和回答新引入的模糊点；仅在它们会影响范围、规则、输出或验收时进入下一轮，总轮数不得超过 3 轮。
+  - [ ] 第 3 轮后不得继续提问；仍有 P0/P1 时保持 `pending` 并说明阻断项，仍有 P2 时仅可按已记录的默认行为与影响处理。
+  - [ ] 能由代码或资料确认的事实自行回答并附证据，不把现状当作产品决策。
+  - [ ] 完成一个分支后再进入下一个；不得遗留模糊的“视情况而定”。
+  - [ ] 无需澄清时使用三章精简记录，不伪造 `BR-*`、`Q-*` 或 `DEC-Q-*`。
+- [ ] Step 3：记录 Requirement Clarification ⚠️ REQUIRED
+  - [ ] 记录总澄清轮数，并为每个问题记录所属轮次、推荐答案、用户回答、最终决策、来源和目标位置；依赖、备选、代码证据和未确认影响仅在适用时记录。
+  - [ ] P0/P1 未解决时保持 `pending`；P2 延后必须给出默认行为和影响。
+- [ ] Step 4：重新生成 Product Requirement ⛔ BLOCKING
+  - [ ] 读取 `references/product-requirement-schema.md` 和 `references/acceptance-criteria.md`。
+  - [ ] 基于原始需求、冻结的 Product Analysis 和 Clarification 重新生成，不做字符串回写。
+  - [ ] 优先级：用户确认决策 > 原始明确需求 > 已确认默认值 > 模型推断；代码库事实只用于理解现状、发现冲突和辅助澄清，不构成独立需求来源。
+  - [ ] 不得把 `CODE-FACT-*`、仓库路径、代码符号、模块结构、数据表或当前实现过程原样写入 Product Requirement；代码事实只有经用户确认或被原始需求明确要求时，才能转换为不含实现细节的产品规则，证据仍只保留在 Product Analysis 和 Clarification。
+  - [ ] 把决策自然合并到范围、规则、故事、逐故事输出规范和 AC，并在决策追溯中登记。
+  - [ ] 用户故事只描述角色/使用方、目标/能力、价值、入口/触发方式和 AC 引用；详细产品行为只写在同 ID 输出规范中，正式 AC 嵌入该输出规范。
+  - [ ] target 为 `backend` 或 `both` 时，后端故事只定义 API 的业务能力、输入输出语义、权限和规则；具体方法、路径及 DTO 留给依赖 skill。
+- [ ] Step 5：验证并交付 ⛔ BLOCKING
+  - [ ] 向 Product Analysis 和 Product Requirement 校验器传入归一化 target，再运行三个产物校验器和 validator matrix。
+  - [ ] 确认 `product-analysis.md` 与进入澄清前的冻结版本完全一致。
+  - [ ] 只有所有命令返回 0 才能声明完成。
+
+完整格式示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
+
+## 完成规则
+
+- `no-clarification-required` 仍生成三个产物；Clarification 使用“澄清结论、来源、合并结果”三章精简结构。
+- `complete` Clarification 的全部分支必须 resolved，P0/P1 必须由用户确认，每个决策标记必须进入 Product Requirement 决策追溯。
+- Product Requirement 必须自包含；读者不得依赖聊天、Product Analysis 或 Clarification 才能理解需求。
+- Product Requirement 只描述目标产品行为，不记录代码库事实、证据位置或当前实现；不得出现 `CODE-FACT-*`、仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名或实现算法。
+- 不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
+
+## Validation
+
+把 `<skill-root>` 解析为本 `SKILL.md` 所在目录，全部参数使用绝对路径：
+
+```bash
+node <skill-root>/scripts/validate-product-analysis.mjs <product-analysis.md> --target <frontend|backend|both>
+node <skill-root>/scripts/validate-product-requirement.mjs <product-requirement.md> --target <frontend|backend|both>
+node <skill-root>/scripts/validate-requirement-clarification.mjs <product-analysis.md> <requirement-clarification.md> <product-requirement.md>
+node <skill-root>/scripts/test-validators.mjs
+```
+
+澄清中的中间产物可加 `--allow-pending`；通过 pending 校验不代表完成。

package/skills/analyze-product-requirements/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "产品需求分析"
+  short_description: "分析并按需澄清需求，生成故事、输出规范和验收标准"
+  default_prompt: "使用 $analyze-product-requirements 分析并按需澄清需求，生成完整 Product Requirement。"

package/skills/analyze-product-requirements/references/acceptance-criteria.md

@@ -0,0 +1,91 @@
+# 详细验收标准规则
+
+## 目录
+
+- 基本要求
+- 分段最低要求
+- 前端示例
+- 后端示例
+- 不合格写法
+
+## 基本要求
+
+每条验收标准必须独立可执行、结果可观察，并使用 Given/When/Then。一个用户故事存在多个关键流程时，拆成多个 AC，不要把互不相关的行为塞入一条 AC。
+
+每条 AC 必须说明：
+
+1. Given：用户身份、权限、业务数据、系统状态和必要依赖。
+2. When：具体操作、请求、事件或任务触发。
+3. Then：明确的 UI、状态、字段值、状态码、数据变化或日志结果。
+4. 异常场景：空数据、错误输入、无权限、超时、依赖失败及恢复方式。
+5. 禁止行为：不得泄露、重复提交、产生脏数据、白屏或静默失败等。
+
+## 分段最低要求
+
+- Given：至少 1 个具体条目。
+- When：至少 1 个具体条目。
+- Then：至少 2 个可观察条目。
+- 异常场景：至少 1 个条目；每个条目必须同时写明具体触发条件和可观察处理结果。
+- 四段总计：至少 6 个条目。
+- Then 或异常场景：至少包含一个禁止行为、失败保护、保留、恢复、重试或兜底结果。
+
+不得在 AC 中使用“功能正常、应正常展示、展示正确、接口可用、数据正确、符合预期、妥善处理、合理处理”等模糊结果。
+不得用“无异常情况”“没有需要处理的异常场景”“无需处理失败”等表述代替异常处理结果。
+
+## 前端示例
+
+```md
+#### AC-FE-001 展示退款处理中状态
+
+Given：
+- 用户已登录且订单属于当前用户。
+- 订单存在退款记录，refundStatus 为 processing。
+
+When：
+- 用户从订单列表进入该订单详情页。
+
+Then：
+- 退款进度模块展示“退款处理中”。
+- 展示 currentStep 和格式化后的 updatedAt。
+- 请求完成后 loading 状态消失。
+- 页面不得展示其他订单的退款数据。
+
+异常场景：
+- 请求超时时展示失败提示和重试入口。
+- currentStep 缺失时展示“状态未知”，页面不得白屏。
+```
+
+## 后端示例
+
+```md
+#### AC-BE-001 返回退款处理中状态
+
+Given：
+- 请求用户已认证且拥有目标订单。
+- 退款记录状态为 processing。
+
+When：
+- 调用 GET /orders/{orderId}/refund-status。
+
+Then：
+- HTTP 状态码为 200。
+- refundStatus 为 processing，failedReason 为 null。
+- currentStep 与退款记录一致，updatedAt 使用约定时间格式。
+- 响应不得包含内部错误堆栈或其他用户数据。
+
+异常场景：
+- 订单不存在时返回 404 和标准错误结构。
+- 无权访问时返回 403，且不得泄露订单详情。
+```
+
+## 不合格写法
+
+以下内容不能单独作为验收标准：
+
+- 功能正常。
+- 页面展示正确。
+- 接口可用。
+- 数据符合预期。
+- 异常情况正确处理。
+
+必须将“正常、正确、可用、符合预期”替换为可核对的具体结果。

package/skills/analyze-product-requirements/references/clarification-and-knowledge.md

@@ -0,0 +1,56 @@
+# 澄清、代码事实与合成规则
+
+## 1. 知识库与代码事实
+
+未执行知识检索时明确记录 `not-integrated`/`not-executed`，不得声称“未命中”或模拟记录。
+
+提供代码仓库时只做定向事实搜索：认证、权限、状态枚举、相似能力、字段类型、统一错误结构。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+
+知识或代码与需求冲突时：保留来源证据、生成澄清问题、用户裁决前不选边。
+
+## 2. 决策树式访谈
+
+1. 从 Product Analysis 的推断、问题、输出规范和高风险默认值提取 3–6 个顶层 `BR-*` 分支。
+2. 标注分支依赖，从范围、权限、核心流程、数据语义等基础决策开始。
+3. 每轮只处理一个主要问题：先给推荐答案和理由，再提问并等待回答。同分支、同依赖链的子项可合并，不相关问题不得换装为一题。
+4. 收到回答后重新识别剩余模糊点；仅在它们会影响范围、输出或验收时开启下一轮。
+5. 一次助手提问与用户回答记为一轮，总轮数不得超过 3。第 3 轮后仍有 P0/P1 时保持 pending 并阻断 Product Requirement complete；P2 按已记录的默认行为和影响处理。
+6. 所有分支解决后，用一段话总结关键决策。
+
+### 回答复核
+
+收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求或已有决策冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
+
+任一条件不满足时：
+
+- 保留用户原始回答，`最终决策` 写“未形成”并说明具体模糊点。
+- P0/P1 使用 `pending-blocking`；P2 使用 `pending-non-blocking`，同时记录默认行为和未确认影响。
+- 下一轮优先继续当前分支，明确指出上一轮回答仍不清晰的部分，并将问题收窄为可直接确认的决策点；不得原样重复问题或跳到其他分支。
+- 不得把模型推断、推荐答案或代码现状当作用户确认。
+
+当前问题明确后，再扫描其他未解决问题和本次回答新引入的模糊点。只有会改变范围、权限、核心流程、数据语义、输出行为或验收结果的问题才继续澄清；不影响产品行为的措辞和下游技术细节不消耗澄清轮次。
+
+问题等级：
+
+- P0：改变范围、权限、关键流程、数据语义或验收结果；必须由用户明确确认。
+- P1：可以推荐默认值，但必须经用户确认。
+- P2：可延后，但必须给出当前默认行为、影响和后续确认入口。
+
+没有问题时跳过交互访谈，不伪造分支、问题或决策标记，但仍生成完整 Clarification 检查记录。
+
+## 3. 合成规则
+
+Product Analysis 冻结不回写。`最终决策` 是合成最终需求的规范化事实；`目标位置` 指向需求范围、业务规则、故事、输出规范或 AC。
+
+三个产物必须写入同一 `<project-root>/docs/product-analysis/<requirement-id>/`。同目录来源使用相对路径，避免把个人机器绝对路径写入可交接产物。
+
+生成 Product Requirement 时：
+
+- 用户确认的推断转为正式需求。
+- 用户否定的推断删除或进入非目标。
+- 确认的默认值进入规则和故事。
+- 代码库事实只用于解释现状、识别冲突和支持澄清，不作为独立需求来源；未经用户确认且未被原始需求明确要求的代码现状不得进入 Product Requirement。
+- 需要合并的代码事实必须转换为目标产品语言，只保留用户可感知的行为、业务规则和验收结果；`CODE-FACT-*`、证据路径、代码符号、模块结构、数据表和实现过程继续留在 Product Analysis 或 Clarification。
+- 决策影响故事时重新生成故事与 AC，不只在决策列表堆积答案。
+- `DEC-Q-*` 在决策追溯中登记，并能定位到正式章节。
+- 无需澄清时不生成任何 `DEC-Q-*`，说明需求直接来源于原始需求。

package/skills/analyze-product-requirements/references/example.md

@@ -0,0 +1,86 @@
+# V3 完整流程示例
+
+需求：登录用户在个人资料页修改昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+
+## Product Analysis 关键结构
+
+```md
+---
+artifact_version: "3.0"
+artifact_type: product-analysis
+requirement_id: profile-nickname
+project_root: ../../..
+analysis_scope: frontend
+analysis_status: no-clarification-required
+source_requirement: inline
+repository_root: none
+---
+
+## 6. 初步前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收关注点：合法值可保存；非法值不可提交；失败时保留输入
+
+## 7. 初步前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：保存失败时保留输入，不得静默失败
+```
+
+Product Analysis 不创建正式 AC。
+
+## 无需澄清记录
+
+```md
+## 1. 澄清结论
+- 状态：no-clarification-required
+- 原因：范围、权限、数据语义和验收结果已经明确。
+## 2. 来源
+- Product Analysis：./product-analysis.md
+## 3. 合并结果
+- Product Requirement 根据明确需求生成，无额外决策标记。
+```
+
+## Product Requirement 故事、规范与 AC
+
+```md
+## 5. 前端用户故事
+### FE-US-001 修改昵称
+- 角色：已登录用户
+- 目标：修改自己的展示昵称
+- 价值：保持个人资料准确
+- 入口：个人资料页
+- 验收标准：AC-FE-001
+
+## 6. 前端输出规范
+### FE-US-001 修改昵称
+- 页面/组件：个人资料页、昵称编辑表单
+- 展示内容：当前昵称、字符计数、校验提示
+- 交互动作：编辑、保存、取消、重试
+- UI 状态：normal、dirty、loading、success、error、disabled
+- 表单校验：昵称长度为 2–20 个字符
+- 权限可见性：仅当前登录用户
+- 边界处理：失败时保留输入，不得静默失败
+
+#### AC-FE-001 保存合法昵称
+Given：
+- 用户已登录并打开个人资料页。
+When：
+- 用户输入合法昵称并点击保存。
+Then：
+- 页面提交昵称修改请求。
+- 保存成功后展示新昵称。
+- 保存期间按钮保持 disabled。
+异常场景：
+- 保存失败时保留输入并提供重试入口。
+```
+
+故事与输出规范使用同一 ID；故事只引用 AC，AC 正文只在对应输出规范中出现一次。

package/skills/analyze-product-requirements/references/forward-test-cases.md

@@ -0,0 +1,66 @@
+# Forward-Test Cases
+
+在独立 agent 中逐个执行，不提供预期正文，只核对不变量。
+
+## Case 1：无需澄清
+
+```text
+Use $analyze-product-requirements --target frontend.
+需求：登录用户在个人资料页修改自己的昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
+```
+
+核对：三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`；三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC；Clarification 使用三章精简结构且没有 BR/Q/DEC；Product Requirement 为 complete；故事与同 ID 输出规范一一对应。
+
+## Case 2：需要逐题澄清
+
+```text
+Use $analyze-product-requirements target=both.
+需求：管理员可以导出用户数据。
+```
+
+核对：先列 3–6 个分支；从管理员角色和敏感字段范围开始；每轮先推荐再只问一个主要问题；收到回答后重新识别模糊点；`clarification_rounds` 和问题轮次一致且最多为 3。第 3 轮后仍有 P0/P1 时保持 pending，不再提问、不自行补全；不得回写 Product Analysis。
+
+## Case 3：后端 API 业务需求
+
+```text
+Use $analyze-product-requirements target=backend.
+需求：登录用户查询自己订单的退款状态，失败时看到可理解原因，内部错误不得泄露。
+```
+
+核对：BE 故事只保留能力、使用方、价值、触发方式和 AC 引用；同 ID 输出规范明确输入输出语义、权限和规则；不虚构最终 URL、HTTP 方法、DTO 或代码落点。
+
+## Case 4：非 API 后端任务
+
+```text
+Use $analyze-product-requirements target=backend.
+需求：每天归档 90 天前已完成通知，重复执行不得重复归档。
+```
+
+核对：触发方式明确为定时任务；包含批次、幂等、并发和失败恢复；不会把它误标为 API。
+
+## Case 5：回答仍然模糊
+
+```text
+Use $analyze-product-requirements target=both.
+需求：管理员可以导出用户数据。
+第一轮询问导出字段范围时，用户回答：敏感字段按实际情况处理。
+```
+
+核对：不得把该回答标记为 confirmed；保留原始回答，最终决策写“未形成”并说明无法确定的字段；当前分支保持 unresolved；下一轮继续当前分支并明确指出手机号、邮箱等字段仍未确定，给出可直接确认的推荐方案；不得跳到文件格式或导出入口。
+
+## Case 6：下一轮消除模糊
+
+```text
+沿用 Case 5。下一轮用户回答：导出邮箱，不导出手机号和身份证号。
+```
+
+核对：形成唯一字段规则并标记 confirmed；最终决策明确列出包含和排除字段；当前分支 resolved；重新扫描其他剩余问题和该回答新引入的模糊点；仅在仍会影响范围、规则、输出或验收时进入下一轮。
+
+## Case 7：代码事实不得泄漏到最终需求
+
+```text
+Use $analyze-product-requirements target=backend，并提供一个仓库。
+需求：仅管理员可以导出用户数据。仓库中现有权限判断位于 src/auth/permission.ts，使用 role=admin。
+```
+
+核对：Product Analysis 可记录 `CODE-FACT-*`、证据路径和现状；Clarification 可引用该证据辅助判断，但不得把现状自动视为目标决策；Product Requirement 只写“仅管理员可以导出用户数据”等产品规则，不包含 `CODE-FACT-*`、`src/auth/permission.ts`、`role=admin`、代码符号、模块结构或当前实现过程。

package/skills/analyze-product-requirements/references/product-analysis-schema.md

@@ -0,0 +1,32 @@
+# Product Analysis V3 输出契约
+
+Product Analysis 是澄清前快照，只允许一次创建。首次写入后，正文、frontmatter 和路径全部冻结；需要更正时使用新的 `requirement_id`。
+
+```yaml
+---
+artifact_version: "3.0"
+artifact_type: product-analysis
+requirement_id: <lowercase-slug>
+project_root: ../../..
+analysis_scope: frontend | backend | both
+analysis_status: ready-for-clarification | no-clarification-required
+source_requirement: <路径或 inline>
+repository_root: <路径或 none>
+---
+```
+
+文件固定为 `<project-root>/docs/product-analysis/<requirement-id>/product-analysis.md`。
+
+固定章节：原始需求、需求概述、业务目标、需求分析、外部事实。需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。
+
+按 scope 追加“初步前端用户故事/初步前端输出规范”或“初步后端用户故事/初步后端输出规范”。不得生成独立用户角色或验收标准汇总。
+
+前端故事字段：角色、目标、价值、入口、验收关注点。
+
+后端故事字段：系统能力、使用方、业务价值、触发方式、验收关注点。触发方式使用 API、定时任务、事件、消息、内部调用或数据迁移。
+
+每个故事必须恰好存在一个同 ID 输出规范。前端输出规范字段：页面/组件、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端输出规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
+
+Product Analysis 只记录验收关注点，不得出现正式 `AC-FE-*`、`AC-BE-*` 或 Given/When/Then 块。
+
+`no-clarification-required` 的待确认问题明确写“无”和理由，不得出现问题标记、优先级或问句；`ready-for-clarification` 至少包含一个带优先级或问号的问题。

package/skills/analyze-product-requirements/references/product-requirement-schema.md

@@ -0,0 +1,33 @@
+# Product Requirement V3 输出契约
+
+Product Requirement 是澄清后的完整需求文档和下游唯一需求事实源。
+
+```yaml
+---
+artifact_version: "3.0"
+artifact_type: product-requirement
+requirement_id: <lowercase-slug>
+project_root: ../../..
+requirement_status: pending | complete
+analysis_scope: frontend | backend | both
+source_requirement: <路径或 inline>
+source_product_analysis: ./product-analysis.md
+source_clarification: ./requirement-clarification.md
+---
+```
+
+固定章节：需求概述、业务目标、需求范围、业务规则、决策追溯。需求范围包含已确认需求、非目标、默认假设、未决事项。不得生成独立用户角色或验收标准汇总。
+
+Product Requirement 只描述目标产品行为，不承载代码侦察记录。不得包含 `CODE-FACT-*`、仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。代码库事实只可在经用户确认或被原始需求明确要求后，转换为不含实现细节的产品规则；原始证据保留在 Product Analysis 或 Clarification。
+
+按 scope 追加前端/后端用户故事和同域输出规范。
+
+前端故事字段：角色、目标、价值、入口、验收标准。后端故事字段：系统能力、使用方、业务价值、触发方式、验收标准。
+
+每个故事必须恰好存在一个同 ID 输出规范。前端规范字段：页面/组件、展示内容、交互动作、UI 状态、表单校验、权限可见性、边界处理。后端规范字段：输入语义、输出语义、数据读写、权限规则、业务规则、安全要求、幂等与并发、错误与边界。
+
+正式 `AC-FE-*` 或 `AC-BE-*` 作为四级标题嵌入对应输出规范。故事的验收标准引用必须与该规范中的 AC 完全一致；AC 遵循 `acceptance-criteria.md`。
+
+后端触发方式明确写 API、定时任务、事件、消息、内部调用或数据迁移，供下游判断 API 适用性。
+
+`complete` 不得包含未解决 P0/P1。真实未决项以 `P0：`、`P1：` 或 `P2：` 开头。澄清决策使用 `DEC-Q-*` 在决策追溯中登记并定位到正式章节。

package/skills/analyze-product-requirements/references/requirement-clarification-schema.md

@@ -0,0 +1,35 @@
+# Requirement Clarification V3 输出契约
+
+```yaml
+---
+artifact_version: "3.0"
+artifact_type: requirement-clarification
+requirement_id: <lowercase-slug>
+project_root: ../../..
+analysis_scope: frontend | backend | both
+clarification_status: pending | complete
+clarification_rounds: 0 | 1 | 2 | 3
+source_product_analysis: ./product-analysis.md
+target_product_requirement: ./product-requirement.md
+---
+```
+
+文件与 Product Analysis、Product Requirement 位于同一需求目录。
+
+## 无需澄清
+
+只生成三个章节：澄清结论、来源、合并结果。`clarification_rounds` 必须为 `0`。澄清结论写明 `no-clarification-required` 和理由；不得生成 `BR-*`、`Q-*`、`DEC-Q-*`。
+
+## 需要澄清
+
+固定章节：澄清来源、决策分支、问题记录、决策索引。定义 3–6 个 `BR-*` 分支，表格包含分支 ID、名称、优先级、依赖和状态。
+
+问题核心字段：澄清轮次、分支、优先级、影响范围、推荐答案、推荐理由、用户回答、最终决策、决策来源、状态、决策标记、目标位置。`clarification_rounds` 必须为 `1`–`3`，每个问题的澄清轮次不得超过该值。
+
+条件字段：有前置依赖时写依赖问题；存在真实备选时写备选方案；决策来源为 `code-evidence` 时写代码证据；状态为 `pending-non-blocking` 时写未确认影响。
+
+状态使用 confirmed、default-confirmed、pending-blocking、pending-non-blocking；决策来源使用 user、source-requirement、code-evidence、confirmed-default。决策标记必须为 `DEC-Q-*`。
+
+`complete` 要求全部分支 resolved；P0/P1 必须由用户明确回答并使用 confirmed/user；P2 可确认、使用已确认默认值，或在写明影响后延后。complete 时每个决策标记必须出现在 Product Requirement 的决策追溯中。
+
+每轮在用户回答后重新识别模糊点，有必要才再澄清。最多 3 轮；第 3 轮后仍有 P0/P1 时产物必须保持 `pending`，不得继续追问或自行填补决策。