@dawn0608/dsh-skill-manager 0.1.1 → 0.1.2

package/README.md

@@ -2,35 +2,57 @@
 
 English | [中文](README.zh.md)
 
-Open **Skills** below **Plugins** in the DeepSeek Harness sidebar. Search the global catalog by name or description. Open a skill to see its description and rendered `SKILL.md`, with its provenance badge or repository link beside the title.
+## Features
 
-## Manage skills
+Open **Skills** below **Plugins** in the DeepSeek Harness sidebar. Search the global catalog, inspect rendered `SKILL.md`, and see provenance or the original repository. Built-in, Self-authored, and Third-party groups use the existing Harness controls. This plugin does not add another management page.
 
-- The catalog groups skills as Built-in, Self-authored, and Third-party. Skills with unconfirmed provenance appear under Third-party.
-- For shared skills, record provenance in `~/.agents/skills/.provenance.json` (or under `$DSH_AGENTS_HOME/skills`). Use the instruction file path relative to the skills root, such as `my-skill/SKILL.md`, as the key. Set `origin` to `self` or `third-party`. For a third-party skill, an optional credential-free HTTPS `repository` URL appears as a link in the detail view.
-- For a copy previously imported and managed by the plugin, use the switch in the list or detail view to enable or disable it, or uninstall it from the detail view. Managed copies live under `$DSH_HOME/skill-manager/bundles` and are activated in `$DSH_HOME/skills` for profiles using that home.
+## Installation
 
-## Install
-
-Requires DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`. In Desktop, open **Plugins → Add plugin** and enter `@dawn0608/dsh-skill-manager`. You can also install it with the CLI.
+In Desktop, open **Plugins → Add plugin** and enter `@dawn0608/dsh-skill-manager`, or run this command for your profile.
 
 ```bash
 dsh plugin --profile <profile> add @dawn0608/dsh-skill-manager
 ```
 
-To switch from a local checkout, remove the existing installation before adding the npm package. Restart Harness if prompted. To keep installing from source, run `npm ci` and `npm run build --workspace @dawn0608/dsh-skill-manager` at the repository root, then add the absolute path of `plugins/skill-manager` in Desktop.
+Upgrade through the Harness plugin manager and restart if prompted. To switch from a checkout, remove its installation before adding the npm package. Plugin installation does **not** install the optional background service. No postinstall script runs it.
 
-## Optional shared skill sync on macOS
+### Install or upgrade optional macOS shared sync
 
-The optional user service synchronizes enablement for shared global skills across Harness, Codex, and Claude Code. It runs at login and can handle Codex and Claude Code changes while Harness is closed. Set it up from a persistent checkout of the matching source release, with `node` and `codex` on your PATH. [Source release](https://github.com/dawn0608/dsh-plugins/tree/skill-manager-v0.1.1)
+Install or upgrade the service directly from npm.
 
 ```bash
