royenheart/dsh-migrate-bot

dsh-migrate-bot

GitHub Action，用于监视 DeepSeek Harness（dsh-v）发布，并迁移第三方插件：机械测试、两次 dsh 审查会话（DeepSeek V4 Flash，thinking max，随附的 standard agent 预设）、修复循环，然后仅在插件树有变更时创建 Issue 和 PR。

通过向插件仓库添加工作流来安装它。它在该仓库的 GitHub 托管运行器上运行。将 DEEPSEEK_API_KEY_DSH_MIGRATE_BOT 作为仓库密钥提供（或通过 api_key_env / secrets.apiKeyEnv 使用其他名称）。

将 Action 固定为 royenheart/dsh-migrate-bot@v0。

用法

1. 添加仓库密钥 DEEPSEEK_API_KEY_DSH_MIGRATE_BOT。
2. 将 examples/workflow.yml 复制到 .github/workflows/dsh-migrate.yml 并设置 cron。
3. 可选：将 examples/dsh-migrate.yml 复制到 .github/dsh-migrate.yml。

所需权限：contents: write、issues: write、pull-requests: write，以及 Allow GitHub Actions to create and approve pull requests（Settings → Actions → General → Workflow permissions）；如果没有勾选该项，GITHUB_TOKEN 可以推送分支并打开 Issue，但在 POST /pulls 时会收到 403。

首次运行始终会执行。之后的计划运行在 dsh-v 未发生变化时跳过（status: skipped）。在 workflow_dispatch 上使用 force: true 重新运行同一版本。

每个配置键、其默认值以及可选反馈渠道都在 docs/installation.md 中。

最后处理的版本存储在分支 dsh-migrate/state 上（seen.json + badge.json）。保持该分支不被合并。seen.json 是监视游标（当 dsh 未变化时跳过下一次 cron）和命令账本——记录哪些 /dsh-migrate 命令已经执行过，因此重新投递的命令会被应答而不是重复执行；删除该文件会遗忘这些记录。badge.json 是用于 默认分支 支持的 shields.io 端点：一次干净的 compatible 运行会立即验证；迁移 PR 会保持 pending，直到你合并它（如果你关闭它则为 unverified）。.dsh-migrate/ 下的报告（A/B/C、harness checkout、每个补丁的报告）会作为 artifact 上传，不会被提交。

公开 README 徽章（替换 OWNER / REPO）：

dsh

复制 examples/workflow.yml，以便在你合并或拒绝迁移 PR 时，pull_request: closed 会刷新徽章。在首次 Action 运行写入 badge.json 之前，shields.io 可能会显示 invalid。

流水线

flowchart TD
start([Schedule, dispatch, or release event]) --> resolve[Resolve target dsh-v]
resolve --> gate{Same version as last successon dsh-migrate/state?}mermaid
gate -->|yes, not forced| skipped([skipped])
gate -->|first run, updated, or force| base[Baseline probe: boot theunmodified plugin on the FROM tag]

base --> v1[V1 fast gatescan, typecheck, build, unit tests]
v1 --> skipAB{skip-if-mechanical-passand V1 passed?}
skipAB -->|yes| final
skipAB -->|no| checkout[Sparse-checkout target harness]
checkout --> A[Review A: official overlap]
A --> B[Review B: design alignment]

B --> loop{V2 boot on TO probe}
loop -->|fail| C[Repair Cn:A+B, failing subset, prior C]
C --> conv{agent-declared BLOCKERwith evidence, orsignature unchanged twice?}
conv -->|yes| patchreport[Stop: patch-report exit]
conv -->|no| loop
loop -->|pass| e2e[V3 E2E subsetfailing tests + smoke]
e2e -->|fail| C
e2e -->|pass| final

final[V4 full verificationV1 + boot on TO + full E2E]
final --> e2ebranch[Update dsh-migrate/e2e branch:discover, extend or create suite,refresh index.json]
e2ebranch --> dirty{Plugin tree dirty?ignore .dsh-migrate}
dirty -->|no| nopublish[No Issue or PR]
dirty -->|yes| pr[Open Issue + PR with Closes]
pr --> comment[Comment on Issue:PR link, patch table, report bodies]
comment --> rec
nopublish --> rec{Verification passed?}
rec -->|yes| save[Record processed version on dsh-migrate/state]
rec -->|no| failed([failed — next schedule retries])
save --> done([compatible or migrated])
done -.->|only when a maintainer merges the migrate PR| feedback[Feedback channels]

