From 431ad3e5064d14ecb37c231f8211168d63344921 Mon Sep 17 00:00:00 2001 From: jiangkuaixue123 Date: Wed, 18 Nov 2026 14:51:50 +0800 Subject: [PATCH] fix(knowledge): guide Ascend tasks through external setup Provide actionable setup links for unavailable or disabled cannbot knowledge, preserve complete CLI recovery guidance, and document discovery, search and identity-bound read verification. Agent-assisted-by: Codex (implementation) Signed-off-by: jiangkuaixue123 --- AGENTS.md | 5 ++ docs/external-channels.md | 84 ++++++++++++++++++++++++++-- docs/operations.md | 16 ++++-- docs/quickstart.md | 5 ++ src/inferrsi/apps/cannbot/project.py | 28 ++++++++-- src/inferrsi/apps/cli/__init__.py | 3 +- tests/test_cannbot_boundaries.py | 75 +++++++++++++++++++++++++ 7 files changed, 201 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1e4aca37..7e8cc57f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,6 +102,11 @@ Portable operator guidance and candidate procedures live in [src/inferrsi/knowle ## Optimization requests +For Ascend tasks, follow the [external knowledge preflight](docs/external-channels.md#ascend-task-preflight). +If cannbot is unavailable or not enabled, proactively provide the installation +recommendation and guide link, then verify discovery, search and a pinned card +read after setup. Respect explicit local-only or knowledge-off conditions. + Ordinary project optimization stays in the current Agent conversation. Follow the [shared optimization workflow](docs/optimization-workflow-unification.md): prepare explicit workload, quality/measurement scripts, metric, gates, declared diff --git a/docs/external-channels.md b/docs/external-channels.md index 6db248f5..b7fa79ba 100644 --- a/docs/external-channels.md +++ b/docs/external-channels.md @@ -14,7 +14,7 @@ no_match 135 entries searched; rephrase, or search the corpus directly with r external (not locally verified; scores are not comparable across channels) cannbot-knowledge [not_enabled] cannbot knowledge is not enabled for this project - fix: inferrsi cannbot enable --checkout --python + fix: For Ascend tasks, install cannbot-knowledge if needed (checkout, Python environment and index), then enable it: inferrsi cannbot enable --checkout --python --backend ascend --platform . Installation and verification: https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up . For local-only search, use inferrsi find --no-external. ``` `no_match` there is honest: the packaged corpus really holds nothing for that @@ -27,6 +27,41 @@ per-API cards**. The external cannbot-knowledge corpus holds **10,550 cards, 2,993 of them Ascend C API cards**. Ignoring that gap is what the channel exists to prevent. +## Ascend task preflight + +When the user declares an Ascend task, check external knowledge availability +before researching optimization directions. Confirm the actual platform (`a2`, +`a3`, etc.); do not infer it from query text. If the task explicitly requires +local-only or knowledge-off operation, honor that condition and skip this probe. + +1. From the target Git project, run `inferrsi cannbot describe` and inspect its + JSON `state`. Exit code 0 alone does not establish that the channel is ready. +2. For `not_enabled`, proactively recommend cannbot-knowledge for Ascend API + and operator references and provide the [installation guide](#setting-one-up) + ([web link](https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up)). + Explain that the missing project grant does not prove the source is absent: + an existing installation only needs project enablement. Offer + `inferrsi find --no-external` for local-only work. +3. For a missing checkout or reader (`unreachable`), use the same guide to + restore the installation or enable its new location. For `index_stale`, + rebuild the approved source's index using the returned guidance. Other + failure states require their stated repair; do not report them as zero hits. +4. Apply existing installation/access authorization; if absent, obtain it before + installing or enabling a source. Then complete all three + [verification steps](#verify-the-installation) below before reporting that + external knowledge is usable. If setup is deferred, continue with the + permitted local knowledge and state that external coverage was unavailable. + +`find --backend ascend` also emits the installation recommendation, enable +command and complete guide URL in text and JSON when the channel is not enabled, +whether or not local hits exist. Explicit `--no-external` and nonmatching +backends such as `cuda` omit this channel and its suggestion. + +This integration uses a local checkout and reader process. Registering an MCP +server in an Agent host is not a prerequisite, and an installed host MCP does +not create an InferRSI project grant. InferRSI's `cannbot serve` proxy is not +implemented; the steps below configure the current CLI integration. + ## Why it is not downloaded for you cannbot-knowledge has its own CANN Open Software License Agreement v2.0. @@ -42,9 +77,13 @@ a wheel, or `evidence/`. ## Setting one up You supply a checkout, an interpreter, and the backend it serves. The `git` -executable must be available for read-time revision checks: +executable must be available for read-time revision checks. Use Python 3.10+ +and an interpreter with PyYAML. The following POSIX shell example uses `a2`; +replace it with the confirmed target platform. If the checkout, environment and +index already exist, reuse them and proceed to `enable` in the target Git project. ```bash +mkdir -p ~/src ~/venvs git clone https://gitcode.com/cann/cannbot-knowledge.git ~/src/cannbot-knowledge python3 -m venv ~/venvs/cannbot && ~/venvs/cannbot/bin/pip install pyyaml @@ -72,15 +111,50 @@ already could have fixed. | `--backend` | Default task backend; explicit `find --backend` takes precedence. Cannbot serves Ascend only. | | `--platform` | Default upstream platform (`a2`, `a3`, `950`, `310p`, `910`, …) | -Check it: +### Verify the installation + +Run these checks from the same target Git project that was enabled. Choose a +platform supported by the task; the example below uses `a2`. + +**1. Check discovery and configuration.** ```bash $ inferrsi cannbot describe {"state": "ok", "revision": "92dc2607...", "cards": 10550, "index": {"schema": "cannbot-knowledge-index.v1", "version": 3, - "content_fingerprint": "75ef3269..."}} + "content_fingerprint": "75ef3269..."}, "platforms": ["a2"]} +``` + +Require `state: "ok"`, a source revision and the intended platform in +`platforms`. A successful `enable` or process exit alone is insufficient. + +**2. Check integrated search.** + +```bash +inferrsi find "CeilDivision" --backend ascend --platform a2 --external-limit 1 --json ``` +Inspect the `cannbot-knowledge` entry in `external[]`: require `state: "ok"`, +its revision and at least one result with an `open` command. Local `no_match` +does not make this check fail. If the source answers with zero hits, discovery +worked but search-to-read verification is still incomplete; use a term known to +exist on the selected platform. A timeout or stale index needs repair first. + +**3. Open the returned card with its identity.** + +Run the exact `open` command returned by step 2. Its shape is: + +```bash +inferrsi cannbot read --sha256 --revision +``` + +Require `state: "ok"`, non-empty `text`, and a `card_sha256` and `revision` +matching the search result. If another page is needed, append `--page 2` to the +same command, preserving both identity flags. A drift rejection requires a new +search; do not drop the flags to make verification succeed. This verifies the +delivery path, not the card's technical claims or campaign evidence eligibility. +Do not copy the returned body into shared logs or evidence. + Revoke it with `inferrsi cannbot disable`. The grant lives at `~/.config/inferrsi/cannbot-projects/.json` and is bound to the project's `.git` identity, so copying it to another clone does not carry the @@ -140,7 +214,7 @@ owned resources; Python cannot forcibly stop arbitrary in-process threads. | --- | --- | | `ascend` | `cannbot-knowledge`, plus any platform-neutral channel | | `cuda`, `mlx`, `rocm`, `cpu` | none — an Ascend source must not answer a CUDA task | -| not declared, no grant | none; each channel reports `backend_unknown` | +| not declared, no grant | none; cannbot reports `not_enabled` with setup guidance | The backend is never inferred from the query text. A query containing "asc" is not evidence that the task is an Ascend task, and a wrong inference would be diff --git a/docs/operations.md b/docs/operations.md index 806b2602..f12eabeb 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -275,18 +275,24 @@ no_match 135 entries searched; rephrase, or search the corpus directly with r external (not locally verified; scores are not comparable across channels) cannbot-knowledge [not_enabled] cannbot knowledge is not enabled for this project - fix: inferrsi cannbot enable --checkout --python + fix: For Ascend tasks, install cannbot-knowledge if needed (checkout, Python environment and index), then enable it: inferrsi cannbot enable --checkout --python --backend ascend --platform . Installation and verification: https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up . For local-only search, use inferrsi find --no-external. ``` -Enabling a channel is a deliberate, per-checkout action by a person; see -[external knowledge channels](external-channels.md). This repository does not +For Ascend tasks, follow the [availability preflight](external-channels.md#ascend-task-preflight) +and proactively present the [installation guide](external-channels.md#setting-one-up) +when the source is missing or not enabled. After setup, verify discovery, +integrated search and a revision/digest-bound read using the +[verification steps](external-channels.md#verify-the-installation). Enabling a +channel is a deliberate, per-checkout action. This repository does not clone, download or bundle the corpus automatically. Review the upstream terms for the intended use before granting access; source permissions remain separate from this integration mechanism. - **Inputs:** `--backend ` declares the task backend; **without it and - without an approved grant, no channel is searched** and each one reports - `backend_unknown`. `--no-external` skips all channels for CI and offline runs. + without an approved grant, no channel is searched**; cannbot reports + `not_enabled` with setup guidance. `backend_unknown` applies to a channel + without a task declaration and without a more specific availability hint. + `--no-external` skips all channels and setup suggestions for CI and offline runs. `--external-limit ` overrides the per-channel cap (`cannbot-knowledge` 100, `mindie-agent` 5). `--external-timeout ` bounds discovery and search together (8s default); `--platform` overrides the upstream platform in the grant. diff --git a/docs/quickstart.md b/docs/quickstart.md index 01c5b488..71d95ca7 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -47,6 +47,11 @@ Its common catalog ID and the separate MLX-LM procedure remain unchanged. ## Discover knowledge and skills +For Ascend tasks, first follow the [external knowledge preflight](external-channels.md#ascend-task-preflight). +If cannbot is not installed or enabled for the project, the CLI recommends setup +and links the [installation and verification guide](external-channels.md#setting-one-up). +External knowledge is optional; an explicit `--no-external` keeps the search local. + Start from the problem. `find` ranks packaged skills, imported records and casebook entries together and reports what each one's evidence covers, so a direction already tried and dropped surfaces beside the procedure for trying it: diff --git a/src/inferrsi/apps/cannbot/project.py b/src/inferrsi/apps/cannbot/project.py index 7386f049..8a681028 100644 --- a/src/inferrsi/apps/cannbot/project.py +++ b/src/inferrsi/apps/cannbot/project.py @@ -25,6 +25,17 @@ # refused rather than forwarded: the upstream CLI is fail-closed about platform # and a typo there would silently change which cards answer. PLATFORMS = ("a2", "a3", "950", "310p", "910", "kirin_x90", "kirin_9030", "agnostic") +SETUP_GUIDE = ( + "https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md" + "#setting-one-up" +) +_SETUP_FIX = ( + "For Ascend tasks, install cannbot-knowledge if needed (checkout, Python " + "environment and index), then enable it: inferrsi cannbot enable " + "--checkout --python --backend ascend --platform . " + f"Installation and verification: {SETUP_GUIDE} . " + "For local-only search, use inferrsi find --no-external." +) class ChannelFailure(ValueError): @@ -44,7 +55,7 @@ def project_root() -> Path: return folder raise ChannelFailure( "Open a Git project to use project-scoped cannbot knowledge", - state="not_enabled", fix="Open a Git project, then enable cannbot knowledge", + state="not_enabled", fix="Open a Git project first. " + _SETUP_FIX, ) @@ -105,10 +116,11 @@ def load_grant(root: Path | None = None) -> dict: except FileNotFoundError: raise ChannelFailure( "cannbot knowledge is not enabled for this project", state="not_enabled", - fix="inferrsi cannbot enable --checkout --python ", + fix=_SETUP_FIX, ) from None except OSError: - raise ChannelFailure("The cannbot project grant could not be read", state="not_enabled") \ + raise ChannelFailure("The cannbot project grant could not be read", state="not_enabled", + fix=_SETUP_FIX) \ from None if (grant.get("schema") != _SCHEMA or grant.get("project_root") != str(root) or grant.get("checkout_identity") != checkout @@ -126,6 +138,13 @@ def load_grant(root: Path | None = None) -> dict: def _run(grant: dict, action: str, arguments: dict, *, timeout: float, request=None) -> dict: + upstream = Path(grant["upstream"]) + query_script = upstream / ".agents/skills/knowledge-query/scripts/knowledge_query.py" + if not (upstream / "knowledge").is_dir() or not query_script.is_file(): + raise ChannelFailure( + "The approved cannbot checkout is missing or incomplete", state="unreachable", + fix=_SETUP_FIX, + ) environment = os.environ.copy() for key in ("CANNBOT_MCP_TOKENS", "CANNBOT_KNOWLEDGE_PLATFORM"): environment.pop(key, None) @@ -147,7 +166,8 @@ def _run(grant: dict, action: str, arguments: dict, *, timeout: float, request=N raise ChannelFailure("cannbot output exceeded 2 MiB", state="rejected") from None except OSError: raise ChannelFailure( - "The approved cannbot reader could not be started", state="unreachable" + "The approved cannbot reader could not be started", state="unreachable", + fix=_SETUP_FIX, ) from None if len(result.stdout) > MAX_BYTES: raise ChannelFailure("cannbot returned more than 2 MiB", state="rejected") diff --git a/src/inferrsi/apps/cli/__init__.py b/src/inferrsi/apps/cli/__init__.py index 974f3d9a..1b94758d 100644 --- a/src/inferrsi/apps/cli/__init__.py +++ b/src/inferrsi/apps/cli/__init__.py @@ -169,7 +169,8 @@ def _print_external(result: dict) -> None: line += f"\t{_clip(entry['detail'], 100)}" print(line) if entry.get("fix"): - print(f" fix: {_clip(entry['fix'], 120)}") + # Keep setup URLs and recovery commands complete and copyable. + print(f" fix: {_tsv(entry['fix']).strip()}") continue revision = (entry.get("revision") or "")[:12] or "unpinned" print(f" {entry['channel']} @ {revision}\t[{entry['score_scale']}]" diff --git a/tests/test_cannbot_boundaries.py b/tests/test_cannbot_boundaries.py index bf0648ee..c6f7a9af 100644 --- a/tests/test_cannbot_boundaries.py +++ b/tests/test_cannbot_boundaries.py @@ -4,6 +4,7 @@ import json import os import shlex +import shutil import subprocess import sys import time @@ -285,6 +286,80 @@ def test_outside_git_project_reports_not_enabled(tmp_path, monkeypatch, backend) assert payload["items"] assert payload["external"][0]["state"] == "not_enabled" assert "Git project" in payload["external"][0]["fix"] + assert project.SETUP_GUIDE in payload["external"][0]["fix"] + + +@pytest.mark.parametrize("query, no_match", [("tiling", False), ("qzxvjkqzxvjk", True)]) +@pytest.mark.parametrize("json_output", [False, True]) +def test_uninstalled_channel_suggests_setup_with_complete_link( + tmp_path, monkeypatch, query, no_match, json_output, +): + home, root = tmp_path / "home", tmp_path / "project" + home.mkdir() + (root / ".git").mkdir(parents=True) + monkeypatch.setenv("HOME", str(home)) + monkeypatch.setenv("USERPROFILE", str(home)) + monkeypatch.setenv("PYTHONPATH", str(REPO / "src")) + output_flags = ["--json"] if json_output else [] + result = cli("find", query, "--backend", "ascend", *output_flags, cwd=root) + assert result.returncode == 0, result.stderr + if json_output: + payload = json.loads(result.stdout) + assert payload["no_match"] is no_match + entry = payload["external"][0] + assert entry["state"] == "not_enabled" + guidance = entry["fix"] + else: + assert ("no_match\t" in result.stdout) is no_match + assert "[not_enabled]" in result.stdout + guidance = result.stdout + assert "install cannbot-knowledge if needed" in guidance + assert project.SETUP_GUIDE in guidance + assert "--platform " in guidance + assert "--no-external" in guidance + # A suggestion must not silently install or authorize an external source. + assert not (home / ".config/inferrsi/cannbot-projects").exists() + + +@pytest.mark.parametrize("args", [("--backend", "cuda"), ("--backend", "ascend", "--no-external")]) +def test_explicit_local_only_conditions_omit_setup_suggestion(upstream, args): + _, script, _ = upstream + project.disable() + script.write_text("raise RuntimeError('source must not be probed')\n") + result = cli("find", "tiling", *args, "--json") + assert result.returncode == 0, result.stderr + assert "external" not in json.loads(result.stdout) + assert project.SETUP_GUIDE not in result.stdout + result.stderr + + +def test_installed_but_disabled_source_suggests_setup_without_probing(upstream): + source, script, _ = upstream + project.disable() + marker = source / "unexpected-probe" + script.write_text("from pathlib import Path\nPath('unexpected-probe').touch()\n") + info = json.loads(cli("cannbot", "describe").stdout) + assert info["state"] == "not_enabled" + assert project.SETUP_GUIDE in info["fix"] + assert "if needed" in info["fix"] + assert not marker.exists() + + +@pytest.mark.parametrize("missing", ["checkout", "interpreter"]) +def test_missing_approved_dependency_includes_installation_guidance(upstream, missing): + source, _, _ = upstream + if missing == "checkout": + shutil.rmtree(source) + else: + path = project._grant_path(project.project_root()) + grant = project.load_grant() + grant["python"] = str(source / "missing-python") + path.write_text(json.dumps(grant)) + result = cli("find", "tiling", "--backend", "ascend", "--json") + assert result.returncode == 0, result.stderr + payload = json.loads(result.stdout) + assert payload["items"] + assert payload["external"][0]["state"] == "unreachable" + assert project.SETUP_GUIDE in payload["external"][0]["fix"] def test_platform_override_and_cuda_gate(upstream):