Metadata-Version: 2.4
Name: omnicrawl-agent
Version: 0.1.4
Summary: Local OmniCrawl agent with TUI, tools, MCP and NPM Hook plugins
Author: OmniCrawl
License: MIT
Project-URL: Repository, https://github.com/cccchiban/omnicrawl
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.68.0
Requires-Dist: markdown>=3.4.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: textual<9.0,>=8.2.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: google-genai>=1.0.0
Provides-Extra: windows
Requires-Dist: pywin32>=306; extra == "windows"
Dynamic: license-file

# OmniCrawl

本目录实现本地 OmniCrawl，提供终端 TUI 和本机 HTTP/SSE API：

1. TUI 使用键盘交互，HTTP API 供后续 Web 或桌面前端接入。
2. 通过统一模型运行时调用多家协议：OpenAI Chat Completions / Responses、Anthropic Messages、Google Gemini Generate Content（各用原生 SDK）。
3. AI 会按 Agent 循环处理任务：理解目标、读取项目文件、搜索文本、写文件或执行命令；默认会在工具执行前拦截确认，也可开启自动审批模式。
4. AI 回复会在 TUI 中显示，或通过 SSE 事件流推送给 API 客户端。
5. 支持多 Profile、`models.yaml` 自定义模型目录，以及 TUI `/model` 双列热切换（不重启、不清空会话）。
6. 提供默认关闭的定义式 SubAgent：支持 1–4 个 `fresh`/受控 `fork` 任务、后台管理、模型覆盖、跨进程安全快照恢复和 Session/SSE/TUI/API 生命周期观察。默认角色仅只读；`verify` 只能运行固定检查；通用写 Agent 必须显式开启，并优先在独立 Git worktree 中执行，由父 Agent 决定应用或丢弃结果。

## Agent 临时目录

项目内置 `.agent_tmp/` 作为 Agent 专用临时目录，用于存放一次性文件、图片、代码、视频和脚本，避免把临时产物散落在项目根目录。

```text
.agent_tmp/
├── files/    # 普通临时文件和中间结果
├── images/   # 截图、生成图片和图像处理中间文件
├── code/     # 一次性验证代码、草稿代码和临时样例
├── videos/   # 临时视频、录屏和转码中间文件
└── scripts/  # 只为当前任务服务的临时脚本
```

Agent 启动时会自动创建该目录，并通过 `.agent_tmp/.last_cleanup` 的文件时间记录上次清理时间；距离上次清理超过 24 小时时，启动阶段会立即补清理一次，运行期间也会继续按间隔清理。`.agent_tmp/README.md`、`.agent_tmp/.gitignore` 和 `.agent_tmp/.last_cleanup` 会被保留，其他临时内容会被清理后重建分类子目录。

## Agent 能力

程序启动后，普通对话会直接进入 Agent 模式，不需要额外输入 `/agent`。

启动时会自动检测当前要操作的项目路径：优先使用 `AI_WORKSPACE_ROOT` 环境变量；否则使用启动 Agent 时的目录，并向上查找 `.git`、`AGENTS.md`、`pyproject.toml`、`package.json`、`requirements.txt` 等常见项目标记。检测到的工作区会显示在启动面板的 `workspace` 行，并注入系统提示词，后续文件工具都会以该目录作为访问边界。

内置工具：

