{"data":{"schema_version":"2026.08.29.install.3","public_base_url":"https://kb.deepsellers.com:8443","mcp_url":"https://kb.deepsellers.com:8443/mcp","agent_pack_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip","setup_prompt_url":"https://kb.deepsellers.com:8443/download/ask-agent-to-setup.txt","agent_bootstrap_url":"https://kb.deepsellers.com:8443/install/bootstrap.json","quickstart_url":"https://kb.deepsellers.com:8443/install/quickstart.json","install_wizard_url":"https://kb.deepsellers.com:8443/install/wizard","install_wizard_json_url":"https://kb.deepsellers.com:8443/install/wizard.json","install_metadata_url":"https://kb.deepsellers.com:8443/install.json","client_mode_matrix_url":"https://kb.deepsellers.com:8443/install/client-matrix.json","manifest_url":"https://kb.deepsellers.com:8443/download/agent-pack-manifest.json","sha256_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip.sha256","client_report_url":"https://kb.deepsellers.com:8443/v1/client-report","pack_version":"2026.09.07.1","server_name":"deepsellers-kb","quality_contract":"2026.08.25.quality.8","answer_quality_contract":"2026.08.26.answer-quality.6","token_policy":{"token_required":true,"token_placeholder":"PASTE_CUSTOMER_TOKEN_HERE","env_var":"ALLEN_KB_TOKEN","put_token_in_args":false,"send_token_separately":true,"token_values_returned":false},"automation_contract":{"schema_version":"2026.08.29.agent-automation.3","agent_may_install_without_more_questions":true,"agent_may_upgrade_without_more_questions":true,"read_install_metadata_first":true,"read_client_mode_matrix_first":true,"check_client_compatibility_first":true,"client_mode_matrix_url":"https://kb.deepsellers.com:8443/install/client-matrix.json","client_compatibility_url":"https://kb.deepsellers.com:8443/install/compatibility","client_report_url":"https://kb.deepsellers.com:8443/v1/client-report","agent_bootstrap_url":"https://kb.deepsellers.com:8443/install/bootstrap.json","quickstart_url":"https://kb.deepsellers.com:8443/install/quickstart.json","install_wizard_json_url":"https://kb.deepsellers.com:8443/install/wizard.json","stable_install_dir_required":true,"sha256_verification_required":true,"upgrade_supported":true,"upgrade_script":"upgrade_mcp.py","upgrade_metadata_url":"https://kb.deepsellers.com:8443/install.json","token_storage":"env.ALLEN_KB_TOKEN","token_in_args_forbidden":true,"token_in_logs_forbidden":true,"self_test_required":true,"restart_agent_required":true,"trust_connector_when_prompted":true,"success_requires_answer_check":true},"client_version_policy":{"schema_version":"2026.08.29.client-version-policy.1","latest_agent_pack_version":"2026.09.07.1","minimum_agent_pack_version":"2026.09.07.1","required_quality_contract_version":"2026.08.25.quality.8","minimum_quality_contract_version":"2026.08.25.quality.8","required_answer_quality_contract_version":"2026.08.26.answer-quality.6","minimum_answer_quality_contract_version":"2026.08.26.answer-quality.6","required_bridge_version":"0.4.0","version_headers":{"agent_pack_version":"X-DeepSellers-Agent-Pack-Version","quality_contract_version":"X-DeepSellers-KB-Quality-Contract","answer_quality_contract_version":"X-DeepSellers-KB-Answer-Contract","bridge_version":"X-DeepSellers-KB-Bridge-Version"},"agent_decision_rules":{"unknown_version":"run upgrade_mcp.py --client auto, then install_diagnose.py --self-test","pack_version_mismatch":"upgrade agent-pack.zip from install_metadata.agent_pack_url","quality_contract_mismatch":"upgrade and rerun setup_mcp.py so quality headers are current","answer_quality_contract_mismatch":"upgrade and verify kb_answer_check acceptance checks","compatible":"continue using the current install and keep sending version headers"},"token_values_returned":false,"secret_material_returned":false},"client_mode_matrix":{"schema_version":"2026.08.29.client-mode-matrix.1","status":"ready","server_name":"deepsellers-kb","mcp_url":"https://kb.deepsellers.com:8443/mcp","token_env_var":"ALLEN_KB_TOKEN","token_values_returned":false,"decision_order":[{"id":"native_remote_http","use_when":"The Agent client explicitly supports JSON-RPC HTTP POST MCP with bearer token or secret-store auth and does not require a long-lived SSE session.","recommended":false,"transport":"remote-http","config_template":"mcp-config.remote-http-template.json","mcp_url":"https://kb.deepsellers.com:8443/mcp","customer_steps":["store the customer token in the client secret store or env.ALLEN_KB_TOKEN","configure the Remote/HTTP MCP URL","keep version headers when the client supports custom headers","restart/trust the connector if required"],"fallback_if_failed":"local_stdio_bridge"},{"id":"workbuddy_codex_auto","use_when":"The Agent is WorkBuddy or Codex, or the Agent can run setup_mcp.py and write its own MCP config.","recommended":true,"transport":"local-stdio-bridge","setup_command":"python setup_mcp.py --client auto","requires_agent_pack":true,"requires_restart":true,"requires_trust_when_prompted":true,"fallback_if_failed":"generic_stdio"},{"id":"generic_stdio","use_when":"The Agent only accepts a local stdio MCP server config.","recommended":false,"transport":"local-stdio-bridge","setup_command":"python setup_mcp.py --client generic","config_artifacts":["generic-stdio-mcp-config.json","generic-stdio-mcp-config.toml"],"fallback_if_failed":"ask_customer_for_client_logs_without_token"}],"profiles":{"workbuddy":{"default_choice":"workbuddy_codex_auto","why":"WorkBuddy starts local stdio connectors more reliably than native Remote/HTTP for this service and requires Trust/enable after config changes.","must_not":["hard-code another user's absolute path","put token in args","leave placeholders in command"]},"codex":{"default_choice":"workbuddy_codex_auto","why":"Codex should use the local stdio bridge for a stable live RPC channel and env.ALLEN_KB_TOKEN for auth.","must_not":["put token in args","skip install_diagnose.py --self-test"]},"remote-http-capable":{"default_choice":"native_remote_http","why":"Use only when the client supports this service's JSON-RPC HTTP POST transport and can store Authorization headers securely.","must_not":["use port 443 before ICP filing is complete","send the token in public chat or screenshots"]},"unknown":{"default_choice":"workbuddy_codex_auto","why":"Auto setup can detect supported local clients and generate generic stdio fallback files.","must_not":["ask the user many setup questions before reading install metadata"]}},"agent_auto_decision_rules":["First read /install/bootstrap.json, /install/client-matrix.json, /install/wizard.json, and /install.json.","If the client is WorkBuddy or Codex, choose workbuddy_codex_auto and run setup_mcp.py --client auto.","Choose native_remote_http only when the client explicitly supports JSON-RPC HTTP POST MCP with secure Authorization headers and does not require an SSE session.","If only stdio MCP config is supported, choose generic_stdio and import the generated config artifact.","If setup fails, follow self_healing_contract.repair_sequence before asking the customer for more input.","If repair still fails, export the safe support bundle and report only redacted diagnostics."],"self_healing_contract":{"schema_version":"2026.08.29.agent-self-healing.1","status":"ready","mcp_url":"https://kb.deepsellers.com:8443/mcp","safe_endpoint":"https://kb.deepsellers.com:8443/mcp","do_not_try_443_until_icp_restored":true,"token_env_var":"ALLEN_KB_TOKEN","diagnostic_command":"python install_diagnose.py --self-test","upgrade_command":"python upgrade_mcp.py --client auto","support_bundle_url":"https://kb.deepsellers.com:8443/portal/support-bundle?format=text&days=30","client_matrix_url":"https://kb.deepsellers.com:8443/install/client-matrix.json","wizard_url":"https://kb.deepsellers.com:8443/install/wizard.json","agent_may_repair_without_more_questions":true,"repair_sequence":[{"id":"verify_endpoint","trigger":"tls_reset_on_443 or connection_closed_before_mcp_initialize","action":"Use the safe 8443 endpoint from mcp_url and do not switch to 443 until ICP filing is complete.","success":"HTTPS health or MCP initialize reaches kb.deepsellers.com:8443."},{"id":"verify_token_env","trigger":"401 or unauthorized","action":"Check that ALLEN_KB_TOKEN exists in the Agent process environment or local secret store without printing it.","success":"Token is present, not in args, and not printed in logs."},{"id":"rerun_setup","trigger":"stuck_connecting, connection_closed, tools_missing, placeholder_path_detected","action":"From the stable install directory, run setup_mcp.py --client auto for WorkBuddy/Codex or --client generic for stdio-only clients.","success":"Config uses an absolute Python path, stable remote_bridge.py path, and env.ALLEN_KB_TOKEN."},{"id":"restart_and_trust","trigger":"configured_but_tools_missing or client_shows_pending_connector","action":"Fully quit and reopen the Agent, then trust/enable deepsellers-kb when the client asks.","success":"Tools list includes kb_context, kb_answer_check, and kb_search."},{"id":"run_live_quality_check","trigger":"tools_present_after_setup","action":"Ask the test question, call kb_context first, draft an answer, then call kb_answer_check with the context packet.","success":"context_quality.ok=true, relevance_pass=true, answer_check_ok=true, and answer_check_citation_coverage_pass=true."},{"id":"export_safe_support_bundle","trigger":"repair_sequence_failed","action":"Use support_bundle_url with the customer's bearer token and send the downloaded text to DeepSellers support.","success":"Support bundle is generated and contains no raw token or secret material."}],"error_map":{"401":"Token is missing, expired, revoked, or not visible to the MCP process.","403":"Token scope, customer permission, or optional IP policy does not allow the request.","429":"Minute rate limit, daily quota, or concurrency cap was reached.","connection_closed":"Local stdio bridge crashed or endpoint/TLS setup failed before MCP initialization.","stuck_connecting":"Agent did not restart/trust the connector or local config still points at a bad command path.","tls_reset_on_443":"Domestic 80/443 SNI access is unavailable until ICP filing is complete; keep 8443.","tools_missing":"MCP config was not loaded, connector is not trusted, or setup wrote to the wrong client profile."},"reporting_rules":["Never print the full token in diagnostics, logs, screenshots, or support messages.","Report only redacted token presence, chosen client mode, config file path, tool list, and acceptance markers.","If support is needed, export /portal/support-bundle?format=text&days=30 instead of sending local config with secrets."],"secret_material_returned":false},"failure_triage":[{"symptom":"stuck_connecting","likely_cause":"client did not restart, connector not trusted, or local stdio bridge is waiting on a bad command path","safe_action":"fully quit the Agent, reopen it, trust/enable deepsellers-kb, then run install_diagnose.py --self-test"},{"symptom":"connection_closed","likely_cause":"stdio bridge crashed because Python path, script path, or token env is wrong","safe_action":"rerun setup_mcp.py --client auto from the stable install directory; do not hand-edit token into args"},{"symptom":"tls_reset_on_443","likely_cause":"kb.deepsellers.com 80/443 SNI access is blocked until ICP filing is complete","safe_action":"use https://kb.deepsellers.com:8443/mcp until ICP filing restores 443"},{"symptom":"401","likely_cause":"token missing, expired, revoked, or not available to the MCP process environment","safe_action":"verify ALLEN_KB_TOKEN exists locally without printing it; request rotation if needed"},{"symptom":"429","likely_cause":"minute rate limit, daily quota, or concurrency limit reached","safe_action":"wait for quota reset or upgrade the customer plan"}],"acceptance":{"required_tools":["kb_context","kb_answer_check","kb_search"],"required_order":["kb_context","kb_answer_check","kb_search"],"do_not_use_search_only":true,"test_question":"如何优化亚马逊广告结构？","success_markers":["context_quality.ok=true","relevance_pass=true","answer_quality_contract_ok=true","answer_check_ok=true","answer_check_citation_coverage_pass=true","no_token_in_args_or_logs"]},"user_prompt_short":"请自动接入 DeepSellers KB。先读取 /install/bootstrap.json、/install/client-matrix.json、/install/wizard.json 和 /install.json；WorkBuddy/Codex 默认下载 Agent Pack 后用 ALLEN_KB_TOKEN 运行 setup_mcp.py --client auto；只有客户端明确支持 JSON-RPC HTTP POST MCP 且能安全保存 Authorization Header 时，才直接连 https://kb.deepsellers.com:8443/mcp；如连接失败，按 self_healing_contract.repair_sequence 自愈并导出安全支持包；不要输出完整 token，完成后用 kb_context 和 kb_answer_check 自测。","secret_material_returned":false},"client_compatibility_url":"https://kb.deepsellers.com:8443/install/compatibility","client_compatibility_without_headers":{"schema_version":"2026.08.29.client-compatibility.1","status":"upgrade_required","upgrade_required":true,"reasons":["agent_pack_version_missing","quality_contract_version_missing","answer_quality_contract_version_missing","bridge_version_missing"],"current":{"agent_pack_version":null,"quality_contract_version":null,"answer_quality_contract_version":null,"bridge_version":null},"required":{"agent_pack_version":"2026.09.07.1","quality_contract_version":"2026.08.25.quality.8","answer_quality_contract_version":"2026.08.26.answer-quality.6","bridge_version":"0.4.0"},"recommended_action":"Run upgrade_mcp.py --client auto, keep ALLEN_KB_TOKEN in the environment, restart/trust the Agent, then run install_diagnose.py --self-test.","upgrade_plan":{"schema_version":"2026.08.29.upgrade-plan.1","server_name":"deepsellers-kb","latest_pack_version":"2026.09.07.1","metadata_url":"https://kb.deepsellers.com:8443/install.json","agent_pack_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip","sha256_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip.sha256","expected_sha256":"093af03831655c22336f91b57ac2a9a1d361243034ac5fab4522b4c2b98152b5","verify_sha256":true,"script":"upgrade_mcp.py","token_env_var":"ALLEN_KB_TOKEN","token_values_returned":false,"token_in_args":false,"command":"ALLEN_KB_TOKEN=<customer-token> python upgrade_mcp.py --client auto","steps":["read /install.json before upgrading","download agent-pack.zip","verify SHA256 when expected_sha256 is present","back up the existing stable install directory","preserve generated generic stdio configs when present","extract the latest pack into the stable install directory","rerun setup_mcp.py with ALLEN_KB_TOKEN from the environment","restart the Agent and trust/enable deepsellers-kb when prompted"],"acceptance":{"required_tools":["kb_context","kb_answer_check","kb_search"],"preferred_first_tool":"kb_context","required_final_check":"kb_answer_check","minimum_success":["latest_pack_version_installed","sha256_verified","setup_reran_successfully","no_token_in_args_or_logs","kb_context_returns_context_packet","kb_answer_check_reports_answer_check_ok"]}},"token_values_returned":false,"secret_material_returned":false},"install_plan":{"schema_version":"2026.08.27.install-plan.1","server_name":"deepsellers-kb","pack_version":"2026.09.07.1","token_env_var":"ALLEN_KB_TOKEN","token_values_returned":false,"stable_install_dirs":{"windows":"%USERPROFILE%\\.deepsellers-kb\\mcp-server","macos":"~/.deepsellers-kb/mcp-server","linux":"~/.deepsellers-kb/mcp-server"},"download":{"agent_pack_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip","manifest_url":"https://kb.deepsellers.com:8443/download/agent-pack-manifest.json","sha256_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip.sha256","expected_sha256":"093af03831655c22336f91b57ac2a9a1d361243034ac5fab4522b4c2b98152b5","verify_sha256":true},"steps":[{"id":"read_metadata","description":"Read /install.json and follow this machine-readable plan.","required":true},{"id":"download_pack","description":"Download agent-pack.zip and verify SHA256 when expected_sha256 is present.","required":true},{"id":"extract_stable_dir","description":"Extract into the current user's stable install directory, not a temp/download directory.","required":true},{"id":"set_token_env","description":"Set ALLEN_KB_TOKEN in the Agent environment; never place the token in args, logs, or chat output.","required":true},{"id":"run_setup","description":"Run setup_mcp.py with --client auto for WorkBuddy/Codex, or --client generic for stdio-only clients.","required":true},{"id":"self_test","description":"Run install_diagnose.py --self-test after configuration and before handing back to the user.","required":true},{"id":"restart_trust","description":"Restart the Agent and enable/trust the deepsellers-kb connector if the client requires approval.","required":true}],"commands":{"auto":{"description":"Recommended for WorkBuddy and Codex.","command":"python setup_mcp.py --client auto","requires_env":{"ALLEN_KB_TOKEN":"<customer-token>"}},"generic_stdio":{"description":"Fallback for Agents that only support local stdio MCP.","command":"python setup_mcp.py --client generic","requires_env":{"ALLEN_KB_TOKEN":"<customer-token>"},"output_config":"generic-stdio-mcp-config.json"},"diagnose":{"description":"Run after setup to prove the bridge and quality contract.","command":"python install_diagnose.py --self-test","requires_env":{"ALLEN_KB_TOKEN":"<customer-token>"}}},"client_targets":[{"id":"workbuddy","preferred_command":"python setup_mcp.py --client auto","requires_restart":true,"requires_trust":true,"expected_tools":["kb_context","kb_answer_check","kb_search"]},{"id":"codex","preferred_command":"python setup_mcp.py --client auto","requires_restart":true,"requires_trust":false,"expected_tools":["kb_context","kb_answer_check","kb_search"]},{"id":"generic-stdio","preferred_command":"python setup_mcp.py --client generic","requires_restart":true,"requires_trust":null,"expected_tools":["kb_context","kb_answer_check","kb_search"]}],"failure_diagnosis":[{"symptom":"401","likely_cause":"token missing, expired, revoked, or written to the wrong environment"},{"symptom":"403","likely_cause":"token scope or customer permission does not allow the requested tool"},{"symptom":"429","likely_cause":"minute rate limit, daily quota, or concurrency limit reached"},{"symptom":"Connection closed","likely_cause":"client stdio bridge crashed or endpoint TLS/network failed"},{"symptom":"tools missing","likely_cause":"Agent was not restarted or connector was not trusted/enabled"}],"acceptance":{"required_tools":["kb_context","kb_answer_check","kb_search"],"preferred_first_tool":"kb_context","required_final_check":"kb_answer_check","test_question":"如何优化亚马逊广告结构？","minimum_success":["tool_list_contains_required_tools","kb_context_returns_context_packet","kb_answer_check_reports_answer_check_ok","no_token_in_args_or_logs"]}},"upgrade_plan":{"schema_version":"2026.08.29.upgrade-plan.1","server_name":"deepsellers-kb","latest_pack_version":"2026.09.07.1","metadata_url":"https://kb.deepsellers.com:8443/install.json","agent_pack_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip","sha256_url":"https://kb.deepsellers.com:8443/download/agent-pack.zip.sha256","expected_sha256":"093af03831655c22336f91b57ac2a9a1d361243034ac5fab4522b4c2b98152b5","verify_sha256":true,"script":"upgrade_mcp.py","token_env_var":"ALLEN_KB_TOKEN","token_values_returned":false,"token_in_args":false,"command":"ALLEN_KB_TOKEN=<customer-token> python upgrade_mcp.py --client auto","steps":["read /install.json before upgrading","download agent-pack.zip","verify SHA256 when expected_sha256 is present","back up the existing stable install directory","preserve generated generic stdio configs when present","extract the latest pack into the stable install directory","rerun setup_mcp.py with ALLEN_KB_TOKEN from the environment","restart the Agent and trust/enable deepsellers-kb when prompted"],"acceptance":{"required_tools":["kb_context","kb_answer_check","kb_search"],"preferred_first_tool":"kb_context","required_final_check":"kb_answer_check","minimum_success":["latest_pack_version_installed","sha256_verified","setup_reran_successfully","no_token_in_args_or_logs","kb_context_returns_context_packet","kb_answer_check_reports_answer_check_ok"]}},"client_report_plan":{"schema_version":"2026.08.29.client-report-plan.1","endpoint":"https://kb.deepsellers.com:8443/v1/client-report","method":"POST","auth":"Bearer token in Authorization header","token_env_var":"ALLEN_KB_TOKEN","send_after_setup":true,"send_after_upgrade":true,"send_after_diagnose":true,"token_values_returned":false,"minimum_fields":["agent_pack_version","quality_contract_version","answer_quality_contract_version","bridge_version","client"]},"client_modes":[{"id":"workbuddy","label":"WorkBuddy","recommended":true,"setup_command":"ALLEN_KB_TOKEN=<customer-token> python setup_mcp.py --client auto","config_strategy":"auto-detect WorkBuddy MCP config and write env.ALLEN_KB_TOKEN"},{"id":"codex","label":"Codex","recommended":true,"setup_command":"ALLEN_KB_TOKEN=<customer-token> python setup_mcp.py --client auto","config_strategy":"auto-detect Codex MCP config and write env.ALLEN_KB_TOKEN"},{"id":"generic-stdio","label":"Generic stdio MCP","recommended":false,"setup_command":"ALLEN_KB_TOKEN=<customer-token> python setup_mcp.py --client generic","config_strategy":"use mcp-config.generic-stdio-template.json or mcp-config.generic-stdio-template.toml"}],"required_tool_order":["kb_context","kb_answer_check","kb_search"],"primary_tool":"kb_context","answer_check_tool":"kb_answer_check","secondary_tool":"kb_search","acceptance_checks":["tools include kb_context, kb_answer_check, and kb_search","context_quality.ok=true","relevance_pass=true","answer_quality_contract_ok=true","knowledge_map_entrypoint_ok=true","minimum_evidence_pass=true","source_diversity_pass=true","answer_check_ok=true","answer_check_citation_coverage_pass=true"],"sha256":"093af03831655c22336f91b57ac2a9a1d361243034ac5fab4522b4c2b98152b5","token_values_returned":false,"secret_material_returned":false}}