chenxin
42513d13c6
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
78 lines
5.4 KiB
Markdown
78 lines
5.4 KiB
Markdown
# Lingtai Service
|
||
|
||
灵台引擎独立服务形态的 gRPC 契约。本文件是服务方法、错误映射与形态边界的登记处；机器化前以本文件为命名基线，机器化后以 `proto/lingtai/v1/lingtai.proto` 为真源。进程内形态契约见 [Lingtai C ABI](lingtai-ffi.md)；架构语义见[灵台引擎架构](../architecture/lingtai-engine.md)。
|
||
|
||
## 1. 适用范围与稳定性
|
||
|
||
- 消费方：同一部署内的 FastAPI 宿主、Worker、Go 网关与经部署者授权的内部系统。这是**部署内部契约**，不进入 `api.<domain>`/`gateway.<domain>` 公共分面，不经公共网关暴露，不向最终用户承诺稳定性。
|
||
- proto 按 protobuf 官方演进纪律：不修改既有字段编号与类型，新增字段由消费方忽略；破坏性变更升 `v2` 包，并行维护一个旧包的最短过渡期。
|
||
- 服务无权威状态：任何方法被路由到任一实例结果一致；实例可水平扩缩，无会话粘滞（流式方法除外，见第 5 节）。
|
||
|
||
## 2. 命名
|
||
|
||
| 对象 | 规则 | 示例 |
|
||
| --- | --- | --- |
|
||
| proto 包 | `lingtai.v<major>` | `lingtai.v1` |
|
||
| 服务 | `LingtaiEngine` | `lingtai.v1.LingtaiEngine` |
|
||
| 方法 | 模块职责 + 动词 | `TransformMarkdown`、`EvaluatePolicy` |
|
||
| 消息 | 请求/响应后缀 | `TransformMarkdownRequest` |
|
||
| 二进制 | `hunjing-lingtai-server` | 监听部署内部地址 |
|
||
|
||
字段命名使用 `snake_case`，与 [协议与稳定标识](README.md) 一致；消息字段语义与 C ABI 的 JSON 边界（[统一富内容与流式协议](content-blocks-and-streaming.md)）同源，不另造字段语义。
|
||
|
||
## 3. 能力与方法
|
||
|
||
| 方法 | 对应子系统 | 语义 |
|
||
| --- | --- | --- |
|
||
| `GetEngineInfo` | `hj_core` | 版本、ABI major、parser version、能力位 |
|
||
| `TransformMarkdown` | `hj_transform` | Markdown → canonical ContentBlock 列表（含 parser version） |
|
||
| `RebuildExport` | `hj_transform` | canonical Block → 可移植 Markdown 重建 |
|
||
| `OpenStream` | `hj_stream` | 双向流：宿主喂增量，服务回 `content.block.*` 事件 envelope |
|
||
| `ValidatePlan` | `hj_plan` | 计划 DAG 校验、拓扑排序与预算核算 |
|
||
| `AssembleContext` | `hj_plan` | Context Manifest 裁剪与优先级排序计算 |
|
||
| `RerankRecall` | `hj_recall` | 多路检索结果重排与合并（服务形态能力） |
|
||
| `EvaluatePolicy` | `hj_policy` | Schema/路径/URL 校验、验签、幂等键规范化、决策表评估 |
|
||
| `CheckStateTransition` | `hj_core` | Run/Turn 状态转换合法性校验 |
|
||
|
||
- 形态边界登记：`hj_recall` 的离线索引文件 mmap 仅进程内形态可用；服务形态只提供 `RerankRecall` 等 CPU 计算部分。新增单形态能力必须在本表登记。
|
||
- 所有请求携带调用方声明的限额（长度/深度/预算）；服务端按部署配置二次钳制，取两者较小值。
|
||
|
||
## 4. 传输与认证
|
||
|
||
- 仅监听部署内部网络；TLS 必启，客户端与服务端双向 mTLS，证书由部署内部 CA 签发。
|
||
- 认证是工作负载身份（客户端证书/SPIFFE 类标识），不是用户凭据；用户级授权判定在宿主完成后才调用引擎，引擎不重复也不绕过用户授权。
|
||
- 不存在匿名访问；未经认证连接在握手阶段断开并记审计。
|
||
- 部署元数据（trace 上下文）经 gRPC metadata 传播，与 `traceparent` 语义一致；业务请求 ID 由宿主透传，服务不生成权威 ID。
|
||
|
||
## 5. 流式语义
|
||
|
||
- `OpenStream` 为双向流：客户端按序发送增量帧，服务端按序返回事件 envelope；事件带 `sequence` 与 `delta_index`，语义与 C ABI 回调一致。
|
||
- 一条流绑定一个服务端会话句柄；流中断（网络/超时）后会话丢弃，客户端以最终权威数据重放重建，不依赖半程状态。
|
||
- 背压：服务端按配置的内存水位暂停读取；客户端必须在水位恢复前停止发送，不得假设无限缓冲。
|
||
|
||
## 6. 错误映射
|
||
|
||
`HjStatus`（[Lingtai C ABI](lingtai-ffi.md)）到 gRPC status 的映射：
|
||
|
||
| `HjStatus` | gRPC code |
|
||
| --- | --- |
|
||
| `HJ_OK` | `OK` |
|
||
| `HJ_ERR_INVALID_ARGUMENT` / `HJ_ERR_PARSE_FAILED` | `INVALID_ARGUMENT` |
|
||
| `HJ_ERR_LIMIT_EXCEEDED` | `OUT_OF_RANGE` 或 `RESOURCE_EXHAUSTED`（按限额类型） |
|
||
| `HJ_ERR_POLICY_DENIED` / `HJ_ERR_SIGNATURE_INVALID` | `FAILED_PRECONDITION` 或 `PERMISSION_DENIED`（按调用语义） |
|
||
| `HJ_ERR_INDEX_CORRUPT` | `DATA_LOSS`（要求重建索引） |
|
||
| `HJ_ERR_UNSUPPORTED_ABI` | `UNIMPLEMENTED` |
|
||
| `HJ_ERR_OUT_OF_MEMORY` / `HJ_ERR_INTERNAL` | `INTERNAL` |
|
||
| `HJ_ERR_HANDLE_INVALID` / `HJ_ERR_REENTRANCY` | `INTERNAL`（进程内契约，服务面不应出现） |
|
||
|
||
- 服务自身的基础设施错误（不可达、超时、认证失败、过载）使用标准 gRPC code：`UNAVAILABLE`、`DEADLINE_EXCEEDED`、`UNAUTHENTICATED`、`UNAVAILABLE`（过载）。
|
||
- 错误 detail 不包含请求正文、密钥或凭据；宿主对 `UNAVAILABLE`/`DEADLINE_EXCEEDED` 的重试由 gRPC 重试策略统一配置，计算方法无副作用、可安全重试。
|
||
|
||
## 7. 禁令清单
|
||
|
||
- 不得把本服务经公共网关或 `api.<domain>` 暴露给外部调用方。
|
||
- 不得在服务面引入用户身份认证或授权判定（那是宿主与 Policy Core 的职责）。
|
||
- 不得让任何方法在服务形态与进程内形态产生不同语义；发现分歧按缺陷处理并以 golden 测试复现。
|
||
- 不得绕过 `GetEngineInfo` 的版本/能力协商硬编码猜测方法行为。
|
||
- 不得将引擎错误消息原样透传给最终用户；错误本地化由宿主完成。
|