EchoLog

本地优先（local-first）的个人活动记录与复盘引擎——给人用，也给 AI agent 用。

用 el CLI 或 Web 控制台记录你在做什么（学习 / 项目 / 任务，支持多任务并行、暂停恢复、笔记与阻塞项）；macOS 上被动采样屏幕前台应用；每天自动汇总并生成 Markdown 日报。所有数据存在你自己的 PostgreSQL 里，不上传任何地方。

对 OpenClaw、Claude Code、Codex 等 agent，EchoLog 的设计目标是开箱即被工具化：CLI 就是工具面，el --help 就是工具说明书，--json 给出机器可读输出，错误一律非 0 退出码 + 结构化错误体。

功能

活动记录：start / stop / pause / resume / cancel，类型 learning | project | task，标签、项目归属、结果总结；多任务并行
父子任务：一个大任务可挂多层小任务；服务端防止自指/成环，CLI 与 Web 可创建、查询并查看直接子任务进度
笔记：给任意记录追加 note | blocker | next
补录与编辑：el add --at --for、el edit
内置插件：screen-time 采样和追溯分类前台应用；tmux-status 通过外部 CLI 提供结构化 pane/资源观测，并以 v3 合约持久化已验证的 Agent conversation↔pane 恢复映射
汇总与日报：今日/指定日汇总、日报 Markdown 生成、可同步到指定目录
提醒（可选）：任务超时、空闲提醒、macOS 通知 + ntfy 推送到手机
四个入口，一套 REST API：免构建的 Web 控制台、el CLI、本地 stdio MCP、HTTP API（docs/API.md）

快速开始

要求：Node.js ≥ 22、pnpm、Docker（跑 PostgreSQL）。

git clone https://github.com/CubePlus1/echolog.git && cd echolog
pnpm install
docker compose up -d                 # PostgreSQL 16，本机端口 5436
cp config.yaml.example config.yaml   # 按需改；apiKey 建议 openssl rand -hex 24
pnpm migrate                         # 建表
pnpm build
node dist/server/app.js              # 或开发模式 pnpm dev

打开 http://localhost:19827 即可看到 Web 控制台。

把 CLI 放进 PATH（任选其一）：

# 方式一：wrapper（推荐，重新 build 不用重装）
printf '#!/bin/sh\nexec node %s/dist/cli/index.js "$@"\n' "$PWD" | sudo tee /usr/local/bin/el >/dev/null
sudo chmod +x /usr/local/bin/el

# 方式二：直接用
node dist/cli/index.js status

el start "读《史记》三十页" --type learning -t 读书
el start "整理人物关系" --parent <父任务id>
el subtasks <父任务id>          # 直接子任务 + 完成进度
el note "卡在第三章" -b        # 给唯一活跃任务加阻塞项，无需 id
el stop -n "读毕，摘记三条"
el today
el report                        # 输出日报 Markdown

给 AI Agent 用

约定（详见仓库根的 AGENTS.md，agent 可直接读取）：

工具面 = el CLI。el --help 与各子命令 --help 包含语义、参数取值枚举、时间格式与示例，按工具说明书标准编写
机器可读：所有命令支持 --json，输出 API 原始 JSON，不二次包装
退出码契约：成功 0；连接失败 / 校验失败 / 404 / 409 等一律非 0，错误走 stderr 或 JSON 错误体 {"error", ...}
省略 id 的 stop/pause/resume/note/cancel 由服务端匹配唯一活跃记录；歧义时返回 409 和候选列表 {"error", "candidates":[{id,title,status}]}，按提示带 id 重试
无 shell 的 agent 可直接走 HTTP API（docs/API.md）；跨机器访问带 X-API-Key
支持 MCP 的本机 agent 可注册 el mcp；工具清单、错误契约与 Codex 配置见 MCP Server

el status --json          # 今日概览 + 活跃任务
el log --json -n 50       # 历史记录
el screen --json          # 今日屏幕使用（macOS）
el plugins list --json    # 内置插件清单与状态
el tmux status --json     # tmux-status 原始快照（插件默认禁用）

Codex 集成

