Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: add server cli design (#46)

qin-ctx26930c01042b
diff --git a/docs/design/server_client/prompt.md b/docs/design/server_client/prompt.md
new file mode 100644
index 000000000..05d8026b5
--- /dev/null
+++ b/docs/design/server_client/prompt.md
@@ -0,0 +1,1225 @@
+# OpenViking Server/CLI 实现任务 Prompt
+
+本文档包含各任务的 Agent Prompt,用于指导实现。
+
+---
+
+## T1: Service 层抽取
+
+### 目标
+从 `async_client.py` 抽取业务逻辑到独立的 Service 层,使业务逻辑与传输层解耦。
+
+### 背景
+当前 `openviking/async_client.py` 包含了所有业务逻辑,需要将其抽取到 `openviking/service/` 目录下,便于 HTTP Server 和 CLI 复用。
+
+### 任务详情
+
+1. **创建 Service 层目录结构**:
+```
+openviking/service/
+├── __init__.py
+├── core.py # OpenVikingService 主类
+├── fs_service.py # 文件系统操作
+├── resource_service.py # 资源导入、技能添加
+├── search_service.py # 语义搜索
+├── session_service.py # 会话管理
+├── relation_service.py # 关联管理
+└── pack_service.py # 导入导出
+```
+
+2. **抽取业务逻辑**:
+
+- `FSService`: ls, tree, stat, mkdir, rm, mv, read, abstract, overview, grep, glob
+- `ResourceService`: add_resource, add_skill, wait_processed
+- `SearchService`: find, search
+- `SessionService`: session, sessions, add_message, compress, extract
+- `RelationService`: link, unlink, relations
+- `PackService`: export_ovpack, import_ovpack
+
+3. **创建 OpenVikingService 主类**:
+- 组合所有子 Service
+- 管理 VikingFS、VectorIndex 等基础设施
+- 提供统一的初始化和关闭方法
+
+4. **修改 async_client.py**:
+- 改为调用 Service 层
+- 保持现有 API 不变(兼容层)
+
+### 验收标准
+- 现有单元测试全部通过
+- `async_client.py` API 保持不变
+- Service 层可独立使用
+
+### 参考文件
+- `openviking/async_client.py` - 现有实现
+- `openviking/storage/viking_fs.py` - VikingFS 实现
+- `design/server-cli-design.md` - 设计文档 4.1 节
+
+---
+
+## T2: HTTP Server 实现
+
+### 目标
+基于 FastAPI 实现 HTTP Server,提供 RESTful API。
+
+### 背景
+参考 `design/server-cli-design.md` 第七节 HTTP API 设计。
+
+### 任务详情
+
+1. **创建 Server 目录结构**:
+```
+openviking/server/
+├── __init__.py
+├── app.py # FastAPI 应用入口
+├── bootstrap.py # 服务启动器
+├── config.py # 服务器配置
+├── auth.py # API Key 认证
+├── dependencies.py # 依赖注入
+├── models.py # 响应模型、错误码
+└── routers/
+ ├── __init__.py
+ ├── resources.py # /api/v1/resources
+ ├── filesystem.py # /api/v1/fs
+ ├── content.py # /api/v1/content
+ ├── search.py # /api/v1/search
+ ├── relations.py # /api/v1/relations
+ ├── sessions.py # /api/v1/sessions
+ ├── pack.py # /api/v1/pack
+ └── system.py # /api/v1/system, /health
+```
+
+2. **实现统一响应格式**(参考设计文档 5.2 节):
+```python
+class Response(BaseModel):
+ status: str # "ok" | "error"
+ result: Optional[Any] = None
+ error: Optional[ErrorInfo] = None
+ time: float = 0.0
+ usage: Optional[UsageInfo] = None
+```
+
+3. **实现 API Key 认证**:
+- 支持 `X-API-Key` header
+- 支持 `Authorization: Bearer` header
+
+4. **实现所有 API 端点**(参考设计文档 7.3 节):
+- 资源管理: POST /api/v1/resources, POST /api/v1/skills
+- 文件系统: GET /api/v1/fs/ls, GET /api/v1/fs/tree, etc.
+- 内容读取: GET /api/v1/content/read, /abstract, /overview
+- 搜索: POST /api/v1/search/find, /search, /grep, /glob
+- 关联: POST /api/v1/relations/link, DELETE /api/v1/relations/link
+- 会话: POST/GET/DELETE /api/v1/sessions
+- 导入导出: POST /api/v1/pack/export, /import
+- 系统: GET /health, GET /api/v1/system/status
+
+5. **实现服务启动器** (bootstrap.py):
+- 加载配置文件 `~/.openviking/server.yaml`
+- 初始化 OpenVikingService
+- 启动 uvicorn 服务器
+
+### 验收标准
+```bash
+# 启动服务
+openviking serve --path ./data --port 8000
+
+# 验证 API
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/api/v1/resources \
+ -H "X-API-Key: test" -d '{"path": "./docs"}'
+curl "http://localhost:8000/api/v1/fs/ls?uri=viking://" \
+ -H "X-API-Key: test"
+```
+
+### 依赖
+- T1 (Service 层) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 第七节
+- `openviking/service/` - Service 层(T1 产出)
+
+---
+
+## T3: CLI 基础框架
+
+### 目标
+使用 Typer 实现 CLI 核心命令。
+
+### 背景
+参考 `design/server-cli-design.md` 第六节 CLI 设计。
+
+### 任务详情
+
+1. **创建 CLI 目录结构**:
+```
+openviking/cli/
+├── __init__.py
+├── main.py # CLI 入口
+├── output.py # 输出格式化(JSON/Table/Plain)
+└── config.py # 配置管理(读取环境变量、配置文件)
+```
+
+2. **更新 pyproject.toml**:
+```toml
+[project.scripts]
+openviking = "openviking.cli.main:app"
+
+[project.optional-dependencies]
+cli = [
+ "typer>=0.9.0",
+ "rich>=13.0.0",
+]
+```
+
+3. **实现核心命令**:
+```bash
+# 服务管理
+openviking serve --path <dir> [--port 8000] [--host 0.0.0.0]
+openviking status
+
+# 资源导入
+openviking add-resource <path> [--to <uri>] [--wait] [--timeout N]
+
+# 文件系统操作
+openviking ls <uri> [--simple] [--recursive]
+
+# 内容读取
+openviking read <uri>
+openviking abstract <uri>
+openviking overview <uri>
+
+# 搜索
+openviking find <query> [<uri>] [--limit N] [--threshold F]
+```
+
+4. **实现配置优先级**:
+- 命令行参数 > 环境变量 > 配置文件
+- 环境变量: OPENVIKING_URL, OPENVIKING_API_KEY, OPENVIKING_USER, OPENVIKING_AGENT
+
+5. **实现输出格式化**:
+- 支持 `--output json` 输出 JSON
+- 默认使用 Rich 美化输出
+
+### 验收标准
+```bash
+openviking --help
+openviking serve --path ./data --port 8000
+openviking add-resource ./docs/ --wait
+openviking ls viking://resources/
+openviking find "how to use"
+```
+
+### 依赖
+- T1 (Service 层) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 第六节
+- `openviking/service/` - Service 层(T1 产出)
+
+---
+
+## T4: Python SDK
+
+### 目标
+实现 HTTPClient,支持通过 HTTP 连接远程 Server。
+
+### 背景
+参考 `design/server-cli-design.md` 3.1 节分层架构和 6.2 节 Python SDK。
+
+### 任务详情
+
+1. **创建 Client 目录结构**:
+```
+openviking/client/
+├── __init__.py
+├── base.py # 客户端基类接口
+├── local.py # LocalClient(直接调用 Service)
+└── http.py # HTTPClient(HTTP 调用 Server)
+```
+
+2. **定义客户端接口** (base.py):
+```python
+class BaseClient(ABC):
+ @abstractmethod
+ async def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> Response: ...
+ @abstractmethod
+ async def find(self, query: str, target_uri: str = "viking://", limit: int = 10) -> Response: ...
+ # ... 所有方法
+```
+
+3. **实现 HTTPClient** (http.py):
+- 使用 httpx 进行 HTTP 调用
+- 实现所有 API 端点的客户端方法
+- 处理认证(API Key)
+- 处理错误响应,转换为异常
+
+4. **实现 LocalClient** (local.py):
+- 直接调用 OpenVikingService
+- 包装返回值为统一的 Response 格式
+
+5. **修改 OpenViking 类**:
+```python
+class OpenViking:
+ def __init__(
+ self,
+ path: Optional[str] = None, # 嵌入式模式
+ url: Optional[str] = None, # HTTP 模式
+ api_key: Optional[str] = None,
+ user: Optional[str] = None,
+ agent: Optional[str] = None,
+ ):
+ if url:
+ self._client = HTTPClient(url, api_key)
+ else:
+ self._client = LocalClient(path)
+```
+
+### 验收标准
+```python
+# HTTP 模式
+client = OpenViking(url="http://localhost:8000", api_key="test")
+results = client.find("how to use")
+
+# 嵌入式模式(保持兼容)
+client = OpenViking(path="./data")
+results = client.find("how to use")
+```
+
+### 依赖
+- T2 (HTTP Server) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 3.1 节、6.2 节
+- `openviking/server/` - HTTP Server(T2 产出)
+
+---
+
+## T5: CLI 完整命令
+
+### 目标
+补全所有 CLI 命令。
+
+### 背景
+参考 `design/server-cli-design.md` 6.1 节命令列表。
+
+### 任务详情
+
+1. **会话管理命令**:
+```bash
+openviking session new [--user <name>]
+openviking session list
+openviking session get <id>
+openviking session compress <id>
+openviking session extract <id>
+openviking session delete <id>
+```
+
+2. **文件系统命令**:
+```bash
+openviking tree <uri>
+openviking stat <uri>
+openviking mkdir <uri>
+openviking rm <uri> [--recursive]
+openviking mv <from> <to>
+```
+
+3. **搜索命令**:
+```bash
+openviking search <query> [<uri>] [--session-id ID] [--limit N]
+openviking grep <uri> <pattern> [-i]
+openviking glob <pattern> [<uri>]
+```
+
+4. **关联命令**:
+```bash
+openviking link <from> <to>... [--reason TEXT]
+openviking unlink <from> <to>
+openviking relations <uri>
+```
+
+5. **导入导出命令**:
+```bash
+openviking export <uri> <file.ovpack>
+openviking import <file.ovpack> <uri> [--force] [--no-vectorize]
+```
+
+6. **配置命令**:
+```bash
+openviking config show
+openviking config init
+```
+
+7. **工具命令**:
+```bash
+openviking wait [--timeout N]
+openviking add-skill <file> [--wait]
+```
+
+### 验收标准
+```bash
+openviking --help # 显示所有命令
+openviking session new --user alice
+openviking session list
+openviking export viking://resources/docs/ ./backup.ovpack
+openviking config show
+```
+
+### 依赖
+- T3 (CLI 基础框架) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 6.1 节
+- `openviking/cli/main.py` - CLI 基础框架(T3 产出)
+
+---
+
+## T6: 集成测试
+
+### 目标
+编写端到端集成测试,验证 CLI、Server、Python SDK 的完整工作流程。
+
+### 背景
+参考 `design/server-cli-design.md` 8.5 节验证方案。
+
+### 任务详情
+
+1. **创建测试文件**:
+```
+tests/integration/
+├── test_cli.py # CLI 命令测试
+├── test_server.py # HTTP Server 测试
+└── test_http_client.py # Python SDK 测试
+```
+
+2. **CLI 测试** (test_cli.py):
+```python
+def test_serve_command():
+ """测试 serve 命令启动服务"""
+ ...
+
+def test_add_resource_command():
+ """测试 add-resource 命令"""
+ ...
+
+def test_ls_command():
+ """测试 ls 命令"""
+ ...
+
+def test_find_command():
+ """测试 find 命令"""
+ ...
+
+def test_session_commands():
+ """测试 session 子命令"""
+ ...
+```
+
+3. **Server 测试** (test_server.py):
+```python
+async def server():
+ """启动测试服务器"""
+ ...
+
+async def test_health_endpoint(server):
+ """测试 /health 端点"""
+ ...
+
+async def test_resources_api(server):
+ """测试资源 API"""
+ ...
+
+async def test_search_api(server):
+ """测试搜索 API"""
+ ...
+
+async def test_auth_required(server):
+ """测试认证"""
+ ...
+```
+
+4. **Python SDK 测试** (test_http_client.py):
+```python
+async def test_http_client_find():
+ """测试 HTTP 客户端 find 方法"""
+ ...
+
+async def test_http_client_session():
+ """测试 HTTP 客户端会话管理"""
+ ...
+
+async def test_http_client_error_handling():
+ """测试错误处理"""
+ ...
+```
+
+5. **端到端工作流测试**:
+```python
+async def test_full_workflow():
+ """完整工作流测试"""
+ # 1. 启动 Server
+ # 2. 使用 Python SDK 连接
+ # 3. 添加资源
+ # 4. 搜索
+ # 5. 会话管理
+ # 6. 导出/导入
+ ...
+```
+
+### 验收标准
+- 所有集成测试通过
+- 覆盖主要使用场景
+- 测试报告显示覆盖率
+
+### 依赖
+- T4 (Python SDK) 必须先完成
+- T5 (CLI 完整命令) 必须先完成
+
+### 参考文件
+- `tests/` - 现有测试结构
+- `tests/conftest.py` - pytest 配置
+
+---
+
+## T7: 文档更新
+
+### 目标
+更新用户文档,包括 README、API 文档、CHANGELOG。
+
+### 背景
+参考 `design/server-cli-design.md` 6.3 节使用指南。
+
+### 任务详情
+
+1. **更新 README.md**:
+- 添加 CLI 安装和使用说明
+- 添加 Server 部署说明
+- 添加 HTTP API 使用示例
+- 更新架构图
+
+2. **生成 OpenAPI 文档**:
+- FastAPI 自动生成 `/docs` 和 `/redoc`
+- 确保所有端点有完整的描述和示例
+
+3. **更新 CHANGELOG.md**:
+- 记录新增的 CLI 功能
+- 记录新增的 HTTP API
+- 记录 SDK 的 HTTP 模式支持
+
+4. **添加使用示例**:
+```markdown
+## CLI 使用
+
+### 启动服务
+\`\`\`bash
+openviking serve --path ./data --port 8000
+\`\`\`
+
+### 添加资源
+\`\`\`bash
+openviking add-resource ./docs/ --wait
+\`\`\`
+
+### 语义搜索
+\`\`\`bash
+openviking find "how to configure"
+\`\`\`
+
+## HTTP API 使用
+
+### 健康检查
+\`\`\`bash
+curl http://localhost:8000/health
+\`\`\`
+
+### 搜索
+\`\`\`bash
+curl -X POST http://localhost:8000/api/v1/search/find \
+ -H "X-API-Key: your-key" \
+ -H "Content-Type: application/json" \
+ -d '{"query": "how to configure", "limit": 10}'
+\`\`\`
+
+## Python SDK (HTTP 模式)
+
+\`\`\`python
+from openviking import OpenViking
+
+client = OpenViking(url="http://localhost:8000", api_key="your-key")
+results = client.find("how to configure")
+\`\`\`
+```
+
+### 验收标准
+- README 包含完整的 CLI/Server/API 使用说明
+- OpenAPI 文档可访问且完整
+- CHANGELOG 记录所有变更
+
+### 依赖
+- T6 (集成测试) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 6.3 节
+- `README.md` - 现有文档
+
+---
+
+## T8: Docker 部署
+
+### 目标
+提供 Docker 镜像和 docker-compose 配置,简化部署流程。
+
+### 背景
+Docker 是现代应用部署的标准方式,降低用户部署门槛。
+
+### 任务详情
+
+1. **创建 Dockerfile**:
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# 安装依赖
+COPY pyproject.toml .
+RUN pip install .
+
+# 复制代码
+COPY openviking/ openviking/
+
+# 暴露端口
+EXPOSE 8000
+
+# 启动命令
+CMD ["openviking", "serve", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+2. **创建 docker-compose.yml**:
+```yaml
+version: '3.8'
+
+services:
+ openviking:
+ build: .
+ ports:
+ - "8000:8000"
+ volumes:
+ - openviking-data:/data
+ environment:
+ - OPENVIKING_PATH=/data
+ - OPENVIKING_API_KEY=${OPENVIKING_API_KEY}
+ - OPENAI_API_KEY=${OPENAI_API_KEY}
+ restart: unless-stopped
+
+volumes:
+ openviking-data:
+```
+
+3. **创建 .dockerignore**:
+```
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+tests/
+docs/
+*.md
+```
+
+4. **多阶段构建优化**(可选):
+- 使用多阶段构建减小镜像体积
+- 分离构建依赖和运行依赖
+
+5. **发布到 Docker Hub / GitHub Container Registry**:
+- 配置 GitHub Actions 自动构建和发布
+- 支持多架构(amd64, arm64)
+
+### 验收标准
+```bash
+# 构建镜像
+docker build -t openviking .
+
+# 运行容器
+docker run -p 8000:8000 -e OPENAI_API_KEY=xxx openviking
+
+# 使用 docker-compose
+docker-compose up -d
+
+# 验证服务
+curl http://localhost:8000/health
+```
+
+### 依赖
+- T2 (HTTP Server) 必须先完成
+
+### 参考文件
+- `pyproject.toml` - 依赖配置
+- `openviking/server/` - Server 实现
+
+---
+
+## T9: MCP Server 实现
+
+### 目标
+实现 Model Context Protocol (MCP) 服务端,让 Claude 等 AI 可以直接调用 OpenViking。
+
+### 背景
+MCP 是 Anthropic 推出的标准协议,允许 AI 模型与外部工具交互。实现 MCP Server 可以让 OpenViking 无缝集成到 Claude Desktop、Cursor 等支持 MCP 的应用中。
+
+### 任务详情
+
+1. **创建 MCP Server 目录结构**:
+```
+openviking/mcp/
+├── __init__.py
+├── server.py # MCP Server 主入口
+├── tools.py # Tool 定义
+└── resources.py # Resource 定义
+```
+
+2. **定义 MCP Tools**:
+```python
+# 核心 Tools
+tools = [
+ {
+ "name": "openviking_find",
+ "description": "Semantic search in OpenViking context database",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string", "description": "Search query"},
+ "uri": {"type": "string", "description": "Target URI scope"},
+ "limit": {"type": "integer", "description": "Max results"}
+ },
+ "required": ["query"]
+ }
+ },
+ {
+ "name": "openviking_read",
+ "description": "Read content from OpenViking",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "uri": {"type": "string", "description": "Resource URI"}
+ },
+ "required": ["uri"]
+ }
+ },
+ {
+ "name": "openviking_ls",
+ "description": "List directory contents in OpenViking",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "uri": {"type": "string", "description": "Directory URI"}
+ },
+ "required": ["uri"]
+ }
+ },
+ # ... 更多 tools
+]
+```
+
+3. **实现 MCP Server**:
+```python
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+
+server = Server("openviking")
+
+async def list_tools() -> list[Tool]:
+ return tools
+
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+ if name == "openviking_find":
+ result = await client.find(arguments["query"], ...)
+ return [TextContent(type="text", text=json.dumps(result))]
+ # ... 处理其他 tools
+```
+
+4. **支持 stdio 和 SSE 传输**:
+- stdio: 用于 Claude Desktop 等本地应用
+- SSE: 用于 Web 应用
+
+5. **配置文件示例** (claude_desktop_config.json):
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "command": "openviking",
+ "args": ["mcp", "--path", "/path/to/data"]
+ }
+ }
+}
+```
+
+6. **添加 CLI 命令**:
+```bash
+openviking mcp [--path <dir>] [--transport stdio|sse]
+```
+
+### 验收标准
+- MCP Server 可以通过 stdio 启动
+- Claude Desktop 可以成功连接并调用 tools
+- 所有核心功能(find, read, ls, abstract, overview)可通过 MCP 调用
+
+### 依赖
+- T1 (Service 层) 必须先完成
+- 建议 T3 (CLI 基础框架) 先完成
+
+### 参考文件
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+- `openviking/service/` - Service 层
+
+---
+
+## T10: TypeScript SDK
+
+### 目标
+基于 HTTP API 实现 TypeScript/JavaScript 客户端 SDK。
+
+### 背景
+TypeScript/JavaScript 是 Web 开发的主流语言,覆盖前端和 Node.js 后端开发者。
+
+### 任务详情
+
+1. **创建项目结构**:
+```
+openviking-js/
+├── package.json
+├── tsconfig.json
+├── src/
+│ ├── index.ts # 主入口
+│ ├── client.ts # OpenViking 客户端
+│ ├── types.ts # 类型定义
+│ └── errors.ts # 错误类
+├── tests/
+│ └── client.test.ts
+└── README.md
+```
+
+2. **实现客户端类**:
+```typescript
+// src/client.ts
+export interface OpenVikingConfig {
+ url: string;
+ apiKey: string;
+ user?: string;
+ agent?: string;
+}
+
+export class OpenViking {
+ private config: OpenVikingConfig;
+
+ constructor(config: OpenVikingConfig) {
+ this.config = config;
+ }
+
+ async find(query: string, options?: FindOptions): Promise<SearchResult> {
+ const response = await fetch(`${this.config.url}/api/v1/search/find`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-API-Key': this.config.apiKey,
+ },
+ body: JSON.stringify({ query, ...options }),
+ });
+ return this.handleResponse(response);
+ }
+
+ async ls(uri: string, options?: LsOptions): Promise<LsResult> { ... }
+ async read(uri: string): Promise<ReadResult> { ... }
+ async abstract(uri: string): Promise<ReadResult> { ... }
+ async overview(uri: string): Promise<ReadResult> { ... }
+ // ... 其他方法
+}
+```
+
+3. **类型定义**:
+```typescript
+// src/types.ts
+export interface Response<T> {
+ status: 'ok' | 'error';
+ result?: T;
+ error?: ErrorInfo;
+ time: number;
+}
+
+export interface SearchResult {
+ items: SearchItem[];
+ query: string;
+ total: number;
+}
+
+export interface SearchItem {
+ uri: string;
+ score: number;
+ content: string;
+ abstract?: string;
+}
+
+// ... 其他类型
+```
+
+4. **错误处理**:
+```typescript
+// src/errors.ts
+export class OpenVikingError extends Error {
+ code: string;
+ details?: Record<string, unknown>;
+
+ constructor(code: string, message: string, details?: Record<string, unknown>) {
+ super(message);
+ this.code = code;
+ this.details = details;
+ }
+}
+
+export class NotFoundError extends OpenVikingError {}
+export class InvalidURIError extends OpenVikingError {}
+// ... 其他错误类
+```
+
+5. **发布配置**:
+```json
+// package.json
+{
+ "name": "@openviking/sdk",
+ "version": "1.0.0",
+ "main": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "scripts": {
+ "build": "tsc",
+ "test": "jest"
+ }
+}
+```
+
+### 验收标准
+```typescript
+import { OpenViking } from '@openviking/sdk';
+
+const client = new OpenViking({
+ url: 'http://localhost:8000',
+ apiKey: 'your-api-key',
+});
+
+// 搜索
+const results = await client.find('how to configure');
+console.log(results.items);
+
+// 读取
+const content = await client.read('viking://resources/doc.md');
+console.log(content);
+```
+
+### 依赖
+- T2 (HTTP Server) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 7.3 节 API 端点
+- `openviking/server/models.py` - 响应模型定义
+
+---
+
+## T11: Golang SDK
+
+### 目标
+基于 HTTP API 实现 Golang 客户端 SDK。
+
+### 背景
+Go 是云原生和基础设施领域的主流语言,覆盖 Kubernetes 生态和后端开发者。
+
+### 任务详情
+
+1. **创建项目结构**:
+```
+openviking-go/
+├── go.mod
+├── go.sum
+├── client.go # 主客户端
+├── types.go # 类型定义
+├── errors.go # 错误定义
+├── client_test.go # 测试
+└── README.md
+```
+
+2. **实现客户端**:
+```go
+// client.go
+package openviking
+
+import (
+ "bytes"
+ "encoding/json"
+ "net/http"
+)
+
+type Config struct {
+ URL string
+ APIKey string
+ User string
+ Agent string
+}
+
+type Client struct {
+ config Config
+ httpClient *http.Client
+}
+
+func NewClient(config Config) *Client {
+ return &Client{
+ config: config,
+ httpClient: &http.Client{},
+ }
+}
+
+func (c *Client) Find(query string, opts *FindOptions) (*SearchResult, error) {
+ body := map[string]interface{}{
+ "query": query,
+ }
+ if opts != nil {
+ if opts.URI != "" {
+ body["uri"] = opts.URI
+ }
+ if opts.Limit > 0 {
+ body["limit"] = opts.Limit
+ }
+ }
+
+ resp, err := c.post("/api/v1/search/find", body)
+ if err != nil {
+ return nil, err
+ }
+
+ var result SearchResult
+ if err := json.Unmarshal(resp.Result, &result); err != nil {
+ return nil, err
+ }
+ return &result, nil
+}
+
+func (c *Client) Ls(uri string, opts *LsOptions) (*LsResult, error) { ... }
+func (c *Client) Read(uri string) (*ReadResult, error) { ... }
+func (c *Client) Abstract(uri string) (*ReadResult, error) { ... }
+func (c *Client) Overview(uri string) (*ReadResult, error) { ... }
+// ... 其他方法
+```
+
+3. **类型定义**:
+```go
+// types.go
+package openviking
+
+import "encoding/json"
+
+type Response struct {
+ Status string `json:"status"`
+ Result json.RawMessage `json:"result,omitempty"`
+ Error *ErrorInfo `json:"error,omitempty"`
+ Time float64 `json:"time"`
+}
+
+type ErrorInfo struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ Details map[string]interface{} `json:"details,omitempty"`
+}
+
+type SearchResult struct {
+ Items []SearchItem `json:"items"`
+ Query string `json:"query"`
+ Total int `json:"total"`
+}
+
+type SearchItem struct {
+ URI string `json:"uri"`
+ Score float64 `json:"score"`
+ Content string `json:"content"`
+ Abstract string `json:"abstract,omitempty"`
+}
+
+type FindOptions struct {
+ URI string
+ Limit int
+ Threshold float64
+}
+
+// ... 其他类型
+```
+
+4. **错误处理**:
+```go
+// errors.go
+package openviking
+
+import "fmt"
+
+type OpenVikingError struct {
+ Code string
+ Message string
+ Details map[string]interface{}
+}
+
+func (e *OpenVikingError) Error() string {
+ return fmt.Sprintf("[%s] %s", e.Code, e.Message)
+}
+
+var (
+ ErrNotFound = &OpenVikingError{Code: "NOT_FOUND"}
+ ErrInvalidURI = &OpenVikingError{Code: "INVALID_URI"}
+ ErrUnavailable = &OpenVikingError{Code: "UNAVAILABLE"}
+ // ... 其他错误
+)
+```
+
+5. **HTTP 请求封装**:
+```go
+func (c *Client) post(path string, body interface{}) (*Response, error) {
+ jsonBody, err := json.Marshal(body)
+ if err != nil {
+ return nil, err
+ }
+
+ req, err := http.NewRequest("POST", c.config.URL+path, bytes.NewBuffer(jsonBody))
+ if err != nil {
+ return nil, err
+ }
+
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("X-API-Key", c.config.APIKey)
+
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return nil, err
+ }
+ defer resp.Body.Close()
+
+ var response Response
+ if err := json.NewDecoder(resp.Body).Decode(&response); err != nil {
+ return nil, err
+ }
+
+ if response.Status == "error" {
+ return nil, &OpenVikingError{
+ Code: response.Error.Code,
+ Message: response.Error.Message,
+ Details: response.Error.Details,
+ }
+ }
+
+ return &response, nil
+}
+```
+
+### 验收标准
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/openviking/openviking-go"
+)
+
+func main() {
+ client := openviking.NewClient(openviking.Config{
+ URL: "http://localhost:8000",
+ APIKey: "your-api-key",
+ })
+
+ // 搜索
+ results, err := client.Find("how to configure", &openviking.FindOptions{
+ Limit: 10,
+ })
+ if err != nil {
+ panic(err)
+ }
+ for _, item := range results.Items {
+ fmt.Printf("%s: %.2f\n", item.URI, item.Score)
+ }
+
+ // 读取
+ content, err := client.Read("viking://resources/doc.md")
+ if err != nil {
+ panic(err)
+ }
+ fmt.Println(content.Content)
+}
+```
+
+### 依赖
+- T2 (HTTP Server) 必须先完成
+
+### 参考文件
+- `design/server-cli-design.md` - 7.3 节 API 端点
+- `openviking/server/models.py` - 响应模型定义
+
+---
+
+## 附录:异常类定义
+
+所有任务共用的异常类定义,应在 T1 中创建 `openviking/exceptions.py`:
+
+```python
+class OpenVikingError(Exception):
+ """Base exception for all OpenViking errors."""
+ def __init__(self, code: str, message: str, details: dict = None):
+ self.code = code
+ self.message = message
+ self.details = details or {}
+ super().__init__(f"[{code}] {message}")
+
+# 参数错误
+class InvalidArgumentError(OpenVikingError): pass
+class InvalidURIError(InvalidArgumentError): pass
+
+# 资源错误
+class NotFoundError(OpenVikingError): pass
+class AlreadyExistsError(OpenVikingError): pass
+
+# 认证/权限错误
+class UnauthenticatedError(OpenVikingError): pass
+class PermissionDeniedError(OpenVikingError): pass
+
+# 服务错误
+class UnavailableError(OpenVikingError): pass
+class InternalError(OpenVikingError): pass
+class DeadlineExceededError(OpenVikingError): pass
+
+# 业务错误
+class ProcessingError(OpenVikingError): pass
+class EmbeddingFailedError(OpenVikingError): pass
+class SessionExpiredError(OpenVikingError): pass
+```
+
+---
+
+## 附录:错误码映射
+
+```python
+ERROR_CODE_TO_HTTP_STATUS = {
+ "OK": 200,
+ "INVALID_ARGUMENT": 400,
+ "INVALID_URI": 400,
+ "NOT_FOUND": 404,
+ "ALREADY_EXISTS": 409,
+ "PERMISSION_DENIED": 403,
+ "UNAUTHENTICATED": 401,
+ "RESOURCE_EXHAUSTED": 429,
+ "FAILED_PRECONDITION": 412,
+ "ABORTED": 409,
+ "DEADLINE_EXCEEDED": 504,
+ "UNAVAILABLE": 503,
+ "INTERNAL": 500,
+ "UNIMPLEMENTED": 501,
+ "PROCESSING": 202,
+ "EMBEDDING_FAILED": 500,
+ "VLM_FAILED": 500,
+ "SESSION_EXPIRED": 410,
+}
+```
diff --git a/docs/design/server_client/server-cli-design.md b/docs/design/server_client/server-cli-design.md
new file mode 100644
index 000000000..d05955445
--- /dev/null
+++ b/docs/design/server_client/server-cli-design.md
@@ -0,0 +1,1484 @@
+# OpenViking Server/CLI 模式技术方案
+
+## 一、背景与目标
+
+### 1.1 当前架构
+
+OpenViking 目前主要以 Python SDK 形式提供服务,支持两种部署模式:
+- **Embedded 模式**:自动启动本地 AGFS 子进程和 VikingVectorIndex(单例)
+- **Service 模式**:连接远程 AGFS 和 VectorDB 服务(非单例)
+
+### 1.2 现有问题
+
+| 问题 | 描述 |
+|------|------|
+| 缺少统一 CLI | 无法通过命令行管理 OpenViking |
+| 服务分散 | AGFS 和 VectorDB 需要分别启动 |
+| 无 HTTP API | 核心功能没有 HTTP API 暴露 |
+| 部署复杂 | 生产环境需要手动协调多个服务 |
+
+### 1.3 目标
+
+1. **CLI 模式**:提供完整的命令行工具
+2. **Server 模式**:提供统一的 HTTP API 服务
+3. **保持兼容**:现有 SDK 使用方式不变
+
+---
+
+## 二、竞品分析与最佳实践
+
+### 2.1 竞品对比
+
+| 产品 | CLI 设计 | Server 模式 | API 风格 | 部署模式 |
+|------|----------|-------------|----------|----------|
+| **Chroma** | `chroma run/db/login` | 内置 FastAPI | RESTful | in-memory/persistent/client-server |
+| **Qdrant** | 无独立 CLI | 独立服务 | RESTful + gRPC | standalone/distributed |
+| **Milvus** | `milvus_cli` 交互式 | 独立服务 | RESTful + gRPC | lite/standalone/distributed |
+| **Mem0** | 无 CLI | Platform + OSS | RESTful | managed/self-hosted |
+| **LlamaIndex** | 无统一 CLI | 微服务架构 | RESTful | self-hosted |
+
+### 2.2 Chroma 设计参考
+
+Chroma 的 CLI 设计简洁实用:
+```bash
+chroma run --path <directory> # 启动服务器
+chroma db create <name> # 创建数据库
+chroma login # 认证登录
+chroma browse # 浏览数据
+```
+
+**借鉴点**:
+- 三种运行模式(in-memory/persistent/client-server)
+- 简洁的命令结构
+- 环境变量配置支持
+
+### 2.3 Qdrant API 设计参考
+
+Qdrant 的 REST API 采用资源层级结构:
+```
+POST /collections/{collection_name}/points/search
+GET /collections/{collection_name}/points/{id}
+PUT /collections/{collection_name}/points
+```
+
+**借鉴点**:
+- 资源层级 URL 设计
+- POST 用于复杂查询(请求体包含向量和过滤条件)
+- 完善的过滤 DSL
+- 一致性级别控制
+
+### 2.4 Milvus CLI 设计参考
+
+Milvus CLI 采用模块化架构:
+```
+milvus_cli/
+├── Connection.py # 连接管理
+├── Collection.py # 集合操作
+├── Database.py # 数据库管理
+├── Index.py # 索引管理
+├── Partition.py # 分区管理
+├── Data.py # 数据操作
+├── Role.py # 角色管理
+└── User.py # 用户管理
+```
+
+**借鉴点**:
+- 模块化命令组织
+- 交互式 CLI 支持
+- 完整的 RBAC 支持
+
+### 2.5 Mem0 架构参考
+
+Mem0 的双部署模式:
+- **Platform API**:托管服务,API Key 认证
+- **OSS SDK**:自托管,直接调用
+
+**借鉴点**:
+- 统一的搜索管道(Platform 和 OSS 共用)
+- 复杂的过滤 DSL(AND/OR 逻辑)
+- 用户隔离(user_id scoping)
+
+### 2.6 Redis/MySQL 客户端设计参考
+
+Redis 和 MySQL 的客户端设计模式:
+- **Server 独立运行**:Server 作为独立进程启动,不依赖 Client
+- **Client 仅连接**:Client 只负责连接 Server,不负责启动或管理 Server
+- **配置分离**:Server 配置和 Client 配置分开管理
+
+```python
+# Redis 示例
+import redis
+r = redis.Redis(host='localhost', port=6379) # 仅连接,不启动 Server
+r.set('foo', 'bar')
+
+# MySQL 示例
+import mysql.connector
+conn = mysql.connector.connect(host='localhost', user='root') # 仅连接
+```
+
+**借鉴点**:
+- Client 无需 `initialize()` 方法
+- 连接参数通过构造函数传入
+- Server 生命周期独立于 Client
+
+### 2.7 响应格式与错误处理最佳实践
+
+#### Qdrant 响应格式
+```json
+{
+ "status": "ok",
+ "time": 0.123,
+ "result": {...},
+ "usage": {"cpu": 100, "vector_io_read": 40}
+}
+```
+- 统一的 `status/time/result` 包装
+- 可选的 `usage` 字段用于资源监控
+- 错误通过 HTTP 状态码 + 消息字符串返回
+
+#### Milvus 错误码
+```python
+# 数字错误码 + 消息
+(code=1, message="UnexpectedError...")
+(code=2, message="Connection timeout...")
+(code=2200, message="Retry exhausted...")
+```
+- 基于 gRPC 的数字错误码
+- 包含 `code`, `message`, `reason` 三元组
+
+#### gRPC 标准状态码(业界标准)
+| 码 | 名称 | HTTP | 说明 |
+|----|------|------|------|
+| 0 | OK | 200 | 成功 |
+| 3 | INVALID_ARGUMENT | 400 | 参数无效 |
+| 5 | NOT_FOUND | 404 | 资源不存在 |
+| 7 | PERMISSION_DENIED | 403 | 权限不足 |
+| 13 | INTERNAL | 500 | 内部错误 |
+| 14 | UNAVAILABLE | 503 | 服务不可用 |
+| 16 | UNAUTHENTICATED | 401 | 未认证 |
+
+**借鉴点**:
+- gRPC 17 种标准状态码覆盖所有常见场景
+- 明确的 HTTP 状态码映射
+- 可重试 vs 不可重试错误分类
+
+### 2.8 最佳实践总结
+
+| 方面 | 最佳实践 | 来源 |
+|------|----------|------|
+| **CLI 结构** | 动词-名词命令(`run`, `db create`) | Chroma |
+| **API 路由** | 资源层级(`/collections/{name}/points`) | Qdrant |
+| **认证** | API Key + 可选 JWT | Qdrant, Mem0 |
+| **部署模式** | 三层(embedded/standalone/distributed) | Milvus |
+| **过滤系统** | JSON DSL(AND/OR/比较操作符) | Mem0, Qdrant |
+| **模块化** | 按资源类型组织命令 | Milvus |
+| **Client 设计** | 仅连接,不管理 Server 生命周期 | Redis, MySQL |
+| **响应格式** | `{status, time, result}` 统一包装 | Qdrant |
+| **错误码** | gRPC 标准状态码(字符串形式) | gRPC, Milvus |
+| **HTTP 映射** | 错误码到 HTTP 状态码的标准映射 | gRPC |
+
+### 2.9 参考资料
+
+- [Chroma Documentation](https://docs.trychroma.com/) - CLI 设计参考
+- [Qdrant API Reference](https://api.qdrant.tech/) - REST API 设计参考
+- [Milvus CLI](https://github.com/zilliztech/milvus_cli) - 模块化 CLI 参考
+- [Mem0 Documentation](https://docs.mem0.ai/) - 双部署模式参考
+- [LlamaIndex Architecture](https://developers.llamaindex.ai/python/cloud/self_hosting/architecture/) - 微服务架构参考
+- [gRPC Status Codes](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) - 标准错误码定义
+- [gRPC HTTP Mapping](https://grpc.github.io/grpc/core/md_doc_http-grpc-status-mapping.html) - HTTP 状态码映射
+- [Qdrant Common Errors](https://qdrant.tech/documentation/guides/common-errors/) - 错误处理参考
+- [Chroma Troubleshooting](https://docs.trychroma.com/troubleshooting) - 异常类设计参考
+
+---
+
+## 三、架构设计
+
+### 3.0 接口定位
+
+OpenViking 提供三种接口,面向不同使用场景:
+
+| 接口 | 使用者 | 场景 | 特点 |
+|------|--------|------|------|
+| **Python SDK** | Agent 开发者 | Agent 代码中调用 | 对象化 API,支持异步,client 实例维护状态 |
+| **Bash CLI** | Agent / 运维人员 | Agent subprocess 调用、运维脚本 | 非交互式,通过环境变量管理状态 |
+| **HTTP API** | 任意语言客户端 | 跨语言集成、微服务调用 | RESTful,无状态,每次请求带身份信息 |
+
+**选型建议**:
+- **Agent 开发**:优先使用 Python SDK,可以维护 client 实例状态
+- **Agent 调用外部工具**:使用 Bash CLI,通过环境变量传递身份信息
+- **非 Python 环境**:使用 HTTP API
+
+### 3.1 分层架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ CLI Layer │
+│ openviking <command> [options] │
+└─────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Client Layer │
+│ ┌─────────────────┐ ┌─────────────────┐ │
+│ │ LocalClient │ │ HTTPClient │ │
+│ │ (直接调用Service)│ │ (HTTP调用Server)│ │
+│ └─────────────────┘ └─────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Service Layer │
+│ ┌─────────────────────────────────────────────────────────┐│
+│ │ OpenVikingService ││
+│ │ - ResourceService (资源解析、向量化) ││
+│ │ - SearchService (语义搜索) ││
+│ │ - SessionService (会话管理) ││
+│ │ - FSService (文件系统操作) ││
+│ └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Infrastructure Layer │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
+│ │ VikingFS │ │ VikingDB │ │ AGFS │ │
+│ └─────────────┘ └─────────────┘ └─────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 部署模式
+
+#### 选型决策
+
+**为什么支持多种部署模式**:
+
+1. **嵌入式模式**:降低入门门槛,开发者无需部署服务即可使用
+2. **独立服务模式**:支持团队共享、多 Agent 并发访问
+3. **混合模式**:灵活组合,适应不同基础设施环境
+
+**参考业界实践**:
+- Chroma:in-memory / persistent / client-server 三种模式
+- Milvus:lite / standalone / distributed 三种模式
+- SQLite:嵌入式 vs PostgreSQL/MySQL 独立服务
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| **嵌入式** | SDK 自动启动本地 AGFS + VectorDB | 本地开发、单机部署 |
+| **独立服务** | 通过 CLI 启动 Server,SDK/CLI 通过 HTTP 连接 | 团队共享、生产环境 |
+| **混合模式** | 本地 Server + 远程 AGFS/VectorDB | 分布式部署 |
+
+```
+嵌入式模式:
+┌─────────────────────────────────────┐
+│ Python Process │
+│ ┌─────────┐ ┌─────────┐ │
+│ │ SDK │──│ Service │ │
+│ └─────────┘ └────┬────┘ │
+│ │ │
+│ ┌─────────┐ ┌────┴────┐ │
+│ │ AGFS │ │ VectorDB│ │
+│ └─────────┘ └─────────┘ │
+└─────────────────────────────────────┘
+
+独立服务模式:
+┌─────────────┐ ┌─────────────────────────────────────┐
+│ CLI / SDK │─HTTP─│ OpenViking Server │
+│ (Client) │ │ ┌─────────┐ ┌─────────┐ │
+└─────────────┘ │ │ Service │──│ AGFS │ │
+ │ └────┬────┘ └─────────┘ │
+ │ │ │
+ │ ┌────┴────┐ │
+ │ │ VectorDB│ │
+ │ └─────────┘ │
+ └─────────────────────────────────────┘
+```
+
+### 3.3 身份与隔离
+
+支持多租户场景,通过 `user` 和 `agent` 实现数据隔离:
+
+| 参数 | 说明 | 作用域 |
+|------|------|--------|
+| `user` | 用户标识 | `viking://user/{user}/memories/` |
+| `agent` | Agent 标识 | `viking://agent/{agent}/memories/` |
+
+### 3.4 配置管理
+
+#### Server 配置 (`~/.openviking/server.yaml`)
+
+```yaml
+storage:
+ path: ~/.openviking/data
+
+server:
+ host: 0.0.0.0
+ port: 8000
+ api_key: your-api-key
+
+embedding:
+ provider: openai
+ model: text-embedding-3-small
+ api_key: ${OPENAI_API_KEY}
+
+vlm:
+ provider: openai
+ model: gpt-4o
+ api_key: ${OPENAI_API_KEY}
+```
+
+#### Client 配置 (`~/.openviking/client.yaml`)
+
+```yaml
+url: http://localhost:8000
+api_key: your-api-key
+# 注意:user 和 agent 通过环境变量管理,不存配置文件
+```
+
+#### 环境变量
+
+| 环境变量 | 说明 | 示例 |
+|----------|------|------|
+| `OPENVIKING_URL` | Server URL | `http://localhost:8000` |
+| `OPENVIKING_API_KEY` | API Key | `sk-xxx` |
+| `OPENVIKING_USER` | 用户标识 | `alice` |
+| `OPENVIKING_AGENT` | Agent 标识 | `agent-a1` |
+| `OPENVIKING_PATH` | 本地数据路径(嵌入式模式) | `./data` |
+
+**为什么 `user`/`agent` 用环境变量而不是配置文件**:
+1. **进程隔离**:环境变量是进程级的,多个 Agent 进程互不干扰
+2. **无并发冲突**:不会出现多个进程同时写配置文件的问题
+3. **易于设置**:Agent 启动时设置一次,后续调用自动继承
+
+#### 配置优先级
+
+从高到低:
+1. 命令行参数(`--url`, `--user` 等)
+2. 环境变量(`OPENVIKING_URL`, `OPENVIKING_USER` 等)
+3. 配置文件(`~/.openviking/client.yaml`)
+
+---
+
+## 四、模块设计
+
+### 4.1 模块职责
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| **service/** | 核心业务逻辑,与传输层无关 | Infrastructure Layer |
+| **server/** | HTTP API 服务,调用 Service 层 | service/ |
+| **cli/** | 命令行工具,调用 Client 层 | client/ |
+| **client/** | 客户端抽象,支持本地和 HTTP 两种模式 | service/ 或 HTTP |
+
+**设计原则**:
+- **Service 层独立**:业务逻辑不依赖传输层(HTTP/CLI),便于测试和复用
+- **Client 层抽象**:LocalClient 和 HTTPClient 实现相同接口,上层无感知
+- **CLI 薄层**:CLI 只负责参数解析和输出格式化,业务逻辑在 Service 层
+
+### 4.2 目录结构
+
+```
+openviking/
+├── service/ # Service 层(业务逻辑)
+│ ├── __init__.py
+│ ├── core.py # OpenVikingService
+│ ├── fs_service.py # 文件系统操作
+│ ├── resource_service.py # 资源导入、技能添加
+│ ├── search_service.py # 语义搜索
+│ ├── session_service.py # 会话管理
+│ ├── relation_service.py # 关联管理
+│ └── pack_service.py # 导入导出
+│
+├── server/ # HTTP Server
+│ ├── __init__.py
+│ ├── app.py # FastAPI 应用
+│ ├── bootstrap.py # 服务启动器
+│ ├── config.py # 服务器配置
+│ ├── dependencies.py # 依赖注入
+│ └── routers/
+│ ├── resources.py # /api/v1/resources
+│ ├── filesystem.py # /api/v1/fs
+│ ├── content.py # /api/v1/content
+│ ├── search.py # /api/v1/search
+│ ├── relations.py # /api/v1/relations
+│ └── sessions.py # /api/v1/sessions
+│
+├── cli/ # CLI 模块
+│ ├── __init__.py
+│ ├── main.py # CLI 入口
+│ └── output.py # 输出格式化
+│
+├── client/ # Client 层
+│ ├── __init__.py
+│ ├── local.py # LocalClient
+│ └── http.py # HTTPClient
+│
+├── async_client.py # 兼容层
+└── sync_client.py # 兼容层
+```
+
+### 4.3 pyproject.toml
+
+```toml
+[project.scripts]
+openviking = "openviking.cli.main:app"
+```
+
+### 4.4 新增依赖
+
+```toml
+dependencies = [
+ # ... 现有依赖
+ "typer>=0.9.0", # CLI 框架
+ "rich>=13.0.0", # CLI 美化输出
+]
+```
+
+---
+
+## 五、接口设计
+
+### 5.1 核心方法定义
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `add_resource` | `path, target, wait, timeout` | 导入资源 |
+| `add_skill` | `data, wait` | 添加技能 |
+| `ls` | `uri, simple, recursive` | 列出目录 |
+| `tree` | `uri` | 目录树 |
+| `stat` | `uri` | 状态信息 |
+| `mkdir` | `uri` | 创建目录 |
+| `rm` | `uri, recursive` | 删除 |
+| `mv` | `from_uri, to_uri` | 移动 |
+| `read` | `uri` | 读取完整内容 (L2) |
+| `abstract` | `uri` | 读取摘要 (L0) |
+| `overview` | `uri` | 读取概览 (L1) |
+| `find` | `query, target_uri, limit, threshold` | 语义搜索 |
+| `search` | `query, target_uri, session, limit` | 带上下文搜索 |
+| `grep` | `uri, pattern, case_insensitive` | 内容搜索 |
+| `glob` | `pattern, uri` | 模式匹配 |
+| `link` | `from_uri, uris, reason` | 创建关联 |
+| `unlink` | `from_uri, uri` | 删除关联 |
+| `relations` | `uri` | 查看关联 |
+| `export_ovpack` | `uri, to` | 导出 |
+| `import_ovpack` | `file, target, force, vectorize` | 导入 |
+| `session` | `user` | 创建/获取 Session 对象 |
+| `sessions` | - | 获取所有 Session 对象列表 |
+| `wait_processed` | `timeout` | 等待处理完成 |
+
+**Session 对象方法:**
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `add_message` | `role, content` | 添加消息 |
+| `compress` | - | 压缩会话 |
+| `extract` | - | 提取记忆 |
+| `delete` | - | 删除会话 |
+
+### 5.2 统一返回值格式
+
+参考 Qdrant 的响应格式设计,采用 `{status, time, result}` 统一包装:
+
+**成功响应**:
+```json
+{
+ "status": "ok",
+ "result": {...},
+ "time": 0.123,
+ "usage": { // 可选,用于监控
+ "tokens": 100,
+ "vectors_scanned": 1000
+ }
+}
+```
+
+**错误响应**:
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "NOT_FOUND", // gRPC 风格错误码
+ "message": "Resource not found: viking://...",
+ "details": {...} // 可选,额外错误信息
+ },
+ "time": 0.05
+}
+```
+
+**Python 数据模型**:
+```python
+@dataclass
+class Response:
+ status: str # "ok" | "error"
+ result: Optional[Any] = None
+ error: Optional[ErrorInfo] = None
+ time: float = 0.0
+ usage: Optional[UsageInfo] = None
+
+@dataclass
+class ErrorInfo:
+ code: str # NOT_FOUND, INVALID_URI, ...
+ message: str
+ details: Optional[dict] = None
+
+@dataclass
+class UsageInfo:
+ tokens: Optional[int] = None
+ vectors_scanned: Optional[int] = None
+```
+
+### 5.3 各方法返回值
+
+**ls / tree**
+```json
+{
+ "status": "ok",
+ "result": {
+ "entries": [
+ {"name": "doc.md", "type": "file", "uri": "viking://resources/doc.md", "size": 1024},
+ {"name": "images/", "type": "dir", "uri": "viking://resources/images/", "children_count": 5}
+ ]
+ },
+ "time": 0.05
+}
+```
+
+**find / search**
+```json
+{
+ "status": "ok",
+ "result": {
+ "items": [
+ {
+ "uri": "viking://resources/doc.md",
+ "score": 0.92,
+ "content": "...",
+ "abstract": "...",
+ "metadata": {"type": "markdown", "scope": "resources"}
+ }
+ ],
+ "query": "how to use openviking",
+ "total": 10
+ },
+ "time": 0.15,
+ "usage": {"vectors_scanned": 1000}
+}
+```
+
+**read / abstract / overview**
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/doc.md",
+ "content": "...",
+ "level": "L2"
+ },
+ "time": 0.02
+}
+```
+
+**stat**
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/doc.md",
+ "type": "file",
+ "size": 1024,
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-02T00:00:00Z",
+ "has_abstract": true,
+ "has_overview": true,
+ "vectorized": true
+ },
+ "time": 0.01
+}
+```
+
+**add_resource**
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/my-docs/",
+ "files_count": 10,
+ "processing_status": "processing",
+ "queue": {
+ "vectorize": {"processed": 5, "total": 10, "failed": 0}
+ }
+ },
+ "time": 0.5
+}
+```
+
+**session**(Python CLI 返回 Session 对象,HTTP API 返回 JSON)
+```python
+# Python CLI
+session = client.session(user="alice")
+session.id # "session-abc123"
+session.user # "alice"
+session.created_at # datetime
+session.message_count # 10
+session.compressed # False
+
+# HTTP API 返回
+{
+ "status": "ok",
+ "result": {
+ "session_id": "session-abc123",
+ "user": "alice",
+ "created_at": "2024-01-01T00:00:00Z",
+ "message_count": 10,
+ "compressed": false
+ },
+ "time": 0.02
+}
+```
+
+**错误示例**
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "NOT_FOUND",
+ "message": "Resource not found: viking://resources/nonexistent/"
+ },
+ "time": 0.01
+}
+```
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "INVALID_URI",
+ "message": "Invalid URI format: 'invalid-uri'",
+ "details": {
+ "expected": "viking://<scope>/<path>",
+ "received": "invalid-uri"
+ }
+ },
+ "time": 0.001
+}
+```
+
+### 5.4 错误处理
+
+基于 gRPC 标准状态码,结合 OpenViking 业务场景定制。
+
+#### 通用错误码(基于 gRPC 标准)
+
+| 错误码 | HTTP 状态 | 说明 | 适用场景 |
+|--------|-----------|------|----------|
+| `OK` | 200 | 成功 | 所有成功操作 |
+| `INVALID_ARGUMENT` | 400 | 参数无效 | URI 格式错误、参数缺失、类型错误 |
+| `NOT_FOUND` | 404 | 资源不存在 | URI 指向的资源不存在 |
+| `ALREADY_EXISTS` | 409 | 资源已存在 | 创建重复资源、重复导入 |
+| `PERMISSION_DENIED` | 403 | 权限不足 | API Key 无权限、用户隔离 |
+| `UNAUTHENTICATED` | 401 | 未认证 | API Key 缺失或无效 |
+| `RESOURCE_EXHAUSTED` | 429 | 资源耗尽 | 配额超限、速率限制 |
+| `FAILED_PRECONDITION` | 412 | 前置条件失败 | 资源未就绪、依赖缺失 |
+| `ABORTED` | 409 | 操作中止 | 并发冲突、事务失败 |
+| `DEADLINE_EXCEEDED` | 504 | 超时 | 处理超时、等待超时 |
+| `UNAVAILABLE` | 503 | 服务不可用 | AGFS/VectorDB 不可用 |
+| `INTERNAL` | 500 | 内部错误 | 未预期的服务端错误 |
+| `UNIMPLEMENTED` | 501 | 未实现 | 功能未实现 |
+
+#### OpenViking 特定错误码
+
+| 错误码 | HTTP 状态 | 说明 | 适用场景 |
+|--------|-----------|------|----------|
+| `INVALID_URI` | 400 | URI 格式无效 | `viking://` 协议解析失败 |
+| `PROCESSING` | 202 | 处理中 | 资源正在处理,尚未就绪 |
+| `EMBEDDING_FAILED` | 500 | 向量化失败 | Embedding API 调用失败 |
+| `VLM_FAILED` | 500 | VLM 调用失败 | 摘要/概览生成失败 |
+| `SESSION_EXPIRED` | 410 | 会话过期 | 会话已被删除或过期 |
+
+#### Python 异常类
+
+参考 Chroma 的特定异常类设计,异常类与错误码一一对应:
+
+```python
+# openviking/exceptions.py
+
+class OpenVikingError(Exception):
+ """Base exception for all OpenViking errors."""
+ def __init__(self, code: str, message: str, details: dict = None):
+ self.code = code
+ self.message = message
+ self.details = details or {}
+ super().__init__(f"[{code}] {message}")
+
+# 参数错误
+class InvalidArgumentError(OpenVikingError): pass
+class InvalidURIError(InvalidArgumentError): pass
+
+# 资源错误
+class NotFoundError(OpenVikingError): pass
+class AlreadyExistsError(OpenVikingError): pass
+
+# 认证/权限错误
+class UnauthenticatedError(OpenVikingError): pass
+class PermissionDeniedError(OpenVikingError): pass
+
+# 服务错误
+class UnavailableError(OpenVikingError): pass
+class InternalError(OpenVikingError): pass
+class DeadlineExceededError(OpenVikingError): pass
+
+# 业务错误
+class ProcessingError(OpenVikingError): pass
+class EmbeddingFailedError(OpenVikingError): pass
+class SessionExpiredError(OpenVikingError): pass
+```
+
+**错误码到异常的映射**:
+```python
+ERROR_CODE_TO_EXCEPTION = {
+ "INVALID_ARGUMENT": InvalidArgumentError,
+ "INVALID_URI": InvalidURIError,
+ "NOT_FOUND": NotFoundError,
+ "ALREADY_EXISTS": AlreadyExistsError,
+ "UNAUTHENTICATED": UnauthenticatedError,
+ "PERMISSION_DENIED": PermissionDeniedError,
+ "UNAVAILABLE": UnavailableError,
+ "INTERNAL": InternalError,
+ "DEADLINE_EXCEEDED": DeadlineExceededError,
+ "PROCESSING": ProcessingError,
+ "EMBEDDING_FAILED": EmbeddingFailedError,
+ "SESSION_EXPIRED": SessionExpiredError,
+}
+
+def raise_for_error(response: dict):
+ """Convert error response to exception."""
+ if response.get("status") == "error":
+ error = response["error"]
+ exc_class = ERROR_CODE_TO_EXCEPTION.get(error["code"], OpenVikingError)
+ raise exc_class(error["code"], error["message"], error.get("details", {}))
+```
+
+---
+
+## 六、CLI 实现
+
+### 6.1 Bash CLI
+
+#### 模式选型:非交互式 CLI
+
+**选型决策**:采用非交互式 CLI。
+
+**为什么选择非交互式**:
+
+1. **Agent 调用场景**:Agent 通过 subprocess 调用 CLI,非交互式更自然
+2. **无状态设计**:每次调用独立,避免状态污染和并发冲突
+3. **易于集成**:可以直接在 shell 脚本、CI/CD 中使用
+4. **参考业界实践**:kubectl、aws cli、gh cli 都是非交互式设计
+
+#### 多 Agent 场景
+
+OpenViking 支持多 user、多 agent,CLI 需要处理多进程并发场景:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ OpenViking Server │
+│ │
+│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
+│ │ user:alice│ │ user:bob │ │ user:carol│ │
+│ │ agent:a1 │ │ agent:b1 │ │ agent:c1 │ │
+│ └──────────┘ └──────────┘ └──────────┘ │
+└─────────────────────────────────────────────────────────────┘
+ ▲ ▲ ▲
+ │ │ │
+ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
+ │ Agent A │ │ Agent B │ │ Agent C │
+ │ (进程1) │ │ (进程2) │ │ (进程3) │
+ └─────────┘ └─────────┘ └─────────┘
+```
+
+多个 Agent 进程可能同时运行,各自有不同的 user/agent 身份。因此 `user`/`agent` 通过环境变量管理(详见 3.4 配置管理)。
+
+#### 使用示例
+
+**Agent 调用场景**:
+```bash
+# Agent 启动时设置环境变量
+export OPENVIKING_URL=http://localhost:8000
+export OPENVIKING_API_KEY=sk-xxx
+export OPENVIKING_USER=alice
+export OPENVIKING_AGENT=agent-a1
+
+# 后续 CLI 调用自动使用环境变量,无需重复指定
+openviking find "how to use openviking"
+openviking ls viking://resources/
+openviking read viking://resources/doc.md
+```
+
+**临时覆盖**:
+```bash
+# 命令行参数覆盖环境变量
+openviking --user bob find "query"
+```
+
+#### 设计原则
+
+1. **与接口一致**:命令名、参数与接口定义保持一致
+2. **体现核心特性**:突出文件系统范式、分层上下文、语义搜索、会话管理
+3. **简洁直观**:常用操作简单,复杂操作通过子命令组织
+
+#### 命令列表
+
+```bash
+# 服务管理
+openviking serve --path <dir> [--port 8000] [--host 0.0.0.0]
+openviking serve --port 8000 --agfs-url <url> --vectordb-url <url>
+openviking status
+
+# 资源导入
+openviking add-resource <path> [--to <uri>] [--wait] [--timeout N]
+openviking add-skill <file> [--wait]
+
+# 文件系统操作
+openviking ls <uri> [--simple] [--recursive]
+openviking tree <uri>
+openviking stat <uri>
+openviking mkdir <uri>
+openviking rm <uri> [--recursive]
+openviking mv <from> <to>
+
+# 内容读取
+openviking read <uri>
+openviking abstract <uri>
+openviking overview <uri>
+
+# 搜索
+openviking find <query> [<uri>] [--limit N] [--threshold F]
+openviking search <query> [<uri>] [--session-id ID] [--limit N]
+openviking grep <uri> <pattern> [-i]
+openviking glob <pattern> [<uri>]
+
+# 关联管理
+openviking link <from> <to>... [--reason TEXT]
+openviking unlink <from> <to>
+openviking relations <uri>
+
+# 会话管理
+openviking session new [--user <name>]
+openviking session list
+openviking session get <id>
+openviking session compress <id>
+openviking session extract <id>
+
+# 导入导出
+openviking export <uri> <file.ovpack>
+openviking import <file.ovpack> <uri> [--force] [--no-vectorize]
+
+# 工具命令
+openviking wait [--timeout N]
+openviking config show
+openviking config init
+```
+
+#### 命令分组说明
+
+| 命令组 | 体现特性 | 说明 |
+|--------|----------|------|
+| `add-resource/add-skill` | 自动处理 | 导入后自动解析、分层、向量化 |
+| `ls/tree/stat/mkdir/rm/mv` | 文件系统范式 | 像操作文件一样管理上下文 |
+| `read/abstract/overview` | 分层上下文 | L0/L1/L2 按需加载 |
+| `find/search` | 目录递归检索 | 语义搜索 + 目录定位 |
+| `session *` | 会话管理 | 自动压缩、记忆提取 |
+
+#### 实现 (使用 Typer)
+
+```python
+# openviking/cli/main.py
+import typer
+from rich.console import Console
+
+app = typer.Typer(name="openviking", help="OpenViking - Context Database for AI Agents")
+console = Console()
+
+# 顶层命令
+def serve(port: int = 8000, host: str = "0.0.0.0"):
+ """Start OpenViking server."""
+ ...
+
+def ls(uri: str, simple: bool = False, recursive: bool = False):
+ """List directory contents."""
+ ...
+
+def find(query: str, uri: str = "viking://", limit: int = 10):
+ """Semantic search."""
+ ...
+
+# 子命令组
+session_app = typer.Typer(help="Session management")
+app.add_typer(session_app, name="session")
+
+@session_app.command("new")
+def session_new(user: str = None):
+ """Create new session."""
+ ...
+```
+
+---
+
+### 6.2 Python SDK
+
+#### 使用方式
+
+```python
+from openviking import OpenViking
+
+# 嵌入式模式
+client = OpenViking(path="./data")
+
+# HTTP 模式
+client = OpenViking(url="http://localhost:8000", api_key="xxx")
+```
+
+#### 完整示例
+
+```python
+from openviking import OpenViking
+
+# 连接
+client = OpenViking(url="http://localhost:8000", api_key="xxx")
+
+# 导入资源
+result = client.add_resource("./docs/", target="viking://resources/my-docs/", wait=True)
+print(f"导入完成: {result.data.uri}, 文件数: {result.data.files_count}")
+
+# 分层读取
+abstract = client.abstract("viking://resources/my-docs/") # L0
+overview = client.overview("viking://resources/my-docs/") # L1
+content = client.read("viking://resources/my-docs/README.md") # L2
+
+# 语义搜索
+results = client.find("how to configure", target_uri="viking://resources/my-docs/", limit=10)
+for r in results.data.results:
+ print(f"{r.uri}: {r.score:.2f}")
+
+# 会话管理(OOP 模式)
+session = client.session(user="alice")
+session.add_message("user", "What is OpenViking?")
+results = client.search("What is OpenViking?", session=session)
+
+# Session 操作
+session.compress()
+memories = session.extract()
+
+# 获取所有 session
+all_sessions = client.sessions()
+```
+
+#### 实现方式
+
+```python
+class Session:
+ """Session 对象,封装会话操作"""
+ def __init__(self, client, session_id: str, user: str):
+ self._client = client
+ self.id = session_id
+ self.user = user
+
+ def add_message(self, role: str, content: str):
+ """添加消息"""
+ ...
+
+ def compress(self):
+ """压缩会话"""
+ ...
+
+ def extract(self):
+ """提取记忆"""
+ ...
+
+class OpenViking:
+ def __init__(
+ self,
+ path: Optional[str] = None,
+ url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ user: Optional[str] = None,
+ agent: Optional[str] = None,
+ ):
+ if url:
+ self._backend = HTTPBackend(url, api_key)
+ else:
+ self._backend = LocalBackend(path)
+ self._user = user
+ self._agent_id = agent
+
+ def session(self, user: str = None) -> Session:
+ """创建或获取 Session 对象"""
+ ...
+
+ def sessions(self) -> List[Session]:
+ """获取所有 Session 对象"""
+ ...
+```
+
+### 6.3 使用指南
+
+#### 安装
+
+```bash
+pip install openviking
+```
+
+#### 环境变量
+
+详见 3.4 配置管理中的环境变量定义。
+
+#### viking:// 目录结构
+
+```
+viking://
+├── resources/ # 外部资源(文档、代码等)
+├── user/
+│ └── memories/ # 用户记忆
+├── agent/
+│ ├── memories/ # Agent 记忆
+│ ├── skills/ # Agent 技能
+│ └── instructions/ # Agent 指令
+└── session/ # 会话数据
+```
+
+#### 分层上下文
+
+| 层级 | 方法 | 说明 | 适用场景 |
+|------|------|------|----------|
+| L0 | `abstract()` | 一句话摘要 | 快速浏览、列表展示 |
+| L1 | `overview()` | 核心信息 | 初步了解、决策参考 |
+| L2 | `read()` | 完整内容 | 详细阅读、代码执行 |
+
+---
+
+## 七、HTTP API 实现
+
+### 7.1 设计原则
+
+**选型决策**:
+
+1. **RESTful 风格**:资源层级 URL,标准 HTTP 方法
+ - 参考 Qdrant API 设计:`/collections/{name}/points`
+ - 便于理解和使用,符合开发者习惯
+
+2. **POST 用于复杂查询**:搜索等操作使用 POST,请求体包含查询参数
+ - 原因:GET 的 URL 长度有限制,复杂查询参数(如向量、过滤条件)不适合放 URL
+ - 参考:Qdrant、Elasticsearch 都采用 POST 进行搜索
+
+3. **统一响应格式**:所有 API 返回 `{status, time, result}` 结构
+ - 参考 Qdrant 响应格式
+ - 便于客户端统一处理
+
+**为什么不用 GraphQL**:
+- OpenViking 的查询模式相对固定,不需要 GraphQL 的灵活性
+- RESTful 更简单,学习成本低
+- 便于缓存和调试
+
+### 7.2 认证机制
+
+采用 API Key 认证:
+
+```
+X-API-Key: your-api-key
+# 或
+Authorization: Bearer your-api-key
+```
+
+### 7.3 API 端点设计
+
+所有 API 响应格式遵循 5.2 统一返回值格式,具体返回值结构见 5.3 各方法返回值。
+
+#### 资源管理 `/api/v1/resources`
+```
+POST /api/v1/resources # add_resource
+ Body: {"path": "...", "target": "...", "wait": false}
+
+POST /api/v1/skills # add_skill
+ Body: {"data": {...}}
+```
+
+#### 文件系统 `/api/v1/fs`
+```
+GET /api/v1/fs/ls?uri=viking:// # ls
+GET /api/v1/fs/tree?uri=viking:// # tree
+GET /api/v1/fs/stat?uri=viking://... # stat
+POST /api/v1/fs/mkdir # mkdir
+ Body: {"uri": "viking://..."}
+
+DELETE /api/v1/fs?uri=viking://...&recursive=false # rm
+POST /api/v1/fs/mv # mv
+ Body: {"from": "...", "to": "..."}
+```
+
+#### 内容读取 `/api/v1/content`
+```
+GET /api/v1/content/read?uri=viking://... # read (L2)
+GET /api/v1/content/abstract?uri=viking://... # abstract (L0)
+GET /api/v1/content/overview?uri=viking://... # overview (L1)
+```
+
+#### 搜索 `/api/v1/search`
+```
+POST /api/v1/search/find # find
+ Body: {"query": "...", "uri": "viking://", "limit": 10}
+
+POST /api/v1/search/search # search (with session)
+ Body: {"query": "...", "uri": "...", "session_id": "..."}
+
+POST /api/v1/search/grep # grep
+ Body: {"uri": "...", "pattern": "...", "case_insensitive": false}
+
+POST /api/v1/search/glob # glob
+ Body: {"pattern": "**/*.md", "uri": "viking://"}
+```
+
+#### 关联 `/api/v1/relations`
+```
+POST /api/v1/relations/link # link
+ Body: {"from": "...", "to": "...", "reason": "..."}
+
+DELETE /api/v1/relations/link # unlink
+ Body: {"from": "...", "to": "..."}
+
+GET /api/v1/relations?uri=viking://... # relations
+```
+
+#### 会话 `/api/v1/sessions`
+```
+POST /api/v1/sessions # session new
+ Body: {"user": "alice"}
+
+GET /api/v1/sessions # session list
+GET /api/v1/sessions/{id} # session get
+DELETE /api/v1/sessions/{id} # session delete
+
+POST /api/v1/sessions/{id}/compress # session compress
+POST /api/v1/sessions/{id}/extract # session extract
+POST /api/v1/sessions/{id}/messages # add message
+ Body: {"role": "user", "content": "..."}
+```
+
+#### 导入导出 `/api/v1/pack`
+```
+POST /api/v1/pack/export # export
+ Body: {"uri": "...", "file": "..."}
+
+POST /api/v1/pack/import # import
+ Body: {"file": "...", "uri": "...", "force": false}
+```
+
+#### 系统 `/api/v1/system`
+```
+GET /health # 健康检查
+GET /api/v1/system/status # 系统状态
+POST /api/v1/system/wait # wait_processed
+ Body: {"timeout": 60}
+```
+
+### 7.4 Server 实现
+
+```python
+# openviking/server/app.py
+from fastapi import FastAPI, Depends
+from openviking.server.auth import verify_api_key
+from openviking.server.routers import resources, filesystem, content, search, sessions
+
+app = FastAPI(
+ title="OpenViking API",
+ description="Context Database for AI Agents",
+ version="1.0.0"
+)
+
+# 注册路由
+app.include_router(resources.router, prefix="/api/v1/resources", dependencies=[Depends(verify_api_key)])
+app.include_router(filesystem.router, prefix="/api/v1/fs", dependencies=[Depends(verify_api_key)])
+app.include_router(content.router, prefix="/api/v1/content", dependencies=[Depends(verify_api_key)])
+app.include_router(search.router, prefix="/api/v1/search", dependencies=[Depends(verify_api_key)])
+app.include_router(sessions.router, prefix="/api/v1/sessions", dependencies=[Depends(verify_api_key)])
+
+async def health():
+ return {"status": "healthy"}
+```
+
+---
+
+## 八、实现任务拆解
+
+### 8.1 任务概览
+
+| 任务 | 描述 | 依赖 | 优先级 | 适合社区开发者 |
+|------|------|------|--------|---------------|
+| T1 | Service 层抽取 | - | P0 | |
+| T2 | HTTP Server | T1 | P1 | |
+| T3 | CLI 基础框架 | T1 | P1 | |
+| T4 | Python SDK | T2 | P2 | |
+| T5 | CLI 完整命令 | T3 | P2 | |
+| T6 | 集成测试 | T4, T5 | P3 | |
+| T7 | 文档更新 | T6 | P3 | |
+| T8 | Docker 部署 | T2 | P1 | ✅ |
+| T9 | MCP Server | T1 | P1 | ✅ |
+| T10 | TypeScript SDK | T2 | P2 | ✅ |
+| T11 | Golang SDK | T2 | P2 | ✅ |
+
+### 8.2 依赖关系
+
+```
+T1 (Service层)
+ ├── T2 (Server) ──┬── T4 (Python SDK) ──┐
+ │ ├── T8 (Docker) │
+ │ ├── T10 (TS SDK) ├── T6 (测试) ── T7 (文档)
+ │ └── T11 (Go SDK) │
+ │ │
+ ├── T3 (CLI基础) ── T5 (CLI完整) ────────┘
+ │
+ └── T9 (MCP Server)
+```
+
+### 8.3 任务详情
+
+#### T1: Service 层抽取(P0)
+
+**目标**:从 `async_client.py` 抽取业务逻辑到独立的 Service 层
+
+**交付物**:
+- `openviking/service/core.py` - OpenVikingService
+- `openviking/service/resource_service.py` - 资源导入、技能添加
+- `openviking/service/search_service.py` - 语义搜索
+- `openviking/service/session_service.py` - 会话管理
+- `openviking/service/fs_service.py` - 文件系统操作
+
+**验收标准**:
+- 现有单元测试全部通过
+- `async_client.py` 作为兼容层,API 不变
+
+---
+
+#### T2: HTTP Server(P1)
+
+**目标**:实现 FastAPI HTTP Server
+
+**交付物**:
+- `openviking/server/app.py` - FastAPI 应用
+- `openviking/server/bootstrap.py` - 服务启动器
+- `openviking/server/auth.py` - API Key 认证
+- `openviking/server/routers/*.py` - 所有 API 路由
+- `openviking/server/models.py` - 统一响应模型
+
+**验收标准**:
+```bash
+# 启动服务
+openviking serve --path ./data --port 8000
+
+# 验证 API
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/api/v1/resources \
+ -H "X-API-Key: test" -d '{"path": "./docs"}'
+curl http://localhost:8000/api/v1/fs/ls?uri=viking://
+```
+
+---
+
+#### T3: CLI 基础框架(P1)
+
+**目标**:实现 CLI 核心命令
+
+**交付物**:
+- `openviking/cli/main.py` - CLI 入口
+- `openviking/cli/output.py` - 输出格式化
+- 核心命令:`serve`, `ls`, `find`, `read`, `abstract`, `overview`, `add-resource`
+
+**验收标准**:
+```bash
+openviking serve --path ./data --port 8000
+openviking add-resource ./docs/ --wait
+openviking ls viking://resources/
+openviking find "how to use"
+```
+
+---
+
+#### T4: Python SDK(P2)
+
+**目标**:支持通过 HTTP 连接远程 Server
+
+**交付物**:
+- `openviking/client/http.py` - HTTPClient
+- `openviking/client/local.py` - LocalClient(重构)
+- 修改 `async_client.py` 支持 `server_url` 参数
+
+**验收标准**:
+```python
+# HTTP 模式
+client = OpenViking(server_url="http://localhost:8000", api_key="test")
+client.initialize()
+results = client.find("how to use")
+```
+
+---
+
+#### T5: CLI 完整命令(P2)
+
+**目标**:补全所有 CLI 命令
+
+**交付物**:
+- 会话命令:`session new/list/get/compress/extract`
+- 文件系统命令:`tree`, `stat`, `mkdir`, `rm`, `mv`
+- 搜索命令:`search`, `grep`, `glob`
+- 关联命令:`link`, `unlink`, `relations`
+- 导入导出:`export`, `import`
+- 配置命令:`config show/init`
+- 工具命令:`wait`, `status`
+
+**验收标准**:
+```bash
+openviking --help # 显示所有命令
+openviking session new --user alice
+openviking export viking://resources/docs/ ./backup.ovpack
+```
+
+---
+
+#### T6: 集成测试(P3)
+
+**目标**:端到端测试
+
+**交付物**:
+- `tests/integration/test_cli.py`
+- `tests/integration/test_server.py`
+- `tests/integration/test_http_client.py`
+
+**验收标准**:
+- 所有集成测试通过
+- 覆盖主要使用场景
+
+---
+
+#### T7: 文档更新(P3)
+
+**目标**:更新用户文档
+
+**交付物**:
+- README.md 更新(CLI 和 Server 使用说明)
+- OpenAPI 文档(自动生成)
+- CHANGELOG.md 更新
+
+---
+
+#### T8: Docker 部署(P1)
+
+**目标**:提供 Docker 镜像和 docker-compose 配置
+
+**交付物**:
+- `Dockerfile` - 多阶段构建
+- `docker-compose.yml` - 本地部署配置
+- `.dockerignore` - 忽略文件
+- GitHub Actions 自动构建发布
+
+**验收标准**:
+```bash
+docker build -t openviking .
+docker run -p 8000:8000 -e OPENAI_API_KEY=xxx openviking
+curl http://localhost:8000/health
+```
+
+---
+
+#### T9: MCP Server(P1)
+
+**目标**:实现 Model Context Protocol 服务端,让 Claude 等 AI 可直接调用
+
+**交付物**:
+- `openviking/mcp/server.py` - MCP Server 主入口
+- `openviking/mcp/tools.py` - Tool 定义(find, read, ls, abstract, overview)
+- CLI 命令:`openviking mcp [--path <dir>]`
+
+**验收标准**:
+- Claude Desktop 可成功连接并调用 tools
+- 支持 stdio 传输
+
+---
+
+#### T10: TypeScript SDK(P2)
+
+**目标**:基于 HTTP API 实现 TypeScript/JavaScript 客户端
+
+**交付物**:
+- `openviking-js/` - 独立 npm 包
+- 完整类型定义
+- 错误处理
+- README 和示例
+
+**验收标准**:
+```typescript
+import { OpenViking } from '@openviking/sdk';
+const client = new OpenViking({ url: 'http://localhost:8000', apiKey: 'xxx' });
+const results = await client.find('how to configure');
+```
+
+---
+
+#### T11: Golang SDK(P2)
+
+**目标**:基于 HTTP API 实现 Golang 客户端
+
+**交付物**:
+- `openviking-go/` - 独立 Go 模块
+- 完整类型定义
+- 错误处理
+- README 和示例
+
+**验收标准**:
+```go
+client := openviking.NewClient(openviking.Config{URL: "http://localhost:8000", APIKey: "xxx"})
+results, _ := client.Find("how to configure", nil)
+```
+
+### 8.4 关键文件
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `pyproject.toml` | 修改 | 添加依赖和入口点 |
+| `openviking/exceptions.py` | 新增 | 异常类定义 |
+| `openviking/cli/main.py` | 新增 | CLI 入口 |
+| `openviking/server/app.py` | 新增 | FastAPI 应用入口 |
+| `openviking/server/auth.py` | 新增 | API Key 认证 |
+| `openviking/server/models.py` | 新增 | 响应模型、错误码定义 |
+| `openviking/server/routers/*.py` | 新增 | API 路由 |
+| `openviking/client/http.py` | 新增 | HTTP 客户端 |
+| `openviking/async_client.py` | 修改 | 支持 HTTP 模式 |
+
+### 8.5 验证方案
+
+#### Bash CLI 验证
+```bash
+openviking config init
+openviking serve --port 8000
+openviking add-resource ./docs/ --wait
+openviking ls viking://
+openviking find "how to use"
+```
+
+#### HTTP API 验证
+```bash
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/api/v1/resources \
+ -H "X-API-Key: xxx" -d '{"path": "./docs"}'
+curl "http://localhost:8000/api/v1/fs/ls?uri=viking://" \
+ -H "X-API-Key: xxx"
+```
+
+#### Python CLI 验证
+```python
+from openviking import OpenViking
+client = OpenViking(url="http://localhost:8000", api_key="xxx")
+result = client.find("how to use")
+print(result)
+```