-git clone --branch skill-manager-v0.1.1 https://github.com/dawn0608/dsh-plugins.git
-cd dsh-plugins
-npm ci
-node scripts/install-skill-sync.mjs
+npx --yes --package @dawn0608/dsh-skill-manager@0.1.2 dsh-skill-sync-install
 ```
 
-The installer configures a user LaunchAgent and Claude Code hooks, backs up existing Codex and Claude Code settings, and prints the backup path. Restart Harness and reopen Claude Code sessions to register their working directories.
+## Usage and configuration
+
+- Previously imported copies remain supported: use the switch to enable or disable a copy and the detail action to uninstall it. Bundles remain under `$DSH_HOME/skill-manager/bundles`, activated in `$DSH_HOME/skills`.
+- Shared skill provenance lives in `$DSH_AGENTS_HOME/skills/.provenance.json` (default `~/.agents/skills/.provenance.json`). Keys are relative paths such as `my-skill/SKILL.md`; `origin` is `self` or `third-party`. An optional credential-free HTTPS `repository` is shown for third-party skills. Unconfirmed origins appear under Third-party.
+- Shared skills use `$DSH_AGENTS_HOME/skills/<name>/SKILL.md`, with matching folder and skill names. The optional service manages Claude Code links, but only deletes links it created whose stored filesystem identity still matches. Preexisting links and older ownership claims without identity are preserved.
+
+### Configure shared sync
+
+The installer honors `DSH_HOME`, `DSH_AGENTS_HOME`, `CODEX_HOME`, and `CLAUDE_CONFIG_DIR`, including `~/`. Defaults are `~/.dsh`, `~/.agents`, `~/.codex`, and `~/.claude`. Set the same variables for Harness and the installer. `DSH_SKILL_SYNC_CODEX` can select the Codex executable. The installer copies a bundled, self-contained daemon into `$DSH_HOME/skill-manager/shared-sync/runtime`, installs `local.dsh-skill-sync` as a user LaunchAgent, and adds Claude Code `SessionStart` / `CwdChanged` hooks. It checks the new service identity before reporting success; existing unrelated hooks remain intact and only exact hooks proven by the previous owned LaunchAgent are migrated. Restart Harness and reopen Claude Code sessions to register workspaces.
+
+The service runs at login and synchronizes even while Harness is closed. Harness **Skills**, Codex **Skills**, and Claude Code `/skills` can toggle shared skills. Claude Code synchronization covers fully on/off states. Each destination's confirmed state is saved separately; failed writes retry against that baseline. A newer opposite external choice is preserved and reported as a conflict, which remains until an explicit Harness choice resolves it. Name collisions remain conflicts. Failures retain the last disabled Harness policy. The Skills page shows service failure/staleness and the last successful synchronization time. An already open Codex window may need restarting to reload its settings.
+
+### Stop and recover shared sync
+
+Uninstalling the plugin does **not** stop the independent daemon. Stop it explicitly:
+
+```bash
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/local.dsh-skill-sync.plist"
+```
+
+Remove that plist to prevent login startup, and remove only this service's exact command from Claude Code `SessionStart` / `CwdChanged` hooks. Keep unrelated hooks. Stopping synchronization leaves current enablement settings in place; restarting the service is done by rerunning the npm installer.
+
+Every install prints a private backup directory under `$DSH_HOME/skill-manager/shared-sync/backup-*`, with a manifest of original paths/existence, Claude and Codex settings, state, the previous runtime and plist when present. If startup/readiness fails, the installer restores its changed files and reloads the previously loaded service. Concurrent edits are preserved and reported for manual recovery. For manual recovery, stop the service first, inspect that manifest, and restore only the intended backup files; do not blindly overwrite newer settings. Existing disabled state is retained on sync failures. The daemon log is `$DSH_HOME/skill-manager/shared-sync/error.log`.
+
+## Compatibility and limitations
+
+- Requires DeepSeek Harness `>=0.2.2-rc.1 <0.3.0` and Node.js 24 or later.
+- Optional shared sync requires macOS and an installed `codex` CLI on PATH. Validate integration with launchd and your Codex and Claude Code sessions in your environment.
+
+## Development
 
-Put shared skills in `~/.agents/skills/<name>/SKILL.md`, matching the folder and skill name. The service maintains the Claude Code symlink. Use Harness **Skills**, Codex **Skills**, or Claude Code’s `/skills` to toggle a shared skill. For Claude Code, synchronization covers fully enabled and disabled states. Harness reports conflicts with a matching name in another location. If an open Codex desktop window still shows the previous state, restart it to reload the settings.
+From the repository root, run `npm test -w @dawn0608/dsh-skill-manager` for the plugin tests and `npm run verify` for the full repository check.

package/README.zh.md

@@ -2,35 +2,57 @@
 
 [English](README.md) | 中文
 
-在 DeepSeek Harness 左侧边栏的「插件」下方打开「技能」。可按名称或描述搜索全局技能。点击技能可查看描述和渲染后的 `SKILL.md`，并在标题旁查看归属标签或仓库链接。
+## 功能
 
-## 管理技能
-
-- 目录按内置技能、自建技能和第三方技能分组。归属待确认的技能暂列第三方。
-- 共享技能的归属记录在 `~/.agents/skills/.provenance.json`（或 `$DSH_AGENTS_HOME/skills` 下）。以说明文件相对技能根目录的路径为键，例如 `my-skill/SKILL.md`，将 `origin` 设为 `self` 或 `third-party`。第三方技能可填写不含凭据的 HTTPS `repository` 地址，详情页会将其显示为链接。
-- 此前由插件导入的受管副本可在列表或详情页启停，也可在详情页卸载。受管副本保存在 `$DSH_HOME/skill-manager/bundles`，通过 `$DSH_HOME/skills` 为使用同一主目录的 Harness profile 启用。
+从 DeepSeek Harness 侧边栏 **插件** 下方打开 **技能**，搜索全局技能目录、阅读渲染后的 `SKILL.md`，查看来源标记或原仓库。内置、自建、第三方分组复用 Harness 现有控件，不另加管理页面。
 
 ## 安装
 
-适用于 DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`。在 Desktop 打开「插件 → 添加插件」，输入 `@dawn0608/dsh-skill-manager`。也可以通过 CLI 安装。
+在 Desktop **插件 → 添加插件** 中输入 `@dawn0608/dsh-skill-manager`，或在 CLI 中为指定 profile 执行以下命令。
 
 ```bash
 dsh plugin --profile <profile> add @dawn0608/dsh-skill-manager
 ```
 