- `list_files`：列出工作区文件，默认执行前会要求确认。
- `read_file`：读取工作区内 UTF-8 文本文件，默认执行前会要求确认。
- `read_file` 支持 `start_line`/`max_lines` 行范围、`function_name` 函数或方法定位，以及 `text`/`context_lines` 文字片段上下文定位；Python 优先使用 AST，其他常见代码使用声明与大括号范围回退。
- `search_text`：在工作区内搜索文本或正则，默认执行前会要求确认。
- `replace_text`：替换单个文件中的文本，默认执行前会要求确认。
- `write_file`：写入或追加文件，默认执行前会要求确认。
- `bash`：使用 Git Bash 执行 Bash 命令，只接受 POSIX Shell 语法；可用独立 `diagnostic_command` 在主命令后采集日志，默认执行前会要求确认。
- `powershell`：使用 PowerShell 执行 Windows 命令，只接受 PowerShell 语法并优先使用 PowerShell 7；同样支持独立 `diagnostic_command`，默认执行前会要求确认。
- `monitor`：受 Agent 管理地在后台执行命令，默认使用 PowerShell，也可显式指定 Bash；`start` 返回任务 ID，`poll` 按游标读取增量日志，`stop` 停止任务，`list` 查看任务。Agent 关闭或切换工作区时会自动终止其子进程树，默认执行前会要求确认。
- Windows 原生桌面工具（仅 Windows）：`windows_window` 枚举/读取/激活窗口，`windows_control` 使用 UI Automation 查找并操作控件，`windows_input` 通过 SendInput 模拟鼠标键盘，`windows_clipboard` 读写 Unicode 文本剪贴板，`windows_screenshot` 截取虚拟桌面/区域/窗口并在模型支持 vision 时直接提供图片；五项均默认要求确认，并按调用顺序串行执行。Windows 工具的历史设计文档已归档至飞书知识空间 `ocl`。
- `subagent`：仅在 `subagents.enabled=true` 时注册；支持有界批量 `run`、后台 `spawn`、`list/get/cancel`，以及显式开启后的 `fork`、模型覆盖和 Worktree `list/apply/discard` 控制。默认角色仅只读；`verify` 只能调用固定检查标识，通用写 Agent 与 Worktree 均需额外开关。

安全边界：

- 文件工具只能访问当前项目目录内的路径；`config.yaml`、`models.yaml` 和历史 `config.json`、`.env`、`.git`、虚拟环境和缓存目录仍是受保护路径。
- `approval.mode` 默认为 `manual`，所有受限工具都会先在终端显示确认页；按 `Enter`、`Y` 或 `1` 允许，按 `N` 或 `2` 拒绝；方向键只会被消费，不会触发工具执行。
- `approval.mode` 设为 `auto` 时完全自动批准受限工具；设为 `review` 时只把疑似删除行为交给同一模型的非思考模式审查，其他工具调用自动执行。自动模式不显示确认页，只显示步骤和执行记录。
- 命令工具不是系统级沙箱；所有命令均通过明确的 PowerShell 或 Git Bash 解释器以 `shell=False` 启动，并由 Host 注入 UTF-8 子进程环境。不要混用两种 Shell 的语法。需要在测试或构建失败后读取日志时，应把主操作放入 `command`、日志读取放入 `diagnostic_command`；两者独立执行，任一失败都会使工具返回失败，诊断步骤不会掩盖主命令退出状态。确认前请检查命令内容，尤其是删除、移动、覆盖、联网下载、安装依赖、修改系统配置等操作。
- Windows 桌面工具不能突破 UAC、安全桌面、锁屏、受保护媒体或跨权限（UIPI）边界；不要用它们绕过访问控制。输入文本与剪贴板写入内容不会进入确认页或工具参数会话记录；截图 Base64 只存在于当前模型工具循环，不写入 Session 或长期历史。读取剪贴板和截图结果仍应按敏感数据处理。
- MCP 默认关闭；开启后会在启动时发现已启用的 MCP Server，并把 Tool 以 `server.tool` 名称追加到 Agent 工具列表，同时按需读取 Resource 和 Prompt。单个 Server 失败只会显示降级诊断，不影响内置工具。
- SubAgent 默认关闭。`delegated-read-only` 角色继承父 Host 已注册的 MCP Tool/Resource/Prompt、Skill 上下文、桌面/浏览器工具及其他外部能力，但硬性移除 `write_file`、`replace_text`、`memory_write` 和递归 `subagent`。`bash`、`powershell`、`monitor` 只允许通过 Host 只读命令策略的查询、联网和浏览器 CLI 命令；重定向、脚本解释器、文件原地修改、Git 变更及未知命令会在执行前拒绝。MCP 的外部副作用由 MCP 自身权限和 Host 审批约束，不等同于本地工作区写权限。fresh 子任务在入队前冻结父 Skill 索引或当前活动 Skill 正文，Fork 继续使用冻结的父公开上下文。模型任务参数仍不能提交自定义工具、Skill、MCP Server 或 permission profile。显式设置 `subagents.enable_verify_agent=true` 后，内置 `verify` 只获得固定读取工具与子任务私有 `verify_command`。通用写 Agent 仍需显式开启 standard/worktree 开关。父 Session 归档/恢复会取消旧会话子任务，结果继续经过脱敏、裁剪和受控 artifact 持久化。
- Agent 不再限制主循环的连续工具步骤；系统提示要求证据充分后及时收尾，并禁止在状态未变化时重复相同读取、搜索或验证。SubAgent 按角色定义和全局配置限制模型回合、工具次数与调用边界时间，工具 Schema 只列出当前配置可执行的角色；子任务模型请求失败后不自动重试，而是返回带有脱敏 `diagnostic`（错误分类、异常类型、Provider、状态码和可重试性）的结构化错误交还主 Agent。主 Agent 遇到 `SUBAGENT_MODEL_ERROR` 时不得只更换角色重复调用，除非运行环境已改变或用户明确要求重试。时间预算会阻止继续启动新步骤，并收紧单次模型请求超时，但无法强制终止不响应取消的第三方 SDK 或系统调用。主 Agent 返回空响应时会最多尝试 5 次，每次请求超时 180 秒。可通过环境变量调整：

