dsh-nga-reader-plugin

Readme

# dsh-nga-reader

[![DSH Plugin](https://img.shields.io/badge/DSH-plugin-5b21b6)](https://dshfind.com/plugins/jo32/dsh-nga-reader)
[![DeepDeck App](https://img.shields.io/badge/DeepDeck-App-f15a24)](https://github.com/jo32/DeepDeck)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A persistent `dsh-plugin` Cordis Host/Client bundle for browsing NGA, reading
discussions and using selected content in AI conversations.

> **Best used with [DeepDeck](https://github.com/jo32/DeepDeck).** DeepDeck
> supplies the Apps launcher, standalone reader window, app-scoped Workspace,
> settings and canonical conversations used by **Explain** and **Summarize**.
> This plugin expects DeepDeck's App runtime service when it is mounted.

## Screenshot

NGA Reader supports guest browsing and keeps authentication optional until a
personal or write action needs it. QR, account/password and existing token
sign-in are available. The screenshot below is captured from the standalone
DeepDeck desktop App window—not a browser tab. It uses an isolated **Guest
session** to open the public **音乐影视** forum and read a discussion without an
account, so no account identifier or credential is present.

![NGA Reader browsing a public forum as a guest in DeepDeck](docs/images/deepdeck-nga-reader.jpg)

## Install with DeepDeck (recommended)

1. Open **Settings → Apps** in DeepDeck.
2. Paste `https://github.com/jo32/dsh-nga-reader.git` into **Install an App
   plugin**.
3. Choose **Inspect source**, review the detected package and build command,
   then choose **Confirm install**.
4. Restart DeepDeck when prompted.
5. Open **Apps → NGA Reader** from the sidebar.

For local development, build the checkout and install the resulting local
bundle into the active DeepDeck web profile:

```bash
git clone https://github.com/jo32/dsh-nga-reader.git
cd dsh-nga-reader
npm install
npm run typecheck && npm test
dsh plugin --profile web add "$PWD"
```

The last command only mounts the Cordis bundle; run it in a DeepDeck-managed
profile so the required App runtime is present.

## Usage examples

- Open a forum, select a topic and read paginated posts in the focused reader.
- Select text or right-click a post, then choose **Explain** or **Summarize** to
  open a canonical Session in `~/DeepDeck/Apps/nga-reader`.
- Ask the DeepDeck agent: `列出 NGA 当前热门主题，并按版面分组。`
- Ask about a selected topic: `阅读这个帖子，提炼主要共识、争议点和有用链接。`
- Connect an account only when you need favorites, notifications, messages,
  check-in, voting or replies. Agent-triggered publishing remains
  approval-gated.

## Features

- NGA forum discovery and filtering
- Topic lists, topic search, pagination, post reading, icons, avatars and images
- QR scan login (NGA App scan-to-authorize) and account password login
- Manual access_uid/token entry as a fallback
- Persistent local credential storage; explicit reply publishing
- Agent tools for forum discovery, topic reading and current UI context
- Reader window: the sidebar launcher promotes `GET /nga-reader` (a
  self-contained reader document) into a real secondary Electron app window
  through the desktop shell's `deepdeck:open-app-window` IPC request; without
  a desktop IPC parent it stays closed; the Client contains no embedded reader
- Text selection -> right-click -> Explain or Summarize in the standalone
  window; a same-origin BroadcastChannel starts a canonical app Session and
  opens that conversation directly in the main DeepDeck window

## Extended NGA support

MNGA feature parity (ported from `logic/service/src` contracts):

- Daily check-in, notifications (typed: replies / mentions / votes / PMs)
- Short messages: conversations, thread reader with paging, reply and new
  messages to one or more recipients
- Favorites: forum favorites (list/add/remove), topic folders (list/create/
  rename/set-default/delete), favorite topics per folder, favor/unfavor a topic
- Hot topics per forum with day/week/month range and reply sorting
- User profiles by uid or name (stats, signature, mute/ip, follow state,
  avatar fallback), follow/unfollow, follow list, follow activity feed
- Per-user topic lists and per-user post search (`searchpost`)
- Post voting (topic recommend up/down), reply draft fetch (quote/reply/modify
  verbatim incl. attachment auth), report post, subforum filter block/show
- Signature update; notification read-state tracked client-side in the session
- Standalone-window UI: drawer panels for notifications / messages /
  favorites / user cards, clock-in and hot-topics buttons, vote and favor
  actions on posts

Agent tools added for agentic access: `nga_clock_in`, `nga_notifications`,
`nga_short_messages`, `nga_read_message`, `nga_send_message` (approval-gated),
`nga_favorite_forums`, `nga_hot_topics`, `nga_user`, `nga_user_topic_list`,
`nga_user_post_list`, `nga_following_users`, `nga_following_activity`, and
`nga_vote_post`. The full action set is also exposed on `/api/nga-reader`
(`clock-in`, `notis`, `msg-*`, `fav-*`, `user*`, `follow-*`, `vote`,
`reply-draft`, `report`, `signature`, `subforum-filter`).

## Authentication and credential storage

Login implementation notes:

- QR keys come from `nuke.php?__act=qrlogin_gen`; the QR encodes the official
  `qrlogin_ui` URL, and `__act=login` with `qrkey`/`hiddenkey` exchanges the
  authorization for `uid`/`token` (pending state: "license not found").
- Passwords are RSA (PKCS#1 v1.5) encrypted with the official web public key
  before submission, matching the passport page behavior.
- QR images are generated locally with the Node `qrcode` package; no
  third-party QR service receives sign-in data.

The Host persists only the NGA `uid` and access token as the plugin-owned
`dsh-nga-reader-plugin/nga-account` grant in the Harness credential document
`$DSH_HOME/.credentials.yaml` (default: `~/.dsh/.credentials.yaml`). Account
passwords are never stored. The mounted `credentials-local` service owns
atomic writes, cross-process locking, private file permissions and durable
reloads. The plugin reads the record for each NGA operation instead of caching
the token as plugin state, and its Sign out action deletes that record.

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
```

The plugin, NGA HTTP client, parsers, authentication helpers, and QR generation
are implemented in strict TypeScript/Node.js under `src/` and compiled to the
ESM/runtime artifacts under `lib/`. Python is not required. Generated `lib/`
output is not committed.

## License

MIT. Runtime dependency licenses are recorded by their respective npm packages.