如何集成和使用 impeccable

其实也没啥，就是在 HagiCode 项目里集成个设计工具，勉强算是个完整方案吧——包括仓库结构、多语言工作流、内容维护这些，都是在实践里慢慢摸索出来的。

背景

说起软件开发里的 UI/UX 设计质量，其实还挺重要的，毕竟能直接决定产品的用户体验和商业成功。只是传统开发流程里，设计师和开发者之间总有一道无形的墙：设计师画了精美的静态稿，开发者努力去实现，却总是在某些细节上有些偏差。这种割裂让最终产品很难完全匹配设计愿景，迭代成本也跟着水涨船高。

HagiCode 项目在做桌面应用和 Web 产品的时候，也需要专业的 UI/UX 设计支持，同时还要求设计和代码实现能够紧密协作。为此，我们引入了 impeccable 工具——一个专业的 AI 驱动的前端界面设计和优化工具。impeccable 不仅提供设计指导，还能直接处理代码实现，算是把设计和开发之间的鸿沟给填上了一些。

为了让 impeccable 在 HagiCode monorepo 中有效集成和使用，我们需要建立标准化的集成方式、文档流程和维护规范。这包括工具的安装配置、技能集成、文档站点建设，以及团队协作的最佳实践。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，提供了 Web 端和桌面端两种形态，帮助开发者提升编码效率。在开发过程中，我们需要高质量的设计工具来支持产品的 UI/UX 建设，impeccable 正是在这样的背景下被引入到项目中的。

技术架构分析

impeccable 的技能驱动设计

impeccable 采用了技能驱动的设计架构，通过标准化的技能文件定义不同设计任务的上下文和行为。在 HagiCode 项目中，impeccable 以 npm 技能包形式集成，主要通过以下方式使用：

技能文件结构：/home/newbe36524/.agents/skills/impeccable/SKILL.md 定义了完整的技能配置，包括命令集合、工具权限、参数提示和许可信息。
命令分类体系：impeccable 将设计任务分为六大类别：
- Build：构建型命令（craft、shape、teach、document、extract）
- Evaluate：评估型命令（critique、audit）
- Refine：优化型命令（polish、bolder、quieter、distill、harden、onboard）
- Enhance：增强型命令（animate、colorize、typeset、layout、delight、overdrive）
- Fix：修复型命令（clarify、adapt、optimize）
- Iterate：迭代型命令（live）

文档站点需求分析

为了支持团队使用 impeccable，HagiCode 建立了独立的文档站点 impeccable-site，该站点需要满足以下需求：

多语言支持：提供英文和中文的完整文档，满足国际化团队需求
命令目录：归一化展示所有命令，包括分类、描述和参考链接
本地化内容：维护 HagiCode 特定的使用指南和最佳实践
静态生成：使用 Astro 构建静态站点，便于部署和访问

集成面临的挑战

在集成过程中面临以下挑战：

源码同步：上游 impeccable 仓库包含完整的工具代码和文档，但需要选择性地集成文档部分，避免依赖整个工具代码库
内容维护：需要在保持上游更新同步的同时，维护本地化的内容和使用指南
构建流程：建立自动化的内容同步、目录生成和站点构建流程
多语言工作流：设计高效的翻译和本地化维护流程

解决方案设计

仓库结构设计

通过 Git submodule 机制集成上游 impeccable 仓库：

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

这种设计的优势包括：

版本控制：可以精确控制上游版本，避免意外更新导致的问题
轻量级集成：只拉取需要的源码，避免引入不必要的依赖
更新灵活：可以选择性地更新上游内容

内容模型设计

采用分层的内容模型：

上游源码：vendor/impeccable/ - 提供原始命令定义和参考文档
本地化内容：src/content/commands/ - 维护中英文命令说明
共享 UI 文案：src/i18n/locales/ - 管理站点界面的多语言文本
生成式目录：src/lib/generated/command-catalog.json - 构建时生成的命令目录

构建流程优化

设计自动化的构建流程，通过 npm 脚本集成各个步骤：

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

