fix(dsh): 角色工具白名单先分区再 restrict,实现文档迁入插件目录

缺陷:dsh-ops 把 ops_* 注册在 agent 自己的作用域层
(inheritable:false),全局层名册里没有这些名字。角色白名单
一旦命中 ops_*,首次 restrict 就抛错,整份策略应用失败,成员
工具面完全不设防——四个专精角色此前实际没拿到过白名单。

修复:白名单改走「先分区、再 restrict」两步——作用域层名字由
分区器摘除交策略层,全局层一次性交 restrict。三条路径(初始
注入 / 降级重试 / rebind 重放)共用同一个分区器,行为逐字一致。

两条刻意设计:
- 白名单全被分区掉时 allow 集合为空,必须显式发 {"allow":[]}
  (fail closed;省略即不限制,会静默放开全部工具)
- 未向任何提供方注册的名字报 not visible yet and not
  restrictable,不得误报成「未注册」——注册时机问题不能把
  将来能用的名字从白名单里丢掉

真机验收(宿主重启后取证):目标角色 doc-writer 走
applied in one pass (allow=35),白名单 43 项 = 4 作用域层 +
4 不可解析 + 35 进限制,与 diag 逐行自洽;成员工具面
qq_*/workbuddy_*/ImageGen 全部不可见;persona 逐字注入。

能力边界报备(未修,文档已写明):ops_discover_tools 可激活
写侧作用域工具绕过白名单——白名单是初始可见面裁剪,不是安全
边界;要封锁写权限须连它一起排除。

