独立、可嵌入的「经验子系统」。宿主应用（非Coding agent,这里指能接受先root的AI应用）在每次潜在 LLM 调用之前 先询问 Runtime：这次请求是否命中已知经验？置信度够不够？安全上能不能直接执行？
- 命中且成熟 → 确定性执行，在特定情况下可以不调用 LLM（根据experience的类型决定，快速、低成本、可复现）
- 命中但不成熟 → assist，宿主把经验预填 + 来源注入 LLM，做选择性修正
- 未命中 → delegate，宿主走正常 LLM 流程
- 事后反馈 → 置信度升降 → 经验在 raw → learning → automatic 之间演化
- 项目级工作区：任意目录生成
.experience/（独立经验库 + 管理仪表盘 + 经验卡片），本项目经验与其它项目隔离 - MCP 插件化：40 个工具（标准帧协议），接入 Codex / TRAE / Claude；配合 Agent 提示词契约 实现「无匹配且有价值 → 主动询问沉淀」
- 当前版本：v0.2.1
| Skill | Experience | |
|---|---|---|
| 本质 | 给 LLM 读的文档 | 给宿主执行的程序化路径 |
| 每次调用成本 | 必须过 LLM | 命中后零 LLM |
| 谁拥有 | 随 agent 分发 | 随使用逐渐长出来 |
| 生命周期 | 静态 | raw → learning → automatic → 衰减/沉睡 |
experience_runtime/
├── __init__.py # ExperienceRuntime 入口
├── runtime.py # 编排：request → encode/match/gate/run → feedback；before_llm 门面；目标记忆
├── state.py # 状态编码（规则 + 可插拔）
├── matcher.py # 三元匹配（规则/标签/向量 + BM25）
├── index.py # 轻量倒排索引（繁多经验快速命中）
├── controller.py # 激活门控（置信度 × 相似度 × 安全门）
├── executor.py # 确定性执行器 + 安全表达式求值器（非 eval）
├── compiler.py # 经验编译（规则基座 + 宿主 LLM 增强 + 校验回退）
├── feedback.py # 三路径反馈 → 置信度闭环
├── store.py # 独立 SQLite（不碰宿主数据库）
├── schema.py # 经验 Schema（版本化）
├── classes.py # 分类注册表与参数模板
├── portable.py # 经验包导出/导入
├── project_workspace.py # 项目级经验工作区（.experience/ 初始化与卡片同步）
├── experience-viewer.js # 可移植经验查看器（Web Component）
├── dashboard_server.py # 可视化管理栏（独立服务）
├── dashboard_export.py # 静态快照导出
├── mcp_server.py # MCP 外壳（40 工具；标准帧 + 换行双协议）
├── prompts.md # Agent 接入模板（记忆类型差异化 + 主动询问沉淀）
├── integrations/ # 接入配置（TRAE/Codex/Claude MCP + root 网关 + PROMPT_GUIDE）
├── docs/ # 设计文档（项目级经验工作区设计等）
├── tests/ # 测试套件（122 项）+ 使用展示与数据
└── exceptions.py
> 说明：默认经验库 `exp.db` 与项目工作区 `.experience/` 为本地数据（已在 .gitignore 排除），不随仓库分发。
from experience_runtime import ExperienceRuntime
runtime = ExperienceRuntime(
db_path="my_app/exp.db",
data_providers={"finance": my_finance_provider}, # workflow 步骤用
llm=my_llm_call, # 可选：经验编译/辅助
)
def handle(user_input, context):
# ① 每次潜在 LLM 调用之前，先问 Runtime
r = runtime.request(user_input, context)
if r["decision"] == "execute":
return r["output"] # 直接返回，不调 LLM
if r["decision"] == "assist":
prompt = inject_prefill(user_input, r["prefill"], r["origin"])
reply = my_llm_call(prompt)
runtime.feedback(r, llm_output=reply) # ② 反馈闭环
return reply
# delegate：正常 LLM 流程
reply = my_llm_call(user_input)
runtime.feedback(r, llm_output=reply)
# ③ 用户确认结果有效后，转化为经验供后续使用
if user_confirms(reply):
runtime.compile_experience(reply, source_type="llm_output",
origin_type="user_confirmed")
return replyrequest(input, context)
→ encode 状态编码（规则，可替换）
→ match 本地检索候选（规则 0.55 + 标签 0.25 + 向量 0.20）
→ decide 候选降级链（按相似度从高到低逐个审查）
① 触发条件不满足 → 跳过（记 rejected）
② 异常规则命中 → 跳过（记 rejected）
③ 安全门 ≤ 0.3 → 跳过（记 rejected）
④ conf ≥ 0.75 且 sim ≥ 0.50 → execute（绕过 LLM）
⑤ conf ≥ 0.35 且 sim ≥ 0.30 → assist（注入 prefill/origin）
⑥ 全部被否决 → delegate（携带候选摘要 + 被否决原因，供 LLM 轻介入）
→ run 确定性执行（模板/工作流/规则）
→ feedback 事后更新置信度（自动检测 + 用户反馈）
设计要点：候选按「匹配质量」排序，置信度只决定"信任到什么程度"， 不参与排序——避免高置信弱匹配挤掉低置信强匹配。 被否决的候选会逐一记录（decision_counts.rejected），便于事后质疑与审查。
治本：不同经验类型不再共用同一套匹配权重与拒绝链。
- 按类型分化匹配权重（matcher.KIND_WEIGHTS）：
- reference：语义主导
0.30 规则 + 0.20 标签 + 0.50 向量——跨项目/表观差异大时关键词失效，靠语义命中； - process：
0.45/0.25/0.30（动作词 + 语义并重）； - result：
0.60/0.20/0.20、reflex：0.65/0.20/0.15（执行型精确优先）。
- reference：语义主导
- hint 参考档（吸铁石）：reference/process 型经验只要成为候选（sim ≥ 0.10）且置信度 ≥ 0.25， 即使未达 assist 门槛也以低优先级参考注入（prefill 前缀「参考提示·可能相关」），由 LLM 仲裁； 深层经验的价值是在黑盒中放入吸铁石、吸引出有效内容以节省 token，而不是追求零 LLM 调用。
- 拒绝链公平化：
- reference 的 condition/安全门失败 → 降级为 hint（不再硬拒）；
- reference + delegate_only → 不记拒绝，转为结果里的
recall_candidates（可召回记忆，可见但不注入）； - 执行型（result/reflex）保持原严格门槛。
- 复合优先：多条参考经验部分命中时，composite 组装优先于单条 hint，避免拆散方法链。
score = PA × (base + UF×w_uf + UA×w_ua + R×w_r) × DS
PA = success / (success + failure + 1) 预测准确率（主导因子）
UF = min(近期使用频率, 10) / 10 使用频率放大器（随 tick 衰减）
UA = (positive_fb + 1) / (positive_fb + negative_fb + 2) 用户接受度
R = e^(-0.05 × 距上次使用天数) 新鲜度（约 14 天半衰期）
DS = 数据稳定性（默认由最近输出一致性推导，宿主可注入覆盖）
默认权重: base=0.50, uf=0.20, ua=0.15, freshness=0.15（可配置）
每条经验维护的多维计数（存于 confidence）:
| 计数 | 作用 |
|---|---|
| success_count / failure_count / streak | 预测准确率 + 连续成功/失败 |
| frequency / total_usage | 使用频率（frequency 随 tick 按 0.7 衰减） |
| positive_fb / negative_fb | 用户显式正/负反馈 |
| last_used | 新鲜度 |
| consistency_window（最近 10 次输出哈希） | 输出一致性 → DS |
| decision_counts {executed/assisted/delegated/rejected/hinted} | 决策路径观察（质疑/审查） |
等级与状态：
- automatic ≥ 0.75；learning ≥ 0.35；raw < 0.35
- 连续 3 次失败 → 强制压到 learning 以下（质疑加速，避免僵化复用）
- score < 0.15 且失败 ≥ 成功 → sleeping（不再参与匹配）
{
"id": "exp_monthly_review_20260810_120000_ab12",
"name": "月度消费复盘",
"description": "根据当月消费数据输出复盘",
"level": "learning",
"status": "active",
"family": "finance_review",
"parent_id": "",
"prerequisites": ["exp_basic_finance_xxx"], # 前置经验：使用时链式注入其方法
"extends": "", # 递进指向：本经验建立在它之上
"kind": "process",
"reuse_mode": "assist_only",
"logic": {
"goal": "对当月消费数据做复盘",
"triggers": ["月度", "消费"],
"path": [
{"action": "加载当月支出与必需消费", "tool": "finance", "input": "month", "expect": "", "verify": ""}
],
"branches": [
{"if": "支出 > 1000", "then": "提示支出偏高", "why": "超过历史均值"}
],
"references": ["docs/budget.md"],
"io": {"inputs": ["month"], "outputs": ["支出汇总", "必需/弹性拆分"]}
},
"trigger": {"event": "monthly_review", "frequency": "recurring", "condition": ""},
"match": {"tags": ["消费", "月度"], "keywords": ["复盘", "消费"], "embedding": []},
"requires": ["expense"],
"exec": {
"template": {"reply": "本月支出 {expense} 元，其中必需 {essential} 元"},
"workflow": [{"name": "load", "provider": "finance", "params": {}}],
"decision_rules": [{"if": "expense > 1000", "then": "warning:支出偏高"}],
"exception_rules": [{"if": "expense > 10000", "then": "delegate"}],
"code": null
},
"confidence": {
"score": 0.52,
"success_count": 2, "failure_count": 1,
"streak": {"success": 2, "failure": 0},
"frequency": 3, "total_usage": 3,
"positive_fb": 2, "negative_fb": 1,
"last_used": "", "consistency_window": [],
"last_output_hash": "", "last_decay_at": "",
"decision_counts": {"executed": 1, "assisted": 1, "delegated": 1, "rejected": 0}
},
"origin": {"type": "user_confirmed", "source": "llm_output",
"reason": "用户确认有效", "episode_ids": []}
}- 规则基座：纯本地，从结构化数据提取 name / trigger / tags / 模板
（数值字段自动参数化为
{var}占位符）。 - LLM 增强：宿主注入
llm_call(system, prompt) -> {"success", "text"}， 在规则基座之上生成更完整的 trigger / decision_rules / 模板； LLM 缺字段时回落到规则基座，绝不空手而归。 - Schema 校验：任何产物先过
schema.normalize_experience，不合法则回退。
exp_id = runtime.compile_experience(
{"total_expense": 5000, "essential": 3000},
source_type="monthly_report",
origin_type="user_confirmed",
llm=my_llm_call, # 可选
)dry_run=True 可预览编译结果而不落库。
| 参数 | 默认 | 说明 |
|---|---|---|
db_path |
包内 exp.db |
独立存储，宿主可指定 |
encoder |
默认规则编码器 | 可注入自定义编码 |
data_providers |
{} | workflow 步骤提供者 |
llm |
None | 经验编译/辅助用（不参与确定性执行） |
automatic_threshold |
0.75 | 经验成熟阈值 |
assist_threshold |
0.35 | 辅助阈值 |
min_similarity |
0.10 | 匹配最低门槛 |
formula_weights |
默认权重 | 置信度公式权重（base/uf/ua/freshness） |
default_goal_inject_policy |
hybrid/start/p=0.15 | 长期目标注入策略（start+关键词+概率+上限） |
audit_retention_days |
0（永久） | 决策审计保留天数，tick 自动清理 |
auto_compile_limit |
5 | 单次自动编译条数上限 |
max_source_chars |
8000 | 传给 LLM 增强的源材料截断 |
composite_max_parts / max_per_family |
3 / 1 | composite assist 组装上限 |
每次 update_experience 都会先存一份快照；可查看版本、按版本回滚：
runtime.update_experience(eid, name="V2", note="改名")
vers = runtime.get_versions(eid) # [{id, note, created_at}, ...]
runtime.restore_version(eid, vers[-1]["id"])相似但轻微不同的经验组织成「经验族（family）」，族内用父子关系表达 "同一器官的不同肌肉/神经元"：
财务复盘（父，泛化）
├── 消费复盘（子，具体）
└── 收入复盘（子，具体）
匹配时先定位"器官"（族），再在族内选最具体的变体；子变体被否决时， 父变体作为回退。API：
runtime.set_parent(child_id, parent_id) # 自动继承父经验的族
runtime.list_families() # 族概览
runtime.family_tree(family) # 族内父子树把相似 episode（LLM 输出，用户确认有效）自动编译为经验：
rt.save_episode("monthly_report", llm_output, user_validated=True)
sugs = rt.suggest_compilations(min_episodes=3) # 找到可沉淀的相似簇
created = rt.auto_compile(min_episodes=3) # 编译为经验（origin=auto_compiled）- 方法簇（mode=method）：同一 (source_type, signature) 的任务签名聚类 → process 经验（方法）。
- 轨迹簇（mode=trajectory）：无显式签名、但 meta.trajectory 行为轨迹相同的 episode 按"动作序列"聚类 → 从行为自动推断方法骨架（路径/工具/失败对策）。 轨迹簇的 episode 不参与文本簇，避免方法素材被当成可复现结果沉淀。
- 文本簇（mode=text）：无签名、无轨迹的 episode 按文本相似度 ≥0.5 聚类 → result 经验（可复现输出）。
- 单次自动编译受 auto_compile_limit 上限约束；建议宿主先展示 suggest_compilations 结果、用户审阅后再 auto_compile。
启动 MCP 服务器：
python -m experience_runtime.mcp_server --db path/to/exp.dbCodex 配置（TOML，合并到 ~/.codex/config.toml；注意用解释器绝对路径，
环境变量写在 env 表，--db 可指向项目工作区经验库）：
[mcp_servers.experience_runtime]
enabled = true
command = 'C:\Users\<你>\...\python.exe'
args = ["-m", "experience_runtime.mcp_server", "--db", "D:/某项目/.experience/exp.db"]
[mcp_servers.experience_runtime.env]
PYTHONPATH = 'D:/.../VE5'TRAE / Claude Desktop 配置示例见 integrations/mcp/trae/mcp.json、
integrations/mcp/claude/claude_desktop_config.json；Codex 完整示例与常见错误见
integrations/mcp/codex/。
协议：stdio 双模自动识别——标准 Content-Length 帧（Codex/Claude 等标准客户端） 与换行分隔 JSON-RPC（向后兼容）；已修复 Windows 管道下 stdin 大块读取阻塞问题。
暴露 40 个工具（tools/list 可查），按用途分组：
| 分组 | 工具 |
|---|---|
| 查询/门面 | experience_request、experience_before_llm |
| 沉淀 | experience_compile、experience_create、experience_save_episode、experience_suggest_compile、experience_auto_compile、experience_authorize |
| 管理 | experience_get/list/update/delete、experience_versions/restore、experience_set_parent、experience_set_prerequisites、experience_set_extends、experience_set_category、experience_classes |
| 目标记忆 | experience_goal_add / update / list / state / delete |
| 审计/统计 | experience_stats、experience_families/tree、experience_audit / audit_get、experience_evidence、experience_episode_get、experience_dashboard、experience_cleanup_audit |
| 迁移 | experience_export、experience_export_markdown、experience_import |
| 项目工作区/联想 | experience_project_init、experience_project_sync、experience_assoc_query |
重要：MCP 是拉取式工具提供者，不是中间件。要让 agent 在每次 LLM 调用前自动查询、
并在有价值时沉淀经验，必须配合 Agent 提示词契约（见下节与
integrations/mcp/codex/PROMPT_GUIDE.md、prompts.md）。
宿主驱动门面：experience_before_llm 返回 {action: bypass|assist|proceed}，
适合不支持请求前 hook 的宿主，由业务代码确定性调用。
把任意目录指定为「项目文件夹」后，在其中生成独立经验工作区 .experience/，
管理该项目产生的全部经验，与全局/其它项目隔离：
<项目根>/.experience/
├── exp.db # 项目级独立经验库
├── config.json # 元信息（项目路径/名称/创建时间/runtime 版本）
├── README.md # 项目经验使用说明
├── PROMPT_GUIDE.md # Agent 契约副本（含主动询问规则）
├── dashboard/ # 本地可视化管理栏模板（dashboard_server + experience-viewer + 启动脚本）
└── experiences/ # 经验卡片视图：大类=文件夹，细分=子文件夹
- 初始化/同步：
CLI：
from experience_runtime.project_workspace import init_project_workspace, sync_experience_cards init_project_workspace(r"C:\\任意\\项目目录") # 生成 .experience/ sync_experience_cards(r"C:\\任意\\项目目录") # 镜像经验卡片
python -m experience_runtime.project_workspace init <目录>/sync <目录>； MCP：experience_project_init/experience_project_sync； - 组织规则：完全不同的经验 → 对应大类文件夹（document_processing / financial_analysis /
planning / development / quantitative / general）；树状「大类经验-细分经验」→
<大类>/<父经验名>/<分支经验名>.md子文件夹； - 接入：把 MCP 的
--db指向<项目根>/.experience/exp.db，本项目经验即自动归属本项目； - 设计文档：
docs/项目级经验工作区设计.md。
MCP 模式下经验不会自动生成——需要 agent 遵守契约（项目级复制 PROMPT_GUIDE.md，暂不做全局）：
- 前置查询：每次潜在 LLM 调用前先
experience_before_llm/experience_request（<20ms）； - 事后沉淀：满足判据（可复制/方法性/已验证/未覆盖/降本 ≥3 条）→
experience_save_episode； - 主动询问：无匹配（proceed/delegate）且本次任务有价值时，主动询问用户是否生成为经验， 确认后沉淀到当前项目工作区；不静默、也不擅自生成；
- 聚类编译：同签名 ≥3 条 →
experience_suggest_compile→experience_auto_compile； reflex 免 LLM 执行需用户确认后experience_authorize； - 反馈闭环：assist/execute 后按用户评价
experience_feedback驱动置信度成长/降级； - 生成位置：经验默认写入当前项目工作区
.experience/exp.db，不写全局库。
中文任务短语按"虚词断句 + 动词拆分"处理，让局部复用也能命中共享子经验：
"帮我整理海豹文件夹的文档" → [整理, 海豹文件夹, 文档]
"整理文档" → [整理, 文档]（与上一条共享 整理/文档 子经验）
state.task_tokens()：任务级分词；derive_keywords()用它派生经验关键词。- 上下文标签新增
task / intent / action字段：宿主传入context={"task": "file_organize"}时与经验标签保持同一语义空间（解决 TRAE 测试发现的标签桥接问题）。
- 初始置信度按证据定价：
user_confirmed→ 0.30；auto_compiled→ 按簇大小0.25 + 0.05×(簇数-3)，封顶 0.35；llm_compiled→ 0.25。 - assist 增加强匹配放行子句：
conf ≥ 0.25 且 sim ≥ 0.35也允许 assist （新经验可在强相关时上场，LLM 仍仲裁，绝不自动 execute）。
多条 process/reference 经验部分命中时，组装为综合 prefill 注入 LLM：
请求"整理海豹文件夹文档"
├─ 整理文档（流程） ← 动作槽命中
└─ 海豹文件夹文档（上下文） ← 对象槽命中
→ assist + composite=true，prefill 含多条来源（【名称｜匹配度｜置信】标注）
- 冲突消解：按（特异性=similarity，置信度）降序，LLM 为最终仲裁者。
- 组装只发生在 assist 路径，永不 execute；result 型经验不参与组装。
经验可以表达"课程式阶梯"：一条经验建立在前一条之上。
prerequisites：前置经验列表（ID 或名称）。命中某经验（assist）时， 自动沿 prerequisites 链（BFS，深度上限 3，防环）解析前置经验， 把其方法摘要注入 prefill 的【前置经验】段落，并在sources[].relation="prerequisite"中归因。extends：递进指向（ID 或名称）。本经验"建立在它之上"， 链式注入时与 prerequisites 同样处理（自动跟随 extends 链）。- 注入只发生在 assist 路径：execute 直接短路（无需 LLM 仲裁）， delegate 交给 LLM 完整探索。
- 引用解析支持 ID 或名称；跨库迁移时由便携格式自动重写。
API：
runtime.set_prerequisites(exp_id, prereq_ids)/runtime.set_extends(exp_id, extends_id)- 请求结果新增：
decision_id、chain_injected（本次注入的前置经验 ID 列表）
每次 request() 都写入一条决策审计（decision_logs 表），
便于事后质疑："为什么这次没用它 / 为什么它被跳过"。
每条记录包含：
- decision_id / input / decision（execute|assist|hint|delegate）+ input_chars / prefill_chars（token 代理）
- candidates：候选归因（matched_by）
- rejected：被否决原因链（factor + detail + safety_factors）
- sources：实际采用的来源（含 prerequisite 注入）
- feedback_rating：用户反馈回写（feedback() 自动关联 decision_id）
API：
runtime.audit_logs(limit, exp_id, decision)/runtime.audit_get(decision_id)feedback(result, ..., user_rating=1)会把 rating 回写到对应审计记录
经验可以打包为 JSON「经验包」跨宿主迁移（VE / Codex / TRAE）：
runtime.export_experiences(exp_ids=None, include_episodes=False, include_confidence=True)runtime.export_experience(exp_id, ...)runtime.export_markdown(exp_ids=None)→ 人类可读 Markdown（供审阅）runtime.import_bundle(bundle, mode="remap"|"preserve", on_conflict="skip"|"overwrite", reset_confidence=False, dry_run=False)- remap：生成新 ID，自动重写 parent_id / prerequisites / extends 引用
- preserve：保留原 ID；冲突按 on_conflict 处理
- reset_confidence：导入后置信度重置为证据定价默认值（重新培育）
当宿主没有显式打任务签名时，只要把"行为轨迹"记进 episode 的 meta.trajectory， runtime 就能从重复的动作序列推断方法骨架：
rt.save_episode("document_summary", text, user_validated=True, meta={
"task": "文档摘要",
"trajectory": [
{"action": "解析文件格式", "tool": "pdfplumber", "ok": True},
{"action": "提取核心观点", "tool": "llm", "ok": True},
{"action": "压缩到300字", "tool": "llm", "ok": False, "error": "超长需分段"},
],
})- 动作序列签名 = 动作 slug 串联；≥min_episodes 条同序列 → 轨迹簇。
- 自动推断：传导路径（action+tool）、失败对策（ok=False → branches）、 参考材料、任务名；产物为 process 经验（assist_only，永不 execute）。
- 宿主流程：suggest_compilations（展示）→ 用户审阅 → auto_compile（落库）。
- 成本治理：auto_compile(limit=N) 或运行时 auto_compile_limit 控制单次编译数； stats() 提供 compile_count / llm_compile_count。
经验指向证据，而不是把结果当权威：
- origin.evidence：{episode_id, ref, type(episode|file|url|node), note}， 自动由 origin.episode_ids 与 logic.references 组装。
- API：
get_episode(ep_id)下钻原文；evidence(exp_id)查看完整证据链。 - assist 时 sources[].evidence 携带证据链，prefill 追加"证据来源"段落， 引导 LLM 读活数据源而非信任缓存快照。
- 匹配器新增轻量 BM25 召回分（查询任务词在经验词表中的命中率）。
- 作为独立信号参与 matched_by 归因（可含 "bm25"）与同分排序仲裁； 不改变综合相似度门槛，避免高置信弱匹配挤掉低置信强匹配。
auto_compile_limit（默认 5）：单次自动编译条数上限，可按调用覆盖。max_source_chars（默认 8000）：传给 LLM 增强的源材料截断上限。runtime_meta表持久化 compile_count / llm_compile_count，stats() 可见。
不同大类（行为域）拥有不同的门控/置信度/治理参数：
- 内置大类：document_processing / financial_analysis / planning / development / quantitative / general（通用默认）。
- 归类：显式
category> family 映射/前缀 > general； create/compile/auto_compile 自动归类，set_category手动指定。 - 消费点：
- 门控：类级
assist_only（永不 execute）与safety_factor（控制器）； - 置信度：类级
half_life_days与sleep_threshold（反馈引擎）； - 治理：
require_evidence缺证据时 assist 注入警告。
- 门控：类级
- API：
class_of / class_params / list_classes / register_class / set_category； MCP：experience_classes/experience_set_category；stats()["classes"]按类计数；审计日志记录 class_name。
简单确定性任务（如文件迁移）可沉淀为 reflex 型经验：
- 轨迹簇中全部为确定性工具操作（无 llm/generate/freeform）→ auto_compile 产出 kind=reflex、exec.workflow 的经验，默认未授权（assist 注入方法）。
authorize_experience(exp_id, note=...)（MCP：experience_authorize）用户确认后， 命中即 execute——不依赖 LLM 的"神经反射"闭环。- 授权是 per-经验 的显式开关：自动沉淀不自动获得执行权，安全默认保留。
authorize_experience支持score参数（v0.2.1+）：用户显式授权即视为直接赋分，授权分成为该经验的置信度下限（孰高原则），后续反馈公式不会将其压低；未显式传分时默认按 0.75 起步。
同一族（一条神经的不同末节）有多条变体经验时：
- 排序：相似度定主位；同族相似度接近时按分支质量（显式反馈 + 近期频率） 决定哪条末节优先——反馈好的分支自动"上位"，差的降级。
- 回退链：持续负反馈（连击 ≥2 或负反馈 ≥3 且比率 <0.4）的分支在控制器中被 标记 branch_demoted 并回退到下一条候选。
- 沉淀门：
auto_compile(min_episodes=3, min_occurrence_days=K)——只有周期内 重复出现的任务才沉淀；罕见/一次性场景不经验化。 - 使用门：低频 + 失败 ≥ 成功 → sleeping，不再参与匹配（tick 自动衰减）。
- 组装时同族只保留最优末节（composite_max_per_family=1），整体封顶 （composite_max_parts=3），避免数十条同族经验拼出"方法墙"。
- 不同族各自贡献方法，仍可组装（如"整理文档"+"海豹文件夹文档"）。
- 同一任务签名/动作序列再次出现、但 episode 携带新的 context_tags（如"实证"/"理论"） 时，suggest_compilations 返回 mode=variant 建议；auto_compile 创建分支经验： parent_id=基座、family=基座、tags=基座+新上下文标签。
- 分支命中：请求上下文含该标签 → 分支优先；通用上下文 → 基座优先。
- 这就是"大类经验 → 细分经验"的自动分化：A 是大类，B 是分支，反馈与频率决定谁上位。
- 按 类/族/关键词/标签/触发事件/名称 建 token 倒排，请求时先收敛候选再精排， 避免每次对全部经验做完整打分与反序列化。
- 收敛不足（<3）或召回为空时自动回退全量扫描，保证 embedding 独有命中不漏。
- 审计保留：
audit_retention_days（默认 0=永久）；cleanup_audit(retention_days)手动清理，tick()自动清理；MCP：experience_cleanup_audit。 - 索引指纹：
match_version仅在匹配相关字段（name/description/family/category/kind/ reuse_mode/trigger/match）变化时递增；置信度/反馈等更新不触发索引重建。 - 批量拉取：索引命中后一次
SELECT ... IN (...)拉取候选，避免逐条往返。
- API：
runtime.dashboard(recent=10)→ 经验清单（置信度/频率/正负反馈/最近操作）+ 审计回放 + 大类分布；MCP：experience_dashboard。 - 独立仪表盘：
python -m experience_runtime.dashboard_server --db exp.db --port 8765→ 打开 http://127.0.0.1:8765/ 查看。 - 可移植查看器：
experience_runtime/experience-viewer.js（Web Component +ExperienceViewer.render(data, container)，零依赖）。宿主嵌入：<script src="experience-viewer.js"></script><experience-viewer data-api="/api/dashboard">。 - 静态快照导出：
python -m experience_runtime.dashboard_export --db exp.db -o dashboard.html→ 自包含 HTML（内嵌 JSON 快照 + 查看器，双击即开、可存档/分享；--mask-len控制操作输入脱敏）。 - 三种形态（独立服务 / 静态快照 / 宿主嵌入）共用同一渲染代码，数据契约均为
dashboard()。
experience_runtime/integrations/ 提供两种接入模式：
-
MCP 插件：
integrations/mcp/下含 TRAE（mcp.json）、Codex（config.toml.example）、 Claude Desktop（claude_desktop_config.json）三份配置示例——工具提供者， 是否在 LLM 前查询取决于 agent/宿主。 -
记忆类型差异化：反射/执行型直接按授权执行（不注入）；流程/方法型每次任务边界注入； 长期目标记忆按注入策略节流（start 一次 + 概率自检 + 变更关键词触发 + 单任务上限）， 日常由 agent 通过记忆工具（
memory_tools()/ MCPexperience_goal_state）按需拉取； 注入次数/时间见goal_inject_stats（仪表盘）。 -
Root 逻辑：
integrations/root/experience_gateway.py——进程内 LLM 网关， 应用把唯一 LLM 入口换成ExperienceGateway.ask()，每次 LLM 调用前强制先问 runtime： execute 直接返回（免 LLM）、assist 注入 prefill 后调 LLM、delegate 正常调 LLM；confirm_and_compile()完成"用户确认 → 沉淀为经验"的闭环。
VE 等自有应用在每个 LLM 调用点之前确定性调用：
gate = runtime.before_llm(user_input, context)
# {"action": "bypass", "output": ...} 直接短路
# {"action": "assist", "prefill": ..., "sources": [...]} 注入后走 LLM
# {"action": "proceed"} 正常走 LLMMCP 端对应 experience_before_llm 工具；TRAE/Codex 的系统 prompt 模板见
prompts.md（含组装/反馈/沉淀的完整协议）。
- 不导入宿主任何模块：无 VE 的
app_paths/ai_gateway/ 业务数据库。 - 存储独立：默认
experience_runtime/exp.db。 - 执行确定性：
executor与SafeEvaluator不使用eval/exec。 - 测试独立：
python experience_runtime/tests/run_all.py（不依赖 pytest）——122 项单测全绿；另有真实 MCP 用例（可行性、reflex 零 LLM 执行、process 方法注入、长项目记忆、项目工作区）与对应报告接入 tests/。