prismfy-wizard｜为本地 AI 编码代理安装 Prismfy 实时搜索命令与搜索规则

access：来源确认 · npx prismfy-wizard setup --root /path/to/project

project_type：来源确认 · It installs a local `prismfy-search` command and injects a managed Prismfy block that tells agents when to use live web search.

# Prismfy Wizard

Give local AI agents a default live web search path.

`prismfy-wizard` is a CLI for developers using agent tools that read local instruction files such as `AGENTS.md`, `CLAUDE.md`, Cursor/Windsurf rules, Copilot instructions, and similar repo-level or home-level agent config. It installs a local `prismfy-search` command and injects a managed Prismfy block that tells agents when to use live web search.

It does not control model behavior at runtime. It changes the local instructions and helper files your agents already use.

Prismfy itself is a web search API for AI agents and automated workflows.

This project is for people who want local agents to stop treating web search like an optional extra. Instead of only exposing a tool, Prismfy Wizard installs the command and the rule that tells the agent when to use it.

## Quick Start

Try the safe path first:

```bash
npx prismfy-wizard scan --root /path/to/project
npx prismfy-wizard setup --dry-run --root /path/to/project
```

Then install:

```bash
npx prismfy-wizard setup --root /path/to/project
```

Install non-interactively:

```bash
npx prismfy-wizard setup --root /path/to/project --mode balanced --key ss_live_YOUR_KEY --yes
```

