@xyzensun/filelay

通用 CLI 工具：从 git 仓库按 YAML 规则把文件铺到指定目录。目标平台由规则文件定义，AI agent 平台只是其中一种用法。

安装与用法

无需安装，直接通过 npx 使用：

npx @xyzensun/filelay add <git仓库> [规则文件] [放置目录] [平台]

| 参数 | 必填 | 默认 | 说明 | | --- | --- | --- | --- | | add | 是 | — | 显式子命令，为将来 remove / update 留扩展 | | <git仓库> | 是 | — | git 仓库地址，支持 #branch 指定分支 | | [规则文件] | 否 | 仓库根 filelay.yaml（兼容 .yml） | 也可为本地路径或远程 URL（如 https://a.com/a.yaml） | | [放置目录] | 否 | .（当前目录） | 替换路径中的 {TARGET_PATH} | | [平台] | 否 | 自动 / 交互 | 规则里只有一个平台则自动使用；多个则交互式选择 |

需要跳过中间的可选参数时，用 - 占位表示"使用默认值"，例如：

# 使用仓库内默认规则文件，放置到 ./out，平台 pi
npx @xyzensun/filelay add https://github.com/a/b - ./out pi

Flags

• --force：目标已存在时直接全覆盖，不询问
• --dry-run：只预览将要进行的操作，不实际写入
• -h, --help：显示帮助
• -v, --version：显示版本

规则文件 filelay.yaml

version: 1

# 本仓库支持的平台；用户未指定时从这里交互选择
platforms:
  claude-code:
    description: Claude Code
  pi:
    description: Pi coding agent

# 文件摆放规则
files:
  # source 相对仓库根；指向目录则递归拷贝
  - source: skills/my-skill
    targets:
      claude-code: "{HOME}/.claude/skills/my-skill"
      pi: "{HOME}/.pi/agent/skills/my-skill"

  - source: prompts/review.md
    targets:
      claude-code: "{TARGET_PATH}/.claude/prompts/review.md"   # 相对放置目录
      pi: "{TARGET_PATH}/prompts/review.md"

路径变量

• {TARGET_PATH}：可在路径任意位置出现，替换为放置目录（默认 .）。不支持 $ 简写。
• {HOME}：家目录（v1 仅此一个额外变量）。
• 不含任何变量的路径：
  • 以 ~ 开头 → 展开为家目录
  • 否则视为绝对路径
  • 裸相对路径 → 报错（避免歧义）

仓库获取

• 一律 git clone --depth 1 克隆到系统临时目录，不区分托管平台。
• 支持 #branch 指定分支；不做 tag 语义校验。
• 拷贝完成后临时目录（含 .git）整体删除。

source 规则

• 一律相对仓库根（即使规则文件来自本地路径或远程 URL）。
• 指向目录时递归拷贝整个目录（含子目录），符号链接不追踪。
• 不支持 glob（想铺多个文件就用目录，或逐条列）。

冲突与错误处理

• 目标路径已存在时，默认交互询问（覆盖 / 跳过 / 备份为 .bak）；--force 全覆盖；--dry-run 只预览。
• 仓库里没有 filelay.yaml 且未指定规则文件，或指定的规则文件不可达（本地不存在 / URL 拉取失败）→ 报错退出。

环境要求

• Node.js >= 20
• 系统已安装 git

License

MIT