create-yss-spec 2.1.11 → 2.1.14

package/template/.agents/skills/llm-wiki/scripts/lint-wikilinks.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXTRACT_KINDS } from "./extract.mjs";
+import { exists, sha256 } from "./inventory.mjs";
+
+export const INFRA = new Set([
+  "index.md",
+  "log.md",
+  "claude.md",
+  "agents.md",
+  "soul.md",
+  "concept-table.md",
+]);
+const WIKILINK_RE = /\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g;
+const SOURCE_HEADING_RE = /^##\s+来源\s*$/m;
+const H1_RE = /^#\s+(.+?)\s*$/m;
+
+export function articlesDir(wikiRoot) {
+  return path.join(wikiRoot, "wiki");
+}
+
+export function extractLinks(text) {
+  const ids = [];
+  const invalid = [];
+  WIKILINK_RE.lastIndex = 0;
+  let match;
+  while ((match = WIKILINK_RE.exec(text))) {
+    const target = match[1].trim();
+    if (!target) continue;
+    if (target.startsWith("../") || target.includes("/")) {
+      invalid.push(target);
+      continue;
+    }
+    ids.push(target);
+  }
+  return { ids, invalid };
+}
+
+export async function lintWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+  const dir = articlesDir(wikiRoot);
+  if (!(await exists(path.join(dir, "index.md")))) {
+    return { ok: false, errors: [`missing ${path.join(dir, "index.md")}`], counts: {} };
+  }
+  const names = (await readdir(dir)).filter((name) => name.endsWith(".md"));
+  const articleFiles = names.filter((name) => !INFRA.has(name.toLowerCase()));
+  const articleIds = new Set(articleFiles.map((name) => name.slice(0, -3)));
+  const errors = [];
+  let linkCount = 0;
+
+  const indexText = await readFile(path.join(dir, "index.md"), "utf8");
+  const indexLinks = extractLinks(indexText);
+  linkCount += indexLinks.ids.length;
+  for (const target of indexLinks.invalid) errors.push(`CROSS-WIKI (index): [[${target}]]`);
+  const indexed = new Set();
+  for (const id of indexLinks.ids) {
+    indexed.add(id);
+    if (!articleIds.has(id)) errors.push(`MISSING (index): [[${id}]]`);
+  }
+
+  for (const file of articleFiles) {
+    const id = file.slice(0, -3);
+    const text = await readFile(path.join(dir, file), "utf8");
+    const heading = text.match(H1_RE);
+    if (!heading || heading[1] !== id) errors.push(`H1 MISMATCH: ${file} expected # ${id}`);
+    if (!SOURCE_HEADING_RE.test(text)) errors.push(`NO SOURCE SECTION: ${file}`);
+    if (!indexed.has(id)) errors.push(`ORPHAN: ${file}`);
+    const links = extractLinks(text);
+    for (const target of links.invalid) errors.push(`CROSS-WIKI: ${file} -> [[${target}]]`);
+    for (const target of links.ids) {
+      linkCount += 1;
+      if (!articleIds.has(target)) errors.push(`MISSING: ${file} -> [[${target}]]`);
+    }
+  }
+
+  const manifestFile = path.join(wikiRoot, ".wiki-manifest.json");
+  if (await exists(manifestFile)) {
+    const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+    const sourceById = new Map();
+    for (const source of manifest.sources || []) {
+      if (source?.id) sourceById.set(source.id, source);
+    }
+    const listedFiles = new Set();
+    for (const article of manifest.articles || []) {
+      const rel = path.posix.normalize(article.file || "");
+      listedFiles.add(rel);
+      const expectedId = path.posix.basename(rel, ".md");
+      if (article.id !== expectedId) {
+        errors.push(`MANIFEST ID MISMATCH: ${article.file} id=${article.id} expected ${expectedId}`);
+      }
+      const file = path.resolve(wikiRoot, article.file);
+      if (!(await exists(file))) errors.push(`MANIFEST ARTICLE MISSING: ${article.file}`);
+      for (const sourceId of article.sourceIds || []) {
+        if (!sourceById.has(sourceId)) {
+          errors.push(`UNKNOWN SOURCE ID: ${article.id} -> ${sourceId}`);
+        }
+      }
+    }
+    for (const file of articleFiles) {
+      const rel = path.posix.join("wiki", file);
+      if (!listedFiles.has(rel)) errors.push(`UNLISTED ARTICLE: ${file}`);
+    }
+    for (const source of manifest.sources || []) {
+      if (manifest.profile === "documents" && source.kind === "code-surface") {
+        errors.push(`PROFILE KIND: documents forbids code-surface (${source.id})`);
+      }
+      if (source.kind === "document" || source.kind === "derived") {
+        if (!source.rawPath) {
+          errors.push(`RAW PATH REQUIRED: ${source.id} (${source.kind})`);
+        } else {
+          const raw = path.resolve(wikiRoot, source.rawPath);
+          if (!(await exists(raw))) errors.push(`RAW MISSING: ${source.id} (${source.rawPath})`);
+        }
+      }
+      if (source.kind === "derived") {
+        const extractKind = source.extract?.kind;
+        if (!extractKind) errors.push(`EXTRACT REQUIRED: ${source.id}`);
+        else if (!EXTRACT_KINDS.includes(extractKind)) {
+          errors.push(`EXTRACT KIND: ${source.id} (${extractKind})`);
+        }
+      }
+      if (source.kind === "code-surface" && source.rawPath != null) {
+        errors.push(`RAW PATH FORBIDDEN: ${source.id} (code-surface)`);
+      }
+      if (!source.livePath) continue;
+      const live = path.resolve(repoRoot, source.livePath);
+      if (!(await exists(live))) {
+        errors.push(`MANIFEST SOURCE MISSING: ${source.id} (${source.livePath})`);
+        continue;
+      }
+      const current = sha256(await readFile(live));
+      if (!source.sha256 || current !== source.sha256) {
+        errors.push(`STALE HASH: ${source.id} (${source.livePath})`);
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    counts: { articles: articleFiles.length, links: linkCount },
+  };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let wikiArg;
+  let repoRoot = process.cwd();
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--repo") repoRoot = argv[++i];
+    else if (!wikiArg && !argv[i].startsWith("-")) wikiArg = argv[i];
+  }
+  repoRoot = path.resolve(repoRoot);
+  if (!wikiArg) {
+    throw new Error("usage: lint-wikilinks.mjs <wiki-root> [--repo <repo-root>]");
+  }
+  const wikiRoot = path.resolve(repoRoot, wikiArg);
+  const result = await lintWiki(wikiRoot, { repoRoot });
+  for (const error of result.errors) process.stdout.write(`${error}\n`);
+  process.stdout.write(
+    `校验完成：${result.counts.articles || 0} 篇文章，${result.counts.links || 0} 条 wikilink\n`,
+  );
+  if (result.ok) process.stdout.write("通过：所有 wikilink / 来源 / 索引检查通过\n");
+  else {
+    process.stdout.write(
+      "失败：存在缺失的 wikilink、孤儿页、来源小节、跨路径链接、H1 或 manifest 闭合问题\n",
+    );
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/template/.agents/skills/llm-wiki/scripts/lint-wikilinks.test.mjs

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "./inventory.mjs";
+import { lintWiki } from "./lint-wikilinks.mjs";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const broken = path.join(skillRoot, "assets/fixtures/broken-wiki");
+
+test("broken fixture fails on dangling wikilink", async () => {
+  const result = await lintWiki(broken);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("[[不存在的页]]")));
+});
+
+test("complete wiki passes wikilink, index, and source-section checks", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-lint-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(
+    path.join(wiki, "index.md"),
+    "# index\n\n## 分类\n\n- [[Alpha]]\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  await writeFile(path.join(wiki, "CLAUDE.md"), "# schema\n", "utf8");
+  const result = await lintWiki(root);
+  assert.equal(result.ok, true, result.errors.join("\n"));
+  assert.equal(result.counts.articles, 1);
+});
+
+test("cross-path wikilink fails instead of being ignored", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-cross-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[../other]]\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const result = await lintWiki(root);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("CROSS-WIKI") && line.includes("[[../other]]")));
+});
+
+test("manifest sha256 mismatch is stale", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-hash-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(wikiRoot, "raw"), { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v2\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[API]]\n", "utf8");
+  await writeFile(path.join(wiki, "API.md"), "# API\n\nSummary.\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: liveRel,
+          rawPath: "raw/api.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [{ id: "API", file: "wiki/API.md", sourceIds: ["api.md"] }],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("STALE HASH") && line.includes("api.md")));
+});
+
+async function seedClosedWiki() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-closed-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(wikiRoot, "raw"), { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v1\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const manifest = {
+    schemaVersion: 1,
+    profile: "documents",
+    sources: [
+      {
+        id: "api.md",
+        kind: "document",
+        livePath: liveRel,
+        rawPath: "raw/api.md",
+        sha256: sha256(Buffer.from("v1\n")),
+      },
+    ],
+    articles: [{ id: "Alpha", file: "wiki/Alpha.md", sourceIds: ["api.md"] }],
+  };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  return { repo, wikiRoot, wiki, manifest };
+}
+
+test("closed manifest passes listing, id, sourceIds, profile, and rawPath checks", async () => {
+  const { repo, wikiRoot } = await seedClosedWiki();
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, true, result.errors.join("\n"));
+});
+
+test("open manifest fails unlisted article, id mismatch, unknown source, profile kind, and rawPath", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-open-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  await writeFile(path.join(repo, "docs", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n- [[Beta]]\n", "utf8");
+  await writeFile(path.join(wiki, "Alpha.md"), "# Alpha\n\nSee [[Beta]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(path.join(wiki, "Beta.md"), "# Beta\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "code-surface",
+          livePath: "docs/api.md",
+          rawPath: "raw/should-not-exist.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+        {
+          id: "note",
+          kind: "document",
+          livePath: "docs/api.md",
+          rawPath: "",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [
+        {
+          id: "WrongId",
+          file: "wiki/Alpha.md",
+          sourceIds: ["api.md", "ghost"],
+        },
+      ],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("UNLISTED ARTICLE") && line.includes("Beta.md")));
+  assert.ok(result.errors.some((line) => line.includes("MANIFEST ID MISMATCH") && line.includes("WrongId")));
+  assert.ok(result.errors.some((line) => line.includes("UNKNOWN SOURCE ID") && line.includes("ghost")));
+  assert.ok(result.errors.some((line) => line.includes("PROFILE KIND") && line.includes("code-surface")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH REQUIRED") && line.includes("note")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH FORBIDDEN") && line.includes("api.md")));
+});
+
+test("derived source requires a known extract.kind", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources.push({
+    id: "lock",
+    kind: "derived",
+    livePath: "docs/api.md",
+    rawPath: "raw/api.md",
+    sha256: sha256(Buffer.from("v1\n")),
+  });
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const missing = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(missing.ok, false);
+  assert.ok(missing.errors.some((line) => line.includes("EXTRACT REQUIRED") && line.includes("lock")));
+
+  manifest.sources.at(-1).extract = { kind: "whole-file" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const unknown = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(unknown.ok, false);
+  assert.ok(unknown.errors.some((line) => line.includes("EXTRACT KIND") && line.includes("whole-file")));
+
+  manifest.sources.at(-1).extract = { kind: "skill-names" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const ok = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(ok.ok, true, ok.errors.join("\n"));
+});
+
+test("document rawPath must exist on disk", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources[0].rawPath = "raw/missing.md";
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("RAW MISSING") && line.includes("raw/missing.md")));
+});

