Skip to content

CLAUDE.md

Latest commit

 

History

History
172 lines (125 loc) · 6.37 KB

CLAUDE.md

File metadata and controls

172 lines (125 loc) · 6.37 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

KnowCompile — Electron 桌面应用，AI 驱动的资料编译器，将 PDF/Markdown/文本编译为结构化 Wiki。

核心理念：一次编译，永久复用（Compile once, reuse forever）。知识库随使用越来越聪明。

技术栈：Electron + React 19 + TypeScript + Vite + Tailwind CSS + SQLite (better-sqlite3) + LanceDB + bge-m3 (ONNX)

常用命令

# 开发
npm run dev                # Vite + Electron 热重载开发（端口 5199）
npm run build              # 生产构建
npm run pack               # 打包为目录（调试用）
npm run dist               # 打包为安装程序

# 测试
npm test                   # 全量测试（后端 + 渲染层，约 5-8 分钟）
npx vitest run src/        # 仅渲染层测试（jsdom，约 30 秒）
npx vitest run tests/      # 仅后端测试（node 环境）

# 跳过 LLM 集成测试（快速单元测试）
npx vitest run --exclude='tests/llm-service*' --exclude='tests/compile-pipeline*' --exclude='tests/qa-pipeline*' --exclude='tests/compile-service*'

# 运行单个测试文件
npx vitest run tests/qa-pipeline.test.ts --test-timeout=300000

# 编译提示词质量评审
npx tsx tests/compile-prompt-review.ts <kbPath> [rawFile1 rawFile2 ...]

架构

双进程模型

electron/           # 主进程（Node.js + 原生模块）
  main.ts           # 入口，窗口管理
  preload.ts        # contextBridge IPC 白名单
  ipc-handlers.ts   # 所有 IPC 处理器注册（~1200 行，应用的调度中心）
  llm-service.ts    # LLM 调用（chat, chatStream, compileNewPages）
  qa-service.ts     # 问答管道（semanticQA, semanticQAStream, buildContext）
  compile-service.ts # 编译管道（incrementalCompile, reviewContent）
  embedding-service.ts # bge-m3 嵌入（ONNX 工作线程）
  vector-db.ts      # LanceDB 封装
  index-db.ts       # SQLite 封装（better-sqlite3）
  llm-store.ts      # LLM 配置管理（多供应商、场景配置）
  prompt-engine.ts  # Prompt 模板引擎（加载、渲染、变量插值）
  prompt-defaults.ts # 10 个内置默认 Prompt 模板

src/                # 渲染进程（React + Tailwind）
  App.tsx           # 根组件，视图路由
  views/            # 7 个主视图：QAView, IngestView, WikiView, SettingsView, GraphView, SystemView, LogViewer
  components/       # UI 组件（含 LLMManager.tsx, PromptTemplateManager.tsx）
  hooks/useIPC.ts   # IPC 类型化封装

IPC 通信

所有主进程 ↔ 渲染进程通信通过 preload.ts 白名单控制。新增 IPC 通道必须：

  1. 在 preload.ts 的 ALLOWED_CHANNELS 中注册
  2. 在 src/test-utils/mock-ipc.ts 中添加 mock
  3. 在 src/hooks/useIPC.ts 中添加类型化方法

流式问答通道：

qa:ask-stream (invoke) → 启动流式问答
qa:token      (on)     → 每个 token 推送
qa:token-end  (on)     → 流完成

LLM 配置通道：

llm:get-config, llm:save-config, llm:add-provider, llm:update-provider
llm:delete-provider, llm:test-connection, llm:get-scenario, llm:update-scenarios

Prompt 模板通道：

prompt:list-templates, prompt:get-template, prompt:save-template
prompt:reset-template, prompt:render-preview

数据架构

你的知识库/
├── raw/                    # 原始资料（LLM 编译的原料）
├── wiki/                   # LLM 编译的知识页面（Markdown，扁平 + 双向链接）
├── schema/                 # AI 行为规则（人类可编辑，控制编译和文风）
│   └── prompts/            # Prompt 模板（每个模板一个目录，含 meta.json + .md 消息文件）
├── .index/                 # 索引层（可随时删除重建）
│   ├── pages.db            # SQLite 元数据
│   └── vectors.lancedb/    # LanceDB 向量索引
└── .ai-notes/              # 应用元数据（对话、日志、分析）

关键约束：raw/、wiki/、schema/ 是唯一真相来源。所有索引可从这三个目录完全重建。

核心管道

  1. 编译管道：raw/ → 分块 → bge-m3 向量化 → LanceDB 语义搜索 → LLM 生成 CompilePlan → LLM 生成页面 → 内容审查 → 写入 wiki/
  2. 问答管道：问题 → bge-m3 嵌入 → 混合检索（向量 + 关键词）→ RRF 融合 → LLM 流式生成 → 行内引用
  3. 索引重建：从 wiki/ + raw/ 完全重建 SQLite + LanceDB（确定性操作）

测试架构

两层测试环境

层 位置 环境 需要 LLM？ 需要 embedding？
后端测试 tests/*.test.ts node 部分 部分
渲染层测试 src/*.test.{ts,tsx} jsdom 否 否

渲染层测试模式

组件测试不依赖 Electron，通过 mock IPC 工厂隔离：

// src/test-utils/render.tsx - 组件测试入口
import { render } from '@testing-library/react'
import { createMockIPC } from './mock-ipc'

// 自动 stub window.electronAPI
;(window as any).electronAPI = createMockIPC()

// 测试组件
render(<MyComponent />)

createMockIPC(overrides?) 返回所有 IPC 方法的 vi.fn() mock，可通过 overrides 参数定制返回值。

LLM API 配置

测试读取 %APPDATA%/knowcompile/settings.json，也可用环境变量覆盖：

export KNOWCOMPILE_API_KEY="sk-..."
export KNOWCOMPILE_PROVIDER="openai"
export KNOWCOMPILE_BASE_URL="https://..."
export KNOWCOMPILE_MODEL="gpt-4o"

关键模式

  1. IPC 白名单：所有 IPC 通道必须在 preload.ts 注册，否则渲染进程调用会被阻止
  2. 测试隔离：组件测试通过 createMockIPC() 完全隔离，不依赖真实 Electron 环境
  3. 增量编译：编译管道基于 SHA-256 哈希检测变更，只处理新增/修改的 raw 文件
  4. 多 LLM 配置：支持多个 LLM 供应商，为编译、问答、内容审查三个场景分别配置
  5. 向量 + 关键词混合检索：问答管道使用 RRF 融合 LanceDB 向量搜索和 FlexSearch 关键词搜索
  6. Prompt 模板系统：所有 LLM prompt 通过模板引擎管理（prompt-engine.ts），模板以 Markdown 文件存放在 schema/prompts/，支持 {{variable}} 变量插值和 {{#array}} 循环

版本历史

详见 CHANGELOG.md

当前版本：v0.4.0