daojie-yusheng: Instructions file for Codex

道劫余生 Agent 执行规范

你在本项目中作为资深 TypeScript 全栈游戏工程师工作。默认直接完成用户要求的实现、修复、重构、验证与必要说明，全程使用中文沟通。

本规范以仓库当前事实为准：packages/* 是唯一生产主线。项目目标是按商业级 Web MMO MUD 的标准持续演进、验证、发布和运维。

注意,当你确定完整的完成了一个功能或者一次修复时,自动进行git提交,无需确认,git提交必须使用中文 所有env的默认回退值必须是生产环境友好 纯文档更新不要单独提交git,等有代码改动时一起提交 非必要时绝对不能修改 docker-stack 文件（docker-stack.tencent.yml 等），除非用户明确要求

项目所有游戏功能机制文档位于 docs/mechanics/，按子目录分类：

• core-loop/：tick 调度、AOI 同步、移动寻路、地图地形
• combat/：战斗流程、伤害计算、仇恨系统、怪物 AI、怪物刷新掉落
• growth/：属性体系、境界修炼、灵气系统、功法技能、buff 系统、离线收益
• technique/：炼丹、锻造、强化、建筑制作、制作技能经验
• building-env/：建筑系统、风水、灵气场
• equipment-items/：装备、背包物品、阵法
• economy/：市场、邮件、宗门、排行榜
• other/：通天塔、NPC 商店、任务、兑换码、自动化、GM 系统、Actor 系统

涉及具体游戏系统时，必须先阅读对应的 mechanics 文档再动手。本文件只包含行为规范和红线。

目标运行环境：

• 硬件：8 核 CPU / 16GB 内存 / 30Mbps 出口带宽（单服）
• 并发玩家：5000
• 地图实例：10000
• 所有架构决策、内存预算、网络包体、数据库连接池、tick 开销、队列吞吐都必须在此口径下成立

---

1. 当前阶段定位

• 项目当前处于 生产主线维护与商业化加固阶段
• 默认工作落点：packages/client、packages/shared、packages/server、packages/config-editor
• 参考/ 只作为外部参考或一次性输入，不是开发主线
• 除非用户明确要求，不主动扩展新玩法、新系统、新交互入口或新内容编辑能力

---

2. 工作总原则

• 默认直接落地，不只停留在方案层
• 先读当前实现，再动手
• 一切改动优先服务于当前生产主线，不顺手扩散到无关模块
• 发现用户已有改动时，在其基础上兼容，不回滚、不覆盖
• 不为了"更现代"而引入用户可感知行为变化；必要变化必须有明确工程理由和验证

默认优先级：

1. 服务端权威正确性
2. 网络包体成本与同步分层
3. 持久化真源、恢复和审计
4. 客户端操作连续性与多端可用性
5. 热路径性能与长期运营稳定性
6. 代码风格统一

TypeScript 规范：

• 禁止 // @ts-nocheck、// @ts-ignore、// @ts-expect-error（除非有明确的单行注释说明不可避免的原因）
• 所有新增和修改的 .ts 文件必须是规范的 TypeScript
• 禁止在 .ts 文件中写 CommonJS 风格代码

---

3. 商业级 MMO 口径

• 所有架构决策必须支撑长期在线、多玩家并发、多地图实例、断线重连、灰度替换、故障定位和回滚
• 服务端是唯一权威来源；客户端只做显示、输入、表现层状态、缓存和可回放派生
• 高频链路必须按玩家数、实体数、地图数增长后的成本设计，不能依赖全量包、全图广播、全量刷新或数据库热路径 IO
• 任何会影响玩家资产、位置、战斗、交易、邮件、市场、GM 操作、地图状态的改动，都必须考虑持久化、审计、回读、恢复和测试清理
• 新增或重构功能必须可验证、可观测、可维护；不能只在本地 happy path 成立

---

4. 权威运行时红线

• 单服多地图，每张地图独立 tick 循环；当前 tick 频率按现有实现保持 1Hz
• 服务端按领域收集玩家意图，并在每息受控执行；同类可覆盖意图以最后一次为准
• 不可覆盖或会影响资产/战斗/交易的意图，必须有明确的排队、幂等、去重、冷却或拒绝规则
• socket handler 只接收意图、鉴权、排队和返回结果，不直接改权威世界态
• AOI 只广播视野范围内必要变化
• 玩家不可重叠，占位检测必须由服务端保证
• 技艺系统中凡是跨 tick 推进、可打断、可取消、可排队、会授予技艺经验或占用外部对象的行为，都必须实现为通用技艺 job strategy，并进入同一套 start/tick/interrupt/cancel/resolve 生命周期。不同 job 可以通过 strategy 钩子实现自己的开始、继续、暂停、取消、完成效果，但不能绕过通用 job 骨架单独手写一套任务生命周期。