dsh-plugin-upgrade 0.1.0

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "dsh-plugin-upgrade",
+  "version": "0.1.0",
+  "description": "Plugin-author upgrade skill for DeepSeek Harness: a version-locked 0.1.3-alpha.1 -> 0.1.5-alpha.1 version card plus a zero-dependency seam scanner (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false green), packaged as a bundle skill and an npx CLI.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-plugin-upgrade.git"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-plugin-upgrade#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-plugin-upgrade/issues"
+  },
+  "author": "PerryLink",
+  "private": false,
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.mjs"
+    },
+    "./scan": {
+      "types": "./types.d.ts",
+      "default": "./lib/scan.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-plugin-upgrade-scan": "./scripts/scan-0.1.5.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "types.d.ts",
+    "lib",
+    "scripts",
+    "skills",
+    "cordis.patch.yml",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "AGENTS.md",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "cordis",
+    "plugin-upgrade",
+    "migration",
+    "skill",
+    "version-card",
+    "scanner"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-skill": "0.1.5-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "scan": "node scripts/scan-0.1.5.mjs",
+    "check:readmes": "node scripts/check-readme-sync.mjs",
+    "verify:self-contained": "node scripts/verify-self-contained.mjs",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "verify": "npm test && node scripts/check-readme-sync.mjs && node scripts/verify-self-contained.mjs && node scripts/verify-artifacts.mjs"
+  },
+  "license": "Apache-2.0",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/PerryLink"
+  }
+}

package/scripts/changelog-section.mjs

