内容
# 技能宝库 Qu@ntum
**面向开发者和 AI 代理的本地优先知识操作系统。**
在单个可移植的 Go 二进制文件中存储、搜索和检索提示、技能、工作流程、决策、项目记忆、会话摘要和长 AI 输出。
```
_____ _ _ _ __ __ _ _
/ ____| (_) | | \ \ / /__ _ __ | |__ ___| |
| (___ | | | | | \ \ / / _ \ '_ \| '_ \ / _ \ |
\___ \| | | | | \ V / __/ | | | |_) | __/ |
____) |_|_| | | \_/ \___|_| |_|_.__/ \___|_|
|_____/ |_|
```
**代号：** Qu@ntum
**状态：** v3 — 工作流程执行 + 服务强化
**二进制文件大小：** ~7 MB
**依赖：** 零框架。仅 `modernc.org/sqlite`。
**语言：** Go 1.25+
---
## 文档
| 指南 | 描述 |
|-------|-------------|
| [`docs/quickstart.md`](docs/quickstart.md) | 安装、初始化和前 6 步，5 分钟完成 |
| [`docs/commands.md`](docs/commands.md) | 完整的 CLI 参考 — 所有命令和标志 |
| [`docs/vars.md`](docs/vars.md) | 变量检测、元数据和注入指南 |
| [`docs/mcp.md`](docs/mcp.md) | MCP 服务器设置，用于 Claude Code / OpenCode |
| [`docs/tutorial.md`](docs/tutorial.md) | 实际工作流程：项目 → 技能 → 上下文 → 会话 |
| [`docs/architecture.md`](docs/architecture.md) | 清洁架构深入解析、数据流和设计决策 |
---
## 痛点问题
与 AI 编码代理合作会带来重复的摩擦：
**提示和技能** 分散在聊天、文件、工具和 GitHub 仓库中。
**代理 overload** 如果每个技能都全局安装。
**长 AI 输出** （PDF 分析、规格、报告）有价值但污染上下文，如果保存到提示中。
**项目决策** 在会话之间被遗忘。
**工作流程缺少步骤** 当没有可重用的检查清单时。
**上下文** 要么太少，要么太多 — 永远不是合适的数量。
技能宝库通过成为代理所需的一切的**本地真相来源**来解决这个问题，并为人类和 AI 设计了检索功能。
---
## 创新：Qu@ntum 上下文层
大多数保险库只是存储东西。技能宝库 Qu@ntum **在代理需要时提供合适的上下文**。
- **7 种上下文模式** — 配置文件、项目、工作流程、技能、规划、会话回忆、全简报
- **基于优先级的编译** — 用户反馈 > 项目状态 > 决策 > 工作流程 > 会话 > 工件摘要 > 引用
- ** token-aware 截断** — 尊重 `max_chars`，首先删除优先级最低的部分
- **输出**：干净、结构化的文本，准备好进行代理注入：
```
# 上下文包
## 范围
项目：MyApp
模式：规划
## 用户偏好
- 优先考虑实用架构
- 对核心领域行为使用 TDD
## 活动决策
- 使用 SQLite 进行本地存储
- v1 中不进行云同步
## 建议的下一步
根据规范生成实现计划。
```
---
## 安装
```bash
# 先决条件：Go 1.26+
git clone https://github.com/QuantumEdu/kbs
cd kbs
# 构建（单个二进制文件，无 CGO）
go build -o ~/tools/skillvault ./cmd/skillvault
# 初始化保险库
skillvault init
# 验证
skillvault version
```
就这样。一个二进制文件。没有守护进程，没有数据库服务器，没有框架。
---
## 快速入门
```bash
# 创建一个项目
skillvault add-project --name "MyApp" --description "我的应用程序"
# 保存可重用的技能
skillvault add-entry \
--title "清洁架构审查" \
--type skill \
--summary "审查清洁架构合规性的检查清单" \
--project myapp \
--tags "architecture,review"
# 搜索您的保险库
skillvault search "architecture"
# 将长 AI 输出保存为工件（存储在磁盘上，索引在数据库中）
skillvault save-artifact \
--title "PDF 分析 - 安全审计" \
--type pdf_analysis \
--content "$(cat /tmp/long-analysis.md)" \
--project myapp \
--tags "security,audit"
# 为您的代理获取紧凑的上下文
skillvault get-context --mode planning --project myapp --max-chars 5000
# 用决策结束会话
skillvault session-wrap \
--project myapp \
--summary "审查身份验证中间件" \
--decisions "使用 JWT，不使用会话" \
--pending "添加刷新令牌轮换"
```
---
## 架构
### 核心原则
```
数据库决定。磁盘记住。Qu@ntum 交付。
```
- **数据库决定**：存在什么，什么类型，状态，关系，如何找到它（SQLite + FTS5）。
- **磁盘记住**：长工件，AI 输出，规格，报告存储为 `objects/YYYY/MM/` 中的文件。
- **Qu@ntum 交付**：为代理编译紧凑、过滤、按优先级排序的上下文。
### 包映射
```
cmd/skillvault/
├── internal/cli/ # 21+ CLI 命令（标准库，无 Cobra）
├── internal/mcp/ # 16 个 MCP 工具，通过 stdio JSON-RPC 2.0
├── internal/api/ # HTTP API（仅本地）
├── internal/app/ # 用例：保存、搜索、上下文、会话、引用、内存、管道
├── internal/domain/ # 纯实体 + 验证器
├── internal/db/ # SQLite + FTS5（8 个存储 + 2 个迁移）
├── internal/files/ # 工件文件系统（objects/YYYY/MM/）
├── internal/context/ # Qu@ntum 上下文编译器（7 种模式）
├── internal/security/ # 机密扫描器（4 个正则表达式模式）
├── internal/vars/ # 变量检测 + 注入 + 元数据解析器
├── internal/export/ # 导入/导出，具有冲突解决
└── internal/api/ # HTTP REST 服务器
```
### 存储布局
```
~/.skillvault/
├── vault.db # SQLite + FTS5（元数据、搜索、关系）
├── objects/ # 长工件文件
│ └── YYYY/MM/
│ └── <slug>.<ext> # 通过 SHA256 内容寻址
├── exports/ # JSON 导出
└── cache/ # 临时缓存
```
**规则**：内容放入数据库时需小且频繁检索。内容放入文件系统时需长，或最终文档，或值得保存的 AI 输出。
---
## CLI 命令
| 命令 | 描述 | 示例 |
|---------|-------------|---------|
| `init` | 创建保险库目录 + 数据库 | `skillvault init` |
| `add-entry` | 保存可重用条目 | `skillvault add-entry --title "..." --type skill --summary "..."` |
| `search` | FTS5 搜索，带过滤器 | `skillvault search "auth" --type skill --project myapp` |
| `get` | 按 ID 或 slug 获取条目 | `skillvault get clean-architecture-review` |
| `save-artifact` | 保存长文件备份工件 | `skillvault save-artifact --title "..." --type pdf_analysis --file report.md` |
| `save-result` | 将 AI 结果保存为保险库条目 | `skillvault save-result --name "result" --content "..."` |
| `get-context` | 编译 Qu@ntum 上下文包 | `skillvault get-context --mode planning --project myapp` |
| `add-project` | 创建项目 | `skillvault add-project --name "MyApp" --description "..."` |
| `list-projects` | 列出所有项目 | `skillvault list-projects` |
| `archive` | 存档条目 | `skillvault archive clean-architecture-review` |
| `add-workflow` | 创建工作流程（JSON 文件） | `skillvault add-workflow workflow.json` |
| `render-workflow` | 将工作流程渲染为检查清单 | `skillvault render-workflow spec-plan-task` |
| `run` | 执行工作流程管道，逐步 | `skillvault run research-article article.md --save output.md` |
| `session-wrap` | 保存会话和决策 | `skillvault session-wrap --project myapp --summary "..." --decisions "d1,d2"` |
| `graph` | 可视化条目图 | `skillvault graph --entry e1 --format mermaid` |
| `ref` | 管理图边（别名） | `skillvault ref add e1 e2 depends_on` |
| `entry ref add/list/remove` | 管理图边 | `skillvault entry ref add e1 e2 depends_on` |
| `memory index/reindex/list-external` | 索引 pi-memory.md 文件 | `skillvault memory index --path ~/memory --project myapp` |
| `export` | 将保险库导出为 JSON | `skillvault export vault.json` |
| `import` | 从 JSON 导入保险库 | `skillvault import vault.json` |
| `version` | 显示保险库版本 | `skillvault version` |
| `compare-entries` | 两个条目之间的向量相似性 | `skillvault compare-entries e1 e2` |
---
## MCP 工具（16 个）
适用于 AI 代理（Claude Code、OpenCode 等）：
| 工具 | 描述 |
|------|-------------|
| `save_entry` | 保存提示、技能、决策、反馈、会话 — 任何可重用的内容 |
| `search_entries` | 按类型、项目、标签、状态进行 FTS5 搜索 |
| `get_entry` | 通过 ID 检索条目，并附上工件引用 |
| `save_artifact` | 将长 AI 输出保存为文件备份工件，并附上元数据 |
| `save_result` | 将 AI 提示结果保存为保险库条目 |
| `get_context` | 编译适用于代理的上下文包（7 种模式） |
| `compose_series` | 获取系列中的有序条目 |
| `render_workflow` | 获取工作流程步骤作为有序检查清单 |
| `session_wrap` | 创建包含决策、待办事项、学习内容的会话条目 |
| `archive_entry` | 将条目状态设置为存档 |
| `list_projects` | 列出所有项目及其状态 |
| `save_entry_ref` | 在两个条目之间创建/更新图边（具有环检测） |
| `list_entry_refs` | 列出图边及其过滤器 |
| `get_entry_graph` | 从起始条目遍历条目图 |
| `search_by_tags` | 按标签交集（全部）或并集（任意）搜索条目 |
| `get_context_bundle` | 获取具有按类型分组条目的结构化项目上下文包 |
### MCP 设置（Claude Code / OpenCode）
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"skillvault": {
"command": "/path/to/skillvault",
"args": ["mcp"]
}
}
}
```
为代理专用访问创建符号链接：
```bash
ln -sf ~/tools/skillvault ~/tools/mcp
# 现在代理可以直接调用 "mcp"
```
---
## 实体模型
### 条目类型（11 种）
| 类型 | 目的 |
|------|---------|
| `prompt` | 可重用提示模板 |
| `skill` | 结构化技能/模式 |
| `workflow_note` | 关于工作流程的笔记 |
| `reference` | 参考文档 |
| `user` | 用户偏好 |
| `feedback` | 用户反馈/决策 |
| `project_state` | 项目快照 |
| `session` | 会话摘要 |
| `decision` | 架构决策 |
| `artifact_summary` | 存储工件的摘要 |
| `handoff` | 会话移交文档 |
### 状态模型
| 状态 | 含义 |
|--------|---------|
| `draft` | 尚未准备好供代理使用 |
| `active` | 可用于正常检索 |
| `archived` | 可搜索但从上下文包中排除 |
| `deprecated` | 保留用于历史，不推荐 |
| `canonical` | 首选版本 |
### 关系（EntryLink — 11 种）
条目可以通过具有环检测的有向图显式关联：
```
references → 链接到支持内容
supersedes → 更新版本取代旧版本（易出现环）
related_to → 松散连接
part_of → 组合关系（易出现环）
derived_from → 源 → 导出的关系
implements → 实现规范/决策
uses → 源调用目标（代理使用工作流程）
extends → 源专门化目标
handoff_of → 移交条目引用会话工作
generated_from → 条目从另一个条目导出
depends_on → 源依赖目标（易出现环）
```
**环检测**：`depends_on`、`part_of` 和 `supersedes` 在插入前使用 `WITH RECURSIVE` CTE 验证反对传递环。最大深度：10。
**遍历**：`GetEntryGraph` 支持多方向（`outgoing|incoming|both`）遍历，带有可配置的深度。CLI：`skillvault graph --entry <id>`。
**内存索引**：来自 pi-memory-md 的影子条目通过 `external_ref` 自动链接。Markdown 正文中的 Wikilinks（`[[target]]`）成为 `related_to` 边。
---
## 安全
技能宝库在机密进入保险库之前检测并阻止：
| 模式 | 示例 |
|---------|---------|
| OpenAI 密钥 | `sk-...` （20+ 个字符） |
| 私钥 | `-----BEGIN PRIVATE KEY-----` |
| GitHub 令牌 | `ghp_...` |
| Slack 令牌 | `xoxb-...` 、 `xoxa-...` |
检测到后：内容被**拒绝**或**编辑**并发出警告。不会存储任何机密。
---
## 用户流程
### 1. 从 AI 代理保存 PDF 分析
```
用户 → "将此分析保存到 SkillVault 作为数字取证项目的工件"
代理 → 调用 save_artifact(title, type=pdf_analysis, content, project)
SkillVault → 将文件存储在 objects/2026/06/forense-analisis.md 中
→ 创建工件元数据 + 数据库中的条目
→ 在 FTS5 中索引摘要 + 标签
```
### 2. 代理检索规划上下文
```
代理 → 调用 get_context(project="MyApp", mode="planning", max_chars=8000)
SkillVault → 编译：用户偏好 + 项目状态 + 决策 + 工作流程
→ 截断优先级最低的部分以适应 8000 个字符
→ 返回结构化文本以注入代理
```
### 3. 项目连续性的会话包装
```
用户 → "结束会话，保存我们的决定"
代理 → 调用 session_wrap(project, summary, decisions[...], pending[...], learnings[...])
SkillVault → 创建会话条目 + 可选工件
→ 链接到项目
→ 可用于下一次 get_context 调用
```
---
## 比较
| 功能 | 文件系统 | GitHub Gists | Obsidian | SkillVault |
|---------|-------------|-------------|----------|------------|
| 代理面向的 MCP | ❌ | ❌ | ❌ | ✅ |
| FTS5 搜索 | ❌ | ❌ | ❌ | ✅ |
| 上下文编译 | ❌ | ❌ | ❌ | ✅ （Qu@ntum） |
| 混合数据库 + 磁盘 | ❌ | ❌ | ❌ | ✅ |
| 机密检测 | ❌ | ❌ | ❌ | ✅ |
| 工作流程检查清单 | ❌ | ❌ | ❌ | ✅ |
| 工作流程管道 | ❌ | ❌ | ❌ | ✅ （v3） |
| 单个 10MB 二进制文件 | ❌ | ❌ | ❌ | ✅ |
| 零云依赖 | ✅ | ❌ | ❌ | ✅ |
| 可移植（任何操作系统） | ✅ | ❌ | ❌ | ✅ |
| 条目关系 | ❌ | ❌ | ❌ | ✅ |
---
## 测试
```bash
# 运行全部 400+ 测试
go test ./...
# 带有覆盖率
go test -cover ./...
# 集成测试使用内存 SQLite（无需文件系统）
```
测试金字塔：
- **单元测试**：领域验证、安全模式、变量检测
- **集成测试**：SQLite 存储、工件文件系统、MCP 工具
- **验收测试**：完整的端到端流程（AC1-AC10）
---
## 依赖
- **Go 1.26+** — 标准库，用于 CLI、HTTP、JSON、文件 I/O、加密、嵌入
- **`modernc.org/sqlite`** — 纯 Go SQLite 驱动（无 CGO）
**零框架**。无 Cobra、无 Fiber、无 ORM、无 Gin、无 Echo。
---
## 项目状态
| 阶段 | 状态 |
|-------|--------|
| v1-alpha（SQLite 保险库） | ✅ 已存档 |
| v2 Qu@ntum（混合 + 上下文） | ✅ 已存档 |
| v3 Qu@ntum（工作流程管道） | ✅ 活跃 |
| v3 服务强化（身份验证、关闭、MCP 工具） | ✅ 活跃 |
| 云同步（S3 + GitHub 传输） | ✅ 活跃 |
| TUI（Bubble Tea，构建标签门控） | ✅ 活跃 |
| 向量搜索（GloVe，纯 Go） | ✅ 活跃 |
| 条目差异 / 比较条目 | ✅ 活跃 |
| 条目版本控制（历史、恢复、差异 API） | ✅ 活跃 |
| 条目技能包导出 | ✅ 活跃 |
| HTTP 身份验证层 | ✅ 活跃 |
| 正常关闭 | ✅ 活跃 |
| 保存结果 MCP 工具 | ✅ 活跃 |
---
## 许可证
MIT
