企业官网建设流程全解析

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

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie

本篇以 Potpie 仓库中potpie/cli/README.md为骨架，系统讲解 Potpie CLI（console 脚本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()可以看到完整的装配逻辑：

1. 创建一个typer.Typer根应用（no_args_is_help=True，不带参数即打印帮助）；
2. @app.callback暴露三个全局选项：--json（机器可读输出）、--verbose/-v（错误时打印详细 traceback）、--version（打印版本并退出，eager 回调）；
3. 顶层命令由四个 registrar 注册：query_cmds（resolve/search/record）、bootstrap（setup/doctor/whoami/use/config/status）、auth_cmds、ui_cmds；
4. 其余分组以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()）：

• 默认（daemon）：get_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/cli/commands/query.py 的源码可以逐一印证这些契约：

• resolve接受task位置参数与--intent（默认feature）、--include（逗号分隔的 include 家族）、--mode（fast | balanced | verify | deep）、--pot，构造EngineResolveRequest后经EngineClient.resolve()返回 envelope；
• search接受query位置参数与--include、--pot，返回同一AgentEnvelope形状（pot_id、intent、overall_confidence、items[]、coverage[]——其中coverage的graph_view字段是向graph read迁移的指针）；
• record要求--type与--summary，可选--scope（k: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-op（readiness 现在是默认行为）；--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

3.2contract()错误边界与结构化错误形状

contract()上下文管理器（_common.py）把领域异常一一映射为上述退出码：EngineClientError按错误category分派（authentication/authorization→ 4；selection/domain→ 1；其余 → 2）；CapabilityNotImplemented→ codenot_implemented、退出码 2；ContextEngineDisabled→ 提示用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_pot）>active pot（否则no_active_pot）。一个反直觉但有保护意味的细节：source add传infer_from_repo=False——因为注册仓库这条命令本身就是建立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-status

• cli-install依赖ui-build（cd potpie/daemon/http/ui/frontend && npm install && npm run build），随后先停止旧 daemon（potpie 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（根包要求 Python>=3.12,<3.15，见 pyproject.toml）。

安装后的首跑旅程（来自 cli-flow.md 的 canonical journey，README 亦指向该文档）：

# 已发布包 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 的目标类与全局技能根目录在 potpie/skills/targets.py 中实现（ClaudeAgentTarget、Codex、Cursor、OpenCode四个FileBackedAgentTarget`），与 docs/context-graph/skills.md 的表格一致。

5.1 随包模板的目录布局

README 指出随包模板位于 potpie/cli/templates/：

• 项目 bundle：agent_bundle/（含AGENTS.md与.agents/skills/*/SKILL.md）与claude_bundle/（.claude/skills/*/SKILL.md）；
• 紧凑的全局指令块：global_agent_bundle/（AGENTS.md与CLAUDE.md）；
• Claude 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 指令文件的合并规则（不覆盖用户内容）

对于有文档化文件级全局指令的 harness，install/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中的一个建议性（advisory）skills块：缺失/过期的技能清单加上精确的安装命令——即漂移提醒的唯一通道。技能本体是纯指令文本（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