cc-viewer 1.6.342 → 1.6.344

package/server/system-prompt-templates/reference/claude-code-cli-startup-options.md

@@ -0,0 +1,325 @@
+# Claude Code CLI Startup Options — Complete Reference
+
+> Target version: **Claude Code 2.1.195** (`claude --version`)
+> This document is translated and organized from the `claude --help` output of that version,
+> grouped by use case.
+> Items marked `--print` only are effective only in non-interactive (print / SDK) mode.
+
+---
+
+## Basic Usage
+
+```
+claude [options] [command] [prompt]
+```
+
+- Default: starts an **interactive session**.
+- Add `-p` / `--print` for **non-interactive mode** (prints result and exits, suitable for pipes / scripts).
+- `prompt`: passed directly as the first prompt (positional argument).
+
+```bash
+claude                          # Interactive session
+claude "帮我看下这个目录"         # 交互式会话 + 首条提示
+claude -p "总结 README"          # 非交互，打印后退出
+echo "代码内容" | claude -p "审查"  # 管道输入
+```
+
+---
+
+## 一、模型与推理
+
+| 参数 | 说明 |
+|------|------|
+| `--model <model>` | 本次会话使用的模型。可传别名（`fable` / `opus` / `sonnet`，取该系列最新款）或完整名（如 `claude-fable-5`）。 |
+| `--fallback-model <model>` | 主模型过载 / 不可用时自动回退到指定模型。支持逗号分隔多个，按顺序尝试；每个用户回合开始时会重试主模型。**仅 `--print`**。 |
+| `--effort <level>` | 本次会话的推理强度：`low` / `medium` / `high` / `xhigh` / `max`。 |
+| `--agent <agent>` | 本次会话使用的 agent，覆盖 `agent` 设置。 |
+| `--agents <json>` | 用 JSON 内联定义自定义 agent，例：`'{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}'`。 |
+
+---
+
+## 二、System Prompt（系统提示词）
+
+| 参数 | 说明 |
+|------|------|
+| `--system-prompt <prompt>` | 本次会话使用的 system prompt（**整段替换**默认 prompt）。 |
+| `--append-system-prompt <prompt>` | 在默认 system prompt 之后**追加**一段（保留 Claude Code 默认能力）。 |
+| `--system-prompt-file <file>` | 从文件读取，**整段替换**默认 system prompt。隐藏参数（不在 `--help` 主列表，但实测可用）。 |
+| `--append-system-prompt-file <file>` | 从文件读取，**追加**到默认 system prompt 之后。隐藏参数（同上）。 |
+| `--exclude-dynamic-system-prompt-sections` | 把 per-machine 段（cwd、env 信息、memory 路径、git status）从 system prompt 挪到首条 user 消息，提升跨用户的 prompt-cache 复用。**仅对默认 prompt 生效**，配 `--system-prompt` 时忽略。默认 `false`。 |
+
+> 注：`--system-prompt-file` / `--append-system-prompt-file` 为隐藏参数，`--help` 主列表未单独列出（仅在 `--bare` 描述中以 `--system-prompt[-file]` 形式带过），但已实测有效（commander 报 `argument missing` 而非 `unknown option`），用于较长 / 可复用的 prompt 内容。
+
+```bash
+claude --append-system-prompt "始终用中文回答"
+claude --system-prompt-file ./my-system.txt
+```
+
+---
+
+## 三、工具与权限
+
+| 参数 | 说明 |
+|------|------|
+| `--tools <tools...>` | 指定可用的内置工具集。`""` 禁用全部，`default` 启用全部，或指定名称如 `"Bash,Edit,Read"`。 |
+| `--allowedTools, --allowed-tools <tools...>` | 允许的工具名列表（逗号或空格分隔），例：`"Bash(git *)" Edit`。 |
+| `--disallowedTools, --disallowed-tools <tools...>` | 拒绝的工具名列表，格式同上。 |
+| `--permission-mode <mode>` | 本次会话的权限模式：`acceptEdits` / `auto` / `bypassPermissions` / `default` / `dontAsk` / `plan`。 |
+| `--dangerously-skip-permissions` | 绕过**所有**权限检查。仅建议在无网络的沙箱中使用。 |
+| `--allow-dangerously-skip-permissions` | 把「绕过所有权限检查」作为一个**可选项**开启（默认不启用）。仅建议无网络沙箱。 |
+
+---
+
+## 四、目录、会话与恢复
+
+| 参数 | 说明 |
+|------|------|
+| `--add-dir <directories...>` | 额外允许工具访问的目录。 |
+| `-c, --continue` | 继续当前目录下**最近一次**对话。 |
+| `-r, --resume [value]` | 按 session ID 恢复对话；不带值则打开交互选择器（可附搜索词）。 |
+| `--fork-session` | 恢复时新建 session ID 而非复用原 ID（配合 `--resume` / `--continue`）。 |
+| `--from-pr [value]` | 恢复与某 PR 关联的会话（PR 号 / URL），或打开交互选择器（可附搜索词）。 |
+| `--session-id <uuid>` | 指定本次对话的 session ID（须为合法 UUID）。 |
+| `--no-session-persistence` | 关闭会话持久化：不写盘、不可恢复。**仅 `--print`**。 |
+| `-n, --name <name>` | 设置本会话显示名（显示在提示框、`/resume` 选择器、终端标题）。 |
+
+---
+
+## 五、非交互 / 打印模式（`--print` 相关）
+
+| 参数 | 说明 |
+|------|------|
+| `-p, --print` | 打印响应后退出（便于管道）。非交互模式会跳过工作区信任弹窗；校验失败的 settings 文件会被静默忽略。务必只在可信目录用。 |
+| `--output-format <format>` | 输出格式（**仅 `--print`**）：`text`（默认）/ `json`（单条结果）/ `stream-json`（实时流）。 |
+| `--input-format <format>` | 输入格式（**仅 `--print`**）：`text`（默认）/ `stream-json`（实时流式输入）。 |
+| `--include-partial-messages` | 输出中包含到达的部分消息块。**仅 `--print` 且 `--output-format=stream-json`**。 |
+| `--include-hook-events` | 输出流中包含所有 hook 生命周期事件。**仅 `--output-format=stream-json`**。 |
+| `--replay-user-messages` | 把 stdin 的 user 消息回显到 stdout 用于确认。**仅 `--input-format=stream-json` 且 `--output-format=stream-json`**。 |
+| `--json-schema <schema>` | 用于结构化输出校验的 JSON Schema。例：`{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}`。 |
+| `--max-budget-usd <amount>` | API 调用花费的美元上限。**仅 `--print`**。 |
+| `--prompt-suggestions [value]` | 启用提示建议；print/SDK 模式下每回合后发一条 `prompt_suggestion` 预测下一条用户提示。取值：`true/false/1/0/yes/no/on/off`，preset 为 `true`。 |
+
+---
+
+## 六、MCP、插件与配置来源
+
+| 参数 | 说明 |
+|------|------|
+| `--mcp-config <configs...>` | 从 JSON 文件或字符串加载 MCP 服务器（空格分隔多个）。 |
+| `--strict-mcp-config` | 只用 `--mcp-config` 提供的 MCP 服务器，忽略其它所有 MCP 配置。 |
+| `--plugin-dir <path>` | 仅本次会话从目录或 `.zip` 加载插件（可重复：`--plugin-dir A --plugin-dir B.zip`）。默认 `[]`。 |
+| `--plugin-url <url>` | 仅本次会话从 URL 拉取插件 `.zip`（可重复）。默认 `[]`。 |
+| `--settings <file-or-json>` | 加载额外设置：可传 settings JSON 文件路径或 JSON 字符串。 |
+| `--setting-sources <sources>` | 逗号分隔的设置来源：`user` / `project` / `local`。 |
+| `--betas <betas...>` | API 请求中附带的 beta header（仅 API key 用户）。 |
+
+---
+
+## 七、调试与诊断
+
+| 参数 | 说明 |
+|------|------|
+| `-d, --debug [filter]` | 开启 debug，可按类别过滤，例：`"api,hooks"` 或 `"!1p,!file"`。 |
+| `--debug-file <path>` | 把 debug 日志写到指定文件路径（隐式开启 debug）。 |
+| `--verbose` | 覆盖 config 里的 verbose 设置。 |
+| `-v, --version` | 输出版本号。 |
+| `-h, --help` | 显示帮助。 |
+
+---
+
+## 八、特殊启动模式
+
+| 参数 | 说明 |
+|------|------|
+| `--bare` | 极简模式：跳过 hooks、LSP、插件同步、署名、auto-memory、后台预取、keychain 读取、CLAUDE.md 自动发现。设置 `CLAUDE_CODE_SIMPLE=1`。Anthropic 鉴权严格限定为 `ANTHROPIC_API_KEY` 或经 `--settings` 的 apiKeyHelper（不读 OAuth / keychain）；第三方供应商（Bedrock/Vertex/Foundry）用各自凭据。Skills 仍可经 `/skill-name` 解析。需显式提供上下文：`--system-prompt[-file]`、`--append-system-prompt[-file]`、`--add-dir`、`--mcp-config`、`--settings`、`--agents`、`--plugin-dir`。 |
+| `--safe-mode` | 关闭所有自定义（CLAUDE.md、skills、插件、hooks、MCP、自定义命令与 agent、output styles、workflows、自定义主题、键位等），用于排查损坏的配置。Admin（policy）设置仍生效；鉴权、模型选择、内置工具、权限正常工作。设置 `CLAUDE_CODE_SAFE_MODE=1`。 |
+| `--bg, --background` | 以后台 agent 启动会话并立即返回（用 `claude agents` 管理）。 |
+| `--remote-control [name]` | 启动启用了 Remote Control 的交互会话（可命名）。 |
+| `--remote-control-session-name-prefix <prefix>` | 自动生成的 Remote Control 会话名前缀（默认主机名）。 |
+| `--disable-slash-commands` | 禁用所有 skills。 |
+
+---
+
+## 九、集成与环境
+
+| 参数 | 说明 |
+|------|------|
+| `--ide` | 启动时若恰好有一个可用 IDE，则自动连接。 |
+| `--chrome` | 启用 Claude in Chrome 集成。 |
+| `--no-chrome` | 禁用 Claude in Chrome 集成。 |
+| `--brief` | 启用 `SendUserMessage` 工具，用于 agent→user 通信。 |
+| `--ax-screen-reader` | 渲染对屏幕阅读器友好的输出（纯文本、无装饰边框 / 动画）。 |
+| `--file <specs...>` | 启动时下载的文件资源。格式 `file_id:relative_path`，例：`--file file_abc:doc.txt file_def:img.png`。 |
+
+---
+
+## 十、Git Worktree / tmux
+
+| 参数 | 说明 |
+|------|------|
+| `-w, --worktree [name]` | 为本会话新建一个 git worktree（可指定名称）。 |
+| `--tmux` | 为 worktree 创建 tmux 会话（需配合 `--worktree`）。有 iTerm2 时用其原生分屏；`--tmux=classic` 用传统 tmux。 |
+
+---
+
+## 子命令（Commands）
+
+| 命令 | 说明 |
+|------|------|
+| `agents [options]` | 管理后台 agent。 |
+| `auth` | 管理鉴权。 |
+| `auto-mode` | 查看 auto 模式分类器配置。 |
+| `doctor` | 检查 Claude Code 自动更新器的健康状况（会跳过信任弹窗并启动 `.mcp.json` 的 stdio 服务做健康检查，只在可信目录用）。 |
+| `gateway [options]` | 运行企业版鉴权 / 遥测网关。 |
+| `install [options] [target]` | 安装 Claude Code 原生构建。`[target]` 指定版本（`stable` / `latest` / 具体版本号）。 |
+| `mcp` | 配置与管理 MCP 服务器。 |
+| `plugin` \| `plugins` | 管理 Claude Code 插件。 |
+| `project` | 管理 Claude Code 项目状态。 |
+| `setup-token` | 设置长期有效的鉴权 token（需 Claude 订阅）。 |
+| `ultrareview [options] [target]` | 云端多 agent 代码评审当前分支（或 PR 号 / 基准分支）并打印结果。 |
+| `update` \| `upgrade` | 检查更新并安装。 |
+
+---
+
+## 附录 A：`--agent` / `--agents` 详解
+
+这两个参数都围绕 **subagent（子代理）**，但作用层级不同：
+
+- **`--agents <json>`**：在命令行**临时定义**一批 agent（仅本次会话有效），不落盘。
+- **`--agent <name>`**：让**主会话本身以某个 agent 身份运行**（整段替换默认 system prompt），相当于把整个 Claude Code 变成那个定制 agent。
+
+### A.1 `--agents <json>` —— 内联定义 agent
+
+JSON 结构：**顶层 key = agent 名称**，value = 该 agent 的配置对象。`prompt` 字段对应文件版的 markdown 正文（即 system prompt）。
+
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer. Use proactively after code changes.",
+    "prompt": "You are a senior code reviewer. Focus on quality, security, best practices.",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  },
+  "debugger": {
+    "description": "Debugging specialist for errors and test failures.",
+    "prompt": "You are an expert debugger. Find root causes and provide fixes."
+  }
+}'
+```
+
+**支持字段**（与文件版 frontmatter 一致，外加 `prompt`）：
+
+| 字段 | 必填 | 类型 | 作用 |
+|------|------|------|------|
+| `description` | ✓ | string | 何时该委派给此 agent，Claude 据此决定自动委派 |
+| `prompt` | — | string | system prompt / 指令（`--agents` JSON 专用；文件版放在 markdown 正文） |
+| `tools` | — | string[] | 可用工具，省略则继承全部。如 `["Read","Grep","Bash"]`、MCP 形如 `["mcp__github"]` |
+| `disallowedTools` | — | string[] | 从继承列表中**剔除**的工具，如 `["Write","Edit"]`、`["mcp__*"]` |
+| `model` | — | string | `sonnet`/`opus`/`haiku`/`fable` 别名、完整 ID（`claude-opus-4-8`）或 `inherit`（默认） |
+| `permissionMode` | — | string | `default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan` |
+| `maxTurns` | — | number | agent 停止前的最大回合数 |
+| `skills` | — | string[] | 启动时预加载进上下文的 skill 全文 |
+| `mcpServers` | — | (string\|object)[] | 该 agent 可用的 MCP server（引用名或内联定义） |
+| `hooks` | — | object | 生命周期 hook（`PreToolUse`/`PostToolUse`/`Stop`），格式同 settings.json |
+| `memory` | — | string | 持久记忆作用域：`user`/`project`/`local`，支持跨会话学习 |
+| `background` | — | boolean | `true` 则始终作为后台任务运行（默认 `false`） |
+| `effort` | — | string | `low`/`medium`/`high`/`xhigh`/`max`，覆盖会话推理强度 |
+| `isolation` | — | string | 设为 `worktree` 则在临时 git worktree（仓库隔离副本）中运行 |
+| `color` | — | string | 显示颜色：`red`/`blue`/`green`/`yellow`/`purple`/`orange`/`pink`/`cyan` |
+| `initialPrompt` | — | string | 当此 agent 作为主会话运行（`--agent` 或 `agent` 设置）时自动提交的首回合 |
+
+> `name` 在 `--agents` 里不用单独写——JSON 的 key 就是 name。
+
+### A.2 `--agent <name>` —— 让主会话作为某 agent 运行
+
+```bash
+claude --agent code-reviewer
+```
+
+- 整个会话接管该 agent 的：**system prompt（完全替换默认 Claude Code 提示词）**、工具限制、模型、以及 hooks/memory/permissionMode 等配置。
+- 启动头部会显示 `@<name>` 表示已生效；恢复会话时保持。
+- 也可写进 settings.json 持久化：`{"agent": "code-reviewer"}`（`--agent` 即覆盖此设置）。
+- 插件提供的 agent 用带作用域的名字：`claude --agent my-plugin:security-reviewer`。
+
+### A.3 agent 名称解析优先级（高 → 低）
+
+1. **Managed settings**（组织管理员下发）
+2. **`--agents` CLI 参数**（仅本次会话）
+3. **`.claude/agents/`**（项目级，随仓库共享）
+4. **`~/.claude/agents/`**（用户级，所有项目）
+5. **插件 agent**（最低）
+
+同名时取优先级最高的来源。
+
+### A.4 文件版定义（`.claude/agents/*.md`）
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, security, and maintainability
+tools: Read, Grep, Glob, Bash      # 文件版用逗号分隔；--agents JSON 用数组
+model: sonnet
+permissionMode: default
+color: blue
+---
+
+You are a senior code reviewer. Review for:
+1. Correctness: logic errors, edge cases, null handling
+2. Security: injection, auth bypass, data exposure
+3. Maintainability: naming, complexity, duplication
+每条结论必须给出具体修复方案。
+```
+
+- **frontmatter（YAML）**：配置元数据；**markdown 正文**：该 agent 的 system prompt。
+- 字段与 `--agents` JSON 完全一致，区别仅在 `prompt`（JSON 字段）↔ markdown 正文。
+
+### A.5 会话中如何调用 subagent（针对非主会话的子代理）
+
+- **自然语言委派**：`用 code-reviewer 检查我的改动`，Claude 读 `description` 自动委派。
+- **@ 提及强制指定**：`@agent-code-reviewer review the auth module`；插件 `@agent-my-plugin:code-reviewer`。
+- **整会话运行**：`--agent <name>` 或 settings.json `{"agent":"..."}`（即 A.2）。
+- 子代理经 **Agent 工具**（旧称 Task）启动，只看到自己的 prompt，看不到完整的 Claude Code 默认 system prompt。
+
+### A.6 两者关系小结
+
+| | `--agents` | `--agent` |
+|--|-----------|-----------|
+| 作用 | **定义** agent（提供候选） | **选用** agent 作为主会话身份 |
+| 落盘 | 否（仅本次会话） | 自身不落盘；可被 settings.json `agent` 持久化 |
+| 典型搭配 | `claude --agents '{...}' --agent reviewer`（内联定义 + 立刻以它运行） | 单独用时引用文件/插件里已存在的 agent |
+
+---
+
+## 常用组合示例
+
+```bash
+# 指定模型 + 高推理强度
+claude --model opus --effort high
+
+# 非交互、JSON 输出、限定预算，跑脚本
+claude -p "审查改动" --output-format json --max-budget-usd 0.5
+
+# 自定义 system prompt + 仅允许部分工具
+claude --system-prompt-file ./sys.txt --tools "Read,Bash"
+
+# 计划模式 + 追加规则
+claude --permission-mode plan --append-system-prompt "先出方案再动手"
+
+# 内联定义一个 agent 并立刻以它身份运行整会话
+claude --agents '{"reviewer":{"description":"code reviewer","prompt":"You are a senior code reviewer.","tools":["Read","Grep","Bash"]}}' --agent reviewer
+
+# 在 worktree 里开一个会话
+claude --worktree feature-x
+
+# 极简 / 排障
+claude --bare        # 跳过大部分自动行为
+claude --safe-mode   # 关闭所有自定义，排查配置问题
+
+# 恢复最近会话 / 按选择器恢复
+claude -c
+claude -r
+```
+
+---
+
+> 备注：以上为 2.1.195 版本快照，不同版本参数可能增删。随时用 `claude --help` 查看本机实际支持的参数，用 `claude <command> --help`（如 `claude mcp --help`）查看子命令详情。

package/server/system-prompt-templates/reference/prompt-control-tokens-deepseek-v4.md

@@ -0,0 +1,178 @@
+# DeepSeek 的控制标记（Control Tokens）：原理 + 速查（V4 版）
+
+> 从模型（DeepSeek）自身视角，解释其 Control Tokens 机制——与 Claude 的 XML 风格标签有本质不同——并按功能分类列出所有标记。与 `prompt-xml-tags-opus-4-8.md` / `prompt-xml-tags-fable-5.md` / `prompt-control-tokens-qwen3.md` 构成同一组对照文档。
+>
+> 可信度说明：本版所有字面量与组装逻辑均校订自 DeepSeek-V4-Pro 官方仓库的编码模块 [`encoding/encoding_dsv4.py`](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/encoding/encoding_dsv4.py)。早先由模型自述生成的版本中，角色标记（`你`/`我`）、定界符（`结束`）、推理标记（`反思`）、工具格式（`进行…格式…`）等均为幻觉，已全部以源码为准重写。
+
+## 结论先行
+
+DeepSeek 的 Control Tokens 与 Claude 的 XML 标签有**根本性的区别**：Claude 的 `<instructions>` 等标签是纯文本层面的「软约定」，依靠训练形成的注意力偏好生效，标签名可以自造；而 DeepSeek 的对话结构由**Tokenizer 级专用 Token**（如 `<｜User｜>`）和**官方编码模块硬拼装的模板**决定，字面量固定、不可替换，用户也不应手写。
+
+V4 的体系分三层：
+
+1. **Tokenizer 特殊 Token** —— 序列边界（BOS/EOS）、角色标记、任务标记，全角竖线 `｜` 风格；
+2. **推理标记** —— `<think>` / `</think>`，thinking 模式与 chat 模式靠它切换；
+3. **DSML 工具协议** —— `｜DSML｜` 锚定的 XML 变体，承载结构化工具调用。
+
+> 简单说：Claude 用的是「暗示」，DeepSeek 用的是「指令」。
+
+***
+
+# 一、原理：它为什么不一样
+
+## 1. 本质差异：文本协议 vs. 专用 Token + 硬模板
+
+| 特性   | Claude XML Tags     | DeepSeek Control Tokens     |
+| ---- | ------------------- | --------------------------- |
+| 机制   | 纯文本「软约定」            | Tokenizer 特殊 Token + 编码模块拼装 |
+| 实现方式 | 训练中形成的注意力偏好         | 固定字面量，编码/解码两端都做断言校验         |
+| 可替换性 | 可换成 `【指令】...【指令结束】` | 不可替换，解析器按精确字面量切分            |
+| 灵活性  | 高，用户可自造标签名          | 低，角色标记和协议格式完全固定             |
+| 谁来写  | 用户在 prompt 里手写      | 编码模块自动注入，用户手写反而出错           |
+
+特殊 Token 使用\*\*全角竖线 `｜`（U+FF5C）和下划块 `▁`（U+2581）\*\*拼写，如 `<｜begin▁of▁sentence｜>`。这种拼法刻意避开普通文本会出现的半角 `|` 和空格，保证用户内容永远不会「碰巧」拼出一个特殊 Token——解码器还会反向断言：模型输出的正文里不允许泄漏任何特殊 Token。
+
+## 2. 没有 Jinja 模板：V4 用 Python 编码模块组装
+
+V3 时代对话格式由 tokenizer\_config 里的 Jinja2 chat template 渲染；V4 改为随模型发布一个独立的 Python 编码模块（`encoding_dsv4.py`），核心入口是 `encode_messages()`。它接收 OpenAI 风格的 messages 数组，按角色逐条渲染：
+
+```
+<｜begin▁of▁sentence｜>{system 内容}{## Tools 区段（可选）}
+<｜User｜>{用户内容}
+<｜Assistant｜>{推理}</think>{正文}{工具调用块}<｜end▁of▁sentence｜>
+<｜User｜>{用户内容}
+<｜Assistant｜><think>          ← add_generation_prompt 在此触发生成
+```
+
+注意两点与直觉不同：
+
+* **没有 system 角色标记**。system 消息就是裸文本放在序列最前面（BOS 之后），不带任何包裹标记；工具定义（`## Tools` 区段）和强制输出 schema（`## Response Format:` 区段）也是作为纯文本追加在 system 内容后面的。
+* **消息边界不对称**。assistant 消息以 EOS（`<｜end▁of▁sentence｜>`）显式收尾；user 消息没有结束符，下一个角色标记本身就是边界。
+
+## 3. 三层机制各管一段
+
+* **角色边界**靠特殊 Token：模型从 token 层面就能区分「谁在说话」，不存在用户冒充 assistant 的文本歧义；
+* **推理/回答边界**靠 `<think>`/`</think>`：thinking 与 chat 是同一个模型的两种解码起点（见第三类详解）；
+* **工具调用结构**靠 DSML：一种以 `｜DSML｜` 特殊标记为锚点的 XML 变体——形似 XML，但起始锚点是普通文本拼不出来的，解析器可以放心用精确匹配切分,不会和正文里恰好出现的 XML 混淆。
+
+***
+
+# 二、速查：DeepSeek V4 Control Tokens 分类
+
+## 第一类：序列级 Token
+
+| Token                   | 说明                              |
+| ----------------------- | ------------------------------- |
+| `<｜begin▁of▁sentence｜>` | BOS，整个 prompt 的开头（无前置上下文时注入）    |
+| `<｜end▁of▁sentence｜>`   | EOS，每条 assistant 消息的结尾；也是生成停止信号 |
+
+> `encoding_dsv4.py` 中只定义字面量，不含数字 Token ID——ID 由 tokenizer 词表决定，文档不应妄称具体数值。
+
+## 第二类：角色标记（Role Markers）
+
+| Token                 | 含义                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------- |
+| `<｜User｜>`            | 用户消息开头                                                                                              |
+| `<｜Assistant｜>`       | 助手消息开头；也是 generation prompt 的触发标记                                                                   |
+| `<｜latest_reminder｜>` | 「最新提醒」消息开头——位于对话末尾、向模型注入临场约束的专用通道（类似 Claude harness 的 `<system-reminder>`，但 DeepSeek 把它做成了专用 Token） |
+
+几个角色的特殊处理规则：
+
+* **developer 角色**：渲染为 user 消息（前缀 `<｜User｜>`），可附带工具定义和 response format 区段；开启 drop\_thinking 时,较早的 developer 消息会被整条丢弃。
+* **tool 角色**：**不支持直接渲染**，编码模块会抛 `NotImplementedError`。工具结果必须先经 `merge_tool_messages()` 折叠进相邻的 user 消息，以 `<tool_result>` 内容块的形式出现（见第五类）。
+* **system 角色**：无专用 Token，裸文本置顶。
+
+## 第三类：推理标记（Thinking Tokens）
+
+| Token      | 说明              |
+| ---------- | --------------- |
+| `<think>`  | 推理开始            |
+| `</think>` | 推理结束，其后是面向用户的正文 |
+
+**thinking 模式与 chat 模式的切换机制**是 V4 编码里最精巧的一处——两种模式的区别仅在 generation prompt 的最后一个标记：
+
+```
+thinking 模式：...<｜User｜>问题<｜Assistant｜><think>     ← 模型从推理写起
+chat 模式：  ...<｜User｜>问题<｜Assistant｜></think>    ← think 块被「预闭合」，模型直接写正文
+```
+
+chat 模式不是「关掉」推理，而是替模型把 think 块**预先闭合**——同一个模型、同一套权重，靠解码起点的一个标记决定走不走长推理链。
+
+配套规则：
+
+* **drop\_thinking**：多轮对话回灌历史时，最后一个 user 消息之前的 assistant 推理内容默认被剥离（只保留 `</think>` 之后的正文），节省上下文；但只要任何消息定义了 tools，剥离就整体禁用——工具调用场景下推理链是行为依据，不能丢。
+* **reasoning\_effort \= "max"**：thinking 模式下若指定最高推理力度，编码模块会在序列最前面（index 0）注入一段固定文本，开头为 `"Reasoning Effort: Absolute maximum with no shortcuts permitted."`——注意这是**纯文本注入**，不是特殊 Token，属于「软硬结合」里软的那一半。
+* **解码端**：`parse_message_from_completion_text` 在 thinking 模式下以 `</think>` 切分 `reasoning_content` 与 `content`，并断言该标记必须存在。
+
+## 第四类：DSML 工具调用协议（Tool Call Protocol）
+
+DSML 以特殊标记 `｜DSML｜` 为锚点构造 XML 风格标签。assistant 发起工具调用的完整格式：
+
+```
+{正文（可为空）}
+
+<｜DSML｜tool_calls>
+<｜DSML｜invoke name="get_weather">
+<｜DSML｜parameter name="city" string="true">北京</｜DSML｜parameter>
+<｜DSML｜parameter name="days" string="false">3</｜DSML｜parameter>
+</｜DSML｜invoke>
+</｜DSML｜tool_calls><｜end▁of▁sentence｜>
+```
+
+要点：
+
+* **块边界**：整个工具调用块由 `\n\n<｜DSML｜tool_calls>` 起始——解码器正是用这个序列探测「正文结束、工具调用开始」；
+* **多工具**：一个 `tool_calls` 块内可并列多个 `invoke`；
+* **参数类型标注**：字符串参数原样内联并标 `string="true"`；其他类型（数字、布尔、对象、数组）JSON 序列化后标 `string="false"`，解码时据此重建 JSON；
+* **校验严格**：解析器逐个 invoke 提取函数名和参数对，拒绝重复参数和畸形定界符，并要求块结束后紧跟 EOS、不允许尾随内容；
+* 工具的**定义**（schema 列表）不走特殊 Token，而是以纯文本 `## Tools` 区段附在 system 消息后，schema 列在 `### Available Tool Schemas` 下。
+
+## 第五类：工具结果与任务标记
+
+**工具结果**没有专用 Token，用普通文本标签包裹、折叠进 user 消息：
+
+```
+<｜User｜><tool_result>{工具返回内容}</tool_result>
+
+{用户后续追问（如有）}
+```
+
+多个内容块（文本块、tool\_result 块）之间以空行连接；`encode_messages` 还会把 tool\_result 块按上一条 assistant 消息中 tool\_call 的顺序重排对齐。
+
+**任务标记（`DS_TASK_SP_TOKENS`）**——一组内部任务专用 Token，用于触发分类/检索类内部任务，普通对话不会出现：
+
+| Token           | 任务                                      |
+| --------------- | --------------------------------------- |
+| `<｜action｜>`    | action（附加在 `<｜Assistant｜><think>` 之后触发） |
+| `<｜query｜>`     | query                                   |
+| `<｜authority｜>` | authority                               |
+| `<｜domain｜>`    | domain                                  |
+| `<｜title｜>`     | title                                   |
+| `<｜read_url｜>`  | read\_url                               |
+
+***
+
+# 三、对照：V3 / R1 → V4 的演进
+
+| 特性   | V3 / R1 时代                               | V4                                            |
+| ---- | ---------------------------------------- | --------------------------------------------- |
+| 组装方式 | tokenizer\_config 内 Jinja2 chat template | 独立 Python 编码模块 `encoding_dsv4.py`             |
+| 角色标记 | `<｜User｜>` / `<｜Assistant｜>`（相同）         | 相同，新增 `<｜latest_reminder｜>`                   |
+| 推理标记 | R1 用 `<think>` / `</think>`，V3 无         | 全系 `<think>` / `</think>`，thinking/chat 双模式统一 |
+| 工具调用 | `<｜tool▁calls▁begin｜>` 等一族专用 Token       | DSML 协议（`｜DSML｜` 锚点 + XML 风格标签）               |
+| 工具结果 | `<｜tool▁output▁begin｜>` 包裹               | 文本标签 `<tool_result>`，折叠进 user 消息              |
+| 推理力度 | 无                                        | `reasoning_effort="max"` 文本注入                 |
+
+方向很清楚：**角色边界继续下沉到 Token 层，工具协议反而上浮成「特殊标记锚定的文本协议」**（DSML）——后者与 Claude 工具调用的内部表示思路趋同：既要结构化可解析，又要保留文本层的可读性和扩展性（如 `name=` / `string=` 属性）。
+
+***
+
+# 四、实操经验 + 一句话总结
+
+1. **不要手写 Control Tokens。** 与 Claude 的 XML 标签不同，这些标记由编码模块自动注入；解码端会断言正文中不得出现任何特殊 Token，手写轻则被过滤，重则解析报错。通过 API 用 messages 数组传参即可。
+2. **chat 模式 \= 预闭合的 think 块。** 想理解 V4 为什么「同一个模型既能深推理又能秒回」，看 generation prompt 的最后一个标记就够了：`<think>` 是推理起点，`</think>` 是跳过推理直接作答。
+3. **没有 tool 角色。** 把 OpenAI 风格的 `role: "tool"` 消息直接喂给 V4 编码模块会报错——工具结果要并入 user 消息的 content\_blocks。自建网关/代理时这是最常见的踩坑点。
+4. **多轮回灌注意 drop\_thinking 规则。** 默认丢弃历史推理，但定义了 tools 就全保留——上下文预算要按后者估算。
+5. **DSML 的参数类型靠 `string=` 属性。** 给模型看的工具调用示例如果自己编格式（比如塞 ` ```json ` 代码块），与训练分布不符,反而劣化调用质量。
+
+**一句话总结：** DeepSeek 的 Control Tokens 是 Tokenizer 级别的「硬」信号，由官方编码模块织入对话结构——角色边界用专用 Token 钉死，推理模式靠 `<think>`/`</think>` 的解码起点切换，工具调用走 `｜DSML｜` 锚定的结构化协议；与 Claude 的 XML 软标签分属两种哲学，用户不应也不需手动编写它们。