Freezer Sample Locator#

Purpose: Systematically manage and retrieve sample locations in -80°C freezers using hierarchical storage organization.

Classification: Tool/Script型 (本地脚本执行)

🎯 Core Functions#

Primary Operations#

• Record: Store sample locations with hierarchical coordinates (freezer → level → rack → box → position)
• Retrieve: Search samples by name, project, freezer, date, or unique ID
• Manage: Update sample metadata, delete records, maintain inventory
• Export: Generate reports in CSV/JSON formats with filtering options

Data Integrity Features#

• Conflict Detection: Prevent duplicate position assignments
• Validation: Enforce proper location encoding rules
• Audit Trail: Track creation and modification timestamps
• Backup: JSON-based storage with automatic file creation

Data Structure#

Sample location information is stored in JSON files:

json

{
  "samples": [
    {
      "id": "uuid",
      "name": "Sample Name",
      "project": "Project Name",
      "freezer": "F01",
      "level": 1,
      "rack": "A",
      "box": "01",
      "position": "A1",
      "quantity": 1,
      "date_stored": "2024-01-15",
      "notes": "Notes",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Parameters#

Global Parameters#

ParameterTypeDefaultRequiredDescriptioncommandstring-YesCommand to execute (add, search, list, update, delete, export, stats)--configstring-NoPath to configuration file

Add Command#

ParameterTypeDefaultRequiredDescription--namestring-YesSample name--projectstring-YesProject identifier--freezerstring-YesFreezer ID (e.g., F01)--levelint-YesShelf level number--rackstring-YesRack identifier--boxstring-YesBox number--positionstring-YesPosition within box (e.g., A1)--quantityint1NoSample quantity--notesstring-NoAdditional notes

Search Command#

ParameterTypeDefaultRequiredDescription--namestring-NoSearch by sample name (fuzzy)--projectstring-NoSearch by project (exact)--freezerstring-NoSearch by freezer ID--idstring-NoSearch by sample UUID

List Command#

ParameterTypeDefaultRequiredDescription--freezerstring-NoFilter by freezer ID

Update Command#

ParameterTypeDefaultRequiredDescription--idstring-YesSample UUID to update--positionstring-NoNew position--quantityint-NoNew quantity--notesstring-NoNew notes

Delete Command#

ParameterTypeDefaultRequiredDescription--idstring-YesSample UUID to delete

Export Command#

ParameterTypeDefaultRequiredDescription--output, -ostring-YesOutput file path--freezerstring-NoFilter by freezer ID

Stats Command#

No additional parameters required.

Usage#

🚀 Usage Guide#

Command Line Interface#

Sample Management

bash

# Add new sample
python scripts/main.py add \
  --name "Sample-001" \
  --project "Project-A" \
  --freezer "F01" \
  --level 1 \
  --rack "A" \
  --box "01" \
  --position "A1" \
  --quantity 2 \
  --notes "Primary culture"

# Search operations
python scripts/main.py search --name "Sample-001"    # Name search (fuzzy)
python scripts/main.py search --project "Project-A" # Project search (exact)
python scripts/main.py search --freezer "F01"        # Freezer search
python scripts/main.py search --id "uuid-string"     # ID search (exact)

# List with optional filtering
python scripts/main.py list                           # All samples
python scripts/main.py list --freezer "F01"          # Specific freezer

# Update sample information
python scripts/main.py update --id "uuid" --position "B2" --quantity 1

# Delete sample record
python scripts/main.py delete --id "uuid"

# Export functionality
python scripts/main.py export --output samples.csv --freezer "F01"

# Statistics
python scripts/main.py stats

Python API Usage

python

from scripts.main import FreezerSampleLocator

# Initialize locator
locator = FreezerSampleLocator()

# Add sample with validation
sample = locator.add_sample(
    name="Sample-001",
    project="Project-A",
    freezer="F01",
    level=1,
    rack="A",
    box="01",
    position="A1",
    quantity=2,
    notes="Primary culture"
)

# Search with multiple criteria
results = locator.search_samples(
    name="Sample-001",
    project="Project-A"
)

# Get formatted location
location = locator.get_sample_location(sample_id)
print(location["location_str"])  # "F01 > L1 > RA > B01 > A1"

# Export data
locator.export_csv("inventory.csv", freezer="F01")

🧪 Evaluation & Testing#

Success Criteria#

1. Functional Accuracy: 100% correct position recording and retrieval
2. Performance: <1 second response time for 1000+ sample database
3. Data Integrity: Zero corruption in concurrent operations
4. User Experience: Clear error messages and intuitive commands

Test Suite#

python

# Core functionality tests
def test_add_sample():
    """Test sample addition with validation"""

def test_search_operations():
    """Test search by name, project, freezer"""

def test_conflict_prevention():
    """Test duplicate position detection"""

def test_export_functionality():
    """Test CSV/JSON export formats"""

def test_data_integrity():
    """Test concurrent access safety"""

Validation Checklist#

• Position encoding validation
• Duplicate detection accuracy
• Search result correctness
• Export format compliance
• Error handling robustness
• File permission safety

📊 Monitoring & Maintenance#

Usage Metrics#

• Operation Volume: Track add/search/update/delete frequencies
• Database Size: Monitor sample count growth
• Performance Metrics: Response time trends
• Error Rates: Failed operation frequency

Maintenance Tasks#

• Data Backup: Regular JSON file backups
• Performance Optimization: Index rebuilding for large datasets
• Validation Updates: Location encoding rule changes
• Security Review: Access pattern analysis

Health Checks#

bash

# Verify database integrity
python scripts/main.py stats

# Test search performance
python scripts/main.py search --name "test"

# Export validation
python scripts/main.py export --output test.csv

📋 Location Encoding Standards#

Hierarchical Coordinate System#

ComponentFormatRangeDescriptionFreezer IDF01, F02, F03...F01-F99Physical freezer unitLevel1-101-10Vertical level (top to bottom)RackA-ZA-ZHorizontal rack positionBox01-9901-99Box number within rackPositionA1-H12A1-H12Grid position (96-well standard)

Validation Rules#

• Uniqueness: Each position can contain only one sample
• Format Compliance: Strict pattern matching enforced
• Range Checking: All components validated against allowed ranges
• Conflict Prevention: Real-time duplicate detection

Location String Format#

text

{Freezer} > L{Level} > R{Rack} > B{Box} > {Position}
Example: F01 > L1 > RA > B01 > A1

🔒 Security & Compliance#

Risk Assessment#

• File System Access: ✅ Controlled to skill directory only
• Script Execution: ✅ Sandboxed Python environment
• Data Privacy: ✅ No external network calls or data transmission
• Input Validation: ✅ Comprehensive parameter checking

Security Controls#

• Path Constraints: Limited to data/ subdirectory within skill folder
• Input Sanitization: Validates all coordinates and metadata
• Error Handling: Safe exception handling without information leakage
• Access Control: No privileged operations or system calls

🔄 Lifecycle Management#

Version History#

VersionDateChangesAuthorv1.02026-02-06Initial release with core functionality研发部

Deployment Status#

• Environment: Production ready
• Test Coverage: Manual validation completed
• Security Review: ✅ Passed (MEDIUM risk accepted)
• Performance: ✅ Meets requirements (<1s response)

Monitoring Plan#

• Daily: Usage statistics and error logs
• Weekly: Performance metrics and database size
• Monthly: Security audit and backup verification
• Quarterly: Feature review and optimization assessment

Deprecation Policy#

• Notice Period: 3 months for major changes
• Migration Support: Data export tools provided
• Backward Compatibility: Maintained for minor versions

📞 Support & Contact#

Technical Support#

• Owner: 研发部
• Escalation: Contact skill repository maintainers
• Documentation: This file + inline code comments

Issue Reporting#

• Bug Reports: Include error messages and reproduction steps
• Feature Requests: Provide use case and requirements
• Security Issues: Report immediately to security team

📦 Dependencies & Prerequisites#

Runtime Requirements#

• Python: 3.8+ (standard library only)
• No third-party dependencies: Reduces supply chain risk

File Structure#

text

freezer-sample-locator/
├── SKILL.md                 # This file
├── scripts/
│   └── main.py             # Core implementation
└── data/
    └── samples.json        # Sample database (auto-created)

Installation & Setup#

bash

# No additional installation required - uses Python standard library
# Data directory created automatically on first run

---

Skill Classification: Tool/Script型 (MEDIUM Risk)

Compliance Status: ✅ Approved for production use

Next Review: 2026-05-06

Risk Assessment#

Risk IndicatorAssessmentLevelCode ExecutionPython/R scripts executed locallyMediumNetwork AccessNo external API callsLowFile System AccessRead input files, write output filesMediumInstruction TamperingStandard prompt guidelinesLowData ExposureOutput files saved to workspaceLow

Security Checklist#

• No hardcoded credentials or API keys
• No unauthorized file system access (../)
• Output does not expose sensitive information
• Prompt injection protections in place
• Input file paths validated (no ../ traversal)
• Output directory restricted to workspace
• Script execution in sandboxed environment
• Error messages sanitized (no stack traces exposed)
• Dependencies audited

Prerequisites#

No additional Python packages required.

Evaluation Criteria#

Success Metrics#

• Successfully executes main functionality
• Output meets quality standards
• Handles edge cases gracefully
• Performance is acceptable

Test Cases#

1. Basic Functionality: Standard input → Expected output
2. Edge Case: Invalid input → Graceful error handling
3. Performance: Large dataset → Acceptable processing time

Lifecycle Status#

• Current Stage: Draft

• Next Review Date: 2026-03-06

• Known Issues: None

• Planned Improvements:

  • Performance optimization
  • Additional feature support