> For the complete documentation index, see [llms.txt](https://daozi-art.gitbook.io/daozi.art-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://daozi-art.gitbook.io/daozi.art-docs/readme.md). # 介绍 > **完整教程**: 从入门到精通\ > **适用版本**: 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 # 获取详情 oho session abort -s # 中止会话 oho session todo -s # 待办事项 oho session summarize -s # 会话总结 oho session revert -s # 回退消息 ``` ### 消息管理 ```bash oho message add -s "msg" # 发送消息 oho message add -s "msg" --file # 带文件 oho message add -s "msg" --no-reply # 异步 oho message list -s # 查看消息 oho message get -s # 消息详情 ``` ### 配置管理 ```bash oho config get # 查看配置 oho config set --model # 设置模型 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*