dsh-observe 0.2.27 → 0.2.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +0 -0
  2. package/LICENSE +0 -0
  3. package/README.en.md +446 -0
  4. package/README.es.md +446 -0
  5. package/README.hi.md +446 -0
  6. package/README.md +292 -196
  7. package/README.pt.md +446 -0
  8. package/THIRD_PARTY_NOTICES.md +0 -0
  9. package/cordis.patch.yml +6 -1
  10. package/lib/index.js +72 -10
  11. package/lib/typert.host.js +0 -0
  12. package/lib/types/backoff.d.ts +0 -0
  13. package/lib/types/backoff.d.ts.map +0 -0
  14. package/lib/types/backoff.js +0 -0
  15. package/lib/types/backoff.js.map +0 -0
  16. package/lib/types/collector.d.ts +0 -0
  17. package/lib/types/collector.d.ts.map +1 -1
  18. package/lib/types/collector.js +22 -2
  19. package/lib/types/collector.js.map +1 -1
  20. package/lib/types/config.d.ts +9 -0
  21. package/lib/types/config.d.ts.map +1 -1
  22. package/lib/types/config.js +3 -1
  23. package/lib/types/config.js.map +1 -1
  24. package/lib/types/ids.d.ts +0 -0
  25. package/lib/types/ids.d.ts.map +0 -0
  26. package/lib/types/ids.js +0 -0
  27. package/lib/types/ids.js.map +0 -0
  28. package/lib/types/index.d.ts +0 -0
  29. package/lib/types/index.d.ts.map +0 -0
  30. package/lib/types/index.js +0 -0
  31. package/lib/types/index.js.map +0 -0
  32. package/lib/types/model.d.ts +6 -0
  33. package/lib/types/model.d.ts.map +1 -1
  34. package/lib/types/model.js +0 -0
  35. package/lib/types/model.js.map +1 -1
  36. package/lib/types/pipeline.d.ts +0 -0
  37. package/lib/types/pipeline.d.ts.map +0 -0
  38. package/lib/types/pipeline.js +0 -0
  39. package/lib/types/pipeline.js.map +0 -0
  40. package/lib/types/pricing.d.ts +0 -0
  41. package/lib/types/pricing.d.ts.map +0 -0
  42. package/lib/types/pricing.js +0 -0
  43. package/lib/types/pricing.js.map +0 -0
  44. package/lib/types/project.d.ts +22 -0
  45. package/lib/types/project.d.ts.map +1 -1
  46. package/lib/types/project.js +57 -0
  47. package/lib/types/project.js.map +1 -1
  48. package/lib/types/remote.d.ts +0 -0
  49. package/lib/types/remote.d.ts.map +0 -0
  50. package/lib/types/remote.js +0 -0
  51. package/lib/types/remote.js.map +0 -0
  52. package/lib/types/sanitize.d.ts +0 -0
  53. package/lib/types/sanitize.d.ts.map +0 -0
  54. package/lib/types/sanitize.js +0 -0
  55. package/lib/types/sanitize.js.map +0 -0
  56. package/lib/types/sinks.d.ts +0 -0
  57. package/lib/types/sinks.d.ts.map +1 -1
  58. package/lib/types/sinks.js +22 -3
  59. package/lib/types/sinks.js.map +1 -1
  60. package/lib/types/spool.d.ts +0 -0
  61. package/lib/types/spool.d.ts.map +0 -0
  62. package/lib/types/spool.js +0 -0
  63. package/lib/types/spool.js.map +0 -0
  64. package/lib/types/typert.host.d.ts +0 -0
  65. package/lib/types/typert.host.d.ts.map +0 -0
  66. package/lib/types/typert.host.js +0 -0
  67. package/lib/types/typert.host.js.map +0 -0
  68. package/lib/types/version.d.ts +1 -1
  69. package/lib/types/version.d.ts.map +0 -0
  70. package/lib/types/version.js +1 -1
  71. package/lib/types/version.js.map +0 -0
  72. package/lib/types/wire.d.ts +0 -0
  73. package/lib/types/wire.d.ts.map +0 -0
  74. package/lib/types/wire.js +0 -0
  75. package/lib/types/wire.js.map +0 -0
  76. package/package.json +33 -14
  77. package/src/backoff.ts +0 -0
  78. package/src/collector.ts +26 -2
  79. package/src/config.ts +12 -1
  80. package/src/ids.ts +0 -0
  81. package/src/index.ts +0 -0
  82. package/src/model.ts +6 -0
  83. package/src/pipeline.ts +0 -0
  84. package/src/pricing.ts +0 -0
  85. package/src/project.ts +58 -0
  86. package/src/remote.ts +0 -0
  87. package/src/sanitize.ts +0 -0
  88. package/src/sinks.ts +22 -3
  89. package/src/spool.ts +0 -0
  90. package/src/typert.host.ts +0 -0
  91. package/src/version.ts +1 -1
  92. package/src/wire.ts +0 -0
  93. package/README-es.md +0 -354
  94. package/README-hi.md +0 -354
  95. package/README-pt.md +0 -354
  96. package/README-zh.md +0 -354
