@xuanling-rs/xuanling-dsh-skills 0.2.2 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umbrella22 and XuanLing contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-ZH.md

@@ -0,0 +1,21 @@
+# xuanling-dsh-skills
+
+[English](README.md) | 简体中文
+
+该 DeepSeek Harness bundle 包含两个按需 XuanLing 工作流 Skill 和严格整文件覆盖 policy。
+它不注册 MCP server，也不依赖 `@xuanling-rs/xuanling-mcp`。
+
+```sh
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-skills@0.2.4
+```
+
+该命令会扩展 DSH 内置的 Web profile。内置 Headless profile 应使用 `--profile headless`。
+未知 profile 名称只包含 base bundle，本身不会提供可运行的 Web 或 Headless 应用。
+
+请与且仅与一个 XuanLing 工具 bundle 组合使用。只有 fs 工具族可见时，
+`xuanling-file-workflow` 才在 Harness 原生与 XuanLing 文件工具之间路由，并覆盖 CAS overwrite、
+复合后缀、原子多 hunk patch、确定性重复验证和 Host 后台任务。`xuanling-memory-workflow` 将项目
+局部 L1 事实与共享 XuanLing L2 事实分开，按显式指针 pull recall，并保持 proposal/review 边界。
+Policy 会在 MCP dispatch 前拒绝缺少 `expected_sha256` 的既有文件覆盖。
+
+要求 Node.js 22.14 或更高版本。使用 MIT License。

package/README.md

@@ -0,0 +1,26 @@
+# xuanling-dsh-skills
+
+English | [Simplified Chinese](README-ZH.md)
+
+DeepSeek Harness bundle containing two on-demand XuanLing workflow Skills and
+the strict whole-file overwrite policy. It registers no MCP server and has no
+dependency on `@xuanling-rs/xuanling-mcp`.
+
+```sh
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-skills@0.2.4
+```
+
+This command augments DSH's shipped Web profile. Use `--profile headless` for
+the shipped Headless profile. Unknown profile names start with the base bundle
+only and do not provide a runnable Web or Headless application by themselves.
+
+Use it with exactly one XuanLing tool bundle. `xuanling-file-workflow` routes
+between Harness-native and XuanLing file tools only when the fs family is
+visible; it also covers CAS overwrite, compound suffixes, atomic multi-hunk
+patches, deterministic repeated validation, and host background jobs.
+`xuanling-memory-workflow` keeps project-local L1 facts separate from shared
+XuanLing L2 facts, uses explicit pointer-driven pull recall, and preserves the
+proposal/review boundary. The policy rejects an existing-file overwrite
+without `expected_sha256` before MCP dispatch.
+
+Node.js 22.14 or newer is required. Licensed under the MIT License.

package/cordis.patch.yml

@@ -0,0 +1,28 @@
+# XuanLing on-demand skills for DeepSeek Harness.
+#
+# One insert block mounts a dedicated @deepseek-ai/dsh-skill-filesystem
+# provider that sees ONLY this bundle's skills/ directory and the strict
+# XuanLing overwrite policy from this installed package:
+#   - providerName is unique ("xuanling-dsh-skills"), so it never clashes
+#     with the preset's own "filesystem" provider registration;
+#   - includeDefaultRoots stays false: no dependence on ~/.dsh/skills or any
+#     project skill root — the two skills travel with the bundle;
+#   - watch stays false: the shipped contents are static, so the catalog
+#     digest and request history stay stable.
+#
+# An installed profile resolves the skill directory and policy module through
+# this package. XUANLING_DSH_SKILLS_ROOT remains a development override for the
+# content root; the policy module itself must be profile-installed so Loader
+# resolves one stable package specifier.
+
+- insert:
+    - id: xuanling-skills
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: xuanling-dsh-skills
+        includeDefaultRoots: false
+        watch: false
+        customSkillDirs:
+          - !!js process.env.XUANLING_DSH_SKILLS_ROOT ?? process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@xuanling-rs/xuanling-dsh-skills/package.json')), 'skills')
+    - id: xuanling-file-policy
+      name: '@xuanling-rs/xuanling-dsh-skills/strict-overwrite-policy.mjs'

package/package.json

