dsh-plugin-guide 0.3.29 → 0.3.31

package/scripts/download-sources.ps1

@@ -1,195 +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') | 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'))
+# 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') | 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

@@ -1,91 +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)"
+# 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)"