Need an API key? Create one at [prismfy.io](https://prismfy.io/?utm_source=github&utm_medium=readme&utm_campaign=agent_search).

If you're landing here from GitHub and want to evaluate it before signing up, start with `scan` or `setup --dry-run`.

## Who This Is For

- developers using Claude Code, Codex-style agents, Cursor, Windsurf, Copilot, Cline, or similar local agent workflows
- teams that want repo-level agent rules to be more consistent across projects
- people building coding, research, monitoring, or documentation agents that need live web verification

## Typical Use Cases

- give a coding agent a default path for checking current package docs and API behavior
- make research agents verify company, product, pricing, or release information before answering
- install one repeatable search policy across multiple repos or local agent environments
- reduce stale-memory answers in workflows where “latest” or “current” matters

## Why This Instead Of Just Adding A Search Tool

Most agent integrations stop at tool access.

That still leaves two common failures:

- the agent has a search tool but does not use it when it should
- verification behavior changes from session to session or repo to repo

Prismfy Wizard is opinionated about that gap. It installs:

- a local `prismfy-search` command
- a managed policy block in agent instruction files
- a selectable verification mode: `minimal`, `balanced`, or `strict`

## Why Use It

- Adds a local `prismfy-search` command backed by Prismfy.
- Injects a managed search policy block into selected agent files.
- Lets you choose how aggressive verification should be.
- Supports `--dry-run` before any write.
- Updates only Prismfy-managed blocks on re-run.
- Supports uninstall later through recorded install state.

![Prismfy Wizard setup flow](./assets/Prismfy-wizard.gif)

## Before You Run It

Without `--root`, `setup` and `scan` search beyond the current repo and can discover home-level agent files too.

Default scan scope includes:

- the current working directory
- `~/.claude`
- `~/.codex`
- `~/.openclaw`
- `~/.hermes`
- `~/.gemini`
- `~/.config/opencode`
- `~/.config/amp`
- `~/.config`
- `~/.factory`
- `~/.codeium/windsurf/memories`
- `~/Documents/Cline/Rules`
- `~/Cline/Rules`

If you want to limit discovery to one project, use `--root`:

```bash
npx prismfy-wizard scan --root /path/to/project
npx prismfy-wizard setup --dry-run --root /path/to/project
```

Selection behavior matters too:

- in interactive setup, the file selector starts with all detected files selected
- in non-interactive flows such as `--yes` or non-TTY execution, all detected files are selected automatically

If you're just landing here from GitHub: Prismfy is not only for this wizard. You can use the API directly, but `prismfy-wizard` is the fastest way to give local agents a durable live-search rule instead of relying on memory or ad hoc browsing.

## What It Writes

Search install can create or update:

- a managed Prismfy block in selected agent files
- `prismfy-search-guide.md` next to each selected agent file
- `~/.prismfy/.env`
- `~/.prismfy/agent-config.json`
- `~/.prismfy/bin/search.sh`
- `~/.prismfy/bin/prismfy-search`
- `export PATH="$HOME/.prismfy/bin:$PATH"` in `.bashrc`, `.zshrc`, or `.profile` when needed

If no agent files are found or selected, `setup` can still install the local helper files under `~/.prismfy/`.

## What Gets Added To Agent Files

Prismfy Wizard writes a managed block like this:

```md
<!-- prismfy-search:start -->
Prismfy Web Search is installed. It searches the live web through multiple engines via `prismfy-search "<query>"`.

Prismfy is the DEFAULT and REQUIRED tool for web search. When you need to discover, verify, compare, or update information from the web, use Prismfy first.

Search usage policy is STRICTLY set to: balanced.

For exact commands, engine selection, citations, and cost-saving rules, read: `prismfy-search-guide.md`.

Never reveal `PRISMFY_API_KEY`.
<!-- prismfy-search:end -->
```

Re-running `setup` or `update` replaces only Prismfy's managed block. It does not rewrite the rest of the file.

## Example Dry Run

Example `setup --dry-run` output from this repo:

```text
◇ 01 Scanning agent files
◇ 02 Choosing search discipline
◇ 03 Choosing agent files

◆ Agent files
│  ✓ 7 found   safe targets only; skills/templates/backups are skipped
│  → 7 prompt  7 guide file(s) already present

◆ Selection
│  ✓ 7 chosen  install into all detected files
│  → prompt    7 already match, 0 need mode update, 0 new
│  → guide     7 existing, 0 new

◆ Dry run
│  ✓ safe      no files will be changed
› Mode: balanced
› Env file: ~/.prismfy/.env
› Search helper: ~/.prismfy/bin/search.sh
› Search command: ~/.prismfy/bin/prismfy-search
│  → install   0 new prompt block(s), 0 prompt mode update(s), 7 already correct prompt(s), 0 new guide file(s), 7 guide update(s), 2 shell helper(s)
```

## Search Modes

Choose how strict the installed policy should be.

| Mode | Best for | Behavior |
| --- | --- | --- |
| `minimal` | Lightweight coding agents and lower-verification workflows | Search when the user explicitly asks to search, verify, browse, or get current information. |
| `balanced` | Everyday agent work | Search before answering current, external, uncertain, or high-impact factual questions. |
| `strict` | High-verification workflows | Treat memory as untrusted for external facts and verify external claims whenever search is available. |

Update the installed mode later:

```bash
prismfy-wizard update --mode strict
```

## Supported Targets

Direct file targets:

- `AGENTS.md`
- `AGENT.md`
- `agent.md`
- `CLAUDE.md`
- `CLAUDE.local.md`
- `GEMINI.md`
- `global_rules.md`
- `guidelines.md`
- `.cursorrules`
- `.windsurfrules`
- `.github/copilot-instructions.md`
- `.junie/agents.md`
- `.junie/guidelines.md`

Rule directories:

- `.cursor/rules/*.mdc`
- `.windsurf/rules/*.md`
- `.clinerules/*.md`
- `.clinerules/*.txt`
- `.continue/rules/*`

Explicitly not targeted:

- `.github/instructions/*.instructions.md`

Skipped directories include:

- `.git`
- `node_modules`
- `.next`
- `dist`
- `build`
- `coverage`
- `logs`
- `media`
- `output`
- `runtime`
- `sessions`
- `cache`
- `backups`
- `backup`
- `.backup`
- `templates`
- `skills`
- `commands`
- `droids`
- `__pycache__`

## Local Search Helper

Setup installs:

```text
~/.prismfy/.env
~/.prismfy/bin/search.sh
~/.prismfy/bin/prismfy-search
```

The helper is Bash-based and requires `curl` and `jq`.

Examples:

```bash
prismfy-search "latest OpenAI Agents SDK docs"
prismfy-search --engine google "LangGraph human in the loop docs"
prismfy-search --engines github,reddit "MCP server examples"
prismfy-search --time week "Claude Code release notes"
prismfy-search --domain docs.python.org "asyncio TaskGroup"
prismfy-search --quota
```

Important defaults:

- if you do not pass `--engine` or `--engines`, the helper uses `google`
- if you do not pass `--lang`, the helper uses `en`
- `--quota` reads quota from `GET /v1/user/me`

## Command Reference

Core commands:

```bash
prismfy-wizard scan
prismfy-wizard setup
prismfy-wizard status
prismfy-wizard update --mode strict
prismfy-wizard repair
prismfy-wizard uninstall
```

Behavior notes:

- `scan` is scan-driven and does not write files.
- `setup` scans for targets, can prompt for scope, validates the API key unless `--skip-key-check` is used, and writes helper/config files under `~/.prismfy/`.
- `status` reads recorded install state from `~/.prismfy/agent-config.json`.
- `update` is config-driven and rewrites the recorded agent files with the new mode.
- `repair` is config-driven and re-installs the helper, re-adds PATH exports if needed, and rewrites recorded agent files and guides.
- `uninstall` is config-driven and removes managed blocks only from files recorded in `~/.prismfy/agent-config.json`.

Useful flags:

```bash
prismfy-wizard setup --dry-run
prismfy-wizard setup --root /path/to/project
prismfy-wizard setup --mode balanced --yes
prismfy-wizard setup --mode strict --key ss_live_YOUR_KEY --yes
prismfy-wizard setup --skip-key-check
```

`--yes` skips file-selection prompts, but you still need `--key` if you want a fully non-interactive setup that does not stop to ask for an API key.

## Safety Model

- `--dry-run` previews changes before writing.
- Dry runs do not require an API key.
- Managed blocks are wrapped in `<!-- prismfy-search:start -->` and `<!-- prismfy-search:end -->`.
- Re-running setup updates only Prismfy-managed blocks.
- API keys are stored locally in `~/.prismfy/.env`.
- Setup may add `export PATH="$HOME/.prismfy/bin:$PATH"` to `.bashrc`, `.zshrc`, or `.profile`.
- `status`, `update`, `repair`, and `uninstall` depend on recorded install state in `~/.prismfy/agent-config.json`.
- `uninstall` removes helper files, local config, local env, and managed blocks from recorded files. It does not currently remove PATH exports from shell profiles.

## Optional Project Memory

Project memory is separate from search install.

Use it if you also want Prismfy Wizard to scaffold `project-knowledge/` and inject a memory protocol block into agent files:

```bash
prismfy-wizard knowledge-init
prismfy-wizard memory-install --root /path/to/project
prismfy-wizard memory-status
prismfy-wizard memory-uninstall
```

`memory-install` scans only the specified project scope and nested directories. Use `--knowledge-root` to point at an existing knowledge directory.

## Requirements

- Node.js and npm to run the published package with `npx` or a global install
- Bash
- `curl`
- `jq`
- network access to `https://api.prismfy.io` for key validation and searches
- a Prismfy API key for non-dry-run setup

For development from source:

- Bun

## Troubleshooting

`jq` is missing:

```bash
# macOS
brew install jq

# Debian/Ubuntu
sudo apt-get install jq
```

No agent files found:

```bash
prismfy-wizard scan --root /path/to/project
prismfy-wizard setup --dry-run --root /path/to/project
```

Invalid API key:

- Create a fresh key at [prismfy.io](https://prismfy.io/?utm_source=github&utm_medium=readme&utm_campaign=agent_search).
- Re-run `prismfy-wizard setup`.
- Use `--skip-key-check` only for local testing or private environments where you intentionally want to bypass live validation.

Want to remove Prismfy from recorded agent files:

```bash
prismfy-wizard uninstall
```

## Development

Run from the repo root:

```bash
bun run apps/prismfy-wizard/src/index.ts help
```

Build from the package directory:

```bash
cd apps/prismfy-wizard
npm run build
```

Test the built CLI:

```bash
node dist/prismfy-wizard.js help
```

The published binary name is `prismfy-wizard`.

## Start With Prismfy

Try the safe path first:

```bash
npx prismfy-wizard setup --dry-run --root /path/to/project
```

Then install with a real key:

```bash
npx prismfy-wizard setup --root /path/to/project
```

Prismfy: [prismfy.io](https://prismfy.io/?utm_source=github&utm_medium=readme&utm_campaign=agent_search)  
Status: [status.prismfy.io](https://status.prismfy.io)

Node.js 与 npm（用于 npx 或全局安装）；Bash；curl；jq；访问 https://api.prismfy.io 的网络；非 dry-run 安装需 Prismfy API Key（在 prismfy.io 创建）；从源码开发需 Bun。具体费用与配额待核验；服务部署地域、国内网络可用性待核验。