Cooling Planner

Cooling Planner v0.10 预览版

English | 日本語

一款浏览器应用，可在模型奶牛场中操作设备，并比较环境、奶牛散热以及水和能源的使用情况。它复用了 v0.4 的几何、物理和编辑功能，同时重建了屏幕与计算之间的连接。v0.9 新增了与设备变化联动的牛群平均代表日产奶量估算（假设模型 milk-heat-deficit-v0.1）。v0.10 新增了代表日逐小时天气（24 行）、按日汇总点位/面积，以及受约束的候选方案比较（compare_candidates）。

此代码库是从 Dairy Horizon 拆分出的独立版本。无需 FastAPI、API 密钥或父项目。 需要 Node.js 22.12+。首次运行：npm ci && npm run build，然后运行 npm start。 代码库同时跟踪源文件和构建后的发行文件；修改后请重新生成发行文件。

在线演示与分支

分支	UI 语言	托管演示（AWS Amplify）
english	英语	https://english.da05znjm47ziu.amplifyapp.com/
main	日语	https://main.da05znjm47ziu.amplifyapp.com/

english 分支是为海外黑客马拉松创建的，仅提供英文 UI（没有语言切换器）。两个分支的模型计算、保存格式和 MCP 词汇均相同；只有面向用户的字符串不同。每个分支在推送时都会自动部署到各自的 Amplify URL。下文引用的 UI 标签为英文；日文操作说明见 docs/README.ja.md。

快速开始

cooling-planner-v0.10.html 是一个包含 CSS、JavaScript 和计算工作线程的单文件。解压后，用桌面版 Chrome/Edge 打开即可。无需网络连接、登录或 API 密钥。如果浏览器拒绝打开本地文件，请使用下方的本地 HTTP 服务方式。

如需了解当前范围，请参阅 当前计划；如需了解验收标准与当前代码的对应关系，请参阅 验收标准。

产奶量计算规范见 热负荷 → 产奶量假设模型 v0.1；操作流程和验证见 实现计划 和 报告。已发布的 6 种条件产奶量表作为参考资料保存在参考屏幕中。

验证范围和结果记录在 独立验证记录 中。 并未检查所有公共 HTTPS、file:// 与真实 Chrome/Edge/Safari 的组合。

第一步（3–5 分钟）

屏幕是以牛棚为中心的 HUD。从底部停靠栏放置设备，在右侧面板中配置，并在底部抽屉中比较结果。首次运行时会显示简短指南（可跳过；可通过“？”帮助菜单重新查看）。

1. 等待初始计算完成。“Draft A”一开始是基线的副本，因此热损失变化量为 0 W 是正确的。
2. 在停靠栏中点击“Roof”，开启“reflective coating”和“20 mm insulation”。在 Feeding 7 时，局部空气温度从 36.5 → 33.0 °C，热损失改善约 +384 W。这些是模型计算出的数值。
3. 在停靠栏中按“Fan”，然后点击牛棚内放置新设备（按 Esc / Cancel 可取消）。点击现有风扇可选中并拖动；在右侧面板中更改高度和方向。拖动背景可旋转视图。“Undo”可撤销一项操作。
4. 在“Results & compare” → “Timeline”中查看 60 分钟的固定天气图表和播放功能。左上角的指标标签（亏缺 / 改善 / 风速 / 空气温度）可切换地面颜色。卡片和地面颜色均基于 60 分钟平均值。
5. 在“Results & compare” → “Reference impacts”中查看牛群平均代表日产奶量、与基线相比的变化量，以及受胎参考条件。“View published table”可显示产奶量参考表。
6. 在“Compare”中查看平均/最大亏缺、牛位/采食/等待区亏缺，以及与基线相比的用水量/能耗变化量。按下亏缺最高的位置可跳转到地面亏缺视图及该点的热损失分解。
7. 使用顶部的“Save”将设备摆放和条件保存为 JSON，并使用“Load”恢复。也可以通过“Compare”或“Settings & save” → “Import MCP scenario JSON”粘贴 MCP 场景 JSON。

