GitCode Toolkit

GitCode 协作类 skill 的共享基础库。遵循渐进式披露原则：本文档为速查索引，详细内容按需在 references/ 中展开，确定性操作由 scripts/ 提供。

定位：内部参考，不直接触发。其他 GitCode skill（gitcode-pr-handler、gitcode-issue-gen、gitcode-issue-handler 等）按需引用。

---

常见问题速答

Q: 如何拉取 PR 代码到本地？

方式一（推荐）：通过 merge-requests 引用

git fetch origin +refs/merge-requests/{pr_number}/head:pr_{pr_number}
git checkout pr_{pr_number}

方式二：从 fork remote 获取（仅当方式一失败时）

git remote add fork https://gitcode.com/{fork_user}/{fork_repo}.git
git fetch fork {head_ref}:pr_{pr_number}
git checkout pr_{pr_number}

Q: 如何查看 PR 相比 master 的变更？

方式一：merge-base 模式（推荐）

# 先获取 base 分支
git fetch origin {base_ref}:base_branch
# 计算 merge base
MERGE_BASE=$(git merge-base base_branch pr_{pr_number})
# 查看变更统计
git diff --stat $MERGE_BASE pr_{pr_number}
# 查看具体文件 diff
git diff $MERGE_BASE pr_{pr_number} -- {file_path}

方式二：triple-dot 模式（本地已有 PR 分支）

git diff --stat origin/${BASE_BRANCH}...HEAD
git diff origin/${BASE_BRANCH}...HEAD -- path/to/file.py

Q: 如何获取 GitCode API Token？

Token 获取优先级：用户直接在消息中提供 → 环境变量 GITCODE_TOKEN → 询问用户。

传递方式（二选一）：

方式	示例
Header 方式	curl -H "PRIVATE-TOKEN: {token}" https://api.gitcode.com/api/v5/...
参数方式	curl https://api.gitcode.com/api/v5/...?access_token={token}

Token 需至少 reporter 以上权限才能创建 Issue。详见 token-config.md。

---

速查索引

必选流程（MUST）

步骤	内容	详细文档	脚本支持
Step 0	环境预检（token / git / curl / /tmp / git-author）	env-check.md	bash scripts/preflight.sh
Token	获取优先级：用户消息 → GITCODE_TOKEN → 询问	token-config.md	—
URL	解析 PR/Issue 链接：/pull/{n}, /issues/{n}, /merge_requests/{n}	url-parsing.md	python scripts/parse_gitcode_url.py "<url>"
API	PR/Issue/仓库 API + 错误码处理	gitcode-api.md	—

建议流程（SHOULD）

步骤	内容	详细文档	脚本支持
克隆+检出	PR 分支检出、base 分支确定、merge-base	clone-and-checkout.md	—
Diff+变更	变更统计（merge-base / triple-dot 模式）	diff-and-changes.md	—
Log+文件	commit 元信息提取、文件读取	log-and-show.md	—
Remote+分支	remote 管理、分支查询、推送	remote-and-branch.md	—
PR 上下文	一键获取 clone + diff + log	—	python scripts/fetch_pr_context.py --repo <owner/repo> --pr <N>

可选参考（MAY）

内容	详细文档
变更列表展示格式	change-table-display.md
日志命名与记录规范	logging-conventions.md
Git 操作易错点对照	pitfalls.md

---

工作流

PR 创建工作流

从 fork 仓库向上游创建 PR 的完整 8 步流程（Step 1~8），含 git 提交身份校验（Step 5：5.1 硬性阻断 + 5.2 建议性校验）。详见：

references/pr-creation-workflow.md

Issue 创建工作流

创建 GitCode Issue 的标准 7 步流程。Step 3/4 为业务层（由调用方 skill 实现），infra 提供 Step 1/2/5/6/7 的通用能力。详见：

references/issue-creation-workflow.md

---

脚本工具

脚本	功能	用法
scripts/parse_gitcode_url.py	确定性 URL 解析，输出 JSON	python scripts/parse_gitcode_url.py "<url>"
scripts/preflight.sh	环境预检，输出结构化报告	bash scripts/preflight.sh [--skip-git-author]
scripts/fetch_pr_context.py	一键获取 PR 上下文（clone+diff+log）	python scripts/fetch_pr_context.py --repo <owner/repo> --pr <N>
scripts/trigger_pr_pipeline.sh	触发 PR CI 流水线（提交 "compile" 评论）	bash scripts/trigger_pr_pipeline.sh --repo <owner/repo> --pr <N>

---

适用平台

本工具集仅适用于 GitCode 平台（gitcode.com）。不支持 GitHub / GitLab 等平台。

---

参考文档索引

文档	说明	约束级别
env-check.md	Step 0 环境预检（token / git / 临时目录）	MUST
gitcode-api.md	PR/Issue/仓库 API + 错误处理	MUST
url-parsing.md	URL 格式识别与解析	MUST
token-config.md	Token 获取优先级	MUST
pr-creation-workflow.md	PR 创建 8 步完整流程（含 git 身份校验）	SHOULD
issue-creation-workflow.md	Issue 创建 7 步流程（含预设模板）	SHOULD
clone-and-checkout.md	克隆、浅克隆、PR 分支检出、merge-base	SHOULD
diff-and-changes.md	diff 变更统计（merge-base / triple-dot 模式）	SHOULD
log-and-show.md	git log 元信息提取、git show 文件读取	SHOULD
remote-and-branch.md	remote 管理、分支查询、push	SHOULD
logging-conventions.md	日志命名与记录规范	MAY
change-table-display.md	变更文件列表展示格式	MAY
pitfalls.md	Git 操作易错点对照表	MAY