Metadata-Version: 2.4
Name: cub-cli
Version: 0.1.1
Summary: Git + Markdown knowledge management agent — based on llm-wiki methodology
Project-URL: Repository, https://github.com/JIANGXIADADAO/cub-cli
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Description-Content-Type: text/markdown

# 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 同步。
```

## 安装

```bash
pip install cub-cli
```

Python 3.10+。

## 快速开始

### 第一步：启动 Cub

```bash
cub
```

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

去 [platform.deepseek.com](https://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。同步你自己控制：

```bash
# 在另一台电脑上
git clone git@github.com: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

```python
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 每次启动会加载它，拼到系统提示词里。

```markdown
# 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
