使用 Skill
除了直接使用命令行工具，您也可以让 AI 助手通过 revive-project Skill 完成 REVIVE 项目。Skill 是一套供助手读取的任务说明、参考资料和辅助脚本；您提供业务目标、数据、约束和执行范围，助手据此整理数据、编写配置、调用 REVIVE 并说明结果。
本页介绍如何安装 Skill、开始一项任务，以及查看和继续已有项目。当前 Skill 版本为 2.0.3，适配 REVIVE 2.0.0；Skill 安装与 SDK 环境准备分开，不替代运行授权或模型效果验收。
能做什么
Skill 可以辅助完成从业务梳理到模型交付的流程：检查数据与变量含义，准备训练、验证和测试数据，生成配置，执行训练与参数搜索，评价模型，并按授权范围导出模型和验证部署。
您不需要先选择算法或编写配置，但需要说明哪些量可观测、哪些量可控制、设备的实际限制，以及什么结果算达标。数据中没有出现过的值不等于设备边界；缺少的业务信息需要确认，不能由助手自行补成事实。
训练使用 REVIVE 官方命令或接口。模型是否达到业务要求，需要根据约定条件评价；训练完成、文件导出成功和实际部署通过是不同的结果。
安装 Skill
获取安装包
下载并解压 revive-project Skill 完整包。包中包含任务说明、辅助脚本和与 REVIVE 2.0.0 匹配的用户文档知识包，不包含 SDK、Python 依赖或许可证。
解压后的 skills/revive-project/ 就是完整 Skill。SDK 软件包不包含 Skill，请单独取得该安装包并核对 SKILL.md 中的版本。保留整个目录，不要只复制 SKILL.md。
安装到 AI 助手
使用支持 Agent Skills、本地文件读写和终端执行的 AI 助手。以下以 Codex 为例，在任务项目的根目录运行，将路径替换为刚才的解压位置：
npx skills@1.7.0 add /absolute/path/skills/revive-project --agent codex --copy这里使用第三方 Skills CLI，已验证版本为 1.7.0，需要 Node.js 22.20.0 或更高版本和 npm，首次运行需要联网取得安装工具。该命令将 Skill 复制到当前项目的 .agents/skills/revive-project/，之后不依赖原解压目录；安装时不运行 REVIVE，也不安装 Python 依赖。
希望所有项目共用时，可在命令末尾加上 --global。使用其他受支持的助手时，可去掉 --agent codex，按提示选择。已有同名 Skill 时，请先备份并确认替换范围，不要直接覆盖修改过的文件。
离线或不使用 Node.js
不使用安装工具时，可以直接复制整个 revive-project 文件夹。Codex 支持以下位置，选择其中一个即可：
| 使用范围 | 复制后的目录 |
|---|---|
| 当前项目 | <项目根目录>/.agents/skills/revive-project/ |
| 当前用户的所有项目 | ~/.agents/skills/revive-project/ |
目录内应直接包含 SKILL.md、scripts/、references/、knowledge/ 和依赖清单。复制前确认目标目录不存在，或先备份旧版本，避免新旧文件混用。其他助手的发现目录以其说明为准；Codex 的加载约定见 官方 Skills 文档。
确认已加载
在任务项目中打开助手。Codex 可以通过 $revive-project 显式指定 Skill，例如：
请使用 $revive-project，先检查当前环境，说明缺少什么。
不要安装依赖，不要启动训练，也不要部署服务。如果已有 SDK 环境，可补充其 Python 可执行文件路径。助手会从已加载的 Skill 目录定位检查脚本，不需要您手动配置 Skill 路径变量。未发现 Skill 时，检查目录层级并重启会话；仅把路径贴到对话中，不代表助手已加载成功。
只支持文字对话、不能访问本地文件或执行命令的助手，无法直接运行这套流程。按任务需要开放权限；Skill 不替代助手本身的权限控制。
首次使用时检查环境
安装 Skill 不要求先安装 REVIVE。首次运行辅助脚本前，助手会使用选定 Python 执行随包的 scripts/doctor.py，检查 Python、SDK 和辅助依赖的安装版本。检查脚本只使用 Python 标准库，不联网、不导入 SDK、不读取凭据，也不申请许可证。
根据检查结果，按当前任务补齐环境即可：
| 当前任务 | 环境要求 |
|---|---|
| 讨论业务目标、整理已有说明 | 可以先开始，不要求 SDK 已安装 |
| 运行数据准备等辅助脚本 | Python 3.10 或 3.11，以及 Skill 所需的 NumPy、pandas、PyYAML |
| 调用 SDK 预检、训练与受保护功能 | 按安装与授权准备 REVIVE 2.0.0、目标运行环境及授权 |
NumPy 和 PyYAML 已属于 SDK 的基础依赖；pandas 是数据准备辅助工具需要的依赖，不应默认认为安装 SDK 时已经包含。发现缺失或不兼容项时，助手应先确认所用 Python 环境，说明拟执行的安装命令和影响，经您同意后再处理。不会因为加载了 Skill 就自动安装 SDK、修改依赖或开始训练。完全离线准备环境时，仍需事先取得对应的 SDK 与依赖包。
检查通过只说明版本元数据符合要求，不代表驱动、依赖导入、许可证或训练已经验证。后续仍按 SDK 预检和运行流程执行；首次在线训练的授权步骤见安装与授权。access key、许可证和数据库密码保留在本地，不要粘贴到对话中。
开始一项任务
先整理业务与数据
给出工作目录、数据位置、业务目标和本次允许完成的范围。例如：
请使用 revive-project 处理这个项目。
工作目录是 /absolute/path/cooling-project，数据在 data/ 下，字段说明在 business.md。
我希望根据设备观测和控制记录预测温度变化，先确认数据是否满足建模要求。
这次只整理业务信息、检查并准备数据，不启动训练，也不部署服务。
保留原始数据；缺少单位、采样时序或设备限制时，请列出需要我确认的问题。将路径和目标替换为您的实际任务。最好一并提供变量单位、设备或批次划分、观测与动作的先后顺序、可用的未来输入，以及评价指标和门槛。尚不确定的内容可以说明“待确认”，不必为了启动任务先填一个猜测值。
助手会建立项目记录，并根据当前资料检查数据。您确认的业务说明会与来源一起保留；确认业务事实不等于允许启动训练。
确认预算后训练
数据和业务条件明确后，再给出训练次数、单次时长、计算设备以及评价要求。例如：
业务事实和评价要求已确认。允许在当前项目中使用 CPU 训练，最多启动 2 次，
每次最长 10 分钟；失败、恢复和短训练检查也计入次数。
先完成一次正式训练并评价验证集，只有确有改进依据时才使用剩余预算。
按已确认的指标说明结果，预算不足或未达标时如实报告；本次不部署服务。这些数值只是预算示例，不是推荐训练量，也不保证模型在该预算内达标。参数搜索同样消耗项目预算；需要扩大范围时，应先确认新的授权。
验证集用于比较和改进方案，最终测试用于模型选定后的验收。控制策略还需要独立的仿真或业务评价，不能只凭训练奖励判断收益。需要部署时，另行明确目标环境、目录、服务范围和验收条件，见部署模型。
按需查阅文档
助手遇到具体 SDK 字段或用法问题时，只检索当前需要的文档片段，不必预先读取整套用户手册。文档来源取决于收到的 Skill 交付包：
| 交付方式 | 文档从哪里来 | 使用条件 |
|---|---|---|
| 完整包 | 随包提供的、与 SDK 版本匹配的用户文档知识包 | 文档检索可离线进行，无需另行下载官网 |
| 轻量包 | 根据随包来源配置，下载固定版本的索引和命中页面，并缓存在本地 | 首次获取未缓存内容时需要联网，且对应静态文档快照已发布 |
轻量包不要求本地预先保存整套文档，也不需要部署 MCP 服务。普通官网页面地址不能直接代替来源配置：交付方需要提供配套的静态知识快照和 knowledge/source.json。尚未取得这些材料或不能确认访问条件时，请使用完整包。
检索工具会自动确认 SDK 版本和文档快照是否匹配，不会在当前版本缺失时改用其他版本。项目首次实际检索会生成 .revive-knowledge-lock.json，用于固定文档来源。更新 Skill 或切换完整包、轻量包前，请核对版本；遇到快照不匹配时，不要直接删除该记录。
下载的文档会缓存在本地。要求检索完全不联网时，可让助手使用检索工具的 --offline 选项；完整包可以继续检索，轻量包只能使用已缓存的索引和页面。--refresh 用于重新读取已读片段，不会升级文档版本，也不能补齐离线时缺失的页面。
文档下载只请求清单、索引和页面，查询词在本地处理，不随这些请求上传业务数据。AI 助手自身如何处理对话和文件，仍取决于其服务和隐私设置；SDK 在线授权的配置步骤见安装与授权。
查看结果与继续任务
默认项目结构中，业务记录和 SDK 配置分开保存，运行产物位于 work/。实际路径以项目的 output_dir 和本次执行结果为准；尚未执行的步骤不会提前生成对应产物。
| 文件或目录 | 用来查看什么 |
|---|---|
project.yaml | 业务事实、数据定义、执行授权、预算和评价要求 |
config.yaml | 提交给 REVIVE 的原生模型与训练配置 |
work/prepared/ | 准备后的数据和划分记录 |
work/tasks/ | 配置版本及对应的业务图、决策流图 |
work/jobs/、work/runs/ | 执行记录、日志、模型和评价结果 |
work/deployments/ | 完成打包后的模型与交付材料，不表示服务已启动 |
project.yaml 是 Skill 的项目记录，不是 SDK 训练配置，不要将它直接传给 revive train --config。
关闭对话后继续工作时，保留整个项目目录，并让助手先检查已有状态：
请使用 revive-project 继续 /absolute/path/cooling-project。
先读取 project.yaml 并检查磁盘上的任务、运行和结果记录，说明已经完成的阶段。
沿用现有预算和授权范围，不因缺少聊天记录而重新训练。交付时请查看实际完成的步骤、模型身份、原始单位下的指标、未达标或未执行的项目，以及部署验证状态。导出文件存在不等于模型已满足业务门槛；本机服务验证通过也不等于生产环境已经验收。
常见问题
| 问题 | 处理方式 |
|---|---|
| 助手没有使用 Skill | 检查完整目录和层级，在 Codex 中显式使用 $revive-project；必要时重启会话 |
没有 Node.js 或不能联网运行 npx | 按离线方式复制完整 Skill，无需为了加载 Skill 安装 Node.js |
| 找不到脚本或提示缺少依赖 | 让助手先运行随包的 doctor.py，确认 SDK 对应的 Python 和缺失项，确认后再安装依赖 |
| 已安装 REVIVE，但检查不到 SDK | 告知助手实际的 Python 可执行文件路径，先切换到正确环境再检查，不要在其他环境重复安装 |
提示 source_not_configured | 轻量包缺少可信来源配置，请向交付方获取配套材料，或改用完整包 |
提示 download_failed 或 offline_missing | 检查文档入口和网络；离线时只能使用完整包或已有缓存，未缓存的页面不能继续下载 |
提示 snapshot_mismatch 或 integrity_error | 保留项目锁、缓存和报错，联系交付方获取与当前项目版本匹配的文档包 |
| 已配置 access key，但预检提示无许可证 | 预检不申请在线许可证；按首次运行在已授权预算内启动训练，或先安装离线许可证 |