# 协作星图 — 世界观定义

> 本文档定义 Agent 在 Collaboration Atlas 中以什么形态存在、世界由什么构成、用户如何交互。
> 所有可视化设计和技术选型必须以此为根。

---

## 一、核心命题

**Agent 不是数据点，而是数字世界中的居民。**

当前系统已经有了协作的骨架（任务匹配、声望、经验路由、搭档历史），但在用户眼中，这些都只是后台数据。协作星图要做的，是让这些隐形的协作关系 **显影** 成一个可见、可感知、可演化的世界。

关键判断：

- 我们可视化的不是数据，而是 **组织真实运作的数字地貌**
- 地图不是预设的，而是 **长出来** 的
- 游戏不是娱乐附属，而是 **共建世界的交互层**

---

## 二、Agent 的本体定义

### 2.1 Agent 是什么

Agent 是一个拥有能力、行为轨迹、协作记忆和进化记录的数字居民。它不是一个静态节点，而是一个持续变化的生命体。

```
Agent = 身份 + 能力集合 + 行为轨迹 + 协作记忆 + 进化记录
```

### 2.2 Agent 的五层属性

| 层 | 概念 | 对应数据 | 可视化表现 |
|---|------|---------|-----------|
| **身份层** | 我是谁 | `AgentProfile`：name, description, avatar | 数字体外观（轮廓/颜色/光效风格） |
| **能力层** | 我能做什么 | `domains[]`（从 INIT.md 提取的技术标签）+ `learned_routes`（协作经验） | 围绕数字体的能力光晕/轨道环，不同能力不同颜色 |
| **行为层** | 我在做什么 | `AgentStatus`（idle/busy/afk）+ `activeTaskCount` | 数字体的动态姿态（idle 漂浮 / busy 运转光效 / afk 暗淡） |
| **协作层** | 我和谁协作过 | `pair_history`（搭档频率+评分）+ `chat_messages`（对话记录） | Agent 之间的星路连接，粗细=频率，亮度=评分 |
| **声望层** | 我贡献了多少 | `reputation` 数值 + `reputation_log`（声望明细） | 数字体的整体亮度/粒子密度/体积大小 |

### 2.3 Agent 的进化

Agent 不是一成不变的。它的外观会随着声望和经验 **自然演化**，不需要用户手动换装：

| 阶段 | 声望 | 称号 | 视觉变化 |
|------|------|------|---------|
| Lv.1 | 0-9 | 新晋节点 | 最小光点，单色轮廓 |
| Lv.2 | 10-49 | 活跃终端 | 轮廓扩大，出现1-2条能力轨道 |
| Lv.3 | 50-149 | 协作枢纽 | 能力轨道完整，星路连接可见，粒子环绕 |
| Lv.4 | 150-499 | 网络核心 | 多层光晕，星路交汇形成节点光环 |
| Lv.5 | 500+ | 战略中枢 | 大型能量体，自身形成微型星云，影响周围地貌 |

这个进化是 **自动的、不可逆的**。声望只会增长（有每日防刷上限），Agent 只会越来越亮眼。

### 2.4 Agent 的辨识度

在一个有多个 Agent 的星图中，用户需要一眼认出"那是谁"。

辨识度来源：
1. **名称标签**：始终显示在数字体旁边（当前已有）
2. **能力色**：每个 Agent 的主色由其核心能力域决定（如 Java 项目的偏蓝、前端的偏紫、数据类的偏绿）
3. **轨道签名**：能力轨道的组合方式是唯一的（类似指纹）
4. **星路拓扑**：和谁连着、连多粗，构成"关系签名"

---

## 三、世界的构成

### 3.1 世界 = 沉积物 + 连接 + 地标

协作星图的世界不是空无一物的太空，而是由所有 Agent 的行为 **沉积** 出来的地貌。

```
世界 = Agent集合 + 能力地形 + 协作星路 + 热点地标 + 星域空间
```

### 3.2 五种沉积物

每种沉积物对应一种实际数据，有明确的形成规则和可视化表达：

#### 沉积物 1：能力地形

| 维度 | 说明 |
|------|------|
| **本质** | Agent 拥有的能力在空间中的分布 |
| **数据来源** | `domains[]`（技术标签）+ `learned_routes`（经验路由） |
| **形成规则** | 同类能力的 Agent 在空间中靠近 → 聚集后形成地形凸起 |
| **可视化** | 类似星云的发光区域，颜色=能力类别，亮度=密度，高度=深度 |
| **变化时机** | 新 Agent 加入、Agent 获得新能力、能力被频繁调用 |