1. 解析目标 dsh-v（latest 或固定版本）。latest 使用 GITHUB_TOKEN 读取 GitHub releases；如果该调用被拒绝（速率限制、服务中断、无网络路由），则回退到 git ls-remote --tags，并按版本顺序选择最新的 dsh-v，因此未认证的每小时 60 次配额不会导致运行失败。
2. 如果该版本与 dsh-migrate/state 匹配，则跳过，除非设置了 force 或 watch.enabled 为 false。失败的运行不会更新分支，因此下一次调度会重试。
3. 基线探测（verify.boot）：在 Action 上次处理的先前 dsh-v 下启动未修改的插件树。它不决定是否运行——它决定归因（pre-existing 还是 we broke it）和范围（通过的基线将问题限制在 from → to 这一跳；失败的基线意味着插件落后了好几个走廊，agent 必须进一步回溯）。如果没有记录的基线，则使用声明的 @deepseek-ai/dsh- peer 版本；如果两者都没有，则跳过基线并报告为缺失。
4. V1 快速门禁：静态扫描（插件形状、键控槽位），然后运行插件自身的 build / typecheck / 单元测试——或 tests.commands，它会替换默认测试套件。缺失的 node_modules 会执行 npm install，然后将每个 @deepseek-ai/dsh- 依赖固定到目标版本，以便 typecheck 和测试看到该 harness。DSH_MIGRATE_TARGET_VERSION 会在这些命令上设置。
5. 将目标 harness 标签以稀疏检出方式检出到 .dsh-migrate/harness（不提交）。审查：always（默认）先运行重叠检查（A），再运行对齐检查（B）；skip-if-mechanical-pass 在快速门禁通过时跳过 A/B。
6. 在 A/B/C 期间，agent 保留插件已记录的产品形态（README 功能、具名入口点、用于完整表面的 patches/）。只有当官方重叠吸收了该特定表面（相同的槽位、菜单、RPC 或行为）时，它才可以缩减或退役某个表面。回退或静默降级不算覆盖，更粗粒度的官方接缝也不是同一项工作。当官方扩展点仍无法覆盖该表面时，dsh 侧补丁保留。对于每个剩余补丁，它写入 .dsh-migrate/patch-reports//report.md：先搜索官方 issues / PRs / discussions 并记录链接；如果不存在，则写一份讨论草稿（# [Feature request] …、英文摘要、Background、Current state、Proposal、Appendix: patch、Questions to confirm、Related）。
7. V2 启动探测（verify.boot）：将迁移后的树安装到临时配置中，并在目标标签下实际启动 dsh。该探测无需密钥——它将模型路由指向一个死端口，并将“到达凭据检查”视为成功启动。它在以下情况失败：plugin(s) failed to load、apply 抛出异常、pending (waiting for services: …)，或看门狗超时（dsh 自身没有挂起保护）。
8. 探测失败时，修复会话获得 A+B、仅失败的那部分输出，以及先前的 C1..Cn-1；然后重新运行探测。无论基线如何，该循环都保留完整的 loop.maxAttempts 预算。它仅在有以下证据时提前停止：agent 声明 BLOCKER: upstream 并附上其尝试过的插件侧修复、出问题的 harness 源代码位置，以及为什么任何插件侧更改都无法奏效；或者连续两轮产生未变化的失败签名。无论哪种情况，结果都进入现有的补丁报告出口。
9. V3 E2E 子集 / V4 完整 E2E（e2e）：agent 编写的测试套件在循环期间运行先前失败的测试加上一组冒烟测试，并在最终验证时运行全部测试。参见 docs/design/e2e-migration-pipeline.md。
10. 干净的插件树：没有 Issue，没有 PR（.dsh-migrate/ 和 .secrets.local.json 不算作脏，且从不提交）。干净的运行仍会验证版本，因此徽章可以显示 compatible 而无需拉取请求。
11. 脏插件树：开一个 Issue 和一个 PR。PR 正文包含 Closes #。随后 Action 会在 Issue 上评论：伴随 PR 的 URL、一个补丁报告索引表，然后是每个报告正文（issuePr.language：en 或 zh）。对于每个草稿（尚无官方讨论帖），它会发布一条后续评论，附带一个 Ideas 的“开启官方讨论”链接。完整的 A/B/C 报告保留在 artifact 中。自动创建该官方主题尚未实现；参见 docs/official-discussion-auto-post.md。

