tool.xpcool.com/docs/CHANGELOG.md

CHANGELOG — 项目变更日志

记录每次请求/变更，倒序排列（最新在上）。 与 docs/PROJECT_STATE.md 配合使用：本文件回答「改了什么」，状态文档回答「现在是什么样」。

---

2026-09-14 第八批：修「字太小」+ 换风格为「清晰蓝 · 卡片工作台」+ 补上 UI 库主题控制

用户反馈：① 界面字体、下拉与功能控件都太小；② 再换一种风格；③ UI 库（TDesign）的主题此前没有真正接上， 需要用主题变量控制组件的色彩与风格。 三者一并处理：换主色与密度（风格）→ 放大令牌与控件（太小）→ 用 --td-comp-* / --td-font-* 接管 TDesign 尺度（主题控制）。 构建通过（vue-tsc --noEmit + vite build，22.86s）。

⚠️ 本轮挖出的头号坑：theme-mode 选择器权重

TDesign 的浅/深色变量声明在 :root[theme-mode='light'|'dark']（权重 0,2,0）， 而上一版我们写的是 html[theme-mode='dark']（0,1,1）—— 生产构建里即便我们的 CSS 排在 vendor CSS 之后， 仍会被 UI 库的深色变量盖掉。表现：深色下卡片/输入框用回 TDesign 自带灰（卡片 #242424、描边 #ddd）。 修复：tokens.scss 与 tdesign-theme.scss 全部改用 :root[theme-mode=...]（与 TDesign 同级权重 + 后加载者胜）。 （验证提醒：切完主题别只看 getComputedStyle(body).backgroundColor，它可能命中计算值缓存，需用探针元素或刷新后再读。）

🎨 风格：青玉编辑感 → 宝石蓝 · 卡片工作台

• 主色：青玉 #0c7c59 → 宝石蓝 #2563eb（与白底 5.17:1 过 AA；深色下按钮底同色 + 白字，链接另用 #7aa8ff）。
• 中性色：青灰 → 蓝灰（浅 #f4f6fb / #ffffff / #0f1729，深 #0b0f18 / #131926 / #e9eef8）； 品牌/中性/语义三级色板与 index.html 的 theme-color 同步更新。
• 形状：圆角整体放大一档（xs5 / sm7 / md10 / lg12 / xl16 / 2xl22）； 卡片由「无框发丝线」改回「白底 + 细描边」，重新有边界感（仅列表条目分隔线仍用 --tk-hairline）。
• 密度：--tk-space-9 80→68、版心 1120→1200、顶栏 64→68、侧栏 248→268。

🔠 字号整体放大一档（tokens.scss）

• 旧 → 新：12→13 / 13→14 / 14→16 / 15→17 / 17→19 / 20→22 / 26→28 / 34→36 / 44→46 / 58→52。
• 正文基准 16px，全站最小字号 13px（--tk-text-xs）。
• 工具页里残留的 11px/12px 硬编码字号一次性提升为 var(--tk-text-xs)（27 个 .vue 文件）。

🧩 UI 库主题控制（tdesign-theme.scss 新增第 ③ 段，本轮核心）

TDesign 组件样式完全建立在 --td-* 变量之上（例如 .t-input.t-size-l { height: var(--td-comp-size-xl) }）， 所以「控件太小」的正解是改变量，而不是逐个组件写 CSS：

变量分组	TDesign 默认	本版	影响面
--td-comp-size-m（默认控件）	32px	40px	输入框 / 按钮 / 下拉 / 日期选择器
--td-comp-size-xl（large）	40px	48px	large 尺寸控件
--td-comp-size-xs / xxs / xxxs	24 / 20 / 16px	28 / 24 / 18px	小按钮、标签、复选框
--td-font-size-body-medium	14px	16px	控件文字（与正文同号）
--td-font-size-body-small	12px	13px	小标签、说明
--td-font-size-title-*	14/16/18px	16/18/20px	卡片标题、分组标题
--td-line-height-body-*	20/22/24px	22/24/26px	必须与字号成对改，否则大字号被行高挤住
--td-comp-paddingTB / LR-*	size 阶梯	放宽一档	控件内边距，避免大控件里文字贴边

• 只覆盖 --td-comp-*，不动 --td-size-* 原子刻度（图标/徽标/间距都在用它）。
• 深色中性色阶（反向，1 最深 → 14 最浅）补进 :root[theme-mode='dark']，避免组件在深色下退回 UI 库冷灰。
• 下拉：--td-comp-size-m 放大后 .t-select-option / .t-dropdown__item 行高自动跟随，仅补一条字号保险。

