Kimi Code CLI 会话标题自动生成：GenerateTitleRequest 请求模型与后端实现解析

Kimi Code CLI 会话标题自动生成GenerateTitleRequest 请求模型与后端实现解析【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读Kimi Code CLI 的 Web 界面在管理会话Session时需要为每次对话自动生成简洁标题方便用户在会话列表与搜索中快速定位。GenerateTitleRequest正是该能力对外暴露的 HTTP 请求模型它仅包含两个均可选的字符串字段。本文以该请求模型为切入点讲解其字段含义、前后端数据契约、请求参数缺省时后端如何自动从wire.jsonl中抽取首轮对话以及标题生成的完整状态机AI 生成、回退标题、失败重试与幂等保护。一、模型概览两个可选字段构成的最小请求体GenerateTitleRequest是一个刻意保持轻量的请求模型——调用方可以只传空对象甚至完全不传请求体后端仍能完成任务。其字段定义如下NameType说明userMessagestring会话首轮的用户消息文本对应 wire 协议中的user_inputassistantResponsestring会话首轮助手Assistant的文本回复内容两个字段均为可选且在缺省时为null/undefined。这一点在官方文档中明确说明Parameters are optional - if not provided, the backend will read from wire.jsonl automatically.也就是说该模型更像是一个覆盖/提示参数如果你能提供首轮对话文本后端直接使用如果你不提供后端会自行从会话目录下的wire.jsonl中解析出第一轮对话。前后端双端定义该模型在仓库中同时存在后端与前端两套定义二者通过 OpenAPI 规范保持一致后端Python/Pydanticsrc/kimi_cli/web/models.py 中定义为class GenerateTitleRequest(BaseModel): Generate title request. Parameters are optional - if not provided, the backend will read from wire.jsonl automatically. user_message: str | None None assistant_response: str | None None前端TypeScriptweb/src/lib/api/models/GenerateTitleRequest.ts 中定义为接口GenerateTitleRequest属性为userMessage?: string | null与assistantResponse?: string | null。注意前后端字段名映射前端使用驼峰命名userMessage/assistantResponse而 JSON 线上传输与后端使用蛇形命名user_message/assistant_response。这一转换由 OpenAPI Generator 生成的序列化函数完成见 web/src/lib/api/models/GenerateTitleRequest.ts 中的GenerateTitleRequestToJSON/GenerateTitleRequestFromJSONTyped。二、请求示例TypeScript 调用范式文档给出了标准的 TypeScript 用法示例展示了构造对象 → 序列化为 JSON → 反序列化回对象的完整链路import type { GenerateTitleRequest } from ./models/GenerateTitleRequest const example { userMessage: null, assistantResponse: null, } satisfies GenerateTitleRequest console.log(example) // Convert the instance to a JSON string const exampleJSON: string JSON.stringify(example) console.log(exampleJSON) // Parse the JSON string back to an object const exampleParsed JSON.parse(exampleJSON) as GenerateTitleRequest console.log(exampleParsed)userMessage与assistantResponse均为null正对应不提供参数、交由后端自动读取的典型用法。实际调用中你可以传入其中任意一个或两个例如const req: GenerateTitleRequest { userMessage: 为我的 React 项目添加单元测试, assistantResponse: 好的我先查看项目结构并规划测试方案……, }对应的 JSON 请求体为{ user_message: 为我的 React 项目添加单元测试, assistant_response: 好的我先查看项目结构并规划测试方案…… }三、后端端点POST /{session_id}/generate-title 的完整处理流程GenerateTitleRequest是 Web API 端点POST /{session_id}/generate-title的请求体模型实现在 src/kimi_cli/web/api/sessions.py。整个处理流程可以概括为六个阶段1. 幂等保护已生成标题直接返回state load_session_state(session_dir) # Check if title was already generated (avoid duplicate calls) if state.title_generated: return GenerateTitleResponse(titlestate.custom_title or Untitled)会话状态持久化在会话目录的state.json中对应 src/kimi_cli/session_state.py 的STATE_FILE_NAME。SessionState模型src/kimi_cli/session_state.py包含三个与标题相关的关键字段custom_title: str | None——用户或系统最终确定的标题title_generated: bool——是否已完成标题生成用于去重title_generate_attempts: int——AI 生成失败的累计尝试次数。一旦title_generated为True后续请求直接返回既有标题避免重复调用 LLM 造成资源浪费。2. 参数优先缺省则回退读取 wire.jsonluser_message request.user_message if request else None assistant_response request.assistant_response if request else None if not user_message or not assistant_response: first_turn extract_first_turn_from_wire(session_dir) if first_turn: user_message, assistant_response first_turnextract_first_turn_from_wiresrc/kimi_cli/web/api/sessions.py是参数缺省时的兜底机制它逐行解析会话目录下的wire.jsonl遇到TurnBegin消息时取出payload.user_input作为用户消息在首轮范围内收集ContentPart中type text的文本片段拼接为助手回复遇到第二个TurnBegin或TurnEnd时停止确保只取第一轮对话。3. 回退标题无论如何都有结果即使既无参数、wire.jsonl 又无有效内容端点也不会报错而是返回默认值if not user_message: return GenerateTitleResponse(titleUntitled)而当用户消息存在时会基于消息文本生成回退标题from kimi_cli.utils.string import shorten user_text user_message.strip() user_text .join(user_text.split()) fallback_title shorten(user_text, width50) or Untitled即折叠空白后取用户消息前 50 个字符作为回退标题。4. 失败次数上限超过 3 次后放弃 AIif state.title_generate_attempts 3: fresh load_session_state(session_dir) ... fresh.custom_title fallback_title fresh.title_generated True save_session_state(fresh, session_dir) invalidate_sessions_cache() return GenerateTitleResponse(titlefallback_title)当 AI 生成连续失败title_generate_attempts 3时直接采用回退标题并标记为已生成防止无限重试。5. AI 生成标题约束最大 50 字符正常情况下端点通过kosong.generate调用 LLM 生成标题system_prompt ( Generate a concise session title (max 50 characters) based on the conversation. Only respond with the title text, nothing else. No quotes, no explanation. ) prompt fUser: {user_message[:300]} Assistant: {(assistant_response or )[:300]} Title:实现要点输入侧用户消息与助手回复各截取前 300 字符送入 prompt输出侧系统提示约束标题最长 50 字符、只输出标题文本本身生成的标题会去除首尾引号strip(\)若生成结果超过 50 字符使用shorten截断当 provider 为 Kimi 时会应用SESSION_TITLE_MAX_COMPLETION_TOKENS值为 512见 src/kimi_cli/web/api/sessions.py限制补全 token 数并尊重配置中已有的max_completion_tokens上限取两者较小值。6. 读-改-写并发安全地落盘fresh load_session_state(session_dir) # Another request or manual rename may have finalized the title while the # LLM call was in flight. Preserve that newer title instead of clobbering it. if fresh.title_generated: invalidate_sessions_cache() return GenerateTitleResponse(titlefresh.custom_title or Untitled) fresh.custom_title title if ai_generated: fresh.title_generated True else: fresh.title_generate_attempts fresh.title_generate_attempts 1 save_session_state(fresh, session_dir) invalidate_sessions_cache()这段读-改-写read-modify-write逻辑专门处理并发场景在 LLM 调用期间用户可能已通过手动重命名PATCH会话设置title见 src/kimi_cli/web/api/sessions.py或另一个请求抢先完成了标题生成。此时重新加载最新状态若title_generated已为True则保留新标题而不是覆盖它。AI 生成成功后title_generated置为True失败则累加title_generate_attempts。四、响应模型与调用链端点返回GenerateTitleResponsesrc/kimi_cli/web/models.py仅含一个字段class GenerateTitleResponse(BaseModel): Generate title response. title: str即无论走哪条路径缓存命中、AI 生成、回退标题或 Untitled最终都返回一个非空的title字符串保证调用方无需处理异常分支。从调用链来看该端点的依赖注入关系为POST /{session_id}/generate-title └─ generate_session_title(session_id, request, runner) ├─ get_editable_session(session_id, runner) # 校验会话可编辑 ├─ load_session_state(session_dir) # 读取 state.json ├─ extract_first_turn_from_wire(session_dir) # 缺参时解析 wire.jsonl ├─ kosong.generate(...) # AI 生成标题 ├─ save_session_state(...) # 原子写入 state.json └─ invalidate_sessions_cache() # 使会话列表缓存失效其中save_session_state通过 src/kimi_cli/utils/io.py 的atomic_json_write原子写入避免写入中途崩溃损坏状态文件invalidate_sessions_cache确保会话列表接口能立刻看到新标题。五、状态持久化与旧数据兼容标题生成状态最终落在会话目录的state.json中。值得注意的是src/kimi_cli/session_state.py 提供了从旧版metadata.json迁移的能力迁移时会合并以下标题相关字段custom_title旧字段title且值不为Untitled时才迁移title_generatedtitle_generate_attempts仅当新状态中该字段为 0 时迁移旧值。这套兼容逻辑保证了从旧版本升级到 Web 会话管理后已生成的标题不会丢失也不会触发重复生成。六、实战要点总结可完全省略请求体GenerateTitleRequest是 Web 端点中少见的零参数也能工作的请求模型后端会自动从wire.jsonl抽取第一轮对话TurnBegin的user_input 首轮文本ContentPart。显式传参会跳过 wire.jsonl 解析若调用方如前端界面已持有对话文本传入userMessage与assistantResponse可省去文件解析开销。注意字段命名映射TS 侧为驼峰userMessageJSON 线上为蛇形user_message手写 HTTP 请求时务必使用蛇形键名。结果具有幂等性无论请求多少次已生成标题的会话都会返回同一个title重复调用不会产生额外 LLM 费用。并发安全后端通过读-改-写 重新加载模式保证 LLM 调用期间的手动重命名不会被覆盖。标题约束AI 生成的标题最长 50 字符超出会被shorten截断输入文本各截取 300 字符Kimi provider 下补丁 token 数上限为 512并受配置中max_completion_tokens约束。需要进一步查看的仓库资源GenerateTitleRequest.md 官方文档、前端模型定义、后端端点实现、会话状态模型、OpenAPI 规范。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考