Skip to content

Commit 2553193

Browse files
lava-clawmanlava-clawman
committed
docs: polish google native provider guidance
1 parent 29da7ca commit 2553193

5 files changed

Lines changed: 114 additions & 32 deletions

File tree

‎README.en.md‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,14 @@ Once installed, Claw can invoke InkOS atomic commands and control-surface operat
5151
```bash
5252
inkos config set-global \
5353
--lang en \
54-
--provider <openai|anthropic|custom> \
54+
--provider <openai|anthropic|custom|google> \
5555
--base-url <API endpoint> \
5656
--api-key <your API key> \
5757
--model <model name>
5858

59-
# provider: openai / anthropic / custom (use custom for OpenAI-compatible proxies)
59+
# provider: openai / anthropic / custom / google
60+
# - custom: use for OpenAI-compatible proxies
61+
# - google: Gemini native API (recommended default model: gemini-2.5-flash)
6062
# base-url: your API provider URL
6163
# api-key: your API key
6264
# model: your model name
@@ -73,10 +75,10 @@ inkos init my-novel # Initialize project
7375

7476
```bash
7577
# Required
76-
INKOS_LLM_PROVIDER= # openai / anthropic / custom (use custom for any OpenAI-compatible API)
77-
INKOS_LLM_BASE_URL= # API endpoint
78+
INKOS_LLM_PROVIDER= # openai / anthropic / custom / google
79+
INKOS_LLM_BASE_URL= # API endpoint (for google use https://generativelanguage.googleapis.com/v1beta)
7880
INKOS_LLM_API_KEY= # API Key
79-
INKOS_LLM_MODEL= # Model name
81+
INKOS_LLM_MODEL= # Model name (recommended for Google native: gemini-2.5-flash)
8082

8183
# Language (defaults to global setting or genre default)
8284
# INKOS_DEFAULT_LANGUAGE=en # en or zh
@@ -102,6 +104,21 @@ inkos config show-models # View current routing
102104

103105
Agents without explicit overrides fall back to the global model.
104106

107+
**Google Native Provider (Gemini)**
108+
109+
You can also use Gemini through the native Google provider instead of an OpenAI-compatible shim:
110+
111+
```bash
112+
inkos config set-global \
113+
--lang en \
114+
--provider google \
115+
--base-url https://generativelanguage.googleapis.com/v1beta \
116+
--api-key <your-google-api-key> \
117+
--model gemini-2.5-flash
118+
```
119+
120+
The recommended default model is `gemini-2.5-flash`. Gemini `3.x` preview models were validated online as well, but they are still treated as preview options rather than the default stable recommendation.
121+
105122
### v0.6 Update
106123

