JSON-RPC 参考

本地客户端通过 daemon socket（~/.carina/daemon.sock）或 stdio 使用 JSON-RPC 2.0。注册表 protocol/jsonrpc/methods.json 和 protocol/schemas/ 是方法与 schema 的权威来源。

session.create

创建绑定到工作区和权限 profile 的会话。

字段	类型	必填	说明
workspace_root	string	是	会话绑定的绝对工作区路径
profile	string	否	能力配置，默认 safe-edit

结果包含不透明的 session_id、绑定后的 workspace_id 与实际 profile。

request.json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session.create",
  "params": {"workspace_root": "/repo", "profile": "safe-edit"}
}

Gateway 与 daemon

方法	作用
runtime.initialize	协商客户端身份与 projection 版本
runtime.capabilities	返回运行时能力
gateway.hello / gateway.methods	返回契约快照和实时方法目录
gateway.token.issue	本地签发带作用域 token；要求签名密钥
daemon.status / metrics / doctor	运行状态和健康检查
daemon.remote.disable	远程入口总开关
daemon.reload	重新加载配置

会话与任务

方法	作用
session.create / get / list / close	会话生命周期
session.pause / resume	暂停与继续
session.replay / items / review	历史、UI 投影与治理视图
session.events.stream	类型化实时事件
execution.start / cancel / status	任务控制
governance.action.approve / deny	处理待审批动作

工作区

方法	作用
workspace.tree	通过 carina-scan 获取文件树
workspace.search	通过 carina-grep 结构化搜索
workspace.file.get	按 FileRead 能力读取工作区内不超过 1 MiB 的相对路径 UTF-8 文件
workspace.diff	有上限的 tracked / untracked diff；忽略二进制
workspace.patch.propose / apply / rollback	事务补丁生命周期
worktree.*	隔离 worktree 的创建、查询与进入

Memory

方法	作用
memory.list	列出 memory 或 user 目标的条目
memory.context	返回当前会话的围栏式召回片段
memory.status	本地权威、外部召回健康与身份 scope
memory.write	经 MemoryWrite 能力增删改或批处理
memory.projection.*	可选 HMS projection 的授权、重试与重播

memory.write 仅限本地控制面，默认需要审批。审计只记录目标、scope、动作、操作数和内容哈希，不记录原始记忆文本。

Worker 租约

worker.register 只返回一次 worker_id 与 credential，daemon 只保存 credential 哈希。work.poll 返回 lease_generation fencing token，后续 work.renew 和 work.report 必须原样回传，防止旧租约发布结果。

Context engine

方法	Scope	作用
context.status	read	配置值与实际生效的本地 engine 状态
context.doctor	read	daemon doctor 使用的健康探针
context.stats	read	压缩计数
context.compress	write	诊断压缩，不走 Agent transcript

Carina 不内置或启动外部压缩运行时；auto mode 会使用本地 no-op 实现。

运维检查边界

• workspace.diff 禁用 Git locks、fsmonitor、external diff 和 textconv；单份文本 diff 上限 256 KiB，响应上限 1 MiB。
• mcp.inventory 只返回公共 server / tool 名称、prompt 数量和连接健康，不泄露进程参数、环境变量或 schema。

event.json

{"jsonrpc":"2.0","method":"event",
 "params":{"event_id":"evt_...","session_id":"sess_...",
 "type":"CommandStarted","permission_decision_id":"perm_..."}}

提示

agent.*、session.checkpoint.*、workflow.*、schedule.*、channel.*、extension.* 与 telemetry 等完整分组请在方法目录中过滤查看。

权威来源

• 注册表：protocol/jsonrpc/methods.json · 叙述：docs/rpc-api.md
• 双目录：apps/docs → pnpm sync-protocol · 方法目录
• 相关：API 概览 · API 版本 · 会话

下一步

• 方法目录 — 完整列表与 Try it
• 会话 — 会话生命周期方法