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

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 功能目标

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

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)

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

Phase 2: Optimizer Workspace 保留 (P0)

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

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

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

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. 后续优化

统一清理策略: 提供命令清理旧的临时文件和 proposal
路径配置诊断: skvm config paths 命令显示当前所有路径配置
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.

core/config: add SKVM_TMP_DIR / --tmp-dir / paths.tmpDir temp-dir res…

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

Description