slhaf/Partner
1
0
Fork 0
mirror of https://github.com/slhaf/Partner.git synced 2026-05-12 08:43:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README and add documentation skeleton

Browse Source
This commit is contained in:
slhafzjw
2026-04-27 15:03:03 +08:00
parent 9144cd90ce
commit e022f134ac
12 changed files with 111 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
README.md
View File

@@ -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<order, List<MetaAction>>`。每个 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.

0
doc/action/action.md Normal file
View File

1
doc/architechture/action.md
View File

@@ -1 +0,0 @@
# 流程参考: 行动模块

96
doc/architechture/memory.md
View File

@@ -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: "[结束]<br/>---<br/>记忆无命中"}
ResultNormal@{shape: braces, label: "[结束]<br/>---<br/>聚合为特定格式的 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[认知核心]
```

59
doc/architechture/perceive.md
View File

@@ -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[静态记忆提取模块]
```

0
doc/architecture/overview.md Normal file
View File

BIN
doc/assets/partner-overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

0
doc/config/configuration.md Normal file
View File

0
doc/context/context-workspace.md Normal file
View File

0
doc/memory/memory.md Normal file
View File

0
doc/model/providers.md Normal file
View File

21
doc/start/如何启动.md
View File

@@ -1,21 +0,0 @@
# Partner 项目启动流程
> 由于整个项目启动依赖提前写好的配置文件，所以在启动项目之前，最好阅读先该文档，准备好必要的配置，避免启动失败
## 前置操作
确保已经安装`Java21`环境
克隆项目至本地：
```bash
git clone https://github.com/slhafzjw/Partner.git
```
## 准备配置
克隆好项目之后，在项目的根目录创建目录`config/`
### 准备基础配置文件