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分で具体化したもの。実装の現実性と革新性を両立した世界初級ツールの仕様です。
|