@lmzhen/dsh-tool-skill-manage 0.32.3 → 0.32.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +11 -114
  2. package/lib/index.js +9 -4
  3. package/package.json +8 -8
package/README.md CHANGED
@@ -1,126 +1,23 @@
1
1
  # @lmzhen/dsh-tool-skill-manage
2
2
 
3
- Model-facing `skill_manage` tool: it exposes skill-library mutations to the model and
4
- routes them through the evolution approval seam when one is mounted; it owns neither the
5
- library nor its lifecycle rules.
3
+ > Agent 写技能的工具(创建/修补/归档/合并入口)。
6
4
 
7
- ## Model surface
5
+ ## 你会看到
8
6
 
9
- - **Model-visible:** the `skill_manage` tool schema and its success/validation messages; result tokens scale with what is returned. The skills-guidance section (`evolution-skills-guidance`) ends with the policy's protected-skill list, carried by the prompt variable `evolution_skill_guard`: the provider runs at EVERY assembly (a policy change needs no reload), and an empty list leaves the section byte-identical to the guidance alone, so the guidance's prefix-cache behaviour is unchanged.
10
- - **Prompt prefix / KV cache:** the tool schema is prefix-stable, and skill writes do not alter the current request prompt; catalog invalidation affects the next request; family rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
11
- - **Mount it?** yes — the `tool-skill-manage` row, carried by the `evolution-all` and one-click `evolution-preset` bundles and the Evolution agent preset delta.
7
+ 用户看到的是 Agent 创建/修改技能;改错可看历史/撤销。
12
8
 
13
- ## Safety model
9
+ ## 什么时候会用到
14
10
 
15
- ### Write gates
11
+ 你让 Agent 把做法写成技能,或它自己改进时。
16
12
 
17
- Every mutation THROUGH THIS TOOL passes ONE ordered admission sequence (`src/write-gates.ts`): the
18
- scalar argument shape, the required arguments per action, the policy's protected list,
19
- read-before-write, and the operator confirmation. The
20
- ADMISSION point runs the sequence before the approval seam, so a write that is refused is never
21
- staged for approval and never spends the operator's attention; the EXECUTION point (`executeCore`)
22
- re-runs the gates a replay or a direct write can still fail, because a replay's stored arguments
23
- passed no schema and the protected list can change while a record sits pending. Both points read the
24
- same table, so they cannot diverge.
13
+ ## 默认 / 前提
25
14
 
26
- The sequence covers the MODEL tool path. The family's other writers reach their own library
27
- handles: the `/evolution` and `/graph` command face writes what the operator typed (the operator is
28
- the authority there), the review's plan executor writes a plan its own filter already screened
29
- (`filterUnreadSkillOps`), and a record staged outside this tool replays into the execution point
30
- without re-deciding the admission-only gates — there is no writing session to read.
15
+ all/分层预设才有;host 没有。
31
16
 
32
- Read-before-write is admission-only (the replayed record has no writing session): a non-foreground
33
- write whose target the session never read is refused with `E-318`, and only a read that did not fail
34
- counts. A session log the tool cannot read proceeds with one warning rather than blocking every
35
- autonomous write.
17
+ ## 边界
36
18
 
37
- A foreground `create`, or a bare foreground `delete`, is the ONE write this tool puts to a human
38
- before writing; a `delete` carrying `absorbed_into` is the merge protocol and does not ask. WHAT
39
- that confirmation does is the `skillWriteConfirm` parameter (`/evolution params`, and the
40
- 技能写入规则 card):
19
+ 写入有保护;删除是归档。
41
20
 
42
- | Mode | What happens |
43
- |---|---|
44
- | `auto` (**the default**) | the write proceeds with no prompt — an unattended run (a background pass, a scheduled review, a headless session) must not park a tool call on a question nobody will answer |
45
- | `ask` | the question waits for as long as it takes; the answer is `Create`/`Delete` to proceed, `Cancel` (or a dismissed card) to refuse with `E-317` |
46
- | `timeout` | the question is asked with a deadline of `skillWriteConfirmTimeoutSeconds` (default 120 s); an unanswered prompt cancels the write with `E-319`, which names the three knobs |
21
+ ## 维护者参考:参数别名(G0/S0.3)
47
22
 
