全员通用操作手册

本手册是什么

这是一份面向**所有角色（pm / contract / backend / frontend / qa / admin）**的通用工具箱。各角色专属手册（如 pm.md / backend.md 等）会引用这里的章节，凡是全员都会用到的 skill 只在本文维护一次，不重复写。

本手册只覆盖通用 skill。与角色深度绑定的 skill（如 pm-docs-gen / dev-backend / qa-docs-gen）见对应角色手册。

环境准备

首次加入团队，按顺序完成两步即可开工：

1. 初始化本地配置 `/docs-init`

/docs-init

在当前项目根目录创建空的 .docs.env
自动把 .docs.env 和 .docs/ 追加到 .gitignore（含 Token，绝对禁止入库）
结束后，把管理员通过安全渠道发给你的配置整段粘贴到 .docs.env

.docs.env 顶层字段（monorepo 迁移后统一单 token）：

GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213           # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx   # 单 token，覆盖所有项目读写

MEMBER_NAME=your_name
MEMBER_TG=@your_tg

SKILLS_GROUP_PATH=skills
SKILLS_ROLE=frontend
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_ROLE_TOKEN=glpat-xxxx

TELEGRAM_BOT_TOKEN=...
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=...

[pay-fi]
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1

没有收到配置？找管理员跑 /member-token-gen。

2. 安装角色 skill 包 `/skills-install`

/skills-install

读取 .docs.env 的 SKILLS_ROLE / SKILLS_COMMON_TOKEN / SKILLS_ROLE_TOKEN
克隆 skills-common + skills-{你的角色} 到临时目录
自动复制所有 skill 到当前项目 .claude/skills/
完成后按提示重启 Claude Code 使 skill 生效

后续要更新 skill，原地再跑一次即可，幂等。

每天的基础操作

代码提交：`/git-branch` + `/git-commit`

新起分支 — /git-branch 按照 Git Flow 生成命名：

类型	格式	示例	源
feature	`feature/<role>-<nnn>-<desc>`	`feature/fe-001-login`	develop
release	`release/v<version>`	`release/v1.2.0`	develop
hotfix	`hotfix/<desc>`	`hotfix/wallet-connect`	main

role 缩写：fe / be / ct / qa。编号按角色自动递增（三位补零）。

生成提交信息 — /git-commit：

读取暂存区 git diff --cached，为空则直接拦截
按路径自动推断 scope（frontend / backend / contract / docs / config）
从分支名 feature/fe-001-login 自动提取 Task: FE-001
按 Conventional Commits 格式预览，y 确认后执行 git commit

发版与热修：`/release-flow`

PM 一般不涉及，后台 / 前端 / 合约 / QA 在正式发版或 hotfix 时使用：

a) 创建 release — 从 develop 切 release/v1.x.y，基于最新 tag 自动推 patch/minor/major，按 commit type 生成 CHANGELOG
b) 完成 release — 创建 MR 到 main（自托管 GitLab 是 MR 不是 PR），合并后打 tag，回合 develop，删 release 分支
c) 创建 hotfix — 从 main 切 hotfix/xxx
d) 完成 hotfix — 同 b 流程
e) 查看发布状态 — 当前分支、最新 tag、develop 领先 main 的 commit、活跃 release/hotfix

部署规则：develop 推送后 CI/CD 自动部署测试环境；main 合并后需在 GitLab Pipeline 手动审批到生产。

文档推送：`/docs-push-gitlab`

post-monorepo 新架构（2026-04-20）：所有项目文档合并进单一 docs-site 仓库（ID 213）。

单 token：顶层 GITLAB_DOCS_WRITE_TOKEN，不再按 [project] 段拆 token
路径前缀：本地 docs/{project}/{type}/... 推到远端 content/{project}/{type}/...
文档类型：1. requirements / 2. contract / 3. backend / 4. tests / 5. bugs

流程：

多项目场景先选项目（单项目自动用之），再选类型
列出本地 vs 远程差异：新增 / 变更 / 删除
并发冲突检查：对每个变更文件调用 Commits API 看最后提交人，若是 72 小时内他人修改，逐文件询问 y/n 是否覆盖
新增 → POST，变更 → PUT，删除 → 软归档到 content/{project}/_archive/{YYYY-MM-DD}/...（不硬删除）
输出推送摘要（新增几个 / 更新几个 / 归档几个 / 跳过几个）

