dsh-plugin-guide 0.1.0

package/scripts/download-sources.ps1

@@ -0,0 +1,195 @@
+# DeepSeek Harness 插件开发资料全量下载脚本
+# 输出: dsh-plugin-guide/downloads/{web,github,community} + manifest.tsv
+# 参数: -DocRoot <路径> 官方 checkout 的 docs 目录(Phase D 站点路由来源),默认本机 checkout。
+param([string]$DocRoot = 'D:\deepseek-harness\docs')
+$ErrorActionPreference = 'Continue'
+$ProgressPreference = 'SilentlyContinue'
+
+$kit  = Split-Path $PSScriptRoot -Parent
+$dl   = Join-Path $kit 'downloads'
+New-Item -ItemType Directory -Force -Path $dl | Out-Null
+$manifest = New-Object System.Collections.Generic.List[string]
+$manifest.Add("status`thttpcode`tbytes`turl`tfile")
+
+function Log([string]$line) { $script:manifest.Add($line) }
+
+function Do-Curl([string]$url, [string]$outFile, [string]$extra) {
+  $dir = Split-Path $outFile -Parent
+  if ($dir -and -not (Test-Path $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
+  $args1 = @('-sS','-L','--max-time','90','-o',$outFile)
+  if ($extra) { $args1 += $extra }
+  $args1 += @('-w','%{http_code}', $url)
+  $code = & curl.exe @args1 2>$null
+  if (($code -match '^2') -and (Test-Path $outFile)) {
+    $sz = (Get-Item $outFile).Length
+    if ($sz -eq 0) { Remove-Item $outFile -Force; Log "FAIL`t$code`t0`t$url"; return $false }
+    Log "OK`t$code`t$sz`t$url`t$outFile"
+    return $true
+  }
+  if (Test-Path $outFile) { Remove-Item $outFile -Force -ErrorAction SilentlyContinue }
+  Log "FAIL`t$code`t0`t$url"
+  return $false
+}
+
+function Download([string[]]$urls, [string]$outFile, [string]$extra) {
+  foreach ($u in $urls) { if (Do-Curl $u $outFile $extra) { return $true } }
+  return $false
+}
+
+function Get-DefaultBranch([string]$metaFile, [string]$fallback) {
+  if (!(Test-Path $metaFile)) { return $fallback }
+  try {
+    $m = Get-Content $metaFile -Raw | ConvertFrom-Json
+    if ($m.default_branch) { return $m.default_branch }
+  } catch { }
+  return $fallback
+}
+
+$ua = @('-H','User-Agent: dsh-plugin-guide-research')
+
+# ---------- Phase A: 固定 URL ----------
+Download @('https://raw.githubusercontent.com/cordiverse/cordis/HEAD/README.md',
+          'https://raw.githubusercontent.com/cordiverse/cordis/master/README.md',
+          'https://raw.githubusercontent.com/cordiverse/cordis/main/README.md') `
+  (Join-Path $dl 'github\cordis\README.md')
+Download @('https://raw.githubusercontent.com/cordiverse/cordis/HEAD/package.json') `
+  (Join-Path $dl 'github\cordis\package.json')
+Download @('https://api.github.com/repos/cordiverse/cordis') `
+  (Join-Path $dl 'github\cordis\repo.json') $ua
+
+Download @('https://raw.githubusercontent.com/cordiverse/paper/HEAD/README.md',
+          'https://raw.githubusercontent.com/cordiverse/paper/master/README.md',
+          'https://raw.githubusercontent.com/cordiverse/paper/main/README.md') `
+  (Join-Path $dl 'github\paper\README.md')
+Download @('https://api.github.com/repos/cordiverse/paper') `
+  (Join-Path $dl 'github\paper\repo.json') $ua
+
+Download @('https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/HEAD/README.md',
+          'https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/master/README.md',
+          'https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/main/README.md') `
+  (Join-Path $dl 'github\harness\README.md')
+Download @('https://api.github.com/repos/deepseek-ai/deepseek-harness') `
+  (Join-Path $dl 'github\harness\repo.json') $ua
+
+# 官网与文档站入口页
+Download @('https://www.deepseek.com/harness/','https://www.deepseek.com/harness','https://deepseek.com/harness/') `
+  (Join-Path $dl 'web\deepseek-com-harness.html')
+Download @('https://deepseek-harness.github.io/deepseek-harness/sitemap.xml') `
+  (Join-Path $dl 'web\sitemap.xml')
+Download @('https://deepseek-harness.github.io/deepseek-harness/develop/basic/') `
+  (Join-Path $dl 'web\develop-basic.html')
+
+# ---------- Phase B: cordis 仓库全量 md 文档 ----------
+$cordisBranch = Get-DefaultBranch (Join-Path $dl 'github\cordis\repo.json') 'master'
+$treeFile = Join-Path $dl 'github\cordis\tree.json'
+Download @("https://api.github.com/repos/cordiverse/cordis/git/trees/$cordisBranch`?recursive=1") $treeFile $ua
+if (Test-Path $treeFile) {
+  try {
+    $t = Get-Content $treeFile -Raw | ConvertFrom-Json
+    $i = 0
+    foreach ($item in $t.tree) {
+      if ($item.type -ne 'blob') { continue }
+      if ($item.path -notmatch '\.(md|mdx)$') { continue }
+      $i++
+      if ($i -gt 120) { break }
+      $out = Join-Path $dl ("github\cordis\repo\" + ($item.path -replace '/','\'))
+      Download @("https://raw.githubusercontent.com/cordiverse/cordis/$cordisBranch/$($item.path)") $out
+    }
+  } catch { Log "FAIL`tparse-tree`t0`tcordis tree.json 解析失败" }
+}
+
+# ---------- Phase C: paper 仓库 md/tex ----------
+$paperBranch = Get-DefaultBranch (Join-Path $dl 'github\paper\repo.json') 'master'
+$ptreeFile = Join-Path $dl 'github\paper\tree.json'
+Download @("https://api.github.com/repos/cordiverse/paper/git/trees/$paperBranch`?recursive=1") $ptreeFile $ua
+if (Test-Path $ptreeFile) {
+  try {
+    $t = Get-Content $ptreeFile -Raw | ConvertFrom-Json
+    $i = 0
+    foreach ($item in $t.tree) {
+      if ($item.type -ne 'blob') { continue }
+      if ($item.path -notmatch '\.(md|tex|bib|typ|pdf)$') { continue }
+      $i++
+      if ($i -gt 60) { break }
+      $out = Join-Path $dl ("github\paper\repo\" + ($item.path -replace '/','\'))
+      Download @("https://raw.githubusercontent.com/cordiverse/paper/$paperBranch/$($item.path)") $out
+    }
+  } catch { Log "FAIL`tparse-tree`t0`tpaper tree.json 解析失败" }
+}
+
+# ---------- Phase D: GitHub Pages 全站爬取 ----------
+$siteBase = 'https://deepseek-harness.github.io/deepseek-harness/'
+$docRoot = $DocRoot
+$routes = New-Object System.Collections.Generic.HashSet[string]
+
+function SitePath([string]$rel) {
+  $p = $rel -replace '\.zh\.md$','' -replace '\.md$',''
+  $p = $p -replace '\\','/'
+  if ($p -match '/index$') { $p = $p -replace '/index$','' }
+  return $p
+}
+
+Get-ChildItem (Join-Path $docRoot 'user') -Recurse -Filter *.md | ForEach-Object {
+  $rel = $_.FullName.Substring((Join-Path $docRoot 'user').Length + 1)
+  [void]$routes.Add((SitePath $rel))
+}
+Get-ChildItem (Join-Path $docRoot 'cordis-tutorial') -Filter *.md | ForEach-Object {
+  [void]$routes.Add('develop/cordis-tutorial/' + (SitePath $_.Name))
+}
+Get-ChildItem (Join-Path $docRoot 'subsystems') -Filter *.md | ForEach-Object {
+  $n = SitePath $_.Name
+  [void]$routes.Add($(if ($_.BaseName -eq 'README') { 'reference/subsystems' } else { "reference/subsystems/$n" }))
+}
+@('architecture','cordis-primer','capability-seams','agent-lifecycle','tool-execution-pipeline','config-catalog','tool-catalog','persistence-catalog') | ForEach-Object {
+  [void]$routes.Add("reference/$_")
+}
+Get-ChildItem (Join-Path $docRoot 'cordis-api') -Filter *.md | ForEach-Object {
+  [void]$routes.Add('reference/cordis-api/' + (SitePath $_.Name))
+}
+@('adding-a-package','adding-a-tool','adding-an-llm-adapter','extension-cookbook','adding-a-conversation-node') | ForEach-Object {
+  [void]$routes.Add("reference/cookbook/$_")
+}
+
+$siteCount = 0
+foreach ($r in $routes) {
+  foreach ($loc in @('','en/')) {
+    $rel = $loc + $r
+    $url = $siteBase + $rel
+    $fname = $rel -replace '/','\'
+    if ($fname -eq '') { $fname = 'index' }
+    $out = Join-Path $dl ("web\site\$fname.html")
+    Do-Curl $url $out | Out-Null
+    $siteCount++
+  }
+}
+Log "INFO`t-`t$siteCount`tpages attempted`tghpages crawl"
+
+# ---------- Phase E: 社区仓库 README ----------
+$community = @(
+  @('AdamPlatin123','awesome-dsh-plugins'),
+  @('omdsh-dev','dsh-plugin-dev'),
+  @('omdsh-dev','plugin-template'),
+  @('omdsh-dev','dsh-plugin-skills'),
+  @('vlln','plugin-registry'),
+  @('0xsline','awesome-deepseek-harness'),
+  @('awesome-dsh-plugin','awesome-dsh-plugin'),
+  @('Alex-Yanggg','awesome-DSH-plugin'),
+  @('bruc3van','awesome-dsh-plugin'),
+  @('Dominic789654','awesome-deepseek-harness'),
+  @('hikariming','dshfind'),
+  @('dsh-external','hub'),
+  @('titanwings','colleague-skill')
+)
+foreach ($pair in $community) {
+  $owner = $pair[0]; $repo = $pair[1]
+  Download @("https://raw.githubusercontent.com/$owner/$repo/HEAD/README.md",
+            "https://raw.githubusercontent.com/$owner/$repo/master/README.md",
+            "https://raw.githubusercontent.com/$owner/$repo/main/README.md") `
+    (Join-Path $dl "community\$repo.md")
+  Download @("https://api.github.com/repos/$owner/$repo") `
+    (Join-Path $dl "community\$repo.json") $ua
+}
+
+# ---------- Phase F: manifest ----------
+Set-Content -Path (Join-Path $dl 'manifest.tsv') -Value $manifest -Encoding UTF8
+Write-Output ("DONE: " + $manifest.Count + " 条记录 -> " + (Join-Path $dl 'manifest.tsv'))

package/scripts/gen-topic-snapshot.ps1

@@ -0,0 +1,91 @@
+# dsh-plugin-guide 话题快照生成脚本
+# 用途: 抓取 GitHub topic:dsh-plugin 全量仓库清单,产出与 sources.md §D.2 记录一致的快照目录
+#   <OutDir>/raw-github-api-page-<n>.json + repos.tsv + README.md(全量表)
+# 用法: pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <路径> [-PerPage 100] [-MaxPages 10] [-DelaySeconds 6]
+# 说明: 走 GitHub Search API(未认证 10 次/分钟、分页上限 1000 条),分页抓取、按 full_name 去重、按 star 降序;
+#       提供 $env:GH_TOKEN / -Token 后限速提到 30 次/分钟且更稳定。
+#       传输用 Invoke-WebRequest(PS 5.1 下 curl 数组参数的引号拆分会把 -H 头打碎——已规避)。
+#       与 08-13/08-14 各期快照同构,便于续期对比(新增/消失仓库用 repos.tsv diff)。
+param(
+  [Parameter(Mandatory=$true)][string]$OutDir,
+  [int]$PerPage = 100,
+  [int]$MaxPages = 10,
+  [int]$DelaySeconds = 6,
+  [string]$Token = $env:GH_TOKEN
+)
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+
+$headers = @{ 'User-Agent' = 'dsh-plugin-guide-research'; 'Accept' = 'application/vnd.github+json' }
+if ($Token) { $headers['Authorization'] = "Bearer $Token" }
+
+$all = @()
+$total = -1
+for ($p = 1; $p -le $MaxPages; $p++) {
+  $r = $null
+  for ($a = 0; $a -lt 3 -and $null -eq $r; $a++) {
+    try {
+      $resp = Invoke-WebRequest -Uri "https://api.github.com/search/repositories?q=topic:dsh-plugin&per_page=$PerPage&page=$p" -Headers $headers -TimeoutSec 45 -UseBasicParsing
+      $r = $resp.Content | ConvertFrom-Json
+    } catch { Start-Sleep -Seconds 3 }
+  }
+  if ($null -eq $r) { Write-Output "page ${p} FAILED (after retries)"; break }
+  if ($r.PSObject.Properties.Name -contains 'message') { Write-Output "page ${p}: API message $($r.message)"; break }
+  if (@($r.items).Count -eq 0) { Write-Output "page ${p}: no items (end)"; break }
+  $total = $r.total_count
+  $all += @($r.items)
+  $raw = Join-Path $OutDir "raw-github-api-page-$p.json"
+  $r | ConvertTo-Json -Depth 6 | Set-Content $raw -Encoding UTF8
+  Write-Output "page ${p}: total=$($r.total_count) items=$(@($r.items).Count)"
+  Start-Sleep -Seconds $DelaySeconds
+  if ($all.Count -ge $total -or @($r.items).Count -lt $PerPage) { break }
+}
+
+$uniq = @{}
+foreach ($i in $all) { if (-not $uniq.ContainsKey($i.full_name)) { $uniq[$i.full_name] = $i } }
+$rows = @($uniq.Values | Sort-Object -Property stargazers_count -Descending)
+
+$tsv = @("full_name`tstars`tlanguage`tlicense`tarchived`tpushed_at`tdescription")
+foreach ($i in $rows) {
+  $desc = ($i.description -replace "[\r\n\t]", ' ')
+  $tsv += "{0}`t{1}`t{2}`t{3}`t{4}`t{5}`t{6}" -f $i.full_name, $i.stargazers_count, $i.language, $i.license.spdx_id, $i.archived, $i.pushed_at, $desc
+}
+Set-Content -Path (Join-Path $OutDir 'repos.tsv') -Value ($tsv -join "`r`n") -Encoding UTF8
+
+$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mmZ')
+$L = @()
+$L += '# DeepSeek Harness `dsh-plugin` 话题全量清单'
+$L += ''
+$L += '> 数据来源：GitHub Search API `q=topic:dsh-plugin`（公开话题页 <https://github.com/topics/dsh-plugin>）。'
+$L += "> 抓取时间：$utc（UTC）。API total_count $total；本清单去重收录 $($rows.Count) 个。"
+$L += '> 注意：Search API 分页上限 1000 条，去重数与 total_count 都要记录（见 sources.md §D.2 惯例）。'
+$L += ''
+$L += '## 元信息'
+$L += ''
+$L += '| 项目 | 值 |'
+$L += '|---|---|'
+$L += '| 话题 | [dsh-plugin](https://github.com/topics/dsh-plugin) |'
+$L += "| 仓库总数 | $($rows.Count)（API total_count $total） |"
+$L += "| 抓取时间 (UTC) | $utc |"
+$L += '| 排序 | star 数降序 |'
+$L += ''
+$L += '## 全量清单（按 star 排序）'
+$L += ''
+$L += '| # | 仓库 | ⭐ | 语言 | 许可 | 归档 | 功能 / 效果（官方描述） | 最近推送 (UTC) | 话题标签 |'
+$L += '|---|------|----|------|------|------|----------------|----------------|----------|'
+$n = 0
+foreach ($i in $rows) {
+  $n++
+  $name = $i.full_name
+  $stars = $i.stargazers_count
+  $lang = $i.language
+  $lic = if ($i.license) { $i.license.spdx_id } else { '-' }
+  $arch = if ($i.archived) { '是' } else { '否' }
+  $desc = ($i.description -replace '\|','\|' -replace "[\r\n]", ' ')
+  $push = $i.pushed_at
+  $topics = if ($i.topics) { ($i.topics -join ', ') } else { '' }
+  $L += "| $n | [$name](https://github.com/$name) | $stars | $lang | $lic | $arch | $desc | $push | $topics |"
+}
+Set-Content -Path (Join-Path $OutDir 'README.md') -Value ($L -join "`r`n") -Encoding UTF8
+Write-Output "DONE: $($rows.Count) unique repos -> $OutDir (README/repos.tsv/raw pages)"

package/scripts/install-skill.ps1

@@ -0,0 +1,63 @@
+# dsh-plugin-guide skill installer.
+# Purpose: copy the KB (excluding generated/local-only parts) into an agent skill directory and verify byte parity.
+# Usage:   pwsh -File scripts/install-skill.ps1 -Target <skill-dir> [-Source <kb-root>]
+# Scope:   SKILL.md, guide/, references/ (incl. official-docs), scripts/, README*.md, LICENSE, NOTICE.md, CONTRIBUTING.md, SECURITY.md.
+# Excluded: downloads/ (generated by scripts), .github/ (CI), .gitignore.
+# Target must be the skill directory itself (e.g. ~/.deepseek/skills/dsh-plugin-guide or <project>/.agents/skills/dsh-plugin-guide).
+param(
+  [Parameter(Mandatory=$true)][string]$Target,
+  [string]$Source = ''
+)
+$ErrorActionPreference = 'Stop'
+if (-not $Source) { $Source = Split-Path $PSScriptRoot -Parent }
+$src = (Resolve-Path $Source).Path
+$top = @('SKILL.md','LICENSE','NOTICE.md','CONTRIBUTING.md','SECURITY.md') + @(Get-ChildItem $src -Filter 'README*.md' -File | ForEach-Object { $_.Name })
+$dirs = @('guide','references','scripts')
+
+New-Item -ItemType Directory -Force -Path $Target | Out-Null
+
+foreach ($f in $top) { Copy-Item (Join-Path $src $f) (Join-Path $Target $f) -Force }
+foreach ($d in $dirs) {
+  # Copy-Item -Recurse into an existing directory would nest the source inside it; replace the owned dir instead.
+  $td = Join-Path $Target $d
+  if (Test-Path $td) { Remove-Item $td -Recurse -Force }
+  Copy-Item (Join-Path $src $d) $td -Recurse -Force
+}
+
+# Prune target files under the owned scope that no longer exist in the source (keeps reinstalls clean).
+foreach ($d in $dirs) {
+  $td = Join-Path $Target $d
+  if (Test-Path $td) {
+    $sd = Join-Path $src $d
+    $sRoot = (Resolve-Path $sd).Path
+    $tRoot = (Resolve-Path $td).Path
+    Get-ChildItem -Recurse -File $td | ForEach-Object {
+      $rel = $_.FullName.Substring($tRoot.Length + 1)
+      if (-not (Test-Path (Join-Path $sRoot $rel))) { Remove-Item $_.FullName -Force }
+    }
+  }
+}
+Get-ChildItem $Target -File -ErrorAction SilentlyContinue | ForEach-Object {
+  if (($_.Name -like 'README*.md' -or $top -contains $_.Name) -and -not (Test-Path (Join-Path $src $_.Name))) { Remove-Item $_.FullName -Force }
+}
+
+# Parity report: every scoped source file must exist in the target byte-for-byte.
+$checked = 0; $mismatch = 0
+foreach ($f in $top) {
+  $s = Join-Path $src $f; $t = Join-Path $Target $f
+  if (Test-Path $t) { $checked++; if ((Get-FileHash $s -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $f" } }
+  else { $mismatch++; Write-Output "MISSING-TARGET: $f" }
+}
+foreach ($d in $dirs) {
+  $sd = Join-Path $src $d
+  $sRoot = (Resolve-Path $sd).Path
+  Get-ChildItem -Recurse -File $sd | ForEach-Object {
+    $rel = $_.FullName.Substring($sRoot.Length + 1)
+    $t = Join-Path (Join-Path $Target $d) $rel
+    if (Test-Path $t) { $checked++; if ((Get-FileHash $_.FullName -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $d\$rel" } }
+    else { $mismatch++; Write-Output "MISSING-TARGET: $d\$rel" }
+  }
+}
+Write-Output "DONE: $checked scoped files verified, $mismatch mismatches -> $Target"
+if ($mismatch -gt 0) { exit 1 }
+exit 0

package/scripts/sync-official-docs.ps1

@@ -0,0 +1,130 @@
+# dsh-plugin-guide official-docs sync script.
+# Purpose: sync the deepseek-harness checkout's official docs into references/official-docs/ (verbatim copy).
+# Source is pinned to origin/master (HEAD fallback): untracked drafts and unpushed commits in the checkout never enter the KB.
+# Output: references/official-docs/SNAPSHOT.md (source ref/SHA, sync time, file counts - the freshness authority for READMEs).
+# Usage:  pwsh -File scripts/sync-official-docs.ps1 [-Checkout <path>] [-SkipGit]
+# Verify: pwsh -File scripts/verify-kit.ps1 -Checkout <path>   # drift report KB vs checkout (tracked files only)
+param(
+  [string]$Checkout = 'D:\deepseek-harness',
+  [switch]$SkipGit
+)
+$ErrorActionPreference = 'Stop'
+$kit  = Split-Path $PSScriptRoot -Parent
+$dest = Join-Path $kit 'references\official-docs'
+
+if (-not (Test-Path $Checkout)) { Write-Error "checkout not found: $Checkout"; exit 1 }
+
+$gitOk = $false
+if (-not $SkipGit) {
+  $gitOk = (& git -C $Checkout rev-parse --is-inside-work-tree 2>$null) -eq 'true'
+}
+
+$ref = 'filesystem'
+$sha = ''
+$pruned = 0
+$mdCount = 0
+$zhCount = 0
+
+# Sync scope: docs/, root AGENTS.md/BENCHMARK.md/CLAUDE.md/CONTRIBUTING.*/README.zh.md/README.i18n.yaml/THIRD_PARTY_NOTICES.md/LICENSE, packages/AGENTS.md, examples/AGENTS.md, packages/README.md, vendor/README.md, website/docs.ts
+# 上游 root README.md 不在此列：official-docs/README.md 是 KB 自有索引（上游英文 README 快照在 downloads/github/harness/README.md）。
+# pathspec 全部用 :(top) 锚定，避免 git 的 basename 全局匹配把仓库深处的同名 symlink（如各处 CLAUDE.md）误收进归档。
+$paths = @(':(top)docs', ':(top)AGENTS.md', ':(top)BENCHMARK.md', ':(top)CONTRIBUTING.md', ':(top)CONTRIBUTING.zh.md', ':(top)CONTRIBUTING.i18n.yaml', ':(top)README.zh.md', ':(top)README.i18n.yaml', ':(top)THIRD_PARTY_NOTICES.md', ':(top)LICENSE', ':(top)packages/AGENTS.md', ':(top)examples/AGENTS.md', ':(top)packages/README.md', ':(top)vendor/README.md', ':(top)website/docs.ts')
+
+if ($gitOk) {
+  # Prefer origin/master, fall back to HEAD - never the working tree (may contain untracked/unpushed content).
+  if ((& git -C $Checkout rev-parse --verify -q origin/master 2>$null)) { $ref = 'origin/master' } else { $ref = 'HEAD' }
+  $sha = (& git -C $Checkout rev-parse $ref).Trim()
+
+  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("dsh-official-docs-$sha.tar")
+  Remove-Item $tmp -Force -ErrorAction SilentlyContinue
+  & git -C $Checkout archive -o $tmp $ref -- $paths
+  if ($LASTEXITCODE -ne 0) { Write-Error "git archive failed (ref=$ref)"; exit 1 }
+
+  New-Item -ItemType Directory -Force -Path $dest | Out-Null
+  & tar -xf $tmp -C $dest
+  if ($LASTEXITCODE -ne 0) { Write-Error 'tar extraction failed'; exit 1 }
+  Remove-Item $tmp -Force
+
+  # CLAUDE.md 在上游是 symlink（指向 AGENTS.md，mode 120000）；Windows tar 无法解出 symlink，
+  # 且 pathspec 'CLAUDE.md' 会 basename 匹配到仓库深处同名 symlink，故不在 $paths 中——解包后按其
+  # symlink 目标文本落地同名普通文件（内容即上游 blob 原文）。
+  $claudeTarget = (& git -C $Checkout cat-file -p "${ref}:CLAUDE.md" 2>$null | Select-Object -First 1)
+  if (-not $claudeTarget) { $claudeTarget = 'AGENTS.md' }
+  Set-Content -Path (Join-Path $dest 'CLAUDE.md') -Value $claudeTarget -Encoding UTF8
+
+  # website/docs.ts keeps its in-repo filename in the archive; move it to the KB's flat name.
+  if (Test-Path (Join-Path $dest 'website\docs.ts')) {
+    Copy-Item (Join-Path $dest 'website\docs.ts') (Join-Path $dest 'website-docs.ts') -Force
+    Remove-Item (Join-Path $dest 'website\docs.ts') -Force
+    Remove-Item (Join-Path $dest 'website') -Force -Recurse -ErrorAction SilentlyContinue
+  }
+
+  # 目的目录只保留范围内条目（清掉历史抽取残留/上游删除的根文件，保证逐字副本无污染）。
+  $rootKeep = @('docs','examples','packages','vendor','AGENTS.md','BENCHMARK.md','CLAUDE.md','CONTRIBUTING.md','CONTRIBUTING.zh.md','CONTRIBUTING.i18n.yaml','LICENSE','README.zh.md','README.i18n.yaml','THIRD_PARTY_NOTICES.md','SNAPSHOT.md','README.md','website-docs.ts')
+  Get-ChildItem -Force $dest | Where-Object { $rootKeep -notcontains $_.Name } | ForEach-Object {
+    Remove-Item $_.FullName -Recurse -Force; $pruned++
+  }
+  foreach ($sub in @('examples','packages','vendor')) {
+    $subDir = Join-Path $dest $sub
+    if (Test-Path $subDir) {
+      $subKeep = @()
+      if ($sub -eq 'examples') { $subKeep = @('AGENTS.md') }
+      if ($sub -eq 'packages') { $subKeep = @('AGENTS.md','README.md') }
+      if ($sub -eq 'vendor')   { $subKeep = @('README.md') }
+      Get-ChildItem -Force -Directory $subDir -ErrorAction SilentlyContinue | ForEach-Object {
+        Remove-Item $_.FullName -Recurse -Force; $pruned++
+      }
+      Get-ChildItem -Force -File $subDir -ErrorAction SilentlyContinue | Where-Object { $subKeep -notcontains $_.Name } | ForEach-Object {
+        Remove-Item $_.FullName -Force; $pruned++
+      }
+    }
+  }
+
+  # Prune docs/ files that no longer exist in the source ref (a verbatim copy does not keep upstream-deleted content).
+  $tracked = New-Object System.Collections.Generic.HashSet[string]
+  foreach ($t in (& git -C $Checkout ls-tree -r --name-only $ref -- docs)) { [void]$tracked.Add($t.Replace('\','/')) }
+  $docsDir = Join-Path $dest 'docs'
+  if (Test-Path $docsDir) {
+    $docsRoot = (Resolve-Path $docsDir).Path
+    Get-ChildItem -Recurse -File $docsDir | ForEach-Object {
+      $rel = 'docs/' + $_.FullName.Substring($docsRoot.Length + 1).Replace('\','/')
+      if (-not $tracked.Contains($rel)) { Remove-Item $_.FullName -Force; $pruned++ }
+    }
+  }
+} else {
+  Write-Output 'WARN: checkout is not a git repo (or -SkipGit) - copying the filesystem as-is; untracked files are not filtered and no pruning runs.'
+  foreach ($p in $paths) {
+    $rel = $p -replace '^:\(top\)',''   # 去掉 pathspec 锚定前缀得到仓库内相对路径
+    $srcFull = Join-Path $Checkout ($rel -replace '/','\')
+    if (-not (Test-Path $srcFull)) { Write-Output "SKIP(source missing): $rel"; continue }
+    $target = Join-Path $dest ($rel -replace '/','\')
+    $tdir = Split-Path $target -Parent
+    if ($tdir -and -not (Test-Path $tdir)) { New-Item -ItemType Directory -Force -Path $tdir | Out-Null }
+    Copy-Item $srcFull $target -Recurse -Force
+  }
+}
+
+$mdCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.md).Count
+$zhCount = (Get-ChildItem -Recurse -File (Join-Path $dest 'docs') -Filter *.zh.md).Count
+$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+$L = @(
+  '# official-docs snapshot (SNAPSHOT.md)',
+  '',
+  '> Generated by `scripts/sync-official-docs.ps1`. This file is the single authority for how `references/official-docs/` lines up with upstream deepseek-harness.',
+  '> The "last verified" dates and commit SHAs in README/guide must cite this file; do not hand-edit them.',
+  '',
+  '| Item | Value |',
+  '|---|---|',
+  "| Source checkout | ``$Checkout`` |",
+  "| Source ref | ``$ref`` |",
+  "| Source commit | ``$sha`` |",
+  "| Synced at (UTC) | $utc |",
+  '| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md`(symlink 目标文本), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml`（上游英文 `README.md` 不在本目录，快照见 `downloads/github/harness/README.md`）, `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `examples/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |',
+  "| File counts | docs/: $mdCount md files ($zhCount .zh.md pairs) |",
+  "| Pruned this run | $pruned 个不在范围内/上游已删除的条目 |",
+  '',
+  'Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).'
+)
+Set-Content -Path (Join-Path $dest 'SNAPSHOT.md') -Value ($L -join "`r`n") -Encoding UTF8
+
+Write-Output "DONE: ref=$ref sha=$sha pruned=$pruned -> $dest"