```powershell
$env:AGENT_REQUEST_RETRY_COUNT = "5"
$env:AGENT_REQUEST_TIMEOUT_SECONDS = "180"
$env:AGENT_COMMAND_TIMEOUT_SECONDS = "360"
python main.py
```

## Hook 插件（NPM）

OmniCrawl 支持在 Host 生命周期节点分发 Hook，并通过独立 Node Worker 加载 NPM 插件。默认关闭，不影响现有 TUI / Skill / MCP / Session。

```powershell
# 诊断环境（源码入口和安装入口均可）
python main.py plugin doctor
ocl plugin doctor
omnicrawl plugin doctor   # 兼容入口

# 启用全局插件系统（写入用户配置目录的 config.yaml）
ocl plugin system enable

# 注册本地开发插件（dev 模式，不进可回滚 store）
ocl plugin install .\path\to\plugin --dev --project

# 从 NPM 安装（需 Node 20+；强制 --ignore-scripts）
ocl plugin install @scope/name@1.2.3 --project --enable --yes

ocl plugin list
ocl plugin disable @scope/name --project
ocl plugin rollback @scope/name --project
```

TUI 内可输入 `/plugins` 查看当前 Worker 只读状态；安装/更新/卸载仍走进程级 CLI。输入 `/settings` 可打开中文设置面板，修改模型、推理强度、上下文长度（32K–2048K）、审批模式、记忆、MCP、插件、子任务和上下文压缩总开关；修改立即生效并持久化到用户配置目录。上下文压缩默认关闭，开启后仅在完整回合结束且预计下一次请求达到 70K Token 时使用模型辅助压缩，并同步启用受当前摘要约束的证据恢复工具。压缩完成时，项目目标、约束、决策、完成/当前状态、文件产物和后续事项会自动同步到本地长期记忆；`/compact` 与 `/compact --model` 同样生效，记忆写入失败不会影响会话压缩。上下文长度按当前活动模型保存：自定义模型写入 `models.yaml`，其他模型写入 `config.yaml` 默认值。高风险的 Worktree、共享写入和网络安装等细项不会通过面板开放。

插件架构历史设计文档已归档至飞书知识空间 `ocl`。注意：Worker 隔离用于故障边界，**不是**恶意代码沙箱；只安装可信插件。插件若要提供最低优先级的 Agent Markdown 定义，必须在 manifest 的 `omnicrawl.agents` 中声明包内路径，并同时声明且获批 `agent:definitions` 权限。

## 安装依赖

运行终端工作台需要 Python `>=3.9,<4.0`。

### 从源码运行

