prior-work-retrieval

过往工作检索

仅当上方出现触发条件时，才在开展大量生产工作前运行此流程。只读的当前状态检查仍应直接进行，除非用户要求了解历史。此流程并非为了再生成一份摘要，而是要回答：已有内容是什么，哪个来源是最新的，应该复用什么，以及哪些内容确实是新的？

不适用于：检查当前文件、常规错误修复、机械式验证，或仅仅因为最终答案恰好是报告／摘要而开展的任务。提及当前／现有的测试、README、文件、实现、行为或验证，本身并不代表用户要求检索过往工作。不要仅仅因为新工作可能与已有内容重复就推断存在触发条件——这种风险本身并不构成明确请求。

完成要求

只有满足以下所有条件，检索流程才算完成：

1. 用一句话写明任务真正的业务目标。
2. 清单中声明的每个相关载体都报告为 searched、manual_completed，或明确指出失败／覆盖范围缺口。
3. 候选声明须在其原始路径或记录中打开核实，不能仅凭搜索摘要采信。
4. 每项采纳内容都要做出 reuse 或 adapt 决策，并说明与当前任务相关的理由。如果没有采纳任何内容，回执中必须包含具体的 no_reuse_reason。
5. scripts/prior_work.py check 接受本会话的回执。

retrieved 不等于 verified；verified 不等于 reused。请将这些状态分开，避免“我搜过了”冒充“我采用了我们最合适的过往工作”。

工作流程

1. 先阅读本地操作上下文

查询前，先阅读当前项目的 AGENTS.md／CLAUDE.md、导航索引，以及其中指定的任何 North Star／当前决策文件。历史资料不能凌驾于更新的明确决策之上。

2. 验证明确的来源清单

清单是唯一的发现范围。不能仅因某个目录按惯例理应存在，就认定它存在。验证所选清单：

从实际安装的 Skill 目录运行以下命令。从项目目录调用时，使用捆绑脚本的绝对路径。

uv run --no-project python scripts/prior_work.py \
  --manifest <path> validate-manifest

CLI 的 --manifest 覆盖选项仅对该次调用生效。Hooks 使用宿主继承的 PRIOR_WORK_MANIFEST，若未设置则使用 ~/.config/daymade/prior-work/sources.json。CLI 操作和 hooks 必须遵循当前要求的必需来源约定及记录状态；只要该约定一致，清单路径可以不同，并且 hooks 能够读取要求和回执即可。

在子 shell 中执行 export 不会更改已运行的父宿主环境。请完成该宿主当前有效的约定。在 hooks 激活前，为未来的宿主绑定预期清单；不要在任务中途替换必需来源，以让回执通过。

将全局选项放在子命令之前。架构和载体示例见 references/source-manifest.md。

3. 跨已声明载体检索

将用户实际想要的结果与建议的实现方式分别写明。然后 提供：

• --outcome-term：1–5 个工件／事件／实体／日期术语，可用于查找 已完成的结果（已验收的交付物、规范的文字记录、已部署的服务、决策或运行 证据）。
• --term：1–8 个实现术语（代码符号、旧工作流名称、技术名词、故障现象）。

运行时会将业务结果查询发送到文档、会议、档案和对话；将实现查询发送到 代码和 Skill 载体。结果候选项优先按业务结果排序。因此，代码搜索 不能再代替检查所请求的结果是否已存在。不要只传入“做／优化／系统”等泛化动词。

uv run --no-project python scripts/prior_work.py retrieve \
  --business-outcome 'the observable result the user actually needs' \
  --outcome-term 'accepted artifact, entity, event, or date' \
  --query 'the implementation or workflow currently being considered' \
  --term 'distinctive entity' \
  --term 'old workflow name' \
  --term 'failure symptom' \
  --session-id "$CODEX_SESSION_ID"

不要重定向输出（> /tmp/run.txt）来保存：即使是只读路由命令，文件 重定向也会触发写入门禁，因此重定向的检索会被阻止，运行 JSON 也不会写入你指定的位置。让输出直接显示，并从记录中读取；持久化副本是清单中 state_dir 下的运行 JSON（最后一行会打印其 run_path）。

--session-id：仅用于 retrieve、complete 和 check；validate-manifest 不接受此参数。在 Codex 中使用 $CODEX_SESSION_ID。Claude Code 没有此类环境变量，因此应从先前工作的钩子消息中原样提取完整 ID （UserPromptSubmit 注入／PreToolUse 拒绝／Stop 阻止）。其旁边显示的回执文件名是该 ID 的 sha256，而不是 ID 本身；在猜测的 ID 下完成回执会写入一个 check 永远不会读取的文件，门禁也会继续拒绝。切勿用看起来像哈希的文件名代替 ID。

