# Workflow: Repo Setup（仓库初始化）

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **AI Agent 工作流**：此工作流专为 AI Agent 设计，用于自动化仓库初始化设置。

AI Agent 自动创建新仓库并完成基础配置，包括分支保护、初始文档、Issue 模板等，确保新项目快速启动。

## 工作流概述

Repo Setup 工作流自动化创建新 GitLink 仓库，并进行标准化初始化配置，包括 README、LICENSE、分支保护、CI 配置等项目必需的设置。

## 适用场景

- **项目创建**：快速创建新的项目仓库
- **标准化设置**：确保所有仓库配置一致
- **模板应用**：应用组织或团队的项目模板
- **批量创建**：批量创建多个相关项目

## 工作流步骤

### 步骤 1：创建仓库

```bash
# 创建新仓库
gitlink-cli repo +create \
  --name my-awesome-project \
  --description "一个很棒的项目" \
  --private false

# 或者创建私有仓库
gitlink-cli repo +create \
  --name internal-project \
  --description "内部项目" \
  --private true
```

### 步骤 2：初始化本地仓库

```bash
# 本地初始化
cd my-awesome-project
git init
git remote add gitlink https://www.gitlink.org.cn/username/my-awesome-project.git

# 创建初始文件
echo "# My Awesome Project" > README.md
echo "MIT License" > LICENSE
git add .
git commit -m "Initial commit"
git push -u gitlink master:master
```

### 步骤 3：设置分支保护

```bash
# 保护主分支
gitlink-cli branch +protect \
  --owner username \
  --repo my-awesome-project \
  --name master

# 如果使用 main 分支
gitlink-cli branch +protect \
  --owner username \
  --repo my-awesome-project \
  --name main
```

### 步骤 4：创建配置文件

```bash
# 创建 .gitignore
cat > .gitignore << 'EOF'
# 依赖
node_modules/
vendor/

# 构建输出
dist/
build/
*.log

# IDE
.vscode/
.idea/

# 环境变量
.env
.env.local
EOF

# 创建配置文件（根据项目类型）
if [ "$PROJECT_TYPE" = "node" ]; then
    echo '{"name":"my-awesome-project","version":"1.0.0"}' > package.json
elif [ "$PROJECT_TYPE" = "python" ]; then
    echo "[project]\nname = 'my-awesome-project'\nversion = '1.0.0'" > pyproject.toml
fi

git add .gitignore package.json pyproject.toml
git commit -m "Add project configuration files"
git push gitlink master:master
```

### 步骤 5：创建 Issue 和 PR 模板

```bash
# 创建 Issue 模板
cat > .github/ISSUE_TEMPLATE/bug_report.md << 'EOF'
---
name: Bug 报告
about: 报告项目中的问题
title: '[Bug] '
---

## Bug 描述
简要描述遇到的问题。

## 复现步骤
1.
2.
3.

## 预期行为
描述你期望发生的行为。

## 实际行为
描述实际发生的行为。

## 环境
- 操作系统:
- 版本:
- 其他信息:
EOF

# 创建 PR 模板
cat > .github/PULL_REQUEST_TEMPLATE.md << 'EOF'
## 变更描述
简要描述这个 PR 的目的和内容。

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 功能改进
- [ ] 文档更新
- [ ] 性能优化
- [ ] 代码重构

## 测试
描述你如何测试这些变更：

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的测试
- [ ] 已更新相关文档
- [ ] 所有测试通过
- [ ] 无合并冲突
EOF

git add .github/
git commit -m "Add issue and PR templates"
git push gitlink master:master
```

### 步骤 6：创建初始 Issue

```bash
# 创建项目初始化 Issue
gitlink-cli issue +create \
  --owner username \
  --repo my-awesome-project \
  --title "完成项目初始化" \
  --body "## 初始化任务清单

- [x] 创建仓库
- [x] 添加 README.md
- [x] 添加 LICENSE
- [x] 设置分支保护
- [x] 添加配置文件
- [x] 创建 Issue 模板
- [x] 创建 PR 模板
- [ ] 配置 CI/CD
- [ ] 添加项目文档
- [ ] 设置开发指南

## 下一步
1. 配置 CI/CD 流程
2. 编写项目文档
3. 设置开发环境指南
4. 创建贡献指南"
```

### 步骤 7：配置 CI/CD（可选）

```bash
# 创建 CI 配置文件
cat > .gitlab-ci.yml << 'EOF'
stages:
  - test
  - build
  - deploy

test:
  stage: test
  script:
    - echo "Running tests..."
    - npm test

build:
  stage: build
  script:
    - echo "Building..."
    - npm run build

deploy:
  stage: deploy
  script:
    - echo "Deploying..."
    - npm run deploy
  only:
    - master
EOF

git add .gitlab-ci.yml
git commit -m "Add CI/CD configuration"
git push gitlink master:master
```

