npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/migration/migration-openclaw-migration.md DELETED Viewed

@@ -1,316 +0,0 @@
----
-title: "Openclaw Migration — 将用户的 OpenClaw 自定义配置迁移到 Hermes Agent"
-sidebar_label: "Openclaw Migration"
-description: "将用户的 OpenClaw 自定义配置迁移到 Hermes Agent"
----
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-# Openclaw Migration
-将用户的 OpenClaw 自定义配置迁移到 Hermes Agent。从 `~/.openclaw` 导入 Hermes 兼容的记忆、`SOUL.md`、命令白名单、用户技能及所选工作区资产，并精确报告无法迁移的内容及原因。
-## Skill 元数据
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/migration/openclaw-migration` 安装 |
-| 路径 | `optional-skills/migration/openclaw-migration` |
-| 版本 | `1.0.0` |
-| 作者 | Hermes Agent (Nous Research) |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `Migration`, `OpenClaw`, `Hermes`, `Memory`, `Persona`, `Import` |
-| 相关 skill | [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-## 参考：完整 SKILL.md
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
-:::
-# OpenClaw -> Hermes 迁移
-当用户希望以最少的手动清理将其 OpenClaw 配置迁移到 Hermes Agent 时，使用此 skill。
-## CLI 命令
-如需快速、非交互式迁移，使用内置 CLI 命令：
-```bash
-hermes claw migrate              # Full interactive migration
-hermes claw migrate --dry-run    # Preview what would be migrated
-hermes claw migrate --preset user-data   # Migrate without secrets
-hermes claw migrate --overwrite  # Overwrite existing conflicts
-hermes claw migrate --source /custom/path/.openclaw  # Custom source
-```
-CLI 命令运行与下文所述相同的迁移脚本。当需要交互式、引导式迁移并支持 dry-run（预览）和逐项冲突解决时，请通过 agent 使用此 skill。
-**首次设置：** `hermes setup` 向导会自动检测 `~/.openclaw`，并在配置开始前提供迁移选项。
-## 此 skill 的功能
-它使用 `scripts/openclaw_to_hermes.py` 来：
-- 将 `SOUL.md` 导入 Hermes 主目录，保存为 `SOUL.md`
-- 将 OpenClaw 的 `MEMORY.md` 和 `USER.md` 转换为 Hermes 记忆条目
-- 将 OpenClaw 命令审批模式合并到 Hermes `command_allowlist`
-- 迁移 Hermes 兼容的消息设置，例如 `TELEGRAM_ALLOWED_USERS` 和 `MESSAGING_CWD`
-- 将 OpenClaw skill 复制到 `~/.hermes/skills/openclaw-imports/`
-- 可选地将 OpenClaw 工作区指令文件复制到所选 Hermes 工作区
-- 将兼容的工作区资产（如 `workspace/tts/`）镜像到 `~/.hermes/tts/`
-- 归档没有直接 Hermes 目标的非机密文档
-- 生成结构化报告，列出已迁移项、冲突项、跳过项及原因
-## 路径解析
-辅助脚本位于此 skill 目录下：
-- `scripts/openclaw_to_hermes.py`
-从 Skills Hub 安装此 skill 后，通常位于：
-- `~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py`
-请勿猜测更短的路径，如 `~/.hermes/skills/openclaw-migration/...`。
-运行辅助脚本前：
-1. 优先使用 `~/.hermes/skills/migration/openclaw-migration/` 下的已安装路径。
-2. 如果该路径失败，检查已安装的 skill 目录，并相对于已安装的 `SKILL.md` 解析脚本路径。
-3. 仅在已安装位置缺失或 skill 被手动移动时，才使用 `find` 作为备用方案。
-4. 调用终端工具时，不要传入 `workdir: "~"`。请使用绝对目录（如用户主目录），或完全省略 `workdir`。
-使用 `--migrate-secrets` 时，还将导入一小组 Hermes 兼容的白名单 secret，目前包括：
-- `TELEGRAM_BOT_TOKEN`
-## 默认工作流
-1. 首先通过 dry run 进行检查。
-2. 呈现简洁摘要，说明哪些内容可以迁移、哪些不能迁移、哪些将被归档。
-3. 如果 `clarify` 工具可用，使用它处理用户决策，而非要求自由格式的文字回复。
-4. 如果 dry run 发现已导入 skill 目录存在冲突，在执行前询问处理方式。
-5. 在执行前，请用户在两种支持的迁移模式中选择一种。
-6. 仅在用户希望迁移工作区指令文件时，才询问目标工作区路径。
-7. 使用匹配的 preset 和标志执行迁移。
-8. 汇总结果，重点说明：
-   - 已迁移的内容
-   - 已归档待手动审查的内容
-   - 已跳过的内容及原因
-## 用户交互协议
-Hermes CLI 支持 `clarify` 工具进行交互式提示，但有以下限制：
-- 每次只能处理一个选择
-- 最多 4 个预定义选项
-- 自动提供 `Other` 自由文本选项
-它**不**支持在单个提示中进行真正的多选复选框操作。
-每次 `clarify` 调用：
-- 必须包含非空的 `question`
-- 仅对真实可选提示包含 `choices`
-- `choices` 限制为 2-4 个纯字符串选项
-- 不得输出占位符或截断选项，如 `...`
-- 不得在选项中填充或添加额外空白
-- 不得在问题中包含虚假表单字段，如 `在此输入目录`、空白行或下划线 `_____`
-- 对于开放式路径问题，只询问纯文本句子；用户在面板下方的普通 CLI 提示符中输入
-如果 `clarify` 调用返回错误，检查错误文本，修正 payload，并使用有效的 `question` 和干净的 choices 重试一次。
-当 `clarify` 可用且 dry run 揭示任何需要用户决策的情况时，**下一个动作必须是 `clarify` 工具调用**。
-不得以如下普通助手消息结束对话：
-- "让我来呈现选项"
-- "您希望怎么做？"
-- "以下是选项"
-如果需要用户决策，在生成更多文字之前通过 `clarify` 收集。
-如果存在多个未解决的决策，不要在它们之间插入解释性助手消息。收到一个 `clarify` 响应后，下一个动作通常应是下一个必要的 `clarify` 调用。
-当 dry run 报告以下情况时，将 `workspace-agents` 视为未解决的决策：
-- `kind="workspace-agents"`
-- `status="skipped"`
-- 原因包含 `No workspace target was provided`
-在这种情况下，必须在执行前询问工作区指令问题。不得静默地将其视为跳过的决策。
-由于上述限制，使用以下简化决策流程：
-1. 对于 `SOUL.md` 冲突，使用 `clarify`，选项如：
-   - `keep existing`
-   - `overwrite with backup`
-   - `review first`
-2. 如果 dry run 显示一个或多个 `kind="skill"` 项的 `status="conflict"`，使用 `clarify`，选项如：
-   - `keep existing skills`
-   - `overwrite conflicting skills with backup`
-   - `import conflicting skills under renamed folders`
-3. 对于工作区指令，使用 `clarify`，选项如：
-   - `skip workspace instructions`
-   - `copy to a workspace path`
-   - `decide later`
-4. 如果用户选择复制工作区指令，追加一个开放式 `clarify` 问题，要求提供**绝对路径**。
-5. 如果用户选择 `skip workspace instructions` 或 `decide later`，继续执行而不添加 `--workspace-target`。
-5. 对于迁移模式，使用 `clarify`，提供以下 3 个选项：
-   - `user-data only`
-   - `full compatible migration`
-   - `cancel`
-6. `user-data only` 表示：迁移用户数据和兼容配置，但**不**导入白名单 secret。
-7. `full compatible migration` 表示：迁移相同的兼容用户数据，并在存在时导入白名单 secret。
-8. 如果 `clarify` 不可用，以普通文本提出相同问题，但仍将答案限制为 `user-data only`、`full compatible migration` 或 `cancel`。
-执行门控：
-- 当由 `No workspace target was provided` 导致的 `workspace-agents` 跳过仍未解决时，不得执行。
-- 唯一有效的解决方式为：
-  - 用户明确选择 `skip workspace instructions`
-  - 用户明确选择 `decide later`
-  - 用户在选择 `copy to a workspace path` 后提供了工作区路径
-- dry run 中缺少工作区目标本身并不构成执行许可。
-- 当任何必要的 `clarify` 决策仍未解决时，不得执行。
-使用以下精确的 `clarify` payload 形式作为默认模式：
-- `{"question":"Your existing SOUL.md conflicts with the imported one. What should I do?","choices":["keep existing","overwrite with backup","review first"]}`
-- `{"question":"One or more imported OpenClaw skills already exist in Hermes. How should I handle those skill conflicts?","choices":["keep existing skills","overwrite conflicting skills with backup","import conflicting skills under renamed folders"]}`
-- `{"question":"Choose migration mode: migrate only user data, or run the full compatible migration including allowlisted secrets?","choices":["user-data only","full compatible migration","cancel"]}`
-- `{"question":"Do you want to copy the OpenClaw workspace instructions file into a Hermes workspace?","choices":["skip workspace instructions","copy to a workspace path","decide later"]}`
-- `{"question":"Please provide an absolute path where the workspace instructions should be copied."}`
-## 决策到命令的映射
-将用户决策精确映射到命令标志：
-- 如果用户对 `SOUL.md` 选择 `keep existing`，**不**添加 `--overwrite`。
-- 如果用户选择 `overwrite with backup`，添加 `--overwrite`。
-- 如果用户选择 `review first`，在执行前停止并审查相关文件。
-- 如果用户选择 `keep existing skills`，添加 `--skill-conflict skip`。
-- 如果用户选择 `overwrite conflicting skills with backup`，添加 `--skill-conflict overwrite`。
-- 如果用户选择 `import conflicting skills under renamed folders`，添加 `--skill-conflict rename`。
-- 如果用户选择 `user-data only`，使用 `--preset user-data` 执行，**不**添加 `--migrate-secrets`。
-- 如果用户选择 `full compatible migration`，使用 `--preset full --migrate-secrets` 执行。
-- 仅在用户明确提供绝对工作区路径时，才添加 `--workspace-target`。
-- 如果用户选择 `skip workspace instructions` 或 `decide later`，不添加 `--workspace-target`。
-执行前，用简洁语言重述精确的命令计划，并确保其与用户的选择一致。
-## 运行后报告规则
-执行后，将脚本的 JSON 输出作为事实来源。
-1. 所有计数基于 `report.summary`。
-2. 仅当 `status` 恰好为 `migrated` 时，才将该项列入"已成功迁移"。
-3. 除非报告显示该项为 `migrated`，否则不得声称冲突已解决。
-4. 除非 `kind="soul"` 的报告项 `status="migrated"`，否则不得声称 `SOUL.md` 已被覆盖。
-5. 如果 `report.summary.conflict > 0`，包含冲突部分，而非静默暗示成功。
-6. 如果计数与列出的项不一致，在回复前修正列表以匹配报告。
-7. 在可用时包含报告中的 `output_dir` 路径，以便用户检查 `report.json`、`summary.md`、备份和归档文件。
-8. 对于记忆或用户档案溢出，除非报告明确显示归档路径，否则不得声称条目已被归档。如果 `details.overflow_file` 存在，说明完整溢出列表已导出到该位置。
-9. 如果 skill 以重命名文件夹导入，报告最终目标并提及 `details.renamed_from`。
-10. 如果 `report.skill_conflict_mode` 存在，将其作为所选已导入 skill 冲突策略的事实来源。
-11. 如果某项 `status="skipped"`，不得将其描述为已覆盖、已备份、已迁移或已解决。
-12. 如果 `kind="soul"` 的 `status="skipped"` 且原因为 `Target already matches source`，说明其保持不变，不提及备份。
-13. 如果重命名的已导入 skill 的 `details.backup` 为空，不得暗示现有 Hermes skill 已被重命名或备份。仅说明已导入的副本被放置在新目标位置，并将 `details.renamed_from` 作为保持原位的已有文件夹引用。
-## 迁移 preset
-正常使用时优先选择以下两个 preset：
-- `user-data`
-- `full`
-`user-data` 包含：
-- `soul`
-- `workspace-agents`
-- `memory`
-- `user-profile`
-- `messaging-settings`
-- `command-allowlist`
-- `skills`
-- `tts-assets`
-- `archive`
-`full` 包含 `user-data` 中的所有内容，另加：
-- `secret-settings`
-辅助脚本仍支持类别级别的 `--include` / `--exclude`，但将其视为高级备用方案，而非默认用户体验。
-## 命令
-完整发现的 dry run：
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py
-```
-使用终端工具时，优先使用绝对调用模式，例如：
-```json
-{"command":"python3 /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"}
-```
-使用 user-data preset 的 dry run：
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data
-```
-执行 user-data 迁移：
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip
-```
-执行完整兼容迁移：
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip
-```
-包含工作区指令的执行：
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path"
-```
-默认情况下不要使用 `$PWD` 或主目录作为工作区目标。请先明确询问工作区路径。
-## 重要规则
-1. 除非用户明确表示立即执行，否则在写入前先运行 dry run。
-2. 默认不迁移 secret。Token、认证 blob、设备凭据和原始 gateway 配置应保留在 Hermes 之外，除非用户明确要求迁移 secret。
-3. 除非用户明确要求，否则不得静默覆盖非空的 Hermes 目标。辅助脚本在启用覆盖时会保留备份。
-4. 始终向用户提供跳过项报告。该报告是迁移的一部分，而非可选附加内容。
-5. 优先使用主 OpenClaw 工作区（`~/.openclaw/workspace/`）而非 `workspace.default/`。仅在主文件缺失时才使用默认工作区作为备用。
-6. 即使在 secret 迁移模式下，也只迁移具有干净 Hermes 目标的 secret。不支持的认证 blob 仍须报告为已跳过。
-7. 如果 dry run 显示大型资产复制、冲突的 `SOUL.md` 或溢出的记忆条目，在执行前单独指出这些情况。
-8. 如果用户不确定，默认选择 `user-data only`。
-9. 仅在用户明确提供目标工作区路径时，才包含 `workspace-agents`。
-10. 将类别级别的 `--include` / `--exclude` 视为高级逃生通道，而非正常流程。
-11. 如果 `clarify` 可用，不得在 dry run 摘要结尾使用含糊的"您希望怎么做？"。改用结构化的后续提示。
-12. 当真实选择提示可用时，不要使用开放式 `clarify` 提示。优先使用可选选项，仅对绝对路径或文件审查请求使用自由文本。
-13. dry run 后，如果仍有未解决的决策，不得在摘要后停止。立即对最高优先级的阻塞决策使用 `clarify`。
-14. 后续问题的优先顺序：
-    - `SOUL.md` 冲突
-    - 已导入 skill 冲突
-    - 迁移模式
-    - 工作区指令目标
-15. 不得在同一消息中承诺稍后呈现选项。通过实际调用 `clarify` 来呈现它们。
-16. 在收到迁移模式答案后，明确检查 `workspace-agents` 是否仍未解决。如果是，下一个动作必须是工作区指令的 `clarify` 调用。
-17. 在任何 `clarify` 答案之后，如果还有其他必要决策待处理，不要叙述刚刚决定的内容。立即提出下一个必要问题。
-## 预期结果
-成功运行后，用户应拥有：
-- 已导入的 Hermes persona 状态
-- 已填充转换后 OpenClaw 知识的 Hermes 记忆文件
-- 在 `~/.hermes/skills/openclaw-imports/` 下可用的 OpenClaw skill
-- 显示任何冲突、遗漏或不支持数据的迁移报告

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/mlops/mlops-accelerate.md DELETED Viewed

