新官方页面的证据研究流程
当任务要求证据时效性（freshness），或 ledger（证据台账）尚未覆盖某个产品/页面时，ark-ui skill 会启动一套标准化的"官方页面证据研究流程"：公开检查目标页面与其加载的生产 CSS/JS，用 scripts/analyze-css-evidence.py 抽取颜色、字体、动效与几何证据，再把 URL、资产、日期、框架、可复用模式按置信度分级记录进 references/source-ledger.md。本页完整剖析该流程的触发条件、工具链、台账数据模型、置信度体系与法律边界。
Purpose and Scope
本页覆盖 ark-ui skill 中新增官方页面证据的端到端研究机制，包括：
- 触发条件：什么任务形态会启动新证据研究
- 工具链：
scripts/analyze-css-evidence.py的调用方式与产出物 - 台账结构：
references/source-ledger.md的数据模型（官方视觉表面、生产资产清单、token 样本、官方评论、GitHub 调查、派生观察） - 置信度体系：Direct / Supported / Inference 三级分级如何约束表述
- 复核机制：research pass 日期戳与 SHA-256 资产指纹的活体验证
- 归因边界：官方 vs 社区 vs 二次证据的区分规则
以下相关主题由兄弟页面承接，本页不展开：
- 证据锁定下的界面迭代与视觉 QA 流程，见 SKILL.md 中 "Iterate with an evidence lock" 一节（对应目录中的核心工作流页）
- 证据的合法性与许可边界细节，见 references/legal.md
- 从证据推导出的前端实现模式（mask、blend-mode、clip-path 等），见 references/frontend-evidence.md
- 视觉语言与产品家族选择，见 references/design-language.md
Overview
ark-ui skill 的核心哲学是"从有据可查的视觉与实现证据出发构建原创界面，而不是凭模糊的 'cyberpunk' 式提示词"（SKILL.md L7-L8）。要维持这个承诺，skill 必须持续持有一份可验证、可复核、可溯源的官方页面证据库。
这份证据库就是 references/source-ledger.md。它记录了截至某个 research pass（当前为 2026-07-20，Asia/Shanghai）对 Hypergryph 官方公开页面的直接观察：
| 关键概念 | 含义 |
|---|---|
| research pass | 一次完整的证据采集批次，带时区日期戳，用于声明证据的新鲜度 |
| Direct（直接） | 在渲染后的官方页面或其公开加载的生产 CSS/JS 中直接观察到的事实 |
| Supported（有据） | 由官方/认证公司渠道或官方招聘站点陈述的事实 |
| Inference（推断） | 从反复出现的直接观察中派生出的解释，不是公司陈述 |
| production asset manifest | 生产资产清单：SHA-256 + 字节数 + Last-Modified + 公开 CDN URL，"是指针，不是打包依赖" |
典型使用场景：
- 用户要求为某个 ledger 未覆盖的新产品（例如鹰角未来新作官网）构建界面 → 触发新研究
- 已有证据可能过时（官方改版）→ 触发活体复核
- 需要引用某个具体颜色/字体/动效，但当前 ledger 中没有对应条目 → 补充采集
Architecture
架构要点：
- 单向数据流：所有证据只能来自公开层（渲染页面、生产 CDN、官方渠道、GitHub 公开检索），不存在私有端点或凭据访问。
- 分析器是唯一工具入口：对 CSS/JS 的机械化证据抽取由
analyze-css-evidence.py完成，避免人工"目测"引入主观漂移。 - 台账是唯一持久化层：新证据必须写入
source-ledger.md，并区分直接观察与推断（SKILL.md L153-L161）。 - legal.md 作为旁路约束：它不参与采集，但约束记录表述（例如不得声称"官方 Hypergryph UI"）与社区代码的许可决策。
核心流程详解
1. 触发条件：何时启动新研究
SKILL.md 明确定义了触发条件（SKILL.md L153-L161）：
When the task requires freshness or a product not covered in the ledger, inspect the public page and its loaded CSS/JS.
即两类触发：
| 触发情形 | 典型信号 | 对应动作 |
|---|---|---|
| 需要新鲜度 | 任务涉及时效性主张、上次 research pass 距今较远 | 先复核现有条目，再决定是否补采 |
| ledger 未覆盖的产品 | 用户提到的产品/页面在台账中无条目 | 完整采集：页面 + 生产 CSS/JS + 官方渠道 |
台账首页即声明了这个约束：Research pass: 2026-07-20 (Asia/Shanghai). Re-check live sources before making time-sensitive claims.（references/source-ledger.md L3）
2. 采集阶段：公开检查页面与其生产资产
采集的核心对象是"公开页面 + 它加载的生产 CSS/JS"。ledger 的"Official visual surfaces"表（source-ledger.md L22-L40）记录了当前覆盖的 15 个官方表面，每行记录：表面名称、URL、直接观察到的内容。
以 Endfield CN 为例，一行记录的结构是：
| Endfield CN | https://endfield.hypergryph.com/ | Pale vertical rail, white/charcoal/yellow shell, segmented key art, docked platform actions, large section identifiers, Next.js App Router/CSS Modules/Swiper patterns |Source: references/source-ledger.md
观察维度刻意覆盖四类信息：
- 结构布局（Pale vertical rail、dock 的存在）
- 色彩与表面（white/charcoal/yellow shell）
- 内容组织（segmented key art、large section identifiers）
- 技术栈指纹（Next.js App Router / CSS Modules / Swiper）
同时明确排除项——台账在 Scope 一节声明：No source map, private endpoint, credential, or non-public repository was accessed.（source-ledger.md L20）这是流程的合法性底线：只看公开可加载的生产产物，不碰 sourcemap、不碰私有端点、不碰需要凭据的资源。
3. 分析阶段：analyze-css-evidence.py
SKILL.md 给出的标准调用形式（SKILL.md L155-L159）：
python3 "$CODEX_HOME/skills/ark-ui/scripts/analyze-css-evidence.py" <css-url-or-file>Source: SKILL.md
参数说明（依据 SKILL.md 的 <css-url-or-file> 占位符与 "Bundled code" 描述）：
| 参数 | 类型 | 说明 |
|---|---|---|
<css-url-or-file> | string | 一个公开 CSS 的 URL，或已下载到本地的 CSS 文件路径 |
脚本职责（依据 "Bundled code" 一节：extract color, font, motion, and geometry evidence from public CSS，SKILL.md L175）：
- color（颜色）：主导色、可选强调色及其使用强度
- font（字体）：字体家族清单，包括需要许可替代的自定义/展示字体
- motion（动效）：keyframe 家族（如 orbital/point/glint、floating layers、bounce feedback）
- geometry（几何）：mask 数量、blend-mode 声明数、clip-path 等结构性证据
实现细节说明：
scripts/analyze-css-evidence.py的内部实现（正则规则、输出格式）在本页撰写时未读取（源工具预算已用尽），上述能力描述依据 SKILL.md 的官方文档化描述，未逐行验证脚本实现。
4. 记录阶段：写入台账并区分置信度
SKILL.md 对记录格式的要求（SKILL.md L161）：
Record the page URL, asset URL, retrieval date, observed framework, colors, fonts, and reusable pattern in
references/source-ledger.md. Separate direct observations from inference.
即每条新证据必须包含七要素：页面 URL、资产 URL、抓取日期、观察到的框架、颜色、字体、可复用模式，并区分"直接观察 vs 推断"。
台账的三级置信度体系（source-ledger.md L14-L18）：
- **Direct**: observed in the rendered official page or its publicly loaded production CSS/JS.
- **Supported**: stated by an official/verified company channel or official recruiting site.
- **Inference**: interpretation derived from repeated direct observations; not a company statement.Source: references/source-ledger.md
三级体系的设计意图：
- Direct 是最强证据——来自渲染页面或公开生产 CSS/JS，可被任何人生成 SHA-256 复核。
- Supported 是公司陈述——如 Weibo 官方帖、Bilibili 官方专栏、官方招聘站。它证明公司观点，但不等于页面实现细节。
- Inference 是 skill 自己的解释——从重复出现的直接观察中归纳，用"5 条派生观察"（source-ledger.md L111-L119）显式存放，避免与官方事实混淆。
生产资产清单与指纹机制
"Production asset manifest" 是台账的技术核心（source-ledger.md L42-L63）。它把每个观察到的生产资产记成四元组：
| SHA-256 | Bytes | Last-Modified | Public production asset |
|---|---:|---|---|
| `55b9681174b545b4b5fbabcc0127afd76a7fe753c2ce0a9ce302a8ea56f7c380` | 107,343 | 2026-02-09 | https://web.hycdn.cn/arknights/official/_next/static/css/3759d2520092f84b.css |Source: references/source-ledger.md
设计意图有三：
- 可复核性：任何人可对同一 URL 重新计算 SHA-256，验证资产是否未变。台账头部注明：
SHA-256 and decoded byte size were computed from HTTP responses on 2026-07-10. These files are evidence pointers, not bundled dependencies.（source-ledger.md L44） - 免责边界："evidence pointers, not bundled dependencies" 明确了这些 URL 是指针，skill 不将其打包进交付物——与 legal.md 的"不得再分发生产 bundle"呼应。
- 变更检测：活体复核时对比 SHA-256 即可判断官方是否改版。
"Direct token samples" 一节（source-ledger.md L65-L71）给出了从各家族 CSS 直接抽取的 token 样本，是分析器输出落地的实际形态：
- Arknights current CSS: dominant `#000`, `#fff`, `#18d1ff`; Bender, Oswald, Novecento Sans Wide, Source Han Sans; masks, mix-blend overlays, 7rem section labels, orientation-specific layout.
- Endfield CSS: dominant `#191919`, `#fff`, `#fffa00`; optional `#00ffa2`; Gilroy, Space Grotesk, Novecento Sans Wide; clip paths, yellow load wipe, vertical rail, large identifiers.Source: references/source-ledger.md
格式规律：主导色 → 可选色 → 字体家族 → 结构性模式。这正是分析器四类证据（color/font/motion/geometry）在台账中的落点。
活体复核流程（Live Verification）
台账设有 "2026-07-20 live verification" 一节（source-ledger.md L73-L78），是研究流程的闭环环节：在最新 research pass 时，对关键表面重新访问并核对资产指纹。
复核条目的典型结构：
- Arknights CN still exposes the black edge shell, cyan active state, bilingual indexed navigation, current news categories, and an operator/world/media hierarchy. Its main production stylesheet still matches SHA-256 `55b9681174b545b4b5fbabcc0127afd76a7fe753c2ce0a9ce302a8ea56f7c380`, with `#000`, `#fff`, and `#18d1ff` dominant, 14 mask declarations, 8 blend-mode declarations, and six keyframe families.Source: references/source-ledger.md
复核条目的判定逻辑："still matches SHA-256 ..."。如果指纹一致，则既有观察（包括 mask/blend-mode/keyframe 的量化计数）继续有效；若指纹变化，则说明官方改版，需要重新执行采集→分析→记录全流程。
下面的时序图展示一次完整的新证据研究循环：
官方评论与 GitHub 调查
官方评论（Supported 级证据）
台账 "Official commentary and recruiting" 一节（source-ledger.md L80-L90）收录公司渠道陈述，例如 Weibo 官方帖（介绍 UI 设计师栊一水又、阿树、AZE、阿福并讨论 UI 制作）、Bilibili 官方"何以鹰角"系列、官方招聘站的角色分类。这些提供 Supported 级上下文——证明"UI 被公司作为跨产品的工艺来讨论"，但不提供实现细节。
该节末尾有一条明确的排除规则（source-ledger.md L90）：
Do not treat fan video essays, Behance redesigns, or secondary job mirrors as official design rules.GitHub 身份纠错与社区仓库许可决策
"GitHub search findings" 一节（source-ledger.md L92-L109）承担两个职责：
1. 身份纠错（Identity correction）——防止常见的错误归因：
- `https://github.com/HyperGryph` has one repository, `HyperGryph/hyperloop`, described as University of Guelph's Hyperloop Team Software. It is unrelated to Shanghai Hypergryph Network Technology. This prevents a common false attribution.Source: references/source-ledger.md
legal.md 同样记录了这条结论（references/legal.md L11）：No verified official Hypergryph GitHub organization or licensed frontend repository was found during the July 2026 research pass.
2. 社区仓库许可决策——对每个社区仓库记录检视的 commit、许可证与处置决定（MIT 的 Yue-plus/nextjs-starter-arknights 可作参考但不复制；无许可证的 sayuriu/endfield、Jet-Fighters/cyber-music 标记 "Do not copy"）。
3. 反直觉原则：Public availability does not make them official or grant rights to bundled Hypergryph assets.（source-ledger.md L109）——公开可得 ≠ 官方 ≠ 授予资产权利。
派生观察：从证据到设计法则
台账最后一节 "Derived observations"（source-ledger.md L111-L119）是研究流程的产出物——把 Direct 级观察归纳为 Inference 级设计法则：
11. The stable cross-product identity lies in information hierarchy, edge docking, bilingual micro-labels, and controlled accent—not one fixed color palette.
22. Each title is allowed a strong sub-identity: industrial cyan, field yellow, cosmic aqua, or playful blue/yellow.
33. Production marketing sites favor media-heavy full-screen sections and extensive portrait-specific styling.
44. Technical credibility comes from real layout structure, state, and restrained metadata, not random HUD decoration.
55. The company repeatedly uses custom/display fonts, but redistribution should use licensed substitutes.Source: references/source-ledger.md
这五条是整个 skill 设计语言（design-language.md）、tokens（ark-ui.tokens.json 的五个证据派生主题家族）与审计规则（audit-ark-ui.mjs 对"模仿陈词滥调"的检查）的上游依据。它们解释了 SKILL.md "Avoid" 一节中为何禁止"随机六边形、终端噪声、扫描线、glitch、霓虹渐变"——因为真实官方证据中不存在这些装饰（SKILL.md L126）。
Configuration / 记录字段参考
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Surface / 页面 URL | string | ✅ | 官方页面地址，如 https://endfield.hypergryph.com/ |
| Asset URL | string | ✅ | 生产 CDN 资产地址（web.hycdn.cn / web-ipv6.hycdn.cn） |
| Retrieval date | date | ✅ | 抓取日期；台账头部还需标注时区，如 2026-07-20 (Asia/Shanghai) |
| Observed framework | string | ✅ | 技术栈指纹：React 18.2、Next.js App Router、CSS Modules、Swiper、Umi |
| Colors | list | ✅ | 主导色 + 可选色，如 dominant #191919, #fff, #fffa00; optional #00ffa2 |
| Fonts | list | ✅ | 字体家族；再分发时须用有许可的替代品 |
| Reusable pattern | string | ✅ | 可复用模式：clip paths、vertical rail、dock、floating layers、bounce feedback |
| SHA-256 | string | ✅ | 资产指纹，用于活体复核 |
| Bytes | int | ✅ | 解码后字节大小 |
| Last-Modified | date | ✅ | HTTP 响应头日期 |
| Confidence | enum | ✅ | Direct / Supported / Inference |
API 参考
analyze-css-evidence.py <css-url-or-file>
python3 "$CODEX_HOME/skills/ark-ui/scripts/analyze-css-evidence.py" <css-url-or-file>Source: SKILL.md
用途：从公开 CSS 中提取四类证据（color、font、motion、geometry），供记录进台账。
参数：
css-url-or-file(string, 必填)：公开生产 CSS 的 URL，或本地已下载的 CSS 文件路径。
产出：可直接落入台账 "Direct token samples" 与 "live verification" 条目的结构化证据（主导色、字体家族、mask/blend-mode/keyframe 计数等）。
注：脚本的内部实现与确切输出格式未在本次文档撰写中读取源码验证，本节依据 SKILL.md 对该脚本的官方描述。
失败模式、边界与并发
失败模式与处理
| 失败模式 | 判定信号 | 处理策略 |
|---|---|---|
| 官方改版导致证据过时 | 活体复核时 SHA-256 不匹配 | 重新执行完整采集→分析→记录流程，更新日期戳 |
| 时效性主张未复核 | 任务涉及"当前""现在"类主张 | 台账头部的规则：Re-check live sources before making time-sensitive claims |
| 错误归因 | 把社区/同人仓库当官方 | 参考 "Identity correction"：HyperGryph/hyperloop 是滑铁卢大学 Hyperloop 队，与上海鹰角无关 |
| 二次证据被当规则 | 粉丝视频、Behance 重设计、二手招聘镜像 | Do not treat fan video essays, Behance redesigns, or secondary job mirrors as official design rules |
| 越权访问 | sourcemap、私有端点、凭据、非公开仓库 | 流程红线：No source map, private endpoint, credential, or non-public repository was accessed |
| 无许可证社区代码 | GitHub 仓库无 detected license | 台账明确 "Do not copy"；MIT 仓库也仅作参考且资产需独立权利审查 |
| 字体再分发风险 | 官方使用自定义/展示字体 | 派生观察 #5：redistribution should use licensed substitutes；skill 的 tokens 使用安全回退字体栈 |
边界条件
- 研究范围上限：仅公开可加载的生产产物。台账明示 "evidence pointers, not bundled dependencies"——URL 是指针，不打包。
- 置信度边界：Inference 不能升格为公司陈述。台账用独立章节存放派生观察，与 Direct/Supported 事实隔离。
- 称谓边界：legal.md 要求除非用户在授权官方素材上工作，否则应说 "Hypergryph-inspired" / "evidence-based family resemblance"，而非 "official Hypergryph UI"（references/legal.md L23）。
并发与一致性
- 台账是单文件顺序更新（
references/source-ledger.md），天然避免分布式写入冲突。 - 一致性锚点是 research pass 日期戳 + SHA-256 指纹：同一批次内的证据共享同一日期戳；资产指纹是内容寻址的，不依赖时间戳即可验证一致性。
- 活体复核采用"仍匹配则沿用"（still matches）语义，即指纹一致时直接保留既有量化观察（如 14 mask / 8 blend-mode / six keyframe families），无需重算。
扩展点：如何新增一个产品家族
要为新产品（ledger 未覆盖）补证据，标准路径：
- 访问其公开官网，记录 URL 与直接观察（结构/色彩/内容组织/技术栈）。
- 抓取其加载的生产 CSS/JS，记录 SHA-256、Bytes、Last-Modified、URL。
- 运行
analyze-css-evidence.py <css-url-or-file>提取 token 级证据。 - 在台账补一行 "Official visual surfaces"、一行 "Production asset manifest"、必要时更新 "Direct token samples"。
- 若存在官方渠道陈述，补 "Official commentary" 行（Supported 级）。
- 若引入了新设计法则，追加编号条目到 "Derived observations"（Inference 级）。
- 检索 GitHub 是否有官方组织（纠错）与相关社区仓库（许可决策）。
- 更新台账头部的 research pass 日期。
下游联动：新证据将影响 assets/tokens/ark-ui.tokens.json 的主题家族、references/design-language.md 的家族描述，以及 references/family-depth-matrix.md 的家族×深度矩阵。
Related Links
- SKILL.md — Research new official pages — 流程的权威定义（触发条件 + 工具调用 + 记录要求）
- references/source-ledger.md — 研究台账本体（表面清单、资产指纹、token 样本、GitHub 调查、派生观察）
- references/legal.md — 证据合法性边界与称谓规范
- references/frontend-evidence.md — 从证据推导的实现模式
- references/design-language.md — 证据的消费端：视觉语言定义
- scripts/analyze-css-evidence.py — 证据提取脚本