dsh-j-space-warm

J-Space First V3 Warm 预设插件 —— 为 DeepSeek Harness（dsh）Web GUI 打包的即装即用 Agent 预设。

一句话：只要有安装包（tgz），就能安装本插件，然后在新会话预设选择器中直接选用「J-Space First V3 Warm (experimental)」，行为与本机原预设完全一致。

本插件把完整预设（组合编排 + 本地插件 + J-Space 技能树）打包为 dsh 标准 bundle 插件：安装后在宿主启动时自动把预设同步到 ~/.dsh/.agent-presets/j-space-exp-v3，升级插件即自动更新预设，卸载插件不影响已安装的预设文件。以 GitHub Release 为发布与备份标准。

---

目录

• 背景与定位
• 核心特性
• 工作原理
• 目录结构
• 安装
• 使用
• 验证安装成功
• 升级与卸载
• 故障排查
• 从源码构建
• 开发与测试
• 许可与致谢

---

背景与定位

本预设是 anchored-standard（MIT）的 V3 Warm 实验变体，叠加了 J-Space Cognition Suite V3.6（Apache-2.0）的认知控制技能：

• 锚定两阶段：首个模型请求只暴露 Minimal 精确双工具（pwsh + str_replace_editor），只保留一行 persona、清空运行时上下文，锚定 Minimal 推理轨迹；
• 热身轮（Warm）：真实任务之前插入一轮 0 任务热身，模型调用一次 pwsh 即触发工具晋升——真实任务一开始就是全工具就绪，且 J-Space 协议在热身轮被完整阅读；
• J-Space 协议注入强化：everyUserMessage——每个携带真实用户消息的请求都会重新注入协议，长任务中协议不再衰减。

预设文件原存放于 ~/.dsh/.agent-presets/j-space-exp-v3，本插件将其连同全部相关文件（13 个本地插件/模块 + 15 个 J-Space 技能文件）打包，实现：

1. 可分发：单一 tgz 安装包，任意 dsh 环境可装；
2. 可复现：安装后预设与本机原预设逐字节一致（含校验测试）；
3. 可维护：升级插件即同步升级预设，无需手工拷贝；
4. 可追溯：GitHub 仓库 + Release 附件作为版本化备份标准。

---

核心特性

特性	说明
即装即用	dsh plugin --profile web add <tgz> 一条命令安装，重启后预设出现在选择器
自动同步	宿主启动时把 presets/j-space-exp-v3/ 同步进 ~/.dsh/.agent-presets/，字节级幂等（无变化不重写）
升级联动	插件升级 → 预设自动更新；旧文件清理（prune extras）
卸载安全	卸载插件不删除已同步的预设，其他用户自建预设绝不触碰
结构校验	同步后对 agent.cordis.yml 做结构校验，坏文件以失败条目报告而非静默
可迁移	技能树经 baseUrl 相对解析，预设装到任何目录都可用
双语文档	中文 README + 英文 README + 架构/安装/变更文档

---

工作原理

┌───────────────────────────── dsh 宿主进程 ─────────────────────────────┐
│  cordis.patch.yml（bundle 层）                                          │
│    └─ insert: - id: j-space-warm → name: 'dsh-j-space-warm'            │
│  lib/index.js（host 插件）                                              │
│    ├─ apply(ctx)                                                        │
│    │   ├─ syncPresetTrees(presets/ → ~/.dsh/.agent-presets)            │
│    │   │   ├─ 逐目录拷贝（幂等，字节比较）                               │
│    │   │   ├─ 删除源中不存在的旧文件（prune extras）                     │
│    │   │   └─ 结构校验 agent.cordis.yml                                 │
│    │   └─ systemPrompt.section（向模型宣告插件存在）                     │
└──────────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ~/.dsh/.agent-presets/j-space-exp-v3/
              （dsh agent-presets 发现根目录）
                              │
                              ▼
        新会话预设选择器 → 「J-Space First V3 Warm (experimental)」

预设本身是 agent-plane 组合：agent.cordis.yml 里 24 个行（row）按职责分组——bootstrap（工具晋升/上下文过滤）、shell（pwsh 引导面，bash 全程禁用）、filesystem（str_replace_editor 引导编辑器）、skills（技能发现 + J-Space 技能目录）、jspace-first（协议注入）、warmup-round（热身轮）、resident-extras（晋升后常驻工具面）、planning/compaction/delegation（各服务行）。详见 docs/ARCHITECTURE.md。

---

目录结构

