aiworkdb

团建游戏库 · 开发指南（经验总结 + 新内容 SOP）

面向后续开发新游戏 / 新线路 / 新文章的开发者（人或 AI）。 前两轮（剧本杀×综艺）+ 本轮（桌游团建）共 18 款新游戏、9 篇文章、3 个工具的完整经验沉淀。 最后更新：2026-10-13

---

一、铁律：团建主线，不做纯游戏开发

这是用户明确的定调，所有内容必须围绕「团队提升」展开：

• ❌ 不做：玩法介绍 + 规则搬运 + 「这个游戏真好玩」
• ✅ 要做：这个游戏能练什么团队问题 → 怎么编排进团建流程 → 复盘怎么引导 → 迁移回什么工作场景

判断标准：删掉团建章节后文档是否还成立？如果只剩规则说明，方向就错了。

---

二、新游戏开发 SOP（七步）

Step 1 选题与查重（最容易被跳过、代价最高的一步）

1. slug 查重：新线路选款前，先列出候选，与全库比对 slug/别名：
   • ls games/*/ 全部已有游戏 md 文件名
   • ls ../boardgames/category/*/（若与桌游库联动）——78 款桌游中 33 款已有团建改造版，初版 6 款全撞车被删过，血泪教训
2. 能力矩阵查空缺：优先选「团队能力」还没有覆盖的款。12 能力域见 play/tools/capacity-picker/index.html 内的数据注释；用能力域 × 已有游戏数找空格
3. 能力映射互不重复：同批选出的游戏，核心能力锚点不能撞车（本轮 6 款分别锚定估值/需求理解/优先级/专业互信/观察举证/决策机制）

Step 2 写文档（标准十章节结构）

团建指南型（外链规则库）：概览表（含外链完整规则+printables）→ 团建核心价值 → 90/60/45 分钟团建流程编排表 → 引用要点 → 复盘三问 → 4F 框架 → 培训主题 → 人数场景适配 → 物料打印 → 教练笔记

独立游戏型：参照 games/collaboration/virus-outbreak.md 标杆结构

硬性要求：

• 「团建核心价值」必须用标准列表格式 - **短词**：说明（冒号用全角 ：，短词 ≤10 字、去 emoji），索引靠它提取能力标签
• 复盘三问 + 完整 4F（每步带时长和定制问题，不是模板复述）
• 培训主题每款 2-3 个，按游戏定制（关键词+适用场景+迁移重点）
• 踩过的坑：老游戏措杂小节会污染标签提取——新游戏一律放标准章节，别自创节名

Step 3 生成链路（三条命令，按序）

cd /Users/gaodun/code/aiworkdb.github.io/teambuilding
python3 md2html.py          # md → html（含新游戏）
python3 gen_index.py        # 重建 index.html（卡片/分类/标签）
# README 索引表补一行（含团队能力列）

• 脚本已修复 Windows 硬编码（用 Path(__file__).parent），别再写死绝对路径
• gen_index.py 常见雷区：f-string + .format() 双处理会 KeyError（模板去掉 f 前缀）；标签提取窗口必须有小节边界检测

Step 4 工具联动

• play/tools/capacity-picker/、materials/、plan-generator/、variety-wheel/ 数据内嵌游戏清单——加新游戏后必须跑 python3 tools/sync_capacity_picker.py 与 python3 tools/sync_play_tools.py，否则这几个工具选不到新游戏
• 新工具注册：play/index.html 的 CATEGORIES 数组加一行
• 路径坑：从 play/tools/X/ 链到游戏文档用 ../../../games/（三层，不是 ../../——那指向 play/games 的 H5 游戏）

Step 5 公众号文章（全链路六件套）

1. 选题：清单/避坑型钉周五（138 型，阅读量最高）；单品篇放周一/周四
2. 写 md 到 wechat/articles/<系列>/（1100-1300 字，对照 01-公众号文章模板.md）
3. 转换：BASEDIR=wechat/articles/<系列> python3 convert_to_wechat_html.py（或参照既有编排）
4. 封面：ImageGen 生成 → strip_watermark_and_crop.py 裁 900×383
   • 坑：make_cover 永远取 raw/ 里 mtime 最新的文件——多个封面一次跑完会全用同一张图。逐款隔离源图再裁
5. 生成 manifest.json
6. CTA 标准话术 + 游戏库数量：数字变了要全局 grep 老文章批量刷新（58→68→74 已刷三轮），用词精确匹配避免误伤（如「58 岁」≠「58 款」）

Step 6 日历与账目

