opensource/CLI-Anything
3
0
Fork 0
mirror of https://github.com/HKUDS/CLI-Anything.git synced 2026-08-28 23:27:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: vendor full methodology resources for Codex skill

Browse Source
This commit is contained in:
Liuyaguang
2026-06-02 18:11:09 +08:00
parent f23e051a05
commit 31fd544c53
8 changed files with 328 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/check-codex-skill.yml
+31
View File
@@ -0,0 +1,31 @@
name: Check Codex Skill
on:
pull_request:
paths:
- 'codex-skill/**'
- 'cli-anything-plugin/**'
- 'docs/PREVIEW_PROTOCOL.md'
- '.github/workflows/check-codex-skill.yml'
push:
branches:
- main
paths:
- 'codex-skill/**'
- 'cli-anything-plugin/**'
- 'docs/PREVIEW_PROTOCOL.md'
- '.github/workflows/check-codex-skill.yml'
workflow_dispatch:
permissions:
contents: read
jobs:
test-installer:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Test Codex skill installer
run: bash codex-skill/tests/test_install.sh
README.md
+17 -1
View File
@@ -554,6 +554,11 @@ On Windows PowerShell, use:
```
This installs the skill to `$CODEX_HOME/skills/cli-anything` (or `~/.codex/skills/cli-anything` if `CODEX_HOME` is unset).
The installer also vendors the canonical `HARNESS.md`, command specifications,
on-demand guides, reusable helper scripts, skill template, and preview protocol
into the installed skill's `references/` and `scripts/` directories.
This keeps the Codex skill self-contained while using `cli-anything-plugin/` as
the source of truth.
Restart Codex after installation so it is discovered.
@@ -565,10 +570,17 @@ Describe the task in natural language, for example:
Use CLI-Anything to build a harness for ./gimp
Use CLI-Anything to refine ./shotcut for picture-in-picture workflows
Use CLI-Anything to validate ./libreoffice
Use CLI-Anything to list generated harnesses under the current directory
```
The Codex skill adapts the same methodology used by the Claude Code plugin and
OpenCode commands, while keeping the generated Python harness format unchanged.
To verify the self-contained Codex installation locally:
```bash
bash CLI-Anything/codex-skill/tests/test_install.sh
```
</details>
<details>
@@ -1338,7 +1350,11 @@ cli-anything/
│ └── scripts/
│ └── setup-cli-anything.sh # Setup script
│
├── 🤖 codex-skill/ # Codex skill entry point
├── 🤖 codex-skill/ # Self-contained Codex skill installer
│ ├── SKILL.md # Codex workflow entry point
│ ├── agents/ # Codex UI metadata
│ ├── scripts/ # Bash and PowerShell installers
│ └── tests/ # Installer resource-sync regression test
├── 🧭 hermes-skill/ # Hermes Agent skill entry point
├── 🎨 gimp/agent-harness/ # GIMP CLI (107 tests)
├── 🧊 blender/agent-harness/ # Blender CLI (208 tests)
README_CN.md
+13 -1
View File
@@ -278,6 +278,7 @@ bash CLI-Anything/codex-skill/scripts/install.sh
```
脚本会把 skill 安装到 `$CODEX_HOME/skills/cli-anything`；如果没有设置 `CODEX_HOME`，则默认安装到 `~/.codex/skills/cli-anything`。
安装器还会把权威版本的 `HARNESS.md`、命令规范、按需指南、可复用辅助脚本、skill 模板和 preview 协议复制到已安装 skill 的 `references/`、`scripts/` 和 `assets/` 目录。这样 Codex skill 可以独立工作，同时仍以 `cli-anything-plugin/` 作为唯一权威来源。
安装后重启 Codex，让它重新发现这个 skill。
@@ -289,11 +290,18 @@ bash CLI-Anything/codex-skill/scripts/install.sh
Use CLI-Anything to build a harness for ./gimp
Use CLI-Anything to refine ./shotcut for picture-in-picture workflows
Use CLI-Anything to validate ./libreoffice
Use CLI-Anything to list generated harnesses under the current directory
```
这个 Codex skill 复用了 Claude Code 插件和 OpenCode 命令所使用的同一套方法论，
不会改变生成出来的 Python harness 结构。
可以运行下面的命令，验证 Codex 安装包是否完整：
```bash
bash CLI-Anything/codex-skill/tests/test_install.sh
```
</details>
<details>
@@ -741,7 +749,11 @@ cli-anything/
│ ├── cli-anything-validate.md # 标准验证
│ └── cli-anything-list.md # 列出所有 CLI 工具
│
├── 🤖 codex-skill/ # Codex skill 接入层
├── 🤖 codex-skill/ # 可独立安装的 Codex skill
│ ├── SKILL.md # Codex 工作流入口
│ ├── agents/ # Codex 界面元数据
│ ├── scripts/ # Bash 和 PowerShell 安装器
│ └── tests/ # 安装资源同步回归测试
├── 🎨 gimp/agent-harness/ # GIMP CLI（107 项测试）
├── 🧊 blender/agent-harness/ # Blender CLI（208 项测试）
├── ✏️ inkscape/agent-harness/ # Inkscape CLI（202 项测试）
codex-skill/SKILL.md
+100 -56
View File
@@ -1,13 +1,57 @@
---
name: cli-anything
description: Use when the user wants Codex to build, refine, test, or validate a CLI-Anything harness for a GUI application or source repository. Adapts the CLI-Anything methodology to Codex without changing the generated Python harness format.
description: Use when the user wants Codex to build, refine, test, validate, or list CLI-Anything harnesses for GUI applications or source repositories. Adapts the full CLI-Anything methodology to Codex without changing the generated Python harness format.
---
# CLI-Anything for Codex
Use this skill when the user wants Codex to act like the `CLI-Anything` builder.
If this skill is being used from inside the `CLI-Anything` repository, read `../cli-anything-plugin/HARNESS.md` before implementation. That file is the full methodology source of truth. If it is not available, follow the condensed rules below.
## Read the Full Methodology First
Before implementation, use the full methodology source of truth:
1. Read `references/HARNESS.md` relative to this skill directory.
2. Read the matching mode specification under `references/commands/`.
3. Read referenced files under `references/guides/` only when they apply to the target.
4. If the installed resources are unavailable and this skill is being used from a
`CLI-Anything` repository checkout, read `../cli-anything-plugin/HARNESS.md` and
the resources around it.
5. If neither local source is available, clone or download
`https://github.com/HKUDS/CLI-Anything` and use `cli-anything-plugin/HARNESS.md`.
6. Only if all full-methodology sources are unavailable, follow the condensed rules below.
The installer vendors the canonical resources from `cli-anything-plugin/` into this
skill so a normal Codex installation is self-contained.
## Resource Map
| Path | Purpose |
|------|---------|
| `references/HARNESS.md` | Complete methodology and quality rules |
| `references/commands/cli-anything.md` | Build-mode specification |
| `references/commands/refine.md` | Refine-mode specification |
| `references/commands/test.md` | Test-mode specification |
| `references/commands/validate.md` | Validation checklist |
| `references/commands/list.md` | Installed/generated harness discovery |
| `references/guides/` | On-demand implementation guidance |
| `scripts/repl_skin.py` | Copy into generated harnesses as `utils/repl_skin.py` |
| `scripts/preview_bundle.py` | Copy into preview-capable harnesses as `utils/preview_bundle.py` |
| `scripts/skill_generator.py` | Generate canonical and packaged CLI skills |
| `assets/SKILL.md.template` | Skill generation template |
| `references/docs/PREVIEW_PROTOCOL.md` | Shared preview bundle protocol |
When reading vendored documents, apply these path remappings instead of resolving
plugin paths against the current working directory:
| Document reference | Installed skill path |
|--------------------|----------------------|
| `guides/...` | `references/guides/...` |
| `cli-anything-plugin/repl_skin.py` | `scripts/repl_skin.py` |
| `cli-anything-plugin/preview_bundle.py` | `scripts/preview_bundle.py` |
| `cli-anything-plugin/skill_generator.py` | `scripts/skill_generator.py` |
| `templates/SKILL.md.template` | `assets/SKILL.md.template` |
| `docs/PREVIEW_PROTOCOL.md` | `references/docs/PREVIEW_PROTOCOL.md` |
## Inputs
@@ -22,9 +66,39 @@ Derive the software name from the local directory name after cloning if needed.
### Build
Use when the user wants a new harness.
Read `references/commands/cli-anything.md`. Build a complete harness through source
analysis, architecture design, implementation, test planning, test implementation,
test documentation, CLI-specific `SKILL.md` generation, and local installation.
Produce this structure:
### Refine
Read `references/commands/refine.md`. Inventory current commands and tests, compare
them against the target software, then incrementally add high-impact capabilities
without removing existing commands unless the user requests a breaking change.
### Test
Read `references/commands/test.md`. Run the harness tests against the real backend,
verify installed-command subprocess coverage, and update `TEST.md` only with passing
results.
### Validate
Read `references/commands/validate.md`. Validate the harness against the complete
directory, implementation, test, documentation, packaging, and code-quality checklist.
### List
Read `references/commands/list.md`. Discover installed and generated CLI-Anything tools
and support human-readable or JSON output as requested.
## Condensed Fallback Rules
Use these only when the full methodology cannot be retrieved.
### Harness Structure
Produce:
```text
<software>/
@@ -42,63 +116,33 @@ Produce this structure:
└── tests/
```
Implement a stateful Click CLI with:
### Required Behavior
- one-shot subcommands
- REPL mode as the default when no subcommand is given
- `--json` machine-readable output
- session state with undo/redo where the target software supports it
- Prefer the real software backend over reimplementation.
- Provide one-shot Click subcommands and default REPL mode.
- Support `--json` machine-readable output.
- Add session state with undo/redo where the target supports it.
- Auto-save one-shot session mutations and support `--dry-run`.
- Use locked session-file writes to avoid concurrent JSON corruption.
- Copy and use the unified `ReplSkin`.
- Add truthful preview commands for software with meaningful visual or inspection state.
- Generate both canonical and packaged CLI-specific `SKILL.md` files.
### Refine
### Testing
Use when the harness already exists.
- Write `TEST.md` before test code.
- Keep `test_core.py` for unit coverage.
- Keep `test_full_e2e.py` for real-file workflows and real backend validation.
- Verify rendered/exported output programmatically, not only process exit codes.
- Test the installed `cli-anything-<software>` command via `_resolve_cli()`.
- Run release validation with `CLI_ANYTHING_FORCE_INSTALLED=1`.
First inventory current commands and tests, then do gap analysis against the target software. Prefer:
### Packaging
- high-impact missing features
- easy wrappers around existing backend APIs or CLIs
- additions that compose well with existing commands
Do not remove existing commands unless the user explicitly asks for a breaking change.
### Test
Plan tests before writing them. Keep both:
- `test_core.py` for unit coverage
- `test_full_e2e.py` for workflow and backend validation
When possible, test the installed command via subprocess using `cli-anything-<software>` rather than only module imports.
### Validate
Check that the harness:
- uses the `cli_anything.<software>` namespace package layout
- has an installable `setup.py` entry point
- supports JSON output
- has a REPL default path
- documents usage and tests
## Backend Rules
Prefer the real software backend over reimplementation. Wrap the actual executable or scripting interface in `utils/<software>_backend.py` when possible. Use synthetic reimplementation only when the project explicitly requires it or no viable native backend exists.
## Packaging Rules
- Use `find_namespace_packages(include=["cli_anything.*"])`
- Keep `cli_anything/` as a namespace package without a top-level `__init__.py`
- Expose `cli-anything-<software>` through `console_scripts`
## Workflow
1. Acquire the source tree locally.
2. Analyze architecture, data model, existing CLIs, and GUI-to-API mappings.
3. Design command groups and state model.
4. Implement the harness.
5. Write `TEST.md`, then tests, then run them.
6. Update README usage docs.
7. Verify local installation with `pip install -e .`
- Use `find_namespace_packages(include=["cli_anything.*"])`.
- Keep `cli_anything/` as a namespace package without a top-level `__init__.py`.
- Expose `cli-anything-<software>` through `console_scripts`.
- Include the packaged CLI-specific `skills/SKILL.md`.
## Output Expectations
codex-skill/agents/openai.yaml
+2 -2
View File
@@ -1,4 +1,4 @@
interface:
display_name: "CLI-Anything"
short_description: "Build or refine CLI-Anything harnesses from Codex."
default_prompt: "Use CLI-Anything to build, refine, test, or validate a harness for the user's target software or source repository."
short_description: "Build, refine, test, validate, or list harnesses."
default_prompt: "Use $cli-anything to build, refine, test, validate, or list harnesses for the user's target software or source repository."
codex-skill/scripts/install.ps1
+41 -2
View File
@@ -2,6 +2,9 @@ $ErrorActionPreference = "Stop"
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$skillDir = Split-Path -Parent $scriptDir
$repoRoot = Split-Path -Parent $skillDir
$pluginDir = Join-Path $repoRoot "cli-anything-plugin"
$previewProtocol = Join-Path $repoRoot "docs/PREVIEW_PROTOCOL.md"
$codexHome = if ($env:CODEX_HOME) {
$env:CODEX_HOME
@@ -13,14 +16,50 @@ $codexHome = if ($env:CODEX_HOME) {
$destRoot = Join-Path $codexHome "skills"
$destDir = Join-Path $destRoot "cli-anything"
$stagingDir = Join-Path $destRoot ".cli-anything.tmp.$PID"
if (-not (Test-Path (Join-Path $pluginDir "HARNESS.md"))) {
throw "Cannot find canonical CLI-Anything resources at: $pluginDir`nRun this installer from a full CLI-Anything repository checkout."
}
if (-not (Test-Path $previewProtocol)) {
throw "Cannot find preview protocol at: $previewProtocol`nRun this installer from a full CLI-Anything repository checkout."
}
New-Item -ItemType Directory -Path $destRoot -Force | Out-Null
if (Test-Path $destDir) {
Write-Error "Refusing to overwrite existing skill: $destDir`nRemove it manually if you want to reinstall."
throw "Refusing to overwrite existing skill: $destDir`nRemove it manually if you want to reinstall."
}
Copy-Item -Path $skillDir -Destination $destDir -Recurse
try {
Copy-Item -Path $skillDir -Destination $stagingDir -Recurse
$assetDir = Join-Path $stagingDir "assets"
$referenceDir = Join-Path $stagingDir "references"
$referenceCommands = Join-Path $referenceDir "commands"
$referenceDocs = Join-Path $referenceDir "docs"
$referenceGuides = Join-Path $referenceDir "guides"
$resourceScripts = Join-Path $stagingDir "scripts"
New-Item -ItemType Directory -Path $assetDir, $referenceCommands, $referenceDocs, $referenceGuides, $resourceScripts -Force | Out-Null
Copy-Item -Path (Join-Path $pluginDir "HARNESS.md") -Destination (Join-Path $referenceDir "HARNESS.md")
Copy-Item -Path (Join-Path $pluginDir "commands/*.md") -Destination $referenceCommands
Copy-Item -Path (Join-Path $pluginDir "guides/*.md") -Destination $referenceGuides
Copy-Item -Path (Join-Path $pluginDir "repl_skin.py") -Destination (Join-Path $resourceScripts "repl_skin.py")
Copy-Item -Path (Join-Path $pluginDir "preview_bundle.py") -Destination (Join-Path $resourceScripts "preview_bundle.py")
Copy-Item -Path (Join-Path $pluginDir "skill_generator.py") -Destination (Join-Path $resourceScripts "skill_generator.py")
Copy-Item -Path (Join-Path $pluginDir "templates/*") -Destination $assetDir
Copy-Item -Path $previewProtocol -Destination (Join-Path $referenceDocs "PREVIEW_PROTOCOL.md")
Move-Item -Path $stagingDir -Destination $destDir
} finally {
if (Test-Path $stagingDir) {
Remove-Item -Path $stagingDir -Recurse -Force
}
}
Write-Host "Installed Codex skill to: $destDir"
Write-Host "Vendored CLI-Anything methodology resources into the installed skill."
Write-Host "Restart Codex to pick up the new skill."
codex-skill/scripts/install.sh
+40 -1
View File
@@ -4,8 +4,24 @@ set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)"
PLUGIN_DIR="${REPO_ROOT}/cli-anything-plugin"
PREVIEW_PROTOCOL="${REPO_ROOT}/docs/PREVIEW_PROTOCOL.md"
DEST_ROOT="${CODEX_HOME:-$HOME/.codex}/skills"
DEST_DIR="${DEST_ROOT}/cli-anything"
STAGING_DIR="${DEST_ROOT}/.cli-anything.tmp.$$"
if [[ ! -f "${PLUGIN_DIR}/HARNESS.md" ]]; then
echo "Cannot find canonical CLI-Anything resources at: ${PLUGIN_DIR}" >&2
echo "Run this installer from a full CLI-Anything repository checkout." >&2
exit 1
fi
if [[ ! -f "${PREVIEW_PROTOCOL}" ]]; then
echo "Cannot find preview protocol at: ${PREVIEW_PROTOCOL}" >&2
echo "Run this installer from a full CLI-Anything repository checkout." >&2
exit 1
fi
mkdir -p "${DEST_ROOT}"
@@ -15,7 +31,30 @@ if [[ -e "${DEST_DIR}" ]]; then
exit 1
fi
cp -R "${SKILL_DIR}" "${DEST_DIR}"
cleanup() {
rm -rf "${STAGING_DIR}"
}
trap cleanup EXIT
cp -R "${SKILL_DIR}" "${STAGING_DIR}"
mkdir -p \
"${STAGING_DIR}/assets" \
"${STAGING_DIR}/references/commands" \
"${STAGING_DIR}/references/docs" \
"${STAGING_DIR}/references/guides" \
"${STAGING_DIR}/scripts"
cp "${PLUGIN_DIR}/HARNESS.md" "${STAGING_DIR}/references/HARNESS.md"
cp "${PLUGIN_DIR}/commands/"*.md "${STAGING_DIR}/references/commands/"
cp "${PLUGIN_DIR}/guides/"*.md "${STAGING_DIR}/references/guides/"
cp "${PLUGIN_DIR}/repl_skin.py" "${STAGING_DIR}/scripts/repl_skin.py"
cp "${PLUGIN_DIR}/preview_bundle.py" "${STAGING_DIR}/scripts/preview_bundle.py"
cp "${PLUGIN_DIR}/skill_generator.py" "${STAGING_DIR}/scripts/skill_generator.py"
cp "${PLUGIN_DIR}/templates/"* "${STAGING_DIR}/assets/"
cp "${PREVIEW_PROTOCOL}" "${STAGING_DIR}/references/docs/PREVIEW_PROTOCOL.md"
mv "${STAGING_DIR}" "${DEST_DIR}"
echo "Installed Codex skill to: ${DEST_DIR}"
echo "Vendored CLI-Anything methodology resources into the installed skill."
echo "Restart Codex to pick up the new skill."
codex-skill/tests/test_install.sh
Executable
+84
View File
@@ -0,0 +1,84 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)"
PLUGIN_DIR="${REPO_ROOT}/cli-anything-plugin"
TMP_DIR="$(mktemp -d)"
CODEX_HOME="${TMP_DIR}/codex-home"
INSTALLED_DIR="${CODEX_HOME}/skills/cli-anything"
cleanup() {
rm -rf "${TMP_DIR}"
}
trap cleanup EXIT
fail() {
echo "FAIL: $*" >&2
exit 1
}
assert_file() {
[[ -f "$1" ]] || fail "expected file: $1"
}
assert_same() {
cmp -s "$1" "$2" || fail "files differ: $1 $2"
}
assert_tree_same() {
diff -qr "$1" "$2" >/dev/null || fail "directories differ: $1 $2"
}
CODEX_HOME="${CODEX_HOME}" bash "${SKILL_DIR}/scripts/install.sh"
assert_file "${INSTALLED_DIR}/SKILL.md"
assert_file "${INSTALLED_DIR}/references/HARNESS.md"
assert_file "${INSTALLED_DIR}/references/commands/cli-anything.md"
assert_file "${INSTALLED_DIR}/references/commands/refine.md"
assert_file "${INSTALLED_DIR}/references/commands/test.md"
assert_file "${INSTALLED_DIR}/references/commands/validate.md"
assert_file "${INSTALLED_DIR}/references/commands/list.md"
assert_file "${INSTALLED_DIR}/references/guides/auto-save-dry-run.md"
assert_file "${INSTALLED_DIR}/references/guides/session-locking.md"
assert_file "${INSTALLED_DIR}/references/guides/preview-methodology.md"
assert_file "${INSTALLED_DIR}/scripts/repl_skin.py"
assert_file "${INSTALLED_DIR}/scripts/preview_bundle.py"
assert_file "${INSTALLED_DIR}/scripts/skill_generator.py"
assert_file "${INSTALLED_DIR}/assets/SKILL.md.template"
assert_file "${INSTALLED_DIR}/references/docs/PREVIEW_PROTOCOL.md"
assert_same "${PLUGIN_DIR}/HARNESS.md" "${INSTALLED_DIR}/references/HARNESS.md"
assert_same "${PLUGIN_DIR}/repl_skin.py" "${INSTALLED_DIR}/scripts/repl_skin.py"
assert_same "${PLUGIN_DIR}/preview_bundle.py" "${INSTALLED_DIR}/scripts/preview_bundle.py"
assert_same "${PLUGIN_DIR}/skill_generator.py" "${INSTALLED_DIR}/scripts/skill_generator.py"
assert_same "${REPO_ROOT}/docs/PREVIEW_PROTOCOL.md" "${INSTALLED_DIR}/references/docs/PREVIEW_PROTOCOL.md"
assert_tree_same "${PLUGIN_DIR}/commands" "${INSTALLED_DIR}/references/commands"
assert_tree_same "${PLUGIN_DIR}/guides" "${INSTALLED_DIR}/references/guides"
assert_tree_same "${PLUGIN_DIR}/templates" "${INSTALLED_DIR}/assets"
python3 -m py_compile \
"${INSTALLED_DIR}/scripts/repl_skin.py" \
"${INSTALLED_DIR}/scripts/preview_bundle.py" \
"${INSTALLED_DIR}/scripts/skill_generator.py"
if CODEX_HOME="${CODEX_HOME}" bash "${SKILL_DIR}/scripts/install.sh" >/dev/null 2>&1; then
fail "installer overwrote an existing skill"
fi
grep -q 'references/HARNESS.md' "${INSTALLED_DIR}/SKILL.md" ||
fail "installed SKILL.md does not point to vendored HARNESS.md"
DETACHED_ROOT="${TMP_DIR}/detached"
DETACHED_LOG="${TMP_DIR}/detached-install.log"
mkdir -p "${DETACHED_ROOT}"
cp -R "${SKILL_DIR}" "${DETACHED_ROOT}/codex-skill"
if CODEX_HOME="${TMP_DIR}/detached-home" bash "${DETACHED_ROOT}/codex-skill/scripts/install.sh" >"${DETACHED_LOG}" 2>&1; then
fail "installer accepted a detached skill without canonical resources"
fi
grep -q 'Cannot find canonical CLI-Anything resources' "${DETACHED_LOG}" ||
fail "detached install did not explain the missing canonical resources"
echo "PASS: Codex skill installer vendors the complete CLI-Anything resource set."