# 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](https://github.com/xiaobright/dsh-anchored-standard)（MIT）的 **Warm** 实验变体（前身 V3），叠加了 [J-Space Cognition Suite V3.6](https://github.com/Tiger3807861189/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](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：本地安装包（推荐，离线可用）

```bash
# 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 装配（开发调试）

```bash
dsh plugin --profile web add github:zbsph/dsh-j-space-warm
# 或本地目录
dsh plugin --profile web add <本插件源码目录>
```

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

```bash
# 把 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 感知）。

---

## 验证安装成功

```bash
# 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: ...（异常时）
```

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

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

---

## 升级与卸载

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

**卸载**：

```bash
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 不同，其余完全一致；按环境选择即可 |

---

## 从源码构建

```bash
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）：

```text
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）：

```bash
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](LICENSE)；
- 预设基座源于 [xiaobright/dsh-anchored-standard](https://github.com/xiaobright/dsh-anchored-standard)（**MIT**）；
- J-Space 技能内容源于 [Tiger3807861189/J-Space-Cognition-Suite-V3.6](https://github.com/Tiger3807861189/J-Space-Cognition-Suite-V3.6)（**Apache-2.0**，打包内容与其上游 `j-space/` 逐字节一致）；
- 同步机制模式参考 [@linxin666/dsh-liangshen](https://github.com/zhu1090093659/dsh-web-ui)（Apache-2.0）；
- 完整归属见 [NOTICE](NOTICE)。