@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/localized/zh-CN/skills/cc-technical-diagrams/scripts/png-qa.mjs

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { segmentHits } from "./diagram-layout.mjs";
+import { pathToFileURL } from "node:url";
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.png || args.help) {
+  printHelp();
+  process.exit(args.help ? 0 : 1);
+}
+
+try {
+  const image = readPng(args.png);
+  const manifest = args.manifest ? readManifest(args.manifest) : undefined;
+  const report = analyze(image, manifest, Boolean(args.strict));
+  if ((args.format ?? "markdown") === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderMarkdown(report));
+  }
+  process.exit(report.ok ? 0 : 2);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+}
+
+function parseArgs(values) {
+  const parsed = { format: "markdown", strict: false, help: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") parsed.help = true;
+    else if (value === "--strict") parsed.strict = true;
+    else if (value === "--png") parsed.png = values[++index];
+    else if (value === "--manifest") parsed.manifest = values[++index];
+    else if (value === "--format") parsed.format = values[++index];
+    else throw new Error(`Unknown argument: ${value}`);
+  }
+  if (parsed.format !== "json" && parsed.format !== "markdown") {
+    throw new Error("--format must be json or markdown");
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage: node skills/cc-technical-diagrams/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
+}
+
+function readManifest(filePath) {
+  const manifest = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return {
+    ...manifest,
+    canvas: manifest.canvas,
+    boxes: Array.isArray(manifest.boxes) ? manifest.boxes : [],
+    connectors: Array.isArray(manifest.connectors) ? manifest.connectors : [],
+  };
+}
+
+function readPng(filePath) {
+  const buffer = fs.readFileSync(filePath);
+  const signature = "89504e470d0a1a0a";
+  if (buffer.subarray(0, 8).toString("hex") !== signature) {
+    throw new Error(`Not a PNG file: ${filePath}`);
+  }
+
+  let offset = 8;
+  let ihdr;
+  const idat = [];
+  while (offset < buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.subarray(offset + 4, offset + 8).toString("ascii");
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (type === "IHDR") {
+      ihdr = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!ihdr) throw new Error("PNG is missing IHDR");
+  if (ihdr.bitDepth !== 8) throw new Error(`Unsupported PNG bit depth: ${ihdr.bitDepth}`);
+  if (ihdr.compression !== 0 || ihdr.filter !== 0 || ihdr.interlace !== 0) {
+    throw new Error("Unsupported PNG compression/filter/interlace settings");
+  }
+
+  const channels = channelsForColorType(ihdr.colorType);
+  const inflated = zlib.inflateSync(Buffer.concat(idat));
+  const pixels = unfilter(inflated, ihdr.width, ihdr.height, channels);
+  return {
+    path: path.resolve(filePath),
+    width: ihdr.width,
+    height: ihdr.height,
+    colorType: ihdr.colorType,
+    channels,
+    pixels,
+  };
+}
+
+function channelsForColorType(colorType) {
+  if (colorType === 0) return 1;
+  if (colorType === 2) return 3;
+  if (colorType === 4) return 2;
+  if (colorType === 6) return 4;
+  throw new Error(`Unsupported PNG color type: ${colorType}`);
+}
+
+function unfilter(data, width, height, channels) {
+  const stride = width * channels;
+  const output = Buffer.alloc(stride * height);
+  let sourceOffset = 0;
+
+  for (let y = 0; y < height; y += 1) {
+    const filterType = data[sourceOffset];
+    sourceOffset += 1;
+    const rowOffset = y * stride;
+    const previousRowOffset = (y - 1) * stride;
+
+    for (let x = 0; x < stride; x += 1) {
+      const raw = data[sourceOffset + x];
+      const left = x >= channels ? output[rowOffset + x - channels] : 0;
+      const up = y > 0 ? output[previousRowOffset + x] : 0;
+      const upLeft = y > 0 && x >= channels ? output[previousRowOffset + x - channels] : 0;
+      let value;
+      if (filterType === 0) value = raw;
+      else if (filterType === 1) value = raw + left;
+      else if (filterType === 2) value = raw + up;
+      else if (filterType === 3) value = raw + Math.floor((left + up) / 2);
+      else if (filterType === 4) value = raw + paeth(left, up, upLeft);
+      else throw new Error(`Unsupported PNG filter type: ${filterType}`);
+      output[rowOffset + x] = value & 0xff;
+    }
+    sourceOffset += stride;
+  }
+
+  return output;
+}
+
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const upDistance = Math.abs(estimate - up);
+  const upLeftDistance = Math.abs(estimate - upLeft);
+  if (leftDistance <= upDistance && leftDistance <= upLeftDistance) return left;
+  if (upDistance <= upLeftDistance) return up;
+  return upLeft;
+}
+
+function analyze(image, manifest, strict) {
+  const issues = [];
+  const nextActions = new Set();
+  const ink = measureInk(image, strict ? 10 : 18);
+
+  if (image.width < 64 || image.height < 64) {
+    addIssue(issues, nextActions, "image-too-small", "PNG is too small for reliable visual QA.", "Export a larger PNG before review.");
+  }
+
+  if (ink.coverage < (strict ? 0.001 : 0.0002)) {
+    addIssue(issues, nextActions, "blank-image", "PNG appears blank or nearly blank.", "Check the renderer/export target and regenerate the image.");
+  }
+
+  if (ink.bounds) {
+    const pad = strict ? 6 : 3;
+    if (ink.bounds.minX <= pad || ink.bounds.minY <= pad || image.width - ink.bounds.maxX <= pad || image.height - ink.bounds.maxY <= pad) {
+      addIssue(issues, nextActions, "edge-clipping", "Visible content is very close to the PNG edge.", "Increase canvas/viewBox padding or reduce subject scale.");
+    }
+  }
+
+  if (manifest) analyzeManifest(image, manifest, issues, nextActions, strict);
+
+  return {
+    ok: issues.length === 0,
+    image: {
+      path: image.path,
+      width: image.width,
+      height: image.height,
+      colorType: image.colorType,
+      inkCoverage: Number(ink.coverage.toFixed(6)),
+      inkBounds: ink.bounds,
+    },
+    measurement: manifest?.measurement ?? "image-only",
+    verification: { image: "checked", geometry: manifest ? "checked" : "unavailable", text: manifest?.measurement === "browser" ? "browser-measured" : "estimated-or-unavailable", visual: "pending" },
+    issues,
+    nextActions: [...nextActions],
+  };
+}
+
+function measureInk(image, threshold) {
+  const first = samplePixel(image, 0, 0);
+  let inkPixels = 0;
+  let minX = image.width;
+  let minY = image.height;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const pixel = samplePixel(image, x, y);
+      const differs = colorDistance(pixel, first) > threshold && pixel.a > 8;
+      if (differs) {
+        inkPixels += 1;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+
+  return {
+    coverage: inkPixels / (image.width * image.height),
+    bounds: inkPixels > 0 ? { minX, minY, maxX, maxY } : null,
+  };
+}
+
+function samplePixel(image, x, y) {
+  const offset = (y * image.width + x) * image.channels;
+  if (image.channels === 1) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: 255 };
+  }
+  if (image.channels === 2) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: image.pixels[offset + 1] };
+  }
+  return {
+    r: image.pixels[offset],
+    g: image.pixels[offset + 1],
+    b: image.pixels[offset + 2],
+    a: image.channels === 4 ? image.pixels[offset + 3] : 255,
+  };
+}
+
+function colorDistance(left, right) {
+  return Math.abs(left.r - right.r) + Math.abs(left.g - right.g) + Math.abs(left.b - right.b) + Math.abs(left.a - right.a);
+}
+
+export function analyzeManifest(image, manifest, issues, nextActions, strict) {
+  if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
+    addIssue(
+      issues,
+      nextActions,
+      "manifest-canvas-mismatch",
+      `Manifest canvas ${manifest.canvas.width}x${manifest.canvas.height} does not match PNG ${image.width}x${image.height}.`,
+      "Regenerate the manifest from the final export dimensions.",
+    );
+  }
+
+  for (const box of manifest.boxes) if (![box.x,box.y,box.width,box.height].every(Number.isFinite) || box.width <= 0 || box.height <= 0) addIssue(issues,nextActions,"invalid-box-geometry",`Invalid geometry for "${box.id}".`,"Correct source dimensions.");
+  const allBoxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  const boxes = allBoxes.filter((box) => box.kind !== "group");
+  for (const issue of manifest.issues ?? []) addIssue(issues, nextActions, issue.code, issue.message, "Fix the source layout and render again.");
+  const labels = manifest.labels ?? [];
+  for (const label of labels) {
+    const owner = allBoxes.find((box) => box.id === label.owner);
+    if (label.kind === "node" && !owner) addIssue(issues,nextActions,"label-owner-missing",`Label "${label.id}" has an unknown node owner.`,"Correct label ownership in the manifest.");
+    if (![label.x,label.y,label.width,label.height].every(Number.isFinite) || label.width < 0 || label.height < 0) addIssue(issues,nextActions,"invalid-label-geometry",`Label "${label.id}" has invalid bounds.`,"Measure source labels again.");
+    if (label.x < 0 || label.y < 0 || label.x + label.width > image.width || label.y + label.height > image.height) addIssue(issues, nextActions, "label-out-of-bounds", `Label "${label.id}" exceeds the canvas.`, "Expand the canvas or adjust the source label position.");
+    if (label.kind === "node" && owner && (label.x < owner.x || label.y < owner.y || label.x + label.width > owner.x + owner.width || label.y + label.height > owner.y + owner.height)) addIssue(issues, nextActions, "node-text-overflow", `Label "${label.id}" exceeds node "${owner.id}".`, "Expand the source node or adjust its text layout.");
+    if (Array.isArray(label.lines) && label.lines.join("").replace(/\r?\n/g, "") !== String(label.text ?? "").replace(/\r?\n/g, "")) addIssue(issues, nextActions, "label-content-loss", `Label "${label.id}" does not preserve source text.`, "Restore the complete source label.");
+    if (label.kind === "edge") for (const box of boxes) if (overlapArea(label, box) > 0) addIssue(issues, nextActions, "edge-label-collision", `Label "${label.id}" overlaps node "${box.id}".`, "Move the edge label to a clear route segment.");
+  }
+  for (let i = 0; i < labels.length; i++) for (let j = i + 1; j < labels.length; j++) if (overlapArea(labels[i], labels[j]) > 0) addIssue(issues, nextActions, "text-overlap", `Labels "${labels[i].id}" and "${labels[j].id}" overlap.`, "Increase label spacing in the source.");
+  for (const box of boxes) {
+    if (box.x < 0 || box.y < 0 || box.x + box.width > image.width || box.y + box.height > image.height) {
+      addIssue(issues, nextActions, "box-out-of-bounds", `Box "${box.id}" is outside the canvas.`, "Move out-of-bounds nodes inside the canvas or expand the canvas.");
+    }
+    if (!labels.length && box.label && estimateLabelOverflow(box, strict)) {
+      addIssue(issues, nextActions, "label-overflow", `Box "${box.id}" label is likely to overflow.`, "Wrap or shorten labels, widen boxes, or increase export scale.");
+    }
+  }
+
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const overlap = overlapArea(boxes[i], boxes[j]);
+      if (overlap > 0) {
+        addIssue(issues, nextActions, "box-overlap", `Boxes "${boxes[i].id}" and "${boxes[j].id}" overlap by ${Math.round(overlap)}px^2.`, "Increase node spacing or split dense groups.");
+      }
+    }
+  }
+
+  const boxById = new Map(boxes.map((box) => [box.id, box]));
+  const segments = [];
+  for (const connector of manifest.connectors) {
+    const points = normalizePoints(connector.points);
+    if(points.some(point=>point.x<0||point.y<0||point.x>image.width||point.y>image.height)) addIssue(issues,nextActions,"connector-out-of-bounds",`Connector "${connector.id}" exceeds the canvas.`,"Correct explicit waypoints or expand the source canvas.");
+    if (points.length < 2 || points.every((point) => point.x === points[0].x && point.y === points[0].y)) addIssue(issues, nextActions, "degenerate-connector", `Connector "${connector.id ?? "unnamed"}" has no visible path.`, "Give self calls a loop and other connectors distinct endpoints.");
+    for (let index = 0; index < points.length - 1; index += 1) {
+      const segment = { connector, a: points[index], b: points[index + 1] };
+      segments.push(segment);
+      for (const label of labels) if (segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],label)) addIssue(issues,nextActions,"connector-through-text",`Connector "${connector.id}" crosses label "${label.id}".`,"Move the source label or route around its text.");
+      for (const box of boxes) {
+        if (box.id === connector.from || box.id === connector.to) continue;
+        if (segmentIntersectsBox(segment, box)) {
+          addIssue(issues, nextActions, "connector-through-label", `Connector "${connector.id ?? "unnamed"}" crosses box "${box.id}".`, "Add waypoints around labels or use orthogonal routing.");
+        }
+      }
+    }
+    if ((connector.from && !boxById.has(connector.from)) || (connector.to && !boxById.has(connector.to))) {
+      addIssue(issues, nextActions, "connector-endpoint-missing", `Connector "${connector.id ?? "unnamed"}" references a missing endpoint.`, "Update connector endpoints to match manifest box ids.");
+    }
+  }
+
+  for (let i = 0; i < segments.length; i += 1) {
+    for (let j = i + 1; j < segments.length; j += 1) {
+      if (segments[i].connector === segments[j].connector) continue;
+      if (segmentsStack(segments[i], segments[j], strict ? 4 : 2)) {
+        addIssue(issues, nextActions, "connector-stacking", "Two connector segments are stacked or nearly stacked.", "Offset parallel connectors or bundle them into a labeled shared route.");
+      }
+    }
+  }
+}
+
+function normalizeBox(box) {
+  if (!box || typeof box.id !== "string") return null;
+  const normalized = {
+    id: box.id,
+    kind: box.kind,
+    x: Number(box.x),
+    y: Number(box.y),
+    width: Number(box.width),
+    height: Number(box.height),
+    label: typeof box.label === "string" ? box.label : "",
+  };
+  if ([normalized.x, normalized.y, normalized.width, normalized.height].some((value) => !Number.isFinite(value))) return null;
+  return normalized;
+}
+
+function normalizePoints(points) {
+  if (!Array.isArray(points)) return [];
+  return points
+    .map((point) => {
+      if (Array.isArray(point)) return { x: Number(point[0]), y: Number(point[1]) };
+      return { x: Number(point?.x), y: Number(point?.y) };
+    })
+    .filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y));
+}
+
+function estimateLabelOverflow(box, strict) {
+  const label = box.label.trim();
+  if (!label) return false;
+  const lines = label.split(/\r?\n/);
+  const maxLine = Math.max(...lines.map((line) => visualLength(line)));
+  const estimatedWidth = maxLine * (strict ? 7.5 : 7);
+  const estimatedHeight = lines.length * (strict ? 18 : 16);
+  return estimatedWidth > Math.max(0, box.width - 12) || estimatedHeight > Math.max(0, box.height - 8);
+}
+
+function visualLength(value) {
+  return [...value].reduce((total, char) => total + (/[\u4e00-\u9fff]/.test(char) ? 2 : 1), 0);
+}
+
+function overlapArea(left, right) {
+  const width = Math.max(0, Math.min(left.x + left.width, right.x + right.width) - Math.max(left.x, right.x));
+  const height = Math.max(0, Math.min(left.y + left.height, right.y + right.height) - Math.max(left.y, right.y));
+  return width * height;
+}
+
+function segmentIntersectsBox(segment, box) {
+  return segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],box);
+}
+
+function legacySegmentIntersectsBox(segment, box) {
+  if (pointInsideBox(segment.a, box) || pointInsideBox(segment.b, box)) return true;
+  const edges = [
+    [{ x: box.x, y: box.y }, { x: box.x + box.width, y: box.y }],
+    [{ x: box.x + box.width, y: box.y }, { x: box.x + box.width, y: box.y + box.height }],
+    [{ x: box.x + box.width, y: box.y + box.height }, { x: box.x, y: box.y + box.height }],
+    [{ x: box.x, y: box.y + box.height }, { x: box.x, y: box.y }],
+  ];
+  return edges.some(([a, b]) => segmentsIntersect(segment.a, segment.b, a, b));
+}
+
+function pointInsideBox(point, box) {
+  return point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+}
+
+function segmentsIntersect(a, b, c, d) {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+  if (o1 !== o2 && o3 !== o4) return true;
+  return false;
+}
+
+function orientation(a, b, c) {
+  const value = (b.y - a.y) * (c.x - b.x) - (b.x - a.x) * (c.y - b.y);
+  if (Math.abs(value) < 0.0001) return 0;
+  return value > 0 ? 1 : 2;
+}
+
+function segmentsStack(left, right, tolerance) {
+  const leftHorizontal = Math.abs(left.a.y - left.b.y) <= tolerance;
+  const rightHorizontal = Math.abs(right.a.y - right.b.y) <= tolerance;
+  const leftVertical = Math.abs(left.a.x - left.b.x) <= tolerance;
+  const rightVertical = Math.abs(right.a.x - right.b.x) <= tolerance;
+
+  if (leftHorizontal && rightHorizontal && Math.abs(left.a.y - right.a.y) <= tolerance) {
+    return rangesOverlap([left.a.x, left.b.x], [right.a.x, right.b.x]) > tolerance;
+  }
+  if (leftVertical && rightVertical && Math.abs(left.a.x - right.a.x) <= tolerance) {
+    return rangesOverlap([left.a.y, left.b.y], [right.a.y, right.b.y]) > tolerance;
+  }
+  return false;
+}
+
+function rangesOverlap(left, right) {
+  const a = [Math.min(...left), Math.max(...left)];
+  const b = [Math.min(...right), Math.max(...right)];
+  return Math.max(0, Math.min(a[1], b[1]) - Math.max(a[0], b[0]));
+}
+
+function addIssue(issues, nextActions, code, message, action) {
+  issues.push({ code, message, action });
+  if (typeof nextActions.add === "function") nextActions.add(action);
+  else if (!nextActions.includes(action)) nextActions.push(action);
+}
+
+function renderMarkdown(report) {
+  const lines = [
+    "# PNG QA Report",
+    "",
+    `- Status: ${report.ok ? "ok" : "issues-found"}`,
+    `- Image: ${report.image.width}x${report.image.height}`,
+    `- Ink coverage: ${report.image.inkCoverage}`,
+  ];
+  if (report.image.inkBounds) {
+    lines.push(`- Ink bounds: ${JSON.stringify(report.image.inkBounds)}`);
+  }
+  lines.push("", "## Issues");
+  if (report.issues.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const issue of report.issues) {
+      lines.push(`- ${issue.code}: ${issue.message}`);
+    }
+  }
+  lines.push("", "## Next Actions");
+  if (report.nextActions.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const action of report.nextActions) lines.push(`- ${action}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/localized/zh-CN/skills/{fec-typescript-project-standard → cc-typescript-project-standard}/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: fec-typescript-project-standard
-description: 用于创建、配置、审查或调试前端应用、库、SDK、CLI、monorepo 包中的 TypeScript 项目规范，包括 tsconfig、strictness、module/moduleResolution、路径别名、project references、声明文件、package exports、公共 API 类型、DTO、高级泛型、判别联合、类型守卫、类型收窄或类型级回归。React/Vue/Next/Nuxt 组件架构优先使用框架项目 skill；中文触发词包括 TypeScript 项目规范、TS 项目规范、TypeScript 类型安全、类型建模、泛型、判别联合、类型收窄、tsconfig、声明文件。
+name: cc-typescript-project-standard
+description: 用于TypeScript 工程配置、模块解析、公共类型、声明文件、包导出、类型收窄或泛型契约需要设计审查，适用于应用、SDK、CLI、桌面进程与库。
 ---
 
 # TypeScript 项目规范
 
+本入口面向库、CLI、桌面核心及服务中的语言工程；应用角色由实际子工程证据决定，不由前端/后端产品名决定。
+
 ## 用途
 
 统一 TypeScript 层的工程配置、类型边界和发布产物规则。适用于前端应用、组件库、SDK、CLI、monorepo package 和纯 TypeScript 工具库，但不接管 React、Vue、Next.js、Nuxt 或 Vite 的框架架构职责。
@@ -19,7 +21,7 @@ description: 用于创建、配置、审查或调试前端应用、库、SDK、C
    - React、Vue、Next.js、Nuxt 等框架的组件架构、路由组织和状态管理归对应框架 skill；本流程只处理跨框架 TypeScript 契约和工程边界。
 
 2. 收敛 `tsconfig`
-   - 默认开启 `strict`，不要为通过构建关闭 `noImplicitAny`、`strictNullChecks` 或 `exactOptionalPropertyTypes` 等关键约束。
+   - 新代码优先 `strict` 并保留已有检查，不为掩盖缺陷关闭 `noImplicitAny` 或 `strictNullChecks`。`exactOptionalPropertyTypes` 是独立选项；有依据时以局部、兼容迁移引入更严格配置。
    - 按运行环境选择 `target`、`lib`、`module` 和 `moduleResolution`；浏览器应用、Node 脚本、库包不要共用一份含混配置。
    - 将基础配置、应用配置、测试配置和构建声明配置拆开，避免测试全局类型污染生产代码。
    - 路径别名必须同时被 TypeScript、bundler、test runner 和发布产物理解；库包不得发布无法解析的源码别名。
@@ -43,7 +45,7 @@ description: 用于创建、配置、审查或调试前端应用、库、SDK、C
 
 ## 约束
 
-- 不用 `skipLibCheck`、`any`、无守卫非空断言或宽泛 `as` 掩盖真实边界问题。
+- 不用 `any`、无守卫非空断言或宽泛 `as` 掩盖未经验证的边界。合理的 `skipLibCheck` 依赖政策与检查自身公共API有别，需记录其限制。
 - 不在应用代码中依赖发布包私有深层路径。
 - 不把框架目录结构、组件分层、路由组织或状态管理决策放进本流程；这些交给对应框架或专项流程。
 - 不让生成类型、测试类型或 Node-only 类型污染浏览器运行代码。
@@ -52,3 +54,7 @@ description: 用于创建、配置、审查或调试前端应用、库、SDK、C
 ## 预期输出
 
 输出应包含 TypeScript 上下文判断、关键 `tsconfig`/package 类型入口建议、类型边界方案、声明文件或 public API 风险、验证命令。完成后项目应能独立 typecheck，公开类型可被消费方解析，类型安全问题有明确收窄或建模方案。
+
+## 工程实践
+
+按当前任务读取[本入口工程细则](references/engineering-practices.md)，再按链接选择公共原则。规则级别与例外以实际项目契约为准；不因产品前后端标签限制语言或职责。

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/README.md

@@ -0,0 +1,7 @@
+# 外部输入边界 — EP-TS-01
+
+将此目录复制到可写临时位置。样例自有Node >=22.18目标（原生类型擦除），不升级父项目。显式准备：pnpm install --ignore-scripts --frozen-lockfile，然后pnpm typecheck。PowerShell设$env:CRAFT_ENGINEERING_DEFECTIVE为1，运行pnpm test，非法输入命名断言应失败；设为0或移除变量后同组两个测试通过。POSIX可在测试命令前设置同名环境变量。
+
+回调记录校验前后的真实副作用，缺陷分支故意以断言替代校验；默认受保护。这里不验证付款服务、浏览器、异步状态及声明发布。仅依赖本目录源码和已声明工具，node_modules/build/log应留在可写副本。
+
+[Node.js 类型擦除历史与限制](https://nodejs.org/api/typescript.html)：运行时类型擦除与显式 TypeScript 类型检查分开。

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/boundary.test.ts

@@ -0,0 +1,16 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { acceptAmount } from "./input.ts";
+
+test("EP-TS-01 rejects invalid input before any effect", () => {
+  const effects: number[] = [];
+  for (const input of [{ amount: "10" }, { amount: -1 }, { amount: Number.MAX_SAFE_INTEGER + 1 }, null]) {
+    assert.throws(() => acceptAmount(input, amount => effects.push(amount)), /invalid amount/);
+    assert.deepEqual(effects, []);
+  }
+});
+test("EP-TS-01 accepts a valid input exactly once", () => {
+  const effects: number[] = [];
+  acceptAmount({ amount: 10 }, amount => effects.push(amount));
+  assert.deepEqual(effects, [10]);
+});

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/input.ts

@@ -0,0 +1,12 @@
+/** Test switch only; normal use always validates the external boundary. */
+export function acceptAmount(value: unknown, effect: (amount: number) => void): void {
+  if (process.env.CRAFT_ENGINEERING_DEFECTIVE === "1") {
+    effect((value as { amount: number }).amount);
+    return;
+  }
+  if (typeof value !== "object" || value === null || !("amount" in value)
+      || typeof value.amount !== "number" || !Number.isSafeInteger(value.amount) || value.amount <= 0) {
+    throw new TypeError("invalid amount");
+  }
+  effect(value.amount);
+}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "engineering-typescript-boundary-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": { "node": ">=22.18.0" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test --test-reporter=tap boundary.test.ts"
+  },
+  "devDependencies": { "typescript": "5.9.3", "@types/node": "22.20.5" }
+}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/pnpm-lock.yaml

@@ -0,0 +1,39 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@types/node':
+        specifier: 22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+
+packages:
+
+  '@types/node@22.20.5':
+    resolution: {integrity: sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==}
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+snapshots:
+
+  '@types/node@22.20.5':
+    dependencies:
+      undici-types: 6.21.0
+
+  typescript@5.9.3: {}
+
+  undici-types@6.21.0: {}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/pnpm-workspace.yaml

@@ -0,0 +1 @@
+packages: []

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "strict": true, "noEmit": true, "allowImportingTsExtensions": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts"]
+}