0 Fork 0

Files

T

chenxin 42513d13c6 📝 docs: 建立魂镜完整 1.0 设计文档体系

- 产品层：产品宪章与永久禁域、产品定义、完整 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

2026-09-09 21:07:14 +08:00

5.4 KiB

Raw Permalink Blame History

Lingtai Service

灵台引擎独立服务形态的 gRPC 契约。本文件是服务方法、错误映射与形态边界的登记处；机器化前以本文件为命名基线，机器化后以 proto/lingtai/v1/lingtai.proto 为真源。进程内形态契约见 Lingtai C ABI；架构语义见灵台引擎架构。

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，与协议与稳定标识一致；消息字段语义与 C ABI 的 JSON 边界（统一富内容与流式协议）同源，不另造字段语义。

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）到 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 的版本/能力协商硬编码猜测方法行为。
不得将引擎错误消息原样透传给最终用户；错误本地化由宿主完成。

5.4 KiB Raw Permalink Blame History Unescape Escape