File size: 32,295 Bytes
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
5ca3c16
 
 
 
 
8f4045a
 
5ca3c16
115b94d
 
 
 
 
 
 
 
 
 
8f4045a
5ca3c16
 
 
 
8f4045a
 
 
 
115b94d
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
 
 
 
 
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
 
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
 
 
 
 
5ca3c16
8f4045a
 
115b94d
 
 
 
 
 
 
 
 
 
 
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
8f4045a
 
 
 
 
 
115b94d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8f4045a
5ca3c16
 
 
 
115b94d
5ca3c16
 
 
 
 
115b94d
 
 
 
 
 
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
115b94d
 
 
 
 
 
 
 
5ca3c16
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
"""Loopback UI/API with persistent identity, CSRF and project-scoped operations."""
import hmac
import hashlib
import re
import asyncio
import time
from typing import Literal
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request, Depends
from fastapi.exceptions import RequestValidationError
from fastapi.responses import FileResponse, JSONResponse, Response, RedirectResponse, HTMLResponse
from pydantic import BaseModel, ConfigDict, Field
from starlette.middleware.trustedhost import TrustedHostMiddleware
from src.modules.skill.domain.models import SkillError
from src.apps.workbench.engine import SCENARIOS


class Input(BaseModel):
    model_config=ConfigDict(extra='forbid',strict=True)
class Login(Input):
    username:str=Field(min_length=3,max_length=40)
    password:str=Field(min_length=1,max_length=128)
class User(Login):
    roles:list[str]=Field(default_factory=lambda:['developer'],max_length=3)
class Member(Input):
    project_id:str=Field(max_length=80)
    user_id:str=Field(max_length=80)
    enabled:bool
class Job(Input):
    scenario:str=Field(max_length=40)
    requirement:str=Field(min_length=2,max_length=6000)
    request_key:str=Field(min_length=8,max_length=128)
    skill_id:str|None=Field(default=None,max_length=80)
    recovery_of:str|None=Field(default=None,max_length=80)
    auto_recover:bool=False
    acknowledge_new_cost:bool=False
    model:str|None=Field(default=None,max_length=80)
    workflow_revision:int|None=Field(default=None,ge=1)
    scope_id:str|None=Field(default=None,max_length=80)
class ScopePrepare(Input):
    requirement:str=Field(min_length=2,max_length=6000)
    request_key:str=Field(min_length=8,max_length=128)
    parent_id:str|None=Field(default=None,max_length=80)
    base_run:str|None=Field(default=None,max_length=80)
    supplement:str|None=Field(default=None,min_length=2,max_length=3000)
class ScopeConfirm(Input):
    digest:str=Field(pattern='^[a-f0-9]{64}$')
class Chat(Input):
    conversation:str=Field(min_length=1,max_length=80)
    prompt:str=Field(min_length=1,max_length=4000)
    request_key:str=Field(min_length=8,max_length=128)
    project:str|None=Field(default=None,max_length=80)
    model:str|None=Field(default=None,max_length=80)
class BudgetDecision(Input):
    digest:str=Field(pattern='^[a-f0-9]{64}$')
    accept:bool
    revision:int|None=Field(default=None,ge=1)
class Question(Input):
    question:str=Field(min_length=2,max_length=500)
class BusinessQuestion(Question):
    scenario:Literal['erp','wms','equipment']
class BusinessAction(Input):
    scenario:Literal['erp','wms','equipment']
    action:Literal['receive','issue','start','complete']
    entity_id:str=Field(min_length=1,max_length=80)
    parameters:dict=Field(default_factory=dict)
    expected_version:int=Field(ge=1,le=2147483647)
    request_key:str=Field(min_length=8,max_length=120)
class BusinessReset(Input):
    scenario:Literal['erp','wms','equipment']
    request_key:str=Field(min_length=8,max_length=120)
class Preview(Input):
    kind:str=Field(pattern='^(example|run|skill)$')
    reference:str=Field(max_length=100)