@@ -0,0 +1,21 @@
+// Print the CHANGELOG.md section for one version, for GitHub Release notes.
+// Usage: node scripts/changelog-section.mjs <x.y.z>
+import { readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const version = process.argv[2]
+if (!version) {
+  console.error('usage: node scripts/changelog-section.mjs <x.y.z>')
+  process.exit(2)
+}
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const lines = readFileSync(join(root, 'CHANGELOG.md'), 'utf8').split(/\r?\n/)
+const start = lines.findIndex(l => l.startsWith(`## [${version}]`))
+if (start < 0) {
+  console.error(`CHANGELOG.md has no "## [${version}]" section`)
+  process.exit(1)
+}
+const rest = lines.slice(start + 1)
+const end = rest.findIndex(l => l.startsWith('## ['))
+process.stdout.write(`${rest.slice(0, end < 0 ? rest.length : end).join('\n').trim()}\n`)

package/scripts/check-readme-sync.mjs

@@ -0,0 +1,33 @@
+// Five-language README sync gate: every README must carry the same number of
+// `## ` sections as the English source and state the install command.
+// Usage: node scripts/check-readme-sync.mjs
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const FILES = ['README.md', 'README.zh.md', 'README.es.md', 'README.pt.md', 'README.hi.md']
+const INSTALL_COMMAND = 'dsh plugin --profile web add dsh-plugin-upgrade'
+const failures = []
+const read = (file) => {
+  const p = join(root, file)
+  if (!existsSync(p)) { failures.push(`${file} is missing`); return '' }
+  return readFileSync(p, 'utf8')
+}
+const sectionCount = text => (text.match(/^## /gmu) ?? []).length
+
+const contents = FILES.map(read)
+const expected = sectionCount(contents[0])
+for (let i = 1; i < FILES.length; i++) {
+  if (contents[i] === '') continue
+  const count = sectionCount(contents[i])
+  if (count !== expected) failures.push(`${FILES[i]}: ${count} '## ' sections, expected ${expected}`)
+  if (!contents[i].includes(INSTALL_COMMAND)) failures.push(`${FILES[i]}: missing the install command`)
+}
+if (!contents[0].includes(INSTALL_COMMAND)) failures.push('README.md: missing the install command')
+if (failures.length) {
+  console.error('readme-sync: FAIL')
+  for (const f of failures) console.error('  ' + f)
+  process.exit(1)
+}
+console.log(`readme-sync: all ${FILES.length} READMEs share ${expected} sections and the install command`)

package/scripts/scan-0.1.5.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper for the packaged seam scanner.
+ *
+ * Usage:
+ *   node scripts/scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams M1,S3] [--quiet]
+ *   npx --package dsh-plugin-upgrade dsh-plugin-upgrade-scan --repo <path>
+ *
+ * Exit codes: 0 = no error-severity hit, 1 = at least one error-severity hit,
+ *             2 = usage or scan failure. The implementation lives in ../lib/scan.mjs
+ * so the plugin, the CLI and the tests share one seam catalog.
+ */
+import { main } from '../lib/scan.mjs'
+
+process.exit(main(process.argv.slice(2)))

package/scripts/sweep-all.mjs

@@ -0,0 +1,36 @@
+// Sweep every plugin repo under a workspace root and write the evidence table.
+// Usage: node sweep-all.mjs [<workspaceRoot>] [<out.md>]
+import fs from 'node:fs'
+import path from 'node:path'
+import { scanRepo } from '../lib/scan.mjs'
+
+const ROOT = path.resolve(process.argv[2] || '.')
+const OUT = path.resolve(process.argv[3] || path.join(ROOT, 'scan-0.1.5-sweep.md'))
+const SKIP = new Set(['adp-list', 'audit-dsh-infinite-gen-2', 'pan17-dsh-wechat', 'dsh-autotier', 'dsh-personal-directive'])
+const dirs = fs.readdirSync(ROOT, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name)
+  .filter(n => !n.startsWith('_') && !n.startsWith('.') && !SKIP.has(n))
+  .filter(n => fs.existsSync(path.join(ROOT, n, 'package.json'))).sort()
+
+const rows = []
+for (const n of dirs) {
+  const r = scanRepo(path.join(ROOT, n))
+  const errors = r.hits.filter(h => h.severity === 'error')
+  const warns = r.hits.filter(h => h.severity === 'warn')
+  rows.push({ repo: n, files: r.files, errors: errors.length, warns: warns.length, errorSeams: [...new Set(errors.map(h => h.seam))].join(',') || '-' })
+}
+const L = []
+L.push('# scan-0.1.5 · workspace sweep evidence')
+L.push('')
+L.push(`Generated ${new Date().toISOString()} · scanner \`scripts/scan-0.1.5.mjs\` · workspace \`${ROOT}\``)
+L.push('')
+L.push('All repos below were adapted to `0.1.5-alpha.1` by the 2026-09-09 wave. Error-severity hits are expected to be **zero**; warn-severity hits are heuristic leads for manual review (S1/S2/S10).')
+L.push('')
+L.push('| repo | files | errors | warns | error seams |')
+L.push('|---|---|---|---|---|')
+for (const r of rows) L.push(`| ${r.repo} | ${r.files} | ${r.errors} | ${r.warns} | ${r.errorSeams} |`)
+L.push('')
+const withErr = rows.filter(r => r.errors > 0)
+L.push(`**Totals**: ${rows.length} repos · ${rows.reduce((a, r) => a + r.files, 0)} files · ${rows.reduce((a, r) => a + r.errors, 0)} error hits · ${rows.reduce((a, r) => a + r.warns, 0)} warn hits · repos with errors: ${withErr.length ? withErr.map(r => r.repo).join(', ') : 'none'}`)
+fs.mkdirSync(path.dirname(OUT), { recursive: true })
+fs.writeFileSync(OUT, L.join('\n'), 'utf8')
+console.log(L.join('\n'))

package/scripts/verify-artifacts.mjs

@@ -0,0 +1,86 @@
+// verify-artifacts: pack the package into a temp directory and prove the published
+// tarball carries the plugin entry, the skill bundle, the CLI and the patch layer,
+// and that the entry imports under plain Node.
+// Usage: node scripts/verify-artifacts.mjs
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readdirSync, rmSync, existsSync, readFileSync, symlinkSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const staging = mkdtempSync(join(tmpdir(), 'dsh-plugin-upgrade-pack-'))
+const failures = []
+try {
+  execFileSync('npm', ['pack', '--pack-destination', staging], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: true })
+  const tgz = readdirSync(staging).find(f => f.endsWith('.tgz'))
+  if (!tgz) throw new Error('npm pack produced no tarball')
+  const extract = join(staging, 'x')
+  execFileSync('tar', ['-xzf', join(staging, tgz), '-C', staging], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+  const pkgRoot = join(staging, 'package')
+  if (!existsSync(pkgRoot)) { rmSync(extract, { recursive: true, force: true }); failures.push('tarball has no package/ root') }
+
+  const required = [
+    'index.mjs',
+    'cordis.patch.yml',
+    'lib/scan.mjs',
+    'scripts/scan-0.1.5.mjs',
+    'skills/plugin-upgrade-015/SKILL.md',
+    'skills/plugin-upgrade-015/scripts/scan-0.1.5.mjs',
+    'skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+  ]
+  for (const rel of required) if (!existsSync(join(pkgRoot, rel))) failures.push(`tarball is missing ${rel}`)
+
+  // The packaged entry must import without the harness present. It imports the
+  // declared peer @deepseek-ai/schemastery, so lend the extracted tree this
+  // repo's installed peers through a directory link instead of reinstalling.
+  try {
+    const nm = join(pkgRoot, 'node_modules')
+    if (!existsSync(nm) && existsSync(join(root, 'node_modules'))) {
+      symlinkSync(join(root, 'node_modules'), nm, process.platform === 'win32' ? 'junction' : 'dir')
+    }
+    const entryUrl = pathToFileURL(join(pkgRoot, 'index.mjs')).href
+    const out = execFileSync(process.execPath, ['-e', `import(${JSON.stringify(entryUrl)}).then(m => console.log('exports:' + ['name','inject','Config','apply'].filter(k => k in m).join(',')))`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    if (!/exports:name,inject,Config,apply/.test(out)) failures.push(`entry export surface unexpected: ${out.trim()}`)
+  } catch (error) {
+    failures.push(`packaged entry failed to import: ${error instanceof Error ? String(error.stderr || error.message).slice(0, 200) : String(error)}`)
+  }
+
+  // The packaged SKILL.md must keep its corridor frontmatter.
+  const skill = readFileSync(join(pkgRoot, 'skills/plugin-upgrade-015/SKILL.md'), 'utf8')
+  if (!/^name:\s*plugin-upgrade-015\s*$/m.test(skill)) failures.push('packaged SKILL.md lost its frontmatter name')
+
+  // cordis.patch.yml must stay a top-level YAML ARRAY of loader patch entries:
+  // a mapping (`insert:` at column 0) mounts nothing and dsh reports
+  // "must be a top-level YAML array of loader patch entries" at profile load.
+  const patch = readFileSync(join(pkgRoot, 'cordis.patch.yml'), 'utf8')
+  const body = patch.split(/\r?\n/).filter(l => l.trim() !== '' && !l.trim().startsWith('#'))
+  if (!body[0]?.startsWith('- ')) failures.push(`cordis.patch.yml is not a top-level YAML array (starts with ${JSON.stringify(body[0]?.slice(0, 30))})`)
+  if (!body.some(l => /^-\s+insert:/.test(l))) failures.push('cordis.patch.yml has no top-level `- insert:` entry')
+  if (!body.some(l => /name:\s*dsh-plugin-upgrade\s*$/.test(l))) failures.push('cordis.patch.yml does not insert the dsh-plugin-upgrade row')
+
+  // The skill-relative scanner entry must work from inside the tarball, because
+  // the skill body resolves `./scripts/...` against the skill directory.
+  const probe = join(staging, 'bad-probe')
+  mkdirSync(probe, { recursive: true })
+  writeFileSync(join(probe, 'index.ts'), "ctx.on('tool/code-dispatch', () => {})\n")
+  try {
+    execFileSync(process.execPath, [join(pkgRoot, 'skills/plugin-upgrade-015/scripts/scan-0.1.5.mjs'), '--repo', probe, '--quiet'], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    failures.push('packaged skill-relative scanner exited 0 on a real seam')
+  } catch (error) {
+    if (error.status !== 1) failures.push(`packaged skill-relative scanner exited ${error.status}, expected 1`)
+  }
+
+  if (failures.length) {
+    console.error('artifacts: FAIL')
+    for (const f of failures) console.error('  ' + f)
+    process.exitCode = 1
+  } else {
+    console.log(`artifacts: OK (${required.length} required files present, entry imports, skill frontmatter intact)`)
+  }
+} finally {
+  rmSync(staging, { recursive: true, force: true })
+}

package/scripts/verify-self-contained.mjs

@@ -0,0 +1,59 @@
+// verify-self-contained: every bare import in this package must resolve from the
+// declared dependency set, and no import may point outside the package root.
+// Usage: node scripts/verify-self-contained.mjs
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { dirname, join, resolve, relative, isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const declared = new Set([
+  ...Object.keys(pkg.dependencies ?? {}),
+  ...Object.keys(pkg.devDependencies ?? {}),
+  ...Object.keys(pkg.peerDependencies ?? {}),
+  ...Object.keys(pkg.optionalDependencies ?? {}),
+])
+const BUILTIN = /^(node:|[a-z]+$)/
+const SKIP = new Set(['node_modules', '.git', 'fixtures'])
+
+function* walk(dir) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) { if (!SKIP.has(e.name)) yield* walk(join(dir, e.name)) }
+    else if (/\.(mjs|cjs|js)$/.test(e.name)) yield join(dir, e.name)
+  }
+}
+
+const problems = []
+for (const file of walk(root)) {
+  // Strip comments and template literals first: this script itself contains
+  // `import('${...}')` inside a template literal, which is not an import edge.
+  const text = readFileSync(file, 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^[ \t]*\/\/.*$/gm, '')
+    .replace(/`(?:[^`\\]|\\.)*`/g, '``')
+  for (const m of text.matchAll(/(?:from|import\()\s*['"]([^'"]+)['"]/g)) {
+    const spec = m[1]
+    if (spec.startsWith('.')) {
+      const target = resolve(dirname(file), spec)
+      const rel = relative(root, target)
+      if (rel.startsWith('..') || isAbsolute(rel)) problems.push(`${relative(root, file)}: relative import escapes the package: ${spec}`)
+      else if (!existsSync(target) && !existsSync(`${target}.mjs`) && !existsSync(join(target, 'index.mjs'))) problems.push(`${relative(root, file)}: relative import does not exist: ${spec}`)
+      continue
+    }
+    if (BUILTIN.test(spec)) continue
+    const base = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0]
+    if (!declared.has(base)) problems.push(`${relative(root, file)}: bare import not declared in package.json: ${spec}`)
+  }
+}
+
+// The packaged skill and its references must exist for the plugin to mount.
+for (const required of ['skills/plugin-upgrade-015/SKILL.md', 'skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md', 'cordis.patch.yml']) {
+  if (!existsSync(join(root, required))) problems.push(`missing packaged asset: ${required}`)
+}
+
+if (problems.length) {
+  console.error('self-contained: FAIL')
+  for (const p of problems) console.error('  ' + p)
+  process.exit(1)
+}
+console.log('self-contained: all imports resolve within the package and from declared dependencies')

package/skills/plugin-upgrade-015/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: plugin-upgrade-015
+description: Migrate a DeepSeek Harness plugin repo from the 0.1.3-alpha.1 line to 0.1.5-alpha.1. Runs a zero-dependency seam scanner (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false-green), then walks the fix-and-verify loop with real-host smoke.
+whenToUse: Use when a DSH plugin must support @deepseek-ai/dsh 0.1.5-alpha.1 (or any host line in >=0.1.3-alpha.1 <0.1.5-alpha.2) while keeping the 0.1.2-rc.1 peer band working. Not for 0.1.1→0.1.2 migrations (use the community convergence skill) and not for the DSH user-facing upgrade/repair path.
+metadata:
+  corridor: "0.1.3-alpha.1 -> 0.1.5-alpha.1"
+  host-baseline: "0.1.5-alpha.1 (checkout 19d2e38480, tag dsh-v0.1.5-alpha.1 5dda764ed3)"
+  evidence: "40 plugin repos, 2026-09-09 wave"
+  status: "published"
+user-invocable: true
+---
+
+# Plugin upgrade · 0.1.3-alpha.1 → 0.1.5-alpha.1
+
+You are migrating **one plugin repository** to the DSH `0.1.5-alpha.1` line. The goal is not "make typecheck pass" — it is "prove the plugin still works on the target host". Local gates are necessary but not sufficient: two failure classes survive a green gate (stale-type false green, and tests mocked against the old shape).
+
+## Hard rules
+
+1. **Run the scanner first.** `node ./scripts/scan-0.1.5.mjs --repo <repo>` — it prints `file:line` facts. Do not trust a green `typecheck` before M1 is cleared.
+2. **M1 is a blocker, not a warning.** If `tsconfig` `paths` do not resolve, TypeScript silently falls back to published types and every other signal is fake. Fix the paths, then re-run; new red is real signal.
+3. **Only adapt what the card says changed.** Do not refactor beyond the card; keep the old peer band working (the repo must still boot on `0.1.2-rc.1`).
+4. **Behavior change ⇒ test change ⇒ docs change, in one commit.** Five-language READMEs and CHANGELOG move with the code.
+5. **Real-host smoke is the exit criterion.** Temp `DSH_HOME` (mkdtemp) + target CLI + `dsh plugin --profile web add <tarball>` + `--dump-config`. Never touch the user's real `~/.dsh`.
+
+## Loop
+
+1. **Identify** — record: repo, current version, peer band, target host tag, node/pnpm, and whether the repo has client half / tracked `lib/`.
+2. **Baseline** — run the repo's own gate chain and *record pre-existing failures*; never let them be counted as migration regressions.
+3. **Scan** — run `./scripts/scan-0.1.5.mjs`; load only the version card facts that hit.
+4. **Plan** — group by host/client/config/distribution; list files, why they change, tests, rollback point. Get confirmation before editing.
+5. **Adapt + verify per module** — fix, run the module's tests, keep commits conventional and independently revertable.
+6. **Prove** — full gate chain + real-host smoke (+ resume round-trip for log writers, + browser assertion for client halves). Report done / not-hit / pre-existing / unverified / rollback.
+
+## Reference
+
+- `./references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md` — the version card: 10 seams with host path + commit + minimal fix + regression, and the 4 that no community PR covers yet (S3/S8/S9/M1).
+- `./scripts/scan-0.1.5.mjs` — the detector (zero dependency, `file:line`, exit 1 on error-severity hits).
+- The package's own test suite (`node --test`) — synthetic bad/good fixtures plus a live negative on a repo already adapted by this wave.

package/skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md

@@ -0,0 +1,90 @@
+# Version card · `0.1.3-alpha.1` → `0.1.5-alpha.1`
+
+> 适用：任何 `@deepseek-ai/dsh-*` peer 落在 `>=0.1.2-rc.1 <0.2.0`、且需要同时支持 `0.1.5-alpha.1` 的插件仓。
+> 状态：**本地留档（未发布）**。证据来自 2026-09-09 批次 40 个真实插件仓的实测升级波（宿主 checkout `0.1.5-alpha.1`，HEAD `19d2e38480`；官方 tag `dsh-v0.1.5-alpha.1` = `5dda764ed3`）。
+> 证据目录：`_scratch/batch-2026-09-09/`（`COMPLETION-REPORT.md` §2、`cards/*.md`、`probe/*.json`、`doctor/`、`charset/`、`phase-e/`）。
+
+## 0. 这一跳与其它跳的关系
+
+| 走廊 | 社区状态（2026-09-09 实测） |
+|---|---|
+| `0.1.0-rc.8 → 0.1.3-alpha.2` | 合流仓 `oh-my-dsh/dsh-plugin-upgrade-skill` 已合入 |
+| `0.1.3-alpha.2 → 0.1.5-alpha.1` | **两条 open PR 已认领**（#195 18 卡 / #197 6 卡），均未合入 |
+| 本卡覆盖 | `0.1.3-alpha.1 → 0.1.5-alpha.1`，**只补已被实测、但上述 PR 未覆盖的 4 类**（S3 / S8 / S9 / M1），其余 seam 作为交叉核对 |
+
+**本卡的四类独家内容**：S3（`assistant/message.stream`）、S8（`SessionHandleReadResult`）、S9（`SystemPrompt.persona` → `personaPrefix`）、**M1（tsconfig 陈旧路径导致 typecheck 静默假绿）**。
+
+## 1. M1 · tsconfig 陈旧路径 → 本地门禁假绿（**最高优先级，独家**）
+
+| 项 | 内容 |
+|---|---|
+| 旧假设 | `tsconfig.json` 的 `paths` 把 `@deepseek-ai/*` 指到本地 harness checkout，`pnpm run typecheck` 即"对最新版编译" |
+| 触发 | 工作区搬迁（2026-09-07）后 `../../../packages|vendor` 不再指向 checkout（实测解析到 `D:\Projects\packages`，不存在） |
+| 真实行为 | TypeScript 对**解析失败的 path 映射静默回退**到 `node_modules` 的已发布类型 → 门禁全绿，但编译的不是目标版本 |
+| 实测规模 | 40 仓中 **11 仓**命中；修复路径后**3 仓立刻暴露真实 TS 错误**（原本"全绿"） |
+| 正确写法 | 相对仓库根：`../../../../deepseek-harness/packages/<pkg>/lib/types/index.d.ts`（及 `vendor/...`） |
+| 检测 | `node scripts/scan-0.1.5.mjs --seams M1`：逐条解析 `paths`，目标不存在即报 error |
+| 回归 | 修复后 `pnpm run typecheck` 必须仍绿；**若变红，那才是真实适配缺口**（先修代码，不要回退路径） |
+| 剩余风险 | 路径依赖本地 checkout 布局；CI 侧应改用 `typecheck:ci`（清空 paths）做已发布线回归，两把尺子都要绿 |
+
+## 2. S3 · `assistant/message` 必填 `stream`（**独家**）
+
+| 项 | 内容 |
+|---|---|
+| 目标契约 | `packages/core/session/src/index.ts` 的 `assertAssistantSettlementShape` 要求 `Array.isArray(data.stream)` |
+| 谁受影响 | **写入会话日志的一方**（导入器/转换器/eval 产物生成器），不是只读消费者 |
+| 失败形态 | 日志写入成功、`Session.fromRestore` 抛 `seed assistant/message at index N has invalid settlement fields` → **会话不可续聊**（比 typecheck 红更隐蔽） |
+| 实测案例 | `dsh-claude-move`：handle 基线导入成功但 resume 失败；修复 = `normalizeHandleEvents` 在格式版本 ≥2 时为 `assistant/message` 补 `stream: []`（legacy 与版本 <2 路径零改动） |
+| 注意 | 这不是 0.1.5 新增：0.1.3-alpha.1 的旧断言同样会抛，只是 0.1.2-rc.1 线无该字段；**升级到 alpha 线后成为阻断项** |
+| 检测 | 扫描器 S3：文件出现 `assistant/message` + 会话写入迹象、且全文无 `stream:` → error |
+| 回归 | L6 级往返测试：新日志可 resume、缺 `stream` 形状被拒、legacy 可读回 |
+
+## 3. S8 · `SessionHandleReadResult`（**独家**）
+
+| 项 | 内容 |
+|---|---|
+| 目标契约 | `SessionHandle.read()` 返回 `{ eventState, events, ... }`（`packages/session/session-persistence/src/*`，commit `9b78f99dec`） |
+| 旧假设 | `read()` 返回 `SessionEvent[]`（直接 `.filter()` / `.findLast()` / 当数组用） |
+| 实测案例 | `dsh-background-agents` 生产代码 `src/tools.ts:713`（`TS2740: missing length, concat, join, slice…`）+ 两处测试；`dsh-output-styles` 的 `scripts/verify-session-log.mjs` 直接 TypeError |
+| 正确写法 | `const { events } = await handle.read()` 或 `(await handle.read()).events` |
+| 检测 | 扫描器 S8：`await X.read()` 出现但全文无 `.events`/解构解包 → error |
+| 回归 | 测试夹具改成 `.events`；verify 脚本用同一契约 |
+
+## 4. S9 · `SystemPrompt` 配置改名（**独家**）
+
+| 项 | 内容 |
+|---|---|
+| 目标契约 | `packages/core/system-prompt/src/index.ts` 的 Config：`includeHarnessIdentity?` / `includeRuntimeContext?` / `personaPrefix?` / `personaSuffix?` / `toolOrder?`（commit `40792330c0`） |
+| 旧假设 | `{ persona: '' }` |
+| 实测案例 | `dsh-data-quality`、`dsh-industry-research`、`dsh-research-report`、`dsh-fast` 的测试夹具（`TS2353: 'persona' does not exist in type 'Config'`） |
+| 正确写法 | `{ personaPrefix: '' }`；**不要**用 `includeHarnessIdentity: false` 代替——那会删掉 `harness:identity` 段，语义不等价 |
+| 官方先例 | `apps/cli/tests/profiles/headless/tests/harness.ts:59` |
+| 检测 | 扫描器 S9：`{ persona:` 且文件含 `SystemPrompt` → error |
+| 回归 | typecheck + typecheck:ci 双绿 |
+
+## 5. 其余 seam（交叉核对用，细节见 COMPLETION-REPORT §2）
+
+| seam | 一句话 | 影响仓（实测） |
+|---|---|---|
+| S1 | 会话格式 V3 + 日志世代名 `session.v3.jsonl.zstd` | 日志读写方；硬编码旧名会静默失效 |
+| S2 | `EpochHeader.system` 移除，系统提示词进 `system/message` | auto-review / fast / observe / output-styles |
+| S4 | `tool/code-dispatch` → `tool/ptc-dispatch`（V3 迁移映射） | doublecheck（4 处）/ observe（2 处） |
+| S5 | `ctx.agent` 移除 | wechat（唯一命中；替代 = setup 第 2 参） |
+| S6 | `Inbox` 类型化（不可构造） | fund-research / score / test-drive（夹具） |
+| S7 | `SubprocessHandle.pid` 移除 | click / talk / score / test-drive / lsp-actions |
+| S10 | 事件词表 fail-closed、`append` 无 `ignorable` 写入通道 | permission-rules（版本预检未覆盖新线 → 审计行未盖章 → 会话不可恢复） |
+
+## 6. 强制验证顺序（本地门禁是必要非充分）
+
+1. `scan-0.1.5.mjs` 出 `file:line` 事实（先看 M1：假绿不排掉，后面全是幻觉）。
+2. `pnpm install --no-frozen-lockfile` → `typecheck`（对 checkout）+ `typecheck:ci`（对已发布线）双绿。
+3. `test` + `build` + 仓内 `verify:*` + `pack`。
+4. **真实宿主冒烟**：临时 `DSH_HOME`（`%TEMP%` mkdtemp）+ 目标版 CLI → `dsh plugin --profile web add <tgz>` → `--dump-config` 出现插件行。
+5. 写会话日志的插件追加 **resume 往返**（S3）；有 client 半的追加真实浏览器断言（L9）。
+6. 记录：改动面、未命中项、迁移前既有失败、未验证边界、回滚点。
+
+## 7. 剩余风险与边界
+
+- 版本卡会过期：`0.1.5-alpha.1` 之后仍有新跳；本卡只对 `0.1.3-alpha.1 → 0.1.5-alpha.1` 负责。
+- 扫描器是启发式：S2/S7/S10 为 warn 级，需人工复核；M1/S3/S8/S9 为 error 级且已在合成夹具 + 真实仓双向验证。
+- 未覆盖：真机 L9（浏览器）与 L11（真实模型）在无凭据/无浏览器环境下未执行。

package/skills/plugin-upgrade-015/scripts/scan-0.1.5.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Skill-relative scanner entry.
+ *
+ * The skill body resolves its relative paths against this skill's own directory
+ * (the `resourceBase`), so `./scripts/scan-0.1.5.mjs` must exist here as well as
+ * at the package root. Both are thin wrappers over the single implementation in
+ * `<package>/lib/scan.mjs`, so the skill, the CLI and the tests share one catalog.
+ *
+ * Usage: node ./scripts/scan-0.1.5.mjs --repo <path>
+ */
+import { main } from '../../../lib/scan.mjs'
+
+process.exit(main(process.argv.slice(2)))

package/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Public type surface for dsh-plugin-upgrade.
+ * @module dsh-plugin-upgrade
+ */
+
+/** Plugin configuration (Schemastery-backed; every field is a deployment choice). */
+export interface Config {
+  /** Register the packaged skill (default true). */
+  enabled?: boolean
+  /** Skill name published to the model catalog (default 'plugin-upgrade-015'). */
+  skillName?: string
+  /** Skill root inside the package; must contain `<skillName>/SKILL.md`. */
+  skillsRoot?: string
+  /** Mark the skill user-invocable in addition to model-invocable (default true). */
+  userInvocable?: boolean
+}
+
+/** One seam hit produced by the scanner. */
+export interface SeamHit {
+  /** Seam id: S1..S10 or M1. */
+  seam: string
+  /** 'error' fails the scan; 'warn' is a manual-review lead. */
+  severity: 'error' | 'warn'
+  /** Absolute path of the file carrying the hit. */
+  file: string
+  /** 1-based line number. */
+  line: number
+  /** Trimmed source line (truncated to 200 characters). */
+  snippet: string
+  /** Human-readable explanation, including the suggested action for M1. */
+  detail: string
+}
+
+/** Scanner report for one repository. */
+export interface ScanReport {
+  repo: string
+  scannedAt: string
+  files: number
+  hits: SeamHit[]
+  bySeam: Record<string, number>
+}
+
+/** Scan a repository directory for the 0.1.3-alpha.1 -> 0.1.5-alpha.1 seams. */
+export declare function scanRepo(repoDir: string, options?: { seams?: string[] }): ScanReport
+
+/** Render a report for a terminal. */
+export declare function render(report: ScanReport): string
+
+/** CLI entry point; returns the process exit code. */
+export declare function main(argv: string[]): number
+
+/** Split a SKILL.md frontmatter block into its routing fields and body. */
+export declare function splitFrontmatter(text: string): { description?: string, whenToUse?: string, body: string }
+
+/** Read and validate a packaged skill bundle (fails loud). */
+export declare function readSkillBundle(skillsRoot: string, skillName: string): {
+  frontmatterName: string
+  description?: string
+  whenToUse?: string
+  body: string
+  skillDir: string
+}
+
+export declare const name: string
+export declare const inject: string[]
+export declare const Config: unknown
+export declare function apply(ctx: unknown, config?: Config): void