主题
术语表
本站反复出现的术语，每条给一句话定义 + 一句"你什么时候会碰到它" + 指向讲透它的那一页。
这页的定位是查词，不是教程。所以每条都短，需要展开的一律指过去。 如果你在读某一页时被一个词卡住，回来查这条就够继续读下去。
术语的英文原词不翻译
provider、Hook、MCP、LSP、Skill、worktree、prompt cache 这些词全站保留英文—— 它们是你在配置文件和命令行里要实际敲的字符串，翻译成中文反而对不上。
快速上手
最常被问到的几个词，先看这张表：
| 术语 | 一句话 |
|---|---|
| harness | 模型之外的那整套工程：工具、循环、权限、上下文。首页说的「harness 你改」就是它 |
| agentic loop | 「模型输出 → 调工具 → 结果喂回 → 再输出」的循环，是它干活的基本形态 |
| 上下文窗口 | 一次请求能装多少 token，按模型算，32K 到 1M 不等 |
| 权限模式 | 八档预设，决定「哪些操作要问你、哪些直接干」 |
| 轨迹 | 每个会话落盘的完整执行记录，排查问题和算成本都靠它 |
| effort 档位 | 五档推理强度旋钮，越高越想得久、越贵 |
| prompt cache | 重复前缀的缓存复用，是成本上最大的那个杠杆 |
详细说明
按主题分组。同一主题内的词互相有依赖，顺着读比跳着读省劲。
核心概念
harness
定义：模型之外的那一整套工程——它有哪些工具、怎么循环（见下条 agentic loop）、 权限怎么管、上下文怎么组织、出错怎么重试。模型负责"想"，harness 负责"把想法变成 对你代码库的真实操作，并且不出事"。
你什么时候碰到它：同一个模型配不同的 harness，好用程度差很远——你觉得"这个 agent 笨"， 很多时候不是模型笨，是 harness 没把该给的上下文给到、或者该拦的没拦住。 sid-code 的 harness 整套开源可改，这是它和闭源产品结构上的区别： sid-code 是什么 那张差异表里「harness 是黑盒」指的就是这件事。
相关：扩展方式总览 · 博客（这一层主要在讲 harness 各部分怎么设计的）
agentic loop
定义：一轮完整的「你输入 → 模型流式输出 → 需要动手时调用工具 → 把工具结果喂回模型 → 继续下一轮」的循环。模型返回 end_turn 才结束，返回 tool_use 就继续转。
你什么时候碰到它：你在终端里看到的每一条「读了哪个文件、跑了什么命令、改了哪几行」， 都是这个循环的一步。它是 sid-code 与「代码补全」的根本区别——补全给你一段文本， agentic loop 自己去验证结果对不对。
相关：sid-code 是什么 · 跑通第一个任务
轮（turn）
定义：循环转一圈叫一轮。一次用户输入可能触发几十轮——每次调用工具、拿到结果、 再让模型继续，都是新的一轮。
你什么时候碰到它：/goal turns <n> 给持续执行设轮数上限； Esc Esc 的回退点是按轮登记的（每轮用户输入前存一个）。
工具（tool）
定义：模型能调用的具体动作，比如 read、edit、bash、grep。 共 44 个内置工具，加上 MCP 接进来的外部工具。
你什么时候碰到它：写权限规则、给子代理配工具清单、写 Hook 的 matcher， 三处填的都是工具名这个字符串。名字的确切拼写查内置工具。
provider
定义：LLM 服务提供方 + 它的协议族。sid-code 支持三族：anthropic、openai （含全部 OpenAI 兼容网关：DeepSeek、GLM、Grok、公司网关、Azure）、ollama（本地）。
你什么时候碰到它：配置的第一步就是选 provider。两族的 base_url 规则相反—— anthropic 族不带 /v1，openai 族要带，配错会 404 或者拿到一个 HTTP 200 的 HTML 错误页。 这是新手最常踩的坑。
无头模式（headless）
定义：不开 TUI，用 -p（--print）直接把 sid-code 当命令行工具调， 结果打到 stdout。可以 --output-format json 拿结构化结果。
你什么时候碰到它：写脚本、进 CI、被别的程序调用时。 注意无头模式下没法弹权限确认框，所以要显式放行工具，否则该问的操作会直接失败。
上下文与成本
上下文窗口
定义：一次 LLM 请求能容纳的 token 总量（系统提示词 + 全部历史消息 + 工具定义）。 按模型算，不是固定值——模型注册表里从 8K 到 1M 都有。
你什么时候碰到它：它决定什么时候触发压缩。同一句"用了 60%"在不同模型上是 完全不同的绝对量，所以看百分比别看 token 数。
相关：上下文与压缩
token
定义：模型计费和计长度的单位。大致上一个英文词 ≈ 1 个 token， 一个汉字 ≈ 1–2 个。所有费用都是按 token 数 × 单价算出来的。
你什么时候碰到它：/cost 里的输入/输出/缓存读取三个数都是 token 计数。 注意 输入 是全会话累加口径，会远大于上下文窗口，这不是 bug。
压缩（compact）
定义：上下文快满时，把早期对话交给模型总结成一段摘要，用摘要替换原始消息， 腾出空间继续干活。可以手动 /compact，也会在阈值处自动触发。
你什么时候碰到它：长任务里「它突然不记得前面说过的话」通常就是发生了压缩。 压缩是有损的——摘要保留结论、丢掉过程细节。重要约定别指望它记住。
相关：上下文与压缩
microcompact（微压缩）
定义：比压缩更轻的一档——不调 LLM，只清理旧的工具结果内容。 按工具类型区分：read/bash/grep 这类输出可以重新执行拿回来的直接清空； edit/write 这类有副作用、输出不可复现的保留一段摘要。
你什么时候碰到它：它是自动发生的，一般你不会注意到。 知道它存在的价值在于理解「为什么上下文降下去了但对话历史还完整」。
prompt cache
定义：把请求的稳定前缀缓存在服务端，下次同前缀的请求直接复用， 按远低于输入价的「缓存读取价」计费。
你什么时候碰到它：这是成本上最大的杠杆。核心机制是按前缀命中，前缀一变整段作废—— 所以「让稳定的东西待在前面」是所有省钱建议的共同原理。
两族协议的机制不同，正常命中率也不同：anthropic 族是客户端显式标记缓存边界， 正常 90%+；openai 族靠服务端隐式判断，60–70% 就是结构性上限。 别拿一个数字套两族。
相关：成本与用量 · Prompt Cache：两族协议的分叉 （这两个区间怎么测出来的、4.3 亿 token 的实测账本）
辅助调用（影子调用）
定义：不在主对话里、但真实花钱的 LLM 调用：生成会话标题、抽取记忆、 给 bash 命令做风险分类、生成压缩摘要等。
你什么时候碰到它：/cost 里的「其中辅助调用」那一行，只在 >0 时显示。 这部分容易被忽略，但它真的计费——把它算进去才能和网关账单对上。
相关：成本与用量
effort 档位
定义：统一的推理强度旋钮，五档 low / medium / high / xhigh / max， 外加 auto（不显式下发，跟随模型默认）。档位越高，模型思考得越久、越贵。
你什么时候碰到它：/effort 查看或切换，--effort <level> 启动时指定， effortLevel 字段作为启动初值。
关键点是这个标度与底层模型无关：你面对的永远是这五档，由能力层翻译成各 provider 的线格式。所以模型可能不支持你选的那一档——比如 DeepSeek 只认 high/max， o-series 没有 max。这种情况命令会接受你的选择并明确告诉你实际下发的是哪档， 不静默糊弄。
相关：斜杠命令（/effort） · settings.json 字段（effortLevel）
安全与权限
权限模式
定义：一组预设档位，决定「哪些操作要问你、哪些直接放行、哪些直接拒绝」。 共八档，从最保守的 default（除只读外逐个问）到最宽的 dangerously-skip-permissions。Shift+Tab 在会话里循环切换。
你什么时候碰到它：这是绝大多数人用完第一天就想改的东西——默认档每一步都问，很烦。 日常最顺手的是 acceptEdits（文件读写自动放行，bash 仍要问）。
相关：权限与人工确认
权限规则
定义：比模式更细的粒度，写成 工具名 或 工具名(模式)， 分 allow / deny / ask 三类。例：Bash(npm *)、Read(/src/**)、mcp__*。
你什么时候碰到它：想放行一批操作但不想整档放宽时。 最容易写错的是路径前缀：/src/** 是项目根相对，文件系统绝对路径要写两个斜杠 （//etc/**）。写混了不报错，只是静默不匹配。
相关：权限与人工确认
Plan Mode（计划模式）
定义：一个代码级强制只读的权限档。不是"请求模型别动手"，而是写操作在权限层 直接被拒。它先探索代码、出方案、等你批准，批准后才退出只读。
你什么时候碰到它：复杂改动想先看它打算怎么干的时候。 注意它不是提示词层面的约定——所以模型没法"忘记"自己在 plan 模式。
HITL（human-in-the-loop）
定义：人在回路——关键动作停下来等人确认，而不是全自动跑到底。 sid-code 里它的具体形态就是权限确认框、Plan Mode 的方案审批、ask_user_question 提问。
你什么时候碰到它：每次弹出 y/n/a 的确认框。危险操作会标红且默认聚焦在拒绝上—— 手快连按回车不会误批。
扩展机制
CLAUDE.md
定义：项目/用户级的约定文件，内容进系统提示词，每个会话自动带上。 七层合并（managed → user → userRulesDir → project → subdir → rulesDir → local）， 越靠后优先级越高。
你什么时候碰到它：想让它懂你这个项目的规矩时——这是性价比最高的扩展手段， 写一个文件就生效。反面是它每次请求都带，写一百行没人遵守的规则等于每次都为它付费。
记忆（memory）
定义：跨会话持久化的事实，存成一个个小文件 + 一份索引。 注入方式是「索引进上下文 + 需要时按需读」，所以记忆多了不会线性推高成本。 按 git 顶层目录分桶，多个 worktree 共享同一份。
你什么时候碰到它：save_memory 工具写入；也可以让它「记住这件事」。 和 CLAUDE.md 的分工：CLAUDE.md 是你手写的规矩，记忆是它自己攒的事实。
Skill
定义：打包成目录的一套专业能力（一个 SKILL.md 加可选脚本）， 按需被调用，不占常驻上下文。8 个内置 Skill，也可以自己写。
你什么时候碰到它：想把一套重复流程（代码评审清单、事故复盘步骤、发布流程） 固化下来时。它比 Hook 轻——Hook 是自动触发，Skill 是被调用。
相关：Skill
Hook
定义：在固定时机自动执行的外部命令。32 类事件（工具执行前后、 LLM 请求前后、压缩前后、会话起止、子代理起止…），部分事件可以阻断后续动作。
你什么时候碰到它：想做「提交前必须跑 lint」「拦掉某类危险命令」「编辑后自动格式化」 这类自动化时。注意配置文件里的事件名必须写 snake_case 且平铺，写 PascalCase 会被校验器拒。
相关：Hook 指南（怎么用） · Hook 事件（字段表）
MCP（Model Context Protocol）
定义：一个开放协议，让外部系统把自己的工具/资源暴露给 agent。 接进来的工具名形如 mcp__<server>__<tool>。
你什么时候碰到它：要接数据库、工单系统、内部 API 时。 权限规则里可以按 server 整体放行（mcp__myserver）或全部放行（mcp__*）。
相关：MCP
子代理（subagent）
定义：一个独立上下文的子任务执行者，跑完只把结论带回主会话。 6 个内置类型：explore / task / plan / summarize / verify / general-purpose。
你什么时候碰到它：两个价值——① 探索过程中读的一堆文件不进主上下文； ② 可以按类型配便宜模型，零配置下 explore/plan/summarize 已自动降到便宜档， task/verify 留主模型保质量。
相关：子代理
LSP（Language Server Protocol）
定义：编辑器与语言服务器之间的协议。接上之后 sid-code 能拿到编译器级的诊断 （类型错误、未定义符号）和跳转/引用查询，而不是靠读代码猜。
你什么时候碰到它：改类型密集的代码时差别最明显——诊断每轮注入， 改错了当轮就知道，不用等跑构建。
相关：代码智能（LSP）
worktree
定义：git 的原生特性——同一个仓库签出到多个目录，各自在不同分支上。 sid-code 用它做并行隔离：几个任务同时改代码而互不冲突。
你什么时候碰到它：并行跑多个改动时。有个坑要知道： sid-code 默认会 symlink node_modules（比 git 原生行为激进）， 跨分支 lockfile 不一致时会出错乱，所以它会检测并给你三行告警。
相关：Worktree 隔离
会话与运维
会话（session）
定义：一次从启动到退出的完整对话，有唯一 id，格式 YYYYMMDD-HHMMSS-<8位hex> （例 20260727-195536-2b2aa744）。时间前缀让目录的字典序天然等于时间序。
你什么时候碰到它：-c 续上次会话、--resume <id> 指定恢复、 --list-sessions 列出全部。报问题时贴这个 id 最省事——它能直接定位到轨迹。
相关：会话管理
轨迹（trajectory / trace）
定义：每个会话落盘的完整执行记录，在 ~/.sid-code/trajectories/sessions/<会话id>/ 下，主要是：
| 文件 | 内容 |
|---|---|
session.traj | 结构化的执行轨迹（每一步的思考、工具调用、结果） |
events.jsonl | 结构化事件流（会话起止、模型调用、重试、超时…），一行一个事件 |
raw.jsonl | 原始请求/响应记录，排协议问题用 |
你什么时候碰到它：排查「它当时为什么那么干」、算成本、做过程评估。 /trace（别名 /digest）可以把轨迹嚼碎成结构化摘要，比手读几百 KB 的 jsonl 现实得多。
回退点（rewind point）
定义：每轮用户输入前登记的一个还原点，记录当轮的文件快照 + 对话位置。 上限 30 个（超了丢最早的）。Esc Esc 打开选择器， 三档回退：仅代码 / 仅对话 / 两者。
你什么时候碰到它：「刚才那几轮走错方向了，退回去重来」的时候。 和 /undo 的区别：/undo 退一步文件修改，回退点可以直接跳回好几轮前。
相关：会话管理
checkpoint
定义：write/edit 执行前自动存的文件快照，比回退点更细——粒度是单次工具调用， 不是一轮对话。存在 ~/.sid-code/checkpoints/<会话id>/。
你什么时候碰到它：/checkpoints 看历史，/undo 撤销最近一次文件修改， /undo <文件> 只回滚一个文件。
相关：会话管理
fallback（降级）
定义：主模型重试耗尽后切到备用模型。三种策略：ask（问你，生产默认）/ auto（自动切）/ off（不降级，直接报错）。
你什么时候碰到它：主模型限流或网关抖动时。备用模型必须在 availableModels 里， 否则配置校验会拦下来。
相关：settings.json 字段（fallbackModel / fallbackSwitchMode）
循环检测（loop detection）
定义：检测模型是否在原地打转（反复调同一个工具、输出重复内容）并中断它。
你什么时候碰到它：正常情况下碰不到——它默认全局关闭。 原因是实测下来 shape 检测的误判率接近 100%（大文件分段读、多点编辑、 反复跑同一个 bash 命令都是正常行为，被它当成死循环杀掉），而 exact 检测几乎召回不到真死循环。 代码保留着，SID_ENABLE_LOOP_DETECTION=1 可以显式开。
相关：环境变量
team-defaults（团队默认配置）
定义：一份发给团队所有人的默认 settings 模板。语义是纯拷贝、且只在 settings.json 不存在时写入——绝不覆盖别人已有的配置。
你什么时候碰到它：在团队里推开 sid-code 时，让新同事装完即可用，不用手配 provider。
相关：团队默认配置分发
配额（quota）
定义：成本与速率的硬上限：costLimit（花费）、requestsPerMinute、 tokensPerMinute、budgetRules。撞到上限会终止而不是继续跑。
你什么时候碰到它：给团队人均成本设天花板时。 有个坑：quota.costLimit 会静默盖掉命令行的 --max-budget-usd。
常见问题
「轨迹」和「会话」有什么区别。 会话是这次对话本身（运行时概念），轨迹是这次对话落到磁盘上的记录（数据概念）。 一个会话对应一个轨迹目录，同名同 id。
「压缩」「microcompact」「/clear」怎么选。/clear 是清空重开（任务真做完了用它，最省）；/compact 是有损总结、保留结论； microcompact 是自动发生的轻量清理，你不用选。判断口诀：换任务用 /clear， 同一任务撑不住了用 /compact。
「回退点」和「checkpoint」到底哪个是哪个。 回退点按轮（每次你按回车前存一次），checkpoint 按工具调用（每次改文件前存一次）。 前者粗、能带对话一起退；后者细、只管文件。
「effort 档位」和「模型」哪个影响更大。 换模型的影响远大于调档位。档位是在同一个模型内部调"想多久"， 换模型是换能力上限。先选对模型，再调档位。
这里没有我要查的词。 本站的确切写法都在参考层：CLI 参数 / 斜杠命令 / 内置工具 / settings.json 字段 / 环境变量 / Hook 事件。这六页由脚本从源码生成， 不会跟实现漂移。词条缺失可以提出来补。
相关
- sid-code 是什么 —— 定位与和 Claude Code 的差异
- 接下来读什么 —— 按目标挑阅读路径
- 排障 —— 按症状索引的错误表