magic-agent 2.1.5 → 2.3.2

package/internal/client/suggest.go

@@ -0,0 +1,131 @@
+package client
+
+// suggest.go - `POST /desk/suggest`：生成「下一轮快捷回复」（一轮结束后可点的下一句）。
+//
+// 为什么放在插件而不是各端自己调模型（用户 2026-10-23：「在回复结束后 ai 自动生成
+// 下一轮的建议，点击即可发送」，先给了方案、选了「B. 模型生成」）：
+//  1. 提示词与解析口径只能有一份 —— 移动端 / PC 各写一份，同一轮回答会给出不同建议；
+//  2. 模型调用要落在桌面端（引擎 CLI、凭据、配额都在那台机器上），手机只拿结果；
+//  3. **不续接当前会话**：core 的 `--suggest-followups` 是一次独立旁路调用（ToolsOff、
+//     不带 SessionID），不会把「请生成建议」这类指令写进用户正在聊的上下文。
+//
+// 与 `/desk/session/{id}/title/summarize` 同一套做法：插件 exec core，不自己实现归纳/提炼。
+// 失败一律如实回错（502/504），界面侧静默不画按钮 —— 没有建议是合法结果，不拿模板凑。
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"os/exec"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+const (
+	// suggestTimeout 单次生成的超时。界面侧 20s 就放弃（见 conversation.js），
+	// 这里留一点余量，避免「进程还没退、上下文已经被撤」的夹缝报错。
+	suggestTimeout = 25 * time.Second
+	// suggestMaxBody 请求体上限：只该带「这一轮」的问答，超了说明调用方塞了整条会话。
+	suggestMaxBody = 64 << 10
+	// suggestMaxUserRunes / suggestMaxReplyRunes 服务端兜底截断（core 还会再截一次）。
+	suggestMaxUserRunes  = 4000
+	suggestMaxReplyRunes = 16000
+)
+
+// suggestSlots 并发闸：建议是锦上添花，不能因为客户端重试/多开把引擎进程堆起来。
+// 2 = 允许「当前会话收尾」与「刚切过去的另一个会话」各一条，超出直接 429。
+var suggestSlots = make(chan struct{}, 2)
+
+// handleSuggest POST /desk/suggest。
+//
+// 请求：{"user":"用户上一句","reply":"本轮回答正文","engine":"可选","model":"可选"}
+// 响应：{"suggestions":["…", "…"], "engine":"llm", "elapsedMs":1234}
+func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	var body struct {
+		User   string `json:"user"`
+		Reply  string `json:"reply"`
+		Engine string `json:"engine"`
+		Model  string `json:"model"`
+	}
+	if r.Body != nil {
+		if err := json.NewDecoder(io.LimitReader(r.Body, suggestMaxBody)).Decode(&body); err != nil {
+			writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+truncateForMsg(err.Error()))
+			return
+		}
+	}
+	body.Reply = strings.TrimSpace(body.Reply)
+	if body.Reply == "" {
+		writeErr(w, http.StatusBadRequest, `缺少 reply（本轮回答正文）：形如 {"user":"…","reply":"…"}`)
+		return
+	}
+	body.User = clipRunes(strings.TrimSpace(body.User), suggestMaxUserRunes)
+	body.Reply = clipRunes(body.Reply, suggestMaxReplyRunes)
+
+	select {
+	case suggestSlots <- struct{}{}:
+		defer func() { <-suggestSlots }()
+	default:
+		writeErr(w, http.StatusTooManyRequests, "建议生成太频繁：上一轮还没结束，请稍后")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), suggestTimeout)
+	defer cancel()
+
+	payload, _ := json.Marshal(suggest.RequestBody{User: body.User, Reply: body.Reply})
+	args := []string{"--suggest-followups", "-"}
+	/* 引擎/模型由界面带（当前引擎一定装过）；不传则 core 用 llm（见 runSuggestFollowups）。 */
+	if e := strings.TrimSpace(body.Engine); e != "" {
+		args = append(args, "-e", e)
+	}
+	if m := strings.TrimSpace(body.Model); m != "" {
+		args = append(args, "-m", m)
+	}
+	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd.Stdin = bytes.NewReader(payload)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			writeErr(w, http.StatusGatewayTimeout, "生成建议超时（>25s）：这一轮先不给建议")
+			return
+		}
+		msg := strings.TrimSpace(stderr.String())
+		if msg == "" {
+			msg = strings.TrimSpace(stdout.String())
+		}
+		if msg == "" {
+			msg = err.Error()
+		}
+		writeErr(w, http.StatusBadGateway, "生成建议失败："+truncateForMsg(msg))
+		return
+	}
+	var res suggest.Result
+	if err := json.Unmarshal(stdout.Bytes(), &res); err != nil {
+		// core 换了输出形状就如实报错，别静默回空（那会表现成「功能时灵时不灵」）。
+		writeErr(w, http.StatusBadGateway, "core 回的建议不是 JSON："+truncateForMsg(stdout.String()))
+		return
+	}
+	if res.Suggestions == nil {
+		res.Suggestions = []string{}
+	}
+	writeJSON(w, http.StatusOK, res)
+}
+
+// clipRunes 按 rune 截断（中文不能按字节切）。
+func clipRunes(s string, max int) string {
+	if max <= 0 || utf8.RuneCountInString(s) <= max {
+		return s
+	}
+	return string([]rune(s)[:max])
+}

