zbsph / dsh-j-space-warm

dsh-j-space-warm

J-Space Anchored Warm（j-a-w）预设插件 —— 为 DeepSeek Harness（dsh）Web GUI 打包的即装即用 Agent 预设，提供两个工具面变体：

预设	显示名	引导工具面	适用平台
j-space-exp-v3	j-a-w(Pwsh)	pwsh + str_replace_editor（bash 全程禁用）	Windows（tool-pwsh 仅 win32 启用）
j-a-w-bash	j-a-w(Bash)	持久 bash + str_replace_editor（pwsh 全程禁用）	跨平台（非 Windows 环境）

一句话：只要有安装包（tgz），就能安装本插件，然后在新会话预设选择器中直接选用「j-a-w(Pwsh)」或「j-a-w(Bash)」，行为与本机原预设完全一致。

两个变体仅工具面不同（初始工具 pwsh↔bash、晋升后同样只有对应 shell），其余文件（组合编排、J-Space 技能树、全部本地插件）逐字节一致。本插件把预设完整打包为 dsh 标准 bundle 插件：安装后在宿主启动时自动把预设同步到 ~/.dsh/.agent-presets/，升级插件即自动更新预设，卸载插件不影响已安装的预设文件。以 GitHub Release 为发布与备份标准。

---

目录

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

---

背景与定位

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

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

预设文件原存放于 ~/.dsh/.agent-presets/，本插件将其连同全部相关文件打包，实现：

1. 可分发：单一 tgz 安装包，任意 dsh 环境可装；
2. 可复现：安装后预设与本机原预设逐字节一致（含自动化校验测试）；
3. 可维护：升级插件即同步升级预设，无需手工拷贝；
4. 可追溯：GitHub 仓库 + Release 附件作为版本化备份标准；
5. 可审计：构建与 CI 内置密钥/泄露扫描（见「安全审计」）。

---

核心特性

特性	说明
即装即用	dsh plugin --profile web add <tgz> 一条命令安装，重启后预设出现在选择器
自动同步	宿主启动时把 presets/ 全部预设同步进 ~/.dsh/.agent-presets/，字节级幂等（无变化不重写）
升级联动	插件升级 → 预设自动更新；旧文件清理（prune extras）
卸载安全	卸载插件不删除已同步的预设，其他用户自建预设绝不触碰
结构校验	同步后对每个 agent.cordis.yml 做结构校验，坏文件以失败条目报告而非静默
可迁移	技能树经 baseUrl 相对解析，预设装到任何目录都可用
双变体	j-a-w(Pwsh)（Windows）/ j-a-w(Bash)（跨平台），仅工具面不同
安全审计	npm run audit 扫描密钥/凭据/本地路径泄露，接入构建与 CI
双语文档	中文 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/   → 选择器「j-a-w(Pwsh)」
        └─ j-a-w-bash/       → 选择器「j-a-w(Bash)」
                              │
                              ▼
        新会话预设选择器 → 按环境选用对应变体

预设本身是 agent-plane 组合：agent.cordis.yml 里 24 个行（row）按职责分组——bootstrap（工具晋升/上下文过滤）、shell（引导面）、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/       # ★ 预设「j-a-w(Pwsh)」全树（Windows，pwsh 引导面）
│   └── j-a-w-bash/           # ★ 预设「j-a-w(Bash)」全树（跨平台，bash 引导面）
│       （两者除工具面外逐字节一致：agent.cordis.yml / preset.yml / 13 个 .mjs / skills/j-space/ 15 文件）
├── scripts/
│   ├── build.sh              # 语法检查 + 安全审计 + 测试 + verify + npm pack
│   ├── audit-secrets.mjs     # 密钥/泄露扫描（构建与 CI 强制）
│   ├── verify-install.mjs    # 独立端到端验证（默认写临时目录，--real 写真实根）
│   └── sync-from-reference.mjs  # 把本机预设拷回 presets/（维护闭环）
├── 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.2.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 <本插件源码目录>

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

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

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

