diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Design.md | 41 | ||||
| -rw-r--r-- | doc/Specifications.md | 23 |
2 files changed, 59 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` diff --git a/doc/Specifications.md b/doc/Specifications.md index 9d13343..2aa19c5 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -155,6 +155,13 @@ IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・ | failed | 回復不能な失敗 | 終端 | | cancelled | 安全停止完了 | 終端 | +### 5.5.1 v1実行並列性 + +- 複数Taskを `queued` として同時に受け付けることができる。 +- アプリケーション全体で `planning` または `running` になれるTaskは最大1件とする。 +- Task Resourceを適用できるTaskも同時に最大1件とする。 +- `agent_run` の非同期受付は維持し、実行待ちTaskは受付順の単一キューで処理する。 + ### 5.6 CLI v1のCLI surfaceは次に限定する。 @@ -186,6 +193,8 @@ CLIは起動方式と表示言語を変更するためのI/Fであり、SandboxP | OLL-12 | Retry | Ollama通信失敗は既定3回まで再試行する。 | | OLL-13 | Usage | `prompt_eval_count` と `eval_count` をTask実測tokenとして記録する。 | +Vision入力は設定可能な画像数、1画像あたりのsize、request合計sizeの上限を持ち、上限超過をOllama呼出し前に拒否しなければならない。具体的な既定値は設計および設定schemaで定義する。 + --- ## 7. Agent Runtime仕様 @@ -205,6 +214,8 @@ CLIは起動方式と表示言語を変更するためのI/Fであり、SandboxP AgentはTaskの期待副作用と観測結果を比較し、実行が必要なのにtool callが0件の場合はTaskをcompletedにしない。再試行はAgent Loopの失敗回数へ算入する。純粋な説明・分析Taskにはtool callを強制しない。 +Internal Toolが返す読取・検索・tail結果は設定可能な上限を持ち、contextを無制限に消費してはならない。上限値は設計および設定schemaで定義する。 + --- ## 8. Planner仕様 @@ -261,6 +272,8 @@ Task実績はOllama応答の `prompt_eval_count` をinput token、`eval_count` | SES-05 | context上限接近時は古い情報を単純削除せず要約する。 | | SES-06 | 要約後も未完了Task、security decision、重要なexecution result、利用者制約を保持する。 | +Context要約を開始する利用率閾値は設定可能でなければならない。具体値は設計および設定schemaで定義する。 + --- ## 10. Skill・Prompt仕様 @@ -359,6 +372,7 @@ Task実績はOllama応答の `prompt_eval_count` をinput token、`eval_count` - overwrite、patch、atomic replaceを併用できる。 - 通常は変更前内容をメモリに保持し、編集後検証に失敗した場合にrollbackする。 - 設定されたmemory backup閾値を超える大容量ファイルでは、Sandbox管理下の一時backupを使用できる。 +- memory backup閾値は設定可能でなければならない。 - 利用者向け恒久 `.bak` ファイルは既定で作成しない。 - atomic replaceが適用可能な操作では、部分書込み状態を利用者から観測させないことを優先する。 @@ -489,6 +503,15 @@ Task実績はOllama応答の `prompt_eval_count` をinput token、`eval_count` | AT-19 | 追加localeがコード変更なしでロードされる。 | | AT-20 | 未知locale keyまたは壊れたJSONで起動/checkが失敗する。 | +### 20.1 Operational E2E + +| ID | 検証条件 | +| --- | --- | +| E2E-01 | ソースツリー外へ展開したRelease Bundleだけを使い、local Ollamaとstdio MCP Clientから実際のfixture修正、build、test、日本語応答、Audit追跡、Task Resource cleanupまで完走する。 | +| E2E-02 | E2E-01と同等の作業をloopback限定Streamable HTTPで完走する。 | + +v1の完了には、win-x64向けself-contained Release Bundleが単独起動でき、E2E-01とE2E-02がInternetまたはcloud modelに依存せずPASSすることを必須とする。 + --- ## 21. 要求トレーサビリティ |