create-next-imagicma 0.1.15 → 0.2.1

package/README.md

@@ -4,6 +4,7 @@
 
 ## 模版源
 
+- `../nextjs-app`
 - `../hono-app`
 如果要修改模版，请修改源头，然后执行 `pnpm run sync-template` 同步到当前模版目录，切记不可直接修改当前模版目录。
 ## 使用
@@ -49,6 +50,7 @@ pnpm run sync-template
 
 默认同步：
 
+- `../nextjs-app` -> `template/`
 - `../hono-app` -> `template-hono/`
 
 可通过环境变量覆盖：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-imagicma",
-  "version": "0.1.15",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "create-next-imagicma": "./bin/create-next-imagicma.mjs"

package/template-hono/.env.example

@@ -1,18 +1,10 @@
 # 复制为 .env.local 后按需覆盖（.env.local 不会被提交）
 #
-# 必填：PostgreSQL 连接串
-# DATABASE_URL="postgresql://postgres:password@127.0.0.1:5432/hono_app"
+# 数据库类型：默认 sqlite，可切换为 postgres
+# DB_TYPE="sqlite"
 #
-# AI 网关配置
-# 可选：提供商，支持 openai / openai-compatible / minimax / kimi
-# AI_PROVIDER="minimax"
-# 必填：模型访问密钥
-# AI_API_KEY="<your-api-key>"
-# 可选：自定义网关地址；minimax / kimi 留空时会自动使用官方兼容地址
-# AI_BASE_URL="https://api.minimaxi.com/v1"
-# 可选：模型 ID；未设置时默认 gpt-4o-mini
-# AI_MODEL="MiniMax-M2.7"
+# 当 DB_TYPE=sqlite 时，可选：自定义 SQLite 文件位置；默认使用 ./.data/app.db
+# DATABASE_FILE="./.data/app.db"
 #
-# 兼容旧变量名：
-# OPENAI_API_KEY="<your-api-key>"
-# OPENAI_BASE_URL="https://api.openai.com/v1"
+# 当 DB_TYPE=postgres 时，填写 Postgres 连接串
+# DATABASE_URL="postgres://user:pass@localhost:5432/mydb"

package/template-hono/.imagicma/AGENTS.md

@@ -0,0 +1,7 @@
+
+## 开发规则
+
+- `/.imagicma/port.json` 是初始化生成的锁定端口文件，禁止修改。
+- 禁止修改 `scripts/` 下的受保护启动文件：`imagicma-common.mjs`、`imagicma-guard.mjs`、`imagicma-dev.mjs`、`imagicma-start.mjs`。
+- 禁止修改 `package.json` 中 `scripts.dev` 与 `scripts.start`（以及对应 `predev`、`prestart`）命令。
+- 禁止直接执行 `vite` 或 `node dist/server/index.js` 启动项目；只能通过 `pnpm dev` / `pnpm start` 启动。

package/template-hono/AGENTS.md

