Identity Forge

Identity Forge MCP

为编码 Agent 提供设计系统、品牌命名和域名研究。

面向用户 · 面向 Agent · MCP 工具 · CLI 参考 · 文档

免费使用。 79 套设计套件中有 69 套免费，并提供全部 6 种导出格式、CLI、MCP 服务和 API。无需账户。Pro 可解锁另外 10 套套件、每月 1,000 次 AI 生成和高级功能。

面向用户

Identity Forge 会在编码 Agent 开始构建之前，为它提供一套完整的视觉系统。你可以自行选择设计套件，也可以让 Agent 根据你的产品和期望的氛围为目录中的套件排序。每套套件都包含字体、语义颜色令牌、布局、图案、注意事项，以及 Agent 可以据此构建的 DESIGN.md。

Agent 可以将套件导出为 CSS、Tailwind v3 或 v4、shadcn 注册表数据、DTCG 令牌或 JSON，然后在冲突保护下应用。品牌命名、域名研究和可分享的客户端项目也集成在同一工作流中。

公开的免费套件无需账户即可使用。浏览设计套件，或在安装前了解 Agent 工作流的运作方式。

观看实际演示

这部三分钟的生命周期影片展示了设计系统从初次选择，到产品图像、电商网站重建、后续品牌更新、旧网站重建和团队评审的全过程。Aubade 商店和 Shiftly 重建都是基于真实 Identity Forge 设计系统，由 Agent 一次性完整构建的项目。Commonkeep 评审则在真实的评审体验中使用合成演示数据。

https://github.com/user-attachments/assets/fc3cdba2-4876-46e5-a92a-09ce6d7071ff

下载完整分辨率的 1080p WebM。

面向 Agent

将本地 MCP 服务安装到你使用的客户端中：

npx --yes identityforge@latest install --client claude-code   # Claude Code
npx --yes identityforge@latest install --client cursor        # Cursor
npx --yes identityforge@latest install --client vscode        # VS Code / Copilot
npx --yes identityforge@latest install --client codex         # Codex

也支持：gemini、opencode、pi。所有客户端都运行相同的本地 stdio 服务，install 会合并到现有配置中，而不是替换它。七种客户端的配置路径均列于安装到 Agent。

公开的免费套件无需密钥即可立即使用。告诉你的 Agent：

使用 Identity Forge 为这个产品挑选合适的主题、应用主题，并遵循 DESIGN.md。

登录后即可使用持久化项目、已保存的工作、经身份验证的配额或 Pro 访问权限：

npx --yes identityforge@latest login

还没有账户？在浏览器中注册、完成安全检查、选择 Send verification email，然后打开邮件中的链接。接着选择 Confirm email and continue，批准恢复的授权，CLI 就会自动收到密钥。

用例发现

每个用例类别都有两项检查。首先，工具包的编写目标受众或 bestFor 必须提到该类产品。然后，根据文本对比度、图表系列区分度和信息密度等具体令牌测量结果，对符合条件的工具包进行排序。视觉标签有助于搜索，但不能证明产品适配性。技术评分再高，也不能让不相关的工具包进入某个类别。由于整个目录正在等待重新丰富数据，每个类别的文字说明目前已停用，因此返回的评分没有附带解释句。

• list_themes({ use: "data-dashboard" }) 会返回为仪表盘编写的工具包，并按测得的仪表盘适配度排序。
• list_themes({ q: "calm fintech dashboard" }) 会在情绪、行业和用例类别中运行支持同义词的排序搜索。
• search_themes 会返回未经排序的完整目录，让 Agent 自行判断细微的需求。

使用类别筛选候选项，并通过排序结果进行比较。不要把评分当作解释：它会在考虑编写时的意图后对技术适配度进行排序，但不会说明工具包为何适合某项具体需求。

对于数据类别，有比评分更好的答案。每个工具包摘要都包含一个 charts 区块，数据按工具包默认模式测量：minDeltaE 和 cvdMinDeltaE（系列颜色中最接近的一对，分别为普通模式和色盲模拟模式下），distinct、hueFamilies、severityHeadroom（任意系列接近破坏性、警告和成功状态角色的程度——0 表示某个类别颜色就是状态颜色）、sequentialReady，以及 designed。如果工具包未定义图表槽位，而是从品牌角色中循环选取五种颜色，则 designed 为 false。这些都是测量结果，因此与适配度评分不同，可以直接作为推荐理由告知用户。

用例类别：data-dashboard、admin-internal-tool、saas-marketing、landing-page、ecommerce-store、portfolio、editorial-blog、docs-knowledge-base、mobile-app、business-services、community-social、ai-agent-chat。

同样的发现功能也适用于工具包图库和 HTTP API（GET /api/v1/kits?use=…&q=…，参见 llms.txt）。

