thing

@unravel-tech/thing

用于 thing 的命令行工具：从编码 Agent 推送、管理版本并分享各类产物（HTML 页面、Markdown 文档、独立图片和 PDF）。

npx -y @unravel-tech/thing push report.html

首次推送会打开浏览器以供授权，等待登录后继续操作，并输出永久 URL。Markdown、图片和 PDF 的操作方式也相同。如果经常使用，可全局安装：npm i -g @unravel-tech/thing。

命令

命令	功能说明
thing --version / thing version	显示已安装的 CLI 版本
thing update [--force] [--manager npm|bun]	全局安装最新版本；即使服务报告当前版本已是最新，--force 也会执行
thing login [--account name] [--server url] [--no-browser]	使用设备代码登录，添加或刷新一个命名账户；默认以已验证的电子邮件地址作为名称
thing accounts	列出已保存的账户，并显示此目录会解析到哪个账户
thing switch <account> [--local]	更改全局默认账户，或将账户绑定到当前 Git 仓库／工作目录
thing switch --clear-local	移除此目录继承的账户绑定
thing logout [--account name] [--all] / thing whoami	移除已保存的凭据／显示解析后的身份及推送目标
thing default [team] [--clear]	显示或设置服务端默认推送目标（未指定 --team 时，在任何机器上都会使用）
thing setup claude [--remove] [--dry-run]	让 Claude Code 自动模式无需拒绝即可将内容发布到 thing：在 ~/.claude/settings.json 的 autoMode 信任项中添加 usething.ai 和 thing push，并保留 Claude Code 的默认设置。请自行运行（在 Claude Code 中输入 ! npx -y @unravel-tech/thing@latest setup claude）；--remove 可撤销此设置
thing use <team> [project]	为此机器设置本地生效的团队／项目覆盖项
thing push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility v] [--password p]	如有需要则进行身份验证，然后推送新的不可变版本并打印其服务 URL。--visibility 可设为 private（仅你和你添加的人可见）、team（组织内所有人可见，默认值）或 public（任何拥有链接的人可见）。--password 允许知道密码的任何人访问此资源，团队和人员访问权限不受影响
thing list	列出你可查看的资源；使用 --label 或 --search 筛选，使用 --sort created 或 updated 排序，并通过 --order asc 或 desc 指定顺序，使用 --limit 和 --offset 分页
thing get <name> [--version n] [--output file]	读取已推送版本的源文件。HTML 和 Markdown 会打印到 stdout；PDF 和图像会保存到其下载名称对应的文件（不会覆盖现有文件），或保存到 --output 指定的位置
thing export --all [--output file] / thing export --team <slug>	将账户持有的所有内容（账户、每个资源的所有版本、评论和 Inputs 答案）下载为一个 zip；也可由团队管理员下载整个团队的内容。资源在最近一次推送 30 天后过期，请保留副本。绝不会覆盖文件
thing comments <name>	获取可查看资源中的评论和回复
thing versions <name>	查看资源的版本历史；查看者和公开链接均可使用
thing responses <name> [--mine] [--collection c] [--history] [--csv]	读取页面的 Inputs 答案（发布者和编辑者可查看所有答复者的答案）。每行都会注明答案来自浏览器还是 Agent
thing respond <name> <collection> (--data '{json}' | --field key=value ...) [--version n]	以已登录用户的身份回答页面的 Inputs。--field 可重复使用，支持 true、false、null 和数字类型。记录为 via: agent
thing rollback <name> <n>	将 latest 指回版本 n
thing open <name>	在浏览器中打开此资源
thing mcp	通过 stdio 运行 Model Context Protocol 服务（工具：server_info、push_artifact、list_artifacts、get_artifact、list_artifact_versions、list_artifact_comments、list_artifact_responses、submit_artifact_response、whoami）

<name> 可以是资源名称、team/slug 或粘贴的链接。/v/N 链接会固定到该版本，?k= 链接密钥会保留。读取其他主机上的链接时不会使用你的令牌，除非你自己的服务确认它指向同一资源。 push 会将任何服务端 notes（例如 Inputs 填写错误）输出到 stderr，并将其包含在 --json 中。 每条命令都接受 --json，以输出机器可读的内容。需要身份验证的命令也接受 --account name，可单次使用已保存的账户，而不更改全局默认账户或目录绑定。 未通过身份验证时，push --json 会输出以换行符分隔的身份验证状态；最后一个 JSON 对象始终是推送结果。使用 --no-login 可立即失败，而不是启动交互式身份验证，例如在 CI 中使用。

可见性值：private、team、anyone-with-link（会输出带令牌的分享 URL）、public。

更新

Thing 支持由 Thing 服务发布的提示性更新和强制更新。提示性更新会向 stderr 输出频率受限的通知，但命令会继续执行。强制更新会阻止普通命令并返回退出码 3，但仍可使用 --help、--version 和 update。--json 会返回结构化的 CLIENT_UPDATE_REQUIRED 错误。

