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

Merge remote-tracking branch 'origin/master' into worktree/context-source-cards

Browse Source 
# Conflicts:
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	packages/skill/tool-skill/README.i18n.yaml
This commit is contained in:
creatixchu
2026-08-05 14:11:29 +08:00
parent 340c9ba576 61e46f077e
commit e6293785bc
1062 changed files with 4994 additions and 3630 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/skill/README.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/skill/README.md
README.md: 4fb41dda5d9f001f5d7c47a29f7743291c0b0822
README.zh.md: 5981173d05e74e0576e83f4f0ec42894050675cf
README.zh.md: ebe9ca40a5967d3167bee9f30ba3d3e9c417f636

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

@@ -2,7 +2,7 @@
[English](README.md) | 中文
可复用 agent（智能体）指令的规范能力 seam 由三个包（package）组成：提供方注册表、本地实现，以及面向模型的目录／loader 消费方。全部均为**产品**包。
可复用 agent（智能体）指令的规范能力 seam 由三个包组成：提供方注册表、本地实现，以及面向模型的目录／loader 消费方。全部均为**产品**包。
| 包 | 职责 | ctx 键 |
|---|---|---|

2
packages/skill/skill-local/README.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/skill/skill-local/README.md
README.md: f85cc2e6fd0c32cb88f28a2914a03e22b3a20657
README.zh.md: 73a66831ad14b7edb346227cf6adb52ec8247fd7
README.zh.md: 9ee09938737237df9e97e517c1dd44b511b7f596

12
packages/skill/skill-local/README.zh.md
View File