E2E 套件分支

由 agent 编写的端到端套件位于其独立分支（e2e.branch，默认为 dsh-migrate/e2e），且绝不会出现在迁移 PR 中：
mermaid
flowchart LR
main[default branch] --- e2e["dsh-migrate/e2eindex.json / INDEX.mdspecs / snapshot baselines"]
main --- prbranch["dsh-migrate/VERSION-STAMPmigration PR"]
e2e -.->|force rebase onto the migration branch head| prbranch

- 首次运行：agent 会检查仓库中是否存在现有框架（playwright.config.、cypress.config.、vitest.config.、test:e2e 脚本、现有的 e2e/ 目录、CI 浏览器安装）。如果存在，它会扩展该框架；否则它会在 e2e.dir 下使用 Playwright + Chromium 创建套件，与 dsh 自身所用保持一致。
- 此后的每次运行都会复用并扩展同一套件，因此覆盖率会不断累积，而不是被重建。如果你自行合并该分支，下一次运行的发现步骤只会发现框架已经存在并继续扩展它——两者是幂等的。
- e2e.gate 默认为 advisory：在首次运行时，套件是在迁移之后*编写的，因此它是一个弱信号。一旦存在具有绿色基线的套件，就将其设置为 blocking。
- 基线快照位于此分支上；在那里刷新它们，而不是在迁移 PR 内。

整个设计——层定义、基线归属表、预算策略、BLOCKER 证据规则、UI 断言策略以及测试矩阵——都在 docs/design/e2e-migration-pipeline.md 中。

仅写入了 .dsh-migrate/ 的运行被视为干净。官方余额不足，或本次运行支出超过 quota.limit / quota_limit，会在不开启 Issue 或 PR 的情况下中止。

12. 如果维护者之后合并了迁移拉取请求，Feedback 阶段会向你启用的渠道报告发生了什么。被关闭但未合并的拉取请求不会报告任何内容。

配置

键的完整表格、其默认值、Action 输入以及配额行为都在 docs/installation.md 中。简版如下：

| 字段 | 默认值 |
|---|---|
| model | deepseek-v4-flash |
| thinking | enabled / max |
| mode | standard（dsh agent 预设 id：standard、minimal、cordis 或 ptc） |
| review | always |
| watch | enabled |
| 启动探测 | 已启用，180 秒看门狗 |
| 看门狗 | 代理会话 60 分钟，每个机械命令 20 分钟，harness 检出 10 分钟 |
| Web 冒烟测试 | 已启用（仅当插件具有 dsh.client 接口时） |
| E2E 套件 | 已启用，分支 dsh-migrate/e2e，门禁 advisory |
| Issue/PR 语言 | en |
| 修复循环 | 5（完整预算；提前停止由证据驱动） |
| 反馈渠道 | 三者均关闭 |
| API 密钥 secret | DEEPSEEK_API_KEY_DSH_MIGRATE_BOT |
| 配额限制 | 未设置（本次运行的官方 USD 上限） |

覆盖提示词位于 .github/dsh-migrate.yml 中的 prompts.absorption、prompts.alignment 和 prompts.fix 下。

反馈

