cli-jaw/README.zh-CN.md at main · lidge-ai/cli-jaw · GitHub
Skip to content

Latest commit

 

History

History
619 lines (454 loc) · 26.5 KB

README.zh-CN.md

File metadata and controls

619 lines (454 loc) · 26.5 KB

CLI-JAW — 你的个人 AI 助手。每个 AI CLI,一个仪表盘。

一个助手、一份记忆、一个仪表盘,统一你已经在付费的 AI 编码 CLI。
Claude、Codex、Cursor、Grok、Copilot、OpenCode、Kiro、Antigravity 和 Pi — 像一支团队那样协作。

npm version latest release Node.js 22.4+ MIT license

# 现有用户想要最小改动:JAW_SAFE=1 npm install -g cli-jaw
npm install -g cli-jaw
jaw dashboard

Download for macOS (.dmg) Download for Windows (.exe) Download for Linux (.AppImage)

每个 agent 都在一处

在管理面板里启动、停止并预览每个正在运行的实例。

CLI-JAW 管理面板

为工作准备的看板

看板泳道、优先级矩阵和提醒,跟踪每个会话正在做什么。

agent 会话的看板

agent 能读的笔记

内置的 Markdown 工作区,支持所见即所得编辑、数学公式和 Mermaid 图表。

笔记编辑器

English · 한국어 · 中文 · 日本語 · 📖 官网 · 文档


CLI-JAW 是什么?

CLI-JAW 把你已经在用的 AI 编码 CLI 统一成一个助手、一份记忆、一个仪表盘。你的主 CLI(“Boss”)把其他 CLI 当作“员工”调用,于是你不用再在多个应用之间复制粘贴,在一个地方就能下达指令。

  • 无需 API 密钥 — 通过你已经在付费的订阅路由
  • 无按 token 计费 — 月费固定,和你现有的订阅一样
  • 本地运行 — 你的代码不会离开本机
  • 随处可用 — Web、桌面应用、终端、Telegram、Discord 或 Slack

原生 Code API(/api/code)提供隔离的 Codex、Claude、Cursor 和 Grok 会话,具备持久 transcript 和原生 resume。参见 native Code sessions。


安装

安全安装 — 面向现有用户,最小改动
# macOS / Linux
JAW_SAFE=1 npm install -g cli-jaw    # skips optional tool/runtime setup
jaw init                              # interactive setup later when you're ready

Windows 支持。 推荐使用 WSL 路径,它是稳定的。原生 PowerShell 安装脚本也可以用,但仍处于 beta 阶段:

irm https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install.ps1 | iex

需要 Node.js 22.4+。

管理面板在 24576 端口,每个 agent 的 Web UI 在 3457 端口。如果执行策略挡住了 jaw.ps1,不要放宽策略,直接用 .cmd:

jaw.cmd doctor

原生 Windows 的开机自启通过 windows-startup 后端注册。jaw service install 同样支持 macOS(launchd) 和 Linux(systemd)。

无论走哪条路径,cli-jaw 现在都能把两者精确区分开:jaw doctor --json 会把 platform 报告为 windows-native 或 wsl,两者各有独立诊断。原生 Windows 不会再仅仅因为机器上配置了 WSL interop 就收到“在 WSL 里重新安装” 的建议。

# macOS / Linux / WSL with Node.js 22+ already installed
npm install -g cli-jaw
jaw dashboard

npm 12+? npm 现在默认阻止依赖的安装脚本。如果看到 npm warn allow-scripts,请批准脚本后再安装:

npm install -g cli-jaw --allow-scripts=cli-jaw
Windows npm 安装恢复 — npm 12+ 阻止了脚本,或 PowerShell 执行策略限制

npm 12+ 可能完成全局安装,同时阻止 CLI-JAW 的依赖 postinstall。只批准这一个包然后重新安装,或把批准保存下来供 以后升级使用:

npm install -g cli-jaw --allow-scripts=cli-jaw
npm config set allow-scripts=cli-jaw --location=user
jaw doctor

