概述

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 工具：

这些工具通过 ~/.mcp.json 配置集成到 Claude Code 环境中，使 LLM 能够直接访问和管理记忆系统。

资料来源：src/piloci/installer.py:1-30

项目隔离与团队协作

piLoci 支持多项目隔离，每个项目拥有独立的记忆空间。同时，通过项目共享机制，团队成员可以访问共同的记忆库，实现知识在团队内的传播和复用。

资料来源：README.md:20-35

技术架构

系统架构图

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

技术栈

资料来源：README.md:40-50

组件结构

前端组件

前端代码位于 web/ 目录，采用 Next.js App Router 架构：

资料来源：web/components/DashboardSummaryPanels.tsx:1-50 资料来源：web/app/admin/users/page.tsx:1-30

后端模块

后端代码位于 src/piloci/ 目录：

资料来源：src/piloci/installer.py:1-50

部署架构

本地部署场景

piLoci 设计为在树莓派 5 上本地运行，通过 Cloudflare Tunnel 等工具实现安全的公网访问。这种架构特别适合：

• 个人开发者拥有完全的数据控制权
• 小型团队共享一台设备，降低成本
• 在网络受限环境中使用

配置要求

反向代理配置中需要正确设置 BASE_URL 环境变量：

BASE_URL=https://piloci.example.com

Google OAuth 回调地址必须与 BASE_URL 完全匹配：

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 调用实现：

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 服务。

1 项目概述

1.1 项目定位

oc-piloci 是一个基于 OCI（Open Container Initiative）标准的容器镜像管理与分发服务。该项目实现了容器镜像的拉取、推送、转换和管理功能，为容器运行时提供标准化的镜像操作接口。

1.2 核心功能范围

资料来源：src/piloci/main.py:1-50

2 整体架构

2.1 架构分层设计

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 模块依赖关系

资料来源：src/piloci/api/v1.py:1-30

3 核心模块详解

3.1 配置管理模块

配置模块负责管理应用的运行时配置，包括镜像仓库地址、认证信息、超时设置等参数。

# 配置加载流程
配置文件 → 环境变量 → 命令行参数 → 默认值

关键配置项：

资料来源：src/piloci/config.py:1-80

3.2 核心服务模块

核心模块（core.py）实现了镜像操作的业务逻辑，包括：

• 镜像manifest处理：解析和构建 OCI Image Manifest
• 层管理：处理镜像层的下载、上传和缓存
• 摘要计算：使用 SHA256 算法计算内容摘要
• 格式转换：Docker v2s2 与 OCI 格式的相互转换

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 端点：

资料来源：src/piloci/api/v1.py:1-100

3.4 类型定义模块

类型模块定义了系统内部使用的数据结构，确保类型安全和序列化/反序列化的一致性。

核心数据类型：

# 镜像描述符
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 等效的功能，支持脚本化和自动化场景。

piloci [全局选项] <子命令> [子命令选项]

子命令列表：

资料来源：src/piloci/cli.py:1-150

4.2 命令执行流程

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 界面。

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 镜像拉取流程

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 镜像推送流程

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 认证机制

系统支持多种认证方式：

7.2 可扩展设计

• 插件式存储后端：可通过配置切换不同的存储实现
• 中间件支持：API 层支持中间件扩展
• 配置驱动：大部分行为可通过配置文件调整

资料来源：src/piloci/utils.py:1-50

8 总结

oc-piloci 项目采用清晰的分层架构设计，实现了以下设计原则：

1. 关注点分离：各层职责明确，依赖单向流动
2. 接口抽象：通过类型定义和抽象接口实现模块解耦
3. 可测试性：核心逻辑与 I/O 操作分离，便于单元测试
4. 可扩展性：支持插件机制和多种认证方式

这套架构设计为容器镜像管理提供了稳定、高效、可维护的基础设施。

架构概览

graph TD
    subgraph "数据层"
        A[SQLite<br/>身份数据] --> B[ORM层<br/>SQLAlchemy]
        C[LanceDB<br/>向量存储] --> D[向量检索引擎]
        E[Redis<br/>会话状态] --> F[会话管理器]
        G[内存/LRU<br/>嵌入缓存] --> H[fastembed<br/>ONNX推理]
    end
    
    subgraph "业务层"
        I[MCP工具层] --> B
        I --> D
        I --> F
        I --> H
    end
    
    J[API路由层] --> I

