Tianyi Cui
7f024a1a9d
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.
50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# 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`).
|