fable-eco

Fable Eco

为 get-fable 提供精选能力分发与执行控制子系统。

用途

弥合零散的开发者工具安装与有序激活 Agent 能力之间的差距。fable-eco 遵循“多安装、少激活”的架构原则：通过事务方式配置精选的 AI 工程能力（代码图索引器、代码审查辅助工具、浏览器工具、测试运行器），并固定不可变版本；同时为显式遵循最小权限策略的 get-fable 路由任务编译受任务范围限制的执行合约。

适用场景

• 在不产生副作用的前提下，发现本机运行时、编译器、包管理器和编码宿主配置。
• 解析、规划、安装、更新或回滚精选生态能力。
• 在 .fable/eco.json 中管理项目能力绑定，以声明所需能力、配置集和最低合约版本。
• 通过不会修改内容的 doctor 检查，诊断或修复生态完整性、锁文件、日志或损坏的符号链接。
• 根据生命周期路由决策，为 Agent 任务编译确定性的能力执行合约。

不适用场景

• 高层生命周期任务路由或状态管理（使用 get-fable）。
• 不需要外部能力的纯内部代码编写（使用 fable-execute）。
• 执行测试优先的红-绿-重构循环（使用 fable-tdd）。
• 诊断反复出现的执行失败或损坏的测试框架（使用 fable-recover）。

输入

• routing_decision：来自 fable_core::RoutingDecision 的结构化路由决策，包含选定的技能、任务形态和意图。
• project_binding：来自 .fable/eco.json 的可选工作区绑定，声明启用的配置集、固定的能力和策略覆盖项。
• catalog_layers：来自官方分发源、团队仓库或本地目录的多层能力清单。
• machine_facts：检测到的系统运行时、操作系统平台、包管理器和宿主配置状态。

预期输出

• install_plan：安装操作的拓扑有向无环图（DAG），并标明回滚类别。
• lockfile：经过加密哈希的 .fable/eco.lock，包含 SHA-256 摘要和来源元数据。
• execution_contract：受任务范围限制的清单，仅公开获准的工具、环境变量和执行限制。
• capability_receipt：结构化记录，用于记录宿主配置编辑、已安装版本和当前所有权。

流程

1. 发现：运行不会修改内容的探测，以发现机器事实、已安装的运行时、现有能力版本和宿主配置文件。
2. 加载与验证清单：载入官方、团队和本地清单层中的能力与配置集清单，并执行语义架构验证。
3. 确定性解析：构建依赖关系图和冲突图，解析传递性能力需求，并检测不兼容项或缺失的前置条件。
4. 生成计划：构建执行计划，在应用任何更改之前列出所有文件复制、下载内容解压、环境更新和健康检查。
5. 事务式配置：在暂存沙箱内执行操作，并使用预写日志（.fable/eco-journal.json）验证校验和并进行原子提交。
6. 健康验证：对每项已安装能力运行安装后健康探测，以确认其已准备就绪、能够正常运行。
7. 回执与锁定：更新 .fable/eco.lock，并写入宿主配置所有权回执。
8. 编译合约：针对路由任务，根据路由决策和策略规则筛选已安装能力，以编译执行合约。

决策规则

• 先规划再修改：未经验证的执行前计划确认，不得修改文件、下载内容或编辑配置。
• 稳定通道上的不可变性：稳定能力必须解析为不可变的 git 提交或经过加密哈希验证的发布归档（拒绝 main 或 HEAD）。
• 权限分层只允许收紧：项目策略只能限制能力；项目策略不能覆盖机器级拒绝规则。
• 按最小权限启用能力：仅暴露当前生命周期阶段和任务类型所需的特定能力。
• 失败时回滚：配置过程中，如果健康检查或安装步骤失败，则使用事务日志触发自动回滚。

工具策略

• 使用高性能 fable-eco Rust crate 原生执行发现和解析。
• 使用原子文件系统暂存和复制操作，并严格防止路径遍历（禁止使用 .. 跳转）。
• 执行只读探测，不得更改系统文件或环境状态。
• 根据 schemas/eco/ 中的规范 JSON Schema 定义验证所有传入清单。

证据要求

• 发现结果必须包含结构化的机器信息（操作系统、架构、运行时、包管理器、主机）。
• 安装计划必须列出所有操作，并明确指定 id、kind、depends_on 和 rollback_class。
• 执行契约必须明确指定确切的能力 ID、允许使用的工具、网络策略和执行等级。
• 完成的操作必须通过安装后健康检查，并提供相应证据，之后才能持久化到锁文件。

故障处理

• 事务暂存失败或发生意外崩溃时，对日志状态进行分类（Clean、RecoverableRollback、RecoverableCommit、Corrupted）并执行恢复。
• 如果主机上缺少所需的运行时或依赖项，则将该能力标记为降级或不兼容，并报告修复步骤。
• 如果能力需求冲突，则停止解析并输出冲突的能力链。

完成标准

• 所有选定能力均已成功暂存、验证并提交，且未发生未处理错误。
• 目标主机配置文件已成功修补，并带有经过验证的所有权标签。
• 安装后健康检查通过，退出代码为 0，且输出有效。
• 已生成确定性的 .fable/eco.lock，并与工作区状态同步。