CLAUDE.md · diff
git:20260521.422d879 to git:20260523.69d4743
105 added, 107 removed. Audit A to A.
# StarBlog Publisher 项目指南
## 项目概述
- StarBlog Publisher 是一个基于 Avalonia UI 框架的跨平台桌面应用程序（C# .NET），用于将本地 Markdown 文章发布到 StarBlog 博客系统。支持 Windows/Linux/macOS 三平台。
+ StarBlog Publisher 是一个跨平台博客发布系统（C# .NET），包含三个端：
+ 1. **GUI** — Avalonia UI 桌面应用（主入口）
+ 2. **CLI** — 命令行工具，面向脚本和自动化
+ 3. **MCP Server** — 面向 AI Agent 的标准化工具接口
- ## 关键依赖
- - **框架**: .NET 10.0, Avalonia 11.3.10
- - **MVVM**: CommunityToolkit.Mvvm 8.4.0, ReactiveUI 22.3.1
- - **HTTP**: Refit 9.0.2 (声明式 REST 客户端)
- - **AI**: Microsoft.Extensions.AI.OpenAI (用于 AI 辅助功能)
- - **Markdown**: Markdig 0.44.0, Markdown.Avalonia 11.0.3-a1
- - **图片处理**: SixLabors.ImageSharp 3.1.12
- - **序列化**: Newtonsoft.Json 13.0.4
- - **词云**: Sdcb.WordCloud 2.0.1
- - **图标**: Projektanker.Icons.Avalonia.FontAwesome 9.6.2
- - **消息弹窗**: MessageBox.Avalonia 3.3.1
- - **加载动画**: LoadingIndicators.Avalonia 11.0.11.1
- - **加密**: System.Security.Cryptography.ProtectedData 10.0.1
+ 三端共享同一套 Application 业务逻辑，通过 `StarBlogPublisher.Core` 类库复用。
## 项目结构
```
- StarBlogPublisher/
- ├── Models/ # 数据模型 (BlogPost, Category, AIProfile 等)
- ├── Models/Dtos/ # DTO 数据传输对象
- ├── Services/ # 服务层
+ StarBlogPublisher.Core/ # 共享核心库（无 UI 依赖）
+ ├── Models/ # 数据模型（BlogPost, Category, AIProfile 等）
+ ├── Models/Dtos/ # DTO 数据传输对象
+ ├── Services/ # 基础设施服务
+ │ ├── AppSettings.cs # 配置管理
+ │ ├── GlobalState.cs # 认证状态
+ │ ├── ApiService.cs # StarBlog API (Refit)
│ ├── AIService.cs # AI 大模型服务
- │ ├── ApiService.cs # StarBlog API 服务 (Refit)
- │ ├── AppSettings.cs # 应用配置管理
- │ ├── GlobalState.cs # 全局状态
- │ ├── ImageCompressionService.cs # 图片压缩
│ ├── MarkdownProcessor.cs # Markdown 处理
- │ ├── StarBlogApi/ # Refit API 接口定义
- │ │ ├── IAuth.cs # 认证接口
- │ │ ├── IBlogPost.cs # 文章接口
- │ │ └── ICategory.cs # 分类接口
- │ └── Security/ # 安全相关服务
- ├── ViewModels/ # ViewModel 层
- │ ├── MainWindowViewModel.cs
- │ ├── SettingsWindowViewModel.cs
- │ ├── AiSettingsWindowViewModel.cs
- │ ├── PreviewWindowViewModel.cs
- │ ├── WordCloudWindowViewModel.cs
- │ ├── ImageGalleryWindowViewModel.cs
- │ ├── AddCategoryWindowViewModel.cs
- │ ├── CoverPromptWindowViewModel.cs
- │ ├── AboutWindowViewModel.cs
- │ └── ViewModelBase.cs
- ├── Views/ # 视图层 (.axaml + .axaml.cs)
- │ ├── MainWindow.axaml # 主窗口
- │ ├── SettingsWindow.axaml # 设置窗口
- │ ├── AiSettingsWindow.axaml # AI 设置窗口
- │ ├── PreviewWindow.axaml # 文章预览
- │ ├── WordCloudWindow.axaml # 词云窗口
- │ ├── ImageGalleryWindow.axaml # 图片管理
- │ ├── AddCategoryWindow.axaml # 添加分类
- │ ├── CoverPromptWindow.axaml # AI 封面提示词
- │ └── AboutWindow.axaml # 关于窗口
- └── Assets/ # 资源文件 (logo.ico 等)
+ │ ├── ImageCompressionService.cs
+ │ ├── StarBlogApi/ # Refit 接口定义
+ │ └── Security/ # 加密服务
+ ├── Services/Application/ # 应用服务（业务编排）
+ │ ├── AuthApplicationService.cs
+ │ ├── CategoryApplicationService.cs
+ │ ├── ArticlePublishApplicationService.cs
+ │ └── AiApplicationService.cs
+ └── Utils/ # PromptBuilder, PromptTemplates 等
+
+ StarBlogPublisher/ # GUI 项目（Avalonia）
+ ├── Models/AvaloniaImageInfo.cs # GUI 专属展示模型
+ ├── ViewModels/ # ViewModel 层（薄壳，调用 Application 服务）
+ ├── Views/ # 视图层 (.axaml)
+ └── Assets/
+
+ StarBlogPublisher.Cli/ # CLI + MCP Server
+ ├── Program.cs # 入口路由（CLI 模式 / MCP 模式）
+ ├── McpServer.cs # MCP Server 入口（stdio 传输）
+ ├── Commands/ # System.CommandLine 命令
+ │ ├── AuthCommand.cs # auth login/status/logout
+ │ ├── CategoryCommand.cs # category list/create
+ │ ├── PostCommand.cs # post publish/get
+ │ └── AiCommand.cs # ai generate-summary/optimize-title/suggest-tags/generate-slug
+ └── Tools/ # MCP Tools
+ ├── AuthTools.cs
+ ├── CategoryTools.cs
+ ├── PostTools.cs
+ └── AiTools.cs
```
- ## 核心业务流程
+ ## 架构原则
- ### 1. 登录流程
- - 用户输入 StarBlog 后端的域名和用户名密码
- - 通过 `ApiService` 调用 `/auth/login` 获取 JWT Token
- - Token 存储在 `GlobalState` 中，后续 Refit 请求自动附加
- - **注意**: 支持自定义后端地址（AppSettings.UseCustomBackend + BackendUrl）
+ 1. **ViewModel 不直接编排业务流程** — 业务逻辑在 Application 服务中
+ 2. **CLI 命令和 MCP Tool 只调用 Application 层 Use Case**
+ 3. **所有日志统一通过 ILogger** — Core 不直接写 stdout
+ 4. **MCP 模式下 stdout 仅输出协议消息** — 日志通过 stderr 输出
- ### 2. 文章发布流程
- - 选择本地 Markdown 文件 → 解析 FrontMatter（标题、分类、标签等）
- - 处理 Markdown 正文（提取/上传图片、处理链接、生成目录）
- - AI 辅助功能（可选）：生成/补充文章信息、优化标题、生成封面提示词
- - 手动/自动关联分类、设置发布时间等
- - 调用 API 发布（POST/PUT）
+ ## 常见命令
- ### 3. 图片处理
- - 扫描 Markdown 中的图片链接
- - 支持本地图片自动上传到 StarBlog 服务器
- - 支持图片压缩（ImageCompressionService）
- - 两种图片解析模式：标准模式 / 正则模式（配置 EnableRegexImageParsing）
+ ```bash
+ # 构建整个解决方案
+ dotnet build StarBlogPublisher.sln
- ### 4. AI 辅助流程
- - 支持 OpenAI、Azure OpenAI、Ollama 等多种提供商
- - 当前选用 AI 配置文件（AiProfile），包含 Provider / Key / Model / ApiBase
- - 支持标题润色、文章摘要生成、标签推荐、文章分类、封面图提示词
+ # 运行 GUI
+ dotnet run --project StarBlogPublisher
- ## 关键文件及其职责
+ # CLI 使用
+ dotnet run --project StarBlogPublisher.Cli -- auth status
+ dotnet run --project StarBlogPublisher.Cli -- category list
+ dotnet run --project StarBlogPublisher.Cli -- post publish ./hello.md --category 1
+ dotnet run --project StarBlogPublisher.Cli -- ai generate-summary ./hello.md
- ### Services/AppSettings.cs
- - 应用配置管理（JSON 文件存储在 `~/.config/StarBlogPublisher/settings.json` 或 `%APPDATA%/StarBlogPublisher/settings.json`）
- - 管理代理设置、后端 URL、AI 配置、登录凭据等
- - 敏感信息（密码、AI Key）通过 Security/EncryptionService 加密存储
- - 支持多 AI 配置文件（AIProfiles），通过配置名切换
+ # MCP Server（供 AI Agent 调用）
+ dotnet run --project StarBlogPublisher.Cli -- mcp
+ ```
- ### Services/AIService.cs
- - AI 服务封装，使用 `Microsoft.Extensions.AI.IChatClient`
- - 提供对话、标题润色、生成摘要、标签推荐、分类、封面提示等功能
- - 支持自动切换到当前选中的 AI 配置
- - **注意**: 传入的 system prompt 在每次对话时拼接，需要确保 prompt 中信息的完整性
+ ## MCP 配置示例
- ### Services/ApiService.cs
- - Refit 生成的 HTTP 客户端，封装所有 StarBlog 后端 API 调用
- - 提供 POST/PUT/GET/DELETE 文章、获取分类列表、上传图片等接口
- - 自动处理 Token 刷新（通过 RefitTypeRegistration 设置 HttpMessageHandler）
+ 在 Claude Desktop 或 Cursor 的 MCP 配置中添加：
- ### Services/GlobalState.cs
- - 全局单例状态，管理当前选中的文件、文章、分类列表、登录状态
- - 事件驱动：`StateChanged` 通知 UI 更新
+ ```json
+ {
+ "mcpServers": {
+ "starblog": {
+ "command": "dotnet",
+ "args": ["run", "--project", "/path/to/StarBlogPublisher.Cli", "--", "mcp"]
+ }
+ }
+ }
+ ```
- ## 版本发布
- - 使用 CI/CD 自动构建（GitHub Actions），触发格式：`v*.*.*` 标签
- - 默认配置为 AOT 编译，生成单文件可执行文件
- - 编译目标：win-x64 (.zip), linux-x64 (.tar.gz), osx-x64 (.tar.gz)
- - **注意**: AOT 相关配置在 csproj 中已注释，CI 构建时通过命令行参数启用
- - 当前框架目标为 net10.0，CI 使用 .NET 8.0（需要更新）
+ ### MCP Tools 列表
- ## Scoop 安装
- - 本仓库 `bucket/` 目录包含 Scoop 包管理器的安装清单 (`starblog-publisher.json`)
- - 通过将此仓库添加为 Scoop bucket 安装：`scoop bucket add starblog-publisher <repo-url> && scoop install starblog-publisher/starblog-publisher`
- - Windows 发布包命名格式：`StarBlogPublisher-windows-<VERSION>.zip`
- - 更新版本时需同步更新 `bucket/starblog-publisher.json` 中的 version 和 hash 值
+ | Tool | 描述 |
+ |------|------|
+ | `auth_login` | 登录到 StarBlog 后端 |
+ | `auth_status` | 查看登录状态 |
+ | `auth_logout` | 登出 |
+ | `category_list` | 列出所有分类 |
+ | `category_create` | 创建新分类 |
+ | `post_publish` | 发布 Markdown 文件为文章 |
+ | `post_get` | 获取文章详情 |
+ | `ai_optimize_title` | AI 优化标题 |
+ | `ai_generate_summary` | AI 生成摘要 |
+ | `ai_suggest_tags` | AI 推荐标签 |
+ | `ai_generate_slug` | AI 生成 URL slug |
+ | `ai_generate_cover_prompt` | AI 生成封面图提示词 |
- ## 常见命令
- - 构建：`dotnet build StarBlogPublisher/StarBlogPublisher.csproj`
- - 运行：`dotnet run --project StarBlogPublisher/StarBlogPublisher.csproj`
- - 发布（非 AOT）：`dotnet publish -c Release -r <rid> --self-contained true`
- - 发布（AOT）：上述命令 + `/p:PublishAot=true` 及对应的裁剪参数
+ ## 关键依赖
+ - **框架**: .NET 10.0
+ - **GUI**: Avalonia 11.3.10, CommunityToolkit.Mvvm 8.4.0
+ - **CLI**: System.CommandLine 2.0.8
+ - **MCP**: ModelContextProtocol 1.3.0
+ - **HTTP**: Refit 9.0.2
+ - **AI**: Microsoft.Extensions.AI.OpenAI
+ - **Markdown**: Markdig 0.44.0
+ - **图片处理**: SixLabors.ImageSharp 3.1.12
+ - **加密**: System.Security.Cryptography.ProtectedData 10.0.1
## 编码规范
- - 命名空间：`StarBlogPublisher.Services`, `StarBlogPublisher.ViewModels`, `StarBlogPublisher.Views`, `StarBlogPublisher.Models`
+ - 命名空间保持一致：`StarBlogPublisher.Models`, `StarBlogPublisher.Services`, `StarBlogPublisher.Services.Application`
- 语言版本：C# default（latest minor）
- Nullable：enable
- - 使用 Avalonia Compiled Bindings (AvaloniaUseCompiledBindingsByDefault=true)
- - MVVM 模式：CommunityToolkit.Mvvm [RelayCommand] + [ObservableProperty]，部分窗口使用 ReactiveUI
+ - GUI 使用 Avalonia Compiled Bindings
+ - MVVM 模式：CommunityToolkit.Mvvm [RelayCommand] + [ObservableProperty]
+
+ ## 版本发布
+ - CI/CD 触发格式：`v*.*.*` 标签
+ - 编译目标：win-x64, linux-x64, osx-x64
+ - 当前框架目标为 net10.0