magic-agent 1.0.49 → 1.0.108

package/internal/requirements/consolidate.go

@@ -0,0 +1,908 @@
+package requirements
+
+// consolidate.go - 归纳主流程：记忆 → 功能点文档。
+//
+// 口径继承业务项目（magic-test desktop/requirements.cjs）里**实测出来**的那几条：
+//
+//	· 模型只给增量（desc / points / conclusions / sources 编号），骨架与日期由代码写；
+//	· 已有文档**只喂「模块 + 名称 + 已有需求点/结论」**，不喂整篇（省 token，去重更准）；
+//	· 归属以「已有文档的模块」为准，模型这轮给的 module 只对**新文档**生效
+//	  （否则同一篇在两轮归纳里被搬来搬去，用户刚记住的位置就变了）；
+//	· 全量重放要**分片**：一次让模型输出所有功能点会被输出上限截断（实测 22 篇断在半句）；
+//	· 「来源对话」由代码按记忆编号回查原文 —— 不让模型摘抄（实测它只摘当轮那一条）。
+//
+// 与业务项目不同的两处：
+//
+//	① 归纳用哪个引擎：那边固定 llm 引擎；这里可用 Options.Engine 指定，默认仍是 llm
+//	   （纯文本、无工具：归纳不需要读文件，给它工具反而会把工具痕迹混进 JSON）。
+//	② 「最终版」由代码从「需求描述 + 已定结论」收敛生成，不额外调一次 LLM。
+//	   业务项目的最终版是「手动点一下才生成」的定稿；这里是全自动链路，没有那个点击时机，
+//	   留一个永远「（待生成）」的段等于交付半个产品。代价是它会随结论增长而变化 ——
+//	   但它是**派生**内容，不是用户编辑过的正文，变化符合预期。
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// DefaultTimeout 单次归纳 LLM 调用的默认超时。
+//
+// 240s 与业务项目同口径：80 条记忆 + 二十来篇已有文档的 prompt，实测 40~90s 出结果，
+// 推理模型翻倍。给到 4 分钟既能容忍慢模型，也不会让「自动归纳」把进程吊太久。
+const DefaultTimeout = 240 * time.Second
+
+// lockStale 归纳锁超过这个时长视为陈旧（进程被 kill 时会留下锁文件）。
+const lockStale = 15 * time.Minute
+
+// outSchema 归纳输出契约（只给增量，不给整篇文档）。
+//
+// 它同时承担两件事：llm 引擎的结构化输出后处理（顶层 Required 校验）、
+// 以及渲染进 prompt 的形状说明（见 buildPrompt 末尾）。
+var outSchema = &agent.JSONSchema{
+	Type: "object",
+	Properties: map[string]map[string]any{
+		"features": {
+			"type": "array",
+			"items": map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"module":      map[string]any{"type": "string"},
+					"name":        map[string]any{"type": "string"},
+					"desc":        map[string]any{"type": "string"},
+					"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"}},
+				},
+				"required": []string{"module", "name", "desc", "points", "conclusions", "sources"},
+			},
+		},
+	},
+	Required: []string{"features"},
+}
+
+// featureOut 模型给出的一条功能点增量。
+type featureOut struct {
+	Module      string `json:"module"`
+	Name        string `json:"name"`
+	Desc        string `json:"desc"`
+	Points      []string
+	Conclusions []string
+	Sources     []int
+}
+
+// UnmarshalJSON 容忍 sources 里混进字符串编号（模型偶尔给 "#12"）。
+func (f *featureOut) UnmarshalJSON(b []byte) error {
+	var raw struct {
+		Module      string            `json:"module"`
+		Name        string            `json:"name"`
+		Desc        string            `json:"desc"`
+		Points      []string          `json:"points"`
+		Conclusions []string          `json:"conclusions"`
+		Sources     []json.RawMessage `json:"sources"`
+	}
+	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
+	for _, s := range raw.Sources {
+		var n int
+		if json.Unmarshal(s, &n) == nil {
+			f.Sources = append(f.Sources, n)
+			continue
+		}
+		var str string
+		if json.Unmarshal(s, &str) == nil {
+			if v, err := strconv.Atoi(strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(str), "#"))); err == nil {
+				f.Sources = append(f.Sources, v)
+			}
+		}
+	}
+	return nil
+}
+
+// Consolidate 跑一轮归纳。
+//
+// where 可以是工作区 id（ws-xxxx），也可以是目录路径（含 ~）；空 = 当前目录。
+// 一轮的语义：先把该目录下所有会话的新 user 事件补进记忆流（ingest），
+// 再把游标之后、上限之内的记忆喂给模型，把返回的增量合并进功能点文档。
+func Consolidate(ctx context.Context, where string, opts Options) (Result, error) {
+	dir := strings.TrimSpace(where)
+	if dir == "" {
+		if cwd, err := os.Getwd(); err == nil {
+			dir = cwd
+		}
+	}
+	ws, ok := resolveWorkspace(dir)
+	if !ok {
+		return Result{Dir: dir, Error: "工作区不存在: " + dir}, fmt.Errorf("requirements: workspace not found: %s", dir)
+	}
+	if Root() == "" {
+		return Result{Workspace: ws.ID, Dir: ws.Dir, Error: "无法确定需求存储目录"}, fmt.Errorf("requirements: no storage root")
+	}
+	res := Result{Workspace: ws.ID, Dir: ws.Dir}
+
+	// 锁：同一工作区同时只允许一轮归纳（客户端防抖 + 手动「立即整理」可能撞上）。
+	release, busy := acquireLock(ws.ID)
+	if busy {
+		res.Error = "另一个进程正在归纳，跳过"
+		return res, errBusy
+	}
+	defer release()
+
+	if ws.Dir != "" {
+		registerWorkspace(ws.Dir)
+	}
+
+	st := readState(ws.ID)
+	// 摄入失败不阻断归纳：已有记忆照样能归纳，无非是这一轮少吃几条。
+	_, _ = ingest(ws.ID, ws.Dir, &st)
+	_ = writeState(ws.ID, st) // 摄入游标先落盘：即使下面 LLM 失败，也不重复摄入
+
+	mem := readMemory(ws.ID)
+
+	/* 首次「整理」：先按空间目录反推一版需求基线，再把旧会话记为已消费。
+	   判断依据是 state.BootstrapAt（不是文档数 / 不是 LastConsolidatedAt）：
+	   自动归纳可能已经产出过几篇文档，但「有没有按目录初始化过」是另一件事。
+	   opts.Auto 的自动路径不初始化 —— 它每轮都可能跑，不能悄悄花几分钟读代码。 */
+	if st.BootstrapAt == 0 && !opts.Auto {
+		boot, berr := bootstrapWorkspace(ctx, ws, opts)
+		if berr != nil {
+			res.Error = truncRunes(berr.Error(), 240)
+			_ = writeState(ws.ID, withError(st, res.Error))
+			return res, berr
+		}
+		res.Scanned = boot.Scanned
+		res.BootstrapEngine = boot.Engine
+		now := time.Now().UnixMilli()
+		st.BootstrapAt = now
+		st.LastConsolidatedAt = now
+		st.LastError = ""
+		/* 这一轮确实做了「首次初始化」——目录为空也算（标记已落盘，用户点过就该有反馈）。
+		   Calls 只统计真的调了模型的轮次（空目录不会调）。 */
+		res.Bootstrap = true
+		if boot.Called {
+			res.Calls++ // 反推是一次带工具的 agent 调用（与下面的归纳共用 calls 口径）
+		}
+		if !boot.Empty {
+			res.Updated += boot.Updated
+			res.Created += boot.Created
+			res.Points += boot.Points
+			res.Conclusions += boot.Conclusions
+			/* 目录基线已经覆盖了「此刻之前的历史」：旧会话不再逐条重放。
+			   这正是用户要的「没有初始化过 → 按空间目录重新生成；之后只处理新会话」。
+			   --requirement-all 是显式回填，保留重放语义（游标不动）。 */
+			if !opts.All {
+				st.Consumed = len(mem)
+				if err := writeState(ws.ID, st); err != nil {
+					res.Error = "写状态失败: " + err.Error()
+					return res, err
+				}
+				res.OK = true
+				res.Pending = 0
+				return res, nil
+			}
+		}
+		/* 目录为空（或显式全量重放）：初始化标记照落，继续走会话增量。
+		   空目录不是错误 —— 一个只有对话、没有代码的工作区也应该能靠聊天长需求。 */
+		if err := writeState(ws.ID, st); err != nil {
+			res.Error = "写状态失败: " + err.Error()
+			return res, err
+		}
+	}
+
+	cursor := st.Consumed
+	if cursor < 0 {
+		cursor = 0
+	}
+	if cursor > len(mem) {
+		cursor = len(mem) // 记忆文件被外部截断 → 游标跟着收敛，不越界
+	}
+	entries := mem[cursor:]
+	if opts.All {
+		entries = mem
+	}
+	if len(entries) == 0 && !opts.Force {
+		res.OK = true
+		res.Noop = true
+		res.Pending = 0
+		return res, nil
+	}
+
+	use := entries
+	if opts.All {
+		if len(use) > MaxReplayEntries {
+			use = use[len(use)-MaxReplayEntries:]
+		}
+	} else if len(use) > MaxEntriesPerRun {
+		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()
+		_ = writeState(ws.ID, withError(st, res.Error))
+		return res, callErr
+	}
+
+	chunks := chunkEntries(use, opts.All)
+	merger := newDocMerger(ws.ID)
+	byN := make(map[int]Entry, len(mem))
+	for _, e := range mem {
+		byN[e.N] = e
+	}
+	wsName := ws.Name
+	if wsName == "" {
+		wsName = ws.ID
+	}
+
+	for _, chunk := range chunks {
+		// 每片重新读已有文档：上一片刚写的要点必须出现在这一片的「已有需求点」里，
+		// 否则同一件事会被重复追加。
+		docs := featureDocsOf(ws.ID)
+		prompt := buildPrompt(wsName, docs, chunk, listModules(ws.ID), opts.All)
+		text, err := call(prompt, outSchema)
+		res.Calls++
+		if err != nil {
+			res.Error = truncRunes(err.Error(), 240)
+			_ = writeState(ws.ID, withError(st, res.Error))
+			return res, err
+		}
+		outs, perr := parseFeatures(text)
+		if perr != nil {
+			res.Error = "LLM 输出不可解析: " + perr.Error()
+			_ = writeState(ws.ID, withError(st, res.Error))
+			return res, perr
+		}
+		if len(outs) == 0 {
+			continue
+		}
+
+		// 新模块的同义二审：归纳是逐轮独立的，模型容易把同一件事拆成近义模块
+		//（「任务列表」/「对话列表」）。只有确认已有模块里没有同义项时才允许新建。
+		alias := map[string]string{}
+		existing := listModules(ws.ID)
+		newMods := []string{}
+		seenNew := map[string]bool{}
+		for _, o := range outs {
+			m := SlugifyModule(o.Module)
+			if m == "" || seenNew[m] || contains(existing, m) {
+				continue
+			}
+			seenNew[m] = true
+			newMods = append(newMods, m)
+		}
+		if len(newMods) > 0 && len(existing) > 0 {
+			alias = resolveModuleAlias(call, newMods, existing)
+		}
+
+		for _, o := range outs {
+			w := writeFeatureItem(ws.ID, o, &writeCtx{
+				merger: merger,
+				alias:  alias,
+				kind:   "归纳",
+				all:    opts.All,
+				sourcesOf: func(x featureOut) []string {
+					out := make([]string, 0, len(x.Sources))
+					for _, n := range x.Sources {
+						e, ok := byN[n]
+						if !ok {
+							continue
+						}
+						out = append(out, fmt.Sprintf("[%s] #%d %s", fmtTs(e.Ts), e.N, truncRunes(collapseSpace(e.Text), SourceChars)))
+					}
+					return out
+				},
+			})
+			if !w.ok {
+				continue
+			}
+			res.Points += w.points
+			res.Conclusions += w.conclusions
+			if w.created {
+				res.Created++
+			} else {
+				res.Updated++
+			}
+		}
+	}
+
+	consumed := cursor
+	if !opts.All {
+		consumed = cursor + len(use)
+		if consumed > len(mem) {
+			consumed = len(mem)
+		}
+	}
+	st.Consumed = consumed
+	st.LastConsolidatedAt = time.Now().UnixMilli()
+	st.LastError = ""
+	if err := writeState(ws.ID, st); err != nil {
+		res.Error = "写状态失败: " + err.Error()
+		return res, err
+	}
+	res.OK = true
+	res.Consumed = 0
+	if !opts.All {
+		res.Consumed = len(use)
+	}
+	res.Replayed = 0
+	if opts.All {
+		res.Replayed = len(use)
+	}
+	res.Pending = len(mem) - consumed
+	if res.Pending < 0 {
+		res.Pending = 0
+	}
+	return res, nil
+}
+
+// errBusy 另一个进程正在归纳（不是错误，是「这次跳过」）。
+var errBusy = fmt.Errorf("requirements: busy")
+
+// IsBusy 判断一轮归纳是否因为别的进程持锁而被跳过。
+func IsBusy(err error) bool { return err == errBusy }
+
+// llmCall 一次模型调用（prompt + 可选结构化契约 → 模型正文）。
+type llmCall func(prompt string, schema *agent.JSONSchema) (string, error)
+
+// newCaller 构造实际调用器。
+//
+// 抽成一层是为了让单测能灌一个假模型 —— 归纳真正容易错的地方是**合并与游标**
+// （骨架解析、去重、来源回查、消费到第几条），那些逻辑不该因为「跑测试要真调模型」
+// 而没人验。真机验收走的就是这里的默认实现。
+var newCaller = func(ctx context.Context, engineName, model string, timeout time.Duration) (llmCall, error) {
+	engine := agent.Lookup(engineName)
+	if engine == nil {
+		return nil, fmt.Errorf("未知引擎: %s", engineName)
+	}
+	return func(prompt string, schema *agent.JSONSchema) (string, error) {
+		cctx, cancel := context.WithTimeout(ctx, timeout)
+		defer cancel()
+		runner := &agent.Runner{Engine: engine, Timeout: timeout}
+		resp, err := runner.Run(cctx, agent.Request{
+			Messages:   []agent.Message{{Role: "user", Content: prompt}},
+			Tools:      agent.ToolsOff,
+			Model:      model,
+			JSONSchema: schema,
+			Timeout:    timeout,
+		})
+		if err != nil {
+			return "", err
+		}
+		return strings.TrimSpace(resp.Text), nil
+	}, nil
+}
+
+// chunkEntries 分片。
+//
+// 增量轮不分片（≤80 条、且只输出「有变化的」那几个功能点）；
+// 全量重放必须分：一次喂全部历史时模型要一口气输出所有功能点，输出会被上限截断。
+func chunkEntries(use []Entry, all bool) [][]Entry {
+	if !all {
+		if len(use) == 0 {
+			return [][]Entry{{}}
+		}
+		return [][]Entry{use}
+	}
+	if len(use) == 0 {
+		return [][]Entry{{}}
+	}
+	out := make([][]Entry, 0, (len(use)+ReplayChunk-1)/ReplayChunk)
+	for i := 0; i < len(use); i += ReplayChunk {
+		end := i + ReplayChunk
+		if end > len(use) {
+			end = len(use)
+		}
+		out = append(out, use[i:end])
+	}
+	return out
+}
+
+// existsDoc 已有功能点（喂 prompt 用：只给模块 + 名称 + 已有要点/结论）。
+type existsDoc struct {
+	Module string
+	Name   string
+	Doc    Doc
+}
+
+func featureDocsOf(id string) []existsDoc {
+	files := listFeatureFiles(id)
+	out := make([]existsDoc, 0, len(files))
+	for _, f := range files {
+		d := Doc{}
+		if b, err := os.ReadFile(f.File); err == nil {
+			d = ParseDoc(string(b))
+		}
+		out = append(out, existsDoc{Module: f.Module, Name: f.Name, Doc: d})
+	}
+	return out
+}
+
+// buildPrompt 组归纳 prompt。
+//
+// 规则段是**产品口径**，不是技术参数：哪些话不能写进需求点（缺陷措辞）、
+// 什么样的模块必须复用、结论与问题的界限。这些是业务项目半年里一条条纠正出来的，
+// 换实现时原样保留，别按自己的口味重写。
+func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []string, replay bool) string {
+	mods := make([]string, 0, len(modules))
+	for _, m := range modules {
+		if strings.TrimSpace(m) != "" {
+			mods = append(mods, m)
+		}
+	}
+	var fb strings.Builder
+	if len(docs) == 0 {
+		fb.WriteString("（暂无功能点，可按需新建）")
+	} else {
+		for i, d := range docs {
+			if i > 0 {
+				fb.WriteString("\n")
+			}
+			if d.Module != "" {
+				fb.WriteString("[模块 " + d.Module + "] ")
+			} else {
+				fb.WriteString("[未归类] ")
+			}
+			fb.WriteString(d.Name + "\n")
+			if len(d.Doc.Points) > 0 {
+				fb.WriteString("  已有需求点：\n")
+				for j, p := range d.Doc.Points {
+					fb.WriteString("    " + strconv.Itoa(j+1) + ") " + truncRunes(p, 40) + "\n")
+				}
+			}
+			if len(d.Doc.Conclusions) > 0 {
+				fb.WriteString("  已有结论：\n")
+				for _, c := range d.Doc.Conclusions {
+					fb.WriteString("    · " + truncRunes(c, 40) + "\n")
+				}
+			}
+		}
+	}
+	var mb strings.Builder
+	for i, e := range entries {
+		if i > 0 {
+			mb.WriteString("\n")
+		}
+		mb.WriteString("#" + strconv.Itoa(e.N) + " [" + fmtTs(e.Ts) + "]")
+		if t := strings.TrimSpace(e.Title); t != "" {
+			mb.WriteString("(任务: " + t + ")")
+		}
+		mb.WriteString(" " + collapseSpace(e.Text))
+	}
+	memBlock := mb.String()
+	if memBlock == "" {
+		memBlock = "（无）"
+	}
+
+	rules := []string{
+		"0. 本次只给了**新增的那一批**记忆，按下面的规则归纳即可。",
+		"1. 每条需求都必须归入某个 module（大功能点）—— module 是必填字段；",
+		"2. module 优先复用（**硬约束**）：必须先从上面「已有模块」里挑一个。判据是**语义是否相同**，" +
+			"而不是字面是否相近 —— 只要已有模块表达了同一件事，就必须复用它，哪怕你觉得另起一个名字更贴切：",
+		"     · 「任务列表」与「对话列表」都指\"列表\"这件事 → **是同一个模块**，必须复用已有的那个；",
+		"     · 「对话交互」与「对话列表」一个指交互行为、一个指列表展示 → 不是一回事，可以并存；",
+		"   只有「已有模块」里**没有任何一个**表达相同含义时，才新建 module（不超过 " + strconv.Itoa(ModuleMaxChars) + " 个汉字）。",
+		"   module 是**产品模块名**（如「任务列表」「对话交互」「需求管理」「应用打包」），" +
+			"不是需求描述、不是动词短语。宁可归到一个稍宽泛的已有模块，也不要新建近义模块；",
+		"3. 功能点优先复用：属于某个已有功能点时，**逐字沿用它的 name 与 module**，只输出新增内容；",
+		"4. 只输出**增量**（代码会按文本去重，所以「已有」的那条**逐字照抄**、绝不改写）：",
+		"   · desc：该功能点的一句话需求描述（产品视角，说清\"用户拿它做什么 / 期望是什么样\"，" +
+			"不是缺陷描述）。已有描述且本次无变化 → 给空串 \"\"；",
+		"   · points：需求点，每条 ≤30 字。⚠️ **必须是「需求」，不是「bug 清单」**：",
+		"     写「这个功能**应当**是什么样」（用户能做什么 / 会发生什么），而不是「哪里坏了、要修什么」。",
+		"     **不许出现**：「修复 X」「X 有问题 / 不正确 / 错误 / 异常」「X 仍然存在 / 仍可见」" +
+			"「应改为 …」「排查 / 优化 X」这类**现象或缺陷措辞** —— 那描述的是现状，不是需求。",
+		"     要从现象里**提炼出期望行为**再写；提炼不出来（用户只是笼统说「有问题」）就**不写这条**：",
+		"       「npc有问题 同时玩家直接穿进来了」→「玩家撞到 NPC 会被挡住，不能直接穿过去」",
+		"       「允许进 但是实际挡住了 应该进不去」→「被 NPC 挡住的位置一律进不去，没有能穿过去的缺口」",
+		"     与「已有需求点」**语义相同的一律逐字照抄已有那条**（不要同义改写 —— 改写会变成重复项）；" +
+			"只有确实缺失的才新增；",
+		"   · conclusions：**已经定下来**的结论 / 决策 / 取舍 / 约束，每条 ≤30 字。" +
+			"只写记忆里**明确表达过**的（用户拍板的、明确说不要的、选定的方案）；" +
+			"不要写建议、不要推测、不要写\"待定/需确认\"；没有就给空数组 [];",
+		"     ⚠️ **现象与问题描述不是结论**：像「删除任务后列表仍可见，需修复」这种是**问题**，" +
+			"不要当结论写进去；结论必须是「已经定下来的做法/取舍」。",
+		"     与「已有结论」语义相同的同样逐字照抄；**已有结论为空但记忆里有明确结论的必须补上**；",
+		"   · sources：本条目引用的记忆编号（整数数组，取自上面 `#编号`）；",
+		"5. 只归纳记忆里真实出现的内容，不要发明未提到的功能，**不要写任何日期**；",
+		"6. 没有任何新信息时输出空数组 features: []。",
+	}
+	if replay {
+		rules[0] = "0. **本次是全量重放**：上面给的是该工作区的**全部历史记忆**（不是新增的那一批）。" +
+			"判据是「这个功能点还能不能更完整」而不是「有没有新东西」——" +
+			"把记忆里涉及到的功能点**都输出一遍**（哪怕只补 desc）：" +
+			"desc 可用记忆重新校核改写（这是唯一允许改写 desc 的场景），" +
+			"需求点/结论里已有的一字不改照抄、缺的补上。"
+	}
+
+	var b strings.Builder
+	b.WriteString("你是资深产品经理，负责把「对话记忆」归纳成**两级**功能点需求文档的**增量**。工作区：" + wsName + "\n\n")
+	b.WriteString("== 已有模块（大功能点 · 一级）==\n")
+	if len(mods) == 0 {
+		b.WriteString("（暂无模块，可新建）")
+	} else {
+		b.WriteString(strings.Join(mods, "、"))
+	}
+	b.WriteString("\n\n== 已有功能点（模块 + 名称 + 已有需求点/结论 · 二级 · 用于去重）==\n")
+	b.WriteString(fb.String())
+	b.WriteString("\n== 新增对话记忆（`#编号` 用于「来源」引用）==\n")
+	b.WriteString(memBlock)
+	b.WriteString("\n\n== 归纳规则 ==\n")
+	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]}]}")
+	return b.String()
+}
+
+// aliasSchema 模块同义二审的输出契约。
+var aliasSchema = &agent.JSONSchema{
+	Type: "object",
+	Properties: map[string]map[string]any{
+		"pairs": {
+			"type": "array",
+			"items": map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"from": map[string]any{"type": "string"},
+					"to":   map[string]any{"type": "string"},
+				},
+				"required": []string{"from", "to"},
+			},
+		},
+	},
+	Required: []string{"pairs"},
+}
+
+// resolveModuleAlias 把本轮新出现的模块名和已有模块做语义比对，同义的归一到已有模块。
+//
+// 失败一律返回空表（本轮按原名新建）—— 二审是质量增强，不该让归纳整轮失败。
+func resolveModuleAlias(call func(string, *agent.JSONSchema) (string, error), cands, existing []string) map[string]string {
+	if len(cands) == 0 || len(existing) == 0 {
+		return map[string]string{}
+	}
+	prompt := []string{
+		"你是资深产品经理。下面是同一个产品工作区里【已有模块】和【本轮新增模块】。",
+		"请找出「新增模块」中哪些其实与某个已有模块表达**同一件事**（语义相同，不是字面相近）。",
+		"判据示例：「任务列表」与「对话列表」都指\"列表\"这件事 → 同一件事；" +
+			"「对话交互」指交互行为、「对话列表」指列表展示 → 不是同一件事。",
+		"",
+		"== 已有模块 ==\n" + strings.Join(existing, "、"),
+		"",
+		"== 本轮新增模块 ==\n" + strings.Join(cands, "、"),
+		"",
+		"规则：to 必须**原样**取自「已有模块」；from 必须**原样**取自「本轮新增模块」；" +
+			"没有同义的输出空数组。",
+		`只输出 JSON：{"pairs":[{"from":"新增模块","to":"已有模块"}]}`,
+	}
+	text, err := call(strings.Join(prompt, "\n"), aliasSchema)
+	if err != nil {
+		return map[string]string{}
+	}
+	obj, ok := firstJSONObject(text)
+	if !ok {
+		return map[string]string{}
+	}
+	var pairs struct {
+		Pairs []struct {
+			From string `json:"from"`
+			To   string `json:"to"`
+		} `json:"pairs"`
+	}
+	if json.Unmarshal([]byte(obj), &pairs) != nil {
+		return map[string]string{}
+	}
+	out := map[string]string{}
+	for _, p := range pairs.Pairs {
+		from, to := strings.TrimSpace(p.From), strings.TrimSpace(p.To)
+		// 双向校验：模型偶尔会把 to 编一个不存在的模块名 —— 只认已有模块里的原值。
+		if from == "" || to == "" || from == to || !contains(existing, to) || !contains(cands, from) {
+			continue
+		}
+		out[from] = to
+	}
+	return out
+}
+
+// parseFeatures 从模型输出里取 features 数组。
+//
+// 容忍 markdown 围栏与前后废话（不同引擎的正文包裹方式不一样）；拿不到就报错，
+// 让上层把「不可解析」记进 state 的 last_error —— 这比静默 noop 强得多。
+func parseFeatures(text string) ([]featureOut, error) {
+	raw := strings.TrimSpace(text)
+	if obj, ok := firstJSONObject(raw); ok {
+		var wrap struct {
+			Features []featureOut `json:"features"`
+		}
+		if err := json.Unmarshal([]byte(obj), &wrap); err == nil {
+			return wrap.Features, nil
+		}
+	}
+	// 退一步：模型可能只给了数组本身。
+	if i := strings.Index(raw, "["); i >= 0 {
+		if j := strings.LastIndex(raw, "]"); j > i {
+			var arr []featureOut
+			if err := json.Unmarshal([]byte(raw[i:j+1]), &arr); err == nil {
+				return arr, nil
+			}
+		}
+	}
+	return nil, fmt.Errorf("缺少 features 数组")
+}
+
+// firstJSONObject 从文本里找首个完整的顶层 JSON 对象（去围栏、容忍前后废话）。
+func firstJSONObject(s string) (string, bool) {
+	s = stripFence(s)
+	start := strings.IndexByte(s, '{')
+	if start < 0 {
+		return "", false
+	}
+	depth, inStr, escape := 0, false, false
+	for i := start; i < len(s); i++ {
+		c := s[i]
+		if inStr {
+			switch c {
+			case '\\':
+				escape = !escape
+				continue
+			case '"':
+				if !escape {
+					inStr = false
+				}
+			}
+			escape = false
+			continue
+		}
+		switch c {
+		case '"':
+			inStr = true
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return s[start : i+1], true
+			}
+		}
+	}
+	return "", false
+}
+
+// stripFence 去掉整段 markdown 代码围栏。
+func stripFence(s string) string {
+	t := strings.TrimSpace(s)
+	if !strings.HasPrefix(t, "```") {
+		return t
+	}
+	if i := strings.IndexByte(t, '\n'); i > 0 {
+		t = t[i+1:]
+	}
+	if j := strings.LastIndex(t, "```"); j > 0 {
+		t = t[:j]
+	}
+	return strings.TrimSpace(t)
+}
+
+// writeCtx 写文档的上下文（归纳与将来的「反推」共用同一套写入口径）。
+type writeCtx struct {
+	merger    *docMerger
+	alias     map[string]string
+	kind      string
+	all       bool
+	sourcesOf func(featureOut) []string
+}
+
+// writeResult 一条增量的落盘结果。
+type writeResult struct {
+	ok          bool
+	created     bool
+	points      int
+	conclusions int
+}
+
+// writeFeatureItem 把一条增量合并进功能点文档。
+//
+// 这里埋着四个**实测踩过**的坑，处理方式逐条对应：
+//   - 同名匹配三档（模型把已有名写长再被截断会凭空多一篇）→ docMerger.match；
+//   - 同一轮里同一功能点被输出两次（会撞 slug 生成 xxx-2.md）→ 命中已有文档就原地合并；
+//   - slug 撞车（两个不同功能点截断后同名）→ usedFile 错开编号；
+//   - 占位符回吐（模型把「（暂无）」当内容）→ 写入前过滤 + RenderDoc 再滤一次。
+func writeFeatureItem(id string, out featureOut, ctx *writeCtx) writeResult {
+	name := strings.TrimSpace(truncRunes(strings.TrimSpace(out.Name), TitleMaxChars))
+	if name == "" {
+		return writeResult{}
+	}
+	hit, has := ctx.merger.match(name)
+
+	addPoints := cleanList(out.Points)
+	addConcs := cleanList(out.Conclusions)
+	addDesc := strings.TrimSpace(out.Desc)
+	if isPlaceholder(addDesc) {
+		addDesc = ""
+	}
+	if !has && addDesc == "" && len(addPoints) == 0 && len(addConcs) == 0 {
+		return writeResult{} // 只有个名字、没有内容：不写空壳
+	}
+
+	// 归属：已有文档沿用它的模块（不搬家）；只有新文档才采纳模型给的 module。
+	rawMod := SlugifyModule(out.Module)
+	if has {
+		rawMod = SlugifyModule(hit.Module)
+	}
+	if a, ok := ctx.alias[rawMod]; ok {
+		rawMod = a
+	}
+	dir := featuresDir(id)
+	if rawMod != "" {
+		dir = filepath.Join(dir, rawMod)
+	}
+	base := SlugifyFeature(name)
+	full := ""
+	if has {
+		full = hit.File
+	} else {
+		full = filepath.Join(dir, base+".md")
+		for k := 2; ctx.merger.usedFile[full]; k++ {
+			full = filepath.Join(dir, base+"-"+strconv.Itoa(k)+".md")
+		}
+	}
+	ctx.merger.usedFile[full] = true
+
+	prev := Doc{}
+	if has {
+		if b, err := os.ReadFile(hit.File); err == nil {
+			prev = ParseDoc(string(b))
+		}
+	}
+	desc := addDesc
+	if desc == "" {
+		desc = prev.Desc
+	}
+	points := mergeUnique(prev.Points, addPoints, MaxPoints, true, nil)
+	conclusions := mergeUnique(prev.Conclusions, addConcs, MaxConclusions, true, nil)
+	srcLines := []string{}
+	if ctx.sourcesOf != nil {
+		srcLines = ctx.sourcesOf(out)
+	}
+	sources := mergeUnique(prev.Sources, srcLines, MaxSources, false, sourceKey)
+
+	dPts := len(points) - len(prev.Points)
+	if dPts < 0 {
+		dPts = 0
+	}
+	dCcs := len(conclusions) - len(prev.Conclusions)
+	if dCcs < 0 {
+		dCcs = 0
+	}
+	line := todayStr() + " " + ctx.kind + "：新增需求点 " + strconv.Itoa(dPts) +
+		" 条 · 结论 " + strconv.Itoa(dCcs) + " 条"
+	if ctx.all {
+		line += "（全量重放）"
+	}
+	if len(out.Sources) > 0 {
+		parts := make([]string, 0, len(out.Sources))
+		for _, n := range out.Sources {
+			parts = append(parts, "#"+strconv.Itoa(n))
+		}
+		line += " · 来源 " + strings.Join(parts, " ")
+	}
+	logLines := mergeUnique(prev.Log, []string{line}, MaxLogLines, false, nil)
+
+	doc := Doc{
+		Final:       renderFinal(desc, conclusions),
+		Desc:        desc,
+		Points:      points,
+		Conclusions: conclusions,
+		Sources:     sources,
+		Log:         logLines,
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return writeResult{}
+	}
+	if err := os.WriteFile(full, []byte(RenderDoc(name, doc)), 0o600); err != nil {
+		return writeResult{}
+	}
+	if !has {
+		ctx.merger.add(featureFile{Module: rawMod, Name: name, File: full})
+	}
+	return writeResult{ok: true, created: !has, points: dPts, conclusions: dCcs}
+}
+
+// renderFinal 从「需求描述 + 已定结论」收敛出「最终版」。
+//
+// 不调模型：它是**派生**内容（把分散的结论收成一眼能看的定稿），
+// 而不是又一轮归纳 —— 多调一次模型只会多一份可能和需求点打架的措辞。
+func renderFinal(desc string, conclusions []string) string {
+	var b strings.Builder
+	if d := strings.TrimSpace(desc); d != "" && !isPlaceholder(d) {
+		b.WriteString("**目标**：" + d + "\n")
+	}
+	if len(conclusions) > 0 {
+		if b.Len() > 0 {
+			b.WriteString("\n")
+		}
+		b.WriteString("**已定**：\n")
+		for _, c := range conclusions {
+			b.WriteString("- " + c + "\n")
+		}
+	}
+	return strings.TrimSpace(b.String())
+}
+
+// cleanList 过滤空串与占位符。
+func cleanList(in []string) []string {
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		v := strings.TrimSpace(s)
+		if v == "" || isPlaceholder(v) {
+			continue
+		}
+		out = append(out, v)
+	}
+	return out
+}
+
+// collapseSpace 把连续空白压成单个空格（记忆 / 来源行都要单行展示）。
+func collapseSpace(s string) string { return strings.Join(strings.Fields(s), " ") }
+
+// fmtTs unix 毫秒 → 「10-22 14:30」（来源行 / 记忆清单同一口径）。
+func fmtTs(ms int64) string {
+	if ms <= 0 {
+		return "--"
+	}
+	return time.UnixMilli(ms).Format("1-02 15:04")
+}
+
+// todayStr 今天（更新记录用；日期只由代码写，模型不参与）。
+func todayStr() string { return time.Now().Format("2006-01-02") }
+
+// withError 返回一份带失败原因的状态副本。
+func withError(st state, msg string) state {
+	st.LastError = truncRunes(msg, 240)
+	return st
+}
+
+// acquireLock 取工作区归纳锁；已被占用返回 busy=true。
+//
+// 用 O_EXCL 建锁文件（原子），内容写 pid + 时间：
+// 进程被 kill 会留下锁，超过 lockStale 视为陈旧可抢占。
+func acquireLock(id string) (release func(), busy bool) {
+	f := filepath.Join(wsDir(id), "state.lock")
+	_ = os.MkdirAll(wsDir(id), 0o700)
+	if b, err := os.ReadFile(f); err == nil {
+		var o struct {
+			PID int   `json:"pid"`
+			At  int64 `json:"at"`
+		}
+		_ = json.Unmarshal(b, &o)
+		if o.At > 0 && time.Since(time.UnixMilli(o.At)) < lockStale {
+			return func() {}, true
+		}
+		_ = os.Remove(f) // 陈旧锁：抢占
+	}
+	fh, err := os.OpenFile(f, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+	if err != nil {
+		return func() {}, true // 抢不到就是有人在写
+	}
+	b, _ := json.Marshal(map[string]any{"pid": os.Getpid(), "at": time.Now().UnixMilli()})
+	_, _ = fh.Write(b)
+	_ = fh.Close()
+	return func() { _ = os.Remove(f) }, false
+}