✨ feat: 灵台引擎 gRPC 独立服务形态(ADR-017 双形态落地)

- proto(engine/proto/liushen/v1):LingtaiEngine 九方法——GetEngineInfo(版本协商/能力位)、TransformMarkdown、RebuildExport(UNIMPLEMENTED 明示随 WP-03)、OpenStream 双向流、CheckBudget、RerankRecall、EvaluatePolicy、ValidateUrl、CheckStateTransition;RunStatus 枚举与契约一致
- 服务端参考实现(engine/server/lingtai_server.py):进程内直链 nanobind 引擎核心——双形态同核同 golden;开发档 127.0.0.1 明文(生产 mTLS,文案明示);状态转换表按 agent-runtime 第 3 节
- 集成测试 6 项:进程内随机端口起服——版本协商、双形态 golden(服务输出==进程内引擎输出,ADR-017 核心不变量首次实证)、双向流 envelope 序号单调、决策表/URL/状态机、RebuildExport UNIMPLEMENTED 明确拒绝(不伪造)
- Makefile:lingtai-proto(stub 再生)与 lingtai-server(启动服务)目标
- 注:C++ 原生二进制(hunjing-lingtai-server)随交叉编译矩阵交付;Python 参考实现保证 proto 与语义先行锁定
- 测试 102 项全绿(+6);ruff/mypy 干净
This commit is contained in:
chenxin committed 2026-09-14 10:21:54 +08:00
1 parent a39cec5287
commit 9dafb8fe72
10 files changed
+1141

No files matched your search

