joy-cli/docs/ai-native.md

joy CLI — AI 原生设计核查

日期：2026-07-10
配套：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 包装

建议神兽/三员环境统一：

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":{...}}

失败

{"error": "...", "code": "E_USAGE|E_PERM|...", "ok": false, "detail": "..."}

写到 stderr；stdout 应为空。

4. 发现面（agent 启动协议）

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. 核查清单（回归）

# 非 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_*（新命令继承）。