Stardew Agent Bridge

0.1.0 源码预览。2026-10-22 复核：46 项 Node 测试、17 项隔离 C# 检查、17 项安装脚本检查通过；真实游戏中的移动、箱子存取与去重、制作、放置，以及 Web 接管已验证。钓鱼/战斗、完整消费与跨日流程、三个真实宿主仍有待验收项。完整结果见 FINAL_TEST_REPORT.md，尚未发布稳定版 Release。

让任意本地 MCP Agent（DSH、Codex CLI、Claude Code……）观察并操作真实的星露谷游戏：一个 SMAPI Mod + 一个常驻本机 Bridge + 一个 Web 控制台，共用同一套游戏能力与同一份动作账本。

• MCP 接口只是连接方式：不依赖任何具体 Agent、不绑定任何模型厂商，也不需要任何专用插件。

• 所有写操作走游戏正常流程：没有传送、改钱、改物品、跳过剧情这类调试命令（代码里也不存在，不是隐藏起来）。

• 多客户端可同时观察，但同一时刻只有一个写者；玩家本人随时可以用热键或在网页上接管。

English: README.en.md

1. 结构

Agent 宿主（DSH / Codex / Claude Code）
   │  标准 MCP（Streamable HTTP，或 stdio 适配器）
   ▼
Bridge 常驻进程（127.0.0.1:17655）           ← 唯一业务核心 control-core
   ├── MCP 工具面（28 个 stardew_* 工具）
   ├── Web 控制台（状态 / 时间线 / 配置向导 / 人工接管）
   ├── 动作账本（SQLite：actionId 去重、终态缓存、未决动作）
   └── 控制权（控制会话 + 租约 + 写者独占）
   │  本机 WebSocket（127.0.0.1:17654，Bearer 令牌，协议 stardew-agent-bridge/1）
   ▼
SMAPI Mod（游戏主线程）                      ← 唯一执行者
   ├── 观察：地图 / 角色 / 背包 / 作物 / 商店 / 菜单
   ├── 动作：移动 / 使用 / 交互 / 菜单 / 买卖 / 制作 / 钓鱼 / 战斗 / 装卸存档
   └── 自保：控制权 epoch、失联即释放输入并尝试正常暂停、F9 紧急停止

关键设计：

Related MCP server: makmolga

2. 快速开始（Windows，单人存档）

前置：Windows 10/11、星露谷 1.6.15 + SMAPI 4.5.2、Node.js ≥ 22.5（用到内置 node:sqlite）。源码构建与隔离 C# 测试使用 .NET SDK 10；游戏 Mod 的目标仍为 net6.0，并引用你本机的游戏程序集。

1. 构建（同时生成 Mod 与 Web 产物）

   npm ci
   npm run build
   $env:STARDEW_GAME_PATH = 'F:\SteamLibrary\steamapps\common\Stardew Valley'  # 按实际路径
   npm run build:mod

2. 先启动一次 Bridge：它会生成 Mod 与客户端要用的本机凭据。

   npm start

   打开 http://127.0.0.1:17655/ 可以看到控制台。保持它运行。

3. 安装 Mod（游戏必须已退出；脚本会先备份旧目录）

   npm run install:mod

4. 启动游戏并加载存档：用 SMAPI 启动，日志里应出现 Stardew Agent Bridge Mod 已启动：ws://127.0.0.1:17654/。

5. 确认连接

   npm run doctor      # 应显示 Mod 连接=是
   node scripts/smoke.mjs

6. 接入你的 Agent 宿主：在网页的「连接其他 Agent 宿主」卡片里选宿主与传输方式，复制配置片段；也可以命令行输出：

   node apps/server/dist/cli.js hosts --host codex --transport stdio
   node apps/server/dist/cli.js matrix

   各宿主完整步骤见 docs/CLIENTS.md。

7. 想让 Agent 真正动手时，在网页上点「获取控制权」（或让 Agent 调用 stardew_session）；结束后点「释放控制权」或按 F9。

3. 工具面（28 个）

写工具统一接受可选 actionId（缺省由 Bridge 生成）与可选 controlSessionId（单活跃会话时自动推断，歧义时报 CONTROL_REQUIRED）。

错误码、effectKnown、nextAction（observe/query_action/stop/wait/restart_control/fix_environment/upgrade）定义见 docs/PROTOCOL.md。

4. 安全边界

• 只监听回环：Bridge 与 Mod 只绑定 127.0.0.1。Mod 拒绝带 Origin 的连接；Bridge 校验 Host 和本机 Origin，Web 写操作另需会话与 CSRF。

• 凭据本机化：令牌写在 %LOCALAPPDATA%\StardewAgentBridge\credentials.json（用户目录权限保护），不进仓库、不进日志、不进问题包；Mod 每次连接重新读取，轮换令牌不需要重启游戏。

• 写者独占：没有控制会话的写请求一律拒绝；租约到期、连接断开、换存档、人工接管都会让旧 epoch 失效。

• 结果不明就停：网络断开、超时、异常一律返回 unknown + effectKnown=false，指引 Agent 先查询/观察，不允许换新 ID 重放消费动作（同 actionId 不同参数会被 IDEMPOTENCY_CONFLICT 拒绝）。

• 没有调试后门：warp、resource、skipevent、diag 等命令在 Mod 协议与工具面都不存在；工具面里也没有任何"直接改存档"的入口。

5. 数据目录

%LOCALAPPDATA%\StardewAgentBridge（可用 SAB_HOME 覆盖）：

6. 开发

npm run build      # tsc -b + Web 类型检查 + esbuild
npm test           # 46 个测试（契约 / 控制权 / MCP HTTP / 故障注入），使用模拟 Mod
npm run test:mod   # 17 项真实 C# 控制源码隔离检查（不是游戏实测）
npm run test:installer # 17 项 Windows 安装与回滚检查
npm run clean
npm run pack       # 生成 release\StardewAgentBridge-0.1.0\（含 CHECKSUMS.txt；不会上传）

目录：packages/contracts（协议与工具定义）、packages/game-client（Mod WS 客户端）、packages/control-core（账本/控制权/动作服务）、packages/mcp（MCP 工具面）、apps/server（Bridge 进程 + /api/v1 + Web 静态）、apps/web（无框架前端）、adapters/stdio（stdio 适配器）、mods/StardewAgentBridge（C# Mod）、tests（模拟 Mod 与端到端测试）。

7. 验收状态

诚实说明（证据见 docs/EVIDENCE.md）：

8. 许可证与来源

MIT。迁移来源与逐文件差异见 NOTICE.md 与 docs/MIGRATION.md：上游 rottenpen/agent-stardew（MIT，commit d1f8934）的 Mod 与客户端代码被改造为独立的 Bridge 协议，不包含任何游戏本体资源、存档或凭据。