hunbs-1/dsh-codepect

dsh-codepect

dsh-codepect 是一个基于 DSH 动态 Cordis 插件机制构建的自动 API 文档生成器。它扫描工作区中的 TypeScript/JavaScript 源代码，解析 JSDoc 注释以及 NestJS/Express 风格的路由定义，并生成 OpenAPI 3.0 规范（openapi.json / openapi.yaml）。零外部依赖，可离线运行。

该名称结合了“code”和“spec”：你的源代码被转换为一份 OpenAPI 契约。

快速开始

git clone https://github.com/hunbs-1/dsh-codepect.git
cd dsh-codepect
node devtest/host-smoke.cjs   # zero-dependency offline smoke test (no npm install, no network)

扫描器完全自包含：克隆并运行冒烟测试无需任何依赖。
要将其用作文档生成器，你需要一个正在运行的 DSH 实例（该插件是一个 DSH
动态 Cordis 插件）。按照用法部分所述，每个 DSH 进程加载一次即可。

详细用法

前提条件：一个正在运行的 DSH 实例（该插件在 DSH 内部运行，而不是作为独立
程序运行），以及你自己的、使用 JSDoc 注释、NestJS
装饰器或 Express 路由的 TypeScript/JavaScript API 源代码。

1. 获取插件

git clone https://github.com/hunbs-1/dsh-codepect.git

插件本身实际只需要两个文件：src/host.js（Host 半部分：扫描、
schema 推断、OpenAPI 生成、mock 服务器、git 集成、HTTP 路由）和
src/client.js（Client 半部分：内嵌的“设置 -> API 文档”页面以及运行卡片面板）。

2. 添加配置文件

将 .dsh-api-docs.config.json（不带点号的拼写也被接受）放在你使用
该插件的文件夹中，并将 include 指向你的源代码目录。扫描根目录是包含该配置
文件的文件夹；该文件夹之外的任何内容都不会被扫描。

{
"title": "My API",
"version": "1.0.0",
"description": "API docs for my service",
"language": "zh",
"include": ["src//.ts"],
"exclude": ["/node_modules/", "/dist/"]
}

每个字段的说明见下方的配置参考。

3. 在 DSH 会话中加载插件

可以任选其一：

- 让你的 DSH 助手读取 dsh-codepect/src/host.js 和 dsh-codepect/src/client.js，
并将它们注册为一个动态 Cordis 插件（code.host / code.client），或者
- 手动使用 cordis_define 机制，将 src/host.js 作为 code.host，将
src/client.js 作为 code.client，然后运行该包，如有提示则批准。

注意：动态插件仅存在于 DSH 进程内存中，因此重启 DSH 后你需要再次加载
该插件（这两个文件是唯一事实来源，所以这个过程很快且无损）。

4. 生成文档

- 调用模型工具 api_docs_generate（可选传入 { "rescan": true }），或者
- 让插件在加载时自动运行启动扫描，或者
- 在 watch.enabled 开启时更改源文件以触发自动重新扫描。

扫描会在配置的输出路径写入 openapi.json 和 openapi.yaml，并更新
版本归档与变更日志。

5. 查看文档

- 独立页面：http://localhost:3080/api-docs（搜索、端点展开、schema、
变更日志、可复制示例、mock 链接、版本切换、语言和主题切换）
- 嵌入式页面：DSH Web UI，设置 -> API 文档
- 运行卡片：插件的状态面板（端点/schema 数量、破坏性变更、git 修订版本、
输出路径）
- 契约文件：http://localhost:3080/api-docs.json（JSON）和 /api-docs.yaml（YAML），
可直接交给前端团队或工具使用。

6. 版本管理与破坏性变更检测

1. 在配置中保留 version（例如 "1.0.0"）。
2. 每次扫描都会在该版本下归档完整规范（api-docs/versions.json）。
3. 修改你的源代码（添加/删除端点、将参数设为必填、更改 schema），
然后重新扫描。
4. 打开变更日志（/api-docs/changelog.json 或 UI 中的变更日志开关）：新
条目会分别标记破坏性变更（端点被删除、必填参数被添加/删除、类型
变更、请求/响应结构变更）和非破坏性变更，并附带
扫描时捕获的 git 修订版本。
5. 在 /api-docs/version/{v}（HTML）、.../{v}.json 或
.../{v}.yaml 浏览任意已归档版本；文档页面中的版本下拉菜单可在它们之间切换。

7. Mock 服务器

启用 mockEnabled（默认 true）。Mock 数据根据每个端点的 200 响应
schema 生成，并通过 mockPrefix + 端点路径提供，且区分方法：

GET http://localhost:3080/api-mock/api/users/123
POST http://localhost:3080/api-mock/api/users

8. 请求示例

每个端点都会获得一个 cURL 和一个 JavaScript Fetch 示例（路径/查询参数会填入
示例值，存在示例请求体时也会填入），存储在 x-examples 扩展中，并
显示在文档 UI 中（独立页面有复制按钮）。

9. 语言切换

