npm - create-yss-spec - Versions diffs - 3.0.0 → 3.0.1 - Mend

create-yss-spec 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1508) hide show

package/template/.trae/skills/yss-prototype-stage/tests/run-scenarios.mjs CHANGED Viewed

@@ -3,152 +3,105 @@ import assert from "node:assert/strict";
 import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import {
-  preparePrototype,
-  validatePrototypeEvidence,
-  validatePrototypeProject
-} from "../scripts/prototype-contract.mjs";
+import { prepareFlowPrototype, prepareStaticPrototype, validatePrototypeEvidence, validatePrototypeProject } from "../scripts/prototype-contract.mjs";
 const tempRoot = await mkdtemp(path.join(os.tmpdir(), "yss-prototype-contract-"));
 const projectRoot = path.join(tempRoot, "project");
 const feature = "order-review";
-const prototypeRoot = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
-await mkdir(path.join(prototypeRoot, "src"), { recursive: true });
 await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify({
-  name: "order-review-prototype",
-  private: true,
-  type: "module",
-  scripts: { build: "vite build" },
-  dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" }
-}, null, 2));
-await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({
-  algorithm: "default",
-  token: {
-    colorPrimary: "#3371ff",
-    borderRadius: 6,
-    controlHeight: 32,
-    layoutHeaderHeight: 64
-  }
-}, null, 2));
+await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
-const before = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(before.errors.some((message) => message.includes("antd")), "RED: starter without antd must fail");
-assert(before.errors.some((message) => message.includes("pnpm-lock.yaml")), "RED: missing pnpm lockfile must fail");
+const h1Root = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
+await prepareStaticPrototype({ projectRoot, root: h1Root, feature });
+assert.match(await readFile(path.join(h1Root, "index.html"), "utf8"), /H1 · visual-review/);
+assert.deepEqual((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors, []);
+await writeFile(path.join(h1Root, "package.json"), "{}\n");
+assert((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors.some((message) => message.includes("package.json")), "H1 必须拒绝伪构建依赖");
-await preparePrototype({ projectRoot, root: prototypeRoot, feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
-const pkg = JSON.parse(await readFile(path.join(prototypeRoot, "package.json"), "utf8"));
-assert.equal(pkg.dependencies.antd, "6.6.2");
-assert.equal(pkg.packageManager, "pnpm@10.15.0");
-assert.match(await readFile(path.join(prototypeRoot, "src/yss-theme.js"), "utf8"), /compactAlgorithm/);
+const h2Feature = "approval-flow";
+const h2Root = path.join(projectRoot, "docs/.scratch", h2Feature, "design/prototypes");
+await mkdir(path.join(h2Root, "src"), { recursive: true });
+await writeFile(path.join(h2Root, "index.html"), "<!doctype html><div id=app></div>\n");
+await writeFile(path.join(h2Root, "package.json"), JSON.stringify({ name: "approval-flow-prototype", private: true, type: "module", scripts: { build: "vite build" }, dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" } }, null, 2));
+await prepareFlowPrototype({ projectRoot, root: h2Root, feature: h2Feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
+await writeFile(path.join(h2Root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+await writeFile(path.join(h2Root, "src/App.jsx"), 'import { ConfigProvider } from "antd"; import { yssTheme } from "./yss-theme.js"; export function App(){return <ConfigProvider theme={yssTheme}/>;}\n');
+assert.deepEqual((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.2" })).errors, []);
+assert((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.1" })).errors.some((message) => message.includes("精确锁定")));
-await writeFile(path.join(prototypeRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-await writeFile(path.join(prototypeRoot, "src/App.jsx"), [
-  'import { ConfigProvider, Button } from "antd";',
-  'import { yssTheme } from "./yss-theme.js";',
-  'export function App() { return <ConfigProvider theme={yssTheme}><Button type="primary">提交</Button></ConfigProvider>; }'
-].join("\n"));
-const after = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert.deepEqual(after.errors, []);
-const wrongTarget = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.1" });
-assert(wrongTarget.errors.some((message) => message.includes("精确锁定 antd 6.6.1")), "target 与实际 antd 版本不一致必须失败");
-const npmPackage = structuredClone(pkg);
-npmPackage.packageManager = "npm@11.0.0";
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(npmPackage, null, 2));
-const npmProject = await validatePrototypeProject({ root: prototypeRoot, targetAntdVersion: "6.6.2" });
-assert(npmProject.errors.some((message) => message.includes("packageManager")), "原型包管理器漂移到 npm 必须失败");
-await writeFile(path.join(prototypeRoot, "package.json"), JSON.stringify(pkg, null, 2));
-await assert.rejects(
-  preparePrototype({
-    projectRoot,
-    root: path.join(projectRoot, "prototypes", feature),
+function common(profile, kind, block) {
+  return {
+    schema_version: 3,
     feature,
-    targetAntdVersion: "6.6.2",
-    pnpmVersion: "10.15.0"
-  }),
-  /docs\/.scratch/,
-  "非标准原型目录必须被拒绝"
-);
-const validEvidence = {
-  schema_version: 2,
-  feature,
-  prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
-  prototype_stack: {
-    framework: "react",
-    package_manager: "pnpm",
-    package_manifest_ref: `docs/.scratch/${feature}/design/prototypes/package.json`,
-    lockfile_ref: `docs/.scratch/${feature}/design/prototypes/pnpm-lock.yaml`,
-    source_entry_ref: `docs/.scratch/${feature}/design/prototypes/src/App.jsx`,
-    build_entry_ref: `docs/.scratch/${feature}/design/prototypes/dist/index.html`,
-    build_command: "pnpm build",
-    build_result: "passed",
-    actual_antd_version: "6.6.2"
-  },
-  design_baseline: {
-    design_standard: "ant-design-v6",
-    project_design_ref: "docs/design/design.md",
-    project_token_refs: ["docs/design/tokens/theme.json"],
-    theme_adapter_ref: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`,
-    project_override_reviewed: true
-  },
-  visual_semantic_mapping: {
-    runtime_component_library: "ant-design-vue-4.x",
-    runtime_version_source: "implementation-lockfile",
-    components: [{
-      semantic_role: "primary-action",
-      antd_v6_component: "Button",
-      project_token_refs: ["colorPrimary"],
-      yss_or_antdv_target: "YButton",
-      state_mapping: ["default", "hover", "active", "disabled", "loading"],
-      react_only_api_not_copied: true,
-      verification_ref: "verification/button-states.png"
-    }]
-  },
-  antd: { target_antd_version: "6.6.2", queries: { design_md: "verification/antd-design.json", components: [] } },
-  browser_verification: { rendered_nonblank: true, viewports: [], main_flow_result: "passed", failure_permission_or_conflict_result: "passed", console_error_ref: "verification/console.txt" },
-  design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed" },
-  accessibility_verification: {
-    contrast_results_ref: "verification/contrast.json",
-    keyboard_navigation_result: "passed",
-    focus_visible_and_order_result: "passed",
-    semantic_label_dialog_result: "passed",
-    zoom_200_result: "passed",
-    reduced_motion_result: "passed",
-    target_size_result: "passed",
-    automated_scan: { tool: "axe", version: "4", result: "passed", ref: "verification/axe.json" }
-  },
-  review: { prototype_review_ref: "design/review.md", result: "approved" },
-  user_confirmation: { confirmation_ref: "design/confirmation.md", result: "approved" },
-  blockers: []
-};
-assert.deepEqual(validatePrototypeEvidence(validEvidence).errors, []);
-const missingMapping = structuredClone(validEvidence);
-delete missingMapping.visual_semantic_mapping;
-assert(validatePrototypeEvidence(missingMapping).errors.some((message) => message.includes("visual_semantic_mapping")));
+    prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
+    prototype_profile: profile,
+    profile_kind: kind,
+    profile_decision: {
+      decision_to_inform: "确认审批交互与状态",
+      risk_assumptions: ["状态必须可理解"],
+      trigger_results: [{ trigger: "visual-only", matched: profile === "H1", evidence_ref: "design/review.md" }],
+      calculated_profile: profile,
+      override: { applied: false, direction: "none", reason: "not-applicable", evidence_ref: "not-applicable" }
+    },
+    upstream_refs: { spec_ref: "spec.md", interaction_spec_ref: "interaction.md", low_fidelity_ref: "low.md", state_matrix_ref: "states.md", prototype_review_ref: "review.md" },
+    source_visual: { ideation_status: "not-applicable", selected_ref: "approved-pattern.md", reuse_reason: "复用已批准模式" },
+    design_baseline: { project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
+    browser_delivery: {
+      delivery_kind: "static-directory", entry_ref: `docs/.scratch/${feature}/design/prototypes/index.html`, rendered_nonblank: true, prototype_digest: "sha256:prototype",
+      viewports: [
+        { name: "desktop", size: "1440x900", result: "passed", screenshot_ref: "desktop.png" },
+        { name: "narrow", size: "390x844", result: "passed", screenshot_ref: "narrow.png" }
+      ],
+      console_result: "passed", console_ref: "console.txt"
+    },
+    design_qa: { report_ref: `docs/.scratch/${feature}/verification/design-qa.md`, result: "passed", axes: { visual: "passed", layout: "passed", interaction: "passed", content: "passed", accessibility: "passed", cross_platform: "passed" } },
+    profile_evidence: block,
+    implementation_handoff: {
+      prototype_code_reusable: false,
+      production_component_assumptions: ["YSS 组件可以表达已确认的交互语义"],
+      verification_targets: [{ behavior: "核验目标组件的真实 props/slots/events 与状态", target_stage: "frontend-implementation-plan" }]
+    },
+    review: { result: "approved", review_ref: "review.md" },
+    user_confirmation: { result: "approved", confirmation_ref: "confirmation.md", confirmed_decision: "接受当前设计", operable_scope: ["主操作"], simulations_or_gaps: [] },
+    gaps: [], blockers: []
+  };
+}
-const copiedReactApi = structuredClone(validEvidence);
-copiedReactApi.visual_semantic_mapping.components[0].react_only_api_not_copied = false;
-assert(validatePrototypeEvidence(copiedReactApi).errors.some((message) => message.includes("React-only")));
+const h1Evidence = common("H1", "visual-review", { visual_review: {
+  runtime_build_required: false, key_interactions_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed",
+  zoom_200: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" },
+  reduced_motion: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" }
+} });
+assert.deepEqual(validatePrototypeEvidence(h1Evidence).errors, []);
+const fakeH1 = structuredClone(h1Evidence);
+fakeH1.profile_evidence.visual_review.lockfile_ref = "pnpm-lock.yaml";
+assert(validatePrototypeEvidence(fakeH1).errors.some((message) => message.includes("H1 禁止字段")));
-const inaccessible = structuredClone(validEvidence);
-inaccessible.accessibility_verification.contrast_results_ref = "";
-assert(validatePrototypeEvidence(inaccessible).errors.some((message) => message.includes("contrast_results_ref")));
+const h2Evidence = common("H2", "flow-review", { flow_review: {
+  implementation: { framework: "react", runtime_build_required: true, package_manager: "pnpm", package_manifest_ref: "package.json", lockfile_ref: "pnpm-lock.yaml", build_command: "pnpm build", build_result: "passed" },
+  main_flow_result: "passed", exceptional_state_result: "passed", exceptional_state_ref: "conflict.png", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed",
+  visual_regression: { applicable: true, result: "passed", evidence_ref: "visual.json" },
+  prototype_library_facts: { applicable: true, component_basis: "react-antd-6", source: "fact-pack", actual_antd_version: "6.6.2", manifest_ref: "docs/design/facts/antd/6.6.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false }
+} });
+assert.deepEqual(validatePrototypeEvidence(h2Evidence).errors, []);
+const staleFacts = structuredClone(h2Evidence);
+staleFacts.profile_evidence.flow_review.prototype_library_facts.project_token_baseline_digest = "sha256:old";
+assert(validatePrototypeEvidence(staleFacts).errors.some((message) => message.includes("Token digest")));
+const fakeH3Claim = structuredClone(h2Evidence);
+fakeH3Claim.profile_evidence.flow_review.real_component_verified = true;
+assert(validatePrototypeEvidence(fakeH3Claim).errors.some((message) => message.includes("禁止生产组件字段")));
-const wrongQaRoot = structuredClone(validEvidence);
-wrongQaRoot.design_qa.report_ref = "docs/design/design-qa.md";
-assert(validatePrototypeEvidence(wrongQaRoot).errors.some((message) => message.includes("design_qa.report_ref")));
+const h3Evidence = common("H3", "component-contract", { component_contract: {
+  implementation_repo_ref: "repo:frontend", lockfile_ref: "pnpm-lock.yaml", framework: "vue-3", component_library: "@yss-ui/components", component_library_version: "4.2.1", harness_ref: "storybook-static/index.html", story_refs: ["stories/approval.stories.ts"], real_component_verified: true,
+  main_flow_result: "passed", exceptional_state_result: "passed", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed", automated_visual_regression: { result: "passed", evidence_ref: "visual-regression.json" }
+} });
+assert(validatePrototypeEvidence(h3Evidence).errors.some((message) => message.includes("H1/H2")), "H3 必须被原型合同拒绝");
-const versionMismatch = structuredClone(validEvidence);
-versionMismatch.antd.target_antd_version = "6.6.1";
-assert(validatePrototypeEvidence(versionMismatch).errors.some((message) => message.includes("target_antd_version")));
+const invalidHandoff = structuredClone(h2Evidence);
+invalidHandoff.implementation_handoff.verification_targets[0].target_stage = "prototype";
+assert(validatePrototypeEvidence(invalidHandoff).errors.some((message) => message.includes("前端实现阶段")));
-const unresolvedBlocker = structuredClone(validEvidence);
-unresolvedBlocker.blockers = ["缺少权限失败态"];
-assert(validatePrototypeEvidence(unresolvedBlocker).errors.some((message) => message.includes("blockers")));
+assert(validatePrototypeEvidence({ schema_version: 2 }).errors.some((message) => message.includes("只读旧证据")));
+assert.deepEqual(validatePrototypeEvidence({ schema_version: 2 }, { allowLegacy: true }).errors, []);
-process.stdout.write("YSS prototype contract scenarios passed\n");
+process.stdout.write("YSS prototype profile contract scenarios passed\n");

package/template/.trae/skills/yss-repository/SKILL.md CHANGED Viewed

@@ -43,7 +43,7 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 - Domain 不依赖 Infrastructure。
 - Gateway 定义在 Domain，实现放在 Infrastructure。
-- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 Router 回到 `yss-domain` / `yss-tactical-design`。
+- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 实现合同编译器 回到 `yss-domain` / `yss-tactical-design`。
 - Domain Gateway 只交换 Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，禁止返回 Web VO 或把 `PageQuery` 带入 Domain。
 - PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
 - Convertor 必须优先使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、`BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
@@ -74,7 +74,7 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 ## 阶段 7 合同
-- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 Router 返回 `blocked`。
+- 前置条件：数据架构、领域元数据、实现仓库和批准后的 `Slice Implementation Contract` 均可用；否则不执行本 skill，由 实现合同编译器 返回 `blocked`。
 - PO/Repository/Convertor 骨架可使用 `controlled-generation`；复杂过滤、分页语义、并发、事务和迁移行为必须拆为 `behavior-tdd`。
 - 写入仅限合同 `allowed_write_paths`，证据必须包含实际 PO、Repository、Convertor、GatewayImpl、测试和 `./mvnw ...` 结果。
 - 按统一 `YSS Skill Execution Result` 返回 `seam_deferred/deviations/new_impacts`；发现数据模型、DDL、SQL、索引或 API schema 变化时暂停并重路由。

package/template/.trae/skills/yss-resilience4j/SKILL.md CHANGED Viewed

@@ -11,7 +11,7 @@ Use this skill for YSS Resilience4j 组件. Keep implementation grounded in the
 ## Source Index First
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-resilience4j-starter`

package/template/.trae/skills/yss-resilience4j/references/source-index.md CHANGED Viewed

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.

package/template/.trae/skills/yss-security-algorithm/SKILL.md CHANGED Viewed

@@ -11,7 +11,7 @@ Use this skill for YSS 安全算法组件. Keep implementation grounded in the l
 ## Source Index First
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-security-algorithm`

package/template/.trae/skills/yss-security-algorithm/references/source-index.md CHANGED Viewed

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.

package/template/.trae/skills/yss-skill-source-index-refresh/SKILL.md ADDED Viewed

@@ -0,0 +1,63 @@
+---
+name: yss-skill-source-index-refresh
+description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
+---
+# YSS Skill Source Index Refresh
+Use this maintenance skill to keep YSS skills grounded in current source and documentation.
+中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
+## Source Location Policy
+- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
+- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
+- Frontend YSS UI components: `http://192.168.164.27:3200/components`
+- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
+- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
+## Refresh Workflow
+Run:
+```bash
+export YSS_SKILLS_ROOT="/path/to/.agents/skills"
+export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
+node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs"
+```
+Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
+The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
+中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
+If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
+## Output Contract
+Generated source indexes should contain:
+- source root and generated timestamp
+- exact source Git commit and worktree state
+- component directories and documentation files
+- Maven modules
+- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- recommended next reads for Agent when performing implementation or troubleshooting
+Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
+## Freshness Gate
+Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
+中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
+## After Refresh
+Validate the migrated Node helper with:
+```bash
+node --test "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs"
+```

package/template/.trae/skills/yss-skill-source-index-refresh/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Skill Source Index Refresh"
+  short_description: "Locate sources and refresh YSS skill indexes"
+  default_prompt: "Refresh YSS skill indexes from yss-cloud-microservice and YSS UI docs."

package/template/.trae/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs ADDED Viewed

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
+const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
+const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
+const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
+const exists=async p=>{try{await access(p);return true}catch{return false}};
+async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
+const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
+function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
+async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
+function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
+async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
+export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs\`. Do not hand-edit generated sections.`,``,`Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
+ if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
+ return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
+async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
+if(process.argv[1]===fileURLToPath(import.meta.url))await main();

package/template/.trae/skills/yss-ui/SKILL.md CHANGED Viewed

@@ -30,7 +30,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
-产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于原型设计构建，进入本技能后不得再调用。
+产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于相关 H2 React/AntD 原型；原型阶段不得调用本技能。只有进入前端实现计划、已批准切片的生产实现或实现还原验证后，才从目标 lockfile、类型、本地文档和既有用法取得真实组件事实。
 ## 3. 组件选型门禁
@@ -168,3 +168,4 @@ verification: pnpm type-check
 - 禁止把 React Ant Design v6 API 写入 Vue 生产代码。
 - 禁止引用不存在的 skill、未验证 Demo 或未冻结 API 契约。
 - 禁止省略错误、权限、空态、焦点和验证证据。
+- 禁止在原型阶段调用本技能，或用生产组件实现冒充原型资产。

package/template/.trae/skills/yss-ui/assets/docs/guide/llms.md CHANGED Viewed

@@ -110,67 +110,6 @@ Always reference the YSS UI documentation when working with components:
 ---
-### Gemini CLI
-在 Gemini CLI 中，可以通过 `--context` 参数或在 `.gemini/config.json` 中指定 LLMs.txt 文件路径。
-**使用方法 1：命令行参数**
-```bash
-gemini --context http://192.168.164.27:3200/llms-full.txt "如何使用 YTable 组件？"
-```
-**使用方法 2：配置文件**
-在项目根目录创建 `.gemini/config.json`：
-```json
-{
-  "context": [
-    "http://192.168.164.27:3200/llms-full.txt"
-  ]
-}
-```
-<a href="https://ai.google.dev/gemini-api/docs" target="_blank">详细了解 Gemini CLI 上下文配置</a>
----
-### Antigravity
-Antigravity（Google Gemini 官方 AI 编程助手）可以通过 `read_url_content` 工具直接读取在线文档。
-**方式 1：全局规则配置（强力推荐）** 🚀
-配置 `~/.gemini/GEMINI.md`，从根本上教会 AI "文档优先"，无需每次重复提示。
-```markdown
-## 核心原则：文档优先
-在回答关于 YSS UI 问题时，必须优先读取以下文档：
-http://192.168.164.27:3200/llms-full.txt
-```
-**方式 2：项目 README 配置**
-在项目根目录 `README.md` 中添加文档链接，Antigravity 读取项目概况时会自动发现。
-```markdown
-## 相关文档
-- YSS UI: http://192.168.164.27:3200/llms-full.txt
-```
-**方式 3：对话直接引用**
-临时询问时，直接在对话中粘贴 URL：
-```
-参考文档 http://192.168.164.27:3200/llms-full.txt，帮我写一个表格。
-```
-> **提示**：Antigravity 不支持类似 Cursor `@Docs` 的配置，主要依靠上下文理解和工具调用。
----
 ### Trae
 在 Trae 中，将 LLMs.txt 文件放入项目的 knowledge sources 并在设置里开启引用。

package/template/.trae/skills/yss-up-springboot3/SKILL.md CHANGED Viewed

@@ -21,7 +21,7 @@ Use this skill for YSS backend upgrade analysis and migration tasks around Sprin
 2. Check for Jakarta namespace changes (`javax.servlet`, `javax.validation`, `javax.annotation`, JPA APIs, and related imports).
 3. Check Spring Security configuration style, deprecated adapters, authorization server dependencies, and filter registration behavior.
 4. Check component-specific integration by loading specialist skills such as `yss-mybatis`, `yss-dto`, `yss-cache`, `yss-audit-log`, `yss-excel-mvc`, or `yss-jdbc`.
-5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-source-index/references/source-location.md` before recommending code changes.
+5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-skill-source-index-refresh/references/source-location.md` before recommending code changes.
 6. Produce an upgrade checklist or patch with explicit compatibility risks and verification commands.
 ## Common Checks

package/template/.trae/skills/yss-userinfo/SKILL.md CHANGED Viewed

@@ -11,7 +11,7 @@ Use this skill for YSS 用户信息组件. Keep implementation grounded in the l
 ## Source Index First
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-userinfo-starter`

package/template/.trae/skills/yss-userinfo/references/source-index.md CHANGED Viewed

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.

package/template/.trae/skills/yss-validation/SKILL.md CHANGED Viewed

@@ -11,7 +11,7 @@ Use this skill for YSS 校验组件. Keep implementation grounded in the local p
 ## Source Index First
-- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
 - Component path hints: `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303`

package/template/.trae/skills/yss-validation/references/source-index.md CHANGED Viewed

@@ -5,7 +5,7 @@ Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.

package/template/.trae/skills/yss-web-controller/SKILL.md CHANGED Viewed

@@ -16,7 +16,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 Router 补 `yss-application` / `yss-domain` 和相应合同输入。
+- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 实现合同编译器 补 `yss-application` / `yss-domain` 和相应合同输入。
 ## 优先流程
@@ -82,4 +82,4 @@ node scripts/generate_controller.mjs \
 - 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
-- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。
+- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 实现合同编译器/生命周期。