c2d5a5be80
Bring PR #219 onto current master before re-evaluating review findings so fixes are tested against the code that would actually land. Resolve generated catalogs by regeneration, preserve the new ACP tool-schema sidecar format while refreshing affected snapshots keylessly, and update the newly paired Chinese adding-a-tool document to match the background-task guidance. This keeps generated and bilingual artifacts authoritative instead of choosing one conflict side blindly.
4.9 KiB
Packages
Packages use the @deepseek-ai/dsh-* scope. Each is a Cordis Service subclass or function plugin; contributions use ctx.effect(), ctx.on(), or ctx.waterfall(). Authoring rules: package and root.
Hierarchy
Packages live at packages/<group>/<pkg>/; groups are containers, while names remain @deepseek-ai/dsh-<pkg>. Each group README is the canonical package/ctx-key map.
| Group | Role | Release expectation |
|---|---|---|
core/ |
Product API spine: session, system-prompt, tools, agent, and the concrete loop | Product — stable surface |
llm/ |
LLM capability family: the abstract service + provider adapters | Product — stable surface |
bash/ |
Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface |
code-runtime/ |
Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
sandbox/ |
Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
fs/ |
Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
skill/ |
Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
compact/ |
Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
context/ |
Opt-in request-context enrichment | Product — stable surface |
subagent/ |
Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
tasks/ |
Generic background-task runtime and model-facing task_* control tools |
Product — stable surface |
workflow/ |
Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing workflow tool |
Product — stable surface |
web/ |
Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
timeout/ |
Tool-call timeout policy: the tools/execute deadline enforcer |
Product — stable surface |
todo/ |
Todo/planning family: the model-facing todo_write tool |
Product — stable surface |
guard/ |
Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
cordis/ |
Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins (design) | Product — stable surface |
hooks/ |
Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
session-persistence/ |
Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
session-query/ |
Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface |
ui/ |
Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface |
support/ |
Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations |
util/ |
Low-level zero-dependency utilities shared across groups (the Branded<B> primitive) |
Support — small, stable, harness-dep-free |
Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
Dependencies
The inter-package dependency graph is generated: docs/module-graph.md (pnpm run gen-module-graph, freshness-gated in CI).
Extension plugins depend on interfaces, never the concrete loop. Composition bundles such as dsh-agent-core intentionally assemble that loop. Swappable capabilities split into interface, implementation, and consumer packages; see capability seams.
Package READMEs cover purpose, APIs, extension points, and Model Experience unless on the model-agnostic omission allowlist. They also carry ## Known Limitations and Deferred Work or use its allowlist.