UI 语言默认为 config.language（"zh" 或 "en"）。独立页面和
嵌入式页面都有一个页面内语言按钮；独立页面会将选择记住在
localStorage 中。插件生成的文本（响应描述、变更日志条目、验证
和扫描消息）在扫描时遵循配置的语言。

10. 监听模式

将 watch.enabled 设为在扫描的源文件发生变化时自动重新扫描：

"watch": { "enabled": true, "intervalSeconds": 5 }

11. 模型工具

api_docs_generate 支持两个标志：

- rescan: true — 立即强制进行完整重新扫描
- diagnoseBase: true — 返回工作区根目录解析诊断信息（选择了哪个目录
作为扫描根目录以及原因）

12. 将插件移动到另一个项目

复制 src/host.js、src/client.js 以及一个 .dsh-api-docs.config.json，其 include 指向
该项目的源代码。由于扫描根目录是配置文件所在的文件夹，插件会
只扫描该项目，而不扫描其他内容。

配置参考
将 .dsh-api-docs.config.json（也接受无点拼写）放在你使用该插件的文件夹中：

{
"title": "Demo User Service API",
"version": "1.0.0",
"description": "Sample API documentation generated by the dsh-codepect plugin",
"language": "en",
"include": ["demo-api//.ts"],
"exclude": ["/node_modules/", "/.git/", "/dist/"],
"outputPath": "demo-api/openapi.json",
"yamlOutputPath": "demo-api/openapi.yaml",
"versionArchivePath": "api-docs/versions.json",
"changelogPath": "api-docs/changelog.json",
"mockEnabled": true,
"mockPrefix": "/api-mock",
"examplesEnabled": true,
"watch": { "enabled": true, "intervalSeconds": 5 }
}

| 字段 | 默认值 | 描述 |
| --- | --- | --- |
| title | API Documentation | 规范标题，显示在文档页面页眉中 |
| version | 1.0.0 | 当前规范版本；每次扫描后归档到 versionArchivePath 下 |
| description | 空 | 规范信息描述，显示在标题下方 |
| language | zh | UI 语言：zh 或 en（页面内切换仍然可用） |
| include | ["/.ts", "/.js"] | 源文件的 Glob 模式，相对于配置文件所在文件夹 |
| exclude | node_modules/.git/dist/build/coverage | 要跳过的 Glob 模式 |
| outputPath | api-docs/openapi.json | JSON 规范输出路径（相对于配置文件所在文件夹） |
| yamlOutputPath | api-docs/openapi.yaml | YAML 规范输出路径 |
| versionArchivePath | api-docs/versions.json | 版本归档文件 |
| changelogPath | api-docs/changelog.json | 变更日志文件 |
| mockEnabled | true | 启用 /api-mock/ 模拟服务器 |
| mockPrefix | /api-mock | 模拟服务器 URL 前缀 |
| examplesEnabled | true | 生成 cURL/Fetch 示例到 x-examples |
| watch | { "enabled": false, "intervalSeconds": 60 } | 源文件更改时自动重新扫描 |

扫描范围

扫描根目录是包含插件配置文件的目录；会首先探测该目录，并且优先于任何会话目录或粘性目录，因此插件只会扫描使用它的文件夹。include / exclude 模式相对于该目录解析，逃逸模式（绝对路径或 ../）会被拒绝并给出警告——绝不会扫描配置目录之外的任何内容。

HTTP 路由

| 路由 | 描述 |
| --- | --- |
| GET /api-docs | 独立文档页面（版本切换、变更日志、可复制示例、模拟链接、语言/主题切换） |
| GET /api-docs.json / /api-docs.yaml | 当前 OpenAPI 规范（JSON / YAML） |
| GET /api-docs/versions.json | 版本索引 |
| GET /api-docs/version/{v} / .../{v}.json / .../{v}.yaml | 历史版本文档（页面 / JSON / YAML） |
| GET /api-docs/changelog.json | 变更日志 |
| GET|POST|... /api-mock/{endpoint-path} | 模拟数据（根据 200 响应 schema 生成） |

源注释指南

该插件从你的源代码注释中读取文档——无需维护单独的文档文件：

/* 用户管理端点 /
@Controller('api/users')
export class UserController {
/*
* 获取用户详情
* 根据用户 id 返回完整的用户记录
/
@Get(':id')
async getUser(
/* 用户 id */
@Param('id') id: string
): Promise { ... }
}

- 摘要：控制器/方法/路由之前的 JSDoc 块的第一行。
- 描述：同一 JSDoc 块的后续行。
- 参数：@param {type} name - description（Express）、带内联 JSDoc 的 @Param/@Query/@Headers
装饰器（NestJS）。
- 请求体：@Body() 参数类型（NestJS）、@param body（Express）。
- 返回类型：方法的 TypeScript 返回类型 / @returns {type}。
- 模式：带内联字段注释的 interface / type / enum 声明。
- 弃用：@deprecated。

demo-api/ 是一个完整的演示项目，展示了上述所有内容。

功能特性

核心（MVP）

