jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
858 Commits 5 Branches 29 Tags
4e70b8d5d8a38cf6c7927c275ca50ee1fd7d5fcb
Commit Graph

16 Commits

Author SHA1 Message Date
JianFeeeee
4e70b8d5d8 refactor(module): 核心仓 Go module 路径改为 github.com/JianFeeeee/HologramAgent 
批 1，不含 SDK 仓与目录改名。

- go.mod 第 1 行 module 路径
- 366 个 .go 文件的完整前缀 github.com/JianFeeeee/HomeAgent 机械替换
  （857 处，仅完整前缀；展示名/注释里的 HomeAgent 字样留给批 5）
- 未改：third_party 目录名、SDK 自身 go.mod module、go.mod replace 目标、
  homed/waiter 可执行名、.hmap 后缀
 2026-10-21 12:17:19 +08:00
root
d35b7b7275 feat(status): ONNX 状态补 dep_parser 字段；人格改成「说人话」的说话方式 
## 1. ONNX 状态补依存句法分析器（onnx.dep_parser）

此前 onnx.enabled 只反映**多模态向量空间**，解析器状态完全不可见 —— 于是
只能靠翻启动日志猜，而日志又曾把「内嵌模型已启用」错报成「规则引擎」
（见上一个提交）。现在健康快照直接给：

    "dep_parser": { "enabled": true,
                    "model_path": "/home/newqqagent/nlp/dep_parser.onnx",
                    "embedded": true }

- sdk.ONNXStatus 增加 DepParser / DepParserStatus（enabled/model_path/embedded）
- agent 侧由 nlp 包级默认解析器反查实际状态（判据是「真能 Parse 且报得出路径」，
  不是「配置里写了 onnx_model_path」）
- healthcheck_kernel 的描述同步说明该字段

## 2. 人格：从「交报告」改成「聊天」

用户反馈实例说话一股人机味。实测原文：

    第一件·文件读写：
    - 写：files_write 往 /tmp/... 写入 hello-files，回执 11 字节
    - 读：files_read 读回来，内容就是 hello-files，对上了

问题不在语气词，而在**结构**：清单体 + 小标题 + 加粗 + 把工具名/字节数/耗时
当成绩单报出来。旧人格只禁了「客服腔四件套」，没禁这些。

DefaultPersonaPrompt 的说话方式一节重写，明确：
- 短句为主；先给结果/情绪，再补解释
- 不用清单体（“-”/“1.”/“•”）、不用小标题/加粗/表格
- 不报工单式细节（不罗列工具名、参数、字节数、耗时）——说人话
- 不用客服腔，拿不准/失败直说
- 只有用户明确要清单/步骤/数据时才结构化

## 3. 本机实例人格同步优化（personal.md，优先级高于配置项）

按同一套规则重写 /home/newqqagent/personal/personal.md，并保留「照大肥鱼那股
活人味来」与形象特征。重启后实测（问「在吗？状态咋样」）：

    在呢在呢 (｀・ω・´)
    刚拉了个运行时快照看了眼，状态挺好——内核 1.4.0dev 跑着，29 个插件全部 loaded……
    刚忙完就赶紧来找我聊天，老大你这节奏也太充实了呗～

无清单、无小标题、无工具名报账。

验证：go test（sdk / agent core / healthcheck / config）全绿；
本机实例重启后 onnx.dep_parser 三字段正确返回。
 2026-10-20 09:08:20 +08:00
JianFeeeee
5a3a8f484b fix(agent): 工具超时不再一刀切 60s，支持工具自声明与按参数推导 
## 缺陷（2026-10-17 生产日志实测）

`toolcall.go` 里写死 `time.After(60 * time.Second)`，与工具自己的超时
**互相矛盾**且让内层形同虚设：

	23:13:38  执行 cmd_run（agent 传了 timeout="130" 级参数）
	23:14:38  ★ 内核 60s 硬超时掐断 → 「执行超时（60秒）」

同一份日志里 healthcheck 声明默认 120s ⇒ 被砍掉一半，天生跑不完。

## 改动