## 完整工作流示例

```bash
#!/bin/bash

# 仓库初始化自动化脚本

PROJECT_NAME=$1
PROJECT_DESC=$2
IS_PRIVATE=${3:-false}
OWNER="username"

if [ -z "$PROJECT_NAME" ]; then
    echo "使用方法: $0 <project_name> [description] [private]"
    exit 1
fi

echo "开始初始化项目: $PROJECT_NAME"

# 1. 创建仓库
echo "创建仓库..."
REPO_INFO=$(gitlink-cli repo +create \
  --name "$PROJECT_NAME" \
  --description "$PROJECT_DESC" \
  --private "$IS_PRIVATE" \
  --format json)

if echo "$REPO_INFO" | jq -e '.ok' > /dev/null; then
    echo "✅ 仓库创建成功"
else
    echo "❌ 仓库创建失败"
    exit 1
fi

# 2. 本地初始化
echo "初始化本地仓库..."
mkdir -p "$PROJECT_NAME"
cd "$PROJECT_NAME"
git init
git remote add gitlink "https://www.gitlink.org.cn/$OWNER/$PROJECT_NAME.git"

# 3. 创建基础文件
echo "创建项目文件..."

# README.md
cat > README.md << EOF
# $PROJECT_NAME

$PROJECT_DESC

## 快速开始

\`\`\`bash
# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test
\`\`\`

## 项目结构

\`\`\`
$PROJECT_NAME/
├── src/           # 源代码
├── tests/         # 测试文件
├── docs/          # 文档
├── scripts/       # 脚本
└── package.json   # 项目配置
\`\`\`

## 贡献指南

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License
EOF

# LICENSE
cat > LICENSE << 'EOF'
MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
EOF

# package.json
cat > package.json << EOF
{
  "name": "$PROJECT_NAME",
  "version": "1.0.0",
  "description": "$PROJECT_DESC",
  "main": "src/index.js",
  "scripts": {
    "dev": "echo 'Development mode'",
    "build": "echo 'Building project'",
    "test": "echo 'Running tests'",
    "lint": "echo 'Linting code'"
  },
  "keywords": [],
  "author": "",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://www.gitlink.org.cn/$OWNER/$PROJECT_NAME.git"
  }
}
EOF

# .gitignore
cat > .gitignore << 'EOF'
node_modules/
dist/
build/
*.log
.env
.env.local
.DS_Store
*.swp
*.swo
.vscode/
.idea/
coverage/
.nyc_output/
EOF

# 创建目录结构
mkdir -p src tests docs scripts

# 4. 提交初始文件
echo "提交初始文件..."
git add .
git commit -m "Initial commit"
git push -u gitlink master:master

# 5. 设置分支保护
echo "设置分支保护..."
gitlink-cli branch +protect \
  --owner "$OWNER" \
  --repo "$PROJECT_NAME" \
  --name master

# 6. 创建项目模板
echo "创建 Issue 模板..."
mkdir -p .github/ISSUE_TEMPLATE

cat > .github/ISSUE_TEMPLATE/bug_report.md << 'EOF'
---
name: Bug 报告
about: 报告项目中的问题
title: '[Bug] '
---

## Bug 描述
简要描述遇到的问题。

## 复现步骤
1. 
2. 
3. 

## 预期行为
描述你期望发生的行为。

## 实际行为
描述实际发生的行为。

## 环境
- 操作系统:
- 版本:
- 其他信息:
EOF

# 7. 创建初始化 Issue
echo "创建初始化 Issue..."
gitlink-cli issue +create \
  --owner "$OWNER" \
  --repo "$PROJECT_NAME" \
  --title "完成项目初始化设置" \
  --body "## 项目初始化任务

### 基础配置
- [x] 创建仓库
- [x] 添加 README.md
- [x] 添加 LICENSE
- [x] 设置分支保护
- [x] 添加配置文件
- [x] 创建目录结构

### 下一步任务
- [ ] 配置 CI/CD
- [ ] 编写项目文档
- [ ] 设置开发指南
- [ ] 创建贡献指南
- [ ] 添加代码规范
- [ ] 配置代码检查

## 开发环境设置
\`\`\`bash
# 克隆仓库
git clone https://www.gitlink.org.cn/$OWNER/$PROJECT_NAME.git

# 安装依赖
cd $PROJECT_NAME
npm install

# 开发模式
npm run dev
\`\`\`

## 贡献流程
1. Fork 本仓库
2. 创建功能分支 (\`git checkout -b feature/AmazingFeature\`)
3. 提交更改 (\`git commit -m 'Add some AmazingFeature'\`)
4. 推送到分支 (\`git push origin feature/AmazingFeature\`)
5. 创建 Pull Request"

echo "✅ 项目初始化完成！"
echo ""
echo "项目信息:"
echo "  名称: $PROJECT_NAME"
echo "  仓库: https://www.gitlink.org.cn/$OWNER/$PROJECT_NAME"
echo "  状态: $([ "$IS_PRIVATE" = "true" ] && echo "私有" || echo "公开")"
echo ""
echo "下一步:"
echo "  1. cd $PROJECT_NAME"
echo "  2. 配置开发环境"
echo "  3. 开始开发"
```