存储组件矩阵

身份数据层

数据模型

身份数据层基于 SQLite 数据库，使用 SQLAlchemy ORM 进行所有数据库操作。严禁使用原始 SQL 语句，所有查询必须通过 ORM API 完成。资料来源：CLAUDE.md:28

#### 核心实体关系

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 实现高效的临时状态存储。会话数据支持以下生命周期管理：

stateDiagram-v2
    [*] --> 活跃: 用户登录
    活跃 --> 活跃: 继续操作
    活跃 --> 暂停: 超时/断开
    暂停 --> 活跃: 恢复会话
    暂停 --> 终止: 过期
    终止 --> [*]: 清理数据

向量存储层

LanceDB 向量引擎

向量存储采用 LanceDB 作为核心引擎，该引擎基于列式存储格式，专为向量相似度搜索优化。资料来源：README.md:1

#### 架构特点

• 列式存储：使用 Apache Arrow 格式，支持列式查询优化
• 版本化支持：内置数据版本管理能力
• 过滤查询：支持带条件的向量检索

#### 核心操作

向量处理流程

graph LR
    A[文本输入] --> B[fastembed<br/>ONNX推理]
    B --> C[嵌入向量]
    C --> D[向量归一化]
    D --> E[LanceDB<br/>upsert]
    
    F[查询请求] --> G[fastembed<br/>ONNX推理]
    G --> H[归一化向量]
    H --> I[LanceDB<br/>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

#### 缓存策略

graph TD
    A[嵌入请求] --> B{缓存命中?}
    B -->|是| C[直接返回]
    B -->|否| D[计算向量]
    D --> E{结果有效?}
    E -->|是| F[存入缓存]
    E -->|否| G[返回空/错误]
    F --> H[返回向量]
    C --> H

配置与环境变量

存储相关配置

BASE_URL 重要性

在反向代理场景下部署时，必须在 .env 文件中显式设置 BASE_URL 为外部 HTTPS 域名。资料来源：README.ko.md:1

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}

发布前检查清单

故障排查

常见存储问题

安全检查

• 确认所有数据库操作使用 SQLAlchemy ORM
• 确认密码使用 argon2id 哈希
• 确认 JWT/Session 密钥来自环境变量而非代码硬编码

概述

oc-piloci 的认证与授权系统是一个模块化、多层级的安全框架，提供了完整的身份验证和访问控制能力。该系统支持多种认证方式，包括传统的用户名密码认证、OAuth第三方登录、TOTP动态口令以及设备配对认证。所有认证模块遵循统一的安全标准，采用JWT（JSON Web Token）作为令牌机制，确保跨服务的身份状态同步。

该系统设计目标是提供企业级的安全性，同时保持良好的用户体验和开发便利性。通过中间件模式与FastAPI框架深度集成，认证逻辑对业务代码保持透明，开发者可以专注于业务逻辑实现。

系统架构

整体架构图

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

模块组件说明

JWT令牌机制

核心功能

JWT令牌是整个认证系统的核心，所有认证方式最终都通过生成JWT令牌来完成用户身份确认。jwt_utils.py模块提供了完整的JWT操作能力，包括令牌生成、签名验证、载荷提取和令牌刷新等功能。

令牌采用HS256算法进行签名，确保令牌内容不可篡改。令牌中包含标准声明如签发时间、过期时间，同时也支持自定义声明以满足业务需求。

令牌结构

graph LR
    A[JWT Header] --> C[完整令牌]
    B[JWT Payload] --> C
    C --> D[Base64编码]
    D --> E[签名验证]
    
    F[标准声明] --> B
    G[自定义声明] --> B

关键参数配置

资料来源：src/piloci/auth/jwt_utils.py:1-50

密码认证

密码安全策略

password.py模块实现了符合现代安全标准的密码处理机制。密码采用bcrypt算法进行哈希存储，确保即使数据库泄露也无法还原原始密码。系统支持密码强度验证，可配置最小长度、复杂度要求等规则。

