Skip to content

fix(knowledge): guide Ascend tasks through external setup - #492

Open
jiangkuaixue123 wants to merge 1 commit into
mainfrom
codex/cannbot-setup-guidance
Open

jiangkuaixue123 wants to merge 1 commit into
mainfrom
codex/cannbot-setup-guidance

Conversation

@jiangkuaixue123

Copy link
Copy Markdown
Collaborator

Refs #476

Ascend tasks with unavailable or disabled cannbot knowledge previously received only a short enable hint, and text output could truncate recovery links. This follow-up to merged #484 provides an installation recommendation, a complete guide URL and an explicit verification workflow.

Governing scope and delivery

The maintainer explicitly requested this bounded setup-guidance change and authorized committing, pushing and updating the PR in the implementation conversation. Codex is the implementation agent; this record is not independent approval.

  • Add the Ascend availability preflight to AGENTS, quickstart and operation guidance. An existing checkout can be enabled without reinstalling it; explicit local-only/knowledge-off conditions are respected.
  • Include installation/enablement guidance in not_enabled and missing-checkout/interpreter unreachable results. Preserve complete text-mode recovery URLs and commands.
  • Document installation prerequisites and three verification steps: discovery, integrated search, and a read preserving both revision and raw-byte SHA256. Explain empty results, stale indices, timeouts and identity drift.
  • Cover missing/disabled installations, missing approved dependencies, local hits/no-match, text/JSON output, and CUDA/local-only exclusions.

This uses the existing local checkout/reader integration. Host MCP registration is neither required nor an InferRSI project grant. It does not implement cannbot serve, automatically install or authorize sources, or import external card bodies.

Validation

Checked commit: 431ad3e5064d14ecb37c231f8211168d63344921, based on 8aba657d.

  • pytest -o addopts='' -q tests/test_cannbot_boundaries.py tests/test_knowledge_channels.py tests/test_knowledge_find.py: 129 passed on the new branch.
  • ruff check src tests tools and git diff --check: successful.
  • All eight affected local documentation links/anchors resolve.
  • Test installations and grants are synthetic and temporary. No real external source installation or end-to-end installation rehearsal was performed for this follow-up.
  • Full local suite not rerun; CI pending. Independent review is pending.

Knowledge authorship declaration: not applicable; no protected knowledge paths changed.

Remaining work

This is a setup-guidance slice of #476. The broader RFC, source-use decisions, MCP serving and receipt/import work remain separate; whole-Issue acceptance or closure is not claimed. Merge requires the repository's current checks and independent approvals.

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 <jiangxiaozhou111@163.com>

@Dong1017 Dong1017 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR review verdict — DO NOT PASS

Reviewed base 8aba657da79e8ed9f6e6fbb33437e9d9fdd8f1c7 and head 431ad3e5064d14ecb37c231f8211168d63344921. This is the full diff, since it is the first review. prior-reviews.md has no formal reviews: no Approve on this head and no outstanding CHANGES_REQUESTED. I'm treating this as the first independent review (Dong-bot, authorized delegate).

Blocker (documentation contract with no code or test behind it)

  • docs/external-channels.md changes the backend-gating table row from "not declared, no grant | none; each channel reports backend_unknown" to "none; cannbot reports not_enabled with setup guidance". docs/operations.md makes the same change to the Inputs bullet, and its new backend_unknown sentence is also vague.
  • The diff changes no gating logic for the undeclared-backend path. Its project.py edits only add fix= text to existing not_enabled and unreachable failures, plus a checkout-completeness probe in _run.
  • None of the new tests runs find without --backend and without a grant. They use --backend ascend, --backend cuda or --no-external.
  • As submitted, the docs may now contradict the actual behavior, which was backend_unknown before. Please do one of these:
    1. Point to the code path that now returns not_enabled for undeclared backends and add a test for it (no --backend, no grant, text and JSON).
    2. Revert the two doc changes if the behavior is unchanged.
  • The Ascend-task preflight in AGENTS.md and docs/external-channels.md says the backend is declared and never inferred from query text. That makes this row the one most likely to mislead.

