@wwkit/harness 1.0.4 → 1.0.5

package/README.md

@@ -27,7 +27,7 @@ pnpm install
 
 ```bash
 cd ~/.config/opencode
-npm install harness
+npm install @wwkit/harness
 ```
 
 ## 引入方式
@@ -37,7 +37,7 @@ npm install harness
 | 方式 | 配置 | 提供内容 | 适用 |
 |------|------|---------|------|
 | **A. 插件模式（仅技能）** | 在 `~/.config/opencode/opencode.jsonc` 注册插件 | 仅 `extract`/`revise` **技能** | 只需要技能能力 |
-| **B. 环境变量模式（完整，推荐）** | 设置 `OPENCODE_CONFIG_DIR` 指向包目录 | **代理 + 技能**（原生扫描 `agents/`、`skills/`） | 需要代理完整能力 |
+| **B. 环境变量模式（完整，推荐）** | 设置 `OPENCODE_CONFIG_DIR` 指向包目录 | **代理 + 技能 + 命令**（原生扫描 `agents/`、`skills/`、`commands/`） | 需要完整能力 |
 
 ### 方式 A：插件模式（仅技能）
 
@@ -45,23 +45,23 @@ npm install harness
 
 ```jsonc
 {
-  "plugin": ["node_modules/harness"]
+  "plugin": ["node_modules/@wwkit/harness"]
 }
 ```
 
-该模式仅注册技能（`extract`/`revise`）。opencode 不支持通过插件注册代理（`agents.paths` 字段不存在），因此**方式 A 不含代理**。
+该模式仅注册技能（`extract`/`revise`）。opencode 不支持通过插件注册代理或命令（`agents.paths`/`commands.paths` 字段不存在），因此**方式 A 不含代理与命令**。
 
 ### 方式 B：环境变量模式（完整，推荐）
 
-将 `OPENCODE_CONFIG_DIR` 指向包的安装目录，opencode 会把它当作配置目录，原生发现其中的 `agents/`、`skills/`：
+将 `OPENCODE_CONFIG_DIR` 指向包的安装目录，opencode 会把它当作配置目录，原生发现其中的 `agents/`、`skills/`、`commands/`：
 
 ```bash
-echo 'export OPENCODE_CONFIG_DIR="$HOME/.config/opencode/node_modules/harness"' >> ~/.zshrc
+echo 'export OPENCODE_CONFIG_DIR="$HOME/.config/opencode/node_modules/@wwkit/harness"' >> ~/.zshrc
 ```
 
 说明：
 - 需在**启动 opencode 前**设置环境变量；
-- 与用户原有配置目录是**叠加**关系，不覆盖已有代理/技能；
+- 与用户原有配置目录是**叠加**关系，不覆盖已有代理/技能/命令；
 - 该变量为**单一路径**，同时只能指向一个目录；
 - 若之前注册过插件（方式 A），改用方式 B 时请移除 `opencode.jsonc` 中的 `plugin` 项，避免技能重复扫描。
 
@@ -82,6 +82,12 @@ echo 'export OPENCODE_CONFIG_DIR="$HOME/.config/opencode/node_modules/harness"'
 | `extract` | 按 format（list/detail/text/navi）从 HTML/文本/JSON 提取内容 |
 | `revise` | 按 format（question/status/gallery/article）二次创作内容 |
 
+### Commands（命令）
+
+| Command | 作用 |
+|---------|------|
+| `/tl` | 中英互译：中文→英文附关键词解析（Keywords & Phrases），英文→中文 |
+
 ## 使用方式
 
 ```bash
@@ -99,3 +105,24 @@ opencode run --agent query '{"prompt": "写一篇关于AI的文章"}'
 ```
 
 未提供 `output` 时，结果直接输出到 stdout。
+
+## 使用命令（Commands）
+
+命令由 opencode 原生加载（需方式 B：`OPENCODE_CONFIG_DIR` 指向本包），在 TUI 内输入命令名即可调用：
+
+```text
+/tl <要翻译的文本>   # 中英互译；中文→英文附关键词解析，英文→中文
+```
+
+## 用本包配置启动 opencode（pnpm 脚本）
+
+在包目录 `packages/harness` 下执行 pnpm 脚本 `opencode`，它会先设置 `OPENCODE_CONFIG_DIR` 为本包目录，再启动 opencode（从而加载本包的技能/代理/命令）：
+
+```bash
+pnpm run opencode                     # 在当前工作目录启动
+pnpm run opencode -- /path/to/project # 指定 cwd：以该目录为项目目录启动
+```
+
+- `opencode` 脚本定义：`"opencode": "OPENCODE_CONFIG_DIR=$(pwd) opencode"`；
+- 不带参数时 `opencode` 以当前工作目录启动；带参数时以参数目录为项目目录启动（opencode 位置参数即项目目录）；
+- 在 monorepo 根目录可用 `pnpm --filter harness run opencode`，或 `pnpm --dir packages/harness run opencode`。

package/commands/tl.md

@@ -0,0 +1,11 @@
+---
+description: 中英互译（中文→英文附关键词解析；英文→中文）
+model: openrouter/openrouter/free
+---
+
+Translate $ARGUMENTS directly. No questions, no preamble, no tools, no extra remarks.
+
+- Chinese → English: **Translation**（英文译文）+ **Keywords & Phrases**（从译文中挑关键词，附中文释义/例句）
+- English → Chinese: **翻译**（中文译文）
+
+Style: 通俗口语。专业术语保留英文（prompt/token/agent…），代码与命令原样不译。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/harness",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "author": "bluesliu <langcai163@163.com>",
   "description": "WebWork abilities for opencode",
   "type": "module",
