dsh-plugin-guide 0.3.42 → 0.4.0

package/guide/quick-reference.es.md

@@ -1,185 +0,0 @@
-# Chuleta de plugins de DeepSeek Harness
-
-> Referencia rápida de una página. Detalles: [plugin-dev-guide.md](plugin-dev-guide.md) (chino) y [references](../references/).
-> Otros idiomas: [English](quick-reference.md) · [中文](quick-reference.zh-CN.md) · [Português](quick-reference.pt.md) · [हिन्दी](quick-reference.hi.md)
-
-## Esqueleto del plugin
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'my-plugin'          // obligatorio
-export const inject = ['tools']          // servicios requeridos; omite si no hay
-
-export interface Config { limit: number }
-export const Config: Schema<Config> = Schema.object({
-  limit: Schema.number().default(10),    // schema de Schemastery, no un objeto plano
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.effect(() => {                     // registro = efecto, se deshace al descargar
-    const timer = setInterval(() => {}, 1000)
-    return () => clearInterval(timer)
-  })
-  ctx.on('tools/result', (exec, result) => { /* ... */ })
-  ctx.tools.register(defineTool({
-    name: 'my_tool',
-    description: '…',
-    parameters: { x: { type: 'string', required: true } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) { return `hi ${args.x}` },  // respeta exec.signal
-  }))
-}
-```
-
-Otras formas: objeto `export default { name, inject, apply }`; clase `class X extends Service { static inject=[...]; constructor(ctx){ super(ctx,'key') } }` (úsela al proveer un servicio).
-
-## API principal de ctx (Cordis)
-
-| Propósito | API |
-|---|---|
-| Registrar recurso + limpieza | `ctx.effect(() => disposer)` |
-| Escuchar eventos | `ctx.on(name, handler)` (limpieza automática) |
-| Difusión / sin retorno | `ctx.emit(name, payload)` |
-| Valor con cortocircuito | `ctx.bail(name, input)` (gana el primero no-null/false/undefined) |
-| Valor ordenado | `await ctx.serial(name, input)` |
-| Tubería | `await ctx.waterfall(name, input, init)`; los listeners **deben llamar `next()`** |
-| Contextos hijo | `ctx.extend(meta)` / `ctx.isolate(name, label?)` / `ctx.intercept(name, config)` |
-| Montar plugin hijo | `ctx.plugin(plugin)` → Fiber; `await fiber.dispose()` |
-| Consulta de servicio opcional | `ctx.get('metrics')?.x()` |
-| Logging | `ctx.logger(name)` |
-
-Ciclo de vida: `PENDING → LOADING → ACTIVE` (si apply lanza → FAILED); `ACTIVE → UNLOADING → DISPOSED`. Si un servicio requerido desaparece, el plugin se descarga; se recarga cuando el servicio vuelve.
-
-## Modos de despacho de eventos (cinco, incluido bail)
-
-| Modo | await | Orden | Valor de retorno |
-|---|---|---|---|
-| emit | no | orden de registro | ninguno |
-| waterfall | no | orden de registro | sí (**no llamar `next()` cortocircuita**) |
-| parallel | sí | paralelo | ninguno |
-| serial | sí | orden de registro | sí (el primero no vacío detiene) |
-| bail | no | orden de registro | sí (el primero no null/false/undefined cortocircuita y DETIENE el resto) |
-
-Eventos tipados (declaration merging):
-
-```ts
-declare module '@deepseek-ai/cordis' {
-  interface Events { 'my/event': (p: { id: string }) => void }
-  interface Context { myService: MyService }   // al proveer un servicio
-}
-```
-
-## cordis.yml / capas
-
-```yaml
-# scratch-plugin/cordis.yml (overlay --patch)
-- insert:
-    - id: hello
-      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
-      config: { greeting: 'Hi' }
-
-# bundle: "dsh": {"bundle":{"patch":"./cordis.patch.yml"}} en package.json
-# profile: "dsh": {"profile":{"bundles":["@deepseek-ai/dsh-base","my-bundle"]}}
-# orden efectivo: bundles → cordis.patch.yml del profile → $DSH_HOME/cordis.patch.yml → --patch
-# sobrescritura por id; se reemplaza toda la fila config (sin deep merge) — repite cada clave
-# !!js se evalúa tras activarse los servicios inyectados; disabled se evalúa en cada montaje
-```
-
-Comandos: `dsh --profile web` · `dsh --profile headless "task"` · `dsh --profile X --dump-config` · `dsh plugin --profile X add/remove <pkg>` · `pnpm dsh web --patch ./scratch-plugin/cordis.yml`
-
-Canales de instalación (repository-plugin eliminado el 0811 — solo quedan dos):
-- **plugin bundle** (`"dsh":{"bundle":{"patch":"..."}}`) → `dsh plugin add <pkg>` entra en la pila `dsh.profile.bundles`; efecto tras reiniciar.
-- **plugin cordis simple** (sin `dsh.bundle`) → `dsh plugin add <pkg>` instala la dependencia + una fila insert en `cordis.patch.yml` del profile; **HMR de configuración en vivo**.
-- fuente git: `dsh plugin add "github:owner/repo#<sha>&path:<subdir>"` (fija el commit; build `prepare` autocontenido + `allowBuilds` en `pnpm-workspace.yaml` del profile; npm/tarball no requiere permiso de build).
-
-## Servicios integrados comunes (claves de ctx)
-
-`sessions` registro de sesión · `systemPrompt` ensamblado de prompts · `tools` registro de herramientas + pipeline protegido · `agents` registro de agentes · `agentLoop` driver del bucle · `llm` registro de adaptadores · `skills` registro de skills · `commands` comandos slash · `approval` aprobación única · `jobs` trabajos en segundo plano · `fs` seam de sistema de archivos · `shell` seam de ejecución bash · `subprocess` seam de subprocesos · `terminals` PTY · `sandbox` seam de confinamiento · `codeRuntime` ejecución de código · `sessionPersistence` persistencia · `settings` / `credentials` / `workspaceRegistry` / `goals` / `planMode` / `subagents` / `workflowEngine` / `storage`.
-Lista completa y firmas exactas → `references/official-docs/docs/capability-seams.md` + `docs/subsystems/*.md` (regiones Cordis API generadas).
-
-## Pipeline de políticas de herramientas (orden de ejecución)
-
-```
-tools/pre-execute (waterfall, allow|deny|ask) → ctx.tools.guard() (denegación monótona)
-→ tools/execute (wrapper; solo exec.signal reemplazable) → execute(args, exec)
-→ tools/post-execute (reemplazar content/value, bloquear, adjuntar contexto) → finalizeContent
-→ tools/result (solo observación) → tool/result durable (evento de sesión)
-```
-
-Selección: puertas de política → pre-execute; denegación inapelable → guard; timeout/reintentos/métricas → execute; transformar resultados → post-execute; auditoría/recolección → result.
-Code Mode: `await tools.<name>(args)` viene gratis; éxito = valor JSON canónico final; fallo = `ToolCallError(name, toolName, message)`.
-
-## Tarjetas de UI (¡funciones puras! solo args(+result) — sin I/O/reloj/aleatorio)
-
-- `presentCall(args)` → `{card:'generic',title,kind?,rawInput?,content?,locations?}` | `{card:'terminal',title,description?,cwd?}` | `{card:'diff',title,diffs,locations?}`
-- `presentResult(args,{content,isError,meta?})` → generic / terminal / diff / search(`shape:'matches'|'paths'`) / read / web(`kind:'search'|'fetch'`)
-- Metadatos de repetición: `output.presentationMeta(args, value)` → persistido en `tool/result.meta`
-
-## Plantilla de seam de capacidad de tres roles
-
-Definition (`dsh-my-cap`): `export abstract class MyCapService extends Service { constructor(ctx){super(ctx,'myCap')} abstract execute(req): Promise<res> }` + declaration merging de Context.
-Provider (`dsh-my-cap-local`): `export function apply(ctx){ ctx.plugin(class MyCapLocal extends MyCapService {...}) }`.
-Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(defineTool({... execute: args => ctx.myCap.execute(...)}))`.
-Reglas: no dividir prematuramente; Provider y Consumer nunca dependen entre sí; los valores por defecto se resuelven explícitamente en `resolve(request): Spec`.
-
-## Esenciales del adaptador LLM
-
-`class MyAdapter extends LlmAdapter { async *stream(options): AsyncIterable<StreamChunk> }` → `ctx.llm.registerAdapter(['provider'], adapter)`.
-Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloque completo) → … → `usage` (antes de finish) → `finish` (último; `reason: {kind:'stop'|'tool-calls'}`). Lanza `LlmError` con código estable para los campos que no puedas cumplir.
-
-## Reglas estrictas (violarlas = fallos de puerta / mal comportamiento)
-
-1. Todo registro pasa por `ctx.effect()` / `ctx.on()` / el `register()` de un servicio (devuelve disposer). Un registro en otro contexto (p. ej. `agent.ctx`) tiene **dos dueños**: guarda también su disposer en tu propio effect.
-2. Los listeners de waterfall deben llamar `next()`; no llamarlo cortocircuita por diseño. Al reescribir una decisión de `agent/pre-step`, **propágala con spread** (`{ ...decision, messages }`) para no perder campos como `startsRequestSeries`.
-3. **El mecanismo más débil que baste**: `ctx.tools.restrict()` (solo quita) < `ctx.tools.guard()` (solo deniega) < reescritura por waterfall (depende del orden) < `system-prompt/assemble` (reemplaza todo). Observa resultados finales en `tools/result`; usa `tools/post-execute` solo para transformar.
-4. Visible-para-el-modelo ⇔ registrado: una nueva entrada visible requiere un nuevo evento de sesión (`SessionEventMap`) — **lo añade el host**, no tú (ver regla 10).
-5. Nunca codifiques valores ajustables (prueba: ¿puede cambiarlos cordis.yml?); la mala configuración falla en voz alta. Los campos editables en vivo usan `Volatile<T>` + `loader/volatile-update` (el namespace del formulario es el id de la entrada del perfil).
-6. Paquetes de plugin independientes: cordis es peerDependency con la misma identidad del host (mezclar scoped `@deepseek-ai/cordis` y unscoped divide identidades); ESM; manifiesto `dsh.bundle` (`patch` puede ser una lista ordenada); instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball. Los paquetes dsh de instancia compartida van **solo en peerDependencies + devDependencies**, nunca en `dependencies` (una copia en el perfil ensombrece el runtime en silencio). ⚠️ Corregido: **los rangos de peers SÍ se aplican al instalar** — `dsh plugin add` compara la versión del runtime con el rango declarado de `@deepseek-ai/dsh-*` y rechaza la instalación; solo `engines.dsh` es declarativo y no se aplica. Un rango indica "se puede instalar", no "esta API existe": mantén la sonda en runtime (selección de rango: `version-matrix.md` §4).
-7. Publica metadatos de presentación: `locale/*.json` con `meta.title`/`meta.description` y un `./icon` exportado (SVG/PNG/JPEG/WebP, ≤256 KiB, dentro del paquete). Los plugins de subruta **nunca** leen su propio `package.json`.
-8. Documentación bilingüe en pares; descripciones/prompts son comportamiento; cambios no triviales llevan Agent Note; ejecuta el conjunto mínimo de checks antes de empujar (dsh-pre-push-checks).
-9. Los ids opacos entre límites son branded (`Branded<B>` de `dsh-brand`), nunca `string` pelado.
-10. **Nunca añadas un evento de sesión con un `type` nuevo**: los miembros de `SessionEventMap` son required-on-read — un build que no conoce un tipo rechaza todo el log salvo que el evento lleve la marca `ignorable: true` del sobre, y `Session.append()` en vivo no puede escribir esa marca (su tercer argumento es un `SurfaceIntent` solo para eventos de superficie). Deriva tu estado de eventos existentes o guárdalo en un servicio de storage localizado por inspection. Solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION` (hoy `4`; la migración V3→V4 eleva los resultados de tool a mensajes con rol tool y mueve los `source` de mensaje al `source.kind` del productor). El switch sobre `SessionEvent` sigue cayendo por un `default` documentado — sin `assertNever` (unión merge-extensible).
-11. El `source` de `agent.inject()` ya **no acepta** el envoltorio retirado `{ kind: 'plugin', plugin: '<name>' }`: declara tu propio kind con `MessageSourceMap` primero. `inject` no despierta al agente (`followup()`/`steer()` sí).
-12. **Nunca escribas el `cordis.patch.yml` del perfil con sesiones en marcha** (HMR lo recarga: los tools desaparecen de las sesiones vivas, los turnos en vuelo mueren y reconstruir `session-controller` puede dejarlo muerto hasta reiniciar el proceso). Nunca escribas a mano el `package.json` del perfil ni ejecutes pnpm dentro del directorio del perfil.
-13. Plugins de UI: renderiza React en un slot (nunca una página servida en iframe); estiliza **solo** con tokens de tema `--dsw-alias-*`; nunca hagas `require` de un paquete Client de Harness (un componente que lanza deja el slot en blanco); `dsh.client.inject` debe ser un **array estático**.
-14. Rendimiento: guarda el estado por sesión en `ctx.sessionProjections` (`apply` puro y síncrono, misma referencia si lo ignora, JSON plano + `stateVersion`); espera eventos durables (`turn/end`, `assistant/message`, `tool/result`) y renderiza tokens en vivo desde `agent/assistant-stream`; nunca hagas polling de `agent/status`.
-
-## Lista rápida de trampas comunitarias (detalles: guía §7.3 / community-repo-deep-dive.md)
-
-- Trío de tsconfig: `moduleResolution: bundler` + `allowImportingTsExtensions` + `rewriteRelativeImportExtensions` (+ `lib:["ES2024"]`, `types:["node"]` explícito).
-- `tsc` emite pese a errores → `tsc || exit 1` / `--noEmitOnError`; busca imports `.ts` residuales en el build antes de publicar.
-- Junctions de Windows con PowerShell `New-Item -ItemType Junction`; la letra de unidad de vitest en mayúscula `C:/`.
-- `DSH_PERMISSION_MODE=danger-full-access` es de alto riesgo (sin backend de sandbox en Windows, aprobaciones desactivadas); `DSH_*` en `~/.dsh/.env` rompe el arranque.
-- Los archivos de sesión son zstd multiframe: usa `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: `dsh` sin alcance es el proyecto ajeno node-dsh (un shell) — instala `@deepseek-ai/dsh` (latest=0.1.2-rc.1); `@deepseek-ai/dsh-tools` y `@deepseek-ai/dsh-session-persistence-jsonl` tienen `latest` obsoleto (0.0.1-rc.1), fija `next` (0.1.2-rc.1); `create-dsh-plugin` latest=0.2.1; dsh-core/dsh-sdk siguen sin publicarse (verificado 2026-09-04).
-- Haz `resolve()` en ambos lados antes de comparar rutas (trampa de barras invertidas de Windows).
-
-## Enlaces de documentación
-
-Documentación oficial de desarrollo — base del sitio <https://deepseek-harness.github.io/deepseek-harness> (la raíz es chino, `en/` es inglés; copias locales textuales en `references/official-docs/docs/`):
-
-- Básico: [develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) → [tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) · [config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) · [publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
-- Framework: [develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/) ([service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service), [events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events)) · Práctica: [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/) ([LLM adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter))
-- Guías: [quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) · [providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) · [python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk)
-- Cordis: [primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) · [tutorial](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) · [core API](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context)
-- Referencia: [architecture](https://deepseek-harness.github.io/deepseek-harness/reference/) · [cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) · [subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)
-- Índice completo URL ↔ copia local: [guide/links.md](links.md)
-
-Documentación comunitaria de desarrollo — plantillas/tutoriales/errores, lista completa en [references/community-ecosystem.md](../references/community-ecosystem.md): [plugin-template](https://github.com/omdsh-dev/plugin-template) · [dsh-plugin-dev pitfalls](https://github.com/omdsh-dev/dsh-plugin-dev) · [from-scratch tutorial](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) · [dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check)
-
-## Índice de fuentes clave
-
-- Documentación oficial textual: `references/official-docs/docs/**` (215 páginas, incluye pares `.zh.md`)
-- Restricciones raíz del repo: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; estado de sincronización en `references/official-docs/SNAPSHOT.md`
-- HTML del sitio: `downloads/web/site/**` (sitio completo EN+ZH) + `downloads/manifest.tsv`
-- Cordis upstream: `downloads/github/cordis/**` + investigación `references/upstream-cordis.md`
-- Paper de Cordis: `downloads/github/paper/**` + investigación `references/cordis-paper-and-community.md`
-- Investigación del sitio web: `references/website-pages.md`
-- Investigación del repo: `references/harness-repo.md`
-- Comunidad/ecosistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
-- Todas las URLs de fuentes: `references/sources.md`
-- [Matriz de versiones](version-matrix.md) — los cuatro valores «latest», etiquetas `latest` congeladas, fallas de compatibilidad y selección de rango de peers.
-- [Lista de migración](migration-0.2.md) — §0–§12 cubren los cambios que rompen compatibilidad, **§13 los 19 seams de `0.2.1-alpha.2`**.

package/guide/quick-reference.hi.md

@@ -1,185 +0,0 @@
-# DeepSeek Harness प्लगइन चीट शीट
-
-> एक पेज का त्वरित संदर्भ। विवरण: [plugin-dev-guide.md](plugin-dev-guide.md) (चीनी) और [references](../references/)।
-> अन्य भाषाएँ: [English](quick-reference.md) · [中文](quick-reference.zh-CN.md) · [Español](quick-reference.es.md) · [Português](quick-reference.pt.md)
-
-## प्लगइन का ढाँचा
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'my-plugin'          // अनिवार्य
-export const inject = ['tools']          // आवश्यक सेवाएँ; न हों तो छोड़ें
-
-export interface Config { limit: number }
-export const Config: Schema<Config> = Schema.object({
-  limit: Schema.number().default(10),    // Schemastery स्कीमा, सादा ऑब्जेक्ट नहीं
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.effect(() => {                     // पंजीकरण = इफ़ेक्ट, अनलोड पर पूर्ववत
-    const timer = setInterval(() => {}, 1000)
-    return () => clearInterval(timer)
-  })
-  ctx.on('tools/result', (exec, result) => { /* ... */ })
-  ctx.tools.register(defineTool({
-    name: 'my_tool',
-    description: '…',
-    parameters: { x: { type: 'string', required: true } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) { return `hi ${args.x}` },  // exec.signal का सम्मान करें
-  }))
-}
-```
-
-अन्य रूप: ऑब्जेक्ट `export default { name, inject, apply }`; क्लास `class X extends Service { static inject=[...]; constructor(ctx){ super(ctx,'key') } }` (सेवा प्रदान करते समय उपयोग करें)।
-
-## मुख्य ctx API (Cordis)
-
-| उद्देश्य | API |
-|---|---|
-| संसाधन पंजीकरण + सफ़ाई | `ctx.effect(() => disposer)` |
-| घटनाएँ सुनना | `ctx.on(name, handler)` (स्वतः सफ़ाई) |
-| प्रसारण / बिना रिटर्न | `ctx.emit(name, payload)` |
-| शॉर्ट-सर्किट मान | `ctx.bail(name, input)` (पहला non-null/false/undefined जीतता है) |
-| क्रमबद्ध मान | `await ctx.serial(name, input)` |
-| पाइपलाइन | `await ctx.waterfall(name, input, init)`; श्रोताओं को **`next()` अवश्य बुलाना चाहिए** |
-| चाइल्ड कॉन्टेक्स्ट | `ctx.extend(meta)` / `ctx.isolate(name, label?)` / `ctx.intercept(name, config)` |
-| चाइल्ड प्लगइन माउंट | `ctx.plugin(plugin)` → Fiber; `await fiber.dispose()` |
-| वैकल्पिक सेवा लुकअप | `ctx.get('metrics')?.x()` |
-| लॉगिंग | `ctx.logger(name)` |
-
-जीवनचक्र: `PENDING → LOADING → ACTIVE` (apply में त्रुटि → FAILED); `ACTIVE → UNLOADING → DISPOSED`। आवश्यक सेवा गायब होने पर प्लगइन अनलोड होता है; सेवा लौटने पर पुनः लोड होता है।
-
-## इवेंट डिस्पैच मोड (पाँच, bail सहित)
-
-| मोड | await | क्रम | रिटर्न मान |
-|---|---|---|---|
-| emit | नहीं | पंजीकरण क्रम | कोई नहीं |
-| waterfall | नहीं | पंजीकरण क्रम | हाँ (**`next()` न बुलाना शॉर्ट-सर्किट करता है**) |
-| parallel | हाँ | समानांतर | कोई नहीं |
-| serial | हाँ | पंजीकरण क्रम | हाँ (पहला गैर-खाली रुकता है) |
-| bail | नहीं | पंजीकरण क्रम | हाँ (पहला non-null/false/undefined शॉर्ट-सर्किट करता है और बाकी रोक देता है) |
-
-टाइप्ड इवेंट (declaration merging):
-
-```ts
-declare module '@deepseek-ai/cordis' {
-  interface Events { 'my/event': (p: { id: string }) => void }
-  interface Context { myService: MyService }   // सेवा प्रदान करते समय
-}
-```
-
-## cordis.yml / परतें
-
-```yaml
-# scratch-plugin/cordis.yml (--patch ओवरले)
-- insert:
-    - id: hello
-      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
-      config: { greeting: 'Hi' }
-
-# bundle: package.json में "dsh": {"bundle":{"patch":"./cordis.patch.yml"}}
-# profile: "dsh": {"profile":{"bundles":["@deepseek-ai/dsh-base","my-bundle"]}}
-# प्रभावी क्रम: bundles → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch
-# id से ओवरराइड; पूरी config पंक्ति बदलती है (deep merge नहीं) — हर कुंजी दोबारा लिखें
-# !!js इंजेक्ट की गई सेवाओं के सक्रिय होने पर मूल्यांकित होता है; disabled हर माउंट पर जाँचा जाता है
-```
-
-कमांड: `dsh --profile web` · `dsh --profile headless "task"` · `dsh --profile X --dump-config` · `dsh plugin --profile X add/remove <pkg>` · `pnpm dsh web --patch ./scratch-plugin/cordis.yml`
-
-इंस्टॉल मार्ग (repository-plugin 0811 को हटाया गया — केवल दो बचे):
-- **bundle प्लगइन** (`"dsh":{"bundle":{"patch":"..."}}`) → `dsh plugin add <pkg>` से `dsh.profile.bundles` स्टैक में; पुनः आरंभ पर प्रभावी।
-- **सादा cordis प्लगइन** (बिना `dsh.bundle`) → `dsh plugin add <pkg>` निर्भरता लगाता है + profile के `cordis.patch.yml` में insert पंक्ति; **कॉन्फ़िग HMR लाइव**।
-- git स्रोत: `dsh plugin add "github:owner/repo#<sha>&path:<subdir>"` (commit पिन करें; स्वनिर्भर `prepare` बिल्ड + profile `pnpm-workspace.yaml` allowBuilds; npm/tarball को बिल्ड अनुमति नहीं चाहिए)।
-
-## सामान्य अंतर्निर्मित सेवाएँ (ctx कुंजियाँ)
-
-`sessions` सत्र लॉग · `systemPrompt` प्रॉम्प्ट असेंबली · `tools` टूल रजिस्ट्री + संरक्षित पाइपलाइन · `agents` एजेंट रजिस्ट्री · `agentLoop` लूप ड्राइवर · `llm` मॉडल अडैप्टर रजिस्ट्री · `skills` स्किल रजिस्ट्री · `commands` मानव स्लैश कमांड · `approval` एकबार अनुमोदन · `jobs` पृष्ठभूमि कार्य · `fs` फ़ाइलसिस्टम सीम · `shell` bash निष्पादन सीम · `subprocess` सबप्रोसेस सीम · `terminals` PTY · `sandbox` प्रक्रिया-सीमा सीम · `codeRuntime` कोड निष्पादन · `sessionPersistence` पर्सिस्टेंस · `settings` / `credentials` / `workspaceRegistry` / `goals` / `planMode` / `subagents` / `workflowEngine` / `storage`।
-पूरी सूची व सटीक हस्ताक्षर → `references/official-docs/docs/capability-seams.md` + `docs/subsystems/*.md` (जनरेटेड Cordis API क्षेत्र)।
-
-## टूल नीति पाइपलाइन (निष्पादन क्रम)
-
-```
-tools/pre-execute (waterfall, allow|deny|ask) → ctx.tools.guard() (एकांगी अस्वीकृति)
-→ tools/execute (रैपर; केवल exec.signal बदला जा सकता है) → execute(args, exec)
-→ tools/post-execute (content/value बदलें, ब्लॉक करें, संदर्भ जोड़ें) → finalizeContent
-→ tools/result (केवल अवलोकन) → टिकाऊ tool/result (सत्र इवेंट)
-```
-
-चयन: नीति द्वार → pre-execute; अपील-रहित अस्वीकृति → guard; टाइमआउट/रिट्री/मेट्रिक्स → execute; परिणाम बदलना → post-execute; ऑडिट/संग्रह → result।
-Code Mode: `await tools.<name>(args)` मुफ़्त मिलता है; सफलता = अंतिम कैननिकल JSON मान; विफलता = `ToolCallError(name, toolName, message)`।
-
-## UI कार्ड (शुद्ध फ़ंक्शन! केवल args(+result) — कोई I/O/घड़ी/यादृच्छिक नहीं)
-
-- `presentCall(args)` → `{card:'generic',title,kind?,rawInput?,content?,locations?}` | `{card:'terminal',title,description?,cwd?}` | `{card:'diff',title,diffs,locations?}`
-- `presentResult(args,{content,isError,meta?})` → generic / terminal / diff / search(`shape:'matches'|'paths'`) / read / web(`kind:'search'|'fetch'`)
-- रीप्ले मेटाडेटा: `output.presentationMeta(args, value)` → `tool/result.meta` में संग्रहीत
-
-## त्रि-भूमिका क्षमता सीम (seam) टेम्पलेट
-
-Definition (`dsh-my-cap`): `export abstract class MyCapService extends Service { constructor(ctx){super(ctx,'myCap')} abstract execute(req): Promise<res> }` + Context declaration merging।
-Provider (`dsh-my-cap-local`): `export function apply(ctx){ ctx.plugin(class MyCapLocal extends MyCapService {...}) }`।
-Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(defineTool({... execute: args => ctx.myCap.execute(...)}))`।
-नियम: समय से पहले न बाँटें; Provider और Consumer कभी एक-दूसरे पर निर्भर न हों; डिफ़ॉल्ट स्पष्ट `resolve(request): Spec` में।
-
-## LLM अडैप्टर की अनिवार्य बातें
-
-`class MyAdapter extends LlmAdapter { async *stream(options): AsyncIterable<StreamChunk> }` → `ctx.llm.registerAdapter(['provider'], adapter)`।
-चंक प्रोटोकॉल: `block-start` → `text-delta*` → `block-end` (पूर्ण ब्लॉक) → … → `usage` (finish से पहले) → `finish` (अंतिम; `reason: {kind:'stop'|'tool-calls'}`)। जिन फ़ील्ड को पूरा नहीं कर सकते उनके लिए स्थिर कोड सहित `LlmError` फेंकें।
-
-## कठोर नियम (उल्लंघन = गेट विफलता / गलत व्यवहार)
-
-1. हर पंजीकरण `ctx.effect()` / `ctx.on()` / सेवा के `register()` से हो (disposer लौटाता है)। किसी अन्य context पर पंजीकरण (जैसे `agent.ctx`) के **दो मालिक** होते हैं — उसका disposer अपने effect में भी रखें।
-2. waterfall श्रोताओं को `next()` बुलाना ही होगा; न बुलाना जानबूझकर शॉर्ट-सर्किट है। `agent/pre-step` निर्णय बदलते समय उसे **spread** करें (`{ ...decision, messages }`) ताकि `startsRequestSeries` जैसे फ़ील्ड न खोएँ।
-3. **जो सबसे कमज़ोर mechanism काम करे वही लें**: `ctx.tools.restrict()` (केवल हटाता है) < `ctx.tools.guard()` (केवल मना करता है) < waterfall rewrite (क्रम पर निर्भर) < `system-prompt/assemble` (सब बदल देता है)। अंतिम परिणाम `tools/result` पर देखें; बदलने के लिए ही `tools/post-execute` लें।
-4. मॉडल-दृश्य ⇔ लॉग: नई मॉडल-दृश्य इनपुट के लिए नया सत्र इवेंट चाहिए (`SessionEventMap`) — **होस्ट जोड़ता है**, आप नहीं (नियम 10 देखें)।
-5. समायोज्य मान कभी हार्डकोड न करें (कसौटी: क्या cordis.yml इसे बदल सकता है?); गलत कॉन्फ़िग ज़ोर से विफल हो। लाइव-संपादन योग्य फ़ील्ड `Volatile<T>` + `loader/volatile-update` से (फ़ॉर्म namespace = profile entry id)।
-6. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट (`patch` क्रमबद्ध array हो सकता है); git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें। साझा-इंस्टेंस वाले dsh पैकेज **केवल peerDependencies + devDependencies** में रखें, `dependencies` में कभी नहीं (profile की प्रति runtime को चुपचाप ढक देती है)। ⚠️ सुधार: **peer रेंज इंस्टॉल के समय लागू होती है** — `dsh plugin add` runtime संस्करण की तुलना घोषित `@deepseek-ai/dsh-*` रेंज से करता है और इंस्टॉल अस्वीकार कर देता है; केवल `engines.dsh` घोषणात्मक है और लागू नहीं होता। रेंज बताती है "इंस्टॉल हो सकता है", यह नहीं कि "यह API मौजूद है" — runtime probing रखें (रेंज चयन: `version-matrix.md` §4)।
-7. प्रदर्शन मेटाडेटा ज़रूर भेजें: `locale/*.json` में `meta.title`/`meta.description` और export किया हुआ `./icon` (SVG/PNG/JPEG/WebP, ≤256 KiB, पैकेज के भीतर)। subpath प्लगइन अपना `package.json` **कभी नहीं** पढ़ते।
-8. दस्तावेज़ द्विभाषी जोड़ों में; टूल विवरण/प्रॉम्प्ट ही व्यवहार हैं; गैर-तुच्छ बदलाव में Agent Note चाहिए; पुश से पहले न्यूनतम जाँच सेट चलाएँ (dsh-pre-push-checks)।
-9. सीमाओं के पार अपारदर्शी ids branded होते हैं (`Branded<B>` from `dsh-brand`), कभी भी नंगे `string` नहीं।
-10. **किसी नए `type` के साथ session event कभी न जोड़ें**: `SessionEventMap` सदस्य required-on-read हैं — जो build किसी प्रकार को नहीं जानता वह पूरा log अस्वीकार कर देता है, जब तक उस event पर envelope का `ignorable: true` चिह्न न हो, और चल रहा `Session.append()` वह चिह्न लिख नहीं सकता (उसका तीसरा argument केवल surface events के लिए `SurfaceIntent` है)। अपनी state मौजूदा events से निकालें, या plugin का डेटा inspection से मिली storage service में रखें। केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं (अब `4`; V3→V4 माइग्रेशन tool परिणामों को tool-role संदेशों में उठाता है और संदेश `source` को producer के `source.kind` पर ले जाता है)। `SessionEvent` पर switch अब भी दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
-11. `agent.inject()` का `source` अब सेवानिवृत्त `{ kind: 'plugin', plugin: '<name>' }` wrapper **स्वीकार नहीं करता** — पहले `MessageSourceMap` से अपना kind declare करें। `inject` agent को जगाता नहीं (`followup()`/`steer()` जगाते हैं)।
-12. **सत्र चलते समय profile का `cordis.patch.yml` कभी न लिखें** (HMR उसे reload करता है: जीवित सत्रों से tools गायब हो जाते हैं, चल रहे turn मर जाते हैं, और `session-controller` दोबारा बनाने पर वह पूरी प्रक्रिया restart तक मृत रह सकता है)। profile का `package.json` हाथ से न लिखें, profile डायरेक्टरी में pnpm न चलाएँ।
-13. UI प्लगइन: React को slot में render करें (iframe में सर्व किया पेज कभी नहीं); styling केवल `--dsw-alias-*` theme tokens से; Harness Client पैकेज को `require` कभी न करें (throw करता component पूरा slot खाली कर देता है); `dsh.client.inject` **स्थिर array** होना चाहिए।
-14. प्रदर्शन: per-session state `ctx.sessionProjections` में रखें (शुद्ध synchronous `apply`, अनदेखा करने पर वही reference, शुद्ध JSON + `stateVersion`); durable events की प्रतीक्षा करें (`turn/end`, `assistant/message`, `tool/result`) और live tokens `agent/assistant-stream` से render करें; `agent/status` को कभी poll न करें।
-
-## समुदाय की त्वरित समस्या-सूची (विवरण: गाइड §7.3 / community-repo-deep-dive.md)
-
-- tsconfig तिकड़ी: `moduleResolution: bundler` + `allowImportingTsExtensions` + `rewriteRelativeImportExtensions` (+ `lib:["ES2024"]`, स्पष्ट `types:["node"]`)।
-- त्रुटि पर भी `tsc` आउटपुट देता है → `tsc || exit 1` / `--noEmitOnError`; प्रकाशन से पहले बिल्ड में बचे `.ts` इम्पोर्ट खोजें।
-- Windows junctions PowerShell `New-Item -ItemType Junction` से; vitest ड्राइव अक्षर बड़ा `C:/`।
-- `DSH_PERMISSION_MODE=danger-full-access` उच्च जोखिम है (Windows पर सैंडबॉक्स बैकएंड नहीं, अनुमोदन बंद); `~/.dsh/.env` में `DSH_*` स्टार्टअप तोड़ता है।
-- सत्र फ़ाइलें मल्टी-फ़्रेम zstd हैं: `scanZstdFrames`/`createZstdFrameDecoder` उपयोग करें (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`)।
-- npm: बिना स्कोप वाला `dsh` असंबंधित node-dsh प्रोजेक्ट (एक shell) है — `@deepseek-ai/dsh` इंस्टॉल करें (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.2); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` और `@deepseek-ai/dsh-session-persistence-jsonl` का `latest` अब भी पुराना है (0.0.1-rc.1), इसलिए `next` (0.2.0-rc.2) या `alpha` (0.2.1-alpha.1) पिन करें; `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 और नया टैग `dsh-0-2-1-alpha-1`=4.0.5-alpha.1; dsh-core/dsh-sdk अभी भी अप्रकाशित (2026-10-06 को सत्यापित)।
-- पथ तुलना से पहले दोनों ओर `resolve()` करें (Windows बैकस्लैश जाल)।
-
-## दस्तावेज़ लिंक
-
-आधिकारिक डेव दस्तावेज़ — साइट आधार <https://deepseek-harness.github.io/deepseek-harness> (रूट चीनी, `en/` अंग्रेज़ी; हूबहू स्थानीय प्रतियाँ `references/official-docs/docs/` में):
-
-- मूल बातें: [develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) → [tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) · [config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) · [publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
-- फ़्रेमवर्क: [develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/) ([service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service), [events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events)) · अभ्यास: [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/) ([LLM adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter))
-- गाइड: [quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) · [providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) · [python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk)
-- Cordis: [primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) · [tutorial](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) · [core API](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context)
-- संदर्भ: [architecture](https://deepseek-harness.github.io/deepseek-harness/reference/) · [cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) · [subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)
-- पूर्ण URL ↔ स्थानीय प्रति सूची: [guide/links.md](links.md)
-
-सामुदायिक डेव दस्तावेज़ — टेम्पलेट/ट्यूटोरियल/समस्याएँ, पूरी सूची [references/community-ecosystem.md](../references/community-ecosystem.md) में: [plugin-template](https://github.com/omdsh-dev/plugin-template) · [dsh-plugin-dev pitfalls](https://github.com/omdsh-dev/dsh-plugin-dev) · [from-scratch tutorial](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) · [dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check)
-
-## मुख्य स्रोत सूची
-
-- आधिकारिक दस्तावेज़ हूबहू: `references/official-docs/docs/**` (215 पृष्ठ, `.zh.md` जोड़े सहित)
-- रिपो-रूट बाधाएँ: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; सिंक स्थिति `references/official-docs/SNAPSHOT.md` में
-- साइट क्रॉल HTML: `downloads/web/site/**` (EN+ZH पूर्ण साइट) + `downloads/manifest.tsv`
-- अपस्ट्रीम Cordis: `downloads/github/cordis/**` + शोध `references/upstream-cordis.md`
-- Cordis पेपर: `downloads/github/paper/**` + शोध `references/cordis-paper-and-community.md`
-- वेबसाइट शोध: `references/website-pages.md`
-- रिपो शोध: `references/harness-repo.md`
-- समुदाय/पारिस्थितिकी: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
-- सभी स्रोत URL: `references/sources.md`
-- [संस्करण मैट्रिक्स](version-matrix.md) — चार "latest" मान, जमे हुए `latest` टैग, संगतता-भंग बिंदु और peer रेंज का चयन।
-- [माइग्रेशन सूची](migration-0.2.md) — §0–§12 संगतता-भंग बदलाव, **§13 में `0.2.1-alpha.2` के 19 seams**।

package/guide/quick-reference.md

@@ -1,185 +0,0 @@
-# DeepSeek Harness Plugin Cheat Sheet
-
-> One-page quick reference. Full details: [plugin-dev-guide.md](plugin-dev-guide.md) (Chinese) and [references](../references/).
-> Other languages: [中文](quick-reference.zh-CN.md) · [Español](quick-reference.es.md) · [Português](quick-reference.pt.md) · [हिन्दी](quick-reference.hi.md)
-
-## Plugin skeleton
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'my-plugin'          // required
-export const inject = ['tools']          // required services; omit if none
-
-export interface Config { limit: number }
-export const Config: Schema<Config> = Schema.object({
-  limit: Schema.number().default(10),    // Schemastery schema, not a plain object
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.effect(() => {                     // registration = effect, undone on unload
-    const timer = setInterval(() => {}, 1000)
-    return () => clearInterval(timer)
-  })
-  ctx.on('tools/result', (exec, result) => { /* ... */ })
-  ctx.tools.register(defineTool({
-    name: 'my_tool',
-    description: '…',
-    parameters: { x: { type: 'string', required: true } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) { return `hi ${args.x}` },  // honor exec.signal
-  }))
-}
-```
-
-Other forms: object `export default { name, inject, apply }`; class `class X extends Service { static inject=[...]; constructor(ctx){ super(ctx,'key') } }` (use when providing a service).
-
-## Core ctx API (Cordis)
-
-| Purpose | API |
-|---|---|
-| Register resource + cleanup | `ctx.effect(() => disposer)` |
-| Listen to events | `ctx.on(name, handler)` (auto-cleaned) |
-| Broadcast / no return | `ctx.emit(name, payload)` |
-| Short-circuit value | `ctx.bail(name, input)` (first non-null/false/undefined wins) |
-| Ordered value | `await ctx.serial(name, input)` |
-| Pipeline | `await ctx.waterfall(name, input, init)`; listeners **must call `next()`** |
-| Child contexts | `ctx.extend(meta)` / `ctx.isolate(name, label?)` / `ctx.intercept(name, config)` |
-| Mount child plugin | `ctx.plugin(plugin)` → Fiber; `await fiber.dispose()` |
-| Optional service lookup | `ctx.get('metrics')?.x()` |
-| Logging | `ctx.logger(name)` |
-
-Lifecycle: `PENDING → LOADING → ACTIVE` (apply throws → FAILED); `ACTIVE → UNLOADING → DISPOSED`. A required service disappearing unloads the plugin; it reloads when the service returns.
-
-## Event dispatch modes (five, including bail)
-
-| Mode | awaited | Order | Return value |
-|---|---|---|---|
-| emit | no | registration order | none |
-| waterfall | no | registration order | yes (**not calling next() short-circuits**) |
-| parallel | yes | parallel | none |
-| serial | yes | registration order | yes (first non-empty stops) |
-| bail | no | registration order | yes (first non-null/false/undefined short-circuits and stops the rest) |
-
-Typed events (declaration merging):
-
-```ts
-declare module '@deepseek-ai/cordis' {
-  interface Events { 'my/event': (p: { id: string }) => void }
-  interface Context { myService: MyService }   // when providing a service
-}
-```
-
-## cordis.yml / layering
-
-```yaml
-# scratch-plugin/cordis.yml (--patch overlay)
-- insert:
-    - id: hello
-      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
-      config: { greeting: 'Hi' }
-
-# bundle: "dsh": {"bundle":{"patch":"./cordis.patch.yml"}} in package.json
-# profile: "dsh": {"profile":{"bundles":["@deepseek-ai/dsh-base","my-bundle"]}}
-# effective order: bundles → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch
-# override by id; the whole config row is replaced (no deep merge) — restate every key
-# !!js expressions evaluate after injected services activate; disabled is evaluated on every mount
-```
-
-Commands: `dsh --profile web` · `dsh --profile headless "task"` · `dsh --profile X --dump-config` · `dsh plugin --profile X add/remove <pkg>` · `pnpm dsh web --patch ./scratch-plugin/cordis.yml`
-
-Install channels (repository-plugin removed 0811 — only two remain):
-- **bundle plugin** (`"dsh":{"bundle":{"patch":"..."}}`) → `dsh plugin add <pkg>` enters the `dsh.profile.bundles` stack; takes effect on restart.
-- **plain cordis plugin** (no `dsh.bundle`) → `dsh plugin add <pkg>` installs the dependency + an insert row in the profile `cordis.patch.yml`; **config HMR applies live**.
-- git source: `dsh plugin add "github:owner/repo#<sha>&path:<subdir>"` (pin the commit; self-contained `prepare` build + profile `pnpm-workspace.yaml` allowBuilds; npm/tarball needs no build permission).
-
-## Common built-in services (ctx keys)
-
-`sessions` session log/in-memory store · `systemPrompt` prompt assembly · `tools` tool registry + guarded pipeline · `agents` agent registry · `agentLoop` loop driver · `llm` model adapter registry · `skills` skill registry · `commands` human slash commands · `approval` one-shot approval · `jobs` background jobs · `fs` filesystem seam · `shell` bash execution seam · `subprocess` subprocess seam · `terminals` PTY · `sandbox` process confinement seam · `codeRuntime` code execution · `sessionPersistence` persistence · `settings` / `credentials` / `workspaceRegistry` / `goals` / `planMode` / `subagents` / `workflowEngine` / `storage`.
-Full list + exact signatures → `references/official-docs/docs/capability-seams.md` + `docs/subsystems/*.md` (generated Cordis API regions).
-
-## Tool policy pipeline (execution order)
-
-```
-tools/pre-execute (waterfall, allow|deny|ask) → ctx.tools.guard() (monotonic deny)
-→ tools/execute (wrapper; only exec.signal replaceable) → execute(args, exec)
-→ tools/post-execute (replace content/value, block, attach context) → finalizeContent
-→ tools/result (observe-only) → durable tool/result (session event)
-```
-
-Selection: policy gates → pre-execute; non-appealable deny → guard; timeout/retry/metrics → execute; transforming results → post-execute; audit/collection → result.
-Code Mode: `await tools.<name>(args)` comes free; success = final canonical JSON value; failure = `ToolCallError(name, toolName, message)`.
-
-## UI cards (pure functions! args(+result) only — no I/O/clock/random)
-
-- `presentCall(args)` → `{card:'generic',title,kind?,rawInput?,content?,locations?}` | `{card:'terminal',title,description?,cwd?}` | `{card:'diff',title,diffs,locations?}`
-- `presentResult(args,{content,isError,meta?})` → generic / terminal / diff / search(`shape:'matches'|'paths'`) / read / web(`kind:'search'|'fetch'`)
-- Replay metadata: `output.presentationMeta(args, value)` → persisted in `tool/result.meta`
-
-## Three-role capability seam template
-
-Definition (`dsh-my-cap`): `export abstract class MyCapService extends Service { constructor(ctx){super(ctx,'myCap')} abstract execute(req): Promise<res> }` + Context declaration merging.
-Provider (`dsh-my-cap-local`): `export function apply(ctx){ ctx.plugin(class MyCapLocal extends MyCapService {...}) }`.
-Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(defineTool({... execute: args => ctx.myCap.execute(...)}))`.
-Rules: don't split preemptively; Provider and Consumer never depend on each other; defaults resolve explicitly via `resolve(request): Spec`.
-
-## LLM adapter essentials
-
-`class MyAdapter extends LlmAdapter { async *stream(options): AsyncIterable<StreamChunk> }` → `ctx.llm.registerAdapter(['provider'], adapter)`.
-Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block) → … → `usage` (before finish) → `finish` (last; `reason: {kind:'stop'|'tool-calls'}`). Throw `LlmError` with a stable code for fields you cannot honor.
-
-## Hard rules (violations = gate failures / wrong behavior)
-
-1. Every registration goes through `ctx.effect()` / `ctx.on()` / a service `register()` (returns a disposer). A registration on another context (e.g. `agent.ctx`) has two owners — keep its disposer in your own effect too.
-2. Waterfall listeners must call `next()`; not calling it short-circuits by design. When rewriting an `agent/pre-step` decision, **spread it** (`{ ...decision, messages }`) so fields like `startsRequestSeries` survive.
-3. Weakest mechanism that suffices: `ctx.tools.restrict()` (remove only) < `ctx.tools.guard()` (deny only) < waterfall rewrite (order-dependent) < `system-prompt/assemble` (replaces everything). Observe final outcomes on `tools/result`; use `tools/post-execute` only to transform.
-4. Model-visible ⇔ logged: new model-visible input requires a new session event (`SessionEventMap`) — added by the host, never by appending a new `type` yourself (see rule 8).
-5. Never hardcode tunables (test: can cordis.yml change it?); misconfiguration fails loud. Live-editable user fields use `Volatile<T>` + `loader/volatile-update` (the form namespace is the profile entry id).
-6. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest (`patch` may be an ordered array); git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball. Shared-instance dsh packages go in **peerDependencies + devDependencies only** — never `dependencies` (a profile copy silently shadows the runtime). ⚠️ Corrected: **peer ranges ARE enforced at install time** — `dsh plugin add` compares the runtime version against the declared `@deepseek-ai/dsh-*` range and refuses the install; only `engines.dsh` is declarative and unenforced. A range says "can it install", not "does this API exist" — keep runtime probing (range selection: `version-matrix.md` §4).
-7. Ship display metadata: `locale/*.json` `meta.title`/`meta.description` plus an exported `./icon` (SVG/PNG/JPEG/WebP, ≤256 KiB, inside the package). Subpath plugins never read their own `package.json`.
-8. Bilingual docs in pairs; tool descriptions/prompts are behavior; non-trivial changes need an Agent Note; run the minimal check set before pushing (dsh-pre-push-checks).
-9. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
-10. **Never append a session event with a new `type`.** `SessionEventMap` members are required-on-read: a reader that does not know a type refuses the whole log unless the event carries the envelope's `ignorable: true` marker, and live `Session.append()` cannot set that marker (its third argument is a `SurfaceIntent` for surface events only). Derive your state from existing events, or keep plugin-owned data in a storage service found through inspection. Only structural format changes bump `SESSION_FORMAT_VERSION` (currently `4`; the V3→V4 migration lifts tool results into tool-role messages and moves message sources to producer-owned `source.kind`). Switch over `SessionEvent` still falls through a documented `default` — no `assertNever` (merge-extensible union).
-11. `agent.inject()`'s `source` no longer accepts the retired `{ kind: 'plugin', plugin: '<name>' }` wrapper — declare your own kind through `MessageSourceMap` first. `inject` does not wake the agent (`followup()`/`steer()` do).
-12. Never write a profile `cordis.patch.yml` while sessions run (HMR reloads it: tools vanish from live sessions, in-flight turns die, and a rebuild of `session-controller` can kill it until a full restart). Never hand-write a profile `package.json`; never run pnpm inside the profile directory.
-13. UI plugins: render React in a slot (never an iframe-hosted page); style with `--dsw-alias-*` theme tokens only; never `require` a Harness Client package (a throwing component blanks the slot); `dsh.client.inject` must be a **static array**.
-14. Performance: keep per-session state in `ctx.sessionProjections` (pure synchronous `apply`, same reference when ignored, plain JSON + `stateVersion`); wait on durable events (`turn/end`, `assistant/message`, `tool/result`) and render live tokens from `agent/assistant-stream`; never poll `agent/status`.
-
-## Community pitfalls quick list (details: guide §7.3 / community-repo-deep-dive.md)
-
-- tsconfig trio: `moduleResolution: bundler` + `allowImportingTsExtensions` + `rewriteRelativeImportExtensions` (+ `lib:["ES2024"]`, explicit `types:["node"]`).
-- `tsc` emits despite errors → `tsc || exit 1` / `--noEmitOnError`; grep the build for leftover `.ts` imports before shipping.
-- Windows junctions via PowerShell `New-Item -ItemType Junction`; vitest drive letter must be uppercase `C:/`.
-- `DSH_PERMISSION_MODE=danger-full-access` is high-risk (no sandbox backend on Windows, approvals disabled); `DSH_*` vars in `~/.dsh/.env` break startup.
-- Session files are multi-frame zstd: use `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: unscoped `dsh` is the unrelated node-dsh shell — install `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.2); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` and `@deepseek-ai/dsh-session-persistence-jsonl` still ship a stale `latest` (0.0.1-rc.1), so pin `next` (0.2.0-rc.2) or `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 with a new `dsh-0-2-1-alpha-1` tag at 4.0.5-alpha.1; dsh-core/dsh-sdk still unpublished (verified 2026-10-06).
-- `resolve()` both sides before path comparisons (Windows backslash trap).
-
-## Documentation links
-
-Official dev docs — site base <https://deepseek-harness.github.io/deepseek-harness> (root = Chinese, `en/` = English; verbatim local copies under `references/official-docs/docs/`):
-
-- Basics: [develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) → [tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) · [config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) · [publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
-- Framework: [develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/) ([service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service), [events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events)) · Practice: [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/) ([LLM adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter))
-- Guides: [quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) · [providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) · [python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk)
-- Cordis: [primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) · [tutorial](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) · [core API](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context)
-- Reference: [architecture](https://deepseek-harness.github.io/deepseek-harness/reference/) · [cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) · [subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)
-- Full URL ↔ local-copy index: [guide/links.md](links.md)
-
-Community dev docs — templates/tutorials/pitfalls, full list in [references/community-ecosystem.md](../references/community-ecosystem.md): [plugin-template](https://github.com/omdsh-dev/plugin-template) · [dsh-plugin-dev pitfalls](https://github.com/omdsh-dev/dsh-plugin-dev) · [from-scratch tutorial](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) · [dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check)
-
-## Key source index
-
-- Official docs verbatim: `references/official-docs/docs/**` (429 md pages, all 212 `.zh.md` pairs included, mirror at `dsh-v0.2.1-alpha.2`); the pages **not on the documentation site** (session-format-status, `upgrade-guide/**`, `persistence-changes/**`, ui-radius, web-styling, module-graph) are listed in [links.md](links.md) §2.1
-- Migration checklist: [migration-0.2.md](migration-0.2.md) — §0–§12 cover every breaking change from `0.1.6-alpha.2` → `0.2.1-alpha.1`, and §13 covers `0.2.1-alpha.1` → `0.2.1-alpha.2` as 19 citable seams (`L1`–`L19`); each entry cites its official upgrade-guide source
-- The official in-repo plugin-development skill: [references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md)
-- Repo-root constraints: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; sync state in `references/official-docs/SNAPSHOT.md`
-- Site crawl HTML: `downloads/web/site/**` (EN+ZH full site) + `downloads/manifest.tsv` (download ledger)
-- Upstream Cordis: `downloads/github/cordis/**` + research `references/upstream-cordis.md`
-- Cordis paper: `downloads/github/paper/**` + research `references/cordis-paper-and-community.md`
-- Website research: `references/website-pages.md`
-- Repo research: `references/harness-repo.md`
-- Community/ecosystem: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
-- All source URLs: `references/sources.md`