potpie 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

potpie 项目

基于规范驱动开发，专为大型代码库打造。

Potpie 概述与快速开始

Potpie 是一个面向开发者的"代码库上下文引擎 + AI Agent 平台"。其核心思路是：把任意代码仓库解析为知识图谱，并在此基础上构建可调用的预构建 Agent 与自定义 Agent，让模型在"真实代码上下文"而非泛化训练数据上完成问答、生成、审查、规划等任务资料来源：README.md。仓库根 README 明确列出了 GitHub、Linear、Jira、Co...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 安装与启动

继续阅读本节完整说明和来源证据。

章节 3.2 通过 CLI 创建自定义 Agent

继续阅读本节完整说明和来源证据。

章节 3.3 注册自定义工具

继续阅读本节完整说明和来源证据。

1. 项目定位与目标

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

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

2. 核心架构

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

3. 快速开始

3.1 安装与启动

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

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

资料来源：legacy/README.md。

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

3.2 通过 CLI 创建自定义 Agent

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

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。

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。

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

3.4 常用工具集合

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

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

4.1 外部集成

GitHub / Linear / Jira / Confluence：仓库根 README 列出的四大集成，分别索引仓库与 PR、团队与项目、问题状态、空间与决策资料来源：README.md。
编码工具适配：通过 CLAUDE.md / AGENTS.md 等约定文件，把 Potpie 的提示词与技能注入 Claude Code、Codex、Cursor、OpenCode 资料来源：README.md。
Bitbucket：社区正在筹建统一的 Atlassian CLI 登录，期望与 Jira、Confluence 共享同一套接入路径资料来源：issue #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。这意味着 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。

5. 已知问题与踩坑提示

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

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

6. See Also

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

资料来源：legacy/README.md。

上下文引擎与 CLI 架构

Potpie v2 将项目拆分为两个 PyPI 包：potpie（CLI 与守护进程入口）和 potpie-context-engine（上下文引擎核心）。CLI/守护进程负责本地编排、状态查询与代理触发，上下文引擎负责对代码库、问题跟踪与文档系统建立可查询的图谱（context graph）。资料来源：README.md 与 legacy/README.md 中描述的 p...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

Potpie v2 将项目拆分为两个 PyPI 包：potpie（CLI 与守护进程入口）和 potpie-context-engine（上下文引擎核心）。CLI/守护进程负责本地编排、状态查询与代理触发，上下文引擎负责对代码库、问题跟踪与文档系统建立可查询的图谱（context graph）。资料来源：README.md 与 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（Setup Guide 与 API Access 小节）以及社区 issue #926（"Align potpie status default with agent readiness contract"）均指出，potpie status 应返回 context/pot/backend/skill 的就绪状态，而非仅返回集成鉴权状态。

分层与包结构

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

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 显示 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 列出的 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 顶部 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、legacy/app/modules/intelligence/tools/linear_tools/README.md、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。
已暴露问题：issue #909 指出 HashingEmbedder 输出 256 维而索引默认 1536 维，需在向量索引创建处显式对齐；issue #899 指出 AgentContextTools.context_resolve 在 _ResolutionServiceShim 拆除后已成永久死代码；issue #235 反映本地仓库解析失败常与 daemon 启动或凭证配置相关。

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 Jira 集成

继续阅读本节完整说明和来源证据。

章节 3.2 Confluence 集成

继续阅读本节完整说明和来源证据。

章节 3.3 v2 的 CLI 认证适配

继续阅读本节完整说明和来源证据。

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）。

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

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 产品各自维护一套登录流。

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 准备就绪"语义对齐，这对新接入的编码工作台首启体验至关重要。

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与解析引擎

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

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

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

资料来源：potpie/parsing/src/tag_extract.rs:1-50

沙箱与代理执行

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

工具注册表与外部集成

工具元数据统一在 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 同时支持全局环境变量与每用户密钥。

资料来源：

常见故障与社区报告

现象	根因（社区/源码证据）	缓解措施
本地仓库解析失败	`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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Create shared environment resolution for CLI, daemon, and child processes

可能增加新用户试用和生产接入成本。

medium 来源证据：Add root CLI version command

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

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

来源：Doramagic 发现、验证与编译记录