dsh-lens

A "code health check" plugin for DSH (DeepSeek Harness). It watches your code
changes, checks for syntax/type/lint problems, shows them on a card next to the
chat input, and shares them with the AI assistant — no technical knowledge
required.

1. What does it do?

Think of it as a doctor who sits next to your code:

• After every edit, it quickly checks for obvious mistakes (e.g. a missing
  bracket).
• When the AI reads or edits a TypeScript/JavaScript file, it runs a full check in the background (type check, lint).
• Problems appear on a diagnostic card above the chat input and are also
  reported to the AI assistant so it can help fix them.

It never blocks your edits or modifies your files on its own. Card refreshes use a separate read-only endpoint and never place snapshot JSON in the AI conversation context.

2. Before you start

What is a terminal? On Windows it is called PowerShell:
click the Start button → type PowerShell → press Enter.
A dark window with a blinking cursor appears. All commands below are typed there.

3. Install, step by step (about 3 minutes)

Step 1 — Check that DSH is installed

Copy this line into the terminal and press Enter:

dsh --version

Success looks like: a version number such as 0.1.0-rc.6.

If you see dsh is not recognized (or command not found): DSH is not
installed yet or not on your PATH. Install DSH first (see FAQ below).

Step 2 — Install the plugin (copy one command)

dsh plugin --profile web add npm:@dsh-lens/dsh-lens

What this does: dsh plugin manages plugins, --profile web targets the web
profile, add npm:@dsh-lens/dsh-lens downloads the plugin from npm (an app
store for software).

Success looks like: text scrolls and stops, returning to a prompt (usually
Done). It normally takes less than a minute.

Testing locally before publishing? Run npm run pack in the plugin
source folder (produces dsh-lens-0.1.0.tgz), then install it:

dsh plugin --profile web add C:\your\path\dsh-lens-0.1.0.tgz

(Plain npm pack names the file dsh-lens-dsh-lens-0.1.0.tgz — also fine;
delete the old .tgz before repacking.)

Step 3 — Confirm it is installed

dsh plugin --profile web list

Success looks like: the list contains a line with @dsh-lens/dsh-lens.

Step 4 — Restart DSH

1. Close the DSH window/page completely.
2. Open DSH again as usual.

Done. It starts working automatically — no further setup.

4. Quick check that it works (30 seconds)

1. Open any TypeScript project (a folder containing tsconfig.json).
2. Open a .ts file and intentionally break one line, e.g.:

   const x: number = "hello";

3. Save the file.
4. Look near the chat input — a diagnostic card should appear saying
   something like "1 个问题 / 1 issue".

Projects without a tsconfig.json are intentionally not checked.

5. FAQ

6. Advanced settings (some technical knowledge needed; skippable)

The defaults work for most users. To customize, create a file named
.dsh-lens.json in your project root (never auto-generated):

{
  "enabled": true,
  "typecheck": { "enabled": true },
  "eslint": { "enabled": false },
  "exclude": ["generated/**"]
}

Priority: built-in defaults < DSH global config < project .dsh-lens.json.
Changes hot-reload on save — no restart needed.

Full config (profile patch):

- id: dsh-lens
  config:
    enabled: true
    include:
      - "**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"
    exclude:
      - "**/node_modules/**"
      - "**/dist/**"
      - "**/build/**"
    fast:
      enabled: true
      maxFileBytes: 524288
      budgetMs: 50
    typecheck:
      enabled: true
      debounceMs: 800
      timeoutMs: 60000
    eslint:
      enabled: false
      debounceMs: 1000
      timeoutMs: 30000
    feedback:
      inject: true
      maxDiagnostics: 8
      maxBytes: 4096
    scheduler:
      maxConcurrentProjects: 2

7. For developers

• Requirements: Node.js >= 20; DSH baseline 0.1.0-rc.6 (all
  @deepseek-ai/* packages are peers, not bundled); TypeScript >= 5.0.0 is an
  optional peer.
• Commands: npm install → npm run verify (typecheck + 107 tests + build) →
  npm pack --dry-run.
• Pipeline:

write/edit ──► quick syntax (transpileModule) ──► post-execute additionalContexts
     │
read ─┴─► debounced background check (tsc / eslint via ctx.subprocess)
              └─► delta classification ──► agent.inject() report
                                     └─► lens snapshot ──► Web card

• Modules: ./client, ./adapter, ./diagnostics, ./quick-syntax,
  ./scheduler, ./background-check, ./providers, ./delta, ./feedback,
  ./snapshot, ./lens-card, ./config, ./reliability, ./types.
• The Web card polls a same-origin, no-store HTTP snapshot endpoint; polling
  does not write command events or snapshot JSON into the Session context.
• Known limitations: no Web settings page in the first release; typecheck
  and eslint share one debounce pipeline.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.