package/internal/client/suggest_test.go

@@ -0,0 +1,116 @@
+package client
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// fakeSuggestCore 写一个假 core 脚本：记录 argv → 吃掉 stdin → 打印一份建议 JSON。
+func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
+	t.Helper()
+	argLog := filepath.Join(dir, "args.txt")
+	p := filepath.Join(dir, "magic-agent")
+	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)
+	}
+	return p, argLog
+}
+
+func TestSuggestEndpoint(t *testing.T) {
+	dir := t.TempDir()
+	core, argLog := fakeSuggestCore(t, dir, `printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+
+	req := httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"fake-engine","model":"fake-model"}`))
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("code = %d，body=%s", rec.Code, rec.Body.String())
+	}
+	var res struct {
+		Suggestions []string `json:"suggestions"`
+		Engine      string   `json:"engine"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &res); err != nil {
+		t.Fatalf("响应不是 JSON：%v", err)
+	}
+	if len(res.Suggestions) != 2 || res.Suggestions[0] != "好的，执行吧" {
+		t.Fatalf("suggestions = %#v", res.Suggestions)
+	}
+	args, _ := os.ReadFile(argLog)
+	if !strings.Contains(string(args), "--suggest-followups -") {
+		t.Fatalf("没走 --suggest-followups：%s", args)
+	}
+	if !strings.Contains(string(args), "-e fake-engine") || !strings.Contains(string(args), "-m fake-model") {
+		t.Fatalf("引擎/模型没透传：%s", args)
+	}
+}
+
+func TestSuggestEndpointBadRequests(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":[]}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+
+	cases := []struct {
+		name string
+		req  *http.Request
+		code int
+	}{
+		{"GET 不允许", httptest.NewRequest(http.MethodGet, "/desk/suggest", nil), http.StatusMethodNotAllowed},
+		{"缺 reply", httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(`{"user":"只说了半句"}`)), http.StatusBadRequest},
+		{"非法 JSON", httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(`nope`)), http.StatusBadRequest},
+	}
+	for _, c := range cases {
+		rec := httptest.NewRecorder()
+		s.handleSuggest(rec, c.req)
+		if rec.Code != c.code {
+			t.Errorf("%s：code = %d，期望 %d（body=%s）", c.name, rec.Code, c.code, rec.Body.String())
+		}
+	}
+}
+
+func TestSuggestEndpointCoreFailure(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, "echo 'llm CLI not found' >&2\nexit 3")
+	s := &Service{opts: Options{MagicAgent: core}}
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"要我继续吗？"}`)))
+	if rec.Code != http.StatusBadGateway {
+		t.Fatalf("code = %d，期望 502", rec.Code)
+	}
+	if !strings.Contains(rec.Body.String(), "llm CLI not found") {
+		t.Fatalf("core 的失败原因没带回：%s", rec.Body.String())
+	}
+}
+
+func TestSuggestEndpointGarbageCoreOutput(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf 'not json\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"要我继续吗？"}`)))
+	if rec.Code != http.StatusBadGateway {
+		t.Fatalf("code = %d，期望 502", rec.Code)
+	}
+	if !strings.Contains(rec.Body.String(), "不是 JSON") {
+		t.Fatalf("应明确说 core 的输出不是 JSON：%s", rec.Body.String())
+	}
+}
+
+func TestClipRunes(t *testing.T) {
+	if got := clipRunes("一二三四五", 3); got != "一二三" {
+		t.Fatalf("clipRunes = %q", got)
+	}
+	if got := clipRunes("短", 10); got != "短" {
+		t.Fatalf("短文本不该变：%q", got)
+	}
+}

