echoctl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VincentHuang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Echo — 本地优先的 AI 对话知识论坛
+
+Echo 把 Claude Code / AI 编程会话捕获成 Markdown 文章，并提供本地网页用于浏览、搜索、打标签和评论。
+
+核心原则：**文章正文不可变**。AI 对话一旦转成文章，就作为源记录保存；后续整理通过标签、评论、标注和派生内容完成。
+
+## 当前使用方式
+
+> [!TIP]
+> **AI 时代的安装方法：**可以将当前页面交给 AI，让它帮你安装和配置 Echo。
+
+### 1. 安装开发版 CLI
+
+```bash
+cd /Users/vincenthuang/myNote/echo-prototype
+npm install
+npm link
+```
+
+确认命令可用：
+
+```bash
+echoctl --version
+```
+
+### 2. 在你的项目目录初始化
+
+每个要被 Echo 收集的文件夹都需要注册一次。未注册目录里的对话会落到 legacy buffer，不会自动显示在网页“项目”分组里。
+
+```bash
+mkdir -p ~/echo-notes
+cd ~/echo-notes
+
+echoctl init
+echoctl init project
+echoctl doctor
+```
+
+### 3. 安装 Claude Code hook
+
+```bash
+echoctl hook install claude --write
+echoctl hook doctor
+```
+
+之后你在已注册项目目录里和 AI 聊天，hook 会把会话写入：
+
+```text
+~/.echo-workspace/projects/<project-id>/session-buffer/
+```
+
+### 4. 启动本地网页
+
+```bash
+echoctl serve
+```
+
+`serve` 默认后台运行，并在启动时自动执行一次：
+
+```text
+convert → validate → index → resolve → build docs
+```
+
+启动后会显示类似：
+
+```text
+Echo服务在后台运行 / Echo serve started in background
+
+Docs / 访问地址             http://127.0.0.1:5173/
+API / 接口地址              http://127.0.0.1:8787/
+State / 状态文件            ~/.echo-workspace/.serve.json
+Log / 日志文件              ~/.echo-workspace/.serve.log
+
+echoctl serve              # 后台启动 / Start in background
+echoctl serve --foreground # 前台调试 / Run in foreground for debugging
+echoctl stop               # 停止服务 / Stop Echo serve
+echoctl capture on/off     # 控制 AI 聊天记录收集 / Toggle AI chat logging
+```
+
+打开 `Docs / 访问地址` 即可浏览文章。
+
+### 5. 日常命令
+
+| 命令 | 用途 |
+|---|---|
+| `echoctl serve` | 后台启动本地网页和 API |
+| `echoctl serve --foreground` | 前台启动，方便调试 |
+| `echoctl stop` | 停止后台服务 |
+| `echoctl capture status` | 查看是否正在收集 AI 聊天记录 |
+| `echoctl capture on` | 开启收集 |
+| `echoctl capture off` | 关闭收集 |
+| `echoctl project list` | 查看已注册项目 |
+| `echoctl project find <id>` | 查看项目详情 |
+| `echoctl all` | 手动跑完整管线 |
+| `echoctl search -- --keyword "关键词"` | 搜索文章 |
+| `echoctl tag list` | 查看标签 |
+| `echoctl tag add <article-id> <tag>` | 给文章加标签 |
+| `echoctl tag remove <article-id> <tag>` | 移除标签 |
+
+## 重要边界
+
+### 空文件夹不会自动变成项目
+
+如果你新建一个空文件夹后直接聊天，但没有执行：
+
+```bash
+echoctl init project
+```
+
+那么会话会降级写入：
+
+```text
+~/.echo-workspace/session-buffer/
+```
+
+这个 legacy buffer 不会自动出现在网页项目列表里。正确流程是：
+
+```bash
+cd ~/new-project
+echoctl init project
+echoctl serve
+```
+
+### 当前还不是实时刷新
+
+`echoctl serve` 会在启动时自动跑一次管线，但当前版本还没有持续监听新的 `session-buffer`。
+
+也就是说：
+
+| 场景 | 网页是否立刻出现新文章 |
+|---|---|
+| 启动 `serve` 前已经有 buffer | 会显示 |
+| `serve` 已在后台运行，然后继续聊天 | 不会立刻自动出现 |
+| 聊完后重启 `echoctl serve` 或手动 `echoctl all` 后刷新 | 会显示 |
+
+后续计划：给 `serve` 增加 watcher，监听新会话并自动重建页面。
+
+## 数据目录
+
+```text
+~/.echo-workspace/
+  registry.json
+  .serve.json
+  .serve.log
+  session-buffer/             # 未注册目录的 legacy fallback
+  projects/
+    <project-id>/
+      session-buffer/
+      articles/
+      comments/
+      index/
+  .site/                      # echoctl serve 生成的 VitePress 站点
+```
+
+## 开发命令
+
+这些命令主要给 Echo 项目开发者使用，普通使用优先用 `echoctl`。
+
+```bash
+cd /Users/vincenthuang/myNote/echo-prototype
+
+npm test
+npm run all
+npm run docs:generate
+```
+
+## 更多文档
+
+- [USAGE_GUIDE_V3.md](USAGE_GUIDE_V3.md) — 多项目模型和手动验证流程
+- [ENGINEERING_BOUNDARIES.md](ENGINEERING_BOUNDARIES.md) — 工程边界和路径模型
+- [ECHO_STATUS.md](ECHO_STATUS.md) — 当前进度和已知问题

