研发本体 · MCP / CLI / Skill

把湖仓查询，变成一条受控的产品边界。

推荐“共享查询核心 + MCP / REST 双入口”。连接、关联规则与数据口径集中在服务端；CLI 默认走 REST，AI Host 直连 MCP，Skill 是可选的薄说明书。

查看目标架构 ↓查看一手调研下载 HTML

交付范围：源码审阅、最佳实践调研、架构与迁移设计。本页中的 API、命令、预算和排期均为建议契约；没有部署业务 MCP 服务或连接生产湖仓。

01 · Decision

问题不是文档写得不够多，而是边界放错了。

现有 ontoos-probe 已经验证了数据字典、批次模型、跨域关系和安全护栏，但客户端仍能看到底层连接与任意 SQL。方案保留成熟的抽取与治理能力，重画访问边界。

A / DRIFT

动态事实，不写死快照

表数、视图数、行数和最新批次只作为响应里的观测值返回，带 observed_at、batch_id、source_id 与质量状态；Skill 不再承诺固定数量。

B / CONTROL

连接细节留在服务端

ADB-PG、SSH 跳板、SSL、超时、slice 和 schema 映射都由 Query Service 管理。客户端没有数据库密码，也没有任意 SQL 通道。

C / SURFACE

意图优先的工具面

围绕“搜服务、看上下文、查影响、查血缘、看新鲜度”暴露稳定工具；复杂查询由服务端模板与策略编排。

D / COMPAT

一次建模，多种客户端

MCP 给 AI Host；HTTP/JSON 给平台集成；轻量 CLI 给人和脚本。三者共享领域模型、版本化 JSON Schema 与审计契约，OpenAPI 描述 REST 映射。

推荐边界：所有进入湖仓的请求必须经过 Query Service。只有它能解析语义参数、选择视图、注入租户过滤、执行只读策略、截断结果并记录审计。

Research · Primary sources

借鉴 Lark 的产品界面，保留 OntoOS 的领域深度。

查阅日期 2026-09-20。以下是可验证的公开实践，以及基于本项目的设计判断；不是外部项目对 OntoOS 的现成保证。

一手实践	可以借鉴	在 OntoOS 中的取舍
Lark CLI：三层命令	Shortcut → API commands → Raw API；schema 自省、JSON 默认输出、分页和 dry-run 是显式能力。	场景命令 → 结构化实体/关系查询 → 受控 API。Lark 的 raw API 调用的是已有权限边界的业务 API；不能类比为向全员开放任意 SQL。
Lark CLI：企业扩展	Credential、Transport、Platform 钩子允许替换凭据源、限制命令与采集审计。	把同类扩展点放到服务端：AuthContext、Policy、QueryBackend、AuditSink。CLI 是可被替换的客户端，不能是授权的唯一执行点。
Lark CLI：错误契约	成功 stdout；失败 stderr；稳定的 type/subtype 与非零退出码；提示信息与机器分支标识分开。	统一 OntoOS envelope 与稳定错误码。表格只负责展示；默认 JSON 面向 Agent。日志、进度和登录提示不能污染 stdout。
GitHub MCP Server	提供远程服务、工具集合与显式工具 allowlist；read-only 模式优先排除写工具。	按服务发现、影响分析、数据治理分 toolset；tools/list 只展示可用工具，tools/call 仍逐次鉴权。不要一次注册每张物理表。
MCP 2026-07-28 规范	新规范以无状态、自包含请求及逐请求能力信息为基础；tools、resources、prompts 分工明确。	远程首选 Streamable HTTP。固定经过企业 Host 实测的 SDK/协议组合；旧版初始化/会话逻辑留在兼容适配层，业务核心不绑定协议 session。

与简单“probe 套 MCP 壳”的区别：服务端接管实体消歧、关系规则、场景计划、权限过滤、快照与失败语义。仅远程执行 probe.py SQL 会搬走凭据，却保留模型拼错 JOIN、无限扫描和返回敏感配置的风险。

