Define the core contracts: domain model
Details (original message): Define the core contracts: domain model, stream events, HITL, profiles, tools, plugins, UI vocabulary, ingest IR, retrieval and memory; golden-sample conformance tests; TS mirror.
This commit is contained in:
weichen
@@ -1,5 +1,25 @@
|
||||
# Agent-System-Core
|
||||
|
||||
系统核心契约仓：领域模型、流式事件协议、HITL 卡片协议、插件 API、设置与 UI 扩展词汇、文档解析/检索/记忆契约。Go 模块路径 agent-system-core；同时发布 JSON Schema 与 TS 类型。不含实现。
|
||||
系统核心契约：领域模型（Project/Conversation/Message/Run/Artifact/Plan）、流式事件信封、
|
||||
HITL 卡片协议、插件 API 与 manifest、AgentProfile 画像、设置 schema、UI 扩展词汇、
|
||||
文档解析（ParsedDocument IR）与检索/记忆契约。Go 模块路径 `agent-system-core`。
|
||||
|
||||
契约与架构见 Agent-System-Documents 设计方案与架构文档；开发规范见 development-guidelines（Dev 仓 `development/guidelines`）。本仓为 Agent-System 多仓组合的组成部分。
|
||||
## 三态一致
|
||||
|
||||
同一契约以三种形态发布，变更须保持一致：
|
||||
|
||||
1. **Go 类型**（`*.go`，camelCase JSON 标签）——后端与代码插件使用。
|
||||
2. **黄金样本**（`testdata/golden/*.json`）——线格式权威，`go test ./...` 强校验；变更显式重生成（`go test ./... -update`）。
|
||||
3. **TS 类型**（`ts/types.ts`）——前端镜像，前端测试按黄金样本做形状断言。
|
||||
|
||||
## 原则
|
||||
|
||||
- 只含契约与纯函数，不含实现、不含 I/O、不依赖生态仓。
|
||||
- 前向兼容：字段只增不删；消费方对未知 `type`/词汇静默忽略（`v` 字段协商）。
|
||||
- 摄取 IR（ParsedDocument）是解析器与下游的隔离层；检索/记忆契约先行、实现后置。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
package core
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"flag"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// 黄金样本一致性：Go 序列化（线格式契约）与 testdata/golden/*.json 逐字节一致。
|
||||
// ts/types.ts 镜像同一契约；前端测试按样本做形状断言。变更契约须显式更新样本。
|
||||
var update = flag.Bool("update", false, "rewrite golden files")
|
||||
|
||||
func golden(t *testing.T, name string, v any) {
|
||||
t.Helper()
|
||||
data, err := json.MarshalIndent(v, "", " ")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
path := filepath.Join("testdata", "golden", name+".json")
|
||||
if *update {
|
||||
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(path, append(data, '\n'), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return
|
||||
}
|
||||
want, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("golden missing (run go test ./... -update): %v", err)
|
||||
}
|
||||
if string(want) != string(append(data, '\n')) {
|
||||
t.Errorf("%s: golden mismatch:\n got: %s\nwant: %s", name, data, want)
|
||||
}
|
||||
}
|
||||
|
||||
func sampleMessage() Message {
|
||||
return Message{
|
||||
ID: "msg_abc123def456", ConversationID: "cnv_abc123def456", RunID: "run_abc123def456",
|
||||
Role: RoleAssistant,
|
||||
Parts: []Part{
|
||||
{Type: PartThinking, Text: "考虑先检索…", Process: true},
|
||||
{Type: PartToolCall, Process: true, ToolCall: &ToolCallPart{ID: "call_1", Name: "history_search", Arguments: `{"q":"部署"}`, Duration: 12.5}},
|
||||
{Type: PartToolResult, Process: true, ToolResult: &ToolResultPart{CallID: "call_1", Status: "ok", Summary: "3 条命中"}},
|
||||
{Type: PartText, Text: "根据历史记录……"},
|
||||
{Type: PartArtifactRef, Artifact: &ArtifactRef{ArtifactID: "art_abc123def456", Name: "报告.md", Kind: "document"}},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func sampleRun() Run {
|
||||
return Run{
|
||||
ID: "run_abc123def456", ConversationID: "cnv_abc123def456", ProjectID: "prj_abc123def456",
|
||||
Kind: RunConversation, ProfileID: "default", Status: RunCompleted, Phase: PhaseDone,
|
||||
Usage: &Usage{PromptTokens: 1200, CompletionTokens: 300, TotalTokens: 1500, DurationMs: 4200.5, ToolCalls: 2},
|
||||
}
|
||||
}
|
||||
|
||||
func TestGoldenDomain(t *testing.T) {
|
||||
golden(t, "message", sampleMessage())
|
||||
golden(t, "run", sampleRun())
|
||||
golden(t, "project", Project{ID: "prj_abc123def456", Name: "示例项目"})
|
||||
golden(t, "conversation", Conversation{ID: "cnv_abc123def456", ProjectID: "prj_abc123def456", Title: "新会话"})
|
||||
golden(t, "artifact", Artifact{ID: "art_abc123def456", ProjectID: "prj_abc123def456", Name: "报告.md", Kind: "document", MIME: "text/markdown", Size: 128})
|
||||
}
|
||||
|
||||
func TestGoldenEvents(t *testing.T) {
|
||||
golden(t, "event_message_delta", StreamEvent{Seq: 42, RunID: "run_1", ConversationID: "cnv_1", TS: "2026-09-29T10:00:00Z", V: 1, Type: EvMessageDelta, Payload: json.RawMessage(`{"index":0,"text":"你"}`)})
|
||||
golden(t, "event_agent_spawn", StreamEvent{Seq: 43, RunID: "run_1", ConversationID: "cnv_1", TS: "2026-09-29T10:00:01Z", V: 1, Type: EvAgentSpawn, Payload: json.RawMessage(`{"agentRun":"run_sub1","name":"检索员","task":"查法规"}`)})
|
||||
golden(t, "event_run_completed", StreamEvent{Seq: 44, RunID: "run_1", ConversationID: "cnv_1", TS: "2026-09-29T10:00:02Z", V: 1, Type: EvRunCompleted, Payload: json.RawMessage(`{"usage":{"promptTokens":100,"completionTokens":20,"totalTokens":120,"durationMs":1500,"toolCalls":1}}`)})
|
||||
}
|
||||
|
||||
func TestGoldenHITL(t *testing.T) {
|
||||
golden(t, "hitl_card", HITLCard{
|
||||
ID: "hitl_abc123def456", RunID: "run_1", ConversationID: "cnv_1",
|
||||
Question: "采用哪种输出格式？", Kind: HITLKindChoice,
|
||||
Choices: []HITLChoice{
|
||||
{ID: "md", Label: "Markdown 文档", Description: "可版本管理的轻量文档", Impact: "写入 artifacts，可在右栏查看", Recommended: true},
|
||||
{ID: "docx", Label: "Word 文档", Description: "正式交付格式", Impact: "生成 docx 工件"},
|
||||
},
|
||||
AllowFreeInput: true, FreeInputHint: "也可以直接输入其他格式要求",
|
||||
})
|
||||
}
|
||||
|
||||
func TestGoldenProfileAndTools(t *testing.T) {
|
||||
maxT := 40
|
||||
golden(t, "profile", AgentProfile{
|
||||
ID: "default", Name: "通用助手", Builtin: true, Source: "builtin",
|
||||
SystemPrompt: "你是一个通用智能体助手。",
|
||||
Model: ModelRoute{Chat: "gpt-default", Lightweight: "gpt-lite"},
|
||||
Tools: ToolPolicy{Allow: []string{"*"}, Deny: []string{"http.admin."}, Confirm: []string{"http."}},
|
||||
Context: ContextPolicy{MaxHistoryMessages: 40, MaxToolResultChars: 20000},
|
||||
HITL: HITLPolicy{AskOnAmbiguity: true},
|
||||
Budget: RunBudget{MaxToolCalls: &maxT},
|
||||
})
|
||||
golden(t, "tool_http", ToolDesc{
|
||||
Name: "http_translate", Description: "调用翻译 API", Source: SourceUser,
|
||||
Parameters: json.RawMessage(`{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}`),
|
||||
HTTP: &HTTPToolSpec{Method: "POST", URL: "https://api.example.com/translate", BodyTemplate: `{"q":"{{param.text}}"}`, TimeoutMs: 10000, ResultPath: "data.0"},
|
||||
})
|
||||
}
|
||||
|
||||
func TestGoldenIngest(t *testing.T) {
|
||||
golden(t, "parsed_document", ParsedDocument{
|
||||
Meta: DocMeta{Filename: "报告.docx", MIME: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", Parser: "builtin:docx", Confidence: 0.92},
|
||||
Blocks: []DocBlock{
|
||||
{Type: BlockHeading, Level: 1, Text: "概述"},
|
||||
{Type: BlockPara, Text: "本文档说明……"},
|
||||
{Type: BlockList, Items: []string{"要点一", "要点二"}},
|
||||
{Type: BlockTable, Rows: [][]string{{"项", "值"}, {"版本", "1.0"}}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
func TestGoldenPlugin(t *testing.T) {
|
||||
golden(t, "plugin_manifest", PluginManifest{
|
||||
ID: "example", Name: "示例插件", Version: "0.1.0", APIVersion: PluginAPIVersion,
|
||||
Requires: PluginRequires{Network: []string{"api.example.com"}},
|
||||
Provides: PluginProvides{Tools: []string{"http_echo"}, Intents: []string{"demo"}, Panels: []string{"demo"}, Cards: []string{"note"}, Settings: []string{"greeting"}},
|
||||
})
|
||||
}
|
||||
|
||||
// ---- 纯函数行为 ----
|
||||
|
||||
func TestToolPolicy(t *testing.T) {
|
||||
p := ToolPolicy{Allow: []string{"*"}, Deny: []string{"http.admin."}, Confirm: []string{"http."}}
|
||||
if !p.ToolAllowed("history_search") {
|
||||
t.Error("allow * should permit builtin tools")
|
||||
}
|
||||
if p.ToolAllowed("http.admin.reset") {
|
||||
t.Error("deny prefix should win over allow *")
|
||||
}
|
||||
if !p.ToolAllowed("http.fetch") || !p.NeedsConfirm("http.fetch") {
|
||||
t.Error("http prefix tools allowed but need confirm")
|
||||
}
|
||||
if p.NeedsConfirm("history_search") {
|
||||
t.Error("builtin tool should not need confirm")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPlainText(t *testing.T) {
|
||||
d := ParsedDocument{Blocks: []DocBlock{
|
||||
{Type: BlockHeading, Level: 2, Text: "标题"},
|
||||
{Type: BlockPara, Text: "段落"},
|
||||
{Type: BlockTable, Rows: [][]string{{"a", "b"}}},
|
||||
}}
|
||||
got := d.PlainText()
|
||||
for _, want := range []string{"## 标题", "段落", "a\tb"} {
|
||||
if !contains(got, want) {
|
||||
t.Errorf("PlainText missing %q in %q", want, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestSettingsMergeAndPath(t *testing.T) {
|
||||
base := map[string]any{"models": map[string]any{"chat": "a", "temperature": 0.7}, "ui": map[string]any{"theme": "light"}}
|
||||
over := map[string]any{"models": map[string]any{"chat": "b"}, "ui": map[string]any{"theme": "dark"}}
|
||||
eff := EffectiveSettings(MergeSettings(base, over))
|
||||
if eff.GetString("models.chat", "") != "b" || eff.GetNumber("models.temperature", 0) != 0.7 {
|
||||
t.Error("deep merge failed")
|
||||
}
|
||||
if eff.GetString("models.missing", "def") != "def" {
|
||||
t.Error("missing path should return default")
|
||||
}
|
||||
}
|
||||
|
||||
func contains(s, sub string) bool {
|
||||
return len(s) >= len(sub) && (func() bool {
|
||||
for i := 0; i+len(sub) <= len(s); i++ {
|
||||
if s[i:i+len(sub)] == sub {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
})()
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
package core
|
||||
|
||||
import "time"
|
||||
|
||||
// ---- 文档摄取与解析（4.11）----
|
||||
|
||||
// ParsedDocument 是解析中间表示：所有下游（附件上下文/工件预览/检索索引/全文检索）
|
||||
// 只消费 IR，不关心解析器——解析器可替换、可组合、可交叉验证。
|
||||
type ParsedDocument struct {
|
||||
Meta DocMeta `json:"meta"`
|
||||
Blocks []DocBlock `json:"blocks"`
|
||||
Warnings []string `json:"warnings,omitempty"`
|
||||
}
|
||||
|
||||
type DocMeta struct {
|
||||
Filename string `json:"filename"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Parser string `json:"parser"` // builtin:md / builtin:docx / mineru / agent
|
||||
Confidence float64 `json:"confidence,omitempty"` // 0–1；交叉验证差异块拉低
|
||||
CrossCheck *CrossCheck `json:"crossCheck,omitempty"`
|
||||
ParsedAt time.Time `json:"parsedAt"`
|
||||
}
|
||||
|
||||
type CrossCheck struct {
|
||||
With string `json:"with"` // 交叉验证的另一解析器
|
||||
DiffBlocks int `json:"diffBlocks"`
|
||||
Verdict string `json:"verdict"` // agree | differ
|
||||
}
|
||||
|
||||
type DocBlockType string
|
||||
|
||||
const (
|
||||
BlockHeading DocBlockType = "heading"
|
||||
BlockPara DocBlockType = "para"
|
||||
BlockList DocBlockType = "list"
|
||||
BlockTable DocBlockType = "table"
|
||||
BlockCode DocBlockType = "code"
|
||||
BlockImageRef DocBlockType = "image-ref"
|
||||
)
|
||||
|
||||
type DocBlock struct {
|
||||
Type DocBlockType `json:"type"`
|
||||
Level int `json:"level,omitempty"` // heading
|
||||
Text string `json:"text,omitempty"` // para/heading/list 项拼接/code
|
||||
Items []string `json:"items,omitempty"` // list
|
||||
Rows [][]string `json:"rows,omitempty"` // table（首行为表头）
|
||||
Ref string `json:"ref,omitempty"` // image-ref 的对象键
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
}
|
||||
|
||||
// PlainText 把文档压成纯文本（附件注入与全文索引用）；表格按行拼接。
|
||||
func (d ParsedDocument) PlainText() string {
|
||||
out := make([]byte, 0, 1024)
|
||||
for _, b := range d.Blocks {
|
||||
switch b.Type {
|
||||
case BlockHeading:
|
||||
out = append(out, '\n')
|
||||
for i := 0; i < b.Level; i++ {
|
||||
out = append(out, '#')
|
||||
}
|
||||
out = append(out, ' ')
|
||||
out = append(out, b.Text...)
|
||||
out = append(out, '\n')
|
||||
case BlockPara, BlockCode:
|
||||
out = append(out, b.Text...)
|
||||
out = append(out, '\n')
|
||||
case BlockList:
|
||||
for _, it := range b.Items {
|
||||
out = append(out, "- "...)
|
||||
out = append(out, it...)
|
||||
out = append(out, '\n')
|
||||
}
|
||||
case BlockTable:
|
||||
for _, row := range b.Rows {
|
||||
for i, cell := range row {
|
||||
if i > 0 {
|
||||
out = append(out, '\t')
|
||||
}
|
||||
out = append(out, cell...)
|
||||
}
|
||||
out = append(out, '\n')
|
||||
}
|
||||
}
|
||||
out = append(out, '\n')
|
||||
}
|
||||
return string(out)
|
||||
}
|
||||
|
||||
// ParserDesc 注册表条目（来源标记：builtin/plugin/...；一切可禁用）。
|
||||
type ParserDesc struct {
|
||||
ID string `json:"id"`
|
||||
Formats []string `json:"formats"` // 支持的扩展名
|
||||
Source SourceKind `json:"source"`
|
||||
Note string `json:"note,omitempty"`
|
||||
}
|
||||
|
||||
// ---- 检索（4.12）----
|
||||
|
||||
// KnowledgeDoc 是检索语料的一条文档（来自 ingest 或插件知识库，带来源标记）。
|
||||
type KnowledgeDoc struct {
|
||||
ID ID `json:"id"`
|
||||
ProjectID ID `json:"projectId,omitempty"` // 空 = 插件级知识库
|
||||
Source string `json:"source"` // upload | artifact | plugin:<id>
|
||||
Title string `json:"title"`
|
||||
Ref string `json:"ref,omitempty"` // 工件/文件引用
|
||||
Chunk string `json:"chunk"`
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
}
|
||||
|
||||
type RetrievalHit struct {
|
||||
Doc KnowledgeDoc `json:"doc"`
|
||||
Score float64 `json:"score"`
|
||||
Kind string `json:"kind"` // fulltext | vector | plugin
|
||||
}
|
||||
|
||||
type RetrievalQuery struct {
|
||||
ProjectID ID `json:"projectId,omitempty"`
|
||||
Text string `json:"text"`
|
||||
TopK int `json:"topK,omitempty"`
|
||||
Sources []string `json:"sources,omitempty"` // 过滤来源
|
||||
}
|
||||
|
||||
// ---- 记忆（4.13 契约；实现远期）----
|
||||
|
||||
type MemoryEntry struct {
|
||||
ID string `json:"id"`
|
||||
Scope string `json:"scope"` // user | project
|
||||
ProjectID ID `json:"projectId,omitempty"`
|
||||
Type string `json:"type"` // fact | preference | decision | episode | procedure
|
||||
Content string `json:"content"`
|
||||
Source string `json:"source"` // run:<id> | manual
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
LastAccessed time.Time `json:"lastAccessed"`
|
||||
ExpiresAt *time.Time `json:"expiresAt,omitempty"`
|
||||
}
|
||||
|
||||
// ---- 上传文件 ----
|
||||
|
||||
type UploadInfo struct {
|
||||
ArtifactID ID `json:"artifactId"`
|
||||
Filename string `json:"filename"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Size int64 `json:"size"`
|
||||
Parsed *ParsedDocument `json:"parsed,omitempty"`
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
package core
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// 事件信封：后端 → 前端的唯一增量通道（SSE），持久化后转发，Seq 在会话内单调。
|
||||
// 消费方对未知 Type 静默忽略（原则 6 前向兼容）。
|
||||
type StreamEvent struct {
|
||||
Seq int64 `json:"seq"`
|
||||
RunID ID `json:"runId,omitempty"`
|
||||
ConversationID ID `json:"conversationId"`
|
||||
TS string `json:"ts"` // RFC3339
|
||||
V int `json:"v"`
|
||||
Type StreamEventType `json:"type"`
|
||||
Payload json.RawMessage `json:"payload,omitempty"`
|
||||
}
|
||||
|
||||
type StreamEventType string
|
||||
|
||||
const (
|
||||
EvMessageDelta StreamEventType = "message.delta"
|
||||
EvThinkingDelta StreamEventType = "thinking.delta"
|
||||
EvToolCall StreamEventType = "tool.call"
|
||||
EvToolResult StreamEventType = "tool.result"
|
||||
EvRunPhase StreamEventType = "run.phase"
|
||||
EvHITLRequest StreamEventType = "hitl.request"
|
||||
EvHITLResolved StreamEventType = "hitl.resolved"
|
||||
EvPlanUpdate StreamEventType = "plan.update"
|
||||
EvTodoUpdate StreamEventType = "todo.update"
|
||||
EvAgentSpawn StreamEventType = "agent.spawn"
|
||||
EvAgentProgress StreamEventType = "agent.progress"
|
||||
EvAgentResult StreamEventType = "agent.result"
|
||||
EvArtifactCreated StreamEventType = "artifact.created"
|
||||
EvArtifactUpdated StreamEventType = "artifact.updated"
|
||||
EvRunCompleted StreamEventType = "run.completed"
|
||||
EvRunFailed StreamEventType = "run.failed"
|
||||
EvError StreamEventType = "error"
|
||||
)
|
||||
|
||||
// ProtocolVersion 是事件信封与 payload 词汇的当前版本。
|
||||
const ProtocolVersion = 1
|
||||
|
||||
// ---- 各事件 payload（新增字段只增不删；消费方忽略未知字段）----
|
||||
|
||||
// MessageDeltaPayload：正文增量。Index 标识目标 Part 序号（流式聚合用）。
|
||||
type MessageDeltaPayload struct {
|
||||
Index int `json:"index"`
|
||||
Text string `json:"text"`
|
||||
}
|
||||
|
||||
type ThinkingDeltaPayload struct {
|
||||
Index int `json:"index"`
|
||||
Text string `json:"text"`
|
||||
}
|
||||
|
||||
type ToolCallPayload struct {
|
||||
CallID string `json:"callId"`
|
||||
Name string `json:"name"`
|
||||
Arguments string `json:"arguments,omitempty"`
|
||||
}
|
||||
|
||||
type ToolResultPayload struct {
|
||||
CallID string `json:"callId"`
|
||||
Status string `json:"status"`
|
||||
Summary string `json:"summary,omitempty"`
|
||||
Truncated bool `json:"truncated,omitempty"`
|
||||
}
|
||||
|
||||
type RunPhasePayload struct {
|
||||
Phase RunPhase `json:"phase"`
|
||||
}
|
||||
|
||||
type HITLResolvedPayload struct {
|
||||
CardID ID `json:"cardId"`
|
||||
Answer string `json:"answer,omitempty"`
|
||||
Kind string `json:"kind"` // choice | free | timeout | cancelled
|
||||
}
|
||||
|
||||
type PlanUpdatePayload struct {
|
||||
Plan PlanSnapshot `json:"plan"`
|
||||
}
|
||||
|
||||
type TodoUpdatePayload struct {
|
||||
List TodoList `json:"list"`
|
||||
}
|
||||
|
||||
// AgentSpawnPayload：子代理派生；AgentRun 即子 Run（父子关系即任务树）。
|
||||
type AgentSpawnPayload struct {
|
||||
AgentRun ID `json:"agentRun"`
|
||||
Name string `json:"name"`
|
||||
Task string `json:"task"`
|
||||
}
|
||||
|
||||
type AgentProgressPayload struct {
|
||||
AgentRun ID `json:"agentRun"`
|
||||
Note string `json:"note,omitempty"`
|
||||
Phase RunPhase `json:"phase,omitempty"`
|
||||
}
|
||||
|
||||
type AgentResultPayload struct {
|
||||
AgentRun ID `json:"agentRun"`
|
||||
Status RunStatus `json:"status"`
|
||||
Summary string `json:"summary,omitempty"`
|
||||
}
|
||||
|
||||
type ArtifactPayload struct {
|
||||
Artifact Artifact `json:"artifact"`
|
||||
}
|
||||
|
||||
type RunCompletedPayload struct {
|
||||
Usage Usage `json:"usage"`
|
||||
}
|
||||
|
||||
type RunFailedPayload struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
type ErrorPayload struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
RunID ID `json:"runId,omitempty"`
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
package core
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// HITL 卡片协议（4.5）：choice | input | confirm | form 四种；
|
||||
// 发起方必须给 Choices 提供 description 与 impact——用户在决策点需要上下文。
|
||||
type HITLCard struct {
|
||||
ID ID `json:"id"`
|
||||
RunID ID `json:"runId"`
|
||||
ConversationID ID `json:"conversationId"`
|
||||
Question string `json:"question"`
|
||||
Kind HITLKind `json:"kind"`
|
||||
Choices []HITLChoice `json:"choices,omitempty"`
|
||||
AllowFreeInput bool `json:"allowFreeInput"`
|
||||
FreeInputHint string `json:"freeInputHint,omitempty"`
|
||||
TimeoutSec *int `json:"timeoutSec,omitempty"`
|
||||
Form []UINode `json:"form,omitempty"` // form kind 的字段（UI 词汇）
|
||||
CreatedAt string `json:"createdAt"`
|
||||
Resolved bool `json:"resolved"`
|
||||
}
|
||||
|
||||
type HITLKind string
|
||||
|
||||
const (
|
||||
HITLKindChoice HITLKind = "choice"
|
||||
HITLKindInput HITLKind = "input"
|
||||
HITLKindConfirm HITLKind = "confirm"
|
||||
HITLKindForm HITLKind = "form"
|
||||
)
|
||||
|
||||
type HITLChoice struct {
|
||||
ID string `json:"id"`
|
||||
Label string `json:"label"`
|
||||
Description string `json:"description"`
|
||||
Impact string `json:"impact"` // 该选择可能造成的影响（必填）
|
||||
Recommended bool `json:"recommended,omitempty"`
|
||||
}
|
||||
|
||||
// HITLResponse 是用户对卡片的响应；自由输入时 ChoiceID 为空。
|
||||
type HITLResponse struct {
|
||||
CardID ID `json:"cardId"`
|
||||
ChoiceID string `json:"choiceId,omitempty"`
|
||||
FreeText string `json:"freeText,omitempty"`
|
||||
FormData json.RawMessage `json:"formData,omitempty"`
|
||||
}
|
||||
@@ -0,0 +1,217 @@
|
||||
// Package core 定义 Agent-System 的核心契约：领域模型、流式事件、HITL 卡片、
|
||||
// 插件 API、设置与 UI 词汇。本仓只含契约与少量纯函数，不含实现、不含 I/O。
|
||||
//
|
||||
// JSON 标签（camelCase）是前后端与插件共同的线格式契约；TS 类型镜像见 ts/types.ts，
|
||||
// 黄金样本见 testdata/golden/（conformance 测试保证 Go 序列化与样本一致）。
|
||||
package core
|
||||
|
||||
import "time"
|
||||
|
||||
// ---- 标识 ----
|
||||
|
||||
// ID 形态为 <kind>_<hex12>；生成由后端负责，契约只约束非空与唯一。
|
||||
type ID = string
|
||||
|
||||
// ---- 项目与会话 ----
|
||||
|
||||
type Project struct {
|
||||
ID ID `json:"id"`
|
||||
Name string `json:"name"`
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
UpdatedAt time.Time `json:"updatedAt"`
|
||||
Settings map[string]any `json:"settings,omitempty"` // 项目层设置覆盖（4.9 覆盖链）
|
||||
}
|
||||
|
||||
type Conversation struct {
|
||||
ID ID `json:"id"`
|
||||
ProjectID ID `json:"projectId"`
|
||||
Title string `json:"title"`
|
||||
ProfileID ID `json:"profileId,omitempty"` // 空为默认画像
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
UpdatedAt time.Time `json:"updatedAt"`
|
||||
}
|
||||
|
||||
// ---- 消息与部件 ----
|
||||
|
||||
type Role string
|
||||
|
||||
const (
|
||||
RoleUser Role = "user"
|
||||
RoleAssistant Role = "assistant"
|
||||
RoleSystem Role = "system"
|
||||
)
|
||||
|
||||
// PartType 区分消息成分；前端按类型查渲染器，未知类型静默忽略（原则 6）。
|
||||
type PartType string
|
||||
|
||||
const (
|
||||
PartText PartType = "text"
|
||||
PartThinking PartType = "thinking"
|
||||
PartToolCall PartType = "tool_call"
|
||||
PartToolResult PartType = "tool_result"
|
||||
PartArtifactRef PartType = "artifact_ref"
|
||||
PartHITL PartType = "hitl"
|
||||
PartPlan PartType = "plan"
|
||||
PartError PartType = "error"
|
||||
PartCard PartType = "card" // 插件自定义卡片（Data 为 UI schema）
|
||||
)
|
||||
|
||||
type Message struct {
|
||||
ID ID `json:"id"`
|
||||
ConversationID ID `json:"conversationId"`
|
||||
RunID ID `json:"runId,omitempty"`
|
||||
Role Role `json:"role"`
|
||||
Parts []Part `json:"parts"`
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
}
|
||||
|
||||
// Part 是判别联合：Type 决定哪些字段有意义；未用字段为零值。
|
||||
type Part struct {
|
||||
Type PartType `json:"type"`
|
||||
|
||||
Text string `json:"text,omitempty"` // text / thinking（流式增量聚合后）
|
||||
|
||||
ToolCall *ToolCallPart `json:"toolCall,omitempty"`
|
||||
ToolResult *ToolResultPart `json:"toolResult,omitempty"`
|
||||
Artifact *ArtifactRef `json:"artifact,omitempty"`
|
||||
Hitl *HITLSummary `json:"hitl,omitempty"`
|
||||
Plan *PlanSnapshot `json:"plan,omitempty"`
|
||||
Card *CardPart `json:"card,omitempty"`
|
||||
Err *ErrorPart `json:"error,omitempty"`
|
||||
|
||||
// 过程标记：true 的部件在 run 终态后由前端折叠为摘要行（4.2）。
|
||||
Process bool `json:"process,omitempty"`
|
||||
}
|
||||
|
||||
type ToolCallPart struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Arguments string `json:"arguments,omitempty"` // 原始 JSON
|
||||
Duration float64 `json:"durationMs,omitempty"`
|
||||
}
|
||||
|
||||
type ToolResultPart struct {
|
||||
CallID string `json:"callId"`
|
||||
Status string `json:"status"` // ok | error
|
||||
Summary string `json:"summary,omitempty"`
|
||||
Truncated bool `json:"truncated,omitempty"` // 超长截断并转工件引用（4.10）
|
||||
}
|
||||
|
||||
type ArtifactRef struct {
|
||||
ArtifactID ID `json:"artifactId"`
|
||||
Name string `json:"name"`
|
||||
Kind string `json:"kind,omitempty"` // document | image | data | ...
|
||||
}
|
||||
|
||||
type HITLSummary struct {
|
||||
CardID ID `json:"cardId"`
|
||||
Question string `json:"question"`
|
||||
Resolved bool `json:"resolved"`
|
||||
Answer string `json:"answer,omitempty"` // 选中项 label 或回填文本
|
||||
}
|
||||
|
||||
type ErrorPart struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
// CardPart.Data 是 UI schema 节点（4.6 有限词汇）。
|
||||
type CardPart struct {
|
||||
Kind string `json:"kind"`
|
||||
Data []UINode `json:"data"`
|
||||
}
|
||||
|
||||
// ---- Run（一切运行皆 Run）----
|
||||
|
||||
type RunKind string
|
||||
|
||||
const (
|
||||
RunConversation RunKind = "conversation"
|
||||
RunSubagent RunKind = "subagent"
|
||||
RunTool RunKind = "tool"
|
||||
)
|
||||
|
||||
type RunStatus string
|
||||
|
||||
const (
|
||||
RunPending RunStatus = "pending"
|
||||
RunRunning RunStatus = "running"
|
||||
RunWaitingHITL RunStatus = "waiting_hitl"
|
||||
RunCompleted RunStatus = "completed"
|
||||
RunFailed RunStatus = "failed"
|
||||
RunCancelled RunStatus = "cancelled"
|
||||
RunInterrupted RunStatus = "interrupted"
|
||||
)
|
||||
|
||||
type RunPhase string
|
||||
|
||||
const (
|
||||
PhaseThinking RunPhase = "thinking"
|
||||
PhaseActing RunPhase = "acting"
|
||||
PhaseResponding RunPhase = "responding"
|
||||
PhaseDone RunPhase = "done"
|
||||
)
|
||||
|
||||
type Run struct {
|
||||
ID ID `json:"id"`
|
||||
ParentRunID ID `json:"parentRunId,omitempty"`
|
||||
ConversationID ID `json:"conversationId"`
|
||||
ProjectID ID `json:"projectId"`
|
||||
Kind RunKind `json:"kind"`
|
||||
ProfileID ID `json:"profileId,omitempty"`
|
||||
Status RunStatus `json:"status"`
|
||||
Phase RunPhase `json:"phase,omitempty"`
|
||||
AgentName string `json:"agentName,omitempty"` // subagent 显示名
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
EndedAt *time.Time `json:"endedAt,omitempty"`
|
||||
Usage *Usage `json:"usage,omitempty"`
|
||||
Error *ErrorPart `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
type Usage struct {
|
||||
PromptTokens int `json:"promptTokens"`
|
||||
CompletionTokens int `json:"completionTokens"`
|
||||
TotalTokens int `json:"totalTokens"`
|
||||
DurationMs float64 `json:"durationMs"`
|
||||
ToolCalls int `json:"toolCalls"`
|
||||
}
|
||||
|
||||
// ---- 工件 ----
|
||||
|
||||
type Artifact struct {
|
||||
ID ID `json:"id"`
|
||||
ProjectID ID `json:"projectId"`
|
||||
Name string `json:"name"`
|
||||
Kind string `json:"kind"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Size int64 `json:"size"`
|
||||
SourceRun ID `json:"sourceRun,omitempty"`
|
||||
CreatedAt time.Time `json:"createdAt"`
|
||||
UpdatedAt time.Time `json:"updatedAt"`
|
||||
}
|
||||
|
||||
// ---- 计划与待办（右栏 Plan / Todos）----
|
||||
|
||||
type PlanSnapshot struct {
|
||||
PlanID ID `json:"planId"`
|
||||
Title string `json:"title"`
|
||||
Steps []PlanStep `json:"steps"`
|
||||
}
|
||||
|
||||
type PlanStep struct {
|
||||
ID string `json:"id"`
|
||||
Text string `json:"text"`
|
||||
Status string `json:"status"` // pending | in_progress | done | skipped
|
||||
AgentRun ID `json:"agentRun,omitempty"`
|
||||
}
|
||||
|
||||
type TodoList struct {
|
||||
ConversationID ID `json:"conversationId"`
|
||||
Items []TodoItem `json:"items"`
|
||||
}
|
||||
|
||||
type TodoItem struct {
|
||||
ID string `json:"id"`
|
||||
Text string `json:"text"`
|
||||
Status string `json:"status"` // pending | in_progress | done
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
package core
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// 插件 manifest（4.6）：插件 = manifest + 声明资产 + 可选代码。
|
||||
// 校验失败整批拒绝（fail-closed）；卸载注销注册项，在途引用按定义缺失稳定报错。
|
||||
|
||||
const PluginAPIVersion = "1.0"
|
||||
|
||||
type PluginManifest struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Version string `json:"version"`
|
||||
APIVersion string `json:"apiVersion"`
|
||||
Requires PluginRequires `json:"requires,omitempty"`
|
||||
Provides PluginProvides `json:"provides"`
|
||||
}
|
||||
|
||||
type PluginRequires struct {
|
||||
Network []string `json:"network,omitempty"` // 允许访问的域名（展示用，v1 自装自审）
|
||||
}
|
||||
|
||||
type PluginProvides struct {
|
||||
Tools []string `json:"tools,omitempty"` // tools/ 目录下的资产名
|
||||
Workflows []string `json:"workflows,omitempty"`
|
||||
Intents []string `json:"intents,omitempty"`
|
||||
Prompts []string `json:"prompts,omitempty"`
|
||||
Panels []string `json:"panels,omitempty"`
|
||||
Cards []string `json:"cards,omitempty"`
|
||||
Settings []string `json:"settings,omitempty"`
|
||||
}
|
||||
|
||||
// PluginPanel：右栏面板声明（UI schema 静态骨架 + 可选数据提供者）。
|
||||
type PluginPanel struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Icon string `json:"icon,omitempty"`
|
||||
Body []UINode `json:"body"`
|
||||
// Tool 绑定：面板挂载时调用该工具刷新 Body 中的动态区（v1 简化为整体刷新）。
|
||||
RefreshTool string `json:"refreshTool,omitempty"`
|
||||
}
|
||||
|
||||
// WorkflowDef：工作流即数据（4.6）。Step 可产 HITL 卡片、调工具、产出工件。
|
||||
type WorkflowDef struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Description string `json:"description,omitempty"`
|
||||
IntentID string `json:"intentId,omitempty"` // 绑定意图（命中即启动）
|
||||
Steps []WorkflowStep `json:"steps"`
|
||||
}
|
||||
|
||||
type WorkflowStep struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Kind string `json:"kind"` // prompt | tool | hitl | artifact
|
||||
Prompt string `json:"prompt,omitempty"` // prompt: 发给模型的指令模板
|
||||
Tool string `json:"tool,omitempty"` // tool: 工具名
|
||||
Args json.RawMessage `json:"args,omitempty"` // tool: 参数模板
|
||||
Hitl *HITLCardTemplate `json:"hitl,omitempty"` // hitl: 卡片模板
|
||||
Artifact string `json:"artifact,omitempty"` // artifact: 产出工件名模板
|
||||
}
|
||||
|
||||
type HITLCardTemplate struct {
|
||||
Question string `json:"question"`
|
||||
Kind HITLKind `json:"kind"`
|
||||
Choices []HITLChoice `json:"choices,omitempty"`
|
||||
AllowFreeInput bool `json:"allowFreeInput"`
|
||||
FreeInputHint string `json:"freeInputHint,omitempty"`
|
||||
}
|
||||
+205
@@ -0,0 +1,205 @@
|
||||
package core
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// 智能体画像（4.7）：核心定制机制，全部数据化、可导入导出。
|
||||
type AgentProfile struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Builtin bool `json:"builtin,omitempty"`
|
||||
Source string `json:"source,omitempty"` // builtin | plugin | user
|
||||
SystemPrompt string `json:"systemPrompt"`
|
||||
Model ModelRoute `json:"model"`
|
||||
Tools ToolPolicy `json:"tools"`
|
||||
Context ContextPolicy `json:"context"`
|
||||
HITL HITLPolicy `json:"hitl"`
|
||||
Budget RunBudget `json:"budget"`
|
||||
}
|
||||
|
||||
// ModelRoute 按用途选择模型（4.7 kind 路由）：空串回落到 chat 默认。
|
||||
type ModelRoute struct {
|
||||
Chat string `json:"chat,omitempty"`
|
||||
Lightweight string `json:"lightweight,omitempty"`
|
||||
Embedding string `json:"embedding,omitempty"`
|
||||
Rerank string `json:"rerank,omitempty"`
|
||||
}
|
||||
|
||||
// ToolPolicy 三清单：allow/deny 决定可见工具，confirm 强制执行前 HITL 确认。
|
||||
// 匹配语义：精确名或前缀通配（"http.*" 表示 http 前缀）；deny 优先于 allow。
|
||||
type ToolPolicy struct {
|
||||
Allow []string `json:"allow"` // ["*"] 全部
|
||||
Deny []string `json:"deny,omitempty"`
|
||||
Confirm []string `json:"confirm,omitempty"`
|
||||
}
|
||||
|
||||
// ContextPolicy（4.10）：ctxasm 的输入；逐版本增加策略项不动组装器接口。
|
||||
type ContextPolicy struct {
|
||||
MaxHistoryMessages int `json:"maxHistoryMessages"` // 0 = 默认 40
|
||||
SummarizeBeyond bool `json:"summarizeBeyond,omitempty"` // 远期；先存标志
|
||||
MemoryBudgetPct int `json:"memoryBudgetPct,omitempty"` // 注入槽份额上限
|
||||
KnowledgeBudgetPct int `json:"knowledgeBudgetPct,omitempty"`
|
||||
MaxToolResultChars int `json:"maxToolResultChars,omitempty"` // 0 = 默认 20000
|
||||
}
|
||||
|
||||
type HITLPolicy struct {
|
||||
AskOnAmbiguity bool `json:"askOnAmbiguity"`
|
||||
TimeoutSec *int `json:"timeoutSec,omitempty"`
|
||||
}
|
||||
|
||||
type RunBudget struct {
|
||||
MaxTokens *int `json:"maxTokens,omitempty"`
|
||||
MaxToolCalls *int `json:"maxToolCalls,omitempty"`
|
||||
MaxTurns *int `json:"maxTurns,omitempty"` // LLM 循环轮上限
|
||||
}
|
||||
|
||||
// ToolAllows 判定：deny 优先；allow 含 "*" 或精确/前缀命中。
|
||||
func (p ToolPolicy) ToolAllowed(name string) bool {
|
||||
if matchAny(p.Deny, name) {
|
||||
return false
|
||||
}
|
||||
if len(p.Allow) == 0 {
|
||||
return true
|
||||
}
|
||||
return matchAny(p.Allow, name)
|
||||
}
|
||||
|
||||
func (p ToolPolicy) NeedsConfirm(name string) bool {
|
||||
return matchAny(p.Confirm, name)
|
||||
}
|
||||
|
||||
// matchAny 语义：pattern 精确等于 name，或以 "xxx." 开头表示前缀族（http. → http.*）。
|
||||
func matchAny(patterns []string, name string) bool {
|
||||
for _, p := range patterns {
|
||||
if p == "*" || p == name {
|
||||
return true
|
||||
}
|
||||
if n := len(p); n > 1 && p[n-1] == '.' {
|
||||
if len(name) > n-1 && name[:n-1] == p[:n-1] {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// ---- 设置（4.9）----
|
||||
|
||||
type SettingType string
|
||||
|
||||
const (
|
||||
SettingString SettingType = "string"
|
||||
SettingNumber SettingType = "number"
|
||||
SettingBool SettingType = "boolean"
|
||||
SettingEnum SettingType = "enum"
|
||||
SettingSecret SettingType = "secret"
|
||||
)
|
||||
|
||||
type SettingEffect string
|
||||
|
||||
const (
|
||||
EffectHot SettingEffect = "hot" // 立即生效
|
||||
EffectNewRun SettingEffect = "new-run" // 仅影响新 run
|
||||
EffectRestart SettingEffect = "restart" // 需重启
|
||||
)
|
||||
|
||||
// SettingDesc 描述一个设置项；设置页按此渲染并标注生效时机（schema 驱动）。
|
||||
type SettingDesc struct {
|
||||
Key string `json:"key"`
|
||||
Group string `json:"group"` // 分区：models | profiles | tools | knowledge | ui | plugin:<id>
|
||||
Label string `json:"label"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Type SettingType `json:"type"`
|
||||
Default any `json:"default,omitempty"`
|
||||
Options []string `json:"options,omitempty"` // enum
|
||||
Effect SettingEffect `json:"effect"`
|
||||
Secret bool `json:"secret,omitempty"`
|
||||
}
|
||||
|
||||
// EffectiveSettings 是覆盖链（system → user → project → conversation）深合并结果。
|
||||
type EffectiveSettings map[string]any
|
||||
|
||||
// MergeSettings 深合并：后者覆盖前者；map 递归合并，其它类型直接覆盖（4.9 数组显式覆盖）。
|
||||
func MergeSettings(base, override map[string]any) map[string]any {
|
||||
out := make(map[string]any, len(base)+len(override))
|
||||
for k, v := range base {
|
||||
out[k] = v
|
||||
}
|
||||
for k, v := range override {
|
||||
if bm, ok := base[k].(map[string]any); ok {
|
||||
if vm, ok2 := v.(map[string]any); ok2 {
|
||||
out[k] = MergeSettings(bm, vm)
|
||||
continue
|
||||
}
|
||||
}
|
||||
out[k] = v
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// GetString/GetBool/GetNumber 读取点路径（"models.chat"）；缺省返回 def。
|
||||
func (s EffectiveSettings) GetString(path, def string) string {
|
||||
v, ok := lookupPath(s, path)
|
||||
if !ok {
|
||||
return def
|
||||
}
|
||||
if str, ok2 := v.(string); ok2 {
|
||||
return str
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
func (s EffectiveSettings) GetBool(path string, def bool) bool {
|
||||
v, ok := lookupPath(s, path)
|
||||
if !ok {
|
||||
return def
|
||||
}
|
||||
if b, ok2 := v.(bool); ok2 {
|
||||
return b
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
func (s EffectiveSettings) GetNumber(path string, def float64) float64 {
|
||||
v, ok := lookupPath(s, path)
|
||||
if !ok {
|
||||
return def
|
||||
}
|
||||
if f, ok2 := v.(float64); ok2 {
|
||||
return f
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
func lookupPath(m map[string]any, path string) (any, bool) {
|
||||
parts := splitPath(path)
|
||||
var cur any = m
|
||||
for _, p := range parts {
|
||||
cm, ok := cur.(map[string]any)
|
||||
if !ok {
|
||||
return nil, false
|
||||
}
|
||||
cur, ok = cm[p]
|
||||
if !ok {
|
||||
return nil, false
|
||||
}
|
||||
}
|
||||
return cur, true
|
||||
}
|
||||
|
||||
func splitPath(path string) []string {
|
||||
var out []string
|
||||
cur := ""
|
||||
for i := 0; i < len(path); i++ {
|
||||
switch path[i] {
|
||||
case '.':
|
||||
out = append(out, cur)
|
||||
cur = ""
|
||||
default:
|
||||
cur += string(path[i])
|
||||
}
|
||||
}
|
||||
return append(out, cur)
|
||||
}
|
||||
|
||||
var _ = json.Marshal // 保持 encoding/json 引用（RawMessage 一致性）
|
||||
Vendored
+10
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"id": "art_abc123def456",
|
||||
"projectId": "prj_abc123def456",
|
||||
"name": "报告.md",
|
||||
"kind": "document",
|
||||
"mime": "text/markdown",
|
||||
"size": 128,
|
||||
"createdAt": "0001-01-01T00:00:00Z",
|
||||
"updatedAt": "0001-01-01T00:00:00Z"
|
||||
}
|
||||
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"id": "cnv_abc123def456",
|
||||
"projectId": "prj_abc123def456",
|
||||
"title": "新会话",
|
||||
"createdAt": "0001-01-01T00:00:00Z",
|
||||
"updatedAt": "0001-01-01T00:00:00Z"
|
||||
}
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"seq": 43,
|
||||
"runId": "run_1",
|
||||
"conversationId": "cnv_1",
|
||||
"ts": "2026-09-29T10:00:01Z",
|
||||
"v": 1,
|
||||
"type": "agent.spawn",
|
||||
"payload": {
|
||||
"agentRun": "run_sub1",
|
||||
"name": "检索员",
|
||||
"task": "查法规"
|
||||
}
|
||||
}
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"seq": 42,
|
||||
"runId": "run_1",
|
||||
"conversationId": "cnv_1",
|
||||
"ts": "2026-09-29T10:00:00Z",
|
||||
"v": 1,
|
||||
"type": "message.delta",
|
||||
"payload": {
|
||||
"index": 0,
|
||||
"text": "你"
|
||||
}
|
||||
}
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"seq": 44,
|
||||
"runId": "run_1",
|
||||
"conversationId": "cnv_1",
|
||||
"ts": "2026-09-29T10:00:02Z",
|
||||
"v": 1,
|
||||
"type": "run.completed",
|
||||
"payload": {
|
||||
"usage": {
|
||||
"promptTokens": 100,
|
||||
"completionTokens": 20,
|
||||
"totalTokens": 120,
|
||||
"durationMs": 1500,
|
||||
"toolCalls": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
Vendored
+26
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "hitl_abc123def456",
|
||||
"runId": "run_1",
|
||||
"conversationId": "cnv_1",
|
||||
"question": "采用哪种输出格式？",
|
||||
"kind": "choice",
|
||||
"choices": [
|
||||
{
|
||||
"id": "md",
|
||||
"label": "Markdown 文档",
|
||||
"description": "可版本管理的轻量文档",
|
||||
"impact": "写入 artifacts，可在右栏查看",
|
||||
"recommended": true
|
||||
},
|
||||
{
|
||||
"id": "docx",
|
||||
"label": "Word 文档",
|
||||
"description": "正式交付格式",
|
||||
"impact": "生成 docx 工件"
|
||||
}
|
||||
],
|
||||
"allowFreeInput": true,
|
||||
"freeInputHint": "也可以直接输入其他格式要求",
|
||||
"createdAt": "",
|
||||
"resolved": false
|
||||
}
|
||||
Vendored
+45
@@ -0,0 +1,45 @@
|
||||
{
|
||||
"id": "msg_abc123def456",
|
||||
"conversationId": "cnv_abc123def456",
|
||||
"runId": "run_abc123def456",
|
||||
"role": "assistant",
|
||||
"parts": [
|
||||
{
|
||||
"type": "thinking",
|
||||
"text": "考虑先检索…",
|
||||
"process": true
|
||||
},
|
||||
{
|
||||
"type": "tool_call",
|
||||
"toolCall": {
|
||||
"id": "call_1",
|
||||
"name": "history_search",
|
||||
"arguments": "{\"q\":\"部署\"}",
|
||||
"durationMs": 12.5
|
||||
},
|
||||
"process": true
|
||||
},
|
||||
{
|
||||
"type": "tool_result",
|
||||
"toolResult": {
|
||||
"callId": "call_1",
|
||||
"status": "ok",
|
||||
"summary": "3 条命中"
|
||||
},
|
||||
"process": true
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"text": "根据历史记录……"
|
||||
},
|
||||
{
|
||||
"type": "artifact_ref",
|
||||
"artifact": {
|
||||
"artifactId": "art_abc123def456",
|
||||
"name": "报告.md",
|
||||
"kind": "document"
|
||||
}
|
||||
}
|
||||
],
|
||||
"createdAt": "0001-01-01T00:00:00Z"
|
||||
}
|
||||
Vendored
+40
@@ -0,0 +1,40 @@
|
||||
{
|
||||
"meta": {
|
||||
"filename": "报告.docx",
|
||||
"mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
"parser": "builtin:docx",
|
||||
"confidence": 0.92,
|
||||
"parsedAt": "0001-01-01T00:00:00Z"
|
||||
},
|
||||
"blocks": [
|
||||
{
|
||||
"type": "heading",
|
||||
"level": 1,
|
||||
"text": "概述"
|
||||
},
|
||||
{
|
||||
"type": "para",
|
||||
"text": "本文档说明……"
|
||||
},
|
||||
{
|
||||
"type": "list",
|
||||
"items": [
|
||||
"要点一",
|
||||
"要点二"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "table",
|
||||
"rows": [
|
||||
[
|
||||
"项",
|
||||
"值"
|
||||
],
|
||||
[
|
||||
"版本",
|
||||
"1.0"
|
||||
]
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Vendored
+28
@@ -0,0 +1,28 @@
|
||||
{
|
||||
"id": "example",
|
||||
"name": "示例插件",
|
||||
"version": "0.1.0",
|
||||
"apiVersion": "1.0",
|
||||
"requires": {
|
||||
"network": [
|
||||
"api.example.com"
|
||||
]
|
||||
},
|
||||
"provides": {
|
||||
"tools": [
|
||||
"http_echo"
|
||||
],
|
||||
"intents": [
|
||||
"demo"
|
||||
],
|
||||
"panels": [
|
||||
"demo"
|
||||
],
|
||||
"cards": [
|
||||
"note"
|
||||
],
|
||||
"settings": [
|
||||
"greeting"
|
||||
]
|
||||
}
|
||||
}
|
||||
Vendored
+32
@@ -0,0 +1,32 @@
|
||||
{
|
||||
"id": "default",
|
||||
"name": "通用助手",
|
||||
"builtin": true,
|
||||
"source": "builtin",
|
||||
"systemPrompt": "你是一个通用智能体助手。",
|
||||
"model": {
|
||||
"chat": "gpt-default",
|
||||
"lightweight": "gpt-lite"
|
||||
},
|
||||
"tools": {
|
||||
"allow": [
|
||||
"*"
|
||||
],
|
||||
"deny": [
|
||||
"http.admin."
|
||||
],
|
||||
"confirm": [
|
||||
"http."
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"maxHistoryMessages": 40,
|
||||
"maxToolResultChars": 20000
|
||||
},
|
||||
"hitl": {
|
||||
"askOnAmbiguity": true
|
||||
},
|
||||
"budget": {
|
||||
"maxToolCalls": 40
|
||||
}
|
||||
}
|
||||
Vendored
+6
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"id": "prj_abc123def456",
|
||||
"name": "示例项目",
|
||||
"createdAt": "0001-01-01T00:00:00Z",
|
||||
"updatedAt": "0001-01-01T00:00:00Z"
|
||||
}
|
||||
Vendored
+17
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"id": "run_abc123def456",
|
||||
"conversationId": "cnv_abc123def456",
|
||||
"projectId": "prj_abc123def456",
|
||||
"kind": "conversation",
|
||||
"profileId": "default",
|
||||
"status": "completed",
|
||||
"phase": "done",
|
||||
"createdAt": "0001-01-01T00:00:00Z",
|
||||
"usage": {
|
||||
"promptTokens": 1200,
|
||||
"completionTokens": 300,
|
||||
"totalTokens": 1500,
|
||||
"durationMs": 4200.5,
|
||||
"toolCalls": 2
|
||||
}
|
||||
}
|
||||
Vendored
+23
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"name": "http_translate",
|
||||
"description": "调用翻译 API",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"text": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"text"
|
||||
]
|
||||
},
|
||||
"source": "user",
|
||||
"http": {
|
||||
"method": "POST",
|
||||
"url": "https://api.example.com/translate",
|
||||
"bodyTemplate": "{\"q\":\"{{param.text}}\"}",
|
||||
"timeoutMs": 10000,
|
||||
"resultPath": "data.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
package core
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// 工具契约（4.8）：内置、声明式 HTTP、插件工具统一走 ToolProvider 形态。
|
||||
// Parameters 是 JSON Schema（draft-07 子集即可），调用参数按其校验。
|
||||
|
||||
type SourceKind string
|
||||
|
||||
const (
|
||||
SourceBuiltin SourceKind = "builtin"
|
||||
SourcePlugin SourceKind = "plugin"
|
||||
SourceUser SourceKind = "user"
|
||||
)
|
||||
|
||||
type ToolDesc struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
Parameters json.RawMessage `json:"parameters,omitempty"`
|
||||
Source SourceKind `json:"source"`
|
||||
PluginID string `json:"pluginId,omitempty"`
|
||||
HTTP *HTTPToolSpec `json:"http,omitempty"` // 声明式 HTTP 工具（无代码）
|
||||
}
|
||||
|
||||
// HTTPToolSpec：无代码自定义工具（4.8）。模板变量 {{param.x}} 从调用参数注入。
|
||||
type HTTPToolSpec struct {
|
||||
Method string `json:"method"`
|
||||
URL string `json:"url"`
|
||||
Headers map[string]string `json:"headers,omitempty"`
|
||||
BodyTemplate string `json:"bodyTemplate,omitempty"` // JSON 模板
|
||||
AuthRef string `json:"authRef,omitempty"` // 设置中的密钥引用（settings key）
|
||||
TimeoutMs int `json:"timeoutMs,omitempty"`
|
||||
// ResultPath 从响应 JSON 中裁剪（jq 点路径）；空取整个响应。
|
||||
ResultPath string `json:"resultPath,omitempty"`
|
||||
}
|
||||
|
||||
type ToolCallRequest struct {
|
||||
CallID string `json:"callId"`
|
||||
Name string `json:"name"`
|
||||
Arguments json.RawMessage `json:"arguments,omitempty"`
|
||||
}
|
||||
|
||||
type ToolCallResult struct {
|
||||
CallID string `json:"callId"`
|
||||
Status string `json:"status"` // ok | error
|
||||
Output string `json:"output,omitempty"`
|
||||
Truncated bool `json:"truncated,omitempty"`
|
||||
Artifact *Artifact `json:"artifact,omitempty"` // 超长转工件
|
||||
}
|
||||
+198
@@ -0,0 +1,198 @@
|
||||
// Agent-System-Core 契约的 TypeScript 镜像。
|
||||
// 线格式契约以 Go 类型（camelCase JSON 标签）与 testdata/golden/*.json 黄金样本为准；
|
||||
// 本文件手工镜像同一契约，前端按未知 type/字段静默忽略（前向兼容原则）。
|
||||
|
||||
export type ID = string;
|
||||
|
||||
// ---- 领域模型 ----
|
||||
|
||||
export interface Project {
|
||||
id: ID; name: string; createdAt: string; updatedAt: string;
|
||||
settings?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface Conversation {
|
||||
id: ID; projectId: ID; title: string; profileId?: ID;
|
||||
createdAt: string; updatedAt: string;
|
||||
}
|
||||
|
||||
export type Role = 'user' | 'assistant' | 'system';
|
||||
|
||||
export type PartType =
|
||||
| 'text' | 'thinking' | 'tool_call' | 'tool_result' | 'artifact_ref'
|
||||
| 'hitl' | 'plan' | 'error' | 'card';
|
||||
|
||||
export interface Part {
|
||||
type: PartType;
|
||||
text?: string;
|
||||
toolCall?: { id: string; name: string; arguments?: string; durationMs?: number };
|
||||
toolResult?: { callId: string; status: 'ok' | 'error'; summary?: string; truncated?: boolean };
|
||||
artifact?: { artifactId: ID; name: string; kind?: string };
|
||||
hitl?: { cardId: ID; question: string; resolved: boolean; answer?: string };
|
||||
plan?: PlanSnapshot;
|
||||
card?: { kind: string; data: UINode[] };
|
||||
error?: { code: string; message: string };
|
||||
process?: boolean; // run 终态后折叠为摘要行
|
||||
}
|
||||
|
||||
export interface Message {
|
||||
id: ID; conversationId: ID; runId?: ID; role: Role;
|
||||
parts: Part[]; createdAt: string;
|
||||
}
|
||||
|
||||
export type RunKind = 'conversation' | 'subagent' | 'tool';
|
||||
export type RunStatus =
|
||||
| 'pending' | 'running' | 'waiting_hitl' | 'completed'
|
||||
| 'failed' | 'cancelled' | 'interrupted';
|
||||
export type RunPhase = 'thinking' | 'acting' | 'responding' | 'done';
|
||||
|
||||
export interface Usage {
|
||||
promptTokens: number; completionTokens: number; totalTokens: number;
|
||||
durationMs: number; toolCalls: number;
|
||||
}
|
||||
|
||||
export interface Run {
|
||||
id: ID; parentRunId?: ID; conversationId: ID; projectId: ID;
|
||||
kind: RunKind; profileId?: ID; status: RunStatus; phase?: RunPhase;
|
||||
agentName?: string; createdAt: string; endedAt?: string;
|
||||
usage?: Usage; error?: { code: string; message: string };
|
||||
}
|
||||
|
||||
export interface Artifact {
|
||||
id: ID; projectId: ID; name: string; kind: string; mime?: string;
|
||||
size: number; sourceRun?: ID; createdAt: string; updatedAt: string;
|
||||
}
|
||||
|
||||
export interface PlanSnapshot {
|
||||
planId: ID; title: string;
|
||||
steps: { id: string; text: string; status: 'pending' | 'in_progress' | 'done' | 'skipped'; agentRun?: ID }[];
|
||||
}
|
||||
|
||||
export interface TodoList {
|
||||
conversationId: ID;
|
||||
items: { id: string; text: string; status: 'pending' | 'in_progress' | 'done' }[];
|
||||
}
|
||||
|
||||
// ---- 流式事件 ----
|
||||
|
||||
export type StreamEventType =
|
||||
| 'message.delta' | 'thinking.delta' | 'tool.call' | 'tool.result'
|
||||
| 'run.phase' | 'hitl.request' | 'hitl.resolved' | 'plan.update' | 'todo.update'
|
||||
| 'agent.spawn' | 'agent.progress' | 'agent.result'
|
||||
| 'artifact.created' | 'artifact.updated'
|
||||
| 'run.completed' | 'run.failed' | 'error';
|
||||
|
||||
export interface StreamEvent<P = unknown> {
|
||||
seq: number; runId?: ID; conversationId: ID; ts: string; v: number;
|
||||
type: StreamEventType; payload?: P;
|
||||
}
|
||||
|
||||
// payload 形状（按 type 判别；未知字段忽略）
|
||||
export interface MessageDeltaPayload { index: number; text: string }
|
||||
export interface AgentSpawnPayload { agentRun: ID; name: string; task: string }
|
||||
export interface AgentProgressPayload { agentRun: ID; note?: string; phase?: RunPhase }
|
||||
export interface AgentResultPayload { agentRun: ID; status: RunStatus; summary?: string }
|
||||
export interface HITLResolvedPayload { cardId: ID; answer?: string; kind: 'choice' | 'free' | 'timeout' | 'cancelled' }
|
||||
export interface RunCompletedPayload { usage: Usage }
|
||||
export interface RunFailedPayload { code: string; message: string }
|
||||
|
||||
// ---- HITL ----
|
||||
|
||||
export type HITLKind = 'choice' | 'input' | 'confirm' | 'form';
|
||||
|
||||
export interface HITLChoice {
|
||||
id: string; label: string; description: string; impact: string; recommended?: boolean;
|
||||
}
|
||||
|
||||
export interface HITLCard {
|
||||
id: ID; runId: ID; conversationId: ID; question: string; kind: HITLKind;
|
||||
choices?: HITLChoice[]; allowFreeInput: boolean; freeInputHint?: string;
|
||||
timeoutSec?: number | null; form?: UINode[]; createdAt: string; resolved: boolean;
|
||||
}
|
||||
|
||||
export interface HITLResponse {
|
||||
cardId: ID; choiceId?: string; freeText?: string; formData?: unknown;
|
||||
}
|
||||
|
||||
// ---- UI 词汇 ----
|
||||
|
||||
export type UINodeType =
|
||||
| 'section' | 'list' | 'kv' | 'form' | 'markdown' | 'doc-ref' | 'actions' | 'chart-lite';
|
||||
|
||||
export interface UINode {
|
||||
type: UINodeType;
|
||||
title?: string;
|
||||
items?: string[];
|
||||
kv?: [string, string][];
|
||||
fields?: UIField[];
|
||||
markdown?: string;
|
||||
docId?: ID;
|
||||
actions?: { id: string; label: string; style?: 'primary' | 'default' | 'danger' }[];
|
||||
chart?: { kind: 'bar' | 'line'; labels: string[]; series: number[] };
|
||||
children?: UINode[];
|
||||
}
|
||||
|
||||
export interface UIField {
|
||||
key: string; label: string;
|
||||
type: 'text' | 'textarea' | 'number' | 'boolean' | 'select';
|
||||
options?: string[]; required?: boolean; placeholder?: string; help?: string; default?: string;
|
||||
}
|
||||
|
||||
// ---- 画像 / 设置 ----
|
||||
|
||||
export interface AgentProfile {
|
||||
id: string; name: string; description?: string; builtin?: boolean; source?: string;
|
||||
systemPrompt: string;
|
||||
model: { chat?: string; lightweight?: string; embedding?: string; rerank?: string };
|
||||
tools: { allow: string[]; deny?: string[]; confirm?: string[] };
|
||||
context: {
|
||||
maxHistoryMessages: number; summarizeBeyond?: boolean;
|
||||
memoryBudgetPct?: number; knowledgeBudgetPct?: number; maxToolResultChars?: number;
|
||||
};
|
||||
hitl: { askOnAmbiguity: boolean; timeoutSec?: number | null };
|
||||
budget: { maxTokens?: number | null; maxToolCalls?: number | null; maxTurns?: number | null };
|
||||
}
|
||||
|
||||
export interface SettingDesc {
|
||||
key: string; group: string; label: string; description?: string;
|
||||
type: 'string' | 'number' | 'boolean' | 'enum' | 'secret';
|
||||
default?: unknown; options?: string[];
|
||||
effect: 'hot' | 'new-run' | 'restart';
|
||||
secret?: boolean;
|
||||
}
|
||||
|
||||
// ---- 插件 ----
|
||||
|
||||
export interface PluginManifest {
|
||||
id: string; name: string; version: string; apiVersion: string;
|
||||
requires?: { network?: string[] };
|
||||
provides: {
|
||||
tools?: string[]; workflows?: string[]; intents?: string[];
|
||||
prompts?: string[]; panels?: string[]; cards?: string[]; settings?: string[];
|
||||
};
|
||||
}
|
||||
|
||||
export interface PluginPanel {
|
||||
id: string; title: string; icon?: string; body: UINode[]; refreshTool?: string;
|
||||
}
|
||||
|
||||
// ---- 摄取 / 检索 ----
|
||||
|
||||
export interface ParsedDocument {
|
||||
meta: {
|
||||
filename: string; mime?: string; parser: string; confidence?: number;
|
||||
crossCheck?: { with: string; diffBlocks: number; verdict: 'agree' | 'differ' };
|
||||
parsedAt: string;
|
||||
};
|
||||
blocks: {
|
||||
type: 'heading' | 'para' | 'list' | 'table' | 'code' | 'image-ref';
|
||||
level?: number; text?: string; items?: string[];
|
||||
rows?: string[][]; ref?: string; confidence?: number;
|
||||
}[];
|
||||
warnings?: string[];
|
||||
}
|
||||
|
||||
export interface RetrievalHit {
|
||||
doc: { id: ID; projectId?: ID; source: string; title: string; ref?: string; chunk: string; createdAt: string };
|
||||
score: number; kind: 'fulltext' | 'vector' | 'plugin';
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
package core
|
||||
|
||||
// UI schema 词汇（4.6 原则 3）：设置界面、插件面板、HITL 表单、插件卡片共用
|
||||
// 这套有限词汇，由前端通用渲染器渲染。插件不注入 React 组件；表达不了的高级
|
||||
// 交互走 Core 契约扩展流程新增词汇，而不是开洞。
|
||||
|
||||
type UINodeType string
|
||||
|
||||
const (
|
||||
UISection UINodeType = "section" // 标题 + 子节点
|
||||
UIList UINodeType = "list" // 字符串列表
|
||||
UIKV UINodeType = "kv" // 键值对列表
|
||||
UIForm UINodeType = "form" // 字段表单（HITL form / 设置分区复用）
|
||||
UIMarkdown UINodeType = "markdown"
|
||||
UIDocRef UINodeType = "doc-ref" // 工件引用（右栏查看器打开）
|
||||
UIActions UINodeType = "actions" // 可点动作（发命令/发消息）
|
||||
UIChartLite UINodeType = "chart-lite"
|
||||
)
|
||||
|
||||
type UINode struct {
|
||||
Type UINodeType `json:"type"`
|
||||
Title string `json:"title,omitempty"`
|
||||
Items []string `json:"items,omitempty"` // list
|
||||
KV [][2]string `json:"kv,omitempty"` // kv
|
||||
Fields []UIField `json:"fields,omitempty"` // form
|
||||
Markdown string `json:"markdown,omitempty"`
|
||||
DocID ID `json:"docId,omitempty"` // doc-ref
|
||||
Actions []UIAction `json:"actions,omitempty"`
|
||||
Chart *UIChart `json:"chart,omitempty"`
|
||||
Children []UINode `json:"children,omitempty"` // section
|
||||
}
|
||||
|
||||
type UIField struct {
|
||||
Key string `json:"key"`
|
||||
Label string `json:"label"`
|
||||
Type string `json:"type"` // text | textarea | number | boolean | select
|
||||
Options []string `json:"options,omitempty"`
|
||||
Required bool `json:"required,omitempty"`
|
||||
Placeholder string `json:"placeholder,omitempty"`
|
||||
Help string `json:"help,omitempty"`
|
||||
Default string `json:"default,omitempty"`
|
||||
}
|
||||
|
||||
type UIAction struct {
|
||||
ID string `json:"id"`
|
||||
Label string `json:"label"`
|
||||
Style string `json:"style,omitempty"` // primary | default | danger
|
||||
}
|
||||
|
||||
type UIChart struct {
|
||||
Kind string `json:"kind"` // bar | line
|
||||
Labels []string `json:"labels"`
|
||||
Series []float64 `json:"series"`
|
||||
}
|
||||
Reference in New Issue
Block a user