@godcreator/gwb-time 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 godcreator02
+
+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.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# gwb-time
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+东八区（UTC+8）时间。用户常在亚洲与美国之间往返，电脑的时区跟着变；写进文件名、目录名、id 的时间一律用东八区，
+同一时刻起的名字不管人在哪儿都一样。
+
+| 包 | 在哪 | 做什么 |
+| --- | --- | --- |
+| `@godcreator/utc8-time` | `packages/utc8-time/` | 库，零依赖：`utc8PartsOf`、`formatUtc8(at, 'yyMMddHHmm')`、`utc8Iso`，node 与浏览器都能用 |
+| `@godcreator/gwb-time` | `plugins/time/` | gwb 插件：状态栏右侧显示东八区的月日时分；命令 `time.now` 回起文件名常用的几种写法；随包说明书 `time` |
+
+插件把库打包进自己的产物，装插件不需要另装库；别的仓的代码要东八区时间就直接依赖库。
+
+## 插件
+
+- **状态栏时钟**：登记成外壳的只显示格子（`registerStatusItem` 带 `kind: 'label'`，外壳 0.15.13 起），浏览器侧导出
+  `mountStatusLabel`，显示 `MM-dd HH:mm`，每到整分钟换字。没有窗格
+- **`time.now`**：无参数，`effect: read`。回执 `data` 的键就是排法：`yyMMddHHmm`、`yyyyMMddHHmmss`、`yyyy-MM-dd`、
+  `yyyy-MM-ddTHH:mm`，另有带 `+08:00` 的 `iso`
+- **说明书 `time`**：agent 起时间文件名先调 `time.now`，代码里用库，不用 `getHours()` 与 `toISOString()`
+
+## 构建与检查（仓根）
+
+```powershell
+pnpm install
+pnpm build          # 先构建库，再构建插件（esbuild 打包 node 侧与浏览器侧、tailwindcss 生成样式）
+pnpm check          # 各包的 typecheck、lint、vitest
+```
+
+在隔离 home 里验证与发版照说明书 `gwb-devkit`，版本号照 `gwb-release`。发版时 `packages` 写
+`["packages/utc8-time", "plugins/time"]`，库在前。

package/dist/client.js

@@ -0,0 +1,73 @@
+// src/client/index.tsx
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+// ../../packages/utc8-time/dist/index.js
+var UTC8_OFFSET_MS = 8 * 60 * 60 * 1e3;
+function utc8PartsOf(at) {
+  const ms = at.getTime();
+  if (Number.isNaN(ms))
+    throw new Error("utc8PartsOf \u6536\u5230\u7684\u662F\u65E0\u6548\u7684 Date\uFF08getTime() \u662F NaN\uFF09");
+  const shifted = new Date(ms + UTC8_OFFSET_MS);
+  return {
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+    hour: shifted.getUTCHours(),
+    minute: shifted.getUTCMinutes(),
+    second: shifted.getUTCSeconds(),
+    weekday: (shifted.getUTCDay() + 6) % 7
+  };
+}
+var pad = (value, width) => String(value).padStart(width, "0");
+var TOKEN = /yyyy|yy|MM|dd|HH|mm|ss/g;
+function formatUtc8(at, pattern) {
+  const parts = utc8PartsOf(at);
+  return pattern.replace(TOKEN, (token) => {
+    switch (token) {
+      case "yyyy":
+        return pad(parts.year, 4);
+      case "yy":
+        return pad(parts.year % 100, 2);
+      case "MM":
+        return pad(parts.month, 2);
+      case "dd":
+        return pad(parts.day, 2);
+      case "HH":
+        return pad(parts.hour, 2);
+      case "mm":
+        return pad(parts.minute, 2);
+      default:
+        return pad(parts.second, 2);
+    }
+  });
+}
+
+// src/client/next-minute.ts
+function msUntilNextMinute(at) {
+  return 6e4 - at.getTime() % 6e4;
+}
+
+// src/client/index.tsx
+import { jsx } from "react/jsx-runtime";
+function Utc8Clock() {
+  const [now, setNow] = useState(() => /* @__PURE__ */ new Date());
+  useEffect(() => {
+    const timer = setTimeout(() => setNow(/* @__PURE__ */ new Date()), msUntilNextMinute(now));
+    return () => clearTimeout(timer);
+  }, [now]);
+  return /* @__PURE__ */ jsx("span", { className: "time:font-mono time:tabular-nums", children: formatUtc8(now, "MM-dd HH:mm") });
+}
+function mountStatusLabel(_args, container) {
+  const root = createRoot(container);
+  root.render(/* @__PURE__ */ jsx(Utc8Clock, {}));
+  return {
+    dispose() {
+      root.unmount();
+      container.textContent = "";
+    }
+  };
+}
+export {
+  mountStatusLabel
+};