如需了解 UI 改造计划和验证，请参阅 游戏风格 UI 实施计划 和 报告。

基线并非“没有设备”：它已有 10 台风扇 + 12 台喷淋器，且没有屋顶措施。Draft B 使用相同的风扇，喷淋器关闭、雾化运行。B 的热损失变化量为负，表示“比此基线更差”，而非“雾化没有效果”。

构建与测试

要求：Node.js 22.12+、TypeScript 5.8.3。3D 渲染使用 Three.js 0.180.0（作为 npm 依赖在构建时打包）。运行时不需要外部网络或 CDN。

npm ci
npm run typecheck
npm test
npm run build
npm start

npm start 会在 http://127.0.0.1:4173/ 提供 dist-offline；使用 PORT 更改端口。如果只想查看已构建的发行版，只需 Node 即可运行 npm start——无需 npm install 或重新构建。

构建输出：

• cooling-planner-v0.10.html：独立 HTML（旧版 cooling-planner-v0.9.html 也会保留）。
• dist-offline/：用于静态托管的 HTML/CSS/app.js/worker.js；请提供整个文件夹。

对于黑客松 PoC，Agent 侧验证包括类型检查、相关单元/集成测试和构建。E2E 和真实浏览器检查由人工和 CI 负责；只有在明确要求时，Agent 才会运行这些检查。

以下 E2E 流程供人工/CI 使用。浏览器测试使用 Python Playwright/pytest 和 Chromium；默认采用无头模式，无需 Xvfb。 将 CHROMIUM_PATH 指向现有的 Chromium，或省略该变量以使用 Playwright 管理的版本。 如需运行有头模式，请提供显示设备并设置 HEADLESS=0。

python -m pip install -r requirements-test.txt
python -m playwright install chromium
npm run build
npm run test:browser

默认情况下，独立 HTML 会以内联方式进行测试。在另一个终端中运行 npm start，然后运行 COOLING_PLANNER_URL=http://127.0.0.1:4173/ npm run test:browser 以测试 HTTP 版本。 在此设置下，即使 WebGL 不可用，相关测试仍会使用独立 HTML。

Python 参考实现：

(cd reference/thermal && python -m unittest -v)
(cd reference/fertility && python -m unittest -v)

node scripts/make-examples.mjs 会重新生成已验证的输入示例和集成计算结果。请先运行 npm run build。

MCP 与 WebMCP（外部 AI 客户端集成）

选择适用于演示的集成方式：

集成方式	用途	连接方式
WebMCP	操作显示的英文或日文公共网站，包括视图模式、All/Top/Side、旋转、平移和缩放	支持浏览器的 AI 客户端（例如 Codex）→ Chrome DevTools MCP → 已打开的网站；请参阅 WebMCP 设置
本地 MCP	操作一个本地提供服务的屏幕	stdio 服务端 + http://127.0.0.1:4174/?mcp=1；说明如下
远程 MCP	在不控制浏览器屏幕的情况下评估场景	托管的 Lambda MCP；请参阅 远程 MCP 连接

WebMCP 和本地 MCP 使用实时的浏览器端 ProjectStore，并共享屏幕的撤销历史记录。远程 MCP 则是独立的无状态计算服务。实现详情：本地 MCP 计划 和 WebMCP 报告。

本地 MCP：启动并连接

1. 在仓库内运行 npm ci && npm run build。
2. 在 AI 客户端中注册以下 stdio 服务（将路径调整为仓库的实际位置；等同于 npm run mcp）：

{
  "mcpServers": {
    "cooling-planner": {
      "command": "node",
      "args": ["/absolute/path/to/cooling-planner/scripts/mcp-server.mjs"]
    }
  }
}

对于 Devin CLI，在仓库内运行（注册到 .devin/mcp_config.local.json）：

devin mcp add cooling-planner -- node "$(pwd)/scripts/mcp-server.mjs"

3. 在单个标签页中打开 http://127.0.0.1:4174/?mcp=1。此模式下无需运行 npm start；MCP 进程也会提供 dist-offline。
4. 让 AI 调用 get_state。

