dsh-adaptive-anchored-standard

Readme

<div align="center">
  <h1>dsh-adaptive-anchored-standard</h1>
  <p><b>先用官方 Minimal 稳住首请求，再一次性进入完整 Standard 能力</b></p>
  <p>
    <a href="https://github.com/uruana33/dsh-adaptive-anchored-standard/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
    <img alt="DSH >= 0.1.0-rc.7" src="https://img.shields.io/badge/DSH-%3E%3D0.1.0--rc.7-2f80ed" />
    <img alt="Node.js >= 22.19" src="https://img.shields.io/badge/Node.js-%3E%3D22.19-339933" />
    <img alt="Status: Experimental" src="https://img.shields.io/badge/Status-Experimental-d97706" />
  </p>
  <p>
    面向 DeepSeek V4 Pro 的 DSH 用户 preset。首个 root 请求保持官方 Minimal 的<br />
    persona 与双工具面；完成首个 assistant/tool 事件后，状态可恢复地晋升到完整 Standard。
  </p>
</div>

> [!WARNING]
> 当前版本是实验性 preset。macOS/Linux 的本地验证已通过，但真实 Windows 主机 smoke、真实
> V4 Pro 参考评测和 IP/session/provider 因果实验尚未完成。请先在自己的环境中验证，再考虑设为默认。

## ✨ 功能一览

- **🎯 Minimal-first**：普通 root 首请求只暴露 `bash` 与 `str_replace_editor`，并暂时隐藏
  `agent-instructions`、`skill-catalog`；plan 首请求额外保留 `exit_plan_mode`。
- **🔓 一次性晋升**：首个 `assistant/message` 或 `tool/call` 后开放完整 Standard 工具目录，
  不按任务关键词路由，也不在会话中反复切换工具面。
- **💾 可恢复状态**：resume、compaction、进程重启和 editor crash/restart 都从 durable event log
  重建状态，不会把已晋升的会话重新降回 Minimal。
- **👥 Child 完整能力**：child session 直接使用完整 catalog，不继承 root 的 Minimal 清空逻辑。
- **🧩 宿主原生组合**：复用 DSH 官方插件、sandbox、approval、persistence 和 model route；preset
  不引入动态 loader、`eval` 或 `new Function`。
- **↩️ 原子升级回滚**：安装器只替换目标 preset 目录，升级前自动备份，失败时恢复旧版本，不改
  `settings.yaml`、API key 或其它 preset。

## 🧭 工作方式

| 时机 | Persona | 模型可见工具 | 上下文处理 |
| --- | --- | --- | --- |
| 普通 root 首请求 | 官方 Minimal | `bash`、`str_replace_editor` | 暂时移除 `agent-instructions`、`skill-catalog` |
| plan 首请求 | 官方 Minimal | 上述两项 + `exit_plan_mode` | 同上 |
| 首个 assistant/tool 事件后 | 保持首轮 persona | 完整 Standard catalog | 恢复允许的 AGENTS/skills 消息 |
| child session | 宿主正常 persona | 完整 Standard catalog | 不套用 root 的 Minimal 清空逻辑 |

晋升只发生一次。`runtime`、时间、provider 等易变上下文不会被拼回 routed persona；协议版本和
source hash 只写入运维 manifest，不会注入模型 prompt 或工具 schema。

## 🚀 安装

### 前置条件

- 已安装并能运行 DSH，版本 **`>=0.1.0-rc.7`**；
- Node.js **`>=22.19.0`**；
- macOS、Linux 或 Windows。Windows 需要可用的 Git Bash、MSYS2 或 WSL `bash` 后端。

### 在 DSH 中安装并启用

这是一个 **agent preset**，不是普通的 profile 插件包。因此不要使用
`dsh plugin --profile web add dsh-adaptive-anchored-standard`：`dsh plugin` 管理的是
`~/.dsh/profiles/<profile>/package.json` 中的 npm/pnpm 插件依赖，本项目应安装到 DSH 的用户 preset 根目录。

如果还没有安装 DSH，可以先安装官方 CLI：

```bash
npm install -g @deepseek-ai/dsh@latest
dsh --version
```

然后执行以下命令安装 preset：

```bash
git clone https://github.com/uruana33/dsh-adaptive-anchored-standard.git
cd dsh-adaptive-anchored-standard
npm run install:user
```

安装器将以下 payload 原子复制到 `${DSH_HOME:-$HOME/.dsh}/.agent-presets/adaptive-anchored-standard`：
`agent.cordis.yml`、`preset.yml`、`README.md` 和 `src/`。安装器会检查 DSH 版本、生成 manifest、
在升级前保留 backup，并且不会修改 API key 或其它 preset。

启动 DSH Web：

```bash
dsh web
```

在 Web 界面的 **Agent Preset/智能体预设选择器** 中选择
`adaptive-anchored-standard`（显示名称为“自适应锚定标准模式”），然后创建一个新 session。
已经运行的 session 不会因切换默认值而迁移；请用新 session 验证首轮双工具和后续晋升行为。

