tutti/docs/architecture/claude-code-sdk-requirements.md

Claude Code SDK 重构保真要求

本文定义 Tutti 中 Claude Code 集成的产品保真范围和重构验收边界。它描述的是必须长期成立的产品契约，不绑定旧代码结构。

Claude Code 只有一条运行链路：tuttid 启动 @tutti-os/claude-sdk-sidecar，sidecar 使用 Claude Agent SDK。不得增加运行时选择器、平行实现或仅供迁移期使用的第二套会话语义。

具体模块所有权和协议见 Claude Code SDK Runtime。

用户能力保真

安装、认证与状态

• 自动发现 Claude CLI、Node 和 SDK sidecar，展示安装、登录、版本、可用性和可恢复错误。
• 支持安装、登录、刷新，以及用户已有 Claude 订阅、Anthropic API Key、Auth Token 和兼容 endpoint。
• 展示账号套餐、会话与周额度、重置时间和 extra usage；自定义 API 配置允许 quota 不可用。
• 安装、登录、配置文件变化、运行时认证失败和账号切换后，provider 状态与模型目录必须同步失效和刷新。
• 所有可能刷新共享 OAuth credential 的启动操作必须串行，等待过程响应取消；隐藏模型发现不得破坏 token 旋转。
• macOS usage 读取必须以 Keychain 为主、$CLAUDE_CONFIG_DIR/.credentials.json 为兜底；AgentGUI 初次挂载不得访问 Anthropic usage API。

会话、历史与窗口

• 支持从 Agent Dock、Launchpad、Agent 提及及业务入口创建 Claude Code 会话。
• 支持项目目录和无项目会话、多会话、多工作台窗口及独立 Agent 窗口。
• 支持新建、恢复、重试、搜索、分页、重命名、置顶、删除、批量删除和在新窗口打开。
• 支持按项目、Chats、Pinned 和 Agent Target 浏览，并正确呈现运行、等待、完成、失败、取消和未读状态。
• 支持 Claude 本地历史导入，保留标题、项目、消息、最近模型和时间；重复导入必须幂等。
• 支持会话 handoff；多个窗口共享 daemon 中的同一份 durable session 和 activity 真相。

Composer 与上下文

• 支持普通文本、多行文本、长文本托管附件、图片、文件、目录和结构化 workspace reference。
• 支持 Workspace App、产物、Issue、历史 Agent 会话和 Agent Target mention，并由对应 Tutti skill 路由。
• 发现项目技能、个人技能和 Tutti 注入技能；支持 Claude slash commands 和参数提示。
• 支持 /compact、/context、/usage、/status、/fast、/plan、/goal 和 /review 对应能力。
• 忙碌时支持提示词排队、编辑、删除和立即发送；guidance 进入当前 turn，不创建普通下一 turn。

设置与能力协商

• 模型目录优先使用 live session，回退到 auth-scoped last-known-good cache，再回退静态模型。
• 支持 Default、账号动态模型、自定义模型、reasoning effort、Standard/Fast、权限模式和 Plan Mode。
• 模型、reasoning、速度、权限和 Plan Mode 可在 live session 中更新；active session 设置不反写新会话默认值。
• 静态 composer profile 是预启动权威；会话启动后以 runtime capability 为权威。
• Runtime 必须报告 image input、compact、token usage、rate limits、plan mode、interrupt、skills、review 和 goal；仅在实际启用时报告 browser/computer。
• capability 不可用时，GUI 隐藏或禁用入口，daemon 同时拒绝越权调用。

执行、活动与交互

• 实时显示回答、thinking、工具输入/进度/输出/终态、计划、后台 Agent、嵌套 Agent 和 task notification。
• SDK 消息在 daemon 边界归一为稳定 session/message/turn/tool identity；GUI 不读取 sidecar stdout 或 SDK 日志补数据。
• Assistant/thinking 分段、工具生命周期、文件 diff、usage 和 compact boundary 必须可乱序对账且不能重复终态。
• 支持 Allow、Allow for session、Reject、AskUserQuestion 和 ExitPlanMode；pending interaction 具备 object/null/omitted 三态语义。
• 支持停止、goal set/show/clear/complete、上下文用量、手动 compact、Undo/Reapply 和生成文件再次引用。
• 后台 Agent 使用 tool call identity 作为主键，保留父子链；子 assistant 文本不能提前终结 task。

Tutti 扩展能力

• 每会话在 run-scoped 目录生成 system prompt、Claude plugin、skills、manifest 和托管临时文件，不修改用户项目或用户 .claude 内容。
• 注入 tutti-cli、tutti-handoff、tutti-model-allocation、issue-manager、workspace-app 和 reference，按能力注入 browser/computer skill。
• Claude Code 可通过 Tutti CLI 访问 Workspace、Agent、Issue、Workspace App 和 reference bundle。
• Browser 由 daemon-owned tutti browser 路由；Computer 仅在开关、driver 和系统权限均满足时启用，启动时 fail fast 且不擅自弹授权框。

