企业官网建设流程全解析

@gastown/gt：Gas Town 多智能体工作区管理器的 npm 安装与使用指南

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown

导读

@gastown/gt是 Gas Town（一个用于协调 AI 编码智能体的多智能体工作区管理器）的官方 npm 发行包，通过npm install -g @gastown/gt即可在 macOS、Linux 与 Windows 上安装原生的gt命令行工具。本文以 npm-package/README.md 为主体，结合 npm-package/package.json、postinstall.js、test.js 以及internal/cmd下的命令源码，完整讲解包的安装机制、平台支持矩阵、二进制下载原理、核心命令用法与手动安装/故障排查方案，读完即可在本地完成安装并初始化第一个 Gas Town rig。

包概览：npm 只是分发层，真正执行的是 Go 原生二进制

@gastown/gt本质上是一个"引导（bootstrap）"型 npm 包：它本身不含 CLI 逻辑，而是在安装阶段从项目 Releases 下载与当前平台匹配的原生二进制，再通过bin字段暴露gt命令。这一点在 npm-package/package.json 中体现得很明确：

• name：@gastown/gt，scoped 包名，避免与同名包冲突；
• version：1.2.1，与 Go 侧 CLI 版本保持一致（见 internal/cmd/version.go 中Version = "1.2.1"）；
• main/bin：bin/gt.js是命令入口，npm install -g后 npm 会为gt命令创建全局符号链接，指向该 JS 包装脚本；
• scripts.postinstall：node scripts/postinstall.js，npm 安装完成后自动触发二进制下载；
• engines：node >= 14.0.0，对 Node.js 运行时版本的最低要求；
• os/cpu：分别限定为darwin/linux/win32与x64/arm64，npm 会据此做安装前置校验；
• files：发布到 npm registry 时仅包含bin/、scripts/、README.md、LICENSE，体积精简。

该包在 npm 侧的定位是"多智能体 / 工作区管理器 / AI Agent 编排"工具，keywords字段（multi-agent、workspace-manager、ai-agent、coding-agent、claude、git、orchestration）也印证了它服务于 AI 编码智能体协调场景。

安装：一条命令搞定平台二进制

原文档给出的标准安装方式为：

npm install -g @gastown/gt

-g表示全局安装，安装后gt命令即进入PATH。文档特别强调："This will download the appropriate native binary for your platform during installation"（安装过程中会下载与你的平台匹配的原生二进制），这正是postinstall钩子承担的工作。

postinstall 下载流程拆解

npm-package/scripts/postinstall.js 是安装的核心，其执行链路如下：

1. 读取版本：require('../package.json')获取version（1.2.1），用它拼出对应版本的 Release 归档名；
2. 平台/架构映射（getPlatformInfo）：把 Node.js 的os.platform()/os.arch()映射为发布命名：
   • darwin→darwin（二进制名gt）；
   • linux→linux（二进制名gt）；
   • win32→windows（二进制名gt.exe，Windows 需要.exe后缀）；
   • 其余平台直接抛错Unsupported platform；
   • x64→amd64，arm64→arm64，其余架构抛错Unsupported architecture。
3. 拼装归档名并下载：归档命名规则为gastown_<version>_<platform>_<arch>.<ext>，其中 Windows 使用zip，其余平台使用tar.gz；下载地址指向项目的 GitHub Releases 页面（https://github.com/.../releases/download/v<version>/<archiveName>格式）。下载器对 301/302 重定向做了处理（downloadFile中会递归跟进response.headers.location），非 200 响应会被清理并报错；
4. 解压：
   • Unix 系使用tar -xzf（extractTarGz）；
   • Windows 使用powershell -command "Expand-Archive ..."（extractZip）；
   • 解压后校验二进制存在，并在非 Windows 平台执行chmodSync(binary, 0o755)赋予可执行权限；
5. 清理与验证：删除下载的归档文件，随后执行<binary> version验证二进制可运行；验证失败只打印警告，不中断安装；
6. CI 环境跳过：脚本末尾if (!process.env.CI) { install(); }—— 在 CI 环境中跳过二进制下载，避免重复拉取大文件，这属于有意的设计而非缺陷。

安装失败的兜底

如果下载阶段出错，脚本会打印可读的失败原因，并提示两条路径：从项目 Releases 页面手动下载二进制，或在项目 issues 区提交问题，随后process.exit(1)让 npm 感知安装失败。

支持平台矩阵

原文档明确列出支持范围，结合postinstall.js与package.json的os/cpu字段可得到完整的矩阵：

需要说明的是：该矩阵对应的是 npm 包的自动下载分支；package.json的cpu字段仅声明了x64与arm64，因此在 npm 层面，如 x86 的 32 位系统等其余架构将无法通过本包安装。除 npm 途径外，仍可通过 Releases 手动下载（见下文"手动安装"）。

安装后的自检：scripts/test.js

安装完成后可用 npm-package/scripts/test.js 做冒烟验证（npm test）。该脚本用最朴素的方式做了三项检查：

1. 二进制存在：bin/gt（Windows 为bin/gt.exe）必须存在；
2. 可执行且能输出版本：执行<binary> version，输出必须包含gt version字样，以此证明二进制可运行且版本信息正常；
3. 包装脚本存在：bin/gt.js必须存在。

最终打印N passed, N failed，任一失败即以非零码退出。这套自检与postinstall.js末尾的版本验证形成双重保障，可用于确认安装完整性。

核心命令用法与底层实现

原文档给出的四个入门命令如下：

