项目定位与目标

AgentLoom 是一个面向应用层的多智能体框架，核心理念是"通过 YAML 构建多智能体应用"。框架提供配置驱动的多智能体应用运行时、内置工具集、模型管理与 checkpoint 恢复能力，使开发者能以声明式方式编排 Agent、Workflow、Tools、Skills 与 MCP 集成。资料来源：README.md

框架在 v1.0.0 达到首个稳定公开版本，确立 Supervisor / Worker 工作流模型与基础工具集（文件、Shell、搜索、代码编辑、Git、Todo、Skill 等）。v1.0.1 在此基础上新增了本地 Codex Exec 工具封装与 fixed_args 参数锁定机制，进一步扩展了框架的开发场景适用性。资料来源：README.md

核心架构：Supervisor / Worker 模型

AgentLoom 的运行时采用分层协调架构。Supervisor Agent 负责整体任务规划与分发，Worker Agents 专注于单一职责的处理单元。这种设计的核心特征是：Worker Agent 通过 agent_function_schema 暴露明确的输入输出契约，使其能被 Supervisor 或其他 Worker 导出为可调用的 Function Tool，从而支持嵌套编排与链式调用。资料来源：README.md、src/lib/smolagents/agent/agent_validation.py

flowchart TD
    User["用户任务 / YAML 入口"] --> Sup["Supervisor Agent<br/>任务规划与调度"]
    Sup --> W1["Worker Agent A<br/>文件 / Shell"]
    Sup --> W2["Worker Agent B<br/>代码 / Git"]
    Sup --> W3["Worker Agent C<br/>搜索 / Skill"]
    Sup --> Tools["Function Tools<br/>file / shell / search ..."]
    Sup --> Codex["Codex Tool<br/>v1.0.1"]
    Tools --> Result["结构化输出"]
    Codex --> Result
    W1 --> Result
    W2 --> Result
    W3 --> Result
    Sup --> Checkpoint[".logs / Checkpoint<br/>断点恢复"]

模型层由 ModelTypeManager 统一管理，支持 powerful、fast、summary、custom 等类型，每种类型对应 YAML 中不同的模型配置段（base_url、api_key、temperature、max_tokens 等），并在运行时通过 resolve_model_type 解析默认值或显式指定值。未定义的模型类型会立即抛出 ValueError，确保配置错误早期暴露。资料来源：src/lib/smolagents/models/model_types.py

配置驱动与工厂模式

AgentLoom 的 Agent 构建采用 YAML Agent Factory 模式。YamlAgentFactory.create_agent_tool 接受 YAML/Markdown 路径或字典配置，解析后实例化 YamlConfiguredAgent，最终返回以 @tool 装饰的工具列表。这套工厂方法通过 agent_function_schema 校验输入输出格式，确保 Worker Agent 的工具契约稳定可调用。资料来源：src/lib/smolagents/agent/yaml_agent_factory.py

配置校验由 agent_validation.py 负责，关键规则包括：agent_function_schema.output 必须为字典并包含非空 description；worker_agents 列表中每项必须为字典且仅支持 path 字段，禁止旧版 name 字段。这些校验在加载阶段即执行，避免运行时出现隐式契约错误。资料来源：src/lib/smolagents/agent/agent_validation.py

v1.0.1 引入的 fixed_args 机制允许 Workflow 在 YAML 中锁定工具的部分输入参数，防止 LLM 在生成 tool_call 时意外覆盖关键配置（如 Codex 的 sandbox 模式）。这对于需要稳定外部副作用的工作流尤其重要。资料来源：src/lib/smolagents/agent/yaml_agent_factory.py

运行时能力与应用生态

AgentLoom 内置 core_file、markdown_report 等工具集，可通过 YAML 显式启用。tool_registry_markdown_validation 应用演示了非默认 markdown_report 工具集的实时 LLM 验证流程。资料来源：applications/tool_registry_markdown_validation/README.md

框架提供多类开箱即用应用：ai_quality_analysis（12 个 Worker Agent 分阶段代码审查）、unit_test_studio（pytest 测试生成）、repo_map（仓库架构地图生成，结合 tree-sitter 符号提取与 Bottom-Up LLM 分析）、codex_exec_demo（v1.0.1 新增的本地 Codex 顺序调用示例）。这些应用共享同一套 Supervisor/Worker 运行时，但通过不同 YAML 配置形成差异化的业务流。资料来源：README.md、applications/repo_map/README.md

