技术管理员操作手册

你是谁 / 本手册范围

你是技术管理员：一次性搭起团队的文档站（docs-site）+ skills 分发仓库，日常按项目注册 content/{project}/ 子目录、按成员签发 Token、把本地 skill 改动按角色同步到 7 个 GitLab 仓库。本手册只讲 admin 专属 skill（docs-site-init / skills-init / docs-admin-init / member-token-gen / skills-sync）。全员通用的 /git-*、/docs-push-gitlab、/notify、/bug-* 等先读 common.md。

2026-04-20 docs monorepo 迁移后三个关键变化：

单一真理源 — 所有项目文档合并到 docs-site（project ID 213）的 content/{project}/**，不再建独立 {project}-docs 仓库

单 docs token — 每位成员一个 docs-{name}（api 权限）token 就能读写所有项目，不再按项目发多份

docs-admin-init 职责缩小 — 不再建 GitLab 仓库，而是在 docs-site 下 mkdir content/{project}/ 并更新 projects.json

首次配置

1. 初始化管理员 `.docs.env`

管理员本地 .docs.env 是高权限配置（含 GITLAB_ADMIN_TOKEN），不会分发给任何成员。首次配置需包含以下字段：

# GitLab 基础配置
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main

# 管理员身份
MEMBER_NAME=admin_name
MEMBER_TG=@admin_tg

# 管理员专属高权限 Token（api 权限，用于创建仓库 / 签发成员 Token）
GITLAB_ADMIN_TOKEN=glpat-xxxxxxxxx

# docs-site 仓库（所有项目文档的单一真理源，固定 213）
GITLAB_DOCS_PROJECT_ID=213
DOCS_SITE_PROJECT_ID=213
GITLAB_DOCS_SITE_WRITE_TOKEN=glpat-xxxx    # 管理员自己要写 team.md / daily-log 等，需单独给自己跑一次 member-token-gen

# Cloudflare Pages（docs-site-init 一次性写入；CLOUDFLARE_API_TOKEN 只存 CI 变量不入此文件）
CLOUDFLARE_ACCOUNT_ID=xxxx
CLOUDFLARE_PAGES_PROJECT=team-docs

# 历史兼容字段（monorepo 后基本不用，docs-site-init 读取 Group 时作为备选）
GITLAB_DOCS_GROUP_ID=
GITLAB_DOCS_GROUP_PATH=docs

# 图床
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=xxx

# Telegram
TELEGRAM_BOT_TOKEN=bot123:xxx
# 成员名单不在本地——单一真相源是 docs-site/content/manage/team.md（由 /member-token-gen 通过 Files API 维护）

# 项目段（仅 TELEGRAM_CHAT_ID + LSKY_STRATEGY_ID；不再需要 per-project token / ID）
[pay-fi]
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1

[fomo-pad]
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=2

.docs.env 已加入 .gitignore，绝对不得提交。

2. 生成 `.skills.env`（`/skills-init` 一次性）

/skills-init

在 GitLab Group 下创建 7 个角色仓库（已存在则跳过）
自动生成 .skills.env，内含 GITLAB_BASE_URL / GITLAB_GROUP_ID / GITLAB_GROUP_PATH + 7 个 SKILLS_REPO_*（COMMON / PM / FRONTEND / BACKEND / CONTRACT / QA / ADMIN）
.skills.env 已加入 .gitignore

换机器时直接重跑即可恢复（幂等，API 检测已存在仓库后复用其 id）。

3. 自检管理员必需字段

跑 admin skill 前核对五组：

GitLab 高权限 — GITLAB_ADMIN_TOKEN（api 权限，Maintainer 或 Owner）；创建仓库 / 签发 token 都靠它
docs-site 引用 — GITLAB_DOCS_PROJECT_ID=213 + DOCS_SITE_PROJECT_ID=213 + GITLAB_DOCS_SITE_WRITE_TOKEN（管理员要写 team.md / daily-log 时用）
Cloudflare 访问 — CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_PAGES_PROJECT（CLOUDFLARE_API_TOKEN 只放 GitLab CI 变量）
Skills 分发 — .skills.env 中 7 个 SKILLS_REPO_* id 齐全
图床 + 通知 — LSKY_BASE_URL / LSKY_TOKEN / TELEGRAM_BOT_TOKEN 已填（分发成员 token 时读出来写进成员配置）。成员名册不在本地，已迁移到 docs-site content/manage/team.md 单一真相源

缺哪项，对应 skill 会在 HARD-GATE 阶段拦下并指名。

日常工作流

场景 A：一次性初始化文档站

什么时候用：全团队从零起步，还没有 docs-site 仓库 / Cloudflare Pages 项目时。只跑一次。

触发命令：

/docs-site-init

关键输入：一次性表单填 3 项：Cloudflare Account ID（Dashboard → 右侧边栏）/ Cloudflare API Token（需 Pages 编辑权限）/ 文档站项目名（最终 URL 是 {name}.pages.dev，默认 team-docs）。

产出结果：

GitLab 创建 docs-site 仓库，推 Astro 模板 + .gitlab-ci.yml（main push 自动 build + wrangler pages deploy --branch=main）
GitLab CI/CD Variables 写 4 项：DOCS_ADMIN_TOKEN / CLOUDFLARE_API_TOKEN（masked）+ CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_PAGES_PROJECT
Cloudflare Pages 创建同名项目，production_branch=main
管理员 .docs.env 追加 CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_PAGES_PROJECT / DOCS_SITE_PROJECT_ID

跑过就别再跑 — 幂等但浪费 API 调用且可能覆盖你手动调的 CI 变量。

场景 B：一次性初始化 skills 分发

什么时候用：.skills.env 还没生成，或者换机器想恢复时。每个 group 跑一次。

触发命令：

/skills-init

关键输入：一次性表单填 4 项：GitLab 地址（末尾不带 /）/ Group ID（Settings → General）/ Group 路径（URL 中的 group 名）/ Skills 仓库名前缀（默认 skills，留 0 即默认）。

产出结果：

Group 下创建 7 个仓库（skills-common / skills-pm / skills-frontend / skills-backend / skills-contract / skills-qa / skills-admin），已存在的取其 id 复用
项目根写入 .skills.env（含 7 个 SKILLS_REPO_* id），.gitignore 自动追加
末尾提示：跑 /skills-sync 推本地 skill 到各仓库

场景 C：新建项目文档目录

什么时候用：新项目启动时执行一次。monorepo 后不再创建独立仓库，只在 docs-site 下建子目录。

触发命令：

/docs-admin-init

关键输入：2 项 — 项目名称（全小写，如 pay-fi）/ 使用哪个 Group（推荐 .docs.env 中 GITLAB_DOCS_GROUP_ID，或 .skills.env 的 Group）。

产出结果（以 pay-fi 为例）：

本地 clone 的 docs-site 下 mkdir -p content/pay-fi/{requirements,contract,backend,tests,bugs,dashboard} 并放 .gitkeep + README.md 占位
更新 projects.json，追加 {"name": "pay-fi", "display_name": ..., "slug": "pay-fi", "order": N}
Commit + push docs-site main，CI 自动 build + deploy；~30 秒后 https://team-docs.pages.dev/pay-fi/ 出现
管理员 .docs.env 追加空 [pay-fi] section（仅 TELEGRAM_CHAT_ID= / LSKY_STRATEGY_ID=，不再需要 per-project ID）
可选：设置 Cloudflare Pages 环境变量 PROJECT_PASSWORD_{PROJECT_UPPER} 作为访问密码

SKILL.md 里的 Step 6-8（旧架构 trigger pipeline / {project}-docs 仓库注册）monorepo 后已废弃，skill 内部自动跳过。

场景 D：给新成员发 Token

什么时候用：新人入职、调换角色、首次加入某项目时。

触发命令：

/member-token-gen     # 交互菜单，选 1. create

关键输入：一次性表单 6 项 — 姓名（多人逗号分隔）/ 角色（1 pm / 2 frontend / 3 backend / 4 contract / 5 qa / 6 admin）/ 分配项目（已注册项目中多选）/ 技术水平（1 开发者版 / 2 非技术版；多人 bob:1,alice:2）/ Telegram 用户名（如 @bob_dev）/ 有效期（90 / 180 / 365 天或自定义）。

产出结果：每位成员自动创建 3 个 Token：

Token 名	权限	用途
`skills-common-{name}`	read_repository	拉 common skills
`skills-{role}-{name}`	read_repository	拉角色 skills
`docs-{name}`	api（在 `GITLAB_DOCS_PROJECT_ID=213` 下）	读写所有项目的 `content/{project}/**`

AI 输出按技术水平分发的配置清单：

开发者版：完整 .docs.env 文本块（含 GITLAB_DOCS_PROJECT_ID=213 / GITLAB_DOCS_WRITE_TOKEN={token_docs} / skills 两个 token + 项目段的 chat id / lsky strategy），直接粘贴
非技术版：中文三步指引（打开文件夹 → 粘贴配置 → /skills-install → 日常用 /pm 菜单），适合 PM 等非技术角色

同时 AI 会通过 Files API 把新成员追加到 docs-site content/manage/team.md（单一真相源，本地 .docs.env 不再保留 TEAM_MEMBERS）。

Token 仅此一次显示，关掉窗口就拿不回来了。务必通过加密消息/飞书私信发，不要贴群里。

批量模式（/member-token-gen --all）：从远程 content/manage/team.md 读取成员列表，一次性为所有已登记成员重新签发 3 份新 token，每人一个 /tmp/member-configs/{name}.env 文件 + 一条可直接贴 TG 的私聊消息。

场景 E：同步 skills 改动到 GitLab

什么时候用：你在本地 .claude/skills/ 改了/加了 skill，要让团队下次 /skills-install 能拉到新版。

触发命令：

/skills-sync

关键输入：推送范围 — 1 全部角色仓库（自动跳过无变更，推荐）或 2 只处理指定角色（common / pm / frontend / backend / contract / qa / admin，仅调试时用）。

产出结果：每个仓库独立处理 — clone 到 /tmp/skills-sync-{ts}/{repo}/（立即 scrub token）→ git pull --rebase（冲突 --abort 跳过）→ 按分配表从 .claude/skills/{skill}/ 拷过来 → 无变更直接跳 commit → chore(skills): sync {repo} from source {date} + push → 清理临时目录。末尾汇总表（✅ 已推送 / ⏭️ 无变更 / ⚠️ rebase 冲突 / ❌ push 失败）。

推完跑 /notify 选场景 12「Skills 工具已更新」，@全员提醒跑 /skills-install 更新。

场景 F：成员离职回收

什么时候用：成员离职 / 调换角色 / 调换项目时。越快越好，token 留着就是风险。

触发命令：

/member-token-gen     # 交互菜单，选 3. revoke

关键输入：成员姓名 + 吊销范围（1 全部 / 2 只 docs / 3 只 skills）。

产出结果：扫描所有 skills 仓库 + docs-site(213) 匹配 skills-*-{name} / docs-{name}，展示列表 → confirm → 逐一 DELETE。docs-{name} 命名保证只吊销该成员，不影响他人。离职后同步从 content/manage/team.md 表格删除该成员行。

场景 G：给老成员新增项目访问

什么时候用：老成员本来只在 pay-fi 工作，现在也加入 fomo-pad。

触发命令：

/member-token-gen     # 交互菜单，选 1. create，增量模式

关键输入：选择”只新增项目”选项，填成员姓名 + 新项目名。

产出结果：monorepo 架构下不需要新发 token（单 GITLAB_DOCS_WRITE_TOKEN 已覆盖所有项目）。AI 只输出一段项目段，让成员追加到自己 .docs.env：

[{new_project}]
TELEGRAM_CHAT_ID={chat_id}
LSKY_STRATEGY_ID={strategy_id}

这是迁移后最大的便利：老成员加新项目从”重发 3 个 token + 改 3 个文件”变成”追加 3 行配置”。

通用 skill 速查

全员通用 skill 的详细规则看 common.md。管理员视角最常用三个：

命令	管理员的典型使用场景
`/docs-push-gitlab`	管理员自己偶尔要推 `content/manage/team.md`（新成员入职时更新 roster）或 `content/manage/daily/` 时用；走的是管理员自己的 `GITLAB_DOCS_WRITE_TOKEN`（跑 `/member-token-gen` 给自己签发一次）
`/notify`	跑完 `/skills-sync` 发场景 12「Skills 工具已更新」，@全员提醒跑 `/skills-install`；新项目上线发场景 1
`/bug-add` + `/bug-update`	管理员虽然不直接 handle 业务 bug，但发现 CI / 文档站 / token 系统的问题时照样可以录 bug 跟进

常见问题 / 故障排查

Q1：/docs-site-init 可以多跑一次吗？

幂等的 — 仓库已存在会 400 然后查 id 继续，CI 变量已存在改用 PUT，Cloudflare Pages 已存在跳过。但没必要再跑一次，浪费 API 调用而且会覆盖你手动调过的 CI 变量。如果想改项目名或 CF Pages 配置，直接在 Cloudflare Dashboard / GitLab CI Variables 页面改。

Q2：新项目跑完 /docs-admin-init 后，Cloudflare Pages 需要重新配吗？

不需要。docs-site 是单仓库多项目，一套 Cloudflare Pages 项目 + 一条 CI/CD 流水线就够了。/docs-admin-init 只是在 content/ 下 mkdir 新子目录 + 更新 projects.json，push 后走同一个 .gitlab-ci.yml 自动 build + wrangler pages deploy --branch=main（必须带 --branch=main，否则只进预览环境不会刷新生产域名）。如果 30 秒过了站点还没更新，看 common.md FAQ 「rules.changes allowlist 不含 yaml」那条。

Q3：成员 Token 生成后丢了，能重新给他一份同样的吗？

不能。GitLab Project Access Token 明文值只在创建那一刻返回一次，丢了就是丢了。正确做法：

跑 /member-token-gen → 3. revoke，吊销该成员已丢失的 Token
再跑 /member-token-gen → 1. create，重新为他签发一套

刻意走 revoke 再 create 的原因：万一丢的 Token 被别人捡到了，revoke 把风险切掉。

Q4：/skills-sync 某个仓库卡在 rebase 冲突怎么办？

skill 自己 git rebase --abort 并跳过这个仓库，继续处理下一个。汇总标 ⚠️ rebase 冲突，已跳过。处理：手动 clone 该仓库，git pull --rebase 解冲突后 push，再重跑 /skills-sync。真正远程手动 commit（有人直接在 GitLab 改了 skills 仓库）才会冲突，正常工作流几乎不遇到。

Q5：某个 skill 只想推到一个角色仓库？

/skills-sync Step 3 选 2. 只处理指定角色，输入角色名（如 backend）。但 skill 的”归属角色”由分配表（skills-sync SKILL.md 内的 SSOT）决定 —git-commit 只在 SKILLS_REPO_COMMON、dev-backend 只在 SKILLS_REPO_BACKEND，“只推 backend”不会漏推。要改归属得先改分配表（本 CLAUDE.md、skills-sync/SKILL.md、skills-install/SKILL.md 三处同步）。

技术管理员操作手册

技术管理员操作手册

你是谁 / 本手册范围

首次配置

1. 初始化管理员 .docs.env

2. 生成 .skills.env（/skills-init 一次性）

3. 自检管理员必需字段

日常工作流

场景 A：一次性初始化文档站

场景 B：一次性初始化 skills 分发

场景 C：新建项目文档目录

场景 D：给新成员发 Token

场景 E：同步 skills 改动到 GitLab

场景 F：成员离职回收

场景 G：给老成员新增项目访问

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化管理员 `.docs.env`

2. 生成 `.skills.env`（`/skills-init` 一次性）