@kirkchinese/dsh-citeciter 0.4.2 → 0.5.0

package/README.md

@@ -11,31 +11,38 @@ Investigate any line in a DSH response—without stopping the Agent or changing
 ## Highlights
 
 - **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.
+- **No need to wait.** A committed intermediate model call can be investigated while the surrounding Agent turn continues, including its reasoning or a selection spanning reasoning and answer text.
 - **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.
+- **Presenter Topics.** A read-only teacher can build a durable formula, diagram, table, or animation board through atomic tool commits while it explains.
 - **Side-by-side workflow.** The conversation concedes space whenever the panel and a usable conversation fit; tighter layouts fall back to an overlay.
+- **Web update notices.** CiteCiter checks npm's stable version and offers a copyable upgrade command without granting the browser package-management access.
 
 ## 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!`.
+1. Select answer or reasoning inside a committed assistant model call. When reasoning is collapsed, begin the selection on its disclosure row; the row represents the complete model call. The surrounding Agent turn may still be running.
+2. Right-click the selection, enter your first question, and choose `开始提问` or `开始讲解`.
 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 panel width without changing the source Session.
 
-## Install v0.4.2
+## Install v0.5.0
 
-CiteCiter 0.4.2 requires Node.js `^22.19.0 || >=24.0.0` and DSH `>=0.1.1-rc.1 <0.1.1-rc.3`.
+CiteCiter 0.5.0 requires Node.js `^22.19.0 || >=24.0.0` and DSH `>=0.1.1-rc.1 <0.1.1-rc.3`.
 
 For DSH Web:
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.2
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
+dsh plugin --profile web list --depth 0
 ```
 
-Restart DSH Web and refresh the page. Packaged Desktop adaptation is deferred; CiteCiter 0.4.2 does not provide a supported Desktop installation path.
+Confirm that the list shows `@kirkchinese/dsh-citeciter@0.5.0`, then restart DSH Web and refresh the page.
+
+CiteCiter 0.5.0 is Web-only.
+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.
 
 ## Context modes
 
@@ -43,41 +50,43 @@ 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.
 
-## Compatibility and verification
+## Presenter board
 
-| Host | CiteCiter version | Status |
-|---|---|---|
-| DSH Web `0.1.1-rc.2` | `0.4.2` | Linux package, regression tests, and real-browser selection 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 |
+Presenter Topics use the standard Agent loop plus a scoped `blackboard_apply` tool. A board batch becomes visible only after its paired tool result succeeds; a failed or interrupted batch leaves the previous board intact. Refresh and restart project the final board from the private Topic Session rather than storing a second mutable copy.
 
-The demo uses a deterministic fixture to show the workflow; it is not real-provider or packaged-Desktop acceptance evidence.
+## Web update notices
 
-## Upgrade from an earlier version
+The Web client checks npm's `latest` stable version without blocking startup. A newer version appears in a persistent upper-right card with `更新`, `下次一定`, and `不再提示`: the first action copies the standard Web Profile install command, the second hides that version for the current tab session, and the third disables future checks until the CiteCiter settings page enables them again. CiteCiter never runs the install command; execute it in a terminal and restart DSH Web.
 
-To install or upgrade v0.4.2 in Web:
+The first release containing the checker still needs one manual upgrade because an older installed build cannot run code it does not contain. Custom Web Profiles must replace `web` in the copied command. Check the newer release's DSH requirement before installing; the notice compares package versions and does not assert host compatibility. Desktop updates are outside this feature.
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.2
-dsh plugin --profile web list --depth 0
-```
+## Host developer API
+
+0.5.0 provides the v1 Host service `ctx.citeciterRuntime` (`create`, `ask`, `get`, `list`, and `delete`) and the `citeciter/topic-created`, `citeciter/topic-updated`, and `citeciter/topic-deleted` events. Browser entry registration, presets, and a separate client face remain planned for M4/M5, so frontend extension APIs are not stable yet.
+
+## Supported hosts
 
-Packaged Desktop adaptation is deferred and is not part of the supported 0.4.2 upgrade path.
+| Host | CiteCiter version | Notes |
+|---|---|---|
+| DSH Web `0.1.1-rc.1` and `0.1.1-rc.2` | `0.5.0` | Fresh-profile Linux package, assembled browser smokes, and a real DeepSeek provider run passed |
+| [DSH Desktop 2.0.2](https://github.com/anywhere-labs/deepseek-harness-desktop) with bundled DSH `0.1.1-rc.2` | Future target | Packaged Desktop installers have not been accepted yet |
+| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) development shell with DSH `0.1.1-rc.1` | `0.4.0` only | Historical Linux source-shell record |
+| DSH Web `0.1.0-rc.7` | `0.3.2` | Previous stable line |
+| DSH TUI | — | Not supported yet |
 
