AGENTS.md — Orrery

项目是什么

个人 Agent 驾驶舱（Tauri 2）：跨 harness 会话中枢 + 本地模型代理。先自用，后开源。

当前状态

• 阶段 0B：npm run dev 桌面窗口已跑通（2026-09-14），Claude Code 会话真扫 + 磁盘占用统计
• 前端：ui/（index.html + styles.css + app.js，浏览器 mock / Tauri invoke 双模式）
• 真实扫描：Claude Code、Kimi Code、DSH（DeepSeek）、Codex、OpenCode、Z Code、Antigravity、WorkBuddy、StepCode 九家。Z Code（zcode.rs，只读，用量以 model_usage 为准、逐行按 computed_total_tokens 判断缓存是否已含在 input 里）；Antigravity（antigravity.rs，库只读打开；删除只移走对话自己的文件、不写 agy 的摘要库，正在打开的对话看 presence/<id>.lock 能否读取，每个对话一个 SQLite，用量从 gen_metadata 的 protobuf 按字段号解出，cache_read 与 input 分开记）；OpenCode 删除只经官方 opencode session delete，回收站模式先 opencode export 到 ~/.orrery/exports/。另有通用适配器 custom.rs，读 ~/.orrery/harnesses.json 登记的 OpenCode 系工具（只读、不支持删除与恢复）。WorkBuddy（workbuddy.rs，2026-09-27 接入）只读：~/.workbuddy/projects/<压缩工作目录>/<sessionId>.jsonl 一行一个 item，cwd 直接写在每个 item 上（项目路径无损，不像 Claude Code 要解有损目录名）、标题取 ai-title 那条的 aiTitle、用量按 providerData.messageId 去重（一次请求会拆成 message/function_call/reasoning 多个 item 共用同一份用量）、正在运行的会话读 ~/.workbuddy/sessions/<pid>.json 判活（复用 cleanup::guard::pid_alive）；删除未开放，它是 Electron 应用、没有可调用的终端 CLI 所以也不做恢复。不要把未公开工具的目录名/表结构写进仓库，那属于用户本地配置。StepCode（stepcode.rs，2026-10-09 接入）可删可恢复：~/.stepcode/agent/sessions/--<编码后的 cwd>--/<ISO 时间戳>_<sessionId>.jsonl，目录名把 : \ / 全变成 -（有损），精确 cwd 取首行 {"type":"session",…,"cwd":…}；用量取 assistant 条目的 message.usage 四个桶（互不重叠，totalTokens 恰等于四桶之和，599/599 条），compaction / branch_summary 的 usage 计入，toolResult 里子 agent 的 usage 不计（子 agent 各有会话文件，折进来会双倍）；标题优先 session_info.name（/name 设的显示名），否则第一条真实用户输入（跳过 <system-reminder> 这类注入块）；子 agent 会话按时间包含关系折进父会话（格式里没有父 id，parentSession 只在 /fork 场景出现），匹配不上的按 kind = "subagent" 单独列出；删除就是删 jsonl，没有要清理的文本索引；恢复只能是 step --session <jsonl 绝对路径>（按 id 恢复官方不支持，--session <uuid> / --resume <uuid> / --session-id <uuid> 全部找不到，实测记录见 resume.rs 头部），路径由后端 stepcode::session_file 反查，找不到返回 session_file_missing；状态一律 idle（StepCode 没有活会话登记处）。逐会话对账脚本 scripts/verify-stepcode.mjs
• 模型代理：src-tauri/src/proxy/ 已能真实转发（OpenAI / Anthropic 两种 wire、SSE 透传、应用内启停）；真实供应商联调已通过（作者本机，2026-09）
• 会话转换：src-tauri/src/transfer/，每家一个读取器 + 每个目标一个写入器，中间是 Transcript；现开放 Claude Code、Codex、OpenCode 三家互转。保真标准：不悄悄丢内容。未知记录类型、PDF、链接形式的图片一律拒绝；目标放不下的图片（工具结果里的截图、要进 Codex 的图片）由 transfer/media.rs 存成 ~/.orrery/transfer-media/<转换>/ 下的文件、原位置留路径（owner.json 记归属，经 Orrery 删除目标会话时一并处理），转换前经只读的 preview_transfer 告知张数；工具记录在目标里是带来源标记的历史文本。新增来源/目标前必须：真实会话只读试跑（real_sessions_dry_run）+ 沙盒端到端测试 + 目标工具实际恢复并把历史送进回环假供应商（scripts/verify-*-transfer.mjs；存成文件的图片由 scripts/verify-transfer-media.mjs 验证目标工具能按路径打开并把图片送回模型）。细节见 docs/01-架构与技术路线.md
• 解析索引：~/.orrery/index.json 落盘，冷启动 188 个会话 5.5s → 0.12s
• 在终端恢复：src-tauri/src/resume.rs，各家各自的恢复命令见该文件头部表格；Windows 上找可执行文件必须 .exe/.cmd 优先于无扩展名（npm 的 bash shim 会假装启动成功）- 落地页：site/index.html（单文件，三语，无第三方字体/统计脚本；下载按钮运行时读 GitHub 最新 release 并按系统推荐），.github/workflows/pages.yml 把 site/ 与 .github/assets/ 拼成站点发布到 https://arvelvale.github.io/orrery/ 。页面上的能力说法（含工具能力矩阵 TOOLS）必须与 README「What works today」一致，改功能时一并改。功能截图 site/img/*.{en,zh-CN,ja}.png 是按界面元素边界截的局部（mock 数据，截图时隐藏外框与相邻元素）。迁移 / 清理 / 代理三块功能卡是脚本渲染的交互演示（示例数据，真实截图留在卡片右上角的「应用截图」页签）；它们复述了应用里的规则（迁移时哪些图片存成文件、清理跳过最近 10 分钟有写入的会话并先备份索引、代理只听回环地址），改这些规则时演示要一并改。页面是深色“夜间观测站”基调（应用窗口和三个演示保持应用自己的浅色，放在深色上反差最强），首屏是太阳系仪：每个支持的工具一颗行星，颜色取自应用顶栏的状态灯；字体自托管在 site/fonts/（Geist + 思源黑体 SC/JP 子集，SIL OFL，许可证随附），改了页面文案要跑 scripts/build-site-fonts.mjs 重新生成子集，否则新字会回退到系统字体。中日文标题不要套西文的负字距。动效一律尊重 prefers-reduced-motion（减弱时直接给最终状态），循环类动效（打字、数据包）只在看得见时运行
• 发版：打 v* tag → GitHub Actions 三平台出包（Windows msi/nsis、macOS universal dmg、Linux deb/rpm/AppImage）→ 进草稿 release，人工确认再公开。改版本号要同时改 package.json / tauri.conf.json / Cargo.toml + Cargo.lock，再打 tag
• macOS / Linux 的包只有 CI 验证过（clippy + 测试），没有人在真机上跑过应用，README 里如实标注了这点
• token 口径：主 agent + 子 agent，按 API 调用去重求和（CC 按 message.id 保留最后一行；Kimi 每条 usage.record 即一次调用；DSH 只读 v3 日志；Codex 以 token_usage_record 为准、之前时段累加去重后的 token_count.last，输入要减缓存命中）。每接一个新 harness 都要用独立脚本逐会话对账后再宣布完成。字段对照写在 src-tauri/src/adapters/mod.rs 的 TokenUsage 注释里，改口径先改那张表

