在仓库内运行 jeo，它会读取文件、编辑代码、执行命令，并把任务推进到完成 — 每一步都通过滚动友好的内联 TUI 实时呈现。

文档

📖 使用指南 — 安装、TUI 操作（↑ 历史、Ctrl+O、! shell）、斜杠命令、/resume、规格优先工作流，附演示视频。

无法内联播放？▶ 播放/下载演示视频。

亮点

• 多提供商、单一循环 — Anthropic / OpenAI(+Codex) / Gemini / Antigravity / Ollama / LM Studio，以及 20+ 个 OpenAI、Anthropic 兼容云服务(Groq、DeepSeek、Mistral、OpenRouter、xAI、Kimi、z.ai 等)，统一在一个 JSON 工具循环中 — 还包括你自己注册的端点: jeo provider add --id my-proxy --base-url https://…(或 --preset litellm|vllm|sglang|azure-openai|…)让 LiteLLM 代理、自托管 vLLM、企业内部 Anthropic 网关拥有各自的路由前缀、模型列表和凭据，而不是劫持内置的 openai 提供商。输入框内直接 OAuth 登录(/provider login)，每次模型选择都会持久化为新的默认值，而 prompt routing 只会自动选择真实可用的凭据路径: Gemini OAuth 会走 provider-qualified 的 antigravity/* 代理模型集，以账号当前实际提供的为准(实时发现 — 例如 Gemini 3.6 Flash 各档、Gemini 3.1 Pro、Claude Sonnet/Opus 4.6；非对话模型与已弃用的 id 会被过滤掉，列表为空时也不会用静态目录顶替)，绝不选择需要 GEMINI_API_KEY 的 public google/gemini-* 行；如果已配置的路由指向尚未就绪的提供商，jeo 会先切换到同层级的等价凭据模型，再退回默认模型。
• 编辑完整性 — read 输出携带内容锚点(42ab|)；带锚点的编辑会与当前文件校验、行移动时自动重映射、不匹配时连同最新内容一起拒绝 — 绝不污染文件。
• 自我修正的验证循环 — 配置 post-edit 钩子(tsc / eslint / 测试)，代理会亲自读取诊断并在循环内修复；钩子未通过时 done 会被阻断。
• 没有表演的真实门禁 — ralplan 共识由真正读取仓库的 critic 子代理执行，[OKAY] 裁决被持久化且 jeo approve 强制要求它；ultragoal 诚实报告(套件运行只是全局信号，绝不伪造逐条通过)。
• 崩溃耐久、本地优先 — 全部状态位于 .jeo/，原子写入、跨进程运行锁、失败任务标记 + 恢复时的部分编辑警告。
• 动态步数预算 — 只要近期工具调用展现新的进展就持续延长，停滞时优雅收敛为总结；子代理保持精确的步数契约。
• 内联 TUI — 已完成的工作流入真实滚动缓冲区(回合中也可用 tmux 滚轮)，代理运行时普通查询输入框仍保持可见并可编辑。Ctrl+O 详细信息切换、主题、剪贴板图片粘贴(Ctrl+V)、CJK/表情安全的宽度计算。
• 浏览器工具 — 基于 Playwright 的无头 Chromium 自动化,作为一等代理工具:对命名并复用的标签页执行 open/close/run/act,优先使用 observe 标记的元素 id 而非截图来驱动页面。act {verb:"verify", goal, ...} 闭合了可视化 QA 循环:对页面截图,并让一个独立的、具备视觉能力的模型依据一句大白话目标来判断({verdict:"PASS"|"MISMATCH", detail}),不再需要人工(或同一个代理)去肉眼核对保存下来的 PNG。需要执行一次 npx playwright install chromium(未捆绑 — jeo 本身仍是零原生依赖,浏览器二进制文件是 Playwright 的独立下载项)。
• 持续积累的技能 — 卡壳的一轮现在会把死胡同写入同一个技能的项目级文件(.jeo/skills/<name>.md,首次写入时从内置技能播种,采用确定性关键词匹配,不使用 LLM),因此下一个会话的 $<skill> 调用会带上累积的"Known Failure Modes"/"Anti-Patterns"知识,而不是让内置文档永远保持静态。手动记录用 jeo skills lesson <skill> <failure|anti-pattern> "<title>" "<detail>";jeo skills eval <skill> 会运行一次真正的 LLM 判断,检查每条已记录的经验是否仍被技能当前的指引覆盖,还是已经过时。
• 低价位评分模型路由 — /goal 验证器、critic 子代理角色,以及未锁定的 task 扇出批次,现在默认使用低价位、已配置凭证的模型,而不是悄悄搭乘与它们所评分/执行的工作相同的全价模型(resolveVerifierModel,针对浏览器 verify 动作按视觉能力过滤,确保纯文本的低价模型不会悄悄丢弃附带的截图)。
• jeo routine init — 生成一个 GitHub Actions 工作流,在 schedule/issue/PR 触发器上以无头模式运行 jeo(jeo "<prompt>" -p),运行在 GitHub 自己的 runner 上 — 不需要笔记本电脑,并且不会给 jeo 自身增加任何新的攻击面(没有进程内调度器或 webhook 监听器)。--dry-run 可预览,--no-pr 则改为直接提交而非默认的每次运行一个 PR。
• 远程监控与控制(Telegram、Discord、Slack) — 配对一次机器人(jeo notify setup --provider telegram|discord|slack)后，一个共享的 jeo daemon start 会在所有活跃会话中、子代理每次状态变化(启动 → 完成/失败/取消)时推送消息，并接受来自人类 allowlist 的 /subagents、/steer、/cancel(Discord/Slack 上还有 /sessions 和 /send)回传。Telegram 额外提供论坛主题、内联键盘和图片附件；Discord 使用 REST + Gateway WebSocket；Slack 使用 Web API + Socket Mode。附带各平台详细配置指南及可安装的 Agent Skill(channel-notify)。
• 无法绕过的门禁 — approve 会重新校验它正在批准的那份计划的精确摘要，team 会拒绝已审阅摘要发生变化的计划；done 调用会对照最新的验证证据重新检查(后来的失败检查会使先前的通过失效，三次纠正往返后硬性拒绝)；autopilot ratchet 会把失败的回滚记录为 rollback_failed 并以非零状态停止，而不是声称该步骤已回退。
• 不阻塞回合的会话级异步执行 — 通过 task 工具真实的 tasks 数组扇出独立工作，不阻塞父回合。detached 子代理、后台 job 和逐行 monitor 可在后续回合中继续使用 subagent/job/monitor 的 list、inspect、await、cancel、tail 控制。内联 TUI 为每个 worker 保留独立的实时 activity 槽位，并在会话退出或 Ctrl-C 时清理全部 registry。
• 独立验证器，真正强制执行 — 计划再也无法跳过 architect/critic 步骤: PlanSchema 会拒绝任何以未验证变更结尾的计划(把验证器放在它该检查的变更之前也不算数)，在 ralplan 起草阶段和 team/approve 执行阶段都强制生效。每一次 architect/critic 裁决也都必须展示真实证据 — 观测到的 read/search/find/ast_grep/lsp 调用为零，无论文本怎么声称，裁决都会被拦下。
• 安全边界自动模型回退 — 未分类的安全拒绝(可能是分类器误报，而非真实的内容策略命中)现在会切换到真正不同提供商的模型，而不是在同一个模型上无限退让 — 与现有的 rate-limit 快速回退是同一套模式。Refusal (<category>) 这种形态的确定性拒绝不受影响，仍然零回退硬失败。
• 内存: 应得的信任 — 概念的验证日期现在只在蒸馏阶段被明确标记为已验证时才会写入，而不是每次写入都记录；isConceptStale 把未验证(或超过 30 天过期)的概念视为需要重新验证，而不是信任一个被动的时间戳。
• 动态工作流(eval 工具) — 围绕子代理派遣编写真正的 JS 控制流: task(role, taskText, context?)、parallel(thunks)、pipeline(items, ...stages)、log(message)，组合出 task 单阶段 tasks[] 批次无法表达的顺序/分支编排。运行在隔离的 Worker 线程中，具备真正的抢占式超时(worker.terminate()，而非同进程内的竞争) — 与 bash 同等的全进程信任级别，不假装沙箱，受同一个 interview 变更锁门控。
• 在破损输出管道上安静退出 — 当管道输出到提前停止读取的命令时(jeo --help | head、消失的远程对端),不再转储原始的 EPIPE 堆栈 — 现在会以 shell 对被 SIGPIPE 终止的管道生产者报告的相同退出码(141)安静退出。真正的崩溃不受影响,仍会清晰地暴露出来。
• macOS 低文件描述符上限警告 — 较低的 ulimit -n(BSD 默认 256/1024)可能导致文件监视、浏览器工具或大范围仓库扫描出现不明的 EMFILE 失败 — jeo 现在会在启动时警告一次(仅 stderr,绝不污染被管道的 -p 输出),并给出具体的 ulimit/launchctl 指引。可通过 JEO_SKIP_NOFILE_CHECK=1 选择退出。

