nalog-agent

NaLog 🌾 [](https://github.com/khawtech/nalog-agent/actions/workflows/ci.yml) [](LICENSE)  > 我的岳父在的稻田里孤独地去世，他正在检查水位。<br> > 数百万泰国农民仍然每天都在做同样的事情——在40°C的高温下步行数公里，只为了检查水泵是否仍在运行。<br> > 在上一季，我们在某个家庭的稻田中部署的AWD传感器减少了31%的抽水量，而产量没有损失。<br> > 每个传感器都能减少一次步行。<br> > **黑客马拉松的资金直接用于传感器和LoRa网关。** **NaLog 代理**是一个**Qwen-powered MemoryAgent**，它将那些传感器转化为针对小规模稻米和甘蔗农民的个性化、记忆化的农业建议——一个农民口袋里的农艺专家。<br> 它建立在 **Alibaba Cloud**（模型工作室/Qwen，函数计算，表格存储，DashVector）之上，位于 [NaLog / KhawTECH](https://nalog.khawtech.com) 物联网灌溉平台之上 **生产系统 - 不是黑客马拉松原型。** 这是部署在曼谷（`ap-southeast-7`）的Alibaba Cloud函数计算上的同一个泰国伊桑的服务。<br> 处理实时对话、传感器数据和泵命令。<br> > 这里包含的演示模式使用捆绑的数据集，因此任何人都可以本地运行它——生产路径只有一个`STORAGE_DRIVER=alibaba`命令。 **黑客马拉松赛道：**道 1 - MemoryAgent** （主要提交）。同一个代码库还包括一个警报Webhook（`api/alerts`），可以为**赛道 - Autopilot Agent** 资格，但该项目被注册为MemoryAgent。<br> 查看[赛道 1 理由](#track-1-rationale)。 > **由 [Alberto Roura](https://albertoroura.com) 构建** — **Alibaba Cloud MVP**，连续 8 年（2018-2026 年）<br> > 以及 **2019 年 Alibaba Cloud MVP** （在 MVP 全球峰会上全球颁发）。<br> > Apsara 会议组织者和共同演讲者（涵盖 Alibaba 的 Hanguang 800 AI 芯片发布）以及 **Qwen VIP**。<br> > 这个项目技术使命：让世界级的 Alibaba Cloud农民无法承受。 --- ## 为什么存在 KhawTECH 在小农户农民的田地里提供经济实惠的 AWD（交替湿润和传感器。<br> 传感器会产生数据——但原始数据并不是建议。<br> 良好的农业指导必须**记忆**：<br> *这* 片稻田在重新平整后排水更快，*这* 位农民更喜欢在开花附近手动批准水泵，*去年* 在这里，AWD 将抽水减少了 31%，而没有产量损失。 NaLog 每个农民口袋里的农艺专家。<br> - **积累经验**，每个农民和每块稻田，跨会话和季节。 - **检测矛盾** - 当学习提取的事实与现有的记忆（相似度 0.50-0.相冲突时，一个廉价的LLM仲裁决定新的事实是否取代旧的。<br> 旧记忆被保留以便审计，但不被召回。<br> 参见 [基准测试](docs/BENCHMARK.md)。 - **及时遗忘** - 记忆随着年龄的增长而衰减，并通过表格存储TTL物理过期，除非它们持续被证明是有用的（强化）。<br> 衡量，而不是声称：参见[可复制的基准测试](docs/BENCHMARK.md)。 - **安全救援底线** - 关键记忆（强化 >= 5）始终在召回结果中浮现，即使它们的得分低于前K个截止点。<br> 确保安全关键知识（例如“在开花期间保持洪水”）永远不会在无关查询中被遗忘。 - **在微小的上下文窗口中回忆** - 4层混合召回：向量优先的前K个（DashVector + `qwen3-rerank`交叉编码器）+ BM25启发的关键词重叠 + 近期衰减 + 强化评分，然后总结——因此它适用于离线优先，低带宽的农村部署。 - **看到实地** - 附加照片，`qwen3-vl-plus`状况，水，害虫和杂草到推理循环中。 - **自主行动，但绝不盲目** - 传感器警报触发未提示的推理回合（`POST /api/alerts`）；任何泵动作都是一个*提案*，由人类批准；只有然后才会发送 LoRaWAN 下行链路。 - **流式传输其工作** - Qwen 思考，实时工具调用和回复的 SSE 流式传输，因此农民可以观看代理检查实时传感器。<br> 包括一个**内存跟踪**（哪些内存被召回，它们的分数，什么被排除）和一个**内存差异**（“2 个新，1 个强化，1 个取代”）在每个回合后。 - **互操作** - 相同的功能作为 **MCP 服务器** 暴露，因此任何 MCP 客户端（Claude，Cursor，其他代理）都可以使用 NaLog 的工具。<br> 参见[从任何MCP客户端使用](#use-it-from-any-mcp-client)。 **评委：** 从 [`docs/JUDGE-GUIDE.md`](docs/JUDGE-GUIDE.md) 开始，2分钟概述。 ## 架构  查看 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 获取完整设计和 [4层混合内存模型](docs/ARCHITECTURE.md#memory-model)。 ## 使用的Alibaba Cloud服务（部署证明） | 服务 | 用途 | 代码 | |---|---|---| | **模型工作室（Qwen）** | 4层模型路由：`qwen3.7-max` （思考，工具使用）· `qwen3.6-plus` （泰语/英语NLG）· `qwen3.6-flash` （内存提取）· `qwen3-vl-plus` （田间照片）；SSE流式传输 | [`dashscope.js`](src/llm/dashscope.js)，[`tools.js`](src/agent/tools.js) | | **模型工作室（嵌入）** | 语义内存向量（`text-embedding-v3`） | [`embed()`](src/llm/embeddings.js) | | **模型工作室（重排）** | `qwen3-rerank` 交叉编码器重新排序召回的记忆 | [`rerank.js`](src/llm/rerank.js) | | **表格存储** | 持久化内存（配置文件，会话式记忆，带有TTL，会话，提案）；`BatchGetRow` 召回热路径上的点查找 | [`tablestoreStore.js`](src/memory/store/tablestoreStore.js) | | **DashVector** | 向量优先的语义回忆过去的田间经验 | [`dashVector.js`](src/memory/vector/dashVector.js) | | **函数计算 3.0** | 无服务器后端（ZIP自定义运行时，无ACR） | [`fc-zip-build.sh`](deploy/fc-zip-build.sh)，[`fc-deploy.mjs`](deploy/fc-deploy.mjs) | 裁判的单一文件后端证明：[`docs/proof-of-alibaba-deployment.md`](docs/proof-of-alibaba-deployment.md)。 ## 快速入门（本地，Docker） ```bash cp .env.example .env # 添加您的DASHSCOPE_API_KEY（模型工作室） docker compose build docker compose run --rm app npm run seed # 播种演示农民的记忆 docker compose up #localhost:8080 ``` 默认情况下，完全离线可用：`STORAGE_DRIVER=local`，`VECTOR_DRIVER=local`，`NALOG_USE_DEMO=true`（内置Kut Chum，Yasothon演示农场）。<br> 只需要一个模型工作室API密钥即可与Qwen对话。 捆绑的Web聊天界面（`public/ `）流式传输代理的工作（思考→工具调用→回复令牌），显示每个答案的可展开工具跟踪，渲染泵提案的批准卡片，允许您附加田间Qwen-VL），并具有显示代理记住的内容的内存面板（带有强化计数器）。<br> 尝试询问（泰语或英语）： - *"นาแปลง 3 ตอนนี้ต้องสูบน้ำไหม?"* ("现在Paddy 3需要抽水吗？") - *"What's the water level in Paddy 3 and what do you recommend?"* 代理读取（演示）传感器趋势，回忆过去，并 - 如果有意义的话 - 显示一个**批准卡片**。<br> 批准它会发送LoRaWAN下行链路（除非配置了`CHIRPSTACK_*`）。 模拟自主警报路径（传感器警报→未提示的代理回合→提案）： ```bash curl -X POST http://localhost:8080/api/alerts -H 'Content-Type: application/json' \ -d '{"paddyId":"paddy-rice-3","metric":"water_level","value":-16.2,"unit":"cm","threshold":-15,"direction":"below"}' ``` ## 在Alibaba Cloud上部署生产环境 此存储库是 **相同的代码库**，在KhawTECH的生产环境中运行。<br> 通过更改驱动程序环境变量，从本地开发切换到生产环境： 1. 配置存储：STORAGE_DRIVER=alibaba`，`VECTOR_DRIVER=dashvector`和`.env`中的`_*` / `DASHVECTOR_*`： ```bash docker compose run --rm app npm run provision 2. 包并部署到函数计算（基于ZIP的-不需要容器ACR）： ```bash npm run deploy:build # 构建dist/nalog-agent-fc.zip（Linux node_modules通过Docker） npm run deploy:fc # 创建/更新FC函数+HTTP触发器 ``` 函数计算和表格存储在泰国`ap-southeast-7`（曼谷）默认运行。<br> DashVector和模型工作室在那里不可用，因此它们通过HTTPS到达其新加坡/全球端点。 3. 在线部署端到端进行烟雾测试： ```bash BASE_URL=https://<your-fc-trigger>.ap-southeast.fcapp.run npm run smoke:deploy ``` 4. （可选）以真实农民的身份打开实时Web UI - 铸造短期Firebase ID令牌并获取可打开的URL（需要`.env`中的`FIREBASE_WEB_API_KEY`和`local/firebase-service-account.json`处的服务帐户JSON）： ```bash BASE_URL=https://<your-fc-trigger>.ap-southeast-7.fcapp.run \ node scripts/firebase-test-token.mjs <farmer- 生产环境中，KhawTECH NaLog农民仪表盘通过函数计算HTTP触发器后端，转发 ID令牌以进行身份范围限定。 完整步骤： [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)，[`deploy/fc-zip-build.sh`](deploy/fc-zip-build.sh)和[`deploy/fc-deploy.mjs`](deploy/fc-deploy.mjs)。 **仅部署依赖** （本地开发或测试不需要）： ```bash npm install --no-save @alicloud/fc20230330 @alicloud/openapi-client @alicloud/tea-util ``` ## 从任何MCP客户端使用 代理的能力作为 **MCP服务器** 通过stdio公开，因此Claude Desktop，Cursor或其他代理可以直接驱动NaLog - 相同的工具处理程序为应用内ReAct循环和MCP提供支持（一个实现，两个界面）。 ```bash docker compose run --rm app npm run mcp # 在stdio上提供MCP docker compose run --rm app node scripts/mcp-smoke.js # 使用真正的MCP客户端进行验证 ``` 暴露的工具（全部9个，与ReAct循环相同）：`get_farm_overview`，`get_paddy_status`，`get_sensor_history`，`recall_memory`，`save_memory`，`update_profile`，`get_irrigation_history`，`analyze_field_photo`（Qwen-VL），`propose_irrigation`（人工干预）。<br> 实现： [`src/mcp/server.js`](src/mcp/server.js)。 **Cursor / Claude Desktop** - 添加到 `.cursor/mcp.json` 或 `claude_desktop_config.json`： ```json { "mcpServers": { "nalog-agent": { "command": "node", "args": ["src/mcp/server.js"], "cwd": "/path/to/nalog-agent", "env": { "DASHSCOPE_API_KEY": "sk-your-key", "MCP_FARMER_ID": "your-user-id" } } } } ``` `MCP_FARMER_ID` 将所有内存范围限定为特定用户。<br> 如果没有它，则使用演示农民。<br> 设置 `NALOG_USE_DEMO=true` （默认）以使用捆绑的农场数据，或将 `NALOG_API_URL` 指向您自己的平台。 ## 在其基础上进行构建 这是一个 **开源，MIT许可** 的MemoryAgent，旨在让农业技术构建者、合作社、非政府组织和为农业社区提供服务的开发人员进行扩展。 - **[集成指南](docs/INTEGRATION.md)** - 三种路径：MCP仅内存，全MCP或平台替换。 - **[连接器API参考](docs/CONNECTOR-API.md)** - 您的平台需要实现的REST合同（带有示例有效载荷）。 - **可交换存储** - `local` （JSON文件）用于开发，`alibaba` （表格存储+ DashVector）用于生产。<br> 通过在集成指南中记录的存储/向量接口实现您自己的驱动程序。 ## 测试，CI ```bash npm test # 125个测试，取代，巩固评分，安全，存储，向量，工具，身份验证，代理循环，流式传输...） npm run check # 启动应用程序端点 npm run bench 复制的内存检索→ docs/BMARK.md + 图测试完全（演示模式密钥，无外部服务盖： | 区域 | 测试 | |---|---| | **内存** | 4层回，向量优先的水分补充，关键词评分，强化，衰底线，整合，清除+孤立向量清理，优雅的回退 | | **取代** | LLM仲裁检测矛盾，取代标记旧记忆，召回排除取代的，审计保存，失败处理 | | **内存学习** | 自动转折后提取（模拟LLM），按文本和语性进行重复数据删除，矛盾取代，差异处理 | |** | 过期内存压缩为摘要后清除，LLM失败元数据保存内存跟踪** | `recallWithTrace` 返回候选/取代/营救计数，Context` 暴露跟踪，`memory_trace` SSE事件发出 | 代理循环** |ReAct轮工具执行，合成，提案，事件流式传输，每个回合跨会话内存，`memory_diff事件 | | **身份验证** | API密钥门，Firebase ID令（签名，到，观众，，算法混农民范围 | 路由** |聊天验证，SSE流协议，图像验证警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警警报Webhook，警报所有权+生命周期，提案所有权+生命周期 | | **路由** | 内存，警报Webhook，提案所有权+生命周期 | | **存储/向量** | 配置文件CRUD，会话式列表，`getEpisodicByIds` 查找，TTL过期，插入/查询/删除，过滤器，持久性 | | **重排** | DashScope解析，禁用/离线/失败回退 | | **领域** | 作物日历（水稻&甘蔗），演示数据集，NaLog连接器，嵌入，向量工具处理程序 | **内存基准测试** （[`docs/BENCHMARK.md`](docs/BENCHMARK.md)）显示了为什么使用4层混合混合： 在标记的2季节数据集上，它实现了**100％召回率@5**，并且始终将当前事实排名置于其过时的双胞胎之上，而纯向量搜索会泄漏 **两次** 旧记忆进入上下文。<br> **消融研究** 证明每个机制（取代，强化，关键词，混合）都独立地获得其位置。  CI在每次推送和PR时通过 [GitHub Actions](.github/workflows/ci.yml) 在Node 20、22和24上运行，并包括`npm test`，`npm run check`（自检），MCP客户端烟雾测试和`npm audit`。<br> Node 24是活跃的LTS开发/ Docker目标；Node 20被保留在矩阵中以匹配Alibaba函数计算的捆绑自定义运行时版本。 ## 如何映射到评判标准 | 评判标准 | 体现在哪里 | |---|---| | **技术深度与工程（30%）** | 故意设计的4层Qwen路由（`qwen3.7-max`思考 + 工具调用，`qwen3.6-plus`自然语言生成，`qwen3.6-flash`提取 + 裁决，`qwen3-vl-plus`视觉）采用混合思考控制和SSE流式传输； **MCP服务器**暴露所有9种工具； **基准测试的4层混合检索**，采用**LLM裁决的超优先级**（向量优先 + `qwen3-rerank`交叉编码器 + BM25关键词重叠 + 及时性衰减 + 强化学习 + 矛盾检测 + Tablestore TTL + 3层去重 + 孤立向量清理）— **100% Recall@5, 0个过时事实**，相比Mem0风格的基线（92.9%，10个过时泄漏）；验证Firebase身份（RS256对抗Google证书，无SDK）；125个自动化测试 + 持续集成； **消融实验**证明每个机制都独立发挥作用。 | | **创新与AI创造力（30%）** | **4层混合检索**（语义 + 关键词 + 及时性 + 强化学习）将稠密向量检索与BM25启发的词汇匹配相结合 — 通过消融实验证明每个信号都是必要的； **LLM裁决的矛盾超优先级** — 当新事实与旧记忆相矛盾（相似度0.50–0.85）时，通过廉价的`qwen3.6-flash`裁决决定是否替换旧事实；旧记忆被保留以便审计，但不参与检索； **安全救援层**在查询相似度较低时仍能触发关键记忆； **可解释的检索**（`memory_trace` SSE）和**记忆差异**（`memory_diff` SSE）使记忆系统透明；自主传感器警报转换，人工介入；交叉编码器重排序；通过Qwen-VL进行实物照片验证；模块化存储/向量驱动；有界ReAct循环，优雅降级；自主回合学习，3层去重（精确 + 语义 + 裁决）；令牌预算约束，支持并发的每轮报告和重试/回退。 | | **问题价值与影响（25%）** | **生产部署**，服务于真实农民（库特楚姆， Yasothon）— 节水/柴油，甲烷减排，贫困家庭粮食安全；开源（MIT），可在合作社和东南亚推广。 | | **展示与文档（15%）** | 架构图，实时流媒体UI，工具跟踪透明，可复制的基准测试与图表（[docs/BENCHMARK.md](docs/BENCHMARK.md)），完整文档（`README`，`docs/ARCHITECTURE.md`，`docs/proof-of-alibaba-deployment.md`，[`docs/SECURITY.md`](docs/SECURITY.md)）， [博客文章](https://albertoroura.com/adding-qwen-powered-memory-augmented-agent-to-nalog-platform/)。 | ## 项目布局 ``` src/ llm/ Qwen客户端（Model Studio）：聊天/流/JSON，嵌入，qwen3-rerank memory/ 记忆系统：存储（本地|Tablestore）+ 向量（本地|DashVector） agent/ ReAct循环（流事件），工具（包括Qwen-VL照片），提示 integrations/ NaLog读取连接器，ChirpStack下行链路，作物日历，演示数据 routes/ 聊天（SSE），提案（HITL，所有权），警报（自主），健康检查 middleware/ API密钥门控 + 验证的Firebase农民身份 mcp/ MCP服务器，通过stdio暴露代理工具 public/ 网页聊天UI（流式传输，工具跟踪，照片上传，记忆面板） deploy/ Tablestore/DashVector配置，Function Compute部署 scripts/ 自检，MCP冒烟测试，部署冒烟测试，记忆基准测试，演示种子 test/ 125个自动化测试（全部确定性，无云依赖） docs/ 架构，阿里巴巴证明，基准测试，安全集成指南，连接器API ``` ## 博客文章 [为NaLog平台添加Qwen驱动的记忆增强代理](https://albertoroura.com/adding-qwen-powered-memory-augmented-agent-to-nalog-platform/) ## YouTube视频 [为NaLog平台添加Qwen驱动的记忆增强代理](https://www.youtube.com/watch?v=tzedZsHiYXU) ## 许可证 MIT — 见 [LICENSE](LICENSE)。开源，以便任何农民合作社、非政府组织或开发者都可以运行。