本地 AI 生成 Schema（known-ai）

状态：预览。 侧车本体（known-ai.exe）已经能跑通端到端生成，四条生成任务与守卫行为都在真机上实测过，可以直接下载；llama.cpp 运行时已随安装包内置，只剩模型权重由 known-ai pull 一条命令下好，不必再手工找文件。还没上线的只有设计器里的一键接入——所以下面「下载」「pull」「启动它」「开机自启」和「它能做四件事」你现在就能照做，「谁在调用它」里的设计器自动接入要等下一个版本。

它解决的是哪一段

运行时 Schema 渲染 把页面变成了数据：一份 JSON 描述实体、字段、布局，Known 在运行时把它渲染成列表、表单和增删改查。但"手写这份 JSON"仍然有门槛——字段类型只有七种、布局只有五种、settings.columns 得用逗号分隔的字符串、枚举和 refEntity 只能引已存在的实体。这些规则不难，只是琐碎，而琐碎的事情正适合交给模型。

known-ai 干的就是这一段：把你的自然语言描述，变成一份能过校验的 Schema JSON。它不生成 .razor，不生成实体类，也不参与代码生成那条路线——产物就是一份 JSON，和你手写的完全同构，落地方式一模一样。

一句话对比：

为什么装在本地，而不是放在网站上

三个理由，都直接决定了你能免费用到什么程度：

1. 算力来自你的机器。 它在你本机拉起一个 llama-server.exe 子进程，跑一个 1.7B 的量化模型（权重约 1.28 GB，常驻内存约 2.7 GB，纯 CPU 推理）。厂商侧没有推理账单，所以不必靠调用次数回本。
2. 你的业务模型不出本机。 网站服务器上不保存用户的 Schema。侧车只绑 127.0.0.1，从不监听 0.0.0.0；生成的 JSON 直接回到你的浏览器/应用，中间没有云端存储这一站。
3. 断网也能用。 除了第一次下载权重，运行期不需要任何外部服务。策略拉取失败时按放行处理——到期与额度只会砍"生成"这个动作，绝不会砍健康检查、也不会砍你已经生成好的数据。

它能做四件事

每次请求带一个 taskKey，形状由对应的 JSON Schema 在解码层锁死——不在闭集内的取值（比如把布局写成 dashboard）根本吐不出来，这比在提示词里叮嘱有效得多。

字段类型只允许 string / int / decimal / bool / datetime / enum / ref，组件只允许 table / form / subtable / list / schema-stats / schema-chart，布局只允许 console / left-right / top-bottom / tabs / grid——与运行时渲染器实际支持的集合一一对应，没有多余选项。

权重在启动时一次性加载，实测十几秒后就绪；这期间 GET /health 会一直回 ready: false，那是"正在加载"而不是"没装好"。真正影响体验的是请求之间：四个任务的提示词有一段逐字节相同的静态前缀，第一次请求的 prompt 阶段要 1.5–2.4 s，之后命中 KV 缓存降到约 36 ms——差了近 60 倍。所以批量建模比逐个手动请求划算得多，/bootstrap 就是为此存在的。

下载

known-ai.exe 是 Native AOT 单文件产物：机器码直接写盘，解压即可运行，不需要安装 .NET 运行时，也不依赖任何随包分发的托管 DLL。llama.cpp 推理运行时（runtime\，含 llama-server.exe 及其原生 DLL）也一并打进这个包，解压后就位——双击 known-ai.exe 即可，首次运行会自动把模型权重补上。

双击就能用（首次自动补权重）

安装包里的 25.9 MB 已含侧车本体与 llama.cpp 运行时（runtime\），解压即就位。你不需要敲任何命令：

1. 把 zip 解压到任意文件夹；
2. 双击 known-ai.exe。

首次运行时本机还没有模型权重，程序会自动把它下载到安装目录同级的 data\models\（约 1.19 GB，只需这一次），进度显示在弹出的窗口里；下完自动加载，就绪后即可被 Known 应用调用。窗口保持打开＝服务在运行，关掉窗口＝停止。装机标识、激活码、试用记录、用量账本也都一并落在同级 data\——整个文件夹可以原样搬走或备份，重装系统后放回即可继续用。

