Potpie change-timeline 技能从 Context Graph 检索与记录项目变更时间线【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie在 AI 原生 SDLC 中最近改了什么、回归的根因可能在哪是 Agent 最常遇到的取证问题。Potpie 的potpie-change-timeline技能SKILL.md为 Agent 规定了完整的变更时间线工作流先用potpie graph read的recent_changes.timeline视图按 pot项目边界拉取排好序的变更证据再用 workbench 写流程catalog → describe → propose → commit → history把 GitHub、Linear、Jira、文档与部署记录中的变更持久化进图。读完本篇你能掌握 timeline 视图的三个标准查询姿势、相关性而非证明的证据使用纪律以及 harness-led而非 scanner-led的历史记录写路径。1. 技能定位什么时候触发 change-timeline该技能以标准 Agent Skill 形式存放在项目模板目录 .agents/skills/ 下frontmatter 声明了触发条件name: potpie-change-timeline description: Use when an agent needs recent or historical change context: what changed recently, regressions, merged PRs, tickets, docs, incidents, deployments, releases, and source-history ingestion.即以下三类场景应使用本技能用户询问最近改了什么recent or historical change context调试疑似回归possible regression需要找到时间上相关的变更需要从 GitHub、Linear、Jira、文档或部署记录中摄取源历史source-history ingestion。项目级的 AGENTS.md 也把它登记为六个仓库本地技能之一职责描述为recent or historical PRs, tickets, docs, incidents, deployments, and regression correlation与potpie-debug-memory历史 bug/修复、potpie-repo-baseline仓库基线等技能分工明确。2. Fast Path先读项目级时间线不要窄化到当前仓库技能的第一原则是先读项目时间线。一个 pot 是项目边界project boundary可以包含多个仓库因此除非用户明确要求否则不要把查询收窄到当前 repo。2.1 相对时间窗口最近 7 天potpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --time-window 7d \ --limit 202.2 用户给出精确日期用--since/--untilpotpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --since 2026-06-01 \ --until 2026-06-15 \ --limit 502.3 用户给出服务、环境或主题叠加--scope与--querypotpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --scope service:service-name \ --query symptom feature deployment \ --time-window 14d \ --limit 202.4 参数语义从源码确认的默认值与行为结合 graph read 命令实现potpie/cli/commands/graph.py上述命令的完整参数边界如下参数语义与默认值--subgraph/--view均必填且--view不允许携带subgraph.view的完整限定写法带了会报 graph read now requires --subgraph --view--time-window/--window相对回看窗口如24h、7d、2w当--since设置时会被忽略--since/--untilISO 时间下/上界与--time-window经_resolve_time_bounds统一解析--scopekey:value[,key:value]形式timeline 支持service:、repo:等键另有独立的--repoowner/repo、URL 或current缺省即项目级时间线--query语义锚点配合--query-threshold默认0.70越小越宽松--limit默认12技能示例显式放大到 20/50--formatauto \| raw \| events \| table \| jsonltimeline 视图默认渲染为eventsbullet 列表技能示例显式指定table得到 markdown 表格--sortauto \| score \| occurred_attimeline 默认按occurred_at排序保证时间线有序--dedupeauto \| none \| source_ref \| activitytimeline recent糖化路径固定用source_ref去重此外源码中有一个关键细节timeline 视图在不带--query时ReadRequest会携带freshness_preferencefresh带 query 时为balanced见 graph read 的 freshness 分支。这让最近改了什么这类无查询词的时间线读取天然偏向新鲜证据。同一语义还有更短的入口potpie timeline recent它是graph read --subgraph recent_changes --view timeline的 sugar固定sortoccurred_at、dedupesource_ref且支持--service作用域见 timeline recent 命令实现。3. 读取底层timeline 读的是什么谓词、为什么可信recent_changes.timeline是 Potpie 的 9 个命名视图之一共 8 个 subgraph其背后是专用的timelinereader。根据 Querying the Context Graph 文档 的 reader 对照表timeline reader 读取MENTIONS、TOUCHED、PERFORMED、AUTHORED四类谓词命中的是since/until窗口内触及 scope 的Activity行时间字段优先occurred_at回退valid_atPR、commit、issue、deployment 都会坍缩成单一Activity实体key 前缀activityreader 会按 activity 去重边、折叠为一个事件所有读取走同一条 read trunkReadOrchestrator→ 9 个 reader →ClaimQueryPort.find_claims→RankingService→EnvelopeBuilder返回的是排序后的证据而非合成答案——Potpie 不做服务端答案总结由 Agent 基于证据自行推理。视图契约哪些输入合法、排序输入、是否有 traversal由GraphViewSpec声明graph read会先按视图的ViewContract校验required_any_scope与supported_filters不合法时返回missing_required_scope/unsupported_filter而不是执行一次畸形读取。视图与谓词的权威定义在 graph_views.py 与 graph_workbench_ontology.py 中后者内置了potpie graph read --subgraph recent_changes --view timeline --time-window 7d --json这类示例命令。4. Apply Results时间线是相关性不是证明技能对结果的解读给出了明确纪律必须完整遵守Timeline context is correlation, not proof用时间线证据来选择要检查的文件、PR、ticket 或部署然后在归罪某个变更之前先核实其 source ref未记录的本地工作不在时间线里timeline 读取不包含未提交的本地改动除非它们已被记录进图——所以最近没人改过 X不等于X 没有被本地动过。这两条把技能从查个列表提升为可审计的取证流程时间线负责缩小嫌疑集source ref 负责最终确认。5. Record Historyharness-led 的历史记录写路径当 Agent 需要把 GitHub、Linear、Jira、文档等源的变更写入图时技能规定了两条前置约束和一条标准写流程。5.1 前置约束先用 Agent 自己的 integration tools/connectors 水合hydrate记录再写图不要使用 Potpie CLI 的 queue ingestion 作为源历史路径。这与 potpie-source-ingestion 技能 的 Phase 4: Hosted/GitHub Hydration明确写有 not Potpie queue ingestion commands以及 AGENTS.md 的 Ingestion Boundary 章节三方一致Potpie 只做校验、降阶lowering、提交、审计与排序语义判断由 harnessAgent完成。Timeline capture is harness-led禁止 scanner-driven 的图更新也禁止在不读源的情况下把源标题source titles直接变成事实。5.2 标准 workbench 写流程五条命令读完源之后使用技能给出的完整序列potpie --json graph catalog --task record timeline change potpie --json graph describe recent_changes --view timeline --examples potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id逐条对应到源码实现命令实现与行为graph catalog --task ...契约发现返回版本、命令、truth classes、mutation ops、source authorities、match_mode、视图与实体/谓词类型。--task在 V1.5 被接受但忽略见 graph_catalog 与 querying.mdgraph describe recent_changes --view timeline --examples上下文无关的 typed 元数据操作不选择 pot、不获取 engine lease返回该视图的输入契约与示例并推荐下一步graph read见 graph_describegraph propose --file mutation.json提交语义 mutation JSON也可从 stdin 读入可选--ttl如30m、1h、2d控制 plan 过期返回 proposal 状态/diff/冲突/review 标记见 graph_proposegraph commit plan_id --verify提交 plan--verify会读回已提交的 claim keys 并执行 post-commit 质量检查验证失败会以 validation 退出码失败见 graph_commit。proposal 若处于review_required状态需要按策略附--approved-bygraph history --plan plan_id变更/claim/实体的审计历史也支持--entity、--claim、--mutation、--since/--until默认--limit 50见 graph_historymutation JSON 的结构可从 graph.py 中的静态模板 看出形状顶层为pot_id、idempotency_key、created_bysurface/harness、operations[]每个 op 携带op如assert_claim、link_entities、upsert_entity、subject/object实体键与类型、predicate、truth、confidence、description与evidencesource_ref authority。对于时间线记录truth应使用timeline_event在 potpie-source-ingestion 技能的证据矩阵中定义为 source-time activity from PRs, tickets, releases, or deployments。5.3 两个必须遵守的语义规则occurred_at用源事件时间而不是摄取时间否则时间线视图的since/until窗口与occurred_at排序会全部失真只记录源明确支持的关联fix、decision、bug pattern、infra 链接只在源材料显式支持时才添加。这与 source-ingestion 技能 Tickets and issues … do not prove a fix unless tied to a merged PR, commit, deployment, or explicit shipped-resolution source 的规则一脉相承。6. 与相邻技能的协作关系change-timeline 不是孤立技能仓库中的技能编排形成了清晰的先后顺序先 baseline后 timelinepotpie-source-ingestion 明确要求run baseline before change history——用potpie-repo-baseline建立仓库目的、服务、环境、API、数据存储等基线事实后再用potpie-change-timeline处理近期或历史活动且不得从 PR 标题或 issue 状态推断基线架构。写侧共享同一纪律change-timeline 的 Record History 与 source-ingestion 的 Phase 5-8证据矩阵、身份解析、propose/commit --verify、质量门使用完全相同的 workbench 写路径graph search-entities在写前做身份解析identity resolution before a write避免近似重复实体。质量门graph commit --verify报警或失败时按 source-ingestion 的 Phase 8 用graph read --subgraph recent_changes --view timeline --scope repo:repo与graph quality duplicate-candidates / low-confidence / conflicting-claims / orphan-entities下钻。7. 适用前提与小结适用前提本地potpieCLI 可用且当前 pot 的图数据面就绪可先用potpie graph status/potpie graph catalog预检--json输出用于工作流中的机器解析人类可读输出用于例行定向。图数据平面当前为GRAPH_CONTRACT_VERSIONv1.5见 querying.md 与 graph.py 中的契约导入。一句话总结这个技能的设计哲学读侧recent_changes.timeline视图给出按occurred_at排序、按 activity 去重、按证据强度打分的项目级时间线Agent 只把它当相关性线索写侧历史摄取必须由 harness 读源后走catalog → describe → propose → commit --verify → history的受校验路径拒绝一切 scanner-driven 和标题即事实的捷径。这两条纪律共同保证了 Context Graph 中每条时间线事件都携带 source ref、truth classtimeline_event与可审计的提交历史。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Potpie change-timeline 技能：从 Context Graph 检索与记录项目变更时间线
Potpie change-timeline 技能从 Context Graph 检索与记录项目变更时间线【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie在 AI 原生 SDLC 中最近改了什么、回归的根因可能在哪是 Agent 最常遇到的取证问题。Potpie 的potpie-change-timeline技能SKILL.md为 Agent 规定了完整的变更时间线工作流先用potpie graph read的recent_changes.timeline视图按 pot项目边界拉取排好序的变更证据再用 workbench 写流程catalog → describe → propose → commit → history把 GitHub、Linear、Jira、文档与部署记录中的变更持久化进图。读完本篇你能掌握 timeline 视图的三个标准查询姿势、相关性而非证明的证据使用纪律以及 harness-led而非 scanner-led的历史记录写路径。1. 技能定位什么时候触发 change-timeline该技能以标准 Agent Skill 形式存放在项目模板目录 .agents/skills/ 下frontmatter 声明了触发条件name: potpie-change-timeline description: Use when an agent needs recent or historical change context: what changed recently, regressions, merged PRs, tickets, docs, incidents, deployments, releases, and source-history ingestion.即以下三类场景应使用本技能用户询问最近改了什么recent or historical change context调试疑似回归possible regression需要找到时间上相关的变更需要从 GitHub、Linear、Jira、文档或部署记录中摄取源历史source-history ingestion。项目级的 AGENTS.md 也把它登记为六个仓库本地技能之一职责描述为recent or historical PRs, tickets, docs, incidents, deployments, and regression correlation与potpie-debug-memory历史 bug/修复、potpie-repo-baseline仓库基线等技能分工明确。2. Fast Path先读项目级时间线不要窄化到当前仓库技能的第一原则是先读项目时间线。一个 pot 是项目边界project boundary可以包含多个仓库因此除非用户明确要求否则不要把查询收窄到当前 repo。2.1 相对时间窗口最近 7 天potpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --time-window 7d \ --limit 202.2 用户给出精确日期用--since/--untilpotpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --since 2026-06-01 \ --until 2026-06-15 \ --limit 502.3 用户给出服务、环境或主题叠加--scope与--querypotpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --scope service:service-name \ --query symptom feature deployment \ --time-window 14d \ --limit 202.4 参数语义从源码确认的默认值与行为结合 graph read 命令实现potpie/cli/commands/graph.py上述命令的完整参数边界如下参数语义与默认值--subgraph/--view均必填且--view不允许携带subgraph.view的完整限定写法带了会报 graph read now requires --subgraph --view--time-window/--window相对回看窗口如24h、7d、2w当--since设置时会被忽略--since/--untilISO 时间下/上界与--time-window经_resolve_time_bounds统一解析--scopekey:value[,key:value]形式timeline 支持service:、repo:等键另有独立的--repoowner/repo、URL 或current缺省即项目级时间线--query语义锚点配合--query-threshold默认0.70越小越宽松--limit默认12技能示例显式放大到 20/50--formatauto \| raw \| events \| table \| jsonltimeline 视图默认渲染为eventsbullet 列表技能示例显式指定table得到 markdown 表格--sortauto \| score \| occurred_attimeline 默认按occurred_at排序保证时间线有序--dedupeauto \| none \| source_ref \| activitytimeline recent糖化路径固定用source_ref去重此外源码中有一个关键细节timeline 视图在不带--query时ReadRequest会携带freshness_preferencefresh带 query 时为balanced见 graph read 的 freshness 分支。这让最近改了什么这类无查询词的时间线读取天然偏向新鲜证据。同一语义还有更短的入口potpie timeline recent它是graph read --subgraph recent_changes --view timeline的 sugar固定sortoccurred_at、dedupesource_ref且支持--service作用域见 timeline recent 命令实现。3. 读取底层timeline 读的是什么谓词、为什么可信recent_changes.timeline是 Potpie 的 9 个命名视图之一共 8 个 subgraph其背后是专用的timelinereader。根据 Querying the Context Graph 文档 的 reader 对照表timeline reader 读取MENTIONS、TOUCHED、PERFORMED、AUTHORED四类谓词命中的是since/until窗口内触及 scope 的Activity行时间字段优先occurred_at回退valid_atPR、commit、issue、deployment 都会坍缩成单一Activity实体key 前缀activityreader 会按 activity 去重边、折叠为一个事件所有读取走同一条 read trunkReadOrchestrator→ 9 个 reader →ClaimQueryPort.find_claims→RankingService→EnvelopeBuilder返回的是排序后的证据而非合成答案——Potpie 不做服务端答案总结由 Agent 基于证据自行推理。视图契约哪些输入合法、排序输入、是否有 traversal由GraphViewSpec声明graph read会先按视图的ViewContract校验required_any_scope与supported_filters不合法时返回missing_required_scope/unsupported_filter而不是执行一次畸形读取。视图与谓词的权威定义在 graph_views.py 与 graph_workbench_ontology.py 中后者内置了potpie graph read --subgraph recent_changes --view timeline --time-window 7d --json这类示例命令。4. Apply Results时间线是相关性不是证明技能对结果的解读给出了明确纪律必须完整遵守Timeline context is correlation, not proof用时间线证据来选择要检查的文件、PR、ticket 或部署然后在归罪某个变更之前先核实其 source ref未记录的本地工作不在时间线里timeline 读取不包含未提交的本地改动除非它们已被记录进图——所以最近没人改过 X不等于X 没有被本地动过。这两条把技能从查个列表提升为可审计的取证流程时间线负责缩小嫌疑集source ref 负责最终确认。5. Record Historyharness-led 的历史记录写路径当 Agent 需要把 GitHub、Linear、Jira、文档等源的变更写入图时技能规定了两条前置约束和一条标准写流程。5.1 前置约束先用 Agent 自己的 integration tools/connectors 水合hydrate记录再写图不要使用 Potpie CLI 的 queue ingestion 作为源历史路径。这与 potpie-source-ingestion 技能 的 Phase 4: Hosted/GitHub Hydration明确写有 not Potpie queue ingestion commands以及 AGENTS.md 的 Ingestion Boundary 章节三方一致Potpie 只做校验、降阶lowering、提交、审计与排序语义判断由 harnessAgent完成。Timeline capture is harness-led禁止 scanner-driven 的图更新也禁止在不读源的情况下把源标题source titles直接变成事实。5.2 标准 workbench 写流程五条命令读完源之后使用技能给出的完整序列potpie --json graph catalog --task record timeline change potpie --json graph describe recent_changes --view timeline --examples potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id逐条对应到源码实现命令实现与行为graph catalog --task ...契约发现返回版本、命令、truth classes、mutation ops、source authorities、match_mode、视图与实体/谓词类型。--task在 V1.5 被接受但忽略见 graph_catalog 与 querying.mdgraph describe recent_changes --view timeline --examples上下文无关的 typed 元数据操作不选择 pot、不获取 engine lease返回该视图的输入契约与示例并推荐下一步graph read见 graph_describegraph propose --file mutation.json提交语义 mutation JSON也可从 stdin 读入可选--ttl如30m、1h、2d控制 plan 过期返回 proposal 状态/diff/冲突/review 标记见 graph_proposegraph commit plan_id --verify提交 plan--verify会读回已提交的 claim keys 并执行 post-commit 质量检查验证失败会以 validation 退出码失败见 graph_commit。proposal 若处于review_required状态需要按策略附--approved-bygraph history --plan plan_id变更/claim/实体的审计历史也支持--entity、--claim、--mutation、--since/--until默认--limit 50见 graph_historymutation JSON 的结构可从 graph.py 中的静态模板 看出形状顶层为pot_id、idempotency_key、created_bysurface/harness、operations[]每个 op 携带op如assert_claim、link_entities、upsert_entity、subject/object实体键与类型、predicate、truth、confidence、description与evidencesource_ref authority。对于时间线记录truth应使用timeline_event在 potpie-source-ingestion 技能的证据矩阵中定义为 source-time activity from PRs, tickets, releases, or deployments。5.3 两个必须遵守的语义规则occurred_at用源事件时间而不是摄取时间否则时间线视图的since/until窗口与occurred_at排序会全部失真只记录源明确支持的关联fix、decision、bug pattern、infra 链接只在源材料显式支持时才添加。这与 source-ingestion 技能 Tickets and issues … do not prove a fix unless tied to a merged PR, commit, deployment, or explicit shipped-resolution source 的规则一脉相承。6. 与相邻技能的协作关系change-timeline 不是孤立技能仓库中的技能编排形成了清晰的先后顺序先 baseline后 timelinepotpie-source-ingestion 明确要求run baseline before change history——用potpie-repo-baseline建立仓库目的、服务、环境、API、数据存储等基线事实后再用potpie-change-timeline处理近期或历史活动且不得从 PR 标题或 issue 状态推断基线架构。写侧共享同一纪律change-timeline 的 Record History 与 source-ingestion 的 Phase 5-8证据矩阵、身份解析、propose/commit --verify、质量门使用完全相同的 workbench 写路径graph search-entities在写前做身份解析identity resolution before a write避免近似重复实体。质量门graph commit --verify报警或失败时按 source-ingestion 的 Phase 8 用graph read --subgraph recent_changes --view timeline --scope repo:repo与graph quality duplicate-candidates / low-confidence / conflicting-claims / orphan-entities下钻。7. 适用前提与小结适用前提本地potpieCLI 可用且当前 pot 的图数据面就绪可先用potpie graph status/potpie graph catalog预检--json输出用于工作流中的机器解析人类可读输出用于例行定向。图数据平面当前为GRAPH_CONTRACT_VERSIONv1.5见 querying.md 与 graph.py 中的契约导入。一句话总结这个技能的设计哲学读侧recent_changes.timeline视图给出按occurred_at排序、按 activity 去重、按证据强度打分的项目级时间线Agent 只把它当相关性线索写侧历史摄取必须由 harness 读源后走catalog → describe → propose → commit --verify → history的受校验路径拒绝一切 scanner-driven 和标题即事实的捷径。这两条纪律共同保证了 Context Graph 中每条时间线事件都携带 source ref、truth classtimeline_event与可审计的提交历史。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考