阶段 3 — 可配置空间与角色(personas.yaml + locations.yaml)

📝 描述

阶段 3 — 可配置空间与角色。把阶段 1 (REQ-9d88acbf) 的硬编码 5 agent + 5 地点外部化为 YAML, 让产品运营 / 客户演示 / 创意策划改一个文件就换世界。 【功能模块】 1. personas.yaml — 智能体定义 - id / name / persona(年龄 + 职业 + 性格描述) / initial_location / color(画布圆点色) - 默认保留现有 5 个 (lisi/wangwu/zhangwei/liuna/chenlei) 作为 base.yaml 2. locations.yaml — 空间定义 - name / x / y / color(画布色块) / adjacency(双向连接列表, 影响 legal_targets + dialogue 触发概率) - 默认保留现有 5 个(李四家/王五家/客厅/厨房/公园)作为 base.yaml 3. 加载策略 - town bootstrap 读这两个 YAML,失败回退到 base.yaml + 警告日志 - 通过 TOWN_DATA_DIR 环境变量切到自定义配置目录(空 = 默认 5+5) - MVP 不做热重载,改 YAML 重启生效 【API 影响】 - /api/agents 返回的 id/name/location 来自 YAML,前端透明 - /api/agents/{id}/status 的 persona 字段读自 YAML - bootstrap.py 改 read_personas() + read_locations() 两个函数 注入 World.snapshot 的 legal_targets 也从 YAML 计算 【验收标准(初版,待 brainstorming 细化)】 1. 编辑 personas.yaml +1 个 agent (zhaomin/32 岁设计师),locations.yaml +1 个地点 (咖啡馆),重启 town → /api/agents 返 6 个含 zhaomin,前端画布显示「咖啡馆」色块。 2. locations.yaml adjacency 把「客厅」邻居从「厨房/李四家」改为「厨房/咖啡馆」 → LLM 决策返回 go_to 咖啡馆 通过合法性校验(world.apply_action 不拒绝)。 3. personas.yaml 故意配错 id 重复(zhaomin 出现两次) → town 启动报 friendly error,服务不挂(回退 base + warn 日志)。 【复用资产】 - town bootstrap.py 已有 personas 解析代码,扩展即可 - virtual-world-engine DEFAULT_LOCATIONS 改为 read_locations() 加载,保持 API 兼容 - agent-runtime AgentFactory 已经 name+persona 构造,直接传 YAML 读出的 dict - canvas.js LOCATIONS const 目前 hardcoded,改造为 init 时从 /api/agents 派生 【MVP 不做 — YAGNI】 - Web UI 增删改(独立 P2/P3 需求) - YAML 热重载(必须重启) - 节点冲突严格校验(只做基础 id 重复检查) - 向后兼容旧配置格式(直接 breaking,YAML 是新格式) 【成本预估】 - 改 YAML 重启 town:0 增量成本,沿用现有 path - 单 tick LLM 决策:人数/地点数变化影响 prompt tokens,YAML 一般 5-10 人,边际成本 < ¥0.5/天 - 单测:fake loader 注入测试 YAML,无需真实 bootstrap ## 关联 引用 REQ-9d88acbf(阶段 1,complete 2026-06-29)的硬编码 5+5,本 REQ 外部化为 YAML。后续 REQ-378ef1e0(导演控制台 P2)在 #1 基础上扩展导演维度,#2(自定义剧情 P2)依赖 #1 提供可配置空间。

👤 用户故事

作为产品运营,我希望改一个 YAML 就换 agent 阵容和地图拓扑(人数/名字/性格/邻接关系)而不必改代码,从而给不同客户演示不同世界。

✅ 验收标准 (1 项)

1. Given 编辑 personas.yaml +1 个 agent(zhaomin)+ locations.yaml +1 个地点(咖啡馆)
   When 重启 town + GET /api/agents
   Then 返 6 个含 zhaomin,前端画布显示咖啡馆色块

🏷️ 标签

ai-agent-virtual-life stage3 custom-config yaml ext-of:9d88acbf

🔄 推进状态