安装到 Agent

install --client <name> 会为该 Agent 写入 MCP 服务配置，并合并任何现有配置：

客户端	--client	配置文件
Claude Code	claude-code	.mcp.json
Cursor	cursor	.cursor/mcp.json
Codex	codex	~/.codex/config.toml
Gemini CLI	gemini	.gemini/settings.json
VS Code / Copilot	vscode	.vscode/mcp.json
opencode	opencode	opencode.json
Pi	pi	.pi/agent/mcp.json

它们都会通过 npx -y identityforge@latest mcp 运行相同的本地 stdio 服务。 安装后，identityforge doctor --client <name> 会检查客户端是否指向滚动更新的软件包，并初始化该软件包的 MCP 服务，不会调用 Identity Forge API，也不会消耗配额。

安装 Agent 插件和技能

该仓库还将 MCP 服务与 Agent Skill 打包在一起，告诉 Agent 何时使用 Identity Forge、免费访问与经过身份验证的访问有何不同，以及如何引导用户在待处理的浏览器授权恢复前执行 Send verification email。

Claude Code：

claude plugin marketplace add KasayoDotCom/identityforge-mcp
claude plugin install identity-forge@identity-forge

GitHub Copilot CLI：

copilot plugin marketplace add KasayoDotCom/identityforge-mcp
copilot plugin install identity-forge@identity-forge

Codex 和其他兼容 Agent Skills 的客户端：

npx skills add KasayoDotCom/identityforge-mcp

其中包含用于目录分发的 Cursor 元数据。在此处列出之前，请使用上方的 install --client cursor 命令连接到同一个 MCP 服务。

MCP 工具

连接后，Agent 会获得 63 个工具。浏览免费工具包无需密钥；适用的权限范围会另行注明。

查找设计套件

• list_themes：以简洁摘要浏览目录。使用 use 按用途类别排序，使用 q 执行排序搜索，使用 offset 翻页，并按 featured、popular、recent、name 或 fit 排序。
• search_themes：返回未经排序的完整目录，适用于细微到无法按用途类别排序的需求简述。
• similar_themes：给定一个套件 slug，根据配色、标签和受众查找相近套件。
• match_palette：给定现有品牌颜色，按感知色差对套件排序。

在套件之外选择字体

套件已指定标题、正文和等宽字体。以下两个工具适用于套件未指定字体的情况。

• search_fonts：按名称或类别浏览 Google Fonts 目录，也可以传入 like 和你已有的字体系列，查找相似字体。仅提供元数据；like 不会读取字形，因此在承诺采用前请确认实际效果。
• suggest_font_pairings：提供精选的标题／正文／等宽字体搭配表，或查找适合用户已选定字体系列的搭配。

读取并应用

• get_design_md：获取套件的 DESIGN.md，即完整设计简述。
• get_tokens：以 dtcg、css、tailwind-v3、tailwind-v4、shadcn-registry 或 json 格式获取令牌。
• apply_theme：将 DESIGN.md、令牌文件和 identityforge.json 标记写入项目。如果文件不是由它写入的，它会拒绝覆盖，详见下文。

apply 会写入什么，以及不会覆盖什么

apply_theme（以及 identityforge apply）会在目标目录中写入三个文件：

Identity Forge 请求会携带一个随机引用标识，该标识仅在当前 CLI 或 MCP 进程期间有效。本地应用会报告一个有明确范围的结果：文件已写入、产物已是最新、安全冲突导致拒绝，或失败阶段。报告包含数量和分类，不包含本地路径或错误文本。作为 MCP 服务运行时，请求还会携带编辑器或 Agent 在 MCP 握手中已发送的客户端名称（claude-code、cursor-vscode、codex），因此可以将使用情况归因于具体产品，而非归于无名来源。上述信息均不包含路径、文件名、提示词、文件内容、仓库名称、异常文本或持久安装标识符。设置 IDENTITYFORGE_TELEMETRY=0 可省略进程引用标识和本地结果报告；常规 API 请求仍会出现在服务访问日志中。

文件	内容
DESIGN.md	Agent 据此构建的设计简述
<slug>.css / .json / .js	令牌，文件名根据你请求的格式确定
identityforge.json	标记：记录应用的套件、版本，以及每个已写入文件的 SHA-256

标记属于你的仓库，而非套件。它记录了此代码库构建所依据的内容；这是服务端无法获知的信息，因此请提交该文件。它也使应用过程更加安全：写入任何内容之前，apply 都会将磁盘上的文件与标记中的哈希值进行比较。

• 不存在的文件会被创建。
• 内容已与套件匹配的文件会保持不变。
• 上次应用写入且仍逐字节相同的文件，会在套件更新时一并更新。
• 未记录在标记中的文件（例如你自行编写的 DESIGN.md），或写入后发生变化的文件，都属于冲突。

