Skip to content

docs: add Chat suite documentation standard #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gene9831 wants to merge 1 commit into
base: docs/update-chat-ui-desc
Choose a base branch
from
Open

docs: add Chat suite documentation standard #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
361 changes: 361 additions & 0 deletions docs/chat-suite-documentation-standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,361 @@
# TinyRobot Chat 套件文档生成规范

## 1. 目的与适用范围

本规范用于指导 AI 编写、重构和评审以下两篇文档：

- `docs/src/suites/chat.md`
- `docs/src/suites/chat-runtime.md`

本规范是 [`component-documentation-standard.md`](./component-documentation-standard.md) 的 Chat 套件专用补充。两者同时适用；发生冲突时，本规范优先决定两篇 Chat 套件文档的职责划分和内容组织，通用规范继续约束 Demo、API 表格、术语、事实源和验证方式。

本文使用以下规范词：

- **MUST**：必须满足；不满足时不能认为文档已经完成。
- **SHOULD**：通常应满足；省略时应有明确理由。
- **MAY**：按当前改动范围和读者需要选择。

## 2. 文档目标与读者

两篇文档共同服务需要搭建聊天应用的开发者，但承担不同任务：

| 文档 | 首要读者 | 需要解决的问题 |
| ----------------- | -------------------------------- | ---------------------------------------------------------- |
| `chat.md` | 接入、配置和定制聊天界面的开发者 | 选择合适入口、完成首次聊天、定制常用区域、理解 UI 状态责任 |
| `chat-runtime.md` | 接入模型、会话和请求流程的开发者 | 选择 Runtime 入口、管理会话和请求、扩展发送流程、处理错误 |

AI MUST 按用户任务组织内容，不能按源码目录逐文件复述实现。读者不需要先理解 TinyRobot 内部架构，才能完成第一个可工作的聊天应用。

## 3. 套件概念与责任边界

### 3.1 首次出现时必须解释的概念

下列概念首次出现时，MUST 用一句到三句话说明“是什么、解决什么问题、何时选择”，不能只给出导入语句或函数签名：

| 概念 | 文档需要表达的责任 |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `TrChat` | 完整聊天套件；组合界面和 Runtime，适合大多数接入场景 |
| `TrChatUI` | 受控聊天界面；不负责模型请求和持久化，由应用提供数据并处理事件 |
| `ChatRuntime` | 连接聊天界面与会话、发送、取消等动作的状态和行为契约 |
| `useChatRuntime` | 根据模型和会话配置创建默认 Runtime；作为新项目的推荐入口 |
| `useChatRuntimeFromConversation` | 将已有 Kit `useConversation` 会话接入 Chat 套件；自定义回调时应用承担相应副作用 |
| `useChatRuntimeAdapter` | 将自定义 Runtime 状态和动作适配为 `TrChatUI` 所需数据和事件；属于高级集成入口 |

解释概念时 MUST 区分：

- 组件负责的可见界面；
- Runtime 负责的状态和动作；
- 应用负责的请求、持久化、受控状态或自定义回调；
- 使用默认实现与提供自定义实现后的责任变化。

### 3.2 选型说明

`chat.md` 的快速开始之前 MUST 提供简短选型说明，至少回答：

1. 新项目为什么优先选择 `TrChat + useChatRuntime`；
2. 什么情况下只使用 `TrChatUI`；
3. 已有 Kit 会话时使用哪个入口；
4. 需要完全自定义 Runtime 时从哪里继续阅读。

选型说明 SHOULD 使用表格或短列表，不在首屏展开全部类型和配置字段。

## 4. 两篇文档的职责划分

### 4.1 `chat.md` 的内容契约

`chat.md` MUST 聚焦聊天界面和套件使用，推荐结构如下：

```text
# Chat 聊天套件

## 概览与选择建议
## 快速开始
### 安装与样式
### 创建 Runtime 并完成第一次聊天

## 常用功能
### 配置输入区
### 配置消息展示
### 管理历史会话
### 配置欢迎区和推荐问题
### 调整布局与侧栏
### 使用插槽扩展界面
### 处理加载、错误和响应式布局

## 使用 TrChatUI
### 数据和事件责任
### 受控与非受控状态

## API
## 常见问题
```

标题可以根据实际内容调整，但 MUST 保持“选型 → 首次成功 → 高频任务 → 高级受控用法 → 参考”的学习顺序。

`chat.md` 的“常用功能”至少 MUST 覆盖下列任务域：