class PreviewRequest(Input):
    method:str=Field(pattern='^(GET|POST)$')
    path:str=Field(min_length=1,max_length=501)
    body:dict|None=None
    preview_id:str|None=Field(default=None,max_length=80)
class PreviewClient(Input):
    preview_id:str=Field(min_length=1,max_length=80)
    client_id:str=Field(pattern='^[a-f0-9]{32}$')
    event:Literal['attach','heartbeat','release']


def create_web(engine,port=8789,*,preview_port=None,workbench_port=None,preview_only=False,owns_engine=True):
    identity=engine.identity
    preview_origin=f'http://127.0.0.1:{port if preview_only else preview_port or port}'
    workbench_origin=f'http://127.0.0.1:{workbench_port or port}'
    if preview_port is not None and not preview_only: engine.preview_origin=preview_origin
    def csrf_for_origin(csrf):
        return hmac.new(csrf.encode(),('preview-origin:'+str(port)).encode(),hashlib.sha256).hexdigest() if preview_only else csrf
    @asynccontextmanager
    async def lifespan(app):
        yield
        if owns_engine:engine.shutdown()
    app=FastAPI(title='ZKCoding 本地工作台',docs_url=None,redoc_url=None,lifespan=lifespan)
    app.add_middleware(TrustedHostMiddleware,allowed_hosts=['127.0.0.1','localhost','testserver'])
    origins={f'http://127.0.0.1:{port}',f'http://localhost:{port}'}
    @app.middleware('http')
    async def boundary(request,call_next):
        if preview_only:
            path=request.url.path
            allowed=(path in {'/','/runtime.css','/health/live','/api/session','/api/preview','/api/preview/client','/api/preview/request','/api/preview/pdf-sample','/preview-generated/'}
                     or path.startswith(('/preview-launch/','/preview-site/','/draft-preview/','/api/export/')) or path=='/api/previews')
            if not allowed:return JSONResponse({'code':'PREVIEW_ROUTE_DENIED','message':'该端口只提供生成应用预览。'},status_code=404)
            if path=='/api/session' and request.method!='GET':return JSONResponse({'code':'PREVIEW_ROUTE_DENIED'},status_code=404)
            if path.startswith('/api/export/'):
                try:
                    actor,_,_=identity.session(request.cookies.get('zk_session',''))
                    if hasattr(engine,'preview_pool'):
                        kind,reference=path.removeprefix('/api/export/').split('/',1)
                        current=engine.preview_pool.find(actor,kind,reference)
                    else:current=engine.preview_state(actor)
                    if path!='/api/export/'+str(current.get('kind'))+'/'+str(current.get('reference')):
                        raise SkillError('PREVIEW_EXPORT_DENIED','仅能导出当前预览工程。',403)
                except SkillError as exc:return JSONResponse({'code':exc.code,'message':exc.message},status_code=exc.status)
        if any(h in request.headers for h in ('x-user-id','x-tenant-id','x-internal-authorization','authorization')):
            return JSONResponse({'code':'UNTRUSTED_IDENTITY_HEADER','message':'网站使用本地登录会话。'},status_code=400)
        if request.method not in {'GET','HEAD','OPTIONS'} and request.headers.get('origin') not in origins:
            return JSONResponse({'code':'ORIGIN_DENIED','message':'请求来源不符。'},status_code=403)
        raw=bytearray()
        async for chunk in request.stream():
            raw.extend(chunk)
            if len(raw)>(190000 if request.url.path=='/api/preview/request' else 32768): return JSONResponse({'code':'PAYLOAD_TOO_LARGE'},status_code=413)
        request._body=bytes(raw)
        response=await call_next(request)
        response.headers.update({'Cache-Control':'no-store','X-Content-Type-Options':'nosniff','Referrer-Policy':'no-referrer'})
        if 'Content-Security-Policy' not in response.headers:
            response.headers['Content-Security-Policy']="default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"
        return response
    @app.exception_handler(SkillError)
    async def failure(request,exc):
        body={'code':exc.code,'message':exc.message}
        if exc.code=='SCOPE_BUDGET_CHANGED' and exc.details.get('scope'):
            body['details']={'scope':exc.details['scope']}
        return JSONResponse(body,status_code=exc.status)
    @app.exception_handler(RequestValidationError)
    async def invalid(request,exc):
        return JSONResponse({'code':'INVALID_INPUT','message':'输入不符合接口契约。'},status_code=422)
    def principal(request:Request):
        actor,csrf,_=identity.session(request.cookies.get('zk_session',''))
        if request.method not in {'GET','HEAD'} and not hmac.compare_digest(request.headers.get('x-csrf-token',''),csrf_for_origin(csrf)):
            raise SkillError('CSRF_DENIED','请刷新页面后重试。',403)
        return actor
    if not preview_only and hasattr(engine,'skills'):
        from src.modules.skill.api.router import build_router
        app.include_router(build_router(engine.skills,principal))
        if hasattr(engine, 'runtimes') and engine.runtimes:
            from src.apps.workbench.workflow_read import build_router as workflow_read_router
            app.include_router(workflow_read_router(engine, principal))
            from src.apps.workbench.workflow_edit import build_router as workflow_edit_router
            app.include_router(workflow_edit_router(engine, principal))

    @app.get('/health/live')
    def health(): return {'status':'alive','scope':'loopback-local-demo','production_accepted':False}
    @app.get('/api/session')
    def session(request:Request):
        try:
            actor,csrf,name=identity.session(request.cookies.get('zk_session',''))
            if preview_only:return {'authenticated':True,'csrf':csrf_for_origin(csrf),'workbench_origin':workbench_origin,'preview_origin':preview_origin,'scope':'generated-app-preview'}
            return {'authenticated':True,'username':name,'actor':actor.model_dump(),'csrf':csrf,'projects':identity.projects(actor),
                    'preview_origin':preview_origin,'workbench_origin':workbench_origin,
                    'resource_limits':getattr(engine,'resource_limits',None),'budget_policy':getattr(engine,'budget_policy',None),
                    'capabilities':{} if getattr(engine,'resource_limits',None) else {'automatic_recovery':'bounded-continuation-v1'}}
        except SkillError:
            return {'authenticated':False,'needs_setup':identity.needs_setup()}
    def signed_in(data):
        token,csrf=identity.login(data.username,data.password)
        response=JSONResponse({'ok':True,'csrf':csrf})
        response.set_cookie('zk_session',token,httponly=True,samesite='strict',max_age=28800,path='/')
        return response
    @app.post('/api/session/setup')
    def setup(data:Login):
        identity.create_user(data.username,data.password,['admin'],setup=True)
        return signed_in(data)
    @app.post('/api/session/login')
    def login(data:Login): return signed_in(data)
    @app.post('/api/session/logout')
    def logout(request:Request,actor=Depends(principal)):
        identity.logout(request.cookies.get('zk_session',''))
        response=JSONResponse({'ok':True});response.delete_cookie('zk_session');return response
    @app.get('/api/scenarios')
    def scenarios(actor=Depends(principal)):
        projects={p['id'] for p in identity.projects(actor)}
        return [dict(id=k,name=v['name'],project_id=v['project'],requirement=v['requirement']) for k,v in SCENARIOS.items() if v['project'] in projects]
    @app.get('/api/models')
    def models(actor=Depends(principal)):
        return engine.runtimes['erp'].llm.routes()
    @app.get('/api/skill-library')
    def skill_library(actor=Depends(principal)):
        return {'items':engine.skill_library(actor)}
    @app.get('/api/jobs')
    def jobs(actor=Depends(principal)): return engine.jobs(actor)
    @app.post('/api/jobs',status_code=202)
    def submit(data:Job,actor=Depends(principal)):
        if data.scope_id:
            raise SkillError('SCOPE_ADMISSION_REMOVED','范围裁剪已撤回,请直接提交完整原需求。',409)
        return engine.submit(actor,data.scenario,data.requirement,data.request_key,data.skill_id,
                             **({'recovery_of':data.recovery_of} if data.recovery_of else {}),
                             **({'auto_recover':True} if data.auto_recover else {}),model=data.model,
                             **({'acknowledge_new_cost':True} if data.acknowledge_new_cost else {}),
                             **({'workflow_revision':data.workflow_revision} if data.workflow_revision else {}))
    @app.post('/api/business-scope')
    def prepare_scope(data:ScopePrepare,actor=Depends(principal)):
        raise SkillError('SCOPE_ADMISSION_REMOVED','范围裁剪已撤回,请直接提交完整原需求。',410)
    @app.get('/api/business-scope/{scope_id}')
    def read_scope(scope_id:str,actor=Depends(principal)):
        from src.apps.workbench.business_scope import BusinessScopes
        return BusinessScopes(engine).get(actor,scope_id)
    @app.post('/api/business-scope/{scope_id}/confirm')
    def confirm_scope(scope_id:str,data:ScopeConfirm,actor=Depends(principal)):
        raise SkillError('SCOPE_ADMISSION_REMOVED','旧范围卡仅保留记录,不再启动简化方案;请提交完整原需求。',410)
    @app.post('/api/chat',status_code=202)
    def chat(data:Chat,actor=Depends(principal)):
        return engine.conversations.submit(actor,data.conversation,data.prompt,data.request_key,data.project,model=data.model)
    @app.get('/api/chat/{key}')
    def chat_result(key:str,actor=Depends(principal)): return engine.conversations.get(actor,key)
    @app.get('/api/java-skills')
    def java_skills(actor=Depends(principal)): return engine.java_skills.list(actor)
    @app.post('/api/java-skills',status_code=201)
    def generate_skill(data:Preview,actor=Depends(principal)):
        body=engine.java_skills.create(actor,data.kind,data.reference)
        return {k:v for k,v in body.items() if k not in {'evidence','contract'}}
    @app.get('/api/java-skills/{key}/export')
    def export_skill(key:str,actor=Depends(principal)):
        return Response(engine.java_skills.export(actor,key),media_type='application/zip',headers={'Content-Disposition':'attachment; filename="java-skill.zip"'})
    @app.get('/api/jobs/{run_id}')
    def job(run_id:str,actor=Depends(principal)): return engine.job(actor,run_id)
    @app.post('/api/jobs/{run_id}/budget')
    def budget(run_id:str,data:BudgetDecision,actor=Depends(principal)):
        with engine.lock:
            row=engine.job(actor,run_id)
            duplicate=any(a['digest']==data.digest and a['approved']==data.accept for a in row['budget_authorizations'])
            if data.accept and not duplicate and engine.queue.full():raise SkillError('QUEUE_FULL','队列已满,预算尚未修改。',429)
            runtime=engine.runtimes[row['scenario']]
            try:updated=(runtime.decide_limit if row.get('limit_request') or row['status']=='waiting_limit' else runtime.decide_budget)(actor,run_id,data.digest,data.accept,data.revision)
            except SkillError:
                current=engine.store.get(run_id)
                if current['status'] in {'waiting_budget','waiting_limit','failed','unknown','cancelled'}:
                    with engine.store.connect() as db:db.execute('UPDATE web_jobs SET state=?,error=? WHERE id=?',(current['status'],current['error'],run_id))
                raise
            if updated['budget_decision_applied'] or updated['status'] in {'waiting_budget','waiting_limit'}:
                with engine.store.connect() as db:
                    state=updated['status']
                    if 'budget_enqueue_required' in updated:
                        # A live debt decision must not demote a concurrently completed job.
                        import json
                        current=json.loads(db.execute('SELECT body FROM runs WHERE id=?',(run_id,)).fetchone()['body'])
                        state=current['status']
                        if state=='running':state='working'
                        if state=='waiting_approval':
                            existing=db.execute('SELECT state FROM web_jobs WHERE id=?',(run_id,)).fetchone()['state']
                            state=existing if existing in {'verified','waiting_approval'} else 'working'
                        updated={**updated,'error':current['error']}
                    db.execute('UPDATE web_jobs SET state=?,error=? WHERE id=?',(state,updated['error'],run_id))
            if data.accept and updated.get('budget_enqueue_required',updated['budget_decision_applied']):engine.queue.put_nowait(run_id)
        return engine.job(actor,run_id)
    @app.post('/api/jobs/{run_id}/project')
    def project(run_id:str,actor=Depends(principal)):
        from src.apps.workbench.project_files import materialize
        return materialize(engine,actor,run_id)
    @app.get('/api/jobs/{run_id}/record')
    def record(run_id:str,actor=Depends(principal)):
        from src.apps.workbench.project_files import execution_record
        import json
        body=execution_record(engine,actor,run_id)
        return Response(json.dumps(body,ensure_ascii=False,indent=2),media_type='application/json',
                        headers={'Content-Disposition':'attachment; filename="'+body['record']['id']+'-execution.json"'})
    @app.get('/api/jobs/{run_id}/snapshot')
    def snapshot(run_id:str,actor=Depends(principal)):
        from src.apps.workbench.deliverables import saved_snapshot
        return Response(saved_snapshot(engine,actor,run_id),media_type='application/zip',
            headers={'Content-Disposition':'attachment; filename="'+run_id+'-saved-work.zip"','Cache-Control':'no-store'})
    @app.post('/api/jobs/{run_id}/cancel')
    def cancel(run_id:str,actor=Depends(principal)):
        row=engine.job(actor,run_id)
        cancelled=engine.runtimes[row['scenario']].cancel(actor,run_id)
        if cancelled['status']=='cancelled':
            with engine.store.connect() as db:db.execute("UPDATE web_jobs SET state='cancelled' WHERE id=?",(run_id,))
        return engine.job(actor,run_id)
    @app.get('/api/examples')
    def examples(actor=Depends(principal)): return engine.examples(actor)
    @app.get('/api/deliveries/{kind}/{reference}')
    def delivery(kind:str,reference:str,actor=Depends(principal)):
        from src.apps.workbench.deliverables import get_delivery
        return get_delivery(engine,actor,kind,reference)
    @app.get('/api/export/{kind}/{reference}')
    def export(kind:str,reference:str,actor=Depends(principal)):
        content=engine.export(actor,kind,reference)
        return Response(content,media_type='application/zip',headers={'Content-Disposition':'attachment; filename="zkcoding-java-validation.zip"'})
    @app.get('/api/erp/knowledge')
    def knowledge(actor=Depends(principal)): return engine.erp.catalog(actor)
    @app.post('/api/erp/ask')
    def ask(data:Question,actor=Depends(principal)):
        service=getattr(engine,'business',None) or engine.erp
        return service.ask(actor,data.question)
    @app.get('/api/business/scenarios')
    def business_scenarios(actor=Depends(principal)):
        available={p['id'] for p in identity.projects(actor)}
        return [engine.business.catalog(actor,scenario) for scenario in ('erp','wms','equipment') if scenario+'-demo' in available]
    @app.post('/api/business/ask')
    def business_ask(data:BusinessQuestion,actor=Depends(principal)):
        return engine.business.ask(actor,data.question,data.scenario)
    @app.post('/api/business/actions')
    def business_action(data:BusinessAction,actor=Depends(principal)):
        return engine.business.act(actor,data.scenario,data.action,data.entity_id,data.parameters,data.expected_version,data.request_key)
    @app.post('/api/business/reset')
    def business_reset(data:BusinessReset,actor=Depends(principal)):
        return engine.business.reset(actor,data.scenario,data.request_key)
    @app.post('/api/preview',status_code=202)
    def preview(data:Preview,actor=Depends(principal)): return engine.start_preview(actor,data.kind,data.reference)
    @app.get('/api/preview')
    def preview_state(preview_id:str|None=None,actor=Depends(principal)):
        return engine.preview_state(actor,preview_id) if preview_id else engine.preview_state(actor)
    @app.get('/api/previews')
    def previews(actor=Depends(principal)):return engine.preview_pool.list(actor)
    @app.post('/api/preview/client')
    def preview_client(data:PreviewClient,actor=Depends(principal)):
        return engine.preview_pool.browser_client(actor,data.preview_id,data.client_id,data.event)
    @app.get('/api/preview/pdf-sample')
    def pdf_sample(preview_id:str|None=None,actor=Depends(principal)):
        state=engine.preview_state(actor,preview_id) if preview_id else engine.preview_state(actor)
        if state['scenario']!='pdf':raise SkillError('SCENARIO_INVALID','当前预览不是PDF解析。',409)
        from src.modules.execution.scenarios.pdf import sample_pdf
        return Response(sample_pdf(),media_type='application/pdf',headers={'Content-Disposition':'attachment; filename="two-page-example.pdf"'})
    @app.delete('/api/preview')
    def close_preview(preview_id:str|None=None,actor=Depends(principal)):
        if preview_id:engine.close_preview(actor,preview_id)
        else:engine.close_preview(actor)
        return {'status':'closed'}
    @app.post('/api/preview/request')
    def preview_request(data:PreviewRequest,actor=Depends(principal)):
        state=engine.preview_state(actor,data.preview_id) if data.preview_id else engine.preview_state(actor)
        if data.preview_id is not None and data.preview_id!=state['id']:
            raise SkillError('PREVIEW_REPLACED','此网站的预览租约已结束,请从对应制品重新打开网站。',409)
        prefixes={'erp':('/health','/api/purchase/quote'),'wms':('/health','/api/stock','/api/stock/move'),
                  'equipment':('/health','/api/work-orders','/api/work-orders/open','/api/work-orders/transition','/api/inspection/next'),
                  'calculator':('/health','/api/calculate'),'pdf':('/health','/api/pdf/analyze'),
                  'webapp':(),'business-app':('/api/app/meta','/api/app/list','/api/app/action'),
                  'erp-orders':('/health','/api/orders','/api/orders/meta','/api/orders/detail',
                                            '/api/orders/receive','/api/orders/return','/api/orders/pay')}
        if not re.fullmatch(r'/(?:[A-Za-z0-9_/?=&.+-]|%[0-9A-Fa-f]{2}){0,500}',data.path) or data.path.split('?')[0] not in prefixes[state['scenario']]:
            raise SkillError('PREVIEW_PATH_DENIED','仅允许场景中定义的接口路径。',403)
        if state['scenario']=='business-app' and ((data.path.split('?')[0]=='/api/app/action') != (data.method=='POST')):
            raise SkillError('PREVIEW_METHOD_DENIED','该接口的方法不允许。',403)
        if data.body is not None and (state['scenario']!='pdf' or data.method!='POST' or data.path!='/api/pdf/analyze'):
            raise SkillError('PREVIEW_BODY_DENIED','该接口不接受上传内容。',422)
        if data.body is not None and (set(data.body)!={'base64'} or not isinstance(data.body['base64'],str) or len(data.body['base64'])>174764):
            raise SkillError('PREVIEW_BODY_INVALID','请上传不超过128KiB的PDF文件。',422)
        token={'erp':'demo-sales','erp-orders':'demo-sales','business-app':'demo-sales','wms':'demo-warehouse','equipment':'demo-maintenance','calculator':'demo-calculator','pdf':'demo-pdf','webapp':'demo-webapp'}[state['scenario']]
        return engine.request_preview(actor,data.method,data.path,'Bearer '+token,**({'body':data.body} if data.body is not None else {}),
                                      **({'preview_id':data.preview_id} if data.preview_id else {}))
    @app.get('/api/admin')
    def admin(actor=Depends(principal)):
        identity.admin(actor)
        jobs=engine.jobs(actor)
        modules=engine.runtimes['erp'].readiness(actor)
        try:
            engine.runtimes['erp'].sandbox.preflight();modules['sandbox_image_check']='verified'
        except SkillError as exc: modules['sandbox_image_check']=exc.code
        return {'readiness':modules,'model_routing':engine.runtimes['erp'].llm.routes(),'users':identity.users(actor),'jobs':jobs,'identity_mode':'persistent-local-accounts',
                'ordinary_chat_usage':engine.conversations.usage(actor),
                'external_sso':'not_configured','model_calls':sum(len(j['model_calls']) for j in jobs),
                'charged_tokens':sum(c['charged'] or 0 for j in jobs for c in j['model_calls']),
                'unsettled_token_reservations':sum(c['reservation'] for j in jobs for c in j['model_calls'] if c['charged'] is None),
                'deployment':{'bind':'127.0.0.1','port':port,'version':'local-web-v1','target_environment':'pending-user-selection'}}
    @app.post('/api/admin/users',status_code=201)
    def create_user(data:User,actor=Depends(principal)):
        return {'id':identity.create_user(data.username,data.password,data.roles,actor=actor)}
    @app.post('/api/admin/members')
    def membership(data:Member,actor=Depends(principal)):
        identity.set_member(actor,data.project_id,data.user_id,data.enabled);return {'ok':True}
    static=Path(__file__).resolve().parents[3]/'sites/zkcoding-workbench/dist'
    @app.get('/preview-launch/')
    def preview_launch(request:Request,actor=Depends(principal)):
        if not preview_only and preview_port is not None:
            return RedirectResponse(preview_origin+request.url.path+('?' + request.url.query if request.url.query else ''),status_code=307)
        return FileResponse(Path(__file__).parent/'preview_site/launch.html')
    @app.get('/preview-launch/{name}')
    def preview_launch_asset(name:str,actor=Depends(principal)):
        if name not in {'launch.js','lifecycle.js','site.css'}: raise SkillError('NOT_FOUND','资源不存在。',404)
        return FileResponse(Path(__file__).parent/'preview_site'/name)
    @app.get('/draft-preview/{run_id}/')
    def draft_preview(run_id:str,actor=Depends(principal)):
        if not preview_only and preview_port is not None:
            return RedirectResponse(preview_origin+'/draft-preview/'+run_id+'/',status_code=307)
        from src.apps.workbench.deliverables import draft_page
        return HTMLResponse(draft_page(engine,actor,run_id),headers={'Content-Security-Policy':
            "default-src 'none'; frame-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-ancestors 'none'"})
    @app.get('/preview-site/')
    async def preview_website(request:Request,actor=Depends(principal)):
        if not preview_only and preview_port is not None:
            return RedirectResponse(preview_origin+request.url.path+('?' + request.url.query if request.url.query else ''),status_code=307)
        kind,reference=request.query_params.get('kind'),request.query_params.get('reference')
        if kind is not None or reference is not None:
            # This GET only waits. The workbench starts the VM with its normal
            # authenticated, CSRF-protected POST; no debugging page is rendered.
            if kind not in {'run','example','skill'} or not reference:
                return HTMLResponse('<p>请从工作台的工程打开应用。</p>',status_code=422)
            await asyncio.to_thread(engine.evidence,actor,kind,reference)
            # Match the existing 900-second preview lease; a dependency profile
            # permits two separate VM stages of up to 420 seconds each.
            deadline=time.monotonic()+900;first_deadline=time.monotonic()+15;lease=None
            while time.monotonic()<deadline:
                if await request.is_disconnected():return Response(status_code=499)
                try:
                    if hasattr(engine,'preview_pool'):
                        state=await asyncio.to_thread(engine.preview_pool.state,actor,lease) if lease else await asyncio.to_thread(engine.preview_pool.find,actor,kind,reference)
                    else:state=await asyncio.to_thread(engine.preview_state,actor)
                except SkillError as exc:
                    if exc.code!='PREVIEW_NOT_FOUND':raise
                    state=None
                if not state and not lease and hasattr(engine,'preview_pool'):
                    return FileResponse(Path(__file__).parent/'preview_site/launch.html')
                if state and state.get('kind')==kind and state.get('reference')==reference:
                    if lease and lease!=state['id']:break
                    if state['status']=='ready':return RedirectResponse('/preview-site/?lease='+state['id'],status_code=307)
                    if state['status']=='starting':lease=state['id']
                    elif lease:break
                elif lease:break
                if not lease and time.monotonic()>first_deadline:break
                await asyncio.sleep(.25 if not lease else 1)
            return HTMLResponse('<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>应用暂未就绪</title><p>应用暂未就绪,请回工作台查看运行结果后重试。</p></html>',status_code=503)
        lease=request.query_params.get('lease')
        if lease:engine.preview_state(actor,lease)
        else:engine.preview_state(actor)
        return FileResponse(Path(__file__).parent/'preview_site/index.html')
    @app.get('/preview-site/{name}')
    def preview_asset(name:str,actor=Depends(principal)):
        engine.preview_state(actor)
        if name not in {'site.js','lifecycle.js','site.css'}: raise SkillError('NOT_FOUND','资源不存在。',404)
        return FileResponse(Path(__file__).parent/'preview_site'/name)
    @app.get('/preview-generated/')
    def preview_generated(lease:str,actor=Depends(principal)):
        state=engine.preview_state(actor,lease)
        if state['status']!='ready' or state['scenario'] not in {'webapp','business-app'}:
            raise SkillError('PREVIEW_NOT_FOUND','此网页预览不可用。',404)
        scenario,_,evidence=engine.evidence(actor,state['kind'],state['reference'])
        if scenario!=state['scenario'] or evidence['manifest']['source']['source_digest']!=state['receipt']['source_digest']:
            raise SkillError('PREVIEW_SOURCE_CHANGED','此预览的源码已变更,请重新打开。',409)
        source=evidence['manifest']['source']
        engine.runtimes[scenario].harness.files({'files':source['files']},evidence['manifest']['snapshot']['framework'])
        page=source['files']['website/index.html']
        if scenario=='business-app':
            from src.apps.workbench.business_bridge import inject
            page=inject(page)
        return HTMLResponse(page,headers={'Content-Security-Policy':
            "sandbox allow-scripts allow-modals; default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-ancestors 'self'"})
    @app.get('/')
    def index(request:Request):
        if preview_only:
            actor=principal(request)
            if request.url.query:return RedirectResponse('/preview-launch/?'+request.url.query,status_code=307)
            current=engine.preview_state(actor)
            if current['status']=='ready':return RedirectResponse('/preview-site/?lease='+current['id'],status_code=307)
            return RedirectResponse('/preview-launch/?kind='+str(current['kind'])+'&reference='+str(current['reference']),status_code=307)
        return FileResponse(static/'index.html')
    @app.get('/admin/')
    def admin_page():
        if preview_only:raise SkillError('NOT_FOUND','文件不存在。',404)
        return FileResponse(static/'admin'/'index.html')
    @app.get('/admin/{name}')
    def admin_asset(name:str):
        if preview_only or name not in {'admin.js','admin.css','workflow-editor.js','workos-admin-base.css'}:
            raise SkillError('NOT_FOUND','文件不存在。',404)
        return FileResponse(static/'admin'/name)
    @app.get('/{name}')
    def asset(name:str):
        if name not in {'app.js','app.css','workos-base.css','icons.js','local-store.js','runtime.js','runtime.css','favicon.svg'}: raise SkillError('NOT_FOUND','文件不存在。',404)
        return FileResponse(static/name)
    return app