@@ -1,350 +0,0 @@
----
-title: "Huggingface Accelerate — 最简分布式训练 API"
-sidebar_label: "Huggingface Accelerate"
-description: "最简分布式训练 API"
----
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-# Huggingface Accelerate
-最简分布式训练 API。仅需 4 行代码即可为任意 PyTorch 脚本添加分布式支持。统一的 DeepSpeed/FSDP/Megatron/DDP API。自动设备放置、混合精度（FP16/BF16/FP8）。交互式配置，单条启动命令。HuggingFace 生态系统标准。
-## Skill 元数据
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/mlops/accelerate` 安装 |
-| 路径 | `optional-skills/mlops/accelerate` |
-| 版本 | `1.0.0` |
-| 作者 | Orchestra Research |
-| 许可证 | MIT |
-| 依赖项 | `accelerate`, `torch`, `transformers` |
-| 平台 | linux, macos, windows |
-| 标签 | `Distributed Training`, `HuggingFace`, `Accelerate`, `DeepSpeed`, `FSDP`, `Mixed Precision`, `PyTorch`, `DDP`, `Unified API`, `Simple` |
-## 参考：完整 SKILL.md
-:::info
-以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
-:::
-# HuggingFace Accelerate - 统一分布式训练
-## 快速开始
-Accelerate 将分布式训练简化为 4 行代码。
-**安装**：
-```bash
-pip install accelerate
-```
-**转换 PyTorch 脚本**（4 行）：
-```python
-import torch
-+ from accelerate import Accelerator
-+ accelerator = Accelerator()
-  model = torch.nn.Transformer()
-  optimizer = torch.optim.Adam(model.parameters())
-  dataloader = torch.utils.data.DataLoader(dataset)
-+ model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
-  for batch in dataloader:
-      optimizer.zero_grad()
-      loss = model(batch)
--     loss.backward()
-+     accelerator.backward(loss)
-      optimizer.step()
-```
-**运行**（单条命令）：
-```bash
-accelerate launch train.py
-```
-## 常见工作流
-### 工作流 1：从单 GPU 到多 GPU
-**原始脚本**：
-```python
-# train.py
-import torch
-model = torch.nn.Linear(10, 2).to('cuda')
-optimizer = torch.optim.Adam(model.parameters())
-dataloader = torch.utils.data.DataLoader(dataset, batch_size=32)
-for epoch in range(10):
-    for batch in dataloader:
-        batch = batch.to('cuda')
-        optimizer.zero_grad()
-        loss = model(batch).mean()
-        loss.backward()
-        optimizer.step()
-```
-**使用 Accelerate**（新增 4 行）：
-```python
-# train.py
-import torch
-from accelerate import Accelerator  # +1
-accelerator = Accelerator()  # +2
-model = torch.nn.Linear(10, 2)
-optimizer = torch.optim.Adam(model.parameters())
-dataloader = torch.utils.data.DataLoader(dataset, batch_size=32)
-model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)  # +3
-for epoch in range(10):
-    for batch in dataloader:
-        # 无需 .to('cuda') — 自动处理！
-        optimizer.zero_grad()
-        loss = model(batch).mean()
-        accelerator.backward(loss)  # +4
-        optimizer.step()
-```
-**配置**（交互式）：
-```bash
-accelerate config
-```
-**问题**：
-- 使用哪种机器？（单/多 GPU/TPU/CPU）
-- 机器数量？（1）
-- 混合精度？（no/fp16/bf16/fp8）
-- DeepSpeed？（no/yes）
-**启动**（适用于任意配置）：
-```bash
-# 单 GPU
-accelerate launch train.py
-# 多 GPU（8 个 GPU）
-accelerate launch --multi_gpu --num_processes 8 train.py
-# 多节点
-accelerate launch --multi_gpu --num_processes 16 \
-  --num_machines 2 --machine_rank 0 \
-  --main_process_ip $MASTER_ADDR \
-  train.py
-```
-### 工作流 2：混合精度训练
-**启用 FP16/BF16**：
-```python
-from accelerate import Accelerator
-# FP16（带梯度缩放）
-accelerator = Accelerator(mixed_precision='fp16')
-# BF16（无缩放，更稳定）
-accelerator = Accelerator(mixed_precision='bf16')
-# FP8（H100+）
-accelerator = Accelerator(mixed_precision='fp8')
-model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
-# 其余均自动处理！
-for batch in dataloader:
-    with accelerator.autocast():  # 可选，已自动完成
-        loss = model(batch)
-    accelerator.backward(loss)
-```
-### 工作流 3：DeepSpeed ZeRO 集成
-**启用 DeepSpeed ZeRO-2**：
-```python
-from accelerate import Accelerator
-accelerator = Accelerator(
-    mixed_precision='bf16',
-    deepspeed_plugin={
-        "zero_stage": 2,  # ZeRO-2
-        "offload_optimizer": False,
-        "gradient_accumulation_steps": 4
-    }
-)
-# 代码与之前完全相同！
-model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
-```
-**或通过配置**：
-```bash
-accelerate config
-# 选择：DeepSpeed → ZeRO-2
-```
-**deepspeed_config.json**：
-```json
-{
-    "fp16": {"enabled": false},
-    "bf16": {"enabled": true},
-    "zero_optimization": {
-        "stage": 2,
-        "offload_optimizer": {"device": "cpu"},
-        "allgather_bucket_size": 5e8,
-        "reduce_bucket_size": 5e8
-    }
-}
-```
-**启动**：
-```bash
-accelerate launch --config_file deepspeed_config.json train.py
-```
-### 工作流 4：FSDP（全分片数据并行）
-**启用 FSDP**：
-```python
-from accelerate import Accelerator, FullyShardedDataParallelPlugin
-fsdp_plugin = FullyShardedDataParallelPlugin(
-    sharding_strategy="FULL_SHARD",  # 等价于 ZeRO-3
-    auto_wrap_policy="TRANSFORMER_AUTO_WRAP",
-    cpu_offload=False
-)
-accelerator = Accelerator(
-    mixed_precision='bf16',
-    fsdp_plugin=fsdp_plugin
-)
-model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
-```
-**或通过配置**：
-```bash
-accelerate config
-# 选择：FSDP → Full Shard → No CPU Offload
-```
-### 工作流 5：梯度累积
-**累积梯度**：
-```python
-from accelerate import Accelerator
-accelerator = Accelerator(gradient_accumulation_steps=4)
-model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)
-for batch in dataloader:
-    with accelerator.accumulate(model):  # 自动处理累积
-        optimizer.zero_grad()
-        loss = model(batch)
-        accelerator.backward(loss)
-        optimizer.step()
-```
-**有效批大小**：`batch_size * num_gpus * gradient_accumulation_steps`
-## 与替代方案的对比
-**适合使用 Accelerate 的场景**：
-- 需要最简单的分布式训练方式
-- 需要单脚本适配任意硬件
-- 使用 HuggingFace 生态系统
-- 需要灵活性（DDP/DeepSpeed/FSDP/Megatron）
-- 需要快速原型开发
-**核心优势**：
-- **4 行代码**：代码改动极少
-- **统一 API**：同一套代码适用于 DDP、DeepSpeed、FSDP、Megatron
-- **自动化**：设备放置、混合精度、分片均自动处理
-- **交互式配置**：无需手动配置启动器
-- **单条启动命令**：适用于所有环境
-**适合使用替代方案的场景**：
-- **PyTorch Lightning**：需要回调机制、高层抽象
-- **Ray Train**：多节点编排、超参数调优
-- **DeepSpeed**：直接 API 控制、高级特性
-- **原生 DDP**：最大控制权、最少抽象层
-## 常见问题
-**问题：设备放置错误**
-不要手动移动到设备：
-```python
-# 错误
-batch = batch.to('cuda')
-# 正确
-# Accelerate 在 prepare() 之后自动处理
-```
-**问题：梯度累积不生效**
-使用上下文管理器：
-```python
-# 正确
-with accelerator.accumulate(model):
-    optimizer.zero_grad()
-    accelerator.backward(loss)
-    optimizer.step()
-```
-**问题：分布式环境下的检查点保存**
-使用 accelerator 方法：
-```python
-# 仅在主进程保存
-if accelerator.is_main_process:
-    accelerator.save_state('checkpoint/')
-# 在所有进程上加载
-accelerator.load_state('checkpoint/')
-```
-**问题：FSDP 结果不一致**
-确保使用相同的随机种子：
-```python
-from accelerate.utils import set_seed
-set_seed(42)
-```
-## 高级主题
-**Megatron 集成**：张量并行、流水线并行和序列并行的配置，请参阅 [references/megatron-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/megatron-integration.md)。
-**自定义插件**：创建自定义分布式插件及高级配置，请参阅 [references/custom-plugins.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/custom-plugins.md)。
-**性能调优**：性能分析、内存优化及最佳实践，请参阅 [references/performance.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/performance.md)。
-## 硬件要求
-- **CPU**：支持（速度较慢）
-- **单 GPU**：支持
-- **多 GPU**：DDP（默认）、DeepSpeed 或 FSDP
-- **多节点**：DDP、DeepSpeed、FSDP、Megatron
-- **TPU**：支持
-- **Apple MPS**：支持
-**启动器要求**：
-- **DDP**：`torch.distributed.run`（内置）
-- **DeepSpeed**：`deepspeed`（pip install deepspeed）
-- **FSDP**：PyTorch 1.12+（内置）
-- **Megatron**：需自定义配置
-## 资源
-- 文档：https://huggingface.co/docs/accelerate
-- GitHub：https://github.com/huggingface/accelerate
-- 版本：1.11.0+
-- 教程："Accelerate your scripts"
-- 示例：https://github.com/huggingface/accelerate/tree/main/examples
-- 使用方：HuggingFace Transformers、TRL、PEFT 及所有 HF 库