仓库提供一个可安装的 Codex Plugin 包：integrations/codex/echolog。它组合显式写入的 $echolog:track-work、只读复盘的 $echolog:review-work 和自动注册的本地 el mcp（8 个类型化工具）；standalone Skill 则使用无前缀名称，也保留手动 MCP 注册方式。Skills 与 MCP 都只经 HTTP API 访问 daemon，不直连数据库，也不复制服务端的唯一活跃记录和父子关系判断。

该 Codex Plugin 与 EchoLog Core 的 Bundled Plugin API v1 是不同层次：前者运行在 Codex 侧，后者运行在 EchoLog 服务内。personal marketplace 安装/更新、支持范围、前置条件与隐私边界见 Codex Integration。

配置

config.yaml（参考 config.yaml.example）：

段	说明
`server`	端口（默认 19827）、`apiKey`（本机豁免，非本机必带）、`serveWeb`（false = 纯 API 服务）、`corsOrigins`（跨源白名单，默认不允许跨源）
`database`	PostgreSQL 连接（与 docker-compose 默认值对应）
`plugins.screen-time`	屏幕采样开关、频率与空闲阈值（默认启用）
`plugins.tmux-status`	外部 executable、超时、采样频率、异常阈值，以及 v3 Agent conversation↔pane 恢复映射（默认禁用）
`sync`	日报 Markdown 同步目标目录
`notifications`	macOS 通知、ntfy 推送、超时/空闲/日报提醒规则

el 默认读取 EchoLog 安装根目录的 config.yaml，不会误读当前 Codex 工作目录中其他项目的同名文件。测试或多实例部署需要替代配置时，显式设置 ECHOLOG_CONFIG_PATH=/absolute/path/to/config.yaml。

常驻运行（macOS launchd 示例）

<!-- ~/Library/LaunchAgents/com.echolog.daemon.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.echolog.daemon</string>
  <key>ProgramArguments</key><array>
    <string>/usr/local/bin/node</string><string>dist/server/app.js</string>
  </array>
  <key>WorkingDirectory</key><string>/path/to/echolog</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/echolog.stdout.log</string>
  <key>StandardErrorPath</key><string>/tmp/echolog.stderr.log</string>
</dict></plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.echolog.daemon.plist
# 更新代码后：pnpm build && launchctl kickstart -k gui/$(id -u)/com.echolog.daemon

架构

Web Shell / el CLI / el mcp
        |
     HTTP API
        |
EchoLog Core (records, notes, subtasks, reports, sync)
        |
