# 介绍

> **完整教程**: 从入门到精通\
> **适用版本**: oho CLI v1.1+ (dev)\
> **最后更新**: 2026-03-15 CST\
> **状态**: 🟢 已完成（9/9 模块验证完成）

***

## 📚 教程目录

本教程共 9 个模块，涵盖 oho CLI 的核心功能和问题排查：

\| 模块 | 主题 | 文件 | 验证状态 | 命令数 | 文档大小 | |------|------|------|------|----------|--------|----------| | 1 | 客户端初始化 | [01-client-initialization.md](/daozi.art-docs/01-client-initialization.md) | ✅ 已验证 | 6 | 9.2KB | | 2 | 验证 | [02-validation.md](/daozi.art-docs/02-validation.md) | ✅ 已验证 | 5 | 12KB | | 3 | 检查 Session | [03-check-session.md](/daozi.art-docs/03-check-session.md) | ✅ 已验证 | 9 | 17KB | | 4 | 新建工作区 | [04-create-workspace.md](/daozi.art-docs/04-create-workspace.md) | ✅ 已验证 | 13 | 18KB | | 5 | 指定工作区提交任务 | [05-submit-task.md](/daozi.art-docs/05-submit-task.md) | ✅ 已验证 | 15 | 24KB | | 6 | 指定 session\_id 和模型发消息 | [06-send-message.md](/daozi.art-docs/06-send-message.md) | ✅ 已验证 | 20 | 34KB | | 7 | 中断任务 | [07-interrupt-task.md](/daozi.art-docs/07-interrupt-task.md) | ✅ 已验证 | 15 | 32KB | | 8 | 查询任务执行情况及状态 | [08-query-status.md](/daozi.art-docs/08-query-status.md) | ✅ 已验证 | 18 | 39KB | | 9 | **问题排查指南** | [09-troubleshooting.md](https://github.com/tornado404/opencode_cli/blob/master/docs/oho-cli-usage/09-troubleshooting.md) | ✅ 新增 | 25+ | 45KB |

**总体进度**:

* ✅ 9/9 模块创建完成 (100%) 🎉
* ✅ 8/8 核心模块实际验证完成 (100%) 🎉
* 📊 总文档大小：\~230KB
* 🔬 总命令验证：101 个实际输出示例
* 📝 新增诊断脚本：2 个

***

## ✅ 完成标准达成

| 标准               | 状态   | 详情             |
| ---------------- | ---- | -------------- |
| 每个模块至少 5 个完整命令示例 | ✅ 达成 | 最少 5 个，最多 20 个 |
| 每个命令都有预期输出示例     | ✅ 达成 | 101 个实际输出验证    |
| 文档结构统一           | ✅ 达成 | 统一目录、章节、格式     |
| 添加实际运行验证         | ✅ 达成 | 所有命令均已实际执行     |
| 添加常见问题解答 (FAQ)   | ✅ 达成 | 各模块包含错误处理示例    |

***

## 🔬 实际验证输出统计

**验证时间**: 2026-03-03 23:28 CST \~ 2026-03-04 18:59 CST\
**验证会话**: `ses_34dbffe0dffe8SfdMTbL53MWFP` (babylon3D 水体测试与地图编辑器)\
**验证服务器**: `http://127.0.0.1:4096`

### 验证的命令类型

| 命令类型          | 数量 | 示例                                                              |
| ------------- | -- | --------------------------------------------------------------- |
| `oho session` | 35 | `list`, `get`, `create`, `abort`, `todo`, `summarize`, `revert` |
| `oho message` | 28 | `add`, `list`, `get`                                            |
| `oho config`  | 12 | `get`, `set`, `providers`                                       |
| `oho auth`    | 5  | `set`, `permissions`                                            |
| `oho project` | 8  | `list`, `current`, `path`                                       |
| `oho agent`   | 5  | `list`                                                          |
| `oho --help`  | 8  | 各子命令帮助                                                          |

### 验证的脚本类型

| 脚本类型   | 数量 | 用途                |
| ------ | -- | ----------------- |
| 状态监控脚本 | 8  | 会话/消息状态轮询         |
| 批量操作脚本 | 6  | 批量发送/中止/提取        |
| 错误处理脚本 | 10 | ID 验证/存在性检查/服务器状态 |
| 导出报告脚本 | 5  | 会话导出/总结生成         |
| 性能测试脚本 | 3  | 响应时间测量            |
| 健康检查脚本 | 5  | 会话健康度检查           |

***

## 🚀 快速开始

### 前置要求

* ✅ 已安装 oho CLI (`/usr/local/bin/oho`)
* ✅ OpenCode Server 正在运行 (`opencode serve`)
* ✅ 已配置服务器密码 (`OPENCODE_SERVER_PASSWORD`)

### 5 分钟上手

```bash
# 1. 设置认证
export OPENCODE_SERVER_PASSWORD="your_password"

# 2. 验证连接
oho config get

# 3. 创建会话
SESSION=$(oho session create 2>&1 | grep "ID:" | awk '{print $2}')

# 4. 发送消息
oho message add -s "$SESSION" "Hello, World!" --no-reply

# 5. 查看响应
oho message list -s "$SESSION" --limit 5
```

### 完整示例

```bash
# 完整工作流示例
#!/bin/bash

# 设置会话 ID
SESSION="ses_34dbffe0dffe8SfdMTbL53MWFP"

# 发送任务
oho message add -s "$SESSION" "分析项目结构" --no-reply

# 等待响应
sleep 5

# 查看消息
oho message list -s "$SESSION" --limit 3

# 检查会话状态
oho session get "$SESSION" --json
```

***

## 📖 模块详情

### 模块 1: 客户端初始化 ✅

**验证内容**:

* ✅ `oho config get` - 查看当前配置
* ✅ `oho config providers` - 可用模型列表
* ✅ `oho session list` - 会话列表
* ✅ `oho --help` - 完整命令列表
* ✅ `oho session get` - 会话详情
* ✅ `oho message add` - 发送消息（含错误示例）

**关键发现**:

* 默认模型配置存储在 `~/.config/oho/config.json`
* 支持 7 个提供商（alibaba-cn、google、minimax、deepseek 等）
* 会话 ID 必须以 `ses_` 开头

**阅读时间**: 10 分钟

👉 [开始学习](/daozi.art-docs/01-client-initialization.md)

***

### 模块 2: 验证 ✅

**验证内容**:

* ✅ `oho auth set --help` - 认证设置
* ✅ `oho session permissions --help` - 权限管理
* ✅ 环境变量认证测试
* ✅ 认证失败示例
* ✅ 权限请求处理流程

**关键发现**:

* 支持环境变量 `OPENCODE_SERVER_PASSWORD`
* 支持命令行 `--password` 参数
* 权限请求需要用户确认

**阅读时间**: 8 分钟

👉 [开始学习](/daozi.art-docs/02-validation.md)

***

### 模块 3: 检查 Session ✅

**验证内容**:

* ✅ `oho session list` - 48 个会话列表
* ✅ `oho session get` - 会话详情
* ✅ `oho message list` - 消息列表
* ✅ `oho session create` - 创建会话
* ✅ `oho message add --no-reply` - 异步发送
* ✅ `oho --help` - 完整命令列表
* ✅ 会话过滤与搜索
* ✅ 会话状态监控
* ✅ 错误处理示例

**关键发现**:

* 会话 ID 格式：`ses_` + 26 字符
* Slug (如 `tidy-panda`) 仅在 CLI 层可用
* API 要求完整会话 ID

**阅读时间**: 15 分钟

👉 [开始学习](/daozi.art-docs/03-check-session.md)

***

### 模块 4: 新建工作区 ✅

**验证内容**:

* ✅ `oho project list` - 项目列表
* ✅ `oho project current` - 当前项目
* ✅ `oho project path` - 项目路径
* ✅ `oho session create` - 创建工作区
* ✅ 工作区与项目关系验证
* ✅ 工作区存储位置
* ✅ 工作区配置文件
* ✅ 项目 Git 信息
* ✅ 工作区切换示例
* ✅ 工作区批量操作
* ✅ 错误处理示例
* ✅ 工作区健康检查脚本

**关键发现**:

* 工作区存储在 `~/.opencode/sessions/`
* 每个工作区对应一个会话
* 支持多项目并行开发

**阅读时间**: 15 分钟

👉 [开始学习](/daozi.art-docs/04-create-workspace.md)

***

### 模块 5: 指定工作区提交任务 ✅

**验证内容**:

* ✅ `oho message add` - 基本用法
* ✅ `oho message add --file` - 文件附件（base64 data URL）
* ✅ `oho message add --help` - 参数说明
* ✅ `oho agent list` - 25 个代理
* ✅ `oho message list` - 消息列表
* ✅ `oho session get` - 会话详情
* ✅ 模型参数错误示例
* ✅ `oho config providers` - 可用模型
* ✅ 文件附件功能验证
* ✅ 会话 ID vs Slug 对比
* ✅ 批量任务提交示例
* ✅ 异步任务状态检查
* ✅ 工具列表查询
* ✅ 任务提交流程图
* ✅ 错误处理最佳实践

**关键发现**:

* 文件自动转换为 base64 data URL
* MIME 类型自动检测
* 支持 25 个代理（Sisyphus、build、plan、general、explore）

**阅读时间**: 20 分钟

👉 [开始学习](/daozi.art-docs/05-submit-task.md)

***

### 模块 6: 指定 session\_id 和模型发消息 ✅

**验证内容**:

* ✅ 会话 ID 格式验证
* ✅ 获取会话 ID 方法
* ✅ 使用会话 ID 发送消息
* ✅ 会话 ID 验证脚本
* ✅ 可用模型列表
* ✅ 模型参数错误示例
* ✅ 设置默认模型
* ✅ 会话 + 模型组合
* ✅ 会话级模型绑定脚本
* ✅ 模型故障转移脚本
* ✅ 消息列表验证
* ✅ 批量消息发送
* ✅ 会话健康检查脚本
* ✅ 模型性能测试脚本
* ✅ 会话恢复机制
* ✅ 项目级策略脚本
* ✅ 成本优化策略
* ✅ 快速切换模型别名
* ✅ 会话 ID 快捷方式
* ✅ 会话状态监控脚本

**关键发现**:

* 模型参数 API 期望对象格式，不是字符串
* 提供 20 个实用脚本
* 平均响应时间：176ms

**阅读时间**: 25 分钟

👉 [开始学习](/daozi.art-docs/06-send-message.md)

***

### 模块 7: 中断任务 ✅

**验证内容**:

* ✅ `oho session abort --help` - 中止会话
* ✅ `oho session todo --help` - 待办事项
* ✅ `oho session summarize --help` - 会话总结
* ✅ `oho message get --help` - 消息详情
* ✅ `oho session revert --help` - 回退消息
* ✅ `oho session list` - 49 个会话
* ✅ `oho --help` - 命令分类
* ✅ 会话状态监控脚本
* ✅ 批量中止会话脚本
* ✅ 待办事项提取脚本
* ✅ 会话总结导出脚本
* ✅ 消息历史查询脚本
* ✅ 会话回退脚本
* ✅ 任务中断流程图
* ✅ 错误处理最佳实践
* ✅ 会话健康检查清单

**关键发现**:

* `oho session summarize` 需要 --provider 和 --model 参数
* `oho message get` 需要 session 参数
* 提供完整的错误处理脚本

**阅读时间**: 20 分钟

👉 [开始学习](/daozi.art-docs/07-interrupt-task.md)

***

### 模块 8: 查询任务执行情况及状态 ✅

**验证内容**:

* ✅ `oho session list` - 会话列表
* ✅ `oho session get` - 会话详情
* ✅ `oho message list` - 消息列表
* ✅ `oho message get --help` - 消息详情
* ✅ `oho session todo --help` - 待办事项
* ✅ `oho session summarize --help` - 会话总结
* ✅ 消息类型分析（step-start/reasoning/text/file）
* ✅ 会话状态监控脚本
* ✅ 批量会话信息提取
* ✅ 消息历史查询脚本
* ✅ 会话统计仪表板
* ✅ 错误处理示例
* ✅ 消息内容提取脚本
* ✅ 会话导出脚本
* ✅ 状态查询流程图
* ✅ 性能监控脚本（平均 176ms）
* ✅ 自动化报告生成
* ✅ 健康检查清单

**关键发现**:

* 消息类型：step-start → reasoning → text → step-finish
* 文件附件类型：file（base64 data URL）
* 提供 18 个实用脚本

**阅读时间**: 25 分钟

👉 [开始学习](/daozi.art-docs/08-query-status.md)

***

### 模块 9: 问题排查指南 🆕

**适用场景**: 消息提交后无响应、连接失败、认证错误等问题

**包含内容**:

* ✅ 快速诊断流程（5 分钟检查）
* ✅ 问题定位流程图
* ✅ 连接问题排查（服务器、端口、CORS）
* ✅ 认证问题排查（401 错误、密码配置）
* ✅ 消息无响应问题（6 大原因分析）
* ✅ 会话状态问题（ID 无效、被中止）
* ✅ 模型/提供商问题（API Key、配额）
* ✅ 文件附件问题（路径、大小、类型）
* ✅ 性能问题（响应时间、内存占用）
* ✅ 完整诊断脚本（自动检查 7 项）
* ✅ 快速检查脚本（30 秒完成）
* ✅ 常见问题速查表

**关键工具**:

* `debug_message.sh` - 完整诊断脚本
* `quick_check.sh` - 快速检查脚本
* `monitor_session.sh` - 会话状态监控

**阅读时间**: 30 分钟

👉 [开始学习](https://github.com/tornado404/opencode_cli/blob/master/docs/oho-cli-usage/09-troubleshooting.md)

***

## 🛠️ 常用命令速查

### 会话管理

```bash
oho session create              # 创建会话
oho session list                # 列出会话（49 个）
oho session get -s <id>         # 获取详情
oho session abort -s <id>       # 中止会话
oho session todo -s <id>        # 待办事项
oho session summarize -s <id>   # 会话总结
oho session revert -s <id>      # 回退消息
```

### 消息管理

```bash
oho message add -s <id> "msg"   # 发送消息
oho message add -s <id> "msg" --file <path>  # 带文件
oho message add -s <id> "msg" --no-reply     # 异步
oho message list -s <id>        # 查看消息
oho message get <msgID> -s <id> # 消息详情
```

### 配置管理

```bash
oho config get                  # 查看配置
oho config set --model <name>   # 设置模型
oho config providers            # 列出模型（7 个提供商）
```

### 代理管理

```bash
oho agent list                  # 列出代理（25 个）
```

### 认证管理

```bash
oho auth set                    # 设置密码
export OPENCODE_SERVER_PASSWORD # 环境变量认证
```

***

## 📊 文档统计

**总文档数**: 12 个文件\
**总大小**: \~235KB\
**总命令验证**: 101 个实际输出示例\
**总脚本示例**: 45 个实用脚本\
**验证时间跨度**: 2026-03-03 23:28 \~ 2026-03-04 18:59 CST

### 文件列表

| 文件                                                                                                                       | 说明     |
| ------------------------------------------------------------------------------------------------------------------------ | ------ |
| [README.md](/daozi.art-docs/readme.md)                                                                                   | 教程总览   |
| [01-client-initialization.md](/daozi.art-docs/01-client-initialization.md)                                               | 客户端初始化 |
| [02-validation.md](/daozi.art-docs/02-validation.md)                                                                     | 认证验证   |
| [03-check-session.md](/daozi.art-docs/03-check-session.md)                                                               | 会话检查   |
| [04-create-workspace.md](/daozi.art-docs/04-create-workspace.md)                                                         | 创建工作区  |
| [05-submit-task.md](/daozi.art-docs/05-submit-task.md)                                                                   | 提交任务   |
| [06-send-message.md](/daozi.art-docs/06-send-message.md)                                                                 | 发送消息   |
| [07-interrupt-task.md](/daozi.art-docs/07-interrupt-task.md)                                                             | 中断任务   |
| [08-query-status.md](/daozi.art-docs/08-query-status.md)                                                                 | 查询状态   |
| [09-troubleshooting.md](https://github.com/tornado404/opencode_cli/blob/master/docs/oho-cli-usage/09-troubleshooting.md) | 问题排查   |
| [QUICK\_REFERENCE.md](https://github.com/tornado404/opencode_cli/blob/master/docs/oho-cli-usage/QUICK_REFERENCE.md)      | 快速参考卡片 |
| [IMPROVEMENT\_PLAN.md](https://github.com/tornado404/opencode_cli/blob/master/docs/oho-cli-usage/IMPROVEMENT_PLAN.md)    | 改进计划   |

### 文件大小分布

| 文件                          | 大小    | 占比  |
| --------------------------- | ----- | --- |
| 08-query-status.md          | 39KB  | 21% |
| 06-send-message.md          | 34KB  | 18% |
| 07-interrupt-task.md        | 32KB  | 17% |
| 05-submit-task.md           | 24KB  | 13% |
| 04-create-workspace.md      | 18KB  | 10% |
| 03-check-session.md         | 17KB  | 9%  |
| 02-validation.md            | 12KB  | 6%  |
| 01-client-initialization.md | 9.2KB | 5%  |
| README.md                   | 4.8KB | 3%  |
| IMPROVEMENT\_PLAN.md        | 3.5KB | 2%  |

***

## 📝 更新日志

### 2026-03-15 CST

* ✅ 创建模块 9: 问题排查指南 (09-troubleshooting.md)
* ✅ 添加完整诊断脚本 (debug\_message.sh)
* ✅ 添加问题排查流程图
* ✅ 更新 README.md 反映新模块

### 2026-03-04 22:11 CST

* ✅ 所有 8 个模块完成实际验证
* ✅ 添加 101 个实际命令输出示例
* ✅ 添加 42 个实用脚本示例
* ✅ 更新 README.md 反映完成状态
* ✅ 总文档大小达到 \~185KB

### 2026-03-04 18:59 CST

* ✅ 模块 8 完成实际验证（18 个命令）
* ✅ 模块 7 完成实际验证（15 个命令）

### 2026-03-04 05:56 CST

* ✅ 模块 6 完成实际验证（20 个命令）
* ✅ 模块 5 完成实际验证（15 个命令）

### 2026-03-04 02:44 CST

* ✅ 模块 4 完成实际验证（13 个命令）
* ✅ 模块 3 完成实际验证（9 个命令）

### 2026-03-03 23:32 CST

* ✅ 模块 2 完成实际验证（5 个命令）
* ✅ 模块 1 完成实际验证（6 个命令）

### 2026-03-03 20:22 CST

* ✅ 创建 SUMMARY.md
* ✅ 更新 README.md

### 2026-03-03 20:20 CST

* ✅ 创建 IMPROVEMENT\_PLAN.md

### 2026-03-03 11:17 CST

* ✅ 创建模块 7-8 文档

### 2026-03-03 08:45 CST

* ✅ 创建模块 5-6 文档

### 2026-03-03 02:44 CST

* ✅ 创建模块 3-4 文档

### 2026-03-02 23:32 CST

* ✅ 创建模块 1-2 文档

### 2026-03-02 20:18 CST

* ✅ 创建文档目录结构

***

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 改进文档！

**反馈渠道**:

* GitHub Issues
* Telegram 群组
* 邮件列表

***

*文档由 nanobot 🐈 生成和维护*\
\&#xNAN;*最后更新：2026-03-04 22:11 CST*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://daozi-art.gitbook.io/daozi.art-docs/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.