# QualitativeAgent

**Repository Path**: lyflyy/QualitativeAgent

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qualitative Agent / Research Space

本仓库用于设计并逐步实现一个面向定性研究场景的 AI 研究工作台。当前阶段重点不是搭建通用 Agent 平台，而是用最小、清晰、可验证的架构完成本期研究流程闭环。

## 架构与业务流转总览

下面这张图用于对外宣讲当前整体方案：上半部分说明架构边界，中间说明业务从需求到报告的流转，下半部分说明本期需要开发的模块。

![Research Space 架构与业务流转总览](docs/research-space/assets/architecture-business-flow.svg)
## 当前架构

```text
WeKnora frontend
  -> 复用登录态、路由守卫、组织上下文、布局和组件体系
  -> 新增 Research Space 页面模块
  -> 调用 WeKnora API：登录、知识库、组织等平台能力
  -> 调用 Research Space API：研究项目、阶段状态、用户讨论、Artifact、证据链

Research Space API
  -> 内置 LangGraph workflow module / worker：固定 MVP Agent 流程编排
  -> WeKnora API：认证上下文、权限判断、RAG 检索、文件/ASR 能力
```

## 核心结论

- `WeKnora` 是平台底座，负责通用用户体系、组织权限、知识库、RAG、文件/ASR 和模型配置。
- `weknora-origin/frontend` 本期承载 Research Space 页面模块，以复用登录、鉴权、组织上下文、路由和组件体系。
- `Research Space API` 是轻量业务控制面，只负责定性研究项目中的业务事实。
- `LangGraph` 本期内置在 `Research Space API` 中，作为固定流程执行模块，不单独拆成服务。
- WeKnora frontend 中的 Research Space 页面只调用 `Research Space API` 的业务动作，不直接调用 LangGraph。
- 定性研究业务流程不写入 WeKnora backend，避免污染通用平台。

## MVP 范围

本期保留：

```text
ResearchSpace
StageRun
StageInteraction
Artifact
ArtifactVersion
EvidenceReference
RAG search wrapper
ProjectKnowledgePublication
Research report history
WeKnora frontend Research Space pages
```

本期延后：

```text
独立 workflow-service
独立 Research Space frontend 工程
通用 Skill Runtime
Skill 热加载
Tool marketplace
自定义 Space RBAC
Graph 编辑器
招募访谈流程
访谈音频上传 / ASR 转写 / 访谈总结
前端直连 LangGraph
把定性研究流程写入 WeKnora backend
```

## 目录结构

```text
openspec/
  specs/                  当前系统行为事实源
  changes/                变更提案、设计、任务与 delta spec

docs/research-space/
  README.md               机器合同目录说明
  assets/                 需求图、流程图等评审资产
  specs/openapi/          MVP OpenAPI 合同
  specs/schemas/          MVP Artifact JSON Schema

research-space-service/
  Python/FastAPI 服务骨架，后续内置 LangGraph workflow module / worker

weknora-origin/frontend/
  WeKnora 前端工程，本期新增 Research Space 页面模块

web-min/
  临时最小前端验证页面，正式页面跑通后可删除

weknora-origin/
  WeKnora 上游项目，作为用户、权限、知识库、RAG 能力来源

deer-flow/
  DeerFlow 上游参考项目，用于理解 LangGraph/Agent 编排经验

tests/spec_mapping/
  MVP spec -> OpenAPI -> test_id 映射与合同断言

scripts/
  spec、dev、live 检查脚本
```

## 常见架构问题

- [Research 模块是否应该放进 LangGraph？](docs/research-space/qa/research-langgraph-boundary.md)
## 阅读顺序

1. `openspec/README.md`
2. `openspec/specs/spec-governance/spec.md`
3. `openspec/specs/mvp-architecture/spec.md`
4. `openspec/specs/identity-access/spec.md`
5. `openspec/specs/research-space/spec.md`
6. `openspec/specs/stage-pipeline/spec.md`
7. `openspec/specs/artifact-evidence/spec.md`
8. `openspec/specs/project-knowledge-base/spec.md`
9. `openspec/specs/api-contract/spec.md`
10. `docs/research-space/specs/openapi/openapi.yaml`

## 本地检查

安装基础依赖：

```bash
python -m pip install --upgrade pip
pip install -r requirements-spec-ci.txt
pip install pytest
```

运行 spec-ci：

```bash
python scripts/spec_ci.py
```

运行 spec mapping 测试：

```bash
python -m pytest tests/spec_mapping -q
```

如果环境有 `make`：

```bash
make spec-ci
```

## 启动 Research Space Service

```bash
cd research-space-service
python -m venv .venv
. .venv/Scripts/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

健康检查：

```bash
curl http://127.0.0.1:8000/api/research/v1/health
```

## 前端开发入口

本期正式前端开发进入：

```text
weknora-origin/frontend/src/views/research-space/
weknora-origin/frontend/src/api/research-space/
weknora-origin/frontend/src/stores/research-space.ts
weknora-origin/frontend/src/types/research-space.ts
```

建议路由：

```text
/platform/research-spaces
/platform/research-spaces/:spaceId
```

## OpenSpec 约束

当前系统行为以 `openspec/specs/` 为准。新增需求必须先进入：

```text
openspec/changes/<change-id>/
  proposal.md
  design.md
  tasks.md
  specs/<capability>/spec.md
```

如果需求会引入独立 Workflow Service、独立 Research Space 前端工程、通用 Skill 平台、自定义 RBAC、Graph 编辑器或 WeKnora backend 内置研究业务流程，必须作为未来变更单独评审，不能默认进入 MVP。