@sanqianx/claude-ai-workbench 0.11.0

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.
Files changed (90) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +129 -0
  3. package/apps/agent-terminal/app.css +567 -0
  4. package/apps/agent-terminal/app.js +2392 -0
  5. package/apps/agent-terminal/index.html +158 -0
  6. package/apps/ai-profile-settings-host/index.html +25 -0
  7. package/apps/ai-profile-settings-host/page.css +1 -0
  8. package/apps/ai-profile-settings-host/page.js +113 -0
  9. package/apps/minimal-test-host/README.md +15 -0
  10. package/apps/minimal-test-host/host.css +2 -0
  11. package/apps/minimal-test-host/host.js +35 -0
  12. package/apps/minimal-test-host/index.html +58 -0
  13. package/apps/minimal-test-host/optional-mock/fault-injection.js +15 -0
  14. package/docs/sdk/FILE_LAYOUT.md +31 -0
  15. package/docs/sdk/INTEGRATION.md +126 -0
  16. package/docs/sdk/README.md +21 -0
  17. package/docs/sdk/openapi.yaml +760 -0
  18. package/package.json +51 -0
  19. package/packages/client/README.md +11 -0
  20. package/packages/client/index.d.ts +81 -0
  21. package/packages/client/index.js +198 -0
  22. package/packages/client/package.json +29 -0
  23. package/packages/contracts/README.md +9 -0
  24. package/packages/contracts/index.d.ts +252 -0
  25. package/packages/contracts/index.js +295 -0
  26. package/packages/contracts/package.json +24 -0
  27. package/packages/core/README.md +8 -0
  28. package/packages/core/index.d.ts +76 -0
  29. package/packages/core/index.js +214 -0
  30. package/packages/core/package.json +29 -0
  31. package/packages/server/README.md +17 -0
  32. package/packages/server/bin/agent-terminal-server.js +36 -0
  33. package/packages/server/bin/claude-workbench-server.js +46 -0
  34. package/packages/server/bin/claude-workbench.js +225 -0
  35. package/packages/server/index.d.ts +145 -0
  36. package/packages/server/index.js +183 -0
  37. package/packages/server/lib/agent-discovery.js +112 -0
  38. package/packages/server/lib/agent-registry.js +98 -0
  39. package/packages/server/lib/attachment-store.js +78 -0
  40. package/packages/server/lib/bridges/app-server-bridge.js +372 -0
  41. package/packages/server/lib/bridges/opencode-server-bridge.js +490 -0
  42. package/packages/server/lib/capture-settings-store.js +34 -0
  43. package/packages/server/lib/context-resolver.js +40 -0
  44. package/packages/server/lib/drivers/cli-json-runner.js +960 -0
  45. package/packages/server/lib/drivers/codex-driver.js +1413 -0
  46. package/packages/server/lib/drivers/opencode-driver.js +1527 -0
  47. package/packages/server/lib/drivers/zcode-driver.js +1167 -0
  48. package/packages/server/lib/event-stream.js +35 -0
  49. package/packages/server/lib/folder-picker.js +623 -0
  50. package/packages/server/lib/http-handler.js +254 -0
  51. package/packages/server/lib/json-file.js +19 -0
  52. package/packages/server/lib/model-detection.js +295 -0
  53. package/packages/server/lib/profile-store.js +149 -0
  54. package/packages/server/lib/project-store.js +102 -0
  55. package/packages/server/lib/session-archive-store.js +53 -0
  56. package/packages/server/lib/system-doctor.js +119 -0
  57. package/packages/server/lib/ui-preferences-store.js +48 -0
  58. package/packages/server/lib/workbench-service.js +620 -0
  59. package/packages/server/package.json +34 -0
  60. package/packages/ui/README.md +30 -0
  61. package/packages/ui/ai-profile-settings.d.ts +45 -0
  62. package/packages/ui/ai-profile-settings.js +283 -0
  63. package/packages/ui/claude-terminal.d.ts +31 -0
  64. package/packages/ui/claude-terminal.js +343 -0
  65. package/packages/ui/index.d.ts +18 -0
  66. package/packages/ui/index.js +51 -0
  67. package/packages/ui/package.json +42 -0
  68. package/packages/ui/theme.css +13 -0
  69. package/src/assets/claude-prompts.json +21 -0
  70. package/src/backend/http/ai-profile-routes.js +61 -0
  71. package/src/backend/http/claude-routes.js +170 -0
  72. package/src/backend/http/node-helpers.js +45 -0
  73. package/src/backend/index.js +21 -0
  74. package/src/backend/lib/ai-adapter.js +144 -0
  75. package/src/backend/lib/ai-profile-store.js +259 -0
  76. package/src/backend/lib/ai-vendor-presets.js +83 -0
  77. package/src/backend/lib/ai-workspace.js +140 -0
  78. package/src/backend/lib/automation-config.js +253 -0
  79. package/src/backend/lib/claude-cli-runner.js +1749 -0
  80. package/src/backend/lib/data-dir.js +169 -0
  81. package/src/backend/lib/llm-client.js +176 -0
  82. package/src/backend/lib/model-context-windows.js +82 -0
  83. package/src/backend/lib/prompt-registry.js +166 -0
  84. package/src/backend/lib/runtime-config.js +121 -0
  85. package/src/index.js +7 -0
  86. package/src/sdk-wave-a.ts +1 -0
  87. package/src/sdk-wave-b.ts +1 -0
  88. package/src/sdk-wave-c.ts +1 -0
  89. package/src/sdk-wave-d.ts +1 -0
  90. package/src/sdk-wave-e.ts +1 -0