本地证据与复用边界

已审阅 ontoos-probe 35e10c2 与 ontoos_extract cfa22b55 的工作区。未读取私有 .env 内容，未执行生产查询；下列结论是源码事实，不能据此断言线上批次数或性能。

ontoos-probe/SKILL.md:26–73：PG、SSH、SSL 与任意 SQL 示例；:74–136：固定表数和行数快照。单 SKILL 文件 46,526 字节（文件规模，不是湖仓规模）。
scripts/probe.py:778：run_query 连接并 fetchall；:906–907：可配置 timeout 和 allow-write；全局 active connection/信号机制针对单进程 CLI，不能直接复用到多请求 Web 服务。
ontoos_extract/schema_contract.py:1–77：从 schema.py 生成 meta/ODS 表列与主键契约。它尚不是包括视图、字段分级、关联语义的完整服务目录。
ontoos_extract/publish.py:208–338：先钉住源批次，copy/verify/switch 在同一事务完成；结构对账单独处理。发布工具可以复用，查询进程不应带入发布权限。
console/db.py:687–777：已有指针摘要/历史写次数比较；代码也注明手工 A→B→A 的残余局限。它是变化检测，不能直接当成跨页快照保证。

02 · Target architecture

一个查询平面，三种接入方式。

服务端是唯一能接触湖仓凭据与底层 SQL 的组件。MCP 与 REST 是协议适配层，不复制领域逻辑。

领域服务 / 适配公开协议入口治理与审计

03 · Boundary change

从“能连库”到“能完成任务”。

迁移的判断标准不是是否还能执行同一条 SQL，而是常见研发问题能否用稳定、可审计、可解释的语义请求完成。

现状风险	目标行为	验收证据
Skill 写入表/视图数量、行数和日期快照	每个响应返回 `freshness`：active batch、采集时间、各 source 状态、schema version、quality flags；文档只讲字段语义。	同一个工具连续两次请求可看到当前批次；数据更新无需改 Skill。
客户端持有 `PG_*`、SSH、SSL 与跳板参数	凭据只在服务端 secret store / runtime；连接池、只读事务、statement timeout 和取消逻辑都在服务端。	客户端配置不出现数据库密码、跳板机、真实 schema；网络策略只允许 Query Service 访问湖仓。
`probe.py` 接受任意 SQL，模型可自行拼 JOIN	默认只暴露 allowlist 工具；内部 SQL 模板有参数 schema、最大行数、最大耗时、敏感列策略。	未注册工具/未知字段/超限请求在入口拒绝；日志含 policy decision。
Skill 同时承担知识库、驱动说明、运维手册	Skill 只说明何时用、如何选工具、输出如何解释；连接与实现文档归服务端仓库。	Skill 可在无 ADB 环境安装；只需配置 MCP URL 或 CLI profile 即可使用。

Engineering choices

先建模块化单体，避免三套业务实现。

以下为推荐选型。语言和数据库不因采用 MCP 而必须重写；当前 Python 资产决定了最低迁移成本。

服务端：Python 优先

FastAPI REST + 官方 MCP Python SDK 适配；Pydantic 模型输出 OpenAPI/JSON Schema。复用 schema、关系与场景资产。不要在 Web 请求内调用旧 CLI 子进程。SDK 版本在 PoC 固定并验证目标 Host；若最新协议兼容不足，先用已验证版本，或将 MCP 适配器独立为官方 TS SDK 进程。

CLI：Go 单二进制

默认 REST + 生成类型的 HTTP client；手写少量场景命令，支持 macOS/Linux/Windows。公司制品库分发签名/校验和版本包，不要求员工装 Python、PG 驱动或 SSH。已有 Node 分发体系时可改为 TS，协议契约保持一致。

部署：企业内网 K8s

Query Server 与 serving 湖仓网络可达；生产用私网路由，替代每个员工本地跳板。起步同进程两个适配器、独立读账号。Cloudflare 本次仅托管这份静态方案，业务湖仓和查询结果不放到本页。