```powershell
pip install -r requirements.txt

# 可选：安装可编辑 console script；同时提供 ocl 和 omnicrawl 两个命令
pip install -e . --no-build-isolation
```

### 从 PyPI 安装

```powershell
python -m pip install omnicrawl-agent
```

安装完成后，推荐使用短命令 `ocl`；旧命令 `omnicrawl` 仍保留兼容：

```powershell
ocl
# 等价兼容入口
omnicrawl
```

首次启动会按配置查找顺序选择 `config.yaml` 和 `models.yaml`：优先读取环境变量指定路径，其次读取用户配置目录 `~/.OmniCrawl`；仅源码开发环境在用户目录没有文件时才回退到当前工作目录和项目根目录。所有未显式指定路径的配置写入都固定保存到 `~/.OmniCrawl`，并打开模型渠道配置向导。向导预置 OpenAI、Anthropic、Gemini 三种请求方式；OpenAI 可选择 Chat Completions 或 Responses 协议。每个渠道独立配置渠道名称、Base URL、API Key 和模型 ID，同一种请求方式可通过 `A` 添加多个不同渠道。

渠道列表使用 `↑↓` 选择、`空格` 启用或禁用、`Enter` 编辑、`A` 添加、`D` 二次确认删除、`F` 设为默认，最后按 `Ctrl+S` 保存。API Key 仅写入实际使用的本机 `config.yaml`，不会进入 `models.yaml` 或发布包。所有系统统一使用用户主目录下的 `~/.OmniCrawl` 保存配置。升级后首次启动会将旧的 `%APPDATA%\\OmniCrawl`、`~/.config/omnicrawl` 或 `~/.omnicrawl` 内容迁移到新目录；迁移成功后旧目录会被删除，冲突文件会保留为 `.migrated.bak` 备份。如果首次启动没有保存至少一个已启用且具备 Key 的默认渠道，程序会显示提示并退出，配置完成后重新运行 `ocl` 即可。

首次启动还会检查 Node.js、模型目录和插件注册状态。Node.js 或插件检查失败只会影响插件功能，不会阻止无插件模式启动。

TUI 首屏显示后会在后台通过 PyPI RSS 检查 `omnicrawl-agent` 最新版本，请求超时为 3 秒，成功结果在用户配置目录的 `version-check.json` 中缓存 24 小时。右上角始终显示当前版本；发现更新时显示 `v当前版本 ↑ v最新版本`，并在对话区提示 `pip install --upgrade omnicrawl-agent`。离线、代理、RSS 或缓存异常均静默降级，不会延迟或阻止启动。

## 运行

### 终端 TUI

安装包启动：

```powershell
ocl
```

源码目录启动仍可使用：

```powershell
python main.py
```

从 IDE、测试窗口或普通命令行运行时，源码入口的 Windows 行为可能会弹出独立 PowerShell 窗口；`ocl` 和 `python -m omnicrawl` 在当前控制台运行。

### 本地 HTTP/SSE API

```powershell
$env:OMNICRAWL_API_TOKEN = "请替换为随机长令牌"
python -m omnicrawl.api
```

默认监听 `127.0.0.1:8765`。Swagger UI 位于 `http://127.0.0.1:8765/docs`，
机器可读契约位于 `/openapi.json`。除健康检查和文档外，所有接口必须携带
`Authorization: Bearer <token>`。完整接入说明见 `omnicrawl/docs/API.md`。

运行后：