🧱 外壳、首页与公共组件（跟随新尺度）

• MainLayout：顶栏 68px、命令面板入口 44px、图标按钮 40px、内容区留白 32/48/72、移动端抽屉宽 300。
• SideNav：筛选框 42px、导航项 padding 9/12（行高约 43px）、图标 19px、活动指示条 3×18px。
• HomeView：hero 标题 52px、搜索底线 60px、工具索引行 padding 20px、服务端卡片图标 38px + 轻投影。
• 公共组件：CommandPalette（搜索行 64px、结果项 58px、kbd 22px）、UploadDrop（拖拽区加大、 缩略图 56px、删除按钮热区 36px）、AppBrand（标记 36px）、ThemeSwitch / LocaleSwitch（40px 高）、 HistoryPanel（条目最小高 48px、操作按钮热区撑大）。
• unocss.config.ts 的 panel（改实描边 + 更大内边距）、code-block（14px）、hint-text（13px）跟随放大。

---

2026-09-14 第七批：界面改版 →「更松弛的编辑感」

用户反馈对现有主题界面仍不满意，经方向选择后定为编辑感（Editorial）： 加大留白与字号反差，卡片几乎无边框，靠排版与呼吸感建立层次。 依据 design-taste-frontend 技能执行，旋钮 DESIGN_VARIANCE 6 / MOTION_INTENSITY 3 / VISUAL_DENSITY 3。 构建通过（vue-tsc --noEmit + vite build，32.17s）。

🎯 本轮解决的三个真实问题

1. 首页 hero 超标：eyebrow + 标题 + 描述 + 搜索框 + 文字链接共 5 个文字元素（超过 hero 上限 4）， 且 eyebrow 是模板化开场 → 删掉 eyebrow 与重复的 hero 链接（服务端专区入口已在下方，同意图不出现两次）。
2. 58 张卡片长得一模一样：全部 14px 圆角 + 1px 描边 + 绿底图标，重复得没有节奏 → 改为发丝线索引行（像书末索引），图标常态中性灰、hover 才上主色。
3. 层次全靠边框与底纹堆出来，排版本身承担的信息层级偏弱 → 标题 58px / 说明 17px 拉开反差，分区之间改用 80px 留白而非横线。

🧱 令牌层（tokens.scss）

• 新增 --tk-hairline（浅 #e7ecea / 深 #232b29）：内容容器与条目分隔线用它； 功能控件仍用 --tk-border，两类不要互换。
• 新增排版令牌：--tk-text-5xl(58px)、--tk-leading-display/title/body、 --tk-track-display/title、--tk-font-display。其中展示字体显式等于系统字体族 —— 中文环境下可用的展示字体就是系统字体本身，引入网络 CJK 展示字体要多付 2MB+ 首屏成本。
• --tk-space-9(80px) 专用于分区之间；--tk-header-h 60 → 64。
• 移除未使用的 --tk-track-caps（不在 CJK 场景下用宽字距）。

📐 全局排版与容器（index.scss / unocss.config.ts / tdesign-theme.scss）

• .page-title → clamp(26px, 3vw, 34px) + 字重 640；.page-desc → 15px / 1.75 / max-width: 62ch； .tool-section 间距 16 → 32px；新增 .section-heading 与 .rule。
• t-card / UnoCSS panel：圆角 → 2xl、描边 → 发丝线、内边距放大一档（p-5 md:p-7、 .t-card .t-card__body 24/32，窄屏在 @media (max-width: 767px) 收回）。
• 滚动条 10 → 8px；.reveal 位移 14 → 10px（编辑感入场要「不动声色」）。

🏠 首页重写（HomeView.vue）

• 抬头区：58px 左对齐标题 + 一句说明 + 底线式搜索框（聚焦时底线加粗为 2px， 用 box-shadow 叠加避免 border-width 变化引起 1px 位移；输入框自身不画焦点环）。
• 事实条去掉全部边框与底纹，数字直接摊在纸面上。
• 服务端专区保留青玉底纹（全站唯一），是分区层级的锚点。
• 分类目录 = 标题 + 数量注记 + 说明 + 发丝线索引网格（列间距 52px，避免两栏读串行）。

🧭 外壳（MainLayout / SideNav / AppBrand）