Python SDK 的 tools/resources 和 Streamable HTTP 用法见官方仓库；Go CLI 的分发方式是本方案选择，并非 MCP 协议要求。

方案	收益	代价 / 判断
仅远程 MCP	Agent 直连简单，服务治理集中。	普通脚本也承担 MCP 客户端兼容。若只有 AI Host 可以用；本项目还需要轻 CLI 与平台 API，故不选为唯一入口。
仅 REST + CLI	开发、缓存与脚本调试成熟。	AI Host 还要额外工具桥接，发现能力较弱；可作为同一核心的首个交付切片。
共享核心 + MCP / REST ✓	两类客户端共享行为、身份、预算、审计；新增协议不复制 SQL。	多一组适配层契约测试；初期部署单元仍为一个，避免无收益的微服务拆分。

04 · Contract

小而稳定的工具面，动态且可追溯的结果。

先收敛到高频读场景。工具返回“结果 + 解释 + 事实身份”，让 Agent 不必猜查询日期和表口径。

下述工具名、URL 和 CLI 均为拟议 v1 契约。首次搜索返回稳定 entity_id 和候选集合；重名必须选择环境/集群，不自动取第一项。

`ontology.search`

跨域检索服务、工作负载、接口、页面、库表、错误签名。输入受限于 query、domains、limit。

read-onlymax 50RBAC filtered

`ontology.service_context`

返回一个服务的部署、版本、负责人、入口、依赖、配置真值和最近批次，优先使用预建 DWS 视图。

provenancefreshness

`ontology.impact`

以表、接口、Bean、MQ channel 或工作负载为起点，返回影响面和关联置信度；调用线索缺口显式标注。

bounded graphconfidence

`ontology.lineage`

解释字段或资产的来源、派生表达式、采集轨道、active batch 与最后验证时间，避免把静态声明误称为运行事实。

source_trackobserved_at

`ontology.freshness`

返回各 source 的 active batch、activated_at、采集延迟、失败/缺口和 schema drift。它是所有结果的可复用事实卡。

cacheableno hardcode

`ontology.health`

执行低成本数据质量巡检：批次指针、schema contract、关键视图可用性、敏感数据策略和最近错误率。

operatorno raw SQL

{
  "ok": true,
  "data": {"items": [{"entity_id": "svc_demo", "name": "billing-api"}]},
  "meta": {
    "request_id": "oq_example", "contract_version": "1.0",
    "returned_count": 1, "next_cursor": null, "truncated": false,
    "snapshot_id": "snap_example", "consistency": "snapshot",
    "freshness": {
      "queried_at": "2026-09-20T09:20:00Z", "state": "unknown",
      "sources": [{"source_ref": "src_demo", "batch_ref": "batch_demo",
        "collected_at": null, "published_at": "2026-09-20T08:00:00Z"}]
    },
    "evidence": [{"ref": "ev_demo", "track": "declared", "rule_version": "r1"}],
    "warnings": ["COLLECTION_TIME_UNAVAILABLE"]
  }
}

虚构示例。published_at 不代表采集时刻；没有采集证据时 freshness 为 unknown。普通用户只见授权后的逻辑引用，不暴露物理表/连接信息。管理员可用 request_id 查执行指纹。

# 以下命令为拟议界面；示例 entity_id / endpoint 不是现网资源。
ontoos auth login --endpoint https://ontoos-query.example.com
ontoos search --query billing --kind service --format table
ontoos service context --id svc_demo --format json
ontoos impact --id table_demo --depth 2 --format ndjson
ontoos freshness --domain code
ontoos schema ontology.impact
ontoos doctor

# 可选：与 REST 共用参数和 envelope，传输差异由客户端封装
ontoos --transport mcp service context --id svc_demo

auth login 使用企业 SSO；token 存操作系统密钥库。profile 只含服务 URL / 环境 / 输出偏好。JSON 是默认；表格需显式开启；ndjson 包含 meta、item、end 类型，流中失败以 error 记录与非零退出码收尾。

