dsh_plugin_swift_cycle

一句话定位

这是 Swift Cycle v1.2.0 治理 Skill 的 DeepSeek Harness 适配器，把上游锁定版本以 SHA-256 校验后注册为 /swift-cycle 命令；模型不会自动挑选它，适合想给 DSH 接入一套轻量级项目治理流程的用户。

核心能力

• 提供 /swift-cycle 用户显式命令，把锁定版本 v1.2.0 的 Swift Cycle 治理流程加载到 DSH
• 在加载时离线校验 vendor 快照与 upstream.lock.json 中每个文件 SHA-256，载荷指纹不匹配则拒绝注册
• 治理覆盖 Knowledge Promotion（本地知识晋升）、State Separation（拆分独立生命周期）、Governance Baseline（建立可比较基线）、Commit Boundary（多提交边界规划）、Source/Runtime Boundary（源码/制品/运行态分层验证）五类场景
• 引导 Agent 按"快速扫描 → 最小变更 → 立即验证 → 继续或回退"短循环推进，避免重型流程
• 强制 Swift Cycle 走用户显式入口，模型不会自动选用，也不会修改用户已有的同名 Skill

技术实现

• 语言: JavaScript（ESM 模式，Node 内置模块）
• 关键依赖: 无运行时依赖（仅依赖 node:crypto / node:fs/promises / node:path / node:url）
• 架构模式: 单一 ESM 入口通过 export const inject = ['skills'] 把自身挂到 DSH Cordis 容器，apply(ctx) 阶段调用 ctx.skills.register() 注册只读快照 Skill；Cordis patch 负责把插件节点插入宿主
• 入口文件: index.js（apply → registerPackagedSkill → loadPackagedSkill → verifyPackagedSnapshot → extractBody），上游快照位于 vendor/swift-cycle/，载荷指纹位于 upstream.lock.json

适用场景

当用户在 DSH 里需要给小型或个人项目接一套轻量治理流程、又希望 Skill 内容来自受信任的固定上游时使用本插件。它把 Swift Cycle 的工作流（基线、提交边界、源/运行态分层、知识晋升）以 /swift-cycle 显式命令的方式暴露出来，适合做项目初始化、跨边界重构、候选方案评审或项目收尾时的统一入口；不适合需要模型自动调用 Skill 的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Solismuchengxue/dsh_plugin_swift_cycle

配置项

本插件无需额外配置。安装后由 DSH 启动时自动调用 apply(ctx) 完成 swift-cycle Skill 注册，无任何用户可调参数；如需切换上游版本，请重新安装并通过 upstream.lock.json 重新校验。

常见问题

Q: 这个插件和官方 Swift Cycle 是什么关系？

A: 官方 Swift Cycle 仓库（Solismuchengxue/skill_swift_cycle）才是权威内容来源；本插件只是把固定的 v1.2.0 快照通过适配器注册到 DSH，离线校验 SHA-256 后透出，自身不修改上游。

Q: 模型会自动选择这个 Skill 吗？

A: 不会。注册时显式设置 modelInvocable=false、userInvocable=true，必须由用户在对话里输入 /swift-cycle 才会被触发。

Q: 安装后还需要配置什么吗？

A: 不需要。本插件没有运行时配置项，安装完成后 DSH skills 服务会自动注册 swift-cycle Skill。

Q: 怎么卸载？

A: 从项目的 cordis.patch.yml 中移除 swift-cycle 对应那一行，重启 DSH 即可。本插件运行时不会写用户级 Skill 目录，也不会删除已有的同名 Skill。

Q: 这个插件有运行时依赖吗？

A: 没有。package.json 的 dependencies 字段为空，只使用 Node 内置模块（node:crypto、node:fs/promises、node:path、node:url），也不存在 install/preinstall/postinstall/prepare 生命周期脚本。

Q: 能在哪些平台运行？

A: 跨平台。代码不依赖任何原生模块（没有 node-pty、node:sqlite 之类的 native binding），engines.node 写的是 >=20，macOS、Windows、Linux 都一致工作。

Q: vendor/ 目录里的文件可以手工修改吗？

A: 不可以。vendored SKILL.md、agents/openai.yaml、references/zh-CN.md 都登记在 upstream.lock.json 中并按 SHA-256 校验，任何修改会导致注册阶段 hash mismatch 失败。

Q: 项目里已有的同名 swift-cycle Skill 会被覆盖吗？

A: 适配器遵循 DSH Skill 注册规则：项目级同名条目可以遮蔽本适配器的注册，但本适配器不会删除或改写被遮蔽的 Skill；适配器自身的注册也可能被项目级同名 Skill 遮蔽。

上手难度

入门 — 安装一行命令即可使用，无需任何额外配置或环境变量；唯一的"门槛"是要知道 Swift Cycle 的治理流程只能通过 /swift-cycle 显式触发，不会被模型自动选用。

已知问题与限制

