# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## 项目概述 这是一个 Obsidian vault，包含两个主要项目： - **obsidian-halo** — 将 Obsidian 笔记发布到 [Halo](https://github.com/halo-dev/halo) 博客平台的社区插件 - **Club-Service-Guide** — 河南理工大学人工智能协会内部知识库（独立 Git 仓库，托管于协会 Gitea） vault 根目录的 `博客/` 目录存放博客文章草稿，通过 Halo CLI 发布到 `blog.liuhangyv.top`。 ### 博客目录结构 ```text 博客/ ├── covers/ # 博客封面图片（.png） ├── AI与大模型/ # AI 与大模型相关文章 ├── 学术与效率/ # 学术研究与效率工具 ├── 数据分析与报告/ # 数据分析与报告相关 ├── 机器学习/ # 机器学习理论与应用 ├── 编程与工具/ # 编程技巧与工具链 └── 其他/ # 未分类文章 ``` ## 博客发布 ### 发布方式 两种方式均可发布博客文章，优先使用 Halo CLI： 1. **Halo CLI**（推荐）— 从 Markdown 文件直接发布 ```bash # 导入并发布文章（导入后默认为草稿，需手动 publish） npx halo post import-markdown --file "博客/编程与工具/文章名.md" # 更新分类、slug 并发布 npx halo post update --categories "" --slug "slug-name" --publish true ``` 2. **obsidian-halo 插件** — 在 Obsidian 编辑器内通过命令面板发布 ### Halo CLI 配置文件 当前激活的 profile 是 `aliyun`，指向生产环境 `https://blog.liuhangyv.top`。NAS 本地有 Halo 备份实例（`http://192.168.5.8:8090`，profile `local`），用于测试。 ```bash npx halo post list --page 1 --size 20 # 查看文章列表 npx halo post get # 查看文章详情 npx halo post create --title "标题" --content "内容" --publish true npx halo post update --categories "..." --tags "..." --publish true npx halo post tag list # 列出所有标签 npx halo post category list # 列出所有分类 ``` ### 博客分类与标签（硬约束） **发布时必须只使用现有分类和标签，禁止创建新的。** 现有 8 个分类和 11 个标签（具体列表见 memory `halo-blog-tags`）。 常用组合： - 技术教程/工具文章 → 分类 `技术思考`，标签 `技术深潜`（+ `零基础入门` 如面向新手） - 协会活动/通知 → 分类 `协会进行时`，标签 `协会动态` - AI 科普/入门 → 分类 `成长实验室`，标签 `零基础入门, AI智能体` ### 博客文章 Frontmatter 格式 ```yaml --- title: 文章标题 date: 2026-07-23 author: liuhangyv category: 技术思考 # 必须从现有 8 个分类中选 tags: - 技术深潜 # 必须从现有 11 个标签中选 - 零基础入门 excerpt: 文章摘要 --- ``` ## Club-Service-Guide `Club-Service-Guide/` 是河南理工大学人工智能协会的内部知识库项目，有独立的 Git 仓库和 CLAUDE.md。 - **Git 远程**: `git@gitea.liuhangyv.top:Serendipity/Club-Service-Guide.git` - **访问方式**: Obsidian 打开 `Club-Service-Guide/` 目录作为独立 vault - **链接规范**: 使用标准 Markdown 相对路径（`[文本](路径.md)`），禁用 `[[wiki-link]]`（Gitea Web 不渲染） - **提交格式**: 约定式提交 `docs:` / `feat:` 等 ## 开发命令 所有开发命令在 `obsidian-halo/` 目录下执行，使用 pnpm 作为包管理器： ```bash cd obsidian-halo pnpm install # 安装依赖 pnpm run dev # 开发模式（watch + 自动构建） pnpm run build # 生产构建（输出 main.js） pnpm run check # Biome lint + 格式化（自动修复） pnpm test # 运行测试（watch 模式） pnpm run test:run # 运行测试（单次） ``` 构建产物为 `obsidian-halo/main.js`，直接由 Obsidian 加载。 ## 代码规范 - **Linter/Formatter**: Biome（非 ESLint/Prettier），配置在 `biome.json` - 缩进: 2 空格，行宽 120，LF 换行，双引号，尾逗号 - 测试文件放在源码同级的 `__tests__/` 目录，使用 Vitest ## 架构 ### 技术栈 - TypeScript + Obsidian Plugin API - Rslib（基于 Rspack 的库构建工具）打包，输出 CJS 格式 - `@halo-dev/api-client` 与 Halo API 交互 - i18next 国际化（en / zh-cn / zh-tw） - gray-matter 解析 frontmatter，markdown-it 渲染 Markdown ### 目录结构 ```text obsidian-halo/src/ ├── main.ts # 插件入口，注册命令和 UI ├── settings.ts # 设置类型定义和设置面板 ├── i18n/ # 国际化资源 ├── commands/ # 命令实现（发布、删除、导入、搜索等） ├── modals/ # 弹窗 UI 组件 ├── views/ # 面板视图（同步状态） ├── services/ # 核心业务逻辑层 │ ├── client.ts # HTTP 客户端（封装 Obsidian requestUrl） │ ├── halo-service.ts # 主服务门面，协调各子服务 │ ├── post-service.ts # 文章 CRUD │ ├── content-service.ts # 内容处理 │ ├── image-service.ts # 图片上传 │ ├── taxonomy-service.ts # 标签/分类管理 │ ├── types.ts # Halo API 数据类型（Post, Tag, Category 等） │ └── error.ts # 错误类型体系（HaloError / HttpError） ├── service/ # 兼容性重导出层（指向 services/） └── utils/ # 工具函数（重试、日志、ID 生成、Markdown 处理等） ``` ### 关键设计模式 - **HaloService（门面模式）**: `src/services/halo-service.ts` 是核心协调器，组合 PostService、ImageService、TaxonomyService、ContentService 完成发布/拉取/导入等操作 - **HaloClient（HTTP 封装）**: 封装 Obsidian 的 `requestUrl`，内置重试机制（`withRetry`）和错误映射 - **Frontmatter 驱动**: 已发布文章通过 YAML frontmatter 中的 `halo` 字段（site/name/publish）追踪同步状态 - **多站点支持**: 设置中可配置多个 Halo 站点，通过 `HaloSite` 接口管理，支持设置默认站点 ### 服务层兼容路径 `src/service/index.ts` 是兼容性重新导出，实际指向 `src/services/halo-service.ts`。`main.ts` 通过 `import HaloService from "./service"` 引入。新功能应写在 `src/services/` 中。