48
- **One human gate per write (T2-10/A25).** When the approval seam is mounted, enabled and will stage
49
- this write (a background-origin write, or a deployment with `stageForeground`), the confirmation is
50
- SKIPPED — the approval window is the stronger gate (it holds the bytes until someone decides and replays
51
- them), and asking first as well asked the same question twice for one foreground write. The confirmation
52
- still fires exactly once when there is no such seam. A session whose approval policy is `never` has
53
- opted out of interrupts altogether; the seam allows the write outright there, which is that instruction
54
- rather than two gates collapsing into none.
55
-
56
- The deadline is enforced by the gate itself, not only by the abort signal it hands the question
57
- service: a prompt that outlives it returns anyway, and the timer is unref'd and cleared, so an
58
- answered prompt leaves neither a parked call nor a live timer behind. This gate is UX, not a
59
- security door: it is admission-only (a replayed record already carries the human release that staged
60
- it), and — in the two modes that ask at all — an unmounted question service, a caller that is not
61
- the registry's exact live root agent, or a failing ask all PROCEED with one warning. The shipped
62
- `auto` mode asks nothing, so it never reaches those fallbacks; the operator's own session stays the
63
- authority that asked for the write.
64
-
65
- ### Approval seam
66
-
67
- Mutations (create/edit/update/patch/delete/write_file/remove_file/restructure) pass through the evolution approval seam when `evolution-approval` is mounted; approved/staged writes are replayed by the registered runner with the library origin preserved. The admission gates run BEFORE that boundary, so a write that cannot execute is refused, never staged for approval.
68
-
69
- ### pin/unpin: explicit exception
70
-
71
- `pin` and `unpin` are deliberately **outside** the approval seam. Pinning only lifts/restores the curator-lifecycle freeze (a lifecycle flag, never content) and is fully reversible by the same tool. Routing it through `policy:'ask'` would let a staged-but-never-approved request hold the library in a pinned state invisibly. Tradeoff accepted: no approval on a lifecycle-flag flip; if product policy changes, pin/unpin should be wired into the same staging path as `patch`.
72
-
73
- ## Configuration
74
-
75
- - `maxSkillContentChars` / `maxSkillFileBytes` bound SKILL.md reads and support-file writes on this row.
76
- - Deprecated name (G0/S0.3): `maxSkillContentChars` is the legacy spelling of the
77
- policy row's `skillContentChars` (canonical id). The two are not auto-synchronised with it: this row's value is what
78
- the write paths use, and since 0.6.0 the user settings layer can override it
79
- per user. Reading the legacy name still works; writing it is refused. Removal was planned for 0.7.0 and is deferred:
80
- the alias still ships, so no later version is claimed here.
81
-
82
- ### Description length: the three numbers
83
-
84
- A skill description is measured against three different bounds. They are not interchangeable, and
85
- only the second one refuses a write:
86
-
87
- | Bound | Value | Source | What it does |
88
- |---|---|---|---|
89
- | Authoring bar | 60 chars | `AUTHORING_DESCRIPTION_BAR` (the upstream 60-char rule) | advisory feedback on every create/edit/update; `descriptionStrict: true` turns it into a refusal |
90
- | Family storage ceiling | 1024 chars | `MAX_DESCRIPTION_LENGTH`, lowered per deployment by this row's `maxDescriptionLength` | the hard validation limit — the ONLY refusal threshold of the three |
91
- | Platform catalog view | 500 chars by default | `catalogDescriptionMaxLength` on the platform's `tool-skill` row (`PLATFORM_CATALOG_DESCRIPTION_DEFAULT`) | truncates the description in the skill catalog the model reads; the family's own rows set that field to 60 (`evolution-host`, `evolution-all` and `evolution-preset` each carry it, and the composer injects it onto a generated preset row too), so 500 governs only a composition that overrides none of them; `packages/README.md` states which of those rows takes effect per install form |
92
-
93
- The third row is a view, not a rule: a description the family accepts can still be cut in a catalog
94
- viewer, which is why the authoring feedback names the bar rather than treating the cut as a limit.
95
-
96
- ### The create-time duplicate hint
97
-
98
- A `create` compares its candidate against the library listing before it writes, over the name +
99
- description projection (core `nearDuplicateSummaries`, at `SUMMARY_DUPLICATE_HINT_THRESHOLD`), and
100
- names the closest existing skills in the same "Authoring check" block. Three properties are
101
- deliberate: it adds no read of its own (`library.list()` already reads every SKILL.md to parse
102
- its frontmatter — that listing is what publishes `description` — and the hint never calls
103
- `library.read`, never holds a body and never compares content); it is a HINT (the write proceeds
104
- — only the model's next decision changes); and a listing failure degrades to a named line instead of
105
- silence, because "nothing similar was checked" and "nothing similar exists" must not look alike. The
106
- library-wide BODY scan stays where it was, in the `review` action.
107
-
108
- ### The retention line
109
-
110
- A whole-body replacement that keeps less than half of the previous SKILL.md says so in the same result
111
- message (`Content kept 26% of the previous body (2104 of 8123 characters); the replaced version is
112
- preserved in this skill's history.`). It is computed where the write path still holds both bodies — the
113
- library's own in-lock read, core `contentRetentionFeedback` — because a caller re-reading the file
114
- would race the writers the library serializes. Like the duplicate hint it is FEEDBACK, not a gate: no ratio
115
- refuses a write, small skills stay quiet (a 40-character skill cut in half is not news), and patches,
116
- support-file writes, creates and archives have no ratio to report.
117
-
118
- ## Known limitations
119
-
120
- - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
121
-
122
- **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
123
-
124
- ## Notes and history
125
-
126
- - pin/unpin: explicit exception (0.3.18, E-70)
23
+ `maxSkillContentChars` → `skillContentChars`。旧名仍可读,写入会拒绝。
package/lib/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, EXTRACT_PROMPT_V1, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, anchorVerdict, authoringFeedback, authorityFrom, buildExtractPlanFromLibrary, callingScope, clampOnce, computeDedupGroups, contentHash, createSubagentChannel, evolutionIoAdapter, fuzzyPatch, isPresent, isUnknown, liveBool, nearDuplicateSummaries, newSkillLibrary, normalizeFrontmatter, ownerCandidatesFromSummaries, ownerDecisionText, paramRowId, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, projectExtractBodies, proposalFromPlan, protectedSkillNamesOf, resolveExecOrigins, sessionReadSkillNames, skillWriteGateContext, unwrapLive, userSetKeys, writeProposalReport } from "@lmzhen/dsh-evolution-core";
1
+ import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, EXTRACT_PROMPT_V1, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, anchorVerdict, authoringFeedback, authorityFrom, buildExtractPlanFromLibrary, callingScope, clampOnce, computeDedupGroups, contentHash, createSubagentChannel, evolutionIoAdapter, fuzzyPatch, isPresent, isUnknown, liveBool, nearDuplicateSummaries, newSkillLibrary, normalizeFrontmatter, ownerCandidatesFromSummaries, ownerDecisionText, paramRowId, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, projectExtractBodies, proposalFromPlan, protectedSkillNamesOf, resolveExecOrigins, sessionReadSkillNames, sessionReadSupportFiles, skillWriteGateContext, unwrapLive, userSetKeys, writeProposalReport } from "@lmzhen/dsh-evolution-core";
2
2
  import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
