# https://github.com/potpie-ai/potpie 项目说明书

生成时间：2026-06-26 17:31:47 UTC

## 目录

- [Potpie 概述与快速开始](#page-overview)
- [上下文引擎与 CLI 架构](#page-architecture)
- [集成、认证与编码工具适配](#page-integrations)
- [沙箱、解析引擎与常见故障](#page-runtime-issues)

<a id='page-overview'></a>

## Potpie 概述与快速开始

### 相关页面

相关主题：[上下文引擎与 CLI 架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)
- [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)
- [potpie/integrations/README.md](https://github.com/potpie-ai/potpie/blob/main/potpie/integrations/README.md)
- [legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- [legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)
- [potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)
- [potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py)

</details>

# Potpie 概述与快速开始

## 1. 项目定位与目标

Potpie 是一个面向开发者的"代码库上下文引擎 + AI Agent 平台"。其核心思路是：把任意代码仓库解析为**知识图谱**，并在此基础上构建可调用的预构建 Agent 与自定义 Agent，让模型在"真实代码上下文"而非泛化训练数据上完成问答、生成、审查、规划等任务 资料来源：[README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)。仓库根 README 明确列出了 GitHub、Linear、Jira、Confluence 四类外部数据源集成，以及 Claude Code、OpenAI Codex、Cursor、OpenCode 等编码工具适配 资料来源：[README.md:1-30](https://github.com/potpie-ai/potpie/blob/main/README.md)。

社区已经验证的能力边界包括：在 v1.0.0 中，内置的 Coding Agent 在 SWE Bench Lite 上取得 63% 通过率；v1.0.2 引入 ColBERT/BM25 混合向量索引；v1.1.0 引入沙箱原生 Agent 执行与多后端支持；v2.0.0 作为本地优先上下文引擎的预发布版本，提供全新 CLI、守护进程工作流以及更完善的上下文图集成 资料来源：[社区版本发布记录](https://github.com/potpie-ai/potpie/releases)。

## 2. 核心架构

```mermaid
flowchart LR
    subgraph Client["客户端层"]
        UI["Potpie UI (单独仓库 potpie-ui)"]
        VSCode["VSCode 扩展"]
        Slack["Slack 集成"]
        Harness["编码工具
        Claude Code / Codex / Cursor / OpenCode"]
    end

    subgraph Core["核心服务层"]
        API["FastAPI 网关
        localhost:8001"]
        Auth["Firebase Auth
        (开发模式自动注入 dummy 用户)"]
        Router["Agent Router"]
        Tools["Tool Service / Tool Registry"]
        Conv["Conversation Service"]
        Celery["Celery Worker + Redis"]
    end

    subgraph Context["上下文与知识层"]
        KG["Neo4j 知识图谱"]
        Parsing["Rust 解析器
        (tree-sitter + rayon)"]
        Vector["ColBERT / BM25 混合索引
        (Qdrant)"]
    end

    subgraph Ext["扩展与集成层"]
        Integrations["potpie/integrations
        (Hexagonal 架构)"]
        Sandbox["potpie/sandbox
        沙箱与 Git 平台适配"]
        Obs["Loki + Grafana + Promtail"]
    end

    UI --> API
    VSCode --> API
    Slack --> API
    Harness --> API
    API --> Auth
    API --> Router
    Router --> Tools
    Router --> Conv
    Tools --> KG
    Tools --> Vector
    Celery --> Parsing
    Parsing --> KG
    API --> Integrations
    API --> Sandbox
    Core --> Obs
```

架构要点源自仓库根目录与 `legacy/README.md` 的"Architecture"小节：

- **FastAPI** 作为统一 API 入口，运行在 `localhost:8001`，自带 CORS、Logfire 链路追踪与可选 Sentry 错误捕获 资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。
- **Firebase Auth** 负责生产鉴权；开发模式下自动注入本地 dummy 用户，免去配置 Firebase 的成本 资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。
- **Celery + Redis** 作为后台任务队列，承担仓库克隆、AST 抽取与知识图谱构建等长时操作 资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。
- **Conversation Service / Agent Router / Tool Service** 三件套分别负责多轮会话记忆、按意图分派 Agent，以及向 Agent 暴露可调用工具 资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。
- **potpie/integrations** 采用六边形架构（domain / application / adapters.inbound.http / adapters.outbound）组织 OAuth 提供方、项目源与 HTTP 路由，避免与 `context-engine` 的可编辑安装冲突 资料来源：[potpie/integrations/README.md](https://github.com/potpie-ai/potpie/blob/main/potpie/integrations/README.md)。
- **Rust 解析器** 使用 `tree-sitter` 构建 AST，并通过 `rayon` 并行提取标签、节点与引用关系 资料来源：[potpie/parsing/src/tag_extract.rs:1-20](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)。
- **沙箱层** 通过 `SandboxOpClient` 抽象 PR 创建、PR 评论等操作，支持 Top-level 与 Inline 两种评论形式，并在缺少 `path` 或 `line` 时显式抛错 资料来源：[potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py)。

## 3. 快速开始

### 3.1 安装与启动

仓库根 README 提示 UI 不再作为子模块，需单独克隆并构建：

```bash
git clone https://github.com/potpie-ai/potpie-ui.git
cd potpie-ui
cp .env.template .env
pnpm build && pnpm start
```

资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。

后端服务则通过 FastAPI 暴露在 `localhost:8001`，Celery Worker 负责异步解析 资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。v2.0.0b3 已经将 `potpie==2.0.0b3` 与 `potpie-context-engine==0.1.0b3` 发布到 PyPI，CLI 与本地守护进程可在仓库外通过 `uv tool` 安装 资料来源：[v2.0.0b3 Beta 发布说明](https://github.com/potpie-ai/potpie/releases)。

### 3.2 通过 CLI 创建自定义 Agent

最简的自定义 Agent 创建示例，使用仓库 `legacy/README.md` 中展示的 `auto` 端点：

```bash
curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "An agent that takes stacktrace as input and gives root cause analysis and proposed solution as output"}'
```

资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)。

### 3.3 注册自定义工具

工具元数据通过 `ToolMetadata` 描述，包含 `id`、`name`、`description`、`tier`（low / medium / high）、`category`，并支持 `defer_loading`、`aliases`、`local_mode_only` 等高级字段。Agent 通过 **AllowList** 或 **Category** 解析工具，而非硬编码列表 资料来源：[legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)。

`local_mode`（仅 VSCode 扩展触发）允许在请求层按 `User-Agent` 决定工具可见性，例如 `execute_terminal_command` 在 `local_mode=False` 时被排除 资料来源：[legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)。

### 3.4 常用工具集合

| 工具分类 | 典型能力 | 来源 |
| --- | --- | --- |
| Codebase Q&A | 解释函数、特性与架构 | [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md) |
| Code Generation | 基于真实代码生成与重构 | [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md) |
| Spec Agent | 产出 PRD / 架构文档 | [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md) |
| Confluence Tools | 空间、页面、评论读写 | [legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md) |
| Sandbox PR 工具 | 创建 PR / 评论 PR（Top-level + Inline） | [potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py) |

## 4. 集成、扩展与可观测性

### 4.1 外部集成

- **GitHub / Linear / Jira / Confluence**：仓库根 README 列出的四大集成，分别索引仓库与 PR、团队与项目、问题状态、空间与决策 资料来源：[README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)。
- **编码工具适配**：通过 CLAUDE.md / AGENTS.md 等约定文件，把 Potpie 的提示词与技能注入 Claude Code、Codex、Cursor、OpenCode 资料来源：[README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)。
- **Bitbucket**：社区正在筹建统一的 Atlassian CLI 登录，期望与 Jira、Confluence 共享同一套接入路径 资料来源：[issue #911](https://github.com/potpie-ai/potpie/issues/911)。

### 4.2 沙箱与 Git 平台

`sandbox.api.client.SandboxOpClient.create_pull_request` 接受 `head_branch`、`base_branch`、`reviewers`、`labels` 等参数，并通过注入的 `GitPlatformProvider` 完成鉴权链；评论接口则细分为"顶层评论"与"行内评论"两类，`path` 与 `line` 必须同时给出，否则抛 `SandboxOpError` 资料来源：[potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py)。这意味着 PR 评论可以脱离工作树从纯分析流程触发（例如 `review-pr` Agent）。

### 4.3 可观测性

部署模块采用 **Loki + Grafana + Promtail** 组合：

- **标签**（低基数）：`service`、`env`、`level`、`container`。
- **结构化元数据**（高基数）：`request_id`、`conversation_id`、`run_id`、`user_id`、`task_id`、`project_id`、`logger`。
- 高基数 ID 通过 `obs_context` / `obs_fields` 平铺到 JSON 输出，再由 Promtail 提升为结构化字段，避免污染标签索引 资料来源：[legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)。

## 5. 已知问题与踩坑提示

社区讨论中频繁出现的痛点集中在 CLI 与解析流程，建议新用户预先留意：

- **CLI 版本与状态命令**：`potpie --version` 在某些版本下报 `No such option: --version`；`potpie status` 的默认输出与"Agent 准备就绪"契约不一致，社区正在推动二者对齐 资料来源：[issue #924](https://github.com/potpie-ai/potpie/issues/924)、[issue #926](https://github.com/potpie-ai/potpie/issues/926)。
- **本地仓库解析**：早期版本在解析本地路径时容易失败，需确认 Celery Worker 与 Neo4j 已启动，并使用最新文档中的端点 资料来源：[issue #235](https://github.com/potpie-ai/potpie/issues/235)。
- **仓库标识符**：历史上 `repo_name` 与 `repo_path` 双变量贯穿解析流程，社区已提案合并为单一仓库标识符，以减少条件分支 资料来源：[issue #517](https://github.com/potpie-ai/potpie/issues/517)。
- **Embedder 维度对齐**：`HashingEmbedder` 默认输出 256 维，而大多数向量索引创建器默认 1536 维（OpenAI `text-embedding-3-small`），本地离线场景需显式同步维度 资料来源：[issue #909](https://github.com/potpie-ai/potpie/issues/909)。

## 6. See Also

- 知识图谱解析流水线：[potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)
- 工具注册中心：[legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- 集成六边形布局：[potpie/integrations/README.md](https://github.com/potpie-ai/potpie/blob/main/potpie/integrations/README.md)
- 沙箱 API 客户端：[potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py)
- 可观测性部署指引：[legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)

---

<a id='page-architecture'></a>

## 上下文引擎与 CLI 架构

### 相关页面

相关主题：[Potpie 概述与快速开始](#page-overview), [集成、认证与编码工具适配](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)
- [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)
- [legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- [legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)
- [legacy/app/modules/intelligence/tools/jira_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/jira_tools/README.md)
- [legacy/app/modules/intelligence/tools/linear_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/linear_tools/README.md)
- [legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)
- [potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)
- [potpie/context-engine/adapters/inbound/http/api/v1/context/event_payload.py](https://github.com/potpie-ai/potpie/blob/main/potpie/context-engine/adapters/inbound/http/api/v1/context/event_payload.py)
- [potpie/context-engine/adapters/inbound/http/ui/frontend/src/App.tsx](https://github.com/potpie-ai/potpie/blob/main/potpie/context-engine/adapters/inbound/http/ui/frontend/src/App.tsx)
</details>

# 上下文引擎与 CLI 架构

## 概述

Potpie v2 将项目拆分为两个 PyPI 包：`potpie`（CLI 与守护进程入口）和 `potpie-context-engine`（上下文引擎核心）。CLI/守护进程负责本地编排、状态查询与代理触发，上下文引擎负责对代码库、问题跟踪与文档系统建立可查询的图谱（context graph）。资料来源：[README.md](https://github.com/potpie-ai/potpie/blob/main/README.md) 与 [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md) 中描述的 pre-built agents（Codebase Q&A、Codegen、Spec、Custom Agent）依然由 CLI/守护进程调用，v2 的目标是为这些 agent 提供更快、更本地化的上下文供给。

CLI 与守护进程以"本地优先"为设计原则：用户安装 `potpie` 后即可在本地启动 daemon，由 daemon 拉起上下文引擎实例并暴露 HTTP API；CLI 既可作为人类可读的命令入口，也可作为自动化入口（如 CI 中的 `potpie status` 健康检查）。资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)（Setup Guide 与 API Access 小节）以及社区 issue #926（"Align `potpie status` default with agent readiness contract"）均指出，`potpie status` 应返回 context/pot/backend/skill 的就绪状态，而非仅返回集成鉴权状态。

## 分层与包结构

上下文引擎遵循六边形（端口/适配器）架构，将 inbound 入口、application 服务与 outbound 适配器分离：

```mermaid
graph TD
    CLI[CLI / host_cli.py] --> Daemon[Daemon / host/daemon.py]
    Daemon --> API[HTTP API / adapters/inbound/http/api/v1]
    API --> UI[UI Frontend / adapters/inbound/http/ui/frontend]
    API --> App[Application Services<br/>setup_orchestrator.py]
    App --> Domain[Domain Ports<br/>context_graph.py, semantic_mutations.py]
    Domain --> Out[Outbound Adapters<br/>GitHub / Jira / Linear / Confluence / Sentry]
    Out --> Providers[(External Providers)]
```

- `adapters/inbound/cli/host_cli.py` 提供命令行入口；
- `host/daemon.py` 负责常驻进程生命周期；
- `bootstrap/container.py` 负责依赖装配；
- `application/services/setup_orchestrator.py` 协调初始化流程；
- `domain/ports/context_graph.py` 与 `domain/semantic_mutations.py` 描述图谱与破坏性写操作的契约（包含 `approval` 与 `auto_commit` 标志，社区 issue #902 强调破坏性 mutation 必须经过审核）。

资料来源：[potpie/context-engine/adapters/inbound/http/api/v1/context/event_payload.py](https://github.com/potpie-ai/potpie/blob/main/potpie/context-engine/adapters/inbound/http/api/v1/context/event_payload.py) 显示 ingestion 事件载荷统一在 API 边界序列化，包含 `pot_id`、`provider`、`repo_name`、`status`、`lifecycle_status`、`dedup_key`、`correlation_id` 等字段，跨 inbound/outbound 边界保持一致。

## CLI 与 Daemon 工作流

CLI 命令通过 Click/Typer 等机制注册到 `host_cli.py`，由 daemon 接收并转发到上下文引擎。社区反馈（issue #924 "Add root CLI version command"）指出当前 `potpie --version` 失败，建议在根命令暴露版本号以便 `uv tool` 安装校验；这与 v2 "cleaner CLI and daemon workflows" 的目标一致。资料来源：[README.md](https://github.com/potpie-ai/potpie/blob/main/README.md) 列出的 Atlassian 集成（Jira/Confluence/未来 Bitbucket，见 issue #911）走统一的"unified Atlassian login"路径，由 CLI 引导 OAuth 流程后把 token 写入 SecretManager。

工具注册是 CLI 暴露能力的关键：`legacy/app/modules/intelligence/tools/registry/README.md` 描述了 `ToolMetadata`、`ToolTier`、`ToolCategory` 与 `AllowListDefinition` 的元数据模型，并通过 `local_mode` 区分 VS Code 扩展等本地调用方。CLI 在装配 agent 时按 allow-list 与 category 解析工具，避免硬编码。

## 集成、解析与已知问题

- **解析管线**：`potpie/parsing/src/tag_extract.rs` 使用 `tree-sitter` 与 `rayon` 并行解析多种语言，将 `TagPayload`、`NodePayload`、`RelationshipPayload` 写入知识图谱。资料来源：[potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs) 顶部 import 段。
- **集成工具**：Jira、Linear、Confluence、Sentry、GitHub 各自以 `*_client.py` + LangChain `StructuredTool` 的模式实现，并通过 `check_*_integration_exists(user_id, db)` 在执行前校验连接。资料来源：[legacy/app/modules/intelligence/tools/jira_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/jira_tools/README.md)、[legacy/app/modules/intelligence/tools/linear_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/linear_tools/README.md)、[legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)。
- **可观测性**：Loki + Promtail 通过 `service/env/level/container` 等低基数标签和 `request_id`、`run_id`、`user_id` 等高基数结构化元数据区分日志维度。资料来源：[legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)。
- **已暴露问题**：issue #909 指出 `HashingEmbedder` 输出 256 维而索引默认 1536 维，需在向量索引创建处显式对齐；issue #899 指出 `AgentContextTools.context_resolve` 在 `_ResolutionServiceShim` 拆除后已成永久死代码；issue #235 反映本地仓库解析失败常与 daemon 启动或凭证配置相关。

## See Also

- [Potpie v2.0.0 Pre-release Notes](https://github.com/potpie-ai/potpie/releases/tag/v2.0.0)
- [Confluence Tools Reference](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)
- [Tool Registry Schema](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)

---

<a id='page-integrations'></a>

## 集成、认证与编码工具适配

### 相关页面

相关主题：[Potpie 概述与快速开始](#page-overview), [沙箱、解析引擎与常见故障](#page-runtime-issues)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)
- [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)
- [legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- [legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)
- [legacy/app/modules/intelligence/tools/jira_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/jira_tools/README.md)
- [potpie/sandbox/sandbox/api/client.py](https://github.com/potpie-ai/potpie/blob/main/potpie/sandbox/sandbox/api/client.py)
- [potpie/context-engine/adapters/inbound/http/ui/frontend/src/theme.ts](https://github.com/potpie-ai/potpie/blob/main/potpie/context-engine/adapters/inbound/http/ui/frontend/src/theme.ts)
- [potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)

</details>

# 集成、认证与编码工具适配

## 1. 概述

Potpie 的"集成、认证与编码工具适配"层承担了三个相互衔接的职责：把外部系统（GitHub、Linear、Jira、Confluence 等）抽象为可被 Agent 调用的工具;管理这些工具在 CLI/VSCode/服务端等不同场景下的认证链路;并把上下文能力以 skill 形式投放到 Claude Code、OpenAI Codex、Cursor、OpenCode 等编码工作台中。在 v2.0.0 的"local-first context engine"重构下，该层从原本直接挂在 `legacy/app/modules/intelligence/tools/` 下的 LangChain 工具集合，演进为 v2 中 `context-engine/adapters/` 下的入站/出站适配器分层（[potpie v2.0.0 release notes](https://github.com/potpie-ai/potpie/releases/tag/v2.0.0)）。

资料来源：[README.md:1-15]()。

## 2. 外部系统集成矩阵

根 README 中的"Integrations"与"Coding harnesses"两表，Potpie 当前支持的集成分两类：

| 类别 | 集成对象 | 主要用途 |
|------|---------|---------|
| 集成源 | GitHub、Linear、Jira、Confluence | 索引仓库、Issue、PR、文档与决策上下文 |
| 编码工作台 | Claude Code、OpenAI Codex、Cursor、OpenCode | 注入 Potpie 指令与 skill |

资料来源：[README.md:5-25]()。

在 v1.0.2 之后，解析层从原来的 `create_graph_rs` Rust 模块重构为 `app/src/parsing/` 子包，并通过 ColBERT/BM25 混合索引提升代码搜索质量，这为上述集成源中"被索引对象"的语义召回提供了基础设施（[v1.0.2 release](https://github.com/potpie-ai/potpie/releases/tag/1.0.2)）。

## 3. 认证链路

### 3.1 Jira 集成

Jira 工具以 `JiraClient` 为底层，封装官方 Jira Python 库，提供 OAuth2 + token refresh 能力。`get_jira_client_for_user(user_id, db)` 从数据库中按用户读取其 Jira 集成凭据并构造已认证客户端，再被 6 个 LangChain 工具（get/search/create/update/comment/transition）共用。System Agent `jira_integration_agent`（位于 `app/modules/intelligence/agents/chat_agents/system_agents/`）负责把自然语言翻译为 JQL 并调度这些工具。

资料来源：[legacy/app/modules/intelligence/tools/jira_tools/README.md:50-70]()。

### 3.2 Confluence 集成

Confluence 工具通过 OAuth 2.0 (3LO) 接入 Atlassian REST API v2。所有工具在执行前都会调用 `check_confluence_integration_exists(user_id, db)`，未授权则返回标准化的错误结构 `{success: False, error: ...}`。注意 Confluence 使用 HTML storage 格式而非 Jira 的 ADF，且不支持 webhook，这与社区中"统一 Atlassian 登录"的诉求（#911）紧密相关——一旦 Jira/Confluence/Bitbucket 走同一登录流，前置 `check_*_integration_exists` 的调用模式可以收敛。

资料来源：[legacy/app/modules/intelligence/tools/confluence_tools/README.md:128-148]()。

### 3.3 v2 的 CLI 认证适配

v2 把认证逻辑下沉到 `context-engine/adapters/outbound/cli_auth/`，CLI 侧对应 `adapters/inbound/cli/auth/`，典型如 `atlassian_client.py`、`atlassian_auth.py`、`github_commands.py`。这一分层让 #911 描述的"统一 Atlassian 登录"可以在 CLI 层提供单一入口，而后端凭据获取则由同一出站适配器复用，从而避免每个 Atlassian 产品各自维护一套登录流。

```mermaid
flowchart LR
  User[用户] --> CLI[potpie CLI]
  CLI --> Auth[inbound/cli/auth]
  Auth --> Out[outbound/cli_auth]
  Out --> Atlassian[Atlassian OAuth]
  Out --> GitHub[GitHub OAuth]
  Atlassian --> JiraTools[Jira 工具集]
  Atlassian --> ConfTools[Confluence 工具集]
  GitHub --> GHConn[GitHub 连接器]
```

## 4. 工具注册与本地模式

`legacy/app/modules/intelligence/tools/registry/` 是 Agent↔Tool 绑定的单一事实来源。每条 `ToolMetadata` 除了基础字段（id、name、tier、category）外，还携带 `local_mode_only`、`non_local_only`、`defer_loading`、`aliases` 等控制位；当请求来自 VSCode 扩展（通过 `User-Agent` 判定 `local_mode=True`）时，`execute_terminal_command` 这类本地受限工具会被下发，而 `show_diff` 等 UI 可接管工具则会被排除。

资料来源：[legacy/app/modules/intelligence/tools/registry/README.md:5-22]()。

## 5. 编码工具与沙箱接入

v1.1.0 引入"沙箱原生 Agent 执行"，Agent 不再直接操作宿主机文件系统，而是经由 `potpie/sandbox/sandbox/api/client.py` 中的沙箱客户端创建/复用工作区。客户端方法如 `comment_on_pull_request` 在缺少 `path`/`line` 时会抛 `SandboxOpError`，并对 inline review comment 与顶层 PR comment 做了区分——这种严格的前置校验直接关系到 PR 评论是否被误投递到错误的行号上。

资料来源：[potpie/sandbox/sandbox/api/client.py:30-70]()。

前端 UI 通过 `theme.ts` 中的 `TYPE_CATEGORY` 与 `KIND_PALETTE` 把上下文图谱中的节点（`Period`、`Policy`、`Decision` 等）按类别分桶着色，让 Agent 在 Claude Code / Cursor 等工作台中可视化时能与活动类型（feature/fix/chore/security/removal）对应起来。

资料来源：[potpie/context-engine/adapters/inbound/http/ui/frontend/src/theme.ts:1-40]()。

## 6. 已知问题与演进方向

- **#911** 推动 Jira/Confluence/Bitbucket 走统一 Atlassian 登录路径，减少重复的 OAuth 注册流程。
- **#909** 暴露了 `HashingEmbedder`（256 维）与默认向量索引（1536 维）之间的维度不一致；外部集成索引使用 OpenAI `text-embedding-3-small` 时尤其需要确认 embedder 维度对齐。
- **#517** 要求把 `repo_name` 与 `repo_path` 合并为单一 Repository Identifier，这将影响所有集成源在写入图谱时使用的键空间。
- **#924 / #926** 指向 CLI 表面契约：`potpie --version` 与 `potpie status` 的默认行为需要与"Agent 准备就绪"语义对齐，这对新接入的编码工作台首启体验至关重要。

## See Also

- 解析与索引管线：[v1.0.2 release notes](https://github.com/potpie-ai/potpie/releases/tag/1.0.2)
- 本地优先上下文引擎：[v2.0.0 release notes](https://github.com/potpie-ai/potpie/releases/tag/v2.0.0)
- Tool Registry Schema：[legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- PyPI Beta：[Potpie v2.0.0b3 Beta](https://github.com/potpie-ai/potpie/releases/tag/v2.0.0)

---

<a id='page-runtime-issues'></a>

## 沙箱、解析引擎与常见故障

### 相关页面

相关主题：[上下文引擎与 CLI 架构](#page-architecture), [集成、认证与编码工具适配](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)
- [README.md](https://github.com/potpie-ai/potpie/blob/main/README.md)
- [potpie/parsing/src/lib.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/lib.rs)
- [potpie/parsing/src/tag_extract.rs](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)
- [legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- [legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)
- [legacy/app/modules/intelligence/tools/jira_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/jira_tools/README.md)
- [legacy/app/modules/intelligence/tools/linear_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/linear_tools/README.md)
- [legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)
</details>

# 沙箱、解析引擎与常见故障

## 概述与解析引擎

Potpie 是一个面向代码库的 AI 代理平台，自 v2.0.0b3 起作为 `potpie` 与 `potpie-context-engine` 两个 PyPI 包分发，定位为"本地优先的上下文引擎 + 沙箱原生代理执行"。v1.1.0 之后代理不再直接读写宿主机文件系统，而是运行在隔离执行后端中。

资料来源：[legacy/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)

整条解析链路由 Rust 内核驱动，其 Python 入口在 `potpie/parsing/src/lib.rs` 中通过 `pyo3` 暴露五大模块：`code_index`（并行构建代码索引）、`fff_search`（fzf‑style 文件名/内容模糊索引）、`git`（`bare_clone`、`list_files`）、`parse`（`process_file`、`index` 入口）与 `tag_extract`（基于 tree‑sitter 的结构化标签与图谱抽取）。

资料来源：[potpie/parsing/src/lib.rs:1-20](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/lib.rs)

`tag_extract.rs` 使用 `rayon` 并行遍历文件，通过 `tree_sitter::Query` + `QueryCursor` 抽取 `TagPayload`、`NodePayload`、`RelationshipPayload`，并以 `ReferenceRecord`、`DefinitionMetadata` 在线程间共享，最终聚合成 `GraphPayload` 写回 Neo4j。

资料来源：[potpie/parsing/src/tag_extract.rs:1-50](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/tag_extract.rs)

## 沙箱与代理执行

v1.1.0 引入"沙箱原生代理执行 + 多后端支持 + bare‑repo 缓存"，代理在隔离沙箱中工作，避免重复克隆开销，也避免把宿主 shell 暴露给模型。v2 进一步把沙箱做成可拔插后端，CLI 与 daemon 解耦。

工具粒度由统一注册表管理。`local_mode_only=True` 的工具（如 `execute_terminal_command`、`terminal_session_output`、`terminal_session_signal`）只在 `local_mode=True`（如 VSCode 扩展）时下发；`add_when_non_local` / `exclude_in_local` 则在 allow‑list 级别再过滤一次（如 `show_diff` 由扩展自行处理）。

资料来源：[legacy/app/modules/intelligence/tools/registry/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)

## 工具注册表与外部集成

工具元数据统一在 `registry/README.md` 中以 `ToolMetadata` 定义：`ToolTier`（`low`/`medium`/`high`）、`ToolCategory`（如 `search`、`code_changes`、`terminal`、`integration_jira`），v1.1.0 起额外支持 `read_only`、`destructive`、`idempotent`、`requires_confirmation` 标志，赋予注册表级别的安全语义。

外部集成遵循同一模式：先通过 OAuth/API Key 认证，再把外部 API 包装为 LangChain `StructuredTool`。Jira 提供 6 个工具（`get_issue` / `search` / `create` / `update` / `comment` / `transition`），由 `jira_integration_agent` 通过自然语言调度；Confluence 提供 7 个工具，基于 REST API v2 + OAuth 2.0 (3LO)，使用 HTML 存储格式与 CQL；Linear 通过 `SecretManager.create_integration_keys` 同时支持全局环境变量与每用户密钥。

资料来源：
- [legacy/app/modules/intelligence/tools/jira_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/jira_tools/README.md)
- [legacy/app/modules/intelligence/tools/confluence_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/confluence_tools/README.md)
- [legacy/app/modules/intelligence/tools/linear_tools/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/linear_tools/README.md)

## 常见故障与社区报告

| 现象 | 根因（社区/源码证据） | 缓解措施 |
| --- | --- | --- |
| 本地仓库解析失败 | `repo_name` / `repo_path` 双标识符不一致，路径克隆逻辑在多个模块重复 | 合并为单一仓库标识符后再触发 Celery 任务 |
| 嵌入维度不匹配 | OSS `HashingEmbedder` 输出 256 维，而向量索引默认 1536 | 通过 `getattr(self._embedder, "_DEFAULT_DIMENSIONS", 1536)` 显式对齐 |
| 死代码 / 破坏性变更 | `_ResolutionServiceShim` 拆除后 `context_resolve` 成为永久死存根；破坏性语义变更存在绕过审核的风险 | 移除 stub；对 `destructive` 类型强制 `requires_confirmation` |
| CLI 版本号缺失 | `potpie --version` 抛出 `No such option` | 在根 CLI 注册 `--version` |
| `potpie status` 错配 | 默认返回集成鉴权而非代理契约所需的 `context_status` | 把 `context_status`（context/pot/backend/skill 就绪度 + 推荐下一步）作为默认返回 |

高频社区反馈还包括 #241（开发者邮件投诉）等运营问题。可观测性侧通过 Loki/Promtail 的结构化元数据（`request_id`、`conversation_id`、`run_id`、`task_id`、`project_id`）做关联追踪：高基数 ID 放在 `obs_context` / `obs_fields`，Promtail 提升为 structured metadata 而非 label，便于跨服务复现上述解析与执行故障。

资料来源：[legacy/deploy/observability/README.md](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)

## See Also

- [README.md 顶层集成与 harness 列表](https://github.com/potpie-ai/potpie/blob/main/README.md)
- [legacy/README.md 架构总览与 Pre‑built Agents](https://github.com/potpie-ai/potpie/blob/main/legacy/README.md)
- [potpie/parsing/src/lib.rs Rust 解析引擎入口](https://github.com/potpie-ai/potpie/blob/main/potpie/parsing/src/lib.rs)
- [legacy/app/modules/intelligence/tools/registry/README.md 工具注册表与 AllowList](https://github.com/potpie-ai/potpie/blob/main/legacy/app/modules/intelligence/tools/registry/README.md)
- [legacy/deploy/observability/README.md Loki/Grafana/Promtail 部署说明](https://github.com/potpie-ai/potpie/blob/main/legacy/deploy/observability/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：potpie-ai/potpie

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Create shared environment resolution for CLI, daemon, and child processes。

## 1. 安装坑 · 来源证据：Create shared environment resolution for CLI, daemon, and child processes

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Create shared environment resolution for CLI, daemon, and child processes
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/potpie-ai/potpie/issues/946 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Add root CLI version command

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add root CLI version command
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/potpie-ai/potpie/issues/924 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/potpie-ai/potpie | host_targets=codex, chatgpt

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/potpie-ai/potpie | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/potpie-ai/potpie | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/potpie-ai/potpie | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/potpie-ai/potpie | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/potpie-ai/potpie | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/potpie-ai/potpie | release_recency=unknown

<!-- canonical_name: potpie-ai/potpie; human_manual_source: deepwiki_human_wiki -->