Files
knowledge-governance/internal/releaseadapter/v071/wiki_scope.go
T
姚章浩 e5fa063d7d feat(release): wiki 通道按归属判定替换,共享知识库不再被整库清空
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 补验收点与镜像前提。
2026-10-08 19:06:36 +08:00

375 lines
14 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 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
}