@@ -1,128 +1,99 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-
-This is a `Hono + Vite + React` app designed for enterprise-level product development. Keep browser code in `client/src`, server entrypoints in `server/`, and shared contracts in `shared/`.
-
-### Documentation Structure (Design Phase)
-All design artifacts are stored under `docs/designer/`:
-
-- `docs/designer/project_state.json`: project state and version tracking
-- `docs/designer/prd/prd.md`: Product Requirements Document
-- `docs/designer/persona/persona_*.md`: user personas (one file per persona)
-- `docs/designer/feature_plan/`: feature module planning
-  - `feature_modules.md`: module list, relationship diagrams, and shared/common components (may contain full details if ≤4 modules)
-  - `feature_module_[name].md`: detailed module specifications for large apps (pages, layouts, components, business rules, and navigation)
-- `docs/designer/style_guide/*.style-guide.md`: visual design guidelines
-- `docs/designer/db/`: database schema documentation
-  - `db_schema.md`: global ER diagram and module index
-  - `db_schema_[module].md`: per-module database schemas
-
-### Application Code Structure
-- `client/src/pages/`: route-level pages (e.g., `home.tsx`)
-- `client/src/components/`: reusable UI components, with shadcn/ui primitives under `components/ui/`
-- `client/src/lib/` and `client/src/hooks/`: client utilities and custom hooks
-- `client/src/main.tsx`: frontend entry point
-- `client/src/App.tsx`: React Router configuration
-- `client/src/globals.css`: global styles
-- `client/public/`: static assets
-- `server/app.ts`: Hono application entry point
-- `server/routes/`: route registration only; bind paths and hand off to controllers
-- `server/middlewares/`: cross-cutting HTTP middleware such as auth, request-id, logging, and rate-limit
-- `server/controllers/`: HTTP layer; parse requests, call repositories/lib, and map errors to responses
-- `server/repositories/`: data access only; wrap Drizzle/SQL queries
-- `server/db/`: database client and database-level infrastructure
-- `server/lib/`: external integrations and reusable backend helpers
-- `server/env.ts`: environment loading and config validation
-- `shared/routes.ts` and `shared/schema.ts`: Zod-backed API contracts and shared schema
-- `scripts/`: guarded dev/start scripts; do not bypass them
-- `.env.local`: local runtime secrets such as `DATABASE_URL`; do not commit it
-
-**Critical**: The homepage must never ship blank. `client/src/pages/home.tsx` should render visible, meaningful content on first load, not hidden placeholders or empty shells.
-
-## Development Preparation
-
-Before starting development, agents must confirm the database connection with the user by using `question`. Ask for the PostgreSQL connection string that should be used locally, for example:
-
-- `DATABASE_URL="postgresql://postgres:password@127.0.0.1:5432/hono_app"`
-
-Do not assume the database host, port, username, password, or database name. After the user confirms the value, place it in `.env.local` (or ensure it is already available in the environment) before running database-related work such as `pnpm db:push`, server development, or any feature that depends on persistence.
-
-## Build, Test, and Development Commands
-
-- `restart_workflow`: required agent entrypoint for restarting dev services; do not call `pnpm dev` directly
-- `pnpm build`: builds the client with Vite and compiles the server with `tsc`
-- `pnpm start`: runs the production server through the guarded startup script
-- `pnpm check`: TypeScript type-check for both client and server configs
-- `pnpm lint`: runs ESLint across the repository
-- `pnpm db:push`: applies Drizzle schema changes to the PostgreSQL database from `DATABASE_URL`
-
-### AI Feature Rule
-- If you are developing AI-related features in this template, you must use the `ai-feature` skill before implementation.
-
-## Coding Style & Naming Conventions
-
-Use TypeScript and ESM throughout. Follow the existing style: 2-space indentation, double quotes, semicolons, and trailing commas. Prefer:
-
-- PascalCase for React components (e.g., `HelloClient.tsx`)
-- kebab-case for route/page files (e.g., `not-found.tsx`)
-- snake_case for database schema files (e.g., `db_schema_user.md`)
-- Colocate logic in `hooks/`, `lib/`, and `routes/` before creating new top-level folders
-
-Reuse the `@/` import alias for client code where it improves readability.
-
-### Backend Layering Rules
-- Backend request flow must follow `routes -> middlewares -> controllers -> repositories -> db`.
-- `routes/` may define paths and middleware, but must not contain business logic or direct database access.
-- `middlewares/` are for cross-cutting concerns such as auth, request-id, logging, and rate-limit; they may read/write Hono Context and short-circuit requests when needed.
-- Auth-related checks should be implemented as middleware and mounted in `routes/`, not reimplemented inside controllers.
-- `controllers/` may read/write HTTP details, call repositories or `lib/`, and map errors, but must not contain SQL.
-- `repositories/` own database reads/writes only and must not shape HTTP responses.
-- `db/` is limited to connection setup, schema wiring, and database infrastructure helpers.
-- `lib/` is for external providers or shared backend utilities; routes should reach it through middleware or controllers, not directly.
-- Controllers should consume auth context that middleware has already prepared instead of parsing tokens again.
-- New backend features should default to adding files along the same chain: route, middleware when needed, controller, repository.
-- Do not mock backend data for feature development. Implement against real backend flows, real repositories, and real interfaces unless the user explicitly asks for a temporary test double.
-
-### Shared Schema Rules
-- Always split shared schema by business module in `shared/schema/*.ts`, not by individual table.
-- `shared/schema.ts` must remain the unified export entry so existing imports and Drizzle config stay stable.
-- Each schema module should contain the tables, Zod schema exports, and inferred TS types for that module.
-- Avoid one-file-per-table unless the user explicitly asks for it or a single module is exceptionally large.
-
-### Design Documentation Standards
-- All Mermaid diagrams must NOT include styling elements (no style definitions, classDef, linkStyle or fill colors)
-- Use basic graph syntax only: `graph TD`/`graph TB` for architecture, and `erDiagram` for schemas
-- File naming must strictly follow the patterns defined in File Structure section
-
-### Technical Selection Policy
-Technical selection is strictly an engineering responsibility, governed globally:
-- When evaluating complex system requirements (e.g., OCR, Payments, AI integrations, Auth), propose solutions contrasting self-built vs. commercial options.
-- Strip away meaningless basic scaffolding choices; focus squarely on domain-specific system blockers.
-- When human input is mandatory to finalize a route, translate technical jargon into business dimensions for the stakeholders: "Development Time, Cost, and Product Experience".
-- Final architectural decisions must be persisted into `docs/designer/tech_design/tech_design.md`.
-
-## Testing & Quality Assurance
-
-Before opening a PR, complete manual verification to ensure the application is usable end to end.
-
-If you add tests, keep them as `*.test.ts` or `*.test.tsx`, or add a `tests/` folder and document the new command in `package.json`.
-
-### Manual Verification Checklist
-- All API endpoints work correctly
-- All pages are accessible without 404 errors
-- All buttons are clickable and trigger the expected behavior
-- All links navigate to the correct destination
-
-## Commit & Pull Request Guidelines
-
-Recent history uses Conventional Commit prefixes such as `feat:`, `fix:`, and `chore:`; keep that format and write concise subjects. PRs should include:
-
-- a short description of behavior changes
-- linked issue or task when available
-- screenshots or recordings for UI changes
-- notes for env, port, or database-impacting changes
-
-## Runtime & Configuration Notes
-
-Agents must use `restart_workflow` instead of invoking `pnpm dev` manually. Do not pass a port on the command line or by prefixing `pnpm dev` with `PORT=...`; keep runtime port configuration in `.imagicma/runtime.env`. Database access must come from `DATABASE_URL` in `.env.local` (or process env), and secrets must never be committed.
+# 项目 Agent 指南（Hono + Vite + React + TypeORM）
+
+默认使用中文沟通与输出（除非用户明确要求其他语言）。
+
+## 目标
+
+交付可运行、可预览、可验证、可演示的完整应用。
+
+## 技术栈与约束
+
+- 框架：Hono（Node runtime）+ Vite（单进程开发）
+- 前端：React 19 + React Router + Tailwind v4 + shadcn/ui
+- 请求层：React Query + fetch
+- 契约：Zod（`shared/contracts/routes.ts`，兼容 `shared/routes.ts` re-export）
+- 数据库：TypeORM（默认 `DB_TYPE=sqlite` + `./.data/app.db`；切到 Postgres 时使用 `DB_TYPE=postgres` + `DATABASE_URL`）
+
+## 目录约定
+
+```text
+client/
+  index.html                 # Vite 前端入口 HTML
+  public/                    # 前端静态资源
+  src/                       # 前端应用入口、页面、Provider、错误边界
+    components/ui/           # shadcn/ui 组件
+    hooks/                   # 客户端 hooks
+    lib/                     # 通用工具（含 app-metadata.ts，生成项目后优先修改应用名/title）
+
+server/
+  app.ts                     # Hono 装配入口，仅负责注册 middleware、routes、静态资源
+  routes/                    # 路由绑定层，只做 URL 到 controller 的映射
+  controllers/               # HTTP 适配层，解析请求并返回响应
+  middlewares/               # 日志、异常等横切能力
+  models/
+    entities/                # TypeORM entity 等持久化模型
+    repositories/            # 数据库访问实现，只回答“怎么查、怎么存”
+    services/                # 业务规则与编排，只回答“为什么这么查、怎么处理结果”
+  db/                        # DataSource 与数据库配置
+
+shared/
+  contracts/                 # 前后端共享 API path 与 Zod 契约
+  types/                     # 前后端共享纯 TypeScript 类型
+  constants/                 # 前后端共享纯常量
+```
+
+- `shared/`：禁止放 TypeORM entity、Node API、Hono Context 与其他仅服务端可运行的代码
+
+## 常用命令
+
+- `pnpm dev`：单进程开发（Vite + Hono dev middleware）
+- `pnpm build`：构建前端并编译 server
+- `pnpm start`：生产启动
+- `pnpm check`：类型检查
+- `pnpm lint`：ESLint
+
+## 执行硬规则
+
+- 数据库 entity 与运行时连接配置必须保持一致，禁止手写临时 SQL 与 ORM entity 并行漂移。
+- 当任务涉及数据库选型且用户未明确指定时，必须优先使用 `question tool` 询问使用什么数据库；仅在无法询问或未获得明确答复时，才按默认 `sqlite`（`DB_TYPE=sqlite` + `./.data/app.db`）处理。
+- 禁止修改 `scripts/` 下的受保护启动文件：`imagicma-common.mjs`、`imagicma-guard.mjs`、`imagicma-dev.mjs`、`imagicma-start.mjs`、`imagicma-runtime-logs.mjs`。
+- 禁止修改 `package.json` 中 `scripts.dev` 与 `scripts.start`（以及对应 `predev`、`prestart`）命令。
+- 禁止直接执行 `vite` 或 `node dist/server/index.js` 或 `pnpm dev` 或 `pnpm start` 启动项目；只能通过 `restart_workflow` 启动。
+- 禁止主动注入环境变量到 `process.env`。
+- 端口契约只允许使用大写 `PORT`。
+- 运行时端口读取顺序固定为：外部环境变量 `PORT` -> 项目内 `.imagicma/runtime.env`。
+- 预览地址规则固定为 `https://{port}.preview.imagicma.cn`，其中 `port` 为实际启动端口。
+
+## 状态文件写入规则
+
+- 若维护 `docs/project_state.json`，每次写入前先读取最新版本。
+- 若写入报冲突（文件已变更），必须重新读取后重试，不得忽略。
+- `quality_gates.typecheck=true` 仅在构建命令真实通过后设置。
+
+## UI 质量门禁（必须全部满足）
+
+- `/` 路由必须可访问并落到首页组件。
+- `client/src/pages/home.tsx` 不允许为空文件、空组件，或仅返回 `null` / 空白占位；首页必须渲染可见内容。
+- 接入真实业务时，应将 `/` 首页替换为真实业务内容，不要长期保留模板默认文案或空白首页。
+- 视觉风格必须明确：字体、颜色、间距、动效要统一。
+- 必须定义可复用设计 token（颜色、圆角、阴影、间距等级）。
+- 至少覆盖桌面与移动端关键断点，不允许内容溢出。
+- 交互状态完整：hover/focus/disabled/loading/error/success。
+- 列表增删改状态建议加入轻量动效（如 `framer-motion` 的入场/退出），并提供失败反馈（toast 或 inline alert）。
+
+## 数据与安全
+
+- API 响应必须经过 `shared/contracts/routes.ts`（或 `shared/routes.ts` re-export）的 Zod schema 校验。
+- 优先复用 `client/src/components/ui` 与 `client/src/hooks`，避免重复造轮子。
+
+## 完成标准
+
+只有以下全部满足才允许结束：
+
+- `pnpm build` 通过（无 pnpm 时 `npm run build` 通过）
+- 页面可在本地端口访问并完成核心流程
+- `/` 首页路由可访问
+- 关键日志无阻塞级错误
+- UI 达到可演示级（非“功能可用但观感粗糙”）
+- 按钮可点击
+- 页面跳转后正常打开，非404