Token 401 → 联系管理员重新签发；项目 404 → 检查 GITLAB_DOCS_PROJECT_ID=213；推送前先 /xxx-docs-pull 避免覆盖他人编辑。

成员日志：`/daily-log`

notify 每次触发时会自动在 content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md 追加一条日志。当天没跑 notify（研究日、开会日、阻塞日）或想补记漏掉的一条时，手动用 /daily-log：

/daily-log add   "{今日完成的描述}"
/daily-log plan  "{明日计划}"        # 覆盖"## 明日计划"小节
/daily-log block "{阻塞描述}"        # 覆盖"## 阻塞与问题"
/daily-log                           # 无参数 → 交互式三连问

通过 GitLab Files API 直接写 docs-site（ID 213）仓库，乐观锁 + 409 最多 3 次重试
不发 Telegram，仅追加日志文件
需要 GITLAB_DOCS_WRITE_TOKEN 非空；角色字段从 content/manage/team.md 实时拉取
PM 下班前跑 /daily-board（PM 专属）汇总当日所有成员日志 + 项目变化 → 生成 content/manage/daily/YYYY-MM-DD.md

团队通知：`/notify`（12 种场景）

所有推文档 / 部署 / 修 bug 完成后，统一用 /notify 发 Telegram 群，按角色自动 @mention：

#	场景	什么时候用	@mention 角色
1	需求文档已更新	PM 推 `requirements/` 后	contract / backend / frontend / qa
2	接口文档已更新	后台推 `backend/` 后	frontend / qa
3	合约文档已更新	合约推 `contract/` 后	backend / frontend / qa
4	测试用例已更新	QA 推 `tests/` 后	backend / frontend / contract
5	测试 Bug 文档已更新	推 `bugs/` 后（`/bug-add` 或 `/bug-update` 之后）	动态：diff 中涉及的 reporter_role + assignee role
6	后台已部署	后台部署到测试服 / 正式服	frontend / qa
7	前端已部署	前端部署到测试服 / 正式服	qa / pm
8	合约已部署	合约部署到测试网 / 主网	backend / frontend / qa / pm
9	后台 Bug 已修复	后台 hotfix/fix 分支修复并部署	frontend / qa
10	前端 Bug 已修复	前端修复并部署	qa / pm
11	合约 Bug 已修复	合约修复并部署	backend / frontend / qa / pm
12	Skills 工具已更新	管理员跑 `/skills-sync` 后	全员

通用规则：

同类别可多选（如 1,2），跨类别不允许
消息结尾固定追加 @hi_sam1369（PM 兜底）
发送前展示预览，y 确认才会真的发
每次调用成功后，自动往 content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md 追一行日志 + 可选刷新”明日计划 / 阻塞”

Bug 管理

录 bug：`/bug-add`

任何角色（QA / PM / 开发）发现 bug 都可以提。两种模式：

① 单条快速模板（默认）

标题: 充值成功但余额未刷新
步骤:
  1) 登录
  2) 点击充值 0.1 BNB
  3) 支付成功后返回
预期: 余额应自动 +0.1
实际: 余额仍为原值
关联: STAKE-FEAT-002

AI 自动解析字段，必需项：标题 + 实际
可用 cmd+V 粘贴截图，自动上传 Lsky Pro 图床（LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID），返回 URL 写入 bug 段
严重度（P0-P3）和负责角色（contract / backend / frontend）由 AI 预判，ok 全部采纳，或输入关键字覆盖（如 P0 backend）

② Excel 批量导入（用户回复 批量 触发）

自动生成 bug-import-template.xlsx 到项目根目录（含下拉约束、示例、说明 sheet）
填完拖回窗口 → AI 校验必填 + 去重 + 预览 → ok 批量写入
截图支持 WPS / Office 365「放置在单元格」功能，浮动图不可识别

所有 bug 写入 docs-site content/{project}/bugs/bugs.md，按”严重度 + 状态”排序，同时刷新 stats.md（每日 / 角色分布 / 修复效率 / 个人贡献 / 月度数据）。

改 bug：`/bug-update`

/bug-update BUG-007                              # 交互模式
/bug-update BUG-007 status=in-progress           # 单字段
/bug-update BUG-007 status=fixed assignee=Carol  # 多字段
/bug-update BUG-007 status=reopen                # 重开（自动跨档迁回）

合法状态流转：

open → in-progress → fixed → closed
             ↑          ↓
             └── reopen ┘       （closed 7 天后自动归档，reopen 会自动从 archive 迁回）

