@kirkchinese/dsh-citeciter 0.3.2 → 0.4.1

package/README.md

@@ -1,39 +1,41 @@
 # `@kirkchinese/dsh-citeciter`
 
-A private learning companion for live DeepSeek Harness conversations. Select text from a committed assistant response, ask beside the source, and continue in an independent multi-turn Topic while the source Agent keeps working.
+Investigate any line in a DSH response—without stopping the Agent or changing the source Session. CiteCiter provides verifiable, source-bound, read-only side investigations for interactive DSH.
 
-[简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
+![Select a DSH response and continue investigating in a private CiteCiter Topic](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
 
-## Install
+*Select, right-click, and investigate beside the source while the main Agent keeps working.*
 
-CiteCiter requires Node.js `^22.19.0 || >=24.0.0`, DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8`, and a configured model provider.
+[简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
-```
+## Highlights
 
-Restart the corresponding DSH Web process and refresh the page after installation or upgrade.
+- **Exact source binding.** CiteCiter rechecks the visible selection against the committed response before creating a Topic.
+- **No need to wait.** A committed model response can be investigated while the surrounding Agent turn continues.
+- **Durable investigations.** Private Topics support natural follow-up questions and reopen after a refresh or restart.
+- **Evidence with no write access.** CiteCiter can inspect committed source events and search or read project files, but cannot change the source Session or workspace.
+- **Inspectable work.** Questions, answers, source reads, and project-file checks remain together in the investigation panel.
+- **Side-by-side workflow.** The conversation concedes space whenever the panel and a usable conversation fit; tighter layouts fall back to an overlay.
 
 ## Use
 
 1. Select text inside a committed assistant model call. The surrounding Agent turn may still be running.
 2. Right-click the selection, enter your first question, and choose `Citer!`.
-3. CiteCiter creates a new Topic in the learning dock.
+3. CiteCiter creates a new Topic in the investigation panel.
 4. Continue asking questions there, or reopen an earlier Topic from CiteCiter's Topic rail.
-5. Change the Topic model, reasoning effort, title, archive state, or dock width without changing the source Session.
+5. Change the Topic model, reasoning effort, title, archive state, or panel width without changing the source Session.
 
-## Highlights
+## Install v0.4.1
+
+CiteCiter 0.4.1 requires Node.js `^22.19.0 || >=24.0.0` and DSH `>=0.1.1-rc.1 <0.1.1-rc.3`.
+
+For DSH Web:
 
-- **Model-call citations.** Start as soon as an `assistant/message` is committed; there is no need to wait for the full Agent turn.
-- **Private Topics.** Each submission creates an independent DSH Session under `$DSH_HOME/citeciter/`, outside the ordinary Session list.
-- **Precise selections.** Visible Markdown selections map back to Host-verifiable source ranges.
-- **Cross-flow selections.** A range spanning reasoning, tools, and body text binds to its final committed assistant call while retaining the complete visible quote in the learning workspace.
-- **Bound evidence.** `read_source_session` reads committed events from one fixed source Session without exposing its physical log path.
-- **Open-ended investigation.** The standard read-only `glob` and `grep` tools discover project files and search their contents before `read` opens a known path.
-- **Read-only operation.** CiteCiter cannot write to the source Session or source workspace.
-- **Inspectable workflow.** Live reasoning, prompt injections, tool calls, results, and user questions use compact expandable rows inside the learning dock.
-- **Natural follow-ups.** After the first answer, the model may emit three strictly formatted next questions; malformed output creates no shortcuts and is logged silently.
-- **Native workflow.** The selection popover, resizable learning dock, active/archive Topic navigation, and settings remain inside the DSH programming interface.
+```sh
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.1
+```
+
+Restart DSH Web and refresh the page. Packaged Desktop adaptation is deferred; CiteCiter 0.4.1 does not provide a supported Desktop installation path.
 
 ## Context modes
 
@@ -41,14 +43,30 @@ Observer is the default. It creates an independent Topic and reads committed sou
 
 Exact Fork is an advanced mode for a source turn that has already ended. `exact-when-available` uses Exact Fork when a stable boundary exists and otherwise falls back to Observer.
 
-## Upgrade from v0.2
+## Compatibility and verification
+
+| Host | CiteCiter version | Status |
+|---|---|---|
+| DSH Web `0.1.1-rc.2` | `0.4.1` | Linux package, CI, upgrade, and assembled keyless browser checks passed; real-provider acceptance was not run |
+| [DSH Desktop 2.0.2](https://github.com/anywhere-labs/deepseek-harness-desktop) with bundled DSH `0.1.1-rc.2` | Future target | Adaptation and native acceptance are deferred; no packaged-Desktop compatibility claim |
+| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) development shell with DSH `0.1.1-rc.1` | `0.4.0` only | Historical conditional Linux source-shell evidence |
+| DSH Web `0.1.0-rc.7` | `0.3.2` | Previous stable line |
+| DSH TUI | — | Not supported yet |
+
+The demo uses a deterministic fixture to show the workflow; it is not real-provider or packaged-Desktop acceptance evidence.
+
+## Upgrade from an earlier version
+
+To install or upgrade v0.4.1 in Web:
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.1
 dsh plugin --profile web list --depth 0
 ```
 
-The upgrade does not rewrite source Sessions or import v0.2 Citation Threads. Existing child Sessions remain ordinary DSH data; new discussions use private v0.3 Topics.
+Packaged Desktop adaptation is deferred and is not part of the supported 0.4.1 upgrade path.
+
+Upgrading from v0.3 does not migrate or rewrite existing Topics, settings, or source Sessions. Users remaining on DSH `0.1.0-rc.7` should keep CiteCiter 0.3.2.
 
 ## Limitations
 
@@ -56,8 +74,21 @@ The upgrade does not rewrite source Sessions or import v0.2 Citation Threads. Ex
 - Renderer-generated KaTeX layout and footnote numbers cannot be cited directly because they lack stable source coordinates.
 - Exact Fork cannot start from an open source turn.
 - Source-file access depends on the running DSH filesystem service and remains read-only.
+- Read Frog translated selections are a best-effort compatibility path on DSH rc.1/rc.2 and activate only when its complete private marker set is present; ordinary DSH selection does not depend on Read Frog.
+- DSH does not yet expose a public additive right-dock contribution point. CiteCiter therefore uses a reversible private AppFrame grid adapter whenever the panel and conversation fit; it preserves the layout's details preference but temporarily hides that column while the investigation panel is open, and it must be retested for every supported DSH release.
+- Topics are Host-durable. When Desktop restarts on a different loopback port, CiteCiter falls back to the most recently updated Topic because browser local storage is origin-scoped; configure a fixed Desktop port to restore the exact last-viewed Topic.
+- CiteCiter 0.4.1 makes no packaged-Desktop compatibility claim; native Windows and macOS adaptation continues separately.
+- There is currently no TUI interaction adapter.
 - DSH is prerelease software; later DSH API versions may require a CiteCiter update.
 
+## Community
+
+Questions, workflow ideas, and compatibility reports are welcome in the DSH-Citeciter QQ group (`1108040435`).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="360" alt="QR code for the DSH-Citeciter QQ group 1108040435">
+</p>
+
 ## Contributing
 
 Issues and pull requests are welcome. Before submitting code, read the [contribution guide](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.md).

package/README.zh.md

@@ -1,39 +1,41 @@
 # `@kirkchinese/dsh-citeciter`
 
-服务于进行中 DeepSeek Harness 对话的独立学习伴侣。在已经提交的助手回答中选中文字，就地提问；来源 Agent 可以继续工作，讨论则在独立 Topic 中多轮进行。
+对 DSH 回复里的某一句追到底，不打断主 Agent，也不改变来源 Session。CiteCiter 为交互式 DSH 提供可核查、与来源精确绑定、只读的旁路调查。
 
-[English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
+![选中 DSH 回答后在 CiteCiter 私有 Topic 中继续调查](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
 
-## 安装
+*划选、右键、就地调查；主 Agent 继续工作。*
 
-CiteCiter 需要 Node.js `^22.19.0 || >=24.0.0`、DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8`，以及已经配置的模型提供方。
+[English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
-```
+## 核心能力
 
-安装或升级后，请重启对应的 DSH Web 进程并刷新页面。
+- **精确绑定来源。** 创建 Topic 前，CiteCiter 会把可见选区与已经提交的回答重新核对。
+- **不用等待主任务。** 一次模型回答提交后即可开始调查，外层 Agent 轮次可以继续运行。
+- **调查可以持续。** 私有 Topic 支持自然续问，刷新或重启后仍能重新打开。
+- **有证据、无写权限。** CiteCiter 能检查来源中已提交的事件，也能搜索和阅读项目文件，但不能改变来源 Session 或工作区。
+- **过程可检查。** 问题、回答、来源读取和项目文件核查都留在调查面板中。
+- **并排工作流。** 面板和可用主对话能同时容纳时，主对话会自动让出空间；更紧的布局才回退为覆盖模式。
 
 ## 使用
 
 1. 在一次已经提交的助手模型调用中选择文字；外层 Agent 轮次可以仍在运行。
 2. 右键选区，输入第一个问题，然后点击 `Citer!`。
-3. CiteCiter 在学习栏中创建一个新 Topic。
+3. CiteCiter 在调查面板中创建一个新 Topic。
 4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
-5. 独立调整模型、思考强度、标题、归档状态和学习栏宽度，不改变来源 Session。
+5. 独立调整模型、思考强度、标题、归档状态和面板宽度，不改变来源 Session。
 
-## 核心能力
+## 安装 v0.4.1
+
+CiteCiter 0.4.1 需要 Node.js `^22.19.0 || >=24.0.0` 与 DSH `>=0.1.1-rc.1 <0.1.1-rc.3`。
+
+DSH Web 使用：
 
-- **模型调用级引用。** `assistant/message` 一经提交即可开始，无需等待整个 Agent 轮次结束。
-- **私有 Topic。** 每次提交都会在 `$DSH_HOME/citeciter/` 下创建独立 DSH Session，不进入普通 Session 列表。
-- **精确选区。** 可见 Markdown 选区会映射回 Host 可复验的原文范围。
-- **跨流程选区。** 同时选中思考、工具与正文时，以选区中最后一个已提交模型回答作为可复验锚点，完整可见选区仍保留在学习栏中。
-- **绑定来源的证据。** `read_source_session` 只读取一个固定来源 Session 的已提交事件，不暴露物理日志路径。
-- **开放式项目调查。** 标准只读 `glob` 与 `grep` 先发现项目文件并搜索内容，再由 `read` 打开已知路径。
-- **只读运行。** CiteCiter 不能写入来源 Session 或来源工作区。
-- **可检查的对话流程。** 实时思考、提示词注入、工具调用、结果和用户提问都在学习栏中以紧凑可展开行显示。
-- **自然续问。** 第一轮回答完成后，模型可按严格格式给出三个后续问题；格式无效时前端不创建快捷入口，只记录日志。
-- **原生工作流。** 选区浮层、可调宽学习栏、活动/归档 Topic 导航和设置都保留在 DSH 编程界面内。
+```sh
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.1
+```
+
+安装后重启 DSH Web 并刷新页面。正式 Desktop 适配已经暂缓；CiteCiter 0.4.1 不提供受支持的 Desktop 安装路径。
 
 ## 上下文模式
 
@@ -41,14 +43,30 @@ Observer 是默认模式。它创建独立 Topic，并按需读取已经提交
 
 Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
 
-## 从 v0.2 升级
+## 兼容性与验证
+
+| 宿主 | CiteCiter 版本 | 状态 |
+|---|---|---|
+| DSH Web `0.1.1-rc.2` | `0.4.1` | Linux 包、CI、升级与组装 keyless 浏览器检查通过；真实提供方验收未运行 |
+| [DSH Desktop 2.0.2](https://github.com/anywhere-labs/deepseek-harness-desktop)（内置 DSH `0.1.1-rc.2`） | 后续目标 | 适配与原生验收暂缓；不声明正式 Desktop 安装包兼容性 |
+| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) 源码开发壳（内置 DSH `0.1.1-rc.1`） | 仅 `0.4.0` | 历史上的有条件 Linux 源码壳证据 |
+| DSH Web `0.1.0-rc.7` | `0.3.2` | 旧版稳定线 |
+| DSH TUI | — | 暂不支持 |
+
+动图使用确定性测试场景展示交互，不作为真实提供方或正式 Desktop 安装包验收证据。
+
+## 从旧版本升级
+
+在 Web 安装或升级 v0.4.1：
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.1
 dsh plugin --profile web list --depth 0
 ```
 
-升级不会改写来源 Session，也不会导入 v0.2 Citation Thread。旧子 Session 仍是普通 DSH 数据；新讨论使用私有 v0.3 Topic。
+正式 Desktop 适配已经暂缓，不属于 0.4.1 的受支持升级路径。
+
+从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
 
 ## 已知限制
 
@@ -56,8 +74,21 @@ dsh plugin --profile web list --depth 0
 - 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
 - Exact Fork 不能从仍在运行的来源轮次开始。
 - 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
+- Read Frog 翻译选区是 DSH rc.1/rc.2 上的 best-effort 兼容路径，仅在其完整私有标记同时存在时启用；普通 DSH 选区不依赖 Read Frog。
+- DSH 尚未提供公开的增量右侧 dock 布局扩展点。CiteCiter 因此在面板与主对话能够同时容纳时使用可逆的私有 AppFrame grid 适配器；它保留布局的 details 偏好，但在调查面板打开期间临时隐藏该列，并且每个受支持的 DSH 版本都必须重新验证。
+- Topic 由 Host 持久保存。Desktop 重启到不同 loopback 端口时，浏览器 localStorage 会因 origin 改变而失去精确指针，CiteCiter 将回退到最近更新的 Topic；需要精确恢复“上次查看”时应配置固定 Desktop 端口。
+- CiteCiter 0.4.1 不声明正式 Desktop 安装包兼容性；Windows 与 macOS 原生适配将另行继续。
+- 当前没有 TUI 交互适配器。
 - DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。
 
+## 交流与反馈
+
+欢迎加入 DSH-Citeciter QQ 群（群号 `1108040435`），交流使用方式、功能想法和兼容性问题。
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="360" alt="DSH-Citeciter QQ 群 1108040435 二维码">
+</p>
+
 ## 参与贡献
 
 欢迎提交 Issue 和 Pull Request。提交代码前请阅读[贡献文档](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.zh.md)。