@kirkchinese/dsh-citeciter 0.2.1 → 0.3.1

package/README.md

@@ -1,81 +1,65 @@
 # `@kirkchinese/dsh-citeciter`
 
-**A learning companion grounded in an exact point of your DeepSeek Harness conversation.** Select text from a completed assistant reply, choose `Citer!`, ask your own question, and continue learning in a durable Citation Thread without writing to the source session.
+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.
 
-[中文说明](https://github.com/kirkchinese/CiteCiter/blob/main/packages/citeciter/README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
-
-> **Early development:** v0.2.0 introduced the durable Host+Client architecture; v0.2.1 fixes later-turn preparation when DSH treats an already-effective read-only switch as an idempotent no-op. APIs, compatibility, and installation details may still change. Issues and pull requests are welcome.
+[简体中文](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, 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.2.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
 ```
 
-Restart the corresponding DSH Web process and refresh the page. A restart is required after installation or upgrade because the Host and Typert manifests are loaded at process startup.
-
-The package declares DSH peers from `^0.1.0-rc.6`. Focused builds use the rc.6 package set; the v0.2 browser flow was also verified on a fresh DSH `0.1.0-rc.7` process.
+Restart the corresponding DSH Web process and refresh the page after installation or upgrade.
 
 ## Use
 
-1. Select text wholly inside one completed assistant response.
-2. Right-click and choose `Citer!`.
-3. Write a custom first question or use a quick question.
-4. Continue with genuine follow-up turns in the same Thread.
-5. Reopen, switch, rename, or archive Threads from the persistent launcher.
-
-Each Citation creates or reuses an isolated child session at the exact historical boundary. The main DSH session never changes and its log is not modified.
-
-## What v0.2 implements
-
-- **Exact historical fork.** The browser resolves `data-chat-anchor-key` through the source-session snapshot, requires a finalized assistant node in a closed turn, and forks at its real `anchorSeq`. Key text is never interpreted as an event sequence.
-- **Stable Citation identity.** Source session, anchor seq, exact UTF-16 range, selected text, and bounded surrounding evidence are canonicalized and hashed with SHA-256. Different ranges in one answer remain different Citations.
-- **Four separate model-input layers.** A scoped system Tutor, the inherited history prefix, durable user-role Citation Context, and genuine user questions retain distinct authority and persistence.
-- **Persistent multi-turn Threads.** The first question and follow-ups are normal child-session user messages. The panel shows only child-owned transcript rows, not inherited history or runtime-context plumbing.
-- **Recovery and organization.** Host projection data powers a persistent launcher, parent-grouped picker, page-reload/process-restart recovery, rename, switch, and supported workspace archive.
-- **Fail-closed isolation.** CiteCiter opens the concrete child without navigating the main GUI, requires matched admission plus durable successful `/permission read-only` settlement and a current read-only sandbox, validates Host lineage and Citation evidence, and guards model tool execution with an explicit allowlist.
-- **Parent noninterference.** Citation context, questions, answers, stop operations, errors, and titles belong to the child. Browser smoke checks that the source log's size and nanosecond mtime do not change.
-- **Safe rich answers.** Markdown, code, and KaTeX stream normally. Complete safe `svg` fences become inert data-URI images. Complete `html` fences use a script-free, network-free sandboxed iframe. Rejected or incomplete fences remain Markdown code blocks.
-- **Fiber-owned cleanup.** Host Agent effects, Client Remote mounts, slots, listeners, subscriptions, animation frames, and in-flight state are reversible. Late async work cannot reinstall state after disposal.
-
-## Input model
-
-```text
-system: Scoped CiteCiter Tutor
-history: exact source-session prefix through the selected assistant boundary
-user context: durable, quoted Citation JSON (untrusted data)
-user: the person's actual first question and follow-ups
-```
+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.
+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.
+
+## Highlights
 
-Citation text never receives system authority, even when it contains instruction-like prose, role-shaped JSON, HTML, or delimiters. The accepted architecture decision and real-model comparison are documented in [`docs/architecture/0001-model-input-layering.md`](https://github.com/kirkchinese/CiteCiter/blob/main/docs/architecture/0001-model-input-layering.md).
+- **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.
+- **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.
+- **Native workflow.** The selection popover, resizable learning dock, active/archive Topic navigation, and settings remain inside the DSH programming interface.
 
-## Compatibility and limitations
+## Context modes
 
-- DSH Web and completed `assistant-step` replies only; user messages, input fields, and arbitrary page text are ignored.
-- The selection must stay inside one assistant flow. Cross-message and cross-block Citations are not supported.
-- Archive hides a Thread through the DSH workspace archive set. CiteCiter has no unarchive UI; selecting the same Citation after archive may create a new active Thread.
-- The current read-only tool allowlist is intentionally conservative. `run_code` remains available for sandboxed analysis, but Host preparation durably verifies the read-only sandbox and every nested tool dispatch still passes the authoritative allowlist guard. A tool absent from the running DSH installation is unavailable.
-- Rich HTML/SVG rendering is intentionally conservative; rejected content falls back to visible source rather than executing.
-- No settings UI, localization framework, mobile-specific layout, or cross-platform browser CI yet.
-- DSH is still prerelease software; later DSH APIs may require a CiteCiter update.
+Observer is the default. It creates an independent Topic and reads committed source evidence on demand, including while the source turn is still running.
 
-## Development
+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.
 
-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.1
+dsh plugin --profile web list --depth 0
 ```
 
-The repository tracks `packages/citeciter/lib/`. The build removes stale top-level chunks before emitting the Host entry, Client bundle, strict Typert artifacts, and declarations. Reproducible model evaluation, disposable browser smoke, HMR checks, and publish gates are in the [verification guide](https://github.com/kirkchinese/CiteCiter/blob/main/docs/implementation-milestones.md).
+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.
+
+## Limitations
+
+- A selection must stay inside one committed assistant flow. Streaming fragments and cross-message selections are not supported.
+- 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.
+
+## 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).
 
-CiteCiter is published early so the community can help shape it. 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,100 +1,65 @@
 # `@kirkchinese/dsh-citeciter`
 
-**基于精确历史上下文的、隔离式学习伴侣。** 在 DeepSeek Harness（DSH）的一条已完成助手回复中选中文字，右键点击 `Citer!`，提出你真正想问的问题，并在持久 Citation Thread 中继续追问；源会话不会被写入。
+服务于进行中 DeepSeek Harness 对话的独立学习伴侣。在已经提交的助手回答中选中文字，就地提问；来源 Agent 可以继续工作，讨论则在独立 Topic 中多轮进行。
 
 [English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-> **开发状态：** v0.2.0 引入持久化 Host+Client 架构；v0.2.1 修复了 DSH 将已生效的 read-only 重复切换视为幂等 no-op 时，后续追问准备失败的问题。当前仍处于早期开发阶段，API、兼容范围和安装方式仍可能变化。
-
 ## 安装
 
-需要 Node.js `^22.19.0 || >=24.0.0`、DSH Web 和已配置的模型提供方。
+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.2.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.3.1
 ```
 
-安装或升级后，请重启对应的 DSH Web 进程并刷新页面。Host 与 Typert 清单在进程启动时加载，因此不能只替换浏览器 bundle。
-
-包声明的 DSH peer range 从 `^0.1.0-rc.6` 开始。focused build 使用 rc.6 包集；v0.2 浏览器全链路也在一个全新启动的 DSH `0.1.0-rc.7` 进程中通过验证。
+安装或升级后，请重启对应的 DSH Web 进程并刷新页面。
 
 ## 使用
 
-1. 在一条已经完成的助手回复内部选中文字。
-2. 右键点击 `Citer!`。
-3. 输入自定义首问，或选择一个快捷问题。
-4. 在同一 Thread 中继续真实的多轮追问。
-5. 通过常驻入口恢复、切换、重命名或归档 Thread。
-
-每条 Citation 都会在所选历史边界创建或复用一个隔离子会话。插件不会切换 DSH 主界面的当前会话，也不会修改源会话日志。
-
-## v0.2 已实现能力
-
-- **精确历史 fork。** 浏览器用 `data-chat-anchor-key` 在源会话 snapshot 中解析真实节点，要求它是已关闭轮次中的最终助手回复，再使用节点的真实 `anchorSeq` fork；绝不从 key 文本猜事件序号。
-- **稳定 Citation 身份。** 源会话、anchor seq、UTF-16 精确范围、原文和有界前后文按固定格式序列化并计算 SHA-256。同一回复中的不同选区仍是不同 Citation。
-- **四层模型输入。** 受限作用域的 system Tutor、fork 继承的精确历史、持久的 user-role Citation Context，以及真正的用户首问/追问保持不同的权限与持久性。
-- **持久多轮 Thread。** 首问和每次追问都是子会话中的普通用户消息。侧栏只展示 Thread 自己拥有的问答/错误，不把继承历史和 runtime-context 内部行混进聊天记录。
-- **恢复与组织。** Host projection 驱动常驻入口、按父会话分组的选择器、页面刷新/进程重启恢复、切换、重命名和 DSH workspace 归档。
-- **失败即关闭的隔离。** 插件在不导航主界面的情况下打开具体子会话，先要求命令确实匹配，再由 Host 等待 `/permission read-only` 持久成功结算并确认当前 sandbox 仍为只读；随后校验 lineage、边界和 Citation 证据，模型工具执行受显式 allowlist 保护。
-- **父日志零干扰。** Citation context、提问、回答、停止、错误和标题都属于子会话。浏览器 smoke 会比较源日志的文件大小和纳秒 mtime。
-- **富内容安全。** Markdown、代码和 KaTeX 正常流式显示；完整且安全的 `svg` 围栏成为惰性 data-URI 图片；完整 `html` 围栏进入禁脚本、禁网络的 sandbox iframe；不安全或未闭合内容回退为 Markdown 源码。
-- **Fiber 生命周期。** Host Agent 作用域、Client Remote、slot、listener、订阅、动画帧和异步状态都可逆；销毁后的延迟异步结果不能重新安装状态。
-
-## 模型输入结构
-
-```text
-system：仅作用于该 Thread 的 CiteCiter Tutor
-history：截至所选助手边界的精确源会话前缀
-user context：持久、被引用的 Citation JSON（不可信数据）
-user：用户真正输入的首问与后续追问
-```
+1. 在一次已经提交的助手模型调用中选择文字；外层 Agent 轮次可以仍在运行。
+2. 右键选区，输入第一个问题，然后点击 `Citer!`。
+3. CiteCiter 在学习栏中创建一个新 Topic。
+4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
+5. 独立调整模型、思考强度、标题、归档状态和学习栏宽度，不改变来源 Session。
 
-即使选中文本包含命令口吻、role JSON、HTML 或分隔符，它也不会获得 system 权限。架构决策与同题同模型真实对比见 [`docs/architecture/0001-model-input-layering.md`](https://github.com/kirkchinese/CiteCiter/blob/main/docs/architecture/0001-model-input-layering.md)。
+## 核心能力
 
-## 兼容性与已知限制
+- **模型调用级引用。** `assistant/message` 一经提交即可开始，无需等待整个 Agent 轮次结束。
+- **私有 Topic。** 每次提交都会在 `$DSH_HOME/citeciter/` 下创建独立 DSH Session，不进入普通 Session 列表。
+- **精确选区。** 可见 Markdown 选区会映射回 Host 可复验的原文范围。
+- **绑定来源的证据。** `read_source_session` 只读取一个固定来源 Session 的已提交事件，不暴露物理日志路径。
+- **开放式项目调查。** 标准只读 `glob` 与 `grep` 先发现项目文件并搜索内容，再由 `read` 打开已知路径。
+- **只读运行。** CiteCiter 不能写入来源 Session 或来源工作区。
+- **可检查的对话流程。** 实时思考、提示词注入、工具调用、结果和用户提问都在学习栏中以紧凑可展开行显示。
+- **原生工作流。** 选区浮层、可调宽学习栏、活动/归档 Topic 导航和设置都保留在 DSH 编程界面内。
 
-- 只支持 DSH Web 中已完成的 `assistant-step`；不处理用户消息、输入框或任意页面文本。
-- 选区必须完整位于同一助手 flow；暂不支持跨消息或跨 block Citation。
-- 归档使用 DSH workspace 全局归档集合隐藏 Thread。CiteCiter 暂无取消归档 UI；归档后再次选择同一 Citation 可能创建新的活跃 Thread。
-- 只读工具 allowlist 有意保持保守。`run_code` 只用于 sandbox 内分析；Host 准备阶段会持久确认 read-only sandbox，每次嵌套工具分派仍经过权威 allowlist guard。当前 DSH 未安装的工具自然不可用。
-- HTML/SVG 安全策略有意保守，被拒绝的内容显示源码而不执行。
-- 暂无设置 UI、完整国际化框架、移动端专项布局和跨平台浏览器 CI。
-- DSH 仍处于预发布阶段，后续 API 变化可能要求同步适配。
+## 上下文模式
 
-## 构建与验证
+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.1
+dsh plugin --profile web list --depth 0
 ```
 
-仓库跟踪 `packages/citeciter/lib/`。构建会先清理过期的顶层 hash chunk，再生成 Host 入口、Client bundle、严格 Typert 清单和 declaration。真实模型分层实验、临时 DSH_HOME 浏览器 smoke、HMR 检查和发布门禁见 [`docs/implementation-milestones.md`](https://github.com/kirkchinese/CiteCiter/blob/main/docs/implementation-milestones.md)。
+升级不会改写来源 Session，也不会导入 v0.2 Citation Thread。旧子 Session 仍是普通 DSH 数据；新讨论使用私有 v0.3 Topic。
 
-## 本地浏览器验证
+## 已知限制
 
-```sh
-pnpm --filter @kirkchinese/dsh-citeciter exec playwright install chromium
-rm -rf /tmp/citeciter-dsh-home
-mkdir -p /tmp/citeciter-dsh-home/profiles/node_modules/@kirkchinese
-ln -sfn "$(pwd)/packages/citeciter" \
-  /tmp/citeciter-dsh-home/profiles/node_modules/@kirkchinese/dsh-citeciter
-node packages/citeciter/dev/seed-smoke-session.mjs \
-  /tmp/citeciter-dsh-home "$(pwd)"
-DSH_HOME=/tmp/citeciter-dsh-home dsh --profile web \
-  --patch "$(pwd)/packages/citeciter/dev/patch.yml" --port 3907
-node packages/citeciter/dev/smoke.mjs \
-  http://127.0.0.1:3907 CiteCiter \
-  /tmp/citeciter-dsh-home/citeciter-smoke.json
-```
+- 选区必须完整位于一个已经提交的助手 flow；暂不支持流式片段和跨消息选区。
+- 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
+- Exact Fork 不能从仍在运行的来源轮次开始。
+- 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
+- DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。
 
-Smoke 使用真实渲染的 `14:assistant-step1:1` 节点和真实 `anchorSeq: 6`，验证自定义首问、持久投影、恢复、重命名、常驻入口、侧栏宽度、父日志 revision 与浏览器错误。临时 profile 没有模型凭据时，正常的 provider 错误也只会在 read-only、Remote 准备、Citation Context 和真实用户消息全部成功后出现。
+## 参与贡献
 
-## 贡献与许可证
+欢迎提交 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