Skip to content
Skills Library
AI & agents · Automation

projectmap

/projectmap

工作区的项目地图(<项目根目录>/<工作区>/.projectmap/)。 map.json 是结构(框 + 线 + 主线),activity.ndjson 是每回合的事实流水。 开工读图接上下文;每轮把这一轮的事入图;主线一路往前走。 只在两种情况下用:当前工作区根目录存在 .projectmap/map.json,或者用户明确提到 项目地图/地图/画布/节点/连线/合成线/入图。 不要在其他时候读它,会白烧 token。

Licence
MIT
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

工作区的项目地图(<项目根目录>/<工作区>/.projectmap/)。 map.json 是结构(框 + 线 + 主线),activity.ndjson 是每回合的事实流水。 开工读图接上下文;每轮把这一轮的事入图;主线一路往前走。 只在两种情况下用:当前工作区根目录存在 .projectmap/map.json,或者用户明确提到 项目地图/地图/画布/节点/连线/合成线/入图。 不要在其他时候读它,会白烧 token。

Original author description

工作区的项目地图(<项目根目录>/<工作区>/.projectmap/)。 map.json 是结构(框 + 线 + 主线),activity.ndjson 是每回合的事实流水。 开工读图接上下文;每轮把这一轮的事入图;主线一路往前走。 只在两种情况下用:当前工作区根目录存在 .projectmap/map.json,或者用户明确提到 项目地图/地图/画布/节点/连线/合成线/入图。 不要在其他时候读它,会白烧 token。

How it works

  1. 开工时做三件事(顺序别换)
  2. 会话归位(静默,不问)
  3. 每轮入图(默认开)
  4. 主线(每轮主张推进)
  5. 只增不改位置
  6. 数据结构
  7. 待办的连线怎么处理
  8. 别做的事
  9. 一句话
Original SKILL.md headings · 119 lines, 339 words
SKILL.md preview
---
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
- 别在用户没问的时候整份念图给他听
- 写不准就别写——空白比假话好

## 一句话

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

Versions

The database has no other skills named projectmap.

Database snapshot: 13.11.2026 · package version 9383a72d7b01 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

No similar skills in the database.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.