SkillOpt-Sleep 多平台集成指南：为 Claude Code、Codex、Cursor、Copilot、Devin 等 Agent 接入夜间睡眠自进化循环

• 人工智能
• 大模型
• AI Agent
• 提示工程

SkillOpt-Sleep 是 SkillOpt 项目中的"部署期"组件：它离线回顾 Agent 近期会话、挖掘重复性任务、在独立验证门控（held-out gate）下对记忆与技能提出有界文本编辑，并将提案暂存（staged）供人工审核后再采纳。本指南以 plugins/README.md 为骨架，结合仓库源码与各平台插件，完整讲解七大平台集成的安装方式、共享 CLI 的全部动作与参数、数据边界、偏好配置、Handoff 后端、调度与安全模型，帮助你为自己的编码 Agent 部署一套"越用越强"的夜间自进化管线。

核心机制：一次"睡眠周期"如何运作

SkillOpt-Sleep 的本质是给本地编码 Agent 增加一个可重复的夜间循环。官方集成文档给出的一次睡眠周期如下：

harvest supported local sessions → mine recurring tasks → replay tasks → reflect and propose bounded edits → validate on held-out real tasks → stage proposal → (you) review and adopt

即：采集本地会话 → 挖掘重复任务 → 重放任务 → 反思并提出有界编辑 → 在留出的真实任务上验证 → 暂存提案 → 人工审核并采纳。

这套循环有三个思想来源，体现在 plugins/claude-code/README.md 的表格中：

从源码看，该循环由 skillopt_sleep/main.py 中的run_sleep_cycle（来自 skillopt_sleep/cycle.py）驱动，run、dry-run、status、adopt、harvest、schedule/unschedule七个动作都通过同一个python -m skillopt_sleep入口分发（见main()中sub.add_parser注册逻辑）。

关键的安全语义是：在用户显式执行adopt（或显式传入--auto-adopt）之前，任何线上文件都不会被修改；而每次adopt都会先备份现有目标文件。这就是"审核后采纳"契约（review, then adopt or discard）。

共享引擎位于 skillopt_sleep，它对论文中的skillopt/实验包没有任何运行时依赖——正如 plugins/README.md 开头所强调的，集成层只依赖这一套独立引擎。

七条平台集成一览

仓库提供了六条共享引擎集成 + 一条独立的参考适配（OpenClaw），全部围绕同一个skillopt_sleepCLI：

各平台插件的具体形态差异很大：Claude Code 走 marketplace 插件 + slash 命令；Codex 采用"技能优先"（skill-first）路线（因为自定义 prompt 在 Codex 中已废弃）；Copilot 与 Devin 用纯标准库实现的 MCP 服务器；dsh 则以 Cordis 插件注册原生工具。但底层全部调用同一个共享引擎。

共享 runner：run-sleep.sh 的解析链

所有共享引擎集成都依赖 plugins/run-sleep.sh 作为统一启动入口。该脚本的解析顺序是：

1. 从脚本自身位置向上寻找仓库根（含skillopt_sleep/目录）；若设置了CLAUDE_PLUGIN_ROOT或SKILLOPT_SLEEP_REPO环境变量也作为候选；
2. 找不到源码目录时，回退到PATH上的skillopt-sleep可执行文件（覆盖uv tool install/pipx安装，它们与系统 Python 的 import 路径隔离）；
3. 再回退到可 import 的skillopt_sleep模块。

脚本会按python3.12 → python3.11 → python3.10 → python3顺序挑选 Python ≥ 3.10 的解释器，并支持SKILLOPT_SLEEP_PYTHON显式覆盖。这解释了为什么"源码检出无需pip install"，以及uv tool install skillopt/pip install skillopt这两种回退安装方式为何可用。

安装与版本前提

前置要求

• Python 3.10 或更新版本（所有集成通用）。
• 真实 CLI 后端（如claude、codex、cursor-agent）需要对应 Agent CLI 已安装并完成认证；默认的mock后端不需要任何登录与 API 预算。

各平台安装步骤

版本注意事项

