stow

stow

梳理这段对话，找出目前仅存在于聊天中的持久知识，并按照用户的明确指示、项目现有的本地惯例，或当前目录中的私有 .stow-notes.md 备用方案，将其归档。 目标是为下一次会话留下简洁、最新的操作指南，而不是不断累积的日志：每条持久发现都要落盘，每个被此技能修改的文件都应变得更准确，而不只是更长。 条目分级存放，并在每轮整理后逐渐淡化；过时内容应转移到本地归档，而不是删除。 默认将所有内容存入本地；只有通过第 3 步中的明确指示规则，才会访问问题跟踪系统等外部系统。

功能

1. 梳理对话，找出尚未记录的持久知识。 回顾本次会话，留意以下内容：

   • 用户偏好：用户顺带提及、而非通过配置文件明确说明的工作方式、工具、格式或审批偏好。
   • 项目事实：当前项目的构建、测试、部署、架构或惯例信息，能帮助日后在此项目中工作的任何人（或 Agent）。
   • 操作注意事项：工作中发现的易错点、变通方法、常见错误或不明显的原因。
   • 持续有效的决策：本次会话中应长期保留的选择，例如已确定的方案、已排除的选项或达成一致的惯例。
   • 未完成的后续事项：尚未处理、且此前未记录在任何地方的待办事项或已约定事项。 在归档任何发现之前，先检查它是否已权威地记录在其他地方，例如 README、配置文件、现有文档或代码本身。 如果已记录，应写下一行指向其权威来源，而不是复制内容，以免归档笔记脱离来源而过时。

2. 先了解宿主环境的现有惯例，再决定内容存放位置。 不要预设存放位置——应按大致顺序查找实际存在的文件：

   • 项目级记忆文件，例如仓库根目录或附近的 CLAUDE.md、AGENTS.md 或同类文件。
   • 运行中的 Agent 会跨项目读取的用户级（全局）记忆文件（如果存在且可读）。
   • 项目中已受版本控制的 TODO、BACKLOG、NOTES 或类似名称的纯文本文件。 此步骤仅涉及本地文件；不要在此处查找或推断问题跟踪系统，外部路由由第 3 步负责。

3. 按此固定优先顺序处理每条发现，优先使用本地位置。

   1. 最高优先级——明确指示优先。 如果用户在本次对话中较早时候明确表示，或在已发现的用户级记忆文件中记录了长期选择（见第 4 步），要求将此类发现写入特定系统，则写入该系统。 这是唯一可以使用外部或公共系统（例如问题跟踪器、托管项目看板或工单系统）的途径。 已配置的 Git 托管平台远程仓库、.github/.gitlab 文件夹，或任何其他表明可能存在跟踪器的信号，都不能单独作为在其中提交内容的依据——绝不能根据推断将内容写入外部系统。
   2. 否则——采用项目或用户已有的本地惯例。 项目事实、操作注意事项和长期决定写入已发现的项目记忆文件；未完成的后续事项写入现有的 TODO/BACKLOG/NOTES 文件；用户偏好写入已发现的用户级记忆文件（如果恰好可以访问）——这是额外选项，绝不应假定其存在或将其视为必需。 只有这一优先级会将发现写入受版本控制的共享文件或当前目录之外的位置，而且仅限用户已经设定了该目标位置的情况。
   3. 回退方案——将所有类型的发现写入当前目录下的 .stow-notes.md。 如果没有适用的现有惯例，不要自行选择位置，也不要临时编造文件名。 在 Git 工作树中，先确认 .stow-notes.md 尚未被纳入索引跟踪；如果已被跟踪，则不要在其中写入私密发现——应告知用户，在用户选择安全位置之前，无法使用此回退方案。 否则，在当前工作目录中创建或更新 .stow-notes.md——绝不能使用用户级或主目录路径，这样即使 Agent 只能访问当前目录中的沙箱，此回退方案也能正常使用。 然后确保该文件不被 Git 跟踪：在当前目录的 .gitignore 文件中添加一行 .stow-notes.md。该文件必须是此路径下的普通文件，而非 Git 内部的排除机制；在关联工作树中，后者可能指向工作目录之外。 将此 .gitignore 行暂存或提交的工作留给用户处理，与此技能所写的其他内容一样。 如果写入 .gitignore 失败，不要因此受阻或报错——仍然写入 .stow-notes.md，并告知用户需要手动将其加入忽略列表。

