@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/localized/zh-CN/skills/fec-data-fetching/references/query-patterns.md

@@ -0,0 +1,103 @@
+# Server State 数据获取模式
+
+## 先判断是否需要查询库
+
+- 简单静态请求、一次性提交或已有框架 loader 足够表达的页面，不必默认引入查询库。
+- 需要跨组件缓存、去重、后台刷新、分页、乐观更新、预取或 SSR hydration 时，再使用 TanStack Query、SWR、Nuxt 数据获取或项目既有请求缓存方案。
+- 查询库只管理 server state，不替代本地 UI 状态、表单状态、权限判断或 Service Worker 缓存。
+
+## 选型参考
+
+先沿用仓库已有请求层和缓存方案；新增依赖时再按框架与复杂度选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React server state | TanStack Query / SWR / 项目既有封装 | TanStack Query 适合 mutation、invalidation 和无限查询；SWR 适合轻量读取缓存。 |
+| Vue server state | TanStack Query Vue adapter / VueUse / Nuxt `useFetch` / 项目既有封装 | 不要让 Vue 项目照搬 React-only hook 示例。 |
+| Solid / Svelte / 跨框架 | TanStack Query 对应 adapter 或项目既有资源层 | cache key、staleTime、mutation 回滚原则保持一致。 |
+| 简单页面请求 | 框架 loader、组件内轻量请求或 API composable | 仍要处理 loading/error/empty 和取消或过期响应。 |
+| SSR / SSG | 框架预取、水合或服务端数据边界 | 确保服务端 key 与客户端 key 一致，避免重复请求和水合错配。 |
+
+## 通用边界
+
+- API 函数只负责请求、解析和错误归一化，不包含 UI toast、loading 或缓存逻辑。
+- cache key/query key 必须包含所有影响响应的参数。
+- mutation 成功后按实体或列表失效；乐观更新必须先保存快照，失败时回滚。
+- 无限查询只处理数据分页；DOM 虚拟化由列表虚拟化流程处理。
+- 预取要有明确用户路径或首屏收益，不为所有可能数据提前请求。
+
+## QueryClient 默认配置
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000,
+      gcTime: 30 * 60 * 1000,
+      retry: 2,
+      refetchOnWindowFocus: true,
+    },
+  },
+});
+```
+
+## Query Key 设计
+
+- 推荐：`["users", "list", { page, status }]`
+- 详情：`["users", "detail", userId]`
+- 所有影响请求结果的参数都必须进入 key。
+
+## 乐观更新
+
+```tsx
+const mutation = useMutation({
+  mutationFn: () => api.likePost(postId),
+  onMutate: async () => {
+    await queryClient.cancelQueries({ queryKey: ["post", postId] });
+    const previousPost = queryClient.getQueryData(["post", postId]);
+    queryClient.setQueryData(["post", postId], (old: Post) => ({
+      ...old,
+      likes: old.likes + 1,
+      liked: true,
+    }));
+    return { previousPost };
+  },
+  onError: (_error, _variables, context) => {
+    queryClient.setQueryData(["post", postId], context?.previousPost);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["post", postId] });
+  },
+});
+```
+
+## 无限查询
+
+```tsx
+const feed = useInfiniteQuery({
+  queryKey: ["feed"],
+  queryFn: ({ pageParam = 1 }) => api.fetchFeed({ page: pageParam, limit: 20 }),
+  getNextPageParam: (lastPage, pages) => (lastPage.hasMore ? pages.length + 1 : undefined),
+  initialPageParam: 1,
+});
+```
+
+虚拟列表场景将数据分页与 DOM 虚拟化分开设计。
+
+## API 层整合
+
+```ts
+export async function getUserList(params: GetUserListParams): Promise<GetUserListResponse> {
+  return request.get("/api/users", { params });
+}
+
+export function useUsers(params: GetUserListParams) {
+  return useQuery({
+    queryKey: ["users", "list", params],
+    queryFn: () => getUserList(params),
+    select: (response) => response.list,
+  });
+}
+```
+
+API 函数不包含 UI toast、loading 或缓存逻辑。

package/localized/zh-CN/skills/fec-debug-framework/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: fec-debug-framework
+description: 用于诊断前端构建失败、运行时错误、UI 异常、API/数据问题、白屏、请求失败或难以解释的线上异常；中文触发词包括 调试、debug、排查、定位、报错、异常、白屏、请求失败。
+---
+
+# 前端诊断框架
+
+## 用途
+
+用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。
+
+## 流程
+
+所有前端问题诊断遵循统一流程：
+
+### Step 1: 分类（Classify）
+
+识别问题类型和影响范围：
+
+| 类型    | 判断依据                     | 诊断入口       |
+| ------- | ---------------------------- | -------------- |
+| build   | 命令退出非零、stderr 有错误  | → Build 模块   |
+| runtime | 控制台异常、白屏、功能不可用 | → Runtime 模块 |
+| ui      | 视觉偏差、交互不符预期       | → UI 模块      |
+| api     | 请求状态码异常、数据不一致   | → API 模块     |
+
+跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。
+
+### Step 2: 收集（Collect）
+
+按类型收集证据（各模块有具体策略，见下方）。
+
+### Step 3: 假设（Hypothesize）
+
+基于证据提出可能根因，按可能性排序：
+
+- 每个假设必须可测试（有明确的验证方法）
+- 最多保留 3 个假设，避免发散
+- 格式：「因为 X，导致 Y，可通过 Z 验证」
+
+### Step 4: 验证（Verify）
+
+逐一测试假设：
+
+- 从最可能的假设开始
+- 每次只改一个变量
+- 验证结果记录：证实 / 证伪 / 待定
+- 假设全部证伪时回到 Step 2 重新收集
+
+### Step 5: 修复与确认（Fix & Validate）
+
+- 应用最小修复
+- 运行受影响验证命令
+- 确认无回归
+- 输出修复报告
+
+---
+
+## 诊断模块
+
+### Build 模块
+
+**收集**：运行最小失败命令，捕获完整 stderr/stdout
+**假设**：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式
+**验证**：修一类根因 → 重跑命令 → 确认错误减少
+**特殊处理**：
+
+- 依赖版本、peer dependency、ESM/CJS、lockfile 相关失败先作为 build 兼容性问题收集证据
+- 记录 package manager、Node 版本、lockfile diff、相关包版本和完整错误日志
+- 不在缺少证据时升级依赖、手工编辑 lockfile，或把依赖迁移与普通调试修复混在同一批改动
+- 若任务目标本身是版本升级、CVE 修复或 lockfile 风险评审，应转入依赖升级工作流
+- CI 专属失败检查 Node 版本、包管理器、环境变量差异
+
+### Runtime 模块
+
+**收集**：
+
+- 复现路径（用户操作序列）
+- 控制台错误和堆栈
+- 组件渲染树状态（检查关键组件是否正确挂载）
+- 相关 store/state 快照
+
+**假设**：
+
+- 堆栈反向追踪：从异常位置回溯到触发源
+- 状态流分析：检查 state 变化是否符合预期
+- 生命周期分析：是否在错误的时机访问了未初始化的数据
+
+**验证**：
+
+- 添加临时日志确认状态值
+- 在可疑路径添加断言
+- 复现路径验证修复
+
+### UI 模块
+
+**收集**：
+
+- 当前截图 vs 期望效果
+- DOM 结构检查（元素是否存在、层级是否正确）
+- 计算样式检查（实际应用的 CSS 值）
+- 响应式断点测试
+
+**假设**：
+
+- CSS 特异性冲突（选择器权重不够被覆盖）
+- 组件状态不匹配（props/state 未正确传递）
+- 布局模型问题（flex/grid 配置错误）
+- 响应式断点遗漏
+
+**验证**：
+
+- 浏览器 DevTools 实时调整验证
+- 隔离组件测试（排除外部样式干扰）
+- 多断点逐一验证
+
+### API 模块
+
+**收集**：
+
+- 请求 URL、method、headers、body
+- 响应 status、headers、body
+- 网络瀑布时序
+- 相关 store/state 中的缓存数据
+
+**假设**：
+
+- 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
+- 数据转换检查（响应解析、类型映射）
+- 缓存策略检查（过期、失效、竞态）
+- 并发请求竞态（race condition）
+
+**验证**：
+
+- curl 独立复现（排除前端干扰）
+- 逐层 mock 定位问题层级
+- 端到端请求验证修复
+
+---
+
+## 详细参考
+
+撰写诊断报告时，加载 [references/report-template.md](references/report-template.md)。
+
+## 约束
+
+- 不在缺少证据时猜测根因
+- 不通过关闭规则、删除测试或降低类型安全来「修复」
+- 每次只改一个变量来验证假设
+- 不在验证前扩大改动范围
+- 同一假设连续 3 次验证失败，停止并报告阻塞
+
+## 预期输出
+
+- 诊断报告保存为 `reports/debug-YYYY-MM-DD-HHmmss.md`
+- 报告包含问题类型、关键证据、假设验证记录、根因、修复内容、验证结果和剩余风险
+- build/runtime/ui/api 问题均能说明复现路径、验证命令或下一步阻塞点

package/localized/zh-CN/skills/fec-debug-framework/references/report-template.md

@@ -0,0 +1,58 @@
+# 诊断报告模板
+
+```markdown
+# 前端诊断报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 问题类型: build / runtime / ui / api
+> 影响范围: 页面、功能、用户群或环境
+
+## 问题描述
+
+- 用户报告或观察到的现象
+- 首次出现时间、环境、分支或版本
+
+## 复现路径
+
+1. 操作步骤或触发命令
+2. 期望结果
+3. 实际结果
+
+## 收集的证据
+
+- 日志 / stderr / console stack
+- 截图、DOM、样式、网络请求或 trace
+- 相关配置、依赖版本、环境变量或状态快照
+
+## 假设与验证
+
+| 假设 | 验证方法 | 结果 |
+| --- | --- | --- |
+| 因为 X，导致 Y | 通过 Z 验证 | 证实 / 证伪 / 待定 |
+
+## 根因
+
+- 最终确认的根本原因
+- 为什么已有证据能支持该结论
+
+## 修复内容
+
+- 修改的文件和行为
+- 为什么这是最小有效修复
+
+## 验证结果
+
+- 执行的命令、手工路径或浏览器验证
+- 修复后观察到的结果
+
+## 剩余风险
+
+- 未覆盖的边界
+- 可能回归的区域
+
+## 下一步
+
+- 需要用户决策、后续任务或监控项
+```
+
+诊断完成后，将报告保存到 `reports/debug-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/skills/fec-dependency-upgrade/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-dependency-upgrade
+description: 用于规划、实现或审查前端依赖升级、包迁移、lockfile 变更、框架大版本升级、CVE 修复、peer dependency 冲突、ESM/CJS 切换、构建工具兼容性或 CI 验证矩阵；中文触发词包括 依赖升级、版本升级、lockfile、peer dependency、CVE 修复、大版本迁移。
+---
+
+# 依赖升级
+
+适用于前端依赖升级、漏洞修复、大版本迁移和 lockfile 风险评审。需要具体流程和检查清单时加载 [references/dependency-upgrade-workflow.md](references/dependency-upgrade-workflow.md)。
+
+## 用途
+
+用来源驱动和小批验证的方式升级依赖，降低破坏性变更、供应链风险和 CI 回归。
+
+## 流程
+
+1. 建立事实基线：读取 package manager、lockfile、Node 版本、workspace 范围、CI 命令和当前验证状态。
+2. 分类升级目标：安全修复、补丁升级、小版本升级、大版本迁移、框架迁移、构建工具迁移或依赖清理。
+3. 查证来源：对版本敏感的库读取官方 release notes、migration guide、peer dependency、Node/browser 支持和弃用项。
+4. 拆小批次：安全补丁可集中处理；大版本、构建工具、框架和测试工具必须单独批次验证。
+5. 处理兼容边界：检查 ESM/CJS、TypeScript 类型、CSS 处理、SSR/RSC、插件 API、peer dependency 和 polyfill 变化。
+6. 运行验证矩阵：至少覆盖 install、typecheck、unit/component tests、build；关键应用补 E2E、Storybook 或手工冒烟。
+7. 同步文档：记录升级原因、版本、破坏性变更、迁移命令、回滚方式和仍需人工验证的路径。
+
+## 约束
+
+- 不在缺少来源和验证的情况下进行大版本连跳。
+- 不为了消除 audit 警告盲目升级运行时关键包；先判断可利用路径和修复影响。
+- 不手工编辑 lockfile 规避依赖冲突。
+- 不把依赖升级和无关重构混在一个批次。
+- 不移除 peer dependency 或构建插件，除非有证据证明没有被运行时、子包或 CI 使用。
+
+## 预期输出
+
+输出升级清单、风险分类、来源依据、批次策略、修改范围、验证命令、失败处理和回滚建议。完成后 lockfile 与 package 清单一致，关键验证通过，破坏性变更有记录。

