ECC 的 /instinct-import 命令深度解析把外部本能安全导入 continuous-learning-v2 系统【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC导读/instinct-import是 ECCagent harness performance optimization system中 continuous-learning-v2 技能体系的核心命令之一用于将外部来源的 instincts本能即带置信度的小型经验规则导入本地学习存储实现团队之间、项目之间以及不同 agent harnessClaude Code、Codex、Opencode 等之间的经验共享。读完本文你将掌握该命令支持的三种导入源、导入文件格式、五步导入流水线与冲突合并策略并能结合仓库内instinct-cli.py的真实实现理解其去重、置信度过滤、SSRF 防护等底层原理。一、定位instinct 是什么为什么要 import在 continuous-learning-v2 的设计中一个instinct是一条原子化、置信度加权的小型经验行为例如 when writing new functions, prefer functional style。它在结构上是一个带 YAML frontmatter 的文本块包含id、trigger触发情境、confidence置信度 0.3–0.9、domain领域标签以及正文中的## Action等段落。其完整数据模型与学习流水线见 SKILL.md。本系统的学习数据被划分为两类目录personal/由 hook 自动观测会话后沉淀的自学本能inherited/通过/instinct-import从外部导入的继承本能。import的价值在于你不用重复踩坑才能沉淀经验。团队某个成员已经通过观测总结出了use-zod-validation这类高质量本能其他人直接 import 即可获得同样的行为约束——这正是 v2.0 引入的 Sharing: Export/import instincts 能力见 SKILL.md 中 v1/v2 对比表。命令在 Opencode 集成中的注册信息可见 opencode.jsoncommand.instinct-import条目它把 instinct-import.md 作为模板下发给 build agent 执行。二、命令形态与三种导入源命令由 build agent 执行参数经$ARGUMENTS注入三种调用方式如下。1. 本地文件导入File Import/instinct-import path/to/instincts.json导入本地文件路径适合接收同事通过/instinct-export导出的结果文件。2. 远程 URL 导入URL Import/instinct-import https://example.com/instincts.json从 HTTP(S) URL 直接拉取适合从公开的 instinct registry / 团队内部制品地址同步。3. 团队共享导入Team Share Import/instinct-import teammate/instincts以teammate风格引用另一位成员共享的经验集适合团队协作场景。需要说明上述三种形态与命令文档中的概念一致。在仓库中面向Claude Code的命令定义 commands/instinct-import.md 给出了等价的底层调用方式即直接运行 Python CLI见后文第六节两者最终都汇入同一条导入引擎。三、导入文件格式3.1 命令文档约定的 JSON 载荷结构命令约定导入文件期望的 JSON 结构如下见 .opencode/commands/instinct-import.md{ instincts: [ { trigger: [situation description], action: [recommended action], confidence: 0.7, category: coding, source: imported } ], metadata: { version: 1.0, exported: 2025-01-15T10:00:00Z, author: username } }字段含义字段说明instincts[].trigger触发情境描述决定该本能何时生效instincts[].action建议采取的行为instincts[].confidence置信度用于导入时的排序与冲突仲裁instincts[].category领域分类如 coding / testinginstincts[].source来源标记导入时为importedmetadata文件级元信息格式版本、导出时间、作者3.2 落盘存储的实际 YAML 本能格式导入完成后数据以 YAML 文件形式存入inherited/目录。仓库的解析引擎 instinct-cli.py 中parse_instinct_file()L516-L567用一对---分隔多条本能只保留含id的条目无 id 的记录被静默丢弃测试见 test_parse_instinct.py 中test_parse_no_id_skipped。一条真实的导入本能由导入引擎写出长这样--- id: use-zod-validation trigger: when validating api payloads confidence: 0.7 domain: coding source: inherited scope: project imported_from: team-instincts.yaml project_id: a1b2c3d4e5f6 project_name: my-project --- ## Action Use zod schemas to validate all API request payloads. ## Evidence Imported from team instinct library.其中trigger、imported_from等在写出时会经_yaml_quote()L238-L245做双引号转义避免值内嵌引号破坏 YAML 结构。四、五步导入流水线对照源码命令文档将导入过程定义为五个阶段下面逐一对齐仓库实现cmd_import()instinct-cli.py L886-L1068验证。1. Validate format —— 校验格式先按来源类型获取内容URL 来源经_validate_import_url()L189-L218校验必须是https、必须含主机名、解析出的 IP 必须为公网地址拒绝私网 / 回环 / 链路本地 / 组播 / 保留地址再经_fetch_import_url()L221-L235拉取附加 2MB 大小上限、15 秒超时、Content-Type 白名单text/、markdown、yaml、json、octet-stream与自定义 User-Agent。本地文件来源经_validate_file_path()L149-L173解析并做路径穿越防护——禁止指向/etc、/usr、/bin、/proc、/var/...等系统目录。随后调用parse_instinct_file()解析。若解析结果为空则直接报No valid instincts found in source.。2. Deduplicate —— 去重去重分两层源码见 L935-L960源文件内部去重同一 id 出现多条时保留置信度最高者与本地已有本能比对按目标 scope只比较同一 scope 内的已有本能避免跨 scope 互相遮蔽加载现有本能集合existing_ids将待导入条目分成三类to_add本地不存在的新本能to_update本地已有但导入版本置信度更高duplicates本地已有且置信度不低于导入版本跳过。3. Adjust confidence —— 置信度过滤与仲裁命令文档提出的思路是对导入本能适当调低信任度在仓库的引擎实现中等价机制是通过--min-confidence n阈值做过滤L962-L965只保留置信度 ≥ 阈值的条目进入新增/更新集合。这与 continuous-learning-v2 的置信度语义一致0.3 试探 → 0.9 近乎确定见 SKILL.md 置信度表帮助你把来路不明的低置信经验挡在门外。4. Merge —— 合并写入本地本能库无--dry-run且无--force时先打印冲突分析并请求交互确认Import N new, update M? [y/N]L993-L998。确认后按目标 scope 确定输出目录project的instincts/inherited/或全局instincts/inherited/文件名形如source-yyyyMMdd-HHmmss.yaml。先写新文件、后删旧文件更新条目会先定位 scope 内personal/或inherited/中的旧文件限定在 scope 根目录内防止跨 scope 误删待新文件写入成功后再清理避免中途失败导致数据丢失L1008-L1060。文件头会写入注释# Imported from source、# Date、# Scope以及 project 维度信息保证来源可追溯。5. Report —— 输出导入摘要最后输出导入完成信息见命令文档 instinct-import.md 的 Import Report 章节以及引擎实现的收尾输出典型形态如下Import Summary Source: [path or URL] Total in file: X Imported: Y Skipped (duplicates): Z Errors: W Imported Instincts: - [trigger] (confidence: 0.XX) - [trigger] (confidence: 0.XX) ...引擎侧的真实输出在导入前会分三组明细展示NEW (n)、UPDATE (n)、SKIP (n)重复项较多时只显示前 5 条并提示... and N more。五、冲突解决策略当导入与本地本能发生 id 冲突时命令文档规定了明确的仲裁规则也与引擎实现一一对应场景文档规则引擎行为L950-L960导入版本置信度更高保留更高置信度版本进入to_update成为更新候选需用户确认除非--force导入版本置信度相等或更低跳过保留本地进入duplicates不写入本地不存在作为新本能添加进入to_add同时文档提到合并应用计数并更新时间戳——在实现中更新的本质是原子替换新文件携带新的时间戳命名写入inherited/同时删除旧文件因此状态栏里的计数与时间戳都会自然推进。导入前若使用--dry-run则可无副作用预览本次将新增 X 条、更新 Y 条。一个典型冲突预览来自 commands/instinct-import.mdWARNING: prefer-functional-style Local: 0.8 confidence, 12 observations Import: 0.7 confidence → Keep local (higher confidence) WARNING: test-first-workflow Local: 0.75 confidence Import: 0.9 confidence → Update to import (higher confidence)六、Scope 控制、命令行参数与来源追踪6.1 底层 CLI 调用方式Claude Code / 手动安装场景下可绕过斜杠命令直接调用引擎见 commands/instinct-import.mdpython3 ${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py import file-or-url [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]未安装为插件无CLAUDE_PLUGIN_ROOT时使用python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import file-or-url命令行参数在 argparse 中的正式定义见 instinct-cli.py L2216-L2223参数说明source必填位置参数本地文件路径或 URL--dry-run仅预览不写入--force跳过交互确认--min-confidence n置信度下限阈值--scope project\|global目标作用域默认project6.2 作用域降级与目标目录导入目标作用域决定数据落点。引擎在 L891-L895 做了一次重要降级若用户选择project作用域但当前环境检测不到任何项目git 仓库 / 显式 env则自动降级为 global 作用域并提示No project detected. Importing as global scope.。两种作用域对应的继承目录项目作用域~/.claude/homunculus/projects/project-id/instincts/inherited/v2.1 起默认迁移至 XDG 目录见 6.3全局作用域~/.claude/homunculus/instincts/inherited/。在运行时加载层面项目作用域本能优先于全局本能同 id 冲突时项目版本胜出见 load_all_instincts() L693-L725 及测试test_load_all_project_overrides_global。6.3 数据目录解析continuous-learning-v2 将观察数据存储在 homunculus 目录下解析顺序见_resolve_homunculus_dir()L54-L67CLV2_HOMUNCULUS_DIR须为绝对路径覆盖$XDG_DATA_HOME/ecc-homunculus兜底$HOME/.local/share/ecc-homunculus。旧版本数据位于~/.claude/homunculus/可用仓库提供的迁移脚本 migrate-homunculus.sh 一次性迁移CLI 在cmd_status()中也会检测遗留数据并给出迁移提示。6.4 来源追踪字段为确保继承本能可审计导入的每条本能都会被打上来源标记。命令文档与 commands/instinct-import.md 的 Source Tracking 章节给出如下字段引擎在写出时逐条写入L1036-L1051source: inherited scope: project imported_from: team-instincts.yaml project_id: a1b2c3d4e5f6 project_name: my-project项目 id 由 git remote URL或仓库路径经 SHA-256 取前 12 位哈希生成_project_hashL112-L113同名远端仓库在不同机器上会得到相同 id便于团队同步。projects.json注册表则把哈希映射回可读的项目名与路径见 SKILL.md 的文件结构图。七、导入结果复核与后续演进命令文档在结尾给出了重要提示导入完成后用/instinct-status复核TIP 章节。PASS: Import complete! Added: 8 instincts Updated: 1 instinct Skipped: 3 instincts (equal/higher confidence already exists) New instincts saved to: ~/.claude/homunculus/instincts/inherited/ Run /instinct-status to see all instincts.复核与后续处理通常构成完整闭环/instinct-status查看项目 全局本能的置信度条与触发条件命令定义见 instinct-status.md其底层同样调用instinct-cli.py status/evolve把足够多的相关本能聚类成技能 / 命令 / agent/promote将在 2 个项目中出现且平均置信度 ≥ 0.8 的项目本能提升为全局本能/instinct-export把高质量本能导出为共享文件建议仅导出 0.8 高置信度条目见 instinct-export.md与 import 形成双向循环。八、安全与健壮性设计源码级远程导入天然具备攻击面引擎给出了成体系的防护值得作为同类导入功能的设计参考仅允许 HTTPS_validate_import_url直接拒绝明文 HTTP对应测试test_validate_import_url_rejects_httpSSRF 防护对解析出的每个 IP 做私网 / 回环 / 链路本地 / 组播地址检查测试test_validate_import_url_rejects_private_hosts用 127.0.0.1 验证拒绝公网 IP 正常放行响应体约束2MB 大小上限 Content-Type 白名单防止恶意大文件或非文本载荷路径穿越防护本地路径禁止指向系统目录/etc、/var/log等并有专门测试覆盖test_validate_rejects_etc等见 test_parse_instinct.py原子写入先写新文件再删旧文件、注册表与目录写操作在支持平台走fcntl文件锁_registry_lockL408-L428避免并发会话互相踩踏。此外导入只写入inherited/目录、绝不触碰自动学习产生的personal/从机制上保证了外部输入与自身沉淀的清晰边界任何一条导入本能都可通过imported_from字段回溯其出处。九、总结/instinct-import是 ECC continuous-learning-v2 经验共享闭环中的关键一环它把文件、URL、团队成员三种外部来源的经验经过格式校验 → 去重 → 置信度过滤 → 冲突仲裁 → 原子合并五步流水线安全地沉淀为本地的继承本能并通过source、scope、imported_from等字段保持全程可审计。配合/instinct-export、/evolve、/promote、/instinct-status形成完整的导出—共享—导入—聚类—晋升知识循环让团队经验随项目流动、随实践增值。想深入原理的读者建议按以下路径继续研读仓库先读命令规格 .opencode/commands/instinct-import.md 与其 Claude Code 变体 commands/instinct-import.md再通读核心实现 instinct-cli.py 的cmd_import与校验函数最后用 test_parse_instinct.py 中的解析、路径校验、URL 校验测试验证上述全部行为并以 SKILL.md 作为整体架构参照。中文译版可对照 docs/zh-CN/commands/instinct-import.md。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考