package/bin/echoctl.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../scripts/cli/echoctl.js");

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "echoctl",
+  "version": "0.1.0",
+  "private": false,
+  "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"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daxiguaguagua-hash/echo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/daxiguaguagua-hash/echo/issues"
+  },
+  "homepage": "https://github.com/daxiguaguagua-hash/echo#readme",
+  "files": [
+    "bin/",
+    "scripts/",
+    "docs/.vitepress/",
+    "docs/index.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm test && npm run all",
+    "test": "node --test",
+    "verify": "npm run test && npm run validate && npm run resolve",
+    "validate": "node scripts/validate.js",
+    "index": "node scripts/index.js",
+    "resolve": "node scripts/resolve.js",
+    "convert": "node scripts/convert.js",
+    "annotate": "node scripts/annotate.js",
+    "import": "node scripts/import-sessions.js",
+    "search": "node scripts/search.js",
+    "mcp": "node bin/echoctl.js mcp",
+    "all": "node bin/echoctl.js all",
+    "docs:generate": "node scripts/build-docs.js",
+    "docs:dev": "npm run docs:generate && vitepress dev ~/.echo-workspace/.site",
+    "docs:build": "npm run docs:generate && vitepress build ~/.echo-workspace/.site",
+    "docs:preview": "npm run docs:generate && vitepress preview ~/.echo-workspace/.site",
+    "serve": "node bin/echoctl.js serve",
+    "prepare": "mkdir -p bin && printf '#!/usr/bin/env node\\nrequire(\"../scripts/cli/echoctl.js\");\\n' > bin/echoctl.js && chmod +x bin/echoctl.js"
+  },
+  "bin": {
+    "echoctl": "./bin/echoctl.js",
+    "echo-mcp": "./bin/echoctl.js"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "vitepress": "^1.6.4"
+  },
+  "devDependencies": {
+  }
+}

package/scripts/annotate.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const store = require("./lib/infra/markdown-store");
+const { writeComment } = require("./lib/usecases/write-comment");
+
+function runAnnotate(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const evOf = opts.evolutionOf ? opts.evolutionOf.split(",").map((s) => s.trim()).filter(Boolean) : [];
+
+  const result = writeComment({
+    articleId: opts.articleId,
+    quote: opts.quote,
+    comment: opts.commentText,
+    author: opts.author,
+    evolutionKind: opts.evolutionKind || "null",
+    evolutionOf: evOf,
+    status: opts.status || "open",
+    dirs,
+    store,
+  });
+
+  console.log(`Created: comments/${result.id}.md`);
+  console.log(`  article: ${opts.articleId}`);
+  if (opts.quote) console.log(`  quote:   ${opts.quote.slice(0, 60)}${opts.quote.length > 60 ? "..." : ""}`);
+  if (evOf.length > 0) console.log(`  replies: ${evOf.join(", ")}`);
+
+  return result;
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  function flag(name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : null;
+  }
+
+  const articleId = flag("article");
+  const quote = flag("quote");
+  const commentText = flag("comment");
+  const author = flag("author") || "vincent";
+  const evolutionKind = flag("evolution-kind") || "null";
+  const evolutionOf = flag("evolution-of");
+  const status = flag("status") || "open";
+
+  if (!articleId || !quote || !commentText) {
+    console.log("Usage: node scripts/annotate.js --article <id> --quote \"<text>\" --comment \"<text>\" [--author <name>] [--evolution-of <id>] [--evolution-kind <kind>]");
+    console.log("");
+    console.log("  --article        Article ID (from frontmatter)");
+    console.log("  --quote          Exact text to annotate");
+    console.log("  --comment        Your comment text");
+    console.log("  --author         Default: vincent");
+    console.log("  --evolution-of   Comma-separated annotation IDs this replies to");
+    console.log("  --evolution-kind refines | contradicts | expands | supersedes | null");
+    console.log("  --status         Default: open");
+    process.exit(1);
+  }
+
+  try {
+    runAnnotate({ articleId, quote, commentText, author, evolutionKind, evolutionOf, status });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    if (err.availableArticles) {
+      console.log("Available articles:");
+      for (const a of err.availableArticles) {
+        console.log(`  ${a.id}  (${a.relPath})`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { runAnnotate };