当某个通常可选的实时载体与请求相关时，明确将其设为必需项：--require-source live-wechat。必须记录该手动路由后，回执才能完成。

该命令使用 rg 搜索文件系统载体，调用明确声明的命令适配器（例如正式的 Claude 历史记录查找器），并显示实时微信等手动路由。内容搜索始终受已声明的 glob 限定；只有当结果／实现术语明确指向路径（文件名、路径或 ISO 日期）时，才会枚举完整路径。project_doc_max_bytes 这类符号不足以作为遍历工作区中所有文件名的理由。该命令会在清单的 state_dir 下写入不可变的运行 JSON，并返回其 run_id。

如果必需载体标记为 manual_required，请执行指定的 Skill 路由，并在完成前记录结果。搜索本地微信档案不能证明已覆盖实时微信；对话索引不能证明已覆盖会议或代码。

4. 在权威来源处核实候选项

如果请求是找回已部署的产物，首先要确认指定的系统以及所需的状态（历史版本、特定时间使用的版本或当前部署）。相关设计文档只是候选项，并非找回的文件。选择名称相似的实验项之前，应先遵循项目的产物／部署负责人所指引的来源。如果可以获取运行时证据，就应在交付前获取；仅添加“未经核实”的免责声明并不能完成查找。如果用户明确要求历史草稿，则应返回该版本，不要强行要求进行在线核查。

如果用户明确要求重用过去成功的方法——例如询问过去如何成功完成某事，或希望再次采用已验证的方法——那么导航文档、目录条目或索引命中都只是定位线索。应继续查找实际可操作的方法（执行过的步骤或命令）以及当时记录的结果：成功、失败或未确认。只有同时打开两者后，才能将候选项认定为历史成功案例，并在现有的采用理由中记录该方法、记录的结果，以及它对当前环境的适用性差异（工具、版本、账户、数据形态）。如果无法重新读取旧结果（日志已丢失、记录已过期），应将历史成功报告为未经核实，而不是声称其成功；如果存在目前可核实且已授权的标准操作流程（SOP），则应继续采用它：无法读取旧日志并非硬性阻碍。普通代码重用、当前状态检查以及仅仅定位入口点，都不需要成功证据。

在候选项的原始路径中打开有希望的项。检查：

• 匹配度：它解决的是相同的业务问题，还是仅仅出现了相同的字词？
• 权威性：当前实现／SSOT 优先于历史提案；原始对话记录只能证明当时说过什么，不能证明其仍然正确。
• 时效性：比较当前 Git HEAD、文件修改时间、决策日期以及任何已取代标记。不要用存档覆盖当前行为。
• 结果证据：优先采用代码／测试／已验收的交付物和运行结果，而不是仅仅看起来流程完整的过程。

批量排除命中项本身就是一种断言。 当某个载体返回许多匹配项，而你判断它们全都无关时——例如“文档里只是引用了这个术语”或“这是无关模块”——这个判断就是你即将报告的发现，而不是你在筛选出一个目标时顺手做的步骤。对你要排除的每种不同类型，至少打开一个命中项，并在回执中说明排除了哪些类型，以及依据是什么。如果一个返回 47 个匹配项的载体对答案毫无贡献，那么它与一个没有返回任何结果的载体所提供的信息相同，也应像对待其他任何负面结果一样保持审慎：产生结果的运行可能没有问题，但你对结果的解读可能有误。

5. 完成重用回执

如果存档请求中包含实际文件读取，首先使用 verify_artifact.py，将选定的交付物与其关联的工具结果进行比较，而不是与附近的参考文件进行比较：

uv run --no-project python scripts/verify_artifact.py \
  --candidate /tmp/agent-backup.zip --member skills/editor/SKILL.md \
  --archive /tmp/request.json.gz --read-path /agent/skills/editor/SKILL.md

检查器接受包含 request_id、带时区的 timestamp，以及采用 Anthropic 工具调用格式的 request.body.messages 的 JSON/gzip 归档。对于普通文件，省略 --member。退出码 0 表示候选内容的字节出现在记录时间的一次成功关联 read 中——对于原始字节读取器（read/read_file），必须逐字节完全一致；对于 Claude Code 的 Read，则必须是带行号的结果，且绝对行号能够证明覆盖整个文件并重建文件内容（部分 offset/limit 读取永远无法通过；JSON 的 match_basis 会说明通过了哪种证明，rejected_read_reconstructions 会统计未满足覆盖前提的带行号读取）。1 表示没有匹配的证明；2 表示证据无效或有歧义。提及路径、失败的读取以及相关旧文件都无法通过。其他证据格式仍由特定来源的读取器支持；不要将不受支持的格式转换为否定结论。

归档必须来自经过验证的系统所对应的特定来源读取器或可观测性工具。此检查无法验证归档的真实性，无法判定用户指的是哪个系统，也无法确认当前部署情况。它也无法证明已恢复所有依赖项。交接时请保留这些区别。检索制品时，请在采用理由中记录选定的制品／成员及其匹配证据。仅涉及定位文档的收据，无法证明最终制品正确；对于要求成功方法的请求，也无法证明定位到的方法确实成功。

对你实际检查过的项目进行分类：

uv run --no-project python scripts/prior_work.py complete \
  --run <run_id> \
  --reuse '<candidate_id>=reuse unchanged because ...' \
  --adapt '<candidate_id>=adapt boundary X because ...' \
  --session-id "$CODEX_SESSION_ID"

如果没有符合条件的项目，请使用 --no-reuse-reason 并说明经验证的不匹配之处。“没有命中”不是理由；它只是检索结果，可能需要扩大检索词范围或解决失败的载体。也不能通过换种说法，将必需载体返回零候选报告为“没有”。请检查索引提供方的覆盖范围和新鲜度，调整索引检索词，并报告剩余缺口。不要对未建立索引的完整历史记录执行标签普查。

必须检查返回的结果。 当载体返回 result_count > 0，同时 terms_passed: false 时，请在撰写收据前展开这些排序结果。请依据命令来源契约解读该适配器字段，不要将其视为字面匹配、排序置信度或相关性判断。阅读这些结果后再撰写收据。

此要求关乎收据必须能够证明什么。no_reuse_reason 必须指出具体结果，并说明每个结果为何无法解决当前任务——“我读了这三项，它们涉及的是不同系统”是理由；如果载体返回了十二条结果，却没有人打开过，那么“没有用户讨论这件事的记录”就不是理由。请将此要求与上文的零候选条款一并理解：前者适用于载体未返回任何结果的情况，后者适用于载体已返回结果、但你尚未取得排除这些结果的依据的情况。两种情况都必须妥善处理，否则未打开的结果批次就会被悄然当成不存在的证据。 已完成的收据会保留 business_outcome 和 outcome_terms；check 会拒绝缺少任一字段的旧收据或手动构建的收据。收据的新鲜度绑定于必需 载体的定义。编辑可选载体不会使已验证的必需覆盖失效；更改必需根目录、 路由、模式、权限或限制则会使其失效。完整清单哈希仍作为来源记录保留。 在 retrieve 和 complete 之间，必需的 Git 支持文件系统来源，以及已作出 复用／改编／拒绝决定的可选来源，都会保留其搜索范围和所选文件字节。如果 这些输入一致，无关提交或纯变基无需重新检索。来源的包含／排除范围内发生 更改（包括新增、删除或未选中的候选项）、工作文件或忽略规则依赖项发生变化， 都需要再次搜索。CLI 使用 ripgrep 的 glob 规则检查此范围；旧版运行仍保留更严格的 HEAD 和 mtime 检查。非 Git 和命令适配器不会获得 Git 范围证明。 此比较用于完成原始检索；它不会持续刷新已完成的收据，也不会豁免新的用户要求。 Gitlink 更改不符合此狭义重新绑定证明的条件。 如果完成操作报告来源证据或范围发生变化，请针对当前要求重新检索，检查受影响的 结果，并完成新一轮运行。 不要编辑已保存的运行记录或旧收据，让过时证据通过检查。 然后验证：

uv run --no-project python scripts/prior_work.py check \
  --session-id "$CODEX_SESSION_ID"

只有通过此检查后，才能开始实质性的生产工作。在实现／计划中引用已采纳的 候选项 ID，让收据与结果关联，而不是沦为形式主义的文书工作。

check 接受收据，表示验证本次会话搜索过的来源、分类过的候选项和声明契约。 这并不能证明已采纳候选项在业务上取得成功，也不能证明定位器的目标确实已读取； 这些仍属于上述验证职责。

配套钩子

清单有效且自测试通过后再安装：

scripts/prior-work-retrieval.sh --selftest
scripts/prior-work-retrieval.sh --install

版本化包装器是钩子运行时的同步 SSOT。它会解析一个直接的 Python 解释器， 绝不会进入包管理器／缓存生命周期；请将上面的 uv run ... prior_work.py 命令保留为明确的检索和收据操作，而不要将其用作钩子启动器。

安装程序会将必需的处理程序添加到 Claude 和 Codex，而不替换无关钩子：

• UserPromptSubmit 只有在用户明确表达了复用先前工作或查阅历史记录的意图时，才会创建仅限当前提示词的要求，并注入 Skill 路由。过滤器可避免在用户未提出要求的情况下触发：
  • 不是用户发言。 内部模板（You are a/an …、# Overview）、执行框架信封（<agent-message …>、<task-notification …>、<system-reminder …>）和粘贴的对话记录行（⏺ …）都会作为提示词传递给此处理程序。它们绝不会启用要求。
  • 执行器无法满足门槛。 如果提示词禁止读取技能或运行 shell，就等于移除了完成收据所需的能力；此时启用门槛会阻塞工作，且没有解除阻塞的途径。如果提示词明确表示不进行先前工作检索，也会按人们实际使用的说法处理（Do NOT perform prior-work retrieval、opts out of prior-work retrieval），而不只是识别 skip/disable。
  • 否定复用。 “不要复用 X”、“别沿用”和 don't reuse 表示不采用先前工作；将某事描述为很久以前的内容（“很久之前写的”）说明它可能已过时，而不是要求查找。匹配前会排除这两类内容，因此同一句中真正的查找请求仍会被计入；而“别重复造轮子”／“不希望你重新造”表达的是要求复用，仍会启用门槛。
  • 模糊回忆需要指向远处的对象。 “上次”／“好像是”／“我记得是”／“记不清”只有与带有远指或不定指限定词的工作名词同时出现时（“那个／某个／哪个脚本”），才会启用门槛，因为“这个脚本”指的是眼前的对象——“这个脚本好像是死循环”是错误报告，而不是回忆。单独出现 history 也需要搭配限定词（conversation history，而不是 git history）。
  • 有效收据已覆盖本次会话。 使用模糊措辞的回忆请求不再创建新的要求，以免让已完成的收据失效；明确提出的新先前工作请求仍会创建要求。
  • 当前执行的连续性。 “沿用当前 child”、继续当前会话、工作目录或只读范围等指令，不代表请求检索历史记录。仅排除由执行对象组成的完整列表；如果同一列表还提到了历史资料，则保留“沿用”。提示词其他位置的历史复用请求仍会被计入。

运行 scripts/prior_work.py audit，检查门槛是否正常工作：该命令会报告触发条件分布、空门槛率（已启用但从未生成收据的要求——这表明门槛可能阻塞了无法满足要求的任务）、悬置的收据、非用户输入触发的要求，以及每个仍会触发的条目所匹配的令牌。添加 --json 可输出机器可读格式。应根据这些数据而非测试是否通过来评估门槛。

• PreToolUse 仅在明确的要求尚未完成强制执行且缺少有效收据时，才会阻止实质性写入操作。它绝不会将普通写入操作变成检索义务。要求生效期间，仍可进行只读探索和小型机械编辑。
• Stop 会验证尚未完成强制执行的明确要求。它绝不会根据输出长度、代码、工具使用情况或笼统的生产请求凭空创建要求。验证成功后，本批次的强制执行范围即告结束，但会保留收据；之后明确提出检索请求时，将创建新的要求。在此之前，普通的后续请求和继续执行的措辞不会自动清除要求；如需明确解除，请使用现有的用户退出机制。

如果当前执行连续性错误地启用了要求，操作员可以在部署经过审核的分类器修正后，重放其原始事件。请通过执行负责人确认，目标范围内没有提示词编写器处于活动状态。将 REQUIREMENT_ID 设为原始的精确 ID，并将 ORIGINAL_EVENT_JSON 设为保留的原始 UserPromptSubmit 事件，然后运行：

scripts/prior-work-retrieval.sh --reclassify-requirement "$REQUIREMENT_ID" < "$ORIGINAL_EVENT_JSON"

