作用域(scope)
按项目 / 目录决定技能与规则是否生效。默认全域生效,只有写了作用域配置才出现局部生效。
status/ 裸list/policy list/skills list只读;list的 add / exclude / remove / default / reset 与policy/skills写命令复用同一套预览与确认,预览会展示完整规则 / 档案内容。
用途与场景
- 全局装了 CLI、技能与规则,但只想在指定项目 / 父目录生效,或排除某些项目 / 目录
- 排查「为什么这个目录生效 / 不生效」:看命中的配置文件与规则
- 团队自建项目层配置时,同样按就近覆盖参与判定
常用命令
toolkit scope # 状态优先向导:看状态 / 加白黑名单 / 管条目 / 默认值 / 高级规则 / 技能矩阵
toolkit scope wizard # 显式进入交互向导(非 TTY 按无交互退出码结束)
toolkit scope status # 当前目录的判定与原因
toolkit scope status --skill fxri-plan-review # 按技能级规则判定单个技能
toolkit scope status --skills # 列出包内与已安装外部技能在该目录的生效结论
toolkit scope status --skills --at ~/work/repo # 以指定目录为判定起点(不改进程 cwd)
toolkit scope status --format json # 给 AI / 脚本消费
toolkit scope list # 规则、来源与优先级
toolkit scope policy list # 列出策略、来源层与当前命中结果
toolkit scope policy add --paths ~/work --mode allowlist --allow fxri-plan-review # 新增策略
toolkit scope policy remove --id policy-xxx # 按稳定 id 移除
toolkit scope policy reset --paths ~/work --dry-run # 按路径批量清除(预演)
toolkit scope skills list # 技能档案与技能维度策略
toolkit scope skills allow fxri-plan-review --paths ~/work # 只允许列出的技能
toolkit scope skills deny fxri-code-encoding --paths ~/work # 排除列出的技能
toolkit scope skills profile front --allow "fxri-*" # 写入技能档案
toolkit scope list add ~/work # 加入白名单,默认切到「仅名单内生效」
toolkit scope list exclude ~/work/legacy # 加入黑名单,默认值不变
toolkit scope list add ~/work --layer project # 写入当前项目层(随仓库共享)
toolkit scope list remove ~/work --from include --to exclude # 白名单转黑名单
toolkit scope list remove ~/work/legacy --from exclude # 从黑名单移除
toolkit scope list default # 查看当前默认值
toolkit scope list default off # 切换为「仅名单内生效」
toolkit scope list reset # 清除限制(全部生效)
toolkit skill mount ~/work --dry-run # 批量项目面安装:先预览(由 scope mount 迁入)
toolkit scope guard fxri-plan-task # 内容闸门:按当前目录作用域输出技能正文(未激活按未激活退出码结束)名单的查看与增删改统一收进 scope list 组:裸 scope list 查看名单, list add / list exclude / list remove / list default / list reset 负责写入。 旧写法 scope add / scope exclude / scope remove / scope default / scope reset 仍可用,但会提示已弃用并提示迁移到该子组。
策略命令
scope policy list [--at <目录>] [--format json]:列出来源层、id、name、条件、技能维度与当前命中结果; 旧activation编译出的规则标注legacy只读scope policy add:条件--paths/--subpaths/--markers/--git-remotes; 技能维度--mode/--profile/--allow/--deny;--effect缺省allow--effect deny不接受这些技能名单,只按scope skills deny生成的技能选择器生效--id不含空白 / 控制字符且不能以legacy:开头,缺省自动生成且不可变--profile只能引用目标层及更低层已定义的档案scope policy remove:优先--id;--name仅在该层唯一且无跨层同名时可用scope policy reset:按--id/--paths(精确或 glob 命中)批量清除;整层清空需--all+--yes, 只清policies,不清旧activationscope skills是技能维度快捷视图:allow只允许列出的技能,deny排除列出的技能,profile管理档案,reset清空该层技能策略profile移除时提示仍被哪些策略引用与同名回退profile的精确技能名按包内清单校验;只含 deny 的档案不能用于 allowlist / deny 展开profile省略档案名时按--layer过滤列表,未传为合并视图- 优先级:层(local > project > global)→ 具体度 →
deny>allow→ 后写覆盖;只取最高优先的一条,不合并 - 非技能维度(纯路径 / 标记 / 远端)同样用
scope policy表达;--mode/--allow仅在allowlist下参与放行 deny只按技能选择器限定范围,携带名单会被拒绝;未限定技能会拒绝该范围全部技能,写入需--yes
交互与写命令
- 无参
toolkit scope:TTY 下进入状态优先向导;非 TTY 输出状态摘要与子命令提示并以0退出。 交互入口也可显式运行toolkit scope wizard(非 TTY 按无交互退出码结束,见退出码) scope status/list的--format仅接受json,非法值在 stderr 报错并以1退出,不再回落文本- 向导首页固定显示「当前层 + 配置文件 + 默认值 + 白名单 / 黑名单条数」;首项为查看状态 / 规则清单,避免盲改
- 动作按意图排列:添加白名单 / 添加黑名单 / 管理条目(移除、互转)/ 切换默认值 / 清除限制 / 高级规则 / 技能矩阵 / 切换配置层 / 退出
- 添加流程先选白或黑,再选来源:扫描项目选择、手动输入目录、使用当前目录;扫描结果页显示跳过统计, 可切换包含隐藏目录 / 嵌套仓库或下探更深
- 项目层 / 本地层额外提供「仅本项目生效」「在本项目内排除」两个快捷项,落到同一配置模型,不再走独立分支
- 管理条目合并两列表并标注
[白]/[黑]、路径存在性与被覆盖提示;勾选后移出或转到另一侧,写前展示 diff - 高级规则(启用标记 / git 远端 / 技能级规则)只读展示并给出配置文件路径,复制后自行编辑,不自造低频编辑 UI
- 技能矩阵页:选择范围(当前项目 / 手动项目与子路径 / 扫描)、模式(只允许 / 全部允许但排除)、技能或档案, 可选标记 / 远端条件;预览后写入,空现场提示先安装技能或创建档案,不写空规则
- 内容闸门与批量挂载已移出本域:默认分发形态用
toolkit config set skillDelivery.default gated|full切换,on对应gated(入口壳)、off对应full(全文),查看用toolkit config get skillDelivery.default;toolkit skill install --gate/--embed生成或还原入口壳;批量挂载用toolkit skill mount - 选择页统一提供「← 返回」(末位)与 ESC 返回上一级;顶层「退出」按成功计
0,Ctrl+C 结束整个命令(取消退出码) - ESC 有约 500ms 判定延迟(readline 需先排除方向键序列),属正常现象
scope list add/list exclude/list remove均需显式目录:无参只提示改用toolkit scope wizard,不再隐式进入完整向导list add加入白名单并把默认值切到「仅名单内生效」;list exclude只加黑名单、默认值不变;同路径在另一侧时写前预览「移入 / 转入」list remove --from include|exclude|both(默认both)指定来源侧,--to include|exclude一步转入另一侧;带参与交互同口径list default on|off查看或切换默认值;list reset清除限制(全部生效并清空两列表,保留标记 / git 远端 / 技能级规则)- 写前统一展示预览:TTY 下确认后落盘,
--yes跳过确认,--dry-run只预览;非 TTY 带显式参数直接执行 - 结果块统一输出写入文件、变更条目与当前默认值;无变化时只提示「没有变化,无需写入」
- 相对路径按目标层项目根解析(全局层按当前目录);
--layer global|project|local缺省全局 scope list同时输出条目存在性:文本模式列出「条目异常」,--format json的data.items含path/list/exists; 相对路径条目按所属配置层的项目根解析- 批量项目面安装已迁至
toolkit skill mount(原scope mount已移除);写入边界与--dry-run见 技能分发 · mount - 非 TTY 环境:
wizard会提示无法交互(无交互退出码,见退出码);写命令请直接带参数
内容闸门 guard
- 前置:技能已被判定为入口壳形态(矩阵限制或
skillDelivery规则),由toolkit skill install生成入口壳; 旧键skillInstall.gate/metadata.gate: false仍读时兼容,新配置用skillDelivery toolkit scope guard <技能名>读取当前目录的作用域判定:激活时把真源SKILL.md正文写到 stdout。 未激活时 stdout 为空、原因写 stderr 并以未激活退出码结束(见退出码)- 输出契约:stdout 只放正文(供 AI 直接消费),参考文件目录与诊断一律走 stderr;只读,不写缓存
- 技能名须为内置包或已登记来源中存在的单段名字;未知名字或含路径分隔符时以退出码
1报错 - 仅在 argv 恰为
scope guard <技能名>时走快速路径(不加载完整命令集);带其它参数(含--help)回落常规 CLI - 入口壳只降低正文被读取的概率,不是物理隔离;需要绝对干净用
skill mount或skill install --scope project做项目面安装 toolkit skill install --embed可随时回退为全文安装- 联动提示:矩阵限制的技能已按策略推导自动进入入口壳;仅当显式规则把被拒技能设为全文时,
scope status/scope skills list/skill status(项目面)提示「策略对该技能无效:已显式设为全文安装」
判定顺序
- 多条策略命中时按层(local > project > global)→ 同层具体度(
subpaths>paths> 无条件;技能精确名 > glob > 无技能约束; 条件更多、路径更长)→deny>allow→ 后写覆盖,只取最高优先的一条 effect: deny直接拒绝;effect: allow再按skills.mode判断当前技能(allowlist 需命中允许项,denylist / all 仅排除项)- 无策略命中默认允许
旧 activation 加载时编译为同层策略:exclude / 标记排除为 deny,include 与启用条件为 allow,空 allowlist 产生兜底 deny, 既有配置结论不变。判定基准为项目根:优先 git 根,其次最近 .tasks 根,都没有则回落当前目录。 scope status --format json 走统一信封,data 内含 active / mode / baseDir / skill / sourceFile / matchedRule / reason。 matchedRule 为 policy:<id>,有 name 时附 (name)。 scope status --skills --format json 的 data 另含 skills 与 linkage。 只有 policies 时,scope status 不显示旧字段模式,改为显示策略条数与策略来源;scope list 同样追加策略摘要。 基准变化或规则按真实路径写入导致不命中时,status 会在 stderr 给出提示。
边界
- 默认
mode = all,不配置时与历史行为完全一致;denylist是等价的兼容别名,status/list显示为all(兼容读取 denylist), 任何写命令都会把旧值归一为all mode = all时include不参与判定,list会在白名单后标注「当前默认全部生效,未参与判定」- 只影响技能与内容闸门(
scope guard),不影响toolkit命令本身(命令是显式调用的) scope policy reset --all只清policies;旧activation需scope list reset,两者不要混用- 矩阵未允许的已安装技能只提示、不自动删除,用
toolkit skill uninstall清理 - 全局规则无法按目录排除(agent 限制);项目专用规则需落在项目内
- 工具不创建、不修改项目内配置或标记;项目层配置由用户自行写入时正常参与
相关页面
- 配置:作用域配置(activation / policies) · 配置参考
- 参考:CLI 参考 · 技能分发