-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.
+The demo is only a workflow illustration. It is not packaged-Desktop acceptance evidence.
 
 ## Limitations
 
-- 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.
+- 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. A committed model call's reasoning disclosure row may represent that complete call.
 - 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.
+- Read Frog translated selections are only a compatibility fallback for DSH rc.1/rc.2 and only activate when the full private marker set is present.
+- DSH still has no public right-dock extension point. When side-by-side layout fits, CiteCiter temporarily adjusts the layout; every new DSH version needs that path retested.
 - 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.2 makes no packaged-Desktop compatibility claim; native Windows and macOS adaptation continues separately.
+- Permanent Topic deletion is owner maintenance over CiteCiter's fixed private JSONL root because DSH rc.2 has no Session deletion API. One active CiteCiter process must own a DSH home; sharing that home between live processes is unsupported.
+- CiteCiter 0.5.0 is Web-only; packaged Desktop support is still pending.
 - There is currently no TUI interaction adapter.
 - DSH is prerelease software; later DSH API versions may require a CiteCiter update.
 

package/README.zh.md

@@ -11,31 +11,38 @@
 ## 核心能力
 
 - **精确绑定来源。** 创建 Topic 前，CiteCiter 会把可见选区与已经提交的回答重新核对。
-- **不用等待主任务。** 一次模型回答提交后即可开始调查，外层 Agent 轮次可以继续运行。
+- **不用等待主任务。** 一次中间模型调用提交后即可开始调查，外层 Agent 轮次可以继续运行；思考内容和跨越“思考+回答”的选区也可以使用。
 - **调查可以持续。** 私有 Topic 支持自然续问，刷新或重启后仍能重新打开。
 - **有证据、无写权限。** CiteCiter 能检查来源中已提交的事件，也能搜索和阅读项目文件，但不能改变来源 Session 或工作区。
 - **过程可检查。** 问题、回答、来源读取和项目文件核查都留在调查面板中。
+- **讲解 Topic。** 只读老师可以在讲解时通过原子工具提交构建持久的公式、图形、表格或动画黑板。
 - **并排工作流。** 面板和可用主对话能同时容纳时，主对话会自动让出空间；更紧的布局才回退为覆盖模式。
+- **Web 更新提醒。** CiteCiter 检查 npm 中的稳定版本，并提供可复制的升级命令，无需给浏览器包管理权限。
 
 ## 使用
 
-1. 在一次已经提交的助手模型调用中选择文字；外层 Agent 轮次可以仍在运行。
-2. 右键选区，输入第一个问题，然后点击 `Citer!`。
+1. 在一次已经提交的助手模型调用中选择回答或思考内容；思考正文未展开时，可以从折叠行开始选择，该行代表该次完整模型调用。外层 Agent 轮次可以仍在运行。
+2. 右键选区，输入第一个问题，然后点击“开始提问”或“开始讲解”。
 3. CiteCiter 在调查面板中创建一个新 Topic。
 4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
 5. 独立调整模型、思考强度、标题、归档状态和面板宽度，不改变来源 Session。
 
-## 安装 v0.4.2
+## 安装 v0.5.0
 
