dsh-plugin-scaffold

Readme

# dsh-plugin-scaffold

A starter [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin.
It demonstrates the four extension shapes a community plugin can use, shipped as a
working persistent note scratchpad: `note_write` / `note_read` / `note_list` / `note_delete`.

| Shape | Where in this repo |
|---|---|
| Plugin with `Config` | `src/index.ts` — Schemastery schema, defaults, cordis.yml overrides |
| Tools | `ctx.tools.register(defineTool(...))` — canonical JSON outputs + `output.render` |
| UI cards | `presentCall` / `presentResult` / `presentationMeta` — pure projections |
| Hooks | `ctx.on('session/event', ...)` — observe the agent loop |

## Try it

Install the bundle into any profile (the `prepare` script builds on install):

```sh
dsh plugin --profile web add github:Tianbaidi/dsh-plugin-scaffold
```

Open the Web UI and ask the agent to `save a note called project-ideas
about the scaffold, then list all notes`.

Prefer a dev overlay instead? Point it at your local checkout:

```yaml
- insert:
    - id: scaffold
      name: 'file:///<path-to-plugin>/src/index.ts'
```

> Windows note: plugin paths in overlays must be `file://` URLs
> (`file:///D:/...%20...`), not bare `D:/...` paths — the ESM loader rejects
> the latter as scheme `d:`.

## Develop

```sh
pnpm install        # installs the published @deepseek-ai peer packages
pnpm typecheck      # strict TypeScript check against published .d.ts
pnpm test           # vitest: config defaults, tool round-trips, limits, presenters
```

Hot reload: edit `src/index.ts`, save, and the running `dsh web` reloads the
plugin (registrations are effects and clean themselves up).

## Make it yours

1. Rename the package and the `name` export in `src/index.ts`.
2. Replace the note domain with yours — keep the Config/tool/card/hook shapes.
3. Rebuild the `cordis.yml` `name:` file URL to point at your `src/index.ts`.

## Publish to the ecosystem

This project is already a **bundle** (`dsh.bundle.patch` in `package.json`), the
official distribution format: install it into any profile with `dsh plugin add`.

```sh
# from a dsh installation (npm or source checkout):
dsh plugin --profile my-profile add /path/to/dsh-plugin-scaffold
dsh --profile my-profile "save a note about the scaffold"
```

> Windows note: `dsh plugin add` forwards the path to pnpm, which splits on
> spaces — keep the package on a path without spaces, or use a tarball.

To share it with the community:

1. Push this project to your own GitHub repository.
2. Add the [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic to your repo
   so the community can discover it.
3. Users can then install straight from GitHub (`dsh plugin --profile my-profile
   add github:you/dsh-plugin-scaffold`). The `prepare` script builds `lib/` from
   source on install — pnpm will ask you to allowlist the build once
   (see the [package-and-install tutorial](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)).
4. (Optional) `npm publish` to make it installable by name.

## License

MIT