迁移拉取请求是一种意见；合并它是维护者的裁决。当迁移拉取请求被合并时，该 Action 会将迁移情况——合并本身、围绕它的评论，以及维护者在合并前更改的文件——报告给所有已启用的渠道：
mermaid
flowchart TD
pr[Migrate PR opened] --> open{Maintainer acts}
open -->|closed unmerged| nothing([Nothing is reported])
open -->|merged| read[Collect: merge, comments,maintainer's edits, run reports]
read --> loop{Each enabled channel}
loop -->|no token| skip[Skip and log why]
loop -->|one agent session| kind{Kind}
kind -->|analysis| deliver[Deliver an issue,a pull, or both]
kind -->|dedupe| check{Draft already asked?}
check -->|no| deliver
check -->|yes| hold[Log the thread that covers it]

| 渠道 | 写入到 | 方式 |
|---|---|---|
| upgrade-skill | oh-my-dsh/dsh-plugin-upgrade-skill | issue——一张错误的卡片，或一条没有卡片的走廊 |
| migrate-bot | royenheart/dsh-migrate-bot | issue——维护者手动修复了什么，以及哪个阶段本应捕获它 |
| harness-discussion | deepseek-ai/deepseek-harness | discussion——迁移已经起草的功能请求，除非它现在是重复的 |

这三个渠道默认全部关闭，每个都需要一个能够写入其自身目标的 token（GITHUB_TOKEN 无法做到），而一个已启用但没有 token 的渠道会被跳过，并在日志中记录原因，而不是让运行失败。你也可以用自己的提示词和目标定义自己的渠道。

使用 docs/installation.md 进行设置；该机制的设计见 docs/design/migration-feedback.md。
在你配置了自己的部署目标后（可选，默认关闭），同一次运行还会流式传输一个只读实时视图，你可以在它工作时观看，并且每个迁移拉取请求都可以获得一个预览实例，用于提供迁移后的插件，这样你无需克隆任何东西就能试用。预览带有一个 /safe 入口，它不加载任何第三方插件，在一个永远不会到达分支的临时树中迭代，并且只通过此 Action 的关卡进行发布。实时视图和命令界面——/dsh-migrate status|feedback|redeploy|destroy|extend|publish，每个动词所接受的标志见 docs/installation.md——在 docs/installation.md 中实现和配置。publish 是唯一一个由 Action 自身完成其工作的动词：它冻结临时修订，应用它，在该作业中运行关卡，并且只推送绿色的树。这些命令所指向的预览实例，以及将冻结修订提供回来的目标，设计于 docs/design/preview-and-live-view.md，它们是部署目标必须提供的那一半。

上游基准测试

vendor/ 下一层目录以子模块形式保存社区迁移考试套件（oh-my-dsh/dsh-plugin-upgrade-skill），并固定到一个提交——绝不固定到 main，因为他们自己的可比性规则要求冻结快照。他们的任务附带参考答案，而 oracle 运行必须恰好得分 1.0；该自检在此处运行，无需 Harbor 或 API 密钥：
sh
git submodule update --init vendor/dsh-plugin-upgrade-skill
npm run check:upstream                      # oracle self-check, no API key needed
DEEPSEEK_API_KEY=... ./tools/harbor/run-benchmark.sh M1-host-migration

第二种形式在本项目自己的 agent 上对他们的考试任务进行评分：tools/harbor/dsh_agent.py 是一个 Harbor agent 适配器，它将随附的 migrate 配置文件上传到任务容器中，并逐字运行任务陈述。

DSH_HARBOR_SKILLS 选择被测的迁移——native 仅从 harness 源进行迁移，upgrade-skills 还会加载此仓库所附带的社区技能——而 BENCH_RUNS 设置每个任务的尝试次数。每次尝试都会记录其奖励、token 和持续时间，并且该运行的服务构建会被探测一次，以便可以将得分归因到确切的 backend。这两种模式对彼此说明了什么，以及为什么差异是一个方向而不是一次测量，见 docs/upstream-benchmark.md。

native 迁移

| Scored | Attempts | Mean reward | Full score | Cache-miss in | Cache-hit in | Out | Cost |
|---|---|---|---|---|---|---|---|
| 54/56 | 168 (3/任务) | 0.641 | 25 | 17.4M | 1752.3M | 13.7M | $16.11 |

上游 ecab245，dsh 0.1.1-rc.2, 0.1.2-alpha.2，每个任务 3 次尝试。由 deepseek-flash 提供服务，指纹 aeb56401ca74e127821c4f9126dcb669。

每个任务的奖励、范围和 token 计数：20260912T201310+0000-native.json。

upgrade-skills 迁移

| 已评分 | 尝试次数 | 平均奖励 | 满分 | 缓存未命中输入 | 缓存命中输入 | 输出 | 成本 |
|---|---|---|---|---|---|---|---|
| 54/56 | 168 (3/任务) | 0.684 | 29 | 23.6M | 2017.2M | 14.6M | $18.37 |

上游 ecab245，dsh 0.1.2-alpha.2, 0.1.1-rc.2，每个任务 3 次尝试，在 ecab245 处有 9 个社区技能。由 deepseek-flash 提供服务，指纹 aeb56401ca74e127821c4f9126dcb669。

每个任务的奖励、范围和 token 计数：20260912T201310+0000-upgrade-skills.json。

Oracle 自检（参考解决方案，无 API 密钥）：upstream 1.000，dsh-home 0.400。

引用你所需模式对应的章节：这两种模式是不同的对象，它们的均值不可比较。

Oracle 检查还会运行第二个分支，该分支仅有一行不同——即此 Action 的 DSH_HOME——因为它们的评判器硬编码了 /root/.dsh/profiles。该分支正是此检查旨在捕获的回归：同一任务环境在没有它时得分为 1.0，有它时得分为 0.4。

每次运行产生内容的记录存放在 reports/ 中，采用版本化格式，固定了迁移模式、为运行提供服务的模型构建、每次尝试、token 以及成本背后的价格表——规则见 reports/README.md，而 docs/design/continuous-quality-tracking.md 围绕它们设计了一个趋势与回归框架。上表由 npm run sync:readme 从这些记录生成；当它过期时 npm run gates 会失败。

参见 docs/upstream-benchmark.md，了解每次运行所应用的准备工作、该套件不要求的内容（隔离仅仅是“一次性容器”），以及该练习在我们自己的代码中暴露出的缺陷。

本地 CLI
sh
npm install
npm test
node dist/src/cli.js run --workdir /path/to/plugin --mechanical-only --dsh-version 0.1.1-rc.2

--skip-github 运行 agent 而不打开 Issue 或 PR。--mechanical-only 跳过 agent 和 GitHub。宿主 agent 运行需要在 PATH 上有真实的 dsh 二进制文件（如果它不叫 dsh，则用 DSH_BIN）。shell 别名对 spawn 不可见。

将 API 密钥放入被 gitignore 的 .secrets.local.json（参见 .secrets.local.json.example），或设置 DEEPSEEK_API_KEY_DSH_MIGRATE_BOT（本地也接受 DEEPSEEK_API_KEY）。实时 e2e：DSH_MIGRATE_LIVE=1 npm run test:e2e。
sh
docker build -t dsh-migrate-bot .
docker run --rm \
-e DEEPSEEK_API_KEY_DSH_MIGRATE_BOT \
-v "$PWD/fixtures/plugins/typecheck-ok:/github/workspace" \
dsh-migrate-bot run --workdir /github/workspace --mechanical-only --dsh-version 0.1.1-rc.2

使用 -e DEEPSEEK_API_KEY_DSH_MIGRATE_BOT 或 KEY=value 环境变量文件传递密钥，而不是将 .secrets.local.json 作为 Docker 的 --env-file。

该镜像在构建过程中会全局安装 dsh CLI。在访问公共 npm 仓库较慢的网络路径上，这一层可能需要数十分钟；请改为针对镜像源构建（CI 运行器不需要这样做）：
sh
docker build --build-arg NPM_REGISTRY=https://registry.npmmirror.com -t dsh-migrate-bot .

贡献

AGENTS.md 载有长期有效的规则：要运行的命令、文档关卡以及提交约定。docs/index.md 索引了每一份文档，并指明了负责每个主题的章节。推送前请运行 npm run gates。

发布

版本号位于 .cz.toml。Commitizen（cz bump）会更新 VERSION、package.json、package-lock.json 和 CHANGELOG.md。
sh
pipx install commitizen
npm run commit
npm run bump
git push origin HEAD
git push origin "v$(cat VERSION)"

该标签需要单独推送：cz 创建的是轻量标签，而 git push --follow-tags 只会推送附注标签。推送 vX.Y.Z 标签会运行 .github/workflows/release.yml：它会创建一个 GitHub Release，并强制更新浮动主版本标签（v0.1.1 → v0，v1.0.0 → v1）。像 v1.0.0-rc.1 这样的预发布标签会被忽略。要重新指定主版本标签（回滚），请手动运行 release 工作流。

使用者会固定到 @v0 或 @v1。Marketplace 上架仍只是 GitHub Release 上的一个复选框。