Files

T

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

2026-08-20 23:42:02 +08:00

7.5 KiB

Raw Blame History

git-init 使用文档

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

配套阅读：

架构.md — 组件、数据流、流程图
Gitea 说明 — 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 -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

效果：

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

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

本机一次配置

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

$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 -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 仓库）。

初始化

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

或：

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

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

日常提交

按 git-init 提交这些改动

日常推送

推送到 Gitea

提交并推送

提交并推送

克隆

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

拉取

拉取远程更新

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

分支 / 合并 / 查看

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

更多例句见 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。完整步骤见 gitea.md。

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

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

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

也可本机自己跑：

$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 → 验证
本地保持：

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。

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

7.5 KiB Raw Blame History Unescape Escape