装到 Program Files 等只读位置时，data\ 会自动回落到 %LOCALAPPDATA%\Known\ai\，行为不变。

下载在幕后怎么发生（也可手动）

自动下载与手动 known-ai.exe pull 走的是同一条通道，机制如下：

字节数与 SHA-256 都写死在程序里，下完必须校验通过才改名落地。候选源按本机实测吞吐排序：权重走 ModelScope（实测约 8 MB/s，1.19 GB 两分半下完），再退 hf-mirror、HuggingFace 主域。第一个源不通就自动换下一个，--source modelscope.cn 可以指定只走某一家。

• 传到一半断掉不必从头再来：.part 里留着已下载的字节，下一次用 HTTP Range 从断点续——实测在 480 MB 处续传，续完整份校验依然通过。Ctrl+C 中断同理，.part 原地保留。
• 校验失败会点名期望与实际哈希并换源，绝不会把坏文件留下续传——坏权重的症状是"输出变差"而不是报错，那是最难自查的一类故障。
• 想在气隙机上离线准备、或自动下载不便时，仍可手动执行 known-ai.exe pull（默认只补权重）；--only runtime 是修复入口，仅当内置的 runtime\ 被删或这份包被拆散时才需要；--only all 两件都重下，--force 重下已就位的文件。
• 不想要自动下载（纯云端接入、或想自己管模型）时，用 --autopull false 关掉；关掉后本机没模型就不自动下，等你在「模型管理」里手动加。

手工指定路径也仍然有效（放在别处、或多套权重切换时用）：

known-ai.exe --model D:\models\Qwen3-1.7B-Q4_K_M.gguf --runtime D:\llama.cpp

• --runtime 指向包含 llama-server.exe 的目录（llama.cpp 的 Windows 发布包即可）。
• --model 指向 gguf 权重。
• 端口不指定时用随机空闲端口，始终只绑回环；同时生成一段随机 hex 作为配对令牌。

启动完成后，端口与令牌会写进发现文件：

%LOCALAPPDATA%\Known\ai\known-ai.json
{ "port": 54321, "token": "…", "pid": 18324,
  "model": "D:\\models\\Qwen3-1.7B-Q4_K_M.gguf", "buildExpiry": null }

GET /health 不需要令牌，加载完成前返回 ready: false，之后返回 true 并带上端口。没找到权重时它不会假装可用：/health 秒回 ready: false，/generate 直接 503。

开发时让它常驻

默认每次都得有人把侧车拉起来。装成登录自启的后台任务后，开机就在那里：

known-ai.exe service install     ← 装；当前用户登录触发，不需要管理员权限
known-ai.exe service status      ← 任务装没装、侧车在不在线、模型加载好没
known-ai.exe service start       ← 手动起
known-ai.exe service stop        ← 手动停
known-ai.exe service uninstall   ← 撤销自启任务

用的是任务计划程序（在 taskschd.msc 里叫 Known AI Sidecar），不是真 Windows 服务。理由是这套东西的前提就是你的用户会话：只绑 127.0.0.1、发现文件写在你的 %LOCALAPPDATA%、配对令牌要给同一个用户的开发进程读——跑在 SYSTEM 下这三条都得重做，而 sc create 还要管理员权限。登录触发加当前用户的 SID，普通账户就能装。

几处值得先知道的行为：

• 安装时先确认权重与 llama-server.exe 是否就位，缺了会点名缺哪一样，并让你先跑 known-ai pull。
• 用 dotnet known-ai.dll 这种方式执行会被拒绝：任务里存的是绝对路径，装出来的任务会指向一个重启后不存在的位置。请用发布出来的 known-ai.exe。
• service stop / uninstall 会连同 llama-server.exe 子进程一起结束，只停任务本身的话那个约 2.8 GB 的子进程会被留在内存里。它按发现文件里的 PID 杀整棵进程树，且先确认那个端口真在应答——所以绝不会误伤你自己另起的 llama-server。
• 重复安装是覆盖同一个任务，不会攒出好几个自启项；IgnoreNew 也挡住了登录事件重放造成的双实例。
• 后台任务没有控制台，日志不落盘。要排查失败原因，先 service stop，再在前台跑一次 known-ai.exe 看输出。

谁在调用它：配对令牌

