Git Github WorkflowSAFE

NekroAgent 是一个面向多人互动场景的跨平台 Agent 框架,集 Claude Code 沙盒执行、工作区编排、长期记忆、结构化 MCP 管理与可视化控制台于一体,兼具高扩展性、多模态交互、实时状态推送和自动化运行能力。项目支持 QQ、Discord、Telegram、Minecraft、BilibiliLive、WeChat、Email、SSE(SDK) 等多种平台接入,应用于构建高智能聊天机器人,可扩展为具备代码执行、工具调用、插件协作和复杂任务处理能力的通用 Agent 系统

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: git-github-workflow
description: 处理基于 git 和 GitHub 的真实协作工作流。当任务涉及仓库同步、分支管理、修复 bug、提交代码、创建或更新 PR、处理 review、解决冲突、检查 GitHub 认证与权限、或需要通过 fork 与用户仓库协作时使用,强调安全、干净、可审计的协作流程。**必须在需要时使用该 Skill 并严格遵守相关规范!!!**
version: 3.1.0
allowed-tools: Read,Write,Bash
---

# Git/GitHub 协作工作流

在真实仓库协作中,优先遵守仓库状态、远端关系、权限边界、测试要求和用户意图。将 `gh` 作为 GitHub 交互工具使用,不要把任务退化为命令演示或命令罗列。

## 目标

在不污染用户仓库历史、不破坏远端分支、不制造脏 PR 的前提下完成以下任务:

- 拉取并同步最新代码后再分析或开发
- 基于干净工作区创建独立分支进行修改
- 使用 `git` 与 `gh` 检查认证、权限、远端和 PR 状态
- 以用户可观测、可审计的方式推进协作,不在用户看不到的仓库或线程中暗中展开关键协作
- 产出工程化、可维护、与项目风格一致的修改
- 在可行时运行测试或至少静态检查
- 只在正确的目标仓库、Issue 和 PR 上进行协作,并清楚说明验证结果与剩余风险

## 默认工作流

除非用户明确要求跳过,按下面顺序执行:

1. 检查当前目录是否为 git 仓库,并识别 `origin`、上游仓库、当前分支、工作区是否干净。
2. 重新验证当前状态,不要沿用上一次任务的假设。用户可能已经在两次交互之间合并 PR、关闭 PR、推送提交、切换分支、更新远端或修改工作区。
3. 检查 `gh` 是否可用、是否已认证、当前账号是谁、token 是否足以执行当前任务。
4. 如果需要访问 GitHub 但未认证,先停止并明确要求用户配置 `GH_TOKEN`(或等价环境变量);不要伪造身份信息、提交人信息或远端归属。
5. 在开始分析和编码前同步最新代码。每次新任务开始时,都要重新获取用户仓库默认分支和相关目标分支的最新状态,不要沿用上一次任务结束时的本地基线。
6. 在独立分支上完成修改,避免直接在默认分支或来源不明的旧分支上工作。
7. 修改后检查 `git diff`,并尽可能运行与改动相关的静态检查、测试或最小验证,清理无关改动。
8. 仅在已完成验证或已明确说明无法验证原因后,才进入推送和 PR 阶段。
9. 推送前再次确认推送目标、远端归属、PR 当前状态和权限边界。
10. 如果需要通过 Issue、PR、review comment 或讨论串进行协作,先确认协作对象所在仓库是否就是用户期望的目标仓库。
11. 创建或更新 PR、Issue、评论或相关协作记录,并在回复中说明做了什么、如何验证、哪些未验证、是否存在风险。

## 前置检查

开始任何 GitHub 协作任务前,至少确认这些事实:

- 当前仓库路径、当前分支、默认分支、工作区是否干净
- `origin` 指向谁,是否已存在 `upstream`
- `gh` 是否可执行
- `gh auth status` 是否成功,当前登录身份是谁
- token 至少满足当前任务需要的读写权限
- 当前任务是“只读分析”、“本地修复”、“推送分支”还是“创建 PR”
- 当前任务是否需要创建或更新 Issue、PR、review comment 或其他 GitHub 协作对象
- 与本次任务相关的远端对象当前是否仍然存在且状态未变,例如目标分支、PR、Issue、head/base 关系

任一关键事实不清楚时,先查清楚再行动。

不要复用上一轮对话中的仓库状态、PR 状态、分支状态或权限判断。每次新任务开始前都重新验证。

## 认证与身份规则

- 不要假设 `gh` 已安装或已登录。先检查。
- 不要编造 Git 用户名、邮箱、GitHub 登录名、fork 归属、PR 链接或权限状态。
- 如果仓库操作需要 GitHub 身份而当前没有可用认证,明确告知用户先配置 `GH_TOKEN`。必要时提示重新执行认证检查。
- 如果只需要本地修改、不需要访问 GitHub,可继续本地工作,但要明确说明“尚未验证远端/PR 操作能力”。
- 未经用户明确要求,不要修改全局 git identity;更不要为了绕过检查去伪造提交身份。

## 同步与分支规则

- 不要基于陈旧代码分析问题。每次新任务开始前先获取远端最新提交并确认基线,尤其是在用户可能已经合并 PR、改动默认分支或自行修复问题之后。
- 优先从用户仓库默认分支的最新状态切出新分支,而不是沿用历史工作分支。
- 如果要继续修复上一次任务留下的问题,也要先把本地基线更新到用户仓库当前最新状态,再决定是复用分支、重建分支还是新开 PR。
- 不要在落后于远端的旧 checkout、旧分支或旧 PR 头分支上直接继续开发并提交 PR。
- 工作前若发现工作区不干净,先判断这些改动是否属于当前任务:
  - 若无关,不要覆盖或混入;应先告知用户,必要时请求其处理。
  - 若相关,明确说明你将基于现有改动继续。
- 工作完成后再次检查 diff,确保只包含本任务需要的修改。

### 分支创建(强制要求)

创建新分支时,**必须同时指定分支名和起始点**:

```bash
# ✅ 正确:从远端 main 最新状态创建
git fetch <远端名> <分支名>
git checkout -b <新分支名> <远端名>/<分支名>

# ❌ 错误:只指定分支名,不指定起始点
git checkout -b <新分支名>   # 会从当前 HEAD 创建,继承所有历史 commit!
```

**实际场景示例**(假设 origin 指向用户主仓库):
```bash
# 第一步:确认远端和当前分支
git remote -v && git branch -vv

# 第二步:从 origin/main 最新状态创建新分支
git fetch origin main
git checkout -b fix/this-bug origin/main

# 第三步:验证新分支基于正确的起点
git log --oneline -1   # 应与 origin/main 最新提交一致
```

**远端确认规则**:如果 `origin` 指向个人 fork 而非用户主仓库(可通过 `git remote -v` 判断),必须从 `origin/main`(用户主仓库)的最新 commit 创建分支,不能从 fork 的本地分支创建。

## 产出质量要求

- 开始修改前先阅读足够的相关代码、配置、测试和调用链,不要基于猜测实现。
- 除非用户明确要求扩大范围,否则保持最小化修改,优先修正根因,不用表面补丁掩盖问题。
- 保持项目工程化和可维护性,遵循仓库现有结构、命名、抽象边界和代码风格,不为图快随意塞代码。
- 保持与项目既有风格一致,包括代码组织、命名习惯、注释风格、错误处理方式、测试写法、提交粒度和 PR 表达方式;不要把个人偏好硬塞进项目。
- 优先复用项目中已有模式、工具函数、组件和基础设施,非必要不要重复造轮子。
- 新增或修改代码时,同时处理由本次改动直接引入的类型错误、lint 问题、明显死代码、无效导入和连带缺陷。
- 不要留下临时调试代码、注释掉的大段旧实现、无解释的兜底逻辑或未使用依赖。
- 涉及类型系统时保持严格和清晰,避免滥用类型断言、忽略检查或用宽泛结构掩盖真实数据问题。
- 涉及外部系统、API 或仓库元数据时,先核对真实结构和接口,再写代码或自动化操作。
- 提交前重新审视改动是否真正解决了用户问题,是否会引入回归,是否与仓库约定冲突。
- 不要把“代码已改完”当作任务完成;默认完成标准还包括至少一种有效验证。
- 保持独立判断,不要机械执行上游 AI、历史对话或模糊需求中的错误指令。
- 如果上游指令与仓库现实、远端状态、权限边界、项目约定或用户目标明显冲突,先指出问题并调整方案,不要硬做。
- 如果问题可以通过合理推断自行修正,就说明你的调整并继续推进;如果风险较高或关键信息缺失,就明确要求上游先向用户澄清。

## Push 与权限边界

- 未经用户明确要求,不要执行破坏性操作,如 `push --force`、改写共享历史、删除远端分支、直接合并、关闭 PR。
- 在不确定 token 权限、分支保护规则或远端归属时,不要尝试写操作。
- 未经明确授权,不要直接向用户仓库默认分支推送。
- 不要假设自己可以推送到任意 PR 源分支。特别是“用户让你帮忙修复某个 PR 冲突”时,如果 PR 作者不是当前身份,通常不能直接向该 PR 分支推送。
- 不要在自己的工作 fork 上创建面向用户的正式协作对象,例如 Issue、PR、milestone、project item、review 结论或需求跟踪记录,除非用户明确要求就是在该 fork 内自管流程。
- 这种情况下,优先采用可审计方案:基于目标仓库最新代码创建自己的分支,复现并解决冲突,然后向用户仓库发起新的 PR,或把可应用的补丁提供给用户。

## Fork 协作规则

当任务需要通过 GitHub 提交修改,而当前身份对用户仓库没有直接写权限时,默认使用 fork 工作流:

