Files
ssw-ontology/server/mcp_progress.go
T
adminandClaude Code d14440a3ed feat(server): v1.8.0 本体导入 + 分区 + 行级归属 + 认证位 + 结构 diff + 分页 + 进度回报
一次收口 2026-11-06 的九项能力(CHANGELOG 1.5.4 → 1.8.0):

- 自检探针(readiness.go):check_readiness / check_answerable 两个只读探针,把
  「本体里没有」「我没权限看」「模型没抽全」三种空结果原因拆开
- 读路径语义钉死(scope.go):标记与分级的可见范围统一由 Scope 产出,实例分级
  为空时继承类型默认级(fail-closed),列表与详情口径一致
- 行级可改性轴(object_owner.go):归属只收窄不宽于 grants,所有对象写路径统一
  走 canWriteObject,归属查询失败即拒绝
- 公理第 6 类 certification:认证位保护人工策展内容,AI 重摄取不再覆盖已认证条目
- 跨版本结构 diff(schema_diff.go):schema_snapshots 全量快照 + diff 端点,机器
  事实与人工策展分组呈现
- 分区维度 zone:分区绑类型、命中任一即可见,读路径一律带 zone 条件
- 统一分页信封(pagination.go):列表回包统一 count/total/limit/offset/has_more/
  truncated,total 与 items 同源
- MCP 长任务进度(mcp_progress.go):客户端带 progressToken 才走 SSE 进度帧
- 本体 schema 导入(ontology_import.go):Turtle 导入 + 四道 fail-fast 闸门 +
  整事务 + (source, external_id) 幂等 + IRI 往返不变式

MCP 工具清单并入单一注册表(mcp_registry.go),对外声明与实际可调不再各说各话;
工具数 42 → 54(只读 27 / 写入 27),注册表与分发 case 的双向漂移由 AST 单测拦截。

CHANGELOG 编号整理:新「认证位 + 行级归属」条目由 1.6.0 改为 1.5.6(1.6.x 留给
分区与结构 diff),2026-09-20 的 GB/T 规划稿改标「规划稿·未发布」——该能力已并入
v1.5.1,避免与正式发布的版本号重复。

Co-Authored-By: Claude Code <[email protected]>
2026-11-06 13:51:48 +08:00