4. 如果两个现有惯例之间确实存在歧义，只询问一次，然后记住答案。 如果发现的多个本地惯例都可能适用于某条发现，请向用户明确询问，今后这类备注应存放在哪里。 如果用户明确要求今后将内容写入跟踪器或其他非本地系统，而非仅针对某个事项，也应如此处理。 用户回答后，主动提出记住这一选择：获得用户明确许可后，在已发现的（或新商定的）用户级记忆文件中记录一条简短的长期说明，这样在此项目中就不必重复询问。 添加该说明前务必先询问——绝不能悄悄设定惯例。 如果完全没有适用的现有惯例（而非仅存在歧义），应采用第 3 步的回退方案，不要提问。

5. 只写入已作为实际约定存在的位置、第 3 步的备用位置（以及其中的 .gitignore 行），或用户在第 4 步刚刚批准的目标位置。 不要臆造项目中尚不存在的新共享文件、新文件夹或新跟踪类别。 绝不要将技能存储、创建或编辑为发现事项的目标位置：不存在“将其升级为技能”这一步，即使仓库中现有的 .claude/skills/ 或 skills/ 目录看起来像是一种约定。 第 7 步中的卸载出口不会改变这一点：此技能只会提出这类迁移，而按需加载的存放位置由用户通过自己的变更流程创建，绝不会通过此技能的写入创建。 如果备用位置不可写，且用户不想建立新约定，就明确说明，并让该发现事项保持未归档状态，而不是编造一个目标位置。

6. 写入前先读取目标文件：先检查再更新，绝不盲目追加。 写入任何发现事项之前，完整读取目标文件的当前内容；对于 TODO/BACKLOG/NOTES 条目，要读取完整的现有条目，而不只是标题。 然后根据已有内容对发现事项分类：新增、重复、取代现有条目，或表明现有条目已过时的证据。 按分类所要求的方式写入经过审慎处理的替代内容——重复内容应合并到已有相关条目中；取代旧内容的发现事项应改写被取代的条目；过时条目则应在同一轮中更新、归档或替换，并保留其事实——而不是盲目追加新条目或整体覆盖文件。 优先用一句话改写现有条目，而不是另加一条几乎相同的内容。 被取代且值得保留的正文应通过第 7 步中的某个出口移出，以便仍可恢复，而不是在改写中悄然丢失。 按下方的层级约定，为写入记忆文件或 .stow-notes.md 的每个条目标注层级，但绝不要向现有的 TODO/BACKLOG/NOTES 文件添加层级标记。 记录每个尚未完成的后续步骤，并在确实受阻时注明它在等待什么。

7. 整理本轮打开的每个记忆文件，而不只是发现事项要写入的那个文件。 根据下方层级约定中的时间周期，评估每个带日期的条目；用当前证据重新验证仍有效的内容，并归档持续过时的内容。 归档已不再适用的内容，包括已完成的历史记录、过时的版本和路径、临时任务状态、已解决的备选方案、旧指标以及篇幅较大的流程。仅在被取代的主张和重复内容的事实已在其他位置保留时，才合并或删除它们。 优先保留一条简洁、当前有效的规则，或指向权威来源的链接，而不是重复的描述。 绝不要直接移除独有且当前有效的事实：必须将其归档到可恢复的冷存储层，或迁移到实时按需加载的存放位置，或通过保留该事实的合并整合来保存。 这是一项准确性要求，而非篇幅目标——过时条目会误导下一次会话；当前有效的条目才值得保留。 .stow-notes.md 中的记录只有以下五种处理方式：提升到用户批准的共享跟踪文件中；合并到发现的用户级记忆文件中；归档到本地且永不加载的归档文件中；经用户批准迁移到按需加载的存放位置（技能或作用域指令文件），并通过用户自己的变更流程执行，而不是由此技能执行；或删除已由更具权威性的来源保留的重复内容——不要另行发明处理方式。

