dsh-plugin-guide 0.1.0

package/guide/quick-reference.es.md

@@ -0,0 +1,176 @@
+# 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 + 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) |
+
+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).
+2. Los listeners de waterfall deben llamar `next()`; no llamarlo cortocircuita por diseño.
+3. Visible-para-el-modelo ⇔ registrado: una nueva entrada visible requiere un nuevo evento de sesión (`SessionEventMap`).
+4. Nunca codifiques valores ajustables (prueba: ¿puede cambiarlos cordis.yml?); la mala configuración falla en voz alta.
+5. 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`; instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball.
+6. 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).
+7. Los ids opacos entre límites son branded (`Branded<B>` de `dsh-brand`), nunca `string` pelado.
+8. Los miembros de `SessionEventMap` son required-on-read: los eventos de tipo desconocido deben llevar `ignorable: true` (o el log se rechaza); solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION`. El switch sobre `SessionEvent` cae por un `default` documentado — sin `assertNever` (unión merge-extensible).
+
+## 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`; `@deepseek-ai/dsh-tools` y `@deepseek-ai/dsh-session-persistence-jsonl` tienen `latest` obsoleto (0.0.1-rc.1), fija `next` (0.1.0-rc.6); `create-dsh-plugin` ya está publicado (0.1.1, 2026-08-13); dsh-core/dsh-sdk siguen sin publicarse (verificado 2026-08-14).
+- 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/examples/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`

package/guide/quick-reference.hi.md

@@ -0,0 +1,176 @@
+# 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 | हाँ | पंजीकरण क्रम | हाँ (पहला गैर-खाली रुकता है) |
+
+टाइप्ड इवेंट (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 लौटाता है)।
+2. waterfall श्रोताओं को `next()` बुलाना ही होगा; न बुलाना जानबूझकर शॉर्ट-सर्किट है।
+3. मॉडल-दृश्य ⇔ लॉग: नई मॉडल-दृश्य इनपुट के लिए नया सत्र इवेंट चाहिए (`SessionEventMap`)।
+4. समायोज्य मान कभी हार्डकोड न करें (कसौटी: क्या cordis.yml इसे बदल सकता है?); गलत कॉन्फ़िग ज़ोर से विफल हो।
+5. स्वतंत्र प्लगइन पैकेज: cordis peerDependency है और होस्ट पहचान से मेल खाना चाहिए (scoped `@deepseek-ai/cordis` और unscoped मिलाना पहचान बाँट देता है); ESM; `dsh.bundle` मैनिफ़ेस्ट; git इंस्टॉल को `prepare` + `allowBuilds` चाहिए; `lib/` या tarball प्रकाशित करें।
+6. दस्तावेज़ द्विभाषी जोड़ों में; टूल विवरण/प्रॉम्प्ट ही व्यवहार हैं; गैर-तुच्छ बदलाव में Agent Note चाहिए; पुश से पहले न्यूनतम जाँच सेट चलाएँ (dsh-pre-push-checks)।
+7. सीमाओं के पार अपारदर्शी ids branded होते हैं (`Branded<B>` from `dsh-brand`), कभी भी नंगे `string` नहीं।
+8. `SessionEventMap` सदस्य required-on-read हैं: अज्ञात प्रकार के इवेंट पर `ignorable: true` होना चाहिए (वरना log अस्वीकृत); केवल संरचनात्मक प्रारूप बदलाव ही `SESSION_FORMAT_VERSION` bump करते हैं। `SessionEvent` पर switch दस्तावेज़ित `default` में गिरता है — `assertNever` नहीं (merge-extensible union)।
+
+## समुदाय की त्वरित समस्या-सूची (विवरण: गाइड §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` इंस्टॉल करें; `@deepseek-ai/dsh-tools` और `@deepseek-ai/dsh-session-persistence-jsonl` का `latest` पुराना है (0.0.1-rc.1), `next` (0.1.0-rc.6) पिन करें; `create-dsh-plugin` अब प्रकाशित है (0.1.1, 2026-08-13); dsh-core/dsh-sdk अभी भी अप्रकाशित (2026-08-14 को सत्यापित)।
+- पथ तुलना से पहले दोनों ओर `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/examples/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`

package/guide/quick-reference.md

@@ -0,0 +1,176 @@
+# 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 + 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) |
+
+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).
+2. Waterfall listeners must call `next()`; not calling it short-circuits by design.
+3. Model-visible ⇔ logged: new model-visible input requires a new session event (`SessionEventMap`).
+4. Never hardcode tunables (test: can cordis.yml change it?); misconfiguration fails loud.
+5. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest; git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball.
+6. 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).
+7. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
+8. `SessionEventMap` members are required-on-read: unknown event types must carry `ignorable: true` (or the log is refused); only structural format changes bump `SESSION_FORMAT_VERSION`. Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
+
+## 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`; `@deepseek-ai/dsh-tools` and `@deepseek-ai/dsh-session-persistence-jsonl` have stale `latest` (0.0.1-rc.1), pin `next` (0.1.0-rc.6); `create-dsh-plugin` is now published (0.1.1, 2026-08-13); dsh-core/dsh-sdk still unpublished (verified 2026-08-14).
+- `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/**` (215 pages, all `.zh.md` pairs included)
+- Repo-root constraints: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/examples/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`