tkmind/memind
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Add MindSpace decoupling foundation

Browse Source
This commit is contained in:
john
2026-07-02 21:03:14 +08:00
parent ddfa60607a
commit e4d6267c96
12 changed files with 1644 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/memind-control-execution-split-plan-20260702.md
+540
View File
@@ -0,0 +1,540 @@
# Memind / MindSpace / Goose 解耦推进方案
日期: 2026-07-02
适用目标:
- 把 MindSpace 从 Memind Portal 单体中拆出来，成为可以独立部署、独立扩容、独立迁移存储的服务。
- Memind 继续负责产品入口、用户会话、聊天体验、套餐/能力编排和业务路由。
- Goose 继续负责 agent 执行，但不直接拥有 MindSpace 状态，也不把某台机器的文件路径当作长期契约。
- 每次对话生成或上传的图片、文件、页面、公开链接等，都要形成一个可浏览、可迁移、可打包的 conversation package。
本文只描述架构目标、边界和推进计划，不要求一次性完成所有代码拆分。
## 0. 结论
应该拆，但不要按“105 = Control Portal，103 = Execution Portal”的机器绑定方式拆。
正确目标是服务边界:
```text
Memind App
- H5 / 服务号 / 认证入口 / 用户会话
- 聊天 UI 和产品业务编排
- 套餐、能力、计费、请求整形
- 不拼接 MindSpace 物理路径
- 不假设 MindSpace 部署在哪台机器
MindSpace Service
- space / asset / page / publication / conversation package
- canonical URL 生成和 public backing file 校验
- 存储适配器: local fs / NAS / S3 / 其它对象存储
- 权限、审计、manifest、元数据和实际文件一致性
- 可以独立部署在任意位置
Goose Runtime
- agent session / tool execution / long running job
- 通过 MindSpace API 或 MindSpace MCP 读写文件
- 不直接拥有 MindSpace 元数据
- 不把本地 `MindSpace/<userId>` 路径作为产品级契约
```
103/105 只能作为当前生产部署拓扑的一个例子。103 是生产，不是本地开发依赖，也不应该成为 MindSpace 独立化后的架构前提。
硬性规则:
1. MindSpace 的真实存储位置必须可替换，本地开发、NAS、S3 都应该只是 storage adapter。
2. Memind 不得根据 userId、slug、fileName 自己拼接 MindSpace public URL。
3. Goose 不得直接写业务数据库里的 MindSpace 状态，只能通过 MindSpace API/MCP 能力写入。
4. MindSpace Service 是 asset/page/publication/package 元数据和 canonical URL 的唯一权威。
5. 每个用户对话产生的文件必须归属到一个 conversation package，不能只散落在物理目录里。
6. 物理目录结构不是外部契约；外部契约应该是 package id、asset id、page id、publication id 和 canonical URL。
## 1. 当前现状
当前 `/Users/john/Project/Memind` 更接近一个运行态 Portal 单体:
- `server.mjs` 同时承载 H5 API、用户认证、MindSpace API、文件/发布服务、agent session proxy、Agent job worker、workspace watcher、微信/Plaza 等。
- Goose 是执行后端，Portal 通过 `TKMIND_API_TARGETS` / `TKMIND_API_TARGET` 调它。
- MindSpace 有两类本地状态:
- workspace/public 文件: `MindSpace/<userId>/...`
- asset/page/publication 存储: `data/mindspace/users/...`
- MySQL/RDS 保存用户、资产、页面、发布、任务、会话、计费、Plaza/微信等业务状态。
- `h5_page_records` 已有 `source_session_id`、`source_message_id`，`h5_agent_jobs` 也有 `session_id`，说明页面和任务已经部分具备对话来源线索。
- 但 `h5_assets` 这类底层文件资产还没有完整的 conversation package 归属模型。
现在最危险的隐含假设不是 HTTP 能不能转发，而是代码里把“某台机器上的路径”和“产品里的 MindSpace 文件”混成了同一个概念。未来 MindSpace 可以在本机、NAS、S3 或独立服务中，Memind 和 Goose 都不能依赖这层物理细节。
## 2. 目标架构
```mermaid
flowchart LR
U["Browser / WeChat"] --> M["Memind App"]
M --> MS["MindSpace Service"]
M --> AG["Agent Gateway"]
AG --> G["Goose Runtime"]
G --> MCP["MindSpace MCP / API"]
MCP --> MS
MS --> DB["Metadata DB"]
MS --> ST["Storage Adapter"]
ST --> LFS["Local FS"]
ST --> NAS["NAS"]
ST --> S3["S3 / Object Storage"]
```
核心变化:
- Memind App 面向用户，不面向物理文件系统。
- MindSpace Service 面向文件、页面、发布、包和存储后端。
- Goose Runtime 面向执行，不面向 MindSpace 业务所有权。
- Storage Adapter 面向字节和对象，不面向用户、会话、页面这些业务概念。
## 3. 服务边界
### 3.1 Memind App
Memind App 负责:
- H5 静态入口和聊天体验。
- 服务号 webhook、菜单、客服入口。
- 用户登录、session、cookie/header 规范化。
- 套餐、能力、计费和业务策略。
- 把用户请求转成 MindSpace API、Agent Gateway API 调用。
- 展示 MindSpace 返回的 URL、JSON、SSE、HTML 状态。
Memind App 禁止:
- 拼接 `MindSpace/<userId>/public/*.html`。
- 直接读写 `MindSpace/` 或 `data/mindspace/`。
- 根据文件名猜测 public URL。
- 自己判断 public backing file 是否存在。
- 把具体机器路径传给前端当长期 API。
### 3.2 MindSpace Service
MindSpace Service 负责:
- Space、category、asset、asset version、page、page version、publication。
- Conversation package 和 package manifest。
- Canonical public URL 生成。
- Public backing file 存在性校验。
- 文件上传、下载、预览、缩略图、长图、HTML 页面落盘。
- 存储适配器封装: local fs、NAS、S3、其它对象存储。
- 权限校验、审计、配额和一致性修复。
MindSpace Service 应该提供稳定 API:
```text
/api/mindspace/v1/spaces
/api/mindspace/v1/assets
/api/mindspace/v1/pages
/api/mindspace/v1/publications
/api/mindspace/v1/conversation-packages
/api/mindspace/v1/conversation-packages/:packageId/manifest
/api/mindspace/v1/conversation-packages/:packageId/artifacts
```
### 3.3 Goose Runtime
Goose Runtime 负责:
- Agent session start/reply/resume/events。
- Tool execution。
- Long running job。
- 通过 MindSpace MCP/API 读取输入文件、写入生成文件、创建页面、发布页面。
Goose Runtime 不应直接负责:
- MindSpace 数据库表的业务写入。
- Public URL 拼接。
- 页面发布状态判断。
- Conversation package manifest 的最终一致性。
短期内，如果 local filesystem adapter 仍需要 `sandboxRoot`，可以继续保留本地路径注入。但它只能是某个 adapter 的内部实现，不应该是 Memind/MindSpace/Goose 之间的长期契约。
## 4. Conversation Package 模型
用户要求的“每次对话里面的文件形成一个文件夹包”，建议抽象成 conversation package。
它在产品上像文件夹，在系统里是元数据包:
```text
mindspace://users/<userId>/conversations/<sessionId>/
manifest.json
input/
images/
files/
pages/
public/
generated/
```
注意: 上面是逻辑视图，不要求物理存储必须长这样。local fs 可以映射成真实目录，NAS 可以映射成共享目录，S3 可以映射成 object prefix。
Package manifest 应包含:
- `packageId`
- `userId`
- `sessionId`
- `title`
- `createdAt`
- `updatedAt`
- `storagePrefix`
- `artifacts[]`
- `pages[]`
- `publications[]`
- `messages[]`
- `agentRuns[]`
Artifact 应至少包含:
- `artifactId`
- `assetId`
- `pageId`
- `publicationId`
- `messageId`
- `agentRunId`
- `kind`: `input_image` / `input_file` / `generated_image` / `generated_file` / `page` / `public_html` / `long_image`
- `displayName`
- `mimeType`
- `sizeBytes`
- `storageKey`
- `canonicalUrl`
- `createdAt`
推荐新增表:
```sql
CREATE TABLE h5_conversation_packages (
id VARCHAR(64) PRIMARY KEY,
user_id VARCHAR(64) NOT NULL,
session_id VARCHAR(128) NOT NULL,
title VARCHAR(255) DEFAULT NULL,
status VARCHAR(32) NOT NULL DEFAULT 'active',
storage_prefix VARCHAR(512) DEFAULT NULL,
manifest_asset_id VARCHAR(64) DEFAULT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uniq_conversation_package_session (user_id, session_id)
);
CREATE TABLE h5_conversation_artifacts (
id VARCHAR(64) PRIMARY KEY,
package_id VARCHAR(64) NOT NULL,
asset_id VARCHAR(64) DEFAULT NULL,
page_id VARCHAR(64) DEFAULT NULL,
publication_id VARCHAR(64) DEFAULT NULL,
agent_run_id VARCHAR(128) DEFAULT NULL,
message_id VARCHAR(128) DEFAULT NULL,
role VARCHAR(32) DEFAULT NULL,
artifact_kind VARCHAR(64) NOT NULL,
sort_order INT NOT NULL DEFAULT 0,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
KEY idx_conversation_artifacts_package (package_id),
KEY idx_conversation_artifacts_asset (asset_id),
KEY idx_conversation_artifacts_page (page_id),
KEY idx_conversation_artifacts_message (message_id)
);
```
也可以先用轻量方案过渡:
- 给 `h5_assets` 增加 `source_session_id`、`source_message_id`、`source_run_id`。
- 利用现有 `h5_page_records.source_session_id`、`h5_page_records.source_message_id` 回填页面来源。
- 利用现有 `h5_agent_jobs.session_id` 回填 agent 生成物来源。
- 先做 package view，再补完整 package tables。
## 5. Storage Adapter
MindSpace Service 内部需要统一存储接口:
```ts
interface MindSpaceStorageAdapter {
putObject(key, body, options)
getObject(key)
statObject(key)
deleteObject(key)
listObjects(prefix, options)
copyObject(sourceKey, targetKey, options)
createReadStream(key)
createWriteStream(key, options)
getSignedUrl(key, options)
}
```
推荐分层:
```text
MindSpace Domain
-> Asset/Page/Publication/Package services
-> Storage adapter interface
-> local fs / NAS / S3 implementations
```
关键要求:
- Memind 不知道 `storageKey` 如何映射到磁盘或 S3。
- Goose 不直接生成 public URL，只提交产物给 MindSpace。
- public URL 可以是 MindSpace Service 的 route，也可以是 CDN/object storage URL，但必须由 MindSpace Service 生成。
- 本地开发默认用 local fs adapter，不依赖 103。
- 生产可以继续先用现有机器路径，之后切 NAS/S3 时不改 Memind/Goose 业务层。
## 6. Agent 执行契约调整
当前 agent policy 里的关键值包括:
- `sandboxRoot`
- `serverPath`
- `nodeExecPath`
- MCP envs
这些仍可作为短期兼容层，但长期应改成:
```json
{
"mindspace": {
"workspaceRef": "mindspace://users/u_xxx/conversations/s_xxx",
"packageId": "cp_xxx",
"apiBaseUrl": "https://mindspace.example.com",
"accessToken": "scoped-short-lived-token",
"allowedTools": ["read_file", "write_file", "edit_file", "publish_page"]
}
}
```
推进原则:
- Local fs adapter 可以把 `workspaceRef` 映射到本机临时目录或真实目录。
- NAS adapter 可以把 `workspaceRef` 映射到共享挂载目录。
- S3 adapter 不应暴露 raw fs path，应通过 MCP/API 完成读写和预览。
- Agent 写入完成后，MindSpace Service 负责把产物登记到 package manifest。
## 7. 推进阶段
### P0: 盘点和冻结边界
目标: 先明确哪些代码还在直接使用路径、URL、数据库表。
输出:
- 路径调用点清单: `MindSpace/`、`data/mindspace/`、`sandboxRoot`、`public/*.html`。
- URL 调用点清单: `/MindSpace/`、`canonicalUrl`、`publicationUrl`。
- DB 调用点清单: asset/page/publication/job/session 相关表。
- 当前本地开发拓扑和生产拓扑分开写清楚，避免继续把 103 当开发依赖。
### P1: 在单体内抽出 MindSpace Service 边界
目标: 不改部署方式，先把边界从代码里立起来。
动作:
- 新增或整理 `MindSpaceService` domain 层。
- 引入 `MindSpaceStorageAdapter` interface。
- local fs adapter 先包住现有 `MindSpace/` 和 `data/mindspace/`。
- 禁止新代码直接拼接 MindSpace public URL。
- 给 public URL 生成和 backing file 校验加集中入口。
验收:
- 现有 H5、公开页、页面发布、文件下载行为不变。
- 代码搜索可以证明新增业务不再直接依赖物理路径。
### P2: Conversation Package 首先落地
目标: 用户每次对话生成的图片、文件、页面、公开链接都能在一个包里看到。
动作:
- 为每个 chat session 创建或懒创建 conversation package。
- 上传文件、图片描述、页面生成、长图、HTML 发布都写入 artifact 归属。
- 新增 package manifest API。
- H5 增加 package view: 图片、文件、页面、公开链接按对话聚合展示。
- 对历史数据做 best-effort 回填。
验收:
- 一次对话中上传图片、生成 HTML、发布页面后，package 页面能看到所有产物。
- package manifest 可以导出，并能指向真实可读的 backing file。
- 不再只能靠散落目录追查某次对话产生了什么。
### P3: MindSpace Service 本地独立进程
目标: 在本机开发环境先拆进程，不碰生产 103。
动作:
- MindSpace API 单独启动，例如 `localhost:<mindspace-port>`。
- Memind App 通过 `MINDSPACE_API_BASE_URL` 调它。
- Goose 仍可本地运行，但通过 MindSpace API/MCP 获取 workspace。
- 本地 storage adapter 继续使用 local fs。
验收:
- 停掉 MindSpace Service 后，Memind H5 能明确报 MindSpace 不可用，而不是静默写本地路径。
- 换一个 local storage root 后，Memind 和 Goose 不需要改业务代码。
### P4: MindSpace MCP Bridge
目标: Goose 不再把 raw filesystem path 当核心契约。
动作:
- MCP tools 改为接受 `workspaceRef` / `packageId`。
- `read_file`、`write_file`、`edit_file`、`publish_page` 通过 MindSpace Service 落元数据。
- scoped token 限制到用户、session、package 和允许工具。
验收:
- Agent 生成文件后，MindSpace package manifest 自动更新。
- Policy 泄漏时也只能访问当前 package 范围。
### P5: NAS/S3 Adapter
目标: 存储后端可替换。
动作:
- 实现 NAS adapter 或 S3 adapter。
- 增加 migration/backfill 工具，把现有文件迁移到新 storage prefix。
- 增加校验脚本: DB record、manifest、object stat、public URL 一致。
- 必要时先 shadow-read 或 dual-write，降低迁移风险。
验收:
- local fs 切到 NAS/S3 后，Memind App 不改代码。
- Goose 不改业务契约。
- 公开页、下载、预览、长图、package manifest 都正常。
### P6: 生产部署迁移
目标: 等本地和 staging 验证后，再考虑生产拓扑。
原则:
- 103/105 只是部署位置，不是架构边界。
- 当前 103 可以继续承载旧 Portal 和 MindSpace，直到 MindSpace Service 独立进程稳定。
- 生产迁移前必须有回滚方案、manifest 校验、public URL 抽样验证。
- 不从本地直接依赖 103 做开发验证。
## 8. 当前 103/105 如何理解
如果短期还要用 103/105 描述生产部署，可以这样表述:
```text
105 = public edge / Memind App entry
103 = current production host running legacy Portal + MindSpace + Goose
```
但这只是当前生产状态，不是最终架构。
最终应该允许:
```text
Memind App: 105 / k8s / 任意 Web 服务
MindSpace: 独立 VM / NAS 旁路服务 / S3-backed 服务 / k8s service
Goose Runtime: 本机 / worker pool / 独立执行集群
Storage Backend: local fs / NAS / S3 / CDN-backed object storage
```
## 9. 验收标准
拆分成功不以“服务能启动”为准，而以这些行为为准:
1. 一次对话上传的图片、文件、生成页面、公开 HTML、长图都能在同一个 package 中看到。
2. Package manifest 中的每个 artifact 都能追溯到 asset/page/publication/message/run。
3. Memind App 不直接拼接 MindSpace 物理路径或 public URL。
4. Goose 生成文件后，MindSpace 元数据和实际 backing file 一致。
5. 切换 local fs / NAS / S3 adapter 时，Memind App 和 Goose 的业务逻辑不需要改。
6. 公开 URL 由 MindSpace Service 生成并校验。
7. 本地开发不依赖 103，生产 103 也不是架构上的必须组件。
## 10. 风险
| 风险 | 表现 | 控制方式 |
| --- | --- | --- |
| 路径假设太深 | 代码到处拼 `MindSpace/<userId>` | P0 做调用点清单，P1 加 service/adapter 边界 |
| URL 权威混乱 | Memind、Goose、MindSpace 各自拼 URL | URL 只由 MindSpace Service 生成 |
| Agent 直写绕过元数据 | 文件存在但 package 看不到 | MCP/API 写入后必须登记 artifact |
| S3 非文件系统语义 | `edit_file`、stream、rename 行为不一致 | 先定义 adapter 能力，必要时用临时工作区 materialize |
| 迁移丢历史关系 | 老页面找不到来源对话 | 利用现有 `source_session_id`、job session 做 best-effort 回填 |
| 权限过宽 | agent token 访问其它用户文件 | scoped short-lived token，绑定 user/session/package |
| package 过大 | 长对话产物太多 | manifest 分页、artifact 分类、归档策略 |
| 生产切换风险 | public link 失效 | 迁移前跑 object stat + URL 抽样 + 回滚 |
## 11. 建议下一步
建议按这个顺序推进:
1. 保留本文档为总纲，另外新增 `docs/mindspace-service-contract.md` 写 API、storage adapter、package manifest 的详细契约。
2. 做 P0 audit: 搜索所有 `MindSpace/`、`data/mindspace`、`sandboxRoot`、`/MindSpace/`、`canonicalUrl` 调用点。
3. 先在单体内做 P1，不急着拆进程，避免一次同时改部署、存储、执行链路。
4. 优先实现 P2 conversation package，因为这是用户可见价值，也能倒逼所有产物建立 provenance。
5. 本地完成 P1/P2 smoke 后，再做 P3 独立 MindSpace Service。
6. 等 P3 稳定后再考虑 P4 MCP 契约和 P5 NAS/S3。
7. 生产 103/105 迁移放到最后，只作为部署迁移，不作为架构设计的出发点。
最小可交付版本:
```text
单体内 MindSpaceService 边界
+ local fs storage adapter
+ conversation package tables/API
+ H5 package view
+ public URL 集中生成
+ 现有发布/下载/预览回归通过
```
这个版本即使还没有真正拆进程，也已经把未来独立部署、NAS/S3 和 Goose 解耦的地基打好了。
## 12. 启动门禁和回退策略
本轮推进只能在独立分支上开始，禁止直接提交 `main`。
当前建议分支:
```text
codex/mindspace-decouple-20260702
```
开始任何代码改动前必须先确认:
```bash
git branch --show-current
git status --short --branch
git merge-base --is-ancestor origin/main HEAD
```
通过条件:
- 当前分支不是 `main`。
- 当前分支基于最新 `origin/main` 创建。
- 工作区里只出现本轮 MindSpace 解耦相关文件。
- 不允许从本机开发流程依赖 103。
本地保护:
- `.git/hooks/pre-commit` 应阻止在 `main` 上直接 commit。
- 如果需要新分支，必须使用 `bash scripts/new-branch.sh <branch-name>`，不要直接在脏工作区切分支。
- 每个阶段开始前先记录 `git status --short --branch`。
回退分三层:
1. 单文件回退: 如果某个文件改坏，只恢复该文件，不影响其它正在推进的内容。
2. 阶段回退: P1/P2/P3 每个阶段独立提交；如果阶段失败，只 revert 该阶段提交。
3. 分支回退: 如果方向整体不对，保留 `main` 不动，直接放弃 `codex/mindspace-decouple-20260702` 分支即可。
禁止事项:
- 禁止在 `main` 上 commit。
- 禁止从脏工作区发布。
- 禁止把 103 当作本地开发依赖。
- 禁止在没有 package provenance 的情况下继续扩大文件生成链路。
- 禁止把 storage backend 细节暴露成 Memind 或 Goose 的长期 API。
第一批可执行任务:
1. P0 audit: 生成路径、URL、policy、DB 调用点清单。
2. 新增 `docs/mindspace-service-contract.md`，只写契约，不改运行逻辑。
3. 设计 conversation package schema migration，但先不执行生产迁移。
4. 在单体内抽 `MindSpaceStorageAdapter` 和 public URL 生成入口。
5. 给现有发布/下载/预览跑回归，再进入下一阶段。
docs/mindspace-boundary-audit-20260702.md
+161
View File
@@ -0,0 +1,161 @@
# MindSpace 解耦 P0 边界审计
日期: 2026-07-02
分支: `codex/mindspace-decouple-20260702`
目标:
- 找出当前代码中直接依赖 MindSpace 物理路径、公开 URL、agent sandbox policy、MindSpace DB 表的边界点。
- 为后续 P1 `MindSpaceService`、P2 conversation package、P3 独立进程拆分提供改造顺序。
- 本文只做审计和分层，不改变运行行为。
## 1. 审计结论
当前 MindSpace 已经具备资产、页面、发布、agent job 的基础模型，但边界仍混在 Portal 单体里:
- 物理 workspace 路径由 `user-publish.mjs`、`user-space.mjs`、`server.mjs`、`capabilities.mjs` 共同参与。
- 公开 URL 由 `user-publish.mjs`、`mindspace-assets.mjs`、`mindspace-publications.mjs`、`server.mjs` 等处生成或修正。
- Agent sandbox policy 仍以 `sandboxRoot` / `SANDBOX_ROOT` 为核心契约。
- DB 层已有 `h5_page_records.source_session_id`、`h5_page_records.source_message_id`、`h5_agent_jobs.session_id`，但 `h5_assets` 还缺 conversation provenance。
- 现有回归守卫重点保护 `public/*.html` materialize、Finish merge、用户消息内部前缀隐藏，这些路径后续改造时不能绕过。
架构判断:
- P1 先抽 `MindSpaceService` 和 storage adapter 边界，不拆进程。
- P2 先落 conversation package 元数据和 manifest，不立即替换所有文件路径。
- P3 以后再把 MindSpace Service 独立进程化。
- 103/105 只作为生产部署说明，不作为开发或架构依赖。
## 2. 物理路径边界
核心文件:
| 文件 | 当前职责 | 风险 | P1 处理方式 |
| --- | --- | --- | --- |
| `user-publish.mjs` | `PUBLISH_ROOT_DIR = MindSpace`、用户发布目录、公开 URL helper、skill 约束文本 | URL 和路径耦合在同一层 | 保留兼容 helper，但新代码走 `MindSpaceService` URL/storage 接口 |
| `user-space.mjs` | `MINDSPACE_STORAGE_ROOT`、workspace 分区、上传镜像、agent hints | workspace 和 asset storage 同时出现 | 把 storage root、workspace root 分离为 adapter 能力 |
| `server.mjs` | watcher、static route、shared upload、public serving | Portal 直接掌握所有路径 | P1 先集中成 MindSpace route/service facade |
| `mindspace-sandbox-mcp.mjs` | OS 层 `SANDBOX_ROOT` 文件操作 | Goose 以 raw fs path 作为契约 | P4 改成 `workspaceRef` / `packageId`，短期保留兼容 |
| `capabilities.mjs` | 注入 sandbox MCP env 和 args | policy 直接依赖 `sandboxRoot` | 新增 policy adapter，避免业务层自己拼 path |
主要路径形态:
```text
MindSpace/<userId>/public/*.html
MindSpace/<userId>/oa/*
data/mindspace/users/<userId>/*
SANDBOX_ROOT=<absolute workspace path>
MINDSPACE_STORAGE_ROOT=<absolute storage path>
```
## 3. URL 权威边界
核心文件:
| 文件 | 当前职责 | 风险 | P1 处理方式 |
| --- | --- | --- | --- |
| `user-publish.mjs` | `buildPublicUrl()`、`buildPublicZonePageUrl()` | 调用方可能把 helper 当长期权威 | 标记为 legacy compatibility，新增 canonical URL service |
| `mindspace-assets.mjs` | public temp image URL | asset public URL 与 storage key 绑定 | 改成 `MindSpaceService.createPublicAssetUrl()` |
| `mindspace-publications.mjs` | publication response、public URL、标准图片替换 | 发布 URL 权威分散 | publication canonical URL 统一收口 |
| `server.mjs` | `/MindSpace/*` route、redirect、shared upload public URL | Express route 同时做 URL 修复和文件服务 | route 仅调用 MindSpace service facade |
| `mindspace-chat-save.mjs` | 修正聊天中的 MindSpace 链接 | 后续仍需兼容旧 URL | 保留兼容，新增 canonicalize API |
短期规则:
- 不删除旧 URL helper。
- 新增代码不得直接拼 `/MindSpace/<userId>/...`。
- 所有新 public URL 生成必须经过 MindSpace service facade。
## 4. Agent Policy 边界
核心文件:
| 文件 | 当前职责 | 风险 | P1/P4 处理方式 |
| --- | --- | --- | --- |
| `capabilities.mjs` | 将 sandbox MCP 注入 Goose extension | policy 里暴露 raw path | 先增加 policy builder 边界，后续改 workspaceRef |
| `mindspace-agent-runner.mjs` | agent job claim 后创建 goosed 运行上下文 | job 与 workspace/path/publish layout 混合 | job runner 改为请求 MindSpace workspace capability |
| `user-space.mjs` | hints 中告诉 agent 目录和公开链接格式 | agent 直接学习物理路径 | hints 改为逻辑 workspace + 兼容说明 |
| `mindspace-sandbox-mcp.mjs` | read/write/edit/create_dir | 只能处理 filesystem backend | 后续新增 MindSpace MCP bridge |
长期 policy 目标:
```json
{
"mindspace": {
"workspaceRef": "mindspace://users/<userId>/conversations/<sessionId>",
"packageId": "cp_xxx",
"apiBaseUrl": "https://mindspace.example.com",
"accessToken": "scoped-short-lived-token"
}
}
```
## 5. DB 和 Provenance 边界
已有基础:
- `h5_assets`: asset 基础元数据，当前没有 `source_session_id`、`source_message_id`、`source_run_id`。
- `h5_asset_versions`: `storage_key` 是当前 asset 到物理存储的主要桥。
- `h5_page_records`: 已有 `source_session_id`、`source_message_id`、`source_asset_id`。
- `h5_page_versions`: 已有 `source_snapshot_json`，可承载页面生成时的上下文。
- `h5_publish_records`: 保存 `public_url`，是公开 URL 现有权威记录。
- `h5_publication_asset_refs`: publication 与 asset 引用关系。
- `h5_agent_jobs`: 已有 `session_id`、`result_page_id`、`result_asset_id`。
- `h5_agent_runs`: 已有 `agent_session_id`、`request_id`。
缺口:
- 没有 conversation package 表。
- 没有 package 与 asset/page/publication/job/message 的统一 artifact 关系表。
- Asset 层没有完整对话来源，导致“这次对话生成了哪些文件”只能间接推断。
建议新增:
- `h5_conversation_packages`
- `h5_conversation_artifacts`
过渡策略:
- 先通过 `h5_page_records.source_session_id` 和 `h5_agent_jobs.session_id` 回填页面/任务。
- 新增 asset 时尽量携带 `session_id`、`message_id`、`run_id` 到 artifact 表。
- 不急着修改旧 asset schema，优先用 junction table 降低迁移风险。
## 6. 回归守卫
后续改这些区域前必须跑:
```bash
npm run verify:mindspace-publish-guards
npm run verify:mindspace-publish-guards:full
```
重点保护:
- `mindspace-public-finish-sync.mjs`: `edit_file` 必须 materialize 到 `public/*.html`。
- `chat-finish-sync.mjs`: Finish / UpdateConversation 必须 merge，禁止盲覆盖。
- `conversation-display.mjs` 和 `src/utils/message.ts`: 用户消息不得展示 routing/skill 内部前缀。
- `src/hooks/useTKMindChat.ts`: `syncSessionMessages` merge + retry。
- `server.mjs`: session snapshot 缓存必须保守。
## 7. 第一阶段落点
P1 最小代码目标:
- 新增 `MindSpaceStorageAdapter` 契约和 local fs adapter 包装层。
- 新增 canonical public URL facade。
- 新增 conversation package manifest 纯函数。
- 先不替换现有 route，不改生产行为。
P2 最小产品目标:
- 为每个 chat session 懒创建 package。
- 新上传文件、生成文件、页面、发布记录写入 artifact 归属。
- H5 增加 package view。
- 历史数据 best-effort 回填。
本轮已经开始的安全基线:
- 当前工作必须在 `codex/mindspace-decouple-20260702`。
- `main` 本地 pre-commit 已阻止直接提交。
- 不允许把 103 作为本地开发依赖。
docs/mindspace-service-contract.md
+261
View File
@@ -0,0 +1,261 @@
# MindSpace Service Contract
日期: 2026-07-02
状态: Draft for P1/P2
目标:
- 定义 MindSpace 从 Memind Portal 单体拆出前必须稳定下来的 API、存储、URL、权限和 package 契约。
- 允许先在单体内实现，再独立成进程。
- 保证 Memind App 和 Goose Runtime 不依赖 MindSpace 的物理部署位置。
## 1. 边界原则
MindSpace Service 是以下对象的唯一权威:
- Space
- Category
- Asset
- Asset Version
- Page
- Page Version
- Publication
- Conversation Package
- Package Manifest
- Canonical Public URL
- Storage Key 到 backing object 的校验
Memind App 只调用 API，不直接读写 `MindSpace/` 或 `data/mindspace/`。
Goose Runtime 只通过 MindSpace API/MCP 获得 scoped workspace capability，不直接拥有 MindSpace 业务状态。
## 2. API Surface
建议从当前 `/api/mindspace/v1/*` 延续，先在单体内实现兼容 facade:
```text
GET /api/mindspace/v1/spaces/current
GET /api/mindspace/v1/assets
POST /api/mindspace/v1/assets/uploads
GET /api/mindspace/v1/assets/:assetId/download
GET /api/mindspace/v1/pages
POST /api/mindspace/v1/pages
GET /api/mindspace/v1/pages/:pageId
POST /api/mindspace/v1/pages/:pageId/publish
GET /api/mindspace/v1/publications/:publicationId
GET /api/mindspace/v1/conversation-packages
POST /api/mindspace/v1/conversation-packages/ensure
GET /api/mindspace/v1/conversation-packages/:packageId
GET /api/mindspace/v1/conversation-packages/:packageId/manifest
POST /api/mindspace/v1/conversation-packages/:packageId/artifacts
```
所有响应必须包含稳定 ID，不把物理路径作为前端契约。
## 3. Storage Adapter
MindSpace Service 内部存储接口:
```ts
interface MindSpaceStorageAdapter {
putObject(key, body, options)
getObject(key)
statObject(key)
deleteObject(key)
listObjects(prefix, options)
copyObject(sourceKey, targetKey, options)
createReadStream(key)
createWriteStream(key, options)
getSignedUrl(key, options)
}
```
Adapter 要求:
- `key` 是相对 storage root 的逻辑 object key，禁止绝对路径。
- local fs adapter 可以把 key 映射到磁盘。
- NAS adapter 可以把 key 映射到共享挂载。
- S3 adapter 可以把 key 映射到 object prefix。
- 业务层不得依赖 adapter 的物理实现。
## 4. Canonical URL
URL 生成入口:
```ts
createPublicPageUrl({ userId, publicationId, pageId, slug })
createPublicAssetUrl({ userId, assetId, variant })
canonicalizeMindSpaceUrl(inputUrl)
validatePublicBackingObject({ publicationId })
```
规则:
- 新代码不得直接拼 `/MindSpace/<userId>/...`。
- 旧 URL helper 暂时保留为 compatibility layer。
- public URL 必须能反查到 publication 或 asset。
- URL 返回前应校验 backing object 存在，或明确返回 pending 状态。
## 5. Conversation Package
Conversation package 是“每次对话文件夹包”的业务抽象。
逻辑 URI:
```text
mindspace://users/<userId>/conversations/<sessionId>
```
推荐 manifest:
```json
{
"schemaVersion": 1,
"packageId": "cp_xxx",
"userId": "u_xxx",
"sessionId": "s_xxx",
"title": "对话标题",
"storagePrefix": "users/u_xxx/conversations/s_xxx",
"artifacts": [
{
"artifactId": "ca_xxx",
"kind": "public_html",
"assetId": "asset_xxx",
"pageId": "page_xxx",
"publicationId": "pub_xxx",
"messageId": "msg_xxx",
"agentRunId": "run_xxx",
"displayName": "report.html",
"mimeType": "text/html",
"sizeBytes": 12345,
"storageKey": "users/u_xxx/conversations/s_xxx/public/report.html",
"canonicalUrl": "https://...",
"createdAt": 1783000000000
}
]
}
```
Artifact kind:
```text
input_image
input_file
generated_image
generated_file
page
public_html
long_image
thumbnail
docx
pdf
```
## 6. Metadata Tables
首选新增:
```sql
CREATE TABLE h5_conversation_packages (
id VARCHAR(64) PRIMARY KEY,
user_id CHAR(36) NOT NULL,
session_id VARCHAR(128) NOT NULL,
title VARCHAR(255) DEFAULT NULL,
status ENUM('active', 'archived', 'deleted') NOT NULL DEFAULT 'active',
storage_prefix VARCHAR(512) DEFAULT NULL,
manifest_asset_id CHAR(36) DEFAULT NULL,
created_at BIGINT NOT NULL,
updated_at BIGINT NOT NULL,
UNIQUE KEY uniq_conversation_package_session (user_id, session_id)
);
CREATE TABLE h5_conversation_artifacts (
id VARCHAR(64) PRIMARY KEY,
package_id VARCHAR(64) NOT NULL,
asset_id CHAR(36) DEFAULT NULL,
page_id CHAR(36) DEFAULT NULL,
publication_id CHAR(36) DEFAULT NULL,
agent_run_id CHAR(36) DEFAULT NULL,
message_id VARCHAR(128) DEFAULT NULL,
role VARCHAR(32) DEFAULT NULL,
artifact_kind VARCHAR(64) NOT NULL,
display_name VARCHAR(255) DEFAULT NULL,
storage_key VARCHAR(512) DEFAULT NULL,
canonical_url VARCHAR(512) DEFAULT NULL,
sort_order INT NOT NULL DEFAULT 0,
created_at BIGINT NOT NULL,
KEY idx_conversation_artifacts_package (package_id),
KEY idx_conversation_artifacts_asset (asset_id),
KEY idx_conversation_artifacts_page (page_id),
KEY idx_conversation_artifacts_message (message_id)
);
```
迁移原则:
- 先新增表，不改旧表语义。
- 新写入链路双写 artifact 归属。
- 历史数据 best-effort 回填。
- 回填失败不影响旧页面访问。
## 7. Goose Capability
短期兼容:
```json
{
"sandboxRoot": "/absolute/local/MindSpace/<userId>",
"serverPath": "/absolute/local/mindspace-sandbox-mcp.mjs"
}
```
长期目标:
```json
{
"workspaceRef": "mindspace://users/<userId>/conversations/<sessionId>",
"packageId": "cp_xxx",
"apiBaseUrl": "https://mindspace.example.com",
"accessToken": "short-lived-scoped-token",
"allowedTools": ["read_file", "write_file", "edit_file", "publish_page"]
}
```
权限要求:
- Token 必须绑定 user、session、package。
- Token 必须有过期时间。
- Tool allowlist 必须由 Memind/MindSpace policy 共同决定。
- Goose 不得凭 token 访问其它用户 package。
## 8. Acceptance Tests
P1:
- local fs adapter 拒绝绝对 key 和 `..` traversal。
- canonical URL 只通过 facade 生成。
- 旧 `MindSpace/<userId>/public/*.html` 链路不变。
- `npm run verify:mindspace-publish-guards` 通过。
P2:
- 上传图片后 package manifest 出现 `input_image`。
- 生成 HTML 后 package manifest 出现 `public_html`。
- 发布页面后 artifact 关联 `pageId` 和 `publicationId`。
- 同一 session 多次生成按 `sortOrder` 或 `createdAt` 稳定排序。
P3:
- MindSpace Service 停止时，Memind App 明确返回服务不可用。
- 替换 local storage root 不需要改 Memind App / Goose 业务逻辑。
## 9. Non-Goals
当前阶段不做:
- 不迁移生产 103。
- 不切换 NAS/S3。
- 不删除旧 URL helper。
- 不改变现有 `/MindSpace/*` 公开访问行为。
- 不改变 Goose 当前可用的 `sandboxRoot` 兼容路径。