| 模块 | 描述 |
| --- | --- |
| 源码扫描 | 递归发现匹配 include 的 TS/JS 文件并解析 JSDoc 块（摘要 / 描述 / @param / @returns / @deprecated / @tag） |
| 路由发现 | NestJS：@Controller('base') + @Get/@Post/@Put/@Patch/@Delete/@All('path')；Express：app.get/post/...('path') |
| 参数提取 | NestJS：@Param('id') -> 路径，@Query('page') -> 查询，@Headers('x-t') -> 请求头，@Body() -> requestBody；Express：:id 路径标记 + JSDoc @param |
| 模式推断 | 基本类型、数组、联合枚举、嵌套对象、$ref、可选字段、Promise/Partial/Readonly/Record 解包、Date -> date-time、循环保护 |
| 规范生成 | 标准 OpenAPI 3.0：paths + parameters + requestBody + responses + components.schemas |
| 输出文件 | openapi.json（格式化 JSON）+ openapi.yaml（手写 YAML 序列化器，经过往返验证） |
| 文档页面 | 1. DSH Web UI“设置 -> API 文档”内嵌页面 2. 独立页面 /api-docs 3. 运行卡片状态面板 |
| 模型工具 | api_docs_generate 工具：{ "rescan": true } 强制重新扫描 |

扩展（V2）

| 特性 | 描述 |
| --- | --- |
| 多版本文档 | 每次生成都会归档一个版本（api-docs/versions.json）；路由 /api-docs/version/{v}（HTML）/ .json / .yaml；UI 中的版本下拉菜单 |
| 破坏性变更检测 | 与上一版本进行差异对比，并标记 破坏性变更（移除端点、添加/移除必需参数、类型变更、请求/响应结构变更）以及非破坏性变更（新增端点、新增可选参数）；变更日志位于 api-docs/changelog.json，可在 UI 中查看 |
| Mock 服务器 | 根据 OpenAPI 模式生成模拟数据（枚举/示例值、嵌套对象、数组、$ref 解析）；前缀 /api-mock + 端点路径，例如 /api-mock/api/users/123，支持按方法区分 |
| Git 集成 | 每次扫描记录当前提交（git rev-parse --short HEAD，与变更日志一起持久化）；内置规范校验（$ref 完整性、重复参数、缺失响应）；可选的 watch 模式在源文件变更时自动重新扫描 |
| 请求示例 | 为每个端点生成 cURL 和 JavaScript Fetch 示例（路径/查询填充、示例请求体），显示在 x-examples 和文档 UI 中（独立页面上的复制按钮） |
| i18n | UI 语言可在中文和英文之间切换（默认来自 config.language，页面内切换按钮） |

项目结构

dsh-codepect/
├── src/
│   ├── host.js        # 插件 Host 源码（扫描器 / schema 推断 / OpenAPI 生成 / mock / git）
│   └── client.js      # 插件 Client 源码（DSH Web UI 内嵌文档页面 + 运行卡片）
├── demo-api/src/      # 演示项目（NestJS controller + DTO + enum + Express 路由）
├── devtest/           # 测试脚本（离线冒烟、HTTP E2E、浏览器交互）
├── .dsh-api-docs.config.json  # 插件配置示例
├── README.md          # 本文件
└── LICENSE            # MIT

demo-api/openapi.json、demo-api/openapi.yaml 和 api-docs/ 是生成的产物，
已被 gitignore；克隆后运行一次扫描即可重新生成它们。

测试

node devtest/e2e-check.cjs        # 22 项 HTTP 功能检查，预期 22/22
node devtest/host-smoke.cjs       # 离线流水线冒烟测试（扫描 + YAML 往返）

破坏性变更检测的建议手动流程：

1. 记下当前端点数量（演示项目为 8）
2. 在 demo-api/src/user.controller.ts 中移除一个 @Get 方法或将某个查询参数设为必填
3. 等待约 5 秒（watch 模式自动重新扫描），打开变更日志
4. 预期出现一条带有红色“破坏性变更”标记的新条目，端点数量已更新

实现说明

- 路径锚定：插件配置文件所在目录是扫描根目录，并优先探测；
只有在未找到配置文件时，才回退到发起会话/工作区的
级联。写入操作带有显式的 { mode: 'workspace-write', workspaceRoot:  }
沙箱策略。
- 生命周期：所有路由/工具/RPC/定时器都随插件 fiber 一起释放；scanning
锁可防止重入扫描。
- 错误隔离：单个文件的解析失败会记录在 status.errors 中，不会
中止整个扫描。
- i18n：独立页面和内嵌 React 页面都通过 zh->en 字符串
映射（tr()）进行翻译，由页面内语言按钮切换（独立页面会记住选择，
保存在 localStorage 中）；默认值来自 config.language。

已知限制

- 泛型实例化（例如 Paginated）和复杂函数类型会退化为 {}
- 以带分号的对象字面量形式编写的接口属性解析不完整
- 一个文件中有多个 @Controller 类时，最后一个基础路径生效
- 变更检测是结构性的（JSON Schema 相等性），而非语义兼容性分析
- Mock 数据是确定性的样本值；没有随机化或自定义脚本

许可证

MIT