Aaflyingtofeat(docs): add Linux install guide with OS auto-detection

AI Dev Workflow — Linux 安装指导

⚠️ 本文件是 Linux (Bash) 版本。Windows 用户请使用 README.md。

AI 在开始执行前，根据运行环境的操作系统自动选择：

Linux → 继续本文件

Windows → 切换到 README.md

本文件是 README.md 的 Linux 补充版本，覆盖 Step 0 ~ Step 6 的 Bash 等价命令。

Step 0：环境前置检查

检查项	命令	期望
Python	`python3 --version`	3.x 任意版本
Git	`git --version`	任意 2.x
当前目录是项目空间根目录	`pwd`	路径以项目名结尾
`ai-dev-workflow/` 存在	`test -d ai-dev-workflow && echo OK`	OK
`specs/` 存在	`test -d specs && echo OK`	OK

任意一项失败，提示用户环境版本不匹配，并且自动安装/拉取，然后重试。

Step 1：部署项目级 `AGENTS.md`

cp -f ai-dev-workflow/AGENTS.md ./AGENTS.md

验证：

test -f AGENTS.md && wc -c AGENTS.md | awk '{print $1 > 1000 ? "OK" : "FAIL"}'

如果工作区根目录已存在 AGENTS.md 且内容不同 → 先与用户确认是否覆盖（备份原文件到 AGENTS.md.bak）。

Step 2：部署 `gitcode-*` skills 到项目级 `.agents/skills/`

skillsDir="./.agents/skills"
mkdir -p "$skillsDir"
cp -r ai-dev-workflow/gitcode-*/ "$skillsDir"

验证：

ls -d "$skillsDir"/gitcode-* | xargs -n1 basename

期望至少列出：

gitcode-dev-quality
gitcode-dev-workflow
gitcode-issue-create
gitcode-issue-review
gitcode-issue-triage
gitcode-pipeline-analyzer
gitcode-pr-create
gitcode-pr-review
gitcode-release-helper
gitcode-repo-onboarding
gitcode-security-check

Step 3：部署 superpowers skills 到项目级 `.agents/skills/`

superpowers 上游源：github.com/obra/superpowers，GitCode 官方镜像：GitHub_Trending/su/superpowers。使用 git clone --depth 1 即可获取，无需访问 GitHub。

部署时必须展开拷贝——把 superpowers/skills/ 下的 skill 子目录平铺到 .agents/skills/ 根，跟 gitcode-* 同级。不允许保留 superpowers/ 这层（AI 开发环境只识别 .agents/skills/<skill-name>/ 一级目录）。

tempDir=$(mktemp -d)
git clone --depth 1 https://gitcode.com/GitHub_Trending/su/superpowers.git "$tempDir/superpowers"

skillsDir="./.agents/skills"
mkdir -p "$skillsDir"
cp -r "$tempDir/superpowers/skills/"* "$skillsDir"

rm -rf "$tempDir"

更新：如需更新 superpowers 到最新版本，重复上述命令即可。--depth 1 始终拉取最新快照，不会累积历史。

验证：

ls "$skillsDir" | grep -E 'brainstorming|writing-plans|test-driven-development|subagent-driven-development|requesting-code-review|finishing-a-development-branch|using-superpowers'

至少应看到：brainstorming、writing-plans、test-driven-development、subagent-driven-development、requesting-code-review、finishing-a-development-branch、using-superpowers。缺失任一项 → 停止并向用户报告，不要继续。

Step 4：安装 GitCode CLI

目标：让 gitcode 命令在终端可用。

方式 A：Python wheel（推荐，跨发行版通用）

latestTag=$(git ls-remote --refs --tags https://gitcode.com/gitcode-cli/cli.git 2>/dev/null |
    grep -oP 'v\K\d+\.\d+\.\d+' |
    sort -V -r | head -1)
wheelUrl="https://gitcode.com/gitcode-cli/cli/releases/download/v${latestTag}/gitcode_cli-${latestTag}-py3-none-any.whl"
echo "Installing GitCode CLI v${latestTag} ..."
python3 -m pip install --user "$wheelUrl"

如果安装后 gitcode 仍不可用，把用户级 Python bin 目录加入 PATH：

pythonBin=$(python3 -c "import sysconfig; print(sysconfig.get_path('scripts', scheme='posix_user'))")
echo "export PATH=\"\$PATH:$pythonBin\"" >> ~/.bashrc
source ~/.bashrc

