jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 06:47:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10)

Browse Source 
* 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>
This commit is contained in:
JianFeeeee
2026-10-17 19:18:24 +08:00
committed by GitHub
parent 03d87a4e21
commit a68d6a428c
266 changed files with 30185 additions and 1424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
third_party/homeagent-sdk/sdk/facilities.go vendored Normal file
View File

@ -0,0 +1,77 @@
// Package sdk —— 内核**设施名**（插件声明启动时机时用的名字）。
//
// ## 用途
//
// 插件在 `plg.json` / `plugin.json` 里声明 `requires_facilities`，
// 内核据此决定**何时拉起它**（设计：kernel-modularization-design.md §2.6）：
//
// 不声明 ⇒ 等内核**完全**初始化（默认；存量插件零改动）
// 声明 ["config"] ⇒ config 就绪即拉起（**尽早启动**）
// 声明 ["config","llm"]⇒ 两者都就绪才拉起
//
// ## ★ 为什么这些常量必须在**公开 SDK** 里
//
// 它们原本只定义在内核的 `internal/kernelmod`（Go 的 internal 规则禁止
// 外部包 import）⇒ 插件作者**无从得知**能写哪些名字，只能照文档抄，
// 而抄错（如 "llmservice" vs "llm"）的后果是：
//
// 插件**永远等不到就绪** ⇒ **永不启动**，且无报错。
//
// 这正是本仓反复吃亏的"静默降级"形态。把名字放进公开 SDK 后：
//
// · 插件作者 import 常量 ⇒ **拼错是编译错误**（而不是运行期静默）
// · 且这是内核与插件之间的**契约**，理应公开
//
// ## 内核侧的一致性
//
// 内核在 `internal/kernelmod/facilities.go` 定义同名常量，
// 判据 `TestFacilityNamesMatchPublicSDK` 保证两边**逐字一致**
// （防止改一处忘另一处 —— 那会让插件声明的名字悄悄失效）。
package sdk
// 内核设施名（模块 Provides 的名字）。
//
// ★ 这些是**字符串值**，与内核 internal/kernelmod/facilities.go 必须逐字一致。
const (
// FacilityConfig 是配置快照（cfg）就绪。
FacilityConfig = "config"
// FacilityKernelIO 是 IOManager + EventBus 就绪。
FacilityKernelIO = "kernel-io"
// FacilityMemory 是图记忆（含索引/社交图/蒸馏）就绪。
FacilityMemory = "memory"
// FacilityLua 是 Lua 协议适配 VM 就绪。
FacilityLua = "lua"
// FacilitySupervisor 是代理生命周期守护就绪。
FacilitySupervisor = "supervisor"
// FacilityTracker 是变更追踪（overlayfs）就绪。
FacilityTracker = "tracker"
// FacilityTextMemory 是文本记忆就绪。
FacilityTextMemory = "textmem"
// FacilityLLM 是多源 Provider 管理就绪。
FacilityLLM = "llm"
// FacilityDocStore 是文档记忆就绪。
FacilityDocStore = "docmem"
// FacilityKnowledge 是知识库就绪。
FacilityKnowledge = "knowledge"
// FacilityMultimodal 是多模态向量空间就绪。
FacilityMultimodal = "multimodal"
// FacilityONNX 是依存句法分析器就绪。
FacilityONNX = "onnx"
// FacilityStageHost 是阶段管道 + 插件注册表就绪。
FacilityStageHost = "stagehost"
// FacilityAgent 是主 Agent 就绪（**最晚**的一个，通常在插件加载前）。
FacilityAgent = "agent"
)
// KnownFacilities 返回本 SDK 已知的全部设施名（供工具链校验插件声明）。
//
// ★ 它让**打包期**就能发现"插件声明了不存在的设施名" —— 比运行期发现早得多
// （运行期发现意味着用户已经装上了那个永不启动的插件）。
func KnownFacilities() []string {
return []string{
FacilityConfig, FacilityKernelIO, FacilityMemory, FacilityLua,
FacilitySupervisor, FacilityTracker, FacilityTextMemory, FacilityLLM,
FacilityDocStore, FacilityKnowledge, FacilityMultimodal, FacilityONNX,
FacilityStageHost, FacilityAgent,
}
}

65
third_party/homeagent-sdk/sdk/plugin.go vendored
View File

