# skg

**Repository Path**: suwubee/skg

## Basic Information

- **Project Name**: skg
- **Description**: 智能知识管理软件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SKG 0.5.6 · 本地 Markdown 知识库

**0.5.6 更新：** 文件列表可拖动调整宽度，缩放仍仅影响右侧正文；点击文件复用当前标签，「＋」创建空标签；检索片段提供一致的 Markdown 预览与源码；关系提炼按模型上下文分段、失败段重试并保留有效候选。笔记问答支持继续取证，但 MiniCPM 的具体名单回答仍有误判，尚未通过真实问答质量验收。详情见 [0.5.6 发布说明](docs/0.5.6发布说明.md) 与 [工作流实测](docs/AI工作流性能与分段.md)。

**0.5.5 更新：** 左侧新增独立的全局关系图谱，中央画布展示仓库中的链接、标签、实体提及和已确认 AI 关系。受控笔记问答增加可关闭的短期对话记忆，承接用户追问并重新读取原文证据。发布包、容量与验证边界见 [0.5.5 发布说明](docs/0.5.5发布说明.md)。

**把笔记留在自己的文件夹里，离线写作、搜索，需要时再启用 AI。** SKG 意为“小的知识管理软件”，面向个人笔记、项目资料和本地知识整理。

## 可以做什么

| 场景 | 功能 |
| --- | --- |
| 日常写作 | Markdown 源码、即时、分栏和阅读模式；表格编辑、任务列表、代码块预览与复制、Mermaid |
| 整理文件 | 真实目录、拖放和点击导入、右键导出与定位；自动发现工作区里的外部文件变更 |
| 工作区 | 无弹框新建、重名自动编号、文档/附件多标签、实际文件路径与多仓库管理 |
| 关联笔记 | 链入链出、实体与别名、原文证据；局部关系图支持点击导航、平移和缩放 |
| 阅读资料 | 在同一内容区预览 PDF、HTML、DOCX、XLSX、PPTX；Office 为内容预览，不还原复杂排版 |
| 查找内容 | 离线全文搜索；可选向量模型，启用语义或混合检索 |
| AI 辅助 | 流式聊天、停止生成、上下文预算、可选笔记检索；本地 GGUF 或兼容 API，对话与向量分别配置 |
| 舒适阅读 | 亮色、暗色主题；编辑区域独立缩放；全文及选区字符、词、行统计 |
| 数据掌控 | Markdown 原件与 SQLite 保存在自选工作区；模型和运行组件由用户手动下载 |

**0.5.3 更新：** 新增无弹框创建、轻量多标签、多仓库管理和「笔记助手 → 关系图谱」局部可视化。该发布包图谱基于文档链接、实体提及和标签，尚未提供 AI 自动事实关系抽取。详情及验证范围见[0.5.3 发布说明](docs/0.5.3发布说明.md)。

**AI 整理与受控检索（本包包含）：** 「笔记助手 → AI 整理」支持选中文字或整篇处理、自动分段摘要与润色、AI 关系提炼及原文证据确认。无需手写链接语法或启用向量模型。操作见 [AI 整理与关系提炼](docs/AI整理与关系提炼.md)；原生 tools、JSON 兼容与范围控制见 [Harness 实现与验证](docs/Harness实现与验证.md)。

## 三分钟开始

工作区设计见[工作区交互与多仓库方案](docs/工作区交互与多仓库方案.md)。新功能复用现有编辑器、SQLite 和窗口，不增加运行依赖。

1. 解压适合系统和架构的发布包；Windows 双击 `skg.exe`，Linux/macOS 使用包内启动器。各平台要求见下文。
2. 首次启动选择工作区，确认实际存储位置。笔记、索引和按需下载的模型统一在这里管理。
3. 左侧新建笔记，或将已有 `.md` 文件拖入目标目录；也可点击导入文件、文件夹。
4. 顶部选择编辑模式，直接修改正文；标题旁查看自动保存状态。右键左侧文件可导出或打开所在位置。
5. 先用全文检索查找内容；需要聊天或语义检索时再打开「AI 设置」。基础笔记功能无需模型。

