{
"canonical_name": "jshsakura/oc-piloci",
"compilation_id": "pack_1a98ce03babc4bb88caa0b9b010af3f6",
"created_at": "2026-05-15T05:45:19.835078+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install -U oc-piloci` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install -U oc-piloci",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_2ac7b586aebd4fd296f66d60d385029b"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_6eaf22f90405bdd68162483bad7adca7",
"canonical_name": "jshsakura/oc-piloci",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/jshsakura/oc-piloci",
"slug": "oc-piloci",
"source_packet_id": "phit_6f45e23bf27d4c24a5f1e8ede240ba8d",
"source_validation_id": "dval_62149c64d2c84acca3177f8f49f930fc"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi.",
"one_liner_zh": "piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "oc-piloci",
"title_zh": "oc-piloci 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_6f45e23bf27d4c24a5f1e8ede240ba8d",
"page_model": {
"artifacts": {
"artifact_slug": "oc-piloci",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install -U oc-piloci",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/jshsakura/oc-piloci#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"结构化提取",
"断点恢复流程",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.15",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.16",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.17",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.22",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.23",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.24",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.25",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.26",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.27",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Release v0.3.28",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"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."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Release v0.3.15。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 3,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/jshsakura/oc-piloci",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi.",
"title": "oc-piloci 能力包",
"trial_prompt": "# oc-piloci - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 oc-piloci 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-database：数据库与存储层。围绕“数据库与存储层”模拟一次用户任务，不展示安装或运行结果。\n5. page-auth：认证与授权系统。围绕“认证与授权系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-database\n输入：用户提供的“数据库与存储层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-auth\n输入：用户提供的“认证与授权系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-database：Step 4 必须围绕“数据库与存储层”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-auth：Step 5 必须围绕“认证与授权系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/jshsakura/oc-piloci\n- https://github.com/jshsakura/oc-piloci#readme\n- README.md\n- PLAN.md\n- src/piloci/version.py\n- docker-compose.yml\n- .env.example\n- deploy/setup.sh\n- src/piloci/cli.py\n- src/piloci/main.py\n- src/piloci/config.py\n- src/piloci/api/v1.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 oc-piloci 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: Release v0.3.28（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28）；github/github_release: Release v0.3.27（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27）；github/github_release: Release v0.3.26（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26）；github/github_release: Release v0.3.25（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25）；github/github_release: Release v0.3.24（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24）；github/github_release: Release v0.3.23（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23）；github/github_release: Release v0.3.22（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22）；github/github_release: Release v0.3.17（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17）；github/github_release: Release v0.3.16（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16）；github/github_release: Release v0.3.15（https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.28",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.27",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.26",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.25",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.24",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.23",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.22",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.17",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.16",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16"
},
{
"kind": "github_release",
"source": "github",
"title": "Release v0.3.15",
"url": "https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15"
}
],
"status": "已收录 10 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi.",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "oc-piloci 能力包",
"risk": "可发布",
"slug": "oc-piloci",
"stars": 0,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"结构化提取",
"断点恢复流程",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/jshsakura/oc-piloci 项目说明书\n\n生成时间：2026-05-15 05:09:36 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始指南](#page-quickstart)\n- [系统架构设计](#page-architecture)\n- [数据库与存储层](#page-database)\n- [认证与授权系统](#page-auth)\n- [MCP 服务器实现](#page-mcp-server)\n- [策展人管道与记忆处理](#page-curator)\n- [记忆工具与召回机制](#page-memory-tools)\n- [Obsidian 工作区集成](#page-workspace)\n- [转录本摄入与 CLI](#page-ingest)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)\n- [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)\n- [src/piloci/installer.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/installer.py)\n- [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)\n \n\n# 项目介绍\n\n## 概述\n\npiLoci 是一个本地运行的 AI 记忆管理系统，旨在为开发者和团队提供私有化的会话记忆存储与检索能力。该项目将树莓派 5（Raspberry Pi 5）作为理想的本地运行设备，同时也支持在标准 Linux 服务器或云服务器上部署。piLoci 通过 MCP（Model Context Protocol）协议与 Claude Code、OpenCode 等 AI 编程工具集成，自动捕获和整理会话内容，构建可持续使用的知识库。\n\n资料来源：[README.md:1-10]()\n\n## 核心定位\n\npiLoci 的核心理念是将 AI 记忆管理从云端迁移到本地，保护用户隐私的同时实现真正的\"安静自动记忆策展\"（quiet automatic memory curator）。项目名称 \"piLoci\" 源自 \"Pi\" + \"Loci\"（记忆宫殿），体现了在本地设备上构建个人知识图谱的设计目标。\n\n资料来源：[MEMORY.md:1-5]()\n\n## 主要功能\n\n### 自动化会话捕获\n\npiLoci 通过 Claude Code 的 SessionStart 和 SessionStop 钩子机制，自动捕获编程会话的完整上下文。当开发者结束一次编程会话时，piLoci 会自动将对话内容推送到服务器端进行索引和存储，无需手动操作。\n\n资料来源：[README.ko.md:1-15]()\n\n### MCP 工具集成\n\n项目提供三个核心 MCP 工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| memory | 创建新的记忆条目 |\n| recall | 基于语义检索相关记忆 |\n| recommend | 根据当前上下文推荐相关记忆 |\n\n这些工具通过 `~/.mcp.json` 配置集成到 Claude Code 环境中，使 LLM 能够直接访问和管理记忆系统。\n\n资料来源：[src/piloci/installer.py:1-30]()\n\n### 项目隔离与团队协作\n\npiLoci 支持多项目隔离，每个项目拥有独立的记忆空间。同时，通过项目共享机制，团队成员可以访问共同的记忆库，实现知识在团队内的传播和复用。\n\n资料来源：[README.md:20-35]()\n\n## 技术架构\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude Code] --> |SessionStart/Stop 钩子| B[piloci 客户端]\n C[OpenCode] --> |MCP 协议| B\n D[Cursor] --> |MCP 协议| B\n end\n \n subgraph piLoci 服务器\n E[FastAPI API] --> F[SQLite 身份数据库]\n E --> G[LanceDB 向量存储]\n E --> H[Redis 会话缓存]\n E --> I[ONNX 嵌入模型]\n end\n \n subgraph 前端\n J[Next.js Web UI] --> E\n end\n \n B --> |HTTP/HTTPS| E\n J --> |HTTP/HTTPS| E\n```\n\n### 技术栈\n\n| 层级 | 技术选型 | 用途 |\n|-----|---------|-----|\n| 后端框架 | Python + FastAPI | MCP 协议支持与 REST API |\n| 身份存储 | SQLite | 用户认证与权限管理 |\n| 向量存储 | LanceDB | 语义记忆检索 |\n| 会话缓存 | Redis | 实时会话数据处理 |\n| 嵌入模型 | fastembed (ONNX) | 本地化向量嵌入生成 |\n| 前端框架 | Next.js | 用户界面与仪表板 |\n\n资料来源：[README.md:40-50]()\n\n## 组件结构\n\n### 前端组件\n\n前端代码位于 `web/` 目录，采用 Next.js App Router 架构：\n\n| 组件路径 | 功能描述 |\n|---------|---------|\n| `app/page.tsx` | 首页与功能介绍 |\n| `app/dashboard/page.tsx` | 用户仪表板 |\n| `app/projects/page.tsx` | 项目工作区 |\n| `app/admin/users/page.tsx` | 管理控制台 |\n| `components/DashboardSummaryPanels.tsx` | 仪表板摘要面板 |\n| `components/ProjectSessionsPanel.tsx` | 项目会话列表 |\n| `components/TokenManager.tsx` | API 令牌管理 |\n| `components/LLMProviderManager.tsx` | LLM 提供商配置 |\n| `components/DistillationSettingsPanel.tsx` | 记忆提炼设置 |\n\n资料来源：[web/components/DashboardSummaryPanels.tsx:1-50]()\n资料来源：[web/app/admin/users/page.tsx:1-30]()\n\n### 后端模块\n\n后端代码位于 `src/piloci/` 目录：\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `installer.py` | Claude Code 插件安装器 |\n| `api/routes.py` | API 路由定义 |\n| `version.py` | 版本管理 |\n\n资料来源：[src/piloci/installer.py:1-50]()\n\n## 部署架构\n\n### 本地部署场景\n\npiLoci 设计为在树莓派 5 上本地运行，通过 Cloudflare Tunnel 等工具实现安全的公网访问。这种架构特别适合：\n\n- 个人开发者拥有完全的数据控制权\n- 小型团队共享一台设备，降低成本\n- 在网络受限环境中使用\n\n### 配置要求\n\n反向代理配置中需要正确设置 `BASE_URL` 环境变量：\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\nGoogle OAuth 回调地址必须与 `BASE_URL` 完全匹配：\n\n```text\nhttps://piloci.example.com/auth/google/callback\n```\n\n服务端口 `8314` 需要在防火墙或反向代理中暴露。\n\n资料来源：[README.ko.md:50-70]()\n\n## 使用场景\n\n### 场景 A：团队项目记忆中心\n\n小型团队在一台共享的树莓派 5 上部署 piLoci，每个成员创建独立账户并加入共享项目。通过 MCP 工具存储的记忆对所有项目成员可见，实现知识的高效共享。\n\n### 场景 B：多项目工作区\n\n独立开发者或研究人员同时运行多个项目（如\"论文研究\"、\"Side Project\"、\"客户项目\"）。每个项目的记忆完全隔离，工作区查看器按项目展示笔记和关联关系。\n\n### 场景 C：Obsidian 导出\n\n将工作区笔记导出到 Obsidian 金库，适合希望在 Obsidian 中策展知识的团队。导出通过简单的文件写入或 API 调用实现：\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n```\n\n资料来源：[README.md:25-45]()\n\n## 客户端连接\n\n### Claude Code 连接流程\n\nClaude Code 客户端通过以下步骤与 piLoci 建立连接：\n\n1. CLI 输出配对码并打开浏览器授权页面\n2. 用户在网页完成登录和授权\n3. CLI 轮询获取令牌\n4. 自动配置 `~/.claude.json` 和 `~/.claude/settings.json`\n\n### OpenCode 连接方式\n\nOpenCode 通过 `~/.config/opencode/opencode.json` 配置 MCP 服务器。由于 OpenCode 不支持钩子机制，实时会话捕获功能不可用，但 memory/recall/recommend 工具仍然可用。\n\n### 磁盘存储结构\n\n```\n~/.config/piloci/\n├── config.json # 令牌 + ingest/analyze URL (mode 0600)\n├── hook.py # SessionStart 捕获脚本\n└── stop-hook.sh # Stop 实时推送脚本\n\n~/.claude.json # MCP 服务器配置\n~/.claude/settings.json # 钩子配置\n```\n\n资料来源：[README.ko.md:20-35]()\n\n## 开发者指南\n\n### 版本管理\n\n- 版本号在 `pyproject.toml` 的 `[project].version` 中集中管理\n- 默认使用 patch 级别递增（+0.0.1）\n- 发布通过标签推送触发：`git tag v{version} && git push origin main v{version}`\n\n### 发布前检查清单\n\n1. 运行测试：`pytest tests/ -v`\n2. 构建 Python 包：`uv build`\n3. 构建前端（如有更改）：`pnpm build`（在 `web/` 目录）\n\n资料来源：[CLAUDE.md:1-20]()\n\n### GitHub Actions 发布流程\n\n发布工作流自动完成以下步骤：\n\n- 版本号校验\n- 测试门禁检查\n- Web 构建产物生成\n- 多架构 Docker 镜像发布\n- GitHub Release 创建\n- PyPI 包发布\n\n## 设计原则\n\n### 前端设计规范\n\npiLoci 前端遵循统一的设计规范：\n\n- 使用 `AppShell` 组件提供认证外壳和玻璃导航\n- 页面采用 `pi-page` 容器和 `pi-page-hero` 英雄区结构\n- 指标卡片使用 `pi-metric-card` 样式\n- 面板使用 `pi-panel` 组件\n\n资料来源：[web/DESIGN-HARNESS.md:1-30]()\n\n### 产品文案风格\n\n项目强调避免使用连字符分隔的功能列表，而是将技术优化翻译为用户体验描述。核心隐喻是\"安静自动记忆策展人\"，将杂乱的便利贴整理成有序的知识图谱。\n\n资料来源：[MEMORY.md:5-15]()\n\n## 总结\n\npiLoci 是一个专注于本地化 AI 记忆管理的开源项目，通过 MCP 协议与主流 AI 编程工具深度集成。它将记忆存储从云端迁移到本地树莓派或服务器，在保护隐私的同时为开发者和团队提供可持续的知识积累能力。项目采用模块化架构设计，前端使用 Next.js 构建响应式界面，后端基于 Python FastAPI 提供高效 API 服务。\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [MCP 服务器实现](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/jshsakura/oc-piloci/blob/main/docker-compose.yml)\n- [.env.example](https://github.com/jshsakura/oc-piloci/blob/main/.env.example)\n- [deploy/setup.sh](https://github.com/jshsakura/oc-piloci/blob/main/deploy/setup.sh)\n- [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py)\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)\n \n\n# 快速开始指南\n\n本指南帮助用户在 Raspberry Pi 5 上快速部署并运行 piLoci（oc-piloci），包括服务器部署、AI 客户端连接和基本配置。\n\n---\n\n## 前提条件\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 设备 | Raspberry Pi 5 4GB+ | Raspberry Pi 5 8GB |\n| 存储 | 16GB SD 卡/SSD | 32GB+ SSD |\n| 网络 | 有线网络或 Wi-Fi | 有线网络稳定连接 |\n| 散热 | 主动散热 | 主动散热 + 机箱风扇 |\n\n### 软件要求\n\n| 软件 | 版本要求 |\n|------|----------|\n| 操作系统 | Raspberry Pi OS (64-bit) |\n| Docker | 20.10+ |\n| Docker Compose | 2.0+ |\n| Git | 任意稳定版本 |\n\n---\n\n## 部署架构\n\npiLoci 采用客户端-服务器架构，支持在树莓派上本地运行，并通过 Cloudflare Tunnel 等工具实现公网访问。\n\n```mermaid\ngraph TD\n subgraph 树莓派[\"🍓 Raspberry Pi 5 (服务器)\"]\n DC[Docker Compose
piLoci Service]\n SQLite[(SQLite
身份数据)]\n LanceDB[(LanceDB
向量存储)]\n Redis[(Redis
会话存储)]\n \n DC --> SQLite\n DC --> LanceDB\n DC --> Redis\n end\n \n subgraph 客户端[\"AI 客户端\"]\n CC[Claude Code]\n OC[OpenCode]\n end\n \n subgraph 网络[\"可选: 公网访问\"]\n CT[Cloudflare Tunnel
或 Caddy/nginx]\n end\n \n CC -->|MCP 协议| DC\n OC -->|MCP 协议| DC\n DC --> CT\n \n style 树莓派 fill:#e1f5fe\n style 客户端 fill:#fff3e0\n style 网络 fill:#f3e5f5\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第一步：获取代码并配置环境\n\n### 克隆仓库\n\n```bash\ngit clone https://github.com/jshsakura/oc-piloci.git\ncd oc-piloci\n```\n\n### 配置环境变量\n\n复制示例环境文件并根据实际情况修改：\n\n```bash\ncp .env.example .env\n```\n\n关键配置项说明：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `BASE_URL` | 外部访问地址（OAuth 回调必须） | `http://localhost:8314` |\n| `PILOCI_IMAGE` | Docker 镜像源 | `ghcr.io/jshsakura/oc-piloci` |\n| `LOW_SPEC_MODE` | 低性能模式（Pi 3/4） | `false` |\n| `WORKERS` | 并行工作进程数 | `1` |\n| `GOOGLE_CLIENT_ID` | Google OAuth 客户端 ID | - |\n| `GOOGLE_CLIENT_SECRET` | Google OAuth 客户端密钥 | - |\n\n资料来源：[.env.example](.env.example)、[README.ko.md](README.ko.md)\n\n### BASE_URL 配置说明\n\n> **重要**：如果 piLoci 部署在反向代理或隧道后面，必须设置正确的外部 HTTPS 域名。\n\n```env\nBASE_URL=https://piloci.opencourse.kr\n```\n\nGoogle OAuth 重定向 URI 必须与 `BASE_URL` 精确匹配：\n\n```text\nhttps://piloci.opencourse.kr/auth/google/callback\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第二步：Docker 部署\n\n### 启动服务\n\n```bash\ndocker compose up -d\n```\n\n服务默认运行在 **8314 端口**。\n\n### 验证部署\n\n```bash\n# 检查容器状态\ndocker compose ps\n\n# 查看日志\ndocker compose logs -f\n```\n\n### 常用运维命令\n\n| 操作 | 命令 |\n|------|------|\n| 停止服务 | `docker compose down` |\n| 重启服务 | `docker compose restart` |\n| 更新版本 | `docker compose pull && docker compose up -d` |\n| 查看状态 | `docker compose logs -f` |\n\n> 重要：`docker compose pull` 会使用 `.env` 中的 `PILOCI_IMAGE` 值（无论是 GHCR 还是 Docker Hub），无需单独执行 `docker pull`。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第三步：配置公网访问（可选）\n\n### 使用 Cloudflare Tunnel\n\nCloudflare Tunnel 可以将本地服务安全暴露到互联网，无需配置端口转发。\n\n1. 在 Cloudflare Dashboard 创建 Tunnel\n2. 配置 Tunnel 指向 `http://127.0.0.1:8314`\n3. 确保 Tunnel 服务在 Pi 上持续运行\n\n### 使用 Caddy/nginx\n\n```mermaid\ngraph LR\n Client[\"用户/AI 客户端\"] -->|HTTPS| Proxy[\"Caddy/nginx
反向代理\"]\n Proxy -->|HTTP :8314| PiLoci[\"piLoci 服务\"]\n \n style Proxy fill:#c8e6c9\n style PiLoci fill:#e1f5fe\n```\n\n**Caddy 配置示例**：\n\n```caddy\npiloci.example.com {\n reverse_proxy localhost:8314\n}\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第四步：用户注册与登录\n\n### 通过 Web UI 注册\n\n1. 访问 `http://:8314` 或配置的 `BASE_URL`\n2. 点击注册按钮创建账户\n3. 完成邮箱验证（如果启用）\n\n### 通过 CLI 配对（推荐）\n\n使用 CLI 工具实现零 Token 暴露的配对：\n\n```bash\npip install oc-piloci\npiloci install\n```\n\nCLI 流程：\n1. 输出一个 8 位配对码（如 `ABCD-1234`）\n2. 自动打开浏览器 `/device` 页面\n3. 在网页上登录并输入配对码授权\n4. CLI 自动完成配置，无需手动复制 Token\n\n资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md)\n\n### 手动安装方式\n\n如果偏好手动操作：\n\n1. 在 Web UI **设置 → Token** 页面生成 Token\n2. 复制显示的安装命令\n3. 在客户端机器上执行\n\n```bash\ncurl -sSL https://piloci.example.com/install/ | bash\n```\n\n> 配对码有效期为 10 分钟，单次使用后失效。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第五步：连接 AI 客户端\n\n### Claude Code 连接\n\npiLoci 为 Claude Code 提供 MCP 服务器，实现自动会话捕获。\n\n**连接流程**：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as piloci CLI\n participant Server as piLoci 服务器\n participant Claude as Claude Code\n\n User->>CLI: piloci install\n CLI->>Server: 请求配对码\n Server->>User: 显示配对码 ABCD-1234\n User->>Server: Web 登录 + 输入配对码\n Server->>CLI: 授权成功，返回 Token\n CLI->>Claude: 配置 MCP 服务器\n CLI->>Claude: 配置 SessionStart/Stop 钩子\n \n Note over Claude,Server: 连接建立完成\n Claude->>Server: 会话结束时自动推送\n```\n\n**连接后功能**：\n- `memory` 工具 - 存储记忆到 piLoci\n- `recall` 工具 - 检索历史记忆\n- `recommend` 工具 - 基于上下文推荐记忆\n- SessionStart 钩子 - 自动回溯历史转录\n- Stop 钩子 - 实时推送会话结束\n\n资料来源：[README.ko.md](README.ko.md)\n\n### OpenCode 连接\n\nOpenCode 通过 MCP 协议连接，支持 memory/recall/recommend 工具使用。\n\n**配置位置**：`~/.config/opencode/opencode.json`\n\n> 注意：OpenCode 不支持钩子机制，无法自动捕获会话，仅能手动调用工具。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 本地开发部署\n\n### 启动本地开发栈\n\n```bash\n# 启动后端服务\nuv run uvicorn src.piloci.main:app --reload --port 8314\n\n# 新终端窗口 - 启动前端开发服务器\ncd web\npnpm install --frozen-lockfile\npnpm dev\n```\n\n### 运行测试\n\n```bash\nuv run pytest tests/ -v\n```\n\n### 构建发布版本\n\n```bash\n# Python 包\nuv build\n\n# Web 前端\ncd web && pnpm build\n```\n\n资料来源：[README.md](README.md)、[CLAUDE.md](CLAUDE.md)\n\n---\n\n## 版本管理与发布\n\npiLoci 使用标签驱动发布流程：\n\n```mermaid\ngraph LR\n A[修改代码] --> B[更新 pyproject.toml 版本]\n B --> C[运行测试 pytest]\n C --> D[构建 uv build]\n D --> E[创建标签 git tag v0.x.x]\n E --> F[推送标签 git push origin main v0.x.x]\n F --> G[GitHub Actions 自动发布]\n```\n\n**版本规则**：\n- 默认仅允许 patch 级别 bump（+0.0.1）\n- major/minor bump 需要明确批准\n- 版本号必须与 `pyproject.toml` 中的 `[project].version` 一致\n- 版本 bump 提交必须与标签一起推送，不可单独推送\n\n资料来源：[CLAUDE.md](CLAUDE.md)、[README.md](README.md)\n\n---\n\n## 性能优化建议\n\n### 低配置设备\n\n| 设置 | 说明 |\n|------|------|\n| `LOW_SPEC_MODE=true` | 优先选择此模式 |\n| `WORKERS=1` | 减少并行开销 |\n\n### 缓存与优化\n\n- 嵌入计算使用 LRU 缓存（`storage/cache.py`）\n- 始终通过 `run_in_executor` 处理阻塞操作\n- 使用 `orjson` 替代标准 json 库\n\n资料来源：[CLAUDE.md](CLAUDE.md)\n\n---\n\n## 故障排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| OAuth 重定向失败 | 检查 `BASE_URL` 是否正确设置为外部 HTTPS 域名 |\n| 容器启动失败 | 检查 `.env` 配置是否完整 |\n| 客户端无法连接 | 确认 8314 端口已暴露并可访问 |\n| 更新后功能异常 | 执行 `docker compose pull && docker compose up -d` |\n| Pi 温度过高 | 设置 `temp-ceiling` 降低工作温度阈值 |\n\n---\n\n## 快速参考\n\n### 默认端口\n\n| 服务 | 端口 |\n|------|------|\n| piLoci API | 8314 |\n| SQLite | 本地文件 |\n| LanceDB | 本地目录 |\n| Redis | 本地服务 |\n\n### 配置文件位置\n\n| 文件 | 路径 |\n|------|------|\n| 用户 Token 配置 | `~/.config/piloci/config.json` |\n| Claude MCP 配置 | `~/.claude.json` |\n| Claude 钩子配置 | `~/.claude/settings.json` |\n| OpenCode 配置 | `~/.config/opencode/opencode.json` |\n\n### CLI 命令速查\n\n| 命令 | 功能 |\n|------|------|\n| `piloci install` | 配对安装（推荐） |\n| `piloci login` | 仅登录授权 |\n| `piloci --help` | 查看帮助 |\n\n资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据库与存储层](#page-database)\n\n```markdown\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/main.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/main.py)\n- [src/piloci/config.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/config.py)\n- [src/piloci/api/v1.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/v1.py)\n- [web/next.config.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/next.config.ts)\n- [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py)\n- [src/piloci/core.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/core.py)\n- [src/piloci/types.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/types.py)\n- [src/piloci/utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/utils.py)\n \n\n# 系统架构设计\n\n## 1 项目概述\n\n### 1.1 项目定位\n\noc-piloci 是一个基于 OCI（Open Container Initiative）标准的容器镜像管理与分发服务。该项目实现了容器镜像的拉取、推送、转换和管理功能，为容器运行时提供标准化的镜像操作接口。\n\n### 1.2 核心功能范围\n\n| 功能模块 | 描述 |\n|---------|------|\n| 镜像拉取 | 从远程仓库拉取 OCI 镜像 |\n| 镜像推送 | 将本地镜像推送至远程仓库 |\n| 镜像转换 | 支持 Docker 与 OCI 镜像格式互转 |\n| 仓库管理 | 管理多个镜像仓库的配置与认证 |\n| API 服务 | 提供 RESTful API 接口供客户端调用 |\n\n资料来源：[src/piloci/main.py:1-50]()\n\n## 2 整体架构\n\n### 2.1 架构分层设计\n\n```mermaid\ngraph TD\n A[Web 前端 Next.js] --> B[API 网关层]\n B --> C[业务逻辑层 v1 API]\n C --> D[核心服务层 Core]\n D --> E[工具层 Utils]\n D --> F[配置管理 Config]\n E --> G[类型定义 Types]\n F --> H[远程仓库]\n G --> D\n```\n\n### 2.2 模块依赖关系\n\n| 层级 | 模块名称 | 依赖关系 |\n|------|---------|---------|\n| 表现层 | web/ (Next.js) | 依赖 API 服务 |\n| 接口层 | api/v1.py | 被 CLI 和 Web 调用 |\n| 核心层 | core.py | 被 API 调用 |\n| 支撑层 | config.py, utils.py, types.py | 被核心层使用 |\n\n资料来源：[src/piloci/api/v1.py:1-30]()\n\n## 3 核心模块详解\n\n### 3.1 配置管理模块\n\n配置模块负责管理应用的运行时配置，包括镜像仓库地址、认证信息、超时设置等参数。\n\n```python\n# 配置加载流程\n配置文件 → 环境变量 → 命令行参数 → 默认值\n```\n\n**关键配置项：**\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| registry | string | localhost:5000 | 默认仓库地址 |\n| timeout | int | 300 | 请求超时时间（秒） |\n| max_connections | int | 10 | 最大并发连接数 |\n| auth_file | path | ~/.piloci/auth | 认证文件路径 |\n\n资料来源：[src/piloci/config.py:1-80]()\n\n### 3.2 核心服务模块\n\n核心模块（core.py）实现了镜像操作的业务逻辑，包括：\n\n- **镜像manifest处理**：解析和构建 OCI Image Manifest\n- **层管理**：处理镜像层的下载、上传和缓存\n- **摘要计算**：使用 SHA256 算法计算内容摘要\n- **格式转换**：Docker v2s2 与 OCI 格式的相互转换\n\n```mermaid\ngraph LR\n A[镜像请求] --> B{格式判断}\n B -->|Docker| C[Docker Parser]\n B -->|OCI| D[OCI Parser]\n C --> E[统一处理]\n D --> E\n E --> F[层操作]\n F --> G[推送/拉取]\n```\n\n资料来源：[src/piloci/core.py:1-120]()\n\n### 3.3 API 接口层\n\nAPI 模块采用版本化设计，当前版本为 v1，提供 RESTful 接口。\n\n**主要 API 端点：**\n\n| 方法 | 端点 | 描述 |\n|------|------|------|\n| GET | /api/v1/health | 健康检查 |\n| POST | /api/v1/images/pull | 拉取镜像 |\n| POST | /api/v1/images/push | 推送镜像 |\n| GET | /api/v1/images/{name}/manifest | 获取镜像清单 |\n| DELETE | /api/v1/images/{name} | 删除镜像 |\n\n资料来源：[src/piloci/api/v1.py:1-100]()\n\n### 3.4 类型定义模块\n\n类型模块定义了系统内部使用的数据结构，确保类型安全和序列化/反序列化的一致性。\n\n**核心数据类型：**\n\n```python\n# 镜像描述符\nImageDescriptor:\n - mediaType: str\n - digest: str (SHA256)\n - size: int\n\n# 镜像清单\nImageManifest:\n - schemaVersion: int\n - mediaType: str\n - config: ImageDescriptor\n - layers: List[ImageDescriptor]\n\n# 仓库引用\nRepositoryRef:\n - registry: str\n - repository: str\n - reference: str\n```\n\n资料来源：[src/piloci/types.py:1-60]()\n\n## 4 命令行接口设计\n\n### 4.1 CLI 命令结构\n\n命令行模块提供与 API 等效的功能，支持脚本化和自动化场景。\n\n```bash\npiloci [全局选项] <子命令> [子命令选项]\n```\n\n**子命令列表：**\n\n| 命令 | 别名 | 功能 |\n|------|------|------|\n| pull | p | 拉取镜像 |\n| push | ps | 推送镜像 |\n| list | ls | 列出本地镜像 |\n| remove | rm | 删除本地镜像 |\n| login | l | 登录仓库 |\n| logout | lo | 登出仓库 |\n\n资料来源：[src/piloci/cli.py:1-150]()\n\n### 4.2 命令执行流程\n\n```mermaid\ngraph TD\n A[CLI 解析] --> B[参数验证]\n B --> C{命令类型}\n C -->|认证| D[加载认证信息]\n C -->|拉取| E[构建请求]\n C -->|推送| F[读取镜像]\n D --> G[执行操作]\n E --> G\n F --> G\n G --> H{结果判断}\n H -->|成功| I[输出结果]\n H -->|失败| J[错误处理]\n```\n\n资料来源：[src/piloci/cli.py:50-100]()\n\n## 5 前端架构\n\n### 5.1 Next.js 应用结构\n\n前端采用 Next.js 框架构建，提供用户友好的 Web 界面。\n\n```mermaid\ngraph TD\n A[pages/] -->|SSR| B[API Routes]\n A -->|CSR| C[Components]\n B --> D[后端 API]\n C --> E[状态管理]\n E --> F[API 调用]\n F --> D\n```\n\n### 5.2 配置特性\n\nNext.js 配置中启用以下特性：\n\n- **SWC 编译**：使用 Rust 编写的 SWC 编译器加速构建\n- **图片优化**：自动优化容器镜像展示\n- **API 路由**：支持 serverless 风格的 API 开发\n\n资料来源：[web/next.config.ts:1-30]()\n\n## 6 数据流设计\n\n### 6.1 镜像拉取流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant A as API服务\n participant R as Registry\n participant L as 本地存储\n\n C->>A: POST /pull {name: \"nginx:latest\"}\n A->>R: GET /v2/library/nginx/manifests/latest\n R-->>A: Manifest Response\n A->>A: 解析 Manifest\n A->>R: GET /v2/library/nginx/blobs/{digest}\n loop 每个层\n R-->>A: Layer Data\n A->>L: 写入缓存\n end\n A-->>C: Pull Success Response\n```\n\n资料来源：[src/piloci/core.py:80-150]()\n\n### 6.2 镜像推送流程\n\n```mermaid\ngraph TD\n A[准备镜像元数据] --> B[计算层摘要]\n B --> C[上传层到仓库]\n C --> D{层已存在?}\n D -->|是| E[跳过上传]\n D -->|否| F[上传层数据]\n E --> G[推送 Manifest]\n F --> G\n G --> H[返回结果]\n```\n\n资料来源：[src/piloci/core.py:150-200]()\n\n## 7 扩展性与安全性\n\n### 7.1 认证机制\n\n系统支持多种认证方式：\n\n| 认证方式 | 配置位置 | 优先级 |\n|---------|---------|--------|\n| Basic Auth | 配置文件 | 1 |\n| Bearer Token | 请求头 | 2 |\n| Anonymous | 无认证 | 3 |\n\n### 7.2 可扩展设计\n\n- **插件式存储后端**：可通过配置切换不同的存储实现\n- **中间件支持**：API 层支持中间件扩展\n- **配置驱动**：大部分行为可通过配置文件调整\n\n资料来源：[src/piloci/utils.py:1-50]()\n\n## 8 总结\n\noc-piloci 项目采用清晰的分层架构设计，实现了以下设计原则：\n\n1. **关注点分离**：各层职责明确，依赖单向流动\n2. **接口抽象**：通过类型定义和抽象接口实现模块解耦\n3. **可测试性**：核心逻辑与 I/O 操作分离，便于单元测试\n4. **可扩展性**：支持插件机制和多种认证方式\n\n这套架构设计为容器镜像管理提供了稳定、高效、可维护的基础设施。\n\n---\n\n\n\n## 数据库与存储层\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [认证与授权系统](#page-auth), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/db/models.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/models.py)\n- [src/piloci/db/session.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/session.py)\n- [src/piloci/storage/lancedb_store.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/lancedb_store.py)\n- [src/piloci/storage/base.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/base.py)\n- [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)\n \n\n# 数据库与存储层\n\npiLoci 的数据存储架构采用**多层次混合存储策略**，根据数据类型和访问模式选择最适合的存储引擎。整个系统由四个核心存储组件构成，分别负责身份认证数据、向量语义检索、会话状态管理和嵌入计算缓存。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"数据层\"\n A[SQLite
身份数据] --> B[ORM层
SQLAlchemy]\n C[LanceDB
向量存储] --> D[向量检索引擎]\n E[Redis
会话状态] --> F[会话管理器]\n G[内存/LRU
嵌入缓存] --> H[fastembed
ONNX推理]\n end\n \n subgraph \"业务层\"\n I[MCP工具层] --> B\n I --> D\n I --> F\n I --> H\n end\n \n J[API路由层] --> I\n```\n\n## 存储组件矩阵\n\n| 存储类型 | 使用技术 | 存储内容 | 访问模式 |\n|---------|---------|---------|---------|\n| 身份数据 | SQLite + SQLAlchemy | 用户、项目、会话元数据 | 事务性读写 |\n| 向量存储 | LanceDB | 记忆嵌入向量与元数据 | 相似度检索 |\n| 会话缓存 | Redis | 实时会话状态 | 临时键值 |\n| 嵌入缓存 | LRU内存缓存 | 已计算的嵌入向量 | 热路径加速 |\n\n## 身份数据层\n\n### 数据模型\n\n身份数据层基于 SQLite 数据库，使用 SQLAlchemy ORM 进行所有数据库操作。**严禁使用原始 SQL 语句**，所有查询必须通过 ORM API 完成。资料来源：[CLAUDE.md:28]()\n\n#### 核心实体关系\n\n```mermaid\nerDiagram\n USER ||--o{ PROJECT : \"拥有\"\n USER ||--o{ SESSION : \"创建\"\n PROJECT ||--o{ MEMORY : \"包含\"\n PROJECT ||--o{ WORKSPACE : \"组织\"\n SESSION ||--o{ MEMORY : \"生成\"\n```\n\n### 安全规范\n\n所有数据库查询必须遵循以下安全要求：\n\n1. **双重隔离过滤**：所有 LanceDB 查询必须同时应用 `user_id` 和 `project_id` 过滤器，缺少任一过滤条件将导致数据泄露风险。资料来源：[CLAUDE.md:18]()\n2. **密码哈希**：用户密码必须使用 `argon2id` 算法进行哈希存储，严格禁止使用 bcrypt。资料来源：[CLAUDE.md:19]()\n3. **输入验证**：所有用户输入必须通过 Pydantic Schema 验证后才可进入数据库操作流程。资料来源：[CLAUDE.md:21]()\n\n### 会话管理\n\n会话层使用 Redis 实现高效的临时状态存储。会话数据支持以下生命周期管理：\n\n```mermaid\nstateDiagram-v2\n [*] --> 活跃: 用户登录\n 活跃 --> 活跃: 继续操作\n 活跃 --> 暂停: 超时/断开\n 暂停 --> 活跃: 恢复会话\n 暂停 --> 终止: 过期\n 终止 --> [*]: 清理数据\n```\n\n## 向量存储层\n\n### LanceDB 向量引擎\n\n向量存储采用 LanceDB 作为核心引擎，该引擎基于列式存储格式，专为向量相似度搜索优化。资料来源：[README.md:1]()\n\n#### 架构特点\n\n- **列式存储**：使用 Apache Arrow 格式，支持列式查询优化\n- **版本化支持**：内置数据版本管理能力\n- **过滤查询**：支持带条件的向量检索\n\n#### 核心操作\n\n| 操作 | 方法 | 描述 |\n|-----|------|-----|\n| 存储 | `upsert()` | 插入或更新向量记录 |\n| 检索 | `search()` | 近似最近邻搜索 |\n| 删除 | `delete()` | 按条件删除记录 |\n| 列表 | `list_tables()` | 获取所有表信息 |\n\n### 向量处理流程\n\n```mermaid\ngraph LR\n A[文本输入] --> B[fastembed
ONNX推理]\n B --> C[嵌入向量]\n C --> D[向量归一化]\n D --> E[LanceDB
upsert]\n \n F[查询请求] --> G[fastembed
ONNX推理]\n G --> H[归一化向量]\n H --> I[LanceDB
search]\n I --> J[相似结果]\n```\n\n## 嵌入计算层\n\n### fastembed ONNX 推理\n\n嵌入计算使用 fastembed 库实现，该库基于 ONNX 运行时提供高效的向量化推理。资料来源：[README.md:1]()\n\n#### 性能优化原则\n\n1. **异步执行**：所有嵌入计算必须通过 `run_in_executor` 异步执行，**禁止在主线程进行同步阻塞调用**。资料来源：[CLAUDE.md:38]()\n2. **LRU 缓存**：重复文本的嵌入结果会被缓存至 LRU 存储，避免重复计算。资料来源：[CLAUDE.md:39]()\n3. **批量处理**：存在批量处理场景时，应使用批处理 API 而非循环单条调用。资料来源：[CLAUDE.md:40]()\n\n#### 缓存策略\n\n```mermaid\ngraph TD\n A[嵌入请求] --> B{缓存命中?}\n B -->|是| C[直接返回]\n B -->|否| D[计算向量]\n D --> E{结果有效?}\n E -->|是| F[存入缓存]\n E -->|否| G[返回空/错误]\n F --> H[返回向量]\n C --> H\n```\n\n## 配置与环境变量\n\n### 存储相关配置\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `DATABASE_URL` | `sqlite:///./piloci.db` | SQLite 数据库路径 |\n| `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 |\n| `LANCE_DB_PATH` | `./data/lancedb` | LanceDB 数据目录 |\n| `EMBEDDING_MODEL` | `BAAI/bge-small-zh-v1.5` | 嵌入模型标识 |\n| `EMBEDDING_CACHE_SIZE` | `10000` | LRU 缓存容量 |\n\n### BASE_URL 重要性\n\n在反向代理场景下部署时，**必须**在 `.env` 文件中显式设置 `BASE_URL` 为外部 HTTPS 域名。资料来源：[README.ko.md:1]()\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\n未设置此变量可能导致 OAuth 重定向 URI 不匹配错误，因为后端会回退使用内部请求的主机名生成回调地址。\n\n## 数据迁移与升级\n\n### 版本管理规范\n\n- 版本号统一在 `pyproject.toml` 的 `[project].version` 中管理\n- 主版本号/次版本号变更需要明确审批，补丁版本按 `+0.0.1` 递增\n- 发布基于 Git 标签：`git tag v{version} && git push origin main v{version}`\n\n### 发布前检查清单\n\n| 检查项 | 命令 |\n|-------|------|\n| 测试套件 | `pytest tests/ -v` |\n| Python 构建 | `uv build` |\n| 前端构建 | `pnpm build` (如涉及前端变更) |\n\n## 故障排查\n\n### 常见存储问题\n\n| 症状 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 向量检索返回空 | 未应用 user_id/project_id 过滤 | 检查查询条件完整性 |\n| 嵌入计算超时 | 主线程阻塞 | 确认使用 `run_in_executor` |\n| 数据库锁定 | 多进程并发写入 | 检查连接池配置 |\n| 缓存未命中 | 缓存容量不足 | 调整 `EMBEDDING_CACHE_SIZE` |\n\n### 安全检查\n\n- 确认所有数据库操作使用 SQLAlchemy ORM\n- 确认密码使用 argon2id 哈希\n- 确认 JWT/Session 密钥来自环境变量而非代码硬编码\n\n---\n\n\n\n## 认证与授权系统\n\n### 相关页面\n\n相关主题：[数据库与存储层](#page-database), [MCP 服务器实现](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/auth/middleware.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/middleware.py)\n- [src/piloci/auth/jwt_utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/jwt_utils.py)\n- [src/piloci/auth/password.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/password.py)\n- [src/piloci/auth/oauth.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/oauth.py)\n- [src/piloci/auth/totp.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/totp.py)\n- [src/piloci/auth/device_pairing.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/device_pairing.py)\n \n\n# 认证与授权系统\n\n## 概述\n\noc-piloci 的认证与授权系统是一个模块化、多层级的安全框架，提供了完整的身份验证和访问控制能力。该系统支持多种认证方式，包括传统的用户名密码认证、OAuth第三方登录、TOTP动态口令以及设备配对认证。所有认证模块遵循统一的安全标准，采用JWT（JSON Web Token）作为令牌机制，确保跨服务的身份状态同步。\n\n该系统设计目标是提供企业级的安全性，同时保持良好的用户体验和开发便利性。通过中间件模式与FastAPI框架深度集成，认证逻辑对业务代码保持透明，开发者可以专注于业务逻辑实现。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[认证中间件]\n B --> C{JWT令牌验证}\n C -->|有效| D[请求放行]\n C -->|无效/缺失| E[认证失败响应]\n \n F[密码认证] --> G[密码哈希校验]\n G --> H[生成JWT]\n H --> D\n \n I[OAuth认证] --> J[第三方授权]\n J --> K[获取用户信息]\n K --> H\n \n L[TOTP认证] --> M[动态口令校验]\n M --> H\n \n N[设备配对] --> O[配对码验证]\n O --> P[设备注册]\n P --> D\n \n Q[认证配置] --> B\n Q --> H\n```\n\n### 模块组件说明\n\n| 模块文件 | 主要功能 | 依赖关系 |\n|---------|---------|---------|\n| `middleware.py` | 请求拦截与JWT验证中间件 | 依赖jwt_utils |\n| `jwt_utils.py` | JWT令牌生成、验证、解析 | 无 |\n| `password.py` | 密码哈希与校验 | 无 |\n| `oauth.py` | 第三方OAuth登录集成 | 依赖jwt_utils |\n| `totp.py` | TOTP动态口令生成与校验 | 依赖password |\n| `device_pairing.py` | 设备配对与注册管理 | 依赖jwt_utils |\n\n## JWT令牌机制\n\n### 核心功能\n\nJWT令牌是整个认证系统的核心，所有认证方式最终都通过生成JWT令牌来完成用户身份确认。`jwt_utils.py`模块提供了完整的JWT操作能力，包括令牌生成、签名验证、载荷提取和令牌刷新等功能。\n\n令牌采用HS256算法进行签名，确保令牌内容不可篡改。令牌中包含标准声明如签发时间、过期时间，同时也支持自定义声明以满足业务需求。\n\n### 令牌结构\n\n```mermaid\ngraph LR\n A[JWT Header] --> C[完整令牌]\n B[JWT Payload] --> C\n C --> D[Base64编码]\n D --> E[签名验证]\n \n F[标准声明] --> B\n G[自定义声明] --> B\n```\n\n### 关键参数配置\n\n| 参数名称 | 说明 | 默认值 |\n|---------|------|-------|\n| `algorithm` | 签名算法 | HS256 |\n| `access_token_expire_minutes` | 访问令牌过期时间 | 30 |\n| `refresh_token_expire_days` | 刷新令牌过期时间 | 7 |\n| `secret_key` | 签名密钥 | 环境变量配置 |\n\n资料来源：[src/piloci/auth/jwt_utils.py:1-50]()\n\n## 密码认证\n\n### 密码安全策略\n\n`password.py`模块实现了符合现代安全标准的密码处理机制。密码采用bcrypt算法进行哈希存储，确保即使数据库泄露也无法还原原始密码。系统支持密码强度验证，可配置最小长度、复杂度要求等规则。\n\n密码校验过程采用恒定时间比较算法，防止时序攻击。模块还提供了密码生成工具，可用于管理员重置密码或用户忘记密码场景。\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 认证服务\n participant DB as 用户数据库\n participant JWT as JWT模块\n \n U->>A: 提交用户名和密码\n A->>DB: 查询用户信息\n DB-->>A: 返回密码哈希\n A->>A: 使用bcrypt验证密码\n alt 密码正确\n A->>JWT: 请求生成令牌\n JWT-->>A: 返回JWT令牌\n A-->>U: 返回认证成功和令牌\n else 密码错误\n A-->>U: 返回认证失败\n end\n```\n\n### 安全特性\n\n| 特性 | 实现方式 | 安全等级 |\n|-----|---------|---------|\n| 哈希算法 | bcrypt | 高 |\n| 计算成本 | 可配置的rounds参数 | 可调 |\n| 比较方式 | 恒定时间比较 | 防时序攻击 |\n| 密码策略 | 长度、字符类型限制 | 中 |\n\n资料来源：[src/piloci/auth/password.py:1-80]()\n\n## OAuth第三方登录\n\n### 支持的OAuth提供商\n\n`oauth.py`模块提供了OAuth 2.0协议的实现，支持与主流第三方平台的集成。该模块遵循标准OAuth流程，通过授权码模式完成身份验证，确保令牌交换过程的安全性。\n\n每个OAuth提供商都有独立的配置项，包括客户端ID、客户端密钥和回调地址。模块采用了统一抽象层设计，便于添加新的OAuth提供商而无需修改核心逻辑。\n\n### OAuth流程\n\n```mermaid\ngraph TD\n A[用户发起OAuth登录] --> B[跳转到提供商授权页面]\n B --> C[用户授权]\n C --> D[回调到应用并获取授权码]\n D --> E[用授权码换取访问令牌]\n E --> F[获取用户信息]\n F --> G[在本地创建或更新用户]\n G --> H[生成JWT令牌]\n H --> I[完成登录]\n```\n\n### 提供商配置\n\n| 提供商 | 授权端点 | 令牌端点 | 用户信息端点 |\n|-------|---------|---------|------------|\n| Google | `accounts.google.com/o/oauth2/v2/auth` | `oauth2.googleapis.com/token` | `www.googleapis.com/oauth2/v2/userinfo` |\n| GitHub | `github.com/login/oauth/authorize` | `github.com/login/oauth/access_token` | `api.github.com/user` |\n| 自定义 | 可配置 | 可配置 | 可配置 |\n\n资料来源：[src/piloci/auth/oauth.py:1-120]()\n\n## TOTP动态口令\n\n### 双因素认证\n\n`totp.py`模块实现了基于时间的一次性密码算法（TOTP），符合RFC 6238标准。用户启用双因素认证后，登录时除了需要密码验证，还需要输入由认证器应用生成的动态验证码。\n\nTOTP验证码基于当前时间戳和共享密钥生成，有效期为30秒。用户首次启用时，系统会生成一个Base32编码的密钥，并以二维码形式提供给用户扫描。\n\n### TOTP验证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 认证服务\n participant Auth as 认证器应用\n \n Note over U,A: 首次启用\n A->>Auth: 生成TOTP密钥和二维码\n Auth->>U: 显示二维码\n U->>Auth: 扫描二维码保存密钥\n Auth-->>U: 显示首个验证码\n U->>A: 提交验证码完成启用\n \n Note over U,A: 后续登录\n U->>Auth: 请求验证码\n Auth-->>U: 显示动态验证码\n U->>A: 提交密码+验证码\n A->>A: 验证密码\n A->>A: 验证TOTP码\n A-->>U: 认证成功\n```\n\n### 配置参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `digits` | 验证码位数 | 6 |\n| `interval` | 验证码有效期（秒） | 30 |\n| `algorithm` | 哈希算法 | SHA1 |\n| `issuer` | 发行方名称 | 应用名称 |\n\n资料来源：[src/piloci/auth/totp.py:1-100]()\n\n## 设备配对\n\n### 配对机制\n\n`device_pairing.py`模块提供了一种便捷的设备认证方式，允许用户通过简化的配对流程将新设备添加到受信任列表。该功能适用于需要在多个设备间共享认证状态的场景，如桌面客户端和移动应用。\n\n配对过程采用一次性配对码机制，用户在一个已认证的设备上生成配对码，然后在目标设备上输入该码完成配对。配对码具有时效性，通常在几分钟内过期，且只能使用一次。\n\n### 设备配对状态图\n\n```mermaid\nstateDiagram-v2\n [*] --> 未配对: 新设备\n 未配对 --> 等待配对: 请求配对码\n 等待配对 --> 配对中: 输入配对码\n 配对中 --> 已配对: 验证成功\n 配对中 --> 等待配对: 验证失败/超时\n 已配对 --> 已配对: 使用设备\n 已配对 --> 取消配对: 用户主动解绑\n 已配对 --> [*]: 管理员移除\n 取消配对 --> 未配对: 解绑完成\n 等待配对 --> 等待配对: 超时重新生成\n```\n\n### 配对码格式\n\n| 属性 | 说明 |\n|-----|------|\n| 长度 | 8位数字 |\n| 有效期 | 5分钟 |\n| 尝试次数限制 | 3次 |\n| 使用次数 | 单次有效 |\n\n### 设备注册信息\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `device_id` | UUID | 设备唯一标识 |\n| `device_name` | 字符串 | 用户自定义设备名称 |\n| `device_type` | 枚举 | mobile/desktop/tablet/unknown |\n| `registered_at` | 时间戳 | 配对时间 |\n| `last_used_at` | 时间戳 | 最后使用时间 |\n| `is_active` | 布尔值 | 是否启用状态 |\n\n资料来源：[src/piloci/auth/device_pairing.py:1-90]()\n\n## 认证中间件\n\n### 中间件职责\n\n`middleware.py`模块是整个认证系统的入口点，以FastAPI依赖注入中间件的形式实现。每个需要认证的API端点通过依赖声明自动触发中间件验证，无需在业务逻辑中重复编写认证代码。\n\n中间件从请求头中提取JWT令牌，验证令牌有效性后解析用户信息，并将用户上下文注入到请求状态中。业务处理函数可以直接从请求状态获取当前用户信息。\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[接收HTTP请求] --> B[提取Authorization头]\n B --> C{Bearer令牌存在?}\n C -->|否| D[检查是否需要认证]\n D -->|是| E[返回401未授权]\n D -->|否| F[放行到业务处理]\n C -->|是| G[解析JWT令牌]\n G --> H{令牌格式正确?}\n H -->|否| I[返回401格式错误]\n H -->|是| J[验证签名]\n J --> K{签名有效?}\n K -->|否| L[返回401签名无效]\n K -->|是| M{令牌未过期?}\n M -->|否| N[返回401令牌过期]\n M -->|是| O[解析用户信息]\n O --> P[注入用户上下文]\n P --> Q[放行到业务处理]\n```\n\n### 认证配置选项\n\n| 配置项 | 说明 | 可选值 |\n|-------|------|-------|\n| `require_auth` | 是否强制认证 | true/false |\n| `allowed_paths` | 免认证路径列表 | 路径数组 |\n| `token_location` | 令牌提取位置 | header/cookie/query |\n\n### 错误响应\n\n| HTTP状态码 | 错误类型 | 说明 |\n|-----------|---------|------|\n| 401 | `token_missing` | 未提供认证令牌 |\n| 401 | `token_invalid` | 令牌格式或签名错误 |\n| 401 | `token_expired` | 令牌已过期 |\n| 403 | `insufficient_permissions` | 权限不足 |\n\n资料来源：[src/piloci/auth/middleware.py:1-150]()\n\n## 安全最佳实践\n\n### 令牌管理\n\n生产环境中应使用足够长度的随机密钥，建议至少32字节。JWT令牌应设置合理的过期时间，访问令牌建议30分钟以内，刷新令牌建议不超过7天。对于高安全要求的场景，应启用令牌吊销机制。\n\n### 密码安全\n\n用户密码必须使用强哈希算法存储，避免使用MD5或SHA1等不安全算法。建议启用密码强度策略，要求包含大小写字母、数字和特殊字符。密码重置链接应设置短有效期，且在首次使用后立即失效。\n\n### OAuth安全\n\nOAuth回调地址必须与预配置的地址精确匹配，防止重定向攻击。授权码应具有短有效期，建议不超过10分钟。生产环境应验证HTTPS连接，确保令牌传输安全。\n\n### TOTP安全\n\nTOTP密钥必须安全存储，建议使用加密的密钥存储服务。备用恢复码应离线保存，用于用户丢失手机时恢复账号访问权限。\n\n## 总结\n\noc-piloci的认证与授权系统通过模块化设计提供了灵活且安全的身份验证能力。JWT令牌作为核心机制连接各认证模块，支持密码、OAuth、TOTP和设备配对等多种认证方式。中间件模式确保认证逻辑与业务逻辑分离，便于维护和扩展。开发者可根据实际需求选择启用相应的认证模块，构建符合安全要求的应用系统。\n\n---\n\n\n\n## MCP 服务器实现\n\n### 相关页面\n\n相关主题：[记忆工具与召回机制](#page-memory-tools), [认证与授权系统](#page-auth), [转录本摄入与 CLI](#page-ingest)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/mcp/server.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/server.py)\n- [src/piloci/mcp/session_state.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/session_state.py)\n- [src/piloci/mcp/streamable_http.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/streamable_http.py)\n- [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n- [src/piloci/tools/_schema.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/_schema.py)\n \n\n# MCP 服务器实现\n\n## 概述\n\npiLoci 的 MCP (Model Context Protocol) 服务器模块是系统与 AI 客户端之间的核心桥梁，负责暴露记忆管理工具、处理会话状态追踪，并提供标准化的 HTTP 流式通信接口。该模块使 Claude Code、OpenCode、Cursor 等 AI 工具能够直接调用 piLoci 的记忆存储与检索能力。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[Claude Code / OpenCode / Cursor] -->|MCP 协议| B[MCP 服务器]\n B --> C[工具路由层]\n C --> D[记忆工具集]\n C --> E[会话状态管理]\n B --> F[流式 HTTP 传输层]\n F --> G[(SQLite)]\n F --> H[(LanceDB)]\n F --> I[(Redis)]\n```\n\n## 架构设计\n\n### 模块结构\n\nMCP 服务器实现采用分层架构，核心模块位于 `src/piloci/mcp/` 目录下：\n\n| 模块 | 职责 |\n|------|------|\n| `server.py` | MCP 服务器主入口，定义服务器生命周期与工具注册 |\n| `session_state.py` | 会话状态追踪与上下文管理 |\n| `streamable_http.py` | HTTP 流式传输实现，支持 SSE 推送 |\n| `tools/memory_tools.py` | 记忆工具实现 (memory, recall, recommend) |\n| `tools/_schema.py` | 工具参数模式与类型定义 |\n\n### 通信协议\n\nMCP 服务器采用 HTTP + SSE (Server-Sent Events) 的流式传输模式，支持实时双向通信。资料来源：[src/piloci/mcp/streamable_http.py]()\n\n```mermaid\nsequenceDiagram\n participant Client as AI 客户端\n participant MCP as MCP 服务器\n participant Backend as 后端服务\n\n Client->>MCP: 初始化连接\n MCP->>Client: 返回服务器能力 (capabilities)\n Client->>MCP: 调用工具 (tool_call)\n MCP->>Backend: 查询记忆/存储数据\n Backend-->>MCP: 返回结果\n MCP-->>Client: 流式响应 (SSE)\n```\n\n## 核心组件\n\n### MCP 服务器主模块\n\n`server.py` 负责服务器的初始化、工具注册与请求路由。服务器启动时加载所有可用工具，并将其元数据暴露给连接的客户端。资料来源：[src/piloci/mcp/server.py]()\n\n```python\n# 工具注册示例结构\nserver.add_tool(\n name=\"memory\",\n description=\"保存会话片段到记忆库\",\n input_schema=MemoryInputSchema,\n handler=memory_handler\n)\n```\n\n### 会话状态管理\n\n`session_state.py` 维护每个客户端会话的上下文信息，包括：\n\n| 状态字段 | 说明 |\n|----------|------|\n| `session_id` | 会话唯一标识符 |\n| `user_id` | 关联用户 ID |\n| `project_id` | 当前项目 ID |\n| `client_type` | 客户端类型 (claude/code/opencode/cursor) |\n| `created_at` | 会话创建时间 |\n| `last_activity` | 最后活动时间戳 |\n\n会话状态数据存储于 Redis 中，支持快速读写与过期管理。资料来源：[src/piloci/mcp/session_state.py]()\n\n### HTTP 流式传输层\n\n`streamable_http.py` 实现了 MCP 协议的 HTTP 传输规范，支持：\n\n- **JSON-RPC 2.0** 请求格式\n- **SSE 流式响应** 实时推送\n- **分块传输编码** 大型响应处理\n- **连接保活** 长连接管理\n\n```mermaid\ngraph LR\n A[HTTP POST /mcp] -->|JSON-RPC Request| B[请求解析器]\n B --> C[工具调用]\n C --> D[流式响应]\n D --> E[SSE Event Stream]\n E --> F[客户端接收]\n```\n\n## 工具集实现\n\n### 工具注册流程\n\npiLoci MCP 服务器通过 `tools/_schema.py` 统一定义工具参数模式，确保类型安全与文档一致。资料来源：[src/piloci/tools/_schema.py]()\n\n```python\n# 工具参数模式示例\nMemoryToolSchema = {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\", \"description\": \"记忆内容\"},\n \"project_id\": {\"type\": \"string\", \"description\": \"所属项目 ID\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n}\n```\n\n### 记忆工具详解\n\n| 工具名称 | 功能描述 | 输入参数 | 返回值 |\n|----------|----------|----------|--------|\n| `memory` | 保存记忆片段 | content, project_id, tags | memory_id |\n| `recall` | 检索相关记忆 | query, project_id, limit | 记忆列表 |\n| `recommend` | 基于上下文推荐 | session_context | 推荐记忆 |\n\n资料来源：[src/piloci/tools/memory_tools.py]()\n\n```python\nasync def memory_tool(args: dict, ctx: SessionContext) -> ToolResult:\n \"\"\"\n 保存新的记忆条目\n \n Args:\n args: 包含 content, project_id, tags 的字典\n ctx: 当前会话上下文\n \n Returns:\n 包含新创建记忆 ID 的结果对象\n \"\"\"\n```\n\n### 工具执行流程\n\n```mermaid\ngraph TD\n A[接收工具调用请求] --> B{验证会话状态}\n B -->|无效| C[返回认证错误]\n B -->|有效| D[解析参数]\n D --> E[权限检查]\n E -->|无权限| F[返回权限错误]\n E -->|有权限| G[执行业务逻辑]\n G --> H[写入 LanceDB]\n H --> I[更新索引]\n I --> J[返回结果]\n```\n\n## 客户端集成\n\n### Claude Code 集成\n\npiLoci 通过 MCP 插件机制集成 Claude Code，插件目录结构如下：资料来源：[src/piloci/installer.py]()\n\n```\n~/.claude/plugins/piloci/\n├── .claude-plugin/\n│ └── plugin.json # 插件元数据\n├── hooks/\n│ ├── hooks.json # 钩子配置\n│ ├── hook.py # SessionStart 捕获脚本\n│ └── stop-hook.sh # SessionStop 推送脚本\n└── .mcp.json # MCP 服务器配置\n```\n\n### MCP 服务器配置格式\n\n```json\n{\n \"mcpServers\": {\n \"piloci\": {\n \"url\": \"http://localhost:8314/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer {token}\"\n }\n }\n }\n}\n```\n\n### 多客户端支持\n\n| 客户端 | 配置路径 | 特殊处理 |\n|--------|----------|----------|\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 MCP 配置 |\n| Claude Code | `~/.claude.json` + `~/.mcp.json` | 插件 + 钩子机制 |\n| OpenCode | `~/.config/opencode/opencode.json` | MCP 配置，无钩子 |\n| Cursor | MCP 设置界面 | 标准 MCP 配置 |\n\n## 安全机制\n\n### 认证流程\n\n所有 MCP 工具调用必须携带有效的 Bearer Token：\n\n```mermaid\ngraph LR\n A[客户端请求] --> B{Token 验证}\n B -->|无效| C[401 Unauthorized]\n B -->|有效| D[请求处理]\n D --> E[速率限制检查]\n E -->|超限| F[429 Too Many Requests]\n E -->|正常| G[执行业务逻辑]\n```\n\n### 权限控制\n\n- 用户级权限：验证用户身份与项目关联\n- 项目级隔离：记忆数据按项目隔离，不可跨项目访问\n- 工具级权限：部分工具需要管理员权限\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务监听端口 | `8314` |\n| `MCP_SERVER_HOST` | 绑定地址 | `127.0.0.1` |\n| `MCP_AUTH_REQUIRED` | 是否强制认证 | `true` |\n| `MCP_RATE_LIMIT` | 每分钟请求限制 | `60` |\n\n### 运行时配置\n\n```python\n# MCP 服务器初始化参数\nMCPConfig(\n host=\"127.0.0.1\",\n port=8314,\n auth_required=True,\n tools=[\n \"memory\",\n \"recall\", \n \"recommend\"\n ],\n rate_limit=60,\n timeout=30\n)\n```\n\n## 部署指南\n\n### 独立部署\n\n```bash\n# 启动 MCP 服务器\npiloci mcp serve --host 0.0.0.0 --port 8314\n```\n\n### Docker 部署\n\nMCP 服务器随主应用一同部署在 Docker 容器中，通过 `docker-compose.yml` 统一管理网络与端口映射。资料来源：[README.md]()\n\n```yaml\nservices:\n piloci:\n ports:\n - \"8314:8314\" # MCP + Web UI\n```\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 工具调用超时 | 网络延迟或后端负载高 | 检查 Redis/LanceDB 连接状态 |\n| 401 认证错误 | Token 过期或无效 | 重新获取 Token 并更新配置 |\n| SSE 连接断开 | 反向代理超时 | 调整代理超时设置 |\n| 工具列表为空 | MCP 服务器未正确加载 | 检查服务器日志 |\n\n### 调试模式\n\n启用调试日志：\n\n```bash\nexport PILOCI_LOG_LEVEL=DEBUG\npiloci mcp serve\n```\n\n## 相关文档\n\n- [安装指南](../installation/) - MCP 客户端配置详解\n- [API 参考](../api/) - MCP 工具完整 API 文档\n- [安全架构](../security/) - 认证与授权机制\n\n---\n\n\n\n## 策展人管道与记忆处理\n\n### 相关页面\n\n相关主题：[数据库与存储层](#page-database), [转录本摄入与 CLI](#page-ingest), [Obsidian 工作区集成](#page-workspace)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/curator/scheduler.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/scheduler.py)\n- [src/piloci/curator/distillation_worker.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/distillation_worker.py)\n- [src/piloci/curator/extraction.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/extraction.py)\n- [src/piloci/curator/gemma.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/gemma.py)\n- [src/piloci/curator/budget.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/budget.py)\n- [src/piloci/llm.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/llm.py)\n \n\n# 策展人管道与记忆处理\n\n## 概述\n\n策展人管道（Curation Pipeline）是 piLoci 系统中负责将原始会话数据转化为结构化记忆的核心处理引擎。它位于会话采集与知识存储之间，承担着**提取（Extraction）**、**蒸馏（Distillation）**、**嵌入（Embedding）**和**存储（Storage）**四个关键阶段。\n\n```mermaid\ngraph LR\n A[原始会话采集] --> B[策展人调度器]\n B --> C{状态检查}\n C -->|pending| D[蒸馏工作器]\n C -->|已有记忆| E[跳过]\n D --> F[提取模块]\n F --> G[ Gemma 本地模型]\n G --> H[外部 LLM 备选]\n H --> I[预算控制器]\n I --> J[嵌入向量生成]\n J --> K[LanceDB 存储]\n```\n\n## 核心架构组件\n\n### 组件职责表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 调度器 | `curator/scheduler.py` | 管理任务队列、触发蒸馏工作器、处理低配环境适配 |\n| 蒸馏工作器 | `curator/distillation_worker.py` | 执行记忆提取的核心工作流、控制温度/负载限制 |\n| 提取模块 | `curator/extraction.py` | 调用 LLM 从会话中提取结构化记忆 |\n| Gemma 模块 | `curator/gemma.py` | 管理本地 Gemma 模型推理 |\n| 预算控制器 | `curator/budget.py` | 管理外部 LLM 调用预算、实施成本控制 |\n| LLM 接口 | `llm.py` | 统一封装本地/外部 LLM 调用接口 |\n\n### 策展人调度器（Scheduler）\n\n调度器是策展人管道的入口点，负责：\n\n1. **轮询待处理会话**：从数据库获取 `state='pending'` 的原始会话\n2. **环境适配检测**：检查 `LOW_SPEC_MODE` 配置，低配模式下延迟处理\n3. **触发蒸馏流程**：将待处理任务分配给蒸馏工作器\n\n```python\n# 资料来源：src/piloci/curator/scheduler.py\nclass CurationScheduler:\n def poll_pending_sessions(self):\n \"\"\"获取所有待处理的原始会话\"\"\"\n \n def should_process(self, session) -> bool:\n \"\"\"根据环境状态判断是否应该处理\"\"\"\n```\n\n### 蒸馏工作器（Distillation Worker）\n\n蒸馏工作器是管道核心，负责协调整个记忆提取流程：\n\n```mermaid\ngraph TD\n A[开始蒸馏] --> B{温度超限?}\n B -->|是| C[暂停等待]\n B -->|否| D{负载超限?}\n D -->|是| C\n D -->|否| E{队列溢出?}\n E -->|是| F[使用外部 LLM]\n E -->|否| G[使用本地 Gemma]\n F --> H[预算检查]\n G --> H\n H --> I{预算充足?}\n I -->|否| J[跳过处理]\n I -->|是| K[执行提取]\n K --> L[存储记忆]\n```\n\n**关键控制参数**：\n\n| 参数 | 说明 | 默认行为 |\n|------|------|----------|\n| `temp_ceiling` | SoC 温度上限（°C） | 超过则暂停工作器 |\n| `load_ceiling` | 1分钟负载均值上限 | 超过则暂停工作器 |\n| `overflow_threshold` | 等待队列行数上限 | 超过则触发外部 LLM 旁路 |\n| `monthly_budget` | 月度外部 LLM 预算（USD） | 超额后阻止外部调用 |\n\n```python\n# 资料来源：src/piloci/curator/distillation_worker.py\nclass DistillationWorker:\n async def process_session(self, session):\n if self._temperature_too_high():\n return WorkerStatus.PAUSED\n if self._load_too_high():\n return WorkerStatus.PAUSED\n # 继续处理...\n```\n\n## 记忆提取流程（Extraction）\n\n### 提取模块职责\n\n提取模块负责将非结构化的会话文本转化为结构化记忆：\n\n```python\n# 资料来源：src/piloci/curator/extraction.py\nasync def extract_memories(session_transcript: str) -> List[Memory]:\n \"\"\"从会话记录中提取结构化记忆\"\"\"\n```\n\n### Gemma 本地模型集成\n\nGemma 模块提供本地推理能力，避免依赖外部服务：\n\n```python\n# 资料来源：src/piloci/curator/gemma.py\nclass GemmaModel:\n def __init__(self, model_path: str, device: str = \"cpu\"):\n \"\"\"初始化 Gemma 模型\"\"\"\n \n async def generate(self, prompt: str) -> str:\n \"\"\"本地生成响应\"\"\"\n```\n\n**Gemma 配置选项**：\n\n| 配置项 | 说明 |\n|--------|------|\n| `GemmaModel` | 模型实例化 |\n| `--mlock` | 内存锁定（Pi 上禁止） |\n| `KV_CACHE_SIZE` | 缓存大小限制（Pi 上禁止 > 8192） |\n\n### LLM 统一接口\n\n```python\n# 资料来源：src/piloci/llm.py\nclass LLMClient:\n async def chat_json(\n self, \n messages: List[Message],\n schema: Dict\n ) -> Dict:\n \"\"\"统一调用接口，自动选择本地/外部 LLM\"\"\"\n \n async def chat_stream(\n self, \n messages: List[Message]\n ) -> AsyncIterator[str]:\n \"\"\"流式响应接口\"\"\"\n```\n\n## 预算控制（Budget Management）\n\n预算控制器确保外部 LLM 调用的成本可控：\n\n```mermaid\ngraph TD\n A[外部 LLM 请求] --> B[预算检查]\n B --> C{月度已用}\n C -->|超出限额| D[拒绝请求]\n C -->|在限额内| E[执行调用]\n E --> F[记录消费]\n F --> G[更新统计]\n```\n\n```python\n# 资料来源：src/piloci/curator/budget.py\nclass BudgetController:\n async def check_and_record(self, cost_usd: float) -> bool:\n \"\"\"检查预算并记录消费，返回是否允许调用\"\"\"\n \n def get_remaining_budget(self) -> float:\n \"\"\"获取剩余预算\"\"\"\n```\n\n## 记忆状态机\n\n会话记忆的处理遵循严格的状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 会话采集\n pending --> processing: 调度器选中\n processing --> completed: 提取成功\n processing --> failed: 提取失败\n processing --> pending: 资源不足\n completed --> [*]\n failed --> pending: 重试\n```\n\n| 状态 | 说明 | 允许的操作 |\n|------|------|-----------|\n| `pending` | 等待处理 | 调度器可领取 |\n| `processing` | 处理中 | 工作器正在处理 |\n| `completed` | 已完成 | 已提取并存储记忆 |\n| `failed` | 失败 | 可重试回 pending |\n\n## 配置与调优\n\n### 环境变量配置\n\n```bash\n# 低配环境模式（Raspberry Pi 等级硬件）\nLOW_SPEC_MODE=true\n\n# 会话保留策略\nRAW_SESSION_RETENTION_DAYS=30 # 处理完成后原会话保留天数\nAUDIT_LOG_RETENTION_DAYS=90 # 审计日志保留天数\nMAINTENANCE_INTERVAL_SEC=3600 # 后台维护周期（秒）\n\n# SQLite 性能调优\nSQLITE_BUSY_TIMEOUT_MS=30000\nSQLITE_SYNCHRONOUS=NORMAL\n\n# 数据库路径\nLANCEDB_PATH=./data/lancedb\n```\n\n### 存储后端\n\n| 存储类型 | 用途 | 特点 |\n|----------|------|------|\n| SQLite | 身份数据、会话元数据 | WAL 模式、外键约束启用 |\n| LanceDB | 嵌入向量存储 | 本地嵌入式、与 SQLite 同期备份 |\n| Redis | 会话缓存 | 临时性、用于实时查询 |\n\n## 数据流示意\n\n```mermaid\ngraph LR\n subgraph 采集层\n A1[Claude Code Hook]\n A2[OpenCode MCP]\n end\n \n subgraph 策展人管道\n B1[调度器]\n B2[蒸馏工作器]\n B3[提取模块]\n B4[预算控制器]\n end\n \n subgraph 存储层\n C1[SQLite]\n C2[LanceDB]\n end\n \n A1 --> B1\n A2 --> B1\n B1 --> B2\n B2 --> B3\n B3 --> B4\n B4 --> C1\n B4 --> C2\n```\n\n## 注意事项\n\n### Pi 硬件限制\n\n根据项目规范，以下配置**禁止**在 Pi 环境中使用：\n\n| 禁止项 | 原因 |\n|--------|------|\n| `llama-server --mlock` | 内存锁定不适合低内存设备 |\n| `KV_CACHE_SIZE > 8192` | 过大缓存导致 OOM |\n| 强制 `state='pending'` 时立即调用 LLM | 违反工作器自主调度原则 |\n\n### 状态转换规则\n\n- **禁止绕过** `RawSession.distillation_state` 进行状态修改\n- 所有状态转换必须通过工作器或 ingest 处理器\n- 新增 LLM 调用路径时必须使用 `chat_json` + `record_target`\n\n---\n\n\n\n## 记忆工具与召回机制\n\n### 相关页面\n\n相关主题：[MCP 服务器实现](#page-mcp-server), [转录本摄入与 CLI](#page-ingest), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n- [src/piloci/chat.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/chat.py)\n- [src/piloci/api/routes.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/routes.py)\n- [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)\n \n\n# 记忆工具与召回机制\n\n## 概述\n\npiLoci 的记忆工具与召回机制是系统的核心功能模块，旨在为 AI 助手（Claude Code、OpenCode 等）提供持久化上下文记忆能力。该机制允许 AI 在会话之间自动保存关键信息，并通过向量检索实现精准召回，无需用户手动管理笔记。\n\n### 核心设计目标\n\n- **自动采集**：通过 MCP 协议自动捕获会话中的重要上下文\n- **智能检索**：基于向量嵌入的语义搜索，实现跨会话记忆召回\n- **项目隔离**：支持多项目独立记忆空间，确保数据隔离\n- **隐私优先**：所有嵌入计算在本地（Pi 5）执行，敏感数据不出设备\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 架构设计\n\n### 整体技术栈\n\n| 组件 | 用途 | 技术选型 |\n|------|------|---------|\n| 身份数据 | 用户、项目、权限管理 | SQLite |\n| 向量存储 | 记忆嵌入向量存储与检索 | LanceDB |\n| 会话管理 | 临时会话状态与缓存 | Redis |\n| 嵌入计算 | 本地 ONNX 推理 | fastembed |\n| API 层 | MCP 协议与 REST 接口 | Python/FastAPI |\n| 前端 | 记忆可视化与项目管理 | Next.js |\n\n资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n\n### 数据流架构图\n\n```mermaid\ngraph TD\n A[AI Client
Claude Code / OpenCode] -->|MCP Protocol| B[piLoci API Server]\n B --> C{Memory Operation}\n C -->|存储| D[LanceDB
向量数据库]\n C -->|检索| E[fastembed
本地嵌入]\n D -->|召回结果| B\n E -->|查询向量| D\n B -->|MCP Response| A\n \n F[Session Transcript] -->|捕获| G[Ingest Handler]\n G -->|状态: pending| H[Lazy Distillation Worker]\n H -->|批量处理| I[LLM 蒸馏]\n I -->|生成记忆| D\n \n J[Next.js Frontend] -->|管理界面| B\n J -->|可视化| K[记忆图谱]\n```\n\n---\n\n## 记忆工具实现\n\n### MCP 工具注册\n\npiLoci 通过 MCP（Model Context Protocol）协议向 AI 客户端暴露记忆工具。工具注册遵循严格规范：\n\n| 规范项 | 限制 |\n|--------|------|\n| 工具描述 (description) | ≤ 120 字符 |\n| 参数描述 | ≤ 80 字符 |\n| Schema 格式 | 通过 `compact_schema()` 压缩 |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### 核心工具列表\n\n#### 1. memory 工具\n创建新的记忆条目，支持关联项目和标签。\n\n```python\n# 伪代码示例\nmemory = {\n \"content\": \"用户偏好使用 TypeScript\",\n \"project_id\": \"proj_xxx\",\n \"tags\": [\"preference\", \"language\"],\n \"created_by\": \"claude_code\"\n}\n```\n\n#### 2. recall 工具\n基于语义查询召回相关记忆，使用向量相似度匹配。\n\n#### 3. recommend 工具\n根据当前会话上下文主动推荐相关记忆，无需显式查询。\n\n资料来源：[src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n\n---\n\n## 召回机制详解\n\n### 向量检索流程\n\n```mermaid\ngraph LR\n A[用户查询] -->|自然语言| B[Query Embedding
fastembed]\n B -->|向量表示| C[相似度计算
LanceDB]\n C -->|Top-K 结果| D[重排序]\n D -->|召回记忆| E[返回结果]\n \n F[(LanceDB
向量索引)] -->|存储| C\n```\n\n### 安全过滤机制\n\n**重要**：所有 LanceDB 查询必须包含项目级过滤条件。\n\n```python\n# 正确示例 - 包含 (user_id, project_id) 过滤\nresults = lancedb_table.search(query_vector)\\\n .where(f\"user_id = '{user_id}' AND project_id = '{project_id}'\")\\\n .limit(10)\n\n# 错误示例 - 缺少过滤条件会导致数据泄露\nresults = lancedb_table.search(query_vector).limit(10) # 禁止！\n```\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### API 端点\n\n| 端点 | 方法 | 用途 |\n|------|------|------|\n| `/api/memories` | POST | 创建项目作用域记忆 |\n| `/api/memories` | GET | 列出当前记忆 |\n| `/api/projects/{id}/workspace` | GET | 获取工作区笔记 |\n\n资料来源：[MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)\n\n---\n\n## 性能优化策略\n\n### Pi 5 部署原则\n\n| 优化项 | 实施方式 |\n|--------|----------|\n| 嵌入计算 | 必须使用 `run_in_executor` 异步执行，避免阻塞 |\n| 缓存策略 | 利用 LRU 缓存 (`storage/cache.py`) 减少重复计算 |\n| 批量处理 | 优先批量操作，禁止单条循环处理 |\n| JSON 序列化 | 统一使用 `orjson`，禁止标准库 `json` |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### 懒蒸馏管道 (Lazy Distillation Pipeline)\n\n会话转录 → 记忆提取采用懒加载单 worker 架构：\n\n```mermaid\ngraph LR\n A[Session Transcript] -->|保存| B[RawSession
state: pending]\n B -->|队列| C[Lazy Worker]\n C -->|累积批次| D[Gemma 蒸馏调用]\n D -->|生成| E[Memory + Instincts]\n E -->|存储| F[LanceDB]\n```\n\n**懒蒸馏五要素**：\n\n1. **收集/蒸馏分离**：`/api/ingest` 和 `/api/sessions/analyze` 不直接调用 LLM\n2. **状态持久化**：RawSession 以 `state='pending'` 保存，待 worker 处理\n3. **批量处理**：worker 累积批次后单次 Gemma 调用\n4. **外部追踪**：所有 LLM 调用必须通过 `chat_json` + `record_target`\n5. **Pi 适配**：禁止使用 `--mlock` 或 KV cache 8192+ 等高端参数\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 前端集成\n\n### 记忆可视化\n\npiLoci 前端使用 Next.js 构建，提供记忆图谱展示能力：\n\n```tsx\n// 仪表板摘要面板 - 展示会话记忆状态\n\n - sessionMemories: \"已提取 {count} 条记忆\"\n - sessionPending: \"处理中...\"\n\n```\n\n资料来源：[web/components/DashboardSummaryPanels.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/DashboardSummaryPanels.tsx)\n\n### 项目工作区视图\n\n支持按项目隔离记忆，提供会话列表和转录查看功能：\n\n```tsx\n\n - TranscriptViewer: 查看完整会话转录\n - 客户端标识: Claude Code / OpenCode 等\n - 状态追踪: pending / processed / error\n\n```\n\n资料来源：[web/components/ProjectSessionsPanel.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/ProjectSessionsPanel.tsx)\n\n### API 客户端\n\n前端通过统一 API 客户端与服务端通信：\n\n```typescript\n// web/lib/api.ts\nexport const api = {\n createMemory: (body) => request(\"/api/memories\", { method: \"POST\", body }),\n getFreshness: (projectId) => request(`/api/projects/${projectId}/freshness`),\n // ... 其他端点\n}\n```\n\n资料来源：[web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)\n\n---\n\n## 使用场景\n\n### 场景 A — 团队记忆中心\n\n团队成员在共享的 Pi 5 上各自创建账户，共享项目空间，通过 MCP 工具存储记忆，实现知识共享与项目隔离。\n\n### 场景 B — 多项目工作区\n\n独立开发者或研究员在单一 piLoci 实例上管理多个项目（如\"论文研究\"、\"客户端项目\"），各项目记忆相互隔离，通过工作区视图查看关联关系。\n\n### 场景 C — Obsidian 导出\n\n将 piLoci 中的工作区笔记导出至 Obsidian 金库：\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n\n---\n\n## 安全规范\n\n| 规范项 | 要求 |\n|--------|------|\n| 向量查询过滤 | 必须包含 `(user_id, project_id)` 双重过滤 |\n| 密码存储 | 仅允许 argon2id 算法，禁止 bcrypt |\n| 密钥管理 | JWT secret、session secret 必须通过环境变量或 Docker secrets |\n| SQL 使用 | 禁止 raw SQL，统一使用 SQLAlchemy ORM |\n| 输入验证 | 所有用户输入必须经过 Pydantic schema 验证 |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 开发指南\n\n### 新增 MCP 工具步骤\n\n1. 在 `src/piloci/tools/` 中实现工具逻辑\n2. 在 `src/piloci/mcp/tools.py` 中注册工具\n3. 确保描述符合字符限制（工具 ≤120，参数 ≤80）\n4. 通过 `compact_schema()` 验证 schema 格式\n5. 在 `tests/test_tools_*.py` 中添加测试用例\n\n### 代码风格规范\n\n| 工具 | 配置 |\n|------|------|\n| formatter | black (line-length=100) |\n| linter | ruff |\n| import sort | isort (profile=black) |\n\n提交前必须执行 pre-commit 检查。\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n\n\n## Obsidian 工作区集成\n\n### 相关页面\n\n相关主题：[策展人管道与记忆处理](#page-curator), [转录本摄入与 CLI](#page-ingest)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)（工作区 API 与导出功能）\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)（Obsidian 集成说明）\n- [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)（Vault 缓存与 Obsidian 导出计划）\n- [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)（前端 API 调用）\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)（技术架构与工作流设计）\n\n> **注意**：以下源文件在本次检索上下文中未找到实际代码内容，但文档中明确引用了其功能描述：\n> - `src/piloci/api/routes.py`\n> - `src/piloci/curator/vault.py`\n> - `web/components/VaultNoteCard.tsx`\n> - `web/components/MemoryGraphPanel.tsx`\n\n以下页面内容基于**可验证的上下文文件**整理，并标注了具体引用来源。\n\n \n\n# Obsidian 工作区集成\n\n## 概述\n\npiLoci 的 Obsidian 工作区集成是一种将 piLoci 内部管理的记忆（Memories）与直觉（Instincts）导出为 Obsidian 笔记库格式的能力。该功能支持：\n\n- 从 piLoci 存储的记忆生成 Obsidian 风格的 Markdown 文件\n- 保留 YAML frontmatter 元数据\n- 生成双向链接（Wikilinks）和标签系统\n- 构建笔记关系图数据\n- 支持将整个工作区打包为可下载的 Obsidian zip 压缩包\n\n> 资料来源：[README.md - Obsidian export scenario]()\n\n## 核心概念\n\n### 工作区（Workspace）\n\n工作区是 piLoci 中按项目（Project）隔离的记忆容器。每个项目拥有独立的工作区，包含该项目的所有笔记、图关系和元数据。\n\n### 笔记格式（Note Format）\n\n导出的笔记采用 Obsidian 风格格式：\n\n| 字段 | 说明 |\n|------|------|\n| `path` | 笔记文件路径 |\n| `title` | 笔记标题 |\n| `markdown` | 笔记正文内容 |\n| `tags` | 标签数组 |\n| `created_at` | 创建时间 |\n| `updated_at` | 更新时间 |\n\n> 资料来源：[README.ko.md - Obsidian 내보내기]()\n> 资料来源：[MEMORY.md - Obsidian-style workspace generation]()\n\n## 技术架构\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户交互] --> B[Web UI / API]\n B --> C[piLoci Backend]\n C --> D[SQLite - 身份数据]\n C --> E[LanceDB - 向量存储]\n C --> F[Vault Cache /data/vaults/{slug}/vault.json]\n \n G[Obsidian Export] --> H[GET /api/projects/slug/{slug}/workspace]\n G --> I[GET /api/vault/{slug}/export]\n \n F --> J[Markdown Notes]\n F --> K[Graph Relations]\n \n J --> L[Obsidian Vault]\n K --> M[Obsidian Graph View]\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant VaultCache\n participant FileSystem\n \n User->>API: 请求项目工作区\n API->>VaultCache: 查询缓存数据\n VaultCache-->>API: 返回 vault.json\n API->>User: 返回工作区数据\n \n User->>API: 请求导出\n API->>VaultCache: 读取 vault.json\n VaultCache->>FileSystem: 生成 Markdown 文件\n FileSystem->>User: 返回 Obsidian zip 包\n```\n\n> 资料来源：[MEMORY.md - Vault work is no longer...]()\n> 资料来源：[README.md - Cached vault + export path]()\n\n## API 端点\n\n### 工作区数据获取\n\n```bash\n# 获取项目工作区（JSON 格式）\nGET /api/projects/slug/{slug}/workspace\n\n# 响应结构\n{\n \"notes\": [\n {\n \"path\": \"path/to/note.md\",\n \"title\": \"笔记标题\",\n \"markdown\": \"# 笔记内容...\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n }\n ],\n \"graph\": {\n \"nodes\": [...],\n \"links\": [...]\n }\n}\n```\n\n> 资料来源：[README.md - Usage scenarios - Scenario C]()\n> 资料来源：[web/lib/api.ts - projectWorkspace]()\n\n### 导出 API\n\n```bash\n# 导出为 Obsidian zip 包\nGET /api/vault/{slug}/export\n\n# 前端调用示例（来自 web/lib/api.ts）\nprojectWorkspace: (slug: string) =>\n request(`/api/projects/slug/${slug}/workspace`),\n```\n\n> 资料来源：[README.md - Obsidian-style zip]()\n\n### 前端 API 封装\n\n```typescript\n// web/lib/api.ts 中的相关端点\nexport const api = {\n // 项目工作区\n projectWorkspace: (slug: string) =>\n request(`/api/projects/slug/${slug}/workspace`),\n \n // 项目记忆\n projectKnacks: (slug: string) =>\n request(`/api/projects/slug/${slug}/knacks`),\n};\n```\n\n> 资料来源：[web/lib/api.ts - Projects API]()\n\n## 使用场景\n\n### 场景 A — 团队项目记忆中心\n\n小团队在共享的树莓派 5 上部署 piLoci，每个成员创建账户并加入共享项目。通过 MCP 工具存储记忆，所有成员共享同一知识库，同时项目隔离机制确保工作互不干扰。\n\n### 场景 B — 多项目工作空间\n\n独立开发者或研究者在一个 piLoci 实例上运营多个项目（如\"论文研究\"、\"个人项目\"、\"客户工作\"）。每个项目的记忆相互隔离，工作区浏览器可按项目查看笔记和关系图。\n\n### 场景 C — Obsidian 导出\n\n生成工作区笔记并通过简单文件写入导出到 Obsidian 保管库——适用于希望在 piLoci 收集知识后在 Obsidian 中进行整理的团队。\n\n```bash\n# 直接获取工作区数据\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n\n# 使用现成的导出功能\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n> 资料来源：[README.md - Usage scenarios]()\n> 资料来源：[README.ko.md - 사용 시나리오]()\n\n## 实际集成方式\n\n### 当前推荐工作流\n\n1. 在 piLoci 内部通过 MCP 工具或 Web UI 存储和整理记忆\n2. 调用 `GET /api/projects/slug/{slug}/workspace` 获取工作区数据\n3. 将 `workspace.notes[].markdown` 写入对应的 `workspace.notes[].path`\n4. 将该目录作为 Obsidian 保管库打开，或同步到现有保管库\n\n### 核心实现代码位置\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 记忆存储 | `src/piloci/storage/instincts_store.py` | 管理记忆和直觉数据的持久化 |\n| Vault 生成 | `src/piloci/curator/vault.py` | 从记忆中生成 Obsidian 风格笔记 |\n| API 路由 | `src/piloci/api/routes.py` | 暴露工作区和导出 API |\n| 前端组件 | `web/components/VaultNoteCard.tsx` | 笔记卡片展示 |\n| 图可视化 | `web/components/MemoryGraphPanel.tsx` | 记忆关系图面板 |\n\n> 资料来源：[MEMORY.md - Added preview coverage in tests/test_vault_cache.py]()\n\n## Vault 缓存机制\n\n生成的 workspace 数据现在持久化在 `/data/vaults/{slug}/vault.json`，导出 API 返回包含 Markdown 笔记和 vault JSON 快照的 Obsidian 风格 zip 包。\n\n```\n/data/vaults/{slug}/\n├── vault.json # 缓存的工作区数据\n├── notes/ # 生成的 Markdown 笔记\n│ ├── note-1.md\n│ └── note-2.md\n└── graph.json # 关系图数据\n```\n\n> 资料来源：[README.md - Cached vault + export path]()\n> 资料来源：[MEMORY.md - Vault work is no longer...]()\n> 资料来源：[CLAUDE.md - Local-first deployment model]()\n\n## 配置与部署\n\n### 反向代理配置\n\n在反向代理后面公开 piLoci 时，必须在 `.env` 中使用 `BASE_URL` 固定外部 HTTPS 域名：\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\nGoogle OAuth 重定向 URI 必须完全匹配，在 Google Cloud Console 中注册以下回调：\n\n```\nhttps://piloci.example.com/auth/google/callback\n```\n\n> 资料来源：[README.ko.md - 리버스 프록시 / 터널]()\n\n### 端口配置\n\n默认端口 `8314`，需要在反向代理或隧道中暴露。支持的边缘配置：\n\n- Cloudflare Tunnel\n- Caddy\n- nginx\n\n默认配置将 Pi 主机的 `http://127.0.0.1:8314` 作为代理目标。\n\n> 资料来源：[README.ko.md - 리버스 프록시 / 터널]()\n\n## 未来规划\n\n| 功能 | 状态 | 说明 |\n|------|------|------|\n| Obsidian 单向同步（piLoci → Obsidian） | ✅ 已实现 | 通过 API 导出 |\n| 完整双向同步 | 📋 计划中 | 冲突处理和流畅编辑反馈 |\n| 专用 Obsidian 插件 | 📋 计划中 | 提供更好的原生集成体验 |\n\n> 资料来源：[README.md - 笔记中描述的完整双向同步计划]()\n> 资料来源：[MEMORY.md - 笔记中描述的完整双向同步计划]()\n\n## 技术栈\n\npiLoci 的 Obsidian 集成依赖以下底层技术：\n\n| 技术 | 用途 |\n|------|------|\n| **SQLite** | 身份数据存储 |\n| **LanceDB** | 嵌入向量存储 |\n| **Redis** | 会话管理 |\n| **fastembed (ONNX)** | 本地推理嵌入计算 |\n| **Next.js** | 前端框架 |\n\n> 资料来源：[README.md - Tech stack]()\n> 资料来源：[CLAUDE.md - Local-first deployment model]()\n\n## 快速开始\n\n### 1. 获取工作区数据\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace | jq .\n```\n\n### 2. 导出为 Obsidian zip\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n### 3. 解压到 Obsidian 保管库\n\n```bash\nunzip my-project-export.zip -d ~/Obsidian/my-project-vault\n```\n\n### 4. 在 Obsidian 中打开\n\n在 Obsidian 中选择\"打开保管库\"，指向解压后的目录即可。\n\n---\n\n> **页面更新日志**\n> - 创建时间：基于 piLoci v0.3 源码\n> - 最后更新：2024 年\n> - 主要参考：README.md, MEMORY.md, web/lib/api.ts, CLAUDE.md\n\n---\n\n\n\n## 转录本摄入与 CLI\n\n### 相关页面\n\n相关主题：[MCP 服务器实现](#page-mcp-server), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/cli_ingest.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli_ingest.py)\n- [src/piloci/api/data_portability.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/data_portability.py)\n- [clients/python/src/piloci_client/_client.py](https://github.com/jshsakura/oc-piloci/blob/main/clients/python/src/piloci_client/_client.py)\n- [scripts/piloci-stop-hook.sh](https://github.com/jshsakura/oc-piloci/blob/main/scripts/piloci-stop-hook.sh)\n \n\n# 转录本摄入与 CLI\n\npiLoci 的转录本摄入系统负责将 AI 客户端（Claude Code、OpenCode 等）产生的会话记录捕获并导入到后端进行记忆提取和向量化存储。本页详细说明摄入 CLI 工具、客户端钩子机制以及数据导出功能。\n\n## 概述\n\npiLoci 的摄入架构包含三个核心组件：\n\n| 组件 | 类型 | 职责 |\n|------|------|------|\n| `piloci-ingest` | CLI 工具 | 手动发送本地存储的转录本到服务器 |\n| 客户端钩子 | Shell/Python 脚本 | 自动捕获会话开始/结束事件 |\n| Python Client | SDK | 提供 MCP 工具接口 |\n\n资料来源：[README.md](./README.md)\n\n## 转录本摄入 CLI\n\n### 核心命令\n\n`piloci-ingest` 是 piLoci 提供的命令行工具，用于将捕获的客户端转录本发送到服务器摄入队列：\n\n```bash\npiloci-ingest --client opencode --dry-run\npiloci-ingest --client codex --history-file ~/.codex/history.json\n```\n\n### 参数说明\n\n| 参数 | 说明 | 示例值 |\n|------|------|--------|\n| `--client` | 客户端类型 | `opencode`, `codex` |\n| `--dry-run` | 模拟运行，不实际发送 | 布尔标志 |\n| `--history-file` | 历史记录文件路径 | `~/path/to/file` |\n\n资料来源：[README.md](./README.md)\n\n## 客户端钩子机制\n\n### 工作原理\n\npiLoci 通过 Claude Code 的钩子系统实现会话转录本的自动捕获。钩子在插件安装时配置到 `~/.config/piloci/` 目录。\n\n### 目录结构\n\n安装后，piLoci 在用户主目录创建以下结构：\n\n```\n~/.config/piloci/\n├── config.json # 令牌 + ingest/analyze URL（权限 0600）\n├── hook.py # SessionStart 补抓钩子（Claude 专用）\n└── stop-hook.sh # Stop 实时推送钩子（Claude 专用）\n```\n\n资料来源：[README.md](./README.md)\n\n### 插件目录布局\n\n完整的 Claude 插件目录结构：\n\n```\npiloci/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json ← SessionStart + Stop 绑定到下方脚本\n├── hooks/hook.py ← 从 /api/hook/script 下载\n├── hooks/stop-hook.sh ← 从 /api/hook/stop-script 下载\n└── .mcp.json ← memory/recall/recommend MCP 服务器\n```\n\n资料来源：[src/piloci/installer.py:25-36](src/piloci/installer.py)\n\n### 钩子类型\n\n| 钩子名称 | 触发时机 | 功能 |\n|----------|----------|------|\n| SessionStart | 会话开始 | 补抓历史转录本 |\n| Stop | 会话结束 | 实时推送当前会话转录本 |\n\n### 插件清单配置\n\n插件清单 (`plugin.json`) 包含以下元数据：\n\n```json\n{\n \"name\": \"piloci\",\n \"version\": \"\",\n \"description\": \"piLoci memory — auto-capture sessions and expose memory/recall/recommend MCP tools\",\n \"author\": {\"name\": \"piLoci\"},\n \"homepage\": \"https://github.com/jshsakura/oc-piloci\",\n \"license\": \"MIT\"\n}\n```\n\n资料来源：[src/piloci/installer.py:46-58](src/piloci/installer.py)\n\n## Python Client SDK\n\n### 客户端功能\n\nPython 客户端 (`piloci_client`) 提供 MCP 工具接口，用于与 piLoci 服务器通信：\n\n- **记忆管理**：创建、查询、删除记忆\n- **项目操作**：项目管理、成员邀请\n- **会话查询**：查看历史会话和处理状态\n\n### MCP 工具\n\n客户端注册以下 MCP 工具：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory` | 存储和检索记忆 |\n| `recall` | 基于语义搜索回忆相关记忆 |\n| `recommend` | 推荐相关上下文记忆 |\n\n资料来源：[src/piloci/installer.py](src/piloci/installer.py)\n\n## 数据导出与迁移\n\n### Vault 导出 API\n\npiLoci 提供数据导出端点，支持将工作区笔记导出为独立文件：\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n### Obsidian 集成\n\n导出工作区笔记的 API：\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n```\n\n导出流程：\n1. 调用 API 获取项目工作区数据\n2. 将 `workspace.notes[].markdown` 写入对应路径\n3. 用该目录作为 Obsidian 保管库打开\n\n资料来源：[README.md](./README.md)\n\n### 使用场景\n\n| 场景 | 描述 |\n|------|------|\n| 团队知识中心 | 团队成员共享项目记忆 |\n| 多项目工作区 | 独立开发者管理多个项目 |\n| Obsidian 导出 | 将收集的知识导出到 Obsidian 进行整理 |\n\n## 认证与配置\n\n### 配置文件\n\n`~/.config/piloci/config.json` 包含：\n\n| 字段 | 说明 |\n|------|------|\n| `token` | 认证令牌 |\n| `ingest_url` | 摄入服务地址 |\n| `analyze_url` | 分析服务地址 |\n\n### Claude 配置\n\nClaude Code 的 MCP 服务器配置位于 `~/.claude.json`：\n\n```json\n{\n \"mcpServers\": {\n \"piloci\": {\n \"command\": \"piloci-mcp\",\n \"args\": []\n }\n }\n}\n```\n\nClaude 专用设置文件 `~/.claude/settings.json` 包含自动捕获钩子配置。\n\n资料来源：[README.md](./README.md)\n\n## 性能基线工具\n\n### profile-baseline CLI\n\npiLoci 提供性能采样工具，用于基线测试：\n\n```bash\nexport PILOCI_ENDPOINT=\"http://localhost:8314\"\nexport PILOCI_TOKEN=\"your-token\"\nexport PILOCI_PROFILE_BASELINE_SAMPLES=5\nexport PILOCI_PROFILE_BASELINE_TIMEOUT=5\nexport PILOCI_PROFILE_BASELINE_PATHS=\"/healthz,/readyz,/profilez\"\n\nuv run piloci profile-baseline\n```\n\n### 参数说明\n\n| 参数 | 环境变量 | 说明 |\n|------|----------|------|\n| `--samples` | `PILOCI_PROFILE_BASELINE_SAMPLES` | 采样次数 |\n| `--path` | `PILOCI_PROFILE_BASELINE_PATHS` | 采样路径 |\n| `--timeout` | `PILOCI_PROFILE_BASELINE_TIMEOUT` | 超时秒数 |\n| `--endpoint` | `PILOCI_ENDPOINT` | 服务地址 |\n| `--token` | `PILOCI_TOKEN` | 认证令牌 |\n\n配置优先级：CLI 参数 > 环境变量 > 默认值\n\n资料来源：[README.md](./README.md)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[AI 客户端会话开始] --> B[SessionStart 钩子触发]\n B --> C[下载历史转录本]\n C --> D[转录本摄入队列]\n \n E[会话进行中] --> F[Stop 钩子触发]\n F --> G[实时推送转录本]\n G --> D\n \n D --> H[后台 Worker 处理]\n H --> I{蒸馏状态检查}\n I -->|pending| J[LLM 提取记忆]\n I -->|done| K[直接存储]\n \n J --> L[向量嵌入 LanceDB]\n K --> L\n \n L --> M[记忆可查询]\n```\n\n## 注意事项\n\n1. **卸载**：删除 `~/.config/piloci` 目录即可完成卸载，无需修改 `~/.claude/settings.json` 或 `~/.claude.json`\n2. **令牌安全**：配置文件权限设为 0600，确保令牌不暴露\n3. **OpenCode 限制**：OpenCode 不支持钩子机制，无法进行实时会话捕获，但 MCP 工具仍可使用\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：jshsakura/oc-piloci\n\n摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Release v0.3.15。\n\n## 1. 安装坑 · 来源证据：Release v0.3.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Release v0.3.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Release v0.3.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Release v0.3.22\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.3.23\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.3.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release v0.3.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release v0.3.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release v0.3.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release v0.3.28\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | host_targets=mcp_host, claude\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | release_recency=unknown\n\n\n",
"markdown_key": "oc-piloci",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1219455965",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/jshsakura/oc-piloci"
},
{
"evidence_id": "art_bd304ff09145408a83456c9e5eb30999",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/jshsakura/oc-piloci#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "oc-piloci 说明书",
"toc": [
"https://github.com/jshsakura/oc-piloci 项目说明书",
"目录",
"项目介绍",
"概述",
"核心定位",
"主要功能",
"技术架构",
"组件结构",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1ce66d2582267b033e954cd0a642f1569755b1cd",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docker-compose.yml",
"uv.lock",
"docs/index.md",
"docs/WEB_BUILD.md",
"src/piloci/version.py",
"src/piloci/cli_ingest.py",
"src/piloci/cli.py",
"src/piloci/installer.py",
"src/piloci/profiling_baseline.py",
"src/piloci/llm.py",
"src/piloci/main.py",
"src/piloci/chat.py",
"src/piloci/__init__.py",
"src/piloci/config.py",
"src/piloci/__main__.py",
"src/piloci/api/static.py",
"src/piloci/api/distillation_routes.py",
"src/piloci/api/security.py",
"src/piloci/api/data_portability.py",
"src/piloci/api/team_routes.py",
"src/piloci/api/routes.py",
"src/piloci/api/v1.py",
"src/piloci/api/__init__.py",
"src/piloci/api/ratelimit.py",
"src/piloci/api/audit.py",
"src/piloci/mcp/sse.py",
"src/piloci/mcp/server.py",
"src/piloci/mcp/__init__.py",
"src/piloci/mcp/streamable_http.py",
"src/piloci/mcp/session_state.py",
"src/piloci/notify/telegram.py",
"src/piloci/notify/health.py",
"src/piloci/notify/__init__.py",
"src/piloci/tools/instinct_tools.py",
"src/piloci/tools/memory_tools.py",
"src/piloci/tools/_schema.py",
"src/piloci/tools/project_tools.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @piloci/sdk - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @piloci/sdk 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `curl -OJ http://localhost:8314/api/vault/my-project/export` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `curl -sS http://localhost:8314/api/projects/slug/my-project/workspace` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/jshsakura/oc-piloci/main/docker-compose.yml` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `curl -fsSLo .env.example https://raw.githubusercontent.com/jshsakura/oc-piloci/main/.env.example` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `curl -fsSLo deploy/setup.sh https://raw.githubusercontent.com/jshsakura/oc-piloci/main/deploy/setup.sh` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `git clone https://github.com/jshsakura/oc-piloci.git` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install -U oc-piloci && python -m piloci setup --server https://piloci.example.com` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `curl -sSL https://piloci.example.com/install/ | bash` 证据：`README.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`MEMORY.md`, `PLAN.md`, `README.ko.md`, `README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0012` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：281\n- 重要文件覆盖：40/281\n- 证据索引条目：42\n- 角色 / Skill 条目：11\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @piloci/sdk 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @piloci/sdk 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @piloci/sdk 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 11 个角色 / Skill / 项目文档条目。\n\n- **piLoci — Development Rules**（project_doc）：구현 세션 시작 시: 1. PLAN.md 읽기 → 현재 상태 체크박스 확인 2. 다음 미완료 항목부터 시작 3. 작업 완료 시 체크박스 업데이트 + MEMORY.md 갱신 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **piLoci**（project_doc）：! Website https://img.shields.io/badge/website-piloci.jshsakura.com-blue https://piloci.jshsakura.com/ ! 한국어 https://img.shields.io/badge/문서-한국어-green ./README.ko.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **@piloci/sdk**（project_doc）：TypeScript SDK for the piLoci https://github.com/Sisyphus-Junior/piloci self-hosted memory server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`clients/js/README.md`\n- **piloci-client**（project_doc）：Python SDK for piLoci https://github.com/Sisyphus-Junior/piloci — a self-hosted memory service for LLM assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`clients/python/README.md`\n- **Web Build**（project_doc）：docker-compose.dev.yml 에서 web 빌드를 Python 서비스 시작 전에 자동 실행하려면 아래처럼 profiles 를 활용하거나 별도 서비스를 추가합니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/WEB_BUILD.md`\n- **piLoci Documentation**（project_doc）：Live site : piloci.jshsakura.com https://piloci.jshsakura.com/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **MEMORY**（project_doc）：- Simplified the landing page install CTA: the separate install/update buttons are now one “설치 및 업데이트” / “Install and Update” command, copying uvx oc-piloci@latest setup so fresh installs and refreshes use the same path. - Prepared patch release 0.3.11 for the unified install/update CTA so the package version and release tag can stay aligned. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`MEMORY.md`\n- **piLoci — 개발 계획서**（project_doc）：이 문서는 계획 세션 Opus 4.7 과 구현 세션 Sonnet 4.6 사이의 인수인계 문서입니다. 새 세션을 시작하면 이 문서부터 읽고 현재 상태 섹션을 확인하세요. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`PLAN.md`\n- **piLoci**（project_doc）：! Website https://img.shields.io/badge/website-piloci.jshsakura.com-blue https://piloci.jshsakura.com/ ! English https://img.shields.io/badge/docs-English-blue ./README.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.ko.md`\n- **Security Policy**（project_doc）：Reporting a Vulnerability 취약점 발견 시 GitHub Security Advisories private 로 신고. 공개 Issue 금지. 응답 SLA: 7일 이내 acknowledgement, 90일 이내 패치. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **piLoci Design Harness**（project_doc）：piLoci UI should feel like a calm memory infrastructure product: clear, spatial, low-noise, and trustworthy. Use the shared pi- classes in app/globals.css before inventing new page-level styling. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`web/DESIGN-HARNESS.md`\n\n## 证据索引\n\n- 共索引 42 条证据。\n\n- **piLoci — Development Rules**（documentation）：구현 세션 시작 시: 1. PLAN.md 읽기 → 현재 상태 체크박스 확인 2. 다음 미완료 항목부터 시작 3. 작업 완료 시 체크박스 업데이트 + MEMORY.md 갱신 证据：`CLAUDE.md`\n- **piLoci**（documentation）：! Website https://img.shields.io/badge/website-piloci.jshsakura.com-blue https://piloci.jshsakura.com/ ! 한국어 https://img.shields.io/badge/문서-한국어-green ./README.ko.md 证据：`README.md`\n- **@piloci/sdk**（documentation）：TypeScript SDK for the piLoci https://github.com/Sisyphus-Junior/piloci self-hosted memory server. 证据：`clients/js/README.md`\n- **piloci-client**（documentation）：Python SDK for piLoci https://github.com/Sisyphus-Junior/piloci — a self-hosted memory service for LLM assistants. 证据：`clients/python/README.md`\n- **Package**（package_manifest）：{ \"name\": \"piloci-web\", \"private\": true, \"version\": \"0.0.1\", \"scripts\": { \"dev\": \"next dev --turbopack\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"test:coverage\": \"vitest run --coverage\", \"e2e\": \"playwright test\" }, \"dependencies\": { \"@hookform/resolvers\": \"^5.0.1\", \"@radix-ui/react-accordion\": \"^1.2.3\", \"@radix-ui/react-alert-dialog\": \"^1.1.6\", \"@radix-ui/react-avatar\": \"^1.1.3\", \"@radix-ui/react-checkbox\": \"^1.1.4\", \"@radix-ui/react-dialog\": \"^1.1.6\", \"@radix-ui/react-dropdown-menu\": \"^2.1.6\", \"@radix-ui/react-label\": \"^2.1.2\", \"@radix-ui/react-popover\": \"^1.1.6\", \"@radix-ui/react-progress\": \"^1.1.2\", \"@radix-ui/react… 证据：`web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@piloci/sdk\", \"version\": \"0.1.0\", \"description\": \"TypeScript SDK for the piLoci self-hosted memory server\", \"type\": \"module\", \"main\": \"./dist/index.cjs\", \"module\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"import\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" }, \"require\": { \"types\": \"./dist/index.d.cts\", \"default\": \"./dist/index.cjs\" } } }, \"files\": \"dist\", \"README.md\" , \"scripts\": { \"build\": \"tsup\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"typecheck\": \"tsc --noEmit\" }, \"devDependencies\": { \"tsup\": \"^8.3.5\", \"typescript\": \"^5.7.3\", \"vitest\": \"^3.1.3\" }, \"engines\": { \"node\": \" =18.0.0\" }, \"license\": \"MIT\", \"keywords\": \"piloci\", \"m… 证据：`clients/js/package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Web Build**（documentation）：docker-compose.dev.yml 에서 web 빌드를 Python 서비스 시작 전에 자동 실행하려면 아래처럼 profiles 를 활용하거나 별도 서비스를 추가합니다. 证据：`docs/WEB_BUILD.md`\n- **piLoci Documentation**（documentation）：Live site : piloci.jshsakura.com https://piloci.jshsakura.com/ 证据：`docs/index.md`\n- **MEMORY**（documentation）：- Simplified the landing page install CTA: the separate install/update buttons are now one “설치 및 업데이트” / “Install and Update” command, copying uvx oc-piloci@latest setup so fresh installs and refreshes use the same path. - Prepared patch release 0.3.11 for the unified install/update CTA so the package version and release tag can stay aligned. 证据：`MEMORY.md`\n- **piLoci — 개발 계획서**（documentation）：이 문서는 계획 세션 Opus 4.7 과 구현 세션 Sonnet 4.6 사이의 인수인계 문서입니다. 새 세션을 시작하면 이 문서부터 읽고 현재 상태 섹션을 확인하세요. 证据：`PLAN.md`\n- **piLoci**（documentation）：! Website https://img.shields.io/badge/website-piloci.jshsakura.com-blue https://piloci.jshsakura.com/ ! English https://img.shields.io/badge/docs-English-blue ./README.md 证据：`README.ko.md`\n- **Security Policy**（documentation）：Reporting a Vulnerability 취약점 발견 시 GitHub Security Advisories private 로 신고. 공개 Issue 금지. 응답 SLA: 7일 이내 acknowledgement, 90일 이내 패치. 证据：`SECURITY.md`\n- **piLoci Design Harness**（documentation）：piLoci UI should feel like a calm memory infrastructure product: clear, spatial, low-noise, and trustworthy. Use the shared pi- classes in app/globals.css before inventing new page-level styling. 证据：`web/DESIGN-HARNESS.md`\n- **.Eslintrc**（structured_config）：{ \"extends\": \"next/core-web-vitals\", \"plugins\": \"@typescript-eslint\" , \"rules\": { \"@typescript-eslint/no-unused-vars\": \"warn\" } } 证据：`web/.eslintrc.json`\n- **Components**（structured_config）：{ \"$schema\": \"https://ui.shadcn.com/schema.json\", \"style\": \"new-york\", \"rsc\": true, \"tsx\": true, \"tailwind\": { \"config\": \"\", \"css\": \"app/globals.css\", \"baseColor\": \"neutral\", \"cssVariables\": true, \"prefix\": \"\" }, \"aliases\": { \"components\": \"@/components\", \"utils\": \"@/lib/utils\", \"ui\": \"@/components/ui\", \"lib\": \"@/lib\", \"hooks\": \"@/hooks\" }, \"iconLibrary\": \"lucide\" } 证据：`web/components.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2017\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"preserve\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\" , \"exclude\": \"node modules\" } 证据：`web/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"strict\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"lib\": \"ES2022\", \"DOM\" }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"test\" } 证据：`clients/js/tsconfig.json`\n- **.dockerignore**（source_file）：.env .env. .envrc secrets/ .git/ .gitignore .venv/ venv/ pycache / .pyc .egg-info/ dist/ build/ sdist/ wheels/ .pytest cache/ .mypy cache/ .ruff cache/ .pyre/ .pytype/ .tox/ .nox/ .hypothesis/ .dmypy.json htmlcov/ .coverage .coverage. tests/ docs/ deploy/ web/node modules/ web/.next/ web/out/ node modules/ .log data/ qdrant data/ redis data/ .fastembed cache/ .lance/ .ipynb checkpoints/ .idea/ .vscode/ .claude/ .sisyphus/ opencode.json PLAN.md CLAUDE.md MEMORY.md 证据：`.dockerignore`\n- **piLoci Environment Variables**（source_file）：piLoci Environment Variables Copy to .env and fill in values. Never commit .env. 证据：`.env.example`\n- **To get started with Dependabot version updates, you'll need to specify which**（source_file）：To get started with Dependabot version updates, you'll need to specify which package ecosystems to update and where the package manifests are located. Please see the documentation for all configuration options: https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file 证据：`.github/dependabot.yml`\n- **── Environment & Secrets ──────────────────────────**（source_file）：── Environment & Secrets ────────────────────────── .env .env. !.env.example .envrc secrets/ 证据：`.gitignore`\n- **.Mcp.Json**（source_file）：{ \"mcpServers\": { \"piloci\": { \"type\": \"http\", \"url\": \"https://piloci.example.com/mcp/http\", \"headers\": { \"Authorization\": \"Bearer \" } } } } 证据：`.mcp.json.example`\n- **Two-stage hook setup:**（source_file）：Two-stage hook setup: - pre-commit every git commit → formatters + lint, ~1-2s - pre-push every git push → pytest + vitest, ~30-60s Run once after editing this file so both hook types are installed: pre-commit install The default install hook types line below makes pre-commit install wire up both hook types in one shot. default install hook types: pre-commit, pre-push 证据：`.pre-commit-config.yaml`\n- **piLoci — Multi-stage Dockerfile ARM64 / Raspberry Pi 5**（source_file）：piLoci — Multi-stage Dockerfile ARM64 / Raspberry Pi 5 证据：`Dockerfile`\n- **─────────────────────────────────────────────────────────────────────────────**（source_file）：───────────────────────────────────────────────────────────────────────────── Stage 1: pnpm install + next build ───────────────────────────────────────────────────────────────────────────── FROM public.ecr.aws/docker/library/node:22-slim AS builder 证据：`Dockerfile.web`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash ────────────────────────────────────────────────────────────── piLoci — First Deploy Setup Script Creates .env and fills in runtime secrets for production deployment. Usage: chmod +x deploy/setup.sh ./deploy/setup.sh Safe to re-run — keeps an existing .env untouched. ────────────────────────────────────────────────────────────── set -euo pipefail 证据：`deploy/setup.sh`\n- **── Dev proxy single external port ─────────────────────────**（source_file）：services: ── Dev proxy single external port ───────────────────────── nginx: image: nginx:alpine ports: - \"28314:80\" volumes: - ./deploy/nginx/dev.conf:/etc/nginx/conf.d/default.conf:ro extra hosts: - \"host.docker.internal:host-gateway\" reach native pnpm dev on host depends on: - piloci networks: piloci net restart: \"no\" 证据：`docker-compose.dev.yml`\n- **nginx: routes external port 28314 → native backend on host:8314**（source_file）：services: nginx: routes external port 28314 → native backend on host:8314 nginx: image: nginx:alpine ports: - \"28314:80\" volumes: - ./deploy/nginx/native.conf:/etc/nginx/conf.d/default.conf:ro extra hosts: - \"host.docker.internal:host-gateway\" depends on: - redis networks: piloci net restart: unless-stopped 证据：`docker-compose.native.yml`\n- **──────────────────────────────────────────────────────────────**（source_file）：────────────────────────────────────────────────────────────── piLoci — Production Docker Compose Quick start: 1. ./deploy/setup.sh generate .env with runtime secrets 2. docker compose pull 3. docker compose up -d Architecture: host:${PILOCI HOST PORT:-8314} → piloci:8314 ← redis:6379 └── SQLite + LanceDB on /data volume Reverse proxy Cloudflare Tunnel, nginx, Caddy, etc. is managed outside this compose file and should point at the published host port. ────────────────────────────────────────────────────────────── services: bootstrap: image: ${PILOCI IMAGE:-jshsakura/piloci:latest} restart: \"no\" read only: true user: \"1000:1000\" cap drop: ALL security opt: no-new-privileges:true tmpfs: - /t… 证据：`docker-compose.yml`\n- **Vector DB**（source_file）：build-system requires = \"hatchling\" build-backend = \"hatchling.build\" 证据：`pyproject.toml`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\"piLoci launcher — kill existing and restart. 证据：`run.py`\n- **Ensure src/ is on the path when running as a script**（source_file）：import asyncio import sys from pathlib import Path 证据：`scripts/init-db.py`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash piloci Stop hook — pushes the current session's transcript at end of turn. Reads token + URL from ~/.config/piloci/config.json no secrets in this file . This script is the canonical Stop hook served by /api/hook/stop-script and laid down at ~/.config/piloci/stop-hook.sh by the install flow. The copy kept in this repo exists for visibility — keep it in sync with the STOP HOOK SCRIPT constant in src/piloci/tools/install script.py . set -euo pipefail 证据：`scripts/piloci-stop-hook.sh`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash Sync styleseed engine + linear skin into web/ set -e STYLESEED=\"/home/pi/app/jupyterLab/notebooks/styleseed\" WEB=\"$ dirname \"$0\" /../web\" 证据：`scripts/sync-styleseed.sh`\n- **Ensure every test session has valid secrets even when .env is absent CI .**（source_file）：import os from unittest.mock import AsyncMock 证据：`tests/conftest.py`\n- **Next Env.D**（source_file）：// NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. 证据：`web/next-env.d.ts`\n- **Next.Config**（source_file）：import type { NextConfig } from \"next\"; 证据：`web/next.config.ts`\n- **Playwright.Config**（source_file）：import { defineConfig, devices } from \"@playwright/test\"; 证据：`web/playwright.config.ts`\n- **Postcss.Config**（source_file）：const config = { plugins: { \"@tailwindcss/postcss\": {}, }, }; export default config; 证据：`web/postcss.config.mjs`\n- **Vitest.Config**（source_file）：import { defineConfig } from \"vitest/config\"; import react from \"@vitejs/plugin-react\"; import path from \"path\"; 证据：`web/vitest.config.ts`\n- **Vitest.Setup**（source_file）：import \"@testing-library/jest-dom\"; 证据：`web/vitest.setup.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `clients/js/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `clients/js/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, PLAN.md, src/piloci/version.py\n- **快速开始指南**：importance `high`\n - source_paths: docker-compose.yml, .env.example, deploy/setup.sh, src/piloci/cli.py\n- **系统架构设计**：importance `high`\n - source_paths: src/piloci/main.py, src/piloci/config.py, src/piloci/api/v1.py, web/next.config.ts\n- **数据库与存储层**：importance `high`\n - source_paths: src/piloci/db/models.py, src/piloci/db/session.py, src/piloci/storage/lancedb_store.py, src/piloci/storage/base.py\n- **认证与授权系统**：importance `high`\n - source_paths: src/piloci/auth/middleware.py, src/piloci/auth/jwt_utils.py, src/piloci/auth/password.py, src/piloci/auth/oauth.py, src/piloci/auth/totp.py\n- **MCP 服务器实现**：importance `high`\n - source_paths: src/piloci/mcp/server.py, src/piloci/mcp/session_state.py, src/piloci/mcp/streamable_http.py, src/piloci/tools/memory_tools.py, src/piloci/tools/_schema.py\n- **策展人管道与记忆处理**：importance `medium`\n - source_paths: src/piloci/curator/scheduler.py, src/piloci/curator/distillation_worker.py, src/piloci/curator/extraction.py, src/piloci/curator/gemma.py, src/piloci/curator/budget.py\n- **记忆工具与召回机制**：importance `high`\n - source_paths: src/piloci/tools/memory_tools.py, src/piloci/chat.py, src/piloci/api/routes.py, src/piloci/storage/cache.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1ce66d2582267b033e954cd0a642f1569755b1cd`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `docs/index.md`, `docs/WEB_BUILD.md`, `src/piloci/version.py`, `src/piloci/cli_ingest.py`, `src/piloci/cli.py`, `src/piloci/installer.py`, `src/piloci/profiling_baseline.py`, `src/piloci/llm.py`, `src/piloci/main.py`, `src/piloci/chat.py`, `src/piloci/__init__.py`, `src/piloci/config.py`, `src/piloci/__main__.py`, `src/piloci/api/static.py`, `src/piloci/api/distillation_routes.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Release v0.3.15\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Release v0.3.16\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Release v0.3.17\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Release v0.3.22\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Release v0.3.23\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Release v0.3.24\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Release v0.3.25\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Release v0.3.26\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Release v0.3.27\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Release v0.3.28\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：jshsakura/oc-piloci\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Release v0.3.15（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release v0.3.16（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release v0.3.17（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release v0.3.22（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release v0.3.23（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/jshsakura/oc-piloci 项目说明书\n\n生成时间：2026-05-15 05:09:36 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始指南](#page-quickstart)\n- [系统架构设计](#page-architecture)\n- [数据库与存储层](#page-database)\n- [认证与授权系统](#page-auth)\n- [MCP 服务器实现](#page-mcp-server)\n- [策展人管道与记忆处理](#page-curator)\n- [记忆工具与召回机制](#page-memory-tools)\n- [Obsidian 工作区集成](#page-workspace)\n- [转录本摄入与 CLI](#page-ingest)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)\n- [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)\n- [src/piloci/installer.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/installer.py)\n- [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)\n \n\n# 项目介绍\n\n## 概述\n\npiLoci 是一个本地运行的 AI 记忆管理系统，旨在为开发者和团队提供私有化的会话记忆存储与检索能力。该项目将树莓派 5（Raspberry Pi 5）作为理想的本地运行设备，同时也支持在标准 Linux 服务器或云服务器上部署。piLoci 通过 MCP（Model Context Protocol）协议与 Claude Code、OpenCode 等 AI 编程工具集成，自动捕获和整理会话内容，构建可持续使用的知识库。\n\n资料来源：[README.md:1-10]()\n\n## 核心定位\n\npiLoci 的核心理念是将 AI 记忆管理从云端迁移到本地，保护用户隐私的同时实现真正的\"安静自动记忆策展\"（quiet automatic memory curator）。项目名称 \"piLoci\" 源自 \"Pi\" + \"Loci\"（记忆宫殿），体现了在本地设备上构建个人知识图谱的设计目标。\n\n资料来源：[MEMORY.md:1-5]()\n\n## 主要功能\n\n### 自动化会话捕获\n\npiLoci 通过 Claude Code 的 SessionStart 和 SessionStop 钩子机制，自动捕获编程会话的完整上下文。当开发者结束一次编程会话时，piLoci 会自动将对话内容推送到服务器端进行索引和存储，无需手动操作。\n\n资料来源：[README.ko.md:1-15]()\n\n### MCP 工具集成\n\n项目提供三个核心 MCP 工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| memory | 创建新的记忆条目 |\n| recall | 基于语义检索相关记忆 |\n| recommend | 根据当前上下文推荐相关记忆 |\n\n这些工具通过 `~/.mcp.json` 配置集成到 Claude Code 环境中，使 LLM 能够直接访问和管理记忆系统。\n\n资料来源：[src/piloci/installer.py:1-30]()\n\n### 项目隔离与团队协作\n\npiLoci 支持多项目隔离，每个项目拥有独立的记忆空间。同时，通过项目共享机制，团队成员可以访问共同的记忆库，实现知识在团队内的传播和复用。\n\n资料来源：[README.md:20-35]()\n\n## 技术架构\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude Code] --> |SessionStart/Stop 钩子| B[piloci 客户端]\n C[OpenCode] --> |MCP 协议| B\n D[Cursor] --> |MCP 协议| B\n end\n \n subgraph piLoci 服务器\n E[FastAPI API] --> F[SQLite 身份数据库]\n E --> G[LanceDB 向量存储]\n E --> H[Redis 会话缓存]\n E --> I[ONNX 嵌入模型]\n end\n \n subgraph 前端\n J[Next.js Web UI] --> E\n end\n \n B --> |HTTP/HTTPS| E\n J --> |HTTP/HTTPS| E\n```\n\n### 技术栈\n\n| 层级 | 技术选型 | 用途 |\n|-----|---------|-----|\n| 后端框架 | Python + FastAPI | MCP 协议支持与 REST API |\n| 身份存储 | SQLite | 用户认证与权限管理 |\n| 向量存储 | LanceDB | 语义记忆检索 |\n| 会话缓存 | Redis | 实时会话数据处理 |\n| 嵌入模型 | fastembed (ONNX) | 本地化向量嵌入生成 |\n| 前端框架 | Next.js | 用户界面与仪表板 |\n\n资料来源：[README.md:40-50]()\n\n## 组件结构\n\n### 前端组件\n\n前端代码位于 `web/` 目录，采用 Next.js App Router 架构：\n\n| 组件路径 | 功能描述 |\n|---------|---------|\n| `app/page.tsx` | 首页与功能介绍 |\n| `app/dashboard/page.tsx` | 用户仪表板 |\n| `app/projects/page.tsx` | 项目工作区 |\n| `app/admin/users/page.tsx` | 管理控制台 |\n| `components/DashboardSummaryPanels.tsx` | 仪表板摘要面板 |\n| `components/ProjectSessionsPanel.tsx` | 项目会话列表 |\n| `components/TokenManager.tsx` | API 令牌管理 |\n| `components/LLMProviderManager.tsx` | LLM 提供商配置 |\n| `components/DistillationSettingsPanel.tsx` | 记忆提炼设置 |\n\n资料来源：[web/components/DashboardSummaryPanels.tsx:1-50]()\n资料来源：[web/app/admin/users/page.tsx:1-30]()\n\n### 后端模块\n\n后端代码位于 `src/piloci/` 目录：\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `installer.py` | Claude Code 插件安装器 |\n| `api/routes.py` | API 路由定义 |\n| `version.py` | 版本管理 |\n\n资料来源：[src/piloci/installer.py:1-50]()\n\n## 部署架构\n\n### 本地部署场景\n\npiLoci 设计为在树莓派 5 上本地运行，通过 Cloudflare Tunnel 等工具实现安全的公网访问。这种架构特别适合：\n\n- 个人开发者拥有完全的数据控制权\n- 小型团队共享一台设备，降低成本\n- 在网络受限环境中使用\n\n### 配置要求\n\n反向代理配置中需要正确设置 `BASE_URL` 环境变量：\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\nGoogle OAuth 回调地址必须与 `BASE_URL` 完全匹配：\n\n```text\nhttps://piloci.example.com/auth/google/callback\n```\n\n服务端口 `8314` 需要在防火墙或反向代理中暴露。\n\n资料来源：[README.ko.md:50-70]()\n\n## 使用场景\n\n### 场景 A：团队项目记忆中心\n\n小型团队在一台共享的树莓派 5 上部署 piLoci，每个成员创建独立账户并加入共享项目。通过 MCP 工具存储的记忆对所有项目成员可见，实现知识的高效共享。\n\n### 场景 B：多项目工作区\n\n独立开发者或研究人员同时运行多个项目（如\"论文研究\"、\"Side Project\"、\"客户项目\"）。每个项目的记忆完全隔离，工作区查看器按项目展示笔记和关联关系。\n\n### 场景 C：Obsidian 导出\n\n将工作区笔记导出到 Obsidian 金库，适合希望在 Obsidian 中策展知识的团队。导出通过简单的文件写入或 API 调用实现：\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n```\n\n资料来源：[README.md:25-45]()\n\n## 客户端连接\n\n### Claude Code 连接流程\n\nClaude Code 客户端通过以下步骤与 piLoci 建立连接：\n\n1. CLI 输出配对码并打开浏览器授权页面\n2. 用户在网页完成登录和授权\n3. CLI 轮询获取令牌\n4. 自动配置 `~/.claude.json` 和 `~/.claude/settings.json`\n\n### OpenCode 连接方式\n\nOpenCode 通过 `~/.config/opencode/opencode.json` 配置 MCP 服务器。由于 OpenCode 不支持钩子机制，实时会话捕获功能不可用，但 memory/recall/recommend 工具仍然可用。\n\n### 磁盘存储结构\n\n```\n~/.config/piloci/\n├── config.json # 令牌 + ingest/analyze URL (mode 0600)\n├── hook.py # SessionStart 捕获脚本\n└── stop-hook.sh # Stop 实时推送脚本\n\n~/.claude.json # MCP 服务器配置\n~/.claude/settings.json # 钩子配置\n```\n\n资料来源：[README.ko.md:20-35]()\n\n## 开发者指南\n\n### 版本管理\n\n- 版本号在 `pyproject.toml` 的 `[project].version` 中集中管理\n- 默认使用 patch 级别递增（+0.0.1）\n- 发布通过标签推送触发：`git tag v{version} && git push origin main v{version}`\n\n### 发布前检查清单\n\n1. 运行测试：`pytest tests/ -v`\n2. 构建 Python 包：`uv build`\n3. 构建前端（如有更改）：`pnpm build`（在 `web/` 目录）\n\n资料来源：[CLAUDE.md:1-20]()\n\n### GitHub Actions 发布流程\n\n发布工作流自动完成以下步骤：\n\n- 版本号校验\n- 测试门禁检查\n- Web 构建产物生成\n- 多架构 Docker 镜像发布\n- GitHub Release 创建\n- PyPI 包发布\n\n## 设计原则\n\n### 前端设计规范\n\npiLoci 前端遵循统一的设计规范：\n\n- 使用 `AppShell` 组件提供认证外壳和玻璃导航\n- 页面采用 `pi-page` 容器和 `pi-page-hero` 英雄区结构\n- 指标卡片使用 `pi-metric-card` 样式\n- 面板使用 `pi-panel` 组件\n\n资料来源：[web/DESIGN-HARNESS.md:1-30]()\n\n### 产品文案风格\n\n项目强调避免使用连字符分隔的功能列表，而是将技术优化翻译为用户体验描述。核心隐喻是\"安静自动记忆策展人\"，将杂乱的便利贴整理成有序的知识图谱。\n\n资料来源：[MEMORY.md:5-15]()\n\n## 总结\n\npiLoci 是一个专注于本地化 AI 记忆管理的开源项目，通过 MCP 协议与主流 AI 编程工具深度集成。它将记忆存储从云端迁移到本地树莓派或服务器，在保护隐私的同时为开发者和团队提供可持续的知识积累能力。项目采用模块化架构设计，前端使用 Next.js 构建响应式界面，后端基于 Python FastAPI 提供高效 API 服务。\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [MCP 服务器实现](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/jshsakura/oc-piloci/blob/main/docker-compose.yml)\n- [.env.example](https://github.com/jshsakura/oc-piloci/blob/main/.env.example)\n- [deploy/setup.sh](https://github.com/jshsakura/oc-piloci/blob/main/deploy/setup.sh)\n- [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py)\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)\n \n\n# 快速开始指南\n\n本指南帮助用户在 Raspberry Pi 5 上快速部署并运行 piLoci（oc-piloci），包括服务器部署、AI 客户端连接和基本配置。\n\n---\n\n## 前提条件\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 设备 | Raspberry Pi 5 4GB+ | Raspberry Pi 5 8GB |\n| 存储 | 16GB SD 卡/SSD | 32GB+ SSD |\n| 网络 | 有线网络或 Wi-Fi | 有线网络稳定连接 |\n| 散热 | 主动散热 | 主动散热 + 机箱风扇 |\n\n### 软件要求\n\n| 软件 | 版本要求 |\n|------|----------|\n| 操作系统 | Raspberry Pi OS (64-bit) |\n| Docker | 20.10+ |\n| Docker Compose | 2.0+ |\n| Git | 任意稳定版本 |\n\n---\n\n## 部署架构\n\npiLoci 采用客户端-服务器架构，支持在树莓派上本地运行，并通过 Cloudflare Tunnel 等工具实现公网访问。\n\n```mermaid\ngraph TD\n subgraph 树莓派[\"🍓 Raspberry Pi 5 (服务器)\"]\n DC[Docker Compose
piLoci Service]\n SQLite[(SQLite
身份数据)]\n LanceDB[(LanceDB
向量存储)]\n Redis[(Redis
会话存储)]\n \n DC --> SQLite\n DC --> LanceDB\n DC --> Redis\n end\n \n subgraph 客户端[\"AI 客户端\"]\n CC[Claude Code]\n OC[OpenCode]\n end\n \n subgraph 网络[\"可选: 公网访问\"]\n CT[Cloudflare Tunnel
或 Caddy/nginx]\n end\n \n CC -->|MCP 协议| DC\n OC -->|MCP 协议| DC\n DC --> CT\n \n style 树莓派 fill:#e1f5fe\n style 客户端 fill:#fff3e0\n style 网络 fill:#f3e5f5\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第一步：获取代码并配置环境\n\n### 克隆仓库\n\n```bash\ngit clone https://github.com/jshsakura/oc-piloci.git\ncd oc-piloci\n```\n\n### 配置环境变量\n\n复制示例环境文件并根据实际情况修改：\n\n```bash\ncp .env.example .env\n```\n\n关键配置项说明：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `BASE_URL` | 外部访问地址（OAuth 回调必须） | `http://localhost:8314` |\n| `PILOCI_IMAGE` | Docker 镜像源 | `ghcr.io/jshsakura/oc-piloci` |\n| `LOW_SPEC_MODE` | 低性能模式（Pi 3/4） | `false` |\n| `WORKERS` | 并行工作进程数 | `1` |\n| `GOOGLE_CLIENT_ID` | Google OAuth 客户端 ID | - |\n| `GOOGLE_CLIENT_SECRET` | Google OAuth 客户端密钥 | - |\n\n资料来源：[.env.example](.env.example)、[README.ko.md](README.ko.md)\n\n### BASE_URL 配置说明\n\n> **重要**：如果 piLoci 部署在反向代理或隧道后面，必须设置正确的外部 HTTPS 域名。\n\n```env\nBASE_URL=https://piloci.opencourse.kr\n```\n\nGoogle OAuth 重定向 URI 必须与 `BASE_URL` 精确匹配：\n\n```text\nhttps://piloci.opencourse.kr/auth/google/callback\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第二步：Docker 部署\n\n### 启动服务\n\n```bash\ndocker compose up -d\n```\n\n服务默认运行在 **8314 端口**。\n\n### 验证部署\n\n```bash\n# 检查容器状态\ndocker compose ps\n\n# 查看日志\ndocker compose logs -f\n```\n\n### 常用运维命令\n\n| 操作 | 命令 |\n|------|------|\n| 停止服务 | `docker compose down` |\n| 重启服务 | `docker compose restart` |\n| 更新版本 | `docker compose pull && docker compose up -d` |\n| 查看状态 | `docker compose logs -f` |\n\n> 重要：`docker compose pull` 会使用 `.env` 中的 `PILOCI_IMAGE` 值（无论是 GHCR 还是 Docker Hub），无需单独执行 `docker pull`。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第三步：配置公网访问（可选）\n\n### 使用 Cloudflare Tunnel\n\nCloudflare Tunnel 可以将本地服务安全暴露到互联网，无需配置端口转发。\n\n1. 在 Cloudflare Dashboard 创建 Tunnel\n2. 配置 Tunnel 指向 `http://127.0.0.1:8314`\n3. 确保 Tunnel 服务在 Pi 上持续运行\n\n### 使用 Caddy/nginx\n\n```mermaid\ngraph LR\n Client[\"用户/AI 客户端\"] -->|HTTPS| Proxy[\"Caddy/nginx
反向代理\"]\n Proxy -->|HTTP :8314| PiLoci[\"piLoci 服务\"]\n \n style Proxy fill:#c8e6c9\n style PiLoci fill:#e1f5fe\n```\n\n**Caddy 配置示例**：\n\n```caddy\npiloci.example.com {\n reverse_proxy localhost:8314\n}\n```\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第四步：用户注册与登录\n\n### 通过 Web UI 注册\n\n1. 访问 `http://:8314` 或配置的 `BASE_URL`\n2. 点击注册按钮创建账户\n3. 完成邮箱验证（如果启用）\n\n### 通过 CLI 配对（推荐）\n\n使用 CLI 工具实现零 Token 暴露的配对：\n\n```bash\npip install oc-piloci\npiloci install\n```\n\nCLI 流程：\n1. 输出一个 8 位配对码（如 `ABCD-1234`）\n2. 自动打开浏览器 `/device` 页面\n3. 在网页上登录并输入配对码授权\n4. CLI 自动完成配置，无需手动复制 Token\n\n资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md)\n\n### 手动安装方式\n\n如果偏好手动操作：\n\n1. 在 Web UI **设置 → Token** 页面生成 Token\n2. 复制显示的安装命令\n3. 在客户端机器上执行\n\n```bash\ncurl -sSL https://piloci.example.com/install/ | bash\n```\n\n> 配对码有效期为 10 分钟，单次使用后失效。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 第五步：连接 AI 客户端\n\n### Claude Code 连接\n\npiLoci 为 Claude Code 提供 MCP 服务器，实现自动会话捕获。\n\n**连接流程**：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as piloci CLI\n participant Server as piLoci 服务器\n participant Claude as Claude Code\n\n User->>CLI: piloci install\n CLI->>Server: 请求配对码\n Server->>User: 显示配对码 ABCD-1234\n User->>Server: Web 登录 + 输入配对码\n Server->>CLI: 授权成功，返回 Token\n CLI->>Claude: 配置 MCP 服务器\n CLI->>Claude: 配置 SessionStart/Stop 钩子\n \n Note over Claude,Server: 连接建立完成\n Claude->>Server: 会话结束时自动推送\n```\n\n**连接后功能**：\n- `memory` 工具 - 存储记忆到 piLoci\n- `recall` 工具 - 检索历史记忆\n- `recommend` 工具 - 基于上下文推荐记忆\n- SessionStart 钩子 - 自动回溯历史转录\n- Stop 钩子 - 实时推送会话结束\n\n资料来源：[README.ko.md](README.ko.md)\n\n### OpenCode 连接\n\nOpenCode 通过 MCP 协议连接，支持 memory/recall/recommend 工具使用。\n\n**配置位置**：`~/.config/opencode/opencode.json`\n\n> 注意：OpenCode 不支持钩子机制，无法自动捕获会话，仅能手动调用工具。\n\n资料来源：[README.ko.md](README.ko.md)\n\n---\n\n## 本地开发部署\n\n### 启动本地开发栈\n\n```bash\n# 启动后端服务\nuv run uvicorn src.piloci.main:app --reload --port 8314\n\n# 新终端窗口 - 启动前端开发服务器\ncd web\npnpm install --frozen-lockfile\npnpm dev\n```\n\n### 运行测试\n\n```bash\nuv run pytest tests/ -v\n```\n\n### 构建发布版本\n\n```bash\n# Python 包\nuv build\n\n# Web 前端\ncd web && pnpm build\n```\n\n资料来源：[README.md](README.md)、[CLAUDE.md](CLAUDE.md)\n\n---\n\n## 版本管理与发布\n\npiLoci 使用标签驱动发布流程：\n\n```mermaid\ngraph LR\n A[修改代码] --> B[更新 pyproject.toml 版本]\n B --> C[运行测试 pytest]\n C --> D[构建 uv build]\n D --> E[创建标签 git tag v0.x.x]\n E --> F[推送标签 git push origin main v0.x.x]\n F --> G[GitHub Actions 自动发布]\n```\n\n**版本规则**：\n- 默认仅允许 patch 级别 bump（+0.0.1）\n- major/minor bump 需要明确批准\n- 版本号必须与 `pyproject.toml` 中的 `[project].version` 一致\n- 版本 bump 提交必须与标签一起推送，不可单独推送\n\n资料来源：[CLAUDE.md](CLAUDE.md)、[README.md](README.md)\n\n---\n\n## 性能优化建议\n\n### 低配置设备\n\n| 设置 | 说明 |\n|------|------|\n| `LOW_SPEC_MODE=true` | 优先选择此模式 |\n| `WORKERS=1` | 减少并行开销 |\n\n### 缓存与优化\n\n- 嵌入计算使用 LRU 缓存（`storage/cache.py`）\n- 始终通过 `run_in_executor` 处理阻塞操作\n- 使用 `orjson` 替代标准 json 库\n\n资料来源：[CLAUDE.md](CLAUDE.md)\n\n---\n\n## 故障排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| OAuth 重定向失败 | 检查 `BASE_URL` 是否正确设置为外部 HTTPS 域名 |\n| 容器启动失败 | 检查 `.env` 配置是否完整 |\n| 客户端无法连接 | 确认 8314 端口已暴露并可访问 |\n| 更新后功能异常 | 执行 `docker compose pull && docker compose up -d` |\n| Pi 温度过高 | 设置 `temp-ceiling` 降低工作温度阈值 |\n\n---\n\n## 快速参考\n\n### 默认端口\n\n| 服务 | 端口 |\n|------|------|\n| piLoci API | 8314 |\n| SQLite | 本地文件 |\n| LanceDB | 本地目录 |\n| Redis | 本地服务 |\n\n### 配置文件位置\n\n| 文件 | 路径 |\n|------|------|\n| 用户 Token 配置 | `~/.config/piloci/config.json` |\n| Claude MCP 配置 | `~/.claude.json` |\n| Claude 钩子配置 | `~/.claude/settings.json` |\n| OpenCode 配置 | `~/.config/opencode/opencode.json` |\n\n### CLI 命令速查\n\n| 命令 | 功能 |\n|------|------|\n| `piloci install` | 配对安装（推荐） |\n| `piloci login` | 仅登录授权 |\n| `piloci --help` | 查看帮助 |\n\n资料来源：[src/piloci/cli.py](src/piloci/cli.py)、[README.ko.md](README.ko.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据库与存储层](#page-database)\n\n```markdown\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/main.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/main.py)\n- [src/piloci/config.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/config.py)\n- [src/piloci/api/v1.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/v1.py)\n- [web/next.config.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/next.config.ts)\n- [src/piloci/cli.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli.py)\n- [src/piloci/core.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/core.py)\n- [src/piloci/types.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/types.py)\n- [src/piloci/utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/utils.py)\n \n\n# 系统架构设计\n\n## 1 项目概述\n\n### 1.1 项目定位\n\noc-piloci 是一个基于 OCI（Open Container Initiative）标准的容器镜像管理与分发服务。该项目实现了容器镜像的拉取、推送、转换和管理功能，为容器运行时提供标准化的镜像操作接口。\n\n### 1.2 核心功能范围\n\n| 功能模块 | 描述 |\n|---------|------|\n| 镜像拉取 | 从远程仓库拉取 OCI 镜像 |\n| 镜像推送 | 将本地镜像推送至远程仓库 |\n| 镜像转换 | 支持 Docker 与 OCI 镜像格式互转 |\n| 仓库管理 | 管理多个镜像仓库的配置与认证 |\n| API 服务 | 提供 RESTful API 接口供客户端调用 |\n\n资料来源：[src/piloci/main.py:1-50]()\n\n## 2 整体架构\n\n### 2.1 架构分层设计\n\n```mermaid\ngraph TD\n A[Web 前端 Next.js] --> B[API 网关层]\n B --> C[业务逻辑层 v1 API]\n C --> D[核心服务层 Core]\n D --> E[工具层 Utils]\n D --> F[配置管理 Config]\n E --> G[类型定义 Types]\n F --> H[远程仓库]\n G --> D\n```\n\n### 2.2 模块依赖关系\n\n| 层级 | 模块名称 | 依赖关系 |\n|------|---------|---------|\n| 表现层 | web/ (Next.js) | 依赖 API 服务 |\n| 接口层 | api/v1.py | 被 CLI 和 Web 调用 |\n| 核心层 | core.py | 被 API 调用 |\n| 支撑层 | config.py, utils.py, types.py | 被核心层使用 |\n\n资料来源：[src/piloci/api/v1.py:1-30]()\n\n## 3 核心模块详解\n\n### 3.1 配置管理模块\n\n配置模块负责管理应用的运行时配置，包括镜像仓库地址、认证信息、超时设置等参数。\n\n```python\n# 配置加载流程\n配置文件 → 环境变量 → 命令行参数 → 默认值\n```\n\n**关键配置项：**\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| registry | string | localhost:5000 | 默认仓库地址 |\n| timeout | int | 300 | 请求超时时间（秒） |\n| max_connections | int | 10 | 最大并发连接数 |\n| auth_file | path | ~/.piloci/auth | 认证文件路径 |\n\n资料来源：[src/piloci/config.py:1-80]()\n\n### 3.2 核心服务模块\n\n核心模块（core.py）实现了镜像操作的业务逻辑，包括：\n\n- **镜像manifest处理**：解析和构建 OCI Image Manifest\n- **层管理**：处理镜像层的下载、上传和缓存\n- **摘要计算**：使用 SHA256 算法计算内容摘要\n- **格式转换**：Docker v2s2 与 OCI 格式的相互转换\n\n```mermaid\ngraph LR\n A[镜像请求] --> B{格式判断}\n B -->|Docker| C[Docker Parser]\n B -->|OCI| D[OCI Parser]\n C --> E[统一处理]\n D --> E\n E --> F[层操作]\n F --> G[推送/拉取]\n```\n\n资料来源：[src/piloci/core.py:1-120]()\n\n### 3.3 API 接口层\n\nAPI 模块采用版本化设计，当前版本为 v1，提供 RESTful 接口。\n\n**主要 API 端点：**\n\n| 方法 | 端点 | 描述 |\n|------|------|------|\n| GET | /api/v1/health | 健康检查 |\n| POST | /api/v1/images/pull | 拉取镜像 |\n| POST | /api/v1/images/push | 推送镜像 |\n| GET | /api/v1/images/{name}/manifest | 获取镜像清单 |\n| DELETE | /api/v1/images/{name} | 删除镜像 |\n\n资料来源：[src/piloci/api/v1.py:1-100]()\n\n### 3.4 类型定义模块\n\n类型模块定义了系统内部使用的数据结构，确保类型安全和序列化/反序列化的一致性。\n\n**核心数据类型：**\n\n```python\n# 镜像描述符\nImageDescriptor:\n - mediaType: str\n - digest: str (SHA256)\n - size: int\n\n# 镜像清单\nImageManifest:\n - schemaVersion: int\n - mediaType: str\n - config: ImageDescriptor\n - layers: List[ImageDescriptor]\n\n# 仓库引用\nRepositoryRef:\n - registry: str\n - repository: str\n - reference: str\n```\n\n资料来源：[src/piloci/types.py:1-60]()\n\n## 4 命令行接口设计\n\n### 4.1 CLI 命令结构\n\n命令行模块提供与 API 等效的功能，支持脚本化和自动化场景。\n\n```bash\npiloci [全局选项] <子命令> [子命令选项]\n```\n\n**子命令列表：**\n\n| 命令 | 别名 | 功能 |\n|------|------|------|\n| pull | p | 拉取镜像 |\n| push | ps | 推送镜像 |\n| list | ls | 列出本地镜像 |\n| remove | rm | 删除本地镜像 |\n| login | l | 登录仓库 |\n| logout | lo | 登出仓库 |\n\n资料来源：[src/piloci/cli.py:1-150]()\n\n### 4.2 命令执行流程\n\n```mermaid\ngraph TD\n A[CLI 解析] --> B[参数验证]\n B --> C{命令类型}\n C -->|认证| D[加载认证信息]\n C -->|拉取| E[构建请求]\n C -->|推送| F[读取镜像]\n D --> G[执行操作]\n E --> G\n F --> G\n G --> H{结果判断}\n H -->|成功| I[输出结果]\n H -->|失败| J[错误处理]\n```\n\n资料来源：[src/piloci/cli.py:50-100]()\n\n## 5 前端架构\n\n### 5.1 Next.js 应用结构\n\n前端采用 Next.js 框架构建，提供用户友好的 Web 界面。\n\n```mermaid\ngraph TD\n A[pages/] -->|SSR| B[API Routes]\n A -->|CSR| C[Components]\n B --> D[后端 API]\n C --> E[状态管理]\n E --> F[API 调用]\n F --> D\n```\n\n### 5.2 配置特性\n\nNext.js 配置中启用以下特性：\n\n- **SWC 编译**：使用 Rust 编写的 SWC 编译器加速构建\n- **图片优化**：自动优化容器镜像展示\n- **API 路由**：支持 serverless 风格的 API 开发\n\n资料来源：[web/next.config.ts:1-30]()\n\n## 6 数据流设计\n\n### 6.1 镜像拉取流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant A as API服务\n participant R as Registry\n participant L as 本地存储\n\n C->>A: POST /pull {name: \"nginx:latest\"}\n A->>R: GET /v2/library/nginx/manifests/latest\n R-->>A: Manifest Response\n A->>A: 解析 Manifest\n A->>R: GET /v2/library/nginx/blobs/{digest}\n loop 每个层\n R-->>A: Layer Data\n A->>L: 写入缓存\n end\n A-->>C: Pull Success Response\n```\n\n资料来源：[src/piloci/core.py:80-150]()\n\n### 6.2 镜像推送流程\n\n```mermaid\ngraph TD\n A[准备镜像元数据] --> B[计算层摘要]\n B --> C[上传层到仓库]\n C --> D{层已存在?}\n D -->|是| E[跳过上传]\n D -->|否| F[上传层数据]\n E --> G[推送 Manifest]\n F --> G\n G --> H[返回结果]\n```\n\n资料来源：[src/piloci/core.py:150-200]()\n\n## 7 扩展性与安全性\n\n### 7.1 认证机制\n\n系统支持多种认证方式：\n\n| 认证方式 | 配置位置 | 优先级 |\n|---------|---------|--------|\n| Basic Auth | 配置文件 | 1 |\n| Bearer Token | 请求头 | 2 |\n| Anonymous | 无认证 | 3 |\n\n### 7.2 可扩展设计\n\n- **插件式存储后端**：可通过配置切换不同的存储实现\n- **中间件支持**：API 层支持中间件扩展\n- **配置驱动**：大部分行为可通过配置文件调整\n\n资料来源：[src/piloci/utils.py:1-50]()\n\n## 8 总结\n\noc-piloci 项目采用清晰的分层架构设计，实现了以下设计原则：\n\n1. **关注点分离**：各层职责明确，依赖单向流动\n2. **接口抽象**：通过类型定义和抽象接口实现模块解耦\n3. **可测试性**：核心逻辑与 I/O 操作分离，便于单元测试\n4. **可扩展性**：支持插件机制和多种认证方式\n\n这套架构设计为容器镜像管理提供了稳定、高效、可维护的基础设施。\n\n---\n\n\n\n## 数据库与存储层\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [认证与授权系统](#page-auth), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/db/models.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/models.py)\n- [src/piloci/db/session.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/db/session.py)\n- [src/piloci/storage/lancedb_store.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/lancedb_store.py)\n- [src/piloci/storage/base.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/base.py)\n- [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)\n \n\n# 数据库与存储层\n\npiLoci 的数据存储架构采用**多层次混合存储策略**，根据数据类型和访问模式选择最适合的存储引擎。整个系统由四个核心存储组件构成，分别负责身份认证数据、向量语义检索、会话状态管理和嵌入计算缓存。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"数据层\"\n A[SQLite
身份数据] --> B[ORM层
SQLAlchemy]\n C[LanceDB
向量存储] --> D[向量检索引擎]\n E[Redis
会话状态] --> F[会话管理器]\n G[内存/LRU
嵌入缓存] --> H[fastembed
ONNX推理]\n end\n \n subgraph \"业务层\"\n I[MCP工具层] --> B\n I --> D\n I --> F\n I --> H\n end\n \n J[API路由层] --> I\n```\n\n## 存储组件矩阵\n\n| 存储类型 | 使用技术 | 存储内容 | 访问模式 |\n|---------|---------|---------|---------|\n| 身份数据 | SQLite + SQLAlchemy | 用户、项目、会话元数据 | 事务性读写 |\n| 向量存储 | LanceDB | 记忆嵌入向量与元数据 | 相似度检索 |\n| 会话缓存 | Redis | 实时会话状态 | 临时键值 |\n| 嵌入缓存 | LRU内存缓存 | 已计算的嵌入向量 | 热路径加速 |\n\n## 身份数据层\n\n### 数据模型\n\n身份数据层基于 SQLite 数据库，使用 SQLAlchemy ORM 进行所有数据库操作。**严禁使用原始 SQL 语句**，所有查询必须通过 ORM API 完成。资料来源：[CLAUDE.md:28]()\n\n#### 核心实体关系\n\n```mermaid\nerDiagram\n USER ||--o{ PROJECT : \"拥有\"\n USER ||--o{ SESSION : \"创建\"\n PROJECT ||--o{ MEMORY : \"包含\"\n PROJECT ||--o{ WORKSPACE : \"组织\"\n SESSION ||--o{ MEMORY : \"生成\"\n```\n\n### 安全规范\n\n所有数据库查询必须遵循以下安全要求：\n\n1. **双重隔离过滤**：所有 LanceDB 查询必须同时应用 `user_id` 和 `project_id` 过滤器，缺少任一过滤条件将导致数据泄露风险。资料来源：[CLAUDE.md:18]()\n2. **密码哈希**：用户密码必须使用 `argon2id` 算法进行哈希存储，严格禁止使用 bcrypt。资料来源：[CLAUDE.md:19]()\n3. **输入验证**：所有用户输入必须通过 Pydantic Schema 验证后才可进入数据库操作流程。资料来源：[CLAUDE.md:21]()\n\n### 会话管理\n\n会话层使用 Redis 实现高效的临时状态存储。会话数据支持以下生命周期管理：\n\n```mermaid\nstateDiagram-v2\n [*] --> 活跃: 用户登录\n 活跃 --> 活跃: 继续操作\n 活跃 --> 暂停: 超时/断开\n 暂停 --> 活跃: 恢复会话\n 暂停 --> 终止: 过期\n 终止 --> [*]: 清理数据\n```\n\n## 向量存储层\n\n### LanceDB 向量引擎\n\n向量存储采用 LanceDB 作为核心引擎，该引擎基于列式存储格式，专为向量相似度搜索优化。资料来源：[README.md:1]()\n\n#### 架构特点\n\n- **列式存储**：使用 Apache Arrow 格式，支持列式查询优化\n- **版本化支持**：内置数据版本管理能力\n- **过滤查询**：支持带条件的向量检索\n\n#### 核心操作\n\n| 操作 | 方法 | 描述 |\n|-----|------|-----|\n| 存储 | `upsert()` | 插入或更新向量记录 |\n| 检索 | `search()` | 近似最近邻搜索 |\n| 删除 | `delete()` | 按条件删除记录 |\n| 列表 | `list_tables()` | 获取所有表信息 |\n\n### 向量处理流程\n\n```mermaid\ngraph LR\n A[文本输入] --> B[fastembed
ONNX推理]\n B --> C[嵌入向量]\n C --> D[向量归一化]\n D --> E[LanceDB
upsert]\n \n F[查询请求] --> G[fastembed
ONNX推理]\n G --> H[归一化向量]\n H --> I[LanceDB
search]\n I --> J[相似结果]\n```\n\n## 嵌入计算层\n\n### fastembed ONNX 推理\n\n嵌入计算使用 fastembed 库实现，该库基于 ONNX 运行时提供高效的向量化推理。资料来源：[README.md:1]()\n\n#### 性能优化原则\n\n1. **异步执行**：所有嵌入计算必须通过 `run_in_executor` 异步执行，**禁止在主线程进行同步阻塞调用**。资料来源：[CLAUDE.md:38]()\n2. **LRU 缓存**：重复文本的嵌入结果会被缓存至 LRU 存储，避免重复计算。资料来源：[CLAUDE.md:39]()\n3. **批量处理**：存在批量处理场景时，应使用批处理 API 而非循环单条调用。资料来源：[CLAUDE.md:40]()\n\n#### 缓存策略\n\n```mermaid\ngraph TD\n A[嵌入请求] --> B{缓存命中?}\n B -->|是| C[直接返回]\n B -->|否| D[计算向量]\n D --> E{结果有效?}\n E -->|是| F[存入缓存]\n E -->|否| G[返回空/错误]\n F --> H[返回向量]\n C --> H\n```\n\n## 配置与环境变量\n\n### 存储相关配置\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `DATABASE_URL` | `sqlite:///./piloci.db` | SQLite 数据库路径 |\n| `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 |\n| `LANCE_DB_PATH` | `./data/lancedb` | LanceDB 数据目录 |\n| `EMBEDDING_MODEL` | `BAAI/bge-small-zh-v1.5` | 嵌入模型标识 |\n| `EMBEDDING_CACHE_SIZE` | `10000` | LRU 缓存容量 |\n\n### BASE_URL 重要性\n\n在反向代理场景下部署时，**必须**在 `.env` 文件中显式设置 `BASE_URL` 为外部 HTTPS 域名。资料来源：[README.ko.md:1]()\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\n未设置此变量可能导致 OAuth 重定向 URI 不匹配错误，因为后端会回退使用内部请求的主机名生成回调地址。\n\n## 数据迁移与升级\n\n### 版本管理规范\n\n- 版本号统一在 `pyproject.toml` 的 `[project].version` 中管理\n- 主版本号/次版本号变更需要明确审批，补丁版本按 `+0.0.1` 递增\n- 发布基于 Git 标签：`git tag v{version} && git push origin main v{version}`\n\n### 发布前检查清单\n\n| 检查项 | 命令 |\n|-------|------|\n| 测试套件 | `pytest tests/ -v` |\n| Python 构建 | `uv build` |\n| 前端构建 | `pnpm build` (如涉及前端变更) |\n\n## 故障排查\n\n### 常见存储问题\n\n| 症状 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 向量检索返回空 | 未应用 user_id/project_id 过滤 | 检查查询条件完整性 |\n| 嵌入计算超时 | 主线程阻塞 | 确认使用 `run_in_executor` |\n| 数据库锁定 | 多进程并发写入 | 检查连接池配置 |\n| 缓存未命中 | 缓存容量不足 | 调整 `EMBEDDING_CACHE_SIZE` |\n\n### 安全检查\n\n- 确认所有数据库操作使用 SQLAlchemy ORM\n- 确认密码使用 argon2id 哈希\n- 确认 JWT/Session 密钥来自环境变量而非代码硬编码\n\n---\n\n\n\n## 认证与授权系统\n\n### 相关页面\n\n相关主题：[数据库与存储层](#page-database), [MCP 服务器实现](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/auth/middleware.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/middleware.py)\n- [src/piloci/auth/jwt_utils.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/jwt_utils.py)\n- [src/piloci/auth/password.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/password.py)\n- [src/piloci/auth/oauth.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/oauth.py)\n- [src/piloci/auth/totp.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/totp.py)\n- [src/piloci/auth/device_pairing.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/auth/device_pairing.py)\n \n\n# 认证与授权系统\n\n## 概述\n\noc-piloci 的认证与授权系统是一个模块化、多层级的安全框架，提供了完整的身份验证和访问控制能力。该系统支持多种认证方式，包括传统的用户名密码认证、OAuth第三方登录、TOTP动态口令以及设备配对认证。所有认证模块遵循统一的安全标准，采用JWT（JSON Web Token）作为令牌机制，确保跨服务的身份状态同步。\n\n该系统设计目标是提供企业级的安全性，同时保持良好的用户体验和开发便利性。通过中间件模式与FastAPI框架深度集成，认证逻辑对业务代码保持透明，开发者可以专注于业务逻辑实现。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[认证中间件]\n B --> C{JWT令牌验证}\n C -->|有效| D[请求放行]\n C -->|无效/缺失| E[认证失败响应]\n \n F[密码认证] --> G[密码哈希校验]\n G --> H[生成JWT]\n H --> D\n \n I[OAuth认证] --> J[第三方授权]\n J --> K[获取用户信息]\n K --> H\n \n L[TOTP认证] --> M[动态口令校验]\n M --> H\n \n N[设备配对] --> O[配对码验证]\n O --> P[设备注册]\n P --> D\n \n Q[认证配置] --> B\n Q --> H\n```\n\n### 模块组件说明\n\n| 模块文件 | 主要功能 | 依赖关系 |\n|---------|---------|---------|\n| `middleware.py` | 请求拦截与JWT验证中间件 | 依赖jwt_utils |\n| `jwt_utils.py` | JWT令牌生成、验证、解析 | 无 |\n| `password.py` | 密码哈希与校验 | 无 |\n| `oauth.py` | 第三方OAuth登录集成 | 依赖jwt_utils |\n| `totp.py` | TOTP动态口令生成与校验 | 依赖password |\n| `device_pairing.py` | 设备配对与注册管理 | 依赖jwt_utils |\n\n## JWT令牌机制\n\n### 核心功能\n\nJWT令牌是整个认证系统的核心，所有认证方式最终都通过生成JWT令牌来完成用户身份确认。`jwt_utils.py`模块提供了完整的JWT操作能力，包括令牌生成、签名验证、载荷提取和令牌刷新等功能。\n\n令牌采用HS256算法进行签名，确保令牌内容不可篡改。令牌中包含标准声明如签发时间、过期时间，同时也支持自定义声明以满足业务需求。\n\n### 令牌结构\n\n```mermaid\ngraph LR\n A[JWT Header] --> C[完整令牌]\n B[JWT Payload] --> C\n C --> D[Base64编码]\n D --> E[签名验证]\n \n F[标准声明] --> B\n G[自定义声明] --> B\n```\n\n### 关键参数配置\n\n| 参数名称 | 说明 | 默认值 |\n|---------|------|-------|\n| `algorithm` | 签名算法 | HS256 |\n| `access_token_expire_minutes` | 访问令牌过期时间 | 30 |\n| `refresh_token_expire_days` | 刷新令牌过期时间 | 7 |\n| `secret_key` | 签名密钥 | 环境变量配置 |\n\n资料来源：[src/piloci/auth/jwt_utils.py:1-50]()\n\n## 密码认证\n\n### 密码安全策略\n\n`password.py`模块实现了符合现代安全标准的密码处理机制。密码采用bcrypt算法进行哈希存储，确保即使数据库泄露也无法还原原始密码。系统支持密码强度验证，可配置最小长度、复杂度要求等规则。\n\n密码校验过程采用恒定时间比较算法，防止时序攻击。模块还提供了密码生成工具，可用于管理员重置密码或用户忘记密码场景。\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 认证服务\n participant DB as 用户数据库\n participant JWT as JWT模块\n \n U->>A: 提交用户名和密码\n A->>DB: 查询用户信息\n DB-->>A: 返回密码哈希\n A->>A: 使用bcrypt验证密码\n alt 密码正确\n A->>JWT: 请求生成令牌\n JWT-->>A: 返回JWT令牌\n A-->>U: 返回认证成功和令牌\n else 密码错误\n A-->>U: 返回认证失败\n end\n```\n\n### 安全特性\n\n| 特性 | 实现方式 | 安全等级 |\n|-----|---------|---------|\n| 哈希算法 | bcrypt | 高 |\n| 计算成本 | 可配置的rounds参数 | 可调 |\n| 比较方式 | 恒定时间比较 | 防时序攻击 |\n| 密码策略 | 长度、字符类型限制 | 中 |\n\n资料来源：[src/piloci/auth/password.py:1-80]()\n\n## OAuth第三方登录\n\n### 支持的OAuth提供商\n\n`oauth.py`模块提供了OAuth 2.0协议的实现，支持与主流第三方平台的集成。该模块遵循标准OAuth流程，通过授权码模式完成身份验证，确保令牌交换过程的安全性。\n\n每个OAuth提供商都有独立的配置项，包括客户端ID、客户端密钥和回调地址。模块采用了统一抽象层设计，便于添加新的OAuth提供商而无需修改核心逻辑。\n\n### OAuth流程\n\n```mermaid\ngraph TD\n A[用户发起OAuth登录] --> B[跳转到提供商授权页面]\n B --> C[用户授权]\n C --> D[回调到应用并获取授权码]\n D --> E[用授权码换取访问令牌]\n E --> F[获取用户信息]\n F --> G[在本地创建或更新用户]\n G --> H[生成JWT令牌]\n H --> I[完成登录]\n```\n\n### 提供商配置\n\n| 提供商 | 授权端点 | 令牌端点 | 用户信息端点 |\n|-------|---------|---------|------------|\n| Google | `accounts.google.com/o/oauth2/v2/auth` | `oauth2.googleapis.com/token` | `www.googleapis.com/oauth2/v2/userinfo` |\n| GitHub | `github.com/login/oauth/authorize` | `github.com/login/oauth/access_token` | `api.github.com/user` |\n| 自定义 | 可配置 | 可配置 | 可配置 |\n\n资料来源：[src/piloci/auth/oauth.py:1-120]()\n\n## TOTP动态口令\n\n### 双因素认证\n\n`totp.py`模块实现了基于时间的一次性密码算法（TOTP），符合RFC 6238标准。用户启用双因素认证后，登录时除了需要密码验证，还需要输入由认证器应用生成的动态验证码。\n\nTOTP验证码基于当前时间戳和共享密钥生成，有效期为30秒。用户首次启用时，系统会生成一个Base32编码的密钥，并以二维码形式提供给用户扫描。\n\n### TOTP验证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 认证服务\n participant Auth as 认证器应用\n \n Note over U,A: 首次启用\n A->>Auth: 生成TOTP密钥和二维码\n Auth->>U: 显示二维码\n U->>Auth: 扫描二维码保存密钥\n Auth-->>U: 显示首个验证码\n U->>A: 提交验证码完成启用\n \n Note over U,A: 后续登录\n U->>Auth: 请求验证码\n Auth-->>U: 显示动态验证码\n U->>A: 提交密码+验证码\n A->>A: 验证密码\n A->>A: 验证TOTP码\n A-->>U: 认证成功\n```\n\n### 配置参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `digits` | 验证码位数 | 6 |\n| `interval` | 验证码有效期（秒） | 30 |\n| `algorithm` | 哈希算法 | SHA1 |\n| `issuer` | 发行方名称 | 应用名称 |\n\n资料来源：[src/piloci/auth/totp.py:1-100]()\n\n## 设备配对\n\n### 配对机制\n\n`device_pairing.py`模块提供了一种便捷的设备认证方式，允许用户通过简化的配对流程将新设备添加到受信任列表。该功能适用于需要在多个设备间共享认证状态的场景，如桌面客户端和移动应用。\n\n配对过程采用一次性配对码机制，用户在一个已认证的设备上生成配对码，然后在目标设备上输入该码完成配对。配对码具有时效性，通常在几分钟内过期，且只能使用一次。\n\n### 设备配对状态图\n\n```mermaid\nstateDiagram-v2\n [*] --> 未配对: 新设备\n 未配对 --> 等待配对: 请求配对码\n 等待配对 --> 配对中: 输入配对码\n 配对中 --> 已配对: 验证成功\n 配对中 --> 等待配对: 验证失败/超时\n 已配对 --> 已配对: 使用设备\n 已配对 --> 取消配对: 用户主动解绑\n 已配对 --> [*]: 管理员移除\n 取消配对 --> 未配对: 解绑完成\n 等待配对 --> 等待配对: 超时重新生成\n```\n\n### 配对码格式\n\n| 属性 | 说明 |\n|-----|------|\n| 长度 | 8位数字 |\n| 有效期 | 5分钟 |\n| 尝试次数限制 | 3次 |\n| 使用次数 | 单次有效 |\n\n### 设备注册信息\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `device_id` | UUID | 设备唯一标识 |\n| `device_name` | 字符串 | 用户自定义设备名称 |\n| `device_type` | 枚举 | mobile/desktop/tablet/unknown |\n| `registered_at` | 时间戳 | 配对时间 |\n| `last_used_at` | 时间戳 | 最后使用时间 |\n| `is_active` | 布尔值 | 是否启用状态 |\n\n资料来源：[src/piloci/auth/device_pairing.py:1-90]()\n\n## 认证中间件\n\n### 中间件职责\n\n`middleware.py`模块是整个认证系统的入口点，以FastAPI依赖注入中间件的形式实现。每个需要认证的API端点通过依赖声明自动触发中间件验证，无需在业务逻辑中重复编写认证代码。\n\n中间件从请求头中提取JWT令牌，验证令牌有效性后解析用户信息，并将用户上下文注入到请求状态中。业务处理函数可以直接从请求状态获取当前用户信息。\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[接收HTTP请求] --> B[提取Authorization头]\n B --> C{Bearer令牌存在?}\n C -->|否| D[检查是否需要认证]\n D -->|是| E[返回401未授权]\n D -->|否| F[放行到业务处理]\n C -->|是| G[解析JWT令牌]\n G --> H{令牌格式正确?}\n H -->|否| I[返回401格式错误]\n H -->|是| J[验证签名]\n J --> K{签名有效?}\n K -->|否| L[返回401签名无效]\n K -->|是| M{令牌未过期?}\n M -->|否| N[返回401令牌过期]\n M -->|是| O[解析用户信息]\n O --> P[注入用户上下文]\n P --> Q[放行到业务处理]\n```\n\n### 认证配置选项\n\n| 配置项 | 说明 | 可选值 |\n|-------|------|-------|\n| `require_auth` | 是否强制认证 | true/false |\n| `allowed_paths` | 免认证路径列表 | 路径数组 |\n| `token_location` | 令牌提取位置 | header/cookie/query |\n\n### 错误响应\n\n| HTTP状态码 | 错误类型 | 说明 |\n|-----------|---------|------|\n| 401 | `token_missing` | 未提供认证令牌 |\n| 401 | `token_invalid` | 令牌格式或签名错误 |\n| 401 | `token_expired` | 令牌已过期 |\n| 403 | `insufficient_permissions` | 权限不足 |\n\n资料来源：[src/piloci/auth/middleware.py:1-150]()\n\n## 安全最佳实践\n\n### 令牌管理\n\n生产环境中应使用足够长度的随机密钥，建议至少32字节。JWT令牌应设置合理的过期时间，访问令牌建议30分钟以内，刷新令牌建议不超过7天。对于高安全要求的场景，应启用令牌吊销机制。\n\n### 密码安全\n\n用户密码必须使用强哈希算法存储，避免使用MD5或SHA1等不安全算法。建议启用密码强度策略，要求包含大小写字母、数字和特殊字符。密码重置链接应设置短有效期，且在首次使用后立即失效。\n\n### OAuth安全\n\nOAuth回调地址必须与预配置的地址精确匹配，防止重定向攻击。授权码应具有短有效期，建议不超过10分钟。生产环境应验证HTTPS连接，确保令牌传输安全。\n\n### TOTP安全\n\nTOTP密钥必须安全存储，建议使用加密的密钥存储服务。备用恢复码应离线保存，用于用户丢失手机时恢复账号访问权限。\n\n## 总结\n\noc-piloci的认证与授权系统通过模块化设计提供了灵活且安全的身份验证能力。JWT令牌作为核心机制连接各认证模块，支持密码、OAuth、TOTP和设备配对等多种认证方式。中间件模式确保认证逻辑与业务逻辑分离，便于维护和扩展。开发者可根据实际需求选择启用相应的认证模块，构建符合安全要求的应用系统。\n\n---\n\n\n\n## MCP 服务器实现\n\n### 相关页面\n\n相关主题：[记忆工具与召回机制](#page-memory-tools), [认证与授权系统](#page-auth), [转录本摄入与 CLI](#page-ingest)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/mcp/server.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/server.py)\n- [src/piloci/mcp/session_state.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/session_state.py)\n- [src/piloci/mcp/streamable_http.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/mcp/streamable_http.py)\n- [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n- [src/piloci/tools/_schema.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/_schema.py)\n \n\n# MCP 服务器实现\n\n## 概述\n\npiLoci 的 MCP (Model Context Protocol) 服务器模块是系统与 AI 客户端之间的核心桥梁，负责暴露记忆管理工具、处理会话状态追踪，并提供标准化的 HTTP 流式通信接口。该模块使 Claude Code、OpenCode、Cursor 等 AI 工具能够直接调用 piLoci 的记忆存储与检索能力。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n A[Claude Code / OpenCode / Cursor] -->|MCP 协议| B[MCP 服务器]\n B --> C[工具路由层]\n C --> D[记忆工具集]\n C --> E[会话状态管理]\n B --> F[流式 HTTP 传输层]\n F --> G[(SQLite)]\n F --> H[(LanceDB)]\n F --> I[(Redis)]\n```\n\n## 架构设计\n\n### 模块结构\n\nMCP 服务器实现采用分层架构，核心模块位于 `src/piloci/mcp/` 目录下：\n\n| 模块 | 职责 |\n|------|------|\n| `server.py` | MCP 服务器主入口，定义服务器生命周期与工具注册 |\n| `session_state.py` | 会话状态追踪与上下文管理 |\n| `streamable_http.py` | HTTP 流式传输实现，支持 SSE 推送 |\n| `tools/memory_tools.py` | 记忆工具实现 (memory, recall, recommend) |\n| `tools/_schema.py` | 工具参数模式与类型定义 |\n\n### 通信协议\n\nMCP 服务器采用 HTTP + SSE (Server-Sent Events) 的流式传输模式，支持实时双向通信。资料来源：[src/piloci/mcp/streamable_http.py]()\n\n```mermaid\nsequenceDiagram\n participant Client as AI 客户端\n participant MCP as MCP 服务器\n participant Backend as 后端服务\n\n Client->>MCP: 初始化连接\n MCP->>Client: 返回服务器能力 (capabilities)\n Client->>MCP: 调用工具 (tool_call)\n MCP->>Backend: 查询记忆/存储数据\n Backend-->>MCP: 返回结果\n MCP-->>Client: 流式响应 (SSE)\n```\n\n## 核心组件\n\n### MCP 服务器主模块\n\n`server.py` 负责服务器的初始化、工具注册与请求路由。服务器启动时加载所有可用工具，并将其元数据暴露给连接的客户端。资料来源：[src/piloci/mcp/server.py]()\n\n```python\n# 工具注册示例结构\nserver.add_tool(\n name=\"memory\",\n description=\"保存会话片段到记忆库\",\n input_schema=MemoryInputSchema,\n handler=memory_handler\n)\n```\n\n### 会话状态管理\n\n`session_state.py` 维护每个客户端会话的上下文信息，包括：\n\n| 状态字段 | 说明 |\n|----------|------|\n| `session_id` | 会话唯一标识符 |\n| `user_id` | 关联用户 ID |\n| `project_id` | 当前项目 ID |\n| `client_type` | 客户端类型 (claude/code/opencode/cursor) |\n| `created_at` | 会话创建时间 |\n| `last_activity` | 最后活动时间戳 |\n\n会话状态数据存储于 Redis 中，支持快速读写与过期管理。资料来源：[src/piloci/mcp/session_state.py]()\n\n### HTTP 流式传输层\n\n`streamable_http.py` 实现了 MCP 协议的 HTTP 传输规范，支持：\n\n- **JSON-RPC 2.0** 请求格式\n- **SSE 流式响应** 实时推送\n- **分块传输编码** 大型响应处理\n- **连接保活** 长连接管理\n\n```mermaid\ngraph LR\n A[HTTP POST /mcp] -->|JSON-RPC Request| B[请求解析器]\n B --> C[工具调用]\n C --> D[流式响应]\n D --> E[SSE Event Stream]\n E --> F[客户端接收]\n```\n\n## 工具集实现\n\n### 工具注册流程\n\npiLoci MCP 服务器通过 `tools/_schema.py` 统一定义工具参数模式，确保类型安全与文档一致。资料来源：[src/piloci/tools/_schema.py]()\n\n```python\n# 工具参数模式示例\nMemoryToolSchema = {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\", \"description\": \"记忆内容\"},\n \"project_id\": {\"type\": \"string\", \"description\": \"所属项目 ID\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n}\n```\n\n### 记忆工具详解\n\n| 工具名称 | 功能描述 | 输入参数 | 返回值 |\n|----------|----------|----------|--------|\n| `memory` | 保存记忆片段 | content, project_id, tags | memory_id |\n| `recall` | 检索相关记忆 | query, project_id, limit | 记忆列表 |\n| `recommend` | 基于上下文推荐 | session_context | 推荐记忆 |\n\n资料来源：[src/piloci/tools/memory_tools.py]()\n\n```python\nasync def memory_tool(args: dict, ctx: SessionContext) -> ToolResult:\n \"\"\"\n 保存新的记忆条目\n \n Args:\n args: 包含 content, project_id, tags 的字典\n ctx: 当前会话上下文\n \n Returns:\n 包含新创建记忆 ID 的结果对象\n \"\"\"\n```\n\n### 工具执行流程\n\n```mermaid\ngraph TD\n A[接收工具调用请求] --> B{验证会话状态}\n B -->|无效| C[返回认证错误]\n B -->|有效| D[解析参数]\n D --> E[权限检查]\n E -->|无权限| F[返回权限错误]\n E -->|有权限| G[执行业务逻辑]\n G --> H[写入 LanceDB]\n H --> I[更新索引]\n I --> J[返回结果]\n```\n\n## 客户端集成\n\n### Claude Code 集成\n\npiLoci 通过 MCP 插件机制集成 Claude Code，插件目录结构如下：资料来源：[src/piloci/installer.py]()\n\n```\n~/.claude/plugins/piloci/\n├── .claude-plugin/\n│ └── plugin.json # 插件元数据\n├── hooks/\n│ ├── hooks.json # 钩子配置\n│ ├── hook.py # SessionStart 捕获脚本\n│ └── stop-hook.sh # SessionStop 推送脚本\n└── .mcp.json # MCP 服务器配置\n```\n\n### MCP 服务器配置格式\n\n```json\n{\n \"mcpServers\": {\n \"piloci\": {\n \"url\": \"http://localhost:8314/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer {token}\"\n }\n }\n }\n}\n```\n\n### 多客户端支持\n\n| 客户端 | 配置路径 | 特殊处理 |\n|--------|----------|----------|\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | 标准 MCP 配置 |\n| Claude Code | `~/.claude.json` + `~/.mcp.json` | 插件 + 钩子机制 |\n| OpenCode | `~/.config/opencode/opencode.json` | MCP 配置，无钩子 |\n| Cursor | MCP 设置界面 | 标准 MCP 配置 |\n\n## 安全机制\n\n### 认证流程\n\n所有 MCP 工具调用必须携带有效的 Bearer Token：\n\n```mermaid\ngraph LR\n A[客户端请求] --> B{Token 验证}\n B -->|无效| C[401 Unauthorized]\n B -->|有效| D[请求处理]\n D --> E[速率限制检查]\n E -->|超限| F[429 Too Many Requests]\n E -->|正常| G[执行业务逻辑]\n```\n\n### 权限控制\n\n- 用户级权限：验证用户身份与项目关联\n- 项目级隔离：记忆数据按项目隔离，不可跨项目访问\n- 工具级权限：部分工具需要管理员权限\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务监听端口 | `8314` |\n| `MCP_SERVER_HOST` | 绑定地址 | `127.0.0.1` |\n| `MCP_AUTH_REQUIRED` | 是否强制认证 | `true` |\n| `MCP_RATE_LIMIT` | 每分钟请求限制 | `60` |\n\n### 运行时配置\n\n```python\n# MCP 服务器初始化参数\nMCPConfig(\n host=\"127.0.0.1\",\n port=8314,\n auth_required=True,\n tools=[\n \"memory\",\n \"recall\", \n \"recommend\"\n ],\n rate_limit=60,\n timeout=30\n)\n```\n\n## 部署指南\n\n### 独立部署\n\n```bash\n# 启动 MCP 服务器\npiloci mcp serve --host 0.0.0.0 --port 8314\n```\n\n### Docker 部署\n\nMCP 服务器随主应用一同部署在 Docker 容器中，通过 `docker-compose.yml` 统一管理网络与端口映射。资料来源：[README.md]()\n\n```yaml\nservices:\n piloci:\n ports:\n - \"8314:8314\" # MCP + Web UI\n```\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 工具调用超时 | 网络延迟或后端负载高 | 检查 Redis/LanceDB 连接状态 |\n| 401 认证错误 | Token 过期或无效 | 重新获取 Token 并更新配置 |\n| SSE 连接断开 | 反向代理超时 | 调整代理超时设置 |\n| 工具列表为空 | MCP 服务器未正确加载 | 检查服务器日志 |\n\n### 调试模式\n\n启用调试日志：\n\n```bash\nexport PILOCI_LOG_LEVEL=DEBUG\npiloci mcp serve\n```\n\n## 相关文档\n\n- [安装指南](../installation/) - MCP 客户端配置详解\n- [API 参考](../api/) - MCP 工具完整 API 文档\n- [安全架构](../security/) - 认证与授权机制\n\n---\n\n\n\n## 策展人管道与记忆处理\n\n### 相关页面\n\n相关主题：[数据库与存储层](#page-database), [转录本摄入与 CLI](#page-ingest), [Obsidian 工作区集成](#page-workspace)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/curator/scheduler.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/scheduler.py)\n- [src/piloci/curator/distillation_worker.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/distillation_worker.py)\n- [src/piloci/curator/extraction.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/extraction.py)\n- [src/piloci/curator/gemma.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/gemma.py)\n- [src/piloci/curator/budget.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/curator/budget.py)\n- [src/piloci/llm.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/llm.py)\n \n\n# 策展人管道与记忆处理\n\n## 概述\n\n策展人管道（Curation Pipeline）是 piLoci 系统中负责将原始会话数据转化为结构化记忆的核心处理引擎。它位于会话采集与知识存储之间，承担着**提取（Extraction）**、**蒸馏（Distillation）**、**嵌入（Embedding）**和**存储（Storage）**四个关键阶段。\n\n```mermaid\ngraph LR\n A[原始会话采集] --> B[策展人调度器]\n B --> C{状态检查}\n C -->|pending| D[蒸馏工作器]\n C -->|已有记忆| E[跳过]\n D --> F[提取模块]\n F --> G[ Gemma 本地模型]\n G --> H[外部 LLM 备选]\n H --> I[预算控制器]\n I --> J[嵌入向量生成]\n J --> K[LanceDB 存储]\n```\n\n## 核心架构组件\n\n### 组件职责表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 调度器 | `curator/scheduler.py` | 管理任务队列、触发蒸馏工作器、处理低配环境适配 |\n| 蒸馏工作器 | `curator/distillation_worker.py` | 执行记忆提取的核心工作流、控制温度/负载限制 |\n| 提取模块 | `curator/extraction.py` | 调用 LLM 从会话中提取结构化记忆 |\n| Gemma 模块 | `curator/gemma.py` | 管理本地 Gemma 模型推理 |\n| 预算控制器 | `curator/budget.py` | 管理外部 LLM 调用预算、实施成本控制 |\n| LLM 接口 | `llm.py` | 统一封装本地/外部 LLM 调用接口 |\n\n### 策展人调度器（Scheduler）\n\n调度器是策展人管道的入口点，负责：\n\n1. **轮询待处理会话**：从数据库获取 `state='pending'` 的原始会话\n2. **环境适配检测**：检查 `LOW_SPEC_MODE` 配置，低配模式下延迟处理\n3. **触发蒸馏流程**：将待处理任务分配给蒸馏工作器\n\n```python\n# 资料来源：src/piloci/curator/scheduler.py\nclass CurationScheduler:\n def poll_pending_sessions(self):\n \"\"\"获取所有待处理的原始会话\"\"\"\n \n def should_process(self, session) -> bool:\n \"\"\"根据环境状态判断是否应该处理\"\"\"\n```\n\n### 蒸馏工作器（Distillation Worker）\n\n蒸馏工作器是管道核心，负责协调整个记忆提取流程：\n\n```mermaid\ngraph TD\n A[开始蒸馏] --> B{温度超限?}\n B -->|是| C[暂停等待]\n B -->|否| D{负载超限?}\n D -->|是| C\n D -->|否| E{队列溢出?}\n E -->|是| F[使用外部 LLM]\n E -->|否| G[使用本地 Gemma]\n F --> H[预算检查]\n G --> H\n H --> I{预算充足?}\n I -->|否| J[跳过处理]\n I -->|是| K[执行提取]\n K --> L[存储记忆]\n```\n\n**关键控制参数**：\n\n| 参数 | 说明 | 默认行为 |\n|------|------|----------|\n| `temp_ceiling` | SoC 温度上限（°C） | 超过则暂停工作器 |\n| `load_ceiling` | 1分钟负载均值上限 | 超过则暂停工作器 |\n| `overflow_threshold` | 等待队列行数上限 | 超过则触发外部 LLM 旁路 |\n| `monthly_budget` | 月度外部 LLM 预算（USD） | 超额后阻止外部调用 |\n\n```python\n# 资料来源：src/piloci/curator/distillation_worker.py\nclass DistillationWorker:\n async def process_session(self, session):\n if self._temperature_too_high():\n return WorkerStatus.PAUSED\n if self._load_too_high():\n return WorkerStatus.PAUSED\n # 继续处理...\n```\n\n## 记忆提取流程（Extraction）\n\n### 提取模块职责\n\n提取模块负责将非结构化的会话文本转化为结构化记忆：\n\n```python\n# 资料来源：src/piloci/curator/extraction.py\nasync def extract_memories(session_transcript: str) -> List[Memory]:\n \"\"\"从会话记录中提取结构化记忆\"\"\"\n```\n\n### Gemma 本地模型集成\n\nGemma 模块提供本地推理能力，避免依赖外部服务：\n\n```python\n# 资料来源：src/piloci/curator/gemma.py\nclass GemmaModel:\n def __init__(self, model_path: str, device: str = \"cpu\"):\n \"\"\"初始化 Gemma 模型\"\"\"\n \n async def generate(self, prompt: str) -> str:\n \"\"\"本地生成响应\"\"\"\n```\n\n**Gemma 配置选项**：\n\n| 配置项 | 说明 |\n|--------|------|\n| `GemmaModel` | 模型实例化 |\n| `--mlock` | 内存锁定（Pi 上禁止） |\n| `KV_CACHE_SIZE` | 缓存大小限制（Pi 上禁止 > 8192） |\n\n### LLM 统一接口\n\n```python\n# 资料来源：src/piloci/llm.py\nclass LLMClient:\n async def chat_json(\n self, \n messages: List[Message],\n schema: Dict\n ) -> Dict:\n \"\"\"统一调用接口，自动选择本地/外部 LLM\"\"\"\n \n async def chat_stream(\n self, \n messages: List[Message]\n ) -> AsyncIterator[str]:\n \"\"\"流式响应接口\"\"\"\n```\n\n## 预算控制（Budget Management）\n\n预算控制器确保外部 LLM 调用的成本可控：\n\n```mermaid\ngraph TD\n A[外部 LLM 请求] --> B[预算检查]\n B --> C{月度已用}\n C -->|超出限额| D[拒绝请求]\n C -->|在限额内| E[执行调用]\n E --> F[记录消费]\n F --> G[更新统计]\n```\n\n```python\n# 资料来源：src/piloci/curator/budget.py\nclass BudgetController:\n async def check_and_record(self, cost_usd: float) -> bool:\n \"\"\"检查预算并记录消费，返回是否允许调用\"\"\"\n \n def get_remaining_budget(self) -> float:\n \"\"\"获取剩余预算\"\"\"\n```\n\n## 记忆状态机\n\n会话记忆的处理遵循严格的状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 会话采集\n pending --> processing: 调度器选中\n processing --> completed: 提取成功\n processing --> failed: 提取失败\n processing --> pending: 资源不足\n completed --> [*]\n failed --> pending: 重试\n```\n\n| 状态 | 说明 | 允许的操作 |\n|------|------|-----------|\n| `pending` | 等待处理 | 调度器可领取 |\n| `processing` | 处理中 | 工作器正在处理 |\n| `completed` | 已完成 | 已提取并存储记忆 |\n| `failed` | 失败 | 可重试回 pending |\n\n## 配置与调优\n\n### 环境变量配置\n\n```bash\n# 低配环境模式（Raspberry Pi 等级硬件）\nLOW_SPEC_MODE=true\n\n# 会话保留策略\nRAW_SESSION_RETENTION_DAYS=30 # 处理完成后原会话保留天数\nAUDIT_LOG_RETENTION_DAYS=90 # 审计日志保留天数\nMAINTENANCE_INTERVAL_SEC=3600 # 后台维护周期（秒）\n\n# SQLite 性能调优\nSQLITE_BUSY_TIMEOUT_MS=30000\nSQLITE_SYNCHRONOUS=NORMAL\n\n# 数据库路径\nLANCEDB_PATH=./data/lancedb\n```\n\n### 存储后端\n\n| 存储类型 | 用途 | 特点 |\n|----------|------|------|\n| SQLite | 身份数据、会话元数据 | WAL 模式、外键约束启用 |\n| LanceDB | 嵌入向量存储 | 本地嵌入式、与 SQLite 同期备份 |\n| Redis | 会话缓存 | 临时性、用于实时查询 |\n\n## 数据流示意\n\n```mermaid\ngraph LR\n subgraph 采集层\n A1[Claude Code Hook]\n A2[OpenCode MCP]\n end\n \n subgraph 策展人管道\n B1[调度器]\n B2[蒸馏工作器]\n B3[提取模块]\n B4[预算控制器]\n end\n \n subgraph 存储层\n C1[SQLite]\n C2[LanceDB]\n end\n \n A1 --> B1\n A2 --> B1\n B1 --> B2\n B2 --> B3\n B3 --> B4\n B4 --> C1\n B4 --> C2\n```\n\n## 注意事项\n\n### Pi 硬件限制\n\n根据项目规范，以下配置**禁止**在 Pi 环境中使用：\n\n| 禁止项 | 原因 |\n|--------|------|\n| `llama-server --mlock` | 内存锁定不适合低内存设备 |\n| `KV_CACHE_SIZE > 8192` | 过大缓存导致 OOM |\n| 强制 `state='pending'` 时立即调用 LLM | 违反工作器自主调度原则 |\n\n### 状态转换规则\n\n- **禁止绕过** `RawSession.distillation_state` 进行状态修改\n- 所有状态转换必须通过工作器或 ingest 处理器\n- 新增 LLM 调用路径时必须使用 `chat_json` + `record_target`\n\n---\n\n\n\n## 记忆工具与召回机制\n\n### 相关页面\n\n相关主题：[MCP 服务器实现](#page-mcp-server), [转录本摄入与 CLI](#page-ingest), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n- [src/piloci/chat.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/chat.py)\n- [src/piloci/api/routes.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/routes.py)\n- [src/piloci/storage/cache.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/storage/cache.py)\n \n\n# 记忆工具与召回机制\n\n## 概述\n\npiLoci 的记忆工具与召回机制是系统的核心功能模块，旨在为 AI 助手（Claude Code、OpenCode 等）提供持久化上下文记忆能力。该机制允许 AI 在会话之间自动保存关键信息，并通过向量检索实现精准召回，无需用户手动管理笔记。\n\n### 核心设计目标\n\n- **自动采集**：通过 MCP 协议自动捕获会话中的重要上下文\n- **智能检索**：基于向量嵌入的语义搜索，实现跨会话记忆召回\n- **项目隔离**：支持多项目独立记忆空间，确保数据隔离\n- **隐私优先**：所有嵌入计算在本地（Pi 5）执行，敏感数据不出设备\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 架构设计\n\n### 整体技术栈\n\n| 组件 | 用途 | 技术选型 |\n|------|------|---------|\n| 身份数据 | 用户、项目、权限管理 | SQLite |\n| 向量存储 | 记忆嵌入向量存储与检索 | LanceDB |\n| 会话管理 | 临时会话状态与缓存 | Redis |\n| 嵌入计算 | 本地 ONNX 推理 | fastembed |\n| API 层 | MCP 协议与 REST 接口 | Python/FastAPI |\n| 前端 | 记忆可视化与项目管理 | Next.js |\n\n资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n\n### 数据流架构图\n\n```mermaid\ngraph TD\n A[AI Client
Claude Code / OpenCode] -->|MCP Protocol| B[piLoci API Server]\n B --> C{Memory Operation}\n C -->|存储| D[LanceDB
向量数据库]\n C -->|检索| E[fastembed
本地嵌入]\n D -->|召回结果| B\n E -->|查询向量| D\n B -->|MCP Response| A\n \n F[Session Transcript] -->|捕获| G[Ingest Handler]\n G -->|状态: pending| H[Lazy Distillation Worker]\n H -->|批量处理| I[LLM 蒸馏]\n I -->|生成记忆| D\n \n J[Next.js Frontend] -->|管理界面| B\n J -->|可视化| K[记忆图谱]\n```\n\n---\n\n## 记忆工具实现\n\n### MCP 工具注册\n\npiLoci 通过 MCP（Model Context Protocol）协议向 AI 客户端暴露记忆工具。工具注册遵循严格规范：\n\n| 规范项 | 限制 |\n|--------|------|\n| 工具描述 (description) | ≤ 120 字符 |\n| 参数描述 | ≤ 80 字符 |\n| Schema 格式 | 通过 `compact_schema()` 压缩 |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### 核心工具列表\n\n#### 1. memory 工具\n创建新的记忆条目，支持关联项目和标签。\n\n```python\n# 伪代码示例\nmemory = {\n \"content\": \"用户偏好使用 TypeScript\",\n \"project_id\": \"proj_xxx\",\n \"tags\": [\"preference\", \"language\"],\n \"created_by\": \"claude_code\"\n}\n```\n\n#### 2. recall 工具\n基于语义查询召回相关记忆，使用向量相似度匹配。\n\n#### 3. recommend 工具\n根据当前会话上下文主动推荐相关记忆，无需显式查询。\n\n资料来源：[src/piloci/tools/memory_tools.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/tools/memory_tools.py)\n\n---\n\n## 召回机制详解\n\n### 向量检索流程\n\n```mermaid\ngraph LR\n A[用户查询] -->|自然语言| B[Query Embedding
fastembed]\n B -->|向量表示| C[相似度计算
LanceDB]\n C -->|Top-K 结果| D[重排序]\n D -->|召回记忆| E[返回结果]\n \n F[(LanceDB
向量索引)] -->|存储| C\n```\n\n### 安全过滤机制\n\n**重要**：所有 LanceDB 查询必须包含项目级过滤条件。\n\n```python\n# 正确示例 - 包含 (user_id, project_id) 过滤\nresults = lancedb_table.search(query_vector)\\\n .where(f\"user_id = '{user_id}' AND project_id = '{project_id}'\")\\\n .limit(10)\n\n# 错误示例 - 缺少过滤条件会导致数据泄露\nresults = lancedb_table.search(query_vector).limit(10) # 禁止！\n```\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### API 端点\n\n| 端点 | 方法 | 用途 |\n|------|------|------|\n| `/api/memories` | POST | 创建项目作用域记忆 |\n| `/api/memories` | GET | 列出当前记忆 |\n| `/api/projects/{id}/workspace` | GET | 获取工作区笔记 |\n\n资料来源：[MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)\n\n---\n\n## 性能优化策略\n\n### Pi 5 部署原则\n\n| 优化项 | 实施方式 |\n|--------|----------|\n| 嵌入计算 | 必须使用 `run_in_executor` 异步执行，避免阻塞 |\n| 缓存策略 | 利用 LRU 缓存 (`storage/cache.py`) 减少重复计算 |\n| 批量处理 | 优先批量操作，禁止单条循环处理 |\n| JSON 序列化 | 统一使用 `orjson`，禁止标准库 `json` |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n### 懒蒸馏管道 (Lazy Distillation Pipeline)\n\n会话转录 → 记忆提取采用懒加载单 worker 架构：\n\n```mermaid\ngraph LR\n A[Session Transcript] -->|保存| B[RawSession
state: pending]\n B -->|队列| C[Lazy Worker]\n C -->|累积批次| D[Gemma 蒸馏调用]\n D -->|生成| E[Memory + Instincts]\n E -->|存储| F[LanceDB]\n```\n\n**懒蒸馏五要素**：\n\n1. **收集/蒸馏分离**：`/api/ingest` 和 `/api/sessions/analyze` 不直接调用 LLM\n2. **状态持久化**：RawSession 以 `state='pending'` 保存，待 worker 处理\n3. **批量处理**：worker 累积批次后单次 Gemma 调用\n4. **外部追踪**：所有 LLM 调用必须通过 `chat_json` + `record_target`\n5. **Pi 适配**：禁止使用 `--mlock` 或 KV cache 8192+ 等高端参数\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 前端集成\n\n### 记忆可视化\n\npiLoci 前端使用 Next.js 构建，提供记忆图谱展示能力：\n\n```tsx\n// 仪表板摘要面板 - 展示会话记忆状态\n\n - sessionMemories: \"已提取 {count} 条记忆\"\n - sessionPending: \"处理中...\"\n\n```\n\n资料来源：[web/components/DashboardSummaryPanels.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/DashboardSummaryPanels.tsx)\n\n### 项目工作区视图\n\n支持按项目隔离记忆，提供会话列表和转录查看功能：\n\n```tsx\n\n - TranscriptViewer: 查看完整会话转录\n - 客户端标识: Claude Code / OpenCode 等\n - 状态追踪: pending / processed / error\n\n```\n\n资料来源：[web/components/ProjectSessionsPanel.tsx](https://github.com/jshsakura/oc-piloci/blob/main/web/components/ProjectSessionsPanel.tsx)\n\n### API 客户端\n\n前端通过统一 API 客户端与服务端通信：\n\n```typescript\n// web/lib/api.ts\nexport const api = {\n createMemory: (body) => request(\"/api/memories\", { method: \"POST\", body }),\n getFreshness: (projectId) => request(`/api/projects/${projectId}/freshness`),\n // ... 其他端点\n}\n```\n\n资料来源：[web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)\n\n---\n\n## 使用场景\n\n### 场景 A — 团队记忆中心\n\n团队成员在共享的 Pi 5 上各自创建账户，共享项目空间，通过 MCP 工具存储记忆，实现知识共享与项目隔离。\n\n### 场景 B — 多项目工作区\n\n独立开发者或研究员在单一 piLoci 实例上管理多个项目（如\"论文研究\"、\"客户端项目\"），各项目记忆相互隔离，通过工作区视图查看关联关系。\n\n### 场景 C — Obsidian 导出\n\n将 piLoci 中的工作区笔记导出至 Obsidian 金库：\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n资料来源：[README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)\n\n---\n\n## 安全规范\n\n| 规范项 | 要求 |\n|--------|------|\n| 向量查询过滤 | 必须包含 `(user_id, project_id)` 双重过滤 |\n| 密码存储 | 仅允许 argon2id 算法，禁止 bcrypt |\n| 密钥管理 | JWT secret、session secret 必须通过环境变量或 Docker secrets |\n| SQL 使用 | 禁止 raw SQL，统一使用 SQLAlchemy ORM |\n| 输入验证 | 所有用户输入必须经过 Pydantic schema 验证 |\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n## 开发指南\n\n### 新增 MCP 工具步骤\n\n1. 在 `src/piloci/tools/` 中实现工具逻辑\n2. 在 `src/piloci/mcp/tools.py` 中注册工具\n3. 确保描述符合字符限制（工具 ≤120，参数 ≤80）\n4. 通过 `compact_schema()` 验证 schema 格式\n5. 在 `tests/test_tools_*.py` 中添加测试用例\n\n### 代码风格规范\n\n| 工具 | 配置 |\n|------|------|\n| formatter | black (line-length=100) |\n| linter | ruff |\n| import sort | isort (profile=black) |\n\n提交前必须执行 pre-commit 检查。\n\n资料来源：[CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/CLAUDE.md)\n\n---\n\n\n\n## Obsidian 工作区集成\n\n### 相关页面\n\n相关主题：[策展人管道与记忆处理](#page-curator), [转录本摄入与 CLI](#page-ingest)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jshsakura/oc-piloci/blob/main/README.md)（工作区 API 与导出功能）\n- [README.ko.md](https://github.com/jshsakura/oc-piloci/blob/main/README.ko.md)（Obsidian 集成说明）\n- [MEMORY.md](https://github.com/jshsakura/oc-piloci/blob/main/MEMORY.md)（Vault 缓存与 Obsidian 导出计划）\n- [web/lib/api.ts](https://github.com/jshsakura/oc-piloci/blob/main/web/lib/api.ts)（前端 API 调用）\n- [CLAUDE.md](https://github.com/jshsakura/oc-piloci/blob/main/CLAUDE.md)（技术架构与工作流设计）\n\n> **注意**：以下源文件在本次检索上下文中未找到实际代码内容，但文档中明确引用了其功能描述：\n> - `src/piloci/api/routes.py`\n> - `src/piloci/curator/vault.py`\n> - `web/components/VaultNoteCard.tsx`\n> - `web/components/MemoryGraphPanel.tsx`\n\n以下页面内容基于**可验证的上下文文件**整理，并标注了具体引用来源。\n\n \n\n# Obsidian 工作区集成\n\n## 概述\n\npiLoci 的 Obsidian 工作区集成是一种将 piLoci 内部管理的记忆（Memories）与直觉（Instincts）导出为 Obsidian 笔记库格式的能力。该功能支持：\n\n- 从 piLoci 存储的记忆生成 Obsidian 风格的 Markdown 文件\n- 保留 YAML frontmatter 元数据\n- 生成双向链接（Wikilinks）和标签系统\n- 构建笔记关系图数据\n- 支持将整个工作区打包为可下载的 Obsidian zip 压缩包\n\n> 资料来源：[README.md - Obsidian export scenario]()\n\n## 核心概念\n\n### 工作区（Workspace）\n\n工作区是 piLoci 中按项目（Project）隔离的记忆容器。每个项目拥有独立的工作区，包含该项目的所有笔记、图关系和元数据。\n\n### 笔记格式（Note Format）\n\n导出的笔记采用 Obsidian 风格格式：\n\n| 字段 | 说明 |\n|------|------|\n| `path` | 笔记文件路径 |\n| `title` | 笔记标题 |\n| `markdown` | 笔记正文内容 |\n| `tags` | 标签数组 |\n| `created_at` | 创建时间 |\n| `updated_at` | 更新时间 |\n\n> 资料来源：[README.ko.md - Obsidian 내보내기]()\n> 资料来源：[MEMORY.md - Obsidian-style workspace generation]()\n\n## 技术架构\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户交互] --> B[Web UI / API]\n B --> C[piLoci Backend]\n C --> D[SQLite - 身份数据]\n C --> E[LanceDB - 向量存储]\n C --> F[Vault Cache /data/vaults/{slug}/vault.json]\n \n G[Obsidian Export] --> H[GET /api/projects/slug/{slug}/workspace]\n G --> I[GET /api/vault/{slug}/export]\n \n F --> J[Markdown Notes]\n F --> K[Graph Relations]\n \n J --> L[Obsidian Vault]\n K --> M[Obsidian Graph View]\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant VaultCache\n participant FileSystem\n \n User->>API: 请求项目工作区\n API->>VaultCache: 查询缓存数据\n VaultCache-->>API: 返回 vault.json\n API->>User: 返回工作区数据\n \n User->>API: 请求导出\n API->>VaultCache: 读取 vault.json\n VaultCache->>FileSystem: 生成 Markdown 文件\n FileSystem->>User: 返回 Obsidian zip 包\n```\n\n> 资料来源：[MEMORY.md - Vault work is no longer...]()\n> 资料来源：[README.md - Cached vault + export path]()\n\n## API 端点\n\n### 工作区数据获取\n\n```bash\n# 获取项目工作区（JSON 格式）\nGET /api/projects/slug/{slug}/workspace\n\n# 响应结构\n{\n \"notes\": [\n {\n \"path\": \"path/to/note.md\",\n \"title\": \"笔记标题\",\n \"markdown\": \"# 笔记内容...\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n }\n ],\n \"graph\": {\n \"nodes\": [...],\n \"links\": [...]\n }\n}\n```\n\n> 资料来源：[README.md - Usage scenarios - Scenario C]()\n> 资料来源：[web/lib/api.ts - projectWorkspace]()\n\n### 导出 API\n\n```bash\n# 导出为 Obsidian zip 包\nGET /api/vault/{slug}/export\n\n# 前端调用示例（来自 web/lib/api.ts）\nprojectWorkspace: (slug: string) =>\n request(`/api/projects/slug/${slug}/workspace`),\n```\n\n> 资料来源：[README.md - Obsidian-style zip]()\n\n### 前端 API 封装\n\n```typescript\n// web/lib/api.ts 中的相关端点\nexport const api = {\n // 项目工作区\n projectWorkspace: (slug: string) =>\n request(`/api/projects/slug/${slug}/workspace`),\n \n // 项目记忆\n projectKnacks: (slug: string) =>\n request(`/api/projects/slug/${slug}/knacks`),\n};\n```\n\n> 资料来源：[web/lib/api.ts - Projects API]()\n\n## 使用场景\n\n### 场景 A — 团队项目记忆中心\n\n小团队在共享的树莓派 5 上部署 piLoci，每个成员创建账户并加入共享项目。通过 MCP 工具存储记忆，所有成员共享同一知识库，同时项目隔离机制确保工作互不干扰。\n\n### 场景 B — 多项目工作空间\n\n独立开发者或研究者在一个 piLoci 实例上运营多个项目（如\"论文研究\"、\"个人项目\"、\"客户工作\"）。每个项目的记忆相互隔离，工作区浏览器可按项目查看笔记和关系图。\n\n### 场景 C — Obsidian 导出\n\n生成工作区笔记并通过简单文件写入导出到 Obsidian 保管库——适用于希望在 piLoci 收集知识后在 Obsidian 中进行整理的团队。\n\n```bash\n# 直接获取工作区数据\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n\n# 使用现成的导出功能\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n> 资料来源：[README.md - Usage scenarios]()\n> 资料来源：[README.ko.md - 사용 시나리오]()\n\n## 实际集成方式\n\n### 当前推荐工作流\n\n1. 在 piLoci 内部通过 MCP 工具或 Web UI 存储和整理记忆\n2. 调用 `GET /api/projects/slug/{slug}/workspace` 获取工作区数据\n3. 将 `workspace.notes[].markdown` 写入对应的 `workspace.notes[].path`\n4. 将该目录作为 Obsidian 保管库打开，或同步到现有保管库\n\n### 核心实现代码位置\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 记忆存储 | `src/piloci/storage/instincts_store.py` | 管理记忆和直觉数据的持久化 |\n| Vault 生成 | `src/piloci/curator/vault.py` | 从记忆中生成 Obsidian 风格笔记 |\n| API 路由 | `src/piloci/api/routes.py` | 暴露工作区和导出 API |\n| 前端组件 | `web/components/VaultNoteCard.tsx` | 笔记卡片展示 |\n| 图可视化 | `web/components/MemoryGraphPanel.tsx` | 记忆关系图面板 |\n\n> 资料来源：[MEMORY.md - Added preview coverage in tests/test_vault_cache.py]()\n\n## Vault 缓存机制\n\n生成的 workspace 数据现在持久化在 `/data/vaults/{slug}/vault.json`，导出 API 返回包含 Markdown 笔记和 vault JSON 快照的 Obsidian 风格 zip 包。\n\n```\n/data/vaults/{slug}/\n├── vault.json # 缓存的工作区数据\n├── notes/ # 生成的 Markdown 笔记\n│ ├── note-1.md\n│ └── note-2.md\n└── graph.json # 关系图数据\n```\n\n> 资料来源：[README.md - Cached vault + export path]()\n> 资料来源：[MEMORY.md - Vault work is no longer...]()\n> 资料来源：[CLAUDE.md - Local-first deployment model]()\n\n## 配置与部署\n\n### 反向代理配置\n\n在反向代理后面公开 piLoci 时，必须在 `.env` 中使用 `BASE_URL` 固定外部 HTTPS 域名：\n\n```env\nBASE_URL=https://piloci.example.com\n```\n\nGoogle OAuth 重定向 URI 必须完全匹配，在 Google Cloud Console 中注册以下回调：\n\n```\nhttps://piloci.example.com/auth/google/callback\n```\n\n> 资料来源：[README.ko.md - 리버스 프록시 / 터널]()\n\n### 端口配置\n\n默认端口 `8314`，需要在反向代理或隧道中暴露。支持的边缘配置：\n\n- Cloudflare Tunnel\n- Caddy\n- nginx\n\n默认配置将 Pi 主机的 `http://127.0.0.1:8314` 作为代理目标。\n\n> 资料来源：[README.ko.md - 리버스 프록시 / 터널]()\n\n## 未来规划\n\n| 功能 | 状态 | 说明 |\n|------|------|------|\n| Obsidian 单向同步（piLoci → Obsidian） | ✅ 已实现 | 通过 API 导出 |\n| 完整双向同步 | 📋 计划中 | 冲突处理和流畅编辑反馈 |\n| 专用 Obsidian 插件 | 📋 计划中 | 提供更好的原生集成体验 |\n\n> 资料来源：[README.md - 笔记中描述的完整双向同步计划]()\n> 资料来源：[MEMORY.md - 笔记中描述的完整双向同步计划]()\n\n## 技术栈\n\npiLoci 的 Obsidian 集成依赖以下底层技术：\n\n| 技术 | 用途 |\n|------|------|\n| **SQLite** | 身份数据存储 |\n| **LanceDB** | 嵌入向量存储 |\n| **Redis** | 会话管理 |\n| **fastembed (ONNX)** | 本地推理嵌入计算 |\n| **Next.js** | 前端框架 |\n\n> 资料来源：[README.md - Tech stack]()\n> 资料来源：[CLAUDE.md - Local-first deployment model]()\n\n## 快速开始\n\n### 1. 获取工作区数据\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace | jq .\n```\n\n### 2. 导出为 Obsidian zip\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n### 3. 解压到 Obsidian 保管库\n\n```bash\nunzip my-project-export.zip -d ~/Obsidian/my-project-vault\n```\n\n### 4. 在 Obsidian 中打开\n\n在 Obsidian 中选择\"打开保管库\"，指向解压后的目录即可。\n\n---\n\n> **页面更新日志**\n> - 创建时间：基于 piLoci v0.3 源码\n> - 最后更新：2024 年\n> - 主要参考：README.md, MEMORY.md, web/lib/api.ts, CLAUDE.md\n\n---\n\n\n\n## 转录本摄入与 CLI\n\n### 相关页面\n\n相关主题：[MCP 服务器实现](#page-mcp-server), [策展人管道与记忆处理](#page-curator)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/piloci/cli_ingest.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/cli_ingest.py)\n- [src/piloci/api/data_portability.py](https://github.com/jshsakura/oc-piloci/blob/main/src/piloci/api/data_portability.py)\n- [clients/python/src/piloci_client/_client.py](https://github.com/jshsakura/oc-piloci/blob/main/clients/python/src/piloci_client/_client.py)\n- [scripts/piloci-stop-hook.sh](https://github.com/jshsakura/oc-piloci/blob/main/scripts/piloci-stop-hook.sh)\n \n\n# 转录本摄入与 CLI\n\npiLoci 的转录本摄入系统负责将 AI 客户端（Claude Code、OpenCode 等）产生的会话记录捕获并导入到后端进行记忆提取和向量化存储。本页详细说明摄入 CLI 工具、客户端钩子机制以及数据导出功能。\n\n## 概述\n\npiLoci 的摄入架构包含三个核心组件：\n\n| 组件 | 类型 | 职责 |\n|------|------|------|\n| `piloci-ingest` | CLI 工具 | 手动发送本地存储的转录本到服务器 |\n| 客户端钩子 | Shell/Python 脚本 | 自动捕获会话开始/结束事件 |\n| Python Client | SDK | 提供 MCP 工具接口 |\n\n资料来源：[README.md](./README.md)\n\n## 转录本摄入 CLI\n\n### 核心命令\n\n`piloci-ingest` 是 piLoci 提供的命令行工具，用于将捕获的客户端转录本发送到服务器摄入队列：\n\n```bash\npiloci-ingest --client opencode --dry-run\npiloci-ingest --client codex --history-file ~/.codex/history.json\n```\n\n### 参数说明\n\n| 参数 | 说明 | 示例值 |\n|------|------|--------|\n| `--client` | 客户端类型 | `opencode`, `codex` |\n| `--dry-run` | 模拟运行，不实际发送 | 布尔标志 |\n| `--history-file` | 历史记录文件路径 | `~/path/to/file` |\n\n资料来源：[README.md](./README.md)\n\n## 客户端钩子机制\n\n### 工作原理\n\npiLoci 通过 Claude Code 的钩子系统实现会话转录本的自动捕获。钩子在插件安装时配置到 `~/.config/piloci/` 目录。\n\n### 目录结构\n\n安装后，piLoci 在用户主目录创建以下结构：\n\n```\n~/.config/piloci/\n├── config.json # 令牌 + ingest/analyze URL（权限 0600）\n├── hook.py # SessionStart 补抓钩子（Claude 专用）\n└── stop-hook.sh # Stop 实时推送钩子（Claude 专用）\n```\n\n资料来源：[README.md](./README.md)\n\n### 插件目录布局\n\n完整的 Claude 插件目录结构：\n\n```\npiloci/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json ← SessionStart + Stop 绑定到下方脚本\n├── hooks/hook.py ← 从 /api/hook/script 下载\n├── hooks/stop-hook.sh ← 从 /api/hook/stop-script 下载\n└── .mcp.json ← memory/recall/recommend MCP 服务器\n```\n\n资料来源：[src/piloci/installer.py:25-36](src/piloci/installer.py)\n\n### 钩子类型\n\n| 钩子名称 | 触发时机 | 功能 |\n|----------|----------|------|\n| SessionStart | 会话开始 | 补抓历史转录本 |\n| Stop | 会话结束 | 实时推送当前会话转录本 |\n\n### 插件清单配置\n\n插件清单 (`plugin.json`) 包含以下元数据：\n\n```json\n{\n \"name\": \"piloci\",\n \"version\": \"\",\n \"description\": \"piLoci memory — auto-capture sessions and expose memory/recall/recommend MCP tools\",\n \"author\": {\"name\": \"piLoci\"},\n \"homepage\": \"https://github.com/jshsakura/oc-piloci\",\n \"license\": \"MIT\"\n}\n```\n\n资料来源：[src/piloci/installer.py:46-58](src/piloci/installer.py)\n\n## Python Client SDK\n\n### 客户端功能\n\nPython 客户端 (`piloci_client`) 提供 MCP 工具接口，用于与 piLoci 服务器通信：\n\n- **记忆管理**：创建、查询、删除记忆\n- **项目操作**：项目管理、成员邀请\n- **会话查询**：查看历史会话和处理状态\n\n### MCP 工具\n\n客户端注册以下 MCP 工具：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory` | 存储和检索记忆 |\n| `recall` | 基于语义搜索回忆相关记忆 |\n| `recommend` | 推荐相关上下文记忆 |\n\n资料来源：[src/piloci/installer.py](src/piloci/installer.py)\n\n## 数据导出与迁移\n\n### Vault 导出 API\n\npiLoci 提供数据导出端点，支持将工作区笔记导出为独立文件：\n\n```bash\ncurl -OJ http://localhost:8314/api/vault/my-project/export\n```\n\n### Obsidian 集成\n\n导出工作区笔记的 API：\n\n```bash\ncurl -sS http://localhost:8314/api/projects/slug/my-project/workspace\n```\n\n导出流程：\n1. 调用 API 获取项目工作区数据\n2. 将 `workspace.notes[].markdown` 写入对应路径\n3. 用该目录作为 Obsidian 保管库打开\n\n资料来源：[README.md](./README.md)\n\n### 使用场景\n\n| 场景 | 描述 |\n|------|------|\n| 团队知识中心 | 团队成员共享项目记忆 |\n| 多项目工作区 | 独立开发者管理多个项目 |\n| Obsidian 导出 | 将收集的知识导出到 Obsidian 进行整理 |\n\n## 认证与配置\n\n### 配置文件\n\n`~/.config/piloci/config.json` 包含：\n\n| 字段 | 说明 |\n|------|------|\n| `token` | 认证令牌 |\n| `ingest_url` | 摄入服务地址 |\n| `analyze_url` | 分析服务地址 |\n\n### Claude 配置\n\nClaude Code 的 MCP 服务器配置位于 `~/.claude.json`：\n\n```json\n{\n \"mcpServers\": {\n \"piloci\": {\n \"command\": \"piloci-mcp\",\n \"args\": []\n }\n }\n}\n```\n\nClaude 专用设置文件 `~/.claude/settings.json` 包含自动捕获钩子配置。\n\n资料来源：[README.md](./README.md)\n\n## 性能基线工具\n\n### profile-baseline CLI\n\npiLoci 提供性能采样工具，用于基线测试：\n\n```bash\nexport PILOCI_ENDPOINT=\"http://localhost:8314\"\nexport PILOCI_TOKEN=\"your-token\"\nexport PILOCI_PROFILE_BASELINE_SAMPLES=5\nexport PILOCI_PROFILE_BASELINE_TIMEOUT=5\nexport PILOCI_PROFILE_BASELINE_PATHS=\"/healthz,/readyz,/profilez\"\n\nuv run piloci profile-baseline\n```\n\n### 参数说明\n\n| 参数 | 环境变量 | 说明 |\n|------|----------|------|\n| `--samples` | `PILOCI_PROFILE_BASELINE_SAMPLES` | 采样次数 |\n| `--path` | `PILOCI_PROFILE_BASELINE_PATHS` | 采样路径 |\n| `--timeout` | `PILOCI_PROFILE_BASELINE_TIMEOUT` | 超时秒数 |\n| `--endpoint` | `PILOCI_ENDPOINT` | 服务地址 |\n| `--token` | `PILOCI_TOKEN` | 认证令牌 |\n\n配置优先级：CLI 参数 > 环境变量 > 默认值\n\n资料来源：[README.md](./README.md)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[AI 客户端会话开始] --> B[SessionStart 钩子触发]\n B --> C[下载历史转录本]\n C --> D[转录本摄入队列]\n \n E[会话进行中] --> F[Stop 钩子触发]\n F --> G[实时推送转录本]\n G --> D\n \n D --> H[后台 Worker 处理]\n H --> I{蒸馏状态检查}\n I -->|pending| J[LLM 提取记忆]\n I -->|done| K[直接存储]\n \n J --> L[向量嵌入 LanceDB]\n K --> L\n \n L --> M[记忆可查询]\n```\n\n## 注意事项\n\n1. **卸载**：删除 `~/.config/piloci` 目录即可完成卸载，无需修改 `~/.claude/settings.json` 或 `~/.claude.json`\n2. **令牌安全**：配置文件权限设为 0600，确保令牌不暴露\n3. **OpenCode 限制**：OpenCode 不支持钩子机制，无法进行实时会话捕获，但 MCP 工具仍可使用\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：jshsakura/oc-piloci\n\n摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Release v0.3.15。\n\n## 1. 安装坑 · 来源证据：Release v0.3.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Release v0.3.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Release v0.3.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Release v0.3.22\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.3.23\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.3.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release v0.3.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release v0.3.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release v0.3.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release v0.3.28\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | host_targets=mcp_host, claude\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：jshsakura/oc-piloci\n\n摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Release v0.3.15。\n\n## 1. 安装坑 · 来源证据：Release v0.3.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab726a10491d4c14b7fa95fd35beee64 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Release v0.3.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.16\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bc556664008b404db3fc774023736dcb | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.16 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Release v0.3.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.17\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_013d47bb794f4f13b2f8e2a5859cdabf | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.17 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Release v0.3.22\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.22\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bfd96a53e7e4d859637f79a8ee350d1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.22 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Release v0.3.23\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.23\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38baea4290d648a887a4c7575a3c8c55 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.23 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release v0.3.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.24\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_654bcb552e094dd18bcc59cfdc2a83b5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.24 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release v0.3.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2f6528bce8040c0bab4d074214b33c5 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.25 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release v0.3.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f358a19a360f476bbd41bb4e35bca86e | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.26 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release v0.3.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.27\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_973b50ab39634ba4af49b7df022af9a1 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release v0.3.28\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v0.3.28\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca63e0beff7c4da8844cdea3d52415b6 | https://github.com/jshsakura/oc-piloci/releases/tag/v0.3.28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | host_targets=mcp_host, claude\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | no_demo; severity=medium\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1219455965 | https://github.com/jshsakura/oc-piloci | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# oc-piloci - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 oc-piloci 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: piLoci is a self-hosted MCP memory server built to save tokens, I/O, and LLM calls on low-power devices like Raspberry Pi. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-database：数据库与存储层。围绕“数据库与存储层”模拟一次用户任务，不展示安装或运行结果。\n5. page-auth：认证与授权系统。围绕“认证与授权系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-database\n输入：用户提供的“数据库与存储层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-auth\n输入：用户提供的“认证与授权系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-database：Step 4 必须围绕“数据库与存储层”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-auth：Step 5 必须围绕“认证与授权系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/jshsakura/oc-piloci\n- https://github.com/jshsakura/oc-piloci#readme\n- README.md\n- PLAN.md\n- src/piloci/version.py\n- docker-compose.yml\n- .env.example\n- deploy/setup.sh\n- src/piloci/cli.py\n- src/piloci/main.py\n- src/piloci/config.py\n- src/piloci/api/v1.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 oc-piloci 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：jshsakura/oc-piloci\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U oc-piloci\n```\n\n来源：https://github.com/jshsakura/oc-piloci#readme\n\n## 来源\n\n- repo: https://github.com/jshsakura/oc-piloci\n- docs: https://github.com/jshsakura/oc-piloci#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_62149c64d2c84acca3177f8f49f930fc"
}