magic-agent 2.4.2 → 2.6.0

package/internal/client/suggest.go

@@ -15,11 +15,13 @@ package client
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"io"
 	"net/http"
-	"os/exec"
 	"strings"
+	"sync"
 	"time"
 	"unicode/utf8"
 
@@ -41,6 +43,77 @@ const (
 // 2 = 允许「当前会话收尾」与「刚切过去的另一个会话」各一条，超出直接 429。
 var suggestSlots = make(chan struct{}, 2)
 
+// 建议缓存：同一轮问答（user+reply+引擎/模型都相同）的建议只跑一次模型调用。
+// 界面在会话切换 / 重渲染时会重复请求同一轮的建议，没缓存就每次都起一个旁路
+// 引擎进程白烧一次调用（用户 2026-10-24：「会话的建议要有缓存 不能每次都重复跑」）。
+// 只缓存**成功**响应（含空数组——空也是合法结果）；失败不缓存，下次重试。
+const (
+	suggestCacheTTL     = 30 * time.Minute
+	suggestCacheMaxSize = 128
+)
+
+type suggestCacheEntry struct {
+	payload  []byte // 成功响应的 JSON（已保证 Suggestions 非 nil）
+	expireAt time.Time
+	usedAt   time.Time // LRU 淘汰用
+}
+
+var suggestCache = struct {
+	sync.Mutex
+	m map[string]suggestCacheEntry
+}{m: make(map[string]suggestCacheEntry)}
+
+// suggestCacheKey 按完整请求内容算 key：user/reply 一样但换了引擎/模型就分开算。
+func suggestCacheKey(body struct {
+	User           string `json:"user"`
+	Reply          string `json:"reply"`
+	Engine         string `json:"engine"`
+	Model          string `json:"model"`
+	FallbackEngine string `json:"fallbackEngine"`
+	FallbackModel  string `json:"fallbackModel"`
+}) string {
+	h := sha256.Sum256([]byte(strings.Join([]string{
+		body.User, body.Reply, body.Engine, body.Model, body.FallbackEngine, body.FallbackModel,
+	}, "\x00")))
+	return hex.EncodeToString(h[:])
+}
+
+// suggestCacheGet 命中返回响应 JSON；顺带做惰性过期与 LRU 容量控制。
+func suggestCacheGet(key string) ([]byte, bool) {
+	suggestCache.Lock()
+	defer suggestCache.Unlock()
+	e, ok := suggestCache.m[key]
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(e.expireAt) {
+		delete(suggestCache.m, key)
+		return nil, false
+	}
+	e.usedAt = time.Now()
+	suggestCache.m[key] = e
+	return e.payload, true
+}
+
+func suggestCachePut(key string, payload []byte) {
+	suggestCache.Lock()
+	defer suggestCache.Unlock()
+	if len(suggestCache.m) >= suggestCacheMaxSize {
+		// 淘汰最久未用的一条（缓存最多 128 条，线性找足够快）。
+		var oldestKey string
+		var oldest time.Time
+		first := true
+		for k, v := range suggestCache.m {
+			if first || v.usedAt.Before(oldest) {
+				oldestKey, oldest, first = k, v.usedAt, false
+			}
+		}
+		delete(suggestCache.m, oldestKey)
+	}
+	now := time.Now()
+	suggestCache.m[key] = suggestCacheEntry{payload: payload, expireAt: now.Add(suggestCacheTTL), usedAt: now}
+}
+
 // handleSuggest POST /desk/suggest。
 //
 // 请求：{"user":"用户上一句","reply":"本轮回答正文","engine":"可选","model":"可选"}
@@ -55,6 +128,10 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 		Reply  string `json:"reply"`
 		Engine string `json:"engine"`
 		Model  string `json:"model"`
+		// 建议引擎的主备（2026-10-24，只增字段）：主建议引擎失败时先试它，
+		// 再落到 core 内置的 llm 兜底。空 = 老行为。
+		FallbackEngine string `json:"fallbackEngine"`
+		FallbackModel  string `json:"fallbackModel"`
 	}
 	if r.Body != nil {
 		if err := json.NewDecoder(io.LimitReader(r.Body, suggestMaxBody)).Decode(&body); err != nil {
@@ -70,6 +147,14 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	body.User = clipRunes(strings.TrimSpace(body.User), suggestMaxUserRunes)
 	body.Reply = clipRunes(body.Reply, suggestMaxReplyRunes)
 
+	// 同一轮问答的重复请求直接回缓存（切换会话/重渲染会反复要同一轮的建议）。
+	cacheKey := suggestCacheKey(body)
+	if payload, ok := suggestCacheGet(cacheKey); ok {
+		w.Header().Set("X-Suggest-Cache", "hit")
+		writeJSONBytes(w, http.StatusOK, payload)
+		return
+	}
+
 	select {
 	case suggestSlots <- struct{}{}:
 		defer func() { <-suggestSlots }()
@@ -90,7 +175,13 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	if m := strings.TrimSpace(body.Model); m != "" {
 		args = append(args, "-m", m)
 	}
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	if fb := strings.TrimSpace(body.FallbackEngine); fb != "" {
+		args = append(args, "--suggest-fallback-engine", fb)
+		if m := strings.TrimSpace(body.FallbackModel); m != "" {
+			args = append(args, "--suggest-fallback-model", m)
+		}
+	}
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
 	cmd.Stdin = bytes.NewReader(payload)
 	var stdout, stderr bytes.Buffer
 	cmd.Stdout = &stdout
@@ -119,9 +210,21 @@ func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
 	if res.Suggestions == nil {
 		res.Suggestions = []string{}
 	}
+	if payload, err := json.Marshal(res); err == nil {
+		suggestCachePut(cacheKey, payload)
+		writeJSONBytes(w, http.StatusOK, payload)
+		return
+	}
 	writeJSON(w, http.StatusOK, res)
 }
 
+// writeJSONBytes 按预序列化的字节写响应（缓存命中与缓存写入共用同一份形状）。
+func writeJSONBytes(w http.ResponseWriter, code int, payload []byte) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(code)
+	_, _ = w.Write(payload)
+}
+
 // clipRunes 按 rune 截断（中文不能按字节切）。
 func clipRunes(s string, max int) string {
 	if max <= 0 || utf8.RuneCountInString(s) <= max {

package/internal/client/suggest_test.go

@@ -6,15 +6,31 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 )
 
 // fakeSuggestCore 写一个假 core 脚本：记录 argv → 吃掉 stdin → 打印一份建议 JSON。
+//
+// Windows 上 exec 不了 sh 脚本（既有基线），改写等价的 .cmd 批处理 —— scriptBody
+// 仍收 sh 语法，由映射表翻成 cmd 等价物；没翻译的写法直接 Fatal，防止静默跑错。
 func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
 	t.Helper()
 	argLog := filepath.Join(dir, "args.txt")
 	p := filepath.Join(dir, "magic-agent")
+	if runtime.GOOS == "windows" {
+		p += ".cmd"
+		win, ok := shToCmd[scriptBody]
+		if !ok {
+			t.Fatalf("没给该 sh 脚本体准备 Windows 等价物：%q", scriptBody)
+		}
+		body := "@echo off\r\necho %*>\"" + argLog + "\"\r\nfind /v \"\" >NUL\r\n" + win + "\r\n"
+		if err := os.WriteFile(p, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return p, argLog
+	}
 	body := "#!/bin/sh\nprintf '%s' \"$*\" > " + argLog + "\ncat >/dev/null\n" + scriptBody + "\n"
 	if err := os.WriteFile(p, []byte(body), 0o755); err != nil {
 		t.Fatal(err)
@@ -22,6 +38,15 @@ func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
 	return p, argLog
 }
 
+// shToCmd 测试里用到的假 core 脚本体的 cmd 等价写法。
+var shToCmd = map[string]string{
+	`printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`: `echo {"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}`,
+	`printf '{"suggestions":["继续"],"engine":"fake","elapsedMs":9}\n'`:                  `echo {"suggestions":["继续"],"engine":"fake","elapsedMs":9}`,
+	`printf '{"suggestions":[]}\n'`:        `echo {"suggestions":[]}`,
+	"echo 'llm CLI not found' >&2\nexit 3": `echo llm CLI not found 1>&2&exit /b 3`,
+	`printf 'not json\n'`:                  `echo not json`,
+}
+
 func TestSuggestEndpoint(t *testing.T) {
 	dir := t.TempDir()
 	core, argLog := fakeSuggestCore(t, dir, `printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`)
@@ -53,6 +78,67 @@ func TestSuggestEndpoint(t *testing.T) {
 	}
 }
 
+func TestSuggestEndpointCacheHit(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":["继续"],"engine":"fake","elapsedMs":9}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+	body := `{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"fake-engine"}`
+
+	call := func() *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(body)))
+		return rec
+	}
+
+	first := call()
+	if first.Code != http.StatusOK {
+		t.Fatalf("首次 code = %d，body=%s", first.Code, first.Body.String())
+	}
+	if first.Header().Get("X-Suggest-Cache") == "hit" {
+		t.Fatalf("首次请求不应命中缓存")
+	}
+	second := call()
+	if second.Code != http.StatusOK {
+		t.Fatalf("二次 code = %d，body=%s", second.Code, second.Body.String())
+	}
+	if second.Header().Get("X-Suggest-Cache") != "hit" {
+		t.Fatalf("同内容的第二次请求应命中缓存")
+	}
+	if second.Body.String() != first.Body.String() {
+		t.Fatalf("缓存响应与首次不一致：%s vs %s", second.Body.String(), first.Body.String())
+	}
+
+	// 换引擎 = 换 key，不能复用旧缓存。
+	third := httptest.NewRecorder()
+	s.handleSuggest(third, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"other-engine"}`)))
+	if third.Header().Get("X-Suggest-Cache") == "hit" {
+		t.Fatalf("换了引擎应重新生成，不该命中缓存")
+	}
+
+	// 失败不缓存：core 挂了下次要重试。
+	failing := &Service{opts: Options{MagicAgent: fakeSuggestCoreFailing(t, dir)}}
+	f1 := httptest.NewRecorder()
+	failing.handleSuggest(f1, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"失败那轮"}`)))
+	if f1.Code != http.StatusBadGateway {
+		t.Fatalf("失败轮 code = %d，期望 502", f1.Code)
+	}
+	f2 := httptest.NewRecorder()
+	failing.handleSuggest(f2, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"失败那轮"}`)))
+	if f2.Code != http.StatusBadGateway {
+		t.Fatalf("失败后重试仍应走 core（code = %d，期望 502）", f2.Code)
+	}
+}
+
+// fakeSuggestCoreFailing 恒定失败的假 core（复用 fakeSuggestCore 的平台适配）。
+func fakeSuggestCoreFailing(t *testing.T, dir string) string {
+	t.Helper()
+	p, _ := fakeSuggestCore(t, dir, "echo 'llm CLI not found' >&2\nexit 3")
+	return p
+}
+
 func TestSuggestEndpointBadRequests(t *testing.T) {
 	dir := t.TempDir()
 	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":[]}\n'`)

