shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

querying-hms-documentation

查询官方HEC-HMS文档以回答技术问题。提供用户手册、技术参考手册、发行说明和社区资源的访问途径。当寻求关于HMS方法、参数、文件格式、版本特性或工作流程指导的官方文档时使用。通过权威文档补充调查HMS内部（反编译源代码）。触发关键词：HMS文档, 用户手册, 技术参考, 损失方法, 转换方法, 路由方法, HMS参数, 文件格式, 发行说明, HMS版本特性, 方法参数, 官方HMS, USACE文档。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

Querying HMS Documentation

Purpose: Answer technical questions using official HEC-HMS documentation from the U.S. Army Corps of Engineers (USACE) Hydrologic Engineering Center.

Quick Start

Query Method Parameters

Q: "What parameters does SCS Curve Number require?"
A: See hms_agents/hms_doc_query/AGENT.md → query_documentation("SCS Curve Number parameters", focus_area="loss_methods")

Check File Format

Q: "How are subbasins defined in .basin files?"
A: See hms_agents/hms_doc_query/AGENT.md → query_documentation("subbasin definition", focus_area="file_formats")

Version Features

Q: "What was added in HMS 4.11?"
A: See hms_agents/hms_doc_query/AGENT.md → search_release_notes("4.11")

Primary Sources

Production Agent

Location: hms_agents/hms_doc_query/

Quick access:

  • QUICK_START.md - 5-minute guide
  • AGENT.md - Comprehensive documentation
  • doc_query.py - Query implementation

This agent queries official documentation via web requests to HEC documentation servers.

Documentation Sources

Official USACE Documentation

| Source | URL | Coverage | |--------|-----|----------| | User's Manual | https://www.hec.usace.army.mil/confluence/hmsdocs/hmsum/latest/ | UI, workflows, methods | | Technical Reference | https://www.hec.usace.army.mil/confluence/hmsdocs/hmstrm/latest/ | Method algorithms, equations | | Release Notes | https://www.hec.usace.army.mil/software/hec-hms/downloads.aspx | Version changes, features | | Downloads | https://www.hec.usace.army.mil/software/hec-hms/downloads.aspx | Installation, examples |

Community Resources

| Source | URL | Coverage | |--------|-----|----------| | The RAS Solution Forum | https://therassolution.kleinschmidtgroup.com/ | Professional Q&A | | Hydro School Forums | https://hydroschool.org/forums/ | Tutorials, modeling | | Reddit r/HECRAS | https://www.reddit.com/r/HECRAS/ | Quick questions |

When to Use This Skill

Use When

  1. Method Documentation

    • "What parameters does Clark Unit Hydrograph require?"
    • "How does Green-Ampt loss method work?"
    • "What's the difference between ModClark and Clark?"

  2. File Format Questions

    • "What is the structure of a .control file?"
    • "How are gages defined in .gage files?"
    • "What DSS pathname format does HMS use?"

  3. Version-Specific Features

    • "Is gridded soil moisture available in HMS 4.10?"
    • "What new features were added in HMS 4.11?"
    • "When was the EAP transform introduced?"

  4. Workflow Guidance

    • "How do I set up gridded precipitation?"
    • "How do I configure a reservoir routing model?"
    • "What's the workflow for calibration?"

  5. Troubleshooting

    • "What does WARNING 10020 mean?"
    • "Why am I getting NullPointerException?"
    • "How do I fix 'Project not found' errors?"

Don't Use When

  1. Internal Implementation Details

    • Use investigating-hms-internals skill instead
    • investigating-hms-internals has decompiled source code

  2. JythonHms API Reference

    • Use investigating-hms-internals skill
    • Decompiled JythonHms.java has complete method signatures

  3. Undocumented Features

    • Official docs won't cover undocumented behavior
    • Use investigating-hms-internals for source code analysis

  4. hms-commander API Questions

    • Read hms-commander docstrings directly
    • Check examples/ notebooks

Query Functions

query_documentation()

Main function to query HMS documentation.

Parameters:

  • question (str): The technical question
  • focus_area (str): Narrow search
    • "loss_methods", "transform_methods", "routing_methods"
    • "file_formats", "workflows", "release_notes"
    • "installation", "troubleshooting"
  • hms_version (str): Target version (e.g., "4.11")

get_method_parameters()

Get parameter details for specific HMS method.

Parameters:

  • method_type (str): "loss", "transform", "baseflow", "routing"
  • method_name (str): Name of the method

search_release_notes()

Search HMS release notes.

Parameters:

  • query (str): Search query
  • version (str): Specific version to search

validate_method_name()

Check if method name is valid in HMS.

