# git-init 使用文档

在 Cursor 里用本 Skill 完成完整 Git 流程。默认远程为 **Gitea**（自建或公网实例）：初始化、每次签名提交、每次推送，以及克隆、拉取、分支、合并、标签、暂存。令牌只存在本机并加密，不会出现在对话或仓库里。

配套阅读：

- [架构.md](架构.md) — 组件、数据流、流程图
- [Gitea 说明](../.cursor/skills/git-init/gitea.md) — URL、Token、SSH、GPG 菜单

## 你需要准备什么

| 时机 | 你提供什么 | 不要提供什么 |
| --- | --- | --- |
| 本机一次 | 作者档案 + Gitea 访问令牌（本机终端） | 不要在 Cursor 聊天里粘贴 Token |
| 初始化 | Gitea 仓库 URL；可选 SSH/GPG 偏好 | 不要把私钥或 Token 发给 Agent |
| 日常提交 / 推送 | 说「提交」「推送」或「提交并推送」 | 不必再给 Token |
| 克隆 / 拉取 | Gitea URL 或「拉取远程」 | 不必再给 Token |

默认作者（可在档案里改）：`旅行呀~` `<travelxiao@qq.com>`。

提交信息必须是中文：`类型: 描述`（`初始化` / `新增` / `修复` / `优化` / `文档`）。

**每次提交还必须带 `Co-authored-by`**（与档案作者一致，可另加合作者）：

```
类型: 描述

Co-authored-by: 旅行呀~ <travelxiao@qq.com>
```

由 `emit-commit-message.ps1` 自动拼上。额外合作者在 `store-profile.ps1` 里按 `Name <email>` 追加，写入档案的 `coAuthors`。

## Gitea 地址示例

```
https://git.example.com/owner/repo.git
https://git.example.com:3000/owner/repo.git
git@git.example.com:owner/repo.git
ssh://git@git.example.com:2222/owner/repo.git
```

HTTPS：用户名 = Gitea 登录名，密码 = **访问令牌**（设置 → 应用 → 生成新令牌）。  
SSH / GPG：设置 → SSH / GPG 密钥。

## 安装

在本仓库根目录：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

效果：

- 项目级：`.cursor/skills/git-init`（本仓库直接可用）
- 个人级：`%USERPROFILE%\.cursor\skills\git-init`（所有项目可用）

不要安装到 `~\.cursor\skills-cursor\`。改了 Skill 源码后重新跑一次 `install.ps1`。

## 本机一次配置

在**自己的 PowerShell**里运行（不要在对话里贴 Token）：

```powershell
$scripts = "$env:USERPROFILE\.cursor\skills\git-init\scripts"

powershell -NoProfile -ExecutionPolicy Bypass -File "$scripts\store-profile.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$scripts\store-token.ps1"
```

- `store-profile`：姓名、邮箱、**Gitea 用户名**、SSH 私钥路径；可选追加额外 `Co-authored-by`（`Name <email>`）
- `store-token`：隐藏输入 **Gitea 访问令牌**，DPAPI 加密到 `%USERPROFILE%\.git-skills\token.dpapi`

检查（可在 Cursor 里跑，不会打印 Token）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$scripts\profile-status.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$scripts\token-status.ps1"
```

`token-status` 只会出现 `present` / `missing` / `invalid`。

## 在 Cursor 里怎么说

把下面整句发给 Agent（把 URL 换成你的 Gitea 仓库）。

### 初始化

```text
用 git-init 初始化这个仓库，远程是 git@git.example.com:owner/repo.git
```

或：

```text
用 git-init 初始化，远程是 https://git.example.com:3000/owner/repo.git
```

会：`git init`、写本地作者、加 origin、注入凭据、SSH/GPG、补 `.gitignore`、中文签名提交、推送 `main`。

### 日常提交

```text
按 git-init 提交这些改动
```

### 日常推送

```text
推送到 Gitea
```

### 提交并推送

```text
提交并推送
```

### 克隆

```text
用 git-init 克隆 https://git.example.com/owner/repo.git
```

### 拉取

```text
拉取远程更新
```

默认 `--ff-only`。历史分叉时会停下问你，不会强推。

### 分支 / 合并 / 查看

```text
基于当前分支新建 feature/login 并切过去
把 feature/login 合进 main
现在 git 状态怎么样
```