package/internal/client/team_flags.go

@@ -92,21 +92,35 @@ func teamFlags(t *teamRequest, profile Profile, roles []string) ([]string, error
 		r := t.Routes[rawKind]
 		engine := strings.TrimSpace(r.Engine)
 		model := strings.TrimSpace(r.Model)
-		if engine == "" {
+		fbEngine := strings.TrimSpace(r.FallbackEngine)
+		fbModel := strings.TrimSpace(r.FallbackModel)
+		/* 备用可以单独配（主引擎留空 = 跟随主引擎 + 这一路的备）：所以这里不能用
+		   「engine 为空就 continue」把整条略掉 —— 有备用就得下发。 */
+		if engine != "" {
+			if !profile.AllowsEngine(engine) {
+				return nil, fmt.Errorf("team.routes.%s 的引擎 %q 不在 profile 白名单内", kind, engine)
+			}
+			spec := kind + "=" + engine
 			if model != "" {
-				// 只给模型不给引擎：语义不明（模型属于某一家引擎），不猜。
-				return nil, fmt.Errorf("team.routes.%s 给了 model 但没给 engine", kind)
+				spec += "/" + model
 			}
-			continue // 整条空 = 该类跟随主引擎
-		}
-		if !profile.AllowsEngine(engine) {
-			return nil, fmt.Errorf("team.routes.%s 的引擎 %q 不在 profile 白名单内", kind, engine)
+			args = append(args, "--team-route", spec)
+		} else if model != "" {
+			// 只给模型不给引擎：语义不明（模型属于某一家引擎），不猜。
+			return nil, fmt.Errorf("team.routes.%s 给了 model 但没给 engine", kind)
 		}
-		spec := kind + "=" + engine
-		if model != "" {
-			spec += "/" + model
+		if fbEngine != "" {
+			if !profile.AllowsEngine(fbEngine) {
+				return nil, fmt.Errorf("team.routes.%s 的备用引擎 %q 不在 profile 白名单内", kind, fbEngine)
+			}
+			spec := kind + "=" + fbEngine
+			if fbModel != "" {
+				spec += "/" + fbModel
+			}
+			args = append(args, "--team-fallback", spec)
+		} else if fbModel != "" {
+			return nil, fmt.Errorf("team.routes.%s 给了备用 model 但没给备用 engine", kind)
 		}
-		args = append(args, "--team-route", spec)
 	}
 	return args, nil
 }

package/internal/client/team_flags_test.go

@@ -146,6 +146,45 @@ func TestTeamFlagsRejectsModelWithoutEngine(t *testing.T) {
 	}
 }
 
