@axhub/genie 0.1.6 → 0.1.8

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 (37) hide show
  1. package/dist/api-docs.html +351 -909
  2. package/dist/assets/index-CVjMty4a.js +902 -0
  3. package/dist/assets/index-eo5scY_Z.css +32 -0
  4. package/dist/index.html +5 -5
  5. package/dist/manifest.json +2 -2
  6. package/package.json +8 -2
  7. package/server/channels/core/ChannelManager.js +399 -0
  8. package/server/channels/core/PluginManager.js +59 -0
  9. package/server/channels/index.js +3 -0
  10. package/server/channels/plugins/BasePlugin.js +46 -0
  11. package/server/channels/plugins/dingtalk/DingTalkAdapter.js +156 -0
  12. package/server/channels/plugins/dingtalk/DingTalkPlugin.js +592 -0
  13. package/server/channels/plugins/dingtalk/index.js +2 -0
  14. package/server/channels/plugins/lark/LarkAdapter.js +100 -0
  15. package/server/channels/plugins/lark/LarkCards.js +43 -0
  16. package/server/channels/plugins/lark/LarkPlugin.js +260 -0
  17. package/server/channels/runtime/AgentRuntimeAdapter.js +179 -0
  18. package/server/channels/runtime/DingTalkStreamWriter.js +105 -0
  19. package/server/channels/runtime/LarkStreamWriter.js +99 -0
  20. package/server/channels/store/ChannelStore.js +236 -0
  21. package/server/database/db.js +109 -1
  22. package/server/database/init.sql +47 -1
  23. package/server/gemini-cli.js +280 -0
  24. package/server/index.js +230 -11
  25. package/server/openai-codex.js +104 -8
  26. package/server/opencode-cli.js +673 -0
  27. package/server/projects.js +645 -5
  28. package/server/routes/agent.js +40 -12
  29. package/server/routes/channels.js +221 -0
  30. package/server/routes/cli-auth.js +317 -0
  31. package/server/routes/commands.js +29 -3
  32. package/server/routes/git.js +15 -5
  33. package/server/routes/opencode.js +72 -0
  34. package/shared/modelConstants.js +62 -17
  35. package/dist/assets/index-CtRxrKDm.css +0 -32
  36. package/dist/assets/index-OENtErNy.js +0 -1249
  37. package/server/database/auth.db +0 -0
package/dist/api-docs.html CHANGED
@@ -1,922 +1,364 @@
1
1
  <!DOCTYPE html>
2
- <html lang="en">
2
+ <html lang="zh-CN">
3
3
  <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Axhub Genie - API Documentation</title>
