ethan-agent
CLAUDE.md8 starsChanged yesterdayMITView on GitHub
禁止在主仓库 /Users/jsongo/code/life/ethan-ai 直接开发 feature。 主仓库始终保持在 main 分支,只用于: - 拉取最新 main:git pull - 查看 main 上的文件 - 创建/删除 worktree - 合并 PR 后清理 worktree 所有 feature 开发必须在 worktree 中进行: 命名约定: - worktree 目录:ethan-ai-<kebab-case-name>(放在主仓库同级目录) - 分支名:feature/<kebab-case-name> 已有 worktree 列表:git worktree list 问题:ethan 的 watchdog 机制通过 /tmp/ethan/server.pid 管理服务进程。多个 worktree 同时启动 ethan serve 会互相冲突——watchdog 会杀掉 PID 文件指向的进程,导致非主实例被误杀。 已落地的缓解措施: - ethan serve 启动前先拿 flock 单实例锁(ethan/interface/serve_lock.py,锁文件 /tmp/ethan/serve-<port>.lock):上面的检测都是「先查后做」,两个进程同时启动会同时查到「没人」,然后一起跑完数十秒 lifespan 才在 bind 撞 Errno 48,而 uvicorn 绑失败不退出 → 僵尸进程。锁把「检查 + 启动」变成原子区间,后到者立刻以退出码 1 失败并报出持有者 pid。锁由内核随进程退出释放,无陈旧锁;ETHAN_NO_WATCHDOG=1 时按「端口 + 数据目录」分桶;--force 不加锁;Windows…
- Reads credentials
- Commits and pushes
In this repository2 other files it gives its agents.
- web/AGENTS.mdAGENTS.md
- web/CLAUDE.mdCLAUDE.md
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 93
ALWAYS run the code and verify it passes after modifying it: Never stop after just modifying code without running a local test to catch …
- Very specific: line 95
Never write literal newlines inside f-strings: Use \n escape sequences instead (e.g., f"line1\nline2", never a real line break inside an …
- Very specific: line 99
Review
docs/after any feature change: When a new feature is added or existing behavior is changed, check whether any file in docs/ … - Distinctive: line 109
When the user says "发版" or "release":
- Very specific: line 111
Read current version from pyproject.toml (version = "X.Y.Z")
- Very specific: line 113
Default: increment patch → X.Y.Z+1
- Very specific: line 116
Update pyproject.toml with the new version.
- Distinctive: line 130
Create and push the tag — this triggers the GitHub Action which builds and publishes to PyPI:
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ethan Agent - Project Instructions
Worktree 工作流(必须遵守)
禁止在主仓库 /Users/jsongo/code/life/ethan-ai 直接开发 feature。 主仓库始终保持在 main 分支,只用于:
- 拉取最新 main:
git pull - 查看 main 上的文件
- 创建/删除 worktree
- 合并 PR 后清理 worktree
所有 feature 开发必须在 worktree 中进行:
# 创建 worktree(从最新 main 切出新分支)
git pull
git worktree add ../ethan-ai-<feature-name> -b feature/<feature-name>
# 进入 worktree 开发
cd ../ethan-ai-<feature-name>
# ... 编码、提交、推送、创建 PR ...
# PR 合并后清理
git worktree remove ../ethan-ai-<feature-name>
git branch -d feature/<feature-name>命名约定:
- worktree 目录:
ethan-ai-<kebab-case-name>(放在主仓库同级目录) - 分支名:
feature/<kebab-case-name>
已有 worktree 列表:git worktree list
多 worktree 开发的服务启动规范
问题:ethan 的 watchdog 机制通过 /tmp/ethan/server.pid 管理服务进程。多个 worktree 同时启动 ethan serve 会互相冲突——watchdog 会杀掉 PID 文件指向的进程,导致非主实例被误杀。
已落地的缓解措施:
ethan serve启动前先拿flock单实例锁(ethan/interface/serve_lock.py,锁文件/tmp/ethan/serve-<port>.lock):上面的检测都是「先查后做」,两个进程同时启动会同时查到「没人」,然后一起跑完数十秒 lifespan 才在 bind 撞 Errno 48,而 uvicorn 绑失败不退出 → 僵尸进程。锁把「检查 + 启动」变成原子区间,后到者立刻以退出码 1 失败并报出持有者 pid。锁由内核随进程退出释放,无陈旧锁;ETHAN_NO_WATCHDOG=1时按「端口 + 数据目录」分桶;--force不加锁;Windows 无fcntl自动降级。ethan serve启动前会检测重复实例(cli.py的_find_conflicting_servers()):判据是「是否打开同一个sessions.db」(不是同端口——两个实例用不同端口照样互锁),命中就报错退出并列出冲突 PID,避免多个实例并发写导致database is locked(历史上表现为「对话卡住没响应」,其实不是性能问题)。ETHAN_NO_WATCHDOG=1会跳过这个检测——它的语义就是「我在开发/测试,别管我」。worktree 里跑测试时sessions.db和已 install 的常驻服务是同一个文件,不放行会把下面的开发流程整个堵死。- 不想设环境变量时也可用
ethan serve --force(不推荐,真的会锁冲突)。
- 监听地址可在
config.yaml配:server.host/server.port,优先级 显式--port> config > 默认 8900,ETHAN_SERVER_HOST/ETHAN_SERVER_PORT环境变量再覆盖前两者。watchdog 的端口扫描(_kill_server的lsof -ti :<port>)已参数化跟随实际端口,不再写死 8900 误杀。watchdog 会把监控端口写进/tmp/ethan/watchdog.port,ensure_watchdog_running复用前比对,端口不一致就换掉旧的(否则改端口后会复用到盯旧端口的 watchdog)。
规则:
- 默认端口 8900 同一时间只能有一个实例。watchdog 只监控被拉起时传入的端口,非该端口的实例会被 watchdog 视为"server 死亡"并触发重启,可能杀掉其他实例。
- 开发测试时使用随机端口(8901-8999 之间),但要意识到:
- 启动的实例不要写入
/tmp/ethan/server.pid(否则会被 watchdog 杀) - 实例可能被 watchdog 的端口扫描误杀(
_kill_server会扫描它被指派的端口;若该端口恰好是你的测试端口则会误杀) - 优先用
ethan -p "prompt" --yes单轮模式测试,不启动常驻服务
- 启动的实例不要写入
- 浏览器插件测试:浏览器插件通过
ws://localhost:<port>/ws/browser连接 ethan。测试前确认:- ethan 服务在监听目标端口
- 系统代理(如
127.0.0.1:7890)会拦截 ws 连接,浏览器插件需绕过代理或配置 no_proxy - 可用
NO_PROXY=localhost,127.0.0.1验证连接是否正常
- 启动命令示例(worktree 开发测试):
# 随机端口 8901-8999,避开 8900(watchdog 占用)和已用端口 # ETHAN_NO_WATCHDOG=1 跳过重复实例检测 + PID 写入 + watchdog,避免与其他实例冲突 PORT=$((RANDOM % 99 + 8901)) ETHAN_NO_WATCHDOG=1 .venv/bin/ethan serve --host 127.0.0.1 --port $PORT - 不要
pkill -f "ethan serve":会误杀其他 worktree 的实例。只 kill 自己启动的 PID。 ETHAN_NO_WATCHDOG=1环境变量:代码级开关(api.py+heartbeat.py),设为 1 时:- 不写
/tmp/ethan/server.pid(避免被 watchdog 杀) - 不拉起 watchdog 进程(避免接管其他实例)
- heartbeat 不检查 watchdog 存活(避免互相拉起) 开发测试时必须带这个环境变量。
注意:
ethan serve默认(不设该变量)会写入/tmp/ethan/server.pid并自动拉起 watchdog。目前没有--no-pid之类的独立命令行参数,唯一的开关就是这个环境变量。上面的启动示例(第 4 条)已带ETHAN_NO_WATCHDOG=1,正是为了跳过 PID 写入——请勿删除该变量,否则仍会写 PID、被 watchdog 误杀。- 不写
Web / Desktop 双端同步规范(必须遵守)
本项目同时维护两个前端:
- Web:
/web(Next.js App Router) - Desktop:
/desktop(Vite + React + Tauri)
两端共享相同的业务逻辑和组件集,任何新功能必须同时在两端实现,不允许只加一端。
规则:
- 新增组件/Hook:在一端实现后,必须同步到另一端。注意适配差异:
- Web 文件需要
"use client"指令 - Web 用
API_URL常量(process.env.NEXT_PUBLIC_API_URL),Desktop 用getApiUrl()函数 - Web 用
useRouter()/usePathname()(next/navigation),Desktop 用useNavigate()/useLocation()(react-router-dom)
- Web 文件需要
- 新增 API 函数:同步到两端的
lib/api*.ts,保持函数签名一致。 - 新增路由/页面:两端路由需对应(Web:
app/<name>/page.tsx,Desktop:pages/<Name>Page.tsx+ App.tsx 路由注册)。 - PR 检查:提交前确认改动是否只涉及一端,如是则需补齐另一端。
已知允许的差异:
- Desktop 独有
lib/external-link.ts(Tauri shell 打开外链) - Desktop 独有 Tauri 窗口拖拽相关 CSS(
-webkit-app-region) - Web 独有
app/a2ui-test/page.tsx(纯开发调试页,无需同步)
Agent Behaviors & Rules
- ALWAYS run the code and verify it passes after modifying it. Never stop after just modifying code without running a local test to catch IndentationError, SyntaxError, or logic errors. Use
uv run ...or node scripts to verify. - Never write literal newlines inside f-strings. Use
\nescape sequences instead (e.g.,f"line1\nline2", never a real line break inside an f-string). Literal newlines in f-strings cause SyntaxError in Python < 3.12. - Always update both READMEs together.
README.mdandREADME_CN.mdmust stay in sync — never update one without updating the other. - Review
docs/after any feature change. When a new feature is added or existing behavior is changed, check whether any file indocs/describes the affected area and update it if needed. - New tools: decide
no_compressbased on whether output is read vs. reused. Tool output over 4000 chars is auto-compressed by a cheap model into a ~1200-char summary before reaching the main model (ethan/tools/registry.py). That's fine when the output is prose for the model to read (web pages, shell logs, search results) — let it compress. But if the output contains data the model must pass back verbatim — IDs, refs, coordinates, file paths, structured JSON (e.g. browser tab_id/session_id, snapshot refs, skill instructions, ui_card structures) — setno_compress = Trueon the tool class. Otherwise compression mangles the IDs into a prose summary and the model can no longer act on them (symptom: "it listed the items but couldn't operate on them"). When in doubt, ask: is this output for the model to read, or to feed back as a parameter? The latter needsno_compress. - 文件过长就拆分:改代码时若发现某个单文件超过 1000 行,顺手做模块拆分,把单文件控制在 700 行以内。 识别出超长文件后不要放着不管(也不要为了让行数达标而机械切割),按职责/关注点拆成若干内聚的模块,保持对外接口不变(用 re-export 兜住旧引用路径),改完必须跑通测试与类型检查。拆分本身要单独说明,不要混在无关的功能改动里。
- Reviewing PRs: comment as the user, in Chinese, only on the most severe issues. When asked to review a PR, post comments under the user's identity (not Claude's). Write in Chinese, short and human-sounding (casual tone, like the user wrote it). Only call out the 1-3 most serious problems worth acting on — mention minor/cleanup issues in one trailing line at most, or skip them. Don't post the full structured review. Keep the tone gentle and friendly, not blunt or commanding — these are someone else's PRs. Prefer soft phrasing like "可以关注下 / 建议看看" over "很要命 / 先修这俩". Stay 和气. Phrase suggested fixes as questions, not imperatives — say "改成 suspend 是不是好些?" / "是不是可以删掉这个 stub?" instead of "改成 suspend" / "删掉这个 stub". Anchor each comment to the specific line/code it's about — post inline review comments via
gh api repos/{owner}/{repo}/pulls/{n}/comments(withcommit_id,path,line,side=RIGHT), NOT a single lump comment in the general conversation area.
Publishing to PyPI
When the user says "发版" or "release":
- Read current version from
pyproject.toml(version = "X.Y.Z") - Bump the version:
- Default: increment patch →
X.Y.Z+1 - User says "中版本" / minor: increment minor →
X.Y+1.0 - User says "大版本" / major: increment major →
X+1.0.0
- Default: increment patch →
- Update
pyproject.tomlwith the new version. Regenerate
uv.lockso the lockfile'sethan-agentversion followspyproject.toml:uv lockThis is easy to forget — a bump that only touches
pyproject.tomlleavesuv.locka version behind, and the drift accumulates silently across releases. Alwaysgit add uv.lockin the next step, and confirmuv lock --checkpasses.Most bumps are not done by hand.
auto-bump-version.ymlbumps the patch on every merge to main, and it runsuv lock+git add uv.lockitself (fixed after the lock sat 3 versions behind: pyproject 0.5.278 / lock 0.5.275). The manual steps below are for an explicit "发版" with a chosen version (minor/major). If you bump by hand, you must still syncuv.lockyourself — nothing else will.- Create and push the tag — this triggers the GitHub Action which builds and publishes to PyPI:
git add pyproject.toml uv.lock git commit -m "chore: bump version to vX.Y.Z" git tag vX.Y.Z git push origin main git push origin vX.Y.Z
The GitHub Action (.github/workflows/publish-pypi.yml) triggers on v* tags, reads the version from the tag name, injects it into pyproject.toml, builds, and publishes via uv publish. No manual PyPI interaction needed after the tag is pushed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

