Skip to content

Commit a07e3f6

Browse files
PhineasePhinease
committed
📝 Update developper notes and faqs
1 parent d165587 commit a07e3f6

File tree

9 files changed

+1104
-14
lines changed

9 files changed

+1104
-14
lines changed

‎DEVELOPPER_NOTE.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Nexent Developer Guide 🛠️
2+
3+
[![English](https://img.shields.io/badge/English-Guide-blue)](DEVELOPPER_NOTE.md)
4+
[![中文](https://img.shields.io/badge/中文-指南-green)](DEVELOPPER_NOTE_CN.md)
5+
6+
This guide will help developers quickly get started with Nexent development, including environment setup, tool development, and agent customization.
7+
8+
## Chapter 1: Environment Setup and Running 🚀
9+
10+
### 1. Install Dependencies
11+
```bash
12+
# Navigate to SDK directory
13+
cd sdk
14+
15+
# Install core dependencies
16+
pip install .
17+
```
18+
19+
### 2. Start Backend Services
20+
Nexent consists of three core backend services that need to be started separately:
21+
22+
```bash
23+
# Start data processing service
24+
python backend/data_process_service.py
25+
26+
# Start main service
27+
python backend/main_service.py
28+
29+
# Start MCP service
30+
python backend/mcp_service.py
31+
```
32+
33+
### 3. Start Frontend Service
34+
```bash
35+
# Navigate to frontend directory
36+
cd frontend
37+
38+
# Install dependencies
39+
npm install
40+
41+
# Start development server
42+
npm run dev
43+
```
44+
45+
## Chapter 2: Developing Custom Tools 🛠️
46+
47+
Nexent implements its tool system based on [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk). To develop a new tool:
48+
49+
1. Implement the tool logic in `mcp_service.py`
50+
2. Register the tool using the `@mcp.tool()` decorator
51+
3. Restart the MCP service to activate the new tool
52+
53+
Example:
54+
```python
55+
@mcp.tool(name="my_tool", description="My custom tool")
56+
def my_tool(param1: str, param2: int) -> str:
57+
# Implement tool logic
58+
return f"Processing result: {param1} {param2}"
59+
```
60+
61+
## Chapter 3: Developing Custom Agents 🤖
62+
63+
### 1. System Prompts
64+
System prompt templates are located in the `sdk/nexent/core/prompts` directory, including:
65+
- `code_agent.yaml`: Base agent prompt
66+
- `code_agent_demo.yaml`: Demo agent prompt
67+
68+
### 2. Agent Implementation
69+
Refer to the implementation in `agent_utils.py`:
70+
71+
1. Create an agent instance:
72+
```python
73+
from nexent.core.agents import CoreAgent
74+
from nexent.core.models import OpenAIModel
75+
76+
# Create model instance
77+
model = OpenAIModel(
78+
model_id="your-model-id",
79+
api_key="your-api-key",
80+
api_base="your-api-base"
81+
)
82+
83+
# Create agent
84+
agent = CoreAgent(
85+
model=model,
86+
tools=[your_tools], # Add your tools
87+
system_prompt="Your system prompt" # Custom system prompt
88+
)
89+
```
90+
91+
2. Add tools and configuration:
92+
- Add custom tools in the `tools` parameter
93+
- Set agent behavior through `system_prompt`
94+
- Configure other parameters like `max_steps`, `temperature`, etc.
95+
96+
## Important Notes ⚠️
97+
98+
1. Ensure all services are properly started before testing
99+
2. Restart the relevant service after code modifications
100+
3. Use debug mode in development environment
101+
4. Follow MCP protocol specifications when developing tools
102+
5. System prompts need thorough testing
103+
104+
## Getting Help 💬
105+
106+
- Check the [FAQ](FAQ.md)
107+
- Join our [Discord community](https://discord.gg/tb5H3S3wyv)
108+
- Submit [GitHub Issues](https://github.com/AI-Application-Innovation/nexent/issues)

‎DEVELOPPER_NOTE_CN.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Nexent 开发者指南 🛠️
2+
3+
[![English](https://img.shields.io/badge/English-Guide-blue)](DEVELOPPER_NOTE.md)
4+
[![中文](https://img.shields.io/badge/中文-指南-green)](DEVELOPPER_NOTE_CN.md)
5+
6+
本指南将帮助开发者快速上手 Nexent 的开发工作，包括环境搭建、工具开发和智能体定制。
7+
8+
## 第一章：环境搭建与运行 🚀
9+
10+
### 1. 安装依赖
11+
```bash
12+
# 进入 SDK 目录
13+
cd sdk
14+
15+
# 安装核心依赖
16+
pip install .
17+
```
18+
19+
### 2. 启动后端服务
20+
Nexent 包含三个核心后端服务，需要分别启动：
21+
22+
```bash
23+
# 启动数据处理服务
24+
python backend/data_process_service.py
25+
26+
# 启动主服务
27+
python backend/main_service.py
28+
29+
# 启动 MCP 服务
30+
python backend/mcp_service.py
31+
```
32+
33+
### 3. 启动前端服务
34+
```bash
35+
# 进入前端目录
36+
cd frontend
37+
38+
# 安装依赖
39+
npm install
40+
41+
# 启动开发服务器
42+
npm run dev
43+
```
44+
45+
## 第二章：开发自定义工具 🛠️
46+
47+
Nexent 基于 [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk) 实现工具系统。开发新工具需要：
48+
49+
1. 在 `mcp_service.py` 中实现工具逻辑
50+
2. 使用 `@mcp.tool()` 装饰器注册工具
51+
3. 重启 MCP 服务使新工具生效
52+
53+
示例：
54+
```python
55+
@mcp.tool(name="my_tool", description="我的自定义工具")
56+
def my_tool(param1: str, param2: int) -> str:
57+
# 实现工具逻辑
58+
return f"处理结果: {param1} {param2}"
59+
```
60+
61+
## 第三章：开发自定义智能体 🤖
62+
63+
### 1. 系统提示词
64+
系统提示词模板位于 `sdk/nexent/core/prompts` 目录下，包括：
65+
- `code_agent.yaml`: 基础智能体提示词
66+
- `code_agent_demo.yaml`: 演示用途智能体提示词
67+
68+
### 2. 智能体实现
69+
参考 `agent_utils.py` 中的实现方式：
70+
71+
1. 创建智能体实例：
72+
```python
73+
from nexent.core.agents import CoreAgent
74+
from nexent.core.models import OpenAIModel
75+
76+
# 创建模型实例
77+
model = OpenAIModel(
78+
model_id="your-model-id",
79+
api_key="your-api-key",
80+
api_base="your-api-base"
81+
)
82+
83+
# 创建智能体
84+
agent = CoreAgent(
85+
model=model,
86+
tools=[your_tools], # 添加你的工具
87+
system_prompt="你的系统提示词" # 自定义系统提示词
88+
)
89+
```
90+
91+
2. 添加工具和配置：
92+
- 在 `tools` 参数中添加自定义工具
93+
- 通过 `system_prompt` 设置智能体行为
94+
- 配置其他参数如 `max_steps`、`temperature` 等
95+
96+
## 注意事项 ⚠️
97+
98+
1. 确保所有服务都正确启动后再进行测试
99+
2. 修改代码后需要重启相应服务
100+
3. 建议在开发环境中使用调试模式
101+
4. 遵循 MCP 协议规范开发工具
102+
5. 系统提示词需要经过充分测试
103+
104+
## 获取帮助 💬
105+
106+
- 查看 [常见问题](FAQ_CN.md)
107+
- 加入 [Discord 社区](https://discord.gg/tb5H3S3wyv)
108+
- 提交 [GitHub Issues](https://github.com/AI-Application-Innovation/nexent/issues)

‎FAQ.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Nexent FAQ 🤔
2+
3+
[![English](https://img.shields.io/badge/English-FAQ-blue)](FAQ.md)
4+
[![中文](https://img.shields.io/badge/中文-FAQ-green)](FAQ_CN.md)
5+
6+
This FAQ addresses common questions and issues you might encounter while installing and deploying Nexent. For the basic installation steps, please refer to the [Quick Start Guide](../README.md#-have-a-try-first) in our README.
7+
8+
## 🚀 Installation & Setup
9+
10+
### 🐳 Docker & Docker Compose
11+
- **Q: TODO**
12+
- A: TODO
13+
14+
### 🌐 Port Conflicts
15+
- **Q: Port 3000 is already in use. How can I change it?**
16+
- A: You can modify the port in the Docker Compose configuration file.
17+
18+
## 🔍 Troubleshooting
19+
20+
### 🚫 Common Errors
21+
- **Q: The setup wizard isn't loading at http://localhost:3000**
22+
- A: TODO
23+
24+
### 📦 Container Issues
25+
- **Q: How do I check container logs?**
26+
- A: Use `docker logs <container_name>` to view logs for specific containers.
27+
28+
### 📧 Email Tools Configuration
29+
- **Q: How can I enable and configure email tools?**
30+
- A: Our team has pre-implemented email tools based on IMAP and SMTP. To enable them:
31+
1. Configure email parameters in `.env` file
32+
2. Uncomment the email tool imports and registrations in `agent_utils.py`
33+
3. Switch to the email-enabled system prompt by using `code_agent_with_email.yaml`
34+
4. Restart the MCP service to apply changes
35+
36+
## ❓ Still Need Help?
37+
38+
If your question isn't answered here:
39+
- Join our [Discord community](https://discord.gg/tb5H3S3wyv) for real-time support
40+
- Check our [GitHub Issues](https://github.com/AI-Application-Innovation/nexent/issues) for similar problems
41+
- Refer to our [Contribution Guide](../CONTRIBUTING.md) for more detailed information

‎FAQ_CN.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Nexent 常见问题 🤔
2+
3+
[![English](https://img.shields.io/badge/English-FAQ-blue)](FAQ.md)
4+
[![中文](https://img.shields.io/badge/中文-FAQ-green)](FAQ_CN.md)
5+
6+
本常见问题解答主要针对安装和部署 Nexent 过程中可能遇到的问题。如需了解基本安装步骤，请参考 README 中的[快速开始指南](../README_CN.md#-先来试试看)。
7+
8+
## 🚀 安装与设置
9+
10+
### 🐳 Docker 与 Docker Compose
11+
- **Q: TODO**
12+
- A: TODO
13+
14+
### 🌐 端口冲突
15+
- **Q: 端口 3000 已被占用，如何修改？**
16+
- A: 可以在 Docker Compose 配置文件中修改端口。
17+
18+
## 🔍 故障排除
19+
20+
### 🚫 常见错误
21+
- **Q: 设置向导无法在 http://localhost:3000 加载**
22+
- A: TODO
23+
24+
### 📦 容器问题
25+
- **Q: 如何查看容器日志？**
26+
- A: 使用 `docker logs <容器名称>` 命令查看特定容器的日志。
27+
28+
### 📧 邮件工具配置
29+
- **Q: 如何启用和配置邮件工具？**
30+
- A: 我们团队已经预制实现了基于 IMAP 和 SMTP 的邮件工具。要启用它们：
31+
1. 在 `.env` 文件中配置邮件参数
32+
2. 在 `agent_utils.py` 中取消邮件工具相关的注释
33+
3. 切换到支持邮件的系统提示词 `code_agent_with_email.yaml`
34+
4. 重启 MCP 服务使更改生效
35+
36+
## ❓ 需要更多帮助？
37+
38+
如果这里没有找到您的问题答案：
39+
- 加入我们的 [Discord 社区](https://discord.gg/tb5H3S3wyv) 获取实时支持
40+
- 查看我们的 [GitHub Issues](https://github.com/AI-Application-Innovation/nexent/issues) 寻找类似问题
41+
- 参考我们的[贡献指南](../CONTRIBUTING_CN.md)获取更详细的信息

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,14 +45,18 @@ When the containers are running, open **http://localhost:3000** in your browser
4545

4646
### 3. ❓ Need help?
4747

48-
- Browse the [FAQ](#) for common install issues.
48+
- Browse the [FAQ](FAQ.md) for common install issues.
4949
- Drop questions in our [Discord community](https://discord.gg/tb5H3S3wyv).
5050
- File bugs or feature ideas in [GitHub Issues](#).
5151

5252
#### 4. 🔧 Hack on Nexent
5353

5454
Want to build from source or add new features? Check the [Contribution Guide](CONTRIBUTING.md) for step-by-step instructions.
5555

56+
#### 5. 🛠️ Build from Source
57+
58+
Prefer to run Nexent from source code? Follow our [Developer Guide](DEVELOPPER_NOTE.md) for detailed setup instructions and customization options.
59+
5660
## ✨ Key Features
5761

5862
`1` **Smart agent prompt generation()**

‎README_CN.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,14 +45,18 @@ sh docker/deploy.sh
4545

4646
### 3. ❓ 需要帮助？
4747

48-
- 浏览 [常见问题](#) 了解常见安装问题。
48+
- 浏览 [常见问题](FAQ_CN.md) 了解常见安装问题。
4949
- 在我们的 [Discord 社区](https://discord.gg/tb5H3S3wyv) 中提问。
5050
- 在 [GitHub Issues](#) 中提交错误报告或功能建议。
5151

5252
#### 4. 🔧 开发 Nexent
5353

5454
想要从源代码构建或添加新功能？查看 [贡献指南](CONTRIBUTING_CN.md) 获取分步说明。
5555

56+
#### 5. 🛠️ 从源码构建
57+
58+
想要从源码运行 Nexent？查看我们的[开发者指南](DEVELOPPER_NOTE_CN.md)获取详细的设置说明和自定义选项。
59+
5660
## ✨ 主要特性
5761

5862
`1` **智能体提示词自动生成（To release）**
@@ -104,4 +108,4 @@ sh docker/deploy.sh
104108

105109
# 📄 许可证
106110

107-
Nexent 采用 [Apache License 2.0](LICENSE) 许可证，并附有额外条件。请阅读 [LICENSE](LICENSE) 文件了解详情。
111+
Nexent 采用 [Apache License 2.0](LICENSE) 许可证，并附有额外条件。请阅读 [LICENSE](LICENSE) 文件了解详情。

0 commit comments

Comments
 (0)