create-hile - npm Package Compare versions

Comparing version 2.1.1 to 3.0.0

AI.md

+# AI Guide For create-hile
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Scaffold Hile applications and monorepos from maintained templates.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Scaffold a new project | `create-hile` | `packages/create-hile.md`, `recipes/new-project-scaffold.md` |
+
+
+
+# create-hile
+
+Package: `create-hile`.
+
+## Copy-Paste Example
+
+Create a project:
+
+```bash
+npx create-hile create my-app
+cd my-app
+pnpm install
+pnpm run dev
+```
+
+Skip dependency install:
+
+```bash
+npx create-hile create my-app --skip-install
+```
+
+## More Examples
+
+Template choices:
+
+```text
+default          HTTP API with @hile/http
+next             Next.js + Hile controllers on one port
+micro-http       Microservice plus HTTP endpoint
+micro            Pure microservice
+micro-http-next  Next.js + microservice + HTTP
+monorepo         Lerna + pnpm workspace
+```
+
+Generated default HTTP shape:
+
+```text
+src/
+  controllers/
+    index.controller.ts
+  services/
+    index.boot.ts
+```
+
+## Use When
+
+Use `create-hile` when starting a new Hile application or workspace.
+
+## Do Not Use When
+
+- Do not use generated templates as the final architecture for complex apps without introducing models, services, and context boundaries.
+- Do not trust stale template README files if they mention unrelated application domains; regenerate or rewrite them from current template files.
+
+## Install
+
+Usually no install is needed:
+
+```bash
+npx create-hile create my-app
+```
+
+## Imports
+
+The CLI entrypoint exports a `create` command. Application code does not import `create-hile`.
+
+## Compose With
+
+- Generated apps use `@hile/cli` for `hile start`.
+- HTTP templates use `@hile/core` and `@hile/http`.
+- Next templates use `@hile/http-next` and `@hile/model`.
+- Micro templates use `@hile/micro` and `@hile/message-loader`.
+
+## Runtime And Lifecycle Notes
+
+- Templates use `_env`, `_env.prod`, and `_gitignore`; creation renames them to dotfiles.
+- The CLI prompts for a template and optional dependency installation.
+- The package manager preference is `pnpm`, then `yarn`, then `npm`.
+
+## Anti-Patterns
+
+- Leaving template package versions stale after publishing new Hile packages.
+- Shipping template READMEs copied from unrelated projects.
+- Starting production without running the build command required by the selected template.
+
+## Verification Checklist
+
+- New project has `"type": "module"`.
+- Dev script runs `hile start --dev`.
+- Production script runs `hile start` after build.
+- Boot files default-export `defineService(...)`.
+
+
+
+# Related Recipes
+
+
+
+# New Project Scaffold
+
+## Complete Example
+
+```bash
+npx create-hile create orders-api
+cd orders-api
+pnpm install
+pnpm run dev
+```
+
+Default HTTP controller:
+
+```ts
+// src/controllers/index.controller.ts
+import { defineController } from '@hile/http'
+
+export default defineController('GET', async () => {
+  return { ok: true }
+})
+```
+
+Default HTTP boot:
+
+```ts
+// src/services/index.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
+
+export default defineService('http', async (shutdown) => {
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
+})
+```
+
+## File Layout
+
+```text
+orders-api/
+  src/controllers/index.controller.ts
+  src/services/index.boot.ts
+  package.json
+  .env
+```
+
+## User Intent
+
+Use this recipe when the user wants a new Hile app or template guidance.
+
+## Packages To Use
+
+- `create-hile`
+- Template-selected Hile packages
+
+## Implementation Steps
+
+1. Choose a template by app shape.
+2. Make sure scripts use `hile start --dev` for development.
+3. Keep boot files under `src/**`.
+4. Add models when domain logic grows beyond a sample controller.
+
+## Failure And Cleanup Behavior
+
+- Generated apps rely on `@hile/cli` to find boot files and call container shutdown.
+- Production needs build output under `dist`.
+
+## Verification Checklist
+
+- `package.json` has `"type": "module"`.
+- `pnpm run dev` starts `hile start --dev`.
+- Boot file registers server close function.
+- Template README matches the selected template, not an unrelated app.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

templates/monorepo/README.md

+# Hile Monorepo Template
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+Use this template for a pnpm workspace containing multiple Hile packages or services.
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+## Try It
+
+Create packages with the included workspace scripts, then run build/test from the root.
+
+## Main Packages
+
+- `lerna`
+- `pnpm workspaces`
+- `@hile/* packages as needed`
+
+## Project Shape
+
+```text
+src/
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
+```
+
+## Boundaries
+
+- Keep package boundaries explicit and avoid sharing runtime singletons through random imports.
+- Each runnable package should expose boot files and lifecycle cleanup.
+- Add package-level `AI.md` files when publishing reusable Hile packages.
+
+## AI Context
+
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