发生冲突时，默认完全不写入任何内容，列出所有冲突文件，并以非零状态码退出。只有在规划好所有文件后才会开始写入，因此获取文件失败不会导致目录只应用了一部分。

identityforge apply acid-signal-black --preview   # plan only, writes nothing
identityforge apply acid-signal-black             # refuses if anything conflicts
identityforge apply acid-signal-black --force     # overwrites, content is lost

--force 具有破坏性且无法恢复：冲突文件的当前内容将丢失，报告会列出每个冲突文件。请先预览，向用户展示将发生的更改，并让他们自行决定。

stamp 记录了什么，以及后续 apply 如何读取它

{
  "stampVersion": 1,          // shape of this file, so a reader never has to guess
  "designMdContract": "1.0",  // shape of the DESIGN.md you built against — not the kit's
                              // revision and not this file's. Three different versions
                              // live here; flattening any two invents a baseline.
  "kit": {
    "id": "c2d13a12-…",       // permanent. diff against this, never the slug
    "slug": "sage-slate-editorial",
    "version": 0,             // the kit's monotonic revision, as the export reported it
    "designMdDigest": "sha256:…"
  },
  "layers": [],
  "artifacts": [{ "path": "DESIGN.md", "hash": "sha256:…", "writtenAt": "…" }],
  "integration": { "tokensEntry": null },
  "appliedAt": "…"
}

kit.version 有三种不同的含义，不可混为一谈。数字表示 kit 的修订版本。0 表示 kit 存在，但尚未生成任何版本。 null 表示导出内容根本没有报告版本，这是另一种情况；若将其读作 0，就会在你的仓库中写入一个从未成立过的基线。身份信息直接复制自导出内容自身的 front matter；这里不会推断任何信息。

再次应用时会读取这些记录：

• 版本发生变化 — 服务端自身的计数表明 kit 已更改。请重新读取 brief。
• 版本相同，但渲染后的文件不同 — 变化来自 DESIGN.md 序列化器，而非 kit。无需操作。
• 两边都没有版本 — 只有摘要可用，而它无法区分这两种情况，因此会如实说明，而不会猜测。

由于 id 是持久标识，因此重命名 kit 的 slug 不会被报告为“你应用了另一个 kit”。如果 stamp 是由比当前版本更新的 CLI 写入的，系统会拒绝读取，而不是只读懂一部分：每个文件都会被视为未记录，因此 apply 会停止，而不会根据无法完整读取的记录覆盖内容。

status：询问 stamp 发生了什么变化

identityforge status              # the current directory
identityforge status --dir apps/web

它不需要 kit 或版本，因为 stamp 已经保存了这两者。themes diff --from N 需要你知道 kit，并自行从 JSON 中读取数字；apply --preview 需要 slug，并会获取完整的写入计划来回答一个只读问题。status 会读取 identityforge.json，按 id 向服务端查询，并分别报告 stamp 所表明的三种变化：

• kitMoved — 服务端自身的版本计数不同。设计已更改。
• documentMoved — 渲染后的 DESIGN.md 字节不同。单是序列化器发生变化，就会同时影响所有 kit；因此，仅凭这一点不足以构成修改代码的理由。
• contractMoved — designMdContract 不同。文档的结构发生了变化：某个章节被添加、重命名或移除。这是第三个独立的问题，前两项都无法回答它。

如果某一侧无法给出答案，对应项会是 null 而非 false，并附注说明缺少哪一侧的信息。如果 kit 确实发生了变化，且两边的版本都是数字，则会附上与 themes diff 输出相同的差异内容。它还会将 stamp 记录的每个产物与磁盘上的内容进行哈希比对，因此，如果你后来手动编辑过 DESIGN.md，在再次应用并覆盖它之前，它会显示为 modified。

它不会写入任何内容，也绝不会触碰工作树。如果密钥丢失或遇到 Pro 限制，它会降级为仅基于本地信息生成报告并附注，而不是直接失败。JSON 会输出到 stdout，人类可读摘要则输出到 stderr，因此运行 identityforge status | jq .moved 时，人仍然能看到摘要句子。

互补集合

这些集合回答的是 kit 无法回答的问题，但不能取代 kit。

• list_image_directions / get_image_direction：选择并导出项目图像的呈现与复用方式。
• list_interface_styles / get_interface_style：选择并导出用于界面表面与层级的中性渲染语法，并通过 kit 应用。
• list_page_recipes / get_page_recipe：选择并导出页面陈述主张的方式。