跳级流转（如 open → fixed）直接拒绝，按提示补中间状态
写入时也走乐观锁 + 3 次重试，冲突后重读文件重排
status 变 fixed / closed 时自动填 fixer / closer（当前 MEMBER_NAME），用于 stats.md 个人贡献统计

看 bug

首页活跃 Bug 卡片：https://team-docs.pages.dev/
项目看板：https://team-docs.pages.dev/{project}/bugs/board
单条详情：https://team-docs.pages.dev/{project}/bugs/BUG-XXX

录 / 改完成后标准三步走：/bug-add 或 /bug-update → /docs-push-gitlab（选 5. bugs）→ /notify（选场景 5 / 9 / 10 / 11）。

状态追踪：`/story-status`

项目级单一状态文件 content/{project}/status.md 替代旧 progress/ 目录，由 GitLab Files API 写入，本地零文件。所有角色都装 skills-common 后即可用。

列结构（固定 4 列）： 后台 / 前端 / QA / PM

每列允许状态（按列收紧）：

列	允许状态	前进序列（单调，不可跳）
后台 / 前端	`—` / `未开始` / `联调中` / `已完成`	`未开始` → `联调中` → `已完成`
QA	`—` / `未开始` / `测试中` / `已完成`	`未开始` → `测试中` → `已完成`
PM	`未开始` / `已完成`（永不为 `—` 也无中间态）	`未开始` → `已完成`

不涉及该角色填 —；PM 列永不为 —。

推进权限：

角色	推进哪一列	前置条件
backend	后台	无（自报：自测完成 → 联调中；联调通过 → 已完成）
frontend	前端	无（自报：自测完成 → 联调中；联调通过 → 已完成）
qa	QA	所有涉及的 dev 列 = `已完成`（dev 在联调中也不能进 QA），自报：开始测试 → 测试中；测试通过 → 已完成
pm	PM	QA 列 = `已完成` 或 QA 列 = `—`（QA 在测试中也不能进 PM；QA 缺位时兜底跨档加速）
contract / ops / 其他	拒绝	—

全员仅前进、不回退、不旁路。每次跑一档——例如 /story-status FEAT-001 US-01 第一次跑：未开始 → 联调中；第二次跑：联调中 → 已完成。状态报错只能由管理员通过 GitLab Web UI 手改 content/{project}/status.md。

命令语法（支持单 FEAT / 多 FEAT，每次推进一档）：

# 单 FEAT
/story-status FEAT-002 US-01                   # 单个，前进一档
/story-status FEAT-002 US-01,US-03,US-05       # 多个，各自前进一档
/story-status FEAT-002 all                     # 该 FEAT 涉及当前角色的所有 story 各前进一档

# 多 FEAT（pair 重复，按位置配对）
/story-status FEAT-001 US-01,US-03 FEAT-002 sub-01 FEAT-005 all
# 含义：FEAT-001 推 US-01/US-03、FEAT-002 推 sub-01、FEAT-005 推所有相关
# 单次 GET → 计算合并 diff → 单次 PUT → 一个 commit + 一次 CI（节省调度）

skill 自动 GET 远程 → 算 diff → 展示 ✏️ {当前档} → {下一档} → 等 y/N → 带 last_commit_id PUT。无任何 ✏️ 时直接退出零 PUT、零 CI 触发。

FEAT 总览状态聚合： 全员”已完成” → ✅；全员”未开始” → ⚪；其他（含联调中/测试中或混合）→ 🟡 进行中。

回退（--rollback + 强制原因）：

测试失败 / 自我修正等场景，状态可后退一档。命令：

/story-status FEAT-001 US-01 --rollback "测试发现登录返回 500"
/story-status FEAT-001 US-01,US-03 --rollback "联调接口数据格式错"

回退权限矩阵：

角色	可回退的列	典型场景
backend	后台	自我修正：发现做漏了，已完成 → 联调中
frontend	前端	同上
qa	QA + 后台 + 前端	测试不过打回 dev：dev 列已完成 → 联调中；自己列测试中 → 未开始
pm	后台 + 前端 + QA + PM	复盘发现需求理解错，回退任意列（最高权限）

回退规则：

后退一档（已完成 → 联调中/测试中 → 未开始）；不可跨档
必须带原因（引号内非空字符串）；commit msg 自动记录 rollback by {role}: {原因}
回退是破坏性操作，强制 y/N 二次确认
状态已是 未开始 → 跳过（无可再回退）

