fable-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Config

Change harness/configuration behavior with explicit precedence, least privilege, secret-safe handling, and a verified rollback path.

通过明确的优先级、最小权限、安全处理 Secrets 以及经过验证的回滚路径来更改 Harness/配置行为。

Mission

目标

Configuration is executable behavior. A syntactically valid JSON/TOML/YAML file can still disable a guard, broaden permissions, write to the wrong scope, or be ignored because another source has higher precedence.

The Skill must prove both configuration validity and effective behavior.

配置即可执行行为。语法有效的 JSON/TOML/YAML 文件仍可能禁用防护、扩大权限、写入错误作用域，或因另一配置来源具有更高优先级而被忽略。

Skill 必须同时证明 配置有效性 与 实际生效行为。

Activate When

适用场景

changing host/harness settings, permissions, hooks, keybindings, model/tool config, or environment references;
adding/removing lifecycle enforcement;
troubleshooting why a setting is not taking effect;
configuring safe command/tool allowlists;
migrating configuration formats/scopes.

更改 Host/Harness 设置、权限、Hook、快捷键、模型/工具配置或环境变量引用；
添加或移除生命周期强制执行机制；
排查设置未生效的原因；
配置安全的命令/工具允许列表；
迁移配置格式或作用域。

Do Not Activate When

不适用场景

storing raw credentials/secrets;
application business logic is the real change;
a host capability is unknown and needs research/discovery first;
the requested change is to weaken a safety boundary merely to bypass an error without understanding it.

存储原始凭据或 Secrets；
实际需要更改的是应用业务逻辑；
Host 能力尚不明确，需要先进行调研或能力发现；
仅仅为了绕过错误而请求削弱安全边界，却没有理解问题原因。

Configuration Classification

配置分类

Change	Main risk
Permission/allowlist	excessive privilege/wildcard scope
Hook registration	hook exists but is never invoked / blocks wrong phase
Environment config	precedence, secret leakage, type/format
Host settings	wrong user/project scope, unsupported keys
Model/tool config	changed behavior/cost/access unexpectedly
Keybindings/UI	collision/override
Generated config	manual edit overwritten by generator

更改内容	主要风险
权限/允许列表	权限过度或通配符范围过大
Hook 注册	Hook 已存在但从未被调用，或阻止了错误的阶段
环境配置	优先级、Secret 泄漏、类型/格式问题
Host 设置	用户/项目作用域错误、不受支持的配置键
模型/工具配置	行为、成本或访问权限发生意外变化
快捷键/UI	冲突或覆盖
生成的配置	手动编辑的内容被生成器覆盖

Protocol

协议

Stage 1 — Locate source and effective scope

阶段 1——定位配置来源和实际生效作用域

Identify:

target host/version;
project vs user/global scope;
all configuration sources and precedence;
generated vs hand-maintained files;
existing user customizations to preserve.

Do not edit the first file with the right name until you know it is effective.

确定：

目标 Host 及版本；
项目作用域与用户/全局作用域；
所有配置来源及其优先级；
生成文件与手动维护文件；
需要保留的现有用户自定义配置。

在确认某个文件实际生效之前，不要仅因为文件名看似正确就率先编辑它。

Stage 2 — Define desired behavior and least privilege

阶段 2——定义期望行为并遵循最小权限

State exactly what capability should become allowed/blocked/triggered and what must remain unchanged.

For permissions, prefer narrow command/tool/path patterns. Wildcards need explicit justification and threat consideration.

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

对于权限，应优先使用范围精确的命令、工具或路径模式。使用通配符时，需要明确说明理由并评估相关威胁。

Stage 3 — Protect secrets

阶段 3——保护 Secrets

Configuration may reference environment variable names or secure stores, but should not embed raw tokens/passwords/private keys unless the target's secure format explicitly requires protected encrypted storage.

If an existing secret is found in plaintext, do not echo it; route exposure handling appropriately.

配置可以引用环境变量名称或安全存储区，但不应嵌入原始 Token、密码或私钥，除非目标 Host 的安全格式明确要求采用受保护的加密存储。

如果发现现有 Secret 以明文形式存在，不要将其回显；应采用适当方式处理暴露风险。

Stage 4 — Make a minimal merge

阶段 4——进行最小化合并

Preserve unknown/user-defined settings. Avoid replacing an entire config object/file when one scoped key can be merged.

For generated config, modify source/generator then regenerate.

保留未知或用户定义的设置。如果只需合并一个带作用域的配置键，不要替换整个配置对象或文件。

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

Stage 5 — Validate structure and semantics

阶段 5——验证结构和语义

Run available parser/schema/host diagnostics. Check:

syntax;
key types/enums;
duplicate/conflicting entries;
unsupported/deprecated keys;
permission pattern scope;
hook command/path existence.

运行可用的解析器、Schema 或 Host 诊断工具。检查：

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

Stage 6 — Prove effective behavior

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

A valid file is not enough. Test the configured behavior safely:

target command is allowed while broader command remains denied;
hook fires at intended lifecycle point;
project override wins as expected;
setting is visible to the target host;
rollback restores previous behavior.

仅确保文件有效并不足够。应安全地测试配置后的行为：

