legatus (Sovetnik)

Legatus 翻译为中文是“使者”或“代表”。

JSON-RPC 标准输入输出 ↔ HTTP 代理\ _在两个世界之间传递信息的信使代理_

Legatus 翻译成中文是“使者”或“使节”。这个词在拉丁语中常用来指派往某地执行任务或传达信息的官员或代表。 这是一个极简、无状态的桥接器，它能将标准输入（STDIN）中的对话转换为HTTP操作。它体现了环境（Umwelt）感知-行动统一的原则：每个请求都经过一个完整的功能循环——感知、认知、行动——之后，才以有意义的响应返回。

Legatus 存在的原因

Legatus解决了一个根本性问题： 如何让任何进程通过STDIO使用JSON-RPC进行通信，同时将执行委托给HTTP领域。

用例：

• 编辑器集成通过HTTP将您的编辑器连接到语言服务器
• 命令行界面工具构建用于代理HTTP API的命令行工具
• 代理通信启用进程通过标准流进行通信
• 测试在shell脚本中与HTTP JSON-RPC服务器进行交互

Legatus不仅仅是一个工具；它是一种 翻译仪式 — 一种规范化的智能体与世界通信模式。

快速入门

# Build the escript
mix escript.install hex legatus

# or
git clone git@github.com:sovetnik/legatus.git
mix escript.build

# Start your JSON-RPC HTTP server (example on port 4000)
# Then send a request:
echo '{"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}' | \
  ./legatus http://localhost:4000/rpc

预期输出：

{"jsonrpc":"2.0","result":5,"id":1}

就是这样。输入一行，输出一行。STDIO 转换为 HTTP，HTTP 转换为 STDIO。

哲学：环境（Umwelt）建筑学

该建筑遵循了雅各布·冯·厄克塞尔（Jakob von Uexküll）的（设计理念/原则）。 环境 概念——生物在其自身的“主观宇宙”中感知和行动：

• 外界 — 外部世界（STDIO流）
• 品牌世界 — 感知层（请求验证）
• 作用领域 — 动作层（HTTP传输）
• 环境 — 完整的功能循环（管道协调员）
• “Geist”在中文中可以翻译为“精神”或“鬼魂”，具体含义取决于上下文。如果是指一种抽象的精神或理念，通常翻译为“精神”；如果是指超自然的存在或幽灵，则翻译为“鬼魂” — 动画原理（主循环）

Legatus（使节或代表）在……范围内行事 “Clausura Operationalis” 可以翻译为“运营关闭”或“业务终止”，具体取决于上下文和语境。在商业或项目管理中，这通常指的是某个运营活动、项目或服务的结束阶段 ——它只知道它所感知的世界，并且对此采取连贯一致的行动。它的简单并非限制，而是自律。

使用模式

作为Escript（推荐用于生产环境）

mix escript.build
./legatus http://localhost:4000/rpc

作为混合任务（用于开发）

mix legatus http://localhost:4000/rpc

使用承载令牌认证

当您的上游服务器需要身份验证时，请通过环境变量传递令牌：

# Using escript
token=your_secret_token ./legatus http://localhost:4000/rpc

# Using mix task
token=your_secret_token mix legatus http://localhost:4000/rpc

Legatus 会自动添加 Authorization: Bearer 在所有HTTP请求中添加头部信息。

编辑器集成示例（Zed、Claude Code 等）：

{
  "context_servers": {
    "my_server": {
      "source": "custom",
      "enabled": true,
      "command": "legatus",
      "args": ["http://localhost:4000/rpc"],
      "env": {"token": "your_secret_token"}
    }
  }
}

管道流量

每个请求都经历完整的Umwelt（环境）周期：

STDIN → Geist.loop → Aussenwelt.receptio → Merkwelt.percipere → 
Wirkwelt.portare → Aussenwelt.profanatio → STDOUT

每支箭头都代表了一种意义的转变，而不仅仅是数据的转变。

建筑

数据流

该管道使用带标签的元组来追踪数据状态：

1. “Receptio”的中文翻译是“接受”或“接纳”。 (外部世界)：解析JSON\

{:phaenomenon, map} | {:fiasco, json_error}

1. “Percipere”在拉丁语中意为“感知”或“察觉”。 (Merkwelt): 验证请求\

{:actio, map} | {:fiasco, error_map}

1. 带来，携带 (作用域)：HTTP传输\

{:gloria, map} | {:fiasco, error_map} | {:silentium, map}

1. 亵渎（Profanatio） (外部世界)：格式输出\

{:gloria, json} | {:fiasco, json} | {:silentium, "Nullius in verba"}

1. 发射 (Geist): 写入 STDOUT 或跳过

模块职责

