mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-22 18:08:04 +00:00
Compare commits
5 Commits
v1.2.0-bet
...
v1.2.0
| Author | SHA1 | Date | |
|---|---|---|---|
| f550bb2cca | |||
| 551a423322 | |||
| 6b9a7f36fd | |||
| 70f03354a2 | |||
| 4f9370ae7a |
@ -190,7 +190,7 @@ internal/
|
||||
├── config/ SQLite 配置中心
|
||||
├── events/ 事件总线
|
||||
└── internal/lua/adapters/ 8 个 LLM 协议适配器脚本
|
||||
外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `plugindev` 工具链开发，参考 `example/` 目录下的 Go 和 Lua 示例
|
||||
外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `hmapdev` 工具链开发，参考 `example/` 目录下的 Go 和 Lua 示例
|
||||
```
|
||||
|
||||
## 项目状态
|
||||
@ -209,7 +209,7 @@ internal/
|
||||
是块的**迁移**，不是复制、也不靠引用保活。
|
||||
- **数据面全部走共享内存**（工具调用帧 / Cleaner / 输入输出通道 / 媒体块 / 文档与知识正文），
|
||||
RPC 只传偏移描述符；**RPC 协议升到 2**，fd3 布局改变，**不支持滚动升级**——
|
||||
内核与全部插件必须同批重建、同批安装，存量插件须用新版 `plugindev` 重编。
|
||||
内核与全部插件必须同批重建、同批安装，存量插件须用新版 `hmapdev` 重编。
|
||||
- 注入可声明 `InjectOptions{NoMemory, ContextPolicy}`（**默认仍记入记忆、默认不裁剪**）；
|
||||
裁剪必须显式声明，且先经插件注册的 `Cleaner`。SDK 1.2.0 相对 1.1.0 **纯追加**。
|
||||
- **发行包默认启用** ONNX 向量空间，并把模型（754MB）与 ONNX Runtime（24MB）随
|
||||
@ -226,7 +226,7 @@ internal/
|
||||
|
||||
**v1.1.0** — 记忆系统支持**二进制多媒体节点**。内容寻址媒体存储（CAS + SQLite 元数据 + 磁盘 blob，`Get` always 重校 digest），贯通 L0（上下文事件）/L2（文档）/L3（图谱句子）三层，引用计数式 GC（有引用者绝不删）。视觉模型生成的描述文本是持久语义记忆，blob 只是可被容量 GC 淘汰的缓存。
|
||||
|
||||
**v1.0.0** — 外部插件从 C ABI 动态库迁移到**子进程 + 共享内存**。首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件须用新版 `plugindev` 重编为 `plugin.bin`，**业务代码零改动**）。消除 6 类此前在生产造成故障的缺陷：热重载失效（`DF_1_NODELETE` 让 `dlclose` 成 no-op）、崩溃隔离缺失（插件 panic 带崩 homed）、stage lost update（副本模型丢失 35.8~36.8%）、cgo 超时不可中断（线程线性泄漏）、`output_send` 假成功（模型收到「已发送」而消息未送达）、Windows 能力断层（只见 3 个 stage 字段且无法写回）。三面通信：stdio JSON-RPC（控制）+ 共享内存段（数据）+ 事件环（通知）；权限梯度显式化为三道闸。RPC 往返 p50 24.1µs，崩溃到恢复 <1s。
|
||||
**v1.0.0** — 外部插件从 C ABI 动态库迁移到**子进程 + 共享内存**。首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件须用新版工具链重编；该工具链当时名为 `plugindev`，**现名 `hmapdev`**）。外部插件需重编为 `plugin.bin`，**业务代码零改动**）。消除 6 类此前在生产造成故障的缺陷：热重载失效（`DF_1_NODELETE` 让 `dlclose` 成 no-op）、崩溃隔离缺失（插件 panic 带崩 homed）、stage lost update（副本模型丢失 35.8~36.8%）、cgo 超时不可中断（线程线性泄漏）、`output_send` 假成功（模型收到「已发送」而消息未送达）、Windows 能力断层（只见 3 个 stage 字段且无法写回）。三面通信：stdio JSON-RPC（控制）+ 共享内存段（数据）+ 事件环（通知）；权限梯度显式化为三道闸。RPC 往返 p50 24.1µs，崩溃到恢复 <1s。
|
||||
|
||||
**v0.9.0** — C ABI v2：外部插件 Stage 回调支持写回（`invoke_stage` 增加 result 输出，插件可在 OnInput/AfterToolcall/PostAction 修改 RawMessage/LLMText/ToolResults 等并同步回内核），ABI 版本随内核 minor 对齐（v0.9.x → ABIVersion=2，`version_min=1` 向后兼容旧插件）。同步修复工具循环 zen 兼容补位误伤首轮 system 上下文的问题。配套 SDK 提供增强版 sanitizer 示例（坏 UTF-8/U+FFFD/ANSI 转义全链路清洗）。**该 ABI 已随 v1.0.0 退场。**
|
||||
|
||||
|
||||
@ -179,7 +179,7 @@ internal/
|
||||
├── config/ SQLite config center
|
||||
├── events/ Event bus
|
||||
└── internal/lua/adapters/ 8 LLM protocol adapter scripts
|
||||
External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo, use `plugindev` toolchain, refer to Go and Lua examples in `example/`
|
||||
External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo, use `hmapdev` toolchain, refer to Go and Lua examples in `example/`
|
||||
```
|
||||
|
||||
## Project Status
|
||||
@ -240,7 +240,7 @@ by `-race`; in production this showed up as sporadic nil-dereference crashes dur
|
||||
items are never deleted). The description text produced by the vision model is the durable
|
||||
semantic memory; the blob is only a cache that capacity GC may evict.
|
||||
|
||||
**v1.0.0** — External plugins moved from C ABI shared libraries to **subprocess + shared memory**. The first release that no longer loads `.so`/`.dll`, and it is incompatible with 0.9.x (existing plugins must be rebuilt into `plugin.bin` with the new `plugindev`, though **business code needs zero changes**). Eliminates 6 classes of defects that had caused production incidents: hot-reload silently failing (`DF_1_NODELETE` making `dlclose` a no-op), no crash isolation (a plugin panic took down homed), stage lost updates (35.8~36.8% loss under the copy model), uncancellable cgo timeouts (linear OS-thread leaks), `output_send` reporting false success (the model was told "sent" while the message never went out), and Windows capability degradation (only 3 stage fields visible, no write-back). Three communication planes: stdio JSON-RPC (control) + shared memory segment (data) + event ring (notification); the privilege gradient is now enforced by three explicit gates. RPC round-trip p50 24.1µs; crash-to-recovery under 1s.
|
||||
**v1.0.0** — External plugins moved from C ABI shared libraries to **subprocess + shared memory**. The first release that no longer loads `.so`/`.dll`, and it is incompatible with 0.9.x (existing plugins must be rebuilt into `plugin.bin` with the new toolchain — called `plugindev` back then, **now `hmapdev`** — though **business code needs zero changes**). Eliminates 6 classes of defects that had caused production incidents: hot-reload silently failing (`DF_1_NODELETE` making `dlclose` a no-op), no crash isolation (a plugin panic took down homed), stage lost updates (35.8~36.8% loss under the copy model), uncancellable cgo timeouts (linear OS-thread leaks), `output_send` reporting false success (the model was told "sent" while the message never went out), and Windows capability degradation (only 3 stage fields visible, no write-back). Three communication planes: stdio JSON-RPC (control) + shared memory segment (data) + event ring (notification); the privilege gradient is now enforced by three explicit gates. RPC round-trip p50 24.1µs; crash-to-recovery under 1s.
|
||||
|
||||
**v0.9.0** — C ABI v2: external plugin Stage callbacks can now write back (`invoke_stage` gained a result out-param; plugins may mutate RawMessage/LLMText/ToolResults etc. in OnInput/AfterToolcall/PostAction and have them synced to the core). ABI version now tracks core minor releases (v0.9.x → ABIVersion=2, `version_min=1` keeps old plugins loadable). Also fixes the tool-loop zen-compat placeholder that wrongly fired on first-turn system context tail. The SDK ships an enhanced sanitizer example (bad-UTF-8 / U+FFFD / ANSI-escape scrub across the whole pipeline). **This ABI retired with v1.0.0.**
|
||||
|
||||
|
||||
@ -90,8 +90,8 @@ Setting `ctx.Response` at any stage jumps to `after_output`.
|
||||
RelevanceContext — In-memory events[] + JSON persistence
|
||||
Append: Each input, CleanTemplateText → three-branch vector(textForVector)
|
||||
agent→Response, user→Input, cold_storage→Input+Response
|
||||
StaticEmbedder pretrained word embedding / TF-IDF fallback
|
||||
Prune: StaticEmbedder CosineSimilarity, keep topK + last 10
|
||||
Vector layers: unified multimodal space (primary, with fingerprint) → StaticEmbedder word embedding → TF-IDF (fallback)
|
||||
Prune: DenseCosine (compared only within the same fingerprint) → StaticEmbedder CosineSimilarity fallback; keep topK + last 10
|
||||
├── Keep → timeline → chronologically sorted → system prompt
|
||||
└── Low score → Document layer archive (original timestamp)
|
||||
Save: 5s debounce write to disk
|
||||
@ -99,7 +99,7 @@ Setting `ctx.Response` at any stage jumps to `after_output`.
|
||||
↓ Prune archive ↑ LLM active recall
|
||||
|
||||
② Document (File Memory)
|
||||
DocStore — JSON files + shared StaticEmbedder vector space with Context (fallback: TF-IDF InvertedIndex)
|
||||
DocStore — JSON files + dense vectors (unified multimodal space; dense_fp must match the current space fingerprint or the doc is recomputed; fallback: StaticEmbedder / TF-IDF InvertedIndex)
|
||||
Write: Prune archive / doc_commit / Graph snapshot (syncGraphToDocs)
|
||||
Read:
|
||||
├── Auto-inject: Query(input, top3) → similarity summary under same vector space → [Related Memory Docs] → system prompt (read-only)
|
||||
@ -132,11 +132,22 @@ Setting `ctx.Response` at any stage jumps to `after_output`.
|
||||
→ triples → GraphDB.Commit
|
||||
```
|
||||
|
||||
### Vectorization: Pretrained Word Embedding + TF-IDF Fallback
|
||||
### Vectorization: Unified Multimodal Space (primary) → Word Embedding → TF-IDF (fallback)
|
||||
|
||||
All vectorization unified under `StaticEmbedder` (`internal/memory/static_embedder.go`):
|
||||
Vectorization degrades through three layers by availability; **each missing layer reports an explicit
|
||||
error and never pretends to succeed**:
|
||||
|
||||
**Primary Strategy — Pretrained Word Embedding (aligned 300d)**
|
||||
**① Unified multimodal space (primary path, since v1.2.0)**
|
||||
Text and images share **one model, one dimension, one fingerprint** (default `chineseclip`: 512d,
|
||||
Apache-2.0, Chinese-native; `qwen3vl` or an external `http` provider are alternatives).
|
||||
Providers register through the public `pkg/embedding` SPI — **the kernel hardcodes no model**.
|
||||
Vectors persist together with their fingerprint (`dense_fp` / `vec_model`); any mismatch with the
|
||||
current fingerprint triggers recomputation, and only blocks with the **same fingerprint and the same
|
||||
dimension** participate in fusion (mixing coordinate systems yields a direction resembling neither).
|
||||
|
||||
**② Word embedding (text fallback)** — `StaticEmbedder` (`internal/memory/static_embedder.go`):
|
||||
|
||||
**Model sources** (aligned 300d)
|
||||
- Model sources: ConceptNet Numberbatch (77-language aligned) / fastText Chinese / fastText English
|
||||
- Configured via `core.agent.embedding_model_path` (comma-separated multi-model)
|
||||
- Path containing `numberbatch` → auto-download ConceptNet; `cc.zh.` → fastText Chinese; `cc.en.` → fastText English
|
||||
@ -196,28 +207,32 @@ single typo silently breaks reference binding with no error anywhere in the chai
|
||||
also gained `sentence_text`: media references hang off a sentence, so with no sentence there is
|
||||
nowhere to attach them.
|
||||
|
||||
### Media Memory (since v1.1.0)
|
||||
### Media Memory (since v1.2.0: first-class memory blocks)
|
||||
|
||||
`internal/memory/media/` — `Store`, content-addressed (CAS)
|
||||
Media is not attached content but a **first-class memory node**: `internal/memory/media/` is a
|
||||
content-addressed store (CAS), and graph `block` nodes carry its digest plus its own vector, while
|
||||
structural edges (e.g. `sentence --contains--> block`) express ownership.
|
||||
|
||||
| Concern | Approach | Why |
|
||||
|---|---|---|
|
||||
| Addressing | sha256 digest; metadata in SQLite, blobs on disk | Identical bytes stored once; metadata must be queryable, blobs must not live in the database |
|
||||
| Addressing | sha256 digest; metadata in SQLite, blobs on disk (`blobs/<first2>/<rest>`, two-level fanout) | Identical bytes stored once; metadata must be queryable, blobs must not live in the database |
|
||||
| Integrity | Every `Get` re-verifies the digest | Silently returning corrupt data on disk damage is far worse than an error |
|
||||
| Write atomicity | `.tmp` + rename | A half-written file taken as complete content would permanently poison that digest |
|
||||
| References | `owner_kind/owner_id/digest` composite primary key, `AddRef` idempotent | Three owner kinds: `context` (context events), `document`, `graph_sentence` |
|
||||
| GC | Two-stage with `minAge`, **referenced items are never deleted** | Description text stays in the text layers while blobs may be evicted — semantic memory and byte cache are decoupled |
|
||||
| Retrieval | Blocks carry **their own multimodal vector and fingerprint** and are searched directly | No description text is needed as an intermediary |
|
||||
| Lifecycle | **No separate GC, no refcounts, no keep-set**; deleting the block deletes the content | Media is a memory node, not a cache that needs keeping alive |
|
||||
|
||||
**How media is represented in plain-text memory** is the marker `[<mime> <short digest>] <description>`:
|
||||
**Description-based indexing is gone**: the old implementation embedded a
|
||||
`[<mime> <short digest>] <description>` marker in the body and treated the description as the
|
||||
semantic memory (retrieval used it). That path was removed wholesale in v1.2.0: a description is
|
||||
second-hand model output, and retrieving "someone else's paraphrase of an image" is strictly worse
|
||||
than retrieving the image's own vector. Images are now retrieved only by their own vector in the
|
||||
unified space, and no media marker is written into the body.
|
||||
|
||||
```
|
||||
[image/png a1b2c3d4e5f6] a purple-blue-red three-band chart
|
||||
```
|
||||
|
||||
Why it must ride on text: `Doc.Content`, `sentences.text` and text memory's `Input` are all strings
|
||||
— there is no field to carry structured data. **The description text is the durable semantic
|
||||
memory** (retrieval uses it); the digest is the key back to the bytes (reverse lookup uses it).
|
||||
After capacity GC evicts a blob, the description remains in the L0/L2/L3 text.
|
||||
**Cross-space vector migration**: media rows store their vector together with `vec_model` (the space
|
||||
fingerprint). At startup `reembedStaleMedia()` recomputes and **writes back** every row whose
|
||||
`vec_model` is empty (never embedded) or differs from the current space (model/dimension switched).
|
||||
Modalities outside the space return `ErrModalityUnsupported` — the kernel **never substitutes
|
||||
another model's vector**.
|
||||
|
||||
The media store is **optional throughout**: with `core.memory.media.enabled=false` or no
|
||||
configuration, the whole chain silently degrades to plain-text behaviour — no errors, no panics.
|
||||
@ -292,7 +307,7 @@ VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`.
|
||||
| Method | Registration Mechanism | Compilation | Usage |
|
||||
|--------|----------------------|-------------|-------|
|
||||
| Built-in | `init()` → `RegisterFactory` | `internal/plugins/` compiled into kernel | webui/cli/timer/mcp etc. |
|
||||
| External subprocess plugin | Handshake + stdio JSON-RPC reverse registration | `plugindev build` → `plugin.bin` (ordinary Go binary) | qq/browser/files etc. |
|
||||
| External subprocess plugin | Handshake + stdio JSON-RPC reverse registration | `hmapdev build` → `plugin.bin` (ordinary Go binary) | qq/browser/files etc. |
|
||||
| Lua script plugin | Execute `main.lua` to register tools | No compilation, takes effect after restart/reload | luademo etc. |
|
||||
| SKILL plugin | Parse `SKILL.md` | Markdown definition | Loaded via clawhubadapter |
|
||||
|
||||
@ -311,7 +326,7 @@ Lua script plugin loading: `internal/plugin/` → the gopher-lua interpreter exe
|
||||
| Dimension | Built-in Plugin | External Plugin |
|
||||
|-----------|----------------|-----------------|
|
||||
| Registration | `init()` calls `plugin.RegisterFactory(name, factory)` | Implements `NewPluginFactory(name, config) (sdk.Plugin, error)` entry function |
|
||||
| Compilation | Compiled into `homed` binary, no separate build | Compiled via `plugindev build` to `plugin.bin` (ordinary Go binary, zero cgo); the kernel spawns it as a subprocess |
|
||||
| Compilation | Compiled into `homed` binary, no separate build | Compiled via `hmapdev build` to `plugin.bin` (ordinary Go binary, zero cgo); the kernel spawns it as a subprocess |
|
||||
| Distribution | Bundled with kernel, not independently installable | `.hmap` package (ZIP archive), installed via WebUI or pluginmgr API |
|
||||
| Metadata | `plugin.RegisterPluginMeta()` for display name | `plugin.json` manifest file (name, version, entry, platforms, capabilities, etc.) |
|
||||
| Plugin directory | No separate directory, compiled into binary | `plugins/<name>/` independent directory with `plugin.json` + `plugin.bin` |
|
||||
|
||||
@ -29,75 +29,80 @@ type Plugin interface {
|
||||
|
||||
| Method | Use Case | Complexity |
|
||||
|--------|----------|------------|
|
||||
| **Subprocess plugin (recommended)** | Independently distributed third-party plugins | Medium, generated using `plugindev` toolchain |
|
||||
| **Subprocess plugin (recommended)** | Independently distributed third-party plugins | Medium, generated using `hmapdev` toolchain |
|
||||
| **Built-in plugin** | Released with HomeAgent | Simple, requires merging into main repo |
|
||||
| **Lua script plugin** | Lightweight rapid prototyping | Simple, generated using `plugindev init --lua` |
|
||||
| **Lua script plugin** | Lightweight rapid prototyping | Simple, generated using `hmapdev init --lua` |
|
||||
|
||||
---
|
||||
|
||||
<img src="../../assets/branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
|
||||
|
||||
## 1. Quick Start: Using the plugindev Toolchain
|
||||
## 1. Quick Start: Using the hmapdev Toolchain
|
||||
|
||||
`plugindev` is the unified plugin development toolchain provided in the SDK repository, supporting both Go and Lua plugin types.
|
||||
`hmapdev` is the unified plugin development toolchain provided in the SDK repository, supporting both Go and Lua
|
||||
plugin types, and producing `.hmap` plugin bundles (the tool is named after that package format).
|
||||
|
||||
> Rename note: as of 1.2.0 the toolchain was renamed from `plugindev` to `hmapdev`; the SDK store moved from
|
||||
> `~/.homeagent/plugindev/sdk` to `~/.homeagent/hmapdev/sdk` (the old directory keeps working automatically).
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
cd homeagent-sdk/tools/plugindev
|
||||
go build -o plugindev
|
||||
# Add plugindev to PATH or use directly
|
||||
cd homeagent-sdk/tools/hmapdev
|
||||
go build -o hmapdev
|
||||
# Add hmapdev to PATH or use directly
|
||||
# Prebuilt binaries also ship as release assets (hmapdev_linux_amd64, ...)
|
||||
```
|
||||
|
||||
### SDK Version Management
|
||||
|
||||
`plugindev sdk` manages local SDK versions:
|
||||
`hmapdev sdk` manages local SDK versions:
|
||||
|
||||
```bash
|
||||
plugindev sdk list # list installed SDK versions
|
||||
plugindev sdk current # show current SDK version
|
||||
plugindev sdk latest # show latest available version
|
||||
plugindev sdk install v0.8.0 # install a specific version
|
||||
plugindev sdk use v0.8.0 # switch to a version
|
||||
plugindev sdk path # show current SDK path
|
||||
hmapdev sdk list # list installed SDK versions
|
||||
hmapdev sdk current # show current SDK version
|
||||
hmapdev sdk latest # show latest available version
|
||||
hmapdev sdk install v1.2.0 # install a specific version
|
||||
hmapdev sdk use v1.2.0 # switch to a version
|
||||
hmapdev sdk path # show current SDK path
|
||||
```
|
||||
|
||||
SDK is stored at `~/.homeagent/plugindev/sdk/<version>/`; `plugindev init` reads the current SDK version for `go.mod`.
|
||||
SDK is stored at `~/.homeagent/hmapdev/sdk/<version>/`; `hmapdev init` reads the current SDK version for `go.mod`.
|
||||
|
||||
### Source Debugging
|
||||
|
||||
`plugindev debug` interprets plugin source and prints a call trace, no compilation environment needed:
|
||||
`hmapdev debug` interprets plugin source and prints a call trace, no compilation environment needed:
|
||||
|
||||
```bash
|
||||
plugindev debug [dir] # dir defaults to the current directory
|
||||
hmapdev debug [dir] # dir defaults to the current directory
|
||||
```
|
||||
|
||||
### Creating a Go Plugin
|
||||
|
||||
```bash
|
||||
plugindev init myplugin
|
||||
hmapdev init myplugin
|
||||
cd myplugin
|
||||
# Edit plugin code
|
||||
vim plugin.go
|
||||
# Build and package (default is a multi-platform bundle, see below)
|
||||
plugindev build
|
||||
hmapdev build
|
||||
# Output: dist/myplugin_bundle.hmap
|
||||
# Single-platform build:
|
||||
plugindev build --no-bundle
|
||||
hmapdev build --no-bundle
|
||||
# Output: dist/myplugin_linux_amd64.hmap (or windows_amd64)
|
||||
```
|
||||
|
||||
### Creating a Lua Plugin
|
||||
|
||||
```bash
|
||||
plugindev init myluaplugin --lua
|
||||
hmapdev init myluaplugin --lua
|
||||
cd myluaplugin
|
||||
# Edit plugin code
|
||||
vim main.lua
|
||||
# Local test
|
||||
lua main.lua
|
||||
# Build and package
|
||||
plugindev build
|
||||
hmapdev build
|
||||
# Output: dist/myluaplugin_lua.hmap
|
||||
```
|
||||
|
||||
@ -128,16 +133,16 @@ myluaplugin/
|
||||
|
||||
### Build & Package
|
||||
|
||||
`plugindev build` automatically handles compilation and packaging:
|
||||
`hmapdev build` automatically handles compilation and packaging:
|
||||
|
||||
```bash
|
||||
cd myplugin
|
||||
plugindev build # default bundle mode (multi-platform)
|
||||
plugindev build --no-bundle # single-target build (per plg.json targets)
|
||||
plugindev build --target linux/amd64 # append a target on top of plg.json targets
|
||||
plugindev build --outdir dist # output directory (default: dist)
|
||||
plugindev build --sdk-path <path> # SDK path override (go.mod replace)
|
||||
plugindev build --replace <mod@path> # append a go.mod replace directive (repeatable)
|
||||
hmapdev build # default bundle mode (multi-platform)
|
||||
hmapdev build --no-bundle # single-target build (per plg.json targets)
|
||||
hmapdev build --target linux/amd64 # append a target on top of plg.json targets
|
||||
hmapdev build --outdir dist # output directory (default: dist)
|
||||
hmapdev build --sdk-path <path> # SDK path override (go.mod replace)
|
||||
hmapdev build --replace <mod@path> # append a go.mod replace directive (repeatable)
|
||||
```
|
||||
|
||||
Execution process:
|
||||
@ -171,7 +176,7 @@ the kernel picks the one matching the current platform and renames it to `plugin
|
||||
> - `plugin.so` / `plugin.dylib` / `plugin.dll` are **no longer loaded**. The new kernel
|
||||
> skips legacy artifacts with an actionable error instead of crashing.
|
||||
> - **Business code needs no changes** — the public SDK interface is unchanged; just
|
||||
> rebuild with the new `plugindev`.
|
||||
> rebuild with the new `hmapdev` (formerly `plugindev`).
|
||||
> - The `entry` field in `plg.json` is **meaningless for Go plugins** now (leaving
|
||||
> `plugin.so` there is harmless); it only distinguishes Lua plugins.
|
||||
> - Artifacts no longer need cgo, so cross-compiling requires no target C toolchain.
|
||||
@ -180,12 +185,12 @@ the kernel picks the one matching the current platform and renames it to `plugin
|
||||
|
||||
### Build Targets & Multi-platform Bundle
|
||||
|
||||
**`plugindev build` defaults to bundle mode** (unless `plg.json` explicitly sets `"bundle": false`): it builds linux/amd64 + darwin/amd64 + windows/amd64 in one pass, producing a single `.hmap` with all platform binaries. The output manifest includes a `platforms` field. The kernel auto-selects the correct binary during installation.
|
||||
**`hmapdev build` defaults to bundle mode** (unless `plg.json` explicitly sets `"bundle": false`): it builds linux/amd64 + darwin/amd64 + windows/amd64 in one pass, producing a single `.hmap` with all platform binaries. The output manifest includes a `platforms` field. The kernel auto-selects the correct binary during installation.
|
||||
|
||||
```bash
|
||||
plugindev build # default bundle, outputs dist/myplugin_bundle.hmap
|
||||
plugindev build --bundle # explicitly enable bundle (same as above)
|
||||
plugindev build --no-bundle # disable bundle, build per plg.json targets
|
||||
hmapdev build # default bundle, outputs dist/myplugin_bundle.hmap
|
||||
hmapdev build --bundle # explicitly enable bundle (same as above)
|
||||
hmapdev build --no-bundle # disable bundle, build per plg.json targets
|
||||
```
|
||||
|
||||
Notes:
|
||||
@ -275,7 +280,7 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e
|
||||
|
||||
### Entry Point
|
||||
|
||||
`plugindev init` generates `plugin.go` with the `NewPlugin` export function directly,
|
||||
`hmapdev init` generates `plugin.go` with the `NewPlugin` export function directly,
|
||||
which is the entry point when the kernel loads the plugin:
|
||||
|
||||
```go
|
||||
@ -284,7 +289,7 @@ func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
}
|
||||
```
|
||||
|
||||
At build time, `plugindev build` auto-generates subprocess runtime code
|
||||
At build time, `hmapdev build` auto-generates subprocess runtime code
|
||||
(`z_proc_gen.go` for the platform-independent part, plus `z_proc_shm_unix.go` /
|
||||
`z_proc_shm_windows.go`). All three platforms share the same entry point and the same
|
||||
RPC logic; only the cross-process resource-passing mechanism differs (inherited fds on
|
||||
|
||||
@ -90,8 +90,8 @@ eventLoop() → processTextInput()
|
||||
RelevanceContext — 内存 events[] + JSON持久化
|
||||
Append: 每次输入, CleanText → 三分支向量(textForVector)
|
||||
agent事件→Response, 用户事件→Input, cold_storage→Input+Response
|
||||
StaticEmbedder 预训练词嵌入 / TF-IDF 回退
|
||||
Prune: StaticEmbedder CosineSimilarity, 保留 topK + 最近10条
|
||||
向量层级：统一多模态空间（主，带 fingerprint）→ StaticEmbedder 词嵌入 → TF-IDF（回退）
|
||||
Prune: DenseCosine（仅同指纹才比较）→ 退化 StaticEmbedder CosineSimilarity；保留 topK + 最近10条
|
||||
├── 保留 → timeline → 按时间排序 → system prompt
|
||||
└── 低分 → Document 层归档 (原始时间戳)
|
||||
Save: 5s debounce 写盘
|
||||
@ -99,7 +99,7 @@ eventLoop() → processTextInput()
|
||||
↓ Prune 归档 ↑ LLM 主动召回
|
||||
|
||||
② Document (文件记忆)
|
||||
DocStore — JSON文件 + 与 Context 共享的 StaticEmbedder 向量空间（兜底: TF-IDF InvertedIndex）
|
||||
DocStore — JSON文件 + 稠密向量（统一多模态空间；dense_fp 须与当前空间同指纹，不符即重算；兜底: StaticEmbedder / TF-IDF InvertedIndex）
|
||||
写入: Prune归档 / doc_commit / Graph快照(syncGraphToDocs)
|
||||
读取:
|
||||
├── 自动注入: Query(input, top3) → 同一向量空间下相似度摘要 → 【相关记忆文档】→ system prompt (只读)
|
||||
@ -132,11 +132,20 @@ eventLoop() → processTextInput()
|
||||
→ 三元组 → GraphDB.Commit
|
||||
```
|
||||
|
||||
### 向量化：预训练词嵌入 + TF-IDF 回退
|
||||
### 向量化：统一多模态空间（主）→ 词嵌入 → TF-IDF（回退）
|
||||
|
||||
所有向量化统一使用 `StaticEmbedder`（`internal/memory/static_embedder.go`）：
|
||||
向量化按可用性分三层降级，**每一层缺位都明确报错，不静默假装成功**：
|
||||
|
||||
**主策略 — 预训练词嵌入（词对齐 300 维）**
|
||||
**① 统一多模态空间（主路径，v1.2.0 起）**
|
||||
文本与图像共用**同一模型、同一维度、同一指纹**（默认 `chineseclip`：512 维、Apache-2.0、中文原生；
|
||||
亦可选 `qwen3vl` 或外部 `http` provider）。provider 经 `pkg/embedding` 公共 SPI 注册，
|
||||
**内核不硬编码任何模型**。向量与指纹一起持久化（`dense_fp` / `vec_model`），
|
||||
与当前指纹不一致即触发重算；融合时只接受**同指纹且同维度**的块向量
|
||||
（跨坐标系的向量混进去会算出两边都不像的方向）。
|
||||
|
||||
**② 词嵌入（文本兜底）** — `StaticEmbedder`（`internal/memory/static_embedder.go`）：
|
||||
|
||||
**模型来源**（词对齐 300 维）
|
||||
- 模型来源：ConceptNet Numberbatch（77 语对齐）/ fastText 中文 / fastText 英文
|
||||
- 通过 `core.agent.embedding_model_path` 配置（逗号分隔多模型）
|
||||
- 路径名含 `numberbatch` → 自动下载 ConceptNet，含 `cc.zh.` → fastText 中文，含 `cc.en.` → fastText 英文
|
||||
@ -194,30 +203,31 @@ eventLoop() → processTextInput()
|
||||
要求调用方知道格式，等于让一个拼写错误静默切断引用绑定而全链路无人报错。
|
||||
`memory_commit` 同时新增 `sentence_text`：媒体引用挂在句子上，没有句子就无处可挂。
|
||||
|
||||
### 媒体记忆（v1.1.0 起）
|
||||
### 媒体记忆（v1.2.0 起：一等记忆块）
|
||||
|
||||
`internal/memory/media/` — `Store`，内容寻址（CAS）
|
||||
媒体不是外挂内容，而是**记忆的一等节点**：`internal/memory/media/` 是内容寻址仓储（CAS），
|
||||
图数据库里的 block 节点携带它的 digest 与向量，结构边（如 `sentence --contains--> block`）表达归属。
|
||||
|
||||
| 关注点 | 做法 | 为何 |
|
||||
|---|---|---|
|
||||
| 寻址 | sha256 digest，元数据在 SQLite、blob 在磁盘 | 相同字节只存一份；元数据要可查询，blob 不该进数据库 |
|
||||
| 寻址 | sha256 digest；元数据在 SQLite，blob 在磁盘（`blobs/<前2位>/<其余>` 两级分桶） | 相同字节只存一份；元数据要可查询，blob 不该进数据库 |
|
||||
| 完整性 | 每次 `Get` 重校 digest | 磁盘损坏时静默返回脏数据比报错危险得多 |
|
||||
| 写入原子性 | `.tmp` + rename | 半个文件被当成完整内容会永久污染那个 digest |
|
||||
| 引用 | `owner_kind/owner_id/digest` 三元组主键，`AddRef` 幂等 | 三个 owner 类型：`context`（上下文事件）、`document`（文档）、`graph_sentence`（图谱句子） |
|
||||
| GC | 两阶段 + `minAge`，**有引用者绝不删** | 描述文本留在文本层，blob 可淘汰——语义记忆与字节缓存分离 |
|
||||
| 检索 | 块携带**自己的多模态向量与指纹**，直接参与向量检索 | 不需要描述文本做中介 |
|
||||
| 生命周期 | **无独立 GC、无引用计数、无 keep-set**；删除块即删内容 | 媒体是记忆节点，不是需要保活的缓存 |
|
||||
|
||||
**媒体在纯文本记忆里的表示**是标记 `[<mime> <短digest>] <描述>`：
|
||||
**不再有描述式索引**：旧实现在正文里写 `[<mime> <短digest>] <描述>` 标记，并把描述文本当作语义记忆
|
||||
（检索靠描述）。该机制已在 v1.2.0 整体拆除：描述是模型生成的二手信息，
|
||||
检索“别人转述的图片”不如检索图片自己的向量。现在图片只按自己的统一空间向量被检索，
|
||||
正文里不再有 media marker。
|
||||
|
||||
```
|
||||
[image/png a1b2c3d4e5f6] 一张紫蓝红三色带图
|
||||
```
|
||||
**跨空间向量迁移**：媒体行的向量带 `vec_model`（空间指纹）。启动时
|
||||
`reembedStaleMedia()` 把 `vec_model` 为空（从未嵌入）或与当前空间不一致（换过模型/维度）的行
|
||||
批量重算并**写回库**；模态不在本空间覆盖范围时返回 `ErrModalityUnsupported`，
|
||||
**绝不拿别的模型的向量顶替**。
|
||||
|
||||
之所以必须借文本承载：`Doc.Content`、`sentences.text`、文本记忆的 `Input` 全是字符串，
|
||||
没有字段能挂结构化数据。**描述文本才是持久的语义记忆**（检索靠它），digest 是回到字节的
|
||||
钥匙（反查靠它）。blob 被容量 GC 淘汰后，描述仍留在 L0/L2/L3 的文本里。
|
||||
|
||||
媒体存储**全程可选**：`core.memory.media.enabled=false` 或未配置时，整条链路静默退化为
|
||||
纯文本行为，不报错不 panic。
|
||||
媒体存储全程可选：`core.memory.media.enabled=false` 或未配置时，整条链路静默退化为纯文本行为，
|
||||
不报错不 panic。
|
||||
|
||||
### 其他记忆层
|
||||
|
||||
@ -287,7 +297,7 @@ VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。
|
||||
| 方式 | 注册机制 | 编译 | 用途 |
|
||||
|------|----------|------|------|
|
||||
| 内置插件 | `init()` → `RegisterFactory` | `internal/plugins/` 编译进内核 | webui/cli/timer/mcp 等 |
|
||||
| 外部子进程插件 | 握手 + stdio JSON-RPC 反向注册 | `plugindev build` → `plugin.bin`（普通 Go 二进制） | qq/browser/files 等 |
|
||||
| 外部子进程插件 | 握手 + stdio JSON-RPC 反向注册 | `hmapdev build` → `plugin.bin`（普通 Go 二进制） | qq/browser/files 等 |
|
||||
| Lua 脚本插件 | 执行 `main.lua` 注册工具 | 无需编译，重启/重载生效 | luademo 等 |
|
||||
| SKILL 插件 | 解析 `SKILL.md` | Markdown 定义 | clawhubadapter 兼容加载 |
|
||||
|
||||
@ -306,7 +316,7 @@ Lua 脚本插件加载：`internal/plugin/` → gopher-lua 解释器执行 `main
|
||||
| 维度 | 内置插件 | 外部插件 |
|
||||
|------|----------|----------|
|
||||
| 注册方式 | `init()` 调用 `plugin.RegisterFactory(name, factory)` | 实现 `NewPluginFactory(name, config) (sdk.Plugin, error)` 入口函数 |
|
||||
| 编译方式 | 编译进 `homed` 二进制，无需独立编译 | 通过 `plugindev build` 编译为 `plugin.bin`（普通 Go 二进制，零 cgo），内核 spawn 为子进程 |
|
||||
| 编译方式 | 编译进 `homed` 二进制，无需独立编译 | 通过 `hmapdev build` 编译为 `plugin.bin`（普通 Go 二进制，零 cgo），内核 spawn 为子进程 |
|
||||
| 分发方式 | 随内核分发，不可独立安装/卸载 | `.hmap` 包（ZIP 归档），通过 WebUI 或 pluginmgr API 安装 |
|
||||
| 元数据 | 通过 `plugin.RegisterPluginMeta()` 注册显示名 | `plugin.json` manifest 文件（name, version, entry, platforms, capabilities 等） |
|
||||
| 插件目录 | 无独立目录，编译进二进制 | `plugins/<name>/` 独立目录，包含 `plugin.json` + `plugin.bin` |
|
||||
|
||||
@ -30,75 +30,80 @@ type Plugin interface {
|
||||
|
||||
| 方式 | 适用场景 | 复杂度 |
|
||||
|------|---------|--------|
|
||||
| **子进程插件（推荐）** | 独立分发的第三方插件 | 中等，使用 `plugindev` 工具链生成 |
|
||||
| **子进程插件（推荐）** | 独立分发的第三方插件 | 中等，使用 `hmapdev` 工具链生成 |
|
||||
| **内置插件** | 随 HomeAgent 一起发布 | 简单，需合入主仓库 |
|
||||
| **Lua 脚本插件** | 轻量快速原型 | 简单，使用 `plugindev init --lua` 生成 |
|
||||
| **Lua 脚本插件** | 轻量快速原型 | 简单，使用 `hmapdev init --lua` 生成 |
|
||||
|
||||
---
|
||||
|
||||
<img src="../../assets/branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
|
||||
|
||||
## 一、快速开始：使用 plugindev 工具链
|
||||
## 一、快速开始：使用 hmapdev 工具链
|
||||
|
||||
`plugindev` 是 SDK 仓库提供的统一插件开发工具链，支持 Go 和 Lua 两种插件类型。
|
||||
`hmapdev` 是 SDK 仓库提供的统一插件开发工具链，支持 Go 和 Lua 两种插件类型，
|
||||
最终产出 `.hmap` 插件包（工具名即来自这个包格式）。
|
||||
|
||||
> 改名说明：1.2.0 起工具链由 `plugindev` 更名为 `hmapdev`；SDK 存储目录同时由
|
||||
> `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`（旧目录会自动继续沿用）。
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
cd homeagent-sdk/tools/plugindev
|
||||
go build -o plugindev
|
||||
# 将 plugindev 加入 PATH 或直接使用
|
||||
cd homeagent-sdk/tools/hmapdev
|
||||
go build -o hmapdev
|
||||
# 将 hmapdev 加入 PATH 或直接使用
|
||||
# 也可从 SDK 的 release 附件下载预编译二进制（hmapdev_linux_amd64 等）
|
||||
```
|
||||
|
||||
### SDK 版本管理
|
||||
|
||||
`plugindev sdk` 子命令管理本地 SDK 版本：
|
||||
`hmapdev sdk` 子命令管理本地 SDK 版本：
|
||||
|
||||
```bash
|
||||
plugindev sdk list # 列出已安装的 SDK 版本
|
||||
plugindev sdk current # 显示当前使用的 SDK 版本
|
||||
plugindev sdk latest # 显示最新可用版本
|
||||
plugindev sdk install v0.8.0 # 安装指定版本
|
||||
plugindev sdk use v0.8.0 # 切换使用版本
|
||||
plugindev sdk path # 显示当前 SDK 路径
|
||||
hmapdev sdk list # 列出已安装的 SDK 版本
|
||||
hmapdev sdk current # 显示当前使用的 SDK 版本
|
||||
hmapdev sdk latest # 显示最新可用版本
|
||||
hmapdev sdk install v1.2.0 # 安装指定版本
|
||||
hmapdev sdk use v1.2.0 # 切换使用版本
|
||||
hmapdev sdk path # 显示当前 SDK 路径
|
||||
```
|
||||
|
||||
SDK 存储在 `~/.homeagent/plugindev/sdk/<version>/`，`plugindev init` 自动读取当前 SDK 版本填充 `go.mod`。
|
||||
SDK 存储在 `~/.homeagent/hmapdev/sdk/<version>/`，`hmapdev init` 自动读取当前 SDK 版本填充 `go.mod`。
|
||||
|
||||
### 源码调试
|
||||
|
||||
`plugindev debug` 直接用解释器执行插件源码并输出调用轨迹，无需编译环境：
|
||||
`hmapdev debug` 直接用解释器执行插件源码并输出调用轨迹，无需编译环境：
|
||||
|
||||
```bash
|
||||
plugindev debug [dir] # dir 默认当前目录
|
||||
hmapdev debug [dir] # dir 默认当前目录
|
||||
```
|
||||
|
||||
### 创建 Go 插件
|
||||
|
||||
```bash
|
||||
plugindev init myplugin
|
||||
hmapdev init myplugin
|
||||
cd myplugin
|
||||
# 编辑插件代码
|
||||
vim plugin.go
|
||||
# 编译打包
|
||||
plugindev build # 默认多平台 bundle（见下节）
|
||||
hmapdev build # 默认多平台 bundle（见下节）
|
||||
# 输出: dist/myplugin_bundle.hmap
|
||||
# 单平台构建：
|
||||
plugindev build --no-bundle
|
||||
hmapdev build --no-bundle
|
||||
# 输出: dist/myplugin_linux_amd64.hmap (或 windows_amd64)
|
||||
```
|
||||
|
||||
### 创建 Lua 插件
|
||||
|
||||
```bash
|
||||
plugindev init myluaplugin --lua
|
||||
hmapdev init myluaplugin --lua
|
||||
cd myluaplugin
|
||||
# 编辑插件代码
|
||||
vim main.lua
|
||||
# 本地测试
|
||||
lua main.lua
|
||||
# 编译打包
|
||||
plugindev build
|
||||
hmapdev build
|
||||
# 输出: dist/myluaplugin_lua.hmap
|
||||
```
|
||||
|
||||
@ -129,16 +134,16 @@ myluaplugin/
|
||||
|
||||
### 编译打包
|
||||
|
||||
`plugindev build` 会自动完成编译和打包：
|
||||
`hmapdev build` 会自动完成编译和打包：
|
||||
|
||||
```bash
|
||||
cd myplugin
|
||||
plugindev build # 默认 bundle 模式（多平台合集）
|
||||
plugindev build --no-bundle # 单平台构建（仅当前 plg.json targets）
|
||||
plugindev build --target linux/amd64 # 在 targets 基础上追加一个目标
|
||||
plugindev build --outdir dist # 指定输出目录（默认 dist）
|
||||
plugindev build --sdk-path <path> # 指定 SDK 路径（覆盖 go.mod replace）
|
||||
plugindev build --replace <mod@path> # 追加 go.mod replace 指令（可多次）
|
||||
hmapdev build # 默认 bundle 模式（多平台合集）
|
||||
hmapdev build --no-bundle # 单平台构建（仅当前 plg.json targets）
|
||||
hmapdev build --target linux/amd64 # 在 targets 基础上追加一个目标
|
||||
hmapdev build --outdir dist # 指定输出目录（默认 dist）
|
||||
hmapdev build --sdk-path <path> # 指定 SDK 路径（覆盖 go.mod replace）
|
||||
hmapdev build --replace <mod@path> # 追加 go.mod replace 指令（可多次）
|
||||
```
|
||||
|
||||
执行过程：
|
||||
@ -154,7 +159,7 @@ plugindev build --replace <mod@path> # 追加 go.mod replace 指令（可多次
|
||||
| 文件 | 用途 | 关键字段 |
|
||||
|------|------|---------|
|
||||
| `plg.json` | 项目元信息，由开发者维护 | `targets` — 单平台构建目标（如 `"linux/amd64,windows/amd64"`）；`bundle` — 多平台合集开关（默认 `true`）|
|
||||
| `plugin.json` | 构建产物清单，`plugindev build` 自动生成 | `entry` — 入口文件名；`platforms` — 声明的支持平台 |
|
||||
| `plugin.json` | 构建产物清单，`hmapdev build` 自动生成 | `entry` — 入口文件名；`platforms` — 声明的支持平台 |
|
||||
|
||||
每个目标生成单独的 `.hmap`。子进程插件是普通可执行文件，**不分平台后缀**：
|
||||
|
||||
@ -169,7 +174,7 @@ bundle 包内按 `plugin.bin.<goos>.<goarch>` 区分各平台，安装时内核
|
||||
>
|
||||
> - `plugin.so` / `plugin.dylib` / `plugin.dll` **不再被加载**。新内核遇到旧产物
|
||||
> 会跳过并报可操作错误，不崩溃。
|
||||
> - **业务代码不需要改一行**——公开 SDK 接口零改动，只需用新版 `plugindev` 重编。
|
||||
> - **业务代码不需要改一行**——公开 SDK 接口零改动，只需用新版 `hmapdev`（原 `plugindev`）重编。
|
||||
> - `plg.json` 的 `entry` 字段对 Go 插件**已无意义**（写着 `plugin.so` 也无妨），
|
||||
> 它现在只用于区分 Lua 插件。
|
||||
> - 产物不再需要 cgo，交叉编译无需目标平台 C 工具链。
|
||||
@ -178,12 +183,12 @@ bundle 包内按 `plugin.bin.<goos>.<goarch>` 区分各平台，安装时内核
|
||||
|
||||
### 构建目标与多平台打包（bundle）
|
||||
|
||||
**`plugindev build` 默认就是 bundle 模式**（`plg.json` 未显式写 `"bundle": false` 时）：一次编译 linux/amd64 + darwin/amd64 + windows/amd64，生成包含所有平台二进制的单 `.hmap`，输出清单自动添加 `platforms` 字段。安装时核心自动选择当前平台的二进制，跳过其他平台。
|
||||
**`hmapdev build` 默认就是 bundle 模式**（`plg.json` 未显式写 `"bundle": false` 时）：一次编译 linux/amd64 + darwin/amd64 + windows/amd64，生成包含所有平台二进制的单 `.hmap`，输出清单自动添加 `platforms` 字段。安装时核心自动选择当前平台的二进制，跳过其他平台。
|
||||
|
||||
```bash
|
||||
plugindev build # 默认 bundle，输出 dist/myplugin_bundle.hmap
|
||||
plugindev build --bundle # 显式开启 bundle（同上）
|
||||
plugindev build --no-bundle # 关闭 bundle，按 plg.json 的 targets 逐平台构建
|
||||
hmapdev build # 默认 bundle，输出 dist/myplugin_bundle.hmap
|
||||
hmapdev build --bundle # 显式开启 bundle（同上）
|
||||
hmapdev build --no-bundle # 关闭 bundle，按 plg.json 的 targets 逐平台构建
|
||||
```
|
||||
|
||||
注意：
|
||||
@ -273,7 +278,7 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e
|
||||
|
||||
### 入口点
|
||||
|
||||
`plugindev init` 生成的 `plugin.go` 中直接包含 `NewPlugin` 导出函数，它是内核加载插件时的入口：
|
||||
`hmapdev init` 生成的 `plugin.go` 中直接包含 `NewPlugin` 导出函数，它是内核加载插件时的入口：
|
||||
|
||||
```go
|
||||
func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
@ -281,7 +286,7 @@ func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
}
|
||||
```
|
||||
|
||||
编译时 `plugindev build` 自动生成子进程运行时代码（`z_proc_gen.go` 平台无关 + `z_proc_shm_unix.go` / `z_proc_shm_windows.go` 平台特定），无需手动编写。三平台共享同一入口与同一套 RPC 逻辑，仅跨进程资源传递机制不同（Unix 继承 fd，Windows 命名内核对象）。
|
||||
编译时 `hmapdev build` 自动生成子进程运行时代码（`z_proc_gen.go` 平台无关 + `z_proc_shm_unix.go` / `z_proc_shm_windows.go` 平台特定），无需手动编写。三平台共享同一入口与同一套 RPC 逻辑，仅跨进程资源传递机制不同（Unix 继承 fd，Windows 命名内核对象）。
|
||||
|
||||
### PluginSDK 核心 API
|
||||
|
||||
|
||||
@ -405,13 +405,29 @@ func main() {
|
||||
// 人格设定
|
||||
// ========================================================================
|
||||
|
||||
// 人格来源优先级：personal/personal.md（高级覆盖，存在且非空才生效）
|
||||
// > 配置项 core.agent.personal_prompt（默认模板 = config.DefaultPersonaPrompt）。
|
||||
//
|
||||
// 曾经只有「文件」一个来源且无人维护，导致人格卡写死旧版本号与已删除的 C ABI、
|
||||
// 反过来让实例自称旧版本（v1.2.0 压测发现）。故：
|
||||
// - 配置项化 + 内置默认模板（不含版本号字面量）
|
||||
// - 文件仍在时生效，但扫到腐坏内容就在启动日志里明确告警
|
||||
personalPath := filepath.Join(cfg.Daemon.DataDir, "personal", "personal.md")
|
||||
personality, err := agentPkg.LoadPersonality(personalPath)
|
||||
if err != nil {
|
||||
log.Printf("[homed] warning: load personality: %v", err)
|
||||
}
|
||||
if personality != nil && personality.Content != "" {
|
||||
log.Printf("[homed] personality loaded (%d bytes)", len(personality.Content))
|
||||
log.Printf("[homed] 人格来源=文件 %s（优先于配置项），%d 字节", personalPath, len(personality.Content))
|
||||
if hints := agentPkg.PersonaStaleHints(personality.Content); len(hints) > 0 {
|
||||
log.Printf("[homed] warning: 人格文件含会腐坏的内容 %v — 建议迁到配置项 core.agent.personal_prompt"+
|
||||
"（默认模板不含版本号，被问版本时以运行时快照为准）", hints)
|
||||
}
|
||||
} else if pv := cfgReg.GetString("core.agent.personal_prompt", internalConfig.DefaultPersonaPrompt); strings.TrimSpace(pv) != "" {
|
||||
personality = &agentPkg.Personality{Content: pv, Path: "(core.agent.personal_prompt)"}
|
||||
log.Printf("[homed] 人格来源=配置项 core.agent.personal_prompt，%d 字节", len(pv))
|
||||
} else {
|
||||
log.Printf("[homed] 人格来源=无（配置项为空且无人格文件）")
|
||||
}
|
||||
|
||||
// ========================================================================
|
||||
|
||||
@ -24,7 +24,7 @@ import (
|
||||
// 所以选择：**原生 Windows 不提供 homed**。Windows 用户跑 WSL2——
|
||||
// WSL2 里就是普通 linux/amd64，走与我们测试矩阵完全相同的那条路径。
|
||||
//
|
||||
// 注意范围：只有 homed 如此。plugindev 工具链仍可在 Windows 上运行
|
||||
// 注意范围：只有 homed 如此。hmapdev 工具链仍可在 Windows 上运行
|
||||
// （在 Windows 上开发、为 WSL 构建 linux 插件是合理工作流）。
|
||||
func requireSupportedPlatform() {
|
||||
fmt.Fprintln(os.Stderr, "homed 不支持 Windows 原生运行。")
|
||||
|
||||
@ -130,6 +130,45 @@ main ──────────────── E ────────
|
||||
|
||||
---
|
||||
|
||||
### 7. 开发者文档的发布归属（以 rel 分支的形态为准）
|
||||
|
||||
**规则：面向使用者的开发者文档，先在对应的 `release/vX.Y.x` 上修正成「这一版的实际行为」，
|
||||
再 cherry-pick 合入 `main`。**（文档属 §二.3 所列的发布分支允许事项之一）
|
||||
|
||||
为什么不能直接改 main：
|
||||
|
||||
- `main` 的语义是**下一个未发布版本**（§二.1）。在那儿写的文档要么描述尚未发布的行为，
|
||||
要么与当前 rel 的实际行为**相反**，而文档的读者（包括模型自身）会把它当事实。
|
||||
- `assets/docs/**` 会**随发行包分发并在 WebUI 里被阅读**——它服务的是“这一版”，不是“下一版”。
|
||||
- 版本号、工具名、机制的有无都是**随版变动的**：同一个文件在两个分支上就应该是两种口径。
|
||||
|
||||
做法：
|
||||
|
||||
```bash
|
||||
git switch release/v1.2.x
|
||||
# 按这一版口径修改：版本号、当前工具名（hmapdev）、已移除机制不再写成现行
|
||||
# ... 编辑 assets/docs/**、README{,_EN}.md、docs/zh/** ...
|
||||
git commit -m "docs: 按 v1.2.x 口径修正 …"
|
||||
git switch main && git cherry-pick <sha> # 遵守 §三：只 pick，不 merge
|
||||
```
|
||||
|
||||
`main` 上若需要描述“下一版才有的行为”，必须显式标注（如「（下一版）」或附版本号），
|
||||
不得让读者以为它已发布。
|
||||
|
||||
**反例（本仓真实踩过，均为“文档当成事实后反向误导”）**：
|
||||
|
||||
| 现象 | 后果 |
|
||||
|---|---|
|
||||
| 人格卡写死 `v0.9.0（C ABI v2）` | 内核接口/日志报 1.2.0，agent 却向用户自述旧版本（且该机制 v1.0.0 已删除） |
|
||||
| 架构文档在 1.2.0 后仍把“描述式索引 + 引用计数 GC”写成现行机制 | 读者按已删除的设计理解现行行为 |
|
||||
| README 停在 v1.1.1 并描述已被删除的机制 | 同上 |
|
||||
|
||||
配套硬约束：**任何“模型或用户会当作事实”的文本，都不得写死版本号**——
|
||||
要么用 `meta.Version` 插值，要么要求读运行时快照，并用测试钉住
|
||||
（如 `TestDefaultPersonaPromptHasNoVersionLiterals`）。
|
||||
|
||||
---
|
||||
|
||||
## 三、当前分支对齐（2026-09-12 更新）
|
||||
|
||||
### 主仓（TrueAgent）
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
> 状态：**完成 v3**（2026-09-06）——v2 的迁移已上生产（内核 v1.0.0）；v3 记录 v1.1.1 的公开接口**扩展**。
|
||||
> 目的：钉死「暴露给外部插件的接口不变」这一约束的**合同面**——迁移前、迁移后外部插件看到/调用的 SDK 接口完全一致；
|
||||
> 所有改造落在**核心（homed 侧）+ 工具链（plugindev）**，外部插件业务代码零改动，只需用新 plugindev 重编。
|
||||
> 所有改造落在**核心（homed 侧）+ 工具链（hmapdev，当时名为 plugindev）**，外部插件业务代码零改动，只需用新工具链重编。
|
||||
>
|
||||
> **结果（已验证）**：`git diff third_party/homeagent-sdk/sdk/` 全程为空；17 个 `example/*/plugin.go` 逐字节未改
|
||||
> （`git status example/` 无输出）；生产 17 插件全部经子进程通道运行。
|
||||
@ -11,7 +11,7 @@
|
||||
> 它要保的是「换运行模型不动业务代码」。迁移完成后，SDK 需要能随功能演进而扩展，
|
||||
> 否则多模态这类能力永远到不了插件手上。解除的边界见 §九：**只增不减，签名不改**。
|
||||
>
|
||||
> 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或模板 `tools/plugindev/templates/` 后，
|
||||
> 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或模板 `tools/hmapdev/templates/` 后，
|
||||
> 必须同步更新本矩阵。
|
||||
>
|
||||
> 权威编号：plan.md 第 11 节（11.1~11.9）。本文档只做接口面盘点，不做实现。
|
||||
@ -21,9 +21,9 @@
|
||||
## 一、迁移的形状（一句话）
|
||||
|
||||
```
|
||||
今天： 外部插件 = example/*/plugin.go（纯 Go） ──plugindev c-shared──> plugin.so
|
||||
今天： 外部插件 = example/*/plugin.go（纯 Go） ──hmapdev c-shared──> plugin.so
|
||||
homed ──dlopen──> plugin.so（C ABI bridge：51 个整数 method id）
|
||||
之后： 外部插件 = example/*/plugin.go（纯 Go，一行不改） ──plugindev go build──> plugin.bin
|
||||
之后： 外部插件 = example/*/plugin.go（纯 Go，一行不改） ──hmapdev go build──> plugin.bin
|
||||
homed ──spawn──> plugin.bin（stdio JSON-RPC + shm + eventfd）
|
||||
```
|
||||
|
||||
@ -33,8 +33,8 @@
|
||||
|---|---|---|
|
||||
| 公开 SDK `third_party/homeagent-sdk/sdk/*.go` | ❌ 纯 Go | **不动**（接口面 = 合同） |
|
||||
| 外部插件业务代码 `example/*/plugin.go` | ❌ 纯 Go（只 import 公开 SDK） | **不动**（只重编） |
|
||||
| bridge 模板 `tools/plugindev/templates.go` 的 `tmplLinuxBridge`/`tmplBridge` | ✅ cgo | **删除/替换**为 `tmplProcMain` |
|
||||
| `plugindev` 构建命令 | c-shared | 改普通 `go build` |
|
||||
| bridge 模板 `tools/hmapdev/templates.go` 的 `tmplLinuxBridge`/`tmplBridge` | ✅ cgo | **删除/替换**为 `tmplProcMain` |
|
||||
| `hmapdev` 构建命令 | c-shared | 改普通 `go build` |
|
||||
| homed `internal/plugin/cabi/`（1096 行） | cgo | 删（已归入 plan 迁移收尾 5.2） |
|
||||
| homed `internal/plugin/registry.go` 加载分派 | — | 改：按 `entry` 分派 `.so`/`.bin` |
|
||||
|
||||
@ -300,7 +300,7 @@ C 结构体不好传函数指针（那是运气，任何人给 dispatch 加个 c
|
||||
|
||||
## 七、接口冻结检查点（全部已通过）
|
||||
|
||||
1. ✅ **阶段 2（子进程通道原型）**：`plugindev` 重编 weather → `plugin.bin` → 端到端跑通。
|
||||
1. ✅ **阶段 2（子进程通道原型）**：`hmapdev` 重编 weather → `plugin.bin` → 端到端跑通。
|
||||
验收：weather 业务代码逐字节未改（`git status example/` 无输出）。
|
||||
2. ✅ **阶段 3（共享内存）**：子进程并发改写 StageContext 丢失率 = 0%
|
||||
（`TestPlugin_FiveProcessesConcurrentAppendNoLostUpdate` 与
|
||||
@ -349,7 +349,7 @@ tool output_send__qq result: 已通过 [qq] 通道发送: map[status:sent]
|
||||
|
||||
### 3. 生成模板必须同步接线，否则是**全体外部插件编译失败**
|
||||
|
||||
公开接口加方法时，`tools/plugindev/templates/proc_main.go.tmpl` 里的 `procIO` /
|
||||
公开接口加方法时，`tools/hmapdev/templates/proc_main.go.tmpl` 里的 `procIO` /
|
||||
`procDocMemory` 若不实现新方法，就不满足接口——**每个外部插件都编不过**，是硬失败
|
||||
不是软降级。v1.1.1 这一层是被 `go test` 抓出来的（`internal/plugin/proc` 的两个
|
||||
E2E 用例编译失败），不是靠人工检查发现的。
|
||||
@ -366,7 +366,7 @@ E2E 用例编译失败），不是靠人工检查发现的。
|
||||
|---|---|---|
|
||||
| 存量插件源码零改动 | `cd example/<n> && go vet ./...`（17 个） | ✅ 17/17 通过 |
|
||||
| 旧产物仍能建链 | 用 SDK 0.9.2 编的 `plugin.bin` 跑 `TestRealPlugin_*` | ✅ 4/4 通过（握手校验 `ProtocolVersion=1`，不是 SDK 版本） |
|
||||
| 模板已接线 | `cd tools/plugindev && go test ./...` | ✅ `TestProcTemplate_CoversAllCoreMethods` 含新 method |
|
||||
| 模板已接线 | `cd tools/hmapdev && go test ./...` | ✅ `TestProcTemplate_CoversAllCoreMethods` 含新 method |
|
||||
| 并发安全 | `go test ./sdk/ -race -count=5` | ✅ 零 DATA RACE（13 例压测） |
|
||||
|
||||
### v1.2.x 的接口扩展（2026-09-12）
|
||||
@ -426,5 +426,5 @@ data URL 本身已是 base64 文本，包进二进制传输省不了空间，还
|
||||
- `internal/plugin/proc/protocol.go` — 合同面 B 的代码实现（`Method*` 常量，取代已删的 bridge 模板）
|
||||
- `internal/plugin/proc/shm.go` — 合同面 C 的代码实现（共享段布局与 18 字段枚举）
|
||||
- `internal/plugin/proc/capability.go` — 权限梯度（capability 组 + `withheldCapabilities`）
|
||||
- `third_party/homeagent-sdk/tools/plugindev/templates/` — 子进程运行时模板（三文件）
|
||||
- `third_party/homeagent-sdk/tools/hmapdev/templates/` — 子进程运行时模板（三文件）
|
||||
- `docs/zh/experiments/plugin-arch/` — 18 项可行性实验 + `19-migration-verify/` 迁移执行期工具
|
||||
@ -4,6 +4,8 @@ import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type Personality struct {
|
||||
@ -39,3 +41,25 @@ func (p *Personality) InjectPrompt() string {
|
||||
}
|
||||
return fmt.Sprintf("【人格设定】\n%s\n", p.Content)
|
||||
}
|
||||
|
||||
// 会随时间腐坏的人格内容特征。现场：人格卡写死 v0.9.0 与早已删除的 C ABI v2，
|
||||
// 实例被问版本时自述错误（v1.2.0 压测发现）。
|
||||
var (
|
||||
personaVersionRe = regexp.MustCompile(`\bv?\d+\.\d+\.\d+\b`)
|
||||
personaStalePhrases = []string{"C ABI v2", "plugin.so", "c-shared", "描述式索引", "引用计数式"}
|
||||
)
|
||||
|
||||
// PersonaStaleHints 返回人格文本里会腐坏的内容（空 = 干净）。
|
||||
// 供启动时告警：引导改用配置项 core.agent.personal_prompt（默认模板不含这些）。
|
||||
func PersonaStaleHints(content string) []string {
|
||||
var out []string
|
||||
if m := personaVersionRe.FindAllString(content, -1); len(m) > 0 {
|
||||
out = append(out, fmt.Sprintf("版本号字面量 %v（版本应来自运行时快照）", m))
|
||||
}
|
||||
for _, p := range personaStalePhrases {
|
||||
if strings.Contains(content, p) {
|
||||
out = append(out, "可能已过期的说法: "+p)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
62
internal/agent/personal_test.go
Normal file
62
internal/agent/personal_test.go
Normal file
@ -0,0 +1,62 @@
|
||||
package agent
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// PersonaStaleHints 必须能认出会腐坏的人格内容——版本号字面量与已删除机制。
|
||||
func TestPersonaStaleHints(t *testing.T) {
|
||||
// 现场真实文本（线上人格卡的原文）
|
||||
stale := "你是 HomeAgent（内核代号 HΔ-Kernel，当前版本 v0.9.0）。\n当前运行的二进制是 v0.9.0（C ABI v2，构建于 2026-08-15）。"
|
||||
hints := PersonaStaleHints(stale)
|
||||
if len(hints) == 0 {
|
||||
t.Fatal("未识别出写死版本号与 C ABI 的人格文本")
|
||||
}
|
||||
joined := strings.Join(hints, " | ")
|
||||
if !strings.Contains(joined, "版本号字面量") {
|
||||
t.Fatalf("应报出版本号字面量，实际: %s", joined)
|
||||
}
|
||||
if !strings.Contains(joined, "C ABI v2") {
|
||||
t.Fatalf("应报出已删除机制的残留说法，实际: %s", joined)
|
||||
}
|
||||
|
||||
// 干净文本（配置项默认模板）不应误报
|
||||
if h := PersonaStaleHints(DefaultPersonaProbeClean()); len(h) != 0 {
|
||||
t.Fatalf("干净人格被误报: %v", h)
|
||||
}
|
||||
}
|
||||
|
||||
// DefaultPersonaProbeClean 由 config 包的默认模板等价物构成——
|
||||
// 这里不复用 config 包以避免 import cycle，只断言「不含版本号与旧机制」的文本不被误报。
|
||||
func DefaultPersonaProbeClean() string {
|
||||
return "你是 HomeAgent（内核代号 HΔ-Kernel）。外部插件是独立子进程，经 stdio JSON-RPC 通信；" +
|
||||
"被问到版本时以运行时快照为准。"
|
||||
}
|
||||
|
||||
func TestLoadAndSavePersonality(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "personal", "personal.md")
|
||||
|
||||
// 文件不存在时返回空（不报错、不创建）
|
||||
p, err := LoadPersonality(path)
|
||||
if err != nil || p == nil || p.Content != "" {
|
||||
t.Fatalf("缺文件时应返回空人格，实际 %+v err=%v", p, err)
|
||||
}
|
||||
|
||||
if err := SavePersonality(path, "人格内容"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := os.Stat(path); err != nil {
|
||||
t.Fatalf("SavePersonality 未落盘: %v", err)
|
||||
}
|
||||
p, err = LoadPersonality(path)
|
||||
if err != nil || p.Content != "人格内容" {
|
||||
t.Fatalf("读回失败: %+v err=%v", p, err)
|
||||
}
|
||||
if got := p.InjectPrompt(); !strings.Contains(got, "【人格设定】") || !strings.Contains(got, "人格内容") {
|
||||
t.Fatalf("InjectPrompt 形状不对: %q", got)
|
||||
}
|
||||
}
|
||||
48
internal/config/persona_test.go
Normal file
48
internal/config/persona_test.go
Normal file
@ -0,0 +1,48 @@
|
||||
package config
|
||||
|
||||
import (
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// 人格模板的契约：**不得写死版本号**。
|
||||
//
|
||||
// 来历：线上人格卡（personal/personal.md）曾写死「当前版本 v0.9.0（C ABI v2）」，
|
||||
// 而 C ABI 早在 v1.0.0 就被删除。结果是内核自身日志/接口都报 1.2.0，
|
||||
// agent 被问版本时却按人格卡自述旧版本（v1.2.0 压测发现）。
|
||||
// 版本应来自运行时快照，不来自任何会被发版落下的文本。
|
||||
func TestDefaultPersonaPromptHasNoVersionLiterals(t *testing.T) {
|
||||
re := regexp.MustCompile(`\bv?\d+\.\d+\.\d+\b`)
|
||||
if m := re.FindAllString(DefaultPersonaPrompt, -1); len(m) > 0 {
|
||||
t.Fatalf("默认人格模板含版本号字面量 %v —— 发版后必然腐坏，"+
|
||||
"被问版本时应要求 agent 读运行时快照", m)
|
||||
}
|
||||
if !strings.Contains(DefaultPersonaPrompt, "运行时快照") {
|
||||
t.Fatal("默认人格模板必须显式要求「版本以运行时快照为准」，否则模型会凭记忆编造版本")
|
||||
}
|
||||
}
|
||||
|
||||
// 人格配置项必须注册、默认值就是 DefaultPersonaPrompt（单一事实源），
|
||||
// 且全新安装时会被播种进 DB。
|
||||
func TestPersonaPromptRegisteredWithDefault(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
r := NewConfigRegistry(filepath.Join(dir, "config.db"))
|
||||
r.SeedDefaults(dir)
|
||||
defer r.Close()
|
||||
|
||||
def := r.GetDef("core.agent.personal_prompt")
|
||||
if def == nil {
|
||||
t.Fatal("core.agent.personal_prompt 未注册")
|
||||
}
|
||||
if def.Default != DefaultPersonaPrompt {
|
||||
t.Fatalf("默认值与 DefaultPersonaPrompt 不一致：%q", def.Default)
|
||||
}
|
||||
if def.Type != "text" {
|
||||
t.Fatalf("人格设定应为多行文本类型，实际 %q", def.Type)
|
||||
}
|
||||
if got := r.GetString("core.agent.personal_prompt", ""); got != DefaultPersonaPrompt {
|
||||
t.Fatalf("播种未写入默认人格（长度 %d）", len(got))
|
||||
}
|
||||
}
|
||||
@ -472,6 +472,36 @@ var defaultSources = map[string]map[string]string{
|
||||
"deepseek": {"base_url": "https://api.deepseek.com", "model": "deepseek-v4-flash", "api_key": "", "thinking_enabled": "false", "adapter": "deepseek", "adapter_path": "adapters/deepseek.lua"},
|
||||
}
|
||||
|
||||
// DefaultPersonaPrompt 是「人格设定」的默认模板，作为配置项 core.agent.personal_prompt 的默认值。
|
||||
//
|
||||
// 契约（由 TestDefaultPersonaPromptHasNoVersionLiterals 钉住）：
|
||||
// - **不得含版本号字面量**。写死的版本会随发版腐坏，反过来让实例自称旧版本
|
||||
// （现场：人格卡写死 v0.9.0 与早已删除的 C ABI，实例被问版本时自述错误）。
|
||||
// 被问到版本/构建信息时，要求 agent 读运行时快照。
|
||||
// - 不得把已删除的机制当作现行机制描述。
|
||||
const DefaultPersonaPrompt = `你是 HomeAgent（内核代号 HΔ-Kernel）——一个完全独立自研的新一代 Agent 框架。
|
||||
你以内核 + 插件架构驱动，实现了稳定高效、记忆不衰减的长时持续运行。
|
||||
内核（homed 守护进程）只负责 LLM 编排、记忆管理与知识检索，全部 IO 能力由插件承载。
|
||||
外部插件是独立子进程，经 stdio JSON-RPC（控制面）+ 共享内存段（数据面）+ 事件环（通知面）通信；
|
||||
旧式 C ABI 动态库产物早已不再加载。
|
||||
**不要凭记忆断言版本号或构建日期**：被问到时以运行时快照（healthcheck_kernel 的内核版本字段）为准。
|
||||
|
||||
## 对用户的称呼
|
||||
|
||||
你对用户的称呼永远是“老大”，绝对禁止使用“老板”“主人”称呼用户，不论任何情况。
|
||||
|
||||
## 对话风格
|
||||
|
||||
- 用语气词（哈、嘛、呢、～、😊、🔥 等），不要太端着
|
||||
- 重要的事先说结论，再展开解释
|
||||
- 回复要简洁自然
|
||||
|
||||
## 能力边界
|
||||
|
||||
- 你通过插件编排所有 IO：QQ/微信消息、WebUI、终端、文件、网络
|
||||
- 输出不会自动路由到对话通道：QQ/微信等异步通道必须调用输出门工具（output_send__qq 等）才能真正送达
|
||||
- 你的三层记忆（Context → Document → Graph）持续蒸馏归档，超长运行时记忆不衰减`
|
||||
|
||||
func (r *ConfigRegistry) SeedDefaults(dataDir string) {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
@ -523,6 +553,10 @@ func (r *ConfigRegistry) seedDBValues(dataDir string) {
|
||||
|
||||
set := func(k, v string) { stmt.Exec(k, v) }
|
||||
|
||||
// 人格设定：与其它默认值同批播种（老安装不会被注入——那是刻意的）。
|
||||
// 存量安装里若还有人 personality 文件，它优先于本项（见 cmd/homed/main.go）。
|
||||
set("core.agent.personal_prompt", DefaultPersonaPrompt)
|
||||
|
||||
set("webui.listen_addr", ":8080")
|
||||
set("core.daemon.data_dir", dataDir)
|
||||
set("core.daemon.heartbeat_interval", "15s")
|
||||
@ -633,6 +667,13 @@ WebUI 概览页展示你的立绘，可通过 /mascot.webp 直接访问。如输
|
||||
func (r *ConfigRegistry) seedCoreDefs(dataDir string) {
|
||||
reg := func(d ConfigDef) { r.defs[d.Key] = &d }
|
||||
|
||||
// 人格设定（人格卡的配置项化）：默认模板见 DefaultPersonaPrompt。
|
||||
// 高级用户仍可用 <dataDir>/personal/personal.md 覆盖它。
|
||||
reg(ConfigDef{Key: "core.agent.personal_prompt", Default: DefaultPersonaPrompt, Type: "text", DisplayName: "人格设定",
|
||||
Description: "人格设定块（作为【人格设定】拼在系统提示词之前）。留空则该块不注入。" +
|
||||
"默认模板不含版本号：被问到版本/构建信息时，应读运行时快照而非凭记忆断言。" +
|
||||
"<dataDir>/personal/personal.md 存在且非空时优先于本项。", Category: "agent"})
|
||||
|
||||
reg(ConfigDef{Key: "webui.listen_addr", Default: ":8080", Type: "string", DisplayName: "监听地址", Description: "WebUI HTTP 监听地址", Category: "webui"})
|
||||
reg(ConfigDef{Key: "core.daemon.data_dir", Default: dataDir, Type: "string", DisplayName: "数据目录", Description: "数据存储根目录", Category: "daemon"})
|
||||
reg(ConfigDef{Key: "core.daemon.heartbeat_interval", Default: "15s", Type: "duration", DisplayName: "心跳间隔", Description: "Agent 心跳检查间隔", Category: "daemon"})
|
||||
|
||||
@ -9,7 +9,7 @@ var (
|
||||
//
|
||||
// 1.0.0：外部插件从 C ABI 动态库迁到子进程 + 共享内存。
|
||||
// 这是首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件必须
|
||||
// 用新版 plugindev 重编），故跃到主版本号。
|
||||
// 用新版 hmapdev 重编），故跃到主版本号。
|
||||
// 1.1.0：记忆系统支持二进制多媒体节点——CAS 媒体存储 + L0/L2/L3 贯通。
|
||||
// 1.1.1：多模态贯通**插件边界**。内核实现公开 SDK 1.1.0 新增的媒体接口
|
||||
// （doc.insertWithMedia、io.injectMedia / injectMediaSync /
|
||||
|
||||
@ -17,7 +17,7 @@ const (
|
||||
//
|
||||
// 保留这张表只为**给出明确错误**：插件目录里躺着 plugin.so 而内核不再认它时，
|
||||
// 静默跳过会让「目录在但插件没加载」看起来像配置问题，而实际原因是需要用
|
||||
// 新版 plugindev 重编。
|
||||
// 新版 hmapdev 重编。
|
||||
var legacyCABIEntries = []string{"plugin.so", "plugin.dll", "plugin.dylib"}
|
||||
|
||||
// entryKind 描述插件入口归属的加载通道。
|
||||
|
||||
@ -115,7 +115,7 @@ func TestHasLegacyCABIEntry(t *testing.T) {
|
||||
})
|
||||
}
|
||||
|
||||
// 旧 .so 插件必须报「用新 plugindev 重编」而非静默跳过。
|
||||
// 旧 .so 插件必须报「用新 hmapdev 重编」而非静默跳过。
|
||||
func TestTryDynamic_LegacyCABIGivesActionableError(t *testing.T) {
|
||||
r := NewRegistry()
|
||||
defer r.closeProcHost()
|
||||
@ -129,7 +129,7 @@ func TestTryDynamic_LegacyCABIGivesActionableError(t *testing.T) {
|
||||
}
|
||||
// 错误消息须指向解决办法，且明确业务代码无需改
|
||||
msg := err.Error()
|
||||
for _, want := range []string{"plugindev", "plugin.bin", "业务代码"} {
|
||||
for _, want := range []string{"hmapdev", "plugin.bin", "业务代码"} {
|
||||
if !strings.Contains(msg, want) {
|
||||
t.Errorf("错误消息应含 %q，实际: %v", want, err)
|
||||
}
|
||||
|
||||
@ -10,11 +10,11 @@ import (
|
||||
pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
// 端到端：用**真实 plugindev 模板**编译的插件，经内核 proc 通道加载运行。
|
||||
// 端到端：用**真实 hmapdev 模板**编译的插件，经内核 proc 通道加载运行。
|
||||
//
|
||||
// 与 plugin_test.go 中 testdata/*.go 假插件的区别：
|
||||
// 那些是手写的最简 RPC 实现，只验证内核侧逻辑；
|
||||
// 这里用的是 tools/plugindev/templates/proc_main.go.tmpl —— 外部插件作者
|
||||
// 这里用的是 tools/hmapdev/templates/proc_main.go.tmpl —— 外部插件作者
|
||||
// 真正会拿到的那份运行时。它验证的是「模板 ↔ 内核」两侧协议/布局真的对齐，
|
||||
// 而不只是内核自己跟自己对齐。
|
||||
//
|
||||
@ -101,9 +101,9 @@ func (p *e2ePlugin) Start(s *sdk.PluginSDK) error {
|
||||
func (p *e2ePlugin) Stop() error { return nil }
|
||||
`
|
||||
|
||||
// procRuntimeTemplates 列出 plugindev 会生成到插件目录的运行时文件。
|
||||
// procRuntimeTemplates 列出 hmapdev 会生成到插件目录的运行时文件。
|
||||
//
|
||||
// 必须与 SDK 仓 tools/plugindev/proc_runtime.go 的 procRuntimeFiles 一致：
|
||||
// 必须与 SDK 仓 tools/hmapdev/proc_runtime.go 的 procRuntimeFiles 一致：
|
||||
// 共享段与事件通知的传递机制按平台不同（Unix 继承 fd，Windows 命名
|
||||
// 内核对象），故拆成带 build tag 的文件；只写主模板会编译失败。
|
||||
var procRuntimeTemplates = []struct {
|
||||
@ -115,15 +115,21 @@ var procRuntimeTemplates = []struct {
|
||||
{"proc_shm_windows.go.tmpl", "z_proc_shm_windows.go"},
|
||||
}
|
||||
|
||||
// buildPluginWithRealTemplate 用 plugindev 的真实模板编译一个插件二进制。
|
||||
// buildPluginWithRealTemplate 用 hmapdev 的真实模板编译一个插件二进制。
|
||||
func buildPluginWithRealTemplate(t *testing.T, businessCode string) string {
|
||||
t.Helper()
|
||||
if _, err := exec.LookPath("go"); err != nil {
|
||||
t.Skip("环境无 go 工具链，跳过端到端测试")
|
||||
}
|
||||
|
||||
// 工具链在 SDK 1.2.0 起改名 hmapdev（原 plugindev）。两个目录都接受：
|
||||
// 旧检出（软链或旧版 SDK 仓）仍能跑本测试，新检出走新路径。
|
||||
tmplDir := filepath.Join("..", "..", "..",
|
||||
"third_party", "homeagent-sdk", "tools", "plugindev", "templates")
|
||||
"third_party", "homeagent-sdk", "tools", "hmapdev", "templates")
|
||||
if _, err := os.Stat(tmplDir); err != nil {
|
||||
tmplDir = filepath.Join("..", "..", "..",
|
||||
"third_party", "homeagent-sdk", "tools", "plugindev", "templates")
|
||||
}
|
||||
|
||||
dir := t.TempDir()
|
||||
mustWriteFile(t, filepath.Join(dir, "plugin.go"), businessCode)
|
||||
@ -131,7 +137,7 @@ func buildPluginWithRealTemplate(t *testing.T, businessCode string) string {
|
||||
for _, rt := range procRuntimeTemplates {
|
||||
data, err := os.ReadFile(filepath.Join(tmplDir, rt.tmpl))
|
||||
if err != nil {
|
||||
t.Skipf("plugindev 模板 %s 不可读（SDK 仓可能未就位）: %v", rt.tmpl, err)
|
||||
t.Skipf("hmapdev 模板 %s 不可读（SDK 仓可能未就位）: %v", rt.tmpl, err)
|
||||
}
|
||||
mustWriteFile(t, filepath.Join(dir, rt.out), string(data))
|
||||
}
|
||||
|
||||
@ -260,7 +260,7 @@ func (p *Process) handshake(timeout time.Duration) error {
|
||||
return fmt.Errorf("proc: %s 握手应答解析失败: %w", p.name, err)
|
||||
}
|
||||
if res.Protocol != ProtocolVersion {
|
||||
return fmt.Errorf("proc: %s 协议版本不匹配（插件 %d，内核 %d）——请用配套 plugindev 重编",
|
||||
return fmt.Errorf("proc: %s 协议版本不匹配（插件 %d，内核 %d）——请用配套 hmapdev 重编",
|
||||
p.name, res.Protocol, ProtocolVersion)
|
||||
}
|
||||
log.Printf("[proc] %s 已建链（pid=%d protocol=%d sdk=%s）",
|
||||
|
||||
@ -331,7 +331,7 @@ func TestProcess_ProtocolMismatchRejected(t *testing.T) {
|
||||
}
|
||||
// 运维可读性：光报“不匹配”不能定位到行动。生产上碰到它的现场是
|
||||
// “只更新了内核没重编插件”，所以错误里必须带出这条修复指令。
|
||||
if !strings.Contains(err.Error(), "plugindev") || !strings.Contains(err.Error(), "重编") {
|
||||
if !strings.Contains(err.Error(), "hmapdev") || !strings.Contains(err.Error(), "重编") {
|
||||
t.Errorf("错误应给出重编插件的修复指令，实际: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
@ -143,7 +143,7 @@ func AttachSegment(data []byte) (*Segment, error) {
|
||||
return nil, fmt.Errorf("proc: 共享段魔数不匹配（0x%x，期望 0x%x）", got, shmMagic)
|
||||
}
|
||||
if got := binary.LittleEndian.Uint32(data[offVersion:]); got != shmVersion {
|
||||
return nil, fmt.Errorf("proc: 共享段版本不匹配（%d，本内核 %d）——插件需用配套 plugindev 重编",
|
||||
return nil, fmt.Errorf("proc: 共享段版本不匹配（%d，本内核 %d）——插件需用配套 hmapdev 重编",
|
||||
got, shmVersion)
|
||||
}
|
||||
return &Segment{data: data}, nil
|
||||
|
||||
2
internal/plugin/proc/testdata/stageplugin.go
vendored
2
internal/plugin/proc/testdata/stageplugin.go
vendored
@ -4,7 +4,7 @@
|
||||
// stage 处理经共享内存读改写（模拟 sanitizer 的清洗行为）。
|
||||
//
|
||||
// 它手写 RPC 与共享段访问，不依赖公开 SDK——因为 SDK 侧的 proc 支持
|
||||
// 属于 Part 3（plugindev 工具链）的内容。这里只验证内核侧机制。
|
||||
// 属于 Part 3（hmapdev 工具链）的内容。这里只验证内核侧机制。
|
||||
package main
|
||||
|
||||
import (
|
||||
|
||||
@ -1175,11 +1175,11 @@ func (r *Registry) tryDynamic(plgDir, name string, config map[string]interface{}
|
||||
|
||||
// 旧 .so/.dll 插件给明确错误，不静默跳过。
|
||||
// 静默跳过会让「插件目录在但没加载」看起来像配置问题，
|
||||
// 而实际原因是需要用新 plugindev 重编。
|
||||
// 而实际原因是需要用新 hmapdev 重编。
|
||||
if hasLegacyCABIEntry(plgDir) {
|
||||
return nil, fmt.Errorf(
|
||||
"plugin %s: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。"+
|
||||
"外部插件已改为子进程模式，请用新版 plugindev 重编产出 %s"+
|
||||
"外部插件已改为子进程模式，请用新版 hmapdev 重编产出 %s"+
|
||||
"（业务代码无需修改）", name, binEntry)
|
||||
}
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ import (
|
||||
// 这里用 **example/ 里真实的 17 个插件产物**，验证「业务代码零改动 + 重编即可」
|
||||
// 这一迁移承诺在完整内核装配下成立。
|
||||
//
|
||||
// 前置：插件需已用新版 plugindev 重编（scripts/rebuild-plugins.sh）。
|
||||
// 前置：插件需已用新版 hmapdev 重编（scripts/rebuild-plugins.sh）。
|
||||
// 未重编时测试 skip 而非 fail——CI 上不强制要求先跑重编脚本。
|
||||
|
||||
// realPluginDir 返回某个 example 插件的 linux 产物路径。
|
||||
|
||||
@ -1124,6 +1124,33 @@
|
||||
justify-content: flex-end;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
/* 首启人格向导（复用 confirm-* 弹窗）*/
|
||||
.persona-ta {
|
||||
width: 100%;
|
||||
display: none;
|
||||
margin-bottom: 12px;
|
||||
font: 12px/1.5 var(--font-mono, monospace);
|
||||
padding: 8px;
|
||||
border-radius: var(--radius-md, 8px);
|
||||
border: 1px solid var(--glass-border);
|
||||
background: var(--glass-bg);
|
||||
color: var(--text-primary);
|
||||
box-sizing: border-box;
|
||||
}
|
||||
.persona-warn {
|
||||
display: none;
|
||||
font-size: 12px;
|
||||
line-height: 1.5;
|
||||
color: var(--text-secondary);
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
.persona-actions {
|
||||
display: flex;
|
||||
justify-content: flex-end;
|
||||
gap: 8px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
.empty-state {
|
||||
text-align: center;
|
||||
padding: 48px 24px;
|
||||
@ -2521,8 +2548,87 @@
|
||||
if (card) card.style.transform = "";
|
||||
});
|
||||
|
||||
// ===== API =====
|
||||
async function api(p, o) {
|
||||
// ===== 首启人格向导 =====
|
||||
// 人格是配置项（core.agent.personal_prompt，默认模板不含任何版本号）。
|
||||
// 首次启动问一次「默认 / 自定义 / 稍后」，之后不再打扰；
|
||||
// 不回答 = 稍后 = 保留默认人格，绝不阻塞启动。
|
||||
async function maybeShowPersonaWizard() {
|
||||
var st;
|
||||
try {
|
||||
st = await api("/persona");
|
||||
} catch (e) {
|
||||
return; // 拿不到状态就不打扰用户
|
||||
}
|
||||
if (!st || st.initialized) return;
|
||||
var ov = document.createElement("div");
|
||||
ov.className = "confirm-overlay";
|
||||
ov.style.display = "flex";
|
||||
ov.innerHTML =
|
||||
'<div class="confirm-box">' +
|
||||
"<h3>" + escHtml(__("人格设定", "Persona")) + "</h3>" +
|
||||
"<p>" + escHtml(__(
|
||||
"首次启动：选一下助手的人格。选「使用默认」即可（之后可在设置里修改）；自定义内容在下次重启后生效。",
|
||||
"First run: pick your assistant's persona. \"Use default\" is fine (change it later in Settings); custom content takes effect after the next restart."
|
||||
)) + "</p>" +
|
||||
'<div class="persona-warn"></div>' +
|
||||
'<textarea class="persona-ta" rows="6"></textarea>' +
|
||||
'<div class="persona-actions">' +
|
||||
'<button class="btn btn-ghost btn-sm" data-mode="later">' + escHtml(__("稍后再说", "Later")) + "</button>" +
|
||||
'<button class="btn btn-ghost btn-sm" data-mode="custom">' + escHtml(__("自定义…", "Custom…")) + "</button>" +
|
||||
'<button class="btn btn-sm" data-mode="default">' + escHtml(__("使用默认", "Use default")) + "</button>" +
|
||||
"</div></div>";
|
||||
document.body.appendChild(ov);
|
||||
var ta = ov.querySelector(".persona-ta");
|
||||
var warn = ov.querySelector(".persona-warn");
|
||||
var customOpen = false;
|
||||
if (st.file_override) {
|
||||
warn.style.display = "block";
|
||||
warn.textContent = __(
|
||||
"注意：检测到 personal/personal.md，它优先于这里的设置。",
|
||||
"Note: personal/personal.md exists and takes precedence over this choice."
|
||||
);
|
||||
}
|
||||
function close() {
|
||||
ov.remove();
|
||||
}
|
||||
async function submit(mode, content) {
|
||||
try {
|
||||
var r = await api("/persona", {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ mode: mode, content: content || "" }),
|
||||
});
|
||||
if (r && r.restart_required) toast(__("已保存，重启后生效", "Saved; takes effect after restart"));
|
||||
else toast(__("已保存", "Saved"));
|
||||
} catch (e) {
|
||||
toast(__("保存失败：", "Save failed: ") + e, true);
|
||||
}
|
||||
close();
|
||||
}
|
||||
ov.querySelectorAll("button[data-mode]").forEach(function (b) {
|
||||
b.onclick = function () {
|
||||
var mode = b.getAttribute("data-mode");
|
||||
if (mode !== "custom") {
|
||||
submit(mode);
|
||||
return;
|
||||
}
|
||||
if (!customOpen) { // 第一次点：展开文本域并预填当前人格
|
||||
customOpen = true;
|
||||
ta.style.display = "block";
|
||||
ta.value = st.current_prompt || "";
|
||||
ta.focus();
|
||||
return;
|
||||
}
|
||||
if (!ta.value.trim()) {
|
||||
toast(__("内容不能为空", "Content cannot be empty"), true);
|
||||
return;
|
||||
}
|
||||
submit("custom", ta.value);
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
// ===== API =====
|
||||
async function api(p, o) {
|
||||
var opts = {
|
||||
credentials: "include",
|
||||
headers: { "Content-Type": "application/json", ...o?.headers },
|
||||
@ -6516,6 +6622,7 @@
|
||||
renderAll();
|
||||
connectSSE();
|
||||
startUptimeTicker();
|
||||
maybeShowPersonaWizard();
|
||||
})();
|
||||
setInterval(renderAll, 15000);
|
||||
// 消息同步轮询兜底：每30秒增量同步 chatHistory，补偿 SSE 断连窗口期
|
||||
|
||||
@ -23,6 +23,7 @@ import (
|
||||
"time"
|
||||
|
||||
agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
|
||||
internalConfig "gitcode.com/JianFeeeee/HomeAgent/internal/config"
|
||||
"gitcode.com/JianFeeeee/HomeAgent/internal/meta"
|
||||
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
|
||||
@ -865,6 +866,7 @@ func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
|
||||
mux.HandleFunc("/api/v1/terminals", h.requireAPI(h.handleTerminals))
|
||||
mux.HandleFunc("/api/v1/cmd/history", h.requireAPI(h.handleCmdHistory))
|
||||
mux.HandleFunc("/api/v1/kernel", h.requireAPI(h.handleKernel))
|
||||
mux.HandleFunc("/api/v1/persona", h.requireAPI(h.handlePersona))
|
||||
mux.HandleFunc("/api/v1/plugins", h.requireAPI(h.handlePlugins))
|
||||
mux.HandleFunc("/api/v1/plugins/", h.requireAPI(h.handlePluginByID))
|
||||
// 设备网关（可配置反代到 remotedevice；默认禁用，未启用时返回 404）
|
||||
@ -974,6 +976,111 @@ func (h *Handler) handleKernel(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(w, http.StatusOK, h.status.GetKernelStatus())
|
||||
}
|
||||
|
||||
// 人格设定：配置项键，以及「首启向导已经问过」的一次性标记。
|
||||
//
|
||||
// 为什么需要向导：人格曾经只有 <dataDir>/personal/personal.md 一个来源且无人维护，
|
||||
// 里面写死的旧版本号反过来让实例自述旧版本（v1.2.0 压测发现）。
|
||||
// 现在人格是配置项（默认模板不含任何版本号），首启问一次，之后不再打扰。
|
||||
const (
|
||||
personaPromptKey = "core.agent.personal_prompt"
|
||||
personaInitMarker = "core.internal.persona_initialized"
|
||||
)
|
||||
|
||||
// handlePersona 是首启人格向导的后端。
|
||||
//
|
||||
// GET → {initialized, current_prompt, file_override}
|
||||
// POST → {"mode":"default"|"custom"|"later","content":"..."}
|
||||
// 写入 core.agent.personal_prompt 并打一次性标记，返回 restart_required
|
||||
//
|
||||
// 生效时机：人格在 homed 启动时载入（以【人格设定】块拼进系统提示词），
|
||||
// 所以**自定义内容需重启生效**；选「默认」或「稍后」（保持当前默认）无需重启。
|
||||
// 不回答就是「稍后」：保留默认并打标记，不阻塞任何流程。
|
||||
func (h *Handler) handlePersona(w http.ResponseWriter, r *http.Request) {
|
||||
if h.settings == nil {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "settings not available"})
|
||||
return
|
||||
}
|
||||
switch r.Method {
|
||||
case http.MethodGet:
|
||||
initialized := false
|
||||
if v, err := h.settings.GetCore(personaInitMarker); err == nil {
|
||||
if s, ok := v.(string); ok && strings.TrimSpace(s) != "" {
|
||||
initialized = true
|
||||
}
|
||||
}
|
||||
cur := ""
|
||||
if v, err := h.settings.GetCore(personaPromptKey); err == nil {
|
||||
if s, ok := v.(string); ok {
|
||||
cur = s
|
||||
}
|
||||
}
|
||||
if cur == "" {
|
||||
cur = internalConfig.DefaultPersonaPrompt
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]interface{}{
|
||||
"initialized": initialized,
|
||||
"current_prompt": cur,
|
||||
"file_override": h.personaFileExists(),
|
||||
})
|
||||
case http.MethodPost:
|
||||
var req struct {
|
||||
Mode string `json:"mode"`
|
||||
Content string `json:"content"`
|
||||
}
|
||||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request"})
|
||||
return
|
||||
}
|
||||
restart := false
|
||||
switch req.Mode {
|
||||
case "default":
|
||||
if err := h.settings.SetCore(personaPromptKey, internalConfig.DefaultPersonaPrompt); err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
case "custom":
|
||||
if strings.TrimSpace(req.Content) == "" {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "content required for custom mode"})
|
||||
return
|
||||
}
|
||||
if err := h.settings.SetCore(personaPromptKey, req.Content); err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
restart = true // 人格在启动时载入
|
||||
case "later":
|
||||
// 保持当前（默认）人格，只打标记，不再问
|
||||
default:
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "unknown mode"})
|
||||
return
|
||||
}
|
||||
if err := h.settings.SetCore(personaInitMarker, "1"); err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]interface{}{
|
||||
"status": "ok", "mode": req.Mode, "restart_required": restart,
|
||||
})
|
||||
default:
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
}
|
||||
}
|
||||
|
||||
// personaFileExists 报告是否存在会覆盖配置项的人格文件（存在时它优先）。
|
||||
// 数据目录取自 core.daemon.data_dir（由播种写入）。
|
||||
func (h *Handler) personaFileExists() bool {
|
||||
v, err := h.settings.GetCore("core.daemon.data_dir")
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
dir, _ := v.(string)
|
||||
if dir == "" {
|
||||
return false
|
||||
}
|
||||
_, err = os.Stat(filepath.Join(dir, "personal", "personal.md"))
|
||||
return err == nil
|
||||
}
|
||||
|
||||
func (h *Handler) handleAgents(w http.ResponseWriter, r *http.Request) {
|
||||
switch r.Method {
|
||||
case http.MethodGet:
|
||||
|
||||
145
internal/plugins/webui/handler_persona_test.go
Normal file
145
internal/plugins/webui/handler_persona_test.go
Normal file
@ -0,0 +1,145 @@
|
||||
package webui
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
internalConfig "gitcode.com/JianFeeeee/HomeAgent/internal/config"
|
||||
"gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
)
|
||||
|
||||
func newPersonaHandler(t *testing.T) (*Handler, *internalConfig.ConfigRegistry) {
|
||||
t.Helper()
|
||||
dir := t.TempDir()
|
||||
cfgReg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
|
||||
cfgReg.SeedDefaults(dir)
|
||||
t.Cleanup(func() { cfgReg.Close() })
|
||||
h := NewHandler(testSDK(sdk.SDKConfig{Settings: sdk.NewSettings("webui", cfgReg)}))
|
||||
return h, cfgReg
|
||||
}
|
||||
|
||||
func doPersona(t *testing.T, h *Handler, method, body string) *httptest.ResponseRecorder {
|
||||
t.Helper()
|
||||
var rd *strings.Reader
|
||||
if body == "" {
|
||||
rd = strings.NewReader("")
|
||||
} else {
|
||||
rd = strings.NewReader(body)
|
||||
}
|
||||
req := httptest.NewRequest(method, "/api/v1/persona", rd)
|
||||
w := httptest.NewRecorder()
|
||||
h.handlePersona(w, req)
|
||||
return w
|
||||
}
|
||||
|
||||
// 首启向导的后端契约：GET 报告状态、POST 三选一、并且**只问一次**。
|
||||
func TestPersonaWizardFlow(t *testing.T) {
|
||||
h, cfgReg := newPersonaHandler(t)
|
||||
|
||||
// 1. 全新安装：未初始化，current_prompt 回落到内置默认模板
|
||||
w := doPersona(t, h, http.MethodGet, "")
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("GET 状态码 %d", w.Code)
|
||||
}
|
||||
var got struct {
|
||||
Initialized bool `json:"initialized"`
|
||||
CurrentPrompt string `json:"current_prompt"`
|
||||
FileOverride bool `json:"file_override"`
|
||||
}
|
||||
if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got.Initialized {
|
||||
t.Fatal("全新安装不应已初始化")
|
||||
}
|
||||
if got.CurrentPrompt != internalConfig.DefaultPersonaPrompt {
|
||||
t.Fatal("未设置时应回落到内置默认模板")
|
||||
}
|
||||
if got.FileOverride {
|
||||
t.Fatal("没有人格文件时不应报告 file_override")
|
||||
}
|
||||
|
||||
// 2. 「稍后再说」= 保留默认、打标记、不再问
|
||||
w = doPersona(t, h, http.MethodPost, `{"mode":"later"}`)
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("later 状态码 %d: %s", w.Code, w.Body.String())
|
||||
}
|
||||
if v := cfgReg.GetString(personaInitMarker, ""); v == "" {
|
||||
t.Fatal("later 也必须打一次性标记（否则每次启动都问）")
|
||||
}
|
||||
if v := cfgReg.GetString(personaPromptKey, ""); v != internalConfig.DefaultPersonaPrompt {
|
||||
t.Fatalf("later 不应改动人格，实际 %q", v)
|
||||
}
|
||||
|
||||
// 3. 已初始化后 GET 应报 true
|
||||
w = doPersona(t, h, http.MethodGet, "")
|
||||
got.Initialized = false
|
||||
_ = json.Unmarshal(w.Body.Bytes(), &got)
|
||||
if !got.Initialized {
|
||||
t.Fatal("打过标记后应报告已初始化")
|
||||
}
|
||||
|
||||
// 4. 自定义：写入内容 + 需要重启（人格在启动时载入）
|
||||
h2, cfgReg2 := newPersonaHandler(t)
|
||||
w = doPersona(t, h2, http.MethodPost, `{"mode":"custom","content":"你是测试人格"}`)
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("custom 状态码 %d: %s", w.Code, w.Body.String())
|
||||
}
|
||||
var pr struct {
|
||||
RestartRequired bool `json:"restart_required"`
|
||||
}
|
||||
_ = json.Unmarshal(w.Body.Bytes(), &pr)
|
||||
if !pr.RestartRequired {
|
||||
t.Fatal("自定义人格应提示需要重启才生效")
|
||||
}
|
||||
if v := cfgReg2.GetString(personaPromptKey, ""); v != "你是测试人格" {
|
||||
t.Fatalf("自定义内容未写库: %q", v)
|
||||
}
|
||||
|
||||
// 5. 空内容的 custom 必须被拒（否则等于静默清空人格）
|
||||
h3, _ := newPersonaHandler(t)
|
||||
if w = doPersona(t, h3, http.MethodPost, `{"mode":"custom","content":" "}`); w.Code != http.StatusBadRequest {
|
||||
t.Fatalf("空内容应 400，实际 %d", w.Code)
|
||||
}
|
||||
// 6. 未知 mode 必须被拒
|
||||
if w = doPersona(t, h3, http.MethodPost, `{"mode":"nope"}`); w.Code != http.StatusBadRequest {
|
||||
t.Fatalf("未知 mode 应 400，实际 %d", w.Code)
|
||||
}
|
||||
// 7. 被拒的请求不得打标记（否则向导会被跳过）
|
||||
if v := cfgReg2.GetString(personaInitMarker, ""); v == "" {
|
||||
t.Fatal("前置条件：第 4 步已打标记")
|
||||
}
|
||||
h4, cfgReg4 := newPersonaHandler(t)
|
||||
_ = doPersona(t, h4, http.MethodPost, `{"mode":"nope"}`)
|
||||
if v := cfgReg4.GetString(personaInitMarker, ""); v != "" {
|
||||
t.Fatal("被拒的请求不应打标记")
|
||||
}
|
||||
}
|
||||
|
||||
// 存在人格文件时 GET 要报告 file_override（它会覆盖配置项，向导应提示用户）。
|
||||
func TestPersonaWizardReportsFileOverride(t *testing.T) {
|
||||
h, cfgReg := newPersonaHandler(t)
|
||||
dir := cfgReg.GetString("core.daemon.data_dir", "")
|
||||
if dir == "" {
|
||||
t.Fatal("播种应写入 core.daemon.data_dir")
|
||||
}
|
||||
if err := os.MkdirAll(filepath.Join(dir, "personal"), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(dir, "personal", "personal.md"), []byte("旧人格"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
w := doPersona(t, h, http.MethodGet, "")
|
||||
var got struct {
|
||||
FileOverride bool `json:"file_override"`
|
||||
}
|
||||
_ = json.Unmarshal(w.Body.Bytes(), &got)
|
||||
if !got.FileOverride {
|
||||
t.Fatal("存在 personal.md 时必须报告 file_override")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user