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:
CODEBLOCK0
Parameters
Global Parameters
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE0 | string | - | Yes | Command to execute (add, search, list, update, delete, export, stats) |
| INLINECODE1 |
string | - | No | Path to configuration file |
Add Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE2 | string | - | Yes | Sample name |
| INLINECODE3 |
string | - | Yes | Project identifier |
|
--freezer | string | - | Yes | Freezer ID (e.g., F01) |
|
--level | int | - | Yes | Shelf level number |
|
--rack | string | - | Yes | Rack identifier |
|
--box | string | - | Yes | Box number |
|
--position | string | - | Yes | Position within box (e.g., A1) |
|
--quantity | int | 1 | No | Sample quantity |
|
--notes | string | - | No | Additional notes |
Search Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE11 | string | - | No | Search by sample name (fuzzy) |
| INLINECODE12 |
string | - | No | Search by project (exact) |
|
--freezer | string | - | No | Search by freezer ID |
|
--id | string | - | No | Search by sample UUID |
List Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE15 | string | - | No | Filter by freezer ID |
Update Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE16 | string | - | Yes | Sample UUID to update |
| INLINECODE17 |
string | - | No | New position |
|
--quantity | int | - | No | New quantity |
|
--notes | string | - | No | New notes |
Delete Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE20 | string | - | Yes | Sample UUID to delete |
Export Command
| Parameter | Type | Default | Required | Description |
|---|
| INLINECODE21 , INLINECODE22 | string | - | Yes | Output file path |
| INLINECODE23 |
string | - | No | Filter by freezer ID |
Stats Command
No additional parameters required.
Usage
🚀 Usage Guide
Command Line Interface
Sample Management
CODEBLOCK1
Python API Usage
CODEBLOCK2
🧪 Evaluation & Testing
Success Criteria
- 1. Functional Accuracy: 100% correct position recording and retrieval
- Performance: <1 second response time for 1000+ sample database
- Data Integrity: Zero corruption in concurrent operations
- User Experience: Clear error messages and intuitive commands
Test Suite
CODEBLOCK3
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
CODEBLOCK4
📋 Location Encoding Standards
Hierarchical Coordinate System
| Component | Format | Range | Description |
|---|
| Freezer ID | F01, F02, F03... | F01-F99 | Physical freezer unit |
| Level |
1-10 | 1-10 | Vertical level (top to bottom) |
|
Rack | A-Z | A-Z | Horizontal rack position |
|
Box | 01-99 | 01-99 | Box number within rack |
|
Position | A1-H12 | A1-H12 | Grid 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
CODEBLOCK5
🔒 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
| Version | Date | Changes | Author |
|---|
| v1.0 | 2026-02-06 | Initial 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
CODEBLOCK6
Installation & Setup
# 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 Indicator | Assessment | Level |
|---|
| Code Execution | Python/R scripts executed locally | Medium |
| Network Access |
No external API calls | Low |
| File System Access | Read input files, write output files | Medium |
| Instruction Tampering | Standard prompt guidelines | Low |
| Data Exposure | Output files saved to workspace | Low |
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
- Edge Case: Invalid input → Graceful error handling
- 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
冷冻样本定位器
目的：使用分层存储组织系统化管理和检索-80°C冷冻柜中的样本位置。
分类：工具/脚本型（本地脚本执行）
🎯 核心功能
主要操作
- - 记录：使用分层坐标（冷冻柜→层→架→盒→位置）存储样本位置
- 检索：按名称、项目、冷冻柜、日期或唯一ID搜索样本
- 管理：更新样本元数据、删除记录、维护库存
- 导出：生成带筛选选项的CSV/JSON格式报告
数据完整性特性
- - 冲突检测：防止重复位置分配
- 验证：强制执行正确的位置编码规则
- 审计追踪：跟踪创建和修改时间戳
- 备份：基于JSON的存储，自动创建文件
数据结构
样本位置信息存储在JSON文件中：
json
{
samples: [
{
id: uuid,
name: 样本名称,
project: 项目名称,
freezer: F01,
level: 1,
rack: A,
box: 01,
position: A1,
quantity: 1,
date_stored: 2024-01-15,
notes: 备注,
created_at: 2024-01-15T10:30:00Z,
updated_at: 2024-01-15T10:30:00Z
}
]
}
参数
全局参数
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| command | string | - | 是 | 要执行的命令（add, search, list, update, delete, export, stats） |
| --config |
string | - | 否 | 配置文件路径 |
添加命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --name | string | - | 是 | 样本名称 |
| --project |
string | - | 是 | 项目标识符 |
| --freezer | string | - | 是 | 冷冻柜ID（例如F01） |
| --level | int | - | 是 | 层架编号 |
| --rack | string | - | 是 | 架标识符 |
| --box | string | - | 是 | 盒编号 |
| --position | string | - | 是 | 盒内位置（例如A1） |
| --quantity | int | 1 | 否 | 样本数量 |
| --notes | string | - | 否 | 附加备注 |
搜索命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --name | string | - | 否 | 按样本名称搜索（模糊） |
| --project |
string | - | 否 | 按项目搜索（精确） |
| --freezer | string | - | 否 | 按冷冻柜ID搜索 |
| --id | string | - | 否 | 按样本UUID搜索 |
列表命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --freezer | string | - | 否 | 按冷冻柜ID筛选 |
更新命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --id | string | - | 是 | 要更新的样本UUID |
| --position |
string | - | 否 | 新位置 |
| --quantity | int | - | 否 | 新数量 |
| --notes | string | - | 否 | 新备注 |
删除命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --id | string | - | 是 | 要删除的样本UUID |
导出命令
| 参数 | 类型 | 默认值 | 必填 | 描述 |
|---|
| --output, -o | string | - | 是 | 输出文件路径 |
| --freezer |
string | - | 否 | 按冷冻柜ID筛选 |
统计命令
无需额外参数。
使用指南
🚀 使用指南
命令行界面
样本管理
bash
添加新样本
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
搜索操作
python scripts/main.py search --name Sample-001 # 名称搜索（模糊）
python scripts/main.py search --project Project-A # 项目搜索（精确）
python scripts/main.py search --freezer F01 # 冷冻柜搜索
python scripts/main.py search --id uuid-string # ID搜索（精确）
列表（可选筛选）
python scripts/main.py list # 所有样本
python scripts/main.py list --freezer F01 # 特定冷冻柜
更新样本信息
python scripts/main.py update --id uuid --position B2 --quantity 1
删除样本记录
python scripts/main.py delete --id uuid
导出功能
python scripts/main.py export --output samples.csv --freezer F01
统计
python scripts/main.py stats
Python API使用
python
from scripts.main import FreezerSampleLocator
初始化定位器
locator = FreezerSampleLocator()
添加样本（带验证）
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
)
多条件搜索
results = locator.search_samples(
name=Sample-001,
project=Project-A
)
获取格式化位置
location = locator.get
samplelocation(sample_id)
print(location[location_str]) # F01 > L1 > RA > B01 > A1
导出数据
locator.export_csv(inventory.csv, freezer=F01)
🧪 评估与测试
成功标准
- 1. 功能准确性：100%正确的位置记录和检索
- 性能：1000+样本数据库响应时间<1秒
- 数据完整性：并发操作零损坏
- 用户体验：清晰的错误信息和直观的命令
测试套件
python
核心功能测试
def test
addsample():
测试样本添加及验证
def testsearchoperations():
测试按名称、项目、冷冻柜搜索
def testconflictprevention():
测试重复位置检测
def testexportfunctionality():
测试CSV/JSON导出格式
def testdataintegrity():
测试并发访问安全性
验证清单
- - [ ] 位置编码验证
- [ ] 重复检测准确性
- [ ] 搜索结果正确性
- [ ] 导出格式合规性
- [ ] 错误处理稳健性
- [ ] 文件权限安全性
📊 监控与维护
使用指标
- - 操作量：跟踪添加/搜索/更新/删除频率
- 数据库大小：监控样本数量增长
- 性能指标：响应时间趋势
- 错误率：失败操作频率
维护任务
- - 数据备份：定期JSON文件备份
- 性能优化：大数据集索引重建
- 验证更新：位置编码规则变更
- 安全审查：访问模式分析
健康检查
bash
验证数据库完整性
python scripts/main.py stats
测试搜索性能
python scripts/main.py search --name test
导出验证
python scripts/main.py export --output test.csv
📋 位置编码标准
分层坐标系统
| 组件 | 格式 | 范围 | 描述 |
|---|
| 冷冻柜ID | F01, F02, F03... | F01-F99 | 物理冷冻柜单元 |
| 层 |
1-10 | 1-10 |