• 侧栏去掉底色块与右侧竖线，与正文落在同一张纸面上；hover 改用 --tk-surface （浅色下更亮、深色下也更亮，两种主题都是同一种「抬起」方向）。
• 侧栏筛选框改为底线式；内容区留白 28/28/56 → 40/48/88；页脚改左右分列 + 发丝线。
• 品牌图标去掉全站唯一渐变，改实色小方块（渐变会把视线从标题上拽走）， 品牌辨识度改由字重与字距承担。

♻️ 顺带修复

• HistoryPanel.vue 此前混用硬编码的 --td-* 与写死的 border-radius: 6px， 违反「样式一律用 --tk-*」的硬规则，且每条历史都套一个描边盒子；已改为 --tk-* 令牌 + 发丝线分行。
• 清理 4 份语言包中已失效的 home.eyebrow / home.ctaPrimary / home.ctaSecondary。

---

2026-09-14 第六批：视觉重设计 + 中英日韩四语言 + 昼夜主题 + 服务端接口对接

依据 design-taste-frontend 技能（BRIEF INFERENCE / 单一强调色 / 形状一致性 / 反 AI-slop 清单）重建全站视觉体系， 并一次性补齐多语言、主题切换与 5 个已上线服务端接口的对接。构建通过（vue-tsc --noEmit + vite build，33.88s）。

🎨 视觉体系重建（令牌 → TDesign 桥接，60+ 页面自动生效）

• 新增 src/assets/styles/tokens.scss：全站唯一视觉真相源。冷调石板灰中性色阶 + 青玉 Jade 单一强调色 （浅色 #0c7c59 对比 5.19:1 / 深色 #3fc79b 对比 8.85:1，均过 WCAG AA）；统一圆角规范 （xs4/sm6/md8/lg10/xl14/2xl20/pill999）、8px 间距节奏、字号阶梯、z-index 分层规范、动效曲线与时长； 按语言切换的字体栈（html[lang^='zh'|'ja'|'ko'|'en']，注意必须前缀匹配，lang 写的是完整标签）。
• 新增 src/assets/styles/tdesign-theme.scss：把 --tk-* 映射到 --td-*，重定义品牌色阶、语义色阶、 完整冷调灰阶（--td-gray-color-1..14，浅深共用）、圆角、阴影、滚动条。收益：60+ 未改动的工具页 零成本继承新配色与圆角，这是本次能低风险铺开全站的关键。
• 重写 index.scss：每页只过渡颜色（不碰 transform/布局）、统一 :focus-visible 焦点环、 .skip-to-content、滚动条 background-clip: content-box、标题字重 650 + letter-spacing:-0.02em、 prefers-reduced-motion 降级。
• 新增 src/directives/reveal.ts：v-reveal 滚动进入动效（全局单例 IntersectionObserver，传数字做错峰）。
• unocss.config.ts shortcuts 全部改为令牌驱动，panel 补上内边距（此前 ApiStatus/RandomString/Hash 等 新建页出现内容贴边）——注意页面 scoped 样式（.block[data-v-*]）权重高于该快捷类。

🧭 布局外壳重构

• MainLayout.vue 完全重写：毛玻璃 sticky 顶栏（backdrop-filter: blur(14px) saturate(180%)）+ 三区布局， 品牌区改用 TDesign AppIcon 而非手绘 SVG，全站唯一一处渐变（青玉 → #2fb98d）。
• 新增 CommandPalette.vue 命令面板（⌘K / Ctrl+K，按 UA 显示对应提示）：Teleport 到 body、 扁平结果列表 + 分类标签、↑↓/Enter/Esc 键盘导航、鼠标 hover 同步高亮、打开时锁 body 滚动。
• SideNav.vue 重写：内联筛选框、可折叠分组（tool-nav-collapsed 持久化）、活动态青玉底纹 + 左侧 2px 指示条、nav-dot 标记需联网工具。
• 新增 LocaleSwitch.vue（显示 ZH/EN/JA/KO 而非国旗，避免语言与国家绑定歧义）、 ThemeSwitch.vue（三态，图标显示实际生效的 mode、菜单勾选用户偏好 preference）。

🌏 多语言（中/英/日/韩）

