deepseek-harness 个人集成分支维护技能全解析：dsh-customize / dsh-upgrade / dsh-upstream-customization 与原子化启动器切换机制

deepseek-harness 个人集成分支维护技能全解析dsh-customize / dsh-upgrade / dsh-upstream-customization 与原子化启动器切换机制【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harnessdsh把个人定制从装一次、改一处升级为可复现、可串行、可回滚的工程流程仓库通过dsh-customize、dsh-upgrade、dsh-upstream-customization三个技能让个人在集成分支staging上隔离任务、合入上游变更、并向官方上游发布成果。本文以归档的流程决策笔记 2026-07-23-personal-staging-maintenance-skills.md 为骨架结合当前仓库的 skill 子系统源码与文档深入讲解这套克隆 → 验证 → 原子切换 → 回滚保留的维护模型读完你可以复现其设计并理解为什么它优于在活跃检出上原地变基等替代方案。背景个人定制维护为什么需要一套流程dsh 的定位是一切皆插件个人用户往往会针对自己的安装做大量定制改插件行为、加私有功能、调整界面。这些定制天然面临四个重复出现的问题定位已安装的源码运行中的 dsh 到底从哪个检出checkout加载不能靠猜隔离任务变更多项任务如果混在同一个工作区互相污染、难以发布串行集成多路定制并发修改同一集成分支会让准备中的升级历史失效合入上游变更定制积压后需要在不破坏正在运行的会话所依赖的检出的前提下安全地把上游更新合进来。笔记明确指出用户本地指令只能解决单套安装的问题——它无法指导其他用户也无法与仓库分发的安装脚本行为保持同步。一旦安装脚本的行为变了本地指令就会悄悄漂移失效。因此决策是把这套维护流程以技能的形式随仓库分发。说明该笔记状态为implemented于 2026-08-10 归档。按 .agents/notes/README.md 的归档策略归档内容永久冻结、不作为当前行为的权威依据。从当前检出与仓库历史如cleanup: remove TUI package and legacy dsh entrypoints、cleanup: remove managed source installer等提交看根级skills/目录与 TUI 已不在当前仓库中下文按笔记原始记录还原其设计与原理。决策概览三个技能的分工与分发仓库从根skills/目录分发三个技能职责严格分离技能职责dsh-customize在个人安装上定位源码、用任务 worktree 隔离变更、串行集成定制dsh-upgrade定位当前生效检出与集成分支把上游变更合入同时不破坏运行中的会话dsh-upstream-customization独立于本地维护把经筛选的定制推荐、发布给上游几个贯穿始终的设计原则描述即入口每个技能的 description 同时说明操作内容和会选中它的用户请求让模型与用户都能按意图命中正确的技能以安装的启动器为准工作流根据已安装的启动器launcher推导当前生效的检出和集成分支而不是依赖个人路径或分支名——路径和分支名会变启动器是唯一稳定锚点遵从仓库内指令流程优先遵循仓库自身分发的本地指令避免与安装脚本行为脱节强制任务 worktree每一项任务的变更都在独立 worktree 中进行串行化集成分支修改利用集成分支所在 worktree 既有的.agents/merge.lock让每一次个人集成分支修改排队执行避免写写冲突。技能发现优先级仓库级技能放在哪一层笔记提到分发的 TUI 在启动时把根skills/目录交给本地技能提供方skill provider并且该目录在发现优先级上位于项目根与用户根之后。当前仓库的 skill 子系统文档 docs/subsystems/skills.md 保留了完整的本地发现优先级表可与之互相印证优先级来源路径100project-dshprojectRoot/.dsh/skills200project-agentsprojectRoot/.agents/skills300customConfig.customSkillDirs400user-dshdshHome/skills500user-agentsagentsHome/skills600bundledConfig.bundledSkillDirwhen configured其中bundledrank 600排在 project 与 user 各层之后与笔记中低于项目根和用户根的发现优先级一致。这意味着用户在工作区放置同名技能时可以覆盖仓库级默认而仓库级技能只作为兜底分发——既保证开箱即有安全规则又不剥夺用户覆盖的自由。技能注册表在 packages/skill/skill 中实现多个 provider 的目录会被合并按 rank、provider 顺序再按本地顺序消解同名冲突。dsh-upgrade 升级流程克隆、验证、原子切换升级是整个维护模型里最复杂、也最体现工程取舍的部分可拆成四个阶段。阶段一变基前的 Git 检查在真正执行变基之前升级流程先检查Git 日志与提交范围目标是识别四类信息将进入升级的上游变更incoming upstream changes个人提交personal commits即本地定制的来源重复内容上游已经通过官方渠道合入的定制可能冲突的区域提前定位冲突面。基于检查结果流程会做一次去重裁剪丢弃上游已经提供的定制如果某个定制在本地只剩文档差异说明文档与上游不同但代码已被上游吸收也一并丢弃该说明——除非该说明包含上游缺失、且可独立使用的当前约定current contract。这个例外保证上游代码虽已同步但本地积累的有价值的使用约定不会因去重而丢失。阶段二单一时间戳贯穿整次尝试每次升级尝试都使用同一个 UTC 基本格式时间戳timestamp来命名这次尝试的全部产物形成一一对应的命名族产物命名独立同级克隆dsh-staging-timestamp本地准备分支dsh-upgrade/prepare-timestamp新的集成分支dsh-staging/timestamp私有上游引用与恢复引用含timestamp的私有 refs启动器备份本次尝试专用的备份两个值得注意的约束同级克隆的名称不派生自当前目录名。目录名可能含非法字符、过长或撞名而时间戳唯一且稳定名称冲突直接失败而不是追加临时后缀。dsh-staging-timestamp若已存在说明上一次尝试残留或并发尝试存在此时让流程失败比悄悄换个名字继续安全得多——后缀只会掩盖问题、制造难以追踪的孤儿产物。阶段三推导进程源码位置仓库视为不可变升级流程推导当前 DSH 进程的源码位置时依据的是进程命令行与运行时环境process command 和 runtime environment而不是 shell 工作目录——shell 的 cwd 随时可变而进程实际加载的安装位置才是事实。推导出安装位置后把已安装启动器所指向的仓库和检出视为不可变唯一例外是持有其既有的合并锁即前面提到的.agents/merge.lock。也就是说升级绝不向运行中的检出写入任何内容只借用它的锁来保证串行。阶段四验证 → 建分支 → 原子切换启动器升级路径不是在旧检出上原地变基而是换一个全新的检出让启动器指过去在独立克隆中完成依赖安装、检查与验证创建并验证带时间戳的集成分支dsh-staging/timestamp原子地atomic把启动器从保持不变的旧集成分支检出一次性切换到新的集成分支检出切换后要求重启一次dsh。这条路径的关键不变量是启动器绝不会指向准备、功能、评审、发布或分离状态的检出——它只会指向已验证的集成分支检出。切换的失败处理分两侧切换前失败已安装的检出与启动器保持原样没有任何残留影响切换后失败恢复启动器备份并验证备份确实可用restore verify而非假设恢复成功。旧集成分支检出、其分支、恢复引用和启动器备份会一直保留充当回滚存储直到满足两个条件才允许清理重启后的进程证明 DSH 确实运行在新的集成分支上且用户明确批准回滚清理。也就是说回滚窗口由运行证据 用户确认双重把关而不是拍脑袋定时删除。dsh-upstream-customization向上游发布的独立流程本地维护与上游发布被刻意拆成两条独立流程。dsh-upstream-customization负责后者它有清晰的推荐边界推荐上游化的变更类型bug 修复、附加式且不与现有功能冲突的插件功能、视觉改进需要先取得维护者批准的变更类型侵入式变更。发布的决策权始终保留在用户手里流程设计成多级确认升级结束时agent 对剩余定制分类、说明每项的上游价值、给出是否推荐的建议agent 询问用户希望上游化哪个具名候选named candidate只有用户做出选择后才加载发布工作流每项功能在推送或创建草稿 PR 之前仍必须得到明确批准——即推荐不等于自动推送。发布本身的质量门槛也很明确获批的变更以当前上游master为起点不带入任何无关的个人提交——保证 PR 的 diff 干净、可评审TUI 功能的草稿 PR建议附带截图且截图取自组装后的应用并在截取前移除凭证与个人数据避免泄露敏感信息。dsh-customize定制集成的落地约束dsh-customize负责个人定制侧的落地核心约束是在集成前必须于专用 tmux 会话中检验交互式 TUI 行为。原因很直接TUI 是交互程序脱离真实终端环境伪终端、尺寸、按键流无法可靠验证tmux 会话提供了稳定的交互终端让 agent 能真实驱动并观察界面反馈。这与此前仓库的浏览器/终端演示类技能如 record-browser-gif的真实环境取证思路一脉相承。备选方案与取舍笔记记录了几个被否定的替代方案理解它们能更清楚为什么最终方案重但正确备选方案被否定的原因工作流仅限用户本地其他用户无法发现同一套安全规则工作流会与仓库分发的安装脚本行为漂移在当前集成分支检出上原地变基准备期间会修改大量文件可能干扰新的 dsh 启动无法提供原子发布或一份保持不变的、可回滚的检出先把启动器迁往别处再更新现有检出升级中途启动器会指向非集成分支的目标仍会改写可能承载运行中进程的检出只在最终切换分支时加锁持锁时间更短但变基准备期间其他写入方仍可基于旧基线合并定制导致已准备好的历史失效用一个上游 PR 发布所有个人变更减少分支管理却会把无关定制一起发布并取消按功能逐项批准的用户边界最终方案的本质权衡是用一次克隆 一次原子切换 一次重启换取运行中检出绝对不可变、切换可回滚、上游发布可逐项授权。影响与保障机制升级准备流程在安装依赖和运行检查期间持有已安装集成分支的合并锁因此本地定制的集成必须等待一个一致的结果——这是串行化的直接代价也是正确性前提。整体保障体系可以归纳为单次升级的资源预算一个独立的时间戳克隆、一个集成分支、一次原子启动器切换、一次重启除此之外升级绝不写入启动器背后的仓库或检出仅持有既有锁防御性执行纪律记录前置条件 → 在每次修改前重复检查前置条件 → 修改被中断后检查状态→ 切换失败时恢复并验证启动器备份 → 修正后重跑失败项→ 报告最终状态回滚存储旧集成分支检出持续保留直到新分支运行证据 用户批准双重条件满足仓库内评估覆盖skill 选择、进程源码保护、不安全的仓库状态、回滚、发布授权均有 check-in 的评估用例文档门禁仓库文档检查验证技能链接与格式归档笔记则按 .agents/notes/README.md 的冻结策略被文档门禁跳过分工边界Git 与文件系统操作的正确性仍由技术评审负责而非由自动化全权兜底。小结这套模型的通用启示把这份决策笔记抽象出来它回答的是任何带运行中的进程 可升级的安装类工具都会遇到的问题如何安全地把新版本换进去而不是改进去。dsh 的答案——进程来源以启动器为准、变更发生在独立克隆、切换用单时间戳命名族保证可追踪、回滚由运行证据与用户批准双重把关、上游发布走逐项授权——是一套可以迁移到其他项目安装/升级/定制/上流四段式维护场景的成熟模板。若需进一步了解技能注册表与 provider 机制的实现可继续阅读 packages/skill/skill/README.md 与 docs/subsystems/skills.md。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考