jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-29 22:05:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
bd73a9b2419fa04cf851166c10627bc415e04893
homeagent-sdk/docs/api/memory.md
JianFeeeee bd73a9b241 feat(sdk): 通用反代声明项（DeclareProxy）+ ToolDef.Serial 串行标记 + 场面策略文档 
本次一并提交工作区此前累积的改动（均已验证），并接入工具并发调度所需的
声明项。

把「谁来反代谁」从内核硬编码变成插件可声明。设备网关（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 变动漂移）
2026-09-27 16:17:04 +08:00

8.7 KiB
Raw Blame History

记忆（Memory）

三层记忆的读写接口：图记忆（三元组关系）、文档记忆（带元数据的文档）、文本记忆（事件流水）。以及知识库。

DocMemoryAPI

DocMemoryAPI provides access to the document vector store.

方法 说明
Insert
InsertWithMedia InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
Query
Remove
Stats

DocMemoryAPI.Insert

Insert(doc *Doc) error

memory.go:76

DocMemoryAPI.InsertWithMedia

InsertWithMedia(doc *Doc, attachments []MediaAttachment) error

InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量， 因此图片按自己的向量被召回，不依赖任何生成的描述文本。

memory.go:81

DocMemoryAPI.Query

Query(text string, topK int) []*Doc

memory.go:75

DocMemoryAPI.Remove

Remove(id string)

memory.go:82

DocMemoryAPI.Stats

Stats() map[string]interface{}

memory.go:83

KnowledgeAPI

KnowledgeAPI provides access to the knowledge store.

方法 说明
Add
List
Search

KnowledgeAPI.Add

Add(name, content string) error

knowledge.go:6

KnowledgeAPI.List

List() ([]string, error)

knowledge.go:7

KnowledgeAPI.Search

Search(query string, topK int) ([]*Knowledge, error)

knowledge.go:5

MemoryAPI

MemoryAPI provides access to the graph memory (entity-relation store).

方法 说明
Commit
Introspect
MergeEntities
Purge
Recall

MemoryAPI.Commit

Commit(triples []Triple) error

memory.go:6

MemoryAPI.Introspect

Introspect() (map[string]interface{}, error)

memory.go:7

MemoryAPI.MergeEntities

MergeEntities(source, target string) (int, error)

memory.go:8

MemoryAPI.Purge

Purge(criteria map[string]string, mode string) (int, error)

memory.go:9

MemoryAPI.Recall

Recall(query []string, depth int) ([]Entity, []Relation, error)

memory.go:5

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
GetPerson
GetRelations
GetTrait
ListPersons

SocialAPI.GetNetwork

GetNetwork(name string, depth int) ([]*PersonProfile, error)

memory.go:104

SocialAPI.GetPerson

GetPerson(name string) (*PersonProfile, error)

memory.go:101

SocialAPI.GetRelations

GetRelations(name string) ([]SocialRelation, error)

memory.go:103

SocialAPI.GetTrait

GetTrait(name, trait string) (string, bool)

memory.go:102

SocialAPI.ListPersons

ListPersons() ([]string, error)

memory.go:105

TextMemoryAPI

TextMemoryAPI provides access to chronological text event storage.

方法 说明
Append

TextMemoryAPI.Append

Append(evt TextEvent) error

memory.go:44

Doc

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 返回时由内核填充（仅元数据，不带字节）。

memory.go:89

PluginSDK.DocMemory

func (s *PluginSDK) DocMemory() DocMemoryAPI

DocMemory returns the document memory API (may be nil if not available).

plugin.go:522

Entity

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.

memory.go:13

Knowledge

type Knowledge struct { Name string `json:"name"` // Category 是该条目的父分类路径（如 "tech/go"），根下条目为空。 // // 为何加这个字段：对<EFBC9A><E5AFB9> …

Knowledge represents a knowledge entry.

示例插件里的真实用法

插件 位置 代码
recoverydiag example/recoverydiag/plugin.go:978 if p.sdk != nil && p.sdk.Knowledge() != nil {

knowledge.go:11

PluginSDK.Knowledge

func (s *PluginSDK) Knowledge() KnowledgeAPI

Knowledge returns the knowledge store API (may be nil if not available).

示例插件里的真实用法

插件 位置 代码
recoverydiag example/recoverydiag/plugin.go:978 if p.sdk != nil && p.sdk.Knowledge() != nil {

plugin.go:529

MediaAttachment

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 字段：媒体不作为文本被索引，也不带任何生成的描述。 它只按自己的原生向量被检索与召回；附加文字请写在文档 / 三元组的文本里。

memory.go:58

PluginSDK.Memory

func (s *PluginSDK) Memory() MemoryAPI

Memory returns the graph memory API (may be nil if not available).

plugin.go:508

PersonProfile

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).

memory.go:109

Relation

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.

memory.go:20

PluginSDK.Social

func (s *PluginSDK) Social() SocialAPI

Social returns the social graph API (may be nil if not available).

plugin.go:543

SocialRelation

type SocialRelation struct { Person string `json:"person"` Relation string `json:"relation"` }

SocialRelation represents a social relationship between two persons.

memory.go:116

TextEvent

type TextEvent struct { Role string `json:"role"` Content string `json:"content"` Timestamp int64 `json:"timestamp"` Channel …

memory.go:65

PluginSDK.TextMemory

func (s *PluginSDK) TextMemory() TextMemoryAPI

TextMemory returns the text memory API (may be nil if not available).

plugin.go:515

Triple

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 非空时内核会保证句子存在（不给就自动合成一句）。

memory.go:31