密码校验过程采用恒定时间比较算法，防止时序攻击。模块还提供了密码生成工具，可用于管理员重置密码或用户忘记密码场景。

认证流程

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

安全特性

资料来源：src/piloci/auth/password.py:1-80

OAuth第三方登录

支持的OAuth提供商

oauth.py模块提供了OAuth 2.0协议的实现，支持与主流第三方平台的集成。该模块遵循标准OAuth流程，通过授权码模式完成身份验证，确保令牌交换过程的安全性。

每个OAuth提供商都有独立的配置项，包括客户端ID、客户端密钥和回调地址。模块采用了统一抽象层设计，便于添加新的OAuth提供商而无需修改核心逻辑。

OAuth流程

graph TD
    A[用户发起OAuth登录] --> B[跳转到提供商授权页面]
    B --> C[用户授权]
    C --> D[回调到应用并获取授权码]
    D --> E[用授权码换取访问令牌]
    E --> F[获取用户信息]
    F --> G[在本地创建或更新用户]
    G --> H[生成JWT令牌]
    H --> I[完成登录]

提供商配置

资料来源：src/piloci/auth/oauth.py:1-120

TOTP动态口令

双因素认证

totp.py模块实现了基于时间的一次性密码算法（TOTP），符合RFC 6238标准。用户启用双因素认证后，登录时除了需要密码验证，还需要输入由认证器应用生成的动态验证码。

TOTP验证码基于当前时间戳和共享密钥生成，有效期为30秒。用户首次启用时，系统会生成一个Base32编码的密钥，并以二维码形式提供给用户扫描。

TOTP验证流程

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: 认证成功

配置参数

资料来源：src/piloci/auth/totp.py:1-100

设备配对

配对机制

device_pairing.py模块提供了一种便捷的设备认证方式，允许用户通过简化的配对流程将新设备添加到受信任列表。该功能适用于需要在多个设备间共享认证状态的场景，如桌面客户端和移动应用。

配对过程采用一次性配对码机制，用户在一个已认证的设备上生成配对码，然后在目标设备上输入该码完成配对。配对码具有时效性，通常在几分钟内过期，且只能使用一次。

设备配对状态图

stateDiagram-v2
    [*] --> 未配对: 新设备
    未配对 --> 等待配对: 请求配对码
    等待配对 --> 配对中: 输入配对码
    配对中 --> 已配对: 验证成功
    配对中 --> 等待配对: 验证失败/超时
    已配对 --> 已配对: 使用设备
    已配对 --> 取消配对: 用户主动解绑
    已配对 --> [*]: 管理员移除
    取消配对 --> 未配对: 解绑完成
    等待配对 --> 等待配对: 超时重新生成

配对码格式

设备注册信息

资料来源：src/piloci/auth/device_pairing.py:1-90

认证中间件

中间件职责

middleware.py模块是整个认证系统的入口点，以FastAPI依赖注入中间件的形式实现。每个需要认证的API端点通过依赖声明自动触发中间件验证，无需在业务逻辑中重复编写认证代码。

中间件从请求头中提取JWT令牌，验证令牌有效性后解析用户信息，并将用户上下文注入到请求状态中。业务处理函数可以直接从请求状态获取当前用户信息。

请求处理流程

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[放行到业务处理]

认证配置选项

错误响应

资料来源：src/piloci/auth/middleware.py:1-150

安全最佳实践

令牌管理

生产环境中应使用足够长度的随机密钥，建议至少32字节。JWT令牌应设置合理的过期时间，访问令牌建议30分钟以内，刷新令牌建议不超过7天。对于高安全要求的场景，应启用令牌吊销机制。

密码安全

用户密码必须使用强哈希算法存储，避免使用MD5或SHA1等不安全算法。建议启用密码强度策略，要求包含大小写字母、数字和特殊字符。密码重置链接应设置短有效期，且在首次使用后立即失效。

OAuth安全

OAuth回调地址必须与预配置的地址精确匹配，防止重定向攻击。授权码应具有短有效期，建议不超过10分钟。生产环境应验证HTTPS连接，确保令牌传输安全。

TOTP安全