161 lines
5.3 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 (
"context"
"encoding/json"
"fmt"
"net/http"
"sync"
"time"
"github.com/gin-gonic/gin"
)
// ---------- MCP 进度回报(notifications/progress) ----------
//
// 触发条件:客户端在 tools/call 的 `_meta` 里带 `progressToken`(按 MCP 规范,
// 客户端想要进度时自己带上这个令牌),且 Accept 里有 text/event-stream。
// **没带 → 走原来的单响应路径,行为与从前完全一致**(不进 SSE 模式,不多一次往返)。
//
// 长任务(km_extract / backup_create / recompute_classification / 批量写入)
// 逐条把「阶段名 + 已处理/总数」吐出来:客户端就不会把「还在跑」当成「卡死」,
// 也不会因为自己的超时而重试——重试会叠加负载。
//
// 进度回调挂在 request context 上:MCP 层的进程内子请求(mcpCall / callHandler /
// callConn)继承同一个 ctx,handler 里 `reportProgress(ctx, ...)` 上报即可。
// 没有回调时它是空操作 → REST 直连路径完全不受影响。
// progressReporter 上报一次进度:done / total 是计数,message 是阶段说明。
type progressReporter func(done, total float64, message string)
// progressCtxKey 是 ctx 里进度回调的键(独立类型,避免与别的键撞车)。
type progressCtxKey struct{}
// withProgress 把进度回调挂进 ctx。
func withProgress(ctx context.Context, fn progressReporter) context.Context {
if ctx == nil {
ctx = context.Background()
}
return context.WithValue(ctx, progressCtxKey{}, fn)
}
// progressFrom 取 ctx 里的进度回调;没有则返回 nil。
func progressFrom(ctx context.Context) progressReporter {
if ctx == nil {
return nil
}
// gin.Context 只有在引擎开了 ContextWithFallback 时才把 Value 转发到 request context,
// 这里显式解包,避免调用方传 *gin.Context 时进度丢失(备份/抽取等处就是这么传的)。
if gc, ok := ctx.(*gin.Context); ok {
if gc.Request == nil {
return nil
}
ctx = gc.Request.Context()
}
fn, _ := ctx.Value(progressCtxKey{}).(progressReporter)
return fn
}
// reportProgress 上报一次进度(无回调时空操作)。
func reportProgress(ctx context.Context, done, total float64, message string) {
if fn := progressFrom(ctx); fn != nil {
fn(done, total, message)
}
}
// mcpProgressToken 从 tools/call 的 _meta 里取 progressToken。
// 服务端原样回带这个令牌,客户端才知道某条进度通知对应哪次请求。
func mcpProgressToken(req jsonrpcRequest) (interface{}, bool) {
if req.Method != "tools/call" {
return nil, false
}
meta, _ := req.Params["_meta"].(map[string]interface{})
if meta == nil {
return nil, false
}
tok, ok := meta["progressToken"]
if !ok || tok == nil {
return nil, false
}
return tok, true
}
// mcpProgressMinGap 两次进度写出之间的最小间隔:太密的进度帧会淹没 SSE 流,
// 又不给服务端省下什么(真正耗时的是任务本身,不是写帧)。
const mcpProgressMinGap = 200 * time.Millisecond
// mcpProgressStreamer 把进度写成 SSE 帧(notifications/progress)。
//
// 节流:全库重算可能上万实例,逐条上报会把 SSE 刷爆。
// 这里做「最小间隔」节流——间隔内的上报只记下最新一条(pending),
// 由下一次到期或 finish() 发出。客户端因此看到的是「若干个进度点」而不是噪声流,
// 但最终态一定送达(finish 必发 pending)。
type mcpProgressStreamer struct {
mu sync.Mutex
w http.ResponseWriter
token interface{}
minGap time.Duration
lastSent time.Time
pending *progressFrame
}
type progressFrame struct {
done float64
total float64
message string
}
// newMCPProgressStreamer 建一个进度流写出器。minGap 为两次写出的最小间隔(<=0 表示不限流)。
func newMCPProgressStreamer(w http.ResponseWriter, token interface{}, minGap time.Duration) *mcpProgressStreamer {
return &mcpProgressStreamer{w: w, token: token, minGap: minGap}
}
// report 上报一次进度。并发安全:长任务可能多 goroutine 上报。
func (p *mcpProgressStreamer) report(done, total float64, message string) {
p.mu.Lock()
defer p.mu.Unlock()
now := time.Now()
if p.minGap > 0 && !p.lastSent.IsZero() && now.Sub(p.lastSent) < p.minGap {
p.pending = &progressFrame{done: done, total: total, message: message}
return
}
p.writeLocked(done, total, message)
p.lastSent = now
p.pending = nil
}
// finish 发出最后一次进度(若有被节流压下的),保证客户端看到终态。
func (p *mcpProgressStreamer) finish() {
p.mu.Lock()
defer p.mu.Unlock()
if p.pending == nil {
return
}
p.writeLocked(p.pending.done, p.pending.total, p.pending.message)
p.pending = nil
p.lastSent = time.Now()
}
// writeLocked 写一帧(调用方须持锁)。
func (p *mcpProgressStreamer) writeLocked(done, total float64, message string) {
params := gin.H{"progressToken": p.token, "progress": done}
if total > 0 {
params["total"] = total
}
if message != "" {
params["message"] = message
}
b, err := json.Marshal(map[string]interface{}{
"jsonrpc": "2.0",
"method": "notifications/progress",
"params": params,
})
if err != nil {
return
}
fmt.Fprintf(p.w, "event: message\ndata: %s\n\n", b)
if f, ok := p.w.(http.Flusher); ok {
f.Flush()
}
}