- TUI 会以透明背景启动为全屏 Textual 工作台，继承终端默认前景色、背景色和 ANSI 调色板；顶部 HUD 显示工作区、模型、推理、审批和 Token 摘要，主区保留对话、工具记录，以及始终跟随最新内容的临时运行状态，输入框固定在底部。
- 在输入框按 Enter 发送消息；任务生成期间提交的消息会进入 FIFO 队列，当前回合结束后自动逐条发送，对话区会显示当前排队数量。
- 需要人工审批的工具会显示居中确认模态框；选择“允许执行”或“拒绝”后继续，按 `Esc` 会取消当前任务并拒绝等待中的确认。
- 输入 `/new`：清空模型对话历史，开启新对话。
- 输入 `/undo`：持久化回退最近一轮用户消息与助手回复；若该轮被取消则回退未完成轮次。命令可连续执行，但不会撤销已经产生的文件修改、命令执行等外部副作用。
- 输入 `/skills`：查看已加载的 Skill；输入 `/skill:<名称> 任务` 可手动调用指定 Skill。
- 输入 `/mcp`：查看 MCP 开关、Server 连接状态、已发现能力和最近诊断。
- 输入 `/model`：打开双列模型选择界面（自定义 `models.yaml` + API 自动发现）；列表默认获得焦点，使用 `↑↓` 选择、`←→` 切列、`Enter` 确认，按 `/` 可进入搜索框；`/model --refresh` 刷新发现缓存；`/model <key|alias|model_id|profile/model_id>` 直接切换。
- 输入 `/settings`：打开运行设置；选择“模型渠道”可再次进入渠道管理界面，新增、编辑、启用、禁用、删除渠道或切换默认模型，保存后当前 Agent 立即重新加载默认渠道。
- 输入 `/approval`：查看当前工具审批模式；输入 `/approval:manual`、`/approval:auto`、`/approval:review` 可切换审批模式并同步写入配置文件。
- 任务执行中按 `Esc`：请求取消当前操作；空闲时按 `Esc` 聚焦输入框。`Ctrl+C` 在输入框有选区时复制选中文本，无选区时清空输入框；`Ctrl+L` 只清空当前视图，不清空会话数据。可按 `Ctrl+Q`、输入 `退出`/`结束` 或关闭窗口退出工作台。

终端 UI 的设计和限制见 `omnicrawl/docs/TERMINAL_UI.md`。
Skill 安装、编写和渐进式披露规范见 `omnicrawl/docs/SKILL_INSTALLATION.md`。
运行时系统提示词模板见 `omnicrawl/agent/system_prompt.md`；模板只保留工具协议和按场景读取文档的路由说明，具体规范按需读取对应文档。

如果需要从固定位置启动 Agent 但操作另一个项目，可以显式指定工作区：

```powershell
$env:AI_WORKSPACE_ROOT = "D:\path\to\your-project"
python main.py
```

## 项目结构

```text
.
├── main.py                     # 程序启动入口，保持 python main.py 运行方式
├── omnicrawl/                  # 业务模块包
│   ├── __init__.py              # 旧路径兼容导出（session/memory/llm 等）
│   ├── agent/                   # Agent 主循环与工具/协议/历史
│   │   ├── __init__.py           # 稳定公共 API 导出
│   │   ├── core.py               # LocalToolAgent 外层生命周期与 Host 接线
│   │   ├── execution.py           # 可复用 AgentLoopRunner
│   │   ├── subagents/             # 定义注册表、协调器及内置角色/后台/恢复/Worktree
│   │   ├── tools.py / history.py / llm_protocol.py
│   │   ├── windows_desktop.py     # Windows 窗口、UIA、输入、剪贴板与截图原生工具
│   │   └── system_prompt.md       # 运行时系统提示词模板
│   ├── mcp/                     # MCP 配置、安全、审计、客户端与内置 Server
│   ├── api/                     # FastAPI + SSE 接口
│   │   ├── app.py / service.py / models.py / deps.py
│   │   └── routes/                # 按资源分组的 HTTP 路由
│   ├── state/                   # Session、Memory、Project 存储
│   │   ├── session*.py            # 会话门面与子域
│   │   └── memory*.py             # 记忆存储与排序纯逻辑
│   ├── config/                  # LLM、审批、运行时与模型目录
│   │   ├── llm.py / llm_multi.py # LLMConfig、多 Profile 与 active_model
│   │   ├── llm_client.py         # OpenAI Responses 网络客户端（遗留/审查）
│   │   ├── model_catalog.py      # 自定义 + 自动发现双列目录
│   │   ├── model_store.py        # models.yaml
│   │   ├── runtime.py            # 用户配置路径、严格 YAML 配置仓库
│   │   └── templates/            # 首次启动随 Wheel 分发的配置模板
│   ├── llm/                     # 统一模型协议、Runtime Manager、Provider Adapter
│   │   └── providers/            # openai_chat / openai_responses / anthropic / gemini
│   ├── workspace/               # 工作区工具、Monitor、临时目录
│   │   ├── monitor.py            # 后台任务生命周期
│   │   └── process_control.py    # Windows Job Object 平台实现
│   ├── ui/                      # 全屏 TUI、输入与兼容输出
│   │   └── fullscreen/           # Textual 工作台（含 model_picker）
│   ├── commands/                # 斜杠命令
│   └── extensions/              # Skill 等扩展
├── omnicrawl/docs/             # 随安装包分发的设计说明和实现文档
├── tests/                      # 单元与模块边界回归
├── config.example.yaml         # 多模型运行配置模板
├── models.example.yaml         # 自定义模型目录模板
└── requirements.txt            # Python 依赖
```

