@geekjourneyx/findo 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog
 
+## v1.2.3
+
+- Keep `skills/findo` as pure Agent Skill content and remove Go code from `skills/`.
+- Load bundled skill content through `internal/skillcontent` using the repository or npm package `skills/` directory.
+- Ship `skills/findo` in npm packages and GitHub Release archives, and smoke-test `findo skills read` from npm installs.
+- Simplify `skills/findo/SKILL.md` into a concise English Agent SOP.
+
 ## v1.2.2
 
 - Remove the duplicated internal Agent skill copy.
-- Embed directly from `skills/findo` through the `skills` package, keeping `skills/findo` as the single source of truth.
-- Update release checks to guard the single-source embed path instead of comparing mirrored files.
+- Move toward a single root Agent skill source after removing the mirrored internal copy.
+- Update release checks to guard against mirrored skill files.
 
 ## v1.2.1
 

package/README.md

@@ -27,7 +27,7 @@ The npm package installs the matching GitHub Release binary for your platform an
 Alternative Go install:
 
 ```bash
-go install github.com/geekjourneyx/findo/cmd/findo@v1.2.2
+go install github.com/geekjourneyx/findo/cmd/findo@v1.2.3
 ```
 
 Prebuilt binaries and checksums are available on the [GitHub Releases](https://github.com/geekjourneyx/findo/releases) page.
@@ -117,7 +117,13 @@ Human output defaults to a table. Use `--json` for scripts, agents, CI, and down
 
 ## Agent Skill
 
-Findo embeds its Agent SOP in the release binary so agents can read instructions that match the executable on `PATH`:
+Recommended Agent Skills install:
+
+```bash
+npx skills add geekjourneyx/findo
+```
+
+Findo also ships the same Agent SOP with the CLI package so agents can read instructions that match the executable on `PATH`:
 
 ```bash
 findo skills list --json
@@ -125,7 +131,7 @@ findo skills read findo
 findo skills read findo --json
 ```
 
-`skills read` defaults to raw Markdown for direct agent context. With `--json`, the same content is returned in the `content` field with version metadata. Use this when an external skill install, README, or repository checkout may be older than the installed CLI.
+`skills read` defaults to raw Markdown for direct agent context. With `--json`, the same content is returned in the `content` field with version metadata. Use this when you need to verify the SOP bundled with the installed CLI.
 
 ## Output
 
@@ -133,7 +139,7 @@ Retrieval commands return a stable envelope. A successful JSON response looks li
 
 ```json
 {
-  "version": "1.2.2",
+  "version": "1.2.3",
   "query": {
     "text": "AI Agent 商业化",
     "mode": "search",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekjourneyx/findo",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Install the findo CLI from the matching GitHub Release bundle.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,8 @@
   "files": [
     "scripts/install.js",
     "scripts/run.js",
+    "skills/findo/SKILL.md",
+    "skills/findo/test-prompts.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/scripts/run.js

@@ -6,6 +6,7 @@ const { execFileSync } = require("child_process");
 
 const ext = process.platform === "win32" ? ".exe" : "";
 const binaryPath = path.join(__dirname, "..", "bin", `findo${ext}`);
+const skillsPath = path.join(__dirname, "..", "skills");
 
 if (!fs.existsSync(binaryPath)) {
   console.error(
@@ -15,7 +16,11 @@ if (!fs.existsSync(binaryPath)) {
 }
 
 try {
-  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  const env = { ...process.env };
+  if (!env.FINDO_SKILLS_DIR && fs.existsSync(skillsPath)) {
+    env.FINDO_SKILLS_DIR = skillsPath;
+  }
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit", env });
 } catch (error) {
   if (typeof error.status === "number") {
     process.exit(error.status);

package/skills/findo/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: findo
+description: >-
+  Use Findo, an Agent Native Go CLI for Chinese internet research. Use when the user asks to search Chinese web sources, Zhihu, Zhihu hotlists, Bocha, Volcengine Ark, Chinese internet topics, source-backed briefs, contradiction checks, counterintuitive topic discovery, popular answers, live provider testing, or current Chinese web signals.
+---
+
+# Findo
+
+Use `findo` to retrieve Chinese internet sources through provider APIs and return source-backed answers. Prefer `--json` for agent workflows.
+
+## Before Running
+
+Check availability:
+
+```bash
+findo version
+findo config show --json
+```
+
+If `findo` is missing and the user asked for setup, install it:
+
+```bash
+npm install -g @geekjourneyx/findo
+```
+
+Never print `.env`, API keys, bearer tokens, raw config files, or CI secrets. Treat redacted config values as expected.
+
+## Choose A Source
+
+Use the narrowest source that matches the task:
+
+| Need | Command |
+| --- | --- |
+| Broad web evidence | `findo bocha "<query>" --json --limit 5` |
+| Web-grounded direct answer | `findo volc "<query>" --json --limit 1` |
+| Zhihu opinions and discussions | `findo zhihu "<query>" --json --limit 5` |
+| Zhihu-backed global web search | `findo zhihu web "<query>" --json --limit 5` |
+| Current Zhihu hotlist | `findo hot zhihu --json` |
+| Available source IDs | `findo sources --json` |
+
+Use Zhihu for opinion-rich questions, Bocha for broad corroboration, Volcengine for synthesized direct answers, and hotlist for current attention.
+
+For Zhihu global search only, filters are valid:
+
+```bash
+findo zhihu web "<query>" --filter 'host=="example.com"' --search-db realtime --json
+```
+
+## Research Workflow
+
+1. Rewrite the user request into 2-5 concrete Chinese queries with aliases, product names, and time qualifiers when useful.
+2. Start with `--limit 3` to `--limit 5`; increase only when coverage is weak.
+3. Inspect `status`, `results`, `source_status`, and `errors` in JSON output.
+4. Cross-check important claims across sources before presenting them as facts.
+5. Separate source claims from your inference. Mention provider failures when they reduce confidence.
+
+## Answer Shape
+
+For research answers:
+
+```markdown
+**Conclusion**
+One concise answer.
+
+**Evidence**
+- Source, title, URL, key point.
+- Source, title, URL, key point.
+
+**Assessment**
+What is likely true, what is uncertain, and what to verify next.
+```
+
+For topic discovery:
+
+```markdown
+**Topic Candidates**
+1. Topic: why it matters, source signal, suggested angle.
+2. Topic: why it matters, source signal, suggested angle.
+
+**Counterintuitive Point**
+What contradicts common assumptions.
+
+**Next Step**
+Exact follow-up searches or validation steps.
+```
+
+## Failure Handling
+
+| Signal | Action |
+| --- | --- |
+| `credential_missing` or exit `4` | Check redacted config; ask for the relevant provider key if needed. |
+| Exit `2` | Remove incompatible flags and rerun the simplest valid command. |
+| Exit `5` | Retry once with a smaller limit, then switch provider. |
+| Exit `6` | Narrow the query and reduce `--limit`. |
+| Exit `7` | Rewrite with alternate Chinese terms or broaden to Bocha/Zhihu global search. |
+
+When one provider fails, continue with configured alternatives if the user asked for research rather than debugging.
+
+## Guardrails
+
+- Do not scrape browsers or websites when a Findo provider can answer the task.
+- Do not use `--filter` or `--search-db` outside `findo zhihu web`.
+- Do not treat `findo sources --json` as proof that credentials work; it is only source inventory.
+- Do not present one provider's output as verified fact when sources conflict.
+- Do not expand a narrow question into broad trend research unless the user asks for topic discovery.

package/skills/findo/test-prompts.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": 1,
+    "prompt": "搜一下知乎，帮我找 10 个反直觉、颠覆认知的程序员话题，看看热门回答都在说什么。",
+    "expected": "Uses findo zhihu or findo zhihu web with JSON output, summarizes topic candidates with sources, and separates evidence from inference."
+  },
+  {
+    "id": 2,
+    "prompt": "帮我检查当前 findo 是否已经配置好，分别用最小 limit 测一下知乎、Bocha 和火山引擎能不能正常返回，但不要读取或输出任何密钥。",
+    "expected": "Checks version and redacted config, runs minimal provider smoke calls with --limit 1, reports provider statuses, and avoids reading or exposing secrets."
+  },
+  {
+    "id": 3,
+    "prompt": "我想调研一个中文互联网话题，先用 Bocha 查全网，再用火山引擎给一个直答，最后告诉我哪些结论不确定。",
+    "expected": "Runs narrow Bocha and Volcengine queries with --json, cross-checks claims, reports URLs and uncertainty, and preserves provider failures if any."
+  }
+]