package/localized/zh-CN/skills/fec-dependency-upgrade/references/dependency-upgrade-workflow.md

@@ -0,0 +1,56 @@
+# 依赖升级工作流
+
+## 升级类型
+
+| 类型 | 示例 | 验证 |
+| ---- | ---- | ---- |
+| 安全补丁 | 传递依赖 CVE、patch 版本 | 安装、audit、目标测试 |
+| 小版本升级 | 兼容性功能版本 | typecheck、测试、构建 |
+| 大版本迁移 | React/Vue/Next/Vite/Storybook 大版本 | 迁移指南、完整验证矩阵 |
+| 工具链切换 | ESLint、TypeScript、bundler、test runner | 配置 diff、CI 对齐、样例失败 |
+| 清理 | 移除未使用包 | 引用搜索、构建、测试 |
+
+## 来源检查清单
+
+- 官方 release notes 或 migration guide。
+- 包管理器兼容性和 lockfile 格式。
+- Node 版本和浏览器支持范围。
+- Peer dependency 版本范围。
+- ESM/CJS 导出变化。
+- TypeScript 最低版本和类型变化。
+- SSR、RSC、edge runtime 或 browser-only 约束。
+
+## 分批策略
+
+- 框架大版本升级与样式、测试、lint 升级分开处理。
+- 当 peer 版本范围要求时，adapter 与宿主工具放在同一批升级。
+- Monorepo 中要验证受影响包，并至少验证一个消费这些包的应用。
+- 每个成功批次都记录通过的命令，必要时单独提交或单独报告。
+
+## 失败分诊
+
+1. 复现最小失败命令。
+2. 判断失败属于配置、类型表面、运行时行为还是 peer dependency。
+3. 优先采用官方迁移步骤，而不是本地临时 hack。
+4. 如果某个包阻塞当前批次，先 pin 住并记录原因；只有剩余批次仍然自洽时才继续。
+
+## 报告模板
+
+```markdown
+## 依赖升级摘要
+
+| 包 | 从 | 到 | 原因 | 风险 | 依据 |
+| -- | -- | -- | ---- | ---- | ---- |
+
+## 验证
+
+- install:
+- typecheck:
+- test:
+- build:
+- e2e/storybook/manual:
+
+## 剩余风险
+
+- ...
+```