3
3
  import z from "@deepseek-ai/schemastery";
4
4
  import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -778,9 +778,13 @@ function apply(ctx, rawConfig = {}) {
778
778
  }
779
779
  if (result.normalizedFrontmatterFields && result.normalizedFrontmatterFields.length > 0) feedbackLines.push(`frontmatter auto-quoted (YAML compatibility): ${result.normalizedFrontmatterFields.join(", ")}`);
780
780
  const mutating = !isReadOnlyAction(action) && !(action === "extract" && args.dry_run === true);
781
- if (name && action === "create") await ctx.skillUsage.ensureRecordCreated(name, origin !== "foreground");
782
- if (name && action === "delete") await ctx.skillUsage.markArchived(name);
783
- else if (name && mutating && action !== "create" && result.noop !== true) await ctx.skillUsage.record(name, "patch");
781
+ try {
782
+ if (name && action === "create") await ctx.skillUsage.ensureRecordCreated(name, origin !== "foreground");
783
+ if (name && action === "delete") await ctx.skillUsage.markArchived(name);
784
+ else if (name && mutating && action !== "create" && result.noop !== true) await ctx.skillUsage.record(name, "patch");
785
+ } catch (error) {
786
+ ctx.logger.warn("evolution skill_manage: usage bookkeeping failed after the write landed: " + (error instanceof Error ? error.message : String(error)));
787
+ }
784
788
  }
