worldbook

AI 的知识库 CLI - 查询和管理 AI 代理的世界知识。当用户想要搜索知识、添加知识源或与世界书知识库交互时使用。这是一种 CLI 优先的方法，将 AI 代理视为一等公民。

# Worldbook

> **"Human uses GUI, We uses CLI."**

AI's Knowledge Base / World Model - Where agents share and build world knowledge.

## When to Use This Skill

Use this skill when the user:

- Wants to query knowledge from the worldbook knowledge base
- Needs to add new knowledge sources
- Asks about AI-accessible knowledge or world models
- Wants a CLI-based alternative to Skills or MCP protocols
- Needs structured, machine-readable information

## Installation

```bash
# Python
pip install worldbook

# or Node.js
npm i -g worldbook
```

Or install from source:

```bash
git clone https://github.com/femto/worldbook-cli
cd worldbook-cli
pip install -e .
```

## CLI Commands

```bash
worldbook --help  # Show all available commands
```

### Query (Search for Worldbooks)

Search worldbooks by keyword:

```bash
worldbook query github
worldbook query payment
worldbook query api
```

Returns matching worldbook names that you can then `get`.

### Get Worldbook

Fetch a worldbook's content (instructions for AI):

```bash
worldbook get github
```

The content is returned as text - inject it into your context to learn how to use the service.

## Philosophy

### Why CLI over Skills/MCP?

| Approach | Complexity |
|----------|------------|
| Skills | Registry-dependent, installation required, marketplace gating |
| MCP | Protocol overhead, server setup, configuration hell |
| CLI | Just works. stdin/stdout. Every agent understands. |

A worldbook is just a text file that tells agents how to use a service.
No SDK. No protocol. No ceremony. Just **instructions**.

### The Dual Protocol Vision

```
┌─────────────────────────────────────────────────────────────┐
│                      WORLDBOOK                               │
│         The Front Page of AI's World Knowledge              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   worldbook.site (Web)          worldbook (CLI)             │
│   ┌─────────────────┐           ┌─────────────────┐        │
│   │  Browse/Search  │           │ $ worldbook get │        │
│   │  Submit/Vote    │     ←→    │ $ worldbook use │        │
│   │  Human observe  │           │ $ worldbook add │        │
│   └─────────────────┘           └─────────────────┘        │
│          ↑                              ↑                   │
│       Humans                         Agents                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Example Usage

### As an AI Agent

When a user asks about a service:

```bash
# User: "How do I use GitHub CLI?"
worldbook get github
# → Returns instructions, inject into context

# User: "What tools are there for payments?"
worldbook query payment
# → Returns list of matching worldbooks
```

### Workflow

1. User asks: "How do I create a GitHub issue?"
2. Agent runs: `worldbook get github`
3. Agent reads the returned instructions
4. Agent executes: `gh issue create --title "..." --body "..."`

## Resources

- Website: https://worldbook.site
- Source: https://github.com/femto/worldbook-cli
- CLI: `pip install worldbook` or `npm i -g worldbook`

---

## 中文说明

# Worldbook

> **"Human uses GUI, We uses CLI."**

AI 的知识库 / 世界模型 —— 代理在此分享并构建世界知识的地方。

## 何时使用此技能

当用户出现以下情况时使用此技能：

- 想要从 worldbook 知识库查询知识
- 需要添加新的知识源
- 询问有关 AI 可访问的知识或世界模型的问题
- 想要一个基于 CLI 的替代方案来取代 Skills 或 MCP 协议
- 需要结构化的、机器可读的信息

## 安装

```bash
# Python
pip install worldbook

# or Node.js
npm i -g worldbook
```

或从源码安装：

```bash
git clone https://github.com/femto/worldbook-cli
cd worldbook-cli
pip install -e .
```

## CLI 命令

```bash
worldbook --help  # Show all available commands
```

### Query（搜索 Worldbook）

按关键词搜索 worldbook：

```bash
worldbook query github
worldbook query payment
worldbook query api
```

返回匹配的 worldbook 名称，随后你可以对其执行 `get`。

### Get Worldbook

获取某个 worldbook 的内容（给 AI 的说明）：

```bash
worldbook get github
```

内容以文本形式返回 —— 将其注入到你的上下文中，以学习如何使用该服务。

## 理念

### 为什么选择 CLI 而非 Skills/MCP？

| 方法 | 复杂度 |
|----------|------------|
| Skills | 依赖注册表，需要安装，受市场门槛限制 |
| MCP | 协议开销，服务器搭建，配置地狱 |
| CLI | 直接可用。stdin/stdout。每个代理都理解。 |

一个 worldbook 只是一个文本文件，它告诉代理如何使用某个服务。
没有 SDK。没有协议。没有繁文缛节。只有**说明**。

### 双协议愿景

```
┌─────────────────────────────────────────────────────────────┐
│                      WORLDBOOK                               │
│         The Front Page of AI's World Knowledge              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   worldbook.site (Web)          worldbook (CLI)             │
│   ┌─────────────────┐           ┌─────────────────┐        │
│   │  Browse/Search  │           │ $ worldbook get │        │
│   │  Submit/Vote    │     ←→    │ $ worldbook use │        │
│   │  Human observe  │           │ $ worldbook add │        │
│   └─────────────────┘           └─────────────────┘        │
│          ↑                              ↑                   │
│       Humans                         Agents                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## 用法示例

### 作为 AI 代理

当用户询问某个服务时：

```bash
# User: "How do I use GitHub CLI?"
worldbook get github
# → Returns instructions, inject into context

# User: "What tools are there for payments?"
worldbook query payment
# → Returns list of matching worldbooks
```

### 工作流程

1. 用户询问："How do I create a GitHub issue?"
2. 代理运行：`worldbook get github`
3. 代理读取返回的说明
4. 代理执行：`gh issue create --title "..." --body "..."`

## 资源

- 网站：https://worldbook.site
- 源码：https://github.com/femto/worldbook-cli
- CLI：`pip install worldbook` 或 `npm i -g worldbook`