## AI Agent 集成示例

Claude Code 等 AI Agent 可以深度集成此工作流：

```python
# AI Agent 仓库初始化
def setup_repository(owner, repo_name, description, private=False):
    """AI Agent 自动化仓库初始化"""
    
    # 1. 创建仓库
    repo = create_repository(owner, repo_name, description, private)
    
    # 2. 初始化项目结构
    project_structure = generate_project_structure(repo_name)
    initialize_project_files(repo_name, project_structure)
    
    # 3. 配置分支保护
    protect_branch(owner, repo_name, 'master')
    
    # 4. 创建 Issue 模板
    create_issue_templates(owner, repo_name)
    
    # 5. 配置 CI/CD
    setup_cicd(owner, repo_name, project_structure['type'])
    
    # 6. 创建初始化 Issue
    create_setup_issue(owner, repo_name)
    
    return repo

def generate_project_structure(repo_name):
    """AI 生成项目结构"""
    
    # 分析项目名称和描述，确定项目类型
    project_type = analyze_project_type(repo_name)
    
    structures = {
        'node': {
            'directories': ['src', 'tests', 'docs', 'scripts'],
            'files': {
                'package.json': generate_package_json(repo_name),
                '.gitignore': generate_gitignore('node'),
                'README.md': generate_readme(repo_name)
            }
        },
        'python': {
            'directories': ['src', 'tests', 'docs', 'scripts'],
            'files': {
                'pyproject.toml': generate_pyproject(repo_name),
                '.gitignore': generate_gitignore('python'),
                'README.md': generate_readme(repo_name)
            }
        }
    }
    
    return structures.get(project_type, structures['node'])

def create_issue_templates(owner, repo):
    """创建 Issue 模板"""
    
    templates = {
        'bug_report.md': generate_bug_template(),
        'feature_request.md': generate_feature_template(),
        'question.md': generate_question_template()
    }
    
    for template_name, content in templates.items():
        # 使用 API 创建模板文件
        create_file_via_api(owner, repo, 
                          f'.github/ISSUE_TEMPLATE/{template_name}', 
                          content)
```

## 项目模板

### 前端项目模板

```bash
# 创建前端项目结构
create_frontend_project() {
    mkdir -p src/{components,pages,hooks,utils}
    mkdir -p public/{images,fonts}
    mkdir -p tests/{unit,integration}
    
    # package.json
    cat > package.json << 'EOF'
{
  "name": "my-frontend-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest",
    "lint": "eslint src/"
  },
  "dependencies": {
    "react": "^18.0.0"
  }
}
EOF
}
```

### 后端项目模板

```bash
# 创建后端项目结构
create_backend_project() {
    mkdir -p src/{controllers,models,routes,middleware}
    mkdir -p tests/{unit,integration}
    mkdir -p config
    mkdir -m migrations
    
    # package.json
    cat > package.json << 'EOF'
{
  "name": "my-backend-project",
  "version": "1.0.0",
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "test": "jest",
    "migrate": "knex migrate:latest"
  },
  "dependencies": {
    "express": "^4.18.0",
    "knex": "^2.0.0"
  }
}
EOF
}
```

## 配置检查清单

仓库初始化完成后检查：

- [ ] 仓库创建成功
- [ ] README.md 完整
- [ ] LICENSE 文件存在
- [ ] 分支保护已设置
- [ ] .gitignore 配置正确
- [ ] Issue 模板创建
- [ ] PR 模板创建
- [ ] CI/CD 配置（可选）
- [ ] 初始化 Issue 已创建
- [ ] 本地仓库可正常推送

## 最佳实践

1. **标准化模板**：使用统一的项目模板
2. **配置管理**：统一配置文件格式
3. **文档完整**：确保 README 和文档完整
4. **安全设置**：合理设置分支保护
5. **CI/CD 配置**：早期建立 CI/CD 流程

## References

- [workflow-issue-triage](workflow-issue-triage.md) — Issue 分类工作流
- [workflow-sprint-report](workflow-sprint-report.md) — Sprint 报告工作流
- [gitlink-workflow](../SKILL.md) — 工作流总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [repo +create](../../gitlink-repo/references/repo-create.md) — 创建仓库
- [branch +protect](../../gitlink-branch/references/branch-protect.md) — 保护分支
