项目感知与知识库系统设计方案

// storage/vectordb/archival.go:410,534
results, err := coll.Query(ctx, query, limit, where, whereDocument)

return &tools.ToolResult{
    Summary: fmt.Sprintf("已切换到 %s", absPath),
}, nil

// Cd 后自动检测项目特征，返回丰富的上下文
summary := fmt.Sprintf("已切换到 %s", absPath)
// 检测项目标记文件
projectInfo := detectProjectHints(absPath)
if projectInfo != "" {
    summary += "\n\n" + projectInfo
}
return &tools.ToolResult{Summary: summary}, nil

// projectMarkers 定义项目类型标记文件及其含义
var projectMarkers = []struct {
    file     string
    hint     string
}{
    {"go.mod", "Go 项目"},
    {"package.json", "Node.js 项目"},
    {"Cargo.toml", "Rust 项目"},
    {"pyproject.toml", "Python 项目"},
    {"pom.xml", "Java/Maven 项目"},
    {"build.gradle", "Java/Gradle 项目"},
    {"Makefile", "C/C++ 项目（可能有）"},
    {"docker-compose.yml", "Docker 编排项目"},
    {".git", "Git 仓库"},
}

func detectProjectHints(dir string) string {
    // 1. 检测项目类型
    var hints []string
    for _, m := range projectMarkers {
        if _, err := os.Stat(filepath.Join(dir, m.file)); err == nil {
            hints = append(hints, m.hint)
        }
    }
    
    // 2. 读取项目名称（从 go.mod/package.json 等提取）
    name := detectProjectName(dir)
    
    // 3. 列出顶层目录结构（仅一级，最多 10 项）
    entries := listTopLevel(dir, 10)
    
    // 4. 组装
    var sb strings.Builder
    if name != "" {
        sb.WriteString(fmt.Sprintf("项目: %s", name))
    }
    if len(hints) > 0 {
        if sb.Len() > 0 { sb.WriteString(" | ") }
        sb.WriteString(strings.Join(hints, ", "))
    }
    if len(entries) > 0 {
        sb.WriteString(fmt.Sprintf("\n目录结构:\n%s", entries))
    }
    // 5. 建议 LLM 记住这个项目
    sb.WriteString(fmt.Sprintf("\n💡 提示：如果这是你经常工作的项目，可以用 archival_memory_insert 将项目信息存入知识库（包含路径 %s 和项目特征），下次对话可直接查询。", dir))
    
    return sb.String()
}

### 目录导航习惯
- 你有一个 `Cd` 工具可以切换工作目录，切换后所有后续 Shell 命令都会在新目录执行
- **强烈建议**：当你发现自己在 `/workspace` 下频繁使用 `ls`/`find` 寻找项目时，用 `Cd` 切换到项目根目录
- Cd 工具会自动返回目录的项目类型和结构信息，帮你快速建立上下文
- 切换后你不再需要每次都写完整路径