旧导入路径仍可用（例如 `omnicrawl.session`、`omnicrawl.memory`、`omnicrawl.llm`、`omnicrawl.skill`），实现位于上述真实子模块。历史架构设计文档已归档至飞书知识空间 `ocl`；随安装包分发的技术文档位于 `omnicrawl/docs/`。

## 可选配置

### 推荐：YAML 多模型配置

LLM 凭据、Profile 与当前模型推荐通过 `config.yaml` + `models.yaml` 提供。

```powershell
copy config.example.yaml config.yaml
copy models.example.yaml models.yaml
```

`config.yaml` 关键字段：

```yaml
version: 2
llm:
  active_model:
    source: custom
    key: default-chat
  profiles:
    openai-main:
      provider: openai
      base_url: "https://api.openai.com/v1"
      api_key_env: OPENAI_API_KEY
      default_protocol: openai_chat_completions
      discovery:
        enabled: true
```

`models.yaml` 只放模型元信息，**不要写 api_key**：

```yaml
version: 1
models:
  default-chat:
    display_name: "Default Chat Model"
    profile: openai-main
    model_id: gpt-5.2
    protocol: openai_chat_completions
    aliases: [default, chat]
    context_window_tokens: 128000
```

程序只读取 YAML 运行配置，不再解析、迁移或回退到 JSON。配置文件按以下顺序分别查找：

1. `AI_CONFIG_FILE` / `AI_MODELS_FILE` 指定的文件。
2. 用户配置目录：所有系统统一为 `~/.OmniCrawl`。
3. 仅源码开发环境中的当前工作目录和项目根目录；安装 Wheel 后不会从工作目录或 `site-packages` 回退读取配置。

未显式指定配置路径时，保存操作不会沿用读取到的项目目录路径，而是统一写入 `~/.OmniCrawl`；显式路径或环境变量仍可用于指定其他写入位置。

如果没有找到现有文件，首次启动会在 `~/.OmniCrawl` 创建 `config.yaml` 和 `models.yaml`。用户级全局规则放在 `~/.OmniCrawl/AGENTS.md`；当前项目目录中的 `AGENTS.md` 仍然保留，并且项目级规则优先于全局规则。插件注册表和用户级 SubAgent 定义也统一位于 `~/.OmniCrawl` 下。

源码开发时如需手工准备配置，可以复制到用户目录：

```powershell
New-Item -ItemType Directory -Force "$HOME\\.OmniCrawl"
Copy-Item config.example.yaml "$HOME\\.OmniCrawl\\config.yaml"
Copy-Item models.example.yaml "$HOME\\.OmniCrawl\\models.yaml"
```

如需将配置放到其他位置，可显式设置：

```powershell
$env:AI_CONFIG_FILE = "D:\\path\\to\\config.yaml"
$env:AI_MODELS_FILE = "D:\\path\\to\\models.yaml"
```

显式配置路径和 `AI_CONFIG_FILE` 也必须指向 `.yaml` 或 `.yml` 文件；传入 JSON 会直接报错。若工作区仍残留旧 `config.json`，程序不会读取它，并会提示根据 YAML 模板手工配置。历史 `config.json` 与 `*.migrated.bak` 仍被 `.gitignore` 保护，防止旧凭据误提交。

