echoctl 0.1.0 → 0.1.3

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,36 @@
+import DefaultTheme from 'vitepress/theme'
+import Layout from './Layout.vue'
+import EchoArticleActions from './components/EchoArticleActions.vue'
+import EchoSelectionComment from './components/EchoSelectionComment.vue'
+import EchoSearchLanding from './components/EchoSearchLanding.vue'
+import EchoTagsPage from './components/EchoTagsPage.vue'
+import EchoChatBubbles from './components/EchoChatBubbles.vue'
+import EchoProjectTabs from './components/EchoProjectTabs.vue'
+import EchoCommentChain from './components/EchoCommentChain.vue'
+import EchoCommentNode from './components/EchoCommentNode.vue'
+// [LIVE_SESSION_DISABLED] 后期恢复时取消注释
+// import EchoLiveSession from './components/EchoLiveSession.vue'
+import EchoLegacyRecovery from './components/EchoLegacyRecovery.vue'
+import EchoGlobalControls from './components/EchoGlobalControls.vue'
+import EchoClaudeImportBanner from './components/EchoClaudeImportBanner.vue'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout,
+  enhanceApp({ app }: any) {
+    app.component('EchoArticleActions', EchoArticleActions)
+    app.component('EchoSelectionComment', EchoSelectionComment)
+    app.component('EchoSearchLanding', EchoSearchLanding)
+    app.component('EchoTagsPage', EchoTagsPage)
+    app.component('EchoChatBubbles', EchoChatBubbles)
+    app.component('EchoProjectTabs', EchoProjectTabs)
+    app.component('EchoCommentChain', EchoCommentChain)
+    app.component('EchoCommentNode', EchoCommentNode)
+    // [LIVE_SESSION_DISABLED] 后期恢复时取消注释
+    // app.component('EchoLiveSession', EchoLiveSession)
+    app.component('EchoLegacyRecovery', EchoLegacyRecovery)
+    app.component('EchoGlobalControls', EchoGlobalControls)
+    app.component('EchoClaudeImportBanner', EchoClaudeImportBanner)
+  },
+}

package/docs/.vitepress/theme/lib/echo-api.ts

