# oc-server

**Repository Path**: AungV/oc-server

## Basic Information

- **Project Name**: oc-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Wiki Server

将任意 Markdown 文件夹变为可查询的 AI 知识库。提供服务端 HTTP API + 客户端 CLI。

## 安装

### 前提：hermes-agent

llm-wiki-server 依赖 [hermes-agent](https://github.com/nichochar/hermes) 作为 AI 后端。请先安装 hermes CLI，确保 `hermes` 命令在 PATH 中可用：

```bash
hermes --version   # 应输出版本号
```

如果 hermes 未安装，`llmwiki serve` 启动时会报错并退出。

### 安装 llm-wiki-server

```bash
cd llm-wiki-server
npm install    # 自动编译
npm link       # 创建全局命令
```

---

## 快速开始

```bash
# 1. 注册（客户端本地生成 API Key + code）
llmwiki signup
# 输出：API key: wiki_3f8a2b...  Code: code_e5f6a7...

# 2. 管理员用你的 code 添加用户（在服务器端）
llmwiki serve add-user alice --code code_e5f6a7... --role member

# 3. 启动服务端
llmwiki serve

# 4. 登录（使用 signup 生成的 API Key）
llmwiki login local --host 127.0.0.1 --port 3000

# 5. 使用
llmwiki query "Which model is best for coding?"
llmwiki query "Summarize the API" --length 1k
llmwiki query "What changed?" --stream
llmwiki read models/o3
llmwiki ingest --source "GPT-5 released" --member "gpt-5"
llmwiki ingest --file ./notes.md
llmwiki ingest --dir ./my-notes/ --member alice
```

---

## 客户端命令

### 注册与认证

```bash
# 用户自助注册（本地生成 API Key + code，无需连接服务器）
llmwiki signup

# 管理员添加用户（在服务器端执行）
llmwiki serve add-user alice --code code_e5f6a7b8... --role member
```

注册流程：用户执行 `signup` 生成 API Key（`wiki_` 格式）和 code（`code_` 格式），将 code 发给管理员，管理员用 `serve add-user` 注册账号。服务端只存储 code，不存储原始 API Key。

角色权限：`member` 可使用所有端点（含 `/ingest`），`user` 可使用 `/query`、`/content`、`/auth`、`/health`，但不能 `/ingest`。

### API Key 优先级

1. `--api-key` 参数
2. 配置文件中的 key（`signup` 或 `login` 时保存）

### 登录

```bash
# 交互式（推荐）
llmwiki login

# 参数式
llmwiki login --name work --host wiki.company.com --port 3000

# 切换已有 server
llmwiki login work
```

配置保存在 `~/.llm-wiki-server/config.json`。

### 多 server

```bash
llmwiki login --name work --host wiki.company.com --port 3000
llmwiki login --name personal --host 192.168.1.5 --port 3000

llmwiki list
#   work      wiki.company.com:3000    (current)
#   personal  192.168.1.5:3000

llmwiki login personal          # 切换
llmwiki --server personal query "hello"  # 临时使用，不切换
```

### 命令一览

| 命令 | 说明 |
|------|------|
| `serve` | 启动服务端（hermes gateway + HTTP） |
| `serve add-user <name> --code <code> --role <role>` | 管理员添加用户 |
| `signup` | 用户自助注册（本地生成 API Key + code） |
| `login [--name] [--host] [--port]` | 添加/切换 server |
| `list` | 列出所有 server |
| `auth` | 验证当前连接状态 |
| `query <question> [--length] [--stream]` | 向 wiki 提问 |
| `ingest --source / --file / --dir [--member]` | 更新 wiki 内容 |
| `read <path>` | 读取 wiki 文件 |

全局选项（命令前）：`--server` `--api-key` `--help` `--version`

---

## 服务端

```bash
llmwiki serve
```

自动完成：检测/spawn hermes gateway、初始化 wiki 目录、启动 HTTP 适配器。Ctrl+C 退出，自动停止 hermes gateway。

### 参数

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--port` | 3000 | HTTP 服务端口 |
| `--host` | 127.0.0.1 | HTTP 服务地址 |
| `--hermes-port` | 8642 | Hermes 服务端口 |
| `--hermes-host` | 127.0.0.1 | Hermes 服务地址 |

---

## API 端点

所有端点需 API Key（`Authorization: Bearer <key>` 或 `X-API-Key: <key>`）。`/ingest` 需 `member` 角色。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /query | 自然语言查询 |
| POST | /query/stream | 流式查询（SSE） |
| POST | /ingest | 更新 wiki 内容（需 member 角色） |
| GET | /content/:path | 读取 wiki 文件 |
| GET | /auth | 验证 API Key |
| GET | /health | 健康检查 |

---

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SERVER_HOST` | `127.0.0.1` | HTTP 服务地址 |
| `SERVER_PORT` | `3000` | HTTP 服务端口 |
| `HERMES_HOST` | `127.0.0.1` | Hermes 服务地址 |
| `HERMES_PORT` | `8642` | Hermes 服务端口 |
| `HERMES_API_KEY` | （自动生成） | Hermes API Key，`serve` 启动时自动生成并保存到 `~/.hermes/.env` |
| `AUTH_USERS_FILE` | `~/.llm-wiki-server/users.json` | 用户凭证路径 |
| `WIKI_DIR` | `~/.wiki` | 数据目录（配置、认证、审计等），不是 wiki 内容目录 |
| `WIKI_PATH` | `~/wiki` | Hermes wiki 内容目录（SCHEMA.md、raw/、entities/ 等） |

**重要区分**：`WIKI_DIR`（`~/.wiki`）是 llm-wiki-server 的数据目录，`WIKI_PATH`（`~/wiki`）是 hermes 的 wiki 内容目录，两者分离。