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-11-05 08:47:27 +00:00 · 2026-10-17 19:18:24 +08:00
parent 03d87a4e21
commit a68d6a428c
266 changed files with 30185 additions and 1424 deletions
--- a/internal/plugins/pluginmgr/plugin.go
+++ b/internal/plugins/pluginmgr/plugin.go
@ -95,6 +95,12 @@ type Plugin struct {
 	httpAddr  string // 本实例的监听地址（默认 defaultHTTPAddr；来自 settings）
 	sdk       *sdk.PluginSDK
 	pluginDir string
+	// maxPackageBytes 是单个插件包 **压缩后** 的上限（0 = 不限）。
+	//
+	// 为什么是配置项而不是常量：内嵌运行时（node+pi 之类）就要 ~100MB，
+	// 硬编码一个数必然在某天成为纯粹的障碍。默认值给得很宽松（见
+	// defaultMaxPackageMB），有需要的部署可以调大或设为 0 关闭。
+	maxPackageBytes int64
 }

 func New(name string) *Plugin {
@ -116,6 +122,18 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Category: "pluginmgr",
 	})

+	s.Settings().RegisterDef(sdk.ConfigDef{
+		Key:         "max_package_mb",
+		Default:     defaultMaxPackageMB,
+		Type:        "int",
+		DisplayName: "插件包大小上限 (MB)",
+		Description: "单个插件包**压缩后**的字节上限；0 = 不限制。" +
+			"内嵌运行时（node/pi 等）的包实测约 99MB，旧上限 100MB 下余量仅 1MB —— " +
+			"需要更大就调高，或设 0 关闭限制。" +
+			"该值在**读入内存之前**生效，不是事后检查。",
+		Category: "pluginmgr",
+	})
+
 	// 只写本实例字段，**不写任何包级状态**（见 defaultHTTPAddr 注释）。
 	p.httpAddr = defaultHTTPAddr
 	if v, _ := s.Settings().Get("http_addr"); v != nil {
@ -124,14 +142,44 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		}
 	}