API 映射与协议错误：适配器不能改变领域语义

ontology.search ↔ GET /v1/entities?query=…&kind=service；ontology.service_context ↔ GET /v1/services/{id}/context；ontology.impact ↔ POST /v1/impact；目录与统计分别通过 /v1/catalog 和 /v1/stats 暴露。筛选字段、关系类型、最大深度和数据集由注册表定义。

MCP tools 使用 inputSchema / outputSchema，结果 envelope 放 structuredContent，文本给简短摘要；业务执行失败标 isError。协议无效参数用 JSON-RPC 错误；缺失/失效 token 仍返回 HTTP 401 与 WWW-Authenticate，不藏在工具错误里。REST 使用同一错误标识和适当 HTTP 状态。参见 Tools 规范、Authorization 规范。

CLI 退出码建议：0=成功（含正常空集）；2=参数错误；3=认证/授权；4=后端不可用；5=限流；6=严格新鲜度失败或部分结果；124=超时；130=用户取消。错误含 code、retryable、request_id。仅安全读取按 Retry-After 做有界重试，语义错误不重试。

MCP Resource 可提供 ontoos://catalog/{version}/{domain}；Prompt 可提供“服务影响分析”模板；两者都可选。对不读取 Resource 的 Host 提供 ontology.catalog 工具。工具 readOnly 注解是描述，不替代服务器权限控制。

05 · Safety by construction

安全控制必须靠服务端强制，而不是靠 Skill 提醒。

Skill、CLI 参数和模型输出都不能作为权限依据。查询服务要把身份、参数、数据和审计做成不可绕过的管道。全员可安装，不意味着全员可见全部研发资产。

身份与最小权限

OIDC/OAuth 登录，映射企业身份、团队、域和数据分类；工具级和字段级授权都在服务端，默认 deny；tenant/team/project 范围从已验证身份推导，不能信任请求自填的 team_id。

查询护栏

只读连接、参数化模板、statement timeout、行数/字节上限、分页和取消；原始 SQL 留在独立管理员工具，不进入公共 API；只读还需禁止非白名单函数、外部访问与跨权限联表。

数据最小化

默认返回摘要与链接；敏感字段做列级 mask；错误消息不回显连接串、SQL、密码、内部主机和完整堆栈。

可解释审计

记录 actor、tool、参数摘要、policy decision、query fingerprint、batch identity、耗时、结果规模和 request_id。

企业鉴权与数据隔离的实现细节

SSO 是授权服务器；Query Server 是资源服务器。CLI 使用 Authorization Code + PKCE（IdP 支持时可用 Device Flow）；后台任务用绑定项目范围的工作负载身份。校验签名、issuer、audience、expiry 与 scope，绝不把用户 token 透传给 ADB。远程 MCP 返回 protected-resource metadata 和标准 401 challenge；具体要求见 MCP Authorization。

普通员工只见获批目录摘要；研发按项目/环境查看部署与关系；运维/治理角色可看额外诊断。Apollo/ConfigMap/连接字符串可能含敏感值：默认只返回字段名、存在性、差异分类，秘密值不返回。聚合、搜索命中数、关系边两端和缓存都执行同样的授权过滤。

数据库账号仅 SELECT 获批对象，无 DDL/写入/管理员权限。服务端 whitelist 函数与表达式；只读事务不是全部防线。TLS 验证主机身份；生产不复制旧脚本的 SSH 证书降级行为。上游文本只当数据处理，不能被模型当作执行指令。审计记录参数脱敏摘要和引用，不保存配置正文、access token 或完整 SQL。

失败语义：成功、无结果、数据过期、schema 漂移、超时、权限拒绝和后端不可用必须有不同的机器可读状态；CLI 以非零退出码表达失败，Agent 不能把“空结果”当成“查询成功”。

06 · Living metadata

静态定义版本化，动态事实在线化。

