vima-tech/Innate

层级角色

Innate 是辅助性的——它绝不能阻塞主任务。所有 innate 操作都是尽力而为的。如果工具调用出错：重试一次（使用修正后的调用），然后放弃并继续执行。

何时召回

仅在任务开始时召回，且任务属于以下情况：

• 涉及已知存在重复模式的领域（例如特定的代码库、框架或协议）
• 涉及调试或修复可能之前遇到过的问题
• 架构/设计相关——先前决策很重要

跳过召回的情况：快速的一行命令、答案明确的简单问题、用户明确界定为全新领域且无先前上下文的任务。

查询构建

使用规范意图，而非用户的字面表达。保持跨会话的查询一致性——同一类问题应始终使用相同的规范形式，因为 Innate 会按查询模式累积上下文统计。

用户所说	好的查询	差的查询
"为什么启动时会崩溃？"	startup crash sqlite init	为什么启动时会崩溃
"重构认证流程"	auth flow session token handling	重构认证流程
"给 API 添加限流"	rate limiting middleware pattern	添加限流
"调试这个不稳定的测试"	flaky test race condition timing	调试不稳定测试

调用：innate_recall(query=<规范意图>, budget=4000, source="mcp")

将召回的知识块注入你的工作上下文。向用户提及发现了哪些（如果有）相关的先前知识——一句话即可。

自动召回钩子

当 Innate 通过钩子安装后，一个 UserPromptSubmit 钩子 可能会自动向对话中注入一个 <innate-recall> 块——它已经为当前提示执行了相关性门控的召回，并携带一个 trace_id。当你看到该块时：

• 重用其 trace_id 用于结束时的 innate_record——不要为同一任务再次调用 innate_recall（这会产生重复、悬空的追踪记录）。
• 将其中的知识块视为你自己召回的一样：应用有帮助的部分，然后对每个块给出裁决（见下文）。
• 如果该块不存在且任务有此需要，则按上述方法手动召回。

该钩子受相关性门控，因此它的沉默意味着“没有知识块得分足够高”——而非“不存在知识”。如果你怀疑存在门控遗漏的相关先前知识，请手动召回。

何时记录

在产生实际结果（成功或失败）的任务之后记录。跳过记录的情况：

• 探索性来回对话，无明确结论
• 用户中断的任务，未完成
• 纯检索（用户仅提问，未构建或更改任何内容）

结果规则

情况	outcome
任务完成，用户确认或接受了结果	ok
任务失败，方法错误，用户不得不纠正方向	fail
会话中断，结果不明确	unknown

逐块裁决——强制要求

这是 Innate 中最重要的契约：置信度排序的好坏完全取决于你在此处报告的精度。每次召回并显示了知识块（手动的或钩子注入的）后，都必须以逐块裁决来结束。 对于呈现在你面前的每个知识块，它恰好属于以下三类之一：

裁决	含义	处理方式
已使用 + 有帮助	你应用了它，并且它节省了时间/避免了错误	used=[id] 且 feedback_up=[id]
已使用 + 误导	你应用了它，但它是错误的或将你引向了错误方向	used=[id] 且 feedback_down=[id]
未使用	已召回但从未应用	完全省略（不在 used 中列出）

保持信号清洁的规则：

• used 仅列出你在推理或输出中主动引用的知识块——通常一至三个。切勿用仅召回的知识块填充。
• 如果你没有应用任何知识块，这是一个真实且有价值的信号：显式设置 used=[]（已知无使用）。不要跳过记录——沉默不等于“没有帮助”。
• 你 used 的知识块几乎总是应该同时携带向上 或 向下的信号。一个被使用但没有裁决的知识块会浪费你能给出的最强排序输入。
• 对 feedback_down 要诚实。你标记为错误的知识块会被审查和归档；一个错误但未被标记的知识块会继续误导未来的会话。

输出摘要——结构化格式

编写一个自包含的句子，让未来的智能体在无上下文时也能据此行动。使用以下结构：

<已完成或学到的内容> — <关键约束或方法> — <何时适用>

好的示例：

• 通过检查 PRAGMA journal_mode 响应而非假设 WAL 的方式修复了 SQLite WAL 模式检测——适用于多进程设置中的任何新数据库连接
• 通过注入时钟模拟解决了不稳定的认证测试——真实系统时间会在令牌过期检查中导致竞态条件
• 限流必须在认证中间件之前应用，而非之后——否则未经身份认证的请求会绕过限流器

