知识捕获
自动使用
在任何仓库任务的最终响应之前,如果文件已更改、测试已运行、或做出了决策/发现/后续行动,请为当前会话/工作流创建或更新唯一一个活跃的 session 捕获。此操作应在验证完成后、请求清理积压或批准之前进行。
不要仅仅因为技能被再次调用就创建全新的捕获。如果当前工作流的活跃捕获路径已知,请更新该文件。否则,读取 .ai/raw/active-session.json 作为候选活跃指针。如果没有可靠的活跃捕获存在,或者工作流明显已改变,则创建新的原始捕获并替换指针。
捕获足够的当前任务细节供后续使用。仅读取/更新当前工作流的活跃捕获;在 v0.2 版本中,不要读取、更新、去重、合并、同步、提交、发布或推广不相关的捕获。
仅因为助手写了一个文件并不意味着捕获已完成。不要在其已知事实的部分(特别是“用户请求”、“变更和证据”、“决策和发现”、“开放问题和后续步骤”)中留下“未捕获”。
更新活跃捕获时,应写入在当前工作流步骤之后捕获应呈现的完整内容。不要仅添加增量说明。使用当前任务上下文、可见文件、差异、测试、命令结果和交接文本作为证据;如果连续性不明确,请创建新捕获,而不是凭空捏造丢失的上下文。
保持捕获与当前事实对齐,而不是与每一个中间想法对齐。如果先前的决策已更改,且工作也随之更改,请捕获最终/当前的决策和证据。仅当被取代的决策能解释已实现的代码、回滚、未解决的风险或开放问题时,才保留该决策;省略纯粹理论上的、已被放弃的方案。
将捕获存储为 .ai/raw/<类型文件夹>/YYYY-MM-DDTHH-mm-ssZ--<类型>--<主题slug>.md。如果确切的文件名已存在,则在 .md 前追加 --2、--3 等。
类型:session -> sessions, discussion -> discussions, investigation -> investigations, decision -> decisions, handoff -> handoffs。
对于 session 捕获,维护 .ai/raw/active-session.json 作为指向活跃工作流捕获的本地指针。不要在每次最终响应后清空它;它支持恢复、压缩和交接。当新的工作流捕获开始时,替换它。
捕获
将 /capture 视为创建/更新当前会话捕获。当 <type> 为 session、discussion、investigation、decision 或 handoff 时,将 /capture <type> 视为该类型的捕获。
在上下文压缩、压缩或交接之前,如果有意义的工作或决策尚未被捕获,请先进行捕获。
如果 Node 可用,无依赖的辅助脚本可以创建首个捕获,通过 --update <路径> 替换已知的活跃捕获,或通过 --update-active 替换指针指向的捕获。通过 --stdin 传递丰富的分节细节,或直接写入 Markdown。默认情况下,辅助脚本会阻止仅包含标题/摘要的捕获,因为这会丢失有用的会话知识。
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --summary "Fixed expired refresh token behavior" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update-active --stdin
在标准输入上提供来自 references/raw-capture-schema.md 的 Markdown 标题。如果 Node 或 Shell 执行不可用,则直接创建或更新 Markdown。
对于活跃会话捕获,请按以下顺序处理:
- 如果当前上下文中已知活跃路径,则更新该路径。
- 否则读取
.ai/raw/active-session.json作为候选指针。 - 如果指针和运行时都暴露了一个
agent_session_id并且它们匹配,则更新它。 - 如果会话 ID 不同、缺失或不可用,但用户请求或交接明确延续同一工作流,则更新它并刷新指针。
- 否则创建新捕获并替换指针。绝不要通过猜测最新文件名来选择。
安全边界
- 捕获有用的原始细节,但避免转录、大型日志和整个文件。
- 将更改的文件、测试、命令和证据放在“变更和证据”下;当多个文件更改时,按目的对文件进行分组。
- 仅包含罕见、非显而易见的或与决策相关的命令/结果;省略以后无关紧要的常规命令。
- 仅为了使其准确和有用而重新组织活跃捕获;不要捏造事实,或悄然保留过时的理论,仿佛它仍然正确。
- 将
agent_session_id视为一个有用的护栏,而不是工作流的定义。新的智能体会话可以继续相同的工作流。 - 仅当运行时明确暴露了稳定的当前会话、对话、线程或运行 ID 时,才使用
--agent-session-id。如果不可用,则省略它。绝不要凭空捏造一个。 - 排除秘密、凭证、API 密钥、私钥、客户私人数据和不相关的个人记忆。
- 如果存在敏感内容,不要创建捕获;先抽象地总结。
- 原始/本地状态来自
.ai/raw/路径和技能策略,而不是每个捕获的工作流字段。 - 将 Node 辅助脚本视为可选的。直接创建文件仍然是有效的。
保存后,报告路径、类型以及是创建还是更新。如果辅助脚本阻止了捕获,请报告警告并且不要保存原始内容。
参考
- 仅在手动编写或更改架构时读取
references/raw-capture-schema.md。 - 在不确定更新后的工作流捕获应该如何呈现时,读取
references/active-session-example.md。 - 仅在将该技能适配到其他智能体时,读取
references/agent-portability.md。