The guide使用指南
Everything you need
to run Skein well.把 Skein 用顺手,
这一页就够。
One page, no fluff: what Skein is, how to install and connect it, the commands you'll actually type, the headless contract CI can rely on, and how to undo anything the agent did.
一页讲清，不掺水：Skein 是什么、如何安装与接入、日常真正会敲的命令、CI 可以依赖的无头契约，以及如何撤销智能体做过的任何事。
What is Skein什么是 Skein
A coding agent that lives in your terminal.住在终端里的编码智能体。
You describe a change in plain language. Skein finds the relevant code with its own local index, edits with your permission, runs your checks, and only reports success when those checks prove it.
你用自然语言描述改动，Skein 用自己的本地索引找到相关代码，经你允许后编辑，运行你的检查——只有检查证明之后才报告成功。
You ask你来描述
skein "fix the flaky webhook retry test" — plain language, or pin files with @path. Works interactively or as a one-shot command.
skein "fix the flaky webhook retry test"——纯自然语言，或用 @path 固定文件。既可交互，也可一条命令直达。
It works transparently过程全透明
Every file read, patch, and command shows up in a live timeline. Writes need your approval and get automatic pre-write checkpoints you can restore.
每次读文件、打补丁、执行命令都出现在实时时间线里。写入需要你的批准，并自动生成可恢复的写前检查点。
You get proof结果有证明
The run ends with a completion status backed by real test and typecheck results — never just the model's word. Sessions persist for later audit.
运行以完成状态收尾，背后是真实的测试与类型检查结果——绝不只是模型的一面之词。会话持久保存，随时回溯审计。
Step 1第 1 步
Install.安装。
Skein ships on npm for Node.js 22.16 or newer, on macOS and Linux.
Skein 通过 npm 发布，需要 Node.js 22.16 或更新版本，支持 macOS 与 Linux。
# Node.js 22.16 or newer
npm install -g @skein-code/cli
skein --version
man skein # the manual is generated from the CLI's own help output
# Or the guarded installer: checks Node first, pins exact versions.
curl -fsSL https://raw.githubusercontent.com/lixiang12345/skein/main/scripts/install.sh | shStep 2第 2 步
Connect a model.接入模型。
Every connection names its provider and protocol explicitly — Skein never probes, never guesses from a URL, and never retries across protocols at your expense.
每个连接都显式声明 provider 与协议——Skein 不探测、不从 URL 猜测，更不会跨协议重试让你多花钱。
| Connection连接 | Protocol协议 | Notes说明 |
|---|---|---|
| OpenAI | openai-responses · openai-chat | Responses is the recommended transport推荐使用 Responses 传输 |
| Anthropic | anthropic-messages | Bearer and x-api-key auth both supported同时支持 Bearer 与 x-api-key 认证 |
| Gemini | gemini | Native provider connection原生 provider 连接 |
| Compatible relay兼容中继 | openai-responses · openai-chat · anthropic-messages | Any base URL speaking one of the three protocols任何讲这三种协议之一的 base URL |
export TEAM_RELAY_API_KEY=… # Skein stores the NAME, never the value
skein agents setup --yes \
--name team-relay \
--provider compatible \
--protocol openai-responses \
--base-url https://relay.example/v1 \
--api-key-env TEAM_RELAY_API_KEY \
--model provider/coding-modelFirst run without a connection? skein opens guided setup. Local-only commands — index, search, context, status, doctor, config show — work without any model connection at all.第一次运行还没配连接？直接敲 skein 会进入引导式设置。纯本地命令——index、search、context、status、doctor、config show——完全不需要模型连接。
Step 3第 3 步
The commands you'll actually type.你真正会敲的命令。
Full reference: skein --help or man skein — both generated from the same command registry.
完整参考：skein --help 或 man skein——两者都从同一份命令注册表生成。
| You want to…你想…… | Type就敲 | Notes说明 |
|---|---|---|
| Open the workspace打开工作区 | skein | Composer-first TUI; first run guides relay setup以输入框为中心的 TUI;首次运行引导中继设置 |
| Make one change做一个改动 | skein "add retry logging" | Pin context with @src/file.ts用 @src/file.ts 固定上下文 |
| Ask without editing只问不改 | skein --ask "why is auth slow?" | Mutation tools are denied in ask modeask 模式下修改类工具一律被拒 |
| Script or CI run脚本或 CI 运行 | skein -p "…" --output-format json | Stable exit codes — table below稳定退出码——见下表 |
| Search your code搜索代码 | skein search "token budget" | Local index, offline, scored spans with line ranges本地索引、离线、带行号区间的评分片段 |
| Resume yesterday继续昨天的活 | skein --continue | Or skein session list + --resume <id>或 skein session list + --resume <id> |
| Undo an agent edit撤销智能体的修改 | skein checkpoint list → restore | Every mutation has a pre-write snapshot每次修改都有写前快照 |
| Check your setup体检环境 | skein doctor | Diagnoses terminal, index, connections, credentials诊断终端、索引、连接与凭据 |
| See connection state查看连接状态 | skein status | Reports the default connection's real credential state如实报告默认连接的凭据状态 |
| Report an issue反馈问题 | skein feedback | Prints the tracker URL with a content-free summary打印问题追踪地址与不含内容的环境摘要 |
Inside the interactive workspace交互工作区里
- @path attach a file as pinned context把文件作为固定上下文附加
- /command open the command palette打开命令面板
- !command run one shell command, permission-checked运行一条 shell 命令，经权限检查
- alt+enter queue a follow-up while the agent is busy智能体忙时排队一条后续指令
- esc stop the current run停止当前运行
- ctrl+r search your prompt history搜索提示历史
Automation自动化
Headless, with a contract CI can trust.无头运行，契约让 CI 敢信。
Print mode emits text, JSON, or streaming JSON following the published schema in docs/headless-output.schema.json. Pipelines gate on structured status and exit codes — never on parsed prose.
打印模式输出文本、JSON 或流式 JSON,遵循 docs/headless-output.schema.json 发布的 schema。流水线只依赖结构化状态与退出码——从不解析散文。
skein -p "summarize the failing tests" --output-format json
# → { "status": "verified", "exitCode": 0, "changedFiles": […], "usage": … }| Exit退出码 | Status状态 | Meaning含义 |
|---|---|---|
0 | verified / completed | Done, with current deterministic evidence完成，且有当前的确定性证据 |
1 | error | The run failed with an error运行出错失败 |
2 | needs_input | One persisted clarification question awaits an answer一条持久化的澄清问题等待回答 |
3 | unverified | Work finished but no current check proves it工作完成但没有当前检查能证明 |
4 | verification_failed | A required check ran and failed必需检查已运行且失败 |
5 | blocked | A required permission or gate stopped the run必需权限或门禁拦停了运行 |
6 | cancelled | The run was cancelled运行被取消 |
7 | max_turns | The configured turn limit was reached达到配置的轮次上限 |
8 | token_budget | The configured token budget was exhausted配置的 token 预算耗尽 |
9 | needs_review | Completion requires human review完成需要人工评审 |
Nothing is a one-way door没有单行道
Recover anything.任何东西都能恢复。
Durable sessions and automatic pre-write checkpoints mean an agent run is never something you just hope went well.
持久会话与自动写前检查点，意味着一次智能体运行绝不是「只能祈祷结果」的事。
skein session list # durable, resumable, forkable sessions
skein session fork <id> # branch a run without losing the original
skein checkpoint list # every mutation has a pre-write snapshot
skein checkpoint restore <s> <c> # put the files back, Git history untouched
/recover # in the TUI: retry, diff, audit, rollbackInvariants不变量
Rules the model can't vote on.模型没有投票权的规则。
Independent read, write, shell, Git, and network gates; workspace-root enforcement; and project config that stays untrusted until you pass --trust-project-config. On top of that, four invariants hold across every provider, mode, and flag — including --yes.
独立的读/写/Shell/Git/网络门禁、工作区根路径强制，以及在你传入 --trust-project-config 之前始终不受信的项目配置。在此之上，四条不变量对每个 provider、每种模式、每个 flag(包括 --yes)都成立。
Deterministic truth wins确定性事实优先
Passing receipts beat conflicting model judgment; failing checks cannot be overridden by any reviewer, however persuasive the prose.
通过的回执压过相左的模型判断；失败的检查任何评审者都无法推翻——文字再有说服力也不行。
Content-free telemetry遥测不含内容
Receipts and registries keep hashes, counts, and bounded aggregates — no prompts, no source text, no command arguments, no credentials.
回执与注册表只保留哈希、计数与有界聚合——没有提示词、源码、命令参数或凭据。
Live-human gates stay human真人门禁只认真人
Git push, publish, destructive commands, writer integration: no flag, config rule, or model review can stand in for a person saying yes.
Git push、发布、破坏性命令、写入集成：任何 flag、配置规则或模型评审都不能替一个人说「可以」。
Cloned code has no authority克隆的代码没有权限
Project-local hooks, endpoints, and verification commands activate only after you explicitly trust the workspace configuration.
项目本地的钩子、端点与验证命令，只有在你显式信任该工作区配置后才会激活。
FAQ常见问题
Fair questions.问得都在理。
What happens to my API keys?我的 API Key 会怎样？
Skein saves the environment-variable name, never the value. Diagnostics redact secrets, URLs, and query strings, and receipts are content-free by design.
Skein 只保存环境变量的名字,绝不保存值。诊断输出会遮蔽密钥、URL 与查询串，回执从设计上就不含内容。
Does my code leave my machine?我的代码会离开本机吗？
Indexing, retrieval, ranking, and search run locally and work offline. Only the context selected for a model turn goes to the relay you explicitly configured.
索引、检索、排序与搜索都在本地运行，可完全离线。只有为某次模型调用挑选的上下文，会发送到你显式配置的中继。
Can a cloned repository change Skein's behavior?克隆下来的仓库能改变 Skein 的行为吗？
Not by default. Project-local configuration is untrusted until you opt in with --trust-project-config — hooks, verification commands, and endpoint overrides stay inert in freshly cloned code.
默认不能。项目本地配置在你用 --trust-project-config 选择信任之前不受信——新克隆代码里的钩子、验证命令与端点覆盖全部处于惰性状态。
Which providers does it work with?支持哪些模型服务？
OpenAI Responses, OpenAI Chat, Anthropic Messages, and Gemini natively, plus compatible relay endpoints for the OpenAI and Anthropic protocols — each chosen explicitly per connection.
原生支持 OpenAI Responses、OpenAI Chat、Anthropic Messages 与 Gemini,并支持讲 OpenAI 或 Anthropic 协议的兼容中继端点——每个连接都显式选定。
Weave your next change织起下一次变更