@@ -1,9 +1,28 @@
 {
   "name": "@xuanling-rs/xuanling-dsh-skills",
-  "version": "0.2.2",
-  "description": "XuanLing bootstrap placeholder; replaced by the verified 0.2.3 release.",
+  "version": "0.2.4",
+  "description": "DeepSeek Harness bundle: mounts isolated XuanLing workflow skills and the strict MCP overwrite policy.",
   "license": "MIT",
   "private": false,
+  "dependencies": {
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.5"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README-ZH.md",
+    "cordis.patch.yml",
+    "strict-overwrite-policy.mjs",
+    "skills/xuanling-file-workflow/SKILL.md",
+    "skills/xuanling-file-workflow/agents/openai.yaml",
+    "skills/xuanling-memory-workflow/SKILL.md",
+    "skills/xuanling-memory-workflow/agents/openai.yaml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
   "engines": {
     "node": ">=22.14.0"
   },
@@ -18,6 +37,10 @@
   },
   "publishConfig": {
     "access": "public",
+    "provenance": true,
     "registry": "https://registry.npmjs.org"
+  },
+  "xuanlingRelease": {
+    "sourceCommit": "3fc3e6304a4839de292bf7470f0dbf3f6a7ebe59"
   }
 }

package/skills/xuanling-file-workflow/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: xuanling-file-workflow
+description: Guides DeepSeek Harness agents in choosing between harness-native file tools and a visible XuanLing mcp__xuanling__fs_ family. Use when both families are available and file work needs sha256/CAS guards, strict patches, complete pagination, explicit byte budgets, compound-suffix search, or deterministic repeated validation.
+---
+
+# XuanLing File Workflow
+
+This workspace exposes two file-tool families. Pick one deliberately for each
+operation; both are first-class, and neither is a fallback for the other.
+Apply this workflow only when the named `mcp__xuanling__fs_*` tools are
+visible. A memory-only bundle does not provide file or process tools; keep
+using the native family there instead of inferring unavailable tools.
+
+## Families
+
+- **Native file tools** (`read`, `write`, `edit`, `grep`, `glob`, ...): deeply
+  integrated with the harness. They carry the read-before-edit observation
+  guard, native diff/read UI cards, and the workspace sandbox policy.
+- **XuanLing tools** (`mcp__xuanling__fs_*`, for example
+  `mcp__xuanling__fs_read_text`, `mcp__xuanling__fs_edit`,
+  `mcp__xuanling__fs_search`): typed cross-platform filesystem tools with
+  sha256 preimage guards, explicit byte budgets, strict patches, and
+  resumable pagination. Results are structured JSON, identical on every OS.
+
+## Routing rules
+
+1. Prefer the native file tools for routine small edits and ordinary reads:
+   their observation policy and editor cards are part of the harness UX, and
+   they avoid extra ceremony for one-line changes.
+2. Choose the XuanLing family when the operation needs what only it provides:
+   - **Hash/CAS-protected writes**: verify the file is unchanged since your
+     last read with `expected_sha256` / `expected_preimage_sha256` before
+     replacing or patching it.
+   - **Explicit output limits**: request a bounded result with an `output`
+     byte budget (`max_bytes`) and continue later through the returned
+     cursor or resume token instead of truncating silently.
+   - **Strict edits**: apply a verified unified diff with
+     `mcp__xuanling__fs_patch` (preimage-hash guarded), or a unique-match
+     replacement with `mcp__xuanling__fs_edit` / `mcp__xuanling__fs_replace_text`.
+     For one file with multiple hunks, prefer `mcp__xuanling__fs_patch` in a
+     single atomic call with the full preimage hash; do not split the change
+     into independently committed edits or invent another batch tool.
+   - **Full pagination**: list or search with a bounded window and page
+     through every remaining entry with the typed cursor.
+   - **Whole-file creation or replacement**: use `mode: "create"` for a new
+     file. To replace an existing file, obtain its hash with
+     `mcp__xuanling__fs_read_text` (`include_sha256: true`) or
+     `mcp__xuanling__fs_hash`, then pass both `mode: "overwrite"` and the
+     returned `expected_sha256`. Never omit `mode` for a whole-file write.
+3. Do not use the shell tools (bash, pwsh, terminals) for any file operation
+   this skill covers; the two file families are sufficient, and shell output
+   is not portable evidence.
+4. Read what you need, then act. Avoid re-reading a file you just verified by
+   sha256; avoid issuing the same search twice without consuming the cursor.
+
+## Schema gotchas that bite in practice
+
+- `mcp__xuanling__fs_search` takes the search term in `pattern`; `literal` is
+  a boolean, not a string. There is no `query` field.
+- `mcp__xuanling__fs_glob` takes `patterns` (plural array); `*.mjs` matches
+  one level only, use `**/*.mjs` to recurse.
+- `mcp__xuanling__fs_search.file_extensions` uses exact simple or compound
+  suffixes. Pass `d.ts` and `d.mts` directly (and simple values such as
+  `java` or `.c`); never reduce a compound suffix to its last `ts` or `mts`
+  segment, which would broaden the search.
+- The `output` selector of any window-capable tool is a tagged object such as
+  `{"mode":"bounded","max_bytes":65536}` — never a number or a bare string.
+
+## Verification
+
+For repeated validation with the same argv through `mcp__xuanling__process_run`,
+`mcp__xuanling__project_run`, or `mcp__xuanling__process_pipeline`, pass
+`deterministic: true`. This omits volatile duration fields so results can be
+byte-stable; it does not cache or skip command execution.
+
+For a long build, test suite, or watch process that may exceed the MCP call
+deadline, use the Harness-native background/job mechanism. Do not fabricate
+timeouts, sleep loops, or shell wrappers around a synchronous XuanLing call.
+
+## Failure handling
+
+- `XUANLING_FS_OVERWRITE_REQUIRES_SHA256` means the DSH policy stopped an
+  unsafe whole-file replacement before MCP dispatch. Read or hash the file,
+  reconstruct the intended content from that current version, and retry with
+  `expected_sha256`. Do not switch to `mode: "create"` for an existing file.
+- Treat every typed tool error as information: a duplicate-match error means
+  supply more context or an explicit replace-all decision; a conflict means
+  the file changed under you, so re-read and rebuild the edit.
+- You must not silently fall back to the other family when a tool fails.
+  Surface the error, correct the request, and retry within the same family;
+  switching families because of a failure needs a stated reason.
+- The XuanLing server enforces a workspace root. Paths outside it are denied
+  by design; fix the path instead of escalating.