package.json

 {
   "name": "create-hile",
   "description": "Create a new Hile project",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "type": "module",
@@ -12,2 +12,3 @@ "bin": {
     "README.md",
+    "AI.md",
     "templates"
@@ -36,3 +37,3 @@ ],
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }

README.md

 # create-hile
 
-基于内置模板的 Hile 项目脚手架：交互选择模板后，一条命令复制完整工程并写好 `package.json` 项目名。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 内置模板
+Scaffold Hile applications and monorepos from maintained templates.
 
-| 目录名 | 说明 |
-|--------|------|
-| `default` | 默认 Hile + HTTP |
-| `next` | Next.js + `@hile/http-next` 全栈 |
-| `micro-http` | `@hile/micro` + HTTP |
-| `micro` | 独立 Micro 服务 |
-| `micro-http-next` | Next.js + Micro + HTTP |
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-模板仓库内部分环境文件以 **`_env`、`_env.prod`、`_gitignore`** 命名；创建项目时会自动重命名为 **`.env`、`.env.prod`、`.gitignore`**。
+## When To Use
 
-## 使用方式
+Use `create-hile` when starting a new Hile application or workspace.
 
+## Install
+
 ```bash
-# 推荐：通过 npx 直接运行
 npx create-hile create my-app
-
-# 或全局安装后使用
-npm i -g create-hile
-create-hile create my-app
 ```
 
-按提示选择模板与是否安装依赖。完成后：
+## Copy-Paste Example
 
+Create a project:
+
 ```bash
+npx create-hile create my-app
 cd my-app
-pnpm install   # 若创建时未选安装依赖
-pnpm run dev   # 具体脚本以该模板的 package.json 为准
+pnpm install
+pnpm run dev
 ```
 
-## 生成的项目结构（`next` 模板示例）
+Skip dependency install:
 