dsh-j-space-warm/
├── package.json              # 包元数据；dsh.bundle.patch → cordis.patch.yml
├── cordis.patch.yml          # bundle 补丁：向 profile 名册插入插件行
├── lib/
│   └── index.js              # host 插件：预设同步 + 系统提示宣告（纯 ESM，免编译）
├── presets/
│   └── j-space-exp-v3/       # ★ 预设全树（与源预设逐字节一致）
│       ├── preset.yml        #   预设元数据（显示名）
│       ├── agent.cordis.yml  #   组合编排（24 行）
│       ├── *.mjs             #   本地插件/模块（13 个，见 ARCHITECTURE.md）
│       └── skills/j-space/   #   J-Space 技能树（SKILL.md + 9 modules + 3 references + 3 scripts）
├── scripts/
│   ├── build.sh              # 校验 + 测试 + npm pack
│   └── verify-install.mjs    # 独立端到端验证（默认写临时目录，--real 写真实根）
├── test/
│   └── sync.test.mjs         # node --test 单元测试（同步/校验/幂等/退役）
├── docs/
│   ├── ARCHITECTURE.md       # 预设架构详解（每个 .mjs 的职责与挂载关系）
│   ├── INSTALL.md            # 安装/使用/升级/卸载分步指南
│   └── CHANGELOG.md          # 版本变更记录
├── README.md                 # 本文件（中文）
├── README.en.md              # 英文简介
├── LICENSE                   # Apache-2.0
├── NOTICE                    # 上游归属（anchored-standard MIT / J-Space 套件 Apache-2.0）
└── .github/workflows/release.yml  # 打 tag 自动构建 tgz 并发布 Release

---

安装

前置条件：已安装 dsh（DeepSeek Harness）与 pnpm；目标 profile 名默认为 web。

方式 A：本地安装包（推荐，离线可用）

# 1. 获取安装包：从 GitHub Releases 下载 dsh-j-space-warm-<版本>.tgz
#    或从源码目录构建（见「从源码构建」）

# 2. 安装（把 <路径> 换成 tgz 的绝对路径）
dsh plugin --profile web add C:\path\to\dsh-j-space-warm-0.1.0.tgz

# 3. 重启 dsh（宿主启动时插件执行预设同步）
#    Windows: 重启 dsh web 服务进程即可

方式 B：Git 装配（开发调试）

dsh plugin --profile web add github:zbsph/dsh-j-space-warm
# 或本地目录
dsh plugin --profile web add D:\SharkCode\dsh-j-space-warm

方式 C：手动拷贝（不使用插件机制）

# 把 presets/j-space-exp-v3 整个目录拷到预设发现根
xcopy /E /I presets\j-space-exp-v3 %USERPROFILE%\.dsh\.agent-presets\j-space-exp-v3

安装后请按「验证安装成功」检查。

---

使用

1. 打开 dsh Web GUI（默认 http://127.0.0.1:3080）；
2. 新建会话，在预设选择器中选择 「J-Space First V3 Warm (experimental)」；
3. 开始对话。首轮为热身轮（0 任务，模型调用一次 pwsh 解锁工具库并回复 warm-up complete），随后真实任务自动开始，工具全量就绪，J-Space 协议全程生效。

行为细节：

• 引导面：pwsh + str_replace_editor（Minimal 精确双工具）；bash 全程禁用（V2 起的偏差，Windows 专用）；
• 晋升：首个持久晋升信号（任一工具调用或首条助手消息）后，常驻工具面扩为 pwsh/read/write/edit/vision_toolkit_activate/web_search + 三个发现工具（dev_tool_search / skill_search / skill_load）；更重工具经 dev_tool_search 按需解锁；
• J-Space：协议在热身轮注入，之后每个携带真实用户消息的请求重新注入；<skill-root> 自动解析为预设内技能目录；控制器用法（python <skill-root>/scripts/jspace.py 等）已在注入前文说明；
• 压缩（compaction）：压缩后回落到受控相位（引导双工具 + compactionTools），直到越过边界的新的持久晋升信号（epoch 感知）。

---

验证安装成功

# 1. 预设文件已同步
dir %USERPROFILE%\.dsh\.agent-presets\j-space-exp-v3\agent.cordis.yml

# 2. 与安装包内预设逐字节一致（可选，用安装包里 presets/ 对比）
# 3. GUI：新建会话 → 预设选择器出现「J-Space First V3 Warm (experimental)」
# 4. 插件日志（宿主日志中应出现）
#    dsh-j-space-warm: presets synced into ... (首次)
#    或 dsh-j-space-warm: preset ... sync failed: ...（异常时）