CLI 每小时最多检查一次，并且每天最多显示一次相同的提示性更新。设置 THING_NO_UPDATE_NOTICES=1 可隐藏提示性通知；强制更新无法屏蔽。即使当前版本仍受支持，thing update --force 也会重新安装最新版本。

MCP 会话会通过初始化握手和 server_info 工具公开已安装的版本。提示性更新会显示在 MCP 指令、日志通知和第一个业务工具的结果中。强制更新会保留 server_info 可用，但会阻止使用制品工具，直到 Thing 更新并重启 MCP 客户端。

相应的 Thing 服务端点和强制执行中间件在 THING_SERVER_UPDATE_POLICY.md 中指定。

上下文解析

账户

Thing 可以在一台设备上保存多个登录账户。添加账户时为其设置简短名称，列出账户并切换全局默认账户：

thing login --account work
thing login --account personal
thing accounts
thing switch work

要将当前代码库关联到一个账户，请运行：

thing switch work --local

在 Git 仓库中，此操作会绑定仓库根目录及其下的所有目录。在 Git 仓库之外，此操作会绑定当前工作目录及其子目录。绑定信息存储在用户配置中，而非 .thing.json 中，因此个人账户名称和凭据不会成为代码库的更改。本地绑定优先于全局默认账户；单次命令中，--account personal 的优先级高于两者。使用 thing switch --clear-local 可移除绑定。

现有的单登录配置文件会自动迁移到名为 default 的账户。未指定 --account 的新登录会使用经过身份验证的电子邮件地址作为账户名称。

账户选择按以下顺序解析：--account → 最近的仓库／目录绑定 → 全局 thing switch 选择 → 唯一保存的账户。THING_TOKEN 和 THING_SERVER 仍会覆盖存储的凭据，供 CI 和 MCP 配置使用。

工作区和项目

工作区（在 API 和 --team 标志中称为团队）用于存放团队的制品。项目将工作区内的制品归类，并可限制只有添加到项目中的人员才能访问；也可以将工作区外的人员作为访客添加到项目中。使用 --project <slug> 推送到项目中。

通过 CLI 或 MCP 管理项目：

thing projects --team acme
thing project create "Q4 launch" --team acme --restricted --brief "Ship by week 3"
thing project add acme/q4-launch [email protected] --role editor
thing project set acme/q4-launch --access open --archive
thing push index.html --team acme --project q4-launch --home   # the project's page

项目页面本身可以是其制品之一。在项目页面中，thing.project.get() 会列出项目的制品，并显示每位读取者自己的访问权限。

推送内容所属的工作区按以下顺序确定：--team 标志 → 工作目录中的 .thing.json → 本地 thing use 覆盖项 → 服务端默认值（thing default）→ 个人空间。登录时不再固定工作区；因此，如果未设置任何覆盖项，服务端会选择默认工作区（例如，Unravel 成员的 Unravel 组织）。

MCP

Claude Code、Cursor、Codex 以及其他支持 Model Context Protocol 的工具，都可以通过 thing 发布。无需登录终端：在 usething.ai 的 Settings 下选择 Tokens 创建令牌，然后将其粘贴到 客户端的 MCP 配置中。

{
  "mcpServers": {
    "thing": {
      "command": "npx",
      "args": ["-y", "@unravel-tech/thing@latest", "mcp"],
      "env": { "THING_TOKEN": "paste-your-token-here" }
    }
  }
}

在有 Bun 但没有 Node 的机器上，将 npx 替换为 bunx：

{
  "mcpServers": {
    "thing": {
      "command": "bunx",
      "args": ["-y", "@unravel-tech/thing@latest", "mcp"],
      "env": { "THING_TOKEN": "paste-your-token-here" }
    }
  }
}

此服务提供以下工具：server_info 用于查看已安装的版本和更新状态，push_artifact 用于发布文件或内联内容并获取链接（以及任何服务端的 notes），list_artifacts 用于查看你已有的内容，get_artifact 用于读取某个版本的源文件（文本以内联形式返回，PDF 和图片则保存到 save_to），list_artifact_versions、list_artifact_comments、list_artifact_responses 用于读取页面的 Inputs 答案，submit_artifact_response 用于在用户要求时代为回答，以及 whoami 用于检查你要发布到哪个账户和团队。所有接受 artifact 的工具都支持名称、team/slug 或链接。

如果你已经运行过 thing login，则会使用已存储的凭据，可以不设置 THING_TOKEN。

运行时

Node >= 18 或 Bun，无运行时依赖。thing 可执行文件会在 PATH 中可用的两者之一（优先使用 Node）下启动，因此即使机器从未安装过 Node，全局安装也能正常工作：

bun i -g @unravel-tech/thing
thing login