package/template-hono/README.md

@@ -1,153 +1,121 @@
 # hono-app
 
-基于 **Hono + Vite + React** 的全栈应用。
+基于 **Hono + Vite + React** 的全栈模板，目标是在保留前端开发体验的同时，提供更轻量的 Node 运行时方案。
 
 ## 技术栈
 
 - 前端：React 19、React Router、Tailwind CSS v4、shadcn/ui、React Query
 - 后端：Hono（Node runtime）
-- 数据层：Drizzle ORM + PostgreSQL（默认通过 `DATABASE_URL` 连接）
-- AI 网关：Vercel AI SDK 5（`ai` + `@ai-sdk/openai` + `@ai-sdk/openai-compatible`）
-- 校验契约：Zod（`shared/routes.ts`）
-
-## 目录结构（重点）
-
-- `client/index.html`：前端入口 HTML
-- `client/public/`：前端静态资源
-- `client/src/components/ui/`：shadcn/ui 组件
-- `client/src/hooks/`：前端 hooks
-- `client/src/lib/`：前端通用工具
-- `server/`：Hono 后端入口与路由
-- `shared/`：前后端共享契约与 schema
-
-## AI 网关基础设施
-
-模板已内置最薄的 AI 基础设施，不带默认业务页面：
-
-- 服务端统一入口：`POST /api/ai/chat`
-- 服务端默认架构：Hono API -> Vercel AI SDK -> OpenAI / OpenAI 兼容模型
-- 当前默认支持的小文件附件类型：`image/*`、`text/*`、`application/pdf`
-- 附件限制：最多 3 个文件，总大小不超过 5MB，且必须以内联 data URL 提交
+- 数据层：TypeORM（默认 `sqlite`，支持切换 `postgres`）
+- 契约校验：Zod（`shared/contracts/routes.ts`，兼容 `shared/routes.ts` re-export）
+
+## 目录结构
+
+```text
+.
+├── .imagicma/
+│   ├── AGENTS.md                 # 运行/修改约束补充说明
+│   └── runtime.env               # 项目运行端口契约，仅使用大写 PORT
+├── client/
+│   ├── index.html                # Vite 前端入口 HTML
+│   ├── public/                   # 前端静态资源
+│   └── src/
+│       ├── App.tsx               # 前端应用根组件
+│       ├── main.tsx              # 前端挂载入口
+│       ├── globals.css           # 全局样式与设计 token
+│       ├── components/           # 页面级与基础组件
+│       │   └── ui/               # shadcn/ui 组件
+│       ├── hooks/                # 客户端 hooks
+│       ├── lib/                  # 前端通用工具与预览桥接逻辑
+│       └── pages/                # 路由页面
+├── server/
+│   ├── app.ts                    # Hono 装配入口，仅注册 middleware、routes、静态资源
+│   ├── dev-app.ts                # 开发态 server 入口
+│   ├── index.ts                  # 生产态 server 入口
+│   ├── controllers/             # HTTP 适配层，解析请求并返回响应
+│   ├── db/                      # DataSource 与数据库配置
+│   ├── middlewares/             # 日志、异常等横切能力
+│   ├── models/
+│   │   ├── entities/            # TypeORM entity 等持久化模型
+│   │   ├── repositories/        # 数据访问实现
+│   │   ├── services/            # 业务规则与编排
+│   │   └── types/               # 仅服务端内部使用的类型
+│   └── routes/                  # 路由绑定层，只做 URL 到 controller 的映射
+├── shared/
+│   ├── constants/               # 前后端共享纯常量
+│   ├── contracts/               # 前后端共享 API path 与 Zod 契约
+│   ├── routes.ts                # contracts 的兼容 re-export
+│   ├── schema.ts                # 共享 schema 聚合导出
+│   └── types/                   # 前后端共享纯 TypeScript 类型
+├── scripts/                     # 受保护的启动/守卫脚本
+├── .env.example                 # 环境变量示例
+├── package.json
+├── tsconfig.json
+├── tsconfig.server.json
+└── vite.config.ts
+```
 
