Merge pull request #1 from d-wwei/feat/profile-discovery-pipeline

feat(persona): Profile Discovery Pipeline for bootstrap pre-fill

Author: d-wwei

.gitignore

@@ -35,4 +35,5 @@ src/ui/viewer.html
 .claude-octopus/
 .claude/session-intent.md
 .claude/session-plan.md
-.octo/
+.octo/
+.apex/

INSTALL.md

@@ -0,0 +1,81 @@
+# Installing Agent Recall
+
+Agent Recall gives your AI coding agents persistent memory across sessions.
+It works with Claude Code, Cursor, Codex CLI, Gemini CLI, and OpenCode.
+
+## Quick Start
+
+```bash
+npx agent-recall install
+```
+
+That's it. The installer auto-detects your AI platforms and configures them.
+
+## Verify Installation
+
+```bash
+npx agent-recall doctor
+```
+
+## Managing Platforms
+
+```bash
+npx agent-recall adapter list              # See what's installed
+npx agent-recall adapter install cursor    # Add a platform
+npx agent-recall adapter remove cursor     # Remove a platform
+```
+
+## For Developers
+
+Install from source (allows editing code):
+
+```bash
+npx agent-recall install --from-source
+```
+
+## Uninstall
+
+```bash
+npx agent-recall uninstall
+```
+
+Your memory database (~/.agent-recall/) is preserved. Delete manually if desired.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `npx` not found | Install Node.js >= 18 from https://nodejs.org |
+| Bun install fails | Manual: `curl -fsSL https://bun.sh/install \| bash` |
+| Worker won't start | `npx agent-recall doctor --fix` |
+| Platform not detected | `npx agent-recall adapter install <platform>` |
+
+---
+
+## Agent-Executable Installation Steps
+
+The following section is structured for AI agents to execute directly.
+
+### Prerequisites
+
+- Node.js >= 18 (verify: `node --version`)
+- Internet access for npm package download
+
+### Step-by-Step
+
+1. Run: `npx agent-recall install`
+2. Verify: `npx agent-recall doctor`
+3. Expected output of doctor: all lines show ✓ (green checkmark)
+4. If any ✗ (red cross) appears, run: `npx agent-recall doctor --fix`
+5. Verify Worker is accessible: `curl -s http://localhost:37777/api/health`
+6. Expected response: JSON with `{"status":"ok"}`
+
+### Platform-Specific Manual Registration
+
+If auto-detection fails, register manually:
+
+- Claude Code: `npx agent-recall adapter install claude-code`
+- Cursor: `npx agent-recall adapter install cursor`
+- Codex CLI: `npx agent-recall adapter install codex`
+- Gemini CLI: `npx agent-recall adapter install gemini`
+- OpenCode: `npx agent-recall adapter install opencode`

bin/agent-recall.cjs

@@ -2,24 +2,25 @@
 
 > 本文档记录已完成优化之后的后续迭代方向，供后续开发参考。
 >
-> 日期：2026-04-09
+> 日期：2026-04-10（基于代码审计修正）
 > 当前版本：v1.0.0-beta.1（Phase 1-5 + Phase X 全部落地）
 
 ---
 
 ## 当前状态速览
 
-**已完成**：37/38 项优化，+28,038 行代码，77 个新文件，2511 tests (0 fail)
+**已完成**：38/38 项优化，+28,038 行代码，77 个新文件，2511 tests (0 fail)
 
 **架构**：
-- 存储：SQLite (bun:sqlite) + ChromaDB (可选) 双系统
-- 检索：FTS5 + ChromaDB 自适应融合排序 + 时间锚点 + 偏好合成
-- 编译：CompilationEngine (5-gate + 4-stage) + KnowledgeLint + HotColdManager
+- 存储：SQLite (bun:sqlite) + SeekDB (嵌入式向量搜索，默认) + ChromaDB (可选 fallback，默认关闭)
+- 检索：FTS5 + SeekDB 语义搜索 自适应融合排序 + 时间锚点 + 偏好合成（fallback 链：SeekDB → ChromaDB → SQLite FTS5）
+- 编译：CompilationEngine (5-gate + 4-stage) + KnowledgeLint (已接入 Dashboard) + HotColdManager
 - 上下文：L0-L3 分层 Token 预算 (TokenBudgetManager)
 - 知识图谱：entities + facts + 时序查询