首次进入空库会创建一篇[欢迎笔记](frontend/content/welcome.md)，介绍常用操作和备份。已有笔记不会被这份默认内容覆盖。

## 数据与备份须知

笔记原文在 `vault/`，设置、索引及人工实体记录在 `data/`。**退出软件后至少备份这两个目录**；复制整个工作区可同时保留下载的模型和运行组件。文档 JSON 导出不能代替完整工作区备份。

直接放入文档库的 Markdown 应为 UTF-8，单文件不超过 4 MiB。页面约每 5 秒检查外部变更；异常文件在「目录同步」中提示。浏览器缓存保存偏好和未落盘草稿，清缓存不会删除已经保存的笔记。

AI 为可选功能：使用远程接口时，对话及检索选中的笔记片段会发送给所配置的服务。聊天记录目前只保留在当前页面，刷新会清空；需要长期保存的回答请主动追加到笔记。

## 实现与维护

Go 主程序、实体 Markdown 文件夹、SQLite 索引。支持按需下载 llama.cpp 运行组件和魔搭 GGUF 模型，客户包不预置任何对话模型、向量模型或运行组件。

SKG：小的知识管理软件。维护入口：[代码与容量清单](docs/代码与容量清单.md)、[目录与维护规范](docs/文件治理与维护规范.md)、[文档索引](docs/README.md)。SVG 标识使用一页笔记、字母 K 和书签圆点；Windows EXE、窗口、任务栏与通知区域使用同源多尺寸 ICO。

## 运行与发布

本工作区双击根目录 `启动SKG.cmd`。发布包命名为 `dist/skg-<版本>-<平台>-<架构>.zip`，包括 Go 主程序、启动器、说明与第三方许可证；准确容量见 `dist/packages.json`。Windows、Linux、macOS 分别提供 amd64 / arm64，本版源码与六平台包统一为 0.5.6。版本统一由根目录 `VERSION` 管理，变更见 [CHANGELOG](CHANGELOG.md)。

完整解压到可写目录，Windows 直接双击 `skg.exe`（普通 Intel/AMD 电脑使用 windows-amd64 包）。优先使用 Go 原生 WebView2 窗口，支持按显示器 DPI 缩放；无 WebView2 时回退已安装的 Edge / Chrome 应用窗口。macOS/Linux 当前仍使用浏览器应用窗口；均可回退默认浏览器。Go 内嵌全部页面资源，不需要 Node，不附带 Chromium。`-browser` 强制用浏览器标签页，`-no-browser` 仅启动服务。其他工作区占用默认端口时自动选择空闲端口，同一工作区再次启动会打开原服务。

原生窗口缓存优先存于 `%LOCALAPPDATA%/SKG/webview-工作区标识`，按工作区隔离；不可写时尝试 `data/webview/`。只释放一个内置的小型 WebView2Loader.dll，不下载浏览器引擎。浏览器应用窗口仍使用 `data/ui/`。

Linux / macOS 先授予 `skg` 和启动器执行权限。基础编辑、渲染、全文搜索无需联网或安装推理依赖。

- `vault/`：实际 Markdown 文档、目录、附件及 `.skg` 管理信息。
- `data/`：`knowledge.db`、设置、日志与运行状态。
- `models/`：客户手动下载的模型及来源校验记录。
- `runtimes/`：客户手动安装的 llama.cpp，按平台和版本隔离。

首次双击先选择工作区，确认后才在选定目录内准备 `vault/`、`data/`、`models/`、`runtimes/`。完成页显示实际路径并支持打开文件夹；取消不会创建这些数据目录。下次直接沿用已选位置，磁盘不可用时重新引导，不静默新建替代库。可在「设置 → 文件与缓存」查看并打开位置。已存在的旧版 data/knowledge.db 继续沿用，不自动搬迁。

