silk/AGENTS.md

AGENTS

沟通规则

1. 先说明结论，再说明影响和后续操作。
2. 除非项目约定另有要求，否则使用用户偏好的语言。
3. 交付说明应聚焦于修改的文件、验证结果和风险。
4. 对不清楚的需求或不可逆选择，执行前先向用户确认。
5. 创建或重写本指令文件前，询问用户该文件应使用哪种语言。
6. 每完成一项交付（功能/模块/部署），必须更新根目录 开发交接记录.md，追加「做了什么、设计思路与决策依据、验证结果、回滚点」，保证同事阅读后能快速接手；不得只做口头总结。

项目结构

本仓库是「智慧蚕房环境监测与智能调控系统」多模块 monorepo，各目录职责边界如下：

1. server-go/ — Go 后端（Go 1.23，Gin + GORM），入口为 cmd/server/main.go；提供 REST API（默认 :3000）、WebSocket /ws、视频代理 /live/proxy；消费 MQTT 遥测并处理阈值告警、设备控制、RBAC；依赖 PostgreSQL、IoTDB、Valkey/Redis、Ceph S3、WVP/ZLM、recorder-go。
2. web/ — Web 后台前端（Vite + React + TypeScript + Ant Design），开发端口 5173，/api 代理到后端 :3000。
3. app/ — React Native 移动端（RN 0.74），后端地址通过 .env 配置（参考 .env.example 的 API_BASE_URL）。
4. miniapp/ — 微信小程序（Taro 4 + React + TypeScript + Sass）；project.config.json 的 miniprogramRoot 指向 dist/，该目录是 Taro 构建产物，不得手改。
5. wvp/ — WVP-PRO + ZLMediaKit 视频平台（docker-compose.yml 包含 WVP、ZLMediaKit、MySQL、Redis），并含 recorder-go（Go 连续录制服务，默认 :9090）与 Dockerfile。
6. 根目录文档 — README.md、部署指南(物理机).md、变更记录.md、故障排查处理记录.md、物联网设备接口和数据格式.md、后续工作计划.md（规格书 V2.1 的工作清单与技术选型决策）等为项目说明、规划与部署运维依据。
7. ai-service/（规划中）— Python FastAPI + ONNX Runtime AI 推理微服务（YOLO 蚕病检测、图像/光谱分析），生产部署于云 GPU 主机（NVIDIA T4 16G），与 Go 后端通过 HTTP/gRPC 通信；模型训练在本地 fnOS/P4 物理机完成。技术方向为「现有 Go 底座 + Python AI 微服务」混合架构，生产环境全部上云（业务云主机 + GPU 云主机 + 云对象存储），本地仅用于开发/训练/测试，详细规划见 后续工作计划.md。

生成文件及其来源命令：

1. miniapp/dist/ — 由 npm run dev:weapp / npm run build:weapp 生成。
2. web/dist/ — 由 npm run build 生成。
3. app/android/app/build/outputs/apk/release/app-release.apk — 由 cd android && gradlew assembleRelease 生成。
4. server-go/server-go-linux — 由 go build -o server-go-linux ./cmd/server 交叉编译生成。

编码规则

1. 遵循现有命名、分层、错误处理和格式化约定。
2. 将修改范围限制在用户请求的任务内。
3. 不得覆盖用户无关的已有修改。
4. 不得猜测或编造缺失的需求、事实、约定或技术决策。
5. 根据用户明确输入、仓库文件、配置、文档或命令输出验证相关结论。
6. 如果相关细节不确定、有歧义、存在冲突或无法验证，必须停止并先向用户确认，再继续操作。
7. 不得手改生成产物（如 miniapp/dist/、web/dist/、编译后的 APK、server-go-linux）；需要改动时先修改源文件或源 schema，再重新生成。

安装与配置

1. 后端：cd server-go && go build -o server-go-linux ./cmd/server；开发运行用 go run ./cmd/server。必需环境变量以 README「Go 后端环境变量」为准：PG、REDIS、JWT_SECRET、JWT_EXPIRES_IN、MQTT、IOTDB_URL、WVP_API_BASE、ZLM_API_BASE、RECORDER_API_BASE、S3_ENDPOINT、S3_ACCESS_KEY、S3_SECRET_KEY、S3_BUCKET、PORT、DEFAULT_ADMIN_USERNAME、DEFAULT_ADMIN_PASSWORD。
2. Web 前端：cd web && npm install && npm run dev；生产构建 npm run build。
3. React Native APP：cd app && npm install，按 app/.env.example 配置 API_BASE_URL，然后 npm start / npm run android。
4. 微信小程序：cd miniapp && npm install && npm run dev:weapp；生产构建 npm run build:weapp，产物输出到 dist/。
5. WVP 视频平台：cd wvp && docker compose up -d。
6. 选择未明确指定的技术栈、包管理器、数据库、运行时、部署目标或外部服务前，必须先获得用户确认。
7. 初始化项目时，如果技术栈尚未明确，应先让用户选择技术栈，再创建项目文件。
8. 不得将密钥写入需要提交的文件；需要环境配置时使用占位值创建 .env.example。
9. AI 推理服务（规划中）：Python 3.11 + 虚拟环境，PyTorch（cu121/cu124 wheel，兼容 Tesla P4）+ ultralytics；模型训练在本地 fnOS 服务器（i7-8700T / 62G / Tesla P4 8G，数据集路径 /vol1/ai/datasets）完成，导出 ONNX 后部署到云 GPU 主机（T4 16G）由 FastAPI 服务加载。

