0 Fork 0

Files

T

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.4 KiB

Raw Blame History

AGENTS.md — Harness Packages

This directory contains all @deepseek-ai/dsh-* harness packages. When editing code here, follow these conventions:

Effect-based registrations: every contribution (tool, section, adapter, agent, event listener) goes through ctx.effect() / ctx.on(), and register() methods return disposers. Never use bare arrays or manual cleanup.
Declaration merging: services declare their ctx key in declare module 'cordis' { interface Context { } } and their events in interface Events. Merge-extensible maps (ContentBlockMap, MessageSourceMap, FinishReasonMap, TurnTriggerMap, TurnEndReasonMap, SessionEventMap) are how plugins add new variants.
Waterfall semantics: ctx.waterfall listeners receive (...args, next); call next() to delegate, or return without it to short-circuit (veto). Never call next() after returning.
Tests: vitest in packages/<name>/tests/*.spec.ts. Every registry needs an HMR-safety test (register a plugin, dispose its fiber, assert cleanup). Err on the side of more tests — edge cases, error paths, event ordering, races.

Naming notes:

Files src/index.ts export the service default + all public types
src/types.ts contain only types — no runtime code
Tests live at package level under tests/, not src/__tests__/

Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.

1.4 KiB Raw Blame History

AGENTS.md — Harness Packages

1.4 KiB

Raw Blame History