🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
homunculus-code
Advanced tools
homunculus-code - npm Package Compare versions
| name: Bug Report | ||
| description: Something isn't working as expected | ||
| labels: ["bug"] | ||
| body: | ||
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Thanks for reporting! Please fill in the details below. | ||
| - type: input | ||
| id: version | ||
| attributes: | ||
| label: Homunculus version | ||
| description: "Run `cat homunculus/.manifest.json | head -1` or check package.json" | ||
| placeholder: "e.g. 0.9.0" | ||
| validations: | ||
| required: true | ||
| - type: input | ||
| id: claude-code-version | ||
| attributes: | ||
| label: Claude Code version | ||
| placeholder: "e.g. v2.1.85" | ||
| validations: | ||
| required: true | ||
| - type: dropdown | ||
| id: os | ||
| attributes: | ||
| label: Operating System | ||
| options: | ||
| - macOS | ||
| - Linux | ||
| - Windows (WSL) | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: description | ||
| attributes: | ||
| label: What happened? | ||
| description: Describe the bug clearly. Include error messages if any. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: expected | ||
| attributes: | ||
| label: What did you expect? | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: reproduce | ||
| attributes: | ||
| label: Steps to reproduce | ||
| description: How can we reproduce this? | ||
| placeholder: | | ||
| 1. Run `npx homunculus-code init` | ||
| 2. Run `/hm-night` | ||
| 3. See error... | ||
| - type: textarea | ||
| id: logs | ||
| attributes: | ||
| label: Relevant logs | ||
| description: Paste any relevant log output | ||
| render: shell |
| blank_issues_enabled: true | ||
| contact_links: | ||
| - name: Questions & Discussion | ||
| url: https://github.com/JavanC/Homunculus/discussions | ||
| about: Ask questions or share your evolution results |
| name: Feature Request | ||
| description: Suggest a new feature or improvement | ||
| labels: ["enhancement"] | ||
| body: | ||
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Have an idea to make Homunculus better? We'd love to hear it! | ||
| - type: textarea | ||
| id: problem | ||
| attributes: | ||
| label: What problem does this solve? | ||
| description: Describe the use case or pain point | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: solution | ||
| attributes: | ||
| label: Proposed solution | ||
| description: How do you think this should work? | ||
| validations: | ||
| required: true | ||
| - type: dropdown | ||
| id: area | ||
| attributes: | ||
| label: Which area? | ||
| options: | ||
| - Goal tree / architecture.yaml | ||
| - Instinct extraction | ||
| - Skill evolution / eval | ||
| - Nightly agent | ||
| - Init / upgrade CLI | ||
| - Documentation | ||
| - Other | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: alternatives | ||
| attributes: | ||
| label: Alternatives considered | ||
| description: Any other approaches you've thought about? |
| **语言：** [English](../../README.md) | [繁體中文](../zh-TW/README.md) | [简体中文](README.md) | ||
| # Homunculus for Claude Code | ||
| [](https://www.npmjs.com/package/homunculus-code) | ||
| [](https://opensource.org/licenses/MIT) | ||
| [](https://docs.anthropic.com/en/docs/claude-code) | ||
| [](https://nodejs.org) | ||
| **别再调教你的 AI。让它自己进化。** | ||
| <p align="center"> | ||
| <img src="https://github.com/user-attachments/assets/b3ce6017-02de-44a4-a3c6-8d45765c1693" alt="Homunculus Demo — goal setup + evolution cycle in 60 seconds" width="700"> | ||
| </p> | ||
| 你花了大量时间调整 prompt、编写规则、研究新功能、配置工具。Homunculus 颠覆了这个模式：定义你的目标，系统自己进化——skill、agent、hook、script，一切——而你只需专注于实际工作。 | ||
| ```bash | ||
| npx homunculus-code init | ||
| ``` | ||
| 一条命令。定义你的目标。你的助手开始进化。 | ||
| > **实际验证：** 一位开发者运行了这个系统 5 周。它自动生成了 229 个行为模式，汇聚成 10 个经过测试的 skill，创建了 4 个专业 agent、18 个命令和 37 个自动化脚本。夜间 agent 进行了 1,500+ 次自主 commit——在开发者睡觉时持续改进系统。[查看成果 →](#实际成果) | ||
| --- | ||
| ## 为什么需要它 | ||
| 每个 Claude Code 资深用户都会遇到同样的瓶颈： | ||
| ``` | ||
| 第 1 周：「Claude 太棒了！」 | ||
| 第 2 周：「让我加一些规则和 hook...」 | ||
| 第 3 周：「我需要 skill、agent、MCP server、自定义命令...」 | ||
| 第 4 周：「我花在配置 Claude 上的时间比实际使用还多。」 | ||
| ``` | ||
| 听起来很熟悉？即使是 [OpenClaw](https://github.com/openclaw/openclaw)——拥有 300K+ star 和自扩展能力——仍然需要*你*来决定改进什么、何时改进、以及改进是否有效。编辑 `SOUL.md`、调整 `AGENTS.md`、搞坏了什么、再开一个 AI session 来修复。AI 可以扩展自己，但它无法设定自己的方向或验证自己的质量。 | ||
| **关键区别在于：** | ||
| ``` | ||
| Without Homunculus: With Homunculus: | ||
| You notice tests keep failing Goal tree detects test_pass_rate dropped | ||
| → You research testing patterns → Nightly agent auto-evolves tdd skill | ||
| → You write a pre-commit skill → Eval confirms 100% pass | ||
| → You test it manually → Morning report: "Fixed. Here's what changed." | ||
| → It breaks after a Claude update → Next update? System re-evaluates and adapts | ||
| → You fix it again... → You slept through all of this | ||
| ``` | ||
| --- | ||
| ## 核心理念：目标树 | ||
| 大多数 AI 工具只做局部优化——「你做了 X，所以我记住 X。」Homunculus 做**全局**优化——朝你在树中定义的目标前进： | ||
| ``` | ||
| 🎯 my-project | ||
| ├── code_quality — Ship fewer bugs | ||
| │ ├── testing — Maintain test coverage | ||
| │ │ └── realized_by: jest.config.js, tests/ (42 tests) ✓ | ||
| │ └── linting — Consistent code style | ||
| │ └── realized_by: .eslintrc.js, .prettierrc ✓ | ||
| ├── speed — Move faster | ||
| │ └── deploy_automation — One-command deploys | ||
| │ └── realized_by: # will evolve ○ | ||
| └── knowledge — Learn and remember | ||
| ├── research — Discover better approaches | ||
| │ └── realized_by: nightly agent ✓ | ||
| └── memory — Remember what matters | ||
| └── realized_by: homunculus/instincts/ ✓ | ||
| ``` | ||
| 每个节点定义了**为什么**存在、**如何**衡量、以及**什么**在当前实现它。**目标是稳定的。实现会进化。** 系统自动将每个行为路由到最优机制——实现被替换和升级，而目标保持不变。 | ||
| <details> | ||
| <summary>📖 <code>architecture.yaml</code> 中的目标节点长什么样？</summary> | ||
| ```yaml | ||
| # architecture.yaml — from the reference system | ||
| autonomous_action: | ||
| purpose: "Act without waiting for human commands" | ||
| goals: | ||
| nightly_research: | ||
| purpose: "Discover better approaches while developer sleeps" | ||
| realized_by: heartbeat/heartbeat.sh # a shell script | ||
| health_check: | ||
| command: "test $(find logs/ -mtime -1 | wc -l) -gt 0" | ||
| expected: "nightly agent ran in last 24h" | ||
| task_management: | ||
| purpose: "Track and complete tasks autonomously" | ||
| realized_by: quest-board/server.js # a web app | ||
| metrics: | ||
| - name: forge_completion_rate | ||
| healthy: "> 70%" | ||
| continuous_evolution: | ||
| purpose: "Improve over time without human intervention" | ||
| goals: | ||
| pattern_extraction: | ||
| purpose: "Learn from every session" | ||
| realized_by: homunculus/scripts/evaluate-session.js | ||
| skill_aggregation: | ||
| purpose: "Converge patterns into tested skills" | ||
| realized_by: homunculus/evolved/skills/ | ||
| ``` | ||
| `realized_by` 字段可以指向**任何东西**： | ||
| | 类型 | 示例 | 适用场景 | | ||
| |------|---------|-------------| | ||
| | Skill | `skills/tdd-workflow.md` | 行为知识 | | ||
| | Agent | `agents/code-reviewer.md` | 专业化 AI 子代理 | | ||
| | Hook | `hooks/pre-commit.sh` | 自动化触发器 | | ||
| | Script | `scripts/deploy.sh` | Shell 自动化 | | ||
| | Cron | `launchd/nightly-check.plist` | 定时任务 | | ||
| | MCP | `mcp-servers/github` | 外部集成 | | ||
| | Rule | `rules/security.md` | Claude Code 行为规则 | | ||
| | Command | `commands/quality-gate.md` | Slash command 工作流 | | ||
| </details> | ||
| --- | ||
| ## 进化机制 | ||
| ``` | ||
| You use Claude Code normally | ||
| │ | ||
| ┌──────────┼──────────┐ | ||
| │ │ │ | ||
| Observe Health Check Research | ||
| (hooks) (goal tree) (nightly) | ||
| │ │ │ | ||
| └──────────┼──────────┘ | ||
| │ | ||
| ▼ | ||
| ┌────────────┐ | ||
| │ Evolve │ Goals stay the same. | ||
| │ ──────── │ Implementations get better. | ||
| │ Extract │ | ||
| │ Converge │ | ||
| │ Eval │ | ||
| │ Replace │ | ||
| └────────────┘ | ||
| ``` | ||
| **三个输入，一个引擎：** | ||
| 1. **观察** — hook 监控你的工具使用，将重复模式提取为「instinct」 | ||
| 2. **健康检查** — 目标树识别哪些目标不健康 → 聚焦于此 | ||
| 3. **研究** — 夜间 agent 扫描更好的方法并提出实验 | ||
| 进化引擎随后： | ||
| - 提取行为模式 → **instinct**（标记最佳机制 + 目标路径） | ||
| - 将每个 instinct 路由到最优机制 → **hook、rule、skill、script、agent 或 system** | ||
| - 对于 skill：**eval → improve 循环**直到 100% 通过率 | ||
| - 每晚审查所有目标 → 当前机制是否仍是最优选择？ | ||
| - Instinct 实现后归档 → 机制本身成为事实来源 | ||
| --- | ||
| ## 更新日志 | ||
| ### v0.9.0 — 进化引擎升级 (Mar 2026) | ||
| - **智能观察** — `observe.sh` 现在过滤噪音（跳过 Read/Glob/Grep，写入操作只记录 post-phase）并追踪引用频率——哪些 instinct 和 skill 实际被读取 | ||
| - **三层提取** — `evaluate-session.js` 现在一次性提取 instinct + 记忆建议 + 研究主题。记忆和研究写入 `homunculus/reports/` 供你审查（非侵入式） | ||
| - **语义去重** — 新 instinct 可以声明 `supersedes` 来自动归档它所替代的旧 instinct | ||
| - **写入门控** — 提取 prompt 现在包含质量标准（必须改变未来行为、记录承诺或保存决策依据） | ||
| - **动态每日上限** — Instinct 提取限制随 session 大小缩放（短 session 1 个，长 session 最多 5 个） | ||
| - **更智能的修剪** — `prune-instincts.js` 现在使用引用频率评分（常用 +25，从未引用 -15）、3 级 skill 覆盖检测（直接演化 / 高重叠 / 部分覆盖）、14 天宽限期后才开始信心衰减、以及高风险警告 | ||
| - **幂等性** — 提取追踪扫描状态以避免重复处理相同的观察 | ||
| - **`--json` 输出** — `prune-instincts.js` 支持 `--json` 用于程序化调用 | ||
| ### v0.8.0 — 升级机制 (Mar 2026) | ||
| - **`homunculus-code upgrade`** — 新命令，升级 npm 包后更新托管文件。核心脚本（observe.sh 等）自动替换并备份为 `.bak`；命令和规则仅在你未自定义时才替换——否则写入 `.new` 文件供手动合并 | ||
| - **安装清单** — `init` 现在生成 `homunculus/.manifest.json`，追踪所有托管文件的 SHA256 哈希，实现安全的差异感知升级 | ||
| ### v0.7.0 — 非侵入式安装 & 主动性设计指南 (Mar 2026) | ||
| - **非侵入式安装** — 脚本现在位于 `homunculus/scripts/` 而非项目根目录 `scripts/`，避免与现有项目工具冲突 | ||
| - **安全命令安装** — Slash command 逐文件安装；已有命令以警告方式保留而非覆盖 | ||
| - **Hook 合并** — 如果 `.claude/settings.json` 中已存在 `PostToolUse` hook，观察 hook 会合并到数组中而非跳过整个设置 | ||
| - **主动性设计指南** — 新增 [docs/proactivity.md](../proactivity.md)，涵盖主动式 AI 助手的三个核心概念：Memory Flush、Research Queue 和 Periodic Heartbeat | ||
| ### v0.6.3 — 项目感知目标 & 进化层级 (Mar 2026) | ||
| - **项目扫描** — `/hm-goal` 现在在提问前检测你的技术栈、测试、CI 和目录结构。目标树预填你已有的内容 | ||
| - **通用机制路由** — `/evolve` 将 instinct 路由到最佳机制（hook、rule、skill、script、agent），而不仅仅是 skill | ||
| - **进化强度层级** — 在 `evolution-config.yaml` 中配置 `minimal` / `standard` / `full`，控制深度、频率和成本 | ||
| - **夜间 agent 设置** — 首次 `/hm-night` 运行时正确提供自动夜间进化配置 | ||
| ### v0.5.0 — 初始版本 (Mar 2026) | ||
| - **目标树** — 在 `architecture.yaml` 中定义你想要的 | ||
| - **观察 hook** — 自动捕获 session 中的行为模式 | ||
| - **夜间进化** — `/hm-night` 运行健康检查、提取 instinct、演化 skill 并生成报告 | ||
| - **6 个 slash command** — `/hm-goal`、`/hm-night`、`/hm-status`、`/evolve`、`/eval-skill`、`/improve-skill` | ||
| --- | ||
| ## 快速开始 | ||
| ### 1. 安装 | ||
| 在你的项目目录中运行（`CLAUDE.md` 或 `.claude/` 所在位置）： | ||
| ```bash | ||
| npx homunculus-code init | ||
| ``` | ||
| ``` | ||
| Homunculus — Self-evolving AI Assistant | ||
| ✓ Created homunculus/ directory structure | ||
| ✓ Added evolution rules | ||
| ✓ Copied evolution scripts | ||
| ✓ Added slash commands (/hm-goal, /hm-night, /hm-status) | ||
| ✓ Configured observation hook | ||
| Done! Homunculus is installed. | ||
| Next steps: | ||
| 1. Run claude to open Claude Code | ||
| 2. Type /hm-goal to define your goals (AI-guided) | ||
| 3. Type /hm-night to run your first evolution cycle | ||
| ``` | ||
| ### 2. 定义你的目标 | ||
| 打开 Claude Code 并输入 `/hm-goal`。Claude 会先扫描你的项目，然后根据发现的内容提出针对性问题： | ||
| ``` | ||
| > /hm-goal | ||
| Claude: I see a Next.js + TypeScript project with 42 Jest tests | ||
| and GitHub Actions CI. What's the main purpose of this project? | ||
| You: A SaaS dashboard for analytics | ||
| Claude: You have 42 tests already. Is test coverage a pain point, | ||
| or is something else slowing you down more? | ||
| You: Deployment is manual and error-prone | ||
| Claude: If your AI could fix one thing overnight, what would it be? | ||
| You: Automated deployment with proper checks | ||
| Claude: Here's your goal tree: | ||
| 🎯 analytics-dashboard | ||
| ├── code_quality — Ship fewer bugs | ||
| │ ├── testing — Maintain test coverage | ||
| │ │ └── realized_by: jest.config.js, tests/ (42 tests) ✓ | ||
| │ └── linting — Consistent code style | ||
| │ └── realized_by: .eslintrc.js, .prettierrc ✓ | ||
| ├── deployment — Reliable releases | ||
| │ └── ci_pipeline — Automated checks on every PR | ||
| │ └── realized_by: .github/workflows/ ✓ | ||
| └── productivity — Move faster | ||
| └── deploy_automation — One-command deploys | ||
| └── realized_by: # will evolve ○ | ||
| 4 goals: 3 already have implementations (✓), 1 will evolve (○) | ||
| Does this look right? | ||
| You: Great! | ||
| Claude: ✅ architecture.yaml created with 4 goals! | ||
| ``` | ||
| 对于没有现有文件的新项目，Claude 会退回到关于项目类型和目标的通用问题。 | ||
| ### 3. 运行你的第一个进化周期 | ||
| ``` | ||
| > /hm-night | ||
| ``` | ||
| 观看 Claude 检查你的目标、将 instinct 路由到正确的机制（hook/rule/skill/script/agent）、评估和改进实现、并生成报告——全在一个命令中完成。这就是夜间 agent 在你睡觉时自主执行的操作。 | ||
| ### 4. 升级 | ||
| 新版本发布后，更新你的托管文件： | ||
| ```bash | ||
| npx homunculus-code@latest upgrade | ||
| ``` | ||
| - **核心脚本** → 自动替换（备份保存为 `.bak`） | ||
| - **你未修改的命令/规则** → 自动替换 | ||
| - **你已自定义的命令/规则** → 跳过，新版本保存为 `.new` 供你手动合并 | ||
| ### 5. 继续使用 Claude Code | ||
| 观察 hook 自动监控你的使用情况。随着模式出现，instinct 被提取并路由到正确的机制： | ||
| ``` | ||
| /hm-goal 定义或优化你的目标 | ||
| /hm-night 运行完整进化周期（可手动运行，但最好设为夜间 agent） | ||
| /hm-status 查看进化进度 | ||
| ``` | ||
| `/hm-night` 执行完整的进化流水线：将 instinct 路由到最佳机制（hook/rule/skill/script/agent）、对 skill 运行 eval + improve、审查目标健康度、并生成报告。你可以随时手动运行，但真正的威力在于让它每晚自主运行。 | ||
| > 第一次运行 `/hm-night` 时，它会询问你是否要设置夜间 agent 以实现自动夜间进化。 | ||
| --- | ||
| ## 关键概念 | ||
| ### 目标树（`architecture.yaml`） | ||
| 中枢神经系统。每个目标都有 purpose、metrics 和健康检查。进化系统读取它来决定**改进什么**以及**如何衡量成功**。 | ||
| ### Instinct | ||
| 从你的使用中自动提取的小型行为模式。每个 instinct 标记有： | ||
| - **置信度分数** — 随强化增长，随时间衰减（半衰期：90 天） | ||
| - **建议机制** — 哪种实现类型最合适（hook/rule/skill/script/...） | ||
| - **目标路径** — 在目标树中服务于哪个目标 | ||
| 把 instinct 想象成原材料。它们被路由到正确的机制，实现后即归档。 | ||
| ### 实现路由 | ||
| 系统为每种行为选择最佳机制： | ||
| | 行为类型 | 机制 | | ||
| |--------------|-----------| | ||
| | 确定性的，每次都执行 | **Hook**（零 AI 判断） | | ||
| | 绑定特定文件/目录 | **Rule**（路径范围） | | ||
| | 可复用的知识集合 | **Skill**（带 eval 规范） | | ||
| | 周期性自动化 | **Script + 调度器** | | ||
| | 外部服务连接 | **MCP** | | ||
| | 需要隔离上下文 | **Agent** | | ||
| ### Skill & Eval 规范 | ||
| 当多个 instinct 覆盖同一领域且路由结果为「skill」时，它们汇聚成一个经过测试、有版本控制的知识模块。每个 skill 都有包含场景测试的 eval 规范。未通过 eval 的 skill 会自动改进。 | ||
| ### 可替换的实现 | ||
| 核心原则：**同一目标，进化的实现。** | ||
| ``` | ||
| 目标：「在合并前发现 bug」 | ||
| v1: instinct → 「记得运行测试」 | ||
| v2: rule → .claude/rules/testing.md（路径范围指导） | ||
| v3: skill → tdd-workflow.md（带 eval 规范） | ||
| v4: hook → pre-commit.sh（确定性，自动化） | ||
| ``` | ||
| 系统每晚审查这些——如果一个 skill 应该变成 hook，它会建议升级。 | ||
| --- | ||
| ## 夜间 Agent | ||
| 这是让系统真正自主的关键。夜间 agent 在你睡觉时自动运行 `/hm-night`——路由 instinct 到正确的机制、评估 skill、审查目标健康度、以及研究更好的方法。 | ||
| **设置：** 第一次运行 `/hm-night` 时，它会询问你是否启用自动夜间运行。同意后，它会配置调度器（macOS 上的 `launchd`，Linux 上的 `cron`）每晚运行。 | ||
| 你也可以随时手动运行 `/hm-night` 按需触发一个周期。 | ||
| ### 进化层级 | ||
| 通过 `evolution-config.yaml`（`init` 时创建）控制助手每晚进化的深度： | ||
| | | Minimal | Standard | Full | | ||
| |---|---------|----------|------| | ||
| | Instinct 收割 + 路由 | ✅ | ✅ | ✅ | | ||
| | Skill eval（仅变更部分） | ✅ | ✅ | ✅ | | ||
| | 研究 | — | 2 个主题 | 3-5 个主题 | | ||
| | 实验 | — | 每晚 1 个 | 每晚 3 个 | | ||
| | 额外循环 | — | — | 可选 | | ||
| | **预估费用/晚** | **~$0.5** | **~$2-3** | **~$5-10** | | ||
| 每周深度模式（可配置日期）额外执行：完整 skill 重新评估、目标树机制审查、深度健康检查。 | ||
| ```bash | ||
| # 随时切换层级 | ||
| # 编辑 evolution-config.yaml → tier: minimal | standard | full | ||
| ``` | ||
| 订阅用户（Max/Team）可以运行 `full` 而无需额外 API 费用。 | ||
| ``` | ||
| You go to sleep | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────────┐ | ||
| │ Nightly Agent (phase pipeline) │ | ||
| │ │ | ||
| │ 1. Health check (goal status) │ | ||
| │ │ | ||
| │ 2. Evolution cycle │ | ||
| │ Route instincts → 8 mechanisms │ | ||
| │ Eval + improve implementations │ | ||
| │ Review: best mechanism per goal? │ | ||
| │ │ | ||
| │ 3. Research (cross-night dedup) │ | ||
| │ │ | ||
| │ 4. Act (experiments + quick fixes) │ | ||
| │ │ | ||
| │ 5. Report + sync │ | ||
| └─────────────────────────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| You wake up to a smarter assistant + a report | ||
| ``` | ||
| **以下是真实的晨报示例：** | ||
| ```markdown | ||
| ## 晨报 — 2026-03-22 | ||
| ### 夜间变更 | ||
| - 改进 skill：claude-code-reference v4.6 → v4.8 | ||
| （添加了 CC v2.1.77-80 功能的覆盖） | ||
| - 归档 3 个过时的 instinct（已被 evolved skill 覆盖） | ||
| - 新实验通过：eval 噪声阈值设为 5pp | ||
| ### 目标健康度 | ||
| - continuous_evolution: ✅ 健康（10 个 skill，全部 100% eval） | ||
| - code_quality: ✅ 健康（144/144 测试通过） | ||
| - resource_awareness: ⚠️ 需关注（context 使用量趋势上升） | ||
| → 已排队实验：将大型 skill 拆分为章节 | ||
| ### 研究发现 | ||
| - Claude Code v2.1.81：新的 --bare 标志可加速 headless 模式 | ||
| → 实验已排队至明晚 | ||
| - 社区中检测到新模式：写作者/审查者 agent 分离 | ||
| → 已创建 instinct，如果被强化将进行汇聚 | ||
| ### 建议操作（给你的） | ||
| - 审查夜间研究产出的 2 个知识卡片候选 | ||
| - 批准实验：通过 skill 拆分减少 context | ||
| ``` | ||
| 在我们的参考系统中，夜间 agent 产出了 **1,500+ 次自主 commit**——路由 instinct 到正确的机制、演化 skill、运行实验、研究更好的方法、以及归档过时的模式。全部无需任何人工输入。 | ||
| 夜间 agent 是将 Homunculus 从「一个你使用的工具」变为「一个自行成长的系统」的关键。 | ||
| 参见 [docs/nightly-agent.md](../nightly-agent.md) 了解设置方法。 | ||
| --- | ||
| ## 实际成果 | ||
| 在真实的个人 AI 助手上构建和测试。在 **5 周**内（从零开始）： | ||
| | 进化产物 | 数量 | 详情 | | ||
| |-------------|-------|---------| | ||
| | 目标树 | **10 个目标 / 46+ 子目标** | 每个都有健康检查和指标 | | ||
| | Instinct | **229** | 1 个活跃 + 228 个自动归档（成熟系统：大部分模式已吸收进 skill） | | ||
| | Skill | **10** | 全部 100% eval 通过率 | | ||
| | 实验 | **20** | 结构化 A/B 测试，带通过/失败追踪 | | ||
| | 子代理 | **5** | 从重复的主线程模式中自动提取 | | ||
| | 定时 agent | **5** | 夜间心跳、Discord bridge、每日新闻、交易 × 2 | | ||
| | Hook | **12** | 观察、压缩、质量门禁 | | ||
| | 脚本 | **37** | Session 生命周期、健康检查、进化报告 | | ||
| | Slash command | **18** | 工作流自动化（forge-dev、quality-gate、eval...） | | ||
| | Rule | **7** | 核心模式、进化系统、知识管理 | | ||
| | ADR | **9** | 架构决策记录 | | ||
| | 总 commit 数 | **1,688+** | 大部分由夜间 agent 自动完成 | | ||
| 仅夜间 agent：**1,500+ 次自主 commit**。 | ||
| 系统甚至演化出了自己的任务管理面板： | ||
| <table align="center"> | ||
| <tr> | ||
| <td><img src="https://github.com/user-attachments/assets/5828b1e7-5808-478d-9340-505480a41a2c" alt="Jarvis Dashboard" width="520"></td> | ||
| <td><img src="https://github.com/user-attachments/assets/69c397ab-dde7-4dae-968b-9f7cf9b24e01" alt="Quest Board" width="200"></td> | ||
| </tr> | ||
| <tr> | ||
| <td align="center"><em>Jarvis Dashboard</em></td> | ||
| <td align="center"><em>Quest Board</em></td> | ||
| </tr> | ||
| </table> | ||
| [查看完整参考实现 →](../../examples/reference/) | ||
| --- | ||
| ## 差异对比 | ||
| | | Homunculus | OpenClaw | Cursor Rules | Claude Memory | | ||
| |---|---|---|---|---| | ||
| | **目标驱动** | 带指标 + 健康检查的目标树 | 否 | 否 | 否 | | ||
| | **从使用中学习** | 自动观察 → instinct → 8 种机制 | 自扩展 | 手动 | 自动记忆 | | ||
| | **质量控制** | Eval 规范 + 场景测试 | 无 | 无 | 无 | | ||
| | **自主夜间运行** | 夜间 agent：eval + 改进 + 研究 + 实验 | 否 | 否 | 否 | | ||
| | **自我改进** | Eval → improve → replace 循环 | 部分 | 否 | 否 | | ||
| | **元进化** | 进化机制自身也在进化 | 否 | 否 | 否 | | ||
| | **实现无关性** | Skill、agent、hook、script、MCP、cron... | 仅 skill | 仅 rule | 仅 memory | | ||
| OpenClaw 擅长自扩展。Homunculus 更进一步：它基于目标健康度决定*改进什么*，通过 eval *验证*改进效果，并在夜间*自主*完成所有工作。它们解决不同的问题。OpenClaw 是一个强大的工具。Homunculus 是一个进化操作系统。 | ||
| --- | ||
| ## 生成内容 | ||
| 运行 `npx homunculus-code init` 后： | ||
| ``` | ||
| your-project/ | ||
| ├── architecture.yaml # 你的目标树（大脑） | ||
| ├── evolution-config.yaml # 层级 + 预算设置 | ||
| ├── homunculus/ | ||
| │ ├── instincts/ | ||
| │ │ ├── personal/ # 自动提取的模式 | ||
| │ │ └── archived/ # 自动修剪的旧模式 | ||
| │ ├── evolved/ | ||
| │ │ ├── skills/ # 汇聚的、经测试的知识 | ||
| │ │ ├── agents/ # 专业化子代理 | ||
| │ │ └── evals/ # Skill 评估规范 | ||
| │ ├── experiments/ # A/B 测试追踪 | ||
| │ ├── reports/ # 进化周期报告 | ||
| │ └── scripts/ | ||
| │ ├── observe.sh # 观察 hook | ||
| │ ├── evaluate-session.js # 模式提取 | ||
| │ └── prune-instincts.js # 自动清理 | ||
| ├── .claude/ | ||
| │ ├── rules/ | ||
| │ │ └── evolution-system.md # Claude 应如何进化 | ||
| │ └── commands/ | ||
| │ ├── hm-goal.md # /hm-goal — 定义或查看目标 | ||
| │ ├── hm-night.md # /hm-night — 运行进化周期 | ||
| │ ├── hm-status.md # /hm-status — 进化仪表盘 | ||
| │ ├── eval-skill.md # /eval-skill | ||
| │ ├── improve-skill.md # /improve-skill | ||
| │ └── evolve.md # /evolve | ||
| └── .gitignore # 排除运行时数据 | ||
| ``` | ||
| --- | ||
| ## 进阶：元进化 | ||
| 进化机制本身也在进化： | ||
| - **Instinct 存活率**太低？ → 自动提高提取阈值 | ||
| - **Eval 区分度**太低？ → 添加更难的边界场景 | ||
| - **Skill 汇聚**太慢？ → 调整聚合触发条件 | ||
| - **机制覆盖率**低？ → 标记仅依赖 prompt 的目标以进行升级 | ||
| - **调度合规率**偏低？ → 审查 agent 调度是否遵循 token 决策树 | ||
| 通过五个指标追踪： | ||
| 1. `instinct_survival_rate` — 存活超过 14 天的 instinct 百分比 | ||
| 2. `skill_convergence` — 从首个 instinct 到 evolved skill 的时间 | ||
| 3. `eval_discrimination` — 实际能区分版本差异的 eval 场景百分比 | ||
| 4. `mechanism_coverage` — 拥有非 prompt 实现的目标百分比 | ||
| 5. `compliance_rate` — 在适当 context 压力下执行 agent 调度的百分比 | ||
| --- | ||
| ## 系统要求 | ||
| - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.1.70+ | ||
| - Node.js 18+ | ||
| - macOS 或 Linux | ||
| --- | ||
| ## 常见问题 | ||
| <details> | ||
| <summary><strong>这只能用于 Claude Code 吗？</strong></summary> | ||
| 概念（目标树、eval 驱动的进化、可替换的实现）是工具无关的。当前实现针对 Claude Code 的 hook 和 command，但核心流水线可以适配其他 AI 框架。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>需要额外的 API 费用吗？</strong></summary> | ||
| 观察 hook 是轻量级的（不调用 API）。Instinct 提取每个 session 使用一次简短的 Claude 调用（约 $0.01）。夜间 agent 是可选的，且预算可配置。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>可以保留我现有的 CLAUDE.md 和规则吗？</strong></summary> | ||
| 可以。`npx homunculus-code init` 会在不覆盖现有文件的情况下添加到你的项目中。你当前的设置成为进化的起点。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>这与 Claude Code 内置的记忆有什么不同？</strong></summary> | ||
| Claude 的记忆记录事实。Homunculus 进化*行为*——经过测试的 skill、自动化的 hook、专业化的 agent——全部由你定义的目标驱动，并通过质量门禁防止回退。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>这与 OpenClaw 相比如何？</strong></summary> | ||
| OpenClaw 擅长自扩展。Homunculus 解决不同的问题：自主的、目标导向的进化。它决定什么需要改进（通过目标健康度）、验证改进效果（通过 eval）、并在夜间完成工作（通过夜间 agent）。你可以两者兼用：OpenClaw 用于按需能力扩展，Homunculus 用于顶层的自主进化层。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>启动时看到 hook 错误（SessionStart / Stop）</strong></summary> | ||
| 那些来自你自己的用户级 hook（`~/.claude/settings.json`），不是来自 Homunculus。如果你的 hook 使用相对路径如 `node scripts/foo.js`，它们在没有这些脚本的项目中会失败。修复方法是添加守卫： | ||
| ```json | ||
| "command": "test -f scripts/foo.js && node scripts/foo.js || true" | ||
| ``` | ||
| Homunculus 只向项目级 `.claude/settings.json` 添加 hook。 | ||
| </details> | ||
| --- | ||
| ## 博客文章 | ||
| - [Stop Tuning Your AI. Let It Tune Itself.](../stop-tuning-your-ai.md) — Homunculus 背后的故事，以及为什么目标树胜过手动配置。 | ||
| --- | ||
| ## 理念 | ||
| > 「你的 AI 助手应该是一颗种子，而不是一座雕像。」 | ||
| 别再花晚上的时间调教 AI 了。种下一颗种子，定义你的目标，让它成长。你用得越多，它就越好——它通过 eval 分数、目标健康检查和晨报准确告诉你它是如何进步的以及为什么。 | ||
| --- | ||
| ## 致谢 | ||
| Homunculus 建立在多个项目和研究的思想之上： | ||
| - **[everything-claude-code](https://github.com/affaan-m/everything-claude-code)** — Continuous Learning 模式和 Skill Creator 的 eval → improve 循环。Homunculus 采纳并扩展了这些，发展为目标树驱动的自主进化系统。 | ||
| - **[OpenClaw](https://github.com/openclaw/openclaw)** — 证明了 AI 助手可以扩展自己的能力。Homunculus 在此基础上增加了目标方向、eval 质量门禁和自主夜间运行。 | ||
| - **[Karpathy 的 Autoresearch](https://x.com/karpathy)** — 证明了 AI 可以运行自主实验循环（118 次迭代，12+ 小时）。启发了夜间 agent 的研究周期。 | ||
| - **[Anthropic 的 Eval 研究](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)** — Eval 方法论、噪声容忍度（±6pp）、以及 pass@k / pass^k 指标。 | ||
| --- | ||
| ## 贡献 | ||
| 参见 [CONTRIBUTING.md](../../CONTRIBUTING.md)。 | ||
| ## 许可证 | ||
| MIT | ||
| --- | ||
| **由 [Javan](https://github.com/JavanC) 和他的自我进化 AI 助手构建。** |
| **語言：** [English](../../README.md) | [繁體中文](README.md) | [简体中文](../zh-CN/README.md) | ||
| # Homunculus for Claude Code | ||
| [](https://www.npmjs.com/package/homunculus-code) | ||
| [](https://opensource.org/licenses/MIT) | ||
| [](https://docs.anthropic.com/en/docs/claude-code) | ||
| [](https://nodejs.org) | ||
| **別再調教你的 AI。讓它自己演化。** | ||
| <p align="center"> | ||
| <img src="https://github.com/user-attachments/assets/b3ce6017-02de-44a4-a3c6-8d45765c1693" alt="Homunculus Demo — goal setup + evolution cycle in 60 seconds" width="700"> | ||
| </p> | ||
| 你花了無數小時調整 prompt、撰寫規則、研究新功能、設定工具。Homunculus 反轉這一切：定義你的目標，系統會自行演化——skill、agent、hook、script，一切——而你只需專注在真正的工作上。 | ||
| ```bash | ||
| npx homunculus-code init | ||
| ``` | ||
| 一行指令。定義你的目標。你的助理開始演化。 | ||
| > **實證：** 一位開發者運行此系統 5 週，自動產生了 229 個行為模式，收斂為 10 個經過測試的 skill、4 個專門化 agent、18 個 command、以及 37 個自動化 script。夜間 agent 進行了 1,500+ 次自主 commit——在開發者睡覺時持續改善系統。[查看成果 →](#真實世界的成果) | ||
| --- | ||
| ## 為什麼需要 | ||
| 每個 Claude Code 進階使用者都會撞上同一面牆： | ||
| ``` | ||
| 第 1 週：「Claude 太厲害了！」 | ||
| 第 2 週：「讓我加一些 rule 和 hook...」 | ||
| 第 3 週：「我需要 skill、agent、MCP server、自訂 command...」 | ||
| 第 4 週：「我花在設定 Claude 的時間比用它的時間還多。」 | ||
| ``` | ||
| 聽起來很熟悉？即使是 [OpenClaw](https://github.com/openclaw/openclaw)——擁有 300K+ 星星和自我擴展能力——仍然需要*你*來決定要改善什麼、何時改善、以及改善是否有效。編輯 `SOUL.md`、調整 `AGENTS.md`、搞壞了什麼、再開一個 AI session 來修。AI 可以擴展自身，但它無法設定自己的方向或驗證自身品質。 | ||
| **這就是差異所在：** | ||
| ``` | ||
| Without Homunculus: With Homunculus: | ||
| You notice tests keep failing Goal tree detects test_pass_rate dropped | ||
| → You research testing patterns → Nightly agent auto-evolves tdd skill | ||
| → You write a pre-commit skill → Eval confirms 100% pass | ||
| → You test it manually → Morning report: "Fixed. Here's what changed." | ||
| → It breaks after a Claude update → Next update? System re-evaluates and adapts | ||
| → You fix it again... → You slept through all of this | ||
| ``` | ||
| --- | ||
| ## 核心理念：Goal Tree | ||
| 大多數 AI 工具做局部最佳化——「你做了 X，所以我記住 X。」Homunculus 做**全域最佳化**——朝著你在 tree 中定義的目標前進： | ||
| ``` | ||
| 🎯 my-project | ||
| ├── code_quality — Ship fewer bugs | ||
| │ ├── testing — Maintain test coverage | ||
| │ │ └── realized_by: jest.config.js, tests/ (42 tests) ✓ | ||
| │ └── linting — Consistent code style | ||
| │ └── realized_by: .eslintrc.js, .prettierrc ✓ | ||
| ├── speed — Move faster | ||
| │ └── deploy_automation — One-command deploys | ||
| │ └── realized_by: # will evolve ○ | ||
| └── knowledge — Learn and remember | ||
| ├── research — Discover better approaches | ||
| │ └── realized_by: nightly agent ✓ | ||
| └── memory — Remember what matters | ||
| └── realized_by: homunculus/instincts/ ✓ | ||
| ``` | ||
| 每個節點定義了**為什麼**存在、**如何**衡量、以及**什麼**目前在實作它。**目標是穩定的。實作會演化。** 系統自動將每個行為路由到最佳機制——實作被替換和升級，而目標保持不變。 | ||
| <details> | ||
| <summary>📖 <code>architecture.yaml</code> 中的 goal 節點長什麼樣？</summary> | ||
| ```yaml | ||
| # architecture.yaml — from the reference system | ||
| autonomous_action: | ||
| purpose: "Act without waiting for human commands" | ||
| goals: | ||
| nightly_research: | ||
| purpose: "Discover better approaches while developer sleeps" | ||
| realized_by: heartbeat/heartbeat.sh # a shell script | ||
| health_check: | ||
| command: "test $(find logs/ -mtime -1 | wc -l) -gt 0" | ||
| expected: "nightly agent ran in last 24h" | ||
| task_management: | ||
| purpose: "Track and complete tasks autonomously" | ||
| realized_by: quest-board/server.js # a web app | ||
| metrics: | ||
| - name: forge_completion_rate | ||
| healthy: "> 70%" | ||
| continuous_evolution: | ||
| purpose: "Improve over time without human intervention" | ||
| goals: | ||
| pattern_extraction: | ||
| purpose: "Learn from every session" | ||
| realized_by: homunculus/scripts/evaluate-session.js | ||
| skill_aggregation: | ||
| purpose: "Converge patterns into tested skills" | ||
| realized_by: homunculus/evolved/skills/ | ||
| ``` | ||
| `realized_by` 欄位可以指向**任何東西**： | ||
| | 類型 | 範例 | 使用時機 | | ||
| |------|---------|-------------| | ||
| | Skill | `skills/tdd-workflow.md` | 行為知識 | | ||
| | Agent | `agents/code-reviewer.md` | 專門化 AI subagent | | ||
| | Hook | `hooks/pre-commit.sh` | 自動觸發 | | ||
| | Script | `scripts/deploy.sh` | Shell 自動化 | | ||
| | Cron | `launchd/nightly-check.plist` | 排程任務 | | ||
| | MCP | `mcp-servers/github` | 外部整合 | | ||
| | Rule | `rules/security.md` | Claude Code 行為規則 | | ||
| | Command | `commands/quality-gate.md` | Slash command 工作流 | | ||
| </details> | ||
| --- | ||
| ## 如何演化 | ||
| ``` | ||
| You use Claude Code normally | ||
| │ | ||
| ┌──────────┼──────────┐ | ||
| │ │ │ | ||
| Observe Health Check Research | ||
| (hooks) (goal tree) (nightly) | ||
| │ │ │ | ||
| └──────────┼──────────┘ | ||
| │ | ||
| ▼ | ||
| ┌────────────┐ | ||
| │ Evolve │ Goals stay the same. | ||
| │ ──────── │ Implementations get better. | ||
| │ Extract │ | ||
| │ Converge │ | ||
| │ Eval │ | ||
| │ Replace │ | ||
| └────────────┘ | ||
| ``` | ||
| **三個輸入，一個引擎：** | ||
| 1. **觀察** — hook 監控你的工具使用，將反覆出現的模式提取為 "instinct" | ||
| 2. **健康檢查** — goal tree 識別哪些目標不健康 → 聚焦於此 | ||
| 3. **研究** — 夜間 agent 掃描更好的方法並提出實驗 | ||
| 演化引擎接著： | ||
| - 提取行為模式 → **instinct**（標記最佳機制 + goal 路徑） | ||
| - 將每個 instinct 路由到最佳機制 → **hook、rule、skill、script、agent 或 system** | ||
| - 對於 skill：**eval → improve 迴圈**直到 100% 通過率 | ||
| - 每晚檢視所有 goal → 目前的機制仍是最佳選擇嗎？ | ||
| - Instinct 實作後歸檔 → 機制本身才是 source of truth | ||
| --- | ||
| ## 最新更新 | ||
| ### v0.9.0 — Evolution Engine 升級 (Mar 2026) | ||
| - **智慧觀察** — `observe.sh` 現在過濾雜訊（跳過 Read/Glob/Grep，寫入操作只記錄 post-phase）並追蹤引用頻率——哪些 instinct 和 skill 真正被讀取 | ||
| - **三層提取** — `evaluate-session.js` 現在一次提取 instinct + memory 建議 + 研究主題。Memory 和研究寫入 `homunculus/reports/` 供你審閱（非侵入式） | ||
| - **語意去重** — 新 instinct 可以宣告 `supersedes` 自動歸檔被取代的舊 instinct | ||
| - **寫入門檻** — 提取 prompt 現在包含品質標準（必須改變未來行為、記錄承諾、或保存決策理由） | ||
| - **動態每日上限** — Instinct 提取上限隨 session 大小調整（短 session 1 個，長 session 最多 5 個） | ||
| - **更聰明的修剪** — `prune-instincts.js` 現在使用引用頻率評分（+25 常用、-15 從未引用）、3 層 skill 覆蓋偵測（直接演化 / 高重疊 / 部分）、14 天寬限期再開始信心衰退、以及 at-risk 預警 | ||
| - **冪等性** — 提取追蹤掃描狀態，避免重複處理相同觀察 | ||
| - **`--json` 輸出** — `prune-instincts.js` 支援 `--json` 供程式化使用 | ||
| ### v0.8.0 — 升級機制 (Mar 2026) | ||
| - **`homunculus-code upgrade`** — 升級 npm 套件時更新受管理檔案的新指令。核心 script（observe.sh 等）自動替換並備份為 `.bak`；command 和 rule 只在你未自訂時才替換——否則寫入 `.new` 檔供手動合併 | ||
| - **安裝清單** — `init` 現在產生 `homunculus/.manifest.json` 追蹤所有受管理檔案的 SHA256 hash，實現安全的 diff-aware 升級 | ||
| ### v0.7.0 — 非侵入式安裝 & 主動性設計指南 (Mar 2026) | ||
| - **非侵入式安裝** — Script 現在放在 `homunculus/scripts/` 而非專案根目錄的 `scripts/`，避免與既有專案工具衝突 | ||
| - **安全 command 安裝** — Slash command 逐檔安裝；既有 command 保留並顯示警告，不會被覆蓋 | ||
| - **Hook 合併** — 如果 `.claude/settings.json` 中已有 `PostToolUse` hook，觀察 hook 會合併到陣列中，而非跳過整個設定 | ||
| - **主動性設計指南** — 新增 [docs/proactivity.md](../../docs/proactivity.md) 涵蓋主動式 AI 助理的三個核心概念：Memory Flush、Research Queue、Periodic Heartbeat | ||
| ### v0.6.3 — 專案感知目標 & 演化層級 (Mar 2026) | ||
| - **專案掃描** — `/hm-goal` 現在在提問前偵測你的技術堆疊、測試、CI 和目錄結構。Goal tree 從你已有的東西開始預填 | ||
| - **通用機制路由** — `/evolve` 將 instinct 路由到最佳機制（hook、rule、skill、script、agent），不只是 skill | ||
| - **演化強度層級** — 在 `evolution-config.yaml` 中設定 `minimal` / `standard` / `full` 以控制深度、頻率和成本 | ||
| - **夜間 agent 設定** — 首次執行 `/hm-night` 時正確提供自動夜間演化的設定選項 | ||
| ### v0.5.0 — 初始版本 (Mar 2026) | ||
| - **Goal tree** — 在 `architecture.yaml` 中定義你想要的 | ||
| - **觀察 hook** — 自動從你的 session 中擷取行為模式 | ||
| - **夜間演化** — `/hm-night` 執行健康檢查、提取 instinct、演化 skill、產生報告 | ||
| - **6 個 slash command** — `/hm-goal`、`/hm-night`、`/hm-status`、`/evolve`、`/eval-skill`、`/improve-skill` | ||
| --- | ||
| ## 快速開始 | ||
| ### 1. 安裝 | ||
| 在你的專案目錄（有 `CLAUDE.md` 或 `.claude/` 的地方）執行： | ||
| ```bash | ||
| npx homunculus-code init | ||
| ``` | ||
| ``` | ||
| Homunculus — Self-evolving AI Assistant | ||
| ✓ Created homunculus/ directory structure | ||
| ✓ Added evolution rules | ||
| ✓ Copied evolution scripts | ||
| ✓ Added slash commands (/hm-goal, /hm-night, /hm-status) | ||
| ✓ Configured observation hook | ||
| Done! Homunculus is installed. | ||
| Next steps: | ||
| 1. Run claude to open Claude Code | ||
| 2. Type /hm-goal to define your goals (AI-guided) | ||
| 3. Type /hm-night to run your first evolution cycle | ||
| ``` | ||
| ### 2. 定義你的目標 | ||
| 開啟 Claude Code 並輸入 `/hm-goal`。Claude 會先掃描你的專案，然後根據發現的內容提問： | ||
| ``` | ||
| > /hm-goal | ||
| Claude: I see a Next.js + TypeScript project with 42 Jest tests | ||
| and GitHub Actions CI. What's the main purpose of this project? | ||
| You: A SaaS dashboard for analytics | ||
| Claude: You have 42 tests already. Is test coverage a pain point, | ||
| or is something else slowing you down more? | ||
| You: Deployment is manual and error-prone | ||
| Claude: If your AI could fix one thing overnight, what would it be? | ||
| You: Automated deployment with proper checks | ||
| Claude: Here's your goal tree: | ||
| 🎯 analytics-dashboard | ||
| ├── code_quality — Ship fewer bugs | ||
| │ ├── testing — Maintain test coverage | ||
| │ │ └── realized_by: jest.config.js, tests/ (42 tests) ✓ | ||
| │ └── linting — Consistent code style | ||
| │ └── realized_by: .eslintrc.js, .prettierrc ✓ | ||
| ├── deployment — Reliable releases | ||
| │ └── ci_pipeline — Automated checks on every PR | ||
| │ └── realized_by: .github/workflows/ ✓ | ||
| └── productivity — Move faster | ||
| └── deploy_automation — One-command deploys | ||
| └── realized_by: # will evolve ○ | ||
| 4 goals: 3 already have implementations (✓), 1 will evolve (○) | ||
| Does this look right? | ||
| You: Great! | ||
| Claude: ✅ architecture.yaml created with 4 goals! | ||
| ``` | ||
| 對於沒有既有檔案的新專案，Claude 會退回到詢問關於專案類型和目標的一般性問題。 | ||
| ### 3. 執行第一次演化循環 | ||
| ``` | ||
| > /hm-night | ||
| ``` | ||
| 觀看 Claude 檢查你的目標、將 instinct 路由到正確的機制（hook/rule/skill/script/agent）、評估和改善實作、並產生報告——全在一個指令中完成。這就是夜間 agent 在你睡覺時自主執行的內容。 | ||
| ### 4. 升級 | ||
| 新版本發布時，更新你的受管理檔案： | ||
| ```bash | ||
| npx homunculus-code@latest upgrade | ||
| ``` | ||
| - **核心 script** → 自動替換（備份儲存為 `.bak`） | ||
| - **你未修改過的 command/rule** → 自動替換 | ||
| - **你自訂過的 command/rule** → 跳過，新版本儲存為 `.new` 供你合併 | ||
| ### 5. 持續使用 Claude Code | ||
| 觀察 hook 會自動監控你的使用。當模式浮現時，instinct 會被提取並路由到正確的機制： | ||
| ``` | ||
| /hm-goal 定義或調整你的目標 | ||
| /hm-night 執行完整演化循環（可手動執行，但最佳方式是設為夜間 agent） | ||
| /hm-status 查看演化進度 | ||
| ``` | ||
| `/hm-night` 執行完整的演化流程：將 instinct 路由到最佳機制（hook/rule/skill/script/agent）、對 skill 執行 eval + improve、檢視 goal 健康度、產生報告。你可以隨時手動執行，但真正的威力在於讓它每晚自主運行。 | ||
| > 第一次執行 `/hm-night` 時，它會詢問你是否要設定夜間 agent 以進行自動夜間演化。 | ||
| --- | ||
| ## 關鍵概念 | ||
| ### Goal Tree (`architecture.yaml`) | ||
| 中樞神經系統。每個 goal 都有 purpose、metrics 和 health check。演化系統讀取它來決定**改善什麼**以及**如何衡量成功**。 | ||
| ### Instinct | ||
| 從你的使用中自動提取的小型行為模式。每個 instinct 標記了： | ||
| - **信心分數** — 隨強化成長，隨時間衰退（半衰期：90 天） | ||
| - **建議機制** — 哪種實作類型最適合（hook/rule/skill/script/...） | ||
| - **Goal 路徑** — 這服務 tree 中的哪個 goal | ||
| 把 instinct 想像成原料。它們被路由到正確的機制，實作後就歸檔。 | ||
| ### 實作路由 | ||
| 系統為每個行為選擇最佳機制： | ||
| | 行為類型 | 機制 | | ||
| |--------------|-----------| | ||
| | 確定性的、每次都要 | **Hook**（零 AI 判斷） | | ||
| | 綁定特定檔案/目錄 | **Rule**（path-scoped） | | ||
| | 可複用的知識集合 | **Skill**（含 eval spec） | | ||
| | 週期性自動化 | **Script + scheduler** | | ||
| | 外部服務連接 | **MCP** | | ||
| | 需要隔離 context | **Agent** | | ||
| ### Skill & Eval Spec | ||
| 當多個 instinct 覆蓋相同領域且路由結果是 "skill" 時，它們收斂為經過測試、有版本的知識模組。每個 skill 都有包含情境測試的 eval spec。未通過 eval 的 skill 會自動改善。 | ||
| ### 可替換實作 | ||
| 核心原則：**相同目標，演化的實作。** | ||
| ``` | ||
| Goal: "Catch bugs before merge" | ||
| v1: instinct → "remember to run tests" | ||
| v2: rule → .claude/rules/testing.md (path-scoped guidance) | ||
| v3: skill → tdd-workflow.md (with eval spec) | ||
| v4: hook → pre-commit.sh (deterministic, automated) | ||
| ``` | ||
| 系統每晚檢視這些——如果一個 skill 應該是 hook，它會建議升級。 | ||
| --- | ||
| ## 夜間 Agent | ||
| 這是讓系統真正自主的關鍵。夜間 agent 在你睡覺時自動執行 `/hm-night`——路由 instinct 到正確的機制、評估 skill、檢視 goal 健康度、研究更好的方法。 | ||
| **設定：** 第一次執行 `/hm-night` 時，它會詢問是否啟用自動夜間執行。同意後，它會設定排程器（macOS 上用 `launchd`，Linux 上用 `cron`）每晚執行。 | ||
| 你也可以隨時手動執行 `/hm-night` 來觸發一次循環。 | ||
| ### 演化層級 | ||
| 透過 `evolution-config.yaml`（`init` 時建立）控制你的助理每晚演化的深度： | ||
| | | Minimal | Standard | Full | | ||
| |---|---------|----------|------| | ||
| | Instinct 收割 + 路由 | ✅ | ✅ | ✅ | | ||
| | Skill eval（僅變更的） | ✅ | ✅ | ✅ | | ||
| | 研究 | — | 2 個主題 | 3-5 個主題 | | ||
| | 實驗 | — | 每晚 1 個 | 每晚 3 個 | | ||
| | 額外迴圈 | — | — | 可選 | | ||
| | **預估成本/晚** | **~$0.5** | **~$2-3** | **~$5-10** | | ||
| 每週深度模式（可設定日期）額外包含：全面 skill 重新評估、goal tree 機制審查、深度健康檢查。 | ||
| ```bash | ||
| # 隨時更改層級 | ||
| # 編輯 evolution-config.yaml → tier: minimal | standard | full | ||
| ``` | ||
| 訂閱用戶（Max/Team）可以無額外 API 成本執行 `full`。 | ||
| ``` | ||
| You go to sleep | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────────┐ | ||
| │ Nightly Agent (phase pipeline) │ | ||
| │ │ | ||
| │ 1. Health check (goal status) │ | ||
| │ │ | ||
| │ 2. Evolution cycle │ | ||
| │ Route instincts → 8 mechanisms │ | ||
| │ Eval + improve implementations │ | ||
| │ Review: best mechanism per goal? │ | ||
| │ │ | ||
| │ 3. Research (cross-night dedup) │ | ||
| │ │ | ||
| │ 4. Act (experiments + quick fixes) │ | ||
| │ │ | ||
| │ 5. Report + sync │ | ||
| └─────────────────────────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| You wake up to a smarter assistant + a report | ||
| ``` | ||
| **以下是真實的早報範例：** | ||
| ```markdown | ||
| ## Morning Report — 2026-03-22 | ||
| ### What Changed Overnight | ||
| - Improved skill: claude-code-reference v4.6 → v4.8 | ||
| (added coverage for CC v2.1.77-80 features) | ||
| - Archived 3 outdated instincts (covered by evolved skills) | ||
| - New experiment passed: eval noise threshold set to 5pp | ||
| ### Goal Health | ||
| - continuous_evolution: ✅ healthy (10 skills, all 100% eval) | ||
| - code_quality: ✅ healthy (144/144 tests passing) | ||
| - resource_awareness: ⚠️ attention (context usage trending up) | ||
| → Queued experiment: split large skill into chapters | ||
| ### Research Findings | ||
| - Claude Code v2.1.81: new --bare flag could speed up headless mode | ||
| → Experiment queued for tomorrow night | ||
| - New pattern detected in community: writer/reviewer agent separation | ||
| → Instinct created, will converge if reinforced | ||
| ### Suggested Actions (for you) | ||
| - Review 2 knowledge card candidates from overnight research | ||
| - Approve experiment: context reduction via skill splitting | ||
| ``` | ||
| 在我們的參考系統中，夜間 agent 產生了 **1,500+ 次自主 commit**——路由 instinct 到正確的機制、演化 skill、執行實驗、研究更好的方法、歸檔過時的模式。全部無需任何人為輸入。 | ||
| 夜間 agent 是將 Homunculus 從「你使用的工具」變成「自己成長的系統」的關鍵。 | ||
| 詳見 [docs/nightly-agent.md](../../docs/nightly-agent.md) 了解設定方式。 | ||
| --- | ||
| ## 真實世界的成果 | ||
| 在真實的個人 AI 助理上建置和測試。**5 週**內（從零開始）： | ||
| | 演化的產物 | 數量 | 詳細 | | ||
| |-------------|-------|---------| | ||
| | Goal tree | **10 個 goal / 46+ 個子目標** | 每個都有 health check 和 metrics | | ||
| | Instinct | **229** | 1 個活躍 + 228 個自動歸檔（成熟系統：大部分模式已吸收進 skill） | | ||
| | Skill | **10** | 全部 100% eval 通過率 | | ||
| | 實驗 | **20** | 結構化 A/B 測試，含通過/失敗追蹤 | | ||
| | Subagent | **4** | 從重複的主執行緒模式中自動提取 | | ||
| | 排程 agent | **4** | 夜間 heartbeat、Discord bridge、每日新聞、交易 × 2 | | ||
| | Hook | **12** | 觀察、壓縮、品質門檻 | | ||
| | Script | **37** | Session 生命週期、健康檢查、演化報告 | | ||
| | Slash command | **18** | 工作流自動化（forge-dev、quality-gate、eval...） | | ||
| | Rule | **7** | 核心模式、演化系統、知識管理 | | ||
| | ADR | **9** | 架構決策記錄 | | ||
| | 總 commit 數 | **1,688+** | 大部分由夜間 agent 自動完成 | | ||
| 夜間 agent 單獨貢獻：**1,500+ 次自主 commit**。 | ||
| 系統甚至演化出了自己的任務管理面板： | ||
| <table align="center"> | ||
| <tr> | ||
| <td><img src="https://github.com/user-attachments/assets/5828b1e7-5808-478d-9340-505480a41a2c" alt="Jarvis Dashboard" width="520"></td> | ||
| <td><img src="https://github.com/user-attachments/assets/69c397ab-dde7-4dae-968b-9f7cf9b24e01" alt="Quest Board" width="200"></td> | ||
| </tr> | ||
| <tr> | ||
| <td align="center"><em>Jarvis Dashboard</em></td> | ||
| <td align="center"><em>Quest Board</em></td> | ||
| </tr> | ||
| </table> | ||
| [查看完整參考實作 →](../../examples/reference/) | ||
| --- | ||
| ## 與其他工具的差異 | ||
| | | Homunculus | OpenClaw | Cursor Rules | Claude Memory | | ||
| |---|---|---|---|---| | ||
| | **目標驅動** | Goal tree + metrics + health check | 否 | 否 | 否 | | ||
| | **從使用中學習** | 自動觀察 → instinct → 8 種機制 | 自我擴展 | 手動 | 自動記憶 | | ||
| | **品質控管** | Eval spec + 情境測試 | 無 | 無 | 無 | | ||
| | **自主夜間運作** | 夜間 agent：eval + improve + 研究 + 實驗 | 否 | 否 | 否 | | ||
| | **自我改善** | Eval → improve → replace 迴圈 | 部分 | 否 | 否 | | ||
| | **元演化** | 演化機制自身也在演化 | 否 | 否 | 否 | | ||
| | **實作無關** | Skill、agent、hook、script、MCP、cron... | 僅 Skill | 僅 Rule | 僅 Memory | | ||
| OpenClaw 擅長自我擴展。Homunculus 更進一步：它根據 goal 健康度決定*要改善什麼*、用 eval *驗證*改善、並在夜間*自主*完成一切。兩者解決不同問題。OpenClaw 是強力工具。Homunculus 是演化的作業系統。 | ||
| --- | ||
| ## 產生的檔案結構 | ||
| `npx homunculus-code init` 之後： | ||
| ``` | ||
| your-project/ | ||
| ├── architecture.yaml # 你的 goal tree（大腦） | ||
| ├── evolution-config.yaml # 層級 + 預算設定 | ||
| ├── homunculus/ | ||
| │ ├── instincts/ | ||
| │ │ ├── personal/ # 自動提取的模式 | ||
| │ │ └── archived/ # 自動修剪的舊模式 | ||
| │ ├── evolved/ | ||
| │ │ ├── skills/ # 收斂、經測試的知識 | ||
| │ │ ├── agents/ # 專門化 subagent | ||
| │ │ └── evals/ # Skill 評估規格 | ||
| │ ├── experiments/ # A/B 測試追蹤 | ||
| │ ├── reports/ # 演化循環報告 | ||
| │ └── scripts/ | ||
| │ ├── observe.sh # 觀察 hook | ||
| │ ├── evaluate-session.js # 模式提取 | ||
| │ └── prune-instincts.js # 自動清理 | ||
| ├── .claude/ | ||
| │ ├── rules/ | ||
| │ │ └── evolution-system.md # Claude 應如何演化 | ||
| │ └── commands/ | ||
| │ ├── hm-goal.md # /hm-goal — 定義或檢視目標 | ||
| │ ├── hm-night.md # /hm-night — 執行演化循環 | ||
| │ ├── hm-status.md # /hm-status — 演化儀表板 | ||
| │ ├── eval-skill.md # /eval-skill | ||
| │ ├── improve-skill.md # /improve-skill | ||
| │ └── evolve.md # /evolve | ||
| └── .gitignore # 排除 runtime 資料 | ||
| ``` | ||
| --- | ||
| ## 進階：元演化 | ||
| 演化機制本身也在演化： | ||
| - **Instinct 存活率**太低？→ 自動提高提取門檻 | ||
| - **Eval discrimination** 太低？→ 加入更難的邊界情境 | ||
| - **Skill 收斂**太慢？→ 調整聚合觸發條件 | ||
| - **機制覆蓋率**低？→ 標記僅依賴 prompt 的 goal 以進行升級 | ||
| - **Dispatch 合規率**偏低？→ 檢視 agent dispatch 是否遵循 token 決策樹 | ||
| 透過五個指標追蹤： | ||
| 1. `instinct_survival_rate` — 存活超過 14 天的 instinct 百分比 | ||
| 2. `skill_convergence` — 從第一個 instinct 到演化出 skill 的時間 | ||
| 3. `eval_discrimination` — 實際能區分版本差異的 eval 情境百分比 | ||
| 4. `mechanism_coverage` — 擁有非 prompt 實作的 goal 百分比 | ||
| 5. `compliance_rate` — 在適當 context 壓力下執行的 agent dispatch 百分比 | ||
| --- | ||
| ## 系統需求 | ||
| - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.1.70+ | ||
| - Node.js 18+ | ||
| - macOS 或 Linux | ||
| --- | ||
| ## 常見問題 | ||
| <details> | ||
| <summary><strong>這只能用在 Claude Code 上嗎？</strong></summary> | ||
| 概念（goal tree、eval 驅動演化、可替換實作）不依賴特定工具。目前的實作針對 Claude Code 的 hook 和 command，但核心流程可以適配到其他 AI 框架。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>需要額外的 API 費用嗎？</strong></summary> | ||
| 觀察 hook 很輕量（無 API 呼叫）。Instinct 提取每個 session 使用一次短 Claude 呼叫（約 $0.01）。夜間 agent 是可選的且可設定預算。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>可以保留我既有的 CLAUDE.md 和 rule 嗎？</strong></summary> | ||
| 可以。`npx homunculus-code init` 在不覆蓋既有檔案的情況下加入你的專案。你目前的設定會成為演化的起點。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>這和 Claude Code 內建的 memory 有什麼不同？</strong></summary> | ||
| Claude 的 memory 記錄事實。Homunculus 演化*行為*——經過測試的 skill、自動化 hook、專門化 agent——全部由你定義的目標驅動，並有品質門檻防止退化。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>這和 OpenClaw 有什麼不同？</strong></summary> | ||
| OpenClaw 擅長自我擴展。Homunculus 解決不同的問題：自主、目標導向的演化。它決定什麼需要改善（透過 goal 健康度）、驗證改善（透過 eval）、並在夜間完成工作（透過夜間 agent）。你可以兩者並用：OpenClaw 做隨需能力擴展、Homunculus 做上層的自主演化。 | ||
| </details> | ||
| <details> | ||
| <summary><strong>啟動時看到 hook 錯誤（SessionStart / Stop）</strong></summary> | ||
| 那些來自你自己的使用者層級 hook（`~/.claude/settings.json`），不是 Homunculus 的。如果你的 hook 使用相對路徑如 `node scripts/foo.js`，它們會在沒有那些 script 的專案中失敗。修復方式是加入防護： | ||
| ```json | ||
| "command": "test -f scripts/foo.js && node scripts/foo.js || true" | ||
| ``` | ||
| Homunculus 只會將 hook 加入專案層級的 `.claude/settings.json`。 | ||
| </details> | ||
| --- | ||
| ## 部落格文章 | ||
| - [Stop Tuning Your AI. Let It Tune Itself.](../../docs/stop-tuning-your-ai.md) — Homunculus 背後的故事，以及為什麼 goal tree 比手動設定更好。 | ||
| --- | ||
| ## 理念 | ||
| > 「你的 AI 助理應該是一顆種子，而不是一座雕像。」 | ||
| 別再把晚上的時間花在調教 AI 上。種下一顆種子，定義你的目標，讓它成長。你使用得越多，它就越好——而且它會透過 eval 分數、goal 健康檢查和早報，清楚地告訴你它如何改善以及為什麼。 | ||
| --- | ||
| ## 致謝 | ||
| Homunculus 建立在以下專案和研究的理念之上： | ||
| - **[everything-claude-code](https://github.com/affaan-m/everything-claude-code)** — Continuous Learning 模式和 Skill Creator 的 eval → improve 迴圈。Homunculus 採納並延伸這些，成為目標樹驅動的自主演化系統。 | ||
| - **[OpenClaw](https://github.com/openclaw/openclaw)** — 證明 AI 助理可以擴展自身能力。Homunculus 增加了目標方向、eval 品質門檻、以及自主夜間運作。 | ||
| - **[Karpathy's Autoresearch](https://x.com/karpathy)** — 證明 AI 可以執行自主實驗迴圈（118 次迭代、12+ 小時）。啟發了夜間 agent 的研究循環。 | ||
| - **[Anthropic's Eval Research](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)** — Eval 方法論、雜訊容忍度（±6pp）、以及 pass@k / pass^k 指標。 | ||
| --- | ||
| ## 貢獻 | ||
| 詳見 [CONTRIBUTING.md](../../CONTRIBUTING.md)。 | ||
| ## 授權 | ||
| MIT | ||
| --- | ||
| **由 [Javan](https://github.com/JavanC) 和他的自我演化 AI 助理共同建造。** |
| # Philosophy | ||
| The principles behind Homunculus. These aren't aspirational — they're the constraints we actually use when making design decisions. | ||
| --- | ||
| ## 1. Goals Are Permanent; Implementations Are Temporary | ||
| Your goals ("ship tested code", "respond in the user's language", "stay within budget") rarely change. But the *how* changes constantly — what starts as a prompt tweak becomes a rule, then a skill, then a hook, then a script. | ||
| Homunculus encodes this directly: `architecture.yaml` defines stable goals; everything else (instincts, skills, agents, hooks) is disposable implementation that evolves toward those goals. When an implementation stops serving its goal, it gets archived — no attachment, no ceremony. | ||
| **In practice:** Before building anything, ask "which goal does this serve?" If you can't answer, don't build it. | ||
| ## 2. Observe First, Implement Second | ||
| The system watches what actually happens in sessions before deciding what to improve. Instincts are extracted from real usage patterns, not imagined requirements. Skills are aggregated from multiple instincts that proved useful, not designed top-down. | ||
| This means: | ||
| - **No speculative features.** If a pattern hasn't been observed at least twice, it's not worth codifying. | ||
| - **Confidence decays.** An instinct that hasn't been referenced in 90 days loses relevance and gets pruned. | ||
| - **Evolution is pull-based.** The system improves where friction is observed, not where we guess it might be. | ||
| **In practice:** Run the system for a week before customizing. Your actual usage patterns are more valuable than your predictions about them. | ||
| ## 3. Quality Gates, Not Quality Hopes | ||
| Every evolved skill has an eval spec with scenario tests. Pass rate must hit 100% before a skill is considered stable. Discrimination (can the eval distinguish "has this skill" from "doesn't have it"?) is monitored to prevent gaming. | ||
| This means: | ||
| - A skill that passes eval is **proven useful** — not just written down. | ||
| - Evals that everything passes trivially are **worse than no evals** — they create false confidence. | ||
| - The eval system itself evolves (meta-evaluation) to stay honest. | ||
| **In practice:** If you can't write a scenario where the skill makes a difference, the skill probably doesn't matter. | ||
| ## 4. Mechanism-Agnostic Routing | ||
| The same behavioral improvement can be implemented as an instinct, a rule, a skill, a hook, a script, an agent, or an MCP integration. Homunculus picks the lightest mechanism that works: | ||
| | Need | Mechanism | | ||
| |------|-----------| | ||
| | Deterministic, no AI judgment needed | Hook or script | | ||
| | Path-specific guidance | Rule | | ||
| | Reusable knowledge with nuance | Skill (with eval) | | ||
| | Isolated, parallelizable work | Subagent | | ||
| | Scheduled automation | Cron / launchd | | ||
| Over time, implementations naturally migrate toward more deterministic mechanisms — an instinct becomes a rule, a rule becomes a hook. This is intentional: deterministic beats probabilistic when you know the answer. | ||
| **In practice:** Don't reach for the most powerful mechanism. Reach for the simplest one that handles the case. | ||
| ## 5. The Developer Decides | ||
| The system suggests; the human approves. Nightly evolution reports are *reports*, not automated deployments. Instinct extraction writes to a staging area, not directly to production rules. Research findings are tagged `[adoptable]` / `[informational]` — the developer chooses what to act on. | ||
| Autonomy is a spectrum, not a switch. The system earns trust incrementally: | ||
| - **Day 1:** Everything is a suggestion. | ||
| - **Week 2:** Proven patterns get auto-applied within guardrails. | ||
| - **Month 2:** The nightly agent handles routine evolution autonomously. | ||
| But the developer can always `git revert` any autonomous change. Reversibility is non-negotiable. | ||
| **In practice:** If you're not comfortable with a nightly agent making commits, start with `BUDGET_LEVEL=minimal`. Trust is built, not configured. | ||
| ## 6. Completeness Over Cleverness | ||
| In the AI era, the marginal cost of "complete and tested" vs. "works but fragile" is near zero. A 150-line implementation with tests beats an 80-line clever hack every time. | ||
| This applies to the evolution system itself: | ||
| - Skills include anti-patterns, not just expected behavior. | ||
| - Evals include boundary scenarios that probe edge cases. | ||
| - Reports include what was *rejected* and why, not just what was done. | ||
| **In practice:** When in doubt, add the test. When in doubt, document the decision. The cost of doing it now is always less than the cost of debugging it later. | ||
| --- | ||
| ## Non-Goals | ||
| Things we deliberately don't optimize for: | ||
| - **Generality.** Homunculus is opinionated about Claude Code. It's not a framework for all AI assistants. | ||
| - **Speed of evolution.** Slow, correct evolution beats fast, noisy evolution. One high-quality instinct per week is better than ten low-confidence ones per day. | ||
| - **Zero-config magic.** You need to define goals. You need to review reports. The system augments your judgment, not replaces it. | ||
| - **Backward compatibility.** This is a single-developer system by design. When a better approach exists, migrate fully — no shims, no dual paths, no deprecated aliases. |
+2
-9
@@ -131,3 +131,3 @@ # Architecture: Goal-Tree-Driven Evolution | ||
| ``` | ||
| Nightly P1 B1a reads instinct tags | ||
| Nightly P1 reads instinct tags | ||
| | | ||
@@ -194,10 +194,3 @@ +-- suggested_mechanism: hook → Write hook → Archive instinct | ||
| | | ||
| P0: Assigned tasks (priority:high) | ||
| P1: Evolution cycle | ||
| A: Session review + instinct harvesting | ||
| B1a: Implementation Routing (instinct → best mechanism) | ||
| B1b: Skill eval + improve | ||
| B2: Workflow evolution (skip_rate analysis) | ||
| B3: Subagent evolution (compliance analysis) | ||
| C: System health (21 health_checks + mechanism review + hook candidates) | ||
| P1: Evolution — instinct harvest → routing → skill eval → health check | ||
| P2: Research (cross-night dedup) | ||
@@ -204,0 +197,0 @@ P3: Experiments (hypothesis → verify → merge/discard) |
+6
-5
@@ -9,7 +9,8 @@ # Homunculus — Development Guide | ||
| 2. **README.md** — update What's New section + any affected docs | ||
| 3. **package.json** — bump version (semver: patch/minor/major) | ||
| 4. **git commit + push** — descriptive commit message | ||
| 5. **npm publish** — `npm publish` from repo root | ||
| 6. **GitHub release** — `gh release create vX.Y.Z` with release notes | ||
| 7. **assistant plan.md** — sync `~/assistant/projects/homunculus/plan.md` if applicable | ||
| 3. **i18n sync** — update `docs/zh-TW/README.md` and `docs/zh-CN/README.md` to match | ||
| 4. **package.json** — bump version (semver: patch/minor/major) | ||
| 5. **git commit + push** — descriptive commit message | ||
| 6. **npm publish** — `npm publish` from repo root | ||
| 7. **GitHub release** — `gh release create vX.Y.Z` with release notes | ||
| 8. **assistant plan.md** — sync `~/assistant/projects/homunculus/plan.md` if applicable | ||
@@ -16,0 +17,0 @@ ## Project Structure |
@@ -44,2 +44,51 @@ --- | ||
| ## Noise Tolerance | ||
| **5pp rule**: score delta < 5pp is statistical noise, not a real change. From Anthropic infrastructure noise research — environment variance alone can cause ±5pp swings. | ||
| - `|delta| < 5pp` → `not_significant` (treat as flat) | ||
| - `delta >= 5pp` → real improvement | ||
| - `delta <= -5pp` → real regression | ||
| ## Multiple-Run Modes | ||
| Three optional flags reduce measurement noise. Use independently or combined. | ||
| ### --runs N (eliminate infra noise) | ||
| `/eval-skill my-skill --runs 3` — runs the full eval N times independently, reports mean ± σ. | ||
| - Eliminates session-to-session infrastructure variance | ||
| - **Recommended for nightly agent evals**: `--runs 3` | ||
| - Daily manual evals: default N=1 is fine | ||
| ``` | ||
| 📊 Multi-Run Summary (runs=3): | ||
| Run 1: 85% Run 2: 87% Run 3: 83% | ||
| Mean: 85.0% | σ: 1.6pp | ||
| Verdict: not_significant vs baseline 84% (delta=1pp < 5pp threshold) | ||
| ``` | ||
| ### --passes N (reduce per-scenario LLM noise) | ||
| `/eval-skill my-skill --passes 3` — each scenario evaluated N times, majority vote decides. | ||
| - PASS in >N/2 runs → final PASS (PARTIAL counts as 0.5) | ||
| - **Recommended: N=3** — reduces misjudgment from p to 3p²-2p³ | ||
| ### --pass-k K (measure reliability distribution) | ||
| `/eval-skill my-skill --pass-k 3` — reports pass@k and pass^k per scenario. | ||
| | Metric | Meaning | | ||
| |--------|---------| | ||
| | `pass@k` | At least 1 pass in k tries (exploration rate) | | ||
| | `pass^k` | All k passes (reliability rate) | | ||
| Use to distinguish "sometimes works" from "always works". | ||
| ### Combining flags | ||
| `--runs R --passes P --pass-k K` = R × P × K × scenarios. Use sparingly — `--runs 3` alone is usually enough. | ||
| ## Majority Vote (--passes) | ||
@@ -65,5 +114,22 @@ | ||
| ### Theory | ||
| From Majority Voting / pass@k research: N=3 majority vote reduces misjudgment rate from p to 3p²-2p³ (at p=0.3: from 30% to 22%). | ||
| ## Gaming Gate | ||
| Score jumps >5pp but net new lines ≤ 3 → `gaming_suspected`, discard the improvement. | ||
| Real skill improvement requires substantive additions (new patterns, new examples, new sections). Rephrasing existing content to match scenario wording inflates LLM-judge scores without adding knowledge. | ||
| **Signs of gaming:** | ||
| - Score +8pp but skill only changed 2 lines | ||
| - New wording mirrors scenario's `expected_behavior` verbatim | ||
| - Discrimination rate unchanged despite score increase | ||
| When `gaming_suspected`: revert, add genuinely missing knowledge instead. | ||
| ## Anti-Gaming Scenario Design | ||
| 1. **Boundary scenarios are key** — discrimination comes from edge cases the skill uniquely handles | ||
| 2. **Don't mirror expected_behavior wording** — scenarios should test understanding, not recall | ||
| 3. **Discrimination > 30%** is healthy — if all scenarios pass without the skill, eval isn't testing anything | ||
| 4. **Gradual improvement** — legitimate gains are 2-5pp per round, not 15pp jumps | ||
| ## After Evaluation | ||
@@ -70,0 +136,0 @@ |
@@ -47,2 +47,6 @@ --- | ||
| ## Gaming Gate | ||
| If score jumps >5pp but net new lines ≤ 3 → **gaming_suspected**. Revert and add genuinely missing knowledge instead. See `/eval-skill` Gaming Gate section for details. | ||
| ## Notes | ||
@@ -49,0 +53,0 @@ - Only modify the skill file, never the eval spec (tests stay fixed) |
@@ -5,3 +5,3 @@ #!/usr/bin/env node | ||
| // | ||
| // v0.9.0: Three-layer extraction, dynamic daily cap, semantic dedup, Write Gate | ||
| // v0.10.0: + Durability Gate (score < 0.7 filtered), + CLAUDE.md coverage check (avoid re-extracting implemented rules) | ||
| // | ||
@@ -175,2 +175,25 @@ // Flow: | ||
| // Read goal tree names for goal_path tagging | ||
| // Get [MUST]/[SHOULD] rules from CLAUDE.md to avoid extracting already-implemented patterns | ||
| function getImplementedRulesSummary() { | ||
| try { | ||
| const candidates = [ | ||
| path.join(BASE_DIR, 'CLAUDE.md'), | ||
| path.join(BASE_DIR, '..', 'CLAUDE.md'), | ||
| ]; | ||
| for (const p of candidates) { | ||
| if (!fs.existsSync(p)) continue; | ||
| const content = fs.readFileSync(p, 'utf8'); | ||
| const rules = []; | ||
| for (const line of content.split('\n')) { | ||
| if (/\*\*\[MUST\]\*\*|\*\*\[SHOULD\]\*\*/.test(line)) { | ||
| rules.push(line.trim()); | ||
| if (rules.length >= 25) break; | ||
| } | ||
| } | ||
| return rules.join('\n'); | ||
| } | ||
| } catch { /* ignore */ } | ||
| return ''; | ||
| } | ||
| function getGoalHint() { | ||
@@ -198,2 +221,3 @@ try { | ||
| const existingWithTitles = getExistingInstinctsWithTitles(); | ||
| const implementedRules = getImplementedRulesSummary(); | ||
@@ -220,2 +244,15 @@ const prompt = `Analyze this Claude Code session and extract reusable behavioral patterns. | ||
| ## Durability Gate (required field) | ||
| Every instinct must include a **durability_score** (0.0–1.0): | ||
| - **0.9–1.0**: Universal truths across projects/years (e.g. flock for re-entry, launchd vs cron) | ||
| - **0.7–0.8**: Stable patterns for this system, expected valid 3–12 months | ||
| - **0.5–0.6**: Event-specific or short-cycle patterns (OSS launch tactics, campaign rhythms) → **fails gate** | ||
| - **0.3–0.4**: Highly context-specific to this session → not an instinct | ||
| Rule: ask "will this still matter in 3 months? 6 months?" — durability_score < 0.7 → do not produce instinct. | ||
| ${implementedRules ? ` | ||
| ## Already Implemented Rules (do NOT re-extract as instincts) | ||
| The following rules are already in CLAUDE.md. Skip any instinct that duplicates these: | ||
| ${implementedRules} | ||
| ` : ''} | ||
| ## Implementation Mechanisms (for suggested_mechanism) | ||
@@ -227,4 +264,4 @@ hook (deterministic, every time) | rule (path-scoped guidance) | skill (reusable knowledge with eval) | script (periodic automation) | agent (isolated context specialist) | system (infrastructure) | ||
| ### A. Instincts (behavioral patterns) | ||
| Find 1-2 reusable patterns (confidence > 0.7, must pass Write Gate): | ||
| {"type": "instinct", "name": "kebab-case-name", "confidence": 0.8, "title": "Pattern title", "content": "Full instinct description", "suggested_mechanism": "hook|rule|skill|script|agent|system", "goal_path": "top_goal.sub_goal or unrooted", "supersedes": []} | ||
| Find 1-2 reusable patterns (confidence > 0.7, must pass Write Gate and Durability Gate): | ||
| {"type": "instinct", "name": "kebab-case-name", "confidence": 0.8, "durability_score": 0.8, "title": "Pattern title", "content": "Full instinct description", "suggested_mechanism": "hook|rule|skill|script|agent|system", "goal_path": "top_goal.sub_goal or unrooted", "supersedes": []} | ||
@@ -294,2 +331,8 @@ - supersedes: if this new pattern semantically replaces an existing instinct, list its name. Leave [] if unsure. | ||
| // Durability gate: reject short-lived or event-specific patterns | ||
| if (entry.durability_score !== undefined && entry.durability_score < 0.7) { | ||
| log(` Durability gate filtered: ${entry.name} (score=${entry.durability_score})`); | ||
| break; | ||
| } | ||
| const name = entry.name.replace(/[^a-z0-9-]/g, '-'); | ||
@@ -296,0 +339,0 @@ if (existing.includes(name)) { |
+19
-3
@@ -6,3 +6,3 @@ #!/usr/bin/env bash | ||
| # | ||
| # v0.9.0: Added noise filtering, reference tracking, skill name enrichment | ||
| # v0.10.0: + InstructionsLoaded noise filter, + Bash failure circuit breaker | ||
@@ -54,4 +54,4 @@ set -euo pipefail | ||
| ;; | ||
| # Skip entirely: read-only tools provide no actionable patterns | ||
| Glob|Grep|TodoWrite|TodoRead) | ||
| # Skip entirely: read-only tools and internal events provide no actionable patterns | ||
| Glob|Grep|TodoWrite|TodoRead|InstructionsLoaded) | ||
| exit 0 | ||
@@ -69,2 +69,18 @@ ;; | ||
| [ "$PHASE" = "pre" ] && exit 0 | ||
| # Circuit breaker: track consecutive Bash failures for evolution analysis | ||
| if [ "$TOOL_NAME" = "Bash" ] && [ -n "$INPUT" ] && command -v jq &>/dev/null; then | ||
| BASH_FAILURES="/tmp/homunculus-bash-failures" | ||
| EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_result.exit_code // empty' 2>/dev/null) | ||
| BASH_CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) | ||
| if [ -n "$EXIT_CODE" ] && [ "$EXIT_CODE" != "0" ] && [ -n "$BASH_CMD" ]; then | ||
| PREFIX="${BASH_CMD:0:40}" | ||
| [ -f "$BASH_FAILURES" ] || echo "[]" > "$BASH_FAILURES" | ||
| jq -c --arg p "$PREFIX" --arg ts "$TIMESTAMP" --arg ec "$EXIT_CODE" \ | ||
| '. + [{prefix: $p, timestamp: $ts, exit_code: $ec}] | .[-10:]' \ | ||
| "$BASH_FAILURES" > "${BASH_FAILURES}.tmp" 2>/dev/null \ | ||
| && mv "${BASH_FAILURES}.tmp" "$BASH_FAILURES" || true | ||
| elif [ -n "$EXIT_CODE" ] && [ "$EXIT_CODE" = "0" ]; then | ||
| echo "[]" > "$BASH_FAILURES" 2>/dev/null || true | ||
| fi | ||
| fi | ||
| ;; | ||
@@ -71,0 +87,0 @@ esac |
@@ -37,4 +37,3 @@ # Nightly Agent | ||
| |-------|-------------| | ||
| | **P0** | Complete assigned high-priority tasks | | ||
| | **P1** | Evolution cycle — extract instincts + memory suggestions + research topics, route instincts to 8 mechanisms (hook/rule/skill/script/agent/...), eval + improve skills, review goal implementations | | ||
| | **P1** | Evolution — extract instincts from today's sessions, route each to its best mechanism (hook/rule/skill/script/agent/...), eval + improve skills, health check | | ||
| | **P2** | Research — scan tech news, changelogs, community (with cross-night dedup) | | ||
@@ -41,0 +40,0 @@ | **P3** | Experiments — generate hypotheses from weak goals, test in isolated worktrees | |
+1
-1
| { | ||
| "name": "homunculus-code", | ||
| "version": "0.9.0", | ||
| "version": "0.10.0", | ||
| "description": "A self-evolving AI assistant that grows smarter every night", | ||
@@ -5,0 +5,0 @@ "bin": { |
+17
-15
@@ -0,1 +1,3 @@ | ||
| **Language:** [English](README.md) | [繁體中文](docs/zh-TW/README.md) | [简体中文](docs/zh-CN/README.md) | ||
| # Homunculus for Claude Code | ||
@@ -22,3 +24,3 @@ | ||
| > **Proof it works:** One developer ran this system for 3 weeks. It auto-generated 190 behavioral patterns, routed them into 10 tested skills, created 3 specialized agents, 15 commands, and 24 automation scripts. The nightly agent made 368 autonomous commits — improving the system while the developer slept. [See results →](#real-world-results) | ||
| > **Proof it works:** One developer ran this system for 5 weeks. It auto-generated 229 behavioral patterns, routed them into 10 tested skills, created 4 specialized agents, 18 commands, and 37 automation scripts. The nightly agent made 1,500+ autonomous commits — improving the system while the developer slept. [See results →](#real-world-results) | ||
@@ -443,3 +445,3 @@ --- | ||
| In our reference system, the nightly agent produced **155 autonomous commits** — routing instincts to the right mechanisms, evolving skills, running experiments, researching better approaches, and archiving outdated patterns. All without any human input. | ||
| In our reference system, the nightly agent produced **1,500+ autonomous commits** — routing instincts to the right mechanisms, evolving skills, running experiments, researching better approaches, and archiving outdated patterns. All without any human input. | ||
@@ -454,3 +456,3 @@ The nightly agent is what turns Homunculus from "a tool you use" into "a system that grows on its own." | ||
| Built and tested on a real personal AI assistant. In **3 weeks** (starting from zero): | ||
| Built and tested on a real personal AI assistant. In **5 weeks** (starting from zero): | ||
@@ -460,15 +462,15 @@ | What evolved | Count | Details | | ||
| | Goal tree | **10 goals / 46+ sub-goals** | Each with health checks and metrics | | ||
| | Instincts | **190** | 33 active + 157 auto-archived (system prunes itself) | | ||
| | Skills | **10** | All 100% eval pass rate (152 test scenarios) | | ||
| | Experiments | **15** | Structured A/B tests with pass/fail tracking | | ||
| | Subagents | **3** | Auto-extracted from repetitive main-thread patterns | | ||
| | Scheduled agents | **5** | Nightly heartbeat, Discord bridge, daily news, trading × 2 | | ||
| | Hooks | **11** | Observation, compaction, quality gates | | ||
| | Scripts | **24** | Session lifecycle, health checks, evolution reports | | ||
| | Slash commands | **15** | Workflow automations (forge-dev, quality-gate, eval...) | | ||
| | Rules | **6** | Core patterns, evolution system, knowledge management | | ||
| | ADRs | **8** | Architecture decision records | | ||
| | Total commits | **1,367+** | Mostly automated by nightly agent | | ||
| | Instincts | **229** | 1 active + 228 auto-archived (mature system: most patterns absorbed into skills) | | ||
| | Skills | **10** | All 100% eval pass rate | | ||
| | Experiments | **20** | Structured A/B tests with pass/fail tracking | | ||
| | Subagents | **4** | Auto-extracted from repetitive main-thread patterns | | ||
| | Scheduled agents | **4** | Nightly heartbeat, Discord bridge, daily news, trading | | ||
| | Hooks | **8** | Observation, compaction, quality gates, session lifecycle | | ||
| | Scripts | **37** | Session lifecycle, health checks, evolution reports | | ||
| | Slash commands | **18** | Workflow automations (forge-dev, quality-gate, eval...) | | ||
| | Rules | **7** | Core patterns, evolution system, knowledge management | | ||
| | ADRs | **9** | Architecture decision records | | ||
| | Total commits | **1,688+** | Mostly automated by nightly agent | | ||
| The nightly agent alone: **368 autonomous commits**. | ||
| The nightly agent alone: **1,500+ autonomous commits**. | ||
@@ -475,0 +477,0 @@ The system even evolved its own task management board: |
New alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
531032
15.22%- Number of package files
68
9.68%- Lines of code
1423
2.97%- Number of lines in readme file
652
0.31%Worsened metrics
- Number of low supply chain risk alerts
18
5.88%No dependency changes