一次收口 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]>
161 lines
5.3 KiB
Go
161 lines
5.3 KiB
Go
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()
|
||
}
|
||
}
|