构建流程分为四个阶段：

准备阶段：生成多语言资源和命令目录
内容同步：从上游同步命令内容到本地
验证阶段：检查内容完整性和构建正确性
构建输出：生成静态站点文件

多语言工作流

基于 hagi18n 工具链建立标准化的多语言工作流：

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

提供完整的维护脚本：

i18n:audit - 检查翻译完整性
i18n:sync - 同步翻译条目
i18n:prune - 清理过期翻译
i18n:doctor - 诊断翻译问题

实践指南

初始化设置

首先初始化 submodule 并安装依赖：

# 进入 monorepo 根目录
cd /home/newbe36524/repos/hagicode-mono

# 初始化 submodule
git submodule update --init --recursive

# 进入 impeccable-site 目录
cd repos/impeccable-site

# 安装依赖
env -u NPM_CONFIG_PREFIX npm install

这一步是整个集成流程的基础，submodule 初始化失败会导致后续所有步骤无法进行。HagiCode 在首次集成时就遇到了这个问题，后来在文档中明确了初始化步骤。

日常开发流程

在 repos/impeccable-site 目录下执行日常开发命令：

# 启动开发服务器
env -u NPM_CONFIG_PREFIX npm run dev

# 类型检查
env -u NPM_CONFIG_PREFIX npm run typecheck

# 运行测试
env -u NPM_CONFIG_PREFIX npm test

# 构建站点
env -u NPM_CONFIG_PREFIX npm run build

# 完整验证
env -u NPM_CONFIG_PREFIX npm run validate

开发服务器默认运行在 http://localhost:31266，可以通过环境变量 PORT_IMPECCABLE_SITE 自定义端口。HagiCode 的团队成员在开发过程中发现，频繁在不同语言环境切换时，使用统一的前缀命令可以避免环境变量污染问题。

内容维护策略

添加或更新命令文档时，需要在两个语言目录中创建对应的文件：

# 英文命令文档
src/content/commands/en-US/polish.mdx

# 中文命令文档
src/content/commands/zh-CN/polish.mdx

每个 MDX 文件需要包含 frontmatter 元数据：

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

上游内容同步

当上游 impeccable 更新时，需要同步最新的命令内容：

# 更新 submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# 同步命令内容
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# 同步单个命令
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# 重新生成目录
env -u NPM_CONFIG_PREFIX npm run catalog:generate

同步脚本会从 vendor/impeccable/site/content/skills/ 读取上游命令内容，并将其复制到 src/content/commands/en-US/ 目录中。HagiCode 团队在实践中发现，每次同步后都需要重新生成命令目录，否则会出现内容不一致的问题。

多语言维护

维护站点界面的多语言文本：

# 检查翻译完整性
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# 同步翻译条目
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# 清理过期翻译
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# 诊断翻译问题
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

翻译文件位于 src/i18n/locales/ 目录：

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

YAML 文件示例：

# src/i18n/locales/en-US/docs.yml
commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概览"
  related: "相关命令"

使用 impeccable 命令

在 HagiCode 项目中，可以通过以下方式调用 impeccable 命令：

# 设计新功能
npx impeccable craft "user settings page"

# 规划 UI/UX
npx impeccable shape "checkout flow"

# 设置项目上下文
npx impeccable teach

# 生成设计文档
npx impeccable document

# 审查设计质量
npx impeccable critique "landing page"

# 技术质量检查
npx impeccable audit "navigation component"

# 最终优化
npx impeccable polish "onboarding flow"

# 实时迭代设计
npx impeccable live

每个命令都有特定的用途和参考文档。例如，craft 命令用于端到端构建功能，包括 UX/UI 规划和代码实现；audit 命令用于技术质量检查，包括可访问性、性能和响应式设计。HagiCode 团队在开发过程中，这些命令已经成为日常开发流程的一部分。

部署验证

部署前进行完整的验证：

# 运行完整验证流程
env -u NPM_CONFIG_PREFIX npm run validate

验证流程会检查：

