# CLI 参考

`tokst` CLI 是与 TokST 记忆系统交互的主要界面。以下所有命令按功能分组。

> 许多命令接受 `--atlas` 作为 `--atlas-id` 的简写。为任何命令传入 `--json` 可获取机器可读的输出。

Claude、Pi、Codex 等智能体执行命令时，可设置 `TOKST_AGENT=1` 或传入
`--agent`。这个增量模式提供紧凑且有上限的 JSON、网络硬截止时间、确定性
输出刷新，并跳过交互式版本检查。添加 `--full` 可获得完整的现有 JSON
响应；延迟输入管道使用 `--stdin`。

## Agent 身份与交接

`TOKST_AGENT=1` 或 `--agent` 会使用当前 API Key 绑定的可信 Agent 身份。首次调用会创建稳定的 `agt_...` 身份码，`--source` 保持为展示用来源标签。

`tokst agent list` 列出工作区 Agent；`tokst agent listen [--workspace <id>] [--json]` 保持实时事件流并为 Agent Runtime 输出 JSON Lines；`tokst message send` 支持 `--to agt_...` 定向发送或 `--broadcast` 广播；`tokst message inbox` 默认读取全部工作区的持久收件箱，可用 `--workspace <id>` 过滤；`tokst message acknowledge <id>` 和 `tokst message close <id>` 管理回执。

在长期运行的 Agent 旁启动 `TOKST_AGENT=1 tokst agent listen --json` 作为轻量 sidecar。连接恢复后会先输出未读消息快照；Agent 接受工作后再确认，完成后关闭回执。

---

## 认证

| 命令 | 描述 |
|---|---|
| `tokst version [--verbose]` 或 `tokst --version` | 显示已安装 CLI 版本；`--verbose` 同时显示当前安装渠道和可执行文件。 |
| `curl -fsSL https://tokst.com/install.sh \| bash` | 安装或升级通过 SHA-256 校验的独立 CLI，并保留已有授权。 |
| `irm https://tokst.com/install.ps1 \| iex` | 在 Windows PowerShell 安装或升级通过 SHA-256 校验的独立 CLI。 |
| `tokst update` | 按当前安装渠道升级：校验后的独立二进制、npm 或 Bun。 |
| `tokst login --key <key>` | 使用 API 密钥进行认证（`tk_live_xxxx`）。凭证保存到 `~/.tokst/config.json`。 |
| `tokst logout` | 清除存储的会话凭证。 |
| `tokst doctor [--fix-path]` | 检查认证、可选的 Git 仓库和知识库绑定、智能体集成文件与命令优先级；`--fix-path` 可在 zsh 或 bash 中优先使用独立 CLI。 |

```bash
curl -fsSL https://tokst.com/install.sh | bash
tokst version
tokst doctor
tokst login --key tk_live_abc123def456
tokst logout
```

`setup` 是推荐的交互式流程。它会打开 `tokst.com`，确认已登录账户，再将一次性凭据直接交给等待中的 CLI。它不会选择工作区或知识库：每条命令显式指定范围；终端需要活动工作区时使用 `tokst workspace switch`；仅当目录固定属于一个项目时才绑定知识库。API Key 登录继续适用于 CI、服务器和无人值守脚本。

## 帮助

`tokst --help` 展示日常工作流。使用 `tokst memory --help`、`tokst atlas --help`、`tokst workspace --help` 或 `tokst agent --help` 查看完整命令分组；`tokst help <group>` 提供相同的分组参考。

## 本地智能体初始化

为当前目录中的智能体生成本地指令。

```bash
tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor
```

`tokst init` 只写入本地智能体指令，可在任意目录使用。已有指令文件会被保留；需要刷新时使用 `--force`。使用 `tokst atlas init` 创建知识库，需要项目路由时再使用 `tokst atlas bind --atlas-id <id>` 绑定目录。`tokst doctor` 会报告认证、可选的 Git 仓库和知识库绑定，以及集成文件的检查结果。

---

## 知识库管理

知识库是保存相关记忆的命名知识库。

