Files
ssw-ontology/server/models.go
T
admin 5b67ed991a feat(mcp): 内置提示词席位 + 工具语义标注 + get_usage_guide 场景指南工具
把「怎么用这套本体」从用户侧 skill 前移为服务端能力,任何接入 MCP 的
客户端开箱即用,无需安装 skill:

- initialize 下发 instructions(1.6KB,起步速查:开工三步/查询/写入/
  建模/分级/权限/知识库/铁律;控制在 2KB 内防客户端截断)
- tools/list 每个工具带 title + ToolAnnotations(readOnly/destructive/
  idempotent/openWorld),指针字段确保显式 false 不被 omitempty 吞掉;
  39→40 个工具全覆盖,4 个破坏性工具可被客户端识别
- tools/list 补 ttlMs/cacheScope,清单可缓存 5 分钟
- 新增 get_usage_guide:不传参返回铁律+场景路由总览,传 scenario 返回
  该场景完整 SOP(query/ingest/modeling/classification/access/
  knowledge/backup/gotchas)。静态内容不触库,与 ssw-ontology-ops
  skill 同源——skill 定位转为深度参考

回归测试 4 个用例守护:标注覆盖率、instructions 长度上限、清单顺序
稳定性、指南场景键全覆盖与容错。实测确认 WorkBuddy 不消费协议层
instructions/annotations(asar 逆向证据),故指南必须走工具通道——
本工具为普通 tool call,全客户端有效。
2026-10-15 08:31:30 +08:00