Bundled Plugin API v1
        |-- screen-time
        `-- tmux-status -> external tmux-status executable

Codex Plugin Skills -> el --json ---------^
Codex MCP host ------> el mcp ------------^

一切能力沉在服务端：客户端不复刻推断/校验逻辑；CLI、Web 和 MCP 都以 HTTP 瘦客户端形式接入。开发工作流由 Trellis 管理，编码规范见 .trellis/spec/。

插件协议、信任边界、manifest、生命周期、迁移和错误码见 Bundled Plugin API v1。

产品路线与任务管理

EchoLog 的近期方向不是做普通的工时计时器，而是成为本地优先、面向 AI agent 的个人工作记忆与复盘系统：既记录做过什么，也帮助回看能力如何积累、下一步往哪里走。

当前路线

P0 · 大任务支持子任务：记录支持多层父子关系，父任务可查看直接子任务和完成进度；后端/API、CLI、Web 分为三个实施子任务。
- GitHub：P0 Issue #1（#4 后端/API · #5 CLI · #6 Web）
- Trellis：.trellis/tasks/07-17-p0-record-subtasks/
P0 · 可视化左页命中 Bug：修复 CSS 3D 翻页后，书本左页内部的目录、任务和父子导航按钮无法点击的问题；这是独立 P0，不从属于父子任务能力。
- GitHub：P0 Bug #3
- Trellis：.trellis/tasks/07-17-p0-visual-left-button/
P0 · 关闭任务无需二次确认：Web 端点击“罢”后直接作废任务，保留操作结果提示，不再弹出确认框。
- GitHub：P0 Bug #7
- Trellis：.trellis/tasks/07-18-p0-close-no-confirm/
P1 · 个人成长路径可视化：以时间、项目、标签、学习主题、结果、阻塞项和下一步为证据，生成可回溯的成长时间轴。
- GitHub：P1 Issue #2
- Trellis：.trellis/tasks/07-17-p1-growth-path-visualization/
P1 · 人类 / Agent 工时与工作里程碑：区分人类投入、Agent 运行、并行重叠和端到端历时；阶段完成时记录成果摘要、验证证据与工时快照，用于复盘和后续工作量估算。
- GitHub：P1 Issue #8
- Trellis：.trellis/tasks/07-22-p1-actor-effort-milestones/
P1 · 内置插件架构：Core 插件平台与 screen-time 拆分已实现；tmux-status v3 已实现 canonical schema/fixtures、v1/v2/v3 兼容解析、幂等定时同步和已验证的 Agent conversation↔pane 恢复映射。跨仓库 drift 远程门禁仍待只读 token 启用；显式 link 与 Agent 工时继续依赖前述 actor/span Core 能力。
- GitHub：P1 Issue #10（EchoLog v3 同步 #19 · EchoLog PR #20 · tmux-status v3 合约 #1 · tmux-status PR #3）
- Trellis：.trellis/tasks/08-03-tmux-status-contract-v3-sync/
- Trellis：.trellis/tasks/07-31-plugin-architecture/
P1 · Codex 集成：按顺序交付 Skills-only Plugin、本地 stdio MCP 适配层、Plugin 打包与发布验收；每一步独立 Issue、PR 和 review。
- GitHub：✅ #13 Skills MVP → ✅ #14 MCP 适配 → ✅ #15 打包发布
- Trellis：.trellis/tasks/08-03-codex-integration/
P1 · screen-understanding 设置基础（当前 PR）：为 screen-time 提供可运行时读取/更新、持久化且带乐观版本控制的理解设置，先建立后续能力所需的配置与 API 边界。
- GitHub：Issue #23 · PR #22
- Trellis：PRD 与验收 · 设计 · 实现计划
- 当前范围仅含 settings 持久化与 GET/PUT /api/plugins/screen-time/understanding/settings 契约；截图采集、图片存储、模型调用、队列/重试和后续理解子任务不在本里程碑内。

三处任务同步规则

README 维护产品方向和里程碑，Trellis 维护实施上下文和验收标准，GitHub Issue 维护公开追踪与关闭记录。后续开发必须遵守：

开始前确认三处指向同一个任务；认领 GitHub Issue，并执行 python3 .trellis/scripts/task.py start <slug> 激活 Trellis task。
一个会话只保留一个当前激活的 Trellis task；独立交付物拆成父任务下的子任务，不把多个目标混在一个实现清单里。
完成后先验证验收标准，再关闭 GitHub Issue、归档 Trellis task，并更新 README 状态；历史 Issue 和归档任务保留，不直接删除。
三处内容冲突时，以已验证的实现和 Trellis task 为准，并在同一变更中同步修正 README 与 Issue。

以上五项互相独立；只有 P0“子任务能力”的后端、CLI、Web 实施项属于父任务 #1。

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.claude		.claude
.github/workflows		.github/workflows
.trellis		.trellis
contracts/tmux-status/v3		contracts/tmux-status/v3
docs		docs
integrations/codex/echolog		integrations/codex/echolog
packages/plugin-sdk		packages/plugin-sdk
plugins		plugins
scripts		scripts
src		src
templates		templates
tests		tests
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
config.yaml.example		config.yaml.example
docker-compose.yml		docker-compose.yml
drizzle.config.ts		drizzle.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Repository files navigation

EchoLog

功能

快速开始

给 AI Agent 用

Codex 集成

配置

常驻运行（macOS launchd 示例）

架构

产品路线与任务管理

当前路线

三处任务同步规则

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

EchoLog

功能

快速开始

给 AI Agent 用

Codex 集成

配置

常驻运行（macOS launchd 示例）

架构

产品路线与任务管理

当前路线

三处任务同步规则

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages