dsh-spec-mode

Readme

# dsh-spec-mode

DSH 插件：由模型主导的增量访谈，把用户逐步浮现的需求固化成**开发规范**与**项目文档**。

这份文件回答一个问题：这个插件做什么、怎么用、改它之前要知道哪几条规矩。读者是要安装或改动
它的人——读完你会知道入口在哪、怎么进入访谈模式、改完怎么自测。不需要先读别的文档。

- **入口**：仓库根目录的入口模块，一个接收插件的上下文、把各种能力挂上去的装配函数。
- **依赖**：只用到 Node 自带的加密、文件、环境、路径四类模块。不装任何宿主运行时包，所以只靠
  profile 自身就能解析，不会装出第二份宿主运行时。
- **安装形态**：以链接方式挂进 web profile，加载器的行为名是 include:spec-mode。
- **产出文档的默认读者是不懂代码、也不懂这个业务的人**：说人话优先，代码能不出就不出——要靠贴代码讲
  实现，说明逻辑还没讲清；只有读者要照着做时才给代码，并且要跟着复现步骤。首段是白话导读，术语首次
  出现当句解释，决策只记结论。

## 用法

进入访谈与退出访谈两条命令：

```
/spec [初始想法]
/spec off
```

裸 `/spec` **只切模式**，不提交任何消息：访谈从用户真正写下的东西开始——`/spec` 后面的想法，
或他随后发的第一条普通消息。

访谈结束时不需要用户手动退出：模型会弹一个确认框，让用户选「退出并落盘」或「继续访谈」。访谈
期间工作树只读，唯一可写目标是项目文档目录里的那份访谈草稿。

## 规则

- **改投影状态字段或折叠语义时，必须同时把状态版本号加一。** 否则持久化缓存里的旧行会被前向
  折叠成垃圾。
- **裸 `/spec` 不得合成消息。** 命令面本身不产生模型消息；补一条「起轮」消息等于替用户开题。
  访谈必须由用户写下的内容触发。
- **不要在命令处理里读「有效状态」来回答「这条命令进来之前是什么状态」。** 命令记录在处理器
  之前入日志，那个问题只能问已提交状态。
- **图标用显式颜色，不要跟随当前色。** 图标以数据地址渲染，拿不到宿主样式里的颜色，跟随当前色
  会变成深色背景上不可见的黑色。
- **状态折叠对无关事件必须返回同一个状态引用**，否则投影的增量机制失效。
- **不引宿主包。** 需要宿主工具时按等价实现内联。
- **四条文档规则要跟着落盘文件传下去（自举）。** 写法与判据分两处维护：写法在访谈协议里，写入
  时的提醒判据在软约束模块里；改判据要同时改写法说明，否则模型只被提醒、不知道该怎么写。

## 文档索引

| 文档 | 何时读 |
| --- | --- |
| docs/插件说明.md | 想知道这个插件做什么、怎么用、拦什么不拦什么、界面出现在哪、有哪些限制时 |
| docs/实现逻辑.md | 要改代码，或要理解状态为什么存在投影里、守卫为什么这么判时 |
| docs/交接文档.md | 接手这个插件、要跑验证清单、或升级宿主后排查时 |
| selftest.mjs | 改完纯逻辑模块后跑 `node selftest.mjs` |

## 自测

```
node selftest.mjs
```

23 项纯逻辑断言，不需要宿主：草稿锚点、路径判定、投影折叠的全部分支、产出文件的提醒判据。

## 协议

[MIT](LICENSE)