工作区位置优先记在程序旁的 `skg-workspace.json`；程序目录不可写时记在系统用户配置目录中，完成页显示记录路径。它只记录路径，不保存文档或模型。命令行可用 `-workspace 完整路径` 指定统一位置，或继续使用 `-data`、`-vault`、`-models`、`-runtimes` 定制目录；两种方式不能混用。全新无界面启动需明确指定位置。窗口缓存仍与文档分开：Windows 使用系统用户缓存，其他独立窗口使用 data/ui；首次引导使用临时缓存。

## 本地 AI：三步启用

1. 打开「AI 设置」浮层，在本地 AI 页点击「安装运行组件」。根据当前系统与 CPU 选择官方 llama.cpp b10970，下载后核对 SHA-256、解压并复用。不会在首次启动时自动安装。关闭浮层保留设置草稿和编辑位置，下载继续进行。
2. 选择「对话与写作」或「语义检索」，手动点击下载。也可展开选择其他魔搭仓库与 GGUF 文件。支持暂停、断点续传、完整性校验，下载失败不会作为可用模型发布。
3. 选择已下载模型，点击「加载并使用」。Go 在后台管理推理进程、动态本机端口和访问密钥，自动接入对应功能；停止模型释放资源。曾启用的模型会在下次启动时恢复加载。

默认目录仅列出下载选项，**权重没有进入发布包**：

设置现提供 **Qwen3.5 0.8B / 2B / 4B Q4** 与 **BGE M3 Q8**，根据 CPU 逻辑处理器和当前可用内存给出保守推荐。用户主动采用参数、下载和加载；新模型尚未做本机推理实测。下表为保留的既有选项，完整来源、文件大小与验证状态见 [模型目录与推荐规则](docs/模型目录与推荐规则.md)。

| 用途 | 魔搭仓库 | 文件 | 大小 |
|---|---|---|---|
| 对话、摘要、润色 | `OpenBMB/MiniCPM5-2B-GGUF` | `MiniCPM5-2B-Q4_K_M.gguf` | 1,561,318,368 字节 |
| 中文语义检索 | `fuyuantech/bge-small-q8-zh-v1.5` | `bge-small-q8-zh-v1.5.gguf` | 26,472,640 字节 |

向量模型只负责语义编码。加载 BGE 后，在「检索 / AI」点击「增量更新向量索引」，再使用语义或混合检索。每次先校验模型指纹，复用已完成的有效片段；文档修改后保留正文完全相同的片段向量。可停止任务，完成部分保留，下次继续增量更新。向量任务仍由用户手动启动。

Go 主程序可关闭 CGO 交叉编译；推理由匹配平台的现代 llama.cpp 预编译组件执行，无 Python、旧 go-llama 绑定或首次 C++ 编译要求。GGUF 适合此部署方式；Safetensors/PyTorch 权重不能直接加载到该引擎。运行组件压缩包约 11–18 MB，安装后约 47–70 MB（当前实测四种平台）；不把多个平台组件装入客户包。

「自定义接口」页仍支持远程或已有本机服务。填写完整 embeddings / chat completions 端点，远程使用 HTTPS；密钥在本机 SQLite 保存，读取时掩码显示。切换接口前先停止对应的受管理本地模型。

## 编辑与数据