首次启用 / 历史回填： PM 在该项目目录跑一次 /role-split <任一 FEAT-id>，role-split 检测到远程 status.md 不存在时会自动扫描本地全部 FEAT 一次性 bootstrap，无需独立命令。

查看： team-docs.pages.dev/{project}/status（项目侧边栏 📊 项目进度）

部署脚本生成：`/deploy-gen`（前端 / 后台）

合约部署见合约手册。前端 / 后台部署到服务器只需跑一次：

/deploy-gen

填 5 个变量：SERVICE / BOT_TOKEN / CHAT_ID / REMOTE_PATH / DEPLOYMENT_DIR，直接生成 scripts/deploy.sh（含备份旧版、重载 nginx、Telegram 通知）并 chmod +x。后续部署用 bash scripts/deploy.sh 即可。

故障排查 FAQ

症状	原因	处理
`/docs-push-gitlab` 提示 401 / `GITLAB_DOCS_WRITE_TOKEN` 无效	Token 过期或被吊销	联系管理员跑 `/member-token-gen` 重签，粘贴到 `.docs.env` 顶层 `GITLAB_DOCS_WRITE_TOKEN=...`（不是 `[project]` 段内）
`/docs-push-gitlab` 提示 404 / project not found	`GITLAB_DOCS_PROJECT_ID` 错了	顶层保持 `GITLAB_DOCS_PROJECT_ID=213`（docs-site 仓库），不要填旧的 per-project ID
推 main 后 30 秒过了 `team-docs.pages.dev` 还没更新	`.gitlab-ci.yml` 本身变更不会自触发 CI（rules.changes allowlist 不含 yaml）	改完 yaml 手动去 GitLab 点 “Run pipeline”，或推任意 `content/**` 改动触发
`/bug-add` 截图上传 401	`LSKY_TOKEN` 失效	联系管理员拿新 `LSKY_TOKEN` / `LSKY_STRATEGY_ID` 替换 `.docs.env`
`/bug-update` 写入 “并发冲突过多，请稍后重试”	多人同时改 `bugs.md` 触发 3 次 `file_last_commit_id mismatch`	5 秒后重跑；已上传的截图 URL 保留不丢
`/notify` Step 8 跳过、提示 no `GITLAB_DOCS_SITE_WRITE_TOKEN`	旧配置残留（未迁移）	把顶层 `GITLAB_DOCS_WRITE_TOKEN` 补齐即可；TG 通知本身不受影响
`/daily-log` 写入失败落到 `.docs-outbox/`	连续 3 次 409 或网络问题	检查网络后重跑 `/daily-log`，或把 outbox 里的 md 手动贴回对应日期文件

下一步

角色	角色专属手册
PM	`guides/pm.md` — 需求收集 / 分析 / 拆分 / 角色文档 / 每日看板生成
合约	`guides/contract.md` — 合约需求复核 / ABI 文档 / 部署脚本
后台	`guides/backend.md` — 接口文档生成 / 后台开发流程
前端	`guides/frontend.md` — 前端开发流程 / 原型对齐
QA	`guides/qa.md` — 测试用例生成 / 冒烟 / 回归
管理员	`guides/admin.md` — 项目初始化 / 成员 Token 管理 / skills 分发

通用工具箱（本文档）学会后，按角色翻到对应手册即可上手专属流程。

全员通用操作手册

全员通用操作手册

本手册是什么

环境准备

1. 初始化本地配置 /docs-init

2. 安装角色 skill 包 /skills-install

每天的基础操作

代码提交：/git-branch + /git-commit

发版与热修：/release-flow

文档推送：/docs-push-gitlab

成员日志：/daily-log

团队通知：/notify（12 种场景）

Bug 管理

录 bug：/bug-add

改 bug：/bug-update

看 bug

状态追踪：/story-status

部署脚本生成：/deploy-gen（前端 / 后台）

故障排查 FAQ

下一步

1. 初始化本地配置 `/docs-init`

2. 安装角色 skill 包 `/skills-install`

代码提交：`/git-branch` + `/git-commit`

发版与热修：`/release-flow`

文档推送：`/docs-push-gitlab`

成员日志：`/daily-log`

团队通知：`/notify`（12 种场景）

录 bug：`/bug-add`

改 bug：`/bug-update`

状态追踪：`/story-status`

部署脚本生成：`/deploy-gen`（前端 / 后台）