Stardew Agent Bridge

v0.35（程序版本 0.3.5，预览）：新增可选 AI 任务助手，提供 Windows / Linux x64 原生包、独立 Mod、Docker amd64 镜像与源码工具包。真实模型、完整游戏任务、Linux 游戏和双客户端联机仍待验收。见 更新说明 与 本版验证说明，历史单人验收保留在 FINAL_TEST_REPORT.md。

下载：v0.35 GitHub Release。每版提供校验和，按平台选取，不需要下载全部镜像。发行标签按项目命名为 v0.35，包名、Mod 清单和 API 使用规范版本号 0.3.5。

本版新增可选“AI 任务助手”：由 DSH、Codex 等主 Agent 派单，项目持续调用网页中配置的执行模型。此功能默认关闭，旧 0.2.0-preview.1 下载包不包含此功能。已通过自动化与部分隔离 Mock 浏览器检查，真实模型及游戏仍待验收。见 使用说明 与 独立复核报告。

历史首轮 Linux 验证记录保留在 LINUX_VALIDATION_REPORT.md，上一版验证见 2026-10-29 报告。本版验证以页首的 2026-11-01 说明及发行附件 RELEASE_MANIFEST.json 为准；历史检查不会自动证明新增功能可用。

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

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

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

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

English: README.en.md

给 AI 的游玩技能：stardew-player 包含有来源的攻略、MCP 执行流程与必须维护的短期/长期游玩日志。导入与使用；适用于 DSH、Codex、Claude Code 等主 Agent。本版已包含完整技能目录。

1. 结构

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

关键设计：

Related MCP server: Mine AI MCP

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

前置：Windows 10/11、星露谷 1.6.15 + SMAPI 4.5.2、Node.js ≥ 22.13.0（用到内置 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 宿主：点击网页顶部的「MCP 连接」，选择 DSH、Codex、Claude Code 或其他 MCP 客户端，填写连接名称并生成配置。可复制或下载 JSON/TOML；「检测本机 MCP 通道」会执行真实握手、工具发现和只读状态查询。将配置导入 Agent，再让它调用 stardew_status，即可在网页的「客户端最近调用」中看到记录。也可以命令行输出：

   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。

Linux 首版（源码预览，已完成无游戏首轮验证）

Linux 走同一套业务核心，差别只在宿主适配：发布包自带 Node 运行时、数据根走 XDG、Mod 安装/回退是事务化 MJS 脚本、菜单入口用 .desktop。

npm ci && npm run build
GAME="/home/$USER/.local/share/Steam/steamapps/common/Stardew Valley"
npm run build:mod -- --game-path "$GAME"
node apps/server/dist/cli.js start &      # 发布包内是 bin/stardew-agent-bridge start
npm run install:mod -- --game-path "$GAME"
npm run doctor

完整步骤见 docs/LINUX_INSTALL.md，规则与代码边界见 docs/LINUX_DEVELOPMENT.md，平台差异见 docs/PLATFORM_MATRIX.md。

3. 工具面（33 个）

写工具统一接受可选 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 协议与工具面都不存在；工具面里也没有任何"直接改存档"的入口。

• 可选执行器默认关闭：开启后由 Bridge 调用你配置的执行模型；密钥独立存放，执行模型只能使用政策允许的游戏工具，控制/派单/配置/存档/联机/文件工具永不暴露。人工停止（F9、网页接管）优先于模型回答。

5. 数据目录

Windows 默认 %LOCALAPPDATA%\StardewAgentBridge；Linux 默认 $XDG_DATA_HOME/StardewAgentBridge（未设置时为 ~/.local/share/StardewAgentBridge）。两者都可用绝对路径的 SAB_HOME 覆盖。

6. 开发

npm run build      # tsc -b + Web 类型检查 + esbuild
npm test           # 51 个测试（契约 / 控制权 / MCP HTTP / Web MCP / 故障注入），使用模拟 Mod
npm run test:mod   # 17 项真实 C# 控制源码隔离检查（不是游戏实测）
npm run test:installer # 17 项 Windows 安装与回滚检查
npm run clean
npm run pack       # Windows：生成 release\StardewAgentBridge-0.1.0\（含 CHECKSUMS.txt；不会上传）
npm run pack -- --target linux-x64 --runtime-root <含 bin/node 的目录>   # Linux：包内自带运行时
npm run verify:package -- <包目录>                                       # 仓库外隔离验证（HTTP + stdio）

Linux 上 npm run test:installer 运行 tests/scripts/install-rollback-linux.mjs（临时目录伪造游戏目录、含 SAB_FAIL_AT 故障注入）；Windows 上仍转发到原有 PowerShell 测试。

目录：packages/contracts（协议与工具定义）、packages/platform（数据根/权限/进程身份/桌面入口等跨平台能力）、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）、scripts/（Windows .ps1 与 scripts/linux/*.mjs，由 scripts/*.mjs 按平台分派）、tests（模拟 Mod、契约向量与端到端测试）。

7. 验收状态

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

8. 许可证与来源

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