super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/superpowers/plans/2026-10-03-docs-packaging-trim.md

@@ -0,0 +1,181 @@
+# 发布包瘦身：docs-packaging-trim — 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 发布副本不再携带与 DSH / 本插件无关的材料（别家框架的文档镜像、技能未引用的第三方资料、抓取工具与构建清单），tarball 20.2 MB → ≈3.7 MB、安装后 docs 磁盘 98 MB → ≈15 MB，repo 的 `docs/` 一字不动。
+
+**Architecture:** 只改 `scripts/copy-docs.mjs` 的 EXCLUDE 过滤集。为了可测，把 EXCLUDE 数组从直跑脚本改为**可导入的具名导出**，主流程用 `import.meta.url` 判定是否被 CLI 调用 —— 既有行为零变化，新增纯数据测试面。
+
+**Tech Stack:** 无新依赖。纯 Node `fs` + 正则。
+
+**Spec:** `docs/specs/docs-packaging-trim/spec.md`（含全树盘点表与档位 F 的实测数字）
+
+## Global Constraints
+
+- **repo 的 `docs/` 一字不动**：只改写发布副本 `better-dsh/docs/`。
+- 承重面完好：`docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/`（含 `SKILL.md`）、`src/docs/`、`src/site-pages-map.txt` 必须保留。
+- 规则按**路径前缀锚定**（`dsh-dev-skill/…`），不做裸名匹配，防误伤同名目录。
+- 已知例外（明示接受，不修）：发布副本里 `dsh-dev-skill/src-README.md` 会提到不在包内的 `src-scripts/`，无功能影响。
+- 每个 Task 结束 `tsc --noEmit` 0 错 + 相关单测绿 + commit。
+
+---
+
+### Task 1: EXCLUDE 规则 + 可测化
+
+**Files:**
+- Modify: `scripts/copy-docs.mjs`
+- Test: `test/packaging/copy-docs-exclude.spec.ts`
+
+**Interfaces:**
+- Produces: `EXCLUDE: readonly RegExp[]`（含既有 4 条 + 新增 3 条）；`excluded(srcPath: string): boolean`。
+
+- [ ] **Step 1: 写失败测试**
+
+`test/packaging/copy-docs-exclude.spec.ts`：
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { EXCLUDE, excluded } from '../../scripts/copy-docs.mjs'
+
+describe('copy-docs EXCLUDE (docs-packaging-trim, 档位 F)', () => {
+  it('drops the foreign doc mirror entirely', () => {
+    expect(excluded('docs/80_upstream-docs-and-skills/hermes-dev-skill/src/api-skills.json')).toBe(true)
+    expect(excluded('docs/80_upstream-docs-and-skills/hermes-dev-skill/src-README.md')).toBe(true)
+  })
+  it('drops the uncited third-party reference and the fetch tooling', () => {
+    expect(excluded('docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/x.md')).toBe(true)
+    expect(excluded('docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/.tools/omp_extracted.json')).toBe(true)
+    expect(excluded('docs/80_upstream-docs-and-skills/dsh-dev-skill/src-scripts/docs-tree.json')).toBe(true)
+    expect(excluded('docs/80_upstream-docs-and-skills/dsh-dev-skill/src-scripts/crawl.py')).toBe(true)
+  })
+  it('keeps every load-bearing path', () => {
+    for (const p of [
+      'docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md',
+      'docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch02-plugin-basics.md',
+      'docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/architecture.md',
+      'docs/80_upstream-docs-and-skills/dsh-dev-skill/src/site-pages-map.txt',
+      'docs/50_test-reports/x.md',
+      'docs/20_specs/ast/spec.md',
+      'docs/specs/ast-engine-deomp/spec.md',
+    ]) expect(excluded(p), p).toBe(false)
+  })
+  it('keeps the pre-existing rules working', () => {
+    expect(excluded('docs/60_exploration-and-research/a.md')).toBe(true)
+    expect(excluded('docs/superd/x.md')).toBe(true)
+    expect(excluded('docs/dsh-sys-prompt_20260910.md')).toBe(true)
+  })
+  it('exports the rules for audit', () => {
+    expect(EXCLUDE).toHaveLength(7)
+  })
+})
+```
+
+Run: `npx vitest run test/packaging/copy-docs-exclude.spec.ts`
+Expected: FAIL（模块没有 `EXCLUDE`/`excluded` 导出）
+
+- [ ] **Step 2: 改写脚本**
+
+`scripts/copy-docs.mjs` 顶部改为：
+
+```js
+import { cpSync, rmSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+/** Path fragments excluded from the shipped copy (matched against source path). */
+export const EXCLUDE = [
+  /(^|\/)60_exploration-and-research($|\/)/,
+  /(^|\/)superd($|\/)/,
+  /(^|\/)dsh-sys-prompt_[^/]*\.md$/,
+  /(^|\/)[^/]*_artifacts($|\/)/,
+  // docs-packaging-trim（docs/specs/docs-packaging-trim/spec.md，档位 F）：
+  //   摘掉与 DSH / 本插件无关的材料。repo 的 docs/ 一字不动，只影响发布副本。
+  /(^|\/)hermes-dev-skill($|\/)/,                    // 别家框架文档镜像；抓取阶段产物，无 SKILL.md
+  /(^|\/)dsh-dev-skill\/pi-and-omp($|\/)/,           // OMP/Pi 第三方资料；技能正文零引用
+  /(^|\/)dsh-dev-skill\/src-scripts($|\/)/,          // 抓取工具 + 3.5MB 构建清单
+]
+
+/** True when a repo-relative source path must NOT enter the published copy. */
+export function excluded(srcPath) {
+  return EXCLUDE.some(re => re.test(srcPath))
+}
+```
+
+原 `cpSync('../docs', 'docs', { recursive: true, filter: … })` 的 filter 改为 `src => !excluded(relativeSrc(src))`，其中：
+
+```js
+const relativeSrc = (src) => src.replace(/^\.\.\//, '').replace(/^\.\.\\/, '')
+```
+
+（若原 filter 已是等价实现，仅把判定函数换名，别改目录遍历方式。）
+
+文件末尾把原直跑主体包进：
+
+```js
+const invokedAsCli = process.argv[1] !== undefined
+  && import.meta.url === pathToFileURL(process.argv[1]).href
+if (invokedAsCli) {
+  // …原有 rmSync + cpSync + 脱敏 walk 逻辑原样…
+}
+```
+
+- [ ] **Step 3: 跑测试确认通过**
+
+Run: `npx vitest run test/packaging/copy-docs-exclude.spec.ts`
+Expected: PASS
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add scripts/copy-docs.mjs test/packaging/copy-docs-exclude.spec.ts
+git commit -m "build(packaging): drop foreign docs, uncited references, and fetch tooling from the published copy"
+```
+
+---
+
+### Task 2: 构建验证 + 量化 + 报告
+
+**Files:**
+- Create: `docs/50_test-reports/2026-10-03-docs-packaging-trim实测报告.md`
+
+- [ ] **Step 1: 重建发布副本并量化**
+
+```bash
+cd better-dsh && npm run build 2>&1 | tail -3
+du -sh docs
+du -sh docs/80_upstream-docs-and-skills/*
+```
+Expected: `docs` ≈ 15 MB；`hermes-dev-skill` 不存在；`dsh-dev-skill` ≈ 7.3 MB（11 − 2.8 − 0.3 src-scripts 之后余 skill + src）
+
+- [ ] **Step 2: 打包并核对承重面**
+
+```bash
+npm pack --pack-destination /tmp/trimpkg
+tar -tzf /tmp/trimpkg/better-dsh-*.tgz | grep -c "hermes-dev-skill\|pi-and-omp\|src-scripts"
+tar -tzf /tmp/trimpkg/better-dsh-*.tgz | grep -c "dsh-dev-skill/skill/SKILL.md"
+tar -tzf /tmp/trimpkg/better-dsh-*.tgz | grep -c "dsh-dev-skill/src/site-pages-map.txt"
+ls -la /tmp/trimpkg/better-dsh-*.tgz | awk '{printf "tarball %.1f MB\n", $5/1048576}'
+```
+Expected: 第一个 grep = **0**；后两个 = **1** 各；tarball ≈ 3.7 MB
+
+- [ ] **Step 3: 零新增悬空引用（已知例外除外）**
+
+```bash
+tar -xzf /tmp/trimpkg/better-dsh-*.tgz -C /tmp/trimx 2>/dev/null || (mkdir -p /tmp/trimx && tar -xzf /tmp/trimpkg/better-dsh-*.tgz -C /tmp/trimx)
+grep -rn "hermes-dev-skill\|pi-and-omp\|src-scripts" /tmp/trimx/package/docs | grep -v "src-README.md"
+```
+Expected: 除 `src-README.md` 那一处外无输出
+
+- [ ] **Step 4: rig 冒烟 + 报告**
+
+`bash .test/seed/test123/start.sh` 后确认：
+- 会话技能目录仍列出 `dsh-dev-skill`，`skill://dsh-dev-skill` 可读
+- `read dsh://docs` 列表正常；抽查 `dsh://docs/50_test-reports/` 一份可读
+
+报告记录：tarball 前后体积、磁盘前后体积、四条 grep 计数、技能可读证据。
+
+```bash
+git add docs/50_test-reports/2026-10-03-docs-packaging-trim实测报告.md
+git commit -m "docs(test): docs packaging trim measurement and rig smoke"
+```
+
+> 发布（`npm publish`）仍需 user 单次明确放行 —— 见根 AGENTS.md 〇节，本计划不包含发包。

package/node_modules/better-dsh/docs/superpowers/specs/2026-10-02-ctx-navigation-design.md

@@ -0,0 +1,209 @@
+# ctx:// Long-Session Navigability — Design
+
+> Status: approved (user, 2026-10-02). Implements backlog N1–N6 plus findings F1/F2 from
+> `docs/50_test-reports/2026-09-28-ctx-scheme长会话utility实测报告.md` §八.
+> Live spec delta: `docs/specs/ctx/spec.md`. Plan: `docs/superpowers/plans/2026-10-02-ctx-navigation.md`.
+
+## 1. Scope ruling (carried from the report, §八)
+
+This tool family is **text-keyword recallable navigation** — the phone book + index + pointer
+for a long session. Semantics is out of scope: no embeddings, no semantic ranking, no
+"fuzzy" retrieval. The model is a language model; synonym/substitution/keyword work is its
+job. We guarantee only: **原文可取 + 可寻址** (原文 retrievable, and addressable).
+
+Every number this scheme shows the model MUST either be directly usable as a selector in the
+same URL family, or be explicitly labeled metadata with its unit. A bare, unlabeled number
+that *looks* like a coordinate but is not addressable is the failure mode this change
+eliminates.
+
+## 2. Coordinate model (the spine)
+
+Two coordinate systems, both labeled wherever shown:
+
+| Unit | Meaning | Used by |
+|---|---|---|
+| `seq` | event sequence number in the session log | `[<n\|seq>]` element/label addressing |
+| `line` | transcript line number (1-based) | `:N-M` windows and `grep … ctx://session/transcript` |
+
+The transcript is the **canonical coordinate space**. `grep` on `ctx://session/transcript`
+materializes the transcript and returns transcript line numbers; therefore every exposed
+`lines=` figure is a transcript line and pastes directly into `:N-M`, and episode windows are
+transcript-relative.
+
+**Decision (user, 2026-10-02): transcript-relative everywhere.** `compactions[label]:5300-5310`
+means transcript lines 5300–5310, identical to `transcript:5300-5310`. The first episode starts
+at transcript line 1, so episode-relative and transcript-relative coincide for it.
+
+## 3. Data model changes (in `better-dsh/src/url-schemes/handlers/ctx.ts`)
+
+### 3.1 Transcript line index (structural, N1)
+
+Build the transcript **once** and carry per-entry line ranges, instead of the current two
+independent renders (`transcript()` and each episode's `originalText`):
+
+```ts
+interface TranscriptIndex {
+  text: string                      // the joined transcript (canonical face)
+  totalLines: number
+  lineOfSeq: Map<number, { start: number; end: number }>   // per rendered entry, transcript lines
+}
+
+function buildTranscript(events, toolNameOf): TranscriptIndex {
+  const entries = events
+    .map(e => ({ seq: e.seq as number, text: renderEntry(e, toolNameOf) }))
+    .filter(t => t.text !== '')
+  const lineOfSeq = new Map()
+  let line = 1
+  for (let i = 0; i < entries.length; i++) {
+    const n = entries[i].text.split('\n').length
+    lineOfSeq.set(entries[i].seq, { start: line, end: line + n - 1 })
+    line += n + (i < entries.length - 1 ? 1 : 0)   // one blank separator line between entries
+  }
+  return { text: entries.map(e => e.text).join('\n\n'), totalLines: line - 1, lineOfSeq }
+}
+```
+
+The episode's canonical span is then **derived** from the index (guarantees the invariant by
+construction):
+
+```ts
+// episode lines = min/max transcript line over the shadowed events that rendered
+const lineStart = min(lineOfSeq.get(seq).start for shadowed seqs that rendered)
+const lineEnd   = max(lineOfSeq.get(seq).end   for shadowed seqs that rendered)
+const originalText = transcript.text.split('\n').slice(lineStart - 1, lineEnd).join('\n')
+```
+
+If no shadowed event rendered (degenerate), the episode has an empty span (`lines: null`).
+
+### 3.2 Episode shape
+
+Each episode gains `lines: { start, end } | null`, `fidelity: { userTurns, toolCalls }`, and a
+computed `landmarks` block. The manifest line, the snapshot `compacted[]` entry, the snapshot
+`segments[]` entry, and the episode prepared face all carry `lines=` and `seq=` labeled figures.
+
+### 3.3 `resultTextOf` shape robustness (F2)
+
+`tool/result` messages in the current session format store **flat** text blocks
+(`data.message.content: [{type:"text", text:"…"}]`); the nested `tool-result` block form is
+the older shape. Today `resultTextOf` only flattens the nested form, so every result renders
+empty. Fix: prefer nested, fall back to flat:
+
+```ts
+function resultTextOf(event: PersistenceEvent): string {
+  const blocks = blocksOf(event)
+  const nested = blocks
+    .flatMap(b => (b as { content?: ContentBlock[] }).content ?? [])
+    .map(c => c.text ?? '').join('\n')
+  if (nested !== '') return nested
+  return textOf(blocks)   // flat text blocks (current session format)
+}
+```
+
+## 4. Backlog implementation
+
+### N1 — addressable line coordinates + explicit bounds (F7/F10)
+
+- Manifest line per episode: `seq=<start>..<end> (N items, T tokens)` **and**
+  `lines=<lineStart>..<lineEnd>` (or `lines=<none>`), plus `fidelity=ut:tc`.
+- Snapshot: `segments[]` → `{ segment, seq_start, seq_end, lines: {start,end}|null, items }`;
+  `compacted[]` gains `lines`, `fidelity`.
+- Episode prepared face header prints `lines=` and `seq=` labeled.
+- Episode line windows are transcript-relative and **clamped with an explicit boundary note**
+  when a requested range reaches past the span (never silent-empty):
+
+  ```ts
+  // transcript coords -> episode-local coords
+  function applyEpisodeLines(slice, lineStart, lineEnd, ranges): string
+  // out-of-span tail appends: [ctx:// note: episode span is transcript lines <s>-<e>]
+  ```
+
+  A window entirely outside the span returns the note alone (not empty). `:raw` still returns
+  the full span.
+
+### N2 — digest residence rule (design position §八.4)
+
+- `latest` = the last episode in the chain; its digest is the compact-checkpoint message
+  already resident in live context.
+- Compute the checkpoint's transcript lines (the `user/message` with `source.plugin === 'compact'`
+  at `checkpointSeq`; fall back to the seq when no line is mapped).
+- Latest episode prepared face = **navigation block** (no digest dump):
+
+  ```text
+  [ctx://session/compactions[<label>] — digest is already in your live context]
+  lines=<ls>..<le>  seq=<ss>..<se>  items=<n>  tokens=<t>
+  fidelity=<ut>:<tc>
+  digest resident at seq=<checkpointSeq> (transcript:<start>-<end> when mapped) — read it there,
+  or use :raw here for the shadowed span
+  <landmarks>
+  ```
+
+- Older episode prepared face = **full digest** (`summaryText`) followed by the same pointer
+  block. `:raw` on any episode always returns the span, so a digest is never lost.
+
+### N3 — landmark roster (direction markers, all as line coordinates)
+
+Computed over the episode's shadowed events; capped to stay one screen:
+
+- `user turns (<n>): <line>, <line>, …` — transcript line of each rendered `user/message`
+  with `source.kind === 'user'` (cap 30, then `… +N more`).
+- `failures (<n>): <line> <tool>, …` — `tool/result` events with
+  `data.message.isError === true` or a present `data.error` (cap 20).
+- `touched paths: <path>×<count>, …` — path-valued strings extracted from `tool/call`
+  `arguments` (keys `path`/`file_path`/`filePath`/`file`, plus `edits[].path` and
+  `files[].path`; args larger than 64 000 chars skipped). Best-effort pointer, not an index.
+  (cap 12, sorted by count desc).
+- `prior checkpoints in span: <n>` — count of `user/message` with `source.plugin === 'compact'`.
+
+### N4 — fidelity line
+
+`fidelity=<userTurns>:<toolCalls>` per episode (tool-heavy ⇒ digest trustworthy and detail
+regenerable; user-intent-heavy ⇒ must drill down). Inline in manifest, snapshot `compacted[]`,
+and the episode pointer block.
+
+### N5 — `:path/` and `?q=` in ctx (F5/F8) + error echo
+
+The selector grammar already parses `path`/`query` and `applySelector()` (selector.ts) already
+implements JSON dot-path + line filter. Wire them into `applyFace`:
+
+```ts
+if (selector.kind === 'path' || selector.kind === 'query') {
+  return applySelector(face === 'canonical' ? canonical : prepared, selector)
+}
+```
+
+So `ctx://session:path/totals.tool_calls` narrow-reads the snapshot JSON, and
+`ctx://session/injections?q=subagent-settled` filters the index. The manifest route also runs
+through `applySelector` (so `?q=` and `:N-M` windowing work on it too). Update
+`CTX_BAD_SELECTOR` to echo the URL and the supported selector set.
+
+### N6 — snapshot `asOf`
+
+Snapshot gains `asOf: { seq: <max seq>, line: <totalLines> }` and a hint that totals are live
+at read time (a cached snapshot is knowingly stale).
+
+### F1 — element-collection index faces + error echo
+
+- `user_prompts` bare → index list (one line per prompt: `seq=<s> <preview>`); canonical
+  `:raw` = all joined.
+- `tool_calls` / `agent_responses` bare → bounded index (first 20 lines + `… +N more — use
+  :raw for all, ?q= to filter, [n|seq] for one`); canonical `:raw` = all joined.
+- `[n|seq]` behavior unchanged.
+- Error text for a bad element stops echoing an empty-bracket URL; it names the collection,
+  its count, and the 0-based/seq addressing (already mostly present — align the message).
+
+## 5. Out of scope
+
+- F3 (`read` offset/limit silently ignored on URIs) — harness read-tool contract, not this handler.
+- Semantic/vector retrieval; embeddings; "fuzzy" search (see §1).
+- F4 (compaction label drift) — already mitigated by the error listing current labels; the
+  `compactionId` (uuid) stable-key idea is recorded but not implemented this wave.
+
+## 6. Verification
+
+Unit: extend `better-dsh/test/url-schemes/ctx.spec.ts` (and add focused specs) with the
+invariants above — notably **episode span ≡ transcript slice** and **episode `:N-M` ≡
+`transcript:N-M`** for non-first episodes. Full `vitest run` + `tsc --noEmit` green.
+
+First-person (4999 rig, dsh 0.2.0-rc.2): a real long-session instance reads the snapshot
+(asOf + lines present), windows a deep episode by transcript line, filters an index with
+`?q=`, narrow-reads with `:path/`, and confirms a large tool result is no longer empty.

package/node_modules/better-dsh/docs/upstream-dsh-0.1.5-rc.2-report.md

@@ -0,0 +1,156 @@
+# upstream dsh npm 版本对账：prod 0.1.3-alpha.2 → 0.1.5-rc.2
+
+> 生成时间：2026-09-10（本地时区）
+> 数据源：npm registry（`@deepseek-ai/dsh`）元数据 + `upstream/deepseek-harness` git tag 对账
+> 目标：回答「npm 上比 prod 更高的版本是什么、diff 有多大、对 prod 意味着什么」
+
+---
+
+## 〇、一句话结论
+
+prod 当前跑 **`@deepseek-ai/dsh@0.1.3-alpha.2`**。npm 上比它高的版本是整条 **0.1.5 线**（`alpha.1 / alpha.2 / rc.1 / rc.2`，**0.1.4 从未发布，直接跳号**）。最高版本是 **`0.1.5-rc.2`**（挂在 `next` dist-tag，而 `latest` 还停在 `0.1.5-rc.1`）。
+
+这条 0.1.5 线是**大版本级聚合**：846 commits、3170 文件、约 10.4 万行新增。核心是 **Session 格式 v3 重写**（会话持久化契约变更，对 prod 是**破坏性升级，不可 drop-in**），外加 Electron 桌面打包、Sidebar/dockkit 重构、文件交付「present」工具、图渲染预览、模型默认值切换（DeepSeek V41 Flash）等一批功能。**升级 prod 前必须按 AGENTS.md §一/§二 走对齐轮，不能只换版本号。**
+
+---
+
+## 一、版本全景
+
+npm registry 当前 dist-tags：
+
+| dist-tag | 指向版本 |
+|---|---|
+| `latest` | 0.1.5-rc.1 |
+| `next` | **0.1.5-rc.2**（最高） |
+| `alpha` | 0.1.5-alpha.2 |
+
+比 prod（0.1.3-alpha.2）更高的版本，按发布顺序：
+
+| 版本 | npm 发布时间 (UTC) | dist-tag |
+|---|---|---|
+| 0.1.5-alpha.1 | 2026-09-08 15:57 | — |
+| 0.1.5-alpha.2 | 2026-09-09 14:41 | `alpha` |
+| 0.1.5-rc.1 | 2026-09-10 03:12 | `latest` |
+| **0.1.5-rc.2** | **2026-09-10 14:57** | `next` |
+
+> 注意点：`latest` 并不指向最高版本（rc.1 vs rc.2）；「最高版本」= `next` 上的 **0.1.5-rc.2**。0.1.4 未在 npm 出现过。
+
+对应 git tag（本地 `upstream/deepseek-harness`，已 fetch）：
+
+```
+dsh-v0.1.3-alpha.2  2026-09-07 19:45 +0800   ← prod 当前
+dsh-v0.1.5-alpha.1  2026-09-08 23:25 +0800
+dsh-v0.1.5-alpha.2  2026-09-09 22:13 +0800
+dsh-v0.1.5-rc.1     2026-09-10 09:36 +0800
+dsh-v0.1.5-rc.2     2026-09-10 21:50 +0800
+```
+
+---
+
+## 二、diff 规模
+
+`dsh-v0.1.3-alpha.2 .. dsh-v0.1.5-rc.2`：
+
+| 指标 | 值 |
+|---|---|
+| commits | **846** |
+| 文件 | 3170 changed |
+| 行 | +103,990 / −17,687 |
+| 源码侧（排除 snapshots/tests） | 2474 文件，+68,818 / −13,973 |
+
+分段 commit 分布：
+
+| 区间 | commits |
+|---|---|
+| 0.1.3-alpha.2 → 0.1.5-alpha.1 | 563（大头，聚合了 Session V3 与一堆 feature） |
+| 0.1.5-alpha.1 → 0.1.5-alpha.2 | 262 |
+| 0.1.5-alpha.2 → 0.1.5-rc.1 | 17 |
+| 0.1.5-rc.1 → 0.1.5-rc.2 | 4（收尾/backport） |
+
+---
+
+## 三、依赖面变化（对 prod 直接可见）
+
+prod 0.1.3-alpha.2 有 **71 个 dependencies**，0.1.5-rc.2 有 **72 个**。差异：
+
+1. **新增运行期包 `@deepseek-ai/dsh-tool-present`**（`packages/fs/tool-present`）——新「present」工具：把 agent 产出的文件以不可变交付卡片（download card）呈现，是文件交付特性的宿主半。
+2. `apps/cli` devDeps 新增 `@deepseek-ai/dsh-agent-loop`、`@deepseek-ai/dsh-agent-loop-testkit`（内部，不影响 prod 运行面）。
+3. 新增 client 包 `ui-deliverables`（`PresentRow` / `PresentedFileCard` / `present-open`），属 web shell 交付卡片 UI。
+4. 其余全部 `@deepseek-ai/*` 依赖整体从 `^0.1.3-alpha.2` 抬到 `^0.1.5-rc.2`（同版本号齐步，无个别漂移）。
+5. 底层 `cordis` / `schemastery` / `commander` / `js-yaml` 等版本**未变**（`cordis ^4.0.2`、`schemastery ^3.18.2` 等，与 0.1.3-alpha.2 相同）。
+
+---
+
+## 四、主要变更主题（按 prod 相关度排序）
+
+### 1. Session 格式 v3 重写（⚠ 破坏性，最高风险）
+`session-log-v3` 工作线，是本次最大的变更块。要点：
+
+- 会话身份 **V2 → V3 迁移**（`feat(session): add identity V2-to-V3 migration and writer skeleton`）。
+- system prompt 表示为 **surface node zero**（`refactor(session): represent the system prompt as surface node zero`）。
+- **canonical envelopes**、PTC durable vocabulary、in-history system prompt 表示、JSONL 跨进程写所有权（lease）。
+- 大量 `session.v3.jsonl` 快照与 V2/V3 迁移覆盖面单测。
+
+> **对 prod 的含义**：会话持久化契约改变。上一轮（0.1.3-alpha.2 对齐）已实测：上游 tag diff 会打到 `session-persistence-omp.ts` / `replay.ts` / store 的 handle+lease 契约（见 2026-09-08 对齐报告）。**0.1.5 的 V3 比 0.1.3 的 V2 更进一步，破坏面更大**，`better-dsh` / `omp-web` 这类桥接会话数据的插件必须重新对齐，不能 drop-in。
+
+### 2. Electron 桌面打包（对 3080 web 无直接作用）
+Windows/macOS/Linux 构建、mac 签名+公证、Windows 签名、auto-update、IPC 性能优化。纯桌面宿主线，与本机 `dsh web`（3080）部署无关，但意味着上游发布面从此多一个桌面产物。
+
+### 3. Sidebar / dockkit 重构
+- `dockkit` 可逆停靠引擎、pointer 交互。
+- 全局 sidebar panel、tab 导航、live tab 标题 + 文件类型图标、末 tab 关闭规则、响应式右栏、全屏 shell。
+- session-log 控制移入 header「更多」菜单。
+
+### 4. 文件交付「present」工具 + 文档预览
+- 新 `dsh-tool-present` 包：不可变文件交付下载卡片、artifact 卡原生文件动作、workspace 文件操作。
+- 可扩展文档预览、文本预览分页 tab、文件类型图标集、`ui-deliverables` client 卡。
+- `feat(fs)`：bounded byte-range reads（fs-local / fs-e2b）、dual-face 文件 API。
+
+### 5. 图表 / Markdown 预览
+Chat 代码块内预览 Mermaid / Graphviz / SVG / HTML fence，适配应用主题。
+
+### 6. LLM 模型默认值切换（⚠ 影响 prod 行为）
+- Chat Completions 默认切到 **DeepSeek V41 Flash**（`feat(llm): default Chat Completions to DeepSeek V41 Flash`）。
+- 保留 V4 模型、恢复 V4 Flash Vision Exp catalog 条目。
+> prod 若升级，默认模型会跟着变；需确认是否期望。
+
+### 7. Feedback 对话框
+`/feedback` 与 Dislike 统一为一个带分类的对话框 + toast。
+
+### 8. Subagent catalog
+记录并观察 parent-owned child catalog（子代理目录）。
+
+### 9. native system / node-addon-system
+包族改名 `node-addon-system`，预编译 Node-API flock、Landlock capability 子路径。**新增原生依赖面，升级安装需留意 prod 机上的原生构建/预编译匹配**（本机已有一处 zeromq allowBuilds 特例，见 AGENTS.md §二）。
+
+### 10. minimal profile 行为调整
+- `str_replace_editor` 从 minimal profiles 移除。
+- persistent bash 输出与 one-shot shell 契约对齐。
+> 只影响 minimal profile，不影响 prod `web` profile 的默认工具集。
+
+### 11. 其它
+- CLI：从 shipped 模板创建 profile。
+- skills：Playwright 视频录制 GIF。
+- 内部 CI/审查自动化（weighted PR approval、review owner 排名等）——与 prod 运行无关。
+
+---
+
+## 五、对 prod 升级的风险评估（简要）
+
+| 风险项 | 级别 | 说明 |
+|---|---|---|
+| Session V3 格式迁移 | 🔴 高 | 会话持久化契约变更；`better-dsh`/`omp-web` 会话桥接面需重新对齐，先例（0.1.3 V2）已证实非 drop-in |
+| 模型默认切 V41 Flash | 🟠 中 | 默认行为变化，需 user 确认是否接受 |
+| 新原生依赖（node-addon-system） | 🟡 中低 | 安装面原生构建/预编译匹配；本机 pnpm strictDepBuilds/allowBuilds 需复核 |
+| 新工具 `dsh-tool-present` | 🟡 中低 | 新工具进入 agent 运行时，需确认与现有工具/插件无 id 冲突 |
+| Sidebar/dockkit UI 重构 | 🟢 低（功能面） | 纯增量 UI，但 better-dsh 的 mobile 手势/侧栏 patch 需复测是否仍对齐 |
+| Electron 桌面 | ⚪ 无关 | 不影响 web 部署 |
+
+---
+
+## 六、建议
+
+1. 本次**只做对账、不做升级**：0.1.5 是聚合大版本，且含 Session V3 破坏性契约变更，不能当「换版本号」处理。
+2. 若后续要升级，按 AGENTS.md §一/§二走 **Dev/Test 1（4999 源码级）对齐轮**：切 `dsh-v0.1.5-rc.2` → 重放三处本地 patch（storeDir / unrun devDep / resolveRepositoryRoot）→ install/build → 插件契约对齐（重点 `session-persistence-omp.ts`/`replay.ts`/store 的 V3 handle+lease）→ tsc/单测 → 4999 第一人称实测 → 报告落 `docs/50_test-reports/` → user 确认 → 才动 prod 3080。
+3. 升级目标版本**首选 `0.1.5-rc.2`（`next`）而非 `latest`（rc.1）**，因为 rc.2 才是最高版本；但 rc 阶段仍建议等上游正式 stable 后再定。
+4. 升级前单独确认模型默认值（V41 Flash）是否要在 prod 生效。

package/node_modules/better-dsh/dsh-docs/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
+## Writing rules
+
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
+- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
+
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
+- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Cross-reference with machine-checkable links, never free prose
+
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).