feat: agent 能组帮派 + 群聊 (#17)

[vhankhan]

功能介绍

实现了帮派与群聊系统，包括以下功能：

核心功能

1. 帮派创建 - 玩家可以创建帮派，设置名称和格言
2. 成员管理 - 加入/离开帮派，查看成员列表
3. 帮派聊天 - 仅成员可见的群聊系统
4. 邀请系统 - 成员可以邀请无帮派玩家加入，被邀请者会收到闪烁黄光通知
5. 踢出功能 - 帮主可以踢出成员
6. AI 集成 - 帮派信息会出现在 AI 对话的 system prompt 中

前端特性

• 像素风格帮派面板 (☠️ 按钮)
• 三个标签页：所有帮派 / 我的帮派 / 成员列表
• 点击成员名字弹出操作面板（邀请/踢出）
• 新邀请闪烁黄光通知
• 待处理邀请列表（同意/拒绝按钮）

后端变更

• 新增表：gangs, gangMembers, gangMessages, gangInvites
• 新增 mutations: createGang, joinGang, leaveGang, sendGangMessage, inviteToGang, acceptGangInvite, rejectGangInvite, kickGangMember
• 新增 queries: listGangs, getGangDetail, getPlayerGangs, listAllPlayersWithGangStatus, getPendingInvites

验证结果

• ✅ bun test: 2 pass, 0 fail
• ✅ cd ai-town-fork && bun run build: 构建成功

文件变更

主要新增文件：

• convex/ours/tables/gangs.ts - 帮派表定义
• convex/ours/mutations/gangs.ts - 帮派 mutations
• convex/ours/queries/gangs.ts - 帮派 queries
• convex/ours/gangInputs.ts - 帮派 inputs
• ai-town-fork/src/components/GangPanel.tsx - 帮派面板组件

测试方式

1. 打开 http://localhost:5173/ai-town
2. 点击左下角 ☠️ 按钮打开帮派面板
3. 创建帮派或加入现有帮派
4. 切换到"成员"标签，点击成员邀请或踢出

AI 使用披露

工具 + 模型

Claude Code, GPT-5.4 thinking

反思

在使用 Claude Code 完成 Agent Town 修改的过程中，我对 AI 辅助编程有了几点深刻体会。
首先，提示词必须高度聚焦核心需求。我曾要求 AI 模拟登录流程，结果它自行下载了多个无关插件，不仅偏离了作业范围，还引发了后续一连串的兼容性问题。这说明与 AI 协作时，边界清晰的任务描述远比模糊的“锦上添花”更重要，否则极易引入不必要的复杂度。
其次，AI 在不同层次的表现差异明显。它在后端逻辑与数据表设计上执行力很强，但在前端 UI 呈现上非常薄弱——即便表格数据已就绪，它仍难以自主转化为直观的面板展示，需要开发者一步步指明调用关系。不过，AI 对用户逻辑的考虑上反而带来了惊喜：当我仅提出“踢出成员”时，它自动补充了“只有帮主可执行”的权限判断，这种对前后逻辑的细心补全，有效避免了设计漏洞。（说明AI对逻辑推理以及上下文联系的问题解决能力较强），未来我会更明确地向 AI 拆分任务：后端交给它深挖细节，前端则由我主导架构，取长补短。（文字由AI撰写，观点由我提供，我说的大白话太难懂）

###节选关键的prompt：

我的 prompt：请在 convex/ours/mutations/ 下新建 gangs.ts，参考已有 mutation 文件的写法，实现以下 mutations：

1. createGang: 参数 name、motto、worldId、founderId。检查同名帮派是否已存在；若不存在，插入 gangs 表，并将 founderId 自动插入 gangMembers。
2. joinGang: 参数 gangId、playerId。检查是否已是成员，若否则插入 gangMembers。
3. leaveGang: 参数 gangId、playerId。查找成员记录并删除。
4. sendGangMessage: 参数 gangId、senderId、content。先校验 senderId 在 gangMembers 中，再插入 gangMessages。

要求：

• 所有参数用 v.string()、v.id('gangs') 等做校验。
• handler 内用 ctx.db 操作。
• 先读取 convex/ours/mutations/ 下的现有文件作为参考。

我:
我希望在别人加入的时候组员的海盗图标闪烁黄光打开后出现同意或拒绝面板，并且在帮派面板添加一个列表里面有所有成员的名称，可以点击邀请他们到自己所在的帮派，
列表中成员名称的后面有他们的帮派身份（所属帮派或无帮派）（请先用ai玩家的名称搭建列表

AI:
完成！所有功能已实现。

新增功能总结

1. 闪烁黄光通知

• 当有新邀请时，帮派面板标题栏闪烁黄色 3 秒
• 显示"⚠ 新邀请!"提示

2. 同意/拒绝面板

• 在面板顶部显示待处理邀请列表
• 每个邀请有"同意"和"拒绝"按钮
• 处理后邀请自动消失

3. 成员列表

• 新增"成员"标签页
• 显示所有 AI 玩家名称 (Alice, Bob, Stella, Pete)
• 显示每个成员的帮派身份：
  • 👑 帮主 + 帮派名
  • ⚔ 成员 + 帮派名
  • 无帮派

4. 邀请功能

• 在成员列表中，可以点击"邀请"按钮
• 弹出邀请面板，显示所有无帮派的 AI 玩家
• 点击邀请后发送邀请

5. 新数据结构

• gangInvites 表 - 存储邀请记录
• inviteToGang mutation - 发送邀请
• acceptGangInvite mutation - 接受邀请
• rejectGangInvite mutation - 拒绝邀请
• listAllPlayersWithGangStatus query - 获取成员列表
• getPendingInvites query - 获取待处理邀请

AI 写的 vs 我改的

我:
我看到你加了成员这一栏，但是这些成员并没有可以被邀请的选项，我希望点击他们的名字后跳出邀请和踢出的选项面板

AI:
完成！现在功能已经更新：

新增功能

1. 点击成员名字弹出选项面板

• 在"成员"标签页中，点击任意成员会弹出操作面板
• 面板显示成员头像、名称和当前帮派身份

2. 邀请功能

• 如果该成员无帮派且你有帮派，显示"📨 邀请加入「帮派名」"按钮
• 点击发送邀请

3. 踢出功能

• 如果该成员是你的帮派成员，且你是帮主，显示"👢 踢出帮派"按钮
• 点击后有确认对话框，确认后踢出成员

我:
帮派的ui呢我需要它展示在游戏画面的左下角用一个海盗的图案作为进入帮派ui的按钮

AI：
好

我:
看到按钮了但是点击后没有打开页面，我需要你根据之前部署的功能设计一个面板展示出来，包括，加入帮派，帮派基础信息，创建
帮派，帮派聊天记录功能等等

AI：
好

我:
我看到了，现在的问题是跳转页尺寸不合适，超出游戏视图框边界导致无法全部展示了

AI：
好

我:
调到更小，且将帮派图案和面板换成和游戏画面一致的像素风

AI：
好

我：
点击ai玩家我发现他们的名字后面是空的 我希望在右侧他们的名字下面有标注他们的帮派名称，没有进帮派的写无帮派

AI：
好

AI 犯的错 / 我的 review 方法

我之前想让ai给我开一个暂时的账号可以测试使用功能，结果出现了很多节外生枝的问题

我：
我不想要这个功能了，能否将文件里为我占位的相关改写修改回原来的

修复成功！Vite 服务器已正常启动。

访问地址：http://localhost:5173/ai-town

---

问题总结：

1. convex/node_modules/ 中的符号链接指向了 bun 缓存目录（.bun/），但你用 npm/npx 运行
2. Tailwind 版本混乱：package.json 要 v3.3.3，但之前安装了 v4.3.0

已修复：

• 所有符号链接重新指向正确位置
• PostCSS 配置改回 v3 格式
• Tailwind 版本统一为 v3.4.19

我:
点击人物好像就会黑屏 这是不是和convex停止有关 查找并修复一下问题

AI:
● 修复完成！我添加了错误处理来防止黑屏。

修复内容

PlayerDetails.tsx (ai-town-fork/src/components/PlayerDetails.tsx):

1. 添加数据验证 - 确保 playerGangs 是数组类型：
   const playerGangs = Array.isArray(playerGangsRaw) ? playerGangsRaw : undefined;
2. 添加安全访问 - 使用可选链防止 null 错误：
   playerGangs.map((g) => g?.gang?.name ?? '未知').join('、')

---

现在请：

1. 刷新浏览器 - 访问 http://localhost:5173/ai-town
2. 点击人物测试 - 应该不再黑屏
3. 如果还有问题，请打开浏览器控制台 (F12) 查看具体错误信息

---

服务状态：

• ✅ Convex 后端: 运行中
• ✅ Vite 前端: 运行中 (http://localhost:5173/ai-town)

AI:

修复完成！

问题原因： ai-town-fork/convex/ours/queries/ 目录缺少 playerConversations.ts 和 playerReflections.ts 文件，导致 Convex 后端无法找到这些查询。

已修复：

• 复制了缺失的查询文件到 ai-town-fork/convex/ours/queries/
• 重新部署了 Convex 后端

---

现在请：

1. 刷新浏览器 - http://localhost:5173/ai-town
2. 点击人物测试 - 应该不再黑屏，能看到帮派信息

如果还有问题，请发 F12 控制台的新错误。

总结来说：
一些太过与主体无关的要求可能会让ai牵连很多无关的插件或更改进来，从而影响主体的运行，我要求他帮我模拟登录一个用户，他甚至给我下载了三四个不知名的插件…这导致后续不断有其他地方运行的问题出现。

git log 输出

$ git log --author='Agent Town Developer' --pretty=oneline main..HEAD
9ecb663 feat: add gangs and group chat (#17)

Checklist

• [勾] 我读了 AGENTS.md，特别是 §4 硬规则和 §7 已知 gotchas
• [勾] 没有提交 .env*、密钥、生产 deployment URL
• [勾] 没有直接 ctx.db.patch 修改 convex/aiTown/* 表（参见 AGENTS.md §4.2）
• [勾] 如改了上游文件：ai-town-fork/UPSTREAM_FILES.txt 加了 # EXEMPT: <reason>
• [勾] 已在 #1 作业登记帖 登记 PR 链接 + 学号 + 姓名（未登记不计成绩）