+func TestTeamFlagsFallbackRoute(t *testing.T) {
+	// 主备（2026-10-24）：主 + 备都要翻成 flag；只配备用也要下发（主引擎跟随主引擎）。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {Engine: "codebuddy", Model: "hy3", FallbackEngine: "dsh", FallbackModel: "v3"},
+		"text":  {FallbackEngine: "claude"},
+	}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	joined := strings.Join(args, " ")
+	if !strings.Contains(joined, "--team-route image=codebuddy/hy3") {
+		t.Fatalf("主引擎没下发：%v", args)
+	}
+	if !strings.Contains(joined, "--team-fallback image=dsh/v3") {
+		t.Fatalf("备用引擎没下发：%v", args)
+	}
+	if !strings.Contains(joined, "--team-fallback text=claude") {
+		t.Fatalf("只配备用的路由没下发：%v", args)
+	}
+	if strings.Contains(joined, "--team-route text=") {
+		t.Fatalf("只配备用不该伪造主引擎：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsBadFallback(t *testing.T) {
+	// 备用引擎同样要过白名单。
+	if _, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {Engine: "llm", FallbackEngine: "claude"},
+	}}, Profile{Engines: []string{"llm"}}, nil); err == nil {
+		t.Fatal("备用引擎不在白名单时应报错")
+	}
+	// 备用 model 没有备用 engine：语义不明，不猜。
+	if _, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"image": {FallbackModel: "sonnet"},
+	}}, Profile{}, nil); err == nil || !strings.Contains(err.Error(), "备用") {
+		t.Fatalf("err = %v，应提到备用", err)
+	}
+}
+
 func TestTeamFlagsAcceptsPlanRoute(t *testing.T) {
 	// plan = 计划阶段（谁来拆任务），与五类子任务一样可以单独指定引擎。
 	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"plan": {Engine: "claude"}}}, Profile{}, nil)