package/README.pt.md ADDED
@@ -0,0 +1,446 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-observe-hero-en-dark.webp">
5
+ <img src="docs/assets/dsh-observe-hero-en-light.webp" width="100%" alt="dsh-observe: à esquerda o nome, as frases de valor e o comando de instalação; à direita a cascata de um trace de um turn — spans de turn, step, ferramenta e LLM num eixo temporal, contagens de tokens nas barras LLM e uma faixa de métricas de spans, tokens, custo em USD e pressão de contexto; o cartão indica que o saneamento ocorre antes da fila e nomeia OTLP e Langfuse como destinos">
6
+ </picture>
7
+
8
+ # dsh-observe
9
+
10
+ **Transforme cada sessão em traces OTLP padrão e observações do Langfuse—saneado antes de sair, sem exportar nada por padrão.**
11
+
12
+ Exportador de observabilidade para o DeepSeek Harness: spans de turn/step/chamada de ferramenta/geração LLM, métricas de tokens e custo em USD, lotes assíncronos, buffer offline limitado e novas tentativas com backoff exponencial; use OTLP, Langfuse ou ambos.
13
+
14
+ [Instalar](#instalação-em-três-passos) · [Configuração](#configuração) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
15
+
16
+ [![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
17
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.2.1%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibilidade)
18
+ [![npm](https://img.shields.io/npm/v/dsh-observe?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-observe)
19
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-observe/ci.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-observe/actions/workflows/ci.yml)
20
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibilidade)
21
+
22
+ [![Stars](https://img.shields.io/github/stars/PerryLink/dsh-observe?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-observe/stargazers)
23
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-observe?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-observe)
24
+ [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-observe?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-observe?ref=badge)
25
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-observe/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-observe)
26
+ [![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
27
+ [![Gitee](https://img.shields.io/badge/Gitee-mirror-C71D23?style=flat-square&labelColor=2B3245&logo=gitee)](https://gitee.com/perrylink/dsh-observe)
28
+
29
+ ```sh
30
+ dsh plugin --profile <name> add dsh-observe
31
+ ```
32
+
33
+ </div>
34
+
35
+ <sub>Plugin da comunidade, não afiliado ao DeepSeek. Repositório único: <https://github.com/PerryLink/dsh-observe> (o Gitee é um espelho).</sub>
36
+
37
+ ## O que é
38
+
39
+ O `dsh-observe` traduz o fluxo `session/event` do harness em protocolos de observabilidade padrão: um trace por turn, um span para cada step, chamada de ferramenta e geração LLM, métricas acumuladas de tokens e custo, e corpos de prompt/completion que são saneados e truncados antes de entrar na fila. Ele só exporta: não registra ferramentas de modelo nem comandos visíveis ao usuário, e todo o comportamento vem da configuração. Configure OTLP ou Langfuse, reinicie, e os dados fluem sozinhos; sem configuração nada é coletado.
40
+
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-observe-flow-v5-dark.svg">
43
+ <img src="docs/assets/dsh-observe-flow-v5-light.svg" width="100%" alt="Estrutura do dsh-observe (uma bifurcação em duas canalizações em torno de um buffer limitado): session/event alimenta o collector (spans turn/step/tool/llm e métricas observe.tokens, observe.cost e observe.context_tokens, ids sha256 determinísticos), depois sanitize (redação por nome de chave, padrões de segredos embutidos e orçamentos de prompt/completion 4000 e ferramenta 2000/2000) sanea cada registro antes de qualquer fila; o registro bifurca em duas canalizações independentes, otlp e langfuse, cada uma com fila (256 registros ou 5000ms, maxQueueRecords 2000) → flush/retry (5 tentativas, 1000ms × 2 com teto de 60000ms) → seu endpoint; o esgotamento de tentativas e o transbordo da fila caem no buffer durável e limitado entre as pistas (10000 registros, expulsão do mais antigo, revalidação zod na leitura, sobrevive ao reinício), esvaziado de volta para ambos os endpoints a cada 30000ms pelo trilho tracejado da direita; embaixo à esquerda fica a superfície remota opcional observe/status e observe/setEnabled, e a faixa inferior fixa o contrato de desligado por padrão e os três eventos escutados">
44
+ </picture>
45
+
46
+ ## Instalação em três passos
47
+
48
+ 1. **Instalar** (escolha uma):
49
+
50
+ ```sh
51
+ # canal git (main mais recente; o script prepare compila só com dependências de produção)
52
+ dsh plugin --profile web add github:PerryLink/dsh-observe
53
+ # canal npm (versão publicada)
54
+ dsh plugin --profile web add dsh-observe
55
+ # canal tarball: após pnpm pack neste repositório
56
+ dsh plugin --profile web add ./dsh-observe-<version>.tgz
57
+ ```
58
+
59
+ > Se o pnpm reportar `ERR_PNPM_IGNORED_BUILDS` para este pacote (validação inofensiva do binário de plataforma do esbuild), adicione `allowBuilds: { esbuild: true }` ao seu `pnpm-workspace.yaml`; a CLI `dsh` imprime o trecho exato.
60
+
61
+ 2. **Configuração mínima** (ative `enabled` no patch do perfil e configure ao menos um backend; a linha vem desativada no `cordis.patch.yml`):
62
+
63
+ ```yaml
64
+ - insert:
65
+ - id: dsh-observe
66
+ name: dsh-observe
67
+ config:
68
+ enabled: true
69
+ otlp:
70
+ endpoint: http://localhost:4318
71
+ ```
72
+
73
+ O Langfuse funciona igual: `langfuse.baseUrl` + `langfuse.publicKey` + `langfuse.secretKey`. Os dois backends podem ficar ativos ao mesmo tempo.
74
+
75
+ 3. **Verificar que está ativo**:
76
+
77
+ ```sh
78
+ dsh --profile web --dump-config | grep -A2 'id: dsh-observe'
79
+ ```
80
+
81
+ Nenhum comando visível ao usuário é registrado, então não existe gatilho manual do tipo `/observe`. Com `remote.enabled: true`, uma página de ajustes pode ler os backends configurados, a profundidade das filas e a ocupação do buffer via `observe/status`.
82
+
83
+ **Desinstalar**: `dsh plugin --profile web remove dsh-observe` (ou remova a linha do patch do perfil).
84
+
85
+ <details>
86
+ <summary>Instalar pelo mercado do DSH Desktop</summary>
87
+
88
+ Todos os plugins da PerryLink podem ser navegados no mercado embutido do DSH Desktop: **Mercado → Fontes → adicionar fonte → colar** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ selecionar**. A instalação continua passando pela verificação de identidade npm do mercado e pela sua confirmação.
89
+
90
+ </details>
91
+
92
+ ## Capacidades principais
93
+
94
+ O `dsh-observe` converte o fluxo de eventos de sessão em protocolos de observabilidade padrão:
95
+
96
+ - **Spans** — turn, step, chamada de ferramenta (duração, status, derivação de tentativas) e geração LLM, encadeados em traces por turn com ids determinísticos.
97
+ - **Métricas** — contadores de tokens por provider/model, contadores de custo em USD (tabela de preços configurável) e o gauge opcional de pressão de contexto do `ctx.tokenMeter`.
98
+ - **Captura saneada** — os corpos de prompt e completion passam por redação estrutural de nomes de chave, padrões de segredo embutidos, seus padrões e orçamentos de caracteres antes de entrar na fila ou serem enviados.
99
+ - **Confiabilidade** — lotes assíncronos (por tamanho e por temporizador), buffer offline durável e limitado (storage-domain, expulsão do mais antigo primeiro) e novas tentativas determinísticas com backoff exponencial; lotes não entregues sobrevivem ao reinício.
100
+ - **Interruptor em tempo real** — o remote Typert opcional (`observe/status`, `observe/setEnabled`) deixa uma página de ajustes parar e retomar a exportação sem desmontar o plugin.
101
+ - **Desativado por padrão** — `enabled: true` mais ao menos um backend é a ativação explícita; sem isso nada é coletado nem exportado.
102
+
103
+ ```text
104
+ fluxo session/event
105
+ │ collector (spans turn/step/tool/llm, métricas)
106
+ │ sanitize (chaves, segredos, orçamentos)
107
+ ├──▶ pipeline "otlp" ── fila ── flush ──▶ OTLP /v1/traces + /v1/metrics
108
+ │ └─ retry/backoff ─┐
109
+ ├──▶ pipeline "langfuse" ── fila ── flush ──▶ ingestão do Langfuse
110
+ │ └─ retry/backoff ─┤
111
+ └────────── spool durável (buffer offline, limitado) ◀┘
112
+ ```
113
+
114
+ ### Superfícies
115
+
116
+ Este plugin **não registra ferramentas de modelo** nem comandos visíveis ao usuário: é um exportador em segundo plano. Toda a superfície são três coisas:
117
+
118
+ - **Consome** `session/event` (coleta de spans e métricas), `session/flush` (um empurrão de exportação de melhor esforço — o ponto de durabilidade nunca espera por um backend remoto) e `session/disposed`.
119
+ - **Serviço remoto opcional** `observe` (`remote.enabled`, desativado por padrão) — `observe/status` devolve o estado do interruptor, os backends configurados, a profundidade das filas e a ocupação do buffer; `observe/setEnabled` para e retoma a exportação em tempo de execução.
120
+ - **A única chave de serviço injetada** `storageDomain`, usada pela tabela durável do buffer offline.
121
+
122
+ ### Exemplos
123
+
124
+ Não há gatilho manual: depois de instalar, ative `enabled` com a configuração mínima acima e reinicie; os traces e as métricas aparecem no backend OTLP e as observações no Langfuse. Para confirmar que está coletando, veja o primeiro trace que o backend recebe; para confirmar que está enviando, acompanhe a profundidade de fila do `observe/status` caindo conforme a sessão avança.
125
+
126
+ ## Configuração
127
+
128
+ Todas as opções são campos `Config` do Schemastery (alteráveis no cordis.yml ou no patch do perfil). Uma sobrescrita por id substitui a linha inteira: redeclare todas as chaves necessárias. O [`cordis.patch.yml`](cordis.patch.yml) documenta cada chave em linha.
129
+
130
+ Chaves mais usadas:
131
+
132
+ | Chave | Padrão | Significado |
133
+ |---|---|---|
134
+ | `enabled` | `false` | Interruptor mestre; `true` mais ao menos um backend é a ativação explícita |
135
+ | `otlp.endpoint` | *(obrigatório)* | URL base do OTLP; o plugin acrescenta `/v1/traces` e `/v1/metrics` |
136
+ | `otlp.serviceName` | `deepseek-harness` | Atributo de recurso `service.name` |
137
+ | `langfuse.baseUrl` | `https://cloud.langfuse.com` | URL base do Langfuse |
138
+ | `langfuse.traceName` | `session {session} turn {turn}` | Template do nome do trace; `{session}`/`{turn}` são interpolados por trace |
139
+ | `capture.llm` | `true` | Spans de geração LLM |
140
+ | `llm.prompt` | `true` | Captura o prompt da requisição já saneado (`false` = só tamanhos) |
141
+ | `llm.reasoning` | `true` | Captura o raciocínio separadamente como `gen_ai.completion.reasoning` (`false` = só a resposta) |
142
+ | `batch.maxBufferRecords` | `10000` | Limite do buffer offline durável; os registros mais antigos caem primeiro |
143
+ | `remote.enabled` | `false` | Monta o remote Typert `observe` (interruptor em tempo real) |
144
+
145
+ <details>
146
+ <summary>Tabela completa de configuração (48 chaves)</summary>
147
+
148
+ | Chave | Padrão | Significado |
149
+ |---|---|---|
150
+ | `enabled` | `false` | Interruptor mestre; `true` mais ao menos um backend é a ativação explícita |
151
+ | `otlp` | `null` | Configuração do backend OTLP; `null` o desativa |
152
+ | `otlp.endpoint` | *(obrigatório)* | URL base do OTLP; o plugin acrescenta `/v1/traces` e `/v1/metrics` |
153
+ | `otlp.serviceName` | `deepseek-harness` | Atributo de recurso `service.name` |
154
+ | `otlp.serviceVersion` | *(nenhum)* | Atributo de recurso `service.version` |
155
+ | `otlp.headers` | `{}` | Cabeçalhos extras mesclados em cada requisição de exportação |
156
+ | `otlp.timeoutMs` | `10000` | Tempo limite por requisição |
157
+ | `langfuse` | `null` | Configuração do backend Langfuse; `null` o desativa |
158
+ | `langfuse.baseUrl` | `https://cloud.langfuse.com` | URL base do Langfuse |
159
+ | `langfuse.publicKey` | *(obrigatório)* | Chave pública do projeto |
160
+ | `langfuse.secretKey` | *(obrigatório)* | Chave secreta do projeto |
161
+ | `langfuse.release` | *(nenhum)* | Etiqueta de release carimbada nos traces |
162
+ | `langfuse.traceName` | `session {session} turn {turn}` | Template do nome do trace; `{session}`/`{turn}` são interpolados por trace |
163
+ | `langfuse.tags` | `[]` | Etiquetas estáticas carimbadas em cada trace |
164
+ | `langfuse.timeoutMs` | `10000` | Tempo limite por requisição |
165
+ | `capture.turns` | `true` | Spans de ciclo de vida do turn |
166
+ | `capture.steps` | `true` | Spans de ciclo de vida do step |
167
+ | `capture.tools` | `true` | Spans de chamada de ferramenta com argumentos/resultados saneados |
168
+ | `capture.llm` | `true` | Spans de geração LLM |
169
+ | `llm.prompt` | `true` | Captura o prompt da requisição já saneado (`false` = só tamanhos) |
170
+ | `llm.completion` | `true` | Captura a completion já saneada (`false` = só tamanhos) |
171
+ | `llm.reasoning` | `true` | Captura o raciocínio separadamente como `gen_ai.completion.reasoning` (`false` = só a resposta) |
172
+ | `metadata.sessionId` | `true` | Atributo do id da sessão |
173
+ | `metadata.cwd` | `false` | Diretório de trabalho da sessão (um caminho local; desativado por padrão) |
174
+ | `metadata.agentPreset` | `true` | Atributo do id do preset de agente |
175
+ | `metadata.model` | `true` | Atributos de provider/model |
176
+ | `metrics.tokens` | `true` | Contadores de tokens por provider/model |
177
+ | `metrics.cost` | `true` | Contadores de custo em USD (precisam de regras `pricing` que casem) |
178
+ | `metrics.contextTokens` | `true` | Gauge de pressão de contexto (precisa de `ctx.tokenMeter`) |
179
+ | `pricing` | `[]` | Tabela de preços, vence a primeira correspondência: `{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? }` |
180
+ | `sanitize.enabled` | `true` | Interruptor mestre da redação (`false` desativa a redação, nunca o truncamento) |
181
+ | `sanitize.redactKeys` | `[]` | Substrings extras de nomes de chave (key/token/secret/password/authorization/credential/apiKey sempre entram) |
182
+ | `sanitize.redactPatterns` | `[]` | Expressões regulares extras de segredo |
183
+ | `sanitize.truncatePromptChars` | `4000` | Orçamento de caracteres do prompt |
184
+ | `sanitize.truncateCompletionChars` | `4000` | Orçamento de caracteres da completion |
185
+ | `sanitize.truncateToolInputChars` | `2000` | Orçamento de caracteres dos argumentos de ferramenta |
186
+ | `sanitize.truncateToolOutputChars` | `2000` | Orçamento de caracteres do resultado de ferramenta |
187
+ | `sanitize.truncateAttributeChars` | `512` | Orçamento da string de atributo de span |
188
+ | `batch.maxRecords` | `256` | Esvazia a fila quando ela tem este número de registros |
189
+ | `batch.flushIntervalMs` | `5000` | Intervalo do temporizador de flush |
190
+ | `batch.maxQueueRecords` | `2000` | Limite da fila em memória; o excesso transborda para o buffer |
191
+ | `batch.maxBufferRecords` | `10000` | Limite do buffer offline durável; os registros mais antigos caem primeiro |
192
+ | `batch.bufferRetryIntervalMs` | `30000` | Intervalo de nova tentativa do buffer offline |
193
+ | `retry.maxAttempts` | `5` | Tentativas por lote, incluindo a primeira |
194
+ | `retry.baseDelayMs` | `1000` | Primeiro atraso de backoff |
195
+ | `retry.factor` | `2` | Multiplicador de backoff por falha consecutiva |
196
+ | `retry.maxDelayMs` | `60000` | Teto do backoff |
197
+ | `remote.enabled` | `false` | Monta o remote Typert `observe` (interruptor em tempo real) |
198
+
199
+ </details>
200
+
201
+ > ⚠️ **Aviso de conformidade sobre o raciocínio** — `llm.reasoning` vem ativado por padrão e o raciocínio é exportado separadamente como `gen_ai.completion.reasoning` (nunca dentro de `gen_ai.completion`; no Langfuse ele vai nos metadados da generation). A cadeia de pensamento pode conter a entrada original do usuário ou contexto que o modelo cita literalmente, então **avalie o impacto de conformidade antes de exportá-la**. Defina `llm.reasoning: false` para omiti-la; `llm.completion: false` descarta tanto a resposta quanto o raciocínio.
202
+
203
+ Exemplo de sobrescrita por id (substitui a linha inteira, então redeclare as chaves necessárias):
204
+
205
+ ```yaml
206
+ - insert:
207
+ - id: dsh-observe
208
+ name: dsh-observe
209
+ config:
210
+ enabled: true
211
+ otlp:
212
+ endpoint: http://localhost:4318
213
+ capture:
214
+ tools: false
215
+ sanitize:
216
+ truncatePromptChars: 2000
217
+ batch:
218
+ maxBufferRecords: 20000
219
+ ```
220
+
221
+ ## FAQ
222
+
223
+ <details>
224
+ <summary>O prompt ou os argumentos de ferramenta em texto puro chegam ao backend?</summary>
225
+
226
+ Não em texto puro. Cada registro é saneado antes de entrar na fila, em três camadas: nomes de chave estruturais (key/token/secret/password/authorization/credential/apiKey sempre na lista, e `sanitize.redactKeys` acrescenta substrings), padrões de segredo embutidos (chaves de API, tokens do GitHub, chaves da AWS, credenciais bearer, chaves privadas) mais suas expressões `sanitize.redactPatterns`, e truncamento por orçamento de caracteres (prompt/completion 4000 cada, argumentos e resultados de ferramenta 2000 cada, atributos de span 512). Se você quer só tamanhos sem corpos, defina `llm.prompt` e `llm.completion` como `false` e os registros passam a levar apenas tamanhos e contagens.
227
+
228
+ </details>
229
+
230
+ <details>
231
+ <summary>Perco dados se o backend cair ou a rede oscilar?</summary>
232
+
233
+ Spans e métricas seguem a cadeia de nova tentativa → transbordo: um lote com falha é repetido com backoff exponencial determinístico (`retry.maxAttempts` 5 por padrão, `retry.baseDelayMs × retry.factor`), e quando as tentativas se esgotam ou a fila em memória passa de `batch.maxQueueRecords` ele transborda para o spool durável limitado (`batch.maxBufferRecords` 10000 por padrão, mais antigos primeiro), com drenagem periódica em `batch.bufferRetryIntervalMs`, então lotes não entregues sobrevivem a um reinício. As métricas OTLP são a exceção: são agregadas de forma cumulativa e um flush perdido se recupera no seguinte.
234
+
235
+ </details>
236
+
237
+ <details>
238
+ <summary>O que o plugin guarda e onde ficam as credenciais?</summary>
239
+
240
+ O buffer offline guarda apenas registros saneados, e o que é lido de volta do armazenamento é validado outra vez antes de chegar a um sink. O plugin não guarda credenciais: as chaves pública/secreta do Langfuse aparecem só em requisições ao endpoint do Langfuse que você configurar, e os cabeçalhos OTLP vão só para o seu endpoint OTLP; mantenha-as em referências de credenciais ou valores injetados por ambiente, nunca em um patch de perfil versionado. Ele só lê o fluxo de eventos ao vivo e jamais lê ou reescreve os arquivos de log da sessão.
241
+
242
+ </details>
243
+
244
+ <details>
245
+ <summary>Isso deixa a sessão mais lenta?</summary>
246
+
247
+ A coleta e o saneamento rodam de forma síncrona no manipulador de eventos, mas o envio é totalmente assíncrono: a fila é esvaziada por tamanho ou por temporizador, e `session/flush` é apenas um empurrão de melhor esforço — o ponto de durabilidade nunca espera por um backend remoto. Falhas de exportação avisam, contam (`observe.export_failures`), repetem e por fim caem no spool; uma falha do manipulador de `session/event` é capturada e registrada, então a observabilidade nunca quebra o caminho quente do harness.
248
+
249
+ </details>
250
+
251
+ <details>
252
+ <summary>Ele disputa serviços, eventos ou slots com outros plugins?</summary>
253
+
254
+ Ele injeta uma chave de serviço (`storageDomain`), escuta três eventos `session/*` e não registra ferramentas de modelo, nem comandos, nem slots de cliente, nem listeners de waterfall, nem reescritas globais. A única superfície de nomes a observar é o serviço remoto opcional `observe` (`remote.enabled` vem desativado): se outro plugin do mesmo perfil ocupar esse nome, ative apenas um deles.
255
+
256
+ </details>
257
+
258
+ ## Limites de segurança
259
+
260
+ - **Desativado por padrão** — nada é coletado nem exportado a menos que você ative explicitamente (`enabled: true` mais ao menos um backend).
261
+ - **Saneamento antes do envio** — redação estrutural de chaves, padrões de segredo embutidos (chaves de API, tokens do GitHub, chaves da AWS, credenciais bearer, chaves privadas), seus padrões e orçamentos de caracteres se aplicam antes de qualquer registro sair da memória.
262
+ - **Revalidação na fronteira durável** — registros lidos do armazenamento são checados de novo antes de um sink vê-los.
263
+ - **Falha ruidosa, falha contida** — falhas de exportação avisam, contam, repetem e por fim caem no spool; uma falha do manipulador de sessão é capturada e registrada para que a observabilidade nunca quebre o caminho quente do harness.
264
+ - **Visível ao modelo ⟺ registrado** — as exportações de prompt/completion projetam apenas a superfície da sessão (cujo nó 0 é o system prompt) e o cabeçalho registrado (configuração da chamada e ferramentas); o exportador não inventa conteúdo.
265
+
266
+ ## Permissões e dados
267
+
268
+ - **Permissões**: `network:outbound` para os endpoints que você configurar, `session:read` para o fluxo de eventos e `storage:write` para o buffer offline; sem código nativo e sem acesso ao sistema de arquivos.
269
+ - **Dados**: tudo o que é enviado deriva do log da sessão e é saneado (redação + truncamento) antes de entrar na fila, no buffer ou na transmissão. O buffer offline guarda só registros saneados, revalidados quando lidos de volta.
270
+ - **Credenciais**: as chaves pública/secreta do Langfuse viajam só para o endpoint do Langfuse configurado; os cabeçalhos OTLP só para o endpoint OTLP configurado. O plugin não armazena credenciais — use referências de credenciais ou valores injetados por ambiente.
271
+
272
+ ## Limitações conhecidas
273
+
274
+ - **Base `0.2.2-rc.1`** — o plugin é desenvolvido e testado contra `@deepseek-ai/dsh@0.2.2-rc.1` (devDependencies e a régua principal da CI); `engines.dsh` (`>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`) e o intervalo composto de peers mantêm cada linha publicada instalável, e as bases mais antigas são cobertas pela segunda régua (`typecheck:ci`) e pelo workflow de compatibilidade.
275
+ - **Eventos de auditoria não são persistidos** — os registros `observe/*` do próprio exportador são apenas de auditoria: na linha atual do host o portão de append da sessão só aceita eventos de superfície, então nenhum evento `observe/*` é escrito no log da sessão, e o plugin não falsifica um com append sem marcação (isso tornaria as sessões ilegíveis). Use a saída de `observe/status` (requer `remote.enabled: true`) e os backends OTLP/Langfuse como superfície de auditoria.
276
+ - **Métricas evitam o caminho de nova tentativa/spool** — as métricas OTLP são agregadas de forma cumulativa, então um flush perdido se recupera no seguinte (por projeto, não é um bug).
277
+ - **Sem amostragem** — toda família de spans habilitada é exportada; para sessões de grande volume ajuste os interruptores `capture.*` e `batch.maxBufferRecords`.
278
+
279
+ ## Interoperabilidade com outros plugins DSH
280
+
281
+ A superfície de registro do plugin é deliberadamente estreita, então conflitos são estruturalmente improváveis:
282
+
283
+ - **Sem conflito de nome de ferramenta** — não registra ferramentas de modelo (nem o README nem o `src/index.ts` têm registro de ferramenta).
284
+ - **Sem conflito de nome de comando** — não registra comandos visíveis ao usuário, então nunca toca o namespace de comandos com barra.
285
+ - **Sem conflito de slot de cliente** — o pacote não traz metade de navegador (sem diretório `client/`), então não registra slots de cliente.
286
+ - **Sem curto-circuito de waterfall** — só lê `session/event`, `session/flush` e `session/disposed`; não escuta nenhum waterfall de allow/passthrough, então não pode segurar a decisão de ninguém.
287
+ - **Sua única chave de serviço** — `storageDomain` (injetada, não fornecida); mais um serviço remoto **opcional**, `observe`, registrado só com `remote.enabled: true`.
288
+ - **Tráfego de saída só para os seus endpoints** — OTLP e Langfuse são independentes; desligar um não afeta o outro.
289
+
290
+ Se houver outro plugin de observabilidade no mesmo perfil, atenção a duas coisas: ambos consomem `session/event` (o Cordis difunde, então nenhum mata o outro), mas você terá dois conjuntos de traces, e não registre o nome de serviço remoto `observe` duas vezes.
291
+
292
+ ## Compatibilidade
293
+
294
+ | Dimensão | Estado |
295
+ |---|---|
296
+ | Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (adaptado em 2026-10-04): o formato de sessão V4 representa o resultado de uma ferramenta como uma mensagem de primeira classe `role: 'tool'` com `toolCallId` + `content` + `isError` opcional no nível superior — o bloco de conteúdo `tool-result` do V3 saiu do `ContentBlockMap` do host, e este plugin lê só a forma V4 (um log V3 anterior à atualização ainda é projetado por um caminho de compatibilidade somente leitura). Os demais traços do formato V3 continuam: o fluxo do assistente vem embutido em `assistant/message` / `assistant/attempt`, e o system prompt é o nó 0 da superfície (`system/message`); o plugin consome apenas o fluxo de eventos ao vivo e nunca lê arquivos de log de sessão. `engines.dsh` é `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0`; o teste de fumaça de instalação do perfil é coberto pelo workflow de compatibilidade. |
297
+ | Node | `^22.19.0 \|\| >=24.9.0`, ESM puro (`"type": "module"`) |
298
+ | Backends | OpenTelemetry OTLP/HTTP (traces + métricas, codificação JSON) e Langfuse (observabilidade LLM) — um ou outro, ou ambos |
299
+ | Modelo | Independente de modelo: exporta o fluxo session/event; não faz chamadas a modelos |
300
+
301
+ Dependências peer: `@deepseek-ai/cordis ^4.0.5-alpha.1`, `@deepseek-ai/schemastery ^3.18.5`, e `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-storage`, `@deepseek-ai/dsh-storage-domain`, `@deepseek-ai/dsh-storage-json`, `@deepseek-ai/dsh-typert-protocol` (`>=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0`; devDependencies fixadas em `0.2.2-rc.1`). O `zod` é a única dependência de execução, usada na validação da fronteira durável do buffer offline.
302
+
303
+ ## Ecossistema e qualidade
304
+
305
+ - [Espelho no Gitee](https://gitee.com/perrylink/dsh-observe) (espelho sincronizado; o GitHub é a fonte autoritativa)
306
+ - [Página do plugin no dshfind](https://dshfind.com/plugins/PerryLink/dsh-observe) (instalações e ranking)
307
+ - [Relatório do OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-observe) (gerado pelo [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
308
+ - [Relatório de verificação do dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
309
+ - [DSH Market](https://dsh.market/) (listado)
310
+ - **Canal da loja 1024**: rode `npm i -g dsh1024` uma vez e depois `dsh1024 plugin --profile web add dsh-observe` (conta para o ranking de instalações do [deepseek1024.com](https://deepseek1024.com))
311
+ - [Base de conhecimento do ecossistema](https://perrylink.github.io/dsh-plugin-guide/): guia de desenvolvimento de plugins · dados de seleção · critérios de manutenção
312
+
313
+ ## Desenvolvimento
314
+
315
+ ```sh
316
+ pnpm install # node ^22.19 || >=24.9
317
+ pnpm run typecheck # tsc: src + tests contra as devDeps 0.2.2-rc.1 (sem paths de tsconfig)
318
+ pnpm run typecheck:ci # tsc contra a linha publicada (sem paths)
319
+ pnpm run check:ruler-live # canário: precisa falhar ao compilar, provando que a régua segue viva (requer a face checkout)
320
+ pnpm test # vitest: 126 testes, 18 suítes (costura real de Context/Session/storage)
321
+ pnpm run test:coverage # portão de cobertura (90/80/90/90)
322
+ pnpm run build # bundle tsdown + declarações tsc (lib/)
323
+ pnpm run verify:self-contained # as dependências resolvem a partir do registry
324
+ pnpm run verify:artifacts # face ESM compilada + patch do bundle presentes
325
+ node scripts/check-readme-sync.mjs # portão de sincronia dos README em cinco idiomas
326
+ pnpm pack # o tarball publicado
327
+ ```
328
+
329
+ As imagens do README são geradas por [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (o Pillow desenha os quatro heros de 1440×576; o diagrama de estrutura de 1100×660 é SVG escrito à mão), que grava `docs/assets/dsh-observe-hero-{zh,en}-{light,dark}.webp` e o par `docs/assets/dsh-observe-flow-v5-{light,dark}.svg`; reexecutar é idempotente. Os antigos `docs/assets/dsh-observe-flow-{light,dark}.svg`, `dsh-observe-flow.svg`, `dsh-observe-hero.png` e `dsh-observe-demo.{png,gif}` ficam onde estão para que links externos não deem 404; os README não os referenciam mais.
330
+
331
+ Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `observability`, `opentelemetry`, `otlp`, `langfuse`, `tracing`
332
+
333
+ ## Família e agradecimentos
334
+
335
+ Este projeto faz parte da família de plugins do DeepSeek Harness mantida pela [PerryLink](https://github.com/PerryLink) (todos Apache-2.0). Se este plugin for útil, **deixe uma estrela**: não desbloqueia nada, mas ajuda a próxima pessoa a encontrá-lo.
336
+
337
+ - [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: collector, pipelines, spool, sinks OTLP/Langfuse, saneamento e a documentação em cinco idiomas.
338
+
339
+ <details>
340
+ <summary>Expandir todos os plugins</summary>
341
+
342
+ | Plugin | Status |
343
+ |---|---|
344
+ | **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
345
+ | **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
346
+ | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
347
+ | **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 CONGELADO — ver o README do repo |
348
+ | **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
349
+ | **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
350
+ | **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 CONGELADO — ver o README do repo |
351
+ | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
352
+ | **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
353
+ | **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
354
+ | **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
355
+ | **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
356
+ | **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 CONGELADO — ver o README do repo |
357
+ | **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
358
+ | **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
359
+ | **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
360
+ | **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
361
+ | **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
362
+ | **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
363
+ | **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
364
+ | **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
365
+ | **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
366
+ | **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
367
+ | **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
368
+ | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
369
+ | **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
370
+ | **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
371
+ | **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
372
+ | **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
373
+ | **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
374
+ | **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
375
+ | **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
376
+ | **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
377
+ | **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
378
+ | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
379
+ | **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
380
+ | **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
381
+ | **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
382
+ | **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
383
+ | **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
384
+ | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
385
+ | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
386
+ | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
387
+ | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
388
+ | **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
389
+ | **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 CONGELADO — ver o README do repo |
390
+ | **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
391
+ | **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
392
+ | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
393
+ | **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
394
+ | **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
395
+ | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
396
+ | **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
397
+ | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
398
+ | **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
399
+ | **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
400
+ | **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
401
+ | **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 APOSENTADO (repo arquivado) |
402
+ | **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
403
+ | **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 APOSENTADO (repo arquivado) |
404
+ | **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 APOSENTADO (repo arquivado) |
405
+ | **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
406
+ | **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
407
+ | **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
408
+ | **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
409
+ | **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
410
+ | **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
411
+ | **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
412
+ | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
413
+ | **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
414
+ | **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
415
+ | **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
416
+ | **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 CONGELADO — ver o README do repo |
417
+ | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
418
+ | **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
419
+ | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
420
+ | **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
421
+ | **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
422
+ | **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
423
+ | **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
424
+ | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
425
+ | **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
426
+ | **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
427
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
428
+ | **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 APOSENTADO (repo arquivado) |
429
+ | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
430
+ | **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
431
+ | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 CONGELADO — ver o README do repo |
432
+ | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 CONGELADO — ver o README do repo |
433
+ | **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 CONGELADO — ver o README do repo |
434
+ | **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 CONGELADO — ver o README do repo |
435
+ | **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 CONGELADO — ver o README do repo |
436
+ | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 APOSENTADO (repo arquivado) |
437
+ | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 APOSENTADO (repo arquivado) |
438
+ | **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 APOSENTADO (repo arquivado) |
439
+
440
+ </details>
441
+
442
+ ## Licença
443
+
444
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-observe contributors
445
+
446
+ <p align="center"><sub>Apache-2.0 · Plugin da comunidade, não afiliado ao DeepSeek.</sub></p>
File without changes
package/cordis.patch.yml CHANGED
@@ -45,10 +45,15 @@
45
45
  tools: true
46
46
  llm: true
47
47
  # LLM prompt/completion capture policy. `false` records only sizes
48
- # and counts, never bodies.
48
+ # and counts, never bodies. `completion: false` drops the answer AND
49
+ # the reasoning body; `reasoning` only narrows it further. Reasoning
50
+ # is exported separately (gen_ai.completion.reasoning), never merged
51
+ # into gen_ai.completion, and may quote user input verbatim — evaluate
52
+ # the compliance impact before exporting it.
49
53
  llm:
50
54
  prompt: true
51
55
  completion: true
56
+ reasoning: true
52
57
  # Metadata capture switches. `cwd` is a local path — off by default.
53
58
  metadata:
54
59
  sessionId: true
package/lib/index.js CHANGED
@@ -46,10 +46,12 @@ const Config = z.object({
46
46
  }),
47
47
  llm: z.object({
48
48
  prompt: z.boolean().default(true),
49
- completion: z.boolean().default(true)
49
+ completion: z.boolean().default(true),
50
+ reasoning: z.boolean().default(true)
50
51
  }).default({
51
52
  prompt: true,
52
- completion: true
53
+ completion: true,
54
+ reasoning: true
53
55
  }),
54
56
  metadata: z.object({
55
57
  sessionId: z.boolean().default(true),
@@ -285,7 +287,8 @@ function resolveConfig(config = {}) {
285
287
  },
286
288
  llm: {
287
289
  prompt: llmRaw.prompt ?? true,
288
- completion: llmRaw.completion ?? true
290
+ completion: llmRaw.completion ?? true,
291
+ reasoning: llmRaw.reasoning ?? true
289
292
  },
290
293
  metadata: {
291
294
  sessionId: metadataRaw.sessionId ?? true,
@@ -603,7 +606,7 @@ function langfuseId(...parts) {
603
606
  * @module dsh-observe/version
604
607
  */
605
608
  /** The dsh-observe package version, kept in sync with package.json. */
606
- const VERSION = "0.2.27";
609
+ const VERSION = "0.2.28";
607
610
  // src/sinks.ts
608
611
  /** POST a JSON body with a timeout; throws on non-2xx. */
609
612
  async function postJson(url, headers, body, timeoutMs) {
@@ -696,10 +699,15 @@ function otlpSpan(span) {
696
699
  name: "gen_ai.prompt",
697
700
  attributes: [otlpAttribute("gen_ai.prompt", span.llm.input)]
698
701
  });
699
- if (span.llm?.output !== void 0) events.push({
700
- name: "gen_ai.completion",
701
- attributes: [otlpAttribute("gen_ai.completion", span.llm.output)]
702
- });
702
+ if (span.llm?.output !== void 0 || span.llm?.reasoning !== void 0) {
703
+ const completion = [];
704
+ if (span.llm?.output !== void 0) completion.push(otlpAttribute("gen_ai.completion", span.llm.output));
705
+ if (span.llm?.reasoning !== void 0) completion.push(otlpAttribute("gen_ai.completion.reasoning", span.llm.reasoning));
706
+ events.push({
707
+ name: "gen_ai.completion",
708
+ attributes: completion
709
+ });
710
+ }
703
711
  const error = span.status === "error";
704
712
  return {
705
713
  traceId: otelTraceId(span.sessionId, span.turn),
@@ -991,7 +999,8 @@ var LangfuseSink = class {
991
999
  ...span.llm?.model === void 0 ? {} : { model: span.llm.model },
992
1000
  metadata: {
993
1001
  ...span.attributes,
994
- ...span.llm?.costUsd === void 0 ? {} : { costUsd: span.llm.costUsd }
1002
+ ...span.llm?.costUsd === void 0 ? {} : { costUsd: span.llm.costUsd },
1003
+ ...span.llm?.reasoning === void 0 ? {} : { "gen_ai.completion.reasoning": span.llm.reasoning }
995
1004
  },
996
1005
  ...span.llm?.input === void 0 ? {} : { input: span.llm.input },
997
1006
  ...span.llm?.output === void 0 ? {} : { output: span.llm.output },
@@ -1298,6 +1307,57 @@ function projectContent(blocks) {
1298
1307
  return parts.join("\n");
1299
1308
  }
1300
1309
  /**
1310
+ * Narrow projection used by the completion export: keep only blocks of one
1311
+ * text-bearing kind (`text` or `reasoning`). The retired V3 wrapper is still
1312
+ * walked so a pre-upgrade log projects the same way it always did, but the
1313
+ * two kinds are never merged.
1314
+ * @param blocks - the model-facing content blocks.
1315
+ * @param kind - the block kind to keep.
1316
+ * @returns the joined text of that kind of block.
1317
+ */
1318
+ function projectTextBlocks(blocks, kind) {
1319
+ const parts = [];
1320
+ for (const block of blocks) {
1321
+ if (isRetiredToolResultWrapper(block)) {
1322
+ parts.push(projectTextBlocks(block.content, kind));
1323
+ continue;
1324
+ }
1325
+ if (block === null || typeof block !== "object") continue;
1326
+ const typed = block;
1327
+ switch (typed.type) {
1328
+ case "text":
1329
+ case "reasoning": if (typed.type === kind) parts.push(typed.text);
1330
+ }
1331
+ }
1332
+ return parts.join("\n");
1333
+ }
1334
+ /**
1335
+ * Project the assistant's visible answer: `text` blocks only.
1336
+ *
1337
+ * This is the body of `gen_ai.completion`. `reasoning` blocks are deliberately
1338
+ * excluded — chain-of-thought is model-internal text that can quote the user's
1339
+ * input verbatim, and merging it into the completion makes it
1340
+ * indistinguishable from the final answer to a downstream backend (which would
1341
+ * then price and display CoT as completion output). Tool-call and image blocks
1342
+ * are not answer text either; tool calls are exported through their own tool
1343
+ * spans, never folded back into the completion.
1344
+ * @param blocks - the model-facing content blocks.
1345
+ * @returns the joined `text` blocks (possibly empty).
1346
+ */
1347
+ function projectTextContent(blocks) {
1348
+ return projectTextBlocks(blocks, "text");
1349
+ }
1350
+ /**
1351
+ * Project the reasoning (chain-of-thought) blocks, kept separate from the
1352
+ * completion. Exported only when both `llm.completion` and `llm.reasoning` are
1353
+ * enabled, and never mixed into `gen_ai.completion`.
1354
+ * @param blocks - the model-facing content blocks.
1355
+ * @returns the joined `reasoning` blocks (possibly empty).
1356
+ */
1357
+ function projectReasoningContent(blocks) {
1358
+ return projectTextBlocks(blocks, "reasoning");
1359
+ }
1360
+ /**
1301
1361
  * Project one message's content.
1302
1362
  *
1303
1363
  * A tool-role message carries its failure flag on the MESSAGE (`isError`), not
@@ -1675,7 +1735,8 @@ var Collector = class {
1675
1735
  const usage = normalizeUsage(event.data.usage);
1676
1736
  const price = usage !== void 0 && provider !== void 0 && model !== void 0 ? findPrice(this.config.pricing, provider, model) : void 0;
1677
1737
  const cost = usage !== void 0 && price !== void 0 ? costUsd(price, usage) : void 0;
1678
- const output = this.config.llm.completion ? sanitizeText(projectContent(event.data.message.content), this.config.sanitize.truncateCompletionChars, this.config.sanitize) : void 0;
1738
+ const output = this.config.llm.completion ? sanitizeText(projectTextContent(event.data.message.content), this.config.sanitize.truncateCompletionChars, this.config.sanitize) : void 0;
1739
+ const reasoning = this.config.llm.completion && this.config.llm.reasoning ? sanitizeText(projectReasoningContent(event.data.message.content), this.config.sanitize.truncateCompletionChars, this.config.sanitize) : void 0;
1679
1740
  this.onSpan({
1680
1741
  kind: "llm",
1681
1742
  sessionId: session.id,
@@ -1693,6 +1754,7 @@ var Collector = class {
1693
1754
  ...step.firstChunkUnixNano === void 0 ? {} : { ttftMs: Math.max(0, Math.round((step.firstChunkUnixNano - start) / NANO)) },
1694
1755
  ...step.prompt === void 0 ? {} : { input: step.prompt },
1695
1756
  ...output === void 0 ? {} : { output },
1757
+ ...reasoning === void 0 || reasoning === "" ? {} : { reasoning },
1696
1758
  ...cost === void 0 ? {} : { costUsd: cost }
1697
1759
  }
1698
1760
  });
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes