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.
28 lines
1.4 KiB
Markdown
28 lines
1.4 KiB
Markdown
# 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.
|