# AI 知识宇宙（K-World）

> 把书籍、报告和零散资料转成可搜索、可连接、可追溯的知识空间。

## AI audit entrypoints

- Project manifest: https://world.yuanxuntech.com/api/ai/manifest
- OpenAPI 3.1: https://world.yuanxuntech.com/api/ai/openapi.json
- Well-known manifest: https://world.yuanxuntech.com/.well-known/ai-project.json
- Application: https://world.yuanxuntech.com/

## Access and safety

- Authentication: none.
- Public read: true.
- Public write: false; an editor session is required for data-changing and expensive build routes.
- Do not run write, retry, force study-guide generation, or delete operations against production.
- Use an isolated instance for mutation testing.
- The read-only crawler is: npm run audit:ai -- --base-url https://world.yuanxuntech.com

## API

- GET /api/health [read] 读取服务健康状态、运行时间和模型公开配置。
- GET /api/model/status [read] 检查模型提供方、模式和缺少的配置项，不返回 API Key。
- GET /api/editor/session [read] 检查写操作是否启用以及当前浏览器是否拥有编辑会话。
- GET /api/accounts/session [read] 读取当前账号、套餐、额度和注册开关。
- POST /api/accounts/register [auth] 注册商业账号并创建免费套餐会话。
- POST /api/accounts/login [auth] 登录账号并创建 30 天 HttpOnly 会话。identifier 可填邮箱或用户名，username 字段仅作兼容。
- POST /api/accounts/password [auth] 修改自己的密码：必须提供当前密码，成功后吊销该账号的其它会话，保留当前会话。
- GET /api/accounts/me [read] 读取当前账号、套餐和本月用量。
- PATCH /api/accounts/me [write] 更新账号显示名称。修改密码请用 POST /api/accounts/password（必须提供当前密码）。
- GET /api/audit/events [read] 读取当前账号自己的操作审计记录。
- GET /api/admin/session [read] 查询当前访问者是否具备后台管理权限，以及权限来自编辑模式还是账号角色。
- GET /api/admin/overview [read] 后台总览：账号统计、套餐目录、知识宇宙总数和任务队列状态。
- GET /api/admin/users [read] 后台用户列表：支持按名称、邮箱、套餐或角色搜索，并返回用量、积分和额度。
- POST /api/admin/users [write] 后台新建用户，可直接指定角色、套餐、状态、初始积分和单独的额度覆盖。
- PATCH /api/admin/users/{userId} [write] 后台修改用户：名称、用户名、邮箱、密码、角色、套餐、启用状态和额度覆盖。用户名留空即清除；停用会立即注销其会话。
- DELETE /api/admin/users/{userId} [destructive] 后台删除用户，同时删除其知识宇宙与研究项目、移交其组织所有权并注销其全部会话。
- POST /api/admin/users/{userId}/credits [write] 增减用户积分，正数增加、负数扣减，余额不足会被拒绝；每次变动写入流水。
- GET /api/admin/settings [read] 读取站点开关（注册开放状态、是否需要登录），并说明取值来自后台设置还是服务器环境。
- PATCH /api/admin/settings [write] 后台一键开关公开注册与「需要登录」门禁；传 env 可恢复为跟随服务器环境变量。
- GET /api/admin/users/{userId}/credits [read] 读取某用户的积分余额与最近的积分流水。
- GET /api/admin/audit [read] 读取后台管理员操作审计（admin.* 事件）。
- GET /api/billing/status [read] 读取当前账号的套餐、订阅状态、可用升级项目和支付配置状态。
- GET /api/organizations [read] 列出当前账号加入的组织 Workspace 和成员。
- POST /api/organizations [write] 创建组织 Workspace；默认要求 Team 或 Enterprise 套餐。
- GET /api/organizations/{organizationId} [read] 读取组织详情和成员。
- PATCH /api/organizations/{organizationId} [write] 组织 owner 或 admin 更新组织名称和 slug。
- POST /api/organizations/{organizationId}/members [write] 组织 owner 或 admin 邀请账号并设置 admin、editor 或 viewer 角色。
- DELETE /api/organizations/{organizationId}/members/{userId} [destructive] 组织 owner 或 admin 移除成员；不能移除组织所有者。
- GET /api/organizations/{organizationId}/audit [read] 组织 owner 或 admin 导出组织审计记录，支持 JSON 或 CSV，最多 2000 条。
- GET /api/organizations/{organizationId}/api-keys [read] 组织 owner/admin 查看 API Key 元数据；不返回明文 Token 或哈希。
- POST /api/organizations/{organizationId}/api-keys [auth] 生成组织级 Enterprise API Key；明文 Token 只在创建响应中返回一次。
- DELETE /api/organizations/{organizationId}/api-keys/{keyId} [destructive] 吊销组织 API Key；之后使用该 Key 的请求返回 401。
- POST /api/billing/checkout [external] 为 Pro 或 Team 套餐创建 Stripe Subscription Checkout 会话。
- POST /api/billing/webhook [external] 接收签名验证后的 Stripe Checkout 和 Subscription Webhook，更新账号套餐状态。
- GET /api/research-projects [read] 列出当前账号的云端研究项目。
- POST /api/research-projects [write] 创建持久化云端研究项目，保存实体、来源和研究笔记。
- GET /api/research-projects/{projectId} [read] 读取一个云端研究项目。
- PATCH /api/research-projects/{projectId} [write] 更新研究项目状态、问题、宇宙关联或工作台内容。
- DELETE /api/research-projects/{projectId} [destructive] 永久删除当前账号的一个研究项目。
- GET /api/research-projects/{projectId}/collaboration [read] 读取研究项目评论、活动、审批状态和当前成员权限。
- POST /api/research-projects/{projectId}/comments [write] 在研究项目中发表评论，可附带实体、来源或章节锚点。
- PATCH /api/research-projects/{projectId}/comments/{commentId} [write] 修改评论正文或把评论标记为已解决。
- DELETE /api/research-projects/{projectId}/comments/{commentId} [destructive] 作者删除自己的评论，组织管理员可以删除任意评论。
- POST /api/research-projects/{projectId}/review/submit [write] editor、admin 或 owner 把研究项目提交给组织管理员审阅。
- POST /api/research-projects/{projectId}/review/decision [write] 组织 owner 或 admin 批准或退回研究项目。
- GET /api/research/runs [read] 列出当前账号的多 Agent 研究任务及六个阶段的定义。
- POST /api/research/runs [external] 启动持久化多 Agent 研究流水线：Research、Search、Extraction、Graph、Evidence、Writer。可指定 sourceScope 复用已有知识宇宙的资料池。
- GET /api/research/runs/{runId} [read] 读取多 Agent 研究任务的当前阶段、进度、来源、错误和关键结果。
- POST /api/research/runs/{runId}/retry [external] 重新启动失败或中断的多 Agent 研究流水线。
- POST /api/editor/login [auth] 验证编辑密码并创建 HttpOnly 编辑会话。公共读取不需要调用。
- POST /api/editor/logout [auth] 销毁当前编辑会话。
- POST /api/model/test [external] 向已配置模型发送一次连通性测试，会产生外部请求和模型费用。
- POST /api/documents/parse [cpu] 解析 Base64 文档并返回文本，支持 PDF、Word、Markdown、TXT、HTML 和电子书。
- POST /api/sources/fetch [external] 抓取公开 HTTP(S) 网页并提取正文，内网、元数据地址和本机地址会被拒绝。
- POST /api/research/collect [external] 通过 Tavily、Brave、Serper 或自定义搜索提供商收集多个网页，抓取正文并整理为研究资料。
- GET /api/universes [read] 列出全部知识宇宙及其统计信息。
- POST /api/universes [write] 创建知识宇宙并异步启动解析、抽取和图谱生成。
- GET /api/search [read] 在一个知识宇宙中按关键词和实体类型搜索。
- POST /api/chat [external] 基于指定知识宇宙和当前实体进行带证据的 AI 问答。
- POST /api/universes/{universeId}/retry [write] 重新启动失败或中断的知识宇宙构建任务。
- GET /api/universes/{universeId}/study-guide [conditional-write] 读取学习指南；首次生成或 force=1 时可能调用模型并持久化结果。
- GET /api/universes/{universeId}/research-report [read] 把当前知识宇宙整理为执行摘要、关键实体、发展时间线、关系、证据、结论和限制。
- GET /api/universes/{universeId}/evidence-verification [read] 核验关系来源数量、来源类型、平均可信度、弱来源、无来源实体和无来源时间事件。
- POST /api/universes/{universeId}/entities [write] 向一个知识宇宙手动添加实体，并可创建一条关系。
- DELETE /api/universes/{universeId} [destructive] 永久删除知识宇宙及其持久化文件。
- PATCH /api/universes/{universeId} [write] 知识宇宙所有者更新名称、说明或公开读取状态。
- POST /api/universes/{universeId}/members [write] 所有者邀请已注册账号并设置 viewer 或 editor 角色。
- DELETE /api/universes/{universeId}/members/{userId} [write] 所有者移除知识宇宙成员。
- GET /api/universes/{universeId} [read] 读取一个知识宇宙的完整实体、关系、时间线、来源和学习指南。
- GET /api/universes/{universeId}/entities/{entityId} [read] 读取单个实体及其关联证据。
- POST /api/universes/{universeId}/fact-check [external] 使用 Wikidata 对知识宇宙实体做外部事实核查，并把冲突加入人工复核。
- POST /api/universes/{universeId}/sources/verify [external] 通过 DOI 或 ISBN 核验来源元数据。
- POST /api/source-verification/check [external] 按 URL、发布方、作者、日期和外部数据库信号计算来源可信度。
- POST /api/source-verification/feedback [write] 用人工标注反馈训练并持久化来源可信度权重。
- GET /api/review-queue [read] 读取知识宇宙的人工证据复核队列。
- PATCH /api/review-queue/{itemId} [write] 认领、确认、忽略或要求补充证据。
- POST /api/universes/{universeId}/entity-resolution/run [write] 跨来源识别重复实体，自动合并高置信度项，并把冲突保留为人工候选。
- POST /api/universes/{universeId}/sources/incremental [write] 往已建好的知识宇宙补充资料：按来源指纹去重，重新用模型解析新增内容，只合并新增实体、关系、事件并标记受影响部分。
- GET /api/universes/{universeId}/research-report/export [read] 导出带引用的 Markdown、可编辑 Word 或 PDF 研究报告。
- GET /api/market [read] 公开搜索已发布知识宇宙市场。
- POST /api/market/{listingId}/fork [write] 把公开知识宇宙复制到当前账号的私有空间。
- POST /api/universes/{universeId}/publish [write] 知识宇宙所有者把知识宇宙发布到公开市场。
- GET /api/personalization [read] 读取当前账号的个性化偏好。
- GET /api/jobs [read] 读取持久化任务队列、优先级、预算、重试和状态统计。
- POST /api/jobs/{jobId}/cancel [write] 取消排队或运行中的长任务。