`config.yaml`、`models.yaml` 不要把真实密钥写进示例文件或源码。

工具审批可在配置文件的 `approval.mode` 配置：

- `manual`：默认人工确认。
- `auto`：完全自动批准所有受限工具调用。
- `review`：仅对疑似删除行为使用同一模型的非思考模式审查，审查通过后自动执行；非删除工具调用自动放行，不再进入模型审查。

SubAgent 各项能力通过 `subagents` 段独立启用，所有高风险能力默认关闭：

```yaml
subagents:
  enabled: false
  max_depth: 1
  max_concurrency: 2
  max_tasks_per_batch: 4
  model_request_concurrency: 2
  default_timeout_seconds: 3600
  allow_background: false
  allow_fork: false
  allow_worktree: false
  allow_standard_agent: false
  allow_shared_workspace_writes: false
  enable_verify_agent: false
  verify_command_timeout_seconds: 120
  task_retention_minutes: 60
```

启用后加载顺序为项目 `.omnicrawl/agents/*.md`、兼容项目 `.agents/agents/*.md`、用户 `~/.OmniCrawl/agents/*.md`、包内 `explore`/`plan`/`verify`/`general-purpose`、已批准插件定义；同名时高优先级来源获胜。环境变量只能关闭能力或收紧并发、超时等限制，不能扩大配置。当前实现支持每批 1–4 个同步任务、有界任务并发、独立模型请求限流、输入顺序聚合、失败隔离和同步 `fail_fast`；单个子任务不设模型回合或工具调用上限，默认超时为 3600 秒。默认仅只读，显式启用 `verify` 后只能执行固定的全量 unittest、compileall 和 `git diff --check`。显式设置 `allow_fork: true` 后可使用创建时冻结、脱敏的父公开上下文；任务模型按任务 > 角色定义 > 父模型解析并以独立 Runtime 运行。显式设置 `allow_background: true` 后支持 `spawn/list/get/cancel`，终态任务与未消费通知按 TTL 自动回收，通知只注入一次。父 Run 取消、Agent 关闭和工作区切换会级联取消并有界等待；跨进程恢复只导入安全任务快照，非终态任务折叠为 `SUBAGENT_INTERRUPTED`，不自动重跑或恢复 prompt、Runtime、审批和通知。显式开启 `allow_worktree` 与 `allow_standard_agent` 后，`general-purpose` 可在独立 worktree 写入，主工作树脏时拒绝创建/应用，父 Agent 通过控制动作审查并 apply/discard；共享工作区写入还需额外开启 `allow_shared_workspace_writes` 并受单写锁约束。跨父 Run 的后台审批记录仍仅存在于当前进程，不跨进程恢复；后台 `fail_fast` 尚未开放。

思考深度可在 `llm.reasoning_effort`（或 `llm.defaults.reasoning_effort`）配置，支持 `none`、`low`、`medium`、`high`、`xhigh`、`max`；也兼容 `x-high`、`x_high` 等写法。设置为 `low` 及以上会自动启用 thinking。

`context_window_tokens` 可写在自定义模型或 Profile 默认值中。全屏 TUI 顶部 Token 遥测行使用该值计算 `CTX` 占用率；`/model` 切换后 HUD 会刷新，最近 Token 显示会清零。

会话转录、PromptHistory、HTML 工具预览和 MCP 审计日志会清理常见 API Key、Token、Cookie、密码及 Bearer 凭据后再写入新记录。该保护只覆盖后续新写入内容；已存在的本地会话文件不会被程序自动重写，如需清理历史数据请先自行备份并人工审查。

### 模型目录与热切换

- 自定义模型：`models.yaml`（key、alias、protocol、能力、上下文窗口、`max_output_tokens`、`temperature`）。
  其中 `max_output_tokens` / `temperature` 会在每次请求时自动写入对应 Provider 的生成参数（OpenAI=`max_tokens`，Anthropic=`max_tokens`，Gemini=`max_output_tokens`）。
