FA Installer

install/ 是 @fa-software/context-kit-install 的独立 npm 子项目，用于把标准安装包分发到 Claude Code、Codex、OpenCode。

安装包格式

安装源必须满足以下结构：

<root>/
  manifest.json
  skills/
  agents/
    <category>/
      <agent>.md

说明：

• skills/ 仍按技能目录结构提供源码。
• agents/ 支持子目录组织 canonical source，例如 agents/review/foo.md、agents/research/bar.md。
• 安装时 agent 会按目标平台要求平铺写入目标 agent 根目录，而不是保留源码子目录结构。
• 安装后的 agent 文件名统一以 fa- 开头；若源码 basename 已带 fa-，则保持不变。
• 因为安装产物会平铺，agents/** 下的源码 basename 必须全局唯一。

manifest.json 目前要求：

{
  "schemaVersion": 1,
  "packageName": "fa-context-kit",
  "version": "1.0.0",
  "buildType": "debug",
  "platforms": ["claude", "codex", "opencode"]
}

远程 source 必须是压缩包 URL，本地 source 必须是目录路径。

命令

node install.js --source=.. --claude --local
node install.js status --all --local
node install.js uninstall --claude --local --yes

支持的子命令：

• install
• status
• uninstall

支持的核心参数：

• --source=<url-or-path>
• --claude
• --codex
• --opencode
• --all
• --global
• --local
• --dry-run
• --yes
• --force
• --allow-downgrade

状态与升级

安装器会在目标目录下写入：

.fa/install-state.json

该文件记录当前版本和托管文件列表。升级时只处理托管文件，不碰未托管文件。

如果托管文件已被用户修改：

• 默认报冲突并停止
• 仅 --force 才覆盖或删除

开发

npm run check
npm test

发布前会执行：

npm run prepack