-```text
-my-app/
-├── public/                    # 静态资源
-│   ├── next.svg
-│   ├── vercel.svg
-│   └── ...
-├── src/
-│   ├── app/
-│   │   ├── layout.tsx         # Next.js 根布局
-│   │   ├── page.tsx           # Next.js 首页
-│   │   ├── page.module.css    # 页面样式
-│   │   ├── globals.css        # 全局样式
-│   │   └── click.tsx          # Client 组件示例
-│   ├── controllers/
-│   │   └── post.controller.ts # API 示例 → GET /-/post
-│   ├── models/
-│   │   ├── home/
-│   │   │   └── home.model.ts  # 首页 defineModel（export default）
-│   │   └── post/
-│   │       └── post.model.ts  # /-/post defineModel（export default）
-│   └── services/
-│       └── index.boot.ts      # 服务启动入口（*.boot 须在 src/services/）
-├── next.config.ts
-├── tsconfig.json               # Node.js 编译
-├── tsconfig.next.json          # Next.js 编译
-├── eslint.config.mjs
-└── package.json
+```bash
+npx create-hile create my-app --skip-install
 ```
 
-业务数据与 **`loadModel`** / **`defineModel`** 以 **`packages/http-next/SKILL.md`** 为准：**`src/models/<领域>/*.model.ts`**（**`export default`**）；**`app` / `controllers` / `services`** 仅 **`loadModel`** 消费 model；**`page.tsx`** 使用 **`loadModel`** 须 **`export const dynamic = "force-dynamic"`**；**`controllers`** 可 **`loadService`**；**`app`** **禁止** **`loadService`**。
+## Boundaries
 
-## 生成项目的可用命令
+- Do not use generated templates as the final architecture for complex apps without introducing models, services, and context boundaries.
+- Do not trust stale template README files if they mention unrelated application domains; regenerate or rewrite them from current template files.
 
-| 命令 | 说明 |
-|------|------|
-| `pnpm run dev` | 构建 Next.js 并以开发模式启动 Hile 服务（以模板为准） |
-| `pnpm run build` | 编译 TypeScript 与 Next.js 生产构建 |
-| `pnpm run start` | 以生产模式启动 Hile 服务 |
+- Leaving template package versions stale after publishing new Hile packages.
+- Shipping template READMEs copied from unrelated projects.
+- Starting production without running the build command required by the selected template.
 
-## 技术栈（`next` 类模板）
+## Verify
 
-生成的项目基于以下依赖（其他模板可能包含 `@hile/micro` 等而不含 Next）：
+- New project has `"type": "module"`.
+- Dev script runs `hile start --dev`.
+- Production script runs `hile start` after build.
+- Boot files default-export `defineService(...)`.
 
-- **@hile/core** — 异步服务容器
-- **@hile/http** — Koa + find-my-way HTTP 框架
-- **@hile/http-next** — Next.js 桥接层
-- **@hile/cli** — 命令行启动器（`hile start`）
-- **Next.js 16** — React 服务端渲染与 App Router
-- **React 19** — UI 渲染
+## More Context
 
-## License
-
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

templates/default/README.md

@@ -1,197 +0,42 @@
-# Edvance
+# Hile HTTP API Template
 
-基于 [Hile](https://github.com/cevio/hile) 与 [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/overview) 的海关走私案调查助手：支持多模态输入（文本 + 图片）、按需加载技能（Skills），用于证据识别、案情分析与结构化输出。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 技术栈
+Use this template for a small Koa-style API backed by `@hile/core` and `@hile/http`.
 
-- **运行时**: Node.js (ESM)
-- **服务容器**: [@hile/core](https://www.npmjs.com/package/@hile/core)
-- **HTTP**: [@hile/http](https://www.npmjs.com/package/@hile/http)（Koa + bodyparser）
-- **Agent**: [deepagents](https://www.npmjs.com/package/deepagents) + [LangChain](https://js.langchain.com/) + [@langchain/openai](https://www.npmjs.com/package/@langchain/openai)
-- **数据**: [@hile/typeorm](https://www.npmjs.com/package/@hile/typeorm) + MongoDB（按需）
+## Quick Start
 
-## 环境要求
-
-- Node.js >= 20
-- pnpm（推荐）
-
-## 环境变量
-
-在项目根目录创建 `.env`，或通过 `--env-file` 指定：
-
-| 变量 | 说明 |
-|------|------|
-| `HTTP_PORT` | HTTP 服务端口，默认示例 `9527` |
-| `AI_API_KEY` | 大模型 API Key（兼容 OpenAI 的厂商均可） |
-| `AI_API_URL` | 大模型 API Base URL（如阿里云 DashScope 兼容地址） |
-| `AI_MODEL` | 模型名称（如 `qwen3.5-plus`） |
-
-可选（TypeORM/MongoDB）：
-
-- `TYPEORM_TYPE` / `TYPEORM_HOST` / `TYPEORM_PORT` / `TYPEORM_DATABASE` / `TYPEORM_SYNCHRONIZE`（`true` 时开启自动同步表结构）等
-
-## 安装与运行
-
 ```bash
 pnpm install
-pnpm run build
-pnpm run dev    # 开发：--dev --env-file .env
-# 或
-pnpm run start  # 生产
+pnpm run dev
 ```
 
-服务默认监听 `http://127.0.0.1:9527`（以 `HTTP_PORT` 为准）。
+## Try It
 
-## 项目结构
+curl http://localhost:5173/
 
-```
-edvance/
-├── src/
-│   ├── services/
-│   │   ├── index.boot.ts        # HTTP 服务启动（*.boot 须在 src/services/）
-│   │   └── agent.service.ts     # Deep Agent 定义（模型、backend、skills、tools）
-│   ├── controllers/          # 路由控制器
-│   │   ├── index.controller.ts
-│   │   ├── agent.controller.ts                 # POST /agent
-│   │   ├── evidence-types.controller.ts        # GET /evidence-types
-│   │   └── evidence-data/[id]/index.controller.ts # GET /evidence-data/:id
-│   ├── entities/
-│   │   ├── evidence-type.entity.ts
-│   │   └── customs-inspection-record.entity.ts
-│   ├── tools/
-│   │   ├── console.tool.ts
-│   │   └── mongodb-store.tool.ts # MongoDB 落库工具 mongodb_store
-│   └── utils/
-│       └── image.ts            # 多模态消息构建（文本 + 图片）
-├── system_prompts/
-│   └── SOUL.md                 # 系统提示词（海关走私案调查专员）
-├── skills/                     # Agent 技能（SKILL.md + frontmatter）
-│   └── smuggle-image-evidence-json/
-│       ├── SKILL.md
-│       └── schemas/
-│           └── customs_inspection_record.json
-├── .env
-├── package.json
-└── README.md
-```
+## Main Packages
 
-## API
+- `@hile/core`
+- `@hile/http`
+- `@hile/cli`
 
-### `GET /`
+## Project Shape
 
-健康检查。
-
-**响应示例：**
-
-```json
-{
-  "ok": true,
-  "message": "Hello from hile"
-}
+```text
+src/
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
 ```
 
----
+## Boundaries
 
-### `POST /agent`
+- `src/services/index.boot.ts` defines the HTTP service and registers `shutdown(close)`.
+- `src/controllers/index.controller.ts` default-exports a `defineController(...)` route.
+- Load controllers before `listen()` when adding new boot files.
 
-与海关调查助手对话，支持纯文本或文本 + 图片（多模态）。
+## AI Context
 
-**请求体（JSON）：**
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `message` | string | 是* | 用户问题或指令 |
-| `images` | array | 否 | 图片列表，用于识图分析 |
-
-\* 若提供 `images`，可省略 `message`，将自动使用「请根据图片内容进行分析。」
-
-**图片项格式（`images[]`）：**
-
-- `{ "path": "/服务端本地绝对路径/to/image.jpg" }`
-- 支持：`.jpg` / `.jpeg` / `.png` / `.gif` / `.webp`
-
-**响应：** 助手回复的纯文本（或序列化后的内容）。
-
-**示例：**
-
-```bash
-curl -X POST http://127.0.0.1:9527/agent \
-  -H "Content-Type: application/json" \
-  -d '{"message": "请识别这张单据类型并提取关键字段"}'
-```
-
----
-
-### `GET /evidence-types`
-
-列出所有证据类型。
-
-**响应类型：**
-
-```json
-[
-  { "id": "string", "name": "string" }
-]
-```
-
-**响应示例：**
-
-```json
-[
-  { "id": "customs_inspection_record", "name": "查验记录单" },
-  { "id": "other_evidence", "name": "其他证据" }
-]
-```
-
----
-
-### `GET /evidence-data/:id`
-
-按类型 `id` 查询该类型下所有已入库数据。
-
-**路径参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `id` | string | 是 | 证据类型 ID（如 `customs_inspection_record`） |
-
-**响应示例：**
-
-```json
-[
-  {
-    "id": "66e7...",
-    "typeId": "customs_inspection_record",
-    "typeName": "查验记录单",
-    "data": { "declaration_no": "3104..." },
-    "extra": { "notes": "..." },
-    "sourceImages": ["/workspace/a.jpg"],
-    "createdAt": "2026-03-02T10:00:00.000Z",
-    "updatedAt": "2026-03-02T10:00:00.000Z"
-  }
-]
-```
-
-**错误响应：**
-
-- 未提供 `id`：`400 { "error": "请提供类型 id" }`
-- 数据库未连接：`500 { "error": "MongoDB 连接未就绪" }`
-
-## 系统提示词与技能
-
-- **SOUL**（`system_prompts/SOUL.md`）：固定角色为「海关走私案调查专员」，负责证据识别、整理、分析、归档与案情回答，并遵守以证据为准、表述严谨、边界意识等准则。
-- **Skills**（`skills/*/SKILL.md`）：Deep Agent 从 `/skills/` 按需加载，每个技能为一份带 YAML frontmatter（`name`、`description`）的 Markdown，用于证据解析、字段提取、类型分类/生成、证据存储等能力扩展。
-- **工具**：当前提供 `mongodb_store`，用于将证据结构化结果写入 MongoDB。会维护类型集合 `evidence_types` 与数据集合 `customs_inspection_records`（见 `smuggle-image-evidence-json` 技能约定）。
-
-## 脚本说明
-
-| 命令 | 说明 |
-|------|------|
-| `pnpm run build` | 编译 TypeScript |
-| `pnpm run dev` | 开发模式启动（带 .env） |
-| `pnpm run start` | 生产模式启动（`hile start`） |
-| `pnpm run agent` | 运行示例 Agent 脚本（需先 build，见 `dist/agent/weather.example.js`） |
-
-## License
-
-ISC
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

templates/micro-http-next/README.md

@@ -1,7 +0,9 @@
-# Hile + Next.js
+# Hile Micro + HTTP + Next.js Template
 
-基于 [Hile](https://github.com/cevio/hile) 与 Next.js 的全栈项目。API 路由（`/-` 前缀）与页面路由共享同一端口。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 快速开始
+Use this template for a full-stack app that also participates in microservice discovery.
 
+## Quick Start
+
 ```bash