package/apps/agent-terminal/index.html ADDED
@@ -0,0 +1,158 @@
1
+ <!DOCTYPE html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Agent Terminal</title>
7
+ <link rel="stylesheet" href="./app.css">
8
+ </head>
9
+ <body>
10
+
11
+ <!-- ============ 终端视图 ============ -->
12
+ <div id="view-terminal" class="view active">
13
+ <aside class="sidebar">
14
+ <div class="brand"><h1><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="m5 8 4 4-4 4"/><path d="M13 16h6"/></svg>Agent Terminal</h1><span class="ver" id="app-version"></span></div>
15
+ <button class="new-session" id="btn-new-session"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg><span>新会话</span></button>
16
+ <div class="session-scroll">
17
+ <div class="group-label">项目</div>
18
+ <div id="project-list"></div>
19
+ <button class="add-proj" id="btn-add-proj"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg><span>添加项目</span></button>
20
+ <button class="arch-toggle" id="arch-toggle" type="button" aria-expanded="true">
21
+ <span class="toggle-caret" id="arch-caret"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></span>
22
+ <span>已归档</span>
23
+ <span class="arch-count" id="arch-count" hidden></span>
24
+ </button>
25
+ <div class="arch-list" id="arch-list"><div class="proj-empty" id="arch-empty">暂无归档会话</div></div>
26
+ </div>
27
+ <div class="sidebar-foot">
28
+ <span class="dot" id="agent-dot"></span>
29
+ <span style="flex:1" id="agent-summary">扫描中…</span>
30
+ <button class="ghost" id="open-settings" title="设置"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M19 12a7 7 0 0 0-.1-1.2l2-1.6-2-3.4-2.4 1a7 7 0 0 0-2-1.2L14 3h-4l-.5 2.6a7 7 0 0 0-2 1.2l-2.4-1-2 3.4 2 1.6a7 7 0 0 0 0 2.4l-2 1.6 2 3.4 2.4-1a7 7 0 0 0 2 1.2L10 21h4l.5-2.6a7 7 0 0 0 2-1.2l2.4 1 2-3.4-2-1.6c.06-.4.1-.8.1-1.2z"/></svg></button>
31
+ </div>
32
+ </aside>
33
+
34
+ <div class="main">
35
+ <div class="top-strip">
36
+ <span class="t" id="session-title">选择或创建一个会话</span>
37
+ <span class="session-provider" id="session-provider"></span>
38
+ <span class="st" id="session-status" hidden><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3l1.9 5.8L20 12l-6.1 3.2L12 21l-1.9-5.8L4 12l6.1-3.2z"/></svg><span id="session-status-text"></span></span>
39
+ <span style="flex:1"></span>
40
+ <button class="ghost" id="btn-top-settings" title="设置（模型供应商）"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33h.01a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51h.01a1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82v.01a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg></button>
41
+ </div>
42
+
43
+ <div class="stream" id="stream">
44
+ <div class="col" id="stream-col">
45
+ <div class="empty-hint" id="empty-hint">
46
+ <div class="big"><span class="hint-wrap"><span class="hint-art"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m5 8 4 4-4 4"/><path d="M13 16h6"/></svg></span><span class="hint-spark"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3l1.9 5.8L20 12l-6.1 3.2L12 21l-1.9-5.8L4 12l6.1-3.2z"/></svg></span></span></div>
47
+ <p>从左侧选择一个项目,或 <button class="linklike" id="hint-add-proj">添加项目</button> 开始。<br>
48
+ 新会话将使用底部选中的 Agent 与模型。</p>
49
+ </div>
50
+ </div>
51
+ </div>
52
+
53
+ <button class="jump-latest" id="jump-latest" title="回到底部" hidden><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14"/><path d="m19 12-7 7-7-7"/></svg><span>回到底部</span></button>
54
+
55
+ <div class="composer-wrap">
56
+ <div class="composer" id="composer">
57
+ <textarea id="chat-input" placeholder="给当前会话发送消息" rows="1"></textarea>
58
+ <div class="cmdrow">
59
+ <button class="bar-btn plus" id="btn-attach" title="添加图片或文本文件（txt、md、json、csv；文本每件最多 512KB）"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg></button>
60
+ <input type="file" id="file-input" accept="image/jpeg,image/png,image/gif,image/webp,.txt,.md,.json,.csv" multiple hidden>
61
+ <span class="anchor">
62
+ <button class="bar-btn mode" id="btn-mode" title="权限模式"><span class="shield"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3l8 3v6c0 5-3.5 8-8 9-4.5-1-8-4-8-9V6z"/></svg></span> <span id="mode-label">默认防护</span> <span class="chev"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></span></button>
63
+ <div class="pop from-left" id="pop-mode" hidden></div>
64
+ </span>
65
+ <span class="cmd-spacer"></span>
66
+ <span class="anchor">
67
+ <button class="bar-btn" id="btn-ctx" title="上下文用量" hidden><span id="ctx-label"></span></button>
68
+ <div class="pop from-right ctx-pop" id="pop-ctx" hidden></div>
69
+ </span>
70
+ <span class="anchor">
71
+ <button class="bar-btn" id="btn-model" title="选择供应商与模型"><span id="model-label">Agent 自身登录 · 默认模型</span> <span class="chev"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></span></button>
72
+ <div class="pop from-right" id="pop-model" hidden></div>
73
+ </span>
74
+ <span class="anchor" id="effort-anchor" hidden>
75
+ <button class="bar-btn" id="btn-effort" title="推理力度"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 15l3.5-3.5"/><path d="M20.5 14a9 9 0 1 0-17 0"/></svg><span id="effort-label">高</span> <span class="chev"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></span></button>
76
+ <div class="pop from-right" id="pop-effort" hidden></div>
77
+ </span>
78
+ <button class="send" id="btn-send" title="发送"><span class="up"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 19V5"/><path d="m5 12 7-7 7 7"/></svg></span></button>
79
+ </div>
80
+ </div>
81
+ </div>
82
+ </div>
83
+ </div>
84
+
85
+ <!-- ============ 设置视图 ============ -->
86
+ <div id="view-settings" class="view">
87
+ <div class="settings-wrap">
88
+ <nav class="settings-nav">
89
+ <button class="ghost settings-back" id="settings-back"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 12H4"/><path d="m11 5-7 7 7 7"/></svg><span>返回</span></button>
90
+ <strong>设置</strong>
91
+ <button class="stab active" data-s="providers">模型供应商</button>
92
+ <button class="stab" data-s="agents">Agent 发现</button>
93
+ <button class="stab" data-s="capture">会话捕获</button>
94
+ <button class="stab" data-s="about">关于</button>
95
+ </nav>
96
+ <div class="settings-body">
97
+ <div class="spanel active" id="s-providers">
98
+ <h2>模型供应商</h2>
99
+ <p class="sub">一家供应商配置一次，Claude Code、Codex 与 OpenCode 共用。填写两种 API 端点及对应模型名，API Key 单独加密存储。</p>
100
+ <div class="prov-cols">
101
+ <aside class="mgmt-side">
102
+ <div class="mgmt-group">自定义供应商</div>
103
+ <div id="provider-list"></div>
104
+ <button class="mgmt-item" id="mgmt-add"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg><span class="grow">添加供应商</span></button>
105
+ </aside>
106
+ <div class="mgmt-detail" id="provider-detail"><div class="empty-models">选择或添加一个供应商。</div></div>
107
+ </div>
108
+ </div>
109
+ <div class="spanel" id="s-agents">
110
+ <h2>Agent 发现</h2>
111
+ <p class="sub">自动扫描本机可用的 Agent 程序;不可用或未接入的会如实标注。</p>
112
+ <div id="agent-cards"></div>
113
+ <button class="ghost" id="btn-rescan"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M3 12a9 9 0 1 0 3-6.7"/><path d="M3 4v5h5"/></svg><span>重新扫描</span></button>
114
+ </div>
115
+ <div class="spanel" id="s-capture">
116
+ <h2>会话捕获</h2>
117
+ <p class="sub">默认关闭:终端是内部 AI 运行时,你在这里与 AI 的对话不会进入开发对话记录(知识库的会话浏览)。开启后,此后新建的终端对话会像 CLI 工具对话一样被留档;已存在的会话不受影响。</p>
118
+ <label style="display:flex;align-items:center;gap:8px;cursor:pointer;font-size:13px">
119
+ <input type="checkbox" id="capture-toggle">
120
+ <span>记录终端对话到开发对话记录</span>
121
+ </label>
122
+ <p class="sub" id="capture-note" style="margin-top:10px"></p>
123
+ </div>
124
+ <div class="spanel" id="s-about">
125
+ <h2>关于</h2>
126
+ <p class="sub" id="about-text"></p>
127
+ <div class="auth-note">本页面由 Agent Terminal 服务直接托管,与 API 同版本发布;宿主可通过 iframe 嵌入本页(UI 与服务同版本,天然消灭版本漂移)。</div>
128
+ </div>
129
+ </div>
130
+ </div>
131
+ </div>
132
+
133
+ <!-- ============ 添加项目弹窗 ============ -->
134
+ <div class="modal" id="modal-add-proj">
135
+ <div class="modal-box">
136
+ <h3>添加项目</h3>
137
+ <p class="sub">手动添加项目:填写本地文件夹的绝对路径作为工作区根目录(点「添加项目」通常直接弹出系统文件夹选择器,无需手填)。</p>
138
+ <div class="f"><label>本地文件夹(绝对路径)</label>
139
+ <div class="path-row">
140
+ <input class="fin" id="np-path" placeholder="D:\path\to\project" spellcheck="false">
141
+ <button type="button" class="ghost browse" id="np-browse" title="打开系统文件夹选择器">浏览…</button>
142
+ </div>
143
+ </div>
144
+ <div class="f"><label>项目名称</label><input class="fin" id="np-name" placeholder="自动使用文件夹名"></div>
145
+ <div class="form-error" id="np-error" hidden></div>
146
+ <div class="modal-actions">
147
+ <button class="ghost" id="np-cancel">取消</button>
148
+ <button class="cta" id="np-confirm" disabled>添加项目</button>
149
+ </div>
150
+ </div>
151
+ </div>
152
+
153
+ <div class="toast-host" id="toast" aria-live="polite"></div>
154
+
155
+ <script src="/packages/client/index.js"></script>
156
+ <script src="./app.js"></script>
157
+ </body>
158
+ </html>
package/apps/ai-profile-settings-host/index.html ADDED
@@ -0,0 +1,25 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width,initial-scale=1">
6
+ <title>AI Profile Settings</title>
7
+ <link rel="stylesheet" href="/packages/ui/theme.css">
8
+ <link rel="stylesheet" href="page.css">
9
+ <script src="/packages/client/index.js"></script>
10
+ <script src="/packages/ui/ai-profile-settings.js"></script>
11
+ </head>
12
+ <body>
13
+ <main class="preview">
14
+ <section class="profile-module">
15
+ <div class="module-bar" id="moduleBar">
16
+ <strong>AI 模型</strong>
17
+ <div class="bar-actions"><span id="listFeedback"></span><button id="addProfile">新增</button></div>
18
+ </div>
19
+ <ai-profile-list id="profileList"></ai-profile-list>
20
+ <ai-profile-editor id="profileEditor" class="is-hidden"></ai-profile-editor>
21
+ </section>
22
+ </main>
23
+ <script src="page.js"></script>
24
+ </body>
25
+ </html>
package/apps/ai-profile-settings-host/page.css ADDED
@@ -0,0 +1 @@
1
+ *{box-sizing:border-box}html,body{min-height:100%;margin:0}body{padding:24px;background:#f5f6f7;color:var(--caw-text);font-family:Inter,ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI","Microsoft YaHei",sans-serif}.preview{width:min(680px,100%);margin:0 auto;padding:16px;border:1px solid var(--caw-line);border-radius:10px;background:var(--caw-panel);box-shadow:0 8px 24px rgba(24,34,48,.06)}.profile-module{min-width:0}.module-bar{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:9px}.module-bar strong{font-size:13px}.bar-actions{display:flex;align-items:center;gap:9px}.bar-actions span{max-width:390px;color:var(--caw-muted);font-size:9px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.bar-actions span.good{color:var(--caw-good)}.bar-actions span.bad{color:var(--caw-bad)}.bar-actions button{height:32px;padding:0 11px;border:0;border-radius:7px;background:var(--caw-accent);color:#fff;font:11px inherit;cursor:pointer}.is-hidden{display:none}@media(max-width:520px){body{padding:10px}.preview{padding:12px}.bar-actions span{max-width:180px}}
package/apps/ai-profile-settings-host/page.js ADDED
@@ -0,0 +1,113 @@
1
+ (function () {
2
+ "use strict";
3
+
4
+ const client = createClaudeWorkbenchClient({ apiBase: "/api/claude-workbench/v1" });
5
+ const moduleBar = document.querySelector("#moduleBar");
6
+ const listFeedback = document.querySelector("#listFeedback");
7
+ const addProfile = document.querySelector("#addProfile");
8
+ const profileList = document.querySelector("#profileList");
9
+ const profileEditor = document.querySelector("#profileEditor");
10
+
11
+ function setListStatus(message, tone = "") {
12
+ listFeedback.textContent = String(message || "");
13
+ listFeedback.className = tone;
14
+ }
15
+
16
+ function testErrorMessage(error) {
17
+ const message = String(error?.message || "连接测试失败");
18
+ if (/timed out|timeout/i.test(message)) return "连接测试超时，请检查请求地址、网络或模型名称";
19
+ if (/invalid.*(?:api )?key|unauthorized|\b401\b/i.test(message)) return "API Key 无效或未授权";
20
+ if (/model.*not found|\b404\b/i.test(message)) return "模型名称或请求地址不存在";
21
+ return message;
22
+ }
23
+
24
+ function showList(message = "", tone = "") {
25
+ moduleBar.classList.remove("is-hidden");
26
+ profileList.classList.remove("is-hidden");
27
+ profileEditor.classList.add("is-hidden");
28
+ profileList.busy = false;
29
+ setListStatus(message, tone);
30
+ }
31
+
32
+ function showEditor(profile) {
33
+ moduleBar.classList.add("is-hidden");
34
+ profileList.classList.add("is-hidden");
35
+ profileEditor.classList.remove("is-hidden");
36
+ profileEditor.profile = profile || null;
37
+ profileEditor.setBusy(false);
38
+ profileEditor.setStatus("");
39
+ }
40
+
41
+ async function refresh() {
42
+ profileList.profiles = await client.listProfiles();
43
+ }
44
+
45
+ async function persist(profile, credential) {
46
+ const saved = await client.saveProfile(profile);
47
+ if (credential) await client.setCredential(saved.id, credential);
48
+ return saved;
49
+ }
50
+
51
+ addProfile.addEventListener("click", () => showEditor(null));
52
+ profileList.addEventListener("profile-edit", (event) => showEditor(event.detail.profile));
53
+ profileEditor.addEventListener("profile-cancel", () => showList());
54
+
55
+ profileEditor.addEventListener("profile-save", async (event) => {
56
+ profileEditor.setBusy(true, "保存中…");
57
+ try {
58
+ await persist(event.detail.profile, event.detail.credential);
59
+ await refresh();
60
+ profileEditor.setBusy(false);
61
+ showList("已保存，配置现在可以使用", "good");
62
+ } catch (error) {
63
+ profileEditor.setBusy(false);
64
+ profileEditor.setStatus(error.message, "bad");
65
+ }
66
+ });
67
+
68
+ profileEditor.addEventListener("profile-test", async (event) => {
69
+ profileEditor.setBusy(true, "测试中…");
70
+ try {
71
+ const result = await client.testProfileDraft(event.detail.profile, event.detail.credential);
72
+ profileEditor.setBusy(false);
73
+ profileEditor.setStatus(
74
+ result.runtimeVerified ? `连接成功 · ${result.model || event.detail.profile.models.default} · ${result.durationMs}ms；请点击保存后生效` : "连接测试失败",
75
+ result.runtimeVerified ? "good" : "bad",
76
+ );
77
+ } catch (error) {
78
+ profileEditor.setBusy(false);
79
+ profileEditor.setStatus(testErrorMessage(error), "bad");
80
+ }
81
+ });
82
+
83
+ profileList.addEventListener("profile-test", async (event) => {
84
+ profileList.busy = true;
85
+ setListStatus("测试中…");
86
+ try {
87
+ const result = await client.testProfileDraft(event.detail.profile, "");
88
+ profileList.busy = false;
89
+ setListStatus(result.runtimeVerified ? `连接成功 · ${result.durationMs}ms` : "连接测试失败", result.runtimeVerified ? "good" : "bad");
90
+ } catch (error) {
91
+ profileList.busy = false;
92
+ setListStatus(testErrorMessage(error), "bad");
93
+ }
94
+ });
95
+
96
+ profileList.addEventListener("profile-delete", async (event) => {
97
+ if (!window.confirm(`删除“${event.detail.profile.name}”？`)) return;
98
+ profileList.busy = true;
99
+ setListStatus("删除中…");
100
+ try {
101
+ await client.deleteProfile(event.detail.profile.id);
102
+ await refresh();
103
+ profileList.busy = false;
104
+ setListStatus("已删除", "good");
105
+ } catch (error) {
106
+ profileList.busy = false;
107
+ setListStatus(error.message, "bad");
108
+ }
109
+ });
110
+
111
+ window.addEventListener("beforeunload", () => client.destroy());
112
+ refresh().catch((error) => setListStatus(error.message, "bad"));
113
+ })();
package/apps/minimal-test-host/README.md ADDED
@@ -0,0 +1,15 @@
1
+ # Minimal Test Host
2
+
3
+ Start the real Workbench Server from the repository root. The test host uses the
4
+ same stable product data directory as an installed Workbench instance, rather
5
+ than a disposable temporary directory:
6
+
7
+ ```powershell
8
+ npm run start:test-host
9
+ ```
10
+
11
+ Then open `http://127.0.0.1:5762/test-host/`. Profile metadata is stored in
12
+ `profiles.v2.json`; credentials are stored separately in `credentials.v1.json`
13
+ under that product data directory. The default mode is `REAL` and an unavailable
14
+ server/runtime is shown as a failure. Fault injection is loaded only after the
15
+ explicit button is pressed and reports are marked `MOCK`.
package/apps/minimal-test-host/host.css ADDED
@@ -0,0 +1,2 @@
1
+ :root{color-scheme:light;--bg:#eaf0f5;--panel:#fff;--panel2:#f6f8fb;--line:#d7e0e9;--text:#152235;--muted:#65758a;--accent:#4f6f8f;--good:#2f7d64;--bad:#ad4f4f}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font-family:Inter,-apple-system,"Segoe UI","Microsoft YaHei",sans-serif}.app{height:100vh;display:grid;grid-template-rows:auto minmax(0,1fr)}header{display:flex;align-items:center;justify-content:space-between;gap:18px;padding:14px 18px;border-bottom:1px solid var(--line);background:var(--panel)}h1{margin:0;font-size:18px}header p{margin:4px 0 0;color:var(--muted);font-size:12px}.badges{display:flex;align-items:center;justify-content:flex-end;gap:7px;flex-wrap:wrap}.badge,button,select{border:1px solid var(--line);border-radius:8px;background:var(--panel2);padding:7px 9px;font:inherit;font-size:12px}.badge{border-radius:999px}.badge.ok,.real{color:var(--good)}.badge.err{color:var(--bad)}button{cursor:pointer}.primary{border-color:transparent;background:var(--accent);color:#fff}.layout{min-height:0;display:grid;grid-template-columns:220px minmax(410px,1fr) 330px;gap:12px;padding:12px}.panel{min-height:0;overflow:hidden;border:1px solid var(--line);border-radius:13px;background:var(--panel)}.panel-title{display:flex;align-items:center;justify-content:space-between;padding:11px 12px;border-bottom:1px solid var(--line);font-size:13px;font-weight:750}.panel-body{height:calc(100% - 44px);padding:10px;overflow:auto}.context{width:100%;margin-bottom:7px;padding:9px;text-align:left}.context.active{border-color:var(--accent);box-shadow:0 0 0 2px rgba(79,111,143,.12)}.context small{display:block;margin-top:4px;color:var(--muted)}label{display:grid;gap:5px;margin-top:13px;color:var(--muted);font-size:11px}select{width:100%;background:#fff}.button-grid{display:grid;grid-template-columns:1fr 1fr;gap:7px;margin-top:14px}.wide{grid-column:1/-1}.hint{color:var(--muted);font-size:11px;line-height:1.55}.workbench{min-height:0}dl{margin:0}.metric{display:grid;grid-template-columns:1fr auto;gap:8px;padding:6px 0;border-bottom:1px solid var(--line);font-size:11px}.metric dt{color:var(--muted)}.metric dd{margin:0;font-weight:700;max-width:180px;overflow:hidden;text-overflow:ellipsis}h3{margin:14px 0 7px;font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}pre{min-height:120px;max-height:220px;margin:0;overflow:auto;padding:8px;border:1px solid var(--line);border-radius:8px;background:#101923;color:#dce8f4;white-space:pre-wrap;font:10px/1.5 Consolas,monospace}.drawer{position:fixed;inset:0;display:none;padding:4vh 4vw;background:rgba(15,23,42,.42);z-index:30}.drawer.open{display:block}.drawer-box{position:relative;height:92vh;border-radius:13px;background:var(--panel);overflow:hidden}.drawer-box>button{position:absolute;right:10px;top:9px;z-index:5}@media(max-width:1150px){.layout{grid-template-columns:210px 1fr}.inspector{display:none}}@media(max-width:760px){.app{height:auto;min-height:100vh}.layout{display:block}.sidebar{margin-bottom:10px}.workbench{height:680px}header{align-items:flex-start;flex-direction:column}}
2
+ .drawer-box{display:grid;grid-template-rows:52px minmax(0,1fr)}.drawer-head{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:0 12px 0 16px;border-bottom:1px solid var(--line);background:var(--panel)}.drawer-head strong{font-size:13px}.drawer-content{min-height:0;overflow:auto;padding:12px}@media(max-width:760px){.drawer{padding:0}.drawer-box{height:100vh;border-radius:0}}
package/apps/minimal-test-host/host.js ADDED
@@ -0,0 +1,35 @@
1
+ (function () {
2
+ 'use strict';
3
+ const contexts=[
4
+ {contextId:'context-a',projectId:'context-a',contextType:'test',displayName:'Context A',projectName:'Context A',workspaceRef:'test-workspace-a'},
5
+ {contextId:'context-b',projectId:'context-b',contextType:'test',displayName:'Context B',projectName:'Context B',workspaceRef:'test-workspace-b'},
6
+ {contextId:'context-c',projectId:'context-c',contextType:'test',displayName:'Context C',projectName:'Context C',workspaceRef:'test-workspace-c'},
7
+ ];
8
+ const apiBase=new URLSearchParams(location.search).get('api')||`${location.origin}/api/claude-workbench/v1`;
9
+ const realClient=window.createClaudeWorkbenchClient({apiBase});
10
+ let activeClient=realClient,current=contexts[0],workbench=null,lastState=null,mounted=0,mode='REAL',lastReport=null;
11
+ const eventLog=document.querySelector('#eventLog');
12
+ const originalSubscribe=realClient.subscribe.bind(realClient);
13
+ realClient.subscribe=(sessionId,onEvent,onError,options)=>originalSubscribe(sessionId,event=>{log('SSE',event);onEvent(event)},onError,options);
14
+ const $=selector=>document.querySelector(selector);
15
+ function log(label,value){const row=`[${new Date().toLocaleTimeString()}] ${label} ${value?JSON.stringify(value):''}`;eventLog.textContent=`${row}\n${eventLog.textContent}`.slice(0,50000)}
16
+ function metric(name,value){return `<div class="metric"><dt>${name}</dt><dd>${value==null?'—':String(value)}</dd></div>`}
17
+ function profileTestError(error){const message=String(error?.message||'连接测试失败');if(/timed out|timeout/i.test(message))return'连接测试超时，请检查请求地址、网络或模型名称';if(/invalid.*(?:api )?key|unauthorized|\b401\b/i.test(message))return'API Key 无效或未授权';if(/model.*not found|\b404\b/i.test(message))return'模型名称或请求地址不存在';return message}
18
+ async function persistProfile(profile,credential){const saved=await realClient.saveProfile(profile);if(credential)await realClient.setCredential(saved.id,credential);return saved}
19
+ function renderMetrics(){const counts=activeClient.resourceCounts?.()||{};const state=lastState||{};$('#metrics').innerHTML=[metric('Mode',mode),metric('Context',current.contextId),metric('Generation',state.contextGeneration??state.contextVersion),metric('Session',state.sessionId),metric('Connection',state.session?.connectionState),metric('State',state.session?.state),metric('Last sequence',state.lastSequence),metric('Lines',state.lines?.length||0),metric('Permission',state.permission?.requestId),metric('Token used',state.tokenUsage?.used||0),metric('Open SSE',counts.streams||0),metric('Pending HTTP',counts.requests||0),metric('Reconnects',counts.reconnects||0),metric('Mounted',mounted)].join('')}
20
+ function selectedContext(){return{...current,aiProfileId:$('#profileSelect').value||undefined}}
21
+ function mount(){if(workbench)return;workbench=document.createElement('claude-workbench-pane');workbench.adapter=activeClient;workbench.context=selectedContext();workbench.addEventListener('workbench-state-change',event=>{lastState=event.detail;renderMetrics()});workbench.addEventListener('workbench-error',event=>log('ERROR',{message:event.detail.error.message}));workbench.addEventListener('open-profile-settings',openProfiles);$('#workbenchMount').appendChild(workbench);mounted++;log('MOUNT',selectedContext());renderMetrics()}
22
+ function unmount(){if(!workbench)return;workbench.destroy();workbench.remove();workbench=null;lastState=null;mounted=Math.max(0,mounted-1);log('UNMOUNT');renderMetrics()}
23
+ function selectContext(next){current=next;document.querySelectorAll('.context').forEach(button=>button.classList.toggle('active',button.dataset.id===next.contextId));if(workbench)workbench.context=selectedContext();log('CONTEXT',next);renderMetrics()}
24
+ async function refresh(){try{const [health,runtime,profiles]=await Promise.all([realClient.health(),realClient.runtime(),realClient.listProfiles()]);$('#serverBadge').textContent=`Server ${health.version}`;$('#serverBadge').className='badge ok';$('#runtimeBadge').textContent=runtime.available?'Runtime available':'Runtime unavailable';$('#runtimeBadge').className=runtime.available?'badge ok':'badge err';const old=$('#profileSelect').value;$('#profileSelect').innerHTML='<option value="">选择 Profile</option>'+profiles.map(p=>`<option value="${p.id}">${p.name||p.id}${p.credentialConfigured?'':' · no key'}</option>`).join('');if(profiles.some(p=>p.id===old))$('#profileSelect').value=old;else if(profiles[0])$('#profileSelect').value=profiles[0].id;$('#profileSettings').profiles=profiles;log('HEALTH',{health,runtime,profiles:profiles.length})}catch(error){$('#serverBadge').textContent='Server offline';$('#serverBadge').className='badge err';log('HEALTH ERROR',{message:error.message})}}
25
+ async function stress(){for(let index=0;index<20;index++){selectContext(contexts[index%2]);await new Promise(resolve=>setTimeout(resolve,40))}log('STRESS COMPLETE',activeClient.resourceCounts?.())}
26
+ async function acceptance(){const startedAt=new Date().toISOString(),checks=[];const check=async(name,fn)=>{try{const detail=await fn();checks.push({name,ok:true,detail})}catch(error){checks.push({name,ok:false,error:error.message})}};await check('server-health',()=>realClient.health());await check('runtime-available',async()=>{const value=await realClient.runtime();if(!value.available)throw new Error('Claude Code runtime unavailable');return value});await check('profile-selected',async()=>{if(!$('#profileSelect').value)throw new Error('Select an AI Profile');return $('#profileSelect').value});await check('profile-real-runtime',async()=>{const result=await realClient.testProfile($('#profileSelect').value);if(!result.runtimeVerified)throw new Error('runtimeVerified=false');return result});await check('context-generation-isolation',async()=>{await stress();if(lastState&&lastState.context?.contextId!==current.contextId)throw new Error('late context state won');return{contextId:current.contextId,generation:lastState?.contextGeneration}});await check('lifecycle-cleanup',async()=>{unmount();await new Promise(resolve=>setTimeout(resolve,20));const counts=activeClient.resourceCounts();if(counts.streams||counts.requests)throw new Error(`resources remain: ${JSON.stringify(counts)}`);mount();return counts});lastReport={mode,serverVersion:($('#serverBadge').textContent||'').replace('Server ',''),runtime:'claude-code',profileId:$('#profileSelect').value||null,checks,resourceLeaks:checks.filter(item=>item.name==='lifecycle-cleanup'&&!item.ok),startedAt,finishedAt:new Date().toISOString()};$('#reportLog').textContent=JSON.stringify(lastReport,null,2);log('ACCEPTANCE',lastReport)}
27
+ function exportReport(){if(!lastReport)return;const blob=new Blob([JSON.stringify(lastReport,null,2)],{type:'application/json'});const link=document.createElement('a');link.href=URL.createObjectURL(blob);link.download=`claude-workbench-${mode.toLowerCase()}-report.json`;link.click();setTimeout(()=>URL.revokeObjectURL(link.href),1000)}
28
+ function openProfiles(){const drawer=$('#profileDrawer');drawer.classList.add('open');drawer.setAttribute('aria-hidden','false');refresh()}
29
+ async function toggleMock(){if(mode==='MOCK'){unmount();activeClient.destroy?.();activeClient=realClient;mode='REAL';$('#modeBadge').textContent='REAL';$('#mockBtn').textContent='Enable Optional Fault Injection';mount();renderMetrics();return}if(!window.createFaultInjectionAdapter){await new Promise((resolve,reject)=>{const script=document.createElement('script');script.src='optional-mock/fault-injection.js';script.onload=resolve;script.onerror=reject;document.head.appendChild(script)})}unmount();activeClient=window.createFaultInjectionAdapter({onRaw:event=>log('MOCK',event)});mode='MOCK';$('#modeBadge').textContent='MOCK';$('#mockBtn').textContent='Disable Fault Injection';mount();renderMetrics()}
30
+ const profileSettings=$('#profileSettings');
31
+ profileSettings.addEventListener('profile-save',async event=>{profileSettings.setBusy(true,'保存中…');try{const saved=await persistProfile(event.detail.profile,event.detail.credential);await refresh();profileSettings.setBusy(false);profileSettings.closeEditor();profileSettings.setStatus('已保存，配置现在可以使用','good');log('PROFILE SAVE',{id:saved.id})}catch(error){profileSettings.setBusy(false);profileSettings.setStatus(error.message,'bad');log('PROFILE SAVE ERROR',{message:error.message})}});
32
+ profileSettings.addEventListener('profile-delete',async event=>{if(!window.confirm(`删除“${event.detail.profile.name}”？`))return;profileSettings.setBusy(true,'删除中…');try{await realClient.deleteProfile(event.detail.profile.id);await refresh();profileSettings.setBusy(false);profileSettings.setStatus('已删除','good');log('PROFILE DELETE',{id:event.detail.profile.id})}catch(error){profileSettings.setBusy(false);profileSettings.setStatus(error.message,'bad');log('PROFILE DELETE ERROR',{message:error.message})}});
33
+ profileSettings.addEventListener('profile-test',async event=>{profileSettings.setBusy(true,'测试中…');try{const result=await realClient.testProfileDraft(event.detail.profile,event.detail.credential);profileSettings.setBusy(false);profileSettings.setStatus(result.runtimeVerified?`连接成功 · ${result.model||event.detail.profile.models.default} · ${result.durationMs}ms；请点击保存后生效`:'连接测试失败',result.runtimeVerified?'good':'bad');log('REAL PROFILE TEST',result)}catch(error){const message=profileTestError(error);profileSettings.setBusy(false);profileSettings.setStatus(message,'bad');log('PROFILE TEST ERROR',{message})}});
34
+ $('#contexts').innerHTML=contexts.map((c,index)=>`<button class="context ${index===0?'active':''}" data-id="${c.contextId}"><strong>${c.displayName}</strong><small>${c.workspaceRef}</small></button>`).join('');$('#contexts').onclick=event=>{const button=event.target.closest('.context');if(button)selectContext(contexts.find(item=>item.contextId===button.dataset.id))};$('#mountBtn').onclick=mount;$('#unmountBtn').onclick=unmount;$('#remountBtn').onclick=()=>{unmount();mount()};$('#stressBtn').onclick=stress;$('#refreshBtn').onclick=refresh;$('#profilesBtn').onclick=openProfiles;$('#closeProfiles').onclick=()=>{const drawer=$('#profileDrawer');drawer.classList.remove('open');drawer.setAttribute('aria-hidden','true')};$('#acceptBtn').onclick=acceptance;$('#clearBtn').onclick=()=>eventLog.textContent='';$('#exportBtn').onclick=exportReport;$('#mockBtn').onclick=toggleMock;$('#profileSelect').onchange=()=>{if(workbench)workbench.context=selectedContext()};refresh().then(mount);setInterval(renderMetrics,500);
35
+ })();
package/apps/minimal-test-host/index.html ADDED
@@ -0,0 +1,58 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width,initial-scale=1">
6
+ <title>Claude AI Workbench · Minimal Test Host</title>
7
+ <link rel="stylesheet" href="/reference-ui/dist/claude-ai-workbench-theme.css">
8
+ <link rel="stylesheet" href="/packages/ui/theme.css">
9
+ <link rel="stylesheet" href="host.css">
10
+ <script src="/packages/client/index.js"></script>
11
+ <script src="/packages/ui/ai-profile-settings.js"></script>
12
+ <script src="/reference-ui/dist/claude-workbench-core.js"></script>
13
+ <script src="/reference-ui/dist/claude-workbench-pane.js"></script>
14
+ </head>
15
+ <body>
16
+ <div class="app">
17
+ <header>
18
+ <div><h1>Claude AI Workbench</h1><p>Minimal Test Host · 真实 Runtime 为默认链路</p></div>
19
+ <div class="badges"><span id="serverBadge" class="badge">Server…</span><span id="runtimeBadge" class="badge">Runtime…</span><span id="modeBadge" class="badge real">REAL</span><button id="refreshBtn">刷新</button><button id="profilesBtn">AI Profiles</button><button id="acceptBtn" class="primary">运行验收</button></div>
20
+ </header>
21
+ <main class="layout">
22
+ <aside class="panel sidebar">
23
+ <div class="panel-title">Test Contexts</div>
24
+ <div class="panel-body">
25
+ <div id="contexts"></div>
26
+ <label>AI Profile<select id="profileSelect"><option value="">选择 Profile</option></select></label>
27
+ <div class="button-grid"><button id="mountBtn">Mount</button><button id="unmountBtn">Unmount</button><button id="remountBtn">Remount</button><button id="stressBtn">A/B ×20</button><button id="mockBtn" class="wide">Enable Optional Fault Injection</button></div>
28
+ <p class="hint">浏览器只发送 workspaceRef；绝对工作目录由 Server 白名单解析。</p>
29
+ </div>
30
+ </aside>
31
+ <section id="workbenchMount" class="workbench"></section>
32
+ <aside class="panel inspector">
33
+ <div class="panel-title">Runtime Inspector <button id="clearBtn">清空</button></div>
34
+ <div class="panel-body">
35
+ <dl id="metrics"></dl>
36
+ <h3>Raw SSE / Lifecycle Events</h3>
37
+ <pre id="eventLog"></pre>
38
+ <h3>Acceptance Report</h3>
39
+ <pre id="reportLog">尚未运行</pre>
40
+ <button id="exportBtn">导出报告 JSON</button>
41
+ </div>
42
+ </aside>
43
+ </main>
44
+ </div>
45
+ <div id="profileDrawer" class="drawer" aria-hidden="true">
46
+ <section class="drawer-box" role="dialog" aria-modal="true" aria-labelledby="profileDrawerTitle">
47
+ <header class="drawer-head">
48
+ <strong id="profileDrawerTitle">AI 模型配置</strong>
49
+ <button id="closeProfiles" type="button">关闭</button>
50
+ </header>
51
+ <div class="drawer-content">
52
+ <ai-profile-settings id="profileSettings"></ai-profile-settings>
53
+ </div>
54
+ </section>
55
+ </div>
56
+ <script src="host.js"></script>
57
+ </body>
58
+ </html>
package/apps/minimal-test-host/optional-mock/fault-injection.js ADDED
@@ -0,0 +1,15 @@
1
+ (function(global){
2
+ global.createFaultInjectionAdapter=function createFaultInjectionAdapter(options={}){
3
+ const sessions=new Map(),streams=new Set();let requests=0,sequence=0;
4
+ const raw=event=>{options.onRaw?.(event);return event};
5
+ return{
6
+ async listSessions(context){requests++;try{return[...sessions.values()].filter(s=>s.contextId===context.contextId).map(s=>s.summary)}finally{requests--}},
7
+ async startSession(context){const sessionId=`mock-${context.contextId}-${Date.now().toString(36)}`;const summary={sessionId,contextId:context.contextId,title:'Fault injection session',active:true,state:'idle',model:'mock-model',aiProfileId:context.aiProfileId||'mock-profile'};sessions.set(sessionId,{contextId:context.contextId,summary,events:[]});return summary},
8
+ async loadSession(sessionId){const s=sessions.get(sessionId);return{session:s.summary,events:s.events,permission:null,permissionMode:'default',tokenUsage:{used:0,total:1000,hasUsage:false}}},
9
+ subscribe(sessionId,onEvent){const record={sessionId,onEvent,closed:false};streams.add(record);return()=>{record.closed=true;streams.delete(record)}},
10
+ async send(args){const s=sessions.get(args.sessionId);const emit=(type,extra={},forced)=>{const event=raw({type,sessionId:args.sessionId,contextId:s.contextId,sequence:forced||++sequence,at:new Date().toISOString(),...extra});s.events.push(event);for(const stream of streams)if(!stream.closed&&stream.sessionId===args.sessionId)stream.onEvent(event)};emit('claude/user-prompt',{text:args.text});emit('claude/text-start',{id:'answer'});emit('claude/text-delta',{id:'answer',text:'Fault '});emit('claude/text-delta',{id:'answer',text:'duplicate ignored'},sequence);emit('claude/text-delta',{id:'answer',text:'injection active. '});setTimeout(()=>emit('claude/result',{id:'answer',result:'Fault injection active. Duplicate sequence was ignored.'}),30)},
11
+ async resolvePermission(){},async abort(){},async setPermissionMode(){},
12
+ resourceCounts(){return{streams:streams.size,requests,reconnects:0}},destroy(){streams.clear()}
13
+ }
14
+ }
15
+ })(window);
package/docs/sdk/FILE_LAYOUT.md ADDED
@@ -0,0 +1,31 @@
1
+ # SDK 文件布局
2
+
3
+ ```text
4
+ claude-ai-workbench/
5
+ ├─ packages/ # 可发布 SDK 源码
6
+ │ ├─ contracts/ # 公共类型、常量和输入标准化
7
+ │ ├─ client/ # 浏览器/Node REST + SSE Client
8
+ │ ├─ core/ # 终端状态机、上下文隔离、会话生命周期
9
+ │ ├─ ui/
10
+ │ │ ├─ ai-profile-settings.js # AI Profile 默认入口
11
+ │ │ ├─ ai-profile-settings.d.ts
12
+ │ │ ├─ claude-terminal.js # 产品级 Claude Code 终端入口
13
+ │ │ ├─ claude-terminal.d.ts
14
+ │ │ └─ theme.css
15
+ │ └─ server/ # REST/SSE Server 与 CLI
16
+ ├─ apps/
17
+ │ ├─ ai-profile-settings-host/ # AI Profile 独立接入示例
18
+ │ ├─ claude-terminal-host/ # 无调试面板的终端接入示例
19
+ │ └─ minimal-test-host/ # 内部验收、故障注入和原始事件检查
20
+ ├─ docs/sdk/ # 对外文档和 OpenAPI
21
+ ├─ scripts/ # 校验与 SDK 打包
22
+ └─ dist/sdk/ # 自动生成的 tgz 与 SHA-256 manifest
23
+ ```
24
+
25
+ ## 边界规则
26
+
27
+ 1. 产品宿主只使用 `contracts`、`client`、`core`、`ui` 的公共入口，不复制组件源码。
28
+ 2. `claude-terminal` 不创建 Client、不写死 API 地址、不读取凭据；宿主注入 Client 和 `WorkbenchContext`。
29
+ 3. `minimal-test-host` 是内部 QA 工具，不是产品界面；运行指标、Raw SSE、故障注入不得进入终端组件。
30
+ 4. API Key 只通过 credential 接口或临时测试请求进入 Server，公开 Profile 永不返回明文。
31
+ 5. `dist/sdk/` 每次发布重新生成，不手工修改。
package/docs/sdk/INTEGRATION.md ADDED
@@ -0,0 +1,126 @@
1
+ # SDK 接入说明
2
+
3
+ ## 1. 安装
4
+
5
+ ```bash
6
+ npm install @claude-ai-workbench/contracts@0.2.0 \
7
+ @claude-ai-workbench/client@0.2.0 \
8
+ @claude-ai-workbench/core@0.2.0 \
9
+ @claude-ai-workbench/ui@0.2.0
10
+ ```
11
+
12
+ 运行服务的机器另行安装：
13
+
14
+ ```bash
15
+ npm install @claude-ai-workbench/server@0.2.0
16
+ ```
17
+
18
+ ## 2. 启动 Server
19
+
20
+ ```powershell
21
+ $env:CLAUDE_AI_WORKBENCH_DATA_DIR = 'D:\data\claude-workbench'
22
+ $env:CLAUDE_WORKBENCH_PORT = '5760'
23
+ npx claude-workbench-server
24
+ ```
25
+
26
+ Node.js 也可直接嵌入：
27
+
28
+ ```js
29
+ const { createWorkbenchServer } = require("@claude-ai-workbench/server");
30
+ const app = createWorkbenchServer({ dataDir: "D:/data/claude-workbench", serveHost: false });
31
+ app.server.listen(5760, "127.0.0.1");
32
+ ```
33
+
34
+ ## 3. 接入 Claude Code 终端
35
+
36
+ ```js
37
+ import "@claude-ai-workbench/ui/theme.css";
38
+ import "@claude-ai-workbench/ui/claude-terminal";
39
+ import { createClaudeWorkbenchClient } from "@claude-ai-workbench/client";
40
+
41
+ const client = createClaudeWorkbenchClient({
42
+ apiBase: "http://127.0.0.1:5760/api/claude-workbench/v1",
43
+ });
44
+ const terminal = document.querySelector("#terminal");
45
+
46
+ terminal.client = client;
47
+ terminal.context = {
48
+ contextId: "project-42",
49
+ contextType: "project",
50
+ displayName: "知识库项目",
51
+ workspaceRef: "registered-workspace-42",
52
+ aiProfileId: "claude-sonnet",
53
+ };
54
+
55
+ terminal.addEventListener("terminal-error", ({ detail }) => console.error(detail));
56
+ terminal.addEventListener("terminal-command", event => {
57
+ if (event.detail.command === "config") {
58
+ event.preventDefault();
59
+ openHostSettings();
60
+ }
61
+ });
62
+ window.addEventListener("beforeunload", () => {
63
+ terminal.destroy();
64
+ client.destroy();
65
+ });
66
+ ```
67
+
68
+ ```html
69
+ <claude-workbench-pane id="terminal"></claude-workbench-pane>
70
+ ```
71
+
72
+ `workspaceRef` 是 Server 白名单中注册的工作区标识，不能由浏览器传入任意绝对路径。切换项目时只需重新赋值 `terminal.context`；Core 会中止旧请求、关闭旧 SSE，并隔离新旧上下文事件。
73
+
74
+ 快捷命令不是前端常量。Core 会调用 `GET /sessions/{sessionId}/commands`，从当前 Claude Code 运行时读取内置命令、Skills、Plugins 和 MCP 命令；输入 `/` 后可搜索，选中后仍可补充参数再发送。`terminal-command` 是可取消事件，宿主只在确实需要接管某个命令时调用 `preventDefault()`。
75
+
76
+ 图片默认支持点击选择、拖入和从剪贴板粘贴，格式为 JPEG、PNG、GIF、WebP；单张上限 10 MiB，一次最多 20 张且总计不超过 20 MiB。组件将 Base64 图片交给 Client，Server 验证真实文件签名并保存到产品数据目录的 `attachments/`，会话事件只保存可读取的附件 URL，不保存用户图片的 Base64 副本。宿主要使用自有文件选择器时可拦截：
77
+
78
+ ```js
79
+ terminal.addEventListener("terminal-attach-request", async event => {
80
+ event.preventDefault();
81
+ const files = await openHostImagePicker();
82
+ await event.detail.addFiles(files);
83
+ });
84
+ ```
85
+
86
+ 不使用 UI 时，可直接调用同一公共 API：
87
+
88
+ ```js
89
+ const commands = await client.listCommands(sessionId);
90
+ await client.send({
91
+ sessionId,
92
+ text: "说明这张图",
93
+ attachments: [{ name: "screen.png", mediaType: "image/png", data: base64 }],
94
+ });
95
+ ```
96
+
97
+ ## 4. 接入 AI Profile UI
98
+
99
+ ```js
100
+ import "@claude-ai-workbench/ui";
101
+ import "@claude-ai-workbench/ui/theme.css";
102
+ ```
103
+
104
+ ```html
105
+ <ai-profile-list id="profileList"></ai-profile-list>
106
+ <ai-profile-editor id="profileEditor"></ai-profile-editor>
107
+ ```
108
+
109
+ AI Profile UI 只发布 `profile-save`、`profile-test`、`profile-edit`、`profile-delete` 等 DOM 事件，宿主用 Client 完成持久化。测试连接不会保存；只有 `saveProfile` 和 `setCredential` 会写入产品数据目录。
110
+
111
+ ## 5. 不使用 npm 的浏览器接入
112
+
113
+ 按以下顺序加载静态文件：
114
+
115
+ ```html
116
+ <link rel="stylesheet" href="/vendor/claude-workbench/ui/theme.css">
117
+ <script src="/vendor/claude-workbench/client/index.js"></script>
118
+ <script src="/vendor/claude-workbench/core/index.js"></script>
119
+ <script src="/vendor/claude-workbench/ui/claude-terminal.js"></script>
120
+ ```
121
+
122
+ 加载后可使用全局函数 `createClaudeWorkbenchClient`、全局对象 `ClaudeWorkbenchCore` 和 `<claude-workbench-pane>`。
123
+
124
+ ## 6. 非 JavaScript 程序接入
125
+
126
+ C++、C#、Java 等程序直接按 [openapi.yaml](openapi.yaml) 调用 JSON REST API。OpenAPI 相当于语言无关的接口头文件；UI 仍由 WebView 或浏览器宿主加载。