[feature]路径配置统一与优化记录保留

[YYangZiXin]

Problem / use case

Feature Request: 路径配置统一与优化记录保留

Author: yang_zixin
Date: 2026-05-13
Status: Draft

---

1. 背景与问题

1.1 当前状态

jit-optimize 涉及多种路径，分布在不同层级：

路径类型	当前默认路径	可配置性
Task 目录	<PROJECT_ROOT>/skvm-data/tasks/	✅ SKVM_DATA_DIR
Skill 目录	<SKVM_DATA_DIR>/skills	✅ SKVM_SKILLS_DIR
Proposal 目录	~/.skvm/proposals/	✅ SKVM_PROPOSALS_DIR
Agent WorkDir	/tmp/jit-optimize-run-<id>-<rand>/	❌ 硬编码
Adapter Sandbox	/tmp/skvm-adapter-homes/<name>-<pid>-<rand>/	❌ 硬编码
Optimizer Workspace	/tmp/jit-optimize-<rand>/	❌ 硬编码
Agent Logs	<proposal-dir>/<round>-agent-logs/	❌ 硬编码

1.2 核心问题

问题 1: 部分路径不可配置

三个临时目录路径硬编码在代码中，无法自定义：

• Agent WorkDir: src/jit-optimize/loop.ts:1303-1309
• Adapter Sandbox: src/core/adapter-sandbox.ts:144-168
• Optimizer Workspace: 代码位置待确认

影响:

• 无法控制临时文件存储位置（如需放到更大的磁盘分区）
• 无法统一清理策略
• 在某些环境（容器、受限环境）可能因 /tmp 权限问题失败

问题 2: Optimizer 工作记录被清除

Optimizer 运行时创建的工作目录结构：

/tmp/jit-optimize-<rand>/
├── skill/SKILL.md
├── .optimize/
│   ├── PER_TASK_SUMMARY.md      # 任务摘要（优化输入）
│   ├── tasks/<task-id>/run-N.md  # 详细运行记录
│   └── OPTIMIZATION_PROTOCOL.md  # 优化协议
└── tasks-out/                    # synthetic 输出

当前行为：优化完成后直接删除整个目录（见 loop.ts:357 生命周期说明）。

影响:

• 丢失 optimizer 分析过程的完整证据链
• 无法审计 optimizer 收到了什么信息做决策
• 难以 debug 优化失败的原因
• 无法复现优化过程

问题 3: 路径管理分散

• 临时目录、输出目录、配置目录由不同机制管理
• 环境变量命名不一致（SKVM_CACHE vs SKVM_DATA_DIR vs SKVM_INSTALL_ROOT）
• 缺乏统一的路径配置入口
• 清理策略分散（有的自动清理，有的永久保留）

---

2. 目标

2.1 功能目标

1. 统一配置入口: 提供一致的路径配置机制，支持所有路径类型
2. 保留优化记录: Optimizer workspace 内容可选保留到 proposal 目录
3. 清晰的生命周期管理: 明确临时目录的创建、使用、清理时机

2.2 非功能目标

• 保持向后兼容：现有环境变量继续生效
• 不改变默认行为：新配置项默认值与当前行为一致

---

3. 解决方案

3.1 引入统一的临时目录配置

新增环境变量 SKVM_TMP_DIR，控制所有临时目录的父目录：

# 新增环境变量
SKVM_TMP_DIR=/path/to/tmp

# 生成的临时目录
${SKVM_TMP_DIR}/jit-optimize-run-<id>-<rand>/   # Agent WorkDir
${SKVM_TMP_DIR}/skvm-adapter-homes/<name>-<rand>/ # Adapter Sandbox
${SKVM_TMP_DIR}/jit-optimize-<rand>/              # Optimizer Workspace

优先级:

SKVM_TMP_DIR > ${TMPDIR:-/tmp}

代码变更:

• src/jit-optimize/loop.ts: 使用 getTmpDir() 获取临时目录根
• src/core/adapter-sandbox.ts: 使用 getTmpDir() 获取临时目录根
• 新增 src/core/tmpdir.ts: 统一的临时目录获取逻辑

3.2 保留 Optimizer Workspace 到 Proposal 目录

方案: 将 .optimize/ 目录复制到 proposal

新增配置项:

interface JitOptimizeConfig {
  // 是否保留 optimizer 的工作记录
  // 默认: true（新行为）
  preserveOptimizerWorkspace?: boolean
}

变更后的 Proposal 目录结构:

<proposal-dir>/
├── round-1/
│   └── SKILL.md
├── round-1-optimizer-logs/
│   ├── agent-stdout.log          # 原有
│   └── workspace/                 # 新增: optimizer workspace 备份
│       ├── PER_TASK_SUMMARY.md
│       ├── tasks/
│       │   └── <task-id>/
│       │       ├── run-0.md
│       │       └── run-1.md
│       └── OPTIMIZATION_PROTOCOL.md
└── ...