当用户提供真实的产品、人物或物体时，应将获批图像作为固定输入，交给保留参考图的图像编辑器。围绕它设计项目专属的呈现方案，包括场景、辅助元素、构图、光线、表面、裁剪、成片效果和变化规则。保持源图的身份信息完全一致，以完整分辨率将每个结果与源图逐一对比；避免通过文字重新创建现有产品，也不要将抠图叠放在单独生成的背景上。如果当前 Agent 无法执行基于参考图的编辑，请将源图和导出的方向交给产品图像工作流。此流程中，Identity Forge 提供 brief；它不负责渲染图像。

作者工具包和品牌（kits:write）

• create_theme：从头创作私有工具包，或基于目录中的工具包分叉创建，并通过覆盖项设置设计令牌、颜色、字体和维度预设。
• remix_theme：将可解析的工具包复制到新的私有工具包，并应用覆盖项。
• update_theme：原地编辑你保存的工具包，保留其 slug 和发布状态，让现有使用者沿用更新后的内容。此操作会覆盖存储的工具包，但每次保存都会生成一个版本，因此可通过下方的版本工具读取被替换的状态。此处无法重命名 slug；expectedUpdatedAt 可让并发编辑以 409 错误告终，而不是静默覆盖。
• delete_theme：永久删除你保存的工具包。传入 confirm: true；如果品牌项目仍在引用该工具包，则会拒绝删除并返回 409 kit_in_use，因此请先弃用或重新指向这些引用。
• create_brand_project 和 list_brand_projects：品牌变体和客户端共享的容器。
• add_brand_variation：向项目添加一个方案，包括一个工具包，以及可选的名称、域名、标签和备注。
• update_brand_variation：原地修改一个方案，包括将其重新指向其他工具包。客户端下次查看时即可看到更新。
• remove_brand_variation：永久删除一个方案及其评论。传入 confirm: true；此操作无法撤销。
• revoke_brand_share：永久撤销客户端链接。传入 confirm: true；再次共享时会生成新令牌。
• reorder_brand_variations：设置客户端查看各个方向的顺序。必须恰好列出每个变体一次。
• share_brand_project：创建或轮换只读的 /p/<token> 客户端共享链接，可选择使用密码保护。
• list_client_comments（kits:read）：读取客户端在各个变体上留下的内容。这是共享流程的回传环节。

将其他维度组合到品牌中

品牌由设计工具包、图像方向、界面风格以及任意数量的页面配方组成。这些引用保存在项目中，而非工具包中，因此更换工具包不会影响它们。

• get_brand_layers（kits:read）：查看品牌由哪些内容组成；每个引用都会显示两个修订号，只有记录自固定以来发生变化时才会显示 drift。meta.drifted 统计发生漂移的记录数，links.preview 是渲染后的组合图像。读取不会对品牌做任何更改：不会生成版本，也不会移动固定点。
• add_brand_layer：将一条记录组合到品牌中，并记录其当前修订号，以便后续读取能报告变更，而不是静默应用变更。通过 axis 参数，一个工具即可用于全部三个维度。图像方向和界面风格各只能有一个；除非传入 replace: true，否则添加第二个会返回 409。此参数也可用于接受发生漂移的修订。
• remove_brand_layer：移除一条记录。传入 confirm: true；此操作指定的是记录而非维度，因此过时的视图不会清除它从未见过的图层，重复调用则不执行任何操作。
• export_brand（kits:read）：将品牌导出为一份可直接用于构建的文档——其中包含工具包的 DESIGN.md，以及写入其中的所有固定图层，并遵循决定内容冲突时优先级的规则（工具包负责身份，图层负责应用）。请使用此工具，不要自行合并工具包和各个图层。如果密钥无法打开某个图层，导出内容会标明其所在页面和升级路径，而不会将其丢弃；如果品牌没有选定工具包，则返回 409，而不是返回一个无人选择的占位内容。

描述一次产品，然后获取以其为依据的提案

• get_project_context / set_project_context：在品牌项目中存储产品信息——产品的用途、目标用户、限制条件、已排除的方案、界面和技术栈。之后的每个提案都会以这些信息为依据，包括在从未见过产品描述的会话中。
• recommend_kits({projectId})：为该产品推荐候选方案，每个方案都附带自身的依据，以及对产品实际拥有的界面的适配度评估。使用 Pro 和 kits:write 密钥，还能获得模型排名及每个候选方案的理由；meta.depth 的值为 ranked 或 candidates。

有两点可能会让人意外：

• **set_project_context 会替换内容。**该端点使用 PUT，而非 PATCH，因此你省略的字段会被删除，而不是保留。这是有意为之——合并更新可能会让你从列表中移除一个界面，却静默保留旧界面——但这意味着你需要先用 get_project_context 读取，然后应用修改并发送完整对象。
• recommend_kits 消耗 3 个配额单位且需要密钥；而 list_themes 只消耗 1 个配额单位，其他所有发现路由都支持匿名使用。原因在该路由自身的文档字符串中：它接收自由文本请求体，而非查询参数；同时，它也是唯一可能扩展为计量计费模型调用的路由。写入上下文需要 kits:write；读取则只需要 kits:read。

