ax-repo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ax:repo

Let an AI coding agent interact with the ax GitHub repo (

Necmttn/ax

) for the user - star, file an issue, or fork + open a PR - without the user ever typing a

gh

command. Everything routes through the already-installed

gh

CLI; there is no

axctl

surface for this.

Repo:

Necmttn/ax

https://github.com/Necmttn/ax

让AI编码代理代表用户与ax的GitHub仓库（

Necmttn/ax

）交互——点赞（Star）、提交问题或复刻仓库并提交PR——用户无需输入任何

gh

命令。所有操作均通过已安装的

gh

CLI完成；此功能无

axctl

操作入口。

仓库地址：

Necmttn/ax

https://github.com/Necmttn/ax

When to fire

触发时机

"star ax" / "star the repo" / "I want to support ax" / "give ax a star"
"report this as an ax bug" / "file an ax issue" / "open an issue on ax"
"this looks like an ax bug" (after an
```
ax
```
/
```
axctl
```
error)
"I want to contribute to ax" / "fix this in ax" / "open a PR against ax"

Do NOT fire for GitHub work on other repos or for general

gh

usage. Issues and PRs are user-initiated only. Star is the exception - you may offer it proactively (see Proactive star nudge), but offering ≠ doing: the actual star always needs an explicit yes.

"star ax" / "star the repo" / "我想支持ax" / "给ax点个赞"
"把这个报告为ax的bug" / "提交ax的问题" / "在ax上提交问题"
"这看起来是ax的bug"（在
```
ax
```
/
```
axctl
```
出错后）
"我想为ax做贡献" / "修复ax里的这个问题" / "向ax提交PR"

请勿在处理其他仓库的GitHub工作或通用

gh

操作时触发。问题和PR仅由用户主动发起。点赞是例外情况——你可以主动提及（见主动点赞提示），但提及≠执行：实际点赞操作始终需要用户明确同意。

Non-negotiable rules

不可违反的规则

Preflight
gh
first (read-only, no confirm). Detect three states:
- ```
gh
```
  missing → fall back to a plain URL (see Fallback). Don't error.
- ```
gh
```
  present but unauthenticated → fall back to a plain URL, and tell the user they can
```
gh auth login
```
  to do it inline next time.
- ```
gh
```
  present + authed → proceed to the action (still confirm mutations).
Confirm before any account-mutating call - star, issue create, PR create all change the user's GitHub account/repo. Show the exact command, get an explicit yes. Read-only checks (
```
gh auth status
```
, "is it starred") need NO confirm.
Never break the caller's exit code, never run silently in CI. If
```
$CI
```
is set or stderr/stdin isn't a TTY, do NOT run mutating
```
gh
```
calls - print the URL instead. A failed
```
gh
```
call must not abort the user's task.

先执行
gh
预检（只读操作，无需确认）。检测三种状态：
- ```
gh
```
  未安装 → 回退到纯URL（见回退方案）。不要报错。
- ```
gh
```
  已安装但未认证 → 回退到纯URL，并告知用户下次可通过
```
gh auth login
```
  进行内联操作。
- ```
gh
```
  已安装且已认证 → 继续执行操作（仍需确认变更操作）。
执行任何会更改账户的调用前需确认——点赞、创建问题、创建PR都会更改用户的GitHub账户/仓库。显示确切的命令，获取明确同意。只读检查（
```
gh auth status
```
、“是否已点赞”）无需确认。
绝不能破坏调用者的退出码，绝不能在CI环境中静默运行。如果设置了
```
$CI
```
或stderr/stdin不是TTY，请勿执行变更性
```
gh
```
调用——改为打印URL。
```
gh
```
调用失败绝不能中断用户的任务。

Preflight (run this before every action)

预检（每次操作前执行）

bash

if ! command -v gh >/dev/null 2>&1; then
  echo "GH_STATE=missing"
elif ! gh auth status >/dev/null 2>&1; then
  echo "GH_STATE=unauthed"   # gh auth status exits 4 when not logged in
else
  echo "GH_STATE=ok"
fi

```
missing
```
/
```
unauthed
```
→ use Fallback for the chosen action.
```
ok
```
→ use the
```
gh
```
command for the chosen action (after confirm).

bash

