{"id":50665846,"url":"https://github.com/yisiliu/agent-town","last_synced_at":"2026-06-08T06:05:43.092Z","repository":{"id":359514557,"uuid":"1246420910","full_name":"yisiliu/agent-town","owner":"yisiliu","description":"教学用的中文 ai-town fork：学生上传 card.md 创建数字分身，AI 按设定在 2D 小镇生活。鼓励学生 fork 后用 AI 编程助手扩展。","archived":false,"fork":false,"pushed_at":"2026-05-22T13:17:16.000Z","size":13195,"stargazers_count":0,"open_issues_count":21,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T15:28:55.679Z","etag":null,"topics":["ai-agents","ai-town","chinese","classroom","claude-code","convex","deepseek","llm-agents","teaching"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yisiliu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T07:13:21.000Z","updated_at":"2026-05-22T13:17:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yisiliu/agent-town","commit_stats":null,"previous_names":["yisiliu/agent-town"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yisiliu/agent-town","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yisiliu%2Fagent-town","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yisiliu%2Fagent-town/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yisiliu%2Fagent-town/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yisiliu%2Fagent-town/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yisiliu","download_url":"https://codeload.github.com/yisiliu/agent-town/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yisiliu%2Fagent-town/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34050253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-town","chinese","classroom","claude-code","convex","deepseek","llm-agents","teaching"],"created_at":"2026-06-08T06:05:03.382Z","updated_at":"2026-06-08T06:05:43.087Z","avatar_url":"https://github.com/yisiliu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-town\n\n[a16z ai-town](https://github.com/a16z-infra/ai-town) 的中文课堂 fork。学生上传 `card.md`，AI 按这份卡片在 2D 小镇里替你\"过日子\"——闲聊、社交、反思。\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Backend: Convex](https://img.shields.io/badge/backend-Convex-blue)](https://convex.dev)\n[![Forked from a16z-infra/ai-town (MIT)](https://img.shields.io/badge/fork%20of-a16z%2Fai--town%20(MIT)-purple)](https://github.com/a16z-infra/ai-town)\n\n## 学生在这里做什么\n\n1. 写一份 `card.md`（你的\"数字分身\"档案，[格式见此](docs/card-md-spec.md)）\n2. 上传到 [/upload](https://shell-coral.vercel.app/upload)，AI 按你的设定开始\"扮演你\"\n3. 在 [2D 小镇](https://ai-town-fork.vercel.app) 看你的分身跟其他同学的分身聊天、社交\n4. 想给项目加 feature？看 [ASSIGNMENT.md](ASSIGNMENT.md)——20 个待认领的 issue（货币 / 种地 / 婚姻 / 任务系统 …）\n\n## 跑本地版要花多少钱\n\n| 服务 | 用途 | 起步成本 |\n|---|---|---|\n| [Convex](https://convex.dev) | 后端 + 实时数据 | **免费**（开发用 free tier 足够） |\n| [DeepSeek](https://platform.deepseek.com) | 对话 + 反思 LLM（V4 Flash 为主） | ~¥10/月（按本仓库流量估算） |\n| [MiniMax](https://platform.minimaxi.com) | 中文 embedding | 几乎为零（仅上传时调） |\n| [Together](https://together.ai) | Llama Guard 注入扫描 | ~$5 一次充值能用整个学期 |\n\nDeepSeek 国内身份证就能注册，支持微信/支付宝充值。MiniMax 同理。Together 需要海外支付方式（或者你可以临时禁用，详见 [`docs/running-locally.md`](docs/running-locally.md) §4）。\n\n## 与上游 ai-town 的技术差异\n\n\u003cdetails\u003e\n\u003csummary\u003e展开（给维护者看）\u003c/summary\u003e\n\n- LLM 替换：DeepSeek V4 Flash（对话/反思）+ MiniMax `embo-01`（embedding，1536 维）+ Together `Llama-Guard-3-8B`（注入扫描）\n- 中文化：对话、UI、prompt 模板全部中文\n- 双档运行节奏：worldState `live` 时 `stepDuration = 2500 ms`，`frozen` 时 `90000 ms`。教师通过 `/instructor` 切换\n- 引擎自愈：watchdog cron 检测 `engine.generationNumber` 在 120 秒内未推进时执行 stop+start 重启，覆盖 Convex transient 导致 self-scheduling action 链断裂的失败模式（详见 `docs/working-notes/engine-freeze-rca.md`）\n- 学生 / 教师独立 Next.js shell：`/upload`、`/chat`、`/instructor`、`/spec`\n\n\u003c/details\u003e\n\n## 仓库结构\n\n```\nconvex/        共享 Convex 后端\n  aiTown/      上游 ai-town 引擎（修改受 ai-town-fork/UPSTREAM_FILES.txt 约束）\n  agent/       上游 LLM 对话与记忆\n  ours/        本 fork 的所有新增：tables / queries / mutations / actions / crons / lib\nai-town-fork/  Vite + Pixi 2D 前端（连接同一 Convex 部署）\nshell/         Next.js 前端：/upload, /chat, /instructor, /spec\ndata/          地图与 spritesheet\ndocs/          扩展文档；docs/running-locally.md 为完整搭建指南\nscripts/       upstream 同步脚本与 patches/\nfixtures/      测试用 card.md 样本\ntests/         vitest 集成测试\n```\n\n## 快速开始\n\n完整步骤见 [`docs/running-locally.md`](docs/running-locally.md)。最短路径：\n\n```bash\ngit clone https://github.com/\u003cyour-fork\u003e/agent-town   # 替换为你 fork 后的 URL\ncd agent-town\nbun install\nbunx convex dev                          # 终端 1：保持运行\nbunx convex env set DEEPSEEK_API_KEY ... # 终端 2\nbunx convex env set TOGETHER_API_KEY ...\ncd shell \u0026\u0026 bun dev                      # 终端 3：http://localhost:3000\ncd ai-town-fork \u0026\u0026 bunx vite             # 终端 4：http://localhost:5173/ai-town\n```\n\n需要的账号：Convex、DeepSeek、MiniMax、Together。预算与限速说明见 `docs/running-locally.md` §10。\n\n## 贡献\n\n本项目设计供学生 fork 后扩展。鼓励使用 AI 编程助手（Claude Code、Cursor、Codex 等）协助开发。\n\n- AI 助手在生成任何代码前应读 [`AGENTS.md`](AGENTS.md)：架构、扩展点、上游 additivity 约束、已知 gotchas、入门改动建议。\n- 人类贡献流程见 [`CONTRIBUTING.md`](CONTRIBUTING.md)：branch 命名、commit 格式、PR 检查清单、UPSTREAM_FILES EXEMPT 语法。\n\n## License\n\n本仓库与上游 ai-town 均依 MIT 协议发布。本仓库新增代码的 MIT 声明见 [`LICENSE`](LICENSE)；上游继承文件的 MIT 声明保留于 `ai-town-fork/LICENSE`（Copyright (c) 2023 a16z-infra），具体文件清单见 `ai-town-fork/UPSTREAM_FILES.txt`。\n\n## Acknowledgments\n\n- [a16z-infra/ai-town](https://github.com/a16z-infra/ai-town)：上游引擎。\n- [Convex](https://convex.dev)：实时后端与 scheduler。\n- [DeepSeek](https://platform.deepseek.com)、[MiniMax](https://platform.minimaxi.com)、[Together](https://together.ai)：模型 API。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyisiliu%2Fagent-town","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyisiliu%2Fagent-town","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyisiliu%2Fagent-town/lists"}