mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
jakevin
a9d21f3de0
* fix: project hygiene — docs, lint, daemon restart, code fence - Update Node version requirement from >= 20 to >= 21 in 7 doc files (README, README.zh-CN, installation guides, troubleshooting) - Update adapter count from 79+ to 87+ in READMEs - Remove duplicate `lint` script (identical to `typecheck`) - Fix TESTING.md CI matrix: Node ['22'] instead of ['20', '22'] - Fix autofix SKILL.md code fence escaping (\``` → ~~~) - Add daemon restart to postinstall so updated adapters are picked up - Fix preuninstall to respect OPENCLI_DAEMON_PORT env var * fix: align docs and skills with JS-first adapter contract Adapters are now .js files (not .ts). Update all references across: - README.md, README.zh-CN.md, CONTRIBUTING.md - docs/guide/getting-started.md, docs/index.md - skills/opencli-browser/SKILL.md, skills/opencli-explorer/SKILL.md The runtime (discovery.ts) only loads .js from user clis/ directories, and `opencli browser init` generates .js scaffolds. Documentation was still teaching users to create .ts files. * fix: update CI matrix to Node 22 only (drop Node 20) package.json requires Node >= 21 (styleText dependency). The CI matrix was still testing Node 20 which doesn't meet this requirement. * fix: revert incorrect daemon restart from postinstall The daemon (browser bridge) only handles CDP communication — it has no knowledge of adapters. Adapter discovery, loading, and execution all happen in the CLI process, which is fresh each invocation. The _loadedModules cache in execution.ts is process-local and not a real staleness concern. Remove the unnecessary restartDaemon() call.
69 lines
2.0 KiB
Markdown
69 lines
2.0 KiB
Markdown
# Troubleshooting
|
|
|
|
## Common Issues
|
|
|
|
### "Extension not connected"
|
|
|
|
- Ensure the opencli Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
|
|
- Run `opencli doctor` to diagnose connectivity.
|
|
|
|
### Empty data or 'Unauthorized' error
|
|
|
|
- Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page.
|
|
- Some sites have geographic restrictions (e.g., Bilibili, Zhihu from outside China).
|
|
|
|
### Browser command opens the page but still cannot read context
|
|
|
|
- A healthy Browser Bridge connection does not guarantee that the current page target exposes the data your adapter expects.
|
|
- Some browser adapters are sensitive to the active host or page context.
|
|
- Example: `opencli 1688 item` may fail with `did not expose product context` if the target is too broad.
|
|
- Retry on a real item page, refresh the page in Chrome, and if needed narrow the target, for example:
|
|
|
|
```bash
|
|
OPENCLI_CDP_TARGET=detail.1688.com opencli 1688 item 841141931191 -f json
|
|
```
|
|
|
|
### Node API errors
|
|
|
|
- Make sure you are using **Node.js >= 21**. Some features require `node:util` styleText (stable in Node 21+).
|
|
- Run `node --version` to verify.
|
|
|
|
### Daemon issues
|
|
|
|
```bash
|
|
# View extension logs
|
|
curl localhost:19825/logs
|
|
|
|
# Stop the daemon
|
|
opencli daemon stop
|
|
|
|
# Full diagnostics
|
|
opencli doctor
|
|
```
|
|
|
|
> The daemon is persistent and stays alive until explicitly stopped (`opencli daemon stop`) or the package is uninstalled.
|
|
|
|
### Desktop adapter connection issues
|
|
|
|
For Electron/CDP-based adapters (Cursor, Codex, etc.):
|
|
|
|
1. Make sure the app is launched with `--remote-debugging-port=XXXX`
|
|
2. Verify the endpoint is set: `echo $OPENCLI_CDP_ENDPOINT`
|
|
3. Test the endpoint: `curl http://127.0.0.1:XXXX/json/version`
|
|
|
|
### Build errors
|
|
|
|
```bash
|
|
# Clean rebuild
|
|
rm -rf dist/
|
|
npm run build
|
|
|
|
# Type check
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
- [GitHub Issues](https://github.com/jackwener/opencli/issues) — Bug reports and feature requests
|
|
- Run `opencli doctor` for comprehensive diagnostics
|