dsh-pub/dsh-pub

DSH Pub

dsh.pub 是 DeepSeek Harness 插件生态系统的双语、有来源依据的注册表。它收录当前内置模块，说明运行时和 UI 能力，并将原子模块、内置配置文件层以及固定到公开源代码的社区捆绑包区分开来。

DeepSeek Harness 源代码
│ 固定目录同步
▼
219 个源包 ──► 170 个可加载插件 ──► 英文 + 中文的 Astro 页面
│
└── 3 个清单声明的捆绑包 ──► 内置配置文件激活层

浏览器提交 ──► Turnstile ──► Worker + D1 ──► Cloudflare Workflow
│
└─► GitHub App ──► 提交 PR
│
Cloudflare Workers ◄── 主部署 ◄── 自动合并
│
└── 社区 Git 捆绑包 ──► dshpub CLI ──► 原生 dsh plugin add
└─► D1 已完成安装计数

工作区

apps/
├── web/       Astro 静态注册表
├── server/    Cloudflare Worker 安装 API 和区域设置路由
├── cli/       GitHub 捆绑包安装器（dshpub）
└── dsh-plugin/ DSH 内双语可视化目录
packages/
└── catalog/   生成的 Harness 快照和类型化访问
migrations/    D1 事件和聚合架构

本地开发

npm install
npm run build:og
npm run build
npm run dev --workspace @dsh-pub/web

要在生产构建中启用 Google Analytics，请提供公开的 GA4 衡量 ID：

PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX npm run build

要启用 Google AdSense 账户标签和可选的手动单元：

PUBLIC_ADSENSE_CLIENT_ID=ca-pub-XXXXXXXXXXXXXXXX \
PUBLIC_ADSENSE_SLOT_DETAIL=1234567890 \
PUBLIC_ADSENSE_SLOT_CATALOG=0987654321 \
npm run build

当设置了 PUBLIC_ADSENSE_CLIENT_ID 时，每个页面都会输出 AdSense 账户 meta 标签并加载
adsbygoogle.js。手动单元仅在设置了匹配的 slot 环境变量时才会渲染：详情页使用
PUBLIC_ADSENSE_SLOT_DETAIL，目录使用 PUBLIC_ADSENSE_SLOT_CATALOG。提交流程
从不托管广告单元。apps/web/public/ads.txt 必须与发布商 ID 保持一致。
网站获批后，可以稍后在 AdSense 控制台中开启自动广告；优先使用上述
手动 slot，以便发现页面保持克制的布局。

构建会在 /sitemap-index.xml 生成双语站点地图索引，在
/robots.txt 生成爬虫策略，并在每个可索引页面上生成 canonical、hreflang、Open Graph、Twitter Card 和 JSON-LD 元数据。

Web 应用运行在 http://127.0.0.1:4321。要在本地运行完整的 Worker 边界：

npx wrangler d1 migrations apply dsh-pub --local
npx wrangler dev --local --port 8787

目录同步
生成的目录固定到一个已知的 DeepSeek Harness 提交，并拒绝脏的源代码检出。

node scripts/sync-harness-catalog.mjs

仅当有意验证另一个本地路径时，才覆盖默认的相邻检出：

node scripts/sync-harness-catalog.mjs --source /path/to/deepseek-harness

CLI

npx dshpub add owner/repo \
--path packages/my-bundle \
--profile web

该命令将公共 GitHub ref 解析为确切的提交，验证所选包声明了 dsh.bundle.patch，移除验证检出，并将一个持久化的、固定提交的 Git spec 传递给 dsh plugin --profile … add …。只有原生安装成功才会报告完成。遥测为尽力而为，可通过 DO_NOT_TRACK=1 或 DISABLE_TELEMETRY=1 禁用。

当前的三个 Harness bundle 是内置的 monorepo profile 层，而非独立的 Git 包：它们的 workspace: 依赖需要 Harness workspace。因此目录将它们显示为内置 profile 层，没有安装命令或安装计数。

