Tianyi Cui
066f94c7e0
Hard line breaks mid-paragraph make docs harder to edit and diff — a one-word change reflows and re-diffs the whole paragraph. Reflow all tracked non-vendor Markdown (plus vendor/AGENTS.md) so each prose paragraph is a single line; soft-wrapping is the editor's job. Fenced code, tables, and list structure are preserved (wrapped list items fold to one line per bullet). Documents the convention in AGENTS.md.
1.6 KiB
1.6 KiB
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(), andregister()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 ininterface Events. Merge-extensible maps (ContentBlockMap,MessageSourceMap,FinishReasonMap,TurnTriggerMap,TurnEndReasonMap,SessionEventMap) are how plugins add new variants. - Waterfall semantics:
ctx.waterfalllisteners receive(...args, next); callnext()to delegate, or return without it to short-circuit (veto). Never callnext()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.tsexport the service default + all public types src/types.tscontain only types — no runtime code- Tests live at package level under
tests/, notsrc/__tests__/ - A package's README and module/JSDoc comments are part of the change: when you alter behavior (config keys, defaults, error codes, wire fields), update them in the same commit. CI has no doc-sync gate, so stale docs are on the author.
Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.