这些工具分别是 get_state / edit / evaluate / compare_candidates / describe_model / set_view / get_results / undo，共 8 个。编辑会应用于当前情景，立即反映在屏幕上，并通过现有路径重新计算。人工屏幕操作和 MCP 操作共用同一撤销历史。

• evaluate：评估假设，但不更改屏幕。将与 edit 相同的操作作为数组传入；这些操作会按顺序应用于已提交状态的克隆，调用会返回情景的分区域汇总、资源、屋顶，以及（使用 includeDaily 时）每日牛奶数据和与基线的对比统计。由于它不会触及屏幕情景、设备、撤销历史或重新计算，因此探索“如果采取这项措施会怎样”或“赤字最多能降低多少”时，请使用此工具，而不是使用 edit→undo。

• compare_candidates：将 1–3 组候选操作列表分别应用于同一已提交项目的克隆，并返回每日结果（平均赤字、用水量、能耗、恶化点数）、约束判定和排名。候选项只能使用 update_device / update_system / update_roof；系数、天气、情景切换以及添加/移除操作均会被拒绝。排名仅在本次调用中有效。

• edit / evaluate 中的 add_device 可通过 x 和 y（两者均为必需项）在任意坐标放置设备。超出范围或位于实心区域的位置会报错。

• describe_model：返回模型的计算结构、输入/输出字段含义、主要假设常量、限制和验证状态。解读或说明数值前请先调用此工具（服务器指令中也有说明）。

• 也可通过 MCP 更改模型系数：update_model（物理参数：喷流扩散/衰减、对流换热、辐射偏移量、屋顶模型系数、profiles 敏感性假设集等）、update_milk（牛奶假设：Qref、beta、滞后权重等）、update_references（牛奶基线和受孕率参考值）。模型公式和版本标识符无法更改，超出范围的值会被现有验证机制拒绝。结合 evaluate，可在不触及屏幕的情况下比较不同系数下的结果。

• MCP SDK 为 @modelcontextprotocol/server 2.1.0（v2 系列），由 lockfile 固定版本。

• 未添加 ?mcp=1 时，不会启动本地 WebSocket MCP 连接。支持 WebMCP 时会自动注册其工具；?webmcp=0 可将其禁用。

• 服务和 WebSocket 均固定使用 127.0.0.1；第二个标签页的连接会被拒绝。身份验证、远程访问、多用户和应用内聊天不在 PoC 范围内。

• 如果端口 4174 正被占用，服务器会打印启动消息并退出。请勿同时运行手动启动的 npm run mcp 和由 AI 客户端启动的服务器。COOLING_PLANNER_PORT 可更改端口（浏览器会自动连接到已打开页面所用的端口）。stdio 客户端断开连接时，服务器会自动退出。

• 公式、系数和保存架构均未更改。

浏览器集成检查：设置 CHROMIUM_PATH + python3 -m pytest tests/e2e/test_mcp.py（驱动真实的 MCP stdio 会话并验证屏幕更改）。

WebMCP：操作已部署的屏幕

两个已部署分支均提供相同的 WebMCP 工具：英文演示 和 日文演示。 页面会针对实时的 ProjectStore 自动注册八个 WebMCP 工具：get_state、edit、set_view、get_results、undo、describe_model、evaluate 和 compare_candidates。无需查询参数。注册完成后，屏幕会显示 WebMCP 已就绪。在 HTTPS 托管的页面上即可使用，无需本地 Cooling Planner 服务或 WebSocket 中继。AI 会控制连接到其浏览器 MCP 的标签页；远程 Lambda MCP 则是独立的无状态计算服务。

WebMCP 仍处于实验阶段。请使用已安装的 Chrome DevTools MCP 支持的 Chrome 版本（其当前配置文档要求 Chrome 150+），并启用 --enable-features=WebMCP。启用 MCP 的 --categoryExperimentalWebmcp 类别。请参阅 Chrome DevTools MCP 配置和 WebMCP 调试指南。

