ThunderForge 项目交接文档
August 25, 2026 · View on GitHub
给接手维护/贡献者的交接手册。15 分钟内读懂项目全貌。当前最后提交：见
git log -1。
一、项目速览
| 项 | 值 |
|---|---|
| 仓库 | github.com/oneinitAI/dsh-thunderforge |
| npm | npmjs.com/package/dsh-thunderforge |
| 独立子项目 | oneinitAI/dsh-buddy（画像自适应技能，MIT 同作者） |
| 协议 | MIT |
| 形态 | DSH 单一 Bundle（dsh plugin add dsh-thunderforge） |
| Node 要求 | ≥ 22.19 |
| 测试 | node --test 全量 ≥31 项（零框架依赖） |
| 依赖 | 零运行时依赖（optional peerDeps 仅为元数据） |
二、产品定位
ThunderForge 是 DeepSeek Harness（DSH）的一站式插件开发套件——用户 dsh plugin add 一次装好 5 个插件 + 4 层知识库。
五个插件引擎：
| 引擎 | 路径 | 一句话 |
|---|---|---|
| thunderforge-capture | src/capture/ | LLM 载荷透明捕获（清洁室自研，替代无许可上游组件） |
| thunderforge-skills | src/skills/ + skills/ | 四层知识库注册（入口/架构标准/坑点手册/画像自适应） |
| thunderforge-scaffold | src/scaffold/ | 对话式脚手架（三类零依赖模板，生成即冒烟） |
| thunderforge-debugger | src/debugger/ | 双数据源轨迹瀑布（会话日志 × capture 索引对齐） |
| thunderforge-profile | src/profile/ | profile 管理 + 一键 dev preset |
三、关键架构约束（接手第一天的必读）
3.1 零 harness 导入铁律
绝对禁止 import ... from '@deepseek-ai/...'（受控文件 src/capture/ src/scaffold/ src/debugger/ src/profile/ src/skills/index.js src/debugger/align.js src/scaffold/templates.js——有契约测试兜底）。
踩过的血泪：曾把 dsh-tools 声明为普通依赖 → pnpm 在 profile 里装了第二份副本 → Symbol() 内容寻址的 TOOL_RUNTIME_SCHEDULER 在两份副本中不相等 → ctx.tools[scheduler] 返回 undefined → 多工具并发 turn 以 Cannot read properties of undefined (reading 'prepare') 崩溃（web 实测复现，CHANGELOG 0.1.5 录入完整因果）。
3.2 原始 JSON Schema 工具注册
不能用 defineTool（那是 dsh-tools 的导出）。必须用 原始 JSON Schema 注册且满足真实 ctx.tools.register 检验：
output声明是硬性要求（缺了直接 TypeError）output.schema.type不能是'json'（defineTool 专用糖，raw 不认）- 显式 object 节点必须声明
additionalProperties: boolean - 属性内不要有 DSL 风格
required: true（未知关键字会被拒） - 必填字段放顶层
required: [...]数组
3.3 capture 层序
llm-deepseek 适配器在 @deepseek-ai/dsh-base 层内部。thunderforge 必须排在 dsh.profile.bundles 最前——响应式注入让 capture 恰好在 llm 服务出现后、适配器行之前挂上补丁。排在 base 之后 = 适配器已注册 = 包装落空 = capture 静默失效（llm 服务无公开枚举手段）。
3.4 清洁室与 vendor 规则
src/capture/清洁室自研，仅依据官方 LLM 适配器协议编写- vendor 文件（
src/debugger/session-log.js←dsh-replay,skills/arch-standard/←dsh-plugin-dev-skills,skills/pitfalls/←dsh-plugin-guide,skills/dsh-buddy/←oneinitAI/dsh-buddy）仅文件头前置来源声明，未修改实现 - 红线：不引入/不参照无许可证代码
- 所有上游协议原文进入
LICENSES/台账
四、日常开发流程
# 1. 改代码——遵守 §3 约束
# 2. 跑测试
node --test # 全量
node --test test/<模块>.test.mjs # 单模块
# 3. 真机把关（mock 测不出的错真机一票否决）
dsh --profile <某profile> --dump-config # 层加载无报错
# 4. 提交
git add -A && git commit -m "type(scope): 描述"
# 5. 推送
git push # 网络正常
node scripts/github-push.mjs --trust-remote # github.com:443 被掐时
五、发布流程
node scripts/release.mjs patch # 一键：测试→bump→npm→推送→验证
node scripts/release.mjs patch --dry-run # 只看计划
注意：
- npm 有 2FA（OTP 验证），脚本检测登录态，发布失败时提示剩余手动步骤
- npm 未登录时脚本不阻塞，完成 bump/commit/push 后明确列出缺失命令
- 发布完需要维护者手动 npm publish；然后更新 CHANGELOG 记档
- Windows 下脚本内部走
npm.cmd经 shell 解析
六、文档索引
| 文档 | 面向 |
|---|---|
README.md / README.en.md | 用户（双语文案含梗） |
docs/DEVELOPMENT.md | 贡献者（架构/契约/技能写作规范） |
docs/ROADMAP.md | 路线图（改进与拓展候选：P0 真机坑 / P1 闭环缺口 / P2 拓展） |
docs/PRD.md | 产品（分阶段计划与验收） |
docs/RELEASE.md | 发布清单与验证 |
docs/NETWORK-NOTES.md | 网络排障手册 |
docs/HANDOFF.md（本文件） | 交接 |
CHANGELOG.md | 版本历史（含每次真 bug 的因果记录） |
七、子项目与上游关系
| 项 | 仓库 | 关系 |
|---|---|---|
| dsh-buddy | oneinitAI/dsh-buddy | 同一作者，独立 bundle，MIT；ThunderForge vendor 其 skills/dsh-buddy/ |
| dsh-plugin-dev-skills | zimodzh/dsh-plugin-dev-skills | MIT，原样 vendor→skills/arch-standard/ |
| dsh-plugin-guide | PerryLink/dsh-plugin-guide | Apache-2.0，原样 vendor→skills/pitfalls/（含 NOTICE） |
| dsh-replay | zoahdev/dsh-replay | MIT，引擎文件 vendor→src/debugger/session-log.js |
| dshp | asdf17128/dshp | MIT，实现已吸收并入→src/profile/store.js 等 |
八、工具服务状态
| 工具 | 用途 | 可用 |
|---|---|---|
node scripts/release.mjs | 一键发布 | ✅（Windows npm.cmd 问题已修） |
node scripts/github-push.mjs | 抗网络推送 | ✅（443 降级 + reflog 血统校验） |
node scripts/smoke-capture.mjs | capture e2e 冒烟 | ✅ |
九、环境依赖
- dsh CLI：全局
npm i -g @deepseek-ai/dsh@0.1.1-rc.2 - gh CLI（推送网络）：
gh auth token - npm 登录态（发布）：
npm whoami - 本项目：零其他依赖——
node --test即可，不需npm i
十、遗留任务（按优先级）
2026-08-24 复盘：#1–#5 全部推进完毕，仅剩外部等待项。
| # | 任务 | 状态 |
|---|---|---|
| 1 | web 多工具对话复测 + capture 落盘 | ✅ 完成——顺带抓出并修复真 bug：capture 只包装单步 stream()，而 LlmRuntime 主路径是 prepareCall()→adapterCall.stream() 两步协议，捕获静默落空（v0.1.7 修复）；修复后真机 40 次调用全部落盘（ok:true） |
| 2 | npm publish | ✅ 完成——`dsh-thunderforge@0.1.7$ 已发布 |
| 3 | \text{live} \text{skill} 触发评测 | ✅ 完成（\text{web} 真机抽样）——\text{train} 6/6（正例 4/4 触发·点名/隐式/英文/事件系统；负例 2/2 干净忽略），\text{validation} 4/4（正例 2/2 触发；近邻负例未加载技能但出现一次 \text{ask_user_question} 澄清——边界摇摆非误触发，观察已记入 \text{evals} \text{methodology}）。注意：\text{skill} 触发要求 \text{agent} \text{preset} 含 \text{Skills}（\text{minimal} 极简模式裁剪了 \text{skill} 工具，评测须在标准模式会话跑） |
| 4 | 全链路 \text{e2e} | ✅ 完成——\text{debugger} 双源瀑布对齐真机数据验证：\text{session} 事件 \times \text{capture} 载荷按毫秒交错（\text{tool}/\text{call} 后 4\text{ms} 出现对应 \text{llm}/\text{call} 记录），\text{summary} 统计正确 |
| 5 | \text{dsh}-\text{buddy} 独立仓库同步 + \text{npm} 发布 | ✅ 完成——同步+\text{push}（\text{oneinitAI}/\text{dsh}-\text{buddy} $3123f00，skills 与 vendor 一致、version 0.3.0 对齐）；npm 首发成功 dsh-buddy@0.3.0`（latest） |
| 6 | awesome-deepseek-harness PR #456 等待合并 | ✅ 完成——维护者 0xsline 于 2026-08-23 合并，ThunderForge 已收录进 awesome 列表 README |
遗留任务清零。
十一、外部提交记录
- awesome-deepseek-harness: PR #456——已合并（2026-08-23，ThunderForge 收录进列表）
- npm:
dsh-thunderforge@0.1.7（latest）；dsh-buddy@0.3.0（latest，2026-08-24 首发） - dsh-buddy 独立仓库：
oneinitAI/dsh-buddy@3123f00（canonical rewrite 同步）
十二、项目统计
| 指标 | 值 |
|---|---|
| 源文件（受控） | 11（src/ 下 JS） |
| 测试文件 | 7（含契约测试） |
| skill 目录 | 4 |
node --test 项数 | ≥31 |
| vendor 上游 | 5（一个 Apache-2.0，四个 MIT） |
| CI 矩阵 | Node 22/24 × Linux/Windows |
| 踩过的真 bug 并记入 CHANGELOG | 4（Symbol 双实例、raw 注册契约、层序盲区、patch YAML 顶层数组） |