| 任务域 | 必须说明的入口或行为 |
| ------------ | ---------------------------------------------------------------------- |
| 输入区 | `ui.sender`、输入值、提交/取消、常用操作区和对应插槽 |
| 消息展示 | `ui.bubble`、角色配置、自动滚动、渲染或消息操作扩展 |
| 历史会话 | `ui.history`、会话选择、新建、重命名、删除，以及应用需要处理的副作用 |
| 欢迎与推荐 | `ui.welcome`、`ui.prompts` 与空会话状态的关系 |
| 布局 | 内容宽度、左右侧栏、浮窗、窄容器和移动端行为 |
| 定制 | 配置与插槽的适用边界、插槽是否替换默认行为 |
| 状态与反馈 | 加载、禁用、错误、取消及恢复路径 |

底层 Bubble、Sender、History、Welcome、Prompts 等组件已经有独立文档时，`chat.md` SHOULD 提供套件级最小示例并链接到底层完整 API，不能复制全部组件 API，也不能只给链接而不说明它们在 `TrChat` 中的配置入口。

### 4.2 `chat-runtime.md` 的内容契约

`chat-runtime.md` MUST 聚焦模型、会话、动作和应用责任，推荐结构如下：

```text
# Chat Runtime 配置与操作

## Runtime 概览
### 数据流与责任边界
### Runtime 入口选择

## 接入模型服务
### 基础配置
### 模型能力与 Provider 配置

## 会话与请求
### 发送和取消
### 新建、切换和复用会话
### 发送前处理
### 错误处理和恢复

## 高级接入
### 复用已有 useConversation
### 自定义模型请求
### 自定义 send
### 自定义 Runtime 与 Adapter
### MCP

## API
## 常见问题
```

`chat-runtime.md` 至少 MUST 说明：

- 每个 Runtime 工厂创建、复用或适配哪些状态；
- 默认发送流程中的会话创建、标题生成、请求状态和输入清理；
- 自定义 `request`、`send` 或动作后，哪些默认行为不再执行；
- 发送、取消、会话切换和错误状态之间的关系；
- 普通值、Ref 或 Getter 配置的响应式读取行为；
- 错误由哪里产生、如何传播、在哪里显示以及怎样恢复；
- MCP 等可选能力的安装条件和失败边界。

UI 布局和插槽细节不应在 `chat-runtime.md` 重复展开；需要展示 Runtime 与 UI 协同时，使用最小代码并链接回 `chat.md`。

## 5. 内容分层规则

### 5.1 教程、任务指南和参考必须分层

两篇文档都 MUST 区分三种内容：

1. **快速开始**：提供一条推荐路径，让读者完成第一次可观察的成功；
2. **任务指南**：围绕“配置输入区”“复用已有会话”等真实目标给出最小完整方案；
3. **API 参考**：完整、精确、可检索地记录公开契约。

不得使用一张超长 API 表替代任务指南，也不得在多个任务章节复制同一套完整类型定义。

### 5.2 渐进披露

AI SHOULD 按下列顺序提供信息：

1. 推荐且最常见的路径；
2. 常用配置；
3. 状态所有权和应用责任；
4. 自定义入口；
5. 边界情况和完整 API。

高级入口不能在解释默认路径之前突然出现。一个概念如果只服务后续高级场景，应在对应章节首次引入，而不是堆叠在快速开始中。

### 5.3 避免重复和漂移

- 同一个默认值、字段定义或行为规则 SHOULD 只有一个完整说明位置；其他位置使用链接和简短上下文。
- `chat.md` 负责 UI 配置和事件契约；`chat-runtime.md` 负责 Runtime 配置、状态和动作契约。
- 共享类型只在最适合检索的页面完整展开；另一篇文档只保留完成当前任务所需的片段。
- 类型代码块若不是完整声明，MUST 明确写为“片段”。
- 不能为了简洁编造源码中不存在的聚合类型、默认值或生命周期。

## 6. 源码事实源

AI 在新增或修改内容前 MUST 检查与当前描述直接相关的源码。至少按以下映射选择事实源：

| 文档内容 | 首要事实源 |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| 包根可导出的组件、函数和类型 | `packages/chat/src/index.ts` |
| `TrChat` Props、Events、Slots | `packages/chat/src/Chat.vue` 及其公开类型 |
| `TrChatUI` 数据和事件责任 | `packages/chat/src/ChatUI.vue` 及其公开类型 |
| `ui` 配置字段与默认值 | `packages/chat/src/types/ui/`、`packages/chat/src/ui/defaults.ts` |
| 默认 Runtime 行为 | `packages/chat/src/runtime/useChatRuntime.ts` |
| 已有会话适配与默认发送行为 | `packages/chat/src/runtime/useChatRuntimeFromConversation.ts` |
| Runtime 与 UI 的事件适配 | `packages/chat/src/runtime/useChatRuntimeAdapter.ts` |
| 底层界面组件行为 | 对应 `packages/components` 源码、公开类型和稳定测试 |
| Demo 是否真实可运行 | `docs/demos/chat/` 中被页面实际引用的文件 |