TOTP密钥必须安全存储，建议使用加密的密钥存储服务。备用恢复码应离线保存，用于用户丢失手机时恢复账号访问权限。

总结

oc-piloci的认证与授权系统通过模块化设计提供了灵活且安全的身份验证能力。JWT令牌作为核心机制连接各认证模块，支持密码、OAuth、TOTP和设备配对等多种认证方式。中间件模式确保认证逻辑与业务逻辑分离，便于维护和扩展。开发者可根据实际需求选择启用相应的认证模块，构建符合安全要求的应用系统。

概述

piLoci 的 MCP (Model Context Protocol) 服务器模块是系统与 AI 客户端之间的核心桥梁，负责暴露记忆管理工具、处理会话状态追踪，并提供标准化的 HTTP 流式通信接口。该模块使 Claude Code、OpenCode、Cursor 等 AI 工具能够直接调用 piLoci 的记忆存储与检索能力。资料来源：README.md

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/ 目录下：

通信协议

MCP 服务器采用 HTTP + SSE (Server-Sent Events) 的流式传输模式，支持实时双向通信。资料来源：src/piloci/mcp/streamable_http.py

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

# 工具注册示例结构
server.add_tool(
    name="memory",
    description="保存会话片段到记忆库",
    input_schema=MemoryInputSchema,
    handler=memory_handler
)

会话状态管理

session_state.py 维护每个客户端会话的上下文信息，包括：

会话状态数据存储于 Redis 中，支持快速读写与过期管理。资料来源：src/piloci/mcp/session_state.py

HTTP 流式传输层

streamable_http.py 实现了 MCP 协议的 HTTP 传输规范，支持：

• JSON-RPC 2.0 请求格式
• SSE 流式响应 实时推送
• 分块传输编码 大型响应处理
• 连接保活 长连接管理

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

# 工具参数模式示例
MemoryToolSchema = {
    "type": "object",
    "properties": {
        "content": {"type": "string", "description": "记忆内容"},
        "project_id": {"type": "string", "description": "所属项目 ID"},
        "tags": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["content"]
}

记忆工具详解

资料来源：src/piloci/tools/memory_tools.py

async def memory_tool(args: dict, ctx: SessionContext) -> ToolResult:
    """
    保存新的记忆条目
    
    Args:
        args: 包含 content, project_id, tags 的字典
        ctx: 当前会话上下文
    
    Returns:
        包含新创建记忆 ID 的结果对象
    """

工具执行流程

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 服务器配置格式

{
  "mcpServers": {
    "piloci": {
      "url": "http://localhost:8314/mcp",
      "headers": {
        "Authorization": "Bearer {token}"
      }
    }
  }
}

多客户端支持

安全机制

认证流程

所有 MCP 工具调用必须携带有效的 Bearer Token：

graph LR
    A[客户端请求] --> B{Token 验证}
    B -->|无效| C[401 Unauthorized]
    B -->|有效| D[请求处理]
    D --> E[速率限制检查]
    E -->|超限| F[429 Too Many Requests]
    E -->|正常| G[执行业务逻辑]

权限控制

• 用户级权限：验证用户身份与项目关联
• 项目级隔离：记忆数据按项目隔离，不可跨项目访问
• 工具级权限：部分工具需要管理员权限

配置选项

环境变量配置

运行时配置

# MCP 服务器初始化参数
MCPConfig(
    host="127.0.0.1",
    port=8314,
    auth_required=True,
    tools=[
        "memory",
        "recall", 
        "recommend"
    ],
    rate_limit=60,
    timeout=30
)

部署指南

独立部署

# 启动 MCP 服务器
piloci mcp serve --host 0.0.0.0 --port 8314

Docker 部署

MCP 服务器随主应用一同部署在 Docker 容器中，通过 docker-compose.yml 统一管理网络与端口映射。资料来源：README.md

services:
  piloci:
    ports:
      - "8314:8314"  # MCP + Web UI

故障排查

常见问题

调试模式

启用调试日志：

export PILOCI_LOG_LEVEL=DEBUG
piloci mcp serve

相关文档

• 安装指南 - MCP 客户端配置详解
• API 参考 - MCP 工具完整 API 文档
• 安全架构 - 认证与授权机制

概述

策展人管道（Curation Pipeline）是 piLoci 系统中负责将原始会话数据转化为结构化记忆的核心处理引擎。它位于会话采集与知识存储之间，承担着提取（Extraction）、蒸馏（Distillation）、嵌入（Embedding）和存储（Storage）四个关键阶段。

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 存储]