部署到开发服务器（dev：100.83.103.1）

环境依据：部署指南(物理机).md。SSH 主机 100.83.103.1、用户 pan，密码不写入提交文件，通过环境变量 PAN_SSH_PASS 传入；SSH/SFTP 辅助脚本为 scripts/devssh.py（不含任何密钥）。部署范围目前为 Go 后端（:3000）与 Web（:5174），小程序走微信开发者工具发布流程，不属于本服务器部署。

部署前置（每次发布必做）

1. 本地验证必须全部通过：后端 go test ./...、go build ./...、go vet ./...；Web npm run lint、npm run build；涉及小程序时 npm run build:weapp。
2. 代码可回滚检查（先于任何覆盖操作）：
   • 检查开发服务器 git 仓库状态：git status、git branch --show-current、git log -1 --oneline，确认服务器代码与发布基线的关系；记录服务器当前 commit。
   • 为服务器当前状态打可回滚标记：git tag pre-<YYYYMMDD-HHMMSS>（或把 commit hash 写入部署记录）。
   • 服务器工作区有未提交改动且与发布内容冲突时，不得强制 checkout/reset，先与用户确认。
3. 数据库可回滚检查：本次涉及 schema 变更（新增表/列/索引、数据迁移）时，发布前必须 pg_dump 全库备份到 /home/pan/backups/silk-<YYYYMMDD-HHMMSS>.dump，并记录恢复命令；纯代码发布可不强制，但每次发布前至少确认存在最近一份可用备份。
4. 运行环境检查：df -h（磁盘空间）、ss -tlnp（3000/5174/9090/5432 等端口监听）、服务进程存在性；有异常先记录并停止发布。

部署步骤

1. Go 后端：本机交叉编译 GOOS=linux GOARCH=amd64 go build -o silk-server-go-linux ./cmd/server/ → 上传服务器 → 保留旧二进制（如 silk-server-go-linux.bak-<时间戳>）→ 按 start_sh.txt / 部署指南方式重启（source .env 或导齐环境变量）→ curl http://localhost:3000/api/v1/health 健康检查 → 检查启动日志无 panic/连接错误。
2. Web：npm run build → 上传 dist → 备份旧 dist → 重启 server.cjs → curl -s -o /dev/null -w '%{http_code}' http://localhost:5174/ 应为 200。
3. 新接口/新功能冒烟：用登录 token 调用新增 API（如 /api/v1/knowledge/diseases）验证返回；检查后端日志无 5xx。
4. 部署后：更新 变更记录.md（日期、内容、验证结果、回滚点），并把服务器 commit/备份路径记入部署记录；同时按沟通规则追加 开发交接记录.md。

回滚预案

1. 代码回滚：服务器 git git checkout <pre-commit>，或恢复 .bak 二进制/旧 dist，重启服务并做健康检查。
2. 数据库回滚：仅在新 schema 有问题时执行 pg_restore 恢复备份；恢复前先再次备份当前状态并确认影响范围。
3. 回滚后更新部署记录与 变更记录.md。

禁止事项

1. 未完成备份/未记录回滚点前，不得覆盖服务器代码、二进制或数据库。
2. 不得在服务器上直接修改生成产物；需要修复时改源文件后重新构建部署。
3. 服务器密钥/密码不得写入提交文件；一律通过环境变量注入。

验证

1. 常规修改的针对性检查：Go 后端 go build ./...；Web npm run lint 与 npm run build；APP npm run lint 与 npm run tsc；小程序 npm run build:weapp。
2. 共享行为修改或发布工作执行更广泛检查：后端 go test ./...、go vet ./...，前端构建产物可用性检查。
3. 如果检查无法运行（缺少依赖、网络受限等），必须清楚报告确切命令和失败原因。

代码审查

1. 审查修改的正确性、回归风险、安全性、可维护性和测试覆盖率。
2. 按严重程度排列审查发现，并尽可能提供文件和行号引用。
3. 具体问题优先于总结；如果没有发现问题，应明确说明。
4. 指出影响发布风险的未验证行为、缺失测试或尚未解决的不确定项。