Parameters:

  • method_name (str): Method name to validate
  • method_type (str): "loss", "transform", etc.

Common Questions

Loss Methods

| Question | Focus Area | |----------|------------| | "What are SCS Curve Number parameters?" | loss_methods | | "How does Deficit-Constant differ from Initial-Constant?" | loss_methods | | "What is Green-Ampt infiltration?" | loss_methods |

Transform Methods

| Question | Focus Area | |----------|------------| | "Clark Unit Hydrograph parameters?" | transform_methods | | "How to calculate Time of Concentration?" | transform_methods | | "What's the difference between Clark and ModClark?" | transform_methods |

Routing Methods

| Question | Focus Area | |----------|------------| | "Muskingum-Cunge parameters?" | routing_methods | | "How does kinematic wave routing work?" | routing_methods | | "Modified Puls vs Muskingum?" | routing_methods |

File Formats

| Question | Focus Area | |----------|------------| | "Structure of .basin file?" | file_formats | | "DSS pathname format for HMS?" | file_formats | | "How are time series stored?" | file_formats |

Known Limitations

Image/Screenshot Support

IMPORTANT: HMS documentation relies heavily on screenshots and diagrams.

  • WebFetch retrieves TEXT content from documentation pages
  • Images are REFERENCED but NOT RENDERED
  • Agent cannot describe UI screenshots or visual diagrams
  • Agent CAN identify when images exist and reference captions

Workaround: Agent provides URLs for manual viewing when visual content is needed.

Other Limitations

  • Cannot access local HMS installation help files
  • PDF manuals require direct URLs
  • Community forums have varying quality
  • Version differences may not be clearly documented

Complementary Skills

investigating-hms-internals

Purpose: Decompiled source code analysis

Complementary use: | Question Type | Use This Skill | |---------------|----------------| | "What does the documentation say about X?" | querying-hms-documentation | | "How does HMS actually implement X?" | investigating-hms-internals | | "What parameters are documented for X?" | querying-hms-documentation | | "What is the JythonHms method signature for X?" | investigating-hms-internals |

Related Skills

  • parsing-basin-models - Working with basin files
  • executing-hms-runs - Running simulations
  • managing-hms-versions - Version detection and handling

Integration with hms-commander

This skill supports hms-commander development by providing:

  1. Method Validation: Verify method names and parameters before use
  2. File Format Guidance: Understand file structures when parsing
  3. Version Compatibility: Check feature availability across versions
  4. Troubleshooting Context: Interpret error messages

Example workflow:

# 1. Query documentation for method parameters
# Use hms_doc_query to verify "Deficit and Constant" parameters

# 2. Set parameters with confidence
from hms_commander import HmsBasin
HmsBasin.set_loss_parameters(
    "model.basin", "Sub1",
    method="Deficit and Constant",
    initial_deficit=0.5,
    maximum_deficit=1.0,
    constant_rate=0.2,
    impervious_percent=10
)

Skill Workflow

Standard Query Flow

User Question
    |
    v
Identify Focus Area
    |-- loss_methods, transform_methods, routing_methods
    |-- file_formats, workflows, release_notes
    |-- installation, troubleshooting
    |
    v
Query Documentation (hms_doc_query)
    |
    v
Return Answer + Source URLs
    |
    v
Provide URL for Visual Content (if needed)

When to Escalate to Code Analysis

Documentation Query
    |
    v
Answer Found? --> YES --> Return Answer
    |
    NO
    |
    v
Undocumented Feature?
    |
    v
Use investigating-hms-internals
    |
    v
Decompile and Analyze Source

Quality Checklist

Before answering user questions:

  • [ ] Identified appropriate focus area
  • [ ] Queried correct documentation source
  • [ ] Provided source URLs for verification
  • [ ] Noted when visual content exists but cannot be shown
  • [ ] Suggested investigating-hms-internals for undocumented features
  • [ ] Pointed to primary sources (not duplicated content)

Quick Reference

Common questions -> Focus areas:

| Question Type | Focus Area | |---------------|------------| | Method parameters | loss_methods, transform_methods, routing_methods | | File structure | file_formats | | Version features | release_notes | | How-to guides | workflows | | Error messages | troubleshooting | | Setup/install | installation |

Agent location: hms_agents/hms_doc_query/

Documentation URLs:

  • User's Manual: https://www.hec.usace.army.mil/confluence/hmsdocs/hmsum/latest/
  • Technical Reference: https://www.hec.usace.army.mil/confluence/hmsdocs/hmstrm/latest/

Status: Production skill Version: 1.0 Created: 2025-12-17 Agent: hms_doc_query