自构建以来是否有变化？（只读）

• list_kit_versions、get_kit_version、diff_kit_versions：查看一个工具包的版本时间线、某个过去版本的完整快照，以及两个版本之间的变更。对于没有上限的 diff_kit_versions({slug, from})，会与当前版本比较；对于包含 identityforge.json 的仓库来说，这正是它要问的问题。

• list_brand_project_versions、get_brand_project_version、diff_brand_project_versions：针对品牌项目的同三项功能，按所有者限定。

• list_kit_history、get_kit_history_event：查看同一工具包的事件账本，其记录范围比版本时间线更广。kit_history_events 包含三种事件类型——创建、保存和应用到品牌——但只有前两种会生成版本，因此应用操作只会出现在账本中，不会出现在其他地方。想知道某个工具包是否实际用过，查账本；想知道它的令牌是什么，查时间线。它使用不透明游标分页，而不是版本号，因为事件没有可供向前翻页的序号。 分享：暂停或撤回。 update-share 可撤销，几乎总是正确的选择——--disable 会暂停链接，不会更改令牌；恢复分享后，客户端已有的 URL 会立即重新生效。revoke-share 则是永久操作：无论 /p/<token> URL 被粘贴到哪里，包括已发送的邮件中，它都会停止解析；重新分享时会生成新令牌，而且不会再使用旧令牌。未指定 --yes 时，此操作会被拒绝。

• whoami：套餐、已授予和缺失的权限范围、剩余配额、AI 点数和已保存工具包名额。免费使用，且即使超出配额也不会被拒绝，因此即便返回 429 后仍能正常响应。

这些操作都不会写入任何内容。恢复旧状态需要你主动调用 update_theme。

实际具有历史记录的内容。 已保存的工具包和受管理的目录工具包会累积版本。静态目录回退项在提升到受管理目录之前，版本始终为 0。单独的工具包历史账本仅限所有者查看，并记录创建、保存和应用到品牌的操作。对于品牌项目，会记录整个品牌：名称和域名、字体、固定图层、项目上下文和变体，包括重新排序。刻意不记录的是分享，因为谁可以查看品牌并不属于品牌本身。

Pro 权限门槛对它们的影响。 对于你无权访问的工具包，时间线仍会列出版本，但作者的自由文本备注为 null；diff 则会返回每项变更，并标记 redacted: true，包含其路径和 CSS 变量，但不显示变更前后的内容，另附 redactedChanges 计数。get_kit_version 会返回完整负载，因此会改为返回 403。

为品牌命名（naming:read / naming:write）

• list_naming_recipes：获取完整的命名策略目录。
• list_naming_projects 和 create_naming_project：复用或创建一个持久化看板。
• generate_names：使用 Identity Forge 自有模型生成名称。仅当唯一候选名称被持久化时才会消耗 AI 额度。
• add_name_candidates：使用稳定的调用方 UUID，持久化来自当前 Agent、经授权的离线流程或人工调研的名称。不消耗额度。
• list_name_candidates：读取包含来源和证据的看板。
• list_name_generations：审计模型、提示词、请求和额度来源。
• move_name_candidates 和 rank_name_candidates：以原子方式审核、加入候选名单、排序和选择。
• get_naming_research_context：读取简介、看板、证据、能力和小任务交接约定，不进行服务端排序。
• search_name_evidence：通过可自托管的 SearXNG 执行有范围限制、由模型编写的搜索，并返回证据，不提供结论。每次查询消耗账户范围内的 1 个月度额度单位。
• check_domains：提供 DNS，以及来自不同 RDAP、注册商和可选的自托管 SERP 的证据。基础调研每个唯一域名消耗 1 个额度单位；SERP 额外消耗 1 个。DNS 记录不存在仅表示域名可能可用。
• assess_domain_acquisition：说明目标是新注册、购买二级市场域名，还是两者皆可。它会分别报告注册商注册证据和范围有限的公开落地页证据，包括明确的出售、交易平台、保留页面和可见价格信号。它不会验证卖家，也不保证能够购买。二级市场证据每个唯一域名额外消耗 1 个额度单位；十分钟内完全相同且成功的重复查询不消耗额度。

商标筛查仍需作为独立的人工步骤，通过各相关司法管辖区的官方注册簿进行。记录查询内容、类别、来源 URL、结果原文和日期。这只是初步调研，并非法律审查。

打造品牌并与客户端共享

kits:write 工具可让 Agent 端到端地构建完整品牌套件：