目标命令被允许，而范围更广的命令仍被拒绝；
Hook 在预期的生命周期节点触发；
项目级覆盖按预期生效；
目标 Host 可以读取该设置；
回滚能够恢复之前的行为。

Stage 7 — Record rollback and handoff

阶段 7——记录回滚和交接信息

Capture changed source, effective scope, validation, behavioral proof, and how to revert if the host fails after restart/update.

记录已更改的配置来源、实际生效作用域、验证结果、行为证明，以及 Host 在重启或更新后失败时的回滚方式。

Decision Rules

决策规则

Preserve existing user settings not owned by the task.
Prefer exact allowlists over
```
*
```
, shell wildcards, root/global permissions.
A config key accepted by parser but ignored by host is not a successful change; verify effect.
Host integration levels differ; do not claim hooks/enforcement where the host only supports advisory rules.
Environment variable name may be stored; secret value should remain in secure environment/credential store.
If config precedence is uncertain, investigate before editing more files.
Do not disable security/approval checks simply because they are blocking an unsafe action.
If a malformed edit can lock out the host, keep a reversible backup/atomic write strategy.

保留不属于本任务范围且由用户管理的现有设置。
优先使用精确允许列表，而不是
```
*
```
、Shell 通配符或 Root/全局权限。
配置键即使被解析器接受，但被 Host 忽略，也不能视为成功更改；必须验证实际效果。
不同 Host 的集成程度不同；如果 Host 仅支持建议性规则，不要声称已实现 Hook 或强制执行。
可以存储环境变量名称，但 Secret 值应保留在安全环境或凭据存储中。
如果配置优先级不明确，应先调查，不要盲目编辑更多文件。
不要仅仅因为安全或审批检查阻止了不安全操作，就将其禁用。
如果格式错误的编辑可能导致 Host 无法启动，应采用可逆备份或原子写入策略。

Invariants

不变量

Least privilege is preserved or any broadening is explicit and justified.
Raw secrets are not introduced into repository/config logs.
Existing unrelated user configuration is preserved.
Edited source is the effective source-of-truth.
Syntax/schema and actual host behavior both verify.
Rollback is possible for material changes.

保持最小权限；任何权限扩大都必须明确说明并提供理由。
不将原始 Secrets 引入代码仓库或配置日志。
保留与当前任务无关的现有用户配置。
已编辑的配置来源必须是实际生效的 Source of Truth。
同时验证语法/Schema 和 Host 的实际行为。
重大更改必须可以回滚。

Failure Taxonomy

失败类型

Precedence mismatch

优先级不匹配

Edited file is shadowed by another scope/source. Trace effective configuration.

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

Schema-valid but ignored

Schema 有效但被忽略

Host accepts file but does not support/use key. Verify host version/capability.

Host 接受文件，但不支持或不会使用相应配置键。应验证 Host 版本及其能力。

Permission overreach

权限越界

Pattern allows more than requested. Narrow and test negative case.

模式允许的范围超出请求范围。应缩小权限并测试反例。

Hook misregistration

Hook 注册错误

Script exists but lifecycle never invokes it. Validate registration path/event and permissions.

脚本存在，但生命周期始终不会调用它。应验证注册路径、事件和权限。

Secret leakage

Secret 泄漏

Credential embedded/logged. Remove safely and rotate if exposure occurred.

凭据被嵌入配置或写入日志。应安全移除；如果已经暴露，则轮换凭据。

User-config clobber

用户配置被覆盖

Whole-file rewrite loses existing settings. Restore/merge surgically.

整体重写文件导致现有设置丢失。应恢复并进行局部合并。

Generated drift

生成配置漂移

Manual edit is overwritten. Change generator/source instead.

手动编辑的内容被覆盖。应改为修改生成器或源配置。

Anti-Patterns

反模式

```
"allow": ["*"]
```
to stop approval prompts;
editing global config when project scope suffices;
copying API tokens into settings examples;
validating JSON syntax and calling the hook configured;
claiming full lifecycle enforcement on a host with advisory-only integration;
resetting the whole config file for one key;
disabling security controls to make a command pass;
manually patching generated config.

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

Configuration Packet

配置记录包

text

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:

text

目标 Host/版本/作用域：
实际生效的配置来源及优先级：
期望行为：
已更改的设置：
更改前后的权限：
Secret 处理方式：
语法/Schema 验证：
行为证明及反例：
已保留的用户设置：
回滚方式：

Completion Criteria

完成标准

Configuration completes when:

correct effective source/scope was changed minimally;
configuration parses and satisfies schema/capability constraints;
permissions remain least-privilege;
secrets/unrelated settings remain safe;
target behavior is empirically observed, including important negative case;
rollback and host limitations are explicit.

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

以最小改动修改了正确的实际生效来源和作用域；
配置可以正常解析，并符合 Schema 和 Host 能力约束；
权限保持最小化；
Secrets 和无关设置保持安全；
已通过实证观察目标行为，包括重要的反例；
明确说明回滚方式和 Host 限制。

Progressive Resources

渐进式资源

Deep guide:

references/config-precedence-permissions-and-hooks.md

Existing rules:

references/harness-configuration-rules.md

Example:
```
examples/configure-allowlist.md
```

深入指南：

references/config-precedence-permissions-and-hooks.md

现有规则：

references/harness-configuration-rules.md

示例：
```
examples/configure-allowlist.md
```