Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document package KV cache effects

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-19 17:39:50 +08:00
parent b3c4b732d8
commit bcc920369c
93 changed files with 366 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/skill/skill-local/README.md
View File

@@ -40,6 +40,8 @@ Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdow
Indirectly, through `dsh-tool-skill`, which renders this provider's invocable names and capped descriptions into the session-prefix catalog and a selected instruction body plus resource-base guidance into retained tool history while paths, provider ranks, and disabled skills remain hidden.
**KV Cache effect**: No direct invalidation; the named consumer owns any request-prefix changes.
## Known Limitations and Deferred Work
- **Discovery is one level deep** — only `<root>/<name>/SKILL.md` and `<root>/<name>.md` are recognized; nested skill trees and package manifests are ignored.

2
packages/skill/skill/README.md
View File

@@ -39,6 +39,8 @@ The registry does not render model guidance or register model-facing tools. [`@d
Indirectly, through `dsh-tool-skill`, which renders provider summaries into the session prefix and loaded instructions into retained tool results.
**KV Cache effect**: No direct invalidation; the named consumer owns any request-prefix changes.
## Known Limitations and Deferred Work
- **Completed catalogs have no TTL or watcher invalidation** — a provider's underlying files or remote data can change without a registration revision, so a cached cwd stays stale until eviction or provider/runtime reload.

8
packages/skill/tool-skill/README.md
View File

@@ -32,6 +32,8 @@ The tool does not call `agent.inject()` in v1. Its result is already recorded as
**Token effect**: Repeated input cost scales with skill count and `catalogDescriptionMaxLength`; no catalog tokens are sent when the list is empty or the tool is hidden or shadowed.
**KV Cache effect**: Prefix-stable within a loop instance once the session prefix is composed. A new or resumed instance with different providers, skills, descriptions, visibility, or catalog limits may invalidate reuse from the first changed catalog token.
#### Skill catalog template
```markdown
@@ -52,12 +54,16 @@ If the user names a skill, or the task clearly matches a skill's description, ca
**Token effect**: Fixed schema cost per request where the tool is visible.
**KV Cache effect**: Prefix-stable while the tool definition and visibility are unchanged. Shadowing, restrictions, or plugin lifecycle changes may invalidate reuse from this schema.
### Tool result
**What the model sees**: A successful call uses the result template and the provider-managed, directory, URL, or opaque resource guidance below.
**Token effect**: Loaded instructions are data-dependent tool-result tokens, resent on later steps until compaction; no duplicate `agent.inject()` copy is made.
**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
#### Skill result template
```markdown
@@ -106,6 +112,8 @@ Load referenced resources only as needed.
**Token effect**: Only a failing call adds these retained tokens.
**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
## Known Limitations and Deferred Work
- **The catalog omits `whenToUse`, source, and provider metadata** — routing is based only on name and a capped description; `whenToUse` remains provider metadata and is not rendered by the loaded wrapper either.