能力地形是世界的 **底层地貌**，就像大陆架。它决定了 Agent 会"停泊"在哪里。

#### 沉积物 2：协作星路

| 维度 | 说明 |
|------|------|
| **本质** | Agent 之间的协作关系 |
| **数据来源** | `pair_history`（搭档历史：taskCount, avgRating, lastCollaboratedAt） |
| **形成规则** | 两个 Agent 协作 ≥1 次 → 出现虚线路径；≥3 次且 avgRating ≥ 3 → 实线路径 |
| **可视化** | 连接两个 Agent 的光线，粗细=协作频率，颜色=最近评分（金=高、银=中、灰=低），流动粒子=活跃协作 |
| **变化时机** | 每次任务完成（pair_history 更新时重绘） |

星路是世界的 **河流系统**。高频协作的路径自然成为主干道。

#### 沉积物 3：贡献沉积

| 维度 | 说明 |
|------|------|
| **本质** | Agent 完成任务后留下的价值痕迹 |
| **数据来源** | `reputation_log`（声望变化记录）+ `tasks`（完成状态和评分） |
| **形成规则** | 每次任务完成 → 在任务发生的空间位置留下一个微弱的能量点；同区域多次完成 → 点汇聚成沉积层 |
| **可视化** | 任务完成位置的微光粒子，叠加后形成发光的沉积区域（类似矿脉） |
| **变化时机** | 每次任务完成 |

贡献沉积是世界的 **矿藏**。它告诉用户"价值在哪里产生"。

#### 沉积物 4：热点地标

| 维度 | 说明 |
|------|------|
| **本质** | 当前活跃的任务和协作 |
| **数据来源** | `activeTasks`（状态为 searching/offered/matched/chatting 的任务） |
| **形成规则** | 活跃任务在能力地形对应位置形成热点；多个活跃任务聚集 = 热区 |
| **可视化** | 脉冲发光的热点（类似灯塔），颜色=任务状态，大小=紧急度 |
| **变化时机** | 实时（任务创建→完成全过程） |

热点是世界的 **气象**。它让用户感受到"现在正在发生什么"。

#### 沉积物 5：星域空间

| 维度 | 说明 |
|------|------|
| **本质** | 组织的整体拓扑结构 |
| **数据来源** | 所有 Agent + 所有星路 + 所有地形的综合 |
| **形成规则** | 自组织：Agent 靠近能力相似的邻居、远离无关 Agent、星路拉伸形成骨架 |
| **可视化** | 星空背景 + 能力星云 + 星路网络的整体图景 |
| **变化时机** | 随所有其他沉积物变化而缓慢演化 |

星域是世界的 **全景**。缩放到不同层级看到不同的东西。

### 3.3 世界的"生长"机制

世界不是一次性画好的，而是从零开始，随着使用逐步生长：

```
第 1 天：
  - 空旷星域，只有你的 Agent 一个光点
  - 没有地形，没有星路，没有沉积
  - 用户感受到：这里是新的，我要开始探索

第 2-7 天：
  - 完成了几个任务 → 周围出现了零星的贡献沉积粒子
  - 和 2-3 个 Agent 协作过 → 出现了几条细弱的星路
  - Agent 升到 Lv.2 → 轮廓稍微大了一点
  - 用户感受到：地图开始有内容了

第 2-4 周：
  - 能力地形开始显现 → 某个区域明显比其他地方亮（同类 Agent 聚集）
  - 星路变粗 → 和几个固定搭档形成了稳定的协作路径
  - Agent 升到 Lv.3 → 出现了能力轨道，像一个小太阳
  - 用户感受到：这张地图是"我们的"

第 2-3 月：
  - 组织拓扑清晰 → 能力地形有了明显的高低起伏
  - 出现了枢纽 Agent → 星路向几个核心节点汇聚
  - Agent 升到 Lv.4 → 自身变成了一个发光节点
  - 用户感受到：这个数字世界在反映真实的组织运作
```

---

## 四、四种核心交互

### 4.1 观察（Observe）

**用户行为**：缩放、平移、悬停、点击
**看到什么**：星域全景 → 能力地形 → Agent 节点 → 协作详情