如果 PowerShell 报告 jaw.ps1 无法加载,因为脚本执行 已被禁用,请在下列受控变通方案中选择一个:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
jaw.cmd doctor
node "$(npm prefix -g)\node_modules\cli-jaw\dist\bin\cli-jaw.js" doctor

jaw.ps1 是 PowerShell 的 npm shim,受执行策略约束; jaw.cmd 是等价的 cmd shim,不走该策略。直接使用 node 的形式会绕过两个 shim。jaw doctor 会报告被阻止或过期的安装、 残留的 npm 暂存目录,以及当前 PowerShell 策略;它还会 打印对应的恢复指引。

完成。打开 http://localhost:24576 进入管理仪表盘。单个 agent Web UI 在运行 jaw serve 时仍从 http://localhost:3457 提供。需要 Node.js 22.4+。

第一次用? 默认 npm 安装会初始化 CLI-JAW,并尝试配置原生 Claude。其他 AI CLI 是可选项;在 macOS/Linux 上如需安装全部工具,可运行 CLI_JAW_INSTALL_CLI_TOOLS=1 npm install -g cli-jaw。Windows 请使用下方 WSL 安装路径。

已退役的 runtime。 Claude E(claude-e)和 AI-E multiplexer(ai-e)已被移除。已保存的选择会以已退役状态显示,且无法执行;请选择一个可用的 runtime。详情:runtime integration。

macOS 一键安装 — 没有 Node.js?用这个
curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install.sh | bash
source "${ZDOTDIR:-$HOME}/.zshrc" 2>/dev/null || true
bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"
Windows(WSL — Windows 子系统 Linux) — 从零一键安装
# 1. Install WSL (PowerShell as Admin)
wsl --install

重启后打开 Ubuntu,然后:

# 2. Install CLI-JAW + all dependencies
curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/install-wsl.sh | bash
source ~/.bashrc
jaw dashboard
bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"

从 Windows PowerShell 进入 WSL 时,请通过 login shell 运行命令,以便加载 WSL profile PATH:

wsl.exe -d Ubuntu -- bash -lc "jaw dashboard"
原生 Windows(PowerShell beta) — 分离的服务器日志

jaw serve 会保留它继承的 stdout 和 stderr 流,并把 两个流都追加到 <JAW_HOME>\logs\serve.log。启动时,已经达到 5 MiB 的文件 会被轮转一次为 serve.log.1。原生 Windows 仍然没有注册的 jaw service 日志后端。PowerShell 的 Start-Process -RedirectStandardOutput/-RedirectStandardError 会在每次启动时创建或 截断目标文件,所以不要把这两个选项指向 实例自有的 serve.log。

如果需要独立的、由运维方拥有的 stdout/stderr 文件,请改为在子 PowerShell 进程 内部做重定向。下面的示例把它们追加到 <JAW_HOME>\logs 下,同时避开 Start-Process 的截断默认行为:

$jawHome = 'C:\jaw\worker-a'
$port = 3458
$logDir = Join-Path $jawHome 'logs'
$outLog = Join-Path $logDir 'serve.out.log'
$errLog = Join-Path $logDir 'serve.err.log'
New-Item -ItemType Directory -Force -Path $logDir -ErrorAction Stop | Out-Null
foreach ($path in @($outLog, $errLog)) {
    # OpenOrCreate preserves existing content while proving that the child can append.
    $probe = [IO.File]::Open($path, 'OpenOrCreate', 'Write', 'ReadWrite')
    $probe.Dispose()
}

$jaw = (Get-Command jaw.cmd -ErrorAction Stop).Source
$childCommand = "& '$jaw' --home '$jawHome' serve --port $port --no-open 1>> '$outLog' 2>> '$errLog'"
$encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($childCommand))
Start-Process -FilePath powershell.exe -ArgumentList '-NoProfile', '-EncodedCommand', $encoded -WindowStyle Hidden | Out-Null

请在各自独立的 PowerShell 终端里读取每个流(Get-Content -Wait 会占用该终端)。这些命令使用显式路径,因为启动终端里的变量 在新的 PowerShell 会话中不可用:

# Terminal 1
Get-Content -LiteralPath 'C:\jaw\worker-a\logs\serve.out.log' -Tail 100 -Wait

