# lingya-agent

**Repository Path**: lingya-ai/lingya-agent

## Basic Information

- **Project Name**: lingya-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: codex/faithful-extraction
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lingya-agent

`lingya-agent` 是从现有商业仓库中抽离的 Kotlin Agent 运行时。项目以已经运行的 Agent 代码为唯一基线，保留 ReAct、消息上下文、工具协议、Skill、MCP、内置工具和模型 Provider 的原有行为，仅替换阻碍独立发布的商业依赖边界。

当前版本为 `0.1.0-SNAPSHOT`，使用 JDK 25、Kotlin 2.3.21 和 Gradle 9.6.1，许可证为 Apache-2.0。

> 本仓库仍处于抽离阶段。文档中的“边界”是模块必须满足的稳定约束；只有独立构建、迁移真实性校验和敏感信息审计全部通过后，才表示抽离完成。

## 架构原则

- 迁移遵循“复制实现、替换依赖边界”，不以重写的简化框架代替原实现。
- 公共契约与具体基础设施分离。Agent 内核面向接口工作，不感知数据库、Redis、对象存储或商业业务服务。
- 工作区是文件能力的唯一入口。Agent 和内置工具不得自行拼接本地绝对路径。
- Provider 保留各供应商已有的协议实现，公共 HTTP/SSE 能力只下沉到共享 Provider 模块。
- Spring Boot、文件系统、MCP SDK 和具体云供应商都是可选集成，不能反向进入公共 API。
- `cc.lingya.xiaolingtong.*`、JPA、Redisson、商业 OSS 服务、租户上下文和内部事件不得出现在最终公开制品中。

## 模块依赖方向

```text
agent-workspace-local ──→ agent-workspace-api
agent-api             ──→ agent-workspace-api
agent-core            ──→ agent-api + agent-workspace-api
agent-mcp             ──→ agent-api + agent-core + agent-workspace-api
agent-tools-builtin   ──→ agent-api + agent-core + agent-mcp + agent-workspace-api
agent-provider-http   ──→ agent-api
各云 Provider          ──→ agent-provider-http
Spring Boot Starter   ──→ agent-core + agent-tools-builtin + agent-workspace-local
agent-testing         ──→ agent-api + agent-workspace-api
examples              ──→ 只消费公开模块
agent-bom             ──→ 统一公开制品版本
```

箭头表示左侧模块依赖右侧模块。实际依赖声明以各模块的 `build.gradle.kts` 为准；新增依赖不得突破下文规定的边界。

## 模块定义与边界

### `agent-workspace-api`

工作区的纯契约模块，包名前缀为 `cc.lingya.agent.workspace`。

负责定义：

- `WorkspaceManager` 和 `WorkspaceSession` 生命周期。
- `begin → 文件操作 → commit`，以及异常路径的 `abort`。
- staging overlay、逻辑路径、版本、文件变更、提交结果和不可变发布引用等值类型。
- 流式内容读写与输入文件导入协议。

边界：

- 不包含本地文件系统、数据库或对象存储实现。
- 不暴露 Spring `Resource`、JPA 实体或供应商 SDK 类型。
- 逻辑路径统一使用 `/` 分隔，具体实现必须负责路径穿越、符号链接逃逸和大小写冲突防护。

### `agent-api`

面向应用和扩展实现者的公共 Agent 契约，主要包名前缀为 `cc.lingya.agent`。

负责定义：

- 模型、消息、用量、流式事件和公开结果类型。
- Agent 请求、响应、取消和执行状态等稳定协议。
- 工具描述、调用参数、结果和动态 JSON 边界。
- Provider 与核心共同使用的模型身份、配置及异常协议。
- 需要由调用方实现的公开扩展端口。

边界：

- 可以引用 `agent-workspace-api` 中的工作区契约。
- 不包含 ReAct 状态机、工具实现、MCP SDK 客户端或任何 Provider HTTP 实现。
- 公共结构必须使用明确类型；动态协议数据使用 `JsonNode`，不得以 `Map<String, Any?>` 充当稳定返回模型。
- 不依赖 Spring、JPA、Redis、OSS 或商业包。