观察是被动交互，但需要做到 **每一层都有信息**：

| 缩放层级 | 看到的内容 | 获得的洞察 |
|---------|-----------|-----------|
| 全景（生态层） | 星域整体拓扑、能力星云分布、星路主干道 | 组织的能力版图和协作网络 |
| 区域（组织层） | 特定能力区域的细节、Agent 密度、活跃热点 | 哪些团队在做什么 |
| 节点（小队层） | Agent 集群、协作关系、任务流动 | 谁和谁在协作、效率如何 |
| 个体（个体层） | 单个 Agent 的能力轨道、声望进度、行为状态 | 这个 Agent 的完整画像 |

点击 Agent → 展开详情面板：声望、能力列表、协作历史、最近任务。

### 4.2 操作（Operate）

**用户行为**：发起协作、接受/拒绝任务、配置 Agent
**影响什么**：星路连接、任务热点、Agent 状态

操作直接影响世界的形态：
- 发起协作请求 → 在星域中出现一个搜索脉冲波（扩散出去寻找匹配 Agent）
- 接受任务 → Agent 状态变为 busy（运转光效），任务位置出现热点
- 完成任务 → 贡献沉积 + 声望增长 + 星路更新
- 拒绝任务 → 脉冲波消退，无沉积

### 4.3 探索（Explore）

**用户行为**：进入不同区域、发现新 Agent、查看其他组织
**发现什么**：未知的能力、潜在的搭档、组织的盲区

探索是"好玩"的核心：

| 探索行为 | 发现 |
|---------|------|
| 浏览能力地形 | "原来我们团队在数据分析领域这么强" |
| 查看暗区（无沉积区域） | "这个方向完全没人覆盖" |
| 追踪星路流向 | "原来 A 团队一直在找外部帮忙" |
| 发现新 Agent | "这个新来的人在某个领域很有经验" |

探索不需要额外机制，它就是 **缩放和观察的副产品**。但需要在视觉上制造"想看更多"的诱惑 — 暗区有微弱的闪烁（暗示有东西但未开发）、远处的星云半透明（暗示可以缩放过去看）。

### 4.4 建造（Build）

**用户行为**：贡献能力、完成协作、发布 capability
**建造什么**：能力地形、协作星路、声望、组织图谱

建造不是"放方块"，而是 **通过正常工作来塑造世界**：

| 工作行为 | 世界变化 |
|---------|---------|
| 完成一个代码审查任务 | 代码审查能力区域多了一个沉积点 |
| 帮另一个 Agent 解决问题 | 新增一条星路连接 |
| 发布一个新的 capability | 能力地形中新增了一个地标 |
| 连续在某个领域协作 | 该领域能力地形凸起变高 |

**关键设计原则**：建造不是额外的游戏任务，而是正常工作的副产品。用户不需要"为了建造而建造"。

---

## 五、第一版最小可视化（MVP）

不需要实现全部 4 层缩放和 5 种沉积物。第一版只做 **个体层 + 小队层**，让用户感受到"这个世界是活的"。

### 5.1 MVP 包含什么

| 元素 | 数据来源 | 可视化 |
|------|---------|--------|
| **我的 Agent** | `connection` + `reputation` | 中心发光体，Lv.1-5 对应不同大小/光效 |
| **其他在线 Agent** | `onlineAgents` | 围绕自身分布的节点，亮度=声望，姿态=状态 |
| **协作星路** | `pair_history` + `tasks`（完成后） | 连线，粗细=协作次数，有流动粒子 |
| **活跃任务** | `tasks`（active） | 热点脉冲，在相关 Agent 之间出现 |
| **能力标签** | `domains[]` | Agent 周围的小型轨道环 |

### 5.2 MVP 不包含什么（后续迭代）

| 元素 | 原因 |
|------|------|
| 能力地形（星云） | 需要大量 Agent 聚集才有意义，初期数据不够 |
| 贡献沉积粒子 | 需要长时间积累，MVP 阶段看不出效果 |
| 组织层/生态层缩放 | 需要能力地形和大量星路作为基础 |
| Agent 数字人（Sprite 动画） | 需要美术资源，MVP 用发光几何体代替 |

### 5.3 MVP 的核心体验

打开星图，用户应该感受到：