如果当前 DSH UI 没有显示选择器，也可以将默认值写入
`${DSH_HOME:-$HOME/.dsh}/settings.yaml`。保留文件中的其它设置，只添加或修改这一段：

```yaml
agent-presets:
  default: adaptive-anchored-standard
```

保存后重启 `dsh web`，该默认值只对之后创建的 session 生效。需要临时使用其它 preset 时，
在 UI 中切换即可；不要在已经产生模型输出的 session 中途切换。

macOS/Linux 也可执行 `scripts/install.sh`；Windows PowerShell 可执行：

```powershell
./scripts/install.ps1
```

### 更新与回滚

```bash
git pull
npm run install:user
```

安装器对 DSH 只设置**最低版本**，不设置最高版本：任何格式合法且不低于 `0.1.0-rc.7` 的版本都
允许安装；高于直接验证版本时会输出 warning。DSH 升级后必须重新运行 smoke，若宿主 API 或工具
schema 发生变化，可回滚到最近一次备份：

```bash
node scripts/install.mjs --rollback
```

已运行的旧 session 不会被强制迁移；新 session 使用新版本。安装失败会清理 staging 并恢复旧
目录，具体升级合同见 [`UPGRADE-CONTRACT.md`](./UPGRADE-CONTRACT.md)。

## ✅ 验证与开发

仓库没有运行期 npm 依赖，Node.js 内置测试即可运行：

```bash
npm test
npm run release:check
npm run smoke
npm run smoke:web-api
npm run smoke:web-plan-child
npm run smoke:editor-recovery
npm run profile:event-fold -- --json
```

Windows 实机可额外运行：

```powershell
npm run smoke:windows
```

非 Windows 主机会正确报告跳过，而不是伪造 Windows 通过结果。`release:check` 会在临时
`DSH_HOME` 中验证升级、backup、manifest、显式回滚，以及 `settings.yaml`/凭据文件保持不变。

当前已验证：`npm test` 88 项、POSIX smoke、Web API root/plan/child、editor crash recovery、
安装回滚和 payload hash。尚未验证的内容会在 [`IMPLEMENTATION-STATUS.md`](./IMPLEMENTATION-STATUS.md)
中明确标记，不应从本仓库的 fixture 结果推导 V4 Pro 生产级分数。

## 🔐 安全边界

- preset 复用 DSH 宿主的 sandbox、approval 和 filesystem policy；用户 preset 的权限等同于它引用的
  宿主插件，不会额外提供沙箱；
- 观测模块只记录脱敏后的 header/request hash、工具名、上下文来源和 provider 元数据，不保存 API key
  或完整敏感请求；
- `str_replace_editor` 使用官方 Minimal 的 local fs realm；晋升后的 `read`/`write`/`edit` 仍遵循
  宿主 filesystem policy；
- Windows fallback 通过 Git Bash/MSYS2/WSL 执行命令，没有 Unix PTY 或 OS sandbox 的等价保证。

安装前请审阅 `agent.cordis.yml` 及其引用的 DSH 插件。preset 不是安全边界，也不会改变 DSH 对
工作区、凭据和网络的既有策略。

## ⚠️ 已知限制

- 尚无真实 Windows 主机 smoke 证据；Windows 的 exact Minimal、PTY、sandbox 和评测语义不与
  macOS/Linux 做等价承诺；
- 尚无真实四组参考评测，因此不宣称“98/99”或其它能力分数；`BASELINE.md` 中的 rc.6 数值只是
  历史快照；
- 尚无真实 IP/session/provider 因果结论；请按 [`CAUSAL-EXPERIMENT.md`](./CAUSAL-EXPERIMENT.md)
  固定变量后自行采集；
- `src/rc6-standard-catalog.mjs` 是历史 Standard schema 快照，DSH 升级后需要重新运行验证；
- 不建议在证据补齐前把该 preset 写成全局默认，也不建议在同一 session 中途切换 preset。

## 📚 文档索引

- [`IMPLEMENTATION-STATUS.md`](./IMPLEMENTATION-STATUS.md)：实现状态、已完成证据和未闭合项；
- [`UPGRADE-CONTRACT.md`](./UPGRADE-CONTRACT.md)：原子升级、backup、session 恢复和回滚规则；
- [`RELEASE-CHECKLIST.md`](./RELEASE-CHECKLIST.md)：公开发布前的验收清单；
- [`CAUSAL-EXPERIMENT.md`](./CAUSAL-EXPERIMENT.md)：IP/session/provider 单变量实验格式；
- [`src/adaptive-bootstrap.mjs`](./src/adaptive-bootstrap.mjs)：Minimal-first 与 durable promotion 的核心实现。

## 🤝 贡献

欢迎提交 Issue 或 Pull Request。涉及协议、工具 catalog、安装器和宿主兼容性的改动，请同时附上
相关测试或 smoke 输出；不要提交 API key、完整 provider 请求、个人工作区路径或其它敏感日志。

## 📄 许可证

本项目以 [MIT License](./LICENSE) 发布。