107124
**Structured State + Hook Governance + Length Governance**
@@ -224,6 +241,16 @@ Different agents can use different models and providers. Writer on Claude (stron
224241

225242
Supports any OpenAI-compatible endpoint (`--provider custom`). Stream auto-fallback — when SSE isn't supported, InkOS retries with sync mode automatically. Fallback parser handles non-standard output from smaller models, and partial content recovery kicks in on stream interruption.
226243

244+
### Google Native Provider
245+
246+
InkOS also supports `--provider google` for Gemini's native API. The following were validated online:
247+
248+
- non-stream text generation via `generateContent`
249+
- Gemini-native function/tool calling turns
250+
- replaying tool results back to Gemini, including preserving and forwarding `thoughtSignature`
251+
252+
Current boundary: this is the validated scope today, not a claim of full provider parity. The recommended default remains `gemini-2.5-flash`; Gemini `3.x` preview models were validated, but are not the default stable recommendation.
253+
227254
### Reliability
228255

229256
Every chapter creates an automatic state snapshot — `inkos write rewrite` rolls back any chapter to its pre-write state. The Writer outputs a pre-write checklist (context scope, resources, pending hooks, risks) and a post-write settlement table; the Auditor cross-validates both. File locking prevents concurrent writes. Post-write validator includes cross-chapter repetition detection and 11 hard rules with auto spot-fix.

‎README.ja.md‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,14 @@ npm でインストール済み、またはリポジトリをクローン済み
5151
```bash
5252
inkos config set-global \
5353
--lang en \
54-
--provider <openai|anthropic|custom> \
54+
--provider <openai|anthropic|custom|google> \
5555
--base-url <APIエンドポイント> \
5656
--api-key <APIキー> \
5757
--model <モデル名>
5858

59-
# provider: openai / anthropic / custom（OpenAI互換プロキシにはcustomを使用）
59+
# provider: openai / anthropic / custom / google
60+
# - custom：OpenAI互換プロキシ向け
61+
# - google：Gemini ネイティブ API（推奨デフォルトモデル: gemini-2.5-flash）
6062
# base-url: APIプロバイダーURL
6163
# api-key: APIキー
6264
# model: モデル名
@@ -73,10 +75,10 @@ inkos init my-novel # プロジェクトを初期化
7375

7476
```bash
7577
# 必須
76-
INKOS_LLM_PROVIDER= # openai / anthropic / custom（OpenAI互換APIにはcustomを使用）
77-
INKOS_LLM_BASE_URL= # APIエンドポイント
78+
INKOS_LLM_PROVIDER= # openai / anthropic / custom / google
79+
INKOS_LLM_BASE_URL= # APIエンドポイント（google は https://generativelanguage.googleapis.com/v1beta）
7880
INKOS_LLM_API_KEY= # APIキー
79-
INKOS_LLM_MODEL= # モデル名
81+
INKOS_LLM_MODEL= # モデル名（Google ネイティブ推奨: gemini-2.5-flash）
8082

8183
# 言語（グローバル設定またはジャンルのデフォルトに準拠）
8284
# INKOS_DEFAULT_LANGUAGE=en # en または zh
@@ -102,6 +104,21 @@ inkos config show-models # 現在のルーティングを表示
102104

103105
明示的なオーバーライドがないエージェントはグローバルモデルにフォールバックします。
104106

107+
**Google ネイティブ Provider（Gemini）**
108+
109+
OpenAI互換のシムを使わず、`--provider google` で Gemini ネイティブ API を直接利用できます。
110+
111+
```bash
112+
inkos config set-global \
113+
--lang en \
114+
--provider google \
115+
--base-url https://generativelanguage.googleapis.com/v1beta \
116+
--api-key <your-google-api-key> \
117+
--model gemini-2.5-flash
118+
```
119+
120+
推奨デフォルトモデルは `gemini-2.5-flash` です。Gemini `3.x` プレビューモデルもオンラインで検証済みですが、現時点ではプレビュー扱いであり、デフォルトの安定推奨にはしていません。
121+
105122
### v0.6 アップデート
106123

107124
**構造化ステート + フック管理 + 文字数管理**
@@ -224,6 +241,16 @@ inkos compose chapter my-book
224241

225242
任意のOpenAI互換エンドポイント（`--provider custom`）に対応。ストリーム自動フォールバック — SSEがサポートされていない場合、InkOS は自動的に同期モードでリトライ。フォールバックパーサーが小型モデルの非標準出力を処理し、ストリーム中断時には部分コンテンツリカバリが作動。
226243

244+
### Google ネイティブ Provider
245+
246+
InkOS は `--provider google` による Gemini ネイティブ API にも対応しています。オンラインで検証済みなのは次の範囲です。
247+
248+
- `generateContent` による非ストリームのテキスト生成
249+
- Gemini ネイティブの関数呼び出し / ツール呼び出しターン
250+
- ツール結果の Gemini への再投入、および `thoughtSignature` の保持と引き継ぎ
251+
252+
現時点の境界: これは検証済みスコープの説明であり、他 Provider との完全な機能同等性を主張するものではありません。推奨デフォルトは引き続き `gemini-2.5-flash` で、Gemini `3.x` プレビューモデルは検証済みですがデフォルトの安定推奨ではありません。
253+
227254
### 信頼性
228255

229256
章ごとに自動ステートスナップショットを作成 — `inkos write rewrite` で任意の章を執筆前の状態にロールバック可能。Writerは執筆前チェックリスト（コンテキストスコープ、リソース、保留中のフック、リスク）と執筆後決済テーブルを出力し、Auditorが両方をクロスバリデーション。ファイルロックにより同時書き込みを防止。執筆後バリデーターにはクロスチャプター反復検出と11のハードルールによる自動スポット修正を搭載。

‎README.md‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,17 @@ clawhub install inkos # 从 ClawHub 安装 InkOS Skill
5050

5151
```bash
5252
inkos config set-global \
53-
--provider <openai|anthropic|custom> \
53+
--provider <openai|anthropic|custom|google> \
5454
--base-url <API 地址> \
5555
--api-key <你的 API Key> \
5656
--model <模型名>
5757

58-
# provider: openai / anthropic / custom（兼容 OpenAI 格式的中转站选 custom）
59-
# base-url: 你的 API 提供商地址
60-
# api-key: 你的 API Key
61-
# model: 你的模型名称
58+
# provider: openai / anthropic / custom / google
59+
# - custom：兼容 OpenAI 格式的中转站
60+
# - google：Gemini 原生接口（推荐默认模型：gemini-2.5-flash）
61+
# base-url: API 提供商地址
62+
# api-key: API Key
63+
# model: 模型名称
6264
```
6365

6466
配置保存在 `~/.inkos/.env`，所有项目共享。之后新建项目不用再配。
@@ -72,10 +74,10 @@ inkos init my-novel # 初始化项目
7274

7375
```bash
7476
# 必填
75-
INKOS_LLM_PROVIDER= # openai / anthropic / custom（兼容 OpenAI 接口的都选 custom）
76-
INKOS_LLM_BASE_URL= # API 地址（支持中转站、智谱、Gemini 等）
77+
INKOS_LLM_PROVIDER= # openai / anthropic / custom / google
78+
INKOS_LLM_BASE_URL= # API 地址（custom 用兼容 OpenAI 的地址；google 用 https://generativelanguage.googleapis.com/v1beta）
7779
INKOS_LLM_API_KEY= # API Key
78-
INKOS_LLM_MODEL= # 模型名
80+
INKOS_LLM_MODEL= # 模型名（Google 原生推荐 gemini-2.5-flash）
7981

8082
# 可选
8183
# INKOS_LLM_TEMPERATURE=0.7 # 温度
@@ -98,6 +100,20 @@ inkos config show-models # 查看当前路由
98100

99101
未单独配置的 Agent 自动使用全局模型。
100102

103+
**Google 原生 Provider（Gemini）**
104+
105+
可直接使用 `--provider google` 走 Gemini 原生接口，无需再伪装成 OpenAI 兼容端点：
106+
107+
```bash
108+
inkos config set-global \
109+
--provider google \
110+
--base-url https://generativelanguage.googleapis.com/v1beta \
111+
--api-key <your-google-api-key> \
112+
--model gemini-2.5-flash
113+
```
114+
115+
当前推荐默认模型是 `gemini-2.5-flash`。`gemini-3.x` 预览模型已经做过联机验证，但目前更适合当作预览选项，不作为默认稳定推荐。
116+
101117
### v0.6 更新
102118

103119
**结构化状态 + 伏笔治理 + 字数治理**
@@ -194,6 +210,16 @@ inkos compose chapter 吞天魔帝
194210

195211
支持任何 OpenAI 兼容接口（`--provider custom`）。Stream 自动降级——中转站不支持 SSE 时自动回退 sync。Fallback 解析器处理小模型不规范输出，流中断时自动恢复部分内容。
196212

213+
### Google 原生 Provider
214+
215+
InkOS 也支持 `--provider google` 直连 Gemini 原生接口。当前已经联机验证：
216+
217+
- 非流式文本生成（`generateContent`）
218+
- Gemini 原生函数调用 / 工具调用回合
219+
- 工具调用后的结果回放，以及 `thoughtSignature` 的保留与续传
220+
221+
当前边界：这是已验证能力范围，不宣称与其他 Provider 完全等价；推荐默认模型仍是 `gemini-2.5-flash`，`gemini-3.x` 预览模型已验证可用，但暂不作为默认稳定推荐。
222+
197223
### 可靠性保障
198224

199225
每章自动创建状态快照，`inkos write rewrite` 可回滚任意章节。写手动笔前输出自检表（上下文、资源、伏笔、风险），写完输出结算表，审计员交叉验证。文件锁防止并发写入。写后验证器含跨章重复检测和 11 条硬规则自动 spot-fix。

‎packages/cli/src/commands/config.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -87,10 +87,10 @@ configCommand
8787
configCommand
8888
.command("set-global")
8989
.description("Set global LLM config (~/.inkos/.env), shared by all projects")
90-
.requiredOption("--provider <provider>", "LLM provider (openai / anthropic / custom / google)")
91-
.requiredOption("--base-url <url>", "API base URL")
90+
.requiredOption("--provider <provider>", "LLM provider (openai / anthropic / custom / google; use google for Gemini native)")
91+
.requiredOption("--base-url <url>", "API base URL (for Google native: https://generativelanguage.googleapis.com/v1beta)")
9292
.requiredOption("--api-key <key>", "API key")
93-
.requiredOption("--model <model>", "Model name")
93+
.requiredOption("--model <model>", "Model name (recommended Google native default: gemini-2.5-flash)")
9494
.option("--temperature <n>", "Temperature")
9595
.option("--max-tokens <n>", "Max output tokens")
9696
.option("--thinking-budget <n>", "Anthropic thinking budget")
@@ -177,7 +177,7 @@ configCommand
177177
.argument("<agent>", `Agent name (${KNOWN_AGENTS.join(", ")})`)
178178
.argument("<model>", "Model name")
179179
.option("--base-url <url>", "API base URL (for different provider)")
180-
.option("--provider <provider>", "Provider type (openai / anthropic / custom / google)")
180+
.option("--provider <provider>", "Provider type (openai / anthropic / custom / google; use google for Gemini native)")
181181
.option("--api-key-env <envVar>", "Env variable name for API key (e.g., PACKYAPI_KEY)")
182182
.option("--stream", "Enable streaming (default)")
183183
.option("--no-stream", "Disable streaming")

‎packages/cli/src/commands/init.ts‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,10 @@ export const initCommand = new Command("init")
7474
"# Project-level LLM overrides (optional)",
7575
"# Global config at ~/.inkos/.env will be used by default.",
7676
"# Uncomment below to override for this project only:",
77-
"# INKOS_LLM_PROVIDER=openai",
78-
"# INKOS_LLM_BASE_URL=",
77+
"# INKOS_LLM_PROVIDER=google",
78+
"# INKOS_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta",
7979
"# INKOS_LLM_API_KEY=",
80-
"# INKOS_LLM_MODEL=",
80+
"# INKOS_LLM_MODEL=gemini-2.5-flash",
8181
"",
8282
"# Web search (optional):",
8383
"# TAVILY_API_KEY=tvly-xxxxx",
@@ -90,11 +90,12 @@ export const initCommand = new Command("init")
9090
[
9191
"# LLM Configuration",
9292
"# Tip: Run 'inkos config set-global' to set once for all projects.",
93+
"# Recommended Google native default: gemini-2.5-flash (Gemini 3.x preview models were validated, but are not the default stable recommendation).",
9394
"# Provider: openai (OpenAI native), custom (OpenAI-compatible proxy), anthropic (Anthropic native), google (Gemini native)",
94-
"INKOS_LLM_PROVIDER=openai",
95-
"INKOS_LLM_BASE_URL=",
95+
"INKOS_LLM_PROVIDER=google",
96+
"INKOS_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta",
9697
"INKOS_LLM_API_KEY=",
97-
"INKOS_LLM_MODEL=",
98+
"INKOS_LLM_MODEL=gemini-2.5-flash",
9899
"",
99100
"# Optional parameters (defaults shown):",
100101
"# INKOS_LLM_TEMPERATURE=0.7",
@@ -107,9 +108,9 @@ export const initCommand = new Command("init")
107108
"",
108109
"# Anthropic example:",
109110
"# INKOS_LLM_PROVIDER=anthropic",
110-
"# INKOS_LLM_PROVIDER=anthropic",
111-
"# INKOS_LLM_BASE_URL=",
112-
"# INKOS_LLM_MODEL=",
111+
"# INKOS_LLM_BASE_URL=https://api.anthropic.com",
112+
"# INKOS_LLM_API_KEY=",
113+
"# INKOS_LLM_MODEL=claude-sonnet-4-20250514",
113114
].join("\n"),
114115
"utf-8",
115116
);
@@ -137,8 +138,9 @@ export const initCommand = new Command("init")
137138
log("Next steps:");
138139
if (name) log(` cd ${name}`);
139140
log(" # Option 1: Set global config (recommended, one-time):");
140-
log(" inkos config set-global --provider google --base-url https://generativelanguage.googleapis.com/v1beta --api-key <your-key> --model gemini-2.5-pro");
141+
log(" inkos config set-global --provider google --base-url https://generativelanguage.googleapis.com/v1beta --api-key <your-key> --model gemini-2.5-flash");
141142
log(" # Option 2: Edit .env for this project only");
143+
log(" # Note: gemini-2.5-flash is the recommended stable default; Gemini 3.x preview models were validated but remain preview choices.");
142144
log("");
143145
log(exampleCreate);
144146
}

0 commit comments

Comments
 (0)