- 自动发现：各启用 Profile 通过对应原生 SDK / 兼容接口探测；失败只写诊断，不阻断自定义模型。
- TUI：`/model` 打开双列选择器；`/model --refresh` 刷新；`/model <选择>` 直接切换。
- API：
  - `GET /api/v1/models`：兼容旧扁平列表
  - `GET /api/v1/models/catalog`：双列 + diagnostics
  - `POST /api/v1/models/refresh`：刷新发现缓存
  - `PUT /api/v1/models/current`：切换当前模型（支持旧 `model` 字段与 `source/key`、`source/profile/model_id`）
- 环境变量：`OMNICRAWL_MODEL`、`OMNICRAWL_PROFILE` 优先；仍兼容 `OPENAI_MODEL` / `OPENAI_API_KEY` / `OPENAI_BASE_URL`。

设计细节与实施状态见 `omnicrawl/docs/` 中对应的技术文档；历史架构文档已归档至飞书知识空间 `ocl`。

MCP 可在配置文件的 `mcp` 段配置。当前实现支持本地 `stdio` 和远程 `streamable_http` MCP Server 的初始化、能力发现、工具调用、Resource 读取、Prompt 获取、审计日志和 `/mcp` 状态诊断；Streamable HTTP 支持 JSON/SSE 响应和 `Mcp-Session-Id` 会话复用。MCP Tool 默认需要审批，避免第三方 Server 通过模糊工具名绕过确认。内置 `local_project` Server 可通过 `python -m omnicrawl.mcp.server` 提供项目文档 Resource、健康状态 Resource 和常用 Prompt；工作区文件、搜索、写入及命令操作由 Agent 内置工具提供，不再通过 MCP 重复暴露。环境变量 `MCP_ENABLED`、`MCP_DEFAULT_TIMEOUT_SECONDS` 和 `MCP_MAX_TOOL_OUTPUT_CHARS` 可临时覆盖全局配置。全屏 TUI 中可通过 `/settings` 按“运行设置 → MCP 全局设置 → MCP Server”三级管理 MCP 总开关、安全策略、超时、输出限制以及 Server 的传输、地址/命令、风险等级和连接测试；stdio 环境变量只显示配置数量，凭据不会回显，Streamable HTTP 不会把这些变量隐式转换为请求头。MCP 的渐进式阅读、配置、调用和排障规范见 `omnicrawl/docs/MCP_USAGE.md`。

如果不想把 API Key 写入用户配置目录，也可以设置对应环境变量；环境变量优先于配置文件，便于临时覆盖本地配置：

```powershell
$env:OPENAI_API_KEY = "你的 API Key"
$env:OMNICRAWL_MODEL = "default-chat"   # 或 OPENAI_MODEL=裸模型ID
$env:OPENAI_THINKING_TYPE = "disabled"
$env:OPENAI_BASE_URL = "https://xxx.xx/v1"
ocl
```

如果要强制使用某个语音后端：

```powershell
$env:TTS_BACKEND = "system_speech"
python main.py
```

`pyttsx3` 在部分 Windows/Anaconda 环境会因为 SAPI COM 组件注册异常报“没有注册类”。程序默认不会再走这个后端；确实要测试时可设置。注意：`pyttsx3` 的跨线程打断能力不如默认的 `System.Speech` 稳定：

```powershell
$env:TTS_BACKEND = "pyttsx3"
python main.py
```

如果一直显示“未检测到语音”，通常是默认麦克风选错。优先在启动时按列表序号选择，或用设备名关键字固定选择：

```powershell
$env:MIC_DEVICE_KEYWORD = "Realtek"
python main.py
```

高级排查时也可以指定 PyAudio 底层设备编号：

```powershell
$env:MIC_DEVICE_INDEX = "22"
python main.py
```

Windows 上 PyAudio 会把同一物理设备通过多个音频后端重复列出。程序默认只展示更接近系统设置的 WASAPI 输入端点；如果需要排查全部 PortAudio 输入设备：

```powershell
$env:MIC_SHOW_ALL_INPUTS = "1"
python main.py
```
