jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
1,071 Commits 5 Branches 29 Tags
82d08ebc4535126d077f32964b52d91739ccbcc5
Commit Graph

4 Commits

Author SHA1 Message Date
JianFeeeee
cc0eb51286 refactor(kernel): 统一挂载点 kstate + 插件声明式系统提示词段 
## 起因（生产故障）

A2A 分诊助手（驻留子）把 terminal_create 当一次性命令执行器：

    terminal_create(command='cd /usr/lib/node_modules/@deepseek-ai && ls -d */ | head -60 && …')
    → read /dev/ptmx: input/output error
    → 再开 term_7、term_8、term_9 …

链路拆开四层：
  ① cmd 插件 auto_start=false ⇒ 工具表里没有 cmd_run
  ② 需要 cmd-tools skill 说明"先 plugin_start cmd"
  ③ 但 skill 索引没进那个 agent 的提示词
  ④ 因为 skillIndex 只是根 agent 的字段、由 bootstrap 手工接线

④ 才是总根。而它之所以必须手工接线：agent/core 读不到内核的共享数据。

## 环的精确形状（实测，非推测）

kernelboot 因为持有 KernelState 而依赖 19 个业务包：

    kernelboot ──▶ agent/core ──▶ …
               ──▶ plugin
               ──▶ security
               ──▶ memory / knowledge / text / coldcontext / …

而 kernelboot.go / scheduler.go / funcmodule.go / syncbus.go / lifecycle.go
**一行业务代码都不需要** —— 依赖全在 kernelstate.go 这一个数据文件里。

后果是四个底层包各自造通道：

    core      → Agent 字段（每种 agent 构造点都要记得传）
    plugin    → 12 个 SetXxx
    sdk       → SDKConfig 传参
    security  → 包级单例 Global() / RuntimeGlobal() / ConfigCodec()

四条通道是同一个根因的四个表现。

## 本次做的事

### 1. 抽出 internal/kstate（断环）

kernelstate.go / syncbus.go / lifecycle.go 搬出 kernelboot：

    internal/kstate     纯数据 + 唯一挂载点（叶子，谁都能 import）
    internal/kernelboot 装配引擎，零业务包

挂载点 API：Mount / Get（nil 安全）/ MountForTest（返回 restore，并行测试隔离）。

验证：core 现在能 import kstate（此前 import cycle not allowed）。

### 2. StageHost / Agent 字段存 any

它们是 core 自己的类型（core 是环的一极，这是真环）。按用户裁定的方向：

    > 是其他包在kstate挂共享内容啊

存 any，消费方断言回具体类型 —— 与本仓既有的 PluginCatalog /
PluginScheduler / UpdateCapabilities 同型。

★ 其余字段保持**具体类型**，没有一律改 any。判据是"它会不会反向依赖
agent/core"：实测 plugin / security / sdk 都不依赖 core，所以它们作为
具体类型不构成环，而类型化字段让"拼错/取错类型"是编译错误（本结构体的
设计原则）。

### 3. 插件声明式系统提示词段

SDK 新增 SystemPromptAPI（见 submodule 提交）。内核侧：

    kstate.State.PromptSections *promptsec.Registry   ← 唯一事实来源
    Agent.renderSystemPrompt() 每轮重建时读它

skillmgr 从"实现 SkillIndexProvider 让内核来问"改为"声明自己的段"：

    DeclarePromptSection{Section:"skillmgr.skills", Order:100, Volatile:true}

并挂到全部变更点（启动全扫后、移交事件后、load/unload/create/install/
enable/disable 后、Stop 时撤销）。

### 4. 内核自身的提示词段也走同一管理器

按用户裁定「把现在内核所有 systemprompt 的相关注入都接入到这个统一的
systemprompt 管理器上」，把 buildSystemPrompt 里硬拼的十几块
（人格卡/任务提示词/记忆说明/输出规则/工具目录…）改为声明式：
kernelSections() 当轮计算 → 与插件段按 Order 合并渲染。

顺序由 Order 常量决定，改结构变成调常量而不是挪代码块。