@@ -4,7 +4,7 @@
`ctx.skills` 注册表的本地文件系统提供方。
该包（package）实现一个 skill（技能）来源。它扫描本地项目、自定义和用户 skill 根目录，解析 `SKILL.md` 或平铺 Markdown skill 文件，并将提供方注册到 `ctx.skills`。注册表仍位于 `@deepseek-ai/dsh-skill`；持久会话目录和面向模型的 loader 工具仍位于 `@deepseek-ai/dsh-tool-skill`。
该包实现一个 skill（技能）来源。它扫描本地项目、自定义和用户 skill 根目录，解析 `SKILL.md` 或平铺 Markdown skill 文件，并将提供方注册到 `ctx.skills`。注册表仍位于 `@deepseek-ai/dsh-skill`；持久化会话目录和面向模型的 loader 工具仍位于 `@deepseek-ai/dsh-tool-skill`。
## 插件
@@ -38,9 +38,9 @@
| 400 | `user-dsh` | `<dshHome>/skills` |
| 500 | `user-agents` | `<agentsHome>/skills` |
项目根目录是包含 `.git` 的最近祖先目录；如果不存在，则使用当前 cwd。用户 DSH 根目录会跳过其 `.system` 子目录，因此归系统所有的目录不会被当作普通用户 skill。`includeDefaultRoots: false` 会省略项目根、用户根以及 `$DSH_BUNDLED_SKILL_DIR` 环境默认值，同时保留显式配置的自定义根与 bundled 根，因此可以挂载多个只看到自身根的唯一命名隔离提供方，例如不可变 repository Plugin。该提供方提供项目和用户 skill；其他提供方可提供内置系统 skill。
项目根目录是包含 `.git` 的最近祖先目录；如果不存在，则使用当前 cwd。用户 DSH 根目录会跳过其 `.system` 子目录，因此归系统所有的目录不会被当作普通用户 skill。`includeDefaultRoots: false` 会省略项目根、用户根以及 `$DSH_BUNDLED_SKILL_DIR` 环境默认值，同时保留显式配置的自定义根与 bundled 根，因此可以挂载多个只看到自身根的唯一命名隔离提供方，例如不可变的仓库插件。该提供方提供项目和用户 skill；其他提供方可提供内置系统 skill。
当 `ctx.fs` 可用时，发现通过 `ctx.fs.listDir` 列出根，通过 `ctx.fs.readText` 读取 skill 文件，并通过文件系统服务探测 `.git`。完整 skill 加载会将查找中止信号转发给文件系统元数据和内容读取。如果没有文件系统服务，提供方回退到可中止的 Node 文件系统 I/O，使最小本地上下文仍能加载 skill。已确认缺失的路径属于有效空状态；格式错误或非文本条目会警告并跳过；意外的发现或读取失败会使注册表快照不完整，系统不会因此用看似发生删除的结果替换上一份可用模型目录。
当 `ctx.fs` 可用时，发现通过 `ctx.fs.listDir` 列出根，通过 `ctx.fs.readText` 读取 skill 文件，并通过文件系统服务探测 `.git`。完整 skill 加载会将查找中止信号转发给文件系统元数据和内容读取。如果没有文件系统服务，提供方回退到可中止的 Node 文件系统 I/O，使最小本地上下文仍能加载 skill。已确认缺失的路径属于有效空状态；遇到格式错误或非文本条目时，提供方会发出警告并跳过；意外的发现或读取失败会使注册表快照不完整，系统不会因此用看似发生删除的结果替换上一份可用模型目录。
## 目录变更检测
@@ -50,9 +50,9 @@
如果第一方文件系统 `write` 和 `edit` 工具的目标可能影响受监视的 skill 条目，它们还会通过 `fs/observed` 同步使提供方失效。这条快速路径让模型的下一个步骤无需等待宿主 watcher，即可观察到自身的文件系统变更。外部 IDE、Git、shell 和进程产生的变更依赖 Chokidar 或缺失路径探测。watcher 启动或运行时失败会被记录并触发重试。发现过程仍会扫描可读根目录，并返回其候选项供直接加载，但会将观测标记为不完整，因此不会缓存，也不会作为权威模型目录发布。effect 释放会关闭所有 watcher，并收束延迟回调。
## Skill 格式
## skill 格式
Skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。v1 刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方目前解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。v1 刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方目前解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
这两个调用字段接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`。`disable-model-invocation: true` 会从面向模型的目录和 loader 中排除该 skill；`user-invocable: false` 会从面向用户的命令中排除该 skill。每个省略的字段都默认为允许对应接口调用；提供方始终输出两个正向内部策略值，即使两个键都不存在也不例外。若使用驼峰拼写或提供非布尔调用值，系统会记录警告并从发现结果中排除整个 skill，而不是只丢弃该字段或回退到宽松的默认值。调用策略校验遵循失败时默认拒绝原则，因为忽略无效数据可能会在已禁用的接口上暴露 skill；类型错误的可选 `whenToUse` 和 `metadata` 值则会被省略，因为这两个字段目前都不授予调用权限。
@@ -64,7 +64,7 @@ Skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 M
#### KV Cache 影响
watcher 触发的失效可促使指定的消费方在现有请求历史中追加替换目录。仅涉及正文的编辑不会改变目录 digest。
watcher 触发的失效可促使上述消费方在现有请求历史中追加替换目录。仅涉及正文的编辑不会改变目录 digest。
## 已知限制与暂缓事项

2
packages/skill/skill/README.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/skill/skill/README.md
README.md: f538ae668ccff291be86348627d5547150f460df
README.zh.md: 8a44f684ea4d9519a0af7866d272a8e7834aeda6
README.zh.md: d61a242d01df1e22270c1cb049b922536654bbd6

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

@@ -4,7 +4,7 @@
纯 agent skill（智能体技能）提供方注册表。
该包（package）负责 `ctx.skills` 接口。它不知道 skill 来自本地文件、嵌入式插件数据、HTTP 还是其他后端；提供方通过 `ctx.skills.registerProvider(...)` 注册这些来源。已发布的本地实现是 [`@deepseek-ai/dsh-skill-local`](../skill-local)。
该包负责 `ctx.skills` 接口。它不知道 skill 来自本地文件、嵌入式插件数据、HTTP 还是其他后端；提供方通过 `ctx.skills.registerProvider(...)` 注册这些来源。已发布的本地实现是 [`@deepseek-ai/dsh-skill-local`](../skill-local)。
## 服务：`SkillService`（ctx 键：`skills`）

2
packages/skill/tool-skill/README.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
README.md: deccda0ece1ffe2cbdb576a8af3801f28695d8d5
README.zh.md: 67ec0d32759c5768af32b5a505e7a080e19eb396
README.zh.md: eaf442d9e123a2d56bf09abd9faab47a001e01b9

6
packages/skill/tool-skill/README.zh.md
View File

@@ -14,7 +14,7 @@
如果最初没有模型可调用 skill，则省略目录；如果该 agent（智能体）的工具视图排除了随附的 `skill` 工具，或解析出同名的作用域内遮蔽项，也会省略目录。可见性变更参与 digest 计算，使提示词指引、模型可见 schema 和可执行分派保持对齐。
`catalogDescriptionMaxLength` 控制规范化且经 XML 转义的目录描述。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。[skill 目录热刷新 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) 负责定义持久初始目录和替换目录的生命周期。
`catalogDescriptionMaxLength` 控制规范化且经 XML 转义的目录描述。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。[skill 目录热刷新 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) 负责定义持久初始目录和替换目录的生命周期。
## 工具：`skill`
@@ -128,7 +128,7 @@ Load referenced resources only as needed.
#### KV Cache 影响
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV-cache 条目失效。
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
### 工具错误
@@ -142,7 +142,7 @@ Load referenced resources only as needed.
#### KV Cache 影响
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV-cache 条目失效。
仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
## 已知限制与暂缓事项

18
packages/skill/tool-skill/tests/tool-skill.spec.ts
View File

@@ -38,7 +38,7 @@ async function setup(home: string, config: toolSkill.Config = {}): Promise<Conte
function agentForCwd(cwd: string): Agent {
const id = SessionId(`tool-skill-${cwd}`)
const session = new Session(id, [], { version: 0, id, createdAt: 0, cwd })
const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
return {
ctx: new Context(),
id,
@@ -291,7 +291,7 @@ describe('dsh-tool-skill', () => {
invalidate = control.invalidate
return provider
})
const session = new Session(SessionId('incomplete-prefix'))
const session = Session.create(SessionId('incomplete-prefix'))
const agent = sessionAgent(session)
openMessageTurn(session)
@@ -307,7 +307,7 @@ describe('dsh-tool-skill', () => {
it('records an empty baseline across repeated step observations', async () => {
const home = await tempDir('tool-empty-step')
const ctx = await setup(home)
const session = new Session(SessionId('empty-step'))
const session = Session.create(SessionId('empty-step'))
const agent = sessionAgent(session)
openMessageTurn(session)
@@ -326,7 +326,7 @@ describe('dsh-tool-skill', () => {
source: 'runtime',
content: 'First body.',
})
const session = new Session(SessionId('dynamic-catalog'))
const session = Session.create(SessionId('dynamic-catalog'))
const agent = sessionAgent(session)
openMessageTurn(session)
@@ -375,7 +375,7 @@ describe('dsh-tool-skill', () => {
source: 'runtime',
content: 'Resumed body.',
})
const session = new Session(SessionId('catalog-resume'))
const session = Session.create(SessionId('catalog-resume'))
const agent = sessionAgent(session)
openMessageTurn(session)
session.append('user/message', createUserMessage({
@@ -420,7 +420,7 @@ describe('dsh-tool-skill', () => {
source: 'runtime',
content: 'First body.',
})
const session = new Session(SessionId('catalog-compaction'))
const session = Session.create(SessionId('catalog-compaction'))
const agent = sessionAgent(session)
openMessageTurn(session)
expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('first-skill')
@@ -445,7 +445,7 @@ describe('dsh-tool-skill', () => {
const root = join(home, '.dsh/skills')
await writeSkill(root, 'body-skill', 'Stable description', 'First body.')
const ctx = await setup(home)
const session = new Session(SessionId('body-refresh'))
const session = Session.create(SessionId('body-refresh'))
const agent = sessionAgent(session)
openMessageTurn(session)
@@ -475,7 +475,7 @@ describe('dsh-tool-skill', () => {
source: 'runtime',
content: 'Stable body.',
})
const session = new Session(SessionId('incomplete-catalog'))
const session = Session.create(SessionId('incomplete-catalog'))
const agent = sessionAgent(session)
openMessageTurn(session)
expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('stable-skill')
@@ -499,7 +499,7 @@ describe('dsh-tool-skill', () => {
const home = await tempDir('tool-restricted-catalog')
const ctx = await setup(home)
ctx.skills.register({ name: 'listed-skill', description: 'Listed', source: 'runtime', content: 'body' })
const session = new Session(SessionId('restricted-catalog'))
const session = Session.create(SessionId('restricted-catalog'))
const agent = sessionAgent(session)
openMessageTurn(session)
const { scope } = await mintAgentScope(ctx, agent)