### `agent-core`

从商业仓库迁移的 Agent 运行时内核，主要包名前缀为 `cc.lingya.agent.agents`。

负责定义和实现：

- ReAct 推理循环、执行策略、状态机和生命周期。
- 消息轮次、上下文装配、压缩、Snip 协作和 Token 估算。
- 工具注册、ToolPolicy、拦截器、后处理器和工具循环检测。
- Skill 运行时、Prompt 模板、运行期 SPI 和会话内存实现。
- 用户提问、计划审批等内核所需 Store 契约及本地内存语义。
- 会话执行租约、事件发布、审计和商业持久化替代端口。

边界：

- 依赖 `agent-api` 与 `agent-workspace-api`，只通过工作区契约参与消息级提交。
- 不依赖 `agent-tools-builtin`，需要识别内置工具时只能使用稳定工具协议名或核心扩展端口。
- 不依赖 `agent-mcp` 的 SDK 实现、`agent-workspace-local`、Spring 或任何云 Provider。
- 原实现中的 Spring 全局 Bean、数据库、Redis、OSS、租户上下文和商业事件必须替换为构造注入、上下文属性或 SPI。
- JSON 修复和 Prompt 模板解析属于内核内部能力，不作为单独公开制品。

### `agent-workspace-local`

`agent-workspace-api` 的本地文件系统实现，包名前缀为 `cc.lingya.agent.workspace.local`。

负责实现：

- 消息级 staging 和基线版本 overlay。
- tombstone 删除可见性、不可变版本和完整 manifest。
- 工作区内 HEAD 冲突检测、锁内提交和 HEAD 原子替换。
- SHA-256、大小、媒体类型以及指向不可变版本文件的本地发布引用。
- 过期 staging 清理和未完成版本隔离。

边界：

- 只实现单 JVM 内的并发安全，不承诺多进程或分布式写入一致性。
- 不承担数据库记录、OSS 上传、租户隔离和商业版本恢复任务。
- 不允许通过符号链接或路径规范化缺陷逃逸工作区根目录。
- 其他存储实现应新增模块并实现 `agent-workspace-api`，不能把云存储逻辑塞入本模块。

本地布局如下：

```text
{workspaceRoot}/{workspaceId}/
  HEAD
  versions/{versionId}/manifest.json
  versions/{versionId}/files/**
  staging/{sessionId}/files/**
  staging/{sessionId}/tombstones.json
```

### `agent-mcp`

MCP 客户端与协议适配模块，包名前缀主要为 `cc.lingya.agent.mcp` 及迁移保留的 `cc.lingya.agent.agents.*.mcp`。

负责实现：

- MCP Server 注册、连接生命周期和能力发现。
- Tool、Resource、Resource Template 与 Prompt 的协议转换。
- MCP SDK 内容到 Agent 消息、工具结果和工作区内容的转换。
- 文本、二进制和媒体资源的有界处理。

边界：

- 依赖核心的 MCP 中立契约，但 MCP SDK 类型不能泄漏到 `agent-api` 或 `agent-core` 的公开签名。
- MCP 资源和 Prompt 中的文件内容必须写入当前 `WorkspaceSession` staging。
- 不包含商业数据库配置、密钥加密、Redis 状态或管理后台接口。
- Server 配置由程序化配置或本地配置文件提供。

### `agent-tools-builtin`

现有八组内置工具的真实实现模块，包名前缀为 `cc.lingya.agent.agents.tools`。

该模块保留 `BuiltInToolOptions` 的分组启用语义，默认能力包括：