方式 B：系统包（Debian/Ubuntu）

latestTag=$(git ls-remote --refs --tags https://gitcode.com/gitcode-cli/cli.git 2>/dev/null |
    grep -oP 'v\K\d+\.\d+\.\d+' |
    sort -V -r | head -1)
debUrl="https://gitcode.com/gitcode-cli/cli/releases/download/v${latestTag}/gc_${latestTag}_amd64.deb"
echo "Installing GitCode CLI v${latestTag} ..."
wget -q "$debUrl" -O /tmp/gc.deb
sudo dpkg -i /tmp/gc.deb
rm -f /tmp/gc.deb

ARM64 设备将 amd64 替换为 arm64。

方式 C：系统包（RHEL/CentOS/Fedora）

latestTag=$(git ls-remote --refs --tags https://gitcode.com/gitcode-cli/cli.git 2>/dev/null |
    grep -oP 'v\K\d+\.\d+\.\d+' |
    sort -V -r | head -1)
rpmUrl="https://gitcode.com/gitcode-cli/cli/releases/download/v${latestTag}/gc-${latestTag}-1.x86_64.rpm"
echo "Installing GitCode CLI v${latestTag} ..."
wget -q "$rpmUrl" -O /tmp/gc.rpm
sudo rpm -i /tmp/gc.rpm
rm -f /tmp/gc.rpm

ARM64 设备将 x86_64 替换为 aarch64。

方式 D：Linux 二进制（无需包管理器）

latestTag=$(git ls-remote --refs --tags https://gitcode.com/gitcode-cli/cli.git 2>/dev/null |
    grep -oP 'v\K\d+\.\d+\.\d+' |
    sort -V -r | head -1)
binUrl="https://gitcode.com/gitcode-cli/cli/releases/download/v${latestTag}/gc_linux_amd64"
echo "Installing GitCode CLI v${latestTag} ..."
wget -q "$binUrl" -O /tmp/gc
chmod +x /tmp/gc
sudo mv /tmp/gc /usr/local/bin/gitcode

ARM64 设备将 amd64 替换为 arm64。二进制文件名为 gc_linux_amd64，安装后重命名为 gitcode 以避免与系统命令冲突。

验证：

gitcode version

期望输出类似 gitcode version x.y.z（版本号应与刚安装的一致）。

Step 5：配置 GitCode 访问令牌（永久环境变量 `GC_TOKEN`）

AI 必须先向用户索要 token，不要试图猜测、读取磁盘上其他位置的 token、或跳过此步。

token 获取路径（请用户在浏览器中操作）：

登录 GitCode
点击右上角头像 → 个人设置
左侧 安全设置 → 访问令牌 → 新建访问令牌
勾选权限：至少 Issue / PR / Repository 的读写权限
创建后复制 token（只展示一次），把 token 提供给 AI

拿到 token 后写入环境变量：

echo 'export GC_TOKEN="<token>"' >> ~/.bashrc
source ~/.bashrc

使用 zsh 的用户将 ~/.bashrc 替换为 ~/.zshrc。

验证：

gitcode auth status

期望输出类似 Logged in as <username>。如果报未登录 → 停止，请用户确认 token 是否正确。

Step 6：最终验证

echo "=== AI Dev Workflow 初始化验证 ==="
echo "1. AGENTS.md: $(test -f AGENTS.md && echo OK || echo FAIL)"
echo "2. Skills 目录: $(test -d .agents/skills && echo OK || echo FAIL)"
echo "3. gitcode-* skills: $(ls -d .agents/skills/gitcode-* 2>/dev/null | wc -l) 个"
echo "4. superpowers skills: $(ls .agents/skills 2>/dev/null | grep -cE 'brainstorming|writing-plans|test-driven-development') 个"
echo "5. GitCode CLI: $(gitcode version)"
echo "6. GitCode 认证: $(gitcode auth status)"
echo "7. specs 仓: $(test -d specs && echo OK || echo FAIL)"
echo "=== 验证完成 ==="

全部通过后，输出：

✅ AI Dev Workflow 初始化完成！
- 项目级 AGENTS.md 已部署
- 25+ 个 Skills 已部署
- GitCode CLI 已安装并认证
- specs 文档仓已就绪

下一步：
1. 将业务代码仓 clone 到项目空间根目录
2. 在业务仓创建仓级 AGENTS.md（填充质量门禁等定制项）
3. 开始开发时，AI 会自动读取 AGENTS.md 并按工作流执行