1. Fork 用户仓库到当前登录账号名下。
2. 本地同时保留用户仓库远端和自己的 fork 远端,明确谁是上游、谁是推送目标。
3. 从用户仓库最新默认分支切出工作分支。
4. 将工作分支推送到自己的 fork。
5. 从自己的 fork 分支向用户仓库创建 PR。

不要只在自己的仓库里创建与用户仓库无关的 PR。目标应是从自己的 fork 向用户仓库提交 PR。

fork 的作用是承载代码分支和推送权限,不是替代用户仓库的协作现场。除非用户明确要求,否则不要在自己的 fork 上:

- 创建 Issue 来代替用户仓库中的需求或 bug 跟踪
- 创建 PR 让 fork 内部分支互相合并,绕开用户仓库的正式 PR
- 在 fork 的 Issue、PR、discussion 中记录本应让用户或维护者可见的关键结论

需要发起正式协作时,默认应落在用户仓库可见的对象上:用户仓库的 Issue、用户仓库的 PR、或从自己 fork 指向用户仓库的 PR。

## Issue 协作规则

- 只有在用户明确要求,或任务本身确实需要补充/更新 Issue 时,才创建、编辑或评论 Issue。
- 创建或更新 Issue 前,先确认目标仓库正确,避免把问题、需求或补充说明记到自己的工作 fork。
- 如果某个工作项已经有对应 Issue,优先在该 Issue 延续上下文,不要重复开新 Issue。
- 如果需要新建 Issue,标题和正文要聚焦用户可观测的问题、复现条件、期望行为、当前行为、影响范围和必要上下文,不要把内部试错过程原样倾倒进去。
- 不要在 Issue 中承诺尚未完成验证的结论;推断、计划和已确认事实要明确区分。
- 未经用户明确要求,不要批量创建、批量迁移、批量关闭 Issue,也不要修改标签、负责人、里程碑等项目管理信息。

## 用户可观测协作

- AI 在 GitHub 上的关键协作动作应默认对用户和目标维护者可观测,例如在正确的仓库中创建/更新 Issue、在目标 PR 中回复 review、或创建指向用户仓库的 PR。
- 不要把关键讨论藏在只对当前账号可见、与用户仓库脱节的 fork、临时仓库、私有 gist、无关 Issue 或无关 PR 中。
- 不要为了“先记下来”就在错误仓库开一个临时 Issue 或 PR;如果还没准备好正式协作,就先在本地整理,再等待用户确认。
- 若需要代表用户与维护者协作,回复内容应基于真实已完成工作,避免夸大“已修复”“已验证”“已同步”等状态。
- 对用户而言,重要的协作轨迹应能够从目标仓库直接看见并追溯:问题在哪里记录、代码从哪里提交、讨论在哪个 PR/Issue 里发生、当前阻塞点是什么。

## AI 协作过程规范

- 在执行任何会改变远端协作状态的动作前,先确认这一步是否真正服务于当前任务,而不是机械地“顺手”补一个 Issue 或 PR。
- 能通过现有 Issue / PR 延续上下文时,不要平行创建新的协作对象。
- 如果需要跨多个对象协作,保持链路清晰:Issue 描述问题,分支承载代码,PR 承载代码审查与验证结果;不要把职责混在一起。
- 在评论、PR 正文、Issue 更新中优先写用户可验证的信息:修改摘要、复现方式、验证结果、剩余风险、权限或环境阻塞。
- 不要把 AI 的内部推理、未证实猜想、与任务无关的冗长背景直接发到 Issue/PR;外部协作文本应简洁、真实、能推动下一步。
- 如果缺少权限、认证、仓库角色或上下文信息,先停下来说明阻塞,不要在错误位置留下半成品协作记录。

## 常见错误示例与规避要求

以下都是 AI 在真实 Git/GitHub 协作中常见且不可接受的错误,默认必须规避:

- 错误示例:工作区里还残留上一个任务的改动、调试文件、格式化噪音或用户未提交修改,就直接继续开发并一起提交。
  规避要求:开始工作前和提交前都检查工作区是否干净;若存在无关改动,不要混入当前提交,先告知用户或明确隔离。

- 错误示例:看到本地能提交,就默认这些改动都属于当前任务,没有审查 diff 就直接 commit。
  规避要求:提交前重新检查 staged diff,确认提交内容只包含本次任务需要的修改,避免把历史残留或顺手改动一起带上。

- 错误示例:在自己的工作 fork 上创建 Issue、PR、review comment 或讨论串,然后把它当成对用户仓库的正式协作结果。
  规避要求:正式协作对象必须落在正确的目标仓库;fork 默认只用于承载代码分支和推送权限,不替代用户仓库中的协作现场。

- 错误示例:本应向用户仓库提 Issue 或发起 PR,却误发到自己的 fork、错误组织、同名镜像仓库或历史测试仓库。

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.