| 命令 | 描述 |
|---|---|
| `tokst atlas init --name <name>` | 创建新知识库 |
| `tokst atlas bind --atlas-id <id> [--path <path>]` | 将已有知识库绑定到目录；Git 元数据可选 |
| `tokst atlas list` | 列出活跃工作区中的所有知识库 |
| `tokst atlas rename --atlas-id <id> --name <new>` | 重命名知识库 |
| `tokst atlas profile --atlas-id <id> --keywords a,b,c` | 设置关键词配置以启用自动路由 |
| `tokst atlas delete --atlas-id <id>` | 删除知识库及其所有记忆 |

```bash
tokst atlas init --name "Project Alpha"
tokst atlas bind --atlas-id <id>
tokst atlas list
tokst atlas profile --atlas-id <id> --keywords architecture,backend,api
tokst atlas rename --atlas-id <id> --name "Project Alpha v2"
tokst atlas delete --atlas-id <id>
```

---

## 工作区管理

工作区将知识库分组，以实现组织隔离（例如，个人 vs. 团队）。

| 命令 | 描述 |
|---|---|
| `tokst workspace create --name <name>` | 创建新工作区 |
| `tokst workspace list` | 列出您所属的所有工作区 |
| `tokst workspace switch <workspace-id>` | 切换活跃工作区 |
| `tokst workspace members <workspace-id>` | 列出工作区成员和角色 |
| `tokst workspace invite <团队工作区-id> <email[,email,...]>` | 邀请最多 100 位用户加入团队工作区；支持 `--role` 和 `--expires-in-days` |

云端团队工作区创建会消耗账户的可用团队工作区配额。执行 `tokst workspace create --name <名称> --type team` 前，请先在用户后台申请或购买配额。本地模式保留独立的本地工作区模型。
| `tokst workspace invitations <workspace-id>` | 列出该工作区已发出的邀请 |
| `tokst workspace inbox` | 列出自己待处理的邀请 |
| `tokst workspace respond <invitation-id> --accept\|--decline` | 接受或拒绝邀请 |
| `tokst workspace revoke <invitation-id> --confirm` | 撤销待处理邀请 |
| `tokst workspace leave <workspace-id> --confirm` | 退出工作区 |
| `tokst workspace role <workspace-id> <user-id> --role admin\|member --confirm` | 修改成员角色 |
| `tokst workspace remove <workspace-id> <user-id> --confirm` | 移除成员 |
| `tokst workspace transfer-owner <workspace-id> <user-id> --confirm` | 转移工作区 Owner |

```bash
tokst workspace create --name "Team Engineering"
tokst workspace list
tokst workspace switch <workspace-id>
tokst workspace invite <workspace-id> alice@example.com,bob@example.com --expires-in-days 7
tokst workspace inbox
```

`tokst workspace list` 会标记已保存的当前工作区，并展示待处理邀请及接受、拒绝命令。`tokst workspace switch` 会保存选择，之后的 `tokst atlas init` 将在该工作区创建知识库。接受邀请后，再切换到新加入的工作区。

---

## 记忆操作

TokST 的核心 — 存储、检索和管理记忆。

### 记住 (Remember)

存储一条新记忆。这是最常用的命令。

```bash
tokst remember "Your content here" --type note
```

短事实可以使用纯文本。决策、架构、会议纪要和任务建议使用 Markdown。写入长内容时，可通过标准输入传入 Markdown 文件：

```bash
tokst remember --type decision --tags api,auth --stdin < decision.md
```

标题、列表、任务清单、链接、表格和代码块可以提升阅读效率。密钥、私钥、原始推理和临时工具输出保留在 TokST 之外。

| 选项 | 描述 |
|---|---|
| `--type` | 记忆类型：`fact`、`decision`、`preference`、`task`、`architecture`、`note`（默认：`note`） |
| `--tags` | 逗号分隔的标签，用于筛选（例如：`--tags deploy,production`） |
| `--source-type` | 来源类型：`human`、`agent`、`import`、`system`（默认：`human`） |
| `--source` | 来源名称，例如 `codex` 或 `import` |
| `--atlas` | 目标知识库 ID（`--atlas-id` 的简写） |
| `--title` | 可选的记忆标题 |
| `--file` | 附加一个或多个文件（可重复：`--file a.png --file b.pdf`） |
| `--evidence` | 证据 URL 或来源文件路径 |
| `--confidence` | 可信度，取值 `0` 到 `1` |
| `--valid-until` | 具有时效性信息的 ISO 到期时间 |

