Files

4.4 KiB
Raw Permalink Blame History

Task Plan: 新增用户输入历史 MCP

Goal

为 cc-web 增加一个只读 MCP,可读取指定对话(默认当前来源对话)最近的用户输入,纳入引导表单提交内容,并把所有返回正文控制在合计 1000 个 Unicode 字符以内,供 LLM 作为验收参考。

Current Phase

Phase 3

Phases

Phase 1: 代码发现与契约确认

  • 梳理会话消息存储与 ccweb MCP 注册链路
  • 明确用户输入筛选、默认会话与截断规则
    • 必须确认普通用户输入与引导表单提交的持久化形态。
    • 必须确认来源会话缺失、指定会话不存在时的错误语义。
  • Status: complete

Phase 2: 测试与实现

  • 编写新 MCP 的失败回归测试
    • 覆盖默认当前对话、显式指定对话、默认最近 15 条、仅返回 user 内容。
    • 覆盖引导表单提交消息、合计 1000 字预算、截断标记及缺失来源会话。
  • 实现指定/当前会话的用户输入读取与限制逻辑
  • 注册 MCP schema、描述与运行时上下文
  • Status: complete

Phase 3: 验证与交付

  • 运行针对性测试并修复发现的问题
  • 执行相关回归、核验接口并整理交付
  • Status: complete

Key Questions

  1. 普通用户输入和引导表单提交在持久层中如何标记、是否都使用 role=user?(已确认:提交后经普通 handleMessage 持久化为 role=user;待提交卡是 role=assistant)
  2. 当前来源对话 ID 从哪个线程级运行时上下文解析?(已确认:JSON-RPC/内部 HTTP 上下文把 sourceSessionId 传给 callInternalMcpTool)
  3. MCP 工具注册、参数校验和权限边界由哪些模块负责?(已确认:lib/ccweb-mcp-server.js 的 TOOLS/isCallableToolName 与 server.js 的内部 MCP 分派)

Decisions Made

Decision Rationale
默认返回最近 15 条,最终按时间从旧到新排列 兼顾最近性与作为验收标准时的可读性
所有返回正文合计默认且硬性最多 1000 个 Unicode 字符 避免 15 条输入最坏膨胀到约 15000 字,保证验收上下文可控
从最新输入向前消耗字数预算,最终按旧到新输出 优先保留最新验收要求,同时维持自然阅读顺序
预算导致内容或更早消息未完整返回时给出截断/更多标记 避免 LLM 将不完整历史误认为完整要求
仅返回用户输入,不混入 assistant/tool/system 内容 保持用户原始验收意图纯净

MCP Contract

  • 工具名为 ccweb_list_user_inputs。
  • 入参:
    • conversationId?: string:缺省时使用 MCP 来源会话 ID。
    • limit?: integer:默认 15,允许 1–50。
    • maxChars?: integer:默认 1000,允许 1–1000;约束所有 items[].content 的字符总和。
  • 返回:
    • conversationId、requestedLimit、maxChars、totalChars、returnedCount、hasMore。
    • items[] 至少含 content、createdAt、truncated;若持久层有稳定消息 ID,则同时返回 messageId。
  • 排序与预算:先选最近 limit 条用户输入,再从最新向前填充 maxChars 预算,最终将已选内容按旧到新返回。
  • 默认当前会话但运行时没有来源会话 ID 时返回明确参数错误;显式指定不存在的会话时返回 not-found 错误。

Errors Encountered

Error Attempt Resolution
计划审查指出 1000 字是逐条还是合计存在歧义 1 收紧为所有返回正文合计硬上限 1000 字,并固化预算顺序
codebase-memory 单次查询误报项目未索引 1 立即用 list_projects/index_status 复核,项目实际为 ready;后续收敛查询重试,不触发无谓重建
codebase-memory 重试返回 Transport closed 2 停止重复 MCP 调用,降级到本地 rg/sed 精确核验小函数
初版失败测试覆盖 HOME 且误排除提交表单标题 1 已退回测试代理修正环境隔离与角色/ID 断言后再验红灯
主线程生产补丁因代理并发落盘而校验失败 1 apply_patch 安全拒绝覆盖;检查 git diff 后确认代理已完成目标改动,直接进入验证

Notes

  • 计划与根目录 CSV、update_plan 保持一一同步。
  • 研究发现写入 findings.md,测试结果写入 progress.md。
  • 当前运行进程尚未重载:发现另一个非当前对话仍为 running,按项目约定暂缓 pm2 restart ccweb --update-env。