-	if v, _ := s.Settings().GetCore("plugin.dir"); v != nil {
-		if dir, ok := v.(string); ok && dir != "" {
+	// ★ pluginDir 的正确来源是**内核**（PluginMgrAPI.PluginDir），
+	// 不是 core.plugin.dir 配置项。
+	//
+	// 实测教训（2026-10-15）：用 GetCore("plugin.dir") 读时，生产 config.db
+	// 里**根本没有这个键**（内核只是"播种"默认值，不一定落库），于是
+	// p.pluginDir 为空 —— 而所有以它为起点的功能（技能重扫、删除插件目录）
+	// 会**静默什么都不做**。安装却照常成功（那条路径用的是自己算的 dir），
+	// 所以症状是"局部静默失效"，极难发现。
+	//
+	// 先问内核，配置项只作兼容回退。
+	if mgr := p.pluginMgr(); mgr != nil {
+		if dir := strings.TrimSpace(mgr.PluginDir()); dir != "" {
 			p.pluginDir = dir
 		}
 	}
+	if p.pluginDir == "" {
+		if v, _ := s.Settings().GetCore("plugin.dir"); v != nil {
+			if dir, ok := v.(string); ok && dir != "" {
+				p.pluginDir = dir
+			}
+		}
+	}
+
+	// 上限也走"先给默认值再覆盖"，与本文件其他配置项一致
+	// （避免 settings 尚未就绪时拿到 0 而变成"无限制"）。
+	p.maxPackageBytes = int64(defaultMaxPackageMB) << 20
+	if v, _ := s.Settings().Get("max_package_mb"); v != nil {
+		p.maxPackageBytes = parseLimitMB(v)
+	}

 	p.registerTools(s)

+	// ★ 启动重扫随包 skill：移交只在**安装那一刻**发生，而 skill 落在
+	// 插件目录里（不在 skillmgr 的 skillsDir）⇒ worker 重启后它会**静默消失**。
+	// 延迟几秒是为了等 skillmgr 的订阅就绪（两者 Start 顺序不确定）；
+	// skillmgr 的 loadOne 幂等，重复到达无副作用。见 skill_handout.go。
+	p.scheduleStartupSkillRescan()
+
 	if p.httpAddr != "" {
 		p.startHTTPServer()
 	}
@ -245,6 +293,160 @@ func (p *Plugin) registerTools(s *sdk.PluginSDK) {
 		return p.restartPlugin(name)
 	})

+	// ---- 持久启用/禁用（设计 §2.6.7.4）----
+	//
+	// 与 plugin_start/stop 的分工：
+	//   enable/disable ⇒ **持久**（写 disabled_plugins，跨重启保留）= 系统里"禁止运行"
+	//   start/stop     ⇒ **运行态**（不写配置）                = 现在关掉这个窗口
+	s.RegisterTool("plugin_disable", sdk.ToolDef{
+		Name: "plugin_disable",
+		Description: "**持久**禁用插件：停止它并写入禁用配置，**跨重启保留**（开机也不再自启）。" +
+			"如果只是想临时关掉它、不希望影响开机自启，请用 plugin_stop。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.DisablePlugin(name, "agent"); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "disabled",
+			"name":       name,
+			"persistent": "已写入禁用配置（跨重启保留）",
+		}, nil
+	})
+
+	s.RegisterTool("plugin_enable", sdk.ToolDef{
+		Name: "plugin_enable",
+		Description: "**持久**启用插件：解除禁用配置并立即加载它（跨重启保留）。" +
+			"注意：它同时**清除禁用标记**，所以之后开机会自启；" +
+			"若只是想把 plugin_stop 关掉的插件开回来，用 plugin_start 更精确。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.EnablePlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "enabled",
+			"name":       name,
+			"persistent": "禁用标记已清除（之后开机会自启）",
+		}, nil
+	})
+
+	// ---- 运行态启停（设计 §2.6.7.4）----
+	//
+	// ★ 与 plugin_enable/plugin_disable 的分工（用户明确指出"只有 reload"的缺口）：
+	//
+	//	plugin_enable/disable ⇒ **持久**：写 disabled_plugins，跨重启保留
+	//	plugin_start/stop     ⇒ **运行态**：现在启停，不写任何配置
+	//
+	// 缺了这两个的直接后果：agent 想"临时关掉某插件看现象"只能调
+	// plugin_disable ⇒ 顺带把开机自启也关了 ⇒ 用户下次开机发现"怎么不启动了"。
+	s.RegisterTool("plugin_start", sdk.ToolDef{
+		Name: "plugin_start",
+		Description: "**运行态**启动一个插件：现在拉起它，**不改持久状态**（重启后仍按" +
+			"开机自启/禁用配置决定）。用于把 plugin_stop 关掉的插件开回来。" +
+			"注意：被**持久禁用**的插件会被拒绝，那种情况请用 plugin_enable。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.StartPlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status": "started",
+			"name":   name,
+			// ★ 明确告知这是运行态操作，避免 agent 误以为改了持久设置
+			"persistent": "未改动（重启后按开机自启/禁用配置决定）",
+		}, nil
+	})
+
+	s.RegisterTool("plugin_stop", sdk.ToolDef{
+		Name: "plugin_stop",
+		Description: "**运行态**关闭一个插件：现在停掉它，**不改持久状态**" +
+			"（不会影响开机自启，重启后该插件正常加载）。用于临时腾出资源或隔离问题。" +
+			"与 plugin_disable 不同 —— 后者会**持久**禁用（跨重启保留）。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.StopPlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "stopped",
+			"name":       name,
+			"persistent": "未改动（开机自启设置不变，重启后会重新加载）",
+		}, nil
+	})
+
 	s.RegisterTool("plugin_remove", sdk.ToolDef{
 		Name:        "plugin_remove",
 		Description: "卸载一个已安装的外部插件",
@ -370,9 +572,9 @@ func (p *Plugin) handlePlugins(w http.ResponseWriter, r *http.Request) {
 				return
 			}
 		} else {
-			data, err := io.ReadAll(r.Body)
+			data, err := readLimited(r.Body, p.maxPackageBytes)
 			if err != nil {
-				http.Error(w, "read body: "+err.Error(), http.StatusBadRequest)
+				http.Error(w, err.Error(), http.StatusRequestEntityTooLarge)
 				return
 			}
 			result, err := p.installFromData(data, false)
@ -430,10 +632,22 @@ func (p *Plugin) handlePluginByID(w http.ResponseWriter, r *http.Request) {
 // ======== Core Logic ========

 func (p *Plugin) installFromPath(path string, overwrite bool) (interface{}, error) {
-	data, err := os.ReadFile(path)
+	// 本地文件同样走限流读：先 Stat 拿大小快速拒绝（避免白读一遍），
+	// 再用 readLimited 兜住"Stat 与读取之间文件变大"的竞态。
+	if p.maxPackageBytes > 0 {
+		if st, err := os.Stat(path); err == nil && st.Size() > p.maxPackageBytes {
+			return nil, errPackageTooLarge(p.maxPackageBytes)
+		}
+	}
+	f, err := os.Open(path)
 	if err != nil {
 		return nil, fmt.Errorf("read file: %w", err)
 	}
+	defer f.Close()
+	data, err := readLimited(f, p.maxPackageBytes)
+	if err != nil {
+		return nil, err
+	}
 	return p.installFromData(data, overwrite)
 }

@ -458,9 +672,14 @@ func (p *Plugin) installFromURL(rawURL string, overwrite bool) (interface{}, err
 		return nil, fmt.Errorf("download returned %s", resp.Status)
 	}

-	data, err := io.ReadAll(resp.Body)
+	// 先用 Content-Length 快速拒绝（覆盖绝大多数情况），再用 readLimited
+	// 兜住分块传输（Content-Length 缺失或撒谎）。
+	if p.maxPackageBytes > 0 && resp.ContentLength > p.maxPackageBytes {
+		return nil, errPackageTooLarge(p.maxPackageBytes)
+	}
+	data, err := readLimited(resp.Body, p.maxPackageBytes)
 	if err != nil {
-		return nil, fmt.Errorf("read response: %w", err)
+		return nil, err
 	}

 	result, err := p.installFromData(data, overwrite)
@ -548,6 +767,10 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 		}
 		os.RemoveAll(backup)

+		// ★ 随包 skill 移交（升级路径）：解压完成后才扫，否则目录还不完整。
+		// 失败不阻断 —— skill 登记是附带收益，插件本身已装好。
+		skillN, skillFailed := p.handOutPluginSkills(target, pkg.Name)
+
 		checksum := fmt.Sprintf("%x", sha256.Sum256(data))
 		action := "upgraded"
 		if cmpVersion(pkg.Version, oldVersion) < 0 {
@ -556,15 +779,17 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 			action = "reinstalled"
 		}
 		return map[string]interface{}{
-			"status":           "installed",
-			"name":             pkg.Name,
-			"version":          pkg.Version,
-			"previous_version": oldVersion,
-			"entry":            pkg.Entry,
-			"checksum":         checksum,
-			"action":           action,
-			"reload_required":  true,
-			"config_kept":      true,
+			"status":            "installed",
+			"name":              pkg.Name,
+			"version":           pkg.Version,
+			"previous_version":  oldVersion,
+			"entry":             pkg.Entry,
+			"checksum":          checksum,
+			"action":            action,
+			"reload_required":   true,
+			"config_kept":       true,
+			"skills_registered": skillN,
+			"skills_failed":     skillFailed,
 		}, nil
 	}

@ -577,13 +802,18 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro

 	checksum := fmt.Sprintf("%x", sha256.Sum256(data))

+	// ★ 随包 skill 移交（全新安装路径）。
+	skillN, skillFailed := p.handOutPluginSkills(target, pkg.Name)
+
 	return map[string]interface{}{
-		"status":   "installed",
-		"name":     pkg.Name,
-		"version":  pkg.Version,
-		"entry":    pkg.Entry,
-		"checksum": checksum,
-		"action":   "reload_required",
+		"status":            "installed",
+		"name":              pkg.Name,
+		"version":           pkg.Version,
+		"entry":             pkg.Entry,
+		"checksum":          checksum,
+		"action":            "reload_required",
+		"skills_registered": skillN,
+		"skills_failed":     skillFailed,
 	}, nil
 }

