6531333e44
Agent/JOY_JSON mode returns {ok,count,items,_joy} for array results
(board ls etc). Compat escape: JOY_LIST_ROOT=array keeps bare arrays.
114 lines
4.4 KiB
Markdown
114 lines
4.4 KiB
Markdown
# joy CLI — AI 原生设计核查
|
||
|
||
> 日期：2026-07-10
|
||
> 配套：[`joy-cli-hardening-plan.md`](joy-cli-hardening-plan.md) · README 设计原则
|
||
|
||
## 1. 原则与满足度
|
||
|
||
| 原则 | 目标 | 状态 | 实现 |
|
||
|------|------|------|------|
|
||
| **JSON 成功输出** | agent 可 `json.loads(stdout)` | **满足（agent 模式）** | dict/list 直出；裸 str 在 agent 模式包成 `{format,content}` |
|
||
| **JSON 错误** | `stderr` 可解析 | **满足** | `{error,code,ok:false,...}` |
|
||
| **稳定 exit code** | 0/1/2 | **满足** | 0 ok · 1 业务/内部 · **2 用法**（`JoyUsageError`） |
|
||
| **可发现** | 一次拉全能力 | **满足** | `tools --manifest` / `help --json` 同源 + tier |
|
||
| **最少 token** | 无 banner | **满足** | 无欢迎语；pretty 可选 |
|
||
| **位置参数** | 少 flag 噪声 | **满足** | 核心命令位置优先 |
|
||
| **身份** | 多 agent 隔离 | **满足** | `JOY_IDENTITY` > 启发式 |
|
||
| **写操作三态** | observe/register/execute/control | **满足** | `action_tiers` + web 白名单 |
|
||
| **契约版本** | 可演进 | **满足** | `_joy.schema_version` |
|
||
| **幂等/可脚本** | 管道友好 | **基本满足** | 非 TTY 自动 agent 模式 |
|
||
| **人机双模式** | 不牺牲人类 TTY | **满足** | TTY help 文本；`--text` 强制 |
|
||
|
||
## 2. Agent 模式触发
|
||
|
||
按优先级：
|
||
|
||
1. `--json` / `-j`
|
||
2. `JOY_JSON=1` 或 `JOY_AGENT=1`
|
||
3. **stdout 非 TTY**（管道、脚本、多数 agent runtime）
|
||
4. `--text` / `--human` **关闭** agent 包装
|
||
|
||
建议神兽/三员环境统一：
|
||
|
||
```bash
|
||
export JOY_JSON=1
|
||
# 或
|
||
export JOY_AGENT=1
|
||
```
|
||
|
||
## 3. 输出约定
|
||
|
||
### 成功
|
||
|
||
| 形态 | 说明 |
|
||
|------|------|
|
||
| **object** | 首选；带 `_joy.schema_version` + `_joy.command` |
|
||
| **array** | agent 默认包成 `{ok,count,items,_joy}`；`JOY_LIST_ROOT=array` 仍输出裸数组 |
|
||
| **text 包装** | agent 模式下原裸字符串 → `{"ok":true,"format":"text","content":"...","_joy":{...}}` |
|
||
|
||
### 失败
|
||
|
||
```json
|
||
{"error": "...", "code": "E_USAGE|E_PERM|...", "ok": false, "detail": "..."}
|
||
```
|
||
|
||
写到 **stderr**；stdout 应为空。
|
||
|
||
## 4. 发现面（agent 启动协议）
|
||
|
||
```bash
|
||
joy tools --manifest # 全量命令 + tier + ai_native 原则
|
||
joy help --json # 分类 + examples + ai_native 摘要
|
||
joy tools --check # 依赖自检
|
||
```
|
||
|
||
勿依赖人类排版的 `joy help` 文本做解析。
|
||
|
||
## 5. 核心 ABI（神兽日用 · 已 JSON 化）
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `patrol` | 对象 |
|
||
| `work <vm> transcript\|alive\|idle\|inject` | 对象（transcript 含 content） |
|
||
| `journal …` | 对象/数组 |
|
||
| `board ls` | agent：`{items:[…],count}`；兼容：`JOY_LIST_ROOT=array` 裸数组 |
|
||
| `recall search` | 对象（entries/content） |
|
||
| `profile <vm>` | 对象（content markdown + path）；`--json` 为 capabilities |
|
||
| `data` / `pipeline` / `idea` | 对象 |
|
||
|
||
## 6. 明确例外（可接受）
|
||
|
||
| 例外 | 原因 |
|
||
|------|------|
|
||
| 交互 TTY 下 `joy help` 纯文本 | 人类可读；agent 用 --json |
|
||
| 根数组旧消费者 | 设 `JOY_LIST_ROOT=array` 或读 `items` |
|
||
| `dashboard` 默认 ANSI 表（TTY） | 人用；agent/非 TTY 自动 `--json` |
|
||
| `web` 长驻 HTTP | 给人的决策台，不是 agent 主入口 |
|
||
|
||
## 7. 核查清单（回归）
|
||
|
||
```bash
|
||
# 非 TTY / agent
|
||
joy tools --manifest | jq -e '.ai_native.principles | length > 0'
|
||
joy help --json | jq -e '.categories'
|
||
joy board 2>/dev/null; echo exit:$? # 期望 2
|
||
joy nosuch 2>/dev/null; echo exit:$? # 期望 1
|
||
JOY_JSON=1 joy work devops transcript 3 | jq -e '.content != null'
|
||
JOY_JSON=1 joy recall search test -n 1 | jq -e '.ok == true or .entries != null'
|
||
```
|
||
|
||
自动化：`pytest tests/test_ai_native.py tests/test_contract.py`
|
||
|
||
|
||
## 8. 运行时注入（linuxjoy 脚本）
|
||
|
||
| 入口 | 注入 |
|
||
|------|------|
|
||
| `scripts/lib/joy-agent-env.sh` | 公共 `JOY_JSON=1` `JOY_AGENT=1` |
|
||
| `joy-clones.sh` pane 脚本 | + `JOY_IDENTITY=<vm>`；CLAUDE 模板同步 |
|
||
| `joy-konqi-resident.sh` | + `JOY_IDENTITY=konqi`（tmux send-keys） |
|
||
| `joy-tux-resident.sh` / `joy-tux-opencode.sh` | + `JOY_IDENTITY=tux` |
|
||
| `joy-wapuu-watcher.sh` | + `JOY_IDENTITY=wapuu` |
|
||
| `joy-mind.sh restart` | 启动命令前 export 同上 |
|
||
|
||
**生效说明**：已运行的 pi/kilo/opencode/mimo 需进程重启后继承环境；脚本与 `~/office/.joy-pi/joy-pi-*.sh` 已写入，watchdog/`--wake` 重建即带新 env。三员 session 已 `tmux set-environment JOY_*`（新命令继承）。
|
