fable-config

Fable Config

通过明确优先级、最小权限、妥善处理机密信息以及经过验证的回滚路径，改变运行框架/配置行为。

使命

配置会产生实际行为。语法有效的 JSON/TOML/YAML 文件仍可能禁用防护、扩大权限、写入错误范围，或因其他来源优先级更高而被忽略。

此 Skill 必须证明配置有效性和实际生效行为。

适用场景

• 更改主机/运行框架设置、权限、钩子、键绑定、模型/工具配置或环境变量引用；
• 添加/移除生命周期强制机制；
• 排查设置为何未生效；
• 配置安全的命令/工具允许列表；
• 迁移配置格式/范围。

不适用场景

• 存储原始凭据/机密信息；
• 实际变更涉及应用业务逻辑；
• 主机功能未知，且需要先进行研究/发现；
• 请求仅为绕过错误而削弱安全边界，却未先了解原因。

配置分类

变更	主要风险
权限/允许列表	权限过大/通配符范围过宽
钩子注册	钩子已存在但从未调用/阻塞了错误阶段
环境配置	优先级、机密信息泄露、类型/格式
主机设置	用户/项目范围错误、不支持的键
模型/工具配置	行为/成本/访问权限出现意外变化
键绑定/界面	冲突/覆盖
生成的配置	手动编辑被生成器覆盖

流程

阶段 1 — 定位来源和生效范围

确定：

• 目标主机/版本；
• 项目范围还是用户/全局范围；
• 所有配置来源及其优先级；
• 文件由生成器生成还是手动维护；
• 需要保留的现有用户自定义设置。

在确认某个文件确实生效之前，不要仅凭文件名就编辑它。

阶段 2 — 明确期望行为并遵循最小权限原则

明确说明应允许/阻止/触发哪项能力，以及哪些内容必须保持不变。

对于权限，优先使用范围狭窄的命令/工具/路径模式。使用通配符时，必须明确说明理由并考虑威胁。

阶段 3 — 保护机密信息

配置可以引用环境变量名称或安全存储，但除非目标系统的安全格式明确要求使用受保护的加密存储，否则不应嵌入原始令牌/密码/私钥。

如果发现现有机密信息以明文形式存储，不要复述；应按适当流程处理暴露事件。

阶段 4 — 进行最小合并

保留未知设置和用户自定义设置。若只需合并一个特定范围的键，就不要替换整个配置对象/文件。

对于生成的配置，应修改源文件/生成器，然后重新生成。

阶段 5 — 验证结构和语义

运行可用的解析器/架构/主机诊断工具。检查：

• 语法；
• 键类型/枚举值；
• 重复或冲突的条目；
• 不受支持/已弃用的键；
• 权限模式的范围；
• 钩子命令/路径是否存在。

阶段 6 — 证明实际生效行为

文件有效还不够。安全地测试配置行为：

• 目标命令被允许，而范围更广的命令仍被拒绝；
• 钩子在预期的生命周期节点触发；
• 项目级覆盖按预期生效；
• 目标主机可见该设置；
• 回滚可恢复先前行为。

阶段 7 — 记录回滚方案并交接

记录变更来源、生效范围、验证结果、行为证明，以及主机在重启/更新后出现故障时的回退方法。

决策规则

• 保留不属于当前任务的现有用户设置。
• 优先使用精确的允许列表，而不是 *、Shell 通配符或根级／全局权限。
• 解析器接受但主机忽略的配置键不算成功更改；请验证实际效果。
• 主机集成级别各不相同；如果主机仅支持建议性规则，就不要声称支持钩子／强制执行。
• 可以存储环境变量名称；机密值应保存在安全的环境或凭据存储中。
• 如果不确定配置优先级，请先调查，再编辑更多文件。
• 不要仅仅因为安全检查／审批检查阻止了不安全操作，就将其禁用。
• 如果错误的编辑可能导致主机无法使用，请保留可恢复的备份／原子写入策略。

不变量

• 保持最小权限，或明确说明并证明权限扩大是合理的。
• 不要将原始机密写入仓库／配置日志。
• 保留现有且无关的用户配置。
• 已编辑的源是实际生效的唯一事实来源。
• 验证语法／架构以及主机的实际行为。
• 重大更改必须可以回滚。

故障分类

优先级不匹配

编辑的文件被其他作用域／来源覆盖。追踪实际生效的配置。

架构有效但被忽略

主机接受该文件，但不支持／使用该键。验证主机版本／能力。

权限超范围

模式允许的权限超出请求范围。收窄权限并测试负面情况。

钩子注册错误

脚本存在，但生命周期从未调用它。验证注册路径／事件和权限。

机密泄露

凭据被嵌入／记录。安全地移除；如果已泄露，则轮换凭据。

用户配置被覆盖

重写整个文件导致现有设置丢失。精确恢复／合并。

生成文件漂移

手动编辑被覆盖。请改动生成器／源文件。

反模式

• 使用 "allow": ["*"] 来阻止审批提示；
• 项目作用域已足够时仍编辑全局配置；
• 将 API 令牌复制到设置示例中；
• 仅验证 JSON 语法，就声称已配置钩子；
• 在仅支持建议性集成的主机上声称实现了完整的生命周期强制执行；
• 为更改一个键而重置整个配置文件；
• 禁用安全控制以使命令通过；
• 手动修补生成的配置。

配置数据包

Target host/version/scope:
Effective config sources + precedence:
Desired behavior:
Settings changed:
Permissions before/after:
Secret handling:
Syntax/schema validation:
Behavioral proof + negative case:
Preserved user settings:
Rollback:

完成标准

满足以下条件时，配置工作才算完成：

• 以最小改动修改了正确的实际生效来源／作用域；
• 配置能够解析，并满足架构／能力约束；
• 权限仍遵循最小权限原则；
• 机密／无关设置仍然安全；
• 已通过实证观察目标行为，包括重要的负面情况；
• 已明确说明回滚方式和主机限制。

后续资源

• 深入指南：references/config-precedence-permissions-and-hooks.md
• 现有规则：references/harness-configuration-rules.md
• 示例：examples/configure-allowlist.md