DSH 插件目录

该仓库还附带 @dsh-pub/plugin-directory，这是 DSH 设置中的一个只读可视化目录。它捆绑了与网站相同的公共插件和 bundle 界面，支持双语搜索、八个能力主题、来源/运行时/分发/类型过滤器，以及无需加载第三方代码的确定性排序。

npx dshpub add dsh-pub/dsh-pub --path apps/dsh-plugin --profile web

有关其更新和验证流程，请参阅 apps/dsh-plugin/README.md。

提交插件

使用 dsh.pub/submit 上的双语提交页面。浏览器将一个公共 GitHub 仓库 URL 和一个 Turnstile 令牌发送到 Worker。验证后，Worker 在 D1 中存储一个提交作业，启动一个 Cloudflare Workflow，并立即返回一个状态 URL。页面轮询该 URL，同时 Workflow 使用仓库范围的 dsh.pub GitHub App 创建或查找对应的 submissions/.json 分支和 Pull Request。用户无需 fork 仓库或点击 GitHub 的 Propose changes 操作。

受信任的 GitHub Actions 提交流程从确切的 Pull Request 提交中读取提交的文件，而不检出或执行不受信任的插件代码。它解析插件仓库当前公共默认分支的提交，验证其已提交的 bundle 契约，并运行完整的 dsh.pub 质量门禁。通过的 Pull Request 会以合并提交的方式合并，然后受信任的 main 工作流会重新生成并提交目录。现有的 Cloudflare Workers Git 集成会自动部署 main。任何人都可以提名一个公共仓库；提交者不会被视作已验证的发布者，并且现有的仓库/包路径坐标不能通过此流程被覆盖。
Web 提交页面还会生成 Markdown 和 HTML 徽章片段。在注册表提交部署之前，实时徽章会报告
not listed，之后变为 listed（带有短暂缓存）。
Pull Request 和已检入的提交文件提供了公开的审计追踪。

仓库自动化通过两个范围严格限定的令牌使用同一个 GitHub App。Pull Request
基线漂移恢复仅请求 pull_requests: write；受信任的目录集成仅请求
contents: write，且仅在 lint、测试、E2E 和构建均已通过之后。为这些
工作流配置仓库变量 DSH_PUB_APP_CLIENT_ID 和仓库密钥 DSH_PUB_APP_PRIVATE_KEY_PKCS8。
该 App 必须仅安装在 dsh-pub/dsh-pub 上，并具有 Contents 和 Pull requests 的读写访问权限。这些 Actions 名称有意与 Worker 的 GITHUB_APP_
绑定不同，因为 GitHub 保留了 GITHUB_ 前缀。Pull Request 验证永远不会收到
App 密钥或令牌。

使用两个活动的仓库规则集保护 main。main-pr-gate 要求一个 Pull Request，并且仅将 dsh.pub GitHub App Integration 列为 always 绕过执行者，允许受信任的目录作业进行经过审计的快进提交。main-ref-integrity 没有绕过执行者，并阻止删除
和非快进更新。将这些控制措施分开可防止 App、仓库
管理员和 GitHub Actions 绕过删除或强制推送保护；请勿将管理员角色或 GitHub Actions Integration 添加到任一绕过列表中。

dsh-plugin GitHub 主题每天亚洲/上海时间 01:00 同步。该工作流获取一个
截止快照，固定每个公共默认分支提交，在不
执行第三方代码的情况下验证根 bundle 契约，更新目录和可安装注册表，并将接受和
拒绝的结果记录在 packages/catalog/src/topic-analysis.generated.json 中。在截止时间之后添加或
更新的仓库将推迟到下一次运行。如果 Topic 连接在
三次完整分页尝试后仍然漂移，分析会记录未解决的覆盖范围，并保留先前快照中未见的
记录，而不是将其视为已移除。列入仅证明固定的公共 bundle 契约和所需的已提交文件通过了自动化检查；它不是
人工审查、安全审计、运行时冒烟测试、质量评分、发布者身份检查或
官方背书。标记为 community-reviewed 的较旧记录保留其历史
来源。