Todo 同步机制（todo_sync.py）是长任务执行的关键支撑：Agent 在关键节点被强制要求调用 todo_write 注册或更新任务列表，且在 todo 同步阶段临时禁用所有其他工具，确保任务规划不被 LLM 自由行为打断。资料来源：src/lib/smolagents/agent/todo_sync.py

已知限制与社区反馈

社区反馈揭示了两个值得关注的运行时问题。Issue #4 报告 Windows 平台下原子文件写入在目标 JSON 已存在时触发 WinError 183，影响 checkpoint、任务索引与心跳持久化——这要求在 Windows 环境下对原子写入做兼容性处理。资料来源：Issue #4

Issue #7 与 #9 围绕 Codex Tool 的前置条件展开：本地 codex CLI 必须安装并位于 PATH 中，且 codex login status 必须可执行通过。Issue #9 提议在 Workflow 启动前增加 Codex CLI 登录状态的预校验，避免在未登录或环境变量异常时直接运行导致中途失败。资料来源：Issue #7、Issue #9

See Also

• Model & Configuration — 模型类型解析与 llm.yaml 配置
• Tool Registry & Function Tools — 工具注册与 fixed_args 机制
• Checkpoint & Resume — 断点恢复与长任务执行
• Codex Tool Integration — 本地 Codex Exec Function Tool

概述与设计目标

AgentLoom 是一个配置驱动的多 Agent 应用运行时。其核心设计理念是：开发者通过编写 YAML 文件即可声明 Agent、Workflow、Tool、Skill、MCP 等组件，而无需修改框架代码。运行时由 config/system.yaml 统一装配整个系统。

配置系统由四类核心配置组成：

所有配置在加载时通过 src/lib/config/config.py 中的全局对象 C 暴露，业务代码通过 C.llm.for_type("powerful") 之类的接口读取，避免硬编码路径。

分层配置与合并策略

AgentLoom 支持配置分层（layered configuration）：用户配置与默认配置深度合并。机制实现在 src/lib/config/layered_builder.py。当用户在 config/llm.yaml 中只覆盖 temperature 字段时，框架会保留示例配置中的其它默认字段，从而保证零配置也能运行。

合并完成后，配置会进入 src/lib/config/config_validation.py 走 schema 校验，校验失败会立刻抛错，避免错误配置被延后到运行期才发现。

LLM 模型类型解析

ModelType 是 LLM 配置的核心抽象，定义在 src/lib/smolagents/models/model_types.py 中。框架预置四个标准类型：POWERFUL、FAST、SUMMARY、CUSTOM，同时支持 YAML 中声明的自定义类型。

flowchart LR
    A[YAML agent 配置] --> B[ModelType.resolve_model_type]
    B --> C{类型是否在 llm.yaml 声明?}
    C -- 是 --> D[ModelConfigBuilder.build]
    C -- 否且为空 --> E[使用 model.default_model_type]
    C -- 否且显式传入 --> F[抛 ValueError]
    D --> G[LiteLLMModelV2]
    E --> D
    F --> H[启动失败]

解析逻辑位于 ModelTypeManager.resolve_model_type 中：当 model_type 为空时回退到 C.default_model_type；当显式传入但未声明时立即抛错，以早暴露配置问题。ModelConfig 数据类承载了 model_id、base_url、api_key、temperature、max_tokens、extra_headers、context_cache、extra_completion_params 等字段，最终被 src/lib/smolagents/models/model_manager.py 转换为 litellm.completion() 调用参数。

模型层还支持 ModelConfigOverlay 进行运行时覆盖（runtime override），便于在不同工作流中临时调整 temperature 或 max_tokens 而无需修改配置文件。

Agent、Workflow 与 fixed_args 工具

YamlAgentFactory 是 Agent 编排的入口。它接受 YAML 配置或 Markdown 块，构造 YamlConfiguredAgent 实例，并自动将 Worker Agent 暴露为 Supervisor 可调用的工具（agent_as_tool() 工厂模式）。每个调用都会创建新的 Agent 实例以避免 memory.steps 并发污染。