+- Markdown 同步：MarkdownExporter + MarkdownImporter 双向同步（hash 变更检测）
 - 表现层：Dashboard API + Markdown 导出 + 多输出格式 + MCP 工具
 
-**唯一未实施项**：8.2 seekdb 统一数据库（长期观察方向）
+**全部优化项已实施**（含 SeekDB 向量后端迁移，原 8.2）
 
 ---
 
@@ -130,67 +131,41 @@ Agent 请求 → Worker HTTP API → AuthMiddleware（检查 X-Agent-Id header
 | 搜索结果解释 | SearchExplainer 已就绪 | 小（显示分数、匹配类型、关键词高亮） |
 | 编译状态指示器 | CompilationEngine 有状态 | 小（"Compiling..." 进度条） |
 | LLM 成本追踪面板 | 需要新增计数器 | 中 |
-| Lint 告警面板 | KnowledgeLint 已就绪 | 小 |
+| Lint 告警面板 | KnowledgeLint 已就绪且已接入 Dashboard API | 小（API 已有数据，前端渲染即可） |
 
 **建议**：先做仪表盘（最容易，后端已 ready），再做搜索解释（小改动大提升），最后做图谱（最复杂）。
 
 ---
 
-#### 1.3 KnowledgeLint ↔ Dashboard 集成
+#### ~~1.3 KnowledgeLint ↔ Dashboard 集成~~ ✅ 已完成
 
-**现状**：`DashboardService.ts` 中 `lintWarnings = 0` 有一个 TODO，KnowledgeLint 已实现但未接入 Dashboard。
-
-**修复**：在 Dashboard 查询中调用 `KnowledgeLint.run(project)` 并返回 `warnings.length`。
-
-**预估**：极小改动（< 20 行）。
+> `DashboardService.ts` 已调用 `KnowledgeLint.run(project)`，lint 告警数据已接入 Dashboard API。
 
 ---
 
 ### Tier 2：中优先级（架构质量提升）
 
-#### 2.1 统一数据库方案评估
-
-**现状**：SQLite + ChromaDB 双系统，依赖 ChromaSync 维护同步一致性。
+#### ~~2.1 统一数据库方案评估~~ ✅ 已完成（SeekDB 已落地）
 
-**两个候选方案**：
-
-| 方案 | 说明 | 成熟度 | 优势 | 劣势 |
-|------|------|--------|------|------|
-| **sqlite-vec** | SQLite 原生向量扩展 | 高（活跃生态） | 消除双系统、零依赖 | 向量搜索性能不如专业 DB |
-| **seekdb** | OceanBase AI 原生混合搜索 | 低（v1.2, 2.5k stars） | 原生混合检索+内置 AI 函数 | 太新，JS SDK 不成熟 |
-
-**建议**：
-- 短期（3-6 个月）：评估 sqlite-vec 作为 ChromaDB 的替代品，可以消除 ChromaSync 复杂度
-- 长期（6-12 个月）：持续观察 seekdb 生态成熟度
-- 评估标准：嵌入式部署能力、JS/TS SDK 质量、社区活跃度、基准测试性能
+> **已解决**：SeekDB (`seekdb@^1.2.0`) 已作为默认向量搜索后端落地。
+> - 默认配置：`AGENT_RECALL_VECTOR_BACKEND=seekdb`
+> - 嵌入式运行，无外部依赖（不需要 Python/uv）
+> - ChromaDB 保留为可选 fallback（`CLAUDE_MEM_CHROMA_ENABLED=false` 默认关闭）
+> - 实现文件：`src/services/sync/SeekdbSync.ts`
+>
+> **剩余工作**：评估是否可以完全移除 ChromaDB 代码（`ChromaSync.ts` + `ChromaMcpManager.ts`），进一步精简依赖。
 
 ---
 
-#### 2.2 ObservationRecord 类型统一
+#### ~~2.2 ObservationRecord 类型统一~~ ✅ 已完成
 
-**现状**：`src/types/database.ts` 中的 `ObservationRecord` 接口只有 13 个字段，但实际 observations 表现在有 22 个字段（Phase 1/3 新增了 confidence, tags, has_preference, event_date, last_referenced_at, valid_until, superseded_by, related_observations）。多处代码用 `any` 类型绕过。
-
-**修复方向**：
-- 更新 `ObservationRecord` 接口包含所有字段
-- 更新 `ObservationSearchResult` 扩展接口
-- 消除 `(obs as any).confidence` 等类型断言
-- 同步更新 `SessionSummaryRecord` 和 `SessionSummarySearchResult`
-
-**预估**：中等改动，纯类型重构，不影响运行时。
+> `ObservationRecord` 接口已包含全部 22 个字段（含 Phase 1 enrichment + Phase 3 lifecycle 字段）。
 
 ---
 