-推荐做法：
+## 分层约束
 
-- 前端页面调用项目内 `/api/ai/chat`
-- 不要把模型密钥暴露到浏览器
-- 需要聊天 UI 时，优先使用 `@ai-sdk/react` 的 `useChat` / `DefaultChatTransport` 对接服务端 UI message stream
-- 如果暂时不引入 `@ai-sdk/react`，请复用 `client/src/lib/ai-ui-stream.ts`，不要手写 SSE 解析器
-- OpenAI 官方走 `AI_PROVIDER=openai`
-- MiniMax / Kimi 这类 OpenAI 兼容供应商，优先走 `AI_PROVIDER=minimax|kimi` 或 `openai-compatible`
+- `server/routes` 只能依赖 `controllers`
+- `server/controllers` 只负责 HTTP 适配，依赖 `models` 与 `shared`
+- `server/models/repositories` 只负责数据读写，不返回 HTTP 响应结构
+- `server/models/services` 负责业务规则、聚合与默认值，不接触 Hono `Context`
+- `shared/` 只能放前后端都能安全复用的契约、常量和纯类型，禁止放 TypeORM entity、Node API、Hono 运行时代码
 
-## 开发
+## 常用命令
 
 ```bash
 pnpm install
-start_app.sh
+pnpm dev
+pnpm build
+pnpm start
+pnpm check
+pnpm lint
 ```
 