• 引入 vue-i18n 11.4.10（legacy: false + globalInjection: true），基线语言 zh-CN。
• 新增 src/i18n/index.ts（SUPPORTED_LOCALES / normalizeLocale() / resolveInitialLocale() / applyLocaleToDocument() / setAppLocale()）、src/i18n/helpers.ts（toolName/toolDesc/categoryLabel/tOr 等带中文兜底的取词助手）、src/stores/locale.ts。
• 四份完整语言包 src/i18n/locales/{zh-CN,en-US,ja-JP,ko-KR}.ts：app / nav / palette / theme / locale / home / category / tool（58 个工具名与描述全译） / page / pending / common。
• 新增 src/components/common/BackendPending.vue：用中性信息态（非 t-alert 错误色）如实说明 「前端已就绪、后端接口尚未上线」，不伪装成可用。
• index.html 重写防闪烁内联脚本（同步执行，解析主题 auto + 语言归一化），与 theme store、i18n index 三处逻辑必须同步；theme-mode 属性 + 明暗两套 theme-color meta。

🔌 服务端接口对接（service.xpcool.com /api/service/open/tools/*）

• 新增 src/api/openTools.ts：接口元数据（OPEN_TOOL_ENDPOINTS，供「接口状态」页探测）与调用函数 共用同一份路径定义，避免改路径忘了改探测列表。5 个接口实测线上 全部 HTTP 200。
• src/api/client.ts 重写：BASE_URL 回落到 https://service.xpcool.com（不建 .env 也能用）； 新增 AbortController 超时（10s）、describeStatus() 状态码中文翻译（404 → 「接口尚未上线」）、 区分超时与网络不可达。
• 改造 6 个页面接入真实后端（均为「本机 / 服务端」双模式，默认本机、不自动打网络请求）：
  • ip-info：服务端识别的来源 IP + 内网判定，另附本机环境（时区/语言/平台/屏幕/UA）。 后端不返回归属地，界面如实说明，不做前端猜测。
  • uuid：本机 RFC 4122 v4 / 服务端 GoFrame guid，服务端模式并发 n 次（接口一次只返一个）。
  • random-string（新工具）：本机 Web Crypto（已注明取模偏置量级约 2^-26）/ 服务端 crypto/rand， 长度 1-128，服务端模式数量上限压到 10。
  • api-status（新工具）：串行探测 5 个接口（并发会干扰延迟读数）， performance.now() 计时、500ms 封顶刻度条、状态点承载真实语义、窄屏表格转卡片。
  • hash：新增「同时用服务端计算 MD5」开关（默认关闭——算哈希是高频纯本地动作， 不该每次点击都多一次网络往返），做两端口径对比，比对统一折小写。
  • timestamp：新增服务端时钟卡片，偏移量基于 Unix 秒（与时区无关）并补偿半个往返耗时， 误差上界 rtt/2；偏差 > 2s 提示本机时钟可能不准。
• 未实现接口的工具页（exchange-rate / express-query / phone-locate / network-test / speed-test） 统一改用 <BackendPending />，去掉「后端未就绪就禁用按钮」的旧逻辑。

🧹 修复

• 空分类渲染缺陷：health / study / travel 三个分类无任何工具，却仍渲染出空区块与空标题。 现分类精简为 6 个（work / dev / design / life / fun / online），groupedTools() 过滤空分组。
• SideNav.vue 在 <script setup> 末尾 import（ESM 提升但不规范）、IpInfoView.vue 漏 onBeforeUnmount 导入、HomeView.vue 从 @/api/openTools 错误导入 SUPPORTED_LOCALES —— 均已修正。

📄 备案号

• 新增 src/config.ts 集中管理站点级常量，页脚展示 黔ICP备2026003933号 并链接工信部核验入口 （备案号单列一行——它是监管信息，不与产品承诺混在同一组）。
• ⚠️ 该值必须与主站 xpcool.com 的 src/config.ts 的 SITE.icp 保持一致，换号时两处一起改。

📚 文档

• docs/api-contract.md 按线上实际部署重写：旧版是一份 /api/tools/* 的待实现清单，与实际不符。 现明确区分「已实现 5 个」（含请求/响应字段、错误语义、前端封装函数名）与「待实现 5 个」。
• .env.example 补充默认基址说明；docs/PROJECT_STATE.md 同步更新。

2026-08-24 第五批：删除 5 个工具（60 → 55）

🗑 删除工具（页面目录 + 注册条目 + 相关契约全部清除）

• code-minify 代码压缩美化（dev）
• lucky-wheel 抽奖转盘（fun）
• slogan-generator 文案生成器（fun）
• weather 天气预报（online）—— api-contract 第 1 节一并删除
• stock-quote 股票行情（online）—— api-contract 第 4 节一并删除

🧹 清理

• tools.ts 删除对应条目及无引用图标（StarIcon / SmileIcon / EditIcon / CloudyDayIcon；ChartIcon 因 word-count 仍使用而保留）
• api-contract.md 接口一览更新为 7 个：exchange-rate / express-query / phone-locate / ip-info / network-test / speedtest-download / speedtest-upload
• 删除方式备忘：项目内 rm 触发沙箱 trash 保护（genie-trash 失败），改用 mv 到系统临时目录（$TMPDIR/tool-deleted-*）实现移除

2026-08-24 第四批：网络测速工具（59 → 60）

🆕 新增工具

• speed-test 网络测速（online 分类，图标 RocketIcon）：
  • 下载测速：流式读取计时（后端测速源 / 公网源 / 自定义 URL 三模式），实时进度与峰值速度，5/10/25/50MB
  • 上传测速：生成随机数据上传，后端计时优先（POST /api/tools/speedtest/upload），1/5/10MB
  • 延迟测试：5/10 次 RTT 采样，平均/最小/最大/抖动 + 等级
• 契约新增第 8 节：下载测速返回随机二进制流（带 Content-Length）、上传测速返回 {bytes, duration_ms, speed_mbps}
• src/api/client.ts 导出 BASE_URL（测速工具直接拼流式地址）

2026-08-24 第三批：网络测试工具 + 上下文无缝切换机制

🆕 新增工具

• network-test 网络测试（online 分类）：HTTP 站点检测（前端直连，测 DNS/TTFB/状态/大小）+ Ping / TCP 端口 / DNS 解析（后端模式），后端契约见 api-contract.md 第 7 节

🏗 机制

• 新增 docs/PROJECT_STATE.md：项目状态与交接文档（单点真相），新账号 AI 接手必读
• 新增 docs/CHANGELOG.md：本文件，每次变更必记录
• AGENTS.md 顶部新增「接手必读」指引，指向上述两份文档与 api-contract.md —— 实现跨 CodeBuddy 账号无缝接续
• 约定：任何后续变更必须同步更新 CHANGELOG.md / PROJECT_STATE.md / 工作日志

2026-08-24 第二批：分类重构 + 后端预留机制 + 编程工具全系（40 → 58）

🏗 分类

• 分类重构为 9 个：新增 health 健康生活 / study 学习办公 / travel 旅行出行 / online 在线服务（后端预留）

🆕 后端预留（6）

• src/api/client.ts 统一 API 客户端（VITE_API_BASE 配置，未配置降级提示，统一响应 {code,message,data}）
• docs/api-contract.md 接口契约文档（weather / exchange-rate / express-query / stock-quote / phone-locate / ip-info）
• 6 个预留页面骨架（UI 完整、字段按契约类型化），.env.example 提供配置模板

🆕 编程工具（12）

• code-minify（JS/CSS/HTML 压缩美化）、regex-visual（正则结构树）、markdown-table、api-builder（fetch/curl）、gitignore-gen、code-to-image（canvas 高亮卡片）、color-namer（148 色表）、indent-convert、code-stats（30+ 语言注释规则）、hello-world（33 语言）、json-diff（路径级）、env-parse

🐛 修复

• Vue 模板 attribute 内 \" 导致编译错误 → 字符串常量移到 script
• json-diff k in b 类型收窄 → 断言为 Record

2026-08-24 第一批：趣味分类与工具（31 → 40）

🏗 分类

• 新增 dev 开发进阶 / design 创意设计 / fun 趣味娱乐

🆕 工具（9）

• dev：sql-format（手写分词 SQL 格式化）、text-diff（LCS 行级 diff）、json-to-code（JSON → TS/Go/Python）
• design：gradient-generator（linear/radial/conic + 12 预设）、placeholder-image（PNG/SVG 占位图）、ascii-art（图片转字符画）
• fun：morse-code（中文走 pinyin-pro + Web Audio 电报声）、lucky-wheel（canvas 转盘动画）、slogan-generator（5 类文案库）

📄 文档

• 新增 docs/tool-ideas.md 工具创意库（现状 + 未来创意 + 进度台账）

🐛 修复

• PaletteIcon 不存在 → 改用 ViewModuleIcon（图标引用前需在 node_modules 确认存在）