prts-terrarchive 0.2.0

package/GAME_ASSETS.md

@@ -0,0 +1,26 @@
+# Game Asset Inventory
+
+This file identifies game-derived resources packaged for the Arknights: Endfield map and skin experience. These resources are not covered by the MIT License in [`LICENSE`](LICENSE).
+
+## Excluded paths
+
+- `lib/endfield-map/resources/*.png`
+- `lib/endfield-map/resources/*.json.br`
+- `lib/endfield-map/resources/*.json.gz`
+- `lib/rhine/assets/archive-cassette.glb` — from LBEILC/RhineLabUI;
+  the upstream model is not covered by its code's MIT license. See
+  [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md#rhine-lab-archive-browser).
+- `lib/rhine/assets/archive-assembly.glb` — the same upstream's assembly model,
+  under the same exclusions.
+
+The Brotli (`.br`) and gzip (`.gz`) files are alternate compressed representations of map data and may include serialized geometry, materials, textures, or related presentation data used by the skin.
+
+The following project-authored implementation files are not part of this exclusion and remain covered by the MIT License:
+
+- `lib/endfield-map/map.js.br`
+- `lib/endfield-map/map.js.gz`
+- the source code that loads, renders, and integrates the map and skin
+
+Arknights: Endfield and all related names, trademarks, artwork, models, textures, game data, and other game materials belong to their respective rights holders. Their presence in this package does not grant permission to extract, reuse, modify, sublicense, or redistribute them independently.
+
+This is an unofficial community project and is not affiliated with or endorsed by the game's developers or publishers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PRTS.chat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,274 @@
+# prts-terrarchive (English)
+
+The optional **Rhine Lab Archive** skin combines a continuous 3D retrieval array,
+persistent investigation boards, a per-board evidence inbox, and a two-level archive rack
+with 24 sources per page. The Agent adds clues and relationships and publishes versioned
+reports; it decides whether a follow-up continues an investigation or starts a new one.
+Candidates stay in the array, while actually read or manually saved sources enter the rack.
+Users can stage important material in a chosen board's inbox, edit matching paper cards,
+and connect clues with red strings.
+
+`investigation_get` recalls clue text, versioned reports, the archive rack, evidence inboxes,
+and saved source bodies. Manual bookmarks now persist in session storage; existing browser
+bookmarks are imported automatically. User additions and edits appear in the Agent's next
+model context, or its next conversation when idle, without starting a new turn. Reminders
+remain pending until the corresponding content is successfully returned to the Agent;
+browser reads and unrelated pages do not acknowledge them.
+
+Enable it in Settings → Plugins → PRTS Corpus → Skin, then open the archive from
+a session header. Local and cloud search, Markdown reading, excerpts and tool activity
+share the workspace. Returning from a source restores the previous view and position.
+Manual browsing pauses automatic Agent following until explicitly resumed. Visible room
+models also navigate between stations. A text reader remains available without WebGL.
+
+For local development, use Node.js 22.19 or newer, then run `npm ci`,
+`npm run build:rhine`, and `npm run preview:rhine`. See the
+[workspace guide](docs/rhine-lab.md) and [interaction rules](docs/rhine-interaction-flow.md).
+
+PRTS.chat corpus plugin for DeepSeek Harness (DSH). Provides local corpus
+search, source reading and an activity-timeline tool, plus optional
+PRTS.cloud hybrid retrieval. The plugin first obtains the approved current
+release and per-file digests from the fixed `https://prts.chat` trust origin,
+then downloads the local corpus from ModelScope or a configurable byte-only fallback;
+the optional cloud service discovers candidates that can be mapped back to
+local source text for verification. Anonymous cloud retrieval currently has an
+allowance of 1,000 calls per user per day for DSH clients; this policy may
+change as service capacity evolves.
+
+- Registers DSH `ToolDefinition`s through the host plugin interface.
+- Host-resident instance (settings UI + data manager) + per-session "PRTS
+  mode" preset that mounts the tools only for sessions that select it.
+- The fixed `https://prts.chat` origin is the trust source for latest-release
+  resolution and manifests; ModelScope and the configurable fallback only serve
+  bytes for that fixed release and cannot select or attest a version.
+- Three optional skins (PRTS Agent, Endfield AIC terminal, Rhine Lab Archive) on top of the
+  native Harness UI.
+
+## Data sources
+
+- **Self-built Wiki data**: sourced from [littlepangding/arknights_lore_wiki](https://github.com/littlepangding/arknights_lore_wiki).
+- **Terra timeline data**: sourced from [PRTS Wiki's Terra timeline (泰拉年表)](https://prts.wiki/w/%E6%B3%B0%E6%8B%89%E5%B9%B4%E8%A1%A8) for the plugin's timeline search.
+
+## Install
+
+Web requires Node.js >= 22.19 and DSH >= 0.1.2-alpha.2. The current compatibility
+target is DSH 0.1.7-rc.2. An official Electron Desktop installation supplies
+its own runtime. Corpus disk usage is shown in Settings before download.
+
+### Local Web installation
+
+Install from a local checkout, or use PRTS Portable with the plugin already included:
+
+```bash
+npm install --global @deepseek-ai/dsh@0.1.7-rc.2
+git clone https://github.com/HTian-qwq/prts-terrarchive.git
+cd prts-terrarchive
+node bin/install.js web
+```
+
+The local installer adds the package to the selected profile. DSH 0.1.7 and
+later register PRTS mode directly; older DSH versions still create or migrate
+the compatibility preset in `$DSH_HOME/.agent-presets/prts`. With no
+second argument it uses its own checkout. Another local directory or archive
+can be supplied explicitly:
+
+```bash
+node bin/install.js web /path/to/prts-terrarchive
+```
+
+### Web: install from npm
+
+Install the bundle directly from npm; no additional installer command
+or npm lifecycle hook is needed:
+
+```bash
+dsh plugin --profile web add prts-terrarchive@0.2.0
+```
+
+Restart `dsh web`. On DSH 0.1.7 and later the plugin registers PRTS mode
+directly and removes it when disabled or uninstalled. The default mode and
+ordinary running sessions stay intact. The new registry does not read old
+`$DSH_HOME/.agent-presets/prts` files. Migrate any customized old preset
+through the new mode configuration; the old files remain untouched. Older DSH
+releases continue using the file template, preserving user edits. npm does not
+run `postinstall`.
+
+```bash
+dsh plugin --profile web remove prts-terrarchive
+```
+
+### Official Electron Desktop
+
+For Electron Desktop builds compatible with the DSH 0.1.7 plugin interface, enter
+`prts-terrarchive@0.2.0` in the **desktop application's plugin manager**.
+The manager accepts npm registry package names and versions, not GitHub URLs,
+local directories, or tarballs. Electron exclusively manages the `desktop`
+profile: do not run `node bin/install.js desktop` or
+`dsh plugin --profile desktop`.
+
+Web and official Desktop share the default `$DSH_HOME` product data while
+installing their plugins separately. The plugin package includes its UI,
+map models, textures, skills, and presets. It does **not** bundle corpus data,
+Node/DSH runtimes, or user data. Open Settings → Plugins → PRTS 语料 and download
+the corpus explicitly before using local retrieval. Switching skins does not
+start a separate model or texture download.
+
+PRTS Portable distributions include the plugin, presets, and the complete corpus,
+so no separate corpus download is needed after extraction. Build the official
+Electron portable target with `build-electron.ps1`; the original WebView2 build
+entry remains available. See the [Portable repository](https://github.com/HTian-qwq/prts-terrarchive-portable).
+
+Portable builders that already placed the plugin can continue running
+`node bin/install.js web --preset-only` to create or migrate the compatibility
+preset without invoking the DSH CLI.
+
+### Windows
+
+Local Web installation requires `dsh.cmd`. The installer invokes it through
+cmd.exe, so plugin paths containing a line break or `%` `!` `&` `|` `<` `>` `^`
+`"` are rejected. Use a directory without these characters. The `DSH`
+environment variable can locate an absolute `dsh.cmd` path. Official DSH stores
+the corpus under `%USERPROFILE%\.dsh\prts-corpus\releases` by default;
+Portable stores sessions and settings in its own `userdata` directory, and the
+bundled corpus and subsequent corpus updates in `corpus/releases`.
+
+### Retrieval settings
+
+Select PRTS mode in new sessions to load the corpus tools, DSH's native
+`web_search` and `web_fetch`, and the retrieval Skill. The preset enables both
+`arknights` and `endfield`; Settings stores the effective modules as
+`enabledGames` in `$DSH_HOME/prts-corpus.json`. Start a new session after changing
+them. The preset enables anonymous cloud retrieval by default. A raw plugin
+instance without the cloud configuration keeps it disabled.
+
+Static tokens are bound to the saved service origin. Changing the URL cannot
+forward a token to another origin. Re-enter legacy tokens that lack an origin
+binding in Settings; they remain unsent until saved again.
+
+After the retrieval Skill loads, matched entities and relationships enter DSH's
+dynamic context for the current question. Each new snapshot supersedes the
+previous one. Tool titles identify local/cloud retrieval and the game scope.
+
+## Skins and assets
+
+- **Harness default** keeps the native DSH interface.
+- **PRTS Agent** provides the PRTS.chat terminal-style interface.
+- **Endfield AIC** provides an optional Arknights: Endfield-inspired terminal
+  and 3D map. Its runtime code, models, and textures are pre-compressed and
+  installed with the plugin; switching skins does not start another download.
+
+The two optional skins have separate stylesheets. The client keeps only the
+active skin stylesheet mounted, plus a small shared stylesheet for plugin
+controls, so neither optional skin depends on the other's CSS.
+
+The Endfield AIC plugin code, UI integration, and map-rendering implementation
+are licensed under the MIT License. Game-derived models and textures used by
+that skin are not covered by the MIT License and are packaged only as parts of
+the optional skin. See [GAME_ASSETS.md](GAME_ASSETS.md) for the exact paths.
+These assets are independent of corpus version management: corpus datasets are
+downloaded from a verified ModelScope mirror or PRTS.chat on request, while skin assets require no separate
+download.
+
+## Tools
+
+- `corpus_search` — grep-style search over the local corpus: literal or a
+  linear regex subset (anchors, dot, character classes, escapes and fixed
+  `{n}` repetitions; no grouping, alternation or variable quantifiers) on NFKC-normalized text, with resource-type /
+  character / story / activity / entity / speaker / Wiki-field filters;
+  keep the original conditions and pass `page.next_after` back unchanged as
+  `after` to continue, because the readable anchor includes the full
+  `data_version` and becomes invalid after a corpus release switch
+- `corpus_read` — read Arknights stages by `stage_code` (adding `story_part`
+  only when needed), operator records by character/name/segment, and character
+  materials by category; it can stream a whole Arknights activity or Endfield
+  mission collection with readable, version-bound continuation positions;
+  it can also read a tagged Wiki field or page through a whole document; story
+  documents return requested text only (self-built summaries and the
+  activity timeline must be fetched explicitly, e.g. via `timeline_search`).
+  In a dual-module session, add `game: "arknights"` or `game: "endfield"` only
+  when a character locator needs same-name disambiguation.
+  Use exactly one primary locator per call. If search returns `document_uid`, it
+  replaces `title`; use `{document_uid, line}` or
+  `{document_uid, mode:"document"}`, never both locators. `max_lines` and
+  `max_chars` only cap output and do not select a read mode
+- `timeline_search` — query the Terra calendar timeline; source markers can
+  be resolved back to full provenance
+- `cloud_search` / `cloud_inspect` — optional PRTS.cloud hybrid retrieval
+  (enabled via settings; results are mapped back to local documents)
+- `web_search` — native DSH web discovery for external history, etymology,
+  folklore, and other non-PRTS sources
+- `web_fetch` — read a known public URL for close reading and cross-checking
+
+Repeated and partially reused reads retain the normal page limits and
+continuation. Partial reads include `coverage` identifying previously visible
+lines and newly returned lines; `page.has_more` still determines whether the
+document has more content. Cloud answers remain available when local corpus
+mapping fails, with a warning to install or repair the corpus before verifying
+the original text.
+
+If the corpus changes during a read or search, the request returns a retryable
+`PACKAGE_VERSION_MISMATCH`; resolve the locator against the current version
+before retrying. Old operations cannot populate the new version's document or
+search caches. Reused reads and reads spanning multiple documents enforce the
+same version check.
+
+Wiki documents are typed as canonical character pages, story/operator-record
+pages, or character-by-activity auxiliary pages. `corpus_search.wiki_sections`
+combines those types with character/activity filters, while
+`corpus_read({title, section})` reads the exact tagged field. See
+`skills/prts-retrieval/references/wiki-schema.md` and `retrieval-recipes.md`
+for field semantics and query recipes.
+
+## Compatibility
+
+DSH 0.1.2-alpha.1 and 0.1.2-alpha.2 have completed historical real-host tests
+with the web profile. Alpha.1 was built from the official tag and passed
+installation, preset resolution, host startup, settings-route, and
+client-bundle checks. The current plugin compatibility target is DSH
+0.1.7-rc.2. The shared Connection Fetch transport supports Web and the official
+Electron source implementation; Web also retains HTTP routes. Declarative
+registration and legacy file seeding pass this project's unit tests. A full
+0.1.7-rc.2 Host launch and Windows Electron end-to-end test remain to be run.
+The default Electron portable builder pins the official 0.1.7-rc.2 tag; the legacy
+Electron entry pins 0.1.5-alpha.1 and the original WebView2 builder pins
+0.1.3-alpha.1. Release builds still require a real Windows Host smoke test.
+
+Older custom deployments with `includeUserRoot: false` and no other preset root with
+`trust: user` receive no generated preset or root changes; their operator must
+first enable user preset authoring. The plugin relies on internal host surfaces
+(`ctx.tools`, `agent/pre-step`, Connection Fetch, agent presets, client
+slots/theme); after a DSH major upgrade, re-run the smoke checklist below.
+
+## Development
+
+`presets/` contains the PRTS composition, declarative definition, and legacy user-preset initializer.
+
+```bash
+npm run check   # syntax check
+npm test        # node --test suite
+git diff --check
+```
+
+`bin/pack-map-assets.mjs` pre-compresses the Endfield map assets
+(brotli q9 + gzip 9, the same scheme as endfield.prts.chat); the bundled
+plugin only carries compressed variants. `npm run pack:map:restore`
+restores plaintext for development.
+
+## License
+
+This project uses the following licensing boundaries:
+
+- **Original code and documentation:** licensed under the [MIT License](LICENSE).
+- **Game-related content:** names, trademarks, images, models, textures, game data, and other materials relating to Arknights or Arknights: Endfield are not covered by the MIT License and belong to their respective rights holders. See [GAME_ASSETS.md](GAME_ASSETS.md) for the exact packaged paths.
+- **Corpus datasets:** full datasets are not distributed in this Git repository
+  or bundled plugin code. Downloaded PRTS.chat datasets remain subject to the
+  licenses, source declarations, and terms on the
+  [Arknights dataset](https://modelscope.cn/datasets/HTiantian/prts-agent-corpus-arknights)
+  and [Endfield dataset](https://modelscope.cn/datasets/HTiantian/prts-agent-corpus-endfield)
+  pages.
+
+This is an unofficial community project and is not affiliated with or endorsed by the games' developers or publishers. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the complete notice.
+
+### Official Endfield localization lookup
+
+`corpus_i18n({query: "管理员，你来了。", languages: ["EN", "JP", "KR"]})` returns official localized text with source references. Existing search results can be passed as `title` or `document_uid`, optionally with `line`. Raw text IDs remain hidden unless `include_ids: true` is requested. Missing translations are explicit; profile records are aligned as a whole, not by Chinese paragraph number. Requires plugin 0.2.0 and a corpus release containing localization attachments. See [format and build instructions](docs/endfield-official-i18n.md).