Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(agent): share one configurable budget for web_fetch (#4432)

jack1fc00cdc08d8
diff --git a/.env.example b/.env.example
index 069f28296..fb0529a9c 100644
--- a/.env.example
+++ b/.env.example
@@ -637,6 +637,10 @@ WEKNORA_SANDBOX_DOCKER_ENABLED=false
# 智能体大模型调用默认超时(秒,默认 120;复杂推理调大如 300/600)。
# 注:全局默认;单个智能体在数据库配独立 llm_call_timeout 时以其为准。
# WEKNORA_AGENT_LLM_TIMEOUT=300
+# web_fetch 单页抓取预算(默认 3m)。HTTP 与 chromedp 共用这一预算,不叠加。
+# 支持 Go duration(150s、3m)或纯数字秒(180)。空值、无效值或非正数使用默认值。
+# 工具包装层再多等 5 秒,以便返回工具自己的超时结果。快速回答管道仍为 15s,不使用此项。
+# WEKNORA_WEB_FETCH_TIMEOUT=3m
# MCP 工具人工审核等待超时(秒,默认 600;支持 Go duration 如 30s/5m/1h)。
# WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=600
# MCP 工具人工审批失败时是否放行(true 放行 / 默认 fail-close 拒绝)。
diff --git a/docker-compose.yml b/docker-compose.yml
index a9321ceae..d79b93d13 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -350,6 +350,8 @@ services:
- WEKNORA_CHAT_ATTACHMENT_OCR_MAX_PAGES=${WEKNORA_CHAT_ATTACHMENT_OCR_MAX_PAGES:-8}
# Agent LLM call timeout
- WEKNORA_AGENT_LLM_TIMEOUT=${WEKNORA_AGENT_LLM_TIMEOUT:-}
+ # web_fetch 单页抓取预算(Go duration 或纯数字秒,默认 3m;HTTP 与 chromedp 共用,不叠加)
+ - WEKNORA_WEB_FETCH_TIMEOUT=${WEKNORA_WEB_FETCH_TIMEOUT:-}
- WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=${WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT:-}
# MCP 工具人工审批失败时是否放行(true 放行 / 默认 fail-close 拒绝)
- WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN=${WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN:-}
diff --git a/internal/agent/const.go b/internal/agent/const.go
index cadbc1422..60627a811 100644
--- a/internal/agent/const.go
+++ b/internal/agent/const.go
@@ -13,6 +13,7 @@ import (
"github.com/Tencent/WeKnora/internal/agent/compaction"
"github.com/Tencent/WeKnora/internal/browserskill"
+ webfetch "github.com/Tencent/WeKnora/internal/infrastructure/web_fetch"
"github.com/Tencent/WeKnora/internal/models/api"
"github.com/Tencent/WeKnora/internal/types"
"github.com/google/uuid"
@@ -36,7 +37,7 @@ const (
defaultLLMStallTimeout = 120 * time.Second
// defaultToolExecTimeout is the default maximum time for a single tool execution.
- // Prevents long-running tools (web_fetch, database_query) from hanging indefinitely.
+ // Prevents long-running tools (for example database_query) from hanging indefinitely.
defaultToolExecTimeout = 60 * time.Second
// shellExecToolTimeout is slightly longer than shell_exec's own hard
// 600-second command timeout so the tool can return a structured timeout
@@ -45,6 +46,10 @@ const (
// tryAgentToolTimeout is above the trial runner's own 4-minute limit so
// a slow trial still reports what the agent did before it was stopped.
tryAgentToolTimeout = 4*time.Minute + 30*time.Second
+ // webFetchToolSlack is how much longer the agent wrapper waits than the
+ // shared page-fetch budget. Same 5s headroom as shell_exec, so web_fetch can
+ // return its own timeout result instead of being cancelled first.
+ webFetchToolSlack = 5 * time.Second
// maxLLMRetries is the maximum number of retries for transient LLM errors.
maxLLMRetries = 2
@@ -99,6 +104,8 @@ func toolExecutionTimeout(toolName string, arguments ...string) time.Duration {
return shellExecToolTimeout
case "try_agent":
return tryAgentToolTimeout
+ case "web_fetch":
+ return webfetch.PageFetchTimeout() + webFetchToolSlack
}
return defaultToolExecTimeout
}
diff --git a/internal/agent/const_test.go b/internal/agent/const_test.go
index de7d24017..75f65a364 100644
--- a/internal/agent/const_test.go
+++ b/internal/agent/const_test.go
@@ -8,13 +8,33 @@ import (
)
func TestToolExecutionTimeout(t *testing.T) {
+ // shell_exec and browser human steps keep their longer budgets.
assert.Equal(t, 10*time.Minute+5*time.Second, toolExecutionTimeout("shell_exec"))
- assert.Equal(t, 60*time.Second, toolExecutionTimeout("web_fetch"))
for _, method := range []string{"request_help", "tab_borrow"} {
assert.Equal(t, 5*time.Minute+15*time.Second,
toolExecutionTimeout("local_browser", `{"method":"`+method+`"}`))
}
+ // knowledge_search and non-human browser calls stay at 60s.
+ assert.Equal(t, 60*time.Second, toolExecutionTimeout("knowledge_search"))
for _, args := range []string{`{"method":"click"}`, `{"method":"observe"}`, `{`} {
assert.Equal(t, 60*time.Second, toolExecutionTimeout("local_browser", args))
}
+
+ t.Run("default budget plus slack", func(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "")
+ assert.Equal(t, 3*time.Minute+5*time.Second, toolExecutionTimeout("web_fetch"))
+ })
+ t.Run("go duration", func(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "150s")
+ assert.Greater(t, toolExecutionTimeout("web_fetch"), 2*time.Minute+30*time.Second)
+ assert.Equal(t, 2*time.Minute+35*time.Second, toolExecutionTimeout("web_fetch"))
+ })
+ t.Run("bare seconds", func(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "180")
+ assert.Equal(t, 3*time.Minute+5*time.Second, toolExecutionTimeout("web_fetch"))
+ })
+ t.Run("invalid falls back", func(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "nope")
+ assert.Equal(t, 3*time.Minute+5*time.Second, toolExecutionTimeout("web_fetch"))
+ })
}
diff --git a/internal/agent/tools/web_fetch.go b/internal/agent/tools/web_fetch.go
index 4a549dc51..159efd9b3 100644
--- a/internal/agent/tools/web_fetch.go
+++ b/internal/agent/tools/web_fetch.go
@@ -7,7 +7,6 @@ import (
"net/url"
"strings"
"sync"
- "time"
"unicode/utf8"
webfetch "github.com/Tencent/WeKnora/internal/infrastructure/web_fetch"
@@ -16,10 +15,7 @@ import (
"github.com/Tencent/WeKnora/internal/utils"
)
-const (
- webPageFetchTimeout = 60 * time.Second
- webPageCacheLimit = 8
-)
+const webPageCacheLimit = 8
var webFetchTool = BaseTool{
name: ToolWebFetch,
@@ -164,7 +160,7 @@ func snapshotWaitTimeoutError(err error) error {
// storePage downloads independently of the caller's deadline so a short
// content=true timeout cannot cancel a shared fetch for concurrent web_fetch.
func (t *WebFetchTool) storePage(ctx context.Context, rawURL string) (webPageSnapshot, error) {
- fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), webPageFetchTimeout)
+ fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), webfetch.PageFetchTimeout())
defer cancel()
content, err := t.fetcher.Fetch(fetchCtx, rawURL)
if err != nil {
diff --git a/internal/agent/tools/web_fetch_test.go b/internal/agent/tools/web_fetch_test.go
index 8cbdc2576..7d4c23816 100644
--- a/internal/agent/tools/web_fetch_test.go
+++ b/internal/agent/tools/web_fetch_test.go
@@ -414,3 +414,25 @@ func TestWebFetchOwnerTimeoutDoesNotCancelSharedFetch(t *testing.T) {
assert.Equal(t, "owner page body", longResult.Data["results"].([]map[string]interface{})[0]["raw_content"])
assert.Equal(t, 1, fetcher.callCount[rawURL])
}
+
+type deadlineWebContentFetcher struct {
+ deadline time.Time
+ hasDeadline bool
+}
+
+func (f *deadlineWebContentFetcher) Fetch(ctx context.Context, _ string) (string, error) {
+ f.deadline, f.hasDeadline = ctx.Deadline()
+ return "page body", nil
+}
+
+func TestStorePageBudgetFollowsWebFetchTimeout(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "150s")
+ fetcher := &deadlineWebContentFetcher{}
+ tool := newWebFetchTool(fetcher)
+
+ _, err := tool.storePage(context.Background(), "https://example.com/slow")
+
+ require.NoError(t, err)
+ require.True(t, fetcher.hasDeadline)
+ assert.InDelta(t, 150, time.Until(fetcher.deadline).Seconds(), 2)
+}
diff --git a/internal/infrastructure/web_fetch/fetcher.go b/internal/infrastructure/web_fetch/fetcher.go
index e2236422c..92f1005bc 100644
--- a/internal/infrastructure/web_fetch/fetcher.go
+++ b/internal/infrastructure/web_fetch/fetcher.go
@@ -12,6 +12,7 @@ import (
"net"
"net/http"
"net/url"
+ "os"
"strings"
"time"
"unicode/utf8"
@@ -23,12 +24,39 @@ import (
)
const (
- fetchTimeout = 60 * time.Second
- pipelineFetchTimeout = 15 * time.Second
- maxBodySize = 100 * 1024
- maxAgentBodySize = 2 * 1024 * 1024
+ // defaultPageFetchTimeout is the agent web_fetch page budget when
+ // WEKNORA_WEB_FETCH_TIMEOUT is empty, invalid, or not positive. Three
+ // minutes covers a slow browser render plus HTTP fallback: a 150s cap is
+ // still shorter than the 150036ms success reported for this timeout.
+ defaultPageFetchTimeout = 3 * time.Minute
+ pipelineFetchTimeout = 15 * time.Second
+ maxBodySize = 100 * 1024
+ maxAgentBodySize = 2 * 1024 * 1024
)
+// PageFetchTimeout is the shared budget for one agent web_fetch page read.
+// The HTTP client, the fetch context, and chromedp all use this value.
+// Chromedp's deadline is a child of the fetch context, so the budgets do not add.
+//
+// WEKNORA_WEB_FETCH_TIMEOUT accepts a Go duration (150s, 3m) or a bare positive
+// number of seconds (180), the same pattern as WEKNORA_AGENT_LLM_TIMEOUT.
+// Empty, invalid, and non-positive values use defaultPageFetchTimeout.
+func PageFetchTimeout() time.Duration {
+ value := strings.TrimSpace(os.Getenv("WEKNORA_WEB_FETCH_TIMEOUT"))
+ if value == "" {
+ return defaultPageFetchTimeout
+ }
+ timeout, err := time.ParseDuration(value)
+ if err != nil {
+ // Bare number of seconds, for example "180".
+ timeout, err = time.ParseDuration(value + "s")
+ }
+ if err != nil || timeout <= 0 {
+ return defaultPageFetchTimeout
+ }
+ return timeout
+}
+
// ErrorCode identifies the stage and class of a fetch failure.
type ErrorCode string
@@ -116,7 +144,7 @@ type httpFetchResult struct {
// NewFetcher creates a production fetcher with DNS and redirect SSRF guards.
func NewFetcher() *Fetcher {
- f := newFetcher(fetchTimeout, renderWithChromium)
+ f := newFetcher(PageFetchTimeout(), renderWithChromium)
f.markdown = true
f.maxBodySize = maxAgentBodySize
return f
@@ -350,7 +378,9 @@ func renderWithChromium(ctx context.Context, target pinnedTarget) (string, error
defer cancelAllocator()
browserCtx, cancelBrowser := chromedp.NewContext(allocatorCtx)
defer cancelBrowser()
- browserCtx, cancelTimeout := context.WithTimeout(browserCtx, fetchTimeout)
+ // Child of the fetch context: a full PageFetchTimeout here cannot outlive
+ // the parent budget, so HTTP and chromedp share one deadline instead of stacking.
+ browserCtx, cancelTimeout := context.WithTimeout(browserCtx, PageFetchTimeout())
defer cancelTimeout()
var html string
if err := chromedp.Run(browserCtx,
diff --git a/internal/infrastructure/web_fetch/fetcher_test.go b/internal/infrastructure/web_fetch/fetcher_test.go
index e22d4a85d..af84fb124 100644
--- a/internal/infrastructure/web_fetch/fetcher_test.go
+++ b/internal/infrastructure/web_fetch/fetcher_test.go
@@ -133,7 +133,12 @@ func TestFetcherUsesBrowserFallbackForClientRenderedPage(t *testing.T) {
}
func TestNewFetcherKeepsAgentCompatibleTimeout(t *testing.T) {
- assert.Equal(t, 60*time.Second, NewFetcher().timeout)
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "")
+ assert.Equal(t, 3*time.Minute, NewFetcher().timeout)
+ assert.Equal(t, PageFetchTimeout(), NewFetcher().timeout)
+
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "150s")
+ assert.Equal(t, 150*time.Second, NewFetcher().timeout)
}
func TestNewPipelineFetcherUsesHTTPOnlyAndLegacyTimeout(t *testing.T) {
@@ -142,6 +147,33 @@ func TestNewPipelineFetcherUsesHTTPOnlyAndLegacyTimeout(t *testing.T) {
assert.Nil(t, fetcher.renderBrowser)
}
+func TestPipelineFetcherIgnoresWebFetchToolTimeout(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "180")
+ fetcher := NewPipelineFetcher()
+ assert.Equal(t, 15*time.Second, fetcher.timeout)
+ assert.Nil(t, fetcher.renderBrowser)
+ assert.Equal(t, 180*time.Second, PageFetchTimeout())
+}
+
+func TestPageFetchTimeout(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "")
+ assert.Equal(t, 3*time.Minute, PageFetchTimeout())
+
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "150s")
+ assert.Equal(t, 150*time.Second, PageFetchTimeout())
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "3m")
+ assert.Equal(t, 3*time.Minute, PageFetchTimeout())
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", "180")
+ assert.Equal(t, 180*time.Second, PageFetchTimeout())
+
+ for _, raw := range []string{"", "0", "-1", "0s", "-5s", "nope", " "} {
+ t.Run("fallback_"+raw, func(t *testing.T) {
+ t.Setenv("WEKNORA_WEB_FETCH_TIMEOUT", raw)
+ assert.Equal(t, 3*time.Minute, PageFetchTimeout())
+ })
+ }
+}
+
func TestFetcherReturnsErrorWhenBrowserFallbackFailsOnSPA(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
_, _ = writer.Write([]byte(`<html><body><div id="app">Loading...</div><script>render()</script></body></html>`))
diff --git a/website-docs/01-getting-started/04-configuration.md b/website-docs/01-getting-started/04-configuration.md
index 194877381..3ba47373e 100644
--- a/website-docs/01-getting-started/04-configuration.md
+++ b/website-docs/01-getting-started/04-configuration.md
@@ -296,6 +296,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| Sandbox 配置 | 设置页按空间维护 | 后端、凭据、模板、超时和私网访问策略按空间保存 |
| `WEKNORA_SANDBOX_DOCKER_ENABLED` | false | Docker 沙箱后端回退开关。系统管理员也可在「设置 → 系统设置 → 网络安全」打开(DB 优先,立即生效)。默认关闭,因为本机 `docker.sock` 等同宿主机 root |
| `WEKNORA_AGENT_LLM_TIMEOUT` | 120s | Agent 单次 LLM 调用超时(Go duration 或纯数字秒) |
+| `WEKNORA_WEB_FETCH_TIMEOUT` | 3m | Agent `web_fetch` 单页抓取预算(Go duration 或纯数字秒)。HTTP 与 chromedp 共用这一预算,不叠加。空值、无效值或非正数使用默认值。工具包装层再多等 5 秒。快速回答管道仍为 15s,不使用此项 |
| `WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT` / `_FAIL_OPEN` | 600s / fail-close | MCP 工具人工审批等待与失败策略 |
| `WEKNORA_CHAT_ATTACHMENT_TTL_HOURS` / `_WAIT_TIMEOUT_SEC` / `_OCR_CONCURRENCY` / `_OCR_MAX_PAGES` | 24 / 60 / 8 / 8 | 未被有效会话消息引用的附件保留时长、读取解析等待超时与 OCR 并发/页数上限;已发送附件在原会话或分叉会话仍引用时不因 TTL 清理 |
| `WEKNORA_HOUSEKEEPING_ENABLED` | 启用 | 回收卡在 processing 的脏数据 |
diff --git a/website-docs/03-features/07-agent.md b/website-docs/03-features/07-agent.md
index f9ddabb8c..0a6a73bd6 100644
--- a/website-docs/03-features/07-agent.md
+++ b/website-docs/03-features/07-agent.md
@@ -346,7 +346,7 @@ if !state.IsComplete && ctx.Err() == nil {
- 调用数 ≥ 2 时用 `errgroup` **并行执行**(`buildAgentConfig` 固定开启 `ParallelToolCalls`;best-effort,单个失败不取消兄弟任务),结果按原顺序回填。只有只读工具(`CanRunConcurrently`:检索、阅读、搜索类)会重叠执行;其他工具是屏障,等前面的调用结束后单独执行,再继续后面的调用;
- 每个调用先 `NormalizeToolCallID`,然后解析 JSON 参数——解析失败会先经 `RepairJSON` 修复再试;仍失败则返回带提示的错误结果(`"[Analyze the error above and try a different approach.]"`),让模型换路子而不是让整轮失败;
-- 单个工具执行超时 `defaultToolExecTimeout = 60s`;`shell_exec` 为 `shellExecToolTimeout = 10m5s`(略长于命令自身 600s 上限,以便返回结构化超时结果),`local_browser` 的人工接管步骤使用单独的等待时长;`ToolExecContext` 中额外携带不带该超时的 `ApprovalCtx`,供 MCP 人工审批/OAuth 等合法长等待使用;
+- 单个工具执行超时 `defaultToolExecTimeout = 60s`;`shell_exec` 为 `shellExecToolTimeout = 10m5s`(略长于命令自身 600s 上限,以便返回结构化超时结果),`web_fetch` 为共享页面预算加 5s(默认 3m5s,`WEKNORA_WEB_FETCH_TIMEOUT`),`local_browser` 的人工接管步骤使用单独的等待时长;`ToolExecContext` 中额外携带不带该超时的 `ApprovalCtx`,供 MCP 人工审批/OAuth 等合法长等待使用;
- 发射 `EventAgentToolCall`(含中文 display name 的 hint,如 `搜索网页("...")`)、`EventAgentToolResult`、`EventAgentTool` 事件。工具执行失败同样以 `tool_result` 发给客户端(`success: false` 与 `error`),不再作为 `error` 事件,智能体会根据错误继续处理。
**④ Observe(观察)**:`appendToolResults`(`internal/agent/observe.go`)按 OpenAI 协议把本轮追加进消息数组:一条带 `tool_calls` 的 assistant 消息 + 每个结果一条 `role:"tool"` 消息(内容经 `modelContext.ModelToolResultForTool` 别名化)。随后 `state.CurrentRound++` 进入下一轮。
@@ -418,7 +418,7 @@ flowchart TD
| `data_schema` | `knowledge_id`\*(`dN`) | 读取 CSV/Excel 文件的 `table_summary` + `table_column` 类型分块,返回列信息与行数;并告知模型该文档在 `data_analysis` 中固定以表名 `dataset` 访问 |
| `data_analysis` | `knowledge_id`\*、`sql`\* | 把 CSV/Excel 载入 DuckDB 后执行 SQL。文档由 `knowledge_id` 选定,SQL 中固定以表名 `dataset` 引用它(每次查询在独立连接上建临时视图映射到物理表,模型永远不需要在 SQL 里写文档 ID);多 Sheet Excel 合并为一张表并暴露 `__sheet_name` 列;自动纠正列名大小写/空格差异;会话结束 Cleanup 时 DROP 所建表 |
| `web_search` | `query`\*,可选 `count`(不超过配置上限,最多 20)、`country`(两位国家码或 `ALL`)、`freshness`(`pd`/`pw`/`pm`/`py`,Brave 另支持日期区间)、`content` | 联网搜索,直接返回提供商的标题、摘要和 `wN` 页面短 ID;按任务需要选择知识库或联网检索,Agent 搜索不再自动进行 RAG 压缩;`country`/`freshness` 仅 Brave 与 Serply 支持,其他提供商传入时报错;`content=true` 在 15 秒内并行抓取前 3 条结果、各取 5000 字符正文摘录 |
-| `web_fetch` | `items[]`\*(每项 `url`\*=`wN` 或 HTTP(S) URL,可选 `offset`、`limit`;`limit` 按字符计,默认且最多 8000,多项共享输出预算) | 并发抓取最多 8 个网页(SSRF 安全客户端 + DNS pinning,必要时 chromedp 渲染),直接返回 Markdown 或支持的文本正文;60s 超时。按字符分页,使用 `next_offset` 续读;完整正文保存在 `full_output_path`(`web://` 地址,仅同一会话可读),可用 `read_file` 跨轮按行读取;逐 URL 返回 `success`/`failed`/`skipped` 状态与可重试错误码(如快照已过期的 `snapshot_expired`),部分失败不影响其它页面 |
+| `web_fetch` | `items[]`\*(每项 `url`\*=`wN` 或 HTTP(S) URL,可选 `offset`、`limit`;`limit` 按字符计,默认且最多 8000,多项共享输出预算) | 并发抓取最多 8 个网页(SSRF 安全客户端 + DNS pinning,必要时 chromedp 渲染),直接返回 Markdown 或支持的文本正文;单页预算默认 3 分钟(`WEKNORA_WEB_FETCH_TIMEOUT`,HTTP 与 chromedp 共用)。按字符分页,使用 `next_offset` 续读;完整正文保存在 `full_output_path`(`web://` 地址,仅同一会话可读),可用 `read_file` 跨轮按行读取;逐 URL 返回 `success`/`failed`/`skipped` 状态与可重试错误码(如快照已过期的 `snapshot_expired`),部分失败不影响其它页面 |
| `read_file` | `path`\*、`offset`(从 1 开始的行号)、`limit`(默认 2000 行)、`max_bytes`(上限 64 KiB,网页快照 50 KiB);网页可带 `line_offset` | 读取工作区文本、skill:// 资源、web:// 网页快照及 attachment:// 会话附件,按结果续读;附件支持按需阅读、等待后台解析及指定图片读取,见[会话体验](18-chat-experience.md#使用临时附件提问) |
| `shell_exec` | `command`\*;可选 `skill_name`、`work_dir`、`timeout_sec`、`stdin`(≤ 64 KiB)、`max_output_bytes`(默认 16 KiB,上限 64 KiB)、`max_stderr_bytes`(默认 8 KiB,上限 16 KiB)、`env` | 在当前会话沙箱运行命令,默认工作目录 `/workspace`;指定技能时解析技能目录和变量 |
| `list_sandbox_files` | `path`、`max_entries`(默认 200,上限 500) | 浏览沙箱文件和可用产物;仅在未注册 `shell_exec` 时提供 |
@@ -670,6 +670,7 @@ const (
| `defaultLLMStallTimeout` | 120s(连续无输出的上限,非总时长) | `internal/agent/const.go` |
| `defaultToolExecTimeout` | 60s | `internal/agent/const.go` |
| `shellExecToolTimeout` | 10m5s | `internal/agent/const.go` |
+| `web_fetch` 页面预算 | 3m(`WEKNORA_WEB_FETCH_TIMEOUT`),工具包装层再加 5s | `internal/infrastructure/web_fetch/fetcher.go` |
| `maxLLMRetries` | 2 | `internal/agent/const.go` |
| `maxEmptyResponseRetries` | 2 | `internal/agent/const.go` |
| `maxRepeatedResponseRounds` | 2 | `internal/agent/const.go` |
diff --git a/website-docs/03-features/11-web-search.md b/website-docs/03-features/11-web-search.md
index 12f765256..7f58176a3 100644
--- a/website-docs/03-features/11-web-search.md
+++ b/website-docs/03-features/11-web-search.md
@@ -129,7 +129,7 @@ flowchart TD
- 抓取后将完整 Markdown 保存到会话所属租户的文件存储,返回 `web://...` 格式的 `full_output_path`。`read_file` 可跨轮读取这些文件,无需启用沙箱。正文与生成它的 assistant 消息绑定,读取检查租户、会话所有者、会话、消息和网页专用绑定;普通附件不能作为网页读出。删除消息或会话后不可访问,存储保留策略与现有软删除消息附件一致。
- 保存失败不会丢弃已经抓到的正文:结果包含 `storage_error`,此时续读仅限本轮内存缓存。单个保存的 Markdown 上限 8 MiB。
- `read_file` 的 `offset` 是从 1 开始的行号,`limit` 最多 2,000 行,网页读取最多 50 KiB,并继续受 Agent 输出预算约束。遇到超长单行时返回 `next_offset` 和 `next_line_offset`,使用 `offset` 加 `line_offset` 续读原行;这样无沙箱 Agent 也不需要执行 shell。
-- Agent 单页下载上限 2 MiB,超限报告 `body_too_large`,不会把静默截断的 HTML 冒充完整页面。请求超时仍为 60 秒,Agent 抓取接受 HTTP 2xx 响应。
+- Agent 单页下载上限 2 MiB,超限报告 `body_too_large`,不会把静默截断的 HTML 冒充完整页面。请求超时默认 3 分钟(`WEKNORA_WEB_FETCH_TIMEOUT`,HTTP 与 chromedp 共用这一预算),Agent 抓取接受 HTTP 2xx 响应。
- 失败继续返回稳定错误码与可重试标记。临时失败可合理重试;永久失败可选择其他相关来源,证据不足时说明缺口。一次整批失败不会强制终止研究,也不能视为验证成功。
- 关闭联网时,无论旧 `allowed_tools` 是否列出这两个工具,运行时均不注册。失败网页不再作为成功网页引用展示。