mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00

Files

JianFeeeee 1b6cd57dca fix(skillmgr): 内核旧版 skill 永不更新 —— 无 stamp 不等于"用户改过"

## 缺陷（实测，非推测）

给 kernel-plugins 补上 `skill_info(name, section=...)` 的用法说明后，
改了嵌入内容，但**生产上永远不会更新**：

    /home/hologramagent/skills/kernel-plugins/   mtime 2026-10-26，无 .builtin-sha256
    嵌入版本 1.1.0   vs   磁盘版本 1.0.0

`materializeBuiltinSkills` 的判断链是：

    builtinSkillUnmodified(dir)  → 读 .builtin-sha256
                                  没有 stamp ⇒ false
    ⇒ continue（"用户改过或无法确认，保留人的版本"）

而 stamp 机制是 387ae94（今天早些时候）引入的。生产机上这份 skill
是**更早的内核**写的 —— 它没有 stamp，于是被永久判为"来历不明"。

后果不只是这一份文档：任何在 stamp 机制之前部署的机器，其内核自带
skill 都停在旧版。而 kernel-* 系列正是教模型怎么用工具/记忆/终端的
文档 —— 内核改进了文档，模型永远看不到。

## 修法：用 frontmatter version 区分两种"没有 stamp"

原判据把两件事混成一件：

    用户改过措辞        ⇒ 必须保留
    内核在 stamp 之前写的 ⇒ 应该升级

新增 builtinSkillOutdated(dir, embedded)：只在**没有 stamp** 时被调用，
判据是磁盘 frontmatter 的 `version` 严格低于内嵌版本。

安全性分析（写在代码注释里）：
    人改措辞         通常不动 version ⇒ 不低于 ⇒ 保留 ✓
    人把 version 改高                        ⇒ 保留 ✓
    内核旧版（无 stamp）                      ⇒ 升级 ✓（这正是要修的）
    解析不出版本号                            ⇒ 返回 false ⇒ 保留（保守）
误升级的唯一条件是"人把 version 改低"，而那本身就意味着放弃内核版本。

原有的四条保守判据（含 NoStampIsConservative）全部保持绿。

## 判据抓到了我自己写的 bug

TestCompareVersion 立刻红了：

    compareVersion("1.0","1.0.0")=-1，期望 0

原因：缺失段留成空串 ⇒ Atoi("") 失败 ⇒ 落到字符串比较 ⇒ `"" < "0"`
⇒ 版本号少写一段的 skill 会被无谓地重复升级。改为缺失段视为 "0"。

## 变异验证

  builtinSkillOutdated 恒 return false（= 修复前行为）
      ⇒ TestMaterializeBuiltinSkills_UpgradesStaleKernelVersion 红：
        "★ 没有 stamp 的内核旧版（version 0.0.1）没被升级"

  compareVersion 缺失段改回空串
      ⇒ TestCompareVersion 红："compareVersion(\"1.0\",\"1.0.0\")=-1，期望 0"

## 顺带：kernel-plugins v1.1.0

补一节「Reading a skill without burning context」，说明：
  - 长文档返回目录 + 开头 30 行，目录每行带 (N 行)
  - `section` 可按编号或标题子串取，大小写不敏感，容忍 `##` 前缀
  - 顶层章节返回整棵子树
  - 未命中会列出全部可用章节
  - 章节边界尊重围栏代码块

## 验证

    go build ./...            PASS
    go vet ./...              PASS
    gofmt -l                  干净
    go test ./... -count=1    62 包全过，0 FAIL
    干净检出（worktree）       build + skillmgr 全绿

（包数 63 → 62 是因 clawhubadapter 已在 a0077a2 迁出为外部插件，与本改动无关）

2026-11-04 15:50:39 +08:00

1.6 KiB

Raw Blame History

name, description, version

name	description	version
kernel-plugins	Tools are per-plugin; on-demand plugins need plugin_start before their tools.	1.1.0

Plugin capabilities

Tools are grouped per plugin and registered at runtime.

get_plugin_tools("{plugin}") - full tool definitions (name / parameters / purpose).
A tool missing from your list does not mean the capability is absent: some plugins are on-demand and only start when asked.
plugin_start("{plugin}") starts an on-demand plugin; its tools appear afterwards.
plugin_status shows what is running; plugin_restart / plugin_stop manage lifecycle.
The matching skill (same name as the plugin, or a related one) states whether the plugin is resident or on-demand, and how to use it once started.

Reading a skill without burning context

skill_info(name) returns the whole document for short skills, but for long ones it returns a table of contents + the first 30 lines. Each TOC line is annotated (N lines) — use it to judge the cost before committing.

To read one part only, pass section:

skill_info("commondev-git", section="14")        # by number
skill_info("commondev-git", section="常见操作")   # by title, substring, case-insensitive

Top-level sections return their whole subtree (asking for Setup gives all its ### subsections, not just the heading line).
# prefixes are tolerated: section="## Setup" works.
A miss is not silent — the error lists every available section, so one retry is enough.
Section boundaries respect fenced code blocks: a # comment inside a ```bash block is never treated as a heading.

1.6 KiB Raw Blame History

Plugin capabilities

Reading a skill without burning context

1.6 KiB

Raw Blame History