Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: generated cordis events + services catalog

Browse Source 
Add scripts/gen-cordis-catalog.ts: a fully-generated docs/cordis-catalog/
events-and-services.md cataloging every cordis event (exact signature + @mode)
and ctx.<key> service (exact interface), modeled on gen-module-graph's
--write/--check freshness gate. The harness tier renders in full from the
interface Events / interface Context declarations and their JSDoc; the inherited
cordis-core/loader/hmr/timer surface renders tersely from a curated table.

The generator hard-errors on a missing @mode tag and on a tag that contradicts
a conclusive signature shape (a trailing next param is structurally a
waterfall). Signature blocks use a ts cordis-catalog fence that doc-typecheck
skips. Type tokens cross-link to the core-data-structures catalog.

This supersedes the hand-maintained event-taxonomy table: verify-event-taxonomy
is deleted and verify-cordis-catalog joins doc-sync. architecture.md keeps the
Event taxonomy heading (TOC anchor) but points at the catalog; the Service-map
role table stays. RFC, AGENTS.md @mode authoring rule, and dependent doc/skill
references updated. Negative gate tests cover the missing-tag and
tag/shape-contradiction paths.
This commit is contained in:
Tianyi Cui
2026-06-20 19:47:09 +08:00
parent ee494969af
commit 4e5c08ef82
15 changed files with 1107 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/architecture.md
View File

@@ -56,6 +56,8 @@ Dependency rule: plugins depend on interface packages, never on `dsh-agent-loop`
All registrations (`registerAdapter`, `section`, `tools`, `register`, …) go through `ctx.effect()` and return disposers, so plugin hot-reload (vendored HMR) and fiber disposal clean up automatically.
For each service's full public interface (every method signature, generated from source), plus the inherited cordis-core/loader/hmr/timer surface a plugin also sees, see the `## Services` section of [cordis-catalog/events-and-services.md](cordis-catalog/events-and-services.md). This table is the at-a-glance role summary; that catalog is the exhaustive reference.
## Capability seams: interface / implementation / consumer
Swappable capabilities are split into **three packages** so each part evolves independently. The bash capability is the template:
@@ -167,26 +169,7 @@ A failure that happens once the turn is already closed has no in-turn position f
### Event taxonomy
The `agent/*` events are declared in `@deepseek-ai/dsh-agent` (so nothing depends on the loop package); each other service declares its own events (`tools/*`, `llm/*`, `system-prompt/*`, `session/*`). The table below is CI-verified against the `interface Events` declarations in source (`scripts/verify-event-taxonomy.ts`).
| Event | Mode | Purpose |
|---|---|---|
| `agent/created` / `agent/disposed` / `agent/status` / `agent/queued` | emit | lifecycle + inbox notifications |
| `agent/turn-start` / `agent/turn-end` / `agent/step-start` / `agent/step-end` | emit | boundaries |
| `agent/request` | **waterfall** | mutate the final `GenerateOptions` before the model call |
| `agent/stream-chunk` | emit | token-level UI/log feed |
| `agent/step-result` | **waterfall** | post-process the assistant message before tool dispatch |
| `agent/steering` | emit | steering content injected |
| `agent/turn-continuation` | **waterfall** | override the continue/stop decision |
| `agent/error` | emit | step/turn errors |
| `tools/execute` (dsh-tools) | **waterfall** | wrap/veto/sandbox tool execution |
| `tools/change` (dsh-tools) | emit | a tool was registered/unregistered |
| `llm/stream` / `llm/generate` (dsh-llm) | **waterfall** | model-call interception |
| `llm/adapter-change` (dsh-llm) | emit | an adapter was registered/unregistered |
| `system-prompt/assemble` (dsh-system-prompt) | **waterfall** | mutate the assembly |
| `system-prompt/change` (dsh-system-prompt) | emit | a section/tool-provider changed |
| `session/created` / `session/event` (dsh-session) | emit | session lifecycle + log feed |
| `session/flush` (dsh-session) | parallel (awaited) | durability checkpoint |
The `agent/*` events are declared in `@deepseek-ai/dsh-agent` (so nothing depends on the loop package); each other service declares its own events (`tools/*`, `llm/*`, `system-prompt/*`, `session/*`). The full catalog — every event's exact signature, dispatch mode, and prose — is **generated from source** and lives in [cordis-catalog/events-and-services.md](cordis-catalog/events-and-services.md) (the `## Events` section), alongside the `ctx.<key>` service interfaces. That file is regenerated by `scripts/gen-cordis-catalog.ts` and frozen by the `verify-cordis-catalog` freshness gate (part of `doc-sync`), so it cannot drift from the `interface Events` declarations.
### Cordis waterfall semantics (important)