From 0620453daf50837602ac44ed2212994e6e273fc4 Mon Sep 17 00:00:00 2001 From: Yumiue <229866007@qq.com> Date: Sun, 26 Apr 2026 14:38:03 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(www):=20=E9=87=8D=E6=9E=84=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=AB=99=E5=B9=B6=E8=A1=A5=E9=BD=90=20MCP=20=E4=B8=8E?= =?UTF-8?q?=20Skills=20=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- www/.gitignore | 5 +- www/.vitepress/config.mts | 151 +-- .../theme/components/HomeLanding.vue | 105 +++ .../theme/components/TerminalPreview.vue | 115 +++ www/.vitepress/theme/custom.css | 873 ++++++++---------- www/.vitepress/theme/index.ts | 4 + www/docs/guides/configuration.md | 167 ---- www/docs/guides/mcp.md | 74 -- www/docs/guides/providers.md | 73 -- www/docs/guides/update.md | 24 - www/docs/index.md | 27 - www/docs/quick-start.md | 59 -- www/docs/reference/architecture.md | 28 - www/en/docs/guides/configuration.md | 148 --- www/en/docs/guides/mcp.md | 74 -- www/en/docs/guides/providers.md | 71 -- www/en/docs/guides/update.md | 24 - www/en/docs/index.md | 41 - www/en/docs/quick-start.md | 59 -- www/en/docs/reference/architecture.md | 28 - www/en/guide/configuration.md | 299 ++++++ www/en/guide/daily-use.md | 90 ++ www/en/guide/examples.md | 130 +++ www/en/guide/index.md | 37 + www/en/guide/install.md | 118 +++ www/en/guide/mcp.md | 204 ++++ www/en/guide/skills.md | 176 ++++ www/en/guide/tools-permissions.md | 79 ++ www/en/guide/troubleshooting.md | 117 +++ www/en/guide/update.md | 45 + www/en/index.md | 63 +- www/guide/configuration.md | 283 ++++-- www/guide/daily-use.md | 83 ++ www/guide/examples.md | 130 +++ www/guide/gateway.md | 18 +- www/guide/getting-started.md | 46 - www/guide/index.md | 52 +- www/guide/install.md | 129 ++- www/guide/mcp.md | 204 ++++ www/guide/memo-skills.md | 134 --- www/guide/quick-start.md | 77 -- www/guide/skills.md | 176 ++++ www/guide/tools-permissions.md | 79 ++ www/guide/troubleshooting.md | 119 +++ www/guide/workspace-session.md | 71 -- www/index.md | 75 +- www/reference/index.md | 2 + 47 files changed, 3159 insertions(+), 2027 deletions(-) create mode 100644 www/.vitepress/theme/components/HomeLanding.vue create mode 100644 www/.vitepress/theme/components/TerminalPreview.vue delete mode 100644 www/docs/guides/configuration.md delete mode 100644 www/docs/guides/mcp.md delete mode 100644 www/docs/guides/providers.md delete mode 100644 www/docs/guides/update.md delete mode 100644 www/docs/index.md delete mode 100644 www/docs/quick-start.md delete mode 100644 www/docs/reference/architecture.md delete mode 100644 www/en/docs/guides/configuration.md delete mode 100644 www/en/docs/guides/mcp.md delete mode 100644 www/en/docs/guides/providers.md delete mode 100644 www/en/docs/guides/update.md delete mode 100644 www/en/docs/index.md delete mode 100644 www/en/docs/quick-start.md delete mode 100644 www/en/docs/reference/architecture.md create mode 100644 www/en/guide/configuration.md create mode 100644 www/en/guide/daily-use.md create mode 100644 www/en/guide/examples.md create mode 100644 www/en/guide/index.md create mode 100644 www/en/guide/install.md create mode 100644 www/en/guide/mcp.md create mode 100644 www/en/guide/skills.md create mode 100644 www/en/guide/tools-permissions.md create mode 100644 www/en/guide/troubleshooting.md create mode 100644 www/en/guide/update.md create mode 100644 www/guide/daily-use.md create mode 100644 www/guide/examples.md delete mode 100644 www/guide/getting-started.md create mode 100644 www/guide/mcp.md delete mode 100644 www/guide/memo-skills.md delete mode 100644 www/guide/quick-start.md create mode 100644 www/guide/skills.md create mode 100644 www/guide/tools-permissions.md create mode 100644 www/guide/troubleshooting.md delete mode 100644 www/guide/workspace-session.md diff --git a/www/.gitignore b/www/.gitignore index 8b137891..c51a1e50 100644 --- a/www/.gitignore +++ b/www/.gitignore @@ -1 +1,4 @@ - +# VitePress build artifacts +cache/ +dist/ +node_modules/ diff --git a/www/.vitepress/config.mts b/www/.vitepress/config.mts index e7328913..7f121298 100644 --- a/www/.vitepress/config.mts +++ b/www/.vitepress/config.mts @@ -1,34 +1,19 @@ import { defineConfig } from "vitepress"; -// --- 环境变量检测逻辑 --- const isVercel = process.env.VERCEL === "1"; -const isCFPages = process.env.CF_PAGES === "1"; - +const isCFPages = process.env.CF_PAGES === "1"; const isRootDeploy = isVercel || isCFPages; const repoUrl = "https://github.com/1024XEngineer/neo-code"; -const docsBase = `${repoUrl}/blob/main/docs`; - -// 核心修改 1：动态基础路径 const base = isRootDeploy ? "/" : "/neo-code/"; -// 👇👇👇 新增这段调试日志 👇👇👇 -console.log("====== VitePress Build Info ======"); -console.log("VERCEL Env:", process.env.VERCEL); -console.log("CF_PAGES Env:", process.env.CF_PAGES); -console.log("Final Base Path:", base); -console.log("=================================="); - -// 核心修改 2：动态站点 URL let siteUrl = "https://1024xengineer.github.io/neo-code/"; if (isVercel) { - siteUrl = `https://${process.env.VERCEL_URL || 'neocode-docs.vercel.app'}/`; + siteUrl = `https://${process.env.VERCEL_URL || "neocode-docs.vercel.app"}/`; } else if (isCFPages) { - siteUrl = "https://neocode-docs.pages.dev/"; + siteUrl = "https://neocode-docs.pages.dev/"; } -const brandImageUrl = `${siteUrl}brand/neocode-mark.png`; - export default defineConfig({ title: "NeoCode", description: "基于 Go + Bubble Tea 的本地 Coding Agent 用户指南", @@ -40,23 +25,26 @@ export default defineConfig({ cleanUrls: true, lastUpdated: true, head: [ - ["meta", { name: "theme-color", content: "#090B1A" }], - ["meta", { property: "og:title", content: "NeoCode 用户指南" }], + ["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }], + ["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }], [ - "meta", + "link", { - property: "og:description", - content: "围绕真实命令、配置与 Gateway 使用场景整理的 NeoCode 用户指导网站。", + rel: "stylesheet", + href: "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600;700&display=swap", }, ], - ["meta", { property: "og:type", content: "website" }], + ["meta", { name: "theme-color", content: "#f7f7f4" }], + ["meta", { property: "og:title", content: "NeoCode 用户指南" }], [ "meta", { - property: "og:image", - content: brandImageUrl, + property: "og:description", + content: "围绕真实命令、配置与 Gateway 使用场景整理的 NeoCode 用户指导网站。", }, ], + ["meta", { property: "og:type", content: "website" }], + ["meta", { property: "og:image", content: `${base}brand/neocode-mark.png` }], ["meta", { name: "twitter:card", content: "summary" }], // Favicon 路径随 base 变化 ["link", { rel: "icon", href: `${base}brand/neocode-mark.png` }], @@ -81,51 +69,52 @@ export default defineConfig({ link: "/", themeConfig: { nav: [ - { text: "开始使用", link: "/guide/" }, - { text: "配置", link: "/guide/configuration" }, - { text: "命令与会话", link: "/guide/quick-start" }, + { text: "快速开始", link: "/guide/" }, + { text: "日常使用", link: "/guide/daily-use" }, + { text: "排障", link: "/guide/troubleshooting" }, { text: "Gateway", link: "/guide/gateway" }, - { text: "深入阅读", link: "/reference/" }, + { text: "进阶与设计", link: "/reference/" }, { text: "GitHub", link: repoUrl }, ], sidebar: { "/guide/": [ { - text: "开始使用", + text: "快速开始", items: [ { text: "总览", link: "/guide/" }, - { text: "NeoCode 是什么", link: "/guide/getting-started" }, - { text: "安装与运行", link: "/guide/install" }, - { text: "首次上手", link: "/guide/quick-start" }, + { text: "安装与首次运行", link: "/guide/install" }, + { text: "使用示例", link: "/guide/examples" }, ], }, { text: "日常使用", items: [ - { text: "配置入口", link: "/guide/configuration" }, - { text: "工作区与会话", link: "/guide/workspace-session" }, - { text: "记忆与 Skills", link: "/guide/memo-skills" }, - { text: "Gateway 与 URL Dispatch", link: "/guide/gateway" }, - { text: "升级与版本检查", link: "/guide/update" }, + { text: "日常使用", link: "/guide/daily-use" }, + { text: "配置指南", link: "/guide/configuration" }, + { text: "工具与权限", link: "/guide/tools-permissions" }, ], }, - ], - "/reference/": [ { - text: "深入阅读", + text: "扩展能力", items: [ - { text: "文档导航", link: "/reference/" }, - { text: "旧入口兼容页", link: "/docs/" }, + { text: "MCP 工具接入", link: "/guide/mcp" }, + { text: "Skills 使用", link: "/guide/skills" }, + ], + }, + { + text: "质量与协作", + items: [ + { text: "排障与常见问题", link: "/guide/troubleshooting" }, + { text: "Gateway 使用", link: "/guide/gateway" }, + { text: "升级与版本检查", link: "/guide/update" }, ], }, ], - "/docs/": [ + "/reference/": [ { - text: "文档入口", + text: "深入阅读", items: [ - { text: "总览", link: "/docs/" }, - { text: "开始使用", link: "/guide/" }, - { text: "深入阅读", link: "/reference/" }, + { text: "文档导航", link: "/reference/" }, ], }, ], @@ -133,10 +122,10 @@ export default defineConfig({ { text: "快速导航", items: [ - { text: "开始使用", link: "/guide/" }, - { text: "安装与运行", link: "/guide/install" }, - { text: "首次上手", link: "/guide/quick-start" }, - { text: "配置入口", link: "/guide/configuration" }, + { text: "快速开始", link: "/guide/" }, + { text: "安装与首次运行", link: "/guide/install" }, + { text: "日常使用", link: "/guide/daily-use" }, + { text: "排障", link: "/guide/troubleshooting" }, ], }, ], @@ -169,18 +158,54 @@ export default defineConfig({ "A compact NeoCode docs entrypoint focused on current, verifiable behavior.", themeConfig: { nav: [ - { text: "Home", link: "/en/" }, - { text: "Docs", link: "/en/docs/" }, + { text: "Getting Started", link: "/en/guide/" }, + { text: "Daily Use", link: "/en/guide/daily-use" }, + { text: "Troubleshooting", link: "/en/guide/troubleshooting" }, + // Gateway 页面仅有中文版，英文站跨语言指向 + { text: "Gateway", link: "/guide/gateway" }, + { text: "Reference", link: "/reference/" }, { text: "GitHub", link: repoUrl }, ], sidebar: { - "/en/docs/": [ + "/en/guide/": [ + { + text: "Getting Started", + items: [ + { text: "Getting Started", link: "/en/guide/" }, + { text: "Install & First Run", link: "/en/guide/install" }, + { text: "Usage Examples", link: "/en/guide/examples" }, + ], + }, + { + text: "Daily Use", + items: [ + { text: "Daily Use", link: "/en/guide/daily-use" }, + { text: "Configuration", link: "/en/guide/configuration" }, + { text: "Tools & Permissions", link: "/en/guide/tools-permissions" }, + ], + }, + { + text: "Extensions", + items: [ + { text: "MCP Tools", link: "/en/guide/mcp" }, + { text: "Skills", link: "/en/guide/skills" }, + ], + }, + { + text: "Quality & Ops", + items: [ + { text: "Troubleshooting", link: "/en/guide/troubleshooting" }, + // Gateway 页面仅有中文版，英文站跨语言指向 + { text: "Gateway Usage", link: "/guide/gateway" }, + { text: "Update & Version", link: "/en/guide/update" }, + ], + }, + ], + "/reference/": [ { - text: "Overview", + text: "Reference", items: [ - { text: "Docs Index", link: "/en/docs/" }, - { text: "Chinese Guide", link: "/guide/" }, - { text: "Architecture Notes", link: "/reference/" }, + { text: "Documentation Index", link: "/reference/" }, ], }, ], @@ -210,9 +235,5 @@ export default defineConfig({ sitemap: { hostname: siteUrl, }, - vite: { - define: { - __NEOCODE_DOCS_BASE__: JSON.stringify(docsBase), - }, - }, + }); diff --git a/www/.vitepress/theme/components/HomeLanding.vue b/www/.vitepress/theme/components/HomeLanding.vue new file mode 100644 index 00000000..161685d9 --- /dev/null +++ b/www/.vitepress/theme/components/HomeLanding.vue @@ -0,0 +1,105 @@ + + + diff --git a/www/.vitepress/theme/components/TerminalPreview.vue b/www/.vitepress/theme/components/TerminalPreview.vue new file mode 100644 index 00000000..9e98fe76 --- /dev/null +++ b/www/.vitepress/theme/components/TerminalPreview.vue @@ -0,0 +1,115 @@ + + + + + diff --git a/www/.vitepress/theme/custom.css b/www/.vitepress/theme/custom.css index 90e1202a..9c951b3a 100644 --- a/www/.vitepress/theme/custom.css +++ b/www/.vitepress/theme/custom.css @@ -1,464 +1,407 @@ :root { - --neocode-ink: #090b1a; - --neocode-ink-2: #101323; - --neocode-ink-3: #15192b; - --neocode-peach: #fda580; - --neocode-peach-2: #ffbd9f; - --neocode-cream: #fff4ea; - --neocode-muted: #78645d; - --neocode-border: rgba(9, 11, 26, 0.12); - --neocode-border-warm: rgba(253, 165, 128, 0.28); - --neocode-shadow: 0 24px 70px rgba(9, 11, 26, 0.16); - --neocode-page-bg: #fff8f2; - --neocode-page-bg-alt: #f7ede5; - --neocode-home-glow: radial-gradient(circle at 16% 10%, rgba(253, 165, 128, 0.24), transparent 28%), - radial-gradient(circle at 86% 10%, rgba(253, 165, 128, 0.14), transparent 24%); - --neocode-nav-bg: rgba(255, 249, 244, 0.9); - --neocode-nav-border: rgba(9, 11, 26, 0.08); - --neocode-nav-control-bg: rgba(255, 255, 255, 0.74); - --neocode-nav-control-border: rgba(9, 11, 26, 0.1); - --neocode-surface-1: linear-gradient(180deg, rgba(255, 255, 255, 0.94), rgba(255, 245, 236, 0.88)); - --neocode-surface-2: linear-gradient(180deg, rgba(255, 255, 255, 0.9), rgba(255, 245, 236, 0.78)); - --neocode-surface-3: linear-gradient(180deg, rgba(255, 252, 249, 0.96), rgba(255, 246, 238, 0.82)); - --neocode-surface-raised: linear-gradient(145deg, rgba(255, 255, 255, 0.95), rgba(255, 245, 236, 0.84)); - --neocode-surface-border: rgba(253, 165, 128, 0.26); - --neocode-surface-border-strong: rgba(253, 165, 128, 0.38); - --neocode-surface-shadow: 0 18px 46px rgba(128, 92, 71, 0.12); - --neocode-surface-shadow-strong: 0 24px 60px rgba(128, 92, 71, 0.16); - --neocode-panel-text: #1f2434; - --neocode-panel-muted: #66585a; - --neocode-code-bg: #fffaf6; - --neocode-code-toolbar-bg: rgba(253, 165, 128, 0.14); - --neocode-code-text: #2a2131; - --neocode-doc-bg: transparent; - --neocode-sidebar-bg: transparent; - - --vp-c-brand-1: #d96542; - --vp-c-brand-2: #f0835f; - --vp-c-brand-3: #fda580; - --vp-c-brand-soft: rgba(253, 165, 128, 0.18); - --vp-c-bg: #fff8f2; - --vp-c-bg-alt: #f7ede5; - --vp-c-bg-soft: #f1e2d8; - --vp-c-text-1: #161828; - --vp-c-text-2: #5f5355; - --vp-c-text-3: #8d7a73; - --vp-c-divider: rgba(9, 11, 26, 0.1); - --vp-c-gutter: rgba(9, 11, 26, 0.08); - --vp-c-default-soft: rgba(9, 11, 26, 0.07); - --vp-c-tip-soft: rgba(253, 165, 128, 0.16); - --vp-home-hero-name-color: transparent; - --vp-home-hero-name-background: linear-gradient(125deg, #fff6ee 0%, #fda580 42%, #ffcfb7 100%); - --vp-button-brand-border: rgba(253, 165, 128, 0.5); - --vp-button-brand-text: #090b1a; - --vp-button-brand-bg: #fda580; - --vp-button-brand-hover-border: rgba(255, 210, 188, 0.7); - --vp-button-brand-hover-text: #090b1a; - --vp-button-brand-hover-bg: #ffbd9f; - --vp-button-brand-active-bg: #f0835f; - --vp-button-alt-border: rgba(9, 11, 26, 0.08); - --vp-button-alt-text: #2c2230; - --vp-button-alt-bg: rgba(255, 255, 255, 0.72); - --vp-button-alt-hover-border: rgba(253, 165, 128, 0.4); - --vp-button-alt-hover-text: #161828; - --vp-button-alt-hover-bg: rgba(255, 255, 255, 0.92); - --vp-font-family-base: "Aptos", "Segoe UI Variable", "PingFang SC", "Hiragino Sans GB", sans-serif; - --vp-font-family-mono: "Cascadia Code", "IBM Plex Mono", "SFMono-Regular", Consolas, monospace; + --nc-bg: #f7f7f4; + --nc-bg-soft: #efefeb; + --nc-surface: #ffffff; + --nc-surface-muted: #f3f3ef; + --nc-text: #111111; + --nc-text-soft: #343434; + --nc-muted: #6c6c66; + --nc-border: rgba(17, 17, 17, 0.12); + --nc-border-strong: rgba(17, 17, 17, 0.28); + --nc-accent: #0f766e; + --nc-accent-soft: rgba(15, 118, 110, 0.1); + --nc-success: #047857; + --nc-warning: #b45309; + --nc-danger: #b91c1c; + --nc-code-bg: #101213; + --nc-code-text: #f4f4ef; + --nc-code-toolbar-bg: #191c1d; + --nc-shadow: 0 1px 2px rgba(17, 17, 17, 0.05); + + --vp-c-brand-1: var(--nc-accent); + --vp-c-brand-2: #115e59; + --vp-c-brand-3: #0d9488; + --vp-c-brand-soft: var(--nc-accent-soft); + --vp-c-bg: var(--nc-bg); + --vp-c-bg-alt: var(--nc-bg-soft); + --vp-c-bg-soft: var(--nc-surface-muted); + --vp-c-text-1: var(--nc-text); + --vp-c-text-2: var(--nc-text-soft); + --vp-c-text-3: var(--nc-muted); + --vp-c-divider: var(--nc-border); + --vp-c-gutter: var(--nc-border); + --vp-c-default-soft: rgba(17, 17, 17, 0.05); + --vp-c-tip-soft: var(--nc-accent-soft); + --vp-c-warning-soft: rgba(180, 83, 9, 0.1); + --vp-c-danger-soft: rgba(185, 28, 28, 0.1); + + --vp-button-brand-border: var(--nc-text); + --vp-button-brand-text: #ffffff; + --vp-button-brand-bg: var(--nc-text); + --vp-button-brand-hover-border: var(--nc-accent); + --vp-button-brand-hover-text: #ffffff; + --vp-button-brand-hover-bg: var(--nc-accent); + --vp-button-brand-active-bg: #115e59; + --vp-button-alt-border: var(--nc-border); + --vp-button-alt-text: var(--nc-text); + --vp-button-alt-bg: transparent; + --vp-button-alt-hover-border: var(--nc-border-strong); + --vp-button-alt-hover-text: var(--nc-text); + --vp-button-alt-hover-bg: rgba(17, 17, 17, 0.04); + + --vp-font-family-base: "IBM Plex Sans", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif; + --vp-font-family-mono: "IBM Plex Mono", "JetBrains Mono", "Cascadia Code", "SFMono-Regular", Consolas, monospace; } .dark { - --neocode-border: rgba(253, 165, 128, 0.14); - --neocode-shadow: 0 26px 76px rgba(0, 0, 0, 0.42); - --neocode-page-bg: #090b1a; - --neocode-page-bg-alt: #0d1020; - --neocode-home-glow: radial-gradient(circle at 18% 8%, rgba(253, 165, 128, 0.18), transparent 28%), - radial-gradient(circle at 78% 0%, rgba(253, 165, 128, 0.08), transparent 28%); - --neocode-nav-bg: rgba(9, 11, 26, 0.78); - --neocode-nav-border: rgba(253, 165, 128, 0.13); - --neocode-nav-control-bg: rgba(255, 255, 255, 0.04); - --neocode-nav-control-border: rgba(253, 165, 128, 0.1); - --neocode-surface-1: linear-gradient(180deg, rgba(21, 25, 43, 0.96), rgba(9, 11, 26, 0.94)); - --neocode-surface-2: linear-gradient(180deg, rgba(255, 255, 255, 0.06), transparent 34%), rgba(255, 255, 255, 0.035); - --neocode-surface-3: linear-gradient(145deg, rgba(253, 165, 128, 0.1), transparent 45%), rgba(255, 255, 255, 0.035); - --neocode-surface-raised: linear-gradient(145deg, rgba(21, 25, 43, 0.96), rgba(9, 11, 26, 0.94)); - --neocode-surface-border: rgba(253, 165, 128, 0.18); - --neocode-surface-border-strong: rgba(253, 165, 128, 0.42); - --neocode-surface-shadow: 0 18px 46px rgba(0, 0, 0, 0.24); - --neocode-surface-shadow-strong: 0 24px 64px rgba(0, 0, 0, 0.24); - --neocode-panel-text: #fff4ea; - --neocode-panel-muted: rgba(255, 244, 234, 0.72); - --neocode-code-bg: #080a17; - --neocode-code-toolbar-bg: rgba(253, 165, 128, 0.07); - --neocode-code-text: #fff4ea; - --neocode-doc-bg: transparent; - --neocode-sidebar-bg: transparent; - - --vp-c-bg: #090b1a; - --vp-c-bg-alt: #0d1020; - --vp-c-bg-soft: #15192b; - --vp-c-text-1: #fff4ea; - --vp-c-text-2: #d7c8c0; - --vp-c-text-3: #a99389; - --vp-c-divider: rgba(253, 165, 128, 0.13); - --vp-c-gutter: rgba(253, 165, 128, 0.1); - --vp-c-default-soft: rgba(253, 165, 128, 0.08); - --vp-c-brand-1: #fda580; - --vp-c-brand-2: #ffbd9f; - --vp-c-brand-3: #ffd3c0; - --vp-c-brand-soft: rgba(253, 165, 128, 0.18); - --vp-button-alt-border: rgba(253, 165, 128, 0.24); - --vp-button-alt-text: #fff4ea; - --vp-button-alt-bg: rgba(255, 255, 255, 0.08); - --vp-button-alt-hover-border: rgba(253, 165, 128, 0.4); - --vp-button-alt-hover-text: #ffffff; - --vp-button-alt-hover-bg: rgba(253, 165, 128, 0.14); + --nc-bg: #181a1b; + --nc-bg-soft: #202323; + --nc-surface: #1e2122; + --nc-surface-muted: #272a2b; + --nc-text: #e8e6de; + --nc-text-soft: #c9c7bf; + --nc-muted: #9b9991; + --nc-border: rgba(232, 230, 222, 0.1); + --nc-border-strong: rgba(232, 230, 222, 0.22); + --nc-accent: #5eead4; + --nc-accent-soft: rgba(94, 234, 212, 0.1); + --nc-success: #34d399; + --nc-warning: #f59e0b; + --nc-danger: #f87171; + --nc-code-bg: #111314; + --nc-code-text: #e8e6de; + --nc-code-toolbar-bg: #191c1d; + --nc-shadow: none; + + --vp-button-brand-border: #ddd9cf; + --vp-button-brand-text: #181a1b; + --vp-button-brand-bg: #ddd9cf; + --vp-button-brand-hover-border: var(--nc-accent); + --vp-button-brand-hover-text: #181a1b; + --vp-button-brand-hover-bg: var(--nc-accent); + --vp-button-alt-border: var(--nc-border); + --vp-button-alt-text: var(--nc-text); + --vp-button-alt-bg: transparent; + --vp-button-alt-hover-border: var(--nc-border-strong); + --vp-button-alt-hover-bg: rgba(244, 244, 239, 0.06); +} + +html { + background: var(--nc-bg); } body { - background: - linear-gradient(180deg, rgba(255, 252, 248, 0.98), rgba(255, 248, 242, 0.92) 22%, var(--neocode-page-bg-alt) 100%); -} - -.dark body { - background: - var(--neocode-home-glow), - linear-gradient(180deg, #090b1a 0%, #0d1020 52%, #090b1a 100%); -} - -.Layout { - background: transparent; + background: var(--nc-bg); + color: var(--nc-text); } +.Layout, .VPContent { - background: transparent; + background: var(--nc-bg); } .VPNav { - backdrop-filter: blur(18px); - background-color: var(--neocode-nav-bg); - border-bottom: 1px solid var(--neocode-nav-border); + border-bottom: 1px solid var(--nc-border); + background: color-mix(in srgb, var(--nc-bg) 88%, transparent); } .VPNavBar, +.VPNavBar .content-body, +.VPNavBar .title, .VPLocalNav { - backdrop-filter: none; - background: transparent; - border-bottom: 0; + background: transparent !important; + border-bottom: 0 !important; } -.VPNavBar, -.VPNavBar .title, -.VPNavBar .content, -.VPNavBar .content-body, .VPNavBar .divider, .VPNavBar .divider-line { - background: transparent; - border-bottom: 0; -} - -.VPNavBar .divider { display: none; } -.VPNavBarTitle.has-sidebar .title { - border-bottom: 0 !important; -} - -@media (min-width: 960px) { - .VPNavBar.has-sidebar .container > .title { - box-sizing: border-box; - border-right: 1px solid var(--vp-c-divider); - } - - .VPNavBar.has-sidebar .content { - padding-left: calc(var(--vp-sidebar-width) + 1px); - } -} - .VPNavBarTitle .logo { - box-sizing: border-box; - width: 31px; - height: 31px; - padding: 0; - border-radius: 8px; - background: transparent; - box-shadow: 0 10px 28px rgba(9, 11, 26, 0.18); - object-fit: cover; + width: 28px; + height: 28px; + border-radius: 6px; + box-shadow: none; } .VPNavBarTitle .title { - letter-spacing: -0.03em; + font-family: var(--vp-font-family-mono); + font-size: 14px; + font-weight: 700; + letter-spacing: 0; } -.menu + .translations::before, -.menu + .appearance::before, -.menu + .social-links::before, -.translations + .appearance::before, -.appearance + .social-links::before { - content: none; +.VPNavBarMenuLink, +.VPNavBarMenuGroup .button span, +.VPNavBarTranslations .text { + font-size: 13px; + font-weight: 500; } -.VPNavBarTranslations, -.VPNavBarAppearance, -.VPNavBarSocialLinks { - margin-left: 4px; +.VPNavBarMenuLink:hover, +.VPNavBarMenuLink.active { + color: var(--nc-accent); } -.VPNavBarSocialLinks.social-links { - margin-right: 0; +.VPButton { + border-radius: 6px !important; + font-weight: 650; } -.VPNavBarExtra :is(.VPLocales, .VPSwitchAppearance), -.VPNavBarExtra .social-link, -.VPNavBarExtra .social-link .vpi { - color: var(--vp-c-text-1); +.VPButton.medium { + padding: 0 16px; } -.VPLocalNav { - top: var(--vp-nav-height); +.VPSidebar { + border-right: 1px solid var(--nc-border); + background: color-mix(in srgb, var(--nc-bg) 92%, transparent); } -.VPLocalNav.empty { - display: none !important; +.VPSidebarItem .text { + font-size: 13px; } -.VPLocalNav .menu, -.VPLocalNav .title, -.VPLocalNav .outline-title { - color: var(--vp-c-text-1); +.VPSidebarItem.is-active > .item .link > .text { + color: var(--nc-accent); } -.VPSidebar { - background: var(--neocode-sidebar-bg); - border-right: 1px solid var(--vp-c-divider); +.VPDoc { + padding-top: 42px; } -.VPDoc h1, -.VPDoc h2, -.VPDoc h3 { - letter-spacing: -0.015em; +.VPDoc .container { + max-width: 1160px; } -.VPDoc a, -.VPFooter a { - text-decoration-thickness: 0.08em; - text-underline-offset: 0.14em; +.VPDoc .content-container { + max-width: 760px; } -:is(.VPDoc div[class*='language-'], .vp-code-group) { - border: 1px solid var(--vp-c-divider); - box-shadow: none; +.home-page .VPDoc { + padding-top: 0; } -.dark :is(.VPDoc div[class*='language-'], .vp-code-group) { - border-color: var(--vp-c-divider); - box-shadow: none; +.home-page .VPDoc .container, +.home-page .VPDoc .content, +.home-page .VPDoc .content-container { + max-width: none; } -.VPHome { - position: relative; - animation: neocode-rise 460ms ease-out; +.home-page .VPDoc .content { + padding: 0; } -.VPHome::before { - position: absolute; - inset: 0 0 auto; - height: 520px; - content: ""; - pointer-events: none; - background: - var(--neocode-home-glow), - linear-gradient(180deg, rgba(255, 248, 242, 0.9), rgba(255, 248, 242, 0)); - z-index: 0; +.VPDoc h1, +.VPDoc h2, +.VPDoc h3 { + color: var(--nc-text); + font-weight: 700; + letter-spacing: 0; } -.dark .VPHome::before { - background: - var(--neocode-home-glow), - linear-gradient(180deg, rgba(9, 11, 26, 0.86), rgba(9, 11, 26, 0)); +.VPDoc h1 { + font-size: 40px; + line-height: 1.08; } -.VPHome > * { - position: relative; - z-index: 1; +.VPDoc h2 { + margin-top: 44px; + border-top: 1px solid var(--nc-border); + padding-top: 28px; + font-size: 26px; } -.VPHomeHero .container { - position: relative; - box-sizing: border-box; - margin-top: 24px; - padding: 64px 56px; - overflow: hidden; - border: 1px solid var(--neocode-surface-border-strong); - border-radius: 38px; - background: - linear-gradient(145deg, rgba(253, 165, 128, 0.16), rgba(255, 255, 255, 0) 32%), - linear-gradient(180deg, rgba(255, 255, 255, 0.95), rgba(255, 245, 236, 0.88)); - box-shadow: var(--neocode-shadow); +.VPDoc h3 { + font-size: 18px; } -.dark .VPHomeHero .container { - background: - linear-gradient(135deg, rgba(253, 165, 128, 0.12), transparent 26%), - radial-gradient(circle at 78% 22%, rgba(253, 165, 128, 0.18), transparent 24%), - linear-gradient(145deg, #090b1a 0%, #101323 55%, #15192b 100%); +.VPDoc p, +.VPDoc li { + color: var(--nc-text-soft); + line-height: 1.78; } -.VPHomeHero .container::before { - position: absolute; - inset: 16px; - pointer-events: none; - content: ""; - border: 1px solid rgba(253, 165, 128, 0.16); - border-radius: 28px; +.VPDoc a, +.VPFooter a { + color: var(--nc-accent); + text-decoration-thickness: 0.08em; + text-underline-offset: 0.16em; } -.dark .VPHomeHero .container::before { - border-color: rgba(253, 165, 128, 0.08); +.VPDoc table { + display: table; + width: 100%; + border-collapse: collapse; + overflow: hidden; + border: 1px solid var(--nc-border); + border-radius: 8px; + background: var(--nc-surface); + font-size: 14px; } -.VPHomeHero .container::after { - position: absolute; - right: 12%; - bottom: -16%; - width: 360px; - height: 160px; - pointer-events: none; - content: ""; - background: rgba(253, 165, 128, 0.14); - border-radius: 999px; - filter: blur(42px); +.VPDoc tr { + border-top: 1px solid var(--nc-border); } -.dark .VPHomeHero .container::after { - background: rgba(253, 165, 128, 0.08); +.VPDoc tr:nth-child(2n) { + background: color-mix(in srgb, var(--nc-surface-muted) 66%, transparent); } -.VPHomeHero .main, -.VPHomeHero .image { - position: relative; - z-index: 1; +.VPDoc th, +.VPDoc td { + border: 0; + padding: 12px 14px; } -.VPHomeHero .image { - align-self: center; - padding-top: 28px; +.VPDoc th { + color: var(--nc-text); + font-weight: 700; + text-align: left; + background: var(--nc-surface-muted); } -.VPHomeHero .text { - color: var(--neocode-panel-text); - letter-spacing: -0.04em; +:is(.VPDoc div[class*='language-'], .vp-code-group) { + border: 1px solid var(--nc-border); + border-radius: 8px; + box-shadow: none; } -.dark .VPHomeHero .text { - color: #fff4ea; +.custom-block { + border: 1px solid var(--nc-border); + border-radius: 8px; } -.VPHomeHero .tagline { - max-width: 560px; - color: var(--neocode-panel-muted); +.custom-block.tip { + border-color: color-mix(in srgb, var(--nc-accent) 28%, var(--nc-border)); } -.dark .VPHomeHero .tagline { - color: rgba(255, 244, 234, 0.72); +.custom-block.warning { + border-color: color-mix(in srgb, var(--nc-warning) 34%, var(--nc-border)); } -.VPHomeHero .actions { - padding-top: 10px; +.custom-block.danger { + border-color: color-mix(in srgb, var(--nc-danger) 34%, var(--nc-border)); } -.VPHomeHero .image-bg { - background-image: radial-gradient(circle, rgba(253, 165, 128, 0.3), transparent 62%); - filter: blur(64px); +.home-landing { + width: min(980px, calc(100vw - 56px)); + margin: 0 auto; + padding: 0; } -.VPHomeHero .image-container { - padding: 0; - border: 0; - border-radius: 28px; - background: transparent; - box-shadow: none; +.home-hero { + display: flex; + flex-direction: column; + padding: clamp(92px, 12vh, 132px) 0 72px; } -.VPHomeHero .image-src { - border-radius: 28px; - box-shadow: 0 26px 64px rgba(0, 0, 0, 0.16); +.home-eyebrow { + margin: 0 0 14px; + color: var(--nc-accent); + font-family: var(--vp-font-family-mono); + font-size: 12px; + font-weight: 700; + letter-spacing: 0; + text-transform: uppercase; } -.dark .VPHomeHero .image-src { - box-shadow: 0 26px 64px rgba(0, 0, 0, 0.28); +.home-hero h1 { + max-width: 920px; + margin: 0; + color: var(--nc-text); + font-size: clamp(42px, 5vw, 66px); + line-height: 1.08; + letter-spacing: 0; } -.VPFeatures { - padding-top: 36px; +.home-hero__lead { + max-width: 660px; + margin: 22px 0 0; + color: var(--nc-text-soft); + font-size: 19px; + line-height: 1.72; } -.VPFeature { - border: 1px solid var(--neocode-surface-border); - background: var(--neocode-surface-1); - box-shadow: var(--neocode-surface-shadow); +.home-actions { + display: flex; + flex-wrap: wrap; + gap: 10px; + margin-top: 30px; } -.VPFeature .title { - color: var(--neocode-panel-text); +.home-action { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 42px; + border: 1px solid var(--nc-border); + border-radius: 6px; + padding: 0 16px; + color: var(--nc-text); + font-weight: 700; + text-decoration: none; + transition: border-color 140ms ease, background-color 140ms ease, color 140ms ease; } -.VPFeature .details { - color: var(--neocode-panel-muted); +.home-action:hover { + border-color: var(--nc-border-strong); } -.home-section { - margin: 30px 0; - padding: 30px; - border: 1px solid var(--neocode-surface-border); - border-radius: 28px; - background: var(--neocode-surface-raised); - box-shadow: var(--neocode-surface-shadow-strong); - backdrop-filter: blur(10px); +.home-action--primary { + border-color: color-mix(in srgb, var(--nc-text) 86%, transparent); + background: color-mix(in srgb, var(--nc-text) 92%, transparent); + color: var(--nc-bg); } -.home-section.compact { - padding-top: 26px; +.home-action--primary:hover { + border-color: var(--nc-accent); + background: var(--nc-accent); + color: #ffffff; } -.home-section, -.home-section h2 { - color: var(--neocode-panel-text); +.dark .home-action--primary { + color: #181a1b; } -.home-section p, -.home-section span { - color: var(--neocode-panel-muted); +.home-values { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 18px; + max-width: 860px; + margin-top: 42px; + padding-top: 16px; + border-top: 1px solid color-mix(in srgb, var(--nc-border) 72%, transparent); } -.eyebrow { - margin: 0 0 8px; - color: var(--neocode-peach); - font-size: 12px; - font-weight: 800; - letter-spacing: 0.16em; - text-transform: uppercase; +.home-value { + min-width: 0; } -.home-section h2 { - margin-top: 0; - margin-bottom: 12px; - font-size: 28px; - line-height: 1.15; +.home-value strong { + display: block; + color: var(--nc-text); + font-size: 15px; + font-weight: 700; } -.home-section p:last-child { - margin-bottom: 0; +.home-value span { + display: block; + margin-top: 6px; + color: var(--nc-muted); + font-size: 14px; + line-height: 1.65; } .info-grid, .doc-grid, .quickstart-grid { display: grid; - gap: 18px; + gap: 14px; } -.info-grid { +.info-grid, +.quickstart-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } @@ -466,101 +409,82 @@ body { grid-template-columns: repeat(3, minmax(0, 1fr)); } -.quickstart-grid { - grid-template-columns: repeat(2, minmax(0, 1fr)); - align-items: stretch; -} - :is(.info-grid, .doc-grid, .quickstart-grid) > * { min-width: 0; } +.home-section, .info-card, -.quickstart-card { - padding: 22px; - border: 1px solid var(--neocode-surface-border); - border-radius: 22px; - background: var(--neocode-surface-2); - box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.4), var(--neocode-surface-shadow); -} - -:is(.info-card, .quickstart-card) h3 { - margin-top: 0; - margin-bottom: 10px; - color: var(--neocode-panel-text); -} - -.info-lines p { - margin: 0 0 10px; -} - -.info-lines p:last-child, -.quickstart-links p:last-child { - margin-bottom: 0; -} - -.quickstart-kicker { - margin: 0 0 8px; - color: var(--neocode-peach); - font-size: 12px; - font-weight: 800; - letter-spacing: 0.14em; - text-transform: uppercase; +.quickstart-card, +.doc-card { + border: 1px solid var(--nc-border); + border-radius: 8px; + background: var(--nc-surface); + box-shadow: var(--nc-shadow); } -.quickstart-links { - margin-top: 14px; +.home-section { + margin: 28px 0; + padding: 26px; } -.quickstart-links p { - margin: 0 0 10px; +.info-card, +.quickstart-card, +.doc-card { + padding: 20px; } .doc-card { display: block; - padding: 22px; color: inherit; text-decoration: none; - border: 1px solid var(--neocode-surface-border); - border-radius: 22px; - background: var(--neocode-surface-3); - box-shadow: var(--neocode-surface-shadow); - transition: transform 180ms ease, box-shadow 180ms ease, border-color 180ms ease, background-color 180ms ease; + transition: border-color 140ms ease, background-color 140ms ease; } .doc-card:hover { - transform: translateY(-4px); - border-color: var(--neocode-surface-border-strong); - box-shadow: var(--neocode-surface-shadow-strong); + border-color: var(--nc-border-strong); + background: var(--nc-surface-muted); } +.home-section h2, +.info-card h3, +.quickstart-card h3, .doc-card strong { - display: block; - margin-bottom: 8px; - color: var(--neocode-panel-text); - font-size: 17px; + color: var(--nc-text); + letter-spacing: 0; } -:is(.doc-card, .quickstart-card, .info-card) code { - color: #b35539; - background: rgba(253, 165, 128, 0.12); +.doc-card strong { + display: block; + margin-bottom: 8px; + font-size: 16px; } -.dark :is(.doc-card, .quickstart-card, .info-card) code { - color: #ffd0ba; +.home-section p, +.home-section span, +.info-card p, +.quickstart-card p, +.doc-card span { + color: var(--nc-muted); } -.architecture-block .code-panel { - margin-top: 14px; +.eyebrow, +.quickstart-kicker { + margin: 0 0 8px; + color: var(--nc-accent); + font-family: var(--vp-font-family-mono); + font-size: 12px; + font-weight: 700; + letter-spacing: 0; + text-transform: uppercase; } .code-panel { margin: 14px 0 0; overflow: hidden; - border: 1px solid var(--neocode-surface-border); - border-radius: 20px; - background: var(--neocode-code-bg); - box-shadow: var(--neocode-surface-shadow); + border: 1px solid var(--nc-border); + border-radius: 8px; + background: var(--nc-code-bg); } .code-panel + .code-panel { @@ -572,51 +496,51 @@ body { align-items: center; justify-content: space-between; gap: 12px; - padding: 10px 14px; - border-bottom: 1px solid rgba(253, 165, 128, 0.16); - background: var(--neocode-code-toolbar-bg); + padding: 9px 12px; + border-bottom: 1px solid rgba(244, 244, 239, 0.14); + background: var(--nc-code-toolbar-bg); } .code-panel__label { - color: var(--neocode-panel-muted); - font-size: 12px; - letter-spacing: 0.08em; + color: rgba(244, 244, 239, 0.68); + font-family: var(--vp-font-family-mono); + font-size: 11px; + letter-spacing: 0; text-transform: uppercase; } .code-panel__copy { appearance: none; - border: 1px solid transparent; - border-radius: 999px; - padding: 6px 12px; - color: #090b1a; + border: 1px solid rgba(244, 244, 239, 0.2); + border-radius: 6px; + padding: 4px 10px; + color: #f4f4ef; font: inherit; - font-size: 12px; + font-size: 11px; font-weight: 700; - background: rgba(253, 165, 128, 0.94); + background: transparent; cursor: pointer; - transition: transform 140ms ease, background-color 140ms ease, border-color 140ms ease; } .code-panel__copy:hover { - transform: translateY(-1px); - background: #ffbd9f; + border-color: rgba(244, 244, 239, 0.46); } .code-panel__copy.is-success { - background: rgba(70, 211, 142, 0.92); + border-color: var(--nc-success); + color: var(--nc-success); } .code-panel__copy.is-error { - color: #fff4ea; - background: rgba(190, 24, 93, 0.88); + border-color: var(--nc-danger); + color: var(--nc-danger); } .code-panel pre { margin: 0; - padding: 16px; + padding: 14px; overflow-x: auto; - color: var(--neocode-code-text); + color: var(--nc-code-text); } .code-panel code { @@ -627,100 +551,87 @@ body { white-space: pre; } -@keyframes neocode-rise { - from { - opacity: 0; - transform: translateY(12px); - } - to { - opacity: 1; - transform: translateY(0); - } +:is(.doc-card, .quickstart-card, .info-card) code { + border-radius: 4px; + padding: 0.12em 0.34em; + color: var(--nc-accent); + background: var(--nc-accent-soft); } -@media (max-width: 1320px) { +@media (max-width: 1100px) { + .home-hero { + padding-top: 80px; + } + .quickstart-grid, .doc-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } - - .doc-grid .doc-card:last-child { - grid-column: 1 / -1; - } } -@media (max-width: 960px) { - .VPHomeHero .container { - padding: 42px 30px; - border-radius: 30px; - } - - .VPHomeHero .image { - padding-top: 8px; - } - - .info-grid, - .quickstart-grid, - .doc-grid { - grid-template-columns: 1fr; +@media (max-width: 760px) { + .VPDoc { + padding-top: 24px; } - .doc-grid .doc-card:last-child { - grid-column: auto; + .VPDoc h1 { + font-size: 32px; } -} -@media (max-width: 720px) { - .VPHome::before { - height: 360px; + .VPDoc h2 { + font-size: 23px; } - .VPHomeHero .container { - margin-top: 8px; - padding: 30px 20px; - border-radius: 24px; + .home-landing { + width: min(100% - 32px, 980px); } - .VPHomeHero .container::before { - inset: 10px; - border-radius: 18px; + .home-hero { + padding: 58px 0 46px; } - .VPHomeHero .image { - padding-top: 0; + .home-hero h1 { + font-size: 38px; + line-height: 1.08; } - .VPHomeHero .image-container { - padding: 0; - border-radius: 20px; + .home-hero__lead { + margin-top: 18px; + font-size: 16px; + line-height: 1.72; } - .VPHomeHero .image-src { - border-radius: 20px; + .home-actions { + margin-top: 26px; } - .home-section { - margin: 20px 0; - padding: 20px; - border-radius: 22px; + .home-values { + grid-template-columns: 1fr; + gap: 14px; + margin-top: 30px; } - .home-section h2 { - font-size: 24px; + .info-grid, + .quickstart-grid, + .doc-grid { + grid-template-columns: 1fr; } + .home-section, .info-card, .quickstart-card, .doc-card { padding: 18px; - border-radius: 18px; - } - - .code-panel__toolbar { - padding: 10px 12px; } +} - .code-panel pre { - padding: 14px; +@media (prefers-reduced-motion: reduce) { + *, + *::before, + *::after { + scroll-behavior: auto !important; + transition-duration: 0.01ms !important; + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; } } diff --git a/www/.vitepress/theme/index.ts b/www/.vitepress/theme/index.ts index ecbe7785..89a63803 100644 --- a/www/.vitepress/theme/index.ts +++ b/www/.vitepress/theme/index.ts @@ -2,13 +2,17 @@ import DefaultTheme from 'vitepress/theme' import './custom.css' import ArchitectureGrid from './components/ArchitectureGrid.vue' import CodePanel from './components/CodePanel.vue' +import HomeLanding from './components/HomeLanding.vue' import QuickStartCards from './components/QuickStartCards.vue' +import TerminalPreview from './components/TerminalPreview.vue' export default { ...DefaultTheme, enhanceApp({ app }) { app.component('ArchitectureGrid', ArchitectureGrid) app.component('CodePanel', CodePanel) + app.component('HomeLanding', HomeLanding) app.component('QuickStartCards', QuickStartCards) + app.component('TerminalPreview', TerminalPreview) } } diff --git a/www/docs/guides/configuration.md b/www/docs/guides/configuration.md deleted file mode 100644 index a34bd1aa..00000000 --- a/www/docs/guides/configuration.md +++ /dev/null @@ -1,167 +0,0 @@ -# 配置指南 - -本文说明 NeoCode 当前真实生效的配置规则。 - -## 总原则 - -- `config.yaml` 只保存最小运行时状态 -- provider 元数据来自代码内置定义或 custom provider 文件 -- API Key 只从环境变量读取 -- YAML 采用严格解析，未知字段直接报错 - -这意味着 NeoCode 当前不会： - -- 自动清理旧版 `providers` / `provider_overrides` -- 自动兼容 `workdir`、`default_workdir` 等旧字段 - -## 配置文件位置 - -主配置文件路径： - -```text -~/.neocode/config.yaml -``` - -custom provider 目录： - -```text -~/.neocode/providers//provider.yaml -``` - -## `config.yaml` 可写字段 - -当前支持的主配置示例： - -```yaml -selected_provider: openai -current_model: gpt-5.4 -shell: bash -tool_timeout_sec: 20 -runtime: - max_no_progress_streak: 3 - max_repeat_cycle_streak: 3 - assets: - max_session_asset_bytes: 20971520 - max_session_assets_total_bytes: 20971520 - -tools: - webfetch: - max_response_bytes: 262144 - supported_content_types: - - text/html - - text/plain - - application/json - -context: - compact: - manual_strategy: keep_recent - manual_keep_recent_messages: 10 - micro_compact_retained_tool_spans: 6 - read_time_max_message_spans: 24 - max_summary_chars: 1200 - micro_compact_disabled: false - auto_compact: - enabled: false - input_token_threshold: 0 - reserve_tokens: 13000 - fallback_input_token_threshold: 100000 -``` - -### 基础字段 - -| 字段 | 说明 | -|------|------| -| `selected_provider` | 当前选中的 provider 名称 | -| `current_model` | 当前选中的模型 ID | -| `shell` | 默认 shell，Windows 默认 `powershell`，其他平台默认 `bash` | -| `tool_timeout_sec` | 工具执行超时（秒） | - -### `context` 字段 - -| 字段 | 说明 | -|------|------| -| `context.compact.manual_strategy` | `/compact` 手动压缩策略，支持 `keep_recent` / `full_replace` | -| `context.compact.manual_keep_recent_messages` | `keep_recent` 策略下保留的最近消息数 | -| `context.compact.micro_compact_retained_tool_spans` | 默认保留原始内容的最近可压缩工具块数量，默认 `6` | -| `context.compact.read_time_max_message_spans` | context 读时保留的 message span 上限 | -| `context.compact.max_summary_chars` | compact summary 最大字符数 | -| `context.compact.micro_compact_disabled` | 是否关闭默认启用的 micro compact | -| `context.auto_compact.enabled` | 是否启用自动压缩 | -| `context.auto_compact.input_token_threshold` | 自动压缩输入 token 阈值 | -| `context.auto_compact.reserve_tokens` | 自动阈值推导时预留 token 缓冲 | -| `context.auto_compact.fallback_input_token_threshold` | 自动推导失败时使用的保底阈值 | - -### `runtime` 字段 - -| 字段 | 说明 | -|------|------| -| `runtime.max_no_progress_streak` | 连续"无进展"轮次熔断阈值，默认 `3` | -| `runtime.max_repeat_cycle_streak` | 连续"重复调用同一工具参数"轮次熔断阈值，默认 `3` | -| `runtime.assets.max_session_asset_bytes` | 单个 session asset 最大字节数，默认 20 MiB | -| `runtime.assets.max_session_assets_total_bytes` | 单次请求可携带的 session asset 总字节上限，默认 20 MiB | - -### `tools` 字段 - -| 字段 | 说明 | -|------|------| -| `tools.webfetch.max_response_bytes` | WebFetch 最大响应字节数 | -| `tools.webfetch.supported_content_types` | WebFetch 允许的内容类型 | -| `tools.mcp.servers` | MCP server 列表，见 [MCP 配置](./mcp) | - -## 不写入 `config.yaml` 的字段 - -以下内容不允许写入主配置文件： - -- `providers` -- `provider_overrides` -- `workdir` -- `default_workdir` -- `base_url` -- `api_key_env` -- `models` - -如果这些字段出现在 `config.yaml` 中，加载会直接失败。 - -## 环境变量 - -API Key 只从系统环境变量读取。 - -| Provider | 环境变量 | -|----------|----------| -| `openai` | `OPENAI_API_KEY` | -| `gemini` | `GEMINI_API_KEY` | -| `openll` | `AI_API_KEY` | -| `qiniu` | `QINIU_API_KEY` | - -```bash -export OPENAI_API_KEY="sk-..." -export GEMINI_API_KEY="AI..." -``` - -## CLI 运行参数覆盖 - -工作目录不写入 `config.yaml`，只通过启动参数覆盖： - -```bash -neocode --workdir /path/to/workspace -``` - -## 常见错误 - -### 旧字段被拒绝 - -如果在 `config.yaml` 中包含 `workdir`、`providers` 等字段，当前版本会报未知字段错误。处理方式是手动删除这些字段。 - -### API Key 未设置 - -```text -config: environment variable OPENAI_API_KEY is empty -``` - -在当前 shell 中设置对应环境变量后再启动 NeoCode。 - -## 相关文档 - -- [切换模型](./providers) -- [MCP 配置](./mcp) -- [更新升级](./update) diff --git a/www/docs/guides/mcp.md b/www/docs/guides/mcp.md deleted file mode 100644 index d89ab9b3..00000000 --- a/www/docs/guides/mcp.md +++ /dev/null @@ -1,74 +0,0 @@ -# MCP 配置指南 - -NeoCode 支持通过 stdio 接入 MCP（Model Context Protocol）server，将外部工具暴露给 Agent 调用。 - -## 配置位置 - -在 `~/.neocode/config.yaml` 中添加 `tools.mcp.servers`： - -```yaml -tools: - mcp: - servers: - - id: docs - enabled: true - source: stdio - version: v1 - stdio: - command: node - args: - - ./mcp-server.js - workdir: ./mcp - start_timeout_sec: 8 - call_timeout_sec: 20 - restart_backoff_sec: 1 - env: - - name: MCP_TOKEN - value_env: MCP_TOKEN -``` - -## 字段说明 - -| 字段 | 说明 | -|------|------| -| `id` | server 标识，工具命名空间为 `mcp..` | -| `enabled` | 是否启用，只有 `true` 的 server 会在启动时注册 | -| `source` | 传输类型，当前仅支持 `stdio` | -| `stdio.command` | 启动命令（启用时必填） | -| `stdio.args` | 启动参数列表 | -| `stdio.workdir` | 子进程工作目录，支持相对路径 | -| `stdio.start_timeout_sec` | 启动超时（秒） | -| `stdio.call_timeout_sec` | 调用超时（秒） | -| `stdio.restart_backoff_sec` | 重启间隔（秒） | -| `env` | 传给 MCP 子进程的环境变量，推荐用 `value_env` 引用系统变量 | - -## 启动行为 - -- 启动阶段注册所有 `enabled: true` 的 server -- 注册后执行一次 `tools/list` 初始化工具快照 -- 若注册失败，启动会报错并中止（fail-fast） - -## 验证工具是否可用 - -启动后让 Agent 列出可用工具： - -``` -请先列出你当前可用工具的完整名称。 -``` - -确认 `mcp.docs.` 存在后，发起一次明确调用： - -``` -请调用 mcp.docs.search，参数 {"query":"hello"}，并返回工具结果。 -``` - -## 排查 `tool not found` - -- 检查 `enabled` 是否为 `true` -- 检查 `stdio.command` 是否可执行 -- 检查 `env.value_env` 对应的环境变量是否已设置 -- 检查 MCP server 是否支持 `tools/list` - -## 相关文档 - -- [配置指南](./configuration) diff --git a/www/docs/guides/providers.md b/www/docs/guides/providers.md deleted file mode 100644 index a11e18f7..00000000 --- a/www/docs/guides/providers.md +++ /dev/null @@ -1,73 +0,0 @@ -# 切换模型与 Provider - -NeoCode 支持多个模型服务商（provider），可以随时切换。 - -## 内置 Provider - -当前内置的 provider： - -| Provider | 环境变量 | -|----------|----------| -| `openai` | `OPENAI_API_KEY` | -| `gemini` | `GEMINI_API_KEY` | -| `openll` | `AI_API_KEY` | -| `qiniu` | `QINIU_API_KEY` | - -## 在 TUI 中切换 - -启动 NeoCode 后，在交互界面中可以直接切换 provider 和模型。切换结果会保存到 `~/.neocode/config.yaml` 的 `selected_provider` 和 `current_model` 字段。 - -## 添加自定义 Provider - -对于兼容 OpenAI 接口的服务（企业网关、本地模型等），创建以下文件： - -```text -~/.neocode/providers//provider.yaml -``` - -示例配置： - -```yaml -name: company-gateway -driver: openaicompat -api_key_env: COMPANY_GATEWAY_API_KEY -model_source: discover -base_url: https://llm.example.com/v1 -chat_api_mode: chat_completions -chat_endpoint_path: /chat/completions -discovery_endpoint_path: /models -``` - -### 手动指定模型列表 - -如果 provider 不支持模型发现（`/models` 接口），使用 `model_source: manual`： - -```yaml -name: company-gateway -driver: openaicompat -api_key_env: COMPANY_GATEWAY_API_KEY -model_source: manual -base_url: https://llm.example.com/v1 -chat_endpoint_path: /chat/completions -models: - - id: gpt-4o-mini - name: GPT-4o Mini - context_window: 128000 -``` - -### 字段说明 - -| 字段 | 说明 | -|------|------| -| `name` | provider 标识，用于 `selected_provider` | -| `driver` | 驱动类型，目前支持 `openaicompat` | -| `api_key_env` | API Key 的环境变量名 | -| `model_source` | `discover`（自动发现）或 `manual`（手动列表） | -| `base_url` | 服务 base URL | -| `chat_api_mode` | `chat_completions` 或 `responses` | -| `chat_endpoint_path` | 聊天接口路径 | -| `discovery_endpoint_path` | 模型发现接口路径（`discover` 模式） | - -## 相关文档 - -- [配置指南](./configuration) diff --git a/www/docs/guides/update.md b/www/docs/guides/update.md deleted file mode 100644 index 413588ff..00000000 --- a/www/docs/guides/update.md +++ /dev/null @@ -1,24 +0,0 @@ -# 更新升级 - -## 自动检测 - -NeoCode 启动时会在后台静默检测最新版本（默认 3 秒超时）。更新提示会在应用退出后输出，不干扰 TUI 交互。 - -## 手动升级 - -升级到最新稳定版： - -```bash -neocode update -``` - -包含预发布版本： - -```bash -neocode update --prerelease -``` - -## 版本说明 - -- 发布构建通过 `ldflags` 注入版本号 -- 本地开发构建默认版本为 `dev` diff --git a/www/docs/index.md b/www/docs/index.md deleted file mode 100644 index 7c2ae72e..00000000 --- a/www/docs/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 文档总览 -description: 旧入口兼容页，帮助你从旧的 /docs/ 路径切换到新的用户指南与参考文档。 ---- - -# 文档总览 - -`/docs/` 现在作为兼容入口保留，新的阅读路径分成两类： - -- [开始使用与用户指南](/guide/)：安装、首次上手、配置、工作区、会话、记忆、Skills、Gateway 与升级说明。 -- [深入阅读与设计文档](/reference/)：汇总仓库 `docs/` 中的设计文档和适用场景。 - -## 推荐阅读顺序 - -1. [NeoCode 是什么](/guide/getting-started) -2. [安装与运行](/guide/install) -3. [首次上手](/guide/quick-start) -4. [配置入口](/guide/configuration) -5. [Gateway 与 URL Dispatch](/guide/gateway) - -## 直接跳转 - -- [开始使用](/guide/) -- [配置与 Provider](/guide/configuration) -- [工作区与会话](/guide/workspace-session) -- [记忆与 Skills](/guide/memo-skills) -- [深入阅读](/reference/) \ No newline at end of file diff --git a/www/docs/quick-start.md b/www/docs/quick-start.md deleted file mode 100644 index 6b02c119..00000000 --- a/www/docs/quick-start.md +++ /dev/null @@ -1,59 +0,0 @@ -# 快速开始 - -## 安装 - -### macOS / Linux - -```bash -curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash -``` - -### Windows PowerShell - -```powershell -irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex -``` - -### 从源码运行 - -适合想阅读代码、调试功能或参与开发的方式： - -```bash -git clone https://github.com/1024XEngineer/neo-code.git -cd neo-code -go run ./cmd/neocode -``` - -## 配置 API Key - -NeoCode 从系统环境变量读取 API Key，不会写入配置文件。 - -```bash -# 选择你要使用的 provider，设置对应的环境变量 -export OPENAI_API_KEY="sk-..." -export GEMINI_API_KEY="AI..." -``` - -完整的 provider 与环境变量对应关系见[配置指南](./guides/configuration)。 - -## 启动 - -```bash -neocode -``` - -默认使用上次保存的 provider 和模型。首次启动会进入交互式选择。 - -## 指定工作目录 - -```bash -neocode --workdir /path/to/your/project -``` - -工作目录只对当前进程生效，不会写入配置文件。 - -## 下一步 - -- [配置 provider 和模型](./guides/configuration) -- [切换模型](./guides/providers) -- [配置 MCP 工具](./guides/mcp) diff --git a/www/docs/reference/architecture.md b/www/docs/reference/architecture.md deleted file mode 100644 index bdd6d6c6..00000000 --- a/www/docs/reference/architecture.md +++ /dev/null @@ -1,28 +0,0 @@ -# 架构概览 - -NeoCode 是一个基于 Go 实现的本地 AI 编码助手，主链路为： - -**用户输入 → Agent 推理 → 调用工具 → 获取结果 → 继续推理 → UI 展示** - -## 核心层级 - -| 层级 | 职责 | -|------|------| -| TUI（`internal/tui`） | 终端界面，使用 Bubble Tea 构建，负责展示和输入 | -| Runtime（`internal/runtime`） | ReAct 主循环，编排 Agent 推理、工具调用和状态管理 | -| Provider（`internal/provider`） | 模型服务适配器，将厂商差异收敛在此层 | -| Tools（`internal/tools`） | 工具实现，文件操作、Bash 执行、WebFetch 等 | -| Session（`internal/session`） | 会话持久化，JSON 存储 | -| Config（`internal/config`） | 配置加载与校验 | - -## 设计原则 - -- **层间单向依赖**：TUI 只调用 Runtime，Runtime 只调用 Provider 和 Tool Manager -- **厂商差异隔离**：模型协议差异（OpenAI / Gemini / Anthropic）收敛在 `internal/provider`，不泄漏到上层 -- **工具能力集中**：所有可被模型调用的能力进入 `internal/tools`，不散落在其他层 -- **状态统一管理**：会话状态、消息历史、工具调用记录由 `runtime` 统一管理 - -## 相关文档 - -- [配置指南](../guides/configuration) -- [切换模型](../guides/providers) diff --git a/www/en/docs/guides/configuration.md b/www/en/docs/guides/configuration.md deleted file mode 100644 index b37deffb..00000000 --- a/www/en/docs/guides/configuration.md +++ /dev/null @@ -1,148 +0,0 @@ -# Configuration Guide - -This page covers the configuration rules that NeoCode enforces. - -## Core rules - -- `config.yaml` stores only minimal runtime state -- Provider metadata comes from built-in definitions or custom provider files -- API keys are read from environment variables only -- YAML is parsed strictly — unknown fields cause a startup error - -NeoCode does not: - -- Auto-migrate old `providers` / `provider_overrides` fields -- Silently ignore `workdir`, `default_workdir`, or other legacy fields - -## Config file location - -Main config: - -```text -~/.neocode/config.yaml -``` - -Custom provider directory: - -```text -~/.neocode/providers//provider.yaml -``` - -## Writable fields in `config.yaml` - -```yaml -selected_provider: openai -current_model: gpt-5.4 -shell: bash -tool_timeout_sec: 20 -runtime: - max_no_progress_streak: 3 - max_repeat_cycle_streak: 3 - assets: - max_session_asset_bytes: 20971520 - max_session_assets_total_bytes: 20971520 - -tools: - webfetch: - max_response_bytes: 262144 - supported_content_types: - - text/html - - text/plain - - application/json - -context: - compact: - manual_strategy: keep_recent - manual_keep_recent_messages: 10 - micro_compact_retained_tool_spans: 6 - read_time_max_message_spans: 24 - max_summary_chars: 1200 - micro_compact_disabled: false - auto_compact: - enabled: false - input_token_threshold: 0 - reserve_tokens: 13000 - fallback_input_token_threshold: 100000 -``` - -### Basic fields - -| Field | Description | -|-------|-------------| -| `selected_provider` | Active provider name | -| `current_model` | Active model ID | -| `shell` | Default shell (`powershell` on Windows, `bash` elsewhere) | -| `tool_timeout_sec` | Tool execution timeout in seconds | - -### `runtime` fields - -| Field | Description | -|-------|-------------| -| `runtime.max_no_progress_streak` | Consecutive no-progress rounds before circuit break, default `3` | -| `runtime.max_repeat_cycle_streak` | Consecutive repeated tool calls before circuit break, default `3` | -| `runtime.assets.max_session_asset_bytes` | Max bytes per session asset, default 20 MiB | -| `runtime.assets.max_session_assets_total_bytes` | Max total session asset bytes per request, default 20 MiB | - -### `tools` fields - -| Field | Description | -|-------|-------------| -| `tools.webfetch.max_response_bytes` | Max response bytes for WebFetch | -| `tools.webfetch.supported_content_types` | Allowed content types for WebFetch | -| `tools.mcp.servers` | MCP server list, see [MCP Configuration](./mcp) | - -## Fields that must NOT be in `config.yaml` - -These fields will cause a startup error if present: - -- `providers` -- `provider_overrides` -- `workdir` -- `default_workdir` -- `base_url` -- `api_key_env` -- `models` - -Remove them manually — NeoCode does not auto-migrate them. - -## Environment variables - -| Provider | Environment variable | -|----------|---------------------| -| `openai` | `OPENAI_API_KEY` | -| `gemini` | `GEMINI_API_KEY` | -| `openll` | `AI_API_KEY` | -| `qiniu` | `QINIU_API_KEY` | - -```bash -export OPENAI_API_KEY="sk-..." -export GEMINI_API_KEY="AI..." -``` - -## CLI overrides - -Working directory is passed at startup, not saved: - -```bash -neocode --workdir /path/to/workspace -``` - -## Common errors - -### Unknown field error - -If `config.yaml` contains `workdir`, `providers`, or similar legacy fields, remove them manually. - -### API key not set - -```text -config: environment variable OPENAI_API_KEY is empty -``` - -Set the environment variable in your shell before starting NeoCode. - -## Related - -- [Switch models](./providers) -- [MCP configuration](./mcp) -- [Updating](./update) diff --git a/www/en/docs/guides/mcp.md b/www/en/docs/guides/mcp.md deleted file mode 100644 index 60dee1d2..00000000 --- a/www/en/docs/guides/mcp.md +++ /dev/null @@ -1,74 +0,0 @@ -# MCP Configuration - -NeoCode supports connecting to MCP (Model Context Protocol) servers via stdio, exposing external tools to the agent. - -## Configuration - -Add `tools.mcp.servers` to `~/.neocode/config.yaml`: - -```yaml -tools: - mcp: - servers: - - id: docs - enabled: true - source: stdio - version: v1 - stdio: - command: node - args: - - ./mcp-server.js - workdir: ./mcp - start_timeout_sec: 8 - call_timeout_sec: 20 - restart_backoff_sec: 1 - env: - - name: MCP_TOKEN - value_env: MCP_TOKEN -``` - -## Field reference - -| Field | Description | -|-------|-------------| -| `id` | Server identifier. Tools are namespaced as `mcp..` | -| `enabled` | Only servers with `true` are registered at startup | -| `source` | Transport type. Currently only `stdio` is supported | -| `stdio.command` | Startup command (required when enabled) | -| `stdio.args` | Startup arguments | -| `stdio.workdir` | Child process working directory (relative paths supported) | -| `stdio.start_timeout_sec` | Startup timeout in seconds | -| `stdio.call_timeout_sec` | Call timeout in seconds | -| `stdio.restart_backoff_sec` | Restart interval in seconds | -| `env` | Environment variables passed to the MCP process. Use `value_env` to reference system variables | - -## Startup behavior - -- All `enabled: true` servers are registered at startup -- A `tools/list` call is made after registration to snapshot available tools -- If a registered server fails to start, NeoCode exits with an error (fail-fast) - -## Verify tool availability - -Ask the agent to list its tools: - -``` -List all the tools you currently have available. -``` - -Then make a direct call to confirm: - -``` -Call mcp.docs.search with {"query": "hello"} and return the result. -``` - -## Troubleshooting `tool not found` - -- Check that `enabled` is `true` -- Check that `stdio.command` is executable -- Check that `env.value_env` environment variables are set -- Check that the MCP server supports `tools/list` - -## Related - -- [Configuration guide](./configuration) diff --git a/www/en/docs/guides/providers.md b/www/en/docs/guides/providers.md deleted file mode 100644 index 2b718a94..00000000 --- a/www/en/docs/guides/providers.md +++ /dev/null @@ -1,71 +0,0 @@ -# Switching Models and Providers - -NeoCode supports multiple model providers and lets you switch between them at any time. - -## Built-in providers - -| Provider | Environment variable | -|----------|---------------------| -| `openai` | `OPENAI_API_KEY` | -| `gemini` | `GEMINI_API_KEY` | -| `openll` | `AI_API_KEY` | -| `qiniu` | `QINIU_API_KEY` | - -## Switching in the TUI - -Select a different provider or model from the interactive menu inside NeoCode. The selection is saved to `~/.neocode/config.yaml`. - -## Adding a custom provider - -For any OpenAI-compatible API (enterprise gateways, local models), create: - -```text -~/.neocode/providers//provider.yaml -``` - -Example: - -```yaml -name: company-gateway -driver: openaicompat -api_key_env: COMPANY_GATEWAY_API_KEY -model_source: discover -base_url: https://llm.example.com/v1 -chat_api_mode: chat_completions -chat_endpoint_path: /chat/completions -discovery_endpoint_path: /models -``` - -### Manual model list - -If the provider does not support model discovery, use `model_source: manual`: - -```yaml -name: company-gateway -driver: openaicompat -api_key_env: COMPANY_GATEWAY_API_KEY -model_source: manual -base_url: https://llm.example.com/v1 -chat_endpoint_path: /chat/completions -models: - - id: gpt-4o-mini - name: GPT-4o Mini - context_window: 128000 -``` - -### Field reference - -| Field | Description | -|-------|-------------| -| `name` | Provider identifier, used in `selected_provider` | -| `driver` | Driver type. Currently supports `openaicompat` | -| `api_key_env` | Environment variable name for the API key | -| `model_source` | `discover` (auto) or `manual` (explicit list) | -| `base_url` | Service base URL | -| `chat_api_mode` | `chat_completions` or `responses` | -| `chat_endpoint_path` | Chat endpoint path | -| `discovery_endpoint_path` | Model discovery path (`discover` mode only) | - -## Related - -- [Configuration guide](./configuration) diff --git a/www/en/docs/guides/update.md b/www/en/docs/guides/update.md deleted file mode 100644 index 5870d0bc..00000000 --- a/www/en/docs/guides/update.md +++ /dev/null @@ -1,24 +0,0 @@ -# Updating - -## Automatic update check - -NeoCode silently checks for a newer version in the background at startup (3-second timeout). The update notice is printed after you exit the TUI, so it does not interrupt the session. - -## Manual upgrade - -Upgrade to the latest stable release: - -```bash -neocode update -``` - -Include pre-release versions: - -```bash -neocode update --prerelease -``` - -## Version info - -- Release builds have a version injected via `ldflags` -- Local development builds report `dev` diff --git a/www/en/docs/index.md b/www/en/docs/index.md deleted file mode 100644 index 06fdba37..00000000 --- a/www/en/docs/index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Docs Index -description: A compact English entrypoint that links to the primary Chinese guide and repository design documents. ---- - -# Docs Index - -The Chinese guide is the primary documentation set for NeoCode right now. This page links to the most useful entry points. - -## Start Here - -If you are new to NeoCode, read in this order: - -1. [What is NeoCode](/guide/getting-started) (Chinese) -2. [Install and run](/guide/install) (Chinese) -3. [Quick start](/guide/quick-start) (Chinese) -4. [Configuration](/guide/configuration) (Chinese) -5. [Gateway and URL dispatch](/guide/gateway) (Chinese) - -## Direct Links - -- [Chinese guide overview](/guide/) -- [Install and run](/guide/install) -- [Quick start](/guide/quick-start) -- [Configuration](/guide/configuration) -- [Workspace and sessions](/guide/workspace-session) -- [Memory and Skills](/guide/memo-skills) -- [Gateway and URL dispatch](/guide/gateway) -- [Update and version check](/guide/update) - -## Reference - -- [Reference index](/reference/) -- [README](https://github.com/1024XEngineer/neo-code/blob/main/README.md) -- [Configuration guide](https://github.com/1024XEngineer/neo-code/blob/main/docs/guides/configuration.md) -- [Gateway detailed design](https://github.com/1024XEngineer/neo-code/blob/main/docs/gateway-detailed-design.md) - -## Notes - -- The guide content only covers behavior that exists in the repository today. -- The previous `/docs/` route is now a compatibility entrypoint in Chinese. \ No newline at end of file diff --git a/www/en/docs/quick-start.md b/www/en/docs/quick-start.md deleted file mode 100644 index b7e43427..00000000 --- a/www/en/docs/quick-start.md +++ /dev/null @@ -1,59 +0,0 @@ -# Quick Start - -## Install - -### macOS / Linux - -```bash -curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash -``` - -### Windows PowerShell - -```powershell -irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex -``` - -### Run from source - -For contributors who want to inspect the code or work on the codebase: - -```bash -git clone https://github.com/1024XEngineer/neo-code.git -cd neo-code -go run ./cmd/neocode -``` - -## Set API keys - -NeoCode reads API keys from environment variables. Keys are never written to config files. - -```bash -# Set the key for the provider you want to use -export OPENAI_API_KEY="sk-..." -export GEMINI_API_KEY="AI..." -``` - -See the [configuration guide](./guides/configuration) for a full list of providers and their environment variables. - -## Start - -```bash -neocode -``` - -On first run, NeoCode will prompt you to select a provider and model. Your choice is saved to `~/.neocode/config.yaml`. - -## Set a working directory - -```bash -neocode --workdir /path/to/your/project -``` - -The working directory applies to the current process only and is not saved to config. - -## Next steps - -- [Configure providers and models](./guides/configuration) -- [Switch models](./guides/providers) -- [Set up MCP tools](./guides/mcp) diff --git a/www/en/docs/reference/architecture.md b/www/en/docs/reference/architecture.md deleted file mode 100644 index 25454164..00000000 --- a/www/en/docs/reference/architecture.md +++ /dev/null @@ -1,28 +0,0 @@ -# Architecture Overview - -NeoCode is a local AI coding agent written in Go. The main execution path is: - -**User Input → Agent Reasoning → Tool Call → Result → Continue Reasoning → UI Output** - -## Core layers - -| Layer | Responsibility | -|-------|---------------| -| TUI (`internal/tui`) | Terminal interface built with Bubble Tea. Handles display and input | -| Runtime (`internal/runtime`) | ReAct main loop. Orchestrates reasoning, tool calls, and state management | -| Provider (`internal/provider`) | Model service adapters. Vendor differences are contained here | -| Tools (`internal/tools`) | Tool implementations: file operations, bash execution, WebFetch, etc. | -| Session (`internal/session`) | Session persistence via JSON | -| Config (`internal/config`) | Configuration loading and validation | - -## Design principles - -- **One-way layer dependencies**: TUI calls Runtime; Runtime calls Provider and Tool Manager only -- **Vendor isolation**: Protocol differences (OpenAI / Gemini / Anthropic) stay inside `internal/provider` -- **Centralized tool capabilities**: All agent-callable capabilities live in `internal/tools` -- **Unified state management**: Session state, message history, and tool call records are managed by `runtime` - -## Related - -- [Configuration guide](../guides/configuration) -- [Switching models](../guides/providers) diff --git a/www/en/guide/configuration.md b/www/en/guide/configuration.md new file mode 100644 index 00000000..d10b85b8 --- /dev/null +++ b/www/en/guide/configuration.md @@ -0,0 +1,299 @@ +--- +title: Configuration +description: Minimal config to get running, then adjust models, shell, timeout, and custom providers as needed. +--- + +# Configuration + +## General principles + +- `config.yaml` only stores minimal runtime state +- Provider metadata comes from built-in definitions or custom provider files +- API keys are read from environment variables only +- YAML uses strict parsing — unknown fields cause errors + +This means NeoCode currently will not: + +- Auto-clean legacy `providers` / `provider_overrides` fields +- Auto-compat `workdir`, `default_workdir`, or other legacy fields + +## Minimal config + +To get NeoCode running, this is all you need: + +```yaml +selected_provider: openai +current_model: gpt-5.4 +shell: bash +``` + +Windows users should change `shell` to `powershell`. All other fields have defaults. + +Config file location: `~/.neocode/config.yaml` + +## Common tasks + +### Switch models + +Switch directly in the TUI — the selection is saved automatically: + +```text +/provider # Switch provider +/model # Switch model +``` + +If the model list is empty, check that the corresponding environment variable is set. + +### Change shell + +```yaml +shell: powershell # Windows +shell: bash # macOS / Linux +``` + +### Adjust tool timeout + +```yaml +tool_timeout_sec: 30 # Default is 20 seconds +``` + +### Long sessions drifting + +Try `/compact` first. If it happens often, increase the retained messages in config: + +```yaml +context: + compact: + manual_keep_recent_messages: 20 # Default is 10 +``` + +## Full config example + +```yaml +selected_provider: openai +current_model: gpt-5.4 +shell: bash +tool_timeout_sec: 20 +runtime: + max_no_progress_streak: 3 + max_repeat_cycle_streak: 3 + assets: + max_session_asset_bytes: 20971520 + max_session_assets_total_bytes: 20971520 + +tools: + webfetch: + max_response_bytes: 262144 + supported_content_types: + - text/html + - text/plain + - application/json + +context: + compact: + manual_strategy: keep_recent + manual_keep_recent_messages: 10 + micro_compact_retained_tool_spans: 6 + read_time_max_message_spans: 24 + max_summary_chars: 1200 + micro_compact_disabled: false + budget: + prompt_budget: 0 + reserve_tokens: 13000 + fallback_prompt_budget: 100000 + max_reactive_compacts: 3 +``` + +## Field reference + +### Basic fields + +| Field | Description | +|-------|-------------| +| `selected_provider` | Currently selected provider name | +| `current_model` | Currently selected model ID | +| `shell` | Default shell. Windows defaults to `powershell`, other platforms to `bash` | +| `tool_timeout_sec` | Tool execution timeout in seconds | + +### `context` fields + +| Field | Description | +|-------|-------------| +| `context.compact.manual_strategy` | `/compact` strategy: `keep_recent` / `full_replace` | +| `context.compact.manual_keep_recent_messages` | Number of recent messages to keep under `keep_recent` | +| `context.compact.micro_compact_retained_tool_spans` | Number of recent compressible tool blocks to retain original content for, default `6` | +| `context.compact.read_time_max_message_spans` | Upper limit of message spans retained at context read time | +| `context.compact.max_summary_chars` | Maximum characters for compact summary | +| `context.compact.micro_compact_disabled` | Whether to disable the default micro compact | +| `context.budget.prompt_budget` | Explicit input budget; `> 0` uses directly, `0` means auto-derive | +| `context.budget.reserve_tokens` | Buffer reserved from model window for output, tool calls, and system prompt when auto-deriving | +| `context.budget.fallback_prompt_budget` | Fallback input budget when model window is unavailable or derivation fails | +| `context.budget.max_reactive_compacts` | Maximum reactive compact count allowed within a single Run | + +### `runtime` fields + +| Field | Description | +|-------|-------------| +| `runtime.max_no_progress_streak` | Threshold for consecutive "no progress" turn warnings, default `5` | +| `runtime.max_repeat_cycle_streak` | Threshold for consecutive "same tool same args" warnings, default `3` | +| `runtime.max_turns` | Maximum reasoning turns per Run, default `40` | +| `runtime.assets.max_session_asset_bytes` | Maximum bytes for a single session asset, default 20 MiB | +| `runtime.assets.max_session_assets_total_bytes` | Total byte limit for session assets per request, default 20 MiB | + +### `verification` fields + +| Field | Description | +|-------|-------------| +| `verification.enabled` | Whether to enable the verification engine, default `true` | +| `verification.final_intercept` | Whether to intercept and trigger verification before task completion, default `true` | +| `verification.max_no_progress` | Maximum retries when verification shows no progress, default `3` | +| `verification.max_retries` | Maximum retries after verification failure, default `2` | +| `verification.verifiers..enabled` | Whether to enable this verifier | +| `verification.verifiers..required` | Whether this verifier is a hard requirement | +| `verification.verifiers..timeout_sec` | Execution timeout for this verifier | +| `verification.verifiers..fail_closed` | Whether to treat verifier errors as failures | +| `verification.execution_policy.allowed_commands` | Command whitelist for verifiers | +| `verification.execution_policy.denied_commands` | Command blacklist for verifiers | + +### `tools` fields + +| Field | Description | +|-------|-------------| +| `tools.webfetch.max_response_bytes` | Maximum response bytes for WebFetch | +| `tools.webfetch.supported_content_types` | Allowed content types for WebFetch | +| `tools.mcp.servers` | MCP server list, see MCP configuration below | + +## Environment variables + +API keys are read from environment variables only, never written to config files. + +| Provider | Environment variable | +|---|---| +| OpenAI | `OPENAI_API_KEY` | +| Gemini | `GEMINI_API_KEY` | +| OpenLL | `AI_API_KEY` | +| Qiniu | `QINIU_API_KEY` | +| ModelScope | `MODELSCOPE_API_KEY` | + +```bash +export OPENAI_API_KEY="sk-..." +export GEMINI_API_KEY="AI..." +export MODELSCOPE_API_KEY="ms-..." +``` + +## Custom providers + +If your model service isn't in the built-in list, you can add it via a config file. + +Config file location: `~/.neocode/providers//provider.yaml` + +Example (OpenAI-compatible endpoint): + +```yaml +name: company-gateway +driver: openaicompat +api_key_env: COMPANY_GATEWAY_API_KEY +model_source: discover +base_url: https://llm.example.com/v1 +chat_api_mode: chat_completions +chat_endpoint_path: /chat/completions +discovery_endpoint_path: /models +``` + +You can also use `/provider add` in the TUI to add interactively. + +### Manual model list + +If the provider does not support model discovery, use `model_source: manual`: + +```yaml +name: company-gateway +driver: openaicompat +api_key_env: COMPANY_GATEWAY_API_KEY +model_source: manual +base_url: https://llm.example.com/v1 +chat_endpoint_path: /chat/completions +models: + - id: gpt-4o-mini + name: GPT-4o Mini + context_window: 128000 +``` + +### Custom provider field reference + +| Field | Description | +|-------|-------------| +| `name` | Provider identifier, used in `selected_provider` | +| `driver` | Driver type. Currently supports `openaicompat` | +| `api_key_env` | Environment variable name for the API key | +| `model_source` | `discover` (auto) or `manual` (explicit list) | +| `base_url` | Service base URL | +| `chat_api_mode` | `chat_completions` or `responses` | +| `chat_endpoint_path` | Chat endpoint path | +| `discovery_endpoint_path` | Model discovery path (`discover` mode only) | + +## MCP tools + +If you have an MCP server, register it in `config.yaml` through `tools.mcp.servers`. NeoCode currently supports `stdio` servers, and registered tools are named as `mcp..`. + +```yaml +tools: + mcp: + servers: + - id: docs + enabled: true + source: stdio + version: v1 + stdio: + command: node + args: + - ./mcp-server.js + workdir: ./mcp + start_timeout_sec: 8 + call_timeout_sec: 20 + restart_backoff_sec: 1 + env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +For the full field reference, exposure policy, verification prompts, and troubleshooting steps, see [MCP Tools](./mcp). + +## Fields not allowed in config.yaml + +These fields cause a startup error if present in the main config file: + +`providers`, `provider_overrides`, `workdir`, `default_workdir`, `base_url`, `api_key_env`, `models` + +## Common errors + +### Legacy fields rejected + +If `config.yaml` contains `workdir`, `providers`, etc., the current version will report an unknown field error. Remove these fields manually. + +### Legacy `context.auto_compact` field + +If only `context.auto_compact` exists in config, preflight will auto-migrate it to `context.budget` and write a `config.yaml.bak` backup. If both `context.auto_compact` and `context.budget` are present, startup will error — merge them manually before restarting. + +### API key not set + +```text +config: environment variable OPENAI_API_KEY is empty +``` + +Set the corresponding environment variable in your current shell, then launch NeoCode. + +## CLI argument overrides + +Working directory is not written to `config.yaml` — override it via the launch argument: + +```bash +neocode --workdir /path/to/workspace +``` + +## Next steps + +- Daily operations: [Daily use](./daily-use) +- What the agent can do: [Tools & permissions](./tools-permissions) +- Something wrong: [Troubleshooting](./troubleshooting) +- Check for updates: [Update & Version](./update) diff --git a/www/en/guide/daily-use.md b/www/en/guide/daily-use.md new file mode 100644 index 00000000..12102370 --- /dev/null +++ b/www/en/guide/daily-use.md @@ -0,0 +1,90 @@ +--- +title: Daily Use +description: Session management, memory, skills, and subagents — the operations you use every day. +--- + +# Daily Use + +## Session management + +### Switch workspace + +```text +/cwd # View current workspace +/cwd /path/to/project # Switch to another project +``` + +### Switch session + +```text +/session # Open session picker, switch to another session +``` + +### Compress long sessions + +When the conversation gets too long, agent quality drops. Run a compression to clean up old context: + +```text +/compact +``` + +### New session vs. continue + +| Scenario | Recommendation | +|---|---| +| Finished a feature, starting unrelated bug fix | New session | +| Continuing to refine the same feature | Continue current session | +| Switching to a completely different project | New session + switch workspace | +| Session is long and responses drift | Try `/compact` first, then new session if needed | + +## Memory + +Memory saves preferences and project facts across sessions — no need to repeat yourself. + +### Common operations + +```text +/memo # View all memories +/remember I prefer powershell # Save a memory +/forget powershell # Delete matching memory +``` + +### Memory vs. Skills + +- **Memory**: Saves facts and preferences, persists across sessions. E.g. "I prefer powershell", "This project uses Go 1.25" +- **Skills**: Saves workflow hints, active in current session. E.g. "Read before modifying" + +Quick rule: Need it across sessions → memory. Need a special workflow for the current task → skill. + +## Skills + +Skills are workflow hints that influence agent behavior in the current session. For authoring and loading rules, see [Skills](./skills). + +### Common operations + +```text +/skills # View available skills +/skill use go-review # Activate a skill in current session +/skill off go-review # Deactivate a skill +/skill active # View active skills in current session +``` + +Quick rule: need a special workflow for the current task → enable a Skill; need a long-term fact → use memory; need a real external tool → use [MCP](./mcp). + +## Subagents + +The agent can launch subagents to handle subtasks in parallel — e.g. a researcher to search, a reviewer to check results. You don't need to trigger this manually; the agent decides when to use subagents. + +If you want to encourage subagent use, say something like: + +```text +Use the researcher role to search all compact-related function signatures in internal/runtime +Use the reviewer role to check if the recent changes meet test coverage requirements +``` + +## Next steps + +- Configure models and providers: [Configuration](./configuration) +- What the agent can do and when it needs approval: [Tools & permissions](./tools-permissions) +- Write or activate a Skill: [Skills](./skills) +- Something wrong: [Troubleshooting](./troubleshooting) diff --git a/www/en/guide/examples.md b/www/en/guide/examples.md new file mode 100644 index 00000000..d418e8b6 --- /dev/null +++ b/www/en/guide/examples.md @@ -0,0 +1,130 @@ +--- +title: Usage Examples +description: Four copy-pasteable scenarios to help you get comfortable with NeoCode quickly. +--- + +# Usage Examples + +All examples below are based on NeoCode's currently implemented TUI, tools, and Gateway capabilities. You can copy them directly into a session. + +--- + +## Scenario 1: Understand an unfamiliar project + +**Goal**: You just cloned a repo and want a quick overview of the directory structure and module responsibilities. + +**Prompt**: + +```text +Please read the current project directory structure and summarize each module's responsibilities. If you see an internal/ directory, explain the boundaries of each subpackage in particular. +``` + +**Expected behavior**: + +- NeoCode will call file-read tools to scan directories +- Provide a structured summary of module responsibilities +- If the tree is deep, it may ask whether to continue expanding + +**Key decision points**: + +- If it requests reading many files, choose **Allow** (read-only, no risk) +- If it suggests running `find` or `tree`, choose **Allow** (read_only classification) + +--- + +## Scenario 2: Locate and fix a bug + +**Goal**: A test fails and you want to find the root cause and a fix. + +**Prompt (step 1 — provide context)**: + +```text +I see the following test failure. Please locate the root cause and propose a fix: +``` + +Paste the failure log after this line. + +**Prompt (step 2 — ask it to apply)**: + +```text +Please modify the corresponding file to fix this issue and describe the verification steps. Only change one file. +``` + +**Expected behavior**: + +- Read the relevant source and test files +- Pinpoint the specific function or logic error +- Provide a code diff with the fix +- Remind you how to run the test to verify + +**Key decision points**: + +- When it requests file modifications, choose **Ask** or **Allow** (local_mutation, controllable) +- When it requests running the test command, choose **Allow** (necessary verification step) + +--- + +## Scenario 3: Add tests for a function + +**Goal**: Generate unit tests for a function that currently lacks them. + +**Prompt**: + +```text +Please generate unit tests for the ReadFile function in internal/tools/file.go, covering the happy path, file-not-found, and permission-denied cases. Write the tests to internal/tools/file_test.go. +``` + +**Expected behavior**: + +- Read the target function source to understand inputs and outputs +- Generate corresponding test cases +- After writing the file, ask whether to run verification + +**Prompt (verification)**: + +```text +Please run the tests for this package. If any fail, analyze and fix them. +``` + +**Key decision points**: + +- File writes are local_mutation; **Ask** is recommended (confirm path and content are correct) +- Running tests is read_only / local_mutation; **Allow** is fine + +--- + +## Scenario 4: Add a new feature / endpoint + +**Goal**: Add a new endpoint or feature point to existing code. + +**Prompt (design phase)**: + +```text +I want to add a health-check endpoint in internal/gateway that returns the current runtime status. Please propose an implementation plan, including which files need to be modified. +``` + +**Prompt (implementation phase)**: + +```text +Please implement according to the plan, keeping the style consistent with existing code. After finishing, run go build ./... to verify compilation passes. +``` + +**Expected behavior**: + +- Analyze the existing gateway route registration pattern +- Add a new handler and register the route +- Run the build to verify + +**Key decision points**: + +- For multi-file modifications, **Ask** each time to confirm +- Running `go build` is read_only (verification only), **Allow** is fine + +--- + +## Next steps + +- Permission decision details: [Tools & permissions](./tools-permissions) +- Configure models and providers: [Configuration](./configuration) +- Daily operations: [Daily use](./daily-use) +- Something wrong: [Troubleshooting](./troubleshooting) diff --git a/www/en/guide/index.md b/www/en/guide/index.md new file mode 100644 index 00000000..b94b417a --- /dev/null +++ b/www/en/guide/index.md @@ -0,0 +1,37 @@ +--- +title: Getting Started +description: Find what you need — install, daily use, or troubleshooting. +--- + +# Getting Started + +NeoCode is a local AI coding agent that runs in your terminal. + +## New here? + +From zero to running in 3 minutes: + +1. [Install & First Run](./install) — get it running, set API key, first conversation +2. [Usage Examples](./examples) — 4 copy-pasteable scenarios +3. [Configuration](./configuration) — switch models, custom providers + +## Daily use + +Already using it? Look up operations and config: + +- [Daily Use](./daily-use) — session management, memory, skills, common commands +- [Tools & Permissions](./tools-permissions) — what the agent can do, when it needs your approval +- [Configuration](./configuration) — common config tasks + +## Extensions + +Connect NeoCode to your own workflow: + +- [MCP Tools](./mcp) — connect external tools, control exposure, and verify availability +- [Skills](./skills) — codify workflow guidance and task constraints with `SKILL.md` + +## Something wrong? + +- [Troubleshooting](./troubleshooting) — 3-step diagnosis by symptom +- [Gateway Usage](/guide/gateway) — when to start gateway separately +- [Update & Version](./update) — check version, upgrade diff --git a/www/en/guide/install.md b/www/en/guide/install.md new file mode 100644 index 00000000..249dc281 --- /dev/null +++ b/www/en/guide/install.md @@ -0,0 +1,118 @@ +--- +title: Install & First Run +description: From installation to your first conversation in 3 minutes. +--- + +# Install & First Run + +## 1. Requirements + +- At least one API key (OpenAI, Gemini, OpenLL, Qiniu, or ModelScope) +- Go 1.25+ if running from source + +## 2. Install + +### One-line install (recommended) + +macOS / Linux: + +```bash +curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash +``` + +Windows PowerShell: + +```powershell +irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex +``` + +### Run from source + +```bash +git clone https://github.com/1024XEngineer/neo-code.git +cd neo-code +go run ./cmd/neocode +``` + +## 3. Set API key + +NeoCode reads API keys from environment variables — they are never written to config files. + +macOS / Linux: + +```bash +export OPENAI_API_KEY="your_key_here" +``` + +Windows PowerShell: + +```powershell +$env:OPENAI_API_KEY = "your_key_here" +``` + +Other providers: + +| Provider | Environment variable | +|---|---| +| OpenAI | `OPENAI_API_KEY` | +| Gemini | `GEMINI_API_KEY` | +| OpenLL | `AI_API_KEY` | +| Qiniu | `QINIU_API_KEY` | +| ModelScope | `MODELSCOPE_API_KEY` | + +## 4. Launch + +```bash +neocode +``` + +You'll see the TUI interface. Type at the bottom to start a conversation. + +To specify a workspace: + +```bash +neocode --workdir /path/to/your/project +``` + +## 5. First conversation + +Not sure what to ask? Try these: + +```text +Read the current project directory structure and give a module summary +``` + +```text +Find the tool result injection logic in internal/runtime +``` + +The agent will automatically use file reading and search tools. When it requests file writes or command execution, the TUI will prompt for your approval. + +## 6. Command cheat sheet + +Inside the TUI, type `/` commands to perform operations: + +| Command | Action | +|---|---| +| `/help` | Show all commands | +| `/provider` | Switch provider | +| `/model` | Switch model | +| `/status` | Show current status | +| `/compact` | Compress long session context | +| `/cwd [path]` | View/switch workspace | +| `/session` | Switch session | +| `/memo` | View memory index | +| `/remember ` | Save memory | +| `/forget ` | Delete memory | +| `/skills` | View available skills | +| `/exit` | Exit NeoCode | + +## Installation issues? + +See [Troubleshooting](./troubleshooting) + +## Next steps + +- More usage scenarios: [Usage examples](./examples) +- Switch models or add custom providers: [Configuration](./configuration) +- Daily operations: [Daily use](./daily-use) diff --git a/www/en/guide/mcp.md b/www/en/guide/mcp.md new file mode 100644 index 00000000..abdb1f8a --- /dev/null +++ b/www/en/guide/mcp.md @@ -0,0 +1,204 @@ +--- +title: MCP Tools +description: Connect external MCP servers to NeoCode and let the agent call them through the normal tool system. +--- + +# MCP Tools + +MCP is useful when you already have external capabilities that NeoCode should call, such as internal documentation search, issue lookup, private platform operations, or team-specific automation. + +In NeoCode, MCP tools are not a special bypass. They enter the normal tool registry and still follow tool naming, approval, and exposure rules. + +## When to use MCP + +| Goal | Recommendation | +|---|---| +| Let the agent query internal docs, issue systems, or private platforms | Use MCP | +| Add a real callable external tool | Use MCP | +| Make the agent follow a workflow | Use [Skills](./skills) | +| Save personal preferences or project facts | Use `/remember` memory | + +## Current support + +NeoCode currently supports `stdio` MCP servers only. NeoCode starts a local child process from your config and communicates with it through standard input and output. + +After registration, tool names use this format: + +```text +mcp.. +``` + +For example, if the server id is `docs` and it exposes a `search` tool, the full tool name is `mcp.docs.search`. + +## Configure an MCP server + +Config file: + +```text +~/.neocode/config.yaml +``` + +Minimal example: + +```yaml +tools: + mcp: + servers: + - id: docs + enabled: true + source: stdio + version: v1 + stdio: + command: node + args: + - ./mcp-server.js + workdir: ./mcp + start_timeout_sec: 8 + call_timeout_sec: 20 + restart_backoff_sec: 1 + env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +### Field reference + +| Field | Description | +|---|---| +| `id` | Stable server identifier, used in `mcp..` | +| `enabled` | Only `true` servers are registered on startup | +| `source` | Currently only `stdio` is supported. Empty also means `stdio` | +| `version` | Version label for your own config tracking | +| `stdio.command` | Startup command. Required when the server is enabled | +| `stdio.args` | Startup arguments | +| `stdio.workdir` | Child process working directory. Relative paths are supported | +| `stdio.start_timeout_sec` | Startup timeout | +| `stdio.call_timeout_sec` | Per-call tool timeout | +| `stdio.restart_backoff_sec` | Restart backoff | +| `env` | Environment variables passed to the MCP child process | + +::: tip +Put secrets in system environment variables and reference them with `value_env`. Do not write tokens, API keys, or passwords directly into `config.yaml`. +::: + +## Environment variables + +Each `env` entry must set `name`, and must set exactly one of `value` or `value_env`. + +Recommended: + +```yaml +env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +This reads the system environment variable `MCP_TOKEN` from the shell that starts NeoCode, then passes it into the MCP child process as `MCP_TOKEN`. + +Not recommended: + +```yaml +env: + - name: MCP_TOKEN + value: real-token-here +``` + +## Startup behavior + +On startup, NeoCode: + +1. Reads `tools.mcp.servers`. +2. Skips servers with `enabled: false`. +3. Starts each enabled `stdio` server. +4. Calls `tools/list` once to build the initial tool snapshot. +5. Registers tools as `mcp..`. + +If an enabled server fails to start, misses an environment variable, or fails `tools/list`, NeoCode fails startup. This is intentional: a broken tool config should be visible immediately. + +## Control exposed MCP tools + +If a server exposes many tools, use `exposure` to control what the agent can see. + +```yaml +tools: + mcp: + exposure: + allowlist: + - mcp.docs.* + denylist: + - mcp.docs.delete* + agents: + - agent: default + allowlist: + - mcp.docs.search + servers: + - id: docs + enabled: true + source: stdio + stdio: + command: node + args: + - ./mcp-server.js +``` + +Recommended use: + +| Config | Effect | +|---|---| +| `allowlist` | Expose only matching MCP tools | +| `denylist` | Hide matching MCP tools. Deny wins over allow | +| `agents` | Set visible tools by agent name | + +Patterns can be full tool names or globs, such as `mcp.docs.*`. To target a server, use `mcp.docs`. + +## Verify availability + +After starting NeoCode, ask the agent to list tools: + +```text +List all the tools you currently have available. +``` + +After confirming `mcp.docs.search` is present, make a direct call: + +```text +Call mcp.docs.search with {"query":"hello"} and return the tool result. +``` + +If the tool requires specific arguments, follow your MCP server schema. + +## Common issues + +### `tool not found` + +Check in order: + +- `enabled` is `true` +- `id` is correct, so the tool name is `mcp..` +- `stdio.command` is executable in the current environment +- `stdio.workdir` points to the right directory +- system variables referenced by `env.value_env` are set +- the MCP server supports `tools/list` +- `exposure.allowlist` or `exposure.denylist` did not filter the tool out + +### Startup says an environment variable is empty + +If your config contains: + +```yaml +env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +you must set `MCP_TOKEN` in the same shell that starts NeoCode. + +### The server starts, but calls fail + +Check the MCP server logs, the tool input schema, and `stdio.call_timeout_sec`. NeoCode wraps call failures as tool errors, but the business error usually comes from the MCP server. + +## Next steps + +- Control agent workflow: [Skills](./skills) +- Understand approvals: [Tools & Permissions](./tools-permissions) +- Review full config: [Configuration](./configuration) diff --git a/www/en/guide/skills.md b/www/en/guide/skills.md new file mode 100644 index 00000000..b373d8fd --- /dev/null +++ b/www/en/guide/skills.md @@ -0,0 +1,176 @@ +--- +title: Skills +description: Use SKILL.md files to codify workflow guidance for the current NeoCode session. +--- + +# Skills + +Skills are NeoCode's workflow guidance layer. A Skill injects reusable task instructions, references, examples, and tool preferences into the current session context so the agent works in a specific way. + +Skills do not bypass approval, register tools, or replace MCP. They tell the agent how to approach a class of tasks. + +## When to use Skills + +| Goal | Recommendation | +|---|---| +| Make code reviews follow a fixed checklist | Use a Skill | +| Make the agent read specific docs before a task | Use a Skill | +| Encourage a certain workflow or tool preference | Use a Skill | +| Add a real callable external service | Use [MCP](./mcp) | +| Save long-term personal preferences or project facts | Use `/remember` memory | + +## Where Skills live + +Local Skills are loaded from: + +```text +~/.neocode/skills/ +``` + +A Skill can be a directory: + +```text +~/.neocode/skills/go-review/SKILL.md +``` + +A root-level `SKILL.md` is also supported. Subdirectories are clearer because each Skill gets its own name and boundary. + +## Create a Skill + +Example: `~/.neocode/skills/go-review/SKILL.md` + +```md +--- +id: go-review +name: Go Review +description: Review Go changes for correctness, boundaries, and tests. +version: v1 +scope: explicit +tool_hints: + - filesystem_grep + - bash +--- + +# Go Review + +## Instruction + +Read the relevant Go files and tests before reviewing. Focus on behavior regressions, module boundaries, error handling, and test gaps. Do not request broad refactors for style preferences. + +## References + +- title: Repo rules + path: AGENTS.md + summary: Follow repository boundaries and testing expectations. + +## Examples + +- When the user asks for a review, list high-risk findings first, then a short summary. + +## ToolHints + +- filesystem_grep +- bash +``` + +### Common fields + +| Field | Description | +|---|---| +| `id` | Skill identifier. If omitted, NeoCode derives it from the directory name | +| `name` | Display name. If omitted, NeoCode tries the first H1 heading | +| `description` | Short explanation shown in lists | +| `version` | Version label. Defaults to `v1` | +| `scope` | Scope. Defaults to `explicit` | +| `tool_hints` | Tool preference hints. This is not authorization | + +### Common sections + +| Section | Purpose | +|---|---| +| `Instruction` | Main workflow guidance. This is the most important part | +| `References` | Reference summaries | +| `Examples` | Example tasks or expected behavior | +| `ToolHints` | Suggested tools to consider | + +If there is no `Instruction` section, NeoCode uses the body as the instruction. + +## Activate and deactivate + +Use these commands in the TUI: + +```text +/skills # View available skills +/skill use go-review # Activate a skill in current session +/skill off go-review # Deactivate a skill +/skill active # View active skills in current session +``` + +Notes: + +- `/skill use ` affects only the current session. +- Activated Skills are restored with the session record. +- Skill management requires an active session. If NeoCode just started, send one message or switch sessions first. +- Gateway mode does not currently support Skills management. Use local runtime for these commands. + +## What the agent sees + +For each turn, NeoCode renders active Skills into the `Skills` context section. It includes: + +- Skill name and ID +- `Instruction` +- up to 3 `ToolHints` +- up to 3 `References` +- up to 2 `Examples` + +This affects planning and responses, but not tool permissions. For example, a Skill can say "prefer bash", but high-risk commands still go through normal approval. + +## Skills vs memory vs MCP + +| Capability | Solves | Executes tools | Automatically applies across sessions | +|---|---|---|---| +| Skills | Current task workflow and constraints | No | No, activate per session | +| Memory | Long-term preferences and project facts | No | Yes | +| MCP | External callable tools | Yes | Depends on config | + +Quick rule: + +- Change how the agent works: use Skills. +- Make the agent remember a fact: use memory. +- Add real tool capability: use MCP. + +## Common issues + +### `/skills` does not show my Skill + +Check: + +- The file is under `~/.neocode/skills/` +- The filename is `SKILL.md` +- The Skill file is not too large +- Frontmatter is valid YAML +- `id` is not duplicated + +NeoCode skips invalid Skills, but one broken Skill does not block all others from loading. + +### The Skill is active but has little effect + +Make `Instruction` more specific. Avoid vague text like "be more careful"; define the reading order, output structure, and what not to do. + +Better: + +```md +## Instruction + +Read the related implementation and tests first. Output risks first, then test gaps, then a short summary. Do not request unrelated refactors. +``` + +### Can a Skill authorize tools? + +No. `tool_hints` only suggests tools for the agent to consider. It does not skip approval and does not make unavailable tools available. + +## Next steps + +- Connect external tools: [MCP Tools](./mcp) +- Save long-term preferences: [Daily Use](./daily-use) +- Understand permission boundaries: [Tools & Permissions](./tools-permissions) diff --git a/www/en/guide/tools-permissions.md b/www/en/guide/tools-permissions.md new file mode 100644 index 00000000..19d618e8 --- /dev/null +++ b/www/en/guide/tools-permissions.md @@ -0,0 +1,79 @@ +--- +title: Tools & Permissions +description: What the agent can do, when it needs your approval, and how to choose. +--- + +# Tools & Permissions + +## What the agent can do + +The agent interacts with your project through tools. Read-only operations run automatically; writes and commands need your approval. + +| Capability | Tool | Needs approval | +|---|---|---| +| Read files | `filesystem_read_file` | No | +| Search file contents | `filesystem_grep` | No | +| Search file paths | `filesystem_glob` | No | +| Write files | `filesystem_write_file` | Yes | +| Edit files | `filesystem_edit` | Yes | +| Run commands | `bash` | Depends on risk | +| Fetch web pages | `webfetch` | No | +| Manage task list | `todo_write` | No | +| Save/read/delete memories | `memo_*` | No | +| Launch subagent | `spawn_subagent` | No | + +External tools registered via MCP also appear in the list, namespaced as `mcp..`. See [MCP Tools](./mcp) for setup. + +## Permission approval + +When the agent requests a file write or command execution, the TUI shows a confirmation prompt: + +```text +◆ NEO wants to run: filesystem_write_file + path: src/main.go + content: (428 bytes) + + [Allow] [Ask] [Deny] +``` + +- **Allow**: Approve and remember — future identical operations won't ask again +- **Ask**: Ask every time (default) +- **Deny**: Reject this request + +### How to choose + +| Your situation | Recommendation | +|---|---| +| Continuous refactoring, workspace is safe | Allow — fewer interruptions | +| Reading an unknown repo, observing first | Ask — confirm each time | +| Involves directories you don't want changed or high-risk commands | Deny — block immediately | + +### Full Access mode + +Press `!` to enable Full Access, which skips all permission approvals. + +::: warning +Full Access skips all approvals, including destructive operations. Make sure you understand the risks before enabling it. +::: + +## Command risk classification + +Bash commands aren't all treated the same — NeoCode classifies them by risk: + +| Category | Examples | Handling | +|---|---|---| +| Read-only | `git status`, `git log`, `ls` | Auto-approved | +| Local mutation | `git commit`, `go build` | Needs approval | +| Remote interaction | `git push`, `git fetch` | Needs approval | +| Destructive | `git reset --hard`, `rm` | Needs approval | +| Unknown | Compound commands, parse failures | Needs approval | + +## File operation scope + +All file operations are restricted to the current workspace. Path traversal and symlink escapes are blocked. + +## Next steps + +- Configure tool parameters: [Configuration](./configuration) +- Daily operations: [Daily use](./daily-use) +- Connect external tools: [MCP Tools](./mcp) diff --git a/www/en/guide/troubleshooting.md b/www/en/guide/troubleshooting.md new file mode 100644 index 00000000..ea53a3e8 --- /dev/null +++ b/www/en/guide/troubleshooting.md @@ -0,0 +1,117 @@ +--- +title: Troubleshooting +description: Common NeoCode issues and practical checks for startup, provider auth, gateway, and long-session quality. +--- + +# Troubleshooting + +This page is organized as: symptom -> likely causes -> 3-step checks. + +## 1) `neocode` command not found + +### Symptom + +- Terminal says `command not found` or executable is missing. + +### Likely causes + +- Install script did not complete. +- Binary path is not in `PATH`. + +### 3-step checks + +1. Run `neocode version` and `neocode --help`. +2. If missing, rerun the install steps in [Install and Run](./install). +3. Open a new terminal session and run `neocode version` again. + +## 2) API key is set but auth still fails + +### Symptom + +- Requests fail with `unauthorized` or invalid API key errors. + +### Likely causes + +- Env vars were set in a different shell session. +- Current provider does not match the env var you set. + +### 3-step checks + +1. Use `/provider` to confirm the active provider. +2. Check the env var mapping in [Configuration](./configuration). +3. Restart terminal, then launch `neocode` again. + +## 3) Provider/model switch does not apply + +### Symptom + +- You switched provider/model but behavior still looks old. + +### Likely causes + +- Current session still carries previous context. +- Target model is unavailable under that provider. + +### 3-step checks + +1. Reconfirm with `/provider` and `/model`. +2. Run `/status` to inspect current session state. +3. Start a new session and retry the same prompt. + +## 4) Too many permission prompts + +### Symptom + +- Frequent approval prompts for file edits or commands. + +### Likely causes + +- Current policy is still `Ask`. +- Slight parameter changes make requests non-identical. + +### 3-step checks + +1. Read [Tools and Permissions](./tools-permissions) decision table. +2. Use `Allow` for stable, trusted repetitive actions. +3. Keep `Ask` for unknown repos or risky operations. + +## 5) Gateway connection or URL dispatch fails + +### Symptom + +- Gateway is running but external request flow still fails. + +### Likely causes + +- Gateway not ready or listening mismatch. +- Auth token mismatch. +- Origin/source policy blocks request. + +### 3-step checks + +1. Start `neocode gateway` separately and confirm it is healthy. +2. Verify minimal local path first on `127.0.0.1:8080`. +3. Review limits in [Gateway Usage](/guide/gateway). + +## 6) Long sessions drift or degrade + +### Symptom + +- Answers become repetitive, miss context, or quality drops. + +### Likely causes + +- Prompt budget is too tight for current context. +- Session history contains too much noise. + +### 3-step checks + +1. Trigger manual compaction with `/compact`. +2. Tune `context.budget.*` and `context.compact.*` in config. +3. Start a new session for unrelated tasks. + +## Still blocked? + +- Return to [Getting Started](./) for a minimal path +- Daily operations: [Daily use](./daily-use) +- Gateway issues: [Gateway usage](/guide/gateway) diff --git a/www/en/guide/update.md b/www/en/guide/update.md new file mode 100644 index 00000000..0cd4785d --- /dev/null +++ b/www/en/guide/update.md @@ -0,0 +1,45 @@ +--- +title: Update & Version Check +description: Check your version and upgrade NeoCode. +--- + +# Update & Version Check + +## Automatic update check + +NeoCode silently checks for a newer version in the background at startup (3-second timeout). The update notice is printed after you exit the TUI, so it does not interrupt the session. + +`url-dispatch` and `update` subcommands skip this check. + +## Check version + +```bash +neocode version +``` + +Include pre-release versions: + +```bash +neocode version --prerelease +``` + +When the remote "semantic latest" is not installable on the current platform, `version` will also show the "highest installable version" upgrade hint and flag the remote asset anomaly. + +## Manual upgrade + +```bash +neocode update +``` + +Include pre-release versions: + +```bash +neocode update --prerelease +``` + +## Version info + +- Release builds have a version injected via `ldflags` into `internal/version.Version` +- Local development builds report `dev` + +If you're running from source, seeing `dev` is expected. diff --git a/www/en/index.md b/www/en/index.md index 13c17d44..4e4b9e56 100644 --- a/www/en/index.md +++ b/www/en/index.md @@ -1,58 +1,11 @@ --- -layout: home - -hero: - name: NeoCode - text: An AI coding agent that runs in your terminal - tagline: Install and run locally. No cloud relay. Your code stays on your machine. - image: - src: /brand/neocode-mark.png - alt: NeoCode - actions: - - theme: brand - text: Docs Index - link: /en/docs/ - - theme: alt - text: 中文用户指南 - link: /guide/ - - theme: alt - text: GitHub - link: https://github.com/1024XEngineer/neo-code - -features: - - title: Fully local - details: Model calls go through your local configuration. No third-party relay, no data leaving your machine. - - title: Terminal-native - details: TUI interface. No browser needed. Works directly inside your shell workflow. - - title: Multi-model support - details: Built-in support for OpenAI, Gemini, OpenLL, Qiniu and more. Switch between models without changing code. +layout: page +title: NeoCode +description: A local AI coding agent for your terminal, built around the TUI, Gateway, Runtime, Provider, and Tools path. +aside: false +outline: false +sidebar: false +pageClass: home-page --- -
-