cd wechat
python3 calendar_guard.py backup && python3 calendar_guard.py check
# 改 02-选题与发布日历.md（排期 + 进度总览加总）
python3 verify_calendar.py   # 必须全绿

• 排期数据规则：清单型 138×158、单品 98/105
• 进度总览公式变了要同步改 verify_calendar.py；skip 前缀白名单按需追加
• 历史 \--- 转义污染出现过两次，新写注意

Step 7 校验清单（发布前全绿）

• 索引卡片数 = 游戏 md 数，每个分类图标正常
• 新游戏全部有「团建核心价值」标准列表（能力标签提取得到）
• 新 HTML 全部生成（老 md 改过也要重跑）
• 文章字数 1100-1300、无禁用词
• 日历 verify 全绿、进度总览加总正确
• 工具 JS 语法 OK（node --check）、内链全部可解析
• CTA 数字与全库实际数量一致

---

三、踩坑经验库（按事故类型归档）

3.1 数据一致性

| 坑 | 后果 | 对策 | |—|—|—| | 选款前不做 slug 查重 | 6 款文档全部重做 | 先查重再动笔（Step 1） | | 价值章节格式不统一 | 标签提取失败/漏标签 | 强制 - **短词**：说明 标准格式 | | 能力标签归类审计草率 | 5 个漏归类 + 2 个幽灵标签 | 归类后反向校验：每个标签都能映射回域名，且域名在游戏数据中真实存在 | | 老文章 CTA 数字滞后 | 读者看到旧数量 | 数量变更即全局 grep 刷新，精确词匹配 |

3.2 文本批量处理（AI 高发区）

| 坑 | 后果 | 对策 | |—|—|—| | heredoc 内传全角字符（：） | 正则审计结果自相矛盾 | 用 COLON='\uff1a' 构造字符；以最终产物为 ground truth 验证 | | 全文件批量替换编号列表 | 有序步骤被误转 36 条 | 行级状态机限定小节内转换；动手前 git 留还原点 | | 正则窗口固定长度 | 渗漏到后续小节提取垃圾标签 | 匹配到下一个 ## 或 --- 截断 |

3.3 生成链路

| 坑 | 后果 | 对策 | |—|—|—| | 脚本硬编码 Windows 路径 | mac 上一跑全挂 | Path(__file__).parent | | f-string + .format() 双处理 | KeyError 崩溃 | 模板去掉 f 前缀 | | make_cover 取 mtime 最新 | 多封面全同一张图 | 逐款隔离源图文件再裁剪 | | zsh nullglob + && 链 | glob 不匹配时命令整串短路，raw/ 被误清空 | 批量文件操作前先 cp 备份到 raw_hold/ 一类目录 | | 工具页相对路径少一层 | 游戏链接 404 | play/tools/X/ → ../../../games/ |

3.4 发布运营

| 坑 | 后果 | 对策 | |—|—|—| | 推箱前 IP 白名单未更新 | 40164 全线瘫痪 | 家宽 IP 变了先更新公众号后台白名单 | | 整系列批量推箱 | 一篇失败全链卡住 | SINGLE_NAME 逐篇推 | | 日历进度总览手工改数 | verify 不一致报红 | 改完必跑 verify_calendar.py |

---

四、能力域 × 选款矩阵（12 域速查）

沟通表达 / 团队协作 / 信息与决策 / 信任关系 / 领导管理 / 创新创意 / 目标与计划 / 抗压与危机 / 观察与推理 / 破冰热场 / 复盘与成长 / 商务与客户

• 新游戏选题时：按域查已有款数 → 优先填空缺域
• 文章选题时：一个域可出一篇清单文（如「销售团建只推荐这 3 款」= 商务与客户域）
• 每款游戏锚定 1-2 个主域即可，别贪多——锚点分散=没有锚点

---

五、后续开发方向建议（按优先级）

1. P0 · 填空缺能力域：用 capacity-picker 数据看哪些域款数偏少，定向补款
2. P1 · printables 体系扩展：桌游指南型的物料打印目录是外链，可逐步把高频物料做成本地 printables
3. P1 · 场景化方案包：把「新员工入职 / 管理层工作坊 / 销售激励」等场景 × 游戏编排固化成可下载方案（guide.md 五场景表是雏形）
4. P2 · capacity-picker 数据源统一：目前工具内嵌数据是快照，游戏数量再增长应改为构建时从 games_data.json 生成
5. P2 · 暂不做（用户已明确）：CI/CD、Lint/Format、模板市场/导入导出、协作深化

This site is open source. Improve this page.