dsh-term-dict 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-term-dict 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,131 @@
+# dsh-term-dict
+
+[中文](README.md) | **English**
+
+A cross-session glossary for DSH: keep the terms you and the model agreed on in plain text files. When a term
+first shows up in a session, its definition is injected into the model context automatically. Ships with three
+tools (look up / write / lint) and a settings panel.
+
+Every new session starts blank: the model no longer knows what *your* "report" or "the table" means. Write it
+down once; from then on the first mention in any session carries the agreed meaning.
+
+## Layout
+
+| Layer | File | Holds |
+| --- | --- | --- |
+| General | `$DSH_HOME/dict/general.md` | terms valid across every kind of work |
+| Task | `$DSH_HOME/dict/domains/<task-slug>.md` | terms valid only inside one kind of work, including per-workspace default targets |
+
+One file per kind of work. The file header carries `> 任务类型：<display name>`; the panel lists that name.
+A task layer may bind workspaces with `> 工作空间：<path fragment>` lines — the term only matches when the
+session working directory contains one of the fragments.
+
+## Entry format
+
+```md
+## term name (alias: another name)
+
+- 定义: one sentence, what it is
+- 默认指代: what it points at by default when used alone
+- 边界: what it is not
+- 状态: 已确认 / 部分确认 / 待观察 / 已废
+- 备注: optional; put "which one wins when names collide" here
+```
+
+Only the definition is required. Aliases go into the heading parentheses; looking up an alias is equivalent
+to looking up the term name. The type (term / target / archived) is inferred from which fields are present
+and is not written to the file.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `dict` | Single entry: `action=lookup` (index when `term` is omitted) / `write` / `lint` / `mute` / `unmute` |
+| `dict-lookup` | Look up only: index or full entry text; aliases match too |
+| `dict-write` | Write only: add or update one entry, keeping a `.bak` first |
+| `dict-lint` | Lint only: empty definitions, missing status, duplicate names, alias clashes, cross-layer copies, near-identical names |
+
+A miss is a normal result, not an error: the tool answers with near-miss candidates instead of failing.
+
+## Auto-activation
+
+The first time a term or alias appears in a session, its meaning is injected into the model context through
+the official runtime-context channel. Once per session per term; the state lives in
+`$DSH_HOME/dict/.activation.json`, so restarting or resuming does not inject twice.
+
+- **Timing**: words in the user message apply before that model call; words in the model's own reasoning or
+  output apply from the next step or next turn (the stream already being generated cannot be changed).
+- **Scope**: every agent preset by default. Pick presets in *Settings → Advanced → presets* (the local roster is listed for you) to restrict it;
+  outside those presets the dictionary tools are not registered at all. Empty means unrestricted.
+- **Limits**: 64 terms per session, 12000 characters in total, entries not truncated — all adjustable.
+- **Skipping**: pick local workspaces in the panel (path-substring match, so a parent directory also covers its subdirectories) or type extra fragments (`skipWorkspaces`); session ids go through `skipSessions`; the
+  composer button controls the current session, and each task layer can be forced on or off per session.
+
+## Settings panel
+
+Settings → *Term dictionary*: a layer tree on the left, term editing and raw-text editing on the right, and a
+settings page for auto-activation, the three limits, the preset allowlist and skipped workspaces. A separate
+*Structure* page manages modules and types; removing a module scans its impact first and only touches data
+after 24 hours, with an undo window.
+
+## Local routes
+
+The host half registers 24 loopback-only routes under `/dsh-term-dict`; state-changing requests must also be
+same-origin (cross-site writes from a browser get 403). Non-browser clients without those headers still work.
+
+| Group | Routes |
+| --- | --- |
+| Layers and entries | `GET /api/list`, `GET /api/read`, `POST /api/write`, `POST /api/rename`, `POST /api/create-layer`, `POST /api/workspace`, `GET /api/workspaces` |
+| Sessions | `GET /api/session-state`, `POST /api/session-mute`, `POST /api/session-mute-clear`, `GET|POST /api/session-layers` |
+| Structure | `GET /api/schema-scan`, `POST /api/schema/module-remove`, `POST /api/schema/module-cancel`, `POST /api/schema/module-add`, `POST /api/schema/module-def`, `POST /api/schema/type-enable`, `POST /api/schema/type-module`, `POST /api/schema/type-add`, `GET /api/schema/type-scan`, `POST /api/schema/type-remove`, `POST /api/schema/type-unremove` |
+| Settings | `GET|POST /api/settings`, `GET /api/presets` (the local preset roster used by the allowlist) |
+
+## Data
+
+Everything lives in `$DSH_HOME/dict/`: `general.md`, `domains/<slug>.md`, `.settings.json`,
+`.activation.json`. The dictionary files are plain text and can be edited by hand; the plugin keeps a `.bak`
+before writing. Uninstalling does not delete them.
+On first run, if the general layer does not exist, the plugin seeds two term entries ("词条", alias 词目,
+and "词典", aliases 字典/术语字典; both type 称谓型 with all modules filled in). An
+existing dictionary is never overwritten.
+
+## Install
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-term-dict
+```
+
+Restart DSH afterwards; replace `desktop` with your profile name if you use another one.
+Requires DSH >= 0.2.2-0 (verified on 0.2.2-rc.1; newer versions untested).
+
+## Development
+
+```sh
+npm install
+npm run build:client    # regenerate lib/client.js from src/entry.jsx
+npm run check:client    # committed bundle matches the source
+npm run check           # syntax
+npm run smoke           # structure, composition, host tools and routes, activation defaults, default entry, bundle, leftovers
+```
+
+`lib/client.js` is a committed build artifact: installing from GitHub does not run a build, and without the
+bundle the panel never appears. `react`, `react/jsx-runtime` and `react-dom` stay external (the DSH client
+module table provides them), and the envelope `window.__ModuleLoader__.load({ id, factory })` must carry the
+package name as `id`.
+
+## Limitations
+
+- Auto-activation matches exact term names and aliases only; near-misses are suggestions, not automatic.
+- Task-layer terms only match when workspace binding or a session override allows them.
+- The panel routes are loopback-only: on a remotely accessed DSH the panel returns 403.
+- Entries are plain text split by level-2 headings; hand edits must keep the `## name` heading.
+
+## Feedback
+
+Open an issue: https://github.com/taoziliyouchong/dsh-term-dict/issues
+
+Please include the DSH version, the plugin version, the exact error text and a screenshot.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# dsh-term-dict
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**中文** | [English](README.en.md)
+
+跨会话的术语字典：把「我们之间约定俗成的称谓」写进文本文件，某个词第一次出现时自动把它的口径注入模型上下文，
+再配一个能看能改的设置面板和查／写／体检三条工具。
+
+模型每开一个新会话都会忘掉「你说的 X 指什么」。术语字典把这件事存成文件：不靠记忆、不靠每轮重复解释，
+写一次，之后会话里第一次用到这个词就自动带上口径。
+
+## 它管什么
+
+| 层 | 文件 | 收什么 |
+| --- | --- | --- |
+| 通用 | `$DSH_HOME/dict/general.md` | 跨任务类型都成立的称谓 |
+| 任务 | `$DSH_HOME/dict/domains/<任务slug>.md` | 只在本类任务里成立的称谓，含只对某个工作区成立的默认落点 |
+
+一个任务一个文件，文件表头写一行 `> 任务类型：中文任务名`，面板和列表就按这个名字显示。
+任务层可选绑定工作空间：表头写 `> 工作空间：<路径片段>`（可多行），会话的工作目录命中任一片段才参与匹配。
+
+## 词条格式
+
+```md
+## 词条名（别名：另一个叫法）
+
+- 定义：一句话说清它是什么
+- 默认指代：单独出现时默认优先指哪件事／哪份文件／哪条命令
+- 边界：它不是什么
+- 状态：已确认 / 部分确认 / 待观察 / 已废
+- 备注：可选；撞名认哪条也写这里
+```
+
+除定义外都可选。别名写进标题括号里，查别名与查词条名等价。
+
+三种类型由主字段推断，不写进文件：有定义＝称谓型；只写默认指代＝落点型；状态为已废＝留档型。
+
+## 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `dict` | 一个入口全包：`action=lookup` 查（不传 term 就列索引）／`write` 写词条／`lint` 体检／`mute`、`unmute` 把当前会话加进或移出「不灌注」名单 |
+| `dict-lookup` | 只查：列索引或给词条正文（含定义／默认指代／边界／别称／状态／备注），别名也命中 |
+| `dict-write` | 只写：增或改一条词条，写前留 `.bak` |
+| `dict-lint` | 只体检：空定义、缺状态、同层重名、别称冲突、跨层同名同义可删重、跨层同名异义缺排他性、名字只差一个字的疑似同词 |
+
+查不到时给「疑似同一词」候选，不返回错误——没收录是正常结果。
+
+## 自动激活
+
+同一个会话里，某个词条的词条名或别称第一次出现时，把该条口径作为 runtime-context 注入模型上下文；
+同一会话同一词条只注入一次，状态记在 `$DSH_HOME/dict/.activation.json`，重启或恢复会话后不重复注入。
+
+- **生效时机**：用户消息里的词在本次模型调用前生效；模型思考与输出里的词只能从下一步或下一轮生效（正在流式生成的那一段改不了）。
+- **灌注范围**：默认所有模式都灌注。设置面板「高级设置 → 灌注的模式」会自动列出本机所有模式（带显示名与 id），勾上就只在这些模式里灌注，别的模式连字典工具都看不到；全不勾＝所有模式。清单取不到时退回手填 id。
+- **上限**：默认单会话 64 条、整段 12000 字、单条不截断，都能在面板里改。
+- **不灌注**：面板里勾选本机工作空间（按路径子串匹配，勾上层目录会连带命中其子目录），也可手填其它路径片段（`skipWorkspaces`）；按会话 id 排除走 `skipSessions`；输入栏「词条·注／禁」按钮管当前会话，任务层还能单独设「跟随／强制开／强制关」。
+
+## 设置面板
+
+设置 →「术语字典」，三块：
+
+- **左栏**：通用层与任务层名册，可新建任务层、改名、绑定工作空间。
+- **右栏**：「词条」视图点一条就地改字段；「原文」视图批量整理；底部显示文件与保存状态。
+- **设置页**：自动激活开关、三个注入上限、灌注的模式、不灌注的工作空间；「结构」页管模块与类型（模块是全局清单，类型是勾选组合），删模块先扫描影响、确认后 24 小时才动数据且可撤销。
+
+## 本机路由（面板后端）
+
+宿主半边注册 24 条本机路由，只接受回环地址；改数据的请求还要求同源（浏览器从别的站点发来的写请求直接 403）。
+非浏览器来源（命令行、脚本）不带这些头，照旧放行。
+
+| 分组 | 路由 |
+| --- | --- |
+| 层与词条 | `GET /api/list`、`GET /api/read`、`POST /api/write`、`POST /api/rename`、`POST /api/create-layer`、`POST /api/workspace`、`GET /api/workspaces` |
+| 会话 | `GET /api/session-state`、`POST /api/session-mute`、`POST /api/session-mute-clear`、`GET|POST /api/session-layers` |
+| 结构 | `GET /api/schema-scan`、`POST /api/schema/module-remove`、`POST /api/schema/module-cancel`、`POST /api/schema/module-add`、`POST /api/schema/module-def`、`POST /api/schema/type-enable`、`POST /api/schema/type-module`、`POST /api/schema/type-add`、`GET /api/schema/type-scan`、`POST /api/schema/type-remove`、`POST /api/schema/type-unremove` |
+| 设置 | `GET|POST /api/settings`、`GET /api/presets`（本机模式清单，给「限定模式」勾选用） |
+
+以上路径都挂在 `/dsh-term-dict` 前缀下。
+
+## 数据放哪
+
+`$DSH_HOME/dict/`：`general.md`、`domains/<slug>.md`、`.settings.json`（高级设置）、`.activation.json`（按会话记已激活词条与静音名单）。
+字典文件是纯文本，可直接手改；改之前插件会留 `.bak`。卸载插件不会删这些文件，要清就手工删目录。
+首次运行时通用层不存在，会预置两条词条（「词条（别名：词目）」「词典（别名：字典、术语字典）」，都是称谓型，模块齐全）；已有字典不会被覆盖。
+
+## 安装
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-term-dict
+```
+
+装完重启 DSH。用别的 profile 就把 `desktop` 换成你的 profile 名。
+要求 DSH >= 0.2.2-0；实测 0.2.2-rc.1，更高版本未验证。
+
+## 开发
+
+```sh
+npm install
+npm run build:client    # 从 src/entry.jsx 重新生成 lib/client.js
+npm run check:client    # 已提交产物与源码一致
+npm run check           # 语法
+npm run smoke           # 结构 / 组合声明 / 宿主工具与路由 / 自动激活默认值 / 默认词条 / 客户端产物 / 环境残留 七关
+```
+
+`lib/client.js` 是提交进仓库的构建产物：从 GitHub 安装时不跑构建，缺了它面板不会出现。
+打包要求：`react`、`react/jsx-runtime`、`react-dom` 保持 external（由 DSH 客户端模块表提供）；
+产物外壳 `window.__ModuleLoader__.load({ id, factory })` 里的 `id` 必须等于包名。
+
+源码：
+
+- `src/entry.jsx` —— 浏览器半边（面板、词条编辑、结构页、高级设置）
+- `src/term-text.js` —— 词条文本的解析与渲染（面板与宿主同一套口径）
+- `index.js` —— 宿主半边（四条工具、24 条本机路由、技能注册）
+- `activation.js` —— 自动激活（扫描、状态、灌注上限、模式白名单）与首次运行的默认词条
+- `assets/general-default.md` —— 首次运行写入通用层的默认词条（两条，都是称谓型，模块齐全）
+
+## 已知限制
+
+- 自动激活只认精确命中（词条名／别称），不做形近联想；形近候选要自己 `lookup` 查。
+- 任务层的词条只在工作空间匹配或会话覆盖时参与匹配；没写绑定的任务层对所有工作空间生效。
+- 面板路由只接受本机回环地址：远程访问的 DSH 上，面板会读不到数据（返回 403）。
+- 词条文件是纯文本、按二级标题分块，手改时标题必须是 `## 词条名`。
+
+## 反馈
+
+插件有问题，按这个顺序：
+
+1. 开 Issue：https://github.com/taoziliyouchong/dsh-term-dict/issues —— 能留痕、能搜历史；
+2. 急着问或不想开 Issue，QQ 号：**2171960697**（加好友请注明装的是哪个插件）。
+
+反馈时带上：DSH 版本、插件版本、报错原文、截图。
+
+## 许可
+
+MIT