33 lines
1.6 KiB
Markdown
33 lines
1.6 KiB
Markdown
# [DEF:Std:Plugin:Standard]
|
|
# @TIER: CRITICAL
|
|
# @PURPOSE: Standards for building and integrating Plugins.
|
|
# @LAYER: Domain (Plugin)
|
|
# @INVARIANT: All plugins MUST inherit from `PluginBase`.
|
|
# @INVARIANT: All plugins MUST be located in `backend/src/plugins/`.
|
|
|
|
## 1. PLUGIN CONTRACT
|
|
Every plugin must implement the following properties and methods:
|
|
* `id`: Unique string (e.g., `"my-plugin"`).
|
|
* `name`: Human-readable name.
|
|
* `description`: Brief purpose.
|
|
* `version`: Semantic version.
|
|
* `get_schema()`: Returns JSON schema for input validation.
|
|
* `execute(params: Dict[str, Any], context: TaskContext)`: Core async logic.
|
|
|
|
## 2. STRUCTURED LOGGING (TASKCONTEXT)
|
|
Plugins MUST use `TaskContext` for logging to ensure proper source attribution:
|
|
* **Source Attribution:** Use `context.logger.with_source("src_name")` for specific operations (e.g., `"superset_api"`, `"git"`, `"llm"`).
|
|
* **Levels:**
|
|
* `DEBUG`: Detailed diagnostics (API responses).
|
|
* `INFO`: Operational milestones (start/end).
|
|
* `WARNING`: Recoverable issues.
|
|
* `ERROR`: Failures stopping execution.
|
|
* **Progress:** Use `context.logger.progress("msg", percent=XX)` for long-running tasks.
|
|
|
|
## 3. BEST PRACTICES
|
|
1. **Asynchronous Execution:** Always use `async/await` for I/O operations.
|
|
2. **Schema Validation:** Ensure the `get_schema()` precisely matches the `execute()` input expectations.
|
|
3. **Isolation:** Plugins should be self-contained and not depend on other plugins directly. Use core services (`ConfigManager`, `TaskManager`) via dependency injection or the provided `context`.
|
|
|
|
# [/DEF:Std:Plugin]
|