# dsh-init-plugin

**Repository Path**: dk-1001/dsh-init-plugin

## Basic Information

- **Project Name**: dsh-init-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dsh-init-plugin

一个 [dsh](https://github.com/deepseek-ai/deepseek-harness)(DeepSeek Harness)插件,注册 `/init` 斜杠命令:先对仓库做一次确定性扫描,再以对话方式驱动生成 `AGENTS.md`,风格仿 Claude Code `/init`。

`AGENTS.md` 是 dsh 原生的项目指令文件 —— 每次会话都会加载进 agent 上下文(带字节预算截断,文件变化时热同步)。本插件把"创建它"变成一条命令 + 一轮对话的过程。

## 工作原理

1. `/init [可选附加要求]` 触发已注册的命令处理器。
2. 处理器对仓库根做**确定性扫描**(不消耗模型 token):目录树(忽略 `.git`、`node_modules`、`.npm-cache`、构建产物等;条目超过 40 的目录折叠并标注条目数)、README、`package.json` 摘要、选定配置文件、以及现有根 `AGENTS.md` —— 全部字节受限(摘要预算 24KB;事实段优先保留,目录树最后被截断)。
3. 处理器把扫描摘要 + 任务提示 `steer` 给**接收 agent**(与 `dsh-plan-mode` 提交 `/plan` 可选消息的模式相同)。生成逻辑不留在插件里。
4. agent loop 接管:它自己读关键文件,询问你对现有 `AGENTS.md` 的处理方式(覆盖 / 合并 / 追加 / 跳过),问几个澄清问题,然后用自己的文件工具写文件,最后总结结果。
5. 后续 refine 就是继续对话 —— 随时让 agent 调整各小节。

## 环境要求

- dsh 宿主提供 `commands` 注册表(`packages/interaction/commands`)、`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-llm`(peer 依赖)。
- Node >= 22.19。

## 安装

本插件是一个 **dsh profile bundle**:一条 `dsh plugin add` 即可安装并激活 —— 无需手动编辑组合配置。

```sh
# 安装进 profile,并自动登记 bundle 层
dsh plugin --profile web add git+ssh://git@gitee.com:dk-1001/dsh-init-plugin.git
```

然后**重启 `dsh web`**(bundle 层在启动时组合)。`/init` 默认以 dsh 工作目录为 `root`;若要扫描的仓库不同,在 home 层补丁(`$DSH_HOME/cordis.patch.yml`)覆盖即可(id 定向覆盖优先级最高):

```yaml
- id: dsh-init
  config:
    root: 'D:/WorkSpace/dsh'
```

不用 `dsh plugin` 的手动安装:`npm install --allow-git=all git+ssh://git@gitee.com:dk-1001/dsh-init-plugin.git`(npm 12+ 默认 `allow-git=none` 禁用 git 依赖,该参数为本次安装重新启用),然后把包名写进你的组合。构建产物 `lib/` 已随仓库提交,安装后无需构建。

## 用法

```
/init
/init 侧重测试约定与构建管线
```

命令在带命令适配器的交互界面(Web/CLI)可用;headless 与 ACP 表面没有命令适配器,不在本插件范围内。

## 配置

| 键 | 默认值 | 含义 |
|---|---|---|
| `root` | `process.cwd()` | 待扫描的仓库根。绝对路径,或相对 dsh 工作目录。 |

```yaml
- insert:
    - id: dsh-init
      name: 'dsh-init-plugin'
      config:
        root: 'D:/WorkSpace/dsh'
```

## 开发

```sh
pnpm install          # typescript + @types/node
pnpm run typecheck    # tsc --noEmit
pnpm run test         # node --test tests/(Node 原生 TS,无测试框架)
pnpm run build        # tsc 生成声明 + esbuild 打包 lib/index.js
```

## 实现笔记

- **命令注册**遵循 `dsh-plan-mode` 的条件注入模式:`ctx.inject(['commands'], ...)`,只有组合中存在命令注册表时插件才激活命令。
- **模型可见 ⟺ 已记录**:steer 的任务消息携带插件 `source`(`{ kind: 'plugin', plugin: 'dsh-init', form: 'notice', summary }`),会话日志可完整重建到达模型的内容。
- **扫描器隔离**:`src/scan.ts` 零 dsh 依赖(仅 Node 内建),可独立测试,预算约束 token 成本。
- **运行时零 dsh 依赖**:`src/message.ts` 复刻 `@deepseek-ai/dsh-llm` 的最小 `createUserMessage` 契约(id + role + freeze,已对照 harness 源码核实),使 bundle 在任何环境可加载,即使 harness 包尚未发布。官方包发布后换回正式 import。
- **类型表面**:`types/dsh.d.ts` 只声明本插件用到的 Cordis 命令表面,因为 vendored 的 dsh 源码尚无法从独立包解析。运行时类型来自 dsh 宿主。上游类型变更时刷新声明(形状镜像自 `dsh-plan-mode`)。
- **不改 dsh 源码**:插件组合进 dsh,不修改 harness。

## 已知限制与后续工作

- **仅根级**:嵌套包的 `AGENTS.md`(dsh 原生支持层级加载)尚未生成 —— 扫描会把它们显示在树中,但任务只针对根文件。
- **仅交互表面**:headless/ACP 无命令适配器(dsh 的限制,不是插件的)。
- **无图片输入**:命令未声明 `input.images`;后续可支持截图。
- **扫描启发式**:预算与候选清单针对中小仓库调优,超大 monorepo 可能需要配置覆盖。

## License

MIT