-#### 2.3 Markdown 双向同步完善
-
-**现状**：`MarkdownExporter` 只做 DB → Markdown 单向导出。`markdown_sync` 表已创建但未使用 content hash 追踪。
+#### ~~2.3 Markdown 双向同步完善~~ ✅ 已完成
 
-**完善方向**：
-- 导出时记录 content hash 到 `markdown_sync` 表
-- SessionStart 时检测用户手动编辑（hash 变化）
-- 单侧变更自动同步，双侧变更提示用户选择
-- 冲突解决：`*.db-version.md` 保留 DB 版本，让用户决定
-
-**预估**：中等改动。`MarkdownImporter`（对应 `MarkdownExporter`）需要新建。
+> `MarkdownImporter` 已实现（`src/services/markdown-sync/MarkdownImporter.ts`），支持 hash 变更检测。与 `MarkdownExporter` 组成完整的双向同步。
 
 ---
 
@@ -322,22 +297,25 @@ Agent 请求 → Worker HTTP API → AuthMiddleware（检查 X-Agent-Id header
 
 | 项目 | 位置 | 说明 |
 |------|------|------|
-| `ObservationRecord` 类型不完整 | `src/types/database.ts:64` | 缺少 Phase 1/3 新增的 9 个字段 |
+| ~~`ObservationRecord` 类型不完整~~ | ~~`src/types/database.ts`~~ | ✅ 已修复 — 全部 22 字段已补齐 |
 | `PrivacyGuard` 本地类型定义 | `src/services/compilation/PrivacyGuard.ts:8` | 应引用统一类型而非本地接口 |
-| Dashboard lint 集成 TODO | `src/services/dashboard/DashboardService.ts:101` | `lintWarnings = 0` 硬编码 |
-| ConsolidateStage 无 AI 调用 | `src/services/compilation/stages/ConsolidateStage.ts:13` | MVP 文本拼接，注释标注待升级 |
+| ~~Dashboard lint 集成 TODO~~ | ~~`src/services/dashboard/DashboardService.ts`~~ | ✅ 已修复 — KnowledgeLint 已接入 |
+| ConsolidateStage 无 AI 调用 | `src/services/compilation/stages/ConsolidateStage.ts:13` | MVP 文本拼接，`aiMerge()` 是空壳 stub |
 | `Component` 类型维护 | `src/utils/logger.ts:18` | 新增服务需手动添加组件名，容易遗漏 |
+| ChromaDB 遗留代码 | `src/services/sync/ChromaSync.ts`, `ChromaMcpManager.ts` | SeekDB 已为默认后端，ChromaDB 代码可评估移除 |
 
 ---
 
 ## 建议的下一个 Sprint
 
-如果继续开发，推荐这个优先顺序：
+> 更新于 2026-04-10。Tier 2.1/2.2/2.3 和 Tier 1.3 已在之前的迭代中完成。
+
+推荐优先顺序：
 
-1. **AI 编译升级** (Tier 1.1) — 核心价值提升，从 MVP 到生产级
-2. **Viewer 仪表盘** (Tier 1.2 部分) — 后端 ready，前端接入即可展示
-3. **类型统一** (Tier 2.2) — 消除 `any` 断言，提升代码质量
-4. **sqlite-vec 评估** (Tier 2.1) — 如果通过，可以消除 ChromaDB 依赖
+1. **一键安装** (Tier 1.0) — 获客生命线，SeekDB 嵌入式架构使安装链路大幅简化（不再需要 Python/uv）
+2. **AI 编译升级** (Tier 1.1) — 核心价值提升，`ConsolidateStage.ts` 从 MVP 文本拼接到 LLM 语义合成
+3. **ChromaDB 遗留代码清理** — 评估是否可完全移除 ChromaSync/ChromaMcpManager，进一步精简
+4. **Viewer 仪表盘** (Tier 1.2 部分) — 后端 ready，前端接入即可展示
 5. **Benchmark CI** (Tier 4.1) — 确保搜索质量持续提升
 
 ---