# Scientific-Research-Agent

**Repository Path**: glfapollo/Scientific-Research-Agent

## Basic Information

- **Project Name**: Scientific-Research-Agent
- **Description**: 科研智能体-白天昊维护
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库智能体平台(Zhishiku)

一个**技能驱动的通用智能工作平台**。系统由一个主编排器调度少量通用专家,每位专家按任务加载不同的技能文件完成工作,所有协作围绕一个文件夹展开。

## 核心理念

**一切能力都是技能**。代码只是薄骨架,系统的所有"智力"都由可编辑的技能文件承载。新增任务类型不需要改代码,只需扩充技能库和任务模板。

## 架构一句话

> **主脑**拿到任务,从**任务模板**或**动态规划**得到计划 → 召唤**获取 / 处理 / 产出**三位专家 → 每位专家按指派的**技能**工作,产出落到**工作区**对应子目录 → 主脑监督质量 → 成长闭环沉淀到**经验库**反哺下次任务。

## 文档索引

| 文档 | 内容 |
|------|------|
| [01-架构设计](docs/01-架构设计.md) | 主架构、核心理念、组件关系、数据流 |
| [02-专家与技能配置规范](docs/02-专家与技能配置规范.md) | experts.yaml 规范、技能文件规范 |
| [03-工作区布局规范](docs/03-工作区布局规范.md) | 工作区目录、命名、版本、并发、生命周期 |
| [04-任务模板规范](docs/04-任务模板规范.md) | templates.yaml 规范、推导规则、扩展方式 |
| [05-AI开发注意事项](docs/05-AI开发注意事项.md) | Prompt 工程、幻觉控制、成本、观测、安全 |
| [06-RAG元数据需求规范](docs/06-RAG元数据需求规范.md) | RAGFlow 文档级元数据字段要求 + 加权 rerank |
| [知识库图片入库说明](知识库图片入库说明.md) | 图片/表格抽取 + 推送 RAGFlow 的契约(v1) |
| [知识库图片入库-追加需求](知识库图片入库-追加需求.md) | 对方首版交付差距补齐请求(v1.1) |
| [CHANGELOG-2026-04-20](docs/CHANGELOG-2026-04-20.md) | 本日迭代记录(学习向导 / 十核面板 / produce_skill 修复 等) |

## 推荐阅读顺序

1. 新成员先读 [01-架构设计](docs/01-架构设计.md),建立整体心智
2. 再读 [05-AI开发注意事项](docs/05-AI开发注意事项.md),避开常见坑
3. 按职责深入具体规范:
   - 后端开发 → 02、03、04
   - 领域专家 / 运营 → 02 中"技能文件"章节 + 04

## 项目状态

**阶段**:MVP 已跑通;已进入"Plan Brain + LangGraph v2 + 10 核 + ReAct 自检 + 模板学习" 架构迭代期。

**当前能力**:
- 模板学习向导:上传 2-5 份样本 → 自动产出 skill + template + 9 维章节蓝图(含 subheadings / rag_topics / depends_on / language / chart_slots / quantitative 等)
- Plan Brain:LLM 驱动的动态规划,自主组合 10 核原子能力,不再依赖模板硬编码 phases(`fallback_skills` 仅兜底)
- 10 核能力(R1/R2/O1/O2/P1/P2/G1/G2/L1/L2 + V1):可通过 **系统设置 → 十核 Tab** 在线编辑描述/系统提示词/首选 skill,支持历史回滚
- ReAct 自检:生成后按 gap 分类决定 R2 回头补检索 / L1 补写 / V1 补图
- 工作区:`WorkspaceProtocol` 统一路径,L2 经验沉淀至 `workspaces/_system/experience_cards.jsonl`

**近期迭代**:见 [CHANGELOG-2026-04-20](docs/CHANGELOG-2026-04-20.md)。

## 技术栈

- **编排**:LangGraph(薄骨架,主脑调度)
- **后端**:Python 3.11 + FastAPI
- **存储**:PostgreSQL(元数据/经验库) + Redis(分布式锁/审批中断) + 对象存储(工作区)
- **LLM**:路由层支持多模型(默认 Claude/GPT,可降级到国内模型)
- **检索**:RAGFlow + Jina + ArXiv + DuckDuckGo

## 非目标

- 本系统**不是**通用 Chatbot,不做闲聊交互
- 本系统**不是**"大一统"AGI 框架,不做多智能体自组织对话(MetaGPT/AutoGen 那套)
- 本系统**不做**单纯的 RAG 问答(那是工具层的能力,不是平台定位)

## MVP 快速开始

MVP P0 已实现端到端闭环:本地工作区、技能加载、模板推导、LLM 路由(Anthropic Claude Tool Use)、三专家、主脑 6 节点、CLI。**不**含 LangGraph / FastAPI / Postgres / Redis / 人工审批 / 成长闭环 — 这些进 P1。

### 1. 安装依赖

```bash
# Python 3.11+
pip install -e .
```

核心依赖:`anthropic`、`pyyaml`、`python-frontmatter`、`jinja2`、`typer`、`pydantic`、`python-dotenv`。

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env:填 ANTHROPIC_API_KEY;想先在不花钱的情况下跑通流水线,设 MOCK_LLM=true
```

变量说明:
- `ANTHROPIC_API_KEY`:Anthropic API 密钥
- `ANTHROPIC_MODEL`:模型名(默认 `claude-opus-4-20250514`)
- `WORKSPACE_ROOT`:工作区根目录,默认 `./workspaces`
- `TENANT_ID`:多租户前缀,默认 `local`
- `MOCK_LLM`:`true` 时走内置 mock 输出,跳过真实 API 调用

### 3. 运行示例

```bash
python -m app.cli run "新能源汽车 2026 Q1 中国市场调研"
```

### 4. 查看产出

```
workspaces/local/<task_id>/
├── 任务目标.md
├── 执行计划.yaml
├── 证据/            (行业数据 + 竞品 JSON)
├── 提炼/            (交叉分析 md)
├── 推演/            (SWOT md)
├── 草稿/            (最终市场调研报告 md)
├── 复盘/summary.json
└── 元数据/
    ├── 状态.json
    └── 执行轨迹.jsonl