package/internal/requirements/bootstrap.go

@@ -187,6 +187,10 @@ type bootstrapResult struct {
 	Created     int
 	Points      int
 	Conclusions int
+	// Merged / MergedModules 模块去重合并掉的模块（目录基线自己也可能造近义模块，
+	// 之前 auto 归纳攒下的也顺手合并；见 modules.go）。
+	Merged        int
+	MergedModules []string
 }
 
 // bootstrapWorkspace 按工作区目录反推一版需求基线。
@@ -275,6 +279,18 @@ func bootstrapWorkspace(ctx context.Context, ws workspaceEntry, opts Options) (b
 		   与 features:[] 同样处理：标记初始化完成，回落到会话增量，不要把旧会话吞掉。 */
 		res.Empty = true
 	}
+	/* 模块去重：目录基线自己也可能造出近义模块（模型一次输出 5-20 个功能点），
+	   之前 auto 归纳攒下的相似模块也顺手合并。用初始化引擎包一个文本调用器 ——
+	   不能走 newCaller（测试钉死：首次初始化不碰文本归纳器）。 */
+	if mods := listModules(ws.ID); len(mods) >= 2 && len(similarModulePairs(mods)) > 0 {
+		mergeCall := func(prompt string, schema *agent.JSONSchema) (string, error) {
+			return runBootstrapAgent(ctx, engineName, bootstrapModel, ws.Dir, prompt, timeout)
+		}
+		if merged := dedupeModules(ws.ID, mergeCall); len(merged) > 0 {
+			res.Merged = len(merged)
+			res.MergedModules = merged
+		}
+	}
 	return res, nil
 }
 