if ! command -v gh >/dev/null 2>&1; then
  echo "GH_STATE=missing"
elif ! gh auth status >/dev/null 2>&1; then
  echo "GH_STATE=unauthed"   # gh auth status未登录时退出码为4
else
  echo "GH_STATE=ok"
fi

```
missing
```
/
```
unauthed
```
→ 对所选操作使用回退方案。
```
ok
```
→ 使用
```
gh
```
命令执行所选操作（确认后）。

Actions

操作说明

1. Star

1. 点赞（Star）

Mutates the user's account → confirm first.

bash

undefined

会更改用户账户 → 先确认。

bash

undefined

Optional read-only check (no confirm): is it already starred?

可选只读检查（无需确认）：是否已点赞？

exits 0 (starred) / non-zero / 404 (not starred)

退出码0（已点赞）/非零/404（未点赞）

gh api /user/starred/Necmttn/ax >/dev/null 2>&1 && echo "already starred"

The star (after explicit yes):

点赞操作（得到明确同意后）：

gh api -X PUT /user/starred/Necmttn/ax # silent 204 on success


If already starred, say so and skip - don't re-PUT or re-prompt.
Unstar (only if asked): `gh api -X DELETE /user/starred/Necmttn/ax`.

You can also just run `ax star`, which stars via `gh` (or prints the URL) and
silences the CLI's periodic star reminder.

**Fallback (gh missing/unauthed):** print
`https://github.com/Necmttn/ax` and tell the user to click **Star**.

> Proactive star prompting is NOT this skill's job - the CLI handles it
> deterministically (a once-a-day stderr footer shown only on an interactive
> terminal until the user runs `ax star` / `ax star --done`). This skill only
> acts on an explicit user request.

gh api -X PUT /user/starred/Necmttn/ax # 成功时静默返回204


如果已点赞，告知用户并跳过——不要重复执行PUT操作或再次提示。
取消点赞（仅在用户要求时）：`gh api -X DELETE /user/starred/Necmttn/ax`。

你也可以直接运行`ax star`，它会通过`gh`完成点赞（或打印URL），并关闭CLI定期的点赞提醒。

**回退方案（gh未安装/未认证）：** 打印`https://github.com/Necmttn/ax`并告知用户点击**Star**按钮。

> 主动提示点赞不属于本技能的职责——由CLI确定性处理（仅在交互式终端上每日显示一次stderr页脚，直到用户运行`ax star` / `ax star --done`）。本技能仅在用户明确请求时执行操作。

2. File an issue / bug report

2. 提交问题 / Bug报告

Mutates (creates an issue) → confirm first, and show the title/body you'll submit so the user can edit before you send it.

Interactive (opens a prefilled browser form - good default when the user wants to review/edit in GitHub's UI):

bash

gh issue create --repo Necmttn/ax --web

Non-interactive (prefilled title + body, e.g. an error report you assembled):

bash

gh issue create --repo Necmttn/ax \
  --title "<concise summary>" \
  --body "<body>" \
  --label feedback        # only if the user confirms; omit if unsure label exists

Error-report pattern. When firing off the back of an unhandled

ax

axctl

error, prefill from the failure - never make the user paste a stack trace:

bash

gh issue create --repo Necmttn/ax \
  --title "ingest: <one-line error>" \
  --body "$(cat <<'EOF'
**Command:** `ax <subcommand> <args>`
**ax version:** <output of `ax --version`>
**OS:** <uname -srm>

**What happened**
<one or two sentences>

**Error**

EOF
)"

Scrub paths/tokens that might leak private data before submitting. Confirm the assembled body with the user first.

Fallback (gh missing/unauthed): print the web new-issue URL. You can prefill it via query string:

https://github.com/Necmttn/ax/issues/new?title=<urlencoded>&body=<urlencoded>

(plain

https://github.com/Necmttn/ax/issues/new

also works). Tell the user to review and submit in the browser.

会更改仓库（创建问题）→ 先确认，并展示你要提交的标题/内容，让用户在发送前可编辑。

交互式方式（打开预填充的浏览器表单——用户想要在GitHub界面中查看/编辑时的默认选项）：

bash

gh issue create --repo Necmttn/ax --web

非交互式方式（预填充标题+内容，例如你整理的错误报告）：

