apaam/myagents
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(completion): 自动安装 myagents/myclaude/mykimi shell 补全，移除 eval 旧脚本

Browse Source
This commit is contained in:
Zhengshou Lai
2026-07-04 19:25:01 +08:00
parent 7f1aa9f27e
commit 20e7eba93b
8 changed files with 373 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+8 -16
View File
@@ -2,15 +2,15 @@ ROOT_DIR := $(shell pwd)
VENV_BIN_DIR := $(ROOT_DIR)/.venv/bin
USER_BIN_DIR := $(HOME)/.local/bin
COMMANDS := myagents myclaude mykimi
COMP_DIR := $(HOME)/.local/bin/completions
.PHONY: help install uninstall _symlink-commands _install-completions _uninstall-completions
.PHONY: help install uninstall _symlink-commands
help:
@echo "Usage: make [target]"
@echo ""
@echo " install Sync venv, symlink bin, install completions"
@echo " uninstall Remove bin and completions"
@echo " install Sync venv, symlink bin, install shell completions"
@echo " uninstall Remove bin, completions and user symlinks"
install:
@cd "$(ROOT_DIR)" && \
if command -v uv >/dev/null 2>&1; then \
@@ -20,7 +20,8 @@ install:
PIP_USER=0 .venv/bin/pip install -e .; \
fi
@$(MAKE) _symlink-commands
@$(MAKE) _install-completions
@echo "Installing shell completions…"
@myagents completion install || echo "Warning: completion install failed"
_symlink-commands:
@mkdir -p "$(USER_BIN_DIR)"
@@ -32,15 +33,6 @@ _symlink-commands:
echo "Linked $$dst -> $$src"; \
done
_install-completions:
@$(ROOT_DIR)/scripts/install_completion.sh "$(VENV_BIN_DIR)" "$(COMP_DIR)"
uninstall: _uninstall-completions
uninstall:
@myagents completion uninstall || true
@ROOT_DIR="$(ROOT_DIR)" python3 "$(ROOT_DIR)/scripts/rm_user_local_myagents.py"
_uninstall-completions:
@rm -f \
"$(COMP_DIR)/_myagents" "$(COMP_DIR)/myagents.bash" \
"$(COMP_DIR)/_myclaude" "$(COMP_DIR)/myclaude.bash" \
"$(COMP_DIR)/_mykimi" "$(COMP_DIR)/mykimi.bash"
@echo "Removed completions"
README.md
+18 -14
View File
@@ -49,9 +49,24 @@ make install
`make install` 会：
1. 同步/创建虚拟环境并做可编辑安装
2. 在 `~/.local/bin/` 创建 `myagents`、`myclaude`、`mykimi` 符号链接
3. 安装 shell 补全（zsh/bash）
3. 自动安装 shell 补全到 `~/.local/share/zsh/site-functions` 和 `~/.local/share/bash-completion/completions`
请确保 `~/.local/bin` 在 `PATH` 中。移除链接：`make uninstall`。
请确保 `~/.local/bin` 在 `PATH` 中，并在 `~/.zshrc` 里加上：
```bash
fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -Uz compinit && compinit
```
移除链接与补全：`make uninstall`。
首次运行任意 `myagents` / `myclaude` / `mykimi` 命令时，若补全缺失会自动补齐。也可以手动管理：
```bash
myagents completion doctor # 查看补全状态
myagents completion install # 手动重装补全
myagents completion zsh # 打印 zsh 补全脚本
```
> 💡 **提示**：没有 uv 时会创建项目 `.venv` 并用其中的 pip 做可编辑安装。
@@ -68,6 +83,7 @@ myagents kimi # 启动 Kimi Code CLI
myagents kimi -S <session-id> # 恢复 Kimi session
myagents update # 重装 myagents 并同步 workspace 链接
myagents upgrade # update 别名
myagents completion # 安装/查看/卸载 shell 补全
# 独立入口（与上面完全等价）
myclaude
@@ -91,18 +107,6 @@ mykimi -S <session-id>
export MYAGENTS_WORKSPACE_ROOT="/your/custom/workspace"
```
## Shell 补全（可选）
在 `~/.zshrc` 或 `~/.bashrc` 中加入：
```bash
if command -v myagents >/dev/null 2>&1; then
eval "$(_MYAGENTS_COMPLETE=zsh_source myagents)"
fi
```
Bash 将 `zsh_source` 换成 `bash_source`。保存后 `source` 配置文件。
## 开发
```bash
myagents/cli.py
+16
View File
@@ -5,9 +5,21 @@ from importlib.metadata import PackageNotFoundError, version
import click
from myagents.commands import update_cmd, upgrade_cmd
from myagents.commands.completion import build_completion_group
from myagents.launcher import build_cli
def _progs():
"""Return (prog_name, cli_factory) pairs that need shell completions."""
from myagents.entrypoints import claude_cli, kimi_cli
return [
("myagents", lambda: cli),
("myclaude", lambda: claude_cli),
("mykimi", lambda: kimi_cli),
]
def _package_version() -> str:
try:
return version("myagents")
@@ -32,9 +44,13 @@ cli.add_command(build_cli("claude"), name="claude")
cli.add_command(build_cli("kimi"), name="kimi")
cli.add_command(update_cmd)
cli.add_command(upgrade_cmd, name="upgrade")
cli.add_command(build_completion_group(_progs))
def main() -> None:
from myagents.commands.completion_install import ensure_completions_installed
ensure_completions_installed(_progs())
cli()
myagents/commands/completion.py
+92
View File
@@ -0,0 +1,92 @@
"""Shell tab-completion CLI for myagents."""
from __future__ import annotations
import sys
from typing import Protocol
import click
from click.shell_completion import get_completion_class
from myagents.commands.completion_install import (
ProgList,
install_completions,
run_completion_doctor,
uninstall_completions,
)
class ProgListFn(Protocol):
def __call__(self) -> ProgList: ...
def _print_script(prog_name: str, shell: str) -> None:
"""Print the completion script for one prog/shell pair."""
# Import the requested CLI object on demand to avoid circular imports.
if prog_name == "myagents":
from myagents.cli import cli
cli_obj = cli
elif prog_name == "myclaude":
from myagents.entrypoints import claude_cli
cli_obj = claude_cli
elif prog_name == "mykimi":
from myagents.entrypoints import kimi_cli
cli_obj = kimi_cli
else:
raise click.ClickException(f"Unknown command: {prog_name}")
shell_class = get_completion_class(shell)
if shell_class is None:
raise click.ClickException(f"Unsupported shell: {shell}")
complete_var = f"_{prog_name.upper()}_COMPLETE"
comp = shell_class(cli_obj, {}, prog_name, complete_var)
script = comp.source()
if not script.endswith("\n"):
script += "\n"
sys.stdout.write(script)
def build_completion_group(progs_fn: ProgListFn) -> click.Group:
@click.group(name="completion", help="Install or inspect shell tab-completion scripts.")
def completion() -> None:
pass
@completion.command("install")
def install_cmd() -> None:
"""Write completion scripts for myagents, myclaude and mykimi."""
installed = install_completions(progs_fn())
if not installed:
raise click.ClickException(
"No completion files were written (directory not writable?)."
)
for path in installed:
click.echo(path)
@completion.command("uninstall")
def uninstall_cmd() -> None:
"""Remove completion scripts."""
removed = uninstall_completions(progs_fn())
for path in removed:
click.echo(path)
if not removed:
click.echo("(nothing to remove)")
@completion.command("doctor")
def doctor_cmd() -> None:
"""Report completion install state."""
run_completion_doctor(progs_fn())
for shell in ("bash", "zsh"):
@completion.command(
name=shell,
help=f"Print the {shell} completion script for a command.",
)
@click.argument("command", default="myagents")
def print_shell(command: str, shell_name: str = shell) -> None:
_print_script(command, shell_name)
return completion
myagents/commands/completion_install.py
+213
View File
@@ -0,0 +1,213 @@
"""Install shell tab-completion files for myagents entrypoints.
Completions are written to the user's XDG data directory by default
(``~/.local/share``), which keeps them independent of the active venv path.
"""
from __future__ import annotations
import os
import shlex
import subprocess
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, Sequence
import click
from click.shell_completion import get_completion_class
ProgList = Sequence[tuple[str, Callable[[], click.Command]]]
MANIFEST_FILENAME = "completion-paths.txt"
def _default_install_root() -> Path:
data_home = os.environ.get("XDG_DATA_HOME")
if data_home:
return Path(data_home)
return Path.home() / ".local" / "share"
@dataclass(frozen=True)
class CompletionTarget:
shell: str
prog_name: str
path: Path
@property
def installed(self) -> bool:
return self.path.is_file()
def completion_targets(
prog_name: str,
*,
install_root: Path | None = None,
) -> list[CompletionTarget]:
root = install_root or _default_install_root()
return [
CompletionTarget(
"zsh",
prog_name,
root / "zsh" / "site-functions" / f"_{prog_name}",
),
CompletionTarget(
"bash",
prog_name,
root / "bash-completion" / "completions" / prog_name,
),
]
def _completion_script(cli: click.Command, shell: str, prog_name: str) -> str:
shell_class = get_completion_class(shell)
if shell_class is None:
raise ValueError(f"unsupported shell for completion: {shell}")
comp = shell_class(cli, {}, prog_name, f"_{prog_name.upper()}_COMPLETE")
script = comp.source()
if not script.endswith("\n"):
script += "\n"
return script
def _all_targets(
progs: ProgList,
install_root: Path | None,
) -> list[CompletionTarget]:
targets: list[CompletionTarget] = []
for prog_name, _ in progs:
targets.extend(completion_targets(prog_name, install_root=install_root))
return targets
def install_completions(
progs: ProgList,
*,
install_root: Path | None = None,
) -> list[Path]:
"""Write completion scripts for all progs and return installed paths."""
scripts: dict[tuple[str, str], str] = {}
for prog_name, cli_factory in progs:
cli = cli_factory()
for shell in ("zsh", "bash"):
scripts[(prog_name, shell)] = _completion_script(cli, shell, prog_name)
installed: list[Path] = []
for target in _all_targets(progs, install_root):
try:
target.path.parent.mkdir(parents=True, exist_ok=True)
except OSError:
continue
if not os.access(target.path.parent, os.W_OK):
continue
target.path.write_text(
scripts[(target.prog_name, target.shell)],
encoding="utf-8",
)
installed.append(target.path)
return installed
def uninstall_completions(
progs: ProgList,
*,
install_root: Path | None = None,
) -> list[Path]:
"""Remove completion scripts for all progs and return removed paths."""
removed: list[Path] = []
seen: set[Path] = set()
for target in _all_targets(progs, install_root):
if target.path in seen:
continue
seen.add(target.path)
if target.path.is_file():
target.path.unlink()
removed.append(target.path)
return removed
def completions_installed(
progs: ProgList,
*,
install_root: Path | None = None,
) -> bool:
"""Check whether the zsh completion for the first prog is current."""
if not progs:
return True
prog_name, _ = progs[0]
for target in completion_targets(prog_name, install_root=install_root):
if target.shell == "zsh" and target.installed:
marker = f"_{prog_name.upper()}_COMPLETE"
if marker in target.path.read_text(encoding="utf-8"):
return True
return False
def ensure_completions_installed(
progs: ProgList,
) -> None:
"""Install completions once if they are missing."""
if completions_installed(progs):
return
try:
install_completions(progs)
except (OSError, ValueError):
return
def _in_zsh_fpath(zsh_dir: Path) -> bool:
"""Check whether ``zsh_dir`` is on the interactive zsh fpath."""
try:
check = subprocess.run(
[
"zsh",
"-c",
f"source ~/.zshrc >/dev/null 2>&1; "
f"[[ -n ${{fpath[(r){shlex.quote(str(zsh_dir))}]}} ]] && echo yes",
],
capture_output=True,
text=True,
check=False,
)
return "yes" in check.stdout
except (OSError, subprocess.SubprocessError):
return True
def run_completion_doctor(progs: ProgList) -> None:
"""Report completion install state."""
install_root = _default_install_root()
click.echo(click.style("Install root", bold=True) + f": {install_root}")
click.echo()
click.echo(click.style("Completion scripts", fg="blue", bold=True))
for prog_name, _ in progs:
for target in completion_targets(prog_name):
marker = f"_{prog_name.upper()}_COMPLETE"
if target.installed and marker in target.path.read_text(encoding="utf-8"):
status = click.style("ok", fg="green")
elif target.installed:
status = click.style("stale", fg="yellow")
else:
status = click.style("missing", fg="red")
click.echo(f" {target.shell:5} {target.prog_name:10} {target.path} [{status}]")
click.echo()
zsh_dir = install_root / "zsh" / "site-functions"
if zsh_dir.is_dir() and not _in_zsh_fpath(zsh_dir):
click.echo(
click.style("Zsh", fg="yellow", bold=True)
+ f": add to fpath if Tab does not work:\n fpath=({zsh_dir} $fpath)"
)
click.echo()
if not completions_installed(progs):
click.echo(
click.style("Fix", fg="yellow", bold=True)
+ ": run `myagents completion install` or reinstall the package."
)
return
click.echo(click.style("Completions are installed.", fg="green", bold=True))
myagents/entrypoints.py
+16
View File
@@ -6,11 +6,27 @@ claude_cli = build_cli("claude", prog_name="myclaude")
kimi_cli = build_cli("kimi", prog_name="mykimi")
def _progs():
from myagents.cli import cli
return [
("myagents", lambda: cli),
("myclaude", lambda: claude_cli),
("mykimi", lambda: kimi_cli),
]
def claude_main() -> None:
"""Run ``myclaude``."""
from myagents.commands.completion_install import ensure_completions_installed
ensure_completions_installed(_progs())
claude_cli()
def kimi_main() -> None:
"""Run ``mykimi``."""
from myagents.commands.completion_install import ensure_completions_installed
ensure_completions_installed(_progs())
kimi_cli()
scripts/install_completion.sh
-64
View File
@@ -1,64 +0,0 @@
#!/bin/bash
# Install shell completions for myagents, myclaude, mykimi to user directory only
# Usage: install_completion.sh <venv_bin_dir> <comp_dir>
VENV_BIN_DIR="$1"
COMP_DIR="$2"
if [[ -z "$VENV_BIN_DIR" || -z "$COMP_DIR" ]]; then
echo "Usage: $0 <venv_bin_dir> <comp_dir>" >&2
exit 1
fi
USER_SHELL=$(basename "$SHELL")
# Portable uppercase helper (macOS bash 3.2 lacks ${var^^}).
_upcase() {
printf '%s' "$1" | tr '[:lower:]' '[:upper:]'
}
install_zsh_completion() {
local cmd="$1"
local out="$2"
local var="_$(_upcase "$cmd")_COMPLETE"
mkdir -p "$COMP_DIR" 2>/dev/null || { echo "Error: cannot create $COMP_DIR" >&2; return 1; }
if eval "$var=zsh_source ${VENV_BIN_DIR}/${cmd}" > "$out" 2>/dev/null; then
echo "Installed zsh completion: $out"
return 0
else
echo "Warning: failed to generate zsh completion for $cmd" >&2
return 1
fi
}
install_bash_completion() {
local cmd="$1"
local out="$2"
local var="_$(_upcase "$cmd")_COMPLETE"
mkdir -p "$COMP_DIR" 2>/dev/null || { echo "Error: cannot create $COMP_DIR" >&2; return 1; }
if eval "$var=bash_source ${VENV_BIN_DIR}/${cmd}" > "$out" 2>/dev/null; then
echo "Installed bash completion: $out"
return 0
else
echo "Warning: failed to generate bash completion for $cmd" >&2
return 1
fi
}
if [[ "$USER_SHELL" == "zsh" ]]; then
install_zsh_completion myagents "$COMP_DIR/_myagents"
install_zsh_completion myclaude "$COMP_DIR/_myclaude"
install_zsh_completion mykimi "$COMP_DIR/_mykimi"
elif [[ "$USER_SHELL" == "bash" ]]; then
install_bash_completion myagents "$COMP_DIR/myagents.bash"
install_bash_completion myclaude "$COMP_DIR/myclaude.bash"
install_bash_completion mykimi "$COMP_DIR/mykimi.bash"
else
echo "Shell '$USER_SHELL' is not supported for automatic completion installation."
echo "To install completions manually, run one of the following commands:"
for cmd in myagents myclaude mykimi; do
var="_$(_upcase "$cmd")_COMPLETE"
echo " zsh: $var=zsh_source ${VENV_BIN_DIR}/${cmd} > /path/to/completions/_${cmd}"
echo " bash: $var=bash_source ${VENV_BIN_DIR}/${cmd} > /path/to/completions/${cmd}.bash"
done
fi
scripts/rm_user_local_myagents.py
+10
View File
@@ -43,6 +43,16 @@ def main() -> int:
print("Skip:", link, "is not a symlink, leaving untouched")
skipped += 1
# Clean up legacy completion files from the old manual install location.
legacy_comp_dir = os.path.expanduser("~/.local/bin/completions")
for command in _COMMANDS:
for filename in (f"_{command}", f"{command}.bash"):
path = os.path.join(legacy_comp_dir, filename)
if os.path.isfile(path):
os.unlink(path)
print("Removed legacy completion", path)
removed += 1
if removed == 0 and skipped == 0:
print("Nothing to remove")
return 0