@morehao/dsh-commands 0.0.0 → 0.1.0

package/README.md

@@ -1,45 +1,61 @@
-# @morehao/dsh-commands
+# dsh-commands
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+一个可扩展的 **dsh 原生斜杠命令集合包**（npm 名 `@morehao/dsh-commands`，仓库目录仍为 `commands-dsh/`）。当前内置 git-kit 的 Git 工作流命令（与 opencode 入口、自然语言入口共用 git-kit 同一实现，单一真源）；将来其它 skill 的命令只需往 `lib/index.js` 的 `COMMANDS` 表加条目即可。
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## 提供的命令
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+| 命令 | 参数 | 委托的 git-kit 分支 |
+|---|---|---|
+| `/git-message` | `<中文描述>`（必填） | commit-message |
+| `/git-commit-push` | 无 | commit-push |
+| `/git-branch` | `<中文描述>`（必填） | branch |
+| `/git-pr-create` | `[目标分支]` | pr-create |
+| `/git-pr-merge` | `[PR/MR 编号]` | pr-merge |
+| `/git-tag` | `[tag名或分支名]` | tag |
+| `/git-slim` | `[保留天数]` | slim |
+| `/git-star-classify` | 无 | star-classify |
 
-## Purpose
+## 原理（命令 = 意图表）
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@morehao/dsh-commands`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+每条 dsh 命令注册到 `ctx.commands`（`name`/`description`/`input.hint`/`handler`，即 `CommandDefinition`），出现在 dsh 斜杠菜单。`COMMANDS` 表是**自包含的意图表**：一行声明 = 注册元数据 + 对应的 git-kit 分支 key，**不再读取任何仓库文件**，逻辑与路由唯一真源在 `skills/git-kit`（`SKILL.md` 意图决策树 + `references/` + `scripts/`）。
 
-## What is OIDC Trusted Publishing?
+命令执行时 handler 校验必填输入，然后构造一条 user 消息经 `invocation.agent.followup()` 注入当前会话，由 agent 加载 `git-kit` 并落到对应分支执行——交互确认步骤与自然语言触发 git-kit 完全一致。
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- 编辑 `skills/git-kit/` 的内容**无需重启**，下次执行即生效。
+- 修改本插件的 `lib/index.js`（含 `COMMANDS` 表）需重启 dsh web 生效。
 
-## Setup Instructions
+## 安装
 
-To properly configure OIDC trusted publishing for this package:
+本插件已发布到 npm（`@morehao/dsh-commands`），可通过 dsh 一条命令安装：
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```bash
+# 从 npm 安装已发布版本（git-kit skill 仍需由 ai-kit 提供，见下方说明）
+dsh plugin --profile web add @morehao/dsh-commands
+# 重启 dsh web
+```
 
-## DO NOT USE THIS PACKAGE
+> **skill 依赖**：插件只声明「命令 → git-kit 分支」意图表，真正的执行授权给 `git-kit` skill。而 dsh 不从 node_modules 扫描 skill，所以仍需把 `skills/git-kit/` 放入 `$DSH_HOME/skills`（默认 `~/.dsh/skills`）。完整一键接入见仓库根 `./scripts/dsh-install.sh`，它同时软链 `skills/*` 并以 `link:`（开发模式，源码改动即生效）方式接入本插件。
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+本地开发 / 测试用 `link:` 方式（源码即时生效）：
 
-## More Information
+```bash
+./scripts/dsh-install.sh
+# 重启 dsh web
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## 开发
 
----
+- 增删命令：改 `lib/index.js` 的 `COMMANDS` 表即可（每条一行声明）；`branch` 值必须与 git-kit `SKILL.md` 决策树的分支 key 一致。
+- 命令与 opencode 侧 `commands-opencode/git/*.md` 是同一 git-kit 的两条入口，只声明意图、不重复逻辑。
 
-**Maintained for OIDC setup purposes only**
+## 发布（自动）
+
+用 **changesets** 做自动版本管理与发布（见仓库根 `.github/workflows/release.yml` + `.changeset/config.json`）：
+
+- 每次改动 `lib/index.js` 或 `cordis.patch.yml` 后，在改动所在 PR 里执行
+  ```bash
+  pnpm changeset
+  ```
+  按提示选择 `patch`/`minor`/`major`，会在 `.changeset/` 生成一行版本描述。
+- merge 到 `main` 后，release workflow 自动开「Version Packages」PR；合并它即把新版本发布到 npmjs。
+- **关键约定**：`package.json` 的 `name`（npm 包名）与 `cordis.patch.yml` 的 `insert[0].name`（dsh 启动时 `import()` 的**模块标识符**）必须一致；`lib/index.js` 的 `export const name`（cordis 插件名）与 `cordis.patch.yml` 的 `insert[0].id` 保持一致即可，但与模块标识符解耦。改包名时请三者同步核对。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-commands profile bundle patch：把插件注册进配置树。
+# `name` 是 dsh 启动时用于 import() 的**模块标识符**，必须与 npm 包名一致（scoped）。
+# `id` 是 cordis 配置树内的键，与插件导出的 cordis 插件名保持一致（dsh-commands）。
+- insert:
+    - id: dsh-commands
+      name: '@morehao/dsh-commands'

package/lib/index.js

@@ -0,0 +1,137 @@
+/**
+ * dsh-commands —— 把 ai-kit 的 git-kit Git 工作流以 dsh 原生命令方式接入（可扩展其他命令）。
+ *
+ * 架构（命令 = 意图表，单一真源在 git-kit skill）：
+ * - 逻辑与「意图路由」的唯一真源是 `skills/git-kit`（SKILL.md 意图决策树 +
+ *   references/ + scripts/）。本插件不复制逻辑，只声明「命令 → git-kit 分支」的
+ *   映射表（COMMANDS），是 dsh 斜杠侧的一条薄入口，与 opencode 的
+ *   `commands-opencode/git/*.md`、自然语言触发互为入口。
+ * - 每条命令注册到 ctx.commands（CommandDefinition：name/description/input.hint/
+ *   handler），出现在 dsh 斜杠菜单；handler 校验必填输入后构造一条 user 消息，
+ *   经 invocation.agent.followup() 注入当前会话，让 agent 按 git-kit 对应分支执行。
+ * - 本模块自包含：不读取 ai-kit 仓库内任何文件、无路径耦合、不依赖
+ *   @deepseek-ai/* 运行时 import（消息对象手工构造为官方 createUserMessage 的
+ *   契约形状：role/source/content/id 全齐）。改 git-kit skill 无需重启；
+ *   改本文件（含 COMMANDS 表）需重启 dsh web。
+ *
+ * git-kit 分支 key 词汇表（与 SKILL.md 决策树对齐）：
+ *   commit-push / commit-message / branch / pr-create / pr-merge / tag / slim / star-classify
+ */
+
+import { randomUUID } from "node:crypto";
+
+export const name = "dsh-commands";
+export const inject = ["commands"];
+
+/**
+ * 命令意图表。每条 = 一行声明：注册元数据 + git-kit 分支 key。
+ * `branch` 必须与 skills/git-kit/SKILL.md 决策树的分支 key 一致。
+ */
+const COMMANDS = [
+	{
+		name: "git-message",
+		branch: "commit-message",
+		hint: "<中文描述>",
+		required: true,
+		description: "将中文描述转换为 Conventional Commits 格式的 commit message（纯生成，不提交）"
+	},
+	{
+		name: "git-commit-push",
+		branch: "commit-push",
+		description: "基于代码变更生成 commit message 并自动提交推送到远端；稳定分支（main/master/含 release）时自动创建分支"
+	},
+	{
+		name: "git-branch",
+		branch: "branch",
+		hint: "<中文描述>",
+		required: true,
+		description: "基于中文描述生成候选分支名，选择后从基准分支创建并切换"
+	},
+	{
+		name: "git-pr-create",
+		branch: "pr-create",
+		hint: "[目标分支]",
+		description: "基于代码差异向目标仓库创建或更新 PR/MR（自动识别 gh/glab）"
+	},
+	{
+		name: "git-pr-merge",
+		branch: "pr-merge",
+		hint: "[PR/MR 编号]",
+		description: "按编号合并 PR/MR（自动识别 gh/glab），删除原分支，切回主干并更新代码"
+	},
+	{
+		name: "git-tag",
+		branch: "tag",
+		hint: "[tag名或分支名]",
+		description: "查看最新 tag 与来源分支，选择分支与版本号，构建注记 tag 并推送到远端"
+	},
+	{
+		name: "git-slim",
+		branch: "slim",
+		hint: "[保留天数]",
+		description: "将当前 git 仓库瘦身为浅克隆，默认保留最近 30 天历史，保留本地未提交改动"
+	},
+	{
+		name: "git-star-classify",
+		branch: "star-classify",
+		description: "拉取并分类你自己的 GitHub star 仓库，输出按大类分组的中文 Markdown 清单"
+	}
+];
+
+/** 构造一条 user 消息（形态与官方 createUserMessage 一致，source 必填，全深冻结）。 */
+function userMessage(text) {
+	return Object.freeze({
+		role: "user",
+		// dsh 的 Message 契约要求 source 字段（读 message.source.kind），缺失会在 agent 回合崩溃。
+		source: Object.freeze({ kind: "user" }),
+		content: Object.freeze([Object.freeze({ type: "text", text })]),
+		id: randomUUID()
+	});
+}
+
+/**
+ * 构造注入当前会话的指令：告知用户请求，并把执行交给 git-kit 的对应分支。
+ * git-kit 分支的完整流程（references/ 与 scripts/）由 agent 加载 skill 后自行读取，
+ * 这里不复制任何逻辑，只做意图指路。
+ */
+function buildInstruction(def, input) {
+	return [
+		`【dsh 命令 /${def.name}】`,
+		`用户请求：${input.length > 0 ? input : "（未附加说明，按分支流程默认处理）"}`,
+		"",
+		`请用 skill 工具加载 git-kit，将本次请求视为 ${def.branch} 分支并按该分支的完整流程执行。`,
+		"如需用户决策（候选分支名 / PR·MR 编号 / tag 版本号 / 保留天数等），先向用户确认再继续。"
+	].join("\n");
+}
+
+function makeHandler(def) {
+	return (invocation) => {
+		const input = invocation.rawInput.trim();
+		if (def.required && input.length === 0) {
+			return { kind: "error", text: `Usage: /${def.name} ${def.hint}\n例如：/${def.name} 修复登录超时` };
+		}
+		const instruction = buildInstruction(def, input);
+		try {
+			invocation.agent.followup(userMessage(instruction));
+		} catch (error) {
+			return {
+				kind: "error",
+				text: `已生成委托指令，但无法交给当前会话执行：${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		return { kind: "success", text: `已按 git-kit ${def.branch} 分支委托执行 /${def.name}，agent 将按流程继续。` };
+	};
+}
+
+export function apply(ctx) {
+	ctx.effect(function* () {
+		for (const def of COMMANDS) {
+			yield ctx.commands.register({
+				name: def.name,
+				description: def.description,
+				...(def.hint === undefined ? {} : { input: { hint: def.hint } }),
+				handler: makeHandler(def)
+			});
+		}
+	}, "dsh-commands lifecycle");
+}

package/package.json

@@ -1,10 +1,41 @@
 {
   "name": "@morehao/dsh-commands",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @morehao/dsh-commands",
+  "version": "0.1.0",
+  "description": "把 ai-kit 的 git-kit Git 工作流以 dsh 原生斜杠命令接入（薄意图表，委托 git-kit skill 执行）",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "author": "morehao <morehao@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/morehao/ai-kit.git",
+    "directory": "commands-dsh"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "dsh",
+    "dsh-plugin",
+    "dsh-command",
+    "git",
+    "git-kit",
+    "conventional-commits"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
 }