```

最终交付物位于 `草稿/market_research_v1.md`。

## 工具层

`app/tools/` 提供了统一的 `Tool` 抽象 + `ToolRegistry`,在 LLM Tool Use 循环里被 acquire 专家调用。当前内置三个工具:

| 工具 ID | 用途 | 启用条件 |
|---------|------|----------|
| `web_search` | DuckDuckGo 网页搜索 | 装了 `duckduckgo-search`(默认装) |
| `jina_reader` | 通过 `https://r.jina.ai` 把网页转 Markdown 正文 | 装了 `httpx`(默认装);可选 `JINA_API_KEY` 提升限流 |
| `rag_flow` | RAGFlow 知识库语义检索 | 同时设置 `RAGFLOW_BASE_URL` / `RAGFLOW_API_KEY` / `RAGFLOW_DATASET_IDS` |

工具白名单校验(03/02 规范):
- 每个技能的 `tools_required` 必须是所属专家 `available_tools` 的子集(或 `[llm_only]`),启动时强制校验,不通过直接 raise
- 运行时再过滤一层 `is_available()=False` 的工具(缺凭据 / 网络不通),并在 `元数据/执行轨迹.jsonl` 记 `tool_skip`
- 工具调用每一轮都落 trace:`{action: "tool_call", tool, input, success, duration_ms}`
- 任何工具失败都不会让任务崩溃;错误以 `tool_result` 的 `error` 字段回喂给 LLM,由 LLM 决定重试还是换条路
- `max_iterations` 默认 5,上限 8 — 到达上限直接返回当前 text

新增工具只需实现 `Tool` 协议并在 `registry.py::_register_defaults` 里 register 一次。

## 服务化 (HTTP + WebSocket)

CLI 之外还可以跑常驻服务,供前端 / 外部系统调用。**单进程内存调度**,MVP 够用;审批事件丢失不可恢复,任务本身走工作区持久化,重启可从文件系统恢复状态。

### 启动

```bash
# 安装新增依赖(fastapi / uvicorn / websockets)
pip install -e .

# 启动服务(读 .env 的 API_HOST / API_PORT,默认 127.0.0.1:8000)
python -m app.cli serve
# 或自定义端口: python -m app.cli serve --host 0.0.0.0 --port 9000
```

健康检查:`curl http://127.0.0.1:8000/health`。

### HTTP 路由

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/jobs` | 提交任务,返回 `task_id`;`auto_approve=true` 跳过审批 |
| GET  | `/jobs` | 列出近 50 个任务(按 mtime 降序) |
| GET  | `/jobs/{id}` | 任务状态 + 工作区路径 |
| GET  | `/jobs/{id}/plan` | 读 `执行计划.yaml`(反序列化为 JSON) |
| POST | `/jobs/{id}/approval` | 审批决策(`{"approve": true}` / `{"approve": false, "comment": "..."}`) |
| GET  | `/jobs/{id}/tree` | 工作区目录树 |
| GET  | `/jobs/{id}/files?path=...` | 读单文件,路径穿越已过 `normalize_path` 防御 |
| WS   | `/jobs/{id}/stream` | 实时 trace 流(快照 + 增量) |

### curl 示例

```bash
# 1) 提交任务(自动审批)
curl -s -X POST http://127.0.0.1:8000/jobs \
  -H 'Content-Type: application/json' \
  -d '{"task_desc":"服务化测试","auto_approve":true}'
# => {"task_id":"<uuid>","status":"initialized","tenant_id":"local","workspace_path":"..."}

# 2) 轮询状态
curl -s http://127.0.0.1:8000/jobs/<task_id>
# => {"task_id":"...","status":"done","workspace_path":"...","extra":{...}}

# 3) 提交任务(人工审批)
curl -s -X POST http://127.0.0.1:8000/jobs \
  -H 'Content-Type: application/json' \
  -d '{"task_desc":"审批测试","auto_approve":false}'

# 4) 查看计划后批准
curl -s http://127.0.0.1:8000/jobs/<task_id>/plan
curl -s -X POST http://127.0.0.1:8000/jobs/<task_id>/approval \
  -H 'Content-Type: application/json' \
  -d '{"approve":true,"comment":"looks good"}'

# 5) 查目录树 + 读单文件
curl -s http://127.0.0.1:8000/jobs/<task_id>/tree
curl -s "http://127.0.0.1:8000/jobs/<task_id>/files?path=复盘/summary.json"
```

### WebSocket 示例

```bash
# websocat 一行流
websocat ws://127.0.0.1:8000/jobs/<task_id>/stream
```

```javascript
// 浏览器 / Node
const ws = new WebSocket(`ws://127.0.0.1:8000/jobs/${taskId}/stream`);
ws.onmessage = (e) => console.log(JSON.parse(e.data));  // {type: "trace"|"status"|"end", data: ...}
```

每条消息形如 `{"type":"trace","data":{...}}` / `{"type":"status","data":{...}}`,任务到达 `done|failed|rejected` 终态时服务端推一条 `{"type":"end"}` 然后关闭连接。