hyc sync

hyc sync 是 HyC 最核心的命令之一。它会扫描所有 Markdown/MDX 文章，解析元数据、提取图片引用、生成 AI 文本嵌入向量（用于相似文章推荐）和 AI 摘要（用于文章摘要卡片）。

用法

hyc sync

工作流程

执行 hyc sync 时，HyC 会按以下步骤处理每篇文章：

扫描所有文章文件
  ↓
解析 frontmatter（title, date, categories, draft, tags 等）
  ↓
提取文章中的图片引用 → 存入 asset 表
  ↓
计算文章内容哈希（变更检测）
  ↓
[如果启用了 embedding] 生成 AI 嵌入向量
  ↓
[如果启用了 summary] 调用 AI 生成文章摘要
  ↓
更新数据库记录

变更检测

HyC 使用 rapidhash 计算文章内容的哈希值。只有在文章内容发生变化时才会重新处理，避免重复的 AI 计算开销。

AI 嵌入向量生成

当 hyacine.yml 中 embedding.enabled 为 true 时，HyC 会为每篇文章生成文本嵌入向量：

1. 文本分块：文章正文按句子边界分割为 chunks，每个 chunk 不超过 maxChunkChars 字符
2. 向量化：使用 Hugging Face Transformers 的 feature-extraction pipeline 将每个 chunk 转为向量
3. 均值池化：所有 chunk 向量取平均，再做 L2 归一化，得到最终的文章向量
4. 存储：向量以 float32 二进制格式存入数据库

使用的嵌入模型由 hyacine.yml 中的 embedding.model 配置决定（通常为 Hugging Face 上的 sentence-transformers 系列模型）。

硬件要求

嵌入向量生成需要 GPU 加速。HyC 通过 bun-webgpu 调用本地 GPU。首次运行时会下载模型文件（通常几百 MB）。

AI 摘要生成

当 hyacine.yml 中 summary.enabled 为 true 时，HyC 会为每篇文章生成 AI 摘要：

1. 调用 OpenAI 兼容的 Chat Completions API
2. 系统提示词：专业中文技术编辑，生成 80-180 字精炼概括
3. 摘要结果与模型信息存入数据库

配置项包括：

• apiBaseUrl：API 端点地址
• apiKey：API 密钥
• model：模型名称（如 gpt-4o）
• maxInputChars：最大输入字符数
• maxOutputTokens：最大输出 token 数
• temperature：生成温度（0-2）

跳过处理的条件

• 文章内容未发生变化（哈希值相同）→ 跳过
• embedding.enabled 为 false → 跳过嵌入生成
• summary.enabled 为 false → 跳过摘要生成
• 摘要已有且 sourceHash + model 未变 → 跳过

前置条件

运行 hyc sync 前，需要确保：

1. 项目已通过 hyc init 初始化（存在 hyacine.yml）
2. contentDir 目录下有 Markdown 文章

如果项目未初始化，sync 会报错并提示先运行 hyc init。

输出示例

✅ 同步完成
📝 解析文章: 15 篇
✍️  数据库写入: 3 篇（有变更）
🤖 AI 摘要生成: 3 篇
⚠️  AI 摘要失败: 0 篇
⏭️  跳过: 12 篇（无变更）

常见问题

Q: sync 很慢怎么办？

主要耗时在 AI 功能：

• 嵌入模型下载（首次）：几百 MB的模型文件需要下载
• 向量生成（每篇文章）：取决于文章长度和 GPU 性能
• AI 摘要 API 调用（每篇文章）：取决于网络延迟和 API 响应速度

如果不需要 AI 功能，在 hyacine.yml 中设置 embedding.enabled: false 和 summary.enabled: false 即可大幅加速。

Q: sync 后文章没变化？

检查以下几点：

1. 文章内容是否确实修改了（HyC 通过哈希检测变更）
2. contentDir 路径是否正确
3. 文章文件是否在 postExtension 配置的扩展名范围内

Q: 如何只重新生成特定文章的嵌入/摘要？

目前 HyC 不支持单篇文章的单独处理。修改文章内容后运行 hyc sync，只有变更的文章会重新处理。