feat: implement plugin architecture and application settings with Svelte UI
- Added plugin base and loader for backend extensibility - Implemented application settings management with config persistence - Created Svelte-based frontend with Dashboard and Settings pages - Added API routes for plugins, tasks, and settings - Updated documentation and specifications - Improved project structure and developer tools
This commit is contained in:
298
semantic_protocol.md
Normal file → Executable file
298
semantic_protocol.md
Normal file → Executable file
@@ -1,124 +1,174 @@
|
||||
# SYSTEM STANDARD: CODE GENERATION PROTOCOL
|
||||
|
||||
**OBJECTIVE:** Generate Python code that strictly adheres to the Semantic Coherence standards defined below. All output must be machine-readable, fractal-structured, and optimized for Sparse Attention navigation.
|
||||
|
||||
## I. CORE REQUIREMENTS
|
||||
1. **Causal Validity:** Semantic definitions (Contracts) must ALWAYS precede implementation code.
|
||||
2. **Immutability:** Once defined, architectural decisions in the Module Header are treated as immutable constraints.
|
||||
3. **Format Compliance:** Output must strictly follow the `[DEF]` / `[/DEF]` anchor syntax.
|
||||
|
||||
---
|
||||
|
||||
## II. SYNTAX SPECIFICATION
|
||||
|
||||
Code must be wrapped in semantic anchors using square brackets to minimize token interference.
|
||||
|
||||
### 1. Entity Anchors (The "Container")
|
||||
* **Start:** `# [DEF:identifier:Type]`
|
||||
* **End:** `# [/DEF:identifier]` (MANDATORY for semantic accumulation)
|
||||
* **Types:** `Module`, `Class`, `Function`, `DataClass`, `Enum`.
|
||||
|
||||
### 2. Metadata Tags (The "Content")
|
||||
* **Syntax:** `# @KEY: Value`
|
||||
* **Location:** Inside the `[DEF]` block, before any code.
|
||||
|
||||
### 3. Graph Relations (The "Map")
|
||||
* **Syntax:** `# @RELATION: TYPE -> TARGET_ID`
|
||||
* **Types:** `DEPENDS_ON`, `CALLS`, `INHERITS_FROM`, `IMPLEMENTS`, `WRITES_TO`, `READS_FROM`.
|
||||
|
||||
---
|
||||
|
||||
## III. FILE STRUCTURE STANDARD
|
||||
|
||||
### 1. Python Module Header
|
||||
Every `.py` file starts with a Module definition.
|
||||
|
||||
```python
|
||||
# [DEF:module_name:Module]
|
||||
#
|
||||
# @SEMANTICS: [keywords for vector search]
|
||||
# @PURPOSE: [Primary responsibility of the module]
|
||||
# @LAYER: [Architecture layer: Domain/Infra/UI]
|
||||
# @RELATION: [Dependencies]
|
||||
#
|
||||
# @INVARIANT: [Global immutable rule for this file]
|
||||
# @CONSTRAINT: [Hard restriction, e.g., "No SQL here"]
|
||||
# @PUBLIC_API: [Exported symbols]
|
||||
|
||||
# [SECTION: IMPORTS]
|
||||
...
|
||||
# [/SECTION]
|
||||
|
||||
# ... IMPLEMENTATION ...
|
||||
|
||||
# [/DEF:module_name]
|
||||
```
|
||||
|
||||
### 2. Svelte Component Header
|
||||
Every `.svelte` file starts with a Component definition inside an HTML comment.
|
||||
|
||||
```html
|
||||
<!--
|
||||
[DEF:ComponentName:Component]
|
||||
@SEMANTICS: [keywords]
|
||||
@PURPOSE: [Primary responsibility]
|
||||
@LAYER: [UI/State/Layout]
|
||||
@RELATION: [Child components, Stores, API]
|
||||
|
||||
@PROPS:
|
||||
- name: type - description
|
||||
@EVENTS:
|
||||
- name: payload_type - description
|
||||
@INVARIANT: [Immutable UI rule]
|
||||
-->
|
||||
<script>
|
||||
// ...
|
||||
</script>
|
||||
<!-- [/DEF:ComponentName] -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IV. FUNCTION & CLASS CONTRACTS (DbC)
|
||||
|
||||
Contracts are the **Source of Truth**.
|
||||
|
||||
**Required Template:**
|
||||
```python
|
||||
# [DEF:func_name:Function]
|
||||
# @PURPOSE: [Description]
|
||||
# @SPEC_LINK: [Requirement ID]
|
||||
#
|
||||
# @PRE: [Condition required before execution]
|
||||
# @POST: [Condition guaranteed after execution]
|
||||
# @PARAM: [name] ([type]) - [desc]
|
||||
# @RETURN: [type] - [desc]
|
||||
# @THROW: [Exception] - [Reason]
|
||||
#
|
||||
# @RELATION: [Graph connections]
|
||||
def func_name(...):
|
||||
# 1. Runtime check of @PRE
|
||||
# 2. Logic implementation
|
||||
# 3. Runtime check of @POST
|
||||
pass
|
||||
# [/DEF:func_name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## V. LOGGING STANDARD (BELIEF STATE)
|
||||
|
||||
Logs define the agent's internal state for debugging and coherence checks.
|
||||
|
||||
**Format:** `logger.level(f"[{ANCHOR_ID}][{STATE}] {MESSAGE} context={...}")`
|
||||
|
||||
**States:** `Entry`, `Validation`, `Action`, `Coherence:OK`, `Coherence:Failed`, `Exit`.
|
||||
|
||||
---
|
||||
|
||||
## VI. GENERATION WORKFLOW
|
||||
1. **Analyze Request:** Identify target module and graph position.
|
||||
2. **Define Structure:** Generate `[DEF]` anchors and Contracts FIRST.
|
||||
3. **Implement Logic:** Write code satisfying Contracts.
|
||||
4. **Validate:** If logic conflicts with Contract -> Stop -> Report Error.
|
||||
|
||||
Here is the revised **System Standard**, adapted for a Polyglot environment (Python Backend + Svelte Frontend) and removing the requirement for explicit assertion generation.
|
||||
|
||||
This protocol standardizes the "Semantic Bridge" between the two languages using unified Anchor logic while respecting the native documentation standards (Comments for Python, JSDoc for JavaScript/Svelte).
|
||||
|
||||
***
|
||||
|
||||
# SYSTEM STANDARD: POLYGLOT CODE GENERATION PROTOCOL (GRACE-Poly)
|
||||
|
||||
**OBJECTIVE:** Generate Python and Svelte/TypeScript code that strictly adheres to Semantic Coherence standards. Output must be machine-readable, fractal-structured, and optimized for Sparse Attention navigation.
|
||||
|
||||
## I. CORE REQUIREMENTS
|
||||
1. **Causal Validity:** Semantic definitions (Contracts) must ALWAYS precede implementation code.
|
||||
2. **Immutability:** Architectural decisions defined in the Module/Component Header are treated as immutable constraints.
|
||||
3. **Format Compliance:** Output must strictly follow the `[DEF]` / `[/DEF]` anchor syntax for structure.
|
||||
4. **Logic over Assertion:** Contracts define the *logic flow*. Do not generate explicit `assert` statements unless requested. The code logic itself must inherently satisfy the Pre/Post conditions (e.g., via control flow, guards, or types).
|
||||
|
||||
---
|
||||
|
||||
## II. SYNTAX SPECIFICATION
|
||||
|
||||
Code structure is defined by **Anchors** (square brackets). Metadata is defined by **Tags** (native comment style).
|
||||
|
||||
### 1. Entity Anchors (The "Container")
|
||||
Used to define the boundaries of Modules, Classes, Components, and Functions.
|
||||
|
||||
* **Python:**
|
||||
* Start: `# [DEF:identifier:Type]`
|
||||
* End: `# [/DEF:identifier]`
|
||||
* **Svelte (Top-level):**
|
||||
* Start: `<!-- [DEF:ComponentName:Component] -->`
|
||||
* End: `<!-- [/DEF:ComponentName] -->`
|
||||
* **Svelte (Script/JS/TS):**
|
||||
* Start: `// [DEF:funcName:Function]`
|
||||
* End: `// [/DEF:funcName]`
|
||||
|
||||
**Types:** `Module`, `Component`, `Class`, `Function`, `Store`, `Action`.
|
||||
|
||||
### 2. Graph Relations (The "Map")
|
||||
Defines high-level dependencies.
|
||||
* **Python Syntax:** `# @RELATION: TYPE -> TARGET_ID`
|
||||
* **Svelte/JS Syntax:** `// @RELATION: TYPE -> TARGET_ID`
|
||||
* **Types:** `DEPENDS_ON`, `CALLS`, `INHERITS_FROM`, `IMPLEMENTS`, `BINDS_TO`, `DISPATCHES`.
|
||||
|
||||
---
|
||||
|
||||
## III. FILE STRUCTURE STANDARD
|
||||
|
||||
### 1. Python Module Header (`.py`)
|
||||
```python
|
||||
# [DEF:module_name:Module]
|
||||
#
|
||||
# @SEMANTICS: [keywords for vector search]
|
||||
# @PURPOSE: [Primary responsibility of the module]
|
||||
# @LAYER: [Domain/Infra/API]
|
||||
# @RELATION: [Dependencies]
|
||||
#
|
||||
# @INVARIANT: [Global immutable rule]
|
||||
# @CONSTRAINT: [Hard restriction, e.g., "No ORM calls here"]
|
||||
|
||||
# [SECTION: IMPORTS]
|
||||
...
|
||||
# [/SECTION]
|
||||
|
||||
# ... IMPLEMENTATION ...
|
||||
|
||||
# [/DEF:module_name]
|
||||
```
|
||||
|
||||
### 2. Svelte Component Header (`.svelte`)
|
||||
```html
|
||||
<!-- [DEF:ComponentName:Component] -->
|
||||
<!--
|
||||
@SEMANTICS: [keywords]
|
||||
@PURPOSE: [Primary UI responsibility]
|
||||
@LAYER: [Feature/Atom/Layout]
|
||||
@RELATION: [Child components, Stores]
|
||||
|
||||
@INVARIANT: [UI rules, e.g., "Always responsive"]
|
||||
-->
|
||||
|
||||
<script lang="ts">
|
||||
// [SECTION: IMPORTS]
|
||||
// ...
|
||||
// [/SECTION]
|
||||
|
||||
// ... LOGIC IMPLEMENTATION ...
|
||||
</script>
|
||||
|
||||
<!-- [SECTION: TEMPLATE] -->
|
||||
...
|
||||
<!-- [/SECTION] -->
|
||||
|
||||
<style>
|
||||
/* ... */
|
||||
</style>
|
||||
|
||||
<!-- [/DEF:ComponentName] -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IV. CONTRACTS (Design by Contract)
|
||||
|
||||
Contracts define *what* the code does before *how* it does it.
|
||||
|
||||
### 1. Python Contract Style
|
||||
Uses comment blocks inside the anchor.
|
||||
|
||||
```python
|
||||
# [DEF:calculate_total:Function]
|
||||
# @PURPOSE: Calculates cart total including tax.
|
||||
# @PRE: items list is not empty.
|
||||
# @POST: returns non-negative Decimal.
|
||||
# @PARAM: items (List[Item]) - Cart items.
|
||||
# @RETURN: Decimal - Final total.
|
||||
def calculate_total(items: List[Item]) -> Decimal:
|
||||
# Logic implementation that respects @PRE
|
||||
if not items:
|
||||
return Decimal(0)
|
||||
|
||||
# ... calculation ...
|
||||
|
||||
# Logic ensuring @POST
|
||||
return total
|
||||
# [/DEF:calculate_total]
|
||||
```
|
||||
|
||||
### 2. Svelte/JS Contract Style (JSDoc)
|
||||
Uses JSDoc blocks inside the anchor. Standard JSDoc tags are used where possible; custom GRACE tags are added for strictness.
|
||||
|
||||
```javascript
|
||||
// [DEF:updateUserProfile:Function]
|
||||
/**
|
||||
* @purpose Updates user data in the store and backend.
|
||||
* @pre User must be authenticated (session token exists).
|
||||
* @post UserStore is updated with new data.
|
||||
* @param {Object} profileData - The new profile fields.
|
||||
* @returns {Promise<void>}
|
||||
* @throws {AuthError} If session is invalid.
|
||||
*/
|
||||
// @RELATION: CALLS -> api.user.update
|
||||
async function updateUserProfile(profileData) {
|
||||
// Logic implementation
|
||||
if (!session.token) throw new AuthError();
|
||||
|
||||
// ...
|
||||
}
|
||||
// [/DEF:updateUserProfile]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## V. LOGGING STANDARD (BELIEF STATE)
|
||||
|
||||
Logs delineate the agent's internal state.
|
||||
|
||||
* **Python:** `logger.info(f"[{ANCHOR_ID}][{STATE}] Msg")`
|
||||
* **Svelte/JS:** `console.log(\`[${ANCHOR_ID}][${STATE}] Msg\`)`
|
||||
|
||||
**Required States:**
|
||||
1. `Entry` (Start of block)
|
||||
2. `Action` (Key business logic)
|
||||
3. `Coherence:OK` (Logic successfully completed)
|
||||
4. `Coherence:Failed` (Error handling)
|
||||
5. `Exit` (End of block)
|
||||
|
||||
---
|
||||
|
||||
## VI. GENERATION WORKFLOW
|
||||
|
||||
1. **Context Analysis:** Identify language (Python vs Svelte) and Architecture Layer.
|
||||
2. **Scaffolding:** Generate the `[DEF]` Anchors and Header/Contract **before** writing any logic.
|
||||
3. **Implementation:** Write the code. Ensure the code logic handles the `@PRE` conditions (e.g., via `if/return` or guards) and satisfies `@POST` conditions naturally. **Do not write explicit `assert` statements unless debugging mode is requested.**
|
||||
4. **Closure:** Ensure every `[DEF]` is closed with `[/DEF]` to accumulate semantic context.
|
||||
Reference in New Issue
Block a user