v1.0.1 新增的 fixed_args 字段（见 applications/codex_exec_demo/README.md）允许在 YAML 中锁定工具输入，防止 LLM 在 tool_call 模式下覆盖关键参数：

tools:
  - name: "codex1"
    module: "src.tools.codex.codex_tool"
    function: "codex"
    fixed_args:
      prompt: "Read pyproject.toml and return the project name and version."
      cwd: "."
      timeout: "600"

固定参数会通过 _bind_fixed_tool_args() 在工厂层绑定到函数签名，未列入 fixed_args 的入参仍由 LLM 自由填充。

Skills、MCP 与 Hooks

• Skills：在 config/system.yaml 的 skills 字段中声明。browser_harness_probe 应用刻意将其设为 [] 以禁用全局自动发现，避免无关 Skill Hook 干扰 probe 行为（参考 applications/browser_harness_probe/README.md）。
• MCP 客户端：通过 config/.mcp.json 声明外部 MCP server，框架读取后将其提供的工具并入 Agent 工具集。
• Hooks：通过 YAML 中的 hooks 块定义生命周期事件（pre-step、post-step、on-error 等），匹配规则与执行行为详见官方文档 Hooks Reference。
• 框架级 Skill：agentloom-framework-skill/ 是面向编码助手的开发辅助 Skill，不会被运行时自动加载。

常见失败模式

社区反馈显示两类高频问题：

1. Windows 平台原子写失败（Issue #4）：checkpoint、task index、heartbeat 持久化在目标 JSON 已存在时可能触发 WinError 183。建议在 Windows 环境下使用 wsl 或先清理 .logs/ 再启动。
2. Codex 工具前置条件（Issue #9）：codex exec 依赖本地 CLI 与有效 codex login status。若跳过预检，workflow 可能在执行中才失败——配置层应通过初始化校验尽早暴露此类问题。

See Also

• README.md
• Skills Configuration
• Hooks Reference
• Checkpoint Resume

运行时、工具与可观测性

概览

AgentLoom 的运行时、工具与可观测性层共同支撑了"配置驱动的多 Agent 应用"这一核心理念。运行时负责将 YAML 配置解析为可执行的 Agent 与工具链；工具系统为 Agent 提供可调用的能力边界；可观测性则保证长任务可追踪、可恢复、可调试。README.md 描述的 Supervisor / Worker 编排模型、YAML 应用入口、内置 file/shell/search/edit/git/todo/skill 工具以及 MCP 客户端集成，都构建在这三层之上 资料来源：README.md。

运行时架构

YAML Agent Factory

yaml_agent_factory.py 是运行时入口之一，提供 YamlAgentFactory 类，将 YAML/.md 配置解析为 YamlConfiguredAgent 实例，并返回已通过 @tool 装饰的工具列表 资料来源：src/lib/smolagents/agent/yaml_agent_factory.py。该工厂使用基于文件路径的线程安全缓存 _tool_cache，避免重复加载 资料来源：src/lib/smolagents/agent/yaml_agent_factory.py。

校验与 Schema

agent_validation.py 负责约束 Worker Agent 的配置形状。validate_worker_agents_config 强制要求 worker_agents 列表中每项必须为字典且仅含 path 字段，禁止误用 name，并在收集错误后统一以 ValueError 抛出 资料来源：src/lib/smolagents/agent/agent_validation.py。agent_function_schema 校验则要求 output.description 非空、输入参数统一规范化为 string 类型以保持稳定契约 资料来源：src/lib/smolagents/agent/agent_validation.py。

Loom Mixin 与 Todo 同步

loom_mixin.py 在 _run_stream 中重写注入 Todo 同步 ActionStep，并在解析失败时构建错误恢复消息（build_recovery_message、分类感知 L1 引导），使 Agent 在连续解析失败时可获得结构化提示 资料来源：src/lib/smolagents/agent/loom_mixin.py。todo_sync.py 中的 _DEFAULT_TODO_INIT / _DEFAULT_TODO_UPDATE / _DEFAULT_TODO_FINAL 模板通过 <tool_restriction> 强制要求 Agent 只能调用 todo_write，确保 Todo 列表的全量替换而非追加 资料来源：src/lib/smolagents/agent/todo_sync.py。

