ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
2.9 KiB
English | 简体中文
常见问题
这篇列出常见的报错和现象，以及怎么处理。给所有人看。
模型返回空内容
Claude 4.6 之后的模型默认启用 thinking，max_tokens 过小会出现「思考耗尽额度，正文为空」。把节点的 max_tokens 调大，或者把思考模式设为关闭。时间线里会给出相应提示。
中转网关返回 401
部分网关只接受 Authorization: Bearer，额外携带 x-api-key 就会拒绝。在 provider 设置里勾选「用 Authorization: Bearer 认证」。
数据源结构探查失败
探查失败和「尚未探查」是两种状态。失败时点按钮解决不了，要先处理超时或更换 schema。数据源卡片会显示失败原因和该服务器上可选的库。agent 也会收到实情，并被告知可以直接查 information_schema 自己确认表结构。
网页工具报「解析到内网地址 198.18.x.x，已拦截」
本机代理（Clash / mihomo 等）开了 TUN + fake-ip，查任何域名都先拿到 198.18 段的假地址，被当成内网拦掉了。
- 在
.env里加一行AGENTLAB_HTTP_TOOL_FAKE_IP_RANGES=198.18.0.0/15，重启后端。落在这个段里的解析结果会改向公共 DNS 核实真实地址：公网放行，内网照拦。 - 核实用的 DoH 地址由
AGENTLAB_HTTP_TOOL_DOH_URLS指定（逗号分隔）。 - 不想改配置的话，把代理的 DNS 改成 redir-host，或者把要访问的域名加进
fake-ip-filter。
端口冲突
前端默认 5273、后端 8000，用 AGENTLAB_WEB_PORT / AGENTLAB_PORT 修改。
改了后端代码，正在跑的运行显示中断
dev.sh 开着热重载，改一个后端文件就是一次服务重启。运行被挂起（不是取消），断点完好：在运行详情页点「接着跑」，跑完的节点不会重跑，后面的人工审批照常停下来等人。
运行被中止，提示超过时限
单次执行（两次人工介入之间的那一段）默认最多 600 秒；单次模型调用默认 300 秒没有输出即超时。多半是模型或工具没有响应。确实需要更久，调大 AGENTLAB_MAX_RUN_SECONDS / AGENTLAB_MODEL_TIMEOUT_SECONDS。「设置 → 运行环境」里能看到当前值。
运行报「走满了 N 步还没跑完」
循环按自己 max_iterations 声明的轮数另算步数预算，配多少轮就能跑多少轮，不受全局上限约束。碰到这条报错的，多半是分支连回上游、却没有 loop 节点给它定轮数上限的环：用 loop 节点包住它。确实需要更多步，调大 AGENTLAB_MAX_GRAPH_STEPS（默认 200）。
agent 没查完就收了尾
时间线里有一条提示写明原因：步数用满、连续几步拿不到新信息、令牌或金额预算用完、上下文接近窗口。按提示调节点上或设置里的步数、预算（预算可以设成不限），见护栏。