dsh-session-insights

dsh-session-insights

简体中文 | Introduction | Changelog

Run /session-insights to turn DeepSeek Harness session history into a local workflow review. The Bundle reads sessions through DSH's sessionQuery service and writes a self-contained HTML dashboard plus companion JSON.

It helps answer questions such as:

• What kinds of work am I doing with DSH?
• Which projects and workflows take the most effort?
• Where do tool failures, retries, or unfinished work appear?
• Which practices are working, and what should I try next?

This is behavioral review, not telemetry. It is not a live monitor, a billing calculator, or a claim that it can judge the quality of your work.

What you get

The dashboard brings several views of the same evidence together:

The HTML file contains its own styles and data, so you can keep it locally and open it without a server. A machine-readable JSON report is written beside it.

Install the Bundle

Requirements: DeepSeek Harness and Python 3.11 or newer.

DSH compatibility: The plugin declares 0.1.0-rc.8 as its minimum DSH version. The relevant APIs in 0.1.2-rc.1 have been reviewed, with no compatibility changes identified as necessary; full native-host acceptance testing on that version has not yet been completed.

Install the published Bundle into a DSH profile, then start that profile:

dsh plugin --profile web add dsh-session-insights
dsh web

To install from a reviewed source checkout instead:

git clone https://github.com/GreenLv/dsh-session-insights.git
cd dsh-session-insights
dsh plugin --profile web add .
dsh web

Then run this in the DSH composer:

/session-insights --days 30 --locale en

The command prepares bounded semantic batches, queues the current DSH agent to analyze them serially, and writes the final HTML/JSON under $DSH_HOME/insights/runs/<run-id>. Add --deterministic to skip the model-assisted stage. The command name intentionally differs from /insights, so this Bundle can coexist with dsh-insights.

The npm package has no install or build lifecycle script. The registry command installs the published Bundle; dsh plugin ... add . installs the current local checkout.

Availability

• Install the published Bundle from npm.
• Download versioned artifacts from GitHub Releases.
• Find the public directory entry on dsh.pub.
• Other verified community listings are recorded in the distribution ledger.

Privacy modes

Deterministic reports run offline. In native plugin mode, complete raw snapshots are streamed from sessionQuery to Python over stdin and are not copied into the run directory. Choose how much session content the report and optional model stage may retain:

The tool itself does not add an upload channel. If you use the optional semantic workflow, bounded evidence cleaned according to --analysis-privacy is analyzed by the model provider currently configured in DSH.

Reports are refused inside $DSH_HOME/sessions, so generated files cannot be mixed into the source log tree.

Native command

/session-insights [--days N] [--project PATH] [--privacy MODE]
  [--analysis-privacy MODE] [--analysis-depth LEVEL]
  [--locale zh-CN|en] [--deterministic] [--resume] [--no-open]

Project filters use the host operating system's path syntax. On Windows, pass a native path such as /session-insights --project C:/path/to/project; a POSIX-rooted path such as /path/to/project is rejected instead of silently matching no sessions.

The semantic workflow is the default. Invalid model output gets one repair opportunity and can then fall back explicitly to the deterministic report. The current session is counted for coverage but excluded from recommendations as meta-analysis.

Compatible CLI and Skill workflow

The v0.1 file-log CLI and Skill remain available for automation and environments that do not mount the Bundle:

DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
python3 scripts/bootstrap.py install --dsh-home "$DSH_HOME"
CLI="$DSH_HOME/tools/dsh-session-insights/venv/bin/dsh-session-insights"

# Review the last 30 days and open an English dashboard
"$CLI" report --dsh-home "$DSH_HOME" --days 30 --locale en \
  --format html --output ./dsh-insights.html --open

# Limit the report to one project on macOS or Linux
"$CLI" report --dsh-home "$DSH_HOME" \
  --project /path/to/project --format html --output ./project-insights.html

# Produce aggregate metrics without excerpts or semantic batches
"$CLI" report --dsh-home "$DSH_HOME" --privacy metrics \
  --format json --output ./dsh-metrics.json

# Check the installation
"$CLI" doctor --dsh-home "$DSH_HOME"

The Windows PowerShell equivalent uses the managed Windows launcher and a Windows-native project path:

$Cli = Join-Path $env:DSH_HOME 'tools\dsh-session-insights\venv\Scripts\dsh-session-insights.exe'
& $Cli report --dsh-home $env:DSH_HOME --project 'C:\path\to\project' --format html --output .\project-insights.html

To remove only this project's managed directories:

python3 scripts/bootstrap.py uninstall --dsh-home "$DSH_HOME"

The installer manages only:

• $DSH_HOME/skills/dsh-session-insights
• $DSH_HOME/tools/dsh-session-insights

It refuses symbolic-link targets, overlapping roots, and existing unmarked directories. It does not overwrite another Skill.

Manual semantic review

The native command orchestrates semantic review by default. The CLI exposes each phase for debugging or automation:

dsh-session-insights semantic prepare --dsh-home "$DSH_HOME" --days 30 --workdir /safe/workdir
dsh-session-insights semantic validate-batch --workdir /safe/workdir --batch batch-001
dsh-session-insights semantic prepare-aggregate --workdir /safe/workdir
dsh-session-insights semantic validate-aggregate --workdir /safe/workdir
dsh-session-insights semantic finalize --workdir /safe/workdir --output report.html

Each model-produced JSON file is validated before it can enter the final report. Unknown evidence IDs, prohibited completion claims, malformed enums, and privacy leakage fail closed. If the semantic stage cannot finish, finalize --fallback records the degradation and preserves the deterministic report.

Current scope and limitations

• Native input is the trusted DSH sessionQuery service; CLI compatibility input remains session.jsonl.zstd under $DSH_HOME/sessions.
• Output follows dsh-session-insights/1.
• Token counts are deduplicated per (turn, step) and are usage measurements, not billing or quota figures.
• The Dashboard and semantic prompt contract support zh-CN and en from the same report schema.
• Reports infer patterns from available evidence; they do not prove intent, quality, task acceptance, or security.

Exact package, CI, native macOS, and focused native Windows evidence is kept in the v0.2.0 release acceptance record. Deterministic slash dispatch and rendered English DOM remain unverified natively on Windows. The historical v0.1 CLI/Skill evidence remains in the v0.1.0 acceptance record.

npm download history

The cumulative chart is generated daily from the npm Downloads API. npm download counts measure registry requests; they are not counts of unique users or confirmed installations. The workflow can also be run manually if GitHub delays or disables a scheduled run.

Development and project docs

python3 -m pip install -e '.[dev]'
python3 -m unittest discover -s tests -v
python3 scripts/build_fixture.py --check
python3 scripts/audit_public_tree.py --root .

• Changelog
• Security policy
• Contributing
• Distribution notes

The test fixture is fully synthetic and reproducibly compressed.

License

MIT