package/dist/index.js

@@ -0,0 +1,94 @@
+import { createRequire as __createRequire } from "node:module";
+const require = __createRequire(import.meta.url);
+
+// ../../packages/utc8-time/dist/index.js
+var UTC8_OFFSET_MS = 8 * 60 * 60 * 1e3;
+function utc8PartsOf(at) {
+  const ms = at.getTime();
+  if (Number.isNaN(ms))
+    throw new Error("utc8PartsOf \u6536\u5230\u7684\u662F\u65E0\u6548\u7684 Date\uFF08getTime() \u662F NaN\uFF09");
+  const shifted = new Date(ms + UTC8_OFFSET_MS);
+  return {
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+    hour: shifted.getUTCHours(),
+    minute: shifted.getUTCMinutes(),
+    second: shifted.getUTCSeconds(),
+    weekday: (shifted.getUTCDay() + 6) % 7
+  };
+}
+var pad = (value, width) => String(value).padStart(width, "0");
+var TOKEN = /yyyy|yy|MM|dd|HH|mm|ss/g;
+function formatUtc8(at, pattern) {
+  const parts = utc8PartsOf(at);
+  return pattern.replace(TOKEN, (token) => {
+    switch (token) {
+      case "yyyy":
+        return pad(parts.year, 4);
+      case "yy":
+        return pad(parts.year % 100, 2);
+      case "MM":
+        return pad(parts.month, 2);
+      case "dd":
+        return pad(parts.day, 2);
+      case "HH":
+        return pad(parts.hour, 2);
+      case "mm":
+        return pad(parts.minute, 2);
+      default:
+        return pad(parts.second, 2);
+    }
+  });
+}
+function utc8Iso(at) {
+  return `${formatUtc8(at, "yyyy-MM-ddTHH:mm:ss")}+08:00`;
+}
+
+// src/now.ts
+function utc8NowReply(at) {
+  return {
+    yyMMddHHmm: formatUtc8(at, "yyMMddHHmm"),
+    yyyyMMddHHmmss: formatUtc8(at, "yyyyMMddHHmmss"),
+    "yyyy-MM-dd": formatUtc8(at, "yyyy-MM-dd"),
+    "yyyy-MM-ddTHH:mm": formatUtc8(at, "yyyy-MM-ddTHH:mm"),
+    iso: utc8Iso(at)
+  };
+}
+
+// src/index.ts
+var name = "gwb-time";
+var CLIENT_URL = new URL("./client.js", import.meta.url).href;
+var STYLE_URL = new URL("./style.css", import.meta.url).href;
+var SKILLS_DIR = new URL("../skills/", import.meta.url);
+var inject = ["gwbCommands", "gwbShell"];
+function apply(ctx) {
+  const commands = ctx.gwbCommands;
+  if (commands === void 0) throw new Error("ctx.gwbCommands \u4E0D\u5728\uFF1Ainject \u91CC\u5199\u4E86\u5B83\uFF0Ccordis \u672C\u4E0D\u8BE5\u8C03\u7528 apply");
+  ctx.gwbShell.describeSelf({ title: "\u4E1C\u516B\u533A\u65F6\u95F4", icon: "clock" });
+  ctx.gwbShell.registerStatusItem({
+    id: "clock",
+    title: "\u4E1C\u516B\u533A\u65F6\u95F4\uFF08UTC+8\uFF09\uFF0C\u4E0D\u8DDF\u672C\u673A\u65F6\u533A\u8D70",
+    icon: "clock",
+    kind: "label",
+    client: CLIENT_URL,
+    style: STYLE_URL
+  });
+  commands.register(
+    {
+      name: "time.now",
+      description: "\u4E1C\u516B\u533A\uFF08UTC+8\uFF09\u73B0\u5728\u7684\u65F6\u95F4\uFF0C\u6392\u6210\u8D77\u6587\u4EF6\u540D\u3001\u76EE\u5F55\u540D\u3001id \u5E38\u7528\u7684\u51E0\u79CD\u5199\u6CD5\uFF1B\u4E0D\u8DDF\u672C\u673A\u65F6\u533A\u8D70",
+      usage: "\u65E0\u53C2\u6570\u3002data \u7684\u952E\u5C31\u662F\u6392\u6CD5\uFF1AyyMMddHHmm\uFF08\u5982 2610181128\uFF0Cprobes \u76EE\u5F55\u540D\u7528\u5B83\uFF09\u3001yyyyMMddHHmmss\u3001yyyy-MM-dd\u3001yyyy-MM-ddTHH:mm\uFF08\u8F68\u8FF9\u5361 born-at \u7528\u5B83\uFF09\uFF0Ciso \u662F\u5E26 +08:00 \u7684 ISO 8601\uFF08\u5230\u79D2\uFF09",
+      effect: "read"
+    },
+    async () => ({ ok: true, data: utc8NowReply(/* @__PURE__ */ new Date()) })
+  );
+  ctx.inject(["gwbSkills"], (c) => {
+    c.effect(() => c.gwbSkills.register(SKILLS_DIR));
+  });
+}
+export {
+  apply,
+  inject,
+  name
+};