- 顶部切换源码、即时、分栏和阅读；前三者共用 CodeMirror 6 编辑状态、选区和撤销历史。即时模式直接采用 [Atomic Editor](https://github.com/kenforthewin/atomic-editor) 0.6.2 的公开扩展和样式，替换自研即时渲染；保留紧凑标题间距和应用主题。
- 即时模式支持嵌套列表、续行对齐、任务复选框和 `---` 等分隔线；表格直接点击单元格编辑。跨行选择、中文输入、撤销和磁盘保存继续使用同一 Markdown 状态。`---` 紧接段落时遵循 Markdown 的二级标题下划线规则，作为分隔线时应在前面留空行。接入说明及测试见 [Atomic Editor 接入](docs/atomic-editor-integration.md)。
- 围栏代码块（包括 text、未知语言、未闭合围栏）提供浮层预览、复制代码和复制完整块；完整块保留语言标记及首尾围栏。代码里的 HTML 作为文本显示。图片、Mermaid 仍可通过片段预览、分栏或阅读查看。
- 左侧可删除、右键导出/复制/定位文件，拖动可移入目录、移回根目录及调整同级顺序。底部可拖入或点击选择文件、文件夹；文件夹保留文本目录层级，同名另存副本。单文件 4 MiB、每批约 24 MiB；不导入图片附件。
- 文档标题在右侧顶部直接修改，各视图均可访问。
- 表格支持拖选多个单元格、TSV 复制粘贴、Enter 插入下方行、Alt+Shift+方向键插入行列；右键可选择、删除、移动及对齐。编辑和撤销保留对齐信息，所有变更进入同一 CodeMirror 历史。
- PDF、HTML、DOCX、XLSX、PPTX 可从拖放或选择文件导入到左侧当前目录，同名不覆盖；直接复制到 vault 对应目录的文件也会随目录扫描显示。文件与 Markdown 共用一棵工作区树，可移动、重命名、删除、定位和点击预览。单次导入最大 64 MiB，较大文件可直接复制进文档库。
- PDF 复用浏览器/WebView2 阅读器；HTML 为隔离的静态预览；现代 Office 提供文字/表格内容预览，复杂版式、图片和图表请定位原件用 Office/WPS 查看。旧 DOC/XLS/PPT 显示明确的本地打开提示，不承诺内置排版。原件不上传云端。
- 保存状态在文档标题旁；「更多」集中复制、导出、备份、恢复、主题和帮助。窄屏仍可访问这些操作。
- 「检索 / AI」提供全文、语义、混合检索与写作辅助；快捷键 Ctrl / ⌘ + Shift + K。生成结果需主动追加到文档。
- 左侧「全局图谱」在中央工作区展示整个仓库的笔记关系（文档链接、#标签、实体提及、人工确认的 AI 关系），侧栏仍可操作；支持搜索、类型筛选、缩放平移与证据定位。进入前保存当前笔记，Esc 或「返回编辑」恢复编辑器。
- AI 面板默认展示聊天，输入框固定底部，支持 Markdown 回答、复制、追问、停止和新对话，窄屏适配。检索选项折叠，独立全文搜索仍可用。历史仅保存在当前页面，刷新清空，发送时携带最近 5 轮。
- 默认「普通对话」，可选择自动检索或始终查阅笔记。笔记问答优先使用经检测的原生 tools，并保留 JSON 动作回退；范围、只读工具、调用次数及上下文预算由 Go 控制，支持流式输出和原文证据定位。
- 「承接本轮对话」最多保留此前 3 条用户问题、共 600 字符，不把助手旧回答当作证据；切换范围或关闭记忆会重置承接边界。记忆只在本次页面对话中使用，刷新清空；见 [记忆设计与实测](docs/Harness对话记忆设计.md)。
- 设置顶部展示各模型的运行状态与停止按钮。已运行模型可重新加载或切换，缺少文件时按钮引导到安装/下载步骤。
- Obsidian 或其他编辑器可直接修改 vault。页面约 5 秒检查目录，编辑当前笔记时仍会发现其他文件；目录只传元数据和变化项，正文打开时读取。冲突时保留浏览器草稿，不覆盖磁盘原件。
- 单个超限、编码错误或无法读取的文件单独报告在左下角「目录同步」，不阻断正常笔记；以前读过的异常文件保留上次可读版本，禁止覆盖。忽略 .skg、.git、.obsidian 目录。单文件上限仍为 4 MiB，仅自动接入 UTF-8 .md 文件。
- CodeMirror 按视口渲染文档；约 132 万字符的测试只有 46 个行 DOM 节点。备份会显式读取全部正文，不受按需加载影响。
- 浏览器保存界面偏好和未落盘草稿。清理缓存不删除已保存的 Markdown；草稿恢复会创建独立文档。
- 文档 JSON 备份在「更多」菜单。完整备份请退出 SKG 后复制 vault 和 data；模型及组件可重新下载或一同迁移。
- Windows 原生窗口关闭时，仅在有模型已加载或正在加载时提示分别停用/保留；两个模型都未运行时保存文档并直接退出。可在「设置 → 文件与缓存」启用通知区域驻留，启用后窗口关闭按钮只隐藏窗口，双击右下角图标恢复，右键选择退出时仍执行前述模型检查。此选项默认关闭。
- 本地 AI 支持选择磁盘 GGUF，不复制文件。「提供模型接口」可设置端口、API Key、对话/向量模型名，默认仅本机，可主动切换局域网；只提供兼容推理 API，不开放笔记管理。

## 验证范围

Windows amd64 和 WSL Ubuntu 22.04 amd64 已验证真实 BGE GGUF 检索、MiniCPM Q4 中文摘要、停止与重启恢复。模型 SHA-256 已与魔搭核对。macOS Intel / Apple Silicon 组件已下载、校验 SHA-256 与 Mach-O 架构；缺少 Mac 实机推理测试、签名和公证。Windows/Linux arm64 仅完成主程序交叉编译与下载目录配置。

本版验证见 [0.5.6 发布说明](docs/0.5.6发布说明.md)，真实 MiniCPM / BGE 测试见 [本地模型实测](docs/本地模型实测.md) 与 [对话记忆验收](docs/Harness对话记忆设计.md)。历史回归保留在各版本记录中；Linux 原生组件此前在 glibc 2.35 环境验证，不将此结果泛化到 musl 或所有旧发行版。

## 开发

```powershell
$env:GOPROXY='https://goproxy.cn,direct'
.\.tools\go\bin\go.exe test ./...
.\.tools\go\bin\go.exe vet ./...
npm ci
npm run build
python scripts/integrate_editor.py
powershell -ExecutionPolicy Bypass -File scripts/build_windows_resources.ps1
powershell -ExecutionPolicy Bypass -File scripts/build.ps1 -All
python scripts/release_manifest.py
python scripts/package_release.py
```

已有依赖时可设 `GOPROXY=off`。Python 仅用于开发整合与浏览器测试，不进入客户包。原始 `离线markdown编辑器.html` 保持原文件；扩展位于 web、Go 服务与整合脚本。`config/runtime_catalog.json` 固定官方发布 URL、版本和校验值；升级该目录后重新验证并发布，不在客户机器静默升级推理组件。

Go 代码在 `internal/app`，程序入口为 `cmd/skg`（直接构建用 `go build ./cmd/skg`）；前端源码在 `frontend/src`，交互测试在 `tests`。新增文件后更新 `config/inventory_modules.json`，发布产物完成后运行 `python scripts/code_inventory.py` 与 `--check`。

CLI 也可显式触发安装和下载：

```sh
./skg -data ./data -runtimes ./runtimes -install-runtime
./skg -data ./data -models ./models -download-modelscope OpenBMB/MiniCPM5-2B-GGUF -download-file MiniCPM5-2B-Q4_K_M.gguf
```

官方来源：[llama.cpp b10970](https://github.com/ggml-org/llama.cpp/releases/tag/b10970)、[MiniCPM GGUF](https://modelscope.cn/models/OpenBMB/MiniCPM5-2B-GGUF)、[BGE GGUF](https://modelscope.cn/models/fuyuantech/bge-small-q8-zh-v1.5)。