| 工具组 | 职责 | 关键边界 |
|---|---|---|
| `FILES` | 文本读取、数据预览、创建、更新、替换、元数据、列举和删除 | 只通过 `WorkspaceSession` 操作；删除保持高风险动作 |
| `SKILLS` | Skill 检索、加载、资源列举、读取及复制 | Loader 面向 classpath/本地目录；二进制资源写入 staging |
| `MCP_TOOLS` | MCP 工具、资源、模板和 Prompt 的检索与加载 | 媒体内容经工作区发布；不持有商业 MCP 配置 |
| `SNIP` | 模型主动裁剪无用上下文 | 状态只属于当前 Agent 会话，并保护近期轮次和关键工具消息 |
| `TASKS` | 会话内任务创建、查询、更新和依赖管理 | 默认内存状态；保持原任务状态机和归档语义 |
| `ASK_USER_QUESTION` | 创建问题并等待用户回答 | 保持 `CompletableFuture + TTL + 消息身份校验`，存储由契约替换 |
| `PLAN_MODE` | 计划创建、修改、提交和审批 | 计划写入当前工作区；保持 Future、TTL、拒绝后重提和 ToolPolicy 限制 |
| `SUBAGENT` | `GENERAL_PURPOSE` 与 `FORK` 子 Agent | 同进程执行、继承取消和工作区；禁止递归调用 subagent |

边界：

- 依赖 `agent-core`、`agent-workspace-api` 和 `agent-mcp` 提供的契约。
- 工具名称、输入 Schema、`ToolAction`、输出结构和边界行为属于兼容协议，修改时必须有对应契约测试。
- 文件工具不得直接依赖 `agent-workspace-local`，以便调用方替换工作区实现。
- 不包含 JPA Skill、Redisson Store、商业文件服务、产品 UI 事件或父子会话数据库关系。

### `agent-provider-http`

八个云 Provider 共用的传输与错误处理基础，包名前缀为 `cc.lingya.agent.model_provider`。

负责实现：

- JDK HTTP 请求、SSE 解码、流式聚合和取消传播。
- 通用鉴权头、错误响应解析、可重试/不可重试异常分类。
- OpenAI 兼容协议的共享模型与转换逻辑。
- Provider 公共限流、重试、模型发现和上下文窗口超限识别。

边界：

- 只提供真实 Provider 之间可以共享的机制，不吞并供应商特有协议。
- API Key 只能来自显式配置或环境变量。
- 不接入商业密钥组、加密服务、Redis 限流或数据库模型配置。
- 不依赖 `agent-core` 的 ReAct 实现、内置工具或工作区实现。

### 云 Provider 模块

各 Provider 模块依赖 `agent-provider-http`，保留现有供应商协议、请求响应模型、鉴权和流式行为。

| 模块 | 能力边界 |
|---|---|
| `agent-provider-openai` | 对话、向量、图片 |
| `agent-provider-anthropic` | 对话 |
| `agent-provider-deepseek` | 对话 |
| `agent-provider-kimi` | 对话 |
| `agent-provider-minimax` | 对话、向量、图片 |
| `agent-provider-dashscope` | 对话、向量、图片 |
| `agent-provider-zhipu` | 对话、向量、图片 |
| `agent-provider-jimeng` | 图片 |

边界：

- 供应商专有 DTO、错误码和协议转换留在对应模块。
- 不允许用只转发到一个“通用 Provider”的薄包装替代现有真实实现。
- 测试使用 Mock HTTP/SSE，不读取或调用真实密钥。
- 消费者按需显式添加 Provider 依赖；Starter 不默认引入所有供应商。

### `agent-spring-boot-starter`

Spring Boot 的可选装配层，包名前缀为 `cc.lingya.agent.spring`。

负责实现：

- `lingya.agent.*` 配置绑定。
- 条件化装配 Agent、本地工作区、内存问答/审批 Store 和同进程子 Agent。
- 暴露可被业务应用替换的契约 Bean。

边界：

- Spring 注解和自动配置只能存在于该模块。
- 不引入商业应用配置、Controller、JPA Repository 或租户认证体系。
- Provider 仍由消费者显式选择，Starter 不替应用决定供应商。

### `agent-testing`

