qinglong/docs/adr/ADR-0287-content-free-package-prompt-catalog.md

ADR-0287：Content-free 的 Package Prompt 目录读取

• 状态：Accepted
• 日期：2026-08-08
• 关联：D-85、D-87、D-157、D-213、D-244、D-257、ADR-0150、ADR-0222、ADR-0260、ADR-0261、ADR-0263、ADR-0267、ADR-0276、ADR-0270、ADR-0286

上下文

QingLong 3.0 已经能通过 Local ql3-prompt prompt.execute 和 Cluster POST /api/v3/projects/{projectId}/packages/{packageName}/prompts/{promptId}/executions 执行 generation-bound Package Prompt，但调用者必须预先知道精确 promptId。同一 Package 的 Workflow 已有受认证 目录读取，Prompt 却只能盲调用，导致 AI 产品链路缺少“发现可用能力”这一步。

直接返回 automation publication 会同时暴露 Prompt template、publication digest、installation/generation/lock、其他 Workflow 定义和内部持久化事实。把目录读取绑定到 Provider/Gateway/Secret 或本机 AI feature activation，又会让纯只读 操作承担网络、凭据、并发槽和可选 schema 的成本，不适合低配路由设备。Cluster 默认非 AI 镜像也不能因为目录读取而 获得 @qinglong/ai 生产依赖或新增常驻路由。

决策

1. 共享结果 schema 固定为 qinglong/plugin-package-prompt-catalog@v1。结果只包含 projectId、packageName、 found、publicationState 和 Prompt 摘要数组；每个 Prompt 只允许 id/name/description 与参数 name/description/required。
2. Prompt template、参数值、publication/lock/generation/installation digest、Provider、Model、SecretRef、Artifact、 Run、StepRun、价格、quota、credential、authentication ID 和审计内部字段一律不得进入目录结果。
3. Local 在既有 ql3-prompt command-file schema v1 增加 prompt.inspect。固定要求强 User 和 model.invoke；只读 options 只接受 deployment root、SQLite、Owner pepper、credential 与可选 busy timeout，不要求 Secret keyring、 Provider authority、AI feature activation、Gateway 或网络。allowed/failure audit 的 operation 均为 prompt.inspect。
4. Cluster AI Profile 增加 GET /api/v3/projects/{projectId}/packages/{packageName}/prompts，operation 为 prompt.read、permission 为 model.invoke。认证、Project Policy fence 和 allowed audit 继续由共享 admission pipeline 完成；默认 AI-free cluster-control 不注册该路由。
5. PostgreSQL catalog service 只通过当前 automation publication head 与 immutable publication 的精确 join 读取 一个目标，参数为 Project/Package，查询固定 LIMIT 2；零行返回 found=false，重复行、损坏 JSON、target 漂移或 存储失败统一 unavailable。HTTP 拒绝 GET body、无效 Package 与 capability identity drift。
6. Local 与 Cluster 共用 @qinglong/ai/plugin-package-prompt-catalog 的纯投影 contract；该 subpath 只依赖 runtime-core，不取得数据库 mutation、Provider、Secret、Artifact 或 model invocation authority。
7. 本增量不新增 workspace package、生产 dependency、migration、表、索引、Pool、端口、listener、timer、watcher、 cache、后台扫描或状态机。路由设备按一次短命令付费；Cluster 复用显式 AI 进程已有数据库 Pool。
8. Prompt 目录不是通用 Package inventory，也不是 template/source 下载 API。跨 Package 发现、全文检索、标签、版本 筛选和模板读取必须分别定义索引、分页、权限与敏感内容边界，不能静默扩宽 v1。

被拒绝的方案