Quick Start

-

Run NeoCode, then choose the guide depth you need

- -
- -
-

Entry Points

-

Where to go next

-
- - English docs index - A short overview with links into the Chinese guide and repository docs. - - - Set credentials - Configure OPENAI_API_KEY, GEMINI_API_KEY, and other provider API keys. - - - Chinese guide - The primary user guide covering install, quick start, configuration, sessions, memo, skills, and Gateway usage. - - - Reference index - Curated links to runtime, gateway, configuration, and skills design notes. - -
-
+ diff --git a/www/guide/configuration.md b/www/guide/configuration.md index 56e381c6..2ad4953f 100644 --- a/www/guide/configuration.md +++ b/www/guide/configuration.md @@ -1,38 +1,73 @@ --- -title: 配置入口 -description: NeoCode 当前真实生效的配置文件、字段范围、Provider 入口与环境变量约束。 +title: 配置指南 +description: 最小配置跑起来，然后按需调整模型、shell、超时和自定义 Provider。 --- -# 配置入口 +# 配置指南 -## 配置文件位置 +## 总原则 -主配置文件： +- `config.yaml` 只保存最小运行时状态 +- provider 元数据来自代码内置定义或 custom provider 文件 +- API Key 只从环境变量读取 +- YAML 采用严格解析，未知字段直接报错 -```text -~/.neocode/config.yaml +这意味着 NeoCode 当前不会： + +- 自动清理旧版 `providers` / `provider_overrides` +- 自动兼容 `workdir`、`default_workdir` 等旧字段 + +## 最小配置 + +如果你只想让 NeoCode 跑起来，这个配置就够了： + +```yaml +selected_provider: openai +current_model: gpt-5.4 +shell: bash ``` -自定义 Provider： +Windows 用户把 `shell` 改成 `powershell`。其他字段都有默认值，不需要一开始就全部填写。 + +配置文件位置：`~/.neocode/config.yaml` + +## 常见任务速查 + +### 切换模型 + +在 TUI 里直接切换，选择会自动保存： ```text -~/.neocode/providers//provider.yaml +/provider # 切换 Provider +/model # 切换模型 ``` -## 配置原则 +如果模型列表为空，检查对应的环境变量是否已设置。 -NeoCode 当前的配置规则很明确： +### 换 Shell -- `config.yaml` 只保存最小运行时状态 -- Provider 元数据来自代码内置定义或 custom provider 文件 -- API Key 只从环境变量读取 -- YAML 采用严格解析，未知字段直接报错 +```yaml +shell: powershell # Windows +shell: bash # macOS / Linux +``` -这意味着 NeoCode 不会把明文密钥写进主配置，也不会悄悄兼容一批旧字段。 +### 调工具超时 -## `config.yaml` 里当前常见字段 +```yaml +tool_timeout_sec: 30 # 默认 20 秒 +``` + +### 会话太长跑偏了 -下面这个示例直接对应当前配置指南中的可写字段： +先试 `/compact`。如果经常跑偏，可以在配置里调大保留的最近消息数： + +```yaml +context: + compact: + manual_keep_recent_messages: 20 # 默认 10 +``` + +## 完整配置示例 ```yaml selected_provider: openai @@ -45,6 +80,7 @@ runtime: assets: max_session_asset_bytes: 20971520 max_session_assets_total_bytes: 20971520 + tools: webfetch: max_response_bytes: 262144 @@ -52,6 +88,7 @@ tools: - text/html - text/plain - application/json + context: compact: manual_strategy: keep_recent @@ -60,36 +97,97 @@ context: read_time_max_message_spans: 24 max_summary_chars: 1200 micro_compact_disabled: false - auto_compact: - enabled: false - input_token_threshold: 0 + budget: + prompt_budget: 0 reserve_tokens: 13000 - fallback_input_token_threshold: 100000 + fallback_prompt_budget: 100000 + max_reactive_compacts: 3 ``` -## 用户最常关心的字段 +## 字段说明 ### 基础字段 -- `selected_provider`：当前选中的 Provider -- `current_model`：当前选中的模型 ID -- `shell`：默认 Shell，Windows 通常是 `powershell` -- `tool_timeout_sec`：工具执行超时秒数 +| 字段 | 说明 | +|------|------| +| `selected_provider` | 当前选中的 provider 名称 | +| `current_model` | 当前选中的模型 ID | +| `shell` | 默认 shell，Windows 默认 `powershell`，其他平台默认 `bash` | +| `tool_timeout_sec` | 工具执行超时（秒） | + +### `context` 字段 + +| 字段 | 说明 | +|------|------| +| `context.compact.manual_strategy` | `/compact` 手动压缩策略，支持 `keep_recent` / `full_replace` | +| `context.compact.manual_keep_recent_messages` | `keep_recent` 策略下保留的最近消息数 | +| `context.compact.micro_compact_retained_tool_spans` | 默认保留原始内容的最近可压缩工具块数量，默认 `6` | +| `context.compact.read_time_max_message_spans` | context 读时保留的 message span 上限 | +| `context.compact.max_summary_chars` | compact summary 最大字符数 | +| `context.compact.micro_compact_disabled` | 是否关闭默认启用的 micro compact | +| `context.budget.prompt_budget` | 显式输入预算；`> 0` 时直接使用，`0` 表示自动推导 | +| `context.budget.reserve_tokens` | 自动推导输入预算时，从模型窗口中预留给输出、tool call、system prompt 的缓冲 | +| `context.budget.fallback_prompt_budget` | 模型窗口不可用或推导失败时使用的保底输入预算 | +| `context.budget.max_reactive_compacts` | 单次 Run 内允许的 reactive compact 最大次数 | + +### `runtime` 字段 + +| 字段 | 说明 | +|------|------| +| `runtime.max_no_progress_streak` | 连续"无进展"轮次提醒阈值，默认 `5` | +| `runtime.max_repeat_cycle_streak` | 连续"重复调用同一工具参数"提醒阈值，默认 `3` | +| `runtime.max_turns` | 单次 Run 的最大推理轮数上限，默认 `40` | +| `runtime.assets.max_session_asset_bytes` | 单个 session asset 最大字节数，默认 20 MiB | +| `runtime.assets.max_session_assets_total_bytes` | 单次请求可携带的 session asset 总字节上限，默认 20 MiB | + +### `verification` 字段 + +| 字段 | 说明 | +|------|------| +| `verification.enabled` | 是否启用验证引擎，默认 `true` | +| `verification.final_intercept` | 是否在任务收尾前拦截并触发验证，默认 `true` | +| `verification.max_no_progress` | 验证无进展时的最大重试次数，默认 `3` | +| `verification.max_retries` | 验证失败后的最大重试次数，默认 `2` | +| `verification.verifiers..enabled` | 是否启用该验证器 | +| `verification.verifiers..required` | 该验证器是否为硬性要求 | +| `verification.verifiers..timeout_sec` | 该验证器的执行超时 | +| `verification.verifiers..fail_closed` | 验证器异常时是否按失败处理 | +| `verification.execution_policy.allowed_commands` | 验证器可执行的命令白名单 | +| `verification.execution_policy.denied_commands` | 验证器禁止执行的命令黑名单 | + +### `tools` 字段 + +| 字段 | 说明 | +|------|------| +| `tools.webfetch.max_response_bytes` | WebFetch 最大响应字节数 | +| `tools.webfetch.supported_content_types` | WebFetch 允许的内容类型 | +| `tools.mcp.servers` | MCP server 列表，见下方 MCP 配置 | + +## 环境变量 + +API Key 只从环境变量读取，不写入配置文件。 -### `context` 相关 +| Provider | 环境变量 | +|---|---| +| OpenAI | `OPENAI_API_KEY` | +| Gemini | `GEMINI_API_KEY` | +| OpenLL | `AI_API_KEY` | +| Qiniu | `QINIU_API_KEY` | +| ModelScope | `MODELSCOPE_API_KEY` | + +```bash +export OPENAI_API_KEY="sk-..." +export GEMINI_API_KEY="AI..." +export MODELSCOPE_API_KEY="ms-..." +``` -- `context.compact.manual_strategy`：`/compact` 的手动压缩策略 -- `context.compact.manual_keep_recent_messages`：保留的最近消息数 -- `context.auto_compact.enabled`：是否启用自动压缩 -- `context.auto_compact.reserve_tokens`：自动阈值推导时的预留 token +## 自定义 Provider -### `runtime` 相关 +如果你用的模型服务不在内置列表里，可以通过配置文件接入。 -- `runtime.max_no_progress_streak`：连续无进展轮次的熔断阈值 -- `runtime.max_repeat_cycle_streak`：重复调用同一工具参数时的熔断阈值 -- `runtime.assets.*`：单个与总 `session_asset` 大小限制 +配置文件位置：`~/.neocode/providers//provider.yaml` -## custom provider 示例 +示例（OpenAI 兼容接口）： ```yaml name: company-gateway @@ -102,35 +200,100 @@ chat_endpoint_path: /chat/completions discovery_endpoint_path: /models ``` -如果你使用 `manual` 模式，需要显式提供 `models` 列表；如果没配，加载会直接报错。 +也可以在 TUI 里用 `/provider add` 交互式添加。 -## 不会写进主配置的内容 +### 手动指定模型列表 -以下内容不允许写入 `config.yaml`： +如果 provider 不支持模型发现（`/models` 接口），使用 `model_source: manual`： -- `providers` -- `provider_overrides` -- `workdir` -- `default_workdir` -- `base_url` -- `api_key_env` -- `models` +```yaml +name: company-gateway +driver: openaicompat +api_key_env: COMPANY_GATEWAY_API_KEY +model_source: manual +base_url: https://llm.example.com/v1 +chat_endpoint_path: /chat/completions +models: + - id: gpt-4o-mini + name: GPT-4o Mini + context_window: 128000 +``` -如果这些字段出现在主配置里，加载会失败，而不是静默迁移。 +### 自定义 Provider 字段说明 -## 环境变量 +| 字段 | 说明 | +|------|------| +| `name` | provider 标识，用于 `selected_provider` | +| `driver` | 驱动类型，目前支持 `openaicompat` | +| `api_key_env` | API Key 的环境变量名 | +| `model_source` | `discover`（自动发现）或 `manual`（手动列表） | +| `base_url` | 服务 base URL | +| `chat_api_mode` | `chat_completions` 或 `responses` | +| `chat_endpoint_path` | 聊天接口路径 | +| `discovery_endpoint_path` | 模型发现接口路径（`discover` 模式） | -常见映射如下： +## MCP 工具 -| Provider | 环境变量 | -| --- | --- | -| `openai` | `OPENAI_API_KEY` | -| `gemini` | `GEMINI_API_KEY` | -| `openll` | `AI_API_KEY` | -| `qiniu` | `QINIU_API_KEY` | +如果你有 MCP server，可以在 `config.yaml` 中通过 `tools.mcp.servers` 注册。当前支持 `stdio` server，工具注册后会以 `mcp..` 命名。 + +```yaml +tools: + mcp: + servers: + - id: docs + enabled: true + source: stdio + version: v1 + stdio: + command: node + args: + - ./mcp-server.js + workdir: ./mcp + start_timeout_sec: 8 + call_timeout_sec: 20 + restart_backoff_sec: 1 + env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +完整字段、暴露策略、验证方法和排障步骤见 [MCP 工具接入](./mcp)。 + +## 不允许写进 config.yaml 的字段 + +以下字段如果出现在主配置文件中，加载会直接报错： + +`providers`、`provider_overrides`、`workdir`、`default_workdir`、`base_url`、`api_key_env`、`models` + +## 常见错误 + +### 旧字段被拒绝 + +如果在 `config.yaml` 中包含 `workdir`、`providers` 等字段，当前版本会报未知字段错误。处理方式是手动删除这些字段。 + +### 旧 `context.auto_compact` 字段 + +如果配置中只存在 `context.auto_compact`，启动时 preflight 会自动迁移为 `context.budget`，并写入 `config.yaml.bak` 备份。如果 `context.auto_compact` 与 `context.budget` 同时存在，启动会直接报错，需要手动合并后再启动。 + +### API Key 未设置 + +```text +config: environment variable OPENAI_API_KEY is empty +``` + +在当前 shell 中设置对应环境变量后再启动 NeoCode。 + +## CLI 运行参数覆盖 + +工作目录不写入 `config.yaml`，只通过启动参数覆盖： + +```bash +neocode --workdir /path/to/workspace +``` -## 继续阅读 +## 下一步 -- 会话工作区与 `/cwd`：看 [工作区与会话](./workspace-session) -- Gateway 配置和安全限制：看 [Gateway 与 URL Dispatch](./gateway) -- 更完整的设计说明：看 [深入阅读](/reference/) +- 想了解日常操作：[日常使用](./daily-use) +- 想了解 Agent 能做什么：[工具与权限](./tools-permissions) +- 遇到问题：[排障与常见问题](./troubleshooting) +- 切换模型：[升级与版本检查](./update) diff --git a/www/guide/daily-use.md b/www/guide/daily-use.md new file mode 100644 index 00000000..308ede5f --- /dev/null +++ b/www/guide/daily-use.md @@ -0,0 +1,83 @@ +--- +title: 日常使用 +description: 会话管理、记忆、Skills 和子代理——你每天都在用的操作。 +--- + +# 日常使用 + +## 会话管理 + +### 切换会话 + +```text +/session # 打开会话选择器，切换到其他会话 +``` + +### 压缩长会话 + +对话太长时，Agent 的回复质量会下降。执行一次压缩可以清理旧上下文： + +```text +/compact +``` + +### 什么时候新建会话，什么时候继续 + +| 场景 | 建议 | +|---|---| +| 刚完成一个功能，要开始不相关的 bug 修复 | 新建会话 | +| 同一仓库内继续完善刚才的功能 | 继续当前会话 | +| 切换到完全不同的项目 | 新建会话 + 切换工作区 | +| 会话已经很长，回复开始跑偏 | 先 `/compact`，不行就新建会话 | + +## 记忆 + +记忆帮你保存跨会话的偏好和项目事实，不用每次重复告诉 Agent。 + +### 常用操作 + +```text +/memo # 查看所有记忆 +/remember 我习惯用 powershell # 保存一条记忆 +/forget powershell # 删除匹配的记忆 +``` + +### 记忆 vs Skills + +- **记忆**：保存事实和偏好，跨会话生效。例如"我习惯用 powershell"、"本项目用 Go 1.25" +- **Skills**：保存工作流提示，当前会话生效。例如"先静态阅读再修改" + +一句话决策：需要跨会话记住 → 用记忆；当前任务需要特殊工作方式 → 用 Skill。 + +## Skills + +Skills 是工作流提示层，影响 Agent 在当前会话中的行为偏好。详细写法和加载规则见 [Skills 使用](./skills)。 + +### 常用操作 + +```text +/skills # 查看当前可用的 Skills +/skill use go-review # 在当前会话启用某个 Skill +/skill off go-review # 停用某个 Skill +/skill active # 查看当前会话已激活的 Skills +``` + +一句话判断：当前任务需要特殊工作方式 → 启用 Skill；需要长期记住事实 → 用记忆；需要真实外部工具 → 用 [MCP](./mcp)。 + +## 子代理 + +Agent 可以启动子代理来并行处理子任务，比如用一个 researcher 搜索信息，用一个 reviewer 审查结果。你不需要手动触发——Agent 会根据任务需要自行决定是否使用子代理。 + +如果你想让 Agent 优先使用子代理，可以在对话中这样说： + +```text +请用 researcher 角色搜索 internal/runtime 下所有与 compact 相关的函数签名 +请用 reviewer 角色审查刚才的修改是否满足测试覆盖率要求 +``` + +## 下一步 + +- 想配置模型和 Provider：[配置指南](./configuration) +- 想了解 Agent 能做什么、权限怎么选：[工具与权限](./tools-permissions) +- 想编写或启用 Skill：[Skills 使用](./skills) +- 遇到问题：[排障与常见问题](./troubleshooting) diff --git a/www/guide/examples.md b/www/guide/examples.md new file mode 100644 index 00000000..b0dcbe69 --- /dev/null +++ b/www/guide/examples.md @@ -0,0 +1,130 @@ +--- +title: 使用示例 +description: 4 个可直接复制的常见场景对话，帮助你快速建立 NeoCode 的使用手感。 +--- + +# 使用示例 + +以下示例全部基于 NeoCode 当前已实现的 TUI、工具和 Gateway 能力，可以直接复制粘贴到会话中执行。 + +--- + +## 场景 1：读懂陌生项目 + +**目标**：刚 clone 一个仓库，想快速了解目录结构和模块职责。 + +**输入**： + +```text +请先阅读当前项目目录结构，并按模块给出职责摘要。如果看到 internal/ 目录，请特别说明各子包的边界。 +``` + +**预期行为**： + +- NeoCode 会调用文件读取工具扫描目录 +- 给出结构化的模块职责摘要 +- 如果目录很深，可能会问你是否继续展开 + +**关键决策点**： + +- 如果它请求读取大量文件，选 **Allow**（只读操作无风险） +- 如果它建议执行 `find` 或 `tree`，选 **Allow**（read_only 分类） + +--- + +## 场景 2：定位并修复一个 bug + +**目标**：运行测试时失败，想定位根因并给出修复方案。 + +**输入（第一步：给上下文）**： + +```text +运行测试时看到以下错误，请定位根因并给出修复方案： +``` + +然后把测试失败日志粘贴进去。 + +**输入（第二步：让它动手改）**： + +```text +请直接修改对应文件修复这个问题，并说明验证步骤。只改一个文件。 +``` + +**预期行为**： + +- 先阅读相关源码和测试文件 +- 定位到具体函数或逻辑错误 +- 给出修复后的代码 diff +- 提示你如何运行测试验证 + +**关键决策点**： + +- 当它请求修改文件时，选 **Ask** 或 **Allow**（local_mutation，可控） +- 当它请求运行测试命令时，选 **Allow**（验证修复的必要步骤） + +--- + +## 场景 3：给函数补测试 + +**目标**：为某个缺少测试的函数生成单元测试。 + +**输入**： + +```text +请为 internal/tools/file.go 中的 ReadFile 函数生成单元测试，覆盖正常路径、文件不存在和权限拒绝三种情况。测试写在 internal/tools/file_test.go 中。 +``` + +**预期行为**： + +- 读取目标函数源码，理解入参和返回值 +- 生成对应的测试用例 +- 写入测试文件后询问是否运行验证 + +**输入（验证步骤）**： + +```text +请运行这个包的测试，如果有失败请分析并修复。 +``` + +**关键决策点**： + +- 文件写入属于 local_mutation，建议选 **Ask**（确认路径和内容正确） +- 运行测试命令属于 read_only / local_mutation，选 **Allow** + +--- + +## 场景 4：添加新功能/接口 + +**目标**：在现有代码中添加一个新接口或功能点。 + +**输入（设计阶段）**： + +```text +我想在 internal/gateway 中添加一个 health check 端点，返回当前 runtime 状态。请给出实现方案，包括需要修改哪些文件。 +``` + +**输入（实现阶段）**： + +```text +请按方案实现，保持与现有代码风格一致。实现完成后运行 go build ./... 验证编译通过。 +``` + +**预期行为**： + +- 分析现有 gateway 路由注册方式 +- 新增 handler 和路由注册 +- 运行构建验证 + +**关键决策点**： + +- 多文件修改时，每次写入都建议 **Ask** 确认 +- 运行 `go build` 属于 read_only（只验证，不改状态），可 **Allow** + +--- + +## 下一步 + +- 想了解权限决策细节：[工具与权限](./tools-permissions) +- 想配置模型和 Provider：[配置指南](./configuration) +- 想了解日常操作：[日常使用](./daily-use) +- 遇到报错：[排障与常见问题](./troubleshooting) diff --git a/www/guide/gateway.md b/www/guide/gateway.md index 1c93f09a..b78e0a5f 100644 --- a/www/guide/gateway.md +++ b/www/guide/gateway.md @@ -10,15 +10,25 @@ description: 介绍 neocode gateway、url-dispatch、网络访问面、鉴权和 最简单的方式： ```bash -go run ./cmd/neocode gateway +neocode gateway ``` 指定网络访问面监听地址： ```bash -go run ./cmd/neocode gateway --http-listen 127.0.0.1:8080 +neocode gateway --http-listen 127.0.0.1:8080 ``` +## 什么时候需要单独启动 Gateway + +| 场景 | 是否需要单独启动 Gateway | +|---|---| +| 普通 TUI 会话（`neocode`） | **不需要** —— TUI 会自动探测并拉起本地 Gateway | +| 外部脚本 / curl 调用 JSON-RPC | **需要** —— 先 `neocode gateway`，再发请求 | +| URL Scheme 派发（`url-dispatch`） | **需要** —— Gateway 必须已在运行 | +| 想看 Gateway 专属日志 | **可以** —— 单独启动方便隔离日志输出 | +| 想修改 `--http-listen` 绑定地址 | **需要** —— 默认只监听 localhost | + ## 当前网络访问面 当前实现里，Gateway 网络访问面提供这些端点： @@ -45,7 +55,7 @@ go run ./cmd/neocode gateway --http-listen 127.0.0.1:8080 当前支持通过 URL Scheme 把请求派发到本地 Gateway： ```bash -go run ./cmd/neocode url-dispatch --url "neocode://review?path=README.md" +neocode url-dispatch --url "neocode://review?path=README.md" ``` 目前的 MVP 限制： @@ -100,4 +110,4 @@ Authorization: Bearer ## 继续阅读 - 想看完整网关设计：见 [Gateway 详细设计](https://github.com/1024XEngineer/neo-code/blob/main/docs/gateway-detailed-design.md) -- 想看普通 CLI 使用路径：回到 [首次上手](./quick-start) +- 想看普通 CLI 使用路径：回到 [安装与首次运行](./install) diff --git a/www/guide/getting-started.md b/www/guide/getting-started.md deleted file mode 100644 index 5099b6d2..00000000 --- a/www/guide/getting-started.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: NeoCode 是什么 -description: NeoCode 的定位、适用场景、主链路和当前真实能力概览。 ---- - -# NeoCode 是什么 - -NeoCode 是一个基于 Go 和 Bubble Tea 的本地 Coding Agent，运行在终端里，围绕 ReAct 风格的执行闭环工作： - -`用户输入 -> Agent 推理 -> 调用工具 -> 获取结果 -> 继续推理 -> UI 展示` - -## 适合谁 - -NeoCode 更适合这些场景： - -- 你希望在本地终端里完成代码阅读、修改、调试和自动化操作，而不是切换多个浏览器标签页。 -- 你希望 Provider 差异收敛在内部层，不把模型厂商细节扩散到运行时和 UI。 -- 你需要会话持久化、上下文压缩、工作区隔离，以及一条可验证的执行链路。 - -## 当前真实能力 - -以当前仓库实现为准，NeoCode 已经具备这些入口： - -- Bubble Tea TUI 交互界面 -- 本地 Gateway 进程与 URL Scheme 派发入口 -- Provider / Model 选择 -- 会话持久化与恢复 -- 上下文压缩与自动压缩配置 -- 记忆查看、写入、删除 -- Skills 发现、激活、停用和会话恢复 - -## 模块怎么分工 - -你不需要先理解所有内部实现，但知道这几个层次会更容易判断问题在哪一层： - -- `internal/tui`：终端界面、Slash 命令和运行状态展示 -- `internal/gateway`：IPC / 网络接入、鉴权、ACL 和流式中继 -- `internal/runtime`：ReAct 主循环、tool result 回灌、停止条件、事件派发 -- `internal/provider`：模型协议差异、请求组装和流式响应解析 -- `internal/tools`：工具契约、参数校验、执行与结果收敛 - -## 接下来读什么 - -- 想先跑起来：看 [安装与运行](./install) -- 想知道第一次怎么提问：看 [首次上手](./quick-start) -- 想理解配置文件和 provider：看 [配置入口](./configuration) diff --git a/www/guide/index.md b/www/guide/index.md index 6db91156..bc19d0c1 100644 --- a/www/guide/index.md +++ b/www/guide/index.md @@ -1,32 +1,48 @@ --- title: 开始使用 -description: NeoCode 用户指南总览，帮助你按安装、首次上手、配置和 Gateway 使用顺序阅读。 +description: NeoCode 用户指南——30 秒判断是否适合你，然后按路径找到你需要的内容。 --- # 开始使用 -这套文档只覆盖 NeoCode 当前代码里已经存在的能力，重点是让你在终端里把主链路跑通： +NeoCode 是一个在终端里运行的本地 AI 编码助手。它不是云端 SaaS，不是浏览器插件——它是一个你可以完全掌控的命令行工具。 -`TUI -> Gateway -> Runtime -> Provider / Tool Manager` +## 30 秒判断是否适合你 -## 先读什么 +| 你的情况 | 是否推荐 | +|---|---| +| 习惯在终端里工作 | ✅ 非常适合 | +| 需要完全本地运行，数据不出本机 | ✅ 非常适合 | +| 想要可扩展的 AI 助手，而不是固定功能的 SaaS | ✅ 非常适合 | +| 只用过 ChatGPT 网页版，不熟悉命令行 | ⚠️ 需要适应终端交互 | +| 需要云端协作、多人实时编辑 | ❌ 不适合 | +| 需要 IDE 内嵌的智能补全和 LSP | ❌ 不适合（NeoCode 是终端工具）| -如果你准备第一次运行 NeoCode，按下面顺序即可： +## 新用户 -1. [NeoCode 是什么](./getting-started) -2. [安装与运行](./install) -3. [首次上手](./quick-start) -4. [配置入口](./configuration) +从零开始，3 分钟跑起来： -如果你已经在使用 CLI，可以直接跳到场景化页面： +1. [安装与首次运行](./install) — 装好、设 Key、启动、第一次对话 +2. [使用示例](./examples) — 4 个可直接复制的场景 +3. [配置指南](./configuration) — 切模型、换 shell、加 Provider -- [工作区与会话](./workspace-session) -- [记忆与 Skills](./memo-skills) -- [Gateway 与 URL Dispatch](./gateway) -- [升级与版本检查](./update) +## 日常使用 -## 文档边界 +已经在用了，查操作和配置： -- 用户指导页优先讲怎么用，不展开所有设计细节。 -- 需要看实现背景时，请到 [深入阅读](/reference/) 查看仓库内设计文档的摘要和跳转入口。 -- 英文页面目前只保留简版入口，不与中文站同步扩写。 +- [日常使用](./daily-use) — 会话管理、记忆、Skills、常用命令 +- [工具与权限](./tools-permissions) — Agent 能做什么、什么时候需要你确认 +- [配置指南](./configuration) — 常见配置任务速查 + +## 扩展能力 + +需要把 NeoCode 接进自己的工作流： + +- [MCP 工具接入](./mcp) — 接入外部工具、控制暴露范围、验证工具可用性 +- [Skills 使用](./skills) — 用 `SKILL.md` 固化工作流提示和任务约束 + +## 遇到问题 + +- [排障与常见问题](./troubleshooting) — 按现象查，3 步排查 +- [Gateway 使用](./gateway) — 什么时候需要单独启动、怎么用 +- [升级与版本检查](./update) — 查版本、升级 diff --git a/www/guide/install.md b/www/guide/install.md index 35999234..542c698e 100644 --- a/www/guide/install.md +++ b/www/guide/install.md @@ -1,99 +1,126 @@ --- -title: 安装与运行 -description: 安装脚本、源码运行、环境要求以及第一次启动前的准备项。 +title: 安装与首次运行 +description: 从安装到第一条对话的完整路径，3 分钟跑起来。 --- -# 安装与运行 +# 安装与首次运行 -## 环境要求 +## 1. 环境要求 -- Go `1.25+` -- 至少一个可用的 Provider API Key，例如 OpenAI、Gemini、OpenLL 或 Qiniu +- 操作系统：macOS、Linux 或 Windows +- 终端环境：系统默认终端、PowerShell 或其他兼容终端 +- 至少一个可用的 API Key（OpenAI、Gemini、OpenLL、Qiniu 或 ModelScope） -## 一键安装 +## 2. 安装 -### macOS / Linux +### 一键安装（推荐） + +macOS / Linux： ```bash curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash ``` -### Windows PowerShell +Windows PowerShell： ```powershell irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex ``` -安装脚本会自动从 GitHub Releases 下载最新稳定版二进制文件： +## 3. 设置 API Key -- macOS / Linux：下载并解压到 `/usr/local/bin/`（可能需要 `sudo` 权限） -- Windows：下载并解压到 `%LOCALAPPDATA%\NeoCode`，同时更新用户 `PATH` +NeoCode 从环境变量读取 API Key，不会写入配置文件。 -安装完成后，在终端直接运行： +macOS / Linux： ```bash -neocode +export OPENAI_API_KEY="your_key_here" ``` -## 从源码运行 +Windows PowerShell： -```bash -git clone https://github.com/1024XEngineer/neo-code.git -cd neo-code -go run ./cmd/neocode +```powershell +$env:OPENAI_API_KEY = "your_key_here" ``` -如果你只想启动 Gateway： +其他 Provider 的环境变量名： + +| Provider | 环境变量 | +|---|---| +| OpenAI | `OPENAI_API_KEY` | +| Gemini | `GEMINI_API_KEY` | +| OpenLL | `AI_API_KEY` | +| Qiniu | `QINIU_API_KEY` | +| ModelScope | `MODELSCOPE_API_KEY` | + +## 4. 启动 ```bash -go run ./cmd/neocode gateway +neocode ``` -指定网络访问面监听地址时，可以显式传入 `--http-listen`： +启动后你会看到 TUI 界面，底部是输入框，直接输入文字即可开始对话。 + +如果想指定工作区： ```bash -go run ./cmd/neocode gateway --http-listen 127.0.0.1:8080 +neocode --workdir /path/to/your/project ``` -## 第一次启动前要准备什么 +## 5. 第一次对话 -NeoCode 不会把 API Key 写进 `config.yaml`，而是直接读取环境变量。 +不确定问什么？试试这两句： -### Shell +```text +请阅读当前项目目录结构，给出模块职责摘要 +``` -```bash -export OPENAI_API_KEY="your_key_here" -export GEMINI_API_KEY="your_key_here" -export AI_API_KEY="your_key_here" -export QINIU_API_KEY="your_key_here" +```text +帮我在 internal/runtime 下定位与 tool result 回灌相关逻辑 ``` -### Windows PowerShell +Agent 会自动调用文件读取和搜索工具来完成任务。当它请求写入文件或执行命令时，TUI 会弹出权限确认——你确认后才执行。 -```powershell -$env:OPENAI_API_KEY = "your_key_here" -$env:GEMINI_API_KEY = "your_key_here" -$env:AI_API_KEY = "your_key_here" -$env:QINIU_API_KEY = "your_key_here" -``` +## 6. 常用命令速查 -## 工作区启动 +进入 TUI 后，输入 `/` 开头的命令可以执行操作： -只影响当前进程、不回写配置文件： +| 命令 | 作用 | +|---|---| +| `/help` | 查看所有命令 | +| `/provider` | 切换 Provider | +| `/provider add` | 添加自定义 Provider | +| `/model` | 切换模型 | +| `/status` | 查看当前状态 | +| `/compact` | 压缩长会话上下文 | +| `/clear` | 清空当前草稿 | +| `/cwd [path]` | 查看/切换工作区 | +| `/session` | 切换会话 | +| `/memo` | 查看记忆索引 | +| `/remember ` | 保存记忆 | +| `/forget ` | 删除记忆 | +| `/skills` | 查看可用 Skills | +| `/exit` | 退出 | -```bash -go run ./cmd/neocode --workdir /path/to/workspace -``` +## 装不上？ -这个参数会影响当前运行使用的工作区根目录，也会影响工具访问范围和 session 隔离。 +看 [排障与常见问题](./troubleshooting) -## Gateway 自动拉起 +## 开发者：从源码构建 + +如果你需要阅读代码、调试功能或参与开发，可以从源码构建运行。需要 Go 1.25+ 环境。 + +```bash +git clone https://github.com/1024XEngineer/neo-code.git +cd neo-code +go build ./... +go run ./cmd/neocode +``` -当前实现里： +源码构建的版本号默认为 `dev`，更多信息见 [升级与版本检查](./update)。 -- `neocode` 默认优先通过本地 Gateway 转发 runtime 请求与事件流 -- 启动时会先探测本地网关 -- 如果本地网关未运行，会自动尝试后台拉起并等待就绪 -- 如果拉起后仍不可达或握手失败，会直接报错退出 +## 下一步 -接下来建议阅读 [首次上手](./quick-start)。 +- 想看更多使用场景：[使用示例](./examples) +- 想切换模型或加自定义 Provider：[配置指南](./configuration) +- 想了解日常操作：[日常使用](./daily-use) diff --git a/www/guide/mcp.md b/www/guide/mcp.md new file mode 100644 index 00000000..944e3f70 --- /dev/null +++ b/www/guide/mcp.md @@ -0,0 +1,204 @@ +--- +title: MCP 工具接入 +description: 把外部 MCP server 接入 NeoCode，并让 Agent 安全地调用这些工具。 +--- + +# MCP 工具接入 + +MCP 适合把你已有的外部能力接进 NeoCode，例如内部文档搜索、Issue 查询、私有平台操作或团队已有的工具服务。 + +在 NeoCode 里，MCP 工具不是特殊通道。它们会进入统一工具注册表，继续遵守工具命名、权限审批和暴露策略。 + +## 什么时候用 MCP + +| 你想做的事 | 建议 | +|---|---| +| 让 Agent 查询公司文档、任务系统或私有平台 | 用 MCP | +| 给 Agent 增加一个真实可调用的外部工具 | 用 MCP | +| 只是让 Agent 按某个流程工作 | 用 [Skills](./skills) | +| 只是保存个人偏好或项目事实 | 用 `/remember` 记忆 | + +## 当前支持范围 + +NeoCode 当前只支持 `stdio` 类型的 MCP server。也就是说，NeoCode 会按配置启动一个本地子进程，通过标准输入输出与它通信。 + +工具注册成功后，工具名会变成： + +```text +mcp.. +``` + +例如 server id 是 `docs`，它提供 `search` 工具，那么 Agent 看到的完整工具名就是 `mcp.docs.search`。 + +## 配置 MCP server + +配置文件位置： + +```text +~/.neocode/config.yaml +``` + +最小示例： + +```yaml +tools: + mcp: + servers: + - id: docs + enabled: true + source: stdio + version: v1 + stdio: + command: node + args: + - ./mcp-server.js + workdir: ./mcp + start_timeout_sec: 8 + call_timeout_sec: 20 + restart_backoff_sec: 1 + env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +### 字段说明 + +| 字段 | 说明 | +|---|---| +| `id` | MCP server 的稳定标识，会出现在 `mcp..` 里 | +| `enabled` | 只有 `true` 的 server 会在启动时注册 | +| `source` | 当前仅支持 `stdio`，不填时也按 `stdio` 处理 | +| `version` | 版本标记，主要用于你自己识别配置 | +| `stdio.command` | 启动命令。server 启用时必填 | +| `stdio.args` | 启动参数列表 | +| `stdio.workdir` | 子进程工作目录，支持相对路径 | +| `stdio.start_timeout_sec` | 启动超时 | +| `stdio.call_timeout_sec` | 单次工具调用超时 | +| `stdio.restart_backoff_sec` | 重启退避时间 | +| `env` | 传给 MCP 子进程的环境变量 | + +::: tip +密钥建议放在系统环境变量里，然后用 `value_env` 引用。不要把 token、API Key 或密码直接写进 `config.yaml`。 +::: + +## 环境变量 + +`env` 每一项必须设置 `name`，并且只能在 `value` 和 `value_env` 里二选一。 + +推荐写法： + +```yaml +env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +这表示 NeoCode 从当前系统环境变量 `MCP_TOKEN` 读取值，再传给 MCP 子进程里的 `MCP_TOKEN`。 + +不推荐写法： + +```yaml +env: + - name: MCP_TOKEN + value: real-token-here +``` + +## 启动行为 + +NeoCode 启动时会： + +1. 读取 `tools.mcp.servers`。 +2. 跳过 `enabled: false` 的 server。 +3. 启动每个启用的 `stdio` server。 +4. 调用一次 `tools/list`，初始化工具快照。 +5. 把工具注册成 `mcp..`。 + +如果某个启用的 server 启动失败、环境变量缺失或 `tools/list` 失败，NeoCode 会直接启动失败。这是有意的：配置写错时尽早暴露，比运行中才发现工具不可用更清楚。 + +## 控制哪些 MCP 工具可见 + +如果你接入的 MCP server 暴露了很多工具，可以用 `exposure` 控制 Agent 能看到哪些工具。 + +```yaml +tools: + mcp: + exposure: + allowlist: + - mcp.docs.* + denylist: + - mcp.docs.delete* + agents: + - agent: default + allowlist: + - mcp.docs.search + servers: + - id: docs + enabled: true + source: stdio + stdio: + command: node + args: + - ./mcp-server.js +``` + +规则建议： + +| 配置 | 作用 | +|---|---| +| `allowlist` | 只允许匹配的 MCP 工具暴露给 Agent | +| `denylist` | 隐藏匹配的 MCP 工具，优先级高于 allowlist | +| `agents` | 按 agent 名称设置可见工具 | + +匹配项可以写完整工具名，也可以写通配符，例如 `mcp.docs.*`。如果只想控制某个 server，也可以写 `mcp.docs`。 + +## 验证是否可用 + +启动 NeoCode 后，先让 Agent 列出工具： + +```text +请先列出你当前可用工具的完整名称。 +``` + +确认列表里有 `mcp.docs.search` 之后，再做一次明确调用： + +```text +请调用 mcp.docs.search，参数 {"query":"hello"}，并返回工具结果。 +``` + +如果工具需要特定参数，以你的 MCP server 的 schema 为准。 + +## 常见问题 + +### `tool not found` + +按顺序检查： + +- `enabled` 是否为 `true` +- `id` 是否写对，工具名是否应该是 `mcp..` +- `stdio.command` 是否在当前环境里可执行 +- `stdio.workdir` 是否指向正确目录 +- `env.value_env` 对应的系统环境变量是否已设置 +- MCP server 是否支持 `tools/list` +- `exposure.allowlist` 或 `exposure.denylist` 是否把工具过滤掉了 + +### 启动时报环境变量为空 + +如果配置了： + +```yaml +env: + - name: MCP_TOKEN + value_env: MCP_TOKEN +``` + +就必须先在启动 NeoCode 的同一个 shell 中设置 `MCP_TOKEN`。 + +### server 能启动，但工具调用失败 + +优先检查 MCP server 自己的日志、工具参数 schema 和 `stdio.call_timeout_sec`。NeoCode 会把调用错误收敛成工具错误返回，但具体业务错误通常来自 MCP server。 + +## 下一步 + +- 想控制 Agent 的工作流：[Skills 使用](./skills) +- 想理解权限审批：[工具与权限](./tools-permissions) +- 想查看完整配置：[配置指南](./configuration) diff --git a/www/guide/memo-skills.md b/www/guide/memo-skills.md deleted file mode 100644 index 322925d5..00000000 --- a/www/guide/memo-skills.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 记忆与 Skills -description: 说明 /memo、/remember、/forget 与 Skills 的发现、激活和会话范围。 ---- - -# 记忆与 Skills - -## 记忆相关命令 - -当前会话里可以直接使用： - -```text -/memo -/remember 这个仓库默认使用 powershell -/forget powershell -``` - -对应含义： - -- `/memo`：查看持久记忆索引 -- `/remember `：写入一条显式记忆 -- `/forget `：按关键词删除匹配记忆 - -这适合保留跨会话的偏好、项目事实或反复重复的上下文前提。 - -## Skills 是什么 - -Skills 是 NeoCode 的“能力提示层”，不是新的执行层。它们影响： - -- Context 注入内容 -- 工具暴露顺序上的提示优先级 - -Skills 不会改变： - -- 工具是否真的可执行 -- 权限 ask / deny / allow 决策 -- MCP 注册与权限链路 - -## Skills 的发现与路径 - -当前本地发现路径为： - -```text -~/.neocode/skills/ -~/.codex/skills/ （当 ~/.neocode/skills/ 不存在时自动回退） -``` - -加载规则包括： - -- 扫描 root 下的子目录 -- 每个 Skill 目录要求存在 `SKILL.md` -- 也支持 root 目录直接放一个 `SKILL.md` - -### 仓库内置 Skills - -NeoCode 仓库本身也维护了一套 Skills，位于： - -```text -.agents/skills/ -``` - -包含三类： - -- `issue-rfc-proposal` — 提案类 Issue（RFC 风格） -- `issue-rfc-architecture` — 架构类 Issue（RFC 风格） -- `issue-rfc-implementation` — 实现类 Issue（执行单风格） - -可以通过 `make` 一键安装到常用 AI 工具目录： - -```bash -make install-skills -``` - -默认会安装到以下位置： - -```text -.codex/skills -.claude/skills -.cursor/skills -.windsurf/skills -``` - -如果需要自定义目标，设置 `SKILL_INSTALL_TARGETS`： - -```bash -SKILL_INSTALL_TARGETS=".codex/skills:.claude/skills" make install-skills -``` - -## 会话内 Skills 命令 - -```text -/skills -/skill use -/skill off -/skill active -``` - -含义如下： - -- `/skills`：查看当前工作区 / 会话可用的 Skills -- `/skill use `：激活某个 Skill -- `/skill off `：停用某个 Skill -- `/skill active`：查看当前会话已激活的 Skills - -Skill 激活状态会跟随会话恢复；如果 registry 中缺失，对应 Skill 会被标记为 missing 并发出事件。 - -## Skill 文件结构 - -一个典型的 `SKILL.md` 可以长这样： - -```md ---- -id: go-review -name: Go Review -description: Go 代码审查助手 -version: v1 -scope: session -source: local -tool_hints: - - filesystem_read_file - - filesystem_grep ---- - -## Instruction -优先做静态阅读，再给出可执行修改建议。 -``` - -## 使用建议 - -- 记忆适合沉淀“事实”和“偏好” -- Skill 适合沉淀“工作流提示”和“工具偏好” -- 两者都不应该替代真实工具调用和权限判断 - -如果你想了解它们在实现中的边界，可以继续看 [深入阅读](/reference/)。 diff --git a/www/guide/quick-start.md b/www/guide/quick-start.md deleted file mode 100644 index 8a234839..00000000 --- a/www/guide/quick-start.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 首次上手 -description: 第一次使用 NeoCode 时最常见的提问方式、Slash 命令和会话入口。 ---- - -# 首次上手 - -## 最快的起步方式 - -完成安装并配置好环境变量后，直接启动： - -```bash -go run ./cmd/neocode -``` - -第一次进入会话时，你可以直接输入自然语言任务，例如： - -```text -请先阅读当前项目目录结构并给出模块职责摘要 -帮我在 internal/runtime 下定位与 tool result 回灌相关逻辑 -``` - -## 常用 Slash 命令 - -以下命令来自当前 TUI 实现，适合第一次上手时直接记住： - -| 命令 | 作用 | -| --- | --- | -| `/help` | 查看 Slash 命令帮助 | -| `/clear` | 清空当前草稿会话展示 | -| `/compact` | 压缩当前会话上下文 | -| `/provider` | 打开 Provider 选择器 | -| `/provider add` | 添加自定义 Provider | -| `/model` | 打开 Model 选择器 | -| `/session` | 切换到其他会话 | -| `/cwd [path]` | 查看或设置当前会话工作区 | -| `/memo` | 查看持久记忆索引 | -| `/remember ` | 写入持久记忆 | -| `/forget ` | 删除匹配关键词的记忆 | -| `/skills` | 查看当前可用 Skills | -| `/skill use ` | 激活某个 Skill | -| `/skill off ` | 停用某个 Skill | -| `/skill active` | 查看当前会话已激活的 Skills | -| `/exit` | 退出 NeoCode | - -## Provider 和 Model - -当前 README 与配置文档里明确列出的内置 Provider 包括： - -- `openai` -- `gemini` -- `openll` -- `qiniu` - -你可以通过交互入口切换： - -- `/provider` -- `/model` - -也可以在配置文件中保存上一次的选择状态，详细见 [配置入口](./configuration)。 - -## 本地命令执行 - -如果你需要在当前工作区里直接运行一个本地命令，可以使用： - -```text -& git status -``` - -这适合把终端里的简单检查与会话任务放在同一个上下文里处理。 - -## 什么时候继续往下看 - -- 想了解配置文件和自定义 Provider：看 [配置入口](./configuration) -- 想理解工作区、会话切换和压缩：看 [工作区与会话](./workspace-session) -- 想启用记忆和 Skills：看 [记忆与 Skills](./memo-skills) -- 想手动升级或了解静默版本检测：看 [升级与版本检查](./update) diff --git a/www/guide/skills.md b/www/guide/skills.md new file mode 100644 index 00000000..9254160a --- /dev/null +++ b/www/guide/skills.md @@ -0,0 +1,176 @@ +--- +title: Skills 使用 +description: 用 SKILL.md 固化工作流提示，让 Agent 在当前会话中按指定方式工作。 +--- + +# Skills 使用 + +Skills 是 NeoCode 的工作流提示层。它把一段可复用的任务说明、参考资料和工具偏好注入到当前会话上下文里，帮助 Agent 按你指定的方式工作。 + +Skills 不会绕过权限，不会注册新工具，也不会替代 MCP。它只是告诉 Agent：“这类任务应该这样做”。 + +## 什么时候用 Skills + +| 你想做的事 | 建议 | +|---|---| +| 让 Agent 每次代码审查都按固定清单检查 | 用 Skill | +| 让 Agent 做某类任务前先读指定文档 | 用 Skill | +| 让 Agent 优先考虑某些工具或流程 | 用 Skill | +| 接入一个真实可调用的外部服务 | 用 [MCP](./mcp) | +| 保存长期个人偏好或项目事实 | 用 `/remember` 记忆 | + +## Skills 放在哪里 + +本地 Skills 默认放在： + +```text +~/.neocode/skills/ +``` + +一个 Skill 可以是一个目录： + +```text +~/.neocode/skills/go-review/SKILL.md +``` + +也可以直接是根目录下的 `SKILL.md`。更推荐用子目录，这样每个 Skill 都有清晰的名称和边界。 + +## 创建一个 Skill + +示例：`~/.neocode/skills/go-review/SKILL.md` + +```md +--- +id: go-review +name: Go Review +description: Review Go changes for correctness, boundaries, and tests. +version: v1 +scope: explicit +tool_hints: + - filesystem_grep + - bash +--- + +# Go Review + +## Instruction + +先阅读改动相关的 Go 文件和测试，再给出审查结论。优先关注行为回归、模块边界、错误处理和测试缺口。不要因为风格偏好要求大改。 + +## References + +- title: Repo rules + path: AGENTS.md + summary: Follow repository boundaries and testing expectations. + +## Examples + +- 用户要求 review 时，先列出高风险问题，再给简短总结。 + +## ToolHints + +- filesystem_grep +- bash +``` + +### 常用字段 + +| 字段 | 说明 | +|---|---| +| `id` | Skill 标识。没写时会从目录名推导 | +| `name` | 展示名称。没写时会尝试使用第一个一级标题 | +| `description` | 简短说明，用于列表中识别用途 | +| `version` | 版本标记。没写时默认为 `v1` | +| `scope` | 作用范围。没写时默认为 `explicit` | +| `tool_hints` | 工具偏好提示，不等于权限授权 | + +### 常用段落 + +| 段落 | 作用 | +|---|---| +| `Instruction` | 核心工作流说明，最重要 | +| `References` | 参考资料摘要 | +| `Examples` | 示例任务或示例行为 | +| `ToolHints` | 建议优先考虑的工具 | + +如果没有写 `Instruction` 段落，NeoCode 会把正文内容当作 instruction 使用。 + +## 启用和停用 + +在 TUI 里使用： + +```text +/skills # 查看当前可用的 Skills +/skill use go-review # 在当前会话启用某个 Skill +/skill off go-review # 停用某个 Skill +/skill active # 查看当前会话已激活的 Skills +``` + +注意： + +- `/skill use ` 只影响当前会话。 +- 已激活的 Skills 会随 session 记录恢复。 +- Skills 管理需要当前有活动 session；如果刚启动还没有会话，先发送一条消息或切换 session。 +- Gateway 模式暂不支持 Skills 管理，请切换到 local runtime 使用这些命令。 + +## Agent 会看到什么 + +每轮构建上下文时，NeoCode 会把当前激活的 Skills 渲染到 `Skills` section。内容包括： + +- Skill 名称和 ID +- `Instruction` +- 最多 3 条 `ToolHints` +- 最多 3 条 `References` +- 最多 2 条 `Examples` + +这些内容会影响 Agent 的计划和回复，但不会改变工具权限。比如 Skill 里写了“优先使用 bash”，遇到高风险命令时仍然需要正常审批。 + +## Skills vs 记忆 vs MCP + +| 能力 | 解决什么问题 | 是否执行工具 | 是否跨会话自动生效 | +|---|---|---|---| +| Skills | 当前任务的工作流和任务约束 | 否 | 否，需要在会话中启用 | +| 记忆 | 长期偏好和项目事实 | 否 | 是 | +| MCP | 外部可调用工具 | 是 | 取决于配置是否启用 | + +一句话判断： + +- 想改变 Agent 做事方式：用 Skills。 +- 想让 Agent 记住事实：用记忆。 +- 想增加真实工具能力：用 MCP。 + +## 常见问题 + +### `/skills` 看不到我的 Skill + +检查： + +- 文件是否位于 `~/.neocode/skills/` +- 文件名是否为 `SKILL.md` +- Skill 文件大小是否过大 +- frontmatter 是否是合法 YAML +- `id` 是否重复 + +NeoCode 会跳过无效 Skill，但不会因为一个 Skill 写错就阻止其他 Skills 加载。 + +### Skill 启用了但效果不明显 + +优先把 `Instruction` 写得更具体。不要只写“请更认真”，而要写清楚检查顺序、输出结构和不该做什么。 + +更好的写法： + +```md +## Instruction + +先阅读相关实现和测试，再审查改动。输出时先列风险，再列测试缺口，最后给简短总结。不要要求无关重构。 +``` + +### Skill 能不能授权工具 + +不能。Skill 里的 `tool_hints` 只是提示 Agent 优先考虑某些工具，不会跳过权限审批，也不会让不存在的工具变得可用。 + +## 下一步 + +- 想接入外部工具：[MCP 工具接入](./mcp) +- 想保存长期偏好：[日常使用](./daily-use) +- 想理解权限边界：[工具与权限](./tools-permissions) diff --git a/www/guide/tools-permissions.md b/www/guide/tools-permissions.md new file mode 100644 index 00000000..295ddeaf --- /dev/null +++ b/www/guide/tools-permissions.md @@ -0,0 +1,79 @@ +--- +title: 工具与权限 +description: Agent 能做什么，什么时候需要你确认，怎么选。 +--- + +# 工具与权限 + +## Agent 能做什么 + +Agent 通过工具与你的项目交互。只读操作自动执行，写入和命令操作需要你确认。 + +| 能力 | 工具 | 需要你确认 | +|---|---|---| +| 读取文件 | `filesystem_read_file` | 否 | +| 搜索文件内容 | `filesystem_grep` | 否 | +| 搜索文件路径 | `filesystem_glob` | 否 | +| 写入文件 | `filesystem_write_file` | 是 | +| 编辑文件 | `filesystem_edit` | 是 | +| 执行命令 | `bash` | 视风险而定 | +| 抓取网页 | `webfetch` | 否 | +| 管理任务列表 | `todo_write` | 否 | +| 保存/读取/删除记忆 | `memo_*` | 否 | +| 启动子代理 | `spawn_subagent` | 否 | + +通过 MCP 配置注册的外部工具也会出现在列表中，命名空间为 `mcp..`。接入方式见 [MCP 工具接入](./mcp)。 + +## 权限审批 + +当 Agent 请求写入文件或执行命令时，TUI 会弹出确认界面： + +```text +◆ NEO wants to run: filesystem_write_file + path: src/main.go + content: (428 bytes) + + [Allow] [Ask] [Deny] +``` + +- **Allow**：允许执行，且记住决策——后续相同操作不再询问 +- **Ask**：每次都询问（默认） +- **Deny**：拒绝本次执行 + +### 怎么选 + +| 你的场景 | 建议 | +|---|---| +| 连续重构，已确认安全 | Allow — 减少打断 | +| 阅读未知仓库，先观察 | Ask — 每次确认 | +| 涉及不想改的目录或高风险命令 | Deny — 直接阻断 | + +### Full Access 模式 + +按 `!` 键可以启用 Full Access，跳过所有权限审批。 + +::: warning +Full Access 会跳过所有审批，包括破坏性操作。确认你了解风险后再启用。 +::: + +## 命令风险分类 + +Bash 命令不是一律审批——NeoCode 会按风险分类处理： + +| 分类 | 示例 | 处理方式 | +|---|---|---| +| 只读 | `git status`、`git log`、`ls` | 自动放行 | +| 本地变更 | `git commit`、`go build` | 需要确认 | +| 远端交互 | `git push`、`git fetch` | 需要确认 | +| 破坏性 | `git reset --hard`、`rm` | 需要确认 | +| 无法判断 | 复合命令、解析失败 | 需要确认 | + +## 文件操作范围 + +所有文件操作限制在当前工作区内，路径穿越和符号链接逃逸会被拦截。 + +## 下一步 + +- 想配置工具参数：[配置指南](./configuration) +- 想了解日常操作：[日常使用](./daily-use) +- 想接入外部工具：[MCP 工具接入](./mcp) diff --git a/www/guide/troubleshooting.md b/www/guide/troubleshooting.md new file mode 100644 index 00000000..806fb4f8 --- /dev/null +++ b/www/guide/troubleshooting.md @@ -0,0 +1,119 @@ +--- +title: 排障与常见问题 +description: NeoCode 首次使用和日常使用中的高频问题排查清单，按现象给出可执行的定位步骤。 +--- + +# 排障与常见问题 + +这页按“现象 -> 可能原因 -> 3 步排查”组织，优先解决首次使用中最常见的问题。 + +## 1) 启动失败：`neocode` 命令不存在 + +### 现象 + +- 终端提示 `command not found` / `neocode 不是内部或外部命令` + +### 可能原因 + +- 安装脚本没有执行完成 +- 二进制目录没有加入 PATH + +### 3 步排查 + +1. 运行 `neocode version` 和 `neocode --help`。 +2. 如果命令不存在，重新执行安装脚本（见 [安装与运行](./install)）。 +3. 重开一个终端会话后再次执行 `neocode version`。 + +## 2) API Key 明明设置了，仍报认证失败 + +### 现象 + +- 启动后请求模型时报 `unauthorized`、`invalid api key` 或 provider 认证错误 + +### 可能原因 + +- 只在一个终端会话里设置了环境变量，当前会话没有继承 +- `selected_provider` 对应的环境变量和你实际设置的不一致 + +### 3 步排查 + +1. 用 `/provider` 确认当前选中的 Provider。 +2. 对照 [配置指南](./configuration) 的映射表，确认对应环境变量已设置。 +3. 关闭并重新打开终端后再次启动 `neocode`。 + +## 3) 切换 Provider / Model 后不生效 + +### 现象 + +- 你已经切换了 Provider 或 Model，但请求仍像在走旧配置 + +### 可能原因 + +- 当前会话还在使用旧上下文状态 +- 新模型在当前 Provider 下不可用 + +### 3 步排查 + +1. 在会话中执行 `/provider` 和 `/model` 再确认一次当前选择。 +2. 执行 `/status` 查看当前会话状态。 +3. 新建会话后重试同一个请求，确认是否恢复正常。 + +## 4) 工具调用频繁被拦截或反复弹审批 + +### 现象 + +- 写文件或执行命令时经常弹出权限确认 +- 你以为已允许，但还在重复询问 + +### 可能原因 + +- 当前决策是 `Ask` +- 工具参数变化导致被视为不同请求 + +### 3 步排查 + +1. 阅读 [工具与权限](./tools-permissions) 中 `Allow / Ask / Deny` 决策表。 +2. 对稳定、可控的操作选择 `Allow`，减少重复确认。 +3. 若任务风险高或仓库未知，保持 `Ask` 并逐次确认。 + +## 5) Gateway 连不上 / URL Dispatch 失败 + +### 现象 + +- `neocode gateway` 启动后外部请求仍失败 +- `url-dispatch` 返回连接错误或鉴权错误 + +### 可能原因 + +- Gateway 未就绪或监听地址不匹配 +- 本地鉴权 token 不一致 +- 请求来源不在允许范围 + +### 3 步排查 + +1. 单独启动 `neocode gateway`，确认进程已正常运行。 +2. 使用默认本地监听地址 `127.0.0.1:8080` 先验证最小链路。 +3. 对照 [Gateway 与 URL Dispatch](./gateway) 检查鉴权与来源限制。 + +## 6) 对话越长越“跑偏”或质量下降 + +### 现象 + +- 回答开始重复、遗漏上下文、执行效率下降 + +### 可能原因 + +- 会话上下文过长，输入预算不足 +- 历史消息噪声过多 + +### 3 步排查 + +1. 先手动执行一次 `/compact`。 +2. 在配置中检查 `context.compact.*`（见 [配置指南](./configuration)）。 +3. 对于新任务，建议新建会话，避免历史噪声干扰。 + +## 仍未解决怎么办 + +- 回到 [开始使用](./) 重新走最小路径 +- Gateway 问题：看 [Gateway 使用](./gateway) +- 日常操作问题：看 [日常使用](./daily-use) diff --git a/www/guide/workspace-session.md b/www/guide/workspace-session.md deleted file mode 100644 index ef92f777..00000000 --- a/www/guide/workspace-session.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: 工作区与会话 -description: 解释 --workdir、/cwd、/session、/compact 以及会话持久化的使用边界。 ---- - -# 工作区与会话 - -## `--workdir` 和 `/cwd` 的区别 - -NeoCode 当前同时提供启动参数和会话内命令： - -- `--workdir`：只影响当前进程启动时的工作区，不回写配置文件 -- `/cwd [path]`：在当前会话里查看或切换工作区 - -启动参数示例： - -```bash -go run ./cmd/neocode --workdir /path/to/workspace -``` - -会话内命令示例： - -```text -/cwd -/cwd /path/to/workspace -``` - -## 会话切换 - -当前 TUI 中存在 `/session` 命令，用来切换到其他会话。配合会话持久化，适合把不同任务拆开管理，而不是把所有内容堆在一个长会话里。 - -## 上下文压缩 - -当会话越来越长时，可以使用： - -```text -/compact -``` - -当前实现支持： - -- 手动压缩策略 -- 自动压缩相关阈值配置 -- 读时 micro compact - -压缩策略的目标是保留继续完成任务所需的上下文，而不是让 UI 自己保存散落状态。 - -## 会话为什么重要 - -NeoCode 把这些状态优先放在 Runtime / Session 层，而不是散在 UI： - -- 消息历史 -- 工具调用记录 -- token 累积 -- 激活的 Skills -- 记忆提取与回放相关内容 - -这也是为什么工作区、会话和压缩是一起看的。 - -## 何时使用多个会话 - -建议切分会话的情况： - -- 你在不同仓库或不同工作区之间来回切换 -- 一个会话已经积累了很多无关上下文 -- 你想让某个任务的记忆、压缩和工具轨迹保持独立 - -## 继续阅读 - -- 记忆和 Skills：看 [记忆与 Skills](./memo-skills) -- 配置压缩阈值：看 [配置入口](./configuration) diff --git a/www/index.md b/www/index.md index 9032caf9..a79d1d65 100644 --- a/www/index.md +++ b/www/index.md @@ -1,70 +1,11 @@ --- -layout: home - -hero: - name: NeoCode - text: 在终端里运行的 AI 编码助手 - tagline: 安装即用，无需云端，代码留在本地。 - image: - src: /brand/neocode-mark.png - alt: NeoCode - actions: - - theme: brand - text: 开始使用 - link: /guide/ - - theme: alt - text: 首次上手 - link: /guide/quick-start - - theme: alt - text: GitHub - link: https://github.com/1024XEngineer/neo-code - -features: - - title: 完全本地 - details: 模型调用走本地配置，不经过任何第三方中转服务器，数据留在你的机器上。 - - title: 终端原生 - details: TUI 界面，无需浏览器，和你的 shell 工作流无缝集成，直接在终端中对话和操作。 - - title: 多模型支持 - details: 内置 OpenAI、Gemini、OpenLL、Qiniu 等多个模型服务，通过配置随时切换，无需改代码。 +layout: page +title: NeoCode +description: 终端里的本地 AI 编码助手，围绕 TUI、Gateway、Runtime、Provider 和 Tools 主链路构建。 +aside: false +outline: false +sidebar: false +pageClass: home-page --- -
-

