docs: update install guide and add five how-to guides#24
Open
zlcnju wants to merge 5 commits into
Open
Conversation
The install page still documented the v1.2.0 flow. Verified against the smart-doc chart (charts/smart-doc/scripts/plugin-config.yaml, templates/, files/init-database.sh) and a live v1.5.0 deployment: - Drop the manual database-dump prepare/import sections: since v1.2.1 an init container bootstraps the knowledge base from the built-in dump selected in the form (Built-in KnowledgeBase File). - Fix the upload script: replace undefined AI_CLUSTER_OPERATOR_NAME / CLUSTER (copied from the Alauda AI docs) with PACKAGE_FILE and --clusters=global. - Fix the external PostgreSQL secret example: uri scheme is postgresql+psycopg, not pg8000. - Document the current install form: built-in PGVector/Redis toggles and external-secret formats, credentials Secret reference (llm-api-key/cohere-api-key/api-key), reranker, tool approval strategy, Expose as MCP Server, extra MCP/CA ConfigMaps, Skills, rate and quota limits, RAG tuning. - Remove form fields that no longer exist (Enable Agent Mode, MCP K8s API Server Address) and add a post-install verification section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Deploying alauda-hyperflux with
|
| Latest commit: |
e4bbcf7
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c40986f3.alauda-hyperflux.pages.dev |
| Branch Preview URL: | https://update-install-doc.alauda-hyperflux.pages.dev |
… MCP usage Four task guides under a new How To section, each verified against the smart-doc source (server/src/extra_mcp.py, skills.py, certificates.py, mcp_server.py, auth.py and the chart) and, where possible, against a live deployment: - Configure External MCP Servers: ConfigMap schema (name/url/transport/ headers/tls_verify), registration, tool-name prefixing, and the approval-strategy gotcha where unannotated tools are filtered out under the default `disabled` strategy. - Create Custom Skills: frontmatter format, cosine matching against name+description with the 0.35 threshold, built-in skill overrides, and load/match verification via logs. - Configure TLS: Extra CA ConfigMaps as the main path (process-wide trust for LLM/MCP/reranker, PG excluded), plus the MiConfig-only advanced knobs and the llmSkipSslVerify warning. - Use Hyperflux as an MCP Server in Your IDE: endpoint (trailing slash required — verified live: /mcp without it returns a 307 the ingress strips the Location from), bearer/API-key auth, client config examples, and the elicitation-based write-approval flow. The full handshake and tools/list were exercised against a live deployment. Install guide now cross-links each of the four guides. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
zlcnju
changed the title
Covers the three redaction parts, verified against server/src (regex_filter.py, redaction_audit.py, config.py) and the chart, with the audit endpoint exercised on a live deployment: - queryRedactionFilters value rules: schema (name/pattern/mode/ replace_with/applies_to), redact vs tokenize modes, MiConfig-only configuration with a ModuleInfo patch example, fail-fast validation and fail-closed application, rule-writing guidance. - toolArgRedactKeys key-name masking with the built-in safe set and its replace-not-extend override semantics. - Redaction audit: metadata-only records (values never stored), the admin-only /api/admin/redaction_audit query API (response shape verified live), best-effort writes and the missing-retention caveat. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
zlcnju
changed the title
…section Drop the Advanced TLS settings table (tlsProfileType/tlsMinVersion/ tlsCiphers/pgSSLMode/pgSSLRootCert/securityHeaders) and promote skipping certificate verification (llmSkipSslVerify) to its own section with the full ModuleInfo patch procedure, the LLM-only scope warning, and the revert step. External-PG TLS keeps a one-line pointer to pgSSLMode/ pgSSLRootCert in the extra-CA note. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove the x-api-key HMAC scheme from the IDE guide (its 300-second token freshness makes it impractical for IDE config files, and it was the one path not exercised on a live deployment). ACP bearer token is now the single documented auth method; read-only/write and troubleshooting sections updated accordingly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two parts, all content verified against the smart-doc source and cross-checked on a live deployment.
1. Install guide refresh
The install page still documented the v1.2.0 flow. Verified against the chart (
charts/smart-doc/scripts/plugin-config.yaml,templates/,files/init-database.sh) and a live v1.5.0 deployment (ModuleInfo config, secret key names, init-container logs, pod/container names):${AI_CLUSTER_OPERATOR_NAME}/${CLUSTER}→${PACKAGE_FILE},--clusters=global).postgresql+psycopg, notpg8000).2. New How To section (5 guides)
name/url/transport/headers/tls_verify), registration and restart semantics, tool-name prefixing, and the approval-strategy gotcha: under the defaultdisabledstrategy, tools withoutreadOnlyHint: trueare filtered out entirely.llmSkipSslVerify, LLM-only scope, ModuleInfo patch procedure, test/dev only).mcp.jsonconfig examples, elicitation-based write approval, troubleshooting table.queryRedactionFiltersvalue rules (redact/tokenize modes, ModuleInfo patch example, fail-fast validation),toolArgRedactKeyskey-name masking with the built-in safe set, and the admin-only redaction audit API (metadata-only records; no built-in retention).The install guide cross-links the guides.
Verification on the live environment
get pod | grep smart-doc,logs -l app=smart-doc -c serve) run as written; secret key names andbuiltinDumpFile/pgCollectionNamepairing match.initialize+tools/listhandshake returningserverInfo.name=hyperfluxand thehyperflux_agenttool. This surfaced a fact not visible in the code:/mcpwithout a trailing slash returns a 307 whose Location is lost through the ingress, so the documented URL is/smart-doc/mcp/.surface/rule_name/mode/hit_count, values never stored).🤖 Generated with Claude Code