Potpie CLI 深度解析：上下文图谱的命令入口、Agent 兼容命令与跨平台 Skill 安装机制

Potpie CLI 深度解析上下文图谱的命令入口、Agent 兼容命令与跨平台 Skill 安装机制【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本篇以 Potpie 仓库中potpie/cli/README.md为骨架系统讲解 Potpie CLIconsole 脚本potpie的入口架构、命令分组装配方式、面向 Agent 的四个兼容命令resolve/search/record/status的响应契约、贯穿所有命令的退出码与结构化错误契约以及通过potpie skills install把技能包物化到 Claude Code、Cursor、Codex、OpenCode 等 Agent 运行时的完整机制。读完你可以独立安装并驱动该 CLI理解其“人用和 Agent 用同一套命令面”的设计并能基于源码路径复核每一项结论。一、CLI 在 Potpie 中的定位Potpie 是面向 AI 原生 SDLC 的 Context Graph上下文图谱工具potpieCLI 是这张图谱的命令入口上下文操作读图、记录、状态检查通过类型化的引擎客户端EngineClient路由产品操作pot 管理、daemon 生命周期、技能安装等则使用 Potpie 自有的、来自单一本地运行时组合runtime composition的服务模块。README 对入口与结构的官方描述如下入口potpie/cli/main.py在 pyproject.toml 的[project.scripts]中注册为potpieconsole 脚本[project.scripts] potpie potpie.cli.main:main potpie-daemon potpie.daemon.__main__:main命令分组potpie/cli/commands/ 目录每个模块对应cli-flow.md的一个章节bootstrap、query、pots/source、daemon、ledger、graph、timeline、backend、skills、cloud。横切契约potpie/cli/commands/_common.py 拥有--json输出、退出码映射0 ok / 1 validation / 2 unavailable / 3 degraded / 4 auth、结构化错误形状code/message/detail/recommended_next_action以及 active-pot 解析。未构建的能力以结构化的 not-implemented 契约CapabilityNotImplemented呈现绝不打 traceback。权威参考文档为 docs/context-graph/cli-flow.md完整命令目录、flag、local/managed 两种 profile 与输出契约端到端架构见 docs/context-graph/architecture.md。1.1 入口装配一个 Typer 根应用从 potpie/cli/main.py 的build_app()可以看到完整的装配逻辑创建一个typer.Typer根应用no_args_is_helpTrue不带参数即打印帮助app.callback暴露三个全局选项--json机器可读输出、--verbose/-v错误时打印详细 traceback、--version打印版本并退出eager 回调顶层命令由四个 registrar 注册query_cmdsresolve/search/record、bootstrapsetup/doctor/whoami/use/config/status、auth_cmds、ui_cmds其余分组以add_typer子应用挂载pot、source、daemon、ledger、graph、timeline、backend、skills、cloud带 “Coming soon” 面板因为 managed 路由仍在开发中、telemetry。根帮助文本_ROOT_HELP给出的首跑三件套是potpie setup --repo . --agent harness potpie doctor potpie status根回调在每次启动时还完成加载运行时环境变量ensure_runtime_environment_loaded()、配置错误输出与日志、绑定遥测上下文、配置 Sentry 与产品分析。1.2 上下文操作如何路由daemon 与 in-process 双模式CONTEXT_ENGINE_HOST_MODE环境变量决定上下文操作走哪条路且不改变任何命令契约见 main.py 模块文档与 potpie/cli/commands/_common.py 的get_engine_client()默认daemonget_engine_client()先做 canonical daemon 发现load_daemon_connection再建立DaemonEngineClient并执行带 bearer token 的握手发现失败会给出结构化错误codedaemon_discovery_unavailable建议动作run potpie daemon restart。in_process返回LocalEngineClient走同一套类型化操作处理器与 Resource Manager适合调试。命令体因此保持“薄”上下文命令调用run_engine_operation(...)产品命令调用get_root_runtime()提供的有限根服务get_pot_service、get_auth_service、get_skill_service等全部在进程级缓存。二、Agent 兼容命令四工具契约README 的核心章节之一是 Agent 兼容命令。CLI 对外暴露四个契约各不相同的兼容命令它们与graph workbench骑乘同一套图内核并非“等待 V2 的遗留 V1 面”命令用途响应契约potpie resolve任务的主 bounded-context 包裹返回AgentEnvelope无服务端合成potpie search窄化跟进查询返回AgentEnvelope无服务端合成potpie record记录一条持久学习decision、fix、preference……返回记录回执含status、record_id、mutations_appliedpotpie status所选 pot 与 scope 的就绪信息返回 readiness 信息与推荐 recipe从 potpie/cli/commands/query.py 的源码可以逐一印证这些契约resolve接受task位置参数与--intent默认feature、--include逗号分隔的 include 家族、--modefast | balanced | verify | deep、--pot构造EngineResolveRequest后经EngineClient.resolve()返回 envelopesearch接受query位置参数与--include、--pot返回同一AgentEnvelope形状pot_id、intent、overall_confidence、items[]、coverage[]——其中coverage的graph_view字段是向graph read迁移的指针record要求--type与--summary可选--scopek:v形式如service:inventory-svc返回receipt.status / receipt.record_id / receipt.mutations_applied与 README 描述的回执字段完全一致。status命令定义在 potpie/cli/commands/bootstrap.py它是上下文数据面就绪度与根运行时状态的组合报告daemon、backend、pot、skill 状态支持--intent、--harness默认claude、--pot。两个边界行为值得注意--host是已弃用的 no-opreadiness 现在是默认行为--verify会直接失败并指路potpie auth status --verify——集成凭证状态有意不在这四工具面内本地 provider 认证状态请用potpie auth status [--verify]查询。三、横切契约退出码、结构化错误与 pot 解析README 强调 potpie/cli/commands/_common.py 是跨命令契约的“唯一所有者”。源码印证如下3.1 退出码映射# potpie/cli/commands/_common.py L43-L47 EXIT_OK 0 EXIT_VALIDATION 1 EXIT_UNAVAILABLE 2 EXIT_DEGRADED 3 EXIT_AUTH 4退出码含义0成功1命令 / 校验失败2daemon / API / 依赖不可用含CapabilityNotImplemented、ContextEngineDisabled3部分 / 降级结果4认证 / 权限失败3.2contract()错误边界与结构化错误形状contract()上下文管理器_common.py把领域异常一一映射为上述退出码EngineClientError按错误category分派authentication/authorization→ 4selection/domain→ 1其余 → 2CapabilityNotImplemented→ codenot_implemented、退出码 2ContextEngineDisabled→ 提示用potpie doctor检查后端/daemon 就绪PotNotFound→ 提示potpie pot list或potpie setup。失败时fail()输出统一形状{ code: ..., message: ..., detail: null, recommended_next_action: ... }--json模式下错误也是同样形状的 JSON保证脚本/Agent 可以稳定解析人类模式下则渲染为“动作导向摘要 建议的下一步命令”。emit()同理--json输出稳定可加additive的 JSON 字段否则输出人类可读块。3.3 pot 作用域解析resolve_pot_id()/resolve_pot_scope()_common.py的优先级为显式--pot仓库默认绑定repo-default已注册仓库匹配active pot 优先平局否则ambiguous_potactive pot否则no_active_pot。一个反直觉但有保护意味的细节source add传infer_from_repoFalse——因为注册仓库这条命令本身就是建立repo→pot 映射的动作若从既有注册推断目标 pot可能把新 source 路由到错误的 pot。此外confirm_destructive_operation()实现了破坏性命令的确认策略JSON 或非 TTY 环境下缺少显式确认 flag 会在读取 stdin 或派发操作之前直接失败codedestructive_confirmation_required交互式 TTY 才允许提示确认。四、安装与运行仓库内开发 vs 已发布包README 的 “Local install (this repo)” 一节给出仓库内开发安装路径Makefile 中可完整复核make cli-install make cli-statuscli-install依赖ui-buildcd potpie/daemon/http/ui/frontend npm install npm run build随后先停止旧 daemonpotpie daemon stop避免新 CLI 连上跑旧 Python/后端的 daemon再uv tool install --python 3.12,3.14 --force --editable .安装可编辑包cli-status用uv tool list、command -v potpie、shebang Python 版本、potpie --help健康检查与dist/index.html存在性逐项报告。已发布包用户应改用uv tool install potpie或pip install potpie根包要求 Python3.12,3.15见 pyproject.toml。安装后的首跑旅程来自 cli-flow.md 的 canonical journeyREADME 亦指向该文档# 已发布包 uv tool install potpie # 或: pip install potpie potpie setup --repo . --agent claude potpie status # 仓库本地开发先 make cli-install然后同上 # 读契约再读图 potpie graph catalog --profile read potpie graph read --subgraph debugging --view prior_occurrences --scope service:refunds-api # 解析身份再从规范写入门写入 potpie graph search-entities refund timeout --type BugPattern potpie graph propose --file mutation.json potpie graph commit plan_id --verify查看实时命令列表可直接运行potpie --help或python -m potpie.cli.main --help。五、Agent Harness 安装把技能包物化到运行时README 最后一节讲解potpie skills install [id] --agent claude如何通过显式的根 skill 服务把打包的技能 bundle 物化到指定 Agent harness。默认 scope 是global技能一次性安装到所选 harness 的用户级技能目录Harness全局路径Cursor~/.cursor/skills/skill/SKILL.mdClaude Code~/.claude/skills/skill/SKILL.mdOpenCode~/.config/opencode/skills/skill/SKILL.mdCodex$HOME/.agents/skills/skill/SKILL.md各 harness 的目标类与全局技能根目录在 potpie/skills/targets.py 中实现ClaudeAgentTarget、Codex、Cursor、OpenCode四个FileBackedAgentTarget与 docs/context-graph/skills.md 的表格一致。5.1 随包模板的目录布局README 指出随包模板位于 potpie/cli/templates/项目 bundleagent_bundle/含AGENTS.md与.agents/skills/*/SKILL.md与claude_bundle/.claude/skills/*/SKILL.md紧凑的全局指令块global_agent_bundle/AGENTS.md与CLAUDE.mdClaude Code 插件claude_plugin/commands/、hooks/、skills/共 7 个技能另含README.md。打包层还通过 pyproject.toml 的[tool.hatch.build.force-include]确保claude_plugin/.claude-plugin/marketplace.json、plugin.json与hooks/hooks.json进入 wheel。5.2 指令文件的合并规则不覆盖用户内容对于有文档化文件级全局指令的 harnessinstall/update 同时会刷新~/.claude/CLAUDE.md与~/.codex/AGENTS.md中的紧凑 Potpie 托管块既有用户内容被保留Potpie 只追加或更新!-- potpie-start --/!-- potpie-end --标记之间的托管区段。仓库本地的AGENTS.md与CLAUDE.md用同样方式合并因此 setup 不会替换已有的 agent 指令。5.3 移除与仓库本地作用域potpie skills remove id --agent claude # 移除单个全局技能 potpie skills remove --all --agent claude # 移除该 harness 所有已安装的 Potpie 全局技能 potpie skills remove id --scope project --path . # 仓库本地清理--scope project --path .用于仓库本地安装。从 potpie/cli/commands/skills.py 的_effective_scope()可以看到一个自动行为当--path与global同时给出时scope 自动翻转为project。这些命令全部走contract()边界skills install还会上报安装开始/完成/失败三类埋点事件含 sanitized 失败分类与耗时。5.4 技能教什么、Agent 如何被提醒README 说明 bundle 教的是 feature / debugging / review / operations / docs / onboarding 工作流基于 CLI 的 graph 面。Agent 只会看到potpie status中的一个建议性advisoryskills块缺失/过期的技能清单加上精确的安装命令——即漂移提醒的唯一通道。技能本体是纯指令文本SKILL.mdmarkdown无可执行代码其目录与打包细节见 docs/context-graph/skills.md。六、小结potpie/cli/README.md用一页篇幅定下了 Potpie CLI 的三个结构性事实均可在当前仓库源码中逐条复核其一单一入口、分组装配——potpie/cli/main.py 的build_app()把 query/bootstrap/auth/ui 四个顶层 registrar 与 pot/source/daemon/ledger/graph/timeline/backend/skills/cloud/telemetry 十个子应用组装成一个 Typer 应用其二横切契约集中——退出码 0/1/2/3/4、结构化错误形状与 pot 解析全部收敛在 potpie/cli/commands/_common.py其三人与 Agent 共用一套命令面——resolve/search/record/status四工具契约加skills install的多 harness 物化机制让 CLI 同时成为人的操作台和 Agent 的操作 API。完整的命令目录与 flag 参考请继续查阅 docs/context-graph/cli-flow.md端到端架构服务、端口、组合根见 docs/context-graph/architecture.md。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考