约束

1. UI 对齐 DESIGN.md；状态灯语义固定（绿 run / 蓝 idle / 琥珀 warn / 灰 off）。
2. 浏览器预览可 mock；Tauri 路径必须走 invoke，失败要有可见提示。
3. 代理密钥（2026-09 产品决策）：用户可在应用内填写 API Key，明文保存在 ~/.orrery/proxy.json；仍可用环境变量名回退。解析顺序：api_key 非空优先，否则读 api_key_env。状态列表只显示「是否已设置 / 来源」，不展示密钥原文；编辑接口（get_proxy_config）仅本机 IPC。仓库与日志仍禁止提交真实密钥。模型/供应商由用户在 UI 登记，不再依赖硬编码列表。代理只听回环地址；调用方鉴权头一律丢弃并按目标供应商重建。
4. 提交信息用英文（公开仓库便于国际化；历史已从中文改写为英文）。仓库：https://github.com/arvelvale/orrery（公开，MIT）；README 英文为默认，改 README 时三语（README.md / README.zh-CN.md / README.ja.md）同步。
5. docs/ 是设计文档正本（作者本机的笔记库以目录链接挂载到这里，路径不入库）。
6. README 截图用 mock 数据（无头 Edge 截 npm run preview?lang=<locale> 页面，三语各一套 screenshot-*.{en,zh-CN,ja}.png），不要用真实会话截图——会暴露会话标题与项目路径。
7. 界面文案一律走 ui/i18n.js 的 t()，新增键三种语言同时写（控制台 [i18n] missing keys 会报缺失）；Rust 后端只返回原始数据（时间戳、空标题），不产出任何自然语言。
8. ui/app.js 的 mock 会话必须是虚构项目（acme-web、weather-cli…），不得出现真实项目名或本机路径。
9. 加平台专有调用前先想清楚另外两个平台：Command::new("tasklist") 这类在别的平台上只是执行失败返回空值，编译和测试都不报错，靠它做判断的逻辑会静默失效（删除保护就踩过）。三平台分支写全，或者显式降级并说明。
10. 改 SessionSummary / Rollout 的字段就要 bump adapters/index.rs 的 INDEX_VERSION：索引按这个版本号判断能不能用，忘了 bump 会读出半截旧数据。索引只是缓存，坏了直接整份丢弃重建，任何情况下都不允许它让会话列表出错。
11. 删除功能是破坏性操作：改 cleanup.rs 前先读模块顶部的安全约束；验证只在沙盒做（调试构建设 ORRERY_HOME 指向沙盒主目录），不对真实会话调用 delete_sessions；前后对真实目录做快照比对。

常用命令

# 浏览器预览
npm run preview   # http://127.0.0.1:1420；app.js 是 ES module，直接双击 index.html（file://）不会运行

# 桌面（需 Rust + npm i）
cd orrery
npm install
npm run dev

文档入口

• 定位：docs/00-项目定位.md
• 架构：docs/01-架构与技术路线.md
• 路线：docs/02-MVP路线图.md

实测手段

• 桌面窗口自动化：启动前设 WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9223 --remote-allow-origins=http://127.0.0.1:9223，再用 CDP（/json/list → WebSocket）读 DOM、截图。
• tauri dev 无 devUrl 时由内置服务器在 127.0.0.1:1430 提供 ui/，浏览器打开同地址即 mock 模式。
• app.js 是 ES module，state 等不在 window 上，自动化时走 DOM 或 window.__TAURI__.core.invoke。