@autobest-ui/agent 1.0.6 → 1.0.7

package/skills/common/ui-prd-scope/references/scope-schema.md

@@ -24,6 +24,7 @@
 ```json
 {
   "schemaVersion": 1,
+  "traceabilitySchemaVersion": 1,
   "prId": "<Azure PR ID>",
   "prUrl": "<完整 PR 链接>",
   "requestedPath": "<PR path 过滤条件或 null>",
@@ -33,6 +34,7 @@
     {
       "directory": "01-page-family",
       "pageFamily": "<页面族>",
+      "requirementPrefix": "PF",
       "decision": "<用户分类或合并/拆分依据>",
       "sourceFiles": ["/Frontend_APP/..."],
       "ragCoverage": {
@@ -41,7 +43,24 @@
         "emptyErrors": "no-hit",
         "permissions": "no-hit",
         "crossPage": "not-applicable"
-      }
+      },
+      "requirements": [
+        {
+          "id": "REQ-PF-001",
+          "statement": "<可独立确认、实现和验收的需求>",
+          "status": "active",
+          "sourceRefs": [
+            {
+              "type": "azure-prd",
+              "path": "/Frontend_APP/...",
+              "section": "<章节>"
+            }
+          ],
+          "figmaRefs": ["mobile-default.png#<节点或状态>"],
+          "ragRefs": ["<doc_id>#<规则>"],
+          "statusReason": null
+        }
+      ]
     }
   ],
   "unmappedSources": [],
@@ -57,6 +76,8 @@
 }
 ```
 
+`traceabilitySchemaVersion: 1` 表示该范围包启用需求追踪。`00-global` 可不声明 `requirementPrefix` 和 `requirements`；其他 scope 必须声明。编号、生命周期和刷新规则以 [requirement-traceability.md](requirement-traceability.md) 为准。旧范围包未声明 `traceabilitySchemaVersion` 时仍按旧契约读取，但进入 `review-from-docs` 前必须由本 Skill 刷新。
+
 每条 Figma 溯源记录必须指向 manifest 中已有的 scope 和实际存在的目标目录。默认使用 `operation: "copy"`，并要求源文件继续存在。只有用户明确要求移动时才能使用 `operation: "move"`。`operation: "legacy-move"` 与 `sourceStatus: "not-present-after-move"` 只用于审计本技能采用默认复制策略之前已移动的历史资产。
 
 ## 页面 Scope 模板
@@ -94,6 +115,12 @@
 
 - <PRD 变更边界>
 
+## 需求清单
+
+| 需求 ID | 状态 | 需求陈述 | PRD 来源 | Figma 证据 | RAG 证据 | 状态原因 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `REQ-PF-001` | `active` | <可独立确认、实现和验收的需求> | `<路径>#<章节>` | `<文件>#<节点/状态>` 或 `无` | `<doc_id>#<规则>` 或 `无` | - |
+
 ## 范围外
 
 - <明确排除或暂缓的页面>

package/skills/common/ui-prd-scope/scripts/validate-scope-bundle.mjs

@@ -19,6 +19,8 @@ const coverageStatuses = new Set([
   'not-applicable',
   'deferred-by-user'
 ]);
+const requirementIdPattern = /^REQ-([A-Z][A-Z0-9]{1,15})-\d{3}$/;
+const requirementStatuses = new Set(['active', 'deferred', 'removed']);
 
 const fail = message => errors.push(message);
 
