From a4afb3a501e76c00dd7f3e0fb1b302a51d127e48 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Mon, 1 Jun 2026 16:09:24 +0800 Subject: [PATCH] docs: rebuild documentation site on Fumadocs (bilingual zh/en) Replace the MkDocs Material site with a Fumadocs (Next.js) project. - Bilingual content (Chinese default + English) with i18n routing, language switcher, localized UI and page-action buttons, and Mandarin-tokenized static search. - Migrate ~54 pages from MkDocs markdown to MDX (admonitions -> Callout, content tabs -> Tabs, collapsibles -> Accordions, inlined --8<-- examples, Mermaid, Video), merging richer code examples from the AgentKit GitBook. - New pages: A2UI + VeADK frontend, Agent Skills, A2A Hub, middleware events, built-in MCP tools, system tools, Langchain, AgentKit CLI, API reference, observability overview, installation, local debugging. - Google-ADK-style navigation: root dropdown (Framework / CLI / Reference) with grouped sidebar sections. - Static export for GitHub Pages with base-path handling (assets, MDX images, root redirect, .nojekyll); the POST chat route is excluded from export. - Update the deploy-docs workflow to build the Fumadocs static site on Node 22. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/deploy-docs.yaml | 57 +- .gitignore | 4 +- .gitleaks.toml | 8 +- docs/.gitignore | 204 +- docs/README.md | 47 + docs/app/[lang]/(home)/layout.tsx | 14 + docs/app/[lang]/(home)/page.tsx | 37 + docs/app/[lang]/docs/[[...slug]]/page.tsx | 71 + docs/app/[lang]/docs/layout.tsx | 49 + docs/app/[lang]/layout.tsx | 28 + docs/app/api/chat/route.ts | 108 + docs/app/api/search/route.ts | 17 + docs/app/global.css | 12 + docs/app/layout.tsx | 11 + docs/app/llms-full.txt/route.ts | 11 + docs/app/llms.mdx/docs/[[...slug]]/route.ts | 24 + docs/app/llms.txt/route.ts | 8 + docs/app/og/docs/[...slug]/route.tsx | 28 + docs/app/page.tsx | 17 + docs/biome.json | 41 + docs/components/ai/search.tsx | 477 ++ docs/components/html-lang.tsx | 12 + docs/components/markdown.tsx | 116 + docs/components/mdx.tsx | 39 + docs/components/mdx/mermaid.tsx | 56 + docs/components/mdx/video.tsx | 24 + docs/components/provider.tsx | 8 + docs/components/search.tsx | 53 + docs/components/ui/button.tsx | 29 + docs/content/docs/cli/agentkit-cli.en.mdx | 48 + docs/content/docs/cli/agentkit-cli.mdx | 48 + docs/content/docs/cli/index.en.mdx | 11 + docs/content/docs/cli/index.mdx | 11 + docs/content/docs/cli/meta.en.json | 6 + docs/content/docs/cli/meta.json | 6 + docs/content/docs/cli/veadk-cli.en.mdx | 609 ++ .../cli.md => content/docs/cli/veadk-cli.mdx} | 154 +- .../docs/framework/agent/create.en.mdx | 332 + docs/content/docs/framework/agent/create.mdx | 332 + .../content/docs/framework/agent/meta.en.json | 4 + docs/content/docs/framework/agent/meta.json | 4 + .../agent/multi-agent/a2a-hub.en.mdx | 78 + .../framework/agent/multi-agent/a2a-hub.mdx | 78 + .../framework/agent/multi-agent/a2a.en.mdx | 270 + .../docs/framework/agent/multi-agent/a2a.mdx} | 179 +- .../framework/agent/multi-agent/meta.en.json | 4 + .../framework/agent/multi-agent/meta.json | 4 + .../multi-agent/middleware-events.en.mdx | 127 + .../agent/multi-agent/middleware-events.mdx | 127 + .../agent/multi-agent/overview.en.mdx | 408 ++ .../framework/agent/multi-agent/overview.mdx | 408 ++ .../docs/framework/agent/overview.en.mdx | 62 + .../content/docs/framework/agent/overview.mdx | 62 + .../docs/framework/agent/prompt.en.mdx | 65 + .../docs/framework/agent/prompt.mdx} | 16 +- .../docs/framework/agent/responses-api.en.mdx | 363 ++ .../docs/framework/agent/responses-api.mdx | 363 ++ .../docs/framework/agent/skills.en.mdx | 108 + docs/content/docs/framework/agent/skills.mdx | 108 + .../framework/community/ide-support.en.mdx | 22 + .../docs/framework/community/ide-support.mdx} | 9 +- .../docs/framework/community/langchain.en.mdx | 80 + .../docs/framework/community/langchain.mdx | 80 + .../docs/framework/community/meta.en.json | 4 + .../docs/framework/community/meta.json | 4 + .../docs/framework/configuration.en.mdx | 198 + docs/content/docs/framework/configuration.mdx | 198 + .../docs/framework/deploy/agentkit.en.mdx | 20 + .../docs/framework/deploy/agentkit.mdx} | 5 +- .../docs/framework/deploy/meta.en.json | 4 + docs/content/docs/framework/deploy/meta.json | 4 + .../docs/framework/deploy/vefaas.en.mdx | 548 ++ .../docs/framework/deploy/vefaas.mdx} | 220 +- .../docs/framework/enterprise-design.en.mdx | 111 + .../docs/framework/enterprise-design.mdx | 111 + .../eval-optimization/evaluation.en.mdx | 342 + .../eval-optimization/evaluation.mdx} | 122 +- .../framework/eval-optimization/meta.en.json | 4 + .../framework/eval-optimization/meta.json | 4 + .../eval-optimization/optimization.en.mdx | 250 + .../eval-optimization/optimization.mdx} | 74 +- .../docs/framework/frontend/a2ui.en.mdx | 107 + docs/content/docs/framework/frontend/a2ui.mdx | 107 + .../docs/framework/frontend/meta.en.json | 4 + .../content/docs/framework/frontend/meta.json | 4 + .../docs/framework/frontend/web-ui.en.mdx | 97 + .../docs/framework/frontend/web-ui.mdx | 97 + .../framework/gallery/agent-gallery.en.mdx | 25 + .../docs/framework/gallery/agent-gallery.mdx | 25 + .../docs/framework/gallery/app-gallery.en.mdx | 10 + .../docs/framework/gallery/app-gallery.mdx | 10 + .../docs/framework/gallery/meta.en.json | 4 + docs/content/docs/framework/gallery/meta.json | 4 + .../getting-started/installation.en.mdx | 92 + .../getting-started/installation.mdx | 92 + .../getting-started/local-debugging.en.mdx | 54 + .../getting-started/local-debugging.mdx | 54 + .../framework/getting-started/meta.en.json | 4 + .../docs/framework/getting-started/meta.json | 4 + .../getting-started/quickstart.en.mdx | 73 + .../framework/getting-started/quickstart.mdx | 73 + docs/content/docs/framework/index.en.mdx | 11 + docs/content/docs/framework/index.mdx | 11 + .../docs/framework/introduction.en.mdx | 111 + .../docs/framework/introduction.mdx} | 9 +- .../knowledgebase/best-practice.en.mdx | 187 + .../knowledgebase/best-practice.mdx} | 11 +- .../docs/framework/knowledgebase/meta.en.json | 4 + .../docs/framework/knowledgebase/meta.json | 4 + .../framework/knowledgebase/overview.en.mdx | 803 +++ .../docs/framework/knowledgebase/overview.mdx | 803 +++ .../framework/memory/best-practice.en.mdx | 91 + .../docs/framework/memory/best-practice.mdx} | 43 +- .../docs/framework/memory/long-term.en.mdx | 465 ++ .../docs/framework/memory/long-term.mdx | 465 ++ .../docs/framework/memory/meta.en.json | 4 + docs/content/docs/framework/memory/meta.json | 4 + .../docs/framework/memory/short-term.en.mdx | 280 + .../docs/framework/memory/short-term.mdx | 280 + docs/content/docs/framework/meta.en.json | 31 + docs/content/docs/framework/meta.json | 31 + .../docs/framework/observability/meta.en.json | 4 + .../docs/framework/observability/meta.json | 4 + .../framework/observability/overview.en.mdx | 52 + .../docs/framework/observability/overview.mdx | 52 + .../observability/span-attributes.en.mdx | 92 + .../observability/span-attributes.mdx} | 12 +- .../framework/observability/tracing.en.mdx | 230 + .../docs/framework/observability/tracing.mdx} | 84 +- .../framework/observability/ve-tracing.en.mdx | 263 + .../framework/observability/ve-tracing.mdx} | 40 +- .../docs/framework/plugin/guardrail.en.mdx | 69 + .../docs/framework/plugin/guardrail.mdx} | 15 +- .../docs/framework/plugin/meta.en.json | 4 + docs/content/docs/framework/plugin/meta.json | 4 + docs/content/docs/framework/runner.en.mdx | 83 + .../docs/framework/runner.mdx} | 14 +- .../docs/framework/security/inbound.en.mdx | 288 + .../docs/framework/security/inbound.mdx} | 16 +- .../docs/framework/security/meta.en.json | 4 + .../content/docs/framework/security/meta.json | 4 + .../security/outbound/api-key.en.mdx | 96 + .../framework/security/outbound/api-key.mdx} | 11 +- .../framework/security/outbound/meta.en.json | 4 + .../framework/security/outbound/meta.json | 4 + .../security/outbound/oauth2-m2m.en.mdx | 118 + .../security/outbound/oauth2-m2m.mdx} | 11 +- .../outbound/oauth2-user-federation.en.mdx | 183 + .../outbound/oauth2-user-federation.mdx} | 11 +- .../security/outbound/trusted-mcp.en.mdx | 71 + .../security/outbound/trusted-mcp.mdx} | 16 +- .../docs/framework/security/overview.en.mdx | 100 + .../docs/framework/security/overview.mdx} | 13 +- .../security/permission-policy.en.mdx | 49 + .../framework/security/permission-policy.mdx} | 9 +- .../docs/framework/tools/builtin-mcp.en.mdx | 93 + .../docs/framework/tools/builtin-mcp.mdx | 93 + .../docs/framework/tools/builtin.en.mdx | 1088 ++++ docs/content/docs/framework/tools/builtin.mdx | 1088 ++++ .../framework/tools/custom-function.en.mdx | 276 + .../docs/framework/tools/custom-function.mdx} | 115 +- .../framework/tools/feishu-channel.en.mdx | 91 + .../docs/framework/tools/feishu-channel.mdx} | 40 +- .../content/docs/framework/tools/meta.en.json | 4 + docs/content/docs/framework/tools/meta.json | 4 + .../docs/framework/tools/system-tools.en.mdx | 60 + .../docs/framework/tools/system-tools.mdx | 60 + .../docs/framework/troubleshooting.en.mdx | 59 + .../docs/framework/troubleshooting.mdx | 59 + docs/content/docs/meta.en.json | 3 + docs/content/docs/meta.json | 3 + docs/content/docs/references/api.en.mdx | 39 + docs/content/docs/references/api.mdx | 39 + .../docs/references/contributing.en.mdx | 36 + .../docs/references/contributing.mdx} | 7 +- docs/content/docs/references/index.en.mdx | 12 + docs/content/docs/references/index.mdx | 12 + docs/content/docs/references/license.en.mdx | 6 + docs/content/docs/references/license.mdx | 6 + docs/content/docs/references/meta.en.json | 6 + docs/content/docs/references/meta.json | 6 + docs/docs/__init__.py | 1 - docs/docs/agent/__init__.py | 1 - docs/docs/agent/agent.md | 313 - docs/docs/agent/agents.md | 266 - docs/docs/agent/overview.md | 61 - docs/docs/agent/responses-api.md | 351 - docs/docs/agent/root_agent.py | 279 - docs/docs/configuration.md | 166 - docs/docs/design.md | 112 - docs/docs/gallery/agent-gallery.md | 42 - docs/docs/gallery/app-gallery.md | 9 - docs/docs/index.md | 179 - docs/docs/knowledgebase/overview.md | 670 -- docs/docs/memory/long-term-memory.md | 444 -- docs/docs/memory/short-term-memory.md | 269 - docs/docs/quickstart.md | 145 - docs/docs/references/license.md | 5 - docs/docs/stylesheets/extra.css | 118 - docs/docs/tools/builtin.md | 704 -- docs/docs/troubleshooting.md | 53 - docs/examples/agent/agent/simplest_agent.py | 23 - docs/examples/agent/agent/weather_reporter.py | 13 - .../agent/agent/weather_reporter_agent.yaml | 9 - docs/examples/agent/agents/llm_agent.go | 78 - docs/examples/agent/agents/llm_agent.py | 31 - docs/examples/agent/agents/loop_agent.py | 38 - docs/examples/agent/agents/parallel_agent.py | 23 - docs/examples/agent/agents/seq_agent.py | 23 - docs/examples/channel/feishu_bot.py | 32 - docs/examples/knowledge/viking_knowledge.go | 124 - docs/examples/memory/long_mem_viking_agent.py | 144 - docs/examples/memory/short_mem_mysql_agent.py | 29 - docs/examples/runner/run_async.py | 87 - docs/examples/runner/run_sync.py | 53 - .../function_tools/simple_function_tool.py | 46 - .../function_tools/tool_context_usage.py | 37 - docs/examples/tools/image_generate/agent.py | 40 - docs/examples/tools/lark/agent.py | 40 - docs/examples/tools/las/agent.py | 42 - docs/examples/tools/run_code/agent.py | 36 - docs/examples/tools/vesearch/agent.py | 36 - docs/examples/tools/video_generate/agent.py | 41 - docs/examples/tools/web_search/agent.go | 54 - docs/examples/tools/web_search/agent.py | 34 - docs/examples/tracing/tracing_exporter.py | 20 - docs/lib/chat-types.ts | 15 + docs/lib/cn.ts | 1 + docs/lib/i18n-ui.ts | 37 + docs/lib/i18n.ts | 8 + docs/lib/layout.shared.tsx | 23 + docs/lib/shared.ts | 20 + docs/lib/source.ts | 46 + docs/mkdocs.yml | 181 - docs/next.config.mjs | 28 + docs/package.json | 55 + docs/pnpm-lock.yaml | 5763 +++++++++++++++++ docs/postcss.config.mjs | 7 + .../assets/images/agents/a2a_querystring.png | Bin .../images/agents/cozeloop_prompt_mgr.png | Bin .../assets/images/agents/llm_agent.png | Bin .../assets/images/agents/loop_agent.png | Bin .../assets/images/agents/parallel_agent.png | Bin .../assets/images/agents/responses_api.png | Bin .../assets/images/agents/seq_agent.png | Bin .../assets/images/cli/cli_veadk_create.gif | Bin .../cli/cli_veadk_deploy_vefaas_log.png | Bin .../assets/images/cli/cli_veadk_init.gif | Bin .../assets/images/cli/cli_veadk_kb_add.gif | Bin .../assets/images/cli/cli_veadk_kb_test.gif | Bin .../assets/images/cli/cli_veadk_web.gif | Bin .../assets/images/cozeloop_prompt_key.png | Bin .../assets/images/deploy/add_permission.png | Bin .../assets/images/deploy/close_key_auth.png | Bin .../assets/images/deploy/cp_attach_role.png | Bin .../assets/images/deploy/cp_index.png | Bin .../assets/images/deploy/cp_open.png | Bin .../assets/images/deploy/cr_attach_role.png | Bin .../assets/images/deploy/cr_index.png | Bin .../assets/images/deploy/deploy_agent.png | Bin .../assets/images/deploy/key_auth_token.png | Bin .../images/deploy/veapig_attach_role.png | Bin .../assets/images/deploy/veapig_index.png | Bin .../images/deploy/vefaas_attach_role.png | Bin .../assets/images/deploy/vefaas_index.png | Bin .../assets/images/evaluation/veadk_eval.gif | Bin .../images/evaluation/veadk_web_eval.gif | Bin .../assets/images/faq/troubleshooting-01.png | Bin .../assets/images/faq/troubleshooting-02.png | Bin .../assets/images/faq/troubleshooting-03.jpeg | Bin .../assets/images/knowledge/image-1.png | Bin .../assets/images/knowledge/image-10.png | Bin .../assets/images/knowledge/image-11.png | Bin .../assets/images/knowledge/image-13.png | Bin .../assets/images/knowledge/image-14.png | Bin .../assets/images/knowledge/image-17.png | Bin .../assets/images/knowledge/image-18.png | Bin .../assets/images/knowledge/image-19.png | Bin .../assets/images/knowledge/image-20.png | Bin .../assets/images/knowledge/image-21.png | Bin .../assets/images/knowledge/image-22.png | Bin .../assets/images/knowledge/image-3.png | Bin .../assets/images/knowledge/image-4.png | Bin .../assets/images/knowledge/image-5.png | Bin .../assets/images/knowledge/image-6.png | Bin .../assets/images/knowledge/image-7.png | Bin .../assets/images/knowledge/image-8.png | Bin .../assets/images/knowledge/image-9.png | Bin .../assets/images/knowledge/image.png | Bin .../assets/images/knowledge/kb-bp-1.jpeg | Bin .../assets/images/knowledge/kb-bp-2.jpeg | Bin .../assets/images/observation/apm-console.png | Bin .../assets/images/observation/apm-metrics.png | Bin .../assets/images/observation/apm-session.png | Bin .../assets/images/observation/apm-trace.png | Bin .../images/observation/coze-console.png | Bin .../images/observation/coze-spaceid.png | Bin .../assets/images/observation/coze-trace.png | Bin .../images/observation/show_traceid.jpeg | Bin .../assets/images/observation/tls-console.png | Bin .../assets/images/observation/tls-context.png | Bin .../assets/images/observation/tls-model.png | Bin .../assets/images/observation/tls-project.png | Bin .../assets/images/observation/tls-tools.png | Bin .../assets/images/observation/tls-topic.png | Bin .../assets/images/observation/tls-trace.png | Bin .../images/optimization/lightning_client.png | Bin .../lightning_training_server.png | Bin .../assets/images/optimization/logs.png | Bin .../images/optimization/submit_task.png | Bin .../assets/images/optimization/timeline.png | Bin .../assets/images/optimization/training.png | Bin .../assets/images/overview/agent-overview.png | Bin .../assets/images/overview/veadk-web.png | Bin .../assets/images/tools/agentkittools1.png | Bin .../assets/images/tools/agentkittools2.png | Bin .../assets/images/tools/agentkittools3.png | Bin .../assets/images/tools/cat.jpeg | Bin .../long_running_tool_result.jpeg | Bin .../function_tools/simple_tool_result.png | Bin .../function_tools/tool_context_result.jpg | Bin .../assets/images/tools/image_generate.png | Bin .../assets/images/tools/lark1.png | Bin .../assets/images/tools/lark2.png | Bin .../assets/images/tools/las1.png | Bin .../assets/images/tools/las2.png | Bin .../assets/images/tools/mua_1.png | Bin .../assets/images/tools/mua_2.png | Bin .../assets/images/tools/mua_3.png | Bin .../assets/images/tools/run_code1.png | Bin .../assets/images/tools/run_code1.png.jpg | Bin .../assets/images/tools/run_code2.png | Bin .../assets/images/tools/vesearch.png | Bin .../assets/images/tools/video_generate.gif | Bin .../assets/images/tools/video_generate.png | Bin .../assets/images/tools/video_generate1.png | Bin .../assets/images/tools/video_generate2.png | Bin .../assets/images/tools/web_search.png | Bin .../assets/images/trae_rules.png | Bin .../assets/images/uv_demo.jpeg | Bin .../assets/images/volcengine-color.svg | 0 docs/requirements.txt | 12 - docs/scripts/build-static.mjs | 57 + docs/source.config.ts | 51 + docs/tsconfig.json | 35 + 345 files changed, 23766 insertions(+), 6236 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/app/[lang]/(home)/layout.tsx create mode 100644 docs/app/[lang]/(home)/page.tsx create mode 100644 docs/app/[lang]/docs/[[...slug]]/page.tsx create mode 100644 docs/app/[lang]/docs/layout.tsx create mode 100644 docs/app/[lang]/layout.tsx create mode 100644 docs/app/api/chat/route.ts create mode 100644 docs/app/api/search/route.ts create mode 100644 docs/app/global.css create mode 100644 docs/app/layout.tsx create mode 100644 docs/app/llms-full.txt/route.ts create mode 100644 docs/app/llms.mdx/docs/[[...slug]]/route.ts create mode 100644 docs/app/llms.txt/route.ts create mode 100644 docs/app/og/docs/[...slug]/route.tsx create mode 100644 docs/app/page.tsx create mode 100644 docs/biome.json create mode 100644 docs/components/ai/search.tsx create mode 100644 docs/components/html-lang.tsx create mode 100644 docs/components/markdown.tsx create mode 100644 docs/components/mdx.tsx create mode 100644 docs/components/mdx/mermaid.tsx create mode 100644 docs/components/mdx/video.tsx create mode 100644 docs/components/provider.tsx create mode 100644 docs/components/search.tsx create mode 100644 docs/components/ui/button.tsx create mode 100644 docs/content/docs/cli/agentkit-cli.en.mdx create mode 100644 docs/content/docs/cli/agentkit-cli.mdx create mode 100644 docs/content/docs/cli/index.en.mdx create mode 100644 docs/content/docs/cli/index.mdx create mode 100644 docs/content/docs/cli/meta.en.json create mode 100644 docs/content/docs/cli/meta.json create mode 100644 docs/content/docs/cli/veadk-cli.en.mdx rename docs/{docs/cli.md => content/docs/cli/veadk-cli.mdx} (82%) create mode 100644 docs/content/docs/framework/agent/create.en.mdx create mode 100644 docs/content/docs/framework/agent/create.mdx create mode 100644 docs/content/docs/framework/agent/meta.en.json create mode 100644 docs/content/docs/framework/agent/meta.json create mode 100644 docs/content/docs/framework/agent/multi-agent/a2a-hub.en.mdx create mode 100644 docs/content/docs/framework/agent/multi-agent/a2a-hub.mdx create mode 100644 docs/content/docs/framework/agent/multi-agent/a2a.en.mdx rename docs/{docs/agent/agent-to-agent.md => content/docs/framework/agent/multi-agent/a2a.mdx} (62%) create mode 100644 docs/content/docs/framework/agent/multi-agent/meta.en.json create mode 100644 docs/content/docs/framework/agent/multi-agent/meta.json create mode 100644 docs/content/docs/framework/agent/multi-agent/middleware-events.en.mdx create mode 100644 docs/content/docs/framework/agent/multi-agent/middleware-events.mdx create mode 100644 docs/content/docs/framework/agent/multi-agent/overview.en.mdx create mode 100644 docs/content/docs/framework/agent/multi-agent/overview.mdx create mode 100644 docs/content/docs/framework/agent/overview.en.mdx create mode 100644 docs/content/docs/framework/agent/overview.mdx create mode 100644 docs/content/docs/framework/agent/prompt.en.mdx rename docs/{docs/agent/prompt.md => content/docs/framework/agent/prompt.mdx} (80%) create mode 100644 docs/content/docs/framework/agent/responses-api.en.mdx create mode 100644 docs/content/docs/framework/agent/responses-api.mdx create mode 100644 docs/content/docs/framework/agent/skills.en.mdx create mode 100644 docs/content/docs/framework/agent/skills.mdx create mode 100644 docs/content/docs/framework/community/ide-support.en.mdx rename docs/{docs/ide/txt.md => content/docs/framework/community/ide-support.mdx} (70%) create mode 100644 docs/content/docs/framework/community/langchain.en.mdx create mode 100644 docs/content/docs/framework/community/langchain.mdx create mode 100644 docs/content/docs/framework/community/meta.en.json create mode 100644 docs/content/docs/framework/community/meta.json create mode 100644 docs/content/docs/framework/configuration.en.mdx create mode 100644 docs/content/docs/framework/configuration.mdx create mode 100644 docs/content/docs/framework/deploy/agentkit.en.mdx rename docs/{docs/deploy/deploy-agentkit.md => content/docs/framework/deploy/agentkit.mdx} (79%) create mode 100644 docs/content/docs/framework/deploy/meta.en.json create mode 100644 docs/content/docs/framework/deploy/meta.json create mode 100644 docs/content/docs/framework/deploy/vefaas.en.mdx rename docs/{docs/deploy/deploy-vefaas.md => content/docs/framework/deploy/vefaas.mdx} (67%) create mode 100644 docs/content/docs/framework/enterprise-design.en.mdx create mode 100644 docs/content/docs/framework/enterprise-design.mdx create mode 100644 docs/content/docs/framework/eval-optimization/evaluation.en.mdx rename docs/{docs/deploy/evaluation.md => content/docs/framework/eval-optimization/evaluation.mdx} (61%) create mode 100644 docs/content/docs/framework/eval-optimization/meta.en.json create mode 100644 docs/content/docs/framework/eval-optimization/meta.json create mode 100644 docs/content/docs/framework/eval-optimization/optimization.en.mdx rename docs/{docs/deploy/optimization.md => content/docs/framework/eval-optimization/optimization.mdx} (75%) create mode 100644 docs/content/docs/framework/frontend/a2ui.en.mdx create mode 100644 docs/content/docs/framework/frontend/a2ui.mdx create mode 100644 docs/content/docs/framework/frontend/meta.en.json create mode 100644 docs/content/docs/framework/frontend/meta.json create mode 100644 docs/content/docs/framework/frontend/web-ui.en.mdx create mode 100644 docs/content/docs/framework/frontend/web-ui.mdx create mode 100644 docs/content/docs/framework/gallery/agent-gallery.en.mdx create mode 100644 docs/content/docs/framework/gallery/agent-gallery.mdx create mode 100644 docs/content/docs/framework/gallery/app-gallery.en.mdx create mode 100644 docs/content/docs/framework/gallery/app-gallery.mdx create mode 100644 docs/content/docs/framework/gallery/meta.en.json create mode 100644 docs/content/docs/framework/gallery/meta.json create mode 100644 docs/content/docs/framework/getting-started/installation.en.mdx create mode 100644 docs/content/docs/framework/getting-started/installation.mdx create mode 100644 docs/content/docs/framework/getting-started/local-debugging.en.mdx create mode 100644 docs/content/docs/framework/getting-started/local-debugging.mdx create mode 100644 docs/content/docs/framework/getting-started/meta.en.json create mode 100644 docs/content/docs/framework/getting-started/meta.json create mode 100644 docs/content/docs/framework/getting-started/quickstart.en.mdx create mode 100644 docs/content/docs/framework/getting-started/quickstart.mdx create mode 100644 docs/content/docs/framework/index.en.mdx create mode 100644 docs/content/docs/framework/index.mdx create mode 100644 docs/content/docs/framework/introduction.en.mdx rename docs/{docs/veadk.md => content/docs/framework/introduction.mdx} (92%) create mode 100644 docs/content/docs/framework/knowledgebase/best-practice.en.mdx rename docs/{docs/knowledgebase/best-practice-knowledgebase.md => content/docs/framework/knowledgebase/best-practice.mdx} (95%) create mode 100644 docs/content/docs/framework/knowledgebase/meta.en.json create mode 100644 docs/content/docs/framework/knowledgebase/meta.json create mode 100644 docs/content/docs/framework/knowledgebase/overview.en.mdx create mode 100644 docs/content/docs/framework/knowledgebase/overview.mdx create mode 100644 docs/content/docs/framework/memory/best-practice.en.mdx rename docs/{docs/memory/best-practice-memory.md => content/docs/framework/memory/best-practice.mdx} (67%) create mode 100644 docs/content/docs/framework/memory/long-term.en.mdx create mode 100644 docs/content/docs/framework/memory/long-term.mdx create mode 100644 docs/content/docs/framework/memory/meta.en.json create mode 100644 docs/content/docs/framework/memory/meta.json create mode 100644 docs/content/docs/framework/memory/short-term.en.mdx create mode 100644 docs/content/docs/framework/memory/short-term.mdx create mode 100644 docs/content/docs/framework/meta.en.json create mode 100644 docs/content/docs/framework/meta.json create mode 100644 docs/content/docs/framework/observability/meta.en.json create mode 100644 docs/content/docs/framework/observability/meta.json create mode 100644 docs/content/docs/framework/observability/overview.en.mdx create mode 100644 docs/content/docs/framework/observability/overview.mdx create mode 100644 docs/content/docs/framework/observability/span-attributes.en.mdx rename docs/{docs/observation/span-attributes.md => content/docs/framework/observability/span-attributes.mdx} (94%) create mode 100644 docs/content/docs/framework/observability/tracing.en.mdx rename docs/{docs/observation/tracing.md => content/docs/framework/observability/tracing.mdx} (74%) create mode 100644 docs/content/docs/framework/observability/ve-tracing.en.mdx rename docs/{docs/observation/ve-tracing.md => content/docs/framework/observability/ve-tracing.mdx} (82%) create mode 100644 docs/content/docs/framework/plugin/guardrail.en.mdx rename docs/{docs/tools/guardrail.md => content/docs/framework/plugin/guardrail.mdx} (93%) create mode 100644 docs/content/docs/framework/plugin/meta.en.json create mode 100644 docs/content/docs/framework/plugin/meta.json create mode 100644 docs/content/docs/framework/runner.en.mdx rename docs/{docs/runner.md => content/docs/framework/runner.mdx} (83%) create mode 100644 docs/content/docs/framework/security/inbound.en.mdx rename docs/{docs/auth/inbound.md => content/docs/framework/security/inbound.mdx} (96%) create mode 100644 docs/content/docs/framework/security/meta.en.json create mode 100644 docs/content/docs/framework/security/meta.json create mode 100644 docs/content/docs/framework/security/outbound/api-key.en.mdx rename docs/{docs/auth/api-key-outbound.md => content/docs/framework/security/outbound/api-key.mdx} (86%) create mode 100644 docs/content/docs/framework/security/outbound/meta.en.json create mode 100644 docs/content/docs/framework/security/outbound/meta.json create mode 100644 docs/content/docs/framework/security/outbound/oauth2-m2m.en.mdx rename docs/{docs/auth/oauth2-m2m-outbound.md => content/docs/framework/security/outbound/oauth2-m2m.mdx} (87%) create mode 100644 docs/content/docs/framework/security/outbound/oauth2-user-federation.en.mdx rename docs/{docs/auth/oauth2-user-federation-outbound.md => content/docs/framework/security/outbound/oauth2-user-federation.mdx} (93%) create mode 100644 docs/content/docs/framework/security/outbound/trusted-mcp.en.mdx rename docs/{docs/auth/trusted-mcp-outbound.md => content/docs/framework/security/outbound/trusted-mcp.mdx} (67%) create mode 100644 docs/content/docs/framework/security/overview.en.mdx rename docs/{docs/auth/overview.md => content/docs/framework/security/overview.mdx} (82%) create mode 100644 docs/content/docs/framework/security/permission-policy.en.mdx rename docs/{docs/auth/permission-policy.md => content/docs/framework/security/permission-policy.mdx} (93%) create mode 100644 docs/content/docs/framework/tools/builtin-mcp.en.mdx create mode 100644 docs/content/docs/framework/tools/builtin-mcp.mdx create mode 100644 docs/content/docs/framework/tools/builtin.en.mdx create mode 100644 docs/content/docs/framework/tools/builtin.mdx create mode 100644 docs/content/docs/framework/tools/custom-function.en.mdx rename docs/{docs/tools/function.md => content/docs/framework/tools/custom-function.mdx} (63%) create mode 100644 docs/content/docs/framework/tools/feishu-channel.en.mdx rename docs/{docs/tools/feishu-channel.md => content/docs/framework/tools/feishu-channel.mdx} (65%) create mode 100644 docs/content/docs/framework/tools/meta.en.json create mode 100644 docs/content/docs/framework/tools/meta.json create mode 100644 docs/content/docs/framework/tools/system-tools.en.mdx create mode 100644 docs/content/docs/framework/tools/system-tools.mdx create mode 100644 docs/content/docs/framework/troubleshooting.en.mdx create mode 100644 docs/content/docs/framework/troubleshooting.mdx create mode 100644 docs/content/docs/meta.en.json create mode 100644 docs/content/docs/meta.json create mode 100644 docs/content/docs/references/api.en.mdx create mode 100644 docs/content/docs/references/api.mdx create mode 100644 docs/content/docs/references/contributing.en.mdx rename docs/{docs/references/contributing.md => content/docs/references/contributing.mdx} (70%) create mode 100644 docs/content/docs/references/index.en.mdx create mode 100644 docs/content/docs/references/index.mdx create mode 100644 docs/content/docs/references/license.en.mdx create mode 100644 docs/content/docs/references/license.mdx create mode 100644 docs/content/docs/references/meta.en.json create mode 100644 docs/content/docs/references/meta.json delete mode 100644 docs/docs/__init__.py delete mode 100644 docs/docs/agent/__init__.py delete mode 100644 docs/docs/agent/agent.md delete mode 100644 docs/docs/agent/agents.md delete mode 100644 docs/docs/agent/overview.md delete mode 100644 docs/docs/agent/responses-api.md delete mode 100644 docs/docs/agent/root_agent.py delete mode 100644 docs/docs/configuration.md delete mode 100644 docs/docs/design.md delete mode 100644 docs/docs/gallery/agent-gallery.md delete mode 100644 docs/docs/gallery/app-gallery.md delete mode 100644 docs/docs/index.md delete mode 100644 docs/docs/knowledgebase/overview.md delete mode 100644 docs/docs/memory/long-term-memory.md delete mode 100644 docs/docs/memory/short-term-memory.md delete mode 100644 docs/docs/quickstart.md delete mode 100644 docs/docs/references/license.md delete mode 100644 docs/docs/stylesheets/extra.css delete mode 100644 docs/docs/tools/builtin.md delete mode 100644 docs/docs/troubleshooting.md delete mode 100644 docs/examples/agent/agent/simplest_agent.py delete mode 100644 docs/examples/agent/agent/weather_reporter.py delete mode 100644 docs/examples/agent/agent/weather_reporter_agent.yaml delete mode 100644 docs/examples/agent/agents/llm_agent.go delete mode 100644 docs/examples/agent/agents/llm_agent.py delete mode 100644 docs/examples/agent/agents/loop_agent.py delete mode 100644 docs/examples/agent/agents/parallel_agent.py delete mode 100644 docs/examples/agent/agents/seq_agent.py delete mode 100644 docs/examples/channel/feishu_bot.py delete mode 100644 docs/examples/knowledge/viking_knowledge.go delete mode 100644 docs/examples/memory/long_mem_viking_agent.py delete mode 100644 docs/examples/memory/short_mem_mysql_agent.py delete mode 100644 docs/examples/runner/run_async.py delete mode 100644 docs/examples/runner/run_sync.py delete mode 100644 docs/examples/tools/function_tools/simple_function_tool.py delete mode 100644 docs/examples/tools/function_tools/tool_context_usage.py delete mode 100644 docs/examples/tools/image_generate/agent.py delete mode 100644 docs/examples/tools/lark/agent.py delete mode 100644 docs/examples/tools/las/agent.py delete mode 100644 docs/examples/tools/run_code/agent.py delete mode 100644 docs/examples/tools/vesearch/agent.py delete mode 100644 docs/examples/tools/video_generate/agent.py delete mode 100644 docs/examples/tools/web_search/agent.go delete mode 100644 docs/examples/tools/web_search/agent.py delete mode 100644 docs/examples/tracing/tracing_exporter.py create mode 100644 docs/lib/chat-types.ts create mode 100644 docs/lib/cn.ts create mode 100644 docs/lib/i18n-ui.ts create mode 100644 docs/lib/i18n.ts create mode 100644 docs/lib/layout.shared.tsx create mode 100644 docs/lib/shared.ts create mode 100644 docs/lib/source.ts delete mode 100644 docs/mkdocs.yml create mode 100644 docs/next.config.mjs create mode 100644 docs/package.json create mode 100644 docs/pnpm-lock.yaml create mode 100644 docs/postcss.config.mjs rename docs/{docs => public}/assets/images/agents/a2a_querystring.png (100%) rename docs/{docs => public}/assets/images/agents/cozeloop_prompt_mgr.png (100%) rename docs/{docs => public}/assets/images/agents/llm_agent.png (100%) rename docs/{docs => public}/assets/images/agents/loop_agent.png (100%) rename docs/{docs => public}/assets/images/agents/parallel_agent.png (100%) rename docs/{docs => public}/assets/images/agents/responses_api.png (100%) rename docs/{docs => public}/assets/images/agents/seq_agent.png (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_create.gif (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_deploy_vefaas_log.png (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_init.gif (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_kb_add.gif (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_kb_test.gif (100%) rename docs/{docs => public}/assets/images/cli/cli_veadk_web.gif (100%) rename docs/{docs => public}/assets/images/cozeloop_prompt_key.png (100%) rename docs/{docs => public}/assets/images/deploy/add_permission.png (100%) rename docs/{docs => public}/assets/images/deploy/close_key_auth.png (100%) rename docs/{docs => public}/assets/images/deploy/cp_attach_role.png (100%) rename docs/{docs => public}/assets/images/deploy/cp_index.png (100%) rename docs/{docs => public}/assets/images/deploy/cp_open.png (100%) rename docs/{docs => public}/assets/images/deploy/cr_attach_role.png (100%) rename docs/{docs => public}/assets/images/deploy/cr_index.png (100%) rename docs/{docs => public}/assets/images/deploy/deploy_agent.png (100%) rename docs/{docs => public}/assets/images/deploy/key_auth_token.png (100%) rename docs/{docs => public}/assets/images/deploy/veapig_attach_role.png (100%) rename docs/{docs => public}/assets/images/deploy/veapig_index.png (100%) rename docs/{docs => public}/assets/images/deploy/vefaas_attach_role.png (100%) rename docs/{docs => public}/assets/images/deploy/vefaas_index.png (100%) rename docs/{docs => public}/assets/images/evaluation/veadk_eval.gif (100%) rename docs/{docs => public}/assets/images/evaluation/veadk_web_eval.gif (100%) rename docs/{docs => public}/assets/images/faq/troubleshooting-01.png (100%) rename docs/{docs => public}/assets/images/faq/troubleshooting-02.png (100%) rename docs/{docs => public}/assets/images/faq/troubleshooting-03.jpeg (100%) rename docs/{docs => public}/assets/images/knowledge/image-1.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-10.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-11.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-13.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-14.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-17.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-18.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-19.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-20.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-21.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-22.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-3.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-4.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-5.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-6.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-7.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-8.png (100%) rename docs/{docs => public}/assets/images/knowledge/image-9.png (100%) rename docs/{docs => public}/assets/images/knowledge/image.png (100%) rename docs/{docs => public}/assets/images/knowledge/kb-bp-1.jpeg (100%) rename docs/{docs => public}/assets/images/knowledge/kb-bp-2.jpeg (100%) rename docs/{docs => public}/assets/images/observation/apm-console.png (100%) rename docs/{docs => public}/assets/images/observation/apm-metrics.png (100%) rename docs/{docs => public}/assets/images/observation/apm-session.png (100%) rename docs/{docs => public}/assets/images/observation/apm-trace.png (100%) rename docs/{docs => public}/assets/images/observation/coze-console.png (100%) rename docs/{docs => public}/assets/images/observation/coze-spaceid.png (100%) rename docs/{docs => public}/assets/images/observation/coze-trace.png (100%) rename docs/{docs => public}/assets/images/observation/show_traceid.jpeg (100%) rename docs/{docs => public}/assets/images/observation/tls-console.png (100%) rename docs/{docs => public}/assets/images/observation/tls-context.png (100%) rename docs/{docs => public}/assets/images/observation/tls-model.png (100%) rename docs/{docs => public}/assets/images/observation/tls-project.png (100%) rename docs/{docs => public}/assets/images/observation/tls-tools.png (100%) rename docs/{docs => public}/assets/images/observation/tls-topic.png (100%) rename docs/{docs => public}/assets/images/observation/tls-trace.png (100%) rename docs/{docs => public}/assets/images/optimization/lightning_client.png (100%) rename docs/{docs => public}/assets/images/optimization/lightning_training_server.png (100%) rename docs/{docs => public}/assets/images/optimization/logs.png (100%) rename docs/{docs => public}/assets/images/optimization/submit_task.png (100%) rename docs/{docs => public}/assets/images/optimization/timeline.png (100%) rename docs/{docs => public}/assets/images/optimization/training.png (100%) rename docs/{docs => public}/assets/images/overview/agent-overview.png (100%) rename docs/{docs => public}/assets/images/overview/veadk-web.png (100%) rename docs/{docs => public}/assets/images/tools/agentkittools1.png (100%) rename docs/{docs => public}/assets/images/tools/agentkittools2.png (100%) rename docs/{docs => public}/assets/images/tools/agentkittools3.png (100%) rename docs/{docs => public}/assets/images/tools/cat.jpeg (100%) rename docs/{docs => public}/assets/images/tools/function_tools/long_running_tool_result.jpeg (100%) rename docs/{docs => public}/assets/images/tools/function_tools/simple_tool_result.png (100%) rename docs/{docs => public}/assets/images/tools/function_tools/tool_context_result.jpg (100%) rename docs/{docs => public}/assets/images/tools/image_generate.png (100%) rename docs/{docs => public}/assets/images/tools/lark1.png (100%) rename docs/{docs => public}/assets/images/tools/lark2.png (100%) rename docs/{docs => public}/assets/images/tools/las1.png (100%) rename docs/{docs => public}/assets/images/tools/las2.png (100%) rename docs/{docs => public}/assets/images/tools/mua_1.png (100%) rename docs/{docs => public}/assets/images/tools/mua_2.png (100%) rename docs/{docs => public}/assets/images/tools/mua_3.png (100%) rename docs/{docs => public}/assets/images/tools/run_code1.png (100%) rename docs/{docs => public}/assets/images/tools/run_code1.png.jpg (100%) rename docs/{docs => public}/assets/images/tools/run_code2.png (100%) rename docs/{docs => public}/assets/images/tools/vesearch.png (100%) rename docs/{docs => public}/assets/images/tools/video_generate.gif (100%) rename docs/{docs => public}/assets/images/tools/video_generate.png (100%) rename docs/{docs => public}/assets/images/tools/video_generate1.png (100%) rename docs/{docs => public}/assets/images/tools/video_generate2.png (100%) rename docs/{docs => public}/assets/images/tools/web_search.png (100%) rename docs/{docs => public}/assets/images/trae_rules.png (100%) rename docs/{docs => public}/assets/images/uv_demo.jpeg (100%) rename docs/{docs => public}/assets/images/volcengine-color.svg (100%) delete mode 100644 docs/requirements.txt create mode 100644 docs/scripts/build-static.mjs create mode 100644 docs/source.config.ts create mode 100644 docs/tsconfig.json diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml index 720f1be6..63fa936a 100644 --- a/.github/workflows/deploy-docs.yaml +++ b/.github/workflows/deploy-docs.yaml @@ -4,7 +4,7 @@ on: push: branches: - main - - feat/docs + - feat/new-docs paths: - 'docs/**' - '.github/workflows/deploy-docs.yaml' @@ -16,35 +16,60 @@ permissions: pages: write id-token: write +# Allow one concurrent deployment; cancel in-progress runs. +concurrency: + group: pages + cancel-in-progress: true + jobs: - deploy: + build: runs-on: ubuntu-latest - environment: - name: github-pages + defaults: + run: + working-directory: docs steps: - name: Checkout repository uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up Node.js + uses: actions/setup-node@v4 with: - python-version: '3.12' + node-version: 22 - - name: Install dependencies + # pnpm via corepack (bundled with Node) — avoids third-party setup actions + # that are blocked by the org's allowed-actions policy. + - name: Enable pnpm run: | - cd docs - pip install -r requirements.txt + corepack enable + corepack prepare pnpm@10.16.1 --activate - - name: Build MkDocs site - run: | - cd docs - mkdocs build + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build static site (Fumadocs) + run: pnpm build:static + env: + # GitHub Pages project site is served from /. Without this base + # path, assets and routes 404 under the sub-path. (The pitfall.) + NEXT_PUBLIC_BASE_PATH: /${{ github.event.repository.name }} + # Optional: external Ask-AI endpoint (e.g. a VeFaaS function). + NEXT_PUBLIC_AI_CHAT_URL: ${{ vars.AI_CHAT_URL }} - name: Upload artifact for GitHub Pages uses: actions/upload-pages-artifact@v3 with: - path: docs/site/ + path: docs/out + deploy: + needs: build + runs-on: ubuntu-latest + # The github-pages environment restricts deployments to the default branch. + # Branches/PRs run the build job above to validate; deploy happens on main. + if: github.ref == 'refs/heads/main' + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + steps: - name: Deploy to GitHub Pages id: deploy - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index bb0c80b8..d48b3d08 100644 --- a/.gitignore +++ b/.gitignore @@ -201,4 +201,6 @@ cython_debug/ *.mp3 *.pcm -.trae \ No newline at end of file +.trae +.claude +.agents \ No newline at end of file diff --git a/.gitleaks.toml b/.gitleaks.toml index 0f097484..d69d326f 100644 --- a/.gitleaks.toml +++ b/.gitleaks.toml @@ -73,4 +73,10 @@ description = "Empty environment variables with KEY pattern" regex = '''os\.environ\[".*?KEY"\]\s*=\s*".+"''' [allowlist] -paths = ["requirements.txt", "tests", "veadk/realtime/client.py", "veadk/realtime/live.py"] \ No newline at end of file +paths = ["requirements.txt", "tests", "veadk/realtime/client.py", "veadk/realtime/live.py"] +# False positives: the docs search config references the @orama/tokenizers +# package and its createTokenizer() helper. The word "tokenizer" trips +# token-transformer-id-pattern, but these are library identifiers, not secrets. +regexes = [ + '''tokenizer''', +] \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore index 151c3b9b..b58ad377 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,172 +1,32 @@ -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/#use-with-ide -.pdm.toml - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -.idea/ - -# vscode -.vscode/ -# Windsurf -.windsurf - -# python package -uv.lock - -# VitePress related files (security concern - keep Markdown docs in repo) -docs/package.json -docs/package-lock.json -docs/node_modules/ +# deps +/node_modules + +# generated content +.source + +# test & build +/coverage +/.next/ +/out/ +/build +*.tsbuildinfo + +# misc +.DS_Store +*.pem +/.pnp +.pnp.js +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# others +.env*.local +.vercel +next-env.d.ts + +# The repo root .gitignore is a Python template that ignores `lib/` and +# `build/`. This is a JS project — re-include our source dirs. +!/lib +!/lib/** +!/build \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..301980ab --- /dev/null +++ b/docs/README.md @@ -0,0 +1,47 @@ +# veadk-docs-scaffold + +This is a Next.js application generated with +[Create Fumadocs](https://github.com/fuma-nama/fumadocs). + +It is a Next.js app with [Static Export](https://nextjs.org/docs/app/guides/static-exports) configured. + +Run development server: + +```bash +npm run dev +# or +pnpm dev +# or +yarn dev +``` + +Open http://localhost:3000 with your browser to see the result. + +## Explore + +In the project, you can see: + +- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content. +- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep. + +| Route | Description | +| ------------------------- | ------------------------------------------------------ | +| `app/(home)` | The route group for your landing page and other pages. | +| `app/docs` | The documentation layout and pages. | +| `app/api/search/route.ts` | The Route Handler for search. | + +### Fumadocs MDX + +A `source.config.ts` config file has been included, you can customise different options like frontmatter schema. + +Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details. + +## Learn More + +To learn more about Next.js and Fumadocs, take a look at the following +resources: + +- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js + features and API. +- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs diff --git a/docs/app/[lang]/(home)/layout.tsx b/docs/app/[lang]/(home)/layout.tsx new file mode 100644 index 00000000..5187d9f1 --- /dev/null +++ b/docs/app/[lang]/(home)/layout.tsx @@ -0,0 +1,14 @@ +import type { ReactNode } from 'react'; +import { HomeLayout } from 'fumadocs-ui/layouts/home'; +import { baseOptions } from '@/lib/layout.shared'; + +export default async function Layout({ + params, + children, +}: { + params: Promise<{ lang: string }>; + children: ReactNode; +}) { + const { lang } = await params; + return {children}; +} diff --git a/docs/app/[lang]/(home)/page.tsx b/docs/app/[lang]/(home)/page.tsx new file mode 100644 index 00000000..22c1296f --- /dev/null +++ b/docs/app/[lang]/(home)/page.tsx @@ -0,0 +1,37 @@ +import Link from 'next/link'; + +const copy = { + cn: { + title: 'Volcengine Agent Development Kit', + subtitle: '火山引擎智能体开发套件', + desc: '构建、部署、观测、评测企业级 AI 智能体的一站式云原生框架。', + cta: '阅读文档', + }, + en: { + title: 'Volcengine Agent Development Kit', + subtitle: 'Build production-ready AI agents', + desc: 'A cloud-native framework to build, deploy, observe, and evaluate enterprise-grade AI agents.', + cta: 'Read the docs', + }, +} as const; + +export default async function HomePage({ params }: { params: Promise<{ lang: string }> }) { + const { lang } = await params; + const t = copy[lang as keyof typeof copy] ?? copy.cn; + + return ( +
+

+ {t.title} +

+

{t.subtitle}

+

{t.desc}

+ + {t.cta} + +
+ ); +} diff --git a/docs/app/[lang]/docs/[[...slug]]/page.tsx b/docs/app/[lang]/docs/[[...slug]]/page.tsx new file mode 100644 index 00000000..e3e5081d --- /dev/null +++ b/docs/app/[lang]/docs/[[...slug]]/page.tsx @@ -0,0 +1,71 @@ +import { getPageImage, getPageMarkdownUrl, source } from '@/lib/source'; +import { + DocsBody, + DocsDescription, + DocsPage, + DocsTitle, + MarkdownCopyButton, + ViewOptionsPopover, +} from 'fumadocs-ui/layouts/docs/page'; +import { notFound } from 'next/navigation'; +import { getMDXComponents } from '@/components/mdx'; +import type { Metadata } from 'next'; +import { createRelativeLink } from 'fumadocs-ui/mdx'; +import { gitConfig } from '@/lib/shared'; + +export default async function Page({ + params, +}: { + params: Promise<{ lang: string; slug?: string[] }>; +}) { + const { lang, slug } = await params; + const page = source.getPage(slug, lang); + if (!page) notFound(); + + const MDX = page.data.body; + const markdownUrl = getPageMarkdownUrl(page).url; + + return ( + + {page.data.title} + {page.data.description} +
+ + +
+ + + + + ); +} + +export async function generateStaticParams() { + return source.generateParams(); +} + +export async function generateMetadata({ + params, +}: { + params: Promise<{ lang: string; slug?: string[] }>; +}): Promise { + const { lang, slug } = await params; + const page = source.getPage(slug, lang); + if (!page) notFound(); + + return { + title: page.data.title, + description: page.data.description, + openGraph: { + images: getPageImage(page).url, + }, + }; +} diff --git a/docs/app/[lang]/docs/layout.tsx b/docs/app/[lang]/docs/layout.tsx new file mode 100644 index 00000000..98c900a2 --- /dev/null +++ b/docs/app/[lang]/docs/layout.tsx @@ -0,0 +1,49 @@ +import type { ReactNode } from 'react'; +import { source } from '@/lib/source'; +import { DocsLayout } from 'fumadocs-ui/layouts/docs'; +import { baseOptions } from '@/lib/layout.shared'; +import { BookMarked, LayoutGrid, Terminal } from 'lucide-react'; + +export default async function Layout({ + params, + children, +}: { + params: Promise<{ lang: string }>; + children: ReactNode; +}) { + const { lang } = await params; + const zh = lang === 'cn'; + + // Root dropdown (sidebar RootToggle): Framework / CLI / Reference. + const tabs = [ + { + title: zh ? '框架' : 'Framework', + description: zh ? 'SDK 与核心概念' : 'SDK & core concepts', + url: `/${lang}/docs/framework`, + icon: , + }, + { + title: zh ? '命令行工具' : 'CLI', + description: zh ? '命令行参考' : 'Command-line reference', + url: `/${lang}/docs/cli`, + icon: , + }, + { + title: zh ? '参考' : 'Reference', + description: zh ? 'API · 贡献 · 许可' : 'API · Contributing · License', + url: `/${lang}/docs/references`, + icon: , + }, + ]; + + return ( + + {children} + + ); +} diff --git a/docs/app/[lang]/layout.tsx b/docs/app/[lang]/layout.tsx new file mode 100644 index 00000000..b9183110 --- /dev/null +++ b/docs/app/[lang]/layout.tsx @@ -0,0 +1,28 @@ +import type { ReactNode } from 'react'; +import { RootProvider } from 'fumadocs-ui/provider/next'; +import { i18nProvider } from 'fumadocs-ui/i18n'; +import SearchDialog from '@/components/search'; +import { i18n } from '@/lib/i18n'; +import { translations } from '@/lib/i18n-ui'; +import { HtmlLang } from '@/components/html-lang'; + +export function generateStaticParams() { + return i18n.languages.map((lang) => ({ lang })); +} + +export default async function LangLayout({ + params, + children, +}: { + params: Promise<{ lang: string }>; + children: ReactNode; +}) { + const { lang } = await params; + + return ( + + + {children} + + ); +} diff --git a/docs/app/api/chat/route.ts b/docs/app/api/chat/route.ts new file mode 100644 index 00000000..e53b2c09 --- /dev/null +++ b/docs/app/api/chat/route.ts @@ -0,0 +1,108 @@ +import { createOpenRouter } from '@openrouter/ai-sdk-provider'; +import { convertToModelMessages, stepCountIs, streamText, tool } from 'ai'; +import { z } from 'zod'; +import { source } from '@/lib/source'; +import { Document, type DocumentData } from 'flexsearch'; +import type { ChatUIMessage } from '@/lib/chat-types'; + +export type { ChatUIMessage }; + +interface CustomDocument extends DocumentData { + url: string; + title: string; + description: string; + content: string; +} + +const searchServer = createSearchServer(); + +async function createSearchServer() { + const search = new Document({ + document: { + id: 'url', + index: ['title', 'description', 'content'], + store: true, + }, + }); + + const docs = await chunkedAll( + source.getPages().map(async (page) => { + if (!('getText' in page.data)) return null; + + return { + title: page.data.title, + description: page.data.description, + url: page.url, + content: await page.data.getText('processed'), + } as CustomDocument; + }), + ); + + for (const doc of docs) { + if (doc) search.add(doc); + } + + return search; +} + +async function chunkedAll(promises: Promise[]): Promise { + const SIZE = 50; + const out: O[] = []; + for (let i = 0; i < promises.length; i += SIZE) { + out.push(...(await Promise.all(promises.slice(i, i + SIZE)))); + } + return out; +} + +const openrouter = createOpenRouter({ + apiKey: process.env.OPENROUTER_API_KEY, +}); + +/** System prompt, you can update it to provide more specific information */ +const systemPrompt = [ + 'You are an AI assistant for a documentation site.', + 'Use the `search` tool to retrieve relevant docs context before answering when needed.', + 'The `search` tool returns raw JSON results from documentation. Use those results to ground your answer and cite sources as markdown links using the document `url` field when available.', + 'If you cannot find the answer in search results, say you do not know and suggest a better search query.', +].join('\n'); + +export async function POST(req: Request, ctx: RouteContext<"/api/chat">) { + const reqJson = await req.json(); + + const result = streamText({ + model: openrouter.chat(process.env.OPENROUTER_MODEL ?? 'anthropic/claude-3.5-sonnet'), + stopWhen: stepCountIs(5), + tools: { + search: searchTool, + }, + messages: [ + { role: 'system', content: systemPrompt }, + ...(await convertToModelMessages(reqJson.messages ?? [], { + convertDataPart(part) { + if (part.type === 'data-client') + return { + type: 'text', + text: `[Client Context: ${JSON.stringify(part.data)}]`, + }; + }, + })), + ], + toolChoice: 'auto', + }); + + return result.toUIMessageStreamResponse(); +} + +export type SearchTool = typeof searchTool; + +const searchTool = tool({ + description: 'Search the docs content and return raw JSON results.', + inputSchema: z.object({ + query: z.string(), + limit: z.number().int().min(1).max(100).default(10), + }), + async execute({ query, limit }) { + const search = await searchServer; + return await search.searchAsync(query, { limit, merge: true, enrich: true }); + }, +}); \ No newline at end of file diff --git a/docs/app/api/search/route.ts b/docs/app/api/search/route.ts new file mode 100644 index 00000000..3db2c02b --- /dev/null +++ b/docs/app/api/search/route.ts @@ -0,0 +1,17 @@ +import { source } from '@/lib/source'; +import { createFromSource } from 'fumadocs-core/search/server'; +import { createTokenizer } from '@orama/tokenizers/mandarin'; + +export const revalidate = false; + +// Static (build-time) search index, one per locale. +// Chinese uses Mandarin word segmentation so CJK terms are indexed correctly. +export const { staticGET: GET } = createFromSource(source, { + localeMap: { + cn: { + components: { tokenizer: createTokenizer() }, + search: { threshold: 0, tolerance: 0 }, + }, + en: { language: 'english' }, + }, +}); diff --git a/docs/app/global.css b/docs/app/global.css new file mode 100644 index 00000000..f86f3c9d --- /dev/null +++ b/docs/app/global.css @@ -0,0 +1,12 @@ +@import 'tailwindcss'; +@import 'fumadocs-ui/css/neutral.css'; +@import 'fumadocs-ui/css/preset.css'; + +html { + scrollbar-gutter: stable; +} + +html > body[data-scroll-locked] { + margin-right: 0px !important; + --removed-body-scroll-bar-size: 0px !important; +} diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx new file mode 100644 index 00000000..003da0b2 --- /dev/null +++ b/docs/app/layout.tsx @@ -0,0 +1,11 @@ +import type { ReactNode } from 'react'; +import './global.css'; + +// Root layout. The locale-aware provider lives in `app/[lang]/layout.tsx`. +export default function RootLayout({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} diff --git a/docs/app/llms-full.txt/route.ts b/docs/app/llms-full.txt/route.ts new file mode 100644 index 00000000..d355fa4d --- /dev/null +++ b/docs/app/llms-full.txt/route.ts @@ -0,0 +1,11 @@ +import { getLLMText, source } from '@/lib/source'; +import { i18n } from '@/lib/i18n'; + +export const revalidate = false; + +export async function GET() { + const scan = source.getPages(i18n.defaultLanguage).map(getLLMText); + const scanned = await Promise.all(scan); + + return new Response(scanned.join('\n\n')); +} diff --git a/docs/app/llms.mdx/docs/[[...slug]]/route.ts b/docs/app/llms.mdx/docs/[[...slug]]/route.ts new file mode 100644 index 00000000..1a45520d --- /dev/null +++ b/docs/app/llms.mdx/docs/[[...slug]]/route.ts @@ -0,0 +1,24 @@ +import { getLLMText, getPageMarkdownUrl, source } from '@/lib/source'; +import { notFound } from 'next/navigation'; +import { i18n } from '@/lib/i18n'; + +export const revalidate = false; + +export async function GET(_req: Request, { params }: RouteContext<'/llms.mdx/docs/[[...slug]]'>) { + const { slug } = await params; + // remove the appended "content.md" + const page = source.getPage(slug?.slice(0, -1)); + if (!page) notFound(); + + return new Response(await getLLMText(page), { + headers: { + 'Content-Type': 'text/markdown', + }, + }); +} + +export function generateStaticParams() { + return source.getPages(i18n.defaultLanguage).map((page) => ({ + slug: getPageMarkdownUrl(page).segments, + })); +} diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.ts new file mode 100644 index 00000000..fc80cb65 --- /dev/null +++ b/docs/app/llms.txt/route.ts @@ -0,0 +1,8 @@ +import { source } from '@/lib/source'; +import { llms } from 'fumadocs-core/source'; + +export const revalidate = false; + +export function GET() { + return new Response(llms(source).index()); +} diff --git a/docs/app/og/docs/[...slug]/route.tsx b/docs/app/og/docs/[...slug]/route.tsx new file mode 100644 index 00000000..9668951c --- /dev/null +++ b/docs/app/og/docs/[...slug]/route.tsx @@ -0,0 +1,28 @@ +import { getPageImage, source } from '@/lib/source'; +import { notFound } from 'next/navigation'; +import { ImageResponse } from 'next/og'; +import { generate as DefaultImage } from 'fumadocs-ui/og'; +import { appName } from '@/lib/shared'; +import { i18n } from '@/lib/i18n'; + +export const revalidate = false; + +export async function GET(_req: Request, { params }: RouteContext<'/og/docs/[...slug]'>) { + const { slug } = await params; + const page = source.getPage(slug.slice(0, -1)); + if (!page) notFound(); + + return new ImageResponse( + , + { + width: 1200, + height: 630, + }, + ); +} + +export function generateStaticParams() { + return source.getPages(i18n.defaultLanguage).map((page) => ({ + slug: getPageImage(page).segments, + })); +} diff --git a/docs/app/page.tsx b/docs/app/page.tsx new file mode 100644 index 00000000..a378c00b --- /dev/null +++ b/docs/app/page.tsx @@ -0,0 +1,17 @@ +'use client'; + +import { useEffect } from 'react'; + +// Static-export friendly root redirect to the default locale. +// Uses a relative path so it works under a GitHub Pages base path. +export default function RootRedirect() { + useEffect(() => { + window.location.replace('cn/'); + }, []); + + return ( + + ); +} diff --git a/docs/biome.json b/docs/biome.json new file mode 100644 index 00000000..64ae1e3b --- /dev/null +++ b/docs/biome.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json", + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true + }, + "files": { + "ignoreUnknown": true, + "includes": [ + "**", + "!node_modules", + "!.next", + "!dist", + "!build", + "!.source" + ] + }, + "formatter": { + "enabled": true, + "indentStyle": "space", + "indentWidth": 2 + }, + "linter": { + "enabled": true, + "rules": { + "recommended": true + }, + "domains": { + "next": "recommended", + "react": "recommended" + } + }, + "assist": { + "actions": { + "source": { + "organizeImports": "on" + } + } + } +} \ No newline at end of file diff --git a/docs/components/ai/search.tsx b/docs/components/ai/search.tsx new file mode 100644 index 00000000..1ce008c2 --- /dev/null +++ b/docs/components/ai/search.tsx @@ -0,0 +1,477 @@ +'use client'; +import { + type ComponentProps, + createContext, + type ReactNode, + type SyntheticEvent, + use, + useEffect, + useEffectEvent, + useMemo, + useRef, + useState, +} from 'react'; +import { Loader2, MessageCircleIcon, RefreshCw, SearchIcon, Send, X } from 'lucide-react'; +import { cn } from '../../lib/cn'; +import { buttonVariants } from '../ui/button'; +import { useChat, type UseChatHelpers } from '@ai-sdk/react'; +import { DefaultChatTransport, type Tool, type UIToolInvocation } from 'ai'; +import { Markdown } from '../markdown'; +import { Presence } from '@radix-ui/react-presence'; +import type { ChatUIMessage, SearchTool } from '../../lib/chat-types'; + +const Context = createContext<{ + open: boolean; + setOpen: (open: boolean) => void; + chat: UseChatHelpers; +} | null>(null); + +export function AISearchPanelHeader({ className, ...props }: ComponentProps<'div'>) { + const { setOpen } = useAISearchContext(); + + return ( +
+
+

AI Chat

+

+ AI can be inaccurate, please verify the answers. +

+
+ + +
+ ); +} + +export function AISearchInputActions() { + const { messages, status, setMessages, regenerate } = useChatContext(); + const isLoading = status === 'streaming'; + + if (messages.length === 0) return null; + + return ( + <> + {!isLoading && messages.at(-1)?.role === 'assistant' && ( + + )} + + + ); +} + +const StorageKeyInput = '__ai_search_input'; +export function AISearchInput(props: ComponentProps<'form'>) { + const { status, sendMessage, stop } = useChatContext(); + const [input, setInput] = useState(() => localStorage.getItem(StorageKeyInput) ?? ''); + const isLoading = status === 'streaming' || status === 'submitted'; + const onStart = (e?: SyntheticEvent) => { + e?.preventDefault(); + const message = input.trim(); + if (message.length === 0) return; + + void sendMessage({ + role: 'user', + parts: [ + { + type: 'data-client', + data: { + location: location.href, + }, + }, + { + type: 'text', + text: message, + }, + ], + }); + setInput(''); + localStorage.removeItem(StorageKeyInput); + }; + + useEffect(() => { + if (isLoading) document.getElementById('nd-ai-input')?.focus(); + }, [isLoading]); + + return ( +
+ { + setInput(e.target.value); + localStorage.setItem(StorageKeyInput, e.target.value); + }} + onKeyDown={(event) => { + if (!event.shiftKey && event.key === 'Enter') { + onStart(event); + } + }} + /> + {isLoading ? ( + + ) : ( + + )} +
+ ); +} + +function List(props: Omit, 'dir'>) { + const containerRef = useRef(null); + + useEffect(() => { + if (!containerRef.current) return; + function callback() { + const container = containerRef.current; + if (!container) return; + + container.scrollTo({ + top: container.scrollHeight, + behavior: 'instant', + }); + } + + const observer = new ResizeObserver(callback); + callback(); + + const element = containerRef.current?.firstElementChild; + + if (element) { + observer.observe(element); + } + + return () => { + observer.disconnect(); + }; + }, []); + + return ( +
+ {props.children} +
+ ); +} + +function Input(props: ComponentProps<'textarea'>) { + const ref = useRef(null); + const shared = cn('col-start-1 row-start-1', props.className); + + return ( +
+