cub-cli 0.1.1

Git + Markdown knowledge management agent — based on llm-wiki methodology

Cub

Git + Markdown 知识管理 agent。基于 llm-wiki 方法论。

pip install cub-cli · cub 启动。

问题

Obsidian Sync 要 $5/月。Notion 免费版限制设备数。你花钱同步知识文件—— 而 Git 从 2005 年起就免费干这件事了。

方案

Git + Markdown 天然跨设备、零成本、永不过时。 Cub 在上面加了一层 AI agent：自动读、写、整理、链接、同步你的知识库。 你负责思考，agent 负责管理。

> 把这篇文章关于 AI agent 的核心观点存下来 https://example.com/ai-agents

  [1/3] fetch · 1.2s · 0t        ← 抓取文章内容
  [2/3] write · 0.3s · 245t      ← 提取要点，写入 Markdown
  [3/3] bash  · 0.5s · 89t       ← git add + git commit
  — 3 steps · 2.0s · 334t

搞定。已提交到仓库，随时可以 git push 同步。

安装

pip install cub-cli

Python 3.10+。

快速开始

第一步：启动 Cub

cub

首次运行会提示你粘贴 DeepSeek API key（存到 ~/.cub/config.toml，只问一次）。

去 platform.deepseek.com 免费注册，充 1 块钱够用几个月。

第二步：初始化知识库

Cub 启动时检测当前目录。如果不是 llm-wiki 知识库，会提示你初始化：

Cub — /home/user/my-knowledge
  缺目录: concepts, entities, sources, comparisons, queries, inboxes
  缺文件: CLAUDE.md, index.md, overview.md, log.md
  缺 Git 仓库

  当前目录不像 llm-wiki 知识库。要在这里初始化吗？[Y/n] y

  初始化 llm-wiki 知识库 → /home/user/my-knowledge

  git init
  要不要关联远端仓库？输入 URL，不要就回车跳过:
  目录结构创建完成 (6 个目录)
  模板文件写入完成 (CLAUDE.md + index + overview + log)
  git commit: [init] 知识库创建

  知识库创建完成。编辑 CLAUDE.md 可以自定义 Cub 的行为。

初始化后会生成：

my-knowledge/
├── CLAUDE.md          ← Cub 的指令文件（你可编辑，个性化 Cub 的行为）
├── index.md           ← 路由器：主题 → 页面映射
├── overview.md        ← 全局图景和核心论点
├── log.md             ← 时间线日志
├── concepts/          ← 抽象概念
├── entities/          ← 具体事物（人、公司、工具）
├── sources/           ← 来源摘要（文章、书籍、对话）
├── comparisons/       ← 对比分析
├── queries/           ← 查询归档
└── inboxes/           ← 待处理经验碎片

第三步：开始使用

> 我们之前记录的 AI agent 架构决策有哪些？

  [1/3] grep · 0.3s · 45t        ← 搜索所有 Markdown 文件
  [2/3] read · 0.1s · 12t        ← 读匹配到的页面
  — 2 steps · 0.4s · 100t

找到 3 个相关页面：
- concepts/ai-agent-architecture.md（6月15日更新）
- entities/langchain-vs-llamaindex.md
- sources/anthropic-agent-paper.md

跨设备同步

Cub 负责读写文件 + git commit。同步你自己控制：

# 在另一台电脑上
git clone [e-mail]:you/my-knowledge.git
cd my-knowledge
cub
> 上次那篇 AI agent 的文章，帮我回顾一下要点

这就是 llm-wiki 的核心：Obsidian Sync 要 $5/月做的事情，Git 免费做，Cub 还多一个 AI agent。

对比

	Obsidian Sync	Notion Free	Cub
跨设备同步	$5/月	1 设备限制	免费（Git）
AI 知识管理	单独插件	AI 加购 ($10/月)	内置
文件格式	Markdown (👍)	私有格式 (👎)	Markdown (👍)
离线	可以	不行	可以（Git）
锁定	低	高	零
Agent 自动整理	否	部分	是

API

import asyncio
from cub import Agent, DeepSeekClient, Mode

async def main():
    client = DeepSeekClient(api_key="sk-...")
    agent = Agent(client,
        system_prompt="You are a knowledge management agent.",
        mode=Mode.AUTO)

    async for event in agent.run("Summarize the AI agents page"):
        if event["type"] == "text_delta":
            print(event["text"], end="", flush=True)
        elif event["type"] == "tool_call":
            print(f"\n  [{event['step']}/{event['max_steps']}] {event['tool']}")
        elif event["type"] == "summary":
            print(f"\n  — {event['steps']} steps · "
                  f"{event['duration_ms']/1000:.1f}s · {event['tokens']}t")

asyncio.run(main())

架构

用户提问（或分享链接）
    │
    ▼
┌──────────────────────────────────────┐
│           Agent (loop.py)            │
│                                      │
│  Stream LLM → 思考该做什么            │
│  Tool call → read/write/grep/bash   │
│  Execute → 结果返回 LLM              │
│  Loop 直到回答完成                    │
└──────────────────────────────────────┘
    │            │               │
    ▼            ▼               ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ llm.py  │ │ tools.py │ │permissions.py│
│DeepSeek │ │ 7 个工具  │ │ read/yn/auto │
│流式输出  │ │  异步    │ │  + 硬墙      │
└─────────┘ └──────────┘ └──────────────┘

工具

工具	用途
read	读文件
write	创建或覆盖文件
edit	精确替换文件中的字符串
grep	用正则搜索文件内容
glob	按文件名模式查找
bash	执行命令（git、构建、测试等）
fetch	抓取 URL 内容为 Markdown

权限模式

模式	读文件	写文件	执行命令	硬墙可绕过？
Read（只读）	✅	❌	❌	否
YN（默认）	✅	询问	询问	否
Auto（自动）	✅	✅	✅	否

硬墙（任何模式永久禁止）：rm -rf、sudo、git push --force、 路径：raw/、agents/、archive/、/etc/、/proc/、/sys/。

自定义 Cub 的行为

编辑知识库根目录的 CLAUDE.md。Cub 每次启动会加载它，拼到系统提示词里。

# CLAUDE.md

## 用户自定义规则

- 所有输出用中文
- 技术文章偏好代码示例
- 每周日帮我做一次 lint

改完保存，下次 cub 启动就生效。

llm-wiki 方法论

1. 知识存在 Git 里。 一堆 Markdown 文件。版本控制。可移植。免费。
2. Agent 负责整理。 你不用手动建目录和链接。Agent 干。
3. 每次变更都是 commit。 知识演化有迹可查。随时回滚。
4. 纯文本，不锁定。 你用任何工具都能读写。Agent 是可选的。
5. 知识复利增长。 页面互相链接。索引永远是最新的。碎片自动归位。

项目结构

cub-cli/
├── cub/
│   ├── __init__.py        # Public API
│   ├── cli.py             # REPL + KB 检测 + 初始化
│   ├── loop.py            # Agent 循环 + 流式 + checkpoint
│   ├── llm.py             # DeepSeek API（流式 + 用量）
│   ├── tools.py           # 7 工具 + registry + async handlers
│   └── permissions.py     # 3 级权限 + 硬墙
├── tests/                 # 65 个测试
├── README.md
└── pyproject.toml

License

MIT