• Legatus 可以翻译为“使者”或“代表”，具体含义取决于上下文。在古罗马语境中，它通常指的是被派遣执行特定任务或代表某人或某机构行事的人。 — 入口点和配置
• “Geist”在中文中可以翻译为“精神”或“灵魂”，具体含义取决于上下文。在德语中，“Geist”通常指的是某种抽象的精神、灵魂或智能的存在，也可以指某种特定的气质或风度 — 主循环（STDIN → STDOUT 循环）
• 外界 — 输入/输出边界（解析/格式化JSON）
• Merkwelt 翻译成中文是“标志世界”或“品牌世界”。这个词汇通常用来描述一个由各种标志、品牌或符号构成的视觉或概念世界，可能用于设计、市场营销或文化研究等领域 — 请求验证（符合JSON-RPC规范）
• "Wirkwelt" 在德语中通常指的是“作用领域”或“影响范围”，具体翻译可能根据上下文有所调整。在中文中，可以翻译为“作用领域”、“影响范围”或“功能领域”等，以表达该词所蕴含的含义。 — HTTP 协调器（将传输响应解释为环境概念）
• 作用领域.Httpc（或可理解为“功能范围.Httpc”，具体翻译可能根据上下文有所调整） — HTTP传输（纯POST，包含状态/正文）
• 《编年史》（Chronica） — 日志记录（标准错误诊断）

传输层设计

Wirkwelt遵循清晰的职责分离原则：

“Wirkwelt”行为契约：

@callback post(request :: map()) :: 
  {status :: pos_integer(), body :: map() | String.t()} | {:error, reason :: term()}

• 传输（Httpc）返回原始HTTP响应 {200, body} 或者 {:error, reason}
• 协调员（影响领域）将回答解释为 {:gloria, map()}， {:silentium, map()}或者 {:fiasco, map()}

这种设计使得无需更改业务逻辑即可轻松添加新的HTTP适配器（如Finch、Hackney）。

错误处理

所有错误均符合JSON-RPC规范：

• -32700 解析错误（JSON 无效）
• -32600 无效请求（缺少方法）
• -32000 HTTP 错误（4xx/5xx）
• -32001 传输错误（连接被拒绝）

配置

Legatus 通过以下方式配置 命令行参数 — 无需静态配置：

mix legatus http://localhost:4000/rpc

上游URL在运行时通过动态方式设置 Application.put_env/3。

设计原则

1. 带标签的元组 对于明确的数据流
2. 纯函数 在可能的情况下（在边界进行输入/输出）
3. 模式匹配 “over conditionals”可以翻译为“关于条件”或“在条件之上（考虑）”。具体翻译取决于上下文，但通常指的是对条件进行讨论、分析或基于条件进行某种操作或判断
4. 关注点分离（或职责分离） （解析、验证、传输、格式化）
5. 可测试性 通过依赖注入

JSON-RPC 支持

请求：

• ✅ 标准请求，附带 id
• ✅ 通知（无 id)
• ✅ 批处理（请求的数组）

回复

• ✅ 成功响应（result)
• ✅ 错误响应（error)
• ✅ HTTP 204 处理（通知）
• ✅ 批量响应

局限性

• 基于STDIO（每行一个请求）
• 仅支持HTTP POST（不支持WebSocket/SSE）
• 没有内置的重试逻辑
• 单一上游服务器

许可证

请参阅LICENSE文件。

词源

• “Legatus”在中文中可以翻译为“使节”或“使者”，具体含义可能根据上下文有所不同，但通常指的是被派遣去执行任务或传达信息的代表或官员。 (拉丁语) — 使者，大使，信使
• 环境 (德语) — 环境，“以自我为中心的世界”
• “Geist”在中文中可以翻译为“精神”或“灵魂”，具体含义取决于上下文。它既可以指一种抽象的精神力量，也可以指某种特定的精神风貌或灵魂状态 (德语) — 精神，心智，激发活力的原则
• 外部世界 (德语) — 外界
• Merkwelt 翻译成中文是“品牌世界”或“品牌宇宙”。这个词汇结合了“Merk”（品牌）和“Welt”（世界/宇宙）两个词，用来描述一个品牌所创造或所处的广阔市场或环境 (德语) —— 感知世界
• 作用领域（或影响范围） (德语) — 行动的世界

下一步

进一步探索：

• 阅读 umwelt.dev/docs（可翻译为：“环境开发文档”或根据具体语境简化为“环境文档”，但直接保留原样“umwelt.dev/docs”在技术文档或网站链接中更为常见） 为哲学基础（或：奠定哲学基础）
• 加入讨论 问题
• 通过以下方式贡献： 拉取请求（或合并请求）

相关项目：

• 骷髅 — 代理系统的认知基础
• “Reticulum Universalis”在中文中可以翻译为“全网状结构”或“通用网状结构”，具体翻译可能根据上下文有所调整。这个术语可能用于描述某种网络状的结构或系统，其“通用”一词表明它具有广泛适用性或普遍存在的特性 — 分布式代理的通信模式

Legatus是一项实验性的 运营关闭 — 每个组件都使用着相同的感知与行动语言。如果你对此有共鸣，欢迎加入我们的讨论。