人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項目地址https://gitcode.com/gh_mirrors/gs/gsd-2點擊查看免費下載本篇技術(shù)指南以 GSD 項目GitHub 加速計劃 / gsd-2一個面向長期自主運行的元提示、上下文工程與規(guī)范驅(qū)動開發(fā)系統(tǒng)的官方文檔為基礎(chǔ)系統(tǒng)講解如何通過~/.gsd/agent/models.json將默認模型注冊表之外的模型接入 GSD——包括自托管推理端點Ollama、vLLM、LM Studio、微調(diào)模型、代理網(wǎng)關(guān)LiteLLM、OpenRouter、Vercel AI Gateway以及新發(fā)布的商業(yè)模型。讀完本文你將掌握 models.json 的完整配置語法、API Key 的三種取值方式、OpenAI 兼容性開關(guān)的逐項含義、Provider 級與模型級覆蓋語義以及成本追蹤與社區(qū)擴展的接入方法。配置入口models.json 的位置、加載時機與優(yōu)先級GSD 通過~/.gsd/agent/models.json加載自定義模型與 Provider其解析邏輯實現(xiàn)在 models-resolver.ts 中。官方文檔給出的查找順序為~/.gsd/agent/models.json主路徑~/.pi/agent/models.json回退路徑面向從 PI 平滑遷移/開發(fā)場景從源碼看實際解析邏輯比文檔描述更細resolveModelsJsonPath()會依次檢查兩個路徑是否存在——若 GSD 路徑存在則直接返回否則若 PI 路徑存在則返回 PI 路徑兩者都不存在時返回 GSD 路徑該文件將被創(chuàng)建。文件頭注釋還揭示了三態(tài)合并語義當兩個文件同時存在時兩個文件會被合并且 GSD 文件優(yōu)先級更高。文件在每次打開/model時重新加載會話中途編輯無需重啟。這一點也體現(xiàn)在 preferences-models.ts 的實現(xiàn)中它以輕量 JSON 解析直接讀取 models.json保持與resolveModelsJsonPath()一致的雙路徑回退并且格式錯誤的 models.json 不會阻斷會話啟動——該模塊顯式忽略解析異常。同理doctor-providers.ts 在健康檢查中對損壞的 models.json 也不會報錯?；窘Y(jié)構(gòu)Provider 與 Model 兩層模型models.json 采用Provider 容器 Model 列表的兩層結(jié)構(gòu){ providers: { my-provider: { baseUrl: https://my-endpoint.example.com/v1, apiKey: MY_PROVIDER_API_KEY, api: openai-completions, models: [ { id: model-id-here, name: Friendly Model Name, reasoning: false, input: [text], contextWindow: 128000, maxTokens: 16384, cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 } } ] } } }最小示例接入本地模型對于本地模型Ollama、LM Studio、vLLM每個模型只需要id一個字段{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, models: [ { id: llama3.1:8b }, { id: qwen2.5-coder:7b } ] } } }apiKey字段在 JSON 語法上必須存在但 Ollama 會忽略它的值所以任意字符串都可以。/model與--list-models均按模型id列出條目配置的name用于模型匹配--model模式匹配以及模型詳情/狀態(tài)文本展示。支持的 API 類型api字段決定 GSD 以何種協(xié)議與端點通信可在 Provider 層設(shè)置該 Provider 下所有模型的默認值也可在模型層覆蓋API說明openai-completionsOpenAI Chat Completions兼容性最好本地服務(wù)首選openai-responsesOpenAI Responses APIanthropic-messagesAnthropic Messages APIgoogle-generative-aiGoogle Generative AI模型配置字段參考字段必填默認值說明id是—模型標識符實際傳給 API 的模型名name否id人類可讀的模型標簽用于--model匹配與狀態(tài)展示api否Provider 的api覆蓋 Provider 層的 API 類型reasoning否false是否支持擴展思考extended thinkinginput否[text]輸入類型[text]或[text, image]contextWindow否128000上下文窗口大小token 數(shù)maxTokens否16384最大輸出 token 數(shù)cost否全零每百萬 token 成本{input, output, cacheRead, cacheWrite}compat否Provider 的compatOpenAI 兼容性覆蓋與 Provider 層compat合并生效關(guān)于reasoning: true的模型從 openai-completions.ts 的實現(xiàn)看系統(tǒng)提示詞的角色選擇與思考參數(shù)的注入都由reasoning與compat共同決定見下文。API Key 解析環(huán)境變量、字面量與占位值apiKey字段支持三種取值方式GSD 會自動分辨環(huán)境變量名OPENROUTER_API_KEY— GSD 自動解析同名環(huán)境變量的值字面量sk-abc123...— 直接使用該字符串占位值not-needed— 供無需鑒權(quán)的本地服務(wù)使用。更完整的取值機制見 docs/user-docs/custom-models.md其中apiKey與headers的取值實際支持三種格式比 gitbook 版文檔多出一種Shell 命令格式Shell 命令以!開頭執(zhí)行命令并取 stdout 作為值例如從系統(tǒng)鑰匙串或密碼管理器讀取憑據(jù)apiKey: !security find-generic-password -ws anthropic apiKey: !op read op://vault/item/credential該機制有命令白名單保護只有以pass、op、aws、gcloud、vault、security、gpg、bw、gopass、lpass開頭的命令允許執(zhí)行其余命令被攔截且值解析為undefined同時向 stderr 寫入警告命令參數(shù)中禁止出現(xiàn);、|、、反引號、$、、等 Shell 運算符以防止注入。若使用白名單之外的憑據(jù)工具可在全局設(shè)置~/.gsd/agent/settings.json中通過allowedCommandPrefixes整體替換默認白名單需自行包含仍要保留的默認項{ allowedCommandPrefixes: [pass, op, sops, doppler, mycli] }也可以設(shè)置逗號分隔的環(huán)境變量GSD_ALLOWED_COMMAND_PREFIXES其優(yōu)先級高于 settings.jsonexport GSD_ALLOWED_COMMAND_PREFIXESpass,op,sops,doppler注意該設(shè)置是全局限定的項目級project/.gsd/settings.json無法覆蓋命令白名單——這是為了防止克隆倉庫提升命令執(zhí)行權(quán)限。從源碼側(cè)印證doctor-providers.ts 會把認證來源歸類為auth.json、env、models.json、none四類doctor-providers.test.ts 中的測試也驗證了 models.json 中的 apiKey 可以滿足自定義 Provider 的鑒權(quán)檢查。這意味著配置了有效 apiKey 的自定義 Provider 不會觸發(fā)儀表盤的健康告警。Compatibility FlagsOpenAI 兼容性開關(guān)本地服務(wù)與非標準服務(wù)器往往需要兼容性調(diào)整compat字段就是為此設(shè)計的{ compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, stripReasoningContent: true, supportsUsageInStreaming: false, thinkingFormat: qwen } }compat可以放在 Provider 層對該 Provider 下所有模型生效也可以放在模型層僅覆蓋該模型。兩層同時設(shè)置時會合并模型層優(yōu)先。開關(guān)默認值作用supportsDeveloperRoletrue服務(wù)器不支持developer消息角色時設(shè)為falsesupportsReasoningEfforttrue服務(wù)器不支持reasoning_effort參數(shù)時設(shè)為falsestripReasoningContentfalse設(shè)為true時從外發(fā)歷史中剝離回放的 assistantreasoning_content字段部分 vLLM/TensorRT-LLM 端點否則會返回 400 錯誤supportsUsageInStreamingtrue流式響應(yīng)不包含 token 用量時設(shè)為falsethinkingFormat—qwen使用 Qwen 思考模式qwen-chat-template使用聊天模板變體背后的源碼機制這些開關(guān)在 pi-ai 的 OpenAI 兼容層中有完整實現(xiàn)。OpenAICompletionsCompat接口定義于 types.ts除上述開關(guān)外還包括maxTokensFieldmax_completion_tokens或max_tokens、requiresToolResultName、requiresAssistantAfterToolResult、requiresThinkingAsText、supportsStrictMode、reasoningEffortMap等且多數(shù)開關(guān)標注為從 URL 自動探測默認值。關(guān)鍵行為對應(yīng)關(guān)系如下supportsDeveloperRole在 openai-completions.ts 的convertMessages()中系統(tǒng)提示詞的角色由model.reasoning compat.supportsDeveloperRole決定——推理模型且服務(wù)器支持時才使用developer角色否則回退為system消息。這與 docs/user-docs/custom-models.md 的說明一致不支持developer角色的服務(wù)器如 Ollama 等本地端點應(yīng)設(shè)supportsDeveloperRole: false讓 GSD 用system消息發(fā)送系統(tǒng)提示詞。stripReasoningContent同樣在convertMessages()中實現(xiàn)啟用時會在外發(fā)消息轉(zhuǎn)換階段剝離回放的推理字段。單元測試 openai-completions.test.ts 用一條帶thinkingSignature: reasoning_content的 assistant 消息驗證了兩種行為啟用后reasoning_content字段被剝離值為undefined未啟用時則原樣透傳。thinkingFormat與思考參數(shù)請求構(gòu)造邏輯中zai與qwen格式對推理模型使用頂層enable_thinking: boolean值由 reasoningEffort 決定OpenAI 風格默認openai則通過reasoning_effort參數(shù)注入并可經(jīng)reasoningEffortMap將 GSD 思考級別映射為 Provider 特定的取值。qwen使用頂層enable_thinking而qwen-chat-template針對需要chat_template_kwargs.enable_thinking的本地 Qwen 兼容服務(wù)器。內(nèi)置模型注冊表 custom.ts 中多個 Qwen/Z.ai 系列條目即使用thinkingFormat: qwen/zai配合supportsDeveloperRole: false。自定義 Headers為代理補充額外請求頭需要額外請求頭的代理場景可在 Provider 層設(shè)置headers{ providers: { litellm-proxy: { baseUrl: https://litellm.example.com/v1, apiKey: MY_API_KEY, api: openai-completions, headers: { x-custom-header: value }, models: [...] } } }headers的取值方式與apiKey完全一致同樣支持環(huán)境變量名、字面量與 Shell 命令三種格式。例如通過 Portkey 網(wǎng)關(guān)路由 Anthropic 請求時可以這樣寫headers: { x-portkey-api-key: PORTKEY_API_KEY, x-secret: !op read op://vault/item/secret }另外Provider 層還有authHeader字段設(shè)為true時 GSD 自動追加Authorization: Bearer apiKey請求頭。Model Overrides按模型覆蓋內(nèi)置模型無需重定義整個模型modelOverrides允許在不重寫 Provider 全部模型列表的前提下精細化定制某個內(nèi)置模型的設(shè)置{ providers: { openrouter: { modelOverrides: { anthropic/claude-sonnet-4: { compat: { openRouterRouting: { only: [amazon-bedrock] } } } } } } }modelOverrides支持按模型覆蓋以下字段name、reasoning、input、cost支持部分覆蓋、contextWindow、maxTokens、headers、compat。行為語義如下覆蓋只作用于內(nèi)置 Provider 的模型未知模型 ID 會被忽略可同時使用 Provider 層的baseUrl/headers與modelOverrides若 Provider 同時定義了models數(shù)組自定義模型在內(nèi)置覆蓋之后合并——id相同的自定義模型會替換被覆蓋的內(nèi)置條目。openRouterRouting與vercelGatewayRouting在 types.ts 中都有類型定義二者結(jié)構(gòu)一致only指定僅路由到的 Provider 列表order指定嘗試順序。請求構(gòu)造邏輯中當baseUrl指向 openrouter.ai 且模型帶openRouterRouting時路由偏好以provider字段傳給 OpenRouter指向 Vercel AI Gateway 時則以providerOptions.gateway傳遞。Vercel 網(wǎng)關(guān)示例如路由 Kimi K2.5 經(jīng)由 Fireworks/Novitacompat: { vercelGatewayRouting: { only: [fireworks, novita], order: [fireworks, novita] } }覆蓋內(nèi)置 Provider將流量重定向到代理若只是想把某個內(nèi)置 Provider 的流量經(jīng)代理轉(zhuǎn)發(fā)不必重定義其模型列表——直接覆蓋baseUrl即可{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1 } } }此時內(nèi)置 Anthropic 模型全部保留可用原有的 OAuth 或 API Key 鑒權(quán)繼續(xù)生效。若要同時向內(nèi)置 Provider 合并自定義模型則需補上models數(shù)組{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1, apiKey: ANTHROPIC_API_KEY, api: anthropic-messages, models: [...] } } }合并語義與 docs/user-docs/custom-models.md 中 Overriding Built-in Providers 章節(jié)一致內(nèi)置模型保留自定義模型按id在 Provider 內(nèi) upsertid與內(nèi)置模型相同的自定義模型替換內(nèi)置條目全新id則追加到內(nèi)置模型旁。Cost Tracking讓自定義模型成本不再顯示為 $0.00自定義模型默認不產(chǎn)生成本數(shù)據(jù)——沒有cost字段時成本追蹤顯示 $0.00這是預(yù)期默認行為。需要準確成本統(tǒng)計時按每百萬 token添加cost字段cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 }cost同樣支持部分覆蓋如僅在modelOverrides中覆蓋input與output。本地模型成本為零時可顯式寫全零與內(nèi)置注冊表中各模型的成本結(jié)構(gòu)保持同構(gòu)。社區(qū)擴展為未內(nèi)置 Provider 提供完整支持對于 GSD 未內(nèi)置的 Provider社區(qū)擴展可提供完整的 Provider 支持。例如阿里云 DashScopeQwen3、GLM-5 等通過pi-dashscope擴展安裝gsd install npm:pi-dashscope擴展機制與 extensions 生態(tài)相關(guān)更多說明可參考 docs/dev/extending-pi/ 與 docs/extension-sdk/。常見排障與最佳實踐小結(jié)400 錯誤來自推理內(nèi)容回放若接入 vLLM/TensorRT-LLM 端點時多輪對話請求返回 400優(yōu)先檢查compat.stripReasoningContent: true參考 docs/user-docs/custom-models.md 的說明與 openai-completions.test.ts 的驗證用例。角色錯誤本地服務(wù)器不支持developer角色時設(shè)置compat.supportsDeveloperRole: false同時不支持reasoning_effort時再設(shè)置supportsReasoningEffort: falseOllama 即屬此類詳見 docs/user-docs/providers.md 中的 Ollama 配置示例。憑據(jù)來源可觀測gsd doctor的健康檢查會報告每個自定義 Provider 的認證來源models.json/env/auth.json可通過 doctor-providers.ts 的實現(xiàn)了解其判定邏輯。配置即時生效修改 models.json 后打開/model即可重載無需重啟 GSD格式錯誤不會阻斷啟動可放心迭代。綜合來看models.json 是 GSD 接入任意模型的關(guān)鍵擴展點無論是本地 Ollama/vLLM/LM Studio、私有微調(diào)模型還是 OpenRouter、Vercel AI Gateway 等代理網(wǎng)關(guān)都可在一份 JSON 中完成注冊、鑒權(quán)、兼容性適配與成本配置并在/model中立即切換使用。贊分享人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項目地址https://gitcode.com/gh_mirrors/gs/gsd-2點擊查看免費下載相關(guān)推薦MLflow Gateway 插件 Provider 實戰(zhàn)通過 Python Entry Point 擴展自定義模型端點MLflow Gateway 插件 Provider 實戰(zhàn)通過 Python Entry Point 擴展自定義模型端點 導(dǎo)讀 MLflow GatewayMLOpsLLMOps人工智能大模型模型評測LLM 網(wǎng)關(guān)可觀測性mpv Lua 腳本完整指南5 個腳本快速搞定追劇、裁剪、音量與置頂mpv Lua 腳本完整指南5 個腳本快速搞定追劇、裁剪、音量與置頂 看老電影上下黑邊占掉小半個屏追到第 5 集播放器卻停在列表結(jié)束電視劇廣告炸耳音視頻視頻音頻Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊實戰(zhàn)Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊實戰(zhàn) 每個 Flue Agent 在同一時刻只由一個 LLM 驅(qū)動而這個模型人工智能大模型AI AgentAgent 框架工具調(diào)用Agent 沙箱MCP Clients上一篇告別聊天記錄丟失WeChatMsg 微信聊天記錄導(dǎo)出與永久保存完整指南下一篇如何用SubtitleEdit完成字幕編輯時間軸校準、批量轉(zhuǎn)換與OCR實戰(zhàn)全攻略創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考