xiaoluolyg--god/CONTRIBUTING.zh-CN.md

🤝 为 GOD 做贡献

欢迎提 issue 与 PR。
_{无论是修一个错别字、加一张地图，还是重写一段 runtime —— 谢谢你。}

🌏 English

---

🧭 你可以怎么贡献

🐛 报 bug	提一个 issue，附上复现步骤、截图，以及 ./scripts/god.sh status 的输出。
💡 提需求	先提一个 issue，简短描述 + 一段使用场景就够。
🗺️ 加新地图	把文件夹丢到 agentsociety/custom/maps/<your_map_id>/，遵循 docs/MAP_PACKAGES.zh-CN.md。欢迎 PR。
🧪 加新实验	把文件夹丢到 agentsociety/quick_experiments/<your_hypothesis>/<your_experiment>/。参考 hypothesis_god_town/experiment_1/ 的形态。
✏️ 改文档	修翻译、打磨措辞、加截图、加图示。
🔌 接 Runtime	欢迎为新的 LLM runtime 或 persona 模板提 adapter PR —— 见 agentsociety/custom/agents/。

🚀 开发环境

git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start

会自动装好 Python 和 Node 依赖，启动完整栈，创建 live session，先跑完第 1 步， 让控制台打开时就是已初始化的小镇。改完代码刷新即可。

常用命令：

./scripts/god.sh restart    # 先干净停止，再重新启动
./scripts/god.sh new-run    # 清掉 replay 数据，开一个新 session
./scripts/god.sh status     # 查看端口、URL、模型状态
./scripts/god.sh tail       # 跟随日志
./scripts/god.sh stop       # 停止所有服务

🌳 分支与 PR 流程

1. Fork 仓库，从 main 拉一个 topic 分支。

2. PR 要 小而聚焦 —— 每个 PR 只做一件事。

3. 跑你改过部分的校验器：

   # 改过地图包
   cd agentsociety
   uv run python scripts/validate_map_package.py custom/maps/<map_id>
   
   # 改过 Python 服务
   cd agentsociety/packages/agentsociety2
   uv run pytest
   

4. 把 PR 提到 main。正文里写清楚 改了什么 和 为什么。UI 改动配上截图或短视频效果更好。

5. 耐心等等 —— reviewer 可能在另一个时区。

📝 代码风格

• Python: 4 空格缩进，必要的地方加类型注解，不要留无用 import。 目前没有强制统一 formatter，跟周围代码风格一致即可。
• TypeScript / React: 跟周围组件风格保持一致。
• 行宽: 合理的地方控制在 120 字符以内。
• 不使用前置声明（项目规则）。
• 注释 只解释非显然的意图，不要复述代码做了什么。
• Commit: 现在时、短主题（约 60 字符）、需要再加正文。
• 文档: 同时存在 .md 和 .zh-CN.md 的，改一个就两个都改。 请用地道的中英文，不要直译。

🗺️ 提交新地图包 · 检查表

• 目录名 agentsociety/custom/maps/<map_id>/
• 含 map.yaml、README.md、ATTRIBUTION.md
• Tiled JSON 包含 Collisions 层
• 所有图块素材路径都落在地图包内
• uv run python scripts/validate_map_package.py custom/maps/<map_id> 通过
• PR 正文至少附一张截图

🧪 提交新实验 · 检查表

• 目录在 agentsociety/quick_experiments/<hypothesis>/<experiment>/
• README.md（英文）+ README.zh-CN.md（中文）
• init/init_config.json + init/steps.yaml
• run.sh 能用 AgentSociety CLI 拉起实验
• 如果有操作员脚本，补一份手动运行说明（参考 PKU Trump 实验的模式）

📜 License

向 GOD 贡献内容，即表示你同意按 Apache License 2.0 授权你的贡献。 集成的上游代码（agentsociety/、jiuwenclaw/）各自保留了它们的 LICENSE / NOTICE， 对应子树仍受其约束。

🛡️ 友善些

GOD 是一个小型开源项目。请保持耐心、具体描述，给出你也愿意收到的那种反馈。 我们要做的是一座由 Agent 组成的小镇 —— 也希望围绕它，慢慢长出一个温暖的小社区。

---

_{谢谢你让 GOD 变得更好。⭐}