x07-package

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

x07-package

This skill documents the single canonical workflow for dependency management in X07 using the built-in package manager (

x07 pkg ...

本技能文档介绍了使用内置包管理器（

x07 pkg ...

）在X07中进行依赖管理的唯一标准工作流。

When to use

使用场景

Use this skill when:

adding/updating dependencies,
generating/verifying lockfiles,
publishing a package to an index/registry.

在以下场景中使用本技能：

添加/更新依赖项，
生成/验证锁定文件，
将包发布到索引/注册表。

Canonical commands

标准命令

Create a publishable package repo (for
```
x07 pkg publish
```
):
- ```
x07 init --package
```
Add a dependency entry to
```
x07.json
```
and sync the lockfile:
- ```
x07 pkg add <name>@<version> --sync
```
Generate or update a project lockfile:
- ```
x07 pkg lock --project x07.json
```
Non-mutating whole-project validation (no emit):
- ```
x07 check --project x07.json
```
Reverse-lookup which package provides a module:
- ```
x07 pkg provides <module-id>
```

List available versions of a package:

```
x07 pkg versions <name>
```
```
x07 pkg versions <name> --refresh
```

Verify a lockfile is up to date (CI mode):
- ```
x07 pkg lock --project x07.json --check
```
- If you intentionally accept risk in CI: add
```
--allow-yanked
```
  and/or
```
--allow-advisories
```

Pack a package directory deterministically:

x07 pkg pack --package <dir> --out <out.x07pkg>

Interactive:
```
x07 pkg login --index <url>
```

Non-interactive:

printf '%s' "$X07_TOKEN" | x07 pkg login --index <url> --token-stdin

Publish:

x07 pkg publish --package <dir> --index <url>

创建可发布的包仓库（用于
```
x07 pkg publish
```
）：
- ```
x07 init --package
```
向
```
x07.json
```
添加依赖项条目并同步锁定文件：
- ```
x07 pkg add <name>@<version> --sync
```
生成或更新项目锁定文件：
- ```
x07 pkg lock --project x07.json
```
非变更型全项目验证（无输出）：
- ```
x07 check --project x07.json
```
反向查找提供某模块的包：
- ```
x07 pkg provides <module-id>
```

列出包的可用版本：

```
x07 pkg versions <name>
```
```
x07 pkg versions <name> --refresh
```

验证锁定文件是否为最新版本（CI模式）：
- ```
x07 pkg lock --project x07.json --check
```
- 若在CI中有意接受风险：添加
```
--allow-yanked
```
  和/或
```
--allow-advisories
```

确定性打包包目录：

x07 pkg pack --package <dir> --out <out.x07pkg>

交互式：
```
x07 pkg login --index <url>
```

非交互式：

printf '%s' "$X07_TOKEN" | x07 pkg login --index <url> --token-stdin

发布：

x07 pkg publish --package <dir> --index <url>

Notes

注意事项

Official registry index URL:
```
sparse+https://registry.x07.io/index/
```
Publishing to the official registry requires non-empty
```
description
```
and
```
docs
```
in
```
x07-package.json
```
.
The lockfile path is controlled by
```
x07.json
```
(
```
lockfile
```
) and defaults to
```
x07.lock.json
```
.
When fetching is required,
```
x07 pkg lock
```
defaults to the official registry index; override with
```
--index <url>
```
.
Sparse index reads (including
```
x07 pkg versions
```
) may be cached; use
```
--refresh
```
after publishing to force a cache-busting fetch (HTTP/HTTPS indexes only).
Canonical project manifests use
```
x07.project@0.3.0
```
.
```
x07.project@0.2.0
```
is accepted for legacy manifests, but
```
project.patch
```
requires
```
@0.3.0
```
.
In
```
--check
```
mode, when the index can be consulted, lock validation also fails on yanked dependencies and active advisories unless explicitly allowed.
Use
```
project.patch
```
in
```
x07.json
```
to override transitive dependency versions (for example, moving off yanked/advised versions).
Patch paths under
```
.x07/deps/...
```
are treated as vendored deps (fetchable) during
```
x07 pkg lock
```
hydration; patch paths elsewhere are local-only and must exist on disk.
Official packages may declare required helper packages via
```
meta.requires_packages
```
. When present,
```
x07 pkg lock
```
may add and fetch these transitive deps (and update
```
x07.json
```
).
If dependencies are already present on disk,
```
x07 pkg lock
```
can run without
```
--index
```
using
```
--offline
```
.

官方注册表索引URL：
```
sparse+https://registry.x07.io/index/
```
向官方注册表发布时，
```
x07-package.json
```
中必须包含非空的
```
description
```
和
```
docs
```
字段。
锁定文件路径由
```
x07.json
```
中的
```
lockfile
```
字段控制，默认路径为
```
x07.lock.json
```
。
当需要拉取依赖时，
```
x07 pkg lock
```
默认使用官方注册表索引；可通过
```
--index <url>
```
覆盖。
稀疏索引读取（包括
```
x07 pkg versions
```
）可能会被缓存；发布后使用
```
--refresh
```
可强制跳过缓存重新拉取（仅适用于HTTP/HTTPS索引）。
标准项目清单使用
```
x07.project@0.3.0
```
。旧版清单
```
x07.project@0.2.0
```
可被兼容，但
```
project.patch
```
需要
```
@0.3.0
```
版本。
在
```
--check
```
模式下，若可访问索引，锁定验证在遇到已撤回（yanked）的依赖项或存在安全预警的依赖项时会失败，除非显式允许。
可在
```
x07.json
```
中使用
```
project.patch
```
来覆盖传递依赖的版本（例如，从已撤回/有安全预警的版本切换）。
在
```
x07 pkg lock
```
的依赖注入过程中，
```
.x07/deps/...
```
下的补丁路径会被视为可拉取的 vendored 依赖；其他位置的补丁路径仅为本地路径，必须存在于磁盘上。
官方包可通过
```
meta.requires_packages
```
声明所需的辅助包。存在该字段时，
```
x07 pkg lock
```
可能会添加并拉取这些传递依赖（同时更新
```
x07.json
```
）。
若依赖项已存在于磁盘上，
```
x07 pkg lock
```
可在不使用
```
--index
```
的情况下通过
```
--offline
```
参数运行。

另请参阅：https://x07lang.org/docs/packages/publishing-by-example/