package/internal/requirements/consolidate.go

@@ -60,6 +60,9 @@ var outSchema = &agent.JSONSchema{
 					"points":      map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
 					"conclusions": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
 					"sources":     map[string]any{"type": "array", "items": map[string]any{"type": "integer"}},
+					// page_url：该功能点对应的页面地址（**可选**）。
+					// 不进 required：多数功能点没有页面，硬要求会让模型编一个出来。
+					"page_url": map[string]any{"type": "string"},
 				},
 				"required": []string{"module", "name", "desc", "points", "conclusions", "sources"},
 			},
@@ -76,6 +79,8 @@ type featureOut struct {
 	Points      []string
 	Conclusions []string
 	Sources     []int
+	// PageURL 该功能点对应的页面地址（记忆里有才填，空 = 没有）。
+	PageURL string `json:"page_url"`
 }
 
 // UnmarshalJSON 容忍 sources 里混进字符串编号（模型偶尔给 "#12"）。
@@ -87,12 +92,14 @@ func (f *featureOut) UnmarshalJSON(b []byte) error {
 		Points      []string          `json:"points"`
 		Conclusions []string          `json:"conclusions"`
 		Sources     []json.RawMessage `json:"sources"`
+		PageURL     string            `json:"page_url"`
 	}
 	if err := json.Unmarshal(b, &raw); err != nil {
 		return err
 	}
 	f.Module, f.Name, f.Desc = raw.Module, raw.Name, raw.Desc
 	f.Points, f.Conclusions = raw.Points, raw.Conclusions