删除文档中的固定数量只是第一步。服务端必须区分“设计有哪些对象”“已部署哪些对象”和“当前观测到多少数据”。

信息类别	权威来源与更新	返回约定
定义 / 语义	schema.py + 人工审阅的关系/场景规则；CI 生成 versioned metadata pack。补足现有 schema_contract 未覆盖的 DWD/DWS 视图、释义、敏感分级。	schema_version、rule_version、实体/字段的稳定 ID。文档中的稳定规则可以保留，统计快照移出。
实际可用目录	后台读取 serving information_schema，与定义契约对账；加列/删列/类型变化显式标 drift。	declared / deployed / unavailable 分开。缺少依赖时只禁用受影响工具，不把“目录存在”冒充“数据可用”。
规模与覆盖率	publish 成功后后台计算，事件通知 + 定时对账补偿；昂贵精确 count 走任务，按 source/batch 复用统计。	count、exact/estimated/unknown、computed_at、snapshot_id、scope、分子/分母口径。禁止每次请求全库 count；未经授权的数据不计入用户可见统计。
新鲜度 / 质量	source 批次映射、采集记录、发布记录和质量诊断联合生成。缺采集时间先 unknown，再补采集 manifest；不能用激活时间替代观测时间。	按源返回 collected_at / published_at / queried_at、fresh/stale/unknown/partial。日更域初始阈值建议 36h，可按源配置；这是产品策略，不是现网实测 SLA。

快照一致性需要读机制支持，不能只加一个 digest 字段

单请求：在同一只读事务中读取批次映射与数据，目标 ADB 的隔离级别和相关视图必须 PoC 验证；能支持时采用 REPEATABLE READ。否则执行器显式将 ODS 读取约束到固定 source→batch 集合，DWS/DWD 计划也须重写或物化。旧 current 视图不会自动遵守客户端传来的 snapshot_id。

跨页：首版将有界查询结果物化为短期服务端 result set，再返回签名 cursor。cursor 绑定 actor / 授权版本 / 参数 hash / snapshot / offset / expiry；每页重新鉴权。批次淘汰、结果过期、授权变化分别失败，不默默换成新批次继续翻页。没有 batch_id 的表也一并物化，不能声称它们有历史快照。

缓存：key 至少包含授权范围摘要、policy_version、tool/contract_version、规范化参数、schema_version、snapshot_id；先鉴权再查缓存。发布切换使新请求使用新 snapshot key，旧结果只在明确 TTL 内继续可读。统计未算完返回 unknown/stale，不回填上个批次的值冒充当前值。

抽取完成

追加批次，记录采集/缺口

质量校验

schema、行数、关键关联

原子发布

copy / verify / switch

后台刷新

目录、统计、能力健康

查询返回

业务结果 + 事实身份

Server-owned knowledge

把最有价值的关联经验，变成可测试的规则。

一个由服务端维护的语义注册表提供高层场景，也支撑长尾查询；不把现有能力缩成六个硬编码查询。

实体与关系注册表

稳定 entity_id；身份键包含域内 source 和自然主键。source_id 用于域内隔离，不能跨域直接 JOIN；代码→服务的镜像/commit 关联保留证据。重名返回 candidates；跨数据库同名表必须用 datasource 消歧。

采集轨道与可信度

静态与 in-situ 的 component_id 不通，跨轨按 archive 粒度规则配对；observed/declared、匹配方法与覆盖缺口随边输出。沿用 deployed 视图的部署位点语义，不能把所有归档中的接口都称为线上接口。

受控长尾查询

ontology.query 接受注册 dataset、白名单 fields/filters、聚合与 relation path；不接受 SQL 字符串。模板携带成本级别、依赖、输出契约、降级路径。未覆盖问题返回 UNSUPPORTED_QUERY 并进入模板评审，不让模型自由拼跨域 JOIN。

这些约束来自本地 SKILL.md:136–175 与 references/relationships.md。文档中的历史命中率只作为待复测的案例，不能写成新服务永久常量。

