智能体可靠性工程 · 研究项目

博士论文主线：度量 → 诊断 → 可证明的缓解 环境：Windows + WSL2 (Ubuntu 20.04) 项目路径（WSL 内）：~/research/agent-reliability Windows 访问：\\wsl$\Ubuntu-20.04\home\ljh\research\agent-reliability（或双击 D:\research\open-project.bat）

0. 两条不可违反的纪律

纪律一：证据链

论文里出现的每一个数字，都必须能在 results/ 里找到对应文件，且该文件由 scripts/ 中已提交的脚本生成。

这条纪律存在的原因很具体：本项目由 AI 承担绝大部分劳动，最大的失败模式不是”做不出来”，而是产出一篇看起来很完整、但数字是编的论文——初稿越流畅越不容易被察觉。所以可靠性必须由机制保证，而不是由人眼检查。

具体做法：

每个实验脚本必须把原始记录落盘到 results/<实验名>/<run_id>.json，字段至少包含： run_id / timestamp / model / model_version / config_hash / prompt_tokens / completion_tokens / cost_estimate / raw_outputs
论文草稿中的数字使用行内标记标注来源，例如： `幸运通过率 37.2%`
投稿前运行 python3 audit.py papers/draft.md，检查每个标记的数字是否与来源文件一致。审计不通过不许投稿。
参考文献一律经多源核实（nature-ref-verifier），不允许出现”看起来很真”的引用。

纪律二：可中断、可续跑

所有实验必须能在任意时刻被杀掉并恢复，不丢失已完成的工作。

原因：会话会关闭、笔记本会休眠、API 会限流、余额会用完。这不是可选项。

具体做法：逐样本落盘（每完成一个样本写一次），启动时扫描 results/ 跳过已完成的 run_id；同一 (prompt, model, 参数) 的调用结果永久缓存，重跑不重复付费。

1. 目录结构

agent-reliability/
├─ check_env.py      环境自检（零依赖）：验证 API 密钥是否真能跑通
├─ audit.py          数字可追溯性审计（投稿前必跑）
├─ .env              密钥（已 gitignore，需自行创建）
├─ .env.example      密钥模板
│
├─ src/
│  ├─ harness/       实验框架：可续跑执行器、API 客户端、缓存、计费
│  ├─ perturbations/ 论文 1：语义等价扰动生成器
│  ├─ memory/        论文 2：记忆系统接入 + 四维诊断指标
│  └─ mas/           论文 4：一致性协议与冲突注入
│
├─ scripts/          每个实验一个可重跑入口脚本
├─ results/          所有数字的唯一来源（JSON/CSV）
├─ figures/          出版级图
├─ papers/           论文草稿
├─ refs/             文献库（bib + 核实报告）
└─ notes/            实验日志、决策记录

2. 环境与运行方式

决策：在 WSL2 下构建和运行，不要用 Windows 原生 Python。

理由（均为本机实测）：

项目	Windows	WSL2 (Ubuntu 20.04)
Python	3.14.0（太新，生态未跟上）	3.11.7（合适）
Docker	需 Docker Desktop	已装 28.1.1，原生运行
生态兼容	部分 agent 框架假设 POSIX 路径	Linux 优先，无坑
可用磁盘	D 盘 477 GB	843 GB + /mnt/d 477 GB
内存	31.5 GB	15 GB（WSL 上限）
网络	DeepSeek/DashScope/GLM 可达，OpenAI 不可达	与 Windows 完全一致

项目必须放在 Linux 文件系统里，不能放在 `/mnt/d`

这一条是实测出来的，不是经验之谈。在 Windows 盘（/mnt/d，9p 挂载）与 Linux 文件系统上各创建 2000 个 4KB 小文件：

操作	Windows 盘 `/mnt/d`	Linux 文件系统	倍差
创建 2000 个文件	10.87 s	0.11 s	~100×
stat 2000 个文件	3.20 s	0.00 s	—

/mnt/d 的挂载参数为 type 9p (rw,noatime,...,msize=65536)，这是 WSL2 访问 Windows 磁盘的经典慢路径。另外在该挂载点上 chmod 失效——chmod +x 后权限仍是 -rwxrwxrwx，所有文件都是 777。

对本项目的实际影响：

创建虚拟环境（数万个小文件）：Linux 文件系统上几秒，/mnt/d 上要几分钟
Python 包导入：每个新进程都会慢 1–3 秒，而本项目会运行成千上万个短脚本
未来若用 SWE-bench 等需要 Docker 的基准：从 9p 挂载进容器会极慢

结论：代码、虚拟环境、实验结果一律放 Linux 文件系统；只把需要人工查看的最终交付物（论文稿、图）导出到 Windows 侧。

从 WSL 内部运行（常规方式）

cd ~/research/agent-reliability
python3 check_env.py

从 Windows 运行 WSL 命令

wsl -e bash -lc "cd ~/research/agent-reliability && python3 check_env.py"

在 Windows 里打开项目

双击 D:\research\open-project.bat
或在资源管理器地址栏粘贴： \\wsl$\Ubuntu-20.04\home\ljh\research\agent-reliability
建议在资源管理器里把它**固定到”快速访问”**，以后一键直达（右键左侧栏 → 固定）

用 VS Code 编辑（推荐）

wsl -e bash -lc "cd ~/research/agent-reliability && code ."

VS Code 会自动以 WSL 远程模式打开，编辑体验和本地文件完全一样，且不受 9p 性能影响。

3. 当前进度

环境可行性实测（硬件、网络、WSL、Docker、文件系统性能）
项目骨架与两条纪律确立
项目迁至 Linux 文件系统（避免 9p 的 ~100× 性能损失）
check_env.py 环境自检脚本，已在 WSL 内实测通过
密钥配置 ← 卡在这里，需要你操作（见下）
audit.py 数字审计脚本
src/harness/ 可续跑执行器 + API 客户端 + 缓存
论文 1 完整实验规格（基准、模型、扰动设计、样本量、预算、检查点）
论文 4 两周预实验（验证并发冲突痛点是否真实）

4. 你需要做的事

配置密钥（约 5 分钟）

复制模板：

wsl -e bash -lc "cd ~/research/agent-reliability && cp .env.example .env"

编辑密钥文件。两种方式任选：
- 双击 D:\research\open-project.bat，在打开的窗口里双击 .env（用记事本编辑）
- 或直接在资源管理器地址栏粘贴： \\wsl$\Ubuntu-20.04\home\ljh\research\agent-reliability\.env
验证：

wsl -e bash -lc "cd ~/research/agent-reliability && python3 check_env.py"

看到 ✅ 可用 就说明环境就绪。

注意：不要把密钥粘贴到聊天窗口里 —— 它会留在对话记录中。写进 .env 文件即可，我能直接读取该文件。

其余两件小事

文献全文权限：需要你打开 Chrome 登录学校图书馆/CARSI，之后我用 nature-downloader 取 PDF。
长期：每当我报告”这一批实验跑完了”，你花十分钟看一眼结果，重新打开一次会话说”继续”。