-CiteCiter 0.4.2 需要 Node.js `^22.19.0 || >=24.0.0` 与 DSH `>=0.1.1-rc.1 <0.1.1-rc.3`。
+CiteCiter 0.5.0 需要 Node.js `^22.19.0 || >=24.0.0` 与 DSH `>=0.1.1-rc.1 <0.1.1-rc.3`。
 
 DSH Web 使用：
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.2
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
+dsh plugin --profile web list --depth 0
 ```
 
-安装后重启 DSH Web 并刷新页面。正式 Desktop 适配已经暂缓；CiteCiter 0.4.2 不提供受支持的 Desktop 安装路径。
+请确认列表显示 `@kirkchinese/dsh-citeciter@0.5.0`，然后重启 DSH Web 并刷新页面。
+
+CiteCiter 0.5.0 只提供 Web 安装路径。
+从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。
+仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
 
 ## 上下文模式
 
@@ -43,41 +50,43 @@ Observer 是默认模式。它创建独立 Topic，并按需读取已经提交
 
 Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
 
-## 兼容性与验证
+## 讲解黑板
 
-| 宿主 | CiteCiter 版本 | 状态 |
-|---|---|---|
-| DSH Web `0.1.1-rc.2` | `0.4.2` | Linux 包、回归测试与真实浏览器选区检查通过；真实提供方验收未运行 |
-| [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 | — | 暂不支持 |
+讲解 Topic 使用标准 Agent loop 和 scoped `blackboard_apply` 工具。黑板批次只在配对工具结果成功后显示；失败或中断批次保留此前画面。刷新和重启从私有 Topic Session 投影最终黑板，不存储第二份可变副本。
 
-动图使用确定性测试场景展示交互，不作为真实提供方或正式 Desktop 安装包验收证据。
+## Web 更新提醒
 
-## 从旧版本升级
+Web 客户端在不阻塞启动的情况下检查 npm `latest` 稳定版本。发现新版本后，右上角持久卡片提供 `更新`、`下次一定` 和 `不再提示`：第一个操作复制标准 Web Profile 安装命令，第二个操作在当前标签页会话内隐藏该版本，第三个操作关闭后续检查，直到在 CiteCiter 设置页重新开启。CiteCiter 不会执行安装命令；请在终端执行并重启 DSH Web。
 
-在 Web 安装或升级 v0.4.2：
+首次包含检查器的版本仍需手动升级一次，因为已经安装的旧构建无法运行尚未包含的代码。使用自定义 Web Profile 时需替换复制命令中的 `web`。安装前请核对新版对 DSH 的要求；提醒只比较包版本，不声明宿主兼容性。此功能不包含 Desktop 更新。
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.4.2
-dsh plugin --profile web list --depth 0
-```
+## Host 开发接口
+
+0.5.0 提供 Host 侧 v1 服务 `ctx.citeciterRuntime`（`create`、`ask`、`get`、`list`、`delete`）和 `citeciter/topic-created`、`citeciter/topic-updated`、`citeciter/topic-deleted` 事件。浏览器入口注册、preset 和独立客户端 face 仍在 M4/M5 计划内，因此前端扩展接口尚未稳定。
+
+## 支持范围
 
-正式 Desktop 适配已经暂缓，不属于 0.4.2 的受支持升级路径。
+| 宿主 | CiteCiter 版本 | 说明 |
+|---|---|---|
+| DSH Web `0.1.1-rc.1` 与 `0.1.1-rc.2` | `0.5.0` | 全新 profile Linux 包、组装浏览器冒烟与真实 DeepSeek 提供方验收通过 |
+| [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 | — | 暂不支持 |
 
-从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
+动图只是流程演示，不代表 Desktop 安装包验收结果。
 
 ## 已知限制
 
-- 选区中必须至少包含一个已经提交的助手模型回答；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。
+- 选区中必须至少包含一个已经提交的助手模型调用；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。已提交模型调用的思考折叠行可以代表该次完整调用。
 - 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
 - Exact Fork 不能从仍在运行的来源轮次开始。
 - 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
-- Read Frog 翻译选区是 DSH rc.1/rc.2 上的 best-effort 兼容路径，仅在其完整私有标记同时存在时启用；普通 DSH 选区不依赖 Read Frog。
-- DSH 尚未提供公开的增量右侧 dock 布局扩展点。CiteCiter 因此在面板与主对话能够同时容纳时使用可逆的私有 AppFrame grid 适配器；它保留布局的 details 偏好，但在调查面板打开期间临时隐藏该列，并且每个受支持的 DSH 版本都必须重新验证。
+- Read Frog 翻译选区只是 DSH rc.1/rc.2 的兼容补丁，只有完整私有标记都在时才会启用。
+- DSH 还没有公开的右侧 dock 扩展点。能并排显示时，CiteCiter 会临时调整布局；换到新的 DSH 版本后需要重新确认这一块。
 - Topic 由 Host 持久保存。Desktop 重启到不同 loopback 端口时，浏览器 localStorage 会因 origin 改变而失去精确指针，CiteCiter 将回退到最近更新的 Topic；需要精确恢复“上次查看”时应配置固定 Desktop 端口。
-- CiteCiter 0.4.2 不声明正式 Desktop 安装包兼容性；Windows 与 macOS 原生适配将另行继续。
+- DSH rc.2 没有 Session 删除 API，因此 Topic 永久删除是对 CiteCiter 固定私有 JSONL 根目录执行的所有者维护。一个 DSH home 只能由一个活动 CiteCiter 进程占用，不支持多个活动进程共享。
+- CiteCiter 0.5.0 只提供 Web 安装路径；Desktop 的正式安装包还没跟上。
 - 当前没有 TUI 交互适配器。
 - DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。