package/localized/zh-CN/skills/fec-doc-sync/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fec-doc-sync
+description: 用于根据 package.json、lockfile、配置、env 示例、路由、API client 或 server routes、schema、组件、测试、CI、构建/部署配置、ADR、changelog 或迁移说明等事实源同步前端项目文档。不要用于单纯润色普通文案；中文触发词包括 文档同步、更新 README、docs sync、环境变量文档、命令清单、API 文档同步。
+---
+
+# 文档同步
+
+## 用途
+
+从代码、配置、测试、类型、脚本和运行时模板同步前端项目文档，避免 README、docs、环境变量说明、API/路由说明、架构决策和迁移说明与实际项目行为漂移。
+
+## 流程
+
+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. 运行相关文档一致性、旧口径搜索、报告格式一致性、类型检查、测试、构建或打包检查。
+
+## 约束
+
+- 不把 README 变成完整实现细节；公开文档保留高信号摘要。
+- 不引入与事实来源不一致的命令、路径、环境变量、API 行为或能力名称。
+- 不把未确认的 TODO、草案或实验能力写成已支持行为。
+- 不修改用户项目私有文档，除非用户明确指定。
+- 多语言文档若无法完整翻译，至少保持命令名、环境变量、路由/API 名称、版本约束和报告格式一致。
+- 不把国际化 README 同步简化成只改主 README；公共事实、功能清单、报告清单、命令/脚本说明和示例用法必须检查所有语言入口。
+- 不把 ADR 当作长篇复盘；只记录背景、决策、取舍、影响范围、验证和回滚线索。
+
+## 预期输出
+
+- 列出已同步的 README/docs/ADR/changelog/env/setup/deploy 文档。
+- 列出已检查的 README/docs 入口，并说明哪些语言文件已同步、哪些无需同步、哪些需要人工确认。
+- 总结使用的事实来源、更新范围、验证命令和未覆盖风险。
+- 汇总旧口径搜索、报告文件名/路径/命令一致性和多语言关键事实一致性验证结果。
+- 标出仍需人工确认的产品文案、翻译、外部服务配置或发布说明。

