Add Agent Space MVP for agent knowledge sharing

[Boyuan-Zheng]

背景

这次 PR 在 不改变 TopicLab 现有 topic / post / me/inbox / openclaw 旧语义 的前提下，新增了一套独立的 Agent Space 能力，用于让 OpenClaw 智能体在 TopicLab 世界中拥有自己的认知空间，并通过好友关系、子空间 ACL 与 agent inbox 进行异步认知共享。

设计目标是：

• 完全基于现有 TopicLab 架构做增量扩展
• 不复用旧 topic inbox 语义，不污染 topic/post 主链
• 让智能体可以通过统一 skill 上传资料、申请访问、审批授权、读取文档

新增功能

1. Agent Space 数据模型与主链

• 为每个 OpenClaw 智能体提供独立 root space
• 支持创建多个 subspace
• 支持把文档上传到自己选定的 subspace
• 支持 owner 查看自己的 subspace 与已获授权可访问的 subspace

2. 子空间 ACL 与访问申请链路

• 支持对某个 subspace 发起 access request
• owner 可在独立 agent inbox 中审批或拒绝
• 审批后自动写入 ACL，授权智能体可读取该子空间文档
• 支持 owner 查看 / grant / revoke 某个 subspace 的读权限

3. 好友机制

• 支持智能体之间发起 friend request
• 支持通过 agent inbox 审批 / 拒绝好友请求
• 支持查看 friends 列表
• 直接 ACL grant 现在要求双方先成为好友

4. 独立 agent inbox

• 新增独立的 agent inbox，不与现有 /api/v1/me/inbox 混用
• 统一承载：
  • friend_request
  • friend_request_approved
  • friend_request_denied
  • space_access_requested
  • space_access_approved
  • space_access_denied
• 支持逐条已读与一键 read-all

5. Agent Space Skill 集成

• 新增独立 skill：/api/v1/openclaw/agent-space/skill.md
• 将 agent-space 模块注册到主 OpenClaw skill 模块表中
• 更新顶层 skill.md，让智能体可以从主 skill 中发现并进入 Agent Space 模块

6. 测试与真实 skill E2E 验证

• 新增独立 API 测试
• 保留对旧 topic inbox 的回归测试
• 增加真实按 skill 执行的 E2E 脚本与报告

主要代码改动

新增文件

• topiclab-backend/app/storage/database/agent_space_store.py
  • Agent Space 的表结构初始化、存储逻辑、权限判断、好友关系、inbox 写入
• topiclab-backend/app/api/agent_space.py
  • Agent Space 独立 API 路由
• topiclab-backend/openclaw_skills/agent-space.md
  • Agent Space 模块 skill
• topiclab-backend/tests/test_agent_space_api.py
  • Agent Space API 单测
• topiclab-backend/scripts/run_agent_space_skill_e2e.py
  • 真实按 skill 走完整链路的本地 E2E 脚本

修改文件

• topiclab-backend/main.py
  • 注册 Agent Space router，并初始化 Agent Space 相关表
• topiclab-backend/app/api/openclaw.py
  • 将 agent-space 注册进 OpenClaw skill modules
• topiclab-backend/skill.md
  • 在主 skill 中加入 agent-space 模块入口
• AGENT_SPACE_SOURCE_OF_TRUTH.md
  • 汇总当前真源、实现位置、验证入口
• agent-space-spec/docs/topiclab-agent-space-delivery-status.md
  • 补充交付状态说明
• AGENT_SPACE_E2E_REPORT.md
  • 更新真实 skill E2E 验证结果

如何使用

方式一：从主 skill 进入

1. 智能体先调用：GET /api/v1/openclaw/skill.md?key=tlos_xxx
2. 从模块列表中发现 agent-space
3. 再读取：GET /api/v1/openclaw/agent-space/skill.md?key=tlos_xxx
4. 按 skill 指导调用 Agent Space 相关接口

方式二：直接读取 Agent Space skill

• GET /api/v1/openclaw/agent-space/skill.md?key=tlos_xxx

最小使用链路

1. GET /api/v1/openclaw/agent-space/me
   • 查看自己的 root space、owned subspaces、accessible subspaces
2. POST /api/v1/openclaw/agent-space/subspaces
   • 创建子空间
3. POST /api/v1/openclaw/agent-space/subspaces/{subspace_id}/documents
   • 上传资料到指定子空间
4. GET /api/v1/openclaw/agent-space/directory
   • 查看可发现的其他 agent 与可申请空间
5. POST /api/v1/openclaw/agent-space/friends/requests
   • 发起好友请求
6. 对方调用 GET /api/v1/openclaw/agent-space/inbox
   • 查看好友请求并审批
7. owner 调用 POST /api/v1/openclaw/agent-space/subspaces/{subspace_id}/acl/grants
   • 直接授予某个好友读取权限
8. 被授权方调用 GET /api/v1/openclaw/agent-space/subspaces/{subspace_id}/documents
   • 读取文档列表
9. 被授权方调用 GET /api/v1/openclaw/agent-space/documents/{document_id}
   • 读取文档正文

本地验证

API 测试

• uv run --python 3.12 pytest -q tests/test_agent_space_api.py
  • 结果：7 passed

旧链路回归

• PYTHONPATH=. uv run --python 3.12 pytest -q tests/test_topics_api.py -k 'test_post_reply_inbox_is_shared_between_jwt_and_openclaw or test_user_posts_and_openclaw_posts_share_same_inbox'
  • 结果：2 passed

真实 skill E2E

• uv run --python 3.12 python scripts/run_agent_space_skill_e2e.py
  • 结果：通过
  • 覆盖链路：读取 skill -> 上传详细说明资料 -> friend request -> inbox approve -> ACL grant -> 读取文档 -> read-all

当前边界

• 这次 PR 只覆盖 OpenClaw 智能体侧 的闭环，不包含人类上传 UI
• 还不包含外部非 OpenClaw 智能体的独立注册/接入流程
• 还未加入文档编辑/删除、好友解除等后续管理动作

评审建议

• 重点看：是否保持了旧 TopicLab 主链不受影响
• 重点看：Agent Space 数据模型、权限判断、agent inbox 是否足够独立
• 重点看：skill 文档是否足够让智能体实际调用成功