diff options
Diffstat (limited to 'doc/Design.md')
| -rw-r--r-- | doc/Design.md | 41 |
1 files changed, 36 insertions, 5 deletions
diff --git a/doc/Design.md b/doc/Design.md index f877e3e..d3ace2a 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -206,7 +206,7 @@ result: <final natural-language answer; completed only> - `stream=false`をv1既定とし、Agent内部でも1call単位の完了responseを扱う。 - `prompt_eval_count` と `eval_count` を毎callで取得する。 ### 6.2 Option mapping -`OllamaOptions` は既知optionをnullable typed propertyとして持つ。設定されていないpropertyはpayloadへ出さない。`extra_options` は `Dictionary<string, JsonElement>` とし、typed propertyと同名keyがある場合はconfiguration errorとする。 +`OllamaOptions` は既知optionをnullable typed propertyとして持つ。設定されていないpropertyはpayloadへ出さない。`extra_options` は `Dictionary<string, JsonElement>` とし、typed propertyと同名keyがある場合はtyped propertyを優先し、同名のextra optionをpayloadへ出さない。 代表的typed property: ```text num_ctx, num_keep, num_predict, temperature, seed, @@ -223,6 +223,7 @@ overrideはTask objectにcopyし、global configurationを変更しない。Sess ### 6.4 Vision - `images[]`をBase64としてOllama messageへ転送する。 - mime_type、Base64妥当性、設定上限size/countを事前検査する。 +- 既定上限は4画像、1画像10 MiB、request合計20 MiBとする。 - model capability確認でVision非対応と判定した場合はOllama呼出し前にlocalized error。能力確認不能時は呼出しを行い、Ollama errorを正規化して返す。 ### 6.5 Tool calling Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS command (`grep.exe`等) をtoolとして増殖させない。 @@ -242,11 +243,13 @@ Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS com - `root`はread許可directory/file配下でなければdeny。 - `tail`はtext file向け。binaryは拒否する。 - `max_results`にhard upper boundを設け、context爆発を防ぐ。 +- `max_results`のhard upper boundは1,000件、`tail_lines`は10,000行とする。 ### 7.2 file_read ```json {"path":"string","mode":"whole|range|metadata","start":0,"length":0} ``` - wholeはsize上限を超えた場合range利用を要求する。 +- whole readの既定上限は1 MiBとする。 - read前にcanonical pathとreparse pointを検査する。 ### 7.3 file_edit ```json @@ -286,7 +289,7 @@ Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS com "optimistic_tokens":0, "most_likely_tokens":0, "pessimistic_tokens":0, - "state":"queued|running|completed|failed|null" + "state":"queued|planning|running|completed|failed|cancelled|null" } ``` PlannerがDAG、不変条件、completed immutable、max_tasksを再検査してから適用する。 @@ -300,7 +303,7 @@ Task Id: UUID Description: string Dependencies: Set<TaskId> - State: queued|running|completed|failed + State: queued|planning|running|completed|failed|cancelled BudgetClass: TokenBudgetClass O, M, P: long ExpectedTokens: double @@ -349,7 +352,7 @@ AgentSession 7. previous Summary 8. recent Conversation / Execution Result ### 9.3 Summary policy -`num_ctx`に対する利用率が設定閾値を超えたとき、古いConversation/Execution Resultを要約する。次は削除・曖昧化してはならない。 +`num_ctx`に対する利用率が設定閾値を超えたとき、古いConversation/Execution Resultを要約する。既定閾値は80%とする。次は削除・曖昧化してはならない。 - 利用者が明示した制約 - 未完了Taskとdependency - completed Taskの重要成果 @@ -370,6 +373,10 @@ mcp: http: host: 127.0.0.1 port: 8080 + images: + max_count: 4 + max_bytes_each: 10485760 + max_total_bytes: 20971520 agent: user_system_prompt: prompts/user-system.md max_iterations: 128 @@ -403,6 +410,11 @@ sandbox: process_timeout_seconds: 1800 file_edit: memory_backup_limit_mb: 16 +limits: + whole_read_bytes: 1048576 + search_max_results: 1000 + tail_max_lines: 10000 + context_summary_ratio: 0.8 localization: directory: config/locales fallback: en @@ -515,6 +527,8 @@ failure -> rollback snapshot -> verify original hash ``` ### 13.2 backup threshold `memory_backup_limit_mb`以下はメモリsnapshot、それより大きい場合はTask専用temp directoryへbackupする。16MBをdefault候補とするが、実装時benchmarkで変更可能。これは仕様上の固定値ではない。 + +v1の既定値は16 MiBとし、benchmark結果を変更根拠として記録できるconfiguration defaultとして扱う。 ### 13.3 Patch patchは適用前にtarget hashまたはcontext一致を検査する。曖昧適用を禁止し、複数候補に一致する場合は失敗としてLLMへ返す。 --- @@ -567,9 +581,12 @@ Auditはappend-only JSONLを採用する。1 event = 1 line。 - stdio: EOFまたはparent process消失をClient切断とみなし、所有Taskをsafe stop。 - Streamable HTTP: 1回のHTTP response完了は切断ではない。MCP sessionの明示終了、session失効、server shutdownをsafe stop triggerとする。 ### 16.3 Ollama retry -network/temporary errorだけを最大3回retryする。validation error、Vision unsupported、invalid model等の恒久errorは即failed。backoffの具体値は実装時に小さく固定し、汎用retry frameworkを導入しない。 +network/temporary errorだけを最大3回retryする。validation error、Vision unsupported、invalid model等の恒久errorは即failed。backoffは250 ms、500 ms、1,000 msに固定し、汎用retry frameworkを導入しない。 --- ## 17. 状態遷移 +### 17.0 実行キュー +複数Taskの受付は許可するが、`planning` / `running` およびTask Resource適用はアプリケーション全体で最大1件とする。受付順の単一キューで直列実行する。 + ### 17.1 Task ```text queued -> planning -> running -> completed @@ -658,6 +675,13 @@ errorは内部codeとlocalized messageを分離し、ログ/auditにはcode、MC | 7 | WFP | deny/allow-list integration test | | 8 | Vision/Streamable HTTP | image optional、loopback HTTP | | 9 | Audit/Hardening | security matrix全PASS | +| 10 | Release/Operational E2E | self-contained Bundle単独起動、stdio/HTTP実利用 | + +### 21.1 Release設計 +- `dotnet publish -c Release -r win-x64 --self-contained true` のfolder publishを配布元とする。 +- Bundleはversion付きZIP、展開済みdirectory、file manifest、SHA-256 checksumから成る。 +- 起動時の相対pathは実行ファイルdirectoryを基準に解決し、ソースツリーを参照しない。 +- 必須Gateはlocal Ollamaだけで実行し、cloud modelは任意互換試験に限定する。 --- ## 22. Codex実装制約 - 新規NuGet dependencyを勝手に追加しない。追加時は標準ライブラリで不能な理由を示す。 @@ -744,6 +768,13 @@ errorは内部codeとlocalized messageを分離し、ログ/auditにはcode、MC | localization.fallback | en | | skills.directory | Skill directory | | logging.directory | log directory | +| limits.whole_read_bytes | whole read上限 | +| limits.search_max_results | search結果上限 | +| limits.tail_max_lines | tail行数上限 | +| limits.context_summary_ratio | context要約開始比率 | +| mcp.images.max_count | 画像数上限 | +| mcp.images.max_bytes_each | 1画像byte上限 | +| mcp.images.max_total_bytes | request画像合計byte上限 | ## 28. 主要データ型索引 - `AgentSession` - `AgentTask` |