weichen
1ee32822c3
Why: EXT-9 is the other step-4 hard prerequisite; the surface (Options.DisableUploadIndexing passthrough, Host.KnowledgePublish idempotent replace, Host.KnowledgeDelete prefix-enforced revoke, SurfaceVersion 2.2.0-experimental) must land with the acceptance reds pinned before implementation. Evidence: app red = publish not implemented; server red = switch-on still indexes (hits=1); rows recorded on the task card. Impact: pkg/extension additive surface (surface.txt updated); internal Options passthrough; Server.DisableUploadIndexing field; host method stubs. Behavior unchanged. Refs: EXT-9 proposal; task card.
70 lines
3.4 KiB
Go
70 lines
3.4 KiB
Go
package extension
|
||
|
||
import (
|
||
"context"
|
||
|
||
core "agent-system-core"
|
||
)
|
||
|
||
// Request 是进程内命令处理器收到的一次分发请求（cmdbus.Request 的子集）。
|
||
type Request struct {
|
||
ID string
|
||
Params map[string]any
|
||
Entrance string // button | card | slash | chat | api（归一）
|
||
Actor string
|
||
Owner string
|
||
ConversationID string
|
||
}
|
||
|
||
// Handler 是下游注册的进程内命令处理器：每次分发由基座构造 owner 作用域的
|
||
// Host 句柄传入，处理器经句柄访问基座能力，不得自行越权持有 owner 凭证。
|
||
type Handler func(ctx context.Context, h Host, req Request) (any, error)
|
||
|
||
// Host 是基座在分发时构造的 owner 作用域宿主句柄（EXT-1 最小集 + EXT-5 解析）。
|
||
// 所有能力的可见范围都以本次分发的 Owner 为准；artifacts 只读
|
||
// （写入属完整集，另行评估）。实现由基座 internal 提供。
|
||
type Host interface {
|
||
// PluginID 返回注册处理器的插件标识（形如 rdm）。
|
||
PluginID() string
|
||
// Owner 返回本次分发的作用域 owner。
|
||
Owner() string
|
||
|
||
// KVPut/KVGet 插件 KV（按 pluginID+owner 隔离）。
|
||
KVPut(key, value string) error
|
||
KVGet(key string) (value string, ok bool, err error)
|
||
|
||
// Audit 写一条 owner 名下的审计事件。
|
||
Audit(action, target, evidence string) error
|
||
|
||
// Complete 经基座 LLM 路由补全（owner 的模型配置生效）。
|
||
Complete(ctx context.Context, prompt string) (string, error)
|
||
|
||
// KnowledgePublish 幂等发布（EXT-9）：按 docs 的 ref 整批替换——先清该 owner
|
||
// 下相同 ref 的旧行与旧向量，再走 KnowledgeWrite 语义（Owner/Source 强制同彼）。
|
||
// 重试产生相同结果；embed=true 时重建向量。
|
||
KnowledgePublish(ctx context.Context, docs []core.KnowledgeDoc, embed bool) error
|
||
// KnowledgeDelete 撤销本插件来源的知识索引（EXT-9）：sourcePrefix 必须是
|
||
// "plugin:<本插件ID>"——manual 或他人来源拒绝；删除行与向量，幂等（无匹配不报错）。
|
||
KnowledgeDelete(ctx context.Context, sourcePrefix string) error
|
||
|
||
// KnowledgeSearch 混合检索（owner 可见范围）。
|
||
KnowledgeSearch(ctx context.Context, projectID core.ID, text string, topK int) ([]core.RetrievalHit, error)
|
||
// KnowledgeWrite 写知识分块；embed=true 时同步建向量（失败降级纯全文）。
|
||
// docs 各项的 Owner 由基座强制改写为本次 owner；Source 为空补 "plugin:<PluginID>"。
|
||
KnowledgeWrite(ctx context.Context, docs []core.KnowledgeDoc, embed bool) error
|
||
|
||
// TaskCreate/TaskUpdate 后台任务台账（进度/状态记账，执行体由下游自跑）。
|
||
TaskCreate(kind, title, conversationID string) (taskID string, err error)
|
||
TaskUpdate(taskID, status string, progress int, errText string) error
|
||
|
||
// ArtifactGet/ArtifactContent 工件只读（R1-3 ingest 读原件）。
|
||
ArtifactGet(artifactID string) (core.Artifact, error)
|
||
ArtifactContent(artifactID string) ([]byte, error)
|
||
|
||
// ParseDocument 用基座内置解析器把文档字节解析为 ParsedDocument（EXT-5）。
|
||
// 纯计算，不读写 owner 数据——要解析工件原件先经 ArtifactContent 取字节，
|
||
// owner 作用域由它保证。按扩展名分派；不可解析返回带 Warnings 的文档
|
||
//（显式失败），只有 ctx 取消与输入超过 100MiB 两种情况返回 error。
|
||
ParseDocument(ctx context.Context, filename, mime string, content []byte) (core.ParsedDocument, error)
|
||
}
|