diff options
| author | tanaka takashi <isazaka@gmail.com> | 2026-08-11 00:04:36 +0900 |
|---|---|---|
| committer | tanaka takashi <isazaka@gmail.com> | 2026-08-11 00:04:36 +0900 |
| commit | d5b3cb20c6dacd31bb54c52a30a0f64487e30215 (patch) | |
| tree | 1461ed9f6c3ad42488485045f7295f391928e7b7 /doc | |
| parent | e8b625e22f343d75e1b50d1634b4ab06899d060b (diff) | |
feat: P1 tool improvements and P5 Agent Skills standard compliance
P1: Tool小改善
1. tailバイナリ判定 (TextFileDetector):
- file_search tailモードでtext/binary判定を追加
- 先頭4KBのみ読み、BOM確認(UTF-8/UTF-16 LE/BE)→UTF-8 strict byte検証
- NULバイトのみ判定不可(UTF-16でNULが正常出現するため)
- binaryファイルはToolValidationExceptionで拒否
- TextFileDetectorクラスへ判定ロジックを分離
2. file_edit rename機能:
- file_edit.operation=renameを追加(新規toolではない)
- new_path property追加、Write capability要求(source/destination双方)
- destination既存時は禁止(overwrite不可)
- cross-volume renameは不支持、Tool failureとして拒否
- FileRenameTransaction + RecoveryManager file.rename recovery追加
- crash recovery: destination hash == journal記録の場合のみ戻す
P5: Agent Skills open standard準拠
3. Skill形式をagentskills.io標準へ移行:
- legacy単一Markdown形式(skills/*.md)を廃止
- <skill-name>/SKILL.md標準directory形式のみ対応
- YAML frontmatter必須(name/description)、YamlDotNetで解析
- validation: name必須(1-64文字,lowercase英数字+hyphen,親dir名一致),
description必須(1-1024文字), malformed YAML reject, duplicate fatal
4. Progressive Disclosure:
- Stage 1 Discovery: name+descriptionのみをsystem messageへ(name+desc一覧)
- Stage 3 Instructions: 選択Skillの本文のみ注入
- PromptComposer: 全文埋め込みを廃止、カタログ形式へ変更
- PromptContext: Skills→AvailableSkills+SelectedSkillsへ分割
- 未選択Skill本文はpromptへ入らない
5. Internal Tool境界維持:
- skill_read等のInternal Tool追加なし
- Internal Toolは6群(file_search/file_read/file_edit/process_run/task_update/dir)のまま
- Skill選択・本文ロードはAgent Runtime/Prompt Context Managementの責務
6. AgentSkill data model (Agent.Core/Skills/AgentSkill.cs):
- RootPath, Name, Description, Instructions, License?, Compatibility?, Metadata?, AllowedTools?
- SkillLoader(Agent.App)がYamlDotNetでfrontmatter解析→AgentSkill構築
設計判断:
- renameはfile_edit operation拡張(新規toolではない)
- rmdir空dirのみ制約は維持
- Skill load != permission grant維持
- allowed-toolsはSandbox permissionとして解釈しない
- YamlDotNetはAgent.App側のみ使用(Agent.Coreへ依存追加なし)
変更対象:
- TextFileDetector.cs: 新規、text/binary判定
- WindowsToolBackend.cs: tail binary判定統合、rename case追加
- InternalToolCatalog.cs: file_edit operation enum に rename 追加、new_path property
- InternalToolValidator.cs: rename時new_path必須検証
- TransactionalFileEditor.cs: Rename() + FileRenameTransaction
- RecoveryManager.cs: file.rename recovery
- AgentSkill.cs: 新規data model
- SkillLoader.cs: 全面書き換え、YamlDotNet frontmatter解析、validation
- PromptComposer.cs: Progressive Disclosure、AvailableSkills+SelectedSkills
- AgentRuntimeSettings.cs: Skills型変更
- AgentRuntime.cs: SelectedSkills=[]で初期化
- Program.cs: SkillLoader戻り値型対応
- Specifications.md: FS-07 rename、Skill節Agent Skills standard準拠
- Design.md: §7.1 tail binary判定、§7.3 rename、AgentSkill model
- ImplementationPlan.md: Prompt順序更新、Skill標準準拠
テスト:
- SecurityPolicyTests.cs: tail binary拒否/UTF-8/UTF-16 text許可、rename正常/dest既存拒否/許可外拒否
- InternalToolTests.cs: rename validationテスト追加
- ConfigurationTests.cs: SkillLoader標準形式/missing frontmatter/name mismatch/duplicate tests
- PromptAndRuntimeTests.cs: PromptContext型変更対応、skill catalog検証
検証結果:
- Release build: 警告0、エラー0
- Core tests: 61/61 PASS、skip 0
- Planner tests: 10/10 PASS、skip 0
- Internal Tool 6群固定: 確認済み
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Design.md | 12 | ||||
| -rw-r--r-- | doc/Specifications.md | 15 |
2 files changed, 19 insertions, 8 deletions
diff --git a/doc/Design.md b/doc/Design.md index 101a896..31d0247 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -265,7 +265,7 @@ Ollamaに公開するInternal Toolは次の6群に固定する。個々のOS com {"root":"string","mode":"glob|name|text|regex|tail","query":"string","max_results":100,"tail_lines":100} ``` - `root`はread許可directory/file配下でなければdeny。 -- `tail`はtext file向け。binaryは拒否する。 +- `tail`はtext file向け。binaryは拒否する。判定は先頭4 KiBのみを読み、BOM確認(UTF-8/UTF-16 LE/UTF-16 BE)→BOMなしはUTF-8 strict byte sequence検証で行う。NULバイトのみの判定はUTF-16 textを誤拒否するため使用しない。 - `max_results`にhard upper boundを設け、context爆発を防ぐ。 - `max_results`のhard upper boundは1,000件、`tail_lines`は10,000行とする。 ### 7.2 file_read @@ -279,14 +279,17 @@ Ollamaに公開するInternal Toolは次の6群に固定する。個々のOS com ```json { "path":"string", - "operation":"overwrite|patch|atomic_replace|delete", + "operation":"overwrite|patch|atomic_replace|delete|rename", "content":"string|null", "patch":"string|null", - "expected_sha256":"string|null" + "expected_sha256":"string|null", + "new_path":"string|null" } ``` - overwrite/patch/atomic_replaceはwrite permissionを要求する。 - deleteはdelete permissionを要求する。 +- renameはsource/destination双方にwrite permissionを要求する。destinationが既に存在する場合は拒否する(overwrite不可)。cross-volume renameは不支持でTool failureとして返す。 +- rename transaction: PREPARE(source/destination検査+journal) → APPLY(File.Move) → VERIFY(source不存在/destination存在/hash一致) → COMMIT。crash recoveryはdestination hashがjournal記録と一致する場合のみdestinationからsourceへ戻す。 - `expected_sha256` 指定時はoptimistic concurrency guardとして利用する。 ### 7.4 process_run ```json @@ -379,7 +382,7 @@ AgentSession 1. Fixed System Prompt 2. User System Prompt 3. locale instruction -4. selected Skills +4. selected Skills (name + description一覧のみ、Progressive Disclosure Stage 1) 5. Sandbox capability summary 6. current TaskGraph / current Task 7. previous Summary @@ -829,6 +832,7 @@ errorは内部codeとlocalized messageを分離し、ログ/auditにはcode、MC - `AuditEvent` - `LanguageContext` - `SkillDescriptor` +- `AgentSkill` - `ToolCallRecord` ## 29. 実装レビュー用チェックリスト - [ ] public MCP toolは2個だけか。 diff --git a/doc/Specifications.md b/doc/Specifications.md index 5d21037..007ce51 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -310,10 +310,16 @@ Context要約を開始する利用率閾値は設定可能でなければならã ### 10.2 Skill -- SkillはMarkdown instructionである。 -- Skillロードは権限付与を意味しない。 -- 必要なSkillだけを選択する。 -- Skill選択はLLMにより行うが、選択可能集合は設定されたSkill directoryに限定する。 +- Agent Skills open standard (agentskills.io) に準拠する。 +- Skill directory構造は `<skill-name>/SKILL.md` のみを扱う。legacy単一Markdown形式は廃止する。 +- `SKILL.md` はYAML frontmatter + Markdown bodyで構成し、`name` (1-64文字、lowercase英数字+hyphen、親directory名と一致) と `description` (1-1024文字) を必須とする。 +- frontmatterなしのSkillは推測せずrejectする。malformed YAML、duplicate skill nameは起動/check時fatalとする。 +- Progressive Disclosure: Stage 1 Discovery (name + descriptionのみ) → Stage 2 Selection (LLM) → Stage 3 Instructions Load (選択SKILL.md本文) → Stage 4 Resources (scripts/references/assets)。 +- Skill選択はLLMにより行う。選択可能集合は設定されたSkill directoryに限定する。Runtimeは選択結果を検証し、unknown Skill名を読み込まない。 +- Skillロードは権限付与を意味しない。`allowed-tools` metadataはSandbox permissionとして解釈しない。 +- Skillに `scripts/` が含まれていても自動実行許可しない。実行には通常どおりFilesystem execute capability、Process Approval、path + SHA-256、Sandbox Brokerを必須とする。 +- Skill directory内resourceについてcanonicalization、reparse point検査、Skill root外へのescape禁止を行う。 +- Skill選択・本文ロードはInternal Toolとして公開せず、Agent Runtime / Prompt Context Managementの責務として実装する。Internal Toolは既存5群+dir=6群に固定する。 --- @@ -344,6 +350,7 @@ Context要約を開始する利用率閾値は設定可能でなければならã | FS-04 | write権限だけではdeleteできない。 | | FS-05 | ACLとAppContainerの両方で強制可能な形にする。 | | FS-06 | ディレクトリ作成 (mkdir) はwrite権限で許可する。ディレクトリ削除 (rmdir) はdelete権限で許可するが、空ディレクトリのみとする。ディレクトリ列挙 (list) はread権限で許可する。 | +| FS-07 | renameはsource/destination双方にwrite権限を要求する。destination既存時は拒否する。cross-volume renameは不支持とする。 | ### 11.3 Process Policy |
