文档权限与撤权

设置规则

后台 SDK 使用 documentAccess / updateDocumentAccess 读取和修改规则，示例见下文；控制台的“文档访问权限”是可选治理入口。规则使用原文档标识，托管分片应填写 documentId（例如 manual-1），不填写分片 id（例如 manual-1:0）。规则同时作用于该知识库所有版本，包含托管、内联和远程知识。

应用管理员也可调用 GET/PUT /v1/apps/{app}/knowledge/{knowledgeId}/documents/{documentId}/access。首次读取返回 revision: 0；更新携带 If-Match: 0，后续使用最新 revision。示例正文：

{"enabled":true,"subjects":["alice"],"tenants":["tenant-a"],"roles":["USER"],"reason":"仅向本项目成员开放"}

非空维度需同时满足，同一维度允许任一值。enabled:false 表示禁止检索。文档自身租户规则始终生效，不因 ACL 留空而开放跨租户文档。没有独立规则时保留原有租户规则。普通用户不能读取或修改规则，修订冲突返回 412，原因不能为空。更细的组织和项目权限仍由业务知识 Provider 在检索中强制校验。

撤权行为

保存访问规则会使当前应用旧会话、历史 Run 文本读取和在途任务失效，返回 KNOWLEDGE_ACCESS_CHANGED。请新建会话重新检索；这能避免旧回答作为历史继续进入模型。该策略会影响应用内未使用该文档的会话，变更前安排业务窗口。管理运行概览、工具账本与审计仍保留。已经发给外部模型的数据不能追回。

检索在筛选规则后才排序和截断，避免被拒绝的文档占用 topK。在途模型响应或流式输出经过后续权限检查，撤权后不再形成成功回答；已经发送的文本片段无法从用户设备撤回。

后台 SDK

var policy = client.documentAccess("manual", "manual-1").toCompletableFuture().join();
client.updateDocumentAccess("manual", "manual-1",
    Map.of("enabled", false, "reason", "项目成员资格撤销"),
    ((Number) policy.get("revision")).longValue()).toCompletableFuture().join();

Kotlin 可对同一方法使用 awaitResult()。应用管理凭据与业务用户凭据应独立保管。

升级与验证

升级自动执行 Flyway V8 新增访问规则表，无须重发知识版本。回退时保留该表并暂停依赖权限限制的应用，旧代码无法执行文档规则。集成测试覆盖管理权限、修订冲突、过滤先于 topK、历史失效、在途撤权与跨版本规则。完整平台构建通过 44 项测试。

文档来源与验证记录

状态：已确认；日期：2026-09-30；来源：DocumentAccess、Runs、Knowledge、平台集成测试；责任人：项目维护者；关联任务：K05。