核心架构组件

组件职责表

策展人调度器（Scheduler）

调度器是策展人管道的入口点，负责：

1. 轮询待处理会话：从数据库获取 state='pending' 的原始会话
2. 环境适配检测：检查 LOW_SPEC_MODE 配置，低配模式下延迟处理
3. 触发蒸馏流程：将待处理任务分配给蒸馏工作器

# 资料来源：src/piloci/curator/scheduler.py
class CurationScheduler:
    def poll_pending_sessions(self):
        """获取所有待处理的原始会话"""
        
    def should_process(self, session) -> bool:
        """根据环境状态判断是否应该处理"""

蒸馏工作器（Distillation Worker）

蒸馏工作器是管道核心，负责协调整个记忆提取流程：

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[存储记忆]

关键控制参数：

# 资料来源：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）

提取模块职责

提取模块负责将非结构化的会话文本转化为结构化记忆：

# 资料来源：src/piloci/curator/extraction.py
async def extract_memories(session_transcript: str) -> List[Memory]:
    """从会话记录中提取结构化记忆"""

Gemma 本地模型集成

Gemma 模块提供本地推理能力，避免依赖外部服务：

# 资料来源：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 配置选项：

LLM 统一接口

# 资料来源：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 调用的成本可控：

graph TD
    A[外部 LLM 请求] --> B[预算检查]
    B --> C{月度已用}
    C -->|超出限额| D[拒绝请求]
    C -->|在限额内| E[执行调用]
    E --> F[记录消费]
    F --> G[更新统计]

# 资料来源：src/piloci/curator/budget.py
class BudgetController:
    async def check_and_record(self, cost_usd: float) -> bool:
        """检查预算并记录消费，返回是否允许调用"""
        
    def get_remaining_budget(self) -> float:
        """获取剩余预算"""

记忆状态机

会话记忆的处理遵循严格的状态转换：

stateDiagram-v2
    [*] --> pending: 会话采集
    pending --> processing: 调度器选中
    processing --> completed: 提取成功
    processing --> failed: 提取失败
    processing --> pending: 资源不足
    completed --> [*]
    failed --> pending: 重试

配置与调优

环境变量配置

# 低配环境模式（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

存储后端

数据流示意

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 环境中使用：

状态转换规则

• 禁止绕过 RawSession.distillation_state 进行状态修改
• 所有状态转换必须通过工作器或 ingest 处理器
• 新增 LLM 调用路径时必须使用 chat_json + record_target

概述

piLoci 的记忆工具与召回机制是系统的核心功能模块，旨在为 AI 助手（Claude Code、OpenCode 等）提供持久化上下文记忆能力。该机制允许 AI 在会话之间自动保存关键信息，并通过向量检索实现精准召回，无需用户手动管理笔记。

核心设计目标

• 自动采集：通过 MCP 协议自动捕获会话中的重要上下文
• 智能检索：基于向量嵌入的语义搜索，实现跨会话记忆召回
• 项目隔离：支持多项目独立记忆空间，确保数据隔离
• 隐私优先：所有嵌入计算在本地（Pi 5）执行，敏感数据不出设备

资料来源：CLAUDE.md

概述

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 风格格式：

资料来源：README.ko.md - Obsidian 내보내기

资料来源：MEMORY.md - Obsidian-style workspace generation

技术架构

组件关系

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]

数据流

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 端点

工作区数据获取

# 获取项目工作区（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

# 导出为 Obsidian zip 包
GET /api/vault/{slug}/export

# 前端调用示例（来自 web/lib/api.ts）
projectWorkspace: (slug: string) =>
  request<import("./types").ProjectWorkspace>(`/api/projects/slug/${slug}/workspace`),

资料来源：README.md - Obsidian-style zip

前端 API 封装

