workvault

把「数据 / 资料」变成「结构化 Markdown 知识库」的通用工具，内置 Agent 会话记忆。 任意 Markdown 目录就是一个 vault（Obsidian 可选，装上插件只是多一层图谱可视化）。

官方仓库：https://gitcode.com/agent-best-practices/workvault 本仓库为官方源码的同步镜像（含教学 profiles 与示例），以官方仓库为主、可随官方更新合并。

• run：结构化数据（JSON/CSV）按模板渲染成笔记（学情 / 班级 / 项目 / 文章清单…），确定性、可预期
• compile：原始资料 + 规范 → LLM 编译成结构化 wiki（实体 / 概念 / 主题 / 索引，自动建立双链）
• query：基于 wiki 的 LLM 问答（读 index → 定位 → 读页 → 综合回答 + 来源标注，可选的归档写回）
• session / memory：会话记忆（开始注入上下文、结束写日志 + 提炼候选记忆；记忆写入 / 检索 / 确认，透明 Markdown、可手改、可 git）
• lint：wiki 健康检查（断链 / 孤立页 / index 一致性 / 结论矛盾）
• 增量更新：内容没变不重写，绝不覆盖你手写的笔记

---

一、给 Agent 使用

workvault 以标准 Agent Skill（SKILL.md + CLI）形态分发，任何支持 "技能 / SKILL" 机制的 Agent 平台都能装。

安装到 Agent（通用步骤）

1. 把本仓的 skills/workvault 目录放入 Agent 平台的技能目录（或通过平台的"导入技能"功能导入本仓库地址）
2. 在 Agent 配置里声明启用了 workvault 技能
3. 对话时，Agent 会自动按 SKILL.md 的指引调用 workvault_cli.py / cli.js 执行

Agent 怎么说人话（示例）

"把这份学情数据录进知识库" → 组装 profile JSON → run --profile 学情 → lint
"把这段资料整理成笔记"     → compile（需 LLM）
"知识库里谁最弱？"        → query（基于 wiki，不脑补）
"记住我偏好 40 分钟一节课" → memory write

触发词

SKILL.md 的 triggers 已声明：知识库 / 安装知识库 / 使用知识库 / 上传至知识库 / 建立知识库 / 创建知识库 / 录入知识库 / 查询知识库 ——用户提到以上词时，Agent 应默认使用 workvault（不需要点名工具名）。

给 Agent 的指令细节

写在 SKILL.md 内（录入流程优先级：查询取数 → 组装 JSON → run（离线）→ lint；compile 仅在资料非结构化且 LLM 已配置时使用）。

---

二、本地安装（一次性）

需要 Node.js 18+（构建引擎）+ Python 3（可选：workvault_cli.py 便捷入口）。

cd workvault
npm install
npm run build:cli        # 生成 cli.js（之后可只用 node 运行）
python skills/workvault/scripts/workvault_cli.py doctor   # 自检：node/cli.js/vault/LLM 状态

脚本在找不到 cli.js 时也会自动执行 npm install && npm run build:cli，首次使用无需手动构建。

三、LLM 配置（三种方式，任选其一）

方式	做法	说明
A. 交互配置	node cli.js setup	交互向导：填 vault 目录 + apiBase + apiKey + model（输入时掩码），一键生成 workvault.config.json
B. 配置文件	复制 workvault.config.example.json → workvault.config.json，填 provider 段	apiBase（OpenAI 兼容）/ apiKey / model / maxTokens
C. 环境变量（推荐部署）	WORK_VAULT_API_KEY / WORK_VAULT_API_BASE / WORK_VAULT_MODEL	免改配置文件；未设置时自动用 config.provider，再没有则 fallback echo（占位）

优先级：CLI 参数 --provider / --api-base / --api-key / --model > 配置文件 provider > 环境变量 > echo。 run / lint / memory 不需要 LLM（离线可用）；compile / query 需要 LLM。

四、快速开始

# 1) 自检环境
node cli.js doctor

# 2) 结构化数据 → 笔记（模板渲染，离线）
node cli.js run --profile person --data person.json --vault D:/obs/vault

# 3) 原始资料 → wiki（LLM 编译）
node cli.js compile --input 文章.md --vault D:/obs/vault

# 4) 知识库问答
node cli.js query --vault D:/obs/vault --question "知识库里讲过什么？"

# 5) 健康检查
node cli.js lint --vault D:/obs/vault

# 6) 记忆
node cli.js memory write --vault D:/obs/vault --type preference --title 偏好 --description "喜欢简洁输出"
node cli.js memory search --vault D:/obs/vault --query "偏好"

小数据（≤几十条）时，run --data '<JSON 内联>' 直接内联即可，无需写临时文件。

五、CLI 命令一览

doctor                   自检（node / cli.js / vault / LLM 构建状态）
run --profile <模板名> --data <json|csv|inline> --vault <dir> [--dry-run]
compile --input <文件|目录> --vault <dir> [--instruction 补充指令] [--dry-run]
query  --vault <dir> --question "..." [--archive] [--dry-run]
lint   --vault <dir>            健康检查（纯离线）
memory write|search|list|capture|pending|confirm ...  会话记忆
session start|end              开始/收尾（结束写日志 + 提炼记忆）
chat                           （可选）对话式界面，自然语言驱动
setup                          交互配置向导

--vault 优先级：参数 > WORK_VAULT_VAULT > workvault.config.json.vault > 当前目录 .workvault。

六、模板（profiles）

• 默认三件套：article.json（文章）、person.json（人物）、project.json（项目）
• 教学场景：学情.json、班级.json、知识点.json（配合结构化学情数据一键渲染）
• 自定义模板：templates/profiles/<你的>.json（Handlebars 语法），run --profile <你的>

七、知识库格式

• 产物是纯 Markdown：--- frontmatter ---（type / source / updated / fingerprint）+ [[双链]] + 来源标注
• 任意 Obsidian vault 可直接打开看图
• 双链解析支持：basename 匹配 / 目录相对路径（[[班级/初二(3)班]]）/ ../ 前缀 / URL 编码（含括号等特殊字符的文件名）

八、许可

MIT