企业官网建设流程全解析

SIA layout.py 导读：任务布局、venv 路径与名称解析的单一事实来源

【免费下载链接】siaSIA is a Self Improving AI framework to autonomously improve the performance of any AI system (Model / Agent) on a benchmark task.项目地址: https://gitcode.com/GitHub_Trending/sia4/sia

SIA（Self Improving AI）是一个自改进 AI 框架，能让 Meta、Target、Feedback 三个智能体在基准任务上循环迭代、自主提升性能。而 sia/layout.py 正是整个框架里任务布局、venv 路径与文件名解析的单一事实来源：所有目录结构、产物文件名、虚拟环境可执行文件路径，都在这一个文件里统一定义。本文带你快速读懂它。

为什么要有一个"单一事实来源"？

在大型 Python 项目里，路径字符串（如runs/run_1/gen_2/target_agent.py）最容易散落各处、改一处漏一处。SIA 在 layout.py 的开头就写明了设计意图：

路径与文件名常量此前散落在 orchestrator.py 和 context_manager.py 中，现在统一收口于此；路径构建方法返回str（而非Path），以匹配既有的os.path调用点，保证行为逐字节一致。

💡对新手的意义：以后想找"某个产物文件到底叫什么、放在哪"，只需要打开这一个文件。

layout.py 的四大构件

1️⃣ Names：所有文件名的集中登记表

Names 类 以类属性的形式登记了运行产物与任务输入的全部文件名，例如：

2️⃣ RunLayout：runs 目录的"地图"

RunLayout 数据类（frozen=True，即不可变）描述一次运行（如./runs/run_1）下的完整目录结构，提供了一组"按代次取路径"的方法：

runs/run_1/ ├── venv/ ← layout.venv_dir ├── context.md ← layout.context_md └── gen_{n}/ ← layout.gen_dir(n) ├── target_agent.py ← layout.target_agent(n) ├── improvement.md ← layout.improvement_md(n) └── agent_execution/ ← layout.agent_execution_dir(n)

有个细节值得注意：stdout_log(n, focus=...)会根据改进焦点模式返回不同日志名——harness模式（改代码/提示词）记录target_agent_stdout.log，weights模式（基于 RL 调参）记录train_stdout.log。这让同一条路径逻辑适配了两种完全不同的训练方式。

3️⃣ TaskLayout：任务目录的"地图"

TaskLayout 数据类 描述任务目录本身，把task_dir（数据与任务描述）和shared_dir（共享资源）组织成属性：dataset_dir（数据集目录）、task_md（任务描述）、reference_agent（参考智能体模板）、evaluate_script()（评估脚本）等。

📦 任务目录的标准结构详见 docs/walkthrough.md，整体目录布局见 docs/architecture.md。

4️⃣ venv 路径与任务名解析函数

resolve_task_dir：--task 与 --task_dir 的解析规则

这是新手最关心的"我怎么告诉 SIA 用哪个任务"。resolve_task_dir() 把两个互斥的 CLI 参数统一解析为(task_dir, shared_dir)真实路径：

• --task gpqa→ 定位到打包进 wheel 的内置任务sia/tasks/gpqa/，共享目录用内置sia/tasks/_shared/。内置任务清单 BUNDLED_TASKS 共 4 个：gpqa、lawbench、longcot-chess、spaceship-titanic，任务不存在时会直接报错并列出可用名称。

• --task_dir ./my-task→ 定位外部任务目录；若其同级存在_shared/目录则优先使用，否则回退到内置_shared/。
• 两者都没传→ 直接报错提示必须二选一。

这种"外部优先、内置兜底"的设计，让自定义任务可以完全独立于仓库运行。

venv 路径为什么单独封装？

SIA 每次运行都会为智能体创建隔离的 Python 虚拟环境（runs/run_{id}/venv/），并优先使用uv提速、没有则回退标准venv模块。见 sia/run_setup.py 中的_create_venv()：

# 有 uv 时（更快） uv venv runs/run_1/venv uv pip install --python runs/run_1/venv/bin/python <packages> # 无 uv 时（标准库） python3 -m venv runs/run_1/venv runs/run_1/venv/bin/pip install <packages>

如果venv/bin/python这个相对路径写死在多处，将来支持 Windows（venv\Scripts\python.exe）就要改 N 个地方——而封装成venv_python_path()后只需改一处。此外，orchestrator.py 在每代评估前都用该 venv 的 python 执行evaluate.py，路径一致性保证了"装好的环境"和"运行的环境"永远是同一个。

layout.py 在项目中被谁使用？

📚 阅读源码的三个建议

1. 从常量表读起：先扫一遍 Names 类，把所有文件名过一遍，脑中形成"文件清单"。
2. 对着目录结构读方法：RunLayout/TaskLayout的每个方法都对应目录树里的一格，配合 docs/architecture.md 的目录布局图读事半功倍。
3. 跑一次真实运行验证理解：pip install 'sia-agent[openhands]'后执行sia run --task gpqa --max_gen 2 --run_id 1，再对照runs/run_1/的实际文件与本文目录树逐一核对。

相关资料

• 项目 README 与快速上手：README.md
• 任务目录完整说明：docs/walkthrough.md
• 配置与 Profile 参考：docs/configuration.md
• 排错指南：docs/troubleshooting.md
• 内置任务示例（含参考智能体模板）：sia/tasks/

【免费下载链接】siaSIA is a Self Improving AI framework to autonomously improve the performance of any AI system (Model / Agent) on a benchmark task.项目地址: https://gitcode.com/GitHub_Trending/sia4/sia