@kirkchinese/dsh-citeciter 0.3.0 → 0.3.2

package/README.md

@@ -1,108 +1,67 @@
 # `@kirkchinese/dsh-citeciter`
 
-**A private learning companion for live DeepSeek Harness conversations.** Select text from a committed assistant model call, ask beside the selection, and continue the discussion in an independent CiteCiter Topic while the source Agent keeps working.
+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.
 
-[中文说明](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
-
-> **Early development:** v0.3 replaces ordinary DSH child Threads with private Observer Topics. APIs, storage, compatibility, and installation details may still change.
+[简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
 ## Install
 
-CiteCiter requires Node.js `^22.19.0 || >=24.0.0`, DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8` (tested on `0.1.0-rc.7`), and a configured model provider.
+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.
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.0
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
 ```
 
-Restart the corresponding DSH Web process and refresh the page after installation or upgrade. The Host, Typert descriptors, and browser bundle are resolved when the process starts.
+Restart the corresponding DSH Web process and refresh the page after installation or upgrade.
 
 ## Use
 
 1. Select text inside a committed assistant model call. The surrounding Agent turn may still be running.
-2. Right-click, enter the first question in the selection popover, and choose `Citer!`.
-3. CiteCiter creates a new Topic for every submission and opens it in the wide learning dock.
-4. Continue with normal follow-up questions, or reopen an older Topic from CiteCiter's own Topic rail.
-5. Adjust the model, reasoning effort, title, archive state, and dock width without changing the source Session.
-
-The default mode is Observer. Exact Fork remains an advanced mode for a source turn that has already ended; `exact-when-available` uses Observer when that stable fork boundary does not exist.
-
-## What v0.3 implements
-
-- **Model-call citation boundary.** A committed `assistant/message` is enough to create an Observer Topic; CiteCiter does not wait for `turn/end`.
-- **Exact Markdown selections.** Rendered selections map through GFM source positions to the original Markdown. Emphasis, deletion, links, and code retain Host-verifiable UTF-16 ranges while the UI keeps the text the user actually saw.
-- **One submission, one Topic.** Repeating the same selection creates another private conversation instead of silently reusing an earlier one.
-- **Private standard DSH Sessions.** Topic logs use the DSH Session, Agent Loop, tool, title, and persistence services under CiteCiter-owned storage in `$DSH_HOME/citeciter/`; they do not appear in the ordinary Session list.
-- **Bound Observer evidence.** The Topic-only `read_source_session` tool reads structured committed events from its fixed source Session, records the captured seq, and never exposes the physical Session file to the model.
-- **Independent titles and model controls.** New Topics copy the source model route, generate a DSH title after the first prompt, and can later switch model and reasoning effort independently.
-- **Source-aware settings.** The DSH settings page controls the default context mode, source reasoning, optional read-only source-file access, dock width, and reopening the last Topic.
-- **Read-only execution.** The private Agent uses a read-only sandbox. Only `read_source_session` and, when enabled and available, the standard file `read` tool reach the model.
-- **Independent lifecycle.** Topics can be reopened, renamed, archived, restored, stopped, and continued without navigating or writing to the source Session.
-- **Safe rich answers.** Markdown, code, and KaTeX render normally. Conservative SVG and sandboxed HTML handling falls back to visible source when content is incomplete or unsafe.
-
-## Model input
-
-```text
-system: the Topic-scoped CiteCiter Tutor and read-only policy
-history: this Topic's own DSH history (plus a frozen prefix only in Exact Fork)
-user context: the durable Citation record, explicitly marked as untrusted evidence
-tool result: bounded source Session or source-workspace evidence read on demand
-user: the person's actual first question and follow-ups
-```
+2. Right-click the selection, enter your first question, and choose `Citer!`.
+3. CiteCiter creates a new Topic in the learning dock.
+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.
 
-Source text, reasoning, tool arguments, tool results, and workspace files remain untrusted evidence. They never receive system authority. See [ADR 0002](https://github.com/kirkchinese/CiteCiter/blob/main/docs/architecture/0002-observer-learning-companion.zh.md) for the product and storage decisions.
-
-## Upgrade from v0.2
+## Highlights
 
-Installing v0.3 replaces the plugin code but does not rewrite the source Sessions or v0.2 forked Citation Threads. Those older child Sessions remain ordinary DSH data and are not imported into the v0.3 Topic rail. New discussions use the private v0.3 store.
+- **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.
 
-Use a valid three-part version such as `0.3.0`, then verify the installed result rather than relying only on the package-manager completion line:
+## Context modes
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.0
-dsh plugin --profile web list --depth 0
-```
+Observer is the default. It creates an independent Topic and reads committed source evidence on demand, including while the source turn is still running.
 
-## Compatibility and limitations
+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.
 
-- CiteCiter supports DSH Web and selections contained in one committed assistant flow. Cross-message and cross-block selections are not supported.
-- KaTeX layout and footnote numbers are renderer-generated DOM without stable source-character coordinates, so selecting those elements does not open CiteCiter; ordinary text around a formula remains citable.
-- Observer sees only committed Session events. It cannot cite an unfinished streaming fragment that has not produced `assistant/message`.
-- Source reasoning is available only when it was recorded by the source provider and the CiteCiter setting remains enabled.
-- Source-file access requires the running DSH composition to provide its filesystem service; it remains read-only and can be disabled.
-- A missing source Session does not delete an existing Topic, but fresh source reads fail and the dock reports that the source is unavailable.
-- The interface currently uses Chinese product copy and has no complete localization or cross-platform browser CI.
-- DSH remains prerelease software; later DSH APIs may require a CiteCiter update.
-
-## Development
-
-From the repository root:
+## Upgrade from v0.2
 
 ```sh
-pnpm install
-pnpm run typecheck
-pnpm --dir packages/citeciter test
-pnpm run build
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
+dsh plugin --profile web list --depth 0
 ```
 
-The repository tracks `packages/citeciter/lib/`. Rebuild after changing source or build configuration, and inspect the real npm tarball before publishing.
+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.
 
-For browser work, use a disposable DSH home and a dynamically assigned port so an existing server on `3080` is never touched:
+## Limitations
 
-```sh
-CITECITER_DSH_ROOT="$(mktemp -d /tmp/citeciter-dsh.XXXXXX)"
-mkdir -p "$CITECITER_DSH_ROOT/profiles/node_modules/@kirkchinese"
-ln -s "$(pwd)/packages/citeciter" \
-  "$CITECITER_DSH_ROOT/profiles/node_modules/@kirkchinese/dsh-citeciter"
-node packages/citeciter/dev/seed-smoke-session.mjs \
-  "$CITECITER_DSH_ROOT" "$(pwd)"
-DSH_HOME="$CITECITER_DSH_ROOT" dsh --profile web \
-  --patch "$(pwd)/packages/citeciter/dev/patch.yml" --port 0
-```
+- 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.
+- DSH is prerelease software; later DSH API versions may require a CiteCiter update.
 
-Use the printed URL for browser inspection and stop only that disposable process.
+## Contributing
 
-## Contributing and license
+Issues and pull requests are welcome. Before submitting code, read the [contribution guide](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.md).
 
-Please open an [issue](https://github.com/kirkchinese/CiteCiter/issues) or submit a pull request. Contributor rules are in [AGENTS.md](https://github.com/kirkchinese/CiteCiter/blob/main/AGENTS.md).
+## License
 
 MIT © CiteCiter contributors

package/README.zh.md

@@ -1,108 +1,67 @@
 # `@kirkchinese/dsh-citeciter`
 
-**服务于进行中 DeepSeek Harness 对话的独立学习伴侣。** 在一次已经提交的助手模型调用中选中文字，就地提问；来源 Agent 可以继续工作，讨论则在独立的 CiteCiter Topic 中多轮进行。
+服务于进行中 DeepSeek Harness 对话的独立学习伴侣。在已经提交的助手回答中选中文字，就地提问；来源 Agent 可以继续工作，讨论则在独立 Topic 中多轮进行。
 
 [English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-> **开发状态：** v0.3 用独立 Observer Topic 取代了普通 DSH 子 Thread。API、存储、兼容范围和安装方式仍可能变化。
-
 ## 安装
 
-需要 Node.js `^22.19.0 || >=24.0.0`、DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8`（当前验证线为 `0.1.0-rc.7`）和已经配置的模型提供方。
+CiteCiter 需要 Node.js `^22.19.0 || >=24.0.0`、DSH Web `>=0.1.0-rc.7 <0.1.0-rc.8`，以及已经配置的模型提供方。
 
 ```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.0
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
 ```
 
-安装或升级后，请重启对应的 DSH Web 进程并刷新页面。Host、Typert 描述和浏览器 bundle 都在进程启动时解析。
+安装或升级后，请重启对应的 DSH Web 进程并刷新页面。
 
 ## 使用
 
 1. 在一次已经提交的助手模型调用中选择文字；外层 Agent 轮次可以仍在运行。
-2. 右键，在选区旁的浮层输入第一个问题，然后点击 `Citer!`。
-3. CiteCiter 为每次提交创建一个新 Topic，并在宽学习栏中打开它。
-4. 继续普通多轮追问，或从 CiteCiter 自己的 Topic 栏恢复旧讨论。
+2. 右键选区，输入第一个问题，然后点击 `Citer!`。
+3. CiteCiter 在学习栏中创建一个新 Topic。
+4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
 5. 独立调整模型、思考强度、标题、归档状态和学习栏宽度，不改变来源 Session。
 
-默认模式是 Observer。Exact Fork 是来源轮次已经结束时使用的高级模式；`exact-when-available` 在不存在稳定 fork 边界时使用 Observer。
-
-## v0.3 已实现能力
-
-- **模型调用级引用。** 已提交的 `assistant/message` 足以创建 Observer Topic，不需要等待 `turn/end`。
-- **精确 Markdown 选区。** 渲染后的可见选区会通过 GFM 源位置映射回原始 Markdown；强调、删除线、链接和代码中的引用都保留 Host 可复验的 UTF-16 范围，UI 仍显示用户看到的文字。
-- **一次提交一个 Topic。** 即使选区相同，再次提交也会创建另一条独立对话，不会静默复用旧讨论。
-- **独立的标准 DSH Session。** Topic 在 `$DSH_HOME/citeciter/` 下使用 DSH Session、Agent Loop、工具、标题和持久化服务，不进入普通 Session 列表。
-- **绑定来源的 Observer 证据。** Topic 专属的 `read_source_session` 只读取固定来源 Session 的结构化已提交事件，记录实际捕获 seq，并且不向模型暴露物理 Session 文件。
-- **独立标题和模型控制。** 新 Topic 复制来源模型路由，在首问后通过 DSH 标题流程生成标题，之后可以独立切换模型和思考强度。
-- **来源与界面设置。** DSH 设置页可以配置默认上下文模式、来源 reasoning、可选的只读来源文件访问、学习栏宽度和是否恢复上次 Topic。
-- **只读执行。** 独立 Agent 使用 read-only sandbox。只有 `read_source_session`，以及启用且可用时的标准文件 `read` 工具会提供给模型。
-- **独立生命周期。** Topic 可以恢复、重命名、归档、取消归档、停止和继续，而不导航或写入来源 Session。
-- **安全富文本。** Markdown、代码和 KaTeX 正常渲染；保守的 SVG 与沙箱 HTML 处理会在内容不完整或不安全时显示源码。
-
-## 模型输入结构
-
-```text
-system：Topic 作用域的 CiteCiter Tutor 与只读策略
-history：该 Topic 自己的 DSH 历史；只有 Exact Fork 额外带冻结前缀
-user context：持久 Citation 记录，并明确标记为不可信证据
-tool result：按需读取的有界来源 Session 或来源工作区证据
-user：用户真正输入的首问和后续问题
-```
-
-来源文本、reasoning、工具参数、工具结果和工作区文件始终是不可信证据，不会获得 system 权限。产品与存储决定见 [ADR 0002](https://github.com/kirkchinese/CiteCiter/blob/main/docs/architecture/0002-observer-learning-companion.zh.md)。
-
-## 从 v0.2 升级
-
-安装 v0.3 会替换插件代码，但不会改写来源 Session 或 v0.2 fork 出来的 Citation Thread。旧子 Session 仍是普通 DSH 数据，不会导入 v0.3 Topic 栏；新讨论使用 v0.3 独立存储。
-
-请使用 `0.3.0` 这样的合法三段版本号，并检查实际安装结果，不要只依赖包管理器显示的完成提示：
+## 核心能力
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.0
-dsh plugin --profile web list --depth 0
-```
+- **模型调用级引用。** `assistant/message` 一经提交即可开始，无需等待整个 Agent 轮次结束。
+- **私有 Topic。** 每次提交都会在 `$DSH_HOME/citeciter/` 下创建独立 DSH Session，不进入普通 Session 列表。
+- **精确选区。** 可见 Markdown 选区会映射回 Host 可复验的原文范围。
+- **跨流程选区。** 同时选中思考、工具与正文时，以选区中最后一个已提交模型回答作为可复验锚点，完整可见选区仍保留在学习栏中。
+- **绑定来源的证据。** `read_source_session` 只读取一个固定来源 Session 的已提交事件，不暴露物理日志路径。
+- **开放式项目调查。** 标准只读 `glob` 与 `grep` 先发现项目文件并搜索内容，再由 `read` 打开已知路径。
+- **只读运行。** CiteCiter 不能写入来源 Session 或来源工作区。
+- **可检查的对话流程。** 实时思考、提示词注入、工具调用、结果和用户提问都在学习栏中以紧凑可展开行显示。
+- **自然续问。** 第一轮回答完成后，模型可按严格格式给出三个后续问题；格式无效时前端不创建快捷入口，只记录日志。
+- **原生工作流。** 选区浮层、可调宽学习栏、活动/归档 Topic 导航和设置都保留在 DSH 编程界面内。
 
-## 兼容性与限制
+## 上下文模式
 
-- CiteCiter 支持 DSH Web，以及完整位于一个已提交助手 flow 内的选区；暂不支持跨消息或跨 block 引用。
-- KaTeX 排版和脚注编号是渲染器生成的 DOM，没有稳定的原文字符坐标，因此直接选中这些元素不会打开 CiteCiter；公式周围的普通文本仍可引用。
-- Observer 只能看到已经提交的 Session 事件，不能引用尚未形成 `assistant/message` 的流式片段。
-- 只有来源提供方实际记录了 reasoning 且 CiteCiter 设置保持开启时，来源 reasoning 才可读取。
-- 来源文件访问要求当前 DSH 组合提供文件系统服务；它始终只读，并且可以关闭。
-- 来源 Session 缺失不会删除已有 Topic，但新的来源读取会失败，学习栏会显示来源不可用。
-- 界面目前使用中文产品文案，尚无完整国际化和跨平台浏览器 CI。
-- DSH 仍处于预发布阶段，后续 DSH API 变化可能要求同步更新 CiteCiter。
+Observer 是默认模式。它创建独立 Topic，并按需读取已经提交的来源证据；来源轮次仍在运行时也可以使用。
 
-## 构建与验证
+Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
 
-在仓库根目录运行：
+## 从 v0.2 升级
 
 ```sh
-pnpm install
-pnpm run typecheck
-pnpm --dir packages/citeciter test
-pnpm run build
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.2
+dsh plugin --profile web list --depth 0
 ```
 
-仓库跟踪 `packages/citeciter/lib/`。修改源码或构建配置后必须重新构建，并在发布前检查真实 npm tarball。
+升级不会改写来源 Session，也不会导入 v0.2 Citation Thread。旧子 Session 仍是普通 DSH 数据；新讨论使用私有 v0.3 Topic。
 
-浏览器开发应使用一次性 DSH home 和动态端口，绝不触碰已经运行在 `3080` 的服务：
+## 已知限制
 
-```sh
-CITECITER_DSH_ROOT="$(mktemp -d /tmp/citeciter-dsh.XXXXXX)"
-mkdir -p "$CITECITER_DSH_ROOT/profiles/node_modules/@kirkchinese"
-ln -s "$(pwd)/packages/citeciter" \
-  "$CITECITER_DSH_ROOT/profiles/node_modules/@kirkchinese/dsh-citeciter"
-node packages/citeciter/dev/seed-smoke-session.mjs \
-  "$CITECITER_DSH_ROOT" "$(pwd)"
-DSH_HOME="$CITECITER_DSH_ROOT" dsh --profile web \
-  --patch "$(pwd)/packages/citeciter/dev/patch.yml" --port 0
-```
+- 选区中必须至少包含一个已经提交的助手模型回答；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。
+- 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
+- Exact Fork 不能从仍在运行的来源轮次开始。
+- 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
+- DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。
 
-使用命令打印的 URL 进行浏览器检查，并且只停止这个一次性进程。
+## 参与贡献
 
-## 贡献与许可证
+欢迎提交 Issue 和 Pull Request。提交代码前请阅读[贡献文档](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.zh.md)。
 
-请到 [GitHub](https://github.com/kirkchinese/CiteCiter) 提交 Issue 或 Pull Request，并先阅读仓库 [AGENTS.md](https://github.com/kirkchinese/CiteCiter/blob/main/AGENTS.md)。
+## 许可证
 
 MIT © CiteCiter contributors