with one click
external-control-api
// 规划或实现面向外部 agent / Claw 的稳定控制 API,优先做底层分层、query/command 收口、runtime 串行化与契约文档,而不是零散补接口
// 规划或实现面向外部 agent / Claw 的稳定控制 API,优先做底层分层、query/command 收口、runtime 串行化与契约文档,而不是零散补接口
Use when working on tools/img_gen avatar image generation, OpenAI-compatible image API config, human or yaoguai portrait prompts, qi-refining base generation, image-to-image realm edits, white-background postprocessing, manifests, or prompt rules that preserve pixel-art identity while changing cultivation realms.
规划、实现或重构角色扮演模式(默认上帝视角下的单角色接管)时使用。适用于一期文本决策、二期统一有限选择框架、三期依附 Conversation 动作的自由对话,以及对应的 runtime/API/frontend/test 收口。
运行 Phase 2 工作流。执行脚本扫描缺失的多语言词条,并按注册表补全启用语言(如 en-US、zh-TW、vi-VN、ja-JP),最后修复相关测试。
国际化 (i18n) 开发指南。在添加新文本、创建物品/事件、修改翻译或管理 PO/MO 文件时使用。
运行项目测试(涵盖 Python 后端、Vue 前端及多语言校验)
创建包含正确远程处理的 Pull Request
| name | external-control-api |
| description | 规划或实现面向外部 agent / Claw 的稳定控制 API,优先做底层分层、query/command 收口、runtime 串行化与契约文档,而不是零散补接口 |
当任务涉及以下任一方向时使用本技能:
本技能的目标不是“快补几个 endpoint”,而是确保 API 方向具备长期可演进性:
src/server/main.py 中直接读写 game_instance 的路径?game_loop() / sim.step() 产生并发写 world 风险?优先查看:
src/server/main.pysrc/server/services/*.pysrc/sim/simulator_engine/simulator.pyweb/src/api/**/*.tsweb/src/types/api.tsdocs/specs/external-control-api.md.cursor/rules/external-control-api.mdc目标:
在改代码前先明确:
如果任务范围足够大,优先顺序应是:
不要反过来先加一堆 endpoint,再回头补底盘。
优先:
set_long_term_objectiveset_world_phenomenoncreate_avatardelete_avatarupdate_avatar_adjustment避免直接引入:
get_load_gameget_generate_custom_content_draftget_generate_custom_goldfinger_draftget_apply_runtime_content_localeget_configCONFIG 一直是最新对象。main.CONFIG 与当前配置模块中的最新 CONFIG,避免全量测试或数据根切换时读错目录。改动外接控制 API 时,优先同步:
docs/specs/external-control-api.mdREADME.mdAGENTS.md如果引入新规则或新的长期约束,记得同步 .cursor/rules/*.mdc 和仓库根 AGENTS.md。
至少考虑:
若涉及前端同步迁移,还应运行:
pytest
cd web && npm run test
cd web && npm run type-check
如果目标是尽快做出一个可用的 Claw / agent 控制 skill,优先按下面套路实现:
GET /api/v1/query/runtime/statusPOST /api/v1/command/game/startreinitGET /api/v1/query/world/stateGET /api/v1/query/eventsGET /api/v1/query/detailavatar/set-long-term-objectiveworld/set-phenomenonavatar/createavatar/update-adjustmentsrc/server/public_query_builders.pysrc/server/api/public_v1/query.pysrc/server/command_handlers.pysrc/server/api/public_v1/command.py