# Terminal 2
Get-Content -LiteralPath 'C:\jaw\worker-a\logs\serve.err.log' -Tail 100 -Wait

生命周期命令以 home 为作用域,在发送信号前会校验 <JAW_HOME>\jaw.pid.json:

& $jaw --home $jawHome service stop --port $port
& $jaw --home $jawHome service restart --port $port

单独运行 service restart 会以分离方式安全重启实例,但 无法重现运维方的文件重定向。要保留文件捕获,请 stop、可选地轮转已关闭的日志,然后重新运行上面的启动块:

$pidFile = Join-Path $jawHome 'jaw.pid.json'
$serverProcess = $null
if (Test-Path -LiteralPath $pidFile -PathType Leaf) {
    $record = Get-Content -LiteralPath $pidFile -Raw -ErrorAction Stop | ConvertFrom-Json
    $serverProcess = Get-Process -Id ([int]$record.pid) -ErrorAction SilentlyContinue
}

& $jaw --home $jawHome service stop --port $port
if ($LASTEXITCODE -ne 0) {
    throw "jaw service stop failed with exit code $LASTEXITCODE"
}
if ($serverProcess) {
    try {
        if (-not $serverProcess.WaitForExit(5000)) {
            throw "jaw serve pid $($serverProcess.Id) did not exit within 5000ms"
        }
    } finally {
        $serverProcess.Dispose()
    }
}

$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
foreach ($path in @($outLog, $errLog)) {
    if (Test-Path -LiteralPath $path) {
        Move-Item -LiteralPath $path -Destination "$path.$stamp" -ErrorAction Stop
    }
}
# Run the Start-Process launch block above again.

不要使用 Get-Process node | Stop-Process;它可能终止无关的 cli-jaw 实例和 AI runtime 进程。

全新机器证据 — 维护者发布检查

发布安装器变更前,请在干净 VM 上运行此流程。collector 会把环境快照、installer 日志、实际运行的 collector/installer/verifier 脚本及其 SHA-256 哈希、verifier 日志和新 shell PATH probe 写入 ~/cli-jaw-fresh-install-evidence-*。

# macOS Terminal
COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh
curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/collect-fresh-install-evidence.sh -o "$COLLECTOR"
bash "$COLLECTOR" --target macos

# Ubuntu inside WSL
COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh
bash "$COLLECTOR" --target wsl

从 Windows PowerShell 进入受支持的 WSL 路径:

wsl.exe -d Ubuntu -- bash -lc 'COLLECTOR=/tmp/cli-jaw-collect-fresh-install-evidence.sh; curl -fsSL https://raw.githubusercontent.com/lidge-ai/cli-jaw/main/scripts/collect-fresh-install-evidence.sh -o "$COLLECTOR"; bash "$COLLECTOR" --target wsl'

如果 collector 报告 WSL 内没有 powershell.exe,请在审计前从 Windows PowerShell 运行:

wsl.exe -d Ubuntu -- bash -lc 'EVIDENCE_DIR="$(ls -dt ~/cli-jaw-fresh-install-evidence-* | head -1)"; { echo "command=wsl.exe -d Ubuntu -- bash -lc jaw --version"; jaw --version; } | tee "$EVIDENCE_DIR/33-powershell-to-wsl-probe.log"'

对于未合并的分支或本地 VM 检出,请显式传入本地安装器和 verifier:

bash scripts/collect-fresh-install-evidence.sh --target macos --install-script scripts/install.sh --verifier-script scripts/verify-fresh-install.sh
bash scripts/collect-fresh-install-evidence.sh --target wsl --install-script scripts/install-wsl.sh --verifier-script scripts/verify-fresh-install.sh

在把收集到的每个目录当作目标证据之前,请先审计:

EVIDENCE_DIR="$(ls -dt ~/cli-jaw-fresh-install-evidence-* | head -1)"
AUDITOR="$(npm root -g)/cli-jaw/scripts/audit-fresh-install-evidence.mjs"
node "$AUDITOR" "$EVIDENCE_DIR" --target macos
node "$AUDITOR" "$EVIDENCE_DIR" --target wsl