---

使用

1. 打开 dsh Web GUI（默认 http://127.0.0.1:3080）；
2. 新建会话，在预设选择器中选择变体：
   • Windows → 「j-a-w(Pwsh)」（pwsh 引导面）
   • Linux/macOS 或其他环境 → 「j-a-w(Bash)」（bash 引导面）
3. 开始对话。首轮为热身轮（0 任务，模型调用一次 shell 解锁工具库并回复 warm-up complete），随后真实任务自动开始，工具全量就绪，J-Space 协议全程生效。

行为细节（两变体一致，仅 shell 不同）：

• 引导面：pwsh（j-a-w(Pwsh)）或持久 bash（j-a-w(Bash)）+ str_replace_editor（Minimal 精确双工具）；对应变体全程禁用另一个 shell；
• 晋升：首个持久晋升信号（任一工具调用或首条助手消息）后，常驻工具面扩为对应 shell/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
dir %USERPROFILE%\.dsh\.agent-presets\j-a-w-bash\agent.cordis.yml

# 2. GUI：新建会话 → 预设选择器出现「j-a-w(Pwsh)」与「j-a-w(Bash)」
# 3. 插件日志（宿主日志中应出现）
#    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/ 下已同步的预设——保留可用。如需连同预设一起删除，请手动删除对应目录（注意：这会影响正在使用该预设的会话）。

---

故障排查

现象	原因与处理
安装后选择器没有新预设	未重启 dsh（同步发生在宿主启动时）；确认安装命令输出无报错；查看宿主日志中的 dsh-j-space-warm 行
日志出现 preset ... sync failed	同步或结构校验失败，按错误信息检查；预设文件损坏时先删除对应 ~/.dsh/.agent-presets/<id> 再重启让插件重新同步
安装报 pnpm not found	先安装 pnpm（npm i -g pnpm）
git 装配报 build 被 pnpm 阻止	按提示在 profile 的 pnpm-workspace.yaml 的 allowBuilds 中放行
首轮没有热身轮	热身轮是「每个新顶层会话一次」：子代理、恢复的会话不触发；预插失败会优雅降级为无热身（任务照常，只是未锚定）
j-a-w(Bash) 在 Windows 上行为异常	该变体为跨平台设计，Windows 上持久 bash 依赖 PATH 中的 bash（WSL 垫片时可能启动 WSL bash）；Windows 请优先使用 j-a-w(Pwsh)
选错变体	两个变体仅 shell 不同，其余完全一致；按环境选择即可

---

从源码构建

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 <本插件源码目录>   # 构建 tgz
dev_inject_plugin <本插件源码目录>   # 免重启注入验证
dev_uninject_plugin dsh-j-space-warm              # 卸载注入

---

开发与测试

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

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

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

npm run sync:reference    # 把本机 ~/.dsh/.agent-presets/ 全部预设拷回 presets/
JSPACE_REFERENCE_ROOT=~/.dsh/.agent-presets npm test  # 字节一致性回归
npm run audit             # 安全审计（防密钥/路径泄露）
# 更新 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 会按上述流程执行。

---

安全审计

scripts/audit-secrets.mjs 在每次构建（npm run build）与 CI Release 流程中强制运行，扫描四类问题：

1. 已知密钥格式：GitHub PAT（github_pat_/ghp_/gho_ 等）、OpenAI/Anthropic key、AWS AKIA、Slack token、JWT、私钥块；
2. 键值式敏感字段：api_key/secret/password/credential 等赋值；
3. 本地路径泄露：Windows 用户目录/盘符路径、macOS/Linux home 路径（避免公开作者本机布局）；
4. 敏感文件名：.env*、*.pem/*.key/*.p12 等。

任何命中都会使构建失败（exit 1），保证后续每次更新发布都自动复检。npm run audit 可随时手动运行。

---

许可与致谢

• 本插件（插件代码、组合、本地插件）以 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。