+- `pnpm dev`：本地开发，使用受保护脚本拉起 Vite + Hono
+- `pnpm build`：构建前端并编译服务端
+- `pnpm start`：以生产模式启动构建产物
+- `pnpm check`：执行前后端 TypeScript 类型检查
+- `pnpm lint`：执行 ESLint
+
+如果你是在 imagicma 的 agent/workflow 环境中维护该模板，请继续遵循 [`AGENTS.md`](/Users/alexliu/Project/imagicma-all/imagicma-template/hono-app/AGENTS.md) 的约束，通过工作流提供的启动入口执行，不要绕过 `scripts/` 里的受保护脚本。
+
+## 端口与运行时文件
+
 启动时按以下顺序解析端口：
 
 1. 显式环境变量 `PORT`
 2. 项目内 `.imagicma/runtime.env`
 
-如果两者都不存在，启动会直接失败。
-项目内唯一允许的端口文件是 `.imagicma/runtime.env`，内容示例：
+如果两者都不存在，启动会直接失败。`.imagicma/runtime.env` 示例：
 
 ```bash
 PORT=6424
 ```
 
-请勿直接执行 `vite` 或 `pnpm dev` 启动，必须使用 `restart_workflow`。
-
-- `build` 产出：
-  - 前端：`dist/client`
-  - 后端：`dist/server`
-- `start`：由受保护脚本启动服务（禁止直接 `node dist/server/index.js`），并由 Hono 承载 API + 静态资源 + SPA fallback。
-- 生产启动同样按 `PORT -> .imagicma/runtime.env` 的顺序解析端口。
-
-## 数据库
-
-首次运行前初始化结构：
-
-```bash
-pnpm db:push
-```
-
-- 请先复制 `.env.example` 为 `.env.local`
-- 在 `.env.local` 中设置 `DATABASE_URL`
-- `pnpm db:push` 会将 schema 推送到该 PostgreSQL 数据库
-
-## AI 配置
-
-请在 `.env.local` 中配置：
-
-- `AI_PROVIDER`：可选；支持 `openai`、`openai-compatible`、`minimax`、`kimi`
-- `AI_API_KEY`：必填
-- `AI_BASE_URL`：可选；接 OpenAI 兼容网关时填写。`minimax` / `kimi` 留空时自动走官方默认地址
-- `AI_MODEL`：可选；默认 `gpt-4o-mini`
-
-兼容说明：
-
-- 旧变量 `OPENAI_API_KEY` / `OPENAI_BASE_URL` 仍然可用，但新项目建议改用通用命名的 `AI_*`
-- `minimax` 与 `kimi` 默认都走 OpenAI 兼容模式，不需要额外改代码
-- 如果接其它兼容供应商，使用 `AI_PROVIDER=openai-compatible` 并填写 `AI_BASE_URL`
-
-模板内置的 AI 路由会优先读取这些环境变量，再由服务端统一调用模型供应商。
+## 构建产物
 