对于 Codex，请在 MCP 配置中添加一个独立条目，或更新现有的 Chrome DevTools 条目，而不要针对同一浏览器启动两个 MCP：

[mcp_servers.cooling_webmcp_browser]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest", "--categoryExperimentalWebmcp", "--chromeArg=--enable-features=WebMCP"]

此配置会启动一个可见的 Chrome。如果要连接到现有的 Chrome，请使用 MCP 的 --browserUrl 选项，并在启动该浏览器时启用 WebMCP；--chromeArg 仅适用于由 MCP 启动的浏览器。Codex 进程和可见浏览器之间必须能够正常连接，包括使用 WSL 时。请参阅 Codex MCP 配置。

更新 MCP 配置后，重新启动 Codex 会话。让它打开上方部署的网址，列出页面的 WebMCP 工具，并首先执行 get_state。然后使用该响应中的 ID 执行 edit，并使用 {"sheet":"compare"} 执行 set_view。计算完成后检查 get_results；calculating 或 null 并不表示结果为零。describe_model 会说明模型假设。evaluate 和 compare_candidates 会在克隆对象上运行，不会更改屏幕。

set_view 还可控制 3D 摄像机，使用与屏幕按钮相同的「全部／顶部／侧面」取景方式：

操作	set_view 参数
标准 3D，全部	{"mode":"3d","realistic":false,"cameraPreset":"all"}
写实 3D，顶部	{"mode":"3d","realistic":true,"cameraPreset":"top"}
侧面	{"cameraPreset":"side"}
旋转 30° 并向上倾斜 10°	{"orbit":{"azimuthDeg":30,"elevationDeg":10}}
沿畜舍长度／宽度方向平移	{"pan":{"xM":2,"zM":-1}}
放大／缩小	{"zoomFactor":0.8} / {"zoomFactor":1.25}
设置绝对摄像机距离	{"camera":{"distance":30}}
2D	{"mode":"2d"}

摄像机操作需要 3D；从 2D 切换时，请在同一次调用中加入 "mode":"3d"。标准 3D 和写实 3D 均支持这些操作。组合参数按以下顺序应用：预设、绝对 camera、相对 orbit、pan，然后是 zoomFactor。相对手势会限制在屏幕范围内。绝对摄像机角度（azimuth、elevation）以弧度为单位，而相对环绕角度以度为单位；距离和目标 [x,height,z] 的单位为米。get_state().view.camera 会报告已应用的摄像机参数。这些操作会重绘视图，但不会更改模型输入或撤销历史记录。重复调用 orbit 会让摄像机逐步移动；目前没有提供连续动画工具。

不受支持的浏览器会显示 WebMCP 不可用，并继续支持正常的手动交互，不会弹出错误提示。?webmcp=1 仍是一个诊断别名，失败时也会显示提示；?webmcp=0 则会明确禁用工具注册及其状态徽标。注册支持当前的 document.modelContext API 和较早的 navigator.modelContext API。生成的离线发行版和独立 HTML 均包含此适配器，但预期的浏览器配置是使用通过 HTTPS 部署的网站。 实现详情、验证结果和手动验收清单：WebMCP 实现报告。

部署到 AWS

实施计划：docs/AWS_DEPLOY_PLAN.md。Amplify Hosting（静态网站；连接 GitHub，在推送到 main/english 时自动部署）+ Lambda Function URL（REST 和远程 MCP）。远程 MCP 是无状态、无需浏览器的变体；其工具包括 get_default_project / evaluate / compare_candidates / describe_model / get_doc（与本地版本使用相同的操作词汇）。

连接到远程 MCP

在 Kiro、Claude 或其他 MCP 客户端中注册以下内容。公共演示令牌 demo-581fKusGqNgk7YrycFNw6M_5 对所有人开放（如被滥用则会轮换）。私有管理员令牌位于 aws/deploy.local.json 中的 mcpBearerToken（不会提交）：

{"cooling-planner-remote":{"type":"http","url":"https://puzxplbkg2qglia72tkhs2z7km0jrusa.lambda-url.us-east-1.on.aws/","headers":{"Authorization":"Bearer demo-581fKusGqNgk7YrycFNw6M_5"}}}

cd aws && npm ci && cd ..
npm run deploy:aws   # site build → Lambda bundle → cdk deploy (Lambda backend only)

部署状态（Bearer 令牌、URL）存储在 aws/deploy.local.json 中（不会提交）。如有需要，CDK bootstrap 会在首次部署时自动运行。网站发布由连接 GitHub 的 Amplify 应用完成：推送时通过 amplify.yml 构建。

保存格式

schemaVersion: 10。保存位置、屋顶状况、天气（固定值 + 代表性日期的逐小时数据）、系数、参考模型假设、各设备每日启动时间、牛奶模型设置和视图设置。v8/v4 JSON 不经转换会被拒绝，并保留当前场景。请单独保留现有的 v8 正文和数据。

除了位置 JSON，也可以加载或粘贴顶层包含 project 的 MCP evaluate 响应 JSON。系统会验证 project 中的位置、天气、系数和基线，恢复这些内容并在屏幕上重新计算。收到的结果和哈希不会被信任用于显示。最大 2 MiB；支持的版本为 schema 10（v9 会自动转换）。

“Results JSON”是结合项目与计算结果的验证文件。对于小于 2 MiB 的文件，可以提取并恢复其中的 project；但由于文件包含结果，常规交换请使用位置 JSON 或 MCP 响应中的 project。

只要设备支持，就会使用设备端存储，但首次启动始终从标准演示开始。可在“设置与保存”中恢复设备端保存的数据。即使设备端存储不可用，场景 JSON 仍可使用。

分区域可视化

标准 3D / 写实 3D / 2D

使用牛舍上方的选项卡切换。经典渲染仍作为“标准 3D”，并共用设备位置、选定点和结果。 “写实 3D”新增钢构件、牛栏、地面材质、奶牛／设备几何模型、光照和阴影。无需额外下载。 绘制了类似荷斯坦牛的体型和大片斑纹，并呈现站立和休息姿势；50 头奶牛中有 3 头位于配有喷淋器的采食区。奶牛的位置和姿势仅用于装饰，不会改变评估点或占用设置。

• 拖动背景可旋转，滚动滚轮可缩放，按住 Shift 拖动或右键拖动可平移。
• 选择并拖动风扇／喷嘴，即可像在标准 3D 中一样编辑同一设备。撤销操作共用。
• “风”显示气流轨迹；“喷淋”显示喷淋水滴／雾粒。使用时间滑块检查 ON/OFF 运行状态。
• “地图”将现有结果叠加显示在地面上。“分析”会隐藏奶牛并显示热力图。
• “屋顶”显示屋顶的一侧。立柱和桁架会保持可见，以便检查内部结构。

风是基于风扇方向、模型扩散／衰减和障碍物生成的示意图。粒子轨迹并非 CFD。 粒子动画仅用于显示；它不会推进时间，也不会改写模型结果。 材质和形状均由代码生成——这不是摄影测量，也不是照片级的奶牛模型。 实现和验证详情请参阅写实 3D 实现记录。

实现了分区热量／降温可视化规范 v0.1。50 个牛栏面、12 个采食区面和 8 个候区面会按降温缺口（相对于 Qref 的逐秒积分平均值）、热损失改善量、风速和气温着色。点击一个面或表格行，即可选中其代表点，并显示湿润情况、热损失分项和设备动作诊断信息。每个面显示的是其代表点的数值，而非整个面的空间计算结果。schemaVersion 为 10。

模型覆盖范围