-从本地源码切换到 npm 包时，先移除已有安装，再添加 npm 包，并按提示重启。若继续使用源码安装，在仓库根目录运行 `npm ci` 和 `npm run build --workspace @dawn0608/dsh-skill-manager`，然后在 Desktop 添加 `plugins/skill-manager` 的绝对路径。
+通过 Harness 插件管理器升级，提示时重启。由源码目录切换到 npm 时，先移除旧目录安装。安装插件**不会**安装可选后台服务，也没有自动运行服务的 postinstall 脚本。
 
-## macOS 可选设置：同步共享技能
+### 安装或升级可选 macOS 共享同步服务
 
-用户级后台可同步 Harness、Codex 和 Claude Code 中共享全局技能的启停状态。后台随登录启动，在 Harness 关闭时也能处理 Codex 和 Claude Code 的变更。请在长期保留的对应版本源码目录中设置，并确保 PATH 中能找到 `node` 和 `codex`。[对应版本源码](https://github.com/dawn0608/dsh-plugins/tree/skill-manager-v0.1.1)
+通过 npm 直接安装或升级服务。
 
 ```bash
-git clone --branch skill-manager-v0.1.1 https://github.com/dawn0608/dsh-plugins.git
-cd dsh-plugins
-npm ci
-node scripts/install-skill-sync.mjs
+npx --yes --package @dawn0608/dsh-skill-manager@0.1.2 dsh-skill-sync-install
 ```
 
-安装脚本会配置用户级 LaunchAgent 和 Claude Code hooks，备份已有的 Codex 和 Claude Code 配置，并输出备份路径。随后重启 Harness，并重新打开 Claude Code 会话以登记工作目录。
+## 使用与配置
+
+- 保留已有导入副本的管理能力：用开关启停，在详情中卸载。副本仍位于 `$DSH_HOME/skill-manager/bundles`，通过 `$DSH_HOME/skills` 激活。
+- 共享技能来源记录在 `$DSH_AGENTS_HOME/skills/.provenance.json`，默认 `~/.agents/skills/.provenance.json`。键为 `my-skill/SKILL.md` 等相对路径，`origin` 为 `self` 或 `third-party`。第三方可填写不含凭据的 HTTPS `repository`，用于展示原仓库链接。来源未确认的技能归入第三方。
+- 共享技能放在 `$DSH_AGENTS_HOME/skills/<name>/SKILL.md`，文件夹名与技能名一致。可选服务维护 Claude Code 链接，仅删除自己创建且文件系统身份仍吻合的链接；保留预先存在的链接及缺少身份凭据的旧所有权记录。
+
+### 配置共享同步
+
+安装器支持 `DSH_HOME`、`DSH_AGENTS_HOME`、`CODEX_HOME`、`CLAUDE_CONFIG_DIR` 以及 `~/` 展开，默认分别为 `~/.dsh`、`~/.agents`、`~/.codex`、`~/.claude`。Harness 与安装器应使用同一组变量。可通过 `DSH_SKILL_SYNC_CODEX` 指定 Codex 可执行文件。安装器将已打包且自包含的 daemon 复制到 `$DSH_HOME/skill-manager/shared-sync/runtime`，配置用户 LaunchAgent `local.dsh-skill-sync` 和 Claude Code 的 `SessionStart` / `CwdChanged` hooks，并在新服务身份验证成功后报告完成。其他 hooks 保留，仅精准迁移由旧自有 LaunchAgent 证明归属的命令。重启 Harness 并重新打开 Claude Code 会话，以登记工作目录。
+
+服务随登录启动，Harness 关闭后仍会同步。可在 Harness **技能**、Codex **Skills** 或 Claude Code `/skills` 切换共享技能。Claude Code 同步涵盖完全开启或停用状态。各端确认成功后分别保存状态，失败重试前核对基线；保留外部新作出的反向选择并报告冲突，直到在 Harness 中显式选择解决。同名冲突保持可见。同步失败不会解除原有 Harness 停用策略。技能页提示服务异常或过期状态以及上次同步成功时间。已打开的 Codex 窗口可能需要重启才会重新读取设置。
+
+### 停止与恢复共享同步
+
+卸载插件**不会**停止独立 daemon。请显式停止：
+
+```bash
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/local.dsh-skill-sync.plist"
+```
+
+移除该 plist 可阻止下次登录启动；在 Claude Code 的 `SessionStart` / `CwdChanged` hooks 中仅移除本服务的准确命令，保留其他 hooks。停止同步会保留当前启停设置，重新运行 npm 安装器即可恢复服务。
+
+每次安装均输出 `$DSH_HOME/skill-manager/shared-sync/backup-*` 下的私有备份目录，包括原路径及是否存在的清单，以及原有 Claude/Codex 设置、同步状态、runtime 和 plist。启动或就绪检查失败时，安装器恢复本次改动的文件并重新加载原先正在运行的服务；并发修改会保留并提示人工恢复。手动恢复前先停服务、检查清单，仅恢复选定备份，不要直接覆盖更新的设置。同步失败时保留已有停用状态。daemon 日志位于 `$DSH_HOME/skill-manager/shared-sync/error.log`。
+
+## 兼容与限制
+
+- 要求 DeepSeek Harness `>=0.2.2-rc.1 <0.3.0` 和 Node.js 24 或更高版本。
+- 可选共享同步要求 macOS，且 PATH 中有可用的 `codex` CLI。请在实际环境中验收 launchd 与 Codex 和 Claude Code 会话的联动。
+
+## 开发
 
-将共享技能放在 `~/.agents/skills/<name>/SKILL.md`，保持目录名与技能名一致。后台维护 Claude Code 的软链接。可在 Harness「技能」、Codex「技能」或 Claude Code 的 `/skills` 中启停共享技能。Claude Code 侧同步完全启用和完全停用两种状态。遇到其他位置的同名冲突时，Harness 会提示检查。如果已打开的 Codex 桌面仍显示旧状态，重启 Codex 读取更新。
+在仓库根目录运行 `npm test -w @dawn0608/dsh-skill-manager` 检查本插件，或运行 `npm run verify` 验证整个仓库。