package/template/.agents/skills/yss-antd-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: yss-antd-design
+description: Use when 原型设计或高保真构建需要查询 Ant Design v6 设计语言、组件 API/demo/token/semantic，或落盘 AntD CLI 证据。不用于前端代码落地（改用 yss-ui）、Vue 生产 API、生命周期批准、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# YSS Ant Design 事实
+
+只服务原型设计与高保真构建。把官方 `@ant-design/cli`、`design.md`、MCP 与 LLMs.txt 收成可追溯的事实引擎。阶段合同仍是 `yss-prototype-stage`。前端代码落地一律改用 `yss-ui`，不要继续调用本技能。
+
+## 何时使用
+
+- 已进入 `yss-prototype-stage` 的高保真产出前后，需要 Ant Design v6 组件 / token / demo / semantic / 上游 `design.md` 事实。
+- 需要写入 `prototype-evidence.yaml` 的 AntD 段。
+
+不要用本技能：前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。进入实现切片后停用本技能，改走 `yss-ui`。
+
+## 步骤
+
+1. 检测 CLI：优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本。不要在模板源执行 `npm install -g`。
+2. 读项目 `docs/design/design.md` 与 `docs/design/tokens/*`。
+3. 选定 `<target_antd_version>`（项目已选的 v6；未选则先查再记录，不得依赖空仓库自动检测）。此后每次知识查询都传同一版本。
+4. 设置 `ANTD_NO_AUTO_REPORT=1`。一律 `--format json`，对外说明用 `--lang zh`。
+5. 查询官方 `design.md`，再按选用组件跑 `info` / `demo` / `token` / `semantic`。命令矩阵见 `references/cli-matrix.md`。
+6. 把 JSON 路径写入证据清单。字段与 lint 适用范围见 `references/evidence.md`。
+7. 上游默认与项目 token 冲突时，以项目覆盖为准，并标记 `project_override_reviewed`。
+
+## 硬规则
+
+- 禁止凭记忆写 Ant Design v6 API。
+- 禁止 `antd setup`、`npx skills add ant-design/ant-design-cli`，以及把官方 `skills/antd` 拷进 `.agents/skills`。
+- 禁止把官方 `design.md` 的默认色、圆角、间距写回项目实现或覆盖项目 token。
+- 禁止在前端代码落地、垂直切片实现或 `yss-ui` 任务中调用本技能。
+- 禁止把 React props / demo / hook 当作 `yss-ui` 或 Ant Design Vue API。
+- MCP 与 `llms-full.txt` 不是门禁证据。边界见 `references/boundaries.md`。

