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 20

2.2 用户给出精确日期：用`--since`/`--until`

potpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --since 2026-06-01 \ --until 2026-06-15 \ --limit 50

2.3 用户给出服务、环境或主题：叠加`--scope`与`--query`

potpie graph read \ --subgraph recent_changes \ --view timeline \ --format table \ --scope service:<service-name> \ --query "<symptom feature deployment>" \ --time-window 14d \ --limit 20

2.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`/`--until`	ISO 时间下/上界，与`--time-window`经`_resolve_time_bounds`统一解析
`--scope`	`key:value[,key:value]`形式，timeline 支持`service:`、`repo:`等键；另有独立的`--repo`（`owner/repo`、URL 或`current`），缺省即项目级时间线
`--query`	语义锚点，配合`--query-threshold`（默认`0.70`，越小越宽松）
`--limit`	默认`12`，技能示例显式放大到 20/50
`--format`	`auto \\| raw \\| events \\| table \\| jsonl`；timeline 视图默认渲染为`events`（bullet 列表），技能示例显式指定`table`得到 markdown 表格
`--sort`	`auto \\| score \\| occurred_at`，timeline 默认按`occurred_at`排序，保证时间线有序
`--dedupe`	`auto \\| none \\| source_ref \\| activity`；`timeline recent`糖化路径固定用`source_ref`去重

此外源码中有一个关键细节：timeline 视图在不带--query时，ReadRequest会携带freshness_preference="fresh"（带 query 时为balanced），见 graph read 的 freshness 分支。这让"最近改了什么"这类无查询词的时间线读取天然偏向新鲜证据。

同一语义还有更短的入口potpie timeline recent：它是graph read --subgraph recent_changes --view timeline的 sugar，固定sort=occurred_at、dedupe=source_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_at）；
PR、commit、issue、deployment 都会坍缩成单一Activity实体（key 前缀activity），reader 会按 activity 去重边、折叠为一个事件；
所有读取走同一条 read trunk（ReadOrchestrator→ 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 History：harness-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）、提交、审计与排序，语义判断由 harness（Agent）完成。
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.md）
`graph describe recent_changes --view timeline --examples`	上下文无关的 typed 元数据操作，不选择 pot、不获取 engine lease；返回该视图的输入契约与示例，并推荐下一步`graph read`（见 graph_describe）
`graph propose --file mutation.json`	提交语义 mutation JSON（也可从 stdin 读入），可选`--ttl`（如`30m`、`1h`、`2d`）控制 plan 过期；返回 proposal 状态/diff/冲突/review 标记（见 graph_propose）
`graph commit <plan_id> --verify`	提交 plan；`--verify`会读回已提交的 claim keys 并执行 post-commit 质量检查，验证失败会以 validation 退出码失败（见 graph_commit）。proposal 若处于`review_required`状态，需要按策略附`--approved-by`
`graph history --plan <plan_id>`	变更/claim/实体的审计历史，也支持`--entity`、`--claim`、`--mutation`、`--since/--until`，默认`--limit 50`（见 graph_history）

mutation JSON 的结构可从 graph.py 中的静态模板看出形状：顶层为pot_id、idempotency_key、created_by（surface/harness）、operations[]；每个 op 携带op（如assert_claim、link_entities、upsert_entity）、subject/object实体键与类型、predicate、truth、confidence、description与evidence（source_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，后 timeline：potpie-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_VERSION="v1.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 class（timeline_event）与可审计的提交历史。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析