refactor(agent-preset): consolidate creator skills into dsh-doc (#6633)
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * feat(agent-preset): ship plugin artwork skill with creator mode * docs(skills): clarify artwork icon lookup and official review steps * refactor(agent-preset): fold plugin artwork into cordis plugin development * feat(agent-preset): require detail documents for creator bundles * test(release): expect source and maps in master's new payload cases * refactor(agent-preset): consolidate creator skills into dsh-doc * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * docs(agent-preset): add dsh-doc install, upgrade, and fallback guidance * docs(agent-preset): align dsh-doc archive reads and upgrade start versions * docs(agent-preset): bound dsh-doc upgrade index reads and test documented commands * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * docs(upgrade-guide): correct dsh-doc session verification step * test(agent-preset): use a block body for dsh-doc fixture cleanup * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * docs(agent-preset): read the running DSH version from the installation * build(release): publish source and maps from the message-quotes package * docs(agent-preset): document the verified PowerShell runtime invocation * docs(agent-preset): keep PowerShell runtime output streams and exit code * docs(tool-cordis): describe the shipped dsh-doc skill * docs(skills): load configuration guidance separately * fix(skills): declare shared template details in every locale * fix(skills): verify dsh-doc guidance through recorded sessions * test(skills): retain current runtime reminder in dsh-doc replay * test(snapshot): refresh terminal panel runtime context
This commit is contained in:
1 parent
1c63ff48be
commit
03e70034e6
106 files changed
+802
-324
No files matched your search
+6
-6
@@ -27,8 +27,8 @@
|
||||
en: 1f28c04d5002af94
|
||||
zh: 4d4dfea99fc6aee2
|
||||
/agent-note-audience-first-documentation-quality-criteria/proposal/prototype-rules:
|
||||
en: 6ee5714bc0b33cda
|
||||
zh: 587bd85f6f712868
|
||||
en: badae41417e3e3c0
|
||||
zh: 52336cb9ce2790f9
|
||||
/agent-note-audience-first-documentation-quality-criteria/proposal/criteria-by-document-job:
|
||||
en: 9abbe4f2d5038284
|
||||
zh: 45d30352d9cce4b5
|
||||
@@ -36,8 +36,8 @@
|
||||
en: 2641ca1307c3308f
|
||||
zh: 15fd0415d40a9190
|
||||
/agent-note-audience-first-documentation-quality-criteria/proposal/enforcement-slices:
|
||||
en: c2f6617cf8b3bab4
|
||||
zh: b9ad3dae2fc50ddf
|
||||
en: a8bfbf127516e617
|
||||
zh: 284843d0f0a59f58
|
||||
/agent-note-audience-first-documentation-quality-criteria/proposal/non-goals:
|
||||
en: e8633d73b0273bfd
|
||||
zh: 516e6d805158d303
|
||||
@@ -45,8 +45,8 @@
|
||||
en: 5f09627b84bf112b
|
||||
zh: b0f1845df90e5f1a
|
||||
/agent-note-audience-first-documentation-quality-criteria/acceptance-criteria:
|
||||
en: 696ff7205b3362d0
|
||||
zh: a62a50cf3ceadac6
|
||||
en: 1d3ca0cd3ed33607
|
||||
zh: 68ed7b6de42ba3aa
|
||||
/agent-note-audience-first-documentation-quality-criteria/risks:
|
||||
en: b920900d3ff05073
|
||||
zh: 05b2a0271b825260
|
||||
@@ -48,7 +48,7 @@ Adopt one audience-first quality contract with five definitions:
|
||||
|
||||
### Prototype rules
|
||||
|
||||
The [dsh-doc skill](../../../skills/dsh-doc/SKILL.md) owns the first executable version of these rules. The `session-persistence-jsonl` README pair uses the shipped append, recovery, and encoding behavior as evidence rather than treating its prior prose as authority.
|
||||
The [dsh-doc-writing skill](../../../skills/dsh-doc-writing/SKILL.md) owns the first executable version of these rules. The `session-persistence-jsonl` README pair uses the shipped append, recovery, and encoding behavior as evidence rather than treating its prior prose as authority.
|
||||
|
||||
- Every authored package README starts with searchable YAML. A Skill-style `description` and mechanically derived `kind` are required. Four kinds map one-to-one to four skill templates: `package-group` (group map), `package-reference` (plugin or service package), `package-library` (plain module entry), and `package-bundle` (`dsh.bundle.patch`). The counterpart path, hashes, and physical line alignment belong to the merge-safe sidecar and its gate, so README frontmatter contains no `i18n` block. The title or package manifest already owns the name, the document job expresses its audience, and tags remain absent until a governed taxonomy and search consumer proves value beyond full-text search.
|
||||
- Authored pages start with a three-to-five-sentence `Summary`, then a linked `Table of Contents`. An English package README Summary stays within 100 `wc -w`-style words. It describes reader-visible capability instead of Cordis roles, registrations, or internal components, and omits source identifiers unless readers use them directly in configuration, commands, or a public API. Format-owned Agent Notes, postmortems, generated fragments, and machine files keep their required skeletons.
|
||||
@@ -85,7 +85,7 @@ The first prototype should use one large catalog and one mixed subsystem page. I
|
||||
|
||||
### Enforcement slices
|
||||
|
||||
1. Create and validate `dsh-doc`, then rewrite one package README pair as a line-aligned, metadata-bearing prototype without changing runtime claims.
|
||||
1. Create and validate `dsh-doc-writing`, then rewrite one package README pair as a line-aligned, metadata-bearing prototype without changing runtime claims.
|
||||
2. Review the rendered prototype with newcomer, user, developer, and agent tasks; revise the skill before enforcing the format elsewhere.
|
||||
3. Add narrow metadata, Summary-length, section-order, line-alignment, link-resolution, and pairing fixtures. Migrate every existing package Summary that violates the accepted entry limit, and keep sidecars until every merge and recovery consumer has replacement support.
|
||||
4. Extract accepted standing rules into one canonical quality reference, condense `docs/AGENTS.md` below its target, and organize one coherent `docs/` topic at a time with atomic link/navigation repair.
|
||||
@@ -93,7 +93,7 @@ The first prototype should use one large catalog and one mixed subsystem page. I
|
||||
|
||||
This sequence keeps each change independently reviewable. The first three slices improve criteria and package entry points without changing the broader information architecture; the generated-doc prototype supplies evidence before a broader structural change.
|
||||
|
||||
Slices 1–3 have shipped in this form: `dsh-doc` is the consolidated standard (`dsh-doc-standards` and `dsh-doc-site-sync` are folded into it, and the site workflow carries the corrected sidebar values), the `session-persistence-jsonl` README pair is the reference example, and `pnpm run test:docs` enforces the metadata, pairing, and quick documentation checks. Slices 4–5 remain open.
|
||||
Slices 1–3 have shipped in this form: `dsh-doc-writing` is the consolidated standard (`dsh-doc-standards` and `dsh-doc-site-sync` are folded into it, and the site workflow carries the corrected sidebar values), the `session-persistence-jsonl` README pair is the reference example, and `pnpm run test:docs` enforces the metadata, pairing, and quick documentation checks. Slices 4–5 remain open.
|
||||
|
||||
### Non-goals
|
||||
|
||||
@@ -114,9 +114,9 @@ This proposal does not shorten exhaustive facts, merge audience tiers, publish i
|
||||
## Acceptance criteria
|
||||
|
||||
- One canonical quality reference defines brief, intuitive, friendly, accurate, and agent-readable documentation by document job.
|
||||
- `.agents/skills/dsh-doc` validates and directly links its metadata, structure/hierarchy, and review/prototype references without duplicating their detailed rules in `SKILL.md`.
|
||||
- `.agents/skills/dsh-doc-writing` validates and directly links its metadata, structure/hierarchy, and review/prototype references without duplicating their detailed rules in `SKILL.md`.
|
||||
- The `session-persistence-jsonl` README pair demonstrates searchable YAML, Summary, Table of Contents, user-to-developer progression, Further Exploration, final Dev Note, structural parity, and exact line-count equality while preserving verified package contracts.
|
||||
- Every English package README Summary stays within 100 `wc -w`-style words; the focused gate reports the measured count and directs failures to `dsh-doc` and the selected kind template.
|
||||
- Every English package README Summary stays within 100 `wc -w`-style words; the focused gate reports the measured count and directs failures to `dsh-doc-writing` and the selected kind template.
|
||||
- `docs/AGENTS.md` links that reference, remains sufficient as standing instruction, and is below its target with at least 5% headroom.
|
||||
- The root user path, Web quick start, first-plugin tutorial, contributor setup, and architecture overview each name an observable outcome and a verification owner without duplicating implementation detail.
|
||||
- The budget manifest records both target and temporary ceiling, and its check reports or rejects a violated headroom/ratchet state.
|
||||
|
||||
+5
-5
@@ -48,7 +48,7 @@ Status: proposed
|
||||
|
||||
### 原型规则
|
||||
|
||||
[dsh-doc skill](../../../skills/dsh-doc/SKILL.md) 负责这些规则的首个可执行版本。`session-persistence-jsonl` README 对以已交付的追加、恢复与编码行为为证据,而不把其旧版正文当作权威。
|
||||
[dsh-doc-writing skill](../../../skills/dsh-doc-writing/SKILL.md) 负责这些规则的首个可执行版本。`session-persistence-jsonl` README 对以已交付的追加、恢复与编码行为为证据,而不把其旧版正文当作权威。
|
||||
|
||||
- 每个撰写型包 README 都以可搜索 YAML 开头。Skill 风格的 `description` 与按机制推导的 `kind` 为必填字段。四种 kind 与四个技能模板一一对应:`package-group`(组地图)、`package-reference`(插件或服务包)、`package-library`(纯模块入口)与 `package-bundle`(`dsh.bundle.patch`)。对照文件路径、哈希与物理行对齐由支持自动合并的 sidecar 及其门禁负责,因此 README frontmatter 不包含 `i18n` 块。名称已由标题或包 manifest 归属,受众已由文档职责表达;在受治理的标签分类与搜索消费方证明其价值超过全文检索之前,不加入标签。
|
||||
- 撰写型页面先写三至五句的 `Summary`,再写带链接的 `Table of Contents`。英文包 README 的 Summary 不超过 100 个按 `wc -w` 语义统计的词。它描述读者可见能力,而不是 Cordis 角色、注册项或内部组件;除非读者会在配置、命令或公开 API 中直接使用某个源码标识符,否则不得写入该标识符。由格式约束的 Agent Note、事故复盘、生成片段和机器文件保留其必需骨架。
|
||||
@@ -85,7 +85,7 @@ Status: proposed
|
||||
|
||||
### 执行切片
|
||||
|
||||
1. 创建并验证 `dsh-doc`,再把一组 package README 对改写为行对齐、带元数据的原型,同时不改变运行时事实。
|
||||
1. 创建并验证 `dsh-doc-writing`,再把一组 package README 对改写为行对齐、带元数据的原型,同时不改变运行时事实。
|
||||
2. 用新人、用户、开发者和 agent 任务评审渲染后的原型;先修订 skill,再在其他位置强制执行该格式。
|
||||
3. 添加聚焦的元数据、Summary 长度、章节顺序、行对齐、链接解析和配对 fixture。迁移所有违反已接受入口上限的既有包 Summary;在每个合并与恢复消费方都有替代支持前,保留伴随文件。
|
||||
4. 把已接受的常驻规则提取到一份规范质量参考,将 `docs/AGENTS.md` 精简到目标以下,并且一次只组织一个内聚的 `docs/` 主题,同时原子地修复链接与导航。
|
||||
@@ -93,7 +93,7 @@ Status: proposed
|
||||
|
||||
该顺序使每项变更都能独立评审。前三个切片改进标准与包入口,而不改变更广的信息架构;生成文档原型则在更广的结构变更前提供证据。
|
||||
|
||||
切片 1–3 已按此形式交付:`dsh-doc` 成为合并后的标准(`dsh-doc-standards` 与 `dsh-doc-site-sync` 已并入其中,站点工作流携带修正后的侧边栏值),`session-persistence-jsonl` README 对是参考示例,`pnpm run test:docs` 强制执行元数据、配对与快速文档检查。切片 4–5 仍待完成。
|
||||
切片 1–3 已按此形式交付:`dsh-doc-writing` 成为合并后的标准(`dsh-doc-standards` 与 `dsh-doc-site-sync` 已并入其中,站点工作流携带修正后的侧边栏值),`session-persistence-jsonl` README 对是参考示例,`pnpm run test:docs` 强制执行元数据、配对与快速文档检查。切片 4–5 仍待完成。
|
||||
|
||||
### 非目标
|
||||
|
||||
@@ -114,9 +114,9 @@ Status: proposed
|
||||
## 验收标准
|
||||
|
||||
- 一份规范质量参考按文档职责定义简短、直观、友好、准确和便于 agent 阅读的文档。
|
||||
- `.agents/skills/dsh-doc` 通过验证,并直接链接其元数据、结构或层级及评审或原型参考,而不在 `SKILL.md` 中复制这些参考的详细规则。
|
||||
- `.agents/skills/dsh-doc-writing` 通过验证,并直接链接其元数据、结构或层级及评审或原型参考,而不在 `SKILL.md` 中复制这些参考的详细规则。
|
||||
- `session-persistence-jsonl` README 对展示可搜索 YAML、Summary、Table of Contents、从用户到开发者的渐进结构、Further Exploration、结尾 Dev Note、结构一致性和精确行数相等,同时保留已验证的包约定。
|
||||
- 每个英文包 README Summary 都不超过 100 个按 `wc -w` 语义统计的词;聚焦门禁报告实测词数,并引导失败项阅读 `dsh-doc` 与所选 kind 模板。
|
||||
- 每个英文包 README Summary 都不超过 100 个按 `wc -w` 语义统计的词;聚焦门禁报告实测词数,并引导失败项阅读 `dsh-doc-writing` 与所选 kind 模板。
|
||||
- `docs/AGENTS.md` 链接该参考,仍足以充当常驻指令,并低于其目标且至少保留 5% 余量。
|
||||
- 根级用户路径、Web 快速开始、第一个插件教程、贡献者设置和架构概览各自给出一个可观察结果与验证归属者,同时不复制实现细节。
|
||||
- 预算 manifest 同时记录目标与临时上限,其检查会报告或拒绝违反余量或棘轮规则的状态。
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
../../../packages/preset/agent-preset/skills/agent-experience/SKILL.md
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
name: agent-experience
|
||||
description: Use when writing or changing a model-facing tool definition (name, description, parameter schema, or its system-prompt section), and when designing skills, context loading, or multi-step workflows, to make information discoverable and use context efficiently.
|
||||
---
|
||||
|
||||
Read and follow [tool design](../../../packages/preset/agent-preset/skills/dsh-doc/references/tool-design.md). The `dsh-doc` skill ships that file to installed DSH, so edit the rules there.
|
||||
@@ -33,7 +33,7 @@ While the root version is unchanged, the current version directory describes the
|
||||
|
||||
## Format
|
||||
|
||||
Start from the [upgrade-guide template](../dsh-doc/templates/upgrade-guide.md). `verify-upgrade-guides` enforces:
|
||||
Start from the [upgrade-guide template](../dsh-doc-writing/templates/upgrade-guide.md). `verify-upgrade-guides` enforces:
|
||||
|
||||
- frontmatter with exactly `kind: upgrade-guide` and a one-sentence `description` naming what breaks; add a key only together with its gate check, then backfill every guide;
|
||||
- one `#` title, then exactly the `## Change` and `## Migration` sections in `guide.md`, and `## 变更` and `## 迁移` in `guide.zh.md`, in that order;
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: dsh-doc
|
||||
name: dsh-doc-writing
|
||||
description: Create, restructure, review, audit, or migrate DeepSeek Harness Markdown documentation, package READMEs, and the documentation website using audience-first hierarchy, kind-mapped YAML metadata, bilingual line alignment, summary/contents navigation, progressive user-to-developer detail, executed-operation fact-checking, and repository validation. Use for new or revised DSH docs, docs-tree organization, documentation-quality audits and budgets, website page publishing, and bilingual documentation structure changes.
|
||||
---
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -1,43 +1,30 @@
|
||||
---
|
||||
name: dsh-official-plugin-artwork
|
||||
description: Draw and review official DeepSeek Harness plugin icons and optional feature previews, including experimental plugins. Use for package artwork and PluginArtwork glyphs; covers semantic references, proportions, lettering, transparency, localization, package metadata, and designer review. Not for toolbar or action icons.
|
||||
description: Draw and review official DeepSeek Harness plugin icons and optional feature previews, including experimental plugins. Use for package artwork and PluginArtwork glyphs; covers official references and palettes, feature previews, package metadata gates, and designer review, and links the shared drawing rules that the `dsh-doc` skill ships. Not for toolbar or action icons.
|
||||
---
|
||||
|
||||
# Official plugin artwork
|
||||
|
||||
Draw recognizable artwork that belongs beside the existing official icons. Official and official experimental plugins share this visual language; the UI label communicates experimental status. This guidance does not replace designer approval.
|
||||
Read and follow [plugin artwork](../../../packages/preset/agent-preset/skills/dsh-doc/references/artwork.md) first; installed DSH ships it in the `dsh-doc` skill, and it owns the subject, drawing, and export rules. Its Review section describes Creator bundles installed through Plugin Manager; for official plugins, follow its comparison step and replace its other steps with [Review and verify](#review-and-verify) below. Official and official experimental plugins share one visual language; the UI label communicates experimental status. This guidance does not replace designer approval.
|
||||
|
||||
When reviewing the containing page, use the [UI review baseline](../../../docs/ui-design-review-cases.md#review-baseline) to combine artwork balance with its tile, label, neighboring cards and theme material. Keep package artwork distinct from action icons: coherent optical weight does not require equal drawing bounds, monochrome fills or identical geometry across those roles.
|
||||
|
||||
## Optional feature previews
|
||||
|
||||
Before drawing a larger image for the top of an official bundle's detail document, read and follow [adding a plugin feature preview](../../../docs/cookbook/adding-a-plugin-preview.md). It owns optionality, image count, design canvas, position, language variants, file location, and acceptance. The guide also owns the embedded-raster exception for SVG previews; small icons remain geometry-only. The icon dimensions below do not apply to previews. Inspect the real feature and preserve its produced assets.
|
||||
Before drawing a larger image for the top of an official bundle's detail document, read and follow [adding a plugin feature preview](../../../docs/cookbook/adding-a-plugin-preview.md). It owns optionality, image count, design canvas, position, language variants, file location, and acceptance. The guide also owns the embedded-raster exception for SVG previews; small icons remain geometry-only. The icon dimensions in plugin artwork do not apply to previews. Inspect the real feature and preserve its produced assets.
|
||||
|
||||
## Establish the subject
|
||||
## Official references and owners
|
||||
|
||||
- Inspect the actual feature, its output, and its owning manifest before drawing. A badge-producing skill may need a tag, not a medal. Reuse designer-supplied assets; do not invent a brand mark or change product names, identifiers, or unrelated icons without approval.
|
||||
- Read the [existing artwork](../../../packages/client/ui-primitives/src/plugin-artwork.tsx) and the nearest relevant package SVGs. Borrow one coherent treatment, not every reference's effects. Action icons remain with [the UI design entry](../dsh-client-ui-ux/SKILL.md#select-the-rule-owners).
|
||||
- Check every affected entry, list, detail, and component row. Bundle artwork and a component's name and icon can have separate metadata owners; changing one does not update the other.
|
||||
|
||||
## Draw and refine
|
||||
|
||||
1. **Start simple.** Use one dominant subject and only the detail needed to explain it. Related capabilities can share a metaphor; distinguish them through proportions, silhouette, or palette rather than extra panels, symbols, or badges.
|
||||
2. **Judge optical size.** Use `width="36" height="36" viewBox="0 0 36 36"`. Center the artwork with deliberate margins; 18–22 units is a useful starting extent, not a requirement for every silhouette or wide text tag. The [page renderer](../../../packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx) owns display sizes and outer tile framing. Do not bake that tile into the SVG or enlarge a toolbar glyph to fill it.
|
||||
3. **Keep geometry consistent.** Balance the main subject and secondary element. Align repeated marks and corners; keep tails and handles intentional. Refine one requested dimension at a time without changing approved parts.
|
||||
4. **Use restrained color by default.** Balance saturation and brightness with neighboring icons; prefer existing palettes such as [Auto Authorization Review](../../../packages/experimental/auto-review/icon.svg) and [Codex subagent](../../../packages/subagent/subagent-codex/icon.svg). Reserve unusually vivid, bright, or neon colors for approved brand requirements, essential contrast, or explicit designer direction. Tune saturation separately from hue and lightness; do not make artwork gray or muddy merely to reduce saturation. Keep flat fills or short gradients and limited layering; avoid glow, drop shadows, glossy highlights, and emoji. Page CSS still uses semantic theme tokens.
|
||||
5. **Align lettering by visible ink.** Use consistent letterforms, cap height, baseline, weight, and spacing. Compare rendered stroke edges, not just path coordinates: stroke caps and joins can make equal coordinates appear unequal. Export lettering as paths without a font dependency, and keep it readable at actual size.
|
||||
6. **Make empty areas genuinely transparent.** A hollow lens must reveal the background, including where it overlaps another shape. Remove the underlying fill with a local mask or cutout; do not substitute a white or dark disk. Check both themes.
|
||||
|
||||
## Export at the owner
|
||||
|
||||
- Use the manifest's `icon` path and publish its resources. Update intentional bundle/component copies together; verify localized display names and descriptions when those are in scope. Do not change the feature's produced assets merely to change its plugin icon.
|
||||
- Package images render through `<img>`: export self-contained SVG geometry with local, uniquely named gradient, mask, and clip references. No scripts, event handlers, animation, external images/styles, fonts, or `foreignObject`. Inline React artwork needs per-instance IDs; separate image documents do not share IDs.
|
||||
- Reuse designer-supplied assets. Do not invent a brand mark or change product names, identifiers, or unrelated icons without approval.
|
||||
- Read the [existing artwork](../../../packages/client/ui-primitives/src/plugin-artwork.tsx) and the nearest relevant package SVGs. Prefer existing palettes such as [Auto Authorization Review](../../../packages/experimental/auto-review/icon.svg) and [Codex subagent](../../../packages/subagent/subagent-codex/icon.svg). The designer supplies explicit permission for vivid colors; brand requirements need approval. Use these references instead of installed-plugin discovery. Action icons remain with [the UI design entry](../dsh-client-ui-ux/SKILL.md#select-the-rule-owners).
|
||||
- The [page renderer](../../../packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx) owns display sizes and outer tile framing. SVG artwork may use literal colors; page CSS uses semantic theme tokens.
|
||||
- Check every affected entry, list, detail, and component row. Bundle artwork and component metadata have separate owners; update intentional copies together and verify localized display names and descriptions when those are in scope.
|
||||
- Inline React artwork needs per-instance IDs; separate image documents do not share IDs.
|
||||
- Keep the asset change local. Do not add runtime dependencies, primitive exports, or renderer special cases just to display it.
|
||||
|
||||
## Review and verify
|
||||
|
||||
1. Show a few numbered alternatives before polishing uncertain geometry. Preserve their labels through review and apply the chosen version; an existing file or generated draft does not establish designer approval. Keep comparison artifacts in a gitignored directory, not the product package.
|
||||
2. Compare old and new artwork beside unchanged references in light and dark themes, at actual row/card sizes as well as enlarged. Check balance, lettering, empty space, clipping, and image decoding.
|
||||
3. Run `pnpm run verify-package-meta` for [package metadata and SVG artwork](../../../scripts/verify-package-meta.ts), `pnpm run constraints` for the canonical package payload, and `pnpm run verify-official-bundle-catalog`. Regenerate a stale catalog with `pnpm run gen-official-bundle-catalog`, never by hand. Structural checks do not replace visual review.
|
||||
4. Build affected artifacts and inspect the real page through `dsh web`. Batch approved refinements before restarting a metadata-caching Host, then verify the entry and nested component rows in both themes.
|
||||
5. Follow the repository's UI testing policy and [record-browser-gif](../record-browser-gif/SKILL.md) for a GUI PR. Obtain designer approval before landing new glyphs. Record reusable drawing principles here, not the history of rejected drafts.
|
||||
1. Before polishing uncertain geometry, show a few numbered alternatives and keep their numbers through designer review. Apply the chosen one; existing files and generated drafts do not establish approval. Keep comparison artifacts in a gitignored directory, not the product package.
|
||||
2. Run `pnpm run verify-package-meta` for [package metadata and SVG artwork](../../../scripts/verify-package-meta.ts), `pnpm run constraints` for the canonical package payload, and `pnpm run verify-official-bundle-catalog`. Regenerate a stale catalog with `pnpm run gen-official-bundle-catalog`, never by hand. Structural checks do not replace visual review.
|
||||
3. Build affected artifacts and inspect the real page through `dsh web`. Batch approved refinements before restarting a metadata-caching Host, then verify the entry and nested component rows in both themes.
|
||||
4. Follow the repository's UI testing policy and [record-browser-gif](../record-browser-gif/SKILL.md) for a GUI PR. Obtain designer approval before landing new glyphs. Record reusable drawing principles in [plugin artwork](../../../packages/preset/agent-preset/skills/dsh-doc/references/artwork.md), not the history of rejected drafts.
|
||||
@@ -5,7 +5,7 @@ description: Use when writing, reviewing, restoring, trimming, or auditing prose
|
||||
|
||||
# DeepSeek Harness Prose Standard
|
||||
|
||||
Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. A contract is an obligation, invariant, precondition, postcondition, or compatibility promise that a caller, callee, implementer, producer, or consumer relies on. This skill owns editorial judgment and required prose coverage; use [dsh-doc](../dsh-doc/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates, and [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md) for hunting and fixing reasoning-transcript leakage. It is guidance, not a script.
|
||||
Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. A contract is an obligation, invariant, precondition, postcondition, or compatibility promise that a caller, callee, implementer, producer, or consumer relies on. This skill owns editorial judgment and required prose coverage; use [dsh-doc-writing](../dsh-doc-writing/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates, and [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md) for hunting and fixing reasoning-transcript leakage. It is guidance, not a script.
|
||||
|
||||
Treat `contract`, `boundary`, `shape`, `surface`, `seam`, `gate`, and `vocabulary` as terms to check before use, not banned words. First ask whether the exact rule, API, field set, type, validation, timing point, component split, or failure states the fact better. Keep a term when it names the exact technical subject, including caller/callee contracts and security/process boundaries.
|
||||
|
||||
|
||||
@@ -40,6 +40,6 @@ Unaided citation passes fail in both directions by deleting durable references a
|
||||
|
||||
1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/` or `.agents/notes/archived/`. Recorded fixtures and snapshots are derivatives, not prose targets: change the owning source or scenario and regenerate them only when an authorized behavior change requires new evidence.
|
||||
2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), calibrating each probe against a known positive and a near-miss negative before trusting its output, then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge found cases the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
|
||||
3. Fix owner-first per surface: generated catalogs → trace every consumer, fix the source JSDoc or generator template, then regenerate all derivatives; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual prose → update the counterpart minimally and re-record it through the [lightweight routine](../../../docs/AGENTS.md#writing-rules); bilingual fences → copy the corrected verbatim block byte-for-byte into both sides per [dsh-doc](../dsh-doc/SKILL.md), then re-record the pair; model- or user-visible strings → route through [dsh-prose-standard](../dsh-prose-standard/SKILL.md) and change only with owning behavior evidence, otherwise leave unchanged and report the deferral.
|
||||
3. Fix owner-first per surface: generated catalogs → trace every consumer, fix the source JSDoc or generator template, then regenerate all derivatives; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual prose → update the counterpart minimally and re-record it through the [lightweight routine](../../../docs/AGENTS.md#writing-rules); bilingual fences → copy the corrected verbatim block byte-for-byte into both sides per [dsh-doc-writing](../dsh-doc-writing/SKILL.md), then re-record the pair; model- or user-visible strings → route through [dsh-prose-standard](../dsh-prose-standard/SKILL.md) and change only with owning behavior evidence, otherwise leave unchanged and report the deferral.
|
||||
4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop the evidence source.
|
||||
5. Verify: re-run the batteries expecting only sanctioned keeps, this skill's own directory, and the owning note's quoted evidence; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
|
||||
@@ -5,7 +5,7 @@ import { createRequire } from 'node:module'
|
||||
import { randomUUID } from 'node:crypto'
|
||||
import { mkdir, mkdtemp, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { readdirSync, readFileSync, realpathSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { dirname, join } from 'node:path'
|
||||
import { Context } from '@deepseek-ai/cordis'
|
||||
@@ -31,6 +31,7 @@ import { applyChildComposition, childSessionMeta } from '@deepseek-ai/dsh-subage
|
||||
import { ToolCallId, LlmAdapter, createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
import type { GenerateOptions, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
|
||||
import type {} from '@deepseek-ai/dsh-compaction-basic'
|
||||
import { codePointLength } from '@deepseek-ai/dsh-compaction-tool-result-pruner'
|
||||
import type {} from '@deepseek-ai/dsh-skill'
|
||||
import type {} from '@deepseek-ai/dsh-tools'
|
||||
// Type-only: resolves `ctx.get('sessionProjections')` and `ctx.get('tokenMeter')`.
|
||||
@@ -561,11 +562,42 @@ describe('the shipped Web composition', () => {
|
||||
expect(tools).not.toContain('str_replace_editor')
|
||||
expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined()
|
||||
|
||||
// The preset's own authoring skill registers into ITS layer of the host
|
||||
// The preset's own skill registers into ITS layer of the host
|
||||
// registry: the cordis agent's view carries it, the global view does not.
|
||||
const scoped = (await ctx.skills.list({ scope: handle.agent })).map(skill => skill.name)
|
||||
expect(scoped).toContain('editing-cordis-compositions')
|
||||
expect((await ctx.skills.list()).map(skill => skill.name)).not.toContain('editing-cordis-compositions')
|
||||
const packageSkills = realpathSync(join(REPO_ROOT, 'packages/preset/agent-preset/skills'))
|
||||
const shipped = (await ctx.skills.list({ scope: handle.agent }))
|
||||
.filter(skill => skill.path?.startsWith(packageSkills) === true).map(skill => skill.name)
|
||||
expect(shipped).toEqual(['dsh-doc'])
|
||||
expect((await ctx.skills.list()).map(skill => skill.name)).not.toContain('dsh-doc')
|
||||
const loaded = await executeToolFixture(ctx, {
|
||||
callId: ToolCallId('preset-cordis-dsh-doc'),
|
||||
name: 'skill',
|
||||
arguments: { name: 'dsh-doc' },
|
||||
signal: new AbortController().signal,
|
||||
agent: handle.agent,
|
||||
})
|
||||
expect(loaded.isError).toBe(false)
|
||||
const output = loaded.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
|
||||
expect(output).toContain('<skill_content name="dsh-doc">')
|
||||
expect(output).toContain(`Base directory for this skill: ${join(packageSkills, 'dsh-doc')}`)
|
||||
expect(output).toContain('Loading this skill does not authorize changes.')
|
||||
// The composed `read` tool, behind the fs sandbox, returns each whole reference below the
|
||||
// pruner threshold, leaving room for an installation path of up to 256 characters.
|
||||
const references = join(packageSkills, 'dsh-doc', 'references')
|
||||
for (const file of readdirSync(references).filter(entry => entry !== 'packages.md')) {
|
||||
const path = join(references, file)
|
||||
const result = await executeToolFixture(ctx, {
|
||||
callId: ToolCallId(`preset-cordis-dsh-doc-${file}`),
|
||||
name: 'read',
|
||||
arguments: { file_path: path },
|
||||
signal: new AbortController().signal,
|
||||
agent: handle.agent,
|
||||
})
|
||||
expect(result.isError, file).toBe(false)
|
||||
const text = result.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
|
||||
expect(text, file).toContain('(End of file - total ')
|
||||
expect(codePointLength(text) - codePointLength(path) + 256, file).toBeLessThan(8192)
|
||||
}
|
||||
|
||||
// The persona is `standard`'s, pinned verbatim so the two declarations
|
||||
// cannot drift apart: tool descriptions and the skill catalog carry
|
||||
@@ -634,12 +666,10 @@ describe('the shipped Web composition', () => {
|
||||
}
|
||||
})
|
||||
|
||||
it('ships the composition-authoring skill in the declaration package', async () => {
|
||||
const skill = join(
|
||||
REPO_ROOT, 'packages/preset/agent-preset', 'skills', 'editing-cordis-compositions', 'SKILL.md',
|
||||
)
|
||||
it('ships the dsh-doc skill in the declaration package', async () => {
|
||||
const skill = join(REPO_ROOT, 'packages/preset/agent-preset', 'skills', 'dsh-doc', 'SKILL.md')
|
||||
|
||||
expect((await readFile(skill, 'utf8')).startsWith('---\nname: editing-cordis-compositions')).toBe(true)
|
||||
expect((await readFile(skill, 'utf8')).startsWith('---\nname: dsh-doc\n')).toBe(true)
|
||||
})
|
||||
|
||||
it('merges the global skill layer into a preset agent\'s catalog, keeping local discovery preset-side', async () => {
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md — The documentation standard
|
||||
|
||||
This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
|
||||
This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc-writing](../.agents/skills/dsh-doc-writing/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
|
||||
|
||||
## Document structure
|
||||
|
||||
@@ -60,7 +60,7 @@ Ceilings are guardrails, not reduction targets. At or below target, retain at le
|
||||
|
||||
## The slop checklist
|
||||
|
||||
Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
|
||||
Hunt these in any doc; [dsh-doc-writing](../.agents/skills/dsh-doc-writing/SKILL.md) runs this list as an audit:
|
||||
|
||||
- Duplicated rules: search a distinctive phrase; keep one home and link the rest.
|
||||
- History outside its permitted tier: state current facts and link the historical owner.
|
||||
|
||||
@@ -18,8 +18,8 @@
|
||||
en: 995813ee34abfbd6
|
||||
zh: 328d78e65599e0cc
|
||||
/cookbook-adding-a-workspace-package/4-write-the-package-readme:
|
||||
en: 0894bd9f35430753
|
||||
zh: 2d28090e71134edd
|
||||
en: d225694e23b8ac5d
|
||||
zh: 5be18f1018720614
|
||||
/cookbook-adding-a-workspace-package/5-add-optional-plugin-display-metadata:
|
||||
en: ee71fb0a70f02550
|
||||
zh: 1f0d6936d6c2acad
|
||||
|
||||
@@ -75,7 +75,7 @@ Use `SDK` only for the JSON-RPC client/server protocol used by the supported Pyt
|
||||
|
||||
## 4. Write the package README
|
||||
|
||||
Keep package-specific service API, config, events, extension points, and design notes first. Choose the frontmatter `kind` from the four kind labels in the [dsh-doc metadata reference](../../.agents/skills/dsh-doc/references/metadata-links-i18n.md#the-kind-system) — group, reference, library, or bundle — matching the package's repository position and entry shape; each kind selects one README template. The limitations section records durable consumer gaps and non-obvious maintainer constraints owned by this package; ordinary cleanup stays in its source TODO or Agent Note. An indirect Model Experience sentence may name the consumer that surfaces this package's contribution, but it does not restate that consumer's implementation. End a package README with this canonical sequence:
|
||||
Keep package-specific service API, config, events, extension points, and design notes first. Choose the frontmatter `kind` from the four kind labels in the [dsh-doc-writing metadata reference](../../.agents/skills/dsh-doc-writing/references/metadata-links-i18n.md#the-kind-system) — group, reference, library, or bundle — matching the package's repository position and entry shape; each kind selects one README template. The limitations section records durable consumer gaps and non-obvious maintainer constraints owned by this package; ordinary cleanup stays in its source TODO or Agent Note. An indirect Model Experience sentence may name the consumer that surfaces this package's contribution, but it does not restate that consumer's implementation. End a package README with this canonical sequence:
|
||||
|
||||
````markdown
|
||||
## Model Experience
|
||||
|
||||
@@ -75,7 +75,7 @@ package.json 不变式(由 `pnpm run constraints` / `scripts/check-workspace-c
|
||||
|
||||
## 4. 编写包 README
|
||||
|
||||
将包特有的服务 API、配置、事件、扩展点和设计说明放在前面。根据 [dsh-doc 元数据参考](../../.agents/skills/dsh-doc/references/metadata-links-i18n.md#the-kind-system)中的四种 kind 标签——组、参考、库或 bundle——选择 frontmatter 的 `kind`,使其匹配包在仓库中的位置与入口形态;每个 kind 恰好对应一个 README 模板。limitations 部分记录持久的消费方缺口和本包拥有的非显而易见的维护者约束;日常清理事项留在源码 TODO 或 Agent Note 中。间接的 Model Experience 语句可以点名暴露本包贡献的消费方,但不重述该消费方的实现。包 README 以如下规范序列结尾:
|
||||
将包特有的服务 API、配置、事件、扩展点和设计说明放在前面。根据 [dsh-doc-writing 元数据参考](../../.agents/skills/dsh-doc-writing/references/metadata-links-i18n.md#the-kind-system)中的四种 kind 标签——组、参考、库或 bundle——选择 frontmatter 的 `kind`,使其匹配包在仓库中的位置与入口形态;每个 kind 恰好对应一个 README 模板。limitations 部分记录持久的消费方缺口和本包拥有的非显而易见的维护者约束;日常清理事项留在源码 TODO 或 Agent Note 中。间接的 Model Experience 语句可以点名暴露本包贡献的消费方,但不重述该消费方的实现。包 README 以如下规范序列结尾:
|
||||
|
||||
````markdown
|
||||
## Model Experience
|
||||
|
||||
@@ -15,8 +15,8 @@
|
||||
en: 1ba6efaa0b5d6e47
|
||||
zh: 6e216391ad24c541
|
||||
/persistence-type-change-records/files-and-ownership:
|
||||
en: 41d4ab88aac68e7e
|
||||
zh: 062d65578a1dbb53
|
||||
en: c6b8a146d35ab014
|
||||
zh: 8875f16a71c18bb3
|
||||
/persistence-type-change-records/compatibility-rules:
|
||||
en: 218b28a5096b5e7d
|
||||
zh: 5b987c852e204893
|
||||
|
||||
@@ -43,7 +43,7 @@ Each dated record has four sibling files:
|
||||
|
||||
A maintainer captures an agreed format with [`createPersistenceFinalizationCheckpoint`](../../scripts/persistence-finalization.ts), writes a new version-named checkpoint without replacing an earlier one, and advances the paired `latestFinalizedVersion`. The helper requires current schemas to match complete acknowledged history. Run the ordinary verifier before committing.
|
||||
|
||||
The [record template](../../.agents/skills/dsh-doc/templates/persistence-change.md) defines the authored format. Record creation accepts a bilingual prose input and generates the machine declaration, snapshots, catalog pair, and consistency records. The verifier reads the machine declaration once from the English file and checks the Chinese declaration for equality. A declaration names each affected root, its predecessor record, its after digest, and its compatibility decision. A new root has no predecessor; a deletion has no after schema and retains an explicit tombstone.
|
||||
The [record template](../../.agents/skills/dsh-doc-writing/templates/persistence-change.md) defines the authored format. Record creation accepts a bilingual prose input and generates the machine declaration, snapshots, catalog pair, and consistency records. The verifier reads the machine declaration once from the English file and checks the Chinese declaration for equality. A declaration names each affected root, its predecessor record, its after digest, and its compatibility decision. A new root has no predecessor; a deletion has no after schema and retains an explicit tombstone.
|
||||
|
||||
<a id="compatibility-rules"></a>
|
||||
## Compatibility rules
|
||||
|
||||
@@ -43,7 +43,7 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
|
||||
|
||||
维护者通过 [`createPersistenceFinalizationCheckpoint`](../../scripts/persistence-finalization.ts) 捕获已确认格式,写入按版本命名的新检查点而不替换旧文件,并推进双语 `latestFinalizedVersion`。该函数要求当前 schema 与完整确认历史一致。提交前运行常规验证器。
|
||||
|
||||
[记录模板](../../.agents/skills/dsh-doc/templates/persistence-change.md)定义人工编写的格式。创建记录时可以提供双语说明输入,由命令生成机器声明、快照、目录对和一致性记录。验证器从英文文件读取一次机器声明,并检查中文声明是否相同。声明列出每个受影响的根、其前驱记录、变更后摘要和兼容性决策。新根没有前驱;删除操作没有变更后 schema,并保留显式删除标记。
|
||||
[记录模板](../../.agents/skills/dsh-doc-writing/templates/persistence-change.md)定义人工编写的格式。创建记录时可以提供双语说明输入,由命令生成机器声明、快照、目录对和一致性记录。验证器从英文文件读取一次机器声明,并检查中文声明是否相同。声明列出每个受影响的根、其前驱记录、变更后摘要和兼容性决策。新根没有前驱;删除操作没有变更后 schema,并保留显式删除标记。
|
||||
|
||||
<a id="compatibility-rules"></a>
|
||||
## 兼容性规则
|
||||
|
||||
@@ -18,11 +18,11 @@
|
||||
en: 1ebef675a763819c
|
||||
zh: 19457eb77b815c8c
|
||||
/session-persistence-formats/scope-and-evidence:
|
||||
en: b220062139ddac1e
|
||||
zh: 7c4c0efe05dafa9c
|
||||
en: 44ba17a168ec63ac
|
||||
zh: c80a44bdbf17a174
|
||||
/session-persistence-formats/maintain-coverage:
|
||||
en: 0be8010f3fd20d2d
|
||||
zh: b6e3af11c81e8702
|
||||
en: 57ec002a8a9d51dc
|
||||
zh: 713e95db766efb61
|
||||
/session-persistence-formats/dev-note:
|
||||
en: b75c8458928b72b9
|
||||
zh: 003ba4e17b4b5269
|
||||
@@ -39,7 +39,7 @@ The index is generated from validated snapshots and the current writer constant.
|
||||
<a id="scope"></a>
|
||||
## Scope and evidence
|
||||
|
||||
Each `vN.md` / `vN.zh.md` pair has `kind: persistence-format`, an identical `yaml persistence-format` declaration binding every root key to its captured digest, a pairing sidecar, and a complete `vN.schema.json`. The [template](../../../.agents/skills/dsh-doc/templates/persistence-format.md) defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
|
||||
Each `vN.md` / `vN.zh.md` pair has `kind: persistence-format`, an identical `yaml persistence-format` declaration binding every root key to its captured digest, a pairing sidecar, and a complete `vN.schema.json`. The [template](../../../.agents/skills/dsh-doc-writing/templates/persistence-format.md) defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
|
||||
|
||||
V0 and V2 use the latest matching tags in the [captured prerelease archive](../releases/README.md). V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. V3 captures the verified inventory before the V4 writer change in PR #4320. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
|
||||
|
||||
@@ -57,7 +57,7 @@ pnpm run verify-persistence-catalog
|
||||
pnpm run verify-persistence-formats --archive 3
|
||||
```
|
||||
|
||||
Replace `3` with the outgoing writer version for other transitions. `--archive N` creates `vN.schema.json` from the current inventory, retains exactly the types reachable from its roots, and removes source line numbers. It refuses an existing destination, a version other than the current writer, invalid or incomplete schemas, and combination with `--write`. Add the snapshot’s bilingual record and source evidence using the [template](../../../.agents/skills/dsh-doc/templates/persistence-format.md). Retain all earlier records. The successor uses the current catalog; copying a new current catalog cannot satisfy the archived predecessor requirement. Follow the [format-version cookbook](../../cookbook/adding-a-session-format-version.md) for runtime changes.
|
||||
Replace `3` with the outgoing writer version for other transitions. `--archive N` creates `vN.schema.json` from the current inventory, retains exactly the types reachable from its roots, and removes source line numbers. It refuses an existing destination, a version other than the current writer, invalid or incomplete schemas, and combination with `--write`. Add the snapshot’s bilingual record and source evidence using the [template](../../../.agents/skills/dsh-doc-writing/templates/persistence-format.md). Retain all earlier records. The successor uses the current catalog; copying a new current catalog cannot satisfy the archived predecessor requirement. Follow the [format-version cookbook](../../cookbook/adding-a-session-format-version.md) for runtime changes.
|
||||
|
||||
The schema definitions and index inside comment markers are generated. After advancing the writer and completing the machine data and authored evidence, refresh their tables and pairing records, then verify:
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
|
||||
<a id="scope"></a>
|
||||
## 范围与证据
|
||||
|
||||
每组 `vN.md` / `vN.zh.md` 文档包含 `kind: persistence-format`、将每个根类型键绑定到已记录摘要的相同 `yaml persistence-format` 声明、配对记录及完整的 `vN.schema.json`。[模板](../../../.agents/skills/dsh-doc/templates/persistence-format.md)定义这些记录。根类型覆盖所选检查点的逻辑 Session header、物理 JSONL header、事件信封与所有第一方事件;每个根包含所有可达的声明类型。打包的物理 body 记录由每页链接的独立 codec 负责。
|
||||
每组 `vN.md` / `vN.zh.md` 文档包含 `kind: persistence-format`、将每个根类型键绑定到已记录摘要的相同 `yaml persistence-format` 声明、配对记录及完整的 `vN.schema.json`。[模板](../../../.agents/skills/dsh-doc-writing/templates/persistence-format.md)定义这些记录。根类型覆盖所选检查点的逻辑 Session header、物理 JSONL header、事件信封与所有第一方事件;每个根包含所有可达的声明类型。打包的物理 body 记录由每页链接的独立 codec 负责。
|
||||
|
||||
V0 与 V2 使用[已收录预发布归档](../releases/README.zh.md)中最后一个对应 tag。由于收录的 tag 没有 V1 写入器,V1 使用其参考文档中标识的中间源码树。V3 捕获 PR #4320 中 V4 写入器变更前已验证的目录。历史来源保留文件路径,不包含行号。快照保留历史可选字段与不透明值,不会将当前类型替换到旧格式中。历史标识符仅在 schema JSON 与已验证的生成 schema 区间中原样保留;人工说明遵循当前术语规则。
|
||||
|
||||
@@ -57,7 +57,7 @@ pnpm run verify-persistence-catalog
|
||||
pnpm run verify-persistence-formats --archive 3
|
||||
```
|
||||
|
||||
对于其他转换,将 `3` 替换为原写入器版本。`--archive N` 从当前目录创建 `vN.schema.json`,只保留从根类型可达的类型,并移除源码行号。它拒绝已存在的目标、与当前写入器不同的版本、无效或不完整的 schema,以及与 `--write` 的组合。使用[模板](../../../.agents/skills/dsh-doc/templates/persistence-format.md)添加该快照的双语记录与来源证据。保留所有更早的记录。后继格式使用当前目录;复制新的当前目录不能满足归档前驱的要求。运行时变更遵循[格式版本实操手册](../../cookbook/adding-a-session-format-version.zh.md)。
|
||||
对于其他转换,将 `3` 替换为原写入器版本。`--archive N` 从当前目录创建 `vN.schema.json`,只保留从根类型可达的类型,并移除源码行号。它拒绝已存在的目标、与当前写入器不同的版本、无效或不完整的 schema,以及与 `--write` 的组合。使用[模板](../../../.agents/skills/dsh-doc-writing/templates/persistence-format.md)添加该快照的双语记录与来源证据。保留所有更早的记录。后继格式使用当前目录;复制新的当前目录不能满足归档前驱的要求。运行时变更遵循[格式版本实操手册](../../cookbook/adding-a-session-format-version.zh.md)。
|
||||
|
||||
注释标记内的 schema 定义与索引由工具生成。推进写入器并完成机器数据与人工证据后,刷新其表格和配对记录,再执行验证:
|
||||
|
||||
|
||||
@@ -24,8 +24,8 @@
|
||||
en: 2212c587e280c935
|
||||
zh: e1e12ec7d87f9bd2
|
||||
/persistence-changes-across-dsh-prereleases/verification:
|
||||
en: 5ae84a4b450733df
|
||||
zh: 7bd0f834534aae4c
|
||||
en: 67fc6c81917f57d0
|
||||
zh: 60ee3b746a6115dc
|
||||
/persistence-changes-across-dsh-prereleases/dev-note:
|
||||
en: 5de1d6304e00c58f
|
||||
zh: e58fc8dda0bea8d5
|
||||
@@ -90,7 +90,7 @@ pnpm run doc-sync
|
||||
|
||||
The marker-delimited index, inventory cells, and structural-change facts are generated from the snapshots. Default verification rejects stale facts. Run `pnpm run verify-persistence-releases --write` to refresh those regions and pairing records after validating all machine data; authored summaries, source evidence, machine declarations, and schema files are preserved.
|
||||
|
||||
Tag completeness is relative to the manifest’s captured scope; offline checks do not discover later tags automatically. Standard documentation checks validate pairing records and Markdown links. The [format template](../../../.agents/skills/dsh-doc/templates/persistence-release.md) defines each record’s fields.
|
||||
Tag completeness is relative to the manifest’s captured scope; offline checks do not discover later tags automatically. Standard documentation checks validate pairing records and Markdown links. The [format template](../../../.agents/skills/dsh-doc-writing/templates/persistence-release.md) defines each record’s fields.
|
||||
|
||||
<a id="dev-note"></a>
|
||||
## Dev Note
|
||||
|
||||
@@ -90,7 +90,7 @@ pnpm run doc-sync
|
||||
|
||||
标记区间内的索引、清单单元格和结构变化事实由快照生成。默认校验会拒绝陈旧事实。运行 `pnpm run verify-persistence-releases --write` 可在全部机器数据校验通过后刷新这些区间和配对记录;人工概述、源码证据、机器声明和 schema 文件保持不变。
|
||||
|
||||
tag 的完整性以清单的捕获范围为准;离线检查不会自动发现后续新 tag。配对记录及 Markdown 链接由常规文档检查校验。[格式模板](../../../.agents/skills/dsh-doc/templates/persistence-release.md)规定单条记录的字段。
|
||||
tag 的完整性以清单的捕获范围为准;离线检查不会自动发现后续新 tag。配对记录及 Markdown 链接由常规文档检查校验。[格式模板](../../../.agents/skills/dsh-doc-writing/templates/persistence-release.md)规定单条记录的字段。
|
||||
|
||||
<a id="dev-note"></a>
|
||||
## 开发备注
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
|
||||
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
|
||||
# After editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md
|
||||
/:
|
||||
en: 9ad5a74808f483b2
|
||||
zh: c89b849f5de717aa
|
||||
/dsh-doc-replaces-the-creator-mode-skills:
|
||||
en: c87b3ce7403fa47c
|
||||
zh: 1d0a8ca0fead88a7
|
||||
/dsh-doc-replaces-the-creator-mode-skills/change:
|
||||
en: 42be2a4794ccbf7c
|
||||
zh: bb02fb4b4acb9526
|
||||
/dsh-doc-replaces-the-creator-mode-skills/migration:
|
||||
en: 1782843e22357167
|
||||
zh: f8eaab2275d1510f
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
kind: upgrade-guide
|
||||
description: "Creator mode replaces its four skills with one `dsh-doc` skill, and the repository documentation skill becomes `dsh-doc-writing`."
|
||||
---
|
||||
|
||||
# `dsh-doc` replaces the Creator mode skills
|
||||
|
||||
English | [中文](guide.zh.md)
|
||||
|
||||
## Change
|
||||
|
||||
Creator mode offered four skills from `@deepseek-ai/dsh-agent-preset`: `cordis-plugin-development`, `editing-cordis-compositions`, `cordis-composition-reference`, and `agent-experience`. It now offers one skill, `dsh-doc`. Its former content is in files that `dsh-doc` reads on demand, under `skills/dsh-doc/references/` and `skills/dsh-doc/templates/` of that package. The old skill names no longer appear in the skill catalog, and loading one by name fails.
|
||||
|
||||
In a DSH source checkout, the documentation-writing skill `.agents/skills/dsh-doc` is now `.agents/skills/dsh-doc-writing`, named `dsh-doc-writing`.
|
||||
|
||||
This affects Creator mode users whose prompts, saved instructions, or own skills name an old skill, and compositions or scripts that read files at the old paths.
|
||||
|
||||
## Migration
|
||||
|
||||
1. Replace each old skill name in prompts, instructions, and skills with `dsh-doc`; for the source checkout documentation skill, use `dsh-doc-writing`.
|
||||
2. Replace file paths under `@deepseek-ai/dsh-agent-preset/skills/` as follows:
|
||||
|
||||
| Old path | New path |
|
||||
|---|---|
|
||||
| `cordis-plugin-development/SKILL.md` | `dsh-doc/references/plugin-development.md` |
|
||||
| `cordis-plugin-development/references/<file>` | `dsh-doc/references/<file>` |
|
||||
| `cordis-plugin-development/templates/<name>/` | `dsh-doc/templates/<name>/` |
|
||||
| `editing-cordis-compositions/SKILL.md` | `dsh-doc/references/compositions.md` |
|
||||
| `cordis-composition-reference/SKILL.md` | `dsh-doc/references/composition-reference.md` |
|
||||
| `cordis-composition-reference/references/packages.md` | `dsh-doc/references/packages.md` |
|
||||
| `agent-experience/SKILL.md` | `dsh-doc/references/tool-design.md` |
|
||||
|
||||
3. A composition that sets `customSkillDirs` to the package's `skills` directory needs no change.
|
||||
4. Rename or remove a skill named `dsh-doc` in a project's `.dsh/skills/` or `.agents/skills/`: project skills take precedence and would hide the packaged one. In a DSH source checkout, update the checkout to a revision that contains this change, which renames the repository skill.
|
||||
5. Start a new Creator mode session with an installation or revision that contains this change, and confirm that the skill catalog lists `dsh-doc` and none of the four skills this package shipped before.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
kind: upgrade-guide
|
||||
description: "创造模式用一个 `dsh-doc` skill 取代原有的四个 skill,仓库文档 skill 更名为 `dsh-doc-writing`。"
|
||||
---
|
||||
|
||||
# `dsh-doc` 取代创造模式的 skill
|
||||
|
||||
[English](guide.md) | 中文
|
||||
|
||||
## 变更
|
||||
|
||||
创造模式原先从 `@deepseek-ai/dsh-agent-preset` 提供四个 skill(技能):`cordis-plugin-development`、`editing-cordis-compositions`、`cordis-composition-reference` 和 `agent-experience`。现在只提供一个 skill:`dsh-doc`。原有内容位于该包 `skills/dsh-doc/references/` 和 `skills/dsh-doc/templates/` 下的文件中,由 `dsh-doc` 按需读取。旧 skill 名称不再出现在 skill 目录中,按名称加载旧 skill 会失败。
|
||||
|
||||
在 DSH 源码 checkout 中,文档编写 skill `.agents/skills/dsh-doc` 现为 `.agents/skills/dsh-doc-writing`,名称为 `dsh-doc-writing`。
|
||||
|
||||
受影响的对象包括:提示词、已保存指令或自有 skill 中引用旧 skill 名称的创造模式用户,以及读取旧路径文件的组合或脚本。
|
||||
|
||||
## 迁移
|
||||
|
||||
1. 将提示词、指令和 skill 中的每个旧 skill 名称替换为 `dsh-doc`;源码 checkout 中的文档 skill 改用 `dsh-doc-writing`。
|
||||
2. 按下表替换 `@deepseek-ai/dsh-agent-preset/skills/` 下的文件路径:
|
||||
|
||||
| 旧路径 | 新路径 |
|
||||
|---|---|
|
||||
| `cordis-plugin-development/SKILL.md` | `dsh-doc/references/plugin-development.md` |
|
||||
| `cordis-plugin-development/references/<file>` | `dsh-doc/references/<file>` |
|
||||
| `cordis-plugin-development/templates/<name>/` | `dsh-doc/templates/<name>/` |
|
||||
| `editing-cordis-compositions/SKILL.md` | `dsh-doc/references/compositions.md` |
|
||||
| `cordis-composition-reference/SKILL.md` | `dsh-doc/references/composition-reference.md` |
|
||||
| `cordis-composition-reference/references/packages.md` | `dsh-doc/references/packages.md` |
|
||||
| `agent-experience/SKILL.md` | `dsh-doc/references/tool-design.md` |
|
||||
|
||||
3. 将 `customSkillDirs` 设为该包 `skills` 目录的组合无需修改。
|
||||
4. 重命名或删除项目 `.dsh/skills/` 或 `.agents/skills/` 中名为 `dsh-doc` 的 skill:项目 skill 优先级更高,会遮蔽随包提供的同名 skill。在 DSH 源码 checkout 中,将该 checkout 更新到包含本变更的修订版本;本变更会重命名仓库 skill。
|
||||
5. 使用包含本变更的安装或修订版本新建一个创造模式会话,确认 skill 目录列出 `dsh-doc`,且不包含本包此前提供的四个 skill 中的任何一个。
|
||||
@@ -9,7 +9,7 @@
|
||||
order: 4
|
||||
plugins:
|
||||
# Same persona as `standard`: tool descriptions and the skill catalog carry
|
||||
# the operating detail, and the skills own the preset-authoring rules.
|
||||
# the operating detail, and the dsh-doc skill owns the preset-authoring rules.
|
||||
- id: persona
|
||||
name: '@deepseek-ai/dsh-persona'
|
||||
config:
|
||||
|
||||
@@ -30,8 +30,8 @@
|
||||
en: 72ffb7cae674c31a
|
||||
zh: 85674f298a78592a
|
||||
/deepseek-ai-dsh-tool-cordis/model-experience/runtime-inspection/what-the-model-sees:
|
||||
en: 197fabc06c289f6e
|
||||
zh: e7f1695ee2118ed6
|
||||
en: 172dc6793fdc009c
|
||||
zh: 1460b053cf1af16a
|
||||
/deepseek-ai-dsh-tool-cordis/model-experience/runtime-inspection/token-effect:
|
||||
en: 5d9791798f8ce57f
|
||||
zh: b47984cc13e12cfd
|
||||
|
||||
@@ -54,7 +54,7 @@ Host providers combine generated Service/Event catalogs, the live Loader tree pr
|
||||
|
||||
#### What the model sees
|
||||
|
||||
The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The plugin contributes no system prompt section: the tool descriptions state when to call each tool and that queries never invoke business methods. In the `cordis` preset, the first-turn skill catalog carries the descriptions of the two shipped skills, which route plugin, MCP, composition, and destination-less visual requests to the skill covering Plugin Manager, MCP setup, Client packaging, and slot registration. Query results contain the requested API declarations, live tool schemas, the live entry directory with Config status, or one entry's projected Config JSON Schema.
|
||||
The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The plugin contributes no system prompt section: the tool descriptions state when to call each tool and that queries never invoke business methods. In the `cordis` preset, the first-turn skill catalog carries the description of the shipped `dsh-doc` skill, which covers questions about DSH and requests to build or change DSH plugins, MCP connections, and agent presets; its references cover Plugin Manager, MCP setup, Client packaging, and slot registration. Query results contain the requested API declarations, live tool schemas, the live entry directory with Config status, or one entry's projected Config JSON Schema.
|
||||
|
||||
#### Token effect
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ Host provider 结合生成的 Service/Event 目录、经 app-boot Config 投影
|
||||
|
||||
#### 模型所见
|
||||
|
||||
[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。插件不贡献 system prompt 段落:工具描述已说明何时调用每个工具以及查询不会调用业务方法。在 `cordis` preset 中,首轮 skill catalog 携带两个随附技能的描述,把插件、MCP、组合编辑和未指定去向的视觉请求路由到覆盖 Plugin Manager、MCP 设置、Client 打包和 slot 注册的技能。查询结果包含所请求的 API 声明、当前工具 schema、带 Config 状态的运行中 entry 目录,或单个 entry 投影后的 Config JSON Schema。
|
||||
[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。插件不贡献 system prompt 段落:工具描述已说明何时调用每个工具以及查询不会调用业务方法。在 `cordis` preset 中,首轮 skill catalog 携带随附的 `dsh-doc` 技能的描述,该技能覆盖关于 DSH 的问题,以及构建或修改 DSH 插件、MCP 连接和 agent preset 的请求;其参考资料覆盖 Plugin Manager、MCP 设置、Client 打包和 slot 注册。查询结果包含所请求的 API 声明、当前工具 schema、带 Config 状态的运行中 entry 目录,或单个 entry 投影后的 Config JSON Schema。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
|
||||
@@ -15,8 +15,8 @@
|
||||
en: d152484eb41ac6b4
|
||||
zh: b3ad7867f23dad1c
|
||||
/deepseek-ai-dsh-agent-preset/use-this-package:
|
||||
en: 3e243b0ee04dd23f
|
||||
zh: 832841c35b57180a
|
||||
en: 540b1dac9a513e55
|
||||
zh: f7f0e9f5778e4888
|
||||
/deepseek-ai-dsh-agent-preset/understand-the-implementation:
|
||||
en: 7ac55a3a3af4fcef
|
||||
zh: 95fe36abba794967
|
||||
@@ -30,8 +30,8 @@
|
||||
en: 4644bd5f0c865667
|
||||
zh: 9aedc8ac43fb8b61
|
||||
/deepseek-ai-dsh-agent-preset/known-limitations-and-deferred-work:
|
||||
en: 4546a11627bbbca1
|
||||
zh: eaa260cdfe37e31f
|
||||
en: d4dbce86236e8e91
|
||||
zh: 11766aef5d0ff536
|
||||
/deepseek-ai-dsh-agent-preset/known-limitations-and-deferred-work/dev-note:
|
||||
en: e67f633dc6fe7773
|
||||
zh: 8ec3e73528ddb1a6
|
||||
@@ -47,9 +47,9 @@ Define an Agent’s child plugins in ordinary Cordis YAML. Declare several prese
|
||||
|
||||
The declaration row’s `id` addresses Loader edits; `config.id` is the preset identity saved by sessions. Child entry IDs may be omitted and assigned by Loader.
|
||||
|
||||
The package also ships the `skills/` directory that creator mode mounts through `skill-filesystem`: `agent-experience` (tool descriptions and efficient context loading), `cordis-plugin-development` (a short procedure with `references/` read on demand and copyable `templates/` bundles), `editing-cordis-compositions`, and `cordis-composition-reference`, whose `references/packages.md` is generated by `scripts/gen-plugin-packages.ts` and freshness-gated in `doc-sync`. The two procedure skills tell the agent to read inspection results first, then the package README under the `packageDir` that `Config.listConfigs` reports, then built `lib/` or checkout sources. Every shipped `SKILL.md`, rendered as a `skill` tool result, stays under the 8192-character threshold above which the standard preset's tool-result pruner trims results.
|
||||
The package also ships the `skills/` directory that creator mode mounts through `skill-filesystem`. It holds one skill, `dsh-doc`: a short `SKILL.md` that sets the order for finding DSH facts (runtime inspection when its tools are available, then the installed documentation and package sources) and states that loading the skill authorizes no file or profile change, plus `references/` read on demand and copyable `templates/` bundles. The references cover locating documentation, plugin development, bundle display metadata and detail documents, Web UI plugins, MCP bundles, extension practices, user actions, verification and user experience review, icon and feature-image drawing, agent presets, the Loader patch dialect, tool design, upgrades across DSH releases, and `references/packages.md`, which `scripts/gen-plugin-packages.ts` generates and `doc-sync` checks for freshness. The rendered `SKILL.md` and every reference except `packages.md`, read with line numbers, stay under the 8192-character threshold above which the standard preset's tool-result pruner trims results.
|
||||
|
||||
Edit `agent-experience` in [skills/agent-experience/SKILL.md](skills/agent-experience/SKILL.md). The repository discovery path, `.agents/skills/agent-experience/SKILL.md`, is a relative symbolic link to this file; the published package contains the regular file.
|
||||
Edit tool design rules in [skills/dsh-doc/references/tool-design.md](skills/dsh-doc/references/tool-design.md). The repository skill `.agents/skills/agent-experience/SKILL.md` only links to that file.
|
||||
|
||||
<a id="understand-the-implementation"></a>
|
||||
## Understand the implementation
|
||||
@@ -82,7 +82,6 @@ A live Agent’s composition stays stable; new Agents can use an updated definit
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
- Requires the `agentPresets` service. Duplicate preset IDs fail declaration loading. Declarations provide no directory, file-copy or file-delete operations.
|
||||
- Repository discovery of `agent-experience` requires a checkout with symbolic links enabled. With `core.symlinks=false`, Git writes the link target as plain text, not a skill. Creator mode uses the regular file in the package and does not depend on that alias.
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### Dev Note
|
||||
|
||||
@@ -47,9 +47,9 @@ kind: "package-reference"
|
||||
|
||||
声明行的 `id` 是 Loader 编辑地址;`config.id` 是会话保存的 preset 标识符。子插件可省略行 ID,由 Loader 分配。
|
||||
|
||||
本包还随包出货创造模式通过 `skill-filesystem` 挂载的 `skills/` 目录:`agent-experience`(工具描述与高效上下文加载)、`cordis-plugin-development`(简短流程,配合按需读取的 `references/` 与可复制的 `templates/` 组合包)、`editing-cordis-compositions`,以及 `cordis-composition-reference`,后者的 `references/packages.md` 由 `scripts/gen-plugin-packages.ts` 生成并在 `doc-sync` 中做新鲜度门禁。两个流程 skill 让 agent 先读检查结果,再读 `Config.listConfigs` 报告的 `packageDir` 下的包 README,最后读构建后的 `lib/` 或 checkout 源码。每个出货的 `SKILL.md` 作为 `skill` 工具结果渲染后都保持在 8192 字符阈值之下,标准 preset 的工具结果修剪器超过该阈值才会裁剪。
|
||||
本包还随包出货创造模式通过 `skill-filesystem` 挂载的 `skills/` 目录。该目录只包含一个 skill,即 `dsh-doc`:一份简短的 `SKILL.md`,规定查找 DSH 事实的顺序(运行时检查工具可用时先做运行时检查,再查阅已安装的文档与包源码),并说明加载该 skill 不授权任何文件或 profile 修改;另有按需读取的 `references/` 与可复制的 `templates/` 组合包。参考文件涵盖定位文档、插件开发、组合包展示元数据与详情文档、Web UI 插件、MCP 组合包、扩展实践、用户操作、验证与用户体验评审、图标与功能配图绘制、Agent preset、Loader 补丁方言、工具设计、跨 DSH 版本升级,以及 `references/packages.md`;后者由 `scripts/gen-plugin-packages.ts` 生成,并在 `doc-sync` 中做新鲜度门禁。渲染后的 `SKILL.md` 与除 `packages.md` 外的每个参考文件在带行号读取时都保持在 8192 字符阈值之下;标准 preset 的工具结果修剪器会裁剪超过该阈值的结果。
|
||||
|
||||
在 [skills/agent-experience/SKILL.md](skills/agent-experience/SKILL.md) 编辑 `agent-experience`。仓库发现路径 `.agents/skills/agent-experience/SKILL.md` 是指向该文件的相对符号链接;发布包包含普通文件。
|
||||
工具设计规则在 [skills/dsh-doc/references/tool-design.md](skills/dsh-doc/references/tool-design.md) 中编辑。仓库 skill `.agents/skills/agent-experience/SKILL.md` 只包含指向该文件的链接。
|
||||
|
||||
<a id="understand-the-implementation"></a>
|
||||
## 理解实现
|
||||
@@ -82,7 +82,6 @@ kind: "package-reference"
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
- 需要 `agentPresets` 服务。重复的 preset ID 会导致声明加载失败。声明不提供目录、文件复制或文件删除操作。
|
||||
- 从仓库发现 `agent-experience` 要求 checkout 启用符号链接。设置 `core.symlinks=false` 时,Git 会将链接目标写成纯文本,而不是 skill。创造模式使用包内的普通文件,不依赖该别名。
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### 开发备注
|
||||
|
||||
@@ -46,6 +46,7 @@
|
||||
"@deepseek-ai/cordis-plugin-loader": "workspace:~",
|
||||
"@deepseek-ai/dsh-agent-preset-registry": "workspace:*",
|
||||
"@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:*",
|
||||
"@deepseek-ai/dsh-plugin-detail": "workspace:*",
|
||||
"@deepseek-ai/dsh-skill": "workspace:*",
|
||||
"@deepseek-ai/dsh-skill-filesystem": "workspace:*",
|
||||
"@deepseek-ai/schemastery": "workspace:~",
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
name: cordis-plugin-development
|
||||
description: Use when designing, reviewing, adding, enabling, disabling, installing, configuring, or debugging a plugin, bundle, feature, page, panel, tool, or MCP connection in the current Harness profile, including a shipped plugin that is disabled by default, and for any visual object, decoration, or widget request that names no other destination, which means an installed UI plugin rendered in the Harness Web UI.
|
||||
---
|
||||
|
||||
# Persistent Harness plugins
|
||||
|
||||
For implementation, use ordinary workspace files to author a bundle, then `plugin_manager` with `action: install_bundle` and the absolute package directory as `target` to install it in the current profile. Changes affect every session in that profile and survive restart. Load `editing-cordis-compositions` for agent preset changes.
|
||||
|
||||
Do not write the profile's `package.json` or `cordis.patch.yml`, create packages under `$DSH_HOME`, or run pnpm in the profile directory: `install_bundle` performs those steps, and each hand-made write outside the workspace needs its own approval. Every `plugin_manager` action, including `list_plugins` and `list_bundles`, also needs approval without Full access, so call it only when its result decides the next step.
|
||||
|
||||
## Design or review
|
||||
|
||||
Read the applicable references below and inspect the proposed or existing plugin against current APIs. Report design choices or findings instead of following the installation workflow. Do not write files, install bundles, or change profile state unless the user requests implementation.
|
||||
|
||||
## Enable a shipped plugin
|
||||
|
||||
A shipped bundle can resolve a plugin row and leave it `disabled`. The row id and its reason are in the shipped patch, `packages/bundle/*/cordis.patch.yml` in a source checkout. Write a workspace bundle whose patch overrides that row with `disabled: false` and inserts the Host rows it depends on; a source checkout's `apps/cli/config/examples/<feature>/cordis.yml` lists them for opt-in features. Packages shipped with dsh resolve from the dsh installation, so the bundle declares no dependencies on them. Install it with `install_bundle`.
|
||||
|
||||
## Deliver a working plugin first
|
||||
|
||||
1. Resolve the requested result and destination. An unspecified visual destination is the current Harness Web UI; a standalone image or HTML file does not complete such a request. Choose reasonable visual details and implement a small first version; install it before visual refinement.
|
||||
2. Discover only the APIs needed for that version: `cordis_inspect_list`, then targeted `cordis_inspect_query` calls. For UI, query Client `Slots.listSubTree` and the selected slot's registration options and props. For anything beyond a static decoration, such as tool policy, agent context, session-derived state, or Chat rows, read `references/practices.md` before choosing the extension point; for a user action in plugin UI, also read `references/user-actions.md`. Once the chosen slot and registration API are known, write the plugin.
|
||||
3. Read and copy the matching template files into one workspace directory, or author the package, patch, and required Host/Client files there. Before installing, complete the display checklist in `references/host-plugin.md`: meaningful localized titles/descriptions, an original or licensed icon, and exported resources with distribution checks where applicable. This applies to Host-only and configuration-only bundles too; adapt template text and artwork to the request. Check JavaScript syntax and the manifest, then install. Use the installed plugin as the first preview; do not create preview HTML, mock shells, design variants, screenshot scripts, or rasterizer tooling first.
|
||||
4. Read the installation result: `application` and `warnings` decide whether the change is live, not logs, process lists, or the page's boot payload. Confirm new rows with approval-free `cordis_inspect_query`, not `list_plugins`. After `application: applied`, exercise the capability or inspect the live Client registration. Verify installed display metadata and the icon using `references/host-plugin.md`. Use the connected page when available; follow `references/verification.md` for page/panel design checks and unavailable browser control, and `references/user-actions.md` for user actions. Restore user state changed during testing. Report verification limits; installation and slot registration alone do not establish what the user sees.
|
||||
5. Fix observed defects in the same plugin. When the requested result works, finish with its location, verification status, and the reason for any display-resource exception; never silently accept default artwork. Do not continue speculative variants, optional features, or mock previews. Close any task list.
|
||||
|
||||
## Knowledge sources, in order
|
||||
|
||||
1. Inspection: `cordis_inspect_query` answers exact Service methods and Event modes (`Service`, `Event`), a mounted plugin's Config JSON Schema (`Config.listConfigs`: filter the paged directory by `name`, then query the `entry` id), the Tools this Agent can call (`Tool`), and live Client Slots and theme tokens (`Slots`, `Theme`).
|
||||
2. Package documentation: `Config.listConfigs` with `name` set to the package finds its entries; querying one `entry` returns its `packageDir`, the resolved package directory. Read `<packageDir>/README.md`. Bundled packages resolve from the dsh installation and profile-installed bundles from the profile, so never guess the path from `$DSH_PROFILE_DIR`.
|
||||
3. Source: installed packages ship built `lib/index.js` and `lib/types/**/*.d.ts` with JSDoc under that same `packageDir`, not `src/`; a source checkout of DSH has `packages/<group>/<name>/src`. Read them when inspection and the README leave a question open, and start source-level diagnosis from a concrete installation or runtime failure.
|
||||
|
||||
`DSH_PROFILE` (profile name) and `DSH_PROFILE_DIR` (its directory, whose `node_modules` holds only profile-installed bundles) are set in every shell call of a profile-launched Harness and absent when the Harness was booted without a profile. Bash reads them as `$DSH_PROFILE`; PowerShell, which the Windows preset uses, reads them as `$env:DSH_PROFILE`. With `dsh` on the PATH, `dsh --profile "$DSH_PROFILE" --dump-config` prints the composed profile.
|
||||
|
||||
## Read next
|
||||
|
||||
The files below live in this skill's base directory, which the `skill` tool reported, and the table is the complete list: do not enumerate that directory. In every deployment, including a source checkout, read these files with the file-read tool, write copies into the workspace with the file-write tool, and verify a copy by reading it back. In Desktop the directory sits inside `app.asar`, which only the Host process's own file reads can open; shell commands (`ls`, `cat`, `cp`, `cmp`), the glob and search tools (they run a native ripgrep process), `node`, and pnpm all fail on it. Never install or syntax-check a template in place; copy its contents into the workspace first.
|
||||
|
||||
| Task | File |
|
||||
|---|---|
|
||||
| Bundle manifest, locale resources, icons, installation, Host exports and Config | `references/host-plugin.md` |
|
||||
| Web UI: Client manifest, module loader, slot registration | `references/ui-plugin.md` |
|
||||
| Connecting an MCP server through a configuration-only bundle | `references/mcp-bundle.md` |
|
||||
| Page/panel design checks and verification without browser control | `references/verification.md` |
|
||||
| UI plugin template, including display resources | `templates/decoration/package.json`, `templates/decoration/cordis.patch.yml`, `templates/decoration/index.js`, `templates/decoration/client.js`, `templates/decoration/locale`, `templates/decoration/icon.svg` |
|
||||
| MCP bundle template, including display resources | `templates/mcp/package.json`, `templates/mcp/cordis.patch.yml`, `templates/mcp/locale`, `templates/mcp/icon.svg` |
|
||||
| Loader patch dialect and the list of installable plugin packages | the `cordis-composition-reference` skill |
|
||||
| Choosing extension points, contexts, and state mechanisms for upgrade stability and performance | `references/practices.md` |
|
||||
| Sharing application operations between UI actions and agent tools | `references/user-actions.md` |
|
||||
@@ -1,5 +0,0 @@
|
||||
# Connect an MCP server
|
||||
|
||||
Read `templates/mcp/` with the file-read tool and write its files into your bundle directory. A configuration-only bundle's manifest needs a unique name, version, and `dsh.bundle.patch`, but no Host/Client entry files. Its patch, `templates/mcp/cordis.patch.yml`, inserts the already installed `@deepseek-ai/dsh-mcp-client` with `serverName`, `transport: streamable-http`, `url`, and `failOnStartupError: true`.
|
||||
|
||||
Replace the endpoint, install the bundle through `plugin_manager`, then call `mcp__demo__ping` or another newly available `mcp__<serverName>__<tool>` tool to verify the connection. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`; `Config.listConfigs` on the installed row returns the complete client schema. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates.
|
||||
-7
@@ -1,7 +0,0 @@
|
||||
# Verify in the available environment
|
||||
|
||||
Prefer the authenticated page already connected to Harness. Do not launch a separate browser from shell commands, change `HOME`, inspect personal browser profiles, search for authentication tokens, or alter keychains to obtain a screenshot. For a visual-only request without browser control, limit verification to JavaScript syntax, manifest validation, and the live Client slot, then report that visual verification remains unavailable. Before or after installation, do not search for rasterizers, invoke Quick Look, extract SVG into preview files, emulate React/DOM, or implement a custom renderer to compensate for missing browser control. A screenshot of a mock page is not verification of the running plugin.
|
||||
|
||||
For a page or panel, verify that styles use only theme tokens, the plugin imports no Harness Client package such as `@deepseek-ai/dsh-client-ui-primitives`, the console shows no slot entry crash, and the view reads correctly in light and dark themes beside a comparable host page. Scale verification to the change's risk.
|
||||
|
||||
For any test subprocess or temporary resource, use a unique owned directory, bound execution, and await cleanup. A failed optional preview must not turn into environment repair or block installation.
|
||||
-3
@@ -1,3 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
|
||||
<circle cx="32" cy="32" r="24" fill="#247bbf"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 118 B |
@@ -1,5 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
|
||||
<rect x="4" y="18" width="18" height="28" rx="4" fill="#247bbf"/>
|
||||
<rect x="42" y="18" width="18" height="28" rx="4" fill="#247bbf"/>
|
||||
<path d="M22 32h20m-7-7 7 7-7 7" fill="none" stroke="#247bbf" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 335 B |
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: dsh-doc
|
||||
description: Use when a task needs facts about DeepSeek Harness (DSH) itself, such as how a feature, setting, plugin, agent preset, tool, or Cordis API of the running installation works; when the user asks to design, review, build, install, enable, or debug a DSH plugin, bundle, MCP connection, agent preset, plugin icon or detail page, or a DSH tool definition or skill; and when upgrading a plugin or profile to a newer DSH release. Loading it grants no permission to change files or the profile.
|
||||
---
|
||||
|
||||
# DeepSeek Harness documentation
|
||||
|
||||
Answer questions about DSH from the documentation and source of the installed version, not from memory, and extend DSH through bundles installed in the current profile.
|
||||
|
||||
Loading this skill does not authorize changes. Write bundle files, run mutating `plugin_manager` actions such as installing, enabling, disabling, or removing, or change a preset only when the user asks to change DSH or its profile. For a question, design, or review, read-only lookups, including `list_plugins` and `list_bundles` within your tool permissions, remain available; report findings and leave files and the profile unchanged. A request for an image, widget, or decoration that does not target DSH, such as its Web UI or profile, is not a request for a DSH plugin; deliver the ordinary artifact the task asks for.
|
||||
|
||||
## Find facts in this order
|
||||
|
||||
1. Runtime inspection, when `cordis_inspect_list` and `cordis_inspect_query` are among your tools: exact Service methods and Event modes, a mounted plugin's Config schema and `packageDir`, the Tools this Agent can call, and live Client Slots and theme tokens.
|
||||
2. The installed documentation and package sources, located as `references/locate-docs.md` describes.
|
||||
3. When an answer depends on a live API that you can neither inspect nor read, state what remains unverified. Do not change a preset or the profile to gain tools.
|
||||
|
||||
## Read next
|
||||
|
||||
The files below live in this skill's base directory, which the `skill` tool reported, and the table is the complete list: do not enumerate that directory. Read them with the file-read tool, write copies into the workspace with the file-write tool, and verify a copy by reading it back. In Desktop the directory sits inside `app.asar`, which the file-read tool and the runtime that `references/locate-docs.md` describes can open; native utilities such as `ls`, `cat`, `cp`, and `cmp`, the glob and search tools, a `node` from `PATH`, and pnpm fail on it. Never install or syntax-check a template in place; copy its contents into the workspace first.
|
||||
|
||||
| Task | File |
|
||||
|---|---|
|
||||
| Find the installed version's documentation and package sources | `references/locate-docs.md` |
|
||||
| Build, install, enable, or debug a plugin or bundle | `references/plugin-development.md` |
|
||||
| Bundle manifest, locale resources, detail document, icons, installation, Host exports and Config | `references/host-plugin.md` |
|
||||
| Save plugin configuration or credentials | `references/configuration.md` |
|
||||
| Web UI: Client manifest, module loader, slot registration | `references/ui-plugin.md` |
|
||||
| Connect an MCP server through a configuration-only bundle | `references/mcp-bundle.md` |
|
||||
| Choose extension points, contexts, and state mechanisms | `references/practices.md` |
|
||||
| Share application operations between UI actions and agent tools | `references/user-actions.md` |
|
||||
| Verify a page or panel, review its user experience, or work without browser control | `references/verification.md` |
|
||||
| Draw icons and feature images | `references/artwork.md` |
|
||||
| Create, change, or migrate an agent preset; choose Host or preset placement | `references/compositions.md` |
|
||||
| Upgrade a plugin or profile to a newer DSH release | `references/upgrading.md` |
|
||||
| Loader patch dialect | `references/composition-reference.md` |
|
||||
| Installable plugin packages, one table per package group | `references/packages.md` |
|
||||
| Write a DSH tool definition, skill, or multi-step workflow | `references/tool-design.md` |
|
||||
| UI plugin template | `templates/decoration/package.json`, `templates/decoration/cordis.patch.yml`, `templates/decoration/index.js`, `templates/decoration/client.js`, `templates/decoration/locale`, `templates/decoration/docs/DETAIL.md`, `templates/decoration/icon.svg` |
|
||||
| MCP bundle template | `templates/mcp/package.json`, `templates/mcp/cordis.patch.yml`, `templates/mcp/locale`, `templates/mcp/docs/DETAIL.md`, `templates/mcp/icon.svg` |
|
||||
@@ -0,0 +1,33 @@
|
||||
# Plugin artwork
|
||||
|
||||
Draw an icon that is recognizable at row size and belongs beside the icons of installed DSH plugins, and, when it helps, a feature image for the detail document. The display checklist in `references/host-plugin.md` owns manifest exports, accepted formats, size limits, and installed-display checks.
|
||||
|
||||
## Establish the subject
|
||||
|
||||
- Inspect the feature, its output, and its manifest before drawing. A badge-producing skill may need a tag, not a medal. Reuse assets the user supplies; do not invent a brand mark for a third-party product or copy one whose license does not permit redistribution.
|
||||
- Read the icons of two or three installed plugins with related purposes. `references/locate-docs.md` finds each package directory; for a package-root plugin, a top-level `package.json` `icon`, else its `./icon` export, names the file; a subpath plugin uses only `./<subpath>/icon`. Plugins that Plugin Manager draws itself have no icon file. Borrow one coherent treatment, not every reference's effects.
|
||||
- Plugin Manager resolves the icon and display metadata separately for the bundle package and for each plugin its patch inserts; a subpath plugin or another package does not inherit the bundle's icon. Update every one you intend to change, and only those.
|
||||
|
||||
## Draw and refine
|
||||
|
||||
1. **Start simple.** Use one dominant subject and only the detail needed to explain it. Related capabilities can share a subject; distinguish them through proportions, silhouette, or palette rather than extra panels, symbols, or badges.
|
||||
2. **Judge optical size.** Use `width="36" height="36" viewBox="0 0 36 36"`. Center the artwork with deliberate margins; 18–22 units is a useful starting extent, not a requirement for every silhouette or wide text tag. Plugin Manager chooses display sizes and draws the surrounding tile, so do not draw a tile or background in the SVG or enlarge a toolbar glyph to fill it.
|
||||
3. **Keep geometry consistent.** Balance the main subject and secondary element. Align repeated marks and corners; keep tails and handles intentional. Refine one requested dimension at a time without changing approved parts.
|
||||
4. **Use restrained color.** Match the saturation and brightness of neighboring installed icons. Reserve unusually vivid, bright, or neon colors for brand requirements, essential contrast, or explicit user direction. Tune saturation separately from hue and lightness; do not make artwork gray or muddy merely to reduce saturation. Keep flat fills or short gradients and limited layering; avoid glow, drop shadows, glossy highlights, and emoji.
|
||||
5. **Align lettering by visible ink.** Use consistent letterforms, cap height, baseline, weight, and spacing. Compare rendered stroke edges, not just path coordinates: stroke caps and joins can make equal coordinates appear unequal. Draw lettering as paths and keep it readable at actual size.
|
||||
6. **Make empty areas genuinely transparent.** A hollow lens must reveal the background, including where it overlaps another shape. Remove the underlying fill with a local mask or cutout; do not substitute a white or dark disk. Check both themes.
|
||||
|
||||
## Export
|
||||
|
||||
- Plugin Manager loads icons as images; an image that cannot decode falls back to the panel's default artwork. Export self-contained SVG geometry with local, uniquely named gradient, mask, and clip references. For these icons, omit scripts, event handlers, `<style>`, animation, `<image>`, and `foreignObject` to keep the asset self-contained. Draw lettering as paths rather than `<text>` so browser font substitution cannot change it.
|
||||
- Do not change assets the feature itself produces merely to change its icon.
|
||||
|
||||
## Feature image
|
||||
|
||||
A detail document may start with one feature image when a picture shows the result better than text. Draw it only when the user asks for one or the result cannot be shown in text, after the plugin works. Save one SVG per document language, such as `docs/preview.svg` and `docs/preview.zh.svg`, with `width="640" height="300" viewBox="0 0 640 300"`, and reference it from the first line of that document as ``, and `preview.zh.svg` from `DETAIL.zh.md`. Images must fit `pluginManager.detailImageMaxBytes` (5 MiB by default). Show one main example of the real interface or result, optionally with one close-up, using the plugin's exact UI labels; keep important content about 32 units from the edges. The export rules above apply, so outline every word into paths. Check that it stays readable at its displayed width in light and dark themes.
|
||||
|
||||
## Review
|
||||
|
||||
1. Deliver the plugin with one icon first. Show a few numbered SVG alternatives only when the user asks for alternatives or refinement; keep their numbers through review and apply the chosen one. Write alternatives outside the bundle directory.
|
||||
2. Compare the new icon, and the old one when revising, beside unchanged installed icons in light and dark themes, at actual row and card sizes as well as enlarged. Check balance, lettering, empty space, clipping, and that the image decodes. Without browser control, report that rendered display remains unverified.
|
||||
3. After installation, verify the rendered icon in every affected bundle and plugin row through the display checklist.
|
||||
+3
-8
@@ -1,11 +1,6 @@
|
||||
---
|
||||
name: cordis-composition-reference
|
||||
description: Use when writing or reading a Cordis bundle patch or agent preset for this harness and you need the Loader YAML dialect (insert, override by id, group, disabled, isolate, !!js) or the list of installable Harness plugin packages and what each provides.
|
||||
---
|
||||
|
||||
# Cordis composition reference
|
||||
|
||||
Reference material for bundle patches and preset plugin lists. Procedures live in `cordis-plugin-development` and `editing-cordis-compositions`.
|
||||
Reference material for bundle patches and preset plugin lists. Procedures live in `references/plugin-development.md` and `references/compositions.md`.
|
||||
|
||||
## Loader patch dialect
|
||||
|
||||
@@ -22,8 +17,8 @@ A row has `id`, `name` (the plugin package specifier; inserted relative paths ar
|
||||
- `!!js` scalars are Loader expressions, never `!js`. Inside `config` they are evaluated after the row's declared injections activate, against that plugin's context (`ctx.<service>`), so `!!js dshHomePath('sessions')` and `!!js "!ctx.get('profileContext')"` are valid. Other row metadata stays literal.
|
||||
- `isolate` maps service names to `true` or a realm label; a preset plugin that provides a service isolates the provider and all consumers together. Scope controls contributions and event visibility; `isolate` controls service instances.
|
||||
|
||||
`plugin_manager` `list_plugins` reports each row's `enabled` flag and `fiberPhase`; `set_plugin` and `set_bundle` answer `overridden` when a higher-priority layer wins.
|
||||
`plugin_manager` `list_plugins`, or **Plugins** without it, reports each row's `enabled` flag and `fiberPhase`; `set_plugin` and `set_bundle` answer `overridden` when a higher-priority layer wins.
|
||||
|
||||
## Installable plugin packages
|
||||
|
||||
`references/packages.md` lists every workspace package that exports a Cordis plugin, grouped by package group, with whether its row takes `config`. Search it with `grep -n <keyword>` rather than reading it whole. Plugins outside this list come from installed bundles; `plugin_manager` `list_bundles` names them.
|
||||
`references/packages.md` lists every workspace package that exports a Cordis plugin, one table per package group, with whether its row takes `config`. Read it in parts with the file-read tool's offset and limit rather than whole. Plugins outside this list come from installed bundles; `plugin_manager` `list_bundles` names them.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Editing Cordis compositions
|
||||
|
||||
Agent presets are ordinary `@deepseek-ai/dsh-agent-preset` declarations carried by bundle patches. Nothing edits a declaration in place: a preset is created or changed by installing a bundle whose patch declares or overrides it. This file states the declaration format; when it leaves a question open, read the `@deepseek-ai/dsh-agent-preset` README and source; `references/locate-docs.md` finds its package directory.
|
||||
|
||||
## Where declarations live
|
||||
|
||||
The shipped Web presets are `presets/<id>.patch.yml` files of the `@deepseek-ai/dsh-web-app` bundle, ids `standard`, `ptc`, `minimal` and `cordis`. Installed, the bundle resolves from the dsh installation, not the profile; `references/locate-docs.md` finds its package directory, which is `packages/bundle/web-app/` in a source checkout. Read one file with the file-read tool when you need a template; `minimal.patch.yml` is the shortest. In Desktop the bundle sits inside `app.asar`; read it with the file-read tool. Read `references/composition-reference.md` for the patch dialect and `references/packages.md` for the plugin packages a preset can mount.
|
||||
|
||||
A declaration row has these `config` fields: `id` (required, lowercase letters, digits and hyphens), `plugins` (required Cordis entry list), and optional `name`, `description` and `order` (roster position). The Loader row `id` is `preset-<id>` by convention.
|
||||
|
||||
## Create a preset
|
||||
|
||||
Write a bundle directory in the workspace with exactly two files, then install it.
|
||||
|
||||
`review-preset/package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@local/dsh-review-preset",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
|
||||
}
|
||||
```
|
||||
|
||||
`review-preset/cordis.patch.yml`:
|
||||
|
||||
```yaml
|
||||
- insert:
|
||||
- id: preset-review
|
||||
name: '@deepseek-ai/dsh-agent-preset'
|
||||
config:
|
||||
id: review
|
||||
name: Review
|
||||
description: Reviews changes with the shell only.
|
||||
order: 10
|
||||
plugins:
|
||||
- id: persona
|
||||
name: '@deepseek-ai/dsh-persona'
|
||||
config:
|
||||
prefix: You review software changes.
|
||||
- id: tool-bash
|
||||
name: '@deepseek-ai/dsh-tool-bash'
|
||||
```
|
||||
|
||||
Install with `plugin_manager`, `action: install_bundle`, `target` set to the absolute bundle directory. It runs package installation and bundle selection itself; do not reproduce those steps with shell commands. Without `plugin_manager`, follow the fallback in `references/plugin-development.md`.
|
||||
|
||||
## Change a shipped preset
|
||||
|
||||
Override the declaration by its Loader row id instead of inserting. The override replaces the complete `config`, so restate `id`, `plugins` and every other field the shipped file carries:
|
||||
|
||||
```yaml
|
||||
- id: preset-standard
|
||||
name: '@deepseek-ai/dsh-agent-preset'
|
||||
config:
|
||||
id: standard
|
||||
order: 1
|
||||
plugins:
|
||||
# the shipped list with your changes
|
||||
```
|
||||
|
||||
## Migrate a legacy preset
|
||||
|
||||
Before declaration rows, a user preset was a directory `$DSH_HOME/.agent-presets/<id>/` holding `preset.yml` (display `name`, `description`, `order`) and `agent.cordis.yml` (the plugin entry list). Nothing reads that directory any more. To migrate one, create a bundle as above whose declaration takes `id` from the directory name, `name`, `description`, and `order` from `preset.yml`, and `plugins` from `agent.cordis.yml` verbatim; check each plugin name against `references/packages.md` because packages renamed since the preset was written fail at activation. Install it, verify the row, then delete the legacy directory.
|
||||
|
||||
## Verify
|
||||
|
||||
`plugin_manager` `list_bundles` lists the installed bundle and `list_plugins` the `preset-<id>` row with its activation state; without `plugin_manager`, **Plugins** shows both. A declaration whose activation fails stays on the roster with its diagnostic and cannot compose a session until the bundle is fixed and reinstalled. Existing sessions and their children keep the plugin revision they started with; validate changed behavior in a new session. Installing a bundle executes plugin code in the Host process, so it requires Full access or approval.
|
||||
|
||||
## Choose plugin placement
|
||||
|
||||
Host plugins supply shared services: tools and prompt registries, the Agent loop, sessions, persistence, settings, sandbox policy, model routes, and subagent backends. Preset plugins contribute scoped tools, persona, prompt sections, and policies to those registries. Preset revisions are eagerly activated once and shared by their selecting Agents.
|
||||
|
||||
A preset plugin that supplies a service must isolate the provider and all its consumers in the same realm. A service consumed by Host plugins belongs in the Host configuration. Scope controls contributions and event visibility; `isolate` controls service instances. Use ordinary Cordis groups for nested plugin lists. Keep `!!js` expressions only in plugin configuration or `disabled`; the Loader evaluates them when activating the child plugin. Resolve assets from installed packages rather than a preset directory.
|
||||
|
||||
## Extend the Host
|
||||
|
||||
For new plugin code or profile-wide capabilities, follow `references/plugin-development.md`, author a workspace bundle, and install it with `plugin_manager`. When `cordis_inspect_list` and `cordis_inspect_query` are available, inspect APIs and a mounted plugin's Config schema through the Host `Config` provider; those tools do not invoke Remote methods. Verify the installed capability before reporting completion.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Persist your own configuration
|
||||
|
||||
Plugin code never persists configuration by reading, filtering, and rewriting the active profile's `cordis.patch.yml`, and never locates that file by walking up from the package directory. That file is not your bundle's patch: it belongs to the user and holds other plugins' `insert` rows, comments, and `!!js` expressions. To change its own configuration after `apply` returns, a plugin uses the config editor:
|
||||
|
||||
```js
|
||||
const entry = ctx.fiber.entry
|
||||
const editor = ctx.get('configEditor')
|
||||
if (entry === undefined || editor === undefined) throw new Error('Configuration cannot be saved in this profile')
|
||||
await editor.edit(entry, current => ({ ...current, field: value }))
|
||||
```
|
||||
|
||||
`change` returns the row's complete config. The editor keeps the rest of the file, validates the candidate, serializes the write with other profile changes, and rejects values that a higher layer overrides. Report a rejection or a missing editor to the user instead of claiming the value was saved. Editing an ordinary field restarts the plugin so `apply` rebuilds its state; a field declared `.volatile()` updates in place and is read with `config.field.get()`. Store secrets, such as a token from an in-app sign-in or binding flow, as `ctx.credentials.modifyRecord()` records, not configuration; declare `credentials` in `inject` or read it with `ctx.get('credentials')`, and see the `@deepseek-ai/dsh-credentials` README for record keys.
|
||||
+10
-18
@@ -26,31 +26,32 @@ A Host-only bundle needs no dependencies, install scripts, or build tool:
|
||||
config: {}
|
||||
```
|
||||
|
||||
## Display metadata and icon
|
||||
## Display metadata, detail document, and icon
|
||||
|
||||
Plugin Manager and Settings read `meta.title` and `meta.description` from exported locale JSON and an icon from exported resources without activating plugins. Complete this checklist before installation:
|
||||
Plugin Manager and Settings read `meta.title` and `meta.description` from exported locale JSON and an icon from exported resources without activating plugins. The bundle's page in Plugin Manager shows the detail document that `meta.detail` names, otherwise the package README. Complete this checklist before installation:
|
||||
|
||||
- Write a recognizable title and a description of the capability in `locale/en.json` under `meta.title` and `meta.description`. Add the same fields for the user's language and other supported locales, such as `locale/zh.json`; do not leave template copy unrelated to the delivered plugin. Write English titles and other UI labels in sentence case: capitalize only the first word and proper nouns, as in `Git worktrees`.
|
||||
- Create an original icon or use artwork whose license permits redistribution, retaining any required attribution.
|
||||
- Export `./locale/*.json` and `./icon`; retain existing runtime exports. Keep the patch, locales, icon, and every runtime file in `files`, updating it whenever you add modules or assets. For a packed or published bundle, verify the actual packed file list. Local directory installation links the checkout instead, so check the files directly; `files` does not filter a linked directory.
|
||||
- Write a detail document for users in each locale's language, and name it with `meta.detail` in that locale file: a `/`-separated path relative to the package root, inside a subdirectory so images beside it are published, that ends in `.md`, such as `docs/DETAIL.md` for `en` and `docs/DETAIL.zh.md` for `zh`. For bundles delivered with this skill, start with one paragraph on what the user gets, then `## How to use` (where to find or trigger the feature, with its exact UI labels) and `## Good to know` (added tokens or model requests, data read or sent elsewhere, risks, and what changes when the plugin is turned off); Chinese documents use `## 使用方法` and `## 注意事项`. This is the delivery structure, not a Markdown format enforced by the renderer. State only behavior you implemented and verified. The page omits raw HTML and renders relative links as plain text; reference images relative to the document. An optional feature image goes on the first line; see `references/artwork.md`. A malformed `meta.detail`, a missing named file, or a document exceeding `pluginManager.detailMaxBytes` (1 MiB by default) makes the detail section show the failure with **Retry** instead of falling back to the README.
|
||||
- Create an original icon or use artwork whose license permits redistribution, retaining any required attribution. Read `references/artwork.md` before drawing or revising an icon.
|
||||
- Export `./locale/*.json` and `./icon`; retain existing runtime exports. Keep the patch, locales, the detail document's directory, icon, and every runtime file in `files`, updating it whenever you add modules or assets. For a packed or published bundle, verify the actual packed file list. Local directory installation links the checkout instead, so check the files directly; `files` does not filter a linked directory.
|
||||
- Check that the icon is a valid image of the declared format and satisfies the path and size limits below. An accepted filename alone does not establish that its bytes render.
|
||||
|
||||
For example, the locale file contains:
|
||||
|
||||
```json
|
||||
{ "meta": { "title": "My decoration", "description": "Draws a badge under the composer." } }
|
||||
{ "meta": { "title": "My decoration", "description": "Draws a badge under the composer.", "detail": "docs/DETAIL.md" } }
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"exports": { "./locale/*.json": "./locale/*.json", "./icon": "./icon.svg" },
|
||||
"files": ["index.js", "cordis.patch.yml", "locale/*.json", "icon.svg"]
|
||||
"files": ["index.js", "cordis.patch.yml", "locale/*.json", "docs", "icon.svg"]
|
||||
}
|
||||
```
|
||||
|
||||
A package-root plugin may instead declare a top-level `icon` in `package.json`; it takes priority over `./icon` and is a path relative to the manifest directory. A subpath plugin such as `my-plugins/search` is not a package and never reads a `package.json`; it exports `./search/locale/*.json` and `./search/icon` instead. Icons may be SVG, PNG, JPEG, or WebP up to 256 KiB and must stay inside the package; absolute paths, URLs, and symlinks leaving it are rejected. Missing fields of a package-root plugin fall back to `package.json` `name` and `description`, and missing images use the panel's default artwork; malformed metadata produces a diagnostic and keeps the valid text.
|
||||
|
||||
After installation, verify the intended title and description in bundle details and plugin rows, plus the rendered icons, in English and the user's locale where supplied. Check for metadata diagnostics and unintended fallbacks, and that each plugin row shows its own exported icon or, when it has none, the generic artwork. Without browser control, inspect the installed resources and report that rendered display remains unverified; do not claim visual success from installation alone.
|
||||
After installation, verify the intended title, description, and detail document in bundle details and plugin rows, plus the rendered icons, in English and the user's locale where supplied. Check for metadata diagnostics and unintended fallbacks, and that each plugin row shows its own exported icon or, when it has none, the generic artwork. Without browser control, inspect the installed resources and report that rendered display remains unverified; do not claim visual success from installation alone.
|
||||
|
||||
An existing plugin's metadata may remain unchanged when it still describes the requested result. A disposable test fixture or an explicitly requested metadata-free package may omit resources, but explain each omission in the delivery report. A Host-only or configuration-only bundle still has a visible inventory entry; neither is an exception by itself.
|
||||
|
||||
@@ -61,20 +62,11 @@ An existing plugin's metadata may remain unchanged when it still describes the r
|
||||
- `export function apply(ctx, config) {}` with optional `export const inject = ['tools']` and `export const Config`.
|
||||
- A service class as the default export.
|
||||
|
||||
Register every resource inside `apply` with `ctx.effect` or `ctx.on` and return its cleanup. A plugin that declares `Config` validates the row's `config` at activation; query `Config.listConfigs` for an installed plugin's schema before writing its `config`, and follow `$defs` references in the returned document.
|
||||
Register every resource inside `apply` with `ctx.effect` or `ctx.on` and return its cleanup. A plugin that declares `Config` validates the row's `config` at activation; before writing an installed plugin's `config`, read its schema from `Config.listConfigs` through `cordis_inspect_query`, following `$defs` references, or from the owning package's README and source when inspection is unavailable.
|
||||
|
||||
## Persist your own configuration
|
||||
|
||||
Plugin code never persists configuration by reading, filtering, and rewriting the active profile's `cordis.patch.yml`, and never locates that file by walking up from the package directory. That file is not your bundle's patch: it belongs to the user and holds other plugins' `insert` rows, comments, and `!!js` expressions. To change its own configuration after `apply` returns, a plugin uses the config editor:
|
||||
|
||||
```js
|
||||
const entry = ctx.fiber.entry
|
||||
const editor = ctx.get('configEditor')
|
||||
if (entry === undefined || editor === undefined) throw new Error('Configuration cannot be saved in this profile')
|
||||
await editor.edit(entry, current => ({ ...current, field: value }))
|
||||
```
|
||||
|
||||
`change` returns the row's complete config. The editor keeps the rest of the file, validates the candidate, serializes the write with other profile changes, and rejects values that a higher layer overrides. Report a rejection or a missing editor to the user instead of claiming the value was saved. Editing an ordinary field restarts the plugin so `apply` rebuilds its state; a field declared `.volatile()` updates in place and is read with `config.field.get()`. Store secrets, such as a token from an in-app sign-in or binding flow, as `ctx.credentials.modifyRecord()` records, not configuration; declare `credentials` in `inject` or read it with `ctx.get('credentials')`, and see the `@deepseek-ai/dsh-credentials` README for record keys.
|
||||
Read `references/configuration.md` before saving plugin configuration or credentials.
|
||||
|
||||
## Install, enable, and observe
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# Locate documentation and sources
|
||||
|
||||
Answer for the running version, and name the files that support each answer. Read files with the file-read tool, which also opens files inside Desktop's `app.asar`, and use its offset and limit for long files such as `references/packages.md`.
|
||||
|
||||
## Version
|
||||
|
||||
The `version` in `package.json` under `DSH_INSTALL_DIR`, described below, is the running DSH version. Without that variable, use the source checkout's version, or `../../package.json` relative to this skill's base directory, which is the version of the `@deepseek-ai/dsh-agent-preset` package that ships this skill, and state which file the answer used.
|
||||
|
||||
## Documentation
|
||||
|
||||
Every shell call of a profile-launched DSH receives `DSH_INSTALL_DIR`, the directory of the `@deepseek-ai/dsh` package; in Desktop it lies inside `app.asar`. Print it with `echo "$DSH_INSTALL_DIR"` in bash or `$env:DSH_INSTALL_DIR` in PowerShell. Its `docs/` holds this version's documentation and the upgrade guides with their index, `docs/upgrade-guide/README.md`.
|
||||
|
||||
In a source checkout, `DSH_INSTALL_DIR` is the checkout's `apps/cli` and has no `docs/`. A base directory ending in `packages/preset/agent-preset/skills/dsh-doc` with `pnpm-workspace.yaml` five levels up identifies the checkout root; read its `docs/user/index.md`, `packages/README.md`, `packages/<group>/<name>/`, and `docs/upgrade-guide/` directly. The command below resolves only packages that the installation's `node_modules` can reach.
|
||||
|
||||
When `DSH_INSTALL_DIR` is unset and the base directory does not identify a source checkout, DSH was started without a profile and its documentation cannot be located; say so.
|
||||
|
||||
## Package directories
|
||||
|
||||
With inspection tools, `cordis_inspect_query` `Config.listConfigs` filtered by `name` lists a mounted package's entries, and querying one `entry` returns its `packageDir`. Otherwise, resolve a package that the installation ships from `DSH_INSTALL_DIR` with the runtime in `DSH_NODE_EXECUTABLE`, the executable running DSH. In Desktop that is the Electron executable, which runs as Node only with `ELECTRON_RUN_AS_NODE=1`; plain Node ignores the setting. In bash:
|
||||
|
||||
```sh
|
||||
ELECTRON_RUN_AS_NODE=1 "$DSH_NODE_EXECUTABLE" -e "console.log(require('node:path').dirname(require.resolve(process.argv[1] + '/package.json', { paths: [process.env.DSH_INSTALL_DIR] })))" @deepseek-ai/dsh-tool-bash
|
||||
```
|
||||
|
||||
In PowerShell, start the runtime as a process with redirected output: Desktop's Electron executable on Windows is a GUI program that the `&` operator does not wait for. Replace `$script` and `$arguments` for other reads:
|
||||
|
||||
```powershell
|
||||
$script = @'
|
||||
console.log(require('node:path').dirname(require.resolve(process.argv[1] + '/package.json', { paths: [process.env.DSH_INSTALL_DIR] })))
|
||||
'@
|
||||
$arguments = @('@deepseek-ai/dsh-tool-bash')
|
||||
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
|
||||
$start = [System.Diagnostics.ProcessStartInfo]::new($env:DSH_NODE_EXECUTABLE)
|
||||
foreach ($argument in @('-e', $script, '--') + $arguments) { $start.ArgumentList.Add($argument) }
|
||||
$start.Environment['ELECTRON_RUN_AS_NODE'] = '1'
|
||||
$start.UseShellExecute = $false
|
||||
$start.RedirectStandardOutput = $true
|
||||
$start.RedirectStandardError = $true
|
||||
$start.StandardOutputEncoding = [System.Text.Encoding]::UTF8
|
||||
$start.StandardErrorEncoding = [System.Text.Encoding]::UTF8
|
||||
$process = [System.Diagnostics.Process]::Start($start)
|
||||
$stderr = $process.StandardError.ReadToEndAsync()
|
||||
$stdout = $process.StandardOutput.ReadToEnd()
|
||||
$process.WaitForExit()
|
||||
[Console]::Out.Write($stdout)
|
||||
[Console]::Error.Write($stderr.Result)
|
||||
exit $process.ExitCode
|
||||
```
|
||||
|
||||
When `DSH_NODE_EXECUTABLE` is unset, DSH runs as a single executable whose packages are not on disk; do not substitute a `node` from `PATH`, and report package behavior as unverified. When neither inspection nor these variables locate a package, report its behavior as unverified instead of guessing a path.
|
||||
|
||||
A package directory holds `README.md`, `src/`, and built `lib/`. Read the README first, then the `src/` file that owns the behavior.
|
||||
|
||||
## Bounded reads
|
||||
|
||||
Read one file at a time. Native utilities such as `ls`, `cat`, glob, and search cannot open `app.asar`; there, list a directory by running the same runtime through the shell with `require('node:fs').readdirSync(dir).slice(0, 200)`. Elsewhere, search only a narrow directory with a specific pattern. Do not list or read whole package trees. When a needed file is missing in the installed version, say so instead of answering from another version.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Connect an MCP server
|
||||
|
||||
Read `templates/mcp/` with the file-read tool and write its files into your bundle directory. A configuration-only bundle's manifest needs a unique name, version, and `dsh.bundle.patch`, but no Host/Client entry files. Its patch, `templates/mcp/cordis.patch.yml`, inserts the already installed `@deepseek-ai/dsh-mcp-client` with `serverName`, `transport: streamable-http`, `url`, and `failOnStartupError: true`.
|
||||
|
||||
Replace the endpoint, install the bundle through `plugin_manager` or the fallback in `references/plugin-development.md`, then call `mcp__demo__ping` or another newly available `mcp__<serverName>__<tool>` tool to verify the connection. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`; `Config.listConfigs` on the installed row, through `cordis_inspect_query` when available, or the `@deepseek-ai/dsh-mcp-client` README returns the complete client schema. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates.
|
||||
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
This file is GENERATED from workspace manifests (`scripts/gen-plugin-packages.ts`) and verified fresh by `pnpm run verify-plugin-packages` (part of `doc-sync`); do not edit it by hand.
|
||||
|
||||
Every package below exports a Cordis plugin that a bundle patch can name in a Loader row. `Config` marks packages whose row accepts a `config` mapping; query `Config.listConfigs` through `cordis_inspect_query` (filter by `name`, then query the `entry` id) for the mounted schema. Packages under `experimental` are pre-stable.
|
||||
Every package below exports a Cordis plugin that a bundle patch can name in a Loader row. `Config` marks packages whose row accepts a `config` mapping; read the mounted schema from `Config.listConfigs` through `cordis_inspect_query` (filter by `name`, then query the `entry` id) when available, otherwise from the package README. Packages under `experimental` are pre-stable.
|
||||
|
||||
## acp
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Persistent Harness plugins
|
||||
|
||||
A plugin change is a bundle: author its package in ordinary workspace files, then install it with `plugin_manager` `action: install_bundle` and the absolute package directory as `target`. Changes affect every session in the profile and survive restart. Read `references/compositions.md` for agent preset changes.
|
||||
|
||||
Do not write the profile's `package.json` or `cordis.patch.yml`, create packages under `$DSH_HOME`, or run pnpm in the profile directory: `install_bundle` performs those steps, and each hand-made write outside the workspace needs its own approval. Every `plugin_manager` action, including `list_plugins` and `list_bundles`, also needs approval without Full access, so call it only when its result decides the next step. When `plugin_manager` is not among your tools, finish the bundle in the workspace, then tell the user its directory and that **Plugins** > **Add plugin** installs a local directory; do not change a preset to gain the tool.
|
||||
|
||||
## Design or review
|
||||
|
||||
Read the applicable references and check the proposed or existing plugin against current APIs. Report design choices or findings. Do not write files, install bundles, or change profile state unless the user requests implementation.
|
||||
|
||||
## Enable a shipped plugin
|
||||
|
||||
A shipped bundle can resolve a plugin row and leave it `disabled`. The row id and its reason are in the shipped patch, `packages/bundle/*/cordis.patch.yml` in a source checkout. Write a workspace bundle whose patch overrides that row with `disabled: false` and inserts the Host rows it depends on; a source checkout's `apps/cli/config/examples/<feature>/cordis.yml` lists them for opt-in features. Packages shipped with dsh resolve from the dsh installation, so the bundle declares no dependencies on them. Install it with `install_bundle`.
|
||||
|
||||
## Deliver a working plugin first
|
||||
|
||||
1. Resolve the requested result and where it appears in DSH; when the place is unclear, ask. Choose reasonable details and implement a small first version; install it before visual refinement.
|
||||
2. Discover only the APIs needed for that version. With inspection tools, call `cordis_inspect_list`, then targeted `cordis_inspect_query` calls; for UI, query Client `Slots.listSubTree` and the selected slot's registration options and props. Without them, read the owning package README and source as `references/locate-docs.md` describes, and report that live registration was not inspected. For anything beyond a static decoration, such as tool policy, agent context, session-derived state, or Chat rows, read `references/practices.md` before choosing the extension point; for a user action in plugin UI, also read `references/user-actions.md`.
|
||||
3. Copy the matching template files into one workspace directory, or author the package, patch, and required Host/Client files there. Before installing, complete the display checklist in `references/host-plugin.md`: localized titles, descriptions, and detail documents, an original or licensed icon, and exported resources with distribution checks where applicable. This applies to Host-only and configuration-only bundles too; adapt template text and artwork to the request. Check JavaScript syntax and the manifest, then install. Use the installed plugin as the first preview; do not create preview HTML, mock shells, design variants, screenshot scripts, or rasterizer tooling first.
|
||||
4. Read the installation result; when the user installed the bundle, ask them to confirm its row in **Plugins**, verify in a new session, and report what remained unverified. `application` and `warnings` decide whether the change is live, not logs, process lists, or the page's boot payload. Confirm new rows with approval-free `cordis_inspect_query` when available, not `list_plugins`. After `application: applied`, exercise the capability or inspect the live Client registration. Verify installed display metadata and the icon using `references/host-plugin.md`. Use the connected page when available; follow `references/verification.md` for page and panel checks and unavailable browser control, and `references/user-actions.md` for user actions. Restore user state changed during testing. Report verification limits; installation and slot registration alone do not establish what the user sees.
|
||||
5. For a new plugin or a change to its user experience, run the user experience review in `references/verification.md`.
|
||||
6. Fix observed defects in the same plugin. When the requested result works, finish with its location, verification status, and the reason for any display-resource exception; never silently accept default artwork. Do not continue speculative variants, optional features, or mock previews. Close any task list.
|
||||
|
||||
## Profile facts
|
||||
|
||||
`DSH_PROFILE` (profile name) and `DSH_PROFILE_DIR` (its directory, whose `node_modules` holds only profile-installed bundles) are set in every shell call of a profile-launched Harness and absent when the Harness was booted without a profile. Bash reads them as `$DSH_PROFILE`; PowerShell reads them as `$env:DSH_PROFILE`. With `dsh` on the PATH, `dsh --profile "$DSH_PROFILE" --dump-config` prints the composed profile. Bundled packages resolve from the dsh installation and profile-installed bundles from the profile, so never guess a package path from `$DSH_PROFILE_DIR`.
|
||||
+4
-4
@@ -1,6 +1,6 @@
|
||||
# Harness plugin practices
|
||||
|
||||
These rules follow from Harness mechanisms. Confirm every Service method, Event name, and dispatch mode named here with `cordis_inspect_query` (`Service`, `Event`) before relying on it; the installed Harness is the authority.
|
||||
These rules follow from Harness mechanisms. Confirm every Service method, Event name, and dispatch mode named here before relying on it, through `cordis_inspect_query` (`Service`, `Event`) when available or the owning package's README and source; the installed Harness is the authority.
|
||||
|
||||
## Principles
|
||||
|
||||
@@ -9,7 +9,7 @@ These rules follow from Harness mechanisms. Confirm every Service method, Event
|
||||
3. **The framework drives; the plugin computes.** Session projections, Conversation assembly, and slot rendering subscribe, cache, and publish for you. A plugin that subscribes, rescans, or writes DOM itself bypasses that incremental machinery.
|
||||
4. **Extension points are shared; use the weakest mechanism that suffices.** From weakest to strongest: `ctx.tools.restrict()` can only remove tools; `ctx.tools.guard()` can only deny; waterfall listeners can rewrite and depend on registration order; `system-prompt/assemble` replaces the whole assembly. The stronger the mechanism, the more of other plugins' contributions you must preserve.
|
||||
5. **Other plugins and other Harness versions read your data.** Unknown event types, older readers, and older cached state meet what you write; declare compatibility with the envelope fields and versions the Harness provides.
|
||||
6. **Plugin UI is part of the Harness UI.** Users see one application, so a plugin uses the host's theme tokens, locale, and layout patterns, and matches the look and behavior of host components. Whether that is possible is decided by where the UI renders, so choose the rendering surface before writing any view; later styling inside the wrong surface cannot recover consistency.
|
||||
6. **Plugin UI is part of the Harness UI.** Users see one application, so a plugin uses the host's theme tokens, locale, and layout patterns, and matches the look and behavior of host components. Choose the rendering surface before writing any view; styling inside the wrong surface cannot recover consistency.
|
||||
|
||||
## Stability
|
||||
|
||||
@@ -31,8 +31,8 @@ These rules follow from Harness mechanisms. Confirm every Service method, Event
|
||||
## UI
|
||||
|
||||
- Render plugin pages as React components in a slot. Do not serve an HTML page from the Host and embed it in an iframe: an iframe document does not receive the host's theme tokens, light/dark switching, or `ctx.locale`.
|
||||
- Style with the theme tokens that `cordis_inspect_query` `Theme` lists (`--dsw-alias-*`); literal colors are for artwork only. Tokens are the lowest-risk way to match the host: a renamed token degrades appearance but never breaks rendering. Copy spacing, type sizes, and row patterns from an existing host page of the same kind; the Plugin Manager page is the reference for management lists.
|
||||
- Do not `require('@deepseek-ai/dsh-client-ui-primitives')` or load any other Harness Client package as a module; `dsh.client.inject` entries only order activation and stay allowed. They change without notice, a plain-JS plugin has no type check, and a throwing component blanks your slot entry (console: `slot entry crashed in '<slot>'`). Write your own controls and match the host instead: copy markup, CSS, and behavior from the primitive into the plugin (`src/*.tsx` and `*.module.css` in a DSH source checkout, or the installed package's `lib/index.js` and `lib/**/*.css`), or inspect the rendered host control in the connected page. Rename copied classes under your plugin's prefix, keep only `--dsw-alias-*` token references, and keep the behavior that users rely on, such as Modal focus and Escape handling, `role="switch"` with `aria-checked`, and Tooltip placement. Tokens then remain the only shared styling dependency.
|
||||
- Style with the theme tokens (`--dsw-alias-*`) that `cordis_inspect_query` `Theme` lists when available; literal colors are for artwork only. A renamed token degrades appearance but never breaks rendering. Copy spacing, type sizes, and row patterns from an existing host page of the same kind; the Plugin Manager page is the reference for management lists.
|
||||
- Do not `require('@deepseek-ai/dsh-client-ui-primitives')` or load any other Harness Client package as a module; `dsh.client.inject` entries only order activation and stay allowed. They change without notice, and a throwing component blanks your slot entry (console: `slot entry crashed in '<slot>'`). Write your own controls instead: copy markup, CSS, and behavior from the primitive's `src/*.tsx` and `*.module.css`, or from the rendered host control in the connected page. Rename copied classes under your plugin's prefix, keep only `--dsw-alias-*` token references, and keep behavior users rely on, such as Modal focus and Escape handling, `role="switch"` with `aria-checked`, and Tooltip placement.
|
||||
- Contribute through slots: `ctx.slots.inject(ownerKey, () => ctx.slots.register(...))`. The callback's registrations are disposed when the owning declaration collapses and reinstalled when it returns. Read session data through the slot props' selector hooks, subscribing to the smallest slice. Do not write DOM outside your component or append to `document.body`.
|
||||
- Add a Chat row by registering an event definition with `ctx.uiConversation.events.register()` and its view in the `conversation.chat.node` slot under the definition's `kind`, which is the renderer key; the Conversation layer owns paging, Turn and Step placement, and incremental assembly.
|
||||
- When the Client needs a value derived from a session, declare `wire.view` on the Host projection. The value reaches the Client already computed; the Client does not fold session events itself.
|
||||
-5
@@ -1,8 +1,3 @@
|
||||
---
|
||||
name: agent-experience
|
||||
description: Use when writing or changing a model-facing tool definition (name, description, parameter schema, or its system-prompt section), and when designing skills, context loading, or multi-step workflows, to make information discoverable and use context efficiently.
|
||||
---
|
||||
|
||||
- **Start with minimal context:** expose purpose, available actions, and constraints first; load detailed instructions when needed.
|
||||
- **Make discovery explicit:** every deferred resource needs a clear description and a reliable way to retrieve it.
|
||||
- **Keep critical constraints visible:** permissions, destructive effects, and required validation should appear before the relevant action.
|
||||
+1
-1
@@ -8,6 +8,6 @@ Read `templates/decoration/` with the file-read tool and write its files into yo
|
||||
|
||||
The browser artifact registers a lazy factory whose id equals the package name. React comes from the browser module table; no duplicate React installation, CDN script, or UMD search is needed. For compiled sources, use the deployment's Client build tooling to emit this format; declare non-baseline runtime imports in `dsh.client.external`.
|
||||
|
||||
`templates/decoration/client.js` registers a lazy factory into `conversation.composer.dock` through `ctx.slots.inject` and `ctx.slots.register`; follow the selected slot's props and options from `Slots.listSubTree` when you change the slot.
|
||||
`templates/decoration/client.js` registers a lazy factory into `conversation.composer.dock` through `ctx.slots.inject` and `ctx.slots.register`; follow the selected slot's props and options from `Slots.listSubTree` through `cordis_inspect_query` when available, otherwise from the owning package's README and source, when you change the slot.
|
||||
|
||||
Keep factories free of side effects. Register styles, timers, listeners and other resources inside `apply` with `ctx.effect`/`ctx.on` and return their cleanup functions. Component-local styles can render as React elements so unmounting removes them. Verify disposal for resources you add. Inherit the host theme for containers and controls; artwork may use its own colors. A page or panel beyond a decoration follows the UI rules in `references/practices.md`. Route visible UI text through the Client locale service. Do not replace the app root or append a second application to `document.body`. Do not read another plugin's DOM, stylesheet, or component source to estimate placement; choose a slot that already allocates space.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Upgrade across DSH releases
|
||||
|
||||
DSH upgrade guides describe breaks in DSH surfaces: commands, profile and `cordis.yml` keys, plugin configuration, package exports, services, events, Client slots, and persisted data. A third-party plugin's own changelog is separate; read it from that plugin's package or repository.
|
||||
|
||||
When the user asks what an upgrade affects, report the applicable guides and their migration steps. Apply a migration only when the user asks to change files or the profile.
|
||||
|
||||
## Choose the guides
|
||||
|
||||
1. Target version: the running installation's version from `references/locate-docs.md`, unless the user names another target.
|
||||
2. Starting version: an exact version from the user, the old installation, a lockfile, or the plugin's history. A manifest range such as `engines.dsh` or a `@deepseek-ai/dsh-*` dependency range only bounds the candidates; never report it as the starting version. Without an exact version, continue with the candidate directories and check each guide against the plugin's code and the target's APIs. Ask only when the migration order or data safety depends on the exact starting version.
|
||||
3. Affected surfaces: the packages the plugin imports or names in its patch, and the configuration fields, services, events, slots, commands, and stored data it uses.
|
||||
4. Version directories: `upgrade-guide/v<T>/` describes the upgrade from release vT to the release after it; vT is the release being left, not the target. From vA to a released vB, work through the directories from vA up to, but not including, vB, one adjacent step at a time in release order.
|
||||
5. Checkouts and prerelease builds: when the target is a checkout or unreleased build whose version is vB, `upgrade-guide/vB/` holds breaks made after vB that the target may already contain; check each such guide against the target's code. Likewise, when the starting point is a checkout or build at vA, check each `vA/` guide against the plugin's code; it may already be applied.
|
||||
|
||||
## Find and read them
|
||||
|
||||
- Installed DSH: `docs/upgrade-guide/README.md` under the installation directory lists every guide in one `## v<T>` section per version directory, with a summary and English and Chinese paths. The index and its sections can exceed one read, so first print its section headings with their line numbers, then read each chosen section at most 12 lines per call with the file-read tool's offset and limit. With the runtime from `references/locate-docs.md`, in bash, or in PowerShell through its process form with this script and the index path as the argument:
|
||||
|
||||
```sh
|
||||
ELECTRON_RUN_AS_NODE=1 "$DSH_NODE_EXECUTABLE" -e "require('node:fs').readFileSync(process.argv[1], 'utf8').split(/\r?\n/).forEach((line, index) => { if (line.startsWith('## ')) console.log(index + 1, line) })" "$DSH_INSTALL_DIR/docs/upgrade-guide/README.md"
|
||||
```
|
||||
Without that runtime, read the index 12 lines per call from its start.
|
||||
- Source checkout: the repository has no such index. Read the `description` line at the top of each `docs/upgrade-guide/v<T>/<item>/guide.md` in the chosen directories.
|
||||
|
||||
Read only the `guide.md`, or `guide.zh.md` for a Chinese-speaking user, of items that change a surface from step 3. Report the guides used and the ones skipped with the reason. When a needed guide or the documentation directory is missing, say so instead of answering from another version.
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# User actions and agent tools
|
||||
|
||||
Expose the plugin UI's operations on application data and configuration to the agent. Pure view interactions, such as switching tabs or expanding details, do not need tools. Confirm the Host entry points and tools you use with `cordis_inspect_query` before relying on them.
|
||||
Expose the plugin UI's operations on application data and configuration to the agent. Pure view interactions, such as switching tabs or expanding details, do not need tools. Confirm the Host entry points and tools you use with `cordis_inspect_query` when available, otherwise in the owning package's README and source, before relying on them.
|
||||
|
||||
## One operation, two callers
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Verify in the available environment
|
||||
|
||||
Prefer the authenticated page already connected to Harness. Do not launch a separate browser from shell commands, change `HOME`, inspect personal browser profiles, search for authentication tokens, or alter keychains to obtain a screenshot. For a visual-only request without browser control, limit verification to JavaScript syntax, manifest validation, and, with inspection tools, the live Client slot, then report that visual verification remains unavailable. Before or after installation, do not search for rasterizers, invoke Quick Look, extract SVG into preview files, emulate React/DOM, or implement a custom renderer to compensate for missing browser control. A screenshot of a mock page is not verification of the running plugin.
|
||||
|
||||
For a page or panel, verify that styles use only theme tokens, the plugin imports no Harness Client package such as `@deepseek-ai/dsh-client-ui-primitives`, the console shows no slot entry crash, and the view reads correctly in light and dark themes beside a comparable host page. Scale verification to the change's risk.
|
||||
|
||||
For any test subprocess or temporary resource, use a unique owned directory, bound execution, and await cleanup. A failed optional preview must not turn into environment repair or block installation.
|
||||
|
||||
## User experience review
|
||||
|
||||
Before delivering a new plugin or a change to its user experience, run one UI/UX expert review through a subagent; without a subagent tool, perform the same review yourself and say so. Give the reviewer the user's goal, the plugin's location, and the available running-UI evidence. Ask it to check discoverability, the main user flow, feedback, and visual consistency. Apply the verification limits above when browser control is unavailable, and report any review or verification that could not run. Fix substantiated issues within the requested scope and verify the affected behavior before finishing.
|
||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,10 @@
|
||||
A blue circle appears below the message composer in every session.
|
||||
|
||||
## How to use
|
||||
|
||||
- Open any session; the circle is below the message box.
|
||||
|
||||
## Good to know
|
||||
|
||||
- The circle is a decoration only. It adds nothing to model requests.
|
||||
- Turning the plugin off removes the circle from open pages.
|
||||
@@ -0,0 +1,3 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
|
||||
<circle cx="18" cy="18" r="10" fill="#247bbf"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 141 B |
File renamed without changes.
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Komponistendekoration",
|
||||
"description": "Zeigt einen blauen Kreis unter dem Nachrichtenersteller an."
|
||||
"description": "Zeigt einen blauen Kreis unter dem Nachrichtenersteller an.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Composer decoration",
|
||||
"description": "Displays a blue circle below the message composer."
|
||||
"description": "Displays a blue circle below the message composer.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Decoración del compositor",
|
||||
"description": "Muestra un círculo azul debajo del redactor del mensaje."
|
||||
"description": "Muestra un círculo azul debajo del redactor del mensaje.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Décoration du compositeur",
|
||||
"description": "Affiche un cercle bleu sous le compositeur du message."
|
||||
"description": "Affiche un cercle bleu sous le compositeur du message.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "入力欄の装飾",
|
||||
"description": "メッセージ入力欄の下に青い円を表示します。"
|
||||
"description": "メッセージ入力欄の下に青い円を表示します。",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Decoração do compositor",
|
||||
"description": "Exibe um círculo azul abaixo do compositor da mensagem."
|
||||
"description": "Exibe um círculo azul abaixo do compositor da mensagem.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Композиторское украшение",
|
||||
"description": "Отображает синий кружок под составителем сообщения."
|
||||
"description": "Отображает синий кружок под составителем сообщения.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -9,7 +9,7 @@
|
||||
"./locale/*.json": "./locale/*.json",
|
||||
"./icon": "./icon.svg"
|
||||
},
|
||||
"files": ["index.js", "client.js", "cordis.patch.yml", "locale/*.json", "icon.svg"],
|
||||
"files": ["index.js", "client.js", "cordis.patch.yml", "locale/*.json", "docs", "icon.svg"],
|
||||
"dsh": {
|
||||
"bundle": { "patch": "./cordis.patch.yml" },
|
||||
"client": {
|
||||
File renamed without changes.
@@ -0,0 +1,11 @@
|
||||
Agents can call the tools of the Demo MCP server.
|
||||
|
||||
## How to use
|
||||
|
||||
- Ask the agent for a task that the server's tools perform. The agent decides when to call them.
|
||||
|
||||
## Good to know
|
||||
|
||||
- The server's tools and any instructions it sends are added to every model request, so they use some tokens even when the agent does not call them.
|
||||
- Tool arguments the agent chooses are sent to the server, and its replies are added to the conversation.
|
||||
- Turning the plugin off removes the tools from the agent's next request; that request cannot reuse cached input.
|
||||
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
|
||||
<rect x="7" y="12" width="7" height="12" rx="2" fill="#247bbf"/>
|
||||
<rect x="22" y="12" width="7" height="12" rx="2" fill="#247bbf"/>
|
||||
<path d="M14 18h8m-3-3 3 3-3 3" fill="none" stroke="#247bbf" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 355 B |
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Demo-MCP-Verbindung",
|
||||
"description": "Verbindet einen Remote-MCP-Server, um seine Tools dem Agenten zur Verfügung zu stellen."
|
||||
"description": "Verbindet einen Remote-MCP-Server, um seine Tools dem Agenten zur Verfügung zu stellen.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Demo MCP connection",
|
||||
"description": "Connects a remote MCP server to make its tools available to the agent."
|
||||
"description": "Connects a remote MCP server to make its tools available to the agent.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Conexión de demostración MCP",
|
||||
"description": "Conecta un servidor MCP remoto para que sus herramientas estén disponibles para el agente."
|
||||
"description": "Conecta un servidor MCP remoto para que sus herramientas estén disponibles para el agente.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Démo connexion MCP",
|
||||
"description": "Connecte un serveur MCP distant pour mettre ses outils à disposition de l'agent."
|
||||
"description": "Connecte un serveur MCP distant pour mettre ses outils à disposition de l'agent.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "MCP 接続デモ",
|
||||
"description": "リモート MCP サーバーに接続し、そのツールをエージェントが使用できるようにします。"
|
||||
"description": "リモート MCP サーバーに接続し、そのツールをエージェントが使用できるようにします。",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Conexão de demonstração MCP",
|
||||
"description": "Conecta um servidor MCP remoto para disponibilizar suas ferramentas ao agente."
|
||||
"description": "Conecta um servidor MCP remoto para disponibilizar suas ferramentas ao agente.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Демо-соединение MCP",
|
||||
"description": "Подключает удаленный сервер MCP, чтобы сделать его инструменты доступными для агента."
|
||||
"description": "Подключает удаленный сервер MCP, чтобы сделать его инструменты доступными для агента.",
|
||||
"detail": "docs/DETAIL.md"
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -4,6 +4,6 @@
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"exports": { "./locale/*.json": "./locale/*.json", "./icon": "./icon.svg" },
|
||||
"files": ["cordis.patch.yml", "locale/*.json", "icon.svg"],
|
||||
"files": ["cordis.patch.yml", "locale/*.json", "docs", "icon.svg"],
|
||||
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
|
||||
}
|
||||
@@ -1,27 +1,33 @@
|
||||
/**
|
||||
* Shipped creator skills: every rendered skill stays below the pruner threshold, referenced
|
||||
* files exist, templates parse, and no skill bans reading DSH sources.
|
||||
* The shipped dsh-doc skill: it is the package's only skill, renders below the pruner threshold, and
|
||||
* names exactly the files it ships; its templates parse and show their detail documents, and it never
|
||||
* bans reading DSH sources. The Web preset e2e measures whole-reference reads.
|
||||
*/
|
||||
import { execFileSync } from 'node:child_process'
|
||||
import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs'
|
||||
import { dirname, join, matchesGlob, resolve } from 'node:path'
|
||||
import { execFileSync, spawnSync } from 'node:child_process'
|
||||
import { cpSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join, resolve, sep } from 'node:path'
|
||||
import { Context } from '@deepseek-ai/cordis'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import * as yaml from 'js-yaml'
|
||||
import { entryListSchema } from '@deepseek-ai/cordis-plugin-include'
|
||||
import { codePointLength } from '@deepseek-ai/dsh-compaction-tool-result-pruner'
|
||||
import { languageChain, localFiles, readPackageDocument } from '@deepseek-ai/dsh-plugin-detail'
|
||||
import SkillRegistry, { renderSkillContent } from '@deepseek-ai/dsh-skill'
|
||||
import * as SkillFileSystem from '@deepseek-ai/dsh-skill-filesystem'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { describe, expect, it, type TestContext } from 'vitest'
|
||||
import { JSDOM } from 'jsdom'
|
||||
import { packageMetaProblems } from '../../../../scripts/verify-package-meta.ts'
|
||||
|
||||
const skills = fileURLToPath(new URL('../skills/', import.meta.url))
|
||||
const names = readdirSync(skills)
|
||||
|
||||
/**
|
||||
* `packages/bundle/web-app/presets/standard.patch.yml` prunes a tool result only above `thresholdChars: 8192`
|
||||
* code points; a skill result below it reaches the model intact.
|
||||
*/
|
||||
const PRUNER_THRESHOLD_CHARS = 8192
|
||||
/** Fixture read budget, independent of Plugin Manager deployment limits. */
|
||||
const TEST_DOCUMENT_MAX_BYTES = 1 << 20
|
||||
|
||||
/** The body the `skill` tool returns: the file without its YAML frontmatter. */
|
||||
function body(name: string): string {
|
||||
@@ -36,61 +42,50 @@ function markdownFiles(dir: string): string[] {
|
||||
.map(file => join(dir, file))
|
||||
}
|
||||
|
||||
describe('the shipped creator skills', () => {
|
||||
describe('the shipped dsh-doc skill', () => {
|
||||
const skill = join(skills, 'dsh-doc')
|
||||
const templates = join(skill, 'templates')
|
||||
const repositorySkills = fileURLToPath(new URL('../../../../.agents/skills/', import.meta.url))
|
||||
const alias = join(repositorySkills, 'agent-experience/SKILL.md')
|
||||
const canonical = join(skills, 'agent-experience/SKILL.md')
|
||||
|
||||
it('keeps agent-experience in the package with a repository alias, not a second copy', () => {
|
||||
expect(names).toContain('agent-experience')
|
||||
expect(lstatSync(canonical).isFile()).toBe(true)
|
||||
const linked = lstatSync(alias).isSymbolicLink()
|
||||
// Git can materialize link targets as plain files on Windows with core.symlinks=false.
|
||||
if (!linked) expect(process.platform).toBe('win32')
|
||||
const target = linked ? readlinkSync(alias) : readFileSync(alias, 'utf8').trim()
|
||||
expect(resolve(dirname(alias), target)).toBe(canonical)
|
||||
})
|
||||
|
||||
it.for(['package', 'repository'] as const)('loads agent-experience from the %s skill root', async (source, test) => {
|
||||
if (source === 'repository' && process.platform === 'win32' && !lstatSync(alias).isSymbolicLink()) {
|
||||
test.skip(true, 'Repository discovery requires a checkout with symbolic links enabled.')
|
||||
}
|
||||
async function loadRoot(root: string, test: TestContext) {
|
||||
const ctx = new Context()
|
||||
test.onTestFinished(() => ctx.fiber.dispose())
|
||||
await ctx.plugin(SkillRegistry)
|
||||
await ctx.plugin(SkillFileSystem, {
|
||||
includeDefaultRoots: false, watch: false,
|
||||
customSkillDirs: [source === 'package' ? skills : repositorySkills],
|
||||
await ctx.plugin(SkillFileSystem, { includeDefaultRoots: false, watch: false, customSkillDirs: [root] })
|
||||
return ctx
|
||||
}
|
||||
|
||||
it('is the only skill the package skill root exposes', async (test) => {
|
||||
const ctx = await loadRoot(skills, test)
|
||||
expect((await ctx.skills.list()).map(entry => entry.name)).toEqual(['dsh-doc'])
|
||||
expect((await ctx.skills.get('dsh-doc'))?.content).toBe(body('dsh-doc').trim())
|
||||
})
|
||||
|
||||
it('leaves repository skills without a second dsh-doc and wraps the packaged tool-design reference', async (test) => {
|
||||
const ctx = await loadRoot(repositorySkills, test)
|
||||
const repository = (await ctx.skills.list()).map(entry => entry.name)
|
||||
expect(repository).not.toContain('dsh-doc')
|
||||
expect(repository).toEqual(expect.arrayContaining(['dsh-doc-writing', 'agent-experience']))
|
||||
const wrapper = join(repositorySkills, 'agent-experience', 'SKILL.md')
|
||||
expect(lstatSync(wrapper).isFile()).toBe(true)
|
||||
const link = /\]\(([^)]+tool-design\.md)\)/u.exec(readFileSync(wrapper, 'utf8'))?.[1]
|
||||
expect(link && resolve(dirname(wrapper), link)).toBe(join(skill, 'references', 'tool-design.md'))
|
||||
})
|
||||
|
||||
it('renders below the pruner threshold and lists exactly the files it ships', () => {
|
||||
const rendered = renderSkillContent({
|
||||
name: 'dsh-doc', provider: 'filesystem', resourceBase: { kind: 'directory', path: skill }, content: body('dsh-doc'),
|
||||
})
|
||||
expect((await ctx.skills.list()).map(skill => skill.name)).toContain('agent-experience')
|
||||
const loaded = await ctx.skills.get('agent-experience')
|
||||
expect(loaded?.path).toBe(realpathSync(canonical))
|
||||
expect(loaded?.content).toBe(body('agent-experience').trim())
|
||||
})
|
||||
|
||||
it('render below the pruner threshold and name only files that exist', () => {
|
||||
for (const name of names) {
|
||||
const rendered = renderSkillContent({
|
||||
name, provider: 'filesystem', resourceBase: { kind: 'directory', path: join(skills, name) }, content: body(name),
|
||||
})
|
||||
expect(codePointLength(rendered), name).toBeLessThan(PRUNER_THRESHOLD_CHARS)
|
||||
const referenced = [...body(name).matchAll(/`((?:references|templates)\/[^`]+)`/g)].map(match => match[1] ?? match[0])
|
||||
for (const path of referenced) expect(() => statSync(join(skills, name, path)), `${name}: ${path}`).not.toThrow()
|
||||
}
|
||||
})
|
||||
|
||||
it('keep whole-file plugin references below the pruner threshold with read line numbers', () => {
|
||||
const references = join(skills, 'cordis-plugin-development', 'references')
|
||||
for (const file of readdirSync(references)) {
|
||||
const lines = readFileSync(join(references, file), 'utf8').split('\n')
|
||||
// The read tool renders each line as `${number}: ${text}`.
|
||||
const numbered = lines.map((text, index) => `${String(index + 1)}: ${text}`).join('\n')
|
||||
expect(codePointLength(numbered), file).toBeLessThan(PRUNER_THRESHOLD_CHARS)
|
||||
}
|
||||
expect(codePointLength(rendered)).toBeLessThan(PRUNER_THRESHOLD_CHARS)
|
||||
const referenced = new Set([...body('dsh-doc').matchAll(/`((?:references|templates)\/[^`]+)`/g)].map(match => match[1] ?? match[0]))
|
||||
const shipped = readdirSync(skill, { recursive: true, encoding: 'utf8' })
|
||||
.filter(file => file !== 'SKILL.md' && statSync(join(skill, file)).isFile())
|
||||
.map(file => file.split(sep).join('/'))
|
||||
.map(file => file.replace(/(templates\/[^/]+\/locale)\/[^/]+$/u, '$1'))
|
||||
expect([...referenced].sort()).toEqual([...new Set(shipped)].sort())
|
||||
})
|
||||
|
||||
it('ship templates whose manifest, patch, and JavaScript parse', () => {
|
||||
const templates = join(skills, 'cordis-plugin-development', 'templates')
|
||||
for (const name of readdirSync(templates)) {
|
||||
const dir = join(templates, name)
|
||||
const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { dsh: { bundle: { patch: string } } }
|
||||
@@ -103,7 +98,6 @@ describe('the shipped creator skills', () => {
|
||||
})
|
||||
|
||||
it('ships discoverable, exported, packaged display resources with every plugin template', () => {
|
||||
const templates = join(skills, 'cordis-plugin-development', 'templates')
|
||||
for (const name of readdirSync(templates)) {
|
||||
const dir = join(templates, name)
|
||||
const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {
|
||||
@@ -112,35 +106,130 @@ describe('the shipped creator skills', () => {
|
||||
dsh: { bundle: { patch: string } }
|
||||
}
|
||||
expect(manifest).not.toHaveProperty('icon')
|
||||
expect(manifest.files).toContain('docs')
|
||||
const runtimeFiles = [manifest.dsh.bundle.patch, manifest.exports['.'], manifest.exports['./client']]
|
||||
.filter((file): file is string => file !== undefined).map(file => file.replace(/^\.\//u, ''))
|
||||
for (const file of runtimeFiles) expect(manifest.files, file).toContain(file)
|
||||
expect(manifest.exports['./locale/*.json']).toBe('./locale/*.json')
|
||||
// The package-meta gate validates these resources through the real metadata reader.
|
||||
expect(manifest.exports['./icon']).toBe('./icon.svg')
|
||||
const locales = readdirSync(join(dir, 'locale')).map(file => `locale/${file}`)
|
||||
expect(locales).toContain('locale/en.json')
|
||||
const english = JSON.parse(readFileSync(join(dir, 'locale', 'en.json'), 'utf8')) as { meta: Record<string, string> }
|
||||
const details: string[] = []
|
||||
for (const file of locales) {
|
||||
const locale = JSON.parse(readFileSync(join(dir, file), 'utf8')) as { meta: { title: string; description: string } }
|
||||
const locale = JSON.parse(readFileSync(join(dir, file), 'utf8')) as {
|
||||
meta: { title: string; description: string; detail: string }
|
||||
}
|
||||
expect(Object.keys(locale.meta).sort(), file).toEqual(Object.keys(english.meta).sort())
|
||||
expect(locale.meta.title).toMatch(/\S/u)
|
||||
expect(locale.meta.description).toMatch(/\S/u)
|
||||
expect(locale.meta.detail, file).toMatch(/^[^/]+\/.+\.md$/u)
|
||||
details.push(locale.meta.detail)
|
||||
}
|
||||
const resources = new Set([...Object.values(manifest.exports).filter(file => !file.includes('*')),
|
||||
...locales, manifest.dsh.bundle.patch])
|
||||
...locales, ...details, manifest.dsh.bundle.patch])
|
||||
for (const resource of resources) {
|
||||
const file = resource.replace(/^\.\//u, '')
|
||||
expect(body('cordis-plugin-development'), file).toContain(`\`templates/${name}/${file.startsWith('locale/') ? 'locale' : file}\``)
|
||||
expect(body('dsh-doc'), file).toContain(`\`templates/${name}/${file.startsWith('locale/') ? 'locale' : file}\``)
|
||||
expect(statSync(join(dir, file)).isFile(), file).toBe(true)
|
||||
if (file !== 'package.json') expect(manifest.files.some(pattern => matchesGlob(file, pattern)), file).toBe(true)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
it('never forbid reading DSH package sources and never route skill files through the shell', () => {
|
||||
for (const name of names) {
|
||||
for (const file of markdownFiles(join(skills, name))) {
|
||||
const text = readFileSync(file, 'utf8')
|
||||
expect(text, file).not.toMatch(/do not read (DSH |package |DSH package )?sources/i)
|
||||
// Desktop ships the skill directory inside app.asar, which only the Host process can open.
|
||||
expect(text, file).not.toMatch(/`(cat|cp|ls) /)
|
||||
it('publishes template metadata through the same package check as CI', (test) => {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-template-meta-'))
|
||||
test.onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
|
||||
for (const name of readdirSync(templates)) {
|
||||
const destination = join(root, 'packages', 'templates', name)
|
||||
cpSync(join(templates, name), destination, { recursive: true })
|
||||
}
|
||||
expect(packageMetaProblems(root)).toEqual([])
|
||||
})
|
||||
|
||||
it('uses a 36-unit canvas for each template icon', () => {
|
||||
const { window } = new JSDOM()
|
||||
try {
|
||||
for (const name of readdirSync(templates)) {
|
||||
const document = new window.DOMParser().parseFromString(readFileSync(join(templates, name, 'icon.svg'), 'utf8'), 'image/svg+xml')
|
||||
expect(document.querySelector('parsererror'), name).toBeNull()
|
||||
const svg = document.documentElement
|
||||
expect(svg.localName, name).toBe('svg')
|
||||
expect(svg.getAttribute('width'), name).toBe('36')
|
||||
expect(svg.getAttribute('height'), name).toBe('36')
|
||||
expect(svg.getAttribute('viewBox'), name).toBe('0 0 36 36')
|
||||
}
|
||||
} finally { window.close() }
|
||||
})
|
||||
|
||||
it.for(readdirSync(join(skills, 'dsh-doc', 'templates')))('shows the %s template detail document on its bundle page', async (name) => {
|
||||
const dir = join(templates, name)
|
||||
const locale = JSON.parse(readFileSync(join(dir, 'locale', 'en.json'), 'utf8')) as { meta: { detail: string } }
|
||||
for (const file of readdirSync(join(dir, 'locale'))) {
|
||||
const document = await readPackageDocument(localFiles(dir, '1.0.0'), '', languageChain(file.replace(/\.json$/u, '')), TEST_DOCUMENT_MAX_BYTES, AbortSignal.timeout(10_000))
|
||||
expect(document, file).toMatchObject({ origin: 'locale', path: locale.meta.detail })
|
||||
expect(document?.markdown, file).toMatch(/\n## How to use\n[\s\S]*\n## Good to know\n/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('names only shipped files and no retired skill in any of its documents', () => {
|
||||
for (const file of markdownFiles(skill)) {
|
||||
const text = readFileSync(file, 'utf8')
|
||||
for (const match of text.matchAll(/`((?:references|templates)\/[^`]+)`/g)) {
|
||||
expect(() => statSync(join(skill, match[1] ?? '')), `${file}: ${match[1] ?? ''}`).not.toThrow()
|
||||
}
|
||||
expect(text, file).not.toMatch(/cordis-plugin-development|editing-cordis-compositions|cordis-composition-reference|agent-experience/u)
|
||||
}
|
||||
})
|
||||
|
||||
// The commands target bash; Windows Desktop is directed to the file-read tool instead.
|
||||
it.skipIf(process.platform === 'win32')('documents shell commands that locate a package and list upgrade index sections', (test) => {
|
||||
const install = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-doc-commands-')))
|
||||
test.onTestFinished(() => { rmSync(install, { recursive: true, force: true }) })
|
||||
const pkg = join(install, 'node_modules', '@deepseek-ai', 'dsh-tool-bash')
|
||||
mkdirSync(pkg, { recursive: true })
|
||||
writeFileSync(join(pkg, 'package.json'), '{"name":"@deepseek-ai/dsh-tool-bash"}\n')
|
||||
mkdirSync(join(install, 'docs', 'upgrade-guide'), { recursive: true })
|
||||
writeFileSync(join(install, 'docs', 'upgrade-guide', 'README.md'), '# Upgrade guides\r\n\r\n## v2.0.0\r\n\r\n| row |\n## v1.0.0\n')
|
||||
const run = (file: string) => {
|
||||
const command = /```sh\n\s*(.+)\n\s*```/u.exec(readFileSync(join(skill, 'references', file), 'utf8'))?.[1]
|
||||
expect(command, file).toBeDefined()
|
||||
return execFileSync('bash', ['-c', command ?? ''], {
|
||||
encoding: 'utf8', env: { ...process.env, DSH_INSTALL_DIR: install, DSH_NODE_EXECUTABLE: process.execPath },
|
||||
})
|
||||
}
|
||||
expect(run('locate-docs.md').trim()).toBe(pkg)
|
||||
expect(run('upgrading.md')).toBe('3 ## v2.0.0\n6 ## v1.0.0\n')
|
||||
})
|
||||
|
||||
// Desktop's real Electron and archive run in apps/desktop/tests/installed-docs-asar.built.e2e.ts.
|
||||
it.skipIf(spawnSync('pwsh', ['-NoProfile', '-Command', 'exit 0']).status !== 0)('documents a PowerShell process form that waits for the runtime', (test) => {
|
||||
const install = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-doc-pwsh-')))
|
||||
test.onTestFinished(() => { rmSync(install, { recursive: true, force: true }) })
|
||||
const pkg = join(install, 'node_modules', '@deepseek-ai', 'dsh-tool-bash')
|
||||
mkdirSync(pkg, { recursive: true })
|
||||
writeFileSync(join(pkg, 'package.json'), '{"name":"@deepseek-ai/dsh-tool-bash"}\n')
|
||||
const command = /```powershell\n([\s\S]+?)\n```/u.exec(readFileSync(join(skill, 'references', 'locate-docs.md'), 'utf8'))?.[1]
|
||||
expect(command).toBeDefined()
|
||||
const run = (script: string) => spawnSync('pwsh', ['-NoProfile', '-NonInteractive', '-Command', script], {
|
||||
encoding: 'utf8', env: { ...process.env, DSH_INSTALL_DIR: install, DSH_NODE_EXECUTABLE: process.execPath },
|
||||
})
|
||||
const found = run(command ?? '')
|
||||
expect(found.status, found.stderr).toBe(0)
|
||||
expect(found.stdout.trim()).toBe(pkg)
|
||||
// A failing script keeps its exit code and writes its error to stderr only.
|
||||
const missing = run((command ?? '').replace("'@deepseek-ai/dsh-tool-bash'", "'@deepseek-ai/dsh-missing'"))
|
||||
expect(missing.status).not.toBe(0)
|
||||
expect(missing.stdout).toBe('')
|
||||
expect(missing.stderr).toContain('@deepseek-ai/dsh-missing')
|
||||
})
|
||||
|
||||
it('never forbid reading DSH package sources and never route skill files through the shell', () => {
|
||||
for (const file of markdownFiles(skill)) {
|
||||
const text = readFileSync(file, 'utf8')
|
||||
expect(text, file).not.toMatch(/do not read (DSH |package |DSH package )?sources/i)
|
||||
// Desktop ships the skill directory inside app.asar, which only the Host process can open.
|
||||
expect(text, file).not.toMatch(/`(cat|cp|ls) /)
|
||||
}
|
||||
})
|
||||
})
|
||||
Generated
+3
@@ -13918,6 +13918,9 @@ importers:
|
||||
'@deepseek-ai/dsh-compaction-tool-result-pruner':
|
||||
specifier: workspace:*
|
||||
version: link:../../compaction/compaction-tool-result-pruner
|
||||
'@deepseek-ai/dsh-plugin-detail':
|
||||
specifier: workspace:*
|
||||
version: link:../../util/plugin-detail
|
||||
'@deepseek-ai/dsh-skill':
|
||||
specifier: workspace:*
|
||||
version: link:../../skill/skill
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/**
|
||||
* Quick comprehensive documentation-standard tests: the reference example
|
||||
* stays valid, the consolidated `dsh-doc` skill carries no stale copied
|
||||
* stays valid, the consolidated `dsh-doc-writing` skill carries no stale copied
|
||||
* website values or prototype-era language, and the kind system maps each
|
||||
* label to exactly one skill template. Session release records match the
|
||||
* writer bound, bilingual counterpart, and evidence links. These run in `pnpm run test` and
|
||||
@@ -38,14 +38,14 @@ function packageReadmes(): string[] {
|
||||
* or a document whose kind does not match its position fails here.
|
||||
*/
|
||||
const KIND_TEMPLATES: Readonly<Record<string, string>> = {
|
||||
'package-group': '.agents/skills/dsh-doc/templates/package-group.md',
|
||||
'package-reference': '.agents/skills/dsh-doc/templates/package-reference.md',
|
||||
'package-library': '.agents/skills/dsh-doc/templates/package-library.md',
|
||||
'package-bundle': '.agents/skills/dsh-doc/templates/package-bundle.md',
|
||||
'persistence-change': '.agents/skills/dsh-doc/templates/persistence-change.md',
|
||||
'persistence-release': '.agents/skills/dsh-doc/templates/persistence-release.md',
|
||||
'persistence-format': '.agents/skills/dsh-doc/templates/persistence-format.md',
|
||||
'upgrade-guide': '.agents/skills/dsh-doc/templates/upgrade-guide.md',
|
||||
'package-group': '.agents/skills/dsh-doc-writing/templates/package-group.md',
|
||||
'package-reference': '.agents/skills/dsh-doc-writing/templates/package-reference.md',
|
||||
'package-library': '.agents/skills/dsh-doc-writing/templates/package-library.md',
|
||||
'package-bundle': '.agents/skills/dsh-doc-writing/templates/package-bundle.md',
|
||||
'persistence-change': '.agents/skills/dsh-doc-writing/templates/persistence-change.md',
|
||||
'persistence-release': '.agents/skills/dsh-doc-writing/templates/persistence-release.md',
|
||||
'persistence-format': '.agents/skills/dsh-doc-writing/templates/persistence-format.md',
|
||||
'upgrade-guide': '.agents/skills/dsh-doc-writing/templates/upgrade-guide.md',
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -304,15 +304,15 @@ describe('Session format release authority', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('dsh-doc skill consolidation', () => {
|
||||
describe('dsh-doc-writing skill consolidation', () => {
|
||||
it('carries no prototype-era language', () => {
|
||||
const files = [
|
||||
'.agents/skills/dsh-doc/SKILL.md',
|
||||
'.agents/skills/dsh-doc/references/metadata-links-i18n.md',
|
||||
'.agents/skills/dsh-doc/references/structure-hierarchy.md',
|
||||
'.agents/skills/dsh-doc/references/style.md',
|
||||
'.agents/skills/dsh-doc/references/review.md',
|
||||
'.agents/skills/dsh-doc/references/website-sync.md',
|
||||
'.agents/skills/dsh-doc-writing/SKILL.md',
|
||||
'.agents/skills/dsh-doc-writing/references/metadata-links-i18n.md',
|
||||
'.agents/skills/dsh-doc-writing/references/structure-hierarchy.md',
|
||||
'.agents/skills/dsh-doc-writing/references/style.md',
|
||||
'.agents/skills/dsh-doc-writing/references/review.md',
|
||||
'.agents/skills/dsh-doc-writing/references/website-sync.md',
|
||||
]
|
||||
for (const file of files) {
|
||||
const source = readFileSync(resolve(root, file), 'utf8')
|
||||
@@ -321,20 +321,20 @@ describe('dsh-doc skill consolidation', () => {
|
||||
})
|
||||
|
||||
it('copies no stale website sidebar or section-owner values', () => {
|
||||
const source = readFileSync(resolve(root, '.agents/skills/dsh-doc/references/website-sync.md'), 'utf8')
|
||||
const source = readFileSync(resolve(root, '.agents/skills/dsh-doc-writing/references/website-sync.md'), 'utf8')
|
||||
expect(source).not.toContain('en-docs')
|
||||
expect(source).not.toContain('sectionOrder')
|
||||
})
|
||||
|
||||
it('keeps the reference example linked from the skill', () => {
|
||||
const skill = readFileSync(resolve(root, '.agents/skills/dsh-doc/SKILL.md'), 'utf8')
|
||||
const skill = readFileSync(resolve(root, '.agents/skills/dsh-doc-writing/SKILL.md'), 'utf8')
|
||||
expect(skill).toContain('session-persistence-jsonl/README.md')
|
||||
expect(skill).toContain('session-persistence-jsonl/README.zh.md')
|
||||
})
|
||||
|
||||
it('defines controlled English as a precision-preserving review discipline', () => {
|
||||
const skill = readFileSync(resolve(root, '.agents/skills/dsh-doc/SKILL.md'), 'utf8')
|
||||
const style = readFileSync(resolve(root, '.agents/skills/dsh-doc/references/style.md'), 'utf8')
|
||||
const skill = readFileSync(resolve(root, '.agents/skills/dsh-doc-writing/SKILL.md'), 'utf8')
|
||||
const style = readFileSync(resolve(root, '.agents/skills/dsh-doc-writing/references/style.md'), 'utf8')
|
||||
expect(skill).toContain('references/style.md#controlled-technical-english')
|
||||
expect(style).toContain('not certified ASD-STE100 compliance')
|
||||
expect(style).toContain('review prompts, not mechanical gates')
|
||||
@@ -342,7 +342,7 @@ describe('dsh-doc skill consolidation', () => {
|
||||
})
|
||||
|
||||
it('maps every kind label to exactly one skill template that exists', () => {
|
||||
const templateFiles = globSync('.agents/skills/dsh-doc/templates/*.md', { cwd: root }).map(path => path.split(sep).join('/')).sort()
|
||||
const templateFiles = globSync('.agents/skills/dsh-doc-writing/templates/*.md', { cwd: root }).map(path => path.split(sep).join('/')).sort()
|
||||
const registered = Object.values(KIND_TEMPLATES).sort()
|
||||
expect(templateFiles).toEqual(registered)
|
||||
for (const [kind, template] of Object.entries(KIND_TEMPLATES)) {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/**
|
||||
* Generate the loadable-plugin package list shipped inside the
|
||||
* `cordis-composition-reference` skill from the workspace manifests and the
|
||||
* `dsh-doc` skill from the workspace manifests and the
|
||||
* config-catalog classification. `--check` exits 1 when the committed file is stale.
|
||||
*/
|
||||
|
||||
@@ -9,7 +9,7 @@ import { resolve } from 'node:path'
|
||||
import { collectConfigCatalog, type CatalogEntry } from './gen-config-catalog.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
const OUT = 'packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md'
|
||||
const OUT = 'packages/preset/agent-preset/skills/dsh-doc/references/packages.md'
|
||||
|
||||
interface Row {
|
||||
pkg: string
|
||||
@@ -42,7 +42,7 @@ export function render(entries: readonly CatalogEntry[]): string {
|
||||
'',
|
||||
'This file is GENERATED from workspace manifests (`scripts/gen-plugin-packages.ts`) and verified fresh by `pnpm run verify-plugin-packages` (part of `doc-sync`); do not edit it by hand.',
|
||||
'',
|
||||
'Every package below exports a Cordis plugin that a bundle patch can name in a Loader row. `Config` marks packages whose row accepts a `config` mapping; query `Config.listConfigs` through `cordis_inspect_query` (filter by `name`, then query the `entry` id) for the mounted schema. Packages under `experimental` are pre-stable.',
|
||||
'Every package below exports a Cordis plugin that a bundle patch can name in a Loader row. `Config` marks packages whose row accepts a `config` mapping; read the mounted schema from `Config.listConfigs` through `cordis_inspect_query` (filter by `name`, then query the `entry` id) when available, otherwise from the package README. Packages under `experimental` are pre-stable.',
|
||||
'',
|
||||
]
|
||||
let group = ''
|
||||
|
||||
@@ -24,7 +24,7 @@ describe('package README Summary limit', () => {
|
||||
const summary = Array.from({ length: MAX_PACKAGE_README_SUMMARY_WORDS + 1 }, () => 'word').join(' ')
|
||||
|
||||
expect(packageReadmeSummaryErrors('packages/example/example/README.md', readme(summary, kind))).toEqual([
|
||||
`packages/example/example/README.md: Summary has 101 words; the limit is 100. Read .agents/skills/dsh-doc/SKILL.md and .agents/skills/dsh-doc/templates/${kind}.md before rewriting it.`,
|
||||
`packages/example/example/README.md: Summary has 101 words; the limit is 100. Read .agents/skills/dsh-doc-writing/SKILL.md and .agents/skills/dsh-doc-writing/templates/${kind}.md before rewriting it.`,
|
||||
])
|
||||
})
|
||||
|
||||
|
||||
@@ -46,10 +46,10 @@ export function packageReadmeSummaryErrors(file: string, source: string): string
|
||||
|
||||
const kind = readKind(source)
|
||||
const template = kind === undefined
|
||||
? '.agents/skills/dsh-doc/templates/'
|
||||
: `.agents/skills/dsh-doc/templates/${kind}.md`
|
||||
? '.agents/skills/dsh-doc-writing/templates/'
|
||||
: `.agents/skills/dsh-doc-writing/templates/${kind}.md`
|
||||
return [
|
||||
`${file}: Summary has ${String(words)} words; the limit is ${String(MAX_PACKAGE_README_SUMMARY_WORDS)}. Read .agents/skills/dsh-doc/SKILL.md and ${template} before rewriting it.`,
|
||||
`${file}: Summary has ${String(words)} words; the limit is ${String(MAX_PACKAGE_README_SUMMARY_WORDS)}. Read .agents/skills/dsh-doc-writing/SKILL.md and ${template} before rewriting it.`,
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
{"type":"session","version":4,"id":"{{session:1}}","createdAt":1783654655599,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
|
||||
{"type":"permission/preset","data":{"preset":"danger-full-access"}}
|
||||
{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
|
||||
{"type":"approval/policy","data":{"policy":"never"}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Load dsh-doc, read .dsh/skills/dsh-doc/references/artwork.md and .dsh/skills/dsh-doc/references/host-plugin.md with read, then reply DONE. Do not install plugins or modify files."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
|
||||
{"type":"turn/start","data":{"turn":1}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"step/start","data":{"turn":1,"step":1}}
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Load dsh-doc, read .dsh/skills/dsh-doc/references/artwork.md and .dsh/skills/dsh-doc/references/host-plugin.md with read, then reply DONE. Do not install plugins or modify files."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"<system-reminder>\nThe following information describes your current session:\n\nCurrent working directory: \"{{cwd}}\".\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are the root agent. Your name is \"lead\".\n\nTo message other agents, use send_message({ agent: \"<agent-name>\", message: \"...\" }).\nUse list_agents({}) to find your collaborator agents and their names.\n</system-reminder>"}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"working-directory:current","text":"Current working directory: \"{{cwd}}\"."},{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:identity","text":"You are the root agent. Your name is \"lead\".\n\nTo message other agents, use send_message({ agent: \"<agent-name>\", message: \"...\" }).\nUse list_agents({}) to find your collaborator agents and their names."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"<system-reminder>\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n<available_skills>\n- `dsh-doc`: Use when a task needs facts about DeepSeek Harness (DSH) itself, such as how a feature, setting, plugin, agent preset, tool, or Cordis API of the running installation works; when the user asks to design, review, build, install, enable, or debug a DSH plugin, bundle, MCP connection, agent preset, plugin icon or detail page, or a DSH tool definition or skill; and when upgrading a plugin or profile to a newer DSH release. Loading it grants no permission to change files or the profile.\n</available_skills>\n\nIf 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.\nA user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.\n</system-reminder>"}],"source":{"kind":"skill-catalog","form":"catalog","entries":[{"name":"dsh-doc","description":"Use when a task needs facts about DeepSeek Harness (DSH) itself, such as how a feature, setting, plugin, agent preset, tool, or Cordis API of the running installation works; when the user asks to design, review, build, install, enable, or debug a DSH plugin, bundle, MCP connection, agent preset, plugin icon or detail page, or a DSH tool definition or skill; and when upgrading a plugin or profile to a newer DSH release. Loading it grants no permission to change files or the profile."}]},"role":"user","id":"{{message:4}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
|
||||
{"type":"session/title","data":{"title":"Load dsh-doc, read .dsh/skills/dsh-doc/r","messageSeqs":[8],"source":{"kind":"fallback"}}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Load the requested skill."},{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"dsh-doc\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5},"stream":[{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430688,"index":0,"dt":[],"texts":["Load the requested skill."]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699430688,"index":1,"dt":[],"id":"call_skill_load","name":"skill","args":["{\"name\":\"dsh-doc\"}"]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Load the requested skill."}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"dsh-doc\"}"}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"usage","usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_skill_load","name":"skill","arguments":"{\"name\":\"dsh-doc\"}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_skill_load"},"toolCallId":"call_skill_load","content":[{"type":"text","text":"<skill_content name=\"dsh-doc\">\n<skill_resources>\nBase directory for this skill: {{cwd}}/.dsh/skills/dsh-doc\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n</skill_resources>\n\n<skill_instructions>\n# DeepSeek Harness documentation\n\nAnswer questions about DSH from the documentation and source of the installed version, not from memory, and extend DSH through bundles installed in the current profile.\n\nLoading this skill does not authorize changes. Write bundle files, run mutating `plugin_manager` actions such as installing, enabling, disabling, or removing, or change a preset only when the user asks to change DSH or its profile. For a question, design, or review, read-only lookups, including `list_plugins` and `list_bundles` within your tool permissions, remain available; report findings and leave files and the profile unchanged. A request for an image, widget, or decoration that does not target DSH, such as its Web UI or profile, is not a request for a DSH plugin; deliver the ordinary artifact the task asks for.\n\n## Find facts in this order\n\n1. Runtime inspection, when `cordis_inspect_list` and `cordis_inspect_query` are among your tools: exact Service methods and Event modes, a mounted plugin's Config schema and `packageDir`, the Tools this Agent can call, and live Client Slots and theme tokens.\n2. The installed documentation and package sources, located as `references/locate-docs.md` describes.\n3. When an answer depends on a live API that you can neither inspect nor read, state what remains unverified. Do not change a preset or the profile to gain tools.\n\n## Read next\n\nThe files below live in this skill's base directory, which the `skill` tool reported, and the table is the complete list: do not enumerate that directory. Read them with the file-read tool, write copies into the workspace with the file-write tool, and verify a copy by reading it back. In Desktop the directory sits inside `app.asar`, which the file-read tool and the runtime that `references/locate-docs.md` describes can open; native utilities such as `ls`, `cat`, `cp`, and `cmp`, the glob and search tools, a `node` from `PATH`, and pnpm fail on it. Never install or syntax-check a template in place; copy its contents into the workspace first.\n\n| Task | File |\n|---|---|\n| Find the installed version's documentation and package sources | `references/locate-docs.md` |\n| Build, install, enable, or debug a plugin or bundle | `references/plugin-development.md` |\n| Bundle manifest, locale resources, detail document, icons, installation, Host exports and Config | `references/host-plugin.md` |\n| Save plugin configuration or credentials | `references/configuration.md` |\n| Web UI: Client manifest, module loader, slot registration | `references/ui-plugin.md` |\n| Connect an MCP server through a configuration-only bundle | `references/mcp-bundle.md` |\n| Choose extension points, contexts, and state mechanisms | `references/practices.md` |\n| Share application operations between UI actions and agent tools | `references/user-actions.md` |\n| Verify a page or panel, review its user experience, or work without browser control | `references/verification.md` |\n| Draw icons and feature images | `references/artwork.md` |\n| Create, change, or migrate an agent preset; choose Host or preset placement | `references/compositions.md` |\n| Upgrade a plugin or profile to a newer DSH release | `references/upgrading.md` |\n| Loader patch dialect | `references/composition-reference.md` |\n| Installable plugin packages, one table per package group | `references/packages.md` |\n| Write a DSH tool definition, skill, or multi-step workflow | `references/tool-design.md` |\n| UI plugin template | `templates/decoration/package.json`, `templates/decoration/cordis.patch.yml`, `templates/decoration/index.js`, `templates/decoration/client.js`, `templates/decoration/locale`, `templates/decoration/docs/DETAIL.md`, `templates/decoration/icon.svg` |\n| MCP bundle template | `templates/mcp/package.json`, `templates/mcp/cordis.patch.yml`, `templates/mcp/locale`, `templates/mcp/docs/DETAIL.md`, `templates/mcp/icon.svg` |\n</skill_instructions>\n</skill_content>"}],"isError":false,"id":"{{message:6}}"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"step/start","data":{"turn":1,"step":2}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_read_2","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/artwork.md\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"stream":[{"type":"chunk","time":1788699430711,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"chunk","time":1788699430711,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_read_2","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/artwork.md\"}"}}},{"type":"chunk","time":1788699430711,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_read_2","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/artwork.md\"}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_read_2"},"toolCallId":"call_read_2","content":[{"type":"text","text":"<path>{{cwd}}/.dsh/skills/dsh-doc/references/artwork.md</path>\n<type>file</type>\n<content>\n1: # Plugin artwork\n2: \n3: Draw an icon that is recognizable at row size and belongs beside the icons of installed DSH plugins, and, when it helps, a feature image for the detail document. The display checklist in `references/host-plugin.md` owns manifest exports, accepted formats, size limits, and installed-display checks.\n4: \n5: ## Establish the subject\n6: \n7: - Inspect the feature, its output, and its manifest before drawing. A badge-producing skill may need a tag, not a medal. Reuse assets the user supplies; do not invent a brand mark for a third-party product or copy one whose license does not permit redistribution.\n8: - Read the icons of two or three installed plugins with related purposes. `references/locate-docs.md` finds each package directory; for a package-root plugin, a top-level `package.json` `icon`, else its `./icon` export, names the file; a subpath plugin uses only `./<subpath>/icon`. Plugins that Plugin Manager draws itself have no icon file. Borrow one coherent treatment, not every reference's effects.\n9: - Plugin Manager resolves the icon and display metadata separately for the bundle package and for each plugin its patch inserts; a subpath plugin or another package does not inherit the bundle's icon. Update every one you intend to change, and only those.\n10: \n11: ## Draw and refine\n12: \n13: 1. **Start simple.** Use one dominant subject and only the detail needed to explain it. Related capabilities can share a subject; distinguish them through proportions, silhouette, or palette rather than extra panels, symbols, or badges.\n14: 2. **Judge optical size.** Use `width=\"36\" height=\"36\" viewBox=\"0 0 36 36\"`. Center the artwork with deliberate margins; 18–22 units is a useful starting extent, not a requirement for every silhouette or wide text tag. Plugin Manager chooses display sizes and draws the surrounding tile, so do not draw a tile or background in the SVG or enlarge a toolbar glyph to fill it.\n15: 3. **Keep geometry consistent.** Balance the main subject and secondary element. Align repeated marks and corners; keep tails and handles intentional. Refine one requested dimension at a time without changing approved parts.\n16: 4. **Use restrained color.** Match the saturation and brightness of neighboring installed icons. Reserve unusually vivid, bright, or neon colors for brand requirements, essential contrast, or explicit user direction. Tune saturation separately from hue and lightness; do not make artwork gray or muddy merely to reduce saturation. Keep flat fills or short gradients and limited layering; avoid glow, drop shadows, glossy highlights, and emoji.\n17: 5. **Align lettering by visible ink.** Use consistent letterforms, cap height, baseline, weight, and spacing. Compare rendered stroke edges, not just path coordinates: stroke caps and joins can make equal coordinates appear unequal. Draw lettering as paths and keep it readable at actual size.\n18: 6. **Make empty areas genuinely transparent.** A hollow lens must reveal the background, including where it overlaps another shape. Remove the underlying fill with a local mask or cutout; do not substitute a white or dark disk. Check both themes.\n19: \n20: ## Export\n21: \n22: - Plugin Manager loads icons as images; an image that cannot decode falls back to the panel's default artwork. Export self-contained SVG geometry with local, uniquely named gradient, mask, and clip references. For these icons, omit scripts, event handlers, `<style>`, animation, `<image>`, and `foreignObject` to keep the asset self-contained. Draw lettering as paths rather than `<text>` so browser font substitution cannot change it.\n23: - Do not change assets the feature itself produces merely to change its icon.\n24: \n25: ## Feature image\n26: \n27: A detail document may start with one feature image when a picture shows the result better than text. Draw it only when the user asks for one or the result cannot be shown in text, after the plugin works. Save one SVG per document language, such as `docs/preview.svg` and `docs/preview.zh.svg`, with `width=\"640\" height=\"300\" viewBox=\"0 0 640 300\"`, and reference it from the first line of that document as ``, and `preview.zh.svg` from `DETAIL.zh.md`. Images must fit `pluginManager.detailImageMaxBytes` (5 MiB by default). Show one main example of the real interface or result, optionally with one close-up, using the plugin's exact UI labels; keep important content about 32 units from the edges. The export rules above apply, so outline every word into paths. Check that it stays readable at its displayed width in light and dark themes.\n28: \n29: ## Review\n30: \n31: 1. Deliver the plugin Line truncated
|
||||
{"type":"step/end","data":{"turn":1,"step":2}}
|
||||
{"type":"step/start","data":{"turn":1,"step":3}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_read_3","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/host-plugin.md\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:9}}"},"stream":[{"type":"chunk","time":1788699430712,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"chunk","time":1788699430712,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_read_3","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/host-plugin.md\"}"}}},{"type":"chunk","time":1788699430712,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":3,"callId":"call_read_3","name":"read","arguments":"{\"file_path\":\".dsh/skills/dsh-doc/references/host-plugin.md\"}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":3,"message":{"role":"tool","source":{"kind":"tool","callId":"call_read_3"},"toolCallId":"call_read_3","content":[{"type":"text","text":"<path>{{cwd}}/.dsh/skills/dsh-doc/references/host-plugin.md</path>\n<type>file</type>\n<content>\n1: # Bundles and Host plugins\n2: \n3: A bundle is a package whose `package.json` declares `dsh.bundle.patch`; the YAML patch inserts plugin entries. Give the package and rows unique names; use the Loader's existing YAML syntax, including `!!js` where expressions are needed. Read an existing patch before editing it: a matching override replaces the complete `config`.\n4: \n5: ## Manifest\n6: \n7: A Host-only bundle needs no dependencies, install scripts, or build tool:\n8: \n9: ```json\n10: {\n11: \"name\": \"@local/my-plugin\",\n12: \"version\": \"1.0.0\",\n13: \"private\": true,\n14: \"type\": \"module\",\n15: \"exports\": { \".\": \"./index.js\" },\n16: \"dsh\": { \"bundle\": { \"patch\": \"./cordis.patch.yml\" } }\n17: }\n18: ```\n19: \n20: `cordis.patch.yml`:\n21: \n22: ```yaml\n23: - insert:\n24: - id: my-plugin\n25: name: '@local/my-plugin'\n26: config: {}\n27: ```\n28: \n29: ## Display metadata, detail document, and icon\n30: \n31: Plugin Manager and Settings read `meta.title` and `meta.description` from exported locale JSON and an icon from exported resources without activating plugins. The bundle's page in Plugin Manager shows the detail document that `meta.detail` names, otherwise the package README. Complete this checklist before installation:\n32: \n33: - Write a recognizable title and a description of the capability in `locale/en.json` under `meta.title` and `meta.description`. Add the same fields for the user's language and other supported locales, such as `locale/zh.json`; do not leave template copy unrelated to the delivered plugin. Write English titles and other UI labels in sentence case: capitalize only the first word and proper nouns, as in `Git worktrees`.\n34: - Write a detail document for users in each locale's language, and name it with `meta.detail` in that locale file: a `/`-separated path relative to the package root, inside a subdirectory so images beside it are published, that ends in `.md`, such as `docs/DETAIL.md` for `en` and `docs/DETAIL.zh.md` for `zh`. For bundles delivered with this skill, start with one paragraph on what the user gets, then `## How to use` (where to find or trigger the feature, with its exact UI labels) and `## Good to know` (added tokens or model requests, data read or sent elsewhere, risks, and what changes when the plugin is turned off); Chinese documents use `## 使用方法` and `## 注意事项`. This is the delivery structure, not a Markdown format enforced by the renderer. State only behavior you implemented and verified. The page omits raw HTML and renders relative links as plain text; reference images relative to the document. An optional feature image goes on the first line; see `references/artwork.md`. A malformed `meta.detail`, a missing named file, or a document exceeding `pluginManager.detailMaxBytes` (1 MiB by default) makes the detail section show the failure with **Retry** instead of falling back to the README.\n35: - Create an original icon or use artwork whose license permits redistribution, retaining any required attribution. Read `references/artwork.md` before drawing or revising an icon.\n36: - Export `./locale/*.json` and `./icon`; retain existing runtime exports. Keep the patch, locales, the detail document's directory, icon, and every runtime file in `files`, updating it whenever you add modules or assets. For a packed or published bundle, verify the actual packed file list. Local directory installation links the checkout instead, so check the files directly; `files` does not filter a linked directory.\n37: - Check that the icon is a valid image of the declared format and satisfies the path and size limits below. An accepted filename alone does not establish that its bytes render.\n38: \n39: For example, the locale file contains:\n40: \n41: ```json\n42: { \"meta\": { \"title\": \"My decoration\", \"description\": \"Draws a badge under the composer.\", \"detail\": \"docs/DETAIL.md\" } }\n43: ```\n44: \n45: ```json\n46: {\n47: \"exports\": { \"./locale/*.json\": \"./locale/*.json\", \"./icon\": \"./icon.svg\" },\n48: \"files\": [\"index.js\", \"cordis.patch.yml\", \"locale/*.json\", \"docs\", \"icon.svg\"]\n49: }\n50: ```\n51: \n52: A package-root plugin may instead declare a top-level `icon` in `package.json`; it takes priority over `./icon` and is a path relative to the manifest directory. A subpath plugin such as `my-plugins/search` is not a package and never reads a `package.json`; it exports `./search/locale/*.json` and `./search/icon` instead. Icons may be SVG, PNG, JPEG, or WebP up to 256 KiB and must stay inside the package; absolute paths, URLs, and symlinks leaving it are rejected. Missing fields of a package-rooLine truncated
|
||||
{"type":"step/end","data":{"turn":1,"step":3}}
|
||||
{"type":"step/start","data":{"turn":1,"step":4}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The skill is loaded."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:11}}"},"usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4},"stream":[{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430709,"index":0,"dt":[],"texts":["The skill is loaded."]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699430709,"index":1,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The skill is loaded."}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"usage","usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":4}}
|
||||
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
|
||||
Loaded 100 of 106 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user