8. 以诚实的安全结束判定和下次会话的恢复指引收尾。 对本轮检查中处理或考虑过的每个文件报告一项操作：unchanged（未更改）、added（已添加）、rewritten（已重写）、pruned（已删减）、archived（已移至本地归档），或 routed（已将发现交给其他负责人）。 点明任何仍待用户批准、拟移入按需存储位置的内容，避免让人误以为已完成。 然后用通俗语言告诉用户：记录了什么、记录在哪里、哪些内容无法记录（以及原因），以及现在是否可以安全地结束或重置对话——也就是说，本轮检查中的每项持久发现是否都已保存到磁盘或明确指定的跟踪工具中，而不是仅留在此聊天里。 如果有内容尚未记录，必须明确说明，不要声称会话已完全安全。 如果有内容写入 .stow-notes.md，请说明这一点——注明它是私有的，仅限本项目使用，并指出如果用户希望更广泛地展示这些内容，可通过步骤 7 中的晋升出口进行处理。 在 git 仓库中，按实际情况说明忽略保护：要么说明已添加 .gitignore 行，等待用户自行提交；要么说明写入失败，用户必须手动忽略 .stow-notes.md，之后才能依赖 git 将其隐藏。 如果因为 .stow-notes.md 已被跟踪而无法写入备用位置，请说明没有写入私有备用副本，并且在用户选择其他存放位置或接受该文件受跟踪之前，会话还不能完全安全地重置。 如果由于未发现用户级记忆文件，用户偏好被写入 .stow-notes.md，请补充一个注意事项：该偏好现在仅适用于本项目；如果用户希望它在不同项目间生效，必须自行将其复制到自己的全局记忆文件中。 收纳的真正价值不在于本次会话，而在于下一次：最后附上一条简短、可直接复制粘贴的 RESUME POINTER，准确列出新会话需要加载哪些文件，才能从头继续，例如 To pick this back up in a new session, load: CLAUDE.md (project conventions), .stow-notes.md (private notes, not shared)。 仅列出本轮检查实际写入或更新的文件；如果没有写入任何内容，则省略此指引。

分层且随时间衰减的条目

标记采用简洁的尾随 HTML 注释，刻意保持精简，因为标记字节也会计入此技能所维护的每个文件的篇幅：

• `` - aging 条目；嵌入的日期是其最后一次强化的日期。
• `` - perishable 条目；嵌入的日期是其最后一次强化的日期。
• `` - 仅适用于文件头指针明确启用下方检查周期的文件：任一带日期的标记都可以包含 /N，表示有多少轮检查评估过该条目，却未对其进行强化。 省略 /N 表示计数为零，因此持续验证的条目无需占用计数器字节；未启用该机制的文件绝不会写入此计数。
• `` - 在默认层级不是 pinned 的文件中，明确标记为 pinned 的条目。
• `` - 仅用于迁移：未确认的旧条目已用完一次宽限周期；不带日期，因为宽限不算强化。

- The staging deploy needs the VPN profile active or the smoke test hangs. 
- CI is red on the flaky auth test until the pinned runner image updates (tracked in TODO). 
- Always run the schema linter before touching migrations. 
- The staging seed script must run before the fixture import. 

层级名称说明了此技能如何处理条目：

• pinned - 永不衰减，也不会为了缩短文件而删除；只有用户或实际情况发生变化时才会修改。
• aging - 必须重新证明其有效性：自上次强化日期起年龄大于或等于 30 天的条目即为过期；过期条目必须重新验证（刷新日期）或归档，绝不能仅凭惯性保留。
• perishable - 写入时就预备将其丢弃：自上次强化日期起年龄大于或等于 7 天的条目即为过期，其文本必须指出可核查的失效条件，例如工单、版本或有日期的预期。 无法指出可核查条件的条目属于 aging，而非 perishable。

规则：