安装

需要 Bun 1.3.14+。

bun install -g jeo-code
jeo --version

从重命名前的版本升级？旧 CLI 名称 joc 的二进制文件现在会被 scripts/install.sh / scripts/uninstall.sh 自动移除；手动移除: rm -f ~/.local/bin/joc ~/.bun/bin/joc。

快速开始

jeo                      # 在当前仓库启动交互式代理
jeo "整理 README 并跑测试"   # 单次请求
jeo doctor               # 配置 + 模型连通性实测
jeo setup                # API 密钥 / OAuth / 本地模型配置
jeo --tmux               # 在独立 tmux 会话中运行

斜杠命令

在 jeo REPL 中使用(Tab 补全，输入 / 打开面板)。

| 命令 | 说明 | | --- | --- | | /model · /provider | 选择模型/提供商；/model 在一个流程内显示默认/角色徽章、Ralph 风格嵌套的"设为角色"thinking 选择与 OpenAI Codex 角色预设 | | /provider login <name> · /logout | 在输入框内 OAuth 登录/登出 | | /provider add · list · remove · presets | 将 OpenAI/Anthropic 兼容端点注册为一等提供商(15 个网关预设) | | /agents [role] · /subagent | 按角色(executor/planner/architect/critic)配置模型·thinking·步数 | | /thinking [level] | 查看/设置默认推理预算(low…xhigh) | | /route [status\|on\|off\|why\|history [n]] | 切换本会话基于提示词的模型路由 · 解释最近一次路由决策 · history [n] 列出本会话最近 n 条(默认 10 条)路由决策(每轮自动路由到与层级匹配的模型，且只在你已配置的凭证 — OAuth 或 API 密钥 — 实际可用的模型中选择；已配置的路由未就绪时会切换到同层级的等价模型) | | /fast [on\|off\|status] | 当前模型支持 low 推理时切换 fast thinking 模式 | | /skill · $<skill> [intent] | 列出/运行工作流技能($team "任务" 风格) | | /view · /diff · /find · /search | 代码查看、git diff、文件/模式搜索 | | /computer [status\|on\|off] | 切换本会话的 fail-closed 桌面自动化工具 | | /new · /sessions | 开始新会话或列出已保存会话 | | /resume [id\|gajae:<session-id>[#<leaf>]] [--any-cwd] | 恢复 Jeo 会话，或将只读的精确版本 GJC v5 分支导入新的 Jeo 会话 | | /changelog [--full] · /jobs [list\|tail\|await\|cancel] | 显示发布说明 · 查看、等待或取消当前会话的后台任务 | | /history [n\|all] · /export | 将可读的工作活动历史重新输出到滚动区 · 导出记录 | | /retry · /btw <q> | 重试上次请求 · 不写入历史的旁路提问 | | /usage · /context · /compact | Token 用量、上下文明细、手动压缩 | | /theme · /config · /help | 主题、运行时配置、帮助 |

[!CAUTION] 通过 /model <name> 手动指定模型后，路由会在本会话内保持锁定。 Prompt routing(/route)只在没有手动锁定模型时才会逐轮重新评估。用 /model <name> 选定具体模型后，该选择会被锁定 — 直到你运行 /model auto(彻底解除锁定)，或运行 /route on(不会清除锁定，只是优先级更高 — 一旦运行 /route off，锁定会立刻恢复)之前，路由都不会再切换。未配置 roles.* 条目时，只有 standard 层级会确定性地退回到 defaultModel；high/complex 层级通常会先实时扫描已配置凭证中最强的可用模型再决定是否回退，所以即使未配置，也可能每轮落到不同的模型上。例外: 通过 Antigravity 或 Gemini OAuth 授权的会话会用同一个凭证重新导出 Anthropic/Google/OpenAI 的模型 —此时 high/complex 会按公司各选一个模型、以会话为单位稳定分布(不一定是最强的那个)，因此在同一会话内保持固定，而不是逐轮变化。

Antigravity 账户模型与官方 agy 桥接

Cloud Code Assist (antigravity/<CCA-id>) — /model provider antigravity 与 /agents <角色> provider antigravity 显示 Cloud Code Assist 为所选 jeo OAuth 账户返回的模型。发现过程合并 agentModelSorts、tieredModelIds 和 defaultAgentModelId，账户级缓存在刷新后仍保持隔离。空列表或发现失败会如实报告，不会退回静态目录。CLI 模型 slug 不是 CCA 的通信 ID，CLI 中可用也不代表支持通过 CCA 直接调用 Argon。

CCA 示例： jeo auth login antigravity 会发现并缓存该账户的模型。通过 /model antigravity/<CCA-id> 或 /agents executor provider antigravity 选择，或通过 /model save antigravity/<CCA-id> 保存默认值。

官方 CLI (agy/<official-cli-slug>) — 显式选择一个独立的完整代理后端，使用已安装在 PATH 上的 agy 可执行文件。认证通过官方 CLI 自身支持的流程管理；jeo 不管理或导入其凭证。agy models 提供真实列表和准确的 slug，不使用静态目录或 CCA 别名。不能假定 CLI 会话、账户与 jeo OAuth 账户相同；CLI 模型列表仅保存在当前进程内，不使用 jeo 的账户级磁盘缓存。空列表保持为空，发现失败则显示错误，不会编造模型。

agy models
jeo launch --model agy/gemini-4-argon-low --plan --no-tui --no-session --no-skills "Explain this repository"

请使用自己的 CLI 实际返回的 slug。在交互式 jeo 会话中查看列表、选择模型，并按需保存为持久默认值：

/model provider agy
/model agy/gemini-4-argon-low
/model save agy/gemini-4-argon-low

[!WARNING] 官方 agy 代理自行管理工具、沙箱、权限和对话。jeo 的审批不介入其内部工具调用。 --plan 只选择 CLI 的计划模式，不会将工具审批权交给 jeo。此桥接必须显式选择，仅支持文本，不参与自动原始模型或子代理路由；图片附件以及无法强制执行的 jeo 专用工具、系统、步骤数、thinking 控制会被拒绝。

启用 jeo 会话持久化时，恢复会使用该会话保存的 CLI 对话 ID，而不是 CLI 中无关的最近对话。取消和有界超时会停止 CLI 轮次。准确保留所选模型及上游 CLI 错误，包括配额错误；不会静默回退到 CCA、其他模型或其他账户。

CLI 命令

jeo --help 是权威列表；下面是你最常用到的:

| 命令 | 用途 | | --- | --- | | jeo [prompt] [--resume [id]] [--tmux] [--worktree <path>] [-p] [-q] | 交互式代理(默认)；-p/--print 用于无头单次输出，--worktree 用于隔离的同级检出 | | jeo setup · jeo auth login\|logout\|refresh\|status [provider] · jeo doctor | 提供商、自动刷新的 OAuth(PKCE)令牌、实时连通性 + 过期模型锁定检查 | | jeo provider list\|add\|remove\|presets\|test | 具名的自定义 OpenAI/Anthropic 兼容提供商(与 /provider 共用同一套 planner) | | jeo deep-interview → ralplan → approve → team → ultragoal | Spec-first 工作流(见下文)；jeo state <skill> read\|write\|clear\|handoff 用于检查回执 | | jeo notify setup\|status\|health\|test · jeo daemon start\|stop\|status\|reload | Telegram / Discord / Slack 通知与共享控制守护进程 | | jeo autopilot <subcommand> · jeo ledger <subcommand> | 带分数 ratchet 的自主构建循环(status 显示方向、keep/revert 次数和下一步动作) · 跨计划的只追加账本 | | jeo routine init … | 生成一个 GitHub Actions 工作流，按计划或仓库事件以无头模式运行 jeo | | jeo skills list\|read\|sync\|lesson\|eval | 内置、用户和项目技能；漂移检查；已记录的经验 | | jeo mcp serve\|tools · jeo computer <action> | 供外部控制器使用的 MCP stdio 服务器 · 桌面自动化动作 | | jeo session list\|attach\|rm · jeo export [id] · jeo chat "<msg>" | tmux 会话管理 · 导出记录 · 无工具的流式聊天 | | jeo update [--check] · jeo whats-new · jeo memory-migrate | 从 npm 自更新 · 内置发布说明 · 旧版 MEMORY.md → OKF 概念包 |

Spec-first 工作流

需求 → 计划 → 批准 → 执行 → 验证，经由 .jeo/state/ 串联，每次交接都有可阻断的真实门禁:

jeo deep-interview "描述你想构建的东西"
jeo ralplan
jeo approve <计划路径>
jeo team
jeo ultragoal

  ┌──────────────────────┐
  │   deep-interview     │  Socratic ambiguity gate · seed frozen when concrete
  └──────────┬───────────┘
             │ .jeo/state/<seed>.json
             ▼
  ┌──────────────────────┐
  │       ralplan        │  Draft + repo-grounded critic → [OKAY] persisted
  └──────────┬───────────┘
             │ requires [OKAY] verdict
             ▼
  ┌──────────────────────┐
  │       approve        │  Schema + roles + [OKAY] — unlocks execution
  └──────────┬───────────┘
             │
             ▼
  ┌──────────────────────┐
  │        team          │  Serial executor · run lock · mutation audit
  └──────────┬───────────┘
             │ all tasks done
             ▼
  ┌──────────────────────┐
  │      ultragoal       │  Honest verification — suite once, no fabrication
  └──────────────────────┘

• deep-interview — 基于歧义度评分的苏格拉底循环；只有标准足够具体才冻结种子(纯含糊标准会被拒绝)，且种子必须通过自身解析器的往返校验。新想法绝不会静默复用已完成的访谈。
• ralplan — 起草阶段 + 真正读取仓库的 critic 子代理门禁: 强制并持久化 [OKAY]/[ITERATE]/[REJECT] 裁决。无效计划(schema、未知角色)不会被标记为 complete。
• approve — 校验 team 执行的确切契约(schema+角色)，并要求持久化的 [OKAY] 共识裁决。
• team — 串行计划执行器: 跨进程运行锁、过期计划重置、按任务的子代理契约、父侧变更审计(零写入的"完成"会被标记)、失败标记 + 恢复时的部分编辑警告。
• ultragoal — 诚实验证: 套件作为全局信号只运行一次，标准只被记录，绝不伪造为逐条通过。

验证钩子(自我修正)

先全局启用一次(在 ~/.jeo/config.json 中设置 "hooks": { "enabled": true })，再为项目添加 post-edit 检查，代理会读取失败并在 done 之前修复:

// .jeo/hooks.json
{
  "enabled": true,
  "hooks": [
    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
  ]
}

非零退出钩子的输出会附加到模型读取的工具结果中(批内去重)；钩子未通过就调用 done 会收到带钩子名称的回推。

内存流程

jeo 在 .jeo/memory/ 下保存 本地优先、蒸馏后的项目内存(无远程后端,零原生依赖)。过往会话被蒸馏为 OKF 概念包,下一次会话仅把相关的、受预算约束的切片重新注入系统提示 —— 作为 DATA 而非指令加固。用 JEO_NO_MEMORY=1 完全禁用。

迁移(jeo memory-migrate,一次性 · 幂等). 把旧版单文档 MEMORY.md 无损转换为概念包: ## 标题 → 类型,每个项目符号 → 一个类型化概念,缩进行 → 正文; 重建 index.md/log.md,并把原文件重命名为 MEMORY.md.bak。一旦概念包中已有概念,再次运行即为 no-op。回滚: JEO_MEMORY_LEGACY=1 忽略概念包,通过相同的注入加固读取 MEMORY.md/.bak(JEO_NO_MEMORY=1 仍优先于一切)。

与您现有的代理或机器人协同工作 (Works beside your existing agent or bot)

| 工具或机器人 | 推荐的 jeo 命令 | 边界 | | ----------- | ----------------------- | -------- | | Codex CLI | jeo --tmux --worktree <name> 或 jeo | --worktree 指定一个由 jeo 管理的同级 git worktree（basename → 新分支）；对于已有路径，请先 cd 进入。 | | Claude Code | jeo --tmux 或 jeo --tmux --worktree <name> | jeo 不会成为 Claude Code 的扩展。 | | OpenCode | jeo 或 jeo --tmux | 仅限外部运行器工作流。 | | Claw Code | jeo --tmux --worktree <name> | jeo 不会安装到或替换 Claw Code。 | | 外部控制器 / 机器人 | jeo mcp serve (MCP stdio 服务器) | 外部控制器通过 MCP 工具契约驱动 jeo，而非抓取滚动回显。 |

--worktree <name> 在隔离的同级 git worktree 中运行 jeo（路径存在则复用，否则以 basename 分支创建），因此有风险或需审查的工作绝不会触及您的主检出。jeo mcp serve 通过 stdio 向任何支持 MCP 的控制器公开 jeo 的工具（用 jeo mcp tools 列出）。添加 -q/--quiet（或 JEO_QUIET=1）可抑制启动横幅、欢迎动画、发布说明和恢复提示，使 jeo 能够与其他代理并行运行或由机器人驱动。-p/--print 隐含 quiet。

远程监控与控制 (Telegram, Discord & Slack)

可选功能: 一个共享守护进程监视本机上所有活跃的 jeo 会话，并在每次子代理状态变化(启动 → 完成/失败/取消)时推送消息，另附会话身份头、回合开始/结束摘要以及最终的回合文本 — 绝不会重复"仍在运行"之类的通知。allowlist 中的人类可以在聊天里列出、发送、引导和取消；每一条控制都会转发给本地会话，并报告为已确认(已接受，未必已完成)或未确认 — 守护进程绝不声称某条命令已执行。

各平台详细独立指南：

• 📖 渠道集成概览与架构 — 功能对比矩阵与架构图
• 📱 Telegram 集成指南 — 内置后台守护进程、BotFather 交互配对、论坛主题与 /steer 命令
• 🎮 Discord 集成指南 — 即时频道通知 Webhook、双向交互机器人与 Embed 卡片规范
• 💬 Slack 集成指南 — 工作区通知 Incoming Webhook、团队协作 Slack App / Socket Mode 与 Block Kit 卡片
• 🧩 Agent Skill 安装指南 — 将渠道通知技能一键安装至 jeo、Claude Code、Cursor、Codex 等环境

jeo notify setup  [--provider telegram|discord|slack] [--token-env NAME] [--app-token-env NAME] [--chat-id ID | --channel-id ID] [--allowed-user-ids ID,ID,...]
jeo notify status [--provider …]   # masked token, destination, allowlist, daemon state (stopped / stale / initializing / initialized / pairing)
jeo notify health [--provider …]   # read-only: bot identity + destination access, nothing sent
jeo notify test   [--provider …]   # sends one real test message
jeo daemon start|stop|status|reload   # the shared daemon has no provider selector

| | Telegram(默认) | Discord | Slack | | --- | --- | --- | --- | | 凭证 | 机器人 token(JEO_TELEGRAM_BOT_TOKEN 或 --token-env) | 机器人 token(JEO_DISCORD_BOT_TOKEN 或 --token-env)+ Message Content intent | 机器人 xoxb token(JEO_SLACK_BOT_TOKEN 或 --token-env)+ 应用 xapp token(SLACK_APP_TOKEN 或 --app-token-env)，并启用 Socket Mode | | 目标 | 通过挑战配对的私聊(在 120 秒内把显示的 /start jeo_<code> 发给机器人)或显式 --chat-id；群组需要 --allowed-user-ids | 显式 --channel-id(文字频道、DM、公告频道或已有线程) | 机器人已加入的显式 --channel-id(C…)；工作区固定为 token 所属的团队 | | Allowlist | 私聊可选，群组必需 | 必需(人类用户 ID；机器人会被忽略) | 必需(人类用户 ID) | | 传输 | 直接调用 Bot API getUpdates 长轮询，每个机器人 token 只有一个轮询所有者 | 发送走 REST，入站走 Gateway WebSocket | 发送走 Web API，入站走 Socket Mode WebSocket | | 附加能力 | 论坛主题、内联取消按钮、图片附件、可选的每会话主题(notifications.telegram.perSessionTopics，仅限开启 Threaded Mode 的私聊) | 回复某条会话通知即可向该会话发送文本(24 小时内) | 在会话通知的线程中回复即可向该会话发送文本(24 小时内)；已注册的 Slack 斜杠命令或 @bot /command 均可用 | | 命令 | /subagents /steer <session> <subagent> <msg> /cancel <session> <subagent> /help | /sessions /subagents /send <session> <text> /steer … /cancel … /help | 与 Discord 相同 |

这些词不可互换，所以说明一下它们各自的含义:

• Setup 会通过官方 API 验证机器人身份和目标访问权限(Telegram getMe，Discord 机器人 + 频道查询，Slack auth.test/bots.info/conversations.info 以及一个 Socket Mode URL)，并把结果存入 ~/.jeo/config.json 的 notifications.<provider> 下 — 明文；请保持该文件私有。它不会发送消息，也不会打开 socket。
• initialized(jeo daemon status)表示守护进程已持有自己的锁并启动了各传输层；它并不证明 Telegram 轮询、Discord Gateway 握手或 Slack Socket Mode 连接已经成功。要验证这些请使用 notify health / notify test。
• 更改 token 或目标会重置 Discord 和 Slack 的 allowlist(你必须再次传入 --allowed-user-ids)以及 Telegram 的每会话主题映射；用完全相同的凭证和目标重新运行 setup 则会保留它们。
• 远程命令是字面文本(/subagents 等)，仅对已配置的聊天/频道和 allowlist 授权；Slack 还额外接受同名的已注册斜杠命令。allowlist 中的操作者实际上拥有本地代理的全部能力 — 请把这份名单当作信任边界对待。
• 重试按提供商有界: Telegram 遵守 429 的 retry_after 冷却(限制在 1 秒–1 小时之间)并使用独立的轮询退避；Discord 和 Slack 在 429 时按服务器的 Retry-After 最多重试 3 次，且绝不重发结果未知的 POST(平台可能已经收到了它)。
• 孤儿恢复: 守护进程崩溃后，其锁会变为 stale；下一次 jeo daemon start 会回收它。当宿主机能够报告进程启动时间时，jeo daemon stop 会拒绝向已被复用的 PID 发送信号；无法报告时也会明确说明。
• 目前已验证: Telegram 端到端(真实发送、轮询、干净关闭)。Discord 和 Slack 基于同一个守护进程实现，配有离线的传输/接线测试以及代码、安全和类型审查；尚未用真实的机器人/应用凭证进行实际连通性验证。

┌─────────────────────┐        ┌──────────────────┐        ┌───────────────────────────┐
│   interactive turn  │◄──ws──►│  notify daemon   │◄──────►│ Telegram Bot API (poll)   │
│  SubagentRegistry   │  (one  │   (singleton)    │        │ Discord REST + Gateway WS │
│  session endpoint   │  per   │                  │        │ Slack Web API + Socket WS │
└─────────────────────┘ session└──────────────────┘        └───────────────────────────┘

Discord & Slack (Webhook 与 Bot App)

为团队工作区配置标准 Webhook 或 Bot 凭证环境变量：

# Discord Webhook
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# Slack Incoming Webhook
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

支持发送包含任务状态、耗时、Git 提交与 PR 链接的富文本 Embed(Discord) 及 Block Kit 卡片(Slack)。详见 Discord 指南 与 Slack 指南。

安装为 Agent Skill

使用标准的 Agent Skills CLI，可将渠道通知技能快速安装到 jeo 或其它 AI 编码代理中：

# 安装 channel-notify 技能到当前仓库：
npx skills add akillness/jeo-code --skill channel-notify

# 或全局(-g)安装，供所有项目使用：
npx skills add akillness/jeo-code --skill channel-notify -g

安装后，代理可在执行任务时自主发送进度通知：

# 在 jeo 中单次调用：
jeo $channel-notify "所有 47 个测试均已通过，等待代码审查。"

# 在 Claude Code 中调用：
/channel-notify "构建成功。PR 链接: https://github.com/..."

例行任务 (GitHub Actions)

jeo routine init --trigger schedule --cron "0 7 * * *" --prompt "Re-run the eval suite and post a digest" --dry-run
jeo routine init --trigger issues --prompt "Triage this issue" --name "issue-triage"

生成一个 GitHub Actions 工作流(.github/workflows/<name>.yml),安装 jeo 并在 schedule / issues / pull_request 上以无头模式运行它(jeo "<prompt>" -p)— 始终与 workflow_dispatch 搭配,便于手动测试运行 — 运行在 GitHub 自己的托管 runner 上。这就是 jeo "无需笔记本电脑运行"的故事:jeo 自身内部没有进程内调度器、没有 webhook 监听器、没有代码执行沙箱 — 由 GitHub 的基础设施负责触发,jeo 只是运行它现有的无头模式。默认在有任何变更时开一个 PR(peter-evans/create-pull-request,diff 为空时是安全的空操作);--no-pr 则改为直接提交到触发分支。--dry-run 只打印 YAML 而不写入;在相同的 --out 路径上重新运行 jeo routine init,若不加 --force 会拒绝覆盖。请在工作流首次真正运行前,设置好仓库密钥 ANTHROPIC_API_KEY(或 --api-key-env <VAR>)。

本地模型

ollama pull qwen2.5:0.5b
export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
jeo doctor && jeo

配置

• 全局配置: ~/.jeo/config.json(模型选择 MRU 持久化)
• 项目状态/会话: <project>/.jeo/

ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
JEO_DEFAULT_MODEL=...           # 例: ollama/qwen2.5:0.5b
OLLAMA_HOST=http://localhost:11434
JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura/gruvbox-dark
JEO_TUI_ALT_SCREEN=1            # 旧版 alt-screen 回合(默认: 内联滚动缓冲)
JEO_STEP_BASE=24                # 动态步数预算的滚动基数
JEO_STEP_HARD_CAP=600           # 绝对终止保证
JEO_STREAM_MAX_MS=1800000       # 整体流截止(默认30分钟; 约束 slow-drip 流，不是为了中断仍在活跃输出的流); 0 表示禁用
JEO_STREAM_IDLE_MS=300000       # 单次分块空闲上限(默认300秒); 首个 token 前静默较久的慢速/本地后端可调高
JEO_CALL_TIMEOUT_MS=1800000     # 非流式调用墙钟上限(默认30分钟; compaction/subagents/goal-verify)
JEO_TURN_MAX_MS=1800000         # 回合停滞预算: 没有工具进展的最长时间(默认30分钟); 0 表示禁用
JEO_TOOL_OUTPUT_MAX=4000        # 模型可见的工具输出上限(全文溢出到 artifacts)

重试行为通过 ~/.jeo/config.json 的 retry 调整(requestMaxRetries、streamMaxRetries、rateLimitRetries、failFastStatuses 等)。步数预算默认动态 — 只要看到新的进展就延长，停滞时收敛为总结；--max-steps N 恢复有界流程。

自定义提供商

{
  "customProviders": {
    "my-proxy": {
      "baseUrl": "https://gateway.internal/v1",
      "protocol": "openai",            // 或 "anthropic" (/v1/messages 协议)
      "apiKeyEnv": "MY_PROXY_API_KEY", // 默认: <ID>_API_KEY
      "models": ["fast", "smart"]      // 离线列表；实时 /models 优先
    }
  }
}

命令行(jeo provider add|list|remove|presets|test)与输入框(/provider add …)操作同一份注册表。 jeo provider test <id> 会真实探测端点，并分别报告凭据问题与端点问题， 失败时以非零码退出，可直接用作部署脚本的检查关卡。

子代理扇出并发度

{ "subagentConcurrency": 2 }   // 默认 4，限制在 1~16

Anthropic Tier-1 账号在 4 条并发流时会立刻触发限流，使扇出变成比顺序执行更慢的 退避风暴。限流紧张的账号请调低，额度充足时可调高。该值同时约束 task 工具的 tasks[] 批处理与 eval 工具的 parallel/pipeline 辅助函数。

技能迁移与内置技能检查

把某个工作流迁移到 jeo 之前，先检查内置默认值，再决定是否安装或覆盖任何内容:

jeo skills list                 # 内置 + 用户 + 项目技能，附带发现目录
jeo skills read ralplan         # 打印某个技能的完整 SKILL.md
jeo skills sync --check         # 报告与 ~/.jeo/skills 的差异(有差异时非零退出)

jeo skills sync 会把内置的工作流技能(deep-interview、deep-dive、ralplan、team、ultragoal)安装到 ~/.jeo/skills，并且默认保留已有的本地文件 —— 不同的本地副本会被报告为 preserved，绝不会被覆盖。如果 --check 标记出缺失或不同的文件，先用 jeo skills read <name> 对比；只有在确实想替换本地默认工作流技能文件时才使用 jeo skills sync --force。可通过末尾路径参数(或 JEO_CONFIG_DIR)指定不同目录，并加上 --json 获取结构化的 SkillSyncResult。

开发

jeo 是运行在 Bun 上的纯 TypeScript，零原生依赖，因此全局 jeo 命令可以直接运行本仓库的源码 —— 无需构建步骤，每次编辑立即生效。

bun install
bun run dev:link            # 将 `jeo` 软链接到 <repo>/src/cli.ts -> ~/.local/bin
bun run dev:doctor          # 报告全局 `jeo` 是否运行的是本源码(linked/drift/missing)

如果 PATH 中在受管链接之前还有另一个 jeo 遮蔽了它，dev:link 会拒绝继续(可用 JEO_DEV_LINK_DIR 覆盖目标位置)，并运行一次 --version 冒烟测试。当解析出的 jeo 是编译后的二进制文件或已安装副本而非本源码时，dev:doctor 以非零状态退出。无需链接直接从源码运行: bun src/cli.ts --help。内置工作流技能位于源码 src/prompts/skills/<name>/SKILL.md；用 bun run typecheck 和 bun test 验证。

发布 (Publishing)

CI 通过 .github/workflows/npm-publish.yml 发布 — GitHub 发布 release 时自动触发，或手动 workflow_dispatch(可选 dry-run)。工作流依次执行浏览器硬门禁、类型检查、测试(浏览器工具测试在独立进程中)、pack:check、打包 tarball 的启动冒烟，然后运行 npm publish --provenance。

发布使用 npm trusted publishing(OIDC) — 不存在需要轮换、可能泄露或需豁免 2FA 的 NPM_TOKEN secret(npm 自 2026 年 8 月起限制绕过 2FA 的令牌，并于 2027 年 1 月终止用其直接发布)。在 npmjs.com 上一次性设置: 包 jeo-code → Settings → Trusted Publisher → GitHub Actions，owner akillness，repository jeo-code，workflow npm-publish.yml，environment 留空。该 job 需要 permissions.id-token: write 和 npm ≥ 11.5.1(工作流会自行升级 npm)。

致谢 (Acknowledgements)

非常感谢 gajae-code 带来的灵感。

更新日志 (Changelog)

• [Unreleased]
• [0.12.7] (2026-10-18) — Repair desktop screenshot vision feedback, macOS scrolling, complete drag gestures, and keyboard normalization.
• [0.12.6] (2026-10-17) — Preserve OpenAI subscription authentication behind configured proxies, isolate account catalogs, and give provider-specific recovery instructions while retaining Antigravity OAuth calls.
• [0.12.5] (2026-10-17) — Antigravity and Kimi provider support in interactive setup, Kimi live model cache rehydration, immediate discovery caching on provider probing.
• [0.12.4] (2026-10-17) — Refresh Antigravity provider (antigravity/*) account catalogs with antigravity/hub/2.23.1 so entitled Gemini 4 Argon and Gemini 3.8 Flash tiers appear directly in /model provider antigravity.

See CHANGELOG.md for the full history.