lintianle
efba9fab0a
scripts/gen-website-api.ts renders website/zh-CN/api/{cordis,harness}/* and the
api-sidebar.json fragment the VitePress config imports, so pages and navigation
can never drift from the code: signatures, @param/@returns prose, dispatch
modes, and GitHub source links are extracted, never transcribed, and the
generator hard-errors on any rendered member missing docs. verify-website-api
(doc-sync + run-gates) is the freshness gate.
Replaces the hand-written zh api pages (7 pages covering 7 of 15 services,
with phantom APIs: Context.current/Context.events, agent/post-step, tool/call,
compact/*, llm/pre-request none of which exist) with generated English
references: 5 cordis pages, 15 per-service pages, and a 35-event catalog
grouped by scope. The hand-written hub api/index.md stays and now indexes the
full surface; zh for these pages arrives with the unified translation flow.
2.2 KiB
2.2 KiB
ctx.workflows
WorkflowService (abstract seam) — provided by @deepseek-ai/dsh-workflow.
Abstract workflow execution service. Subclass, implement start, and load the subclass as a plugin — it registers as ctx.workflows (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
Semantics every implementation must honor:
- start throws synchronously for a request that cannot begin (an unparseable script, an invalid meta block). Once it returns a WorkflowRun,
resultNEVER rejects — every failure resolves withstopReason: 'error'(or'cancelled') — and once the run is cancelled,resultSETTLES within the implementation's bounded grace even if the script itself never settles (a consumer awaitingresultmust never be wedged past a cancellation). - The
workflow/*events fire through emitWorkflowEvent (data snapshots, per-listener containment);workflow/endfires exactly once per started run, afterresultis settled or as it settles. dispose()reaches quiescence within a bounded grace: it cancels, waits for the script to settle AND its started children to finish disposing, and abandons whatever is left rather than hanging its caller (the engine documents what abandonment leaves behind).- Runs are HOLDER-OWNED: the engine hands control (
cancel/dispose) to thestart()caller and does not track its live runs — disposing the engine's own fiber mid-run deliberately leaves those runs to their holders' teardown, so an engine reload cannot yank a run out from under the consumer awaiting it.
ctx.workflows.start(request)
abstract start(request: WorkflowStartRequest): WorkflowRun
Parse and execute a workflow script.
request— the script, itsargs, the parent agent, and an optional cancel signal.
Returns the live run; its result resolves when the script settles.