@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-doc-sync/SKILL.md

@@ -1,37 +1,39 @@
 ---
 name: fec-doc-sync
-description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, runtime templates, CLI commands, public skills, agents, reports, environment examples, or repository structure. Do not use for general prose polishing only; Chinese triggers include 文档同步, 更新 README, docs sync, 命令清单, 能力表同步.
+description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, lockfiles, config, env examples, routes, API clients or server routes, schemas, components, tests, CI, build/deploy config, ADRs, changelogs, or migration notes. Do not use for general prose polishing only; Chinese triggers include 文档同步, 更新 README, docs sync, 环境变量文档, 命令清单, API 文档同步.
 ---
 
 # 文档同步
 
 ## Purpose
 
-从代码、模板和元数据同步公开文档，避免 README、runtime 文档、能力表和报告说明与实际安装内容漂移。
+从代码、配置、测试、类型、脚本和运行时模板同步前端项目文档，避免 README、docs、环境变量说明、API/路由说明、架构决策和迁移说明与实际项目行为漂移。
 
 ## Procedure
 
-1. 找到事实来源：
-   - `package.json`：版本、脚本、bin、files。
-   - `skills/metadata.json`、`skills/eval_queries.json`：公开 skill 清单。
-   - `agents/`、`commands/`、`templates/shared/rules/`：安装内容。
-   - `docs/project-structure.md` 和 runtime docs：分发说明。
-2. 比对文档中的数量、名称、命令、报告文件名和运行时支持矩阵。
-3. 更新所有受影响语言版本；若仓库有多语言 README，保持信息一致。
-4. 对生成型报告或示例，只更新稳定约定，不把临时报告内容写入公开文档。
-5. 若变更来自依赖升级、架构决策或公共能力调整，同步轻量 ADR、变更说明、示例 prompt 和迁移注意事项。
-6. 运行文档/元数据一致性测试或相关打包检查。
+1. 识别项目栈、文档入口和本次需要同步的范围；README 同步必须扫描根目录 `README*`、`docs/*/README*`、包、应用、部署或运行时相关 README，并排除 `node_modules`、构建产物和第三方依赖目录。
+2. 收集事实来源：`package.json`、lockfile、框架和构建配置、`.env.example`、路由、API clients 或 server routes、types/schemas、组件、测试、CI、build/deploy config。
+3. 比对 README、docs、ADR、changelog、example prompts、setup/deploy/env docs 中的命令、环境变量、路由、API 行为、部署步骤和支持矩阵。
+4. 只更新稳定的公共约定；不要把临时调试结论、一次性报告或未落地设计写入长期文档。
+5. 若仓库已有多语言文档或国际化 README，主 README 的公共事实更新后必须检查其它语言 README 是否需要同步；功能名称、命令名、脚本名、包名、组件/API 名称、报告文件名、路径、环境变量、路由/API 名称、版本约束和支持矩阵必须跨语言一致。
+6. 产品文案可保持本地化表达，但不得保留旧事实、旧默认推荐或过期示例；无法高质量翻译时，至少同步关键事实，并在输出中标出人工翻译风险。
+7. 当项目暴露插件、SDK、CLI、组件库、模板或集成能力时，同步对应的功能清单、集成说明、命令/脚本说明、公开 metadata、示例提示词或示例用法。
+8. 运行相关文档一致性、旧口径搜索、报告格式一致性、类型检查、测试、构建或打包检查。
 
 ## Constraints
 
 - 不把 README 变成完整实现细节；公开文档保留高信号摘要。
-- 不引入与事实来源不一致的命令、路径或能力名称。
+- 不引入与事实来源不一致的命令、路径、环境变量、API 行为或能力名称。
+- 不把未确认的 TODO、草案或实验能力写成已支持行为。
 - 不修改用户项目私有文档，除非用户明确指定。
-- 多语言文档若无法完整翻译，至少保持数量、命令名、skill id、agent id 和报告格式一致。
+- 多语言文档若无法完整翻译，至少保持命令名、环境变量、路由/API 名称、版本约束和报告格式一致。
+- 不把国际化 README 同步简化成只改主 README；公共事实、功能清单、报告清单、命令/脚本说明和示例用法必须检查所有语言入口。
 - 不把 ADR 当作长篇复盘；只记录背景、决策、取舍、影响范围、验证和回滚线索。
 
 ## Expected Output
 
