Tianyi Cui
b8d4790e98
The `yarn doc-sync` gate (doc-typecheck + verify-event-taxonomy) and the @deepseek-ai/dsh-invariants package both exist now, but the instruction docs never caught up and the gate's markdown scope (README.md, docs/**/*.md, packages/*/README.md) does not cover AGENTS.md / packages/AGENTS.md, so they drifted silently. - AGENTS.md: add invariants/ to the Repository Layout; add doc-typecheck / verify-event-taxonomy / doc-sync to Commands; rewrite the false "CI has no doc-sync gate" sentence to describe the gate's actual coverage and what remains outside it (AGENTS.md, packages/README.md, prose drift). - packages/AGENTS.md: fix the same stale "no doc-sync gate" line. - packages/README.md: add dsh-invariants to the dependency graph and the package table. Verification: `yarn doc-sync` green; `grep -rn "no doc-sync gate"` returns nothing; the three command names + dsh-invariants are present.
17 lines
1.8 KiB
Markdown
17 lines
1.8 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__/`
|
|
- 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 runs `yarn doc-sync`, which typechecks fenced `ts` blocks in `packages/*/README.md` and verifies the event-taxonomy table — but it does NOT cover this file or prose drift (config keys, defaults, error codes), so those stay on the author.
|
|
|
|
Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.
|