// web/lib/api.ts 中的相关端点
export const api = {
  // 项目工作区
  projectWorkspace: (slug: string) =>
    request<ProjectWorkspace>(`/api/projects/slug/${slug}/workspace`),
  
  // 项目记忆
  projectKnacks: (slug: string) =>
    request<ProjectKnacksResponse>(`/api/projects/slug/${slug}/knacks`),
};

资料来源：web/lib/api.ts - Projects API

使用场景

场景 A — 团队项目记忆中心

小团队在共享的树莓派 5 上部署 piLoci，每个成员创建账户并加入共享项目。通过 MCP 工具存储记忆，所有成员共享同一知识库，同时项目隔离机制确保工作互不干扰。

场景 B — 多项目工作空间

独立开发者或研究者在一个 piLoci 实例上运营多个项目（如"论文研究"、"个人项目"、"客户工作"）。每个项目的记忆相互隔离，工作区浏览器可按项目查看笔记和关系图。

场景 C — Obsidian 导出

生成工作区笔记并通过简单文件写入导出到 Obsidian 保管库——适用于希望在 piLoci 收集知识后在 Obsidian 中进行整理的团队。

# 直接获取工作区数据
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 保管库打开，或同步到现有保管库

核心实现代码位置

资料来源：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 域名：

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 - 리버스 프록시 / 터널

未来规划

资料来源：README.md - 笔记中描述的完整双向同步计划

资料来源：MEMORY.md - 笔记中描述的完整双向同步计划

技术栈

piLoci 的 Obsidian 集成依赖以下底层技术：

资料来源：README.md - Tech stack

资料来源：CLAUDE.md - Local-first deployment model

快速开始

1. 获取工作区数据

curl -sS http://localhost:8314/api/projects/slug/my-project/workspace | jq .

2. 导出为 Obsidian zip

curl -OJ http://localhost:8314/api/vault/my-project/export

3. 解压到 Obsidian 保管库

unzip my-project-export.zip -d ~/Obsidian/my-project-vault

4. 在 Obsidian 中打开

在 Obsidian 中选择"打开保管库"，指向解压后的目录即可。

概述

piLoci 的摄入架构包含三个核心组件：

资料来源：README.md

转录本摄入 CLI

核心命令

piloci-ingest 是 piLoci 提供的命令行工具，用于将捕获的客户端转录本发送到服务器摄入队列：

piloci-ingest --client opencode --dry-run
piloci-ingest --client codex --history-file ~/.codex/history.json

参数说明

资料来源：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

插件目录布局

完整的 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

钩子类型

插件清单配置

插件清单 (plugin.json) 包含以下元数据：

{
  "name": "piloci",
  "version": "<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

Python Client SDK

客户端功能

Python 客户端 (piloci_client) 提供 MCP 工具接口，用于与 piLoci 服务器通信：

• 记忆管理：创建、查询、删除记忆
• 项目操作：项目管理、成员邀请
• 会话查询：查看历史会话和处理状态

MCP 工具

客户端注册以下 MCP 工具：

资料来源：src/piloci/installer.py

数据导出与迁移

Vault 导出 API

piLoci 提供数据导出端点，支持将工作区笔记导出为独立文件：

curl -OJ http://localhost:8314/api/vault/my-project/export

Obsidian 集成

导出工作区笔记的 API：

curl -sS http://localhost:8314/api/projects/slug/my-project/workspace

导出流程：

1. 调用 API 获取项目工作区数据
2. 将 workspace.notes[].markdown 写入对应路径
3. 用该目录作为 Obsidian 保管库打开

资料来源：README.md

使用场景

认证与配置

配置文件

~/.config/piloci/config.json 包含：

Claude 配置

Claude Code 的 MCP 服务器配置位于 ~/.claude.json：

{
  "mcpServers": {
    "piloci": {
      "command": "piloci-mcp",
      "args": []
    }
  }
}

Claude 专用设置文件 ~/.claude/settings.json 包含自动捕获钩子配置。

资料来源：README.md

性能基线工具

profile-baseline CLI

piLoci 提供性能采样工具，用于基线测试：

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

参数说明

配置优先级：CLI 参数 > 环境变量 > 默认值

资料来源：README.md

工作流程图

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 工具仍可使用

Pitfall Log / 踩坑日志

项目：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