1. `ToolDef.Timeout` / `BuiltinToolDef.Timeout`：工具自己声明单次上限。
   留空 = 沿用 60s（存量插件**一行不改，行为逐字不变**）。

2. 内核取 `max(声明值, 调用参数 timeout)`，再夹到硬上限 10m：
   · 声明修好固定时长的工具（healthcheck 5m）
   · 参数推导修好时长可变的工具（cmd_run 的 timeout 参数）
   · 硬上限防插件声明成 0/无限把队列堵死

3. 非法声明（"130" 少单位、0s、负数）**回退默认并记日志**，不静默接受。
   写错单位是最容易犯的错，默默变成 60s 会让人以为"声明没生效"却查不出。

4. healthcheck 声明 5m（它的 llm_timeout 默认就是 120s）。

★ 没有把 timeout 放进 `ToSchema()`：那份 map 是**发给模型**的 function
  schema。把内核的执行参数混进去，模型会以为需要自己传 timeout 参数。

## 判据（6 条）

未声明→60s / 声明生效 / 参数参与取 max / 参数比声明小用声明 /
非法回退 / 超上限夹住。变异全部咬住。

## 附：这条路只治「工具真的需要更久」

向开发线投递（output_send__*）的两次 60s 超时**不是这个原因** ——
那是 commondev 把"投递"实现成了"同步等任务完成"，已在 SDK 仓修成异步。
这里没有给 output_send 放大超时：投递应该瞬时返回，慢是 bug 不是需求。
 2026-10-18 06:38:51 +08:00
JianFeeeee
a68d6a428c feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10) 
* feat(kernel): 模块化内核 + 编译期依赖图定序

把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。

## 为什么

原 cmd/homed/main.go 里 17 步 init 是**手写顺序**，依赖关系只存在于
注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）：
 · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行，
   只靠 ticker 10min 才没炸（隐式依赖，无声明）
 · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用
 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) **跳过 defer**
   ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生）

## 怎么改

- internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段
  nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、
  scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、
  lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll）
- internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明；
  all/all.go 是唯一的 import 清单（Go 循环导入约束）
- cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest
- 运行期只**读**图，不计算顺序（顺序是编译期决定的，源码里没有中央清单）

## 判据

kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数
与注册表一致性。变异测试 15/15 咬住，含：
 · 删掉 AddCloser 的锁 → -race 报数据竞争
 · Scheduler 同批跑去重 → 203 vs 200
 · 图 hash 不匹配 → 拒绝启动

## 顺带修的缺陷

热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住
"必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。

实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。

* feat(security): 密钥防火墙 + 配置加密 + close 纪律

## 密钥防火墙

模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向
回填。三维能力：
 · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文
 · 入向：模型传别名，入口处填回真值（插件完全无感知）
 · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件

模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。

## 配置加密

- internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM，
  enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密）
- harden.go：数据目录权限收紧
- embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径）
- EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计

## close 纪律（用户明确要求：只要调 close 就要有前置检查）

internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。
关键教训（都写进注释和判据）：
 · `select { case <-ch: default: close(ch) }` **不是**并发安全的
   （两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法
 · `sync.Once` **不可重入**：X.Do(func(){ Safe(&X, ...) }) 会自锁，
   症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do
 · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go）
   改成 *pendingRPC 包装，每通道一个 once

## 判据

security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离）
+ TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。
变异 2/2 咬住。全量 52 包 ok。

* feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复

## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用）

- Manifest 新增 requires_facilities / auto_start（*bool，用于区分
  "未声明"与"显式 false"）
- plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler
  按依赖时机拉起，**不再手写两阶段**
- 运行态停启 StopPlugin/StartPlugin **可逆**：不写 disabled_plugins
  （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面
- 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后**永久无法加载**，
  那是进程退出用的，误用于"暂停"就是关了就死

## 数据目录迁移（伪关机 → 迁移 → 唤醒）

- kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll），
  逆序暂停、逆序恢复、Pause 失败回滚
- kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者
  → 等在途归零）
- distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆，
  恢复要重建整个对象）
- 模块 migration：体检 + 生成可执行迁移脚本