bash

gh issue create --repo Necmttn/ax \
  --title "<简洁摘要>" \
  --body "<内容>" \
  --label feedback        # 仅在用户确认后添加；不确定标签是否存在时省略

错误报告模板。当因未处理的

ax

axctl

错误触发时，从失败信息中预填充内容——绝不要让用户粘贴堆栈跟踪：

bash

gh issue create --repo Necmttn/ax \
  --title "ingest: <单行错误信息>" \
  --body "$(cat <<'EOF'
**命令：** `ax <子命令> <参数>`
**ax版本：** <`ax --version`的输出>
**操作系统：** <uname -srm的输出>

**发生了什么**
<一到两句话描述>

**错误信息**

<实际错误输出——已裁剪，无敏感信息>

EOF
)"

提交前清理可能泄露私有数据的路径/令牌。先让用户确认整理好的内容。

回退方案（gh未安装/未认证）： 提交问题的网页URL。你可以通过查询字符串预填充内容：

https://github.com/Necmttn/ax/issues/new?title=<url编码的标题>&body=<url编码的内容>

（直接使用

https://github.com/Necmttn/ax/issues/new

也可）。告知用户在浏览器中查看并提交。

3. Fork + open a PR (contribute)

3. 复刻仓库 + 提交PR（贡献代码）

For a code change. Fork+clone is account-mutating → confirm before the fork and before the PR; branching/committing locally needs no confirm.

bash

undefined

用于代码变更。复刻+克隆会更改账户 → 在复刻和提交PR前均需确认；本地分支/提交无需确认。

bash

undefined

1. Fork and clone in one step (creates a fork on the user's account):

1. 一步完成复刻和克隆（在用户账户下创建复刻仓库）：

gh repo fork Necmttn/ax --clone # confirm: this creates a fork

gh repo fork Necmttn/ax --clone # 确认：此操作会创建复刻仓库

2. From inside the clone, branch + make the change + commit:

2. 在克隆的仓库内，创建分支 + 进行修改 + 提交：

git checkout -b <topic-branch>

git checkout -b <主题分支>

...edits...

...编辑代码...

git commit -am "<conventional message>" git push -u origin <topic-branch>

git commit -am "<规范提交信息>" git push -u origin <主题分支>

3. Open the PR against upstream (confirm before sending):

3. 向上游仓库提交PR（发送前确认）：

gh pr create --repo Necmttn/ax
--title "<title>" --body "<what + why>"

gh pr create --repo Necmttn/ax
--title "<标题>" --body "<修改内容+原因>"

or interactively review in browser:

或在浏览器中交互式查看：

gh pr create --repo Necmttn/ax --web


If the user is already inside a clone of `Necmttn/ax`, skip the fork step;
`gh pr create` will offer to push to a fork automatically.

**Fallback (gh missing/unauthed):** print `https://github.com/Necmttn/ax/fork`
and tell the user to fork in the browser, then clone their fork manually.

gh pr create --repo Necmttn/ax --web


如果用户已在`Necmttn/ax`的克隆仓库内，跳过复刻步骤；
`gh pr create`会自动推送到复刻仓库。

**回退方案（gh未安装/未认证）：** 打印`https://github.com/Necmttn/ax/fork`并告知用户在浏览器中复刻仓库，然后手动克隆自己的复刻仓库。

House rules

通用规则

Show the exact
```
gh
```
command before running any mutating one; get a yes.
One action per request - don't star and file an issue unless asked for both.
Don't invent labels/milestones; omit
```
--label
```
if you're unsure it exists.
Keep issue bodies short, factual, secret-free; never paste raw transcripts.
On any
```
gh
```
failure, surface the error and offer the URL fallback - never let it abort the user's in-progress task.

在执行任何变更性命令前，显示确切的
```
gh
```
命令；获取用户同意。
每次请求执行一个操作——除非用户明确要求，否则不要同时点赞和提交问题。
不要自行添加标签/里程碑；不确定标签是否存在时省略
```
--label
```
。
问题内容应简短、真实、无敏感信息；绝不粘贴原始日志。
任何
```
gh
```
调用失败时，显示错误信息并提供URL回退方案——绝不能中断用户正在进行的任务。