package/internal/requirements/consolidate.go

@@ -128,7 +128,15 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	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}
+	moduleScope := SlugifyModule(opts.Module)
+	res := Result{Workspace: ws.ID, Dir: ws.Dir, Module: moduleScope}
+
+	// 模块级整理只更新已有模块，不接受一个不存在的名字（否则模型会把新需求
+	// 塞进一个凭空的目录，用户在清单里根本找不到它）。
+	if moduleScope != "" && !contains(listModules(ws.ID), moduleScope) {
+		res.Error = "模块不存在: " + opts.Module
+		return res, fmt.Errorf("requirements: module not found: %s", opts.Module)
+	}
 
 	// 锁：同一工作区同时只允许一轮归纳（客户端防抖 + 手动「立即整理」可能撞上）。
 	release, busy := acquireLock(ws.ID)
@@ -152,8 +160,9 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	/* 首次「整理」：先按空间目录反推一版需求基线，再把旧会话记为已消费。
 	   判断依据是 state.BootstrapAt（不是文档数 / 不是 LastConsolidatedAt）：
 	   自动归纳可能已经产出过几篇文档，但「有没有按目录初始化过」是另一件事。
-	   opts.Auto 的自动路径不初始化 —— 它每轮都可能跑，不能悄悄花几分钟读代码。 */
-	if st.BootstrapAt == 0 && !opts.Auto {
+	   opts.Auto 的自动路径不初始化 —— 它每轮都可能跑，不能悄悄花几分钟读代码。
+	   模块级整理也不初始化：目录基线是空间级的，模块只做增量。 */
+	if st.BootstrapAt == 0 && !opts.Auto && moduleScope == "" {
 		boot, berr := bootstrapWorkspace(ctx, ws, opts)
 		if berr != nil {
 			res.Error = truncRunes(berr.Error(), 240)
@@ -206,8 +215,11 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	if cursor > len(mem) {
 		cursor = len(mem) // 记忆文件被外部截断 → 游标跟着收敛，不越界
 	}
+	/* 模块级整理**不重放**（--requirement-all 是空间级回填），只看游标之后的
+	   新记忆；也不推进游标，否则别的模块的需求会被这一轮悄悄吞掉。 */
+	replay := opts.All && moduleScope == ""
 	entries := mem[cursor:]
-	if opts.All {
+	if replay {
 		entries = mem
 	}
 	if len(entries) == 0 && !opts.Force {
@@ -218,7 +230,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 
 	use := entries
-	if opts.All {
+	if replay {
 		if len(use) > MaxReplayEntries {
 			use = use[len(use)-MaxReplayEntries:]
 		}
@@ -241,7 +253,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		return res, callErr
 	}
 
-	chunks := chunkEntries(use, opts.All)
+	chunks := chunkEntries(use, replay)
 	merger := newDocMerger(ws.ID)
 	byN := make(map[int]Entry, len(mem))
 	for _, e := range mem {
@@ -256,7 +268,15 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 		// 每片重新读已有文档：上一片刚写的要点必须出现在这一片的「已有需求点」里，
 		// 否则同一件事会被重复追加。
 		docs := featureDocsOf(ws.ID)
-		prompt := buildPrompt(wsName, docs, chunk, listModules(ws.ID), opts.All)
+		modules := listModules(ws.ID)
+		/* 模块级整理：只让模型看到这个模块的已有文档与模块名 ——
+		   否则它会把别的模块的新需求也一起写回来（那正是用户点的这一下
+		   「只整理一个模块」所不能接受的事）。 */
+		if moduleScope != "" {
+			docs = docsOfModule(docs, moduleScope)
+			modules = []string{moduleScope}
+		}
+		prompt := buildPrompt(wsName, docs, chunk, modules, replay, moduleScope)
 		text, err := call(prompt, outSchema)
 		res.Calls++
 		if err != nil {
@@ -276,28 +296,34 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 
 		// 新模块的同义二审：归纳是逐轮独立的，模型容易把同一件事拆成近义模块
 		//（「任务列表」/「对话列表」）。只有确认已有模块里没有同义项时才允许新建。
+		// 模块级整理不新建模块（作用域就是这个已有模块），因而也不做二审。
 		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
+		if moduleScope == "" {
+			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)
 			}
-			seenNew[m] = true
-			newMods = append(newMods, m)
-		}
-		if len(newMods) > 0 && len(existing) > 0 {
-			alias = resolveModuleAlias(call, newMods, existing)
 		}
 
 		for _, o := range outs {
+			if moduleScope != "" && !outputInModule(o, moduleScope, merger) {
+				continue
+			}
 			w := writeFeatureItem(ws.ID, o, &writeCtx{
 				merger: merger,
 				alias:  alias,
 				kind:   "归纳",
-				all:    opts.All,
+				all:    replay,
 				sourcesOf: func(x featureOut) []string {
 					out := make([]string, 0, len(x.Sources))
 					for _, n := range x.Sources {
@@ -324,7 +350,7 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 
 	consumed := cursor
-	if !opts.All {
+	if !replay && moduleScope == "" {
 		consumed = cursor + len(use)
 		if consumed > len(mem) {
 			consumed = len(mem)
@@ -339,11 +365,11 @@ func Consolidate(ctx context.Context, where string, opts Options) (Result, error
 	}
 	res.OK = true
 	res.Consumed = 0
-	if !opts.All {
+	if !replay && moduleScope == "" {
 		res.Consumed = len(use)
 	}
 	res.Replayed = 0
-	if opts.All {
+	if replay {
 		res.Replayed = len(use)
 	}
 	res.Pending = len(mem) - consumed
@@ -435,12 +461,38 @@ func featureDocsOf(id string) []existsDoc {
 	return out
 }
 
+// docsOfModule 只留某个模块下的已有功能点（模块级整理的作用域）。
+func docsOfModule(docs []existsDoc, module string) []existsDoc {
+	out := make([]existsDoc, 0, len(docs))
+	for _, d := range docs {
+		if SlugifyModule(d.Module) == module {
+			out = append(out, d)
+		}
+	}
+	return out
+}
+
+// outputInModule 一条模型增量是否属于本次模块级整理的作用域。
+//
+// 已有功能点按 name 匹配后以它**当前所属模块**为准（与 writeFeatureItem 同一口径：
+// 文档一旦归类就不搬家）；新功能点才看模型给的 module。
+func outputInModule(o featureOut, scope string, merger *docMerger) bool {
+	name := strings.TrimSpace(truncRunes(strings.TrimSpace(o.Name), TitleMaxChars))
+	if name == "" {
+		return false
+	}
+	if hit, has := merger.match(name); has {
+		return SlugifyModule(hit.Module) == scope
+	}
+	return SlugifyModule(o.Module) == scope
+}
+
 // buildPrompt 组归纳 prompt。
 //
 // 规则段是**产品口径**，不是技术参数：哪些话不能写进需求点（缺陷措辞）、
 // 什么样的模块必须复用、结论与问题的界限。这些是业务项目半年里一条条纠正出来的，
 // 换实现时原样保留，别按自己的口味重写。
-func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []string, replay bool) string {
+func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []string, replay bool, scope string) string {
 	mods := make([]string, 0, len(modules))
 	for _, m := range modules {
 		if strings.TrimSpace(m) != "" {
@@ -531,9 +583,19 @@ func buildPrompt(wsName string, docs []existsDoc, entries []Entry, modules []str
 			"desc 可用记忆重新校核改写（这是唯一允许改写 desc 的场景），" +
 			"需求点/结论里已有的一字不改照抄、缺的补上。"
 	}
+	/* 模块级整理：模型只该动这一个模块。必须写清楚「别的记忆忽略」——
+	   否则它会把整段对话重新归类，用户点一个模块却把别的模块也改了。 */
+	if scope != "" {
+		rules[0] = "0. **本次只整理模块「" + scope + "」**：只输出属于这个模块的功能点" +
+			"（新功能点的 module 必须逐字写「" + scope + "」，已有功能点沿用它的 name）。" +
+			"不属于这个模块的记忆**一律忽略** —— 它们会在「整理整个空间」时处理。"
+	}
 
 	var b strings.Builder
 	b.WriteString("你是资深产品经理，负责把「对话记忆」归纳成**两级**功能点需求文档的**增量**。工作区：" + wsName + "\n\n")
+	if scope != "" {
+		b.WriteString("【模块级整理】本次作用域：模块「" + scope + "」。\n\n")
+	}
 	b.WriteString("== 已有模块（大功能点 · 一级）==\n")
 	if len(mods) == 0 {
 		b.WriteString("（暂无模块，可新建）")

package/internal/requirements/requirements.go

@@ -127,6 +127,13 @@ type Options struct {
 	Engine string
 	// Model 归纳用哪个模型（空 = 引擎默认）。
 	Model string
+	// Module 只整理这个模块（空 = 整个空间）。
+	//
+	// 语义：只把「属于该模块」的增量写回该模块，**不推进空间游标** ——
+	// 其它模块的记忆仍留在 pending，等空间级「整理」或下一次自动归纳处理。
+	// 因此模块级整理是「只增不减、可重复跑」的，不会吞掉别的模块的需求。
+	// ⚠️ 它不会触发首次目录初始化（目录基线天然是空间级的）。
+	Module string
 	// Timeout 单次调用超时（0 = 归纳 240s；首次目录初始化 9m）。
 	Timeout time.Duration
 	// Auto 自动归纳（插件的轮末防抖 / 每日兜底）。
@@ -141,6 +148,8 @@ type Result struct {
 	// Workspace / Dir 归纳的是哪个工作区。
 	Workspace string `json:"workspace,omitempty"`
 	Dir       string `json:"dir"`
+	// Module 这一轮只整理了哪个模块（空 = 整个空间）。
+	Module string `json:"module,omitempty"`
 	// Noop 没有未归纳记忆、也没要求强制跑（等于什么都没做，不是错）。
 	Noop bool `json:"noop,omitempty"`
 	// Bootstrap 这一轮是否完成了首次初始化。

package/internal/requirements/requirements_test.go

@@ -326,6 +326,27 @@ func TestWorkspacesGroupsAndSorts(t *testing.T) {
 	}
 }
 
+// TestResolveWorkspaceByID 按 ws id 也能解析（客户端手里可能只有 id、没有目录）。
+//
+// 老实现的 safeID 把前缀 `ws-` 里的 w/s 也按十六进制校验，任何 id 都过不了：
+// `--consolidate-requirements ws-xxxx` 直接报「工作区不存在」。
+func TestResolveWorkspaceByID(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-id")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	e := registerWorkspace(proj)
+	got, ok := resolveWorkspace(e.ID)
+	if !ok || got.ID != e.ID || got.Dir != proj {
+		t.Fatalf("按 id 应解析出 %s/%s，实际 %+v ok=%v", e.ID, proj, got, ok)
+	}
+	// 路径穿越仍要被挡住。
+	if safeID("ws-../../etc") || safeID("ws-") || safeID("x-ws-1") {
+		t.Error("非法 id 必须被拒绝")
+	}
+}
+
 // TestConsolidatePipeline 走完整链路：摄入 → prompt → 模型输出 → 合并 → 游标前进。
 // 模型用假调用器（真实归纳的网络/CLI 由真机验收覆盖），验的是代码这一侧。
 func TestConsolidatePipeline(t *testing.T) {
@@ -411,6 +432,114 @@ func TestConsolidatePipeline(t *testing.T) {
 	}
 }
 
+// TestConsolidateModuleScope 模块级整理只动这个模块，且不推进空间游标。
+//
+// 用户 2026-10-23 报障：「点需求的一个模块的整理却触发了所有的整理」。
+// 这里钉住三件事：
+//   - 模型只看到这个模块的已有文档（看不到别的模块，才不会把别的模块也改了）；
+//   - 模型即使输出别的模块的增量，也不落盘；
+//   - 空间游标不动 —— 别的模块的需求留给空间级整理，不能被这一下吞掉。
+func TestConsolidateModuleScope(t *testing.T) {
+	root := testEnv(t)
+	proj := filepath.Join(root, "proj-module")
+	if err := os.MkdirAll(proj, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeSessionLog(t, session.Dir(), "s-mod", proj, "手机号登录要加验证码", "购物车要支持结算")
+
+	id := DirID(proj)
+	merger := newDocMerger(id)
+	wctx := &writeCtx{merger: merger, kind: "归纳"}
+	for _, o := range []featureOut{
+		{Module: "登录", Name: "手机号登录", Points: []string{"手机号可登录"}},
+		{Module: "支付", Name: "购物车结算", Points: []string{"购物车可结算"}},
+	} {
+		if w := writeFeatureItem(id, o, wctx); !w.ok {
+			t.Fatalf("预置文档失败: %+v", w)
+		}
+	}
+	// 已初始化 + 游标 0：模拟「有一批待整理记忆，已过了首次目录初始化」。
+	if err := writeState(id, state{BootstrapAt: time.Now().UnixMilli(), Sessions: map[string]memCursor{}}); err != nil {
+		t.Fatal(err)
+	}
+
+	old := newCaller
+	defer func() { newCaller = old }()
+	var prompts []string
+	newCaller = func(ctx context.Context, engineName, model string, timeout time.Duration) (llmCall, error) {
+		return func(prompt string, schema *agent.JSONSchema) (string, error) {
+			prompts = append(prompts, prompt)
+			return `{"features":[
+				{"module":"登录","name":"手机号登录","points":["支持验证码登录"],"sources":[1]},
+				{"module":"支付","name":"购物车结算","points":["支持优惠券"],"sources":[2]}
+			]}`, nil
+		}, nil
+	}
+
+	res, err := Consolidate(context.Background(), proj, Options{Module: "登录"})
+	if err != nil {
+		t.Fatalf("模块级整理失败: %v", err)
+	}
+	if !res.OK || res.Module != "登录" {
+		t.Fatalf("结果应标明模块级整理: %+v", res)
+	}
+	if res.Consumed != 0 {
+		t.Errorf("模块级整理不该推进游标，实际 consumed=%d", res.Consumed)
+	}
+	if st := readState(id); st.Consumed != 0 {
+		t.Errorf("state 游标不该被模块级整理推进，实际 %d", st.Consumed)
+	}
+	if res.Updated != 1 || res.Created != 0 {
+		t.Errorf("只该更新登录模块的 1 篇，实际 %+v", res)
+	}
+	if len(prompts) != 1 {
+		t.Fatalf("应只调 1 次模型，实际 %d", len(prompts))
+	}
+	if !strings.Contains(prompts[0], "本次只整理模块「登录」") || !strings.Contains(prompts[0], "【模块级整理】") {
+		t.Errorf("prompt 应写明模块作用域:\n%s", prompts[0])
+	}
+	if strings.Contains(prompts[0], "购物车结算") || strings.Contains(prompts[0], "[模块 支付]") {
+		t.Errorf("prompt 不该带出别的模块的文档:\n%s", prompts[0])
+	}
+
+	moduleOf := func(name string) (string, Doc) {
+		for _, f := range listFeatureFiles(id) {
+			if f.Name == name {
+				return f.Module, ParseDoc(readFile(t, f.File))
+			}
+		}
+		t.Fatalf("找不到文档 %s", name)
+		return "", Doc{}
+	}
+	if mod, d := moduleOf("手机号登录"); mod != "登录" || !contains(d.Points, "支持验证码登录") {
+		t.Errorf("登录模块应收到本模块增量，实际［%s］%+v", mod, d.Points)
+	}
+	if _, d := moduleOf("购物车结算"); len(d.Points) != 1 || contains(d.Points, "支持优惠券") {
+		t.Errorf("别的模块不该被模块级整理改动，实际 %+v", d.Points)
+	}
+
+	// 空间级整理仍应消费这批记忆：两个模块都更新，游标前进。
+	res2, err := Consolidate(context.Background(), proj, Options{})
+	if err != nil {
+		t.Fatalf("空间级整理失败: %v", err)
+	}
+	if res2.Consumed != 2 || res2.Updated != 2 {
+		t.Errorf("空间级整理应消费 2 条并更新 2 篇，实际 %+v", res2)
+	}
+	if st := readState(id); st.Consumed != 2 {
+		t.Errorf("空间级整理后游标应为 2，实际 %d", st.Consumed)
+	}
+	if _, d := moduleOf("购物车结算"); !contains(d.Points, "支持优惠券") {
+		t.Errorf("空间级整理应补上支付模块的增量，实际 %+v", d.Points)
+	}
+
+	// 不存在的模块要明确报错，不能凭空建目录。
+	if _, err := Consolidate(context.Background(), proj, Options{Module: "不存在"}); err == nil ||
+		!strings.Contains(err.Error(), "module not found") {
+		t.Errorf("不存在的模块应报错，实际 %v", err)
+	}
+}
+
 // TestConsolidateBootstrapsOnceThenIncremental 首次「整理」按目录反推，之后只处理新会话。
 //
 // 这是 2026-10-22 用户口径的代码化：

package/internal/requirements/store.go

@@ -77,11 +77,19 @@ func registryFile() string { return filepath.Join(Root(), "workspaces.json") }
 
 // safeID 工作区 id 会拼进路径 → 只放行本包生成过的形状（挡目录穿越）。
 func safeID(id string) bool {
-	if !strings.HasPrefix(id, "ws-") || len(id) > 40 {
+	const prefix = "ws-"
+	if !strings.HasPrefix(id, prefix) || len(id) > 40 {
 		return false
 	}
-	for _, r := range id {
-		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || r == '-' {
+	// 前缀 `ws-` 本身含 w/s，不能拿去跑十六进制校验（老实现的循环把整个 id
+	// 都按 [0-9a-f-] 过滤，于是任何 ws id 都过不了 —— 按 id 整理 workspace
+	// 会报「工作区不存在」）。只校验前缀之后的部分。
+	rest := strings.TrimPrefix(id, prefix)
+	if rest == "" {
+		return false
+	}
+	for _, r := range rest {
+		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') {
 			continue
 		}
 		return false