@qilitt-mickey/vue3-temp-skill 1.2.9 → 1.2.10

package/README.md

@@ -56,22 +56,44 @@
 | `references/adapters/vue-element-plus.md` | 实际组件 DOM 与样式落点检查 |
 | `scripts/modules.json`、`scripts/match.py` | 常规需求的按需规范路由 |
 
-## 安装与测试
+## 安装与更新
 
-要求 Node.js >= 22.12.0；能力路由需要 Python 3，无 Python 时按技能入口表加载规范。本轮改动尚未发布到 npm，先从本源码目录安装到选定编辑器：
+要求 Node.js >= 22.12.0；能力路由需要 Python 3，无 Python 时按技能入口表加载规范。命令形状与 `project-ui-design` 完全一致，只有包名不同；`-y` 让 npx 跳过确认提示。
+
+```bash
+npx -y @qilitt-mickey/vue3-temp-skill@latest install     # 安装：自动探测本机已装编辑器
+npx -y @qilitt-mickey/vue3-temp-skill@latest update      # 更新：把已安装目标刷到当前版本
+npx -y @qilitt-mickey/vue3-temp-skill@latest list        # 查看装到了哪些目录、哪个版本
+npx -y @qilitt-mickey/vue3-temp-skill@latest uninstall   # 卸载：只清理本包托管的文件
+```
+
+需要精确控制落点时：
+
+```bash
+npx -y @qilitt-mickey/vue3-temp-skill@latest install qoder                          # 只装 Qoder
+npx -y @qilitt-mickey/vue3-temp-skill@latest install all                            # 全装，含未探测到的编辑器
+npx -y @qilitt-mickey/vue3-temp-skill@latest install copilot --project /path/to/app # 项目级（copilot/gemini 必须带 --project）
+```
+
+省略 `target` 是自动探测，`install all` 是显式全装，两者不同；`update` / `uninstall` 不带 `target` 时按已安装记录整批处理。目标与选项以 `--help` 为准。
+
+安装器携带运行时资源；项目级说明使用独立托管区块，避免覆盖用户说明及另一套技能。旧版本冲突按提示处理，勿直接覆盖未知文件。
+
+设计还原需要两套技能同时在位：
+
+```bash
+npx -y @qilitt-mickey/project-ui-design@latest install
+npx -y @qilitt-mickey/vue3-temp-skill@latest install
+```
+
+在源码仓库内改动后想先自测，用同一套参数直接跑本地 CLI：`node bin/cli.js install qoder`。
 
 ```bash
-node bin/cli.js --help
-node bin/cli.js install qoder
-node bin/cli.js install copilot --project /path/to/project
-node bin/cli.js list
 npm test
 python scripts/match.py --batch
 ```
 
-安装器携带运行时资源；项目级说明使用独立托管区块，避免覆盖用户说明及另一套技能。安装目标和参数以 `--help` 为准。旧版本冲突按提示处理，勿直接覆盖未知文件。
-
-`npx @qilitt-mickey/vue3-temp-skill@latest` 仍指向已发布版本；新版发布前不会包含本轮修改。源码检查通过不代表所有编辑器已经实机验证。
+源码检查通过不代表所有编辑器已经实机验证。
 
 ## 与模板及设计侧的边界
 

package/SKILL.md

@@ -11,7 +11,7 @@ description: 在 vue3-web-temp 及其派生 Vue 3 项目开发功能、修复代
 
 - 使用用户指定的项目根或当前已打开的目标项目；读取项目协同说明、`package.json`、锁文件及 Git 状态，保留已有未提交改动。
 - 读取 `references/core-kernel.md`；以当前源码核对组件、依赖、路由、接口、主题和布局，不把模板清单当成当前项目事实。
-- 用户要求设计还原、UI 改版、按图落地，或同轮调用 `project-ui-design` 时，直接进入 `references/design-apply.md`；有原稿但无 JSON 时在同轮调用或读取设计技能，完成提取后继续实施。
+- 用户要求设计还原、UI 改版、按图落地，或同轮调用 `project-ui-design` 时，直接进入 `references/design-apply.md`；有原稿但无 JSON 时在同轮调用或读取设计技能，完成提取后继续实施。无原稿时同样交给设计技能做来源发现与候选选择，不在项目侧索取原稿或自行挑示例。
 - 只有业务功能需求时运行 `python <本技能>/scripts/match.py "<需求>" --json`，按 `load_files` 加载专项规范；无 Python 时按下表选取。
 - 同时有业务增量和视觉需求时，分别列出用户授权的业务变更与视觉变更；Demo 不提供新增业务需求。
 - 完成条件：项目根、目标范围、任务类型和实际可用规范已确定；不在技能仓库中写目标业务代码。