@ -385,8 +385,35 @@ type PluginMgrAPI interface {
ReloadOne(name string) error
// ListLoadedPlugins 列出已加载插件。
ListLoadedPlugins() []string
// IsPluginDisabled 查询插件是否被禁用。
// IsPluginDisabled 查询插件是否被**持久**禁用。
IsPluginDisabled(name string) bool
// ---- 运行态启停（设计 docs/zh/kernel-modularization-design.md §2.6.7）----
//
// ★ 与 DisablePlugin/EnablePlugin 的区别（这是这两个方法存在的全部理由）：
//
// DisablePlugin/EnablePlugin ⇒ 改**持久**状态（disabled_plugins 配置）
// StopPlugin/StartPlugin ⇒ 只改**运行**状态，不写任何配置
//
// 心智模型：插件是 agent 的应用程序。
// · disabled_plugins = 系统里"禁止运行这个程序"（持久决定）
// · runtimeStopped = 用户"现在关掉这个窗口"（运行决定，重启复位）
//
// 混用二者的后果（实测缺陷）：想临时关一下却顺带关掉了开机自启
// ⇒ 用户下次开机会发现"怎么不启动了"。
// StopPlugin 运行态关闭：现在停掉，**不改持久状态**。重启后按
// auto_start + disabled_plugins 正常决定。
//
// 拒绝作用于 pluginmgr 自身与 webui（自锁/失联，内核层面拦死）。
StopPlugin(name string) error
// StartPlugin 运行态启动：现在拉起，**不解除持久禁用**。
//
// 被持久禁用的插件会被拒绝（提示先用 EnablePlugin）——
// 持久禁用是用户的明确决定，运行态操作不该绕过它。
StartPlugin(name string) error
// IsPluginRuntimeStopped 查询插件是否处于运行态关闭。
IsPluginRuntimeStopped(name string) bool
}
// StageScope controls which events a stage handler receives.
@ -449,6 +476,8 @@ type PluginSDK struct {
llm LLMAPI
sett SettingsAPI
social SocialAPI
secrets SecretsAPI
rawFiles RawFilesAPI
events EventSubscriber
plgMgr PluginMgrAPI
@ -540,6 +569,16 @@ func (s *PluginSDK) LLM() LLMAPI {
}
// Social returns the social graph API (may be nil if not available).
// Secrets returns the kernel secret vault API.
//
// ★ 内核未启用安全模块时它**不是 nil**，而是 Available() 返回 false 的
// 实现 —— 这样插件可以统一地"先问 Available 再决定"，不必到处判空。
func (s *PluginSDK) Secrets() SecretsAPI {
s.apiMu.RLock()
defer s.apiMu.RUnlock()
return s.secrets
}
func (s *PluginSDK) Social() SocialAPI {
s.apiMu.RLock()
defer s.apiMu.RUnlock()
@ -703,6 +742,30 @@ func (s *PluginSDK) SetIOInjector(io IOInjector) {
}
// SetMemoryAPI sets the memory API (called by the core at startup).
// RawFiles 返回随包分发资源的读取接口（内核装配时注入）。
//
// 未注入时返回 nil —— 那是旧内核或测试环境。插件应判空后**响亮失败**，
// 而不是拿一个空实现继续（会表现为"资源读出来是空的"，与"资源不存在"难区分）。
func (s *PluginSDK) RawFiles() RawFilesAPI {
s.apiMu.RLock()
defer s.apiMu.RUnlock()
return s.rawFiles
}
// SetRawFilesAPI 由内核装配时注入（插件不调用它）。
func (s *PluginSDK) SetRawFilesAPI(v RawFilesAPI) {
s.apiMu.Lock()
s.rawFiles = v
s.apiMu.Unlock()
}
// SetSecretsAPI 由内核装配时注入（插件不调用它）。
func (s *PluginSDK) SetSecretsAPI(v SecretsAPI) {
s.apiMu.Lock()
s.secrets = v
s.apiMu.Unlock()
}
func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI) {
s.apiMu.Lock()
s.mem = mem

56
third_party/homeagent-sdk/sdk/rawfiles.go vendored Normal file
View File

@ -0,0 +1,56 @@
package sdk
// RawFilesAPI 让插件读写**随包分发的资源**（rawfile）。
//
// ## 是什么
//
// `hmapdev build` 会把工程根 `rawfile/` 下的全部内容（以及 plg.json
// `rawfiles` 声明的外部路径）打进 .hmap；内核解包时保留路径，落到：
//
// <插件目录>/rawfile/<原相对路径>
//
// 本接口就是插件读这些资源的唯一入口。
//
// ## 为什么不让插件自己拼路径
//
// 插件**不知道自己的安装目录**：内核的 `PluginDir()` 是给插件管理器用的，
// 不暴露给插件自身。而且"包内资源"与"运行期生成的文件"必须分开 ——
// 前者只读、随升级替换，后者可写、跨升级保留。混在一个目录里，
// 升级时会误删运行期数据，或把旧资源留在原地。
//
// 所以：
//
// RawFiles().Read("main/prompt.txt") → 读**包内**资源（只读）
// RawFiles().WorkDir() → 拿**可写**工作目录（运行期数据放这）
//
// ## 安全边界
//
// 所有路径都相对 rawfile/ 根，**必须拒绝路径穿越**（`../`）。
// 资源文件来自包，包可能被替换 —— 让插件能借它读到 `/etc/shadow`
// 就是一个真实的提权面。
type RawFilesAPI interface {
// Read 读一个包内资源（路径相对 rawfile/ 根）。
//
// 例：Read("main/prompt.txt") 读 <插件目录>/rawfile/main/prompt.txt。
Read(rel string) ([]byte, error)
// List 列出某个目录下的条目（相对 rawfile/ 根；"" 表示根）。
//
// 返回的名字是**相对 path 的单层名**（不是全路径），目录名带 `/` 后缀。
List(rel string) ([]string, error)
// Exists 报告某个资源是否存在。
Exists(rel string) bool
// Dir 返回包内资源的根目录（只读）。
//
// 给需要把整个目录交给外部工具的插件用（如把 node 目录的路径
// 传给 exec.Command）。**不要往这里写东西** —— 它在包里，随升级替换。
Dir() string
// WorkDir 返回一个**可写**目录，供插件放运行期生成的文件。
//
// 与 Dir() 分开的原因：Dir() 里的东西随升级被整体替换，
// 运行期数据放那里会在下次升级时丢失。
WorkDir() string
}

111
third_party/homeagent-sdk/sdk/secrets.go vendored Normal file
View File

@ -0,0 +1,111 @@
package sdk
// SecretsAPI 是插件访问**内核变量库**的接口。
//
// ## 为什么要有它（去重）
//
// 在此之前，commondev 插件自带了一整套加密存储（`secrets.json` +
// AES-256-GCM + 别名表 + `${ENV}` 解析），与内核的 `internal/security`
// **完全重复**：
//
// 内核 security.Store 插件 unifiedSecretFile
// 落盘 secrets.json secrets.json
// 加密 AES-256-GCM AES-256-GCM
// 别名 HMAC 自动派生 用户指定
// 引用语法 @{sec_xxx} @{name}
//
// 重复的代价不只是代码量：**两套变量库互不可见** —— 内核拦截时登记的
// 变量，插件看不到；插件登记的，内核拦截不认识。结果是同一个凭据可能
// 在两处各存一份，而使用者不知道哪个才是权威。
//
// ## ★ 安全设计：明文的边界
//
// 内核的硬约束 S1 是「不提供取回明文的接口」—— 理由是一旦 LLM 能取回，
// 它就能把明文写回上下文，整层防护作废。
//
// 那为什么插件可以拿到明文？因为**边界不在插件侧**：
//
// ① 内核在**插件 handler 之前**就把工具参数里的 @{别名} 填好了
// （`StageHost.ExecuteTool` → `security.FillMap`）—— 插件本来
// 就能从 args 里读到明文，这是设计使然（否则插件无法用凭据）。
// ② 明文若被插件**返回**给内核，会被两处拦回别名：
// · `ContextEvent` 的 scrub（记忆/历史侧路）
// · provider 装饰器（出向，LLM 永不看到）
//
// 两条都有判据钉住（`leakback_test.go`）。所以：
//
// **暴露 Fill 不新增泄漏面** —— 它不是「开了一个口子」，
// 而是把「本来就存在的能力」从各插件自己实现改为统一接口。
//
// ⚠️ 但绝不能暴露 `Reveal(alias) -> 明文` 这样的**按名字直取**接口：
// 那会让插件（以及通过插件操纵它的 LLM）枚举别名并逐个取值。
// 本接口刻意**没有**这样的方法 —— 见下面 Fill 与 List 的签名。
//
// ## 与 Encrypt/Decrypt 的区别
//
// 插件常把凭据存进自己的配置文件（如 pi 的 `auth.json`）。那些文件权限
// 0600 但**明文落盘**。`Encrypt`/`Decrypt` 提供 at-rest 加密，
// 密钥由内核统一管理，插件不必自持密钥（自持会让密钥散落、无法轮换）。
type SecretsAPI interface {
// Store 把一个凭据登记进内核变量库，返回其**别名**。
//
// 之后在工具参数里写 @{别名}，内核会在调用插件前换回真实值。
//
// ★ 只返回别名，不回显明文 —— 避免插件（或它转述给 LLM 的内容）
// 顺带把明文带出去。
//
// note 是给人看的用途说明（如「Gitea 推送令牌」）。
Store(value, note string) (alias string, err error)
// List 列出变量库的元信息（别名/来源/备注/命中次数）—— **不含明文**。
//
// ★ 刻意返回元信息而非值：调用方拿不到明文，只能引用。
List() []SecretInfo
// Forget 按别名删除一个变量。
//
// ★ 变量库**不自动淘汰**（用户明确）：泄漏控制靠主动删除，不靠超时。
// 所以凭据用完后应主动删。
Forget(alias string) error
// Fill 把一段文本里的 @{别名} 换成明文。
//
// 用途：插件需要把明文喂给**不经过内核参数回填**的地方 ——
// 例如 commondev 的 enc_shell 要把命令经 **stdin** 送给 bash
//（不是 argv，避免本机其他进程从 /proc/<pid>/cmdline 读到明文）。
//
// ★ 为什么这个方法是安全的（而不是"开了个取回明文的口子"）：
// 插件**本来就**能从 `args` 里拿到内核填好的明文 ——
// 内核在 handler 之前就填了。Fill 只是让插件能对**自己构造的文本**
// 做同样的事（如读文件内容、拼一段脚本）。
//
// 它**不是**按名字直取：要填谁必须先在文本里写出那个别名，
// 而别名本身不泄漏明文（HMAC 派生）。想枚举就得先 List，
// 而 List 只给元信息 —— 拿到别名后仍只能用，不能读回。
//
// 返回替换处数与用到的别名（便于插件做输出脱敏时的比对）。
Fill(text string) (out string, replaced int, aliases []string)
// Encrypt 加密一段字节用于插件自己落盘（密钥由内核管理）。
// 返回的串带版本前缀，可直接存文件。
Encrypt(plain []byte) (string, error)
// Decrypt 解密由 Encrypt 产生的串。
Decrypt(stored string) ([]byte, error)
// Available 报告变量库是否可用（内核未启用安全模块时为 false）。
//
// ★ 插件应据此**响亮失败**而不是静默降级 —— 例如
// 「密钥不可用 ⇒ 拒绝明文存储」。
Available() bool
}
// SecretInfo 是一条变量的元信息（**不含明文**）。
type SecretInfo struct {
Alias string `json:"alias"`
Source string `json:"source"` // intercepted | submitted
Note string `json:"note,omitempty"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at,omitempty"`
Hits int `json:"hits,omitempty"`
}

15
third_party/homeagent-sdk/sdk/settings.go vendored
View File

@ -7,6 +7,21 @@ type SettingsAPI interface {
// Set writes a config value to the plugin's own config table.
Set(key string, value interface{}) error
// SetSecret writes a value that is ALWAYS encrypted at rest, regardless of
// the key name. Use it when the key name is neutral (e.g. "blob", "conn")
// and so cannot be detected as sensitive automatically.
//
// Returns an error (not a silent plaintext write) when no master key is
// installed — a plugin that believes it stored a secret must not end up
// with plaintext on disk.
//
// The companion read is GetSecret. ConfigDef.Secret/Type=="password" and
// sensitive key names are encrypted automatically and do NOT need this.
SetSecret(key string, value interface{}) error
// GetSecret reads a value written by SetSecret (transparently decrypted).
GetSecret(key string) (string, error)
// List returns all keys matching the given prefix.
List(prefix string) ([]string, error)