Pi × EvoX Loop — 智能体经验继承 Skill
让 Agent 的每个坑只踩一次:失败经验自动入库(守卫过滤),同类任务自动召回已验证修法。
术语约定(0.29):正文以中文为主,技术字段在首次出现时标注一次英文原名(如「信号匹配 signals_match」),此后一律用中文,不再反复混排。完整中英对照见
docs/faq.mdQ17。文档地图(0.21 分层):
- 新用户只需读三节:30 秒上手 → 流程 A → 流程 B(约 60 行);其余按需查。
- 一分钟判断要不要用:
docs/one-pager.md(0.30 新增)- 最佳实践集中入口:
examples/quickstart.md(5 分钟闭环)+docs/overview.md(项目概览)+docs/common-mistakes.md(14 条反模式)——三份覆盖"上手/全景/避坑"。- 本文件其余部分 = 触发点/安全摘要/反模式速查/导航;
docs/advanced.md= 回填寻址/时间线/harvest/并发锁/共享库/宿主接入/运维/安全门明细;docs/common-mistakes.md= 常见错误用法完整清单;docs/config-errors.md= 常见配置错误;docs/faq.md= 完整 FAQ。docs/research.md= 流程 C 受控实验 + 陷阱设计纪律——研究专用,绝大多数用户无需打开。
30 秒上手(Quick-Start)
EN: Requires Node >= 22. Optional
@evomap/evolverintegration is GPL-3.0-or-later (only if you install and use--engine evolver); the default light backend is MIT, zero-dependency, zero-exfiltration. Three things only: A recall validated fixes at task start, B deposit after fixing a non-obvious failure, C (optional, research) controlled experiments. Daily use = A/B only. ⚠️ 前置要求:Node ≥ 22(node -v检查;旧版不支持,需先升级)。可选集成@evomap/evolver为 GPL-3.0-or-later——仅在你主动安装并使用--engine evolver时涉及,默认 light 后端为 MIT、零依赖零外发。本 Skill 只做三件事:A 任务开始召回已验证修法、B 修复失败后沉淀、C(可选,研究用)受控实验量化收益。日常只用 A/B,C 默认全关,请勿用于生产。
# A — 任务开始,对靶召回(替换成你的任务一句话)
node code/evolver-recall.mjs --query "处理 GBK 编码文件报错" --top 5
# B — 修复了非显而易见的失败后,贴原始报错生成草稿,再补 FIX 落库
node code/light-cli.mjs draft --error "<原始报错>" --tool <工具名> --context "<当时在做什么>"
node code/light-cli.mjs draft --error "<原始报错>" --strategy "AVOID: <什么不该做> FIX: <具体参数/命令/编码>" --commit
命令均在本仓库根目录执行;未安装依赖先见下方「安装」。
首次运行 · 3 步就绪(先跑自检,再沉淀)
- 装 Node ≥22(traps 生成器与 pi/evolver 均要求;见 FAQ·Q8);
- 自检环境:
node code/light-cli.mjs doctor—— 校验 Node 版本、经验库目录可写、命中登记目录可达(失败项给修正指引); - 点亮经验库:空库无修法可召回属正常,按下方流程 B 沉淀第一条修法即点亮。
新手必读(高频问答速览)
- 首次运行召回显示「无可召回修法」? 正常——库从零开始,先跑一次 B 沉淀即可点亮(FAQ·Q1)。
- Node 版本要求? 需 ≥22(traps 生成器还需 Python 3),过低 pi/evolver 会启动失败(FAQ·Q8)。
- 更多问题见
docs/faq.md(完整 14 条)与下方反模式速查。
安装(一次性)
EN: One-time setup. A/B flows need ONLY Node >= 22 — zero npm dependencies. Get the folder by any of three paths below; any location works (a "skill" is just a folder — put it wherever your host expects, e.g.
~/.claude/skills/pi-evox-lab). Default backend = built-in light (pure Node, MIT). evolver is an optional integration (--engine evolver, needsnpm install). Flow C additionally needs Pi CLI + an OpenAI-compatible LLM key.
三种获取路径(任选其一):
# 路径 1:git clone(推荐)
git clone https://github.com/stwhwing/pi-evox-lab.git && cd pi-evox-lab
# 路径 2:受限网络 → Release zip 直下(附 sha256),解压即用
# https://github.com/stwhwing/pi-evox-lab/releases (国内可达镜像见 FAQ Q7)
# 路径 3:市场一键安装 —— skillhub.cn / ClawHub 搜 pi-evox-loop(WorkBuddy/OpenClaw 用户)
node -v # 前置要求:Node >= 22(唯一硬依赖)
node code/light-cli.mjs doctor # 30 秒自检——通过即可用,无需任何安装步骤
- A/B 日常流程零 npm 依赖;以下
npm install仅为可选集成/实验模式 C 准备:
Provider 配置(仅流程 C 需要)
EN: Flow C only - any OpenAI-compatible endpoint;
$ENVinterpolation needs pi >= 0.85.1. Examples + domestic endpoints (DeepSeek/Bailian/SiliconFlow/Zhipu):docs/providers.md.
流程 A:任务开始 — 召回经验(任何非平凡任务)
EN: Flow A - recall at task start.
--querywith the task text does targeted recall (unrelated experience is never injected - injection is gated by signals_match x query-token overlap, below threshold = no injection). On error (T3), the raw error text IS the query. Multiple matches: geneConflicts drops anti_patterns-mutual low scorers; no targeted hit = no injection. Register the hit at task end with--register-hit --gene <id>(id-addressed, concurrency-safe).
# 国内高频场景(中文 Windows 日志 / CSV 默认 GBK,按 utf-8 读必炸)——空库跑 starter 后先试这条最易见效
node code/evolver-recall.mjs --query "读取中文日志报 UnicodeDecodeError" --top 5
# 推荐:带上任务文本做「对靶」召回(与任务无关的经验不会注入)
node code/evolver-recall.mjs --query "<当前任务的一句话/关键信号>" --top 5
# 遇到报错时(T3):报错原文即查询——错误本身就是提醒
node code/evolver-recall.mjs --error "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc4"
- 只输出「已审核 且 通过修法守卫 且 与查询对靶」的编号修法列表(空库有明确提示,属正常);
- 参数默认值:
--top默认 5 条(软提示注入有上下文成本,宁少勿多);经验库无硬性容量上限,但建议单库 <500 条(超过后对靶精度下降,可用共享池分流); - 对靶规则:按基因
signals_match命中与查询词的交集打分,低于阈值即整条不注入(避免不对靶注入反而增加成本); - 多基因冲突时:
geneConflicts守卫已自动剔除anti_patterns互斥的低分项;仍有多条时取分高者;无对靶项时宁可不注入,不用无关基因凑数; - 与本任务相关时优先采用;结束时实际采用了某条,登记命中(
--gene <id>按 id 寻址,并发安全):
node code/evolver-recall.mjs --register-hit --gene <asset_id或gene_id> --note "<任务一句话>"
- 无关的经验不要硬套;未采用的条目不必登记。
流程 B:失败修复后 — 沉淀经验
EN: Flow B - deposit after fixing a non-obvious failure. Deposit bar (any one): docs/2+ tries needed, environment-specific, counter-intuitive error, or second occurrence. Guided path:
draft --errorauto-extracts signals + pre-fills AVOID + writes anti_patterns; fill in FIX then--commit. Manual path:distillwith explicit signals. strategy MUST be an executable fix (params/commands/encodings) - success summaries are filtered by the repair-signal guard.--shareableonly for genes meant for the shared pool. 判定标准(满足任一条即值得沉淀):
- 排查过程需要查文档 / 试错 ≥2 次才解决;
- 依赖本机或环境特性(编码、路径规范、shell 差异、网络环境);
- 报错信息反直觉,或与文档描述不符;
- 同一坑在历史任务中出现过第二次。 (不满足任一条的普通失败不必沉淀——避免经验库噪声。)
推荐路径:引导式(贴原始报错,信号与「负经验」自动抽取)
# 1) 生成草稿:自动抽 signals_match + 预填 AVOID 模板 + 写入 anti_patterns(负经验 token)
node code/light-cli.mjs draft --error "<原始报错文本>" --tool <出错工具名> --context "<你当时在做什么>"
# 2) 照草稿补全 FIX 后落库(--strategy 覆盖预填占位符)
node code/light-cli.mjs draft --error "<原始报错文本>" \
--strategy "AVOID: <什么不该做> FIX: <具体参数/命令/编码>" --commit
# 3) 审核(四语义状态机见下方「审核状态机」单节;approve 自动先跑取证)
node code/light-cli.mjs approve <gene_id>
AVOID/FIX 模板适用边界(写清才不被守卫拒):
| 段 | 写什么 | 边界 |
|---|---|---|
AVOID: | 什么不该做(负经验,可含危险词——那是警告) | 一句到两句;不要写成功总结 |
FIX: | 具体到参数/命令/编码的可执行修法 | 必须真填——占位符/重试日志/旁白会被 depositionGate 拒绝(fail-closed) |
anti_patterns: | 单 token 字面量(如 assume-default-utf8) | 冲突判定按整串匹配,勿写 kebab 长句 |
signals_match: | 召回对靶信号词 | 与查询词有交集才召得回;勿堆无关词 |
备选路径:手写式(已明确 signals 时)
node code/light-cli.mjs distill --category repair --signals bash,exception \
--strategy "<一句话修法;多步用分号分隔;要具体到参数/命令/编码>" \
--summary "<坑的一句话描述>" [--shareable]
- strategy 必须写成可执行修法(含具体参数/命令),不要写成功总结——召回侧有修法守卫,成功总结会被过滤(宁缺毋滥);
--shareable仅当你希望该基因进入共享池时加(默认不共享 = 不外发);- 沉淀门槛的真实数据(诚实边界):生产真实会话中可自动抽取的"干净修法对"密度很低(实测
distillablePairs=0)——本库基因主要来自人工/引导式沉淀。
沉淀质检 depositionGate(0.17.0,fail-closed)
EN: Quality gate at DEPOSITION time (fail-closed): rejects unfilled placeholder / retry-log repetition / narration openings / missing repair-signal words / AVOID-without-FIX. Non-interactive deposits default to quarantined. Full review semantics: the「审核状态机」section below.
distill/draft --commit时逐条检查,不合法直接拒绝(不落盘):
| 拒绝条件 | 理由 | 下一步 |
|---|---|---|
FIX 是未填占位符 <在此填写可执行修法> | 注入后毫无价值 | 在 draft 里补上真实修法再提交 |
retry with corrected args(重试日志复述) | "重试然后好了"不是修法 | 写 AVOID(为何错)+FIX(怎么做) |
| 旁白开场(Now I understand…) | 推理流水不可执行 | 同上 |
| 缺修法信号词 | 不像在描述坑与修法 | 同上 |
| 有 AVOID 无 FIX(半成品) | 只有坑没有修法,注入后毫无价值(0.22 复审实证:3 条截断 deposit 全是此形态) | 补上可执行修法(参数/命令/编码) |
审核状态机(单一事实源 · 0.36 收敛)
基因从入库到可注入的全部审核语义只在这一节维护,其余文档一律指到这里(防多处表述漂移——0.35 评测点名)。 EN: The single source of truth for all review semantics; other docs only point here.
| 场景 | 默认行为 | 覆盖方式 |
|---|---|---|
本地交互式沉淀(draft --commit / distill,有 TTY) | 自动通过 | config --auto-approve off 改人工;仅作用于本地沉淀 |
| 本地非交互沉淀(脚本/cron/管道,无 TTY) | 默认隔离(quarantined) | 显式 --auto-approve 才通过 |
approve <gene_id> | 自动先跑取证——本地四台账(工具错误/召回/注入/回填)三级输出(强证据/弱上下文/无证据),核对一致才批 | --skip-evidence 为已知无证据场景的显式逃生门(不鼓励);结论被后续事件推翻的保持隔离并留痕 |
池导入 gene import / gene pull | official tier 直通(签名验证);community 默认隔离 | --tier 决定 |
- 为什么 approve 绑死取证:0.20.3 建了
evidence命令却依赖"记得跑"——当天审 6 条全部没跑。机制必须绑在动作节点上(T3 哲学:错误本身就是提醒)。 - 状态台账
review.jsonl为 LWW 追加式,approve/quarantine 双向可逆;info的「待审」= 最后状态既非 approved 也非 quarantined。 - 与两层质量门的关系:depositionGate 在入库前拒收(上节),四道守卫在召回侧过滤(下节)——任何一层拒绝都不注入。
- 无本地证据的基因(共享池/其他机器/起步包来源)按内容与来源审核,批准时注明。
EN: Review-with-evidence (0.20.3): before
approve, runevidence <gene_id>to check the four local ledgers for events matching the gene's claimed failure/fix. Approve only when consistent; genes whose conclusions were overturned by later events stay quarantined with an audit note. Genes without local evidence (pool imports / other machines / starter pack) are reviewed on content and source, noted at approval.
基因签名与 provenance(0.21)
EN: Every deposit is signed with this machine's Ed25519 identity (private key 0600, never leaves the machine); pool imports verify signatures - tampered content is REJECTED. Version-by-version details (v2 canonicalization, source attribution, source_kv, decay):
docs/advanced.md§Provenance.
- 沉淀自动签、入池随行、导入验签:内容被篡改 → 拒绝导入;无签名的老基因原样接受(legacy);
- 私钥不出本机;公钥随基因出入池供他机验签——信任模型是「按 keyid 溯源」,不是中心化 CA;
- 溯源字段随 deposit/回填自动记录(
source_model/source_host/source_kv压缩方案族);基因有效性按反馈衰减(时间半衰期 90 天 + 否定压力,地板 0.25,无反馈不衰减)——逐版明细(v2 规范化 / 精确归因 / 相位留痕 / 衰减参数)见docs/advanced.md§Provenance。
部署与分发(0.23)
EN: Download paths, host integration, pool collaboration, concurrency semantics and scoring; version-by-version detail in
docs/advanced.md§Deployment.
- 下载:GitHub Release zip / npm(国内镜像见 FAQ Q7,附 sha256 校验);
- 宿主接入:
light-cli.mjs install <claude-code|cursor|codex|agents-md>(--yes落盘);OpenClaw/Hermes 用install-hooks;触发规程可install-snippet写进任意指令文件; - 基因池协作:
gene pull --pool <URL|命名> --tier official [--scene <场景>](签名验证);gene submit --bundle <file>回传维护者;命名池见~/.evomap/pools.json;贡献条款见 CONTRIBUTING.md(CC-BY-4.0); - 并发语义(三层,完整行为表见
docs/boundary-and-triggers.md§5):单机多会话=withLock 文件锁;跨机=基因池 Git 化(LWW 台账裁定);多宿主按 gene_id 寻址(0.18 起); - 召回打分与阈值(公开数值):signals 命中 +3/个 + 正文 token 交集 +1/个 + 负载均衡偏置 ±2;低于阈值 2 分不注入(不对靶注入比不注入更差,实测 +36pp);分词=ASCII token(≥3 字符)+ 中文 2 字二元词——多字中文短语写进 signals 无效(
fix-signals可体检); - 会话围栏(0.27):
session open "<任务>"一步完成 T1 召回+记账,session close "<结论>"收尾——未配对的 open/close 会被构建门禁拒绝(审计绑定); - 效果量化与回填:
report周报(L1 活性/L2 回填率/L3 复发,--json机读);recall --record "<结论>"回填验证结论;license verify <token>验证 Ed25519 签名许可; - IO 韧性与错误码(0.34):瞬态错误自动重试(3 次/3s)→ 连续 5 次失败熔断 10s(IO 恢复即闭合);全部失败附具名错误码
[E_USAGE]/[E_ARGS]/[E_GUARD]/[E_NOTFOUND]/[E_INTERNAL](保留 0/1/2 退出码)——参数与完整表见docs/advanced.md; - 理论出处:异构验证的问题意识来自 arXiv:2512.05117(详见 README 致谢区与
docs/research.md);逐版明细(溯源/别名触发词/许可/衰减参数)见docs/advanced.md§Deployment。
安全:四道门(0.16.0)
EN: Four gates: repair-signal guard, narration guard, injection guard (malice; AVOID=warning allowed vs FIX=instruction blocked), redaction gate (privacy, fail-closed off-machine). Per-gate details:
docs/security-and-license.md§Gates.
| # | 门 | 管什么 | 在哪生效 |
|---|---|---|---|
| 1 | 修法守卫 | 有没有真修法(无可执行内容 → 不注入;宁缺毋滥) | 召回 |
| 2 | 叙述守卫 | 是不是旁白流水(旁白对智能体是零信息,实测等效噪声 +36pp) | 召回 |
| 3 | 注入守卫 | 是不是恶意指令(提示词注入 → 不注入;对抗"基因反向操纵宿主"的主防线) | 召回(CLI / Pi 扩展桥精简版 / 编排器)+ 导入 + 导出 |
| 4 | 脱敏闸门 | 会不会泄私有内容(IP/路径/密钥 → 拦截不出网) | 导出 + 导入 |
- 降级语义:导出/导入 fail-closed(守卫模块缺失即拒绝执行);召回侧只跳过注入门、其余三门照常(宿主 bootstrap 路径不因守卫失败而阻断使用者——只读不阻断、写入必须 closed)。
- 每道门具体扫什么、命中后的行为、0.31 修复的两个漏检与回归用例:统一见
docs/security-and-license.md§Gates——本文不复述注入触发特征,避免文档自身被扫描器当成样本(本仓有为此发版的先例)。
能力边界速查(什么时候别指望它)
不适用场景 6 类(多机同写一库 / 100% 避坑保证 / 实时同步库 / 一次性任务 / 当权威知识库 / 跨架构直接复用)与量化边界(注入默认 5 条、库规模上限未实测、跨机无分布式锁、Node ≥22)统一见
docs/boundary-and-triggers.md§1–§2。 EN: Capability limits ("when NOT to use") and quantitative bounds:docs/boundary-and-triggers.md§1–§2.
什么时候提醒:五个触发点(0.16.0 的核心设计)
EN: Recall bound to concrete action nodes, never left to memory: T1 task start, T2 before first side-effecting action, T3 on error (the error text IS the query), T4 after fixing, T5 task end (register-hit/negate). Full spec:
docs/boundary-and-triggers.md. 「装了技能但没人调用」是本项目最根本的失效模式——连作者都会忘(实测:相关基因能召回排 #1,却因为动手前没跑召回而重复踩坑)。所以不能指望"用户记得",必须把召回绑死在具体动作节点上。
| # | 触发点 | 时机 | 命令 | 没接会怎样 |
|---|---|---|---|---|
| T1 | 任务开始 | 拿到非平凡任务、规划之前 | recall --query "<任务>" | 预防失效:该避的坑照踩 |
| T2 | 行动前 | 即将执行第一次不可逆动作之前(写文件/提交代码/部署/调外部接口/删改数据);同一任务内同类动作只触发一次,后续沿用本次结论 | 同上(query=将要做的具体动作,如"用脚本批量改写文件") | 贴身预防(可选) |
| T3 | 遇到报错 | 工具返回错误、准备重试之前 | recall --error "<报错原文>" | 最可惜:明明库里就有修法,却盲目重试 |
| T4 | 修好坑后 | 修复了一个不显而易见的坑 | draft --error ...(沉淀) | 经验流失,下台机器再踩 |
| T5 | 任务结束 | 收尾 | --register-hit --gene <id> / --negate --gene <id> | 无法度量,失效修法发现不了 |
T3 单独拎出来(收益最高、却最容易被忽略):唯一「不用你记得」的触发点——报错本身就是提醒。工具返回错误、准备重试之前,把报错原文直接当查询(不要自己概括):node code/evolver-recall.mjs --error "<报错原文>";命中后按修法重试,仍失败 → 走 T4 沉淀。
完整触发规格统一见
docs/boundary-and-triggers.md——含 T2 判定口径与 3 个例子、多宿主并发矩阵、触发词↔命令映射、三类宿主接入方式、国内镜像、「装了没生效」自检。本文件只保留上面这张核心表,两处不再各自漂移。 触发词只是调用提示,不是召回匹配机制(命中靠signals_match × query-token对靶);任务开始只要判定为"非平凡"就走 T1,不需措辞命中任何一组。
常见错误用法(反模式速查)
EN: Anti-pattern quick list - each row explains the MECHANISM, not just the symptom. Full 14-item catalog with [A] evidence:
docs/common-mistakes.md. Key ones: success-summary strategies are noise (+36pp worse than nothing), model-may-fail traps have unreliable hit rates, token deltas need a no-injection control group (~-22% repeat-execution baseline), error counting must use authoritative flags (isError=true), cold start needs flow-B deposits first. 每条附「为什么会错」——讲机制而非现象。完整清单(含更多条目)见docs/common-mistakes.md。
| 错误做法 | 为什么会错(机制) | 正确做法 |
|---|---|---|
沉淀成功总结 (workaround: use --no-ansi) | 修法守卫骨干词检测:成功总结缺少"改什么"的可执行指令 → 不注入(实测 +36pp 不如不注入) | 写 AVOID: 直接输含 ANSI 转义的命令 FIX: 加 --no-ansi |
| 把整段报错当 signals 写进 FIX | 守卫对"没写修法"的捕获:注入后等于没修 → 召回侧零收益;占位符被 depositionGate 拒绝 | 报错写在 --error、signals 只写那类信号的 1-2 个词 |
| 手写 signals 时抄整段报错词 | 召回打分用交集(query-token × signals_match 对靶)→ signals 越长、召回越窄,反而不如信号词精炼。实测 signals 写 40 字 vs 3 字时召回率 -47% | signals 每个用 1-2 个高信息词(gbk utf-8 编码);多义词用 or |
滥用 --shareable | 共享池内的基因默认开对靶、缺本地脱敏 → 可能泄露隐私 / 违规内容 | 只对经验证环境无关的修法加 --shareable;路径/密钥相关坚决不共享 |
| 任务开始时不先跑召回就直接开始 | T1 是整个 design 的预防杠杆——错过了就是错过了。作者本人都忘了(见 T3 注) | 拿到非平凡任务立即 recall --query "<任务>";养成肌肉记忆 |
已知问题 / 版本边界 (from docs)
EN: Known issues / version boundaries: see
docs/boundary-and-triggers.md§6 +CHANGELOG.md.
- Node 22 required: traps 生成器与之兼容的 pi/evolver 要求,低于此版本不能用(#L8 自检命令会报错);
- 多机无分布式锁:共写一库在并发写时可能产生冲突(
withLock按目录锁,仅限单机);跨机协作推荐基因池 Git 工作流(LWW 台账); - 库上限建议 <500:超过后召回对靶精度可能下降(理论 N 增长→信号空间密度上升→假阳上升);大规模用例建议共享池分流;
- 中文多字短语浪费:召回分词按 ASCII token(≥3 字符)+ 中文 2 字二元词——多字中文短语写进 signals 无效 #118;
- 审核本需主动 approve:自动审核默认 TTY 直接通过,非交互沉淀默认隔离(符合 fail-closed 设计);忘记 approve 的基因虽在库中但不会被召回;
- traps 生成器需 Python 3(语言无关强依赖)。
导航
| 链接 | 谁该读 | 内容 |
|---|---|---|
examples/quickstart.md | 新用户首选(5 分钟闭环) | 一次完整的 A→B 闭环 demo |
docs/overview.md | 想全面了解 | 项目概览、设计哲学、与传统方案对比 |
本文档(docs/skill.md) | 日常查 | 触发点、安全摘要、反模式速查、快速用例 |
docs/boundary-and-triggers.md | 部署/集成/系统调用 | 完整触发表、并发语义、宿主部署、触发词映射能力边界、"装了没生效"自检、国内镜像 |
docs/common-mistakes.md | 想用好但总遇到问题 | 14 条反模式完整清单(每条附机制解释 + 实证) |
docs/config-errors.md | 配置或命令报错 | 常见配置错误与解决步骤 |
docs/faq.md | 跑不通 / 有疑问 | 完整 14 条 FAQ(含 Node 版本、中文分词、空库、性能、traps 生成器等) |
docs/advanced.md | 深入了解 / 调试 / 研究 | 回填寻址、时间线、harvest、基石并发锁、共享库、宿主接入细节、运维、安全门明细、衰减参数、v2 溯源 |
docs/security-and-license.md | 安全审核/合规 | 四道门的详细检测规则、漏检修复记录、许可文本(MIT/GPL-3.0 分离) |
docs/providers.md | 流程 C(实验) | 国内外 Provider 配置示例(含国内镜像) |
docs/research.md | 仅研究用户 | 流程 C 细粒度受控实验、陷阱设计纪律、模型操作测量;大多数用户无需要读 |
README.md | 项目入口 | 一句话简介、状态徽章、致谢、引用 |
CHANGELOG.md | 更新跟踪 | 版本发布说明 |