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

You need	How to check
A computer (Windows or Mac)	You are using one now ✓
DSH installed	You can open the DSH web UI
A terminal window	See Step 1 below

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

Problem	Solution
dsh is not recognized	DSH is not installed or not on PATH. Reinstall DSH.
Permission error / Access denied	Right-click PowerShell → Run as administrator, retry Step 2.
No card after restart	Make sure you opened the web UI, the project has tsconfig.json, and Step 3 listed the plugin.
Card always says "no diagnostics"	Normal — no problems found. Introduce an error and save to see it.
Want to uninstall	dsh plugin --profile web remove dsh-lens
Want to disable checks	See "Advanced settings" below; set enabled to false.

---

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.