此维护模式要求原始会话、完整提示词哈希、需求 ID 和清单都与存储的必需状态一致。它只接受当前执行中的误报情形。它会撤销强制执行并记录更正，同时保留原始需求；既不会创建退出状态，也不会创建回执。身份信息缺失或发生变化时，操作会失败且不改变状态。普通的后续操作（包括普通重放该提示词）绝不会调用此更正。

此模式会将范围更窄、未版本化的 recall-first-evidence UserPromptSubmit 处理程序迁移到此超集，同时将其脚本保留在磁盘上以便恢复。旧触发语族（“我们之前”“什么来着”、模糊记忆）是回归测试。安装后运行此机器的 profile-settings 同步器，以便每个 Claude 配置文件都获得主设置。Codex 需要通过 /hooks 进行一次人工信任审核；安装程序绝不会伪造审核。

用户可以明确表示，不要为当前提示词搜索之前的工作。此退出选择会成为针对提示词的状态，而不是通过环境变量绕过限制。识别到的说法必须在同一句中同时包含拒绝动词（不用/不要/不需要/跳过，或 skip/disable/opt out/do not perform）和检索名词（查历史/历史检索/prior-work/prior work/history retrieval）——单独说「不需要检索」不符合条件，因此在门控期间向用户提供建议时，请引用完整可用的说法，例如「本任务不需要 prior work 检索」。 清单或回执状态格式错误或缺失时，只有在进行实质性生产操作时才会采取失败关闭策略；只读调查以及目标路径恰好为清单路径的写入仍然允许，以便 Agent 修复门控而不绕过它。

搜索路由

需求	路由
项目代码/文档中的已知精确字符串、符号或路径	文件系统载体（rg），范围限于该项目；不要递归搜索对话存储
记得含义，但措辞已改变	使用声明的语义适配器（gbrain 或索引化历史回溯），并先检查提供方范围和新鲜度
记得含义，且平台可能是 Codex	如果索引涵盖 Codex，则使用 history_index.py recall --provider codex；否则报告这一缺口
之前 Claude 工具调用/思考/文件历史的精确证据	先查找索引候选项，再读取精确会话；如果无法在不扫描原始语料的情况下选出候选项，则报告未知
之前的对话证据，但平台未知、涉及多个平台，或不是 Claude	local-conversation-history；每个提供方都是独立存储，因此仅基于 Claude 的回答不足以证明“我们从未讨论过”
会议决策或发言者主张	项目转录载体；打开对应发言者的原始发言
归档的微信文本/语音转录	声明的微信归档载体
实时/最新微信内容	read-wechat-messages；记录人工覆盖情况
当前代码行为	在当前 Git 修订版本中打开实现/测试
工作目标是远程机器或外部检出（部署目录、上游 fork）	优先查看该仓库自己的 docs/、Makefile、部署 README——它们不是清单载体，因此要记录为人工覆盖；绝不要重新构造机器上已有文档说明的构建/部署命令

边界

• 清单是显式的，且与可变索引状态分开进行版本控制。
• 搜索结果是待验证的假设。回执记录验证结果和复用情况。
• 不要将私有项目数据复制到公开示例或 Skill 夹具中。
• 必需载体失败时，不要悄悄回退；应记录这一缺口。
• 除非用户明确要求查询当前外部事实，或本地证据无法作答，否则应先搜索本地既往工作，再开展外部网络研究。
• 此 Skill 就是工作流。配套钩子可能要求在 Write/Edit 之前生成新的回执；Stop 可以强制执行同一项既有义务，但最终答复的形式不能创建新的义务。钩子不会判断哪个候选项合适。

表层约定

在会话中首次使用时：运行一次 python3 scripts/surface_version.py，并记录指纹——该技能 scripts/**/*.py 代码表层的 sha256。如果它与上次看到的该技能指纹不同，说明代码在你使用期间发生了变化：在依据上下文中对这些内容的回显采取行动之前，先从磁盘重新阅读此 SKILL.md 和相关参考资料。指纹仅涵盖代码；文档编辑不会改变它。

维护者验证

uv run --no-project python -m unittest discover -s tests -p 'test_*.py'
uv run --no-project python scripts/prior_work.py \
  --manifest tests/fixtures/manifest.json validate-manifest
scripts/prior-work-retrieval.sh --selftest

回归用例必须涵盖真实的故障类型：未加载跨项目规则、忽略现有提供方契约、旧决策凌驾于 North Star 之上、声明不存在的制品能力、遗漏相邻 Agent 的证据，以及全局“已搜索”声明掩盖会话／会议／微信载体缺口。