更多例句见 [examples.md](../.cursor/skills/git-init/examples.md)。

## 能力一览

| 路径 | 做什么 | 认证 |
| --- | --- | --- |
| Init | 建库、远程、SSH、GPG、首次提交并推送 | Gitea Token + SSH |
| Commit | 每次中文签名提交 + `Co-authored-by` | 本地 GPG |
| Push | 每次推送当前分支 | Token 或 SSH |
| Clone | 克隆 Gitea 仓库 | `prepare-auth` |
| Sync | fetch / pull --ff-only | `prepare-push` |
| Branch / Merge / Tag / Stash / Inspect | 本地协作与只读查看 | 按需联网 |

## 安全约定

- Token 只在 `%USERPROFILE%\.git-skills\token.dpapi`，绑定当前 Windows 用户
- Agent 不得读取该文件，不得让你在聊天里贴 Token
- 不修改已有 `origin`，不改全局 `user.name` / `user.email`
- 不 `--force`、不 `reset --hard`、不跳过 hooks，除非你写明要求

## Gitea 密钥：添加 → 验证（必做）

官方：[GPG/SSH Commit Signatures](https://docs.gitea.com/administration/signing/)。完整步骤见 [gitea.md](../.cursor/skills/git-init/gitea.md)。

网页灰色开锁 /「找不到此签名对应的密钥」= 库中没有**已验证**的可用密钥。只「增加密钥」不够，必须在 `https://<你的Gitea>/user/settings/keys` 点 **验证**。

### 验证 GPG（本 Skill 默认用 GPG 签提交）

在 Cursor 里说「验证 Gitea GPG/SSH 密钥」即可。Agent 会**主动问你要页面令牌**，然后生成签名块给你贴回。

也可本机自己跑：

```powershell
$scripts = "$env:USERPROFILE\.cursor\skills\git-init\scripts"
powershell -NoProfile -ExecutionPolicy Bypass -File "$scripts\verify-gitea-keys.ps1" `
  -GpgToken "GPG页面令牌" `
  -SshToken "SSH页面令牌" `
  -KeyId "你的GPG_Key_ID"
```

（你当前本机 Key ID 示例：`5996DA789B43D451`，以 `gpg --list-secret-keys --keyid-format LONG` 或 Gitea 页面为准。）

说明：

- **可以**把「验证」页上的一次性挑战令牌发给 Agent（不是访问令牌）
- **不要**把 HTTPS 访问令牌发到对话；访问令牌只用 `store-token.ps1`
- Agent 生成签名后，把 `BEGIN PGP SIGNATURE` / `BEGIN SSH SIGNATURE` 贴回 Gitea → **验证**
- 本地保持：

```powershell
git config user.signingkey <你的GPG_Key_ID>
git config commit.gpgsign true
git config --unset gpg.format   # 若曾设为 ssh
```

官方：GPG 用 `echo "TOKEN"`（有换行）；SSH 用 `echo -n`（无换行）。验证成功后**新提交**才会显示已验证；旧提交可能仍开锁。硬刷新（Ctrl+F5）再看。

## 本机依赖

- Git for Windows（含 Git Credential Manager、建议用自带 `gpg.exe` / Git Bash）
- Windows OpenSSH（`ssh-keygen` / `ssh-agent`）
- GPG（Gpg4win，或 Git 自带 `gpg`）

## 常见问题

**对话里提示 profile/token missing**  
本机跑 `store-profile.ps1` / `store-token.ps1`。

**HTTPS 推送失败**  
令牌是否过期、是否勾选仓库写权限；自建是否带端口（如 `:3000`）；重新 `store-token` 后再推送。

**SSH Permission denied**  
公钥是否已加到 Gitea；自定义端口 URL 是否写成 `ssh://git@host:2222/...`。用 `test-ssh.ps1` 测。

**首次连接自建主机问 fingerprint**  
在本机终端确认 host key，不要把 Token 发到聊天。

**提交在 Gitea 网页显示「找不到此签名对应的密钥」**  
对 Cursor 说「验证 Gitea SSH 和 GPG」。Agent 会主动要两个页面挑战令牌并生成签名块。HTTPS 访问令牌仍不要发到对话。详见 [gitea.md](../.cursor/skills/git-init/gitea.md)。

**改了 Skill 但行为没变**  
再跑 `install.ps1`，必要时重开对话。