# soma-ai

SOMA 的 AI 入口包：业务意图 + 已授权接口 → 页面蓝图 → 确定性编译成原生 HTML + 封闭
Tailwind 词汇 + 唯一 SOMA DSL（闸门校验 + 自修复），外加 AI API / AI 助手服务。页面 Registry、
内存编译、按路径访问、发布与回滚由 soma-core 统一承担，soma-ai 不维护第二套页面运行壳。

## 2.0.0 运行时基线

本版本要求 Node.js `24.21.0`、Next.js `16.3.5` 与 `soma-core >=2.0.0`。助手模板和样式
由 `soma-ai` 包提供，Host 只保留配置、挂载与业务接线；没有配置时 Host 应隐藏助手入口。

## 页面生成链

```text
业务意图 + 已授权接口
→ AI 页面蓝图（只出组织意图：选哪些业务语义条目、怎么分组、绑什么数据）
→ BlueprintCompiler 确定性编译：原生 HTML + 封闭 Tailwind 词汇（颜色走 --soma-* 主题令牌）
→ soma-core 内存编译
→ Registry 发布/版本/回滚
→ 页面路径访问
```

- **生成页不渲染 soma-ui 业务组件。** 组件目录由 Host 注入，只作选型提示与契约校验资料；
  每个条目编成原生语义卡片，页面上没有组件实例。soma-ui 业务组件用于人写 / 第一方页面。
- **Tailwind 只在 soma-ai 内。** 词汇与样式表构建都归本包；Host 只加载交付的样式表，
  不安装 Tailwind。
- soma-ai 不依赖 soma-ui；可信目录由 Host 在自己的 `api/service/ai-page/Generate.ts` 里注入
  `AiPageGenerateService`（`soma-ai/host/services`），未注入时生成端点 fail-closed。

## 当前能力（以代码为准）

- **页面生成** `POST /api/ai-page/generate`，四模式：
  - `standard` / `preview`：requirement（自然语言需求）→ 蓝图 → 编译后的页面声明；
  - `visualize`：content（任意形态的结果内容）→ 选业务条目、绑数据的展示页（两段式"答→渲"链的渲段）；
  - `revise`：baseBlueprint（首选）或历史页的 baseDeclaration + instruction，会话式改页，未提及部分逐字保留。
  质量链：提示词规格书 → 蓝图编译与声明闸门 → 零 Domain 渲染冒烟 → 问题清单回喂自修复
  （闸门回喂最多三轮）→ 确定性兜底（带计量）；容错解析。
- **业务组件边界**：新页面的候选、提示目录和编译闸门只开放 `solution/page`；
  `atom/composite` 只能作为业务组件内部实现。页面骨架、区块卡片与响应式栅格只由
  BlueprintCompiler 生成。`revise` 只允许按原数量保留历史底稿已有的旧层组件。
- **页面交付**：生成服务返回 canonical 声明与服务端编译后的 compiled 资产；soma-core 负责
  Registry 发布、版本管理和页面路径渲染。
- **生成页样式表**：本包把封闭词汇预构建成只用 `--soma-*` 主题令牌着色的样式表并随包发布。
  `soma-ai/tailwind-stylesheet` 导出 CSS 文本常量 `SOMA_AI_TAILWIND_CSS`（Host 注入一个 `<style>`
  即可），`soma-ai/tailwind.css` 是同一份文件。样式表没有裸色回退，Host 必须注入 SOMA 主题令牌。
  改词汇或 `tailwind/page.css` 后执行 `npm run build:tailwind -w soma-ai` 并提交 `src/generated/`。
- **AI API / AI 助手服务**：`POST /api/ai-api/invoke`、`GET /api/ai-api/list`、
  `POST /api/ai-assistant/chat`、`GET /api/ai-assistant/knowledge/list`、
  `GET /api/ai-assistant/suggested-prompts`。
- **AI 助手挂件**：`src/html/shared/ai-assistant-widget.html` 随包发布；Host 只需 include
  该片段，再通过 `soma-ai/client` 挂载，不需要复制助手模板。
- **上游协议**：OpenAI 兼容，可接任意模型；`src/testing/ai-upstream-server.mjs` 提供 mock 上游，
  离线可跑全链路。

## 配置（凭据归宿主所有）

宿主 `config/ai.config.<env>.yaml`（每个环境只读取同名文件，勿提交真实凭据）：

```yaml
apiKey: your-api-key
baseUrl: https://your-openai-compatible-endpoint
model: your-model        # 生成链需强制 tool_choice:deepseek 系用 deepseek-chat(v4-flash 不支持,会 400)
```

无 AI 配置时 AI 端点返回 `4501`。运行时覆盖（如助手图标）走宿主 `config/app.config.<env>.yaml`
的 `aiHost.assistant.icon`。

## 文档

- `doc/soma AI 链详设.md` — 第一部分页面生成链（四模式 API、目录检索、蓝图编译与闸门、revise、
  发布交接、组件橱窗）；第二部分助手工具体系。

## 测试

```bash
npm test -w soma-ai                 # 先跑 verify:tailwind（样式表新鲜度），再跑 vitest
npm run build:tailwind -w soma-ai   # 重建生成页样式表（src/generated/）
npm run typecheck -w soma-ai
npm run lint -w soma-ai
```