785
789
  return {
786
790
  ok: result.ok,
@@ -987,6 +991,7 @@ function apply(ctx, rawConfig = {}) {
987
991
  origin: libraryOrigin,
988
992
  protectedNames: protectedSkillNamesOf(ctx.get("evolutionPolicy")),
989
993
  readNames: sessionReadSkillNames(ctx, exec.agent?.session),
994
+ readSupportFiles: sessionReadSupportFiles(ctx, exec.agent?.session, { root: library.root }),
990
995
  confirm: async (request) => confirmSkillWrite(request, exec),
991
996
  confirmMode: approvalSeam !== void 0 && approvalSeam.isEnabled !== false && sessionPolicy !== "never" && (libraryOrigin === "background_review" || approvalSeam.stageForeground !== false) ? "auto" : settings().skillWriteConfirm,
992
997
  confirmTimeoutSeconds: settings().skillWriteConfirmTimeoutSeconds,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lmzhen/dsh-tool-skill-manage",
3
3
  "description": "Model-facing skill_manage tool (community build)",
4
- "version": "0.32.3",
4
+ "version": "0.32.5",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -27,8 +27,8 @@
27
27
  "license": "MIT",
28
28
  "dependencies": {
29
29
  "@deepseek-ai/schemastery": "^3.18.5",
30
- "@lmzhen/dsh-evolution-approval": "^0.32.3",
31
- "@lmzhen/dsh-evolution-core": "^0.32.3"
30
+ "@lmzhen/dsh-evolution-approval": "^0.32.5",
31
+ "@lmzhen/dsh-evolution-core": "^0.32.5"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "@deepseek-ai/cordis": "^4.0.5",
@@ -36,17 +36,17 @@
36
36
  "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.2",
37
37
  "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
38
38
  "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
39
- "@lmzhen/dsh-evolution-io": "^0.32.3",
40
- "@lmzhen/dsh-skill-usage": "^0.32.3"
39
+ "@lmzhen/dsh-evolution-io": "^0.32.5",
40
+ "@lmzhen/dsh-skill-usage": "^0.32.5"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.1-rc.2",
44
44
  "@deepseek-ai/dsh-skill": "^0.2.1-rc.2",
45
45
  "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.2",
46
46
  "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
47
- "@lmzhen/dsh-evolution-core": "^0.32.3",
48
- "@lmzhen/dsh-evolution-io": "^0.32.3",
49
- "@lmzhen/dsh-skill-usage": "^0.32.3"
47
+ "@lmzhen/dsh-evolution-core": "^0.32.5",
48
+ "@lmzhen/dsh-evolution-io": "^0.32.5",
49
+ "@lmzhen/dsh-skill-usage": "^0.32.5"
50
50
  },
51
51
  "engines": {
52
52
  "dsh": ">=0.2.1-rc.2 <0.2.2-0"