dsh-agent-persona 0.1.0

package/README_EN.md

@@ -0,0 +1,237 @@
+# dsh-agent-persona
+
+Different system-prompt personas for different **workspaces** and different **sessions**.
+
+[![npm](https://img.shields.io/npm/v/dsh-agent-persona)](https://www.npmjs.com/package/dsh-agent-persona)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+[![ci](https://github.com/awoodwhale/dsh-agent-persona/actions/workflows/ci.yml/badge.svg)](https://github.com/awoodwhale/dsh-agent-persona/actions/workflows/ci.yml)
+
+[中文](./README.md)
+
+Note: the settings UI is in Chinese. The code, docs and this file are English.
+
+## What it does
+
+A DSH deployment usually runs several jobs at once — frontend work, docs, alert triage, code review — and each
+wants its own identity, tone and constraints. This plugin hands each of them its own persona, injected as a
+**section of the system prompt**:
+
+- **Many personas, each with its own reach.** One persona can apply to several workspace directories and several
+  sessions; a match is `exact`, `prefix`, `contains` or `regex`.
+- **More specific wins.** A session-id rule beats a workspace rule, and `exact` beats `prefix`/`contains`/`regex`;
+  only equal specificity falls back to list order.
+- **An explicit default persona.** Mark one persona as the default and it takes every session nothing else claimed
+  — at most one at a time. With none marked, those sessions keep DSH's own system prompt.
+- **A place belongs to one persona.** Pointing a workspace or session at a new persona takes it away from whoever
+  held it, and the save reports whose claim moved.
+- **Append or replace.** Keep DSH's identity line and put the persona after it, or drop that line and use only the
+  persona.
+- **Empty text means "no persona here"** — add a rule for a place and leave the body empty to switch it off there.
+- **An edit applies to the next message.** No restart: the body is re-read per assembly by file stamp.
+
+Three surfaces, three jobs:
+
+| Surface | Where | What for |
+|---|---|---|
+| **Settings page** | Settings → Agent 人设 | Create, edit, delete, duplicate and reorder personas; write the body, preview Markdown, let AI rework it |
+| **Session view** | the **人设** tab on a conversation | Which persona this session matched and why, the **system prompt it actually sent** (rendered and source), and the same management UI inline |
+| **Sidebar card** | the right bar of `dsh-better-sidebar` | Puts that same view into the sidebar (needs that plugin installed) |
+
+Three preference switches (`编辑后自动保存` / `在对话页显示「人设」标签` / `注册到 dsh-better-sidebar`) appear both on the
+manage page and in **Settings → General** — the latter is not affected by them, so a display position can always
+be switched back on.
+
+## Why it outranks AGENTS.md
+
+DSH turns workspace instructions (`AGENTS.md` and friends) into a **user-role** message, and that message's own
+intro says *"They do not override system, developer, or direct user instructions."* This plugin writes a
+**system-prompt section** instead (section name `agent-persona`, order 1, right after the identity line).
+
+That ordering is the framework's, not something the plugin claims — which is also why editing files inside the
+workspace cannot touch this layer.
+
+## Install
+
+**Tested against DSH `0.1.5-rc.1` (the author's development environment) and `0.1.5-rc.2`.** That is what
+`package.json`'s `dsh.compatibility` declares — it means "we ran on these", not a promise of compatibility work
+for older or newer releases; please verify on yours.
+
+The sidebar card additionally needs **`dsh-better-sidebar`**: without it the `注册到 dsh-better-sidebar` switch is not
+shown at all (there is nothing to register into), and everything else works as usual.
+
+```bash
+dsh plugin --profile web add dsh-agent-persona
+```
+
+Then **restart `dsh web` once**: profile bundles are read at startup, and that is where the plugin row lives.
+
+After the restart:
+
+- the **Agent 人设** entry in settings;
+- `cat ~/.dsh/dsh-agent-persona/state.json` — the load heartbeat: which module was loaded, how many personas,
+  where the store is.
+
+Local install scripts live in `scripts/install.sh` and `scripts/install.ps1`.
+To remove: `dsh plugin --profile web remove dsh-agent-persona`, restart; the persona file is left alone.
+
+## Using it
+
+![persona list](./docs/images/settings-list.png)
+
+**New persona** → add rows under reach, pick a workspace or a session → write the body → switch it on → save.
+
+- A **new persona starts disabled**, so adding one changes nothing until you say so.
+- Reach is a list of rows. Each row picks a kind (**workspace directory** or **a session**) and then the target
+  from a dropdown; switching a row's kind clears its value.
+- The dropdowns come from DSH's own workspace and session lists — sessions carry their **title**, working
+  directory and "minutes ago", so you do not need to know a session id.
+- Boundaries like prefixes and regexes are available through **type it yourself…**.
+- A persona with **no rows applies nowhere** (it is a draft) unless it is marked as the default.
+
+### Reading what a session actually said
+
+The button next to the session dropdown opens a **read-only** transcript: your inputs on the right, the agent's
+replies on the left.
+
+- **Only what you actually typed.** Workspace instructions (`AGENTS.md`), runtime context snapshots, skill
+  directory notes — anything the harness or another plugin injected as a user-role message — are left out, with a
+  single line at the top saying how many were hidden.
+- Long messages are clipped; **展开全文** re-reads just that one and replaces that bubble, and **收起全文** puts the
+  short text back.
+- **跳到最新** shows only the last user input and everything after it.
+
+### The 人设 tab on a conversation
+
+![session view](./docs/images/view-persona.png)
+
+**人设 / 提示词 / 管理**:
+
+- **人设** — which persona matched, **which of its rules matched**, the body as Markdown, its own state markers
+  (in use / disabled, whether it is the default, its injection mode), and an inline editor (name, default switch,
+  injection mode, body). Editing shows 未保存 · 点击保存 in the card header.
+- **提示词** — the prompt this session **actually sent**, with rendered/source views, copy and refresh. With no
+  persona matched it shows DSH's own prompt verbatim.
+- **管理** — the same cards as the settings page, in place.
+
+### The three preferences
+
+| Switch | Default | Meaning | Takes effect |
+|---|---|---|---|
+| 编辑后自动保存 | off | Save the editor about a second after typing stops | Immediately; rule rows (workspace/session) deliberately do **not** autosave, so a half-made choice is never stored |
+| 在对话页显示「人设」标签 | on | Register the conversation view or not | Immediately (registered/unregistered at runtime) |
+| 注册到 dsh-better-sidebar | on | Register the card with the sidebar plugin | Immediately; **not shown at all when that plugin is absent** |
+
+Preferences live in the persona file's `prefs` field — not in the browser — so they share the data's scope. The
+browser keeps only a mirror, used to decide at load whether to register the views.
+
+## Injection mode: append or replace
+
+| Mode | Effect |
+|---|---|
+| **Append** (default) | DSH's own identity sentence stays; the persona follows it |
+| **Replace** | DSH's identity sentence and the deployment's own persona line are dropped; only this persona remains |
+
+Replace only touches what the deployment itself wrote. If an Agent preset shadows that section in its own scope,
+the plugin leaves it alone — someone else's identity wins.
+
+## How matching works
+
+On every assembly:
+
+1. disabled personas are skipped;
+2. any matching row makes a persona a candidate, compared by specificity (session id 3 vs workspace 1; exact beats
+   prefix/contains/regex);
+3. equal specificity falls back to list order (`⋯` → move up/down);
+4. a persona with **no rows does not take part** (draft), unless it is the marked default;
+5. nothing matched → use the default persona if one is marked, otherwise inject nothing;
+6. a winner whose body is empty injects nothing — that is how you say "no persona here".
+
+Only `exact` normalises paths (`/a/project/` equals `/a/project`); `prefix`, `contains` and `regex` compare the
+string you typed. Empty values, a broken regex, or a missing field on the session simply do not match — never an
+error.
+
+## Files and configuration
+
+```
+~/.dsh/dsh-agent-persona/
+├── personas.json   # personas + preferences, mode 600, written atomically
+└── state.json      # load heartbeat, rewritten on every load
+```
+
+The body may use `{{model}}` and `{{cwd}}`; other `{{...}}` are de-braced (an unregistered variable would make the
+whole assembly throw, so it is guarded here).
+
+Configuration (a Schemastery schema, validated at load — a wrong type **fails the load** instead of being ignored):
+
+| Config | Default | Meaning |
+|---|---|---|
+| `storePath` | `''` | Where personas live; empty means `$DSH_HOME/dsh-agent-persona/personas.json` |
+| `tuneProvider` | `''` | Provider for the AI-tuning button; empty means DSH's current model |
+| `tuneModel` | `''` | Model id for the same |
+
+### One store per profile (optional)
+
+The store is **global by default** (`$DSH_HOME/dsh-agent-persona/personas.json`, the same convention other plugins
+use for their state), so profiles on one machine share one set of personas. To separate a profile, override the
+path in **that profile's** `cordis.patch.yml` (override the field — do **not** insert another row):
+
+```yaml
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- id: agent-persona
+  config:
+    storePath: /Users/you/.dsh/profiles/<profile>/personas.json
+```
+
+`DSH_HOME` isolates everything at once (sessions, other plugins' state). The path in force is always on the
+Agent 人设 page (`保存在 …`), so it is never a mystery which file you are editing.
+
+## Honest notes
+
+- **A persona is a behavioural constraint, not a security boundary.** It shapes what the model says; it does not
+  stop tools.
+- `personas.json` is an **ordinary file**: any session with file tools can write it. This plugin does **not**
+  register a `tools.guard`. If you need "a conversation inside the workspace cannot change the persona", do it at
+  the machine level (`chmod 400` plus a different owner, or a restricted sandbox).
+- Only the **first** match is used — no concatenation. Matching is a linear scan; dozens of rules are fine,
+  hundreds want a redesign.
+- Install once per profile: two rows with the same id in one process make the composition fail.
+- **Test boundary**: the suite is unit tests plus source audits (134 host assertions, 15 client assertions, and a
+  generated-artifact drift check). It does not drive a browser — UI behaviour is checked by hand today.
+
+## Development
+
+Sources are TypeScript; `lib/` is build output (not in git, built by `prepare` before `npm publish`):
+
+```
+src/index.ts       host half: store, matching, the system-prompt section, the remote service
+src/client.ts      client half: settings page + session view + sidebar card (bundled to lib/client.js)
+src/endpoints.ts   single source for the remote surface (generates src/remote.ts and src/typert.ts)
+scripts/           the generator and install scripts
+test/              unit tests and source audits
+docs/              architecture, development notes, design decisions
+```
+
+```bash
+npm install
+npm run build        # generate:remote → tsc → esbuild (writes lib/)
+npm run typecheck    # both tsconfigs, no errors
+npm test             # 134 + 15 assertions plus the generated-artifact drift check
+dsh --profile web --dump-config | grep -c 'id: agent-persona'   # composition self-check, expects 1
+```
+
+How edits take effect:
+
+- **`src/**` always needs `npm run build`** — `lib/` is output.
+- Changing the **content** of the client artifact: the client recomposes, so **refresh the page**; do not rename
+  the file.
+- Changing the **content** of the host artifact: ESM caches modules by URL, so it does **not** reload — restart
+  `dsh web`.
+- Changes to `dsh.bundle.patch` or the profile's `bundles`: restart.
+- Never hand-edit the generated `src/remote.ts` / `src/typert.ts`: edit `src/endpoints.ts` and run
+  `npm run generate:remote`; `npm test` fails if they drift.
+
+More in [docs/development.md](./docs/development.md) and [docs/architecture.md](./docs/architecture.md).
+
+## License
+
+Apache-2.0, see [LICENSE](./LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle patch: mounts this package's host half as one Cordis loader row.
+#
+# The same row is the browser roster row — the package declares `dsh.client`, so
+# client-modules discovers `./lib/client.js` from this package's package.json and
+# serves it to the Web app.
+- insert:
+    - id: agent-persona
+      name: dsh-agent-persona