Quick Start

-

先安装，再开始用

- -
- -
-

Guide

-

常用入口

-
- - 安装与运行 - 安装脚本、源码运行和环境要求。 - - - 首次上手 - 第一次提问、常用 Slash 命令和 Provider / Model 切换。 - - - 配置环境变量 - 设置 OPENAI_API_KEY、GEMINI_API_KEY 等 API Key 环境变量。 - - - 配置 - config.yaml、custom provider 和环境变量。 - - - 工作区与会话 - --workdir、/cwd、会话切换和上下文压缩。 - - - 记忆与 Skills - /memo、/remember、/forget 和 Skills。 - - - Gateway 使用 - neocode gateway、url-dispatch 和网络访问面。 - -
-
+ diff --git a/www/reference/index.md b/www/reference/index.md index 2fae0c3e..d43c0e51 100644 --- a/www/reference/index.md +++ b/www/reference/index.md @@ -7,6 +7,8 @@ description: 汇总 NeoCode 仓库中已有设计文档，并说明它们分别 这一页不复制仓库里所有设计文档，而是告诉你什么时候该看哪一份原始文档。 +如果你只是想把 NeoCode 跑起来并稳定使用，请先看 [开始使用](/guide/)；只有当你要改实现、查边界或做架构决策时，再回到这里。 + ## 运行时与上下文 - [Runtime / Provider 事件流](https://github.com/1024XEngineer/neo-code/blob/main/docs/runtime-provider-event-flow.md) From 9545caaee13442d412b0fb742c2d541b283ce57a Mon Sep 17 00:00:00 2001 From: xgopilot Date: Sun, 26 Apr 2026 08:27:22 +0000 Subject: [PATCH 2/3] docs(www): remove stale /status command docs Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Yumiue <188874804+Yumiue@users.noreply.github.com> --- www/en/guide/install.md | 18 +++++++++--------- www/en/guide/troubleshooting.md | 16 ++++++++-------- www/guide/install.md | 17 ++++++++--------- www/guide/troubleshooting.md | 12 ++++++------ 4 files changed, 31 insertions(+), 32 deletions(-) diff --git a/www/en/guide/install.md b/www/en/guide/install.md index 249dc281..c9ea34bb 100644 --- a/www/en/guide/install.md +++ b/www/en/guide/install.md @@ -36,7 +36,7 @@ go run ./cmd/neocode ## 3. Set API key -NeoCode reads API keys from environment variables — they are never written to config files. +NeoCode reads API keys from environment variables and never writes them to config files. macOS / Linux: @@ -66,9 +66,8 @@ Other providers: neocode ``` -You'll see the TUI interface. Type at the bottom to start a conversation. - -To specify a workspace: +You will enter the TUI. Type in the input box at the bottom to start a conversation. +To open a specific workspace: ```bash neocode --workdir /path/to/your/project @@ -76,7 +75,7 @@ neocode --workdir /path/to/your/project ## 5. First conversation -Not sure what to ask? Try these: +Need a starting prompt? Try: ```text Read the current project directory structure and give a module summary @@ -86,19 +85,20 @@ Read the current project directory structure and give a module summary Find the tool result injection logic in internal/runtime ``` -The agent will automatically use file reading and search tools. When it requests file writes or command execution, the TUI will prompt for your approval. +The agent will use file reading and search tools automatically. When it needs to write files or run commands, the TUI will ask for approval. -## 6. Command cheat sheet +## 6. Common `/` commands -Inside the TUI, type `/` commands to perform operations: +Inside the TUI, use `/` commands for common actions: | Command | Action | |---|---| | `/help` | Show all commands | | `/provider` | Switch provider | +| `/provider add` | Add a custom provider | | `/model` | Switch model | -| `/status` | Show current status | | `/compact` | Compress long session context | +| `/clear` | Clear the current draft | | `/cwd [path]` | View/switch workspace | | `/session` | Switch session | | `/memo` | View memory index | diff --git a/www/en/guide/troubleshooting.md b/www/en/guide/troubleshooting.md index ea53a3e8..97ae07f5 100644 --- a/www/en/guide/troubleshooting.md +++ b/www/en/guide/troubleshooting.md @@ -5,7 +5,7 @@ description: Common NeoCode issues and practical checks for startup, provider au # Troubleshooting -This page is organized as: symptom -> likely causes -> 3-step checks. +This page follows: symptom -> likely causes -> 3-step checks. ## 1) `neocode` command not found @@ -41,11 +41,11 @@ This page is organized as: symptom -> likely causes -> 3-step checks. 2. Check the env var mapping in [Configuration](./configuration). 3. Restart terminal, then launch `neocode` again. -## 3) Provider/model switch does not apply +## 3) Provider or model switch does not apply ### Symptom -- You switched provider/model but behavior still looks old. +- You switched provider or model, but behavior still looks unchanged. ### Likely causes @@ -54,8 +54,8 @@ This page is organized as: symptom -> likely causes -> 3-step checks. ### 3-step checks -1. Reconfirm with `/provider` and `/model`. -2. Run `/status` to inspect current session state. +1. Reconfirm the current selection with `/provider` and `/model`. +2. Run `/compact` to reduce stale context impact in the current session. 3. Start a new session and retry the same prompt. ## 4) Too many permission prompts @@ -89,9 +89,9 @@ This page is organized as: symptom -> likely causes -> 3-step checks. ### 3-step checks -1. Start `neocode gateway` separately and confirm it is healthy. +1. Start `neocode gateway` separately and confirm the process is running. 2. Verify minimal local path first on `127.0.0.1:8080`. -3. Review limits in [Gateway Usage](/guide/gateway). +3. Review auth and origin limits in [Gateway usage](./gateway). ## 6) Long sessions drift or degrade @@ -114,4 +114,4 @@ This page is organized as: symptom -> likely causes -> 3-step checks. - Return to [Getting Started](./) for a minimal path - Daily operations: [Daily use](./daily-use) -- Gateway issues: [Gateway usage](/guide/gateway) +- Gateway issues: [Gateway usage](./gateway) diff --git a/www/guide/install.md b/www/guide/install.md index 542c698e..a5ac2276 100644 --- a/www/guide/install.md +++ b/www/guide/install.md @@ -29,7 +29,7 @@ irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/instal ## 3. 设置 API Key -NeoCode 从环境变量读取 API Key，不会写入配置文件。 +NeoCode 只从环境变量读取 API Key，不会写入配置文件。 macOS / Linux： @@ -61,7 +61,7 @@ neocode 启动后你会看到 TUI 界面，底部是输入框，直接输入文字即可开始对话。 -如果想指定工作区： +如果要直接打开指定工作区： ```bash neocode --workdir /path/to/your/project @@ -69,7 +69,7 @@ neocode --workdir /path/to/your/project ## 5. 第一次对话 -不确定问什么？试试这两句： +不知道从哪里开始？可以先试这两句： ```text 请阅读当前项目目录结构，给出模块职责摘要 @@ -79,11 +79,11 @@ neocode --workdir /path/to/your/project 帮我在 internal/runtime 下定位与 tool result 回灌相关逻辑 ``` -Agent 会自动调用文件读取和搜索工具来完成任务。当它请求写入文件或执行命令时，TUI 会弹出权限确认——你确认后才执行。 +Agent 会自动调用文件读取和搜索工具。当它需要写入文件或执行命令时，TUI 会先弹出权限确认。 -## 6. 常用命令速查 +## 6. 常用 `/` 命令 -进入 TUI 后，输入 `/` 开头的命令可以执行操作： +进入 TUI 后，可用 `/` 命令执行常见操作： | 命令 | 作用 | |---|---| @@ -91,7 +91,6 @@ Agent 会自动调用文件读取和搜索工具来完成任务。当它请求 | `/provider` | 切换 Provider | | `/provider add` | 添加自定义 Provider | | `/model` | 切换模型 | -| `/status` | 查看当前状态 | | `/compact` | 压缩长会话上下文 | | `/clear` | 清空当前草稿 | | `/cwd [path]` | 查看/切换工作区 | @@ -102,13 +101,13 @@ Agent 会自动调用文件读取和搜索工具来完成任务。当它请求 | `/skills` | 查看可用 Skills | | `/exit` | 退出 | -## 装不上？ +## 安装有问题？ 看 [排障与常见问题](./troubleshooting) ## 开发者：从源码构建 -如果你需要阅读代码、调试功能或参与开发，可以从源码构建运行。需要 Go 1.25+ 环境。 +如果你要阅读代码、调试功能或参与开发，可以从源码构建运行。需要 Go 1.25+ 环境。 ```bash git clone https://github.com/1024XEngineer/neo-code.git diff --git a/www/guide/troubleshooting.md b/www/guide/troubleshooting.md index 806fb4f8..09c18714 100644 --- a/www/guide/troubleshooting.md +++ b/www/guide/troubleshooting.md @@ -5,7 +5,7 @@ description: NeoCode 首次使用和日常使用中的高频问题排查清单 # 排障与常见问题 -这页按“现象 -> 可能原因 -> 3 步排查”组织，优先解决首次使用中最常见的问题。 +这页按“现象 -> 可能原因 -> 3 步排查”组织，优先覆盖首次使用和日常使用中最常见的问题。 ## 1) 启动失败：`neocode` 命令不存在 @@ -41,11 +41,11 @@ description: NeoCode 首次使用和日常使用中的高频问题排查清单 2. 对照 [配置指南](./configuration) 的映射表，确认对应环境变量已设置。 3. 关闭并重新打开终端后再次启动 `neocode`。 -## 3) 切换 Provider / Model 后不生效 +## 3) 切换 Provider 或 Model 后不生效 ### 现象 -- 你已经切换了 Provider 或 Model，但请求仍像在走旧配置 +- 你已经切换了 Provider 或 Model，但行为看起来仍在使用旧配置 ### 可能原因 @@ -54,8 +54,8 @@ description: NeoCode 首次使用和日常使用中的高频问题排查清单 ### 3 步排查 -1. 在会话中执行 `/provider` 和 `/model` 再确认一次当前选择。 -2. 执行 `/status` 查看当前会话状态。 +1. 在会话中执行 `/provider` 和 `/model`，再确认一次当前选择。 +2. 执行 `/compact`，减少旧上下文对当前会话的影响。 3. 新建会话后重试同一个请求，确认是否恢复正常。 ## 4) 工具调用频繁被拦截或反复弹审批 @@ -91,7 +91,7 @@ description: NeoCode 首次使用和日常使用中的高频问题排查清单 ### 3 步排查 -1. 单独启动 `neocode gateway`，确认进程已正常运行。 +1. 单独启动 `neocode gateway`，确认进程已经正常运行。 2. 使用默认本地监听地址 `127.0.0.1:8080` 先验证最小链路。 3. 对照 [Gateway 与 URL Dispatch](./gateway) 检查鉴权与来源限制。 From f939b4f52c6b1213ce0068930f2b6ff798e9e14f Mon Sep 17 00:00:00 2001 From: Yumiue <229866007@qq.com> Date: Sun, 26 Apr 2026 17:27:53 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(www):=20=E4=BF=AE=E5=A4=8D=E8=8B=B1?= =?UTF-8?q?=E6=96=87=E6=8E=92=E9=9A=9C=E9=A1=B5=20Gateway=20=E9=93=BE?= =?UTF-8?q?=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- www/en/guide/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/www/en/guide/troubleshooting.md b/www/en/guide/troubleshooting.md index 97ae07f5..0aa2cedd 100644 --- a/www/en/guide/troubleshooting.md +++ b/www/en/guide/troubleshooting.md @@ -91,7 +91,7 @@ This page follows: symptom -> likely causes -> 3-step checks. 1. Start `neocode gateway` separately and confirm the process is running. 2. Verify minimal local path first on `127.0.0.1:8080`. -3. Review auth and origin limits in [Gateway usage](./gateway). +3. Review auth and origin limits in [Gateway usage](/guide/gateway). ## 6) Long sessions drift or degrade @@ -114,4 +114,4 @@ This page follows: symptom -> likely causes -> 3-step checks. - Return to [Getting Started](./) for a minimal path - Daily operations: [Daily use](./daily-use) -- Gateway issues: [Gateway usage](./gateway) +- Gateway issues: [Gateway usage](/guide/gateway)