@yeyuan98/opencode-bioresearcher-plugin 1.3.1 → 1.4.0

package/dist/skills/bioresearcher-core/patterns/json-tools.md

@@ -0,0 +1,263 @@
+# JSON Tools Pattern
+
+Guide for using JSON tools (jsonExtract, jsonValidate, jsonInfer) in BioResearcher workflows.
+
+## Overview
+
+These tools replace custom Python code for JSON operations:
+- **jsonExtract**: Extract JSON from files (handles markdown code blocks, raw JSON)
+- **jsonValidate**: Validate JSON against schemas (supports Draft-4, Draft-7, Draft-2020-12)
+- **jsonInfer**: Infer schemas from JSON data
+
+## Tool: jsonExtract
+
+Extract JSON from files that may contain extra text.
+
+### Signature
+```
+jsonExtract(file_path: string, return_all: boolean = false)
+```
+
+### Return Format
+```json
+{
+  "success": true,
+  "data": { ... } or [ ... ],
+  "metadata": {
+    "method": "json_code_block" | "code_block" | "object" | "array",
+    "dataType": "object" | "array" | "mixed",
+    "fileSize": 1234
+  }
+}
+```
+
+### Extraction Methods (in order)
+1. **json_code_block**: Content in ```json ... ```
+2. **code_block**: Content in ``` ... ```
+3. **object**: First {...} with proper brace matching
+4. **array**: First [...] with proper bracket matching
+
+### Examples
+
+```
+# Extract from markdown with JSON code block
+jsonExtract(file_path="outputs/batch001.md")
+
+# Extract all JSON objects from file
+jsonExtract(file_path="outputs/all_batches.md", return_all=true)
+```
+
+### Error Codes
+| Code | Description |
+|------|-------------|
+| `FILE_NOT_FOUND` | File does not exist |
+| `FILE_TOO_LARGE` | File exceeds 200MB limit |
+| `BINARY_FILE` | File is binary format |
+| `EMPTY_FILE` | File has no content |
+| `NO_JSON_FOUND` | No valid JSON found |
+
+## Tool: jsonValidate
+
+Validate JSON data against a JSON Schema.
+
+### Signature
+```
+jsonValidate(data: string, schema: string)
+```
+
+- `data`: JSON string to validate
+- `schema`: JSON Schema string OR file path (auto-detected)
+
+### Return Format (Success)
+```json
+{
+  "success": true,
+  "data": { ... },
+  "valid": true,
+  "metadata": {
+    "errorCount": 0,
+    "schemaFeatures": {
+      "validated": ["type", "properties", "required"],
+      "ignored": ["uniqueItems"]
+    }
+  }
+}
+```
+
+> **Note:** Always check `success` first, then `valid`. If `success` is true and `errorCount` is 0, the validation passed regardless of `valid` field presence.
+
+### Return Format (Validation Errors)
+```json
+{
+  "success": true,
+  "data": null,
+  "valid": false,
+  "errors": [
+    {
+      "path": "summaries.0.row_number",
+      "message": "Expected number, received string",
+      "code": "invalid_type",
+      "expected": "number",
+      "received": "string"
+    }
+  ],
+  "metadata": {
+    "errorCount": 1
+  }
+}
+```
+
+### Examples
+
+```
+# Validate with inline schema
+jsonValidate(
+  data='{"name": "test", "age": 30}',
+  schema='{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "number"}}}'
+)
+
+# Validate with schema file
+jsonValidate(
+  data='{"batch_number": 1, "summaries": [...]}',
+  schema='./schemas/batch_output.schema.json'
+)
+```
+
+### Unsupported Schema Features
+- `not`, `unevaluatedItems`, `unevaluatedProperties`
+- `if`, `then`, `else`, `dependentSchemas`
+
+### Silently Ignored Features
+- `uniqueItems`, `contains`, `minContains`, `maxContains`
+
+## Tool: jsonInfer
+
+Generate a JSON Schema from example data.
+
+### Signature
+```
+jsonInfer(data: string, strict: boolean = false)
+```
+
+- `data`: Example JSON string
+- `strict`: If true, all fields required at all levels; if false, only top-level required array is omitted (nested objects may still have required fields)
+
+### Return Format
+```json
+{
+  "success": true,
+  "data": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "age": { "type": "integer" }
+    },
+    "required": ["name", "age"]
+  },
+  "metadata": {
+    "inferredType": "object",
+    "strictMode": true
+  }
+}
+```
+
+### Examples
+
+```
+# Infer schema from example (optional fields)
+jsonInfer(data='{"name": "Alice", "age": 30}', strict=false)
+
+# Infer schema with required fields
+jsonInfer(data='{"batch_number": 1, "summaries": [{"row": 1, "value": "test"}]}', strict=true)
+```
+
+### Warnings
+- `MIXED_TYPE_ARRAY`: Array contains multiple types
+- `EMPTY_ARRAY`: Cannot infer element type
+- `PARTIAL_OBJECT_SCHEMA`: Object has many properties
+
+### Generated Constraints
+
+jsonInfer may add the following constraints automatically:
+
+| Type | Constraint | Value | Purpose |
+|------|------------|-------|---------|
+| integer | minimum/maximum | ±9007199254740991 | JavaScript safe integer range |
+
+> **Note:** These constraints ensure JSON compatibility but may be overly restrictive for your use case. Remove them from the generated schema if not needed.
+
+## Common Workflows
+
+### Validate Subagent Output
+
+```
+# 1. Extract JSON from output file
+result = jsonExtract(file_path="./outputs/batch001.md")
+if not result.success:
+    log_error("Failed to extract JSON")
+    return
+
+# 2. Validate against expected schema
+validation = jsonValidate(
+    data=json.dumps(result.data),
+    schema=batch_output_schema
+)
+
+if not validation.valid:
+    log_error(f"Validation failed: {validation.errors}")
+    return
+
+# 3. Process validated data
+process(result.data)
+```
+
+### Infer Schema from Example
+
+```
+# 1. Get first valid output
+result = jsonExtract(file_path="./outputs/batch001.md")
+
+# 2. Infer schema from example
+schema_result = jsonInfer(
+    data=json.dumps(result.data),
+    strict=true
+)
+
+# 3. Use inferred schema for validation
+inferred_schema = json.dumps(schema_result.data)
+
+# 4. Validate other outputs
+for file in other_files:
+    data = jsonExtract(file_path=file)
+    validation = jsonValidate(
+        data=json.dumps(data.data),
+        schema=inferred_schema
+    )
+```
+
+### Combine Multiple JSON Files
+
+```
+# 1. Extract all JSON objects
+all_data = []
+for file in output_files:
+    result = jsonExtract(file_path=file, return_all=true)
+    if result.success:
+        all_data.extend(result.data)
+
+# 2. Create combined output
+tableCreateFile(
+    file_path="./combined.xlsx",
+    sheet_name="Results",
+    data=all_data
+)
+```
+
+## Best Practices
+
+1. **Always check success**: Check `result.success` before using `result.data`
+2. **Handle errors gracefully**: Log errors and continue with other files
+3. **Use strict mode for inference**: When you know all fields are required
+4. **Validate early**: Validate before processing to catch errors early
+5. **Keep schemas simple**: Avoid unsupported schema features