@@ -0,0 +1,298 @@
+const CONFIGURED_API_BASE = (typeof import.meta !== 'undefined' && import.meta.env?.VITE_ECHO_API_BASE) || ''
+const DEFAULT_API_BASE = 'http://127.0.0.1:8787'
+const API_CANDIDATES = [CONFIGURED_API_BASE, DEFAULT_API_BASE].filter(Boolean)
+
+interface EchoStatus {
+  ok: boolean
+  captureEnabled: boolean
+  projectId: string | null
+  version: string
+  author: string
+}
+
+interface CommentPayload {
+  articleId: string
+  comment: string
+  quote?: string
+  prefix?: string
+  suffix?: string
+  occurrence?: number
+  author?: string
+  scope?: string
+  evolutionOf?: string[]
+  evolutionKind?: string
+  projectId?: string | null
+}
+
+interface TagPayload {
+  articleId: string
+  tag: string
+  projectId?: string | null
+}
+
+interface PublishPayload {
+  sessionId: string
+  projectId?: string | null
+}
+
+interface PublishResponse {
+  ok: boolean
+  id: string
+  slug: string
+  turnCount: number
+  version: number
+  latest: boolean
+}
+
+interface LiveSessionState {
+  ok: boolean
+  exists: boolean
+  projectId: string | null
+  sessionId: string
+  turnCount: number
+  hash: string | null
+  updatedAt: string | null
+}
+
+interface LegacyCandidate {
+  sessionId: string
+  fileName: string
+  sourcePath: string
+  turnCount: number
+  mtime: string
+  confidence: string
+  evidence: { kind: string; projectRoot: string } | null
+}
+
+interface LegacyCandidatesResponse {
+  projectId: string
+  sourceDir: string
+  candidates: LegacyCandidate[]
+}
+
+interface ClaudeImportCandidate {
+  sessionId: string
+  filePath: string
+  status: string
+  articleId: string
+  turnCount: number
+  mtime: string
+  fileHash: string
+}
+
+interface ClaudeImportCandidatesResponse {
+  projectId: string
+  provider: string
+  projectDir: string
+  summary: { total: number; new: number; updated: number; skipped: number }
+  candidates: ClaudeImportCandidate[]
+}
+
+interface ClaudeImportResponse {
+  ok: boolean
+  imported: number
+  skipped: number
+  articlesDir: string | null
+  refreshScheduled: boolean
+}
+
+interface LegacyMigrateResponse {
+  ok: boolean
+  migrated: number
+  skipped: number
+  targetDir: string
+  refreshScheduled: boolean
+}
+
+class EchoApiError extends Error {
+  status: number
+  constructor(message: string, status: number) {
+    super(message)
+    this.name = 'EchoApiError'
+    this.status = status
+  }
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  if (API_CANDIDATES.length === 0) {
+    throw new EchoApiError('API not available', 0)
+  }
+
+  let lastError: EchoApiError | null = null
+  for (const base of API_CANDIDATES) {
+    try {
+      return await requestFrom<T>(base, path, options)
+    } catch (err) {
+      lastError = err instanceof EchoApiError ? err : new EchoApiError((err as Error).message || 'Network error', 0)
+    }
+  }
+
+  throw lastError || new EchoApiError('Network error', 0)
+}
+
+async function requestFrom<T>(base: string, path: string, options?: RequestInit): Promise<T> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 5000)
+  try {
+    const res = await fetch(`${base}${path}`, {
+      ...options,
+      signal: controller.signal,
+      headers: { 'Content-Type': 'application/json', ...options?.headers },
+    })
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}))
+      throw new EchoApiError((body as any).error || res.statusText, res.status)
+    }
+    return res.json() as Promise<T>
+  } catch (err) {
+    if (err instanceof EchoApiError) throw err
+    if ((err as Error).name === 'AbortError') {
+      throw new EchoApiError('Request timed out', 0)
+    }
+    throw new EchoApiError((err as Error).message || 'Network error', 0)
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export function getStatus(): Promise<EchoStatus> {
+  return request<EchoStatus>('/api/status')
+}
+
+export function getCaptureStatus(): Promise<{ enabled: boolean }> {
+  return request<{ enabled: boolean }>('/api/capture')
+}
+
+export function setCapture(enabled: boolean): Promise<{ enabled: boolean }> {
+  return request<{ enabled: boolean }>('/api/capture', {
+    method: 'POST',
+    body: JSON.stringify({ enabled }),
+  })
+}
+
+export function getMcpConfig(): Promise<{ canonical: { command: string; args: string[] }; legacy: any[]; serverInfo: any }> {
+  return request('/api/mcp-config')
+}
+
+export function postComment(payload: CommentPayload): Promise<any> {
+  return request('/api/comments', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+export function postTag(payload: TagPayload): Promise<any> {
+  return request('/api/tags', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+interface RemoveTagPayload {
+  articleId: string
+  tags: string[]
+  projectId?: string | null
+}
+
+export function removeTags(payload: RemoveTagPayload): Promise<any> {
+  return request('/api/tags/remove', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+interface RenameTagPayload {
+  oldTag: string
+  newTag: string
+  projectId?: string | null
+}
+
+interface RenameTagResponse {
+  oldTag: string
+  newTag: string
+  renamed: number
+}
+
+export function renameTag(payload: RenameTagPayload): Promise<RenameTagResponse> {
+  return request<RenameTagResponse>('/api/tags/rename', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+interface PurgeTagPayload {
+  tag: string
+  projectId?: string | null
+}
+
+interface PurgeTagResponse {
+  tag: string
+  purged: number
+}
+
+export function purgeTag(payload: PurgeTagPayload): Promise<PurgeTagResponse> {
+  return request<PurgeTagResponse>('/api/tags/purge', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+interface SummaryPayload {
+  articleId: string
+  summary: string
+  projectId?: string | null
+}
+
+export function updateSummary(payload: SummaryPayload): Promise<any> {
+  return request('/api/summary', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+export function postPublish(payload: PublishPayload): Promise<PublishResponse> {
+  return request<PublishResponse>('/api/publish', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+}
+
+export function getLiveSessionState(projectId: string | null, sessionId: string): Promise<LiveSessionState> {
+  const params = new URLSearchParams({ sessionId })
+  if (projectId) params.set('projectId', projectId)
+  return request<LiveSessionState>(`/api/live-session-state?${params.toString()}`)
+}
+
+export function getLegacyCandidates(projectId: string): Promise<LegacyCandidatesResponse> {
+  return request<LegacyCandidatesResponse>(`/api/legacy-candidates?projectId=${encodeURIComponent(projectId)}`)
+}
+
+export function migrateLegacyCandidates(projectId: string, candidateIds?: string[]): Promise<LegacyMigrateResponse> {
+  return request<LegacyMigrateResponse>('/api/legacy-candidates/migrate', {
+    method: 'POST',
+    body: JSON.stringify({ projectId, candidateIds }),
+  })
+}
+
+interface ProjectsResponse {
+  projects: { id: string; name: string; root: string; dataRoot: string }[]
+  currentId: string | null
+}
+
+export function getProjects(): Promise<ProjectsResponse> {
+  return request<ProjectsResponse>('/api/projects')
+}
+
+export function getClaudeImportCandidates(projectId: string): Promise<ClaudeImportCandidatesResponse> {
+  return request<ClaudeImportCandidatesResponse>(`/api/import/claude-candidates?projectId=${encodeURIComponent(projectId)}`)
+}
+
+export function importClaudeSessions(projectId: string, sessionIds: string[]): Promise<ClaudeImportResponse> {
+  return request<ClaudeImportResponse>('/api/import/claude', {
+    method: 'POST',
+    body: JSON.stringify({ projectId, sessionIds }),
+  })
+}
+
+export { EchoApiError, CONFIGURED_API_BASE, DEFAULT_API_BASE }
+export type { EchoStatus, CommentPayload, TagPayload, RemoveTagPayload, RenameTagPayload, RenameTagResponse, PurgeTagPayload, PurgeTagResponse, SummaryPayload, PublishPayload, PublishResponse, LiveSessionState, LegacyCandidate, LegacyCandidatesResponse, LegacyMigrateResponse, ClaudeImportCandidate, ClaudeImportCandidatesResponse, ClaudeImportResponse }

package/docs/.vitepress/theme/lib/echo-heartbeat.ts

@@ -0,0 +1,34 @@
+type Subscriber = () => void | Promise<void>
+
+const subscribers = new Set<Subscriber>()
+let timer: ReturnType<typeof window.setInterval> | null = null
+const intervalMs = 10000
+
+function tick() {
+  if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return
+  for (const subscriber of Array.from(subscribers)) {
+    void subscriber()
+  }
+}
+
+function start() {
+  if (typeof window === 'undefined' || timer) return
+  timer = window.setInterval(tick, intervalMs)
+}
+
+function stop() {
+  if (!timer || subscribers.size > 0) return
+  window.clearInterval(timer)
+  timer = null
+}
+
+export function subscribeEchoHeartbeat(subscriber: Subscriber): () => void {
+  subscribers.add(subscriber)
+  start()
+  return () => {
+    subscribers.delete(subscriber)
+    stop()
+  }
+}
+
+export { intervalMs as echoHeartbeatIntervalMs }

package/docs/.vitepress/theme/lib/useEchoStatus.ts

@@ -0,0 +1,59 @@
+import { ref, watch, onMounted, onUnmounted, type Ref } from 'vue'
+import { getStatus, EchoApiError, type EchoStatus } from './echo-api'
+
+type StatusState = 'loading' | 'ready' | 'unavailable'
+
+export function useEchoStatus(articleId: Ref<string | undefined>) {
+  const state = ref<StatusState>('loading')
+  const status = ref<EchoStatus | null>(null)
+  const error = ref<string>('')
+  let controller: AbortController | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+
+  async function check() {
+    controller?.abort()
+    controller = new AbortController()
+    state.value = 'loading'
+    error.value = ''
+
+    try {
+      const result = await getStatus()
+      status.value = result
+      state.value = 'ready'
+    } catch (err) {
+      if ((err as Error).name === 'AbortError' || (err as Error).message?.includes('abort')) return
+      state.value = 'unavailable'
+      error.value = err instanceof EchoApiError ? err.message : '无法连接 Echo 服务'
+      scheduleRetry()
+    }
+  }
+
+  function scheduleRetry() {
+    if (retryTimer) clearTimeout(retryTimer)
+    retryTimer = setTimeout(check, 30000)
+  }
+
+  function cancel() {
+    controller?.abort()
+    controller = null
+    if (retryTimer) {
+      clearTimeout(retryTimer)
+      retryTimer = null
+    }
+  }
+
+  onMounted(() => {
+    check()
+  })
+
+  watch(articleId, () => {
+    cancel()
+    check()
+  })
+
+  onUnmounted(() => {
+    cancel()
+  })
+
+  return { state, status, error, retry: check }
+}

package/docs/.vitepress/theme/lib/useProjectFilter.ts

@@ -0,0 +1,42 @@
+import { ref, computed } from 'vue'
+import { getProjects } from './echo-api'
+
+interface Project {
+  id: string
+  name: string
+  root: string
+  dataRoot: string
+}
+
+// Module-level state for cross-component sharing
+const selected = ref<string>('__all__')
+const projects = ref<Project[]>([])
+const loaded = ref(false)
+
+export function useProjectFilter() {
+  const selectedProject = computed(() => selected.value)
+  const allProjects = computed(() => projects.value)
+
+  async function load() {
+    if (loaded.value) return
+    try {
+      const result = await getProjects()
+      projects.value = result.projects || []
+      loaded.value = true
+    } catch (_) {}
+  }
+
+  function select(projectId: string) {
+    selected.value = projectId
+    try { localStorage.setItem('echo-project-filter', projectId) } catch (_) {}
+  }
+
+  function restore() {
+    try {
+      const saved = localStorage.getItem('echo-project-filter')
+      if (saved) selected.value = saved
+    } catch (_) {}
+  }
+
+  return { selectedProject, allProjects, load, select, restore }
+}

package/docs/index.md

@@ -0,0 +1,89 @@
+---
+layout: home
+
+hero:
+  name: "Echo"
+  text: "本地优先的 AI 对话知识论坛"
+  tagline: 把 AI 编程会话捕获为不可变的 Markdown 文章，支持浏览、搜索、标签、评论、MCP 访问。
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /../GETTING_STARTED.md
+    - theme: alt
+      text: 完整文档
+      link: /../README.md
+
+features:
+  - icon: 📝
+    title: 不可变归档
+    details: 文章正文一旦创建即不可修改。AI 对话作为源记录永久保存，后续整理通过标签、评论、标注完成。
+  - icon: 🔴
+    title: Live Session 实时预览
+    details: 正在聊天的内容通过 live session 页面实时查看，前端心跳自动检测更新，无需手动刷新。
+  - icon: 🤖
+    title: MCP AI 接口
+    details: 9 个 MCP 工具让 AI 助手直接读取、搜索 Echo 本地归档，成为 AI 的长期记忆。
+  - icon: 📁
+    title: 多项目支持
+    details: 每个项目独立管理，会话自动归入对应项目。空目录需显式注册，未注册目录降级写入 legacy buffer。
+  - icon: 🔍
+    title: 全文搜索
+    details: 本地搜索索引，通过 CLI 或网页快速找到历史对话中的关键信息。
+  - icon: 🏷️
+    title: 标签管理
+    details: 为文章打标签、分类整理，支持添加、移除、重命名、删除标签，构建个人知识体系。
+---
+
+## 一分钟了解 Echo
+
+Echo 在你和 AI 聊天时自动捕获会话，转成 Markdown 文章，并在本地网页上展示。你不需要手动整理——hook 会静默工作。
+
+**安装只需三步：**
+
+```bash
+cd echo-prototype && npm install && npm link   # 安装 CLI
+echoctl init && echoctl init project            # 注册项目
+echoctl hook install claude --write             # 安装捕获 hook
+```
+
+然后启动网页：
+
+```bash
+echoctl serve
+```
+
+浏览器打开显示的地址，就能看到你的 AI 对话文章了。
+
+**核心命令速览：**
+
+| 命令 | 用途 |
+|---|---|
+| `echoctl serve` | 后台启动本地网页和 API |
+| `echoctl stop` | 停止后台服务 |
+| `echoctl status` | 查看 Echo 全面状态 |
+| `echoctl all` | 手动跑完整管线（convert → validate → index） |
+| `echoctl refresh` | 不重启 serve 刷新页面 |
+| `echoctl search -- --keyword "关键词"` | 全文搜索文章 |
+| `echoctl tag add <id> <tag>` | 给文章加标签 |
+| `echoctl project list` | 查看已注册项目 |
+
+**MCP 接入（让 AI 读你的归档）：**
+
+```json
+{
+  "mcpServers": {
+    "echo": {
+      "command": "echoctl",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+配置后 AI 助手即可通过 `search_articles`、`get_article`、`list_recent` 等工具访问你的 Echo 归档。
+
+---
+
+> **状态：开发中，未发布 npm。** 当前通过 `npm link` 使用开发版。
+>
+> 更多文档：[上手指南](/../GETTING_STARTED.md) · [完整 README](https://github.com/daxiguaguagua-hash/echo/blob/main/README.md) · [使用指南 V3](/../USAGE_GUIDE_V3.md) · [工程边界](/../ENGINEERING_BOUNDARIES.md) · [项目进度](/../ECHO_STATUS.md)

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "echoctl",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "private": false,
+  "license": "MIT",
   "description": "Local-first AI conversation knowledge forum — capture, search, and annotate Claude Code sessions as Markdown articles with MCP server support",
-  "keywords": ["echo", "knowledge-forum", "ai-conversations", "markdown", "local-first", "mcp", "claude-code", "cli"],
+  "keywords": [
+    "echo",
+    "knowledge-forum",
+    "ai-conversations",
+    "markdown",
+    "local-first",
+    "mcp",
+    "claude-code",
+    "cli"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },
@@ -51,6 +61,5 @@
     "gray-matter": "^4.0.3",
     "vitepress": "^1.6.4"
   },
-  "devDependencies": {
-  }
+  "devDependencies": {}
 }

package/scripts/build-docs.js

@@ -7,7 +7,7 @@ const store = require("./lib/infra/markdown-store");
 const { stripCommentSections } = require("./lib/usecases/strip-comments");
 const { TURN_MARKER_REGEX } = require("./lib/domain/echo-format");
 
-const PACKAGE_DOCS_ROOT = path.resolve(__dirname, "../../docs");
+const PACKAGE_DOCS_ROOT = path.resolve(__dirname, "../docs");
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 
 function defaultDocsRoot() {