### 列表、更新、追加

```bash
tokst memory list                   # 列出最近的记忆
tokst memory update <id> --content "Updated content"
tokst memory append <id> --content "Additional information"
```

### 归档、恢复、删除

记忆遵循生命周期：活跃 -> 已归档 -> 已删除。

```bash
tokst memory archive <id>           # 归档（软隐藏）
tokst memory restore <id>           # 从归档恢复
tokst memory delete <id>            # 永久删除
```

### 验证与替代

为记忆补充证据、可信度和可选有效期后，可将其标记为已验证。新信息替代旧信息时，保留两条记忆之间的关联，以便追溯原有决策。

```bash
tokst memory verify <id> --evidence https://example.com/source --confidence 0.95
tokst memory verify <id> --valid-until 2027-01-01T00:00:00Z
tokst memory supersede <旧记忆-id> <新记忆-id>
```

### 文件附件

```bash
tokst memory attach <id> --file document.pdf
tokst memory download <id>                       # 下载所有附件到 ~/Downloads
tokst memory download <id> --out ./files         # 指定输出目录
tokst memory download <id> --attachment-id <aid> # 下载指定附件
```

---

## 搜索与上下文

```bash
tokst search "keyword query"        # 自适应 auto 模式（默认）
tokst search "query" --search-mode keyword
tokst search "query" --search-mode semantic
tokst search "query" --search-mode hybrid
tokst search "query" --type fact    # 按类型筛选
tokst search "query" --tags api     # 按标签筛选
tokst search "query" --limit 20     # 限制结果数（默认：10）
tokst search "query" --json         # 机器可读输出

tokst context                       # 当前知识库上下文快照
tokst context --atlas <id>          # 指定知识库的上下文
tokst context --limit 50            # 包含最多 50 条最近记忆
```

`tokst context` 返回当前知识库中最近记忆的格式化摘要 — 适用于为 AI 智能体提供对话上下文。

`--json` 会返回最终模式、embedding 缓存层级以及关键词、embedding、向量和总耗时。`SEARCH_DEFAULT_MODE=keyword` 可立即切换为纯关键词默认路径。

---

## 批量导入

从文件夹（或单个文件）批量导入记忆。文本文件自动提取内容；二进制文件作为附件上传，文件名作为记忆内容。

```bash
tokst import ./docs                          # 导入文件夹中的所有文件
tokst import report.pdf                      # 导入单个文件
tokst import ./code --type architecture      # 设置默认记忆类型
tokst import ./docs --tags imported,docs     # 为所有导入的记忆添加标签
tokst import ./large-dir --max 50            # 限制最多导入 50 个文件
tokst import ./docs --dry-run                # 预览不实际导入
tokst import ./docs --no-attach              # 仅创建文本记忆，不上传原文件
```

**支持的文本格式**（自动提取）：txt、md、json、csv、yaml、xml、html、css、js、ts、tsx、py、go、rs、java、sql、sh 等 30+ 种。

**二进制格式**（作为附件上传）：pdf、png、jpg、docx、xlsx 等所有其他格式。

| 选项 | 说明 |
|------|------|
| `--type` | 所有导入记忆的默认类型（默认：`note`）|
| `--tags` | 逗号分隔的标签，添加到所有导入记忆 |
| `--atlas-id` | 目标知识库（默认：自动路由或第一个知识库）|
| `--source` | 来源名称（默认：`import`）|
| `--dry-run` | 扫描预览，不实际导入 |
| `--max` | 最多导入的文件数量 |
| `--no-attach` | 仅创建文本记忆，跳过原文件上传 |

---

## 实用工具

| 命令 | 描述 |
|---|---|
| `tokst status` | 显示套餐、用量、存储、个人工作区与知识库配额、团队工作区配额及记忆统计 |
| `tokst status --json` | 同上，JSON 格式供脚本使用 |
| `tokst migrate` | 在架构之间迁移数据（管理员使用） |
| `tokst sync` | 强制将本地状态与服务器同步 |

```bash
tokst status
```

示例输出（云端模式）：

