AIGC 研报

Use this Skill for CQZX document-scoped AIGC research reports. The backend is
the system of record: do not run research, evidence verification, or long
report generation locally.

For questions about Google Drive reference materials, use the knowledge
workflow below. The host Agent explains retrieved passages; this does not
create a Research job or require an outline approval.

Google Drive knowledge search and explanation

Read references/google-drive-knowledge.md
when the user asks to find, summarize, compare, or explain shared Drive
materials. Retrieve actual indexed text before answering and cite its source
path, section/page when available, and source version. File names alone are
not evidence of document contents.

Use external_knowledge_status, external_knowledge_list_files,
external_knowledge_search, and external_knowledge_get_file when exposed by
the configured connector. Backend 0.2.64 implements these read-only tools at
the deployment-configured knowledge MCP endpoint. Follow next_offset for
catalog/text pages and recheck source versions. CLI knowledge commands are
the fallback. Backend 0.2.68 accepts Keycloak admin or cqzx-knowledge-reader,
the exact resource URL audience and external-knowledge:read scope; REST uses
the API audience and the same read permission. The reader role never grants
admin UI or IR refresh access.
An Agent/legacy Research token does not necessarily authorize knowledge access.

Adapter and login policy

For the packaged CQZX desktop release, public Backend/OAuth/MCP settings are
already in connection.json. Do not ask the user to fill environment variables
or configure a native MCP connector before using the bundled CLI.
When the user asks to log in (for example, "以 yqtest 登录企业知识库"), execute
python scripts/aigc_report_cli.py login --username yqtest from this Skill's
directory, substituting the actual requested username. Omit --username when
none was provided. This opens the cloud Keycloak page in the user's browser;
the user enters the password there. Never request a password in chat.
Keep the login process running while the user finishes the browser callback.
After success, call knowledge status, then retrieve sources for their question.
Use auth status to check stored authorization before starting another login.
The desktop host needs Python 3.10+ and permission to run the bundled scripts.

For first connection, login errors or host configuration, read
references/connection.md.

• Use the configured MCP connector first. MCP is the normal business route.
• Use the bundled CLI only when MCP is unavailable or when a local file must
  be uploaded, downloaded, or inspected by the desktop Agent.
• OAuth authorization-code + S256 PKCE is the preferred CLI login. The helper
  stores tokens in the operating system credential store when available and
  refreshes them as needed. A local token file is a development fallback only.
• A static bearer token or an operator MCP token may be supplied through the
  CLI or environment for service-to-service and diagnostic use.
• The CQZX backend, OAuth issuer, and MCP URL are deployment values. Read the
  bundled connection.json; explicit environment/CLI settings may override it.
  Do not invent a different login domain or place credentials in the profile.
• Keep access tokens, refresh tokens, MCP tokens, and client secrets out of
  chat, committed files, and generated report text.

The target CQZX repository is still migrating the Research runtime and MCP
server. If the configured connector or API reports that a Research route is
missing, report the capability as pending migration; do not silently fall
back to a local mock or claim that a report was generated.

Document-scoped report workflow

Use these MCP tools when they are available:

1. Upload the DOCX with aigc_upload_research_document(file_name, file_base64, brief). Use the returned document_id; a generation id is
   not a document id. For a supplement, pass the existing document_id and
   use only the returned authorized material_id values.
2. Read the outline with aigc_research_get_document_outline(document_id).
   If no outline exists, call aigc_research_normalize_outline(document_id)
   once and inspect the result.
3. Wait for the outline approval event. Show the exact document_id and
   outline_version_id, and obtain an explicit human decision before calling
   aigc_research_approve_outline. Never treat event acknowledgement as
   approval.
4. Start a shadow report with
   aigc_research_start_long_report(document_id, outline_version_id, mode="shadow").
   Pass selected material and section ids only when the user or workflow
   provides them.
5. Poll the durable job with
   aigc_research_long_report_jobs and
   aigc_research_get_long_report_job. Use agent_list_events for lifecycle
   updates, but treat event payloads as notifications rather than report
   content.
6. For supplement_required, collect the requested material and call
   aigc_research_submit_supplement with an idempotent action_id. For
   final_review_required, ask the user for an explicit decision and call
   aigc_research_final_review. Use cancel/resume tools when appropriate.
7. For a succeeded shadow job only, aigc_research_submit_whole_report_aiqc
   may queue independent whole-report AIQC. It does not approve, finalize,
   export, or write back the report.

The serial workflow nodes are outline_gate, research_planner,
retrieval_agent, evidence_verifier, section_planner, section_writer,
chapter_aiqc, revision_agent, and report_assembler. Explain their
status from the durable job rather than guessing from elapsed time.

Evidence and delivery boundaries

• Generic Research Engine behavior must remain domain-neutral. Industry,
  jurisdiction, source authority, writing conventions, and knowledge-base
  selection come from explicit profiles or policies, not this Skill's hidden
  defaults.
• An official or high-authority search result is not automatically relevant
  evidence. Preserve the Fetch/Verification path when relevance is uncertain.
• Do not present search hits, internal source_id/chunk_id, or unverified
  claims as reader-facing citations. Reports use numbered citations such as
  [1] with a matching reference list when the backend provides a deliverable.
• A blocked needs_supplement state is not success. Do not claim completion,
  export, or delivery until the backend's final state and delivery gate allow
  it.

CLI fallback

The bundled helper is scripts/aigc_report_cli.py and uses only the Python
standard library. Useful commands include:

python scripts/aigc_report_cli.py auth login
python scripts/aigc_report_cli.py doctor
python scripts/aigc_report_cli.py mcp connect --mcp-url <deployment-mcp-url>
python scripts/aigc_report_cli.py research upload <outline.docx> --brief <requirements>
python scripts/aigc_report_cli.py research outline <document_id>
python scripts/aigc_report_cli.py research start <document_id> --outline-version-id <id>
python scripts/aigc_report_cli.py research job <document_id> <job_id>

The CLI is an adapter, not a second runtime. It calls the configured
/api/agent routes and returns durable ids and JSON responses. It must not
hold a command open while waiting for a long report unless the user
explicitly asks for polling.