Non-blocking follow-ups

  • project.py _run now hardcodes the upstream layout (knowledge/ and .agents/skills/knowledge-query/scripts/knowledge_query.py). Please confirm it is the same path constant the subprocess launch uses, ideally by sharing one constant, so the probe and the launch can't drift.
  • apps/cli/__init__.py removes the 120-char clip for every channel's fix: line, not only cannbot's. That is reasonable for copyable URLs. Confirm that no other channel emits long or multiline fix text that would now break the TSV-ish output. _tsv(...).strip() should handle newlines, but I did not see its definition in the diff.
  • The _SETUP_FIX string is duplicated verbatim in docs/external-channels.md and docs/operations.md. A doc-vs-code string test would keep them from drifting.

Verified by reading the diff

  • The new tests cover these cases:
    • The setup suggestion is present with local hits and with no_match, in text and JSON.
    • --backend cuda and --no-external omit the suggestion and never probe the source.
    • The installed-but-disabled describe does not execute the reader.
    • A missing checkout or interpreter gives unreachable with the guide.
    • Suggesting setup creates no grant directory.
  • The preflight and verification docs (describe, then find, then pinned cannbot read with --sha256 and --revision) are internally consistent. They keep authorization, local-only and knowledge-off conditions explicit.

Not verified here

  • I did not run the tests or CI, and I did not check the cannbot upstream layout.
  • I did not inspect the unchanged gating code. The blocker above is that the diff gives no evidence either way.

I will re-read after the author pushes.


Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-sonnet-5-5).

@zengchuang-hw zengchuang-hw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR review verdict — DO NOT PASS yet (validation pending; no concrete blocking code defect found in this static review).

Independent review by the maintainer's delegated reviewer, acting through zengchuang-hw under standing authorization for other-author PR reviews. Scope: #492's setup-guidance slice, not acceptance of the whole #476 RFC.

Revision and range: first review, base 8aba657da79e8ed9f6e6fbb33437e9d9fdd8f1c7 → head 431ad3e5064d14ecb37c231f8211168d63344921; all seven changed files examined. No previous review in this account for this PR; no previous findings to mark resolved.

Independent source assessment

  • project.py::_run now checks the approved checkout's bundle and query script before creating a reader process, and missing checkout/interpreter failures carry the same setup guidance. Missing grants still stop before a source probe. The new paths do not install anything or write a grant.
  • Traced CannbotChannel, ChannelRegistry, explain_gate and CLI output: explicit CUDA excludes this Ascend channel; local-only avoids external lookup; missing grants can explain availability without guessing the task backend. Local hits remain separate from channel failures.
  • _print_external no longer truncates the recovery URL/command at 120 characters. The new tests cover text/JSON, local hits/no-match, absent/disabled sources, missing checkout/interpreter and CUDA/local-only exclusions.
  • The guide correctly separates discovery, integrated search and a read retaining both the raw-byte SHA-256 and revision. I traced generated open commands and the worker's revision/digest rejection paths. It explicitly distinguishes a usable delivery path from technical truth, source-use authorization and campaign acceptance; it does not claim MCP serving exists.

Before approval
The current-head ready checks are still incomplete: Python 3.10/3.11 full-check, Windows compatibility and dashboard-browser are running; macOS compatibility is queued. Complete those applicable checks successfully and inspect any failures before treating this review as approval. This is an evidence gap, not a claim that these checks failed.