• 除非文件自身的头部指针指定了不同的默认值，否则，用户级记忆文件默认使用 pinned，而项目记忆文件和 .stow-notes.md 默认使用 aging。
• 与文件的 pinned 默认值相符的条目不带任何标记；每个 aging 和 perishable 条目始终带有注明日期的标记，其字母表示所属层级，因此，带时钟的条目绝不会与未标记的旧内容混淆。
• 标记和指针的字节数计入文件成本，因此记账从设计上就保持精简。
• 本技能整理的每个受管理记忆文件最多带有一行头部指针，用于将本技能标明为方案所有者，例如 ；如果该文件采用不同的默认层级，可选择注明该层级；如果该文件选择启用轮次期限，也可选择注明该期限，例如 。 层级语义、标记写法和时钟仅定义于本技能中，绝不在文件头部重述；头部只注明选项，不注明其数值。 一次性迁移时，即使默认使用 pinned 且只包含未标记条目，也要添加指针，让每个受管理文件都标明其方案所有者。
• 只有在当前会话中有实际证据时，才更新条目的最近强化日期：该事实已被使用、确认或重新推导。 文件中仅仅存在某条目不算证据，重新阅读记忆也绝不算强化。
• 上述日期是默认且唯一的时钟；除非文件头部指针选择启用轮次期限，否则文件只能使用这些日期。 只有在某个文件的整理频率足够高、以至于日期时钟从不触发时，才为该文件启用此选项：每轮接纳发现都是一次事件，因此你不断使用的条目不会有连续 30 个自然日未经强化，而文件只会不断增长；而低频整理的项目在一轮整理间隔内就已超过日期期限，启用轮次期限没有任何收益。 绝不要主动启用此选项；由用户逐个文件决定。
• 文件启用此选项期间，其中的 aging 条目在以下两者中先到者出现时即为过时：经过 10 轮评估但未强化，或 30 天；perishable 条目则在以下两者中先到者出现时即为过时：经过 3 轮未强化，或 7 天。 判断是否过时之前，先递增该轮中未强化的每个带日期条目的计数器；没有 /N 的带日期标记视为计数为零，无需迁移；只有基于实际证据刷新日期，才能清零计数器。 未启用此选项的文件中，绝不写入计数器，也绝不读取已有计数器；按字节原样保留任何现有的 /N，不要规范化或移除。
• 根据 perishable 条目指定的条件重新确认过时条目：若条件仍未解决，则刷新日期；若已解决、已过期或无法再核查，则立即归档。
• 仅在本技能运行时评估衰减；轮次之间不会发生任何变化，因此，低频整理的项目按其整理间隔经历时钟变化。
• 过时不意味着删除：过时条目会从源文件移至其所在目录中的 .stow-archive.md，且不会被任何会话加载；归档记录包括源文件名、层级、存在时的强化日期，以及一行原因。 仅当轮次期限本身导致条目过时，才包含未强化轮次数；使用精确原因 unreinforced <N>p。若由自然日期限或任何其他原因触发归档，即使活动标记带有计数器，也要省略该计数器。 在 git 工作树中，写入任何归档事实之前，先确认该归档路径未在索引中被跟踪。 如果该路径已被跟踪，则不要写入，并告知用户在选择安全目的地之前无法归档。 否则，在归档目录中的 .gitignore 文件里添加一行 .stow-archive.md，且绝不将归档事实写入 git 跟踪的文件。 恢复方式是搜索并复制回来。
• 预先存在的未标记条目属于文件的默认层级，且年龄未知；年龄未知不等于有问题：默认层级为 pinned 的文件中，未标记条目就是 pinned，不受老化时钟、旧条目宽限周期和按年龄归档规则约束，但仍需整理合并。
• 在默认层级带有时钟的文件中，首次运行时，为能够确认的每个未标记条目添加精简的日期标记；否则添加 ``，该标记不含日期，用于保留一个宽限周期，且不会将条目的存在视为强化。 下一轮运行时，若有当前证据，则将该标记替换为常规的带日期层级标记；若无此类证据，则连同 legacy-unvalidated 注记归档该条目。 后续手动编辑若使默认层级带有时钟的文件中的某个条目再次变为未标记，也适用同样的持久化转换流程。
• 当始终加载的记忆文件增长到超出每个会话都应承担的范围时，本技能可以提议——但绝不执行——将某条耐久且只在可明确指出的情境下才重要的条目，移至按需加载的位置，例如某个技能文件，或用户的 Agent 仅在相关情境出现时才会加载的作用域指令文件。 每次移动都须经用户批准；新位置由用户通过自己的更改流程创建，而非由本技能创建；只有在新位置存在后，才从记忆文件中移除该条目。 在按需位置可用之前，此流程绝不会移除或归档任何当前独有的事实。

此技能不会做什么

它不会另行创建笔记系统、初始化版本控制，也不会代替用户暂存、提交或推送任何内容——所有写入内容，包括 .gitignore 中的那一行，都会保留在工作树中，供用户像审查和提交其他更改一样进行审查和提交。 它绝不会记录凭据、机密或其他敏感材料——只会记录无论保存在哪里都适合以纯文本形式保存的知识。 它绝不会仅凭自身推断就将任何内容提交到问题跟踪器、托管看板或其他外部或公开系统——只有在用户明确指示后才会这样做，并遵守步骤 3 中的硬性规则。