e5fa063d7d
WeKnora 的 wiki 图谱与页面同表(wiki_pages),旧的库级 DELETE + 灌包在共享真实 知识库上会把其他文档的页面与 agent 手写页一起抹掉(2026-10-08 生产演练现场)。 - 新增 internal/releaseadapter/v071/wiki_scope.go:按 source_refs 判定归属 (全部引用属于本包 = InScope;引用包外知识 = 外来页;无引用 = index/log/ agent 页永不触碰),目标库存在外来页时降级为只替换包内页集,外来页上仅摘掉 本包知识引用,包内库级页不写;包内会写入的页与外来页同 slug 时 fail-closed 拒绝发布且不落任何改动。 - Replace 与 ReplaceWiki(撤权/回滚)共用同一套判定,不再整库清空。 - 作用域以一行日志落盘:release wiki replace scope in_scope=… degraded=… - 测试:单测 7 条(纯函数判定)+ 真库集成 3 条(共享库保护 / slug 冲突拒绝 / 镜像库整库替换不变),集成用例只用带随机后缀的临时知识库并自清理。 - 文档:P6 新增「wiki 通道的归属门禁」,P8 补验收点与镜像前提。
375 lines
14 KiB
Go
375 lines
14 KiB
Go
package v071
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"errors"
|
||
"fmt"
|
||
"log"
|
||
"strings"
|
||
|
||
"github.com/jackc/pgx/v5"
|
||
)
|
||
|
||
// wikiReplaceScope 描述一次库级 wiki 替换的真实作用域,以及它是否被降级。
|
||
//
|
||
// 背景:WeKnora 的 wiki 图谱与页面同表(wiki_pages,节点/边靠 slug + in_links
|
||
// / out_links 表达),旧的"整库 DELETE + 灌包"在**共享真实知识库**上会把其他
|
||
// 文档的页面和 agent 手写页一起抹掉(2026-10-08 生产演练的现场)。
|
||
//
|
||
// 现在的判定规则:
|
||
//
|
||
// - 目标页的 source_refs 形如 "<knowledge_id>|<doc_title>",只有引用的知识
|
||
// 全部属于"本包覆盖的知识集合"时,这一页才归本包管(InScope);
|
||
// - 引用了包外知识的页是外来页(Foreign),永不删除;
|
||
// - 完全没有 source_refs/chunk_refs 的页(index/log、agent 手写页)永不删除;
|
||
// - 外来页与包内页同 slug 时无法安全处理 → 拒绝发布(fail-closed)。
|
||
//
|
||
// 目标库没有外来页时("镜像库 → 原件"前提成立)仍走整库替换,行为与旧实现一致;
|
||
// 只要出现外来页就降级为"只替换包内页集",其余页面一行不动。
|
||
type wikiReplaceScope struct {
|
||
InScope int // 包内知识拥有、会被删除重建的页
|
||
Foreign int // 引用了包外知识的页,永不删除
|
||
ForeignReferencingIn int // 外来页中仍引用本包知识的页(只摘引用,不动正文)
|
||
Untouched int // 无引用来源的页(index/log/agent),永不触碰
|
||
SkippedLibraryPages int // 降级时被跳过的库级页(index/log 不能由部分快照重写)
|
||
Degraded bool // 目标库存在外来页 → 只替换本包页集
|
||
}
|
||
|
||
func (scope wikiReplaceScope) summary() string {
|
||
return fmt.Sprintf("in_scope=%d foreign=%d foreign_ref_stripped=%d untouched=%d skipped_library=%d degraded=%t",
|
||
scope.InScope, scope.Foreign, scope.ForeignReferencingIn, scope.Untouched, scope.SkippedLibraryPages, scope.Degraded)
|
||
}
|
||
|
||
// targetWikiRef 是目标库现存 wiki 页面的归属信息。
|
||
type targetWikiRef struct {
|
||
ID string
|
||
Slug string
|
||
SourceRefs []string
|
||
ChunkRefs []string
|
||
}
|
||
|
||
const targetWikiRefsSQL = `
|
||
SELECT id, slug, COALESCE(source_refs, '[]'::jsonb), COALESCE(chunk_refs, '[]'::jsonb)
|
||
FROM wiki_pages
|
||
WHERE tenant_id = $1 AND knowledge_base_id = $2 AND deleted_at IS NULL`
|
||
|
||
// packageWikiOwners 返回本包 wiki 快照覆盖的知识 id 集合:快照里 knowledges
|
||
// 行的 id,加上所有页面 source_refs 的归属。
|
||
//
|
||
// 镜像库对原件发布时这个集合是整个库(几百上千篇),单文档包发布时它只有一篇
|
||
// ——所以同一套判定既能保住"整库替换"的镜像语义,又能在共享库上自动收敛。
|
||
func packageWikiOwners(snapshot PostgresSnapshot) (map[string]bool, error) {
|
||
owners := map[string]bool{}
|
||
if tablePresent(snapshot, "knowledges") {
|
||
for _, raw := range snapshot.Table("knowledges").Rows {
|
||
var row struct {
|
||
ID string `json:"id"`
|
||
}
|
||
if json.Unmarshal(raw, &row) != nil || !validSearchIdentifier(row.ID) {
|
||
return nil, errors.New("invalid package knowledge row")
|
||
}
|
||
owners[row.ID] = true
|
||
}
|
||
}
|
||
if tablePresent(snapshot, "wiki_pages") {
|
||
for _, raw := range snapshot.Table("wiki_pages").Rows {
|
||
page, err := decodeWikiRow(raw)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for _, reference := range stringList(page["source_refs"]) {
|
||
if owner := referenceOwner(reference); owner != "" {
|
||
owners[owner] = true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
if len(owners) == 0 {
|
||
return nil, errors.New("package wiki snapshot carries no owning knowledge")
|
||
}
|
||
return owners, nil
|
||
}
|
||
|
||
// referenceOwner 取 source_refs 条目的知识 id:"<knowledge_id>|<doc_title>"。
|
||
func referenceOwner(reference string) string {
|
||
if index := strings.Index(reference, "|"); index > 0 {
|
||
reference = reference[:index]
|
||
}
|
||
if !validSearchIdentifier(reference) {
|
||
return ""
|
||
}
|
||
return reference
|
||
}
|
||
|
||
// classifyTargetWikiPages 判定目标库里每一页的归属(纯函数,便于单测)。
|
||
// 返回作用域、将被替换的包内 slug,以及"仍引用本包知识的外来页"。
|
||
func classifyTargetWikiPages(pages []targetWikiRef, owners map[string]bool) (wikiReplaceScope, []string, []targetWikiRef) {
|
||
scope := wikiReplaceScope{}
|
||
inScopeSlugs := make([]string, 0, len(pages))
|
||
foreignReferencingIn := make([]targetWikiRef, 0)
|
||
for _, page := range pages {
|
||
if page.Slug == "" || (!validSearchIdentifier(page.ID)) {
|
||
// 结构异常的页按外来页处理:不删、不改。
|
||
scope.Foreign++
|
||
continue
|
||
}
|
||
if len(page.SourceRefs) == 0 && len(page.ChunkRefs) == 0 {
|
||
scope.Untouched++
|
||
continue
|
||
}
|
||
if len(page.SourceRefs) == 0 {
|
||
// 只有 chunk_refs(chunk UUID 不带知识 id)时无法归属 → 按外来页处理。
|
||
scope.Foreign++
|
||
continue
|
||
}
|
||
pageOwners := make([]string, 0, len(page.SourceRefs))
|
||
mine, malformed := 0, false
|
||
for _, reference := range page.SourceRefs {
|
||
owner := referenceOwner(reference)
|
||
if owner == "" {
|
||
malformed = true
|
||
break
|
||
}
|
||
pageOwners = append(pageOwners, owner)
|
||
if owners[owner] {
|
||
mine++
|
||
}
|
||
}
|
||
if malformed {
|
||
scope.Foreign++
|
||
continue
|
||
}
|
||
if mine == len(pageOwners) {
|
||
scope.InScope++
|
||
inScopeSlugs = append(inScopeSlugs, page.Slug)
|
||
continue
|
||
}
|
||
scope.Foreign++
|
||
if mine > 0 {
|
||
scope.ForeignReferencingIn++
|
||
foreignReferencingIn = append(foreignReferencingIn, page)
|
||
}
|
||
}
|
||
scope.Degraded = scope.Foreign > 0
|
||
return scope, inScopeSlugs, foreignReferencingIn
|
||
}
|
||
|
||
// replaceWiki 是发布 / 撤权 / 回滚共用的 wiki 通道:先判定归属,再按作用域写入。
|
||
// 必须在已经持有 knowledge base 维度 advisory lock 的事务里调用。
|
||
func (importer *PostgresImporter) replaceWiki(ctx context.Context, tx pgx.Tx, identity PostgresIdentity, snapshot PostgresSnapshot) (wikiReplaceScope, error) {
|
||
tables, hasWiki := wikiSnapshotRows(snapshot)
|
||
if !hasWiki {
|
||
// 老包 / 未启用 wiki 的库:不动目标 wiki。
|
||
return wikiReplaceScope{}, nil
|
||
}
|
||
pageRows := snapshot.Table("wiki_pages").Rows
|
||
folderRows := snapshot.Table("wiki_folders").Rows
|
||
bundleSlugs := make([]string, 0, len(pageRows))
|
||
for _, raw := range pageRows {
|
||
var row struct {
|
||
Slug string `json:"slug"`
|
||
}
|
||
if json.Unmarshal(raw, &row) != nil || row.Slug == "" {
|
||
return wikiReplaceScope{}, errors.New("invalid package wiki page slug")
|
||
}
|
||
bundleSlugs = append(bundleSlugs, row.Slug)
|
||
}
|
||
folderIDs := make([]string, 0, len(folderRows))
|
||
for _, raw := range folderRows {
|
||
var row struct {
|
||
ID string `json:"id"`
|
||
}
|
||
if json.Unmarshal(raw, &row) != nil || row.ID == "" {
|
||
return wikiReplaceScope{}, errors.New("invalid package wiki folder id")
|
||
}
|
||
folderIDs = append(folderIDs, row.ID)
|
||
}
|
||
owners, err := packageWikiOwners(snapshot)
|
||
if err != nil {
|
||
return wikiReplaceScope{}, err
|
||
}
|
||
targetPages, err := loadTargetWikiRefs(ctx, tx, identity)
|
||
if err != nil {
|
||
return wikiReplaceScope{}, err
|
||
}
|
||
scope, inScopeSlugs, foreignReferencingIn := classifyTargetWikiPages(targetPages, owners)
|
||
// 外来页与包内会写入的页同 slug:两边正文不同、又都不该被覆盖 → 拒绝发布。
|
||
bundleRefBearing := make(map[string]bool, len(bundleSlugs))
|
||
for _, raw := range pageRows {
|
||
page, err := decodeWikiRow(raw)
|
||
if err != nil {
|
||
return scope, err
|
||
}
|
||
if len(stringList(page["source_refs"])) == 0 && len(stringList(page["chunk_refs"])) == 0 {
|
||
continue
|
||
}
|
||
slug, _ := page["slug"].(string)
|
||
bundleRefBearing[slug] = true
|
||
}
|
||
if slug, collided := wikiSlugCollision(targetPages, inScopeSlugs, bundleRefBearing); collided {
|
||
return scope, fmt.Errorf("目标知识库的 wiki 页 %s 由其他文档或人工维护,发布包无法安全覆盖,已拒绝发布(%s)", slug, scope.summary())
|
||
}
|
||
if scope.Degraded {
|
||
// 降级:只摘掉外来页上对本包知识的引用(正文不动,避免破坏库级合成结果)。
|
||
if err := stripForeignWikiRefs(ctx, tx, identity, foreignReferencingIn, owners, chunkIDSet(snapshot)); err != nil {
|
||
return scope, err
|
||
}
|
||
if len(inScopeSlugs) > 0 {
|
||
if _, err := tx.Exec(ctx, `
|
||
DELETE FROM wiki_pages
|
||
WHERE tenant_id = $1 AND knowledge_base_id = $2 AND slug = ANY($3::text[])
|
||
`, identity.TenantID, identity.KnowledgeBaseID, inScopeSlugs); err != nil {
|
||
return scope, errors.New("clear in-scope target wiki pages")
|
||
}
|
||
}
|
||
if len(folderIDs) > 0 {
|
||
if _, err := tx.Exec(ctx, `
|
||
DELETE FROM wiki_folders
|
||
WHERE tenant_id = $1 AND knowledge_base_id = $2 AND id = ANY($3::text[])
|
||
`, identity.TenantID, identity.KnowledgeBaseID, folderIDs); err != nil {
|
||
return scope, errors.New("clear package target wiki folders")
|
||
}
|
||
}
|
||
filteredPages := make([]json.RawMessage, 0, len(pageRows))
|
||
for _, raw := range pageRows {
|
||
page, err := decodeWikiRow(raw)
|
||
if err != nil {
|
||
return scope, err
|
||
}
|
||
if len(stringList(page["source_refs"])) == 0 && len(stringList(page["chunk_refs"])) == 0 {
|
||
// index/log 是库级聚合页,部分快照重写会毁掉目标库自己的聚合。
|
||
scope.SkippedLibraryPages++
|
||
continue
|
||
}
|
||
filteredPages = append(filteredPages, raw)
|
||
}
|
||
if err := insertSnapshotRows(ctx, tx, newTableSnapshot("wiki_folders", folderRows)); err != nil {
|
||
return scope, err
|
||
}
|
||
if err := insertSnapshotRows(ctx, tx, newTableSnapshot("wiki_pages", filteredPages)); err != nil {
|
||
return scope, err
|
||
}
|
||
log.Printf("release wiki replace scope %s (只替换包内页集,目标库其余页面未改动)", scope.summary())
|
||
return scope, nil
|
||
}
|
||
// 无外来页:镜像库对原件的正常路径,整库替换(与旧行为一致),
|
||
// 但保留"无引用来源且不在包内"的页面(agent 手写页等)。
|
||
if _, err := tx.Exec(ctx, `
|
||
DELETE FROM wiki_pages
|
||
WHERE tenant_id = $1 AND knowledge_base_id = $2
|
||
AND ((COALESCE(source_refs, '[]'::jsonb) <> '[]'::jsonb) OR (COALESCE(chunk_refs, '[]'::jsonb) <> '[]'::jsonb)
|
||
OR slug = ANY($3::text[]))
|
||
`, identity.TenantID, identity.KnowledgeBaseID, bundleSlugs); err != nil {
|
||
return scope, errors.New("clear target wiki pages")
|
||
}
|
||
if _, err := tx.Exec(ctx, `
|
||
DELETE FROM wiki_folders AS folder
|
||
WHERE folder.tenant_id = $1 AND folder.knowledge_base_id = $2
|
||
AND (folder.id = ANY($3::text[])
|
||
OR NOT EXISTS (SELECT 1 FROM wiki_pages AS page
|
||
WHERE page.knowledge_base_id = folder.knowledge_base_id
|
||
AND page.folder_id = folder.id AND page.deleted_at IS NULL))
|
||
`, identity.TenantID, identity.KnowledgeBaseID, folderIDs); err != nil {
|
||
return scope, errors.New("clear target wiki folders")
|
||
}
|
||
for _, table := range tables {
|
||
if err := insertSnapshotRows(ctx, tx, table); err != nil {
|
||
return scope, err
|
||
}
|
||
}
|
||
log.Printf("release wiki replace scope %s", scope.summary())
|
||
return scope, nil
|
||
}
|
||
|
||
func loadTargetWikiRefs(ctx context.Context, tx pgx.Tx, identity PostgresIdentity) ([]targetWikiRef, error) {
|
||
rows, err := tx.Query(ctx, targetWikiRefsSQL, identity.TenantID, identity.KnowledgeBaseID)
|
||
if err != nil {
|
||
return nil, errors.New("read target wiki page ownership")
|
||
}
|
||
defer rows.Close()
|
||
pages := make([]targetWikiRef, 0)
|
||
for rows.Next() {
|
||
var page targetWikiRef
|
||
var sourceRefs, chunkRefs []byte
|
||
if err := rows.Scan(&page.ID, &page.Slug, &sourceRefs, &chunkRefs); err != nil {
|
||
return nil, errors.New("read target wiki page ownership")
|
||
}
|
||
if json.Unmarshal(sourceRefs, &page.SourceRefs) != nil || json.Unmarshal(chunkRefs, &page.ChunkRefs) != nil {
|
||
// 非数组结构(异常行)按"无法归属"处理:不删、不改。
|
||
page.SourceRefs = nil
|
||
page.ChunkRefs = []string{""}
|
||
}
|
||
pages = append(pages, page)
|
||
}
|
||
if rows.Err() != nil {
|
||
return nil, errors.New("read target wiki page ownership")
|
||
}
|
||
return pages, nil
|
||
}
|
||
|
||
// stripForeignWikiRefs 在外来页上只摘掉本包知识的引用,正文一行不改。
|
||
func stripForeignWikiRefs(ctx context.Context, tx pgx.Tx, identity PostgresIdentity, pages []targetWikiRef, owners map[string]bool, removedChunks map[string]bool) error {
|
||
for _, page := range pages {
|
||
keptSources := make([]string, 0, len(page.SourceRefs))
|
||
for _, reference := range page.SourceRefs {
|
||
if !owners[referenceOwner(reference)] {
|
||
keptSources = append(keptSources, reference)
|
||
}
|
||
}
|
||
keptChunks := make([]string, 0, len(page.ChunkRefs))
|
||
for _, reference := range page.ChunkRefs {
|
||
if !removedChunks[reference] {
|
||
keptChunks = append(keptChunks, reference)
|
||
}
|
||
}
|
||
if len(keptSources) == len(page.SourceRefs) && len(keptChunks) == len(page.ChunkRefs) {
|
||
continue
|
||
}
|
||
encodedSources, _ := json.Marshal(keptSources)
|
||
encodedChunks, _ := json.Marshal(keptChunks)
|
||
if _, err := tx.Exec(ctx, `
|
||
UPDATE wiki_pages SET source_refs = $3::jsonb, chunk_refs = $4::jsonb, updated_at = NOW()
|
||
WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
|
||
`, page.ID, identity.TenantID, string(encodedSources), string(encodedChunks)); err != nil {
|
||
return errors.New("strip package wiki references from shared target page")
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// wikiSlugCollision 找"包内会写入的页 slug 已被目标库外来页占用"的第一个 slug。
|
||
// 命中时两侧正文不同、又都不该被覆盖,只能拒绝发布(fail-closed)。
|
||
//
|
||
// bundleRefBearing 是包内**携带引用**的页 slug:只有这些页在降级路径上会真正
|
||
// 写入;包内的库级页(index/log)会被跳过,因此不构成占用。
|
||
func wikiSlugCollision(pages []targetWikiRef, inScopeSlugs []string, bundleRefBearing map[string]bool) (string, bool) {
|
||
inScope := make(map[string]bool, len(inScopeSlugs))
|
||
for _, slug := range inScopeSlugs {
|
||
inScope[slug] = true
|
||
}
|
||
for _, page := range pages {
|
||
if !bundleRefBearing[page.Slug] || inScope[page.Slug] {
|
||
continue
|
||
}
|
||
return page.Slug, true
|
||
}
|
||
return "", false
|
||
}
|
||
|
||
func chunkIDSet(snapshot PostgresSnapshot) map[string]bool {
|
||
ids := map[string]bool{}
|
||
if !tablePresent(snapshot, "chunks") {
|
||
return ids
|
||
}
|
||
for _, raw := range snapshot.Table("chunks").Rows {
|
||
var row struct {
|
||
ID string `json:"id"`
|
||
}
|
||
if json.Unmarshal(raw, &row) == nil && row.ID != "" {
|
||
ids[row.ID] = true
|
||
}
|
||
}
|
||
return ids
|
||
}
|