不好的示例（过于模糊，无法复用）：

• 修复了那个错误
• 我帮助用户处理了认证
• 问题出在时机上

output_summary 将成为可复用的知识块。如果它读起来像故事，请重写为原则。优先使用通用、可迁移的形式——去掉仓库/文件/函数名称和一次性标识符，将经验教训表达为下一个项目也能复用的原则；仅当经验教训无法在不失其意义的情况下通用化时，才保留项目特定的细节。如果你无法写出有用的摘要，设置 output="unknown" 并跳过记录。

调用：innate_record(trace_id=<id>, outcome=<ok|fail|unknown>, used=[<chunk_ids>], output_summary=<句子>)

显式反馈——为何重要

上述裁决表中的 feedback_up / feedback_down 列表是知识质量最快的信号，它们直接驱动排名和生命周期：同一知识块上收到两次下降信号会触发治理审查；五次会触发自动归档。相反，重复的 used + feedback_up 会将一个 pending 状态的知识块提升为 active。隐瞒反馈会冻结知识库；提供反馈则能让好知识上升、坏知识淘汰。

提名——罕见、显式

仅在真正可泛化的情况下使用 nomination 字段——即那些下次遇到此类问题时能节省大量时间的模式。罕见使用。不适用于每个任务。

提名格式（自包含原则）：

<原则> — <何时适用> — <避免什么>

示例：

innate_record(..., nomination="SQLite 基于部分 WHERE 子句的 UNIQUE 索引要求 ON CONFLICT 中的 WHERE 完全匹配——适用于所有 upsert 模式；没有 WHERE 的裸 ON CONFLICT 会静默跳过 upsert")

MCP 工具参考

工具	用途	说明
innate_recall	任务开始时（相关时）	使用规范查询形式——一致的措辞会积累上下文统计
innate_record	任务结束时（存在实际结果时）	结构化 output_summary + 精确的 used ID
innate_add	捕获已确认的见解	始终设置 source="mcp"；进入 pending 状态，等待审查
innate_spark	快速记录稍后使用的想法	简洁的提炼形式；无需审查
innate_evolve	会话结束时	trigger="manual"；提炼日志并管理知识库
innate_inspect	健康检查	知识块数量、债务比率、重建队列
innate_appraise	在执行风险步骤前进行直觉检查	仅作参考信号——直觉，而非精确答案。将其作为其中一个输入来权衡；绝不允许它覆盖你自己的分析。abstained=true 表示没有依据——这是正确的结果，而非失败

未经用户显式请求，切勿调用： innate_approve, innate_archive, innate_invalidate, innate_restore, innate_mature_spark, innate_promote_spark, innate_drop_spark。

回写决策

在结束长会话之前，静默运行此检查清单：

1. 是否发现了非显而易见的解决方案？（变通方案、隐藏约束、微妙的错误模式）
2. 是否发现了一种通用、可迁移的技能、方法或技术？（优先选择这些——将项目特定的经验教训抽象为可复用的形式；仅在确实无法泛化时才保留项目特定的规则）
3. 用户是否纠正了我可能重复犯的错误假设？
4. 是否在多次失败尝试后获得了来之不易的见解？
5. 是否有召回的知识块主动提供了帮助？（记录 feedback_up）
6. 是否有召回的知识块造成了误导？（记录 feedback_down）

如果 1-4 中任意一项为是 → 向用户提议：

"此会话发现了 [一句话描述]。是否要将其保存到 Innate？"

只有在用户确认后才调用 innate_spark 或 innate_add。切勿静默写入。

禁止逐字记录规则

原始对话文本绝不能存储。始终提炼为可复用的原则形式：

<原则> — <触发上下文> — <避免什么>

❌ 逐字记录	✅ 提炼后
"用户告诉我使用 WAL 模式，我通过更改 pragma 修复了它"	"SQLite WAL 模式必须通过 PRAGMA 响应来验证，而非假设——适用于任何写密集型多进程设置中的数据库打开操作"
"我们花了 2 小时调试认证，因为时钟偏差"	"JWT 验证必须考虑时钟偏差容忍度（≥30 秒）——适用于具有独立系统时钟的分布式服务之间的认证"

优先选择通用而非项目特定

Innate 偏向通用、可迁移的技能、方法和技术——那些跨项目都能受益的知识，而不仅仅是当前代码库。当一个经验教训是项目特定的时候：

