xu-wiki

关系驱动的工程知识库 CLI 工具 — 给 AI 开的工具箱。

xu-wiki 不是给人看的文档库，而是给 AI Agent 的知识管理系统。Agent 通过 CLI 子命令操作知识库，不直写文件。CLI 只做确定性任务，语义决策由 Agent 完成。

架构

┌──────────────┐      CLI (JSON)      ┌──────────────┐
│   LLM Agent  │ ◄──────────────────► │   xu-wiki    │
│  (Hermes)    │    read .md files    │   (Python)   │
└──────────────┘                      └──────┬───────┘
                                      ┌──────┴───────┐
                                      │  SQLite + FS │
                                      └──────────────┘

安装

依赖

• Python 3.11+
• Hermes Agent

一键安装

# 方式 A：Git clone + 本地脚本（推荐）
git clone https://github.com/SadBoen/xu-wiki.git
cd xu-wiki
bash scripts/install.sh

# 方式 B：curl 直接执行
bash <(curl -fsSL https://raw.githubusercontent.com/SadBoen/xu-wiki/master/scripts/install.sh)

⚠️ macOS / Homebrew Python 用户：如遇 externally-managed-environment 错误， 需在 install.sh 之前先创建 venv，或设置 XU_PYTHON 指向非系统 Python。

默认安装位置

东西	路径	说明
项目根	~/xu-wiki/	用 XU_HOME=<path> 覆盖
venv	~/xu-wiki/.venv/	项目本地
CLI 软链	/usr/local/bin/xu	→ ~/xu-wiki/.venv/bin/xu
install.json	~/xu-wiki/.install.json	项目本地，跟着项目走
全局配置	$XDG_CONFIG_HOME/xu/config.yaml（默认 ~/.config/xu/）	XDG 规范
Hermes skill	~/.hermes/skills/autonomous-ai-agents/xu-wiki/	Agent 自动发现

不污染系统：venv 是项目本地隔离的；/usr/local/bin/xu 是软链不是真文件。

脚本自动完成

1. git clone 项目到 ~/xu-wiki/（已存在则复用）
2. 创建 venv ~/xu-wiki/.venv/
3. pip install -e . 安装包
4. 创建 CLI 软链 /usr/local/bin/xu
5. 安装 Hermes skill (category: autonomous-ai-agents)
6. 写 ~/xu-wiki/.install.json 记录安装元数据

验证：

xu --help                              # 列出全部子命令即成功
hermes skills list | grep -E "xu-wiki|skills"
cd ~/xu-wiki && pytest tests/ -q       # 185 passed

卸载

xu uninstall --dry-run    # 默认：只列出要删的东西，不实际删（安全）
xu uninstall --yes         # 实际卸载（除项目目录外全清）
xu uninstall --yes --purge # 卸载 + 删除项目目录（不可逆！）

清理顺序：Hermes skill、venv、CLI 软链、XDG 全局配置中的 wikis 部分、install.json（项目外的）、--purge 时才删项目目录。

兼容老路径（如果你之前装过 v0.3-，会自动清理）：

• ~/.xurc（老配置）
• ~/.xu/env（老 env）
• ~/.local/share/xu-wiki/install.json（老 install.json）

安全护栏：

• 默认 dry-run，不实际删任何东西
• 不传 --yes 时只警告不执行
• 删项目目录必须显式 --purge
• 必须包含 pyproject.toml 才会被识别为 xu-wiki 项目（防误删）

不删知识库数据（raws/、nodes/、.xu/）—— 这些是用户数据，始终保留。 如需清理配置中的旧 wiki 注册：xu unregister <name>。

快速开始

# 创建知识库
xu create /mnt/wiki --name baby

# 摄取文件
xu ingest baby 船舶证书.pdf --node-path "船舶管理/证书"

# Agent 读临时文件，提取特征，提交
xu ingest-commit baby \
  --content-temp-path /tmp/xu_ingest_xxx.md \
  --title "防火证书-第3页" \
  --digest "描述了机舱与生活区之间的A60防火结构要求" \
  --entities "船级社,A60隔离区,证书号X123" \
  --node-path "船舶管理/证书" \
  --relations '[{"to":"2026-ABC","relation_name":"ref"}]'

# 查询
xu query baby "A60隔离区"

# 关系管理
xu query-relation baby show <uid>
xu query-relation baby add <from> <to> ref

# 健康检查
xu doctor baby
xu doctor-fields baby

# 查看已有知识库
xu wikis

口述/原创内容

xu ingest-commit baby --native \
  --content-temp-path /tmp/my_note.md \
  --title "会议记录" \
  --digest "讨论A60隔离区验收标准" \
  --entities "A60,会议" \
  --node-path "项目文档"

CLI 参考

所有操作类命令的语法：xu <command> <wiki_name> <args>

组	命令	用途
create	xu create <dir> --name <name>	创建知识库
	xu register <dir> --name <name>	注册已有知识库
	xu alias add <别名> <目标>	添加别名
	xu delete-node <wiki> <uid>	删除节点
	xu revise <wiki> <uid> [--title]	修改节点
	xu unregister <name>	注销知识库
	xu config <wiki> list|get|set	配置管理
ingest	xu ingest <wiki> <file>	摄取文件
	xu ingest-url <wiki> <url>	摄取 URL
	xu ingest-text <wiki> --content '<text>'	摄取文本
	xu ingest-commit <wiki> --uid ...	提交暂存
query	xu query <wiki> <question>	全文+关系搜索
	xu query --list	列出页面
	xu query --export <dir>	导出知识库
	xu query-relation <wiki> <action>	关系 CRUD
	xu page <wiki> <action>	虚拟合集管理
	xu table <wiki> <uid> <action>	表格行级操作
	xu gallery <wiki> <uid> <action>	图集条目操作
doctor	xu doctor <wiki>	快速概览
	xu doctor-fields <wiki>	字段检查
	xu doctor-files <wiki>	文件一致性
	xu doctor-relations <wiki>	关系完整性
	xu doctor-parser <wiki>	解析追踪
	xu doctor-entities <wiki>	实体引用
	xu doctor-content-type <wiki>	content_type 完整性
	xu doctor-graph <wiki>	图结构分析
	xu doctor-tree <wiki>	节点路径总览
	xu doctor-all <wiki>	全量检查
系统	xu wikis	列出知识库
	xu skill-refresh	刷新 Agent skill 路由
	xu skill log-pitfall	记录踩坑
	xu update self	升级 xu-wiki
	xu update wiki <name>	升级 wiki 格式
	xu uninstall	卸载

开发

# 从源码直接运行（不需要 install.sh）
python3 -m xu.cli --help

# 或者装到当前 shell
pip install -e ".[dev]"
# 之后可以用 python3 -m xu.cli 或找到 .venv/bin/xu

# 测试
pytest tests/ -q
ruff check src/

许可证

MIT