dsh-agent-persona 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **A 人设 tab on the conversation page**: which persona the session matched, the system prompt it actually sent
+  (rendered and source views), and the full management UI in place.
+- **An explicit default persona** (`默认人设`): it takes every session no reach rule claimed, and only one persona
+  can hold the flag — marking a new one releases the previous.
+- **Interface preferences** — `编辑后自动保存`, `在对话页显示「人设」标签`, `注册到 dsh-better-sidebar` — stored in the
+  persona file's `prefs` field, so they share the data's scope; the browser keeps only a load-time mirror.
+- **A sidebar card** for `dsh-better-sidebar`, registered through that plugin's own service. The switch that
+  controls it is **not shown at all** when that plugin is absent.
+- **A Schemastery config**: `storePath`, `tuneProvider`, `tuneModel`, validated when the row loads.
+- **TypeScript sources with a build**: `src/**` compiles to `lib/`, and a generator derives the remote artifacts
+  (`src/remote.ts`, `src/typert.ts`) from the single endpoint list in `src/endpoints.ts`; `npm test` fails if the
+  generated files drift.
+
+### Changed
+
+- **A persona with no reach applies nowhere.** It used to act as a catch-all; a place-less persona is a draft now,
+  and where nothing matched the harness prompt stands. `默认人设` is the explicit way to ask for a fallback.
+- **Replace mode also drops the harness identity line**, not only the deployment's persona line.
+- Display preferences take effect immediately rather than on the next page load: the conversation view and the
+  sidebar card are registered and unregistered at runtime.
+
+### Fixed
+
+- The remote manifest is generated in the shape the mount consumes: an `id` per descriptor, a strict input codec,
+  `parameters: []` for the reads that take none, and the service name `agentPersona`.
+- The default flag survives a store round trip again — the reader no longer drops it — and a save whose payload
+  omits the flag keeps the stored value instead of clearing it.
+- The session view's own draft and dirty check cover the default flag, and its switch no longer calls a method
+  that only the settings component has. Together those made the switch look inert and let a save turn it off.
+
+## [0.1.0] - 2026-09-17
+
+### Fixed
+
+- 跳到最新 kept a fixed four-message window, so a turn where the agent answered several times pushed the user's
+  question out of it. The tail now returns everything from the **last user input** onwards (bounded at 60
+  messages while walking).
+- A message whose Markdown failed to render fell back to plain text **as a whole**, which is what made some
+  bubbles show raw Markdown. Messages are now split into bounded Markdown-safe chunks (blank-line boundaries,
+  never inside a code fence) and each chunk renders on its own: one awkward chunk degrades with a visible note,
+  the rest of the message still renders.
+- `npm test` now also runs a small client-side suite (`test/client-helpers.test.mjs`) that lifts the client's pure
+  helpers out of the source and asserts the splitter is lossless and fence-safe.
+
+- 跳到最新 did nothing: the runtime forwarded a hand-written subset of the history options and dropped ,
+  so the call degraded to a normal head read while the dialog labelled it as the tail. The forwarding is now an
+  exported, asserted .
+### Added
+
+- **展开全文 per bubble.** Every message now carries  (its event index in the log), so a message that was
+  clipped at 1000 characters offers 展开全文: one 
+  read replaces that single bubble with the full text (and 收起全文 puts the short text back without re-reading).
+  Nothing else in the dialog is re-fetched.
+### Changed
+
+- The per-message text cap is 1000 characters (clipping stays markdown-safe), and 跳到最新 no longer appends the
+  rest of the conversation: it walks to the end and replaces the view with the last exchange only, so one click
+  answers "what were we just talking about". 从头看 returns to the sequential view, whose footer states that it
+  reads from the beginning.
+### Fixed
+
+- **Empty sessions are no longer offered.** A session created with a preset but never typed into
+  (`sessionListMetadata.blank`, the same flag the sidebar hides on — found as a 5-event, 0.5 KB,
+  `agentPreset: 'cordis'` session) holds no conversation to give a persona, so the picker drops it and counts it
+  in the hidden tally.
+
+- **Sub-agent and archived sessions no longer appear in the picker.** A sub-agent session (spawned by the
+  model: `origin: 'subagent'` or `delegationDepth > 0`) and an archived one cannot be opened or typed into
+  from the sidebar, so listing them invited personas that could never apply. Archived ids come from the
+  workspace registry, falling back to the workspace store file. The page reports how many were hidden, so a
+  missing session is never a mystery.
+
+- **Sessions could not be read at all**: `sessionPersistence.open(id, access)` takes the access mode as a
+  second, required argument; the reader called `open(id)` and every candidate failed, so the conversation
+  dialog always reported "no reader". It now opens with `'read'` (never taking write ownership) and retries
+  id-only signatures for version tolerance.
+
+### Changed
+
+- **Resolution is specificity-first.** A session-id rule now outranks a workspace rule and an exact value
+  outranks a pattern (`targetSpecificity`); list order only breaks ties between equally specific rules. A persona
+  pointed at one exact session therefore beats a persona pointed at the whole directory, whatever the order.
+
+- The session picker shows how often each session was talked to (`sessionStats.turns` from the same
+  projection read as the title), beside the short id and age; picker menus are widened to fit that row.
+
+- The settings section paints its title and description (and a skeleton card list) before any host call
+  resolves, instead of showing a bare 「加载中…」; a mount race with the remote namespace retries briefly rather
+  than flashing an error.
+
+- Renamed the package from `dsh-workspace-persona` to **`dsh-agent-persona`** (settings page: 「Agent人设」).
+  Everything it writes now lives in `$DSH_HOME/dsh-agent-persona/`.
+- The collapsed card keeps only what reads at a glance — chevron, state dot, name, state, scope chips — and
+  reordering / duplicating / deleting moved into the card's `⋯` menu.
+
+### Added
+
+- **Exactly one persona per workspace or session.** A save that claims a place takes it away from the persona
+  that held it (exact values only, reported back to the page), and the pickers label places that are already
+  taken.
+- **Injection modes** `append` (default) and `replace`, implemented by listening to the
+  `system-prompt/assemble` waterfall and dropping the deployment's own `deployment:persona-prefix` line for
+  `replace`. A preset or subagent persona that shadowed the section is never overwritten.
+- **Session history**: pick a session, hit the button next to the picker, and read that conversation. Reads are
+  windowed (`sessionHistory({id, offset, events})`) so the log is never read up front: the page shows what it
+  got, reports 已显示 N 条, and only reads the next window when 继续加载 is pressed. Messages are capped at 4000
+  characters. Picker rows carry a short session id and the session's age on the right.
+- **Search** appears once a profile holds four or more personas and filters on name, workspace title/path and
+  session title/id, with an explicit 「没有匹配「…」的人设」 state.
+- **Drag to reorder**: a grip on each card header drags it to an absolute position (new `reorderPersona` remote
+  method, `reorderPersonas` is the exported pure function); the ⋯ menu's 上移/下移 stay as the keyboard path,
+  and dragging is disabled while a search filter is active so a drop target is never ambiguous.
+- **Conflicts are visible**: a persona whose exact row would be shadowed by an *earlier* persona's prefix /
+  regex / contains row gets a 「可能被覆盖」 tag (hover explains which rule wins), plus a summary line above the
+  list. Exact duplicates never reach this state — saving takes the claim over instead.
+- **The save shortcut is visible**: a ⌘S / Ctrl+S key chip sits next to the save button and the button carries
+  the same hint in its tooltip.
+- The persona counts are two tags — 「N 条人设」 and a success-toned 「N 条在用」 — instead of a sentence in the
+  meta line, and the store path moved to the right of them.
+- **Unsaved changes are visible**: the open card carries a 未保存 tag while its draft differs from what is
+  stored, and switching cards or collapsing reports 「改动没有保存」 in the status line instead of dropping it
+  silently.
+- The status line is sticky at the bottom of the page so save/error feedback stays visible while the list
+  scrolls; icon buttons grew from 24px to 28px hit targets.
+- The section header now matches the shipped settings pages exactly: an `<h2>` title at 18px/600, a 13px
+  `p` intro in the muted label colour, no leading icon (the count moved into the meta line). Measured side by
+  side against the official 「Agent 预设」 page in the same DOM: identical font size, weight and colour.
+- The page is titled with the Agent-preset glyph (the same one the settings shell uses for 「Agent 预设」); the
+  settings **nav** icon itself is the shell's and cannot be set by a plugin — `settings.section` accepts only
+  `id` / `order` / `label`, and the shell falls back to one generic glyph for every id it does not ship.
+- Creating a persona moved out of the page's top-right corner into a dashed **新建人设** row at the end of the
+  list (the conventional place for an "add" affordance), keyboard reachable via Enter/Space; the header is now
+  just the title and the count.
+- A collapsed card shows its scope on a **second line**, workspaces and sessions apart, with human names
+  (workspace titles, session titles) instead of raw paths; the picker marks a claimed target as 当前人设 when it
+  belongs to the persona being edited, instead of appearing to be someone else's.
+- The conversation dialog is a two-sided chat (your input right, the agent left, both in bubbles) and hides
+  plugin-injected user-side content — `AGENTS.md` (13k chars in a real session), runtime snapshots, the skill
+  catalog, goal rounds — reporting only 「已隐藏 N 条插件注入内容」.
+- The scope pickers can go back from 「自己输入…」 to the list, and the match mode only appears in that
+  manual mode.
+- Session entries in the picker are labelled with their DSH title, and with the session's first prompt (or
+  its latest prompt) when no title exists yet — all three come out of a **single read** of DSH's projection
+  cache. The dropdown never touches a session log: those are 2.6x-5.8x larger and zstd-compressed
+  append-only files that cannot be seeked.
+
+
+### Added
+
+- **Many personas, each scoped independently.** A persona is a first-class record
+  (`id` / `name` / `enabled` / `text` / `targets[]`), and every target is
+  `{ kind: 'workspace' | 'sessionId', match: 'exact' | 'prefix' | 'regex' | 'contains', value }`.
+- **Dropdown scope pickers.** The settings page fills its pickers from the host's
+  workspaces and from DSH's own sessions (newest first, with title, working
+  directory and a relative timestamp), so nobody has to type a path or a session
+  id. The two kinds are mutually exclusive per row — switching a row's type clears
+  its value — and "自己输入…" keeps the advanced match modes reachable.
+- **Resolution rules**: list order is priority (first match wins), rows inside one
+  persona are OR-ed, a persona with no rows is the default persona, a disabled
+  persona is skipped, and a matching persona with an empty text means "no persona
+  here".
+- **System-prompt injection** as section `agent-persona` at order 1
+  (`DEPLOYMENT_PERSONA_PREFIX + 1`), i.e. above the workspace `AGENTS.md`.
+- **One directory for the data**: `$DSH_HOME/dsh-agent-persona/` holds
+  `personas.json` and a `state.json` heartbeat. The data is re-read on every prompt
+  assembly (mtimeNs/size stamp), so an edit applies to the next message.
+- **AI rework** (polish / expand / compress / draft) that uses the model DSH itself
+  is set to use, overridable per deployment with `tuneProvider` / `tuneModel`. It
+  only ever produces a proposal.
+- **Zero runtime dependencies**: a plain ESM host half plus a hand-written
+  `__ModuleLoader__` client half (no build step), with 89 offline assertions in
+  `npm test`.
+
+[Unreleased]: https://github.com/awoodwhale/dsh-agent-persona/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/awoodwhale/dsh-agent-persona/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 awoodwhale
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,233 @@
+# dsh-agent-persona
+
+给不同的**工作区**、不同的**会话**，用不同的 system prompt 人设。
+
+[![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)
+
+[English](./README_EN.md)
+
+## 它能做什么
+
+一个 DSH 部署里常常同时跑着好几摊活：写前端、写文档、盯告警、做代码审查。它们需要不同的身份、口径和约束。
+这个插件把人设按**工作区**或**会话**分发出去，每一份都是 system prompt 里的一段：
+
+- **多个人设，各自声明适用范围**：一条人设可以同时用于若干个工作区目录和若干个会话；匹配方式有
+  完全一致、开头是、包含、正则匹配四种。
+- **越具体越优先**：会话 ID 的规则优先于工作区，精确优先于前缀/正则；只有具体度相同时才按列表顺序决定。
+- **显式默认人设**：可以把某一条标成「默认人设」，它会收下所有没被位置命中的会话 —— 同一时刻只允许一条。
+  不标就没有兜底，那些会话继续用 DSH 自带的 system prompt。
+- **一个位置只能属于一条人设**：把某个工作区/会话配给新人设时，原来占着它的那条会自动失去它，并告诉你从谁那里转来的。
+- **追加或替换**：保留 DSH 自带的身份提示、把人设接在后面，或者去掉那句身份提示只用人设。
+- **正文为空 = 这里不要人设**：给某个位置加一行、正文留空，就显式地在那里关掉人设。
+- **改完下一条消息生效**，不用重启（正文按文件时间戳在每次组装时重读）。
+
+三处界面，各管一件事：
+
+| 界面 | 位置 | 用途 |
+|---|---|---|
+| **设置页** | 设置 → Agent 人设 | 新建/编辑/删除/复制/排序人设；写正文、Markdown 预览、让 AI 改一版 |
+| **会话视图** | 对话页顶部的 **人设** 标签 | 看这条会话命中了哪条人设、**实际发出去的 system prompt**（渲染/源码两视图），以及就地管理全部人设 |
+| **侧边栏卡片** | dsh-better-sidebar 的右侧栏 | 把上面那个「人设」页面挂进右侧栏（需要装了该插件） |
+
+三个偏好开关（`编辑后自动保存` / `在对话页显示「人设」标签` / `注册到 dsh-better-sidebar`）在
+**管理页**与**设置 → 通用设置**里各有一份 —— 后一个位置不受这些开关影响，所以关掉显示位置后永远能从那里打开。
+
+## 为什么它压得住 AGENTS.md
+
+DSH 会把工作区指令（`AGENTS.md` 之类）变成一条 **user 角色**的消息，那条消息自己的导语就写着
+*"They do not override system, developer, or direct user instructions."* 而这个插件写的是
+**system prompt 的一个 section**（section 名 `agent-persona`，order 1，紧跟在身份行之后）。
+
+这个先后关系是框架定的，不是插件自己声明的 —— 也正因为如此，工作区里怎么改文件都动不了这层人设。
+
+## 装
+
+**实测过的 DSH 版本：`0.1.5-rc.1`（作者的开发环境）与 `0.1.5-rc.2`。** `package.json` 的 `dsh.compatibility`
+声明的就是这两项 —— 含义是"我们在这些版本上跑过"，**不是**对更早或更新版本做过兼容工作的承诺；
+其它版本请自行验证。
+
+侧边栏卡片还需要 **`dsh-better-sidebar`**：没装它时，「注册到 dsh-better-sidebar」这个开关不会出现
+（没有可注册的地方），插件其余功能照常。
+
+```bash
+dsh plugin --profile web add dsh-agent-persona
+```
+
+装完**重启一次 `dsh web`**：profile 的 bundles 只在启动时读取，插件行是从那里挂进去的。
+
+重启后能看到：
+
+- 设置左栏的 **Agent 人设**；
+- `cat ~/.dsh/dsh-agent-persona/state.json` —— 插件的加载心跳，写明了它加载了哪个文件、人设存哪、几条人设。
+
+仓库里也有本地安装脚本：`bash scripts/install.sh`（Windows 是 `scripts/install.ps1`）。
+
+卸载：`dsh plugin --profile web remove dsh-agent-persona`，重启即可；人设文件不会被删。
+
+## 用起来
+
+![人设列表](./docs/images/settings-list.png)
+
+点 **新建人设** → 在「适用范围」里加行，选工作区或会话 → 写正文 → 打开启用开关 → 保存。
+
+- **新建出来的人设默认停用**，所以多一条人设不会影响任何现有会话，配好了再开。
+- **适用范围**是一行一行加的。每行先选类型（**工作区目录** 或 **某个会话**），再从下拉框里挑具体是谁。
+  两种类型互斥：把一行从「工作区」切成「某个会话」，这一行原来选的值会被清掉，重新选。
+- 下拉框里的工作区来自 DSH 的工作区列表（带会话数），会话来自 DSH 的全部会话，按时间倒序，
+  带**标题**、工作目录和「几分钟前」—— 不记得 session id 是什么没关系，认标题就行。
+- 想用前缀、正则这类高级匹配，选 **自己输入…** 就会变成输入框。
+- 折叠状态下，卡片第二行分开列出这条人设用在了哪些**工作区**、哪些**会话**；**一个位置都没加**时写着
+  「未设置位置：不生效，该会话仍用 DSH 自带的 prompt」——那是停在草稿状态的人设，不是兜底。
+- 想让它兜底，就打开卡片里的 **默认人设** 开关；列表行上会出现绿色的「默认」标记。
+
+展开一张卡是这样：
+
+![展开编辑](./docs/images/settings-editor.png)
+
+### 看这条会话聊了什么
+
+下拉框旁边那个按钮会打开一个**只读**弹窗：左右气泡式对话（你的输入在右、Agent 的回复在左）。
+
+- **只显示你真正敲进去的内容**：工作区指令（`AGENTS.md`）、运行时上下文快照、skill 目录说明这类
+  **插件注入**的"看起来像用户消息"的东西一律不展示，弹窗顶部只写「已隐藏 N 条插件注入内容」，
+  不占位置，也不会让你困惑"这条我没说过"。
+- 消息过长会被截断，就地提供 **展开全文**（只重读这一条，换掉这一个气泡）与 **收起全文**。
+- **跳到最新** 只显示最后一个用户输入及之后的回复。
+
+### 对话页的「人设」标签
+
+![会话视图](./docs/images/view-persona.png)
+
+选中一条会话后，对话页顶部有 **人设 / 提示词 / 管理** 三个面板：
+
+- **人设**：这条会话命中了哪条人设、**依据是哪几条规则**（命中依据）、正文（Markdown 渲染），
+  以及它自己的状态标记（在用 / 已停用、是否默认人设、注入方式）；下面是一个就地编辑器
+  （名称、默认人设开关、注入方式、正文），改动后卡片头会出现「未保存 · 点击保存」。
+- **提示词**：这条会话**实际发出去的** system prompt，可以切换「渲染 / 源码」、复制、刷新。
+  没有命中任何人设时，这里显示的就是 DSH 原生注入的 prompt —— 不做任何特殊处理。
+- **管理**：与设置页同一套卡片（新建、启用/停用、编辑、排序、复制、删除），就地管理。
+
+### 三个偏好
+
+| 开关 | 默认 | 含义 | 生效时机 |
+|---|---|---|---|
+| 编辑后自动保存 | 关 | 停手约 1 秒自动保存编辑区内容 | 立即；切换到人设规则行（工作区/会话）时**不**自动保存，避免存下半截选择 |
+| 在对话页显示「人设」标签 | 开 | 是否注册对话页那个视图 | 立即（运行时注册/注销） |
+| 注册到 dsh-better-sidebar | 开 | 是否把「人设」页面注册进 dsh-better-sidebar 的右侧栏 | 立即；**没装该插件时这个开关不显示** |
+
+偏好存在人设文件的 `prefs` 字段里（不是浏览器），所以它和数据的可见范围一致；浏览器里只留一份镜像，
+供"加载时决定要不要注册视图"用。
+
+## 注入方式：追加还是替换
+
+| 方式 | 效果 |
+|---|---|
+| **追加**（默认） | 保留 DSH 自带的那句身份提示，这条人设接在它后面 |
+| **替换** | 去掉 DSH 自带的身份句（以及部署自己写的 persona 段），只用这条人设 |
+
+「替换」只动**部署自己写的**那句 persona；如果某个 Agent 预设在自己作用域里写了 persona（把这一段遮蔽了），
+插件不会去覆盖它 —— 别人的身份提示优先。
+
+## 匹配是怎么算的
+
+宿主在每次组装 system prompt 时按这个顺序过一遍：
+
+1. 人设停用了 → 跳过；
+2. 一条人设的**任意一行**匹配上，它就是候选，按"具体度"比较（会话 ID 3 分 > 工作区 1 分；精确 > 前缀/包含/正则）；
+3. 具体度相同 → 取列表里靠上的那条（顺序在卡片的 `⋯` 菜单里调）；
+4. **一个位置都没加的人设不参与匹配**（草稿态），除非它被标成「默认人设」；
+5. 谁都没命中 → 看有没有「默认人设」，有就用它，没有就不注入；
+6. 赢家的正文是空的 → 不注入任何人设（这是"这里明确不要人设"的表达方式）。
+
+四种匹配方式里只有 `完全一致` 会把路径归一化（`/a/project/` 和 `/a/project` 算同一个）；
+`开头是`、`包含`、`正则匹配` 都是拿你写的字符串直接比。值空着、正则写错、或者会话没有那个字段，
+都算「不匹配」，不会报错。
+
+## 文件与配置
+
+```
+~/.dsh/dsh-agent-persona/
+├── personas.json   # 人设数据 + 偏好，权限 600，原子写入
+└── state.json      # 加载心跳，每次加载时重写
+```
+
+正文里可以写 `{{model}}` 和 `{{cwd}}`，渲染时替换成当前的值；其他 `{{...}}` 会被去掉（未注册的变量会让
+整个组装抛错，所以这里做了保护）。
+
+配置项（Schemastery schema，加载时校验，写错类型会**加载失败**而不是被忽略）：
+
+| 配置 | 默认 | 说明 |
+|---|---|---|
+| `storePath` | `''` | 人设文件位置；留空即 `$DSH_HOME/dsh-agent-persona/personas.json` |
+| `tuneProvider` | `''` | AI 调优用哪个 provider；留空即 DSH 当前设置的模型 |
+| `tuneModel` | `''` | 同上，模型 id |
+
+### 多个 profile 各用自己的人设文件（可选）
+
+人设数据默认是**全局一份**（`$DSH_HOME/dsh-agent-persona/personas.json`，与其它插件的状态目录同一约定），
+所以同一台机器上的多个 profile 共用同一份人设。要让某个 profile 独立，在**该 profile** 的
+`cordis.patch.yml` 里覆盖它自己的路径（是覆盖字段，**不要**再 insert 一行）：
+
+```yaml
+# ~/.dsh/profiles/<该 profile>/cordis.patch.yml
+- id: agent-persona
+  config:
+    storePath: /Users/you/.dsh/profiles/<该 profile>/personas.json
+```
+
+也可以用 `DSH_HOME` 环境变量把整个 `~/.dsh` 指向别的目录（那样连会话记录、其它插件状态一起隔离）。
+当前生效的文件路径始终显示在「Agent 人设」页面的 meta 行上（`保存在 …`），不会出现"改了半天不知道改的是哪一份"。
+
+## AI 改一版用哪个模型
+
+默认用 **DSH 当前设置的模型**，设置页里的下拉框会把它预选好；想固定别的模型就用上面的 `tuneProvider`/`tuneModel`。
+AI 只产出建议稿，点「采用」或「追加」才会进编辑框，再点保存才落盘。
+
+## 几句实话
+
+- **人设是行为约束，不是安全边界**。它约束模型怎么说，不阻止模型用工具。
+- `personas.json` 就是个**普通文件**，任何有文件工具权限的会话都写得动它 —— 这个插件**没有**注册
+  `tools.guard`。真要「工作区里的会话改不动人设」，得在本机层面做：`chmod 400` + 换个属主，
+  或者把 DSH 跑在受限沙箱里。
+- 多处同时匹配时**只取第一条**，不拼接；规则是线性扫的，几十条没问题，几百条就该重新设计了。
+- 一个 profile 里只装一次。同一个进程挂两个同 id 的行会让组合起不来。
+- **测试的边界**：仓库里的测试是**单元测试 + 源码审计**（134 条宿主断言 + 15 条客户端断言 + 生成产物漂移校验），
+  它们保证逻辑与代码形状，**不驱动浏览器** —— 界面行为（视图渲染、开关、侧边栏卡片）目前靠人工核对。
+
+## 开发
+
+源码是 TypeScript，`lib/` 是构建产物（不进 git，`npm publish` 前由 `prepare` 构建）：
+
+```
+src/index.ts       host 半边：存储、匹配、system-prompt section、远程服务
+src/client.ts      client 半边：设置页 + 会话视图 + 侧边栏卡片（打包成单文件 lib/client.js）
+src/endpoints.ts   远程方法的单一来源（生成 src/remote.ts 与 src/typert.ts）
+scripts/           生成器 + 安装脚本
+test/              单元测试与源码审计
+docs/              架构、开发笔记、设计决策
+```
+
+```bash
+npm install
+npm run build        # generate:remote → tsc → esbuild（产出 lib/）
+npm run typecheck    # 两个 tsconfig 都不报错
+npm test             # 134 + 15 条断言 + 生成产物漂移校验
+dsh --profile web --dump-config | grep -c 'id: agent-persona'   # 组合自检，应输出 1
+```
+
+改代码之后怎么生效：
+
+- `src/**` 改完必须 **`npm run build`**（`lib/` 是产物）。
+- 客户端产物（`lib/client.js`）改**内容**：客户端会按内容重算，**刷新页面**即可；别改文件名。
+- 宿主产物（`lib/index.js`）改**内容**：ESM 按 URL 缓存模块，**不会**自动重载 —— 重启 `dsh web`。
+- `package.json` 的 `dsh.bundle.patch` 或 profile 的 `bundles` 有改动：必须重启。
+- 生成产物（`src/remote.ts`、`src/typert.ts`）**不要手改**：改 `src/endpoints.ts` 后跑
+  `npm run generate:remote`，`npm test` 会校验它们是否与来源一致。
+
+细节在 [docs/development.md](./docs/development.md)，内部结构在 [docs/architecture.md](./docs/architecture.md)。
+
+## 许可
+
+Apache-2.0，见 [LICENSE](./LICENSE)。