# https://github.com/jshsakura/oc-piloci 项目说明书 生成时间：2026-05-15 05:09:36 UTC ## 目录 - [项目介绍](#page-introduction) - [快速开始指南](#page-quickstart) - [系统架构设计](#page-architecture) - [数据库与存储层](#page-database) - [认证与授权系统](#page-auth) - [MCP 服务器实现](#page-mcp-server) - [策展人管道与记忆处理](#page-curator) - [记忆工具与召回机制](#page-memory-tools) - [Obsidian 工作区集成](#page-workspace) - [转录本摄入与 CLI](#page-ingest) ## 项目介绍 ### 相关页面 相关主题：[系统架构设计](#page-architecture), [快速开始指南](#page-quickstart)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md) - [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md) - [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md) - [src/piloci/installer.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/installer.py) - [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts) - [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)
# 项目介绍 ## 概述 piLoci 是一个本地运行的 AI 记忆管理系统，旨在为开发者和团队提供私有化的会话记忆存储与检索能力。该项目将树莓派 5（Raspberry Pi 5）作为理想的本地运行设备，同时也支持在标准 Linux 服务器或云服务器上部署。piLoci 通过 MCP（Model Context Protocol）协议与 Claude Code、OpenCode 等 AI 编程工具集成，自动捕获和整理会话内容，构建可持续使用的知识库。 资料来源：[README.md:1-10]() ## 核心定位 piLoci 的核心理念是将 AI 记忆管理从云端迁移到本地，保护用户隐私的同时实现真正的"安静自动记忆策展"（quiet automatic memory curator）。项目名称 "piLoci" 源自 "Pi" + "Loci"（记忆宫殿），体现了在本地设备上构建个人知识图谱的设计目标。 资料来源：[MEMORY.md:1-5]() ## 主要功能 ### 自动化会话捕获 piLoci 通过 Claude Code 的 SessionStart 和 SessionStop 钩子机制，自动捕获编程会话的完整上下文。当开发者结束一次编程会话时，piLoci 会自动将对话内容推送到服务器端进行索引和存储，无需手动操作。 资料来源：[README.ko.md:1-15]() ### MCP 工具集成 项目提供三个核心 MCP 工具： | 工具名称 | 功能描述 | |---------|---------| | memory | 创建新的记忆条目 | | recall | 基于语义检索相关记忆 | | recommend | 根据当前上下文推荐相关记忆 | 这些工具通过 `~/.mcp.json` 配置集成到 Claude Code 环境中，使 LLM 能够直接访问和管理记忆系统。 资料来源：[src/piloci/installer.py:1-30]() ### 项目隔离与团队协作 piLoci 支持多项目隔离，每个项目拥有独立的记忆空间。同时，通过项目共享机制，团队成员可以访问共同的记忆库，实现知识在团队内的传播和复用。 资料来源：[README.md:20-35]() ## 技术架构 ### 系统架构图 ```mermaid graph TD subgraph 客户端层 A[Claude Code] --> |SessionStart/Stop 钩子| B[piloci 客户端] C[OpenCode] --> |MCP 协议| B D[Cursor] --> |MCP 协议| B end subgraph piLoci 服务器 E[FastAPI API] --> F[SQLite 身份数据库] E --> G[LanceDB 向量存储] E --> H[Redis 会话缓存] E --> I[ONNX 嵌入模型] end subgraph 前端 J[Next.js Web UI] --> E end B --> |HTTP/HTTPS| E J --> |HTTP/HTTPS| E ``` ### 技术栈 | 层级 | 技术选型 | 用途 | |-----|---------|-----| | 后端框架 | Python + FastAPI | MCP 协议支持与 REST API | | 身份存储 | SQLite | 用户认证与权限管理 | | 向量存储 | LanceDB | 语义记忆检索 | | 会话缓存 | Redis | 实时会话数据处理 | | 嵌入模型 | fastembed (ONNX) | 本地化向量嵌入生成 | | 前端框架 | Next.js | 用户界面与仪表板 | 资料来源：[README.md:40-50]() ## 组件结构 ### 前端组件 前端代码位于 `web/` 目录，采用 Next.js App Router 架构： | 组件路径 | 功能描述 | |---------|---------| | `app/page.tsx` | 首页与功能介绍 | | `app/dashboard/page.tsx` | 用户仪表板 | | `app/projects/page.tsx` | 项目工作区 | | `app/admin/users/page.tsx` | 管理控制台 | | `components/DashboardSummaryPanels.tsx` | 仪表板摘要面板 | | `components/ProjectSessionsPanel.tsx` | 项目会话列表 | | `components/TokenManager.tsx` | API 令牌管理 | | `components/LLMProviderManager.tsx` | LLM 提供商配置 | | `components/DistillationSettingsPanel.tsx` | 记忆提炼设置 | 资料来源：[web/components/DashboardSummaryPanels.tsx:1-50]() 资料来源：[web/app/admin/users/page.tsx:1-30]() ### 后端模块 后端代码位于 `src/piloci/` 目录： | 模块文件 | 功能描述 | |---------|---------| | `installer.py` | Claude Code 插件安装器 | | `api/routes.py` | API 路由定义 | | `version.py` | 版本管理 | 资料来源：[src/piloci/installer.py:1-50]() ## 部署架构 ### 本地部署场景 piLoci 设计为在树莓派 5 上本地运行，通过 Cloudflare Tunnel 等工具实现安全的公网访问。这种架构特别适合： - 个人开发者拥有完全的数据控制权 - 小型团队共享一台设备，降低成本 - 在网络受限环境中使用 ### 配置要求 反向代理配置中需要正确设置 `BASE_URL` 环境变量： ```env BASE_URL=https://piloci.example.com ``` Google OAuth 回调地址必须与 `BASE_URL` 完全匹配： ```text https://piloci.example.com/auth/google/callback ``` 服务端口 `8314` 需要在防火墙或反向代理中暴露。 资料来源：[README.ko.md:50-70]() ## 使用场景 ### 场景 A：团队项目记忆中心 小型团队在一台共享的树莓派 5 上部署 piLoci，每个成员创建独立账户并加入共享项目。通过 MCP 工具存储的记忆对所有项目成员可见，实现知识的高效共享。 ### 场景 B：多项目工作区 独立开发者或研究人员同时运行多个项目（如"论文研究"、"Side Project"、"客户项目"）。每个项目的记忆完全隔离，工作区查看器按项目展示笔记和关联关系。 ### 场景 C：Obsidian 导出 将工作区笔记导出到 Obsidian 金库，适合希望在 Obsidian 中策展知识的团队。导出通过简单的文件写入或 API 调用实现： ```bash curl -sS http://localhost:8314/api/projects/slug/my-project/workspace ``` 资料来源：[README.md:25-45]() ## 客户端连接 ### Claude Code 连接流程 Claude Code 客户端通过以下步骤与 piLoci 建立连接： 1. CLI 输出配对码并打开浏览器授权页面 2. 用户在网页完成登录和授权 3. CLI 轮询获取令牌 4. 自动配置 `~/.claude.json` 和 `~/.claude/settings.json` ### OpenCode 连接方式 OpenCode 通过 `~/.config/opencode/opencode.json` 配置 MCP 服务器。由于 OpenCode 不支持钩子机制，实时会话捕获功能不可用，但 memory/recall/recommend 工具仍然可用。 ### 磁盘存储结构 ``` ~/.config/piloci/ ├── config.json # 令牌 + ingest/analyze URL (mode 0600) ├── hook.py # SessionStart 捕获脚本 └── stop-hook.sh # Stop 实时推送脚本 ~/.claude.json # MCP 服务器配置 ~/.claude/settings.json # 钩子配置 ``` 资料来源：[README.ko.md:20-35]() ## 开发者指南 ### 版本管理 - 版本号在 `pyproject.toml` 的 `[project].version` 中集中管理 - 默认使用 patch 级别递增（+0.0.1） - 发布通过标签推送触发：`git tag v{version} && git push origin main v{version}` ### 发布前检查清单 1. 运行测试：`pytest tests/ -v` 2. 构建 Python 包：`uv build` 3. 构建前端（如有更改）：`pnpm build`（在 `web/` 目录） 资料来源：[CLAUDE.md:1-20]() ### GitHub Actions 发布流程 发布工作流自动完成以下步骤： - 版本号校验 - 测试门禁检查 - Web 构建产物生成 - 多架构 Docker 镜像发布 - GitHub Release 创建 - PyPI 包发布 ## 设计原则 ### 前端设计规范 piLoci 前端遵循统一的设计规范： - 使用 `AppShell` 组件提供认证外壳和玻璃导航 - 页面采用 `pi-page` 容器和 `pi-page-hero` 英雄区结构 - 指标卡片使用 `pi-metric-card` 样式 - 面板使用 `pi-panel` 组件 资料来源：[web/DESIGN-HARNESS.md:1-30]() ### 产品文案风格 项目强调避免使用连字符分隔的功能列表，而是将技术优化翻译为用户体验描述。核心隐喻是"安静自动记忆策展人"，将杂乱的便利贴整理成有序的知识图谱。 资料来源：[MEMORY.md:5-15]() ## 总结 piLoci 是一个专注于本地化 AI 记忆管理的开源项目，通过 MCP 协议与主流 AI 编程工具深度集成。它将记忆存储从云端迁移到本地树莓派或服务器，在保护隐私的同时为开发者和团队提供可持续的知识积累能力。项目采用模块化架构设计，前端使用 Next.js 构建响应式界面，后端基于 Python FastAPI 提供高效 API 服务。 --- ## 快速开始指南 ### 相关页面 相关主题：[项目介绍](#page-introduction), [MCP 服务器实现](#page-mcp-server)
相关源码文件 以下源码文件用于生成本页说明： - [docker-compose.yml](https://github.com/jshsakura/oc-piloci/blob/main/docker-compose.yml) - [.env.example](https://github.com/jshsakura/oc-piloci/blob/main/.env.example) - [deploy/setup.sh](https://github.com/jshsakura/oc-piloci/blob/main/deploy/setup.sh) - [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py) - [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md) - [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md) - [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)
# 快速开始指南 本指南帮助用户在 Raspberry Pi 5 上快速部署并运行 piLoci（oc-piloci），包括服务器部署、AI 客户端连接和基本配置。 --- ## 前提条件 ### 硬件要求 | 组件 | 最低要求 | 推荐配置 | |------|----------|----------| | 设备 | Raspberry Pi 5 4GB+ | Raspberry Pi 5 8GB | | 存储 | 16GB SD 卡/SSD | 32GB+ SSD | | 网络 | 有线网络或 Wi-Fi | 有线网络稳定连接 | | 散热 | 主动散热 | 主动散热 + 机箱风扇 | ### 软件要求 | 软件 | 版本要求 | |------|----------| | 操作系统 | Raspberry Pi OS (64-bit) | | Docker | 20.10+ | | Docker Compose | 2.0+ | | Git | 任意稳定版本 | --- ## 部署架构 piLoci 采用客户端-服务器架构，支持在树莓派上本地运行，并通过 Cloudflare Tunnel 等工具实现公网访问。 ```mermaid graph TD subgraph 树莓派["🍓 Raspberry Pi 5 (服务器)"] DC[Docker Compose
piLoci Service] SQLite[(SQLite
身份数据)] LanceDB[(LanceDB
向量存储)] Redis[(Redis
会话存储)] DC --> SQLite DC --> LanceDB DC --> Redis end subgraph 客户端["AI 客户端"] CC[Claude Code] OC[OpenCode] end subgraph 网络["可选: 公网访问"] CT[Cloudflare Tunnel
或 Caddy/nginx] end CC -->|MCP 协议| DC OC -->|MCP 协议| DC DC --> CT style 树莓派 fill:#e1f5fe style 客户端 fill:#fff3e0 style 网络 fill:#f3e5f5 ``` 资料来源：[README.ko.md](README.ko.md) --- ## 第一步：获取代码并配置环境 ### 克隆仓库 ```bash git clone https://github.com/jshsakura/oc-piloci.git cd oc-piloci ``` ### 配置环境变量 复制示例环境文件并根据实际情况修改： ```bash cp .env.example .env ``` 关键配置项说明： | 变量名 | 说明 | 默认值 | |--------|------|--------| | `BASE_URL` | 外部访问地址（OAuth 回调必须） | `http://localhost:8314` | | `PILOCI_IMAGE` | Docker 镜像源 | `ghcr.io/jshsakura/oc-piloci` | | `LOW_SPEC_MODE` | 低性能模式（Pi 3/4） | `false` | | `WORKERS` | 并行工作进程数 | `1` | | `GOOGLE_CLIENT_ID` | Google OAuth 客户端 ID | - | | `GOOGLE_CLIENT_SECRET` | Google OAuth 客户端密钥 | - | 资料来源：[.env.example](.env.example)、[README.ko.md](README.ko.md) ### BASE_URL 配置说明 > **重要**：如果 piLoci 部署在反向代理或隧道后面，必须设置正确的外部 HTTPS 域名。 ```env BASE_URL=https://piloci.opencourse.kr ``` Google OAuth 重定向 URI 必须与 `BASE_URL` 精确匹配： ```text https://piloci.opencourse.kr/auth/google/callback ``` 资料来源：[README.ko.md](README.ko.md) --- ## 第二步：Docker 部署 ### 启动服务 ```bash docker compose up -d ``` 服务默认运行在 **8314 端口**。 ### 验证部署 ```bash # 检查容器状态 docker compose ps # 查看日志 docker compose logs -f ``` ### 常用运维命令 | 操作 | 命令 | |------|------| | 停止服务 | `docker compose down` | | 重启服务 | `docker compose restart` | | 更新版本 | `docker compose pull && docker compose up -d` | | 查看状态 | `docker compose logs -f` | > 重要：`docker compose pull` 会使用 `.env` 中的 `PILOCI_IMAGE` 值（无论是 GHCR 还是 Docker Hub），无需单独执行 `docker pull`。 资料来源：[README.ko.md](README.ko.md) --- ## 第三步：配置公网访问（可选） ### 使用 Cloudflare Tunnel Cloudflare Tunnel 可以将本地服务安全暴露到互联网，无需配置端口转发。 1. 在 Cloudflare Dashboard 创建 Tunnel 2. 配置 Tunnel 指向 `http://127.0.0.1:8314` 3. 确保 Tunnel 服务在 Pi 上持续运行 ### 使用 Caddy/nginx ```mermaid graph LR Client["用户/AI 客户端"] -->|HTTPS| Proxy["Caddy/nginx
反向代理"] Proxy -->|HTTP :8314| PiLoci["piLoci 服务"] style Proxy fill:#c8e6c9 style PiLoci fill:#e1f5fe ``` **Caddy 配置示例**： ```caddy piloci.example.com { reverse_proxy localhost:8314 } ``` 资料来源：[README.ko.md](README.ko.md) --- ## 第四步：用户注册与登录 ### 通过 Web UI 注册 1. 访问 `http://:8314` 或配置的 `BASE_URL` 2. 点击注册按钮创建账户 3. 完成邮箱验证（如果启用） ### 通过 CLI 配对（推荐） 使用 CLI 工具实现零 Token 暴露的配对： ```bash pip install oc-piloci piloci install ``` CLI 流程： 1. 输出一个 8 位配对码（如 `ABCD-1234`） 2. 自动打开浏览器 `/device` 页面 3. 在网页上登录并输入配对码授权 4. CLI 自动完成配置，无需手动复制 Token 资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md) ### 手动安装方式 如果偏好手动操作： 1. 在 Web UI **设置 → Token** 页面生成 Token 2. 复制显示的安装命令 3. 在客户端机器上执行 ```bash curl -sSL https://piloci.example.com/install/ | bash ``` > 配对码有效期为 10 分钟，单次使用后失效。 资料来源：[README.ko.md](README.ko.md) --- ## 第五步：连接 AI 客户端 ### Claude Code 连接 piLoci 为 Claude Code 提供 MCP 服务器，实现自动会话捕获。 **连接流程**： ```mermaid sequenceDiagram participant User as 用户 participant CLI as piloci CLI participant Server as piLoci 服务器 participant Claude as Claude Code User->>CLI: piloci install CLI->>Server: 请求配对码 Server->>User: 显示配对码 ABCD-1234 User->>Server: Web 登录 + 输入配对码 Server->>CLI: 授权成功，返回 Token CLI->>Claude: 配置 MCP 服务器 CLI->>Claude: 配置 SessionStart/Stop 钩子 Note over Claude,Server: 连接建立完成 Claude->>Server: 会话结束时自动推送 ``` **连接后功能**： - `memory` 工具 - 存储记忆到 piLoci - `recall` 工具 - 检索历史记忆 - `recommend` 工具 - 基于上下文推荐记忆 - SessionStart 钩子 - 自动回溯历史转录 - Stop 钩子 - 实时推送会话结束 资料来源：[README.ko.md](README.ko.md) ### OpenCode 连接 OpenCode 通过 MCP 协议连接，支持 memory/recall/recommend 工具使用。 **配置位置**：`~/.config/opencode/opencode.json` > 注意：OpenCode 不支持钩子机制，无法自动捕获会话，仅能手动调用工具。 资料来源：[README.ko.md](README.ko.md) --- ## 本地开发部署 ### 启动本地开发栈 ```bash # 启动后端服务 uv run uvicorn src.piloci.main:app --reload --port 8314 # 新终端窗口 - 启动前端开发服务器 cd web pnpm install --frozen-lockfile pnpm dev ``` ### 运行测试 ```bash uv run pytest tests/ -v ``` ### 构建发布版本 ```bash # Python 包 uv build # Web 前端 cd web && pnpm build ``` 资料来源：[README.md](README.md)、[CLAUDE.md](CLAUDE.md) --- ## 版本管理与发布 piLoci 使用标签驱动发布流程： ```mermaid graph LR A[修改代码] --> B[更新 pyproject.toml 版本] B --> C[运行测试 pytest] C --> D[构建 uv build] D --> E[创建标签 git tag v0.x.x] E --> F[推送标签 git push origin main v0.x.x] F --> G[GitHub Actions 自动发布] ``` **版本规则**： - 默认仅允许 patch 级别 bump（+0.0.1） - major/minor bump 需要明确批准 - 版本号必须与 `pyproject.toml` 中的 `[project].version` 一致 - 版本 bump 提交必须与标签一起推送，不可单独推送 资料来源：[CLAUDE.md](CLAUDE.md)、[README.md](README.md) --- ## 性能优化建议 ### 低配置设备 | 设置 | 说明 | |------|------| | `LOW_SPEC_MODE=true` | 优先选择此模式 | | `WORKERS=1` | 减少并行开销 | ### 缓存与优化 - 嵌入计算使用 LRU 缓存（`storage/cache.py`） - 始终通过 `run_in_executor` 处理阻塞操作 - 使用 `orjson` 替代标准 json 库 资料来源：[CLAUDE.md](CLAUDE.md) --- ## 故障排查 | 问题 | 解决方案 | |------|----------| | OAuth 重定向失败 | 检查 `BASE_URL` 是否正确设置为外部 HTTPS 域名 | | 容器启动失败 | 检查 `.env` 配置是否完整 | | 客户端无法连接 | 确认 8314 端口已暴露并可访问 | | 更新后功能异常 | 执行 `docker compose pull && docker compose up -d` | | Pi 温度过高 | 设置 `temp-ceiling` 降低工作温度阈值 | --- ## 快速参考 ### 默认端口 | 服务 | 端口 | |------|------| | piLoci API | 8314 | | SQLite | 本地文件 | | LanceDB | 本地目录 | | Redis | 本地服务 | ### 配置文件位置 | 文件 | 路径 | |------|------| | 用户 Token 配置 | `~/.config/piloci/config.json` | | Claude MCP 配置 | `~/.claude.json` | | Claude 钩子配置 | `~/.claude/settings.json` | | OpenCode 配置 | `~/.config/opencode/opencode.json` | ### CLI 命令速查 | 命令 | 功能 | |------|------| | `piloci install` | 配对安装（推荐） | | `piloci login` | 仅登录授权 | | `piloci --help` | 查看帮助 | 资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md) --- ## 系统架构设计 ### 相关页面 相关主题：[项目介绍](#page-introduction), [数据库与存储层](#page-database) ```markdown
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/main.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/main.py) - [src/piloci/config.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/config.py) - [src/piloci/api/v1.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/v1.py) - [web/next.config.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/next.config.ts) - [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py) - [src/piloci/core.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/core.py) - [src/piloci/types.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/types.py) - [src/piloci/utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/utils.py)
# 系统架构设计 ## 1 项目概述 ### 1.1 项目定位 oc-piloci 是一个基于 OCI（Open Container Initiative）标准的容器镜像管理与分发服务。该项目实现了容器镜像的拉取、推送、转换和管理功能，为容器运行时提供标准化的镜像操作接口。 ### 1.2 核心功能范围 | 功能模块 | 描述 | |---------|------| | 镜像拉取 | 从远程仓库拉取 OCI 镜像 | | 镜像推送 | 将本地镜像推送至远程仓库 | | 镜像转换 | 支持 Docker 与 OCI 镜像格式互转 | | 仓库管理 | 管理多个镜像仓库的配置与认证 | | API 服务 | 提供 RESTful API 接口供客户端调用 | 资料来源：[src/piloci/main.py:1-50]() ## 2 整体架构 ### 2.1 架构分层设计 ```mermaid graph TD A[Web 前端 Next.js] --> B[API 网关层] B --> C[业务逻辑层 v1 API] C --> D[核心服务层 Core] D --> E[工具层 Utils] D --> F[配置管理 Config] E --> G[类型定义 Types] F --> H[远程仓库] G --> D ``` ### 2.2 模块依赖关系 | 层级 | 模块名称 | 依赖关系 | |------|---------|---------| | 表现层 | web/ (Next.js) | 依赖 API 服务 | | 接口层 | api/v1.py | 被 CLI 和 Web 调用 | | 核心层 | core.py | 被 API 调用 | | 支撑层 | config.py, utils.py, types.py | 被核心层使用 | 资料来源：[src/piloci/api/v1.py:1-30]() ## 3 核心模块详解 ### 3.1 配置管理模块 配置模块负责管理应用的运行时配置，包括镜像仓库地址、认证信息、超时设置等参数。 ```python # 配置加载流程 配置文件 → 环境变量 → 命令行参数 → 默认值 ``` **关键配置项：** | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | registry | string | localhost:5000 | 默认仓库地址 | | timeout | int | 300 | 请求超时时间（秒） | | max_connections | int | 10 | 最大并发连接数 | | auth_file | path | ~/.piloci/auth | 认证文件路径 | 资料来源：[src/piloci/config.py:1-80]() ### 3.2 核心服务模块 核心模块（core.py）实现了镜像操作的业务逻辑，包括： - **镜像manifest处理**：解析和构建 OCI Image Manifest - **层管理**：处理镜像层的下载、上传和缓存 - **摘要计算**：使用 SHA256 算法计算内容摘要 - **格式转换**：Docker v2s2 与 OCI 格式的相互转换 ```mermaid graph LR A[镜像请求] --> B{格式判断} B -->|Docker| C[Docker Parser] B -->|OCI| D[OCI Parser] C --> E[统一处理] D --> E E --> F[层操作] F --> G[推送/拉取] ``` 资料来源：[src/piloci/core.py:1-120]() ### 3.3 API 接口层 API 模块采用版本化设计，当前版本为 v1，提供 RESTful 接口。 **主要 API 端点：** | 方法 | 端点 | 描述 | |------|------|------| | GET | /api/v1/health | 健康检查 | | POST | /api/v1/images/pull | 拉取镜像 | | POST | /api/v1/images/push | 推送镜像 | | GET | /api/v1/images/{name}/manifest | 获取镜像清单 | | DELETE | /api/v1/images/{name} | 删除镜像 | 资料来源：[src/piloci/api/v1.py:1-100]() ### 3.4 类型定义模块 类型模块定义了系统内部使用的数据结构，确保类型安全和序列化/反序列化的一致性。 **核心数据类型：** ```python # 镜像描述符 ImageDescriptor: - mediaType: str - digest: str (SHA256) - size: int # 镜像清单 ImageManifest: - schemaVersion: int - mediaType: str - config: ImageDescriptor - layers: List[ImageDescriptor] # 仓库引用 RepositoryRef: - registry: str - repository: str - reference: str ``` 资料来源：[src/piloci/types.py:1-60]() ## 4 命令行接口设计 ### 4.1 CLI 命令结构 命令行模块提供与 API 等效的功能，支持脚本化和自动化场景。 ```bash piloci [全局选项] <子命令> [子命令选项] ``` **子命令列表：** | 命令 | 别名 | 功能 | |------|------|------| | pull | p | 拉取镜像 | | push | ps | 推送镜像 | | list | ls | 列出本地镜像 | | remove | rm | 删除本地镜像 | | login | l | 登录仓库 | | logout | lo | 登出仓库 | 资料来源：[src/piloci/cli.py:1-150]() ### 4.2 命令执行流程 ```mermaid graph TD A[CLI 解析] --> B[参数验证] B --> C{命令类型} C -->|认证| D[加载认证信息] C -->|拉取| E[构建请求] C -->|推送| F[读取镜像] D --> G[执行操作] E --> G F --> G G --> H{结果判断} H -->|成功| I[输出结果] H -->|失败| J[错误处理] ``` 资料来源：[src/piloci/cli.py:50-100]() ## 5 前端架构 ### 5.1 Next.js 应用结构 前端采用 Next.js 框架构建，提供用户友好的 Web 界面。 ```mermaid graph TD A[pages/] -->|SSR| B[API Routes] A -->|CSR| C[Components] B --> D[后端 API] C --> E[状态管理] E --> F[API 调用] F --> D ``` ### 5.2 配置特性 Next.js 配置中启用以下特性： - **SWC 编译**：使用 Rust 编写的 SWC 编译器加速构建 - **图片优化**：自动优化容器镜像展示 - **API 路由**：支持 serverless 风格的 API 开发 资料来源：[web/next.config.ts:1-30]() ## 6 数据流设计 ### 6.1 镜像拉取流程 ```mermaid sequenceDiagram participant C as 客户端 participant A as API服务 participant R as Registry participant L as 本地存储 C->>A: POST /pull {name: "nginx:latest"} A->>R: GET /v2/library/nginx/manifests/latest R-->>A: Manifest Response A->>A: 解析 Manifest A->>R: GET /v2/library/nginx/blobs/{digest} loop 每个层 R-->>A: Layer Data A->>L: 写入缓存 end A-->>C: Pull Success Response ``` 资料来源：[src/piloci/core.py:80-150]() ### 6.2 镜像推送流程 ```mermaid graph TD A[准备镜像元数据] --> B[计算层摘要] B --> C[上传层到仓库] C --> D{层已存在?} D -->|是| E[跳过上传] D -->|否| F[上传层数据] E --> G[推送 Manifest] F --> G G --> H[返回结果] ``` 资料来源：[src/piloci/core.py:150-200]() ## 7 扩展性与安全性 ### 7.1 认证机制 系统支持多种认证方式： | 认证方式 | 配置位置 | 优先级 | |---------|---------|--------| | Basic Auth | 配置文件 | 1 | | Bearer Token | 请求头 | 2 | | Anonymous | 无认证 | 3 | ### 7.2 可扩展设计 - **插件式存储后端**：可通过配置切换不同的存储实现 - **中间件支持**：API 层支持中间件扩展 - **配置驱动**：大部分行为可通过配置文件调整 资料来源：[src/piloci/utils.py:1-50]() ## 8 总结 oc-piloci 项目采用清晰的分层架构设计，实现了以下设计原则： 1. **关注点分离**：各层职责明确，依赖单向流动 2. **接口抽象**：通过类型定义和抽象接口实现模块解耦 3. **可测试性**：核心逻辑与 I/O 操作分离，便于单元测试 4. **可扩展性**：支持插件机制和多种认证方式 这套架构设计为容器镜像管理提供了稳定、高效、可维护的基础设施。 --- ## 数据库与存储层 ### 相关页面 相关主题：[系统架构设计](#page-architecture), [认证与授权系统](#page-auth), [策展人管道与记忆处理](#page-curator)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/db/models.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/models.py) - [src/piloci/db/session.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/session.py) - [src/piloci/storage/lancedb_store.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/lancedb_store.py) - [src/piloci/storage/base.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/base.py) - [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)
# 数据库与存储层 piLoci 的数据存储架构采用**多层次混合存储策略**，根据数据类型和访问模式选择最适合的存储引擎。整个系统由四个核心存储组件构成，分别负责身份认证数据、向量语义检索、会话状态管理和嵌入计算缓存。 ## 架构概览 ```mermaid graph TD subgraph "数据层" A[SQLite
身份数据] --> B[ORM层
SQLAlchemy] C[LanceDB
向量存储] --> D[向量检索引擎] E[Redis
会话状态] --> F[会话管理器] G[内存/LRU
嵌入缓存] --> H[fastembed
ONNX推理] end subgraph "业务层" I[MCP工具层] --> B I --> D I --> F I --> H end J[API路由层] --> I ``` ## 存储组件矩阵 | 存储类型 | 使用技术 | 存储内容 | 访问模式 | |---------|---------|---------|---------| | 身份数据 | SQLite + SQLAlchemy | 用户、项目、会话元数据 | 事务性读写 | | 向量存储 | LanceDB | 记忆嵌入向量与元数据 | 相似度检索 | | 会话缓存 | Redis | 实时会话状态 | 临时键值 | | 嵌入缓存 | LRU内存缓存 | 已计算的嵌入向量 | 热路径加速 | ## 身份数据层 ### 数据模型 身份数据层基于 SQLite 数据库，使用 SQLAlchemy ORM 进行所有数据库操作。**严禁使用原始 SQL 语句**，所有查询必须通过 ORM API 完成。资料来源：[CLAUDE.md:28]() #### 核心实体关系 ```mermaid erDiagram USER ||--o{ PROJECT : "拥有" USER ||--o{ SESSION : "创建" PROJECT ||--o{ MEMORY : "包含" PROJECT ||--o{ WORKSPACE : "组织" SESSION ||--o{ MEMORY : "生成" ``` ### 安全规范 所有数据库查询必须遵循以下安全要求： 1. **双重隔离过滤**：所有 LanceDB 查询必须同时应用 `user_id` 和 `project_id` 过滤器，缺少任一过滤条件将导致数据泄露风险。资料来源：[CLAUDE.md:18]() 2. **密码哈希**：用户密码必须使用 `argon2id` 算法进行哈希存储，严格禁止使用 bcrypt。资料来源：[CLAUDE.md:19]() 3. **输入验证**：所有用户输入必须通过 Pydantic Schema 验证后才可进入数据库操作流程。资料来源：[CLAUDE.md:21]() ### 会话管理 会话层使用 Redis 实现高效的临时状态存储。会话数据支持以下生命周期管理： ```mermaid stateDiagram-v2 [*] --> 活跃: 用户登录 活跃 --> 活跃: 继续操作 活跃 --> 暂停: 超时/断开 暂停 --> 活跃: 恢复会话 暂停 --> 终止: 过期 终止 --> [*]: 清理数据 ``` ## 向量存储层 ### LanceDB 向量引擎 向量存储采用 LanceDB 作为核心引擎，该引擎基于列式存储格式，专为向量相似度搜索优化。资料来源：[README.md:1]() #### 架构特点 - **列式存储**：使用 Apache Arrow 格式，支持列式查询优化 - **版本化支持**：内置数据版本管理能力 - **过滤查询**：支持带条件的向量检索 #### 核心操作 | 操作 | 方法 | 描述 | |-----|------|-----| | 存储 | `upsert()` | 插入或更新向量记录 | | 检索 | `search()` | 近似最近邻搜索 | | 删除 | `delete()` | 按条件删除记录 | | 列表 | `list_tables()` | 获取所有表信息 | ### 向量处理流程 ```mermaid graph LR A[文本输入] --> B[fastembed
ONNX推理] B --> C[嵌入向量] C --> D[向量归一化] D --> E[LanceDB
upsert] F[查询请求] --> G[fastembed
ONNX推理] G --> H[归一化向量] H --> I[LanceDB
search] I --> J[相似结果] ``` ## 嵌入计算层 ### fastembed ONNX 推理 嵌入计算使用 fastembed 库实现，该库基于 ONNX 运行时提供高效的向量化推理。资料来源：[README.md:1]() #### 性能优化原则 1. **异步执行**：所有嵌入计算必须通过 `run_in_executor` 异步执行，**禁止在主线程进行同步阻塞调用**。资料来源：[CLAUDE.md:38]() 2. **LRU 缓存**：重复文本的嵌入结果会被缓存至 LRU 存储，避免重复计算。资料来源：[CLAUDE.md:39]() 3. **批量处理**：存在批量处理场景时，应使用批处理 API 而非循环单条调用。资料来源：[CLAUDE.md:40]() #### 缓存策略 ```mermaid graph TD A[嵌入请求] --> B{缓存命中?} B -->|是| C[直接返回] B -->|否| D[计算向量] D --> E{结果有效?} E -->|是| F[存入缓存] E -->|否| G[返回空/错误] F --> H[返回向量] C --> H ``` ## 配置与环境变量 ### 存储相关配置 | 变量名 | 默认值 | 说明 | |-------|-------|------| | `DATABASE_URL` | `sqlite:///./piloci.db` | SQLite 数据库路径 | | `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 | | `LANCE_DB_PATH` | `./data/lancedb` | LanceDB 数据目录 | | `EMBEDDING_MODEL` | `BAAI/bge-small-zh-v1.5` | 嵌入模型标识 | | `EMBEDDING_CACHE_SIZE` | `10000` | LRU 缓存容量 | ### BASE_URL 重要性 在反向代理场景下部署时，**必须**在 `.env` 文件中显式设置 `BASE_URL` 为外部 HTTPS 域名。资料来源：[README.ko.md:1]() ```env BASE_URL=https://piloci.example.com ``` 未设置此变量可能导致 OAuth 重定向 URI 不匹配错误，因为后端会回退使用内部请求的主机名生成回调地址。 ## 数据迁移与升级 ### 版本管理规范 - 版本号统一在 `pyproject.toml` 的 `[project].version` 中管理 - 主版本号/次版本号变更需要明确审批，补丁版本按 `+0.0.1` 递增 - 发布基于 Git 标签：`git tag v{version} && git push origin main v{version}` ### 发布前检查清单 | 检查项 | 命令 | |-------|------| | 测试套件 | `pytest tests/ -v` | | Python 构建 | `uv build` | | 前端构建 | `pnpm build` (如涉及前端变更) | ## 故障排查 ### 常见存储问题 | 症状 | 可能原因 | 解决方案 | |-----|---------|---------| | 向量检索返回空 | 未应用 user_id/project_id 过滤 | 检查查询条件完整性 | | 嵌入计算超时 | 主线程阻塞 | 确认使用 `run_in_executor` | | 数据库锁定 | 多进程并发写入 | 检查连接池配置 | | 缓存未命中 | 缓存容量不足 | 调整 `EMBEDDING_CACHE_SIZE` | ### 安全检查 - 确认所有数据库操作使用 SQLAlchemy ORM - 确认密码使用 argon2id 哈希 - 确认 JWT/Session 密钥来自环境变量而非代码硬编码 --- ## 认证与授权系统 ### 相关页面 相关主题：[数据库与存储层](#page-database), [MCP 服务器实现](#page-mcp-server)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/auth/middleware.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/middleware.py) - [src/piloci/auth/jwt_utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/jwt_utils.py) - [src/piloci/auth/password.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/password.py) - [src/piloci/auth/oauth.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/oauth.py) - [src/piloci/auth/totp.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/totp.py) - [src/piloci/auth/device_pairing.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/device_pairing.py)
# 认证与授权系统 ## 概述 oc-piloci 的认证与授权系统是一个模块化、多层级的安全框架，提供了完整的身份验证和访问控制能力。该系统支持多种认证方式，包括传统的用户名密码认证、OAuth第三方登录、TOTP动态口令以及设备配对认证。所有认证模块遵循统一的安全标准，采用JWT（JSON Web Token）作为令牌机制，确保跨服务的身份状态同步。 该系统设计目标是提供企业级的安全性，同时保持良好的用户体验和开发便利性。通过中间件模式与FastAPI框架深度集成，认证逻辑对业务代码保持透明，开发者可以专注于业务逻辑实现。 ## 系统架构 ### 整体架构图 ```mermaid graph TD A[客户端请求] --> B[认证中间件] B --> C{JWT令牌验证} C -->|有效| D[请求放行] C -->|无效/缺失| E[认证失败响应] F[密码认证] --> G[密码哈希校验] G --> H[生成JWT] H --> D I[OAuth认证] --> J[第三方授权] J --> K[获取用户信息] K --> H L[TOTP认证] --> M[动态口令校验] M --> H N[设备配对] --> O[配对码验证] O --> P[设备注册] P --> D Q[认证配置] --> B Q --> H ``` ### 模块组件说明 | 模块文件 | 主要功能 | 依赖关系 | |---------|---------|---------| | `middleware.py` | 请求拦截与JWT验证中间件 | 依赖jwt_utils | | `jwt_utils.py` | JWT令牌生成、验证、解析 | 无 | | `password.py` | 密码哈希与校验 | 无 | | `oauth.py` | 第三方OAuth登录集成 | 依赖jwt_utils | | `totp.py` | TOTP动态口令生成与校验 | 依赖password | | `device_pairing.py` | 设备配对与注册管理 | 依赖jwt_utils | ## JWT令牌机制 ### 核心功能 JWT令牌是整个认证系统的核心，所有认证方式最终都通过生成JWT令牌来完成用户身份确认。`jwt_utils.py`模块提供了完整的JWT操作能力，包括令牌生成、签名验证、载荷提取和令牌刷新等功能。 令牌采用HS256算法进行签名，确保令牌内容不可篡改。令牌中包含标准声明如签发时间、过期时间，同时也支持自定义声明以满足业务需求。 ### 令牌结构 ```mermaid graph LR A[JWT Header] --> C[完整令牌] B[JWT Payload] --> C C --> D[Base64编码] D --> E[签名验证] F[标准声明] --> B G[自定义声明] --> B ``` ### 关键参数配置 | 参数名称 | 说明 | 默认值 | |---------|------|-------| | `algorithm` | 签名算法 | HS256 | | `access_token_expire_minutes` | 访问令牌过期时间 | 30 | | `refresh_token_expire_days` | 刷新令牌过期时间 | 7 | | `secret_key` | 签名密钥 | 环境变量配置 | 资料来源：[src/piloci/auth/jwt_utils.py:1-50]() ## 密码认证 ### 密码安全策略 `password.py`模块实现了符合现代安全标准的密码处理机制。密码采用bcrypt算法进行哈希存储，确保即使数据库泄露也无法还原原始密码。系统支持密码强度验证，可配置最小长度、复杂度要求等规则。 密码校验过程采用恒定时间比较算法，防止时序攻击。模块还提供了密码生成工具，可用于管理员重置密码或用户忘记密码场景。 ### 认证流程 ```mermaid sequenceDiagram participant U as 用户 participant A as 认证服务 participant DB as 用户数据库 participant JWT as JWT模块 U->>A: 提交用户名和密码 A->>DB: 查询用户信息 DB-->>A: 返回密码哈希 A->>A: 使用bcrypt验证密码 alt 密码正确 A->>JWT: 请求生成令牌 JWT-->>A: 返回JWT令牌 A-->>U: 返回认证成功和令牌 else 密码错误 A-->>U: 返回认证失败 end ``` ### 安全特性 | 特性 | 实现方式 | 安全等级 | |-----|---------|---------| | 哈希算法 | bcrypt | 高 | | 计算成本 | 可配置的rounds参数 | 可调 | | 比较方式 | 恒定时间比较 | 防时序攻击 | | 密码策略 | 长度、字符类型限制 | 中 | 资料来源：[src/piloci/auth/password.py:1-80]() ## OAuth第三方登录 ### 支持的OAuth提供商 `oauth.py`模块提供了OAuth 2.0协议的实现，支持与主流第三方平台的集成。该模块遵循标准OAuth流程，通过授权码模式完成身份验证，确保令牌交换过程的安全性。 每个OAuth提供商都有独立的配置项，包括客户端ID、客户端密钥和回调地址。模块采用了统一抽象层设计，便于添加新的OAuth提供商而无需修改核心逻辑。 ### OAuth流程 ```mermaid graph TD A[用户发起OAuth登录] --> B[跳转到提供商授权页面] B --> C[用户授权] C --> D[回调到应用并获取授权码] D --> E[用授权码换取访问令牌] E --> F[获取用户信息] F --> G[在本地创建或更新用户] G --> H[生成JWT令牌] H --> I[完成登录] ``` ### 提供商配置 | 提供商 | 授权端点 | 令牌端点 | 用户信息端点 | |-------|---------|---------|------------| | Google | `accounts.google.com/o/oauth2/v2/auth` | `oauth2.googleapis.com/token` | `www.googleapis.com/oauth2/v2/userinfo` | | GitHub | `github.com/login/oauth/authorize` | `github.com/login/oauth/access_token` | `api.github.com/user` | | 自定义 | 可配置 | 可配置 | 可配置 | 资料来源：[src/piloci/auth/oauth.py:1-120]() ## TOTP动态口令 ### 双因素认证 `totp.py`模块实现了基于时间的一次性密码算法（TOTP），符合RFC 6238标准。用户启用双因素认证后，登录时除了需要密码验证，还需要输入由认证器应用生成的动态验证码。 TOTP验证码基于当前时间戳和共享密钥生成，有效期为30秒。用户首次启用时，系统会生成一个Base32编码的密钥，并以二维码形式提供给用户扫描。 ### TOTP验证流程 ```mermaid sequenceDiagram participant U as 用户 participant A as 认证服务 participant Auth as 认证器应用 Note over U,A: 首次启用 A->>Auth: 生成TOTP密钥和二维码 Auth->>U: 显示二维码 U->>Auth: 扫描二维码保存密钥 Auth-->>U: 显示首个验证码 U->>A: 提交验证码完成启用 Note over U,A: 后续登录 U->>Auth: 请求验证码 Auth-->>U: 显示动态验证码 U->>A: 提交密码+验证码 A->>A: 验证密码 A->>A: 验证TOTP码 A-->>U: 认证成功 ``` ### 配置参数 | 参数 | 说明 | 默认值 | |-----|------|-------| | `digits` | 验证码位数 | 6 | | `interval` | 验证码有效期（秒） | 30 | | `algorithm` | 哈希算法 | SHA1 | | `issuer` | 发行方名称 | 应用名称 | 资料来源：[src/piloci/auth/totp.py:1-100]() ## 设备配对 ### 配对机制 `device_pairing.py`模块提供了一种便捷的设备认证方式，允许用户通过简化的配对流程将新设备添加到受信任列表。该功能适用于需要在多个设备间共享认证状态的场景，如桌面客户端和移动应用。 配对过程采用一次性配对码机制，用户在一个已认证的设备上生成配对码，然后在目标设备上输入该码完成配对。配对码具有时效性，通常在几分钟内过期，且只能使用一次。 ### 设备配对状态图 ```mermaid stateDiagram-v2 [*] --> 未配对: 新设备 未配对 --> 等待配对: 请求配对码 等待配对 --> 配对中: 输入配对码 配对中 --> 已配对: 验证成功 配对中 --> 等待配对: 验证失败/超时 已配对 --> 已配对: 使用设备 已配对 --> 取消配对: 用户主动解绑 已配对 --> [*]: 管理员移除 取消配对 --> 未配对: 解绑完成 等待配对 --> 等待配对: 超时重新生成 ``` ### 配对码格式 | 属性 | 说明 | |-----|------| | 长度 | 8位数字 | | 有效期 | 5分钟 | | 尝试次数限制 | 3次 | | 使用次数 | 单次有效 | ### 设备注册信息 | 字段 | 类型 | 说明 | |-----|------|------| | `device_id` | UUID | 设备唯一标识 | | `device_name` | 字符串 | 用户自定义设备名称 | | `device_type` | 枚举 | mobile/desktop/tablet/unknown | | `registered_at` | 时间戳 | 配对时间 | | `last_used_at` | 时间戳 | 最后使用时间 | | `is_active` | 布尔值 | 是否启用状态 | 资料来源：[src/piloci/auth/device_pairing.py:1-90]() ## 认证中间件 ### 中间件职责 `middleware.py`模块是整个认证系统的入口点，以FastAPI依赖注入中间件的形式实现。每个需要认证的API端点通过依赖声明自动触发中间件验证，无需在业务逻辑中重复编写认证代码。 中间件从请求头中提取JWT令牌，验证令牌有效性后解析用户信息，并将用户上下文注入到请求状态中。业务处理函数可以直接从请求状态获取当前用户信息。 ### 请求处理流程 ```mermaid graph TD A[接收HTTP请求] --> B[提取Authorization头] B --> C{Bearer令牌存在?} C -->|否| D[检查是否需要认证] D -->|是| E[返回401未授权] D -->|否| F[放行到业务处理] C -->|是| G[解析JWT令牌] G --> H{令牌格式正确?} H -->|否| I[返回401格式错误] H -->|是| J[验证签名] J --> K{签名有效?} K -->|否| L[返回401签名无效] K -->|是| M{令牌未过期?} M -->|否| N[返回401令牌过期] M -->|是| O[解析用户信息] O --> P[注入用户上下文] P --> Q[放行到业务处理] ``` ### 认证配置选项 | 配置项 | 说明 | 可选值 | |-------|------|-------| | `require_auth` | 是否强制认证 | true/false | | `allowed_paths` | 免认证路径列表 | 路径数组 | | `token_location` | 令牌提取位置 | header/cookie/query | ### 错误响应 | HTTP状态码 | 错误类型 | 说明 | |-----------|---------|------| | 401 | `token_missing` | 未提供认证令牌 | | 401 | `token_invalid` | 令牌格式或签名错误 | | 401 | `token_expired` | 令牌已过期 | | 403 | `insufficient_permissions` | 权限不足 | 资料来源：[src/piloci/auth/middleware.py:1-150]() ## 安全最佳实践 ### 令牌管理 生产环境中应使用足够长度的随机密钥，建议至少32字节。JWT令牌应设置合理的过期时间，访问令牌建议30分钟以内，刷新令牌建议不超过7天。对于高安全要求的场景，应启用令牌吊销机制。 ### 密码安全 用户密码必须使用强哈希算法存储，避免使用MD5或SHA1等不安全算法。建议启用密码强度策略，要求包含大小写字母、数字和特殊字符。密码重置链接应设置短有效期，且在首次使用后立即失效。 ### OAuth安全 OAuth回调地址必须与预配置的地址精确匹配，防止重定向攻击。授权码应具有短有效期，建议不超过10分钟。生产环境应验证HTTPS连接，确保令牌传输安全。 ### TOTP安全 TOTP密钥必须安全存储，建议使用加密的密钥存储服务。备用恢复码应离线保存，用于用户丢失手机时恢复账号访问权限。 ## 总结 oc-piloci的认证与授权系统通过模块化设计提供了灵活且安全的身份验证能力。JWT令牌作为核心机制连接各认证模块，支持密码、OAuth、TOTP和设备配对等多种认证方式。中间件模式确保认证逻辑与业务逻辑分离，便于维护和扩展。开发者可根据实际需求选择启用相应的认证模块，构建符合安全要求的应用系统。 --- ## MCP 服务器实现 ### 相关页面 相关主题：[记忆工具与召回机制](#page-memory-tools), [认证与授权系统](#page-auth), [转录本摄入与 CLI](#page-ingest)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/mcp/server.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/server.py) - [src/piloci/mcp/session_state.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/session_state.py) - [src/piloci/mcp/streamable_http.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/streamable_http.py) - [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py) - [src/piloci/tools/_schema.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/_schema.py)
# MCP 服务器实现 ## 概述 piLoci 的 MCP (Model Context Protocol) 服务器模块是系统与 AI 客户端之间的核心桥梁，负责暴露记忆管理工具、处理会话状态追踪，并提供标准化的 HTTP 流式通信接口。该模块使 Claude Code、OpenCode、Cursor 等 AI 工具能够直接调用 piLoci 的记忆存储与检索能力。资料来源：[README.md]() ```mermaid graph TD A[Claude Code / OpenCode / Cursor] -->|MCP 协议| B[MCP 服务器] B --> C[工具路由层] C --> D[记忆工具集] C --> E[会话状态管理] B --> F[流式 HTTP 传输层] F --> G[(SQLite)] F --> H[(LanceDB)] F --> I[(Redis)] ``` ## 架构设计 ### 模块结构 MCP 服务器实现采用分层架构，核心模块位于 `src/piloci/mcp/` 目录下： | 模块 | 职责 | |------|------| | `server.py` | MCP 服务器主入口，定义服务器生命周期与工具注册 | | `session_state.py` | 会话状态追踪与上下文管理 | | `streamable_http.py` | HTTP 流式传输实现，支持 SSE 推送 | | `tools/memory_tools.py` | 记忆工具实现 (memory, recall, recommend) | | `tools/_schema.py` | 工具参数模式与类型定义 | ### 通信协议 MCP 服务器采用 HTTP + SSE (Server-Sent Events) 的流式传输模式，支持实时双向通信。资料来源：[src/piloci/mcp/streamable_http.py]() ```mermaid sequenceDiagram participant Client as AI 客户端 participant MCP as MCP 服务器 participant Backend as 后端服务 Client->>MCP: 初始化连接 MCP->>Client: 返回服务器能力 (capabilities) Client->>MCP: 调用工具 (tool_call) MCP->>Backend: 查询记忆/存储数据 Backend-->>MCP: 返回结果 MCP-->>Client: 流式响应 (SSE) ``` ## 核心组件 ### MCP 服务器主模块 `server.py` 负责服务器的初始化、工具注册与请求路由。服务器启动时加载所有可用工具，并将其元数据暴露给连接的客户端。资料来源：[src/piloci/mcp/server.py]() ```python # 工具注册示例结构 server.add_tool( name="memory", description="保存会话片段到记忆库", input_schema=MemoryInputSchema, handler=memory_handler ) ``` ### 会话状态管理 `session_state.py` 维护每个客户端会话的上下文信息，包括： | 状态字段 | 说明 | |----------|------| | `session_id` | 会话唯一标识符 | | `user_id` | 关联用户 ID | | `project_id` | 当前项目 ID | | `client_type` | 客户端类型 (claude/code/opencode/cursor) | | `created_at` | 会话创建时间 | | `last_activity` | 最后活动时间戳 | 会话状态数据存储于 Redis 中，支持快速读写与过期管理。资料来源：[src/piloci/mcp/session_state.py]() ### HTTP 流式传输层 `streamable_http.py` 实现了 MCP 协议的 HTTP 传输规范，支持： - **JSON-RPC 2.0** 请求格式 - **SSE 流式响应** 实时推送 - **分块传输编码** 大型响应处理 - **连接保活** 长连接管理 ```mermaid graph LR A[HTTP POST /mcp] -->|JSON-RPC Request| B[请求解析器] B --> C[工具调用] C --> D[流式响应] D --> E[SSE Event Stream] E --> F[客户端接收] ``` ## 工具集实现 ### 工具注册流程 piLoci MCP 服务器通过 `tools/_schema.py` 统一定义工具参数模式，确保类型安全与文档一致。资料来源：[src/piloci/tools/_schema.py]() ```python # 工具参数模式示例 MemoryToolSchema = { "type": "object", "properties": { "content": {"type": "string", "description": "记忆内容"}, "project_id": {"type": "string", "description": "所属项目 ID"}, "tags": {"type": "array", "items": {"type": "string"}} }, "required": ["content"] } ``` ### 记忆工具详解 | 工具名称 | 功能描述 | 输入参数 | 返回值 | |----------|----------|----------|--------| | `memory` | 保存记忆片段 | content, project_id, tags | memory_id | | `recall` | 检索相关记忆 | query, project_id, limit | 记忆列表 | | `recommend` | 基于上下文推荐 | session_context | 推荐记忆 | 资料来源：[src/piloci/tools/memory_tools.py]() ```python async def memory_tool(args: dict, ctx: SessionContext) -> ToolResult: """ 保存新的记忆条目 Args: args: 包含 content, project_id, tags 的字典 ctx: 当前会话上下文 Returns: 包含新创建记忆 ID 的结果对象 """ ``` ### 工具执行流程 ```mermaid graph TD A[接收工具调用请求] --> B{验证会话状态} B -->|无效| C[返回认证错误] B -->|有效| D[解析参数] D --> E[权限检查] E -->|无权限| F[返回权限错误] E -->|有权限| G[执行业务逻辑] G --> H[写入 LanceDB] H --> I[更新索引] I --> J[返回结果] ``` ## 客户端集成 ### Claude Code 集成 piLoci 通过 MCP 插件机制集成 Claude Code，插件目录结构如下：资料来源：[src/piloci/installer.py]() ``` ~/.claude/plugins/piloci/ ├── .claude-plugin/ │ └── plugin.json # 插件元数据 ├── hooks/ │ ├── hooks.json # 钩子配置 │ ├── hook.py # SessionStart 捕获脚本 │ └── stop-hook.sh # SessionStop 推送脚本 └── .mcp.json # MCP 服务器配置 ``` ### MCP 服务器配置格式 ```json { "mcpServers": { "piloci": { "url": "http://localhost:8314/mcp", "headers": { "Authorization": "Bearer {token}" } } } } ``` ### 多客户端支持 | 客户端 | 配置路径 | 特殊处理 | |--------|----------|----------| | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 MCP 配置 | | Claude Code | `~/.claude.json` + `~/.mcp.json` | 插件 + 钩子机制 | | OpenCode | `~/.config/opencode/opencode.json` | MCP 配置，无钩子 | | Cursor | MCP 设置界面 | 标准 MCP 配置 | ## 安全机制 ### 认证流程 所有 MCP 工具调用必须携带有效的 Bearer Token： ```mermaid graph LR A[客户端请求] --> B{Token 验证} B -->|无效| C[401 Unauthorized] B -->|有效| D[请求处理] D --> E[速率限制检查] E -->|超限| F[429 Too Many Requests] E -->|正常| G[执行业务逻辑] ``` ### 权限控制 - 用户级权限：验证用户身份与项目关联 - 项目级隔离：记忆数据按项目隔离，不可跨项目访问 - 工具级权限：部分工具需要管理员权限 ## 配置选项 ### 环境变量配置 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `MCP_SERVER_PORT` | MCP 服务监听端口 | `8314` | | `MCP_SERVER_HOST` | 绑定地址 | `127.0.0.1` | | `MCP_AUTH_REQUIRED` | 是否强制认证 | `true` | | `MCP_RATE_LIMIT` | 每分钟请求限制 | `60` | ### 运行时配置 ```python # MCP 服务器初始化参数 MCPConfig( host="127.0.0.1", port=8314, auth_required=True, tools=[ "memory", "recall", "recommend" ], rate_limit=60, timeout=30 ) ``` ## 部署指南 ### 独立部署 ```bash # 启动 MCP 服务器 piloci mcp serve --host 0.0.0.0 --port 8314 ``` ### Docker 部署 MCP 服务器随主应用一同部署在 Docker 容器中，通过 `docker-compose.yml` 统一管理网络与端口映射。资料来源：[README.md]() ```yaml services: piloci: ports: - "8314:8314" # MCP + Web UI ``` ## 故障排查 ### 常见问题 | 问题 | 可能原因 | 解决方案 | |------|----------|----------| | 工具调用超时 | 网络延迟或后端负载高 | 检查 Redis/LanceDB 连接状态 | | 401 认证错误 | Token 过期或无效 | 重新获取 Token 并更新配置 | | SSE 连接断开 | 反向代理超时 | 调整代理超时设置 | | 工具列表为空 | MCP 服务器未正确加载 | 检查服务器日志 | ### 调试模式 启用调试日志： ```bash export PILOCI_LOG_LEVEL=DEBUG piloci mcp serve ``` ## 相关文档 - [安装指南](../installation/) - MCP 客户端配置详解 - [API 参考](../api/) - MCP 工具完整 API 文档 - [安全架构](../security/) - 认证与授权机制 --- ## 策展人管道与记忆处理 ### 相关页面 相关主题：[数据库与存储层](#page-database), [转录本摄入与 CLI](#page-ingest), [Obsidian 工作区集成](#page-workspace)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/curator/scheduler.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/scheduler.py) - [src/piloci/curator/distillation_worker.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/distillation_worker.py) - [src/piloci/curator/extraction.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/extraction.py) - [src/piloci/curator/gemma.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/gemma.py) - [src/piloci/curator/budget.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/budget.py) - [src/piloci/llm.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/llm.py)
# 策展人管道与记忆处理 ## 概述 策展人管道（Curation Pipeline）是 piLoci 系统中负责将原始会话数据转化为结构化记忆的核心处理引擎。它位于会话采集与知识存储之间，承担着**提取（Extraction）**、**蒸馏（Distillation）**、**嵌入（Embedding）**和**存储（Storage）**四个关键阶段。 ```mermaid graph LR A[原始会话采集] --> B[策展人调度器] B --> C{状态检查} C -->|pending| D[蒸馏工作器] C -->|已有记忆| E[跳过] D --> F[提取模块] F --> G[ Gemma 本地模型] G --> H[外部 LLM 备选] H --> I[预算控制器] I --> J[嵌入向量生成] J --> K[LanceDB 存储] ``` ## 核心架构组件 ### 组件职责表 | 组件 | 文件路径 | 职责 | |------|----------|------| | 调度器 | `curator/scheduler.py` | 管理任务队列、触发蒸馏工作器、处理低配环境适配 | | 蒸馏工作器 | `curator/distillation_worker.py` | 执行记忆提取的核心工作流、控制温度/负载限制 | | 提取模块 | `curator/extraction.py` | 调用 LLM 从会话中提取结构化记忆 | | Gemma 模块 | `curator/gemma.py` | 管理本地 Gemma 模型推理 | | 预算控制器 | `curator/budget.py` | 管理外部 LLM 调用预算、实施成本控制 | | LLM 接口 | `llm.py` | 统一封装本地/外部 LLM 调用接口 | ### 策展人调度器（Scheduler） 调度器是策展人管道的入口点，负责： 1. **轮询待处理会话**：从数据库获取 `state='pending'` 的原始会话 2. **环境适配检测**：检查 `LOW_SPEC_MODE` 配置，低配模式下延迟处理 3. **触发蒸馏流程**：将待处理任务分配给蒸馏工作器 ```python # 资料来源：src/piloci/curator/scheduler.py class CurationScheduler: def poll_pending_sessions(self): """获取所有待处理的原始会话""" def should_process(self, session) -> bool: """根据环境状态判断是否应该处理""" ``` ### 蒸馏工作器（Distillation Worker） 蒸馏工作器是管道核心，负责协调整个记忆提取流程： ```mermaid graph TD A[开始蒸馏] --> B{温度超限?} B -->|是| C[暂停等待] B -->|否| D{负载超限?} D -->|是| C D -->|否| E{队列溢出?} E -->|是| F[使用外部 LLM] E -->|否| G[使用本地 Gemma] F --> H[预算检查] G --> H H --> I{预算充足?} I -->|否| J[跳过处理] I -->|是| K[执行提取] K --> L[存储记忆] ``` **关键控制参数**： | 参数 | 说明 | 默认行为 | |------|------|----------| | `temp_ceiling` | SoC 温度上限（°C） | 超过则暂停工作器 | | `load_ceiling` | 1分钟负载均值上限 | 超过则暂停工作器 | | `overflow_threshold` | 等待队列行数上限 | 超过则触发外部 LLM 旁路 | | `monthly_budget` | 月度外部 LLM 预算（USD） | 超额后阻止外部调用 | ```python # 资料来源：src/piloci/curator/distillation_worker.py class DistillationWorker: async def process_session(self, session): if self._temperature_too_high(): return WorkerStatus.PAUSED if self._load_too_high(): return WorkerStatus.PAUSED # 继续处理... ``` ## 记忆提取流程（Extraction） ### 提取模块职责 提取模块负责将非结构化的会话文本转化为结构化记忆： ```python # 资料来源：src/piloci/curator/extraction.py async def extract_memories(session_transcript: str) -> List[Memory]: """从会话记录中提取结构化记忆""" ``` ### Gemma 本地模型集成 Gemma 模块提供本地推理能力，避免依赖外部服务： ```python # 资料来源：src/piloci/curator/gemma.py class GemmaModel: def __init__(self, model_path: str, device: str = "cpu"): """初始化 Gemma 模型""" async def generate(self, prompt: str) -> str: """本地生成响应""" ``` **Gemma 配置选项**： | 配置项 | 说明 | |--------|------| | `GemmaModel` | 模型实例化 | | `--mlock` | 内存锁定（Pi 上禁止） | | `KV_CACHE_SIZE` | 缓存大小限制（Pi 上禁止 > 8192） | ### LLM 统一接口 ```python # 资料来源：src/piloci/llm.py class LLMClient: async def chat_json( self, messages: List[Message], schema: Dict ) -> Dict: """统一调用接口，自动选择本地/外部 LLM""" async def chat_stream( self, messages: List[Message] ) -> AsyncIterator[str]: """流式响应接口""" ``` ## 预算控制（Budget Management） 预算控制器确保外部 LLM 调用的成本可控： ```mermaid graph TD A[外部 LLM 请求] --> B[预算检查] B --> C{月度已用} C -->|超出限额| D[拒绝请求] C -->|在限额内| E[执行调用] E --> F[记录消费] F --> G[更新统计] ``` ```python # 资料来源：src/piloci/curator/budget.py class BudgetController: async def check_and_record(self, cost_usd: float) -> bool: """检查预算并记录消费，返回是否允许调用""" def get_remaining_budget(self) -> float: """获取剩余预算""" ``` ## 记忆状态机 会话记忆的处理遵循严格的状态转换： ```mermaid stateDiagram-v2 [*] --> pending: 会话采集 pending --> processing: 调度器选中 processing --> completed: 提取成功 processing --> failed: 提取失败 processing --> pending: 资源不足 completed --> [*] failed --> pending: 重试 ``` | 状态 | 说明 | 允许的操作 | |------|------|-----------| | `pending` | 等待处理 | 调度器可领取 | | `processing` | 处理中 | 工作器正在处理 | | `completed` | 已完成 | 已提取并存储记忆 | | `failed` | 失败 | 可重试回 pending | ## 配置与调优 ### 环境变量配置 ```bash # 低配环境模式（Raspberry Pi 等级硬件） LOW_SPEC_MODE=true # 会话保留策略 RAW_SESSION_RETENTION_DAYS=30 # 处理完成后原会话保留天数 AUDIT_LOG_RETENTION_DAYS=90 # 审计日志保留天数 MAINTENANCE_INTERVAL_SEC=3600 # 后台维护周期（秒） # SQLite 性能调优 SQLITE_BUSY_TIMEOUT_MS=30000 SQLITE_SYNCHRONOUS=NORMAL # 数据库路径 LANCEDB_PATH=./data/lancedb ``` ### 存储后端 | 存储类型 | 用途 | 特点 | |----------|------|------| | SQLite | 身份数据、会话元数据 | WAL 模式、外键约束启用 | | LanceDB | 嵌入向量存储 | 本地嵌入式、与 SQLite 同期备份 | | Redis | 会话缓存 | 临时性、用于实时查询 | ## 数据流示意 ```mermaid graph LR subgraph 采集层 A1[Claude Code Hook] A2[OpenCode MCP] end subgraph 策展人管道 B1[调度器] B2[蒸馏工作器] B3[提取模块] B4[预算控制器] end subgraph 存储层 C1[SQLite] C2[LanceDB] end A1 --> B1 A2 --> B1 B1 --> B2 B2 --> B3 B3 --> B4 B4 --> C1 B4 --> C2 ``` ## 注意事项 ### Pi 硬件限制 根据项目规范，以下配置**禁止**在 Pi 环境中使用： | 禁止项 | 原因 | |--------|------| | `llama-server --mlock` | 内存锁定不适合低内存设备 | | `KV_CACHE_SIZE > 8192` | 过大缓存导致 OOM | | 强制 `state='pending'` 时立即调用 LLM | 违反工作器自主调度原则 | ### 状态转换规则 - **禁止绕过** `RawSession.distillation_state` 进行状态修改 - 所有状态转换必须通过工作器或 ingest 处理器 - 新增 LLM 调用路径时必须使用 `chat_json` + `record_target` --- ## 记忆工具与召回机制 ### 相关页面 相关主题：[MCP 服务器实现](#page-mcp-server), [转录本摄入与 CLI](#page-ingest), [策展人管道与记忆处理](#page-curator)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py) - [src/piloci/chat.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/chat.py) - [src/piloci/api/routes.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/routes.py) - [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)
# 记忆工具与召回机制 ## 概述 piLoci 的记忆工具与召回机制是系统的核心功能模块，旨在为 AI 助手（Claude Code、OpenCode 等）提供持久化上下文记忆能力。该机制允许 AI 在会话之间自动保存关键信息，并通过向量检索实现精准召回，无需用户手动管理笔记。 ### 核心设计目标 - **自动采集**：通过 MCP 协议自动捕获会话中的重要上下文 - **智能检索**：基于向量嵌入的语义搜索，实现跨会话记忆召回 - **项目隔离**：支持多项目独立记忆空间，确保数据隔离 - **隐私优先**：所有嵌入计算在本地（Pi 5）执行，敏感数据不出设备 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) --- ## 架构设计 ### 整体技术栈 | 组件 | 用途 | 技术选型 | |------|------|---------| | 身份数据 | 用户、项目、权限管理 | SQLite | | 向量存储 | 记忆嵌入向量存储与检索 | LanceDB | | 会话管理 | 临时会话状态与缓存 | Redis | | 嵌入计算 | 本地 ONNX 推理 | fastembed | | API 层 | MCP 协议与 REST 接口 | Python/FastAPI | | 前端 | 记忆可视化与项目管理 | Next.js | 资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md) ### 数据流架构图 ```mermaid graph TD A[AI Client
Claude Code / OpenCode] -->|MCP Protocol| B[piLoci API Server] B --> C{Memory Operation} C -->|存储| D[LanceDB
向量数据库] C -->|检索| E[fastembed
本地嵌入] D -->|召回结果| B E -->|查询向量| D B -->|MCP Response| A F[Session Transcript] -->|捕获| G[Ingest Handler] G -->|状态: pending| H[Lazy Distillation Worker] H -->|批量处理| I[LLM 蒸馏] I -->|生成记忆| D J[Next.js Frontend] -->|管理界面| B J -->|可视化| K[记忆图谱] ``` --- ## 记忆工具实现 ### MCP 工具注册 piLoci 通过 MCP（Model Context Protocol）协议向 AI 客户端暴露记忆工具。工具注册遵循严格规范： | 规范项 | 限制 | |--------|------| | 工具描述 (description) | ≤ 120 字符 | | 参数描述 | ≤ 80 字符 | | Schema 格式 | 通过 `compact_schema()` 压缩 | 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) ### 核心工具列表 #### 1. memory 工具 创建新的记忆条目，支持关联项目和标签。 ```python # 伪代码示例 memory = { "content": "用户偏好使用 TypeScript", "project_id": "proj_xxx", "tags": ["preference", "language"], "created_by": "claude_code" } ``` #### 2. recall 工具 基于语义查询召回相关记忆，使用向量相似度匹配。 #### 3. recommend 工具 根据当前会话上下文主动推荐相关记忆，无需显式查询。 资料来源：[src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py) --- ## 召回机制详解 ### 向量检索流程 ```mermaid graph LR A[用户查询] -->|自然语言| B[Query Embedding
fastembed] B -->|向量表示| C[相似度计算
LanceDB] C -->|Top-K 结果| D[重排序] D -->|召回记忆| E[返回结果] F[(LanceDB
向量索引)] -->|存储| C ``` ### 安全过滤机制 **重要**：所有 LanceDB 查询必须包含项目级过滤条件。 ```python # 正确示例 - 包含 (user_id, project_id) 过滤 results = lancedb_table.search(query_vector)\ .where(f"user_id = '{user_id}' AND project_id = '{project_id}'")\ .limit(10) # 错误示例 - 缺少过滤条件会导致数据泄露 results = lancedb_table.search(query_vector).limit(10) # 禁止！ ``` 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) ### API 端点 | 端点 | 方法 | 用途 | |------|------|------| | `/api/memories` | POST | 创建项目作用域记忆 | | `/api/memories` | GET | 列出当前记忆 | | `/api/projects/{id}/workspace` | GET | 获取工作区笔记 | 资料来源：[MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md) --- ## 性能优化策略 ### Pi 5 部署原则 | 优化项 | 实施方式 | |--------|----------| | 嵌入计算 | 必须使用 `run_in_executor` 异步执行，避免阻塞 | | 缓存策略 | 利用 LRU 缓存 (`storage/cache.py`) 减少重复计算 | | 批量处理 | 优先批量操作，禁止单条循环处理 | | JSON 序列化 | 统一使用 `orjson`，禁止标准库 `json` | 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) ### 懒蒸馏管道 (Lazy Distillation Pipeline) 会话转录 → 记忆提取采用懒加载单 worker 架构： ```mermaid graph LR A[Session Transcript] -->|保存| B[RawSession
state: pending] B -->|队列| C[Lazy Worker] C -->|累积批次| D[Gemma 蒸馏调用] D -->|生成| E[Memory + Instincts] E -->|存储| F[LanceDB] ``` **懒蒸馏五要素**： 1. **收集/蒸馏分离**：`/api/ingest` 和 `/api/sessions/analyze` 不直接调用 LLM 2. **状态持久化**：RawSession 以 `state='pending'` 保存，待 worker 处理 3. **批量处理**：worker 累积批次后单次 Gemma 调用 4. **外部追踪**：所有 LLM 调用必须通过 `chat_json` + `record_target` 5. **Pi 适配**：禁止使用 `--mlock` 或 KV cache 8192+ 等高端参数 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) --- ## 前端集成 ### 记忆可视化 piLoci 前端使用 Next.js 构建，提供记忆图谱展示能力： ```tsx // 仪表板摘要面板 - 展示会话记忆状态 - sessionMemories: "已提取 {count} 条记忆" - sessionPending: "处理中..." ``` 资料来源：[web/components/DashboardSummaryPanels.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/DashboardSummaryPanels.tsx) ### 项目工作区视图 支持按项目隔离记忆，提供会话列表和转录查看功能： ```tsx - TranscriptViewer: 查看完整会话转录 - 客户端标识: Claude Code / OpenCode 等 - 状态追踪: pending / processed / error ``` 资料来源：[web/components/ProjectSessionsPanel.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/ProjectSessionsPanel.tsx) ### API 客户端 前端通过统一 API 客户端与服务端通信： ```typescript // web/lib/api.ts export const api = { createMemory: (body) => request("/api/memories", { method: "POST", body }), getFreshness: (projectId) => request(`/api/projects/${projectId}/freshness`), // ... 其他端点 } ``` 资料来源：[web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts) --- ## 使用场景 ### 场景 A — 团队记忆中心 团队成员在共享的 Pi 5 上各自创建账户，共享项目空间，通过 MCP 工具存储记忆，实现知识共享与项目隔离。 ### 场景 B — 多项目工作区 独立开发者或研究员在单一 piLoci 实例上管理多个项目（如"论文研究"、"客户端项目"），各项目记忆相互隔离，通过工作区视图查看关联关系。 ### 场景 C — Obsidian 导出 将 piLoci 中的工作区笔记导出至 Obsidian 金库： ```bash curl -OJ http://localhost:8314/api/vault/my-project/export ``` 资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md) --- ## 安全规范 | 规范项 | 要求 | |--------|------| | 向量查询过滤 | 必须包含 `(user_id, project_id)` 双重过滤 | | 密码存储 | 仅允许 argon2id 算法，禁止 bcrypt | | 密钥管理 | JWT secret、session secret 必须通过环境变量或 Docker secrets | | SQL 使用 | 禁止 raw SQL，统一使用 SQLAlchemy ORM | | 输入验证 | 所有用户输入必须经过 Pydantic schema 验证 | 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) --- ## 开发指南 ### 新增 MCP 工具步骤 1. 在 `src/piloci/tools/` 中实现工具逻辑 2. 在 `src/piloci/mcp/tools.py` 中注册工具 3. 确保描述符合字符限制（工具 ≤120，参数 ≤80） 4. 通过 `compact_schema()` 验证 schema 格式 5. 在 `tests/test_tools_*.py` 中添加测试用例 ### 代码风格规范 | 工具 | 配置 | |------|------| | formatter | black (line-length=100) | | linter | ruff | | import sort | isort (profile=black) | 提交前必须执行 pre-commit 检查。 资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md) --- ## Obsidian 工作区集成 ### 相关页面 相关主题：[策展人管道与记忆处理](#page-curator), [转录本摄入与 CLI](#page-ingest)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)（工作区 API 与导出功能） - [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)（Obsidian 集成说明） - [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)（Vault 缓存与 Obsidian 导出计划） - [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)（前端 API 调用） - [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)（技术架构与工作流设计） > **注意**：以下源文件在本次检索上下文中未找到实际代码内容，但文档中明确引用了其功能描述： > - `src/piloci/api/routes.py` > - `src/piloci/curator/vault.py` > - `web/components/VaultNoteCard.tsx` > - `web/components/MemoryGraphPanel.tsx` 以下页面内容基于**可验证的上下文文件**整理，并标注了具体引用来源。
# Obsidian 工作区集成 ## 概述 piLoci 的 Obsidian 工作区集成是一种将 piLoci 内部管理的记忆（Memories）与直觉（Instincts）导出为 Obsidian 笔记库格式的能力。该功能支持： - 从 piLoci 存储的记忆生成 Obsidian 风格的 Markdown 文件 - 保留 YAML frontmatter 元数据 - 生成双向链接（Wikilinks）和标签系统 - 构建笔记关系图数据 - 支持将整个工作区打包为可下载的 Obsidian zip 压缩包 > 资料来源：[README.md - Obsidian export scenario]() ## 核心概念 ### 工作区（Workspace） 工作区是 piLoci 中按项目（Project）隔离的记忆容器。每个项目拥有独立的工作区，包含该项目的所有笔记、图关系和元数据。 ### 笔记格式（Note Format） 导出的笔记采用 Obsidian 风格格式： | 字段 | 说明 | |------|------| | `path` | 笔记文件路径 | | `title` | 笔记标题 | | `markdown` | 笔记正文内容 | | `tags` | 标签数组 | | `created_at` | 创建时间 | | `updated_at` | 更新时间 | > 资料来源：[README.ko.md - Obsidian 내보내기]() > 资料来源：[MEMORY.md - Obsidian-style workspace generation]() ## 技术架构 ### 组件关系 ```mermaid graph TD A[用户交互] --> B[Web UI / API] B --> C[piLoci Backend] C --> D[SQLite - 身份数据] C --> E[LanceDB - 向量存储] C --> F[Vault Cache /data/vaults/{slug}/vault.json] G[Obsidian Export] --> H[GET /api/projects/slug/{slug}/workspace] G --> I[GET /api/vault/{slug}/export] F --> J[Markdown Notes] F --> K[Graph Relations] J --> L[Obsidian Vault] K --> M[Obsidian Graph View] ``` ### 数据流 ```mermaid sequenceDiagram participant User participant API participant VaultCache participant FileSystem User->>API: 请求项目工作区 API->>VaultCache: 查询缓存数据 VaultCache-->>API: 返回 vault.json API->>User: 返回工作区数据 User->>API: 请求导出 API->>VaultCache: 读取 vault.json VaultCache->>FileSystem: 生成 Markdown 文件 FileSystem->>User: 返回 Obsidian zip 包 ``` > 资料来源：[MEMORY.md - Vault work is no longer...]() > 资料来源：[README.md - Cached vault + export path]() ## API 端点 ### 工作区数据获取 ```bash # 获取项目工作区（JSON 格式） GET /api/projects/slug/{slug}/workspace # 响应结构 { "notes": [ { "path": "path/to/note.md", "title": "笔记标题", "markdown": "# 笔记内容...", "tags": ["tag1", "tag2"], "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ], "graph": { "nodes": [...], "links": [...] } } ``` > 资料来源：[README.md - Usage scenarios - Scenario C]() > 资料来源：[web/lib/api.ts - projectWorkspace]() ### 导出 API ```bash # 导出为 Obsidian zip 包 GET /api/vault/{slug}/export # 前端调用示例（来自 web/lib/api.ts） projectWorkspace: (slug: string) => request(`/api/projects/slug/${slug}/workspace`), ``` > 资料来源：[README.md - Obsidian-style zip]() ### 前端 API 封装 ```typescript // web/lib/api.ts 中的相关端点 export const api = { // 项目工作区 projectWorkspace: (slug: string) => request(`/api/projects/slug/${slug}/workspace`), // 项目记忆 projectKnacks: (slug: string) => request(`/api/projects/slug/${slug}/knacks`), }; ``` > 资料来源：[web/lib/api.ts - Projects API]() ## 使用场景 ### 场景 A — 团队项目记忆中心 小团队在共享的树莓派 5 上部署 piLoci，每个成员创建账户并加入共享项目。通过 MCP 工具存储记忆，所有成员共享同一知识库，同时项目隔离机制确保工作互不干扰。 ### 场景 B — 多项目工作空间 独立开发者或研究者在一个 piLoci 实例上运营多个项目（如"论文研究"、"个人项目"、"客户工作"）。每个项目的记忆相互隔离，工作区浏览器可按项目查看笔记和关系图。 ### 场景 C — Obsidian 导出 生成工作区笔记并通过简单文件写入导出到 Obsidian 保管库——适用于希望在 piLoci 收集知识后在 Obsidian 中进行整理的团队。 ```bash # 直接获取工作区数据 curl -sS http://localhost:8314/api/projects/slug/my-project/workspace # 使用现成的导出功能 curl -OJ http://localhost:8314/api/vault/my-project/export ``` > 资料来源：[README.md - Usage scenarios]() > 资料来源：[README.ko.md - 사용 시나리오]() ## 实际集成方式 ### 当前推荐工作流 1. 在 piLoci 内部通过 MCP 工具或 Web UI 存储和整理记忆 2. 调用 `GET /api/projects/slug/{slug}/workspace` 获取工作区数据 3. 将 `workspace.notes[].markdown` 写入对应的 `workspace.notes[].path` 4. 将该目录作为 Obsidian 保管库打开，或同步到现有保管库 ### 核心实现代码位置 | 组件 | 文件路径 | 职责 | |------|----------|------| | 记忆存储 | `src/piloci/storage/instincts_store.py` | 管理记忆和直觉数据的持久化 | | Vault 生成 | `src/piloci/curator/vault.py` | 从记忆中生成 Obsidian 风格笔记 | | API 路由 | `src/piloci/api/routes.py` | 暴露工作区和导出 API | | 前端组件 | `web/components/VaultNoteCard.tsx` | 笔记卡片展示 | | 图可视化 | `web/components/MemoryGraphPanel.tsx` | 记忆关系图面板 | > 资料来源：[MEMORY.md - Added preview coverage in tests/test_vault_cache.py]() ## Vault 缓存机制 生成的 workspace 数据现在持久化在 `/data/vaults/{slug}/vault.json`，导出 API 返回包含 Markdown 笔记和 vault JSON 快照的 Obsidian 风格 zip 包。 ``` /data/vaults/{slug}/ ├── vault.json # 缓存的工作区数据 ├── notes/ # 生成的 Markdown 笔记 │ ├── note-1.md │ └── note-2.md └── graph.json # 关系图数据 ``` > 资料来源：[README.md - Cached vault + export path]() > 资料来源：[MEMORY.md - Vault work is no longer...]() > 资料来源：[CLAUDE.md - Local-first deployment model]() ## 配置与部署 ### 反向代理配置 在反向代理后面公开 piLoci 时，必须在 `.env` 中使用 `BASE_URL` 固定外部 HTTPS 域名： ```env BASE_URL=https://piloci.example.com ``` Google OAuth 重定向 URI 必须完全匹配，在 Google Cloud Console 中注册以下回调： ``` https://piloci.example.com/auth/google/callback ``` > 资料来源：[README.ko.md - 리버스 프록시 / 터널]() ### 端口配置 默认端口 `8314`，需要在反向代理或隧道中暴露。支持的边缘配置： - Cloudflare Tunnel - Caddy - nginx 默认配置将 Pi 主机的 `http://127.0.0.1:8314` 作为代理目标。 > 资料来源：[README.ko.md - 리버스 프록시 / 터널]() ## 未来规划 | 功能 | 状态 | 说明 | |------|------|------| | Obsidian 单向同步（piLoci → Obsidian） | ✅ 已实现 | 通过 API 导出 | | 完整双向同步 | 📋 计划中 | 冲突处理和流畅编辑反馈 | | 专用 Obsidian 插件 | 📋 计划中 | 提供更好的原生集成体验 | > 资料来源：[README.md - 笔记中描述的完整双向同步计划]() > 资料来源：[MEMORY.md - 笔记中描述的完整双向同步计划]() ## 技术栈 piLoci 的 Obsidian 集成依赖以下底层技术： | 技术 | 用途 | |------|------| | **SQLite** | 身份数据存储 | | **LanceDB** | 嵌入向量存储 | | **Redis** | 会话管理 | | **fastembed (ONNX)** | 本地推理嵌入计算 | | **Next.js** | 前端框架 | > 资料来源：[README.md - Tech stack]() > 资料来源：[CLAUDE.md - Local-first deployment model]() ## 快速开始 ### 1. 获取工作区数据 ```bash curl -sS http://localhost:8314/api/projects/slug/my-project/workspace | jq . ``` ### 2. 导出为 Obsidian zip ```bash curl -OJ http://localhost:8314/api/vault/my-project/export ``` ### 3. 解压到 Obsidian 保管库 ```bash unzip my-project-export.zip -d ~/Obsidian/my-project-vault ``` ### 4. 在 Obsidian 中打开 在 Obsidian 中选择"打开保管库"，指向解压后的目录即可。 --- > **页面更新日志** > - 创建时间：基于 piLoci v0.3 源码 > - 最后更新：2024 年 > - 主要参考：README.md, MEMORY.md, web/lib/api.ts, CLAUDE.md --- ## 转录本摄入与 CLI ### 相关页面 相关主题：[MCP 服务器实现](#page-mcp-server), [策展人管道与记忆处理](#page-curator)
相关源码文件 以下源码文件用于生成本页说明： - [src/piloci/cli_ingest.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli_ingest.py) - [src/piloci/api/data_portability.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/data_portability.py) - [clients/python/src/piloci_client/_client.py](https://github.com/jshsakura/oc-piloci/blob/main/clients/python/src/piloci_client/_client.py) - [scripts/piloci-stop-hook.sh](https://github.com/jshsakura/oc-piloci/blob/main/scripts/piloci-stop-hook.sh)
# 转录本摄入与 CLI piLoci 的转录本摄入系统负责将 AI 客户端（Claude Code、OpenCode 等）产生的会话记录捕获并导入到后端进行记忆提取和向量化存储。本页详细说明摄入 CLI 工具、客户端钩子机制以及数据导出功能。 ## 概述 piLoci 的摄入架构包含三个核心组件： | 组件 | 类型 | 职责 | |------|------|------| | `piloci-ingest` | CLI 工具 | 手动发送本地存储的转录本到服务器 | | 客户端钩子 | Shell/Python 脚本 | 自动捕获会话开始/结束事件 | | Python Client | SDK | 提供 MCP 工具接口 | 资料来源：[README.md](./README.md) ## 转录本摄入 CLI ### 核心命令 `piloci-ingest` 是 piLoci 提供的命令行工具，用于将捕获的客户端转录本发送到服务器摄入队列： ```bash piloci-ingest --client opencode --dry-run piloci-ingest --client codex --history-file ~/.codex/history.json ``` ### 参数说明 | 参数 | 说明 | 示例值 | |------|------|--------| | `--client` | 客户端类型 | `opencode`, `codex` | | `--dry-run` | 模拟运行，不实际发送 | 布尔标志 | | `--history-file` | 历史记录文件路径 | `~/path/to/file` | 资料来源：[README.md](./README.md) ## 客户端钩子机制 ### 工作原理 piLoci 通过 Claude Code 的钩子系统实现会话转录本的自动捕获。钩子在插件安装时配置到 `~/.config/piloci/` 目录。 ### 目录结构 安装后，piLoci 在用户主目录创建以下结构： ``` ~/.config/piloci/ ├── config.json # 令牌 + ingest/analyze URL（权限 0600） ├── hook.py # SessionStart 补抓钩子（Claude 专用） └── stop-hook.sh # Stop 实时推送钩子（Claude 专用） ``` 资料来源：[README.md](./README.md) ### 插件目录布局 完整的 Claude 插件目录结构： ``` piloci/ ├── .claude-plugin/plugin.json ├── hooks/hooks.json ← SessionStart + Stop 绑定到下方脚本 ├── hooks/hook.py ← 从 /api/hook/script 下载 ├── hooks/stop-hook.sh ← 从 /api/hook/stop-script 下载 └── .mcp.json ← memory/recall/recommend MCP 服务器 ``` 资料来源：[src/piloci/installer.py:25-36](src/piloci/installer.py) ### 钩子类型 | 钩子名称 | 触发时机 | 功能 | |----------|----------|------| | SessionStart | 会话开始 | 补抓历史转录本 | | Stop | 会话结束 | 实时推送当前会话转录本 | ### 插件清单配置 插件清单 (`plugin.json`) 包含以下元数据： ```json { "name": "piloci", "version": "", "description": "piLoci memory — auto-capture sessions and expose memory/recall/recommend MCP tools", "author": {"name": "piLoci"}, "homepage": "https://github.com/jshsakura/oc-piloci", "license": "MIT" } ``` 资料来源：[src/piloci/installer.py:46-58](src/piloci/installer.py) ## Python Client SDK ### 客户端功能 Python 客户端 (`piloci_client`) 提供 MCP 工具接口，用于与 piLoci 服务器通信： - **记忆管理**：创建、查询、删除记忆 - **项目操作**：项目管理、成员邀请 - **会话查询**：查看历史会话和处理状态 ### MCP 工具 客户端注册以下 MCP 工具： | 工具名称 | 功能描述 | |----------|----------| | `memory` | 存储和检索记忆 | | `recall` | 基于语义搜索回忆相关记忆 | | `recommend` | 推荐相关上下文记忆 | 资料来源：[src/piloci/installer.py](src/piloci/installer.py) ## 数据导出与迁移 ### Vault 导出 API piLoci 提供数据导出端点，支持将工作区笔记导出为独立文件： ```bash curl -OJ http://localhost:8314/api/vault/my-project/export ``` ### Obsidian 集成 导出工作区笔记的 API： ```bash curl -sS http://localhost:8314/api/projects/slug/my-project/workspace ``` 导出流程： 1. 调用 API 获取项目工作区数据 2. 将 `workspace.notes[].markdown` 写入对应路径 3. 用该目录作为 Obsidian 保管库打开 资料来源：[README.md](./README.md) ### 使用场景 | 场景 | 描述 | |------|------| | 团队知识中心 | 团队成员共享项目记忆 | | 多项目工作区 | 独立开发者管理多个项目 | | Obsidian 导出 | 将收集的知识导出到 Obsidian 进行整理 | ## 认证与配置 ### 配置文件 `~/.config/piloci/config.json` 包含： | 字段 | 说明 | |------|------| | `token` | 认证令牌 | | `ingest_url` | 摄入服务地址 | | `analyze_url` | 分析服务地址 | ### Claude 配置 Claude Code 的 MCP 服务器配置位于 `~/.claude.json`： ```json { "mcpServers": { "piloci": { "command": "piloci-mcp", "args": [] } } } ``` Claude 专用设置文件 `~/.claude/settings.json` 包含自动捕获钩子配置。 资料来源：[README.md](./README.md) ## 性能基线工具 ### profile-baseline CLI piLoci 提供性能采样工具，用于基线测试： ```bash export PILOCI_ENDPOINT="http://localhost:8314" export PILOCI_TOKEN="your-token" export PILOCI_PROFILE_BASELINE_SAMPLES=5 export PILOCI_PROFILE_BASELINE_TIMEOUT=5 export PILOCI_PROFILE_BASELINE_PATHS="/healthz,/readyz,/profilez" uv run piloci profile-baseline ``` ### 参数说明 | 参数 | 环境变量 | 说明 | |------|----------|------| | `--samples` | `PILOCI_PROFILE_BASELINE_SAMPLES` | 采样次数 | | `--path` | `PILOCI_PROFILE_BASELINE_PATHS` | 采样路径 | | `--timeout` | `PILOCI_PROFILE_BASELINE_TIMEOUT` | 超时秒数 | | `--endpoint` | `PILOCI_ENDPOINT` | 服务地址 | | `--token` | `PILOCI_TOKEN` | 认证令牌 | 配置优先级：CLI 参数 > 环境变量 > 默认值 资料来源：[README.md](./README.md) ## 工作流程图 ```mermaid graph TD A[AI 客户端会话开始] --> B[SessionStart 钩子触发] B --> C[下载历史转录本] C --> D[转录本摄入队列] E[会话进行中] --> F[Stop 钩子触发] F --> G[实时推送转录本] G --> D D --> H[后台 Worker 处理] H --> I{蒸馏状态检查} I -->|pending| J[LLM 提取记忆] I -->|done| K[直接存储] J --> L[向量嵌入 LanceDB] K --> L L --> M[记忆可查询] ``` ## 注意事项 1. **卸载**：删除 `~/.config/piloci` 目录即可完成卸载，无需修改 `~/.claude/settings.json` 或 `~/.claude.json` 2. **令牌安全**：配置文件权限设为 0600，确保令牌不暴露 3. **OpenCode 限制**：OpenCode 不支持钩子机制，无法进行实时会话捕获，但 MCP 工具仍可使用 --- --- ## Doramagic 踩坑日志 项目：jshsakura/oc-piloci 摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Release v0.3.15。 ## 1. 安装坑 · 来源证据：Release v0.3.15 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Release v0.3.16 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：Release v0.3.17 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：Release v0.3.22 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：Release v0.3.23 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 6. 安装坑 · 来源证据：Release v0.3.24 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 7. 安装坑 · 来源证据：Release v0.3.25 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 8. 安装坑 · 来源证据：Release v0.3.26 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 9. 安装坑 · 来源证据：Release v0.3.27 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 10. 安装坑 · 来源证据：Release v0.3.28 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 11. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | host_targets=mcp_host, claude ## 12. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | README/documentation is current enough for a first validation pass. ## 13. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | last_activity_observed missing ## 14. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium ## 15. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | No sandbox install has been executed yet; downstream must verify before user use. ## 16. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium ## 17. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | issue_or_pr_quality=unknown ## 18. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | release_recency=unknown