magic-agent 1.0.49 → 1.0.108

package/internal/requirements/doc.go

@@ -0,0 +1,473 @@
+package requirements
+
+// doc.go - 功能点文档的**骨架**：解析 / 合并 / 渲染。
+//
+// 骨架由代码维护，模型只给**增量**（业务项目 2026-09-19 改造的结论，这里原样继承）：
+//
+//	· 让模型输出整篇 markdown 时，文档会随每轮归纳被重写，越长越容易丢尾巴
+//	  （喂进去的旧文档还得截断），「来源对话」也会退化成模型摘抄的当轮一条；
+//	· 把骨架与证据交给代码之后，模型只负责它擅长的三件事：要点化（desc / points）、
+//	  结论提炼（conclusions）、来源引用（sources 用记忆编号），日期与段落顺序都由代码定。
+//
+// 六个段落与顺序（业务项目定稿）：最终版置于顶部 —— 读者先看「这个功能点最终要做什么」，
+// 往下才是逐轮累积的证据。空段写「（暂无）」占位，不留半截文件；但**渲染出口会再滤一次
+// 占位符**（模型会把看到的「（暂无）」当内容回吐，实测踩过）。
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"unicode"
+)
+
+// docSections 骨架的六个段落名（顺序即 renderDoc 的写盘顺序）。
+var docSections = []string{"最终版", "需求描述", "需求点", "已定结论", "来源对话", "更新记录"}
+
+// Doc 一篇功能点文档的解析结果。
+type Doc struct {
+	// Final 「最终版」整段（多行 markdown，原样保留 —— 里面可能有 **目标** 这类小标题，
+	// 按行拆成数组会把小标题当成一条要点）。
+	Final       string
+	Desc        string
+	Points      []string
+	Conclusions []string
+	Sources     []string
+	Log         []string
+}
+
+// isPlaceholder 占位符判定：整条就等于占位符的一律丢弃。
+//
+// 为什么要它：空段写「（暂无）」是为了文档不留半截，但模型会把看到的「（暂无）」
+// 当成一条内容回吐（于是文档里出现 `- （暂无）`）。
+func isPlaceholder(s string) bool {
+	t := strings.TrimSpace(s)
+	t = strings.Trim(t, "（）()【】[] ")
+	switch strings.ToLower(t) {
+	case "", "暂无", "无", "none", "n/a", "na", "待补充", "待定", "待确认", "暂无内容", "待生成":
+		return true
+	}
+	return false
+}
+
+// ParseDoc 解析已有文档 → Doc。只认我们自己写的骨架（## 段名），认不出的段落忽略
+// （不猜、不迁移 —— 猜错会把别人的内容搅乱）。
+func ParseDoc(text string) Doc {
+	buf := make(map[string][]string, len(docSections))
+	cur := ""
+	for _, raw := range strings.Split(text, "\n") {
+		line := strings.TrimSpace(raw)
+		if strings.HasPrefix(line, "## ") {
+			name := strings.TrimSpace(strings.TrimPrefix(line, "## "))
+			if contains(docSections, name) {
+				cur = name
+			} else {
+				cur = ""
+			}
+			continue
+		}
+		if strings.HasPrefix(line, "# ") {
+			cur = "" // H1 标题不属任何段
+			continue
+		}
+		if cur == "" || line == "" {
+			continue
+		}
+		buf[cur] = append(buf[cur], line)
+	}
+	lines := func(k string) []string {
+		out := make([]string, 0, len(buf[k]))
+		for _, l := range buf[k] {
+			v := stripListMarker(l)
+			if v == "" || isPlaceholder(v) {
+				continue
+			}
+			out = append(out, v)
+		}
+		return out
+	}
+	final := strings.TrimSpace(strings.Join(buf["最终版"], "\n"))
+	if isPlaceholder(final) {
+		final = ""
+	}
+	return Doc{
+		Final:       final,
+		Desc:        strings.TrimSpace(strings.Join(buf["需求描述"], " ")),
+		Points:      lines("需求点"),
+		Conclusions: lines("已定结论"),
+		Sources:     lines("来源对话"),
+		Log:         lines("更新记录"),
+	}
+}
+
+// stripListMarker 去掉行首的列表标记（`1. ` / `- ` / `* ` / `1、`）。
+func stripListMarker(l string) string {
+	s := strings.TrimSpace(l)
+	if s == "" {
+		return ""
+	}
+	if strings.HasPrefix(s, "- ") || strings.HasPrefix(s, "* ") || strings.HasPrefix(s, "+ ") {
+		return strings.TrimSpace(s[2:])
+	}
+	i := 0
+	for i < len(s) && s[i] >= '0' && s[i] <= '9' {
+		i++
+	}
+	if i > 0 && i < len(s) {
+		rest := s[i:]
+		for _, p := range []string{". ", "、", ") ", "）"} {
+			if strings.HasPrefix(rest, p) {
+				return strings.TrimSpace(rest[len(p):])
+			}
+		}
+	}
+	return s
+}
+
+// RenderDoc 渲染功能点文档（六段固定；空段写「（暂无）」，不留半截文件）。
+//
+// 渲染前再滤一次占位符：这是**唯一的落盘出口**，把过滤收在这里，任何上游
+// （模型回吐 / 历史残留 / 解析）漏进来的「（暂无）」都写不出去。
+func RenderDoc(name string, d Doc) string {
+	clean := func(a []string) []string {
+		out := make([]string, 0, len(a))
+		for _, x := range a {
+			v := strings.TrimSpace(x)
+			if v == "" || isPlaceholder(v) {
+				continue
+			}
+			out = append(out, v)
+		}
+		return out
+	}
+	P, C, S, G := clean(d.Points), clean(d.Conclusions), clean(d.Sources), clean(d.Log)
+	final := strings.TrimSpace(d.Final)
+	if final == "" {
+		final = "（待生成）"
+	}
+	desc := strings.TrimSpace(d.Desc)
+	if desc == "" || isPlaceholder(desc) {
+		desc = "（待补充）"
+	}
+	var b strings.Builder
+	b.WriteString("# " + name + "\n\n")
+	b.WriteString("## 最终版\n" + final + "\n\n")
+	b.WriteString("## 需求描述\n" + desc + "\n\n")
+	b.WriteString("## 需求点\n")
+	if len(P) == 0 {
+		b.WriteString("（暂无）\n")
+	} else {
+		for i, p := range P {
+			b.WriteString(itoa(i+1) + ". " + p + "\n")
+		}
+	}
+	b.WriteString("\n## 已定结论\n")
+	if len(C) == 0 {
+		b.WriteString("（暂无）\n")
+	} else {
+		for _, c := range C {
+			b.WriteString("- " + c + "\n")
+		}
+	}
+	b.WriteString("\n## 来源对话\n")
+	if len(S) == 0 {
+		b.WriteString("（暂无）\n")
+	} else {
+		for _, s := range S {
+			b.WriteString("- " + s + "\n")
+		}
+	}
+	b.WriteString("\n## 更新记录\n")
+	if len(G) == 0 {
+		b.WriteString("（暂无）\n")
+	} else {
+		for _, g := range G {
+			b.WriteString("- " + g + "\n")
+		}
+	}
+	return b.String()
+}
+
+// mergeUnique 去重追加。
+//
+// keepHead=true 保留最早的（需求点 / 结论：清单要稳定）；false 保留最新的（来源 / 流水）。
+// keyOf 可自定义判重键 ——「来源对话」用它：同一句原话在同义改写后按整行判重会留下两条。
+func mergeUnique(prev, add []string, cap int, keepHead bool, keyOf func(string) string) []string {
+	key := keyOf
+	if key == nil {
+		key = func(s string) string { return strings.Join(strings.Fields(s), "") }
+	}
+	seen := make(map[string]bool, len(prev))
+	out := make([]string, 0, len(prev)+len(add))
+	for _, p := range prev {
+		k := key(p)
+		if k == "" || seen[k] {
+			continue
+		}
+		seen[k] = true
+		out = append(out, p)
+	}
+	for _, a := range add {
+		v := strings.TrimSpace(a)
+		k := key(v)
+		if k == "" || seen[k] {
+			continue
+		}
+		seen[k] = true
+		out = append(out, v)
+	}
+	if cap > 0 && len(out) > cap {
+		if keepHead {
+			out = out[:cap]
+		} else {
+			out = out[len(out)-cap:]
+		}
+	}
+	return out
+}
+
+// sourceKey 「来源对话」行的判重键：剥掉时间戳 / #编号 / （任务：…）前缀，只留原话本体。
+func sourceKey(s string) string {
+	v := strings.TrimSpace(s)
+	if strings.HasPrefix(v, "[") {
+		if i := strings.Index(v, "]"); i > 0 {
+			v = strings.TrimSpace(v[i+1:])
+		}
+	}
+	if strings.HasPrefix(v, "#") {
+		i := 1
+		for i < len(v) && v[i] >= '0' && v[i] <= '9' {
+			i++
+		}
+		v = strings.TrimSpace(v[i:])
+	}
+	if strings.HasPrefix(v, "（") || strings.HasPrefix(v, "(") {
+		if i := strings.IndexAny(v, "）)"); i > 0 {
+			v = strings.TrimSpace(v[i+len("）"):])
+		}
+	}
+	return strings.Join(strings.Fields(v), "")
+}
+
+// SlugifyFeature 功能点名称 → 安全文件名：保留中文 / 字母 / 数字，压掉非法与空白，限长。
+//
+// 空白与「被删掉的非法字符」两侧会各留一个 '-'（`登录 / 注册` → `登录--注册`），
+// 连续横线压成一个 —— 文件名是用户要在访达里看的东西，别让它长出一串杠。
+func SlugifyFeature(name string) string {
+	var b strings.Builder
+	for _, r := range strings.TrimSpace(name) {
+		switch {
+		case strings.ContainsRune(`\/:*?"<>|`, r):
+			if b.Len() > 0 && !strings.HasSuffix(b.String(), "-") {
+				b.WriteRune('-')
+			}
+		case unicode.IsSpace(r):
+			if b.Len() > 0 && !strings.HasSuffix(b.String(), "-") {
+				b.WriteRune('-')
+			}
+		default:
+			b.WriteRune(r)
+		}
+	}
+	s := strings.Trim(b.String(), "-")
+	if s == "" {
+		return "untitled"
+	}
+	return truncRunes(s, 30)
+}
+
+// SlugifyModule 模块名 → 安全目录名（限 ModuleMaxChars 个字符）。
+func SlugifyModule(m string) string {
+	var b strings.Builder
+	for _, r := range strings.TrimSpace(m) {
+		switch {
+		case strings.ContainsRune(`\/:*?"<>|`, r):
+			continue
+		case unicode.IsSpace(r):
+			continue
+		default:
+			b.WriteRune(r)
+		}
+	}
+	s := strings.Trim(b.String(), ".-")
+	return truncRunes(s, ModuleMaxChars)
+}
+
+// truncRunes 按字符（不是字节）截断，避免把中文切成半个字。
+func truncRunes(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	return string(r[:n])
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	var buf [8]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	return string(buf[i:])
+}
+
+func contains(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}
+
+// featureFile 一个功能点文档的定位信息。
+type featureFile struct {
+	Module string
+	Name   string
+	File   string
+}
+
+// listFeatureFiles 列出功能点文档（两级目录 + 老数据平铺）。
+//
+// 两级：features/<模块>/<名称>.md；平铺：features/<名称>.md（未归类，module 为空）。
+// 跳过点开头的文件与目录（.DS_Store / 临时文件）。
+func listFeatureFiles(id string) []featureFile {
+	base := featuresDir(id)
+	ents, err := os.ReadDir(base)
+	if err != nil {
+		return nil
+	}
+	out := []featureFile{}
+	for _, e := range ents {
+		name := e.Name()
+		if strings.HasPrefix(name, ".") {
+			continue
+		}
+		if e.IsDir() {
+			subs, err := os.ReadDir(filepath.Join(base, name))
+			if err != nil {
+				continue
+			}
+			for _, s := range subs {
+				n := s.Name()
+				if s.IsDir() || strings.HasPrefix(n, ".") || !strings.HasSuffix(n, ".md") {
+					continue
+				}
+				out = append(out, featureFile{
+					Module: name,
+					Name:   strings.TrimSuffix(n, ".md"),
+					File:   filepath.Join(base, name, n),
+				})
+			}
+			continue
+		}
+		if !strings.HasSuffix(name, ".md") {
+			continue
+		}
+		out = append(out, featureFile{Name: strings.TrimSuffix(name, ".md"), File: filepath.Join(base, name)})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Module != out[j].Module {
+			return out[i].Module < out[j].Module
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// listModules 已有模块名（去重、稳定顺序）。
+func listModules(id string) []string {
+	seen := map[string]bool{}
+	out := []string{}
+	for _, f := range listFeatureFiles(id) {
+		if f.Module != "" && !seen[f.Module] {
+			seen[f.Module] = true
+			out = append(out, f.Module)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// docMerger 跨批共用的文档匹配池（片间 / 批间匹配一致）。
+//
+// 匹配三级：同名 → 归一化同名（去标点空格）→ 前缀包含（长度 ≥6 才允许，防「任务」
+// 这种短名把别的文档全吃掉）。
+type docMerger struct {
+	byName   map[string]featureFile
+	byNorm   map[string]featureFile
+	all      []featureFile
+	usedFile map[string]bool
+}
+
+func newDocMerger(id string) *docMerger {
+	files := listFeatureFiles(id)
+	m := &docMerger{
+		byName:   make(map[string]featureFile, len(files)),
+		byNorm:   make(map[string]featureFile, len(files)),
+		all:      files,
+		usedFile: map[string]bool{},
+	}
+	for _, f := range files {
+		m.byName[f.Name] = f
+		if n := normName(f.Name); n != "" {
+			m.byNorm[n] = f
+		}
+	}
+	return m
+}
+
+// normName 归一化名：去掉所有标点与空白，只留文字数字。
+func normName(s string) string {
+	var b strings.Builder
+	for _, r := range s {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+// match 找同名文档（三级匹配），没有返回 false。
+func (m *docMerger) match(name string) (featureFile, bool) {
+	if f, ok := m.byName[name]; ok {
+		return f, true
+	}
+	n := normName(name)
+	if n == "" {
+		return featureFile{}, false
+	}
+	if f, ok := m.byNorm[n]; ok {
+		return f, true
+	}
+	var best featureFile
+	bestLen := 0
+	for _, f := range m.all {
+		fn := normName(f.Name)
+		if len([]rune(fn)) < 6 || len([]rune(n)) < 6 {
+			continue
+		}
+		if !strings.HasPrefix(fn, n) && !strings.HasPrefix(n, fn) {
+			continue
+		}
+		if l := len([]rune(fn)); l > bestLen {
+			best, bestLen = f, l
+		}
+	}
+	return best, bestLen > 0
+}
+
+// add 把新建的文档加进匹配池（同一轮后续分片要能命中它）。
+func (m *docMerger) add(f featureFile) {
+	m.all = append(m.all, f)
+	m.byName[f.Name] = f
+	if n := normName(f.Name); n != "" {
+		m.byNorm[n] = f
+	}
+	m.usedFile[f.File] = true
+}