package/bin/cli.js

@@ -4,9 +4,12 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { createUi, DEFAULT_SINK } from "./ui.mjs";
 
 const PACKAGE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const SKILL_NAME = "vue3-temp-skill";
+// 大字 logo 文案与市面 skills CLI 完全一致（ANSI Shadow 的 SKILLS，43 列，80 列终端不会折行）；品牌名走副标题，避免长包名把字块撑破。
+export const LOGO_TEXT = "SKILLS";
 export const RUNTIME_DIRS = ["references", "scripts", "adapters", "mapping"];
 // 保留已有改动：generate-page.mjs 不再分发；作者侧 cli、测试及临时产物不属于运行资源。
 export const RUNTIME_SCRIPT_FILES = ["match.py", "modules.json", "check-landing.mjs", "generate-css.mjs", "verify-render.mjs"];
@@ -14,14 +17,20 @@ const RUNTIME_FILES = ["SKILL.md", "README.md"];
 const MANIFEST = ".skill-install.json";
 const BEGIN = `<!-- begin ${SKILL_NAME} -->`;
 const END = `<!-- end ${SKILL_NAME} -->`;
-const AUTO_DETECT = false;
+const AUTO_DETECT = true;
 
 // 可注入 HOME、包根和 cwd；import 本身不会安装、写记录或退出进程。