# 检查版本 gt version # 初始化一个新的 town gt init # 查看状态 gt status # 列出 rigs gt rig list

下面结合源码逐一展开。

gt version：版本与构建信息

命令实现在 internal/cmd/version.go。默认输出gt version <Version> (<Build>: <branch>@<commit>)格式，其中：

• Version/Build/Commit/Branch是编译期通过 ldflags 注入的变量（未注入时为dev）；
• 未注入时通过debug.ReadBuildInfo()读取 Go 模块构建信息中的vcs.revision与vcs.branch；
• 仍取不到分支时，退化为运行时执行git symbolic-ref --short HEAD。

两个可选 flag 进一步丰富了输出：

gt version # 默认格式 gt version --short # 仅输出 "1.2.1-dev" 形式的版本号 gt version -v # 追加 Timestamp 与 Go 版本（verbose）

其中--short便于脚本解析版本号，--verbose便于排查构建时间戳与运行时环境。

gt init：把当前目录初始化为一个 rig

命令实现在 internal/cmd/init.go，其职责与约束如下：

• 前置条件：当前目录必须是 git 仓库（内部调用git.NewGit(cwd).CurrentBranch()，否则报错"not a git repository (run 'git init' first)"）；
• 幂等保护：若已存在polecats/目录且未加--force，报错"rig already initialized (use --force to reinitialize)"；-f/--force用于重新初始化既有结构；
• 创建标准代理目录：遍历rig.AgentDirs创建polecats/、witness/、refinery/、mayor/等目录，并为每个目录写入.gitkeep；
• 更新 .git/info/exclude：把代理目录以/polecats/这种仓库根锚定形式追加到.git/info/exclude（源码注释特别说明：锚定根路径是为了避免refinery/这类模式在任意深度匹配、误伤internal/refinery/之类的源码目录）；
• 注册 beads 自定义类型：若检测到bd命令与.beads目录，则以最佳努力方式写入types.custom、types.infra配置（beads 未安装或数据库未初始化时静默跳过）；
• 自动配置 Dolt 生命周期：通过daemon.EnsureLifecycleConfigFile在mayor/daemon.json中补全 reaper、compactor、doctor、backup 等维护 patrol 的默认配置（只补缺失项，不覆盖已有用户配置）。

初始化完成后，命令会提示两个"下一步"：gt rig add <name> <git-url>把该 rig 加入某个 town，以及gt polecat identity add <rig> <name>创建 polecat 身份。

gt status：查看 town 整体状态

命令实现在 internal/cmd/status.go，它会聚合展示整个 town 的运行状态，包括：

• 守护进程（daemon）：daemon.IsRunning(townRoot)检测，输出 PID；
• Dolt 服务：doltserver.IsRunning检测，未运行时给出提示；
• tmux 服务：通过会话列表判断是否运行；
• ACP 服务：存在时输出 PID；
• 各 rig 的智能体运行时：witness、refinery、crew、polecats 等角色的运行状态，以及从实际进程树中探测出的 runtime/model 信息（detectRuntimeFromSession/parseRuntimeInfo解析进程 cmdline 得出，例如claude/opus之类）；同时支持--json输出（TownStatus结构体含json标签），便于脚本消费。

也就是说，gt status是把 town 下所有服务与智能体"一屏看全"的入口，配合gt rig list可从 town 级下沉到 rig 级。

gt rig list：列出 town 中的 rigs

rig是 internal/cmd/rig.go 中定义的命令族（Use: "rig"，GroupID 为 GroupWorkspace），rig list是其子命令（Use: "list"），用于列出 town 中注册的所有 rig，每个 rig 展示：

• 名称与运行状态（OPERATIONAL / PARKED / DOCKED）；
• Witness 状态（running/stopped）；
• Refinery 状态（running/stopped）；
• polecats 数量与 crew 成员数量。

支持gt rig list --json输出 JSON 便于脚本化。同族的常用命令还有gt rig add <name> <git-url>（克隆仓库并创建 rig 容器，含refinery/rig/、mayor/rig/、crew/、witness/、polecats/、.beads/等结构，支持--adopt接管既有目录与 fork 模式）与gt rig remove <name>（仅注销注册项，不删除磁盘文件）。更完整的 rig 管理流程可参考 docs/guides/fork-rig-setup.md。

手动安装与故障排查

原文档说明：当 npm 安装失败（网络受限、Release 下载被拦截、或平台不在自动下载矩阵内）时，可从项目的 GitHub Releases 页面直接下载与平台/架构匹配的归档，解压后把二进制放入PATH即可。归档命名规则与postinstall.js完全一致：gastown_<版本>_<平台>_<架构>.tar.gz（Windows 为.zip），例如gastown_1.2.1_darwin_arm64.tar.gz。

常见的安装失败场景与对应处理：

License

@gastown/gt以 MIT 协议开源（见 npm-package/LICENSE），package.json的license字段亦标注为MIT，可自由使用与二次分发，商用场景下注意保留版权声明即可。

小结

@gastown/gt用最轻量的 npm 包装解决了跨平台分发 Go 二进制的经典问题：npm 负责命令入口与依赖约束，postinstall.js负责平台感知的下载/解压/授权，test.js负责安装自检。安装完成后，gt version、gt init、gt status、gt rig list四个命令即可串起"安装 → 初始化 rig → 加入 town → 查看全局状态"的完整入门链路，为后续使用 polecat、witness、refinery 等 Gas Town 多智能体编排能力打下基础。

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown