designmdme-cli

designmdme CLI

designmdme 可将任何公开网站转换为 DESIGN.md — 一份结构化的 Markdown 规范，描述该网站的设计系统（颜色令牌、字体排版比例、间距、边框圆角、阴影／层级和组件模式）。它还可以选择生成一份自包含的 HTML 预览，将这些令牌渲染成实时视觉示例。

DESIGN.md 专为提供给编码 Agent 而设计：当用户要求你构建或重塑 UI，使其匹配真实品牌时，先生成规范并阅读，然后依据其中的确切令牌值编写代码，而不是猜测颜色和字体。

何时使用此技能

只要任务需要从实际网站中准确获取设计系统，就使用它：

• “以 stripe.com 的风格构建一个落地页” → 生成 stripe.com 的规范，阅读 DESIGN.md，然后使用其中的实际十六进制值和字体栈进行实现。
• “匹配我们营销网站的设计”／“让这个看起来符合品牌风格” → 提取该 URL。
• “linear.app 的调色板／字体是什么？” → 生成规范并阅读相关部分。
• 根据现有参考网站为新项目设置设计令牌。

如果用户只想快速了解视觉效果，不需要代码，HTML 预览（--html）就是可分享的成品。对于所有与代码相关的任务，Markdown 才是事实依据。

安装

该二进制文件名为 designmdme，以 @crowdlinker/designmdme 发布。

# One-off (no install)
npx @crowdlinker/designmdme stripe.com

# Or install globally so the `designmdme` command is always available
npm install -g @crowdlinker/designmdme

身份验证（一次性，交互式）

该 CLI 需要账户验证；生成内容必须使用已登录的令牌。身份验证使用浏览器设备代码流程，并将令牌存储在 ~/.designmdme/auth.json 中（仅包含令牌和到期时间，不包含其他个人身份信息）。令牌默认有效期为 30 天。

designmdme login     # opens a browser, prints a fallback URL + code, then polls
designmdme whoami    # prints the logged-in email + token expiry
designmdme logout    # deletes ~/.designmdme/auth.json

login 是交互式命令（它会打开浏览器，等待用户在最长 10 分钟内批准）。不要无人值守地运行它。如果命令失败并提示“Not logged in”或“Token expired”，请停止并让用户自行运行 designmdme login — 你无法代替他们完成浏览器审批。

生成 DESIGN.md（默认命令）

URL 可以作为位置参数传入，也可以通过 -w／--website 传入；两者等效。http／https 和 www. 会自动规范化。

designmdme stripe.com
designmdme --website https://stripe.com

执行过程：CLI 会检查令牌、验证 URL 是否可访问、扫描网站、流式传输规范并写入文件。默认输出文件名为当前目录中的 DESIGN-<slug>.md，其中 <slug> 是去掉 www. 并将非字母数字字符合并为连字符后的主机名（例如，stripe.com → DESIGN-stripe-com.md）。

选项

标志	含义
-w, --website <url>	网站 URL — 位置参数的别名。
-o, --output <path>	写入指定路径，而不是 DESIGN-<slug>.md。如果父目录不存在，则会创建。
--single-page	仅提取落地页（4 个额度）。请参阅提取模式。
--multi-page	抓取网站的关键页面，以生成更丰富的规范（8 个额度）。
--html	除 Markdown 外，还生成 HTML 预览（+8 个额度 — 请参阅额度费用）。文件写入同一路径，扩展名为 .html 而非 .md。

designmdme stripe.com --output ./docs/stripe-design.md
designmdme stripe.com --single-page           # cheapest, predictable 4 credits
designmdme --website stripe.com --html        # writes DESIGN-stripe-com.md + .html

提取模式

规范可以仅根据落地页生成，也可以通过抓取并合并网站的多个关键页面来生成：

• 单页（--single-page，4 个积分）——仅读取你传入的 URL。
• 多页（--multi-page，8 个积分）——发现并读取关键页面（定价、产品、功能等），以生成更完整的设计系统。

如果你两个标志都不传，CLI 会使用账户已保存的偏好设置（可能是多页模式，即 8 个积分），并在生成前显示最终采用的模式和费用。 如需确保费用可预期，请明确指定模式——只需以低成本获取令牌时使用 --single-page，重视完整性时使用 --multi-page。

CLI 会自动处理以下两种情况：

• 如果账户余额不足 8 个积分，多页模式会回退为单页模式。
• 如果网站最终只有一个路由（没有其他页面可供抓取），即使使用 --multi-page，也会按单页模式（4 个积分）计费，并显示说明。

重要：避免交互式覆盖提示

如果目标文件已存在，CLI 会以交互方式提示“Replace or create a copy? (replace/copy)”并等待输入。在非交互模式下运行时（Agent 通常如此），CLI 会一直卡住。为确保安全：

• 传入明确且唯一的 --output 路径，确保该路径尚不存在，或者
• 先检查并移除默认的 DESIGN-<slug>.md 文件。

如果提示时回答“copy”（默认选项），副本会命名为 DESIGN-<slug>-YYYYMMDD.md（包含日期）。

生成 HTML 设计预览