-补充说明：
+- 前端产物：`dist/client`
+- 后端产物：`dist/server`
 
-- `/api/ai/chat` 返回的是 AI SDK 5 的 UI message stream（SSE `data:` 事件，不是旧的 `0:"..."` 文本流）
-- 如果模型网关不可达，优先检查 `AI_BASE_URL`、网络连通性与服务商侧配置
+生产启动时由 Hono 同时承载 API、静态资源与 SPA fallback。
 
-最小请求示例：
-
-```bash
-curl -N \
-  -X POST http://127.0.0.1:6424/api/ai/chat \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "messages": [
-      {
-        "role": "user",
-        "parts": [
-          { "type": "text", "text": "请用一句话介绍这个项目的 AI 网关职责。" }
-        ]
-      }
-    ]
-  }'
-```
-
-常见配置示例：
+## 数据库
 
-```bash
-# OpenAI 官方
-AI_PROVIDER=openai
-AI_API_KEY=<your-openai-key>
-AI_MODEL=gpt-4o-mini
-
-# MiniMax
-AI_PROVIDER=minimax
-AI_API_KEY=<your-minimax-key>
-AI_MODEL=MiniMax-M2.7
-
-# Kimi
-AI_PROVIDER=kimi
-AI_API_KEY=<your-kimi-key>
-AI_MODEL=kimi-k2.5
-
-# 其它 OpenAI 兼容供应商
-AI_PROVIDER=openai-compatible
-AI_API_KEY=<your-provider-key>
-AI_BASE_URL=https://api.provider.com/v1
-AI_MODEL=<provider-model-id>
-```
+服务启动时会自动同步当前示例表结构。
 