+	f.PageURL = strings.TrimSpace(raw.PageURL)
 	for _, s := range raw.Sources {
 		var n int
 		if json.Unmarshal(s, &n) == nil {
@@ -181,6 +188,8 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		if boot.Called {
 			res.Calls++ // 反推是一次带工具的 agent 调用（与下面的归纳共用 calls 口径）
 		}
+		res.Merged += boot.Merged
+		res.MergedModules = append(res.MergedModules, boot.MergedModules...)
 		if !boot.Empty {
 			res.Updated += boot.Updated
 			res.Created += boot.Created
@@ -222,7 +231,30 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	if replay {
 		entries = mem
 	}
+	engineName := strings.TrimSpace(opts.Engine)
+	if engineName == "" {
+		engineName = "llm"
+	}
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = DefaultTimeout
+	}
 	if len(entries) == 0 && !opts.Force {
+		/* 手动空间级「整理」：没有新记忆也顺手做一次模块去重 —— 用户点「整理」
+		   就是想清理列表，只回一句 noop 等于没修（2026-10-25 报障：magic-agent
+		   空间 12 个模块里躺着多组近义，点整理却只听到「没有新的对话需要整理」）。
+		   构造不出 caller（引擎不存在等）就静默回落 noop，不改变现有行为。 */
+		if mods := listModules(ws.ID); moduleDedupeWanted(opts, res, mods) {
+			if call, cerr := newCaller(ctx, engineName, opts.Model, timeout); cerr == nil {
+				if merged := dedupeModules(ws.ID, call); len(merged) > 0 {
+					res.Merged = len(merged)
+					res.MergedModules = merged
+					res.OK = true
+					res.Pending = max(0, len(mem)-cursor)
+					return res, nil
+				}
+			}
+		}
 		res.OK = true
 		res.Noop = true
 		res.Pending = 0
@@ -238,14 +270,6 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		use = use[:MaxEntriesPerRun]
 	}
 
-	engineName := strings.TrimSpace(opts.Engine)
-	if engineName == "" {
-		engineName = "llm"
-	}
-	timeout := opts.Timeout
-	if timeout <= 0 {
-		timeout = DefaultTimeout
-	}
 	call, callErr := newCaller(ctx, engineName, opts.Model, timeout)
 	if callErr != nil {
 		res.Error = callErr.Error()
@@ -335,6 +359,24 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 					}
 					return out
 				},
+				onWrite: func(module, feature string, sources []int) {
+					rels := make([]Relation, 0, len(sources))
+					for _, n := range sources {
+						e, ok := byN[n]
+						if !ok || e.Session == "" {
+							continue
+						}
+						rels = append(rels, Relation{
+							Ts:      time.Now().UnixMilli(),
+							Session: e.Session,
+							STitle:  e.Title,
+							Module:  module,
+							Feature: feature,
+							N:       n,
+						})
+					}
+					_ = appendRelations(ws.ID, rels)
+				},
 			})
 			if !w.ok {
 				continue
@@ -349,6 +391,18 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		}
 	}
 
+	/* 模块去重：把跨轮堆积的相似模块合并掉（「引擎管理 / 引擎调用」这种近义一级分组，
+	   单靠循环里的「新模块二审」挡不住 —— 那只能管本轮新出现的名字）。模块级整理
+	   不做（moduleDedupeWanted 里挡着），自动路径只在本轮真写了新文档时顺手做。 */
+	if mods := listModules(ws.ID); moduleDedupeWanted(opts, res, mods) {
+		if merged := dedupeModules(ws.ID, call); len(merged) > 0 {
+			res.Merged = len(merged)
+			res.MergedModules = merged
+		}
+	}
+
+	_ = compactRelations(ws.ID) // 归纳收尾去重一次（写入期只 append）
+
 	consumed := cursor
 	if !replay && moduleScope == "" {
 		consumed = cursor + len(use)
@@ -573,6 +627,9 @@ func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []str
 			"不要当结论写进去；结论必须是「已经定下来的做法/取舍」。",
 		"     与「已有结论」语义相同的同样逐字照抄；**已有结论为空但记忆里有明确结论的必须补上**；",
 		"   · sources：本条目引用的记忆编号（整数数组，取自上面 `#编号`）；",
+		"   · page_url：**该功能点对应的页面地址**（可选）。只有当记忆里明确出现了这个页面" +
+			"（http/https 开头）才填，并**原样照抄**那个地址；记忆里没有就填空串 \"\"，" +
+			"**绝不猜、绝不编**（编出来的地址会让人点开一个不存在的页面）；",
 		"5. 只归纳记忆里真实出现的内容，不要发明未提到的功能，**不要写任何日期**；",
 		"6. 没有任何新信息时输出空数组 features: []。",
 	}
