website: generate the API reference from source (cordis + all 15 harness services)

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.
2026-07-16 18:13:34 +08:00
parent da26138592
commit efba9fab0a
31 changed files with 2983 additions and 931 deletions
@@ -0,0 +1,66 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.systemPrompt
+
+`SystemPrompt` — provided by `@deepseek-ai/dsh-system-prompt`.
+
+Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step. Registers the harness-owned `harness:identity` and `deployment:persona` sections itself (see Config.persona).
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/system-prompt/src/index.ts#L291)
+
+### ctx.systemPrompt.section(section)
+
+```ts website-api
+section(section: PromptSection): () => void
+```
+
+Contribute a text section to the system prompt. Order is determined by `section.order` (ascending). Throws if a section with the same name is already registered (a duplicate would silently double prompt text — e.g. a double-loaded tool plugin). The section is removed when the calling fiber is disposed. Emits `system-prompt/change` on register/unregister.
+
+- `section` — the section to contribute (name, order, text or provider).
+
+**Returns** the disposer that removes the section.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/system-prompt/src/index.ts#L340)
+
+### ctx.systemPrompt.tools(provider)
+
+```ts website-api
+tools(provider: () => ToolSchema[]): () => void
+```
+
+Contribute a tool-schema provider that is evaluated at each assembly call (so it can reflect the live registry state). The provider is removed when the calling fiber is disposed. A provider must not return a schema named TOOL_ORDER_REST; that name is reserved for Config.toolOrder's rest entry and rejects the assembly. Emits `system-prompt/change`.
+
+- `provider` — evaluated at every {@link assemble} for fresh schemas.
+
+**Returns** the disposer that removes the provider.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/system-prompt/src/index.ts#L373)
+
+### ctx.systemPrompt.variable(name, provider)
+
+```ts website-api
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+```
+
+Contribute a named prompt variable, referenced from section text as `{{name}}`. The provider is evaluated at each assembly with that assembly's AssembleContext; returning `undefined` means "no value for this assembly" (a section referencing it then fails to render — a deployment must not claim facts it does not have). Throws on a name that does not match `[a-z][a-z0-9_]*` (it could never be referenced) or is already registered. Removed when the calling fiber is disposed; emits `system-prompt/change` on register/unregister.
+
+- `name` — the reference name (matches `[a-z][a-z0-9_]*`).
+- `provider` — evaluated at every {@link assemble} for the value.
+
+**Returns** the disposer that removes the variable.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/system-prompt/src/index.ts#L403)
+
+### ctx.systemPrompt.assemble(context?)
+
+```ts website-api
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Assemble the current prompt for one caller: section texts are resolved against `context` and sorted by order, tools collected from all providers and put in the canonical model-facing order (Config.toolOrder, or lexicographic name order when unconfigured — provider registration order is a plugin-load artifact and never reaches the assembly; a configured order naming a tool no provider contributed rejects the assembly), and every registered variable resolved against `context` into `assembly.variables`. Tool schemas are deep-cloned because adapters and request waterfalls may mutate schema objects. Runs through the `system-prompt/assemble` waterfall, giving listeners the opportunity to mutate or replace the assembly before it reaches the model — like the sections' `order` sort, tool canonicalization happens on the initial assembly, and a listener owns the determinism of whatever it emits. Await the result before reading the assembly values — waterfall listeners may be async. Interpolation happens later, in renderPrompt.
+
+- `context` — what this assembly is for (defaults to an empty context; see {@link AssembleContext}).
+
+**Returns** the assembly after the waterfall has run.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/system-prompt/src/index.ts#L447)