clew-code 0.2.4 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +264 -292
- package/dist/clew-dev.js +5118 -2840
- package/dist/main.js +2315 -2090
- package/docs/_config.yml +1 -1
- package/docs/architecture.html +145 -166
- package/docs/architecture.th.html +2 -23
- package/docs/commands.html +1 -22
- package/docs/commands.th.html +1 -22
- package/docs/configuration.html +145 -166
- package/docs/configuration.th.html +2 -23
- package/docs/css/styles.css +22 -0
- package/docs/daemon.html +128 -160
- package/docs/daemon.th.html +2 -30
- package/docs/features/bridge-mode.html +98 -98
- package/docs/features/bridge-mode.th.html +1 -1
- package/docs/features/evals.html +181 -181
- package/docs/features/evals.th.html +1 -1
- package/docs/features/searxng-search.html +150 -150
- package/docs/features/searxng-search.th.html +1 -1
- package/docs/features/sentry-setup.html +156 -156
- package/docs/features/sentry-setup.th.html +1 -1
- package/docs/index.html +298 -333
- package/docs/index.th.html +1 -36
- package/docs/installation.html +103 -124
- package/docs/installation.th.html +2 -23
- package/docs/internals/growthbook-ab-testing.html +112 -112
- package/docs/internals/growthbook-ab-testing.th.html +1 -1
- package/docs/internals/hidden-features.html +147 -147
- package/docs/internals/hidden-features.th.html +1 -1
- package/docs/js/main.js +78 -7
- package/docs/loop.html +180 -0
- package/docs/loop.th.html +226 -0
- package/docs/mcp.html +246 -157
- package/docs/mcp.th.html +156 -60
- package/docs/models.html +1 -22
- package/docs/models.th.html +1 -22
- package/docs/peer.html +235 -0
- package/docs/peer.th.html +279 -0
- package/docs/permission-model.html +101 -122
- package/docs/permission-model.th.html +2 -23
- package/docs/plugins.html +101 -122
- package/docs/plugins.th.html +2 -23
- package/docs/providers.html +117 -138
- package/docs/providers.th.html +2 -23
- package/docs/quick-start.html +92 -120
- package/docs/quick-start.th.html +1 -29
- package/docs/research-memory.html +79 -111
- package/docs/research-memory.th.html +2 -30
- package/docs/skills.html +116 -137
- package/docs/skills.th.html +2 -23
- package/docs/taste.html +96 -29
- package/docs/taste.th.html +193 -54
- package/docs/tools.html +169 -190
- package/docs/tools.th.html +2 -23
- package/docs/troubleshooting.html +105 -126
- package/docs/troubleshooting.th.html +2 -23
- package/package.json +5 -3
package/docs/mcp.th.html
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="UTF-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<title>MCP — Clew</title>
|
|
7
|
-
<meta name="description" content="
|
|
6
|
+
<title>MCP — Clew Code</title>
|
|
7
|
+
<meta name="description" content="Model Context Protocol (MCP) — เชื่อมต่อเครื่องมือภายนอก, ทรัพยากร, และบริการ ผ่าน stdio, SSE, และ OAuth">
|
|
8
8
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
9
9
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
10
10
|
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Noto+Sans+Thai:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
@@ -12,35 +12,7 @@
|
|
|
12
12
|
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
|
15
|
-
<header class="header">
|
|
16
|
-
<div class="header-inner">
|
|
17
|
-
<a href="index.th.html" class="logo">
|
|
18
|
-
<span>Clew Code</span>
|
|
19
|
-
</a>
|
|
20
|
-
<nav class="header-nav">
|
|
21
|
-
<a href="index.th.html">หน้าแรก</a><a href="index.th.html#features">ฟีเจอร์</a><a href="index.th.html#commands">คำสั่ง</a><a href="quick-start.th.html" class="active">เอกสาร</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a>
|
|
22
|
-
<div class="lang-wrap">
|
|
23
|
-
<button class="lang-btn">🌐</button>
|
|
24
|
-
<div class="lang-menu">
|
|
25
|
-
<a href="../readme/README.zh.md">中文</a>
|
|
26
|
-
<a href="../readme/README.th.md">ไทย</a>
|
|
27
|
-
<a href="../readme/README.ja.md">日本語</a>
|
|
28
|
-
<a href="../readme/README.ko.md">한국어</a>
|
|
29
|
-
<a href="../readme/README.es.md">Español</a>
|
|
30
|
-
<a href="../readme/README.fr.md">Français</a>
|
|
31
|
-
<a href="../readme/README.de.md">Deutsch</a>
|
|
32
|
-
<a href="../readme/README.pt.md">Português</a>
|
|
33
|
-
<a href="../readme/README.vi.md">Tiếng Việt</a>
|
|
34
|
-
<a href="../readme/README.id.md">Bahasa Indonesia</a>
|
|
35
|
-
<a href="../readme/README.ru.md">Русский</a>
|
|
36
|
-
<a href="../readme/README.hi.md">हिन्दी</a>
|
|
37
|
-
<a href="mcp.html">English</a>
|
|
38
|
-
</div>
|
|
39
|
-
</div>
|
|
40
|
-
</nav>
|
|
41
|
-
<button class="menu-btn" id="menuToggle" aria-label="เปิด/ปิดเมนู"><span></span><span></span><span></span></button>
|
|
42
|
-
</div>
|
|
43
|
-
</header>
|
|
15
|
+
<header class="header"></header>
|
|
44
16
|
<div class="app">
|
|
45
17
|
<aside class="sidebar" id="sidebar"></aside>
|
|
46
18
|
<div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
@@ -48,54 +20,178 @@
|
|
|
48
20
|
<main class="content">
|
|
49
21
|
<div class="breadcrumbs"><a href="index.th.html">หน้าแรก</a><span class="sep">/</span><span>MCP</span></div>
|
|
50
22
|
<h1>Model Context Protocol (MCP)</h1>
|
|
51
|
-
<p class="section-subtitle">เชื่อมต่อ Clew กับเครื่องมือภายนอก, แหล่งข้อมูล, และบริการผ่าน
|
|
23
|
+
<p class="section-subtitle">เชื่อมต่อ Clew กับเครื่องมือภายนอก, แหล่งข้อมูล, และบริการผ่าน MCP — มาตรฐานเปิดสำหรับ AI-tool integration</p>
|
|
24
|
+
|
|
25
|
+
<p>MCP อยู่ใน <code>src/services/mcp/</code> — Clew ค้นหาเซิร์ฟเวอร์ MCP จาก <strong>settings.json</strong>, <strong>CLI flags</strong>, และ <strong>plugin manifests</strong> แล้วรวมเครื่องมือเข้าสู่ runtime</p>
|
|
52
26
|
|
|
53
|
-
<
|
|
27
|
+
<h2>สถาปัตยกรรม</h2>
|
|
28
|
+
<pre><code> ┌──────────────────────────────────────────────────────────────────────────┐
|
|
29
|
+
│ MCP — MODEL CONTEXT PROTOCOL │
|
|
30
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
31
|
+
|
|
32
|
+
┌──────────────────────────┐
|
|
33
|
+
│ Settings / CLI Config │
|
|
34
|
+
│ src/services/mcp/config │
|
|
35
|
+
└────────────┬─────────────┘
|
|
36
|
+
│
|
|
37
|
+
▼
|
|
38
|
+
┌──────────────────────────┐
|
|
39
|
+
│ MCPConnectionManager │
|
|
40
|
+
│ จัดการ lifecycle │
|
|
41
|
+
│ ของเซิร์ฟเวอร์ MCP ทั้งหมด │
|
|
42
|
+
└────────────┬─────────────┘
|
|
43
|
+
│
|
|
44
|
+
┌───────────────────┼───────────────────┐
|
|
45
|
+
▼ ▼ ▼
|
|
46
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
47
|
+
│ Stdio MCP │ │ SSE MCP │ │Direct Connect│
|
|
48
|
+
│ (subprocess) │ │ (remote) │ │ (in-process) │
|
|
49
|
+
│ npx/node/etc │ │ HTTP + SSE │ │ │
|
|
50
|
+
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
51
|
+
│ │ │
|
|
52
|
+
└──────────────────┼───────────────────┘
|
|
53
|
+
│
|
|
54
|
+
▼
|
|
55
|
+
┌──────────────────────┐
|
|
56
|
+
│ Client (JSON-RPC) │
|
|
57
|
+
│ tools/list │
|
|
58
|
+
│ tools/call │
|
|
59
|
+
│ resources/list │
|
|
60
|
+
└──────────┬───────────┘
|
|
61
|
+
│
|
|
62
|
+
▼
|
|
63
|
+
┌──────────────────────┐
|
|
64
|
+
│ assembleToolPool │
|
|
65
|
+
│ (MCP + built-in │
|
|
66
|
+
│ tools รวมกัน) │
|
|
67
|
+
└──────────┬───────────┘
|
|
68
|
+
│
|
|
69
|
+
▼
|
|
70
|
+
┌──────────────────────┐
|
|
71
|
+
│ Query Engine │
|
|
72
|
+
│ Model เห็น tools │
|
|
73
|
+
│ ทั้งหมดใน pool │
|
|
74
|
+
└──────────────────────┘</code></pre>
|
|
54
75
|
|
|
55
76
|
<h2>วิธีการทำงาน</h2>
|
|
56
|
-
<pre><code> การตั้งค่าเซิร์ฟเวอร์ MCP (JSON หรือ inline)
|
|
57
|
-
|
|
|
58
|
-
v
|
|
59
|
-
+ MCP Manager (src/services/mcp/)
|
|
60
|
-
| วงจรชีวิตการเชื่อมต่อเซิร์ฟเวอร์
|
|
61
|
-
| การค้นพบเครื่องมือผ่าน tools/list
|
|
62
|
-
| การเข้าถึงทรัพยากรผ่าน resources/read
|
|
63
|
-
|
|
|
64
|
-
+ พูลเครื่องมือ (assembleToolPool)
|
|
65
|
-
| เครื่องมือ MCP ถูกรวมกับเครื่องมือในตัว
|
|
66
|
-
|
|
|
67
|
-
+ Query Loop
|
|
68
|
-
โมเดลเห็นเครื่องมือ MCP ข้างๆ เครื่องมือในตัว</code></pre>
|
|
69
77
|
|
|
70
|
-
<
|
|
78
|
+
<h3>การค้นหาเซิร์ฟเวอร์</h3>
|
|
79
|
+
<p>MCP servers ถูกค้นหาจาก 3 แหล่งเมื่อเริ่มต้น:</p>
|
|
80
|
+
<ol>
|
|
81
|
+
<li><strong><code>settings.json</code></strong> — คีย์ <code>mcpServers</code> กำหนด command, args, env</li>
|
|
82
|
+
<li><strong>CLI <code>--mcp-config</code></strong> — ไฟล์หรือ inline JSON</li>
|
|
83
|
+
<li><strong>Plugins</strong> — manifest ของ plugin สามารถประกาศ MCP server ได้; เริ่มเมื่อ plugin โหลด, หยุดเมื่อ unload</li>
|
|
84
|
+
</ol>
|
|
85
|
+
|
|
86
|
+
<h3>ประเภทการเชื่อมต่อ</h3>
|
|
71
87
|
<table>
|
|
72
|
-
<tr><th
|
|
73
|
-
<tr
|
|
88
|
+
<tr><th>ประเภท</th><th>Transport</th><th>วิธีการ</th></tr>
|
|
89
|
+
<tr>
|
|
90
|
+
<td><strong>Stdio</strong></td>
|
|
91
|
+
<td>stdin/stdout</td>
|
|
92
|
+
<td>Clew spawn subprocess (เช่น <code>npx @modelcontextprotocol/server-filesystem</code>) และสื่อสารผ่าน JSON-RPC ทาง stdin/stdout</td>
|
|
93
|
+
</tr>
|
|
94
|
+
<tr>
|
|
95
|
+
<td><strong>SSE</strong></td>
|
|
96
|
+
<td>HTTP + SSE</td>
|
|
97
|
+
<td>เชื่อมต่อ remote MCP server ผ่าน HTTP ใช้ SSE สำหรับ server→client, HTTP POST สำหรับ client→server รองรับ OAuth</td>
|
|
98
|
+
</tr>
|
|
99
|
+
<tr>
|
|
100
|
+
<td><strong>Direct Connect</strong></td>
|
|
101
|
+
<td>In-process</td>
|
|
102
|
+
<td>รัน MCP server ใน process เดียวกัน ใช้ InProcessTransport — ไม่มี network, ไม่มี subprocess ใช้ใน plugin-bundled servers</td>
|
|
103
|
+
</tr>
|
|
74
104
|
</table>
|
|
75
105
|
|
|
76
|
-
<
|
|
77
|
-
<pre><code
|
|
78
|
-
|
|
106
|
+
<h3>Tool Lifecycle</h3>
|
|
107
|
+
<pre><code> 1. CONNECT ──► MCPConnectionManager เชื่อมต่อ server
|
|
108
|
+
│
|
|
109
|
+
▼
|
|
110
|
+
2. DISCOVER ──► เรียก tools/list (รองรับ paginated)
|
|
111
|
+
│
|
|
112
|
+
▼
|
|
113
|
+
3. MERGE ──► assembleToolPool() รวม MCP tools
|
|
114
|
+
│ กับ built-in tools (sort + dedup)
|
|
115
|
+
▼
|
|
116
|
+
4. PRESENT ──► Model เห็น MCP tools เป็น native tools
|
|
117
|
+
│ (permission gating, hooks, logging)
|
|
118
|
+
▼
|
|
119
|
+
5. EXECUTE ──► Model เรียก tool → toolExecution.ts
|
|
120
|
+
│ route ไปยัง server ที่ถูกต้อง
|
|
121
|
+
▼
|
|
122
|
+
6. RESPOND ──► ผลลัพธ์กลับไปหา model</code></pre>
|
|
79
123
|
|
|
80
|
-
|
|
81
|
-
|
|
124
|
+
<h3>การยืนยันตัวตน (Authentication)</h3>
|
|
125
|
+
<ul>
|
|
126
|
+
<li><strong>OAuth 2.0</strong> — redirect flow สำหรับ remote MCP servers เปิด local HTTP port เพื่อรับ callback</li>
|
|
127
|
+
<li><strong>Bearer token</strong> — static API token ใน <code>Authorization</code> header</li>
|
|
128
|
+
<li><strong>XAA token</strong> — auth provider token สำหรับ Claude-specific servers</li>
|
|
129
|
+
<li><strong>Credential vault</strong> — credentials ที่เก็บไว้ใน vault ถูก inject อัตโนมัติ</li>
|
|
130
|
+
</ul>
|
|
82
131
|
|
|
83
|
-
|
|
84
|
-
|
|
132
|
+
<h2>คำสั่ง MCP</h2>
|
|
133
|
+
<table>
|
|
134
|
+
<tr><th>คำสั่ง</th><th>คำอธิบาย</th></tr>
|
|
135
|
+
<tr><td><code>/mcp</code></td><td>เปิดเมนูจัดการ MCP — list servers, add, remove, reconnect</td></tr>
|
|
136
|
+
<tr><td><code>/mcp list</code></td><td>แสดงเซิร์ฟเวอร์ MCP ทั้งหมด พร้อม tools, resources, prompts</td></tr>
|
|
137
|
+
<tr><td><code>/mcp add <name> <command> [args...]</code></td><td>เพิ่ม stdio MCP server ใหม่</td></tr>
|
|
138
|
+
<tr><td><code>/mcp remove <name></code></td><td>ลบ MCP server</td></tr>
|
|
139
|
+
<tr><td><code>/mcp reconnect <name></code></td><td>เชื่อมต่อ MCP server ใหม่</td></tr>
|
|
140
|
+
</table>
|
|
85
141
|
|
|
86
|
-
<h2
|
|
87
|
-
<
|
|
88
|
-
|
|
142
|
+
<h2>รูปแบบ Config (settings.json)</h2>
|
|
143
|
+
<div class="code-block-wrap">
|
|
144
|
+
<div class="code-block-header"><span>json</span></div>
|
|
145
|
+
<pre><code>{
|
|
146
|
+
"mcpServers": {
|
|
89
147
|
"filesystem": {
|
|
90
148
|
"command": "npx",
|
|
91
149
|
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
|
|
92
150
|
"env": {}
|
|
151
|
+
},
|
|
152
|
+
"database": {
|
|
153
|
+
"command": "node",
|
|
154
|
+
"args": ["./mcp/db-server.js"],
|
|
155
|
+
"env": {
|
|
156
|
+
"DB_URL": "postgresql://localhost:5432/mydb"
|
|
157
|
+
}
|
|
158
|
+
},
|
|
159
|
+
"remote-api": {
|
|
160
|
+
"url": "https://mcp.example.com",
|
|
161
|
+
"headers": {
|
|
162
|
+
"Authorization": "Bearer sk-..."
|
|
163
|
+
}
|
|
93
164
|
}
|
|
94
165
|
}
|
|
95
166
|
}</code></pre>
|
|
167
|
+
</div>
|
|
168
|
+
|
|
169
|
+
<h2>Plugin-Bundled MCP Servers</h2>
|
|
170
|
+
<p>Plugin สามารถประกาศ MCP server ใน manifest เมื่อ plugin โหลด Clew จะสร้าง DirectConnect session ให้อัตโนมัติ — ไม่ต้อง subprocess ไม่ต้อง network — server จะพร้อมใช้งานทันที</p>
|
|
171
|
+
|
|
172
|
+
<h2>เครื่องมือ Built-in ที่ใช้ MCP</h2>
|
|
173
|
+
<table>
|
|
174
|
+
<tr><th>Tool</th><th>MCP ใช้ทำอะไร</th></tr>
|
|
175
|
+
<tr><td><code>ListMcpResources</code></td><td>แสดง resources จาก MCP servers ทั้งหมด (resources/list)</td></tr>
|
|
176
|
+
<tr><td><code>ReadMcpResource</code></td><td>อ่าน resource ตาม URI จาก MCP server (resources/read)</td></tr>
|
|
177
|
+
</table>
|
|
178
|
+
|
|
179
|
+
<h2>ไฟล์สำคัญ</h2>
|
|
180
|
+
<table>
|
|
181
|
+
<tr><th>ไฟล์</th><th>หน้าที่</th></tr>
|
|
182
|
+
<tr><td><code>src/services/mcp/MCPConnectionManager.tsx</code></td><td>จัดการ lifecycle ของเซิร์ฟเวอร์ MCP</td></tr>
|
|
183
|
+
<tr><td><code>src/services/mcp/config.ts</code></td><td>โหลด config จาก settings.json และ CLI flags</td></tr>
|
|
184
|
+
<tr><td><code>src/services/mcp/client.ts</code></td><td>JSON-RPC client</td></tr>
|
|
185
|
+
<tr><td><code>src/services/mcp/auth.ts</code></td><td>OAuth + Bearer token authentication</td></tr>
|
|
186
|
+
<tr><td><code>src/services/mcp/oauthPort.ts</code></td><td>Local HTTP server สำหรับ OAuth callback</td></tr>
|
|
187
|
+
<tr><td><code>src/services/mcp/types.ts</code></td><td>Type definitions</td></tr>
|
|
188
|
+
<tr><td><code>src/services/mcp/InProcessTransport.ts</code></td><td>In-process transport สำหรับ DirectConnect</td></tr>
|
|
189
|
+
<tr><td><code>src/services/mcp/officialRegistry.ts</code></td><td>ทะเบียน MCP server ทางการ</td></tr>
|
|
190
|
+
<tr><td><code>src/tools.ts</code></td><td>assembleToolPool() รวม MCP tools</td></tr>
|
|
191
|
+
</table>
|
|
96
192
|
|
|
97
193
|
<footer class="footer">
|
|
98
|
-
<span>Clew
|
|
194
|
+
<span>Clew Code — โอเพนซอร์ส</span>
|
|
99
195
|
<div class="footer-links">
|
|
100
196
|
<a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
|
|
101
197
|
<a href="https://github.com/JonusNattapong/ClewCode/issues">ปัญหา</a>
|
package/docs/models.html
CHANGED
|
@@ -12,28 +12,7 @@
|
|
|
12
12
|
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
|
15
|
-
<header class="header"
|
|
16
|
-
<span>Clew Code</span>
|
|
17
|
-
</a><nav class="header-nav"><a href="index.html">Home</a><a href="index.html#features">Features</a><a href="index.html#commands">Commands</a><a href="quick-start.html" class="active">Docs</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a>
|
|
18
|
-
<div class="lang-wrap">
|
|
19
|
-
<button class="lang-btn">🌐</button>
|
|
20
|
-
<div class="lang-menu">
|
|
21
|
-
<a href="../readme/README.zh.md">中文</a>
|
|
22
|
-
<a href="../readme/README.th.md">ไทย</a>
|
|
23
|
-
<a href="../readme/README.ja.md">日本語</a>
|
|
24
|
-
<a href="../readme/README.ko.md">한국어</a>
|
|
25
|
-
<a href="../readme/README.es.md">Español</a>
|
|
26
|
-
<a href="../readme/README.fr.md">Français</a>
|
|
27
|
-
<a href="../readme/README.de.md">Deutsch</a>
|
|
28
|
-
<a href="../readme/README.pt.md">Português</a>
|
|
29
|
-
<a href="../readme/README.vi.md">Tiếng Việt</a>
|
|
30
|
-
<a href="../readme/README.id.md">Bahasa Indonesia</a>
|
|
31
|
-
<a href="../readme/README.ru.md">Русский</a>
|
|
32
|
-
<a href="../readme/README.hi.md">हिन्दी</a>
|
|
33
|
-
<a href="../README.md">English</a>
|
|
34
|
-
</div>
|
|
35
|
-
</div>
|
|
36
|
-
</nav><button class="menu-btn" id="menuToggle" aria-label="Toggle navigation"><span></span><span></span><span></span></button></div></header>
|
|
15
|
+
<header class="header"></header>
|
|
37
16
|
<div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
38
17
|
<div class="content-wrap"><main class="content">
|
|
39
18
|
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Models</span></div>
|
package/docs/models.th.html
CHANGED
|
@@ -12,28 +12,7 @@
|
|
|
12
12
|
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
|
15
|
-
<header class="header"
|
|
16
|
-
<span>Clew Code</span>
|
|
17
|
-
</a><nav class="header-nav"><a href="index.th.html">หน้าแรก</a><a href="index.th.html#features">ฟีเจอร์</a><a href="index.th.html#commands">คำสั่ง</a><a href="quick-start.th.html" class="active">เอกสาร</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a>
|
|
18
|
-
<div class="lang-wrap">
|
|
19
|
-
<button class="lang-btn">🌐</button>
|
|
20
|
-
<div class="lang-menu">
|
|
21
|
-
<a href="../readme/README.zh.md">中文</a>
|
|
22
|
-
<a href="../readme/README.th.md">ไทย</a>
|
|
23
|
-
<a href="../readme/README.ja.md">日本語</a>
|
|
24
|
-
<a href="../readme/README.ko.md">한국어</a>
|
|
25
|
-
<a href="../readme/README.es.md">Español</a>
|
|
26
|
-
<a href="../readme/README.fr.md">Français</a>
|
|
27
|
-
<a href="../readme/README.de.md">Deutsch</a>
|
|
28
|
-
<a href="../readme/README.pt.md">Português</a>
|
|
29
|
-
<a href="../readme/README.vi.md">Tiếng Việt</a>
|
|
30
|
-
<a href="../readme/README.id.md">Bahasa Indonesia</a>
|
|
31
|
-
<a href="../readme/README.ru.md">Русский</a>
|
|
32
|
-
<a href="../readme/README.hi.md">हिन्दी</a>
|
|
33
|
-
<a href="models.html">English</a>
|
|
34
|
-
</div>
|
|
35
|
-
</div>
|
|
36
|
-
</nav><button class="menu-btn" id="menuToggle" aria-label="เปิด/ปิดเมนู"><span></span><span></span><span></span></button></div></header>
|
|
15
|
+
<header class="header"></header>
|
|
37
16
|
<div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
38
17
|
<div class="content-wrap"><main class="content">
|
|
39
18
|
<div class="breadcrumbs"><a href="index.th.html">หน้าแรก</a><span class="sep">/</span><span>โมเดล</span></div>
|
package/docs/peer.html
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>Peer System — Clew</title>
|
|
7
|
+
<meta name="description" content="LAN peer-to-peer system — discovery, messaging, task delegation, and remote execution between Clew instances.">
|
|
8
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
10
|
+
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
11
|
+
<link rel="stylesheet" href="css/styles.css">
|
|
12
|
+
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
|
+
</head>
|
|
14
|
+
<body>
|
|
15
|
+
<header class="header"></header>
|
|
16
|
+
<div class="app">
|
|
17
|
+
<aside class="sidebar" id="sidebar"></aside>
|
|
18
|
+
<div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
19
|
+
<div class="content-wrap">
|
|
20
|
+
<main class="content">
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Peer System</span></div>
|
|
22
|
+
<h1>Peer System</h1>
|
|
23
|
+
<p class="section-subtitle">LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.</p>
|
|
24
|
+
|
|
25
|
+
<p>The peer system lives in <code>src/peer/</code> and consists of three core layers: <strong>PeerServer</strong> (HTTP server), <strong>PeerDiscovery</strong> (LAN scanning), and <strong>PeerStore</strong> (in-memory registry).</p>
|
|
26
|
+
|
|
27
|
+
<h2>Architecture</h2>
|
|
28
|
+
<pre><code> ┌─────────────────────────────────────────────────────────────────────────────┐
|
|
29
|
+
│ PEER SYSTEM FLOW │
|
|
30
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
31
|
+
|
|
32
|
+
┌──────────────────────────┐
|
|
33
|
+
│ /peer share │
|
|
34
|
+
│ (Machine A — Worker) │
|
|
35
|
+
└────────────┬─────────────┘
|
|
36
|
+
│
|
|
37
|
+
┌─────────────────┼─────────────────┐
|
|
38
|
+
▼ ▼ ▼
|
|
39
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
40
|
+
│ PeerServer │ │PeerDiscovery │ │ PeerStore │
|
|
41
|
+
│ HTTP :random │ │ │ │ (in-memory) │
|
|
42
|
+
│ port │ │ │ │ │
|
|
43
|
+
└──────┬───────┘ └──────┬───────┘ └──────────────┘
|
|
44
|
+
│ │
|
|
45
|
+
│ ┌────────────┼────────────┐
|
|
46
|
+
│ │ │ │
|
|
47
|
+
│ ▼ ▼ ▼
|
|
48
|
+
│ ┌────────┐ ┌────────┐ ┌─────────────┐
|
|
49
|
+
│ │ File │ │ UDP │ │ PeerStore │
|
|
50
|
+
│ │ ~/.cl/ │ │multicast│ │ (singleton) │
|
|
51
|
+
│ │ peers/ │ │239... │ │ │
|
|
52
|
+
│ │{pid}. │ │:42069 │ │ │
|
|
53
|
+
│ │ json │ │ │ │ │
|
|
54
|
+
│ └────┬───┘ └────┬───┘ └─────────────┘
|
|
55
|
+
│ │ │
|
|
56
|
+
│ │ │ heartbeat every 30s
|
|
57
|
+
│ │ │ stale timeout 90s
|
|
58
|
+
│ │ │
|
|
59
|
+
▼ ▼ ▼
|
|
60
|
+
┌─────────────────────────────────────────────────────┐
|
|
61
|
+
│ LAN NETWORK │
|
|
62
|
+
│ │
|
|
63
|
+
│ ┌─────────┐ ┌─────────┐ │
|
|
64
|
+
│ │ Machine B│◄───────►│ Machine C│ ... │
|
|
65
|
+
│ │ Clew Code│ query │ Clew Code│ │
|
|
66
|
+
│ └────┬─────┘ └────┬─────┘ │
|
|
67
|
+
│ │ │ │
|
|
68
|
+
└────────┼────────────────────┼─────────────────────────┘
|
|
69
|
+
│ │
|
|
70
|
+
│ /peer discover │ /peer discover
|
|
71
|
+
▼ ▼
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
═══ WORKER (Machine A) ENDPOINTS ═══
|
|
75
|
+
|
|
76
|
+
Peer อื่น POST /peer-info ──► { hostname, ip, cwd, shell, ... }
|
|
77
|
+
│ POST /peer-msg ──► receive chat message
|
|
78
|
+
├───────────────► POST /peer-todo ──► receive task (goes to inbox)
|
|
79
|
+
│ POST /peer-exec ──► run shell command + return stdout/stderr
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
═══ CLIENT (Machine B) TOOLS ═══
|
|
83
|
+
|
|
84
|
+
/peer discover ──► scan files + UDP query (3s timeout)
|
|
85
|
+
│
|
|
86
|
+
▼
|
|
87
|
+
[peer list]
|
|
88
|
+
│
|
|
89
|
+
┌───────────────────┼───────────────────┐
|
|
90
|
+
▼ ▼ ▼
|
|
91
|
+
/peer join /peer send_task /peer run
|
|
92
|
+
(POST /peer-info) (POST /peer-todo) (POST /peer-exec)
|
|
93
|
+
|
|
94
|
+
│
|
|
95
|
+
▼
|
|
96
|
+
/peer send_message ──► POST /peer-msg ──► destination inbox
|
|
97
|
+
/peer broadcast ──► POST /peer-msg ──► all connected peers
|
|
98
|
+
/peer ping ──► GET /peer-info ──► check alive
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
═══ DAEMON (agentLoop.ts) ═══
|
|
102
|
+
|
|
103
|
+
┌───────────────────────────────────┐
|
|
104
|
+
│ Autonomous Agent Loop │
|
|
105
|
+
│ - listens /peer-todo 24/7 │
|
|
106
|
+
│ - receives tasks from peers │
|
|
107
|
+
│ - executes in background worker │
|
|
108
|
+
│ - max 3 concurrent workers │
|
|
109
|
+
└───────────────────────────────────┘
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
═══ DATA LIFECYCLE ═══
|
|
113
|
+
|
|
114
|
+
advertise ──► heartbeat every 30s
|
|
115
|
+
│
|
|
116
|
+
├── 90s no heartbeat ──► stale → evict
|
|
117
|
+
│
|
|
118
|
+
stop share ──► send UDP "offline"
|
|
119
|
+
delete peer file
|
|
120
|
+
close HTTP server</code></pre>
|
|
121
|
+
|
|
122
|
+
<h2>Core Components</h2>
|
|
123
|
+
|
|
124
|
+
<h3>PeerServer <code>src/peer/PeerServer.ts</code></h3>
|
|
125
|
+
<p>Lightweight HTTP server started on a random OS-assigned port when <code>/peer share</code> is invoked. Each endpoint handles a different peer interaction:</p>
|
|
126
|
+
<table>
|
|
127
|
+
<tr><th>Endpoint</th><th>Method</th><th>Purpose</th></tr>
|
|
128
|
+
<tr><td><code>/peer-info</code></td><td>GET</td><td>Return peer metadata (hostname, IP, cwd, shell, platform)</td></tr>
|
|
129
|
+
<tr><td><code>/peer-msg</code></td><td>POST</td><td>Receive a chat message from another peer</td></tr>
|
|
130
|
+
<tr><td><code>/peer-todo</code></td><td>POST</td><td>Receive a task delegation from another peer</td></tr>
|
|
131
|
+
<tr><td><code>/peer-exec</code></td><td>POST</td><td>Execute a shell command and return stdout/stderr</td></tr>
|
|
132
|
+
</table>
|
|
133
|
+
|
|
134
|
+
<h3>PeerDiscovery <code>src/peer/PeerDiscovery.ts</code></h3>
|
|
135
|
+
<p>Two discovery mechanisms work together:</p>
|
|
136
|
+
<ul>
|
|
137
|
+
<li><strong>File-based</strong> — Each instance writes <code>~/.claude/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers.</li>
|
|
138
|
+
<li><strong>UDP Multicast</strong> — Broadcasts heartbeat beacons to <code>239.255.37.37:42069</code> every 30 seconds. Responds to <code>clew-peer-query</code> with <code>clew-peer-info</code>. Cross-machine only.</li>
|
|
139
|
+
<li><strong>Stale eviction</strong> — Peers unseen for 90 seconds (<code>PEER_STALE_TIMEOUT</code>) are automatically removed.</li>
|
|
140
|
+
</ul>
|
|
141
|
+
|
|
142
|
+
<h3>PeerStore <code>src/peer/PeerStore.ts</code></h3>
|
|
143
|
+
<p>Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).</p>
|
|
144
|
+
<ul>
|
|
145
|
+
<li><strong>Discovered peers</strong> — Auto-evicted after stale timeout</li>
|
|
146
|
+
<li><strong>Joined connections</strong> — Persistent; never auto-cleaned</li>
|
|
147
|
+
<li><strong>Tags</strong> — Custom display names and roles per peer</li>
|
|
148
|
+
</ul>
|
|
149
|
+
|
|
150
|
+
<h2>Discovery Protocol</h2>
|
|
151
|
+
<pre><code>DiscoveryMessage =
|
|
152
|
+
| { type: "clew-peer-query", version: 1 } // broadcast scan
|
|
153
|
+
| { type: "clew-peer-info", version: 1, // heartbeat / response
|
|
154
|
+
id: string, hostname: string, ip: string, port: number,
|
|
155
|
+
cwd: string, sessionId?: string, appVersion: string,
|
|
156
|
+
shell?: string, platform?: string, term?: string,
|
|
157
|
+
status: "online" | "offline" }
|
|
158
|
+
|
|
159
|
+
UDP port: 42069
|
|
160
|
+
Multicast IP: 239.255.37.37
|
|
161
|
+
Heartbeat: every 30 seconds
|
|
162
|
+
Stale after: 90 seconds</code></pre>
|
|
163
|
+
|
|
164
|
+
<h2>Commands</h2>
|
|
165
|
+
<table>
|
|
166
|
+
<tr><th>Command</th><th>Description</th></tr>
|
|
167
|
+
<tr><td><code>/peer</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
|
|
168
|
+
<tr><td><code>/peer share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
|
|
169
|
+
<tr><td><code>/peer stop</code></td><td>Stop advertising and shut down the peer server</td></tr>
|
|
170
|
+
<tr><td><code>/peer discover</code></td><td>Scan for available peers (file + UDP, 3s timeout)</td></tr>
|
|
171
|
+
<tr><td><code>/peer join <host> <port></code></td><td>Connect to a remote peer by host and port</td></tr>
|
|
172
|
+
<tr><td><code>/peer name <name></code></td><td>Set a custom display name for yourself</td></tr>
|
|
173
|
+
<tr><td><code>/peer role <role></code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
|
|
174
|
+
<tr><td><code>/peer inbox</code></td><td>View pending messages and todos from peers</td></tr>
|
|
175
|
+
<tr><td><code>/peer disconnect <peer></code></td><td>Disconnect from a specific peer</td></tr>
|
|
176
|
+
<tr><td><code>/peer todos</code></td><td>List all received tasks</td></tr>
|
|
177
|
+
<tr><td><code>/peer todo done <id></code></td><td>Mark a received task as done</td></tr>
|
|
178
|
+
</table>
|
|
179
|
+
|
|
180
|
+
<h2>AI Tools</h2>
|
|
181
|
+
<p>These are the tools the AI agent uses to interact with the peer system:</p>
|
|
182
|
+
<table>
|
|
183
|
+
<tr><th>Tool</th><th>Description</th></tr>
|
|
184
|
+
<tr><td><code>peer_discover</code></td><td>Scan LAN for available Clew workers</td></tr>
|
|
185
|
+
<tr><td><code>peer_join</code></td><td>Connect to a remote peer via HTTP</td></tr>
|
|
186
|
+
<tr><td><code>peer_ping</code></td><td>Check if a peer is online (GET /peer-info)</td></tr>
|
|
187
|
+
<tr><td><code>peer_info</code></td><td>Fetch detailed peer information</td></tr>
|
|
188
|
+
<tr><td><code>peer_send_message</code></td><td>Send a chat message to a peer</td></tr>
|
|
189
|
+
<tr><td><code>peer_send_task</code></td><td>Assign a task to a remote worker</td></tr>
|
|
190
|
+
<tr><td><code>peer_broadcast</code></td><td>Send a task to all connected peers simultaneously</td></tr>
|
|
191
|
+
<tr><td><code>peer_run</code></td><td>Execute a shell command on a remote worker</td></tr>
|
|
192
|
+
<tr><td><code>peer_disconnect</code></td><td>Remove a peer from the connection list</td></tr>
|
|
193
|
+
<tr><td><code>peer_list_messages</code></td><td>List all received chat messages</td></tr>
|
|
194
|
+
<tr><td><code>peer_list_roles</code></td><td>List all peers with their roles</td></tr>
|
|
195
|
+
<tr><td><code>peer_list_tasks</code></td><td>List all task assignments and their status</td></tr>
|
|
196
|
+
<tr><td><code>peer_set_name</code></td><td>Assign a custom display name to a peer</td></tr>
|
|
197
|
+
<tr><td><code>peer_set_role</code></td><td>Assign a functional role to a peer</td></tr>
|
|
198
|
+
<tr><td><code>peer_share</code></td><td>Toggle sharing (start/stop/status)</td></tr>
|
|
199
|
+
</table>
|
|
200
|
+
|
|
201
|
+
<h2>DAEMON Integration</h2>
|
|
202
|
+
<p>The autonomous agent loop (<code>src/services/autonomous/agentLoop.ts</code>) integrates with PeerServer to accept tasks from remote peers:</p>
|
|
203
|
+
<ul>
|
|
204
|
+
<li>Listens for incoming <code>/peer-todo</code> POSTs 24/7</li>
|
|
205
|
+
<li>Queues received tasks and processes them in background workers</li>
|
|
206
|
+
<li>Max 3 concurrent workers; tasks time out after 30 minutes</li>
|
|
207
|
+
<li>Results are available via <code>/peer todos</code> and <code>/tasks</code></li>
|
|
208
|
+
</ul>
|
|
209
|
+
|
|
210
|
+
<h2>Architecture Files</h2>
|
|
211
|
+
<table>
|
|
212
|
+
<tr><th>File</th><th>Role</th></tr>
|
|
213
|
+
<tr><td><code>src/peer/PeerServer.ts</code></td><td>HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints</td></tr>
|
|
214
|
+
<tr><td><code>src/peer/PeerDiscovery.ts</code></td><td>File-based + UDP multicast LAN peer discovery</td></tr>
|
|
215
|
+
<tr><td><code>src/peer/PeerStore.ts</code></td><td>In-memory singleton registry (peers, messages, todos, tags)</td></tr>
|
|
216
|
+
<tr><td><code>src/peer/types.ts</code></td><td>Shared types and protocol constants</td></tr>
|
|
217
|
+
<tr><td><code>src/commands/peer/</code></td><td>Interactive peer menu and CLI commands</td></tr>
|
|
218
|
+
<tr><td><code>src/tools/Peer*Tool/</code></td><td>16 AI agent tools wrapping peer operations</td></tr>
|
|
219
|
+
<tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Daemon integration: accepts remote tasks via PeerServer</td></tr>
|
|
220
|
+
</table>
|
|
221
|
+
|
|
222
|
+
<footer class="footer">
|
|
223
|
+
<span>Clew Code v0.2.4 — Open Source</span>
|
|
224
|
+
<div class="footer-links">
|
|
225
|
+
<a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
|
|
226
|
+
<a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
|
|
227
|
+
</div>
|
|
228
|
+
</footer>
|
|
229
|
+
</main>
|
|
230
|
+
<nav class="toc-sidebar"></nav>
|
|
231
|
+
</div>
|
|
232
|
+
</div>
|
|
233
|
+
<script src="js/main.js"></script>
|
|
234
|
+
</body>
|
|
235
|
+
</html>
|