Serendipity
0061345cc4
- 更新插件 manifest.json 中的版本号 - 更新插件配置中的 lastDismissedVersion 字段 - 在插件配置中添加 miyoSearchAll 选项 - 添加 CLAUDE.md 项目文档
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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) 博客平台的社区插件。vault 根目录同时包含 `博客/` 目录存放博客文章草稿。
|
||
|
||
## 开发命令
|
||
|
||
所有开发命令在 `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/` 中。
|