Potpie CLI 完全参考:上下文图命令体系的用法与源码级剖析【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 是一个 CLI-first 的上下文图工具,其命令行既是人类的操作界面,也是 Agent 的调用契约。本文以仓库内的 CLI 参考文档 为骨架,完整覆盖potpie setup、login、status、source add repo、resolve/search/record、graph、ui、skills等全部核心命令的参数与用法,并结合 CLI 入口 与各命令实现源码,深入讲解每个命令背后的服务调用链、输出契约与面向 Agent 的 JSON/退出码设计。读完后你可以直接复制命令完成本地初始化,并理解每条命令在 Potpie 架构中的角色。从安装到 setup:三步建立本地上下文环境Potpie 通过 PyPI 分发,推荐用uv安装(避免全局修改 Python 环境):uv tool install potpie # 或 python3 -m pip install --user potpie安装后运行potpie setup启动设置向导。它一次性完成本地配置、存储、守护进程(daemon)、默认 pot(工作区)和 agent 技能的 provisioning,并允许选择集成与编码 harness。README 中明确了一个关键设计:你不需要单独执行手动 ingest 命令——CLI 只负责注册 source,配置好的 agent 会在任务需要时自行摄取或更新项目上下文。这一注册即就绪的理念贯穿了本文介绍的所有命令。CLI 命令总表以下是参考文档给出的主命令清单,覆盖从初始化到日常查写的完整生命周期:命令用途potpie setup运行首次本地设置:配置、daemon、默认 pot、agent 技能。potpie login登录 Potpie 账号,启用账户托管类功能。potpie github login/potpie linear login连接希望 agent 使用的来源集成。potpie status显示当前 pot 的上下文就绪状态,含 daemon、graph、技能检查。potpie auth status显示已配置集成的认证状态。potpie auth status --verify用轻量级 API 检查校验集成凭据。potpie doctor运行本地诊断:daemon、后端能力、技能漂移。potpie source add repo .将当前仓库注册为已解析 pot 的 source。potpie pot list/potpie pot use {id-or-name}列出 pots 并选择活动工作区。potpie resolve {task}拉取执行任务前 agent 应读取的上下文。potpie search {query}查询特定文件、工作流、bug、决策或约定。potpie record --type {type} --summary {summary}写入一条持久化项目学习。potpie graph ...使用更低层的图读取、质量检查、提案与提交。potpie ui打开由 daemon 提供服务的本地图浏览器。potpie skills install --agent {agent}为某个 agent harness 安装或刷新 Potpie 指引。最简化的上手序列(继承自参考文档示例):potpie setup --repo . --agent claude potpie github login potpie auth status potpie status potpie source add repo . potpie resolve what should I know before working in this repository? potpie search authentication flow potpie record --type decision --summary Prefer the Potpie CLI for graph work从源码结构看,这个清单对应 根 Typer 应用 的组装方式:顶层命令(query、bootstrap、auth、ui)加上按功能域划分的子应用——pot、source、daemon、ledger、graph、timeline、backend、skills、cloud、telemetry。每个子应用对应 CLI 流程文档 中的一个命令组,便于按域演进。首次初始化:potpie setup 的全部参数setup是唯一幂等的首跑命令,定义于 bootstrap 命令实现。它接受以下选项:选项默认值说明--repo.要绑定的仓库路径。--potdefault默认 pot 的名称。--agentclaude要配置的 agent harness(如claude)。--backend活动后端图后端 profile;默认沿用当前活动后端。--scan关setup 时执行扫描。--dry-run关只打印步骤不执行。--yes/-y关对所有提示假设回答 yes(跳过交互向导)。--daemon/--in-process$CONTEXT_ENGINE_HOST_MODE或 daemon是否 provision 真实分离式 daemon。--embeddings已配置值或 sentence-transformers本地语义搜索的嵌入模式:sentence-transformers、auto、local、none。--embedding-model已配置值setup 期间准备的 SentenceTransformer 模型。几个值得注意的实现细节:--dry-run会先preview再退出:它列出全部计划步骤,并区分hard(失败则 setup 整体失败)与soft(警告)两类,人类可读输出会附注 no changes made; run without --dry-run to execute。后端不匹配会显式报错:如果 daemon 已用neo4j之类的后端在运行,而你用--backend falkordb执行 setup,源码会抛出明确的ValueError,并提示先potpie daemon stop(见 后端校验逻辑)。嵌入模式有别名归一化:legacy/sbert/minilm等别名会被归一到sentence-transformers,off/disabled归一到none(见 嵌入选择逻辑),最终通过CONTEXT_ENGINE_EMBEDDER/CONTEXT_ENGINE_EMBEDDING_MODEL环境变量传递给运行时。失败语义:任一 hard 步骤失败时,setup 以退出码EXIT_DEGRADED结束,而不是静默返回 0,便于脚本判断。账号与集成认证:login、provider login、auth statusPotpie 有两条独立的认证线,参考文档中的potpie login和potpie github login分别对应其中一条:Potpie 账号(由 auth 注册器 提供):potpie login # 浏览器 Firebase 会话登录 potpie login --api-key sk-... # 或直接存 API key potpie login --api-key sk-... --url http://127.0.0.1:8001 # 指定 API base URL potpie logout--api-key走 key 认证而非浏览器登录;whoami则显示当前主机身份(本地 OSS 部署会报告none身份)。来源集成(由 集成认证命令 提供):potpie github login、potpie linear login、potpie jira ...、potpie confluence ...等,走 OAuth 授权码 PKCE、本地回调服务器、令牌交换与刷新流程。源码中声明的完整 provider 集合为github、linear、jira、confluence、gitlab、gitbucket(见 _ALL_PROVIDERS)。这些凭据流属于入站适配器的凭据获取,不跨越 context-engine 边界,凭据存储在本地 credentials store 中。认证状态检查:potpie auth status # 本地集成认证状态 potpie auth status --verify # 用轻量 API 检查验证凭据有效性auth组下以 provider 命名的子命令是遗留别名,推荐直接用potpie provider形式。就绪检查:potpie status 与 potpie doctorpotpie status是上下文就绪聚合视图(实现见 status 命令)。它的 JSON 输出包含这些字段:profile/daemon_up:运行 profile 与 daemon 是否在线;active_pot:活动 pot 名称;backend_ready与data_plane:后端是否就绪,以及backend_profile、reader_backed_includes、节点计数counts、新鲜度freshness、质量quality;pot_summary:pot 数量与已注册 source 名称;skills:所选 harness 的技能缺失/过期提示,含可直接执行的install_command;recommended_next_action:按状态推导的下一步建议(无 pot → 跑potpie setup;后端未就绪 → 跑potpie backend doctor;一切就绪 → 提示potpie resolve task)。注意:--verify标志已从status移除,源码会明确报错并指向potpie auth status --verify(见 迁移提示)。potpie doctor做更底层诊断,输出包括:daemon 状态与模式、CLI 安装状态(cli_install)、后端 profile 与已实现能力列表(backend_capabilities)、mutation 就绪详情(backend_readiness)、活动 pot 与当前仓库的有效 pot 映射、ledger 可用性,以及后端未就绪时的建议动作(见 doctor 命令)。此外还有potpie config list|get|set,管理持久化在home/config.json的非密钥配置,已知键集合由KNOWN_CONFIG_KEYS定义。工作区与来源:pot 和 source 命令组Pot 是 Potpie 的工作区/租户边界。核心子命令(实现见 pots 命令):potpie pot list # 列出本地 pots(默认);--all 附加托管 pots 标记 potpie pot use my-pot # 选择活动 pot potpie pot info # 活动 pot 当前仓库的 pot 路由 potpie pot linked # 展示与仓库 source 关联的 pots 及本地默认 potpie pot create my-pot --repo . --use # 建 pot 并顺带注册仓库 source potpie pot default show|set|clear # 仓库级默认 pot 路由pot list目前只列本地 origin 的 pots;--managed单独使用时会返回结构化的未实现契约(managed 路由仍在开发中,源码中明确标注为 HU3 里程碑,见 pot_list)。source add是最容易误解的命令——它的职责是纯注册:potpie source add repo ..或current会先解析为 git remote 或绝对路径再存储(见 仓库位置解析);对 repo 类 source,--default/--no-default控制是否把目标 pot 设为该仓库的本地默认(默认--default);命令组帮助文本和输出都反复强调 registration only; no ingestion or scan started——注册本身不触发任何扫描或摄取;重复注册同一仓库是幂等的:会先匹配已有 source,命中则复用而不新建(见 register_repo_source)。配套命令:source list(含 pot 的 claims/entities 计数与解析途径)、source status [id](全量或单个 source 状态,并对空 pot 给出recommended_next_action)、source remove id。Agent 四件套:resolve、search、recordquery 命令 的模块注释点明了架构定位:resolve/search/record(加上status)构成four-tool agent contract——新的用例通过扩展--intent/--include/--type取值实现,而不是新增命令。potpie resolve task— 为任务拉取有界上下文包裹:选项默认值说明--intentfeature意图类别,驱动返回哪些上下文族。--include全部逗号分隔的 include 家族,收窄返回范围。--modefast检索深度:fast|balanced|verify|deep。--pot已解析 pot显式指定 pot。输出信封(pot、intent、置信度、条目、覆盖度)字段固定:{ pot_id: ..., intent: feature, overall_confidence: ..., items: [{include: ..., score: 0.9, payload: {}}], coverage: [{include: ..., status: ..., graph_view: ...}], unsupported_includes: [{name: ..., reason: ...}] }其中coverage里每个 include 家族都指向对应的graph_view,这正是从resolve平滑过渡到graph read低层读取的路标(见 envelope 构造)。potpie search query— 针对已知短语或实体的窄化查询,支持--include与--pot。potpie record --type type --summary summary— 写入一条持久化项目学习:--type:记录类型,如fix、decision、preference等;--scope:key:value形式的限定,例如service:inventory-svc,多个 scope 用逗号分隔,由 _parse_scope 解析为字典;输出是收据(receipt):status、record_id、mutations_applied(实际应用的图变更数),人类可读形式为applied: record_id (N mutations)。三个命令的成功都会触发激活/用量埋点,但这不影响本地行为与输出契约。图操作与可视化:graph 与 uipotpie graph ...提供低层图能力,通过能力端口访问(实现入口 graph 命令),并挂有四个子应用:graph inbox:待处理的图工作收件箱(claim/mark applied/rejected 等);graph quality:只读质量报告;graph bulk:分块的语义图变更应用;backend(potpie backend ...):GraphBackend profile 选择与健康检查,potpie backend doctor是后端未就绪时的标准动作。尚未在某个 profile 上构建的投影(semantic/inspection/analytics/snapshot)不会崩溃,而是返回结构化的 not-implemented 契约。potpie ui打开本地图浏览器(实现见 ui 命令):potpie ui # 确保 daemon 在线后打开 /ui potpie ui --no-open # 只打印 URL potpie ui --pot my-pot # 直接定位到指定 pot页面与 JSON API 由 daemon 在回环地址的/ui提供服务;若 daemon 版本过旧没有 UI,命令会探测/ui/api/pots并提示potpie daemon restart。技能管理:potpie skills技能是 CLI 管理的配方:agent 在context_status中只能看到建议性 nudge,安装与刷新由 CLI 负责(实现见 skills 命令):potpie skills list # 列出某 agent 的技能及版本 potpie skills install [skill-id] --agent claude potpie skills install --agent claude # 安装/刷新该 harness 的 Potpie 指引 potpie skills update --all --agent claude--agent(默认claude)选择 harness,--scope(默认global)与--path控制安装位置;操作结果返回changed列表(实际变更的文件)与agent/scope元数据。仓库内的模板素材位于 claude plugin 模板 与 agent bundle 模板 等目录,技能目录逻辑由 skills 包 支撑。面向 Agent 的 CLI 契约:全局选项、JSON 与退出码Potpie CLI 明确设计为同时供人类和 agent 使用,这体现在 根应用回调 与 run_cli 入口 中:--json:所有命令支持,输出机器可读 JSON;错误也变为带code/message/next_action的结构化错误(解析错误使用usage_error码);--verbose/-v:错误时打印详细 traceback;--version:打印potpie-context-engine包版本与 Python 环境;稳定退出码:_common模块定义了EXIT_VALIDATION、EXIT_DEGRADED、EXIT_AUTH、EXIT_UNAVAILABLE等语义化退出码,agent 可据此区分参数错误、降级、认证失败与能力不可用;解析错误契约:Click/Typer 的解析异常在--json模式下被转换为usage_error结构而不是裸 traceback,保证脚本调用不会遇到无法解析的文本;宿主模式开关:CONTEXT_ENGINE_HOST_MODE在本地/规范 daemon 的EngineClient之间切换,不改变任何命令契约(见 main 模块注释)。延伸阅读CLI 参考文档:本文的命令总表与示例出处;CLI 流程文档:命令分组与流程定义,命令组结构与其一一对应;CLI 模块规范 与 CLI 契约:规范层面对 CLI 行为的约定;CLI 包边界测试:验证命令面按包边界组织的特征测试。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Potpie CLI 完全参考:上下文图命令体系的用法与源码级剖析【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 是一个 CLI-first 的上下文图工具,其命令行既是人类的操作界面,也是 Agent 的调用契约。本文以仓库内的 CLI 参考文档 为骨架,完整覆盖potpie setup、login、status、source add repo、resolve/search/record、graph、ui、skills等全部核心命令的参数与用法,并结合 CLI 入口 与各命令实现源码,深入讲解每个命令背后的服务调用链、输出契约与面向 Agent 的 JSON/退出码设计。读完后你可以直接复制命令完成本地初始化,并理解每条命令在 Potpie 架构中的角色。从安装到 setup:三步建立本地上下文环境Potpie 通过 PyPI 分发,推荐用uv安装(避免全局修改 Python 环境):uv tool install potpie # 或 python3 -m pip install --user potpie安装后运行potpie setup启动设置向导。它一次性完成本地配置、存储、守护进程(daemon)、默认 pot(工作区)和 agent 技能的 provisioning,并允许选择集成与编码 harness。README 中明确了一个关键设计:你不需要单独执行手动 ingest 命令——CLI 只负责注册 source,配置好的 agent 会在任务需要时自行摄取或更新项目上下文。这一注册即就绪的理念贯穿了本文介绍的所有命令。CLI 命令总表以下是参考文档给出的主命令清单,覆盖从初始化到日常查写的完整生命周期:命令用途potpie setup运行首次本地设置:配置、daemon、默认 pot、agent 技能。potpie login登录 Potpie 账号,启用账户托管类功能。potpie github login/potpie linear login连接希望 agent 使用的来源集成。potpie status显示当前 pot 的上下文就绪状态,含 daemon、graph、技能检查。potpie auth status显示已配置集成的认证状态。potpie auth status --verify用轻量级 API 检查校验集成凭据。potpie doctor运行本地诊断:daemon、后端能力、技能漂移。potpie source add repo .将当前仓库注册为已解析 pot 的 source。potpie pot list/potpie pot use {id-or-name}列出 pots 并选择活动工作区。potpie resolve {task}拉取执行任务前 agent 应读取的上下文。potpie search {query}查询特定文件、工作流、bug、决策或约定。potpie record --type {type} --summary {summary}写入一条持久化项目学习。potpie graph ...使用更低层的图读取、质量检查、提案与提交。potpie ui打开由 daemon 提供服务的本地图浏览器。potpie skills install --agent {agent}为某个 agent harness 安装或刷新 Potpie 指引。最简化的上手序列(继承自参考文档示例):potpie setup --repo . --agent claude potpie github login potpie auth status potpie status potpie source add repo . potpie resolve what should I know before working in this repository? potpie search authentication flow potpie record --type decision --summary Prefer the Potpie CLI for graph work从源码结构看,这个清单对应 根 Typer 应用 的组装方式:顶层命令(query、bootstrap、auth、ui)加上按功能域划分的子应用——pot、source、daemon、ledger、graph、timeline、backend、skills、cloud、telemetry。每个子应用对应 CLI 流程文档 中的一个命令组,便于按域演进。首次初始化:potpie setup 的全部参数setup是唯一幂等的首跑命令,定义于 bootstrap 命令实现。它接受以下选项:选项默认值说明--repo.要绑定的仓库路径。--potdefault默认 pot 的名称。--agentclaude要配置的 agent harness(如claude)。--backend活动后端图后端 profile;默认沿用当前活动后端。--scan关setup 时执行扫描。--dry-run关只打印步骤不执行。--yes/-y关对所有提示假设回答 yes(跳过交互向导)。--daemon/--in-process$CONTEXT_ENGINE_HOST_MODE或 daemon是否 provision 真实分离式 daemon。--embeddings已配置值或 sentence-transformers本地语义搜索的嵌入模式:sentence-transformers、auto、local、none。--embedding-model已配置值setup 期间准备的 SentenceTransformer 模型。几个值得注意的实现细节:--dry-run会先preview再退出:它列出全部计划步骤,并区分hard(失败则 setup 整体失败)与soft(警告)两类,人类可读输出会附注 no changes made; run without --dry-run to execute。后端不匹配会显式报错:如果 daemon 已用neo4j之类的后端在运行,而你用--backend falkordb执行 setup,源码会抛出明确的ValueError,并提示先potpie daemon stop(见 后端校验逻辑)。嵌入模式有别名归一化:legacy/sbert/minilm等别名会被归一到sentence-transformers,off/disabled归一到none(见 嵌入选择逻辑),最终通过CONTEXT_ENGINE_EMBEDDER/CONTEXT_ENGINE_EMBEDDING_MODEL环境变量传递给运行时。失败语义:任一 hard 步骤失败时,setup 以退出码EXIT_DEGRADED结束,而不是静默返回 0,便于脚本判断。账号与集成认证:login、provider login、auth statusPotpie 有两条独立的认证线,参考文档中的potpie login和potpie github login分别对应其中一条:Potpie 账号(由 auth 注册器 提供):potpie login # 浏览器 Firebase 会话登录 potpie login --api-key sk-... # 或直接存 API key potpie login --api-key sk-... --url http://127.0.0.1:8001 # 指定 API base URL potpie logout--api-key走 key 认证而非浏览器登录;whoami则显示当前主机身份(本地 OSS 部署会报告none身份)。来源集成(由 集成认证命令 提供):potpie github login、potpie linear login、potpie jira ...、potpie confluence ...等,走 OAuth 授权码 PKCE、本地回调服务器、令牌交换与刷新流程。源码中声明的完整 provider 集合为github、linear、jira、confluence、gitlab、gitbucket(见 _ALL_PROVIDERS)。这些凭据流属于入站适配器的凭据获取,不跨越 context-engine 边界,凭据存储在本地 credentials store 中。认证状态检查:potpie auth status # 本地集成认证状态 potpie auth status --verify # 用轻量 API 检查验证凭据有效性auth组下以 provider 命名的子命令是遗留别名,推荐直接用potpie provider形式。就绪检查:potpie status 与 potpie doctorpotpie status是上下文就绪聚合视图(实现见 status 命令)。它的 JSON 输出包含这些字段:profile/daemon_up:运行 profile 与 daemon 是否在线;active_pot:活动 pot 名称;backend_ready与data_plane:后端是否就绪,以及backend_profile、reader_backed_includes、节点计数counts、新鲜度freshness、质量quality;pot_summary:pot 数量与已注册 source 名称;skills:所选 harness 的技能缺失/过期提示,含可直接执行的install_command;recommended_next_action:按状态推导的下一步建议(无 pot → 跑potpie setup;后端未就绪 → 跑potpie backend doctor;一切就绪 → 提示potpie resolve task)。注意:--verify标志已从status移除,源码会明确报错并指向potpie auth status --verify(见 迁移提示)。potpie doctor做更底层诊断,输出包括:daemon 状态与模式、CLI 安装状态(cli_install)、后端 profile 与已实现能力列表(backend_capabilities)、mutation 就绪详情(backend_readiness)、活动 pot 与当前仓库的有效 pot 映射、ledger 可用性,以及后端未就绪时的建议动作(见 doctor 命令)。此外还有potpie config list|get|set,管理持久化在home/config.json的非密钥配置,已知键集合由KNOWN_CONFIG_KEYS定义。工作区与来源:pot 和 source 命令组Pot 是 Potpie 的工作区/租户边界。核心子命令(实现见 pots 命令):potpie pot list # 列出本地 pots(默认);--all 附加托管 pots 标记 potpie pot use my-pot # 选择活动 pot potpie pot info # 活动 pot 当前仓库的 pot 路由 potpie pot linked # 展示与仓库 source 关联的 pots 及本地默认 potpie pot create my-pot --repo . --use # 建 pot 并顺带注册仓库 source potpie pot default show|set|clear # 仓库级默认 pot 路由pot list目前只列本地 origin 的 pots;--managed单独使用时会返回结构化的未实现契约(managed 路由仍在开发中,源码中明确标注为 HU3 里程碑,见 pot_list)。source add是最容易误解的命令——它的职责是纯注册:potpie source add repo ..或current会先解析为 git remote 或绝对路径再存储(见 仓库位置解析);对 repo 类 source,--default/--no-default控制是否把目标 pot 设为该仓库的本地默认(默认--default);命令组帮助文本和输出都反复强调 registration only; no ingestion or scan started——注册本身不触发任何扫描或摄取;重复注册同一仓库是幂等的:会先匹配已有 source,命中则复用而不新建(见 register_repo_source)。配套命令:source list(含 pot 的 claims/entities 计数与解析途径)、source status [id](全量或单个 source 状态,并对空 pot 给出recommended_next_action)、source remove id。Agent 四件套:resolve、search、recordquery 命令 的模块注释点明了架构定位:resolve/search/record(加上status)构成four-tool agent contract——新的用例通过扩展--intent/--include/--type取值实现,而不是新增命令。potpie resolve task— 为任务拉取有界上下文包裹:选项默认值说明--intentfeature意图类别,驱动返回哪些上下文族。--include全部逗号分隔的 include 家族,收窄返回范围。--modefast检索深度:fast|balanced|verify|deep。--pot已解析 pot显式指定 pot。输出信封(pot、intent、置信度、条目、覆盖度)字段固定:{ pot_id: ..., intent: feature, overall_confidence: ..., items: [{include: ..., score: 0.9, payload: {}}], coverage: [{include: ..., status: ..., graph_view: ...}], unsupported_includes: [{name: ..., reason: ...}] }其中coverage里每个 include 家族都指向对应的graph_view,这正是从resolve平滑过渡到graph read低层读取的路标(见 envelope 构造)。potpie search query— 针对已知短语或实体的窄化查询,支持--include与--pot。potpie record --type type --summary summary— 写入一条持久化项目学习:--type:记录类型,如fix、decision、preference等;--scope:key:value形式的限定,例如service:inventory-svc,多个 scope 用逗号分隔,由 _parse_scope 解析为字典;输出是收据(receipt):status、record_id、mutations_applied(实际应用的图变更数),人类可读形式为applied: record_id (N mutations)。三个命令的成功都会触发激活/用量埋点,但这不影响本地行为与输出契约。图操作与可视化:graph 与 uipotpie graph ...提供低层图能力,通过能力端口访问(实现入口 graph 命令),并挂有四个子应用:graph inbox:待处理的图工作收件箱(claim/mark applied/rejected 等);graph quality:只读质量报告;graph bulk:分块的语义图变更应用;backend(potpie backend ...):GraphBackend profile 选择与健康检查,potpie backend doctor是后端未就绪时的标准动作。尚未在某个 profile 上构建的投影(semantic/inspection/analytics/snapshot)不会崩溃,而是返回结构化的 not-implemented 契约。potpie ui打开本地图浏览器(实现见 ui 命令):potpie ui # 确保 daemon 在线后打开 /ui potpie ui --no-open # 只打印 URL potpie ui --pot my-pot # 直接定位到指定 pot页面与 JSON API 由 daemon 在回环地址的/ui提供服务;若 daemon 版本过旧没有 UI,命令会探测/ui/api/pots并提示potpie daemon restart。技能管理:potpie skills技能是 CLI 管理的配方:agent 在context_status中只能看到建议性 nudge,安装与刷新由 CLI 负责(实现见 skills 命令):potpie skills list # 列出某 agent 的技能及版本 potpie skills install [skill-id] --agent claude potpie skills install --agent claude # 安装/刷新该 harness 的 Potpie 指引 potpie skills update --all --agent claude--agent(默认claude)选择 harness,--scope(默认global)与--path控制安装位置;操作结果返回changed列表(实际变更的文件)与agent/scope元数据。仓库内的模板素材位于 claude plugin 模板 与 agent bundle 模板 等目录,技能目录逻辑由 skills 包 支撑。面向 Agent 的 CLI 契约:全局选项、JSON 与退出码Potpie CLI 明确设计为同时供人类和 agent 使用,这体现在 根应用回调 与 run_cli 入口 中:--json:所有命令支持,输出机器可读 JSON;错误也变为带code/message/next_action的结构化错误(解析错误使用usage_error码);--verbose/-v:错误时打印详细 traceback;--version:打印potpie-context-engine包版本与 Python 环境;稳定退出码:_common模块定义了EXIT_VALIDATION、EXIT_DEGRADED、EXIT_AUTH、EXIT_UNAVAILABLE等语义化退出码,agent 可据此区分参数错误、降级、认证失败与能力不可用;解析错误契约:Click/Typer 的解析异常在--json模式下被转换为usage_error结构而不是裸 traceback,保证脚本调用不会遇到无法解析的文本;宿主模式开关:CONTEXT_ENGINE_HOST_MODE在本地/规范 daemon 的EngineClient之间切换,不改变任何命令契约(见 main 模块注释)。延伸阅读CLI 参考文档:本文的命令总表与示例出处;CLI 流程文档:命令分组与流程定义,命令组结构与其一一对应;CLI 模块规范 与 CLI 契约:规范层面对 CLI 行为的约定;CLI 包边界测试:验证命令面按包边界组织的特征测试。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
