Obsidian/CLAUDE.md

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 博客平台的社区插件
• Club-Service-Guide — 河南理工大学人工智能协会内部知识库（独立 Git 仓库，托管于协会 Gitea）

vault 根目录的 博客/ 目录存放博客文章草稿，通过 Halo CLI 发布到 blog.liuhangyv.top。

博客目录结构

博客/
├── covers/              # 博客封面图片（.png）
├── AI与大模型/           # AI 与大模型相关文章
├── 学术与效率/           # 学术研究与效率工具
├── 数据分析与报告/       # 数据分析与报告相关
├── 机器学习/            # 机器学习理论与应用
├── 编程与工具/           # 编程技巧与工具链
└── 其他/               # 未分类文章

博客发布

发布方式

两种方式均可发布博客文章，优先使用 Halo CLI：

1. Halo CLI（推荐）— 从 Markdown 文件直接发布

# 导入并发布文章（导入后默认为草稿，需手动 publish）
npx halo post import-markdown --file "博客/编程与工具/文章名.md"
# 更新分类、slug 并发布
npx halo post update <post-name> --categories "<category-name>" --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），用于测试。

npx halo post list --page 1 --size 20           # 查看文章列表
npx halo post get <name-or-id>                   # 查看文章详情
npx halo post create --title "标题" --content "内容" --publish true
npx halo post update <name> --categories "..." --tags "..." --publish true
npx halo post tag list                           # 列出所有标签
npx halo post category list                      # 列出所有分类

博客分类与标签（硬约束）

发布时必须只使用现有分类和标签，禁止创建新的。 现有 8 个分类和 11 个标签（具体列表见 memory halo-blog-tags）。

常用组合：

• 技术教程/工具文章 → 分类 技术思考，标签 技术深潜（+ 零基础入门 如面向新手）
• 协会活动/通知 → 分类 协会进行时，标签 协会动态
• AI 科普/入门 → 分类 成长实验室，标签 零基础入门, AI智能体

博客文章 Frontmatter 格式

---
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 作为包管理器：

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

目录结构

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/ 中。