package/dist/style.css

@@ -0,0 +1,143 @@
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties;
+@layer utilities {
+  .time\:font-mono {
+    font-family: var(--gwb-font-mono);
+  }
+  .time\:tabular-nums {
+    --tw-numeric-spacing: tabular-nums;
+    font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) var(--tw-numeric-figure,) var(--tw-numeric-spacing,) var(--tw-numeric-fraction,);
+  }
+}
+@property --tw-animation-delay {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0s;
+}
+@property --tw-animation-direction {
+  syntax: "*";
+  inherits: false;
+  initial-value: normal;
+}
+@property --tw-animation-duration {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-animation-fill-mode {
+  syntax: "*";
+  inherits: false;
+  initial-value: none;
+}
+@property --tw-animation-iteration-count {
+  syntax: "*";
+  inherits: false;
+  initial-value: 1;
+}
+@property --tw-enter-blur {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-enter-opacity {
+  syntax: "*";
+  inherits: false;
+  initial-value: 1;
+}
+@property --tw-enter-rotate {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-enter-scale {
+  syntax: "*";
+  inherits: false;
+  initial-value: 1;
+}
+@property --tw-enter-translate-x {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-enter-translate-y {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-exit-blur {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-exit-opacity {
+  syntax: "*";
+  inherits: false;
+  initial-value: 1;
+}
+@property --tw-exit-rotate {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-exit-scale {
+  syntax: "*";
+  inherits: false;
+  initial-value: 1;
+}
+@property --tw-exit-translate-x {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-exit-translate-y {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-ordinal {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-slashed-zero {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-numeric-figure {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-numeric-spacing {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-numeric-fraction {
+  syntax: "*";
+  inherits: false;
+}
+@layer properties {
+  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+    *, ::before, ::after, ::backdrop {
+      --tw-ordinal: initial;
+      --tw-slashed-zero: initial;
+      --tw-numeric-figure: initial;
+      --tw-numeric-spacing: initial;
+      --tw-numeric-fraction: initial;
+      --tw-animation-delay: 0s;
+      --tw-animation-direction: normal;
+      --tw-animation-duration: initial;
+      --tw-animation-fill-mode: none;
+      --tw-animation-iteration-count: 1;
+      --tw-enter-blur: 0;
+      --tw-enter-opacity: 1;
+      --tw-enter-rotate: 0;
+      --tw-enter-scale: 1;
+      --tw-enter-translate-x: 0;
+      --tw-enter-translate-y: 0;
+      --tw-exit-blur: 0;
+      --tw-exit-opacity: 1;
+      --tw-exit-rotate: 0;
+      --tw-exit-scale: 1;
+      --tw-exit-translate-x: 0;
+      --tw-exit-translate-y: 0;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@godcreator/gwb-time",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "东八区时间：状态栏右侧显示东八区（UTC+8）的月日时分，命令 time.now 回起文件名常用的几种东八区时间写法，都不跟本机时区走；随包说明书 time 讲 agent 起时间文件名的规矩",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE"
+  ],
+  "keywords": [
+    "gwb-plugin"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@godcreator/gwb-commands": "^0.6.2",
+    "@godcreator/gwb-kernel-desktop": "^0.10.2",
+    "@godcreator/gwb-shell": "^0.15.13",
+    "@godcreator/gwb-skills": "^0.4.14"
+  },
+  "peerDependenciesMeta": {
+    "@godcreator/gwb-skills": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/godcreator02/gwb-time.git"
+  }
 }

package/skills/time/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: time
+description: 要用时间起文件名、目录名、id（probes 目录、轨迹卡日期与 born-at、反馈文件、记录 id 这类），或要知道东八区现在几点时读。这些时间一律用东八区（UTC+8），不用本机时区：用户常在亚洲与美国之间往返，本机时区会跟着变。
+---
+
+# 东八区时间
+
+用户常在亚洲与美国之间往返，电脑的时区跟着切换。**写进文件名、目录名、id、frontmatter 的时间一律用东八区（UTC+8）**，
+这样同一时刻起的名字不管人在哪儿都一样，按名字排序也就是按时间排序。
+
+## agent 起名字
+
+先调 `time.now`（无参数），从回执里取对应的那一种写法，不在 shell 里用 `Get-Date`、`date` 取本机时间：
+
+| 回执的键 | 例子 | 用在哪 |
+| --- | --- | --- |
+| `yyMMddHHmm` | `2610181128` | probes 目录名、反馈文件名里的时间戳 |
+| `yyyyMMddHHmmss` | `20261018112805` | 要到秒的 id |
+| `yyyy-MM-dd` | `2026-10-18` | 轨迹卡文件名的日期、按天分的文件 |
+| `yyyy-MM-ddTHH:mm` | `2026-10-18T11:28` | 轨迹卡的 `born-at` |
+| `iso` | `2026-10-18T11:28:05+08:00` | 要写明时区的地方 |
+
+工作台没启动、调不了命令时，用 pwsh 现算：`[DateTimeOffset]::UtcNow.ToOffset([TimeSpan]::FromHours(8)).ToString('yyMMddHHmm')`。
+
+## 代码里取东八区时间
+
+用包 `@godcreator/utc8-time`（零依赖，node 与浏览器都能用），不用 `getHours()` 这类读本机时区的方法，也不用 `toISOString()`（那是 UTC）：
+
+```ts
+import { formatUtc8, utc8Iso, utc8PartsOf } from '@godcreator/utc8-time'
+
+formatUtc8(new Date(), 'yyMMddHHmm') // 占位符 yyyy yy MM dd HH mm ss，其余字符原样保留
+utc8Iso(new Date()) // 2026-10-18T11:28:05+08:00
+utc8PartsOf(new Date()) // { year, month, day, hour, minute, second, weekday }，weekday 0 = 周一
+```
+
+## 状态栏
+
+插件在状态栏右侧显示东八区的月日时分（`10-18 11:28`），悬停提示写明是东八区。