添加 --html，还可以生成一个独立的 HTML 页面，将提取出的设计系统呈现为实时视觉示例：带十六进制标签的色板、使用网站实际字体的字号比例示例、间距和圆角条、阴影／层级卡片，以及可直接复制的 :root CSS 变量代码块。它是一个独立的 .html 文件，所有 CSS 均内嵌其中，且没有外部依赖——适合与设计师分享、添加到 wiki，或在开发前快速查看品牌效果。

designmdme stripe.com --html     # writes DESIGN-stripe-com.md AND DESIGN-stripe-com.html

行为：

• HTML 文件与 Markdown 文件保存在同一目录——路径相同，扩展名为 .html 而非 .md（使用 --output 控制基础路径）。它同样受覆盖提示影响。
• HTML 根据 Markdown 规范生成，因此总是先生成 Markdown。如果 HTML 步骤失败（例如积分不足），仍会保存 .md 文件。
• 对于代码任务，优先使用 Markdown——它是机器可读的事实来源。只有在用户需要查看或分享视觉产物时才使用 --html。

积分费用

生成内容会消耗账户积分。具体费用如下：

生成内容	积分
DESIGN.md — 单页（--single-page）	4
DESIGN.md — 多页（--multi-page）	8
HTML 预览 — --html 附加项	8
单页 + HTML	总计 12（4 + 8）
多页 + HTML	总计 16（8 + 8）

注意：

• 只有成功时才会扣除积分——生成失败或取消都不会产生费用。
• 缓存结果费用为 0：重新生成已生成过的网站时，会返回缓存的 Markdown（CLI 显示“Served from cache · 0 credits”）。
• HTML 预览同样只计费一次并会缓存——为同一网站再次运行 --html 时会返回缓存文件，不会再次扣费。
• 如果 --html 报告 “Insufficient credits”，说明 Markdown 已成功保存——仅跳过了 HTML 附加项。请勿循环重试；告知用户前往 https://designmd.me/pricing 充值。
• 多页模式需要 8 个积分；如果余额不足，CLI 会静默使用单页模式。费用需要重点关注时，请先检查 designmdme usage。

检查历史记录和用量

designmdme list      # recent generations (CLI + web), with share URLs and local file paths
designmdme usage     # credit balance, credits used vs received, generation counts, recent transactions

list 会为每一行添加 [multi-page] 标签（如适用）和一个状态 （● queued / ● processing / ● failed / ● cancelled；成功的行只显示其 分享链接/文件）。由于生成任务会作为持久化后台任务运行，list 可用于查看仍在处理的任务 或在中断后恢复任务。

批量生成前，请检查 designmdme usage，确认剩余额度充足（每份 Markdown 单页需 4 点 / 多页需 8 点，每个 --html 额外需 8 点）。如果额度用完， 请停止并告知用户前往 https://designmd.me/pricing 充值——不要循环重试。

后台生成

生成任务是持久化的服务端任务。普通的 designmdme <url> 调用仍会一直等待，直到文件写入完成——它会显示实时状态（Queued → Generating），并在完成后返回，因此 Agent 工作流不会改变（负载较高时可能只是耗时稍长）。如果任务被中断（Ctrl+C / 连接断开），它会在服务器上继续运行，而不会取消——之后运行 designmdme list 查看其状态，并在任务完成后获取结果。

推荐的 Agent 工作流

1. 仅在需要时确认身份验证：如果尚未登录，生成调用会迅速失败并显示清晰的提示。不要提前运行 login（该命令需要交互）。
2. 使用明确的模式生成到已知路径，以便准确预估费用： designmdme <url> --single-page --output <unique-path>.md（或者在值得花费 8 点额度获取更完整的跨页面规范时使用 --multi-page）。
3. 阅读生成的 DESIGN.md，并提取准确的值——十六进制颜色代码、字体系列和字号、间距单位、圆角、阴影值、组件样式。在编写的代码中原样使用这些值；不要近似估算。
4. 如果用户还需要视觉参考，请添加 --html 并打开 .html 文件。

故障排除

症状	原因 / 操作
Not logged in / Token expired / Token is no longer valid	请用户运行 designmdme login。身份验证需要交互；你无法代替用户操作。
显示“already exists”后卡住	正在等待交互式覆盖提示——使用唯一的 --output 路径重新运行。
Insufficient credits for HTML preview	--html 的额度不足；Markdown 生成可能仍已成功。请告知用户前往 https://designmd.me/pricing 充值。
意外扣除 8 点额度	未传入模式标志，且账户默认模式为多页。传入 --single-page，确保本次运行费用为 4 点。
URL 无法访问	网站已关闭、屏蔽了机器人，或 URL 有误。请与用户确认 URL。
输出为空	生成未返回内容——重试一次；如果问题仍然存在，请报告此情况。

快速参考

designmdme login                              # one-time browser auth
designmdme whoami                             # who am I + token expiry
designmdme stripe.com --single-page           # → DESIGN-stripe-com.md (4 credits)
designmdme stripe.com --multi-page            # richer, cross-page spec (8 credits)
designmdme stripe.com                         # uses account default mode (prints cost first)
designmdme stripe.com --output ./docs/s.md    # custom path (avoids overwrite prompt)
designmdme stripe.com --single-page --html    # also write .html preview (+8 credits)
designmdme list                               # recent generations (with mode + status)
designmdme usage                              # credits + generation stats
designmdme logout                             # remove stored credentials