@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/localized/zh-CN/skills/cc-drawio-studio/scripts/shape-query.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { formatResult, parseArgs, skillDir } from "./studio-core.mjs";
+
+const INDEX = path.join(skillDir, "data", "shape-index.json");
+const ALIASES = new Map([
+  ["亚马逊", "aws"],
+  ["阿里云", "alibaba cloud"],
+  ["微软云", "azure"],
+  ["谷歌云", "gcp"],
+  ["云", "cloud"],
+  ["数据库", "database"],
+  ["队列", "queue"],
+  ["网关", "gateway"],
+  ["服务", "service"],
+  ["用户", "user"],
+  ["角色", "actor"],
+  ["流程", "flowchart"],
+  ["容器", "container"],
+  ["网络", "network"],
+  ["交换机", "switch"],
+  ["路由器", "router"],
+  ["函数", "lambda"],
+  ["对象存储", "storage"],
+  ["消息", "message"],
+]);
+
+export function loadShapes() {
+  return JSON.parse(fs.readFileSync(INDEX).toString("utf8"));
+}
+
+export function queryShapes(shapes, query, options = {}) {
+  const terms = expandTerms(query);
+  const category = options.category
+    ? String(options.category).toLowerCase()
+    : "";
+  const scored = [];
+  for (const [index, shape] of shapes.entries()) {
+    const haystack =
+      `${shape.title ?? ""} ${shape.tags ?? ""} ${shape.style ?? ""}`.toLowerCase();
+    if (category && !haystack.includes(category)) continue;
+    let score = 0;
+    const title = String(shape.title ?? "").toLowerCase();
+    const tags = String(shape.tags ?? "").toLowerCase();
+    for (const term of terms) {
+      if (title === term) score += 80;
+      else if (title.includes(term)) score += 45;
+      if (tags.split(/\s+/).includes(term)) score += 30;
+      else if (tags.includes(term)) score += 12;
+      if (fuzzyContains(haystack, term)) score += 4;
+    }
+    if (score > 0)
+      scored.push({
+        index,
+        score,
+        titleHits: terms.filter((term) => title.includes(term)).length,
+        shape,
+      });
+  }
+  return scored
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        b.titleHits - a.titleHits ||
+        String(a.shape.title).localeCompare(String(b.shape.title)) ||
+        a.index - b.index,
+    )
+    .slice(0, Number(options.limit ?? 10))
+    .map(({ shape, score }) => ({
+      title: shape.title,
+      w: shape.w,
+      h: shape.h,
+      style: shape.style,
+      score,
+    }));
+}
+
+function expandTerms(query) {
+  const normalized = String(query ?? "").toLowerCase();
+  const raw = normalized.match(/[\p{L}\p{N}._-]+/gu) ?? [];
+  const expanded = [];
+  for (const term of raw) {
+    expanded.push(ALIASES.get(term) ?? term);
+    if (term.includes("-")) expanded.push(...term.split("-"));
+  }
+  return [
+    ...new Set(
+      expanded.join(" ").match(/[a-z0-9._-]+|[\u4e00-\u9fff]+/g) ?? [],
+    ),
+  ].filter((term) => term.length >= 2);
+}
+
+function fuzzyContains(text, term) {
+  if (term.length < 4) return false;
+  let cursor = 0;
+  for (const ch of text) {
+    if (ch === term[cursor]) cursor += 1;
+    if (cursor === term.length) return true;
+  }
+  return false;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const query = args._.join(" ");
+if (!query) {
+  console.error(
+    "usage: node shape-query.mjs <keywords> [--limit 10] [--category aws] [--format markdown|json]",
+  );
+  process.exit(2);
+}
+const results = queryShapes(loadShapes(), query, args);
+if (results.length === 0) {
+  console.error(`no shapes matched ${JSON.stringify(query)}`);
+  process.exit(1);
+}
+if ((args.format ?? (args.json ? "json" : "markdown")) === "json") {
+  process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+} else {
+  process.stdout.write(formatResult({ title: "Shape Query", query, results }));
+}

package/localized/zh-CN/skills/cc-drawio-studio/scripts/studio-core.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+export const skillDir = path.resolve(scriptDir, "..");
+
+export function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function writeText(filePath, body) {
+  fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+  fs.writeFileSync(filePath, body, "utf8");
+}
+
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      args._.push(token);
+      continue;
+    }
+    const [rawKey, inline] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+    if (inline !== undefined) {
+      args[key] = inline;
+    } else if (argv[i + 1] && !argv[i + 1].startsWith("--")) {
+      args[key] = argv[i + 1];
+      i += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+export function formatResult(result, format = "markdown") {
+  if (format === "json") return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [`# ${result.title ?? "Drawio Studio Result"}`, ""];
+  for (const [key, value] of Object.entries(result)) {
+    if (key === "title") continue;
+    if (Array.isArray(value)) {
+      lines.push(`## ${label(key)}`, "");
+      if (value.length === 0) lines.push("- None");
+      else for (const item of value) lines.push(`- ${typeof item === "string" ? item : JSON.stringify(item)}`);
+      lines.push("");
+    } else if (value && typeof value === "object") {
+      lines.push(`## ${label(key)}`, "", "```json", JSON.stringify(value, null, 2), "```", "");
+    } else {
+      lines.push(`- ${label(key)}: ${String(value)}`);
+    }
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function label(value) {
+  return value.replace(/([A-Z])/g, " $1").replace(/^./, (ch) => ch.toUpperCase());
+}
+
+export function xmlEscape(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+export function snap(value, grid = 10) {
+  return Math.round(value / grid) * grid;
+}
+
+export function walkFiles(root, predicate) {
+  const out = [];
+  const skip = new Set([".git", "node_modules", "dist", "target", "vendor", ".next", ".nuxt", "coverage"]);
+  function visit(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (skip.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (!predicate || predicate(full)) out.push(full);
+    }
+  }
+  visit(path.resolve(root));
+  return out.sort();
+}
+
+export function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+
+export function commonPrefix(values) {
+  if (values.length === 0) return "";
+  let prefix = values[0];
+  for (const value of values.slice(1)) {
+    while (prefix && !value.startsWith(prefix)) prefix = prefix.slice(0, -1);
+  }
+  return prefix.replace(/[^/]*$/, "");
+}
+
+export function reduceTransitive(nodes, edges) {
+  const ids = new Set(nodes.map((node) => node.id));
+  const unique = [];
+  const seen = new Set();
+  for (const edge of edges) {
+    if (!ids.has(edge.source) || !ids.has(edge.target) || edge.source === edge.target) continue;
+    const key = `${edge.source}\0${edge.target}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push({ source: edge.source, target: edge.target });
+    }
+  }
+  const adjacency = new Map();
+  for (const edge of unique) {
+    if (!adjacency.has(edge.source)) adjacency.set(edge.source, new Set());
+    adjacency.get(edge.source).add(edge.target);
+  }
+  return unique.filter((edge) => !hasAlternatePath(edge.source, edge.target, adjacency, edge));
+}
+
+function hasAlternatePath(source, target, adjacency, skipped) {
+  const stack = [...(adjacency.get(source) ?? [])].filter((next) => !(source === skipped.source && next === skipped.target));
+  const seen = new Set();
+  while (stack.length) {
+    const next = stack.pop();
+    if (next === target) return true;
+    if (!next || seen.has(next)) continue;
+    seen.add(next);
+    for (const child of adjacency.get(next) ?? []) stack.push(child);
+  }
+  return false;
+}
+
+export function printOrWrite(body, output) {
+  if (output) writeText(output, body);
+  else process.stdout.write(body);
+}

package/localized/zh-CN/skills/cc-drawio-studio/styles/built-in/corporate.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "corporate",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#e3f2fd", "strokeColor": "#1565c0" },
+    "success":   { "fillColor": "#e8f5e9", "strokeColor": "#2e7d32" },
+    "warning":   { "fillColor": "#fff9c4", "strokeColor": "#f57c00" },
+    "accent":    { "fillColor": "#fff3e0", "strokeColor": "#e65100" },
+    "danger":    { "fillColor": "#ffebee", "strokeColor": "#c62828" },
+    "neutral":   { "fillColor": "#eceff1", "strokeColor": "#455a64" },
+    "secondary": { "fillColor": "#f3e5f5", "strokeColor": "#6a1b9a" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=0",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=0",
+    "decision":  "rhombus",
+    "external":  "rounded=0;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Arial",
+    "fontSize": 11,
+    "titleFontSize": 13,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": ["optional", "async"]
+  },
+  "extras": {
+    "sketch": false,
+    "globalStrokeWidth": 1
+  }
+}

package/localized/zh-CN/skills/cc-drawio-studio/styles/built-in/default.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "default",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#dae8fc", "strokeColor": "#6c8ebf" },
+    "success":   { "fillColor": "#d5e8d4", "strokeColor": "#82b366" },
+    "warning":   { "fillColor": "#fff2cc", "strokeColor": "#d6b656" },
+    "accent":    { "fillColor": "#ffe6cc", "strokeColor": "#d79b00" },
+    "danger":    { "fillColor": "#f8cecc", "strokeColor": "#b85450" },
+    "neutral":   { "fillColor": "#f5f5f5", "strokeColor": "#666666" },
+    "secondary": { "fillColor": "#e1d5e7", "strokeColor": "#9673a6" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=1",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=1",
+    "decision":  "rhombus",
+    "external":  "rounded=1;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Helvetica",
+    "fontSize": 12,
+    "titleFontSize": 14,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": []
+  },
+  "extras": {
+    "sketch": false,
+    "globalStrokeWidth": 1
+  }
+}

package/localized/zh-CN/skills/cc-drawio-studio/styles/built-in/handdrawn.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "handdrawn",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#ffe4b5", "strokeColor": "#b8651e" },
+    "success":   { "fillColor": "#def0dc", "strokeColor": "#5c8a49" },
+    "warning":   { "fillColor": "#fff4cc", "strokeColor": "#b8901a" },
+    "accent":    { "fillColor": "#ffd9b3", "strokeColor": "#c25100" },
+    "danger":    { "fillColor": "#ffcdbf", "strokeColor": "#a53d3d" },
+    "neutral":   { "fillColor": "#f5e6d3", "strokeColor": "#8b7355" },
+    "secondary": { "fillColor": "#e6d7e8", "strokeColor": "#7b4397" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=1",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=1",
+    "decision":  "rhombus",
+    "external":  "rounded=1;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Helvetica",
+    "fontSize": 12,
+    "titleFontSize": 14,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;curved=1;rounded=1;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": ["optional"]
+  },
+  "extras": {
+    "sketch": true,
+    "globalStrokeWidth": 2
+  }
+}

package/localized/zh-CN/skills/cc-drawio-studio/styles/schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Agents365-ai/drawio-skill/styles/schema.json",
+  "title": "drawio-skill preset",
+  "type": "object",
+  "required": ["name", "version", "palette", "roles", "shapes", "font", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema":    { "type": "string" },
+    "name":       { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "version":    { "type": "integer", "const": 1 },
+    "default":    { "type": "boolean" },
+    "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type":          { "type": "string", "enum": ["xml", "image", "built-in", "hand-authored"] },
+        "path":          { "type": "string" },
+        "extracted_at":  { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+      }
+    },
+    "palette": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"],
+      "properties": {
+        "primary":   { "$ref": "#/$defs/colorPair" },
+        "success":   { "$ref": "#/$defs/colorPair" },
+        "warning":   { "$ref": "#/$defs/colorPair" },
+        "accent":    { "$ref": "#/$defs/colorPair" },
+        "danger":    { "$ref": "#/$defs/colorPair" },
+        "neutral":   { "$ref": "#/$defs/colorPair" },
+        "secondary": { "$ref": "#/$defs/colorPair" }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "service":  { "$ref": "#/$defs/slotName" },
+        "database": { "$ref": "#/$defs/slotName" },
+        "queue":    { "$ref": "#/$defs/slotName" },
+        "gateway":  { "$ref": "#/$defs/slotName" },
+        "error":    { "$ref": "#/$defs/slotName" },
+        "external": { "$ref": "#/$defs/slotName" },
+        "security": { "$ref": "#/$defs/slotName" }
+      }
+    },
+    "shapes": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "properties": {
+        "service":   { "type": "string" },
+        "database":  { "type": "string" },
+        "queue":     { "type": "string" },
+        "decision":  { "type": "string" },
+        "external":  { "type": "string" },
+        "container": { "type": "string" }
+      }
+    },
+    "font": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fontFamily", "fontSize"],
+      "properties": {
+        "fontFamily":    { "type": "string" },
+        "fontSize":      { "type": "integer", "minimum": 8, "maximum": 36 },
+        "titleFontSize": { "type": "integer", "minimum": 8, "maximum": 48 },
+        "titleBold":     { "type": "boolean" }
+      }
+    },
+    "edges": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["style", "arrow"],
+      "properties": {
+        "style":      { "type": "string" },
+        "arrow":      { "type": "string" },
+        "dashedFor":  { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "extras": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sketch":            { "type": "boolean" },
+        "globalStrokeWidth": { "type": "number", "minimum": 0.5, "maximum": 6 }
+      }
+    }
+  },
+  "$defs": {
+    "colorPair": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fillColor", "strokeColor"],
+          "properties": {
+            "fillColor":   { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+            "strokeColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }
+          }
+        }
+      ]
+    },
+    "slotName": {
+      "type": "string",
+      "enum": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"]
+    }
+  }
+}

package/localized/zh-CN/skills/cc-refactoring-core/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-refactoring-core
+description: 用于在保持可观察行为的前提下整理既有代码、提炼职责、搬移模块或简化结构；不要用于新增功能、改变行为的缺陷修复或依赖升级。
+---
+
+# 保持行为的重构
+
+读取并遵循[公共方法](references/method.md)，依据实际项目选择工具和专业检查，本流程不要求前端技术栈。

package/localized/zh-CN/skills/cc-refactoring-core/references/method.md

@@ -0,0 +1,16 @@
+# 保持行为的重构
+
+重构改变内部组织并保持可观察契约，使用 GREEN → REFACTOR → GREEN，不为结构变换制造失败的行为需求。
+
+1. 区分结构调整、新行为、缺陷修复和依赖迁移；行为变化进入独立流程。
+2. 阅读实现、调用方、导出、注册、持久化与测试；改动前定义结果、错误、副作用及顺序、状态变换、公共名称和协议。
+3. 建立绿色基线，或记录已有失败。关键行为缺少覆盖时补充描述当前行为的特征测试，可以从绿色开始。
+4. 诊断结构证据并排除误判。行数或复杂度指标本身不足以证明应当重写；优先选择最小安全、可回退的变换。
+5. 规划前置步骤；每步记录目标、结构意图、手法、风险、预计文件/函数、公共 API/行为变化（纯重构为零）、验证和回退边界。
+6. 一次只改一个主要结构问题，立即运行最近的有效校验并检查差异；实际范围超出预算时停止并重新评估。
+7. 新回归使当前步骤失效：只撤回当前结构步骤，验证前一基线，再缩小或调整顺序；不撤销无关用户改动，不跨无关模块扩散修复。
+8. 按受影响契约扩展验证：本地/静态、单元/集成、完整 lint/类型/测试、构建和相关专项。使用现有工具，不强制引入框架。
+
+风险依上下文判断：SAFE 为证据充分的局部私有变换，CAUTION 为跨模块/共享状态/生命周期变换，DANGER 为公共 API、schema、持久化、鉴权、权限、协议或架构级变化。手法名称不自动决定安全等级。
+
+给出证明结论：PASS 表示相关行为充分覆盖且校验通过；PARTIAL 表示已执行检查通过但仍有重要覆盖缺口；NOT PROVEN 表示证据或环境不足以证明行为保持。附实际命令、回退决定和剩余风险。

package/localized/zh-CN/skills/cc-source-driven-development/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-source-driven-development
+description: 用于工程决策依赖版本敏感的包、运行时、平台行为、公共 API 假设、官方文档、源码或指定本地知识库时。
+---
+
+# 以事实来源驱动开发
+
+读取并遵循[公共方法](references/method.md)，依据实际项目选择工具和专业检查，本流程不要求前端技术栈。

package/localized/zh-CN/skills/cc-source-driven-development/references/method.md

@@ -0,0 +1,19 @@
+# 以事实来源驱动开发
+
+使用项目事实、权威资料和对应版本的证据做工程决策。
+
+1. 明确问题、版本和本地契约。先读项目清单、配置、实现、调用方和测试；稳定的本地变换可依赖这些事实，运行时、依赖和公共 API 的变化假设需要权威核验。
+2. 收集实际版本的官方文档、源码、类型定义、发布记录、规范和迁移指南。第三方讨论只作线索。记录路径或链接、版本、日期和相关结论。
+3. 对照运行中的项目说明兼容性、维护成本、迁移范围和回退。通过小的适配边界隔离易变化的外部假设，不为追新直接推翻稳定约定。
+4. 使用项目现有校验或最小复现证明关键假设，按实际技术栈选择工具。记录命令和结果；无法验证时明确不确定性，不宣称支持。
+5. 公共接口、依赖或团队约定改变时同步轻量 ADR、迁移记录或事实文档，不复制大段外部资料。
+
+## 本地知识请求
+
+用户将来源限制在本地仓库或知识目录时，先检索指定来源，不用网络猜测补齐。使用明确路径，否则检查 `knowledge/` 是否存在；不存在则说明缺失来源，不虚构目录。
+
+有 `data_structure.md` 时先读导航并选择相关分支，渐进搜索而不加载全库。默认最多五轮关键词调整；记录文件、章节/页码/工作表、版本范围与证据缺口。PDF 和表格先选择合适提取工具。只有用户范围允许时才使用外部来源。
+
+## 证据优先级与交付
+
+实现、配置和测试确定本地契约；官方版本化文档与源码确定外部行为；规范确定平台约束；Issue 和文章仅作辅助。交付决策、来源、实现影响、验证结果及剩余不确定性，不能只说“已查文档”。

package/localized/zh-CN/skills/cc-tdd-methodology/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-tdd-methodology
+description: 用于通过测试实现新的可观察行为、修复行为缺陷，或区分测试驱动开发与纯行为保持重构时。
+---
+
+# 测试驱动开发
+
+读取并遵循[公共方法](references/method.md)，依据实际项目选择工具和专业检查，本流程不要求前端技术栈。

package/localized/zh-CN/skills/cc-tdd-methodology/references/method.md

@@ -0,0 +1,13 @@
+# 测试驱动开发
+
+新增行为和改变行为的缺陷修复使用 RED → GREEN → REFACTOR，测试描述可观察契约，不锁死内部实现结构。
+
+1. 确定一个行为：输入、输出/错误、状态变换或外部可观察副作用。沿用项目现有工具，选择最接近风险且有效的测试层。
+2. 先写能区分缺失或错误行为的最小测试并运行，观察预期行为导致的失败，不将语法、导入或环境错误当成红灯。缺陷测试必须在原缺陷存在时失败。
+3. 只实现足以通过测试的最少代码。红灯阶段不重构，不增加无关功能。
+4. 重跑测试及相关周边测试，再在保持绿色的前提下整理命名和结构；新需求进入下一轮。
+5. 报告实际红绿命令、覆盖行为和未测边界，不根据差异或未执行的测试推断成功。
+
+纯结构重构使用另一条契约：以已有测试或特征覆盖建立当前行为，保持 GREEN → REFACTOR → GREEN，不为流程形式制造失败。
+
+逻辑就近测试；真实边界用集成测试，需要完整旅程时才用端到端测试。不默认上 E2E，不断言脆弱私有状态，不仅为 TDD 引入新框架。项目缺少测试设施时先说明最小搭建方案，并在获得决定后引入；按实际技术栈选择工具，不要求前端测试工具。

package/localized/zh-CN/skills/cc-technical-diagrams/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cc-technical-diagrams
+description: 用于创建或导出结构化技术图表，包括架构图、流程图、序列图、数据流、生命周期、Agent 与记忆流、局部交互预览和 PNG 质检。需要长期手工编辑或厂商图形时使用可编辑 draw.io 源。不要用于 UI 样机、产品视觉、海报或位图编辑。
+---
+
+# 技术图表
+
+从可编辑的结构化源创建完整、清晰的技术图表，适用于前端、后端、基础设施和 Agent 系统。
+
+## 选择源格式
+
+读取[图表工作流](references/diagram-workflows.md)。标准序列图和流程图优先使用本地已有 Mermaid；自包含浏览器交付、语义架构图及 Agent/记忆流使用 HTML 技术图，读取 [HTML 技术图说明](references/html-technical-diagrams.md)。需要官方厂商形状或长期手工编辑时选择可编辑 draw.io。
+
+增量讲解可使用本地交互预览；交付时保留 JSON/SVG/PNG 导出。服务使用 [interactive-diagram-server.mjs](scripts/interactive-diagram-server.mjs)，页面使用 [interactive-diagram.html](assets/interactive-diagram.html)。
+
+## 渲染和导出
+
+保留所有节点、关系、完整标签和显式几何。渲染器支持 workflow、sequence、dataflow、lifecycle、architecture。不得静默简化高级序列语义；激活与 alt/loop/par 片段优先使用 Mermaid。
+
+```sh
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input diagram.json --type architecture --output diagram.html --manifest diagram.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input diagram.html --format png --output diagram.png --theme light --scale 2 --manifest diagram.layout.json --output-manifest diagram.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png diagram.png --manifest diagram.actual.json --format json
+```
+
+标准 Mermaid 使用 [mermaid-render.mjs](scripts/mermaid-render.mjs)。复用 [diagram-layout.mjs](scripts/diagram-layout.mjs) 和 [diagram-browser.mjs](scripts/diagram-browser.mjs)，不另造渲染器，不增加必需的浏览器库、远程脚本或下载图标包。
+
+## 验证与交付
+
+检查实际导出图像中的裁切、文字截断、标签穿线、重叠和内容遗漏。PNG QA 使用实际缩放后的导出清单，不使用源文件的估算坐标。导出成功不代表视觉验收通过。读取 [PNG 修复指导](references/png-qa-autofix.md)，修复源文件或布局，不直接修改输出像素；默认最多两轮修复，并报告未解决问题。
+
+交付 JSON/Mermaid 源、适用的 HTML、导出文件和 QA 证据。记录工具版本、主题、比例、修复轮次和部分验收状态。可选 Mermaid/Graphviz/浏览器工具缺失时明确报错或采用现有降级，不自动安装，也不宣称缺失的导出成功。保留完整标签，不用更高分辨率掩盖溢出。
+
+示例：[质量样例](assets/quality-examples/README.md)、[序列 JSON](assets/quality-examples/sequence.json)、[流程 JSON](assets/quality-examples/workflow.json)、[架构 JSON](assets/quality-examples/architecture.json)、[无效显式几何](assets/quality-examples/invalid-explicit.json)。