# Parser extensions / 解析器扩展

v0.4.0 exposes `ctx.loghudParsers` as a public Cordis Host service. This is for trusted installed plugins, not arbitrary downloaded code. An extension supplies both its block-start rules and parser; new log formats do not have to pass Java/Node/Go keyword filters.

v0.4.0 提供公开的 Cordis Host 服务 `ctx.loghudParsers`。扩展需同时注册错误块起始规则和解析器，不受内置语言关键词预过滤限制。只允许受信任的本机插件，不支持远程执行解析代码。

```ts
import type { Context } from '@deepseek-ai/cordis'
import type { LogErrorExtension } from 'dsh-loghud'

export const inject = ['loghudParsers']
export function apply(ctx: Context) {
  const extension: LogErrorExtension = {
    parser: {
      id: 'example-dsl',
      priority: 100,
      supports: (block) => block.rule.id === 'example-dsl-fault',
      parse: (block) => ({
        category: 'custom:example-dsl',
        language: 'custom:example-dsl',
        runtime: 'custom:example',
        toolchain: 'custom:example-compiler',
        exceptionType: 'ExampleFault',
        summary: block.lines[0] ?? 'Example failed',
        exceptionChain: [],
        rawContext: block.lines,
      }),
    },
    rules: [{
      id: 'example-dsl-fault',
      category: 'custom:example-dsl',
      severity: 'error',
      startPatterns: [/^EXAMPLE FAULT:/],
    }],
  }
  const unregister = ctx.loghudParsers.register(ctx, extension)
  // Optional early removal. Owner disposal also removes this registration.
  // unregister()
}
```

## Contract / 约定

- `register(owner, extension)` returns an idempotent unregister function. Cordis owner disposal removes the parser and its rules.
- Parser IDs and rule IDs must be unique, including built-ins. A failed registration changes nothing.
- Higher priorities run first; ties preserve registration order. Built-ins: TypeScript 500, Node 400, Python 350, Go 325, Spring 300, Java 200. Generic is always last regardless of an extension's numeric priority.
- `supports()` and `parse()` exceptions are isolated and logged without raw payloads. The next parser can still handle the block.
- Custom category/language/runtime/toolchain values use `custom:<id>`. The HUD renders unknown labels as plain text, not HTML.
- Rules use standard JavaScript regular expressions: avoid unbounded catastrophic backtracking. Trusted callbacks run synchronously on the Host and cannot be sandboxed or forcibly timed out.
- A collector snapshots its rule list when a command stream starts; registration changes apply to new streams. Disposed parsers are not called when pending blocks finish.
- Return JSON-safe structured facts. Keep the original bounded context; do not call AI or execute commands inside a parser.

注册与卸载均有生命周期；ID 重复会整体拒绝。优先级相同按注册顺序执行，Generic 固定最后。未知分类按纯文本展示。解析器运行在 Host 内，必须避免耗时计算和高风险正则；插件无法对同步扩展强行超时。规则变化影响新采集流，现有采集流保留开始时的规则列表。