Johgee Open Irrigation

开源、AI 原生的英国家庭花园浇水建议。

v1 能把你已经掌握的信息 — 花园类型、土壤、日照、浇水方式、最近的降雨和土壤手感 — 转化为可解释的计划：毫米数、升数和计划运行时长。它不控制水龙头、定时器或灌溉硬件，也不确认你所在街道是否正在执行水管禁令。

数字建议来自有版本管理的确定性核心。语言模型可以解释这些内容，但不得修改毫米数、升数、运行时长、限制状态、变体 ID 或来源。

当前状态

公开数据模式在 D-01（2026-08-23）之后是动态启用的：输入邮政编码后，可以使用 Met Office DataHub 的 免费 Global Spot 天气数据源，并按粗略网格缓存。如果无法获取天气，API 就会回退到 manual 手动自报，绝不会编造毫米数。限制状态保持为 unknown；软管和喷灌建议在 v3 之前保持 默认关闭（fail-closed）。fixture 仅供测试。

Related MCP server: UK Weather & Travel Outfit Recommender MCP Server

当前可做的事

• 调用 POST /v1/recommendations 并传入 manual_context（无需邮编）。

• 可选发送英国邮编；天气数据按需获取，仅限免费层。

• 通过 MCP 工具运行同样的计算：calculate_watering（手动模式，无网络请求）和 get_watering_advice（可传邮编；只有当服务器有免费层 API 密钥时才获取天气）。

• 将 Theme 部分挂载到 Shopify 页面，或者打开本地电脑的演示页面。

• 阅读前几篇知识页面（HTML、JSON 和 JSON-LD）。

环境要求

• 使用 Docker 或者 pnpm 构建. The user mentioned Node.js: Actually Node.js 22.23.2

• pnpm 11.5.2（通过 Corepack）

确切的运行时版本会有一个在 .node-version 和 package.json 中。

快速开始

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm dev:api

API 监听在 http://localhost:8787。可以这样试用：

curl -sS http://localhost:8787/v1/recommendations \
  -H 'Content-Type: application/json' \
  -d '{
    "garden_type": "borders",
    "area_m2": 12,
    "soil_class": "loamy",
    "establishment": "established",
    "irrigation_method": "watering_can",
    "manual_context": { "recent_rainfall": "light", "soil_feel": "moist" }
  }'

响应头必须为 X-Header: manual。 fixture 响应头仅供测试。

本地规划页面：apps/public-web/watering-plan.html（指向本地 API）。

MCP

构建 stdio 服务器，然后把 Cursor 或 Claude Desktop 指向它。无需 API 密钥。

pnpm --filter @johgee/contracts build
pnpm --filter @johgee/irrigation-core build
pnpm --filter @johgee/ai-tools build

{
  "mcpServers": {
    "johgee": {
      "command": "node",
      "args": ["packages/ai-tools/dist/stdio.js"]
    }
  }
}

工具包括：calculate_watering（手动自报）和 get_watering_advice（英国邮编；天气按需获取，否则回退到同样的自报方式）。无效输入会返回结构化问题，不会由工具去造数。 技能草稿：packages/ai-tools/SKILL.md。

任何人拿到一个干净的克隆后，都应该能在十分钟内完成 MCP 工具的运行：安装依赖、创建上面三个包，再启动 stdio 服务器。

架构

Shopify page / MCP client
        │
        ▼
  Public API (Hono)  ──  MCP stdio (@johgee/ai-tools)
        │                         │
        └────────────┬────────────┘
                     ▼
           irrigation-core
           (pure functions)

• 商店前台：Shopify 页面 + Theme 部分（extensions/watering-planner）。

• 公开 API：https://api.johgeeirrig.co.uk/v1（CORS 允许 Johgee 店面）。

• 核心包：@johgee/irrigation-core — 不依赖网络、数据库或模型。

• 匿名分享链接 30 天后过期。Token 以哈希形式存储。

• 知识信息：apps/public-web/knowledge、llms.txt、sitemap、robots。

完整的英国邮编绝不能进入数据库、日志、链路追踪、本地存储或 Git 中。

仓库总览

apps/                     Local public-web demo
extensions/               Shopify Theme section
services/                 API
packages/                 Core, contracts, planner-ui, ai-tools, content
api/                      OpenAPI 3.1
schemas/                  JSON Schema
docs/                     Product, architecture, ADRs

贡献

请查看 CONTRIBUTING.md，也请阅读 SECURITY.md 和 GOVERNANCE.md。

许可证

Johgee 的代码使用 MIT 许可证。第三方数据和内容保留其原本的条款，使用或再分发前必须登记。

公开源码：github.com/hongzhizuo/johgee-open-irrigation。