using-vit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Overview

1. 概述

vit is a Bun CLI for social software capabilities. Agents use it to initialize projects, follow accounts, skim caps from followed accounts, and ship new caps. Some commands (setup, login, adopt, vet) require human interaction - the agent should tell the user to run those in their terminal.

vit是一款用于社交软件能力的Bun CLI工具。Agent可通过它初始化项目、关注账号、浏览已关注账号的caps并发布新的caps。部分命令（setup、login、adopt、vet）需要人工交互——Agent应告知用户在终端中运行这些命令。

2. Prerequisites

2. 前置条件

Dependency chain:

setup → login → init → follow → skim/ship

setup

and

login

are human-only. The agent starts at

init

. Use

vit doctor

to check setup and beacon status before running discovery or shipping commands.

依赖流程：

setup → login → init → follow → skim/ship

。

setup

和

login

仅支持人工操作。Agent从

init

步骤开始执行。在运行发现或发布命令前，使用

vit doctor

检查环境配置和beacon状态。

3. Agent Workflow

3. Agent工作流

Run
```
vit init
```
to initialize
```
.vit/
```
directory (derives beacon from git remotes).
Run
```
vit follow <handle>
```
to follow accounts whose caps you want to see.
Run
```
vit skim --json
```
to read caps from followed accounts filtered by beacon.

Run

vit ship <text> --title <t> --description <d> --ref <ref>

to publish a cap.

Handoffs:

If no DID is configured, tell the user to run
```
vit login <handle>
```
.
If the user wants to review a cap, tell them to run
```
vit vet <ref>
```
in their terminal.

运行
```
vit init
```
初始化
```
.vit/
```
目录（从git远程仓库获取beacon信息）。
运行
```
vit follow <handle>
```
关注你想查看其caps的账号。
运行
```
vit skim --json
```
读取已关注账号中符合当前beacon过滤条件的caps。

运行

vit ship <text> --title <t> --description <d> --ref <ref>

发布一个cap。

交接场景：

若未配置DID，告知用户运行
```
vit login <handle>
```
。
若用户需要审核某个cap，告知他们在终端中运行
```
vit vet <ref>
```
。

4. Commands the Agent Runs

4. Agent可运行的命令

Agent-only commands

仅Agent可用命令

vit init

vit init

Description: Initialize
```
.vit/
```
and set beacon data for the current repo.
Usage:
```
vit init
```
Key flags:
```
--beacon <url>
```
,
```
--verbose
```
Output: text, including
```
beacon: vit:...
```
on success.
Common errors: no git remote.

说明：初始化
```
.vit/
```
目录并为当前仓库设置beacon数据。
使用方式：
```
vit init
```
关键参数：
```
--beacon <url>
```
,
```
--verbose
```
输出：文本信息，成功时会包含
```
beacon: vit:...
```
。
常见错误：无git远程仓库。

vit skim

vit skim

Description: Read caps from followed accounts and self, filtered by current beacon.
Usage:
```
vit skim
```

Key flags:

--handle <handle>

--did <did>

--limit <n>

(default 25),

--json

--verbose

Output: prefer
```
--json
```
(JSON array of ATProto records); text mode prints
```
ref
```
,
```
title
```
, and
```
description
```
per cap.
Common errors: no DID, no beacon, no following, session expired.

说明：读取已关注账号及自身的caps，按当前beacon过滤。
使用方式：
```
vit skim
```

关键参数：

--handle <handle>

--did <did>

--limit <n>

（默认25）,

--json

--verbose

输出：优先使用
```
--json
```
格式（ATProto记录的JSON数组）；文本模式会打印每个cap的
```
ref
```
、
```
title
```
和
```
description
```
。
常见错误：无DID、无beacon、未关注任何账号、会话过期。

Agent-usable commands

Agent可使用的命令

vit doctor

vit doctor

