参考及开发文档Reference & Development Docs

面向二次开发者与集成方。完整架构决策（ADR）与过程材料见仓库内说明。For integrators and contributors. Full ADRs and process records live in the repository.

1 · 仓库结构1 · Repository Layout

mono-repo，四包各自独立构建、测试与发布：A monorepo; the four packages build, test and release independently:

包Package	职责Responsibility	许可证License
`HIA/core`	公共核心：主题模型、配色算法（Oklch）、关系规则推导、Token 导出适配器、宝典数据。三端以本地包链接复用。Shared core: theme model, Oklch color math, harmony rule engine, token export adapters, baodian data. Reused by all ends via local package links.	MIT
`HIA/web`	网页版（Vite），共享渲染器为三端 UI 单一事实来源，部署 GitHub Pages。Web app (Vite); its shared renderer is the single source of truth for all UI, deployed to GitHub Pages.	MIT
`HIA/electron`	Electron 桌面版：复用 web 渲染产物，隐藏 BrowserWindow 真实渲染取色。Electron desktop: reuses the web renderer; hidden BrowserWindow performs real-render extraction.	Apache-2.0
`HIA/tauri`	Tauri 桌面版：Rust 后端 chromiumoxide 采集，CDP 逐请求 SSRF 拦截。Tauri desktop: Rust backend collects via chromiumoxide with per-request CDP SSRF interception.	MIT

2 · 主题模型契约（摘要）2 · Theme Model Contract (summary)

完整契约见 HIA/core/src/types.ts 与 ADR-007（配色关系模式与辅助色）：The full contract is in HIA/core/src/types.ts and ADR-007 (harmony modes & auxiliary colors):

字段Field	类型Type	语义Semantics
`primary / secondary / thirdColor`	`RoleColor`	主体色成员；RoleColor = { name, value, scale(50..900), on }，色阶由 HEX 重建。Body-color members; RoleColor = { name, value, scale(50..900), on } with scales rebuilt from HEX.
`seriesMode`	`'single'\|'dual'\|'triad'`	主体色模式，由成员数派生（装配语义：缺省补默认）。Body mode, derived from member count (assembly semantics: missing → default).
`seriesRelation`	`SeriesRelationId`	十种关系规则之一（manual/complement/clash/neutral/analogous/split-complement/tertiary/primary-combo/secondary-combo/pure）。One of ten rules (manual/complement/clash/neutral/analogous/split-complement/tertiary/primary-combo/secondary-combo/pure).
`auxiliary`	`RoleColor[]`	辅助色独立维度，0..12 槽位，与主体色模式无关。Independent auxiliary dimension, 0..12 slots, unrelated to the body mode.
`gradients`	`GradientSettings`	8 渐变角色；family 支持 `ColorFamily \| 'third' \| 'auxN'`（N 为槽位索引）。Eight gradient roles; family accepts `ColorFamily \| 'third' \| 'auxN'` (N = slot index).

向后兼容原则：旧数据缺字段一律按 dual/manual/空辅助槽补默认；ThemeInput 与 Preset 均可选携带新字段，清洗层（sanitizePreset）做白名单校验并由 HEX 重建色阶。Backward compatibility: missing fields default to dual/manual/empty aux. ThemeInput and Preset carry the new fields optionally; the sanitize layer (sanitizePreset) whitelists values and rebuilds scales from HEX.

3 · core API 速览3 · core API Quick Tour

import {
  buildTheme, createThemeDraft, presetFromDraft, draftFromPreset,
  deriveSecondaryByRelation, deriveThirdByRelation, generateAuxiliaryCandidates,
  exportThemeCss, exportThemeJson, getExportTarget,
  encodeShareHash, decodeShareHash, buildSharePayload,
  parseThemePack, mergeImportedPresets, serializeThemeLibrary,
  FORM_PACKS, BAODIAN_PALETTE, SERIES_RELATION_DEFS,
} from '@hia/theme-core';

buildTheme(input)：装配主题（推导第三色/副色变体/空辅助槽），全部色阶在此计算；buildTheme(input): assembles the theme (derives third/secondary variant/empty aux); all scales are computed here;
deriveSecondaryByRelation / deriveThirdByRelation：按规则从主色推导副色与第三色；deriveSecondaryByRelation / deriveThirdByRelation: rule-based secondary/third derivation from the primary;
encodeShareHash / decodeShareHash：分享链接编码（紧凑位置数组，缺省字段省略）；encodeShareHash / decodeShareHash: share-link codec (compact positional array, defaults omitted);
parseThemePack：远程/导入主题包清洗（含 v2 契约字段白名单与截断）。parseThemePack: remote/import pack sanitizing (v2 field whitelisting and truncation).

