feat(ql3): establish 3.0 incubation baseline

2026-09-20 16:07:11 +08:00 · 2026-08-12 00:25:26 +08:00
parent 4bf92dcfeb
commit c699c32461
2817 changed files with 779642 additions and 653 deletions
@@ -0,0 +1,81 @@
+# 本机 Plugin Package Prompt
+
+`ql3-prompt` 在 Edge/Standalone 上一次性执行已经安装、materialize 并发布的 Plugin Package
+Prompt。它不是 scheduler 或 daemon；每条命令只打开一个 SQLite authority，完成 Model Gateway
+drain 后退出。
+
+## 前置条件
+
+1. 本机数据库已完成 AI optional migration，且 `ql3-ai-feature` 当前为 `active`；
+2. Prompt 所属 Package 当前 active、未 quarantine，automation publication 中存在目标 Prompt；
+3. 当前强 User 同时具有 Project 的 `run.start`、`model.invoke` 与 `secret.use`；
+4. Provider token 已通过 `ql3-secret` 写入该 Project，并通过 `ql3-model-credential` 绑定到 Provider；
+5. Secret keyring 和 Owner credential 均位于 deployment root 内的私有路径；
+6. Provider endpoint/policy manifest 是 canonical JSON regular file，当前 UID 所有，完成配置后改为
+   `0400` 或 `0440`，不得包含 token、SecretRef 或 authorization header。
+
+Provider manifest 使用 schema `qinglong/projected-model-gateway-authority@v1`，只声明 Provider
+type/base URL、响应字节上限和 Project 模型 Policy。它不是 credential authority；实际 token 在每次
+模型请求时由 durable binding 和加密 Secret 重新解析。
+
+## 执行命令
+
+命令文件必须是 deployment root 的后代、当前 UID 所有且 mode `0600`：
+
+```json
+{
+  "schemaVersion": 1,
+  "operation": "prompt.execute",
+  "options": {
+    "deploymentRoot": "/opt/qinglong3",
+    "databasePath": "/opt/qinglong3/data/qinglong3.sqlite",
+    "profile": "edge",
+    "ownerPepperKeyringDirectory": "/opt/qinglong3/owner-keys",
+    "credentialFilePath": "/opt/qinglong3/credentials/operator.json",
+    "secretKeyringPath": "/opt/qinglong3/secrets/keyring.json",
+    "providerAuthorityFilePath": "/opt/qinglong3/ai/provider-authority.json",
+    "busyTimeoutMs": 1000
+  },
+  "request": {
+    "projectId": "default",
+    "packageName": "example-package",
+    "promptId": "summary",
+    "requestId": "prompt-summary-20260804-1",
+    "traceId": "trace-summary-20260804-1",
+    "auditEventId": "71000000-0000-4000-8000-000000000001",
+    "failureAuditEventId": "71000000-0000-4000-8000-000000000002",
+    "parameters": {
+      "subject": "仅存在于本次内存和 Provider 请求中的内容"
+    },
+    "provider": "openai-compatible",
+    "model": "vendor/model-a",
+    "maxOutputTokens": 512,
+    "temperature": 0.2,
+    "timeoutMs": 60000,
+    "output": {
+      "mode": "live_only"
+    }
+  }
+}
+```
+
+```sh
+chmod 600 /opt/qinglong3/commands/prompt-summary.json
+ql3-prompt run --command-file /opt/qinglong3/commands/prompt-summary.json
+```
+
+不要在 command 中加入 publication、publicationDigest、generation、plan、Run/StepRun/invocation
+identity、Policy fence、SecretRef 或 token；exact-shape 校验会在打开 SQLite 前拒绝这些字段。
+
+## 结果与重放
+
+首次成功返回 content-free receipt identity 和当前 live caller 的模型 `result`。SQLite 中的 plan、
+RunEvent、SecurityAudit、credential-use audit 与 finalization 不含参数值或模型正文。使用完全相同的
+私有 command file 重放时，返回同一 plan/admission/finalization，`status=existing`、`result=null`，
+不会再次调用 Provider。
+
+当前产品入口只接受显式 `live_only`。需要长期保存正文时，不要把 stdout 重定向回数据库或日志；应在
+后续接入受支持的加密 `durable_artifact` key/output authority 后再启用该模式。
+
+错误输出只包含稳定 `code`/`name`。token、SecretRef、数据库路径、credential path 和
+authentication identity 不会进入错误 JSON。