@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/docs/runtimes/opencode.md

@@ -1,10 +1,18 @@
-# frontend-craft: opencode
-
-See root README **Universal Install** and run:
-
-```bash
-npx @bovinphang/frontend-craft install opencode
-```
-
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
-
+# frontend-craft: OpenCode
+
+```bash
+fec setup opencode
+fec setup opencode --global
+fec doctor opencode --local
+fec doctor opencode --global
+```
+
+Without a global CLI installation, use `npx @bovinphang/frontend-craft install opencode --local` or `--global`.
+
+Project base: `.opencode`; user base: `~/.config/opencode` (`XDG_CONFIG_HOME` / `OPENCODE_CONFIG_DIR` supported). Skills use `skills/`; commands use `commands/`. The generated `opencode.jsonc` uses `permission`, not `permissions`. The exact old generated template is repaired; custom JSONC is preserved. Unchanged manifest-owned `command/` files migrate to `commands/`.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://opencode.ai/docs/config/) · [Compatibility and upgrade notes](compatibility.md)
+
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/qoder.md

@@ -1,19 +1,18 @@
-# frontend-craft: qoder
-
-See root README **Universal Install** and run:
-
-```bash
-npx @bovinphang/frontend-craft install qoder
-```
-
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. Local installs write to `.qoder/`; global installs write to `~/.qoder` or `QODER_CONFIG_DIR`.
-
-Installed assets:
-
-- `skills/` -> `.qoder/skills/`
-- `commands/` -> `.qoder/commands/`
-- `agents/` -> `.qoder/agents/`
-- shared rules -> `.qoder/rules/`
-- hook scripts -> `.qoder/hooks/`
-- hook configuration -> `.qoder/settings.json`
-
+# frontend-craft: Qoder
+
+```bash
+fec setup qoder
+fec setup qoder --global
+fec doctor qoder --local
+fec doctor qoder --global
+```
+
+Without a global CLI installation, use `npx @bovinphang/frontend-craft install qoder --local` or `--global`.
+
+Project base: `.qoder`; user base: `~/.qoder` (`QODER_CONFIG_DIR` override). Skills, agents and commands are installed in their named directories; project rules go in `rules/`. Hooks are merged into `settings.json`, with absolute global script paths and deduplicated entries. Invalid settings JSON stops installation. Known unchanged legacy relative global hooks are replaced. This adapter does not configure MCP.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.qoder.com/cli/hooks) · [Compatibility and upgrade notes](compatibility.md)
+
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/trae.md

@@ -1,10 +1,18 @@
-# frontend-craft: trae
-
-See root README **Universal Install** and run:
-
-```bash
-npx @bovinphang/frontend-craft install trae
-```
-
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
-
+# frontend-craft: Trae
+
+```bash
+fec setup trae
+fec setup trae --global
+fec doctor trae --local
+fec doctor trae --global
+```
+
+Without a global CLI installation, use `npx @bovinphang/frontend-craft install trae --local` or `--global`.
+
+Project rules: `.trae/rules/frontend-craft.md`; user rules: `~/.trae/user_rules/frontend-craft.md` (`TRAE_CONFIG_DIR` base override). Both include explicit `alwaysApply: true` metadata. This adapter installs rules, not native skills, agents or MCP configuration.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.trae.ai/ide/rules) · [Compatibility and upgrade notes](compatibility.md)
+
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/windsurf.md

@@ -1,10 +1,18 @@
-# frontend-craft: windsurf
-
-See root README **Universal Install** and run:
-
-```bash
-npx @bovinphang/frontend-craft install windsurf
-```
-
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
-
+# frontend-craft: Windsurf
+
+```bash
+fec setup windsurf
+fec setup windsurf --global
+fec doctor windsurf --local
+fec doctor windsurf --global
+```
+
+Without a global CLI installation, use `npx @bovinphang/frontend-craft install windsurf --local` or `--global`.
+
+Project skills/workflows: `.windsurf/skills` and `.windsurf/workflows`. User skills: `~/.codeium/windsurf/skills`; user workflows: `~/.codeium/windsurf/global_workflows` (base override: `WINDSURF_CONFIG_DIR`). Project rules retain the supported `.windsurf/rules` layout. Unchanged manifest-owned legacy global workflows are retired on update.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.windsurf.com/windsurf/cascade/workflows) · [Compatibility and upgrade notes](compatibility.md)
+
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/superpowers/plans/2026-09-26-content-integrity.md

