跳转至

成员指南

欢迎加入 insightureAI GitHub 组织。 本指南涵盖你需要了解的入门事项和日常工作流。

开始之前

1. 启用双因素认证 (2FA)

2FA 是强制要求的。没有启用 2FA 将无法访问组织的任何资源。

设置步骤： 1. 前往 https://github.com/settings/security 2. 点击 "Enable two-factor authentication" 3. 选择 Authenticator App（推荐：Google Authenticator、1Password 或 Authy） 4. 用 app 扫描 QR code 5. 输入验证码确认 6. 将 recovery codes 保存到安全的地方

不允许使用 SMS 方式的 2FA。请使用 Authenticator App 或 Security Key。

2. 接受组织邀请

你会收到加入 insightureAI 的邮件邀请。接受邀请后即可访问所有仓库。

3. 安装 Git 并配置

git config --global user.name "你的名字"
git config --global user.email "你的GitHub邮箱@example.com"

4. 配置 Claude Code（推荐）

我们使用 Claude Code 辅助开发。首次使用时：

  1. 安装 Claude Code
  2. Clone 任何 retaintive repo 并启动 Claude Code
  3. Trust 项目 — 系统会提示安装 retaintive-plugins marketplace
  4. 运行 /plugin install retaintive-tools@retaintive-plugins
  5. 获得 19 个团队 skills（调查、PR、AWS 调试、文档等）+ 6 个 domain agents

一次安装，所有 retaintive repo 通用。详见 claude-plugins README。

日常工作流

Clone 仓库（首次）

git clone https://github.com/insightureAI/<repo-name>.git
cd <repo-name>

开发新功能或修复 Bug

# 1. 确保在 main 分支并拉取最新代码
git checkout main
git pull

# 2. 创建新分支
git checkout -b feature/your-feature-name
# 或
git checkout -b fix/bug-description

# 3. 进行你的修改...

# 4. 暂存并提交
git add .
git commit -m "feat: 描述你做了什么"

# 5. Push 你的分支
git push origin feature/your-feature-name

创建 Pull Request (PR)

  1. 在 GitHub 上进入对应 repo
  2. 你会看到提示："feature/your-feature-name had recent pushes" → 点击 "Compare & pull request"
  3. 填写 PR 标题和描述
  4. 选择目标分支（通常是 main）
  5. 点击 "Create pull request"
  6. 等待 Owner review 并 approve

PR 被合并后

# 切回 main 并拉取最新代码
git checkout main
git pull

# 删除本地的 feature branch（可选的清理操作）
git branch -d feature/your-feature-name

分支命名规范

类型 格式 示例
新功能 feature/<description> feature/add-login-page
Bug 修复 fix/<description> fix/null-pointer-on-submit
维护/杂项 chore/<description> chore/update-dependencies

Commit Message 规范

我们使用 Conventional Commits：

feat: add user authentication
fix: resolve null pointer on form submit
chore: update npm dependencies
docs: add API endpoint documentation
refactor: extract validation logic into utils

你可以做什么和不可以做什么

允许

  • Clone 和 pull 组织内任何 repo
  • 创建 feature/fix 分支并 push
  • 创建 Pull Request
  • 在 issue 和 PR 上评论
  • 查看组织内所有仓库

不允许

  • 直接 push 到受保护的分支如 main（必须通过 PR）
  • 删除仓库
  • 更改仓库可见性（private/public）
  • 创建新仓库（请联系 Owner）
  • 安装 GitHub Apps
  • 创建 Teams

如果你尝试直接 push 到受保护的分支（如 main）： 

git push origin main
# ❌ remote: error: GH006: Protected branch update failed
# ❌ remote: error: Required pull request review
这是正常的。请创建 feature branch 并通过 PR 提交。

各 Repo 权限与保护规则

所有 repo 的 base permission 为 Write — 你可以 clone、创建分支、push 到 feature branch。以下是每个 repo 受保护的分支和 PR 合并要求：

Repo 受保护分支 PR 合并要求
studio-website-monorepo main 1 个 approval + Lint、Typecheck、Unit Tests、Build Check 通过
lead-tracking main 1 个 approval
callytics-infrastructure main 1 个 approval + CI Checks & Lambda Builds、Validation Summary 通过
callytics-common main 1 个 approval
rcConnectionChecker main 1 个 approval
cloudflare-github-webhook-rerouter main 1 个 approval

所有受保护分支的通用规则： - 禁止直接 push — 必须通过 PR - 禁止 force push — 不能改写历史 - 禁止删除分支 - 新 push 后旧的 review 自动失效（需要重新 review） - PR 中的所有 conversation 必须标记为 resolved 才能合并

没有 status checks 的 repo，PR 只需要 1 个 approval 即可合并。有 status checks 的 repo，CI 必须全部通过 + 1 个 approval。

部署与 Hotfix

指定分支部署

deploy-test.yml、deploy-pre.yml、deploy-prod.yml 都支持 ref 参数，可以部署任意 branch、tag 或 commit SHA：

# 部署指定分支到 test
gh workflow run deploy-test.yml -f ref=feature/my-branch

# 部署 prod tag 的 hotfix 到 prod
gh workflow run deploy-prod.yml -f confirm=deploy-prod -f ref=hotfix/fix-description

紧急 Hotfix

当 prod 出 bug 需要紧急修复时：

# ① 从 prod tag 切分支（不是从 main！）
git tag --list 'prod-*' --sort=-creatordate | head -5
git checkout -b hotfix/简短描述 prod-2026-03-04

# ② 修 bug 并 push
git add 具体文件 && git commit -m "fix: 简要描述"
git push -u origin hotfix/简短描述

# ③ 部署到 test 验证
gh workflow run deploy-test.yml -f ref=hotfix/简短描述

# ④ 部署到 prod
gh workflow run deploy-prod.yml -f confirm=deploy-prod -f ref=hotfix/简短描述

# ⑤ 合回 main（必须！）
gh pr create --base main --head hotfix/简短描述 --title "fix: 合并 hotfix 回 main"

为什么从 tag 切？因为 main 上可能有还没部署的新代码。从 prod tag 切保证 hotfix 分支和当前生产环境一致。

详见 Git 分支与部署指南。

获取帮助

  • 无法访问 repo？ → 确认你已接受组织邀请并启用了 2FA
  • Push 被拒绝？ → 你可能在 push 到受保护的分支。请创建 feature branch
  • 需要新 repo？ → 联系 Owner 创建
  • 需要安装 GitHub App？ → 联系 Owner 审查并安装

Personal Access Tokens (PAT)

如果你需要 token 用于 CLI 工具或脚本：

  1. 前往 https://github.com/settings/tokens?type=beta
  2. 点击 "Generate new token"（使用 Fine-grained，不要用 Classic）
  3. 选择 insightureAI 作为 resource owner
  4. 仅选择你需要的特定 repo
  5. 授予最小必要权限
  6. 设置过期时间
  7. 提交 — Owner 必须审批后 token 才能生效

不要使用 Classic token。始终使用 Fine-grained token 并授予最小必要权限。