OpenCode文档编写规范：API文档与用户手册标准

OpenCode文档编写规范：API文档与用户手册标准

【免费下载链接】termai 项目地址: https://gitcode.com/gh_mirrors/te/termai

文档规范概述

OpenCode作为终端AI助手，需要清晰、一致的文档来帮助用户快速上手和高效使用。本文档定义了API文档与用户手册的编写标准，确保所有文档具备专业性、易用性和一致性。文档内容应面向普通用户及运营人员，避免过多专业术语，控制在800-2000字符之间。

文档结构标准

基础结构要求

所有文档应遵循"总—分—总"结构：

• 痛点引入：开篇200字内点明用户需求或问题
• 分步方案：主体内容分模块展开，每模块100-300字
• 回顾展望：结尾总结核心价值并预告后续内容

模块化组织

文档应包含以下核心模块：

• 概述（Overview）：产品定位与核心价值
• 安装指南（Installation）：环境要求与部署步骤
• 快速上手（Quick Start）：基础操作流程
• 功能详解（Features）：核心能力与使用场景
• 高级配置（Configuration）：自定义选项与参数说明
• 常见问题（FAQ）：故障排除与最佳实践

API文档编写规范

接口描述标准

每个API接口文档必须包含：

• 功能描述：清晰说明接口用途与适用场景
• 请求格式：完整的URL、Method、Headers和Body定义
• 参数说明：所有参数的名称、类型、必填性和默认值
• 返回示例：成功与失败响应的完整JSON结构
• 错误码表：可能出现的错误码及解决方案

示例代码规范

API文档中的代码示例需满足：

• 使用真实可运行的代码，避免占位符
• 包含完整的请求-响应流程
• 关键步骤添加单行注释
• 统一使用bash作为命令行示例语言

# 获取当前会话列表
curl -X GET http://localhost:8080/api/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

用户手册编写规范

语言风格要求

• 使用第二人称"您"而非"你"，保持专业礼貌
• 中英术语首次出现时括号标注，如TUI（终端用户界面）
• 避免使用"简单"、"只需"等可能暗示用户能力的词汇
• 操作步骤使用祈使句，如"点击确认按钮"而非"您可以点击确认按钮"

图表使用规范

• 技术架构使用mermaid流程图展示
• 操作步骤使用编号列表而非项目符号
• 界面说明优先使用ASCII图示而非外部图片
• 数据对比使用表格而非文字描述

键盘快捷键表示

统一使用以下格式表示快捷键：

• 单键：Enter
• 组合键：Ctrl+C
• 顺序操作：Esc → i → Ctrl+S

配置文档规范

配置项说明

所有配置项需包含：

• 默认值：明确参数的默认设置
• 取值范围：允许的数值或选项列表
• 生效方式：是否需要重启及配置位置
• 使用场景：适用情况与注意事项

配置文件示例

提供完整可复制的配置文件示例，如：

{
  "providers": {
    "openai": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "anthropic": {
      "apiKey": "your-api-key",
      "disabled": false
    }
  },
  "autoCompact": true,
  "debug": false
}

文档版本控制

版本标识

文档应在标题下方明确标注版本信息： 文档版本：v1.0.0 | 最后更新：2025-10-22

更新记录

重大版本更新需包含变更记录：

• 新增功能：明确列出新增的文档章节
• 功能变更：说明修改内容及影响范围
• 已移除项：标注删除内容及替代方案

最佳实践与常见问题

文档质量检查清单

•  内容专业准确，无模糊表述
•  步骤可重复，无需额外上下文
•  代码示例可直接运行，无语法错误
•  关键术语使用一致，无同义不同名现象
•  图表与文字内容相互补充，无冗余

常见问题处理

文档编写中常见问题及解决方案：

问题场景	处理方法	参考文档
技术细节过多	拆分基础版与高级版文档	docs/advanced.md
跨平台差异	使用条件表格分别说明	docs/install.md
复杂操作流程	增加流程图辅助说明	docs/workflow.md

资源与工具

文档模板

项目提供标准文档模板：

• API文档模板：templates/api.md
• 用户手册模板：templates/manual.md
• 配置指南模板：templates/config.md

检查工具

文档编写完成后使用以下工具验证：

• 语法检查：markdownlint-cli2
• 链接验证：linkchecker
• 代码测试：shellcheck对所有示例代码进行验证

通过遵循以上规范，可确保OpenCode文档专业、易用且保持一致性，帮助用户快速掌握产品功能并充分发挥其价值。文档维护遵循"持续迭代"原则，鼓励用户反馈并定期更新内容。

【免费下载链接】termai 项目地址: https://gitcode.com/gh_mirrors/te/termai