magic-agent 2.4.2 → 2.6.0

package/internal/requirements/doc.go

@@ -16,13 +16,18 @@ package requirements
 import (
 	"os"
 	"path/filepath"
+	"regexp"
 	"sort"
 	"strings"
+	"time"
 	"unicode"
 )
 
-// docSections 骨架的六个段落名（顺序即 renderDoc 的写盘顺序）。
-var docSections = []string{"最终版", "需求描述", "需求点", "已定结论", "来源对话", "更新记录"}
+// docSections 骨架的段落名（顺序即 renderDoc 的写盘顺序）。
+//
+// 「页面完成情况」是第七段（2026-10-25 用户：「需求文档整理时如果设计页面改造，
+// 调用内置浏览器 MCP 对完成情况截图标注并放在文档中」）：记页面地址 + 改造后的截图。
+var docSections = []string{"最终版", "需求描述", "需求点", "已定结论", "页面完成情况", "来源对话", "更新记录"}
 
 // Doc 一篇功能点文档的解析结果。
 type Doc struct {
@@ -34,6 +39,20 @@ type Doc struct {
 	Conclusions []string
 	Sources     []string
 	Log         []string
+	// PageURL 该功能点对应的页面地址（归纳时从对话里提取，可空）。
+	PageURL string
+	// Shots 页面改造的完成情况截图（按时间正序）。
+	Shots []Shot
+}
+
+// Shot 一张「页面完成情况」截图。
+type Shot struct {
+	// Path 截图在本机的绝对路径（**正斜杠**，跨平台一致）。
+	Path string
+	// Caption 标注说明（用户写的一句话，可空）。
+	Caption string
+	// At 截图时刻（unix 毫秒）。
+	At int64
 }
 
 // isPlaceholder 占位符判定：整条就等于占位符的一律丢弃。
@@ -90,7 +109,7 @@ func ParseDoc(text string) Doc {
 	if isPlaceholder(final) {
 		final = ""
 	}
-	return Doc{
+	d := Doc{
 		Final:       final,
 		Desc:        strings.TrimSpace(strings.Join(buf["需求描述"], " ")),
 		Points:      lines("需求点"),
@@ -98,6 +117,127 @@ func ParseDoc(text string) Doc {
 		Sources:     lines("来源对话"),
 		Log:         lines("更新记录"),
 	}
+	d.PageURL, d.Shots = parseShots(buf["页面完成情况"])
+	return d
+}
+
+// shotPathRe 截图行：`![说明](路径)`（路径是本机绝对路径，正斜杠），
+// 末尾可跟一个时间戳注释 `<!-- 2026-10-25T14:30:00Z -->`。
+//
+// 说明里不许出现 `]`（写入时会被清掉），路径用 `<>` 包时能容纳空格与括号
+// （Windows 下 `C:/Users/x/a b (v2)/x.png` 正是这种形状）。
+//
+// 前缀的列表符号 `- ` 是**可选**的：归纳重渲染写的是列表项（`- ![…]`），
+// 文本级插入写的是裸行 —— 两种形状都要能数出、认得出。
+var shotPathRe = regexp.MustCompile(`^(?:[-*+]\s+)?!\[([^\]]*)\]\((.*)\)(?:\s*<!--\s*([^>]*?)\s*-->)?\s*$`)
+
+// shotTimeRe 截图时间戳注释里的时间（RFC3339）。
+var shotTimeRe = regexp.MustCompile(`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?`)
+
+// pageURLPrefix 页面地址行前缀。
+const pageURLPrefix = "页面地址："
+
+// parseShots 解析「页面完成情况」段：页面地址 + 截图列表。
+//
+// 形状（代码写、模型不参与 —— 截图是事实，不能让模型编）：
+//
+//	页面地址：https://example.com/a
+//	![改成双列布局](C:/Users/x/.magic-agent/requirements/ws-x/shots/…/1.png) <!-- 2026-10-25T14:30:00Z -->
+func parseShots(raw []string) (string, []Shot) {
+	url := ""
+	shots := []Shot{}
+	for _, line := range raw {
+		l := strings.TrimSpace(stripListMarker(strings.TrimSpace(line)))
+		if l == "" {
+			continue
+		}
+		if strings.HasPrefix(l, pageURLPrefix) {
+			v := strings.TrimSpace(strings.TrimPrefix(l, pageURLPrefix))
+			if v != "" && !isPlaceholder(v) {
+				url = v
+			}
+			continue
+		}
+		m := shotPathRe.FindStringSubmatch(l)
+		if m == nil {
+			continue
+		}
+		s := Shot{Path: trimAngle(strings.TrimSpace(m[2])), Caption: strings.TrimSpace(m[1])}
+		if m[3] != "" {
+			if tm := shotTimeRe.FindString(m[3]); tm != "" {
+				if t, err := time.Parse(time.RFC3339, normalizeShotTime(tm)); err == nil {
+					s.At = t.UnixMilli()
+				}
+			}
+		}
+		shots = append(shots, s)
+	}
+	return url, shots
+}
+
+// normalizeShotTime 补齐 RFC3339 需要的时区。
+//
+// 写盘时用 UTC 的 RFC3339（结尾带 Z），但**历史数据**或手改过的文档可能缺时区 ——
+// 那种按 UTC 补 Z。带偏移（+08:00）的原样保留。
+func normalizeShotTime(s string) string {
+	v := strings.TrimSpace(s)
+	if v == "" {
+		return v
+	}
+	if strings.HasSuffix(v, "Z") || strings.HasSuffix(v, "z") {
+		return v
+	}
+	// 结尾是 ±HH:MM 偏移 → 已经是合法 RFC3339。
+	if len(v) >= 6 {
+		tail := v[len(v)-6:]
+		if (tail[0] == '+' || tail[0] == '-') && tail[3] == ':' {
+			return v
+		}
+	}
+	return v + "Z"
+}
+
+// trimAngle 去掉路径外的 `<>`（markdown 的转义写法）。
+func trimAngle(p string) string {
+	if len(p) >= 2 && strings.HasPrefix(p, "<") && strings.HasSuffix(p, ">") {
+		return strings.TrimSpace(p[1 : len(p)-1])
+	}
+	return p
+}
+
+// shotLine 渲染一行截图：说明 + 路径（+ 时间戳注释）。
+//
+// 路径含空格 / 括号时用 `<>` 包（markdown 的标准转义），否则解析回来会断。
+// 时间戳写成 HTML 注释：markdown 渲染时**看不见**，但解析能取回来
+// （清单上要显示「最后截图时间」，注释里不占视觉位置）。
+func shotLine(caption, path string, at int64) string {
+	c := sanitizeCaption(caption)
+	p := strings.TrimSpace(path)
+	if p == "" {
+		return ""
+	}
+	if strings.ContainsAny(p, " ()") {
+		p = "<" + p + ">"
+	}
+	var b strings.Builder
+	b.WriteString("![")
+	b.WriteString(c)
+	b.WriteString("](")
+	b.WriteString(p)
+	b.WriteString(")")
+	if at > 0 {
+		b.WriteString(" <!-- " + time.UnixMilli(at).UTC().Format(time.RFC3339) + " -->")
+	}
+	return b.String()
+}
+
+// sanitizeCaption 清掉会破坏 markdown 结构的字符（`]` 会截断说明、换行会断行）。
+func sanitizeCaption(c string) string {
+	s := strings.TrimSpace(c)
+	s = strings.ReplaceAll(s, "]", "）")
+	s = strings.ReplaceAll(s, "\r", " ")
+	s = strings.ReplaceAll(s, "\n", " ")
+	return strings.TrimSpace(s)
 }
 
 // stripListMarker 去掉行首的列表标记（`1. ` / `- ` / `* ` / `1、`）。
@@ -169,6 +309,17 @@ func RenderDoc(name string, d Doc) string {
 			b.WriteString("- " + c + "\n")
 		}
 	}
+	b.WriteString("\n## 页面完成情况\n")
+	if strings.TrimSpace(d.PageURL) == "" && len(d.Shots) == 0 {
+		b.WriteString("（暂无）\n")
+	} else {
+		if u := strings.TrimSpace(d.PageURL); u != "" {
+			b.WriteString(pageURLPrefix + u + "\n")
+		}
+		for _, s := range d.Shots {
+			b.WriteString("- " + shotLine(s.Caption, s.Path, s.At) + "\n")
+		}
+	}
 	b.WriteString("\n## 来源对话\n")
 	if len(S) == 0 {
 		b.WriteString("（暂无）\n")

package/internal/requirements/graph.go

@@ -0,0 +1,138 @@
+package requirements
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/session"
+)
+
+// 会话↔需求关系图谱：把 relations.jsonl 聚合成 nodes/edges 给前端画图。
+// feature 清单以文档目录**现算**为准（模块合并/改名后 relations 里可能残留
+// 旧名 —— 查不到的功能点连同边一起丢弃，不报错），relations 只供会话侧。
+
+type graphNode struct {
+	ID     string `json:"id"`
+	Type   string `json:"type"` // "session" | "feature"
+	Title  string `json:"title"`
+	Module string `json:"module,omitempty"`
+}
+
+type graphEdge struct {
+	Source string `json:"source"`
+	Target string `json:"target"`
+}
+
+type graphWorkspace struct {
+	ID    string      `json:"id"`
+	Name  string      `json:"name"`
+	Dir   string      `json:"dir,omitempty"`
+	Nodes []graphNode `json:"nodes"`
+	Edges []graphEdge `json:"edges"`
+}
+
+type graphOut struct {
+	OK         bool             `json:"ok"`
+	Root       string           `json:"root"`
+	Workspaces []graphWorkspace `json:"workspaces"`
+}
+
+// BuildGraph 聚合一个工作区（ws id / 目录 / ""=all）的关系图谱。
+func BuildGraph(where string) ([]byte, error) {
+	out := graphOut{OK: true, Root: Root()}
+	wsids := []workspaceEntry{}
+	if where == "" || where == "all" {
+		ws, err := Workspaces()
+		if err != nil {
+			return nil, err
+		}
+		for _, w := range ws {
+			wsids = append(wsids, workspaceEntry{ID: w.ID, Dir: w.Dir, Name: w.Name})
+		}
+	} else {
+		ws, ok := resolveWorkspace(where)
+		if !ok {
+			return nil, fmt.Errorf("requirements: workspace not found: %s", where)
+		}
+		wsids = append(wsids, ws)
+	}
+	for _, ws := range wsids {
+		out.Workspaces = append(out.Workspaces, buildGraphWS(ws))
+	}
+	if out.Workspaces == nil {
+		out.Workspaces = []graphWorkspace{}
+	}
+	b, err := json.Marshal(out)
+	if err != nil {
+		return nil, err
+	}
+	return b, nil
+}
+
+func buildGraphWS(ws workspaceEntry) graphWorkspace {
+	g := graphWorkspace{ID: ws.ID, Name: ws.Name, Dir: ws.Dir, Nodes: []graphNode{}, Edges: []graphEdge{}}
+	if g.Name == "" {
+		g.Name = ws.ID
+	}
+
+	docs := featureDocsOf(ws.ID)
+	featOK := make(map[string]graphNode, len(docs))
+	for _, d := range docs {
+		if d.Name == "" {
+			continue
+		}
+		n := graphNode{ID: "f:" + d.Module + "/" + d.Name, Type: "feature", Title: d.Name, Module: d.Module}
+		featOK[n.ID] = n
+		g.Nodes = append(g.Nodes, n)
+	}
+
+	rels := readRelations(ws.ID)
+	seenEdge := make(map[string]bool, len(rels))
+	sessTitle := make(map[string]string)
+	for _, r := range rels {
+		if r.Session == "" || r.Feature == "" {
+			continue
+		}
+		fid := "f:" + r.Module + "/" + r.Feature
+		if _, ok := featOK[fid]; !ok {
+			continue // 功能点已被合并/改名：关系随文档走，旧名丢弃
+		}
+		sid := "s:" + r.Session
+		if _, ok := sessTitle[r.Session]; !ok {
+			sessTitle[r.Session] = r.STitle
+		}
+		ek := r.Session + "\x00" + fid
+		if !seenEdge[ek] {
+			seenEdge[ek] = true
+			g.Edges = append(g.Edges, graphEdge{Source: sid, Target: fid})
+		}
+	}
+
+	// 会话节点放最后（标题：关系快照 → 登记表兜底）。
+	for s, t := range sessTitle {
+		if t == "" {
+			t = sessionTitleFallback(s)
+		}
+		g.Nodes = append(g.Nodes, graphNode{ID: "s:" + s, Type: "session", Title: t})
+	}
+	return g
+}
+
+// sessionTitleFallback 关系快照没存标题时从登记表/标题表兜底。
+func sessionTitleFallback(sessionID string) string {
+	if recs, err := session.List(); err == nil {
+		for _, r := range recs {
+			if r.SessionID == sessionID || r.RunID == sessionID {
+				if t := session.TitleForAny(r.SessionID, r.RunID); t != "" {
+					return t
+				}
+				return strings.TrimSpace(r.PromptHead)
+			}
+		}
+	}
+	if t := session.TitleForAny(sessionID, ""); t != "" {
+		return t
+	}
+	return sessionID
+}

package/internal/requirements/memory.go

@@ -302,6 +302,13 @@ func featureSummary(f featureFile) Feature {
 	item.Conclusions = len(d.Conclusions)
 	item.Sources = len(d.Sources)
 	item.HasFinal = strings.TrimSpace(d.Final) != ""
+	item.PageURL = d.PageURL
+	item.Shots = len(d.Shots)
+	for _, s := range d.Shots {
+		if s.At > item.ShotAt {
+			item.ShotAt = s.At
+		}
+	}
 	if len(d.Conclusions) > 0 {
 		item.Conclusion = d.Conclusions[0]
 	}

package/internal/requirements/modules.go

@@ -0,0 +1,312 @@
+package requirements
+
+// modules.go - 模块去重：把「表达同一件事」的已有模块合并成一个。
+//
+// 为什么归纳需要它（2026-10-25 用户报障，配图：magic-agent 空间 12 个模块里
+// 躺着「引擎管理 / 引擎调用」「配置管理 / 模型配置」「会话管理 / 对话交互」
+// 这种近义模块）：
+//
+//	· 现有的同义二审（consolidate.go 的 resolveModuleAlias）只挡**本轮新出现**的
+//	  模块名 vs 已有模块 —— 跨轮堆积下来的相似模块（这轮新的、下轮就成了「已有」）
+//	  从来没人互相比，用户在清单里看到的就是十几个近义一级分组；
+//	· 首次目录初始化（bootstrap.go）写文档时 alias 恒为空，模型一次输出 5-20 个
+//	  功能点，想造几个近义模块就造几个。
+//
+// 三条口径（与归纳 prompt 的规则 2 同一套判据，别在这里发明新说法）：
+//
+//	① 合并是**语义判断**，交给模型；代码只做确定性候选（名字共享字/包含）当
+//	   「要不要问这次模型」的成本闸门 —— 自动路径每轮都可能跑，不能每轮都烧一次；
+//	② 方向归一：并入**功能点更多**的那个模块（更主要的那个），数量持平听模型的；
+//	③ 内容不丢：无同名文档整体搬走 + 补一行「模块合并」记录；同名文档合并
+//	   （要点/结论保头去重、来源/流水保尾去重），不生成第二篇。
+//
+// 失败一律「不合并」（模型不可用 / 输出不可解析 / 幻觉模块名）—— 去重是质量增强，
+// 不该让归纳整轮失败，更不该把用户的文档搬丢。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// moduleMergeRules 模块合并的判据（与归纳规则 2 同一口径；prompt 与二审共用）。
+const moduleMergeRules = "「任务列表」与「对话列表」都指\"列表\"这件事 → 同一件事，应合并；" +
+	"「对话交互」指交互行为、「对话列表」指列表展示 → 不是同一件事，不许合并；" +
+	"同一功能域才算同一件事（如「引擎管理」与「引擎调用」同属引擎这一个功能域）；" +
+	"名字像但功能域不同（如「内容创作」与「团队协作」）不许合并。"
+
+// similarModulePairs 确定性候选：两个模块名共享任一字，或互为子串。
+//
+// 它**不做合并判断**（那是模型的语义活），只回答「值不值得为这批模块名跑一次模型」。
+// 中文产品模块名（≤6 字）里真正的同义项几乎都共享字符或互为子串；一个字都不搭的
+// （「远程接入」vs「局域网访问」这种）理论漏判，换取自动路径不为每个工作区每轮烧调用。
+func similarModulePairs(mods []string) [][2]string {
+	sets := make([]map[rune]bool, len(mods))
+	for i, m := range mods {
+		sets[i] = map[rune]bool{}
+		for _, r := range m {
+			sets[i][r] = true
+		}
+	}
+	out := [][2]string{}
+	for i := 0; i < len(mods); i++ {
+		for j := i + 1; j < len(mods); j++ {
+			if strings.Contains(mods[i], mods[j]) || strings.Contains(mods[j], mods[i]) {
+				out = append(out, [2]string{mods[i], mods[j]})
+				continue
+			}
+			for r := range sets[i] {
+				if sets[j][r] {
+					out = append(out, [2]string{mods[i], mods[j]})
+					break
+				}
+			}
+		}
+	}
+	return out
+}
+
+// moduleFeatureCounts 每个模块下的功能点文档数（挑合并目标用：更主要的那个）。
+func moduleFeatureCounts(id string) map[string]int {
+	out := map[string]int{}
+	for _, f := range listFeatureFiles(id) {
+		if f.Module != "" {
+			out[f.Module]++
+		}
+	}
+	return out
+}
+
+// resolveModuleMerge 问模型：哪些已有模块表达同一件事，需要合并。
+//
+// 输出契约复用 aliasSchema（{pairs:[{from,to}]}，from=被合并、to=并入）。
+// 校验：from / to 必须原样取自真实模块名（挡幻觉）；任何失败返回空表。
+func resolveModuleMerge(call llmCall, id string) [][2]string {
+	mods := []string{}
+	names := map[string][]string{}
+	for _, f := range listFeatureFiles(id) {
+		if f.Module == "" {
+			continue
+		}
+		if _, ok := names[f.Module]; !ok {
+			mods = append(mods, f.Module)
+		}
+		names[f.Module] = append(names[f.Module], f.Name)
+	}
+	if len(mods) < 2 {
+		return nil
+	}
+	var b strings.Builder
+	b.WriteString("你是资深产品经理。下面是同一个产品工作区的【已有模块】（一级功能点分组）。\n")
+	b.WriteString("请找出哪些模块其实表达**同一件事**（语义相同，不是字面相近），需要合并成一个。\n\n")
+	b.WriteString("== 已有模块 ==\n")
+	for _, m := range mods {
+		b.WriteString("· " + m + "（" + itoa(len(names[m])) + " 个功能点：" + strings.Join(names[m], "、") + "）\n")
+	}
+	b.WriteString("\n判据（与归纳规则同一口径）：\n· " + moduleMergeRules + "\n")
+	b.WriteString("没有要合并的就输出空数组 —— **宁可漏，不可错并**。\n")
+	b.WriteString("规则：from / to 都必须**原样**取自上面模块名。\n")
+	b.WriteString(`只输出 JSON：{"pairs":[{"from":"被合并模块","to":"并入模块"}]}`)
+
+	text, err := call(b.String(), aliasSchema)
+	if err != nil {
+		return nil
+	}
+	obj, ok := firstJSONObject(text)
+	if !ok {
+		return nil
+	}
+	var pairs struct {
+		Pairs []struct {
+			From string `json:"from"`
+			To   string `json:"to"`
+		} `json:"pairs"`
+	}
+	if json.Unmarshal([]byte(obj), &pairs) != nil {
+		return nil
+	}
+	valid := map[string]bool{}
+	for _, m := range mods {
+		valid[m] = true
+	}
+	out := [][2]string{}
+	for _, p := range pairs.Pairs {
+		from, to := strings.TrimSpace(p.From), strings.TrimSpace(p.To)
+		if from == "" || to == "" || from == to || !valid[from] || !valid[to] {
+			continue // 幻觉模块名一律不认
+		}
+		out = append(out, [2]string{from, to})
+	}
+	return out
+}
+
+// dedupeModules 找出「表达同一件事」的已有模块并合并。返回合并清单（"from → to"）。
+//
+// 流程：问模型 → 方向归一（功能点多的幸存，持平听模型的）→ 解链（A→B、B→C 都归 C，
+// visited 防环）→ 按幸存者分组搬目录。任何一步拿不到结果就原样返回。
+func dedupeModules(id string, call llmCall) []string {
+	pairs := resolveModuleMerge(call, id)
+	if len(pairs) == 0 {
+		return nil
+	}
+	counts := moduleFeatureCounts(id)
+	// target[drop] = keep：drop 被合并掉、keep 幸存。
+	target := map[string]string{}
+	for _, p := range pairs {
+		drop, keep := p[0], p[1]
+		if counts[drop] > counts[keep] {
+			drop, keep = keep, drop // 功能点更多的幸存（更主要的那个）；持平听模型的
+		}
+		target[drop] = keep
+	}
+	// 解链：沿着 target 走到不再被合并的那个模块为止。
+	root := map[string]string{}
+	for d := range target {
+		seen := map[string]bool{}
+		cur := d
+		for {
+			if seen[cur] {
+				break // 环（方向归一后理论上不会出现）：就地停下，不合并这一组
+			}
+			seen[cur] = true
+			next, ok := target[cur]
+			if !ok {
+				break
+			}
+			cur = next
+		}
+		root[d] = cur
+	}
+	groups := map[string][]string{}
+	for d, r := range root {
+		if d == r {
+			continue
+		}
+		groups[r] = append(groups[r], d)
+	}
+	roots := make([]string, 0, len(groups))
+	for r := range groups {
+		roots = append(roots, r)
+	}
+	sort.Strings(roots)
+	out := []string{}
+	for _, r := range roots {
+		drops := groups[r]
+		sort.Strings(drops)
+		for _, d := range drops {
+			if err := mergeModuleInto(id, d, r); err == nil {
+				out = append(out, d+" → "+r)
+			}
+		}
+	}
+	return out
+}
+
+// mergeModuleInto 把模块 from 的全部功能点文档并进 to（内容不丢）。
+func mergeModuleInto(id, from, to string) error {
+	base := featuresDir(id)
+	srcDir := filepath.Join(base, from)
+	dstDir := filepath.Join(base, to)
+	ents, err := os.ReadDir(srcDir)
+	if err != nil {
+		return err // from 不存在 = 没东西可搬
+	}
+	if err := os.MkdirAll(dstDir, 0o700); err != nil {
+		return err
+	}
+	for _, e := range ents {
+		if e.IsDir() {
+			continue
+		}
+		n := e.Name()
+		if strings.HasPrefix(n, ".") || !strings.HasSuffix(n, ".md") {
+			continue
+		}
+		src := filepath.Join(srcDir, n)
+		dst := filepath.Join(dstDir, n)
+		if _, err := os.Stat(dst); err == nil {
+			// 同名文档：两个模块下有同一个功能点 → 合并内容，不生成第二篇。
+			if err := mergeDocFile(src, dst, from, to); err != nil {
+				return err
+			}
+			_ = os.Remove(src)
+			continue
+		}
+		if err := os.Rename(src, dst); err != nil {
+			return err
+		}
+		// 搬走的文档补一行合并记录（可追溯：这篇原来属于哪个模块）。
+		noteModuleMerge(dst, from, to)
+	}
+	_ = os.Remove(srcDir) // 搬空了撤目录；有残留（非 .md）也不阻断（清单只收 .md）
+	// 关系流的 module 归属同步改写（relations.jsonl 记的是模块名，不改会悬空）。
+	_ = rewriteRelationsModule(id, from, to)
+	return nil
+}
+
+// mergeDocFile 两个模块下的同名文档 → 合并成一篇。
+//
+// 以目标文档为基座：desc 取目标已有（没有才用来源的）；要点/结论目标在前来源在后
+// （保头去重，清单稳定）；来源/流水保留最新（保尾去重），合并记录排在最后。
+func mergeDocFile(src, dst, from, to string) error {
+	sb, err := os.ReadFile(src)
+	if err != nil {
+		return err
+	}
+	db, err := os.ReadFile(dst)
+	if err != nil {
+		return err
+	}
+	a, b := ParseDoc(string(sb)), ParseDoc(string(db))
+	desc := b.Desc
+	if desc == "" {
+		desc = a.Desc
+	}
+	concs := mergeUnique(b.Conclusions, a.Conclusions, MaxConclusions, true, nil)
+	line := todayStr() + " 模块合并：从「" + from + "」并入「" + to + "」"
+	hist := append(append([]string{}, b.Log...), a.Log...)
+	doc := Doc{
+		Final:       renderFinal(desc, concs),
+		Desc:        desc,
+		Points:      mergeUnique(b.Points, a.Points, MaxPoints, true, nil),
+		Conclusions: concs,
+		Sources:     mergeUnique(b.Sources, a.Sources, MaxSources, false, sourceKey),
+		Log:         mergeUnique(hist, []string{line}, MaxLogLines, false, nil),
+	}
+	name := strings.TrimSuffix(filepath.Base(dst), ".md")
+	return os.WriteFile(dst, []byte(RenderDoc(name, doc)), 0o600)
+}
+
+// noteModuleMerge 给整体搬过来的文档补一行「模块合并」记录（尽力而为，失败不阻断）。
+func noteModuleMerge(file, from, to string) {
+	b, err := os.ReadFile(file)
+	if err != nil {
+		return
+	}
+	d := ParseDoc(string(b))
+	line := todayStr() + " 模块合并：从「" + from + "」并入「" + to + "」"
+	d.Log = mergeUnique(d.Log, []string{line}, MaxLogLines, false, nil)
+	_ = os.WriteFile(file, []byte(RenderDoc(strings.TrimSuffix(filepath.Base(file), ".md"), d)), 0o600)
+}
+
+// moduleDedupeWanted 这一轮要不要顺手做模块去重。
+//
+//	· 模块级整理（opts.Module 非空）永远不跑 —— 用户点哪个模块就只动那个，
+//	   「只整理一个模块」不能顺手把模块结构改了（2026-10-23 报障的同一条纪律）；
+//	· 名字毫无交集（无确定性候选）不跑 —— 不为「看起来很干净」的清单烧一次模型；
+//	· 自动路径（插件轮末防抖，每轮都可能跑）额外要求本轮真写了新文档；
+//	· 手动（含 force / all / 无新记忆的 noop）：用户点了「整理」就认真查一次。
+func moduleDedupeWanted(opts Options, res Result, mods []string) bool {
+	if len(mods) < 2 || opts.Module != "" {
+		return false
+	}
+	if len(similarModulePairs(mods)) == 0 {
+		return false
+	}
+	if opts.Auto {
+		return res.Created > 0
+	}
+	return true
+}