BizCity Twin Plugin Standard β v2.0
> **TiΓͺu chuαΊ©n chung cho tαΊ₯t cαΊ£ plugin tΓch hợp BizCity Twin Core**
> **PhiΓͺn bαΊ£n**: 2.0 | **Thα»i gian**: 2026-03-27
> **Scope**: Plugin architecture, Provider contracts, API standardization, SSE streaming, UI/UX patterns
> **Γp dα»₯ng cho**: bizcity-tool-* | bizcity-automation-* | bizcity-studio-* | legacy integration
---
1. Overview β 3 Layer Plugin Architecture
<br />
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ<br />
β TWIN PLUGIN ARCHITECTURE (3 LAYER) β<br />
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€<br />
β β<br />
β π¨ LAYER 1: UI/UX β Touch Bar + Agent Profile β<br />
β ββ Touch Bar iframe β guided commands (/slash notation) β<br />
β ββ Quick Chat shortcuts β payload standardization β<br />
β ββ Welcome shortcuts (React) β mention @tool reference β<br />
β β<br />
β βοΈ LAYER 2: Intent & Automation Provider β<br />
β ββ Intent mapping (chat/execution/planning modes) β<br />
β ββ Tool registration in Twin Core registry β<br />
β ββ Slot collection + Planner hooks β<br />
β ββ Job Trace for step-by-step execution β<br />
β β<br />
β π¬ LAYER 3: Studio Provider & Output Embedding β<br />
β ββ Output formatter (markdown/rich HTML) β<br />
β ββ Studio component (React) for preview/edit β<br />
β ββ Persistence to Notebook β<br />
β ββ Export & Share integration β<br />
β β<br />
β π‘ SSE MODE: Real-time Streaming β<br />
β ββ Job events ("step_complete", "tool_executed", etc) β<br />
β ββ Frontend listens & renders live progress β<br />
β ββ Error recovery & state sync β<br />
β β<br />
β π API GATEWAY: Plugin Registry & Bridge β<br />
β ββ Plugin discovery (featured/automation/studio flags) β<br />
β ββ API method extraction (WordPress REST / custom RPC) β<br />
β ββ Tool contract validation (inputs/outputs schemas) β<br />
β β<br />
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ<br />
---
2. Core Principles
β **Slash Command Standard**: All quick prompts and shortcuts MUST resolve to `/tool_name base_text` format
β **Capability Declaration**: Every plugin MUST declare machine-readable metadata (featured, automation_ready, studio_ready, sse_streaming, api_version)
β **Unified Output Envelope**: Tool execution MUST follow ONE output structure + ONE SSE event contract
β **Mode-Aware Context**: Context injection MUST use Twin resolver contracts (chat/knowledge/execution/planning/emotion)
β **Contract-First APIs**: All plugin APIs MUST be discoverable via Gateway + standardized inspection
β **Payload Standardization**: postMessage from profile MUST include: type, source, plugin_slug, tool_name, text
---
3. Quick Prompt Standard β Slash + Mention
All clickable shortcut elements MUST build and send slash commands:
HTML Markup (page-agent-profile.php)
html<br />
<div data-msg="ViαΊΏt bΓ i vα» dinh dΖ°α»‘ng" data-tool="tool_content" data-plugin="bizcity-tool-content"></div><br />
Client send payload standard:
js<br />
window.parent.postMessage({<br />
type: 'bizcity_agent_command',<br />
source: 'bizcity-tool-content',<br />
plugin_slug: 'bizcity-tool-content',<br />
tool_name: 'write_article',<br />
text: '/write_article ViαΊΏt bΓ i vα» dinh dΖ°α»‘ng'<br />
}, '*');<br />
Normalization rule:
- If text does not start with / and tool_name exists, prepend `/{tool_name}`.
- If source exists but tool_name missing, receiver may infer main_tool from plugin metadata.
---
4) Intent Provider Standard
Intent provider must define:
- id, name, patterns, plans, tools
- capabilities block (section 2)
- context() for mode-aware context enrichment
- optional gateway contract mapping (section 9)
Minimal tools schema requirement:
php<br />
'tools' => [<br />
'write_article' => [<br />
'label' => 'Write and publish article',<br />
'schema' => [<br />
'description' => 'Generate article and publish to WordPress',<br />
'input_fields' => [<br />
'topic' => [ 'required' => true, 'type' => 'text' ],<br />
],<br />
],<br />
'callback' => [ 'BizCity_Tool_Content', 'write_article' ],<br />
],<br />
],<br />
---
5) Automation Provider Standard
Automation provider must expose:
- node catalog entry with stable node_id
- input/output schema
- deterministic tool binding to main_tool and secondary tools
- compensation strategy for retry/failure
Required fields:
php<br />
[<br />
'node_id' => 'tool-content.write_article',<br />
'tool_name' => 'write_article',<br />
'provider_id' => 'tool-content',<br />
'supports_retry' => true,<br />
'supports_idempotency' => true,<br />
]<br />
---
6) Studio Provider Standard
Studio integration must declare:
- available actions
- input panel schema
- preview renderer
- output artifact type
Required metadata:
php<br />
[<br />
'studio_action' => 'content.write',<br />
'artifact_type' => 'article',<br />
'editable' => true,<br />
'stream_mode' => 'step+delta',<br />
]<br />
---
7) BizChat Menu Registration Standard
Use centralized hook:
php<br />
add_action('bizchat_register_menus', function($menu) {<br />
$menu->add([<br />
'id' => 'tool-content',<br />
'title' => 'Tool Content',<br />
'parent' => 'bizchat',<br />
'capability' => 'read',<br />
'position' => 80,<br />
]);<br />
});<br />
Rules:
- Do not register direct top-level menu for BizChat tools.
- Keep menu IDs stable and slug-safe.
---
8) SSE Stream Mode Standard
Tool pipelines should emit stream events in this order:
1. trace_begin
2. step events (pending/running/done or failed)
3. optional partial delta events
4. trace_end
Common event payload:
json<br />
{<br />
"event": "tool_trace",<br />
"tool_name": "write_article",<br />
"step": "T2",<br />
"status": "running",<br />
"message": "Generating outline"<br />
}<br />
Requirements:
- send `tool_name` and stable `trace_id`
- include status transitions, not only done state
- send fail event before terminating stream on error
---
9) Context Contract (Twin Resolver)
All AI-calling tool callbacks must consume `_meta`:
php<br />
$meta = $slots['_meta'] ?? [];<br />
$ai_context = $meta['_context'] ?? '';<br />
Context usage policy:
- append ai_context to system prompt when non-empty
- do not mutate or return `_meta` in tool output
- use mode-aware behavior (emotion/knowledge/planning/execution/studio)
---
10) API Integration Contract (Gateway Bridge)
Every tool should optionally define an API contract block to support gateway orchestration:
php<br />
'gateway_contract' => [<br />
'contract_version' => '1.0',<br />
'endpoint' => '/tool-content/v1/write-article',<br />
'method' => 'POST',<br />
'input_schema_ref' => 'tool-content.write-article.input',<br />
'output_schema_ref' => 'tool-content.write-article.output',<br />
'hil_points' => [ 'before_publish' ],<br />
],<br />
Benefits:
- API-first wrappers for legacy WordPress handlers
- deterministic registry map from contract
- HIL and slot collection inferred from schema
---
11) Loader Information Standard
Plugin loader should expose normalized info object:
php<br />
[<br />
'slug' => 'bizcity-tool-content',<br />
'role' => 'tool',<br />
'featured' => true,<br />
'supports_studio' => true,<br />
'supports_automation' => true,<br />
'main_tool' => 'write_article',<br />
'template_page' => 'tool-content',<br />
]<br />
---
12) Legacy Wrapper Standard
For old plugins in WordPress legacy:
- keep old callback intact
- wrap with contract adapter
- map old args to schema input
- map old result to output envelope
Wrapper naming:
- `Legacy_{Plugin}_Gateway_Adapter`
- `Legacy_{Plugin}_Contract_Map`
---
13) Compliance Checklist
- Shortcut click sends slash-prefixed message
- Shortcut payload includes tool_name + plugin_slug
- Provider declares capabilities
- main_tool declared and valid in tools map
- SSE emits trace begin/step/end
- Tool callback reads `_meta` and `_context`
- Tool output envelope contract satisfied
- Menu registered via bizchat_register_menus
- Optional API contract block added
---
14) Migration Plan for Existing Plugins
1. Add capabilities and main_tool metadata
2. Add shortcut payload normalization in profile pages
3. Add tool_name/plugin_slug to postMessage payloads
4. Add gateway_contract block for each main tool
5. Add automation/studio metadata
6. Verify SSE event compliance
7. Register BizChat menu entry
---
15) References
- core/intent/PLUGIN-STANDARD.md
- plugins/bizcity-tool-content/PLUGIN-STANDARD.md
- scaffold/views/page-agent-profile.php
- IMPLEMENTATION-ROADMAP.md