package/dist/skills/bioresearcher-core/patterns/progress.md

@@ -0,0 +1,127 @@
+# Progress Pattern
+
+Track and report progress at configurable intervals during batch operations.
+
+## Overview
+
+Use this pattern when processing multiple items to provide user feedback on completion status.
+
+## Pattern Algorithm
+
+```
+1. Initialize: total = N, completed = 0, report_interval = M
+2. For each item:
+   a. Process item
+   b. completed += 1
+   c. If completed % report_interval == 0 OR completed == total:
+      - Use calculator: percent = (completed / total) * 100
+      - Report: "Progress: X/Y (Z%)"
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `total` | Required | Total number of items to process |
+| `completed` | 0 | Items processed so far |
+| `report_interval` | 3 | Report every N items |
+
+## Tool: calculator
+
+```
+calculator(formula: string, precision: number = 3)
+```
+
+- Supported: +, -, *, /, ^, brackets, scientific notation
+- **MUST** use explicit * for multiplication: `2*(3)` not `2(3)`
+
+## Example: Batch Processing Progress
+
+```
+# Configuration
+total = 100
+completed = 0
+report_interval = 10
+
+# Processing loop
+for item in items:
+    process(item)
+    completed += 1
+    
+    if completed % report_interval == 0 or completed == total:
+        percent = calculator(formula="(completed / total) * 100", precision=1)
+        report("Progress: {completed}/{total} ({percent}%)")
+```
+
+## Example: Wave-Based Progress
+
+For subagent waves (3 subagents per wave):
+
+```
+# Configuration
+total_waves = 4
+completed_waves = 0
+total_batches = 12
+completed_batches = 0
+
+# After each wave completes
+completed_waves += 1
+completed_batches += 3
+percent = calculator(formula="({completed_batches} / {total_batches}) * 100")
+
+report("Progress: {completed_batches}/{total_batches} batches ({percent}%)")
+```
+
+## Progress Report Format
+
+Standard format for consistency:
+
+```
+Progress: X/Y batches completed (Z%)
+```
+
+Examples:
+- "Progress: 3/10 batches completed (30%)"
+- "Progress: 6/10 batches completed (60%)"
+- "Progress: 10/10 batches completed (100%)"
+
+## Percentage Calculation
+
+Use the calculator tool:
+
+```
+calculator(formula="(45 / 100) * 100", precision=1)
+# Returns: { "formula": "(45 / 100) * 100", "result": 45 }
+```
+
+## Example: Time Estimation
+
+```
+# Track start time and items per minute
+start_time = current_time()
+items_per_minute = 10
+
+# Calculate remaining time
+remaining_items = total - completed
+remaining_minutes = calculator(
+    formula="remaining_items / items_per_minute",
+    precision=0
+)
+
+report("Progress: {completed}/{total} ({percent}%) - ~{remaining_minutes} min remaining")
+```
+
+## Integration with Other Patterns
+
+| Pattern | Integration |
+|---------|-------------|
+| `retry.md` | Count retries in progress |
+| `subagent-waves.md` | Report after each wave |
+| `calculator.md` | Calculate percentages |
+
+## Best Practices
+
+1. **Report at meaningful intervals**: Not too frequent (spam) or too sparse (silent)
+2. **Include totals**: Always show X/Y format
+3. **Round percentages**: Use precision=0 or precision=1
+4. **Final report**: Always report 100% completion

package/dist/skills/bioresearcher-core/patterns/retry.md

@@ -0,0 +1,110 @@
+# Retry Pattern
+
+Retry failed operations with configurable delays and backoff.
+
+## Overview
+
+Use this pattern when operations may fail transiently (network issues, API rate limits, temporary resource unavailability).
+
+## Pattern Algorithm
+
+```
+1. Initialize: attempts = 0, max_attempts = N, delay = D, backoff_factor = B
+2. Attempt operation
+3. If success -> continue with workflow
+4. If failure:
+   a. attempts += 1
+   b. If attempts < max_attempts:
+      - Use blockingTimer(delay=D)
+      - delay = delay * backoff_factor
+      - Retry from step 2
+   c. If attempts >= max_attempts:
+      - Report failure or ask user via question tool
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_attempts` | 3 | Maximum retry attempts |
+| `delay` | 2 | Initial wait time in seconds |
+| `backoff_factor` | 1 | Multiply delay after each failure (1 = constant delay) |
+
+## Tool: blockingTimer
+
+```
+blockingTimer(delay: number)
+```
+
+- Maximum delay: 300 seconds
+- Returns: "Timer completed: waited X seconds (actual elapsed: Ys)"
+
+## Example: Constant Delay Retry
+
+```
+# Retry configuration
+max_attempts = 3
+delay = 2
+attempts = 0
+
+# Attempt loop
+while attempts < max_attempts:
+    result = attempt_operation()
+    if result.success:
+        break
+    attempts += 1
+    if attempts < max_attempts:
+        blockingTimer(delay=2)  # Wait 2 seconds
+```
+
+## Example: Exponential Backoff Retry
+
+```
+# Retry configuration
+max_attempts = 4
+delay = 1
+backoff_factor = 2
+attempts = 0
+
+# Attempt loop
+while attempts < max_attempts:
+    result = attempt_operation()
+    if result.success:
+        break
+    attempts += 1
+    if attempts < max_attempts:
+        blockingTimer(delay=delay)
+        delay = delay * backoff_factor  # 1, 2, 4, 8...
+```
+
+## When to Use
+
+| Scenario | delay | backoff_factor | max_attempts |
+|----------|-------|----------------|--------------|
+| Network timeout | 2 | 1 | 3 |
+| API rate limit | 5 | 2 | 4 |
+| File lock | 1 | 1 | 5 |
+| Resource unavailable | 2 | 2 | 4 |
+
+## User Notification on Persistent Failure
+
+After all retries exhausted, use `question` tool:
+
+```
+question(questions=[{
+  "header": "Retry failed",
+  "question": "Operation failed after 3 attempts. How would you like to proceed?",
+  "options": [
+    {"label": "Retry now", "description": "Try one more time immediately"},
+    {"label": "Skip", "description": "Skip this item and continue"},
+    {"label": "Abort", "description": "Stop the entire workflow"}
+  ]
+}])
+```
+
+## Important Notes
+
+1. **Maximum delay**: blockingTimer caps at 300 seconds
+2. **Backoff calculation**: Use `calculator` tool if needed
+3. **State tracking**: Track attempts in your workflow state
+4. **Error logging**: Log failure reasons for debugging

package/dist/skills/bioresearcher-core/patterns/shell-commands.md

@@ -0,0 +1,79 @@
+# Shell Commands Pattern
+
+Generate shell commands using forward slashes for cross-platform compatibility.
+
+## Overview
+
+Forward slashes (`/`) work on all major platforms:
+- Unix-like (Linux, macOS): Native support
+- Windows (Git Bash): Native support
+- Windows (Python): Native support via `os.path`
+- Windows (cmd.exe): Supported in most contexts
+
+## Recommendation
+
+**Use forward slashes (`/`) universally** for maximum compatibility.
+
+## Examples
+
+### Python Script Execution
+```bash
+uv run python <skill_path>/script.py --input ./data/file.csv --output ./results/output.xlsx
+```
+
+### Directory Creation
+```bash
+mkdir -p .work/subdir1 .work/subdir2
+```
+
+### File Listing
+```bash
+ls -la ./work/outputs/
+```
+
+### For Loop
+```bash
+for file in file1.txt file2.txt file3.txt; do
+  uv run python <skill_path>/process.py "$file"
+done
+```
+
+### JSON String Arguments
+```bash
+uv run python script.py --data '{"key": "value"}'
+```
+
+### Environment Variables
+```bash
+export MY_VAR=value
+uv run python script.py
+```
+
+## Windows Edge Cases
+
+In rare cases, Windows cmd.exe may not support forward slashes:
+
+| Command | Forward Slash | Alternative |
+|---------|---------------|-------------|
+| `dir` | Works | `dir ./folder` |
+| `mkdir` | `mkdir -p` fails | Use Python: `python -c "import os; os.makedirs('./folder', exist_ok=True)"` |
+| `copy` | Works | `copy ./src/file.txt ./dest/` |
+| `del` | Works | `del ./folder/file.txt` |
+
+> **Note:** If using pure cmd.exe (not Git Bash), the `-p` flag for `mkdir` is not supported. Use Python's `os.makedirs()` instead.
+
+## Path Handling Guidelines
+
+1. **Always use forward slashes** (`/`) in paths
+2. **Quote paths with spaces** in all contexts
+3. **Use relative paths** from project root when possible
+4. **Python paths**: Forward slashes work on all platforms
+5. **Skill path placeholder**: Replace `<skill_path>` with actual path from skill tool output
+
+## Best Practices
+
+1. **Default to forward slashes** - works 99% of the time
+2. **Test on target platform** if edge cases suspected
+3. **Use Python alternatives** for complex file operations
+4. **Quote all paths** to handle spaces safely
+5. **Avoid cmd.exe-specific syntax** (like `^` line continuation)