@@ -12,28 +14,32 @@ pnpm install
 
-浏览器打开 [http://localhost:3000](http://localhost:3000)。示例 API：`curl http://localhost:3000/-/post`。
+## Try It
 
-## 常用命令
+curl http://localhost:3000/-/post
 
-| 命令 | 说明 |
-|------|------|
-| `pnpm run dev` | 构建 Next.js 并以开发模式启动 Hile 服务 |
-| `pnpm run build` | 编译 TypeScript 与 Next.js 生产构建 |
-| `pnpm run start` | 生产模式启动（需先执行 `pnpm run build`） |
+## Main Packages
 
-## 项目结构
+- `@hile/http-next`
+- `@hile/micro`
+- `@hile/model`
+- `@hile/core`
+- `@hile/cli`
 
-```
+## Project Shape
+
+```text
 src/
-├── app/                 # Next.js App Router（禁止 loadService / defineModel）
-├── controllers/         # *.controller.ts → 默认 GET /-/…（可 loadService / loadModel）
-├── models/              # <领域>/*.model.ts：单文件 export default defineModel
-└── services/            # *.boot.ts | *.service.ts（*.boot 由 CLI 自启动）
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
 ```
 
-- **`src/services/index.boot.ts`**：`HttpNext` 与 **`cwd`**（见 **`packages/http-next/SKILL.md`**）。
-- **`src/models/<领域>/*.model.ts`**：领域数据；**`src/app/page.tsx`** 示范 **`loadModel`** + **`export const dynamic = "force-dynamic"`**（凡 **`page.tsx`** 使用 **`loadModel`** 时强制）。
-- **`src/controllers/post.controller.ts`**：示范 **`loadModel(postModel, …)`**。
+## Boundaries
 
-**`loadService`** 仅可在 **`src/services`**、**`src/models`**、**`src/controllers`** 中使用，**禁止**在 **`src/app`**。
+- Use `@hile/http-next` for page/API sharing and `@hile/micro` for service-to-service RPC.
+- Keep durable jobs in `@hile/redis-stream-queue`; micro pub/sub is not a queue.
+- Keep context values JSON-serializable when they cross process boundaries.
 
-详见 **`packages/http-next/SKILL.md`** 与 [Hile 文档](https://pulian.mintlify.app/packages/http-next)。
+## AI Context
+
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

templates/micro-http/README.md

@@ -1,197 +0,44 @@
-# Edvance
+# Hile Micro + HTTP Template
 
-基于 [Hile](https://github.com/cevio/hile) 与 [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/overview) 的海关走私案调查助手：支持多模态输入（文本 + 图片）、按需加载技能（Skills），用于证据识别、案情分析与结构化输出。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 技术栈
+Use this template when a service needs both HTTP endpoints and micro RPC handlers.
 
-- **运行时**: Node.js (ESM)
-- **服务容器**: [@hile/core](https://www.npmjs.com/package/@hile/core)
-- **HTTP**: [@hile/http](https://www.npmjs.com/package/@hile/http)（Koa + bodyparser）
-- **Agent**: [deepagents](https://www.npmjs.com/package/deepagents) + [LangChain](https://js.langchain.com/) + [@langchain/openai](https://www.npmjs.com/package/@langchain/openai)
-- **数据**: [@hile/typeorm](https://www.npmjs.com/package/@hile/typeorm) + MongoDB（按需）
+## Quick Start
 
-## 环境要求
-
-- Node.js >= 20
-- pnpm（推荐）
-
-## 环境变量
-
-在项目根目录创建 `.env`，或通过 `--env-file` 指定：
-
-| 变量 | 说明 |
-|------|------|
-| `HTTP_PORT` | HTTP 服务端口，默认示例 `9527` |
-| `AI_API_KEY` | 大模型 API Key（兼容 OpenAI 的厂商均可） |
-| `AI_API_URL` | 大模型 API Base URL（如阿里云 DashScope 兼容地址） |
-| `AI_MODEL` | 模型名称（如 `qwen3.5-plus`） |
-
-可选（TypeORM/MongoDB）：
-
-- `TYPEORM_TYPE` / `TYPEORM_HOST` / `TYPEORM_PORT` / `TYPEORM_DATABASE` / `TYPEORM_SYNCHRONIZE`（`true` 时开启自动同步表结构）等
-
-## 安装与运行
-
 ```bash
 pnpm install
-pnpm run build
-pnpm run dev    # 开发：--dev --env-file .env
-# 或
-pnpm run start  # 生产
+pnpm run dev
 ```
 
-服务默认监听 `http://127.0.0.1:9527`（以 `HTTP_PORT` 为准）。
+## Try It
 
-## 项目结构
+curl http://localhost:5173/
 
-```
-edvance/
-├── src/
-│   ├── services/
-│   │   ├── index.boot.ts        # HTTP 服务启动（*.boot 须在 src/services/）
-│   │   └── agent.service.ts     # Deep Agent 定义（模型、backend、skills、tools）
-│   ├── controllers/          # 路由控制器
-│   │   ├── index.controller.ts
-│   │   ├── agent.controller.ts                 # POST /agent
-│   │   ├── evidence-types.controller.ts        # GET /evidence-types
-│   │   └── evidence-data/[id]/index.controller.ts # GET /evidence-data/:id
-│   ├── entities/
-│   │   ├── evidence-type.entity.ts
-│   │   └── customs-inspection-record.entity.ts
-│   ├── tools/
-│   │   ├── console.tool.ts
-│   │   └── mongodb-store.tool.ts # MongoDB 落库工具 mongodb_store
-│   └── utils/
-│       └── image.ts            # 多模态消息构建（文本 + 图片）
-├── system_prompts/
-│   └── SOUL.md                 # 系统提示词（海关走私案调查专员）
-├── skills/                     # Agent 技能（SKILL.md + frontmatter）
-│   └── smuggle-image-evidence-json/
-│       ├── SKILL.md
-│       └── schemas/
-│           └── customs_inspection_record.json
-├── .env
-├── package.json
-└── README.md
-```
+## Main Packages
 
-## API
+- `@hile/core`
+- `@hile/http`
+- `@hile/micro`
+- `@hile/message-loader`
+- `@hile/cli`
 
-### `GET /`
+## Project Shape
 
-健康检查。
-
-**响应示例：**
-
-```json
-{
-  "ok": true,
-  "message": "Hello from hile"
-}
+```text
+src/
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
 ```
 
----
+## Boundaries
 
-### `POST /agent`
+- Keep transport adapters thin and put reusable logic in `@hile/model` models.
+- Use idempotency for HTTP or RPC handlers that can retry side effects.
+- Register both HTTP close functions and micro stop functions with `shutdown`.
 
-与海关调查助手对话，支持纯文本或文本 + 图片（多模态）。
+## AI Context
 
-**请求体（JSON）：**
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `message` | string | 是* | 用户问题或指令 |
-| `images` | array | 否 | 图片列表，用于识图分析 |
-
-\* 若提供 `images`，可省略 `message`，将自动使用「请根据图片内容进行分析。」
-
-**图片项格式（`images[]`）：**
-
-- `{ "path": "/服务端本地绝对路径/to/image.jpg" }`
-- 支持：`.jpg` / `.jpeg` / `.png` / `.gif` / `.webp`
-
-**响应：** 助手回复的纯文本（或序列化后的内容）。
-
-**示例：**
-
-```bash
-curl -X POST http://127.0.0.1:9527/agent \
-  -H "Content-Type: application/json" \
-  -d '{"message": "请识别这张单据类型并提取关键字段"}'
-```
-
----
-
-### `GET /evidence-types`
-
-列出所有证据类型。
-
-**响应类型：**
-
-```json
-[
-  { "id": "string", "name": "string" }
-]
-```
-
-**响应示例：**
-
-```json
-[
-  { "id": "customs_inspection_record", "name": "查验记录单" },
-  { "id": "other_evidence", "name": "其他证据" }
-]
-```
-
----
-
-### `GET /evidence-data/:id`
-
-按类型 `id` 查询该类型下所有已入库数据。
-
-**路径参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `id` | string | 是 | 证据类型 ID（如 `customs_inspection_record`） |
-
-**响应示例：**
-
-```json
-[
-  {
-    "id": "66e7...",
-    "typeId": "customs_inspection_record",
-    "typeName": "查验记录单",
-    "data": { "declaration_no": "3104..." },
-    "extra": { "notes": "..." },
-    "sourceImages": ["/workspace/a.jpg"],
-    "createdAt": "2026-03-02T10:00:00.000Z",
-    "updatedAt": "2026-03-02T10:00:00.000Z"
-  }
-]
-```
-
-**错误响应：**
-
-- 未提供 `id`：`400 { "error": "请提供类型 id" }`
-- 数据库未连接：`500 { "error": "MongoDB 连接未就绪" }`
-
-## 系统提示词与技能
-
-- **SOUL**（`system_prompts/SOUL.md`）：固定角色为「海关走私案调查专员」，负责证据识别、整理、分析、归档与案情回答，并遵守以证据为准、表述严谨、边界意识等准则。
-- **Skills**（`skills/*/SKILL.md`）：Deep Agent 从 `/skills/` 按需加载，每个技能为一份带 YAML frontmatter（`name`、`description`）的 Markdown，用于证据解析、字段提取、类型分类/生成、证据存储等能力扩展。
-- **工具**：当前提供 `mongodb_store`，用于将证据结构化结果写入 MongoDB。会维护类型集合 `evidence_types` 与数据集合 `customs_inspection_records`（见 `smuggle-image-evidence-json` 技能约定）。
-
-## 脚本说明
-
-| 命令 | 说明 |
-|------|------|
-| `pnpm run build` | 编译 TypeScript |
-| `pnpm run dev` | 开发模式启动（带 .env） |
-| `pnpm run start` | 生产模式启动（`hile start`） |
-| `pnpm run agent` | 运行示例 Agent 脚本（需先 build，见 `dist/agent/weather.example.js`） |
-
-## License
-
-ISC
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

templates/micro/README.md

@@ -1,197 +0,43 @@
-# Edvance
+# Hile Microservice Template
 
-基于 [Hile](https://github.com/cevio/hile) 与 [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/overview) 的海关走私案调查助手：支持多模态输入（文本 + 图片）、按需加载技能（Skills），用于证据识别、案情分析与结构化输出。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 技术栈
+Use this template for registry-backed RPC or streaming services without an HTTP API.
 
-- **运行时**: Node.js (ESM)
-- **服务容器**: [@hile/core](https://www.npmjs.com/package/@hile/core)
-- **HTTP**: [@hile/http](https://www.npmjs.com/package/@hile/http)（Koa + bodyparser）
-- **Agent**: [deepagents](https://www.npmjs.com/package/deepagents) + [LangChain](https://js.langchain.com/) + [@langchain/openai](https://www.npmjs.com/package/@langchain/openai)
-- **数据**: [@hile/typeorm](https://www.npmjs.com/package/@hile/typeorm) + MongoDB（按需）
+## Quick Start
 
-## 环境要求
-
-- Node.js >= 20
-- pnpm（推荐）
-
-## 环境变量
-
-在项目根目录创建 `.env`，或通过 `--env-file` 指定：
-
-| 变量 | 说明 |
-|------|------|
-| `HTTP_PORT` | HTTP 服务端口，默认示例 `9527` |
-| `AI_API_KEY` | 大模型 API Key（兼容 OpenAI 的厂商均可） |
-| `AI_API_URL` | 大模型 API Base URL（如阿里云 DashScope 兼容地址） |
-| `AI_MODEL` | 模型名称（如 `qwen3.5-plus`） |
-
-可选（TypeORM/MongoDB）：
-
-- `TYPEORM_TYPE` / `TYPEORM_HOST` / `TYPEORM_PORT` / `TYPEORM_DATABASE` / `TYPEORM_SYNCHRONIZE`（`true` 时开启自动同步表结构）等
-
-## 安装与运行
-
 ```bash
 pnpm install
-pnpm run build
-pnpm run dev    # 开发：--dev --env-file .env
-# 或
-pnpm run start  # 生产
+pnpm run dev
 ```
 
-服务默认监听 `http://127.0.0.1:9527`（以 `HTTP_PORT` 为准）。
+## Try It
 
-## 项目结构
+Start a registry, then start this service and call it through `Application.call(...)`.
 
-```
-edvance/
-├── src/
-│   ├── services/
-│   │   ├── index.boot.ts        # HTTP 服务启动（*.boot 须在 src/services/）
-│   │   └── agent.service.ts     # Deep Agent 定义（模型、backend、skills、tools）
-│   ├── controllers/          # 路由控制器
-│   │   ├── index.controller.ts
-│   │   ├── agent.controller.ts                 # POST /agent
-│   │   ├── evidence-types.controller.ts        # GET /evidence-types
-│   │   └── evidence-data/[id]/index.controller.ts # GET /evidence-data/:id
-│   ├── entities/
-│   │   ├── evidence-type.entity.ts
-│   │   └── customs-inspection-record.entity.ts
-│   ├── tools/
-│   │   ├── console.tool.ts
-│   │   └── mongodb-store.tool.ts # MongoDB 落库工具 mongodb_store
-│   └── utils/
-│       └── image.ts            # 多模态消息构建（文本 + 图片）
-├── system_prompts/
-│   └── SOUL.md                 # 系统提示词（海关走私案调查专员）
-├── skills/                     # Agent 技能（SKILL.md + frontmatter）
-│   └── smuggle-image-evidence-json/
-│       ├── SKILL.md
-│       └── schemas/
-│           └── customs_inspection_record.json
-├── .env
-├── package.json
-└── README.md
-```
+## Main Packages
 
-## API
+- `@hile/micro`
+- `@hile/message-loader`
+- `@hile/core`
+- `@hile/cli`
 
-### `GET /`
+## Project Shape
 
-健康检查。
-
-**响应示例：**
-
-```json
-{
-  "ok": true,
-  "message": "Hello from hile"
-}
+```text
+src/
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
 ```
 
----
+## Boundaries
 
-### `POST /agent`
+- Message handlers live in `src/messages` and default-export `defineMessage(...)`.
+- `Application.call()` returns a promise; do not append a secondary response getter.
+- Use `@hile/redis-stream-queue` instead when work must be durable.
 
-与海关调查助手对话，支持纯文本或文本 + 图片（多模态）。
+## AI Context
 
-**请求体（JSON）：**
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `message` | string | 是* | 用户问题或指令 |
-| `images` | array | 否 | 图片列表，用于识图分析 |
-
-\* 若提供 `images`，可省略 `message`，将自动使用「请根据图片内容进行分析。」
-
-**图片项格式（`images[]`）：**
-
-- `{ "path": "/服务端本地绝对路径/to/image.jpg" }`
-- 支持：`.jpg` / `.jpeg` / `.png` / `.gif` / `.webp`
-
-**响应：** 助手回复的纯文本（或序列化后的内容）。
-
-**示例：**
-
-```bash
-curl -X POST http://127.0.0.1:9527/agent \
-  -H "Content-Type: application/json" \
-  -d '{"message": "请识别这张单据类型并提取关键字段"}'
-```
-
----
-
-### `GET /evidence-types`
-
-列出所有证据类型。
-
-**响应类型：**
-
-```json
-[
-  { "id": "string", "name": "string" }
-]
-```
-
-**响应示例：**
-
-```json
-[
-  { "id": "customs_inspection_record", "name": "查验记录单" },
-  { "id": "other_evidence", "name": "其他证据" }
-]
-```
-
----
-
-### `GET /evidence-data/:id`
-
-按类型 `id` 查询该类型下所有已入库数据。
-
-**路径参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `id` | string | 是 | 证据类型 ID（如 `customs_inspection_record`） |
-
-**响应示例：**
-
-```json
-[
-  {
-    "id": "66e7...",
-    "typeId": "customs_inspection_record",
-    "typeName": "查验记录单",
-    "data": { "declaration_no": "3104..." },
-    "extra": { "notes": "..." },
-    "sourceImages": ["/workspace/a.jpg"],
-    "createdAt": "2026-03-02T10:00:00.000Z",
-    "updatedAt": "2026-03-02T10:00:00.000Z"
-  }
-]
-```
-
-**错误响应：**
-
-- 未提供 `id`：`400 { "error": "请提供类型 id" }`
-- 数据库未连接：`500 { "error": "MongoDB 连接未就绪" }`
-
-## 系统提示词与技能
-
-- **SOUL**（`system_prompts/SOUL.md`）：固定角色为「海关走私案调查专员」，负责证据识别、整理、分析、归档与案情回答，并遵守以证据为准、表述严谨、边界意识等准则。
-- **Skills**（`skills/*/SKILL.md`）：Deep Agent 从 `/skills/` 按需加载，每个技能为一份带 YAML frontmatter（`name`、`description`）的 Markdown，用于证据解析、字段提取、类型分类/生成、证据存储等能力扩展。
-- **工具**：当前提供 `mongodb_store`，用于将证据结构化结果写入 MongoDB。会维护类型集合 `evidence_types` 与数据集合 `customs_inspection_records`（见 `smuggle-image-evidence-json` 技能约定）。
-
-## 脚本说明
-
-| 命令 | 说明 |
-|------|------|
-| `pnpm run build` | 编译 TypeScript |
-| `pnpm run dev` | 开发模式启动（带 .env） |
-| `pnpm run start` | 生产模式启动（`hile start`） |
-| `pnpm run agent` | 运行示例 Agent 脚本（需先 build，见 `dist/agent/weather.example.js`） |
-
-## License
-
-ISC
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

templates/next/README.md

@@ -1,7 +0,9 @@
-# Hile + Next.js
+# Hile Next.js Template
 
-基于 [Hile](https://github.com/cevio/hile) 与 Next.js 的全栈项目。API 路由（`/-` 前缀）与页面路由共享同一端口。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 快速开始
+Use this template when Next.js pages and Hile API controllers should share one port.
 
+## Quick Start
+
 ```bash
@@ -12,28 +14,32 @@ pnpm install
 
-浏览器打开 [http://localhost:3000](http://localhost:3000)。示例 API：`curl http://localhost:3000/-/post`。
+## Try It
 
-## 常用命令
+curl http://localhost:3000/-/post
 
-| 命令 | 说明 |
-|------|------|
-| `pnpm run dev` | 构建 Next.js 并以开发模式启动 Hile 服务 |
-| `pnpm run build` | 编译 TypeScript 与 Next.js 生产构建 |
-| `pnpm run start` | 生产模式启动（需先执行 `pnpm run build`） |
+## Main Packages
 
-## 项目结构
+- `@hile/http-next`
+- `@hile/http`
+- `@hile/model`
+- `@hile/core`
+- `@hile/cli`
 
-```
+## Project Shape
+
+```text
 src/
-├── app/                 # Next.js App Router（禁止 loadService / defineModel）
-├── controllers/         # *.controller.ts → 默认 GET /-/…（可 loadService / loadModel）
-├── models/              # <领域>/*.model.ts：单文件 export default defineModel
-└── services/            # *.boot.ts | *.service.ts（*.boot 由 CLI 自启动）
+  controllers/   # HTTP controllers when the template exposes HTTP
+  messages/      # message handlers when the template exposes micro RPC
+  models/        # reusable business logic when present
+  services/      # *.boot.ts files loaded by hile start
 ```
 
-- **`src/services/index.boot.ts`**：`HttpNext` 与 **`cwd`**（见 **`packages/http-next/SKILL.md`**）。
-- **`src/models/<领域>/*.model.ts`**：领域数据；**`src/app/page.tsx`** 示范 **`loadModel`** + **`export const dynamic = "force-dynamic"`**（凡 **`page.tsx`** 使用 **`loadModel`** 时强制）。
-- **`src/controllers/post.controller.ts`**：示范 **`loadModel(postModel, …)`**。
+## Boundaries
 
-**`loadService`** 仅可在 **`src/services`**、**`src/models`**、**`src/controllers`** 中使用，**禁止**在 **`src/app`**。
+- `HttpNext` serves public assets, `.next/static`, Hile controllers, then Next.js fallback.
+- Controllers live under `src/controllers` and are exposed below the `/-` prefix by default.
+- Do not call `loadService()` at module top level in React components.
 
-详见 **`packages/http-next/SKILL.md`** 与 [Hile 文档](https://pulian.mintlify.app/packages/http-next)。
+## AI Context
+
+For implementation details, read the root `llms-full.txt` or package-local `AI.md` files after installing dependencies.

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Number of package files

94

2.17%

Worsened metrics

Total package byte prevSize

127540

-8.29%

Number of lines in readme file

57

-37.36%

No dependency changes