known-ai 有两个调用方，共用同一条凭据：

1. 本地应用（把它拉起来的那个进程）：启动子进程时生成令牌，经 --pair 注入；
2. 页面设计器（浏览器里的应用）：本地应用把端口 + 令牌经页面地址传进去，设计器每个请求都带一个 X-Known-Pair 请求头。

/health 与 /tasks 免检，其余路径一律校验令牌与 Origin（白名单精确匹配，不给通配符）。这套自动交接要等设计器接入上线；在那之前，你可以直接对它发 HTTP 请求试试：

curl -X POST http://127.0.0.1:54321/generate \
  -H "Content-Type: application/json" \
  -H "X-Known-Pair: <发现文件里的 token>" \
  -d '{"taskKey":"system-structure","idempotencyId":"demo-1",
       "input":{"appName":"进销存","businessHint":"管理客户、商品、采购单与销售单"}}'

existingEntities 必须是 [{ "name": "Customer", "fields": ["Code","Name"] }] 这样的对象数组——传字符串数组会被 400 挡回来，并在错误消息里点名是哪个字段。整个 existingEntities 可以省略（等于"空项目"），数组里只写 name 不写 fields 也合法，意思是"这个实体本次待定义，但允许被 ref 指向"。

另外两条会直接撞到 400 的硬规则：请求头必须是 Content-Type: application/json（curl 默认发 form-urlencoded，会被拒绝并回显它实际收到的类型）；属性名严格区分 camelCase，TaskKey 这种写法不再被大小写宽容地接受——AOT 下序列化元数据全部来自编译期生成的上下文，选项在构造时就冻结了，没有运行时反射可以兜底。形状不对的请求一律 400，错误消息里点名是哪一个字段。

对话通道：POST /chat

除了四条任务式生成，known-ai 还开放一个自由对话端点，专门给 AI 智能体抽屉 用（框架侧由 Known.AgentKit 的 KnownAiAdapter 承接）：请求体形如

{ "model": "local", "idempotencyId": "c-1",
  "messages": [
    { "role": "system",    "content": "你是一个报表助手" },
    { "role": "user",      "content": "本月销售总额" }
  ], "maxTokens": 512 }

应答体是 { ok, text?, error?, quotaReason?, usage?: { promptTokens, completionTokens }, idempotencyId }。

模型选择沿用 /generate 的规则："local" 或字段留空 → 内置 llama-server；其余值按 id 命中「自定义模型」清单里的 OpenAI 兼容后端。也就是说抽屉里点"deepseek-chat"和点"本机内置"是同一条链路，只是最后一步走的是外部 OpenAI 兼容网关还是本机 27 GB 内存里那个 1.7B——密钥与外部地址始终只在 known-ai 进程里出现，抽屉、页面、浏览器都拿不到。

对话也过同一道 IQuotaGate 闸门，账本里 taskKey 记作 chat，与四条生成任务并列可分档统计。错误分诊与 /generate 同形：empty_messages / unknown_model → 400，backend_unavailable → 503，inference_failed → 502，闸门拒 → 402。

生成失败时，四种码对应四种动作

这套区分别看起来像细节，实际上决定了用户会不会白点十次按钮：

422 和 503 尤其不能混：把"没装"显示成"再生成一次"，用户点十次也不会成功。

产物在返回给你之前会过两层处理。先做机械归一化：属性名首字母大写、ID 结尾改成 Id、与框架保留列同名的字段丢掉、重复字段去重——这些有唯一正确写法，直接改比拒绝好。再做校验：只拒绝模型自己有可能改对的问题（闭集外的取值、缺必填），其余降级成 warnings 随结果返回。校验失败的反馈会追加到提示词末尾重试，前面的静态部分保持逐字节一致，这样重试也吃得到 KV 缓存。

所以请把 warnings 显示出来，别吞掉：一个悬空的外键引用留空，比模型为了通过校验把它改指向一个"合法但语义错"的实体更容易发现。

30 天免费试用，但闸门只有一处