-- README、runtime docs、项目结构和 changelog 中的公开能力清单与代码一致。
-- 相关 metadata、marketplace 描述和测试期望同步。
-- 总结事实来源、更新范围、验证命令和仍需人工校对的翻译风险。
+- 列出已同步的 README/docs/ADR/changelog/env/setup/deploy 文档。
+- 列出已检查的 README/docs 入口，并说明哪些语言文件已同步、哪些无需同步、哪些需要人工确认。
+- 总结使用的事实来源、更新范围、验证命令和未覆盖风险。
+- 汇总旧口径搜索、报告文件名/路径/命令一致性和多语言关键事实一致性验证结果。
+- 标出仍需人工确认的产品文案、翻译、外部服务配置或发布说明。

package/skills/fec-drawio-studio/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: fec-drawio-studio
+description: Use when creating editable technical diagrams with draw.io / diagrams.net sources, including architecture diagrams, ERD, UML, sequence diagrams, flowcharts, ML model diagrams, official shape lookup, brand symbols, Graphviz auto-layout, codebase structure maps, .drawio validation, or draw.io CLI export fallback. Do not use for ordinary raster image generation, freehand sketches, interactive canvas/Three.js scenes, or decorative SVG animation. Chinese triggers include draw.io, diagrams.net, 可编辑架构图, .drawio, ER 图, UML, 序列图, 自动布局, 形状检索, 代码结构图.
+---
+
+# 可编辑技术图表工作流
+
+## Purpose
+
+生成、校验和导出可继续编辑的 draw.io / diagrams.net 技术图表。
+
+## Procedure
+
+1. 判断图表路线
+   - 需要长期维护在 Markdown 中的简单图，优先 Mermaid。
+   - 需要官方图标、泳道、复杂布局、层/标签/元数据、可编辑 PNG/SVG/PDF 或 `.drawio` 源时，使用本工作流。
+   - 需要快速浏览器打开或分享时，用 [diagram-url.mjs](scripts/diagram-url.mjs) 生成 URL；需要本地可审计交付时，始终保存 `.drawio` 源。
+   - 用户已经有 Mermaid 或 CSV 内容时，可用 `diagram-url.mjs --create --type mermaid|csv` 交给 diagrams.net 导入；需要长期维护或精确形状时，再转成 XML。
+   - 如果当前宿主已经配置 draw.io MCP App/Tool，可把它作为预览或编辑入口；本 skill 不要求安装 MCP server。
+   - 需要照片、海报、视觉概念或位图编辑时，走图片生成路线。
+
+2. 建立图表规格
+   - 明确图表类型、受众、输出格式、节点清单、关系、层级分组和保存位置。
+   - 用户指定 ERD、UML、Sequence、Architecture、ML/DL 或 Flowchart 时，读取 [diagram-patterns.md](references/diagram-patterns.md)。
+   - 需要选择 XML、Mermaid、CSV、容器、层、标签、metadata 或暗色模式策略时，读取 [xml-and-mermaid.md](references/xml-and-mermaid.md)。
+   - 需要特定厂商/云/网络/流程图形状时，运行 [shape-query.mjs](scripts/shape-query.mjs)；需要 AI、数据库或基础设施品牌符号时，运行 [brand-symbols.mjs](scripts/brand-symbols.mjs)。
+
+3. 生成 `.drawio` 源
+   - 小图可手工生成 draw.io XML，保持节点坐标、尺寸和连线清晰。
+   - 超过约 15 个节点、依赖图或代码结构图时，先生成 graph JSON，再用 [layout-graph.mjs](scripts/layout-graph.mjs) 自动布局。
+   - 代码结构图可先用 [scan-js-modules.mjs](scripts/scan-js-modules.mjs)、[scan-ts-modules.mjs](scripts/scan-ts-modules.mjs)、[scan-python-modules.mjs](scripts/scan-python-modules.mjs)、[scan-go-packages.mjs](scripts/scan-go-packages.mjs)、[scan-rust-modules.mjs](scripts/scan-rust-modules.mjs) 或 [scan-python-classes.mjs](scripts/scan-python-classes.mjs) 生成 graph JSON。
+
+4. 校验和预览
+   - 每次生成 `.drawio` 后运行：
+     ```bash
+     node skills/fec-drawio-studio/scripts/diagram-lint.mjs diagram.drawio --format markdown
+     ```
+   - 若本机有 draw.io desktop CLI，导出预览 PNG 时不要嵌入 XML，并控制宽度：
+     ```bash
+     drawio -x -f png --width 2000 -o diagram.png diagram.drawio
+     ```
+   - 若 CLI 不可用，用 [diagram-url.mjs](scripts/diagram-url.mjs) 生成 diagrams.net viewer/editor URL；严格离线或数据驻留敏感时先读取 [data-residency.md](references/data-residency.md)。
+
+5. 交付最终产物
+   - 保存 `.drawio` 源文件和用户需要的 PNG/SVG/PDF/JPG。
+   - 最终 PNG 若使用 draw.io `-e` 嵌入 XML，导出后运行：
+     ```bash
+     node skills/fec-drawio-studio/scripts/png-embed-fix.mjs diagram.drawio.png
+     ```
+   - 报告源文件、导出文件、校验结果和无法自动验证的外部依赖。
+
+## Tool Resources
+
+工具脚本共享 [studio-core.mjs](scripts/studio-core.mjs)。离线查询使用 [shape-index.json.gz](data/shape-index.json.gz) 与 [brand-icons.json](data/brand-icons.json)，样式预设资源包括 [schema.json](styles/schema.json)、[default.json](styles/built-in/default.json)、[corporate.json](styles/built-in/corporate.json) 和 [handdrawn.json](styles/built-in/handdrawn.json)。
+
+## Constraints
+
+- 不把 draw.io 用作普通图片模型；文本密集或结构化图必须保留可编辑源。
+- 不猜测复杂 `shape=mxgraph.*` 样式；优先用形状查询工具获取官方样式。
+- 不为 draw.io 工作流引入 MCP server 运行时依赖；MCP App/Tool 只作为用户环境已有时的可选互操作入口。
+- Mermaid/CSV URL 是导入捷径，不替代 `.drawio` 源文件、lint 和可编辑交付。
+- 不在预览 PNG 中嵌入 XML；嵌入只用于最终交付。
+- Graphviz、draw.io desktop 和联网品牌图标都是可选外部能力；缺失时必须降级而不是反复重试。
+- 品牌图标和第三方形状索引遵循 [THIRD_PARTY_NOTICES.md](data/THIRD_PARTY_NOTICES.md) 中的来源与许可说明。
+- 参考外部 draw.io MCP 生态时，只吸收路线、约束和互操作经验，不复制其服务实现或长篇提示词。
+
+## Expected Output
+
+交付可编辑 `.drawio` 源和所需导出格式，并给出结构校验结果。图表应节点完整、连线可追踪、标签不截断、布局不重叠，外部工具缺失时提供可打开的 diagrams.net fallback。

package/skills/fec-drawio-studio/data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,10 @@
+# Third Party Notices
+
+This skill includes compact indexes and manifests used to produce editable diagrams.
+
+- `shape-index.json.gz` contains draw.io shape metadata used for local style lookup. Shape names, dimensions and style strings come from the draw.io / diagrams.net shape ecosystem and remain subject to their upstream terms.
+- `brand-icons.json` is a manifest for lobe-icons CDN assets. lobe-icons is MIT licensed; individual logos and names may be trademarks of their respective owners.
+- `brand-symbols.mjs` may reference simple-icons CDN slugs for selected infrastructure and database symbols. simple-icons metadata and icons are available under their upstream license; brand trademarks remain owned by their respective holders.
+- The workflow documents mention optional interoperability with external draw.io MCP App/Tool deployments. Those services are not bundled, vendored or required by this package.
+
+These resources are used only to identify and render diagram symbols. Keep this notice with redistributed packages.