Files
deepseek-harness/docs/subsystems
Tianyi Cui aa0ca6c836 docs: anchor each subsystem page to its package group; make group READMEs thin tables
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.

Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
2026-08-09 01:32:39 +08:00
..

Subsystems

English | 中文

One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a ctx service or event scope backs it — a generated Cordis surface section carrying its service and event reference. The folder complements architecture.md, which describes behavior across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.

Page Owns
core.md the packages/core control spine: the package-by-package loop map, the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map → derived-union pattern
llm-streaming.md the packages/llm conversation vocabulary — Message/ContentBlock, the assembled model request, the StreamChunk wire protocol + adapter contract, BlockAssembler, the LlmAdapter seam
token-meter.md immutable scalar and positional replay measurements with consumed-log revisions
scope.md scoped registration identity, dispatch carriers, and the owned Scope context
typert.md Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams
goal.md persisted goal identity, lifecycle snapshots, activation, change records, and round attribution
commands.md the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views
session.md the full SessionEventMap variant catalog, TurnTrigger/TurnEndReason, deriveMessages(), execution enclosure, and standalone events
persistence.md the durability seam: SessionPersistence, JSONL + SQLite backends, session/flush, crash recovery, SessionHeader
settings.md the user-settings seam: SettingsNamespace registration, layered resolution (defaults → composition base → user document), owner scopes, hot commits
credentials.md the credential seam: CredentialRef references (never values) in configuration, per-operation resolution, UI-safe CredentialInfo, provider source layers
session-query.md logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages
session-title.md durable title snapshots, source provenance, and the asynchronous provider contract
system-prompt.md per-assembly context, tool-provider results, prompt sections, and cooperative assembly
tools.md ToolDefinition full fields, the schema DSL, ToolExecution/ToolResult, tool-presentation UI types, and the guarded execution pipeline
user-interaction.md the UI-backed human question/answer seam: AskUserQuestionRequest, answer/options vocabulary, provider API, error taxonomy
approval.md the one-shot user-approval seam: ApprovalRequest, ApprovalOutcome, per-session policy, audit and answerer contracts
bash.md the bash executor seam: BashExecRequest/Spec, BashRunResult, background BashProcess handles
subprocess.md the subprocess seam: fully-explicit SubprocessSpawnSpec, offset-based output readers, unclassified SubprocessOutcome, and the managed DSH_* environment vocabulary
pty.md persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots
sandbox.md per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, ConfinedArgv, enforcement and fail-closed errors
code-runtime.md the code-execution seam: CodeRunRequest/Result, binding namespaces, captured logs, the CodeRunFailure taxonomy
filesystem.md the filesystem seam: FsTarget, read/write/edit outcomes, observed-file state, FsErrorCode
lsp.md the LSP navigation seam: LspQueryRequest/Result, LspProvider/Service, four operations, LspError
skills.md the skill service: discovery priority, SkillSummary/SkillDefinition, session-prefix catalog, model-facing skill loading
compaction.md the compaction seam: the compact/* session events, CompactionResult, the CompactService interface
subagent.md the subagent seam: the named-provider registry, SubagentStartRequest/Result/Run, the start-time-vs-runtime capability split
web.md the web access seam: WebSearchRequest/Result, WebFetchRequest/Result, WebFetchBody, provider availability, WebError
spill.md the spill storage seam: SaveTextSpill, SpillOwner/SpillSource, SpillRef, the branded SpillLocator
workflow.md the workflow seam: WorkflowStartRequest, WorkflowMeta, WorkflowRun/Result, the workflow/* event payloads, WorkflowError fatality
permission.md the permission-preset layer: PresetSpec/PresetOption, the derived custom state, the log-only permission/preset event
plan.md plan mode: the log-only plan/mode state, pending-selection flush, PlanModeConfig, the exit_plan_mode review arc
invariants.md the runtime-invariant registry: selection Config, InvariantInstaller/InvariantFailure, the empty-companion contract
http-server.md the HTTP carrier: WebRouteKind/WebRoute, match order, the static dist fallback, index taps
storage.md the storage subsystem: the backend seam (StorageBackend), StorageForms, DomainSpec/Domain, domain/changed
tui.md the terminal-extension seam: TuiOverlayRequest/Host/Session, close reasons and outcomes, the modal queue
workspace.md the workspace registry: Workspace/WorkspaceId, registration and resolution, the session cwd relationship
client-modules.md the web plugin table: dshClient declarations, WebBootGraph wire composition, the bundle route and index tap
session-projection.md the projection seam: SessionProjectionMap, the pure ProjectionDefinition unit, ProjectionSnapshot's consistent cut, the change feed
telemetry.md the outbound reporting seam: TelemetryRecord/TelemetrySeverity, the TelemetryBackend contract, the telemetry/record redact waterfall

Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by pnpm run verify-type-equiv (see development.md). Ordinary blocks preserve complete declarations; public-api blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated Cordis surface section.