[PROJECT_CARD]
项目名称: xbot
项目路径: /workspace/xbot
项目类型: Go
技术栈: Go 1.22, SQLite, chromem-go, OpenAI/Anthropic API, Docker
关键入口:
  - 主入口: cmd/xbot/main.go
  - Agent 核心: agent/engine.go, agent/engine_wire.go
  - 记忆系统: memory/letta/letta.go, storage/vectordb/archival.go
  - 工具系统: tools/*.go
常用命令:
  - go test ./...  — 运行全部测试
  - go run cmd/xbot/main.go  — 启动
  - go build ./...  — 编译检查
项目描述: Go 语言 AI Agent 框架，支持 SubAgent、MCP 工具、三层记忆系统
最后更新: 2026-03-20
[END_PROJECT_CARD]

## 项目知识库

你有一个长期的项目知识库，存储在 archival memory 中。你可以用它记住用户的项目信息，避免每次对话都重新探索。

### 知识卡片管理规则

**何时创建知识卡片**：
- 当你在一个新项目中工作了 3 次以上，且每次都要用 Glob/Grep/Read 探索项目结构时
- 当用户明确说「记住这个项目」时
- 当你用 Cd 切换到项目目录，Cd 返回的项目信息很有价值时

**何时查询知识卡片**：
- 对话开始时，如果用户的消息暗示某个项目（提到文件路径、项目名、技术栈关键词）
- 当用户问「那个项目在哪」时
- 当你需要回忆项目结构、技术栈、常用命令时

**何时更新知识卡片**：
- 发现项目新增了重要模块或目录时
- 项目技术栈发生变化时（如新增依赖、切换框架）
- 你发现卡片中的信息已过时时

**知识卡片格式**：
用 `archival_memory_insert` 工具存储，格式以 `[PROJECT_CARD]` 开头、`[END_PROJECT_CARD]` 结尾。
更新时：先 `archival_memory_search` 找到旧卡片，用返回的 ID 通过对话上下文提醒自己需要更新，然后插入新卡片（archival memory 不支持原地更新，新卡片会自然取代旧卡片的检索排名）。

**查询方式**：
用 `archival_memory_search` 工具搜索项目名、路径、技术栈关键词。例如：
- `archival_memory_search("xbot 项目路径和结构")`
- `archival_memory_search("Go agent 框架")`

type ProjectHintMiddleware struct {
    archivalSvc *vectordb.ArchivalService
}

func NewProjectHintMiddleware(archivalSvc *vectordb.ArchivalService) *ProjectHintMiddleware {
    return &ProjectHintMiddleware{archivalSvc: archivalSvc}
}

func (m *ProjectHintMiddleware) Name() string { return "project_hint" }

// Priority=1: 在 SystemPromptMiddleware(0) 之后、ChannelPromptMiddleware(5) 之前
// 确保项目提示作为基础上下文的一部分，在记忆注入(100)之前
func (m *ProjectHintMiddleware) Priority() int { return 1 }

func (m *ProjectHintMiddleware) Process(mc *MessageContext) error {
    if m.archivalSvc == nil {
        return nil // 无 archival 服务时跳过
    }
    
    // 从 MessageContext 获取 TenantID
    tenantID := mc.TenantID
    if tenantID == 0 {
        return nil
    }
    
    // 查询项目知识卡片
    // 使用 chromem-go 的 whereDocument 过滤，只搜索包含 [PROJECT_CARD] 标记的内容
    // chromem-go whereDocument 支持 $contains 操作符
    entries, err := m.archivalSvc.SearchByDocumentContains(
        mc.Ctx, tenantID, "PROJECT_CARD", 3,
    )
    if err != nil || len(entries) == 0 {
        return nil
    }
    
    // 构建注入文本
    var sb strings.Builder
    sb.WriteString("\n## 已知项目\n\n")
    sb.WriteString("以下是你在之前对话中了解到的用户项目信息。你可以直接参考，无需重新探索。\n\n")
    for i, entry := range entries {
        sb.WriteString(fmt.Sprintf("### 项目 %d\n%s\n\n", i+1, entry.Content))
    }
    
    // 注入到 SystemPrompt 的 Parts 中（追加而非替换）
    mc.SystemPromptParts = append(mc.SystemPromptParts, sb.String())
    
    return nil
}

// SearchByDocumentContents searches archival entries where document content
// contains the specified substring, using chromem-go's whereDocument filter.
func (s *ArchivalService) SearchByDocumentContains(ctx context.Context, tenantID int64, contains string, limit int) ([]ArchivalEntry, error) {
    coll, err := s.getOrCreateCollection(tenantID)
    if err != nil {
        return nil, fmt.Errorf("get collection: %w", err)
    }
    
    count := coll.Count()
    if count == 0 {
        return nil, nil
    }
    if limit > count {
        limit = count
    }
    
    // chromem-go whereDocument 支持 $contains 操作符
    // 查找文档内容包含指定标记的条目
    results, err := coll.Query(ctx, contains, limit, nil, map[string]string{
        "$contains": contains,
    })
    if err != nil {
        return nil, fmt.Errorf("query by document contains: %w", err)
    }
    
    entries := make([]ArchivalEntry, len(results))
    for i, r := range results {
        createdAt, _ := time.Parse(time.RFC3339, r.Metadata["created_at"])
        entries[i] = ArchivalEntry{
            ID:          r.ID,
            TenantID:    tenantID,
            Content:     r.Content,
            Similarity:  r.Similarity,
            CreatedAt:   createdAt,
            IsCore:      r.Metadata["is_core"] == "true",
            SenderID:    r.Metadata["sender_id"],
            ToolCallID:  r.Metadata["tool_call_id"],
        }
    }
    return entries, nil
}

// 在 NewAgent() 的 pipeline 构建逻辑中
pipeline.Use(NewProjectHintMiddleware(a.multiSession.ArchivalService()))

// 在 buildSubAgentRunConfig 的 sysPrompt 构建之后、messages 构建之前
// 检索父 Agent 的项目知识卡片
if parentExtras := a.buildToolContextExtras(parentCtx.Channel, parentCtx.ChatID); parentExtras.TenantID != 0 {
    if projEntries, err := a.multiSession.ArchivalService().SearchByDocumentContains(
        ctx, parentExtras.TenantID, "PROJECT_CARD", 3,
    ); err == nil && len(projEntries) > 0 {
        var sb strings.Builder
        sb.WriteString("\n## 用户项目背景\n\n")
        sb.WriteString("以下是你所属的 Agent 之前了解到的用户项目信息，供你参考：\n\n")
        for i, entry := range projEntries {
            sb.WriteString(fmt.Sprintf("### 项目 %d\n%s\n\n", i+1, entry.Content))
        }
        sysPrompt += sb.String()
    }
}

// chromem-go 的 Query 方法签名
Query(ctx context.Context, query string, nResults int, where, whereDocument map[string]string) ([]Document, error)

// whereDocument 支持的操作符（作为 key 的前缀）
map[string]string{
    "$contains": "PROJECT_CARD",   // 文档内容包含指定字符串
}

// 注意：whereDocument 的 value 是普通字符串（非 JSON），$contains 操作符做子串匹配
// chromem-go 文档：https://github.com/philippgille/chromem-go

[PROJECT_CARD]
项目名称: xbot
项目路径: /workspace/xbot
项目类型: Go
技术栈: Go 1.22, SQLite, chromem-go (embed vector DB), OpenAI/Anthropic API, Docker
关键入口:
  - 主入口: cmd/xbot/main.go
  - Agent 核心: agent/engine.go, agent/engine_wire.go
  - 记忆系统: memory/letta/letta.go, storage/vectordb/archival.go
  - 工具系统: tools/*.go
  - 提示词模板: prompt.md, agent/subagent_prompt.go
常用命令:
  - go test ./...  — 运行全部测试
  - go run cmd/xbot/main.go  — 启动服务
  - go build ./...  — 编译检查
项目描述: Go 语言 AI Agent 框架，支持 SubAgent 嵌套、MCP 工具协议、Letta 三层记忆系统、多渠道（飞书/QQ）接入。
代码规模: ~142 个 Go 文件，~32k 行非测试代码
最后更新: 2026-03-20
[END_PROJECT_CARD]

[PROJECT_CARD]
项目名称: my-react-app
项目路径: /workspace/my-react-app
项目类型: TypeScript/React
技术栈: React 18, TypeScript, Vite, Tailwind CSS, React Query
关键入口:
  - 入口页面: src/App.tsx
  - 路由配置: src/router/index.ts
  - API 层: src/api/client.ts
  - 组件目录: src/components/
常用命令:
  - pnpm dev  — 启动开发服务器
  - pnpm build  — 生产构建
  - pnpm test  — 运行测试
项目描述: React SPA 管理后台，使用 Tailwind CSS 样式、React Query 数据管理。
最后更新: 2026-03-20
[END_PROJECT_CARD]

## Problem

xbot currently suffers from **working directory disorientation**:
1. Every command executes in `/workspace`; the LLM doesn't remember project paths across conversations
2. The `Cd` tool exists but is rarely used by the LLM
3. Project context is lost after each conversation (not persisted to archival memory)

## Proposal

Design a **Project Knowledge Base** system that leverages the existing archival memory (embed vector store) to let the LLM build and maintain project awareness.

### Key Design Decisions

1. **Prompt-first approach**: Guide the LLM via prompt to autonomously create/query/update project knowledge cards
2. **No new data structures**: Project cards are structured text stored in archival memory via existing `archival_memory_insert`
3. **Natural deduplication**: New cards naturally outrank old ones in vector similarity search
4. **Phase 1: Cd tool enhancement** — return project context on directory change
5. **Phase 2: Knowledge card schema + prompt guidance** — teach the LLM when/how to create cards
6. **Phase 3: Auto-injection middleware** — `ProjectHintMiddleware` (Priority=1) injects known projects into system prompt
7. **Phase 4: SubAgent knowledge sharing** — inject parent's project cards into SubAgent system prompt
8. **Phase 5: Knowledge governance** — stale card handling, size limits, embedding quality

### Full Proposal Document

📄 [`docs/project-awareness-proposal.md`](./docs/project-awareness-proposal.md) (v3.0, 1133 lines)

### Architecture Impact

- **New files**: `agent/project_hint.go` (middleware)
- **Modified files**: `tools/cd.go`, `prompt.md`, `storage/vectordb/archival.go`, `agent/engine_wire.go`
- **No breaking changes**: All changes are additive; existing memory/session/tool systems untouched
- **No schema changes**: No database migration needed