-## 运行时文件
+- 默认数据库：`DB_TYPE=sqlite`
+- 默认数据库文件：`./.data/app.db`
+- 自定义 SQLite 路径：复制 `.env.example` 为 `.env.local` 后设置 `DATABASE_FILE`
+- 切换 Postgres：
+  - `DB_TYPE=postgres`
+  - `DATABASE_URL=postgres://user:pass@host:5432/dbname`
 
-- `.imagicma/runtime.env`：项目运行端口契约，只使用大写 `PORT`
+数据库类型建议在项目首次启动前确定；初始化后默认按固定配置处理，不承诺无损切换。
 
 ## 验证路径
 
 - API：`GET /api/greeting`
-- AI：`POST /api/ai/chat`
-- 页面：`/hello`
+- 页面：`/`

package/template-hono/client/index.html

@@ -3,7 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>hono-app</title>
+    <link rel="icon" type="image/png" href="/favicon.png" />
+    <title>Agentma App · Powered by agentma.cn</title>
     <script src="/imagicma-picker-bridge.js"></script>
     <script src="/imagicma-preview-feedback.js"></script>
   </head>

package/template-hono/client/public/imagicma-picker-bridge.js

@@ -3,11 +3,7 @@
   var VERSION = 1;
   var MAX_TEXT_LENGTH = 240;
   var MAX_SELECTOR_LENGTH = 512;
-  var PROD_PARENT_ORIGINS = {
-    'https://agentma.cn': true,
-    'https://imagicma.cn': true,
-    'https://nanocoda.com': true,
-  };
+  var PROD_PARENT_ORIGIN = 'https://imagicma.cn';
   var LOCAL_PARENT_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/i;
   var LOCAL_IMAGICMA_PARENT_RE = /^https?:\/\/([a-z0-9-]+\.)?local\.imagicma\.cn(:\d+)?$/i;
 
@@ -25,7 +21,7 @@
 
   function isAllowedParentOrigin(origin) {
     if (!origin) return false;
-    return !!PROD_PARENT_ORIGINS[origin] || LOCAL_PARENT_RE.test(origin) || LOCAL_IMAGICMA_PARENT_RE.test(origin);
+    return origin === PROD_PARENT_ORIGIN || LOCAL_PARENT_RE.test(origin) || LOCAL_IMAGICMA_PARENT_RE.test(origin);
   }
 
   function isRecord(value) {

package/template-hono/client/public/imagicma-preview-feedback.js

@@ -4,7 +4,6 @@
   var PROD_PARENT_ORIGINS = {
     'https://agentma.cn': true,
     'https://imagicma.cn': true,
-    'https://nanocoda.com': true
   };
   var LOCAL_PARENT_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/i;
   var LOCAL_IMAGICMA_PARENT_RE = /^https?:\/\/([a-z0-9-]+\.)?local\.(agentma\.cn|imagicma\.cn)(:\d+)?$/i;

package/template-hono/client/src/components/HelloClient.tsx

@@ -62,7 +62,7 @@ function EnvHint() {
   return (
     <div className="text-sm text-muted-foreground">
       <p>
-        默认使用 PostgreSQL。若 API 报错，请先在 <code>.env.local</code> 设置 <code>DATABASE_URL</code>，再执行 <code>pnpm db:push</code> 初始化数据库。
+        默认使用 <code>DB_TYPE=sqlite</code> 和 <code>./.data/app.db</code>，服务启动时会自动同步示例表。若要切到 Postgres，可在 <code>.env.local</code> 设置 <code>DB_TYPE=postgres</code> 和 <code>DATABASE_URL</code>；数据库类型建议在首次启动前确定。
       </p>
     </div>
   );