package/localized/zh-CN/skills/fec-drawio-studio/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: fec-drawio-studio
+description: 用于创建带 draw.io / diagrams.net 源文件的可编辑技术图，包括架构图、ERD、UML、序列图、流程图、ML 模型图、官方形状检索、品牌符号、Graphviz 自动布局、代码结构图、.drawio 校验或 draw.io CLI 导出兜底。不要用于普通位图生成、手绘草图、交互式 Canvas/Three.js 场景或装饰性 SVG 动画；中文触发词包括 draw.io、diagrams.net、可编辑架构图、.drawio、ER 图、UML、序列图、自动布局、形状检索、代码结构图。
+---
+
+# 可编辑技术图表工作流
+
+## 用途
+
+生成、校验和导出可继续编辑的 draw.io / diagrams.net 技术图表。
+
+## 流程
+
+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. 建立图表规格
+   - 明确图表类型、受众、输出格式、节点清单、关系、层级分组和保存位置。
+   - 用户指定 Flowchart、Architecture、Sequence、UML Class、ERD、Mindmap、Network Topology 或 ML/DL 图表时，读取 [diagram-patterns.md](references/diagram-patterns.md)。
+   - 对需要在 diagrams.net 中清晰打开的流程、工作流、审批、发布或事故响应流程图，还要读取 [flowchart-quality.md](references/flowchart-quality.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) 自动布局。
+   - 手工摆放 XML 时，将坐标对齐到 10px 网格，保持同级节点之间有充足间距，使用 `whiteSpace=wrap;html=1`，默认优先 `fontSize=14`，强制换行写作 `
`，并让容器按内容收紧，避免单侧大面积空白。
+   - 手工流程图保持 `pageWidth` 在易读的 600-800 范围内，除非明确是横向跨职能表；真实阶段使用泳道容器，循环或回滚边通过边距和显式 waypoint 绕行。
+   - 代码结构图可先用 [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
+     node skills/fec-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --width 2000
+     ```
+   - 若 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/drawio-export.mjs diagram.drawio --format png --output diagram.drawio.png --scale 2 --embed
+     node skills/fec-drawio-studio/scripts/png-embed-fix.mjs diagram.drawio.png
+     ```
+   - 报告源文件、导出文件、校验结果和无法自动验证的外部依赖。
+
+## 工具资源
+
+工具脚本共享 [studio-core.mjs](scripts/studio-core.mjs)。离线查询使用 [shape-index.json](data/shape-index.json) 与 [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)。
+
+## 约束
+
+- 不把 draw.io 用作普通图片模型；文本密集或结构化图必须保留可编辑源。
+- 不猜测复杂 `shape=mxgraph.*` 样式；优先用形状查询工具获取官方样式。
+- 不为 draw.io 工作流引入 MCP server 运行时依赖；MCP App/Tool 只作为用户环境已有时的可选互操作入口。
+- Mermaid/CSV URL 是导入捷径，不替代 `.drawio` 源文件、lint 和可编辑交付。
+- 不在预览 PNG 中嵌入 XML；嵌入只用于最终交付。
+- Graphviz、draw.io desktop 和联网品牌图标都是可选外部能力；缺失时必须降级而不是反复重试。`drawio-export.mjs` 可以探测本地 draw.io 路径并输出安装建议，但不得自动安装 draw.io。
+- 品牌图标和第三方形状索引遵循 [THIRD_PARTY_NOTICES.md](data/THIRD_PARTY_NOTICES.md) 中的来源与许可说明。
+- 参考外部 draw.io MCP 生态时，只吸收路线、约束和互操作经验，不复制其服务实现或长篇提示词。
+
+## 预期输出
+
+交付可编辑 `.drawio` 源和所需导出格式，并给出结构校验结果。图表应节点完整、连线可追踪、标签不截断、布局不重叠，外部工具缺失时提供可打开的 diagrams.net fallback。

package/localized/zh-CN/skills/fec-drawio-studio/data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,10 @@
+# 第三方声明
+
+此 skill 包含用于生成可编辑图表的精简索引和 manifest。
+
+- `shape-index.json` 包含用于本地样式检索的 draw.io 图形元数据。图形名称、尺寸和 style 字符串来自 draw.io / diagrams.net 图形生态，并继续受其上游条款约束。
+- `brand-icons.json` 是 lobe-icons CDN 资产的 manifest。lobe-icons 使用 MIT 许可；各个 logo 和名称可能是其各自所有者的商标。
+- `brand-symbols.mjs` 可能为部分基础设施和数据库符号引用 simple-icons CDN slug。simple-icons 元数据和图标遵循其上游许可；品牌商标仍归各自权利人所有。
+- 工作流文档提到可选地与外部 draw.io MCP App/Tool 部署互操作。这些服务未被本包打包、内置或设为必需。
+
+这些资源仅用于识别和渲染图表符号。重新分发包时，请保留此声明。