实现逻辑:

// 优化完成后
if (config.preserveOptimizerWorkspace !== false) {
  const workspaceBackup = path.join(proposal.dir, `${roundLabel}-optimizer-logs`, 'workspace')
  await fs.cp(optimizerWorkspace, workspaceBackup, { recursive: true })
}
// 然后清理临时目录
await fs.rm(optimizerWorkspace, { recursive: true })

3.3 配置文件支持

在 skvm.config.json 中支持所有路径配置：

{
  "paths": {
    // 数据目录
    "dataDir": "/custom/data/dir",
    "skillsDir": "/custom/skills/dir",
    "tasksDir": "/custom/tasks/dir",

    // 输出目录
    "proposalsDir": "/custom/proposals/dir",
    "logsDir": "/custom/logs/dir",

    // 临时目录
    "tmpDir": "/custom/tmp/dir",

    // 运行时行为
    "preserveOptimizerWorkspace": true
  }
}

优先级:

环境变量 > skvm.config.json > 默认值

3.4 CLI 参数支持

skvm jit-optimize \
  --tmp-dir=/custom/tmp \
  --preserve-optimizer-workspace=true \
  ...

---

4. API 变更

4.1 新增环境变量

环境变量	默认值	说明
SKVM_TMP_DIR	${TMPDIR:-/tmp}	所有临时目录的父目录

4.2 新增配置项

配置项	类型	默认值	说明
paths.tmpDir	string	-	临时目录父路径
paths.preserveOptimizerWorkspace	boolean	true	是否保留 optimizer 工作记录

4.3 新增 CLI 参数

参数	类型	说明
--tmp-dir	string	临时目录路径
--preserve-optimizer-workspace	boolean	是否保留 optimizer workspace（默认 true）
--no-preserve-optimizer-workspace	flag	禁用保留（等效于 --preserve-optimizer-workspace=false）

---

5. 实现计划

Phase 1: 基础路径统一 (P0)

1. 创建 src/core/tmpdir.ts，统一临时目录获取逻辑
2. 重构 src/jit-optimize/loop.ts 中的 createRunWorkDir
3. 重构 src/core/adapter-sandbox.ts 中的 createSandbox
4. 添加 SKVM_TMP_DIR 环境变量支持
5. 添加 --tmp-dir CLI 参数

Phase 2: Optimizer Workspace 保留 (P0)

1. 在 src/jit-optimize/loop.ts 中添加 workspace 备份逻辑
2. 添加 preserveOptimizerWorkspace 配置项
3. 更新 proposal 目录结构

Phase 3: 配置文件支持 (P1)

1. 扩展 skvm.config.json schema
2. 添加配置验证逻辑
3. 更新文档

---

6. 验收标准

6.1 路径配置

• SKVM_TMP_DIR 环境变量生效，所有临时目录使用该路径
• --tmp-dir CLI 参数覆盖环境变量
• 未设置时回退到系统默认 /tmp
• 临时目录命名规则保持原有随机性

6.2 Optimizer Workspace 保留

• 默认情况下，.optimize/ 内容复制到 round-N-optimizer-logs/workspace/
• preserveOptimizerWorkspace=false 时跳过复制
• 保留的文件结构与原始 workspace 一致
• 原临时目录仍然被正确清理

6.3 向后兼容

• 未设置新环境变量时，行为与当前版本一致
• 现有 proposal 目录结构不受影响
• 现有环境变量（SKVM_DATA_DIR 等）继续生效

---

7. 风险与缓解

风险	影响	缓解措施
Proposal 目录膨胀	保留 workspace 会增加磁盘占用	提供配置项关闭保留；建议用户定期清理
配置优先级冲突	用户可能设置多个层级的配置	明确文档说明优先级；添加警告日志
路径迁移成本	现有用户可能依赖硬编码路径	保持默认行为不变；新配置为可选

---

8. 后续优化

1. 统一清理策略: 提供命令清理旧的临时文件和 proposal
2. 路径配置诊断: skvm config paths 命令显示当前所有路径配置
3. Workspace 归档: 支持将 workspace 打包为独立文件而非内嵌目录

---

附录: 相关代码位置

功能	文件	行号
Agent WorkDir 创建	src/jit-optimize/loop.ts	1303-1309
Adapter Sandbox 创建	src/core/adapter-sandbox.ts	144-168
Optimizer Workspace	src/jit-optimize/loop.ts	待确认
Agent Logs 路径	src/jit-optimize/loop.ts	382-384
环境变量解析	src/core/config.ts	46-111
Proposal 存储	src/proposals/storage.ts	-

Proposed solution

.

Alternatives considered

No response

Impact / blast radius

No response

Are you planning to send a PR for this?

Maybe, depending on the discussion

Checks

• I searched existing issues and this is not a duplicate.
• I read CONTRIBUTING.md.