package/template/.agents/skills/yss-antd-design/references/boundaries.md

@@ -0,0 +1,30 @@
+# 边界与官方资料
+
+官方文档只提供 React `antd` 事实，不提供 YSS 阶段合同。入口对照：
+
+| 官方资料 | 本技能用法 |
+|---|---|
+| https://ant.design/docs/react/for-agents-cn | 了解 CLI / skill / MCP / LLMs 分层。不要把其中的 “安装 skill” prompt 写进 `AGENTS.md` |
+| https://ant.design/docs/react/cli-cn | 命令与参数的权威说明 |
+| https://ant.design/docs/react/design-md-cn | 上游 `design.md` 定位。项目覆盖是 `docs/design/design.md` |
+| https://ant.design/docs/react/mcp-cn | MCP 是 IDE 加速，8 个知识工具不含 `lint` |
+| https://ant.design/docs/react/llms-cn | CLI 不可用时的降级目录。不要默认注入 `llms-full.txt` |
+| https://ant.design/design.md | 与 `antd design.md` 同一份 v6 上游默认 |
+
+## 与其他技能
+
+- `yss-prototype-stage`：阶段顺序、评审、浏览器验证、用户确认。本技能只回写 AntD 事实段。
+- `yss-design-system`：项目风格与 token 规范。本技能查询上游事实，不得改项目 token。
+- `product-design:index`：Codex 视觉产出。本技能不替代它，也不使用 `antd-page-generator`。
+- `yss-ui`：前端代码落地的唯一 UI 入口。进入实现后不得再查本技能或 `@ant-design/cli` 的 React API。
+- 官方 `antd` skill：不安装、不锁定、不投影。
+
+## MCP 与 LLMs.txt
+
+开发者本机可以运行 `npx -y @ant-design/cli mcp --version <target_antd_version> --lang zh`，但：
+
+- 不把 `.cursor/mcp.json` 提交为模板默认。
+- 不把 MCP 调用记录当成 `evidence.antd-cli-validation`。
+- `antd-page-generator` 不是原型阶段入口。
+
+CLI 不可用时，可用 `https://ant.design/llms.txt` 定位单组件 `.md`，并在证据里写明降级原因。恢复 CLI 后补 JSON 落盘。

