{"owner":"metowolf","repo":"vCards","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":2364,"categories":["claude-rule"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\n这是一个中国常用联系人头像库（vCards），为 iOS/macOS 设备提供企业和机构的联系人信息，用于优化来电和信息界面体验。项目生成 vCard 格式的联系人文件，并支持通过 CardDAV 服务分发。\n\n技术栈：Bun（运行时 / 包管理 / 测试）+ TypeScript（严格模式，`tsc --noEmit` 校验）。\n\n## 核心架构\n\n### 文件结构\n- `data/` - 按分类存储的 YAML 数据文件和对应的 PNG 图标\n  - 每个条目包含一个 `.yaml` 配置文件和一个 `.png` 图标文件\n  - YAML 文件包含 `basic` 对象，包含 `organization`、`cellPhone`、`url`、`workEmail` 等字段\n  - 图标优先使用 512x512px（≤50KB），也支持 200x200px（≤20KB）的 PNG 格式\n- `src/` - TypeScript 源码，由 Bun 直接运行，无需编译产物\n  - `src/build.ts` - 构建入口（CLI，`bun run src/build.ts <task>`）\n  - `src/data.test.ts` - 数据校验测试（`bun test`）\n  - `src/core/data.ts` - YAML 扫描与解析\n  - `src/core/git.ts` - 读取 yaml/png 的 git 提交时间（REV）\n  - `src/core/vcard.ts` - vCard 渲染（标准版与 CardDAV 版共用）\n  - `src/const/` - Zod schema（`schema.ts`）与不收录名单（`block.ts`）\n  - `src/utils/` - 拼音、并发池等纯函数\n\n### 构建系统\n- 运行时与包管理器为 Bun，TypeScript 通过 `tsc --noEmit` 做类型检查\n- 两个主要的生成流程（`src/build.ts` 中的 task）：\n  - `build` - 标准 vCard 生成，产出 `temp/` 与 `public/`\n  - `radicale` - CardDAV 版本，附加 UID 与 git 提交时间 REV，产出 `radicale/`\n- 支持生成分类文件夹和汇总文件（`temp/汇总/<分类>.all.vcf`、`temp/汇总/全部.vcf`）\n- 支持生成 Radicale CardDAV 服务所需的文件结构\n- 构建产物与旧版 Node 实现逐字节一致（标准版仅 REV 为构建时间）\n\n### vCard 渲染\n- `src/core/vcard.ts` 的 `renderVCard(yamlPath, options)` 为统一入口\n- 不传 `options.carddav` 时生成标准 vCard；传入 `{ carddav: { revision } }` 时写入\n  稳定的 UID 与基于 git 提交时间的 REV（对应原来的 `vcard-ext` 插件）\n- 使用 `vcards-js` 库生成 vCard 格式，带标签的号码/邮箱通过 `X-ABLabel` 拼接\n- 自动添加拼音字段（`X-PHONETIC-ORG`）用于中文排序，并按 RFC 2426 折行\n\n## 常用命令\n\n### 开发和测试\n```bash\n# 安装依赖\nbun install\n\n# 运行数据格式检查和 schema 验证\nbun test\n\n# TypeScript 类型检查\nbun run typecheck\n\n# 构建标准版本（用于发布）\nbun run build\n\n# 构建 CardDAV 服务版本\nbun run radicale\n```\n\n## 数据验证和规范\n\n### Schema 验证\n- 使用 Zod 进行数据验证，配置在 `src/const/schema.ts`\n- 电话号码使用 Zod 的 `z.e164()` 校验，未带 `+` 的号码自动补 `+86`\n- 支持中国区号格式和国际格式（带 `+` 的保持原区号）\n\n### 测试规范\n- 图标必须是合法的 PNG 格式（优先 512x512px ≤50KB，也支持 200x200px ≤20KB）\n- YAML 数据必须符合定义的 schema\n- 检查阻止列表（`src/const/block.js`）中的机构\n\n### 添加新条目\n1. 在对应的 `data/分类/` 目录下添加 `.yaml` 和 `.png` 文件\n2. 运行 `bun test` 检查格式规范\n3. YAML 文件必须包含：\n   - `basic.organization` - 机构名称\n   - `basic.cellPhone` - 电话号码数组\n   - `basic.url` - 官网链接（可选）\n   - `basic.workEmail` - 邮箱数组（可选）\n   - `basic` 至少包含 `cellPhone`、`workEmail`、`url` 之一\n\n## 特殊处理\n\n### 电话号码收录\n- 数据不收录 106 开头的短信推送长号码（超过11位）\n\n### 中文支持\n- 自动生成拼音字段用于通讯录排序\n- 使用 `pinyin-pro` 库进行拼音转换\n\n### CardDAV 服务\n- 生成 Radicale 兼容的目录结构\n- iOS 版本按分类生成文件夹\n- macOS 版本将所有联系人合并到一个文件夹\n\n## 输出文件\n\n- `temp/` - 临时生成的 vCard 文件，按分类组织\n- `public/archive.zip` - 打包的发布文件\n- `radicale/ios/` - iOS CardDAV 服务文件，按分类分文件夹\n- `radicale/macos/全部/` - macOS CardDAV 服务文件，所有联系人在一个文件夹\n\n## 关键技术细节\n\n### vCard 生成差异\n- **标准版本**（`bun run build`）：`renderVCard()` 不传 `carddav` 选项，适用于一般用户\n- **CardDAV 版本**（`bun run radicale`）：传入 `carddav: { revision }`，添加稳定的 UID 和基于 git 的 REV 字段\n\n### Git 时间戳集成\n- CardDAV 版本通过 `src/core/git.ts` 使用 `git log` 获取文件最后修改时间（并发上限 8）\n- REV 字段使用 YAML 和 PNG 文件中较新的时间戳\n- 确保 CardDAV 客户端能正确检测更新\n\n### 拼音处理\n- 使用 `pinyin-pro` 库生成拼音（`src/utils/pinyin.ts`）\n- 自动为中文机构名添加 `X-PHONETIC-ORG` 字段\n- 支持通讯录中的中文排序功能\n\n## 注意事项\n\n- 不支持 SVG 图标，必须转换为 PNG\n- 图标设计规范：圆形 140x140px，正方形 120x120px，长方形 160x80px\n- 所有文本编码使用 UTF-8\n- 项目使用 Bun + TypeScript，源码由 Bun 直接运行（ES 模块语法）\n- `zip` 命令用于打包 `public/archive.zip`，为 `build` 任务的外部依赖\n- CardDAV 版本使用 `bun run radicale` 确保包含完整的元数据\n\n## 图标标准化处理\n\n项目优先使用 512x512px 的 PNG 格式，文件大小不超过 50KB。也支持 200x200px（≤20KB）作为备选。Issue 中提供的图标通常尺寸过大（如 1024x1024），需要缩放处理。\n\n### 处理步骤\n\n1. **下载原始图标**：从 GitHub issue 或评论中的 `user-attachments` 链接下载 PNG 文件\n2. **检查原始尺寸**：使用 `file` 命令确认格式和尺寸\n3. **缩放处理**：使用 Python Pillow 进行缩放（优先 512x512）\n   ```python\n   from PIL import Image\n   img = Image.open('input.png')\n   img = img.convert('RGBA')\n   img = img.resize((512, 512), Image.LANCZOS)\n   img.save('output.png', 'PNG', optimize=True)\n   ```\n4. **验证结果**：确认输出为 PNG 格式、512x512px、文件大小 < 50KB\n\n### 环境依赖\n\n- 图片缩放依赖 `Pillow`，如未安装可通过 `pip3 install Pillow` 安装\n- 环境中通常没有 ImageMagick（`convert`/`magick`）或 ffmpeg，优先使用 Python 方案\n- Node.js `canvas` 模块通常也不可用\n\n### 规格要求\n\n- 格式：PNG（不支持 SVG）\n- 尺寸：优先 512x512px（≤50KB），也支持 200x200px（≤20KB）\n- 设计参考：圆形图标有效区域 140x140px，正方形 120x120px，长方形 160x80px"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\n这是一个中国常用联系人头像库（vCards），为 iOS/macOS 设备提供企业和机构的联系人信息，用于优化来电和信息界面体验。项目生成 vCard 格式的联系人文件，并支持通过 CardDAV 服务分发。\n\n技术栈：Bun（运行时 / 包管理 / 测试）+ TypeScript（严格模式，`tsc --noEmit` 校验）。\n\n## 核心架构\n\n### 文件结构\n- `data/` - 按分类存储的 YAML 数据文件和对应的 PNG 图标\n  - 每个条目包含一个 `.yaml` 配置文件和一个 `.png` 图标文件\n  - YAML 文件包含 `basic` 对象，包含 `organization`、`cellPhone`、`url`、`workEmail` 等字段\n  - 图标优先使用 512x512px（≤50KB），也支持 200x200px（≤20KB）的 PNG 格式\n- `src/` - TypeScript 源码，由 Bun 直接运行，无需编译产物\n  - `src/build.ts` - 构建入口（CLI，`bun run src/build.ts <task>`）\n  - `src/data.test.ts` - 数据校验测试（`bun test`）\n  - `src/core/data.ts` - YAML 扫描与解析\n  - `src/core/git.ts` - 读取 yaml/png 的 git 提交时间（REV）\n  - `src/core/vcard.ts` - vCard 渲染（标准版与 CardDAV 版共用）\n  - `src/const/` - Zod schema（`schema.ts`）与不收录名单（`block.ts`）\n  - `src/utils/` - 拼音、并发池等纯函数\n\n### 构建系统\n- 运行时与包管理器为 Bun，TypeScript 通过 `tsc --noEmit` 做类型检查\n- 两个主要的生成流程（`src/build.ts` 中的 task）：\n  - `build` - 标准 vCard 生成，产出 `temp/` 与 `public/`\n  - `radicale` - CardDAV 版本，附加 UID 与 git 提交时间 REV，产出 `radicale/`\n- 支持生成分类文件夹和汇总文件（`temp/汇总/<分类>.all.vcf`、`temp/汇总/全部.vcf`）\n- 支持生成 Radicale CardDAV 服务所需的文件结构\n- 构建产物与旧版 Node 实现逐字节一致（标准版仅 REV 为构建时间）\n\n### vCard 渲染\n- `src/core/vcard.ts` 的 `renderVCard(yamlPath, options)` 为统一入口\n- 不传 `options.carddav` 时生成标准 vCard；传入 `{ carddav: { revision } }` 时写入\n  稳定的 UID 与基于 git 提交时间的 REV（对应原来的 `vcard-ext` 插件）\n- 使用 `vcards-js` 库生成 vCard 格式，带标签的号码/邮箱通过 `X-ABLabel` 拼接\n- 自动添加拼音字段（`X-PHONETIC-ORG`）用于中文排序，并按 RFC 2426 折行\n\n## 常用命令\n\n### 开发和测试\n```bash\n# 安装依赖\nbun install\n\n# 运行数据格式检查和 schema 验证\nbun test\n\n# TypeScript 类型检查\nbun run typecheck\n\n# 构建标准版本（用于发布）\nbun run build\n\n# 构建 CardDAV 服务版本\nbun run radicale\n```\n\n## 数据验证和规范\n\n### Schema 验证\n- 使用 Zod 进行数据验证，配置在 `src/const/schema.ts`\n- 电话号码使用 Zod 的 `z.e164()` 校验，未带 `+` 的号码自动补 `+86`\n- 支持中国区号格式和国际格式（带 `+` 的保持原区号）\n\n### 测试规范\n- 图标必须是合法的 PNG 格式（优先 512x512px ≤50KB，也支持 200x200px ≤20KB）\n- YAML 数据必须符合定义的 schema\n- 检查阻止列表（`src/const/block.js`）中的机构\n\n### 添加新条目\n1. 在对应的 `data/分类/` 目录下添加 `.yaml` 和 `.png` 文件\n2. 运行 `bun test` 检查格式规范\n3. YAML 文件必须包含：\n   - `basic.organization` - 机构名称\n   - `basic.cellPhone` - 电话号码数组\n   - `basic.url` - 官网链接（可选）\n   - `basic.workEmail` - 邮箱数组（可选）\n   - `basic` 至少包含 `cellPhone`、`workEmail`、`url` 之一\n\n## 特殊处理\n\n### 电话号码收录\n- 数据不收录 106 开头的短信推送长号码（超过11位）\n\n### 中文支持\n- 自动生成拼音字段用于通讯录排序\n- 使用 `pinyin-pro` 库进行拼音转换\n\n### CardDAV 服务\n- 生成 Radicale 兼容的目录结构\n- iOS 版本按分类生成文件夹\n- macOS 版本将所有联系人合并到一个文件夹\n\n## 输出文件\n\n- `temp/` - 临时生成的 vCard 文件，按分类组织\n- `public/archive.zip` - 打包的发布文件\n- `radicale/ios/` - iOS CardDAV 服务文件，按分类分文件夹\n- `radicale/macos/全部/` - macOS CardDAV 服务文件，所有联系人在一个文件夹\n\n## 关键技术细节\n\n### vCard 生成差异\n- **标准版本**（`bun run build`）：`renderVCard()` 不传 `carddav` 选项，适用于一般用户\n- **CardDAV 版本**（`bun run radicale`）：传入 `carddav: { revision }`，添加稳定的 UID 和基于 git 的 REV 字段\n\n### Git 时间戳集成\n- CardDAV 版本通过 `src/core/git.ts` 使用 `git log` 获取文件最后修改时间（并发上限 8）\n- REV 字段使用 YAML 和 PNG 文件中较新的时间戳\n- 确保 CardDAV 客户端能正确检测更新\n\n### 拼音处理\n- 使用 `pinyin-pro` 库生成拼音（`src/utils/pinyin.ts`）\n- 自动为中文机构名添加 `X-PHONETIC-ORG` 字段\n- 支持通讯录中的中文排序功能\n\n## 注意事项\n\n- 不支持 SVG 图标，必须转换为 PNG\n- 图标设计规范：圆形 140x140px，正方形 120x120px，长方形 160x80px\n- 所有文本编码使用 UTF-8\n- 项目使用 Bun + TypeScript，源码由 Bun 直接运行（ES 模块语法）\n- `zip` 命令用于打包 `public/archive.zip`，为 `build` 任务的外部依赖\n- CardDAV 版本使用 `bun run radicale` 确保包含完整的元数据\n\n## 图标标准化处理\n\n项目优先使用 512x512px 的 PNG 格式，文件大小不超过 50KB。也支持 200x200px（≤20KB）作为备选。Issue 中提供的图标通常尺寸过大（如 1024x1024），需要缩放处理。\n\n### 处理步骤\n\n1. **下载原始图标**：从 GitHub issue 或评论中的 `user-attachments` 链接下载 PNG 文件\n2. **检查原始尺寸**：使用 `file` 命令确认格式和尺寸\n3. **缩放处理**：使用 Python Pillow 进行缩放（优先 512x512）\n   ```python\n   from PIL import Image\n   img = Image.open('input.png')\n   img = img.convert('RGBA')\n   img = img.resize((512, 512), Image.LANCZOS)\n   img.save('output.png', 'PNG', optimize=True)\n   ```\n4. **验证结果**：确认输出为 PNG 格式、512x512px、文件大小 < 50KB\n\n### 环境依赖\n\n- 图片缩放依赖 `Pillow`，如未安装可通过 `pip3 install Pillow` 安装\n- 环境中通常没有 ImageMagick（`convert`/`magick`）或 ffmpeg，优先使用 Python 方案\n- Node.js `canvas` 模块通常也不可用\n\n### 规格要求\n\n- 格式：PNG（不支持 SVG）\n- 尺寸：优先 512x512px（≤50KB），也支持 200x200px（≤20KB）\n- 设计参考：圆形图标有效区域 140x140px，正方形 120x120px，长方形 160x80px"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/metowolf/vCards/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\n这是一个中国常用联系人头像库（vCards），为 iOS/macOS 设备提供企业和机构的联系人信息，用于优化来电和信息界面体验。项目生成 vCard 格式的联系人文件，并支持通过 CardDAV 服务分发。\n\n技术栈：Bun（运行时 / 包管理 / 测试）+ TypeScript（严格模式，`tsc --noEmit` 校验）。\n\n## 核心架构\n\n### 文件结构\n- `data/` - 按分类存储的 YAML 数据文件和对应的 PNG 图标\n  - 每个条目包含一个 `.yaml` 配置文件和一个 `.png` 图标文件\n  - YAML 文件包含 `basic` 对象，包含 `organization`、`cellPhone`、`url`、`workEmail` 等字段\n  - 图标优先使用 512x512px（≤50KB），也支持 200x200px（≤20KB）的 PNG 格式\n- `src/` - TypeScript 源码，由 Bun 直接运行，无需编译产物\n  - `src/build.ts` - 构建入口（CLI，`bun run src/build.ts <task>`）\n  - `src/data.test.ts` - 数据校验测试（`bun test`）\n  - `src/core/data.ts` - YAML 扫描与解析\n  - `src/core/git.ts` - 读取 yaml/png 的 git 提交时间（REV）\n  - `src/core/vcard.ts` - vCard 渲染（标准版与 CardDAV 版共用）\n  - `src/const/` - Zod schema（`schema.ts`）与不收录名单（`block.ts`）\n  - `src/utils/` - 拼音、并发池等纯函数\n\n### 构建系统\n- 运行时与包管理器为 Bun，TypeScript 通过 `tsc --noEmit` 做类型检查\n- 两个主要的生成流程（`src/build.ts` 中的 task）：\n  - `build` - 标准 vCard 生成，产出 `temp/` 与 `public/`\n  - `radicale` - CardDAV 版本，附加 UID 与 git 提交时间 REV，产出 `radicale/`\n- 支持生成分类文件夹和汇总文件（`temp/汇总/<分类>.all.vcf`、`temp/汇总/全部.vcf`）\n- 支持生成 Radicale CardDAV 服务所需的文件结构\n- 构建产物与旧版 Node 实现逐字节一致（标准版仅 REV 为构建时间）\n\n### vCard 渲染\n- `src/core/vcard.ts` 的 `renderVCard(yamlPath, options)` 为统一入口\n- 不传 `options.carddav` 时生成标准 vCard；传入 `{ carddav: { revision } }` 时写入\n  稳定的 UID 与基于 git 提交时间的 REV（对应原来的 `vcard-ext` 插件）\n- 使用 `vcards-js` 库生成 vCard 格式，带标签的号码/邮箱通过 `X-ABLabel` 拼接\n- 自动添加拼音字段（`X-PHONETIC-ORG`）用于中文排序，并按 RFC 2426 折行\n\n## 常用命令\n\n### 开发和测试\n```bash\n# 安装依赖\nbun install\n\n# 运行数据格式检查和 schema 验证\nbun test\n\n# TypeScript 类型检查\nbun run typecheck\n\n# 构建标准版本（用于发布）\nbun run build\n\n# 构建 CardDAV 服务版本\nbun run radicale\n```\n\n## 数据验证和规范\n\n### Schema 验证\n- 使用 Zod 进行数据验证，配置在 `src/const/schema.ts`\n- 电话号码使用 Zod 的 `z.e164()` 校验，未带 `+` 的号码自动补 `+86`\n- 支持中国区号格式和国际格式（带 `+` 的保持原区号）\n\n### 测试规范\n- 图标必须是合法的 PNG 格式（优先 512x512px ≤50KB，也支持 200x200px ≤20KB）\n- YAML 数据必须符合定义的 schema\n- 检查阻止列表（`src/const/block.js`）中的机构\n\n### 添加新条目\n1. 在对应的 `data/分类/` 目录下添加 `.yaml` 和 `.png` 文件\n2. 运行 `bun test` 检查格式规范\n3. YAML 文件必须包含：\n   - `basic.organization` - 机构名称\n   - `basic.cellPhone` - 电话号码数组\n   - `basic.url` - 官网链接（可选）\n   - `basic.workEmail` - 邮箱数组（可选）\n   - `basic` 至少包含 `cellPhone`、`workEmail`、`url` 之一\n\n## 特殊处理\n\n### 电话号码收录\n- 数据不收录 106 开头的短信推送长号码（超过11位）\n\n### 中文支持\n- 自动生成拼音字段用于通讯录排序\n- 使用 `pinyin-pro` 库进行拼音转换\n\n### CardDAV 服务\n- 生成 Radicale 兼容的目录结构\n- iOS 版本按分类生成文件夹\n- macOS 版本将所有联系人合并到一个文件夹\n\n## 输出文件\n\n- `temp/` - 临时生成的 vCard 文件，按分类组织\n- `public/archive.zip` - 打包的发布文件\n- `radicale/ios/` - iOS CardDAV 服务文件，按分类分文件夹\n- `radicale/macos/全部/` - macOS CardDAV 服务文件，所有联系人在一个文件夹\n\n## 关键技术细节\n\n### vCard 生成差异\n- **标准版本**（`bun run build`）：`renderVCard()` 不传 `carddav` 选项，适用于一般用户\n- **CardDAV 版本**（`bun run radicale`）：传入 `carddav: { revision }`，添加稳定的 UID 和基于 git 的 REV 字段\n\n### Git 时间戳集成\n- CardDAV 版本通过 `src/core/git.ts` 使用 `git log` 获取文件最后修改时间（并发上限 8）\n- REV 字段使用 YAML 和 PNG 文件中较新的时间戳\n- 确保 CardDAV 客户端能正确检测更新\n\n### 拼音处理\n- 使用 `pinyin-pro` 库生成拼音（`src/utils/pinyin.ts`）\n- 自动为中文机构名添加 `X-PHONETIC-ORG` 字段\n- 支持通讯录中的中文排序功能\n\n## 注意事项\n\n- 不支持 SVG 图标，必须转换为 PNG\n- 图标设计规范：圆形 140x140px，正方形 120x120px，长方形 160x80px\n- 所有文本编码使用 UTF-8\n- 项目使用 Bun + TypeScript，源码由 Bun 直接运行（ES 模块语法）\n- `zip` 命令用于打包 `public/archive.zip`，为 `build` 任务的外部依赖\n- CardDAV 版本使用 `bun run radicale` 确保包含完整的元数据\n\n## 图标标准化处理\n\n项目优先使用 512x512px 的 PNG 格式，文件大小不超过 50KB。也支持 200x200px（≤20KB）作为备选。Issue 中提供的图标通常尺寸过大（如 1024x1024），需要缩放处理。\n\n### 处理步骤\n\n1. **下载原始图标**：从 GitHub issue 或评论中的 `user-attachments` 链接下载 PNG 文件\n2. **检查原始尺寸**：使用 `file` 命令确认格式和尺寸\n3. **缩放处理**：使用 Python Pillow 进行缩放（优先 512x512）\n   ```python\n   from PIL import Image\n   img = Image.open('input.png')\n   img = img.convert('RGBA')\n   img = img.resize((512, 512), Image.LANCZOS)\n   img.save('output.png', 'PNG', optimize=True)\n   ```\n4. **验证结果**：确认输出为 PNG 格式、512x512px、文件大小 < 50KB\n\n### 环境依赖\n\n- 图片缩放依赖 `Pillow`，如未安装可通过 `pip3 install Pillow` 安装\n- 环境中通常没有 ImageMagick（`convert`/`magick`）或 ffmpeg，优先使用 Python 方案\n- Node.js `canvas` 模块通常也不可用\n\n### 规格要求\n\n- 格式：PNG（不支持 SVG）\n- 尺寸：优先 512x512px（≤50KB），也支持 200x200px（≤20KB）\n- 设计参考：圆形图标有效区域 140x140px，正方形 120x120px，长方形 160x80px","isInternal":false,"tokens":2364,"sizeBytes":6674}],"systemPromptSnippet":"<yakaai_skills repo=\"metowolf/vCards\">\n<!-- File: CLAUDE.md (Tokens: ~2364 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\n这是一个中国常用联系人头像库（vCards），为 iOS/macOS 设备提供企业和机构的联系人信息，用于优化来电和信息界面体验。项目生成 vCard 格式的联系人文件，并支持通过 CardDAV 服务分发。\n\n技术栈：Bun（运行时 / 包管理 / 测试）+ TypeScript（严格模式，`tsc --noEmit` 校验）。\n\n## 核心架构\n\n### 文件结构\n- `data/` - 按分类存储的 YAML 数据文件和对应的 PNG 图标\n  - 每个条目包含一个 `.yaml` 配置文件和一个 `.png` 图标文件\n  - YAML 文件包含 `basic` 对象，包含 `organization`、`cellPhone`、`url`、`workEmail` 等字段\n  - 图标优先使用 512x512px（≤50KB），也支持 200x200px（≤20KB）的 PNG 格式\n- `src/` - TypeScript 源码，由 Bun 直接运行，无需编译产物\n  - `src/build.ts` - 构建入口（CLI，`bun run src/build.ts <task>`）\n  - `src/data.test.ts` - 数据校验测试（`bun test`）\n  - `src/core/data.ts` - YAML 扫描与解析\n  - `src/core/git.ts` - 读取 yaml/png 的 git 提交时间（REV）\n  - `src/core/vcard.ts` - vCard 渲染（标准版与 CardDAV 版共用）\n  - `src/const/` - Zod schema（`schema.ts`）与不收录名单（`block.ts`）\n  - `src/utils/` - 拼音、并发池等纯函数\n\n### 构建系统\n- 运行时与包管理器为 Bun，TypeScript 通过 `tsc --noEmit` 做类型检查\n- 两个主要的生成流程（`src/build.ts` 中的 task）：\n  - `build` - 标准 vCard 生成，产出 `temp/` 与 `public/`\n  - `radicale` - CardDAV 版本，附加 UID 与 git 提交时间 REV，产出 `radicale/`\n- 支持生成分类文件夹和汇总文件（`temp/汇总/<分类>.all.vcf`、`temp/汇总/全部.vcf`）\n- 支持生成 Radicale CardDAV 服务所需的文件结构\n- 构建产物与旧版 Node 实现逐字节一致（标准版仅 REV 为构建时间）\n\n### vCard 渲染\n- `src/core/vcard.ts` 的 `renderVCard(yamlPath, options)` 为统一入口\n- 不传 `options.carddav` 时生成标准 vCard；传入 `{ carddav: { revision } }` 时写入\n  稳定的 UID 与基于 git 提交时间的 REV（对应原来的 `vcard-ext` 插件）\n- 使用 `vcards-js` 库生成 vCard 格式，带标签的号码/邮箱通过 `X-ABLabel` 拼接\n- 自动添加拼音字段（`X-PHONETIC-ORG`）用于中文排序，并按 RFC 2426 折行\n\n## 常用命令\n\n### 开发和测试\n```bash\n# 安装依赖\nbun install\n\n# 运行数据格式检查和 schema 验证\nbun test\n\n# TypeScript 类型检查\nbun run typecheck\n\n# 构建标准版本（用于发布）\nbun run build\n\n# 构建 CardDAV 服务版本\nbun run radicale\n```\n\n## 数据验证和规范\n\n### Schema 验证\n- 使用 Zod 进行数据验证，配置在 `src/const/schema.ts`\n- 电话号码使用 Zod 的 `z.e164()` 校验，未带 `+` 的号码自动补 `+86`\n- 支持中国区号格式和国际格式（带 `+` 的保持原区号）\n\n### 测试规范\n- 图标必须是合法的 PNG 格式（优先 512x512px ≤50KB，也支持 200x200px ≤20KB）\n- YAML 数据必须符合定义的 schema\n- 检查阻止列表（`src/const/block.js`）中的机构\n\n### 添加新条目\n1. 在对应的 `data/分类/` 目录下添加 `.yaml` 和 `.png` 文件\n2. 运行 `bun test` 检查格式规范\n3. YAML 文件必须包含：\n   - `basic.organization` - 机构名称\n   - `basic.cellPhone` - 电话号码数组\n   - `basic.url` - 官网链接（可选）\n   - `basic.workEmail` - 邮箱数组（可选）\n   - `basic` 至少包含 `cellPhone`、`workEmail`、`url` 之一\n\n## 特殊处理\n\n### 电话号码收录\n- 数据不收录 106 开头的短信推送长号码（超过11位）\n\n### 中文支持\n- 自动生成拼音字段用于通讯录排序\n- 使用 `pinyin-pro` 库进行拼音转换\n\n### CardDAV 服务\n- 生成 Radicale 兼容的目录结构\n- iOS 版本按分类生成文件夹\n- macOS 版本将所有联系人合并到一个文件夹\n\n## 输出文件\n\n- `temp/` - 临时生成的 vCard 文件，按分类组织\n- `public/archive.zip` - 打包的发布文件\n- `radicale/ios/` - iOS CardDAV 服务文件，按分类分文件夹\n- `radicale/macos/全部/` - macOS CardDAV 服务文件，所有联系人在一个文件夹\n\n## 关键技术细节\n\n### vCard 生成差异\n- **标准版本**（`bun run build`）：`renderVCard()` 不传 `carddav` 选项，适用于一般用户\n- **CardDAV 版本**（`bun run radicale`）：传入 `carddav: { revision }`，添加稳定的 UID 和基于 git 的 REV 字段\n\n### Git 时间戳集成\n- CardDAV 版本通过 `src/core/git.ts` 使用 `git log` 获取文件最后修改时间（并发上限 8）\n- REV 字段使用 YAML 和 PNG 文件中较新的时间戳\n- 确保 CardDAV 客户端能正确检测更新\n\n### 拼音处理\n- 使用 `pinyin-pro` 库生成拼音（`src/utils/pinyin.ts`）\n- 自动为中文机构名添加 `X-PHONETIC-ORG` 字段\n- 支持通讯录中的中文排序功能\n\n## 注意事项\n\n- 不支持 SVG 图标，必须转换为 PNG\n- 图标设计规范：圆形 140x140px，正方形 120x120px，长方形 160x80px\n- 所有文本编码使用 UTF-8\n- 项目使用 Bun + TypeScript，源码由 Bun 直接运行（ES 模块语法）\n- `zip` 命令用于打包 `public/archive.zip`，为 `build` 任务的外部依赖\n- CardDAV 版本使用 `bun run radicale` 确保包含完整的元数据\n\n## 图标标准化处理\n\n项目优先使用 512x512px 的 PNG 格式，文件大小不超过 50KB。也支持 200x200px（≤20KB）作为备选。Issue 中提供的图标通常尺寸过大（如 1024x1024），需要缩放处理。\n\n### 处理步骤\n\n1. **下载原始图标**：从 GitHub issue 或评论中的 `user-attachments` 链接下载 PNG 文件\n2. **检查原始尺寸**：使用 `file` 命令确认格式和尺寸\n3. **缩放处理**：使用 Python Pillow 进行缩放（优先 512x512）\n   ```python\n   from PIL import Image\n   img = Image.open('input.png')\n   img = img.convert('RGBA')\n   img = img.resize((512, 512), Image.LANCZOS)\n   img.save('output.png', 'PNG', optimize=True)\n   ```\n4. **验证结果**：确认输出为 PNG 格式、512x512px、文件大小 < 50KB\n\n### 环境依赖\n\n- 图片缩放依赖 `Pillow`，如未安装可通过 `pip3 install Pillow` 安装\n- 环境中通常没有 ImageMagick（`convert`/`magick`）或 ffmpeg，优先使用 Python 方案\n- Node.js `canvas` 模块通常也不可用\n\n### 规格要求\n\n- 格式：PNG（不支持 SVG）\n- 尺寸：优先 512x512px（≤50KB），也支持 200x200px（≤20KB）\n- 设计参考：圆形图标有效区域 140x140px，正方形 120x120px，长方形 160x80px\n</yakaai_skills>"}