AI MUST 按所描述的问题选择事实源：

- 是否公开：检查包根导出；
- 类型和必填性：检查公开 TypeScript 类型；
- 默认值和运行时分支：检查实现；
- 可见行为和回归契约：检查实现及稳定测试；
- 示例使用方式：检查实际 Demo，但不能把 Demo 当成 API 公开性的唯一证据。

当类型、实现、测试和既有文档不一致时，AI 不得自行掩盖差异。应先在文档工作结果或评审意见中指出冲突，并说明采用了哪个事实源以及为什么。

## 7. 示例规范

### 7.1 快速开始示例

快速开始 MUST：

- 使用推荐入口 `TrChat + useChatRuntime`；
- 包含安装、样式、容器高度和 Runtime 创建所需上下文；
- 能观察发送、加载、回答和取消中的适用行为；
- 使用本地、确定且可恢复的模拟服务，或明确标注真实服务需要的前置条件；
- 不把长期模型密钥暴露在浏览器代码中；
- 给出继续阅读的精确链接。

### 7.2 任务示例

每个任务示例 MUST 只解决一个主要问题，并包含：

1. 一句预期结果；
2. 最小但完整的配置或代码；
3. 必要时说明状态由组件、Runtime 还是应用持有；
4. 自定义行为替换默认行为时的责任变化；
5. 指向完整 API 或底层组件文档的链接。

片段沿用前文变量时 MUST 明确说明，例如“以下 `runtime` 沿用快速开始创建的实例”。不能让读者猜测未展示的变量来自哪里。

### 7.3 自定义回调

`send`、`request`、`beforeSend`、错误处理器或 UI 事件等自定义回调的文档 MUST 说明：

- 调用时机；
- 输入参数；
- 返回值或 Promise 的影响；
- 默认逻辑是否仍会执行；
- 会话、消息、输入值、加载和错误状态由谁更新；
- 失败、取消或短路后的状态。

不得把只在默认实现中发生的行为描述成所有自定义实现都具备的行为。

## 8. API 参考规范

两篇文档的 API 章节遵循通用组件文档规范，并额外满足：

- `TrChat` 与 `TrChatUI` 的 Props、Events、Slots、Methods 分区清楚，不能混成一张无法识别归属的表；
- Runtime 工厂必须说明配置、返回状态、动作、错误和副作用，而不只是函数签名；
- 返回对象按“状态 / 派生状态 / 动作”分组；
- 核心对象 `ChatUIOptions`、Runtime 配置和 Runtime 返回值必须有一级结构概览；
- 受控字段必须同时说明对应更新事件和应用更新责任；
- `default-*` 与受控字段同时提供时，必须说明实际优先级；
- 默认值来自底层组件时，可以链接到底层文档，但套件覆盖或组合后的实际默认行为必须在套件文档中说明；
- 只有确认从公共入口导出的稳定或高级类型才能进入正式索引。

API 表中的说明 MUST 写行为和边界，不能只把字段名翻译成中文。

## 9. 术语与行文

两篇文档统一使用以下术语：

| 推荐术语 | 含义 |
| ---------- | ------------------------------------------------------------------ |
| 开发者 | 阅读并接入 Chat 套件的人 |
| 用户 | 操作聊天界面的最终用户 |
| 应用 | 组件外部持有状态、处理事件、调用服务或持久化数据的代码 |
| 聊天界面 | `TrChat` 或 `TrChatUI` 提供的可见 UI |
| Runtime | 向聊天界面提供状态和动作的契约或实例 |
| 会话 | Conversation；不要在同一语境无原因切换为“对话” |
| 消息 | Message；用于用户、助手、系统或工具产生的单条内容 |
| 输入区 | Sender/Composer 所在区域；源码标识符按实际 API 名保留 |

行文 MUST：

- 使用简体中文和明确主语；
- 优先写“应用更新状态”“Runtime 创建会话”，避免“进行相关处理”；
- 区分“默认会发生”和“应用需要执行”；
- 代码标识符使用反引号并保持源码大小写；
- 同一概念在两篇文档中保持同名。

## 10. AI 编写流程

AI 生成或重构两篇文档时 MUST 按以下顺序工作：