1. 使用 create_theme 或 remix_theme 组合四到五种风格迥异的设计方向：可以基于目录中的套件创建分支并覆盖颜色、字体和维度，也可以从头编写。
2. 使用 create_brand_project，为每份客户端简介创建一个项目。
3. 使用 add_brand_variation 附加每种设计方向，并填写品牌名称、域名和标签。
4. 使用 share_brand_project 向客户端提供 /p/<token> 链接，可选择密码保护；客户端可在其中切换不同方案并发表评论。
5. 使用 list_client_comments 查看收到的反馈，然后使用 update_theme、update_brand_variation、remove_brand_variation 和 reorder_brand_variations 修改同一个看板，而不是另建一个。

Agent 创建的所有内容，也都可以由它修改。写入工具会更改实时的、客户端可见的状态；破坏性工具要求设置 confirm: true，因此请先阅读反馈再采取行动。

新密钥默认包含 kits:write。在该权限范围推出前创建的密钥会返回 403，直到你重新运行 identityforge login 或创建包含该权限范围的新密钥。

MCP 服务还会在连接时提供说明，介绍此工作流，因此连接后的 Agent 无需他人逐步指导，就能从需求出发应用套件。

Agent 如何选择套件

当你询问 Agent 想要什么观感时，它应该：

1. 收集意图：产品是什么、面向谁，以及你想要什么氛围，例如“面向中小企业的金融科技仪表盘，平静且值得信赖”。
2. 查找候选项：当构建目标对应某个用途类别时，使用 list_themes({ use })；使用 list_themes({ q }) 进行排序搜索；或者使用 search_themes，根据简短的需求对整个目录进行排序。如果你已有品牌颜色，match_palette({ colors }) 可以找到最接近的套件。
3. 审阅：每个结果都是一份简要摘要，包含名称、标签、字体和颜色概览、等级以及评估的适用度。similar_themes(slug) 可提供相似项，而 get_design_md(slug) 可在确定前读取完整说明。
4. 应用：使用 apply_theme(slug)，还可以选择与技术栈匹配的 tokensFormat，将 DESIGN.md、令牌文件和 identityforge.json 标记写入项目。如果项目中已有并非由它写入的文件，它会显示冲突，而不是覆盖这些文件。
5. 实现：遵循 DESIGN.md，并将令牌接入样式层，无论你使用的是 CSS 变量、Tailwind @theme 块还是 shadcn。

描述越具体，匹配效果越好。

ID 和 slug

每个套件都有一个不透明的 id 和一个 slug，两者都可以直接定位套件，因此找到套件后，你可以跳过发现步骤。它们的持久性有所不同：

• id 永不更改。它只生成一次，永不重新分配，并且始终指向同一个套件。
• slug 是所有者可以重命名的公开标识。已停用的 slug 会通过别名继续解析，因此仅重命名不会导致你无法使用。但之后其他套件可以认领这个已释放的 slug；此时生效的套件优先，因此已保存的 slug 可能会悄悄开始指向另一个套件，而不是明确报错。

当用户输入 slug 时，传入 slug。对于 Agent 保存的任何内容，例如配置值、版本标记或后续会话中重复使用的选择，都应存储 id。list_themes 会同时输出两者。

图像方向、界面风格和页面配方也带有 id，而且更应遵循同样的建议：它们没有别名表，因此重命名后，原 slug 就无法再解析。

CLI 命令

npx -y identityforge@latest login    # browser sign-in (PKCE loopback)
identityforge login --key ifk_…      # or paste a key (headless)
identityforge whoami                 # plan, scopes, quota, credits, saved-kit slots (free)
identityforge usage                  # alias for whoami
identityforge update-check           # current/latest package version as JSON
identityforge doctor --client codex  # verify config and MCP capabilities without API usage
identityforge logout                 # remove stored credentials
identityforge themes                 # list kits
identityforge themes -q "fintech dashboard, calm and trustworthy"
identityforge themes get <id|slug>   # print DESIGN.md to stdout, writing nothing
identityforge themes get <id|slug> --format tailwind-v4 > tokens.css
identityforge themes get <id|slug> --format json      # the whole kit
identityforge themes get <id|slug> --marker           # stale-write marker only

# Author, fork, and find neighbours (kits:write for the first two)
identityforge themes create --name "Acme" --base bento-noir --overrides o.json
identityforge themes remix <id|slug> --overrides o.json   # copies; original untouched
identityforge themes delete <id|slug> --yes                # permanent; refuses kits still in use
identityforge themes similar <id|slug>                    # nearby published kits
identityforge themes match "#1d4ed8" "#f97316"            # kits closest to colors you hold

# Typography, for the cases a kit does not already settle
identityforge fonts search grotesk --category sans-serif   # Google Fonts metadata, no files
identityforge fonts similar Inter                          # faces that resemble one you have
identityforge fonts pairings Fraunces --role heading       # curated table + contrast suggestions