集成参考文档明确跟踪main分支：PyPI 0.2.0支持基础 Sleep CLI，而 Cursor 源/后端/插件支持、Pi 源/后端支持、handoff、非 Azure OpenAI 兼容端点下的 Sleep 支持、OpenCode Sleep 源/后端支持，以及--preferences、多技能 fan-out、审核后子集采纳，都需要源码检出main直到下一个版本发布。使用 pip/uv 安装路线时请选择包含所需特性的版本。

Cursor 安装的细节

Cursor 插件安装器会把插件复制到~/.cursor/plugins/local/skillopt-sleep（Windows 为%USERPROFILE%\.cursor\plugins\local\skillopt-sleep），修改用户环境变量后需重启 Cursor，并在 Settings > Plugins > Installed 中确认出现SkillOpt-Sleep。插件与引擎是两个独立的安装边界：插件教会 Cursor 如何操作 Sleep 引擎，而引擎仍通过 plugins/run-sleep.sh 从源码检出运行，或通过uv tool install skillopt/python -m pip install skillopt安装的 CLI 命令运行。Windows 上插件与转录采集器原生可用，但 Cursor 官方文档建议 Agent CLI 通过 WSL 使用，因此--backend cursor的 provider 调用在 WSL 内执行更稳妥。

共享 CLI 全量速查

七个动作

源码层面（skillopt_sleep/main.py）对应cmd_run（run/dry-run共用，靠dry布尔区分）、cmd_status、cmd_adopt、cmd_harvest、cmd_schedule/cmd_unschedule。cmd_adopt还实现了三种互斥的选择模式：--skill NAME（可重复）、--all-skills、--legacy，同时传入多个模式会返回错误码 2（"use exactly one of --skill, --all-skills, or --legacy"）。

常用参数一览

注意事项

• 夜间 CLI 不暴露实验参数：--gate、--rollouts-k、--optimizer-model、--target-model、--budget-tokens、--budget-minutes都不在受管 CLI 中；不要把实验 harness 的旗标传给主 CLI（_add_common的实现也只注册了上面列出的参数）。
• Cursor 后端语义：--project同时选择目标文件、状态与暂存位置，但不会让该目录成为 Cursor Agent 的执行工作区；目标技能是作为提示文本插入，而非作为原生技能调用。
• dry-run 语义：真实后端的dry-run会执行相同的挖掘与重放模型调用，但抑制暂存、采纳与持久化状态变更。
• replay 标签：当前 Sleep 周期没有实现全新工作树重放；报告中的replay: mock标签描述的是"提示重放"模式，与--backend mock相互独立。

用 --preferences 注入家规

--preferences是面向用户的主要控制旋钮：

python -m skillopt_sleep run --backend codex --project "$(pwd)" \ --preferences "Prefer pytest. Keep commit subjects imperative and concise."

偏好会引导反思阶段，但仍然受验证门控约束——偏好不是绕过门控的手段。源码中该参数被映射为配置键preferences（见_cfg_from_args），并在 skillopt_sleep/config.py 中描述为"注入 reflect 先验的自由文本家规"。

数据边界：什么留在本地、什么会外发

这是整个集成参考中最重要的安全章节，逐条列出：