@@ -43,6 +45,12 @@ if (fs.existsSync(manifestPath)) {
 }
 
 if (manifest) {
+  if (
+    manifest.traceabilitySchemaVersion !== undefined &&
+    manifest.traceabilitySchemaVersion !== 1
+  ) {
+    fail('Manifest traceabilitySchemaVersion 仅支持 1');
+  }
   for (const field of [
     'schemaVersion',
     'prId',
@@ -92,6 +100,9 @@ const scopeDirs = fs
 if (scopeDirs.length === 0) fail('没有找到包含 scope.md 的页面目录');
 
 const manifestScopes = new Map();
+const manifestRequirementIds = new Set();
+const manifestRequirementPrefixes = new Set();
+const traceabilityEnabled = manifest?.traceabilitySchemaVersion === 1;
 if (manifest && Array.isArray(manifest.scopes)) {
   for (const item of manifest.scopes) {
     if (!item || typeof item.directory !== 'string') {
@@ -123,6 +134,55 @@ if (manifest && Array.isArray(manifest.scopes)) {
         fail(`Manifest ${item.directory} 必须说明 RAG 暂缓原因`);
       }
     }
+    if (traceabilityEnabled && item.directory !== '00-global') {
+      if (!/^[A-Z][A-Z0-9]{1,15}$/.test(item.requirementPrefix || '')) {
+        fail(`Manifest ${item.directory} 的 requirementPrefix 格式无效`);
+      } else if (manifestRequirementPrefixes.has(item.requirementPrefix)) {
+        fail(`Manifest 包含重复 requirementPrefix：${item.requirementPrefix}`);
+      } else {
+        manifestRequirementPrefixes.add(item.requirementPrefix);
+      }
+      if (!Array.isArray(item.requirements) || item.requirements.length === 0) {
+        fail(`Manifest ${item.directory} 必须包含非空 requirements`);
+      } else {
+        for (const requirement of item.requirements) {
+          const id = requirement?.id;
+          const match = typeof id === 'string' ? id.match(requirementIdPattern) : null;
+          if (!match) {
+            fail(`Manifest ${item.directory} 包含无效需求 ID：${id}`);
+            continue;
+          }
+          if (match[1] !== item.requirementPrefix) {
+            fail(`Manifest ${item.directory} 的 ${id} 与 requirementPrefix 不一致`);
+          }
+          if (manifestRequirementIds.has(id)) {
+            fail(`Manifest 包含重复需求 ID：${id}`);
+          }
+          manifestRequirementIds.add(id);
+          if (!requirement.statement || typeof requirement.statement !== 'string') {
+            fail(`Manifest ${item.directory} 的 ${id} 缺少 statement`);
+          }
+          if (!requirementStatuses.has(requirement.status)) {
+            fail(`Manifest ${item.directory} 的 ${id} 状态无效：${requirement.status}`);
+          }
+          if (!Array.isArray(requirement.sourceRefs) || requirement.sourceRefs.length === 0) {
+            fail(`Manifest ${item.directory} 的 ${id} 缺少 sourceRefs`);
+          } else if (requirement.sourceRefs.some(ref =>
+            !ref || ref.type !== 'azure-prd' || typeof ref.path !== 'string' || !ref.path
+          )) {
+            fail(`Manifest ${item.directory} 的 ${id} 包含无效 sourceRefs`);
+          }
+          for (const field of ['figmaRefs', 'ragRefs']) {
+            if (!Array.isArray(requirement[field])) {
+              fail(`Manifest ${item.directory} 的 ${id} 缺少数组字段 ${field}`);
+            }
+          }
+          if (['deferred', 'removed'].includes(requirement.status) && !requirement.statusReason) {
+            fail(`Manifest ${item.directory} 的 ${id} 必须说明 statusReason`);
+          }
+        }
+      }
+    }
   }
 
   for (const dirName of scopeDirs) {
@@ -225,6 +285,50 @@ for (const dirName of scopeDirs) {
     if (!content.includes('合并依据：')) {
       fail(`${dirName}：缺少页面族合并依据`);
     }
+    if (traceabilityEnabled && !/^## 需求清单$/m.test(content)) {
+      fail(`${dirName}：缺少“需求清单”`);
+    }
+  }
+
+  if (traceabilityEnabled && !isGlobal) {
+    const traceableScope = manifestScopes.get(dirName);
+    const expectedIds = new Set((traceableScope?.requirements || []).map(item => item.id));
+    const allFoundIds = [...content.matchAll(/\bREQ-[A-Z][A-Z0-9]{1,15}-\d{3}\b/g)].map(
+      match => match[0]
+    );
+    const foundIdSet = new Set(allFoundIds);
+    const requirementHeading = '## 需求清单';
+    const requirementStart = content.indexOf(requirementHeading);
+    const requirementEnd = content.indexOf(
+      '\n## ',
+      requirementStart + requirementHeading.length
+    );
+    const requirementSection = requirementStart === -1
+      ? ''
+      : content.slice(
+          requirementStart + requirementHeading.length,
+          requirementEnd === -1 ? content.length : requirementEnd
+        );
+    const tableIds = [...requirementSection.matchAll(
+      /\bREQ-[A-Z][A-Z0-9]{1,15}-\d{3}\b/g
+    )].map(match => match[0]);
+    for (const id of expectedIds) {
+      if (!foundIdSet.has(id)) fail(`${dirName}：scope.md 缺少需求 ID ${id}`);
+      if (tableIds.filter(value => value === id).length !== 1) {
+        fail(`${dirName}：需求清单中的 ${id} 必须恰好出现一次`);
+      }
+    }
+    for (const id of foundIdSet) {
+      if (!expectedIds.has(id)) fail(`${dirName}：scope.md 包含 manifest 未声明的需求 ID ${id}`);
+    }
+    for (const requirement of traceableScope?.requirements || []) {
+      const row = requirementSection
+        .split('\n')
+        .find(line => line.includes(requirement.id));
+      if (row && !row.includes(`\`${requirement.status}\``)) {
+        fail(`${dirName}：需求清单中 ${requirement.id} 的状态与 manifest 不一致`);
+      }
+    }
   }
 
   for (const fields of [['Workspace', '工作区'], ['页面模块'], ['启动'], ['权限'], ['数据前置']]) {