# Has this kit moved since I built against it? (read-only)
identityforge themes versions <id|slug>               # version timeline, newest first
identityforge themes version <id|slug> 3              # one past snapshot, whole kit
identityforge themes diff <id|slug> --from 3          # what changed since version 3

# Everything that happened to it, which is a wider record (read-only)
identityforge themes history <id|slug>                # + every apply-to-brand
identityforge themes history <id|slug> --cursor "$NEXT"
identityforge themes snapshot <id|slug> <event-id>    # the kit at that entry

# Build a client brand project and read the feedback back (kits:write)
identityforge brand create --name "Acme rebrand" --brief "Calm fintech"
identityforge brand add-variation --project <uuid> --kit <id|slug> --brand-name Acme --label "Direction A"
identityforge brand share --project <uuid> --password hunter2
identityforge brand update-share --project <uuid> --disable   # pause; token survives
identityforge brand revoke-share --project <uuid> --yes       # permanent, new token next time
identityforge brand get --project <uuid>              # one project in full
identityforge brand layers --project <uuid>           # pinned catalogue records
identityforge brand add-layer --project <uuid> --axis imageDirection --record <id>
identityforge brand remove-layer --project <uuid> --axis imageDirection --record <id> --yes
# The kit's DESIGN.md with every pinned layer composed into it: the one document to build from
identityforge brand export --project <uuid> > DESIGN.md
identityforge brand comments --project <uuid>
identityforge brand projects
# Describe the product once, then ask for grounded proposals
identityforge brand context --project <uuid>          # read the stored context
identityforge brand set-context --project <uuid> --file context.json   # REPLACES it
identityforge brand recommend --project <uuid>        # candidates (3 units, needs a key)
# Queue mockups: one AI credit per variation and scene combination
identityforge brand mockups generate --project <uuid> --variation <uuid> --item tshirt:front
identityforge brand mockups list --project <uuid>
identityforge brand mockups get --project <uuid> --job <uuid>

identityforge brand versions --project <uuid>         # project history
identityforge brand version 3 --project <uuid>        # one stored version, in full
identityforge brand diff --project <uuid> --from 2

# Act on the feedback: revise, retire, reorder (kits:write)
identityforge brand update-variation --project <uuid> --variation <uuid> --label "Warmer" --clear notes
identityforge brand remove-variation --project <uuid> --variation <uuid> --yes
identityforge brand reorder --project <uuid> <variation-uuid> <variation-uuid> <variation-uuid>
identityforge themes update <id|slug> --name "Acme v2" --expected-updated-at "$MARKER"
identityforge image-directions list  # list public imagery judgments
identityforge image-directions get <slug> --format markdown
identityforge interface-styles list  # list public render-grammar judgments
identityforge interface-styles get <slug> --format markdown
identityforge page-recipes list      # list public page communication judgments
identityforge page-recipes get <slug> --format markdown
identityforge apply <slug>           # write DESIGN.md + tokens + stamp into the current dir
identityforge apply <slug> --preview # plan it first, writing nothing
identityforge status                 # read the stamp: has the kit, the document, or its shape moved?
identityforge status --dir apps/web
identityforge mcp                    # run the MCP server over stdio

# Naming commands always print JSON
identityforge naming recipes
identityforge naming projects
identityforge naming create-project --name "My product" --description "Product, audience, market, desired character"
identityforge naming generate --project <uuid> --description "..." --recipes compoundWords,metaphor --count 12 --idempotency-key my-product-run-1
# Persist candidates proposed by the active agent or an authorized offline process (1-50 items)
identityforge naming add-candidates --project <uuid> --file candidates.json
# The same command accepts a JSON array or {"candidates":[...]} on stdin
identityforge naming add-candidates --project <uuid> --file - < candidates.json
identityforge naming candidates --project <uuid> --status shortlisted,finalist
identityforge naming generations --project <uuid>
identityforge naming research-context --project <uuid>
identityforge naming search --file research-tasks.json
identityforge naming acquisition candidate.com --intent either
identityforge naming move <candidate-uuid> --project <uuid> --status finalist --notes "Strong market fit"
identityforge naming rank <candidate-uuid>=1 <candidate-uuid>=2 --project <uuid>
identityforge naming domains candidate.de candidate.com --serp --market "Germany heating retail" --language de-DE
# Registrar evidence alongside DNS and RDAP, the closest this gets to an availability answer
identityforge naming domains candidate.de --registrar
# Record WHY a candidate moved, not only that it did
identityforge naming move <candidate-uuid> --project <uuid> --status rejected --evidence why.json

保护命名写入。 naming move 和 naming rank 支持 --expected-updated-at，因此如果候选项在你读取后发生了变化，命令会返回 409，而不是 悄悄覆盖。请从 naming candidates 获取标记，逐字节原样传回， 不要解析它：它看起来像时间戳，但会作为不透明字符串进行比较。