package/template/.agents/skills/yss-antd-design/references/cli-matrix.md

@@ -0,0 +1,38 @@
+# CLI 命令矩阵
+
+运行时入口：已安装的 `antd`，或 `npx -y @ant-design/cli`。记录实际 CLI 版本。知识查询必须带 `--format json`、`--lang zh` 和同一 `<target_antd_version>`。
+
+官方命令说明：https://ant.design/docs/react/cli-cn
+
+## 允许（原型 / 设计事实）
+
+| 命令 | 用途 |
+|---|---|
+| `antd design.md --version <target_antd_version> --lang zh --format json` | 上游默认 Light 主题。只对 antd v6 发布 |
+| `antd list --version <target_antd_version> --format json` | 组件选型 |
+| `antd info <Component> --version <target_antd_version> --format json` | props / 类型 / 默认值 |
+| `antd demo <Component> [name] --version <target_antd_version> --format json` | 可运行 demo 源码（React/TSX） |
+| `antd token <Component> --version <target_antd_version> --format json` | 组件或全局 token |
+| `antd semantic <Component> --version <target_antd_version> --format json` | `classNames` / `styles` 结构 |
+| `antd doc <Component> --version <target_antd_version> --lang zh --format json` | 需要完整文档时 |
+| `antd changelog <v1> <v2> [Component] --format json` | 仅当版本差异影响当前决策 |
+
+`design.md` 对 v5 返回 `UNSUPPORTED_VERSION_FEATURE`。空仓库不传 `--version` 时的回退版本不要假设；必须写进证据。
+
+## 条件允许
+
+| 命令 | 条件 |
+|---|---|
+| `antd lint <tsx-or-src> --format json` | 产物是 React/TSX 源码。HTML 原型不得当作通过 |
+| `antd doctor` / `antd usage` / `antd migrate` | 仅已登记的 React + `antd` 实现仓 |
+| `antd env --format json` | 排障需要环境快照时 |
+
+## 默认禁止
+
+| 命令 | 原因 |
+|---|---|
+| `antd setup` | 会写入 `.agents/skills/antd` 和 `AGENTS.md`，绕过 `skills-lock.json` |
+| `npx skills add ant-design/ant-design-cli` | 同上，安装官方 skill |
+| `antd bug` / `antd bug-cli` | 与 YSS Ticket 无关。保持 `ANTD_NO_AUTO_REPORT=1` |
+| `antd upgrade` | 不得在模板源或未授权时改动全局 CLI |
+| `antd mcp` 作为证据采集 | MCP 调用默认不落盘，见 `boundaries.md` |