• 让调用者继续保存 promptId：执行可用但能力不可发现，不构成完整产品入口。
• 返回完整 Prompt resource 或 automation publication：会暴露 template 与无关的安装、Workflow 和 digest 事实。
• 用 prompt.execute 做探测：会消耗 quota、加载 Provider/Secret，并可能产生外部费用和 durable Run。
• Local inspect 强制 AI feature active：目录事实属于已发布 Package，不需要 model invocation 可选 schema；这会让 低配设备为只读发现承担无效前置条件。
• 把 Prompt 目录加入默认 cluster-control：会破坏默认镜像 AI-free 的依赖与路由闭包。
• 新增 catalog package、projection 表或缓存：既有 immutable publication 已是权威事实，额外持久化会制造双写和 常驻资源成本。
• 使用通用 run.read 或 package.manage：前者没有表达模型调用能力，后者会把普通 Prompt 使用者错误提升为 Package 管理者；v1 固定使用现有 model.invoke。

当前证据

• @qinglong/ai 204 tests：201 pass、3 条外部 PostgreSQL 条件 skip；目录纯投影与 PostgreSQL current-head LIMIT 2 正反向测试通过。
• @qinglong/cluster-control 在可绑定本机端口的环境中 179 tests：177 pass、2 条外部服务条件 skip；新增 route、 identity drift、GET body、共享认证/Policy/audit 和 AI-only composition 通过。
• @qinglong/local-owner-cli 在可绑定本机端口的环境中 102/102；prompt.inspect 证明不激活 AI、不加载 Provider、 不要求 Secret/Provider path，并且结果不包含 template 正文。
• AI、Cluster Control、Local Owner CLI TypeScript package closure 均通过；git diff --check 与 HA 脚本语法检查通过。
• 完整 19-package clean build/test 全绿；backend 1,110 tests 为 1,108 pass/2 条环境条件 skip，零失败。Edge import、 Cluster dependency、package boundary、Cluster deployment、CloudNativePG 与 local image 六项审计均 compatible； package boundary 仍为 19 个受审包、零单文件包，只有两个纯公开产品入口允许浅层布局。
• 十档 Local artifact/RSS 门全部 compatible。最小 Edge 为 3,614,826 bytes，最大 Standalone Application AI 为 6,053,998 bytes，距 6 MiB 上限仍有 237,458 bytes；所有实测 RSS 增量均低于对应预算。
• 刷新后的 GitNexus 为 42,868 nodes/97,573 edges/1,675 clusters/261 flows；13 个关键修改符号均为 LOW， 最大 3 个上游符号，生产执行流无扩散。detect_changes all/compare develop 分别为 12 files/31 symbols 与 14/34，均为 low/0 affected process；QL3 孵化树大部分仍 untracked，因此该统计不替代逐符号 impact、完整测试、 制品与真实 HA 证据。
• PostgreSQL 18.4 arm64 physical-streaming HA 已实跑通过：Prompt catalog 在 primary、standby WAL replay 与 promoted primary 完全一致，found=true/state=active、Prompt ID 精确，template/private input 持续缺席。 timeline 1→2、旧主 fencing、pg_rewind --write-recovery-conf 只读同步 rejoin、两套 fresh control replica 与 gates.passed=true 全绿；最终 ql3-ha-* container/network/volume 零残留。

接受条件

1. 完整 19-package workspace test、backend、package/deployment/image boundary audit 与十档 artifact/RSS 门全绿。
2. PostgreSQL 18.4 arm64 physical-streaming HA 必须证明 primary、standby WAL replay 与 promoted primary 返回完全相同 的 catalog，found=true/state=active、Prompt ID 精确且 template/private input 均缺席；旧主 fencing、 pg_rewind、fresh replicas 与零残留仍须全绿。
3. 刷新 GitNexus 后关键修改保持受审影响范围，并运行 detect_changes all/compare develop。

后续边界

• 若 UI 需要跨 Package 搜索，先交付受认证、按 Package name keyset 的可见 Package 目录，禁止在内存中扫描全部 publication。
• Prompt template 预览、版本 diff、参数默认值和示例输入可能包含敏感内容，必须使用独立 permission/schema，不能 扩宽 content-free catalog。
• 默认非 AI Profile 继续保持零 Prompt route；Local inspect 继续保持 request-driven、零 daemon/Provider/Secret。