magic-agent 1.0.46 → 1.0.108

package/internal/requirements/memory.go

@@ -0,0 +1,324 @@
+package requirements
+
+// memory.go - 记忆流：把**会话里的用户原话**增量收进工作区记忆。
+//
+// 与业务项目那份的区别（本包的核心改动）：记忆不再由客户端在发问时埋点写
+// memory.jsonl，而是 core 自己从会话事件日志里读 `kind:"user"`（见
+// internal/cli/sessionlog.go 的落盘口径）。于是：
+//
+//	· 谁发起的会话都算 —— PC / 移动端 / 直接跑 CLI 的；
+//	· 不需要任何客户端配合，功能是 core 的标准能力；
+//	· 追问轮次天然带上（每条 user 事件各算一条记忆）。
+//
+// 增量靠**字节偏移**而不是 seq：日志只追加，偏移是最便宜的续读游标（seek 即读，
+// 与文件总长无关）。seq 也记着，仅用于「记忆 → 来源」的引用与排障。
+// ⚠️ 文件被截断（删会话后重建同名）时偏移会大于文件大小 —— 此时从头重读，
+// 代价只有一次。
+
+import (
+	"bufio"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/session"
+)
+
+// memCursor 一条会话的摄入游标。
+type memCursor struct {
+	// Seq 已摄入到的最大事件 seq（只用于引用与排障）。
+	Seq uint64 `json:"seq,omitempty"`
+	// Offset 已摄入到的字节偏移（续读用；日志只追加，所以它是可靠的）。
+	Offset int64 `json:"offset,omitempty"`
+}
+
+// logEvent 只解我们关心的字段（日志里其它字段一概不管）。
+type logEvent struct {
+	Seq       uint64 `json:"seq"`
+	Kind      string `json:"kind"`
+	Text      string `json:"text"`
+	At        string `json:"at"`
+	SessionID string `json:"session_id"`
+}
+
+// sessionDirFor 一条登记记录归属的目录。
+//
+// 两条来源，优先显式工作目录：
+//   - Workspace：调用方 `-w/--workspace` 指定的（引擎真正干活的目录）；
+//   - Cwd：**没有** -w 时那条会话实际跑的目录（core 在 Begin 时记下）。
+//
+// 都没有 → 空（不归属任何工作区：宁可漏掉，也不要把它塞进一个错的目录）。
+func sessionDirFor(r session.Record) string {
+	if d := strings.TrimSpace(r.Workspace); d != "" {
+		return normalizeDir(d)
+	}
+	return normalizeDir(r.Cwd)
+}
+
+// ingest 把「该目录下所有会话的新 user 事件」补进记忆流。
+//
+// 返回新增条数。不做并发保护 —— 调用方（Consolidate）已持有工作区锁。
+func ingest(wsID string, dir string, st *state) (int, error) {
+	recs, err := session.List()
+	if err != nil {
+		return 0, err
+	}
+	// 日志目录与 core 落盘时同一份（session.Dir 认 MAGIC_AGENT_SESSIONS，
+	// 默认 ~/.magic-agent/sessions）—— 用 DefaultLogDir 会绕开环境变量，
+	// 单测与「换一套数据」时就找不到日志了。
+	logDir := session.Dir()
+	added := 0
+	memN := len(readMemory(wsID))
+	pending := []Entry{}
+	for _, r := range recs {
+		if sessionDirFor(r) != dir {
+			continue
+		}
+		key := strings.TrimSpace(r.SessionID)
+		if key == "" {
+			key = strings.TrimSpace(r.RunID)
+		}
+		if key == "" {
+			continue
+		}
+		// 日志名可能是 session_id，也可能是 run_id（引擎没吐 id 时先按 run_id 落盘）。
+		logID := session.ResolveLogID(logDir, key)
+		if logID == "" {
+			continue
+		}
+		cur := st.Sessions[key]
+		evs, endOff, maxSeq, err := readUserEvents(filepath.Join(logDir, logID+".jsonl"), cur.Offset)
+		if err != nil {
+			continue // 读不动这一条不影响别的会话（记忆是尽力而为）
+		}
+		for _, ev := range evs {
+			text := strings.TrimSpace(ev.Text)
+			if text == "" {
+				continue
+			}
+			if len([]rune(text)) > MaxMemoryChars {
+				text = string([]rune(text)[:MaxMemoryChars])
+			}
+			memN++
+			pending = append(pending, Entry{
+				N:       memN,
+				Ts:      parseLogTime(ev.At),
+				Session: key,
+				Seq:     ev.Seq,
+				Title:   sessionTitle(r),
+				Text:    strings.Join(strings.Fields(text), " "),
+			})
+			added++
+		}
+		if endOff != cur.Offset || maxSeq > cur.Seq {
+			seq := cur.Seq
+			if maxSeq > seq {
+				seq = maxSeq
+			}
+			st.Sessions[key] = memCursor{Seq: seq, Offset: endOff}
+		}
+	}
+	if added > 0 {
+		if err := appendMemory(wsID, pending); err != nil {
+			return 0, err
+		}
+	}
+	return added, nil
+}
+
+// sessionTitle 一条会话的展示标题（归纳过的用归纳结果，否则回落提示词开头）。
+//
+// 记忆里带标题只是给 prompt 一点上下文（「(任务: xxx)」）—— 需求标题本身由模型归纳，
+// 不拿会话标题当需求标题：会话标题说的是「这一轮在做什么」，需求标题说的是「这个功能
+// 应当是什么样」。
+func sessionTitle(r session.Record) string {
+	if t := session.TitleForAny(r.SessionID, r.RunID); t != "" {
+		return t
+	}
+	return strings.TrimSpace(r.PromptHead)
+}
+
+// readUserEvents 从 offset 起读日志，返回新出现的 user 事件、新偏移、最大 seq。
+//
+// offset 越过文件末尾（日志被截断 / 重建）→ 从头读：宁可重放一次，也不要永久漏掉。
+func readUserEvents(path string, offset int64) ([]logEvent, int64, uint64, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, offset, 0, nil
+		}
+		return nil, offset, 0, err
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil {
+		return nil, offset, 0, err
+	}
+	size := st.Size()
+	if offset > size {
+		offset = 0
+	}
+	if _, err := f.Seek(offset, 0); err != nil {
+		return nil, offset, 0, err
+	}
+	var out []logEvent
+	var maxSeq uint64
+	pos := offset
+	rd := bufio.NewReaderSize(f, 64*1024)
+	for {
+		line, err := rd.ReadString('\n')
+		if line != "" {
+			// 末尾半行（还没写完换行）不算：下次从这一行的起点重读，不能推进偏移。
+			if !strings.HasSuffix(line, "\n") {
+				break
+			}
+			pos += int64(len(line))
+			trimmed := strings.TrimSpace(line)
+			if trimmed != "" {
+				var ev logEvent
+				if json.Unmarshal([]byte(trimmed), &ev) == nil {
+					if ev.Seq > maxSeq {
+						maxSeq = ev.Seq
+					}
+					if ev.Kind == "user" {
+						out = append(out, ev)
+					}
+				}
+			}
+		}
+		if err != nil {
+			break
+		}
+	}
+	return out, pos, maxSeq, nil
+}
+
+// parseLogTime 日志里的 at 是 RFC3339；解不出来用当前时间（时间只用于展示）。
+func parseLogTime(s string) int64 {
+	if t, err := time.Parse(time.RFC3339Nano, strings.TrimSpace(s)); err == nil {
+		return t.UnixMilli()
+	}
+	return time.Now().UnixMilli()
+}
+
+// Workspaces 列出所有工作区及其需求聚合状态。
+//
+// 两个来源合并：① 注册表（有文档、可能已没有会话）② 会话侧反推的目录（有会话但还没
+// 归纳过）。后者也要出现 —— 否则用户看不到「这个目录已经聊了几句、还没成文档」。
+func Workspaces() ([]Workspace, error) {
+	seen := map[string]workspaceEntry{}
+	for _, e := range readRegistry() {
+		seen[e.ID] = e
+	}
+	recs, _ := session.List()
+	for _, r := range recs {
+		d := sessionDirFor(r)
+		if d == "" {
+			continue
+		}
+		id := DirID(d)
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; !ok {
+			seen[id] = workspaceEntry{ID: id, Dir: d, Name: filepath.Base(d)}
+		}
+	}
+	out := make([]Workspace, 0, len(seen))
+	for _, e := range seen {
+		st := readState(e.ID)
+		mem := readMemory(e.ID)
+		w := Workspace{
+			ID:                 e.ID,
+			Dir:                e.Dir,
+			Name:               e.Name,
+			Memory:             len(mem),
+			Pending:            max(0, len(mem)-st.Consumed),
+			Initialized:        st.BootstrapAt > 0,
+			LastConsolidatedAt: st.LastConsolidatedAt,
+			LastError:          st.LastError,
+			Modules:            groupModules(e.ID),
+		}
+		for _, m := range w.Modules {
+			w.FeatureCount += len(m.Features)
+		}
+		if w.Name == "" {
+			w.Name = e.ID
+		}
+		out = append(out, w)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].LastConsolidatedAt != out[j].LastConsolidatedAt {
+			return out[i].LastConsolidatedAt > out[j].LastConsolidatedAt
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out, nil
+}
+
+// groupModules 按模块分组的功能点清单（未归类的 module 为空串，排在最后）。
+func groupModules(id string) []Module {
+	files := listFeatureFiles(id)
+	idx := map[string]int{}
+	out := []Module{}
+	for _, f := range files {
+		i, ok := idx[f.Module]
+		if !ok {
+			i = len(out)
+			idx[f.Module] = i
+			out = append(out, Module{Name: f.Module})
+		}
+		out[i].Features = append(out[i].Features, featureSummary(f))
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if (out[i].Name == "") != (out[j].Name == "") {
+			return out[j].Name == ""
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// featureSummary 读一篇文档，给出卡片需要的展示口径。
+//
+// 为什么带「首条结论」而不只是条数：这一页最该被看见的是**归纳出来的结论**，
+// 只给条数的话，用户还是只能看到「记录了多少条」。
+func featureSummary(f featureFile) Feature {
+	item := Feature{Module: f.Module, Name: f.Name, File: f.File}
+	if st, err := os.Stat(f.File); err == nil {
+		item.Bytes = st.Size()
+		item.UpdatedAt = st.ModTime().UnixMilli()
+	}
+	b, err := os.ReadFile(f.File)
+	if err != nil {
+		return item
+	}
+	d := ParseDoc(string(b))
+	item.Desc = d.Desc
+	item.Points = len(d.Points)
+	item.Conclusions = len(d.Conclusions)
+	item.Sources = len(d.Sources)
+	item.HasFinal = strings.TrimSpace(d.Final) != ""
+	if len(d.Conclusions) > 0 {
+		item.Conclusion = d.Conclusions[0]
+	}
+	for _, line := range strings.Split(d.Final, "\n") {
+		v := strings.TrimSpace(line)
+		if v == "" || (strings.HasPrefix(v, "**") && strings.HasSuffix(v, "**")) || isPlaceholder(v) {
+			continue
+		}
+		item.FinalPreview = truncRunes(v, 140)
+		break
+	}
+	return item
+}
+
+func max(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}

package/internal/requirements/requirements.go

@@ -0,0 +1,169 @@
+// Package requirements - 「根据会话自动聚合成需求」的 core 侧唯一实现。
+//
+// 能力从业务项目（掌天瓶 / magic-test 的 desktop/requirements.cjs）收进 core
+// （用户 2026-10-22：「将 magic-test 过程已实现的根据会话自动聚合成需求的功能变成
+// magic-agent 的标准能力」）。收进来而不是让每个客户端各写一份的理由，与「会话标题」
+// 「会话状态」同源：同一件事在两处实现，迟早在「归到哪个功能点」「哪份优先」上分叉。
+//
+// 与业务项目那份的两处**实质差异**（不是搬家，是修正）：
+//
+//	① 记忆来源改成 core 自己的会话数据 —— 不再要求客户端在发问时埋点写 memory.jsonl。
+//	   core 本来就把每条会话的用户提问落在 <dir>/<session_id>.jsonl 的 kind:"user" 事件里
+//	   （见 internal/cli/sessionlog.go），这里按会话增量读它即可。于是「谁发起的会话」
+//	   不影响聚合：PC / 移动端 / 直接跑 CLI 的会话一视同仁。
+//	   归属用「登记表里的 workspace，空则用那条会话的 cwd」（见 session.Record.Cwd）——
+//	   不指定 -w 的会话也要能归到它实际跑的那个目录。
+//
+//	② 记忆编号（#N）是**单调追加**的，游标按条数前进就是安全的。业务项目那份的游标
+//	   也按条数，但续跑旧会话时记忆会插进时间序中间 —— 顺序假设不成立。这里的记忆流
+//	   只由本包 append（按新会话/新事件追加），编号一旦给出就不再变。
+//
+// 存储（~/.magic-agent/requirements/，可用 MAGIC_AGENT_REQUIREMENTS 覆盖）：
+//
+//	workspaces.json               工作区注册表（目录 ↔ ws id，给「没有会话也在列表里」用）
+//	<wsid>/state.json             归纳游标 + 每会话已读到的 seq + 最后归纳时间/错误
+//	<wsid>/memory.jsonl           记忆流（一行一条 {n,ts,session,seq,text}，追加型）
+//	<wsid>/features/<模块>/<名>.md 功能点需求文档（一人一篇，用户要能在访达里直接打开）
+//
+// 为什么文档不塞进数据库：一个功能点一份 markdown、用户要直接打开看，这是产品形态；
+// 而 core 至今零原生依赖（无 CGO / 无 sqlite 驱动），也不该为这件事引入一个。
+package requirements
+
+import "time"
+
+// 归纳输入的硬上限（防 prompt 爆炸，与业务项目同一口径）。
+const (
+	// MaxEntriesPerRun 单轮增量归纳最多消费的记忆条数。
+	MaxEntriesPerRun = 80
+	// MaxReplayEntries 全量重放最多回看的历史条数。
+	MaxReplayEntries = 400
+	// ReplayChunk 全量重放每片喂给模型的条数（分片是因为一次要模型输出太多会被截断）。
+	ReplayChunk = 20
+	// MaxMemoryChars 单条记忆入库截断。
+	MaxMemoryChars = 2000
+)
+
+// 文档各段的合并上限（增量累积，不整篇重写）。
+//
+// 需求点 / 结论保留最早的（清单要稳定，后来者补在尾部）；来源 / 更新记录保留最新的
+// （证据与流水越新越有用）。
+const (
+	MaxPoints      = 40
+	MaxConclusions = 20
+	MaxSources     = 30
+	MaxLogLines    = 10
+)
+
+// SourceChars 「来源对话」里每条原话的截断长度。
+const SourceChars = 60
+
+// TitleMaxChars 功能点名称的硬上限（汉字个数）。
+const TitleMaxChars = 10
+
+// ModuleMaxChars 模块（大功能点）名硬上限。
+const ModuleMaxChars = 6
+
+// Feature 一个功能点（= 一篇文档）在清单里的展示口径。
+type Feature struct {
+	// Module 所属模块（大功能点）；空 = 未归类（平铺目录里的老数据）。
+	Module string `json:"module"`
+	// Name 功能点名称（= 文档文件名）。
+	Name string `json:"name"`
+	// File 文档绝对路径（客户端点开就是它）。
+	File      string `json:"file"`
+	Bytes     int64  `json:"bytes"`
+	UpdatedAt int64  `json:"updated_at"`
+	// Desc 一句话需求描述（文档「需求描述」段）。
+	Desc string `json:"desc,omitempty"`
+	// Points / Conclusions 需求点与已定结论的条数（卡片上的「归纳成果」）。
+	Points      int `json:"points"`
+	Conclusions int `json:"conclusions"`
+	// Conclusion 首条结论（卡片上直接露出：有结论才说明真归纳过）。
+	Conclusion string `json:"conclusion,omitempty"`
+	// Sources 来源对话条数。
+	Sources int `json:"sources"`
+	// HasFinal 有没有生成过「最终版」。
+	HasFinal bool `json:"has_final"`
+	// FinalPreview 最终版的第一句实质内容（卡片头条）。
+	FinalPreview string `json:"final_preview,omitempty"`
+}
+
+// Module 一个模块（两级结构的一级）及其下的功能点。
+type Module struct {
+	Name     string    `json:"name"`
+	Features []Feature `json:"features"`
+}
+
+// Workspace 一个工作区的需求聚合状态。
+type Workspace struct {
+	ID   string `json:"id"`
+	Dir  string `json:"dir"`
+	Name string `json:"name"`
+	// Pending 还没被归纳的记忆条数。
+	Pending int `json:"pending"`
+	// Memory 记忆流总条数。
+	Memory int `json:"memory"`
+	// Modules 按模块分好组的功能点（未归类的 module 为空串，排在最后）。
+	Modules []Module `json:"modules"`
+	// FeatureCount 功能点总数。
+	FeatureCount int `json:"feature_count"`
+	// Initialized 是否已完成首次「按空间目录反推需求基线」。
+	// false = 下一次手动「整理」会先扫目录生成基线，而不是只消费新会话。
+	Initialized bool `json:"initialized"`
+	// LastConsolidatedAt 最后一次归纳完成的时刻（unix 毫秒，0 = 还没归纳过）。
+	LastConsolidatedAt int64 `json:"last_consolidated_at"`
+	// LastError 上一次归纳失败的原因（空 = 正常）。
+	LastError string `json:"last_error,omitempty"`
+}
+
+// Options 归纳选项。
+type Options struct {
+	// Force 没有未归纳记忆也跑一轮（手动「立即整理」）。
+	Force bool
+	// All 全量重放：忽略游标把历史记忆整体重放一遍（回填 / 滚动校正）。
+	// ⚠️ 仍然走同一套增量合并（只增不减），不会推翻已有内容。
+	All bool
+	// Engine 归纳用哪个引擎（空 = llm：纯文本、不带工具）。
+	Engine string
+	// Model 归纳用哪个模型（空 = 引擎默认）。
+	Model string
+	// Timeout 单次调用超时（0 = 归纳 240s；首次目录初始化 9m）。
+	Timeout time.Duration
+	// Auto 自动归纳（插件的轮末防抖 / 每日兜底）。
+	// 自动路径**不会**触发首次目录初始化：它可能每轮都跑，不能悄悄花几分钟读代码。
+	// 用户手动「整理」（--consolidate-requirements）不传这个标记，于是首次点击会初始化。
+	Auto bool
+}
+
+// Result 一轮归纳的结果（CLI 输出 / HTTP 响应共用）。
+type Result struct {
+	OK bool `json:"ok"`
+	// Workspace / Dir 归纳的是哪个工作区。
+	Workspace string `json:"workspace,omitempty"`
+	Dir       string `json:"dir"`
+	// Noop 没有未归纳记忆、也没要求强制跑（等于什么都没做，不是错）。
+	Noop bool `json:"noop,omitempty"`
+	// Bootstrap 这一轮是否完成了首次初始化。
+	// 目录为空 / 没识别到功能点也算（标记已落盘，用户点过就该有反馈）。
+	Bootstrap bool `json:"bootstrap,omitempty"`
+	// BootstrapEngine 初始化用的引擎（Bootstrap=true 时有值）。
+	BootstrapEngine string `json:"bootstrap_engine,omitempty"`
+	// Scanned 初始化扫描到的目录条目数（排障用）。
+	Scanned int `json:"scanned,omitempty"`
+	// Updated / Created 本轮更新 / 新建的功能点篇数。
+	Updated int `json:"updated"`
+	Created int `json:"created"`
+	// Points / Conclusions 本轮新增的需求点与结论条数。
+	Points      int `json:"points"`
+	Conclusions int `json:"conclusions"`
+	// Consumed 本轮消费的记忆条数（All 模式下为 0：重放不动游标）。
+	Consumed int `json:"consumed"`
+	// Replayed 全量重放实际重放的历史条数。
+	Replayed int `json:"replayed,omitempty"`
+	// Calls 本轮实际调了几次 LLM（分片）。
+	Calls int `json:"calls"`
+	// Pending 归纳完还剩多少条未归纳。
+	Pending int `json:"pending"`
+	// Error 失败原因（OK=false 时有值）。
+	Error string `json:"error,omitempty"`
+}