Checks and limits

  • Actually performed here: connector-based inspection of the exact diff, affected source/callers, synthetic test definitions, AGENTS, review/contribution/collaboration guidance, #476 requirements and current-head check records.
  • Independently read lint-and-smoke job output: Ruff passed and the two smoke modules report 8 passed. GitHub reports both installed-package jobs, declarations and pr-references successful; their full logs were not replayed here.
  • I did not execute local tests, install an external checkout, run real discovery/search/read or rehearse the documented setup. The PR's 129 passed is the author's report, not my local execution. Existing/new synthetic fixtures do not establish current real-upstream installation compatibility.
  • No other review opinions were used. No code changes, source enablement, downloads, merge or campaign claims.

Non-blocking suggestion: add an incomplete-but-still-present checkout case (remove only the query script or bundle directory), to pin the new preflight branch separately from whole-checkout removal. Retain a versioned real-source setup rehearsal when making a real-installation usability claim; the documented current limitation should stay explicit.

@Dong1017 Dong1017 added area:knowledge Knowledge line: packs, skill library, knowledge admission kind:task Bounded delivery task with a delegated slice labels Nov 18, 2026

@david6666666 david6666666 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One correction to the setup verification steps.

Comment thread docs/external-channels.md
"content_fingerprint": "75ef3269..."}, "platforms": ["a2"]}
```

Require `state: "ok"`, a source revision and the intended platform in

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

describe reports the grant's default platforms, not the platforms the checkout can answer. A project with default a3 can still run the explicit --platform a2 search below, so requiring a2 in platforms could send users through unnecessary re-enablement. Could we check that list only when relying on the default, and verify an explicit target in the search and pinned read steps?

@zengchuang-hw zengchuang-hw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent CI follow-up to my initial review. Head remains 431ad3e5064d14ecb37c231f8211168d63344921, base 8aba657da79e8ed9f6e6fbb33437e9d9fdd8f1c7. Non-voting COMMENT: the pending-CI gap is resolved; real setup-workflow validation is still unverified, so no approval yet.

New machine evidence actually inspected

  • Python 3.10 full-check and Python 3.11 full-check both report successful Ruff and 5085 passed, 36 skipped, 1 warning, 671 subtests passed.
  • These jobs tested merge commit 8ac55288c49885febfdce1fff13c972c0f42aad1. I compared Git tree objects: its entire tree and the reviewed head both equal 922881418d9d4bbf196b0362bd7c9d9197029945. This is content correspondence, not an assumption that a merge-ref run is a bare-head run.
  • Windows/macOS host logs each record the eight required host tests passing without skips; Windows additionally records its 25-case declared group passing without skips. I do not treat these groups as external-source installation tests.
  • All ten current check records are now successful, including installed-package, browser, declarations and references. No new code delta occurred.

Why green CI does not validate the installation guide end to end
The two full-check skip summaries explicitly show all five real-source cases in tests/test_cannbot_channel_acceptance.py skipped for “no approved cannbot checkout with a built index”, including test_read_returns_one_pinned_card at line 144. I inspected that module: those tests exercise actual external search/read only with an approved source, unlike the synthetic boundary fixtures. They do not run the fresh clone/environment/index-build recipe themselves.

This PR specifically delivers installation/recovery guidance plus a three-step usable-source verification workflow. Static inspection and synthetic tests validate how InferRSI presents that guidance and handles failures, but neither establishes that the documented prerequisites and commands work with a real declared upstream revision. The author explicitly reports no real installation rehearsal; I also have not performed one. Thus the prior source-level assessment remains favorable and I found no new concrete code defect, but I cannot clear real setup-workflow usability on this evidence alone.

Before clearing that part, retain a bounded authorized POSIX rehearsal of the documented setup (or a specifically scoped already-installed recovery path), with upstream commit, interpreter/dependency identity, index/discovery state, integrated search result identity and one successful read preserving both revision and raw-byte SHA-256. Publish only approved minimal metadata, not card bodies, private paths or credentials. This asks for evidence of the guide's advertised path, not MCP serving, hardware/campaign performance or closure of #476. If acceptance is deliberately limited to guidance rendering and explicitly excludes real-source usability, have that boundary stated by the authorized scope owner rather than silently relabeling the skipped integration stage as passed.

Execution limits: this follow-up used source inspection, completed CI logs and Git objects only. No local tests, source installation/enablement, network query to the upstream corpus, hardware run, code edit or merge was performed. No other reviewers' opinions were read or used. The earlier incomplete-checkout fixture suggestion remains non-blocking; no old CI blocker is being kept open after these successful runs.

@Dong1017

Copy link
Copy Markdown
Collaborator

Posted by an agent on behalf of @Dong1017 (incremental review only; points already raised by Dong-bot, @zengchuang-hw and @david6666666 are not repeated).

Incremental comment on head 431ad3e5 (base 8aba657d). No new blocker; two non-blocking points not covered in the existing reviews.

1. Unreadable-but-present grant now gets install advice (src/inferrsi/apps/cannbot/project.py, load_grant, except OSError branch)

  • FileNotFoundError is caught first, so this branch only runs when the grant file exists but stat()/open() fails (e.g. PermissionError).
  • In that case the new fix=_SETUP_FIX tells the user to "install cannbot-knowledge if needed ... then enable it". The installation and grant are already there; the actual repair is the file's ownership/permissions. That conflicts with the preflight's own rule that a missing grant "does not prove the source is absent", and it can send users into an unnecessary re-enable.
  • Suggestion: give this branch its own fix (check ownership/mode of ~/.config/inferrsi/cannbot-projects/<digest>.json, or disable then enable), and add a case for it next to test_missing_approved_dependency_includes_installation_guidance. Not covered by the new tests.

2. SETUP_GUIDE points at blob/main

  • The URL is baked into the package, so a user on an installed release (e.g. v0.2.0) is sent to the guide on main, which can describe flags or steps that release does not have, and the #setting-one-up / #verify-the-installation anchors can move later.
  • Optional: build the link from the package version/tag, or keep main and note in the fix text that it is the latest guide. Not a blocker.

Scope: read the full diff at 431ad3e5, load_grant in context, _tsv in apps/cli/__init__.py, and all existing reviews/inline comments. Did not run tests, check the upstream layout, or rehearse the setup.

@zengchuang-hw zengchuang-hw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent incremental review for the new mention in source 6972528615, following my previous review.

Range: 431ad3e5064d14ecb37c231f8211168d63344921 → the same exact head; base remains 8aba657da79e8ed9f6e6fbb33437e9d9fdd8f1c7. There is no code delta. This is a new-request evidence recheck, not another claimed test run.

Independently rechecked: project.py::_run rejects a missing bundle/query script as unreachable with installation guidance before launching the worker; missing grants remain not_enabled. _print_external keeps the sanitized recovery command/URL untruncated. The guide still requires explicit access authorization and discovery → integrated search → a read retaining both revision and raw-byte digest before claiming usability. These bounded source properties remain supported; no new concrete defect was found.

Evidence status: the same ten check records remain successful; their latest completion is 07:02:12 UTC, before this mention. They are not new real-source execution evidence. The actual acceptance module still gates five external-source cases on an approved checkout with a built index, and the previously inspected full-check logs skip those cases. No new primary execution artifact was identified for this request.

Conclusion: COMMENT, not APPROVE. CI completion remains resolved. Real documented setup/recovery usability remains unverified, not failed: the new request does not supply the missing authorized, versioned discovery/search/pinned-read rehearsal. The minimal evidence requested in my previous review remains sufficient; this does not demand MCP, hardware performance, campaign qualification or closure of the whole RFC. The incomplete-checkout fixture suggestion remains non-blocking.

This round used exact-head source, current check metadata and my own prior findings only. No other reviewers' opinions were used; no local tests, external installation/enablement, corpus queries, code changes or merge were performed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:knowledge Knowledge line: packs, skill library, knowledge admission kind:task Bounded delivery task with a delegated slice

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants