webnovel-writer/docs/research/2026-04-14-ui-ux-pro-max-skill-architecture-research.md

UI/UX Pro Max Skill 架构调研报告

文档状态：draft（2026-04-14）

文档目标

本文档调研 ui-ux-pro-max skill 的真实工程结构，重点回答四个问题：

• 它不是一个单文件 prompt，那它到底是什么结构
• 它为什么能稳定工作，而不是只靠文案堆砌
• 其中哪些思想和架构值得 webnovel-writer 学习
• 哪些做法可以借鉴，哪些不能直接照搬

说明：

• 本次调研基于本地源码目录
  C:\Users\lcy\.gemini\tmp\webnovel-writer\ui-ux-pro-max-skill\src\ui-ux-pro-max
• 调研目标不是做逐文件复述，而是提炼其可迁移的系统设计
• 结论将服务于后续 references/csv 与 story-system 的收束型 spec

一句话结论

ui-ux-pro-max 能工作的核心，不是”提示词写得长”，而是它把 skill 做成了一个 外置知识库 + 通用检索内核 + 上层推理聚合器 + 持久化主文件/覆盖文件 + 平台分发适配 的小型知识系统。

我们真正缺的不是聚合器（StorySystemEngine 已经承担了这个角色），而是一套显式、结构化、可审查的裁决层——当前很多裁决逻辑仍散落在 engine 代码、CSV、context_manager 和 skill 文本里，还没有被收束成独立的配置层。

对我们最值得学习的，不是 UI 数据本身，而是这五个架构动作：

1. 把知识从 prompt 文本里拆到结构化表
2. 用统一检索 primitive 查询不同知识域
3. 用显式 reasoning 层把”查到什么”变成”最后该怎么裁决”
4. 把运行时结果落成 Master + Override 层级真源
5. 把平台差异收束到模板/元数据层，而不是污染主知识层

但有一个关键区别必须前置：ui-ux-pro-max 本质上是一套”查询时聚合”的准静态知识系统，它的知识域（风格、配色、字体、技术栈 best practices）不会随运行时事件演进。而我们的故事系统会——角色状态、关系、设定、世界规则都随章节提交持续变化。这意味着即使完整复刻它的前四层，仍然还要额外解决 Chapter Commit Layer 与 Projection Layer 的运行时演进问题。

调研范围

本次重点查看了以下内容：

• scripts/core.py
• scripts/design_system.py
• scripts/search.py
• data/*.csv
• data/stacks/*.csv
• data/_sync_all.py
• templates/base/*.md
• templates/platforms/*.json

它的真实系统分层

从目录结构看，ui-ux-pro-max 至少有三层物理结构，加一条独立运行路径：

ui-ux-pro-max/
├── data/        # 结构化知识库
├── scripts/     # 检索、推理、聚合、持久化
└── templates/   # skill 内容模板、平台安装元数据

运行路径则是：

query
  -> search.py
  -> core.py / design_system.py
  -> 结构化输出或持久化产物

1. 数据层：不是一张大表，而是“主题表 + 推理表 + 技术栈表”

它的数据层明显分了三类：

1.1 主题知识表

例如：

• styles.csv
• colors.csv
• charts.csv
• landing.csv
• products.csv
• ux-guidelines.csv
• typography.csv
• icons.csv
• react-performance.csv
• app-interface.csv
• google-fonts.csv

这些表并不追求统一成一个超大表，而是按“知识域”拆分。
对应证据见：

• scripts/core.py:17
• scripts/core.py:18
• scripts/core.py:68

其关键特点是：

• 每个 domain 有独立 file
• 每个 domain 有独立 search_cols
• 每个 domain 有独立 output_cols

也就是说，它不是“查整张表”，而是为每类知识定义了检索字段和展示字段。

1.2 推理表

它额外有一张 ui-reasoning.csv，不承担原始知识条目职责，而是承担：

• 类别到模式的映射
• 风格优先级
• 关键 effect
• 反模式
• decision rules

证据见：

• scripts/design_system.py:24
• scripts/design_system.py:43
• scripts/design_system.py:88

这很关键：
它把“检索结果”和“最终裁决”分开了。

1.3 技术栈表

它还单独维护：

• data/stacks/react.csv
• data/stacks/nextjs.csv
• data/stacks/vue.csv
• data/stacks/react-native.csv
• data/stacks/threejs.csv 等 16 张表

这些不是产品知识，而是实现层 best practices。

证据见：

• scripts/core.py:75
• scripts/core.py:95
• data/stacks/react.csv

这说明它的数据分层并不是按文件类型，而是按职责分层：

• 产品/风格/颜色/字体等“设计知识”
• reasoning“裁决知识”
• stack“实现知识”

运行时架构

2. 通用检索内核：一个 BM25 primitive 服务全部 domain

core.py 的核心并不复杂，但架构很干净：

1. CSV_CONFIG 注册 domain
2. _load_csv() 统一读表
3. _search_csv() 统一走 BM25
4. search() 做 domain 查询
5. search_stack() 做 stack 查询

证据见：

• scripts/core.py:17
• scripts/core.py:166
• scripts/core.py:221
• scripts/core.py:243

这里最值得学习的不是 BM25 本身，而是：

• 所有 domain 共用一个搜索 primitive
• 变化点全部下沉到配置表
• 脚本层只关心“读哪张表、查哪些列、吐哪些列”

这让它的数据表可以持续增加，而不用每加一张表就重写一套逻辑。

关键摘录如下：

CSV_CONFIG = {
    "style": {
        "file": "styles.csv",
        "search_cols": [...],
        "output_cols": [...]
    },
    "color": {
        "file": "colors.csv",
        "search_cols": [...],
        "output_cols": [...]
    },
}

这里也要顺手校准我们当前实现和它的真实差距。
webnovel-writer/scripts/reference_search.py 目前仍然是全局硬编码字段，而不是 per-domain 注册：

_SEARCH_FIELD_WEIGHTS = {
    "意图与同义词": 4,
    "关键词": 3,
    "核心摘要": 2,
    "详细展开": 1,
}

_CONTENT_COLUMNS = [
    "技法名称", "桥段名称", "人设类型", ...
]

这意味着当前更准确的对应关系不是
core.py -> reference_search.py，而是：

• core.py -> reference_search.py + 尚未存在的 CSV_CONFIG 注册层

3. 自动域识别：先判“查哪类知识”

detect_domain() 用关键词表先做 domain 猜测，再决定默认查什么。

证据见：

• scripts/core.py:198
• scripts/core.py:202
• scripts/core.py:216

这一步虽然简单，但很有启发：

• skill 不要求调用者总是显式指定表
• 系统先把自然语言问题归类到知识域
• 再进统一检索

对我们来说，这对应的是：

• 题材输入路由
• 任务意图到知识表映射
• 写前不同 step 的表选择

4. 上层聚合器：不是“查完就返回”，而是“查完再推理再组装”

design_system.py 才是这个 skill 真正的中枢。

其逻辑顺序是：

1. 先查 product
2. 从 product 结果得到 category
3. 用 ui-reasoning.csv 找对应 reasoning rule
4. 带着 style_priority 做多 domain 检索
5. 从 style / color / typography / landing 中挑最佳项
6. 组装成统一 design_system 字典

证据见：

• scripts/design_system.py:51
• scripts/design_system.py:64
• scripts/design_system.py:88
• scripts/design_system.py:163
• scripts/design_system.py:197

这比单纯 reference_search 高了一层，因为它已经不是“返回搜索命中项”，而是：

• 有路由
• 有裁决
• 有优先级
• 有最终统一输出对象

这其实已经很接近一个轻量 contract 生成器。

持久化架构

5. Master + Overrides：把运行时结果落成层级真源

它的另一个关键设计是：
运行时生成的设计系统可以被持久化为：

• design-system/<project>/MASTER.md
• design-system/<project>/pages/<page>.md

证据见：

• scripts/search.py:13
• scripts/design_system.py:561
• scripts/design_system.py:589
• scripts/design_system.py:612
• scripts/design_system.py:886

这套模式的意义非常大：

• MASTER.md 承担全局真源
• pages/*.md 只记录局部偏离
• 覆盖关系是显式的，不是隐式拼接

这和我们现在的 Story System 其实是同构的：

• MASTER_SETTING ≈ MASTER.md
• VOLUME / CHAPTER / REVIEW contract ≈ page override

也就是说，ui-ux-pro-max 的核心思想并不是 UI 专属，而是：

• 先统一主真源
• 再允许局部覆盖
• 覆盖必须被显式表达

分发与平台适配

6. 平台元数据与 skill 内容是分开的

templates/platforms/*.json 说明它不是只为一个 agent 平台准备的。

例如：

• templates/platforms/claude.json
• templates/platforms/codex.json
• templates/platforms/gemini.json

这些 JSON 负责定义：

• 安装根目录
• skillPath
• frontmatter
• title / description
• 是否附带 quickReference

证据见：

• templates/platforms/claude.json
• templates/platforms/codex.json
• templates/platforms/gemini.json

这意味着它把三类东西彻底分开了：

1. 知识内容
2. 运行时逻辑
3. 平台适配壳

这是一个非常值得抄的边界。

数据维护策略

7. 它允许工程脚本维护一致性，但不把脚本当 runtime 主逻辑

data/_sync_all.py 的作用很明确：

• 同步 products.csv、colors.csv、ui-reasoning.csv
• 处理 rename / remove / add
• 衍生一些默认配色与 reasoning 行

证据见：

• data/_sync_all.py:1
• data/_sync_all.py:63
• data/_sync_all.py:136

这个脚本说明它有“离线数据维护流水线”，而不是在 runtime 临时 patch 数据。

但这部分对我们要谨慎学习：

• 可以学它的“离线校验/同步”思想
• 不能照抄它的“程序生成内容”方式

因为我们的硬约束是：

• md -> csv 知识迁移必须人工完成
• 禁止自动抽取、自动翻译、自动拆句入库

所以对我们来说，应当保留：

• schema 校验脚本
• 编号唯一性校验
• 别名覆盖校验
• 路由表与规则表一致性校验

但不能写：

• 自动从 md 批量生成故事知识条目

对我们最值得迁移的思想

8. 我们应该学的，不是 UI 数据，而是把它映射进我们的六层主链

为避免和 story-system-evolution-spec.md 的六层术语打架，后文统一按 evolution-spec 6.1 的六层来描述迁移：

Knowledge Layer
    -> Reasoning Layer
        -> Contract Layer
            -> Runtime Assembly Layer
                -> Chapter Commit Layer
                    -> Projection Layer

ui-ux-pro-max 主要覆盖的是前四层，加上一套 MASTER.md + page override 的持久化真源；
而我们的故事系统还必须额外补上 Chapter Commit 和 Projection，因为知识会随章节运行时演进。

映射到我们项目里，更准确的对照应是：

evolution-spec 六层	ui-ux-pro-max 参照物	webnovel-writer 现状 / 目标	当前完成度
Knowledge Layer	products.csv、styles/colors/...、stack tables	references/csv 基础表、动态表、路由基础表	已有基础骨架：7 张规则表、路由表、README schema 已在位
Reasoning Layer	core.py 的 CSV_CONFIG + detect_domain()，以及 design_system.py 的 reasoning rule	题材与调性推理.csv、StorySystemEngine._route()、未来显式 CSV_CONFIG 与 reasoning config	半成品：已有 route 与 engine 裁决，但还没抽成显式配置层
Contract Layer	design_system 统一对象与 MASTER.md/pages/*.md	MASTER_SETTING / VOLUME_BRIEF / CHAPTER_BRIEF / REVIEW_CONTRACT / anti_patterns	已接上主骨架：engine.build() 可产出 MASTER/CHAPTER/ANTI，RuntimeContractBuilder 可产出 VOLUME/REVIEW
Runtime Assembly Layer	生成页面时“先 page override，再 MASTER”的装配逻辑	context_manager(contract-first) 与运行时上下文装配	半成品：context_manager 已读 runtime contracts，但整体仍是运行时装配器，尚未完全收束到 contract-first SSOT
Chapter Commit Layer	无完整对应；UI/UX skill 没有事件提交主链	CHAPTER_COMMIT + override ledger	已接线待治理：ChapterCommitService 已能生成 commit、写 event log、触发 amend proposal 与 projection writers，但 rejected/backlog 治理仍未完全闭合
Projection Layer	无完整对应；没有状态投影链	state / index / summaries / memory / dashboard	已接线待降级：已有四类 projection writer，但旧的 state/index/memory 散写与双写链路仍未完全退居投影层

如果只看搜索 primitive 和聚合器，对应关系要写得更严格一些：

• core.py ≈ reference_search.py + 尚未存在的 CSV_CONFIG 注册层
• design_system.py ≈ StorySystemEngine + story_system.py + RuntimeContractBuilder

8.1 我们真正缺的不是”聚合器”，而是”显式可审查的裁决层”

当前我们已经有：

• 题材与调性推理.csv
• 7 张规则表
• reference_search.py
• story_system_engine.py

而且当前系统已经不是“只有搜索，没有聚合”。
story_system.py 已经串起了 build -> persist story seed -> build runtime contracts -> persist runtime contracts 的主链：

contract = engine.build(...)
persist_story_seed(...)
volume_brief, review_contract = RuntimeContractBuilder(project_root).build_for_chapter(...)
persist_runtime_contracts(project_root, args.chapter, volume_brief, review_contract)

StorySystemEngine.build() 也已经直接产出 MASTER_SETTING / CHAPTER_BRIEF / anti_patterns：

return {
    "master_setting": {
        "meta": {"contract_type": "MASTER_SETTING"},
        ...
    },
    "chapter_brief": {
        "meta": {"contract_type": "CHAPTER_BRIEF"},
        ...
    },
    "anti_patterns": anti_patterns,
}

这意味着当前的 StorySystemEngine + RuntimeContractBuilder，实际上已经共同承担了 route / aggregate / persist 主链中的大部分职责。

所以现状并不是“还缺一个像 design_system.py 那样的聚合器”，而是：

• 已经有聚合器
• 但聚合裁决逻辑仍散落在 engine 代码、CSV、context_manager.py 和 skill 文本里
• 还没有像 ui-reasoning.csv 那样被提炼成一套显式、结构化、可审查、可测试的规则层

目前很多裁决还散落在：

• story_system_engine.py
• context_manager.py
• skill 文本
• 经验性 prompt

后续建议把这类规则显式收束为 Python 配置层，或落成一张独立 reasoning 表。

不一定非要 CSV，但必须是结构化、可审查、可测试的。

8.2 我们也应该继续强化”Master + Override”心智

这一点其实我们已经部分做到，但还需要在 spec 层写得更硬：

• MASTER_SETTING 是全局真源
• VOLUME_BRIEF 是卷级偏移
• CHAPTER_BRIEF / REVIEW_CONTRACT 是章级偏移
• accepted CHAPTER_COMMIT 是写后事实真源

这和 ui-ux-pro-max 的 MASTER.md + page override 是同一类思想。

但这里必须补一条关键校准：
ui-ux-pro-max 实际上是二层覆盖：

• MASTER.md
• pages/*.md

而我们已经是四层合同覆盖 + 写后事实层：

• MASTER_SETTING
• VOLUME_BRIEF
• CHAPTER_BRIEF
• REVIEW_CONTRACT
• accepted CHAPTER_COMMIT

这意味着同一个 field 可能在多个层级被覆盖，复杂度显著高于
page override trumps master 这种二层规则。
所以我们不能直接照搬它的覆盖判定逻辑，必须与 evolution-spec 8.5 的 override ledger 一起设计。

8.3 我们要学它的”注册式配置”，不是学它的数据体量

对我们真正重要的是建立一个统一注册表，明确：

• 每张表的职责
• 检索列
• 输出列
• 毒点列
• 是否属于基础表 / 动态表 / 路由表
• 是否允许进入 contract 主链

也就是做出属于我们的 CSV_CONFIG。

但这一步的起点应该是：承认当前 reference_search.py 只是一个通用 BM25 primitive，还不是注册式配置层。
它现在的检索列和展示列都是全局硬编码，不区分 domain：

_SEARCH_FIELD_WEIGHTS = {
    "意图与同义词": 4,
    "关键词": 3,
    "核心摘要": 2,
    "详细展开": 1,
}
_CONTENT_COLUMNS = [...]

因此下一步不是重写搜索算法，而是在它上面补一层 per-table / per-domain 的元数据注册。

8.4 我们要学它的”消费适配层隔离”

后续我们自己的 CSV / contract 系统，不应该直接把表结构暴露给所有消费者。

正确方向是：

• story-system 负责产出统一 contract
• context-agent / webnovel-write / webnovel-query / dashboard 只消费 contract
• 平台/skill 差异只停留在消费入口层

8.5 上下文窗口成本是一个被低估的差异

ui-ux-pro-max 的 CSV 检索结果直接进 prompt，单次交互的上下文窗口足够消化。但我们的写作任务书需要织入前文摘要、长期记忆、RAG 线索、当前状态、追读信号等多源数据，context-agent 自身的 research 阶段就要消耗大量上下文。

这意味着 reasoning 层不能照搬它"查完全部再推理"的模式，而是要考虑：

• 哪些数据源在 research 阶段按需查询（而非全量灌入）
• 最终任务书的信息密度要做取舍，不是"查到的都塞进去"
• reasoning 规则本身也要轻量，不能再额外占用大段上下文

这个差异直接影响"reasoning 层该做多重"的设计决策：我们的 reasoning 层应该是轻量配置 + 按需路由，而不是像 design_system.py 那样在单次调用中串联五六个 domain 的检索结果。

不能直接照抄的地方

9.1 不能照抄自动数据生成

ui-ux-pro-max 的 _sync_all.py 有一定“程序生成衍生数据”的倾向。
这对 UI 配色数据可以接受，但对故事知识库不适合。

我们的硬边界仍然要保持：

• 知识条目内容必须人工整理
• 脚本只能做校验、补空、对齐、去重、编号检查
• 不能自动从 md 迁移内容

9.2 不能把自动 domain detect 当成唯一真理

它的 detect_domain() 主要靠关键词启发式。
这在 UI 场景可以用，但故事系统不能只靠这个。

我们更适合的顺序是：

1. 用户显式题材 / .story-system contract
2. 题材与调性推理.csv
3. alias / fallback
4. 最后才是启发式猜测

注：这里说的是题材路由判定顺序，不同于 evolution-spec 7.2 的运行时上下文装配优先级。
后者是在合同已存在时，按 chapter -> volume -> master -> 题材与调性推理.csv -> genre-profiles.md -> templates/genres/*.md 组装输入。

9.3 不能让平台模板反向主导知识结构

平台适配层必须是壳，不应该反向决定 CSV 结构。

对我们下一步 spec 的直接启发

如果把这次调研落成一份可执行 spec，最应该写进 spec 的不是“继续加几百条 CSV”，而是以下结构要求：

10.1 建立我们的 CSV_CONFIG

这里的 CSV_CONFIG 不应取代 references/csv/README.md，两者应该明确分工：

• CSV_CONFIG：Python 代码层注册字典，供 runtime 的检索、路由、contract 注入直接消费
• README.md：人类可读的 schema / 录入规范 / 表边界说明
• 校验脚本：保证 CSV_CONFIG 与 README.md 的列定义、表角色、前缀约定保持一致

当前 README.md 已经承担了 schema 文档职责，例如：

| `关键词` | 是 | 高权重触发词，多值字段，统一使用 `|` |
| `核心摘要` | 是 | 供高权重召回与结果展示使用的简明摘要 |

### 命名规则.csv
| `命名对象` | 角色、书名、地点、势力、功法、道具等 |

因此更合理的落地方向不是”README 或 CSV_CONFIG 二选一”，而是：

• README 讲人话
• CSV_CONFIG 讲机器话
• 硬约束：必须有 CI 校验脚本保证两边对齐。两套 schema 定义如果没有自动化校验，很快就会漂移——这不是建议，是必须做的事

至少明确：

• 表名 / 文件名
• 角色
• 检索字段
• 输出字段
• 毒点字段
• 是否基础表 / 动态表 / 路由表
• contract 注入位置
• 是否允许进入主链
• 与 README 对应的 schema 章节

10.2 明确”route -> reasoning -> rule tables -> contract”的流水线

这一步是本次调研最关键的迁移结论。

10.3 为 CSV 主线补”研究-录入-校验-验收”的闭环

也就是：

• 人工选题
• 人工提炼
• CSV 录入
• schema / alias / route 校验
• contract 抽样验证

10.4 把 skills / agents / dashboard 都降级为消费层

消费统一 contract，而不是各自重新拼知识。

最终判断

ui-ux-pro-max 的成功，本质上说明了一件事：

一个强 skill 的核心，不是写一篇更长的说明书，而是把知识、检索、推理、持久化和消费边界做成明确分层。

对 webnovel-writer 来说，最值得学习的最终不是：

• 继续写更长的 skill 文本
• 继续堆更多零散 md
• 继续让每个入口自己决定查哪些 reference

而是：

• 用 references/csv 承担 Knowledge Layer（见 evolution-spec 6.1, 12.3）
• 用 story_system + 显式 reasoning 配置 承担 Reasoning / Contract Layer（见 evolution-spec 6.1, 7）
• 用 .story-system 承担主真源与覆盖层（见 evolution-spec 7, 8.5）
• 用 CHAPTER_COMMIT + override ledger + canonical event log 承担运行时演进主链（见 evolution-spec 9, 10）
• 让 skills / agents / dashboard 只消费统一输出与投影视图（见 evolution-spec 9.4, 12）

这才是它真正值得迁移过来的思想和架构。