@@ -0,0 +1,145 @@
+# Content Integrity and Validation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
+
+**Goal:** 修复内容声明错误，以共享 YAML 解析、自动测试发现和 pnpm 质量门禁防止再次发生。
+
+**Architecture:** frontmatter 解析属于共享安装基础设施，转换器和发布脚本只消费已校验字段。内容审查负责文件集合、引用和本地化结构；测试发现与 lint 是独立维护工具，发布 CLI 内置 YAML 解析器。
+
+**Tech Stack:** TypeScript / Node.js >=22.0.0 / node:test / tsx / esbuild / YAML 2.9.0 / pnpm 12.4.1 / ESLint flat config / Prettier。
+
+**Spec:** [2026-09-26-project-optimization-design.md](../specs/2026-09-26-project-optimization-design.md)，仅实施“子项目一”；后续子项目另列计划。
+
+## Global Constraints
+
+- 在当前工作区上增量修改，保留已有未提交工作。
+- 遵循用户 pnpm 约定，不提交、不发布。
+- 保留现有公开 skill / command / agent ID、安装路径、更新保护行为与独立技能分发能力。
+- 新增行为以失败案例证明后修复。
+- 不以正则匹配不到列表作为空列表成功处理。
+- 保持已有可选字段允许省略，不擅自要求所有 agent 拥有相同权限或相同技能。
+- 暂不并行安装，不改变修改文件跳过与卸载保护策略。
+- 当前基线已有 195 项通过测试；本地 node=v24.14.1、pnpm=12.4.1、yaml=2.9.0，CI 继续验证 Node 22.x 和 Windows/Linux。
+- 不自动 git add / commit；设计技能的提交步骤由用户“未经确认不 commit”的要求覆盖。
+
+## Review Focus
+
+1. description 含引号、反斜杠、换行以及正文含三重引号时，YAML → TOML 转换必须保留真实值（任务 1、3）。
+2. 缺少可选字段合法，声明错误或空 skills 列表非法；未知引用必须报源文件，不能静默跳过（任务 1、2）。
+3. command 与 skill 同名时，不能覆盖独立技能；新解析器不能误把已转换的 skill schema 当原始 command（任务 3）。
+4. 发布包在没有仓库 node_modules 的环境中仍可安装 Codex / OpenClaw 内容，不能依赖 yaml devDependency（任务 3）。
+5. 新测试文件含空格路径、测试根为空或测试子进程失败时，发现器分别正确执行、拒绝空集、返回失败；不借助 shell 拼接（任务 4）。
+
+## Files and Ownership
+
+| 文件 | 职责 |
+| --- | --- |
+| src/install/shared/frontmatter.ts | YAML 文档解析、三类内容字段类型和校验 |
+| src/install/shared/content-audit.ts | 内容树校验、本地化结构、引用检查 |
+| scripts/check-content.ts | 内容审查 CLI |
+| src/install/codex-agents.ts | 解析后字段的 TOML 安全转换 |
+| src/install/shared/command-skills.ts | 解析后 command 生成 skill，保留同名跳过 |
+| scripts/skill-packaging.ts、scripts/audit-skills.ts | 复用解析器，消除 description 引号误读 |
+| scripts/run-tests.ts | 测试递归发现、排序和进程状态转发 |
+| scripts/check-format.ts、eslint.config.mjs | 格式检查与静态代码检查 |
+| agents/*.md、commands/*.md、对应中文文件 | 内容语法及名称修复 |
+| package.json、pnpm-lock.yaml、.github/workflows/ci.yml | 依赖、统一命令和 CI |
+| CONTRIBUTING.md、CONTRIBUTING.zh-CN.md、PR 模板 | 真实维护步骤与产物路径 |
+| tests/install/*.test.ts、tests/converters/codex-agents.test.ts | 行为回归与发布包验证 |
+
+## Task 1: Shared YAML Parser and Typed Schemas
+
+**Files:** Create src/install/shared/frontmatter.ts and tests/install/frontmatter.test.ts; modify package.json / pnpm-lock.yaml to add yaml@2.9.0 as a direct devDependency.
+
+**Interfaces:**
+
+- `parseFrontmatter(raw: string, source: string): { fields: Record<string, unknown>; body: string }`。
+- `parseSkillDocument(raw: string, source: string, expectedName?: string): { metadata: BaseMetadata; body: string }`。
+- `parseCommandDocument(raw: string, source: string, expectedName?: string): { metadata: BaseMetadata; body: string }`。
+- `parseAgentDocument(raw: string, source: string, expectedName?: string): { metadata: AgentMetadata; body: string }`。
+- `BaseMetadata = { name: string; description: string }`；`AgentMetadata` 扩展可选 tools:string、model:string、permissionMode:"default"|"acceptEdits"、maxTurns:number、skills:string[]、mcpServers:string[]。已存在仓库内容如需其他合法字段，先显式加入 schema，禁止静默放行未知字段。
+- 本阶段原始 skill / command 仅允许 name、description；生成的 user-invocable skill 不进入原始内容审查。
+
+- [x] 写 `frontmatter.test.ts`：`rejects duplicate YAML keys`、`rejects nonmapping frontmatter`、`rejects malformed agent lists`、`allows omitted optional fields`、`decodes quoted and multiline descriptions`、`rejects mismatched names`；断言错误包含 source，语法错误包含行列，skills=[] / string / duplicate 失败，maxTurns 必须为正整数。
+- [x] 用 `pnpm exec node --import tsx --test tests/install/frontmatter.test.ts` 确认因模块未实现而失败。
+- [x] 添加直接 yaml 依赖，实现上述接口；YAML uniqueKeys=true，限制 alias 展开，不通过类型断言假装未知字段有效。保留 LF / CRLF 下的正文，不把 frontmatter 的换行变化传播到正文。
+- [x] 同一命令确认通过；运行 `pnpm typecheck` 确认签名与 NodeNext imports 正确。
+
+## Task 2: Repository Content Audit and Actual Repairs
+
+**Files:** Create src/install/shared/content-audit.ts, scripts/check-content.ts, tests/install/content-audit.test.ts; modify tests/install/metadata-consistency.test.ts, affected English agents/commands and both fec-review commands.
+
+**Interfaces:**
+
+- 消费任务 1 的三个 schema 函数。
+- `auditContent(root: string): string[]` 返回完整的路径定位诊断，空数组表示通过；不修改内容。脚本汇总 stderr，存在诊断时退出 1。
+- 校验英文与中文 agents / commands / skills 文件集合一致；name 和 agent 的 tools/model/permissionMode/maxTurns/skills/mcpServers 结构值一致，description / 正文不比较。
+- agent skills 必须存在且无重复；Markdown 反引号 token 若为 `fec-` ID，属于 agent / command / skill 的显式引用时必须存在。内部约定示例 ID 或工具脚本名称不当作能力 ID；单独禁止 `typescript-reviewer` 作为 agent 引用，修为 `fec-typescript-reviewer`。
+
+- [x] 写 fixture 测试：`rejects invalid YAML instead of skipping skills`、`reports unknown agent skill`、`reports missing localized file`、`reports localized agent structure drift`、`allows translated descriptions`；断言返回数组有来源路径，合法中英文异文通过。
+- [x] 运行 `pnpm exec node --import tsx --test tests/install/content-audit.test.ts` 确认失败。
+- [x] 实现 auditContent 和 CLI，用同一解析器替换 metadata 测试中 regex-only 字段检查；原有计数、关系、语言与链接测试保留。
+- [x] 运行 `pnpm exec tsx scripts/check-content.ts`，确认现有 13 个无效 frontmatter 与错误引用被报告。
+- [x] 对有问题的 description 安全引用，修正英文 fec-ui-checker 列表及 permissionMode 空格，修正中英文 review 引用；如结构校验发现更多既有差异，按英文/中文实际职责核实并修复，不删除测试使其通过。
+- [x] 重跑 fixture、metadata 测试和内容 CLI，确认全部通过；输出仍是 14 agents / 11 commands / 56 skills，不改变 ID。
+
+## Task 3: Converters and Publish Packaging Use Parsed Values
+
+**Files:** Modify src/install/codex-agents.ts, src/install/shared/command-skills.ts, scripts/skill-packaging.ts, scripts/audit-skills.ts, scripts/build-dist.ts, tests/converters/codex-agents.test.ts, tests/install/skill-package.test.ts, tests/install/npm-pack.test.ts; create tests/install/command-skills.test.ts.
+
+**Interfaces:** 保留 agentMdToToml(raw, filename)、installCommandSkills(commandsDir, skillsDir)、parseSkillFrontmatter(body, skillId) 的现有外部签名；内部调用任务 1 解析器。name 与 filename 一致，原测试中的 x.md 改为真实匹配的 fec-test-agent.md。
+
+- [x] 增加转换回归：quoted description 输出不带额外引号，newline / backslash / triple quote 安全转义；正文继续适配 .claude/rules 和 CLAUDE.md。用工作区可用的 TOML parser 或明确字符串 round-trip fixture 证明输出值，不仅检查字段存在。
+- [x] 增加 command fixture：非法 YAML 抛错不生成目标文件、有效 quoted description 正确生成、与技能同名不覆盖、CRLF 正文完整。增加独立技能打包 description 解码回归。
+- [x] 跑上述定向测试，确认旧转换器失败。
+- [x] 改为共享 schema；TOML 字符串按规范转义控制字符及引号，正文三重引号需安全处理。无效 command 不再默认为 Run workflow 并掩盖错误。
+- [x] 将 CLI bundle 的 packages 策略改为 bundle，Node 内建模块保持外部；其他 hook / OpenClaw 策略不变。yaml 是开发依赖但被内置，不添加发布时隐式安装步骤。
+- [x] 发布测试在临时目录复制 npm dry-run 列出的文件，不复制 node_modules；用复制的 CLI 执行 Codex 和 OpenClaw 本地安装，验证解析器可用及产物描述值正确；临时 HOME 与 cwd 隔离。
+- [x] 运行 `pnpm build`，再运行 converter、command-skills、skill-package、npm-pack 四组定向测试，全部通过。
+
+## Task 4: Automatically Discover Tests
+
+**Files:** Create scripts/run-tests.ts and tests/install/test-discovery.test.ts; modify package.json test:only。
+
+**Interfaces:** `discoverTests(root: string): string[]` 返回绝对路径并按相对 POSIX 路径排序；`runTests(root: string): number` 用 process.execPath 与 argv 数组 spawnSync（shell:false），附加 `--import tsx --test --test-concurrency=1`，继承 stdio，返回非零子进程状态，signal / 无 status 映射为 1。main 通过 import.meta.url 检查，仅直接执行时运行，支持 `--root` 测试 fixture。
+
+- [x] 添加 `discovers nested test files in stable order`、`runs a newly added test without script changes`、`handles spaces in test paths`、`fails when no tests exist`、`propagates child failure`。测试 fixture 的 .test.ts 使用 node:test，保证实际执行并断言 exit code / marker。
+- [x] 用 `pnpm exec node --import tsx --test tests/install/test-discovery.test.ts` 确认失败。
+- [x] 实现发现器，只遍历普通目录/文件，不跟随符号链接；排除 node_modules 与生成目录，递归查找 *.test.ts。test:only 设为 `tsx scripts/run-tests.ts`，发现器不调用 pnpm test 避免递归。
+- [x] 定向测试通过；运行完整 `pnpm test` 确认原有及新增用例均被执行，无手写清单。
+
+## Task 5: pnpm Quality Gates and Maintenance Docs
+
+**Files:** Create eslint.config.mjs, scripts/check-format.ts, tests/install/tooling-contract.test.ts; modify package.json, pnpm-lock.yaml, .github/workflows/ci.yml, .github/pull_request_template.md, CONTRIBUTING.md / CONTRIBUTING.zh-CN.md and existing tests mentioning actual maintenance commands; retire root package-lock.json。
+
+**Interfaces:** `format:check` 使用 `tsx scripts/check-format.ts` 检查本次变更的源文件及配置；`check:content` 调用脚本；`lint:code` 执行 ESLint；`lint` 顺序执行 lint:code 和 check:content。现有 build、test、pack 名称保留。
+
+- [x] 写 tooling contract：packageManager=`pnpm@12.4.1`；test:only 自动发现；CI frozen-lockfile 与 lint 有门禁；version script 不 git add / 引用 package-lock；产物表路径与 build entry 表对应。
+- [x] 跑定向测试，确认既有工具链不满足契约。
+- [x] 引入兼容 Node 22 的 ESLint、@eslint/js、typescript-eslint、globals；按官方 flat recommended 配置，限定 bin/src/scripts/tests，忽略生成内容。unused 参数允许 `_` 前缀，no-empty 允许有意空 catch；不全局关闭 correctness 规则，存量问题用小范围等价修复。
+- [x] 固定 packageManager 与依赖版本，更新 pnpm-lock；保留既有不相关依赖解析版本。开发嵌套 npm run 改 pnpm run，version 只同步元数据不自动 stage；npm pack/publish 保留。通过 patch 删除已批准退役的 package-lock，不用递归 shell 删除。
+- [x] CI 在 setup-node 缓存前安装固定 pnpm，然后使用 pnpm 缓存、install --frozen-lockfile、lint、pack:all、typecheck:openclaw。Node floor 保留 >=22.0.0；贡献者通过 npm 安装 pnpm 12 需 Node >=22.13，明确与插件运行时要求不同。
+- [x] 实现 format checker：git diff HEAD + 未跟踪普通文件，argv 调用 Git，无 shell；限定 bin/src/scripts/tests 的 .ts/.mjs 与 package.json / eslint.config.mjs，过滤不存在/生成文件，调用 Prettier API check，不修改。非 Git 发布目录不要求运行此维护命令。
+- [x] 更新中英文贡献流程、PR 清单和 hook 路径；多包管理器测试 fixture 保持支持 npm/yarn/bun，不因本仓库迁移改掉消费者兼容行为。
+- [x] 修复本次触及源文件的格式，运行 `pnpm lint`、`pnpm format:check`、`pnpm typecheck`、`pnpm install --frozen-lockfile`；全部退出 0。
+
+## Task 6: Final Verification and Review
+
+**Files:** 更新本计划复选框，创建 reports/content-integrity-implementation-2026-09-26.zh-CN.md；修复审查发现只限上述范围。
+
+- [x] 检查 git diff，仅本阶段新增修改，保留用户基线；不切换到缺少用户未提交工作的 checkout。
+- [x] 顺序执行 `pnpm lint`、`pnpm format:check`、`pnpm typecheck`、`pnpm typecheck:openclaw`、`pnpm pack:all`、`pnpm audit:skills`。pack:all 已含 build 与全测试，不另外重复整套测试。
+- [x] 确认 15 个运行时 local/global 安装、更新保护、卸载、同名 command 跳过、独立技能包和隔离发布环境测试通过。
+- [x] 做独立最终审查；若选择 native，由我实施，最后交由新 reviewer 检查，保留其证据报告。若用户选择 subagent-driven，遵循对应技能逐任务实施/评审。
+- [x] 报告本次文件、错误修复、工具链迁移、验证数量与未验证真实运行时加载的限制。无 commit / 发布，不宣称四阶段全部完成。
+
+## Self-Review
+
+第一阶段设计覆盖：内容修复→任务 2；共享 parser→1/3；英文中文验证→2；lint / format / CI / pnpm→5；测试发现→4；发布可运行→3/6。五项 Review Focus 均归入测试步骤。task 1 的可选字段与 task 2 的引用检验分工明确；阶段二至四不混入此计划。设计要求没有空缺。
+
+## Sources and Execution Choice
+
+pnpm 版本与安装前提依据 [pnpm installation](https://pnpm.io/installation/)；flat config 依据 [typescript-eslint Quickstart](https://typescript-eslint.io/getting-started/)。实施时只选符合 peerDependencies 与 Node 22 要求的版本，不盲目安装 latest。
+
+建议 native：由当前会话顺序实施，最后独立审查。共享解析器、内容校验和转换器之间依赖紧密，顺序实施能减少接口返工。用户已批准设计、计划并选择当前会话执行。第一阶段已实施与验证，独立审查完成；非阻塞的诊断提示问题记录在实施报告中。
+

package/docs/superpowers/plans/2026-09-26-diagram-quality.md

@@ -0,0 +1,170 @@
+# Diagram Quality Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 改善时序图、流程图和架构图的真实成图质量，修复文字、布局、连线与导出，并以 PNG 视觉检查验证。
+
+**Architecture:** 标准时序与流程图优先 Mermaid，架构图复用 draw.io；现有 JSON/HTML 路线保持兼容并修复质量缺陷。将文字与几何计算、浏览器测量/导出拆为技能内部可复用模块，由现有 CLI 消费；PNG QA 检查扩展 manifest，工作流完成源级修复和人工视觉验收。
+
+**Tech Stack:** Node.js >=22.0.0、ESM `.mjs` + JSDoc、node:test / tsx、SVG、Chromium CDP；可选本地 Mermaid CLI、draw.io desktop、Graphviz。不新增强制外部依赖。
+
+**Spec:** [2026-09-26-diagram-quality-design.md](../specs/2026-09-26-diagram-quality-design.md)；用户于本轮明确回复“设计通过”。
+
+## Global Constraints
+
+- 当前工作区增量修改，保留全部已有未提交工作；版本仍为 2.9.0，不提交、不发布、不创建标签。
+- 保留现有公开命令、JSON schema_version、图种、输入字段、报告字段及输出格式；扩展字段向后兼容。
+- Mermaid、draw.io、Graphviz 可选，不自动安装、下载或使用 CDN；不要求独立安装的 skill 拥有仓库 node_modules。
+- 显式坐标、尺寸和 waypoints 不静默重排；无法满足布局约束时报告，不删字、不改连接关系。
+- 自动修复默认最多两轮，用户要求时最多五轮；修复源而非 PNG 像素。仍有缺陷时标记部分验收。
+- 每类图需要实际 PNG 和视觉审阅。自动检查、模拟 CLI 和字符串测试不能替代成图证据。
+- 中英文脚本保持字节一致；本技能内 helper 使用相对导入并随独立技能包交付。
+- 当前机器可用 Node、pnpm 和本地 Edge；PATH 未检测到 mmdc、drawio、dot。不得将缺失工具的模拟测试计为真实运行通过。
+
+## Review Focus
+
+1. 中文、emoji、英文长单词、换行及 XML 特殊字符：不丢字，正确转义，实际浏览器边界可读（任务 1、5）。
+2. 显式尺寸太小、坐标重叠、waypoints 越界：保持源意图并定位问题，不偷偷改布局（任务 2、3、6）。
+3. 自调用、双向/平行连接、分支回环：保留方向和关系，端口位于轮廓，标签不覆盖箭头（任务 3、4、6）。
+4. 独立 SVG、主题变化、字体加载和 2x 导出：预览/导出同主题一致，manifest 全字段缩放（任务 5、6）。
+5. Windows 路径含空格/中文、工具缺失、子进程超时和 stale 输出：不执行拼接 shell，不伪报成功，不依赖包外脚本（任务 5、7、8）。
+
+## File Structure and Interfaces
+
+所有路径相对项目根。英文脚本位于 `skills/fec-image-generation/scripts/`，其中文镜像位于 `localized/zh-CN/skills/fec-image-generation/scripts/`。
+
+| 单元 | 文件 | 职责 |
+| --- | --- | --- |
+| 文字与几何 | 新增 `diagram-layout.mjs` | Unicode 文字布局、轮廓端口、避障路径、标签位置与画布边界 |
+| 现有渲染 | 修改 `tech-diagram-render.mjs` | 消费布局结果、输出完整 SVG、HTML 和扩展 manifest |
+| 浏览器能力 | 新增 `diagram-browser.mjs` | Chromium 检测、CDP 会话、字体等待、真实边界、冻结样式和导出 |
+| 导出入口 | 修改 `export-diagram.mjs` | 参数校验、独立 SVG、PNG/JPG、实际 manifest 和质量报告 |
+| 质量检测 | 修改 `png-qa.mjs` | 旧 manifest 兼容、文字与边碰撞、分组包含、退化连接 |
+| 成熟工具入口 | 新增 `mermaid-render.mjs` | 检测本地 CLI、安全调用、报告版本和产物状态 |
+| 证据 | 新增 `assets/quality-examples/` 内 JSON、MMD 与 README | 三类图、失败样例、复现命令 |
+| 测试 | 现有 `tests/install/image-generation-skill.test.ts`；新增 `tests/install/diagram-quality.test.ts` | 旧行为、布局、实际 Chromium、工具回退和镜像验证 |
+
+新增脚本加入 `package.json` 的 `typecheck:skill-scripts`；不改依赖和版本。中英文 SKILL 链接全部 helper 与样例索引，保证独立包发布检查能找到内容。
+
+公共内部类型均由 JSDoc 定义，复用原 Box/Connector 字段：
+
+- `TextLayout = { lines: string[], width: number, height: number, fontSize: number, lineHeight: number }`。
+- `Rect = { x: number, y: number, width: number, height: number }`；`Point = [number, number]`。
+- `QualityIssue = { code: string, id: string, message: string }`。
+- 扩展 manifest 保留 `canvas/boxes/connectors`，新增 `coordinateSpace: 'svg'|'png'`、`scale`、`groups: Rect[]`、`labels: Array<Rect & {id, owner, text, kind:'node'|'edge'|'group', lines:string[]}>`、`issues: QualityIssue[]`、`measurement:'estimated'|'browser'`。旧 manifest 不含新字段时按旧行为检测。
+- 渲染报告保留原字段，新增 `quality: { status:'estimated'|'passed'|'partial', issues:QualityIssue[] }`；静态渲染最多为 estimated，不能自称浏览器验证通过。
+
+## Task 1: 完整文字布局与 SVG 文字输出
+
+**Files:** 新增 diagram-layout.mjs；修改 tech-diagram-render.mjs；新增 diagram-quality.test.ts。
+
+**Interfaces:** `layoutText(text:string, maxWidth:number, fontSize=14, lineHeight=20):TextLayout`；`fitNodeText(box:Box, explicit:{width:boolean,height:boolean}):{box:Box, labels:TextLayout[], issues:QualityIssue[]}`。每个返回行完整保留源文字，换行仅影响布局。
+
+- [ ] 写失败测试：`labels preserve Chinese, emoji, explicit breaks and long tokens`，断言去除布局换行后的内容与原文一致，超过两行仍全部输出；`labels escape XML without losing content`；`small explicit boxes report overflow`，断言尺寸不改且问题含节点 ID。
+- [ ] 运行 `pnpm exec tsx --test tests/install/diagram-quality.test.ts`，确认旧实现截断或模块缺失导致失败。
+- [ ] 使用 `Intl.Segmenter` 以 grapheme 换行，CJK/emoji 按 fontSize、ASCII 按 0.6×fontSize 初估；保留显式换行，不用字符数硬截断。默认主文 14px/20px、次文 12px/16px、内边距 16px；图标、actor、编号、副标题各自留位。默认最小普通节点 140×72；决策菱形以中间安全矩形计算内容并扩展自动尺寸。
+- [ ] renderBox 从 TextLayout 输出所有 tspan/文字行，不再 `.slice(0,2)`；记录 labels 的文字、行和估算边界。错误尺寸非正数或非有限数仍属于输入错误。
+- [ ] 运行新测试及 `pnpm exec tsx --test tests/install/image-generation-skill.test.ts`，全部通过；记录仍需任务 5 浏览器测量的估算性质。
+
+## Task 2: 内容驱动的泳道与架构画布
+
+**Files:** diagram-layout.mjs、tech-diagram-render.mjs、diagram-quality.test.ts。
+
+**Interfaces:** `layoutLanes(lanes:Record<string,unknown>[], boxes:Box[]):{boxes:Box[], lanes:Rect[], canvas:Rect, issues:QualityIssue[]}`；`diagramBounds(boxes:Rect[], routes:Point[][], labels:Rect[], padding=40):Rect`。
+
+- [ ] 写失败测试：`workflow expands columns and lanes for tall Chinese nodes`，断言长标签完整且同列/跨列节点不相交；`architecture includes legend and routes in canvas`；`explicit architecture coordinates remain stable`，断言 x/y 不变，重叠和分组越界有定位。
+- [ ] 运行任务测试确认失败。
+- [ ] 先完成节点文字尺寸，再按每列最大宽、每泳道最大高度计算布局；列与泳道间默认净空 32px，外边距 40px。同 lane/col 的自动节点按输入顺序分行，不能叠在一个位置；用户 yOffset 保留并做碰撞检查。
+- [ ] 架构图保留显式 x/y，以分组、图例、标签与连线的实际最大范围计算画布。分组内节点采用内容边界校验，分组标题保留 32px 带；负坐标不静默平移，报告越界。图例按可用宽度换行，禁止横排到画布外。
+- [ ] 运行两组测试，验证默认节点已有样例兼容及输入意图保留。
+
+## Task 3: 避障连线与边标签
+
+**Files:** diagram-layout.mjs、tech-diagram-render.mjs、diagram-quality.test.ts。
+
+**Interfaces:** `boundaryPort(box:Box, side:'top'|'right'|'bottom'|'left'):Point`；`routeConnector(from:Box,to:Box,obstacles:Rect[],occupied:Point[][],waypoints?:Point[]):{points:Point[],issues:QualityIssue[]}`；`placeEdgeLabel(points:Point[],layout:TextLayout,obstacles:Rect[]):{rect:Rect,issues:QualityIssue[]}`。
+
+- [ ] 写失败测试：`automatic routes avoid intervening nodes`、`diamond ports lie on polygon boundary`、`parallel and reverse edges use separate channels`、`edge label uses path-length midpoint and avoids boxes`、`explicit waypoints are preserved and flagged when blocked`。检查线段是否穿过非端点障碍，而非只匹配 SVG 字符串。
+- [ ] 运行任务测试确认失败。
+- [ ] 正交避障采用有限可见网格最短路：候选 x/y 来自端口和障碍扩展边界，障碍净空 12px；线段不得进入非端点矩形。代价为长度 + 每次转弯 24px + 与已占通道重合 80px，稳定按输入顺序和坐标排序处理。每轴最多 128 个候选坐标；超过预算或不可达时给出 route-unresolved，不无限搜索。
+- [ ] 决策菱形使用真实上下左右顶点端口；自调用绕节点外缘；平行和双向边预留独立通道，间隔 16px。显式 waypoints 原样保留并验证，超出/穿越给问题。
+- [ ] 边文字按路径长度找中点，依次尝试上下/左右 12、24、36px 偏移；记录最终文字边界，并检查节点、其他标签及箭头。无可用位置时标记 edge-label-collision，不删除标签。
+- [ ] 运行新旧测试；查看测试中生成的 SVG，确认方向没有为了避障被改变。
+
+## Task 4: 内置时序图质量
+
+**Files:** tech-diagram-render.mjs、diagram-layout.mjs、diagram-quality.test.ts。
+
+**Interfaces:** 复用 layoutText；sequence 输入 participants/messages 不变，manifest connector 加可选 `kind:'sequence'` 和 `self:boolean`，生命周期竖线不冒充消息连接。
+
+- [ ] 写失败测试：`sequence self call has nonzero loop`，断言至少四个路径点、起终点 y 不同且可见回环；`sequence long messages fit participant gaps and row heights`；`sequence preserves request return and async order`；`one participant keeps self-loop within canvas`。
+- [ ] 运行测试确认原零长度直线失败。
+- [ ] 根据参与者文字尺寸与消息宽度计算间距；消息按原数组顺序排布，最小行间距 56px，并容纳完整文字及 32px 高自调用回环。回环宽最小 40px，单参与者画布纳入回环及标签。返回消息保留虚线，已有 variant/flow 行为保持。
+- [ ] 为内置路线不支持的激活/片段语义明确路由说明，不悄悄忽略新增字段。复杂语义样例由任务 7 Mermaid 路线处理。
+- [ ] 运行新旧测试，确认全部消息仍存在、顺序一致、无退化路径。
+
+## Task 5: 自包含 SVG、真实测量与可靠导出
+
+**Files:** 新增 diagram-browser.mjs；修改 tech-diagram-render.mjs、export-diagram.mjs；测试 diagram-quality.test.ts。
+
+**Interfaces:** `findBrowser():string|null`；`withDiagramPage(html:string, options:{theme:'light'|'dark',timeoutMs:number}, action:(session:DiagramSession)=>Promise<T>):Promise<T>`；session 提供 `evaluate(expression:string):Promise<unknown>`、`screenshot(width:number,height:number):Promise<Buffer>`；`freezeSvg(theme):string` 与 `measureManifest():Manifest` 在生成页面的脚本内提供。CDP 通过 Node 内置 WebSocket，不新增浏览器库依赖。
+
+- [ ] 写失败测试：`standalone SVG preserves light and dark diagram styles`、`browser export waits for fonts and measures labels`、`scale two transforms every manifest rectangle and point`、`export paths with spaces and Chinese work`、`failed export does not accept stale output`。浏览器集成测试检测本地 Chromium，无浏览器才明确 skip；本机 Edge 存在，应真实执行。
+- [ ] 运行测试确认裸 SVG 缺样式及未测量导致失败。
+- [ ] 将原页面节点/边主题样式抽成单一定义，嵌入 SVG 内 style；page 外层 UI 样式不混入。根 SVG 设置确定的主题变量和字体，普通导出默认 light，新增 `--theme light|dark`；浏览器按钮按当前主题冻结全部必需样式，保留主题切换。
+- [ ] 通过 CDP 打开本地临时页面，等待 `document.fonts.ready` 及连续两次 RAF，再执行 getBBox 与 getComputedStyle；等宽度稳定后生成 actual labels，设置 measurement=browser。5 秒启动与 30 秒总超时，失败关闭子进程、清理本次临时目录，Windows 隐藏窗口。
+- [ ] 复用 CDP 的 Page.captureScreenshot 精确导出 SVG 区域，避免窗口最小尺寸及浏览器 UI 影响像素大小；保留 JPG 转换路线。SVG 导出无需浏览器时使用自包含样式与估算 manifest，并记录未测量。
+- [ ] export-diagram 新增可选 `--manifest <输入manifest>`、`--output-manifest <实际manifest>`、`--qa-report <JSON>`；未传时旧命令继续有效。所有坐标与 canvas 一并按 scale 缩放；报告列出边界问题，验证截图尺寸及非空后才替换输出。明显质量缺陷不称 passed。
+- [ ] 运行新旧测试，真实查看一张浅色与一张深色 PNG。明确图外标题/摘要不属于 SVG 导出范围，图内图例不得丢失。
+
+## Task 6: manifest 与 PNG QA 闭环
+
+**Files:** png-qa.mjs、tech-diagram-render.mjs、diagram-quality.test.ts、image-generation-skill.test.ts。
+
+**Interfaces:** 扩展 manifest 按 File Structure 定义；旧报告 `ok/image/issues/nextActions` 和退出码 0/2/1 保持。
+
+- [ ] 写失败测试：`QA checks measured node and edge labels`、`QA detects degenerate self calls`、`QA allows group containment but rejects node overlap`、`QA reads legacy manifests unchanged`、`QA compares scale-two geometry against actual image`。
+- [ ] 运行测试确认缺失文字/分组语义的检查失败。
+- [ ] 读入新增 labels/groups/issues；检测 node-text-overflow、edge-label-collision、connector-through-text、degenerate-connector 和既有问题。不要将画布包含、正常分组包含、端点接触以及同一节点内部多行文字视为碰撞；非法尺寸、未知 owner/端点要报告。
+- [ ] 检测文字完整性时对照源 label 与 lines，不做 OCR 承诺；遇到 measurement=estimated 时说明真实文字测量未完成。仅图像检查与浏览器测量检查分开列出。
+- [ ] 以三类复杂样例运行 QA；问题由布局/源修复，默认两轮仍未通过则报告 partial。测试包括持续碰撞不会伪报成功。
+- [ ] 新旧图片测试全部通过。
+
+## Task 7: Mermaid 入口与可选工具回退
+
+**Files:** 新增 mermaid-render.mjs；测试 diagram-quality.test.ts；样例 sequence.mmd、workflow.mmd。
+
+**Interfaces:** CLI `--input <.mmd> --output <.svg|.png> [--cli <执行文件或JS入口路径>] [--theme light|dark] [--format json|markdown]`。报告 `{ok,engine:'mermaid',version,input,output,format,verified,reason?}`。单次执行超时 30 秒，输出不存在或空文件均失败。
+
+- [ ] 写失败测试：`Mermaid missing CLI is explicit and keeps source`、`Mermaid uses argument arrays with spaced paths`、`Mermaid nonzero exit timeout and stale output fail`、`Mermaid unsupported syntax is not silently simplified`。使用临时 Node 假 CLI 验证参数和错误，但标为模拟，不作为视觉证据。
+- [ ] 运行任务测试确认 helper 缺失导致失败。
+- [ ] 优先显式 CLI 路径，再检测本地 PATH；`.js/.mjs` 由 process.execPath 执行。Windows npm shim 解析到对应真实 Node 入口，不把 `.cmd` 和用户文本送入 `cmd /c`；无法安全解析时要求 `--cli` 指定入口。调用 `--version` 记录 CLI 版本，参数数组传 input/output；临时输出成功后替换目标。
+- [ ] 默认 helper 不强行启用 ELK；工作流仅在已安装 Mermaid 实际支持时给 flowchart 配置，否则使用其兼容布局并说明。代码不依赖官方文档最新版号判断本机保证。
+- [ ] Mermaid 时序样例包含自调用、激活、返回、异步、alt 和 loop；流程样例含决策、中文长标签、汇合及失败回环。实际工具存在时渲染并查看 PNG；没有则记录真实执行未验证，提供源，使用内置样例验证图片路线。
+- [ ] 架构图复用现有 draw.io source/lint/layout/export 工具，不复制其实现；仅调整本技能路由及交付说明，工具缺失不自动安装。
+
+## Task 8: 视觉证据、独立包与文档同步
+
+**Files:** assets/quality-examples/ 内 sequence.json、workflow.json、architecture.json、sequence.mmd、workflow.mmd、README.md 及相应中文内容；本技能 SKILL/references；docs/example-prompts.md 及中文镜像；相关 README、project-structure、CHANGELOG；package.json；tests/install/diagram-quality.test.ts。
+
+**Interfaces:** 样例使用既有 JSON schema；报告记录图种、实际路线、工具版本、产物、QA 轮数、剩余问题、视觉观察及未验证能力。证据保存至 `reports/diagram-quality-2026-09-26/`，不要覆盖用户其他输出。
+
+- [ ] 在实施最开始用修改前脚本对同一组 JSON 生成 before HTML/SVG/PNG，保存源与失败观察；本任务结束对照 after。三类图各保留正常复杂样例；另有显式尺寸不足/错误 waypoints 样例用于证明诊断，不列为成功图。
+- [ ] 新增镜像一致、独立包 helper 可导入、缺失外部能力有清晰报告的测试。SKILL 链接每个新增 helper，样例索引链接本技能 assets，禁止跨 skill 链接造成独立分发失败。
+- [ ] 所有英文脚本同步复制到中文镜像并校验 hash；更新 typecheck:skill-scripts 覆盖新增模块。新增脚本测试运行后再更新说明，文档不得宣称工具缺失时完成外部路线视觉验证。
+- [ ] 更新中英文 SKILL、diagram-workflows、html-technical-diagrams、png-qa-autofix；示例区分成熟工具默认与 JSON 兼容路线，增加输出必须查看、字体/布局测量、manifest 缩放、两轮修复与 partial 规则。相关五语言 README/OpenClaw 说明按事实同步；2.9.0 的 Changed 加质量改进，不新增 Unreleased 或改版本。
+- [ ] 执行 `pnpm lint`、`pnpm typecheck`、`pnpm test`（包含构建），全部 exit 0；完整测试与打包检查串行执行，避免共享产物被清理。
+- [ ] 执行 `pnpm pack:skills`，再 `pnpm check:skills-publish`；针对打包后的本技能在临时目录运行 renderer/export/helper，确认无仓库 node_modules 依赖，原独立包引用规则仍成立。
+- [ ] 三类内置样例全部导出 1x/2x、至少一组 light/dark，运行 QA 后逐张使用图片查看工具审阅。检查中文、标签完整、箭头、回环、分组、留白及裁切；尺寸/边界自动通过仍不得跳过看图。外部 Mermaid/draw.io 仅在真实工具可用时记录通过。
+- [ ] 保存验收报告，说明前后改善与剩余限制；复核全部目标要求和未提交 diff。未经用户授权不提交、不发布、不重新打标签。
+
+## Self-Review and Handoff
+
+设计覆盖映射：工具路线/兼容性→任务 7、8；文字→任务 1、5；布局/连接→任务 2、3；时序语义→任务 4、7；导出/测量→任务 5；QA/修复→任务 6、8；镜像/独立包/文档→任务 8。五项 Review Focus 均有对应测试。
+
+执行顺序为 1→2→3→4→5→6→7→8；before 证据在第一个实现修改之前采集。建议在当前会话由主代理顺序实现，减少共享几何/manifest 接口的协调成本；独立最终审阅在得到所选执行方式授权后进行。计划待用户审核并选择执行方式，不能将设计通过等同于计划通过。
+
+
+## Execution disposition
+
+Tasks 1–8 completed in the current session; detailed evidence and rulings are recorded in reports/diagram-quality-2026-09-26/ledger.md, acceptance.md and completion-audit.json. The step checkboxes above preserve the approved plan rather than retroactively claiming every test was written under its exact suggested name. Equivalent behavioral regressions and actual image checks prove the outcomes. Internal helper-name differences and language packaging choices are explicitly ledgered. Optional Mermaid/draw.io/Graphviz visual runs are unverified because no local tool exists; this is the approved fallback case, not a claimed external pass. User no-commit/no-release instruction supersedes any skill commit steps.

package/docs/superpowers/specs/2026-09-26-diagram-quality-design.md

@@ -0,0 +1,77 @@
+# 技术图生成质量改进设计
+
+状态：用户已确认推荐路线并明确回复“设计通过”；实施计划待用户审核并选择执行方式。不得自动提交、发布或重建 v2.9.0 标签。
+
+## 目标与现状
+
+用户反馈 `fec-image-generation` 的时序图、流程图和架构图与人工绘制相比存在明显瑕疵。目标是提升文字完整性、图形语义、布局、连接清晰度及导出一致性，并用实际成图证明改进，不能仅以脚本成功或字符串测试通过验收。
+
+已核实的现状：节点标题使用固定字符数换行后仅保留两行；时序图自调用使用同起终点的直线；泳道与节点采用固定间距；连线没有全图障碍感知，标签位置不是路径长度意义上的中点；HTML 导出只提取 SVG，未携带页面样式。现有 17 项测试全部通过，但主要覆盖结构生成、输入验证及合成 PNG 的几何检查，没有证明复杂成图的可读性。
+
+保留仓库已有未提交修改，沿用 pnpm、现有脚本与发布机制。当前版本仍为 2.9.0，本次变更最终加入该版本中英文变更日志。不修改海报、照片等图像生成路线，也不追求所有复杂图必定零交叉或自动达到人工排版上限。
+
+## 路线与兼容性
+
+| 使用场景 | 默认可编辑源与工具 | 回退 |
+| --- | --- | --- |
+| 标准时序图 | Mermaid `.mmd`，使用已有本地 Mermaid CLI 渲染 | 改进后的 JSON/HTML 渲染器；超出支持范围的语义保留在 `.mmd` 中并报告未渲染 |
+| 标准流程图 | Mermaid `.mmd`，优先使用已安装版本支持的 ELK 布局 | 兼容布局或改进后的 JSON/HTML 泳道路线，说明实际使用方式 |
+| 架构图、长期人工维护 | 复用 draw.io 工作流及 `.drawio` 源、既有 lint、布局和导出脚本 | 工具缺失时提供 `.drawio` 源；需要本地图片时使用改进后的 JSON/HTML 路线，明确回退 |
+| 定制主题、浏览器单文件、现有 JSON 用户 | 现有 HTML/SVG 渲染器 | 不更换输入格式、不静默转成其他引擎 |
+
+工具选择由 skill 工作流决定，不将现有 JSON CLI 的默认行为静默改成外部工具。标准时序图的自调用、返回、异步、激活、分支和循环交给 Mermaid 原生语法；不将不支持的语义降成外观相似但含义错误的方框。
+
+增加本技能内 Mermaid CLI 调用 helper，输入 `.mmd`，输出 SVG/PNG，通过参数数组调用可用本地 CLI，不拼接用户文本到 shell 命令。允许显式指定 CLI 路径；否则检测本地命令。记录实际工具与版本，工具缺失时清晰退出，不自动下载、安装、访问 CDN 或替换源文件。Mermaid、draw.io、Graphviz 保持可选外部能力；不加入根包必须依赖，也不要求已安装 skill 依赖仓库的 node_modules。ELK 支持按实际工具版本判断，不能将网站最新版功能视为本机保证。
+
+保留现有 `tech-diagram-render.mjs` 和 `export-diagram.mjs` 的命令、图种、JSON schema_version、输出路径及报告字段；新增质量字段可选。已有显式坐标和 waypoints 不无声重排：自动布局适用于未指定尺寸及路线的项目；显式布局无法满足约束时报告具体问题，并允许工作流修改源。
+
+## 现有渲染器改进
+
+### 文字与视觉层级
+
+删除两行截断逻辑；保留完整文字、显式换行、中文和英文长单词。先计算文字布局，再确定节点尺寸与图形内有效文字区域。自动尺寸允许扩展，显式尺寸不容纳时产生质量问题，不能悄悄省略文字。主标题、副标题、actor、步骤编号使用独立空间；菱形、数据库和语义图标预留安全区域。
+
+默认技术图采用清晰、克制的字体、线宽、对齐与留白，保留已有主题。最终在浏览器中等待字体加载，测量真实文字边界；静态估算只用于初始排版，不作为准确测量的替代。密集内容优先拆成总览与细节图，禁止靠无限缩小字体通过验收。
+
+### 布局与连线
+
+流程图按实际节点尺寸计算列宽、泳道高度和间隔，避免长文本、高节点、分支共享位置造成重叠。架构图基于节点、分组标题及图例边界计算画布；显式分组越界或节点重叠要报告。
+
+自动连线使用正交路径和边界端口，避开非端点节点及标签区域；决策菱形端口落在真实轮廓，自调用与回环绕行，双向或平行边分配不同通道。显式 waypoints 仍保留，但做越界、穿越与退化检查。路径中点按路径长度计算；边标签单独记录边界并避开节点、其他标签及箭头。找不到合理路线时报告剩余问题，不能无限扩大画布或改写连接关系。
+
+内置时序图修复自调用为可见回环，按消息文字与回环尺寸计算参与者间距、消息行高、上下留白，保证消息顺序及端点关系。复杂激活/分支/循环优先路由到 Mermaid，不要求在内置路线重复实现完整 UML。
+
+## 导出与质量闭环
+
+生成的 SVG 必须携带自身所需的样式、确定的主题变量及字体声明，脱离 HTML 后仍可正常显示。复用单一样式定义，避免预览与导出各维护一套。CLI 导出默认使用明确的浅色技术图主题，允许选择深色；主题切换后的浏览器导出按当前主题冻结样式。PNG 与独立 SVG 同主题内容应一致，标题、图例或摘要若不属于导出画布须明确说明。
+
+复用 Chromium 检测与导出代码，等待字体和渲染完成后再截图，验证产物存在、尺寸正确且内容非空。缺少浏览器时保留可编辑源与独立 SVG，报告 PNG 未验证，不把源码交付说成图片验收通过。
+
+扩展布局 manifest，保留原 canvas/boxes/connectors 字段，增加文字、边标签、分组与实际渲染边界信息。按导出 scale 转换全部坐标，不能只缩放画布。PNG QA 兼容旧 manifest，将节点重叠、文字越界/缺失、边穿节点或文字、标签碰撞、退化自调用、画布裁切列为明确问题；正常分组包含关系不误判成节点重叠。
+
+默认最多两轮源级修复，用户要求时最多五轮。问题回到文本布局、尺寸、节点坐标、路由或导出参数修复；不得改 PNG 像素遮挡缺陷。仍有问题时交付源与问题清单，并标记部分验收，不能声称通过。自动检查之外必须查看最终 PNG，确认语义、中文显示、层级、连接和整体阅读顺序。
+
+## 验证与交付
+
+建立可复现的实际成图样例及回归：
+
+- 时序图：中英文长标签、请求/返回/异步、自调用；Mermaid 样例另含激活及分支循环。
+- 流程图：长决策文字、多分支汇合、失败返回、回环、跨泳道、显式尺寸及 waypoints。
+- 架构图：分层分组、网关/服务/存储、多条双向连接、长中文说明、图例及信任边界。
+- 导出：HTML 与独立 SVG/PNG 同主题一致，浅色/深色、1x/2x 坐标一致，无字体缺失或裁切；文件路径包含空格和中文。
+- 兼容与失败：原有 JSON 样例继续可用，显式布局问题可定位；外部 CLI/浏览器缺失、无效 Mermaid 输入、导出失败不伪报成功；镜像脚本与英文一致，独立技能包可运行。
+
+新增行为先用失败案例复现，再修复并运行针对性测试。视觉验收保留样例源、HTML/SVG、PNG、manifest 和 QA 结果，逐张查看三类图以及前后对比，不以单张简单图证明所有类型通过。
+
+完成 lint、typecheck、测试（包含构建），并执行相关技能独立打包检查。外部工具真实运行与模拟测试分开记录；缺失工具导致未验证的能力不得列为通过。
+
+同步中英文 SKILL、图种路由、HTML 技术图、导出与自动修复说明、示例提示词、相关 README、项目结构及 2.9.0 变更日志。版本号不变，不提交、不发布、不创建标签。
+
+## 依据
+
+- 现有技能、tech-diagram-render.mjs、export-diagram.mjs、png-qa.mjs 与 17 项图片生成测试。
+- 现有 draw.io studio 及其布局、lint、导出工具，保留外部能力可选的约定。
+- Mermaid 官方时序图语法：https://mermaid.js.org/syntax/sequenceDiagram
+- Mermaid 官方布局说明：https://mermaid.js.org/config/layouts
+
+自检：路线、兼容性、缺少依赖时的行为、质量标准与交付范围已明确。该文档是用户已确认的设计，不是已实现能力的发布说明。