# git-init 架构

本文说明组件如何分工、密钥放在哪、各条 Git 路径怎么走。使用步骤见 [使用文档.md](使用文档.md)。

## 设计目标

- **对话里只出现 Gitea 仓库 URL 和 SSH/GPG 选择**，不出现 Token
- **同一套本机档案**服务于初始化以及之后每一次提交、推送、克隆、拉取
- **默认远程为 Gitea**（自建域名与自定义端口）；脚本按 URL 解析 host/port
- **Windows PowerShell** 可执行；不用 `eval "$(ssh-agent -s)"`
- **可复用**：源码在仓库 `.cursor/skills/git-init`，`install.ps1` 同步到个人 Skill 目录

## 逻辑架构

```mermaid
flowchart LR
  user[UserCursorChat]
  agent[AgentPlusSkill]
  scripts[PowerShellScripts]
  profile[ProfileJson]
  tokenFile[TokenDpapi]
  gcm[GitCredentialManager]
  sshAgent[WindowsSshAgent]
  gpg[GpgKeyring]
  git[GitRepo]
  remote[GiteaHost]

  user --> agent
  agent --> scripts
  scripts --> profile
  scripts --> tokenFile
  tokenFile -->|"decrypt CurrentUser"| gcm
  scripts --> sshAgent
  scripts --> gpg
  agent --> git
  gcm --> remote
  sshAgent --> remote
  git --> remote
```

三层：

1. **Skill 指令**（`SKILL.md`）：路由到 Init / Commit / Push / Clone 等，并列出安全红线
2. **脚本**（`scripts/`）：状态检查、加密存取、注入凭据、SSH/GPG；stdout 不含 Token
3. **本机秘密**（`%USERPROFILE%\.git-skills\`）：与任何项目仓库隔离

## 目录与职责

```mermaid
flowchart TB
  subgraph repo [git-skillsRepo]
    skillMd[SKILL.md]
    workflows[workflows.md]
    reference[reference.md]
    examples[examples.md]
    scriptsDir[scripts]
    installPs[install.ps1]
    docsDir[docs]
  end

  subgraph personal [UserHome]
    personalSkill[".cursor/skills/git-init"]
    secrets[".git-skills"]
  end

  installPs -->|"copy skill not secrets"| personalSkill
  scriptsDir --> secrets
