Kimi Code CLI Web 接口 CreateSessionRequest 模型全解析从请求字段到会话创建的完整链路【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读CreateSessionRequest是 Kimi Code CLI 内置 Web 界面kimi web对外开放的会话创建请求模型定义了一次新建会话操作需要携带的全部参数目标工作目录workDir与是否自动建目录createDir。本文以 web/src/lib/api/docs/CreateSessionRequest.md 为骨架结合后端路由实现、前端 Hook 与 TypeScript 模型完整还原从 HTTP 请求体到 Kimi CLI 会话实体落地的全过程读完你即可独立调用POST /api/sessions/创建属于自己的编程会话。一、CreateSessionRequest 是什么CreateSessionRequest是 Kimi Code CLI Web 服务由kimi web启动的本地 Web 界面的 OpenAPI 请求体模型由 OpenAPI Generator 从后端 FastAPI 路由自动生成web/src/lib/api/models/CreateSessionRequest.ts头部注释标明版本为 OpenAPI document 0.1.0。它对应后端 src/kimi_cli/web/api/sessions.py 中定义的 Pydantic 模型class CreateSessionRequest(BaseModel): Create session request. work_dir: str | None None create_dir: bool False # Whether to auto-create directory if it doesnt exist模型本身只包含两个可选字段语义清晰告诉服务端在哪里为新的 CLI 会话建立工作目录以及目录不存在时怎么办。其余会话初始化逻辑标题、会话目录、状态机全部由后端完成请求方无需关心。二、字段详解字段TypeScript 侧JSON 键wire 格式类型默认值含义workDirwork_dirstring \| null缺省后端取用户主目录新会话的工作目录路径支持~展开createDircreate_dirbooleanfalse当workDir指向的目录不存在时是否自动递归创建两个字段均为可选当请求体为空或字段缺失时后端自动回退到用户主目录Path.home()。createDir默认false意味着默认策略是目录必须已存在这是出于安全与可预期的考量——服务端不会在用户未明确授权时擅自创建目录。在 TypeScript 侧模型定义于 web/src/lib/api/models/CreateSessionRequest.ts并配套提供了CreateSessionRequestFromJSON/CreateSessionRequestToJSON序列化函数负责在 camelCaseworkDir/createDir与 snake_casework_dir/create_dir之间转换。三、后端语义POST /api/sessions/ 的完整行为CreateSessionRequest唯一的使用场景是POST /api/sessions/端点SessionsApi.md对应后端create_session路由src/kimi_cli/web/api/sessions.py。其处理流程可拆解为以下步骤解析并规范化路径Path(request.work_dir).expanduser().resolve()支持~主目录缩写并解析符号链接与相对路径。目录存在性校验目录存在进入下一步目录不存在且create_dirTruemkdir(parentsTrue, exist_okTrue)递归创建权限不足时返回403 Permission denied其他OSError返回400 Failed to create directory目录不存在且create_dirFalse返回404 Directory does not exist: {work_dir}这正是前端 Hook 专门捕获的错误类型路径存在但不是目录返回400 Path is not a directory。转换为 KaosPath通过KaosPath.unsafe_from_local_path(work_dir_path)将本地路径包装为 Kimi CLI 的跨主机路径类型该能力来自同仓库的kaos包packages/kaos/src/kaos/path.py以便会话元数据与远程/本地路径语义统一。创建 CLI 会话await KimiCLISession.create(work_dirwork_dir)调用 src/kimi_cli/session.py 的会话工厂生成会话 ID、初始化context.jsonl会话上下文文件与会话目录。失效缓存invalidate_sessions_cache()与invalidate_work_dirs_cache()清空会话列表缓存保证后续GET /api/sessions/能立即看到新会话。请求与响应速查项值方法/路径POST /api/sessions/Content-Typeapplication/jsonAcceptapplication/json成功响应200返回 Session 对象失败响应404目录不存在、400非目录/建目录失败、403无权限、422请求体校验失败四、调用示例4.1 最小请求使用默认工作目录请求体可为空后端自动回退到用户主目录curl -X POST http://localhost:8000/api/sessions/ \ -H Content-Type: application/json4.2 指定工作目录目录已存在curl -X POST http://localhost:8000/api/sessions/ \ -H Content-Type: application/json \ -d {work_dir: /data/web/disk1/git_repo/MyProject}4.3 目录不存在时自动创建curl -X POST http://localhost:8000/api/sessions/ \ -H Content-Type: application/json \ -d {work_dir: ~/projects/from-web-ui, create_dir: true}此时后端会执行mkdir(parentsTrue, exist_okTrue)递归创建目标目录。4.4 TypeScript 侧完整示例沿用 CreateSessionRequest.md 的序列化范式实际项目中可通过生成的 SDK 调用import { SessionsApi } from ./lib/api; import type { CreateSessionRequest } from ./lib/api/models/CreateSessionRequest; const request: CreateSessionRequest { workDir: /data/web/disk1/git_repo/MyProject, createDir: true, }; const api new SessionsApi(); const session await api.createSessionApiSessionsPost({ createSessionRequest: request, }); console.log(session.sessionId, session.workDir);五、前端实战useSessions Hook 中的调用模式Kimi Code CLI 自带的 Web 前端在 web/src/hooks/useSessions.ts 中封装了createSession(workDir?, createDir?)。值得注意的实现细节是该 Hook没有走生成 SDK 的createSessionApiSessionsPost而是直接用fetch请求POST /api/sessions/注释明确说明这是为了支持work_dir参数并保持请求体在字段为空时不发送任何 bodyconst body: { work_dir?: string; create_dir?: boolean } {}; if (workDir) { body.work_dir workDir; } if (createDir) { body.create_dir createDir; } const response await fetch(${basePath}/api/sessions/, { method: POST, headers: { Content-Type: application/json, ...getAuthHeader() }, body: Object.keys(body).length 0 ? JSON.stringify(body) : undefined, });前端还针对后端404 Directory does not exist的响应专门抛出了DirectoryNotFoundError上层 UIweb/src/App.tsx可据此提示用户补选目录或勾选自动创建选项——这是workDir/createDir两个字段在真实交互中配合使用的典型场景。六、响应对象新会话长什么样创建成功后返回 Session 元数据对象字段如下字段类型说明sessionIdstring会话 UUIDtitlestring会话标题lastUpdatedDate最后更新时间取自context.jsonl的文件修改时间isRunningboolean新建会话恒为falsestatusSessionStatus状态快照新建时为stoppedworkDirstringKaosPath 序列化后的工作目录sessionDirstring会话数据目录含context.jsonl、wire.jsonl等后端在 src/kimi_cli/web/api/sessions.py 中手工构造该响应last_updated取context_file.stat().st_mtimestatus初始化为statestopped且seq0说明新会话尚未启动任何后台 worker 进程需要后续通过 WebSocket 流/api/sessions/{session_id}/stream连接后才会真正拉起 CLI 运行环境。七、底层原理从请求到 Kimi CLI 会话将CreateSessionRequest放到更大的链路中看一次创建操作实际触发的是POST /api/sessions/ (CreateSessionRequest) → create_session (src/kimi_cli/web/api/sessions.py) → KaosPath.unsafe_from_local_path(work_dir) → KimiCLISession.create(work_dir...) (src/kimi_cli/session.py) → 生成 session_id / 初始化会话目录与 context.jsonl → invalidate_sessions_cache / invalidate_work_dirs_cache → 返回 Sessionstopped 状态从源码结构看KimiCLISession是 CLI 本体与 Web 层共享的会话核心它负责上下文文件context.jsonl与 wire 消息文件wire.jsonl的维护Web 端后续的标题生成POST /{session_id}/generate-title会从wire.jsonl提取首轮对话、forkPOST /{session_id}/fork等操作均以该会话目录为数据基础。因此CreateSessionRequest虽只有两个字段却是整个 Web 会话管理生态的入口契约。八、常见问题与边界情况workDir 传了但 createDir 为 false目录不存在返回404 Directory does not exist不会创建目录。前端应提示用户切换目录或勾选自动创建。路径存在但是普通文件返回400 Path is not a directory。没有权限创建目录返回403 Permission denied: cannot create directory ...。workDir 完全省略回退到Path.home()用户主目录无需任何前置条件。请求体校验失败字段类型不匹配如create_dir传了字符串时返回422 Validation Error这是 FastAPI Pydantic 的标准校验行为。参考文件索引模型文档web/src/lib/api/docs/CreateSessionRequest.md端点文档web/src/lib/api/docs/SessionsApi.md响应模型web/src/lib/api/docs/Session.md后端路由与模型定义src/kimi_cli/web/api/sessions.pyTypeScript 模型web/src/lib/api/models/CreateSessionRequest.ts前端调用封装web/src/hooks/useSessions.ts【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考