文档:实现说明从 docs/环境与部署 迁入插件自带 docs/(内容全部
是本插件内部实现,按知识各归其位原则);AGENTS.md 与 docs
索引同步改指向,全仓 doc-links 与 mermaid 门禁绿。
This commit is contained in:
2026-11-16 16:42:59 +08:00
parent 9e538d2809
commit 1b740e07b3
6 changed files with 337 additions and 52 deletions
@@ -21,6 +21,8 @@ import {
expandToolFilter,
isUnrestrictableToolName,
parseUnrestrictableToolNames,
partitionToolFilter,
restrictableNameSet,
sumSchemaChars,
} from './policy.js'
import { resolveRoleRoute } from './route.js'
@@ -56,8 +58,25 @@ function visibleToolSchemas(ctx, agent) {
}
}
/** Serialized-schema length per tool name, for budget diagnostics. */
function schemaCharsByName(schemas) {
/**
* The names one agent's scope can see, for the partition's unresolved-vs-scope-local
* distinction. Undefined (not an empty set) when the registry cannot answer, so
* a failure never looks like "nothing is visible".
* @param tools - the tools service.
* @param agent - the viewing agent scope.
* @returns the visible names, or undefined.
*/
function visibleNameSet(tools, agent) {
try {
const view = typeof tools?.view === 'function' ? tools.view(agent) : undefined
const visible = view?.visible
return visible instanceof Map ? new Set(visible.keys()) : undefined
} catch {
return undefined
}
}
/** Serialized-schema length per tool name, for budget diagnostics. */function schemaCharsByName(schemas) {
const map = {}
for (const schema of schemas) {
if (schema === null || typeof schema !== 'object' || typeof schema.name !== 'string') continue
@@ -814,8 +833,17 @@ export function createRoleTool(options) {
}
const tools = child?.ctx?.tools
if (composition.toolFilter !== undefined && typeof tools?.restrict === 'function') {
// Partition against the CHILD's own view: the caller already partitioned
// against the delegating agent's view, but the two scopes need not expose
// the same restrictable set. Doing it here too means the normal path never
// depends on catching an exception.
const partition = partitionToolFilter(composition.toolFilter, {
restrictableNames: restrictableNameSet(tools, child),
visibleNames: visibleNameSet(tools, child),
})
const planned = partition.filter ?? composition.toolFilter
try {
tools.restrict(composition.toolFilter)
tools.restrict(planned)
} catch (error) {
// A tool registered on the delegating agent's own layer is visible to the
// parent but unknown to the child's scope. Drop exactly those names and
@@ -824,7 +852,7 @@ export function createRoleTool(options) {
// original failure is kept and surfaces from `startDelegation`.
if (composition.onMissing === 'error') throw error
const names = parseUnrestrictableToolNames(error)
const next = names.length === 0 ? undefined : dropToolFilterNames(composition.toolFilter, names)
const next = names.length === 0 ? undefined : dropToolFilterNames(planned, names)
if (next === undefined) throw error
tools.restrict(next)
ctx.logger?.warn?.(`[${LOG_PREFIX}] the child's scope cannot restrict ${names.map((name) => `"${name}"`).join(', ')}; they were dropped from the role's tool policy`)
@@ -965,6 +993,31 @@ export function createRoleTool(options) {
warnings.push(message)
ctx.logger?.warn?.(`[${LOG_PREFIX}] ${message}`)
}
// Split off the names `restrict()` cannot accept BEFORE handing the
// filter to the child, so the policy lands on the first attempt instead
// of degrading through a thrown exception. A scope-local name (the
// `ops_*` family is registered on the agent's own layer) stays visible
// regardless, so dropping it from `allow` costs nothing; a denied one
// cannot be enforced at all and is reported instead of silently kept.
const partition = partitionToolFilter(toolFilter, {
restrictableNames: restrictableNameSet(ctx.tools, agent),
visibleNames,
})
toolFilter = partition.filter
if (partition.scopeLocal.length > 0) {
ctx.logger?.info?.(`[${LOG_PREFIX}] role "${role.id}": ${partition.scopeLocal.length} scope-local tool(s) omitted from the enforced policy (they stay visible either way): ${partition.scopeLocal.join(', ')}`)
}
if (partition.unresolved.length > 0) {
// Wording matters: at composition time a lazily registered tool and a
// typo are indistinguishable, so this reports what was observed (not
// visible yet) rather than what would be a role-file bug.
ctx.logger?.info?.(`[${LOG_PREFIX}] role "${role.id}": ${partition.unresolved.length} name(s) not visible yet at composition time: ${partition.unresolved.join(', ')}`)
}
if (partition.unenforceable.length > 0) {
const message = `${ERROR_PREFIX} role "${role.id}" denies tool(s) it cannot restrict; they stay visible to the child: ${partition.unenforceable.join(', ')}`
warnings.push(message)
ctx.logger?.warn?.(`[${LOG_PREFIX}] ${message}`)
}
if (toolFilter?.allow?.length === 0) {
const message = `${ERROR_PREFIX} role "${role.id}" allows no currently available tool; the child will see an empty tool set`
warnings.push(message)
@@ -1277,6 +1330,17 @@ export function createRoleListTool(options) {
lines.push(` budget: ${sumSchemaChars(chars, filter.allow)} of ${totalVisible} visible tool-schema chars`)
}
if (expansion.dropped.length > 0) lines.push(` unavailable: ${expansion.dropped.join(', ')}`)
// What the child's own scope can enforce differs from what this scope
// can see: scope-local tools are visible here but not restrictable
// there. Show the difference so a role file is not read as binding
// names it structurally cannot bind.
const partition = partitionToolFilter(expansion.filter, {
restrictableNames: agent === undefined ? undefined : restrictableNameSet(ctx.tools, agent),
visibleNames: new Set(Object.keys(chars)),
})
if (partition.scopeLocal.length > 0) lines.push(` not enforceable (scope-local, stays visible): ${partition.scopeLocal.join(', ')}`)
if (partition.unresolved.length > 0) lines.push(` not visible at composition time (scope-local or not yet registered): ${partition.unresolved.join(', ')}`)
if (partition.unenforceable.length > 0) lines.push(` deny not enforceable (stays visible): ${partition.unenforceable.join(', ')}`)
}
}
if (diagnostics.length > 0) {