magic-agent 2.4.3 → 2.6.3

package/internal/config/config.go

@@ -71,6 +71,12 @@ const (
 	EnvCBGWPassword = "MAGIC_AGENT_CBGW_PASSWORD"
 )
 
+// feishu 一节支持的环境变量覆盖名（魔法值与其他节一致，都是 MAGIC_AGENT_ 前缀）。
+const (
+	EnvFeishuAppID     = "MAGIC_AGENT_FEISHU_APP_ID"
+	EnvFeishuAppSecret = "MAGIC_AGENT_FEISHU_APP_SECRET"
+)
+
 // EnvSystemPrompt 默认系统提示词的环境变量覆盖名。
 const EnvSystemPrompt = "MAGIC_AGENT_SYSTEM_PROMPT"
 
@@ -98,6 +104,40 @@ type Config struct {
 	 * ⚠️ 与 `arkclaw` 节的分工：`arkclaw` 是**历史保留的单实例**（老配置照旧生效，
 	 * 行为一个字不改）；`agents` 是新增的**多实例**通道。两者互不影响。 */
 	Agents []AgentConfig `json:"agents"`
+
+	/* Feishu 飞书推送（2026-10-26）的自建应用凭据：magic-client 用它把「任务完成 /
+	 * 待确认」推到用户本人的飞书。只有 magic-client 读它，core 引擎不用；
+	 * 移动端「我的 → 通知 → 飞书」也可以直接录（落 ~/.magic-agent/feishu-notify.json，0600），
+	 * 那边优先级更高。环境变量 MAGIC_AGENT_FEISHU_APP_ID / _APP_SECRET 也认（见 EnvFeishu*）。 */
+	Feishu FeishuConfig `json:"feishu"`
+}
+
+/* FeishuConfig 飞书自建应用（机器人）凭据。
+ *
+ *	{ "feishu": { "app_id": "cli_xxxx", "app_secret": "xxxx" } }
+ *
+ * 别名：app_id | appId | appId ；app_secret | appSecret | secret。 */
+type FeishuConfig struct {
+	AppID     string `json:"app_id"`
+	AppSecret string `json:"app_secret"`
+}
+
+// UnmarshalJSON 宽松解析：三个 app id 键名、三个 secret 键名任选其一。
+func (f *FeishuConfig) UnmarshalJSON(b []byte) error {
+	var raw struct {
+		AppID     string `json:"app_id"`
+		AppIDAlt  string `json:"appId"`
+		AppIDAlt2 string `json:"appid"`
+		Secret    string `json:"app_secret"`
+		SecretAlt string `json:"appSecret"`
+		SecretA3  string `json:"secret"`
+	}
+	if err := json.Unmarshal(b, &raw); err != nil {
+		return err
+	}
+	f.AppID = firstNonEmpty(raw.AppID, raw.AppIDAlt, raw.AppIDAlt2)
+	f.AppSecret = firstNonEmpty(raw.Secret, raw.SecretAlt, raw.SecretA3)
+	return nil
 }
 
 // UnmarshalJSON 宽松解析顶层键：systemPrompt / system_prompt / system 任选其一。
@@ -112,10 +152,12 @@ func (c *Config) UnmarshalJSON(b []byte) error {
 		SystemPromptAlt  string          `json:"system_prompt"`
 		SystemPromptAlt2 string          `json:"system"`
 		Agents           []AgentConfig   `json:"agents"`
+		Feishu           FeishuConfig    `json:"feishu"`
 	}
 	if err := json.Unmarshal(b, &raw); err != nil {
 		return err
 	}
+	c.Feishu = raw.Feishu
 	c.ArkClaw = raw.ArkClaw
 	// 四个键名任选其一（同一语义的多种写法；都写时按上面的优先级取第一个非空节）。
 	c.CodeBuddyGateway = firstNonEmptySection(raw.CBGW, raw.CBGWAlt, raw.CBGWAlt2, raw.CBGWAlt3)
@@ -407,6 +449,12 @@ func applyEnv(c Config) Config {
 	if v := strings.TrimSpace(os.Getenv(EnvCBGWPassword)); v != "" {
 		c.CodeBuddyGateway.Password = v
 	}
+	if v := strings.TrimSpace(os.Getenv(EnvFeishuAppID)); v != "" {
+		c.Feishu.AppID = v
+	}
+	if v := strings.TrimSpace(os.Getenv(EnvFeishuAppSecret)); v != "" {
+		c.Feishu.AppSecret = v
+	}
 	return c
 }
 

package/internal/judge/judge.go

