Potpie 的 Claude Code 插件用无模型 Hook 把项目记忆图自动注入 Agent 会话【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 定位为 Context Graph for AI Native SDLC其 Claude Code 插件把 Claude Code 的生命周期事件会话开始、编辑前、Bash 执行前后、任务结束挂接到 Potpie 的项目记忆图上让相关上下文在 Agent 未被询问时自动浮现并在正确的时机提示记录持久化经验。本文基于插件的 README、hook 配置文件与适配器的完整源码讲清这条model-free无模型调用注入链路的事件映射、分类机制、底层 nudge 策略、安装方式与调试手段读完后可在任意项目仓库中部署该插件并理解其每一行行为。设计核心model-free 的 Hook 转发路径插件的 README 开宗明义Hook 路径是model-free的——适配器只把事件形状转发给potpie graph nudge再把返回的上下文/指令注入会话所有什么是事实、对应哪个实体、如何措辞的推理都发生在你的会话里、消耗你自己的订阅额度。这一设计在源码里体现得非常彻底。适配器 hooks/potpie_nudge.py 的模块 docstring 自述它拥有任何触发策略都谈不上、也不做任何模型调用owns no trigger policy and makes no model call其唯一职责是字段转发外加 harness 分类法强制的机械事件名映射一个PostToolUse(Bash)事件必须变成test_failed或test_passed二者之一。所有读什么、是否相关、是否提示写入的决策都住在potpie graph nudge内部而后者只使用本地 embedder。事件与 nudge 的对应关系是插件的核心契约README 中的完整映射表如下Claude 事件hook hint解析出的 nudgeNudge 动作效果SessionStart→session_startsession_startinject仓库基线活跃决策 仓库级偏好PreToolUse(Write\|Edit)→pre_editpre_editinject按被编辑文件定界的偏好 已知 bug 模式PreToolUse(Bash)→bash_prepre_deploy仅部署/基础设施命令否则静默inject带环境限定env-qualified的部署命令服务邻域PostToolUse(Bash)→bash_posttest_failed测试命令且失败inject按症状匹配的历史出现记录 近期变更用于定界PostToolUse(Bash)→bash_posttest_passed测试命令且通过instruct你在编辑 Y 后解决了 X——若非显而易见记录 bugfixStop→stopstopinstruct捕获持久化经验新偏好、决策、修复注意inject与instruct两种动作方向的区别前者向会话注入已排序的图读取结果数据后者注入一条提示你去决定的写入指令而非自动写入。事件到命令的接线hooks.json事件到命令的精确映射定义在 hooks/hooks.json 中共接四个 Claude Code hook 事件、五个 hook hintSessionStart→python3 ${CLAUDE_PLUGIN_ROOT}/hooks/potpie_nudge.py --harness claude --event session_startPreToolUsematcherWrite|Edit|MultiEdit|NotebookEdit→--event pre_editPreToolUsematcherBash→--event bash_prePostToolUsematcherBash→--event bash_postStop→--event stop${CLAUDE_PLUGIN_ROOT}是 Claude Code 插件体系提供的插件根目录变量每个事件以type: command的 command hook 形式执行同一个 Python 适配器仅以--event参数区分语义。这个粗粒度 hintcoarse hint随后由适配器做机械细化。适配器内部机械分类与 fail-safe 语义静默优先的 fail-safe 构造README 强调适配器是 fail-safe 的任何错误或缺失的potpie二进制都意味着它什么都不注入、干净退出Hook 问题永远不可能阻塞你的会话。源码 main() 验证了这一点argparse解析失败参数错误时捕获SystemExit并返回 0potpie二进制在PATH与显式路径中均找不到时debug 记录后返回 0nudge 子进程返回非 0、stdout 无法解析为 JSON、发生TimeoutExpired或任何未预期异常全部吞掉并返回 0、不产生输出。也就是说该适配器在所有失败路径上的行为都是退出码 0 无 stdout对 Claude Code 而言等价于这个 hook 没有任何要注入的内容。事件解析resolve_nudge_event核心分类函数 resolve_nudge_event() 把 hint stdin payload 映射为(nudge_event, fields)返回(None, {})时表示保持静默session_start/stop直接透传无额外字段pre_edit提取file_path作为path字段用于文件级定界bash_pre只有当命令被判定为部署/基础设施命令时才产生pre_deploy附query为命令本身否则静默bash_post只有当命令被判定为测试命令时才继续再按执行结果判定为test_failed附症状查询或test_passed结果模糊时静默其他值若本身就是合法的 nudge 事件名如直接传test_failed则直通——这是为 Codex/Cursor 接线预留的。部署命令与测试命令的标记表命令分类完全基于子串匹配标记表硬编码在适配器中部署标记 _DEPLOY_MARKERS 覆盖kubectl apply/rollout/delete、helm upgrade/install、terraform apply/destroy、docker push、docker compose up、serverless deploy、pulumi up、aws deploy、gcloud run deploy、flyctl deploy、cdk deploy、ansible-playbook等常见部署/基础设施变更动作。测试标记 _TEST_MARKERS 覆盖pytest、unittest、nox、tox、npm/yarn/pnpm test、jest、vitest、mocha、go test、cargo test、gradle test、mvn test、rspec、phpunit、ctest、make test/check等主流测试入口。这两个表意味着普通 Bash 命令如ls、git status在bash_pre和bash_post上都会静默通过不产生任何 nudge 调用。测试结果的判定顺序宁可静默也不误报test_outcome() 的判定顺序值得细读它体现了机械判定模糊即静默的原则显式退出码优先payload 中exit_code/returncode/status等键存在时0为 pass、非 0 为 fail数值失败计数正则N failed/failing/failures/errors命中时只要所有计数为 0 就判 pass——这一count-aware设计专门防止把打印 0 failed 的绿色运行cargo、jest误读为失败锚定标记兜底无数字计数时才看锚定的失败/成功标记如AssertionError、panic:、--- FAIL、not ok、✓、test result: ok、^ok等。裸词 error、failed刻意不作为失败标记因为它们大量出现在绿色输出里测试名、包路径、日志行模糊则 None既无失败信号也无成功信号或两者都有时返回None适配器保持静默而不是发出一个可能错误的test_failednudge。test_failed的query字段由 _failure_symptom() 生成取命令 输出中第一条含error/assert/failed/exception/traceback的行拼接后截断到 300 字符用作症状去图上匹配历史出现记录。调用构造与输出封装build_argv() 最终构造的调用形如potpie --json graph nudge --event nudge_event --session session_id [--path file] [--query text] [--pot pot] [--limit n]render_output() 把 nudge 结果封装为 harness hook 输出有两个值得注意的细节它同时接受新版 Graph V2 workbench 的result包装形状和旧版扁平 V1.5 nudge 形状使已安装的 hook 不需要与 CLI 锁步升级inject_context通过hookSpecificOutput.additionalContext注入但Stop事件下 Claude Code 不 honorsadditionalContext所以改以systemMessage形式呈现为用户可见提示。适配器读取 payload 的访问器session_id_of、file_path_of、command_of等都按点路径列表尝试多个常见键形session_id/sessionId/conversation_id、tool_input.file_path/tool_input.path、tool_input.command/params.command等session_id缺失时回退到环境变量CLAUDE_SESSION_ID/POTPIE_SESSION_ID最终回退default——这是同一适配器跨 harness 复用的基础。子进程超时与调试potpie graph nudge子进程受POTPIE_HOOK_TIMEOUT秒默认 15约束main() 中 subprocess.run 的 timeout 参数设置POTPIE_HOOK_DEBUG1会把适配器的每个决策静默原因、实际执行的 argv、超时/异常写到 stderr在 transcript 模式下可见。这两个环境变量是排查为什么这次没有注入内容的唯二入口。需求的精确表述README 的 Requirements 一节对应源码中的具体取值逻辑potpieCLI 在PATH上或设置环境变量POTPIE_BIN对应 main() 的 --potpie-bin 默认值os.environ.get(POTPIE_BIN, potpie)python3在PATH上hooks.json 里每条命令都以python3启动;项目有激活的 potpotpie pot use id或设置POTPIE_POT对应--pot参数的默认值os.environ.get(POTPIE_POT)见 main()。安装方式三种方式一marketplace推荐/plugin marketplace add /path/to/this/plugin/dir /plugin install potpiepotpie方式二仓库本地 hooks不经 marketplace把 hook 命令加入项目.claude/settings.json的hooks字段命令指向本目录的hooks/potpie_nudge.py并把${CLAUDE_PLUGIN_ROOT}替换为实际目录路径。事件到命令的精确映射即上文 hooks/hooks.json 的内容。方式三一键安装到仓库potpie install --agent claude-plugin会把整个插件目录落入你的仓库。从安装器 install_agent_bundle() 的源码看claude-plugin类型被 AGENT_TYPESdefault/codex/claude/claude-plugin/cursor/opencode识别后整包安装到最近 git 仓库根下的.claude/potpie-plugin/并保持插件内部布局remap 逻辑注释明确.claude-plugin/plugin.json保持为/plugin marketplace add的插件根。注意claude与claude-plugin是两条不同路径前者安装CLAUDE.md skills 到.claude/skills/后者才安装完整插件hooks skills commands。Nudge 的底层策略每个事件读什么、注入什么适配器转发到potpie graph nudge后真正决定读哪些视图、注入数据还是指令的是 context engine 中的策略表。NudgeEvent 枚举与适配器中的NUDGE_EVENTS冻结集合保持一致适配器注释明确要求两者必须匹配。NUDGE_POLICIES 是一张事件到NudgePolicy的映射每个策略声明directiondata注入排序读取结果 /instruction注入写入提示、要读取的视图列表NudgeViewSpec带pass_query/pass_scope/limit参数、以及软相关门min_score。逐项对照事件方向读取的图视图附加行为session_startdatadecisions.active_decisionsdecisions.preferences_for_scopetriggers_ingestTrue另有一次确定性源摄取由 hook 侧ingest --since单独执行pre_editdatadecisions.preferences_for_scopedebugging.prior_occurrences传 query—pre_deploydatainfra_topology.service_neighborhood—test_faileddatadebugging.prior_occurrences传 queryrecent_changes.timeline—test_passedinstruction—注入指令文本刚把一个失败的测试变绿。若 bugfix 非显而易见请捕获以便未来检索以 assert_claim REPRODUCESbug 模式与 RESOLVED修复写入各带 retrieval-grade descriptionstopinstruction—注入指令文本任务结束。把持久化经验作为图断言捕获新偏好POLICY_APPLIES_TO、决策DECIDED、修复RESOLVED先定 truth class、用graph search-entities解析实体身份description 为检索而写源码中还有一道 import 期守卫 _check_nudge_policies_coherent()策略表必须恰好覆盖每一个 nudge 事件且键与策略的event字段一致缺失或错配会静默禁用该事件的 nudge——这解释了为什么一个静默的 hook值得在导入时就报警。插件捆绑的 Skills 与 CommandsREADME 的 Skills 一节说插件捆绑了图契约 skill 与用例工作流 skill。目录结构印证了这一点skills/ 下共 7 个 skillpotpie-graph图契约 skillfrontmatter 标注version: 5是 graph workbench 的总纲覆盖graph status/catalog/read/search-entities/propose/commit --verify/inbox/quality全链路并定义了retrieval-grade description这一最重要的写作规则——每个实体与断言的description是本地 embedder 建索引的自然语言检索卡片要为搜索而非展示而写弱deadlock fix强含症状、同义词、范围与修复位置的完整描述。它还专设 Responding To Nudges 一节规定inject_context视为已排序的图事实直接使用、instruction只是提示你去决定而非自动写入写入按idempotency_key幂等已记录的 nudge 驱动捕获不会重复potpie-project-preferences写码前按最窄 scoperepo/path/service/package/file读偏好scope 越近、置信度越高者优先potpie-infra-architecture读infra_topology.service_neighborhood保留环境限定staging 依赖不是生产依赖的证据识别DEPENDS_ON/DEPLOYED_TO/USES/OWNED_BY等拓扑谓词potpie-debug-memory按症状含精确错误文本先查debugging.prior_occurrences疑似回归再关联recent_changes.timeline--time-window 7dpotpie-source-ingestion显式摄取请求的八阶段流程scope/preflight → todo 计划 → 并行只读发现 → 本地仓库检查 → 托管源 hydration → 证据矩阵 → 身份解析 → 写入 → 验证与质量门并明确禁止 scanner 驱动的图更新potpie-change-timeline、potpie-repo-baseline变更时间线与仓库基线用例。Commands 目录提供两个斜杠命令potpie-feature.mdfeature 工作前先读偏好与基础设施上下文附graph catalog/graph read的具体命令示例与 potpie-record.md工作结束后记录持久化经验先search-entities解析身份再走propose→commit --verify→history的 V2 plan 写入流程。README 所述skills 在你的订阅内会话中运行与 docstring 中推理发生在你的会话里是同一设计哲学Potpie 只负责验证、降格、提交、审计与排序智能部分读什么值得记、如何措辞始终由 harness 承担。其他 HarnessCodex 与 CursorREADME 说明同一适配器经--harness codex|cursor可复用于 Codex 和 Cursor两者 hook 体系不同需按各自文档接线调用python3 potpie_nudge.py --harness name --event hint。从源码看这条复用的可行性在于两点payload 访问器已容忍多种常见键形session_id/sessionId/conversation_id、tool_input.file_path/toolInput.file_path/params.file_path、tool_input.command/params.command等且resolve_nudge_event支持把直接 nudge 事件名session_start、test_failed等连字符别名pre-edit也会被规范化为pre_edit透传绕开 harness 分类法的粗粒度 hint。排查与验证POTPIE_HOOK_DEBUG1适配器的静默原因、实际 argv、子进程退出码都会打到 stderrPOTPIE_HOOK_TIMEOUTnudge 子进程超时上限默认 15 秒适配器各纯函数事件映射、命令分类、argv 构造、输出渲染被直接单元测试见 tests/unit/test_nudge_adapter.py端到端 nudge 链路另有 tests/conformance/test_nudge_e2e.py 覆盖。小结Potpie 的 Claude Code 插件是一条刻意无智能的注入管线hooks.json 做事件接线potpie_nudge.py做机械分类与字段转发部署/测试标记表 宁默不误报的结果判定 全失败路径静默退出potpie graph nudge按NUDGE_POLICIES策略表从项目记忆图的具名视图读出排序结果或写入指令再由 harness你的会话模型决定如何使用与记录。部署三选一marketplace 安装、.claude/settings.json手工接线、或potpie install --agent claude-plugin整包落入.claude/potpie-plugin/。这套hook 无模型、推理在会话的分工使上下文注入对会话零阻塞、对订阅零额外开销同时把全部图操作保留在 Potpie 的验证与审计边界之内。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Potpie 的 Claude Code 插件：用无模型 Hook 把项目记忆图自动注入 Agent 会话
Potpie 的 Claude Code 插件用无模型 Hook 把项目记忆图自动注入 Agent 会话【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 定位为 Context Graph for AI Native SDLC其 Claude Code 插件把 Claude Code 的生命周期事件会话开始、编辑前、Bash 执行前后、任务结束挂接到 Potpie 的项目记忆图上让相关上下文在 Agent 未被询问时自动浮现并在正确的时机提示记录持久化经验。本文基于插件的 README、hook 配置文件与适配器的完整源码讲清这条model-free无模型调用注入链路的事件映射、分类机制、底层 nudge 策略、安装方式与调试手段读完后可在任意项目仓库中部署该插件并理解其每一行行为。设计核心model-free 的 Hook 转发路径插件的 README 开宗明义Hook 路径是model-free的——适配器只把事件形状转发给potpie graph nudge再把返回的上下文/指令注入会话所有什么是事实、对应哪个实体、如何措辞的推理都发生在你的会话里、消耗你自己的订阅额度。这一设计在源码里体现得非常彻底。适配器 hooks/potpie_nudge.py 的模块 docstring 自述它拥有任何触发策略都谈不上、也不做任何模型调用owns no trigger policy and makes no model call其唯一职责是字段转发外加 harness 分类法强制的机械事件名映射一个PostToolUse(Bash)事件必须变成test_failed或test_passed二者之一。所有读什么、是否相关、是否提示写入的决策都住在potpie graph nudge内部而后者只使用本地 embedder。事件与 nudge 的对应关系是插件的核心契约README 中的完整映射表如下Claude 事件hook hint解析出的 nudgeNudge 动作效果SessionStart→session_startsession_startinject仓库基线活跃决策 仓库级偏好PreToolUse(Write\|Edit)→pre_editpre_editinject按被编辑文件定界的偏好 已知 bug 模式PreToolUse(Bash)→bash_prepre_deploy仅部署/基础设施命令否则静默inject带环境限定env-qualified的部署命令服务邻域PostToolUse(Bash)→bash_posttest_failed测试命令且失败inject按症状匹配的历史出现记录 近期变更用于定界PostToolUse(Bash)→bash_posttest_passed测试命令且通过instruct你在编辑 Y 后解决了 X——若非显而易见记录 bugfixStop→stopstopinstruct捕获持久化经验新偏好、决策、修复注意inject与instruct两种动作方向的区别前者向会话注入已排序的图读取结果数据后者注入一条提示你去决定的写入指令而非自动写入。事件到命令的接线hooks.json事件到命令的精确映射定义在 hooks/hooks.json 中共接四个 Claude Code hook 事件、五个 hook hintSessionStart→python3 ${CLAUDE_PLUGIN_ROOT}/hooks/potpie_nudge.py --harness claude --event session_startPreToolUsematcherWrite|Edit|MultiEdit|NotebookEdit→--event pre_editPreToolUsematcherBash→--event bash_prePostToolUsematcherBash→--event bash_postStop→--event stop${CLAUDE_PLUGIN_ROOT}是 Claude Code 插件体系提供的插件根目录变量每个事件以type: command的 command hook 形式执行同一个 Python 适配器仅以--event参数区分语义。这个粗粒度 hintcoarse hint随后由适配器做机械细化。适配器内部机械分类与 fail-safe 语义静默优先的 fail-safe 构造README 强调适配器是 fail-safe 的任何错误或缺失的potpie二进制都意味着它什么都不注入、干净退出Hook 问题永远不可能阻塞你的会话。源码 main() 验证了这一点argparse解析失败参数错误时捕获SystemExit并返回 0potpie二进制在PATH与显式路径中均找不到时debug 记录后返回 0nudge 子进程返回非 0、stdout 无法解析为 JSON、发生TimeoutExpired或任何未预期异常全部吞掉并返回 0、不产生输出。也就是说该适配器在所有失败路径上的行为都是退出码 0 无 stdout对 Claude Code 而言等价于这个 hook 没有任何要注入的内容。事件解析resolve_nudge_event核心分类函数 resolve_nudge_event() 把 hint stdin payload 映射为(nudge_event, fields)返回(None, {})时表示保持静默session_start/stop直接透传无额外字段pre_edit提取file_path作为path字段用于文件级定界bash_pre只有当命令被判定为部署/基础设施命令时才产生pre_deploy附query为命令本身否则静默bash_post只有当命令被判定为测试命令时才继续再按执行结果判定为test_failed附症状查询或test_passed结果模糊时静默其他值若本身就是合法的 nudge 事件名如直接传test_failed则直通——这是为 Codex/Cursor 接线预留的。部署命令与测试命令的标记表命令分类完全基于子串匹配标记表硬编码在适配器中部署标记 _DEPLOY_MARKERS 覆盖kubectl apply/rollout/delete、helm upgrade/install、terraform apply/destroy、docker push、docker compose up、serverless deploy、pulumi up、aws deploy、gcloud run deploy、flyctl deploy、cdk deploy、ansible-playbook等常见部署/基础设施变更动作。测试标记 _TEST_MARKERS 覆盖pytest、unittest、nox、tox、npm/yarn/pnpm test、jest、vitest、mocha、go test、cargo test、gradle test、mvn test、rspec、phpunit、ctest、make test/check等主流测试入口。这两个表意味着普通 Bash 命令如ls、git status在bash_pre和bash_post上都会静默通过不产生任何 nudge 调用。测试结果的判定顺序宁可静默也不误报test_outcome() 的判定顺序值得细读它体现了机械判定模糊即静默的原则显式退出码优先payload 中exit_code/returncode/status等键存在时0为 pass、非 0 为 fail数值失败计数正则N failed/failing/failures/errors命中时只要所有计数为 0 就判 pass——这一count-aware设计专门防止把打印 0 failed 的绿色运行cargo、jest误读为失败锚定标记兜底无数字计数时才看锚定的失败/成功标记如AssertionError、panic:、--- FAIL、not ok、✓、test result: ok、^ok等。裸词 error、failed刻意不作为失败标记因为它们大量出现在绿色输出里测试名、包路径、日志行模糊则 None既无失败信号也无成功信号或两者都有时返回None适配器保持静默而不是发出一个可能错误的test_failednudge。test_failed的query字段由 _failure_symptom() 生成取命令 输出中第一条含error/assert/failed/exception/traceback的行拼接后截断到 300 字符用作症状去图上匹配历史出现记录。调用构造与输出封装build_argv() 最终构造的调用形如potpie --json graph nudge --event nudge_event --session session_id [--path file] [--query text] [--pot pot] [--limit n]render_output() 把 nudge 结果封装为 harness hook 输出有两个值得注意的细节它同时接受新版 Graph V2 workbench 的result包装形状和旧版扁平 V1.5 nudge 形状使已安装的 hook 不需要与 CLI 锁步升级inject_context通过hookSpecificOutput.additionalContext注入但Stop事件下 Claude Code 不 honorsadditionalContext所以改以systemMessage形式呈现为用户可见提示。适配器读取 payload 的访问器session_id_of、file_path_of、command_of等都按点路径列表尝试多个常见键形session_id/sessionId/conversation_id、tool_input.file_path/tool_input.path、tool_input.command/params.command等session_id缺失时回退到环境变量CLAUDE_SESSION_ID/POTPIE_SESSION_ID最终回退default——这是同一适配器跨 harness 复用的基础。子进程超时与调试potpie graph nudge子进程受POTPIE_HOOK_TIMEOUT秒默认 15约束main() 中 subprocess.run 的 timeout 参数设置POTPIE_HOOK_DEBUG1会把适配器的每个决策静默原因、实际执行的 argv、超时/异常写到 stderr在 transcript 模式下可见。这两个环境变量是排查为什么这次没有注入内容的唯二入口。需求的精确表述README 的 Requirements 一节对应源码中的具体取值逻辑potpieCLI 在PATH上或设置环境变量POTPIE_BIN对应 main() 的 --potpie-bin 默认值os.environ.get(POTPIE_BIN, potpie)python3在PATH上hooks.json 里每条命令都以python3启动;项目有激活的 potpotpie pot use id或设置POTPIE_POT对应--pot参数的默认值os.environ.get(POTPIE_POT)见 main()。安装方式三种方式一marketplace推荐/plugin marketplace add /path/to/this/plugin/dir /plugin install potpiepotpie方式二仓库本地 hooks不经 marketplace把 hook 命令加入项目.claude/settings.json的hooks字段命令指向本目录的hooks/potpie_nudge.py并把${CLAUDE_PLUGIN_ROOT}替换为实际目录路径。事件到命令的精确映射即上文 hooks/hooks.json 的内容。方式三一键安装到仓库potpie install --agent claude-plugin会把整个插件目录落入你的仓库。从安装器 install_agent_bundle() 的源码看claude-plugin类型被 AGENT_TYPESdefault/codex/claude/claude-plugin/cursor/opencode识别后整包安装到最近 git 仓库根下的.claude/potpie-plugin/并保持插件内部布局remap 逻辑注释明确.claude-plugin/plugin.json保持为/plugin marketplace add的插件根。注意claude与claude-plugin是两条不同路径前者安装CLAUDE.md skills 到.claude/skills/后者才安装完整插件hooks skills commands。Nudge 的底层策略每个事件读什么、注入什么适配器转发到potpie graph nudge后真正决定读哪些视图、注入数据还是指令的是 context engine 中的策略表。NudgeEvent 枚举与适配器中的NUDGE_EVENTS冻结集合保持一致适配器注释明确要求两者必须匹配。NUDGE_POLICIES 是一张事件到NudgePolicy的映射每个策略声明directiondata注入排序读取结果 /instruction注入写入提示、要读取的视图列表NudgeViewSpec带pass_query/pass_scope/limit参数、以及软相关门min_score。逐项对照事件方向读取的图视图附加行为session_startdatadecisions.active_decisionsdecisions.preferences_for_scopetriggers_ingestTrue另有一次确定性源摄取由 hook 侧ingest --since单独执行pre_editdatadecisions.preferences_for_scopedebugging.prior_occurrences传 query—pre_deploydatainfra_topology.service_neighborhood—test_faileddatadebugging.prior_occurrences传 queryrecent_changes.timeline—test_passedinstruction—注入指令文本刚把一个失败的测试变绿。若 bugfix 非显而易见请捕获以便未来检索以 assert_claim REPRODUCESbug 模式与 RESOLVED修复写入各带 retrieval-grade descriptionstopinstruction—注入指令文本任务结束。把持久化经验作为图断言捕获新偏好POLICY_APPLIES_TO、决策DECIDED、修复RESOLVED先定 truth class、用graph search-entities解析实体身份description 为检索而写源码中还有一道 import 期守卫 _check_nudge_policies_coherent()策略表必须恰好覆盖每一个 nudge 事件且键与策略的event字段一致缺失或错配会静默禁用该事件的 nudge——这解释了为什么一个静默的 hook值得在导入时就报警。插件捆绑的 Skills 与 CommandsREADME 的 Skills 一节说插件捆绑了图契约 skill 与用例工作流 skill。目录结构印证了这一点skills/ 下共 7 个 skillpotpie-graph图契约 skillfrontmatter 标注version: 5是 graph workbench 的总纲覆盖graph status/catalog/read/search-entities/propose/commit --verify/inbox/quality全链路并定义了retrieval-grade description这一最重要的写作规则——每个实体与断言的description是本地 embedder 建索引的自然语言检索卡片要为搜索而非展示而写弱deadlock fix强含症状、同义词、范围与修复位置的完整描述。它还专设 Responding To Nudges 一节规定inject_context视为已排序的图事实直接使用、instruction只是提示你去决定而非自动写入写入按idempotency_key幂等已记录的 nudge 驱动捕获不会重复potpie-project-preferences写码前按最窄 scoperepo/path/service/package/file读偏好scope 越近、置信度越高者优先potpie-infra-architecture读infra_topology.service_neighborhood保留环境限定staging 依赖不是生产依赖的证据识别DEPENDS_ON/DEPLOYED_TO/USES/OWNED_BY等拓扑谓词potpie-debug-memory按症状含精确错误文本先查debugging.prior_occurrences疑似回归再关联recent_changes.timeline--time-window 7dpotpie-source-ingestion显式摄取请求的八阶段流程scope/preflight → todo 计划 → 并行只读发现 → 本地仓库检查 → 托管源 hydration → 证据矩阵 → 身份解析 → 写入 → 验证与质量门并明确禁止 scanner 驱动的图更新potpie-change-timeline、potpie-repo-baseline变更时间线与仓库基线用例。Commands 目录提供两个斜杠命令potpie-feature.mdfeature 工作前先读偏好与基础设施上下文附graph catalog/graph read的具体命令示例与 potpie-record.md工作结束后记录持久化经验先search-entities解析身份再走propose→commit --verify→history的 V2 plan 写入流程。README 所述skills 在你的订阅内会话中运行与 docstring 中推理发生在你的会话里是同一设计哲学Potpie 只负责验证、降格、提交、审计与排序智能部分读什么值得记、如何措辞始终由 harness 承担。其他 HarnessCodex 与 CursorREADME 说明同一适配器经--harness codex|cursor可复用于 Codex 和 Cursor两者 hook 体系不同需按各自文档接线调用python3 potpie_nudge.py --harness name --event hint。从源码看这条复用的可行性在于两点payload 访问器已容忍多种常见键形session_id/sessionId/conversation_id、tool_input.file_path/toolInput.file_path/params.file_path、tool_input.command/params.command等且resolve_nudge_event支持把直接 nudge 事件名session_start、test_failed等连字符别名pre-edit也会被规范化为pre_edit透传绕开 harness 分类法的粗粒度 hint。排查与验证POTPIE_HOOK_DEBUG1适配器的静默原因、实际 argv、子进程退出码都会打到 stderrPOTPIE_HOOK_TIMEOUTnudge 子进程超时上限默认 15 秒适配器各纯函数事件映射、命令分类、argv 构造、输出渲染被直接单元测试见 tests/unit/test_nudge_adapter.py端到端 nudge 链路另有 tests/conformance/test_nudge_e2e.py 覆盖。小结Potpie 的 Claude Code 插件是一条刻意无智能的注入管线hooks.json 做事件接线potpie_nudge.py做机械分类与字段转发部署/测试标记表 宁默不误报的结果判定 全失败路径静默退出potpie graph nudge按NUDGE_POLICIES策略表从项目记忆图的具名视图读出排序结果或写入指令再由 harness你的会话模型决定如何使用与记录。部署三选一marketplace 安装、.claude/settings.json手工接线、或potpie install --agent claude-plugin整包落入.claude/potpie-plugin/。这套hook 无模型、推理在会话的分工使上下文注入对会话零阻塞、对订阅零额外开销同时把全部图操作保留在 Potpie 的验证与审计边界之内。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考