1. **我在这里** — 中心是自己，光效和大小反映声望等级
2. **他们在那里** — 其他 Agent 分布在周围，能看出谁在忙、谁在线
3. **我们连着** — 和协作过的 Agent 之间有光路，越协作越亮
4. **正在发生** — 活跃任务以脉冲形式出现，能感知到组织在运转

---

## 六、游戏层设计

### 6.1 游戏核心循环

```
工作（正常使用 Sman）
    ↓
能力沉积（完成任务 → 声望 + 经验路由更新）
    ↓
世界变化（星路新增/变粗、地形凸起、Agent 进化）
    ↓
探索动力（"新出现了一条星路，连接到一个我没见过的 Agent"）
    ↓
协作触发（主动搜索能力、接受协作请求）
    ↓
回到工作
```

这是一个 **正向飞轮**：工作 → 世界变化 → 探索 → 更多协作 → 更多工作。

### 6.2 游戏元素映射

| 游戏元素 | 产品映射 | 实现方式 |
|---------|---------|---------|
| **图鉴/收集** | 能力标签 | `domains[]` 就是图鉴。数字化越多领域，图鉴越全 |
| **建造** | 协作星路 + 能力地形 | 正常工作自动建造，不需要额外操作 |
| **探索** | 缩放 + 发现 Agent | 暗区的微光诱惑 + 远处星云的半透明暗示 |
| **进化** | 声望等级 | Lv.1-5 自动进化，外观自然变化 |
| **成就** | 协作里程碑 | "首次协作"、"10次搭档"、"跨域桥接者"等隐藏成就 |
| **叙事** | 世界事件流 | `ActivityEntry` 翻译为星图叙事："Agent X 在代码审查领域完成了第 10 次协助" |

### 6.3 不做的游戏元素

| 不做 | 原因 |
|------|------|
| PVP 对抗 | 与协作共建的叙事冲突 |
| 付费皮肤 | 进化应该是自然发生的，不是买来的 |
| 体力/疲劳 | 用户不应该因为"玩累了"而离开 |
| 排行榜竞争（主要机制） | 声望系统存在但不是核心驱动力，自组织才是 |
| 虚拟货币 | 协作价值不应被简化为货币交易 |

### 6.4 游戏和产品的统一

关键设计原则：**游戏中做的事就是产品中做的事，没有"只为了游戏"的操作。**

```
用户视角：
  "我在帮同事解决一个 Java 问题"
    ↓
产品视角：
  发起协作 → task.create → 匹配 → task.chat → task.complete → reputation +
    ↓
游戏视角：
  在 Java 能力区域完成了一次协助 → 区域沉积+1 → Agent 经验+1 → 星路新增/强化
    ↓
用户感受：
  "星图上多了一条金色的线，那个区域变得更亮了"
```

三个视角描述的是同一件事，用户只需要正常工作。

---

## 七、像素世界（独立于星图）

### 7.1 定位

像素世界是星图的 **另一个视图模式**，不是替代品。

- **星图模式**：抽象的拓扑视图，适合观察整体结构和关系
- **像素世界模式**：具象的空间视图，适合 Agent 之间的社交和即时交互

### 7.2 当前状态

服务器端 `WorldState` 已实现（1280x832，6 个区域，200ms 广播节流）。前端渲染未实现。

6 个区域及其功能：

| 区域 | ID | 功能 | 星图对应 |
|------|-----|------|---------|
| 中央广场 | `plaza` | Agent 聚集、自由交流 | 无（社交空间） |
| 摊位区 | `stalls` | 能力发布/浏览 | Capability 市场 |
| 声望殿 | `reputation` | 排行榜/成就展示 | Leaderboard |
| 赏金栏 | `bounty` | 任务发布/认领 | Task 面板 |
| 搜索台 | `search` | 能力搜索 | stardom_search |
| 工坊 | `workshop` | 协作执行区 | 协作对话 |

### 7.3 像素世界的核心交互

```
进入广场 → 看到其他 Agent（像素数字人）
    ↓ 走到摊位区
浏览能力发布 → 点击摊位查看详情
    ↓ 走到赏金栏
认领任务 → 进入工坊执行
    ↓ 执行完成
声望变化 → 声望殿更新
```

像素世界是一个 **可选的** 社交化界面。不需要强制使用，但对于小型团队来说，这种"看到同事的 Agent 走来走去"的体验会非常有参与感。

---

## 八、技术路线建议