@@ -610,10 +667,23 @@ func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []str
 	b.WriteString(strings.Join(rules, "\n"))
 	b.WriteString("\n\n只输出 JSON：{\"features\":[{\"module\":\"≤" + strconv.Itoa(ModuleMaxChars) +
 		"字大功能点\",\"name\":\"≤" + strconv.Itoa(TitleMaxChars) +
-		"字要点\",\"desc\":\"\",\"points\":[\"≤30字\"],\"conclusions\":[\"≤30字\"],\"sources\":[12]}]}")
+		"字要点\",\"desc\":\"\",\"points\":[\"≤30字\"],\"conclusions\":[\"≤30字\"],\"sources\":[12],\"page_url\":\"\"}]}")
 	return b.String()
 }
 
+// validPageURL 页面地址是否可用：只认 http/https（其余一律丢弃）。
+//
+// 为什么这么严：模型偶尔会填「无」「待定」「见上文」，或把本地路径当地址。
+// 这些进了文档会变成一个点不开的链接 —— 比没有更糟。
+func validPageURL(u string) bool {
+	v := strings.TrimSpace(u)
+	if v == "" || isPlaceholder(v) {
+		return false
+	}
+	low := strings.ToLower(v)
+	return strings.HasPrefix(low, "http://") || strings.HasPrefix(low, "https://")
+}
+
 // aliasSchema 模块同义二审的输出契约。
 var aliasSchema = &agent.JSONSchema{
 	Type: "object",
@@ -769,6 +839,11 @@ type writeCtx struct {
 	kind      string
 	all       bool
 	sourcesOf func(featureOut) []string
+	/* onWrite 文档落盘后的关系回调：module/feature 是**改写后**的最终归属
+	   （alias、hit 沿用都算过了），sources 是模型给的记忆编号 —— 调用方据此
+	   记「会话↔需求」关系（relations.jsonl）。事后用 featureOut 重算会记错
+	   模块名（归属在这函数里才定），必须回调。 */
+	onWrite func(module, feature string, sources []int)
 }
 
 // writeResult 一条增量的落盘结果。
@@ -845,6 +920,17 @@ func writeFeatureItem(id string, out featureOut, ctx *writeCtx) writeResult {
 	}
 	sources := mergeUnique(prev.Sources, srcLines, MaxSources, false, sourceKey)
 
+	/* 页面地址（2026-10-25 用户：「涉及页面改造时截图标注放进文档」）：
+	   新值合法才覆盖；本轮没给（或给了非法值）就**保留旧的** ——
+	   页面地址是文档里长期有效的事实，不该被某一轮的空值抹掉。 */
+	pageURL := prev.PageURL
+	if u := strings.TrimSpace(out.PageURL); u != "" && validPageURL(u) {
+		pageURL = u
+	}
+	/* 截图段必须**原样带回**：RenderDoc 是全量重写文档，不带回就会把用户
+	   逐张攒的完成情况截图全部抹掉。 */
+	shots := TrimShots(prev.Shots)
+
 	dPts := len(points) - len(prev.Points)
 	if dPts < 0 {
 		dPts = 0
@@ -874,6 +960,8 @@ func writeFeatureItem(id string, out featureOut, ctx *writeCtx) writeResult {
 		Conclusions: conclusions,
 		Sources:     sources,
 		Log:         logLines,
+		PageURL:     pageURL,
+		Shots:       shots,
 	}
 	if err := os.MkdirAll(dir, 0o700); err != nil {
 		return writeResult{}
@@ -881,6 +969,9 @@ func writeFeatureItem(id string, out featureOut, ctx *writeCtx) writeResult {
 	if err := os.WriteFile(full, []byte(RenderDoc(name, doc)), 0o600); err != nil {
 		return writeResult{}
 	}
+	if ctx.onWrite != nil && len(out.Sources) > 0 {
+		ctx.onWrite(rawMod, name, out.Sources)
+	}
 	if !has {
 		ctx.merger.add(featureFile{Module: rawMod, Name: name, File: full})
 	}