89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# PRD：用户输入历史 MCP
|
||
|
||
## 目标
|
||
|
||
新增公开只读 MCP `ccweb_list_user_inputs`，让 LLM 在实现或验收前读取指定 cc-web 对话（默认当前来源对话）最近的用户输入，降低实现偏离用户原始要求的概率。
|
||
|
||
## 范围
|
||
|
||
- 在正式 ccweb MCP `tools/list` 中暴露工具。
|
||
- 在内部 MCP 分派中实现只读查询。
|
||
- 从持久会话的 `messages` 中只筛选非空 `role=user` 文本。
|
||
- 引导表单提交后形成的普通 user 消息必须自然包含；未提交的 assistant 引导卡必须排除。
|
||
- 补 schema 契约测试、查询行为测试和相关回归。
|
||
|
||
不包含 UI、消息修改、全文搜索、assistant/tool/system 内容、附件正文解析或跨会话权限模型改造。
|
||
|
||
## MCP 契约
|
||
|
||
### 入参
|
||
|
||
- `conversationId?: string`：指定目标会话；缺省时使用 MCP 来源会话 ID。
|
||
- `limit?: integer`：默认 15，最小 1，最大 50。
|
||
- `maxChars?: integer`：默认 1000，最小 1，最大 1000；限制所有 `items[].content` 的 Unicode code point 总数。
|
||
- `additionalProperties: false`。
|
||
|
||
### 选择与截断
|
||
|
||
1. 只选择正文非空的 `role=user` 消息。
|
||
2. 先取最近 `limit` 条候选。
|
||
3. 从最新候选向更早候选分配 `maxChars` 预算。
|
||
4. 若剩余预算不足，保留当前消息开头，设置 `truncated=true`，停止加入更早消息。
|
||
5. 最终按旧到新排列，便于 LLM 理解要求演进。
|
||
6. Unicode 字符使用 code point 计数，不能按 UTF-16 code unit 把 emoji 拆成两字。
|
||
|
||
### 返回
|
||
|
||
成功结果：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"conversationId": "...",
|
||
"requestedLimit": 15,
|
||
"maxChars": 1000,
|
||
"totalChars": 123,
|
||
"returnedCount": 2,
|
||
"hasMore": false,
|
||
"items": [
|
||
{
|
||
"messageId": "...或 null",
|
||
"createdAt": "...或 null",
|
||
"content": "用户输入",
|
||
"contentChars": 4,
|
||
"originalChars": 4,
|
||
"truncated": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
`hasMore=true` 表示存在 limit 之外的更早用户输入，或字数预算截断/省略了候选。
|
||
|
||
### 错误
|
||
|
||
- 默认模式缺少来源会话：`missing_source_conversation`。
|
||
- 显式 `conversationId` 清洗后无效：`invalid_conversation_id`，不得回退来源会话。
|
||
- 目标会话不存在：`conversation_not_found`。
|
||
|
||
## 验收标准
|
||
|
||
- 工具 schema 与描述明确说明默认当前会话、最近 15 条、合计最多 1000 字和验收用途。
|
||
- 默认当前来源会话与显式指定会话均可查询。
|
||
- 默认只返回最近 15 条用户输入，并按旧到新排列。
|
||
- assistant/tool/system、空白 user 消息和未提交引导卡不进入结果。
|
||
- 引导表单提交产生的普通 user 消息进入结果。
|
||
- `limit` 与 `maxChars` 被正确默认和限制；所有正文总字符数不超过 `maxChars`。
|
||
- emoji 等非 BMP 字符按单个 code point 计数。
|
||
- 截断项、`hasMore`、计数字段和错误码可由回归测试稳定断言。
|
||
- 查询不修改会话文件、更新时间、未读状态或运行状态。
|
||
- 针对性测试与项目相关 regression 均通过。
|
||
|
||
## 实施顺序
|
||
|
||
1. 先写失败测试固定 schema、路由与行为。
|
||
2. 实现最小查询和 Unicode 预算逻辑。
|
||
3. 注册正式 MCP schema；仅在现有兼容策略确有需要时纳入旧 dynamic-tool 兼容集。
|
||
4. 跑针对性测试，再跑相关完整回归。
|
||
|