★ 迁移脚本的三个实测教训（都写成了判据）：
 1. 无条件改 /etc/systemd/system ⇒ 演练把**生产** -data 改成了演练目录。
    加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD
 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退，
    并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接）

## 发行包修复（全部经实测确认）

 1. package-linux.sh **完全漏打 depgraph.bin** ⇒ 内核 exit 1
    （"生产构建（内嵌 hash 非空）但读不到依赖图"）
 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入
 3. build.sh 的 LDFLAGS 用**历史模块路径 gitcode.com** ⇒ -X 静默 no-op
    ⇒ --version 显示 unknown
 4. Makefile -ldflags 用**单引号** ⇒ 注入了字面 $GRAPH_HASH

## ★ build.sh 的版本号必须校验（真实事故）

原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回**分支名**
`backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version
⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ **22 个子进程插件全部
握手失败**（"主版本不匹配"）。内核活着、systemd active、日志每条都像
插件的问题 —— 实际是发行包带着非法版本号。

修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源），
并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据，
变异 2/2 咬住。

## deb 的 systemd unit 改为 guard 模式

ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent
（worker exit 42 → guard 重拉，不经过 systemd、不计失败）
含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化
（NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。

## 其他

- internal/plugin/proc：非法 JSON 帧的报错**可定位**（内容摘要 + 可能原因 +
  修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道）
- 示例插件 4 个 14 处 fmt.Printf → log.Printf
- hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf）

* chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐）

- cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets
  串成一条**可执行**的运维路径。没有它，E-1 就只是库里的能力而不是
  "出事时能做的事"，而轮换的价值恰恰在于能执行。
- cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback
  白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test
- internal/ipc、internal/devicebridge、internal/knowledge：配套加固
- third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/
  mgrIsRuntimeStopped）+ settings 对齐

判据：bootstrap_order_test（启动顺序不依赖手写序列）、
shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer，
热更新路径下模块关闭/flush 曾全部丢失）。

* test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截）

GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的
字面量：

  internal/security/prefilter_test.go:39
  internal/security/store_test.go:177
  internal/security/survey_test.go:20

它们全是**假密钥**（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例，
其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。

★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。
原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。

改法：保留**模式库匹配所需的结构**，把可识别内容换成 FAKE：
  glpat-abcdefghijklmnopqrst       → glpat-FAKE-TEST-TOKEN-NOT-REAL
  sk-abcdefghij...012345           → sk-FAKE-TEST-KEY-NOT-REAL-0000000
  AKIAIOSFODNN7EXAMPLE             → AKIA0000FAKE0000TEST   (保持 20 字符)
  ASIAIOSFODNN7EXAMPLE             → ASIA0000FAKE0000TEST
  xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL

★ 中途踩到一次：AWS 键的模式是 `\b(AKIA|ASIA)[0-9A-Z]{16}\b`（共 20 字符），
我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒
TestSurvey_WhatIsCaught / TestRecognizesCommonShapes /
TestPrefilterNeverBlocksRealMatches 三条当场变红。
判据正确地拒绝了"为了过扫描器而削弱覆盖"。

顺带核实：全仓 grep 无任何真实密钥泄漏。

* fix(packaging): package-linux.sh 的版本解析与 build.sh 统一

上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe：

  VERSION="${VERSION:-$(git describe --tags --dirty)}"

无 tag 分支上 git describe 返回**分支名**
（backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝，
但要求人**手动传 VERSION** 才能打包。而 build.sh 早已能自动回退 meta.Version
⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。

危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进
meta.Version 就是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败
（这是真实发生过的事故，见 3efa4e5）。

修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用，
否则回退 meta.Version），并对最终值做形态守卫。

判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本，
要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。
变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。

实测：不传 VERSION 跑 package-linux.sh，输出
  [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0
  Version: 1.4.0

* fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红）

CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红：

  --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods
      bridge_sync_test.go:170: 读模板: open
      ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl:
      no such file or directory

## 根因：判据依赖了一个**被 gitignore 的路径**

`.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。
于是：
  · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过
  · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ **必红**

我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。

## 修法

文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。