@@ -0,0 +1,315 @@
+// Package judge - 判断「本轮任务」与「同一工作空间里正在跑的任务」会不会互相破坏。
+//
+// 为什么需要它（2026-10-26 用户：「任务模式增加自动 在新会话的时候判断是否可能与其他
+// 运行中会话冲突 如果冲突走串行 否则默认走并行」）：锁与进程信号只能回答「有没有人在跑」，
+// 回答不了「在跑什么」—— 同一空间里一个会话在改底部栏、另一个在写这个功能的文档，
+// 两者并行完全安全；而两个都要改 client-ui-mobile/index.html 就必须排队。
+// 这个判断是**语义**的，只能由模型来做（结构化的文件交集在插件侧先用规则筛一遍）。
+//
+// ── 为什么放在 core 而不是各客户端 ──
+// 提示词、输出解析、引擎调用只有一份；客户端（magic-client 的作业队列）exec 这一条即可。
+// 与 `--suggest-followups` / `--summarize-title` 同一套旁路范式：独立进程、ToolsOff、
+// 不带 SessionID，不续接也不污染用户正在聊的上下文，不写会话登记 / 日志。
+//
+// ── 三条纪律 ──
+//  1. **必须快**：调用方只给 2.5s 预算（判定挡在任务开跑前）。所以不思考、不跑工具、
+//     输出限 200 token；超了一律由调用方按「默认并行」放行，绝不拖住用户。
+//  2. **只说结论**：conflict 布尔 + 一句中文理由（必须落到具体文件/功能点，便于界面
+//     解释「为什么排队」）。理由不许编造输入里没有的东西。
+//  3. **判不出来不算冲突**：模型失败/超时返回 error，调用方走 undecided → 并行。
+package judge
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// 默认参数。判定是「开跑前的闸门」，宁可放行也不能让用户干等。
+const (
+	// DefaultEngine 默认 llm：纯文本、无工具、启动最快（CLI 系引擎单是启动就要 2-4s，
+	// 塞不进判定预算）。
+	DefaultEngine = "llm"
+	// DefaultTimeout core 侧兜底；插件侧给 2.5s，到点直接放弃（按并行放行）。
+	/* DefaultTimeout 内层上限（core 自己的判定预算）。外层（magic-client 的异步判定）
+	   给 4.5s，这里留 1s 给「起进程 + 收尾」，别让两层同时到点。 */
+	DefaultTimeout = 3500 * time.Millisecond
+	// MaxPromptRunes 本轮提示词上限（判定只需要「要动什么」，不需要全文）。
+	MaxPromptRunes = 2000
+	// MaxCandidates 最多同时比较几个运行中会话：多了提示词放不下，也判不准。
+	MaxCandidates = 6
+	// MaxFilesPerCandidate 每个候选最多带多少条已改文件（按最近优先）。
+	MaxFilesPerCandidate = 60
+	// MaxRecentRunes 候选「近况」上限。
+	MaxRecentRunes = 800
+	// MaxReasonRunes 理由上限（界面一行放得下）。
+	MaxReasonRunes = 120
+	// maxTokens 只够输出一个短 JSON。
+	maxTokens = 200
+)
+
+// Candidate 一个「正在运行、可能冲突」的会话。
+type Candidate struct {
+	// ID 会话 id（session_id 优先，没有则 run_id）：只用于回传给调用方做归属判断。
+	ID string `json:"id"`
+	// Title 会话标题（core 归纳过的那份，没有就是首问）。
+	Title string `json:"title,omitempty"`
+	// Recent 近况：最近几条用户诉求或助手动作的要点，由调用方从会话日志抽取。
+	Recent string `json:"recent,omitempty"`
+	// Files 这个会话**已经改动过**的文件（日志里 tool_kind=file_change 的参数路径）。
+	// 这是最硬的冲突证据：两边文件集合有交集时，调用方可以跳过模型直接判冲突。
+	Files []string `json:"files,omitempty"`
+}
+
+// RequestBody `--judge-conflict` 的 stdin/文件形状。
+type RequestBody struct {
+	Prompt     string      `json:"prompt"`
+	Candidates []Candidate `json:"candidates"`
+	// Engine / Model 用哪个引擎判（空 = DefaultEngine）。由调用方传用户配的「建议引擎」。
+	Engine string `json:"engine,omitempty"`
+	Model  string `json:"model,omitempty"`
+}
+
+// Request 一次判定的输入（引擎与超时由 CLI 层填）。
+type Request struct {
+	Prompt     string
+	Candidates []Candidate
+	Engine     string
+	Model      string
+	Timeout    time.Duration
+}
+
+// Result 判定结论（也是 `--judge-conflict` 的 stdout 形状）。
+type Result struct {
+	// Conflict 是否冲突。true = 调用方应把本轮改为串行等待。
+	Conflict bool `json:"conflict"`
+	// Level hard | soft | none：severity 只用于文案（hard=文件/功能直接重叠，
+	// soft=相关但不确定，none=不相干）。**是否排队只看 Conflict**，两者不一致时以 Conflict 为准。
+	Level string `json:"level"`
+	// Reason 一句中文理由，必须提到具体文件或功能点（界面直接显示这句）。
+	Reason string `json:"reason"`
+	// Overlaps 冲突点（文件名 / 功能名），界面据此高亮。
+	Overlaps []string `json:"overlaps,omitempty"`
+	// Engine / Model 实际判定的引擎与模型（排查「为什么每次都 undecided」用）。
+	Engine string `json:"engine"`
+	Model  string `json:"model,omitempty"`
+	// ElapsedMS 这次判定花了多久。
+	ElapsedMS int64 `json:"elapsedMs"`
+	// By 判定依据：model = 模型给的结论；rule = 调用方用文件交集直接定的（judge 包不产出）；
+	// undecided = 没判出来（调用方补的）。这里恒为 "model"。
+	By string `json:"by"`
+}
+
+// Prompt 拼判定提示词。刻意短：每个候选只给「标题 + 近况 + 文件」，不给整段历史。
+func Prompt(prompt string, cands []Candidate) string {
+	var b strings.Builder
+	b.WriteString("判断「本轮任务」与「正在运行的任务」并行时会不会互相破坏。\n")
+	b.WriteString("冲突 = 动同一批文件 / 同一功能点 / 同一份产物（同一个页面、同一个接口、同一份配置、同一篇文章）。\n")
+	b.WriteString("不冲突 = 同仓库里改彼此独立的模块；一边改代码一边写该代码的文档；跑构建与改另一个模块。\n\n")
+	b.WriteString("本轮任务：\n")
+	b.WriteString(clipRunes(strings.TrimSpace(prompt), MaxPromptRunes))
+	b.WriteString("\n\n正在运行：\n")
+	for i, c := range cands {
+		if i >= MaxCandidates {
+			break
+		}
+		b.WriteString("- ")
+		if t := strings.TrimSpace(c.Title); t != "" {
+			b.WriteString(clipRunes(t, 80))
+		} else {
+			b.WriteString("(未命名会话)")
+		}
+		if r := strings.TrimSpace(c.Recent); r != "" {
+			b.WriteString("｜近况：")
+			b.WriteString(clipRunes(r, MaxRecentRunes))
+		}
+		if len(c.Files) > 0 {
+			b.WriteString("｜已改：")
+			b.WriteString(strings.Join(tailStrings(c.Files, MaxFilesPerCandidate), ", "))
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("\n只输出 JSON：{\"conflict\":true|false,\"level\":\"hard|soft|none\",\"reason\":\"中文一句话\",\"overlaps\":[\"…\"]}\n")
+	b.WriteString("reason 必须点出具体的文件或功能点（例如「都要改 index.html 的底部栏」），不许笼统；")
+	b.WriteString("不冲突就写「互不相干」并说明各自动的模块；不许编造输入里没有的文件或功能。")
+	return b.String()
+}
+
+// Schema 结构化输出（llm / dsh / arkclaw 等支持 --json-schema 的引擎走它）。
+func Schema() *agent.JSONSchema {
+	return &agent.JSONSchema{
+		Type: "object",
+		Properties: map[string]map[string]any{
+			"conflict": {"type": "boolean"},
+			"level":    {"type": "string", "enum": []string{"hard", "soft", "none"}},
+			"reason":   {"type": "string"},
+			"overlaps": {"type": "array", "items": map[string]any{"type": "string"}},
+		},
+		Required: []string{"conflict", "level", "reason"},
+	}
+}
+
+// Judge 跑一次判定。调用方给的预算到了就返回 error（由调用方按并行放行）。
+func Judge(ctx context.Context, in Request) (Result, error) {
+	prompt := strings.TrimSpace(in.Prompt)
+	if prompt == "" {
+		return Result{}, fmt.Errorf("冲突判定：缺少本轮提示词")
+	}
+	cands := make([]Candidate, 0, len(in.Candidates))
+	for _, c := range in.Candidates {
+		if strings.TrimSpace(c.Title) == "" && strings.TrimSpace(c.Recent) == "" && len(c.Files) == 0 {
+			continue // 三条信息全空：这个候选帮不上任何忙，别占提示词
+		}
+		cands = append(cands, c)
+		if len(cands) >= MaxCandidates {
+			break
+		}
+	}
+	if len(cands) == 0 {
+		// 没有可比对象 = 不可能冲突。这不是错误，直接给结论，省一次模型调用。
+		return Result{Conflict: false, Level: "none", Reason: "没有正在运行的同空间任务", By: "rule"}, nil
+	}
+
+	name := strings.TrimSpace(in.Engine)
+	if name == "" {
+		name = DefaultEngine
+	}
+	if agent.Lookup(name) == nil {
+		return Result{}, fmt.Errorf("冲突判定：未知引擎 %q", name)
+	}
+	timeout := in.Timeout
+	if timeout <= 0 {
+		timeout = DefaultTimeout
+	}
+	cctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	start := time.Now()
+
+	msg := Prompt(prompt, cands)
+	res, err := runOnce(cctx, name, strings.TrimSpace(in.Model), msg, timeout, start)
+	if err == nil {
+		return res, nil
+	}
+	/* 主引擎失败：预算还够就落一次 llm（1-2s，判定用的小模型足够）。
+	   不再试用户配的「建议备用引擎」—— 那是给生成建议用的，判定多一跳只会把 2.5s 吃光。 */
+	if name == DefaultEngine || cctx.Err() != nil {
+		return Result{}, err
+	}
+	remain := timeout - time.Since(start)
+	if remain < 800*time.Millisecond {
+		return Result{}, err
+	}
+	return runOnce(cctx, DefaultEngine, "", msg, remain, start)
+}
+
+// runOnce 用指定引擎跑一次，并解析成 Result。
+func runOnce(ctx context.Context, name, model, msg string, budget time.Duration, start time.Time) (Result, error) {
+	engine := agent.Lookup(name)
+	if engine == nil {
+		return Result{}, fmt.Errorf("冲突判定：未知引擎 %q", name)
+	}
+	attemptCtx, cancel := context.WithTimeout(ctx, budget)
+	defer cancel()
+	runner := &agent.Runner{Engine: engine, Timeout: budget}
+	resp, err := runner.Run(attemptCtx, agent.Request{
+		Model: model,
+		// 判定纯文本：不给工具、不思考（与 --suggest-followups 同口径）。
+		Tools:      agent.ToolsOff,
+		NoThinking: true,
+		Reasoning:  "minimal",
+		MaxTokens:  maxTokens,
+		Messages:   []agent.Message{{Role: "user", Content: msg}},
+		JSONSchema: Schema(),
+	})
+	if err != nil {
+		return Result{}, err
+	}
+	out, perr := Parse(resp.Text)
+	if perr != nil {
+		return Result{}, perr
+	}
+	if out.Level == "" {
+		out.Level = "none"
+	}
+	if out.Conflict && out.Level == "none" {
+		out.Level = "soft" // 模型说冲突但没给档位：按最轻的冲突算，别把「不冲突」写在冲突旁边
+	}
+	out.Engine = engine.Name()
+	out.Model = resp.Model
+	out.ElapsedMS = time.Since(start).Milliseconds()
+	out.By = "model"
+	return out, nil
+}
+
+// Parse 从模型输出里抠出 JSON（容忍 ```json 围栏、前后解释文字）。
+func Parse(text string) (Result, error) {
+	raw := strings.TrimSpace(text)
+	if raw == "" {
+		return Result{}, fmt.Errorf("冲突判定：模型没有输出")
+	}
+	if i := strings.Index(raw, "{"); i > 0 {
+		raw = raw[i:]
+	}
+	if j := strings.LastIndex(raw, "}"); j >= 0 && j+1 < len(raw) {
+		raw = raw[:j+1]
+	}
+	var out Result
+	if err := json.Unmarshal([]byte(raw), &out); err != nil {
+		return Result{}, fmt.Errorf("冲突判定：输出不是 JSON（%v）：%s", err, clipRunes(raw, 120))
+	}
+	out.Level = normalizeLevel(out.Level)
+	out.Reason = clipRunes(strings.TrimSpace(out.Reason), MaxReasonRunes)
+	out.Overlaps = cleanList(out.Overlaps)
+	return out, nil
+}
+
+func normalizeLevel(s string) string {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "hard":
+		return "hard"
+	case "soft":
+		return "soft"
+	case "none", "":
+		return "none"
+	default:
+		return "soft" // 认不出的档位按「可能相关」处理，不放大成 hard
+	}
+}
+
+// cleanList 去空、去重、限长（模型常把同一个文件名重复列两遍）。
+func cleanList(in []string) []string {
+	out := make([]string, 0, len(in))
+	seen := map[string]bool{}
+	for _, s := range in {
+		v := strings.TrimSpace(s)
+		if v == "" || seen[v] {
+			continue
+		}
+		seen[v] = true
+		out = append(out, clipRunes(v, 80))
+		if len(out) >= 8 {
+			break
+		}
+	}
+	return out
+}
+
+func clipRunes(s string, max int) string {
+	if max <= 0 || utf8.RuneCountInString(s) <= max {
+		return s
+	}
+	return string([]rune(s)[:max])
+}
+
+// tailStrings 取最后 n 条（日志按时间追加，越靠后越新）。
+func tailStrings(in []string, n int) []string {
+	if n <= 0 || len(in) <= n {
+		return in
+	}
+	return in[len(in)-n:]
+}

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})
 	}