@ -835,23 +1065,123 @@ type pluginPackage struct {
 	Platforms []string `json:"platforms,omitempty"`
 }

-func validatePackage(data []byte) (*pluginPackage, error) {
-	if len(data) > 100<<20 {
-		return nil, fmt.Errorf("package too large (>100MB)")
-	}
+const (
+	// defaultMaxPackageMB 是插件包默认上限（MB）。
+	//
+	// 为什么给这么大：内嵌运行时的插件包本身就接近 100MB
+	// （node 二进制约 50MB + pi 依赖闭包约 50MB，压缩后）。
+	// 这个值只作为"防止手滑传错文件"的兜底，真正的 DoS 防护
+	// 由 readLimited 在**读取前**按 Content-Length / LimitReader 完成。
+	//
+	// 需要更大（或不需要限制）时改插件设置 max_package_mb（0 = 不限）。
+	defaultMaxPackageMB = 512
+)

+// errPackageTooLarge 是统一的超限错误（三种入口共用）。
+func errPackageTooLarge(limit int64) error {
+	return fmt.Errorf("package too large (>%dMB)；如确需更大，请调整插件设置 max_package_mb（0 = 不限）", limit>>20)
+}
+
+// parseLimitMB 把配置值解析成字节上限（0 = 不限）。
+//
+// ★ 必须处理 string：插件配置从 DB 读出来是**字符串**
+// （config.PluginSettings.Get → openFromStorage 返回 string），
+// 不是 int/float64。初版照抄了 agentcli 的 `v.(float64)` 假设，
+// 于是 switch 一个分支都不匹配 ⇒ **配置被静默忽略**，
+// 用户改了 max_package_mb 却不生效，且没有任何提示。
+//
+// 兼容其它形态是为了稳健（不同装配路径可能给出不同静态类型），
+// 但 string 是真实路径，必须有判据钉住。
+func parseLimitMB(v interface{}) int64 {
+	var mb int64
+	switch n := v.(type) {
+	case string:
+		s := strings.TrimSpace(n)
+		if s == "" {
+			return int64(defaultMaxPackageMB) << 20
+		}
+		parsed, err := strconv.ParseInt(s, 10, 64)
+		if err != nil {
+			log.Printf("[pluginmgr] max_package_mb=%q 不是整数，回退默认 %dMB", s, defaultMaxPackageMB)
+			return int64(defaultMaxPackageMB) << 20
+		}
+		mb = parsed
+	case int:
+		mb = int64(n)
+	case int64:
+		mb = n
+	case float64:
+		mb = int64(n)
+	default:
+		log.Printf("[pluginmgr] max_package_mb 类型意外（%T），回退默认 %dMB", v, defaultMaxPackageMB)
+		return int64(defaultMaxPackageMB) << 20
+	}
+	if mb < 0 {
+		// 负数视为"不限"（与 0 同义），而不是"拒一切" ——
+		// 配置误填负号不该让插件系统完全不可用。
+		mb = 0
+	}
+	return mb << 20
+}
+
+// readLimited 读入 reader 并在 **读取过程中** 施加上限。
+//
+// ★ 为什么必须在这里做，而不是读完再检查：
+//
+// 原实现在 io.ReadAll 之后才 `len(data) > 100<<20`。那时内存**已经占用**，
+// 一个声明 `Content-Length: 10GB` 的请求可以先把进程撑爆再收到"包太大"的报错 ——
+// 限制形同虚设。读前限流才是有意义的防护（也是本次把上限变成配置项的前提：
+// 放宽一个无效检查不会带来新风险，放寛一个有效检查才会）。
+//
+// limit <= 0 表示不限制。
+func readLimited(r io.Reader, limit int64) ([]byte, error) {
+	if limit <= 0 {
+		return io.ReadAll(r)
+	}
+	// 多读 1 字节：能读到 limit+1 才说明确实超了，
+	// 否则恰好等于 limit 的包会被误判（边界差一）。
+	lr := io.LimitReader(r, limit+1)
+	data, err := io.ReadAll(lr)
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > limit {
+		return nil, errPackageTooLarge(limit)
+	}
+	return data, nil
+}
+
+// validatePackage 只做**结构合法性**校验（元数据、平台二进制、路径安全）。
+//
+// 大小不在这里判：它必须在读入内存之前决定，见 readLimited。
+// （曾经这里有一个 `len(data) > 100<<20` 的检查，属于"事后检查"，
+// 挡不住任何东西却会在有一天需要大包时成为障碍 —— 已移除。）
+func validatePackage(data []byte) (*pluginPackage, error) {
 	reader, err := zip.NewReader(bytes.NewReader(data), int64(len(data)))
 	if err != nil {
 		return nil, fmt.Errorf("invalid zip: %w", err)
 	}

+	// ★ 路径检查必须遍历**全部**条目，与找 manifest 分开。
+	//
+	// 原实现把路径检查放在寻找 plugin.json 的循环里，而该循环找到
+	// manifest 后会 `break` —— 于是排在 plugin.json **之后**的条目
+	// 完全没被检查。hmapdev 打包出的 rawfile 条目恒在 plugin.json 之后，
+	// 正好落在检查盲区（实测发现）。
+	//
+	// 落盘侧（extractPackage）另有独立的 path traversal 检查，
+	// 所以这不是可利用漏洞；但"校验函数只校验了一部分还叫校验"本身就是缺陷，
+	// 且一旦将来有人复用 validatePackage 做准入判断就会出事。
+	for _, f := range reader.File {
+		if strings.Contains(f.Name, "..") || strings.HasPrefix(f.Name, "/") {
+			return nil, fmt.Errorf("invalid path: %s", f.Name)
+		}
+	}
+
 	var pkg pluginPackage
 	hasManifest := false

 	for _, f := range reader.File {
-		if strings.Contains(f.Name, "..") || strings.HasPrefix(f.Name, "/") {
-			return nil, fmt.Errorf("invalid path: %s", f.Name)
-		}
 		if f.FileInfo().IsDir() {
 			continue
 		}