jax-hono 1.0.19 → 1.0.21

package/docs/agent.md

@@ -1,167 +1,169 @@
-# Agent 维护说明
-
-这份文档给 Codex、Claude 或其他代码代理阅读，用来说明维护 `jax-hono` 时的默认规则。
-
-## 本地 link 规则
-
-`jax-hono` 是用户自己维护的框架，常通过 `jax link` 链接到业务工程的 `node_modules/jax-hono`。
-
-如果在业务工程中需要修改 `jax-hono` 行为，先检查依赖是否已经 link 到本地源码目录。不要把它当成一次性的第三方 `node_modules` 临时补丁。
-
-在 Windows PowerShell 中，可以在业务仓库根目录查找所有 `jax-hono` 依赖：
-
-```powershell
-Get-ChildItem -Path . -Directory -Recurse -Filter jax-hono |
-  Where-Object { $_.FullName -match '\\node_modules\\jax-hono$' } |
-  Format-List LinkType,Target,FullName
-```
-
-如果 `LinkType` 是 `Junction` 或 `SymbolicLink`，直接修改 `Target` 指向的 `jax-hono` 源码目录。
-
-如果没有 link，先执行：
-
-```powershell
-jax link
-```
-
-然后再次确认 link 状态，再修改框架源码。
-
-## 修改生成器后的验证
-
-修改 `build/generate-registry.ts`、`build/generate-config.ts` 等生成逻辑后，需要在使用方工程里重新生成。
-
-常见命令：
-
-```powershell
-bun run setup
-```
-
-然后检查业务工程中的生成结果，例如：
-
-```text
-.jax-hono/controllers.generated.ts
-.jax-hono/models.generated.ts
-.jax-hono/services.generated.ts
-.jax-hono/middlewares.generated.ts
-.jax-hono/plugins.generated.ts
-.jax-hono/index.ts
-```
-
-如果业务仓库里有多个工程都依赖 `jax-hono`，分别查看各工程的 `package.json`，运行它们自己的 setup/build 命令。
-
-`.jax-hono` 只属于调用项目，不要在 `jax-hono` 包目录里创建或维护 `generated` / `.jax-hono` Junction。需要 `bun --compile` 的项目推荐用 setup 包裹 Bun 构建命令：
-
-```powershell
-bun node_modules/jax-hono/setup.ts src/index.ts -- bun build src/index.ts --compile --production --target=bun-windows-x64 --outfile dist/app.exe
-```
-
-setup 会在执行命令期间临时把入口文件里对 `jax-hono` 的导入切到项目生成入口，命令结束后恢复源码。真正的编译参数交给 `bun build` 自己处理。
-
-业务入口仍然从框架导入：
-
-```ts
-import { config, createApp } from 'jax-hono';
-```
-
-这样 Bun 才能在编译时把生成模块放进可执行文件；运行时动态查找 `.jax-hono/*.ts` 只能作为开发态兜底，旧 `generated/*.ts` 仅作为兼容路径。
-
-## 插件生成约定
-
-生成器只扫描已启用插件。插件启用来源包括：
-
-- `jax-hono/plugins/config.ts`
-- 使用方工程的 `src/config/plugin.ts`
-
-未启用插件不应进入生成结果，避免构建解析未启用插件的运行时依赖。
-
-已启用插件中的约定文件会进入生成器：
-
-- `*.controller.ts` 注册到 `controllers` 根对象
-- `*.service.ts` 注册到 `services.generated.ts`
-- `*.cron.ts` 注册到 `crons.generated.ts`，由框架统一启动/停止
-
-例如启用插件 `foo` 后：
-
-```text
-plugins/foo/foo.controller.ts
-plugins/foo/foo-cache.service.ts
-plugins/foo/foo-cleanup.cron.ts
-```
-
-可生成：
-
-```ts
-controllers.foo
-service.fooCache
-```
-
-Cron 文件可以使用 `defineCron`：
-
-```ts
-import { defineCron } from 'jax-hono';
-
-export default defineCron({
-  name: 'foo-cleanup',
-  cron: '0 0 * * *',
-  immediate: true,
-  async run(ctx) {
-    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
-  }
-});
-```
-
-## Controller 注册约定
-
-生成器需要保持不同命名空间的边界清晰：
-
-- `*.backend.ts` 注册到 `controllers.backend`
-- `*.api.ts` 注册到 `controllers.api`
-- `*.open.ts` 注册到 `controllers.open`
-- `*.client.ts` 注册到 `controllers.client`
-- `*.controller.ts` 注册到 `controllers` 根对象
-
-`.controller.ts` 表示通用 Controller，供 backend/api/open/client 等不同路由复用，不应自动归入 `controllers.backend`。
-
-例如：
-
-```text
-src/modules/oss/oss.controller.ts
-src/modules/oss/oss-bucket.controller.ts
-```
-
-应生成：
-
-```ts
-controllers.oss
-controllers.ossBucket
-```
-
-如果需要后台专用 Controller，使用：
-
-```text
-src/modules/foo/foo.backend.ts
-```
-
-应生成：
-
-```ts
-controllers.backend.foo
-```
-
-## 模块路径命名
-
-模块内文件名如果以模块目录名开头，生成 key 时可以去掉重复前缀：
-
-```text
-src/modules/oss/oss.controller.ts        -> controllers.oss
-src/modules/oss/oss-bucket.controller.ts -> controllers.ossBucket
-```
-
-不要生成成：
-
-```ts
-controllers.oss.oss
-controllers.oss.ossBucket
-```
-
-这样业务侧调用会更自然，也更适合在不同路由层复用。
+# Agent 维护说明
+
+这份文档给 Codex、Claude 或其他代码代理阅读，用来说明维护 `jax-hono` 时的默认规则。
+
+## 本地 link 规则
+
+`jax-hono` 是用户自己维护的框架，常通过 `jax link` 链接到业务工程的 `node_modules/jax-hono`。
+
+如果在业务工程中需要修改 `jax-hono` 行为，先检查依赖是否已经 link 到本地源码目录。不要把它当成一次性的第三方 `node_modules` 临时补丁。
+
+在 Windows PowerShell 中，可以在业务仓库根目录查找所有 `jax-hono` 依赖：
+
+```powershell
+Get-ChildItem -Path . -Directory -Recurse -Filter jax-hono |
+  Where-Object { $_.FullName -match '\\node_modules\\jax-hono$' } |
+  Format-List LinkType,Target,FullName
+```
+
+如果 `LinkType` 是 `Junction` 或 `SymbolicLink`，直接修改 `Target` 指向的 `jax-hono` 源码目录。
+
+如果没有 link，先执行：
+
+```powershell
+jax link
+```
+
+然后再次确认 link 状态，再修改框架源码。
+
+## 修改生成器后的验证
+
+修改 `build/generate-registry.ts`、`build/generate-config.ts` 等生成逻辑后，需要在使用方工程里重新生成。
+
+常见命令：
+
+```powershell
+bun run setup
+```
+
+然后检查业务工程中的生成结果，例如：
+
+```text
+.jax-hono/controllers.generated.ts
+.jax-hono/models.generated.ts
+.jax-hono/services.generated.ts
+.jax-hono/middlewares.generated.ts
+.jax-hono/plugins.generated.ts
+.jax-hono/index.ts
+```
+
+如果业务仓库里有多个工程都依赖 `jax-hono`，分别查看各工程的 `package.json`，运行它们自己的 setup/build 命令。
+
+`.jax-hono` 只属于调用项目，不要在 `jax-hono` 包目录里创建或维护 `generated` / `.jax-hono` Junction。需要 `bun --compile` 的项目推荐用 setup 包裹 Bun 构建命令：
+
+```powershell
+bun node_modules/jax-hono/setup.ts src/index.ts -- bun build src/index.ts --compile --production --target=bun-windows-x64 --outfile dist/app.exe
+```
+
+setup 会在执行命令期间临时把入口文件里对 `jax-hono` 的导入切到项目生成入口，命令结束后恢复源码。真正的编译参数交给 `bun build` 自己处理。
+
+业务入口仍然从框架导入：
+
+```ts
+import { config, createApp } from 'jax-hono';
+```
+
+这样 Bun 才能在编译时把生成模块放进可执行文件；运行时动态查找 `.jax-hono/*.ts` 只能作为开发态兜底，旧 `generated/*.ts` 仅作为兼容路径。
+
+运行时除当前 `cwd` 外，也会根据 Bun 入口脚本位置向上查找 `.jax-hono`。这可以兼容 PM2 配成父目录 `cwd`、脚本指向子项目入口的情况；但仍推荐把 PM2 `cwd` 配到具体项目根。
+
+## 插件生成约定
+
+生成器只扫描已启用插件。插件启用来源包括：
+
+- `jax-hono/plugins/config.ts`
+- 使用方工程的 `src/config/plugin.ts`
+
+未启用插件不应进入生成结果，避免构建解析未启用插件的运行时依赖。
+
+已启用插件中的约定文件会进入生成器：
+
+- `*.controller.ts` 注册到 `controllers` 根对象
+- `*.service.ts` 注册到 `services.generated.ts`
+- `*.cron.ts` 注册到 `crons.generated.ts`，由框架统一启动/停止
+
+例如启用插件 `foo` 后：
+
+```text
+plugins/foo/foo.controller.ts
+plugins/foo/foo-cache.service.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+可生成：
+
+```ts
+controllers.foo
+service.fooCache
+```
+
+Cron 文件可以使用 `defineCron`：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'foo-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
+## Controller 注册约定
+
+生成器需要保持不同命名空间的边界清晰：
+
+- `*.backend.ts` 注册到 `controllers.backend`
+- `*.api.ts` 注册到 `controllers.api`
+- `*.open.ts` 注册到 `controllers.open`
+- `*.client.ts` 注册到 `controllers.client`
+- `*.controller.ts` 注册到 `controllers` 根对象
+
+`.controller.ts` 表示通用 Controller，供 backend/api/open/client 等不同路由复用，不应自动归入 `controllers.backend`。
+
+例如：
+
+```text
+src/modules/oss/oss.controller.ts
+src/modules/oss/oss-bucket.controller.ts
+```
+
+应生成：
+
+```ts
+controllers.oss
+controllers.ossBucket
+```
+
+如果需要后台专用 Controller，使用：
+
+```text
+src/modules/foo/foo.backend.ts
+```
+
+应生成：
+
+```ts
+controllers.backend.foo
+```
+
+## 模块路径命名
+
+模块内文件名如果以模块目录名开头，生成 key 时可以去掉重复前缀：
+
+```text
+src/modules/oss/oss.controller.ts        -> controllers.oss
+src/modules/oss/oss-bucket.controller.ts -> controllers.ossBucket
+```
+
+不要生成成：
+
+```ts
+controllers.oss.oss
+controllers.oss.ossBucket
+```
+
+这样业务侧调用会更自然，也更适合在不同路由层复用。