安装包自带验证脚本（不需要安装即可跑）：

npm run verify    # 默认写临时目录，安全
npm run verify -- --real   # 写真实 ~/.dsh/.agent-presets（谨慎）
npm test          # 单元测试（含「与参考预设逐字节一致」对比，需设环境变量）

---

升级与卸载

升级：下载新版本 tgz → 重复「方式 A」安装。宿主启动时插件会把新版预设同步覆盖旧版（字节级幂等，未变化不重写；不再随包的旧文件会被清理）。升级后需重启 dsh 生效。

卸载：

dsh plugin --profile web remove dsh-j-space-warm

卸载只移除 bundle 行与包文件，不会删除 ~/.dsh/.agent-presets/j-space-exp-v3——已同步的预设保留可用。如需连同预设一起删除，请手动删除该目录（注意：这会同时影响正在使用该预设的会话）。

---

故障排查

现象	原因与处理
安装后选择器没有新预设	未重启 dsh（同步发生在宿主启动时）；确认安装命令输出无报错；查看宿主日志中的 dsh-j-space-warm 行
日志出现 preset ... sync failed	同步或结构校验失败，按错误信息检查；预设文件损坏时先删除 ~/.dsh/.agent-presets/j-space-exp-v3 再重启让插件重新同步
安装报 pnpm not found	先安装 pnpm（npm i -g pnpm）
git 装配报 build 被 pnpm 阻止	按提示在 profile 的 pnpm-workspace.yaml 的 allowBuilds 中放行
首轮没有热身轮	热身轮是「每个新顶层会话一次」：子代理、恢复的会话不触发；预插失败会优雅降级为无热身（任务照常，只是未锚定）
非 Windows 平台	本预设引导面为 pwsh（tool-pwsh 行仅 win32 启用），非 Windows 会退化为完整工具目录，不保证锚定行为——预设为 Windows 专用

---

从源码构建

git clone https://github.com/zbsph/dsh-j-space-warm.git
cd dsh-j-space-warm
npm install          # 仅安装测试依赖（schemastery）
npm run build        # 校验 + 测试 + verify + npm pack
# 产物: dsh-j-space-warm-<版本>.tgz

或使用本机 dsh 插件生产线（若已安装 dsh-super-injector）：

dev_build_plugin D:\SharkCode\dsh-j-space-warm   # 构建 tgz
dev_inject_plugin D:\SharkCode\dsh-j-space-warm   # 免重启注入验证
dev_uninject_plugin dsh-j-space-warm              # 卸载注入

---

开发与测试

• npm test：node --test 单元测试——结构校验、首次同步、幂等跳过、变更重同步 + 清理、退役、坏预设上报、打包产物校验；
• 逐字节对比测试：JSPACE_REFERENCE_PRESET=<源预设目录> npm test（CI 中用本机原预设目录做回归基准）；
• node scripts/verify-install.mjs：模拟宿主启动时的同步全流程（默认临时目录，安全）。

修改预设内容：编辑 presets/j-space-exp-v3/ 下的文件即可（建议同时在 ~/.dsh/.agent-presets/j-space-exp-v3 改动并保持两处一致，或在插件目录改完后执行一次 npm run verify -- --real 同步到本机）。发布新版本时更新 docs/CHANGELOG.md 与 package.json 版本号，打 tag 即触发 Release 工作流。

日常维护闭环（本机改了预设后同步回 GitHub）：

npm run sync:reference    # 把本机 ~/.dsh/.agent-presets/j-space-exp-v3 拷回 presets/
JSPACE_REFERENCE_PRESET=~/.dsh/.agent-presets/j-space-exp-v3 npm test  # 字节一致性回归
# 更新 package.json 版本号 + docs/CHANGELOG.md
npm run build             # 产出新 tgz
git add -A && git commit -m "..." && git push
git tag vX.Y.Z && git push origin vX.Y.Z   # 触发 Release 工作流（或手动建 Release 传 tgz）

也可以直接在会话中对 AI 说「帮我把本机预设同步到 GitHub」，AI 会按上述流程执行。

---

许可与致谢

• 本插件（插件代码、组合、本地插件）以 Apache-2.0 许可发布，见 LICENSE；
• 预设基座源于 xiaobright/dsh-anchored-standard（MIT）；
• J-Space 技能内容源于 Tiger3807861189/J-Space-Cognition-Suite-V3.6（Apache-2.0，打包内容与其上游 j-space/ 逐字节一致）；
• 同步机制模式参考 @linxin666/dsh-liangshen（Apache-2.0）；
• 完整归属见 NOTICE。