Skip to content

Commit c377d2d

Browse files
jaronniejaronnie
committed
chore(docs): update docs
1 parent 39a0d1c commit c377d2d

7 files changed

Lines changed: 320 additions & 6 deletions

File tree

‎docs/src/getting-started/new.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,33 @@ jzero provides the following types of templates to meet various scenarios:
2121

2222
For detailed usage, see: [Template Guide](../guide/template.md)
2323

24+
## Template market
25+
26+
If built-in frames such as `api`, `rpc`, and `gateway` are not enough, visit the [jzero Template Market](https://templates.jzero.io).
27+
28+
The template market is the entry for discovering built-in templates, official external templates, and third-party templates. You can use it to quickly find the source repository, usage guide, and recommended initialization command for a template.
29+
30+
For official external templates, `jzero new` usually only needs the `--branch` parameter because the default remote repository already points to `https://github.com/jzero-io/templates`.
31+
32+
Quick links:
33+
34+
* [Template market home](https://templates.jzero.io)
35+
* [CLI template](https://templates.jzero.io/external/cli/)
36+
* [Vercel API template branch](https://github.com/jzero-io/templates/tree/api-vercel)
37+
38+
```shell
39+
# Official CLI template
40+
jzero new mycli --branch cli
41+
42+
# Official Vercel API template
43+
jzero new myvercel --branch api-vercel
44+
45+
# Third-party or private template
46+
jzero new your_project --remote <template-repo> --branch <template-branch>
47+
```
48+
49+
For more template details and examples, see the [jzero Template Market](https://templates.jzero.io) and [Template Guide](../guide/template.md).
50+
2451
## Initialize api project
2552

2653
::: code-tabs#shell

‎docs/src/guide/cli-plugin.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Custom CLI plugins
3+
icon: /icons/arcticons-game-plugins.svg
4+
star: true
5+
order: 0.15
6+
---
7+
8+
If built-in commands are not enough, you can extend `jzero` with external executables instead of modifying the main binary.
9+
10+
This is useful for team-specific scaffolding, internal release workflows, deployment helpers, or any command that should feel like a native `jzero` subcommand.
11+
12+
## Discovery rules
13+
14+
When `jzero` receives an unknown command, it searches `PATH` for matching plugin executables:
15+
16+
* `jzero hello` -> `jzero-hello`
17+
* `jzero foo bar` -> first tries `jzero-foo-bar`, then falls back to `jzero-foo`
18+
* After a plugin is matched, the remaining arguments are passed through to the plugin unchanged
19+
* The current environment variables are also forwarded to the plugin process
20+
21+
A plugin only needs two requirements:
22+
23+
* The file name starts with `jzero-`
24+
* The file is executable and available in `PATH`
25+
26+
:::tip
27+
Put plugin-specific flags after the plugin command, for example `jzero hello --name codex`.
28+
:::
29+
30+
## Minimal example
31+
32+
The plugin can be written in Go, shell, or any language that can produce an executable in `PATH`.
33+
34+
```bash
35+
mkdir -p ~/.local/bin
36+
37+
cat > ~/.local/bin/jzero-hello <<'EOF'
38+
#!/usr/bin/env bash
39+
set -euo pipefail
40+
41+
name="${1:-world}"
42+
printf 'hello, %s\n' "$name"
43+
EOF
44+
45+
chmod +x ~/.local/bin/jzero-hello
46+
export PATH="$HOME/.local/bin:$PATH"
47+
48+
jzero hello codex
49+
# hello, codex
50+
```
51+
52+
## Read `desc` metadata in Go plugins
53+
54+
If your plugin is implemented in Go, you can also reuse `github.com/jzero-io/jzero/cmd/jzero/pkg/plugin`.
55+
56+
This does not replace external plugin discovery. `jzero` still discovers your binary through the `jzero-*` naming rule. The extra package is for reading parsed project metadata inside the plugin process.
57+
58+
`plugin.New()` scans the current working directory and attempts to parse:
59+
60+
* `desc/api`
61+
* `desc/proto`
62+
* `desc/sql`
63+
64+
It returns a `Metadata` value whose `Desc` field contains:
65+
66+
* `Desc.Api.SpecMap`: parsed API specs keyed by source file path
67+
* `Desc.Proto.SpecMap`: parsed Proto specs keyed by source file path
68+
* `Desc.Model.SpecMap`: parsed SQL table specs keyed by table name
69+
70+
```go
71+
package main
72+
73+
import (
74+
"fmt"
75+
76+
jplugin "github.com/jzero-io/jzero/cmd/jzero/pkg/plugin"
77+
)
78+
79+
func main() {
80+
metadata, err := jplugin.New()
81+
if err != nil {
82+
panic(err)
83+
}
84+
85+
fmt.Printf("api files: %d\n", len(metadata.Desc.Api.SpecMap))
86+
fmt.Printf("proto files: %d\n", len(metadata.Desc.Proto.SpecMap))
87+
fmt.Printf("sql tables: %d\n", len(metadata.Desc.Model.SpecMap))
88+
}
89+
```
90+
91+
:::tip
92+
`plugin.New()` reads from the plugin process's current working directory, so it is typically used when your plugin is executed inside a jzero project root.
93+
:::
94+
95+
## Multi-level commands
96+
97+
You can map multiple command levels to a single executable name.
98+
99+
```bash
100+
# jzero foo bar baz
101+
# jzero will try jzero-foo-bar first
102+
# if not found, it falls back to jzero-foo
103+
# this usually means subcommands like "bar baz" are handled by jzero-foo itself
104+
```
105+
106+
This allows you to organize team commands in a natural way, such as `jzero release publish` or `jzero company bootstrap`.
107+
108+
## Naming notes
109+
110+
Inside each command segment, `jzero` normalizes `-` to `_` before lookup.
111+
112+
For example:
113+
114+
* `jzero my-cmd` -> executable name `jzero-my_cmd`
115+
116+
To keep naming predictable, prefer simple command names or use `_` in the plugin executable when your command segment contains `-`.
117+
118+
## Recommended workflow
119+
120+
1. Build or place the plugin executable in a directory that is already in `PATH`
121+
2. Follow the `jzero-<command>` naming rule
122+
3. Add help output in the plugin itself, then use `jzero <command> --help` to view usage
123+
124+
Plugins are discovered dynamically, so they are not part of the built-in static command list printed by `jzero --help`.

‎docs/src/guide/jzero.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ order: 0.1
1010
* Supports controlling various parameters through configuration file .jzero.yaml
1111
* Supports controlling various parameters through flag
1212
* Supports controlling various parameters through environment variables
13-
* Supports controlling various parameters through combination of above methods, priority from high to low: environment variables > flag > configuration file
13+
* Supports controlling various parameters through combination of above methods, priority from high to low: flag > environment variables > configuration file
1414

1515
Example: `jzero gen --style go_zero` corresponds to `.jzero.yaml` content
1616

@@ -82,3 +82,9 @@ jzero gen --quiet
8282
```shell
8383
jzero gen --debug
8484
```
85+
86+
## Custom CLI plugins
87+
88+
If built-in commands are not enough, `jzero` can dispatch unknown commands to external executables in `PATH`.
89+
90+
See [Custom CLI plugins](./cli-plugin.md).

‎docs/src/zh-CN/blog/cli-tool-guide.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ export MYCLI_GREET_NAME="张三"
278278

279279
jzero CLI 模板提供统一的配置管理系统，所有配置通过 `internal/config/config.go` 管理，支持配置文件、环境变量和命令行标志三种方式，自动按优先级加载。
280280

281-
配置优先级：**环境变量 > 命令行标志 > 配置文件**
281+
配置优先级：**命令行标志 > 环境变量 > 配置文件**
282282

283283
### 统一配置的优势
284284

@@ -790,4 +790,4 @@ cd your-cli
790790

791791
**让 jzero CLI 模板成为你 AI 时代的得力助手！** 🚀
792792

793-
**觉得有用？请给 jzero 一个 ⭐ Star，支持我们继续改进！**
793+
**觉得有用？请给 jzero 一个 ⭐ Star，支持我们继续改进！**

‎docs/src/zh-CN/getting-started/new.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,33 @@ jzero 提供了以下几种类型模板, 满足各种场景:
2121

2222
具体使用请参阅: [模板指南](../guide/template.md)
2323

24+
## 模板市场
25+
26+
如果内置的 `api`、`rpc`、`gateway` 等框架模板无法满足需求，可以访问 [jzero 模板市场](https://templates.jzero.io)。
27+
28+
模板市场是发现内置模板、官方外置模板以及第三方模板的统一入口。你可以在这里快速找到模板对应的源码仓库、使用说明以及推荐的初始化命令。
29+
30+
对于官方外置模板，`jzero new` 通常只需要传入 `--branch`，因为默认远程仓库已经指向 `https://github.com/jzero-io/templates`。
31+
32+
快捷跳转：
33+
34+
* [模板市场首页](https://templates.jzero.io)
35+
* [CLI 模板](https://templates.jzero.io/external/cli/)
36+
* [Vercel API 模板分支](https://github.com/jzero-io/templates/tree/api-vercel)
37+
38+
```shell
39+
# 官方 CLI 模板
40+
jzero new mycli --branch cli
41+
42+
# 官方 Vercel API 模板
43+
jzero new myvercel --branch api-vercel
44+
45+
# 第三方或企业私有模板
46+
jzero new your_project --remote <template-repo> --branch <template-branch>
47+
```
48+
49+
更多模板说明和示例请参阅 [jzero 模板市场](https://templates.jzero.io) 与 [模板指南](../guide/template.md)。
50+
2451
## 初始化 api 项目
2552

2653
::: code-tabs#shell
@@ -129,4 +156,4 @@ jzero new your_project --features model,cache
129156

130157
# 使用场景: 需要连接关系型数据库(model)
131158
jzero new your_project --features model
132-
```
159+
```

‎docs/src/zh-CN/guide/cli-plugin.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: 自定义 jzero CLI 插件
3+
icon: /icons/arcticons-game-plugins.svg
4+
star: true
5+
order: 0.15
6+
---
7+
8+
如果内置命令不够用，可以通过外部可执行文件扩展 `jzero`，而不需要修改主二进制。
9+
10+
这适合承载团队内部脚手架、发布流程、部署辅助命令，或者任何希望表现成原生命令的自定义能力。
11+
12+
## 发现规则
13+
14+
当 `jzero` 收到一个未知命令时，会到 `PATH` 中查找匹配的插件可执行文件：
15+
16+
* `jzero hello` -> `jzero-hello`
17+
* `jzero foo bar` -> 优先尝试 `jzero-foo-bar`，找不到时再回退到 `jzero-foo`
18+
* 命中插件后，剩余参数会原样透传给插件
19+
* 当前环境变量也会一并传递给插件进程
20+
21+
一个插件只需要满足两个条件：
22+
23+
* 文件名以 `jzero-` 开头
24+
* 文件本身可执行，并且位于 `PATH` 中
25+
26+
:::tip
27+
插件自己的参数请放在插件命令之后，例如 `jzero hello --name codex`。
28+
:::
29+
30+
## 最小示例
31+
32+
插件可以用 Go、Shell，或者任何能够生成 `PATH` 内可执行文件的语言来实现。
33+
34+
```bash
35+
mkdir -p ~/.local/bin
36+
37+
cat > ~/.local/bin/jzero-hello <<'EOF'
38+
#!/usr/bin/env bash
39+
set -euo pipefail
40+
41+
name="${1:-world}"
42+
printf 'hello, %s\n' "$name"
43+
EOF
44+
45+
chmod +x ~/.local/bin/jzero-hello
46+
export PATH="$HOME/.local/bin:$PATH"
47+
48+
jzero hello codex
49+
# hello, codex
50+
```
51+
52+
## 在 Go 插件中读取 `desc` 元数据
53+
54+
如果你的插件是用 Go 实现的，还可以复用 `github.com/jzero-io/jzero/cmd/jzero/pkg/plugin`。
55+
56+
这并不会替代前面的外部插件发现机制。`jzero` 仍然通过 `jzero-*` 命名规则发现并执行你的插件二进制；这个包解决的是插件进程内部如何读取并解析项目描述文件。
57+
58+
`plugin.New()` 会基于当前工作目录，尝试解析：
59+
60+
* `desc/api`
61+
* `desc/proto`
62+
* `desc/sql`
63+
64+
返回的 `Metadata` 中，`Desc` 字段包含：
65+
66+
* `Desc.Api.SpecMap`：按源文件路径组织的 API 解析结果
67+
* `Desc.Proto.SpecMap`：按源文件路径组织的 Proto 解析结果
68+
* `Desc.Model.SpecMap`：按表名组织的 SQL 解析结果
69+
70+
```go
71+
package main
72+
73+
import (
74+
"fmt"
75+
76+
jplugin "github.com/jzero-io/jzero/cmd/jzero/pkg/plugin"
77+
)
78+
79+
func main() {
80+
metadata, err := jplugin.New()
81+
if err != nil {
82+
panic(err)
83+
}
84+
85+
fmt.Printf("api files: %d\n", len(metadata.Desc.Api.SpecMap))
86+
fmt.Printf("proto files: %d\n", len(metadata.Desc.Proto.SpecMap))
87+
fmt.Printf("sql tables: %d\n", len(metadata.Desc.Model.SpecMap))
88+
}
89+
```
90+
91+
:::tip
92+
`plugin.New()` 读取的是插件进程当前工作目录下的内容，因此通常应在 jzero 项目根目录中执行插件。
93+
:::
94+
95+
## 多级命令
96+
97+
你可以把多级命令路径映射成一个插件可执行文件名。
98+
99+
```bash
100+
# jzero foo bar baz
101+
# jzero 会优先尝试 jzero-foo-bar
102+
# 如果没找到，则会回退到 jzero-foo
103+
# 这通常意味着后续的 "bar baz" 子命令由 jzero-foo 自己继续处理
104+
```
105+
106+
这样可以自然地组织团队命令，例如 `jzero release publish` 或 `jzero company bootstrap`。
107+
108+
## 命名注意事项
109+
110+
在每个命令段内部，`jzero` 会在查找前把 `-` 归一化成 `_`。
111+
112+
例如：
113+
114+
* `jzero my-cmd` -> 对应的可执行文件名应为 `jzero-my_cmd`
115+
116+
为了减少歧义，建议优先使用简单命令名；如果命令段中必须包含 `-`，则在插件文件名中使用 `_`。
117+
118+
## 推荐工作流
119+
120+
1. 将插件可执行文件构建或放置到已经在 `PATH` 中的目录
121+
2. 按照 `jzero-<command>` 规则命名
122+
3. 在插件内部实现自己的帮助输出，然后通过 `jzero <command> --help` 查看使用方式
123+
124+
插件是动态发现的，因此不会出现在 `jzero --help` 打印的内置静态命令列表中。

‎docs/src/zh-CN/guide/jzero.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ order: 0.1
1010
* 支持通过配置文件 .jzero.yaml 控制各种参数
1111
* 支持通过 flag 控制各种参数
1212
* 支持通过环境变量控制各种参数
13-
* 支持通过以上组合的方式控制各种参数, 优先级从高到低为: 环境变量 > flag > 配置文件
13+
* 支持通过以上组合的方式控制各种参数, 优先级从高到低为: flag > 环境变量 > 配置文件
1414

1515
如: `jzero gen --style go_zero` 对应 `.jzero.yaml` 内容
1616

@@ -81,4 +81,10 @@ jzero gen --quiet
8181

8282
```shell
8383
jzero gen --debug
84-
```
84+
```
85+
86+
## 自定义 CLI 插件
87+
88+
如果内置命令不够用，`jzero` 也支持将未知命令转发给 `PATH` 中的外部可执行文件。
89+
90+
具体说明请参阅 [自定义 jzero CLI 插件](./cli-plugin.md)。

0 commit comments

Comments
 (0)