From 03e70034e6e388ebcac482c2c805afe7bae3f0d3 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 5 Nov 2026 17:53:22 +0800 Subject: [PATCH] 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 --- ...ence-first-documentation-quality.i18n.yaml | 12 +- ...20-audience-first-documentation-quality.md | 10 +- ...audience-first-documentation-quality.zh.md | 10 +- .agents/skills/agent-experience/SKILL.md | 7 +- .../skills/dsh-create-upgrade-guide/SKILL.md | 2 +- .../{dsh-doc => dsh-doc-writing}/SKILL.md | 2 +- .../references/metadata-links-i18n.md | 0 .../references/review.md | 0 .../references/structure-hierarchy.md | 0 .../references/style.md | 0 .../references/website-sync.md | 0 .../templates/package-bundle.md | 0 .../templates/package-group.md | 0 .../templates/package-library.md | 0 .../templates/package-reference.md | 0 .../templates/persistence-change.md | 0 .../templates/persistence-format.md | 0 .../templates/persistence-release.md | 0 .../templates/upgrade-guide.md | 0 .../dsh-official-plugin-artwork/SKILL.md | 39 ++-- .agents/skills/dsh-prose-standard/SKILL.md | 2 +- .agents/skills/dsh-trim-cot-leakage/SKILL.md | 2 +- apps/cli/tests/web-agent-presets.e2e.ts | 50 +++- docs/AGENTS.md | 4 +- docs/cookbook/adding-a-package.i18n.yaml | 4 +- docs/cookbook/adding-a-package.md | 2 +- docs/cookbook/adding-a-package.zh.md | 2 +- docs/persistence-changes/README.i18n.yaml | 4 +- docs/persistence-changes/README.md | 2 +- docs/persistence-changes/README.zh.md | 2 +- .../historical-formats/README.i18n.yaml | 8 +- .../historical-formats/README.md | 4 +- .../historical-formats/README.zh.md | 4 +- .../releases/README.i18n.yaml | 4 +- docs/persistence-changes/releases/README.md | 2 +- .../persistence-changes/releases/README.zh.md | 2 +- .../v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml | 16 ++ .../v0.2.2-rc.1/dsh-doc-skill/guide.md | 35 +++ .../v0.2.2-rc.1/dsh-doc-skill/guide.zh.md | 35 +++ .../bundle/web-app/presets/cordis.patch.yml | 2 +- .../extensions/tool-cordis/README.i18n.yaml | 4 +- packages/extensions/tool-cordis/README.md | 2 +- packages/extensions/tool-cordis/README.zh.md | 2 +- packages/preset/agent-preset/README.i18n.yaml | 8 +- packages/preset/agent-preset/README.md | 5 +- packages/preset/agent-preset/README.zh.md | 5 +- packages/preset/agent-preset/package.json | 1 + .../skills/cordis-plugin-development/SKILL.md | 50 ---- .../references/mcp-bundle.md | 5 - .../references/verification.md | 7 - .../templates/decoration/icon.svg | 3 - .../templates/mcp/icon.svg | 5 - .../agent-preset/skills/dsh-doc/SKILL.md | 40 ++++ .../skills/dsh-doc/references/artwork.md | 33 +++ .../references/composition-reference.md} | 11 +- .../skills/dsh-doc/references/compositions.md | 79 +++++++ .../dsh-doc/references/configuration.md | 12 + .../references/host-plugin.md | 28 +-- .../skills/dsh-doc/references/locate-docs.md | 56 +++++ .../skills/dsh-doc/references/mcp-bundle.md | 5 + .../references/packages.md | 2 +- .../dsh-doc/references/plugin-development.md | 26 +++ .../references/practices.md | 8 +- .../references/tool-design.md} | 5 - .../references/ui-plugin.md | 2 +- .../skills/dsh-doc/references/upgrading.md | 25 ++ .../references/user-actions.md | 2 +- .../skills/dsh-doc/references/verification.md | 11 + .../templates/decoration/client.js | 0 .../templates/decoration/cordis.patch.yml | 0 .../templates/decoration/docs/DETAIL.md | 10 + .../dsh-doc/templates/decoration/icon.svg | 3 + .../templates/decoration/index.js | 0 .../templates/decoration/locale/de.json | 3 +- .../templates/decoration/locale/en.json | 3 +- .../templates/decoration/locale/es.json | 3 +- .../templates/decoration/locale/fr.json | 3 +- .../templates/decoration/locale/ja.json | 3 +- .../templates/decoration/locale/pt.json | 3 +- .../templates/decoration/locale/ru.json | 3 +- .../templates/decoration/package.json | 2 +- .../templates/mcp/cordis.patch.yml | 0 .../dsh-doc/templates/mcp/docs/DETAIL.md | 11 + .../skills/dsh-doc/templates/mcp/icon.svg | 5 + .../templates/mcp/locale/de.json | 3 +- .../templates/mcp/locale/en.json | 3 +- .../templates/mcp/locale/es.json | 3 +- .../templates/mcp/locale/fr.json | 3 +- .../templates/mcp/locale/ja.json | 3 +- .../templates/mcp/locale/pt.json | 3 +- .../templates/mcp/locale/ru.json | 3 +- .../templates/mcp/package.json | 2 +- .../preset/agent-preset/tests/skills.spec.ts | 219 ++++++++++++------ pnpm-lock.yaml | 3 + scripts/doc-standard.spec.ts | 42 ++-- scripts/gen-plugin-packages.ts | 6 +- .../verify-package-readme-summaries.spec.ts | 2 +- scripts/verify-package-readme-summaries.ts | 6 +- .../session/dsh-doc-load/session.v4.jsonl | 33 +++ snapshots/session/dsh-doc-load/snapshot.yml | 9 + snapshots/session/headless.snapshot.ts | 14 +- snapshots/session/skill-load/snapshot.yml | 2 - .../editing-cordis-compositions/SKILL.md | 0 .../terminal-panel-tools/session.v4.jsonl | 2 +- tsconfig.host.json | 1 + website/AGENTS.md | 2 +- 106 files changed, 802 insertions(+), 324 deletions(-) mode change 120000 => 100644 .agents/skills/agent-experience/SKILL.md rename .agents/skills/{dsh-doc => dsh-doc-writing}/SKILL.md (99%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/references/metadata-links-i18n.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/references/review.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/references/structure-hierarchy.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/references/style.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/references/website-sync.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/package-bundle.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/package-group.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/package-library.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/package-reference.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/persistence-change.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/persistence-format.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/persistence-release.md (100%) rename .agents/skills/{dsh-doc => dsh-doc-writing}/templates/upgrade-guide.md (100%) create mode 100644 docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml create mode 100644 docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md create mode 100644 docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.zh.md delete mode 100644 packages/preset/agent-preset/skills/cordis-plugin-development/SKILL.md delete mode 100644 packages/preset/agent-preset/skills/cordis-plugin-development/references/mcp-bundle.md delete mode 100644 packages/preset/agent-preset/skills/cordis-plugin-development/references/verification.md delete mode 100644 packages/preset/agent-preset/skills/cordis-plugin-development/templates/decoration/icon.svg delete mode 100644 packages/preset/agent-preset/skills/cordis-plugin-development/templates/mcp/icon.svg create mode 100644 packages/preset/agent-preset/skills/dsh-doc/SKILL.md create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/artwork.md rename packages/preset/agent-preset/skills/{cordis-composition-reference/SKILL.md => dsh-doc/references/composition-reference.md} (71%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/compositions.md create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/configuration.md rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/references/host-plugin.md (58%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/locate-docs.md create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/mcp-bundle.md rename packages/preset/agent-preset/skills/{cordis-composition-reference => dsh-doc}/references/packages.md (99%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/plugin-development.md rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/references/practices.md (81%) rename packages/preset/agent-preset/skills/{agent-experience/SKILL.md => dsh-doc/references/tool-design.md} (85%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/references/ui-plugin.md (92%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/upgrading.md rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/references/user-actions.md (89%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/references/verification.md rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/client.js (100%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/cordis.patch.yml (100%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/templates/decoration/docs/DETAIL.md create mode 100644 packages/preset/agent-preset/skills/dsh-doc/templates/decoration/icon.svg rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/index.js (100%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/de.json (71%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/en.json (75%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/es.json (72%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/fr.json (74%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/ja.json (69%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/pt.json (73%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/locale/ru.json (63%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/decoration/package.json (94%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/cordis.patch.yml (100%) create mode 100644 packages/preset/agent-preset/skills/dsh-doc/templates/mcp/docs/DETAIL.md create mode 100644 packages/preset/agent-preset/skills/dsh-doc/templates/mcp/icon.svg rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/de.json (60%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/en.json (66%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/es.json (61%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/fr.json (62%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/ja.json (80%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/pt.json (65%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/locale/ru.json (70%) rename packages/preset/agent-preset/skills/{cordis-plugin-development => dsh-doc}/templates/mcp/package.json (76%) create mode 100644 snapshots/session/dsh-doc-load/session.v4.jsonl create mode 100644 snapshots/session/dsh-doc-load/snapshot.yml rename {packages/preset/agent-preset => snapshots/session/skill-load/workspace/.dsh}/skills/editing-cordis-compositions/SKILL.md (100%) diff --git a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.i18n.yaml b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.i18n.yaml index e1371258e1..ecef7bbe6b 100644 --- a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.i18n.yaml +++ b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.i18n.yaml @@ -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 diff --git a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.md b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.md index 9e0c4a6140..7a5d3bcaaf 100644 --- a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.md +++ b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.md @@ -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. diff --git a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.zh.md b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.zh.md index 0b6f1da543..87d71b9883 100644 --- a/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.zh.md +++ b/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.zh.md @@ -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 同时记录目标与临时上限,其检查会报告或拒绝违反余量或棘轮规则的状态。 diff --git a/.agents/skills/agent-experience/SKILL.md b/.agents/skills/agent-experience/SKILL.md deleted file mode 120000 index fb40f7ffce..0000000000 --- a/.agents/skills/agent-experience/SKILL.md +++ /dev/null @@ -1 +0,0 @@ -../../../packages/preset/agent-preset/skills/agent-experience/SKILL.md \ No newline at end of file diff --git a/.agents/skills/agent-experience/SKILL.md b/.agents/skills/agent-experience/SKILL.md new file mode 100644 index 0000000000..4b77eff240 --- /dev/null +++ b/.agents/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. diff --git a/.agents/skills/dsh-create-upgrade-guide/SKILL.md b/.agents/skills/dsh-create-upgrade-guide/SKILL.md index c3442ab971..2a4142433f 100644 --- a/.agents/skills/dsh-create-upgrade-guide/SKILL.md +++ b/.agents/skills/dsh-create-upgrade-guide/SKILL.md @@ -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; diff --git a/.agents/skills/dsh-doc/SKILL.md b/.agents/skills/dsh-doc-writing/SKILL.md similarity index 99% rename from .agents/skills/dsh-doc/SKILL.md rename to .agents/skills/dsh-doc-writing/SKILL.md index 5e32d4c07e..77964d7859 100644 --- a/.agents/skills/dsh-doc/SKILL.md +++ b/.agents/skills/dsh-doc-writing/SKILL.md @@ -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. --- diff --git a/.agents/skills/dsh-doc/references/metadata-links-i18n.md b/.agents/skills/dsh-doc-writing/references/metadata-links-i18n.md similarity index 100% rename from .agents/skills/dsh-doc/references/metadata-links-i18n.md rename to .agents/skills/dsh-doc-writing/references/metadata-links-i18n.md diff --git a/.agents/skills/dsh-doc/references/review.md b/.agents/skills/dsh-doc-writing/references/review.md similarity index 100% rename from .agents/skills/dsh-doc/references/review.md rename to .agents/skills/dsh-doc-writing/references/review.md diff --git a/.agents/skills/dsh-doc/references/structure-hierarchy.md b/.agents/skills/dsh-doc-writing/references/structure-hierarchy.md similarity index 100% rename from .agents/skills/dsh-doc/references/structure-hierarchy.md rename to .agents/skills/dsh-doc-writing/references/structure-hierarchy.md diff --git a/.agents/skills/dsh-doc/references/style.md b/.agents/skills/dsh-doc-writing/references/style.md similarity index 100% rename from .agents/skills/dsh-doc/references/style.md rename to .agents/skills/dsh-doc-writing/references/style.md diff --git a/.agents/skills/dsh-doc/references/website-sync.md b/.agents/skills/dsh-doc-writing/references/website-sync.md similarity index 100% rename from .agents/skills/dsh-doc/references/website-sync.md rename to .agents/skills/dsh-doc-writing/references/website-sync.md diff --git a/.agents/skills/dsh-doc/templates/package-bundle.md b/.agents/skills/dsh-doc-writing/templates/package-bundle.md similarity index 100% rename from .agents/skills/dsh-doc/templates/package-bundle.md rename to .agents/skills/dsh-doc-writing/templates/package-bundle.md diff --git a/.agents/skills/dsh-doc/templates/package-group.md b/.agents/skills/dsh-doc-writing/templates/package-group.md similarity index 100% rename from .agents/skills/dsh-doc/templates/package-group.md rename to .agents/skills/dsh-doc-writing/templates/package-group.md diff --git a/.agents/skills/dsh-doc/templates/package-library.md b/.agents/skills/dsh-doc-writing/templates/package-library.md similarity index 100% rename from .agents/skills/dsh-doc/templates/package-library.md rename to .agents/skills/dsh-doc-writing/templates/package-library.md diff --git a/.agents/skills/dsh-doc/templates/package-reference.md b/.agents/skills/dsh-doc-writing/templates/package-reference.md similarity index 100% rename from .agents/skills/dsh-doc/templates/package-reference.md rename to .agents/skills/dsh-doc-writing/templates/package-reference.md diff --git a/.agents/skills/dsh-doc/templates/persistence-change.md b/.agents/skills/dsh-doc-writing/templates/persistence-change.md similarity index 100% rename from .agents/skills/dsh-doc/templates/persistence-change.md rename to .agents/skills/dsh-doc-writing/templates/persistence-change.md diff --git a/.agents/skills/dsh-doc/templates/persistence-format.md b/.agents/skills/dsh-doc-writing/templates/persistence-format.md similarity index 100% rename from .agents/skills/dsh-doc/templates/persistence-format.md rename to .agents/skills/dsh-doc-writing/templates/persistence-format.md diff --git a/.agents/skills/dsh-doc/templates/persistence-release.md b/.agents/skills/dsh-doc-writing/templates/persistence-release.md similarity index 100% rename from .agents/skills/dsh-doc/templates/persistence-release.md rename to .agents/skills/dsh-doc-writing/templates/persistence-release.md diff --git a/.agents/skills/dsh-doc/templates/upgrade-guide.md b/.agents/skills/dsh-doc-writing/templates/upgrade-guide.md similarity index 100% rename from .agents/skills/dsh-doc/templates/upgrade-guide.md rename to .agents/skills/dsh-doc-writing/templates/upgrade-guide.md diff --git a/.agents/skills/dsh-official-plugin-artwork/SKILL.md b/.agents/skills/dsh-official-plugin-artwork/SKILL.md index fce1964d39..314dd4b588 100644 --- a/.agents/skills/dsh-official-plugin-artwork/SKILL.md +++ b/.agents/skills/dsh-official-plugin-artwork/SKILL.md @@ -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 ``: 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. diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md index 338ff29a21..df4a4d854a 100644 --- a/.agents/skills/dsh-prose-standard/SKILL.md +++ b/.agents/skills/dsh-prose-standard/SKILL.md @@ -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. diff --git a/.agents/skills/dsh-trim-cot-leakage/SKILL.md b/.agents/skills/dsh-trim-cot-leakage/SKILL.md index f8a852bd66..bdab794297 100644 --- a/.agents/skills/dsh-trim-cot-leakage/SKILL.md +++ b/.agents/skills/dsh-trim-cot-leakage/SKILL.md @@ -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`). diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts index e3915c4ad6..a3e4b09a4d 100644 --- a/apps/cli/tests/web-agent-presets.e2e.ts +++ b/apps/cli/tests/web-agent-presets.e2e.ts @@ -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('') + 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 () => { diff --git a/docs/AGENTS.md b/docs/AGENTS.md index d1766b9e80..818f40b452 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -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. diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml index 5f9ee81f66..859380de12 100644 --- a/docs/cookbook/adding-a-package.i18n.yaml +++ b/docs/cookbook/adding-a-package.i18n.yaml @@ -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 diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md index 7c8b051817..d68ba0a01c 100644 --- a/docs/cookbook/adding-a-package.md +++ b/docs/cookbook/adding-a-package.md @@ -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 diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md index 68cde8056a..8cd0daac4d 100644 --- a/docs/cookbook/adding-a-package.zh.md +++ b/docs/cookbook/adding-a-package.zh.md @@ -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 diff --git a/docs/persistence-changes/README.i18n.yaml b/docs/persistence-changes/README.i18n.yaml index 90a4bd0676..50275b6ba6 100644 --- a/docs/persistence-changes/README.i18n.yaml +++ b/docs/persistence-changes/README.i18n.yaml @@ -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 diff --git a/docs/persistence-changes/README.md b/docs/persistence-changes/README.md index cb6e92658d..75466810c1 100644 --- a/docs/persistence-changes/README.md +++ b/docs/persistence-changes/README.md @@ -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. ## Compatibility rules diff --git a/docs/persistence-changes/README.zh.md b/docs/persistence-changes/README.zh.md index 21e7e2e84c..3718d97f76 100644 --- a/docs/persistence-changes/README.zh.md +++ b/docs/persistence-changes/README.zh.md @@ -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,并保留显式删除标记。 ## 兼容性规则 diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml index 81275db31b..41851acbc9 100644 --- a/docs/persistence-changes/historical-formats/README.i18n.yaml +++ b/docs/persistence-changes/historical-formats/README.i18n.yaml @@ -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 diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md index ad213e0c18..6a044c2a88 100644 --- a/docs/persistence-changes/historical-formats/README.md +++ b/docs/persistence-changes/historical-formats/README.md @@ -39,7 +39,7 @@ The index is generated from validated snapshots and the current writer constant. ## 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: diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md index e3ca2d1bd3..5e13e1d2e8 100644 --- a/docs/persistence-changes/historical-formats/README.zh.md +++ b/docs/persistence-changes/historical-formats/README.zh.md @@ -39,7 +39,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式 ## 范围与证据 -每组 `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 定义与索引由工具生成。推进写入器并完成机器数据与人工证据后,刷新其表格和配对记录,再执行验证: diff --git a/docs/persistence-changes/releases/README.i18n.yaml b/docs/persistence-changes/releases/README.i18n.yaml index 7428bab53e..ef389786a2 100644 --- a/docs/persistence-changes/releases/README.i18n.yaml +++ b/docs/persistence-changes/releases/README.i18n.yaml @@ -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 diff --git a/docs/persistence-changes/releases/README.md b/docs/persistence-changes/releases/README.md index c818f28d36..40fbd0fe1b 100644 --- a/docs/persistence-changes/releases/README.md +++ b/docs/persistence-changes/releases/README.md @@ -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. ## Dev Note diff --git a/docs/persistence-changes/releases/README.zh.md b/docs/persistence-changes/releases/README.zh.md index 92d4170717..5665eb8ed9 100644 --- a/docs/persistence-changes/releases/README.zh.md +++ b/docs/persistence-changes/releases/README.zh.md @@ -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)规定单条记录的字段。 ## 开发备注 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml new file mode 100644 index 0000000000..fe6a408bf0 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml @@ -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 diff --git a/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md new file mode 100644 index 0000000000..6a9cacba4e --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md @@ -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/` | `dsh-doc/references/` | + | `cordis-plugin-development/templates//` | `dsh-doc/templates//` | + | `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. diff --git a/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.zh.md b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.zh.md new file mode 100644 index 0000000000..287e67a136 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.zh.md @@ -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/` | `dsh-doc/references/` | + | `cordis-plugin-development/templates//` | `dsh-doc/templates//` | + | `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 中的任何一个。 diff --git a/packages/bundle/web-app/presets/cordis.patch.yml b/packages/bundle/web-app/presets/cordis.patch.yml index 4494bb1530..0fc32e6248 100644 --- a/packages/bundle/web-app/presets/cordis.patch.yml +++ b/packages/bundle/web-app/presets/cordis.patch.yml @@ -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: diff --git a/packages/extensions/tool-cordis/README.i18n.yaml b/packages/extensions/tool-cordis/README.i18n.yaml index b751e7b216..b6752dae5c 100644 --- a/packages/extensions/tool-cordis/README.i18n.yaml +++ b/packages/extensions/tool-cordis/README.i18n.yaml @@ -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 diff --git a/packages/extensions/tool-cordis/README.md b/packages/extensions/tool-cordis/README.md index acf575c6cf..7834afc32a 100644 --- a/packages/extensions/tool-cordis/README.md +++ b/packages/extensions/tool-cordis/README.md @@ -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 diff --git a/packages/extensions/tool-cordis/README.zh.md b/packages/extensions/tool-cordis/README.zh.md index 06b50786d9..4139cf398a 100644 --- a/packages/extensions/tool-cordis/README.zh.md +++ b/packages/extensions/tool-cordis/README.zh.md @@ -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 影响 diff --git a/packages/preset/agent-preset/README.i18n.yaml b/packages/preset/agent-preset/README.i18n.yaml index a2b45603c1..22945f30a9 100644 --- a/packages/preset/agent-preset/README.i18n.yaml +++ b/packages/preset/agent-preset/README.i18n.yaml @@ -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 diff --git a/packages/preset/agent-preset/README.md b/packages/preset/agent-preset/README.md index 243d771ec7..5dcdba79f3 100644 --- a/packages/preset/agent-preset/README.md +++ b/packages/preset/agent-preset/README.md @@ -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. ## Understand the implementation @@ -82,7 +82,6 @@ A live Agent’s composition stays stable; new Agents can use an updated definit - 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. ### Dev Note diff --git a/packages/preset/agent-preset/README.zh.md b/packages/preset/agent-preset/README.zh.md index c7bde250e4..99f4e2a261 100644 --- a/packages/preset/agent-preset/README.zh.md +++ b/packages/preset/agent-preset/README.zh.md @@ -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` 只包含指向该文件的链接。 ## 理解实现 @@ -82,7 +82,6 @@ kind: "package-reference" - 需要 `agentPresets` 服务。重复的 preset ID 会导致声明加载失败。声明不提供目录、文件复制或文件删除操作。 -- 从仓库发现 `agent-experience` 要求 checkout 启用符号链接。设置 `core.symlinks=false` 时,Git 会将链接目标写成纯文本,而不是 skill。创造模式使用包内的普通文件,不依赖该别名。 ### 开发备注 diff --git a/packages/preset/agent-preset/package.json b/packages/preset/agent-preset/package.json index 874f30bd76..dac683e08c 100644 --- a/packages/preset/agent-preset/package.json +++ b/packages/preset/agent-preset/package.json @@ -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:~", diff --git a/packages/preset/agent-preset/skills/cordis-plugin-development/SKILL.md b/packages/preset/agent-preset/skills/cordis-plugin-development/SKILL.md deleted file mode 100644 index 90a9f98e7d..0000000000 --- a/packages/preset/agent-preset/skills/cordis-plugin-development/SKILL.md +++ /dev/null @@ -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//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 `/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///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` | diff --git a/packages/preset/agent-preset/skills/cordis-plugin-development/references/mcp-bundle.md b/packages/preset/agent-preset/skills/cordis-plugin-development/references/mcp-bundle.md deleted file mode 100644 index f1159538ec..0000000000 --- a/packages/preset/agent-preset/skills/cordis-plugin-development/references/mcp-bundle.md +++ /dev/null @@ -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____` 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. diff --git a/packages/preset/agent-preset/skills/cordis-plugin-development/references/verification.md b/packages/preset/agent-preset/skills/cordis-plugin-development/references/verification.md deleted file mode 100644 index 350f6a3d84..0000000000 --- a/packages/preset/agent-preset/skills/cordis-plugin-development/references/verification.md +++ /dev/null @@ -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. diff --git a/packages/preset/agent-preset/skills/cordis-plugin-development/templates/decoration/icon.svg b/packages/preset/agent-preset/skills/cordis-plugin-development/templates/decoration/icon.svg deleted file mode 100644 index 5c7caf5c24..0000000000 --- a/packages/preset/agent-preset/skills/cordis-plugin-development/templates/decoration/icon.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/packages/preset/agent-preset/skills/cordis-plugin-development/templates/mcp/icon.svg b/packages/preset/agent-preset/skills/cordis-plugin-development/templates/mcp/icon.svg deleted file mode 100644 index 4a2710adeb..0000000000 --- a/packages/preset/agent-preset/skills/cordis-plugin-development/templates/mcp/icon.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/packages/preset/agent-preset/skills/dsh-doc/SKILL.md b/packages/preset/agent-preset/skills/dsh-doc/SKILL.md new file mode 100644 index 0000000000..2c19da5355 --- /dev/null +++ b/packages/preset/agent-preset/skills/dsh-doc/SKILL.md @@ -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` | diff --git a/packages/preset/agent-preset/skills/dsh-doc/references/artwork.md b/packages/preset/agent-preset/skills/dsh-doc/references/artwork.md new file mode 100644 index 0000000000..49595a95fa --- /dev/null +++ b/packages/preset/agent-preset/skills/dsh-doc/references/artwork.md @@ -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 `.//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, `