@autobest-ui/agent 1.0.0

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

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = path.resolve(process.argv[2] || '.scratch/page-scope');
+const errors = [];
+const warnings = [];
+const coverageAreas = [
+  'businessRules',
+  'statesTransitions',
+  'emptyErrors',
+  'permissions',
+  'crossPage'
+];
+const coverageStatuses = new Set([
+  'hit',
+  'no-hit',
+  'not-applicable',
+  'deferred-by-user'
+]);
+
+const fail = message => errors.push(message);
+
+if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+  console.error(`Scope 根目录不存在：${root}`);
+  process.exit(1);
+}
+
+const readmePath = path.join(root, 'README.md');
+const manifestPath = path.join(root, 'scope-manifest.json');
+
+if (!fs.existsSync(readmePath)) fail('缺少根目录 README.md 索引');
+if (!fs.existsSync(manifestPath)) fail('缺少 scope-manifest.json');
+
+let manifest = null;
+if (fs.existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    fail(`scope-manifest.json 无效：${error.message}`);
+  }
+}
+
+if (manifest) {
+  for (const field of [
+    'schemaVersion',
+    'prId',
+    'prUrl',
+    'requestedPath',
+    'ragPlatform',
+    'changedSources',
+    'scopes',
+    'unmappedSources',
+    'figmaSources'
+  ]) {
+    if (!(field in manifest)) fail(`Manifest 缺少字段 ${field}`);
+  }
+  if (!/^https:\/\//.test(manifest.prUrl || '')) fail('Manifest prUrl 必须是 HTTPS 链接');
+  if (!Array.isArray(manifest.scopes)) fail('Manifest scopes 必须是数组');
+  if (!Array.isArray(manifest.changedSources) || manifest.changedSources.length === 0) {
+    fail('Manifest changedSources 必须是非空数组');
+  }
+  if (!Array.isArray(manifest.unmappedSources)) {
+    fail('Manifest unmappedSources 必须是数组');
+  }
+  if (!Array.isArray(manifest.figmaSources)) {
+    fail('Manifest figmaSources 必须是数组');
+  }
+  if (Array.isArray(manifest.changedSources)) {
+    const uniqueSources = new Set(manifest.changedSources);
+    if (uniqueSources.size !== manifest.changedSources.length) {
+      fail('Manifest changedSources 包含重复项');
+    }
+  }
+  if (Array.isArray(manifest.unmappedSources)) {
+    for (const item of manifest.unmappedSources) {
+      if (!item || typeof item.path !== 'string' || !item.reason) {
+        fail('每个未映射来源都必须包含 path 和 reason');
+      }
+    }
+  }
+}
+
+const scopeDirs = fs
+  .readdirSync(root, { withFileTypes: true })
+  .filter(entry => entry.isDirectory())
+  .map(entry => entry.name)
+  .filter(name => fs.existsSync(path.join(root, name, 'scope.md')))
+  .sort();
+
+if (scopeDirs.length === 0) fail('没有找到包含 scope.md 的页面目录');
+
+const manifestScopes = new Map();
+if (manifest && Array.isArray(manifest.scopes)) {
+  for (const item of manifest.scopes) {
+    if (!item || typeof item.directory !== 'string') {
+      fail('Manifest scope 缺少 directory');
+      continue;
+    }
+    if (manifestScopes.has(item.directory)) {
+      fail(`Manifest 包含重复 scope：${item.directory}`);
+    }
+    manifestScopes.set(item.directory, item);
+    if (!item.pageFamily) fail(`Manifest ${item.directory} 缺少 pageFamily`);
+    if (!item.decision) fail(`Manifest ${item.directory} 缺少 decision`);
+    if (!Array.isArray(item.sourceFiles) || item.sourceFiles.length === 0) {
+      fail(`Manifest ${item.directory} 缺少 sourceFiles`);
+    }
+    if (!item.ragCoverage || typeof item.ragCoverage !== 'object') {
+      fail(`Manifest ${item.directory} 缺少 ragCoverage`);
+    } else {
+      for (const area of coverageAreas) {
+        const status = item.ragCoverage[area];
+        if (!coverageStatuses.has(status)) {
+          fail(`Manifest ${item.directory} 的 ${area} 覆盖状态无效：${status}`);
+        }
+      }
+      if (
+        Object.values(item.ragCoverage).includes('deferred-by-user') &&
+        !item.ragDeferralReason
+      ) {
+        fail(`Manifest ${item.directory} 必须说明 RAG 暂缓原因`);
+      }
+    }
+  }
+
+  for (const dirName of scopeDirs) {
+    if (!manifestScopes.has(dirName)) fail(`Manifest 未索引 ${dirName}`);
+  }
+  for (const dirName of manifestScopes.keys()) {
+    if (!scopeDirs.includes(dirName)) fail(`Manifest 索引了不存在的 scope：${dirName}`);
+  }
+
+  if (Array.isArray(manifest.changedSources)) {
+    const mappedSources = new Set(
+      manifest.scopes.flatMap(item =>
+        Array.isArray(item.sourceFiles) ? item.sourceFiles : []
+      )
+    );
+    const unmappedSources = new Set(
+      Array.isArray(manifest.unmappedSources)
+        ? manifest.unmappedSources.map(item =>
+            typeof item === 'string' ? item : item && item.path
+          )
+        : []
+    );
+    for (const source of manifest.changedSources) {
+      if (!mappedSources.has(source) && !unmappedSources.has(source)) {
+        fail(`变更来源既未映射也未明确标记为未映射：${source}`);
+      }
+    }
+  }
+
+  if (Array.isArray(manifest.figmaSources)) {
+    for (const item of manifest.figmaSources) {
+      if (!item || !manifestScopes.has(item.scope)) {
+        fail(`Figma 溯源引用了未知 scope：${item && item.scope}`);
+        continue;
+      }
+      if (!item.source || !item.destination || !item.operation || !item.sourceStatus) {
+        fail(`${item.scope} 的 Figma 溯源信息不完整`);
+        continue;
+      }
+      const source = path.resolve(process.cwd(), item.source);
+      const destination = path.resolve(process.cwd(), item.destination);
+      if (!fs.existsSync(destination)) {
+        fail(`${item.scope} 的 Figma 目标目录不存在：${item.destination}`);
+      }
+      if (item.operation === 'copy' && !fs.existsSync(source)) {
+        fail(`${item.scope} 的 Figma 复制源不存在：${item.source}`);
+      } else if (item.operation === 'legacy-move') {
+        if (item.sourceStatus !== 'not-present-after-move') {
+          fail(`${item.scope} 的历史 Figma 移动记录包含无效 sourceStatus`);
+        }
+      } else if (!['copy', 'move'].includes(item.operation)) {
+        fail(`${item.scope} 的 Figma 溯源 operation 无效：${item.operation}`);
+      }
+    }
+  }
+}
+
+const readme = fs.existsSync(readmePath)
+  ? fs.readFileSync(readmePath, 'utf8')
+  : '';
+
+for (const match of readme.matchAll(/\]\(\.\/([^/]+)\/scope\.md\)/g)) {
+  if (!scopeDirs.includes(match[1])) {
+    fail(`README 链接指向缺失或失效的 scope：${match[1]}/scope.md`);
+  }
+}
+
+for (const dirName of scopeDirs) {
+  const dir = path.join(root, dirName);
+  const scopePath = path.join(dir, 'scope.md');
+  const content = fs.readFileSync(scopePath, 'utf8');
+  const isGlobal = dirName === '00-global';
+
+  if (!readme.includes(`./${dirName}/scope.md`)) {
+    fail(`README 未链接 ${dirName}/scope.md`);
+  }
+
+  if (!/^# .+(?:Scope|范围)$/m.test(content)) fail(`${dirName}：缺少 H1 Scope/范围标题`);
+  if (!/^## 项目运行与访问$/m.test(content)) {
+    fail(`${dirName}：缺少“项目运行与访问”`);
+  }
+  if (!/^## RAG 补充/m.test(content)) fail(`${dirName}：缺少“RAG 补充”`);
+  if (!/^## 待质询$/m.test(content)) fail(`${dirName}：缺少“待质询”`);
+
+  if (!isGlobal) {
+    for (const heading of ['需求来源', '页面族', '改动范围', '范围外', 'Figma 输入']) {
+      if (!new RegExp(`^## ${heading}$`, 'm').test(content)) {
+        fail(`${dirName}：缺少“${heading}”`);
+      }
+    }
+    if (!content.includes('- Azure PR: https://')) {
+      fail(`${dirName}：缺少 Azure PR 链接`);
+    }
+    if (manifest && !content.includes(`- Azure PR: ${manifest.prUrl}`)) {
+      fail(`${dirName}：Azure PR 链接与 manifest 不一致`);
+    }
+    if (!content.includes('- Evidence type: `') && !content.includes('- 证据类型：`')) {
+      fail(`${dirName}：缺少证据类型`);
+    }
+    if (!content.includes('合并依据：')) {
+      fail(`${dirName}：缺少页面族合并依据`);
+    }
+  }
+
+  for (const fields of [['Workspace', '工作区'], ['页面模块'], ['启动'], ['权限'], ['数据前置']]) {
+    if (!fields.some(field => content.includes(`| ${field} |`))) {
+      fail(`${dirName}：运行信息表缺少 ${fields.join('/')}`);
+    }
+  }
+  if (!/^\| .*URL \|/m.test(content) && !content.includes('http://localhost:')) {
+    fail(`${dirName}：运行信息表缺少 URL 上下文`);
+  }
+
+  if (
+    !content.includes('| Query focus | Filters | Result |') &&
+    !content.includes('| 查询重点 | 过滤条件 | 结果 |')
+  ) {
+    fail(`${dirName}：缺少 RAG 查询台账`);
+  }
+  if (
+    !content.includes('| Coverage area | Status |') &&
+    !content.includes('| 覆盖领域 | 状态 |')
+  ) {
+    fail(`${dirName}：缺少 RAG 覆盖表`);
+  }
+  const manifestScope = manifestScopes.get(dirName);
+  if (manifestScope && manifestScope.ragCoverage) {
+    for (const area of coverageAreas) {
+      const status = manifestScope.ragCoverage[area];
+      if (!content.includes(`| ${area} | \`${status}\` |`)) {
+        fail(`${dirName}：RAG 覆盖表中的 ${area} 与 manifest 不一致`);
+      }
+    }
+  }
+  if (!content.includes('platform=')) fail(`${dirName}：RAG 查询台账缺少 platform`);
+  if (!/doc_id|no hit|未命中/i.test(content)) {
+    fail(`${dirName}：RAG 证据缺少 doc_id 或未命中结果`);
+  }
+
+  for (const match of content.matchAll(/\]\(\.\/([^\)]+)\)/g)) {
+    const target = path.resolve(dir, match[1]);
+    if (!fs.existsSync(target)) fail(`${dirName}：本地链接无效 ${match[1]}`);
+  }
+
+  const files = fs.readdirSync(dir);
+  const assetFiles = files.filter(name => /\.(json|png)$/i.test(name));
+  const pngFiles = new Set(files.filter(name => name.endsWith('.png')));
+
+  for (const assetName of assetFiles) {
+    if (!content.includes(`./${assetName}`)) {
+      fail(`${dirName}：资产未在 scope.md 中声明：${assetName}`);
+    }
+  }
+
+  for (const jsonName of assetFiles.filter(name => name.endsWith('.json'))) {
+    try {
+      JSON.parse(fs.readFileSync(path.join(dir, jsonName), 'utf8'));
+    } catch (error) {
+      fail(`${dirName}：JSON 无效 ${jsonName}：${error.message}`);
+    }
+    const expectedPng = jsonName.replace(/\.json$/, '.png');
+    if (!pngFiles.has(expectedPng)) {
+      warnings.push(`${dirName}：JSON 缺少同名 PNG：${jsonName}`);
+    }
+  }
+
+  if (!isGlobal && assetFiles.length === 0) {
+    warnings.push(`${dirName}：没有同目录 Figma 资产；scope 必须明确缺失采集物的负责人`);
+  }
+}
+
+for (const warning of warnings) console.warn(`警告 ${warning}`);
+for (const error of errors) console.error(`错误 ${error}`);
+console.log(
+  `已检查 ${scopeDirs.length} 个 scope 目录：${errors.length} 个错误，${warnings.length} 个警告`
+);
+process.exit(errors.length === 0 ? 0 : 1);

package/skills/react/react-code-standards/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: react-code-standards
+description: 实现或修改 React 业务代码时使用的仓库感知编码标准，约束技术栈识别、组件范式、TypeScript 类型、SCSS 组织、核心路径注释和组件库复用。适用于新增功能、缺陷修复、重构及 UI 实现；仓库真实配置和局部规范优先于本 skill 的默认技术栈。
+metadata:
+  version: "1.0"
+---
+
+# React 业务代码标准
+
+## 执行顺序
+
+1. 实现前读取适用范围内的 `AGENTS.md`，并检查目标包的 `package.json`、`tsconfig.json`、现有依赖、相邻组件和样式组织。以仓库真实环境、既有公共 API 和局部惯例为准；它们覆盖本文件的默认值。
+2. 识别可复用的 `@autobest-ui/*` 组件和工具，以及仓库已有的业务组件、类型、状态管理和样式模式。现有能力满足需求时直接复用；只有确实无法满足时才新增自定义实现。
+3. 按下列标准完成最小范围的业务代码改动，并执行仓库规定的 lint、类型检查或构建验证。
+4. 完成前检查所有新增或修改的核心业务路径均有必要注释，类型覆盖实际边界，逻辑与样式保持分离，并在最终响应中说明验证结果和未覆盖风险。
+
+## 技术栈
+
+以下是仓库未明确指定时的默认值，不用于覆盖真实配置：
+
+- React 16.8 或更高版本；只使用当前仓库 React 版本支持的 API。
+- TypeScript 严格类型约束。
+- SCSS。
+- Redux。
+- 组件与工具库：`@autobest-ui/components`、`@autobest-ui/ajax`、`@autobest-ui/utils`。
+
+不得为套用默认栈而升级依赖、切换框架或引入新的状态管理、请求、样式或组件方案。
+
+## 组件范式
+
+- 业务逻辑复杂、状态较多、依赖生命周期或包含多个副作用时，优先使用 Class 类组件，并沿用仓库现有生命周期和状态组织方式。
+- 组件仅负责简单展示或逻辑极简，且没有复杂状态与生命周期时，可以使用函数组件和当前 React 版本支持的 Hooks。
+- 修改现有组件时优先保持其既有范式；只有当前范式明显无法承载需求且变更范围已获授权时才转换组件类型。
+- 拆分组件应形成清晰的业务或复用边界，不为缩短文件机械拆分，也不把跨组件业务状态藏入展示组件。
+
+## TypeScript
+
+- 为 Props、函数入参、业务数据结构和对外返回值声明显式 `interface`；既有项目明确使用 `type` 表达联合、映射等结构时沿用该惯例。
+- 类型应覆盖可选字段、可空值、业务状态和边界枚举，使异常或缺失数据在类型与实现中都有对应处理。
+- 优先通过类型收窄、泛型或领域类型表达不确定性。未知外部数据先使用 `unknown` 并在边界处校验；仅在第三方声明缺失且无法合理建模时局部使用 `any`，同时说明原因。
+- 对网络响应、路由参数、存储数据和跨模块输入进行边界校验，不把类型断言当作运行时校验。
+- 遵循仓库实际 `tsconfig` 和既有编译目标；默认按严格模式编写，即使目标包尚未开启全部严格选项，也不主动扩大弱类型区域。
+
+## 代码与样式组织
+
+- 业务逻辑、状态处理和数据转换放在 `.tsx` / `.ts` 文件；样式放在独立 SCSS 文件，并沿用当前包的 CSS Modules、命名和导入方式。
+- 优先使用样式类表达稳定视觉规则。只有值由运行时数据计算且现有样式机制无法表达时才使用局部内联样式。
+- 类型、业务逻辑和样式按职责组织。共享或复杂业务类型应放在相邻的类型模块中；组件私有且短小的 Props 可以与组件入口共置。
+- 保持现有目录、导出、Redux 和请求层边界，不在局部实现中建立平行架构。
+
+## 注释与代码输出
+
+交付可维护的业务实现，不只提供脱离仓库的裸代码。注释应解释意图、数据流和约束，避免逐行复述语法。
+
+每个新增模块或组件入口应有简短用途说明。核心业务路径的注释必须覆盖其中实际存在的内容：
+
+- 入参边界校验和异常兜底为何这样处理；
+- 关键数据从请求、Props 或 Redux 到状态及 UI 的流向；
+- 容易误判的边界条件和异常场景；
+- 复杂业务中的关键假设、外部约束和潜在风险。
+
+简单赋值、显然的 JSX 和类型声明无需叙述性注释。实现变化后同步更新相关注释，确保注释描述当前行为。
+
+## 组件与工具复用
+
+- 搜索并优先使用 `@autobest-ui/components` 的现成组件及仓库已有业务组件，保持其 Props、交互和样式约定。
+- 请求优先使用 `@autobest-ui/ajax` 或仓库对它的既有封装；通用处理优先使用 `@autobest-ui/utils` 或仓库已有工具。
+- 新建自定义组件或工具前，确认现有实现无法通过受支持的组合或扩展点满足需求。新增实现应保持单一职责，并避免复制已有组件的核心能力。
+- 不猜测组件库 API。通过仓库调用点、类型声明或可用文档确认用法后再实现。
+
+## 完成标准
+
+- 仓库配置、目标模块惯例与本标准之间的优先级已正确处理。
+- 组件范式与业务复杂度匹配，且兼容仓库当前 React 版本。
+- Props、边界输入、业务数据和返回值具有明确类型，外部数据经过必要校验。
+- 逻辑与 SCSS 分离，复用了可用的 `@autobest-ui/*` 或仓库现有能力。
+- 核心业务路径具有准确、必要的注释，复杂假设和风险已被说明。
+- 已按仓库要求完成与改动范围相称的验证，并如实报告结果。

package/skills/react/react-code-standards/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "React Code Standards"
+  short_description: "Apply repository-aware standards to React business code"
+  default_prompt: "Use $react-code-standards to implement this React business change according to the repository stack and coding conventions."