super-dsh 0.3.0-c → 0.3.0-e

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

@@ -1,181 +0,0 @@
-# 发布包瘦身：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

@@ -1,209 +0,0 @@
-# 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

@@ -1,156 +0,0 @@
-# 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

@@ -1,75 +0,0 @@
-# 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)).