技术不变量

身份、所有权与持久化

• 兼容 provider 输入统一规范化为 claude-code；新会话必须携带可信 agentTargetId，daemon 校验 Target/provider 一致性。
• Tutti session、Claude provider session、turn、message 和 tool call id 各自稳定，不得互相替代。
• Provider 可用性、启动授权、会话生命周期、恢复、持久化和 activity 投影归 tuttid；Desktop 只拥有 Electron/host integration，AgentGUI 只消费规范化契约。
• Durable session 与 live process 分离。Idle release 只释放进程，不清 provider session id、resume cursor、历史活动或 runtime manifest。
• SQLite 投影和 agent.activity.updated 是跨窗口同步权威；optimistic prompt 只作为可对账 overlay。

原生配置与凭证安全

• 全链路尊重 CLAUDE_CONFIG_DIR、CLAUDE_CODE_EXECUTABLE、Anthropic credential、endpoint 和模型别名，不自行改写代理模型映射。
• SDK env 优先级为 sidecar process env、用户 settings、从根到 cwd 的项目 settings、daemon session env；损坏或缺失配置不得阻塞启动。
• 不得创建空配置目录隔离用户 credential，不得并发启动会触碰同一 OAuth refresh token 的 Claude 进程。
• 诊断只能记录 credential 是否存在、来源、过期信息和不可逆短 fingerprint；不得记录 token、prompt、账户名、个人路径、命令参数或异常堆栈原文。

Sidecar 与生命周期

• Sidecar 以 raw TypeScript 和生产依赖交付，由 managed Node 使用 --experimental-strip-types 执行。
• Daemon 与 sidecar 使用带版本的 NDJSON；stdout 只承载协议，stderr 有界收集且必须经过敏感字段清理。
• 协议支持 start、exec、guide、cancel、submit_interactive、apply_settings 和 close；请求 ack 使用 request id 和超时。
• close 必须等待 SDK query 完成关闭并收到 sidecar ack 后再关闭进程输入；UI 等待超时不得强杀仍在初始化或落盘 credential 的 SDK 进程。
• 每 session 只有一个持续 reader；turn 返回后仍处理后台 task、title、usage 和 session state。
• Start、Resume 和替换 live process 必须具备失败回滚；Close/reader failure/cancel 必须终结 pending interaction 并释放资源。
• Provider session id 和 opaque resume cursor 必须持久化；不可恢复错误不得静默创建 shadow session。

输入与 Activity

• 文本和图片在 daemon/adapter/sidecar 之间保持结构化 content blocks；文本 prompt 只作为兼容 fallback。
• 图片和附件由 Tutti 托管；daemon 重新校验 realpath、symlink、类型、大小和 state-root 边界。
• 每条 transcript message 必须有稳定 message id、正 version/sequence、turn id 和时间。
• Tool use、stream update、hook 和 result 合并为同一 call id；Edit/Write 的最终 diff 以成功响应的 structured patch 为准。
• Turn lifecycle 具有单调序列和原子 settle；取消幂等，迟到事件不能复活已终结 turn 或后台 task。

打包与可观察性

• Desktop 最终资源包含 sidecar 源码、生产依赖、managed Node contract 和平台 Claude binary，不依赖 monorepo、全局 npm 或开发机 workspace。
• Vendor 完成后必须从 vendored 路径启动进程并跑通 start/exec/close；Electron afterPack 后必须从最终 Resources 路径再次执行同一冒烟协议。
• 关键路径用 workspace/session/turn 关联 provider probe、install/login、prepare、start/resume、submit、usage、模型失效、auth refresh、stderr 和 event reconcile。
• 旧 provider id、旧 workbench state、旧 session provider-only 数据、旧消息 payload 和旧导入记录只在读取边界兼容；新写入使用当前契约。

重构验收门

合入前至少覆盖以下回归面：

领域	必测场景
探测与认证	PATH/CLI/Node、安装、登录、API credential、自定义 endpoint、账号切换、OAuth 并发续期
生命周期	创建、恢复、失败回滚、idle release 后再附着、close、进程异常、event reconnect
Composer	动态模型、live settings、skills、slash commands、browser/computer capability 降级
输入与活动	图片、附件、stream/thinking、tool/diff、审批、问题、后台与嵌套 Agent
状态机	compact、goal、cancel、guidance、busy queue、stop 后 queue suspension
持久化	session/message/activity 对账、分页、历史导入、跨窗口同步、usage quota
发布	vendored 路径启动、最终 Resources 路径启动、无仓库源码依赖、平台架构资源

局部修改先运行 sidecar/daemon/desktop 的针对性测试，再运行 pnpm check:changed。发布或大规模迁移完成时运行 pnpm check:full。