1. **确认范围**：确定本次修改涉及 `chat.md`、`chat-runtime.md` 或两者，以及目标读者任务。
2. **建立公开入口清单**：从包根导出确认相关组件、函数和类型是否公开。
3. **建立行为清单**：从实现和稳定测试确认默认值、分支、副作用、错误和取消行为。
4. **建立任务矩阵**：把本次涉及的能力映射到输入、消息、历史、布局、Runtime、会话、请求、错误等任务域。
5. **选择归属页面**：UI 使用放入 `chat.md`；模型、会话和动作放入 `chat-runtime.md`；另一页只保留必要链接。
6. **先写选型和任务说明**：先让读者知道为什么选择入口，再出现代码和 API 名。
7. **编写或复用 Demo**：优先复用符合单一目标的现有 Demo；新增 Demo 时遵守确定性和可恢复要求。
8. **补全 API 与边界**：核对公开接口、默认值、受控责任和自定义回调替换行为。
9. **检查交叉链接和去重**：确认两篇文档没有维护两套冲突定义。
10. **执行验证**：运行格式、类型、文档构建和适用的交互验证，并报告未执行项。

AI 不得仅根据现有文档改写现有文档。源码、公开类型和稳定行为是必要输入。

## 11. 生成前后检查清单

### 11.1 生成前

- [ ] 已确认改动对应的包根公共导出。
- [ ] 已检查相关 Props、Events、Slots、Runtime 配置和默认值。
- [ ] 已识别默认实现和自定义实现的责任差异。
- [ ] 已确认内容应进入 `chat.md` 还是 `chat-runtime.md`。
- [ ] 已找到可复用的底层组件文档和 Demo。

### 11.2 内容检查

- [ ] 快速开始之前已有概念和入口选择说明。
- [ ] 快速开始能够形成一次可观察的成功。
- [ ] 高频任务不只存在于 API 表中。
- [ ] 每个示例只有一个主要目标。
- [ ] UI、Runtime 和应用的责任边界明确。
- [ ] 默认行为没有被错误推广到自定义回调场景。
- [ ] 受控与非受控模式的所有权、事件和优先级明确。
- [ ] 类型片段与完整声明有明确区分。
- [ ] 两篇文档之间没有重复维护完整定义。
- [ ] 底层组件链接有套件上下文，不是裸链接列表。

### 11.3 验证检查

- [ ] `git diff --check` 通过。
- [ ] Markdown 格式化和项目要求的 lint 通过。
- [ ] 文档站构建通过。
- [ ] 新增或修改的 Demo 能在文档站渲染。
- [ ] 页面内锚点和跨页面链接有效。
- [ ] 与发送、取消、会话和受控状态有关的关键描述已对照源码验证。
- [ ] 未执行的验证及原因已在交付说明或 PR 中列出。

## 12. 禁止的生成模式

AI 不得生成以下内容：

- 在未解释责任和选型前直接引入 `useChatRuntime`、Adapter 等概念；
- 名为“常用功能”但只覆盖布局和视觉定制的章节；
- 把 Bubble、Sender、History 等完整 API 复制到套件文档；
- 只列类型签名、不解释状态所有权和副作用的 Runtime 参考；
- 把默认发送逻辑中的会话创建、输入清理或错误处理描述成自定义 `send` 的固有行为；
- 依赖真实密钥、不稳定远程服务或不可恢复状态的正式 Demo；
- 用“应用自行处理”“根据需要配置”替代具体责任说明；
- 从内部实现或旧文档推断未公开 API；
- 为了让示例简短而省略关键 import、状态来源或事件处理；
- 在两篇文档中维护内容不同的同一类型、默认值或行为说明。

## 13. 完成标准

只有同时满足以下条件，AI 才能声明 Chat 套件文档工作完成：

1. 新读者可以选择正确入口并完成第一次聊天；
2. 开发者可以按任务找到输入、消息、历史、布局、会话、请求和错误相关说明；
3. `TrChat`、`TrChatUI`、Runtime 与应用的责任清晰；
4. API、默认值和边界行为与当前公开源码一致；
5. 两篇文档职责清楚且没有相互冲突的重复定义；
6. 适用验证已经执行，未执行项得到明确披露。
2 changes: 2 additions & 0 deletions docs/component-documentation-standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
- 设计或调整一般性的 VitePress 侧边栏、文档导航或站点信息架构；公开入口的弃用状态发生变化时，仍必须按第 10 节检查首屏、导航标签和推荐链接是否保持一致；
- 直接新增或修改 CI 门禁。本文只记录作者和评审者应执行的验证责任。

修改 `docs/src/suites/chat.md` 或 `docs/src/suites/chat-runtime.md` 时，AI 和文档作者还 MUST 遵循 [TinyRobot Chat 套件文档生成规范](./chat-suite-documentation-standard.md)。该规范负责两篇 Chat 套件文档的职责划分、内容矩阵、源码核对顺序和生成流程。

本文使用以下规范词：

- **MUST**：必须满足；不满足时不能认为文档已经完成。
Expand Down