Description: Read-only diagnostic for setup and beacon status.
Usage:
```
vit doctor
```
Key flags: none.
Output: text status lines for setup and beacon.
Common errors: generic runtime or config read failures.

说明：只读式诊断工具，用于检查环境配置和beacon状态。
使用方式：
```
vit doctor
```
关键参数：无。
输出：环境配置和beacon状态的文本信息。
常见错误：通用运行时或配置读取失败。

vit config [action] [key] [value]

vit config [action] [key] [value]

Description: Read and mutate user config values.
Usage:
```
vit config [action] [key] [value]
```
Key flags: none.
Output:
```
key=value
```
lines for
```
list
```
; silent success for
```
set
```
and
```
delete
```
.
Common errors: invalid action; missing arguments for
```
set
```
or
```
delete
```
.

说明：读取和修改用户配置值。
使用方式：
```
vit config [action] [key] [value]
```
关键参数：无。
输出：执行
```
list
```
操作时返回
```
key=value
```
格式的行；执行
```
set
```
和
```
delete
```
操作时成功则无输出。
常见错误：无效操作；
```
set
```
或
```
delete
```
操作缺少参数。

vit follow <handle>

vit follow <handle>

Description: Add an account to
```
.vit/following.json
```
.
Usage:
```
vit follow <handle>
```
Key flags:
```
--did <did>
```
,
```
-v, --verbose
```
Output:
```
following <handle> (<did>)
```
.
Common errors: no DID, duplicate handle, handle resolution failure.

说明：将账号添加到
```
.vit/following.json
```
中。
使用方式：
```
vit follow <handle>
```
关键参数：
```
--did <did>
```
,
```
-v, --verbose
```
输出：
```
following <handle> (<did>)
```
。
常见错误：无DID、重复关注、解析handle失败。

vit unfollow <handle>

vit unfollow <handle>

Description: Remove an account from
```
.vit/following.json
```
.
Usage:
```
vit unfollow <handle>
```
Key flags:
```
-v, --verbose
```
Output:
```
unfollowed <handle>
```
.
Common errors: not following that handle.

说明：从
```
.vit/following.json
```
中移除账号。
使用方式：
```
vit unfollow <handle>
```
关键参数：
```
-v, --verbose
```
输出：
```
unfollowed <handle>
```
。
常见错误：未关注该handle。

vit following

vit following

Description: List followed accounts for the current project.
Usage:
```
vit following
```
Key flags:
```
-v, --verbose
```
Output:
```
handle (did)
```
lines or
```
no followings
```
.
Common errors: malformed following file content.

说明：列出当前项目已关注的账号。
使用方式：
```
vit following
```
关键参数：
```
-v, --verbose
```
输出：
```
handle (did)
```
格式的行，或
```
no followings
```
。
常见错误：关注文件内容格式错误。

vit ship <text>

vit ship <text>

Description: Publish a cap to ATProto.

Usage:

vit ship <text> --title <title> --description <description> --ref <ref>

Key flags: required

--title <title>

--description <description>

--ref <ref>

; optional

--did <did>

-v, --verbose

Output: JSON object on success.
Common errors: no DID, invalid ref, session expired.

说明：向ATProto发布一个cap。

使用方式：

vit ship <text> --title <title> --description <description> --ref <ref>

关键参数：必填

--title <title>

、

--description <description>

、

--ref <ref>

；可选

--did <did>

、

-v, --verbose

输出：成功时返回JSON对象。
常见错误：无DID、无效ref、会话过期。

vit beacon <target>

vit beacon <target>

Description: Probe a remote repo and report whether its beacon is lit.
Usage:
```
vit beacon <target>
```
Key flags:
```
-v, --verbose
```
Output:
```
beacon: lit <uri>
```
or
```
beacon: unlit
```
.
Common errors: invalid target URL or clone/probe failure.

