mcpField
H
habitat-usage

habitat-usage

github.com/lynx-community开发28233 次安装1 天前更新
代码仓库

关于 habitat-usage

habitat-usage 是 Habitat 依赖同步工具的使用指南技能，面向维护多 Git 仓库和资产依赖的开发者。它提供配置示例、同步建议与故障排查步骤。

主要功能

  1. 01配置 .habitat 与 DEPS
  2. 02管理 Git 和嵌套解决方案依赖
  3. 03下载 HTTP 资产并校验完整性
  4. 04执行自定义同步操作
  5. 05排查同步错误与超时

适用场景

  1. 01搭建主仓库及依赖仓库工作区
  2. 02配置归档文件或工具链下载
  3. 03诊断认证、网络或校验失败

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lynx-community/skills --skill habitat-usage

安装后在 Claude Code 中输入/habitat-usage确认已加载。

附带文件scripts/index.mjs

详细介绍

Habitat 使用指南

Habitat 是一种依赖同步工具，适用于由多个 Git 仓库和资源下载构成的类似单体仓库的布局。本技能提供设置指南、可直接复制粘贴的配置片段，以及常见同步故障的排查清单。

适用场景

  • 使用 .habitat + DEPS 设置“主仓库 + 依赖仓库/资源”工作区
  • 添加或更改依赖类型：Git 仓库、嵌套 solution、HTTP 下载或自定义操作
  • 排查与配置、身份验证、网络或完整性检查相关的 hab sync 失败

故障排查所需信息

同步失败时（获取错误、权限问题、超时），请收集：

  • Habitat 版本和分发形式（仓库中的 ./hab 包装器、hab.pex 等）
  • 操作系统和架构（darwin/windows/linux + arm64/x86_64）
  • 完整命令和完整错误输出（请勿粘贴任何机密信息）
  • 相关配置片段：
    • .habitat
    • DEPS（或 .habitat 中 deps_file 指向的文件）

安装和版本管理

建议将 Habitat 包装器（hab）和配置文件（.habitat、DEPS）提交到仓库中，以便开发者和 CI 使用相同的版本和配置。

避免在自动化流程中下载 releases/latest，因为这无法保证可复现。应固定到特定的发布版本（标签），并确保开发者和 CI 使用的固定版本一致。

HABITAT_VERSION="0.3.145"
curl -L -o hab "https://github.com/lynx-family/habitat/releases/download/${HABITAT_VERSION}/hab"
chmod +x hab

如果只是想在本地试用 Habitat（不建议用于 CI），可以下载最新发布版本：

curl -L -o hab "https://github.com/lynx-family/habitat/releases/latest/download/hab"
chmod +x hab

如果需要完整性验证，请在仓库/CI 中固定 hab 的预期 SHA-256，并在下载后进行验证：

EXPECTED_SHA256="<fill-me>"

if command -v shasum >/dev/null 2>&1; then
  echo "${EXPECTED_SHA256}  hab" | shasum -a 256 -c -
else
  echo "${EXPECTED_SHA256}  hab" | sha256sum -c -
fi

多仓库设置（solutions + deps）

1) 生成 .habitat（solution 配置）

在主仓库根目录生成 Habitat 配置：

./hab config <repo remote uri>

.habitat 描述一个或多个 solutions。最简示例：

solutions = [
    {
        "name": ".",
        "deps_file": "DEPS",
        "url": "[email protected]:namespace/repo.git",
    }
]

字段：

  • name：solution 名称，主仓库通常使用 "."
  • deps_file：依赖清单路径（相对于主仓库根目录）
  • url：主仓库远程 URL（供工具/CI 使用）
2) 编写 DEPS（依赖清单）

在 DEPS 中定义 deps = { ... }。键是主仓库中的目标路径，值描述依赖类型及其参数。

2.1 git deps（源代码仓库）
deps = {
    "lib/example": {
        "type": "git",
        "url": "[email protected]:namespace/lib.git",
        "branch": "dev",
    }
}

注意：

  • 为确保可复现，优先使用稳定的引用（例如提交）；若需要持续更新，则使用分支。
  • 如果目标目录已存在且包含本地更改，请在同步前确认是否可以覆盖。
2.2 solution deps（嵌套 solutions）

如果某个依赖有自己的依赖树，可以将其作为 solution 引入并递归同步：

deps = {
    "third_party/some_solution": {
        "type": "solution",
        "url": "[email protected]:namespace/solution_repo.git",
        "branch": "main",
        "deps_file": "DEPS",
    }
}
2.3 http deps（资源/归档文件/二进制文件）

可用于下载归档文件、工具链、模型文件等。为确保可验证和可复现，建议提供完整性检查：

deps = {
    "third_party/tooling": {
        "type": "http",
        "url": "https://example.com/tooling.zip",
        "sha256": "SHA256_HEX",
    }
}
2.4 action deps（自定义同步操作）

可用于在同步期间执行额外步骤（生成文件、复制资源、应用补丁等）。示例：

def example_function():
    from pathlib import Path
    import shutil

    dest_dir = Path("scripts/sync_something")
    dest_dir.mkdir(parents=True, exist_ok=True)
    src = dest_dir / "input.txt"
    dst = dest_dir / "output.txt"
    src.write_text("example\n", encoding="utf-8")
    shutil.copyfile(src, dst)


deps = {
    "scripts/sync_something": {
        "type": "action",
        "function": example_function,
    }
}

同步依赖（hab sync）

在主仓库根目录运行：

./hab sync .

同步后，依赖会写入 DEPS 中各个键指定的路径。

在版本控制中跟踪配置

提交包装器和配置文件，以便开发者和 CI 能通过一条命令完成引导设置：

git add hab .habitat DEPS && git commit -m "Add habitat to manage dependencies."

常见问题 / 常见故障

1) git 权限/身份验证失败

症状：

  • 出现类似 Permission denied、Authentication failed 或 Could not read from remote repository 的错误

解决方法：

  • 确保依赖项的 url 协议与当前环境相符（SSH/HTTPS）。
  • 对于 SSH，请确认已配置 SSH 密钥，且该密钥有权访问目标仓库。
  • 在 CI 中，确认运行器已配置正确的凭据。
2) http 完整性检查失败（sha256 不匹配）

症状：

  • 下载成功，但完整性验证失败

修复方法：

  • 检查 url 内容是否发生变化，或是否重定向到不同内容。
  • 为实际制品重新计算 sha256，并更新 DEPS 中的 sha256。
  • 如果 URL 会滚动变化（例如 “latest”），优先使用不可变的版本化 URL。
3) 同步卡住／超时

修复方法：

  • 找出哪个依赖速度较慢（暂时注释掉其他依赖并通过二分法排查）。
  • 检查代理设置、DNS 和网络连通性。
  • 对于大型 git 依赖，可考虑固定到某个提交，并减少不必要的历史记录（如果你的设置支持）。

响应格式（协助用户时）

用户询问如何配置依赖、修复错误或加快同步时，请按以下顺序回复：

  1. 先给出结论（根本原因 + 修复方法）
  2. 提供可直接复制粘贴的最简命令／代码片段（.habitat／DEPS／./hab sync .）
  3. 指出有风险的操作（覆盖本地目录、滚动依赖损害可复现性等）
  4. 如果仍可能失败，列出下一步所需的信息（版本、完整错误日志、相关配置片段）

评论

支持 Markdown