当前资产	迁移后的服务端职责	验证关注点
catalog / expected_schema / validate_schema	目录服务 + drift job + metadata pack	真实部署差异、视图未覆盖、字段敏感分级
relationships	关系注册表 / resolver / evidence model	跨域键误用、N:M 歧义、跨轨配对、静态不等于真实调用
product / architecture	search、service_context、impact、受控 query	服务/API、前端图、依赖闭包、循环与耦合分析
rnd-commit / ops	provenance、freshness、配置差异与运维模板	部署/构建分叉；配置值默认不返回；来源可信度
fault / incident	反向查找与场景编排：报错→服务、页面→仓、入口链、MQ 线索	错误签名是代码声明，不是实时日志；单据状态等业务数据问题明确移交
probe.py / 连接 ADR	独立连接池与执行器，移除客户端跳板和 signal 全局状态	取消只影响当前请求；池归还时事务回滚/设置重置；服务端硬超时

Optional Skill

薄到能读完，不承担执行和治理。

目标约 60–100 行，只记录选择工具与解释证据的步骤。无 Skill 时 CLI help / schema 和 MCP discovery 已能独立工作。

# ontoos（拟议 SKILL 内容示例）
适用：研发资产、服务关联、部署溯源、影响分析、数据质量。
不适用：业务单据当前状态、实时日志、修改配置或发布服务。

1. 用 ontoos search 找实体；多候选时按环境/集群消歧。
2. 用 ontoos schema 查看命令参数；用返回的 entity_id 继续查询。
3. 查服务用 service context；查影响用 impact；字段解释查 catalog。
4. 结论引用 evidence、采集时间和覆盖缺口；静态关系不要写成运行事实。
5. stale / partial / unknown 如实说明；权限失败不换身份或尝试直连。
6. 默认 JSON；命令帮助、参数与版本以 CLI / 服务端 discovery 为准。

示例：ontoos service context --id svc_demo --format json
连接配置、SQL、表统计与批次数据均不随此说明分发。

上面是设计稿示例，不是已安装的新技能。后续可从 CLI command registry 自动生成参数和示例；人工只维护触发条件、问答步骤、证据解读与范围边界。

07 · Delivery plan

四阶段上线，先收口，再扩面。

估算 5–7 周：2 名后端/数据工程师 + 1 名 CLI 工程师，平台/IAM 兼职支持；非承诺排期，取决于 SSO、现网查询预算和 Host 兼容验证。按场景迁移，不删除尚未接管的能力。

Phase 1 · 契约与核心（1–2 周）

提取 schema/关系规则为只读包；保留独立 publisher，新增服务端连接池与工具注册。

freshness / search / service_context
OIDC、只读、超时、审计
contract tests + golden responses

Phase 2 · 双入口与 CLI（1–2 周）

发布 ontoos CLI；把原 Skill 改成短说明，默认调用 MCP/REST。

JSON/ndjson/table 输出
profile 与 token 管理
旧命令的迁移提示

Phase 3 · 覆盖与试点（1–2 周）

将高频场景迁移到 allowlist 工具；把 schema drift、质量和审计接到告警。

impact / lineage / health
字段分级与团队策略
结果缓存和限流

Phase 4 · 迁移收口（1 周）

冻结直连 probe 的全员分发；保留隔离的管理员诊断 profile。

旧 Skill 只读兼容期
按使用率下线 raw SQL
文档与 schema 版本化

# 推荐仓库边界（示意）
ontoos-query-service/
  apps/query-api/        # MCP + REST adapter
  packages/domain-tools/ # semantic tools, schemas, policy
  packages/lakehouse/    # read-only connection/catalog adapter; no publisher
  packages/audit/        # redacted events, metrics, traces
  clients/ontoos-cli/    # thin client, no PG dependency
ontoos_extract/           # existing extraction + publish, separate write identity
ontoos-probe-skill/
  SKILL.md               # optional usage guide only

Operations & rollout