package/skills/xuanling-file-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XuanLing File Workflow"
+  short_description: "Choose between native and XuanLing file tools"
+  default_prompt: "Use $xuanling-file-workflow to pick the right file tools for this edit."

package/skills/xuanling-memory-workflow/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: xuanling-memory-workflow
+description: Guides DeepSeek Harness agents in routing host file memory (L1) and XuanLing shared lexical memory (L2). Use when recalling an explicit memory pointer, retaining a cross-project fact, preparing a pending candidate, or handling an explicit user review decision. Enforces single-write storage and separate proposal/review turns.
+---
+
+# XuanLing Memory Workflow
+
+XuanLing memory is proposal-first: nothing you write becomes a canonical
+record until a human decides on the proposal. Two separate turns, always.
+
+## Choose one memory layer
+
+For a project-local must-see convention that belongs in every session, write
+only the host file memory (L1). Make zero XuanLing write and do not create a
+candidate for the same content.
+
+For a cross-project, team-level, or shared fact that the user wants retained
+in XuanLing L2, call `memory_search` first. If the fact is absent or has no
+match, call `memory_candidate_create` to create a pending candidate; only a
+later explicit user review can make it canonical.
+
+At task begin or after a topic switch, follow an explicit L1 memory pointer by
+issuing one scoped `memory_search`. This is a pull trigger, not an instruction
+to search on every turn.
+
+## Before writing anything
+
+1. Search first with `memory_search` (namespaces, scopes, and tags matter —
+   a duplicate record is worse than no record).
+2. Read the exact current content with `memory_get` when a hit looks close.
+   Updating means a replace proposal against that record's current revision,
+   not a second create.
+
+`memory_search` returns complete active `MemoryRecordView` values inside its
+ranked items, not a lightweight manifest. Keep the first query scoped and
+small, then use `memory_get` only when an exact current record is required.
+
+## Creating a candidate
+
+- Call `memory_candidate_create` with the full payload: kind (`fact`,
+  `preference`, `procedure`, `solution`, or `summary`), content, and a
+  one-line title/summary. Include an `idempotency_key` you derive from the
+  proposal's meaning.
+- The call only creates a pending candidate. Report the returned proposal id
+  and its revision to the user, then stop: the terminal state without review
+  is awaiting review.
+- To retry a failed candidate call, reuse the same idempotency key with the
+  same payload. Changing the payload under a reused key is a conflict; that
+  is correct behavior, not an error to work around.
+- Replacing or archiving follows the same shape: `memory_candidate_replace`
+  or `memory_candidate_archive` targets a specific record revision, and the
+  server refuses to apply it if that revision went stale.
+
+## The review gate
+
+- Call `memory_review` only after an explicit user instruction — an approval
+  or rejection decision that names the concrete proposal. A conversational
+  "looks good" during other work is not that decision; ask the user to
+  confirm the specific proposal id if in doubt.
+- Never describe yourself or this agent as the human reviewer. You propose;
+  the user disposes. When you report a review outcome, attribute the decision
+  to the user who made it.
+- Never approve a proposal to finish a task, save tokens, or unblock a
+  workflow; an unreviewed candidate is a correct end state.
+
+## When not to write
+
+- If recall has no match or the store is unavailable during ordinary work,
+  continue the main task and make zero canonical write. Do not invent a fact
+  or treat a partial candidate as a fallback result.
+- Parse failures, model hiccups, tool errors, or an unavailable store mean
+  you skip the write entirely. Do not create partial or best-effort
+  candidates to compensate; just continue the user's task and mention the
+  skipped save if it matters.
+- Nothing here authorizes writing secrets, raw credentials, or user-private
+  content into the shared store.
+- Feedback after recall uses `memory_feedback` on a specific record revision
+  and is safe anytime.
+
+## Scope and namespace quick reference
+
+- `scope` is a tagged object: `{"type":"global"}`,
+  `{"type":"project","project_id":...}`, or
+  `{"type":"workspace","project_id":...,"workspace_id":...}`.
+- Search walks ancestor scopes only when asked; sibling projects never leak.

