magic-agent 2.4.3 → 2.6.3

package/internal/requirements/relations_test.go

@@ -0,0 +1,231 @@
+package requirements
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/session"
+)
+
+// TestAppendAndCompactRelations 追加重复行 → compact 后去重、字段取最新、顺序稳定。
+func TestAppendAndCompactRelations(t *testing.T) {
+	root := testEnv(t)
+	id := DirID(filepath.Join(root, "proj-rel"))
+
+	base := Relation{Session: "s-1", STitle: "会话一", Module: "任务列表", Feature: "加待办", N: 3}
+	r1 := base
+	r1.Ts = 100
+	r2 := base
+	r2.Ts = 200 // 同键重复：compact 应保 Ts=200 这条
+	r3 := Relation{Session: "s-1", STitle: "会话一", Module: "任务列表", Feature: "加待办", N: 5, Ts: 300}
+	r4 := Relation{Session: "s-2", Module: "任务列表", Feature: "加待办", N: 3, Ts: 400}
+	if err := appendRelations(id, []Relation{r1, r3, r4}); err != nil {
+		t.Fatal(err)
+	}
+	if err := appendRelations(id, []Relation{r2}); err != nil {
+		t.Fatal(err)
+	}
+	if rels := readRelations(id); len(rels) != 4 {
+		t.Fatalf("追加期不去重，应 4 行，实际 %d", len(rels))
+	}
+	if err := compactRelations(id); err != nil {
+		t.Fatal(err)
+	}
+	rels := readRelations(id)
+	if len(rels) != 3 {
+		t.Fatalf("去重后应 3 行，实际 %d: %+v", len(rels), rels)
+	}
+	if rels[0].Ts != 200 {
+		t.Errorf("同键重复应保最新，实际 Ts=%d", rels[0].Ts)
+	}
+	if rels[2].STitle != "" {
+		t.Errorf("快照缺失就该缺着，不伪造: %+v", rels[2])
+	}
+	// compact 幂等
+	if err := compactRelations(id); err != nil {
+		t.Fatal(err)
+	}
+	if rels2 := readRelations(id); len(rels2) != 3 {
+		t.Errorf("二次 compact 不应变化，实际 %d", len(rels2))
+	}
+}
+
+// TestConsolidateWritesRelations 归纳落账关系：module 用**改写后**的归属；
+// 模块合并后 relations 里的 from 一并改写成 to。
+func TestConsolidateWritesRelations(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-rel-cons")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeSessionLog(t, session.Dir(), "s-rel", proj, "引擎切换加上", "调用时带上超时")
+	id := DirID(proj)
+	if err := writeState(id, state{BootstrapAt: time.Now().UnixMilli(), Sessions: map[string]memCursor{}}); err != nil {
+		t.Fatal(err)
+	}
+
+	old := newCaller
+	defer func() { newCaller = old }()
+	round := 0
+	newCaller = func(ctx context.Context, engineName, model string, timeout time.Duration) (llmCall, error) {
+		return func(prompt string, schema *agent.JSONSchema) (string, error) {
+			switch {
+			case strings.Contains(prompt, "== 归纳规则 =="):
+				round++
+				if round == 1 {
+					return `{"features":[{"module":"引擎管理","name":"引擎切换","desc":"用户切换默认引擎","points":["可切换默认引擎"],"sources":[1,2]}]}`, nil
+				}
+				return `{"features":[{"module":"引擎调用","name":"调用超时","desc":"用户设置调用超时","points":["可设置调用超时"],"sources":[3]}]}`, nil
+			case strings.Contains(prompt, "本轮新增模块"):
+				return `{"pairs":[]}`, nil
+			default:
+				return `{"pairs":[{"from":"引擎调用","to":"引擎管理"}]}`, nil
+			}
+		}, nil
+	}
+
+	if _, err := Consolidate(context.Background(), proj, Options{}); err != nil {
+		t.Fatal(err)
+	}
+	rels := readRelations(id)
+	if len(rels) != 2 {
+		t.Fatalf("第一轮应落 2 条关系（#1#2 → 引擎切换），实际 %+v", rels)
+	}
+	for _, r := range rels {
+		if r.Session != "s-rel" {
+			t.Errorf("session 应取记忆条目，实际 %q", r.Session)
+		}
+		if r.STitle == "" {
+			t.Errorf("STitle 应有会话标题快照: %+v", r)
+		}
+		if r.Feature == "引擎切换" && r.Module != "引擎管理" {
+			t.Errorf("module 用改写后的归属，实际 %q", r.Module)
+		}
+	}
+
+	// 追加一条记忆触发第二轮 + 模块合并 → relations 的 module 应已改写。
+	ev, err := os.OpenFile(filepath.Join(session.Dir(), "s-rel.jsonl"), os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	line := `{"seq":100,"kind":"user","text":"调用默认引擎带上超时","at":"2026-10-25T10:00:00Z","session_id":"s-rel"}` + "\n"
+	if _, err := ev.WriteString(line); err != nil {
+		t.Fatal(err)
+	}
+	if err := ev.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Consolidate(context.Background(), proj, Options{}); err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, r := range readRelations(id) {
+		if r.Feature == "调用超时" && r.N == 3 {
+			found = true
+		}
+		if r.Module == "引擎调用" {
+			t.Errorf("模块合并后 relations 里的 from 应已改写: %+v", r)
+		}
+	}
+	if !found {
+		t.Errorf("第二轮应补上 #3 → 调用超时的关系: %+v", readRelations(id))
+	}
+}
+
+// TestRewriteRelationsModule 直接改写：from → to。
+func TestRewriteRelationsModule(t *testing.T) {
+	root := testEnv(t)
+	id := DirID(filepath.Join(root, "proj-rel-rw"))
+	writeFeatureDoc(t, id, "内容创作", "写文案", "生成文案")
+	if err := appendRelations(id, []Relation{
+		{Session: "s-1", Module: "内容创作", Feature: "写文案", N: 1, Ts: 1},
+		{Session: "s-1", Module: "团队协作", Feature: "分工", N: 2, Ts: 2},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := rewriteRelationsModule(id, "内容创作", "创作"); err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]string{}
+	for _, r := range readRelations(id) {
+		got[r.Feature] = r.Module
+	}
+	if got["写文案"] != "创作" || got["分工"] != "团队协作" {
+		t.Fatalf("改写不正确: %v", got)
+	}
+}
+
+// TestBuildGraph 多会话 × 多功能点多对多 → 节点/边正确；文档不存在的关系丢弃。
+func TestBuildGraph(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-graph")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	id := DirID(proj)
+	writeFeatureDoc(t, id, "任务列表", "加待办", "新增待办")
+	writeFeatureDoc(t, id, "任务列表", "删待办", "删除待办")
+	if err := appendRelations(id, []Relation{
+		{Session: "s-a", STitle: "会话A", Module: "任务列表", Feature: "加待办", N: 1, Ts: 1},
+		{Session: "s-a", STitle: "会话A", Module: "任务列表", Feature: "删待办", N: 2, Ts: 2},
+		{Session: "s-b", Module: "任务列表", Feature: "加待办", N: 3, Ts: 3},
+		// 悬空关系：文档已不在 → 节点与边都应丢弃
+		{Session: "s-a", STitle: "会话A", Module: "旧模块", Feature: "旧功能", N: 4, Ts: 4},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	b, err := BuildGraph(proj)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out struct {
+		OK         bool `json:"ok"`
+		Workspaces []struct {
+			ID    string      `json:"id"`
+			Nodes []graphNode `json:"nodes"`
+			Edges []graphEdge `json:"edges"`
+		} `json:"workspaces"`
+	}
+	if err := json.Unmarshal(b, &out); err != nil {
+		t.Fatal(err)
+	}
+	if !out.OK || len(out.Workspaces) != 1 {
+		t.Fatalf("应输出 1 个工作区: %+v", out)
+	}
+	g := out.Workspaces[0]
+	if g.ID != id {
+		t.Errorf("工作区 id 应是 %s，实际 %s", id, g.ID)
+	}
+	var feats, sess int
+	for _, n := range g.Nodes {
+		if n.Type == "feature" {
+			feats++
+		} else {
+			sess++
+			if n.ID == "s:s-a" && n.Title != "会话A" {
+				t.Errorf("会话标题应取快照，实际 %q", n.Title)
+			}
+		}
+	}
+	if feats != 2 || sess != 2 {
+		t.Errorf("应 2 个功能点 + 2 个会话节点，实际 feature=%d session=%d: %+v", feats, sess, g.Nodes)
+	}
+	if len(g.Edges) != 3 {
+		t.Fatalf("3 条有效边（悬空关系丢弃），实际 %+v", g.Edges)
+	}
+	// 多对多：s-a 关联两个功能点、加待办有两个会话
+	targets := map[string]int{}
+	for _, e := range g.Edges {
+		targets[e.Source]++
+	}
+	if targets["s:s-a"] != 2 {
+		t.Errorf("s-a 应有 2 条边，实际 %v", targets)
+	}
+}

package/internal/requirements/requirements.go

@@ -86,6 +86,12 @@ type Feature struct {
 	HasFinal bool `json:"has_final"`
 	// FinalPreview 最终版的第一句实质内容（卡片头条）。
 	FinalPreview string `json:"final_preview,omitempty"`
+	// PageURL 该功能点对应的页面地址（归纳时从对话里提取；可空）。
+	PageURL string `json:"page_url,omitempty"`
+	// Shots 页面完成情况截图数。
+	Shots int `json:"shots"`
+	// ShotAt 最后一张截图的时刻（unix 毫秒，0 = 还没截）。
+	ShotAt int64 `json:"shot_at,omitempty"`
 }
 
 // Module 一个模块（两级结构的一级）及其下的功能点。
@@ -171,6 +177,10 @@ type Result struct {
 	Replayed int `json:"replayed,omitempty"`
 	// Calls 本轮实际调了几次 LLM（分片）。
 	Calls int `json:"calls"`
+	// Merged 本轮合并掉的相似模块个数（模块去重，见 modules.go）。
+	Merged int `json:"merged,omitempty"`
+	// MergedModules 合并清单（「被合并模块 → 并入模块」，内容不丢、只并目录）。
+	MergedModules []string `json:"merged_modules,omitempty"`
 	// Pending 归纳完还剩多少条未归纳。
 	Pending int `json:"pending"`
 	// Error 失败原因（OK=false 时有值）。

package/internal/requirements/shots.go

@@ -0,0 +1,418 @@
+package requirements
+
+// shots.go - 「页面完成情况」截图的落盘与文档追加。
+//
+// 需求（2026-10-25 用户）：「需求文档整理时 如果设计页面改造 调用内置浏览器mcp
+// 对完成情况截图标注并放在文档中」。于是每个功能点的文档多出第七段
+// 「页面完成情况」：页面地址 + 若干张带说明的截图。
+//
+// ── 为什么截图落盘在 core 而不在客户端 ──
+//   文档是 core 的资产（~/.magic-agent/requirements/<wsid>/features/…），客户端只
+//   负责发起与回显。截图写进文档必须与归纳写文档走同一套锁与原子写，否则两边
+//   同时写会把对方的段落冲掉。
+//
+// ── 为什么追加截图用**文本级插入**而不是全量重渲染 ──
+//   ParseDoc → RenderDoc 的往返会丢东西：未知 ## 段、段内空行、Final 里的缩进、
+//   用户手改过的措辞。归纳每轮都会重写文档（这是既有的既定行为），但**追加截图**
+//   是「往用户手边的文档里加两行」的动作 —— 它不该顺手抹掉用户两次归纳之间
+//   手写的内容。所以这里只做「定位段落 → 追加两行 → 其余字节原样写回」。
+//   代价：文档里若有奇怪的段落顺序，插入点可能不理想 —— 那比丢内容好。
+//
+// ── 存储形状 ──
+//   <root>/<wsid>/shots/<模块>/<功能点slug>/<unix毫秒>.png
+//   模块名为空（未归类）时用 unfiled；功能点用 SlugifyFeature 归一。
+//   路径在文档里**一律正斜杠**（Windows 上反斜杠会让 markdown 的 `\` 变成转义）。
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	// MaxShotBytes 单张截图的大小上限（PNG）。
+	//
+	// 8MB 对应约 2000×2000 的 PNG —— 手机全屏截图（含标注）远小于此。
+	MaxShotBytes = 8 << 20
+	// MaxShots 一个功能点最多保留的截图数（超出的丢最旧的）。
+	MaxShots = 12
+	// shotsDirName 截图目录名（相对 <wsid>）。
+	shotsDirName = "shots"
+	// unfiledModule 未归类模块的目录名（模块名为空时用它）。
+	unfiledModule = "unfiled"
+)
+
+// pngMagic PNG 文件头（8 字节签名）。
+var pngMagic = []byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A}
+
+// ShotResult 追加一张截图的结果（CLI 输出 / HTTP 响应共用）。
+type ShotResult struct {
+	OK bool `json:"ok"`
+	// Workspace / Dir 归属的工作区。
+	Workspace string `json:"workspace,omitempty"`
+	Dir       string `json:"dir"`
+	// Module / Name 落在哪个功能点上。
+	Module string `json:"module,omitempty"`
+	Name   string `json:"name,omitempty"`
+	// File 文档路径（绝对路径）。
+	File string `json:"file,omitempty"`
+	// Path 截图落盘后的绝对路径（正斜杠）。
+	Path string `json:"path,omitempty"`
+	// Shots 这个功能点现有截图数。
+	Shots int `json:"shots"`
+	// Error 失败原因（OK=false 时有值）。
+	Error string `json:"error,omitempty"`
+}
+
+// AttachShot 给一个功能点追加一张「页面完成情况」截图。
+//
+// where 可以是工作区 id（ws-xxxx）或目录路径；module 为空表示不限模块（按名字找）。
+// name 是功能点名（= 文档名）。caption 是标注说明（可空）。
+//
+// 找不到对应文档时**报错**而不是新建 —— 截图是给已有需求点补证据，
+// 凭空造一篇「同名空文档」只会污染清单。
+func AttachShot(where, module, name, caption string, png []byte) (ShotResult, error) {
+	res := ShotResult{}
+	dir := strings.TrimSpace(where)
+	if dir == "" {
+		if cwd, err := os.Getwd(); err == nil {
+			dir = cwd
+		}
+	}
+	ws, ok := resolveWorkspace(dir)
+	if !ok {
+		res.Error = "工作区不存在: " + dir
+		return res, fmt.Errorf("requirements: workspace not found: %s", dir)
+	}
+	if Root() == "" {
+		res.Error = "无法确定需求存储目录"
+		return res, fmt.Errorf("requirements: no storage root")
+	}
+	res.Workspace, res.Dir = ws.ID, ws.Dir
+
+	name = strings.TrimSpace(truncRunes(strings.TrimSpace(name), TitleMaxChars))
+	if name == "" {
+		res.Error = "功能点名不能为空"
+		return res, fmt.Errorf("requirements: empty feature name")
+	}
+	if len(png) == 0 {
+		res.Error = "截图内容为空"
+		return res, fmt.Errorf("requirements: empty png")
+	}
+	if len(png) > MaxShotBytes {
+		res.Error = fmt.Sprintf("截图过大（%d 字节，上限 %d）", len(png), MaxShotBytes)
+		return res, fmt.Errorf("requirements: png too large")
+	}
+	if !bytes.HasPrefix(png, pngMagic) {
+		res.Error = "不是 PNG 图片"
+		return res, fmt.Errorf("requirements: not a png")
+	}
+
+	// 与归纳共用一把锁：两个进程同时写同一篇文档会把对方的段落冲掉。
+	release, busy := acquireLock(ws.ID)
+	if busy {
+		res.Error = "另一个进程正在整理这个空间，稍后再试"
+		return res, errBusy
+	}
+	defer release()
+
+	// 定位文档：经既有文件列表匹配，**不把用户输入拼进路径**（防目录穿越）。
+	merger := newDocMerger(ws.ID)
+	hit, found := merger.match(name)
+	if !found {
+		res.Error = "找不到这个功能点的文档：" + name
+		return res, fmt.Errorf("requirements: feature not found: %s", name)
+	}
+	mod := SlugifyModule(hit.Module)
+	if m := SlugifyModule(module); m != "" && m != mod {
+		res.Error = fmt.Sprintf("功能点「%s」属于模块「%s」，不是「%s」", name, mod, module)
+		return res, fmt.Errorf("requirements: module mismatch")
+	}
+	res.Module, res.Name, res.File = hit.Module, hit.Name, hit.File
+
+	// 落盘：<wsid>/shots/<模块>/<功能点slug>/<毫秒>.png
+	dirName := mod
+	if dirName == "" {
+		dirName = unfiledModule
+	}
+	shotDir := filepath.Join(wsDir(ws.ID), shotsDirName, dirName, SlugifyFeature(hit.Name))
+	if err := os.MkdirAll(shotDir, 0o700); err != nil {
+		res.Error = "创建截图目录失败：" + err.Error()
+		return res, err
+	}
+	now := time.Now()
+	// 文件名带毫秒 + 序号（同一毫秒内多张不至于撞名）。
+	base := strconv.FormatInt(now.UnixMilli(), 10)
+	full := filepath.Join(shotDir, base+".png")
+	for k := 2; fileExists(full); k++ {
+		full = filepath.Join(shotDir, base+"-"+strconv.Itoa(k)+".png")
+	}
+	if err := os.WriteFile(full, png, 0o600); err != nil {
+		res.Error = "写入截图失败：" + err.Error()
+		return res, err
+	}
+	// 文档里存**正斜杠**路径：Windows 的反斜杠在 markdown 里是转义符。
+	rel := filepath.ToSlash(full)
+	cap := strings.TrimSpace(caption)
+
+	// 追加到文档：文本级插入，其余字节不动。
+	raw, err := os.ReadFile(hit.File)
+	if err != nil {
+		res.Error = "读取文档失败：" + err.Error()
+		return res, err
+	}
+	out, count, err := insertShot(string(raw), rel, cap, now.UnixMilli())
+	if err != nil {
+		res.Error = err.Error()
+		return res, err
+	}
+	if err := writeFileAtomic(hit.File, []byte(out)); err != nil {
+		res.Error = "写文档失败：" + err.Error()
+		return res, err
+	}
+	res.Path = rel
+	res.Shots = count
+	res.OK = true
+	return res, nil
+}
+
+// fileExists 判断文件是否存在。
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}
+
+// insertShot 把一行截图插进「页面完成情况」段。
+//
+// 段不存在时新建：插在「## 来源对话」之前（缺来源段就插在「## 更新记录」之前，
+// 再缺就追加到文件末尾）。已有段则追加到该段末尾。
+//
+// 返回：新文档全文、该功能点现有截图数。
+func insertShot(text, path, caption string, at int64) (string, int, error) {
+	if strings.TrimSpace(path) == "" {
+		return "", 0, fmt.Errorf("requirements: empty shot path")
+	}
+	// 与归纳重渲染写出的形状一致（列表项 `- ![…]`），免得同一篇文档里两种写法混着。
+	line := "- " + shotLine(caption, path, at)
+	if line == "" {
+		return "", 0, fmt.Errorf("requirements: bad shot line")
+	}
+	lines := strings.Split(text, "\n")
+	// 定位「## 页面完成情况」段。
+	start := -1
+	for i, l := range lines {
+		if strings.TrimSpace(l) == "## 页面完成情况" {
+			start = i
+			break
+		}
+	}
+	if start < 0 {
+		// 新建段：插在来源对话之前（没有就插在更新记录之前，再没有就追加到末尾）。
+		pos := len(lines)
+		for i, l := range lines {
+			t := strings.TrimSpace(l)
+			if t == "## 来源对话" || t == "## 更新记录" {
+				pos = i
+				break
+			}
+		}
+		block := []string{"## 页面完成情况", line, ""}
+		out := make([]string, 0, len(lines)+len(block))
+		out = append(out, lines[:pos]...)
+		out = append(out, block...)
+		out = append(out, lines[pos:]...)
+		return strings.Join(out, "\n"), countShots(out), nil
+	}
+	// 已有段：找段尾（下一个 ## 或文件末）。
+	end := len(lines)
+	for i := start + 1; i < len(lines); i++ {
+		if strings.HasPrefix(strings.TrimSpace(lines[i]), "## ") {
+			end = i
+			break
+		}
+	}
+	// 段内占位符「（暂无）」在有图后就不该留着（它会显示成一条假内容）。
+	seg := lines[start:end]
+	cleaned := make([]string, 0, len(seg))
+	for _, l := range seg {
+		if strings.TrimSpace(l) == "（暂无）" {
+			continue
+		}
+		cleaned = append(cleaned, l)
+	}
+	cleaned = append(cleaned, line)
+	cleaned = trimShotLines(cleaned)
+	cleaned = dedupeShotLines(cleaned)
+	// 段与下一段之间要留一个空行，否则 markdown 会把下一段的标题吃掉。
+	tail := lines[end:]
+	if len(cleaned) > 1 && strings.TrimSpace(cleaned[len(cleaned)-1]) != "" && len(tail) > 0 {
+		cleaned = append(cleaned, "")
+	}
+	out := make([]string, 0, len(lines)+2)
+	out = append(out, lines[:start]...)
+	out = append(out, cleaned...)
+	out = append(out, tail...)
+	return strings.Join(out, "\n"), countShots(out), nil
+}
+
+// trimShotLines 把一段里的截图行裁到上限（超出的丢**最旧的**）。
+//
+// 丢最旧而不是最新：最新的截图是「最近一次改造的样子」，最该留。
+func trimShotLines(seg []string) []string {
+	idx := []int{}
+	for i, l := range seg {
+		if shotPathRe.MatchString(strings.TrimSpace(l)) {
+			idx = append(idx, i)
+		}
+	}
+	if len(idx) <= MaxShots {
+		return seg
+	}
+	drop := map[int]bool{}
+	for _, i := range idx[:len(idx)-MaxShots] {
+		drop[i] = true
+	}
+	out := make([]string, 0, len(seg))
+	for i, l := range seg {
+		if drop[i] {
+			continue
+		}
+		out = append(out, l)
+	}
+	return out
+}
+
+// dedupeShotLines 去掉段内**路径相同**的重复截图行。
+//
+// 同一张图被追加两次（客户端重试、或用户手动重放了一次归纳）时，
+// 「页面完成情况」不该出现两行一样的图。
+//
+// 语义与 TrimShots 一致：**留最后一条的内容，位置不动** —— 图的先后顺序
+// 是用户「改的次序」，不该被去重动作重排。
+func dedupeShotLines(seg []string) []string {
+	pos := map[string]int{}
+	content := map[string]string{}
+	for i, l := range seg {
+		t := strings.TrimSpace(l)
+		if !shotPathRe.MatchString(t) {
+			continue
+		}
+		p := shotPathOf(t)
+		if p == "" {
+			continue
+		}
+		if _, ok := pos[p]; !ok {
+			pos[p] = i
+		}
+		content[p] = l
+	}
+	out := make([]string, 0, len(seg))
+	for i, l := range seg {
+		t := strings.TrimSpace(l)
+		if shotPathRe.MatchString(t) {
+			if p := shotPathOf(t); p != "" {
+				if pos[p] != i {
+					continue
+				}
+				out = append(out, content[p])
+				continue
+			}
+		}
+		out = append(out, l)
+	}
+	return out
+}
+
+// shotPathOf 从一行截图里取出路径（去掉 `<>` 包与时间戳注释）。
+func shotPathOf(line string) string {
+	m := shotPathRe.FindStringSubmatch(strings.TrimSpace(line))
+	if m == nil {
+		return ""
+	}
+	return trimAngle(strings.TrimSpace(m[2]))
+}
+
+// countShots 数一篇文档里现有多少张截图。
+func countShots(lines []string) int {
+	n := 0
+	in := false
+	for _, l := range lines {
+		t := strings.TrimSpace(l)
+		if strings.HasPrefix(t, "## ") {
+			in = t == "## 页面完成情况"
+			continue
+		}
+		if in && shotPathRe.MatchString(t) {
+			n++
+		}
+	}
+	return n
+}
+
+// TrimShots 截断一个功能点的截图到上限（超出的丢最旧的），并**按 path 去重**。
+//
+// 只在归纳重写文档时用：RenderDoc 之前先把 Doc.Shots 裁到 MaxShots。
+//
+// 去重按 path：同一张图被写进文档两遍（比如手动重放了一次归纳）时不该在
+// 「页面完成情况」里出现两次。**留最后一条的内容，但位置不动** —— 重排会把
+// 文档里图的先后顺序打乱（用户是按「改的次序」攒图的，顺序本身有意义）。
+func TrimShots(shots []Shot) []Shot {
+	if len(shots) == 0 {
+		return shots
+	}
+	// 记下每个 path 最后一次出现的内容与**首次**出现的位置。
+	pos := map[string]int{}
+	content := map[string]Shot{}
+	for i, s := range shots {
+		p := strings.TrimSpace(s.Path)
+		if p == "" {
+			continue
+		}
+		if _, ok := pos[p]; !ok {
+			pos[p] = i
+		}
+		content[p] = s
+	}
+	out := make([]Shot, 0, len(shots))
+	for i, s := range shots {
+		p := strings.TrimSpace(s.Path)
+		if p == "" {
+			continue
+		}
+		if pos[p] != i {
+			continue
+		}
+		out = append(out, content[p])
+	}
+	if len(out) <= MaxShots {
+		return out
+	}
+	return out[len(out)-MaxShots:]
+}
+
+// writeFileAtomic 原子写文件（tmp + rename）：并发读不会读到半个文件。
+func writeFileAtomic(path string, data []byte) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Remove(tmp)
+		return err
+	}
+	return nil
+}
+
+// shotJSON 便于测试与调试的紧凑表示。
+func shotJSON(s Shot) string {
+	b, _ := json.Marshal(s)
+	return string(b)
+}