```

| 路径 | 职责 |
| --- | --- |
| `.cursor/skills/git-init/SKILL.md` | Agent 入口：路由、红线、Init/Commit/Push |
| `workflows.md` | Clone / Pull / Branch / Merge / Tag / Stash / Inspect |
| `reference.md` | 中文提交规范、Windows SSH/GPG、故障表 |
| `examples.md` | 触发例句 |
| `scripts/*.ps1` | 可执行步骤；失败用退出码和 `key=value` |
| `install.ps1` | 复制 Skill 到 `~/.cursor/skills/git-init` |
| `%USERPROFILE%\.git-skills\profile.json` | 姓名、邮箱、HTTPS 用户名、SSH 路径 |
| `%USERPROFILE%\.git-skills\token.dpapi` | 仅 Token，DPAPI `CurrentUser` |

Agent **可以**读 `profile.json`（经 `profile-status.ps1`）。Agent **不得**读 `token.dpapi`。

## 信任边界

```mermaid
flowchart TB
  subgraph chat [CursorChat]
    urlIn[RemoteUrl]
    talk[NoTokenInChat]
  end

  subgraph machine [ThisWindowsUser]
    dpapi[DPAPI]
    gcm[GCM]
    sshKeys[SSHPrivateKey]
    gpgKeys[GPGSecretKey]
  end

  subgraph project [GitWorkTree]
    gitDir[.git]
    ignore[.gitignore]
  end

  subgraph host [Gitea]
    origin[origin]
  end

  urlIn --> gitDir
  dpapi -->|"git credential approve stdin"| gcm
  gcm --> origin
  sshKeys --> origin
  gitDir --> origin
  ignore -->|"block secrets"| gitDir
```

- 解密只在当前 Windows 用户下有效；换用户或换机器无法读 Token
- 注入走 stdin 给 `git credential approve`，不写进命令行参数、不写进仓库
- 项目 `.gitignore` 忽略 `.git-skills/`、`*.dpapi`、私钥

## 脚本调用关系

```mermaid
flowchart TB
  storeProfile[store-profile.ps1]
  storeToken[store-token.ps1]
  profileStatus[profile-status.ps1]
  tokenStatus[token-status.ps1]
  prepareCommit[prepare-commit.ps1]
  prepareAuth[prepare-auth.ps1]
  preparePush[prepare-push.ps1]
  inject[inject-credential.ps1]
  ensureSsh[ensure-ssh.ps1]
  ensureGpg[ensure-gpg.ps1]
  assertSecrets[assert-no-secrets.ps1]
  repoStatus[repo-status.ps1]
  common[common.ps1]

  storeProfile --> common
  storeToken --> common
  profileStatus --> common
  tokenStatus --> common
  prepareCommit --> common
  prepareAuth --> inject
  prepareAuth --> ensureSsh
  preparePush --> prepareAuth
  inject --> common
  ensureSsh --> common
  ensureGpg --> common
  assertSecrets --> common
  repoStatus --> common
```

| 脚本 | 谁跑 | 作用 |
| --- | --- | --- |
| `store-profile.ps1` / `store-token.ps1` | 用户本机终端 | 交互写入档案 / 加密 Token |
| `profile-status.ps1` / `token-status.ps1` | Agent | `present` / `missing`，无密钥明文 |
| `prepare-commit.ps1` | Agent | 本地作者 + `commit.gpgsign` |
| `prepare-auth.ps1` | Agent | 按 URL 注入 GCM 或 ssh-add（克隆可用） |
| `prepare-push.ps1` | Agent | 读 `origin` 再调 `prepare-auth` |
| `ensure-ssh.ps1` / `ensure-gpg.ps1` | Agent | 复用或生成密钥；日常推送 `-NoGenerate -Quiet` |
| `assert-no-secrets.ps1` | Agent | 提交前拦截密钥路径 |
| `repo-status.ps1` | Agent | 分支、脏否、打码后的 origin |

## 主流程

### 总路由

```mermaid
flowchart TD
  start[UserRequest]
  start --> route{Intent}
  route -->|init| initPath[Init]
  route -->|commit| commitPath[Commit]
  route -->|push| pushPath[Push]
  route -->|commitAndPush| commitPath
  commitPath -->|ifAskedPush| pushPath
  route -->|clone| clonePath[Clone]
  route -->|pullOrFetch| syncPath[Sync]
  route -->|branchMergeTagStash| localPath[LocalGit]
  route -->|statusLogDiff| inspectPath[Inspect]
  route -->|commitButNotRepo| initPath
```

### 初始化

```mermaid
flowchart TD
  detect[DetectRepoAndRemote]
  detect --> profile{ProfileAndToken}
  profile -->|missing| stopStore[StopTellUserRunStoreScripts]
  profile -->|ok| askUrl[NeedRemoteUrl]
  askUrl --> initGit[git init plus local author]
  initGit --> addOrigin[remote add origin]
  addOrigin --> inject[inject-credential]
  inject --> ssh[ensure-ssh plus ssh test]
  ssh --> gpg[ensure-gpg plus gpgsign]
  gpg --> hygiene[gitignore and README]
  hygiene --> firstCommit[Commit path]
  firstCommit --> firstPush[Push main]
  firstPush --> verify[status remote log signature]
```

### 每次提交

```mermaid
flowchart TD
  prep[prepare-commit]
  prep --> signing{signing present}
  signing -->|missing| gpg[ensure-gpg]
  gpg --> prep
  signing -->|ok| inspect[status diff log]
  inspect --> secrets[assert-no-secrets]
  secrets -->|blocked| unstage[Unstage secret paths]
  secrets -->|ok| stage[Stage related files]
  stage --> msg[Chinese type colon description]
  msg --> commit[git commit -S]
  commit --> check[log show-signature]
  check --> maybePush{User asked push}
  maybePush -->|yes| pushPath[Push]
  maybePush -->|no| done[Stop]
```

### 每次推送 / 克隆 / 拉取

```mermaid
flowchart TD
  needAuth[NeedNetworkAuth]
  needAuth --> hasRepo{Inside work tree}
  hasRepo -->|yes| prepPush[prepare-push]
  hasRepo -->|no clone| prepAuth[prepare-auth with URL]
  prepPush --> proto{Protocol}
  prepAuth --> proto
  proto -->|https| gcm[GCM uses injected token]
  proto -->|ssh| sshAdd[ssh-add Quiet]
  gcm --> gitNet[git push or clone or pull]
  sshAdd --> gitNet
```

HTTPS：Token 解密后仅进入 `git credential approve` 的 stdin。SSH：用已有 `id_ed25519`，日常路径不生成新密钥、不打印公钥。

## Agent 控制流

```mermaid
sequenceDiagram
  participant U as User
  participant A as Agent
  participant S as Scripts
  participant G as Git
  participant H as GitHost

  U->>A: 提交并推送
  A->>S: profile-status token-status repo-status
  S-->>A: present plus branch info
  A->>S: prepare-commit
  A->>S: assert-no-secrets
  A->>G: git commit -S
  A->>S: prepare-push
  S->>G: credential approve or ssh-add
  A->>G: git push
  G->>H: objects
  A-->>U: 作者签名与推送结果无 Token
```

## 与原始任务的对应

[相关文档.md](../相关文档.md) 中的步骤映射：

| 文档章节 | 实现 |
| --- | --- |
| 一 init | `git init -b main` |
| 二 用户信息 | `profile.json` + 仓库 local `user.name` / `user.email` |
| 三 远程 | `git remote add origin`（已有则不改） |
| 四 Token | DPAPI + GCM，禁止写入代码 |
| 五 SSH | `ensure-ssh.ps1` + Windows `ssh-agent` |
| 六 GPG | `ensure-gpg.ps1` + `commit.gpgsign` |
| 七 / 十二 中文提交 | 每次 Commit 路径强制 `类型: 描述` |
| 八 README | 缺失才生成 |
| 九 / 十 首次提交推送 | Init 末尾走 Commit + Push |
| 十一 验收 | `status` / `remote -v` / `log --show-signature` |

## Gitea URL 与凭据

```mermaid
flowchart TD
  url[GiteaRemoteUrl]
  url --> parse[Parse-GitRemoteUrl]
  parse --> httpsPath{Protocol}
  httpsPath -->|https or http| credHost[CredentialHost may include port]
  httpsPath -->|ssh| sshHost[Host plus optional Port]
  credHost --> inject[inject-credential to GCM]
  sshHost --> sshTest[test-ssh with ssh -p]
  inject --> pushHttps[git push HTTPS]
  sshTest --> pushSsh[git push SSH]
```

| URL 示例 | CredentialHost | SSH 测试 |
| --- | --- | --- |
| `https://git.example.com/a/b.git` | `git.example.com` | 不适用 |
| `https://git.example.com:3000/a/b.git` | `git.example.com:3000` | 不适用 |
| `git@git.example.com:a/b.git` | 主机名（供日后 HTTPS） | `ssh -T git@...` |
| `ssh://git@git.example.com:2222/a/b.git` | 主机名（不含 2222） | `ssh -p 2222 -T git@...` |

细节见 [gitea.md](../.cursor/skills/git-init/gitea.md)。

## Gitea 密钥验证（官方行为）

依据 [docs.gitea.com/administration/signing](https://docs.gitea.com/administration/signing/)：灰色开锁 = 数据库中找不到可校验密钥。用户密钥须在 `/user/settings/keys` **验证**后，提交签名才能被识别。

```mermaid
flowchart TD
  addKey[AddPubkeyOnGitea]
  addKey --> verifyClick[ClickVerifyOnSettings]
  verifyClick --> challenge[PageShowsToken]
  challenge --> localSign[verify-gitea-keys with tokens from chat]
  localSign --> paste[AgentShowsSignatureBlocks]
  paste --> verified[KeyMarkedVerified]
  verified --> newCommit[NewSignedCommitShowsVerified]
```

| 脚本 | 对齐官方 UI |
| --- | --- |
| `verify-gitea-keys.ps1` | 编排：可缺令牌时提示 `need_token`；有令牌则调下面两个脚本 |
| `verify-gpg-challenge.ps1` | `echo "TOKEN" \| gpg -a --default-key KEY --detach-sig`（有换行） |
| `verify-ssh-challenge.ps1` | `echo -n 'TOKEN' \| ssh-keygen -Y sign -n gitea -f KEY`（无换行） |

HTTPS **访问令牌**禁止进对话。页面 **验证挑战令牌**可由 Agent 主动询问（一次性，不落盘）。