mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-30 14:23:00 +00:00
bd73a9b241
本次一并提交工作区此前累积的改动（均已验证），并接入工具并发调度所需的 声明项。 把「谁来反代谁」从内核硬编码变成插件可声明。设备网关（remotedevice） 这类**编译进内核、没有独立插件目录与 plugin.json** 的服务，静态扫描扫不到， 此前只能靠约定。新增 DeclareProxy 让它们能自己声明反代路由。 ParallelSafe 的**反向**声明项。判据优先级：Serial 胜出，显式声明不允许被 ParallelSafe 或任何默认值覆盖。 为什么需要它：ParallelSafe 零值 false 已表达「安全/串行」，插件无法区分 「我没想过」和「我确认过必须串行」。没有这个区分，工具作者只能靠命名约定 传递意图，那不是契约。 ParallelSafe 本身也补齐了注释，明确其零值语义（默认串行、保守）与理由 （新语义下并发会改变工具的行为前提，让存量插件意外并发比慢一点危险得多）。 配套 ScenePolicy 声明项的使用说明。 remotedevice/ 整目录（C 实现的设备网关，已由 Go 侧 DeclareProxy 路径取代）。 - sdk/knowledge.go：随场面策略配套调整 - docs/api/*、docs/assets/api-index.json、docs/llms.txt、mkdocs.yml： 由 tools/apidoc/build.sh 从源码重新生成（行号随 plugin.go 变动漂移）
384 lines
8.7 KiB
Markdown
384 lines
8.7 KiB
Markdown
<!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
|
||
|
||
# 记忆（Memory）
|
||
|
||
三层记忆的读写接口：**图记忆**（三元组关系）、**文档记忆**（带元数据的文档）、**文本记忆**（事件流水）。以及知识库。
|
||
|
||
## `DocMemoryAPI`
|
||
|
||
DocMemoryAPI provides access to the document vector store.
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`Insert`](#docmemoryapiinsert) | |
|
||
| [`InsertWithMedia`](#docmemoryapiinsertwithmedia) | InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 |
|
||
| [`Query`](#docmemoryapiquery) | |
|
||
| [`Remove`](#docmemoryapiremove) | |
|
||
| [`Stats`](#docmemoryapistats) | |
|
||
|
||
### `DocMemoryAPI.Insert`
|
||
|
||
```go
|
||
Insert(doc *Doc) error
|
||
```
|
||
|
||
<small>`memory.go:76`</small>
|
||
|
||
### `DocMemoryAPI.InsertWithMedia`
|
||
|
||
```go
|
||
InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
|
||
```
|
||
|
||
InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
|
||
内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。
|
||
媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量，
|
||
因此图片按自己的向量被召回，不依赖任何生成的描述文本。
|
||
|
||
<small>`memory.go:81`</small>
|
||
|
||
### `DocMemoryAPI.Query`
|
||
|
||
```go
|
||
Query(text string, topK int) []*Doc
|
||
```
|
||
|
||
<small>`memory.go:75`</small>
|
||
|
||
### `DocMemoryAPI.Remove`
|
||
|
||
```go
|
||
Remove(id string)
|
||
```
|
||
|
||
<small>`memory.go:82`</small>
|
||
|
||
### `DocMemoryAPI.Stats`
|
||
|
||
```go
|
||
Stats() map[string]interface{}
|
||
```
|
||
|
||
<small>`memory.go:83`</small>
|
||
|
||
## `KnowledgeAPI`
|
||
|
||
KnowledgeAPI provides access to the knowledge store.
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`Add`](#knowledgeapiadd) | |
|
||
| [`List`](#knowledgeapilist) | |
|
||
| [`Search`](#knowledgeapisearch) | |
|
||
|
||
### `KnowledgeAPI.Add`
|
||
|
||
```go
|
||
Add(name, content string) error
|
||
```
|
||
|
||
<small>`knowledge.go:6`</small>
|
||
|
||
### `KnowledgeAPI.List`
|
||
|
||
```go
|
||
List() ([]string, error)
|
||
```
|
||
|
||
<small>`knowledge.go:7`</small>
|
||
|
||
### `KnowledgeAPI.Search`
|
||
|
||
```go
|
||
Search(query string, topK int) ([]*Knowledge, error)
|
||
```
|
||
|
||
<small>`knowledge.go:5`</small>
|
||
|
||
## `MemoryAPI`
|
||
|
||
MemoryAPI provides access to the graph memory (entity-relation store).
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`Commit`](#memoryapicommit) | |
|
||
| [`Introspect`](#memoryapiintrospect) | |
|
||
| [`MergeEntities`](#memoryapimergeentities) | |
|
||
| [`Purge`](#memoryapipurge) | |
|
||
| [`Recall`](#memoryapirecall) | |
|
||
|
||
### `MemoryAPI.Commit`
|
||
|
||
```go
|
||
Commit(triples []Triple) error
|
||
```
|
||
|
||
<small>`memory.go:6`</small>
|
||
|
||
### `MemoryAPI.Introspect`
|
||
|
||
```go
|
||
Introspect() (map[string]interface{}, error)
|
||
```
|
||
|
||
<small>`memory.go:7`</small>
|
||
|
||
### `MemoryAPI.MergeEntities`
|
||
|
||
```go
|
||
MergeEntities(source, target string) (int, error)
|
||
```
|
||
|
||
<small>`memory.go:8`</small>
|
||
|
||
### `MemoryAPI.Purge`
|
||
|
||
```go
|
||
Purge(criteria map[string]string, mode string) (int, error)
|
||
```
|
||
|
||
<small>`memory.go:9`</small>
|
||
|
||
### `MemoryAPI.Recall`
|
||
|
||
```go
|
||
Recall(query []string, depth int) ([]Entity, []Relation, error)
|
||
```
|
||
|
||
<small>`memory.go:5`</small>
|
||
|
||
## `SocialAPI`
|
||
|
||
SocialAPI provides read-only access to the social graph (person profiles and relationships).
|
||
External plugins can query person traits and social networks but cannot modify them.
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`GetNetwork`](#socialapigetnetwork) | |
|
||
| [`GetPerson`](#socialapigetperson) | |
|
||
| [`GetRelations`](#socialapigetrelations) | |
|
||
| [`GetTrait`](#socialapigettrait) | |
|
||
| [`ListPersons`](#socialapilistpersons) | |
|
||
|
||
### `SocialAPI.GetNetwork`
|
||
|
||
```go
|
||
GetNetwork(name string, depth int) ([]*PersonProfile, error)
|
||
```
|
||
|
||
<small>`memory.go:104`</small>
|
||
|
||
### `SocialAPI.GetPerson`
|
||
|
||
```go
|
||
GetPerson(name string) (*PersonProfile, error)
|
||
```
|
||
|
||
<small>`memory.go:101`</small>
|
||
|
||
### `SocialAPI.GetRelations`
|
||
|
||
```go
|
||
GetRelations(name string) ([]SocialRelation, error)
|
||
```
|
||
|
||
<small>`memory.go:103`</small>
|
||
|
||
### `SocialAPI.GetTrait`
|
||
|
||
```go
|
||
GetTrait(name, trait string) (string, bool)
|
||
```
|
||
|
||
<small>`memory.go:102`</small>
|
||
|
||
### `SocialAPI.ListPersons`
|
||
|
||
```go
|
||
ListPersons() ([]string, error)
|
||
```
|
||
|
||
<small>`memory.go:105`</small>
|
||
|
||
## `TextMemoryAPI`
|
||
|
||
TextMemoryAPI provides access to chronological text event storage.
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`Append`](#textmemoryapiappend) | |
|
||
|
||
### `TextMemoryAPI.Append`
|
||
|
||
```go
|
||
Append(evt TextEvent) error
|
||
```
|
||
|
||
<small>`memory.go:44`</small>
|
||
|
||
### `Doc`
|
||
|
||
```go
|
||
type Doc struct { ID string `json:"id"` Title string `json:"title"` Content string `json:"content"` Score …
|
||
```
|
||
|
||
Doc represents a document in the document store.
|
||
|
||
MediaDigests / Attachments 在 Query 返回时由内核填充（仅元数据，不带字节）。
|
||
|
||
<small>`memory.go:89`</small>
|
||
|
||
### `PluginSDK.DocMemory`
|
||
|
||
```go
|
||
func (s *PluginSDK) DocMemory() DocMemoryAPI
|
||
```
|
||
|
||
DocMemory returns the document memory API (may be nil if not available).
|
||
|
||
<small>`plugin.go:522`</small>
|
||
|
||
### `Entity`
|
||
|
||
```go
|
||
type Entity struct { Name string `json:"name"` Type string `json:"type"` MentionCount int `json:"mention_count"` }
|
||
```
|
||
|
||
Entity represents a named entity in the knowledge graph.
|
||
|
||
<small>`memory.go:13`</small>
|
||
|
||
### `Knowledge`
|
||
|
||
```go
|
||
type Knowledge struct { Name string `json:"name"` // Category 是该条目的父分类路径（如 "tech/go"），根下条目为空。 // // 为何加这个字段：对<EFBC9A><E5AFB9> …
|
||
```
|
||
|
||
Knowledge represents a knowledge entry.
|
||
|
||
**示例插件里的真实用法**
|
||
|
||
| 插件 | 位置 | 代码 |
|
||
|---|---|---|
|
||
| [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
|
||
|
||
<small>`knowledge.go:11`</small>
|
||
|
||
### `PluginSDK.Knowledge`
|
||
|
||
```go
|
||
func (s *PluginSDK) Knowledge() KnowledgeAPI
|
||
```
|
||
|
||
Knowledge returns the knowledge store API (may be nil if not available).
|
||
|
||
**示例插件里的真实用法**
|
||
|
||
| 插件 | 位置 | 代码 |
|
||
|---|---|---|
|
||
| [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
|
||
|
||
<small>`plugin.go:529`</small>
|
||
|
||
### `MediaAttachment`
|
||
|
||
```go
|
||
type MediaAttachment struct { Digest string `json:"digest,omitempty"` MIME string `json:"mime,omitempty"` Data []byte `json:"data,omitempty"` Name string `json:"name,omite …
|
||
```
|
||
|
||
TextEvent represents a single text memory event.
|
||
MediaAttachment 描述一份与记忆关联的媒体。
|
||
|
||
两个方向共用一个类型：
|
||
- 写入（InsertWithMedia）：给 Data + MIME 就是新内容；只给 Digest 则是引用已有内容。
|
||
- 读出（Query）：内核只填 Digest/MIME，**不回 Data**——
|
||
一次检索可能命中几十张图，把字节全塞回插件会把 ABI 消息撑爆。
|
||
需要字节时拿 Digest 单独取。
|
||
|
||
刻意没有 Description 字段：媒体不作为文本被索引，也不带任何生成的描述。
|
||
它只按自己的原生向量被检索与召回；附加文字请写在文档 / 三元组的文本里。
|
||
|
||
<small>`memory.go:58`</small>
|
||
|
||
### `PluginSDK.Memory`
|
||
|
||
```go
|
||
func (s *PluginSDK) Memory() MemoryAPI
|
||
```
|
||
|
||
Memory returns the graph memory API (may be nil if not available).
|
||
|
||
<small>`plugin.go:508`</small>
|
||
|
||
### `PersonProfile`
|
||
|
||
```go
|
||
type PersonProfile struct { Name string `json:"name"` Traits map[string]string `json:"traits,omitempty"` Relations []SocialRelation `json:"relations,omitemp …
|
||
```
|
||
|
||
PersonProfile represents a person's complete profile (traits + social relations).
|
||
|
||
<small>`memory.go:109`</small>
|
||
|
||
### `Relation`
|
||
|
||
```go
|
||
type Relation struct { SourceName string `json:"source_name"` TargetName string `json:"target_name"` RelationType string `json:"relation_type"` Confidence float6 …
|
||
```
|
||
|
||
Relation represents a relationship between two entities.
|
||
|
||
<small>`memory.go:20`</small>
|
||
|
||
### `PluginSDK.Social`
|
||
|
||
```go
|
||
func (s *PluginSDK) Social() SocialAPI
|
||
```
|
||
|
||
Social returns the social graph API (may be nil if not available).
|
||
|
||
<small>`plugin.go:543`</small>
|
||
|
||
### `SocialRelation`
|
||
|
||
```go
|
||
type SocialRelation struct { Person string `json:"person"` Relation string `json:"relation"` }
|
||
```
|
||
|
||
SocialRelation represents a social relationship between two persons.
|
||
|
||
<small>`memory.go:116`</small>
|
||
|
||
### `TextEvent`
|
||
|
||
```go
|
||
type TextEvent struct { Role string `json:"role"` Content string `json:"content"` Timestamp int64 `json:"timestamp"` Channel …
|
||
```
|
||
|
||
<small>`memory.go:65`</small>
|
||
|
||
### `PluginSDK.TextMemory`
|
||
|
||
```go
|
||
func (s *PluginSDK) TextMemory() TextMemoryAPI
|
||
```
|
||
|
||
TextMemory returns the text memory API (may be nil if not available).
|
||
|
||
<small>`plugin.go:515`</small>
|
||
|
||
### `Triple`
|
||
|
||
```go
|
||
type Triple struct { Subject string `json:"subject"` Relation string `json:"relation"` Object string `json:"object"` Confidence float64 `json:"c …
|
||
```
|
||
|
||
Triple represents a subject-relation-object triple for the knowledge graph.
|
||
|
||
SentenceText 是这条三元组的原句，会写进 sentences 表；媒体引用挂在句子上，
|
||
所以 MediaDigests 非空时内核会保证句子存在（不给就自动合成一句）。
|
||
|
||
<small>`memory.go:31`</small>
|
||
|