## 判据（均经变异验证）

  TestCoreCanImportKstate            真编译探针；环重现则红（实测）
  TestKstateDoesNotDependOnCore      静态版，指向具体字段
  TestKstateIsLeaf                   kstate 不得反依赖上层
  TestRTChildSeesPromptSections      子 agent 能看到插件段
  TestResidentSeesPromptSections     生产实际中招的那一类；变异后红（实测）
  TestRootAgentSeesPromptSections    确认没改坏根路径
  TestNoPromptSectionsMount          未装配时不 panic、不凭空出现段
  TestDeclareTwiceRendersOnce        ★ 回应"会不会多份"：声明 5 次渲染 1 份
  TestSectionRemovalTakesEffect      Stop 后段消失
  TestRuntimeUpdateVisibleToExistingAgent  同一实例下一轮看到新内容
  TestSectionOrderIsRespected        Order 生效且稳定

## 验证

  go build ./...                   PASS
  go vet ./...                     PASS
  gofmt -l internal/ cmd/ pkg/     干净
  go test ./... -count=1           63 包全过，0 FAIL
  干净检出（git worktree）           build + 4 包测试全绿

## 未做（见 kernelplan.md）

  T3 security 三单例收敛（含 Store 复用 Codec 的惰性迁移）
  T5 plugin Setter 收敛
  T6 防腐判据（部分已随本次落地）
 2026-11-04 11:23:05 +08:00
JianFeeeee
55fa2685ae feat(security,device): security 成为独立内核模块（闸门+策略+限式），device 接管内置工具路由 
security（新模块 internal/kernelmod/security）
- 凭据闸门：出向拦截成 @{别名}、入向清洗、执行前回填（internal/security/{gate,runtime}.go）
- 工具黑白名单 + 沙箱（读写根、网络、.. 逃逸）：internal/security/policy.go
- 敏感词过滤 + 提示词注入预警（Finding 不带原文）：internal/security/content.go
- 按主体授权（hard-private 对非内部主体永久拒绝）：internal/security/principal.go
- 插件命名限式（可选档位，插件声明/内核执行，只能收窄）：internal/security/profile.go
- 启动装配从 cmd/homed 迁入模块；启动顺序判据改盯真实装配点

device（新模块）
- 正式内核模块，Provides FacDevice，KernelState.Device
- 内置工具路由表下沉到 internal/toolroute（避免 core↔kernelboot 环），
  device 保留对外入口；agent 未挂载时退化本地 switch
- Agent 侧只留 api.ToolHost/DeviceSurface 适配层

SDK
- InjectOptions.SecurityProfile：插件按 inputch 声明本轮安全档位（可选）
- InjectOptions.TurnHint：插件注入**本轮事实**，内核以独立 system 消息注入，
  不混进用户正文（人设负责怎么说话，TurnHint 只放这一轮成立的事实）
- FacilitySecurity / FacilityDevice

提示词
- 内核自带 prompt/skill/工具返回全面英文化（中文提示会让模型行为漂移）
- 机制解释下沉到 4 个内置 skill（memory/output/tool-order/plugins），
  skill 描述压到 80 runes 内（原来 94–108 全被索引截断）
- 默认人格模板英文化；[Voice] 段删除，规则并入 persona 块（单一段落）
- 历史记忆工具改名 coldcontext_query/commit，图记忆语义改称 stable memory

修复
- tracker: exec mount → unix.Mount（降权运行 + AmbientCapabilities 下才能挂）、
  区分 EPERM 与不支持；启动日志说明后果与恢复方式
- healthcheck_kernel 输出瘦身：status.Tools 只给摘要（原 98,989 tokens/151% 预算）
- plugin_list 描述讲清 auto_start（按需）与 alive（此刻是否在跑），
  明确不能由 alive=false 推断能力不存在
- pluginmgr/webui 去掉写死的 /home/newqqagent 回退路径（env → pluginDir 反推 → 报错）
- lua: 盘上适配器与内置版本不一致且无基线时响亮告警（deepseek 流式丢失
  tool_calls 导致'模型不调工具'的真因）

测试：go build ./... 通过；go test ./... 60 包全绿
 2026-10-26 20:55:25 +08:00
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
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