1. 尝试抽象它——去掉仓库/文件/函数/路径名称和一次性标识符，重写为下一个项目可以复用的原则。
2. 保存抽象后的形式。仅当经验教训确实无法在不失其意义的情况下泛化时，才保留具体的项目细节。

❌ 项目绑定	✅ 泛化后
"在此仓库中，record() 必须在 BEGIN IMMEDIATE 内部执行"	"必须原子化的多步骤状态变更应放在一个排他事务中，而非逐步提交——适用于任何具有并发进程的 SQLite 写入器"
"在元表中设置 recall.budget=4000"	"将检索预算暴露为可调参数而非硬编码——让召回量能随上下文窗口扩展而无需代码更改"

灵感 vs. 笔记

使用 innate_spark	使用 innate_add
快速想法、未成形的预感	已确认的可复用原则
尚未验证	在此会话中已验证
用户说“稍后记录这个”	用户说“记住这条规则”

CLI 回退（如果未配置 MCP）

# 召回
innate recall "<规范意图>" --top 5 --format json --source cli

# 使用结构化摘要记录
innate record <trace_id> --outcome ok \
  --used <id1>,<id2> \
  --output-summary "通过执行 Y 修复了 X——适用于 Z 时" \
  --feedback up  # 或 down

# 捕获见解
innate add "<原则> — <触发条件> — <避免什么>" \
  --trigger "<2-5 个词的上下文>" \
  --source agent

# 快速灵感
innate spark "<1-2 句话的提炼想法>"

# 会话结束
innate evolve --trigger manual
innate inspect

命令

以下斜杠命令通过 innate install 自动安装到 ~/.claude/commands/，并在每次重新运行 innate install 时更新。每个 command 块定义一个命令：--- 之前是元数据，--- 之后是命令体（智能体提示）。

name: innate-recall
description: 为当前任务上下文召回先前的 innate 知识
---
为当前任务上下文运行 innate_recall 并将结果注入此对话。

如果用户在命令后提供了查询，则直接将该查询用作召回查询。
如果未提供查询（$ARGUMENTS 为空），则从最近的用户消息或当前任务意图推断查询——使用**规范意图**（例如 `sqlite wal mode init`，而非 `为什么会崩溃`）。保持查询形式与你在未来如何表述同一类问题一致。

步骤：
1. 构建规范查询字符串（从 $ARGUMENTS 或推断的意图）。
2. 调用 `innate_recall`，使用 `query=<查询>`、`budget=4000`、`source="mcp"`。
3. 如果返回了知识：用一句话总结发现的内容，然后将相关的知识块注入上下文。
4. 如果为空：说“未找到针对以下内容的先前知识：<查询>”——不要编造。
5. 保存 `trace_id` 以备后续在 `/innate-record` 中使用。

name: innate-record
description: 用结果和结构化摘要关闭当前的 innate 追踪
---
用结果和摘要关闭当前的 innate 追踪。

从 $ARGUMENTS 解析以下内容：
- outcome: 为 `ok`、`fail`、`unknown` 之一（如果未指定，默认为 `ok`）
- 任何剩余文本将成为 output_summary 覆盖值

步骤：
1. 确定此会话最近一次 `innate_recall` 调用中的活跃 trace_id。如果没有可用的 trace_id，则说“无活跃追踪——请先运行 /innate-recall”。
2. 确定哪些被召回的知识块 ID 在最终响应中**实际被使用**（不仅仅是候选的召回块）。要精确——未使用的召回块**不应**被列出。
3. 为未来无上下文的智能体编写结构化的 output_summary：
   格式：`<做了什么> — <关键约束/方法> — <何时适用>`
   如果用户在 $ARGUMENTS 中提供了摘要文本，则使用该文本。
4. 评估反馈：
   - 如果任何知识块直接有帮助 → 包含 `feedback_up=[chunk_id]`
   - 如果任何知识块是错误的/误导的 → 包含 `feedback_down=[chunk_id]`
5. 使用 `trace_id`、`outcome`、`used=[<chunk_ids>]`、`output_summary` 以及适用的反馈来调用 `innate_record`。
6. 确认：“已记录追踪 <trace_id>，结果为 <outcome>。”

name: innate-save
description: 将已确认的见解保存到 Innate 作为 pending 知识块
---
将已确认的见解保存到 Innate 作为 pending 知识块。

$ARGUMENTS 是要保存的见解文本（必需）。如果为空，询问：“你想保存什么见解？”

步骤：
1. 将 $ARGUMENTS 解析为见解内容。