# Fadeno：为AI编程代理打造的仓库原生Playbook框架

> Fadeno是一个开源的YAML Playbook框架，旨在解决AI编程代理行为不一致的问题。通过定义一次工作流程并在每次运行时复用，开发者可以确保代理以相同的方式执行任务，同时留下可检查的审计痕迹。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-01T01:46:41.000Z
- 最近活动: 2026-06-01T01:50:15.460Z
- 热度: 161.9
- 关键词: AI编程代理, Playbook, 工作流自动化, 代码审查, Claude Code, Codex, 开发工具, YAML, 开源工具
- 页面链接: https://www.zingnex.cn/forum/thread/fadeno-aiplaybook
- Canonical: https://www.zingnex.cn/forum/thread/fadeno-aiplaybook
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：CrocSwap
- 来源平台：github
- 原始标题：fadeno
- 原始链接：https://github.com/CrocSwap/fadeno
- 来源发布时间/更新时间：2026-06-01T01:46:41Z

## 原作者与来源\n\n- **原作者/维护者**: CrocSwap\n- **来源平台**: GitHub\n- **原始标题**: fadeno\n- **原始链接**: https://github.com/CrocSwap/fadeno\n- **发布时间**: 2026年6月1日\n\n---\n\n## 背景：AI编程代理的一致性问题\n\n随着GitHub Copilot、Claude Code、Codex等AI编程代理的日益强大，开发者们发现了一个令人困扰的问题：这些代理虽然能力出众，但行为却缺乏一致性。每次执行非平凡任务时，开发者都需要重新输入类似的指令：\n\n> \"请小心处理，先制定计划再实施。检查代码中的边界情况。运行测试。如果发现问题就修复。不要在没有询问的情况下安装新依赖或执行破坏性操作。\"\n\n这种重复性的提示输入不仅浪费时间，更重要的是每次运行的行为都可能不同。当对话结束后，代理具体做了什么操作、遵循了什么流程，往往没有留下可供审查的记录。\n\n---\n\n## Fadeno的核心概念\n\nFadeno（发音为/fah-DEH-no/，源自世界语\"thread\"）是一个仓库原生的Playbook框架，其核心理念很简单：**定义一次工作流程，任何代理都以相同的方式运行它**。\n\n### 三层架构设计\n\nFadeno将系统分为三个清晰的层次：\n\n1. **能力层（Capability）**：如何运行和编写Playbook，包括runner和builder技能、角色子代理（worker/reviewer/judge）以及CLI工具。这层可以通过`fadeno init`复制到仓库，或作为Claude Code插件全局安装。\n\n2. **定义层（Definitions）**：具体的Playbook内容，存储在仓库的`.fadeno/`目录下，包括词汇表、Playbook定义、JSON Schema和强制执行策略。\n\n3. **痕迹层（Traces）**：执行记录，保存在`.fadeno/runs/`目录中，包括运行元数据、事件日志和所有输出产物。这是输出而非源代码，可以安全删除。\n\n---\n\n## Playbook的结构与执行流程\n\nFadeno的Playbook采用YAML格式定义，每个Playbook都包含清晰的步骤和决策门控。以`code-change-review`为例，其执行流程如下：\n\n```\nplan（制定计划） → implement（实现代码） → review（代码审查） → review_gate（审查门控）\n                                                      ↓ 通过\n                                                   test（运行测试） → test_gate（测试门控）\n                                                      ↓ 通过\n                                                   finalize（完成提交）\n                                                      ↓ 失败\n                                                   revise（修订代码，最多1次循环）\n```\n\n### 关键设计原则：结构化判断\n\nFadeno有一条铁律：**门控永远不会\"询问LLM\"**。控制流始终是`评估器 → 结构化判断产物 → 确定性条件`。例如，`no_blocking_issues`门控会检查`review-report.json`中是否存在标记为`blocking`的问题，而不是让模型\"感觉\"代码是否没问题。\n\n这种设计确保了可重复性和可审计性。循环始终有界，迭代产物会被版本化而不会被覆盖。\n\n---\n\n## 多平台支持与插件机制\n\nFadeno的一个显著特点是**平台无关性**。相同的Playbook可以在Codex和Claude Code上运行，未来还可以编译到真正的编排运行时。只有轻量级的平台适配层有所不同。\n\n### Claude Code插件\n\n对于Claude Code用户，Fadeno提供了插件安装方式：\n\n```bash\n/plugin marketplace add <owner>/fadeno\n/plugin install fadeno@fadeno\n```\n\n安装后，用户可以使用`/fadeno:runner`命令运行Playbook，或使用`/fadeno:builder`创建新的Playbook。插件将`fadeno` CLI作为单个可执行文件捆绑在`plugin/bin/`目录中，因此技能可以直接调用`fadeno validate`、`fadeno diagram`、`fadeno gate`等命令，无需额外安装。\n\n### Codex支持\n\n对于Codex用户，运行`npx fadeno init --codex`会生成`.agents/skills/`目录和`AGENTS.md`文件，使用`$`风格的调用语法。\n\n---\n\n## 强制执行：建议性与强制性的分层\n\nFadeno对强制执行采取了诚实的分层策略：\n\n- **第一层（建议性）**：在仅支持指令的主机中，批准策略是建议性的——模型被请求遵守，但没有硬性保证。\n- **第二层（强制性）**：真正的保证来自git/CI/pre-commit/hooks层。`fadeno gate`命令作为桥梁，它从磁盘上的结构化判断产物计算门控条件，可以在CI、pre-commit/pre-push钩子或Claude Code的`Stop`钩子中运行相同的检查。\n\n这种设计让工具诚实可信，而不是通过过度承诺来获取信任。\n\n---\n\n## 使用场景与价值\n\nFadeno适用于多种场景：\n\n1. **团队协作标准化**：确保团队中的所有成员使用相同的代码审查、测试和提交流程。\n\n2. **可审计的AI辅助开发**：每次代理运行都会留下完整的执行痕迹，包括计划、实现、审查结果和测试输出。\n\n3. **跨平台工作流移植**：Playbook可以在不同AI编程代理之间共享和复用，降低平台锁定风险。\n\n4. **复杂任务的可靠执行**：通过结构化的步骤和明确的门控，确保复杂任务（如大规模重构、API迁移）按预期完成。\n\n---\n\n## 快速开始\n\n要开始使用Fadeno，只需运行：\n\n```bash\n# 对于Codex\nnpx fadeno init --codex\n\n# 对于Claude Code\nnpx fadeno init --claude\n```\n\n`init`命令是安全可重复运行的：现有文件会被保留，`AGENTS.md`或`CLAUDE.md`的内容会被保留，Fadeno只会在标记区域追加内容。使用`--force`可以覆盖，使用`--with-hooks`可以额外生成第二层强制执行层（pre-commit守卫和CI工作流）。\n\n---\n\n## 总结与展望\n\nFadeno代表了AI辅助开发工具演进的一个重要方向：从\"每次重新描述期望\"到\"定义一次，重复执行"。它不仅解决了行为一致性问题，还通过结构化的执行痕迹提供了可审计性。\n\n随着AI编程代理能力的不断增强，如何有效地管理和控制这些代理将成为开发工作流中的关键问题。Fadeno提供了一个轻量级、可移植、诚实的解决方案，值得所有使用AI编程代理的开发者关注。\n\n未来，Fadeno计划发展为真正的编排运行时，但目前的文件驱动设计已经提供了强大的基础功能，并且与未来的运行时兼容。