145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# CAX Design Specification (ChatGPT Analysis)
|
||
|
||
**Generated by**: ChatGPT
|
||
**Date**: 2025-09-21
|
||
**Context**: 30分集中設計セッション
|
||
|
||
## 🎯 Core Vision
|
||
|
||
**Nyash C-ABI Explorer (CAX)** - GUIでC ABI境界を「ぽいっと付け外し」「視覚化」「録って再生」「スクリプトで自動化」
|
||
|
||
## 🏗️ Architecture Design
|
||
|
||
### Core + GUI 分離アーキテクチャ
|
||
```
|
||
Core (Rust/Nyash): 既存cabi-debuggerフック + IPCサーバ
|
||
↕ JSON-RPC/WebSocket
|
||
GUI (Tauri/Electron): Svelte/React/TypeScript フロントエンド
|
||
```
|
||
|
||
### データフロー
|
||
```
|
||
PluginHost.Invoke → CABIDebugger → IPC → GUI Timeline
|
||
C ABI Calls → Real-time Logs → JSON Stream → 可視化
|
||
```
|
||
|
||
## 🎨 UX Design
|
||
|
||
### 画面レイアウト (5パネル構成)
|
||
```
|
||
┌─────────────┬─────────────────┬─────────────┐
|
||
│ Explorer │ Live Timeline │ Inspector │
|
||
│ (attach/detach) │ (call flow) │ (call details)│
|
||
├─────────────┴─────────────────┴─────────────┤
|
||
│ Record/Replay Controls │
|
||
├─────────────────────────────────────────────┤
|
||
│ Console & Macros (Scripts) │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 操作体験
|
||
1. **1クリック Attach**: `map.so` の行をクリック→即時ログ流れる
|
||
2. **色分け表示**: 緑=Ok、黄=by-name、赤=Err/timeout、紫=ownership警告
|
||
3. **録画/再生**: ワンボタンでJSONL/TLV保存→プラグイン無しで再現
|
||
4. **ホットスワップ**: `disable→quiesce→reload` をGUIウィザードで
|
||
|
||
## 🔧 Technical Features
|
||
|
||
### 1. Real-time Monitoring
|
||
- **Live Timeline**: Swimlane（プラグイン別/スレッド別）
|
||
- **Call Inspector**: 引数/戻り値/実行時間/ソース位置
|
||
- **Filter System**: `outcome:warn plugin:map` 形式
|
||
|
||
### 2. Record/Replay System
|
||
```json
|
||
// ログ1行例
|
||
{
|
||
"ts": 1737153845.123456,
|
||
"plugin": "map.so",
|
||
"type_id": 17,
|
||
"method": "get/1",
|
||
"args": [{"str":"key"}],
|
||
"ret": {"str":"value"},
|
||
"outcome": "Ok",
|
||
"elapsed_us": 87,
|
||
"by_name": false,
|
||
"site": {"file":"apps/x.nyash","line":42}
|
||
}
|
||
```
|
||
|
||
### 3. Hot-Swap Management
|
||
```
|
||
安全手順: disable → wait(0 inflight) → fini → dlclose → dlopen → init → re-enable
|
||
GUI支援: 進捗表示 + state snapshot/restore（任意）
|
||
```
|
||
|
||
### 4. Macro Automation
|
||
```nyash
|
||
// CAX API例
|
||
cax.filter({outcome:'warn'})
|
||
cax.attach("map.so")
|
||
cax.replay("trace.tlv")
|
||
cax.hotswap("map.so", "/tmp/map_new.so")
|
||
```
|
||
|
||
## 📋 Implementation Roadmap
|
||
|
||
### Week 1 (MVP Core)
|
||
- ✅ IPCサーバ（subscribe/attach/detach）
|
||
- ✅ Explorer + Timeline（基本表示）
|
||
- ✅ Inspector（引数/戻り値表示）
|
||
- ✅ 記録（JSONL形式）
|
||
|
||
### Week 2 (Advanced Features)
|
||
- ✅ Signature Checker（extern宣言 vs 実装差分）
|
||
- ✅ Record/Replay（ファイル形式）
|
||
- ✅ 簡易マクロ（フィルタ・基本操作）
|
||
- ✅ Hot-swap wizard（dry-run）
|
||
|
||
## 🎨 GUI Implementation
|
||
|
||
### Technology Stack
|
||
- **Frontend**: Tauri + Svelte/React + TypeScript
|
||
- **IPC**: JSON-RPC over WebSocket
|
||
- **Styling**: TailwindCSS + 可視化ライブラリ
|
||
|
||
### Key Components
|
||
```typescript
|
||
// IPC API例
|
||
interface CaxApi {
|
||
subscribe(params: {plugins: string[], level: string}): void
|
||
attach(params: {plugin: string}): void
|
||
hotswap(params: {plugin: string, path: string}): void
|
||
record: {
|
||
start(params: {file: string}): void
|
||
stop(): void
|
||
}
|
||
replay(params: {file: string, mode: string}): void
|
||
}
|
||
```
|
||
|
||
## 🚧 Risk Mitigation
|
||
|
||
### Performance
|
||
- **オーバーヘッド**: 既定軽量（log sampling、構造化は遅延ダンプ）
|
||
- **再入防止**: スレッドローカルで抑止
|
||
|
||
### Safety
|
||
- **クラッシュ隔離**: detach≠dlclose（最初は"ロード専用"）
|
||
- **権限管理**: プロセス境界越えはエージェント方式
|
||
|
||
## 💡 Competitive Advantages
|
||
|
||
### vs 既存デバッガ
|
||
- **境界特化**: C↔Nyash境界に最適化された可視化
|
||
- **型安全**: TypeBox境界での実時間検証
|
||
- **構造化**: ライフサイクル・所有権の一元観測
|
||
|
||
### Innovation Points
|
||
- **Record/Replay**: ABIコール完全再現（回帰テスト革命）
|
||
- **GUI Integration**: コマンドライン→GUI操作の体験革新
|
||
- **Hot-Swap**: 無停止デバッグ・プラグイン更新
|
||
|
||
---
|
||
|
||
**Note**: この設計は、C ABI動的呼び出しからの1分発想を30分で具体化したもの。実装の現実性と革新性を両立した世界初級ツールの仕様です。 |