# For a local checkout, audit with the checkout's auditor:
node scripts/audit-fresh-install-evidence.mjs "$EVIDENCE_DIR" --target macos
node scripts/audit-fresh-install-evidence.mjs "$EVIDENCE_DIR" --target wsl

发布安装器变更前,请用两个严格的 evidence 目录运行 matrix gate:

GATE="$(npm root -g)/cli-jaw/scripts/verify-release-evidence.mjs"
node "$GATE" --macos /path/to/macos-evidence --wsl /path/to/wsl-evidence

# For a local checkout:
node scripts/verify-release-evidence.mjs --macos /path/to/macos-evidence --wsl /path/to/wsl-evidence

matrix gate 会拒绝用过期 collector、installer 或 verifier 脚本收集到的证据;归档的证据脚本必须与运行该 gate 的当前包或检出匹配。

当 scripts/promote-to-main.sh、scripts/release-preview.sh 或 npm publish 检测到自上一个 tag 以来有安装器敏感变更时,它会在任何 git push 或 npm publish 之前运行同一个 matrix gate。请在开始发布前设置证据目录:

CLI_JAW_MACOS_EVIDENCE_DIR=/path/to/macos-evidence \
CLI_JAW_WSL_EVIDENCE_DIR=/path/to/wsl-evidence \
bash scripts/promote-to-main.sh

scripts/promote-to-main.sh 只提升已经通过认证的 preview head。除非存在针对该精确 preview SHA 的成功 test.yml push run,否则它拒绝启动。不带参数时,它提升当前的 origin/preview head;可选的 SHA 参数必须等于同一个 head,因此它起断言作用,而不是用来提升更旧的提交。

脚本会派发 npm publish,然后不检查发布是否成功就退出,之后也无法再次运行。对于部分完成的发布——npm publish 缺失、GitHub release 缺失、latest 上的版本不对,或 main 上的红色提交——的恢复方法记录在 structure/infra.md § 릴리스 파이프라인과 부분 실패 복구。

Docker
docker compose up -d       # → http://localhost:3457

认证

你只需要一个。选择你已有的订阅:

# Free options (no credit card needed)
copilot login        # GitHub Copilot (free tier available)
opencode             # OpenCode — free models available
kiro                 # AWS Kiro (free tier with AWS account)

# Paid (monthly subscription you already pay for)
claude auth login    # Anthropic Claude Pro or higher
codex login          # OpenAI ChatGPT Pro or higher
cursor-agent login   # Cursor
grok login --oauth   # xAI Grok / Grok Heavy

一次性检查全部:jaw doctor

jaw doctor 输出示例
🦈 CLI-JAW Doctor — 13 checks

 ✅ Node.js        v22.15.0
 ✅ Claude CLI      installed
 ✅ Codex CLI       installed
 ✅ Cursor CLI      installed
 ✅ OpenCode CLI    installed
 ✅ Copilot CLI     installed
 ✅ Database        jaw.db OK
 ✅ Skills          29 active, 238 reference
 ✅ MCP (plugins)   3 servers configured
 ✅ Memory          structured/ exists
 ✅ Server          port 3457 available

你能得到什么

员工:你的 CLI 调用其他 CLI

你只和一个 AI(“Boss”)对话。当它需要专业工作时,会把任务分派给员工——每个员工运行自己的 CLI 和模型——并在回答你之前审查它们的输出。

You: "Fix the frontend styling and update the API endpoint"

Boss (Claude)
  ├── Frontend employee (OpenCode) → "Fix the CSS grid layout in dashboard.tsx"
  ├── Backend employee (Codex)     → "Update /api/users to return pagination metadata"
  └── Synthesizes both results for you
jaw dispatch --agent "Backend" --task "Run read-only verification" --watch
jaw dispatch --virtual "security" --task "Review this branch for auth and secret leaks" --watch

PABCD:计划、审计、构建、检查、完成

对于复杂任务,CLI-JAW 运行结构化工作流。每一次转换都由你批准;只读工作者验证计划和结果。

