安装与技能调用

Ark UI 是一个以 Git 仓库形式分发的 AI 技能（Skill），通过克隆到 Codex 技能目录完成安装，并在任务提示中使用 $ark-ui 触发。本页说明完整的安装、升级、调用语法与调用后技能内部的执行流程。

Purpose and Scope

本页覆盖以下内容：

• 将 ark-ui-skill 仓库安装到 Codex 技能目录（$CODEX_HOME/skills/ark-ui）的标准步骤。
• 从旧版本升级到新版本时的备份与 git pull 约定。
• $ark-ui 的调用语法：风格族与深度两个正交轴的组合表达方式。
• 未指定深度时的默认规则，以及调用后技能（SKILL.md）内部的加载顺序。
• 安装后可用的验证脚本命令。

以下内容不在本页范围内，由兄弟页面承接：

• 五个风格族的视觉特征与选择依据 → 参见风格族相关页面。
• 四档深度的完整规范与验收维度（references/depth-levels.md）→ 参见深度等级相关页面。
• 令牌文件与 React 组件 API → 参见组件与令牌相关页面。
• 审计脚本的检测规则细节 → 参见验证与审计相关页面。

Overview

Ark UI 技能采用"仓库即技能包"的形态：仓库根目录的 SKILL.md 是技能入口文件，其 YAML frontmatter 中的 name: ark-ui 与超长 description 字段共同决定技能何时被自动匹配触发；README.md 则给出人类可读的安装说明。

安装的本质是"把仓库放到 Codex 查找技能的固定路径下"：

Source: README.md

安装完成后，用户不需要执行任何注册或构建命令，直接在任务文本中写 $ark-ui 即可调用该技能。这种"克隆即用"的设计意图是：技能的全部内容（规范文档、起始模板、令牌、样例、脚本）都是静态资源，无需编译或安装依赖，克隆操作即完成部署。

调用时用户通过两个互相独立的选择轴表达意图：

1. 风格族（family）：ark、endfield、exa、popucom、corporate，决定界面的视觉性格。
2. 应用深度（depth）：minimal（极简）、moderate（中等）、complex（复杂）、maximal（极繁），决定这种性格覆盖到什么程度。

两个轴正交意味着 endfield + minimal 与 endfield + maximal 使用同一套设计语言，但视觉饱和度与实现工作量差异巨大——这是调用语法必须同时表达两个参数的原因。

Architecture

安装与调用在系统中的位置如下图所示：用户的调用文本触发技能加载，技能读取自身资源（references / assets / scripts），最终产出经过验证的界面代码。

要点解读：

• SKILL.md 是唯一入口：技能被触发后，其 frontmatter 中的描述决定适用范围（Hypergryph / Arknights / Endfield 系视觉请求、落地页、仪表盘、菜单、HUD 面板、设计系统、HTML/CSS/JS/React 组件、视觉 QA），正文的 "Start here" 流程则规定执行顺序。
• references/ 提供规范：深度等级、设计语言、风格配方等只按需加载——SKILL.md 明确要求只读取所选风格族对应的配方。
• assets/ 提供实现起点：原生起始模板、React 壳层组件、五族令牌文件与可运行样例。
• scripts/ 提供验证闭环：审计、脚手架、CSS 证据分析、截图脚本在实现完成后运行。

安装详解

标准安装

安装命令把仓库克隆到 $CODEX_HOME/skills/ark-ui，目录名必须保持 ark-ui，因为 SKILL.md 中的 name: ark-ui 与后续脚本引用的路径（如 $CODEX_HOME/skills/ark-ui/scripts/audit-ark-ui.mjs）都以这个目录名为锚点。

frontmatter 是技能身份声明，也是自动匹配触发的依据：

Source: SKILL.md

（description 完整文本见源文件第 3 行，其中列出全部触发关键词与两级选择轴。）

从旧版本升级

README 对已存在旧版本的情况给出明确约定：先备份自己的改动，再在该目录执行 git pull。

Source: README.md

这条规则的动机是技能目录同时是 Git 工作副本：如果用户在克隆出的目录里直接修改了模板或令牌，git pull 可能产生合并冲突或覆盖本地改动。备份先行是最低成本的防护。