• 采集是本地的、只读的。mock与handoff后端不发起任何网络调用；handoff只把提示写入文件供用户独立完成。
• 真实后端会把"由截断的转录片段与任务派生的挖掘、重放、评判、反思提示"发给所选 provider。
• Cursor 源读取~/.cursor/projects/*/agent-transcripts中的本地 user/assistant 消息文本、显式回合错误与工具名；不保留工具参数、工具输出或其他记录类型。已知的密钥形态字符串会被脱敏，但这是纵深防御，不是"出站提示必然无密钥"的保证。
• Cursor 后端通过已安装并认证的cursor-agentCLI 发送提示。普通调用在全新空临时工作区中以只读 Ask 模式运行，并拒绝项目文件访问。包含tool_called校验的 Cursor 任务会在 Agent 模式启动前失败；此类任务请改用其他后端。Cursor 及其选定的模型 provider 可能收到生成的提示内容。
• Pi 后端通过已安装并认证的 Pi CLI 向用户配置的 provider 发送提示。这些调用禁用工具、技能、上下文文件、扩展、提示模板、主题与会话写入，但保留用户的 Pi 认证与模型配置。Pi 的离线启动模式阻止配置的 npm/git 包安装、包更新与模型目录刷新，但不阻止所选 provider 的调用。这些控制不构成永久或完全隔离的保证。
• Pi 源保留 user/assistant 文本、工具名与用户文本中的词汇反馈；排除思考、工具参数、工具输出、图片与无关元数据。会话头部的绝对项目cwd被保留用于范围过滤，可能出现在发给真实后端及其 provider 的挖掘提示中。已知密钥形态字符串仅作纵深防御性脱敏。
• 核心opencode源在无 CLI、无认证、无 provider 访问的情况下直接读取本地 OpenCode SQLite 历史，其保留数据边界见 docs/reference/cli.md。
• 核心opencode后端使用已安装的 OpenCode CLI。普通调用禁用项目配置、模型发起的工具调用、外部插件与配置的 MCP 服务器；工具感知重放需显式选择（--opencode-tool-replay）。它只暴露随机命名、结果固定的临时合成工具，然后验证 OpenCode 实际调用了哪些工具。仓库不包含原生 OpenCode 插件或命令。
• 出站提示目前不保证无密钥。不要在敏感转录上使用第三方 provider，除非先审阅数据源与该 provider 的保留政策。

可审核工作流：导出 → 脱敏 → 标记 reviewed → 重放

对于需要人工审核的场景，官方推荐分步执行：

python -m skillopt_sleep harvest --project "$(pwd)" --output reviewed-tasks.json python -m skillopt_sleep dry-run --project "$(pwd)" --backend codex \ --tasks-file reviewed-tasks.json --progress

导出后检查并脱敏 JSON，将其顶层"reviewed"字段设为true，再交给真实后端重放。真实后端会拒绝仍标记为未审核的任务文件——这一点在 skillopt_sleep/main.py 的cmd_run中有直接实现：当backend != "mock"且任务元数据的reviewed不是True时，会打印提示并返回退出码 2。

API-key 与 Azure 托管身份传输边界的说明见 docs/sleep/openai-compatible-endpoints.md。

深入：Pi 源与后端

Pi 转录采集是显式的：--source pi读取~/.pi/agent/sessions下的会话 JSONL 文件；用--pi-home选择包含agent/sessions的父目录。该源不要求Pi CLI 或 provider 认证。它保留 user/assistant 文本、工具名与用户文本中的词汇反馈，排除思考、工具参数、工具输出、图片与无关元数据。注意--source auto保持 Codex→Claude 优先顺序，不会选择 Pi。

源与后端相互独立：

python -m skillopt_sleep run --project "$(pwd)" \ --source pi --backend pi --pi-path /absolute/path/to/pi \ --model provider/model --max-sessions 5 --max-tasks 3 --progress

Pi 调用禁用工具、技能、上下文文件、扩展、提示模板、主题与会话写入，但仍使用用户的 Pi 认证与模型配置；其离线启动模式阻止 npm/git 包安装等行为，却不阻止 provider 调用。这是"有界调用"设置，而非永久或完全隔离。

调度 Pi 前的关键限制：受管调度器会持久化所选后端，但不持久化--source、--pi-home、--pi-path或--model。因此调度 Pi 前，需先在~/.skillopt-sleep/config.json中设置transcript_source、pi_home、pi_path和model，且优先使用绝对pi_path，并确认被调度账户已认证。

深入：Cursor 源与后端

Cursor 转录采集同样是显式的：使用--source cursor而不是--source auto。invoked项目范围使用 Cursor 记录的 workspace 路径（脱敏存储目录为回退），--scope all扫描~/.cursor/projects下的每个 Cursor workspace。模型驱动后端要求已安装并认证的cursor-agent；不在PATH上时用--cursor-path、SKILLOPT_SLEEP_CURSOR_PATH或配置键cursor_path指定，用--model或SKILLOPT_SLEEP_CURSOR_MODEL选择模型。

显式指定项目技能目标，让被接受的学习成果对 Cursor 可见，而不改动插件自身的工作流技能：

python -m skillopt_sleep run --project "$(pwd)" \ --source cursor --backend cursor \ --target-skill-path .cursor/skills/skillopt-sleep-learned/SKILL.md \ --max-sessions 5 --max-tasks 3 --progress

Cursor 原生命令的默认可见目标是.cursor/skills/skillopt-sleep-learned/SKILL.md；不显式指定时，共享引擎默认采用 Claude 受管技能，而 Cursor 不会把它加载为项目技能。

首次采集默认使用 72 小时回看窗口；--lookback-hours N可放宽，--lookback-hours 0在仍尊重--max-sessions的前提下扫描全部历史。一次成功的run（包括未挖掘出任务的情况）会记录新的采集检查点；后续运行基于该检查点，而非初始回看窗口。harvest/dry-run用于检查会话与任务数，且不会推进检查点。

Cursor 重放的边界：引擎读取目标技能并将其文本插入挖掘任务提示，但不会把该文件作为原生 Cursor 技能调用，也不会执行技能中描述的命令。所有普通 Cursor 模型调用（挖掘、重放、评判、反思）都在全新空临时工作区的只读 Ask 模式中运行，文件读取、写入与 MCP 工具均被拒绝。目前没有Cursor 选项能启用全新项目工作树或真实项目工具，因此这种重放适合文本流程、回复惯例与输出格式，而非依赖仓库检视、真实 CLI、浏览器或文件系统变更的端到端技能评测。此外，Cursor 工具感知重放目前暂被禁用（等待权限边界验证），含tool_called检查的任务会在 Agent 模式启动前以非零退出；失败的重放不会新增缓存条目、不会暂存/采纳/持久化状态、也不会推进采集检查点。

Cursor 调度的前置配置：受管schedule命令只持久化项目、后端、时间与可选 auto-adopt 设置，不会把--source、--cursor-home、--cursor-path、--model、--target-skill-path复制进调度命令。因此调度 Cursor 前先在~/.skillopt-sleep/config.json中设置transcript_source、cursor_home、cursor_path、model、target_skill_path；保持目标路径为项目相对路径、使用绝对 CLI 路径（cron 与 Task Scheduler 的PATH可能极简），并确认运行作业的账户已认证cursor-agent。示例配置：

{ "transcript_source": "cursor", "target_skill_path": ".cursor/skills/skillopt-sleep-learned/SKILL.md", "cursor_home": "/absolute/path/to/.cursor", "backend": "cursor" }

限制到仅 Cursor 技能：共享引擎可能还会提议项目CLAUDE.md记忆更新；若只想限定在 Cursor 技能，可在~/.skillopt-sleep/config.json中设置"evolve_memory": false。Cursor 集成刻意没有会话结束 hook 或自动插件执行。

高级配置：~/.skillopt-sleep/config.json

~/.skillopt-sleep/下的 JSON/YAML 配置支持额外的引擎键，包括gate_mode、gate_metric、gate_no_regression、dream_rollouts、dream_factor、recall_k、evolve_memory、evolve_skill。这些是配置键，不是上面列出的不支持的 CLI 旗标的别名。

出厂默认值偏保守：gate_mode="on"、gate_no_regression=false、dream_rollouts=1、dream_factor=0、recall_k=0。

从 skillopt_sleep/config.py 的DEFAULTS可以看到更完整的默认面：

• 范围类：transcript_source="claude"、projects="invoked"、lookback_hours=72；
• 预算类：max_tasks_per_night=40、max_tokens_per_night=400_000、holdout_fraction=0.34（即val_fraction）、test_fraction=0.0；
• 优化器类：backend="mock"、edit_budget=4、gate_metric="mixed"、gate_no_regression=False、replay_mode="mock"；
• 可选增强：dream_rollouts=1、dream_factor=0、recall_k=0、evolve_memory=True、evolve_skill=True、llm_mine=True。

配置解析顺序（后者覆盖前者）：内置DEFAULTS→~/.skillopt-sleep/config.json（若有 PyYAML 也支持.yaml）→load_config(**overrides)的显式覆盖。其中gate_no_regression当设为true时，会要求每个验证任务在gate_metric下保持或提升分数，缺失任务结果或非有限任务分数也会阻止候选。

调度限制：受管schedule命令只存储项目、后端、时间与可选 auto-adopt 设置，不复制命令行参数到调度命令；这与 Pi/Cursor 章节所述一致——调度前先把源、路径、模型等键写入 config.json。

Handoff 后端：让会话本身回答模型调用

--backend handoff让引擎完全不启动模型子进程。引擎执行确定性阶段，并把所有需要的模型调用写入.skillopt-sleep-handoff/PROMPTS.md与pending.json，然后以退出码 3 结束；把答案放入answers/<id>.md后重跑同一命令即可恢复：

python -m skillopt_sleep run --backend handoff --project "$(pwd)" # answer each prompt in a fresh context, then run the same command again

典型情况是每夜 3~6 轮。关键纪律：必须用"未见过其引用内容"的全新上下文回答留出提示——已经看过挖掘任务及其引用的会话会污染验证门控。Claude Code 的/skillopt-sleep-handoff命令会用隔离的全新上下文子代理自动完成这个循环。handoff 模式对订阅制用户尤其友好：不需要claude -p子进程，也不需要 API key。

从源码看（skillopt_sleep/main.py 的_run_handoff与_handoff_mine_and_pin），handoff 模式还会把会话摘要与挖掘任务固定（pin）到 handoff 目录下的digests.json与tasks.json，确保轮次之间新产生的会话不会改变任务集、从而使早期答案失效；一轮完整 run 结束后会把 handoff 目录归档为.skillopt-sleep-handoff.night<N>.done，让下一夜重新采集而非重放固定快照。每次退出码 3 也意味着：在 MCP 集成（Copilot/Devin）中，exit 3 是预期的handoff_pending状态，不是MCP 工具错误。

验证与确定性实验

仓库内置了无需 provider 的确定性检查，覆盖整合与门控逻辑：

python -m skillopt_sleep.experiments.run_experiment \ --persona researcher --assert-improves

该实验会打印留出分数从基线向 1.0 爬升的过程（门控接受了任务所需的一般规则），并确认门控会拒绝一个被注入的有害编辑。真实模型基准结果及其局限记录在 docs/sleep/RESULTS.md；基准配方不是发布版 CLI 的默认设置。

Claude Code 集成文档还给出一个可复现的公开基准路径：对 gbrain-evals 的skillopt-v1套件，用刻意有缺陷的技能跑一夜睡眠，留出评分由本地规则法官执行（无法官 API、无法给自己的作业打分）。其记录显示 Claude (Haiku 4.5) 与 Codex 后端均在一到两夜内把 "brief-writer" 技能的留出分数从 0.00 提升到 1.00，且只改动受保护的LEARNED块。需要强调的是：这些是特定任务/模型/检查下的实测证据，不保证普遍改进，且依赖外部数据集的复现命令不在本文赘述范围内。

安全模型总结

官方集成文档的最终安全清单如下：

• 会话采集是只读的。
• mock与handoff不发起网络调用。
• run只暂存提案；adopt是正常的线上变更边界。
• 采纳会备份现有目标文件。
• --max-sessions与--max-tasks约束工作量，但主 CLI尚未强制硬性 token 或耗时预算。
• 把真实后端的转录摘录视为与所选 provider共享的数据。

在 Claude Code 插件语境下还要补充三点：提案默认暂存、绝不自动应用（除非显式--auto-adopt）；每次采纳都在暂存目录的backup/下写备份；mock重放无副作用。部署建议的完整流程是：先用dry-run --backend mock免费验证管线连通性，再在敏感项目上走"harvest 导出 → 脱敏 → 标记 reviewed → 真实后端重放"的可审核路径，最后才考虑schedule托管夜间运行并自行决定是否启用--auto-adopt。

各平台插件的补充要点

Claude Code 插件

插件捆绑的 runner（plugins/claude-code/scripts/sleep.sh）会自动挑选 Python ≥ 3.10 解释器并调用skillopt_sleep引擎。快速上手：

/skillopt-sleep dry-run # 预览会学到什么；不暂存任何改动 /skillopt-sleep run # 完整周期：暂存一份待审提案（仍无线上编辑） /skillopt-sleep status # 查看历史 + 最近暂存提案 /skillopt-sleep adopt --legacy # 应用审核过的受管提案 # Fan-out 夜晚改用：adopt --skill NAME（可重复）或 --all-skills /skillopt-sleep-handoff run # 同一周期，但由本会话回答模型调用（无 API key）

Codex 插件

Codex 通过AGENTS.md指令、~/.agents/skills/<name>/SKILL.md技能与可分发技能的插件扩展；由于自定义 prompt 在 Codex 中已废弃，该集成采用技能优先路线。安装脚本还会把旧的~/.codex/prompts/sleep.md以.skillopt-legacy*.bak后缀移开。使用时直接对 Codex 说"Use the skillopt-sleep skill to run status/dry-run/... "或直接调用引擎：

python -m skillopt_sleep dry-run --project "$(pwd)" --source codex --backend mock python -m skillopt_sleep run --project "$(pwd)" --source codex --backend codex \ --max-sessions 5 --max-tasks 3 --progress

--source codex读取~/.codex/archived_sessions；--target-skill-path可指向仓库级 Codex 技能（如.agents/skills/<name>/SKILL.md），目标运行会过采样与目标技能路径/标题/内容匹配的挖掘任务。Codex 的exec运行 shell，因此真实工具循环重放（如tool_called: search基准种子）可原生工作。

Copilot 与 Devin（MCP 服务器）

两个插件都是纯标准库（stdlib-only）的 MCP stdio 服务器，零第三方依赖，暴露七个sleep_*工具：sleep_status、sleep_dry_run、sleep_run、sleep_adopt、sleep_harvest、sleep_schedule、sleep_unschedule。工具结果在structuredContent中保留引擎的exit_code；普通非零退出置isError: true，而退出码 3 是预期的handoff_pending状态。sleep_adopt支持staging（精确暂存目录）、skills（技能名数组，逐个转为重复--skill参数）、all_skills、legacy四种选择，且skills/all_skills/legacy三选一、不可组合。Copilot 后端通过copilot -p ... --output-format json驱动，为提速会在隔离的COPILOT_HOME下运行（禁用内置 MCP 服务器与自定义指令），可用SKILLOPT_SLEEP_COPILOT_HOME、SKILLOPT_SLEEP_COPILOT_MODEL、SKILLOPT_SLEEP_COPILOT_FULL_ENV=1覆盖。Devin 插件额外包含harvest_devin.py（把 Devin ATIF-v1.7 转录 + agentmemory +.devin/skills转换为引擎可读的 JSONL）与install.sh（向项目.devin/安装 SessionEnd hook 与规则片段）。

DeepSeek Harness（dsh）插件

dsh 插件是 TypeScript 模块（plugins/dsh/src/index.js），注册 7 个skillopt_*原生工具；plugins/dsh/cordis.patch.yml 是 bundle 补丁层，plugins/dsh/README.md 给出完整配置键表（pythonCmd、module、engineScript、project、scope、backend、source、model、maxTasks/maxSessions、editBudget、preferences、jsonOutput、autoAdopt、unscheduleAll、timeoutMs等）。其中autoAdopt与unscheduleAll标记为 OPERATOR-ONLY。高级引擎键同样进入~/.skillopt-sleep/config.json——所有集成共享同一文件。

OpenClaw（独立参考适配）

OpenClaw 使用自定义 DeepSeek/Ollama 封装（plugins/openclaw/skillopt_sleep_openclaw.py 等），有自己的后端与配置假设，官方明确要求"review and adapt before use"——先本地验证路径、凭据与任务，再用于生产。

结语：从"跑通一夜"到"托管夜间自进化"

SkillOpt-Sleep 的价值在于把 SkillOpt 论文中的"验证门控文本优化"迁移到个人日常使用场景：不需要权重训练，不侵入正常 Agent 请求，所有改动先暂存、经人工审核后带备份采纳。按官方集成参考，推荐的落地路径是：mock后端跑通dry-run验证管线 → 真实后端小规模run（--max-sessions 5 --max-tasks 3 --progress）→ 敏感项目走"harvest 导出 → 脱敏 → 标记 reviewed"的可审核工作流 → 配置~/.skillopt-sleep/config.json后schedule托管夜间运行 → 需要时显式adopt（或显式--auto-adopt）。所有平台共享同一引擎、同一 CLI、同一数据边界契约——这正是本仓库集成设计的核心：一套夜间自进化循环，七大 Agent 平台按各自的原生机制接入。

• 人工智能
• 大模型
• AI Agent
• 提示工程