```
Mode:     Cloud (Supabase)
Endpoint: https://pdjpdivokmcevxdrvtfb.supabase.co

Plan:        pro    206 / 10,000 calls this month   (2% used, resets Jul 1)
Storage:     673 KB / 10.00 GB   7 files   (0% used)

Quotas:
  Personal workspaces:  2 / 10       8 available
  Personal Atlases:     7 / 200      193 available   (20 per workspace)
  Team workspaces:      3 / 5        2 available to create

Summary:
  Workspaces:  2
  Atlases:     7
  Memories:    248 active

Workspaces:
  kueen
  personal

Atlases:
  TokST             in kueen          43 mem  (fact=13, architecture=18, decision=9, note=3)
  ...
```

`Plan:`、`Storage:` 和 `Quotas:` 行仅在云端模式显示。`--json` 会额外输出 `account` 块，包含 `plan`、`monthlyLimit`、`periodResetAt`、`usage`、`storage` 和 `quota` 字段。没有上限的配额会显示为 `unlimited`。

---

## 通用选项

| 选项 | 描述 |
|---|---|
| `--json` | 以 JSON 格式输出结果（而非格式化文本） |
| `--atlas` | `--atlas-id` 的别名，指定目标知识库 |
| `--help` | 显示任何命令的帮助信息 |
| `--version` | 显示 CLI 版本 |

所有命令都支持 `--help` 查看详细用法：

```bash
tokst remember --help
```

## 会话记忆

会话记忆用于多步骤任务和智能体交接。

```bash
TOKST_AGENT=1 tokst session start --atlas-id <atlas-id> --task "实现会话记忆" --json
TOKST_AGENT=1 tokst session capture --session <ses-id> "写入使用幂等键" --kind decision --tags api,reliability --json
TOKST_AGENT=1 tokst session checkpoint --session <ses-id> "服务端路由已完成" --json
TOKST_AGENT=1 tokst session finalize --session <ses-id> "已完成服务端路由与契约。" --json
```

`session start` 返回当前范围的上下文；`capture` 保存候选记忆；`finalize` 写入会话快照，并默认将候选内容编译为正式记忆。添加 `--no-compile` 可保留候选内容等待审核。
使用 `tokst session candidates --scope mine --status pending` 查看自己的待审核队列。Owner 与 Admin 可使用 `--scope managed` 查看整个工作区，并对候选执行编译、驳回、撤销和归档；撤销会归档关联正式记忆并保留审计链路。

### 自动记忆

自动记忆由用户在当前设备主动启用。`tokst auto on` 会检测 WorkBuddy、OpenCode、Pi、Codex 与 Claude Code，安装各自的原生桥接器并启动本机服务。OpenCode 全局插件同时覆盖终端和 macOS App；Pi 使用全局扩展；Codex 与 Claude Code 使用托管 Hook，并完整保留用户已有 Hook；外部 ACP Host 继续使用 ACP 入口。TokST 在本机脱敏后自动保存一条可撤销的正式记忆。原始内容默认即时删除，可选保留 24 小时用于本机故障恢复。

```bash
tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
tokst auto verify --agent all --json
tokst auto privacy --retain-raw 24h
```

OpenCode 终端与 macOS App 使用全局插件。安装一次后重启 OpenCode；通过 `opencode -s` 恢复的会话会更新同一条自动记忆：

```bash
tokst auto on --agent opencode
tokst acp opencode --doctor
# OpenCode 正常启动即可自动加载插件。
# 外部 ACP 宿主可配置 command=tokst，args=["acp", "opencode"]
```

`tokst auto repair --agent <name>` 刷新指定桥接器，`tokst auto off --agent <name>` 仅移除该桥接器，`tokst auto logs --agent <name>` 查看本机诊断。`tokst acp opencode --repair` 保留 ACP Host 修复流程，`tokst acp pi --doctor` 显示 Pi 直接桥接与可选 ACP Host 适配器状态。

自动记忆会启动用户级服务。网络中断时已脱敏事件保留在本机队列中，并以事件 ID 安全补传。个人工作区和默认知识库作为默认路由；团队工作区由用户显式切换后生效。

完整生命周期、重试键、本地工作流、后台治理和 MCP 工具映射请阅读[会话记忆指南](/docs/sessions)。