• vendor 快照内容由 upstream.lock.json 锁定并按 SHA-256 校验，任何手工改动都会让适配器在注册阶段抛出 hash mismatch；按设计只允许通过重新锁定上游身份刷新 vendor
• adapter 的 lock 路径会拒绝 ../ 等不安全相对路径、绝对路径以及重复文件路径，确保任何被篡改的 lock 都不能让快照越界
• 经证据文档（docs/evidence/）覆盖的兼容性范围是 deepseek-hai/dsh 0.1.0-rc.5 隔离 Harness、0.1.0-rc.6 真实 Web profile，以及对应固定的 GitHub v0.1.0 commit 与 npm 0.1.1；其他 DSH 版本、其他 profile、写入流程与生产治理场景尚未单独验证
• 项目级同名 Skill（按 DSH Skill Registry 规则）可以遮蔽本适配器的注册；适配器不会删除或改写被遮蔽的 Skill
• 适配器在 Harness 启动时只调用 ctx.skills.register() 一次，不持久化运行状态；如果上游 DSH 重启，Skill 会按注册流程重新加载

这是 Swift Cycle 的 DeepSeek Harness 适配器。它把锁定的 Swift Cycle v1.2.0 载荷注册为只能由用户显式调用的 Harness Skill。

当前状态

• 适配器版本：0.1.1
• 上游版本：v1.2.0
• 上游 commit：af3c5ddafba516c304613ea69081118fc234add7
• 上游整体 SHA-256：e01de6fa081c12c7e481a219d3932e48a2e386f05202e7b8a6e51a0029fad686
• 本地源码验证：已通过
• 候选制品预检：已通过 dry-run 文件合同和临时解包后完整性验证
• 分发状态：GitHub v0.1.1 与 npm 0.1.1 已发布；v0.1.0 保留为历史版本
• Harness Runtime 兼容性：已通过固定版本的隔离验证、GitHub 固定 commit 安装验证，以及 0.1.0-rc.6 真实 Web profile 中 GitHub v0.1.0 与 npm 0.1.1 的只读显式调用烟测

以上结果证明源码、候选制品、固定版本的隔离 Harness Runtime，以及两个已记录工作区中的真实 Web consumer 调用符合已验证边界；不代表其他项目、写入流程或生产治理已经验证。

包含的 Swift Cycle 能力

• Knowledge Promotion：把长期共享事实从本地记录晋升到适当的 Git 管理资产。
• State Separation：拆分彼此独立的工程、实验、质量和发布结论。
• Governance Baseline：复杂治理开始前记录可比较的当前基线。
• Commit Boundary Planning：为多提交工作预先划分单一意图和验证边界。
• Source/Runtime Boundary：分别验证源码、制品、运行态和实际消费者。

完整治理规则以锁定的上游 SKILL.md 为准；本 README 不复制 Skill 正文。

调用策略

适配器向 Harness 注册：

name = swift-cycle
modelInvocable = false
userInvocable = true

Swift Cycle 不进入模型可隐式选择的 Skill 目录。用户需要显式输入：

/swift-cycle

安装

日常安装使用 npm latest：

dsh plugin --profile web add dsh-plugin-swift-cycle

需要固定、可重放的安装身份时指定版本：

dsh plugin --profile web add [email protected]

npm 固定版本不可变。需要直接从 GitHub 安装同一版本时，使用 v0.1.1 对应的完整 40 位 commit：

dsh plugin --profile web add "github:Solismuchengxue/dsh_plugin_swift_cycle#d44bee70c109bb1d772d26ee790d6de9aadce9cc"

npm 0.1.1 和 GitHub 固定提交均已在临时隔离 DSH_HOME 中验证。各版本的安装身份和验证边界以对应 GitHub Release 为准；不要把未固定的默认分支用于可重放安装。

安装或改动 profile 前先检查合成配置：

dsh --profile web --dump-config

GitHub v0.1.0 固定 commit 与 npm 0.1.1 均已在同一个真实 Web profile 中完成安装、加载和只读调用烟测。其他 profile 的安装仍需用户单独授权。

本地验证

需要 Node.js 20 或更高版本。本包没有运行时依赖，也不需要执行安装生命周期脚本。

npm test
npm run verify:upstream
npm run pack:dry-run

维护者可以显式提供一个 Swift Cycle checkout，做只读载荷比对：

node scripts/verify-upstream.mjs --source "<path-to-swift-cycle-skill-directory>"

适配器加载和运行时不会访问网络，不读取凭据，也不会修改用户级 Skill 目录。通过 npm 或 GitHub 安装时，分发工具仍需要联网获取用户指定的固定版本。

同名 Skill 与证据边界

根据锁定的 DeepSeek Harness Skill Registry 规则，项目级同名条目可以覆盖本适配器的 Runtime 注册；Runtime 注册可能遮蔽同层的用户级同名条目。本适配器不会删除或改写被遮蔽的 Skill。

以下结论必须分别验证：

1. Git 源码与上游锁一致；
2. npm pack 候选制品内容正确；
3. 隔离 Harness Runtime 能注册和显式调用；
4. 真实用户 profile 已安装并由实际消费者使用。

当前四层均已有对应证据；真实 consumer 证据覆盖 GitHub v0.1.0 在空的非 Git 工作区与本仓库中的只读调用，以及 npm 0.1.1 在本仓库中的一次只读调用，不代表其他项目、写入流程或生产治理已经验证。参见 2026-08-15 DSH 隔离兼容性验证、2026-08-16 真实 Web consumer 烟测、2026-08-16 非空 Git 项目治理烟测与 2026-08-20 npm v0.1.1 真实 consumer 烟测。

权威来源

• Swift Cycle 行为和版本：Solismuchengxue/skill_swift_cycle
• DeepSeek Harness 插件与 Skill 语义：deepseek-ai/deepseek-harness
• 本适配器的架构和验证边界：DESIGN.md