package/template/.agents/skills/yss-antd-design/references/evidence.md

@@ -0,0 +1,26 @@
+# AntD 事实证据
+
+目标文件：`docs/.scratch/<feature>/verification/prototype-evidence.yaml`，字段以 `docs/design/templates/prototype-evidence-template.yaml` 为准。本文件只说明如何填 AntD 段。
+
+## 必填
+
+- `antd.cli_command`：实际调用的可执行文件，`antd` 或 `npx -y @ant-design/cli`。
+- `antd.cli_version`：本轮 `antd -V` 或等价输出，禁止写死模板默认值。
+- `antd.target_antd_version`：本轮全部知识查询使用的同一 v6 版本。
+- `antd.queries.design_md`：`antd design.md ... --format json` 的落盘路径。
+- `antd.queries.components[]`：每个选用组件的 `info_ref` / `demo_ref` / `token_ref` / `semantic_ref`。
+- `design_baseline.project_design_ref`：`docs/design/design.md`。
+- `design_baseline.project_override_reviewed`：上游默认与项目 token 已对照。
+
+JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
+
+## lint
+
+`antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
+
+| 产物 | `lint_applicable` | 做法 |
+|---|---|---|
+| `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |
+| React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
+
+浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。

package/template/.agents/skills/yss-antd-design/scripts/validate-frontmatter.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function validateFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error("Invalid SKILL.md frontmatter block");
+  const fields = new Map();
+  for (const line of match[1].split("\n")) {
+    if (!line.trim()) continue;
+    const index = line.indexOf(":");
+    if (index < 0) throw new Error(`Invalid frontmatter line: ${line}`);
+    fields.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
+  }
+  const keys = [...fields.keys()].sort();
+  if (keys.join(",") !== "description,name") throw new Error(`Expected keys ['description', 'name'], got ${JSON.stringify(keys)}`);
+  const name = fields.get("name");
+  const description = fields.get("description");
+  if (name !== "yss-antd-design") throw new Error("Invalid skill name: " + name);
+  if (!description || description.length > 1024) throw new Error("Description must be present and <= 1024 chars");
+  if (!/yss-ui|官方 antd skill|yss-prototype-stage/.test(description)) {
+    throw new Error("Description must exclude frontend landing via yss-ui, official antd skill, and stage-contract takeover");
+  }
+  return name;
+}
+
+export function validateSetupBan(text) {
+  if (!/禁止 `antd setup`/.test(text)) throw new Error("SKILL.md must forbid antd setup");
+  if (!/npx skills add ant-design\/ant-design-cli/.test(text)) throw new Error("SKILL.md must forbid official skill installer");
+}
+
+async function main() {
+  const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
+  try {
+    const text = await readFile(skill, "utf8");
+    const name = validateFrontmatter(text);
+    validateSetupBan(text);
+    console.log(`${name} frontmatter ok`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.agents/skills/yss-antd-design/scripts/validate-frontmatter.test.mjs

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateFrontmatter, validateSetupBan } from "./validate-frontmatter.mjs";
+
+const valid = `---
+name: yss-antd-design
+description: Use when 原型设计。不用于前端代码落地（改用 yss-ui）、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# body
+- 禁止 \`antd setup\`、\`npx skills add ant-design/ant-design-cli\`
+`;
+
+test("accepts the required skill frontmatter", () => {
+  assert.equal(validateFrontmatter(valid), "yss-antd-design");
+});
+
+test("rejects missing exclusion branches in description", () => {
+  assert.throws(
+    () => validateFrontmatter("---\nname: yss-antd-design\ndescription: Use when querying antd.\n---\n"),
+    /exclude frontend landing/
+  );
+});
+
+test("rejects a skill that does not forbid official setup", () => {
+  assert.throws(() => validateSetupBan("# no setup ban"), /forbid antd setup/);
+});

package/template/.agents/skills/yss-design-system/SKILL.md

@@ -13,7 +13,9 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 项目 token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`。
 - 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
 - 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
-- 原型阶段合同：`yss-prototype-stage`，用于统一跨 Agent 的原型资产、AntD 事实和浏览器验证证据。
+- 默认亮色覆盖：项目 Ant Design 5 Less / `:root` 变量已裁定进 `docs/design/design.md` 与 token 快照；原始 Less 不是实现语言。
+- Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
+- 原型阶段合同：`yss-prototype-stage`，用于统一跨 Agent 的原型资产和浏览器验证证据。AntD 事实由 `yss-antd-design` 提供，且只用于原型设计构建。
 
 如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 token，必须读项目内 `docs/design/design.md`；若要执行评审或实现检查，再读 `references/design-system.md`。
 
@@ -29,10 +31,11 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 ## 核心基线
 
 - UI 定位：中后台、数据密集、表单密集、流程密集、可扫描、低装饰。
-- 主色：`#1677ff`，用于主操作、链接、焦点、选中态和激活导航。
-- 默认字号：14px；主要字重：400 / 600。
-- 默认控件高度：32px。
+- 主色：`#3371ff`（`--primary-color` / `--brand-color-primary`），用于主操作、链接、焦点、选中态和激活导航。
+- 默认字号：14px；主要字重：400 / 600；字体栈为系统字体，不强制 `Inter`。
+- 默认控件高度：32px；默认圆角 6px。
 - 间距：4px 网格，优先使用 token，不写任意 magic number。
+- 运行时换肤：短名 CSS 变量必须指向 `--brand-*`，不要再维护第二套色值。
 - 表面层级：页面背景、内容容器、浮层三层模型。
 - 组件语言：优先 Ant Design / YSS UI 语义，不自造同类控件。
 - 状态完整性：loading、empty、error、readonly、disabled、no-permission、conflict、success 必须在设计或实现中可解释。
@@ -84,7 +87,8 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
-| Ant Design v6 组件 / token / demo 查询 | 官方 `@ant-design/cli` / `https://ant.design/docs/react/for-agents` |
+| 原型阶段的 Ant Design v6 组件 / token / demo 查询 | `yss-antd-design`（只用于原型设计构建；前端落地改用 `yss-ui`） |
+| Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
 | API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
 
 ## 更新设计系统