introspect 是做什么的?
将您在 AI 编码线程中发生的事情转变为对智能体工作方式的更改——这样您的设置会不断累积,而不是每次会话都重置。
它是与智能体无关的。它能读取来自 Claude Code、OpenAI Codex 和 Cursor 的线程,找出值得更改的少数几件事,并在获得您的批准后,将它们写回实际引导未来会话的智能体配置中。Claude Code 已经提供了 /insights,它会读取您过去 30 天的数据并向您展示一份报告。那是 Claude 独有的读取部分。Introspect 是写入部分,横跨您使用的所有智能体。Youssef 在其来源线程中说得好:一次性修复系统,这样你就不必修复输出一千次。
让这一切有效的核心理念:模式,而非策略
“我能做得更好的是什么?”的失败模式在于它会浮于表面策略——一个命令的更好标志,对一个 bug 的更巧妙方法。这些不会累积。它们明天就消失了。
真正能累积的是你反复养成的习惯:你在三个不同线程中给出的相同修正,你每周重复的相同偏好,你的智能体每次接触你的测试设置时都会犯的相同错误。因此,整个技能偏向于重复性:
一个候选变更只有在其出现超过一次、尚未在任何地方写下、并且本来可能改变结果时,才值得它的位置。其他一切都是噪音——记录下来,不要采取行动。
这也是对线程中人们提出的两个担忧的诚实回答:
- “我担心错误的决定会累积 / 我的工作流会变蠢。” → 未经你查看确切的差异并批准,不会写入任何内容。每个已应用的更改都会被记录且可逆。有疑问时,提议更少的东西。
- “它是不是每天都会永远更新这个技能——它会收敛吗?” → 它应该会收敛。如果一条规则已经存在,你会强化或合并它;不会添加第二条。安静的一天产生一个空的变更集,这算成功而非失败。
管道
收集 → 提取 → 与现有设置对比差异 → 提出变更集 → 批准 → 应用 + 记录
(脚本) (你) (你,读取当前配置) (你,附有证据) (用户) (你,可逆地)
1. 收集——运行脚本,无需手动重新解析任何内容
scripts/collect_threads.py 读取每个智能体的线程存储(Claude 的 JSONL、Codex 的 rollout 文件、Cursor 的 SQLite),过滤到指定时间窗口,脱敏处理机密信息,并输出一个统一的摘要:每个会话会标记是哪个智能体、用户的输入提示词、使用的工具、工具出错的地方,以及轻量级的“摩擦”信号(读起来像修正的提示词、多次连续调用的工具)。
python3 scripts/collect_threads.py --days 1 # 今天,自动检测所有已安装的智能体
python3 scripts/collect_threads.py --agent all --days 7 # 上一周,强制检测全部三个
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject # 特定项目
python3 scripts/collect_threads.py --selftest # 对全部三个解析器进行完整性检查
--agent 默认为 auto(自动检测哪些智能体已安装)。使用 --format md 以便您自己阅读;使用 --format json 以便进行后处理。脚本从不自行决定任何事——它为您提供干净、标准化的原始素材,这样您可以将判断力花在重要的事情上,而不是解析三种不同的对话记录格式。
2. 提取——阅读摘要并提取出三类内容
像您自己是用户的首席幕僚在审查当天所有工具中的工作情况一样阅读摘要。用户的偏好是第一位的——这个技能主要是为了了解他们喜欢如何工作,而不是为了管教智能体的基线行为。区分:
- 持久性偏好(主要事件)——用户修正默认行为或重述他们偏好的方式(“不,用 pnpm”、“停止添加注释”、“始终先从 development 分支切出一个分支”、“不要碰工作树”)。一个在您的 Claude 和 Codex 线程中都出现的偏好是特别强的信号——这关乎您,而不是工具。
- 导致智能体重复工作的设置缺口——智能体在多次会话中重新推导或卡住的地方,因为某些东西没有被写下来:重新学习构建命令、重新查找始终位于同一位置的文件、缺少项目上下文的某一部分。解决办法是将缺失的内容写入用户的配置——而不是添加一条责备智能体的规则。如果重复仅仅是泛泛的智能体行为,没有用户特定的修复方法(例如“编辑文件前先读取它”),那不是规则,而是噪音;把它排除在外。
- 可复用工作流——用户不止一次驱动的多步骤操作,值得成为一个技能或命令,这样下次就只需要一步。
对于每个候选者,写下证据:哪个智能体、哪些会话、多少次、一句简短引用。没有重复出现的证据 → 就是策略,不是模式 → 舍弃。
3. 与现有设置对比差异——防止膨胀/收敛步骤
在提议任何更改之前,先读取相关智能体已有的配置,这样你就能强化系统而非臃肿它。references/routing.md 有每个智能体的读写位置和格式的详细信息;简短版本:
| 智能体 | 要读取(以及稍后写入)的现有配置 |
|---|---|
| Claude | ~/.claude/CLAUDE.md(全局)、./CLAUDE.md、项目级记忆 ~/.claude/projects/<dir>/memory/、~/.claude/skills/、~/.claude/commands/ |
| Codex | ~/.codex/AGENTS.md(全局)、<repo>/AGENTS.md(项目)、~/.agents/skills/ 中的技能 |
| Cursor | .cursor/rules/*.mdc(项目)、旧版 .cursorrules、AGENTS.md |
对每个候选者问:这个是否已经涵盖? 如果是 → 舍弃它,或者提出一个强化现有规则的小编辑。永远不要添加第二条几乎说同一件事的规则。如果两个候选者重叠,合并它们。优先编辑而非添加。
跨智能体提示: AGENTS.md 会被 Codex 和 Cursor 读取,并且很多人将其符号链接到 CLAUDE.md。如果一个偏好是真正通用的,优先将其写入所有智能体都能看到的地方(一个 AGENTS.md,或者 CLAUDE.md ↔ AGENTS.md 的符号链接),而不是重复三次。在写入之前始终解析符号链接,这样你才知道你真正在编辑哪个文件。
4. 提出变更集——带证据的具体差异,有上限
呈现一个变更集:一个有序、可浏览的列表,其中每个项目包含目标智能体+文件、确切的编辑内容(一个差异或明确标出的修改前后对比)、证据以及置信度。使用 references/changeset-format.md 中的格式。两条规则保持其明智:
- 设定上限。 每次运行最多展示约 5 个更改,按最高置信度优先。其他内容放入“积压”部分——记录下来,不应用。一波编辑潮是工作流变蠢的方式。
- 按重复次数×影响排序。 一个被陈述三次、每次会话都能节省一次修正的偏好,每次都胜过巧妙的单次偏好。
始终将变更集保存到带日期的报告中,即使没有任何东西被应用,这样就有记录可供回顾(这回答了线程中的“你把输出保存在任何地方吗,还是只是读取并继续?”)。将其写入 ~/.introspect/reports/YYYY-MM-DD.md。
5. 批准——关卡
展示变更集并让用户选择要应用的内容:全部、部分或都不。默认为提议并批准——未经明确同意,不要编辑任何智能体的配置。当有多个项目时,使用 AskUserQuestion(多选)让用户选择。如果用户明确要求无人值守/定时运行,请参见下面的“无人值守运行”。
6. 应用 + 记录——可逆地
对于每个已批准的项目,写入正确的表面(完整格式见 references/routing.md):
- Claude — CLAUDE.md: 在正确的
##部分下追加或原地编辑规则;保持原风格(简短、祈使句、解释原因)。 - Claude — 记忆: 创建/追加一个节点文件并向
MEMORY.md添加一行索引;匹配feedback_*/project_*/reference_*约定和[[wikilink]]交叉链接。 - Claude — 技能/命令: 创建/编辑
~/.claude/skills/<name>/SKILL.md或~/.claude/commands/<name>.md。如果几个会话重写了同一个辅助脚本,将其打包。 - Codex — AGENTS.md: 在受管理块内追加(
<!-- introspect:begin --> … <!-- end -->),以便重复运行是幂等的;保持紧凑(Codex 会将 AGENTS.md 截断至约 32 KiB)。优先使用项目根目录的AGENTS.md(桌面应用不能可靠地加载全局应用的那个)。 - Cursor — .cursor/rules/*.mdc: 写入一个带有 YAML 前置元数据的规则文件(将
alwaysApply: true用于始终开启的偏好,或description:+alwaysApply: false)。不要尝试写入 Cursor 的云“记忆”;使用规则文件。不要在 Cursor 运行时写入实时的state.vscdb。
然后向分类账追加一行,记录在 ~/.introspect/ledger.jsonl 中——每个已应用的更改一个 JSON 对象:{date, agent, target_file, kind, summary, evidence, sessions, undo_hint}。分类账让您可以(a)显示设置是如何随时间累积的,以及(b)以后撤销更改。在编辑现有文件之前,在 undo_hint 中记录其之前的状态(或保留 .bak 文件)。
安全模型(请阅读——这正是为什么每天运行是安全的全部原因)
- 提议,而非强加。 默认启用批准关卡。用户看到每一个差异。
- 复发阈值。 不从单次出现提议。习惯,而非策略。
- 收敛,而非搅动。 强化/合并现有规则,而不是添加几乎重复的规则。一次什么都不更改的运行在安静的日子里是完全可以的,也是预期的。
- 限制影响范围。 每次运行最多约 5 个更改;其余的放入积压。
- 规则关乎用户,而非智能体。 捕捉用户想要如何工作。不要制造仅仅重述智能体基线能力的规则(比如“编辑前先阅读”)——那只是臃肿。只有当写下用户设置的某个部分能够防止重复时,“智能体卡住了/重复了”这个信号才值得一个更改。
- 永不存储机密。 收集器会脱敏处理常见密钥/令牌的形状,但保持警惕:永远不要将 API 密钥、密码、
.env值或令牌复制到规则或报告中。如果你看到一个,就把它排除在外,并且(如果看起来是活跃的)向用户标记它。 - 可逆。 所有已应用的内容都在分类账中,带有撤销提示。
- 正确的表面,正确的范围。 用户范围的偏好 → 该智能体的全局文件。项目特定的事实 → 该项目的配置。不要把项目琐事放在全局文件中。
触发方式——三种运行方式
- 按需运行。 “审查我的线程”、“运行 introspect”、“我这周在 Claude 和 Codex 中反复做了什么”、“把今天的修正变成规则”。默认时间窗口:今天。
- 每日 / 定时运行(本机调度器)。 通过工作框架的原生调度器注册运行——使用
schedule技能或CronCreate常规工具——不是操作系统级的 cron、launchd 或 shell 循环。原生调度在框架内使用相同的工具和权限运行此常规,用户通过/schedule管理它。一个好的默认值是每天一次在晚上,使用当天的窗口。 - 每 N 次会话 / 遇到摩擦时触发(可选)。 有些人(参见来源线程中的 buildooor)更倾向于在出现问题或每隔约 10 次会话时触发此功能,而不是按时钟。将其挂钩为一个
Stop钩子,用于计数调用并在达到 N 次后提示。提供此选项;未经批准永远不要安装钩子。
无人值守运行
如果由没有人类在场的定时/常规调用,不要静默地将更改应用于任何智能体的配置。相反:运行管道,将带有提议变更集的带日期报告写入 ~/.introspect/reports/,并通过常规的通知显示一个简短摘要,以便用户可以在其下一次交互式会话中批准。唯一可以在无人值守时安全自动应用的类别是一个不重复任何内容的新 Claude 记忆节点——即便如此,也要记录它。将累积置于人类控制之下;这才是重点。
参考
references/routing.md——每个智能体的读取来源 + 写入表面 + 精确的磁盘格式(CLAUDE.md、记忆、AGENTS.md、.cursor/rules/*.mdc)以及收集器使用的对话记录模式。references/changeset-format.md——变更集 + 报告 + 分类账模板。scripts/collect_threads.py——多智能体收集器(运行--selftest以验证)。
重复核心循环,因为这就是全部:从每个智能体收集线程 → 找出重复模式(而不是一次性策略)→ 检查它们是否已经写下 → 提出一个小的、有上限的、有证据支持的变更集 → 只将批准的内容应用到正确的智能体配置 → 可逆地记录。