# AgentScopeService

**Repository Path**: North_Fan/agent-scope-service

## Basic Information

- **Project Name**: AgentScopeService
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentScope 企业级多用户 Skill 服务

> 参考 [AgentScope Agent Service 官方文档](https://docs.agentscope.io/zh/v2/deploy/agent-service)，
> 把党政机关公文写作技能（official-doc-writer）以 **多租户、多会话、HTTP SSE** 的方式部署，
> 让企业内多个用户可同时调用同一份 Skill 并安全隔离会话与文件。

## ✨ 整体架构

```
┌────────────────────────────┐         ┌──────────────────────────────────┐
│   Vue 3 + Vite 前端         │  HTTPS  │   FastAPI Agent Service           │
│   • 登录 / JWT              │ ───────►│   • POST /api/auth/login          │
│   • 会话列表 / 新建 / 删除   │  SSE    │   • CRUD /api/sessions            │
│   • 流式聊天 / 文件下载      │ ◄───────│   • POST /api/chat (SSE 流)       │
└────────────────────────────┘         │   • GET /api/skills               │
                                       │   • GET /api/files/{user}/{file}  │
                                       └──────────────┬───────────────────┘
                                                      │
                                       ┌──────────────▼───────────────────┐
                                       │  AgentScope ReActAgent + Toolkit │
                                       │  • toolkit.register_agent_skill  │
                                       │  • Tool: generate_official_document│
                                       │  • JSONSession 持久化 state       │
                                       └──────────────┬───────────────────┘
                                                      │
                                       ┌──────────────▼───────────────────┐
                                       │  server/skills/official-doc-writer│
                                       │  • SKILL.md + scripts/*.py       │
                                       └──────────────────────────────────┘
```

### 与官方 Agent Service 资源模型的对应关系

| 官方资源     | 本项目实现                                                      |
| ------------ | --------------------------------------------------------------- |
| `User`       | `server/app/users.py` + JWT 认证                                |
| `Credential` | DashScope API Key（`server/.env` 中的 `DASHSCOPE_API_KEY`）     |
| `Agent`      | `ReActAgent`（system prompt 在 `agent_service.py` 中按用户定制） |
| `Workspace`  | 每个 session 独立挂载 skill 子集（`POST /api/sessions` 时指定）  |
| `Session`    | `server/app/sessions.py` + AgentScope `JSONSession`             |
| `Skill`      | `server/skills/*` 目录，自动扫描 `SKILL.md`                     |
| `Schedule`   | 暂未启用（如需 cron 触发，可参考官方文档接入）                   |

## 🚀 快速启动

### 1. 后端

```bash
# Windows / PowerShell
cd server
pip install -r requirements.txt

# 配置 DashScope Key
copy .env.example .env
# 编辑 .env，填入真实的 DASHSCOPE_API_KEY

# 启动 Agent Service
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

启动后：

- API 文档（OpenAPI / Swagger）：<http://localhost:8000/docs>
- 健康检查：<http://localhost:8000/health>

首次启动会在 `server/data/users.json` 自动创建演示账户：

| 用户名 | 密码     | 角色  | 部门     |
| ------ | -------- | ----- | -------- |
| admin  | admin123 | admin | 信息中心 |
| alice  | alice123 | user  | 人事处   |
| bob    | bob123   | user  | 办公室   |

### 2. 前端

```bash
cd web
npm install
npm run dev
```

访问 <http://localhost:5173>，使用上面任一账户登录。

### 3. 体验流程

1. 用 **alice / alice123** 登录；
2. 在「💬 对话」页点击「+ 新建」创建一次会话（默认挂载 `official-doc-writer` 技能）；
3. 输入：
   > *帮我写一份关于2026年第一季度安全检查工作的通知，发文机关是XX市数据资源管理局，主送各处室，发文字号 沈数据〔2026〕5号*
4. Friday 通过 SSE 流式回复，按需要调用 `generate_official_document` 工具；
5. 在对话气泡中点击 `📥 /api/files/alice/xxx.docx` 即可下载生成的公文 Word 文件；
6. 切换到 **bob / bob123** 登录，可看到 bob 的文件与会话与 alice **完全隔离**。

## 🧱 关键代码导航

| 文件                                                                                       | 作用                                                |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| [server/app/main.py](server/app/main.py)                                                   | FastAPI 应用入口、CORS、lifespan                    |
| [server/app/auth.py](server/app/auth.py)                                                   | JWT 鉴权（对应官方 `get_current_user_id` 依赖）     |
| [server/app/users.py](server/app/users.py)                                                 | 用户存储 + bcrypt 密码哈希                          |
| [server/app/skills_manager.py](server/app/skills_manager.py)                               | 扫描 `SKILL.md` frontmatter，构建 SkillInfo         |
| [server/app/skills_tools.py](server/app/skills_tools.py)                                   | 把 official-doc-writer 包装成 AgentScope Tool       |
| [server/app/sessions.py](server/app/sessions.py)                                           | 会话索引 + 消息历史                                 |
| [server/app/agent_service.py](server/app/agent_service.py)                                 | ReActAgent 构建 + JSONSession 持久化 + SSE 流式输出 |
| [server/app/routers.py](server/app/routers.py)                                             | 全部 REST 路由                                      |
| [web/src/views/ChatView.vue](web/src/views/ChatView.vue)                                   | 流式聊天界面（自实现 SSE 解析）                     |

## 🔐 多用户隔离设计要点

- **JWT** 中携带 `user_id`，所有 API 通过 `Depends(get_current_user)` 强制校验；
- **会话**：`session_id` 仅在创建者 `user_id` 下可见、可读、可写；删除时同时清理 `JSONSession` 状态文件；
- **文件**：公文输出路径形如 `data/outputs/{user_id}/xxx.docx`；下载接口校验用户身份，仅 admin 可越权读其他用户文件；
- **Agent state**：以 `{user_id}__{session_id}` 作为 `JSONSession` 的 `session_id`，避免命名冲突。

## 🛠️ 扩展指南

### 新增 Skill

把 Anthropic 风格的技能目录放入 `server/skills/<your-skill>/`，包含 `SKILL.md`：

```markdown
---
name: "my-skill"
description: "技能能力描述（用于触发）"
---

# 我的技能
...
```

刷新前端「🧩 技能库」即可看到。再在 `agent_service.py` 中给某 session 默认挂载即可。

### 新增 LLM Provider

仿照官方文档 `extra_credentials` 的做法，扩展 [agent_service.py](server/app/agent_service.py) 中
`_build_agent` 函数，根据 session.provider 切换 `OpenAIChatModel` / `AnthropicChatModel` 等即可。

### 接入企业身份系统

替换 [auth.py](server/app/auth.py) 中的 `get_current_user` 实现：

- LDAP：用 `ldap3` 连接企业 AD，把 `dn` 当作 `user_id`；
- OAuth2 / SSO：让 FastAPI 在网关后做 token 验证后，把 `X-User-ID` 透传过来。

## ✅ 验证脚本

```bash
# 后端启动后
python server/tests/test_api.py        # 走通登录→会话→Skill→删除
python server/tests/test_doc_gen.py    # 离线验证 docx 生成
```

## 🔗 参考

- AgentScope Agent Service 文档：<https://docs.agentscope.io/zh/v2/deploy/agent-service>
- AgentScope Agent Skill 文档：<https://docs.agentscope.io/zh/v2/building-blocks/agent-skill>
- GB/T 9704-2012 公文格式标准（见 `server/skills/official-doc-writer/references/`）