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:
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user