升级后自检

安装/升级完成后，可以用 skill-creator 的校验脚本验证技能包结构是否完整：

Source: README.md

调用语法

基本形式

调用由三部分组成：$ark-ui 触发词 + 风格族 + 深度（可选）。以下示例摘自 README：

Source: README.md

第三个示例展示了一个重要能力：可以按区域限定深度——整体 exa + maximal，同时约束正文阅读区不超过 moderate。这与 SKILL.md 中"最密屏不得超过所选深度一个局部等级，主屏不得低于所选深度"的验收规则相呼应。

深度缺省规则

当调用中没有指定深度时，技能按产品类型自动取默认值，并在动手前显式说明该假设：

Source: README.md

设计意图：SKILL.md 规定"只有在深度会实质改变范围或返工时才提问"。默认值 + 显式声明假设的组合，让大多数调用无需往返确认即可开工，同时保留了用户事后纠正的依据。

调用后的契约表达

技能被调用后，设计契约会以根属性形式落到产出代码中。静态页面：

React 使用 ArkShell 的属性：

Sources:

• README.md
• SKILL.md

SKILL.md 强调"保持组件选择器语义化，使两个轴可以独立变化"——data-ark-theme 与 data-ark-depth 分开存放正是为了让风格与深度互不耦合。

Core Flow：调用触发后的执行时序

$ark-ui 被触发后，SKILL.md 规定了一个严格的"读取顺序 → 锁定契约 → 实现 → 迭代 → 验证"流程。下图展示一次典型调用的完整时序：

各步骤的来源依据：

1. 检查目标项目（第 12 行）：先看框架、视口、既有令牌与用户内容，避免无谓重造。
2. 选择族与深度（第 13–24 行）：只选一个族；深度缺省按产品类型取 moderate / complex 并声明假设。
3. 按需读取参考文档（第 25–27 行）：实现或代码评审还需读 frontend-evidence.md；溯源与资产决策读 source-ledger.md 与 legal.md。注意第 25 行明确"只读所选风格族在 recipes.md 中的配方"——这是一个控制上下文开销的按需加载设计。
4. 锁定契约（第 29–35 行）：改代码前先陈述 family、depth、证据模式与主屏必须允许用户完成的任务。
5. 实现（第 37–50 行）：从语义内容与任务层级出发，复用项目组件或复制起始模板，写入根属性契约。
6. 验证（第 132–151 行）：运行目标项目测试、lint、build，随后执行捆绑审计脚本并截图检查。

Sources:

• SKILL.md
• SKILL.md
• SKILL.md

安装产物：技能包内容清单

安装（克隆）完成后，技能目录包含以下可用资源。下表列出每个部分在调用中的作用：

Source: SKILL.md

脚本命令参考

安装后即可在命令行使用以下命令。它们同时也是技能工作流 Validate 阶段的一部分。

audit-ark-ui.mjs

Source: SKILL.md

对传入的 HTML 或 CSS 文件做启发式审计，标记缺失的可访问性/响应式项与常见模仿陈词（随机六边形、终端噪声、扫描线、故障效果、霓虹渐变等无信息角色的装饰）。

capture-showcases.mjs

Source: README.md

默认以 1440×900 重建五张复杂档样例截图；--mobile 追加真实 390×844 设备视口复验，出现横向溢出即返回失败（非零退出码），适合接入 CI。

analyze-css-evidence.py

Source: SKILL.md

接受 CSS URL 或本地文件，提取颜色、字体、动效与几何证据，用于为未收录的新官方页面补充证据，结果需回写 references/source-ledger.md。

quick_validate.py（安装自检）

见上文"升级后自检"一节，用于验证技能包结构完整性。

Configuration Options

调用与安装相关的可配置项汇总如下：

Sources:

• SKILL.md
• SKILL.md
• README.md
• README.md

Failure Modes, Edge Cases & Concurrency

升级冲突（本地改动 vs git pull）

技能目录是 Git 工作副本。若用户直接在 $CODEX_HOME/skills/ark-ui 内修改文件，升级时 git pull 可能冲突。缓解方式即 README 规定的"先备份自己的改动，再 git pull"。更稳妥的扩展方式是修改目标项目而非技能包本身（SKILL.md 第 41 行也要求在改 starter 类名时同步更新选择器）。