★ 这不是"放弃检查"：
  · 跨仓一致性由 **SDK 仓自己的判据**守着
    （tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地
  · 本判据在本机开发时**仍然生效**（已验证：有文件时 PASS，缺文件时 SKIP）

## 验证

 · 本机（有文件）  → PASS（判据真跑）
 · 模拟 CI（移走 tools/）→ SKIP（不再 fail）
 · 全量 53 包 ok / 0 fail

## 顺带

同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的
e2e 判据，CI 默认不跑，无需处理。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
 2026-10-17 19:18:24 +08:00
JianFeeeee
6d38a164eb chore(module): Go module 路径随托管地迁移 gitcode → github 
## 背景

仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑），
gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。
但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源
不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。

## 关键区分（这是本次改动安全的前提）

两个 module 是**不同**的，影响面差一个数量级：

| module | 谁依赖 | 改它的后果 |
|---|---|---|
| `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 |
| `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 |

★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0），
只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串**
（`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。
⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。

SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配，
否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。

## 改动

- `go.mod` / `go.sum`：两个 module 路径 + require/replace
- 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径
- SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板
- 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等）

## 明确**保留** gitcode 的地方（镜像机制，不能动）

- `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job）
- `gitcode.com/api/v5/...`（release 附件上传）
- git remote `gitcode`（镜像拉取/推送）
- `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维）

## 验证

- `go build ./...` / `go vet ./...` 绿
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
- hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`）
- 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0
- 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好

## 顺带修正

`hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」——
module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**：
离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。
 2026-10-08 10:40:17 +08:00
JianFeeeee
698e25d10c feat(parallel): 并发安全改为声明式，并审计标注 37 个工具 
把"能不能并发"从内核硬编码名单改成**工具自己的声明项**，形态照 SDK 的
NoMemory 走。

## ★ 起因：提示词在跟内核不一致

阶段 2.5 写进提示词的「内核默认并行执行」当时是**假的**：toolParallelSafe
只查 stageHost 与 io 两个来源，而全仓 ParallelSafe:true 的生产代码数量
是 **0**。于是除碰巧只发一个工具外，每一批都整批串行回退，而提示词正教
模型把多个查询放同一轮。**内核行为与提示词不一致 = 对模型说谎。**

并发面：0 → 37 个工具（18 插件 ParallelSafe + 19 插件 Serial + 9 内置只读）。

## 声明形态（照 SDK，不自创）

### 插件：结构体字段
    s.RegisterTool("config_get", sdk.ToolDef{
        Name: ..., Description: ...,
        Parameters: map[string]interface{}{...},
        // 已核实只读：…
        ParallelSafe: true,      ← 插在 Parameters 之后、handler 之前
    }, p.handleGet(s))

位置与 SDK 的 NoMemory/ContextPolicy/RecallPolicy 一致：Name 在首位，
声明项在末尾，不打散 gofmt 对齐。

### 新增 SDK 声明项：ToolDef.Serial
ParallelSafe 的**反向**标记，判据优先级高于 ParallelSafe。
为什么需要：ParallelSafe 零值 false 已表达"安全"，插件无法区分"我没想过"
与"我确认过必须串行"。没有这个区分，工具作者只能靠命名约定传递意图。

内核已消费它（io.ToolDef 同步加字段对齐），并有判据守"Serial 胜出"。

### 内置工具：toolDef 的 toolParallel 选项
内置工具以裸 schema map 下发，没有 ToolDef 结构，所以用变参选项：
    toolDef(名字, 描述, 属性)                  // 默认串行
    toolDef(名字, 描述, 属性, "toolParallel")  // 已核实只读，可并发
读工具表的老调用点一行不用动，声明就写在工具定义那一行。

## ★ 走过的弯路（都留了判据）

1. **硬编码白名单**：先在 toolParallelSafe 里查一张
   builtinParallelSafeTools map。那把声明从"工具自己"搬回了内核 ——
   工具改名/新增不会自动跟着变，得靠一条 grep 源码的判据才能发现漂移，
   而判据一改就忘。已删，改为从定义读。

2. **判据前提错（同一个坑踩了两次）**：拿裸 &Agent{} 的 buildToolDefs 输出
   当"实际可见工具"，但这 9 个内置工具全在条件分支里（a.knowledge != nil /
   a.social != nil / a.parentID != ""…），裸 Agent 一个都不产出 ⇒ 全部误报
   "声明形同虚设"。第一次叫它"幽灵条目"，没认出是同一个坑。

3. **注释模仿真实签名污染判据**：toolParallel 的用法注释写着
   `toolDef("knowledge_search", ...)`，判据按文本匹配先撞上注释。

4. **buildToolDefs 的 nil 不一致**：开头判了 a.io != nil，末尾却无条件
   a.io.ListChannels()。任何无 IO 的 Agent 调它都 panic —— 而 panic 报在
   io 包里，根因在 tooldefs.go。已补。

5. **插入脚本用正则找"最后一个顶层字段"**：被嵌套 map 里的同形文本骗到，
   823 处错误重排把文件改坏。改用括号深度 + 记录进入深度 3 的行号
   （空 properties 会让深度在同一行进出平衡，只判 depth==2 不够）。
   工具在 SDK 仓 tools/annotate_parallel/，复用时用绝对路径。

## 提示词措辞同步修正
「默认并行执行」→「尽量并发执行，但这是**逐工具判断**的」，并教模型
**把查询类放同一轮、写操作单独发一轮**（写和查混在一批，整批都串行）。

## 判据
- TestSerialOverridesParallelSafe          Serial 优先于 ParallelSafe
- TestToolParallelDeclarationsAudit        并发面不许再归零
- TestNoToolDeclaresBothParallelAndSerial  两者同标即谎话
- TestBuiltinParallelDeclaredWhereDefined  声明写在定义处、且内核真读到
- TestStoreListIgnoresForeignJSON          压测抓到的 List() 缺陷
 2026-09-27 15:15:57 +08:00
JianFeeeee
f84852e14b feat(healthcheck): 内核状态快照报出内核版本号与 ONNX 模型启用状态 
healthcheck_kernel 此前没有任何「ONNX 模型是否在用」的信息，只报「向量可用/不可用」，
分不清「统一多模态空间已加载」与「退回到词嵌入/TF-IDF 路径」；人格卡要求
「版本以运行时快照为准」，也缺一个可查字段（build.version 早就在，但没人知道）。

- KernelStatus 新增 onnx 段：enabled / provider / dim / fingerprint / modalities / reason。
  判据取 Loaded()（provider 真正打开且元数据合法），**不是**「配置里写了 provider」
  —— 后者在模型缺失 / 运行时缺失时也为真，报出去就是假绿。
- 未启用时 reason 给**具体原因**：未配置（说明会走回退路径）/ 打开失败的具体错误。
  homed 把「配置的 provider 名」与「打开失败原因」透传给 Agent，仅供状态报告。
- ProviderAdapter 新增 Modalities()（可选能力，按接口断言取用，不改公开契约）。
- healthcheck_kernel 的工具描述同步说明它回答这两件事。

**顺带修一个真实 panic**：collectKernelStatus 的 knowledge 是**接口**参数，
(*knowledge.Store)(nil) 塞进接口后 `ks != nil` 仍为真 → 调 List() 直接 panic，
而 healthcheck_kernel 正是走这条路径（panic 发生在工具 goroutine 里）。
GetKernelStatus 改为先按具体指针判空、再赋给接口；并加刻画测试钉住这个成因
（一旦不再 panic 说明参数形状已变，守卫与该测试应同步删除）。

验证：单测 4 例（已启用 / 打开失败 / 未配置 / 未加载）+ 刻画测试；
隔离实例 E2E 7/7：正例 provider=chineseclip → enabled=true、dim=512、模态 2；
反例 provider=nonexistent → enabled=false 且 reason 含具体错误与 provider 名，
真实对话仍通。
 2026-09-12 14:56:25 +08:00
JianFeeeee
2bcd3e94ee refactor(memory): 拆除描述式媒体索引，媒体成为一等块并按原生向量融合 
背景：此前媒体是靠「生成的描述文本」将就进记忆的——写 marker 进正文、
再由正则反解成 media_refs 与图库里的 type=Media 实体。这条链路有三个
致命缺陷：描述由异步模型生成（未生成前媒体等于不存在）、语义检索实质上
只搜描述文字、图库里的「媒体节点」是描述文本的投影而不是媒体本身。

本提交把这条链路整体拆除，媒体改为按自己的原生向量参与记忆：

一、描述链彻底删除（无残留、无兼容分支）
- media.Item 去掉 Description/DescribedBy 与对应列；
- 删除 Store.Describe / Store.Search / Store.Pending；
- 删除 Agent.mediaDescribeLoop / describePendingMedia 与配置项
  core.memory.media.describe_on_ingest；
- SDK 侧 MediaAttachment 去掉 Description（见 SDK 仓独立提交）。

二、marker 机制删除，媒体归属改为结构化块边
- 删除 mediaMarkerLine/parseMediaMarkers/mediaEntityName/mediaTriplesFromText/
  extractMediaDigests/sentenceWithMediaMarkers/docMediaContext；
- memory.Triple 新增 MediaDigests 结构化字段；句子文本保持原样，
  不再被 marker 污染；
- 块以 sentence --contains--> block / document --contains--> block 结构边
  挂到承载节点（新增 documents 表与 document 节点种类）；
- 模型未给原句时用「主谓宾。」拼一句自然语言作落点，不造 marker 文本。

三、旧数据迁移（幂等）
- 新增 GraphDB.MigrateLegacyMediaEntities：把 type=Media 的旧实体按短 digest
  还原成原生块、挂回原句子、删除旧实体与描述关系；Agent 启动时执行；
- CleanupOrphanedSentences 同时看关系引用与块边，避免把只靠块存活的句子
  连同块边一起删掉。

四、向量融合：媒体按图本身被召回
- 新增 vector.FuseVectors（逐维求和 + L2 归一化）；
- Doc.DenseVec = 文本向量 ⊕ 文档块的媒体向量（同 fingerprint 才融合），
  新增 Doc.DenseFP，指纹变化触发重算；
- ContextEvent.DenseVec 同理融合事件块；事件新增 DenseFP，Prune 只在
  同一统一空间内比稠密余弦；
- 跨模态视觉路只召回「仍被某层记忆块持有」的媒体，CAS 全库字节不再
  直接充当记忆检索结果。

五、同时纳入本分支既有的嵌入基础改造（此前工作区未提交，缺它 HEAD 不可构建）
- internal/tfidf 懒回退包、千问三段式多模态 ONNX 空间的 Go 侧
  （qwen/embedder.go、image.go、model_input.go）、CLIP 移除、
  sdk.NewStore 分词器签名与调用点、embed 侧车 systemd 单元。

验证：go build ./... 、go vet ./...（含 -tags medialive）均通过；
在 HEAD 的独立 worktree 上重放本次暂存集后 go test -short ./internal/...
全部通过（端口冲突类用例在隔离环境中亦通过）。未提交工作区中与本改造
无关的改动（HarmonyOS、waiter、devicebridge、plan.md 等）。
 2026-09-11 11:45:24 +08:00
JianFeeeee
2fd2546962 fix: healthcheck auto-check 幂等重启(stopCh 可重建, 修复 plgreload 后定时器失效) 2026-08-16 18:27:25 +08:00
JianFeeeee
4337917a79 healthcheck: 存量改进; mcp: sse 改进 2026-08-14 16:15:24 +08:00
JianFeeeee
456a5b2286 Phase 0.1/1/3/6: 核心生产问题修复 
Healthcheck 隔离 (Phase 0.1):
- 新增 internal/sdk/selftest.go: VirtualInstance 完全隔离自检空间
- PluginSDK.Selftest()/SelftestReset() 暴露隔离实例 (含 mutex)
- LLM 自检只读白名单 isSafeReadonlyTool 防写类工具污染生产
- 单测验证: healthcheck 后生产实例内容不变 + 无残留
- 存量清理: 删除 gotest/luatest 残留目录

GraphDB 去重 (Phase 1):
- migrateRelationUnique: 启动自动重建 relations 表加 UNIQUE 约束并去重
- Commit 改为存在性检查, 重复三元组仅刷新 confidence 不重复插入
- 3 个 dedup 单测全绿

配置时长解析 (Phase 3):
- parseDurationExtended 支持 2d/1w/3h 等人类可读单位
- GetDuration 全局生效, 防 2d 静默回退 30m

Agentcli 通知风暴治理 (Phase 6):
- 语义通知: 累积 notify_bytes(2KB) 或间隔 notify_interval(2s) 触发
- 生命周期即时通知: 启动/进程退出/EOF 立即通知
- 可配置 settings, 保留通知机制保证 agent 感知终端存在
- 运维止血: 已杀掉幽灵 PID 3716282 (bash git sparse clone 运行 16h)

Plan.md: 新增设计意图备忘(插件即App/分层记忆), 更新各 Phase 进度
 2026-08-12 13:51:40 +08:00
JianFeeeee
0d74efd0ea refactor: migrate built-in plugins to SDK-only interface 
- Six-phase plan complete: webui/cli/healthcheck/pluginmgr/clawhubadapter
  now interact with the kernel exclusively via internal/sdk interfaces;
  all Configure() calls and package-level global injection removed
- buildSDK in internal/plugin/registry.go is the single assembly point
- Add internal/sdk/events.go exporting event types/constants
- Fix ProviderManager cooldown sharing: LuaAdaptedProvider.Name() now
  returns the source name instead of lua_<adapter>, so multiple sources
  sharing an adapter (single script load via shared VM AdapterCache) no
  longer share failure-cooldown state
- Verified: build/vet/tests green, deployed to homeagent.service with
  full plugin capability testing via local OpenAI-compatible mock
 2026-08-01 12:17:17 +08:00
JianFeeeee
9bee5295b8 feat: output channel redesign - per-channel output gates, LLM chain events, SDKConfig 
- Output channels generate per-channel tools: output_send__{name} (type=output) + output_send__{name}_help
- content is JSON string transparently passed to plugin handler for routing
- EventAgentLLMChain: full LLM response forwarded after each turn for webui/logs
- sdk.New refactored to SDKConfig struct (no more 13 positional args)
- RegisterOutputChannel adds desc param for JSON format documentation
- channelDevice simplified (no Tools method), desc field added
- Child agent permission updated for output_send__ prefix
- System prompt: output gates, multi-call, long messages split
- WebUI: subscribes to EventAgentLLMChain in SSE, no output channel
- Tests updated for new naming convention
 2026-07-16 12:11:16 +08:00
JianFeeeee
5e80db52f5 feat: restructure plugin system, add Lua plugin support, update docs 2026-07-13 21:48:13 +08:00
JianFeeeee
1259e587c3 fix: correct context pruning order and vector alignment 
- Prune context BEFORE processing (LSTM forget gate pattern)
  so LLM only sees relevant context, instead of pruning after the fact
- Fix ensureTrained() to recompute all event vectors after retraining
  vectorizer, fixing feature-space mismatch between stored vectors and
  query vector that made relevance scoring effectively random
- Add read lock to knowledge BuildTree() (data race fix)
- Log writeIndex() errors instead of discarding them
- Fix TOCTOU race in document ContextToDoc() dedup
- Fix healthcheck timing (measure elapsed before cleanup)
- Refactor waiter CLI into separate files (state, conn, config, editor,
  history, builtin) for maintainability
- Add CLI plugin API key authentication
 2026-07-07 17:07:38 +08:00
JianFeeeee
2908e1637c feat: complete P0/P1/P2 — WebUI SPA, OpenClaw sidecar+simulator, healthcheck auto-sched+perf 
P0: WebUI重构
- 完整 SPA 仪表盘 (7标签页), //go:embed dashboard.html
P1: OpenClaw兼容 (三通道: SKILL.md / sidecar / simulator)
- Node.js 模拟进程统一加载任意 OpenClaw 插件
- JSON-RPC 2.0 over stdio 协议, go:embed 内嵌
P2: Healthcheck 优化
- 定时自动执行 (startAutoCheck, 30min)
- healthcheck_perf 性能监控工具

其他: agentcli/cmd 插件, integration_test, status.go,
      test_deepseek 清理, 多项 bug 修复
 2026-07-04 12:51:32 +08:00