阶段 会发生什么
P — Plan Boss 写出 diff 级别的计划,然后停下等你审查
A — Audit 只读工作者检查计划是否可行
B — Build Boss 实现;只读工作者进行验证
C — Check 类型检查、文档更新、一致性检查
D — Done 汇总所有变更,回到空闲状态

状态在重启后保留。用 jaw orchestrate 或 /pabcd 开始,用 /continue 恢复,用 /goal 让长期目标保持存活。参见 PABCD。

记忆、技能和 MCP

  • 三层记忆 — 最近的会话历史、从对话中沉淀出来的结构化笔记,以及可搜索的 soul/task 快照:jaw memory search "how did we set up the API auth?"
  • 200+ 技能 — 办公文档(PDF、DOCX、XLSX、PPTX、HWP)、浏览器和桌面自动化、媒体、GitHub、Notion 和开发指南:jaw skill install <name>
  • 所有引擎共用一份 MCP 配置 — jaw mcp install @anthropic/context7 会一次同步 Claude、Codex、Kiro、OpenCode、Copilot 和 Antigravity

浏览器和桌面自动化

通过 DevTools Protocol 驱动 Chrome;用 jaw browser vision-click "Login button" 按描述点击;在受支持的 macOS 和 Windows 主机上,通过 jaw-computer-use MCP 工具(或 Codex 原生 Computer Use 插件)控制桌面应用;用 jaw browser web-ai 询问 ChatGPT、Gemini 或 Grok 的 Web UI。

消息

从 Telegram(语音消息、论坛主题、定时 heartbeat 任务)、Discord 和 Slack(Socket Mode、线程、文件中继、mention 监听)与你的 agent 聊天。可以同时启用多个渠道;home 渠道会接收主动发送的内容。

Telegram 设置(3 步)
  1. 给 @BotFather 发消息 → /newbot → 复制 token
  2. jaw init --telegram-token YOUR_TOKEN,或使用 Web UI 设置
  3. 给 bot 发送任意消息。Chat ID 会在第一条消息时自动保存
Slack 设置(引导式向导)
  1. jaw slack setup — 打印 app manifest、打开 Slack 应用页面、实时校验两个 token,并写入设置
  2. 在 bot 需要读取的每个频道执行 /invite @cli-jaw,然后重启 jaw serve

群组 DM 需要 message.mpim 事件和 mpim:history scope。在容器中,SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_TEAM_ID 和 SLACK_CHANNEL_IDS 在运行时拥有各自的字段。详情:Slack tools。

桌面应用

Electron 应用会启动管理面板,随包提供内置的 Node.js sidecar,并常驻你的菜单栏。请从 GitHub Releases 下载:

  • macOS(Apple Silicon) — 打开 DMG,把 CLI-JAW 拖入 Applications。构建产物经过 Developer ID 签名、公证和 stapling,并支持应用内更新。
  • Windows(x64) — 运行 Setup .exe。它没有签名,因此 SmartScreen 可能会要求你确认。
  • Linux(x64) — 给 AppImage 添加执行权限后运行。

首次启动后,接受 Install CLI command(或使用托盘项 Install CLI to Terminal),即可在终端中得到 jaw,无需全局 npm 安装。


AI 运行时

无按 token 的 API 计费。通过你已经在付费的订阅路由。

CLI 默认模型 认证 费用
Pi grok-composer-2.5-fast Settings profile API key、local proxy,或 PI_CODING_AGENT_BIN 通过隔离 profile 连接 local/API endpoint
Claude claude-opus-4-8 claude auth login Claude Pro 或更高订阅
Antigravity AGY-selected 由 agy 在运行时检查 实验性 print-mode runtime
Codex gpt-5.5 codex login ChatGPT Pro 或更高订阅
Codex App gpt-5.5 codex login ChatGPT Pro 或更高订阅
Cursor composer-2.5 cursor-agent login 或 CURSOR_API_KEY Cursor 订阅
Grok grok-build grok login --oauth Grok 订阅
Kiro registry-selected kiro AWS Kiro 免费层
OpenCode opencode-go/kimi-k2.6 opencode 有免费模型可用
Copilot claude-sonnet-4.6 copilot login 有免费层可用