7
- <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
8
- <link rel="icon" type="image/png" href="/favicon.png" />
9
-
10
- <!-- Prism.js for syntax highlighting -->
11
- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
12
-
13
- <style>
14
- * {
15
- margin: 0;
16
- padding: 0;
17
- box-sizing: border-box;
18
- }
19
-
20
- :root {
21
- --gray-50: #f9fafb;
22
- --gray-100: #f3f4f6;
23
- --gray-200: #e5e7eb;
24
- --gray-600: #4b5563;
25
- --gray-700: #374151;
26
- --gray-800: #1f2937;
27
- --gray-900: #111827;
28
- --primary: #2563eb;
29
- --primary-dark: #1d4ed8;
30
- --green: #10b981;
31
- --red: #ef4444;
32
- }
33
-
34
- body {
35
- font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
36
- line-height: 1.6;
37
- color: var(--gray-900);
38
- background: var(--gray-50);
39
- margin: 0;
40
- }
41
-
42
- header {
43
- background: white;
44
- border-bottom: 1px solid var(--gray-200);
45
- padding: 1.5rem 0;
46
- position: sticky;
47
- top: 0;
48
- z-index: 100;
49
- }
50
-
51
- .header-content {
52
- display: flex;
53
- align-items: center;
54
- justify-content: space-between;
55
- padding: 0 2rem;
56
- }
57
-
58
- .brand {
59
- display: flex;
60
- align-items: center;
61
- gap: 0.75rem;
62
- }
63
-
64
- .brand-icon {
65
- width: 32px;
66
- height: 32px;
67
- background: var(--primary);
68
- border-radius: 8px;
69
- display: flex;
70
- align-items: center;
71
- justify-content: center;
72
- }
73
-
74
- .brand-icon svg {
75
- width: 16px;
76
- height: 16px;
77
- stroke: white;
78
- }
79
-
80
- .brand-text h1 {
81
- font-size: 1.25rem;
82
- font-weight: 700;
83
- color: var(--gray-900);
84
- }
85
-
86
- .brand-text .subtitle {
87
- font-size: 0.875rem;
88
- color: var(--gray-600);
89
- }
90
-
91
- .back-link {
92
- display: flex;
93
- align-items: center;
94
- gap: 0.5rem;
95
- padding: 0.5rem 1rem;
96
- background: var(--primary);
97
- color: white;
98
- text-decoration: none;
99
- border-radius: 6px;
100
- font-size: 0.875rem;
101
- font-weight: 500;
102
- transition: background 0.2s;
103
- }
104
-
105
- .back-link:hover {
106
- background: var(--primary-dark);
107
- }
108
-
109
- .back-link svg {
110
- width: 16px;
111
- height: 16px;
112
- }
113
-
114
- .main-layout {
115
- display: flex;
116
- }
117
-
118
- .sidebar {
119
- width: 240px;
120
- background: white;
121
- border-right: 1px solid var(--gray-200);
122
- padding: 2rem 0;
123
- position: sticky;
124
- top: 73px;
125
- height: calc(100vh - 73px);
126
- overflow-y: auto;
127
- flex-shrink: 0;
128
- }
129
-
130
- .sidebar-title {
131
- font-size: 0.75rem;
132
- font-weight: 600;
133
- text-transform: uppercase;
134
- color: var(--gray-600);
135
- padding: 0 1.5rem;
136
- margin: 1.5rem 0 0.5rem;
137
- }
138
-
139
- .sidebar a {
140
- display: block;
141
- padding: 0.625rem 1.5rem;
142
- color: var(--gray-700);
143
- text-decoration: none;
144
- font-size: 0.875rem;
145
- transition: all 0.15s;
146
- border-left: 3px solid transparent;
147
- }
148
-
149
- .sidebar a:hover {
150
- background: var(--gray-50);
151
- color: var(--primary);
152
- border-left-color: var(--primary);
153
- }
154
-
155
- .content-wrapper {
156
- flex: 1;
157
- display: flex;
158
- flex-direction: column;
159
- min-height: calc(100vh - 73px);
160
- }
161
-
162
- .section-row {
163
- display: grid;
164
- grid-template-columns: 1fr 600px;
165
- }
166
-
167
- .docs-section {
168
- padding: 3rem 3rem;
169
- background: white;
170
- border-right: 1px solid var(--gray-200);
171
- }
172
-
173
- .examples-section {
174
- padding: 3rem 2rem;
175
- background: #0d1117;
176
- color: #e6edf3;
177
- }
178
-
179
- .examples-section h4 {
180
- color: #e6edf3;
181
- font-size: 0.875rem;
182
- font-weight: 600;
183
- margin-bottom: 1rem;
184
- text-transform: uppercase;
185
- letter-spacing: 0.05em;
186
- }
187
-
188
- h2 {
189
- font-size: 2rem;
190
- font-weight: 700;
191
- margin-bottom: 1rem;
192
- color: var(--gray-900);
193
- }
194
-
195
- h3 {
196
- font-size: 1.375rem;
197
- font-weight: 600;
198
- margin: 2.5rem 0 1rem;
199
- color: var(--gray-900);
200
- }
201
-
202
- h4 {
203
- font-size: 1rem;
204
- font-weight: 600;
205
- margin: 1.5rem 0 0.75rem;
206
- color: var(--gray-700);
207
- }
208
-
209
- p {
210
- margin-bottom: 1rem;
211
- color: var(--gray-600);
212
- }
213
-
214
- .intro {
215
- background: linear-gradient(135deg, rgba(37, 99, 235, 0.08) 0%, rgba(59, 130, 246, 0.08) 100%);
216
- border: 1px solid rgba(37, 99, 235, 0.2);
217
- border-radius: 8px;
218
- padding: 1.5rem;
219
- margin-bottom: 2rem;
220
- }
221
-
222
- .intro p {
223
- color: var(--gray-700);
224
- margin: 0;
225
- }
226
-
227
- .endpoint {
228
- margin: 2rem 0;
229
- padding: 1.5rem;
230
- background: var(--gray-50);
231
- border-radius: 8px;
232
- border: 1px solid var(--gray-200);
233
- }
234
-
235
- .endpoint-header {
236
- display: flex;
237
- align-items: center;
238
- gap: 1rem;
239
- margin-bottom: 1rem;
240
- }
241
-
242
- .method {
243
- padding: 0.375rem 0.875rem;
244
- border-radius: 6px;
245
- font-weight: 700;
246
- font-size: 0.75rem;
247
- text-transform: uppercase;
248
- }
249
-
250
- .method-post {
251
- background: var(--green);
252
- color: white;
253
- }
254
-
255
- .endpoint-path {
256
- font-family: 'Monaco', 'Menlo', monospace;
257
- font-size: 0.9375rem;
258
- font-weight: 600;
259
- }
260
-
261
- table {
262
- width: 100%;
263
- border-collapse: collapse;
264
- margin: 1rem 0;
265
- font-size: 0.875rem;
266
- }
267
-
268
- th {
269
- text-align: left;
270
- padding: 0.875rem;
271
- background: var(--gray-100);
272
- border: 1px solid var(--gray-200);
273
- font-weight: 600;
274
- color: var(--gray-800);
275
- }
276
-
277
- td {
278
- padding: 0.875rem;
279
- border: 1px solid var(--gray-200);
280
- color: var(--gray-700);
281
- }
282
-
283
- code {
284
- background: rgba(37, 99, 235, 0.08);
285
- padding: 0.1875rem 0.5rem;
286
- border-radius: 4px;
287
- font-family: 'Monaco', 'Menlo', monospace;
288
- font-size: 0.875em;
289
- color: var(--primary-dark);
290
- }
291
-
292
- .api-url {
293
- color: #60a5fa;
294
- }
295
-
296
- .badge {
297
- display: inline-block;
298
- padding: 0.1875rem 0.625rem;
299
- border-radius: 12px;
300
- font-size: 0.6875rem;
301
- font-weight: 600;
302
- text-transform: uppercase;
303
- }
304
-
305
- .badge-required {
306
- background: var(--red);
307
- color: white;
308
- }
309
-
310
- .badge-optional {
311
- background: var(--gray-200);
312
- color: var(--gray-700);
313
- }
314
-
315
- .note {
316
- padding: 1.25rem;
317
- background: rgba(37, 99, 235, 0.05);
318
- border-left: 4px solid var(--primary);
319
- border-radius: 8px;
320
- margin: 1rem 0;
321
- font-size: 0.875rem;
322
- }
323
-
324
- /* Code tabs in side panel */
325
- .tab-buttons {
326
- display: flex;
327
- gap: 0.5rem;
328
- margin-bottom: 1rem;
329
- }
330
-
331
- .tab-button {
332
- padding: 0.5rem 1rem;
333
- background: transparent;
334
- border: 1px solid #30363d;
335
- cursor: pointer;
336
- font-size: 0.8125rem;
337
- font-weight: 500;
338
- color: #7d8590;
339
- border-radius: 6px;
340
- transition: all 0.2s;
341
- }
342
-
343
- .tab-button:hover {
344
- color: #e6edf3;
345
- border-color: #58a6ff;
346
- }
347
-
348
- .tab-button.active {
349
- color: #e6edf3;
350
- background: #1f6feb;
351
- border-color: #1f6feb;
352
- }
353
-
354
- .tab-content {
355
- display: none;
356
- }
357
-
358
- .tab-content.active {
359
- display: block;
360
- }
361
-
362
- pre[class*="language-"] {
363
- margin: 0 0 1.5rem 0;
364
- border-radius: 6px;
365
- font-size: 0.8125rem;
366
- }
367
-
368
- .example-block {
369
- margin-bottom: 2rem;
370
- }
371
-
372
- @media (max-width: 1400px) {
373
- .section-row {
374
- grid-template-columns: 1fr 500px;
375
- }
376
- }
377
-
378
- @media (max-width: 1200px) {
379
- .section-row {
380
- grid-template-columns: 1fr;
381
- }
382
-
383
- .examples-section {
384
- border-top: 1px solid #30363d;
385
- }
386
- }
387
-
388
- @media (max-width: 768px) {
389
- .main-layout {
390
- flex-direction: column;
391
- }
392
-
393
- .sidebar {
394
- width: 100%;
395
- position: relative;
396
- height: auto;
397
- border-right: none;
398
- border-bottom: 1px solid var(--gray-200);
399
- }
400
-
401
- .docs-section {
402
- padding: 2rem 1.5rem;
403
- }
404
-
405
- .examples-section {
406
- padding: 2rem 1.5rem;
407
- }
408
- }
409
- </style>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>开放接口使用文档（MVP）</title>
7
+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
8
+ <link rel="icon" type="image/png" href="/favicon.png" />
9
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
10
+ <style>
11
+ :root {
12
+ --bg: #f5f7fb;
13
+ --surface: #ffffff;
14
+ --border: #e5e7eb;
15
+ --text: #0f172a;
16
+ --muted: #4b5563;
17
+ --primary: #1d4ed8;
18
+ --primary-soft: #dbeafe;
19
+ --sidebar-width: 260px;
20
+ }
21
+
22
+ * {
23
+ box-sizing: border-box;
24
+ }
25
+
26
+ body {
27
+ margin: 0;
28
+ font-family: "SF Pro Text", "PingFang SC", "Hiragino Sans GB", "Segoe UI", sans-serif;
29
+ background: radial-gradient(circle at top right, #e8f1ff 0%, var(--bg) 45%);
30
+ color: var(--text);
31
+ line-height: 1.65;
32
+ }
33
+
34
+ header {
35
+ position: sticky;
36
+ top: 0;
37
+ z-index: 10;
38
+ display: flex;
39
+ align-items: center;
40
+ justify-content: space-between;
41
+ padding: 14px 20px;
42
+ background: rgba(255, 255, 255, 0.9);
43
+ border-bottom: 1px solid var(--border);
44
+ backdrop-filter: blur(8px);
45
+ }
46
+
47
+ .brand {
48
+ display: flex;
49
+ flex-direction: column;
50
+ gap: 2px;
51
+ }
52
+
53
+ .brand strong {
54
+ font-size: 16px;
55
+ font-weight: 700;
56
+ letter-spacing: 0.2px;
57
+ }
58
+
59
+ .brand small {
60
+ color: var(--muted);
61
+ font-size: 12px;
62
+ }
63
+
64
+ .actions {
65
+ display: flex;
66
+ align-items: center;
67
+ gap: 10px;
68
+ }
69
+
70
+ .actions a {
71
+ display: inline-flex;
72
+ align-items: center;
73
+ justify-content: center;
74
+ padding: 7px 12px;
75
+ border-radius: 8px;
76
+ text-decoration: none;
77
+ border: 1px solid var(--border);
78
+ color: var(--text);
79
+ font-size: 13px;
80
+ font-weight: 600;
81
+ transition: all 0.2s;
82
+ background: white;
83
+ }
84
+
85
+ .actions a.primary {
86
+ border-color: var(--primary);
87
+ background: var(--primary);
88
+ color: #fff;
89
+ }
90
+
91
+ .actions a:hover {
92
+ transform: translateY(-1px);
93
+ }
94
+
95
+ main {
96
+ display: flex;
97
+ min-height: calc(100vh - 64px);
98
+ }
99
+
100
+ nav {
101
+ width: var(--sidebar-width);
102
+ flex-shrink: 0;
103
+ border-right: 1px solid var(--border);
104
+ background: var(--surface);
105
+ padding: 16px 0;
106
+ position: sticky;
107
+ top: 64px;
108
+ max-height: calc(100vh - 64px);
109
+ overflow-y: auto;
110
+ }
111
+
112
+ nav .title {
113
+ font-size: 11px;
114
+ text-transform: uppercase;
115
+ letter-spacing: 0.06em;
116
+ color: var(--muted);
117
+ padding: 0 16px 8px;
118
+ font-weight: 700;
119
+ }
120
+
121
+ nav a {
122
+ display: block;
123
+ text-decoration: none;
124
+ color: #1e293b;
125
+ font-size: 14px;
126
+ padding: 9px 16px;
127
+ border-left: 3px solid transparent;
128
+ transition: all 0.15s;
129
+ }
130
+
131
+ nav a:hover {
132
+ background: #f8fafc;
133
+ border-left-color: var(--primary);
134
+ color: var(--primary);
135
+ }
136
+
137
+ section.content {
138
+ width: 100%;
139
+ padding: 24px;
140
+ }
141
+
142
+ .doc-shell {
143
+ max-width: 980px;
144
+ background: var(--surface);
145
+ border: 1px solid var(--border);
146
+ border-radius: 14px;
147
+ padding: 24px 26px;
148
+ margin: 0 auto;
149
+ box-shadow: 0 8px 24px rgba(15, 23, 42, 0.06);
150
+ }
151
+
152
+ .notice {
153
+ margin-bottom: 18px;
154
+ border: 1px solid #bfdbfe;
155
+ background: linear-gradient(120deg, #eff6ff 0%, #f8fbff 100%);
156
+ border-radius: 10px;
157
+ padding: 12px 14px;
158
+ color: #1e3a8a;
159
+ font-size: 13px;
160
+ }
161
+
162
+ .markdown-body h1,
163
+ .markdown-body h2,
164
+ .markdown-body h3,
165
+ .markdown-body h4 {
166
+ line-height: 1.35;
167
+ color: #0b1220;
168
+ }
169
+
170
+ .markdown-body h1 {
171
+ margin-top: 0;
172
+ font-size: 34px;
173
+ margin-bottom: 18px;
174
+ }
175
+
176
+ .markdown-body h2 {
177
+ margin-top: 30px;
178
+ font-size: 24px;
179
+ padding-bottom: 6px;
180
+ border-bottom: 1px solid #e5e7eb;
181
+ }
182
+
183
+ .markdown-body h3 {
184
+ margin-top: 26px;
185
+ font-size: 19px;
186
+ }
187
+
188
+ .markdown-body h4 {
189
+ margin-top: 18px;
190
+ font-size: 16px;
191
+ }
192
+
193
+ .markdown-body p,
194
+ .markdown-body li {
195
+ color: #253043;
196
+ font-size: 15px;
197
+ }
198
+
199
+ .markdown-body table {
200
+ border-collapse: collapse;
201
+ width: 100%;
202
+ margin: 14px 0;
203
+ font-size: 14px;
204
+ }
205
+
206
+ .markdown-body th,
207
+ .markdown-body td {
208
+ border: 1px solid #dfe3ea;
209
+ padding: 9px 10px;
210
+ text-align: left;
211
+ vertical-align: top;
212
+ }
213
+
214
+ .markdown-body th {
215
+ background: #f8fafc;
216
+ color: #0f172a;
217
+ }
218
+
219
+ .markdown-body code {
220
+ background: var(--primary-soft);
221
+ color: #0b3aa7;
222
+ border-radius: 6px;
223
+ font-size: 0.9em;
224
+ padding: 0.15em 0.45em;
225
+ }
226
+
227
+ .markdown-body pre {
228
+ border-radius: 10px;
229
+ overflow: auto;
230
+ margin: 14px 0;
231
+ border: 1px solid #1f2937;
232
+ box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.04);
233
+ }
234
+
235
+ .markdown-body pre code {
236
+ background: transparent;
237
+ color: inherit;
238
+ padding: 0;
239
+ }
240
+
241
+ .markdown-body blockquote {
242
+ margin: 14px 0;
243
+ border-left: 4px solid #93c5fd;
244
+ padding: 6px 14px;
245
+ color: #1e3a8a;
246
+ background: #eff6ff;
247
+ border-radius: 8px;
248
+ }
249
+
250
+ footer {
251
+ color: #64748b;
252
+ font-size: 12px;
253
+ margin-top: 26px;
254
+ }
255
+
256
+ @media (max-width: 960px) {
257
+ nav {
258
+ display: none;
259
+ }
260
+
261
+ section.content {
262
+ padding: 14px;
263
+ }
264
+
265
+ .doc-shell {
266
+ padding: 16px;
267
+ }
268
+
269
+ .markdown-body h1 {
270
+ font-size: 28px;
271
+ }
272
+
273
+ .markdown-body h2 {
274
+ font-size: 21px;
275
+ }
276
+ }
277
+ </style>
410
278
  </head>
411
279
  <body>
412
- <header>
413
- <div class="header-content">
414
- <div class="brand">
415
- <div class="brand-icon">
416
- <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
417
- <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z"/>
418
- </svg>
419
- </div>
420
- <div class="brand-text">
421
- <h1>Axhub Genie</h1>
422
- <div class="subtitle">API Documentation</div>
423
- </div>
424
- </div>
425
- <a href="/" class="back-link">
426
- <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
427
- <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 19l-7-7m0 0l7-7m-7 7h18"/>
428
- </svg>
429
- Back to App
430
- </a>
280
+ <header>
281
+ <div class="brand">
282
+ <strong>Axhub Genie Open API</strong>
283
+ <small>Single Source: <code>docs/open-api-mvp.zh-CN.md</code></small>
284
+ </div>
285
+ <div class="actions">
286
+ <a href="/" class="primary">Back To App</a>
287
+ </div>
288
+ </header>
289
+
290
+ <main>
291
+ <nav>
292
+ <div class="title">Sections</div>
293
+ <a href="#overview">Overview</a>
294
+ <a href="#authentication">Authentication</a>
295
+ <a href="#agent">Agent API</a>
296
+ <a href="#frontend-integration">Frontend Integration</a>
297
+ <a href="#usage-examples">Usage Examples</a>
298
+ <a href="#faq">FAQ</a>
299
+ </nav>
300
+ <section class="content">
301
+ <div class="doc-shell">
302
+ <div class="notice">
303
+ This page is auto-generated. Do not edit <code>public/api-docs.html</code> directly.
431
304
  </div>
432
- </header>
433
-
434
- <div class="main-layout">
435
- <nav class="sidebar">
436
- <div class="sidebar-title">Getting Started</div>
437
- <a href="#authentication">Authentication</a>
438
- <a href="#credentials">GitHub Credentials</a>
439
-
440
- <div class="sidebar-title">API Reference</div>
441
- <a href="#agent">Agent</a>
442
-
443
- <div class="sidebar-title">Examples</div>
444
- <a href="#usage-examples">Usage Patterns</a>
445
- </nav>
446
-
447
- <div class="content-wrapper">
448
- <!-- Intro Section -->
449
- <div class="section-row">
450
- <div class="docs-section">
451
- <div class="intro">
452
- <p><strong>Programmatically trigger AI agents to work on projects.</strong> Clone GitHub repositories or use existing project paths. Perfect for CI/CD pipelines, automated code reviews, and bulk processing.</p>
453
- </div>
454
-
455
- <section id="authentication">
456
- <h2>Authentication</h2>
457
- <p><strong>MVP default:</strong> <code>/api/agent</code> allows local requests without API key.</p>
458
- <p>You can still send <code>X-API-Key</code>; if present it will be validated.</p>
459
- <p>To force API key authentication, set <code>AGENT_API_KEY_REQUIRED=true</code>.</p>
460
-
461
- <p>Generate API keys in Settings → API & Tokens.</p>
462
- </section>
463
-
464
- <section id="credentials">
465
- <h3>GitHub Credentials</h3>
466
- <p>For private repositories, store a GitHub token in settings or pass it with each request.</p>
467
-
468
- <div class="note">
469
- <strong>Note:</strong> GitHub tokens in the request override stored tokens.
470
- </div>
471
- </section>
472
- </div>
473
-
474
- <div class="examples-section">
475
- <div class="example-block">
476
- <h4>MVP Local Request</h4>
477
- <pre><code class="language-http">(No authentication header required)</code></pre>
478
- </div>
479
-
480
- <div class="example-block">
481
- <h4>Optional Authentication Header</h4>
482
- <pre><code class="language-http">X-API-Key: ck_your_api_key_here</code></pre>
483
- </div>
484
- </div>
485
- </div>
486
-
487
- <!-- Agent API Section -->
488
- <div class="section-row">
489
- <div class="docs-section">
490
- <section id="agent">
491
- <h2>Agent</h2>
492
-
493
- <div class="endpoint">
494
- <div class="endpoint-header">
495
- <span class="method method-post">POST</span>
496
- <span class="endpoint-path"><span class="api-url">http://localhost:32123</span>/api/agent</span>
497
- </div>
498
-
499
- <p>Trigger an AI agent (Claude, Cursor, or Codex) to work on a project.</p>
500
-
501
- <h4>Request Body Parameters</h4>
502
- <table>
503
- <thead>
504
- <tr>
505
- <th>Parameter</th>
506
- <th>Type</th>
507
- <th>Required</th>
508
- <th>Description</th>
509
- </tr>
510
- </thead>
511
- <tbody>
512
- <tr>
513
- <td><code>githubUrl</code></td>
514
- <td>string</td>
515
- <td><span class="badge badge-optional">Conditional</span></td>
516
- <td>GitHub repository URL to clone. If path exists with same repo, reuses it. If path exists with different repo, returns error.</td>
517
- </tr>
518
- <tr>
519
- <td><code>projectPath</code></td>
520
- <td>string</td>
521
- <td><span class="badge badge-optional">Conditional</span></td>
522
- <td>Path to existing project OR destination for cloning. If omitted with <code>githubUrl</code>, auto-generates path. If used alone, must point to existing project directory.</td>
523
- </tr>
524
- <tr>
525
- <td><code>message</code></td>
526
- <td>string</td>
527
- <td><span class="badge badge-required">Required</span></td>
528
- <td>Task for the AI agent</td>
529
- </tr>
530
- <tr>
531
- <td><code>sessionId</code></td>
532
- <td>string</td>
533
- <td><span class="badge badge-optional">Optional</span></td>
534
- <td>Resume an existing conversation session. If omitted, a new session is created.</td>
535
- </tr>
536
- <tr>
537
- <td><code>openOnly</code></td>
538
- <td>boolean</td>
539
- <td><span class="badge badge-optional">Optional</span></td>
540
- <td>Open session link only without triggering model execution. Requires <code>sessionId</code>.</td>
541
- </tr>
542
- <tr>
543
- <td><code>provider</code></td>
544
- <td>string</td>
545
- <td><span class="badge badge-optional">Optional</span></td>
546
- <td><code>claude</code>, <code>cursor</code>, or <code>codex</code> (default: <code>claude</code>)</td>
547
- </tr>
548
- <tr>
549
- <td><code>stream</code></td>
550
- <td>boolean</td>
551
- <td><span class="badge badge-optional">Optional</span></td>
552
- <td>Enable streaming (default: <code>true</code>)</td>
553
- </tr>
554
- <tr>
555
- <td><code>model</code></td>
556
- <td>string</td>
557
- <td><span class="badge badge-optional">Optional</span></td>
558
- <td id="model-options-cell">
559
- Model identifier for the AI provider (loading from constants...)
560
- </td>
561
- </tr>
562
- <tr>
563
- <td><code>cleanup</code></td>
564
- <td>boolean</td>
565
- <td><span class="badge badge-optional">Optional</span></td>
566
- <td>Auto-cleanup after completion (default: <code>true</code>). Only applies when cloning via <code>githubUrl</code>. Existing projects specified via <code>projectPath</code> are never cleaned up.</td>
567
- </tr>
568
- <tr>
569
- <td><code>githubToken</code></td>
570
- <td>string</td>
571
- <td><span class="badge badge-optional">Optional</span></td>
572
- <td>GitHub token for private repos</td>
573
- </tr>
574
- <tr>
575
- <td><code>branchName</code></td>
576
- <td>string</td>
577
- <td><span class="badge badge-optional">Optional</span></td>
578
- <td>Custom branch name to use. If provided, <code>createBranch</code> is automatically enabled. Branch names are validated against Git naming rules. Works with <code>githubUrl</code> or <code>projectPath</code> (if it has a GitHub remote).</td>
579
- </tr>
580
- <tr>
581
- <td><code>createBranch</code></td>
582
- <td>boolean</td>
583
- <td><span class="badge badge-optional">Optional</span></td>
584
- <td>Create a new branch after successful completion (default: <code>false</code>). Automatically set to <code>true</code> if <code>branchName</code> is provided. Works with <code>githubUrl</code> or <code>projectPath</code> (if it has a GitHub remote).</td>
585
- </tr>
586
- <tr>
587
- <td><code>createPR</code></td>
588
- <td>boolean</td>
589
- <td><span class="badge badge-optional">Optional</span></td>
590
- <td>Create a pull request after successful completion (default: <code>false</code>). PR title and description auto-generated from commit messages. Works with <code>githubUrl</code> or <code>projectPath</code> (if it has a GitHub remote).</td>
591
- </tr>
592
- </tbody>
593
- </table>
594
-
595
- <div class="note">
596
- <strong>Path Handling Behavior:</strong><br><br>
597
- <strong>Scenario 1:</strong> Only <code>githubUrl</code> → Clones to auto-generated temporary path<br>
598
- <strong>Scenario 2:</strong> Only <code>projectPath</code> → Uses existing project at specified path<br>
599
- <strong>Scenario 3:</strong> Both provided → Clones <code>githubUrl</code> to <code>projectPath</code><br><br>
600
- <strong>Validation:</strong> If <code>projectPath</code> exists and contains a git repository, the remote URL is compared with <code>githubUrl</code>. If URLs match, the existing repo is reused. If URLs differ, an error is returned.
601
- </div>
602
-
603
- <h4>Response (Streaming)</h4>
604
- <p>Server-sent events (SSE) format with real-time updates. Content-Type: <code>text/event-stream</code></p>
605
-
606
- <h4>Response (Non-Streaming)</h4>
607
- <p>JSON object containing session details, assistant messages only (filtered), and token usage summary. Content-Type: <code>application/json</code></p>
608
-
609
- <h4>Error Response</h4>
610
- <p>Returns error details with appropriate HTTP status code.</p>
611
- </div>
612
- </section>
613
- </div>
614
-
615
- <div class="examples-section">
616
- <div class="example-block">
617
- <h4>Basic Request</h4>
618
- <div class="tab-buttons">
619
- <button class="tab-button active" onclick="showTab('curl-basic')">cURL</button>
620
- <button class="tab-button" onclick="showTab('js-basic')">JavaScript</button>
621
- <button class="tab-button" onclick="showTab('python-basic')">Python</button>
622
- </div>
623
-
624
- <div class="tab-content active" id="curl-basic">
625
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
626
- -H "Content-Type: application/json" \
627
- -d '{
628
- "githubUrl": "https://github.com/user/repo",
629
- "message": "Add error handling to main.js"
630
- }'</code></pre>
631
- </div>
632
-
633
- <div class="tab-content" id="js-basic">
634
- <pre><code class="language-javascript">const response = await fetch('<span class="api-url">http://localhost:32123</span>/api/agent', {
635
- method: 'POST',
636
- headers: {
637
- 'Content-Type': 'application/json'
638
- },
639
- body: JSON.stringify({
640
- githubUrl: 'https://github.com/user/repo',
641
- message: 'Add error handling',
642
- stream: false
643
- })
644
- });
645
-
646
- const result = await response.json();</code></pre>
647
- </div>
648
-
649
- <div class="tab-content" id="python-basic">
650
- <pre><code class="language-python">import requests
651
- import os
652
-
653
- response = requests.post(
654
- '<span class="api-url">http://localhost:32123</span>/api/agent',
655
- headers={
656
- 'Content-Type': 'application/json'
657
- },
658
- json={
659
- 'githubUrl': 'https://github.com/user/repo',
660
- 'message': 'Add error handling',
661
- 'stream': False
662
- }
663
- )
664
-
665
- print(response.json())</code></pre>
666
- </div>
667
- </div>
668
-
669
- <div class="example-block">
670
- <h4>Streaming Response</h4>
671
- <pre><code class="language-javascript">data: {"type":"status","message":"Repository cloned"}
672
- data: {"type":"thinking","content":"Analyzing..."}
673
- data: {"type":"tool_use","tool":"read_file"}
674
- data: {"type":"content","content":"Done!"}
675
- data: {"type":"done"}</code></pre>
676
- </div>
677
-
678
- <div class="example-block">
679
- <h4>Non-Streaming Response</h4>
680
- <pre><code class="language-json">{
681
- "success": true,
682
- "sessionId": "abc123",
683
- "sessionPath": "/session/abc123",
684
- "sessionUrl": "http://localhost:5173/session/abc123",
685
- "isResumed": false,
686
- "messages": [
687
- {
688
- "type": "assistant",
689
- "message": {
690
- "role": "assistant",
691
- "content": [
692
- {
693
- "type": "text",
694
- "text": "I've completed the task..."
695
- }
696
- ],
697
- "usage": {
698
- "input_tokens": 150,
699
- "output_tokens": 50
700
- }
305
+ <article id="markdown-root" class="markdown-body"></article>
306
+ <footer>Generated at: 2026-02-12T09:22:33.366Z</footer>
307
+ </div>
308
+ </section>
309
+ </main>
310
+
311
+ <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
312
+ <script>
313
+ const markdownSource = "# 开放接口使用文档（MVP）\n\n> 单一事实源（Single Source of Truth）文件：`docs/open-api-mvp.zh-CN.md` \n> 页面入口：`/api-docs.html`（由脚本自动生成，请勿手改 HTML）\n\n<a id=\"overview\"></a>\n\n> 适用场景：外部系统（本地 Web / 本地服务）与 Assistant UI 本地服务通信，实现**创建会话、进入指定会话、续聊指定会话**。\n\n## Quick English Summary\n\n- Backend endpoints: `GET /health`, `POST /api/agent`\n- Frontend integration: URL query params + iframe `postMessage` (`update_context`, `update_prompt`)\n- Auth default: local anonymous is allowed for `/api/agent`; `X-API-Key` is optional unless `AGENT_API_KEY_REQUIRED=true`\n\n## 1. 基本信息\n\n- Assistant 前端地址（示例）：`http://localhost:5173`\n- Assistant 后端地址（示例）：`http://localhost:32123`\n- 会话页面路由格式：`/session/{sessionId}`\n- 健康检查：`GET /health`\n\n### 1.0 地址发现（先执行命令）\n\n在开发、测试、生产环境中，地址可能不同。请先在部署机器执行：\n\n```bash\naxhub-genie status\n```\n\n建议使用三项核心字段：\n\n- `endpoint.environment`\n- `endpoint.frontendUrl`\n- `endpoint.apiBaseUrl`\n\n说明：\n\n- 在不知道 API 地址时，不需要先调用任何 HTTP 接口；直接用 `axhub-genie status` 获取。\n- 后续所有文档中的 `http://localhost:32123`，都可以替换为 `endpoint.apiBaseUrl` 对应主机地址。\n- 文中示例的 `<CURRENT_API_BASE>` 指 `endpoint.apiBaseUrl`（例如 `http://localhost:32123/api`）。\n\n### 1.1 完整示例\n\n```bash\naxhub-genie status --json\n```\n\n完整返回示例：\n\n```json\n{\n \"running\": true,\n \"pid\": 12345,\n \"port\": 32123,\n \"startedAt\": \"2026-02-08T03:12:45.321Z\",\n \"statusFile\": \"/Users/you/.axhub-genie/runtime-status.json\",\n \"endpoint\": {\n \"environment\": \"development\",\n \"frontendUrl\": \"http://localhost:5173\",\n \"apiBaseUrl\": \"http://localhost:32123/api\"\n }\n}\n```\n\n### 1.0.1 健康检查与服务身份识别\n\n为了避免外部系统误把其他项目当成 Assistant 服务，建议在探活时同时校验 `service.id` 或响应头中的 `X-App-Identifier`。\n\n请求示例：\n\n```bash\ncurl -i http://localhost:32123/health\n```\n\n响应体示例：\n\n```json\n{\n \"status\": \"ok\",\n \"timestamp\": \"2026-02-09T12:00:00.000Z\",\n \"service\": {\n \"id\": \"@axhub/genie\",\n \"name\": \"Axhub Genie\",\n \"version\": \"1.16.3\"\n },\n \"runtime\": {\n \"environment\": \"development\",\n \"port\": 32123\n }\n}\n```\n\n关键响应头（可用于快速识别）：\n\n- `X-App-Identifier: @axhub/genie`\n- `X-App-Name: Axhub Genie`\n- `X-App-Version: 1.16.3`\n- `X-App-Environment: development`\n\n可选环境变量（用于自定义身份/环境标识）：\n\n- `APP_IDENTIFIER`（默认：`@axhub/genie`）\n- `APP_DISPLAY_NAME`（默认：`Axhub Genie`）\n- `APP_VERSION`（默认：读取 `package.json` 的 `version`）\n- `APP_RUNTIME_ENV`（默认：`APP_RUNTIME_ENV || NODE_ENV || development`）\n\n建议：\n\n- 探活成功条件 = HTTP `200` 且 `status=ok` 且 `service.id` 命中预期值。\n- 如果你的网关会剥离自定义 Header，优先校验响应体中的 `service.id`。\n\n### 1.1 前端 URL 参数（新增）\n\n你现在可以通过 `http://localhost:5173/` 的查询参数，预选项目和默认工具：\n\n| 参数 | 示例 | 说明 |\n|---|---|---|\n| `project` | `?project=my-project` | 按项目名/显示名/路径精确匹配项目 |\n| `projectName` | `?projectName=my-project` | `project` 的同义参数 |\n| `cwd` | `?cwd=/Users/you/my-project` | 按项目路径匹配（优先） |\n| `workdir` | `?workdir=/Users/you/my-project` | `cwd` 的同义参数 |\n| `provider` | `?provider=codex` | 预设默认工具（`claude`/`cursor`/`codex`/`gemini`/`opencode`） |\n| `tool` | `?tool=codex` | `provider` 的同义参数 |\n| `cli` | `?cli=codex` | `provider` 的同义参数 |\n| `context` | `?context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D` | 动态上下文（`contextV1` JSON，首次发送消息时自动附加，仅发送一次） |\n| `prompt` | `?prompt=%E8%AF%B7%E5%85%88%E5%88%86%E6%9E%90%E5%BD%93%E5%89%8D%E9%A1%B5` | 预填输入框内容（仅页面生命周期内首次 URL 生效，默认不自动发送） |\n\n示例：\n\n- `http://localhost:5173/?project=my-project&provider=codex`\n- `http://localhost:5173/?cwd=/Users/you/my-project&provider=cursor`\n- `http://localhost:5173/?project=my-project&provider=codex&context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D`\n- `http://localhost:5173/?project=my-project&provider=codex&prompt=%E8%AF%B7%E5%85%88%E6%A3%80%E6%9F%A5%E5%BD%93%E5%89%8D%E9%A1%B5%E9%9D%A2`\n\n`context` 采用固定 `contextV1` 结构（不兼容旧格式）：\n\n```json\n{\n \"version\": \"1\",\n \"systemContext\": \"租户:acme; 角色:analyst\",\n \"currentFile\": \"docs/open-api-mvp.zh-CN.md\",\n \"selectedElements\": [\n {\n \"tag\": \"iframe\",\n \"selector\": \"#preview-frame\",\n \"label\": \"预览区域\"\n }\n ],\n \"extensions\": {\n \"pageId\": \"dashboard\"\n }\n}\n```\n\n字段约束：\n\n- `version`：必填，固定值 `\"1\"`\n- `systemContext`：必填字符串，可为空字符串\n- `currentFile`：必填字符串，可为空字符串（仅路径）\n- `selectedElements`：必填数组，可为空；元素必须包含 `tag`、`selector`、`label` 字符串字段\n- `extensions`：可选对象，预留扩展\n\n兼容性说明：\n\n- URL 仅支持 `context` 参数，不再读取 `externalContext`、`iframeContext`\n\n## 1.1 前端 URL 可选参数\n\n你可以在前端链接上附带以下参数：\n\n- `cwd`：工作目录（本地项目路径）\n- `model`：默认选中模型（与 UI 模型下拉一致）\n\n示例：\n\n- `http://localhost:5173/?cwd=/Users/you/your-project&model=sonnet`\n- `http://localhost:5173/session/019c...c32e?cwd=/Users/you/your-project&model=gpt-5.2-codex`\n\n说明：\n\n- `cwd` 会尝试匹配已存在的项目并自动选中\n- `model` 会自动选中对应模型；若同名模型同时出现在多个 provider 中，会优先保持当前 provider\n\n### 1.2 iframe 场景：通过 `postMessage` 更新 context\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新 context。\n\n行为规则：\n\n- context 只会在**下一次用户发送消息**时自动附加一次。\n- 一旦附加发送过，会标记为“已发送”。\n- 任何新的 `postMessage` 更新都会将状态重置为“未发送”，并在下一次消息时重新附加。\n- `update_context` 新增可选 `mode`：默认 `replace`（覆盖），可选 `append`（追加，适合分多次选择元素）。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n type: 'update_context',\n mode: 'replace', // 可选：replace(默认) / append\n context: {\n version: '1',\n systemContext: '租户:acme; 角色:analyst',\n currentFile: 'docs/open-api-mvp.zh-CN.md',\n selectedElements: [\n {\n tag: 'div',\n selector: '#main-content > .toolbar',\n label: '顶部工具条'\n }\n ],\n extensions: {\n pageId: 'dashboard'\n }\n }\n}, '*');\n```\n\n追加模式示例（分多次追加选中元素）：\n\n```js\niframeEl.contentWindow.postMessage({\n type: 'update_context',\n mode: 'append',\n context: {\n selectedElements: [\n {\n tag: 'button',\n selector: '#save-btn',\n label: '保存按钮'\n }\n ]\n }\n}, '*');\n```\n\n协议约束（MVP v2）：\n\n- 仅支持 `type: update_context`\n- `mode` 可选：`replace`（默认）/ `append`\n- `mode=replace` 时：`context` 必须是对象，且满足 `contextV1` 结构\n- `mode=append` 时：`context` 允许按需传字段；`selectedElements` 会追加到现有上下文（建议按 `tag+selector+label` 去重）\n- `mode=append` 时：除 `selectedElements` 外，其它字段（如 `systemContext`/`currentFile`/`extensions`）若传入则按传入值更新；未传入字段保持原值\n- 不再兼容 `set_context`、`external_context_update`\n- 不再兼容 `payload`、`value`、`customContext`\n- 非法 `context` 会被忽略并输出 `console.warn`，不会阻断正常聊天发送\n\n### 1.3 iframe 场景：通过 `postMessage` 更新预填输入（prompt）\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新输入框预填内容。\n\n行为规则：\n\n- URL 参数 `prompt` 只在页面生命周期内首次生效（不会随 URL 后续变化重复覆盖）。\n- `postMessage` 的 `update_prompt` 会直接替换输入框内容。\n- 默认仅预填，不自动发送。\n- 当 `autoSend=true` 时，仅在“当前可发送”（已选项目且未在生成中）才立即发送；否则只预填，不排队重试。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n type: 'update_prompt',\n prompt: '请基于当前页面状态继续分析',\n autoSend: false\n}, '*');\n```\n\n自动发送示例：\n\n```js\niframeEl.contentWindow.postMessage({\n type: 'update_prompt',\n prompt: '请基于当前页面状态继续分析',\n autoSend: true\n}, '*');\n```\n\n完整消息 JSON 示例：\n\n```json\n{\n \"type\": \"update_prompt\",\n \"prompt\": \"请先总结当前页面上下文，再给出下一步建议\",\n \"autoSend\": true\n}\n```\n\n兼容类型：`update_prompt`、`set_prompt`、`external_prompt_update`\n\n兼容字段：`prompt`（推荐）、`payload`、`value`、`prefill`\n\n<a id=\"authentication\"></a>\n\n## 2. 鉴权策略（MVP）\n\n当前默认策略：\n\n- `POST /api/agent` **可本地匿名调用**（不传 `X-API-Key` 也可）\n- 如果传了 `X-API-Key`，会执行校验\n- 如需强制鉴权，设置环境变量：`AGENT_API_KEY_REQUIRED=true`\n\n<a id=\"agent\"></a>\n\n## 3. 核心开放接口\n\n### 3.1 创建或续聊会话\n\n`POST /api/agent`\n\n#### 请求体\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `projectPath` | string | 条件必填 | 本地项目路径（建议 MVP 直接使用此字段） |\n| `message` | string | 条件必填 | 本轮用户输入。`openOnly=true` 时可为空 |\n| `provider` | string | 否 | `claude` / `cursor` / `codex` / `gemini` / `opencode`，默认 `claude` |\n| `sessionId` | string | 否 | 传入则续聊指定会话，不传则创建新会话 |\n| `openOnly` | boolean | 否 | `true` 表示只返回会话跳转信息，不触发模型调用 |\n| `stream` | boolean | 否 | 是否流式，默认 `true`；集成场景建议 `false` |\n| `model` | string | 否 | 指定模型 |\n| `githubUrl` | string | 否 | 需要自动 clone 仓库时使用 |\n| `cleanup` | boolean | 否 | clone 场景完成后是否清理（默认 `true`） |\n| `githubToken` | string | 否 | GitHub Personal Access Token；请求内优先级高于设置页保存值 |\n| `branchName` | string | 否 | 自定义分支名；传入后会自动开启 `createBranch=true` |\n| `createBranch` | boolean | 否 | 任务完成后创建并推送 Git 分支（默认 `false`） |\n| `createPR` | boolean | 否 | 任务完成后创建 GitHub Pull Request（默认 `false`） |\n\n#### 关键校验规则\n\n- `openOnly=true` 或“`message` 为空且 `sessionId` 非空”时，会进入 only-open 模式。\n- only-open 模式下必须传 `sessionId`。\n- only-open 模式下不支持 `githubUrl` / `createBranch` / `createPR`。\n- `openOnly=true` 请求会忽略 `cleanup`，无需额外传 `cleanup=false`。\n\n#### 返回（`stream: false`）\n\n```json\n{\n \"success\": true,\n \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"isResumed\": false,\n \"messages\": [],\n \"tokens\": {\n \"inputTokens\": 0,\n \"outputTokens\": 0,\n \"cacheReadTokens\": 0,\n \"cacheCreationTokens\": 0,\n \"totalTokens\": 0\n },\n \"projectPath\": \"/Users/you/your-project\"\n}\n```\n\n字段说明：\n\n- `sessionId`：后续续聊和跳转的核心 ID\n- `sessionPath`：前端相对路径\n- `sessionUrl`：可直接打开的前端完整链接\n- `isResumed`：`true` 表示这次请求是续聊\n- `branch`：仅在 `createBranch=true` 时返回（成功返回分支信息，失败返回错误对象）\n- `pullRequest`：仅在 `createPR=true` 时返回（成功返回 PR 信息，失败返回错误对象）\n\n---\n\n### 3.2 进入指定会话（前端跳转）\n\nAssistant 当前已支持固定链接格式，无需新增接口：\n\n- `{FRONTEND_URL}/session/{sessionId}`（生产环境推荐配置 `FRONTEND_URL`）\n- 本地开发默认：`http://localhost:5173/session/{sessionId}`\n\n因此，外部系统调用 `POST /api/agent` 后，拿到 `sessionUrl` 直接打开即可。\n\n### 3.3 只打开会话（不发送消息）\n\n如果你只想“进入某个会话页面”，不想触发模型，可以调用：\n\n- `POST /api/agent`\n- 传 `openOnly: true`\n- `message` 可为空\n- 必须传 `sessionId`\n\n请求示例：\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"openOnly\": true,\n \"stream\": false\n }'\n```\n\n返回示例：\n\n```json\n{\n \"success\": true,\n \"openOnly\": true,\n \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"isResumed\": true,\n \"message\": \"Session link generated. No model call triggered.\"\n}\n```\n\n## 4. 对接流程（推荐）\n\n### 流程 A：创建新会话并打开\n\n1. 外部系统调用 `POST /api/agent`（不传 `sessionId`，且带 `message`）\n2. 保存返回的 `sessionId`\n3. 打开返回的 `sessionUrl`\n\n### 流程 B：进入并续聊已有会话\n\n1. 外部系统根据业务会话键找到已保存的 `sessionId`\n2. 调用 `POST /api/agent` 且传 `openOnly=true`（或直接拼接 URL）\n3. 如需服务端触发续聊，再调用 `POST /api/agent` 并传 `sessionId`\n\n<a id=\"usage-examples\"></a>\n\n## 5. cURL 示例\n\n### 5.1 创建新会话（MVP 无鉴权）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"projectPath\": \"/Users/you/your-project\",\n \"provider\": \"claude\",\n \"message\": \"请先梳理当前项目结构并给出重构计划\",\n \"stream\": false\n }'\n```\n\n### 5.2 续聊指定会话\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"projectPath\": \"/Users/you/your-project\",\n \"provider\": \"claude\",\n \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"message\": \"继续上一轮，把第 1、2 点先落代码\",\n \"stream\": false\n }'\n```\n\n### 5.3 只打开会话（不输入）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n \"openOnly\": true,\n \"stream\": false\n }'\n```\n\n### 5.4 可选：携带 API Key\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: ck_xxx\" \\\n -d '{\n \"projectPath\": \"/Users/you/your-project\",\n \"message\": \"继续处理\"\n }'\n```\n\n### 5.5 自动创建分支并发起 PR\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: ck_xxx\" \\\n -d '{\n \"githubUrl\": \"https://github.com/user/repo\",\n \"message\": \"修复鉴权逻辑并补充测试\",\n \"createBranch\": true,\n \"createPR\": true,\n \"stream\": false\n }'\n```\n\n### 5.6 指定自定义分支名\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"projectPath\": \"/Users/you/your-project\",\n \"message\": \"新增 API 网关重试策略\",\n \"branchName\": \"feature/api-retry-strategy\",\n \"createPR\": true,\n \"stream\": false\n }'\n```\n\n## 6. 外部系统会话映射建议\n\n建议在外部系统保存映射：\n\n- `external_conversation_key -> sessionId`\n\n这样可保证：\n\n- 可重入（同一业务会话可重复进入）\n- 可续聊（服务端调用时带 `sessionId`）\n- 可跳转（拼接前端链接）\n\n<a id=\"frontend-integration\"></a>\n\n## 7. 动态上下文注入规范（MVP v2）\n\n当前前端会在“下一次用户发送消息”时自动附加一次动态上下文，注入格式如下：\n\n```text\n[DYNAMIC CONTEXT V1]\n{ ...contextV1 json... }\n\n[USER MESSAGE]\n...用户输入...\n```\n\n行为规则：\n\n1. `context` 仅附加一次；发送后标记为已发送。\n2. 收到新的 URL `context` 或新的 `postMessage(update_context)` 后，重置为未发送。\n3. `postMessage(update_context)` 默认 `mode=replace`（覆盖当前待发送上下文）。\n4. 当 `mode=append` 时：`selectedElements` 采用追加策略（建议按 `tag+selector+label` 去重），便于分批选元素。\n5. 当 `mode=append` 时：未传入字段保持原值；已传入字段更新为最新值。\n6. 输入区会展示上下文标签（系统上下文 / 当前文件 / 选中元素）。\n7. 用户可手动取消某个标签；取消仅影响当前待发送上下文。\n8. 如果用户取消后上下文为空，则本次不附加动态上下文块。\n\n非法输入处理：\n\n- `context` 非法 JSON（URL）或字段校验失败：忽略该上下文并 `console.warn`\n- 不会阻止用户继续发送消息\n\n<a id=\"faq\"></a>\n\n## 8. 常见问题\n\n### Q1：只想“打开会话页面”，不想触发模型怎么办？\n\n两种方式都可以：\n\n1. 直接跳转：`/session/{sessionId}`\n2. 调用 `POST /api/agent` 并传 `openOnly=true`\n\n### Q2：`sessionId` 传了但会话不存在会怎样？\n\n不同 provider 的底层行为可能不同（可能报错或新建）。建议外部系统以“本地已保存映射”为准，避免传错 ID。\n\n### Q3：如何从当前地址拿到 sessionId？\n\n例如你的地址：\n\n- `http://localhost:5173/session/019c3263-967f-7ba2-84fe-fc5c694f6316`\n\n其中 `019c3263-967f-7ba2-84fe-fc5c694f6316` 就是 `sessionId`。\n\n## 9. 版本说明\n\n- 文档版本：MVP v1.1\n- 更新日期：2026-02-12\n- 文档来源：`docs/open-api-mvp.zh-CN.md`（`/api-docs.html` 由脚本生成）\n- 对应能力：`/api/agent` 支持 `sessionId` 续聊、`openOnly` 仅打开、`gemini/opencode` provider、可选 `createBranch/createPR`\n";
314
+ const root = document.getElementById('markdown-root');
315
+
316
+ function scrollToHashAnchor() {
317
+ const hash = window.location.hash ? window.location.hash.slice(1) : '';
318
+ if (!hash) {
319
+ return;
701
320
  }
702
- }
703
- ],
704
- "tokens": {
705
- "inputTokens": 150,
706
- "outputTokens": 50,
707
- "cacheReadTokens": 0,
708
- "cacheCreationTokens": 0,
709
- "totalTokens": 200
710
- },
711
- "projectPath": "/path/to/project",
712
- "branch": {
713
- "name": "fix-authentication-bug-abc123",
714
- "url": "https://github.com/user/repo/tree/fix-authentication-bug-abc123"
715
- },
716
- "pullRequest": {
717
- "number": 42,
718
- "url": "https://github.com/user/repo/pull/42"
719
- }
720
- }</code></pre>
721
- </div>
722
-
723
- <div class="example-block">
724
- <h4>Resume Existing Session</h4>
725
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
726
- -H "Content-Type: application/json" \
727
- -d '{
728
- "projectPath": "/Users/you/your-project",
729
- "provider": "claude",
730
- "sessionId": "019c3263-967f-7ba2-84fe-fc5c694f6316",
731
- "message": "继续上一轮，按新需求重构这个模块",
732
- "stream": false
733
- }'</code></pre>
734
- </div>
735
-
736
- <div class="example-block">
737
- <h4>Open Session Only (No Message)</h4>
738
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
739
- -H "Content-Type: application/json" \
740
- -d '{
741
- "sessionId": "019c3263-967f-7ba2-84fe-fc5c694f6316",
742
- "openOnly": true,
743
- "stream": false
744
- }'</code></pre>
745
- </div>
746
-
747
- <div class="example-block">
748
- <h4>Error Response</h4>
749
- <pre><code class="language-json">{
750
- "success": false,
751
- "error": "Directory exists with different repo"
752
- }</code></pre>
753
- </div>
754
- </div>
755
- </div>
756
-
757
- <!-- Usage Patterns Section -->
758
- <div class="section-row">
759
- <div class="docs-section">
760
- <section id="usage-examples">
761
- <h2>Usage Patterns</h2>
762
-
763
- <h3>Clone and Process Repository</h3>
764
- <p>Clone a repository to an auto-generated temporary path and process it.</p>
765
-
766
- <h3>Use Existing Project</h3>
767
- <p>Work with an existing project at a specific path.</p>
768
-
769
- <h3>Clone to Specific Path</h3>
770
- <p>Clone a repository to a custom location for later reuse.</p>
771
-
772
- <h3>CI/CD Integration</h3>
773
- <p>Integrate with GitHub Actions or other CI/CD pipelines.</p>
774
-
775
- <h3>Create Branch and Pull Request</h3>
776
- <p>Automatically create a new branch and pull request after the agent completes its work. Branch names are auto-generated from the message, and PR title/description are auto-generated from commit messages.</p>
777
- </section>
778
- </div>
779
-
780
- <div class="examples-section">
781
- <div class="example-block">
782
- <h4>Use Existing Project</h4>
783
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
784
- -H "Content-Type: application/json" \
785
- -H "X-API-Key: ck_..." \
786
- -d '{
787
- "projectPath": "/home/user/my-project",
788
- "message": "Refactor database queries"
789
- }'</code></pre>
790
- </div>
791
-
792
- <div class="example-block">
793
- <h4>Clone to Custom Path</h4>
794
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
795
- -H "Content-Type: application/json" \
796
- -H "X-API-Key: ck_..." \
797
- -d '{
798
- "githubUrl": "https://github.com/user/repo",
799
- "projectPath": "/tmp/my-location",
800
- "message": "Review security",
801
- "cleanup": false
802
- }'</code></pre>
803
- </div>
804
-
805
- <div class="example-block">
806
- <h4>CI/CD (GitHub Actions)</h4>
807
- <pre><code class="language-yaml">- name: Trigger Agent
808
- run: |
809
- curl -X POST ${{ secrets.API_URL }}/api/agent \
810
- -H "X-API-Key: ${{ secrets.API_KEY }}" \
811
- -H "Content-Type: application/json" \
812
- -d '{
813
- "githubUrl": "${{ github.repository }}",
814
- "message": "Review for security",
815
- "githubToken": "${{ secrets.GITHUB_TOKEN }}"
816
- }'</code></pre>
817
- </div>
818
-
819
- <div class="example-block">
820
- <h4>Create Branch and PR</h4>
821
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
822
- -H "Content-Type: application/json" \
823
- -H "X-API-Key: ck_..." \
824
- -d '{
825
- "githubUrl": "https://github.com/user/repo",
826
- "message": "Fix authentication bug",
827
- "createBranch": true,
828
- "createPR": true,
829
- "stream": false
830
- }'</code></pre>
831
- </div>
832
-
833
- <div class="example-block">
834
- <h4>Custom Branch Name</h4>
835
- <pre><code class="language-bash">curl -X POST <span class="api-url">http://localhost:32123</span>/api/agent \
836
- -H "Content-Type: application/json" \
837
- -H "X-API-Key: ck_..." \
838
- -d '{
839
- "githubUrl": "https://github.com/user/repo",
840
- "message": "Add user authentication",
841
- "branchName": "feature/user-auth",
842
- "createPR": true,
843
- "stream": false
844
- }'</code></pre>
845
- </div>
846
-
847
- <div class="example-block">
848
- <h4>Branch & PR Response</h4>
849
- <pre><code class="language-json">{
850
- "success": true,
851
- "branch": {
852
- "name": "feature/user-auth",
853
- "url": "https://github.com/user/repo/tree/feature/user-auth"
854
- },
855
- "pullRequest": {
856
- "number": 42,
857
- "url": "https://github.com/user/repo/pull/42"
858
- }
859
- }</code></pre>
860
- </div>
861
- </div>
862
- </div>
863
- </div>
864
- </div>
865
321
 