@@ -9,6 +9,7 @@
     "plugin.js",
     "skills",
     "agents",
+    "commands",
     "readme"
   ],
   "jest": {
@@ -37,12 +38,12 @@
     "access": "public"
   },
   "dependencies": {
+    "@opencode-ai/plugin": "1.18.27",
     "ajv": "^8.17.0",
     "cheerio": "^1.0.0",
     "json5": "^2.2.3"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.18.18",
     "jest": "^29.7.0"
   },
   "scripts": {
@@ -50,6 +51,7 @@
     "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
     "e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache",
     "e2e:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/e2e",
-    "release": "pnpm version patch && pnpm publish"
+    "release": "pnpm version patch && pnpm publish",
+    "opencode": "OPENCODE_CONFIG_DIR=$(pwd) opencode"
   }
 }

package/readme/development.md

@@ -20,6 +20,8 @@ plugin.js                 # 包入口（"main"），仅把 skills/ 注册进 con
 agents/*.md               # 主代理（extract / revise / query），frontmatter 含权限块
 skills/<name>/SKILL.md    # 技能定义
 skills/<name>/references/ # 工作流：*.md（LLM 指令）、*.js（ESM 辅助脚本）、*.json5（schema）
+commands/*.md             # opencode 命令（/tl 翻译）
+package.json              # scripts.opencode：pnpm run opencode 启动（设置 OPENCODE_CONFIG_DIR）
 tests/unit/               # 单元测试（ESM）
 tests/e2e/                # E2E 测试（CommonJS，真实调用 opencode run）
 readme/                   # 分模块文档（发布 / 测试 / 开发）
@@ -28,8 +30,8 @@ readme/                   # 分模块文档（发布 / 测试 / 开发）
 ## 约定
 
 - 开发与改动约定的权威说明见 `AGENTS.md`（文件格式 ESM/CJS 边界、技能工作流、schema 校验、无网络等约束）。
-- 两种引入方式：**插件模式**仅注册技能（`plugin.js` 经 `config.skills.paths`）；**环境变量模式**（`OPENCODE_CONFIG_DIR` 指向包目录）原生发现代理与技能。两者二选一，避免技能重复扫描。
-- 新增技能只需在 `skills/` 添加目录，新增代理只需在 `agents/` 添加 `.md` 文件，均无需改 `plugin.js`。
+- 两种引入方式：**插件模式**仅注册技能（`plugin.js` 经 `config.skills.paths`）；**环境变量模式**（`OPENCODE_CONFIG_DIR` 指向包目录）原生发现代理、技能与命令。两者二选一，避免技能重复扫描。
+- 新增技能只需在 `skills/` 添加目录，新增代理只需在 `agents/` 添加 `.md` 文件，新增命令只需在 `commands/` 添加 `.md` 文件，均无需改 `plugin.js`。
 - 新增 `revise`/`extract` 的 format 需同时提供 `<format>.md` 与 `<format>.schema.json5`（schema 为数组，`minItems: 1`）。
 
 ## 测试

package/readme/publish.md

@@ -1,6 +1,6 @@
 # 发布 npm 包
 
-发布配置已就绪：`package.json` 的 `files` 白名单（仅发布 `plugin.js`、`skills/`、`agents/`）、`prepublishOnly`（发布前自动跑单元测试）、`publishConfig.registry`（发布强制官方源，安装仍走国内镜像）。
+发布配置已就绪：`package.json` 的 `files` 白名单（仅发布 `plugin.js`、`skills/`、`agents/`、`commands/`、`readme/`）、`prepublishOnly`（发布前自动跑单元测试）、`publishConfig.registry` + `access: public`（发布强制官方源、公开 scoped 包，安装仍走国内镜像）。
 
 发布需在包目录 `packages/harness` 下执行 pnpm 命令：
 
@@ -23,15 +23,18 @@ pnpm publish
 
 # 5. 验证
 #    默认走仓库 .npmrc 的国内镜像（同步快，一般即可确认）
-npm view harness version dist-tags.latest
+npm view @wwkit/harness version dist-tags.latest
 #    显式指定官方源确认发布成功
-npm view harness version dist-tags.latest --registry=https://registry.npmjs.org/
+npm view @wwkit/harness version dist-tags.latest --registry=https://registry.npmjs.org/
 #    查看已发布的所有版本
-npm view harness versions
+npm view @wwkit/harness versions
 ```
 
 ## 注意事项
 
+- 包名 `@wwkit/harness` 为 scoped 包，首次发布需 `publishConfig.access: public`（已配置），否则 npm 会当作私有包要求付费。
+- 需先在 npmjs.org 注册 `wwkit` 组织（org），并把发布账号（如 `langcai`）加入其中，否则推送 `@wwkit/...` 会报 `Scope not found`。
+
 - token 只写入 `~/.npmrc`（用户级），不要写进仓库的 `.npmrc` 或提交到 git。
 - 仓库 `.npmrc` 指向国内镜像（淘宝 npmmirror），只影响安装；发布由 `publishConfig.registry` 强制走官方源。
 - 包名在官方源首次发布前需未被占用；之后每次发布必须先 `pnpm version` 升版本（npm 不允许重复发布相同版本）。