Maglev for DSH
> Maglev 面向 DeepSeek Harness（dsh）的独立插件制品：让软件研发团队和个人，在 dsh 里做长期可控的项目迭代，迭代中天然沉淀知识资产，从而降低项目对特定的人和 AI 体系的依赖。
它是什么
一个自包含的 dsh 插件。装上它，dsh 就拥有：
1. 29 个 Maglev 技能：收敛 → 设计 → 验证 → 结晶主链路 + 治理纪律 + 知识沉淀。技能随插件自动注入（maglev-bundled provider），任意项目（无需本地 .agents/skills）都能发现并使用 2. Maglev GUI： - 结晶卡片：每次迭代沉淀了什么，以卡片形式弹在会话流里 - 真相卡片：AI 读到的项目现状（能力域/主题/契约状态），对人可见 3. spec 工具与验证门禁：spec 完整性检查 + 结晶前机械门禁，把"验证"从模型自觉变成机械约束
flowchart LR
U["dsh 用户"] -->|"pnpm dsh plugin add"| M["Maglev for DSH"]
M --> S["29 技能<br/>自动发现"]
M --> G["Maglev GUI<br/>真相卡片 + 结晶卡片"]
M --> T["spec 工具<br/>验证门禁"]
S --> W["可控迭代 + 知识沉淀 + 降依赖"]
G --> W
T --> W它解决什么问题
dsh 提供了强大的执行能力（agent 循环、工具、沙箱、多代理编排），但缺少软件研发的流程语义——需求 → 设计 → 验证的阶段门、验收证据、不可变 Spec、流程纪律都不存在。Maglev for DSH 补上这一层：
- 可控迭代：结晶必须过 spec 完整性门禁，不通过就不能沉淀（机械强制，不靠 AI 自觉）
- 知识沉淀：每次迭代结晶写回
specs/知识分层，并产生会话事件（结晶卡片） - 随时接手：真相卡片让新接手的人快速看懂"项目是什么、做到哪了"
安装
> 前提：dsh 是 developer preview，没有全局 dsh 命令。所有 dsh 操作都在 dsh 源码 checkout 目录下用 pnpm dsh <子命令> 执行。
# 在 dsh checkout 目录下，把插件装进 web profile（profile 不存在会自动创建）
pnpm dsh plugin --profile web add @idea-maglev/maglev-for-dsh
# 启动 web（用默认 web profile，加载 maglev）
pnpm dsh web启动后打开页面（默认 http://127.0.0.1:3080），即出现 Maglev 卡片（真相卡片 + 结晶卡片）。
> 本地开发（从源码安装，改动即生效）：pnpm dsh plugin --profile <name> add ./maglev-for-dsh（link 本地 checkout）。
使用
在会话里让 AI 调用工具即可：
maglev_reality_status：读项目现状（能力域/进行中主题/愿景/契约），产生真相卡片maglev_crystallize：把已验证结论结晶到specs/，产生结晶卡片（先过门禁）maglev_spec_check：spec 完整性机械检查
完整流程（安装 → 初始化/接入 → 日常迭代 → 对仓库的影响 → 场景举例）见 [使用手册](docs/usage.md)。
它与 Maglev、dsh 的关系
- Maglev（源仓库）：方法论与技能的原型，仅作参考，非运行时依赖（本插件零依赖，见下）
- dsh：执行层宿主（agent harness），插件运行其上
- 本仓库：从 Maglev 一次性派生的自包含插件制品，与 Maglev 源零运行时依赖，技能资产独立演进
> 技术注记：本插件 host 侧不直接依赖 @deepseek-ai/dsh-tools（工具定义手动构造），避免 dsh-tools 多实例导致的工具调度器符号分裂（详见 docs/thinking/2026-08-15-dsh-tools-instance-split.md）。技能通过 ctx.skills.registerProvider 注入（dsh 的 bundled skill 机制，rank 600 低于项目技能，项目优先），因此任意环境安装即用。
自证原则（dogfooding）
本仓库本身就是通过 Maglev 机制构建和治理的：它的演进走 Maglev 主链路，知识沉淀在 specs/ 三层（00_vision / 10_reality / 20_evolution / 90_archive），决策记录在 docs/thinking/。
> Maglev 用自己构建自己，用自己治理自己。 只有本仓库自己跑通了"迭代 → 结晶 → 知识沉淀"闭环，才有资格论证插件真实有效。
仓库结构
| 路径 | 用途 |
|---|---|
index.ts | dsh host 插件入口（3 个 spec 工具 + 结晶门禁 + 会话事件） |
src/client/ | dsh client 插件（真相卡片 + 结晶卡片） |
.agents/skills/ | 29 个固化技能（产品资产）+ _internal 协议主体 |
specs/ | 本仓库自己的知识分层（dogfooding 自证） |
docs/thinking/ | 设计决策 |
scripts/ | maglev-python 运行时、verify_skills 验证工具 |
assets/ | dsh workflow 预设 |
验证
固化技能与 dsh 的兼容性、host/client 插件端到端链路均已实证（见 docs/validation.md 与 specs/10_reality/README.md）：
python3 scripts/verify_skills.py # 校验 29 技能符合 dsh 发现协议
python3 scripts/spec_integrity_check.py # spec 完整性检查许可证
MIT（见 [LICENSE](LICENSE)）。