• 一个散栏牛舍模板、50 个牛栏、70 个独立评估点。并非 CFD，也不保证对真实牛舍的准确性。
• 热量和用水按固定天气条件计算 60 分钟，基础步长为 1 秒。回放显示预先计算的采样值。
• 日产奶量采用独立的代表日计算：固定天气条件重复 24 小时，经过 24 小时预热后，对一个 24 小时评估窗口进行汇总。包括每台设备每日的启动时间、运行时间、ON/OFF 周期，以及跨午夜保留的水膜。
• 体感气温、热损失改善量（W）、产奶量和受胎率是含义不同的指标。
• 日产奶量是基于 milk-heat-deficit-v0.1（demo_assumption）的牛群平均参考值。H=max(0,Qref−Q) 按 70 个点、各区域占用比例（相当于 14/6/4 小时）和时间加权，再根据滞后的 E 计算 Y=Y0−min(Y0×25%, beta×E)。这些系数并非文献中的回归值，其在实际农场中的准确性未经验证。
• 已发布的产奶量表仅涵盖 Zen-raku-ren 在静态条件下、RH 60–70% 时公布的 6 种条件。未列出的值为 null——不进行插值或外推。此表仅作参考。
• 受胎率是基于 5 个时期的 THI 区间和假设的基线受胎率计算的参考场景。初始值采用独立的代表性条件 26 °C / RH 70% 和 40% 的基线受胎率。不会根据设备自动推算总体受胎率改善值。
• 在参考页面上，只有勾选明确的选项后，才会将 60 分钟平均值应用于授精前 52 天的代表性条件。风扇／喷淋的热损失 W 绝不会转换为 THI。
• 存在一个接受各时期 THI 的函数，但首版 UI 只向所有时期提供一个共用的代表性条件。

文件指南

docs/IMPLEMENTATION_REPORT.md：重建的意图、实现、数值结果、验证情况和待处理事项。

docs/DECISIONS_v0_8.md：集成期间确定的实现约定。

docs/REUSE_MAP.json：逐文件与 v0.4 的对比及 SHA-256。

docs/evidence-v08/：拆分前 v0.8 实现的日志、屏幕截图和计算结果。

evidence/：测试时的输出目录。不会纳入 Git 跟踪。

reference/：用于交叉检查的原始 Python 模型和规范。

examples/：可加载的 schema-9 布置示例。

问题和独立仓库

• 反射涂层模型和牛奶参考资料问题：评估结果、敏感性检查、尚未实现的改进候选项。
• 拆分独立仓库：文件提取、独立构建/启动、Git init 流程。
• AGENTS.md：在此独立版本上工作的 Agent 的范围和验证规则。

在屏幕上检查由 MCP 构建的场景

1. 让 AI 使用现有的 MCP evaluate 计算场景；指定 includeDaily: true，以便核对每日资源。
2. 要求提供“evaluate 响应中的 project，保存为 JSON 文件”。如果客户端无法创建附件，请复制 JSON 正文。
3. 点击顶部的“Load”打开文件，或将正文粘贴到“Compare” / “Settings & save”下的“Import MCP scenario JSON”。也可以导入完整的响应 JSON。
4. 重新计算后，检查所选场景、布置、天气、每个区域的缺额以及水和能源。加载会恢复所有场景和共享条件，“Undo”会返回加载前的状态。无效 JSON 会保留当前场景。

对比均值是 70 个代表性点的简单平均值，不按畜群规模或占用情况加权。最大缺额是每个点 60 分钟平均缺额中的最大值。“缺额未减少”指缺额仍不小于基线的点；“无局部动作”是对局部设备动作的诊断（不包括屋顶措施）。某个点的热损失细分存在差异，是因为多个设备同时参与计算，而非各设备独立计算贡献。

MCP 场景恢复和对比实现报告记录了本轮的验证范围。更新源文件/发行包并将其部署到公开的 AWS 服务是单独的任务。

本轮手动检查（人工/CI）

1. 将 MCP 场景 JSON 粘贴到“Import MCP scenario JSON”，确认布置和屋顶条件已反映；确认“Undo”会恢复先前状态。
2. 在“Compare”中查看缺额均值/最大值、停滞/进食/等待情况、水和能源；点击一个缺额最高的位置，确认所选点及其热损失细分会随之切换。

专用 E2E 仅限 python3 -m pytest tests/e2e/test_mcp_comparison.py -v 中的 2 项测试。不执行 Agent 侧测试。