4 · Token 结构（CSS 变量）4 · Token Structure (CSS variables)

导出的 CSS 变量遵循分层命名：Exported variables follow layered naming:

--hia-primary-50 … --hia-primary-900   /* primary, 10 shades */
--hia-secondary-*, --hia-third-*        /* secondary / third families */
--hia-aux0-50 … --hia-auxN-900          /* auxiliary slots (N = index) */
--hia-on-primary / --hia-on-aux0        /* foregrounds (WCAG auto-picked) */
--hia-fs-h1 / --hia-line-height-body    /* typography & line-height tokens (ADR-006) */

运行时（预览区）另有 --p/--s/--t/--a{N} 前缀的快捷变量供 mock 与渐变消费。At runtime the preview area also exposes --p/--s/--t/--a{N} shorthand variables for mocks and gradients.

5 · 导出适配器5 · Export Adapters

WordPress：theme.json（v2+）色板含全部色族 + 子主题骨架 ZIP；WordPress: theme.json (v2+) palette with all families plus a child-theme ZIP skeleton;
Tailwind：tailwind.config 片段，colors 按 primary/secondary/third/aux{N} 族映射；Tailwind: a tailwind.config snippet mapping colors into primary/secondary/third/aux{N} families;
CSS/JSON：通用令牌导出（默认/经典/TDON 三种支持模式，TDON 为声明式适配草稿规范）。CSS/JSON: generic token export (default / classic / TDON support modes; TDON is a declarative adaptation draft spec).

6 · 桌面端架构与取色6 · Desktop Architecture & Extraction

两端共享同一 scanner bundle（HIA/extractor/dist/browser-scanner.bundle.js，IIFE 自包含），保证评分一致；构建校验脚本断言三端内容哈希一致。Both desktop ends share one scanner bundle (HIA/extractor/dist/browser-scanner.bundle.js, self-contained IIFE) so scores match; a build script asserts bundle hash equality across ends.

Electron：隐藏隔离 BrowserWindow 加载目标页 → 稳定化（网络/渲染双重静默）→ 注入 scanner 采集 DOM 证据 → 量化评分；finally 销毁窗口；Electron: a hidden isolated BrowserWindow loads the page → stabilization (network/render) → scanner injection collects DOM evidence → quantified scoring; the window is destroyed in finally;
Tauri：Rust 后端 chromiumoxide launch（显式无头）→ CDP Fetch 域逐请求 SSRF 裁决（重定向每跳 DNS 深度校验，命中即阻断）→ 采集后 Browser.close 带超时护栏，函数返回经 Drop/kill_on_drop 强杀子进程，杜绝残留窗口；Tauri: Rust chromiumoxide launch (explicit headless) → CDP Fetch-domain per-request SSRF adjudication (DNS deep checks on every redirect hop) → after capture, Browser.close with timeout guards; returning drops the Browser and kills the child (kill_on_drop), so no leftover windows;
SSRF 防线：协议白名单 → 私网/保留 IP 字面量 → 连接时 DNS 深度解析（fail-closed）→ CDP 逐请求裁决（Electron 为 webRequest 同口径）。SSRF lines: scheme allowlist → private/reserved IP literals → connect-time DNS resolution (fail-closed) → per-request CDP adjudication (Electron enforces the same bar via webRequest).

7 · 二次开发7 · Development

推荐环境：Node 22 LTS（仓库 .mise.toml 锁定，mise install）、PowerShell 7（Windows）、Rust stable（仅 Tauri）。Recommended: Node 22 LTS (pinned in .mise.toml, mise install), PowerShell 7 on Windows, Rust stable (Tauri only).

# Build core and run its tests
cd HIA/core && npm install && npm run build && node --test test/
# Web dev server
cd HIA/web && npm install && npm run dev
# Electron / Tauri
cd HIA/electron && npm install && npm start
cd HIA/tauri && npm install && npm run build

代码约定：全部语义节点中英双语文档化注释（ROP）；三端渲染器产物哈希一致性由 CI 断言；新增第三方依赖须登记来源/版本/许可证并优先宽松许可。Conventions: bilingual (zh/en) doc comments on every semantic node (ROP); CI asserts renderer hash equality across ends; new third-party dependencies must record source/version/license, permissive licenses preferred.