Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine
# Conflicts: # packages/context/workspace-context/README.md # packages/llm/llm-retry/README.md # packages/session-persistence/session-checkpoint-policy/README.md # scripts/type-equiv.manifest.json
This commit is contained in:
_Kerman
6
packages/skill/README.i18n.yaml
Normal file
6
packages/skill/README.i18n.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
README.md: 5c75661de17826e7ea4763e90b494e9e7a0a7c0f
|
||||
README.zh.md: d219f710c0185298af89ba2e074d9e3b2e093896
|
||||
@@ -1,5 +1,7 @@
|
||||
# skill/ - skill capability family
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
The canonical three-package capability seam for reusable agent instructions: a provider registry, a local implementation, and the model-facing catalog/loader consumer. All are **product** packages.
|
||||
|
||||
| Package | Role | ctx key |
|
||||
|
||||
13
packages/skill/README.zh.md
Normal file
13
packages/skill/README.zh.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# skill/ - skill 功能家族
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
可复用 agent 指令的规范三包功能 seam：提供方注册表、本地实现，以及面向模型的目录/加载器消费方。全部都是**产品** 包。
|
||||
|
||||
| 包 | 职责 | ctx 键 |
|
||||
|---|---|---|
|
||||
| `skill/` | 提供方注册表、优先级解析、稳定目录快照和完整定义查找 | `ctx.skills` |
|
||||
| `skill-local/` | 项目/自定义/用户文件系统提供方 | （注册到 `ctx.skills`） |
|
||||
| `tool-skill/` | 会话前缀目录和面向模型的 `skill` 加载器 | （注册到 `ctx.tools`） |
|
||||
|
||||
接口位于 `skill/skill/`。提供方同步注册，并通过 `ctx.skills` 执行异步发现；`tool-skill` 只消费该接口，因此嵌入式或远程提供方可替换或补充 `skill-local`，无需改变面向模型的契约。`agent-core` 默认加载该家族，但它仍然是核心控制主干之外的功能，与 [`bash/`](../bash/README.md)、[`fs/`](../fs/README.md)、[`web/`](../web/README.md) 和 [`subagent/`](../subagent/README.md) 并列。
|
||||
6
packages/skill/skill-local/README.i18n.yaml
Normal file
6
packages/skill/skill-local/README.i18n.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
README.md: c488fdc4b1d97b5aa1113e41a470484063526ded
|
||||
README.zh.md: 796c814a3c4064d545a966465caf6f99e9dd8601
|
||||
@@ -1,5 +1,7 @@
|
||||
# @deepseek-ai/dsh-skill-local
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Local filesystem provider for the `ctx.skills` registry.
|
||||
|
||||
This package implements one skill source. It scans local project, custom, and user skill roots, parses `SKILL.md` or flat Markdown skill files, and registers the provider on `ctx.skills`. The registry remains in `@deepseek-ai/dsh-skill`; the session-prefix catalog and model-facing loader tool remain in `@deepseek-ai/dsh-tool-skill`.
|
||||
|
||||
54
packages/skill/skill-local/README.zh.md
Normal file
54
packages/skill/skill-local/README.zh.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# @deepseek-ai/dsh-skill-local
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
`ctx.skills` 注册表的本地文件系统提供方。
|
||||
|
||||
该包实现一个 skill 来源。它扫描本地项目、自定义和用户 skill 根，解析 `SKILL.md` 或平铺 Markdown skill 文件，并将提供方注册到 `ctx.skills`。注册表仍位于 `@deepseek-ai/dsh-skill`；会话前缀目录和面向模型的加载器工具仍位于 `@deepseek-ai/dsh-tool-skill`。
|
||||
|
||||
## 插件
|
||||
|
||||
需要 `ctx.skills` （`inject: ['skills']`）。
|
||||
|
||||
### 配置
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
|---|---|---|
|
||||
| `dshHome` | `$DSH_HOME` or `~/.dsh` | 由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析的 DeepSeek Harness 配置根；扫描该目录下的 `skills`。 |
|
||||
| `agentsHome` | `$DSH_AGENTS_HOME` or `~/.agents` | 为兼容 skill 扫描的共享 agent 配置根。 |
|
||||
| `customSkillDirs` | `[]` | 在项目根之后、用户根之前扫描的其他本地 skill 根。 |
|
||||
|
||||
## 发现
|
||||
|
||||
默认根按该提供方的 rank 顺序解析：
|
||||
|
||||
| Rank | 来源 | 路径 |
|
||||
|---|---|---|
|
||||
| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
|
||||
| 200 | `project-agents` | `<projectRoot>/.agents/skills` |
|
||||
| 300 | `custom` | `Config.customSkillDirs` |
|
||||
| 400 | `user-dsh` | `<dshHome>/skills` |
|
||||
| 500 | `user-agents` | `<agentsHome>/skills` |
|
||||
|
||||
项目根是包含 `.git` 的最近祖先；如果不存在，则使用当前 cwd。用户 DSH 根会跳过其 `.system` 子级，因此系统所有目录不会被当作普通用户 skill。该提供方提供项目和用户 skill；其他提供方可提供内置系统 skill。
|
||||
|
||||
当 `ctx.fs` 可用时，发现通过 `ctx.fs.listDir` 列出根，通过 `ctx.fs.readText` 读取 skill 文件，并通过文件系统服务探测 `.git`。完整 skill 加载会将查找中止信号转发给文件系统元数据和内容读取。如果没有文件系统服务，提供方回退到可中止的 Node 文件系统 I/O，使最小本地上下文仍能加载 skill。缺失、不可读或格式错误的 skill 文件会警告并跳过，而不会使整个请求失败。
|
||||
|
||||
## Skill 格式
|
||||
|
||||
Skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。v1 刻意不包含嵌套 `**/SKILL.md` 发现。Frontmatter 使用 `yaml` 包解析为 YAML；它要求 `name` 和 `description`，而 `whenToUse`、`disableModelInvocation` 和 `metadata` 可选。名称必须使用 kebab-case。
|
||||
|
||||
## 模型体验
|
||||
|
||||
通过 `dsh-tool-skill` 间接影响模型。它将该提供方的可调用名称和有上限描述渲染到会话前缀目录中，并将所选指令正文与资源基底指引渲染到已保留工具历史中；路径、提供方 rank 和已禁用 skill 仍被隐藏。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。
|
||||
|
||||
## 已知限制与待完成工作
|
||||
|
||||
- **发现深度为一层**：只识别 `<root>/<name>/SKILL.md` 和 `<root>/<name>.md`；忽略嵌套 skill 树和包 manifest。
|
||||
- **项目范围为最近 `.git` 祖先**：没有该标记的工作区回退到提供的 cwd，不支持其他项目根标记或 monorepo 子项目选择。
|
||||
- **不可读或格式错误的条目会随警告消失**：模型目录不会收到每个 skill 的诊断，无法区分缺失的 skill 与被跳过的 skill。
|
||||
- **无文件系统 watcher**：先前已收集 cwd 重新发现之前，编辑操作依赖注册表缓存被驱逐，或因提供方重新加载而失效。
|
||||
6
packages/skill/skill/README.i18n.yaml
Normal file
6
packages/skill/skill/README.i18n.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
README.md: 639616d0b75f960e9ccd48546d44db841372bbe2
|
||||
README.zh.md: 3afdd415397927ebf107d6f862422c711a51888b
|
||||
@@ -1,5 +1,7 @@
|
||||
# @deepseek-ai/dsh-skill
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Pure agent skill provider registry.
|
||||
|
||||
This package owns the `ctx.skills` interface. It does not know whether skills come from local files, embedded plugin data, HTTP, or another backend; providers register those sources with `ctx.skills.registerProvider(...)`. The shipped local implementation is [`@deepseek-ai/dsh-skill-local`](../skill-local).
|
||||
|
||||
53
packages/skill/skill/README.zh.md
Normal file
53
packages/skill/skill/README.zh.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# @deepseek-ai/dsh-skill
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
纯 agent skill 提供方注册表。
|
||||
|
||||
该包负责 `ctx.skills` 接口。它不知道 skill 来自本地文件、嵌入式插件数据、HTTP 还是其他后端；提供方通过 `ctx.skills.registerProvider(...)` 注册这些来源。已发布的本地实现是 [`@deepseek-ai/dsh-skill-local`](../skill-local)。
|
||||
|
||||
## 服务：`SkillService`（ctx 键：`skills`）
|
||||
|
||||
### 公开 API
|
||||
|
||||
- `ctx.skills.registerProvider(provider): () => void` 使用唯一 `provider.name` 注册只读提供方。重复提供方名称会抛错，`runtime` 保留给 `ctx.skills.register(...)`。注册表借用提供方对象，并直接调用其方法。注册作用域绑定到 effect，可安全用于 HMR；精确的 Cordis disposer 支持有序组合拆卸。
|
||||
- `ctx.skills.list({ cwd?, signal? })` 借用只读查找选项，然后返回当前工作区中模型可调用的摘要；这些摘要跨提供方合并，并按名称排序。
|
||||
- `ctx.skills.get(name, { cwd?, signal? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后将其返回，包括已对模型禁用的 skill。
|
||||
- `ctx.skills.register(skill): () => void` 注册只读运行时嵌入式 skill，省略时添加 `provider: "runtime"`。同名运行时注册使用先到先得：重复项会记录警告，并获得无操作 disposer。成功注册会返回精确的 Cordis disposer，以供有序组合拆卸。
|
||||
|
||||
### 配置
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
|---|---|---|
|
||||
| `collectCacheMaxEntries` | `128` | 内存中保留的最大已完成 cwd/提供方目录数。 |
|
||||
|
||||
## 提供方契约
|
||||
|
||||
提供方同步注册，并在已等待的 `list(options)` 调用中执行远程设置、身份验证和发现。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
|
||||
|
||||
注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读契约。
|
||||
|
||||
契约违反会快速失败。被拒绝的 `list()` 视为瞬时来源失败：系统记录它、跳过它，并且不缓存。只缓存已完成目录；提供方或运行时修订变更会丢弃正在进行的结果并重试。重复名称按 rank、提供方注册顺序，然后按提供方本地顺序解析。摘要按 skill 名称排序。
|
||||
|
||||
## 运行时 Skill
|
||||
|
||||
`ctx.skills.register(...)` 是嵌入式运行时 skill 的便利接口。运行时 skill 使用 rank `250`：项目提供方可覆盖它们，它们则覆盖已发布本地提供方的自定义根和用户根。运行时定义和嵌套资源元数据均以只读方式借用；服务只实体化提供默认 `provider` 所需的顶层定义。运行时贡献内的注册使用先到先得，因此重复贡献无法通过其 disposer 移除活动项。
|
||||
|
||||
## 消费方边界
|
||||
|
||||
注册表不渲染模型指引，也不注册面向模型的工具。[`@deepseek-ai/dsh-tool-skill`](../tool-skill) 消费 `ctx.skills` 以提供会话前缀目录和 `skill` 工具，因此提供方仍与模型接口独立。
|
||||
|
||||
## 模型体验
|
||||
|
||||
通过 `dsh-tool-skill` 间接影响模型；该包将提供方摘要渲染到会话前缀中，并将已加载指令渲染到已保留工具结果中。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。
|
||||
|
||||
## 已知限制与待完成工作
|
||||
|
||||
- **已完成目录没有 TTL 或 watcher 失效机制**：提供方的底层文件或远程数据可在注册修订不变的情况下更改，因此已缓存 cwd 会保持陈旧，直到被驱逐或重新加载提供方/运行时。
|
||||
- **提供方依次查询**：一个缓慢的协作提供方会延迟之后注册的所有提供方；取消会停止调用方等待，但无法终止不协作提供方持续运行的工作。
|
||||
- **提供方列表失败会移除该请求的整个来源**：注册表会记录并跳过它，不提供模型可见诊断或部分目录恢复契约。
|
||||
- **重复解析使用先到先得**：系统会记录并隐藏较晚出现的低优先级候选项；不提供检查全部被遮蔽定义的 API。
|
||||
6
packages/skill/tool-skill/README.i18n.yaml
Normal file
6
packages/skill/tool-skill/README.i18n.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
README.md: 6b0af04a15bfda985be3e04868f18b9af702eae7
|
||||
README.zh.md: 4ca0ccd7734848d5774e92910e916bdf71c88c13
|
||||
@@ -1,5 +1,7 @@
|
||||
# @deepseek-ai/dsh-tool-skill
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
The model-facing skill catalog and `skill` tool.
|
||||
|
||||
Requires `ctx.tools` and `ctx.skills` (`inject: ['tools', 'skills']`).
|
||||
|
||||
148
packages/skill/tool-skill/README.zh.md
Normal file
148
packages/skill/tool-skill/README.zh.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# @deepseek-ai/dsh-tool-skill
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
面向模型的 skill 目录和 `skill` 工具。
|
||||
|
||||
需要 `ctx.tools` 和 `ctx.skills` （`inject: ['tools', 'skills']`）。
|
||||
|
||||
## 会话目录
|
||||
|
||||
该插件在实时会话的第一个 `agent/step` 注入一条持久的用户角色 `<system-reminder>` 目录。它为调用会话的 cwd 解析 skill，将步骤中止信号转发到发现，并只列出已排序的 `name` 和 `description` 条目；skill 正文、路径、来源、提供方和 `whenToUse` 提示仍位于目录之外。如果没有模型可调用 skill，则省略目录；如果该 agent 的工具视图排除已发布的 `skill` 工具，或解析出一个同名作用域遮蔽，也会省略目录。这项精确定义检查使提示词指引、模型可见 schema 和可执行分派保持对齐。
|
||||
|
||||
`catalogDescriptionMaxLength` 控制规范化且经 XML 转义的目录描述。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。目录是一条带来源的 `user/message`，在第一个请求前注入，并保留在普通会话历史中。
|
||||
|
||||
## 工具：`skill`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `name` | string（必填） | 可用 skill 列表中精确的 kebab-case skill 名称。 |
|
||||
|
||||
执行使用调用 agent 的 `session.header.cwd`，使工作区敏感提供方解析胜出 skill。成功调用返回规范 `{ name, provider, resourceBase?, content }`，排除目录 rank 和提供方内部机制；其 Native 渲染器产生一个文本结果，其中包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>`。
|
||||
|
||||
资源指引只会根据 `resourceBase` 解析指令显式引用的路径或 URL；脚本、参考资料和产物按需加载，结果不会列举 skill 目录。本地提供方可以提供目录，而远程或嵌入式提供方可以提供 URL 或不透明加载指引。
|
||||
|
||||
无法解析的名称会报告 skill 未知或已不可用。无效名称和 `disableModelInvocation: true` skill 产生不同的错误结果。
|
||||
|
||||
该工具在 v1 中不调用 `agent.inject()`。其结果已作为工具结果记录，并在下一个模型步骤可用，无需将内容重复为合成上下文。
|
||||
|
||||
## 模型体验
|
||||
|
||||
### 会话目录
|
||||
|
||||
#### 模型所见
|
||||
|
||||
如果存在模型可调用 skill，且该精确 `skill` 工具可见，agent 会收到下方目录模板，其中包含每个已排序 skill 的一条数据依赖条目。该目录是一条持久的用户角色消息。
|
||||
|
||||
##### Skill 目录模板
|
||||
|
||||
```markdown
|
||||
<system-reminder>
|
||||
A skill is a reusable set of task-specific instructions. The following skills are available in this session:
|
||||
|
||||
<available_skills>
|
||||
- `<name>`: <normalized-and-capped-description>
|
||||
</available_skills>
|
||||
|
||||
If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
|
||||
</system-reminder>
|
||||
```
|
||||
|
||||
#### Token 影响
|
||||
|
||||
重复输入成本随 skill 数量和 `catalogDescriptionMaxLength` 增长；当列表为空或工具被隐藏或遮蔽时，不会发送目录 token。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
仅追加，位于现有可重用前缀之后。如果新建或恢复的实例具有不同提供方、skill、描述、可见性或目录上限，则可能从新追加的目录位置起影响缓存重用。
|
||||
|
||||
### 工具 schema
|
||||
|
||||
#### 模型所见
|
||||
|
||||
模型会看到生成的 [`skill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-skill)。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
工具可见时，每次请求都有固定 schema 成本。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
工具定义和可见性不变时，前缀稳定。遮蔽、限制或插件生命周期变更可能从该 schema 起使重用失效。
|
||||
|
||||
### 工具结果
|
||||
|
||||
#### 模型所见
|
||||
|
||||
成功调用使用下方结果模板，以及由提供方管理、目录、URL 或不透明的资源指引。
|
||||
|
||||
##### Skill 结果模板
|
||||
|
||||
```markdown
|
||||
<skill_content name="<escaped-name>">
|
||||
<skill_resources>
|
||||
<resource-guidance>
|
||||
</skill_resources>
|
||||
|
||||
<skill_instructions>
|
||||
<provider-owned-instruction-body>
|
||||
</skill_instructions>
|
||||
</skill_content>
|
||||
```
|
||||
|
||||
##### 提供方管理的资源指引
|
||||
|
||||
```markdown
|
||||
Resources for this skill are managed by provider "<provider>".
|
||||
Load referenced resources only as needed.
|
||||
```
|
||||
|
||||
##### 目录资源指引
|
||||
|
||||
```markdown
|
||||
Base directory for this skill: <path>
|
||||
Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
|
||||
```
|
||||
|
||||
##### URL 资源指引
|
||||
|
||||
```markdown
|
||||
Base URL for this skill: <url>
|
||||
Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.
|
||||
```
|
||||
|
||||
##### 不透明资源指引
|
||||
|
||||
```markdown
|
||||
Resources for this skill: <description>
|
||||
Load referenced resources only as needed.
|
||||
```
|
||||
|
||||
#### Token 影响
|
||||
|
||||
已加载指令是取决于数据的工具结果 token，并在后续步骤中重新发送，直到压缩；不会制作重复的 `agent.inject()` 副本。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV 缓存条目失效。
|
||||
|
||||
### 工具错误
|
||||
|
||||
#### 模型所见
|
||||
|
||||
无效或陈旧选择会精确返回 `Error: invalid skill name "<name>"`、`Error: skill "<name>" is unknown or no longer available` 或 `Error: skill "<name>" is not available for model invocation`。提供方抛出的查找文本取决于数据，并接收同一个 `Error: <message>` 包装层。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
只有失败调用会添加这些已保留 token。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV 缓存条目失效。
|
||||
|
||||
## 已知限制与待完成工作
|
||||
|
||||
- **目录省略 `whenToUse`、来源和提供方元数据**：路由只基于名称和有上限描述；`whenToUse` 仍是提供方元数据，加载后的包装层也不渲染它。
|
||||
- **已加载指令正文没有大小上限**：提供方可返回足以占用大量下一步上下文的 skill；只有目录描述会被截断。
|
||||
- **资源是指引，而非附件**：工具报告基础目录/URL/不透明提示，但既不列举也不为模型获取引用文件。
|
||||
- **加载是一次性文本**：远程提供方缓慢或 skill 正文很大时，不提供部分、流式或缓存内容句柄。
|
||||
Reference in New Issue
Block a user