@tea-agent/loop-agent 0.33.1 → 0.33.2

package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
-import { existsSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { apiBlocks, assertHeadings, field, headings, load, metadata, print, scopeIncludes, section, storyBlocks, tableValue, validateArtifactLocation } from "./validation-helpers.mjs";
+import { dirname } from "node:path";
+import { apiBlocks, assertHeadings, headings, load, metadata, print, scopeIncludes, section, tableValue, validateArtifactLocation, validateFrontmatter } from "./validation-helpers.mjs";
 
 const args = process.argv.slice(2);
 const targetIndex = args.indexOf("--target");
@@ -17,10 +16,11 @@ try { requirement = load(positional[0], "Product Requirement"); api = load(posit
 catch (error) { console.error(error.message); process.exit(2); }
 
 const errors = [];
+validateFrontmatter(api.text, ["artifact_version", "artifact_type", "requirement_id", "api_status", "analysis_scope"], errors, "API Documentation");
 validateArtifactLocation(api, errors, "api-documentation.md");
 const scope = metadata(api.text, "analysis_scope");
 const upstreamScope = metadata(requirement.text, "analysis_scope");
-if (metadata(api.text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(api.text, "artifact_version") !== "4.0") errors.push("artifact_version must be 4.0.");
 if (metadata(api.text, "artifact_type") !== "api-documentation") errors.push("artifact_type must be api-documentation.");
 if (metadata(api.text, "api_status") !== "complete") errors.push("api_status must be complete.");
 if (!["backend", "both"].includes(scope)) errors.push("analysis_scope must be backend or both for API Documentation.");
@@ -28,25 +28,66 @@ if (targetIndex >= 0 && !["backend", "both"].includes(expectedTarget)) errors.pu
 else if (expectedTarget && scope !== expectedTarget) errors.push(`analysis_scope ${scope} does not match requested target ${expectedTarget}.`);
 if (!scopeIncludes(upstreamScope, scope)) errors.push("analysis_scope must be included in Product Requirement scope.");
 if (metadata(api.text, "requirement_id") !== metadata(requirement.text, "requirement_id")) errors.push("requirement_id must match Product Requirement.");
-const source = metadata(api.text, "source_product_requirement");
-if (!source || resolve(dirname(api.path), source) !== requirement.path) errors.push("source_product_requirement must reference the supplied Product Requirement.");
 if (dirname(requirement.path) !== dirname(api.path)) errors.push("API Documentation and Product Requirement must be in the same requirement directory.");
-const repo = metadata(api.text, "repository_root");
-const repoPath = repo ? resolve(dirname(api.path), repo) : "";
-if (!repoPath || !existsSync(repoPath) || !statSync(repoPath).isDirectory()) errors.push("repository_root must be an existing readable directory.");
-const projectRoot = resolve(dirname(api.path), metadata(api.text, "project_root") ?? "");
-if (repoPath && projectRoot && repoPath !== projectRoot) errors.push("repository_root must resolve to project_root.");
 
 assertHeadings(api.text, 2, ["通用约定", "API 索引", "API 详情", "数据模型", "错误码"], errors, "API Documentation");
 const conventions = section(api.text, 2, "通用约定") ?? "";
-assertHeadings(conventions, 3, ["Base URL", "统一响应结构", "错误响应结构", "分页约定", "时间和标识符规范"], errors, "通用约定");
+assertHeadings(conventions, 3, ["Base URL", "成功响应结构", "公共错误响应结构", "时间和标识符规范"], errors, "通用约定");
+const paginationConventions = headings(conventions, 3).filter((item) => item.title.replace(/^\d+(?:\.\d+)*[.、]?[ \t]*/, "").trim() === "分页约定");
+const publicError = section(conventions, 3, "公共错误响应结构") ?? "";
+const publicErrorExample = publicError.match(/```json\s*([\s\S]*?)```/)?.[1];
+if (!publicErrorExample) errors.push("公共错误响应结构 must include a JSON example.");
+else try {
+  const parsed = JSON.parse(publicErrorExample);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Object.hasOwn(parsed, "code")) errors.push("公共错误响应结构 JSON example must contain top-level code.");
+} catch { errors.push("公共错误响应结构 JSON example must be valid."); }
 if (/(?:认证方式|认证要求|鉴权方式|鉴权要求|权限要求|权限规则|访问控制要求|Authorization|Bearer|X-API-Key|access[_-]?token|id[_-]?token|业务规则|业务逻辑|实现逻辑|处理逻辑|分支逻辑|数据读写逻辑|实现算法)/i.test(api.text)) errors.push("API Documentation must not contain authentication, permission, business-rule, or implementation-logic content.");
 if (/(?:复用检查|通用定义复用)/.test(api.text)) errors.push("API Documentation must not contain reuse-check sections or search evidence.");
+if (/\b(?:BE-US|AC-BE)-\d{3,}\b/.test(api.text) || /^\|[^\r\n]*(?:用户故事|\bAC\b)[^\r\n]*\|$/m.test(api.text)) errors.push("API Documentation must not contain user-story or acceptance-criteria traceability.");
 const index = section(api.text, 2, "API 索引") ?? "";
+const indexHeader = index.split(/\r?\n/).find((line) => /^\|/.test(line));
+const indexColumns = indexHeader?.split("|").slice(1, -1).map((cell) => cell.trim()) ?? [];
+if (indexColumns.join("|") !== ["API ID", "Method + Path", "Operation ID", "变更类型"].join("|")) {
+  errors.push("API index columns must be API ID, Method + Path, Operation ID, and 变更类型.");
+}
+const indexRows = index.split(/\r?\n/)
+  .filter((line) => /^\|/.test(line))
+  .slice(1)
+  .filter((line) => !/^\|?[-:| ]+\|?$/.test(line.trim()))
+  .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()))
+  .map((cells) => ({ cells, id: cells[0], signature: cells[1], operation: cells[2], changeType: cells[3] }));
+const indexIds = new Set();
+const indexOperations = new Set();
+for (const row of indexRows) {
+  if (row.cells.length !== 4 || !/^API-\d{3,}$/.test(row.id ?? "") || !/^(?:GET|POST|PUT|PATCH|DELETE)\s+\/\S+$/i.test(row.signature ?? "") || !row.operation || !["新增", "修改", "复用"].includes(row.changeType)) {
+    errors.push("Each API index row must contain a valid API ID, Method + Path, Operation ID, and 变更类型.");
+    continue;
+  }
+  if (indexIds.has(row.id)) errors.push(`Duplicate API ID in index: ${row.id}.`);
+  indexIds.add(row.id);
+  if (indexOperations.has(row.operation)) errors.push(`Duplicate Operation ID in index: ${row.operation}.`);
+  indexOperations.add(row.operation);
+}
 const blocks = apiBlocks(api.text);
 if (!blocks.length) errors.push("API Documentation must contain at least one API-* detail.");
 const ids = new Set();
 const operations = new Set();
+const paginationParameters = [];
+const numericSet = (value) => [...new Set((value.match(/\b\d+\b/g) ?? []).map(Number))].sort((a, b) => a - b);
+const sameNumbers = (left, right) => left.length === right.length && left.every((value, index) => value === right[index]);
+function markdownTableRows(block) {
+  const lines = block.split(/\r?\n/).filter((line) => /^\s*\|/.test(line));
+  if (lines.length < 2) return { headers: [], rows: [] };
+  const cells = (line) => line.trim()
+    .split(/(?<!\\)\|/)
+    .slice(1, -1)
+    .map((cell) => cell.replace(/\\\|/g, "|").trim());
+  const headers = cells(lines[0]);
+  const rows = lines.slice(1)
+    .filter((line) => !/^\s*\|?[-:| ]+\|?\s*$/.test(line))
+    .map(cells);
+  return { headers, rows };
+}
 for (const block of blocks) {
   if (ids.has(block.id)) errors.push(`Duplicate API ID: ${block.id}.`);
   ids.add(block.id);
@@ -60,14 +101,26 @@ for (const block of blocks) {
   const signature = block.text.match(/^>\s*`(GET|POST|PUT|PATCH|DELETE)\s+(\/[^`]+)`/m);
   if (!signature) errors.push(`${block.id} is missing a Swagger-style method and path signature.`);
   for (const title of ["基本信息", "成功响应", "错误响应"]) if (!headings(block.text, 4).some((item) => item.title.trim() === title)) errors.push(`${block.id} is missing section ${title}.`);
+  for (const title of ["Header 参数", "Path 参数", "Query 参数", "Request Body"]) {
+    const optional = section(block.text, 4, title);
+    if (optional && !optional.split(/\r?\n/).slice(1).some((line) => line.trim() && !/^\|?[-:| ]+\|?$/.test(line.trim()))) {
+      errors.push(`${block.id} must omit empty ${title} sections.`);
+    }
+  }
   const query = section(block.text, 4, "Query 参数") ?? "";
-  if (/\b(?:pageSize|page_size|limit|cursor|page)\b/i.test(query)) {
-    const pageSizeRow = query.split(/\r?\n/).find((line) => /^\|\s*(?:pageSize|page_size|limit)\s*\|/i.test(line));
-    if (!pageSizeRow) errors.push(`${block.id} paginated API must define an optional page-size parameter.`);
-    else {
-      if (!/^\|\s*(?:pageSize|page_size|limit)\s*\|\s*[^|]+\|\s*(?:否|可选)\s*\|/i.test(pageSizeRow)) errors.push(`${block.id} page-size parameter must be optional.`);
-      const values = [...new Set(pageSizeRow.match(/\b\d+\b/g) ?? [])].sort((a, b) => Number(a) - Number(b));
-      if (values.join(",") !== "10,20,50,100") errors.push(`${block.id} page-size values must be exactly 10, 20, 50, and 100.`);
+  if (query) {
+    const { headers, rows } = markdownTableRows(query);
+    const nameIndex = headers.findIndex((name) => /^(?:参数|名称|字段)$/.test(name));
+    const allowedIndex = headers.findIndex((name) => /^(?:允许值|可选值|枚举)$/.test(name));
+    for (const row of rows) {
+      const name = row[nameIndex] ?? "";
+      if (!/^(?:pageSize|page_size|limit)$/.test(name)) continue;
+      const allowed = allowedIndex >= 0 ? row[allowedIndex] ?? "" : "";
+      const values = numericSet(allowed);
+      paginationParameters.push({ apiId: block.id, name, values });
+      if (allowedIndex < 0 || !allowed || allowed === "-" || !values.length) {
+        errors.push(`${block.id} pagination parameter ${name} must declare numeric 允许值/可选值/枚举.`);
+      }
     }
   }
   if (signature) {
@@ -81,21 +134,61 @@ for (const block of blocks) {
   }
   const success = section(block.text, 4, "成功响应") ?? "";
   const error = section(block.text, 4, "错误响应") ?? "";
-  if (!/HTTP(?: 状态码)?[：:]\s*2\d\d/.test(success)) errors.push(`${block.id} must define a 2xx success response.`);
-  if (!/^\|\s*[45]\d\d\s*\|/m.test(error)) errors.push(`${block.id} must define at least one 4xx or 5xx error response.`);
+  if (!/HTTP(?: 状态码)?[：:]\s*200\b/.test(success)) errors.push(`${block.id} success response must use HTTP 200.`);
+  const errorRows = [...error.matchAll(/^\|\s*(\d{3})\s*\|\s*([^|]+?)\s*\|/gm)];
+  if (!errorRows.length) errors.push(`${block.id} must define at least one error response.`);
+  else if (errorRows.some((row) => row[1] !== "200")) errors.push(`${block.id} error responses must use HTTP 200.`);
+  const examples = {};
   for (const [content, label] of [[success, "success"], [error, "error"]]) {
     const example = content.match(/```json\s*([\s\S]*?)```/)?.[1];
     if (!example) errors.push(`${block.id} must include a JSON ${label} example.`);
-    else try { JSON.parse(example); } catch { errors.push(`${block.id} ${label} example must be valid JSON.`); }
+    else try {
+      const parsed = JSON.parse(example);
+      examples[label] = parsed;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Object.hasOwn(parsed, "code")) errors.push(`${block.id} ${label} example must contain top-level code.`);
+    } catch { errors.push(`${block.id} ${label} example must be valid JSON.`); }
+  }
+  if (examples.success && examples.error && examples.success.code === examples.error.code) errors.push(`${block.id} success and error codes must be different.`);
+  if (examples.error && Object.hasOwn(examples.error, "code") && errorRows.length && !errorRows.some((row) => row[2].trim() === String(examples.error.code))) {
+    errors.push(`${block.id} error example code must be listed in the error response table.`);
+  }
+  const indexRow = indexRows.find((row) => row.id === block.id);
+  if (!indexRow) errors.push(`${block.id} is missing from API index.`);
+  else {
+    if (operation && indexRow.operation !== operation) errors.push(`${block.id} Operation ID does not match API index.`);
+    if (signature && indexRow.signature !== `${signature[1]} ${signature[2]}`) errors.push(`${block.id} method and path do not match API index.`);
+    if (tableValue(block.text, "变更类型") && indexRow.changeType !== tableValue(block.text, "变更类型")) errors.push(`${block.id} 变更类型 does not match API index.`);
   }
-  if (!index.includes(block.id)) errors.push(`${block.id} is missing from API index.`);
-  if (operation && !index.includes(operation)) errors.push(`${block.id} Operation ID is missing from API index.`);
-  if (signature && !index.includes(`${signature[1]} ${signature[2]}`)) errors.push(`${block.id} method and path are missing from API index.`);
 }
+for (const row of indexRows) if (/^API-\d{3,}$/.test(row.id ?? "") && !ids.has(row.id)) errors.push(`${row.id} appears in API index without a matching API detail.`);
 
-const requiredApiStories = storyBlocks(section(requirement.text, 2, "后端用户故事"), "BE-US").filter((story) => /\bAPI\b/i.test(field(story.text, "触发方式") ?? ""));
-for (const story of requiredApiStories) {
-  if (!index.includes(story.id)) errors.push(`API index does not cover API-triggered story ${story.id}.`);
-  for (const ac of field(story.text, "验收标准")?.match(/AC-BE-\d{3,}/g) ?? []) if (!index.includes(ac)) errors.push(`API index does not trace ${ac}.`);
+if (paginationParameters.length) {
+  if (paginationConventions.length !== 1) {
+    errors.push("API Documentation with pageSize/page_size/limit Query parameters must contain exactly one 分页约定 section.");
+  } else {
+    const conventionBody = paginationConventions[0].text.split(/\r?\n/).slice(1).join("\n");
+    const conventionValues = numericSet(conventionBody);
+    if (!conventionValues.length) errors.push("分页约定 must declare numeric page-size allowed values.");
+    for (const parameter of paginationParameters) {
+      if (parameter.values.length && conventionValues.length && !sameNumbers(parameter.values, conventionValues)) {
+        errors.push(`${parameter.apiId} ${parameter.name} allowed values must match 分页约定.`);
+      }
+    }
+  }
+} else if (paginationConventions.length) {
+  errors.push("Non-paginated API Documentation must not contain 分页约定.");
 }
+
+const requirementPaginationRules = [...requirement.text.matchAll(
+  /^(?=.*(?:pageSize|page_size|limit|每页条数))(?=.*(?:允许值|允许集合|取值范围))(.+)$/gmi,
+)].map((match) => numericSet(match[1])).filter((values) => values.length);
+if (requirementPaginationRules.length && paginationParameters.length) {
+  const upstreamValues = requirementPaginationRules[0];
+  for (const parameter of paginationParameters) {
+    if (parameter.values.length && !sameNumbers(parameter.values, upstreamValues)) {
+      errors.push(`${parameter.apiId} ${parameter.name} allowed values must match Product Requirement.`);
+    }
+  }
+}
+
 print("API Documentation", api.path, errors);

package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs

@@ -1,39 +1,39 @@
 #!/usr/bin/env node
 
-import { existsSync, statSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
-import { apiBlocks, assertHeadings, canonical, field, fieldBlock, headings, load, metadata, print, scopeIncludes, section, storyBlocks, tableValue, validateArtifactLocation } from "./validation-helpers.mjs";
+import { basename, dirname } from "node:path";
+import { apiBlocks, assertHeadings, canonical, field, fieldBlock, headings, load, metadata, print, scopeIncludes, section, storyBlocks, tableValue, validateArtifactLocation, validateFrontmatter } from "./validation-helpers.mjs";
 
 const args = process.argv.slice(2);
 const targetIndex = args.indexOf("--target");
 const expectedTarget = targetIndex >= 0 ? args[targetIndex + 1] : undefined;
-const positional = args.filter((_, index) => targetIndex < 0 || (index !== targetIndex && index !== targetIndex + 1));
+const apiDocIndex = args.indexOf("--api-doc");
+const externalApiArg = apiDocIndex >= 0 ? args[apiDocIndex + 1] : undefined;
+const positional = args.filter((_, index) =>
+  (targetIndex < 0 || (index !== targetIndex && index !== targetIndex + 1))
+  && (apiDocIndex < 0 || (index !== apiDocIndex && index !== apiDocIndex + 1))
+);
 const [requirementArg, dependencyArg, apiArg] = positional;
 if (!requirementArg || !dependencyArg) {
-  console.error("Usage: node validate-dependency-analysis.mjs <product-requirement.md|none> <dependency-analysis.md> [api-documentation.md] [--target frontend|backend|both]");
+  console.error("Usage: node validate-dependency-analysis.mjs <product-requirement.md|none> <dependency-analysis.md> [api-documentation.md] [--api-doc external-api.md] [--target frontend|backend|both]");
   process.exit(2);
 }
-let requirement, dependency, api;
+let requirement, dependency, api, externalApi;
 try {
   if (requirementArg !== "none") requirement = load(requirementArg, "Product Requirement");
   dependency = load(dependencyArg, "Dependency Analysis");
   if (apiArg) api = load(apiArg, "API Documentation");
+  if (externalApiArg) externalApi = load(externalApiArg, "external API Documentation");
 } catch (error) { console.error(error.message); process.exit(2); }
 
 const errors = [];
+validateFrontmatter(dependency.text, ["artifact_version", "artifact_type", "requirement_id", "analysis_scope", "analysis_status", "blocked_on"], errors, "Dependency Analysis");
 validateArtifactLocation(dependency, errors, "dependency-analysis.md");
 const scope = metadata(dependency.text, "analysis_scope");
 const status = metadata(dependency.text, "analysis_status");
 const blockedOn = metadata(dependency.text, "blocked_on") ?? "";
 const blockedReasons = blockedOn.split(/[\s,，]+/).filter(Boolean);
-const source = metadata(dependency.text, "source_product_requirement");
-const sourceApi = metadata(dependency.text, "source_api_documentation");
-const repo = metadata(dependency.text, "repository_root");
-const repoPath = repo && repo !== "none" ? resolve(dirname(dependency.path), repo) : "";
-const repoExists = Boolean(repoPath && existsSync(repoPath) && statSync(repoPath).isDirectory());
-const projectRoot = resolve(dirname(dependency.path), metadata(dependency.text, "project_root") ?? "");
 
-if (metadata(dependency.text, "artifact_version") !== "3.0") errors.push("artifact_version must be 3.0.");
+if (metadata(dependency.text, "artifact_version") !== "4.0") errors.push("artifact_version must be 4.0.");
 if (metadata(dependency.text, "artifact_type") !== "dependency-analysis") errors.push("artifact_type must be dependency-analysis.");
 if (!["frontend", "backend", "both"].includes(scope)) errors.push("analysis_scope must be frontend, backend, or both.");
 if (targetIndex >= 0 && !["frontend", "backend", "both"].includes(expectedTarget)) errors.push("--target must be frontend, backend, or both.");
@@ -45,21 +45,17 @@ function validateRequirementLink({ allowScopeMismatch = false } = {}) {
   if (basename(requirement.path) !== "product-requirement.md") errors.push("Product Requirement filename must be product-requirement.md.");
   if (!allowScopeMismatch && !scopeIncludes(metadata(requirement.text, "analysis_scope"), scope)) errors.push("analysis_scope must be included in Product Requirement scope.");
   if (metadata(dependency.text, "requirement_id") !== metadata(requirement.text, "requirement_id")) errors.push("requirement_id must match Product Requirement.");
-  if (!source || resolve(dirname(dependency.path), source) !== requirement.path) errors.push("source_product_requirement must reference the supplied Product Requirement.");
   if (dirname(requirement.path) !== dirname(dependency.path)) errors.push("Dependency Analysis and Product Requirement must be in the same requirement directory.");
 }
 
 if (status === "blocked") {
-  const allowed = new Set(["requirement-missing", "requirement-invalid", "requirement-not-complete", "repository-missing", "repository-unreadable", "scope-mismatch", "missing-stories", "missing-acceptance", "api-business-contract-incomplete"]);
+  const allowed = new Set(["requirement-missing", "requirement-invalid", "requirement-not-complete", "repository-missing", "repository-unreadable", "scope-mismatch", "missing-stories", "missing-acceptance", "api-business-contract-incomplete", "api-surface-unconfirmed"]);
   if (!blockedReasons.length || blockedOn === "none") errors.push("blocked analysis must declare blocked_on reasons.");
   for (const reason of blockedReasons) if (!allowed.has(reason)) errors.push(`Unknown blocked_on reason: ${reason}.`);
   if (requirement) validateRequirementLink({ allowScopeMismatch: blockedReasons.includes("scope-mismatch") });
   else {
     if (!blockedReasons.includes("requirement-missing")) errors.push("A missing Product Requirement requires blocked_on: requirement-missing.");
-    if (source !== "none") errors.push("Missing Product Requirement must use source_product_requirement: none.");
   }
-  if (!blockedReasons.some((reason) => ["repository-missing", "repository-unreadable"].includes(reason)) && !repoExists) errors.push("repository_root must be readable unless blocked on repository availability.");
-  if (sourceApi !== "none") errors.push("Blocked Dependency Analysis must use source_api_documentation: none.");
   const required = ["分析范围", "输入与代码基线", "阻断原因", "恢复条件"];
   assertHeadings(dependency.text, 2, required, errors, "Blocked Dependency Analysis");
   for (const heading of headings(dependency.text, 2)) if (!required.includes(canonical(heading.title))) errors.push(`Blocked Dependency Analysis must not contain section ${canonical(heading.title)}.`);
@@ -70,13 +66,21 @@ if (status === "blocked") {
 if (!requirement) errors.push("Complete Dependency Analysis requires Product Requirement input.");
 else validateRequirementLink();
 if (blockedOn !== "none") errors.push("complete analysis must use blocked_on: none.");
-if (!repoExists) errors.push("repository_root must be an existing readable directory.");
-if (repoPath && repoPath !== projectRoot) errors.push("repository_root must resolve to project_root.");
-assertHeadings(dependency.text, 2, ["输入与代码基线", "用户故事覆盖矩阵", "跨故事共享依赖", "风险与未定位项"], errors, "Dependency Analysis");
-if (/^##\s+(?:\d+[.、]?\s*)?(?:分析范围|追溯汇总)\s*$/m.test(dependency.text)) errors.push("Complete V3 Dependency Analysis must not contain 分析范围 or 追溯汇总 sections.");
+assertHeadings(dependency.text, 2, ["输入与代码基线", "用户故事覆盖矩阵", "API 实现映射", "跨故事共享依赖", "跨故事风险与未定位项"], errors, "Dependency Analysis");
+const baseline = section(dependency.text, 2, "输入与代码基线") ?? "";
+const knowledgeStatuses = baseline.match(/\b(?:executed-hit|executed-no-match|unavailable)\b/g) ?? [];
+if (/\bnot-executed\b/.test(baseline)) errors.push("输入与代码基线 must not use not-executed; every dependency analysis requires a real knowledge search.");
+if (knowledgeStatuses.length !== 1) errors.push("输入与代码基线 must contain exactly one knowledge status: executed-hit, executed-no-match, or unavailable.");
+if (knowledgeStatuses[0] === "executed-hit" && !/\bKB-EVIDENCE-\d+\b/.test(baseline)) errors.push("executed-hit 输入与代码基线 must contain at least one KB-EVIDENCE-* marker.");
+if (knowledgeStatuses[0] !== "executed-hit" && /\bKB-EVIDENCE-\d+\b/.test(baseline)) errors.push("KB-EVIDENCE-* markers require executed-hit knowledge status.");
+if (knowledgeStatuses[0] === "unavailable" && !/^[ \t]*-[ \t]*用户处置[：:][ \t]*已确认跳过知识库\s*$/m.test(baseline)) errors.push("unavailable 输入与代码基线 must record 用户处置：已确认跳过知识库.");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:分析范围|追溯汇总)\s*$/m.test(dependency.text)) errors.push("Complete V4 Dependency Analysis must not contain 分析范围 or 追溯汇总 sections.");
+if (/^##\s+(?:\d+[.、]?\s*)?(?:全局文件索引|影响文件索引)\s*$/m.test(dependency.text)) errors.push("Dependency Analysis must not contain a global file index.");
+if (/^####\s+(?:Header|Path|Query|Request Body|成功响应|错误响应)/mi.test(dependency.text) || /```json/i.test(dependency.text)) errors.push("Dependency Analysis must not copy full API contract sections or JSON examples.");
+if (/^Given[：:]|^When[：:]|^Then[：:]/m.test(dependency.text)) errors.push("Dependency Analysis must not copy Given/When/Then acceptance text.");
 if (scope === "frontend" || scope === "both") assertHeadings(dependency.text, 2, ["前端依赖详情"], errors, "Dependency Analysis");
-if (scope === "backend" || scope === "both") assertHeadings(dependency.text, 2, ["后端依赖详情", "API 实现映射"], errors, "Dependency Analysis");
-if (scope === "frontend" && /(?:^##\s+.*(?:后端依赖详情|API 实现映射)|\bBE-US-\d{3,}\b|\bAC-BE-\d{3,}\b|\bAPI-\d{3,}\b)/m.test(dependency.text)) errors.push("frontend scope must not contain backend dependency details or API mappings.");
+if (scope === "backend" || scope === "both") assertHeadings(dependency.text, 2, ["后端依赖详情"], errors, "Dependency Analysis");
+if (scope === "frontend" && /(?:^##\s+.*后端依赖详情|\bBE-US-\d{3,}\b|\bAC-BE-\d{3,}\b)/m.test(dependency.text)) errors.push("frontend scope must not contain backend dependency details.");
 if (scope === "backend" && /(?:^##\s+.*前端依赖详情|\bFE-US-\d{3,}\b|\bAC-FE-\d{3,}\b)/m.test(dependency.text)) errors.push("backend scope must not contain frontend dependency details.");
 
 const frontendStories = requirement && (scope === "frontend" || scope === "both") ? storyBlocks(section(requirement.text, 2, "前端用户故事"), "FE-US") : [];
@@ -84,27 +88,39 @@ const backendStories = requirement && (scope === "backend" || scope === "both")
 const apiRequired = backendStories.some((story) => /\bAPI\b/i.test(field(story.text, "触发方式") ?? ""));
 if (apiRequired) {
   if (!api) errors.push("API-triggered backend stories require api-documentation.md.");
-  if (!sourceApi || sourceApi === "none") errors.push("API-triggered backend stories require source_api_documentation.");
-  if (api && resolve(dirname(dependency.path), sourceApi) !== api.path) errors.push("source_api_documentation must reference the supplied API Documentation.");
-} else {
-  if (api) errors.push("API Documentation must not be supplied when no selected backend story uses API.");
-  if (sourceApi !== "none") errors.push("Non-API analysis must use source_api_documentation: none.");
-  if ((scope === "backend" || scope === "both") && !/不适用.*不涉及 HTTP API/s.test(section(dependency.text, 2, "API 实现映射") ?? "")) errors.push("Non-API analysis must mark API 实现映射 not applicable.");
 }
+if (!api && !externalApi && !/不适用.*不涉及 HTTP API/s.test(section(dependency.text, 2, "API 实现映射") ?? "")) errors.push("Analysis without API Documentation must mark API 实现映射 not applicable.");
+
+const documentedApiIds = new Set(api ? apiBlocks(api.text).map((item) => item.id) : []);
+const externalSignatures = new Set(
+  externalApi
+    ? [...externalApi.text.matchAll(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s`|]+)/gi)].map((item) => `${item[1].toUpperCase()} ${item[2]}`)
+    : []
+);
+const storyApiRefs = new Map();
+const localRisks = [];
+const frontendSpecs = requirement ? storyBlocks(section(requirement.text, 2, "前端输出规范"), "FE-US") : [];
 
 function validateDetails(frontend, expectedStories) {
   const title = frontend ? "前端依赖详情" : "后端依赖详情";
   const prefix = frontend ? "FE-US" : "BE-US";
   const acPrefix = frontend ? "AC-FE" : "AC-BE";
   const requiredFields = frontend
-    ? ["验收标准", "页面/路由", "组件", "状态", "API client/类型", "状态与边界落点", "定位证据", "风险", "置信度"]
+    ? ["验收标准", "API 文档引用", "页面/路由", "组件", "状态", "API client/类型", "状态与边界落点", "定位证据", "风险", "置信度"]
     : ["验收标准", "API 文档引用", "路由/入口", "Controller/Handler", "Service/领域逻辑", "DTO/Schema", "数据依赖", "权限依赖", "错误/日志/审计", "测试落点", "定位证据", "风险", "置信度"];
   const details = storyBlocks(section(dependency.text, 2, title), prefix);
-  for (const story of expectedStories) if (!details.some((item) => item.id === story.id)) errors.push(`Dependency Analysis is missing ${title} for ${story.id}.`);
+  for (const story of expectedStories) {
+    const count = details.filter((item) => item.id === story.id).length;
+    if (count === 0) errors.push(`Dependency Analysis is missing ${title} for ${story.id}.`);
+    if (count > 1) errors.push(`Dependency Analysis contains duplicate ${title} for ${story.id}.`);
+  }
   for (const detail of details) {
     const story = expectedStories.find((item) => item.id === detail.id);
     if (!story) errors.push(`Dependency Analysis contains unselected story ${detail.id}.`);
-    for (const name of requiredFields) if (!field(detail.text, name)) errors.push(`${detail.id} dependency detail is missing field ${name}.`);
+    for (const name of requiredFields) {
+      const value = name === "页面/路由" ? fieldBlock(detail.text, name) : field(detail.text, name);
+      if (!value) errors.push(`${detail.id} dependency detail is missing field ${name}.`);
+    }
     const impact = fieldBlock(detail.text, "影响文件");
     if (!impact) errors.push(`${detail.id} dependency detail is missing field 影响文件.`);
     const declarations = [...impact.matchAll(/^\s*-\s*(F\d+)\s+(add|modify|reuse|新增|修改|复用)\s+`?([^`\r\n]+)`?/gmi)];
@@ -117,7 +133,35 @@ function validateDetails(frontend, expectedStories) {
       const expected = field(story.text, "验收标准")?.match(new RegExp(`${acPrefix}-\\d{3,}`, "g")) ?? [];
       const actual = field(detail.text, "验收标准")?.match(new RegExp(`${acPrefix}-\\d{3,}`, "g")) ?? [];
       if ([...expected].sort().join() !== [...actual].sort().join()) errors.push(`${detail.id} acceptance references must match Product Requirement.`);
+      const reference = field(detail.text, "API 文档引用") ?? "";
+      const refs = frontend
+        ? [...new Set([...reference.matchAll(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s`|,，;；]+)/gi)].map((item) => `${item[1].toUpperCase()} ${item[2]}`))]
+        : [...new Set(reference.match(/API-\d{3,}/g) ?? [])];
+      storyApiRefs.set(detail.id, refs);
+      const trigger = field(story.text, "触发方式") ?? "";
+      if (!frontend && /\bAPI\b/i.test(trigger) && !refs.length) errors.push(`${detail.id} API-triggered story must reference one or more API IDs.`);
+      if (!frontend && /^API[（(]Web\s*\+\s*Remote[）)]$/i.test(trigger) && refs.length < 2) errors.push(`${detail.id} API（Web + Remote） story must reference at least two API IDs.`);
+      if (!frontend && !/\bAPI\b/i.test(trigger) && !new RegExp(`^不适用；.*触发方式为\\s*${trigger.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`).test(reference)) {
+        errors.push(`${detail.id} non-API story must use 不适用；触发方式为 ${trigger}.`);
+      }
+      if (frontend && !refs.length && !/^不适用；.+/.test(reference)) errors.push(`${detail.id} frontend story must list Method + Path or use 不适用； and explain why.`);
+      if (frontend && refs.length && !externalApi) errors.push(`${detail.id} lists Method + Path but no --api-doc input was supplied.`);
+      if (frontend) for (const signature of refs) if (!externalSignatures.has(signature)) errors.push(`${detail.id} references Method + Path not found in external API Documentation: ${signature}.`);
+      if (!frontend) for (const id of refs) if (!documentedApiIds.has(id)) errors.push(`${detail.id} references unknown API ID ${id}.`);
+      if (frontend) {
+        const upstreamSpec = frontendSpecs.find((item) => item.id === detail.id);
+        const targetRoute = field(upstreamSpec?.text ?? "", "页面路由") ?? "";
+        const routeDetail = fieldBlock(detail.text, "页面/路由");
+        if (/^不适用；/.test(targetRoute)) {
+          if (!/不适用/.test(routeDetail)) errors.push(`${detail.id} must preserve the Product Requirement non-route designation.`);
+        } else {
+          const path = targetRoute.match(/\/[^`\s；;，,]+/)?.[0];
+          if (path && !routeDetail.includes(path)) errors.push(`${detail.id} page route must match Product Requirement target ${path}.`);
+        }
+      }
     }
+    const risk = field(detail.text, "风险");
+    if (risk && !/^(?:无|不适用)$/.test(risk)) localRisks.push({ story: detail.id, text: risk });
   }
 }
 
@@ -127,6 +171,14 @@ const coverage = section(dependency.text, 2, "用户故事覆盖矩阵") ?? "";
 for (const story of [...frontendStories, ...backendStories]) {
   if (!coverage.includes(story.id)) errors.push(`Coverage matrix is missing ${story.id}.`);
   for (const ac of field(story.text, "验收标准")?.match(/AC-(?:FE|BE)-\d{3,}/g) ?? []) if (!coverage.includes(ac)) errors.push(`Coverage matrix is missing ${ac}.`);
+  for (const apiRef of storyApiRefs.get(story.id) ?? []) if (!coverage.includes(apiRef)) errors.push(`Coverage matrix is missing ${story.id} to ${apiRef} mapping.`);
+}
+
+if (externalApi && (scope === "frontend" || scope === "both")) {
+  const mapping = section(dependency.text, 2, "API 实现映射") ?? "";
+  for (const signature of [...storyApiRefs.entries()].filter(([id]) => id.startsWith("FE-US-")).flatMap(([, refs]) => refs)) {
+    if (!mapping.includes(signature)) errors.push(`API 实现映射 is missing frontend Method + Path ${signature}.`);
+  }
 }
 
 if (api) {
@@ -134,9 +186,15 @@ if (api) {
   for (const item of apiBlocks(api.text)) {
     const operation = tableValue(item.text, "Operation ID");
     const signature = item.text.match(/^>\s*`((?:GET|POST|PUT|PATCH|DELETE)\s+\/[^`]+)`/m)?.[1];
-    if (!mapping.includes(item.id)) errors.push(`API 实现映射 is missing ${item.id}.`);
-    if (operation && !mapping.includes(operation)) errors.push(`API 实现映射 is missing Operation ID ${operation}.`);
-    if (signature && !mapping.includes(signature)) errors.push(`API 实现映射 is missing ${signature}.`);
+    const mappingRow = mapping.split(/\r?\n/).find((line) => new RegExp(`^\\|\\s*${item.id}\\s*\\|`).test(line));
+    const cells = mappingRow?.split("|").slice(1, -1).map((cell) => cell.trim()) ?? [];
+    if (!mappingRow) errors.push(`API 实现映射 is missing ${item.id}.`);
+    if (operation && cells[1] !== operation) errors.push(`API 实现映射 is missing Operation ID ${operation}.`);
+    if (signature && cells[2] !== signature) errors.push(`API 实现映射 is missing ${signature}.`);
+    if (cells.length < 4 || !cells[3] || /^(?:F\d+|未知|未定位|N\/A|不适用)$/i.test(cells[3])) errors.push(`${item.id} must map to a concrete code entry.`);
+    if (![...storyApiRefs.values()].flat().includes(item.id)) errors.push(`${item.id} is orphaned; at least one API-backed story must reference it.`);
   }
 }
+const crossRisk = section(dependency.text, 2, "跨故事风险与未定位项") ?? "";
+for (const risk of localRisks) if (risk.text.length >= 6 && crossRisk.includes(risk.text)) errors.push(`${risk.story} risk is duplicated in 跨故事风险与未定位项.`);
 print("Dependency Analysis", dependency.path, errors);

package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { acceptanceBlocks, assertHeadings, containsUnresolvedBlockingPriority, field, load, metadata, outputSpecBlocks, print, scopeIncludes, section, storyBlocks, validateAcceptance, validateArtifactLocation } from "./validation-helpers.mjs";
+import { acceptanceBlocks, assertHeadings, field, load, metadata, outputSpecBlocks, print, scopeIncludes, section, storyBlocks, validateArtifactLocation, validateFrontmatter } from "./validation-helpers.mjs";
 
 const args = process.argv.slice(2);
 const fileArg = args[0];
@@ -15,62 +15,76 @@ try { artifact = load(fileArg, "Product Requirement"); }
 catch (error) { console.error(error.message); process.exit(2); }
 
 const errors = [];
+validateFrontmatter(artifact.text, ["artifact_version", "artifact_type", "requirement_id", "requirement_status", "analysis_scope"], errors, "Product Requirement");
 validateArtifactLocation(artifact, errors, "product-requirement.md");
 const version = metadata(artifact.text, "artifact_version");
 const upstreamScope = metadata(artifact.text, "analysis_scope");
 const scope = target ?? upstreamScope;
-if (!["2.0", "3.0"].includes(version)) errors.push("artifact_version must be 2.0 or 3.0.");
+if (!["2.0", "3.0", "4.0"].includes(version)) errors.push("artifact_version must be 2.0, 3.0, or 4.0.");
 if (metadata(artifact.text, "artifact_type") !== "product-requirement") errors.push("artifact_type must be product-requirement.");
 if (metadata(artifact.text, "requirement_status") !== "complete") errors.push("requirement_status must be complete.");
 if (!["frontend", "backend", "both"].includes(upstreamScope)) errors.push("analysis_scope must be frontend, backend, or both.");
 if (!["frontend", "backend", "both"].includes(scope)) errors.push("target must be frontend, backend, or both.");
 else if (!scopeIncludes(upstreamScope, scope)) errors.push(`target ${scope} is not included in upstream scope ${upstreamScope}.`);
 
-if (version === "3.0") {
-  assertHeadings(artifact.text, 2, ["需求概述", "业务目标", "需求范围", "业务规则", "决策追溯"], errors, "Product Requirement");
-  if (/^##\s+(?:\d+[.、]?\s*)?(?:用户角色|验收标准汇总)\s*$/m.test(artifact.text)) errors.push("V3 Product Requirement must not contain standalone 用户角色 or 验收标准汇总 sections.");
-} else {
-  assertHeadings(artifact.text, 2, ["需求背景", "需求摘要", "业务目标", "用户角色", "需求范围", "业务规则", "验收标准汇总", "决策追溯"], errors, "V2 Product Requirement");
+const allAcceptanceIds = [...artifact.text.matchAll(/^####\s+(AC-(?:FE|BE)-\d{3,})\s+/gm)].map((match) => match[1]);
+for (const id of new Set(allAcceptanceIds)) {
+  if (allAcceptanceIds.filter((value) => value === id).length > 1) errors.push(`Duplicate acceptance criterion ID: ${id}.`);
 }
-const range = section(artifact.text, 2, "需求范围") ?? "";
-assertHeadings(range, 3, ["已确认需求", "非目标", "默认假设", "未决事项"], errors, "需求范围");
-if (containsUnresolvedBlockingPriority(section(range, 3, "未决事项") ?? "")) errors.push("Product Requirement contains unresolved P0/P1 items.");
-
 function validateDomain(name) {
   const frontend = name === "frontend";
   const title = frontend ? "前端" : "后端";
   const prefix = frontend ? "FE-US" : "BE-US";
   const acPrefix = frontend ? "AC-FE" : "AC-BE";
-  const storyFields = version === "3.0"
-    ? (frontend ? ["角色", "目标", "价值", "入口", "验收标准"] : ["系统能力", "使用方", "业务价值", "触发方式", "验收标准"])
-    : (frontend ? ["用户角色", "用户目标", "页面/入口", "页面/组件", "展示内容", "交互动作", "UI 状态", "权限可见性", "前端边界处理", "验收标准"] : ["系统能力", "使用方", "触发方式", "输入语义", "输出语义", "数据读写", "权限规则", "业务规则", "安全要求", "后端边界处理", "验收标准"]);
-  assertHeadings(artifact.text, 2, [`${title}用户故事`, `${title}输出规范`], errors, "Product Requirement");
+  const structured = version === "3.0" || version === "4.0";
+  if (structured) assertHeadings(artifact.text, 2, [`${title}用户故事`, `${title}输出规范`], errors, "Product Requirement");
+  else assertHeadings(artifact.text, 2, [`${title}用户故事`], errors, "Product Requirement");
   const stories = storyBlocks(section(artifact.text, 2, `${title}用户故事`), prefix);
   if (!stories.length) errors.push(`Missing ${prefix}-* stories.`);
-  const specs = version === "3.0" ? outputSpecBlocks(section(artifact.text, 2, `${title}输出规范`), prefix) : [];
-  const specFields = frontend ? ["页面/组件", "展示内容", "交互动作", "UI 状态", "表单校验", "权限可见性", "边界处理"] : ["输入语义", "输出语义", "数据读写", "权限规则", "业务规则", "安全要求", "幂等与并发", "错误与边界"];
+  const specs = structured ? outputSpecBlocks(section(artifact.text, 2, `${title}输出规范`), prefix) : [];
   const seen = new Set();
   for (const story of stories) {
     if (seen.has(story.id)) errors.push(`Duplicate story ID: ${story.id}.`);
     seen.add(story.id);
-    for (const fieldName of storyFields) if (!field(story.text, fieldName)) errors.push(`${story.id} is missing field ${fieldName}.`);
-    if (!frontend && !/^(?:API|定时任务|事件|消息|内部调用|数据迁移)(?:$|[、,，/])/i.test(field(story.text, "触发方式") ?? "")) errors.push(`${story.id} 触发方式 is invalid.`);
-    const container = version === "3.0" ? specs.find((spec) => spec.id === story.id) : story;
+    if (!field(story.text, "验收标准")) errors.push(`${story.id} is missing field 验收标准.`);
+    const trigger = field(story.text, "触发方式") ?? "";
+    const apiTrigger = /^API[（(](?:Web|Remote|Web\s*\+\s*Remote)[）)]$/i.test(trigger);
+    if (!frontend && !apiTrigger && !/^(?:定时任务|事件|消息|内部调用|数据迁移)$/i.test(trigger)) errors.push(`${story.id} 触发方式 is invalid; API must declare Web, Remote, or Web + Remote.`);
+    const container = structured ? specs.find((spec) => spec.id === story.id) : story;
     if (!container) {
       errors.push(`Missing output specification for ${story.id}.`);
       continue;
     }
-    if (version === "3.0") for (const fieldName of specFields) if (!field(container.text, fieldName)) errors.push(`${story.id} output specification is missing field ${fieldName}.`);
+    if (structured && frontend) {
+      const route = field(container.text, "页面路由") ?? "";
+      if (!route) errors.push(`${story.id} output specification is missing field 页面路由.`);
+      else if (!/^`?\/[^`\s]+`?(?:\s|$|[；;，,])/.test(route) && !/^不适用；.+`?\/[^`\s]+`?.*页面/.test(route)) {
+        errors.push(`${story.id} 页面路由 must start with / or use 不适用； and name its containing page.`);
+      }
+    }
+    if (structured && !frontend && apiTrigger) {
+      for (const fieldName of ["输入语义", "输出语义", "权限规则", "业务规则", "安全要求", "错误与边界"]) {
+        if (!field(container.text, fieldName)) errors.push(`${story.id} API business contract is missing field ${fieldName}.`);
+      }
+    }
     const criteria = acceptanceBlocks(container, acPrefix);
     if (!criteria.length) errors.push(`${story.id} is missing embedded acceptance criteria.`);
     const actual = criteria.map((item) => item.id).sort();
     const referenced = [...(field(story.text, "验收标准") ?? "").matchAll(new RegExp(`${acPrefix}-\\d{3,}`, "g"))].map((item) => item[0]).sort();
     if (actual.join() !== referenced.join()) errors.push(`${story.id} acceptance references must match its embedded criteria.`);
-    for (const item of criteria) validateAcceptance(item.text, item.id, errors);
   }
-  if (version === "3.0") for (const spec of specs) if (!stories.some((story) => story.id === spec.id)) errors.push(`Output specification references unknown story ${spec.id}.`);
+  if (structured) for (const spec of specs) if (!stories.some((story) => story.id === spec.id)) errors.push(`Output specification references unknown story ${spec.id}.`);
 }
 
 if (scope === "frontend" || scope === "both") validateDomain("frontend");
 if (scope === "backend" || scope === "both") validateDomain("backend");
+
+if (version === "2.0") {
+  const backendStories = storyBlocks(section(artifact.text, 2, "后端用户故事"), "BE-US");
+  const hasApi = backendStories.some((story) => /\bAPI\b/i.test(field(story.text, "触发方式") ?? ""));
+  if ((scope === "backend" || scope === "both") && hasApi) {
+    errors.push("V2 Product Requirement with API-triggered stories must be upgraded to V4 before dependency/API analysis.");
+  }
+}
+
 print("Product Requirement input", artifact.path, errors);