工具系统

多模型路由

model_manager.py 与 model_types.py 一起提供多模型管理：ModelType 动态注册 POWERFUL / FAST / SUMMARY / CUSTOM 等类型 资料来源：src/lib/smolagents/models/model_types.py；ModelTypeManager.resolve_model_type 在未指定时回退到 config/llm.yaml 中的 default_model_type，缺失则立即抛出 ValueError，避免隐式回退 资料来源：src/lib/smolagents/models/model_types.py。_build_model_config_from_yaml 解析 extra_headers（支持 dict 或 JSON 字符串），并将其透传至 ModelConfig 资料来源：src/lib/smolagents/models/model_types.py。

Codex 作为 Function Tool

v1.0.1 引入本地 codex exec 封装能力，使 Codex 可像普通工具一样被 Agent 调用；同期新增的 fixed_args 允许在 YAML 中锁定工具参数，防止 LLM 覆盖 资料来源：README.md。yaml_agent_factory.py 中的 _get_fixed_tool_args 与 _bind_fixed_tool_args 会在签名分析后将 fixed_args 绑定到工具函数上，若固定参数与 **kwargs 冲突则会显式报错 资料来源：src/lib/smolagents/agent/yaml_agent_factory.py。

flowchart LR
    YAML[YAML Agent 配置] --> Factory[YamlAgentFactory]
    Factory --> Agent[YamlConfiguredAgent]
    Factory --> Tools[工具列表 @tool]
    Tools --> Builtin[内置 file/shell/edit/git/todo/skill]
    Tools --> Codex[Codex Function Tool]
    Tools --> MCP[MCP 客户端]
    Agent --> Mixin[Loom Mixin]
    Mixin --> Todo[todo_write 同步]
    Agent --> Models[Model Manager 多模型路由]

工具注册验证

tool_registry_markdown_validation 应用通过 loom run 直接执行 markdown_report_agent.yaml，显式启用 core_file 与 markdown_report 工具集，是验证非默认工具集注册行为的最小用例 资料来源：applications/tool_registry_markdown_validation/README.md。

可观测性

日志、检查点与 Dashboard

README.md 列举的运行时检查包括 uv run loom list-tasks、uv run loom dashboard 与 .logs/ 目录，支撑长任务的状态查询、仪表盘查看与原始日志回溯 资料来源：README.md。repo_map 应用进一步在 .repo_map/ 下持久化 analysis_progress.json，可从 AgentLoom checkpoint 恢复 LLM 分析阶段 资料来源：applications/repo_map/README.md。

常见失败模式

社区已记录的 Windows 平台原子写入失败问题（WinError 183）会影响 checkpoint、task index 与心跳持久化，需在 os.rename 之前处理已存在文件 资料来源：README.md。Codex 工具运行依赖两个前置条件：本地 codex CLI 可在 PATH 中访问；codex login status 通过；社区已提出 preflight validation 提案，在 workflow 启动前进行登录态预检 资料来源：README.md。浏览器类工具（如 browser_harness_probe）则受 Chrome remote debugging 授权影响，Agent 与工具本身加载正常时仍可能因浏览器侧配置失败 资料来源：applications/browser_harness_probe/README.md。

See Also

• 主页：README.md
• 配置校验：src/lib/smolagents/agent/agent_validation.py
• 多模型管理：src/lib/smolagents/models/model_manager.py
• Repo Map 应用：applications/repo_map/README.md
• 工具注册验证：applications/tool_registry_markdown_validation/README.md

概述与定位

AgentLoom 的应用生态围绕"以 YAML 配置驱动多 Agent 应用"这一核心模式展开，所有示

Pitfall Log / 踩坑日志

项目：linora-u/AgentLoom

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/linora-u/AgentLoom | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/linora-u/AgentLoom | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/linora-u/AgentLoom | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/linora-u/AgentLoom | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/linora-u/AgentLoom | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/linora-u/AgentLoom | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/linora-u/AgentLoom | release_recency=unknown