239 lines
12 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package main
import "time"
// ============ 本体语义层模型(参考 Palantir Ontology) ============
// ObjectType 对象类型:现实世界实体/事件的 Schema 定义。
type ObjectType struct {
ID int64 `json:"id"`
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Icon string `json:"icon"`
Group string `json:"group"`
// IRI 全局标识(GB/T 48000.3-2026):命名空间 + "#" + api_name,创建即固化。
IRI string `json:"iri,omitempty"`
TitleProperty string `json:"title_property"` // 主标题对应 property.api_name
SubtitleProperty string `json:"subtitle_property"` // 副标题对应 property.api_name
Color string `json:"color"` // UI 标识色
PrimaryKey string `json:"primary_key"` // 主键字段名,默认 'pk'
// 数据分级(2026-09-07):Property 为空 = 该类型不启用分级
ClassificationProperty string `json:"classification_property,omitempty"`
ClassificationLevels []string `json:"classification_levels,omitempty"`
ClassificationDefault string `json:"classification_default,omitempty"`
// Axioms 公理声明(GB/T 48000.3-2026 §8.2):空=nil 不回显。
Axioms *typeAxioms `json:"axioms,omitempty"`
// DisplayNameLang 多语标签(GB/T 48000.3-2026 附录 A.1.3):{"zh-CN":"…","en":"…"};
// 空=nil 不回显,读路径与 Turtle 导出回退单语 DisplayName。
DisplayNameLang map[string]string `json:"display_name_lang,omitempty"`
// ParentID 父类型 ID(不序列化——读路径以 ParentAPIName 形式回显)。
ParentID *int64 `json:"-"`
// ParentAPIName 父类型 api_name(回显专用;非空=已声明 SubclassOf)。
ParentAPIName string `json:"parent_api_name,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Properties []Property `json:"properties,omitempty"`
}
// Property 属性:对象类型的特征字段。
type Property struct {
ID int64 `json:"id"`
ObjectID int64 `json:"object_type_id"`
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
DataType string `json:"data_type"` // string/integer/number/boolean/date/datetime/enum/json/text/uri
Required bool `json:"required"`
EnumValues []string `json:"enum_values,omitempty"`
Description string `json:"description"`
Format string `json:"format"` // 日期格式 / 数字精度 / 字符串正则
DefaultValue interface{} `json:"default_value"` // 默认值(任意 JSON)
Indexable bool `json:"indexable"` // 关键字检索
VectorIndex bool `json:"vector_index"` // 向量索引(语义检索)
BackingColumn string `json:"backing_column"` // 物化层用
// 字段级敏感度(2026-09-07):值取自所属类型的 classification_levels 词汇,
// 高于主体可见上限时该字段对主体 redact(与 FieldPolicy 并行生效)
Sensitivity string `json:"sensitivity,omitempty"`
// IRI 全局标识(GB/T 48000.3-2026):按属性名全局拼接,同名属性跨类型共享 IRI
IRI string `json:"iri,omitempty"`
// DisplayNameLang 多语标签(GB/T 48000.3-2026 附录 A.1.3);空=nil 不回显,回退 DisplayName。
DisplayNameLang map[string]string `json:"display_name_lang,omitempty"`
// Inherited 继承属性标记(计算字段,读路径添加;不存库,不影响 INSERT/SELECT)。
Inherited bool `json:"inherited,omitempty"`
}
// LinkType 链接类型:两个对象类型之间的关系边。
type LinkType struct {
ID int64 `json:"id"`
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
SourceType string `json:"source_type"`
TargetType string `json:"target_type"`
Cardinality string `json:"cardinality"` // one_to_many / many_to_many / one_to_one
Description string `json:"description"`
Directional bool `json:"directional"` // 是否单向(默认 false = 双向)
SourceProperty string `json:"source_property"` // 源端 key 字段(默认 pk)
TargetProperty string `json:"target_property"` // 目标端 key 字段(默认 pk)
// IRI 全局标识(GB/T 48000.3-2026):命名空间 + "#" + api_name,创建即固化
IRI string `json:"iri,omitempty"`
// DisplayNameLang 多语标签(GB/T 48000.3-2026 附录 A.1.3);空=nil 不回显,回退 DisplayName。
DisplayNameLang map[string]string `json:"display_name_lang,omitempty"`
}
// ActionType 动作类型(动力层):对对象/属性/链接进行修改的预定义操作。
// 完整契约(Palantir Ontology 对标 2026-08-24):
// - Params: form schema 数组,每条 {name, type, required, default, enum, validation, description}
// - SubmissionCriteria: 执行前校验(object_status_in / required_grant 等)
// - SideEffects: 执行后触发(webhooks / cascade_actions / notifications)
// - ImplFunctionID: FBA —— 非空时整条 Action 由 Function 实现
// - ReturnType: 返回类型(string / object_ref / array 等)
type ActionType struct {
ID int64 `json:"id"`
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Params string `json:"params"` // form schema(JSON 字符串)
SubmissionCriteria string `json:"submission_criteria"` // JSON 字符串
SideEffects string `json:"side_effects"` // JSON 字符串
ImplFunctionID *int64 `json:"impl_function_id"` // FBA;可空
ImplFunctionName string `json:"impl_function_name"` // JOIN 出来,便于 UI 显示
ReturnType string `json:"return_type"`
WhenToSuggest []string `json:"when_to_suggest"`
LLMToolDescription string `json:"llm_tool_description"`
}
// Object 对象实例:对象类型的一个具体实体(数字孪生中的一个节点)。
type Object struct {
ID int64 `json:"id"`
ObjectID int64 `json:"object_type_id"`
TypeAPIName string `json:"type"` // 冗余存储,便于连接器按类型查询
PK string `json:"pk"` // 该实例在所属类型下的唯一主键
Properties map[string]interface{} `json:"properties"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
// 实例治理(2026-09-05):软删除墓碑 + 别名归并
Deleted bool `json:"deleted"`
SameAs string `json:"same_as"` // 非空 = 该实例是重复实体,canonical 指向同类型另一个 pk
// 生效分级(2026-09-07):空 = 未分级(视为最低,对任何主体可见)
Classification string `json:"classification,omitempty"`
}
// Link 链接实例:两个对象实例之间的具体关系。
type Link struct {
ID int64 `json:"id"`
LinkType string `json:"type"` // link type api_name
SourceType string `json:"source_type"`
SourcePK string `json:"source_pk"`
TargetType string `json:"target_type"`
TargetPK string `json:"target_pk"`
Properties map[string]interface{} `json:"properties,omitempty"` // 边属性(任职起止时间等)
CreatedAt time.Time `json:"created_at"`
}
// ============ AI 摄取相关 ============
// Ingestion AI 摄取任务记录。
type Ingestion struct {
ID int64 `json:"id"`
Title string `json:"title"`
RawText string `json:"raw_text"`
Directive string `json:"directive"` // 用户的更新要求
Mode string `json:"mode"` // auto(直接应用) / review(仅建议)
Status string `json:"status"` // pending / applied / failed / reviewed
Provider string `json:"provider"` // openai / heuristic
ResultJSON string `json:"result_json"`
Summary string `json:"summary"`
CreatedAt time.Time `json:"created_at"`
AppliedAt *time.Time `json:"applied_at"`
}
// AISuggestion AI 抽取结果结构(与后端抽取提示词对齐)。
type AISuggestion struct {
ObjectTypes []AISuggestedType `json:"object_types"`
LinkTypes []AISuggestedLink `json:"link_types"`
ActionTypes []AISuggestedAction `json:"action_types"`
Objects []AISuggestedObject `json:"objects"`
Links []AISuggestedLinkInst `json:"links"`
Summary string `json:"summary"`
}
type AISuggestedType struct {
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Group string `json:"group"`
Icon string `json:"icon"`
Properties []AISuggestedProp `json:"properties"`
}
type AISuggestedProp struct {
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
DataType string `json:"data_type"`
Required bool `json:"required"`
EnumValues []string `json:"enum_values"`
Description string `json:"description"`
}
type AISuggestedLink struct {
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
SourceType string `json:"source_type"`
TargetType string `json:"target_type"`
Cardinality string `json:"cardinality"`
Description string `json:"description"`
}
type AISuggestedAction struct {
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Params string `json:"params"`
}
type AISuggestedObject struct {
Type string `json:"type"`
PK string `json:"pk"`
Properties map[string]interface{} `json:"properties"`
}
type AISuggestedLinkInst struct {
Type string `json:"type"`
SourceType string `json:"source_type"`
SourcePK string `json:"source_pk"`
TargetType string `json:"target_type"`
TargetPK string `json:"target_pk"`
}
// ============ 连接器 / MCP ============
// ConnectorObjectType 连接器精简视图:应用只关心类型名+属性。
type ConnectorObjectType struct {
APIName string `json:"api_name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
// IRI 全局标识(GB/T 48000.3-2026):连接器/MCP 读路径同样回显
IRI string `json:"iri,omitempty"`
Properties []Property `json:"properties"`
}
// MCPTool MCP 工具清单中的单个工具描述(供 WorkBuddy 等接入)。
type MCPTool struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description"`
InputSchema map[string]interface{} `json:"inputSchema"`
Annotations *MCPToolAnnotations `json:"annotations,omitempty"`
}
// MCPToolAnnotations 工具行为提示(spec ToolAnnotations,含 legacy 同名 hints)。
// 指针字段让 omitempty 能区分"未标注"与"显式 false",避免语义丢失。
//
// 注意:规范明确规定这些仅为 hints,客户端 MAY 据此自动放行只读 / 对破坏性操作二次确认,
// 但 MUST 视其为不可信输入,不得单独作为安全判据(服务端自身的鉴权才是边界)。
type MCPToolAnnotations struct {
// ReadOnlyHint true = 不修改环境
ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`
// DestructiveHint true = 可能执行破坏性更新;false = 仅增量更新
DestructiveHint *bool `json:"destructiveHint,omitempty"`
// IdempotentHint true = 同参数重复调用无额外副作用
IdempotentHint *bool `json:"idempotentHint,omitempty"`
// OpenWorldHint true = 与外部开放实体交互;false = 封闭世界
OpenWorldHint *bool `json:"openWorldHint,omitempty"`
}