每个 known-ai 装机自带 30 天免费试用：首次运行时在 exe 同级的 data\trial.start 落一枚 UTC 时间戳（只读安装回落到 %LOCALAPPDATA%\Known\ai\），此后 30 天内放行生成；到期即拒绝生成，quotaReason 给 trial_expired，提示你买一份激活码导入续上。试用期内本地照常记一份只含元信息的流水——时间、任务、耗时、令牌数，不含 Schema 内容。试用只是软门禁：--trial-days 可调天数，留 0（或负数）则不设上限，回到"无授权一直能用"，仅供本地开发调试。因为锚点随 data\ 走，重装系统后把整个安装目录原样放回、试用进度也不会被清零。

整个链路只有一处判定，即"是否允许这次生成"，优先级是 在线策略 > 离线激活码 > 30 天免费试用：只要本机联网拉到过云端策略、或导入过一枚有效激活码，试用计时就自动让位——激活正是越过 30 天的既定出路。

这条边界是刻意的：授权砍的是便利，不砍数据所有权。 无论试用到期还是激活过期，砍的都只是 /generate、/chat；健康检查、模型清单、已建模系统的打开与既有数据一律照常。

离线激活：没有外网的机器也能授权

上面那条策略通道依赖一件事——机器能连上厂商。而有一类装机恰恰连不上：内网隔离、气隙机房，或干脆没配外网。这样的 known-ai 从不访问 /policy，也就永远不出现在装机登记里，管理员既看不到它、也管不到它；不激活就只能回落到内置的 30 天免费试用，一过 30 天即 trial_expired、停生成。

离线激活码是给这条路准备的补充：管理员在你的授权后台按某台机器的装机标识签发一份带有效期的凭证，你经 U 盘一类的离线介质把它带到目标机导入。它沿用的正是在线策略那套签名——一份 activation.json，内容是 { payload, sig }，用厂商私钥签、由 known-ai 内置的公钥验，与在线策略验签逐字节同规范，因此不需要任何额外的信任根。

装机标识在首次运行时自动生成并落盘，是一串 32 位十六进制：

<known-ai 安装目录>\data\install.id

（只读安装回落到 %LOCALAPPDATA%\Known\ai\install.id）

把这份文件里的标识报给管理员，对方按它签发的激活码就只认这一台机器——换到另一台机、或把 activation.json 抄去别处，导入时都会因绑机校验不过而被拒。标识现在落在 exe 同级的 data\ 里，所以重装系统后把整个安装目录（含 data\）原样放回，标识与已导入的激活码都还在、无需重签；只有清空 data\ 或把 known-ai 全新装到另一处，才会生成新标识。导入通过 POST /activation 完成（与其它生成入口一样要先过配对令牌这道守卫）：

curl -X POST http://127.0.0.1:54321/activation \
  -H "Content-Type: application/json" \
  -H "X-Known-Pair: <发现文件里的 token>" \
  --data-binary @activation.json

导入的激活码写进 exe 同级的 data\activation.json（只读安装回落到 %LOCALAPPDATA%\Known\ai\activation.json），每次启动都会重新验签并复用它，所以全程断网、反复重启都不丢。想确认当前状态可 GET /activation，它回显本机标识、是否已有激活码、是否过期、30 天免费试用的剩余天数与到期时刻，以及此刻真正生效的裁决来自哪一路（在线策略 / 离线激活 / 30 天免费试用）。

三类依据同时在场时，优先级是明确的：

几条要如实知道的边界：

• 离线授权管不了已激活的机器。 它是"离线放行"，不是"离线吊销"。一旦激活码导入生效，除非等它到期、或那台机器重新联网被在线策略封禁，否则没法隔空收回。所以给气隙机的激活码建议也设一个到期，到期前续签一份新的即可。
• 到期与生效都以 UTC 为准。 把机器时钟往前拨到激活码到期之后，同样会被判过期而停生成；拨到起始时间之前则按未生效处理。
• 砍的仍只是"生成"。 激活码过期只让 /generate、/chat 回 402，健康检查、模型清单、以及你已经生成好的数据一律照常——与"到期不砍数据所有权"是同一条红线。

相关页面

• 运行时 Schema 渲染——known-ai 的产物由它消费，字段与布局的完整规则在这一页
• 代码生成——另一条路线：产出真实的 .razor 与实体类
• 开发中心——设计器与建模入口
• AI 智能体技能——给编码智能体用的技能包，和这里给建模用的侧车是两件不同的东西