如果某个引擎被限速,下一个会接上(/fallback)。用 /cli codex 实时切换引擎,用 /model gpt-5.5 切换模型 — 可在 Web、终端、Telegram、Discord 或 Slack 中使用。


CLI

# Core
jaw dashboard                     # launch manager dashboard
jaw serve                         # start an agent server (http://localhost:3457)
jaw chat                          # terminal chat UI
jaw ask "question"                # one prompt, one answer — no TTY needed
jaw doctor                        # installation and runtime diagnostics

# Instances
jaw clone ~/project                           # clone instance to new directory
jaw --home ~/project serve --port 3458        # run a second instance
jaw service install                           # auto-start on boot (macOS launchd / Linux systemd)
jaw --home ~/project service restart --port 3458  # restart only this instance

# Agents and workflow
jaw employee list
jaw dispatch --agent "Backend" --task "..." --watch
jaw orchestrate                   # PABCD workflow
jaw goal status                   # persistent goals

# Skills, MCP, memory, browser
jaw skill list
jaw mcp install <package>
jaw memory search <query>
jaw browser fetch "https://example.com" --json

用 jaw clone 创建的每个实例都有自己的设置、记忆、数据库和 MCP 配置,管理面板可以看到全部。远程和无头主机:structure/remote-headless.md。完整命令参考:CLI docs。


文档

主题 位置
官网和快速上手 lidge-ai.github.io/cli-jaw
指南、概念、参考 Developer docs
架构 docs/ARCHITECTURE.md · structure/
Slack 工具和本地 API docs/slack-tools.md
Runtime 集成(含已退役 runtime) structure/runtime-integration.md

开发

npm run build          # tsc → dist/
npm run build:frontend # vite → public/dist/
npm run dev            # tsx server.ts (hot-reload)
npm test               # node:test driver (tests/run.mts)
npm run gate:all       # release/docs parity gates
npm run electron:dev   # desktop app with hot reload

故障排查

问题 解决办法
cli-jaw: command not found 再运行一次 npm install -g cli-jaw。macOS/Linux/WSL:检查 ~/.local/bin 或 npm prefix -g + /bin 是否在 $PATH 中。从 Windows PowerShell 调用 WSL 时,请通过 login shell:wsl.exe -d Ubuntu -- bash -lc "jaw dashboard"。
npm warn allow-scripts ... npm >= 12 会阻止依赖安装脚本:npm install -g cli-jaw --allow-scripts=cli-jaw,或用 npm config set allow-scripts=cli-jaw --location=user 持久保存。已经装过了?jaw init 会完成设置。
pnpm/bun 阻止了构建脚本 pnpm 11+:pnpm add -g --allow-build=cli-jaw cli-jaw。bun:bun add -g --trust cli-jaw。
全新安装的 verifier 失败 修复报告出的 PATH 或可执行位问题,然后重新运行 bash "$(npm root -g)/cli-jaw/scripts/verify-fresh-install.sh"。
Error: node version 升级到 Node.js 22.4+:nvm install 22
NODE_MODULE_VERSION mismatch npm run ensure:native
EADDRINUSE: port 3457 另一个实例正在运行。使用 --port 3458 或先停止它
Telegram / Discord / Slack 认证失败 运行 jaw doctor,检查 token,重启 jaw serve
员工分派挂起 运行 jaw employee list,确认员工 CLI 已认证(jaw doctor),然后用 jaw dispatch --watch 重试

参与贡献

公开代码和产品文档保存在这里。私有规划和历史只保存在独立的同级克隆 cli-jaw-internal 中;请通过 issue 申请访问权限。不要在本检出中创建私有记录,包括 devlog、_plan、_fin 或 .jwc 别名,也不要在公开文档或源码中包含私有记录路径。上传变更前,请先完成本地 pre-push 设置和检查。

  1. 从 dev Fork 并创建分支
  2. npm run build && npm run build:frontend && npm test
  3. 对发布敏感的变更,还要运行 npm run gate:all
  4. 提交 PR

MIT License · 由受够了在 AI 应用之间来回切标签的开发者们打造。