公开指标意味着 CLI 报告的已完成安装数。它不是唯一用户、GitHub 克隆
流量、活跃使用量，或直接通过 Git 或原生 DSH 命令执行的安装。

公开安装程序是 npm 上的 dshpub 包。使用 npx dshpub 运行它。

质量门禁

npm run lint
npm run test
npx playwright install chromium
npm run e2e
npm run build
一次性的 Playwright 安装使目录筛选 E2E 测试独立于机器的系统浏览器。CI 会安装相同的 Chromium 修订版本及其所需的操作系统依赖。

npm run eval 保持独立，因为它可能会调用真实模型并消耗凭据。

Cloudflare 部署

Worker 将 apps/web/dist 作为静态资源提供服务，并且仅对 / 和 /api/* 首先运行。插件源码和文档保留在 GitHub 中。D1 存储安装事件计数器和提交作业状态；它从不存储 GitHub App 私钥、安装令牌或 Workflow 步骤凭据。生产 Workers Builds 监视 dsh-pub/dsh-pub main 上的每个路径，运行 npm run build，并在一个 Worker 中部署静态资源、HTTP API、D1 绑定和 PluginSubmissionWorkflow。

插件提交所需的运行时绑定包括：

| 绑定                           | 用途                                                         |
| ------------------------------ | --------------------------------------------------------------- |
| TURNSTILE_SITE_KEY           | 返回给提交页面的公共站点密钥                 |
| TURNSTILE_SECRET_KEY         | 服务端 Turnstile 验证密钥                       |
| GITHUB_APP_CLIENT_ID         | 用于签署 App JWT 的 GitHub App 客户端 ID                    |
| GITHUB_APP_INSTALLATION_ID   | 限制为 dsh.pub 仓库的安装               |
| GITHUB_APP_PRIVATE_KEY_PKCS8 | 仅在 Worker 内部使用的 PKCS#8 PEM 私钥              |
| GITHUB_TARGET_REPOSITORY_ID  | 创建安装令牌时允许的数字仓库 ID |
| PLUGIN_SUBMISSION_WORKFLOW   | Wrangler Workflow 绑定；在 wrangler.jsonc 中配置       |
| DB                           | 现有 D1 绑定；在 wrangler.jsonc 中配置             |

将部署值排除在源代码管理之外。通过 Cloudflare secrets 配置上述六个字符串绑定（站点密钥和数字标识符并非机密，但统一处理完整的运行时集合可避免环境漂移）：

npm run build
npx wrangler d1 migrations apply DB --remote
npx wrangler secret put TURNSTILE_SITE_KEY
npx wrangler secret put TURNSTILE_SECRET_KEY
npx wrangler secret put GITHUB_APP_CLIENT_ID
npx wrangler secret put GITHUB_APP_INSTALLATION_ID
npx wrangler secret put GITHUB_APP_PRIVATE_KEY_PKCS8
npx wrangler secret put GITHUB_TARGET_REPOSITORY_ID
npx wrangler deploy

这个顺序是有意为之：先构建，迁移生产 D1 数据库，配置运行时密钥，然后部署依赖新 schema 和绑定的 Worker 版本。对于本地开发，将非生产值放入被忽略的 .dev.vars 文件中。切勿将 GitHub App 私钥或安装令牌放入 D1、Workflow 事件负载或持久化的 Workflow 步骤结果中。

参见产品决策、架构和研究证据。
许可证

DSH Pub 在 MIT 许可证 下提供。由 DeepSeek Harness 生成的目录文档在 THIRD_PARTY_NOTICES.md 中保留其上游声明。