soma-ai

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

页面生成链

业务意图 + 已授权接口
→ 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（真实凭据放 ai.config.<env>.local.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、 发布交接、组件橱窗）；第二部分助手工具体系。

测试

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