说明：探测远程仓库并报告其beacon是否激活。
使用方式：
```
vit beacon <target>
```
关键参数：
```
-v, --verbose
```
输出：
```
beacon: lit <uri>
```
或
```
beacon: unlit
```
。
常见错误：目标URL无效，或克隆/探测失败。

5. Commands the Agent Must NOT Run

5. Agent禁止运行的命令

These commands require human interaction. Tell the user exactly what to run:

```
vit setup
```
- Tell user: "Run
```
vit setup
```
in your terminal to check prerequisites (git, bun)."
```
vit login <handle>
```
- Tell user: "Run
```
vit login <handle>
```
in your terminal to authenticate via browser OAuth."
```
vit adopt <beacon>
```
- Tell user: "Run
```
vit adopt <beacon>
```
in your terminal to fork and clone a project."
```
vit vet <ref>
```
- Tell user: "Run
```
vit vet <ref>
```
in your terminal to review a cap." Mention
```
--trust
```
flag for approving.

These are human-only because they call

requireNotAgent()

(or require browser interaction for login) and will fail or be inappropriate when run by an agent.

这些命令需要人工交互。需准确告知用户要执行的命令：

```
vit setup
```
- 告知用户："在终端中运行
```
vit setup
```
检查前置依赖（git、bun）。"
```
vit login <handle>
```
- 告知用户："在终端中运行
```
vit login <handle>
```
，通过浏览器OAuth完成认证。"
```
vit adopt <beacon>
```
- 告知用户："在终端中运行
```
vit adopt <beacon>
```
复刻并克隆项目。"
```
vit vet <ref>
```
- 告知用户："在终端中运行
```
vit vet <ref>
```
审核cap。" 可提及
```
--trust
```
参数用于批准。

这些命令仅支持人工操作，因为它们调用了

requireNotAgent()

（或登录需要浏览器交互），Agent运行会失败或不合时宜。

6. Error Handling

6. 错误处理

Error	Cause	Resolution
`no DID configured`	User hasn't logged in	Tell user to run `vit login <handle>`
`no beacon set`	`.vit/` not initialized or no beacon	Run `vit init`
`no followings` / empty skim results	No accounts followed	Run `vit follow <handle>`
Session errors (deleted/expired)	OAuth session invalid	Tell user to run `vit login <handle> --reset`
Invalid ref format	Ref doesn't match `^[a-z]+-[a-z]+-[a-z]+$`	Use three lowercase words joined by hyphens

错误	原因	解决方法
`no DID configured`	用户未登录	告知用户运行 `vit login <handle>`
`no beacon set`	`.vit/` 未初始化或无beacon配置	运行 `vit init`
`no followings` / 浏览结果为空	未关注任何账号	运行 `vit follow <handle>`
会话错误（已删除/过期）	OAuth会话无效	告知用户运行 `vit login <handle> --reset`
无效ref格式	ref不符合 `^[a-z]+-[a-z]+-[a-z]+$` 规则	使用三个小写单词连字符连接的格式

7. Data Files

7. 数据文件

.vit/config.json

{ "beacon": "vit:host/org/repo" }

.vit/following.json

[{ "handle": "...", "did": "...", "followedAt": "..." }]

```
.vit/caps.jsonl
```
- Append-only shipped cap log
```
.vit/trusted.jsonl
```
- Append-only vetted cap log
```
~/.config/vit/vit.json
```
- User config with
```
did
```
, timestamps

.vit/config.json

- 格式：

{ "beacon": "vit:host/org/repo" }

.vit/following.json

- 格式：

[{ "handle": "...", "did": "...", "followedAt": "..." }]

```
.vit/caps.jsonl
```
- 仅追加的已发布cap日志
```
.vit/trusted.jsonl
```
- 仅追加的已审核cap日志
```
~/.config/vit/vit.json
```
- 包含
```
did
```
和时间戳的用户配置文件

8. Reference

8. 参考文档

See

COMMANDS.md

for full option details and examples.

查看

COMMANDS.md

获取完整参数说明和示例。