better-dsh 0.2.5 → 0.3.0-c

package/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/dsh-docs/baseline.md

@@ -0,0 +1,13 @@
+# DSH runtime compatibility
+
+Better Dash and Super Dash use the same DSH host APIs. The verified upstream source baseline for this alignment is `dsh-v0.2.1-alpha.1` (`5badb15009ae1756c3afe0ae0cef1faafc290ccc`). The pages in this directory include older official reference snapshots; check this baseline before using an API described by a snapshot.
+
+On `0.2.1-alpha.1`:
+
+- The runtime `dsh-invariants` plugin, `ctx.invariants`, and companion `./invariant` exports are removed. The archived invariant reference does not define an available extension API.
+- Plugin subpaths provide display text through `<specifier>/locale/en.json` and localized sibling exports, and icons through `<specifier>/icon`. Subpaths do not read a separate `package.json`.
+- Composer statistics use separate `activity` and `usage` entries.
+- The native Plugin Manager refreshes profile package resolution when bundles are installed, enabled, disabled or removed. Replacing installed package code still requires a restart.
+- Automation is part of the Web composition. Reminder tools depend on agent mode; they are absent in Minimal mode and subagents.
+
+See the [official release notes](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.1) and the actual host package exports for the complete interface contract.

package/dsh-docs/subsystems/invariants.md

@@ -1,5 +1,8 @@
 # Runtime Invariants
 
+> DSH `0.2.1-alpha.1` removes this plugin and all companion `./invariant` exports. This page is an older reference snapshot; use the [runtime compatibility baseline](../baseline.md) for the current host contract.
+
+
 English | [中文](invariants.zh.md)
 
 [dsh-invariants](../../packages/runtime-diagnostics/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the registry design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).

package/dsh-docs/subsystems/invariants.zh.md

@@ -1,5 +1,8 @@
 # 运行时不变式
 
+> DSH `0.2.1-alpha.1` 已移除此插件及所有配套 `./invariant` 导出。本页保留旧版参考快照；当前宿主契约见[运行时兼容基线](../baseline.md)。
+
+
 [English](invariants.md) | 中文
 
 [dsh-invariants](../../packages/runtime-diagnostics/invariants) 是面向包自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；注册表设计由[不变式服务 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md)规定。

package/lib/BrowserWebSocketTransport-D1aFReu_.js

@@ -0,0 +1,4 @@
+import "./util-BHL_dfV_.js";
+import { t as BrowserWebSocketTransport } from "./BrowserWebSocketTransport-wm99h94r.js";
+
+export { BrowserWebSocketTransport };

package/lib/BrowserWebSocketTransport-wm99h94r.js

@@ -0,0 +1,39 @@
+import { o as debugCatchError } from "./util-BHL_dfV_.js";
+
+//#region node_modules/puppeteer-core/lib/puppeteer/common/BrowserWebSocketTransport.js
+/**
+* @internal
+*/
+var BrowserWebSocketTransport = class BrowserWebSocketTransport {
+	static create(url) {
+		return new Promise((resolve, reject) => {
+			const ws = new WebSocket(url);
+			ws.addEventListener("open", () => {
+				return resolve(new BrowserWebSocketTransport(ws));
+			});
+			ws.addEventListener("error", reject);
+		});
+	}
+	#ws;
+	onmessage;
+	onclose;
+	constructor(ws) {
+		this.#ws = ws;
+		this.#ws.addEventListener("message", (event) => {
+			if (this.onmessage) this.onmessage.call(null, event.data);
+		});
+		this.#ws.addEventListener("close", () => {
+			if (this.onclose) this.onclose.call(null);
+		});
+		this.#ws.addEventListener("error", debugCatchError);
+	}
+	send(message) {
+		this.#ws.send(message);
+	}
+	close() {
+		this.#ws.close();
+	}
+};
+
+//#endregion
+export { BrowserWebSocketTransport as t };

package/lib/LaunchOptions-B874eBu2.js

@@ -0,0 +1,4 @@
+import "./main-CupOhMp5.js";
+import { t as convertPuppeteerChannelToBrowsersChannel } from "./LaunchOptions-kGXcZOe0.js";
+
+export { convertPuppeteerChannelToBrowsersChannel };

package/lib/LaunchOptions-kGXcZOe0.js

@@ -0,0 +1,17 @@
+import { b as ChromeReleaseChannel } from "./main-CupOhMp5.js";
+
+//#region node_modules/puppeteer-core/lib/puppeteer/node/LaunchOptions.js
+/**
+* @internal
+*/
+function convertPuppeteerChannelToBrowsersChannel(channel) {
+	switch (channel) {
+		case "chrome": return ChromeReleaseChannel.STABLE;
+		case "chrome-dev": return ChromeReleaseChannel.DEV;
+		case "chrome-beta": return ChromeReleaseChannel.BETA;
+		case "chrome-canary": return ChromeReleaseChannel.CANARY;
+	}
+}
+
+//#endregion
+export { convertPuppeteerChannelToBrowsersChannel as t };

package/lib/NodeWebSocketTransport-BRLjmu2R.js

@@ -0,0 +1,4 @@
+import "./util-BHL_dfV_.js";
+import { t as NodeWebSocketTransport } from "./NodeWebSocketTransport-D9ysYGLM.js";
+
+export { NodeWebSocketTransport };