223 lines
7.5 KiB
Markdown
223 lines
7.5 KiB
Markdown
# 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`，必要时重开对话。
|