866
- <script type="module">
867
- // Import model constants
868
- import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '/shared/modelConstants.js';
322
+ const target = document.getElementById(hash);
323
+ if (target) {
324
+ target.scrollIntoView({ block: 'start', behavior: 'auto' });
325
+ }
326
+ }
869
327
 
870
- // Dynamic URL replacement
871
- const apiUrl = window.location.origin;
872
- document.querySelectorAll('.api-url').forEach(el => {
873
- el.textContent = apiUrl;
874
- });
328
+ function renderFallback() {
329
+ root.innerHTML = '';
330
+ const pre = document.createElement('pre');
331
+ pre.textContent = markdownSource;
332
+ root.appendChild(pre);
333
+ }
875
334
 
876
- // Dynamically populate model documentation
877
- window.addEventListener('DOMContentLoaded', () => {
878
- const modelCell = document.getElementById('model-options-cell');
879
- if (modelCell) {
880
- const claudeModels = CLAUDE_MODELS.OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
881
- const cursorModels = CURSOR_MODELS.OPTIONS.slice(0, 8).map(m => `<code>${m.value}</code>`).join(', ');
882
- const codexModels = CODEX_MODELS.OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
883
-
884
- modelCell.innerHTML = `
885
- Model identifier for the AI provider:<br><br>
886
- <strong>Claude:</strong> ${claudeModels} (default: <code>${CLAUDE_MODELS.DEFAULT}</code>)<br><br>
887
- <strong>Cursor:</strong> ${cursorModels}, and more (default: <code>${CURSOR_MODELS.DEFAULT}</code>)<br><br>
888
- <strong>Codex:</strong> ${codexModels} (default: <code>${CODEX_MODELS.DEFAULT}</code>)
889
- `;
890
- }
335
+ try {
336
+ if (!window.marked) {
337
+ renderFallback();
338
+ } else {
339
+ marked.setOptions({
340
+ gfm: true,
341
+ breaks: false,
342
+ headerIds: true,
343
+ mangle: false
891
344
  });
345
+ root.innerHTML = marked.parse(markdownSource);
346
+ }
347
+ } catch (error) {
348
+ console.error('Failed to render markdown docs:', error);
349
+ renderFallback();
350
+ }
892
351
 
893
- // Tab switching
894
- window.showTab = function(tabName) {
895
- const parentBlock = event.target.closest('.example-block');
896
- if (!parentBlock) return;
897
-
898
- parentBlock.querySelectorAll('.tab-content').forEach(tab => {
899
- tab.classList.remove('active');
900
- });
901
- parentBlock.querySelectorAll('.tab-button').forEach(btn => {
902
- btn.classList.remove('active');
903
- });
904
-
905
- const targetTab = parentBlock.querySelector('#' + tabName);
906
- if (targetTab) {
907
- targetTab.classList.add('active');
908
- event.target.classList.add('active');
909
- }
910
- };
911
- </script>
912
-
913
- <!-- Prism.js -->
914
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
915
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
916
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
917
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js"></script>
918
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-json.min.js"></script>
919
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-yaml.min.js"></script>
920
- <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-http.min.js"></script>
352
+ if (window.Prism) {
353
+ Prism.highlightAll();
354
+ }
355
+ requestAnimationFrame(scrollToHashAnchor);
356
+ window.addEventListener('hashchange', scrollToHashAnchor);
357
+ </script>
358
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
359
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
360
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
361
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-json.min.js"></script>
362
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-http.min.js"></script>
921
363
  </body>
922
364
  </html>