## User flows

- 打开应用并加载默认知识宇宙: GET / 加载 public/index.html、styles.css 和 app.js。 app.js 调用 GET /api/universes 和 GET /api/health。 选择列表中的第一个知识宇宙并调用 GET /api/universes/{universeId}。 初始化图谱、Wiki、时间线、证据库、搜索和 AI 面板。
- 切换知识宇宙: 点击知识宇宙条目。 前端销毁旧图实例并请求 GET /api/universes/{universeId}。 重新渲染全部视图。
- 全局搜索并检查实体: 输入人物、事件或概念关键词。 前端请求 GET /api/search。 选择结果后定位图谱节点并显示实体 Wiki 和证据。
- 节点浮动、体积碰撞与前后层次: 进入图谱视图后，rAF 循环按 25ms 节流推进节点位置，只写 position，不写样式。 每个节点围绕布局锚点向一个缓慢移动的目标点漂移（GRAPH_MOTION_SPRING）。 随后按均匀网格做两遍松弛：气泡重叠时互相推开，形成 Obsidian 那种有机的挤靠感。 每个节点带 0 到 1 的 depth：决定尺寸、透明度、边框、柔光晕、标签大小和 z-index。 depth 每 900ms 缓慢呼吸一次，每次只改动少量节点。 可见边数超过 560 / 1600 时逐级降为纯浮动或静态；帧间隔持续过慢时自动降级，平稳后可回升。 偏好保存在 localStorage 的 k-world:graph-motion，并尊重 prefers-reduced-motion。 离开图谱视图或标签页进入后台时停止循环并把节点放回布局位置。
- 追踪两个实体之间的最短关系路径: 点击关系追踪。 依次选择起点和终点实体。 前端在已加载图谱中计算路径并高亮节点与边。
- 创建知识宇宙: 打开创建对话框，输入名称、说明并添加文件、书名或 URL。 URL 通过 POST /api/sources/fetch 抓取正文。 文件通过 POST /api/documents/parse 解析，文本文件可在浏览器读取。 POST /api/universes 创建知识宇宙并轮询构建进度。
- 对开启登录门禁的站点执行完整审计: 不带凭据运行：识别门禁，确认公开入口正常，输出门禁报告并以退出码 0 结束。 带凭据运行（--login/--password、--editor、--cookie，或对应 K_WORLD_AUDIT_* 环境变量）：先登录换取会话 cookie，再爬取全部内容。 探测 /api/universes 判断是否真的被门禁拦住，而不是只看账号会话（运维身份用的是另一个 cookie）。 凭据错误、缺少密码或登录后仍无读取权限时明确报错并以退出码 1 结束。 凭据与 cookie 不写入报告，日志中的 cookie 脱敏为 kworld_account=***。
- 打开需要登录的站点: GET / 仍然公开，返回应用外壳；应用随后调用 GET /api/accounts/session。 会话返回 requiresLogin:true 且 authenticated:false 时，前端显示整屏登录门禁，不加载任何内容。 此时任何内容接口都返回 401 LOGIN_REQUIRED；只有 health、账号登录注册、编辑模式登录、Stripe 回调和机器可读入口保持公开。 通过门禁登录或注册成功后，前端隐藏门禁并启动应用、加载知识宇宙。 登出后会重新载入页面并回到门禁，确保上一个用户的内容不残留在 DOM 中。
- 后台新增并管理一个用户: 用编辑模式登录，或让账号角色为 admin；GET /api/admin/session 决定入口是否显示。 打开后台：GET /api/admin/overview 读套餐目录，GET /api/admin/users 读用户列表。 新建用户：POST /api/admin/users 可指定角色、套餐、状态、初始积分与额度覆盖。 编辑用户：PATCH /api/admin/users/{userId} 改角色、套餐、状态、密码与额度覆盖。 停用用户后其会话立即失效，再次登录返回 ACCOUNT_DISABLED。 调整积分：POST /api/admin/users/{userId}/credits，余额不足会被拒绝；GET 同路径读流水。 删除用户：DELETE /api/admin/users/{userId}，同时删除其知识宇宙与研究项目。 关闭注册：PATCH /api/admin/settings，公开注册入口与账号弹窗的注册标签同时隐藏；传 env 恢复为跟随环境变量。 所有写操作写入 admin.* 审计，可在 GET /api/admin/audit 查看。
- 给已建好的知识宇宙新增资料: 在知识宇宙顶部或学习页点击「新增资料」，打开增量上传对话框。 拖入或选择文件：POST /api/documents/parse 解析 PDF、Word、电子书正文。 粘贴公开网址：POST /api/sources/fetch 抓取网页正文。 也可以直接在对话框里粘贴正文并填写标题。 POST /api/universes/{universeId}/sources/incremental 提交资料批次，返回 202 与已排队任务。 前端每 4 秒轮询 GET /api/universes/{universeId}，用底部进度条展示 incrementalUpdate 进度。 任务完成后再加载 GET /api/universes/{universeId} 和 GET /api/universes/{universeId}/study-guide 展示合并后的实体、关系和学习指南。
- AI Research: 打开研究对话框并输入问题或网址。 网址先经 POST /api/sources/fetch 抓取。 使用研究模式 POST /api/universes 创建新的知识宇宙。
- 根据知识库上下文向 AI 提问: 选择实体并切换到 AI Explorer。 提交问题到 POST /api/chat。 渲染回答、引用证据和可执行的图谱或时间线动作。
- 生成或查看 AI 研究报告: 在 /research 输入研究问题、主题或公开网址。 账号模式调用 POST /api/research/runs 创建持久化六阶段研究任务。 前端轮询 GET /api/research/runs/{runId} 展示每个 Agent 的阶段状态。 完成后加载 GET /api/universes/{universeId}/research-report。 报告展示执行摘要、关键实体、时间线、关系、证据、核验结果、结论和研究限制。
- 保存研究材料到工作台: 在实体 Wiki 或证据详情中保存实体和来源。 工作台把数据保存在当前浏览器 localStorage。 用户可以添加研究笔记并导出 Markdown。 项目成员可以评论、解决评论、提交审阅，组织管理员批准或退回。
- 注册账号、建立私有宇宙并邀请团队: 注册或登录账号，系统创建账号会话和免费套餐额度。 创建知识宇宙，数据默认私有并归属于当前账号。 打开团队与共享，输入已注册成员邮箱并设置 viewer 或 editor。 所有者决定是否开放公开读取；所有付费和团队数据仍保持账号隔离。
- 创建组织并共享研究资源: Team 或 Enterprise 账号创建组织 Workspace。 组织 owner 或 admin 通过邮箱邀请 admin、editor 或 viewer。 组织成员共享研究项目和知识宇宙，角色决定读取和写入权限。 移除成员后，组织项目与知识宇宙权限立即同步收回。
- 事实核查、人工复核和报告交付: 在证据库触发 Wikidata 事实核查。 系统把冲突、弱来源和无证据结论送入人工复核队列。 复核人员确认、忽略或要求补充证据。 Writer 输出带引用的 Markdown、Word 和 PDF 报告。
- 发布市场、社区建议和个性化: 知识宇宙所有者发布公开市场条目。 其他账号可以提交社区建议或复制为私有知识宇宙。 所有者审核社区建议并应用到实体、关系或备注。 系统根据账号交互偏好生成个性化实体推荐。
- 手动添加实体和关系: 打开实体对话框并填写名称、类型、摘要、关联实体和关系。 POST /api/universes/{universeId}/entities。 重新加载当前知识宇宙并选中新实体。
- 导出学习笔记: 在学习视图打开已生成的学习指南。 前端将指南转换为 Markdown 并下载为文件。
- 删除知识宇宙: 点击知识宇宙条目上的删除按钮。 输入完整名称进行二次确认。 DELETE /api/universes/{universeId} 删除数据和持久化文件。

## Source review

The project source is intentionally not exposed by these endpoints. Review source files in the
project workspace using the sourceMap in the manifest. Secrets from .env and .env.local are never
included.