面向所有模块消费者的测试夹具模块。

负责提供：

- Chat/Embedding/Image 模型桩。
- 工具桩与调用记录。
- 工作区契约夹具。
- Agent 事件顺序和结果断言。

边界：

- 不包含生产运行时状态或真实网络访问。
- 生产模块不得依赖其测试实现；仅测试源集和示例可以消费。

### `agent-bom`

公开 Maven 制品的版本约束模块。

负责统一 `cc.lingya.agent` 下所有可发布模块的版本，使消费者可以通过 BOM 对齐依赖。

边界：

- 只声明版本约束，不包含代码或传递具体运行时实现。
- 示例模块不作为公开库约束发布。

### `examples/cli`

无 Spring 的最小可运行示例，用于演示显式装配模型、内置工具、本地工作区，以及在控制台提交用户回答和计划审批。

边界：示例只能消费公开 API，不得引用模块内部实现、商业仓库路径或真实密钥。

### `examples/spring-boot`

基于 Starter 的最小 Spring Boot 示例，用于验证配置绑定、条件装配和 Bean 替换入口。

边界：不承载生产业务，不引入商业数据库、认证、Redis 或对象存储配置。

## Kotlin 包命名

- 公共根包统一为 `cc.lingya.agent`。
- 工作区公共契约使用 `cc.lingya.agent.workspace`，本地实现使用 `cc.lingya.agent.workspace.local`。
- Agent 运行时沿用迁移后的 `cc.lingya.agent.agents` 领域结构，以便核对原文件与新文件。
- Provider 沿用 `cc.lingya.agent.model_provider`，供应商专有实现位于各自子包。
- Spring Boot 自动配置使用 `cc.lingya.agent.spring`。
- 新增公开类型原则上一个 Kotlin 文件只定义一个顶层类型，并补齐 KDoc。

## 依赖选择示例

仅使用核心契约：

```kotlin
dependencies {
    implementation(platform("cc.lingya.agent:agent-bom:0.1.0-SNAPSHOT"))
    implementation("cc.lingya.agent:agent-core")
}
```

使用内置工具和本地工作区：

```kotlin
dependencies {
    implementation(platform("cc.lingya.agent:agent-bom:0.1.0-SNAPSHOT"))
    implementation("cc.lingya.agent:agent-core")
    implementation("cc.lingya.agent:agent-tools-builtin")
    implementation("cc.lingya.agent:agent-workspace-local")
}
```

Provider 按需选择，例如：

```kotlin
dependencies {
    implementation(platform("cc.lingya.agent:agent-bom:0.1.0-SNAPSHOT"))
    implementation("cc.lingya.agent:agent-provider-openai")
}
```

## 构建与本地发布

```shell
./gradlew clean build
./gradlew publishToMavenLocal
./gradlew :examples:cli:run
```

所有公开库模块应生成 sources/Javadoc JAR 和 Maven POM。本阶段只允许发布到 Maven Local，不推送 GitHub，也不发布 Maven Central。

抽离完成时，Gradle Wrapper 下载地址、插件仓库和依赖仓库必须使用与商业项目一致的腾讯镜像配置；独立构建不得回退到商业仓库、复合构建或绝对源码路径。

## 抽离验收

完成状态至少需要以下证据：

- 迁移清单覆盖商业仓库基线中的每个文件，并记录迁移目标或排除理由。
- 关键公开 API、八组工具 Schema、Prompt 和行为测试可以与原实现对照。
- 工作区 staging、abort、不可变版本、HEAD 冲突、路径安全和残留清理测试通过。
- 用户问答、计划审批、子 Agent、ReAct 和各 Provider 的定向契约测试通过。
- 扫描确认公开制品不包含商业包名、凭证、数据库、Redis、OSS 或内部域名。
- 项目不依赖商业仓库源码、复合构建、符号链接或绝对源码路径。
- `clean build` 与 `publishToMavenLocal` 独立通过，且商业仓库任务前后状态一致。