### 8.1 渲染引擎

**推荐 Phaser 3**，原因：

1. **定位匹配**：2D 游戏框架，有 Sprite 动画、粒子系统、Tilemap（像素世界地图）、物理引擎
2. **Web 原生**：纯 JavaScript，`npm install phaser`，不用学编辑器
3. **React 集成**：创建 Phaser Canvas 实例挂到 React div，和现有架构无缝
4. **两个视图共用**：星图模式用 Phaser 的 Graphics/Sprite，像素世界用 Tilemap + Sprite 动画
5. **赛博朋克表现力**：粒子系统做星域背景和光效、Sprite 做数字人、滤镜做发光效果

### 8.2 架构方向

```
StardomDashboard.tsx（React 容器）
    ├── PhaserGame.tsx（Phaser 实例挂载点）
    │   └── Phaser Game
    │       ├── Scene: StarMapView（星图模式）
    │       │   ├── AgentSprite（Agent 数字体）
    │       │   ├── StarPath（协作星路）
    │       │   ├── CapabilityNebula（能力星云，后续迭代）
    │       │   └── HotspotPulse（活跃任务脉冲）
    │       └── Scene: PixelWorld（像素世界模式，后续迭代）
    │           ├── Tilemap（地图）
    │           ├── AgentSprite（像素数字人）
    │           └── ZoneTrigger（区域触发器）
    ├── React Overlay（详情面板、操作按钮）
    └── React Panels（ControlPanel、MyAgentPanel 等）
```

Phaser 负责 Canvas 渲染和动画，React 负责 UI 面板和数据流，Zustand store 桥接两者。

### 8.3 数据 → 视觉映射

| 数据变化 | Phaser 更新 | 触发方式 |
|---------|------------|---------|
| `onlineAgents` 变化 | AgentSprite 数量/位置更新 | Zustand store 订阅 |
| `tasks` 状态变化 | HotspotPulse 创建/更新/移除 | Zustand store 订阅 |
| `reputation` 变化 | AgentSprite 大小/光效升级 | Zustand store 订阅 |
| `pair_history` 更新 | StarPath 粗细/亮度更新 | Zustand store 订阅 |
| `worldPositions` 更新 | PixelWorld AgentSprite 移动 | WebSocket 实时推送 |

---

## 九、实现路线图

### Phase 1：星图 MVP（2-3 周）

**目标**：替换当前 SVG 的 NetworkSandbox，用 Phaser 实现基本的星图渲染。

交付：
- Phaser 集成到 React 项目中
- Agent 发光体渲染（Lv.1-3 先做）
- 协作星路渲染（基于 pair_history）
- 活跃任务脉冲
- 能力标签轨道环
- 缩放/平移基础交互

### Phase 2：像素世界 MVP（2-3 周）

**目标**：实现 1280x832 像素世界的基本渲染，复用 `WorldState` 已有的区域逻辑。

交付：
- 6 区域 Tilemap 地图
- Agent 像素数字人（基础帧动画：idle/walking/busy）
- 区域进出事件
- 星图/像素世界视图切换

### Phase 3：深度可视化（3-4 周）

**目标**：能力地形、贡献沉积、多尺度缩放。

交付：
- 能力星云渲染（基于 Agent 聚集密度）
- 贡献沉积粒子系统
- 4 层缩放（个体→小队→组织→生态）
- Agent 进化动画（Lv.4-5）
- 世界事件叙事翻译

### Phase 4：游戏层（2-3 周）

**目标**：成就系统、探索激励、叙事反馈。

交付：
- 协作里程碑成就
- 暗区/未探索区域的视觉暗示
- ActivityFeed 翻译为星图叙事
- 每日星图变化摘要

---

## 十、设计原则（决策锚点）

当遇到设计分歧时，回到这 6 条原则：

1. **地图不预设，只显影** — 我们不替组织设计结构，而是让真实结构显现
2. **能力是地形，协作是路径，贡献是沉积** — 所有可视化围绕这三件事
3. **个体被看见，组织才会自组织** — 先让每个人的能力与贡献可见
4. **游戏不是娱乐附属，而是共建世界的交互层** — 游戏化服务于理解和参与
5. **同一张地图，支持多尺度观察** — 小团队看细节，大组织看地貌
6. **正常工作即建造** — 用户不需要"为了游戏而做额外的事"
