# 定性智能体接口文档

**Repository Path**: lyflyy/QualitativeAgentDoc

## Basic Information

- **Project Name**: 定性智能体接口文档
- **Description**: 定性智能体接口文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OmniForge 对外接口文档目录

本文档目录用于给外部对接 OmniForge API。目标是让第三方公司在不复用现有页面服务的情况下，仅依据 PRD 截图和接口能力，完整实现当前 IDI 深访主链路。

## 文档清单

- [00-common-conventions.md](./00-common-conventions.md)：公共调用约定、Header、响应格式、状态枚举。
- [01-prd-page-api-mapping.md](./01-prd-page-api-mapping.md)：按 PRD 截图逐张拆解 UI 功能和接口映射。
- [02-external-api-reference.md](./02-external-api-reference.md)：当前系统已经具备的对外接口、出入参和调用示例。
- [03-provider-debug-guide.md](./03-provider-debug-guide.md)：联调顺序、最小调用链和常见问题。
- [04-meeting-integration.md](./04-meeting-integration.md)：会议服务对接说明，包含内置会议模块、真实腾讯会议 adapter 边界和回传调试方式。
- [05-stage-form-context.md](./05-stage-form-context.md)：阶段表单 JSON 上下文接入方案，说明外部前端如何提交动态表单 JSON、何时会在本次交互中返回 `stage_form_context`、如何通过 `current` 恢复当前阶段表单状态，以及后续独立 `form-context` 接口设计。
- [06-yili-sso-frontend-integration.md](./06-yili-sso-frontend-integration.md)：Yili SSO 前端接入说明，包含登录跳转、callback 处理、请求参数、响应保存、后续 API 鉴权和最小 TypeScript 示例。
- [07-current-api-slimming-plan.md](./07-current-api-slimming-plan.md)：`/current` 接口瘦身结果，说明工作台状态、历史消息、思考详情、执行事件、产物详情等数据的最终拆分边界。
- [PROVIDER_API_PLAYBOOK.md](./PROVIDER_API_PLAYBOOK.md)：最小联调 playbook，包含接口状态、环境变量、按顺序 curl 示例、预期响应核心字段和常见错误。

## 推荐阅读顺序

外部服务商首次接入：

1. 先读 [00-common-conventions.md](./00-common-conventions.md)，确认 `BASE_URL`、Header、统一响应、错误码和阶段枚举。
2. 再读 [02-external-api-reference.md](./02-external-api-reference.md) 的 `0.1 接口总览` 和 `0.2 主页面最常用数据位置`，按业务动作查接口。
3. 按 [PROVIDER_API_PLAYBOOK.md](./PROVIDER_API_PLAYBOOK.md) 完成最小主链路联调。
4. 如果页面有动态表单或大 JSON 上下文，再读 [05-stage-form-context.md](./05-stage-form-context.md)。
5. 如果需要自己实现企业单点登录前端，再读 [06-yili-sso-frontend-integration.md](./06-yili-sso-frontend-integration.md)。
6. 如果要按 PRD 截图逐页还原 UI，再读 [01-prd-page-api-mapping.md](./01-prd-page-api-mapping.md)。

接口状态以 [02-external-api-reference.md](./02-external-api-reference.md) 为准；其中标注为“建议新增”的内容表示设计方案，不代表当前已经可调用。

## 当前主流程

PRD 页面对应的用户可见阶段固定为：

```text
research_design -> outline_design -> user_recruitment -> interview_execution -> insight_analysis
```

页面展示名称分别为：

```text
研究设计 -> 大纲设计 -> 用户招募 -> 访谈执行 -> 分析洞察
```

## 服务边界

OmniForge API 是业务事实源，负责：

- 任务 / 研究空间创建、列表、归档、删除。
- 阶段运行、阶段确认、驳回重跑、继续追问。
- 阶段表单 JSON 上下文接收、保存和业务事实抽取。
- 将用户提交或服务端抽取出的阶段表单 JSON 纳入后续大模型上下文；历史提交记录仍通过交互历史查询。
- 阶段产物 Artifact / ArtifactVersion 管理。
- 右侧文档预览所需的产物查询。
- 用户招募名单解析、访谈会议创建、访谈文本回传。
- 访谈材料入库、总结、证据链和报告生成。
- 调用 OmniForge 的鉴权、知识库、RAG、模型和 Agent 能力。

外部应以 [02-external-api-reference.md](./02-external-api-reference.md) 和 [PROVIDER_API_PLAYBOOK.md](./PROVIDER_API_PLAYBOOK.md) 为准进行联调。PRD 页面涉及的主链路接口均已统一归入对外接口参考文档；音频入口本期不启用，页面置灰或隐藏。