---
sidebar_position: 1
title: MindSpace Development Guide
sidebar_label: Overview
description: MindSpace product scope, architecture, implementation sequence, and acceptance criteria
---

# MindSpace 开发文档总览

MindSpace 是“每个人的 AI 个人空间”：注册用户可以上传资料，让 AI 或 goose 在授权范围内处理资料，将聊天或文件处理结果保存为页面、报告、图片或作品，并通过个人主页、公开链接、密码链接等方式发布。系统必须同时提供用户隔离、敏感信息检测、脱敏、审计和发布版本管理。

## 一句话定义

AI 聊天 + 文件空间 + 页面生成 + 对外发布 + 个人主页的一体化产品。

## 系统边界

- MindSpace 平台负责账号、空间、资产、页面、发布、权限、配额、安全和审计。
- goose 负责 AI 推理、工具调用、文件处理和 Agent 任务执行。
- H5、Web 和桌面端是 MindSpace 的客户端，不直接操作用户物理目录。
- 数据库保存业务元数据，文件系统或对象存储保存文件内容。
- 所有内部和外部文件访问都通过不可猜测的资产标识或发布标识完成。
- 私人资产不能直接变成公开资产，必须生成经过检查的发布副本。

## 开发文档

按以下顺序阅读和实施：

1. [产品范围与领域规则](./01-product-scope.md)
2. [模块拆分与职责边界](./02-module-breakdown.md)
3. [信息架构与页面原型](./03-ux-and-pages.md)
4. [系统架构与代码组织](./04-system-architecture.md)
5. [数据模型与状态机](./05-data-model.md)
6. [API 与错误契约](./06-api-contracts.md)
7. [安全、脱敏与审计](./07-security-and-audit.md)
8. [goose、Agent 与 CLI 集成](./08-agent-integration.md)
9. [前后端开发规范](./09-implementation-guide.md)
10. [MVP 与分阶段路线图](./10-roadmap.md)
11. [测试、验收、部署与运维](./11-testing-and-operations.md)
12. [模板、套餐、增长与商业化](./12-product-operations.md)
13. [需求覆盖矩阵](./13-requirements-traceability.md)
14. [开发进度](./14-implementation-status.md)

## 推荐实施原则

- 首期只实现注册登录、5 MB 配额、OA/私人/公开分类、上传、聊天保存页面、卡片主页、预览详情和公开/私有访问。
- 数据模型从第一天保留版本、发布、安全扫描、审计和 Agent 授权边界，但未启用功能可以不暴露 UI。
- 先实现“成果卡片”体验，再补完整文件树；首页不能退化为传统网盘。
- 先建立安全发布链路，再开放任意 HTML、外部脚本或自定义域名。
- 服务端是授权和状态的唯一可信来源，客户端不得自行判断所有权、配额或发布权限。

## 全局完成定义

每个功能只有同时满足以下条件才算完成：

- 有明确的领域对象、权限规则和状态变更。
- API 有请求、响应、错误码、幂等和分页约定。
- 前端覆盖加载、空状态、成功、失败、无权限和移动端布局。
- 关键写操作有审计记录。
- 私有数据不存在绕过安全检查的公开路径。
- 自动化测试覆盖正常路径、越权路径、配额边界和失败恢复。
- 数据迁移、配置项、日志、指标和回滚方式已说明。

## 核心术语

| 术语 | 定义 |
| --- | --- |
| Space | 每个用户唯一的个人空间及其配额 |
| Category | OA、私人、公开、草稿、归档等逻辑分类 |
| Asset | 文件、图片、文档、目录、页面包等可管理资产 |
| Page | 可预览、编辑、发布和版本化的作品记录 |
| Publication | 页面某个版本的一次发布配置与访问入口 |
| Public copy | 从原始资产生成的、可独立审查和发布的副本 |
| Security scan | 对内容、资源引用和 HTML 行为进行风险检测 |
| Agent job | 在明确输入、输出和权限范围内执行的 AI 任务 |
| Audit log | 不可由普通用户修改的关键操作记录 |

## 不在首期范围

- 团队空间、企业组织树和复杂 RBAC。
- 自定义域名、CDN 和多地域对象存储。
- 发布审批流和多人协作编辑。
- 高级 OCR、医疗诊断或法律结论。
- 支付、预约、表单收集和营销自动化。
- 任意第三方 JavaScript 或不受控 iframe。