# https://github.com/linora-u/AgentLoom 项目说明书

生成时间：2026-06-25 09:54:20 UTC

## 目录

- [Overview & Runtime Architecture](#page-1)
- [Configuration System (YAML, LLM, Skills, MCP, Hooks)](#page-2)
- [Runtime, Tools & Observability](#page-3)
- [Application Ecosystem & Extensions (Examples, Codex Tool, Self-Learning)](#page-4)

<a id='page-1'></a>

## Overview & Runtime Architecture

### 相关页面

相关主题：[Configuration System (YAML, LLM, Skills, MCP, Hooks)](#page-2), [Runtime, Tools & Observability](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- [applications/repo_map/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/README.md)
- [src/lib/smolagents/models/model_types.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_types.py)
- [src/lib/smolagents/models/model_manager.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_manager.py)
- [src/lib/smolagents/agent/yaml_agent_factory.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/yaml_agent_factory.py)
- [src/lib/smolagents/agent/agent_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/agent_validation.py)
- [src/lib/smolagents/agent/todo_sync.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/todo_sync.py)
- [applications/tool_registry_markdown_validation/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/tool_registry_markdown_validation/README.md)
- [applications/browser_harness_probe/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/browser_harness_probe/README.md)
</details>

# Overview & Runtime Architecture

## 项目定位与目标

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]()

```mermaid
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](https://github.com/linora-u/AgentLoom/issues/4)

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

## See Also

- [Model & Configuration](model-and-configuration.md) — 模型类型解析与 llm.yaml 配置
- [Tool Registry & Function Tools](tool-registry.md) — 工具注册与 `fixed_args` 机制
- [Checkpoint & Resume](checkpoint-and-resume.md) — 断点恢复与长任务执行
- [Codex Tool Integration](codex-tool.md) — 本地 Codex Exec Function Tool

---

<a id='page-2'></a>

## Configuration System (YAML, LLM, Skills, MCP, Hooks)

### 相关页面

相关主题：[Overview & Runtime Architecture](#page-1), [Runtime, Tools & Observability](#page-3), [Application Ecosystem & Extensions (Examples, Codex Tool, Self-Learning)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [config/system.yaml](https://github.com/linora-u/AgentLoom/blob/main/config/system.yaml)
- [config/llm.example.yaml](https://github.com/linora-u/AgentLoom/blob/main/config/llm.example.yaml)
- [config/.mcp.json.example](https://github.com/linora-u/AgentLoom/blob/main/config/.mcp.json.example)
- [src/lib/config/config.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/config/config.py)
- [src/lib/config/layered_builder.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/config/layered_builder.py)
- [src/lib/config/config_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/config/config_validation.py)
- [src/lib/smolagents/models/model_types.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_types.py)
- [src/lib/smolagents/models/model_manager.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_manager.py)
- [src/lib/smolagents/agent/yaml_agent_factory.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/yaml_agent_factory.py)
- [README.md](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- [applications/codex_exec_demo/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/codex_exec_demo/README.md)
</details>

# Configuration System (YAML, LLM, Skills, MCP, Hooks)

## 概述与设计目标

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

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

| 配置类别 | 主要文件 | 作用 |
| --- | --- | --- |
| 系统配置 | `config/system.yaml` | 全局参数、模型默认类型、Skills 列表 |
| LLM 配置 | `config/llm.yaml` | 多模型类型（powerful / fast / summary / custom）的连接参数 |
| MCP 配置 | `config/.mcp.json` | 外部 Model Context Protocol 客户端服务器声明 |
| 应用配置 | `applications/<app>/workflows/*.yaml` | 各应用的 Supervisor / Worker Agent 与工具编排 |

所有配置在加载时通过 [src/lib/config/config.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/config/config.py) 中的全局对象 `C` 暴露，业务代码通过 `C.llm.for_type("powerful")` 之类的接口读取，避免硬编码路径。

## 分层配置与合并策略

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

合并完成后，配置会进入 [src/lib/config/config_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/config/config_validation.py) 走 schema 校验，校验失败会立刻抛错，避免错误配置被延后到运行期才发现。

## LLM 模型类型解析

`ModelType` 是 LLM 配置的核心抽象，定义在 [src/lib/smolagents/models/model_types.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_types.py) 中。框架预置四个标准类型：`POWERFUL`、`FAST`、`SUMMARY`、`CUSTOM`，同时支持 YAML 中声明的自定义类型。

```mermaid
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](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_manager.py) 转换为 `litellm.completion()` 调用参数。

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

## Agent、Workflow 与 fixed_args 工具

[YamlAgentFactory](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/yaml_agent_factory.py) 是 Agent 编排的入口。它接受 YAML 配置或 Markdown 块，构造 `YamlConfiguredAgent` 实例，并自动将 Worker Agent 暴露为 Supervisor 可调用的工具（`agent_as_tool()` 工厂模式）。每个调用都会创建**新的 Agent 实例**以避免 `memory.steps` 并发污染。

v1.0.1 新增的 `fixed_args` 字段（见 [applications/codex_exec_demo/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/codex_exec_demo/README.md)）允许在 YAML 中**锁定工具输入**，防止 LLM 在 `tool_call` 模式下覆盖关键参数：

```yaml
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](https://github.com/linora-u/AgentLoom/blob/main/applications/browser_harness_probe/README.md)）。
- **MCP 客户端**：通过 `config/.mcp.json` 声明外部 MCP server，框架读取后将其提供的工具并入 Agent 工具集。
- **Hooks**：通过 YAML 中的 `hooks` 块定义生命周期事件（pre-step、post-step、on-error 等），匹配规则与执行行为详见官方文档 [Hooks Reference](https://github.com/linora-u/AgentLoom/blob/main/docs/en/hooks.md)。
- **框架级 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](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- [Skills Configuration](https://github.com/linora-u/AgentLoom/blob/main/docs/en/skills_config.md)
- [Hooks Reference](https://github.com/linora-u/AgentLoom/blob/main/docs/en/hooks.md)
- [Checkpoint Resume](https://github.com/linora-u/AgentLoom/blob/main/docs/en/checkpoint.md)

---

<a id='page-3'></a>

## Runtime, Tools & Observability

### 相关页面

相关主题：[Overview & Runtime Architecture](#page-1), [Configuration System (YAML, LLM, Skills, MCP, Hooks)](#page-2), [Application Ecosystem & Extensions (Examples, Codex Tool, Self-Learning)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- [src/lib/smolagents/agent/yaml_agent_factory.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/yaml_agent_factory.py)
- [src/lib/smolagents/agent/agent_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/agent_validation.py)
- [src/lib/smolagents/agent/loom_mixin.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/loom_mixin.py)
- [src/lib/smolagents/agent/todo_sync.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/todo_sync.py)
- [src/lib/smolagents/models/model_manager.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_manager.py)
- [src/lib/smolagents/models/model_types.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_types.py)
- [applications/repo_map/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/README.md)
- [applications/tool_registry_markdown_validation/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/tool_registry_markdown_validation/README.md)
- [applications/browser_harness_probe/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/browser_harness_probe/README.md)
</details>

# 运行时、工具与可观测性

## 概览

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]()。

```mermaid
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](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- 配置校验：[src/lib/smolagents/agent/agent_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/agent_validation.py)
- 多模型管理：[src/lib/smolagents/models/model_manager.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_manager.py)
- Repo Map 应用：[applications/repo_map/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/README.md)
- 工具注册验证：[applications/tool_registry_markdown_validation/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/tool_registry_markdown_validation/README.md)

---

<a id='page-4'></a>

## Application Ecosystem & Extensions (Examples, Codex Tool, Self-Learning)

### 相关页面

相关主题：[Configuration System (YAML, LLM, Skills, MCP, Hooks)](#page-2), [Runtime, Tools & Observability](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/linora-u/AgentLoom/blob/main/README.md)
- [applications/repo_map/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/README.md)
- [applications/repo_map/repo_map_app.py](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/repo_map_app.py)
- [applications/repo_map/workflows/repo_map_agent.yaml](https://github.com/linora-u/AgentLoom/blob/main/applications/repo_map/workflows/repo_map_agent.yaml)
- [src/lib/smolagents/agent/yaml_agent_factory.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/yaml_agent_factory.py)
- [src/lib/smolagents/agent/agent_validation.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/agent/agent_validation.py)
- [src/lib/smolagents/models/model_types.py](https://github.com/linora-u/AgentLoom/blob/main/src/lib/smolagents/models/model_types.py)
- [applications/tool_registry_markdown_validation/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/tool_registry_markdown_validation/README.md)
- [applications/browser_harness_probe/README.md](https://github.com/linora-u/AgentLoom/blob/main/applications/browser_harness_probe/README.md)
</details>

# Application Ecosystem & Extensions (Examples, Codex Tool, Self-Learning)

## 概述与定位

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

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: linora-u/AgentLoom; human_manual_source: deepwiki_human_wiki -->