给 tinystruct 加了一层 TypeSafe 的自然语言调用

最近给框架 tinystruct 做了一个有点好玩的东西。

起因

现在很多 AI Agent 的常见模式都是：```
用户
↓
LLM
↓
Tool Calling
↓
生成参数
↓
执行 Tool
```但我一直觉得这里有一个核心问题：如果业务代码本来就是确定且类型严密的，为什么还要让 LLM 去“重新编程”？

在 tinystruct 框架中，我们本来就可以这样定义业务方法：```
@Action(
value = "create-user",
description = "Create a new user account.",
arguments = {
@Argument(key = "name", description = "The user's name."),
@Argument(key = "role", description = "The user's role.")
}
)
public String createUser(String name, Role role) {
// ...
}
```这本身已经是一个结构非常清晰的 Typed Action。

因此，我尝试把逻辑反转过来：```
Natural Language
↓
Jev
↓
Semantic Decision
↓
tinystruct @Action
↓
Existing Java Code
```> 核心思路：

AI 不需要负责编写代码，也不需要重新动态设计 Workflow 。它只负责理解用户意图——匹配已有能力并提取所需强类型参数。

一个直观的例子

假设用户说：

"帮我创建一个叫 James 的管理员账号。"

系统并不是放任 LLM 自由生成松散的 JSON：```
{
"tool": "createUser",
"name": "James",
"role": "ADMIN"
}
```而是将整个流程拆解为类型安全的决策（ TypeSafe Decisions ）：

- 确定动作（ Which action?）

- create-user

- delete-user

- update-user

- list-users

- 确定参数类型（ Role?）

- ADMIN

- EDITOR

- VIEWER

• 最终直接安全调用：```

createUser("James", Role.ADMIN);
```在此模式下，AI 更像是一个 programmable common-sense layer （可编程的常识层），而不是一个拥有任意写权限、行为难以预测的 Agent 。

为什么选择 Jev ？

在这一套机制中，我比较看重 TypeSafe / Jev 的一个特质：它不是让大模型返回一个任意字符串，而是针对预定义的 choices 给出确定性决策。

这与传统后端系统的设计理念非常契合。

• 传统 Java 系统：```

enum Role {
ADMIN,
EDITOR,
VIEWER
}
```- 传统 AI 世界常返回：

- "admin"

- "administrator"

- "super admin"

- "maybe admin?"

(后端随后不得不编写大量 parsing 、validation 、retry 等胶水代码)

如果模型最终只需要在已有类型集合中做 decision ，整体链路会简化非常多：```
LLM
│
│ semantic decision
▼
Typed Choice
│
▼
Typed Argument
│
▼
Java Method

更重要的是：无需重写已有业务代码

这也是该设计最实用的地方。对于已有的 tinystruct application：

- HTTP 接口

- CLI 终端命令

- MCP (Model Context Protocol)

所有现有的 `@Action` 均可直接复用。引入新层后，只是给系统增加了一个全新的交互维度：```
Natural Language ──► tinystruct-typesafe ──► @Action
```整体架构拓扑如下：```
                 ┌── HTTP
                 │
                 ├── CLI
                 │
User ────────────┼── MCP
                 │
                 └── Natural Language
                          │
                         Jev
                          │
                   Semantic Dispatcher
                          │
                          ▼
                       @Action
                          │
                          ▼
                     Existing Code

边界与权限：AI 不应该拥有过多权限

为了让生产落地更加可控，SDK 中实现了一系列偏向工程防线的机制：

- Action allowlist （操作白名单）

- Confidence threshold （置信度阈值机制）

- Per-action threshold （单动作阈值定制）

- Argument validation （强参数校验）

- Confirmation （危险动作确认流）

- Principal resolver （身份解析鉴权）

- Cache （语义与决策缓存）

- Metrics （调用指标监控）

- Workflow persistence （工作流持久化）

特别是针对 Destructive Action （破坏性操作）。例如当用户输入：

"删除用户 James"

AI 可以准确将其解析为 delete-user 动作，但这绝不意味着系统应该直接执行，而是介入严格的安全策略链条：```
AI decision
↓
Policy
↓
Confirmation
↓
Action
```从而将 AI 的作用范围牢牢收敛在预设的安全边界内。

总结：一种新的 Agent 思考模式

过去我们常常把 Agent 想象为：

“给大模型一个庞大的工具箱，让它自行推演和规划下一步该做什么。”

但我现在更倾向于：

“代码定义确定性能力，AI 负责理解真实意图。”

这也是本项目目前最想验证的方向：如果传统 Java 系统已经具备清晰的 typed actions ，AI 能否以最小侵入的方式，直接成为它的一层高质量自然语言入口？

目前项目仍处于早期迭代阶段，已内置实现了 client 、semantic dispatcher 、question generation 、policy 、cache 、metrics 以及 workflow persistence 等核心组件。

- 源码仓库：https://github.com/tinystruct/tinystruct-typesafe-sdk/

也非常期待各位在从事 Java + AI / Agent / MCP / Tool Calling 方向的开发者一起交流探讨！