package/skills/xuanling-memory-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XuanLing Memory Workflow"
+  short_description: "Proposal-first XuanLing memory lifecycle"
+  default_prompt: "Use $xuanling-memory-workflow to save this insight as a pending proposal."

package/strict-overwrite-policy.mjs

@@ -0,0 +1,45 @@
+const GUARDED_TOOL = "mcp__xuanling__fs_write_text";
+
+export const STRICT_OVERWRITE_DENIAL =
+  "[XUANLING_FS_OVERWRITE_REQUIRES_SHA256] " +
+  "mcp__xuanling__fs_write_text mode=overwrite requires a non-empty " +
+  "expected_sha256; read with include_sha256=true or call " +
+  "mcp__xuanling__fs_hash, then retry";
+
+export const name = "xuanling-strict-overwrite-policy";
+
+/**
+ * Decide only the DSH-specific precondition. XuanLing remains responsible for
+ * canonical schema validation, hash format, current-file CAS, and filesystem
+ * effects.
+ */
+export function decideStrictOverwrite(toolName, argumentsValue) {
+  if (toolName !== GUARDED_TOOL) return { kind: "delegate" };
+  if (
+    typeof argumentsValue !== "object" ||
+    argumentsValue === null ||
+    Array.isArray(argumentsValue)
+  ) {
+    return { kind: "delegate" };
+  }
+
+  const mode = argumentsValue.mode;
+  if (mode === "create") return { kind: "delegate" };
+  if (mode !== undefined && mode !== "overwrite") {
+    return { kind: "delegate" };
+  }
+
+  const expectedSha256 = argumentsValue.expected_sha256;
+  if (typeof expectedSha256 === "string" && expectedSha256.length > 0) {
+    return { kind: "delegate" };
+  }
+  return { kind: "deny", reason: STRICT_OVERWRITE_DENIAL };
+}
+
+export function apply(ctx) {
+  ctx.on("tools/pre-execute", (exec, next) => {
+    const decision = decideStrictOverwrite(exec.name, exec.arguments);
+    if (decision.kind === "deny") return Promise.resolve(decision);
+    return next();
+  });
+}