@kirkchinese/dsh-citeciter 0.3.1 → 0.4.0

package/README.md

@@ -1,15 +1,26 @@
 # `@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.
+Ask about any line in a DSH response—without stopping the agent or changing the source session. CiteCiter is a source-bound, read-only learning companion for sustained side questions.
+
+![Select a DSH response and continue asking in a private CiteCiter learning Topic](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
 
 [简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
+## Compatibility
+
+| Host | CiteCiter version | Status |
+|---|---|---|
+| DSH Web `0.1.1-rc.2` | `0.4.x` | Fully verified |
+| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) development shell with DSH `0.1.1-rc.1` | `0.4.x` | Linux source-shell verified; not a macOS/Windows installer claim |
+| DSH Web `0.1.0-rc.7` | `0.3.2` | Previous stable line |
+| DSH TUI | — | Not supported yet |
+
 ## Install
 
-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.
+CiteCiter 0.4.0 requires Node.js `^22.19.0 || >=24.0.0`, DSH `>=0.1.1-rc.1 <0.1.1-rc.3`, and a configured model provider.
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.0
 ```
 
 Restart the corresponding DSH Web process and refresh the page after installation or upgrade.
@@ -27,10 +38,12 @@ Restart the corresponding DSH Web process and refresh the page after installatio
 - **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.
 
 ## Context modes
@@ -39,21 +52,23 @@ 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
+## Upgrade from an earlier version
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.0
 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.
+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
 
-- A selection must stay inside one committed assistant flow. Streaming fragments and cross-message selections are not supported.
+- A selection must include at least one committed assistant model call. User-only ranges, tool-only ranges, and still-streaming fragments cannot anchor a Citation.
 - 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.
+- Desktop validation covers dataelement's Linux development shell; it does not claim packaged macOS or Windows installer testing.
+- There is currently no TUI interaction adapter.
 - DSH is prerelease software; later DSH API versions may require a CiteCiter update.
 
 ## Contributing

package/README.zh.md

@@ -1,15 +1,26 @@
 # `@kirkchinese/dsh-citeciter`
 
-服务于进行中 DeepSeek Harness 对话的独立学习伴侣。在已经提交的助手回答中选中文字，就地提问；来源 Agent 可以继续工作，讨论则在独立 Topic 中多轮进行。
+在 DSH 回复里划一句，旁边追问；主 Agent 继续工作，来源 Session 保持不变。CiteCiter 是与精确原文绑定、只读、可持续多轮追问的学习伴侣。
+
+![选中 DSH 回答后在 CiteCiter 私有学习 Topic 中继续追问](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
 
 [English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
+## 兼容性
+
+| 宿主 | CiteCiter 版本 | 状态 |
+|---|---|---|
+| DSH Web `0.1.1-rc.2` | `0.4.x` | 完整验证 |
+| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) 源码开发壳（内置 DSH `0.1.1-rc.1`） | `0.4.x` | Linux 源码壳验证；不代表 macOS/Windows 安装器实测 |
+| DSH Web `0.1.0-rc.7` | `0.3.2` | 旧版稳定线 |
+| DSH TUI | — | 暂不支持 |
+
 ## 安装
 
-CiteCiter 需要 Node.js `^22.19.0 || >=24.0.0`、DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8`，以及已经配置的模型提供方。
+CiteCiter 0.4.0 需要 Node.js `^22.19.0 || >=24.0.0`、DSH `>=0.1.1-rc.1 <0.1.1-rc.3`，以及已经配置的模型提供方。
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.0
 ```
 
 安装或升级后，请重启对应的 DSH Web 进程并刷新页面。
@@ -27,10 +38,12 @@ dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
 - **模型调用级引用。** `assistant/message` 一经提交即可开始，无需等待整个 Agent 轮次结束。
 - **私有 Topic。** 每次提交都会在 `$DSH_HOME/citeciter/` 下创建独立 DSH Session，不进入普通 Session 列表。
 - **精确选区。** 可见 Markdown 选区会映射回 Host 可复验的原文范围。
+- **跨流程选区。** 同时选中思考、工具与正文时，以选区中最后一个已提交模型回答作为可复验锚点，完整可见选区仍保留在学习栏中。
 - **绑定来源的证据。** `read_source_session` 只读取一个固定来源 Session 的已提交事件，不暴露物理日志路径。
 - **开放式项目调查。** 标准只读 `glob` 与 `grep` 先发现项目文件并搜索内容，再由 `read` 打开已知路径。
 - **只读运行。** CiteCiter 不能写入来源 Session 或来源工作区。
 - **可检查的对话流程。** 实时思考、提示词注入、工具调用、结果和用户提问都在学习栏中以紧凑可展开行显示。
+- **自然续问。** 第一轮回答完成后，模型可按严格格式给出三个后续问题；格式无效时前端不创建快捷入口，只记录日志。
 - **原生工作流。** 选区浮层、可调宽学习栏、活动/归档 Topic 导航和设置都保留在 DSH 编程界面内。
 
 ## 上下文模式
@@ -39,21 +52,23 @@ Observer 是默认模式。它创建独立 Topic，并按需读取已经提交
 
 Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
 
-## 从 v0.2 升级
+## 从旧版本升级
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.0
 dsh plugin --profile web list --depth 0
 ```
 
-升级不会改写来源 Session，也不会导入 v0.2 Citation Thread。旧子 Session 仍是普通 DSH 数据；新讨论使用私有 v0.3 Topic。
+从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
 
 ## 已知限制
 
-- 选区必须完整位于一个已经提交的助手 flow；暂不支持流式片段和跨消息选区。
+- 选区中必须至少包含一个已经提交的助手模型回答；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。
 - 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
 - Exact Fork 不能从仍在运行的来源轮次开始。
 - 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
+- Desktop 验证覆盖 dataelement 项目的 Linux 源码开发壳；尚未宣称 macOS 或 Windows 安装器实测。
+- 当前没有 TUI 交互适配器。
 - DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。
 
 ## 参与贡献