深度未指定时的歧义

未指定深度时技能不提问，而是按产品类型取默认并声明假设。仅在"深度会实质改变范围或返工"时才询问。边界情形：一个产品同时具有生产力与展示属性的混合界面（如带展示落地页的后台），默认取 moderate，用户可通过显式 complex 覆盖。

混合风格族的失控

把多个族的信号色（青、信号黄、水青、品红、橙、酸绿）堆进一个界面是该技能明确禁止的失败模式。约束是：最多两个族，次族只贡献一种受控特征（一种仪表、一个强调色或一种插画行为），主族保持对壳层、排版与主色的控制。

Source: SKILL.md

深度与密度的混淆

深度衡量实现覆盖与编排（壳层、舞台、组件、状态、动效、响应式），不是内容密度。常见误用是把 minimal 理解为"删标签、删状态、删焦点提示"，或把 maximal 理解为"随机 HUD 噪声、假系统码、无限动效"。SKILL.md 的 Avoid 清单对两者都明确禁止；验收规则还要求"最密屏不超所选深度一个局部等级、主屏不低于所选深度"。

Source: SKILL.md

许可与版权边界

安装该技能不等于获得任何官方素材的使用权。Avoid 清单禁止把 Hypergryph、Arknights、Endfield、Rhodes Island、Monster Siren 等受保护的标志、角色立绘、宣传图、UI 截图或 CDN 资源复制进交付物（除非用户拥有权利并显式提供），也禁止重新分发生产构建产物或官方站点的专有字体，以及宣称重建代码是官方源码。产物应是原创或正确归属。

Source: SKILL.md

Performance / Operational Notes

• 按需读取参考文档：recipes.md 只读所选族、family-depth-matrix.md 仅在多族比较时读取。这一设计直接控制每次调用的上下文/token 开销，是技能在长会话中保持可用的关键。
• 验证闭环可自动化：audit-ark-ui.mjs 与 capture-showcases.mjs（--mobile 溢出即失败）都是可脚本化命令，适合接入 CI；quick_validate.py 可作为安装后的冒烟检查。
• scaffold 复制而非链接：scripts/scaffold-ark-ui.py 把起始模板复制到目标目录，目标项目与技能包之间不建立运行时依赖，因此升级技能不会破坏已生成的项目。
• 静态资源、零构建：技能包不含需要安装的依赖或构建步骤，git clone 即部署完成；这也让升级退化为纯 git pull 操作。

Sources:

• SKILL.md
• SKILL.md
• README.md

Extension Points

• 新增风格族：新族需要补充 references/recipes.md 配方、assets/tokens/ark-ui.tokens.json 中的令牌族，以及（可选）assets/showcases/ 样例；SKILL.md 的 frontmatter 描述也应更新以覆盖新触发词。为新官方页面做研究时，先用 analyze-css-evidence.py 提取证据并回写 references/source-ledger.md。
• 扩展审计规则：scripts/audit-ark-ui.mjs 是启发式审计器，可直接在其中追加新的"模仿陈词"检测模式，所有调用共享同一审计标准。
• 项目侧定制：推荐的定制位置是目标项目——复制 starter 后重命名类/ID/data 属性，并在同一次修改中更新全部 JS 选择器（SKILL.md 第 41 行）。令牌按项目命名习惯改名后使用（第 42 行）。
• 接入其他平台：仓库提供 agents/openai.yaml，是技能接入非 Codex 运行时的配置入口。

Source: SKILL.md

Related Links

• SKILL.md — 技能入口：触发规则、Start here 流程、Avoid 与 Validate 清单
• README.md — 安装说明、五族对照表、四档深度表与调用示例
• references/depth-levels.md — 四档深度完整规范（深度选择与验收的权威来源）
• references/recipes.md — 五族配方（调用后按所选族读取）
• assets/tokens/ark-ui.tokens.json — 五族令牌参考
• assets/react/ArkUI.jsx — React 壳层组件（theme / depth 属性入口）