back
loading skill details...
火一五·克劳德·龙虾增强插件 v6.7.13 — large-file-bridge 兜底死循环修 + 用户上传后流程引导:实测用户『我已经上传好了』后 AI 没调 enhance_upload_check 反被兜底又塞了一份上传链接死循环。根因:before_agent_reply 每轮都触发,injected...
---
name: huo15-huo15-openclaw-enhance
description: "火一五·克劳德·龙虾增强插件 v6.7.13 — large-file-bridge 兜底死循环修 + 用户上传后流程引导:实测用户『我已经上传好了』后 AI 没调 enhance_upload_check 反被兜底又塞了一份上传链接死循环。根因:before_agent_reply 每轮都触发,injectedSessions 有 entry + body 不含 URL → 强制 appendText 链接。修法:(1) entry 加 replyAppendUsed 标记,每次 inject 兜底只 fire 一次;(2) prompt 加『用户上传后处理流程』,明确 LLM 看到『传完了』必须 enhance_upload_check({token}) → Read → 处理任务,严禁再发链接 / 反问 / 全盘扫。Use when: 给 OpenClaw 加非侵入式增强(不改龙虾核心、不复制原生功能)。"
version: 6.7.13
homepage: https://cnb.cool/huo15/ai/huo15-openclaw-enhance
metadata: { "openclaw": { "emoji": "🦞", "requires": { "bins": [] } } }
---
# 火一五·克劳德·龙虾增强插件 v5.7.8
## 简介
`@huo15/openclaw-enhance` 是 **OpenClaw 2026.4.24+** 的**非侵入式**增强插件,对标 Claude Code 的 Agent Harness 体验。
**核心原则**:凡是龙虾原生有的功能一律不复制,重叠处以龙虾为准;只补龙虾没有的 Claude-Code 体验。
## v5.7.8 全面适配 openclaw 2026.4.24(2026-04-26 同日)
跑完整 SOP 第 1+2 步发现 openclaw 4.24 的 `api.on` 是**完全 typed**(`<K extends PluginHookName>(hookName: K, handler: PluginHookHandlerMap[K])`),enhance 之前 14 处 `api.on(...as any)` 都能去掉 cast。这是真正的"全面适配"——不是简单升 peerDep,而是让 enhance 利用 SDK 的全部类型信息。
| 维度 | v5.7.7 | v5.7.8 |
|---|---|---|
| `peerDependencies.openclaw` | `^2026.4.22` | **`^2026.4.24`** |
| `build.openclawVersion` | `2026.4.11`(落后 13 patch)| **`2026.4.24`** |
| `compat.pluginApi` | `>=2026.4.11` | **`>=2026.4.24`** |
| `api.on(...as any)` 使用次数 | 14 处 | **0 处** |
| `(event: any, ctx: any)` 使用次数 | 5 处 | **0 处** |
| `(ctx as any)?.agentId` 模式(hook 内部)| 9 处 | **0 处**(仅余 4 处 helper 函数内部,工具 ctx 用) |
| typecheck 错误数 | 0 | **0** |
| openclaw.plugin.json 顶层字段 | 5 | **8**(加 `enabledByDefault` / `uiHints` / `activation`)|
### 隐藏 bug 修复
去掉 `as any` 后 typecheck 暴露 **self-check.ts 长期被屏蔽的类型不匹配**:之前 `return {};` 试图返回 `PluginHookBeforeAgentReplyResult`,但该类型 `handled: boolean` 是必填的——空对象不合规。修法:所有"不接管"分支改成 `return;`(void),仅"阻断空回复"分支返回 `{ handled: true, reply: ..., reason: ... }`。
### 不破坏 openclaw 原生
- 所有 hook handler **return undefined(void)** — 不返回 `{block, prependContext}` 等控制信号时 → enhance 仅观察+附加,绝不改变 openclaw 决策
- typed hook handler 实际行为跟 untyped 完全一致 — 只是 TS 编译期能 narrow 类型,运行时无差异
- manifest 新加的 `enabledByDefault` / `uiHints` / `activation` 都是 openclaw 4.x 已有字段,不引入新依赖
## v5.7.7 session-lifecycle(2026-04-26 同日,跑完整 gap 调研后落地)
**调研依据**:跑了一次完整 SOP 第 1+2 步(Claude Code 官方 hooks 文档 + 反编译 Claude.app + openclaw 4.22 SDK)。发现 **openclaw 4.22 暴露 29 个 hook,enhance 之前只用 4 个**。落地最高 ROI 的 5 个 hook 闭环 session 生命周期:
| Hook | enhance 行为 | 落地表 |
|---|---|---|
| `session_start` | idle > 30min 时插入"🚀 会话开始/续启"章节占位 | `chapters` |
| `session_end` | 加"🏁 会话结束"章节 + flush in_progress todo 到 project memory(tag=session-flush, importance=4) | `chapters` + `memories` |
| `before_reset` | reset 前最后机会抢救最近 3 章节 + 全部未完成 todo 到 decision memory(tag=reset-rescue, importance=6)+ 推 notification | `memories` |
| `subagent_spawned` | 派生子 agent 时加"🤖 派生子 agent: X"章节 | `chapters` |
| `subagent_ended` | 子 agent 结束加"✅/❌ 子 agent 结束: X"章节 | `chapters` |
**防 noise factory 三层防御**(吸收 v5.7.1 教训):30 秒 dedup + 低 importance + 专用 tag(不进黑名单,用户下次会想恢复)。
## v5.7.5 skill-recommender(2026-04-26 同日)
**用户反馈**:"新增自动根据用户的需求自动挑选已经安装的技能,如果没有技能就把规划方案给出来。看看 Claude 是如何做的"
**调研**:反编译 `/Applications/Claude.app/Contents/Resources/app.asar`,发现 Claude 的 skill auto-discovery **本质是把所有 skill 的 name+description 拼成 `"Available skills: ${list}."` 注入到 specialist agent 的 system prompt** —— 没有复杂算法,让 LLM 自己挑。
**enhance 改造**:照搬 name+description 匹配思路,但**改成按需工具**避免每轮 prompt 占 schema。新增模块 `skill-recommender` + 工具 `enhance_skill_recommend(query, limit?, includeUninstalled?, includePlanning?)`:
1. **启动期扫多路径**(WeCom / DingTalk 多 agent 场景关键):
- `~/.openclaw/skills/`
- `~/.openclaw/workspace/skills/`
- `~/.openclaw/workspace-*/skills/` ← **WeCom 多 agent 动态 workspace**(一开始漏扫,烟测才发现)
- `~/.openclaw/agents/*/skills/`
- `<cwd>/.claude/skills/`、`~/.claude/skills/`
- 实测用户机器扫到 56 个 skill 跨 27 个路径
2. **解析 SKILL.md frontmatter**(轻量正则,无 yaml 依赖):name + description + aliases
3. **CJK 双字滑窗 + alias 强 boost** 评分:
- JS `\w` 不含中日韩,直接 split `\s\W` 会让"代码简化"分成空数组
- 解决:CJK 连续段当整体 phrase + 长 ≥4 时滑动 2-grams
- alias 的 token 严格命中(如 "规划" === alias "规划")→ 保底 0.7 分
4. **三段式输出**:
- 🎯 已装 skill(命中 ≥ threshold=0.25)+ 召唤建议
- 📦 ClawHub 上未装的 huo15-* 候选(含 `openclaw skills install` 命令)
- 🛠️ 都没合适 → **自建 skill 规划**:建议 slug + frontmatter 模板 + 触发关键词 + 内容大纲 + **红线 #3 提醒**(必须先 ClawHub publish 再让 enhance 引用 slug,插件不内嵌 skill 内容)
**实测**:
| 查询 | 命中 | 分数 |
|---|---|---|
| "帮我 review 这个 PR" | huo15-openclaw-code-review | 0.60 |
| "设计一个 Web UI 原型" | huo15-openclaw-frontend-design | 0.94 |
| "代码简化" | huo15-openclaw-simplify | 1.00 |
| "做安全审查" | huo15-openclaw-security-review | 0.96 |
| "规划这个任务" | huo15-openclaw-plan-mode | 0.70(alias exact 命中保底)|
模块 `tier=2`(balanced 默认启用,minimal 不暴露 — 用户多半已知道用什么 skill)。
## v5.7.4 config-doctor 扩展:扫已装插件 bare pluginApi(2026-04-26 同日)
**用户反馈**:"提示插件要求 2026.2.24,但是我的 openclaw 已经是 2026.4.22"
**根因**:openclaw plugin compat 规则要求 `compat.pluginApi` 必须是 ranged spec(`>=X.Y.Z` / `^X.Y.Z` / `~X.Y.Z`)。**bare 字符串(如 `"2026.2.24"` 没前缀)= 精确匹配**,与当前 openclaw 不匹配时启动失败。用户实测:
- `~/.openclaw/extensions/tips/package.json` v1.0.0 → `pluginApi: "2026.4.11"` ❌
- `~/.openclaw/node_modules/@huo15/huo15-huihuoyun-odoo/package.json` v1.2.0(npm peerDep 残留)→ `pluginApi: "2026.2.24"` ❌
**新增**:`config-doctor` 启动期扫描 `~/.openclaw/extensions/*` + `~/.openclaw/node_modules/@huo15/*` + 无 scope 的 `node_modules/*`,对每个声明 `openclaw.extensions` 的包检查 `compat.pluginApi`。bare 命中 → 推仪表盘 + log warn + 给可粘贴 fix 命令。
```
⚠️ [plugin-bare-pluginApi] 已装插件 @huo15/wecom-tips 的 openclaw.compat.pluginApi="2026.4.11" 是 bare 版本,会被解读为精确匹配...
→ 修复: python3 -c "..."(一行 inline)
```
## v5.7.3 config-doctor(2026-04-26 同日)
直击用户高频反馈"装上插件还是 'Context limit exceeded'" — 根因往往不在插件,而在 `~/.openclaw/openclaw.json` 的两处陷阱:
1. **缺失 `agents.defaults.compaction.reserveTokensFloor`** — openclaw 4.22 把这个字段嵌套到 `agents.defaults` 里(4.11 时是顶层 `compaction`),老用户配置文件没自动迁移,用 4.22 默认值(很小)→ 长 session 必爆
2. **某个 model 的 `maxTokens` 占 `contextWindow` 一半以上** — 例如 MiniMax-M2.7 默认 maxTokens=131072 / contextWindow=204800,每轮预留输出就吃掉 64% budget。openclaw 把 maxTokens 当作"必须留给输出的 reserve",剩 73k 给 input/tools/memory,**任意几轮就爆**
### 新增
- **`src/modules/config-doctor.ts`** — 启动期 sync 读 openclaw.json 检查上述两类陷阱,发现后用 `notifyQueue.emit("config-doctor", ...)` 推到仪表盘 + log warn + 给可粘贴的 fix 命令(python3 一行原地改 JSON,**不调 child_process**)
- **工具:`enhance_config_doctor`** — 无参数,agent / 用户随时调一下,重新跑诊断(修完了配置可以再跑确认 ✅)
- **配置项:`config.configDoctor`** — `enabled` / `minReserveTokensFloor`(默认 5000)/ `maxReserveTokensFloor`(默认 100000)/ `maxModelMaxTokens`(默认 32000)
### 红线遵守
- **完全只读** ~/.openclaw/openclaw.json(红线 #1:不侵入式修改 openclaw)
- **不调 child_process**(红线 #4) — 修复命令是 python3 inline,由用户/cron-cli 执行
- **不暴露在 minimal 之外**?反过来:**tier=1 minimal 也启用** — 这是关键的"防爆 context"诊断,每个用户都该有
## v5.7.2 hardening(2026-04-26 同日)
继 v5.7.1 hot-fix 之后,对全代码库做了一次审计,修复 4 类潜在 bug:
- **进程内 Map LRU 上限** — `mode-gate` 的 `modeState` / `plannedActions` 和 `session-recap` 的 `lastRecapAt` 之前 keyed by `agentId::sessionId` **跨 session 永不清**。WeCom 多用户场景下 100+ session 会无限累积。现在加 200/200/500 三档 LRU cap,活跃 session 重新插入刷新顺序,老 session 自动淘汰
- **safety_log / notifications 启动期 TTL** — `getDb()` 时跑一次 `DELETE WHERE created_at < datetime('now', '-90 days')`,避免长期运行库无限增长。新增 `purgeOldSafetyLogs(retentionDays)` helper 给运维调
- **memory corpus tag 黑名单** — `auto-compact` / `auto-checkpoint` / `audit` / `internal` 这 4 个保留 tag 在 `scoreRelevance()` 入口直接 return 0,永不召回到 prompt(防御未来 hook 万一又写入 noise)
- **enhance_memory_store 拒收保留 tag** — 用户/agent 显式调 store 时若 tags 含保留词,立即返回错误而非写入
### bump openclaw peerDep `^2026.4.22`
之前 peerDep `>=2026.4.11`,但 npm global 已升到 2026.4.22(差 11 个 patch)。本地 SDK 类型定义同步升级;hook 名验证全部仍存在(`before_prompt_build` / `before_tool_call` / `after_tool_call` / `before_compaction` / `before_agent_reply`),无破坏性变更。
## v5.7.1 hot-fix(2026-04-26)
- **删除 `before_compaction` 噪音 hook** — 之前每次 openclaw auto-compact 都会以 `decision` 类、`auto-compact` tag 写入一条「[auto-compact] 对话上下文已压缩…」记忆。实测单 agent 24 小时积累 613 条全是噪音,关键词命中率虚高 0.4-0.5(过 corpus pruner 默认 0.5 阈值),把真正的 user/project/feedback 决策记忆挤出 prompt 上下文
- **新增工具 `enhance_memory_purge`** — 按 `tag` / `category` / `contentLike` 批量清理当前 agent 记忆,`dry_run` 默认 true(仅预览匹配数)。一键清理历史噪音:`enhance_memory_purge tag="auto-compact" dry_run=false`
- **首次启动自动迁移**:升级到 5.7.1 后即不再生成新噪音;旧噪音留待用户用 purge 工具或直接 SQL 清
## v5.7 新特性(2026-04-25)
- **历史会话搜索(transcript-search)** — 照搬 Claude Desktop `transcriptSearchWorker` 算法(解包 `/Applications/Claude.app/Contents/Resources/app.asar` 抽出参考实现):
- 流式扫 `~/.openclaw/agents/<agentId>/sessions/*.jsonl`,行级 JSON.parse
- `extractText` 兼容 `string` / `[{type:"text", text}]` 数组
- `indexOf` 子串匹配 + ±80 字符 snippet
- 79 个 session 中扫 30 个 → 3–5 ms 找到 5 个 hits(实测)
- 完全只读、不建索引、不建表 — 不动 openclaw 任何东西
- **工具:`enhance_transcript_search`** — `query` 必填;可选 `agentId / limit / includeReset / caseSensitive`
- 模块 tier=2,默认 balanced/full 即可见(minimal 下不暴露)
## v5.6 新特性(2026-04-24)
- **工具分层(toolTier)** — 按 minimal/balanced/full 三档暴露工具 schema,降低每轮 prompt 固定底座(解决长会话 context 提早爆满)
- `minimal`(10 工具):仅核心层 — 记忆 / 状态栏 / spawn / 模式 / 章节 / installer / integrator
- `balanced`(18 工具,默认):+ todo / 章节 / 定时任务桥
- `full`(26 工具):+ workflow / safety / task-planner / session-recap / skill-doctor
- **Workflow 5→2 工具合并** — `enhance_workflow_define / _list / _delete / _tasks / enhance_task` 合并为 `enhance_workflow`(action=define/list/delete/tasks)+ `enhance_task`(保留独立 action 派发器)
- **工具描述全面压缩** — 26 个工具描述从 ~4610 字符 → ~1750 字符(-62%),每轮 prompt 节省约 1400 token,prompt cache 更稳
## 一键安装
```bash
openclaw plugins install @huo15/openclaw-enhance
openclaw restart
```
安装后访问仪表盘:`http://localhost:18789/plugins/enhance/`
## 核心能力
- **分类记忆(corpus supplement + 两段式)** — user / project / feedback / reference / decision 五类,额外支持 `why`(背景/约束)和 `howToApply`(套用时机),对齐 Claude Code feedback/project 记忆体例;通过 `registerMemoryCorpusSupplement` 合入龙虾原生 memory 搜索,**不自建第二套向量库**;搜索结果 deterministic 排序(score → importance → updated → id)保持 prompt cache 稳定
- **工具安全观察员** — 只分类错误 + 建议退避,完全尊重龙虾 `tools.allow/deny`
- **任务 / 章节 / 模式闸门 + ExitPlanMode** — TodoWrite / mark_chapter / plan-explore 模式;`enhance_exit_plan_mode` 在 plan 模式下提交计划给用户审批,自动把计划期间被拦截的写入意图打包成 decision 记忆
- **状态栏(含可观测性)** — `enhance_statusline` 额外展示当前模型、思考档、fast 模式、消息通道、会话 ID;HTTP 端点 `/plugins/enhance/api/statusline` 输出 JSON 供仪表盘嵌入
- **技能巡检 / 子任务一键派发** — `enhance_spawn_task` 返回可直接粘贴到终端的 `openclaw agent` CLI 命令,支持跨 agent 派发和思考档选择
- **定时任务桥** — 登记定时工作流时返回一条 `openclaw cron add` 命令;**调度归龙虾 cron-cli**,插件只管触发时注入 instructions
- **多 Agent 隔离** — 完美适配 WeCom 插件的动态 Agent,记忆/任务/章节/宠物全部按 `agentId` 隔离
- **增强仪表盘** — 小火苗宠物 + 记忆/任务/章节/定时全景
## 与龙虾原生的关系
| 能力 | 龙虾原生 | enhance 策略 |
|------|---------|--------------|
| 记忆向量库 | ✅ 龙虾负责 | 不复制,改为 corpus supplement 并入搜索 |
| 工具 allow/deny | ✅ 龙虾负责 | 只观察,不拦截 |
| Cron 调度 | ✅ 龙虾 cron-cli | 不管理调度,只在触发时注入上下文 |
| 技能安装 | ✅ ClawHub | 只读巡检,不擅自安装 |
## 增强技能(自动注入 `workspace/skills/`)
**工作流模式(4 个)**
- `huo15-openclaw-plan-mode` — 结构化规划模式
- `huo15-openclaw-explore-mode` — 深度探索模式
- `huo15-openclaw-verify-mode` — 验证检查模式
- `huo15-openclaw-memory-curator` — 记忆整理
**设计能力(v5.4 新增,对标 Anthropic frontend-design + huashu-design 生态)**
- `huo15-openclaw-frontend-design` — 高保真 Web UI 原型 + 5 美学流派 + 反 AI Slop 硬红线
- `huo15-openclaw-design-director` — 设计方向顾问(3 方向反差对比 + 强制推荐)
- `huo15-openclaw-brand-protocol` — 品牌规范抓取(Ask/Search/Download/Verify/Codify 5 步)
- `huo15-openclaw-design-critique` — 5 维设计评审(美学/可用性/品牌/内容/实现)
**开发辅助(v5.5.1 新增,对标 Claude Code /simplify / /security-review / /review)**
- `huo15-openclaw-simplify` — 代码简化三维审查(复用/质量/效率)+ 分级修复清单
- `huo15-openclaw-security-review` — 六类漏洞矩阵(密钥/注入/XSS/SSRF/权限/依赖)+ CVSS 分级
- `huo15-openclaw-code-review` — PR 五维综合评审(设计/实现/测试/安全/可维护)+ 可粘贴评论
详见 [README.md](./README.md) 与 [CHANGELOG.md](./CHANGELOG.md)。
## 链接
- npm: https://www.npmjs.com/package/@huo15/openclaw-enhance
- 仓库: https://cnb.cool/huo15/ai/huo15-openclaw-enhance
- License: MIT
- 公司: 青岛火一五信息科技有限公司 — www.huo15.com
don't have the plugin yet? install it then click "run inline in claude" again.