mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui 7f024a1a9d Document the codebase thoroughly and tighten type safety

Docs: per-folder README.md for packages/ (family overview + one per
package: service, events, API, extension points, TODOs), examples/,
and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md
symlinks) for packages/ and vendor/; module-level doc comments in
every packages/*/src file; richer JSDoc on all exported API
(event side effects, disposal contracts, error behavior). Root
AGENTS.md gains a "Type Safety and Documentation" policy section:
the codebase aims to be very type-safe and well documented; type
gymnastics are acceptable in core packages when they improve
plugin-author DX; verbose docs are fine as long as they stay strictly
in sync with the code.

Type safety: removed the upstream-inherited "noImplicitAny": false
from tsconfig.base.json — packages/* now compile under full strict
mode; vendor/loader and vendor/include set it locally (vendor/cordis
already did). Eliminated every `: any` / `as any` from packages and
examples (catch clauses use unknown + a CodedError narrowing type;
event data access uses discriminated-union narrowing).

Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL —
SchemaSpec with per-property `required: true` booleans, type-level
InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and
defineTool() so first-party tools get typed execute(args) with zero
casts (raw JSON Schema still accepted for MCP interop; chosen over
schemastery because it targets JSON Schema generation directly).
echo-tool and all test tools migrated; +7 tests.

2026-06-11 13:01:00 +08:00

1.9 KiB

Raw Blame History

dsh-system-prompt

System prompt assembly registry. Plugins contribute ordered text sections and tool-schema providers; the agent loop calls assemble() once per step.

Service: `SystemPrompt` (ctx key: `systemPrompt`)

Public API

ctx.systemPrompt.section(section: PromptSection): () => void Contribute a section. Disposed with the calling fiber.
ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void Contribute tool schemas (evaluated at each assembly). Disposed with the calling fiber.
ctx.systemPrompt.assemble(): Promise<PromptAssembly> Assemble the current prompt. Runs through the system-prompt/assemble waterfall.

Events

Event	Mode	Purpose
`system-prompt/assemble`	waterfall	Mutate/extend the assembly before it reaches the model
`system-prompt/change`	emit	A section or tool provider was registered or unregistered

Key types

PromptSection — { name, order, text: string | (() => string) }. Sections are concatenated in ascending order.
PromptAssembly — { sections: PromptSection[], tools: ToolSchema[] }. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.
renderPrompt(assembly) — joins section texts with blank lines.

Merge-extensible: plugins can declare extra fields on PromptAssembly via declaration merging.

Extension points

Section providers: AGENTS.md reader, cwd notifier, persona config, etc.
Tool schema providers: ToolRegistry registers itself as a tool provider automatically.
The system-prompt/assemble waterfall: mutate or replace the assembly (system-prompt configurability, dynamic tool filtering).

What is NOT here

Any hardcoded prompt text — every section comes from plugins.
Prompt compaction (belongs on the agent/request seam in dsh-agent).

1.9 KiB Raw Blame History