Potpie 的 /potpie-feature 命令功能开发前如何从 Context Graph 读取项目偏好与架构上下文【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文围绕 Potpie Claude Code 插件中的/potpie-feature斜杠命令模板potpie-feature.md展开。该命令是 Potpie 把项目记忆图context graph接入 AI 编码会话的入口之一在动手写功能代码之前先让 Agent 加载仓库偏好preferences再按需加载基础设施架构上下文infra topology。读完本文你会掌握命令背后的技能加载策略、完整的potpie graph读命令与参数取值、检索 query 扩写技巧以及如何校验图结果的覆盖面、新鲜度与来源引用。一、命令定位功能开发前的上下文闸门/potpie-feature是 Potpie 插件随附的 Claude Code 斜杠命令模板随potpie install --agent claude-plugin一起落入仓库见 插件 README。插件配套的 CLAUDE.md 模板 中明确约定了使用节奏Use/potpie-featurebefore feature work and/potpie-recordto capture即功能开发前执行/potpie-feature读取上下文有价值的产出后用配套的 /potpie-record 命令把决策、修复、偏好等写回图里形成读-写闭环。命令模板本身只有十余行但浓缩了三条规则先读偏好再动手加载potpie-project-preferences技能条件性加载架构上下文仅当改动触及 services、deployment、adapters 或 runtime behavior 时才加载potpie-infra-architecture技能CLI 可用时直接读图给出五条potpie graph命令作为标准读取路径结果要经过质量审视在依赖检索结果之前检查覆盖面coverage、新鲜度freshness、质量quality、回退fallbacks、未决冲突open conflicts与来源引用source refs。这种先取上下文、再约束实现的模式与 Potpie 的核心卖点——Context Graph for AI Native SDLC——一脉相承图里存的不是代码快照而是决策、偏好、故障模式、服务拓扑等语义事实。二、技能加载策略偏好必读架构按需模板首段给出了技能选择逻辑potpie-project-preferences对应 potpie-project-preferences/SKILL.md其 front-matter 声明的触发时机是编写、修改、评审、重构或测试代码之前覆盖错误处理、文件结构、框架、日志、依赖选择、测试、安全、API 风格与命名约定。功能开发几乎必然触及代码因此它是必读项。potpie-infra-architecture对应 potpie-infra-architecture/SKILL.md触发条件收窄为任务触及环境、适配器、部署行为、运行时配置、服务依赖、生产事故或架构变更。功能开发若只改业务逻辑读取服务邻域service neighborhood是浪费 token 的噪音所以模板将其设为条件加载。两个技能文件还各自给出了比命令模板更细的操作路径值得对照参考偏好技能建议用最窄的作用域发起查询repo、path、service、package 或 file并优先采用active、高置信、作用域更近的偏好file directory service repo global冲突时核对 source refs 或询问用户架构技能强调先解析实体身份再假设键名potpie graph search-entities并提醒staging 上的依赖不等于生产依赖——环境限定词必须保留。三、五条标准读命令逐条拆解命令模板给出的核心代码块是/potpie-feature的Fast Pathpotpie --json graph catalog --task feature work in repo:owner/repo potpie --json graph describe decisions --view preferences_for_scope --examples potpie graph read --subgraph decisions --view preferences_for_scope --scope repo:owner/repo potpie graph read --subgraph decisions --view active_decisions --scope repo:owner/repo potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:name --depth 2结合 CLI 实现 potpie/cli/commands/graph.py逐条说明各命令的角色与关键参数。3.1graph catalog发现图契约catalog用于发现图契约版本、可用视图views、mutation 操作类型与本体ontology见 graph_catalog。命令模板把它放在第一条目的是让 Agent 在读取之前先对齐契约。从源码参数定义看几个值得注意的事实--task选项在 V1.5 阶段被接受但被忽略源码注释(accepted, ignored in V1.5)它保留是为了向前兼容模板里仍传入feature work in repo:owner/repo未来版本可直接按任务语义推荐视图--profile取值为full | read默认full。功能开发前只需要读路径时可传--profile read压缩输出输出经normalize_catalog_result归一化后再渲染graph.py因此--json模式下的字段结构是稳定的。3.2graph describe选择一个受支撑的视图describe命令graph_describe接收--subgraph位置参数、--view与--examples返回该子图/视图的结构说明与示例。模板中的用法potpie --json graph describe decisions --view preferences_for_scope --examples即在真正read之前先取decisions子图下preferences_for_scope视图的 schema 与示例确认字段语义和 scope 键格式。describe的输出还带有recommended_next_action提示源码中明确建议选定 scope 后改用potpie graph read --subgraph s --view v --jsongraph.py#L1421-L1425与模板的工作流顺序完全一致。3.3 两条graph read偏好与活跃决策read是模板的主力命令两条变体分别读decisions子图的两个视图命令视图语义potpie graph read --subgraph decisions --view preferences_for_scope --scope repo:owner/repopreferences_for_scope针对给定作用域检索适用的项目偏好potpie graph read --subgraph decisions --view active_decisions --scope repo:owner/repoactive_decisions读取当前仓库作用域内仍处于生效状态的架构/工程决策graph read的完整参数面graph_read远不止模板用到的这些对功能开发场景最常用的有--query语义检索 query 字符串--query-threshold控制语义相似度下限默认0.70取值 0.0–1.0--scopekey:value[,key:value]形式的多键作用域如模板中的repo:owner/repo、service:name偏好技能中还会叠加path:path-or-dir--limit默认 12 条偏好技能示例中显式传--limit 12并配合--query--depth/--direction邻域类视图的遍历深度与方向out | in | both模板中--depth 2即服务的一跳上游 一跳下游--environment环境限定dev/staging/prod/preview架构技能要求仅在任务与环境无关时才省略--since/--until/--time-window如24h、7d时间窗过滤评估结果新鲜度时可用来对比--sortauto | score | occurred_at、--dedupeauto | none | source_ref | activity、--formatauto | raw | events | table | jsonl、--detailcompact | full。需要说明的适用前提以上参数取自当前仓库的 Typer 命令定义实际执行时pot项目 pot需已激活potpie pot use id或环境变量POTPIE_POT否则命令无法定位目标图。3.4graph read读服务邻域架构上下文的最小集模板第五条命令potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:name --depth 2它对应架构技能中的 Fast Path从任务点名的服务/环境/适配器/依赖出发先search-entities解析身份再以service:name为 scope 读两跳邻域。架构技能建议的完整形态还带--environment dev|staging|prod|preview、--direction both、--limit 20并在做宽架构分析前先跑一次potpie --json graph describe infra_topology --view service_neighborhood --examples确认读法。阅读结果时架构技能列出了应关注的显式拓扑谓词DEFINED_IN、DEPLOYED_TO、DEPENDS_ON、USES、EXPOSES、HOSTED_ON、OWNED_BY。这些谓词是判断改动 blast radius爆炸半径的依据也是模板要求条件加载架构技能的实质原因。四、检索 query 扩写写给人看还是写给未来的搜索者模板最后一段给出两条检索纪律Expand the users request into a good retrieval--query/query(add symptoms and synonyms a future searcher would type). Inspect coverage, freshness, quality, fallbacks, open conflicts, and source refs before relying on the result.扩写 query把用户的原始需求扩展成未来检索者会输入的词——症状symptoms、同义词synonyms、作用域术语一起拼进--query。这与 /potpie-record 写入侧的要求互为镜像Write thedescriptionfor retrieval, not display描述写给检索而非展示。写入时埋好症状词与同义词读取时才能以--query-threshold默认 0.70以上的相似度被召回。结果六项体检在把图结果当作实现约束之前检查——coverage返回项是否覆盖了任务的各维度如既有错误处理偏好也有依赖选择偏好freshness记录是否过时可结合--since/--time-window复查时间分布qualityconfidence/truth class 是否足够支撑当作约束的用法fallbacks图给出的替代方案与回退路径如降级策略、兜底实现open conflicts作用域重叠的偏好之间的未决冲突——偏好技能明确两条偏好冲突时先验证 source refs 或询问用户source refs来源引用是否可回溯如github:owner/repo#issue/123形式--source-ref选项支持精确匹配。五、底层调用链CLI 如何到达图工作区从源码结构看这些命令并不直接触碰存储。potpie/cli/commands/graph.py 的文件头注释明确CLI code never touches a store directly; everything goes through the capability ports。其调用链为Typer 命令graph_catalog/graph_describe/graph_read经resolve_pot_id定位项目 potrun_engine_operation(get_engine_client(pot).read(...))等把ReadRequest/DescribeRequest/CatalogRequest定义于potpie/context-engine/src/potpie_context_engine/requests.py发给引擎客户端结果经normalize_workbench_result/normalize_catalog_result来自potpie_context_engine.core.workbench_service包装为统一信封graph_success_envelope/graph_error_envelope/graph_not_implemented_envelope再按--json或人类可读格式输出。这一结构带来两个实用含义其一--json输出的信封是结构稳定的Agent 可可靠解析其二未构建的投影profile 不支持的视图/操作会以结构化的 not-implemented 契约返回而不是崩溃这与模板inspect ... before relying on the result的审慎语气一致。六、与插件其他机制的协作关系/potpie-feature不是孤立存在的它与插件的三条机制互补Hooks 注入hooks.json 通过SessionStart事件注入repo baselineactive decisions repo-level preferences——与模板第二条命令read --view active_decisions读取的是同一类数据。可以推断即便 Agent 忘记手动执行/potpie-feature会话启动时偏好与活跃决策也会经potpie graph nudge被无模型model-free地注入会话/potpie-record写入侧读到的偏好若缺失或功能开发产生新决策/修复/偏好用 record 命令走 V2 图计划流程search-entities解析身份 →graph propose --file mutation.json→graph commit plan_id --verify→graph history --plan plan_id保证下次阅读能召回技能即流程potpie-project-preferences与potpie-infra-architecture两个 SKILL.md 是命令模板的放大版前者多出 scope 收敛、冲突仲裁与偏好写入流程后者多出实体身份解析、环境限定与authoritative_fact/agent_claim两类 truth class 的写入规范。七、小结/potpie-feature命令模板用极短的篇幅定义了 AI Native 功能开发的上下文纪律偏好必读、架构按需、契约先行、query 为检索而写、结果过六项体检。五条potpie graph命令catalog → describe → 两次 read decisions → 一次 read infra_topology构成了从发现契约到取数的标准路径而 potpie/cli/commands/graph.py 中的完整参数面--query-threshold、--scope多键、--depth/--direction、--environment、时间窗与去重选项则为更精细的功能开发场景留出了扩展空间。配合同目录下的 /potpie-record 与 hooks 注入Potpie 把记忆变成了 SDLC 中可重复读写的图资源而非一次性粘贴进会话的静态上下文。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 4:35:27 · 阅读 1.2k Potpie 的 /potpie-feature 命令：功能开发前如何从 Context Graph 读取项目偏好与架构上下文
Potpie 的 /potpie-feature 命令功能开发前如何从 Context Graph 读取项目偏好与架构上下文【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文围绕 Potpie Claude Code 插件中的/potpie-feature斜杠命令模板potpie-feature.md展开。该命令是 Potpie 把项目记忆图context graph接入 AI 编码会话的入口之一在动手写功能代码之前先让 Agent 加载仓库偏好preferences再按需加载基础设施架构上下文infra topology。读完本文你会掌握命令背后的技能加载策略、完整的potpie graph读命令与参数取值、检索 query 扩写技巧以及如何校验图结果的覆盖面、新鲜度与来源引用。一、命令定位功能开发前的上下文闸门/potpie-feature是 Potpie 插件随附的 Claude Code 斜杠命令模板随potpie install --agent claude-plugin一起落入仓库见 插件 README。插件配套的 CLAUDE.md 模板 中明确约定了使用节奏Use/potpie-featurebefore feature work and/potpie-recordto capture即功能开发前执行/potpie-feature读取上下文有价值的产出后用配套的 /potpie-record 命令把决策、修复、偏好等写回图里形成读-写闭环。命令模板本身只有十余行但浓缩了三条规则先读偏好再动手加载potpie-project-preferences技能条件性加载架构上下文仅当改动触及 services、deployment、adapters 或 runtime behavior 时才加载potpie-infra-architecture技能CLI 可用时直接读图给出五条potpie graph命令作为标准读取路径结果要经过质量审视在依赖检索结果之前检查覆盖面coverage、新鲜度freshness、质量quality、回退fallbacks、未决冲突open conflicts与来源引用source refs。这种先取上下文、再约束实现的模式与 Potpie 的核心卖点——Context Graph for AI Native SDLC——一脉相承图里存的不是代码快照而是决策、偏好、故障模式、服务拓扑等语义事实。二、技能加载策略偏好必读架构按需模板首段给出了技能选择逻辑potpie-project-preferences对应 potpie-project-preferences/SKILL.md其 front-matter 声明的触发时机是编写、修改、评审、重构或测试代码之前覆盖错误处理、文件结构、框架、日志、依赖选择、测试、安全、API 风格与命名约定。功能开发几乎必然触及代码因此它是必读项。potpie-infra-architecture对应 potpie-infra-architecture/SKILL.md触发条件收窄为任务触及环境、适配器、部署行为、运行时配置、服务依赖、生产事故或架构变更。功能开发若只改业务逻辑读取服务邻域service neighborhood是浪费 token 的噪音所以模板将其设为条件加载。两个技能文件还各自给出了比命令模板更细的操作路径值得对照参考偏好技能建议用最窄的作用域发起查询repo、path、service、package 或 file并优先采用active、高置信、作用域更近的偏好file directory service repo global冲突时核对 source refs 或询问用户架构技能强调先解析实体身份再假设键名potpie graph search-entities并提醒staging 上的依赖不等于生产依赖——环境限定词必须保留。三、五条标准读命令逐条拆解命令模板给出的核心代码块是/potpie-feature的Fast Pathpotpie --json graph catalog --task feature work in repo:owner/repo potpie --json graph describe decisions --view preferences_for_scope --examples potpie graph read --subgraph decisions --view preferences_for_scope --scope repo:owner/repo potpie graph read --subgraph decisions --view active_decisions --scope repo:owner/repo potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:name --depth 2结合 CLI 实现 potpie/cli/commands/graph.py逐条说明各命令的角色与关键参数。3.1graph catalog发现图契约catalog用于发现图契约版本、可用视图views、mutation 操作类型与本体ontology见 graph_catalog。命令模板把它放在第一条目的是让 Agent 在读取之前先对齐契约。从源码参数定义看几个值得注意的事实--task选项在 V1.5 阶段被接受但被忽略源码注释(accepted, ignored in V1.5)它保留是为了向前兼容模板里仍传入feature work in repo:owner/repo未来版本可直接按任务语义推荐视图--profile取值为full | read默认full。功能开发前只需要读路径时可传--profile read压缩输出输出经normalize_catalog_result归一化后再渲染graph.py因此--json模式下的字段结构是稳定的。3.2graph describe选择一个受支撑的视图describe命令graph_describe接收--subgraph位置参数、--view与--examples返回该子图/视图的结构说明与示例。模板中的用法potpie --json graph describe decisions --view preferences_for_scope --examples即在真正read之前先取decisions子图下preferences_for_scope视图的 schema 与示例确认字段语义和 scope 键格式。describe的输出还带有recommended_next_action提示源码中明确建议选定 scope 后改用potpie graph read --subgraph s --view v --jsongraph.py#L1421-L1425与模板的工作流顺序完全一致。3.3 两条graph read偏好与活跃决策read是模板的主力命令两条变体分别读decisions子图的两个视图命令视图语义potpie graph read --subgraph decisions --view preferences_for_scope --scope repo:owner/repopreferences_for_scope针对给定作用域检索适用的项目偏好potpie graph read --subgraph decisions --view active_decisions --scope repo:owner/repoactive_decisions读取当前仓库作用域内仍处于生效状态的架构/工程决策graph read的完整参数面graph_read远不止模板用到的这些对功能开发场景最常用的有--query语义检索 query 字符串--query-threshold控制语义相似度下限默认0.70取值 0.0–1.0--scopekey:value[,key:value]形式的多键作用域如模板中的repo:owner/repo、service:name偏好技能中还会叠加path:path-or-dir--limit默认 12 条偏好技能示例中显式传--limit 12并配合--query--depth/--direction邻域类视图的遍历深度与方向out | in | both模板中--depth 2即服务的一跳上游 一跳下游--environment环境限定dev/staging/prod/preview架构技能要求仅在任务与环境无关时才省略--since/--until/--time-window如24h、7d时间窗过滤评估结果新鲜度时可用来对比--sortauto | score | occurred_at、--dedupeauto | none | source_ref | activity、--formatauto | raw | events | table | jsonl、--detailcompact | full。需要说明的适用前提以上参数取自当前仓库的 Typer 命令定义实际执行时pot项目 pot需已激活potpie pot use id或环境变量POTPIE_POT否则命令无法定位目标图。3.4graph read读服务邻域架构上下文的最小集模板第五条命令potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:name --depth 2它对应架构技能中的 Fast Path从任务点名的服务/环境/适配器/依赖出发先search-entities解析身份再以service:name为 scope 读两跳邻域。架构技能建议的完整形态还带--environment dev|staging|prod|preview、--direction both、--limit 20并在做宽架构分析前先跑一次potpie --json graph describe infra_topology --view service_neighborhood --examples确认读法。阅读结果时架构技能列出了应关注的显式拓扑谓词DEFINED_IN、DEPLOYED_TO、DEPENDS_ON、USES、EXPOSES、HOSTED_ON、OWNED_BY。这些谓词是判断改动 blast radius爆炸半径的依据也是模板要求条件加载架构技能的实质原因。四、检索 query 扩写写给人看还是写给未来的搜索者模板最后一段给出两条检索纪律Expand the users request into a good retrieval--query/query(add symptoms and synonyms a future searcher would type). Inspect coverage, freshness, quality, fallbacks, open conflicts, and source refs before relying on the result.扩写 query把用户的原始需求扩展成未来检索者会输入的词——症状symptoms、同义词synonyms、作用域术语一起拼进--query。这与 /potpie-record 写入侧的要求互为镜像Write thedescriptionfor retrieval, not display描述写给检索而非展示。写入时埋好症状词与同义词读取时才能以--query-threshold默认 0.70以上的相似度被召回。结果六项体检在把图结果当作实现约束之前检查——coverage返回项是否覆盖了任务的各维度如既有错误处理偏好也有依赖选择偏好freshness记录是否过时可结合--since/--time-window复查时间分布qualityconfidence/truth class 是否足够支撑当作约束的用法fallbacks图给出的替代方案与回退路径如降级策略、兜底实现open conflicts作用域重叠的偏好之间的未决冲突——偏好技能明确两条偏好冲突时先验证 source refs 或询问用户source refs来源引用是否可回溯如github:owner/repo#issue/123形式--source-ref选项支持精确匹配。五、底层调用链CLI 如何到达图工作区从源码结构看这些命令并不直接触碰存储。potpie/cli/commands/graph.py 的文件头注释明确CLI code never touches a store directly; everything goes through the capability ports。其调用链为Typer 命令graph_catalog/graph_describe/graph_read经resolve_pot_id定位项目 potrun_engine_operation(get_engine_client(pot).read(...))等把ReadRequest/DescribeRequest/CatalogRequest定义于potpie/context-engine/src/potpie_context_engine/requests.py发给引擎客户端结果经normalize_workbench_result/normalize_catalog_result来自potpie_context_engine.core.workbench_service包装为统一信封graph_success_envelope/graph_error_envelope/graph_not_implemented_envelope再按--json或人类可读格式输出。这一结构带来两个实用含义其一--json输出的信封是结构稳定的Agent 可可靠解析其二未构建的投影profile 不支持的视图/操作会以结构化的 not-implemented 契约返回而不是崩溃这与模板inspect ... before relying on the result的审慎语气一致。六、与插件其他机制的协作关系/potpie-feature不是孤立存在的它与插件的三条机制互补Hooks 注入hooks.json 通过SessionStart事件注入repo baselineactive decisions repo-level preferences——与模板第二条命令read --view active_decisions读取的是同一类数据。可以推断即便 Agent 忘记手动执行/potpie-feature会话启动时偏好与活跃决策也会经potpie graph nudge被无模型model-free地注入会话/potpie-record写入侧读到的偏好若缺失或功能开发产生新决策/修复/偏好用 record 命令走 V2 图计划流程search-entities解析身份 →graph propose --file mutation.json→graph commit plan_id --verify→graph history --plan plan_id保证下次阅读能召回技能即流程potpie-project-preferences与potpie-infra-architecture两个 SKILL.md 是命令模板的放大版前者多出 scope 收敛、冲突仲裁与偏好写入流程后者多出实体身份解析、环境限定与authoritative_fact/agent_claim两类 truth class 的写入规范。七、小结/potpie-feature命令模板用极短的篇幅定义了 AI Native 功能开发的上下文纪律偏好必读、架构按需、契约先行、query 为检索而写、结果过六项体检。五条potpie graph命令catalog → describe → 两次 read decisions → 一次 read infra_topology构成了从发现契约到取数的标准路径而 potpie/cli/commands/graph.py 中的完整参数面--query-threshold、--scope多键、--depth/--direction、--environment、时间窗与去重选项则为更精细的功能开发场景留出了扩展空间。配合同目录下的 /potpie-record 与 hooks 注入Potpie 把记忆变成了 SDLC 中可重复读写的图资源而非一次性粘贴进会话的静态上下文。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考