# Git Repo Sync Changelog

> Sets up and runs Git remote pull sync plus post-sync change logs with impact and cause analysis. Default analysis uses Cursor SDK local agent with model composer-2.5. Use when the user asks to sync a git repo, pull remote updates, track code changes, �ֿ�ͬ��, ��ȡͬ��, ������˵��, Զ�̱������, repo-sync, or daily scheduled backend sync. Only use rule-based-only or non-Cursor analysis when the user explicitly requests another method.

- Skill: `playerrch/git-repo-sync-changelog` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add playerrch/git-repo-sync-changelog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/playerrch/git-repo-sync-changelog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: playerrch (https://skillmd.com/u/playerrch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/playerrch/git-repo-sync-changelog

---


# Git �ֿ���ȡͬ����䶯����

## Ĭ�ϲ��ԣ��������أ�

| �㼶 | Ĭ�� | ���� |
| --- | --- | --- |
| ������� | **Cursor SDK** + ģ�� **`composer-2.5`** | �û���ȷ˵������ Cursor / ���� API / ֻҪ������� / �ñ��ģ�͡� |
| ��ȡ��ʽ | `git fetch` + `git pull --ff-only` | �û�Ҫ�� rebase��merge ���������� |
| �ĵ����� | UTF-8 **�� BOM**��Windows ���ģ� | �� |

**��Ҫ**Ĭ���ô� `git log`���� Python ����ű��� IDE ��������� SDK�������û���ȷҪ��� `CURSOR_API_KEY` ȱʧ���û����ܽ�����

����ͨ�� **Cursor TypeScript SDK**��`@cursor/sdk`���ں�̨���ñ��� Agent��**����**�� Cursor ���ڣ�Ҳ**����**���ѵ�ǰ�Ի���

---

## ��ʱ���ñ� skill

- �û�Ҫ���� / ͬ�� Git Զ�ֿ̲⵽����Ŀ¼
- �û�Ҫ�Զ����ɻ���¡�������˵����Markdown
- �û�Ҫ����ÿ�춨ʱ��ȡ + ����
- �û��� API Key �����`composer-2.5` ��ν���

---

## ��׼Ŀ¼�ṹ���ɸ��õ������˲֣�

��**Ŀ��ֿ��Ŀ¼**���³� `REPO_ROOT`��Ӧ�߱���

```text
REPO_ROOT/
������ repo.sync.json              # Զ�� URL����֧��changelog ·����cursorAnalysis
������ .repo-sync.local.json       # Git ƾ�ݣ�gitignore��
������ .cursor-sync.env            # CURSOR_API_KEY��gitignore��
������ .repo-sync.local.json.example
������ .cursor-sync.env.example
������ Զ�ֿ̲�ͬ���������˵��.md   # ���� repo.sync.json ָ���ļ���
������ README-�ֿ�ͬ��.md
������ .sync-state.json            # ����ʱ״̬��gitignore��
������ sync-logs/
������ scripts/
    ������ repo-sync.ps1
    ������ run-cursor-analysis.ps1
    ������ install-sync-scheduler.ps1
    ������ fix-doc-encoding.ps1
    ������ analyze-git-changes.py      # ������������Ĭ����·��
    ������ changelog-header.md
    ������ cursor-sync-agent/
        ������ package.json            # @cursor/sdk ^1.0.13
        ������ run-analysis.mjs
```

��Ŀ¼�����ڣ��� [reference.md](reference.md) �Ӳο�ʵ�ָ��ƻ����ɣ�����Ŀ�ο���`high-quality-dataset-backend-dev`����

---

## �����ļ�

### `repo.sync.json`��ʾ����

```json
{
  "remoteUrl": "http://HOST/group/project.git",
  "branch": "dev",
  "changelogFile": "Զ�ֿ̲�ͬ���������˵��.md",
  "stateFile": ".sync-state.json",
  "syncLogDir": "sync-logs",
  "cursorAnalysis": {
    "enabled": true,
    "model": "composer-2.5"
  }
}
```

- ��ģ�ͣ��� `cursorAnalysis.model`�����˺ſ��ã��� `composer-2`��
- �ر� AI�� `"enabled": false`���Կ��� git pull + ��ѡ����ժҪ��

### `.repo-sync.local.json`��GitLab / �Խ� Git��

```json
{
  "username": "user@company.com",
  "password": "token_or_password"
}
```

### `.cursor-sync.env`��Cursor ��������������� composer-2.5��

```env
CURSOR_API_KEY=cursor_xxxxxxxx
```

**API Key ����λ��**������ Cloud Agents ҳ����  
[https://cursor.com/dashboard/integrations](https://cursor.com/dashboard/integrations) �� **API Keys** �� Create��

---

## ִ�����̣�Agent Ӧ����˳��

### 1. �״ι���Զ��

```powershell
cd REPO_ROOT
git init                                    # ������ .git
git remote add origin <remoteUrl>             # �� set-url
git fetch origin <branch>
git checkout -B <branch> origin/<branch>    # ��������ʷʱ
# ����δ�����ļ���ͻ�����ݱ��ض����ļ��� checkout -f
```

д��ƾ�ݣ�`.repo-sync.local.json`��`git credential-manager store`���ű�����������

### 2. �ֶ�ͬ�� + �����������

```powershell
cd REPO_ROOT
powershell -ExecutionPolicy Bypass -File scripts/repo-sync.ps1
```

�ڲ��߼���

1. `git fetch` / `git pull --ff-only`
2. �������ύ �� ��ѡ����ժҪ��`analyze-git-changes.py`��Python ����ʱ��
3. **Ĭ��** �� `run-cursor-analysis.ps1` �� `run-analysis.mjs` �� `Agent.prompt` + **`composer-2.5`**
4. ׷�ӵ� `changelogFile`��UTF-8 BOM��

### 3. ���� Cursor �������� commit��

```powershell
powershell -ExecutionPolicy Bypass -File scripts/run-cursor-analysis.ps1 -OldRef <old> -NewRef <new>
```

�״��裺`cd scripts/cursor-sync-agent && npm install --omit=dev`

### 4. ע��ƻ�����Windows��Ĭ��ÿ�� 0:00��

```powershell
powershell -ExecutionPolicy Bypass -File scripts/install-sync-scheduler.ps1
# ����ʱ�̣�-AtTime "02:00"
```

������Ĭ�ϣ�`HQDataset_Backend_Dev_Sync`�����ڽű������� `-TaskName`����

---

## Composer 2.5 ���������ʽ

׷�ӵ� changelog ���½��������

- **�������**
- **Ӱ�����**��ҵ��ģ�顢SQL��Ȩ�ޡ�API �ȣ�
- **���ԭ���ƶ�**����ȷ������ע�������ύ��ȷ�ϡ���
- **������֤**

�½ڱ��⽨�飺`### Composer 2.5 ��ȷ���`�����ģ�� id����

---

## �������Ĭ��·�������û���ȷҪ��ʱ��

| �û�˵�� | ���� |
| --- | --- |
| ����Ҫ Cursor / ��Ҫ API�� | `cursorAnalysis.enabled: false`������ `analyze-git-changes.py` �� `git log`/`diff --stat` |
| ���� composer-2 / ���ģ�͡� | �� `repo.sync.json` �� `model` |
| �����ڶԻ�����ҷ����� | �ڵ�ǰ Agent �Ự�� diff д MD��**��**�� SDK��˵���붨ʱ�����޹أ� |
| ���� Cloud Agents API�� | �� REST `/v1/agents`���Ǳ� skill Ĭ�� |

�� `CURSOR_API_KEY` ʱ����� pull����־��¼���� AI��**��Ҫ**��װ���� composer-2.5��

---

## �����ĵ�����

д��/׷�� `.md` ������ **UTF-8 BOM**��

- PowerShell��`[System.IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding $true))`
- ����������� `Set-Content` д����
- �޸����룺`powershell -ExecutionPolicy Bypass -File scripts/fix-doc-encoding.ps1`

---

## ��ȫ

- `.repo-sync.local.json`��`.cursor-sync.env` **����**�ύ Git
- `.gitignore` ����������ļ��� `sync-logs/`��`scripts/cursor-sync-agent/node_modules/`

---

## �����Ų�

| ���� | ���� |
| --- | --- |
| `git pull` ʧ�� | ��鱾���޸ģ���ǿ�ƣ��˹� merge |
| `CURSOR_API_KEY not set` | ���� `.cursor-sync.env` |
| SDK 401 | Key ��Ч����ڣ��� Integrations �������� |
| �ƻ�����δ�� | 0:00 �����迪����`Get-ScheduledTask -TaskName '...'` |
| �������� | ���� `fix-doc-encoding.ps1` |

��֤ Key��`curl -u "$env:CURSOR_API_KEY:" https://api.cursor.com/v1/me`

---

## �ο�ʵ��

����Ŀ�����ű�·����`high-quality-dataset-backend-dev/`���� [reference.md](reference.md)����

Agent ʵʩʱ������ **ִ�����нű�**����Ҫ��дһ�ף���ȱ�ļ�ʱ�� reference ���롣