vendor 路径是否正确
所有命令在中英文目录中都有对应内容
生成的多语言资源是最新的
命令目录是最新的
Astro 路由编译正确
静态输出构建成功

注意事项与最佳实践

重要注意事项

Submodule 更新：更新 submodule 后需要重新生成派生资源并提交。HagiCode 团队曾经遇到过一次忘记重新生成资源就直接提交的情况，导致线上站点出现了内容不一致的问题。
语言对等性：确保所有命令在中英文目录中都有对应内容，否则构建会失败。这个检查已经集成到了验证流程中，可以在开发早期发现问题。
前端代理：impeccable-site 通过 monorepo 根目录的静态站点开发脚本进行代理：

# 从 monorepo 根目录启动
npm run dev:static-sites

生产部署：生产站点部署到 https://impeccable.hagicode.com，通过 GitHub Actions 自动化部署。HagiCode 采用了完全自动化的 CI/CD 流程，确保每次提交都能自动部署。
命令文档链接：在 Web 前端的 UI Master 中选择 impeccable 命令时，会显示对应的文档链接，链接格式为：

https://impeccable.hagicode.com/{lang}/commands/{command-name}

最佳实践总结

定期同步上游：关注上游 impeccable 的更新，定期同步新的命令和改进。HagiCode 团队采用每周一次的同步频率，确保不会错过重要的更新。
维护本地化内容：在同步上游内容后，及时更新中英文文档，确保内容的准确性和时效性。
版本控制：submodule 更新后需要验证构建结果，再提交到版本控制系统。
团队协作：通过标准化的多语言工作流，支持团队成员协作维护文档内容。
质量保证：在每次内容更新后运行完整的验证流程，确保站点的正确性。
命令分类使用：根据设计任务的不同阶段选择合适的命令类别：
- 设计新功能时使用 craft 或 shape
- 审查现有设计时使用 critique 或 audit
- 优化设计质量时使用 polish、bolder 或 quieter
- 增强视觉效果时使用 animate、colorize 或 delight
- 修复问题时使用 clarify、adapt 或 optimize
- 实时迭代时使用 live
上下文管理：在使用 craft 命令前，确保已通过 teach 命令设置了项目的 PRODUCT.md 和 DESIGN.md 上下文文件。

总结

通过以上集成和使用方式，HagiCode 项目能够有效利用 impeccable 工具的专业设计能力，提升产品的 UI/UX 质量，同时建立了标准化的文档维护流程，支持团队的长期协作和发展。

本文分享的这套方案，是 HagiCode 在实际开发中经过多次迭代优化出来的。它不仅解决了设计和开发协作的问题，还建立了一套可扩展的文档体系，为其他工具的集成提供了参考。

如果你也在团队中面临类似的设计-开发协作问题，希望本文的实践对你有所启发。这套方案的核心思想是：建立标准化的流程、保持与上游的同步、注重本地化维护、支持团队协作。

总结

围绕“如何集成和使用 impeccable”，更稳妥的推进方式是先把关键配置、依赖边界和落地路径逐步跑通，再补齐优化细节。

当目标、步骤和验收点都明确之后，这类方案通常就能更顺畅地进入实际交付。

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/go?platform=cnblogs&target=%2Fblog%2F2026-06-10-how-to-integrate-and-use-impeccable%2F
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

posted @ 2026-06-10 10:48 Newbe36524 阅读(16) 评论(0) 收藏举报

刷新页面返回顶部

Newbe36524

Now, everyone will be excellent!

如何集成和使用 impeccable

如何集成和使用 impeccable

背景

关于 HagiCode

技术架构分析

impeccable 的技能驱动设计

文档站点需求分析

集成面临的挑战

解决方案设计

仓库结构设计

内容模型设计

构建流程优化

多语言工作流

实践指南

初始化设置

日常开发流程

内容维护策略

上游内容同步

多语言维护

使用 impeccable 命令

部署验证

注意事项与最佳实践

重要注意事项

最佳实践总结

总结

总结

原文与版权说明

公告