-export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, cwd = process.cwd(), log = console.log } = {}) {
+export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, cwd = process.cwd(), log: sink, ui } = {}) {
   home = path.resolve(home);
   skillDir = path.resolve(skillDir);
   cwd = path.resolve(cwd);
-  const version = JSON.parse(fs.readFileSync(path.join(skillDir, "package.json"), "utf8")).version;
+  // 注入 log 视为脚本消费：纯文本、无颜色、无横幅，保证测试与管道输出稳定。
+  const interactive = sink === undefined && Boolean(process.stdout?.isTTY) && Boolean(process.stdin?.isTTY);
+  const display = ui ?? createUi({ write: sink ?? DEFAULT_SINK, tty: interactive });
+  const log = (line) => display.write(line);
+  const pkg = JSON.parse(fs.readFileSync(path.join(skillDir, "package.json"), "utf8"));
+  const version = pkg.version;
+  const packageName = pkg.name || SKILL_NAME;
   const trackFile = path.join(home, `.${SKILL_NAME}.json`);
   // 编辑器专属落点只属于安装器，不进入运行技能的协议或编排。
   const targets = {
@@ -300,12 +309,49 @@ export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, c
     return opts;
   }
   function help() {
-    log(`${SKILL_NAME} v${version}\n用法: ${SKILL_NAME} <install|update|uninstall|list> [target|all] [--project <dir>] [--force]\n目标: ${Object.keys(targets).join(", ")}\nCopilot/Gemini 必须指定 --project；批量全局安装跳过项目专属目标。\nQoder 全局目录: ~/.qoder/skills\n--force 仅迁移可识别的自有旧资源，不能覆盖未管理文件。旧 Qoder / Cursor rules 不会被自动删除。`);
+    // 大字 logo 只在交互式终端出现；管道与脚本消费只读文本，避免把日志刷成噪声。
+    if (interactive) display.logo(LOGO_TEXT);
+    display.write(display.fit(`  ${display.bold(SKILL_NAME)} ${display.dim(`v${version}`)} ${display.dim("·")} ${display.dim(pkg.description || "AI 技能安装器")}`));
+    display.write("");
+    display.write(`  ${display.bold("用法")}`);
+    display.write(`    ${display.cyan(`npx ${packageName}@latest`)} ${display.dim("<install|update|uninstall|list>")} [target|all] [--project <dir>] [--force]`);
+    display.write("");
+    display.write(`  ${display.bold("命令")}`);
+    display.write(`    ${display.white("install")} [target|all]   ${display.dim("省略 target 时自动探测本机已装的编辑器")}`);
+    display.write(`    ${display.white("update")}  [target|all]   ${display.dim("把已安装目标更新到当前版本")}`);
+    display.write(`    ${display.white("list")}                  ${display.dim("查看已安装记录与所在目录")}`);
+    display.write(`    ${display.white("uninstall")} [target|all] ${display.dim("卸载，只清理本包托管的文件")}`);
+    display.write("");
+    display.write(`  ${display.bold("目标")}`);
+    display.write(`    ${display.white(Object.keys(targets).filter((key) => !targets[key].projectOnly).join(", "))}  ${display.dim("全局安装")}`);
+    display.write(`    ${display.white(Object.keys(targets).filter((key) => targets[key].projectOnly).join(", "))}       ${display.dim("仅项目安装，必须带 --project")}`);
+    display.write("");
+    display.write(`  ${display.bold("选项")}`);
+    display.write(`    ${display.white("--project")} <dir>  ${display.dim("安装到指定项目根目录")}`);
+    display.write(`    ${display.white("--force")}          ${display.dim("仅迁移可识别的自有旧资源，不覆盖未管理文件")}`);
+    display.write(`    ${display.white("-v, --version")}     ${display.dim("输出版本号")}`);
+    display.write(`    ${display.white("-h, --help")}        ${display.dim("输出本帮助")}`);
+    display.write("");
+    display.write(`  ${display.dim(`Qoder 全局目录: ${shortPath(path.join(home, targets.qoder.dir, SKILL_NAME))}`)}`);
+    display.write(`  ${display.dim("旧的 Qoder / Cursor rules 文件不会被自动删除，需要时手工清理。")}`);
+    display.write("");
+  }
+  function banner() {
+    if (!interactive) return;
+    display.logo(LOGO_TEXT);
+    display.write(display.fit(`  ${display.bold(SKILL_NAME)} ${display.dim(`v${version}`)} ${display.dim("·")} ${display.dim(pkg.description || "AI 技能安装器")}`));
+    display.write("");
+    display.usage([
+      [`npx ${packageName}@latest install`, "自动探测编辑器并安装"],
+      [`npx ${packageName}@latest update`, "更新到当前版本"],
+      [`npx ${packageName}@latest --help`, "查看全部目标与参数"],
+    ]);
+    display.write("");
   }
   function run(argv) {
     const opts = parseArgs(argv);
     if (opts.help || (!opts.positional.length && !opts.version)) { help(); return; }
-    if (opts.version) { log(version); return; }
+    if (opts.version) { log(version); return { done: 0, failed: 0 }; }
     let [command, target] = opts.positional;
     if (targets[command] || command === "all" || (AUTO_DETECT && command === "系统")) {
       if (target) throw new Error("多余的位置参数");
@@ -317,8 +363,15 @@ export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, c
     if (target && target !== "all" && !targets[target]) throw new Error(`未知目标: ${target}`);
     if (command === "list") {
       if (target || opts.project || opts.force) throw new Error("list 不接受目标或安装参数");
-      for (const entry of readTrack()) log(`${entry.target} v${entry.version} ${entry.project || home}`);
-      return;
+      const entries = readTrack();
+      if (!entries.length) { log(`未找到 ${SKILL_NAME} 的已安装记录。执行 npx ${packageName}@latest install 安装。`); return { done: 0, failed: 0 }; }
+      display.note(`${SKILL_NAME} v${version} · 已安装 ${entries.length} 个目标`, entries.map((entry) => {
+        const behind = entry.version && entry.version !== version;
+        return `${entry.target.padEnd(11)}${display.dim(entry.path || entry.project || home)}${behind ? `  ${display.yellow(`v${entry.version} → v${version}`)}` : ""}`;
+      }));
+      display.write(display.dim(`  更新全部目标: npx ${packageName}@latest update`));
+      display.write("");
+      return { done: entries.length, failed: 0 };
     }
     let track = readTrack();
     let jobs;
@@ -327,9 +380,14 @@ export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, c
       const keys = target && target !== "all" ? [target] : Object.keys(targets).filter((key) => {
         const cfg = targets[key];
         if (cfg.projectOnly) return Boolean(opts.project);
-        return !AUTO_DETECT || Boolean(stat(path.join(opts.project || home, cfg.dir)));
+        // all 是显式全装；只有省略 target 时才按本机已装编辑器自动探测。
+        if (target === "all" || !AUTO_DETECT) return true;
+        return Boolean(stat(path.join(opts.project || home, cfg.dir)));
       });
       jobs = keys.map((key) => ({ target: key, project: opts.project || null }));
+      if (!jobs.length) {
+        throw new Error(`未检测到已安装的编辑器。可指定目标：npx ${packageName}@latest install <${Object.keys(targets).filter((key) => !targets[key].projectOnly).join("|")}>，或全装：install all。`);
+      }
     } else {
       jobs = track.filter((entry) => !target || target === "all" || entry.target === target);
       if (opts.project !== undefined) jobs = jobs.map((entry) => ({ ...entry, project: opts.project }));
@@ -343,24 +401,84 @@ export function createInstaller({ home = os.homedir(), skillDir = PACKAGE_DIR, c
         }
         jobs = batch;
       }
+      if (!jobs.length) {
+        if (command === "update") throw new Error(`未找到 ${SKILL_NAME} 的已安装记录，无法更新。请先执行 npx ${packageName}@latest install。`);
+        log(`未找到 ${SKILL_NAME} 的已安装记录，无需处理。`);
+        return { done: 0, failed: 0 };
+      }
     }
     const identity = (entry) => JSON.stringify([entry.target, entry.project]);
     jobs = [...new Map(jobs.map((entry) => [identity(entry), entry])).values()];
+    // 显式指定 target 时保持严格；批量时任一目标失败不中止整批。
+    const batch = !target || target === "all";
     // 参数与所有项目根在写入前校验；显式 --project 始终覆盖旧记录的 project。
-    for (const job of jobs) paths(job.target, job.project);
-    if (!jobs.length) { log("未找到需要处理的目标。"); return; }
+    const live = [];
+    const stale = [];
     for (const job of jobs) {
-      const dest = command === "uninstall" ? uninstall(job.target, job.project, opts.force) : install(job.target, job.project, opts.force);
+      try { paths(job.target, job.project); live.push(job); }
+      catch (err) {
+        // 项目根已被删除的旧记录会永久卡住 update/uninstall，这里单独摘出来并清理。
+        if (!batch || !job.project || stat(job.project)?.isDirectory()) throw err;
+        stale.push(job);
+      }
+    }
+    jobs = live;
+    banner();
+    for (const job of stale) {
       track = track.filter((entry) => identity(entry) !== identity(job));
-      if (command !== "uninstall") track.push({ target: job.target, project: job.project, version, path: dest });
-      writeTrack(track);
-      log(`${command} ${job.target} → ${dest}`);
+      display.warn(`${job.target} 的项目目录已不存在，跳过并清理该记录：${display.dim(job.project)}`);
+    }
+    if (stale.length) writeTrack(track);
+    if (!jobs.length) {
+      if (!stale.length) log("未找到需要处理的目标。");
+      return { done: 0, failed: 0 };
     }
+    const recorded = new Map(track.map((entry) => [identity(entry), entry.version]));
+    const verb = { install: "安装", update: "更新", uninstall: "卸载" }[command];
+    let done = 0;
+    let failed = 0;
+    for (const job of jobs) {
+      const key = identity(job);
+      const from = recorded.get(key);
+      try {
+        const dest = command === "uninstall" ? uninstall(job.target, job.project, opts.force) : install(job.target, job.project, opts.force);
+        track = track.filter((entry) => identity(entry) !== key);
+        if (command !== "uninstall") track.push({ target: job.target, project: job.project, version, path: dest });
+        writeTrack(track);
+        done++;
+        const note = command === "uninstall" ? display.dim("已移除")
+          : from && from !== version ? display.green(`v${from} → v${version}`)
+          : from === version ? display.dim(`v${version} 内容已刷新`) : display.dim(`v${version}`);
+        display.ok(`${job.target}  ${note}`);
+        display.arrow(display.dim(shortPath(dest)));
+      } catch (err) {
+        if (!batch) throw err;
+        failed++;
+        display.fail(`${job.target}  ${display.dim(String(err.message).split("\n")[0])}`);
+      }
+    }
+    display.note(`${verb}完成 ${done} 个目标 · ${SKILL_NAME} v${version}${failed ? ` · ${display.red(`${failed} 个失败`)}` : ""}`,
+      [command === "uninstall" ? `重装：npx ${packageName}@latest install` : `在编辑器里输入 /${SKILL_NAME} 使用；未生效时重启编辑器或新开会话。`]);
+    return { done, failed };
+  }
+  /** 安装行只显示相对形式，完整路径由 list 给出，避免长绝对路径淹没结果。 */
+  function shortPath(file) {
+    const absolute = path.resolve(file);
+    if (absolute === home || absolute.startsWith(home + path.sep)) return `~/${path.relative(home, absolute).split(path.sep).join("/")}`;
+    const relative = path.relative(cwd, absolute);
+    return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? `./${relative.split(path.sep).join("/")}` : absolute.split(path.sep).join("/");
   }
   return { run, paths, runtimeFiles };
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { createInstaller().run(process.argv.slice(2)); }
-  catch (err) { console.error(err.message); process.exitCode = 1; }
+  try {
+    const result = createInstaller().run(process.argv.slice(2));
+    if (result?.failed) process.exitCode = 1;
+  }
+  catch (err) {
+    const mark = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb" ? "\x1b[31m✗\x1b[0m" : "!";
+    console.error(`${mark} ${err.message}`);
+    process.exitCode = 1;
+  }
 }

package/bin/ui.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+/**
+ * 安装器终端展示层（零依赖；两个技能包共用同一份实现）。
+ *
+ * 视觉规格对齐 npm 包 skills（skills.sh）：ANSI Shadow 大字 logo + 6 级灰度渐变 + dim 副标题，
+ * 结果行使用 ✓ / → / ! / ✗ 前缀，收尾使用汇总块。
+ * 非 TTY、NO_COLOR、TERM=dumb、CI，或调用方注入自定义 log 时自动降级为纯文本，
+ * 保证脚本消费与测试断言稳定。
+ */
+
+const GLYPHS = {
+  "0": [" ██████╗ ","██╔═████╗","██║██╔██║","████╔╝██║","╚██████╔╝"," ╚═════╝ "],
+  "1": [" ██╗","███║","╚██║"," ██║"," ██║"," ╚═╝"],
+  "2": ["██████╗ ","╚════██╗"," █████╔╝","██╔═══╝ ","███████╗","╚══════╝"],
+  "3": ["██████╗ ","╚════██╗"," █████╔╝"," ╚═══██╗","██████╔╝","╚═════╝ "],
+  "4": ["██╗  ██╗","██║  ██║","███████║","╚════██║","     ██║","     ╚═╝"],
+  "5": ["███████╗","██╔════╝","███████╗","╚════██║","███████║","╚══════╝"],
+  "6": [" ██████╗ ","██╔════╝ ","███████╗ ","██╔═══██╗","╚██████╔╝"," ╚═════╝ "],
+  "7": ["███████╗","╚════██║","    ██╔╝","   ██╔╝ ","   ██║  ","   ╚═╝  "],
+  "8": [" █████╗ ","██╔══██╗","╚█████╔╝","██╔══██╗","╚█████╔╝"," ╚════╝ "],
+  "9": [" █████╗ ","██╔══██╗","╚██████║"," ╚═══██║"," █████╔╝"," ╚════╝ "],
+  "A": [" █████╗ ","██╔══██╗","███████║","██╔══██║","██║  ██║","╚═╝  ╚═╝"],
+  "B": ["██████╗ ","██╔══██╗","██████╔╝","██╔══██╗","██████╔╝","╚═════╝ "],
+  "C": [" ██████╗","██╔════╝","██║     ","██║     ","╚██████╗"," ╚═════╝"],
+  "D": ["██████╗ ","██╔══██╗","██║  ██║","██║  ██║","██████╔╝","╚═════╝ "],
+  "E": ["███████╗","██╔════╝","█████╗  ","██╔══╝  ","███████╗","╚══════╝"],
+  "F": ["███████╗","██╔════╝","█████╗  ","██╔══╝  ","██║     ","╚═╝     "],
+  "G": [" ██████╗ ","██╔════╝ ","██║  ███╗","██║   ██║","╚██████╔╝"," ╚═════╝ "],
+  "H": ["██╗  ██╗","██║  ██║","███████║","██╔══██║","██║  ██║","╚═╝  ╚═╝"],
+  "I": ["██╗","██║","██║","██║","██║","╚═╝"],
+  "J": ["     ██╗","     ██║","     ██║","██   ██║","╚█████╔╝"," ╚════╝ "],
+  "K": ["██╗  ██╗","██║ ██╔╝","█████╔╝ ","██╔═██╗ ","██║  ██╗","╚═╝  ╚═╝"],
+  "L": ["██╗     ","██║     ","██║     ","██║     ","███████╗","╚══════╝"],
+  "M": ["███╗   ███╗","████╗ ████║","██╔████╔██║","██║╚██╔╝██║","██║ ╚═╝ ██║","╚═╝     ╚═╝"],
+  "N": ["███╗   ██╗","████╗  ██║","██╔██╗ ██║","██║╚██╗██║","██║ ╚████║","╚═╝  ╚═══╝"],
+  "O": [" ██████╗ ","██╔═══██╗","██║   ██║","██║   ██║","╚██████╔╝"," ╚═════╝ "],
+  "P": ["██████╗ ","██╔══██╗","██████╔╝","██╔═══╝ ","██║     ","╚═╝     "],
+  "Q": [" ██████╗ ","██╔═══██╗","██║   ██║","██║▄▄ ██║","╚██████╔╝"," ╚══▀▀═╝ "],
+  "R": ["██████╗ ","██╔══██╗","██████╔╝","██╔══██╗","██║  ██║","╚═╝  ╚═╝"],
+  "S": ["███████╗","██╔════╝","███████╗","╚════██║","███████║","╚══════╝"],
+  "T": ["████████╗","╚══██╔══╝","   ██║   ","   ██║   ","   ██║   ","   ╚═╝   "],
+  "U": ["██╗   ██╗","██║   ██║","██║   ██║","██║   ██║","╚██████╔╝"," ╚═════╝ "],
+  "V": ["██╗   ██╗","██║   ██║","██║   ██║","╚██╗ ██╔╝"," ╚████╔╝ ","  ╚═══╝  "],
+  "W": ["██╗    ██╗","██║    ██║","██║ █╗ ██║","██║███╗██║","╚███╔███╔╝"," ╚══╝╚══╝ "],
+  "X": ["██╗  ██╗","╚██╗██╔╝"," ╚███╔╝ "," ██╔██╗ ","██╔╝ ██╗","╚═╝  ╚═╝"],
+  "Y": ["██╗   ██╗","╚██╗ ██╔╝"," ╚████╔╝ ","  ╚██╔╝  ","   ██║   ","   ╚═╝   "],
+  "Z": ["███████╗","╚══███╔╝","  ███╔╝ "," ███╔╝  ","███████╗","╚══════╝"],
+  "-": ["      ","      ","█████╗","╚════╝","      ","      "],
+};
+
+const LOGO_ROWS = 6;
+// 与 skills CLI 相同的由亮到暗渐变，让大字有层次而不是纯色块。
+const LOGO_GRAYS = ["38;5;250", "38;5;248", "38;5;245", "38;5;243", "38;5;240", "38;5;238"];
+
+export function logoWidth(text) {
+  return [...String(text).toUpperCase()].reduce((sum, char) => sum + (GLYPHS[char]?.[0].length ?? 0), 0);
+}
+
+/** 逐字拼接 ANSI Shadow 字形；与 figlet 整词渲染逐字节一致。 */
+export function renderLogo(text) {
+  const cells = [...String(text).toUpperCase()].map((char) => GLYPHS[char] ?? GLYPHS["-"]);
+  return Array.from({ length: LOGO_ROWS }, (_, row) => cells.map((glyph) => glyph[row]).join("").replace(/\s+$/, ""));
+}
+
+export const DEFAULT_SINK = (line) => process.stdout.write(`${line}\n`);
+
+/** 东亚宽字符按 2 列计算，避免中英混排时用法行错位。 */
+export function displayWidth(text) {
+  let width = 0;
+  for (const char of String(text)) {
+    const code = char.codePointAt(0);
+    const wide = (code >= 0x1100 && code <= 0x115f) || (code >= 0x2e80 && code <= 0x303e) || (code >= 0x3041 && code <= 0x33ff) ||
+      (code >= 0x4e00 && code <= 0x9fff) || (code >= 0xa000 && code <= 0xa4cf) || (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe30 && code <= 0xfe6f) || (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) || (code >= 0x20000 && code <= 0x2fffd);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+export function createUi({ write = DEFAULT_SINK, tty = Boolean(process.stdout?.isTTY), env = process.env, columns = process.stdout?.columns || 80 } = {}) {
+  const color = Boolean(tty) && !env.NO_COLOR && env.TERM !== "dumb";
+  const strip = (line) => String(line).replace(/\x1b\[[0-9;]*m/g, "");
+  const paint = (code) => (text) => (color ? `\x1b[${code}m${text}\x1b[0m` : String(text));
+  const bold = paint(1);
+  const dim = paint(2);
+  const red = paint(31);
+  const green = paint(32);
+  const yellow = paint(33);
+  const cyan = paint(36);
+  const white = paint(39);
+  return {
+    color,
+    write,
+    columns,
+    bold,
+    dim,
+    red,
+    green,
+    yellow,
+    cyan,
+    white,
+    /** 大字 logo；终端宽度不足时退化为普通标题行，避免块状字被硬换行打散。 */
+    logo(text) {
+      write("");
+      if (logoWidth(text) > Math.max(40, columns - 2)) write(bold(white(text.toUpperCase())));
+      else renderLogo(text).forEach((line, row) => write(color ? `\x1b[${LOGO_GRAYS[row]}m${line}\x1b[0m` : line));
+      write("");
+    },
+    /** 用法行：命令取 cyan，说明取 dim，按显示宽度对齐；放不下说明时只保留命令。 */
+    usage(entries) {
+      const width = Math.max(...entries.map(([command]) => displayWidth(command)));
+      for (const [command, hint] of entries) {
+        const pad = " ".repeat(width - displayWidth(command));
+        const room = hint && columns - (width + pad.length + 8) >= displayWidth(hint);
+        write(`  ${dim("$")} ${cyan(command)}${pad}${room ? `  ${dim(hint)}` : ""}`);
+      }
+    },
+    step(message) { write(`${dim("·")} ${message}`); },
+    ok(message) { write(`${green("✓")} ${message}`); },
+    warn(message) { write(`${yellow("!")} ${message}`); },
+    fail(message) { write(`${red("✗")} ${message}`); },
+    /** 按终端显示宽度截断，保留颜色转义序列；市面 CLI 的横幅副标题同样是一行不折行的短句。 */
+    fit(line, width = columns - 1) {
+      if (displayWidth(strip(line)) <= width) return line;
+      const limit = width - 1;
+      let out = "";
+      let used = 0;
+      let cut = false;
+      for (const part of String(line).split(/(\x1b\[[0-9;]*m)/)) {
+        if (part.startsWith("\x1b[")) { out += part; continue; }
+        if (cut) continue;
+        for (const char of part) {
+          const size = displayWidth(char);
+          if (used + size > limit) { cut = true; break; }
+          out += char;
+          used += size;
+        }
+      }
+      return `${out.replace(/\x1b\[0m$/, "").replace(/\s+$/, "")}…${color ? "\x1b[0m" : ""}`;
+    },
+    arrow(message) { write(`  ${dim("→")} ${this.fit(message, columns - 4)}`); },
+    /** 汇总块：一个加粗标题 + 缩进明细，等价于 skills CLI 的 note()。 */
+    note(title, lines = []) {
+      write("");
+      write(this.fit(bold(title)));
+      for (const line of lines) write(this.fit(`  ${line}`, columns - 1));
+      write("");
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "type": "module",
   "description": "vue3-web-temp 项目工程技能：按需功能开发、保留业务的设计还原与视觉及功能双重验证",
   "bin": {

package/references/design-apply.md

@@ -3,6 +3,7 @@
 ## 1. 接入设计与确定范围
 
 - 接受原始截图、HTML、设计工程、运行地址、`ui.design-handoff/1.0` 或已有 `ui.visual-contract/1.0`；原稿已有而交接缺失时，在本轮加载 `project-ui-design` 补齐交接并继续，不要求用户切会话。
+- 项目内没有任何设计来源时，不在项目侧替用户决定用哪份示例：转由 `project-ui-design` 按其 `references/scope-gate.md` 走完来源发现，就「系统场景 / 页面类型 / 主题」一次提问，选定后自动定位内置 `mockup` 与 `preview` 并回到本节继续实施。项目侧不重复实现来源选择逻辑，也不因缺少附件而停在索取原稿。
 - 读取当前任务的交接和原稿；多个任务并存时按用户指定或上下文选择，无法确定时询问，不默认选目录中的第一份 JSON。
 - 从路由与页面确定目标。用户指定页面时使用该页面；用户要求全系统时覆盖共用外壳及受影响页面类型，列出代表性页面和独有视图，不缩成一页。
 - 原稿有外壳而内容页未确定时，可先做已明确的共用外壳；页面锚点存在歧义时一次询问。没有业务页面时不照 Demo 新建业务；只有用户另行授权业务开发才创建路由和业务页。