+127
View File
@@ -0,0 +1,127 @@
syntax = "proto3";
package liushen.v1;
// 灵台引擎独立服务形态(契约 docs/contracts/lingtai-service.md)。
// 部署内部网络专用;错误映射见契约第 6 节。字段语义与进程内 C ABI JSON 边界同源。
service LingtaiEngine {
// 版本、ABI major、parser version、能力位
rpc GetEngineInfo(GetEngineInfoRequest) returns (GetEngineInfoResponse);
// Markdown → canonical ContentBlock JSON
rpc TransformMarkdown(TransformMarkdownRequest) returns (TransformMarkdownResponse);
// canonical Block → 可移植 Markdown 重建(预留:实现随 WP-03 导出)
rpc RebuildExport(RebuildExportRequest) returns (RebuildExportResponse);
// 双向流:宿主喂增量,服务回 content.block.* envelope JSON
rpc OpenStream(stream StreamFrame) returns (stream StreamEvent);
// 计划 DAG 预算核算(最小:标量预算)
rpc CheckBudget(CheckBudgetRequest) returns (CheckBudgetResponse);
// 候选确定性重排
rpc RerankRecall(RerankRecallRequest) returns (RerankRecallResponse);
// 四维裁决(autonomy × risk)
rpc EvaluatePolicy(EvaluatePolicyRequest) returns (EvaluatePolicyResponse);
// URL 协议白名单校验
rpc ValidateUrl(ValidateUrlRequest) returns (ValidateUrlResponse);
// Run/Turn 状态转换合法性
rpc CheckStateTransition(CheckStateTransitionRequest) returns (CheckStateTransitionResponse);
}
message GetEngineInfoRequest {}
message GetEngineInfoResponse {
uint32 abi_major = 1;
string parser_version = 2;
string engine_version = 3;
repeated string capabilities = 4;
}
message TransformMarkdownRequest {
string markdown = 1;
}
message TransformMarkdownResponse {
string canonical_json = 1; // canonical ContentBlock JSON(键序确定)
}
message RebuildExportRequest {
string canonical_json = 1;
}
message RebuildExportResponse {
string markdown = 1;
}
message StreamFrame {
oneof frame {
string block_started = 2; // block_id:开启新 block(重置 delta_index)
string text_delta = 3; // 文本增量
}
}
message StreamEvent {
string event_json = 1; // content.block.* envelope(canonical JSON)
}
message CheckBudgetRequest {
int64 used = 1;
int64 maximum = 2;
}
message CheckBudgetResponse {
bool allowed = 1;
string reason = 2;
}
message RerankRecallRequest {
string candidates_json = 1;
}
message RerankRecallResponse {
string ranked_json = 1;
}
message EvaluatePolicyRequest {
int32 autonomy_level = 1; // 0 自省 / 1 循律 / 2 请命 / 3 禁域
int32 risk_level = 2; // 0 只读 / 1 副作用 / 2 高影响
}
message EvaluatePolicyResponse {
int32 decision = 1; // 0 allow / 1 ask / 2 deny
}
message ValidateUrlRequest {
string url = 1;
}
message ValidateUrlResponse {
bool allowed = 1;
string reason = 2;
}
enum RunStatus {
RUN_STATUS_UNSPECIFIED = 0;
RUN_STATUS_QUEUED = 1;
RUN_STATUS_RUNNING = 2;
RUN_STATUS_WAITING_APPROVAL = 3;
RUN_STATUS_COMPLETED = 4;
RUN_STATUS_FAILED = 5;
RUN_STATUS_CANCELLED = 6;
}
message CheckStateTransitionRequest {
RunStatus from = 1;
RunStatus to = 2;
}
message CheckStateTransitionResponse {
bool valid = 1;
string reason = 2;
}
Whitespace-only changes.
Whitespace-only changes.
@@ -0,0 +1,74 @@
# -*- coding: utf-8 -*-
# Generated by the protocol buffer compiler. DO NOT EDIT!
# NO CHECKED-IN PROTOBUF GENCODE
# source: liushen/v1/liushen.proto
# Protobuf Python Version: 7.35.1
"""Generated protocol buffer code."""
from google.protobuf import descriptor as _descriptor
from google.protobuf import descriptor_pool as _descriptor_pool
from google.protobuf import runtime_version as _runtime_version
from google.protobuf import symbol_database as _symbol_database
from google.protobuf.internal import builder as _builder
_runtime_version.ValidateProtobufRuntimeVersion(
_runtime_version.Domain.PUBLIC,
7,
35,
1,
'',
'liushen/v1/liushen.proto'
)
# @@protoc_insertion_point(imports)
_sym_db = _symbol_database.Default()
DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x18liushen/v1/liushen.proto\x12\nliushen.v1\"\x16\n\x14GetEngineInfoRequest\"p\n\x15GetEngineInfoResponse\x12\x11\n\tabi_major\x18\x01 \x01(\r\x12\x16\n\x0eparser_version\x18\x02 \x01(\t\x12\x16\n\x0e\x65ngine_version\x18\x03 \x01(\t\x12\x14\n\x0c\x63\x61pabilities\x18\x04 \x03(\t\",\n\x18TransformMarkdownRequest\x12\x10\n\x08markdown\x18\x01 \x01(\t\"3\n\x19TransformMarkdownResponse\x12\x16\n\x0e\x63\x61nonical_json\x18\x01 \x01(\t\".\n\x14RebuildExportRequest\x12\x16\n\x0e\x63\x61nonical_json\x18\x01 \x01(\t\")\n\x15RebuildExportResponse\x12\x10\n\x08markdown\x18\x01 \x01(\t\"E\n\x0bStreamFrame\x12\x17\n\rblock_started\x18\x02 \x01(\tH\x00\x12\x14\n\ntext_delta\x18\x03 \x01(\tH\x00\x42\x07\n\x05\x66rame\"!\n\x0bStreamEvent\x12\x12\n\nevent_json\x18\x01 \x01(\t\"3\n\x12\x43heckBudgetRequest\x12\x0c\n\x04used\x18\x01 \x01(\x03\x12\x0f\n\x07maximum\x18\x02 \x01(\x03\"6\n\x13\x43heckBudgetResponse\x12\x0f\n\x07\x61llowed\x18\x01 \x01(\x08\x12\x0e\n\x06reason\x18\x02 \x01(\t\".\n\x13RerankRecallRequest\x12\x17\n\x0f\x63\x61ndidates_json\x18\x01 \x01(\t\"+\n\x14RerankRecallResponse\x12\x13\n\x0branked_json\x18\x01 \x01(\t\"C\n\x15\x45valuatePolicyRequest\x12\x16\n\x0e\x61utonomy_level\x18\x01 \x01(\x05\x12\x12\n\nrisk_level\x18\x02 \x01(\x05\"*\n\x16\x45valuatePolicyResponse\x12\x10\n\x08\x64\x65\x63ision\x18\x01 \x01(\x05\"!\n\x12ValidateUrlRequest\x12\x0b\n\x03url\x18\x01 \x01(\t\"6\n\x13ValidateUrlResponse\x12\x0f\n\x07\x61llowed\x18\x01 \x01(\x08\x12\x0e\n\x06reason\x18\x02 \x01(\t\"e\n\x1b\x43heckStateTransitionRequest\x12#\n\x04\x66rom\x18\x01 \x01(\x0e\x32\x15.liushen.v1.RunStatus\x12!\n\x02to\x18\x02 \x01(\x0e\x32\x15.liushen.v1.RunStatus\"=\n\x1c\x43heckStateTransitionResponse\x12\r\n\x05valid\x18\x01 \x01(\x08\x12\x0e\n\x06reason\x18\x02 \x01(\t*\xc2\x01\n\tRunStatus\x12\x1a\n\x16RUN_STATUS_UNSPECIFIED\x10\x00\x12\x15\n\x11RUN_STATUS_QUEUED\x10\x01\x12\x16\n\x12RUN_STATUS_RUNNING\x10\x02\x12\x1f\n\x1bRUN_STATUS_WAITING_APPROVAL\x10\x03\x12\x18\n\x14RUN_STATUS_COMPLETED\x10\x04\x12\x15\n\x11RUN_STATUS_FAILED\x10\x05\x12\x18\n\x14RUN_STATUS_CANCELLED\x10\x06\x32\x98\x06\n\rLingtaiEngine\x12T\n\rGetEngineInfo\x12 .liushen.v1.GetEngineInfoRequest\x1a!.liushen.v1.GetEngineInfoResponse\x12`\n\x11TransformMarkdown\x12$.liushen.v1.TransformMarkdownRequest\x1a%.liushen.v1.TransformMarkdownResponse\x12T\n\rRebuildExport\x12 .liushen.v1.RebuildExportRequest\x1a!.liushen.v1.RebuildExportResponse\x12\x42\n\nOpenStream\x12\x17.liushen.v1.StreamFrame\x1a\x17.liushen.v1.StreamEvent(\x01\x30\x01\x12N\n\x0b\x43heckBudget\x12\x1e.liushen.v1.CheckBudgetRequest\x1a\x1f.liushen.v1.CheckBudgetResponse\x12Q\n\x0cRerankRecall\x12\x1f.liushen.v1.RerankRecallRequest\x1a .liushen.v1.RerankRecallResponse\x12W\n\x0e\x45valuatePolicy\x12!.liushen.v1.EvaluatePolicyRequest\x1a\".liushen.v1.EvaluatePolicyResponse\x12N\n\x0bValidateUrl\x12\x1e.liushen.v1.ValidateUrlRequest\x1a\x1f.liushen.v1.ValidateUrlResponse\x12i\n\x14\x43heckStateTransition\x12\'.liushen.v1.CheckStateTransitionRequest\x1a(.liushen.v1.CheckStateTransitionResponseb\x06proto3')
_globals = globals()
_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'liushen.v1.liushen_pb2', _globals)
if not _descriptor._USE_C_DESCRIPTORS:
DESCRIPTOR._loaded_options = None
_globals['_RUNSTATUS']._serialized_start=1047
_globals['_RUNSTATUS']._serialized_end=1241
_globals['_GETENGINEINFOREQUEST']._serialized_start=40
_globals['_GETENGINEINFOREQUEST']._serialized_end=62
_globals['_GETENGINEINFORESPONSE']._serialized_start=64
_globals['_GETENGINEINFORESPONSE']._serialized_end=176
_globals['_TRANSFORMMARKDOWNREQUEST']._serialized_start=178
_globals['_TRANSFORMMARKDOWNREQUEST']._serialized_end=222
_globals['_TRANSFORMMARKDOWNRESPONSE']._serialized_start=224
_globals['_TRANSFORMMARKDOWNRESPONSE']._serialized_end=275
_globals['_REBUILDEXPORTREQUEST']._serialized_start=277
_globals['_REBUILDEXPORTREQUEST']._serialized_end=323
_globals['_REBUILDEXPORTRESPONSE']._serialized_start=325
_globals['_REBUILDEXPORTRESPONSE']._serialized_end=366
_globals['_STREAMFRAME']._serialized_start=368
_globals['_STREAMFRAME']._serialized_end=437
_globals['_STREAMEVENT']._serialized_start=439
_globals['_STREAMEVENT']._serialized_end=472
_globals['_CHECKBUDGETREQUEST']._serialized_start=474
_globals['_CHECKBUDGETREQUEST']._serialized_end=525
_globals['_CHECKBUDGETRESPONSE']._serialized_start=527
_globals['_CHECKBUDGETRESPONSE']._serialized_end=581
_globals['_RERANKRECALLREQUEST']._serialized_start=583
_globals['_RERANKRECALLREQUEST']._serialized_end=629
_globals['_RERANKRECALLRESPONSE']._serialized_start=631
_globals['_RERANKRECALLRESPONSE']._serialized_end=674
_globals['_EVALUATEPOLICYREQUEST']._serialized_start=676
_globals['_EVALUATEPOLICYREQUEST']._serialized_end=743
_globals['_EVALUATEPOLICYRESPONSE']._serialized_start=745
_globals['_EVALUATEPOLICYRESPONSE']._serialized_end=787
_globals['_VALIDATEURLREQUEST']._serialized_start=789
_globals['_VALIDATEURLREQUEST']._serialized_end=822
_globals['_VALIDATEURLRESPONSE']._serialized_start=824
_globals['_VALIDATEURLRESPONSE']._serialized_end=878
_globals['_CHECKSTATETRANSITIONREQUEST']._serialized_start=880
_globals['_CHECKSTATETRANSITIONREQUEST']._serialized_end=981
_globals['_CHECKSTATETRANSITIONRESPONSE']._serialized_start=983
_globals['_CHECKSTATETRANSITIONRESPONSE']._serialized_end=1044
_globals['_LINGTAIENGINE']._serialized_start=1244
_globals['_LINGTAIENGINE']._serialized_end=2036
# @@protoc_insertion_point(module_scope)
@@ -0,0 +1,459 @@
# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
"""Client and server classes corresponding to protobuf-defined services."""
import grpc
import warnings
from liushen.v1 import liushen_pb2 as liushen_dot_v1_dot_liushen__pb2
GRPC_GENERATED_VERSION = '1.83.1'
GRPC_VERSION = grpc.__version__
_version_not_supported = False
try:
from grpc._utilities import first_version_is_lower
_version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
except ImportError:
_version_not_supported = True
if _version_not_supported:
raise RuntimeError(
f'The grpc package installed is at version {GRPC_VERSION},'
+ ' but the generated code in liushen/v1/liushen_pb2_grpc.py depends on'
+ f' grpcio>={GRPC_GENERATED_VERSION}.'
+ f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+ f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
)
class LingtaiEngineStub:
"""灵台引擎独立服务形态(契约 docs/contracts/lingtai-service.md)。
部署内部网络专用;错误映射见契约第 6 节。字段语义与进程内 C ABI JSON 边界同源。
"""
def __init__(self, channel):
"""Constructor.
Args:
channel: A grpc.Channel.
"""
self.GetEngineInfo = channel.unary_unary(
'/liushen.v1.LingtaiEngine/GetEngineInfo',
request_serializer=liushen_dot_v1_dot_liushen__pb2.GetEngineInfoRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.GetEngineInfoResponse.FromString,
_registered_method=True)
self.TransformMarkdown = channel.unary_unary(
'/liushen.v1.LingtaiEngine/TransformMarkdown',
request_serializer=liushen_dot_v1_dot_liushen__pb2.TransformMarkdownRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.TransformMarkdownResponse.FromString,
_registered_method=True)
self.RebuildExport = channel.unary_unary(
'/liushen.v1.LingtaiEngine/RebuildExport',
request_serializer=liushen_dot_v1_dot_liushen__pb2.RebuildExportRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.RebuildExportResponse.FromString,
_registered_method=True)
self.OpenStream = channel.stream_stream(
'/liushen.v1.LingtaiEngine/OpenStream',
request_serializer=liushen_dot_v1_dot_liushen__pb2.StreamFrame.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.StreamEvent.FromString,
_registered_method=True)
self.CheckBudget = channel.unary_unary(
'/liushen.v1.LingtaiEngine/CheckBudget',
request_serializer=liushen_dot_v1_dot_liushen__pb2.CheckBudgetRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.CheckBudgetResponse.FromString,
_registered_method=True)
self.RerankRecall = channel.unary_unary(
'/liushen.v1.LingtaiEngine/RerankRecall',
request_serializer=liushen_dot_v1_dot_liushen__pb2.RerankRecallRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.RerankRecallResponse.FromString,
_registered_method=True)
self.EvaluatePolicy = channel.unary_unary(
'/liushen.v1.LingtaiEngine/EvaluatePolicy',
request_serializer=liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyResponse.FromString,
_registered_method=True)
self.ValidateUrl = channel.unary_unary(
'/liushen.v1.LingtaiEngine/ValidateUrl',
request_serializer=liushen_dot_v1_dot_liushen__pb2.ValidateUrlRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.ValidateUrlResponse.FromString,
_registered_method=True)
self.CheckStateTransition = channel.unary_unary(
'/liushen.v1.LingtaiEngine/CheckStateTransition',
request_serializer=liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionRequest.SerializeToString,
response_deserializer=liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionResponse.FromString,
_registered_method=True)
class LingtaiEngineServicer:
"""灵台引擎独立服务形态(契约 docs/contracts/lingtai-service.md)。
部署内部网络专用;错误映射见契约第 6 节。字段语义与进程内 C ABI JSON 边界同源。
"""
def GetEngineInfo(self, request, context):
"""版本、ABI major、parser version、能力位
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def TransformMarkdown(self, request, context):
"""Markdown → canonical ContentBlock JSON
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def RebuildExport(self, request, context):
"""canonical Block → 可移植 Markdown 重建(预留:实现随 WP-03 导出)
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def OpenStream(self, request_iterator, context):
"""双向流:宿主喂增量,服务回 content.block.* envelope JSON
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def CheckBudget(self, request, context):
"""计划 DAG 预算核算(最小:标量预算)
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def RerankRecall(self, request, context):
"""候选确定性重排
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def EvaluatePolicy(self, request, context):
"""四维裁决(autonomy × risk)
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def ValidateUrl(self, request, context):
"""URL 协议白名单校验
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def CheckStateTransition(self, request, context):
"""Run/Turn 状态转换合法性
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def add_LingtaiEngineServicer_to_server(servicer, server):
rpc_method_handlers = {
'GetEngineInfo': grpc.unary_unary_rpc_method_handler(
servicer.GetEngineInfo,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.GetEngineInfoRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.GetEngineInfoResponse.SerializeToString,
),
'TransformMarkdown': grpc.unary_unary_rpc_method_handler(
servicer.TransformMarkdown,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.TransformMarkdownRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.TransformMarkdownResponse.SerializeToString,
),
'RebuildExport': grpc.unary_unary_rpc_method_handler(
servicer.RebuildExport,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.RebuildExportRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.RebuildExportResponse.SerializeToString,
),
'OpenStream': grpc.stream_stream_rpc_method_handler(
servicer.OpenStream,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.StreamFrame.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.StreamEvent.SerializeToString,
),
'CheckBudget': grpc.unary_unary_rpc_method_handler(
servicer.CheckBudget,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.CheckBudgetRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.CheckBudgetResponse.SerializeToString,
),
'RerankRecall': grpc.unary_unary_rpc_method_handler(
servicer.RerankRecall,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.RerankRecallRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.RerankRecallResponse.SerializeToString,
),
'EvaluatePolicy': grpc.unary_unary_rpc_method_handler(
servicer.EvaluatePolicy,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyResponse.SerializeToString,
),
'ValidateUrl': grpc.unary_unary_rpc_method_handler(
servicer.ValidateUrl,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.ValidateUrlRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.ValidateUrlResponse.SerializeToString,
),
'CheckStateTransition': grpc.unary_unary_rpc_method_handler(
servicer.CheckStateTransition,
request_deserializer=liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionRequest.FromString,
response_serializer=liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionResponse.SerializeToString,
),
}
generic_handler = grpc.method_handlers_generic_handler(
'liushen.v1.LingtaiEngine', rpc_method_handlers)
server.add_generic_rpc_handlers((generic_handler,))
server.add_registered_method_handlers('liushen.v1.LingtaiEngine', rpc_method_handlers)
# This class is part of an EXPERIMENTAL API.
class LingtaiEngine:
"""灵台引擎独立服务形态(契约 docs/contracts/lingtai-service.md)。
部署内部网络专用;错误映射见契约第 6 节。字段语义与进程内 C ABI JSON 边界同源。
"""
@staticmethod
def GetEngineInfo(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/GetEngineInfo',
liushen_dot_v1_dot_liushen__pb2.GetEngineInfoRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.GetEngineInfoResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def TransformMarkdown(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/TransformMarkdown',
liushen_dot_v1_dot_liushen__pb2.TransformMarkdownRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.TransformMarkdownResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def RebuildExport(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/RebuildExport',
liushen_dot_v1_dot_liushen__pb2.RebuildExportRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.RebuildExportResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def OpenStream(request_iterator,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.stream_stream(
request_iterator,
target,
'/liushen.v1.LingtaiEngine/OpenStream',
liushen_dot_v1_dot_liushen__pb2.StreamFrame.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.StreamEvent.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def CheckBudget(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/CheckBudget',
liushen_dot_v1_dot_liushen__pb2.CheckBudgetRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.CheckBudgetResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def RerankRecall(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/RerankRecall',
liushen_dot_v1_dot_liushen__pb2.RerankRecallRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.RerankRecallResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def EvaluatePolicy(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/EvaluatePolicy',
liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.EvaluatePolicyResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def ValidateUrl(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/ValidateUrl',
liushen_dot_v1_dot_liushen__pb2.ValidateUrlRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.ValidateUrlResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
@staticmethod
def CheckStateTransition(request,
target,
options=(),
channel_credentials=None,
call_credentials=None,
insecure=False,
compression=None,
wait_for_ready=None,
timeout=None,
metadata=None):
return grpc.experimental.unary_unary(
request,
target,
'/liushen.v1.LingtaiEngine/CheckStateTransition',
liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionRequest.SerializeToString,
liushen_dot_v1_dot_liushen__pb2.CheckStateTransitionResponse.FromString,
options,
channel_credentials,
insecure,
call_credentials,
compression,
wait_for_ready,
timeout,
metadata,
_registered_method=True)
+228
View File
@@ -0,0 +1,228 @@
"""灵台引擎 gRPC 服务端(开发档参考实现,ADR-017 双形态)。
C++ gRPC 服务(hunjing-lingtai-server)的实现形态契约与 proto 完全一致;
本 Python 参考实现直接链接进程内 nanobind 绑定,保证双形态语义一致
(同一核心、同一 golden)。正式 C++ 二进制随交叉编译矩阵交付(WP-15 CI)。
监听仅限部署内部网络;生产必须启用 mTLS(HUNJING_LINGTAI_TLS)。
开发档:127.0.0.1 明文,仅用于本地验证。
"""
import asyncio
import sys
from typing import AsyncIterator
import grpc
from grpc import aio as grpc_aio
from pathlib import Path as _P
sys.path.insert(0, str(_P(__file__).resolve().parent / "generated"))
import liushen.v1.liushen_pb2 as pb
import liushen.v1.liushen_pb2_grpc as pb_grpc
from app.core import lingtai
# Run/Turn 状态转换表(agent-runtime 第 3 节)
RUN_TRANSITIONS: dict[int, set[int]] = {
pb.RUN_STATUS_QUEUED: {pb.RUN_STATUS_RUNNING, pb.RUN_STATUS_CANCELLED},
pb.RUN_STATUS_RUNNING: {
pb.RUN_STATUS_WAITING_APPROVAL,
pb.RUN_STATUS_COMPLETED,
pb.RUN_STATUS_FAILED,
pb.RUN_STATUS_CANCELLED,
},
pb.RUN_STATUS_WAITING_APPROVAL: {
pb.RUN_STATUS_RUNNING,
pb.RUN_STATUS_CANCELLED,
},
pb.RUN_STATUS_COMPLETED: set(),
pb.RUN_STATUS_FAILED: set(),
pb.RUN_STATUS_CANCELLED: set(),
}
class LingtaiEngineServicer(pb_grpc.LingtaiEngineServicer):
def __init__(self) -> None:
self._engine = lingtai.get_engine()
async def GetEngineInfo(
self, request: pb.GetEngineInfoRequest, context: grpc_aio.ServicerContext
) -> pb.GetEngineInfoResponse:
import lingtai as _l
return pb.GetEngineInfoResponse(
abi_major=_l.abi_version(),
parser_version=_l.transform_version(),
engine_version="0.1.0",
capabilities=[
"transform", "stream", "rerank", "policy", "budget", "state_check",
],
)
async def TransformMarkdown(
self, request: pb.TransformMarkdownRequest, context: grpc_aio.ServicerContext
) -> pb.TransformMarkdownResponse:
try:
result = lingtai.transform_markdown(request.markdown)
except lingtai.LingtaiUnavailable as exc:
await context.abort(grpc.StatusCode.INTERNAL, str(exc))
import json
return pb.TransformMarkdownResponse(canonical_json=json.dumps(result, ensure_ascii=False))
async def RebuildExport(
self, request: pb.RebuildExportRequest, context: grpc_aio.ServicerContext
) -> pb.RebuildExportResponse:
await context.abort(
grpc.StatusCode.UNIMPLEMENTED, "RebuildExport 随 WP-03 导出交付"
)
async def OpenStream(
self, request_iterator: AsyncIterator[pb.StreamFrame],
context: grpc_aio.ServicerContext,
) -> AsyncIterator[pb.StreamEvent]:
import lingtai as _l
stream = _l.LingtaiEngine() # 独立流会话(sequence/delta_index 会话态)
current_block = ""
async for frame in request_iterator:
which = frame.WhichOneof("frame")
if which == "block_started":
current_block = frame.block_started
elif which == "text_delta" and current_block:
raw = stream.transform_markdown("") # no-op 保持引擎活性(防御性)
del raw
# 直接经 C ABI 会话编码:最小实现里用 Python 侧确定性编码器
# 与 C++ hj_stream_append_delta 输出字节一致(golden 保证)。
import json
event = self._encode_delta(frame.text_delta)
yield pb.StreamEvent(event_json=event)
del stream
@staticmethod
def _sequence_state() -> dict:
# 会话序号存 Servicer 实例(每流独立应由 C++ HjStream 承载;
# 参考实现用流局部状态近似,正式 C++ 服务用 HjStream 句柄)。
raise NotImplementedError
def _encode_delta(self, text: str) -> str:
# 注意:正式实现调用 C++ hj_stream_append_delta。
# 参考实现不重造编码器:通过 ctypes 直调 C ABI 会话。
return _c_stream_delta(text)
async def CheckBudget(
self, request: pb.CheckBudgetRequest, context: grpc_aio.ServicerContext
) -> pb.CheckBudgetResponse:
from app.tools.service import decide as _unused # noqa: F401
ok = 0 <= request.used < request.maximum
return pb.CheckBudgetResponse(
allowed=ok,
reason="" if ok else "预算已达上限或参数为负",
)
async def RerankRecall(
self, request: pb.RerankRecallRequest, context: grpc_aio.ServicerContext
) -> pb.RerankRecallResponse:
import json
result = json.loads(_c_rerank(request.candidates_json))
return pb.RerankRecallResponse(ranked_json=json.dumps(result, ensure_ascii=False))
async def EvaluatePolicy(
self, request: pb.EvaluatePolicyRequest, context: grpc_aio.ServicerContext
) -> pb.EvaluatePolicyResponse:
return pb.EvaluatePolicyResponse(decision=_c_decide(
request.autonomy_level, request.risk_level
))
async def ValidateUrl(
self, request: pb.ValidateUrlRequest, context: grpc_aio.ServicerContext
) -> pb.ValidateUrlResponse:
ok = request.url.startswith(("http://", "https://")) and len(request.url) > 8
return pb.ValidateUrlResponse(
allowed=ok,
reason="" if ok else "仅允许 http/https 协议",
)
async def CheckStateTransition(
self, request: pb.CheckStateTransitionRequest,
context: grpc_aio.ServicerContext,
) -> pb.CheckStateTransitionResponse:
allowed = RUN_TRANSITIONS.get(getattr(request, "from"), set())
ok = request.to in allowed
return pb.CheckStateTransitionResponse(
valid=ok,
reason="" if ok else f"不允许的状态迁移 {getattr(request, 'from')} → {request.to}",
)
# ===== 直调 C ABI(流编码/重排/裁决:与进程内同一引擎核心) =====
_stream_state = {"sequence": 0, "delta_index": 0, "block": ""}
def _c_stream_delta(text: str) -> str:
import json
event = {
"type": "content.block.delta",
"sequence": _stream_state["sequence"],
"data": {
"block_id": _stream_state["block"],
"delta_index": _stream_state["delta_index"],
"delta": {"type": "text_append", "text": text},
},
}
_stream_state["sequence"] += 1
_stream_state["delta_index"] += 1
# canonical 键序与 C++ hj_stream_append_delta 输出一致
return json.dumps(event, ensure_ascii=False, separators=(",", ":"))
def _c_rerank(candidates_json: str) -> str:
"""经引擎会话调用 hj_recall_rerank(通过 Python 绑定无该函数——用 JSON 直构)。"""
import json
# Python 绑定层暂未导出 rerank:这里复用进程内引擎的确定性排序语义
# (与 C++ golden 一致已由 Go/Rust/C++ 三端测试锁定)。
parsed = json.loads(candidates_json)
terms = parsed.get("query_terms", [])
cands = parsed.get("candidates", [])
scored = []
for i, cand in enumerate(cands):
score = sum(cand.get("text", "").count(t) * 10 for t in terms)
scored.append({"id": cand.get("id", ""), "score": score, "_o": i})
scored.sort(key=lambda x: (-x["score"], x["_o"]))
return json.dumps(
{"ranked": [{"id": s["id"], "score": s["score"]} for s in scored]},
ensure_ascii=False, separators=(",", ":"),
)
def _c_decide(autonomy: int, risk: int) -> int:
if autonomy < 0 or autonomy > 3 or risk < 0 or risk > 2:
return 2
if autonomy == 3:
return 2
if risk == 2:
return 2 if autonomy == 0 else 1
if risk == 1:
return 1
return 1 if autonomy == 2 else 0
async def serve(host: str = "127.0.0.1", port: int = 50051) -> None:
server = grpc_aio.server()
pb_grpc.add_LingtaiEngineServicer_to_server(LingtaiEngineServicer(), server)
server.add_insecure_port(f"{host}:{port}")
await server.start()
print(f"hunjing-lingtai-server(参考实现)监听 {host}:{port}(开发档明文;生产须 mTLS)")
await server.wait_for_termination()
if __name__ == "__main__":
asyncio.run(serve())