diff --git a/README.md b/README.md index 065d1997..54c40c3b 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,155 @@ # Partner -Partner 是一个实验性的多模块智能体框架，关注 **长期上下文管理、跨模块协同以及行为驱动的系统演化**。 +## 项目介绍 -与强调单次推理或单一能力的智能体实现不同，Partner 将重点放在： +> 当前项目仍处在实验和快速迭代阶段，部分模块已经形成稳定边界，部分模块仍在调整 -- 结构化记忆的选择、更新与长期组织； -- 感知、行动与记忆模块之间的并发协作； -- 在多轮交互中维持稳定、可演进的系统行为。 +基于 Java/Kotlin 的模块化 AI Agent Runtime，围绕动态上下文工作空间、可干预的行动链执行、存储与组织解耦的记忆实现，构建支持多模块异步协作的可扩展 +Agent 运行内核。 -该项目仍处于早期实验阶段，核心目标是探索一种 **可扩展、可重组的智能体系统结构**，而非给出最终形态的“通用智能”实现。 +![Partner 架构总览](doc/assets/partner-overview.png) -## 流程参考 - -### 整体流程 - -```mermaid ---- -config: - layout: elk - elk: - nodePlacementStrategy: LINEAR_SEGMENTS --- -flowchart TD +## 项目启动 - Gate[Agent 网关] - Core[主模块] - Adapter[适配器] +### 环境要求 - Gate <--> Adapter +- JDK 21 +- Maven 3.x - Adapter --> Mem.Pre - Adapter --> Per.Pre - Adapter --> Act.Pre +### 启动项目 - Mem.Pre --> Core - Per.Pre --> Core - Act.Pre --> Core +#### 手动准备环境并启动 - Core --> |异步| Mem.Post - Core --> |异步| Per.Post - Core --> |异步| Act.Post +##### 克隆项目并构建 - Core --> |异步响应| Adapter - - subgraph Pre [前置流程.并发执行] - direction TB - Mem.Pre[记忆模块.选择] - Per.Pre[感知模块.选择] - Act.Pre[动作模块.规划] - end - - subgraph Post [后置流程] - direction TB - Mem.Post[记忆模块.更新] - Per.Post[感知模块.更新] - Act.Post[动作模块.分发] - end +```bash +git clone https://github.com/slhaf/Partner +cd Partner +mvn clean package -DskipTests ``` -### 模块流程参考 +> 当前项目仍处在快速迭代阶段，部分测试依赖尚未稳定的运行时行为。若目标只是从源码构建可运行 jar，推荐先使用 `-DskipTests` +> 跳过测试。 -- [记忆模块](doc/architechture/memory.md) -- [感知模块](doc/architechture/perceive.md) -- [行动模块](doc/architechture/action.md) (尚未完工) +构建完成后，主程序 jar 位于： -## 核心结构 +``` +Partner-Core/target/Partner-Core-0.5.0.jar +``` -### 主体部分 +##### 准备必需配置 -#### 结构化记忆系统 +Partner 默认从 `~/.partner` 读取运行时配置，也可以通过 `PARTNER_HOME` 指定其他目录： -构建以**主题树+记忆切片**为基础的记忆图谱. +```bash +export PARTNER_HOME="$HOME/.partner" +mkdir -p "$PARTNER_HOME/config" +``` -单个主题节点下存在多级子主题。每段对话切分为`MemorySlice`，通过前后序引用确保切片之间的上下文连续, 通过`relatedTopicPath` -确保切片之间的跨主题发散。切片将聚合为`MemoryNode`(记忆节点)的形式挂载到主题节点。除此之外，每个记忆节点还将按照日期进行索引. +创建 WebSocket Gateway 配置： -#### 基于时间轮和行动链的行动系统 +```bash +cat > "$PARTNER_HOME/config/gateway.json" <<'EOF' +{ + "default_channel": "websocket_channel", + "channels": [ + { + "channel_name": "websocket_channel", + "params": { + "hostname": "127.0.0.1", + "port": "29600", + "heartbeat_interval": "10000" + } + } + ] +} +EOF +``` -行动系统由 ActionCore 作为统一能力入口，维护行动池、待确认行动(按用户区分)、可用行动程序(MCP Tool 描述信息)以及语义倾向缓存。行动本体以 -ActionData 表达，分为 ImmediateActionData 与 ScheduledActionData 两类，核心结构是按阶段(order)组织的行动链： -`Map>`。每个 MetaAction 封装具体行动程序的定位信息、参数容器与执行结果。 +配置默认模型： -整体流程分为规划与分发两段： +```bash +export PARTNER_DEFAULT_BASE_URL="https://your-openai-compatible-endpoint/v1/chat/completions" +export PARTNER_DEFAULT_API_KEY="your-api-key" +export PARTNER_DEFAULT_MODEL="your-model-name" +``` -- 规划(Pre)：ActionExtractor 先尝试命中语义缓存，否则调用模型抽取行动倾向；ActionEvaluator - 结合可用行动列表与记忆切片评估行动并产出行动链；ActionConfirmer 对需要确认的行动发起确认，确认通过后进入行动池。 -- 分发(Post)：ActionDispatcher 将 PREPARE 的行动划分为计划型与即时型。计划型进入 ActionScheduler 持有的时间轮组件，即时型直接进入 - ActionExecutor 并发执行。 +也可以使用 `$PARTNER_HOME/config/model.json` 声明模型 provider： -执行时，ActionExecutor 以阶段为单位推进行动链，同一阶段内的多个 MetaAction 并行执行，并通过 Phaser 进行阶段同步。参数由 -ParamsExtractor 从上下文/历史结果中提取；若参数不足，则 ActionRepairer 通过动态生成行动单元、调用已有行动或发起自对话/用户补充进行修复；阶段结束后 -ActionCorrector 可根据执行结果对后续行动链进行修正。 +```json +{ + "providerConfigSet": [ + { + "name": "default", + "type": "OPENAI_COMPATIBLE", + "defaultModel": "your-model-name", + "baseUrl": "https://your-openai-compatible-endpoint/v1/chat/completions", + "apiKey": "your-api-key" + } + ], + "runtimeConfigSet": [] +} +``` -行动干预(ActionInterventor)可在执行中或预备阶段识别用户的“更改行动”意图，经评估后对行动链执行追加、插入、删除、取消或重建等操作。ActionCore -负责将干预应用到具体 ActionData，并确保阶段推进与链变更的互斥安全。 +> 其余详细配置信息参考 ![配置说明](doc/config/configuration.md) -执行环境由 RunnerClient 抽象。LocalRunnerClient 负责本地 MCP 工具调用、动态行动生成与持久化；SandboxRunnerClient -预留为沙盒执行器客户端，实现与远端行动程序的同步与执行。 +##### 启动项目 -#### 多用户会话管理 +``` +java -jar Partner-Core/target/Partner-Core-0.5.0.jar +``` -构建区分用户的单上下文窗口、多用户会话的管理机制. +--- -### 框架部分 +## 项目结构 -#### 基于注解驱动的核心服务与上层模块注册机制 +```text +Partner/ +├── Partner-Framework/ # Agent 运行框架与通用基础设施 +│ └── src/main/java/work/slhaf/partner/framework/agent/ +│ ├── config/ # 配置中心与配置路径解析 +│ ├── factory/ # 组件注册、Capability 注入与初始化流程 +│ ├── interaction/ # Gateway、运行时调度、输入输出通道 +│ ├── model/ # 模型 Provider、模型运行时与消息结构 +│ ├── state/ # 状态持久化支持 +│ └── support/ # Result、目录监听等基础支持 +├── Partner-Core/ # Partner 主运行时与核心模块 +│ └── src/main/java/work/slhaf/partner/ +│ ├── core/ # 感知、认知、记忆、行动等核心能力接口与状态 +│ ├── module/ # 实际参与运行流的模块实现 +│ ├── runtime/ # 主运行上下文、Gateway 实现与运行时异常处理 +│ ├── common/ # Core 内部共享的基础能力 +│ └── Main.java # 启动入口 +├── doc/ # 设计说明与补充文档 +├── pom.xml # Maven 父工程 +└── README.md +``` -1. 基于 Reflections, Proxy, ByteBuddy 的从核心服务到智能体流程的完整基于注解的注册机制 -2. 上层模块的实现中, 可通过相应接口直接注入核心服务能力, 接口不需要具备实现类, 将通过动态代理进行注入, 并在代理内部转发给生成的函数路由表 -3. 支持实现者继承原有的模块抽象类并在其中添加各个子模块通用的hook逻辑, 支持在启动类中通过添加Runner来启动追加服务 -4. 支持可自定义的配置实现类, 但最终返回结构需遵循现有定义, 也可自行提供其完整实现 -5. 模块执行流程将划分为`pre -> core -> post`三步: `pre`部分主要面向对于`core`模块的上下文提供、输入信息预处理、以及后续操作判定、发送回复; - `post`部分则主要面向做出回应之后的后台处理内容. +- `Partner-Framework`：提供 Agent 运行所需的基础框架能力，包括配置加载、组件注册、Capability 注入、模型调用、Gateway + 注册、运行时调度和状态管理。 +- `Partner-Core`：承载 Partner 的主运行逻辑和核心模块实现，包括感知、认知、记忆、行动、通信等能力域。 +- `doc/`：用于沉淀更细的设计文档，README 只保留项目入口和最小启动路径。 -> 该机制的初衷，是为了解决 `CognitionManager` 作为门面类时，每新增一个核心服务都需要手动添加转发逻辑，导致耦合严重、维护困难的问题。 -> -> 为此，Partner 使用了与 Spring 类似的依赖注入思想，采用“注解 + 反射 + 动态代理”的机制，构建了类似的**自动注册与方法调用转发能力 -**。 -> -> 但与 Spring 不同： -> - Spring 的依赖注入主要发生在**对象实例级别**，关注的是 Bean 的生命周期与依赖管理； -> - 而 Partner 中，核心服务在**方法级别**就已存在复杂的跨服务协同需求，单纯的对象注入难以满足这种粒度（不过在某次重构后这种需求也明显减少了，但这个机制或许可以保留下来） -> -> 因此，系统引入了 `CoordinateManager`，用于维护所有核心服务的**方法路由与协调关系** -> 。系统将在启动时构建协调方法与普通方法的完整路由表，并通过接口代理完成实际调用，无需手动编写注册与转发逻辑。 -> -> 模块注册机制原计划作为后续优化任务处理。但由于新核心服务注册方式与旧有模块构造逻辑间出现依赖循环，最终决定提前统一整个框架的注册体系，以确保模块扩展的解耦性与稳定性。 +--- -## 模块(已实现/正在实现) +## 相关文档 -- 预处理模块: `PreprocessExecutor` -- 后处理模块: `PostprocessExecutor` -- 主对话模块: `CoreModel` -- 记忆模块 - - 记忆选择模块: `MemorySelector` - - 主题提取模块: `MemorySelectExtractor` - - 切片评估模块: `SliceSelectEvaluator` - - 记忆更新模块: `MemoryUpdater` - - 记忆总结模块[多聊天对象]: `MultiSummarizer` - - 记忆总结模块[单聊天对象]: `SingleSummarizer` - - 记忆总结模块[汇总]: `TotalSummarizer` -- 感知模块 - - 感知选择模块: `PerceiveSelector` - - 感知更新模块: `PerceiveUpdater` - - 关系提取模块: `RelationExtractor` - - 静态记忆提取模块: `StaticMemoryExtractor` -- 行动模块 - - 行动规划模块: `ActionPlanner` - - 行动确认模块: `ActionConfirmer` - - 行动提取模块: `ActionExtractor` - - 行动评估模块: `ActionEvaluator` - - 行动分发模块: `ActionDispatcher` - - 行动调度模块: `ActionScheduler` - - 行动执行模块: `ActionExecutor` - - 行动干预模块: `ActionInterventor` - - 干预识别模块: `InterventionRecognizer` - - 干预评估模块: `InterventionEvaluator` +### 已完成 -## 当前问题 +### 待完成 -- 系统的正常运作效果取决于各模块中大模型对于`prompt`的遵循能力，目前来看`qwen3`的遵循效果明显较好，但在轮次较多时，也容易出现不遵循的情况。 +- ![整体架构与运行流](doc/architecture/overview.md) +- ![ContextWorkspace](doc/context/context-workspace.md) +- ![行动系统](doc/action/action.md) +- ![记忆存储与组织](doc/memory/memory.md) +- ![模型提供商](doc/model/providers.md) +- ![配置说明](doc/config/configuration.md) -## 规划 - -- [ ] 继续完善当前行动模块 -- [ ] 调整记忆模块实现机制 -- [ ] 将当前行动模块中的语义缓存机制同样应用于记忆模块，可用作主题提取流程的快速匹配 -- [ ] 回顾时发现不少遗留的逻辑错误或不合适的处理规则，需要找时间回顾整个流程并做出修正 -- [ ] 服务端与客户端的通信加上消息队列，防止消息因连接断开而丢失。 -- [ ] 实现流式输出，同时在各模块执行时可向客户端返回回调信息，优化使用体验。(现在用的是`websocket`与客户端通信, - 应该实现这点会简单些) -- [ ] 踩坑。 -- [ ] 实现演进机制 +--- ## License -This project is not licensed for public use. All rights reserved. +暂未指定。 -Partner is currently in an early experimental phase. Code, logic, and architecture are rapidly evolving. -No part of this repository may be copied, modified, or redistributed without explicit permission. - -For collaboration or inquiries, contact the maintainer directly. diff --git a/doc/action/action.md b/doc/action/action.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/architechture/action.md b/doc/architechture/action.md deleted file mode 100644 index b01cd76b..00000000 --- a/doc/architechture/action.md +++ /dev/null @@ -1 +0,0 @@ -# 流程参考: 行动模块 \ No newline at end of file diff --git a/doc/architechture/memory.md b/doc/architechture/memory.md deleted file mode 100644 index 85bdbdd4..00000000 --- a/doc/architechture/memory.md +++ /dev/null @@ -1,96 +0,0 @@ -# 流程参考: 记忆模块 - -> 仅展示大致流程，缓存命中、持久化等内容在下方流程图中尚未体现 - -## 前置模块: [MemorySelector](../../Partner-Main/src/main/java/work/slhaf/partner/module/modules/memory/selector/MemorySelector.java) - -```mermaid ---- -config: - layout: elk - elk: - nodePlacementStrategy: LINEAR_SEGMENTS ---- - -flowchart TD - direction TB - - Input[输入] --> |主题提取| Extractor - subgraph TE [主题提取] - Extractor[主题提取模块] --> Extract{主题提取} - Extract --> |提取到主题| TopicSet[主题路径集合] - - TopicSet --> TopicPath1[主题路径.1] --> Slice1[记忆切片.1] - TopicSet --> TopicPath2[主题路径.2] --> Slice2[记忆切片.2] - TopicSet --> TopicPath3[主题路径.3] --> Slice3[记忆切片.3] - end - - subgraph SE [切片评估] - - Evaluator[切片评估模块] - - Slice1 --> Evaluator --> Thread1[评估线程.1] --> Evaluated{评估是否通过} - Slice2 --> Evaluator --> Thread2[评估线程.2] --> Evaluated{评估是否通过} - Slice3 --> Evaluator --> Thread3[评估线程.3] --> Evaluated{评估是否通过} - Evaluated --> |否| Throwed - end - - Context[流程上下文] - Extract --> |未提取到主题| ResultEmpty - Evaluated --> |是| ResultNormal - ResultEmpty --> |写入| Context - ResultNormal --> |写入| Context - - ResultEmpty@{shape: braces, label: "[结束]
---
记忆无命中"} - ResultNormal@{shape: braces, label: "[结束]
---
聚合为特定格式的 Prompt"} - Throwed@{ shape: dbl-circ, label: "丢弃" } -``` - -### 后置模块: [MemoryUpdater](../../Partner-Main/src/main/java/work/slhaf/partner/module/modules/memory/updater/MemoryUpdater.java) - -```mermaid ---- -config: - layout: elk - elk: - nodePlacementStrategy: LINEAR_SEGMENTS ---- - -flowchart TD - direction TB - - Trigger.Time[触发: 时间周期] --> MT - Trigger.Threshold[触发: 对话阈值] --> MT - - CognationCore --> |读取| Messages - subgraph MT [对话分流] - Messages[对话记录] --> Single[单个主体对话] - Single --> Single1[主体1] - Single --> Single2[主体2] - Single --> Single3[主体3] - - Messages[对话记录] --> Multi[多个主体对话] - end - - subgraph MS [对话摘要] - Single1 --> |并发| SSum1[单主体摘要线程1] --> SSResult1[单主体摘要结果1] - Single2 --> |并发| SSum2[单主体摘要线程2] --> SSResult2[单主体摘要结果2] - Single3 --> |并发| SSum3[单主体摘要线程3] --> SSResult3[单主体摘要结果3] - - Multi --> MSum[多主体摘要] --> MSResult[多主体摘要结果] - end - - subgraph MU[记忆更新] - MemoryCore[记忆核心] - SSResult1 --> Slice1[记忆切片1] --> |更新| MemoryCore - SSResult2 --> Slice2[记忆切片2] --> |更新| MemoryCore - SSResult3 --> Slice3[记忆切片3] --> |更新| MemoryCore - - MSResult --> Slice4[记忆切片4] --> |更新| MemoryCore - - end - - MU --> |滚动对话窗口| CognationCore - - CognationCore[认知核心] -``` \ No newline at end of file diff --git a/doc/architechture/perceive.md b/doc/architechture/perceive.md deleted file mode 100644 index c10f8b09..00000000 --- a/doc/architechture/perceive.md +++ /dev/null @@ -1,59 +0,0 @@ -# 流程参考: 感知模块 - -> 相较于其他模块，目前的感知模块实际上流程非常简单，但后续或将添加一些新的内容 -> 此外，其后置模块实际上与 [记忆模块](./memory.md) 中的后置模块为并发执行，且都为后台任务 - -## 前置模块: [PerceiveSelector](../../Partner-Main/src/main/java/work/slhaf/partner/module/modules/perceive/selector/PerceiveSelector.java) - -```mermaid -flowchart TD - Context[流程上下文] --> |获取| UserId - UserId --> |查询| PerceiveCore - PerceiveCore --> |结果回写| Context - - subgraph result [感知核心查询结果] - relation[关系] - attitude[态度] - impression[印象] - static_memory[静态记忆] - end -``` - -## 后置模块: [PerceiveUpdater](../../Partner-Main/src/main/java/work/slhaf/partner/module/modules/perceive/updater/PerceiveUpdater.java) - -```mermaid ---- -config: - layout: elk - elk: - nodePlacementStrategy: LINEAR_SEGMENTS ---- - -flowchart TD - - Trigger.Time[触发: 时间周期] --> PE - Trigger.Threshold[触发: 对话阈值] --> PE - - CognationCore --> |读取| Messages[对话记录] - PerceiveCore --> |读取| UserInfo[现有的用户信息] - subgraph PE [内容提取] - Messages --> |输入| RelationExtractor - UserInfo --> |输入| RelationExtractor - - Messages --> |输入| StaticExtractor - UserInfo --> |输入| StaticExtractor - end - - subgraph PU [感知更新] - StaticExtractor --> |生成| NewInfo[修正后的用户信息] - RelationExtractor --> |生成| NewInfo[修正后的用户信息] - end - - NewInfo --> |更新| PerceiveCore - - CognationCore[认知核心] - PerceiveCore[感知核心] - - RelationExtractor[关系提取模块] - StaticExtractor[静态记忆提取模块] -``` \ No newline at end of file diff --git a/doc/architecture/overview.md b/doc/architecture/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/assets/partner-overview.png b/doc/assets/partner-overview.png new file mode 100644 index 00000000..83317a21 Binary files /dev/null and b/doc/assets/partner-overview.png differ diff --git a/doc/config/configuration.md b/doc/config/configuration.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/context/context-workspace.md b/doc/context/context-workspace.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/memory/memory.md b/doc/memory/memory.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/model/providers.md b/doc/model/providers.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/start/如何启动.md b/doc/start/如何启动.md deleted file mode 100644 index 0556d2f8..00000000 --- a/doc/start/如何启动.md +++ /dev/null @@ -1,21 +0,0 @@ -# Partner 项目启动流程 - -> 由于整个项目启动依赖提前写好的配置文件，所以在启动项目之前，最好阅读先该文档，准备好必要的配置，避免启动失败 - -## 前置操作 - -确保已经安装`Java21`环境 - -克隆项目至本地： - -```bash -git clone https://github.com/slhafzjw/Partner.git -``` - -## 准备配置 - -克隆好项目之后，在项目的根目录创建目录`config/` - -### 准备基础配置文件 - -