identityforge naming candidates --project <uuid> --status finalist   # read updatedAt from the row
identityforge naming move <candidate-uuid> --project <uuid> --status selected \
  --expected-updated-at "<marker>"

该标记只保护一个候选项，因此如果与多个 ID 一起传入，命令会在发送任何内容前拒绝执行，而不是应用到所有候选项：每一行都有自己的标记，将一个标记用于整个批次会保护错误的行。请单独移动受保护的候选项。这对 --status selected 尤其重要，因为它还会设置项目选定的品牌名称。

--evidence 则不同：它不针对某一行，因此会应用到批次中的每个候选项。 它接受路径或表示标准输入的 -；如果文件无法解析，命令会拒绝执行，而不会将其作为空对象发送， 因为这会把“无证据”记录成经过考虑后的答案。

编辑已保存的套件，同时避免覆盖并发编辑

PATCH 接受 expectedUpdatedAt 标记；如果套件在你读取后发生了变化，它会返回 409，而不会覆盖套件。使用 themes get --marker 读取当前标记：

MARKER=$(identityforge themes get my-kit --marker)
identityforge themes get my-kit --format json > kit.json
# ... edit kit.json, then guard the write with the marker you read
identityforge themes update my-kit --kit kit.json --expected-updated-at "$MARKER"

--kit 会与已存储的套件进行深度合并，因此文件中只需包含变更内容。请保持 slug 不变：它是套件的公开标识，若载荷中包含不同的 slug，请求会被拒绝并返回 400 slug_rename_unsupported，而不是被悄然忽略。省略 --expected-updated-at 仍然可用，也仍会写入；但它会覆盖已存储的内容，包括他人在你读取后所做的编辑，因此命令会在 stderr 中说明这一点。

标记是不透明的。请逐字节原样回传，绝不要解析它。 它在线路上传输的是原始 Postgres 时间戳，而不是 ISO-8601；并且校验会比较字符串，因此客户端若将其解析为 Date 再序列化，永远无法匹配，始终会收到 409。解析还会丢失微秒，因此对两侧进行规范化的比较可能会误判为匹配，让真正过期的写入通过。精选目录中的套件没有标记，因为它没有对应的数据行，也无法编辑。

身份验证

命令使用 Identity Forge API 密钥（ifk_…）进行身份验证。login 会以模式 600 将密钥存储在 ~/.identityforge/config.json 中。你也可以按 shell 设置：

export IDENTITYFORGE_API_KEY=ifk_…
export IDENTITYFORGE_API_URL=https://identityforge.io   # override the API base
export IDENTITYFORGE_TELEMETRY=0                        # optional: disable apply-completion counting

免费套件和命名配方发现功能无需密钥即可使用。登录后，即可在经过身份验证的配额内保留持久化项目和已保存的工作。自有命名项目和域名研究使用 naming:read；生成和画板编辑使用 naming:write；读取设计系统使用 kits:read；创建或混编套件以及构建可分享的品牌项目使用 kits:write。API 调用会计入所有密钥共享的单一账户级月度 API 配额；此外，成功持久化的唯一候选项会单独消耗 AI 积分。请在 https://identityforge.io/account/api-keys 管理密钥。

本地应用成功后，客户端会发送一次仅包含元数据的完成请求，以便统计汇总构建次数。请求包含套件标识，以及每个 API 请求中已有的客户端名称和版本。它绝不会发送仓库路径或文件内容，也不会改变应用结果；可以通过 IDENTITYFORGE_TELEMETRY=0 禁用。

现有的仅限设计功能的密钥不会被悄然升级。如果密钥提示缺少 naming:read 或 naming:write，请创建一个具有相应范围的密钥，或重新通过浏览器登录。

Docker

MCP 服务也可以作为通过 stdio 通信的容器运行：

docker build -t identityforge-mcp .
docker run -i --rm -e IDENTITYFORGE_API_KEY=ifk_… identityforge-mcp

镜像不包含任何套件载荷。密钥是可选的：没有密钥时，服务仍会启动，并通过 Identity Forge 平台 API 获取已发布的免费套件。Pro 套件、已保存的工作和写入操作需要账户密钥。

链接

• 源代码和 Agent 插件：公开的 CLI 和 MCP 实现。
• 套件图库：浏览所有套件，查看实时预览，按创作意图筛选使用场景并进行搜索。
• 面向 Agent：完整的 Agent 集成说明。
• API 清单 和 llms.txt。
• 官方 MCP Registry 记录 和 Glama 上附带独立构建与安全分析的条目。

如果 Identity Forge 能在你的工作流中占有一席之地，点个 GitHub 星标可以帮助其他开发者发现它。

许可证

MIT