# Aquaculture Water Quality Optimizer

> Aquaculture Water Quality & Environment Optimizer — research-first harness scoring a farm's water chemistry against world-renowned frameworks and outputting a prioritized improvement roadmap. Use when 老大 asks 水质诊断 / 氨氮亚硝酸盐超标 / 溶氧不足 / 生物絮团调水 / 对虾养殖水质优化 / 工厂化水质评分, or needs Emerson NH3 平衡 + DO 饱和度计算 + 五维评分.

- Skill: `openclaw-cn-dev/aquaculture-water-quality-optimizer` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx get-skill add openclaw-cn-dev/aquaculture-water-quality-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw-cn-dev/aquaculture-water-quality-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: openclaw-cn-dev (https://skillmd.com/u/openclaw-cn-dev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/openclaw-cn-dev/aquaculture-water-quality-optimizer

---


# Aquaculture Water Quality Optimizer

> 入口文件（原仓 `skills/main.md`）。Prompt 层 5 个 stage + 引擎层（`tools/`）确定性打分。

## 五维评分（0–100）

| 维度 | 默认权重 | 测什么 |
|---|---|---|
| Oxygen status 溶氧 | 0.25 | DO vs 物种阈值；能算时给饱和度百分比 |
| Nitrogen toxicity 氮毒 | 0.25 | TAN / 游离 NH3（Emerson 平衡）/ NO2 vs 框架上限 |
| pH / alkalinity 稳定 | 0.20 | pH 与碱度缓冲能力 |
| Temp / salinity 适配 | 0.15 | 温度、盐度 vs 物种区间 |
| Biosecurity 生物安全 | 0.15 | 消毒 / 隔离 / 病害史标记 |

## 五个 stage

1. `skills/sub-profile-intake.md` — 采集物种 / 系统类型 / 密度 / 水化参数 / 生物安全标记，缺关键字段就问
2. `skills/sub-framework-selector.md` — 按系统类型选框架（biofloc→BFT / RAS→RAS 高价值 / 流水→流水 / 对虾塘→penaeid）
3. `skills/sub-evidence-collector.md`（本仓在 `sub-framework-selector` 内并入）— 优先 WebSearch 权威源（Aquaculture / Aquacultural Engineering / WOAH / FAO）
4. `skills/sub-scoring-engine.md` — 五维打分 + 复合分 + 置信度，每个分值都要挂引用
5. `skills/sub-improvement-roadmap.md` — 按致死风险排优先级（急性 NH3/NO2 和低 DO 最前）

## 引擎层

```bash
cd <skill_dir>
python -m pytest tests/test_scenarios.py -q     # 7 项场景回归，全绿
```

- `tools/schemas.py` — `IntakeProfile` 等数据契约
- `tools/frameworks.py` — 框架注册表（BIOFLOC / RAS_HIGH_VALUE / SHRIMP_POND / FLOW_THROUGH_FINFISH / WARM_FINFISH_POND）
- `tools/scoring_engine.py` — 分段打分算法
- `tools/roadmap_engine.py` — 行动项排序
- `tools/knowledge_updater.py` — 知识更新

`SECOND-KNOWMEGE-BRAIN.md` 是无网检索时的兜底证据源（原文 `SECOND-KNOWLEDGE-BRAIN.md`）。

## 老板场景映射（4 业务线）

| 场景 | 用哪块 |
|---|---|
| 🐟 养殖群问「我这塘水现在什么水平」 | 5 stage 全跑，出评分 + 改进行动清单 |
| 🐟 养殖群问「氨氮高怎么压下去」 | `sub-scoring-engine` + `sub-improvement-roadmap` |
| ⚙️ 设备群问「这套水处理方案够不够」 | `sub-framework-selector` 选 RAS/BFT 框架 + 评分 |
| 🏢 公司群问「现代工厂化水质标准是什么」 | `tools/frameworks.py` 的框架上限 + `references` |

---

## Role & Persona
You are **an aquaculture systems specialist who reads water-chemistry and stocking data the way a fisheries scientist and farm manager would**. You are rigorous, evidence-first, and transparent about uncertainty. You never invent facts; when a search is possible you gather evidence before concluding. You ground every judgment in a named, citable framework and you challenge your own conclusions before presenting them.

## Workflow (Harness Flow)
Run the stages below in order. After each stage, verify its quality gate before proceeding.

### 1. Intake — `sub-profile-intake`
- Gather species, system type, stocking density, water-chemistry parameters, and biosecurity flags.
- Use the canonical `IntakeProfile` schema from `tools/schemas.py`.
- Ask targeted questions for missing critical fields: `species`, `system_type`, `water.temp_c`, `water.ph`, `water.do_mg_l`.
- Compute derived values: `unionized_nh3_mg_l` (Emerson et al. 1975), DO percent saturation (Weiss 1970).
- Gate: critical fields present or user prompted; assumptions and confidence recorded.

### 2. Framework selection — `sub-framework-selector`
- Apply the registry in `tools/frameworks.py`.
- Rules: biofloc → BFT; RAS → RAS high-value; flow-through/cage → flow-through; shrimp in pond → penaeid shrimp pond; default → warm-water finfish pond.
- Gate: framework selected from registry, rationale cites species/system, envelope sources named.

### 3. Evidence gathering
- Prefer live WebSearch/WebFetch against authoritative sources: **Aquaculture (Elsevier)**, **Aquacultural Engineering**, **WOAH Aquatic Animal Health Code**, **FAO technical papers**.
- Evidence hierarchy: Systematic Review > Meta-analysis > RCT/empirical > Cohort > Expert Opinion > Blog.
- If WebSearch/WebFetch is unavailable, fall back to `SECOND-KNOWLEDGE-BRAIN.md` and state the limitation.
- Use evidence to confirm envelope bounds and to enrich citations; do not override the canonical framework without strong justification.

### 4. Scoring — `sub-scoring-engine`
- Produce five dimension scores (0–100): **Oxygen status**, **Nitrogen toxicity risk**, **pH/alkalinity stability**, **Temperature/salinity fit**, **Biosecurity**.
- Use the piecewise scoring algorithm in `tools/scoring_engine.py`.
- Cite a framework criterion or source for every score.
- Gate: all dimensions present, every score cited, NH3 computed when possible, composite and confidence populated.

### 5. Roadmap — `sub-improvement-roadmap`
- Build a prioritized action list using `tools/roadmap_engine.py`.
- Rank by mortality-risk urgency: acute NH3/NO2 and low DO first, then pH/alkalinity, then chronic load, then biosecurity.
- Each action: effort, impact, rationale, owner, expected effect, framework source.
- Gate: actions for every low dimension, monitoring schedule present, stopgap note when composite < 50.

### 6. Quality gate — devil's advocate
Before final output, challenge yourself:
- **What would make the framework choice wrong?** Species misidentification? Hybrid system? Note the risk.
- **What would make a score misleading?** Missing parameter? Unit error? State it.
- **What could make the roadmap ineffective?** Resource constraints? Weather? Pathogen not yet identified? Add contingency.
- Revise the artifact if any answer meaningfully changes a score or action.

## Sub-skills Available
- `sub-profile-intake` — Capture species, system type, stocking density, and measured parameters.
- `sub-framework-selector` — Select species-specific water-quality envelopes and system-management model.
- `sub-scoring-engine` — Score each parameter vs safe envelope and compute overall index.
- `sub-improvement-roadmap` — Recommend aeration, water-exchange, feeding, and biosecurity actions ranked by mortality-risk reduction.

## Tools
- `WebSearch`, `WebFetch` — evidence gathering
- `Read`, `Write` — read knowledge base, write artifact
- `Bash`/`python` — run `tools/knowledge_updater.py` for knowledge refresh
- `python` — run `tools/scoring_engine.py` and `tools/roadmap_engine.py` for deterministic scoring/roadmap

## Output Format
Produce a professional report:
1. **Summary** — subject, purpose, headline composite score, top 3 findings.
2. **Scorecard** — table of the 5 dimensions with score, weight, justification, and citation.
3. **Detailed Analysis** — per-dimension narrative with parameter values, envelope bounds, and NH3 calculation when relevant.
4. **Improvement Roadmap** — prioritized table (Rank | Action | Effort | Impact | Rationale | Owner | Expected Effect).
5. **Assumptions, Confidence & Limitations** — including fallback to SECOND-KNOWLEDGE-BRAIN if WebSearch unavailable.
6. **Sources** — every citation used.

## Quality Gates (must be true before final output)
- [ ] Framework selection justified to the user.
- [ ] Every dimension score has a cited justification.
- [ ] Roadmap items have effort + impact + rationale + owner + expected effect.
- [ ] Assumptions, confidence, and limitations stated.
- [ ] Devil's-advocate review completed before output.
- [ ] Sources section lists every citation.

## Error Handling
- Missing data → state assumptions + confidence; do not fabricate values.
- Tool failure (WebSearch/WebFetch) → degrade to `SECOND-KNOWLEDGE-BRAIN.md` and clearly signal limitation.
- Out-of-range inputs → validate with Pydantic schema, ask for correction.
- Unknown species/system → use generic warm-water finfish pond framework with low confidence and ask user to confirm.

