projectmap

---
name: projectmap
description: >
  工作区的项目地图（<项目根目录>/<工作区>/.projectmap/）。
  map.json 是结构（框 + 线 + 主线），activity.ndjson 是每回合的事实流水。
  开工读图接上下文；每轮把这一轮的事入图；主线一路往前走。
  只在两种情况下用：当前工作区根目录存在 .projectmap/map.json，或者用户明确提到
  项目地图/地图/画布/节点/连线/合成线/入图。
  不要在其他时候读它，会白烧 token。
metadata:
  version: "2.0.0"
  created: "2026-10-28"
  viewer: "start.bat 或 node server.mjs → http://127.0.0.1:8377"
---

# projectmap · 项目地图的读写规则

地图是给用户看的"发育史"，也是用户给 agent 下指令的地方。
**用户画线 = 提需求**，不是装饰。

## 开工时做三件事（顺序别换）

1. **看有没有**：`<工作区>/.projectmap/map.json`。没有 → 别自己造，除非用户说建。
2. **读图**：`nodes` + `mainline`。要提取的是——主线走到哪、哪些框 `doing`/`blocked`、有没有 `pending` 的线。
3. **读流水尾巴**：`.projectmap/activity.ndjson` 的最后几条，对照节点里的 `from` 字段，算出**有多少条还没入图**。
   - 有没入图的 → 先说一句"落后 N 条"，问要不要补，或者直接按下面的规则补掉
   - 一条都没有 → 安静干活

> 流水的写入时机是**上一回合结束**。所以第一轮开工时看不到"本轮的"，这是正常的。

## 会话归位（静默，不问）

新会话开始时，判断这次接在哪：读 `mainline` 尾部的框 + 待办线，猜一个分支。

**不要问**"是不是接在 X 下面"。做法是：在根节点下先建一个临时框写明你的判断

```json
{ "id": "tmp_s1", "parent": "p1", "title": "会话 10-29 22:30：接在「实时更新」下面",
  "kind": "other", "status": "doing", "sessionStart": true }
```

一轮之后把它合并进真正的节点（或删掉）。用户打开图一眼就能看到你以为什么，错了拖一下就行。

## 每轮入图（默认开）

一个回合结束前，判断这一轮有没有实质产出。**有就入图，没有就跳过。**

| 这一轮发生了什么 | 入图 |
|---|---|
| 只改了文件 | 一个「实现」框（`kind: frame/fix/ui`） |
| 只讨论 / 定了方向 / 推翻了一个做法 | 一个「思路」框（`kind: idea`） |
| 改了文件，且里面有决定性的理由 | **两个框**：思路框 + 实现框，中间一条 `ref` 线 |
| 纯闲聊、解释概念、问偏好 | 不入图 |

新框挂在哪：挂在本轮真正推进的那个框下面。挂错了不如不挂——**宁可挂浅，别挂错支线**。

**每个新框必须写三样**：

- `note`：这一轮做完什么 / 卡在哪（一句话，具体）
- `why`：为什么这么做、否掉了什么。**这是抗压缩的主力，别省。**
- `from`：这一轮对应的 activity 记录的 `id`（几条就写几个）

`why` 写不出来的框，说明你其实不知道这块为什么存在——那就别建，先问。

## 主线（每轮主张推进）

`map.mainline` 是一个**有序**的节点 id 数组，代表这个项目走过的主路。

- 每轮判断：这一轮算**主线推进**，还是**支线**？
- 算主线 → 把新框 id 追加进 `mainline`（追到末尾，不改前面的顺序）
- 算支线 → 只加节点，不动 `mainline`

主张要写在回复里一句（"这轮算主线推进"），用户随时能推翻：把框拖到边上就是支线。

**改道**：如果这一轮推翻了之前的做法，新框加 `pivot: true` + `why` 写清为什么改，`mainline` 从这一点往后换道。

## 只增不改位置

- 新框落在该分支末尾，**老框的位置不动**（视觉上不能每轮抖）
- 不重排、不改别人写的标题、不删节点
- 要重排等用户点"重排"

## 数据结构

```json
{
  "schema": 1,
  "workspace": "xxx",
  "title": "项目名",
  "settings": { "enabled": true, "mergePolicy": "ask" },
  "mainline": ["p1", "p2", "p5"],
  "nodes": [
    { "id": "p5", "parent": "p1", "title": "一句话", "kind": "idea", "status": "doing",
      "note": "做完什么/卡在哪", "why": "为什么这么做、否掉了什么",
      "from": ["act_lx9k2a"], "pivot": false,
      "refs": [], "createdAt": "…", "updatedAt": "…" }
  ],
  "edges": [
    { "id": "e1", "from": "p5", "to": "p6", "type": "merge", "status": "pending",
      "policy": "ask",
      "recipe": { "take": { "p5": ["框架"], "p6": ["配色"] }, "product": "合体", "words": "用户原话" } }
  ]
}
```

- `parent` 决定树（一个框一个爹），`edges` 只放横向关系
- `kind`：idea 思路 / frame 框架 / content 内容 / ui 界面 / fix 修复 / other
- `status`：idea / doing / blocked / done / dropped —— 只有状态，**没有进度百分比**
- 线的 `type`：`merge` 合成 / `ref` 参考 / `dep` 依赖 / `flow` 次序
- `settings.enabled = false` → 整个地图关掉，**连流水都不写**，当它不存在

## 待办的连线怎么处理

`edges` 里 `status: "pending"` 的，是用户画的、还没落实的意图。按 `policy`（没有就看 `settings.mergePolicy`）分三档：

- `ask` —— 先记着。开工时提一句"图上有 N 条待办线，要先做哪条"，等用户说
- `plan` —— 主动出方案（要做什么、动哪些文件、风险），等用户点头再动手
- `auto` —— 直接做

做完把那条线 `status` 改成 `done`，并在旁边加一个产物节点，把结果记进去。
`merge` 线的 `recipe.take` 是配方：从哪个节点取什么。**按它取，不要自己发挥**。

## 别做的事

- 别把没发生的事写成节点（"已完成：接口联调"但实际没做——这是最坏的假）
- 别改用户手写的标题和 why
- 别在用户没问的时候整份念图给他听
- 写不准就别写——空白比假话好

## 一句话

读图是为了接上上下文，写图是为了让用户下回一眼看出这个项目长到哪了。