把昂贵查询和失败降级关在服务端。

以下是起始预算建议，必须用真实 ADB 计划与并发压测校准；本次没有测量生产延迟。

有界同步执行

搜索建议默认 20 条、上限 100；工具响应字节上限建议 256 KB。DB statement timeout 初值 8s，总请求 deadline 10s；工具可收紧，用户不可放宽。并发池与每角色配额一起限制数据库总压力，取消要下传到当前连接。

重查询独立任务

跨域全景/精确统计走持久 job，建议初始硬预算 60s，失败无无限重试。job_id 绑定身份，读取/取消均鉴权；结果 TTL 建议 15min。MCP Tasks 仅在客户端兼容时启用，否则使用普通 job 工具 + REST 轮询。

计划与健康分开

历史视图有 slice/内存/超时案例；LIMIT 或 WHERE 不保证计划降 slice。按工具维护已验证 fallback plan，失败熔断昂贵路径。临时表策略需单独验证目标库读角色权限及资源配额；不能为此给所有请求开放写入。

上线门与回滚边界

试点先覆盖服务搜索、服务上下文、部署溯源、表影响、报错反查、页面归属、入口链、MQ 线索、配置差异、freshness 等代表场景。把旧 SQL 与新工具在相同数据快照上影子比对：结果集合、消歧、来源与缺口都要一致，不只比较行数。

试点目标建议：普通查询 p95 ≤ 2s、错误率 < 1%、未授权对象泄露 0；这些是拟议验收目标。观测 query_duration、pool_wait、timeout、denied、rows/bytes、cache hit、source lag、drift；按 request_id 关联日志，避免以实体 ID 作为高基数 metrics 标签。

发布先内部团队→单域试点→扩大；只回滚 Query Server 镜像/模板/metadata pack。涉及 schema 变更用 expand/contract，不能让旧程序读不兼容字段。旧 probe 限管理员隔离环境，不作为全员“服务故障自动直连”回退。迁移到位后撤销已分发 DB 凭据，调整网络白名单；再更新 ontoos-code-probe 等兄弟技能使用语义 API。

08 · Acceptance gates

用证据判断是否真的完成。

以下门槛直接对应本次诉求，可作为 PR、发布和安全评审的检查表。

门槛	必须证明	测试方式
新鲜度不漂移	Skill/CLI 文档不含固定行数、表数或过期日期；响应带 batch 与 observed_at。	更新一批抽取数据后不改客户端，回归测试比对 freshness。
底层连接不外泄	客户端包、Skill、CLI help 和错误输出都没有 PG/SSH 密钥或真实 schema。	secret scan + 安装隔离测试 + 网络 egress policy。
任意 SQL 被隔离	公共 MCP/REST surface 没有 raw SQL；所有工具参数由 JSON Schema 校验。	fuzz unknown tool/field、超时、超限、注入 payload。
结果可追溯	任意结果都能关联 request_id、tool、policy、query fingerprint、batch identity。	审计事件 contract test；抽查脱敏日志。
协议可迁移	MCP 与 REST 的结果语义一致；CLI 断网、权限拒绝、空结果的退出码稳定。	golden JSON/ndjson、MCP client compatibility、端到端 smoke。

09 · Evidence

方案依据与可追溯来源。

现状证据来自工作区源码；外部做法来自一手项目和官方协议/部署文档。链接可继续核验。

LARK CLI三层命令系统、结构化 envelope、配置/凭据与 enterprise wrapper 的参考样本。 MCPHost / Client / Server 边界与 2026-07-28 逐请求能力信息。 MCP SDKStreamable HTTP、stdio、tools/resources/prompts 与服务端实现方向。 CLOUDFLARE本页用 Pages Direct Upload 发布；静态 HTML 作为预构建资产部署。 SPEC REPOMCP 规范与变更记录；生产实现应固定兼容版本并持续评估升级。 LOCAL抽取工程中的 append-only batch、active pointer、publish、schema contract 与 console 证据。