@namewta/skills-hub 0.0.7 → 0.1.0

package/README.md

@@ -9,12 +9,22 @@
 需要 Node.js 22.14+。npm 包名为 `@namewta/skills-hub`，命令名为 `skills-hub`。可直接通过 npm 使用，无需预先克隆：
 
 ```bash
-npx @namewta/skills-hub@0.0.7 list
-npx @namewta/skills-hub@0.0.7 install --domain dev
-npx @namewta/skills-hub@0.0.7 install --skill dev-grill dev-spec system-proxy
+# 直接交互多选领域或技能
+npx @namewta/skills-hub@0.1.0
+
+# 或全局安装后运行
+npm install -g @namewta/skills-hub@0.1.0
+skills-hub
+
+# 原有命令行安装方式继续保留
+npx @namewta/skills-hub@0.1.0 list
+npx @namewta/skills-hub@0.1.0 install --domain dev
+npx @namewta/skills-hub@0.1.0 install --skill dev-grill dev-spec system-proxy
 ```
 
-在目标项目根目录执行，按领域或技能选择；npm 下载包不会自动安装技能。也可以克隆源码后离线运行安装器：
+在目标项目根目录执行，按领域或技能选择；npm 下载包不会自动安装技能。终端中不带参数运行 `skills-hub` 或 `skills-hub install` 会进入中文交互：空格多选，回车确认，Ctrl+C 取消。支持 `skills-hub install --dry-run` 交互预览；内容冲突需检查后显式运行 `skills-hub install --replace`，不会自动覆盖。非交互环境继续要求明确参数，不会等待输入。
+
+交互界面使用 `@clack/prompts`、`picocolors`、`string-width` 和 `wrap-ansi`；npm 自动安装这些依赖。源码的显式参数安装器仍仅依赖 Node.js 标准库、可离线运行；源码交互模式先运行 `npm ci`。也可以克隆源码后离线运行安装器：
 
 ```bash
 git clone https://github.com/NAMEWTA/skills-hub.git
@@ -54,7 +64,7 @@ node C:\tools\skills-hub\install.mjs install --domain dev
 
 ### 从 skills-wta 迁移
 
-从旧包 `skills-wta@0.0.1` 切换到 `@namewta/skills-hub@0.0.7`，继续在同一项目运行上面的安装命令。新旧版本使用相同的 `.agents/skills/<技能名>/`，技能内容相同则不变，有差异时先检查再用 `--replace`；新的开发记录写入 `.agents/dev/`，系统维护记录写入 `.agents/system/`；已有项目记录按迁移说明处理，安装器不会自动搬迁。新版补齐 `.agents/skills-hub-licenses/`，新备份使用 `.agents/.skills-hub-backups/`；旧许可和备份保留。旧 GitHub 标签 `v0.0.1` 保留为原包历史；本次 scoped 包根据先前的 0.0.2 准备版本基于现有 npm `0.0.6` 递增发布 `0.0.7`，使用 `v0.0.7` 标签，不覆盖历史版本。详见[迁移说明](docs/installation.md#从-skills-wta-迁移)。
+从旧包 `skills-wta@0.0.1` 切换到 `@namewta/skills-hub@0.0.8`，继续在同一项目运行上面的安装命令。新旧版本使用相同的 `.agents/skills/<技能名>/`，技能内容相同则不变，有差异时先检查再用 `--replace`；新的开发记录写入 `.agents/dev/`，系统维护记录写入 `.agents/system/`；已有项目记录按迁移说明处理，安装器不会自动搬迁。新版补齐 `.agents/skills-hub-licenses/`，新备份使用 `.agents/.skills-hub-backups/`；旧许可和备份保留。旧 GitHub 标签 `v0.0.1` 保留为原包历史；本次从已发布的 scoped npm `0.0.7` 递增 `+0.0.1` 发布 `0.0.8`，使用 `v0.0.8` 标签，不覆盖历史版本。详见[迁移说明](docs/installation.md#从-skills-wta-迁移)。
 
 ## dev：完整开发流程
 
@@ -134,6 +144,7 @@ node C:\tools\skills-hub\install.mjs install --domain dev
 | [system-cleanup](skills/system/system-cleanup/SKILL.md) | 按实际占用选择可清理对象，执行后量测并验证 |
 | [system-proxy](skills/system/system-proxy/SKILL.md) | 排查和配置代理、DNS、客户端与应用生效范围 |
 | [system-config](skills/system/system-config/SKILL.md) | 调整已指定的软件或系统配置，保留备份并验证真实生效 |
+| [system-herdr](skills/system/system-herdr/SKILL.md) | 在 Herdr 内查看与控制窗格、标签页、工作区、命令及 agent；仅在用户明确要求使用 Herdr 时启用 |
 
 系统技能不会把“清缓存”扩展为删除业务数据，也不会把“应用代理”扩展为修改整机路由。主机文档按需放在 `.agents/system/<主机标识>/`；密码与订阅秘密只记录安全引用。
 
@@ -206,6 +217,8 @@ node scripts/install-hooks.mjs
 | D · 3 份 | [Elaya AI Design Skills](https://github.com/elayadesign/ai-design-skills/tree/456d9e0d3e2d84c748bb143c6ca3d90c45e16213)，完整落地页、Figma 设计技能与说明 | `456d9e0d3e2d84c748bb143c6ca3d90c45e16213` | [D 组索引](materials/README.md#d-组) |
 | E · 8 份、F · 19 份 | [Speculo](https://github.com/NAMEWTA/Speculo/tree/9199c3bd0cf983c131efbc6340e44ac8b83a583d)，所参考的知识、部署及系统维护资料；仅按需融合，未移植状态引擎 | `9199c3bd0cf983c131efbc6340e44ac8b83a583d` | [E 组索引](materials/README.md#e-组)、[F 组索引](materials/README.md#f-组) |
 
+G 组新增 [Herdr 上游技能](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md)，固定提交 `ee5bfb5041bb3e4a49d591c72308aae3c81ecdde`，固定文件见[该修订原文](https://github.com/herdrdev/herdr/blob/ee5bfb5041bb3e4a49d591c72308aae3c81ecdde/skills/herdr/SKILL.md)，完整原件与中文译文见 [G 组索引](materials/README.md#g-组)。`system-herdr` 直接复制自本地 `/home/wta/projects/huhu/.agents/skills/herdr/SKILL.md`，仅更名并添加修改说明；保留本地追加的 Claude Code、Codex、Pi 启动示例，不将这些示例冒称上游内容。逐文件 Git blob、摘要及适配关系见清单 `g001`。Herdr 在运行内容中作为实际操作工具名称保留，不作为来源署名或外部文档依赖。
+
 感谢这些内容的作者与贡献者。PR 视觉说明方法还通过上述资料引用了 [Dex Horthy](https://github.com/dexhorthy) 与 [HumanLayer show-me](https://github.com/humanlayer/humanlayer) 的贡献，对应 Apache 2.0 与 NOTICE 已一并附带。B 组完整镜像所固定的 `pstack/` 目录，逐文件与该提交的目录树核对，无遗漏；其余组按表中范围收录。运行包按主题整合为独立中文技能，原品牌图片、原插件配置、自动联网安装器和复杂计划准入工具仅保留作对照，不成为使用条件。
 
 技能组织方式还参考 [Rethinking skills and prompts for GPT-6 Astra](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra) 与 [Harness engineering](https://openai.com/index/harness-engineering/)。文章的组织原则已转化为本项目的本地编写与知识管理说明；未转载文章全文。代理配置字段的理解另参考 [MetaCubeX 文档](https://github.com/MetaCubeX/Meta-Docs/tree/2a6ba6b04a9eecdbe5c88c4e4a09776659c0878b)，运行说明已写在技能本地，不要求使用者访问该文档。

package/THIRD_PARTY_NOTICES.md

@@ -5,6 +5,7 @@
 | 权利人 | 许可原文 | 本项目使用范围 |
 | --- | --- | --- |
 | NAMEWTA | [项目 MIT](licenses/PROJECT-LICENSE.txt) | 本项目原创说明、整合与程序 |
+| Herdr 贡献者 | [Apache 2.0](licenses/herdr-Apache-2.0.txt) | Herdr 技能完整原件、中文译文与 `system-herdr` 运行适配；已更名并保留本地追加的启动示例 |
 | Copyright (c) 2026 DeepSeek | [MIT](licenses/deepseek-harness-MIT.txt) | 知识、归档、写作方法与笔记实例的中文译文及适配 |
 | Copyright (c) 2026 Matt Pocock | [MIT](licenses/mattpocock-skills-MIT.txt) | 需求、架构、实施、诊断、审查与写作资料的中文译文及适配 |
 | Copyright (c) 2026 Lauren Tan | [MIT](licenses/pstack-MIT.txt) | 限 pstack 目录内的方法、操作规程与实例 |
@@ -15,6 +16,8 @@
 
 来源项目、固定修订和贡献者致谢集中见 [README](README.md#致谢与许可)。所有纳入对照的文件可在 [本地资料索引](materials/README.md) 中找到，原件与中文底稿均保留，不需要访问来源仓库才能核对。
 
+Herdr 许可原文固定于提交 `ee5bfb5041bb3e4a49d591c72308aae3c81ecdde` 的根目录 `LICENSE`，Git blob 为 `261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64`；该修订无上游 `NOTICE` 文件。本次仅收录技能文档，不收录其程序或 vendor 组件。
+
 许可原文保持原语言和原始版权声明，中文技能正文不能替代法律原文。对照资料中保留的署名和链接属于历史原件内容，不是运行时外部依赖。
 
 仅参考写作或技术原理、未取得全文转载许可的文章不作全文转载。本项目提供自己的本地说明；来源致谢不表示取得来源仓库未授权目录的复制许可。

package/cli.mjs

@@ -0,0 +1,56 @@
+import * as prompts from '@clack/prompts';
+import pc from 'picocolors';
+import stringWidth from 'string-width';
+import wrapAnsi from 'wrap-ansi';
+import { createInstaller, select, main } from './install.mjs';
+
+export function formatSummary(names, columns = process.stdout.columns ?? 80) {
+  const width = Math.max(20, Math.min(columns - 8, 100));
+  const label = '已选择';
+  return wrapAnsi(`${pc.bold(label)}${' '.repeat(Math.max(1, 8 - stringWidth(label)))}${names.join('、')}`, width, { hard: true });
+}
+
+export async function interactive({ argv = [], project = process.cwd(), ui = prompts } = {}) {
+  if (argv.some(value => !['install', '--replace', '--dry-run'].includes(value))) {
+    throw new Error('交互安装只接受 install、--replace 和 --dry-run。');
+  }
+  const ask = async promise => {
+    const value = await promise;
+    if (ui.isCancel(value)) { ui.cancel('已取消，未修改文件。'); throw new Cancelled(); }
+    return value;
+  };
+  try {
+    ui.intro(pc.cyan('skills-hub · 按需安装中文技能'));
+    ui.note(project, '目标项目（技能写入 .agents/skills/）');
+    const skills = createInstaller().catalog();
+    const mode = await ask(ui.select({ message: '如何选择？', options: [
+      { value: 'domain', label: '按领域安装' },
+      { value: 'skill', label: '选择特定技能' },
+      { value: 'all', label: '安装全部技能' },
+    ] }));
+    let domains = [], names = [];
+    if (mode === 'domain') domains = await ask(ui.multiselect({ message: '选择领域（空格勾选，回车继续）', required: true,
+      options: [...new Set(skills.map(skill => skill.domain))].map(domain => ({ value: domain, label: domain, hint: `${skills.filter(skill => skill.domain === domain).length} 个技能` })) }));
+    if (mode === 'skill') names = await ask(ui.multiselect({ message: '选择技能（空格勾选，回车继续）', required: true,
+      options: skills.map(skill => ({ value: skill.name, label: skill.name, hint: skill.domain })) }));
+    const selected = select(skills, domains, names, mode === 'all');
+    ui.note(formatSummary(selected.map(skill => skill.name)), `${selected.length} 个技能`);
+    const dryRun = argv.includes('--dry-run');
+    if (!await ask(ui.confirm({ message: dryRun ? '检查安装计划？（不写入文件）' : '安装以上技能？', initialValue: true }))) {
+      ui.cancel('已取消，未修改文件。'); return 0;
+    }
+    const command = ['install', '--skill', ...selected.map(skill => skill.name)];
+    if (argv.includes('--replace')) command.push('--replace');
+    if (dryRun) command.push('--dry-run');
+    const spinner = ui.spinner();
+    const output = [];
+    spinner.start(dryRun ? '正在检查计划' : '正在安装');
+    let code;
+    try { code = main(command, { project, stdout: line => output.push(line), stderr: line => output.push(pc.red(line)) }); }
+    finally { spinner.stop('检查与文件操作结束'); }
+    ui.note(output.join('\n'), '结果');
+    ui.outro(code === 0 ? pc.green(dryRun ? '预览完成，未写入文件。' : '安装完成。') : pc.red('安装失败；请检查以上错误，内容冲突需核对后显式使用 --replace。'));
+    return code;
+  } catch (error) { if (error instanceof Cancelled) return 0; throw error; }
+}
+class Cancelled extends Error {}

package/install.mjs

@@ -9,7 +9,7 @@ export const licenseBundleFiles = Object.freeze([
   'PROJECT-LICENSE.txt', 'THIRD_PARTY_NOTICES.txt', 'deepseek-harness-MIT.txt',
   'mattpocock-skills-MIT.txt', 'pstack-MIT.txt', 'ai-design-skills-MIT.txt',
   'Speculo-MIT.txt', 'taste-skill-MIT.txt', 'humanlayer-Apache-2.0.txt',
-  'humanlayer-NOTICE.txt',
+  'humanlayer-NOTICE.txt', 'herdr-Apache-2.0.txt',
 ]);
 const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
@@ -293,4 +293,11 @@ export function main(argv = process.argv.slice(2), { repository = repositoryRoot
   } catch (error) { stderr(`Error: ${error.message}`); return 1; }
 }
 
-if (isMain(import.meta.url)) process.exitCode = main();
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const interactiveRequest = argv.length === 0 || (argv[0] === 'install' && argv.slice(1).every(value => ['--replace', '--dry-run'].includes(value)));
+  if (interactiveRequest && process.stdin.isTTY && process.stdout.isTTY) {
+    try { process.exitCode = await (await import('./cli.mjs')).interactive({ argv }); }
+    catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; }
+  } else process.exitCode = main(argv);
+}

package/licenses/herdr-Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/skills-hub",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "独立中文 Agent Skills：按领域安装，覆盖开发交付、项目知识与系统维护。",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "install.mjs",
+    "cli.mjs",
     "skills/",
     "licenses/",
     "LICENSE",
@@ -46,5 +47,11 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "picocolors": "1.1.1",
+    "string-width": "8.3.0",
+    "wrap-ansi": "10.0.2"
   }
 }

package/skills/system/system-herdr/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: system-herdr
+description: "控制 Herdr，一个面向编程 agent 的终端多路复用器。仅当用户明确提到 Herdr，或要求使用 Herdr 查看或控制窗格、标签页、工作区、命令或其他 agent 时使用。不要仅因任务可能受益于后台终端、委派或并行工作就使用。要求 HERDR_ENV=1。"
+---
+
+# Herdr
+
+Herdr 将终端组织为工作区、标签页和窗格，识别窗格中运行的编程 agent，并通过 `herdr` CLI 提供当前会话的访问入口。
+
+执行任何控制命令前，先确认当前 agent 正在 Herdr 管理的窗格内运行：
+
+```bash
+test "${HERDR_ENV:-}" = 1
+```
+
+如果检查失败，说明当前不在 Herdr 内运行，然后停止。不要从 Herdr 外部查看或控制当前聚焦的 Herdr 会话。
+
+检查通过后，`PATH` 中的 `herdr` 程序会与当前会话通信。使用它查看相邻工作、创建终端布局、启动 agent 和命令、读取输出，以及等待状态变化。
+
+## 了解当前 CLI
+
+命令语法以已安装的程序为准。先运行：
+
+```bash
+herdr --help
+```
+
+然后运行不带子命令的相关命令组，查看其说明：
+
+```bash
+herdr agent
+herdr pane
+herdr workspace
+herdr tab
+herdr worktree
+herdr terminal
+herdr notification
+herdr integration
+herdr session
+herdr machine
+```
+
+不要用不带参数的 `herdr` 探索命令，它会启动或连接 TUI。不要通过省略参数来试探会修改状态的嵌套命令。`herdr workspace create` 等命令使用默认值也有效，会实际执行。
+
+大多数控制命令返回 JSON。从响应中读取标识符和状态，不要猜测。
+
+## 理解布局、窗格和 agent
+
+选择与任务匹配的操作对象：
+
+- 工作区、标签页和窗格的拓扑关系用于组织终端位置。
+- 窗格命令控制原始终端、shell、测试、服务、输入和输出。
+- agent 命令控制当前占用窗格、且已被识别的编程 agent。
+
+无论是否包含 agent，窗格都独立存在。`agent start` 要求已有可用的 shell 窗格，绝不会创建、拆分或移动布局。普通进程使用窗格命令。需要 Herdr 验证 agent 身份或解释 `idle`、`working`、`blocked`、`done` 和 `unknown` 生命周期状态时，使用 agent 命令。
+
+agent 命令接受唯一的在线 agent 名称，或当前承载该 agent 的窗格 ID。不接受终端 ID 或单独的 agent 类型标签。名称必须匹配 `[a-z][a-z0-9_-]{0,31}`，并且在在线 agent 中唯一。名称跟随当前窗格中的 agent，在该 agent 退出、被释放或被替换时清除。用 Ctrl+Z 挂起 agent 后运行非 agent 命令，只要原进程仍存活，其身份就会保留。如果另一个被识别的 agent 接管窗格，原身份不会继续保留。身份保留不代表 agent 位于前台，发送输入前先检查窗格。
+
+`idle` 和 `done` 通常表示 agent 可以接收输入，但都不保证 Herdr 识别出了陌生的审批对话框，也不保证身份被保留的 agent 位于前台。CLI/API 根据服务端记录的已查看状态区分二者。显式聚焦命令会将目标标为已查看，读取操作不会。每个 TUI 客户端独立记录已查看的完成结果，因此其 Done 标记可能与 CLI 或其他客户端不同。Antigravity 和 Grok 可能在后台任务或子 agent 仍运行时处于 idle，因此等待状态稳定不能证明这些任务已结束。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示 agent 存在，但 Herdr 无法可靠分类，不能据此判定已完成。
+
+## 使用 ID 和调用方上下文
+
+公开 ID 是不应解析其内部含义的稳定标识：
+
+- 工作区：`w1`
+- 标签页：`w1:t1`
+- 窗格：`w1:p1`
+
+已关闭的标签页和窗格 ID 不会复用。窗格移动到其他工作区后，会获得带有新工作区限定的新窗格 ID。执行 `pane move` 后，继续使用 `.result.move_result.pane.pane_id` 或在线 agent 名称。旧值通过 `.result.move_result.previous_pane_id` 返回。只有被移动进程继承的调用方上下文仍能解析该旧 ID，不要将它用作通用 agent 目标。
+
+Herdr 会向每个受管理的窗格注入调用方上下文：
+
+```bash
+printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
+```
+
+窗格命令应作用于调用方窗格时，优先使用 `--current`。`pane split` 省略目标时，如果存在 `HERDR_PANE_ID`，则使用调用方窗格，否则使用当前聚焦的窗格。其他命令可能使用 UI 中聚焦的窗格，而该窗格可能属于用户或其他客户端。
+
+使用以下命令查看实时状态：
+
+```bash
+herdr workspace list
+herdr tab list --workspace "$HERDR_WORKSPACE_ID"
+herdr pane current --current
+herdr pane list --workspace "$HERDR_WORKSPACE_ID"
+herdr agent list
+```
+
+创建操作的响应会提供后续应使用的 ID。`workspace create` 返回 `.result.workspace`、`.result.tab` 和 `.result.root_pane`。`tab create` 返回 `.result.tab` 和 `.result.root_pane`。`pane split` 通过 `.result.pane` 返回新窗格。
+
+ID 和在线 agent 名称的作用域限于单个服务端。两个已保存的 SSH 机器都可能有 `w1:p1` 或名为 `reviewer` 的 agent。在 TUI 中选择机器不会改变窗格内命令的目标。不带 `--machine` 时，命令仍使用继承的会话和套接字上下文。
+
+要控制已保存的 SSH 机器，在查看状态和后续每条命令中都使用相同的全局前缀：
+
+```bash
+herdr --machine <label-or-id> agent list
+herdr --machine <label-or-id> pane list
+herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000
+```
+
+选择器必须是已启用的已保存配置 ID，或区分大小写的唯一标签，不能是任意 SSH 主机名。命令使用该配置的远程会话，无需打开 TUI。不要将 `--machine` 与 `--session` 或 `--remote` 混用。先在目标机器上查询 ID，继承的本地 ID 和 `--current` 不能用于标识远程窗格。
+
+两端安装都必须支持机器 API 转发，且远程服务端必须已运行并与 API 兼容。转发绝不会安装、启动或重启服务端，也绝不会回退到本地。不会转发本地配置、会话管理、安装命令和交互式连接。远程 worktree 路径必须是绝对路径、`~` 或以 `~/` 开头，插件链接路径必须是绝对路径。连接失败不能证明修改操作未生效，重试前先检查远程状态。
+
+`herdr machine list` 列出已保存的连接配置，而不是跨机器的窗格清单。脚本中加上 `--json`。仅在用户要求时添加、删除、启用或禁用配置。删除配置会断开客户端连接，但不会停止远程会话。交互式 `machine add` 会发现正在运行的远程会话，并可能让用户选择。非交互式配置使用远程默认会话，除非显式提供 `--remote-session`。使用 `herdr machine status [<label-or-id>] --json` 诊断连接失败的机器。`herdr machine reconnect` 需要用户在自己的终端中完成 SSH 认证，不要代为运行。配置流程在停止不兼容的服务端前会询问，默认选择 No。未经用户同意，不要批准替换。实验性交接功能不属于 `machine add`。
+
+## 启动和协调 agent
+
+默认使用当前标签页中的相邻窗格和当前工作目录。除非用户明确要求相应拓扑或位置，否则不要创建工作区、标签页、worktree，也不要换用其他工作目录。
+
+遵循用户指定的拆分方向。如果未指定，先检查调用方窗格：
+
+```bash
+herdr pane layout --pane "$HERDR_PANE_ID"
+```
+
+宽窗格向右拆分，窄窗格或高窗格向下拆分。避免连续同方向拆分，造成过窄的列或过矮的行。将用户焦点保留在调用方窗格，并显式保留调用方工作目录：
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+```
+
+适当时将 `right` 替换为 `down`。从 `.result.pane.pane_id` 读取新窗格 ID。
+
+可用的 shell 窗格必须停在交互式提示符，shell 自身位于前台，且没有前台命令、编辑器或 agent 正在运行。在该窗格中启动受支持的 agent，并使用有意义的唯一名称：
+
+```bash
+herdr agent start reviewer --kind codex --pane <returned-pane-id>
+```
+
+使用用户要求的类型。运行 `herdr agent` 查看当前安装支持的类型和选项。agent 原生参数只能放在 `--` 之后：
+
+```bash
+herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
+```
+
+只有 Herdr 在同一窗格内检测到预期 agent，且认定其已准备好接收交互式输入后，`agent start` 才会成功返回。如果 agent 在启动期间受阻，命令立即返回 `agent_not_ready`，但保留名称，供 `agent read` 和 `agent send-keys` 使用。等待 agent 进入 idle 后再发送提示。启动超时默认为 30 秒。
+
+通过 agent 命令提交工作：
+
+```bash
+herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
+```
+
+`agent prompt` 遵循窗格当前的括号粘贴模式，将文本和编码后的 Enter 作为一次有序提交发送。只有两者都写入后才报告提交成功，但这本身不能证明 agent 开始了新一轮工作。对于 Windows 上的 Codex，Herdr 会在 Enter 前发送粘贴边界，使提交不依赖提示长度。如果 agent 已停在审批或提问对话框，命令会在发送任何输入前返回 `agent_blocked`。检查受阻界面，回答前先询问用户。普通 agent 工作使用 `--wait` 即可，它会等待首次稳定的 `idle`、`done` 或 `blocked` 状态。不要用 `--until` 重复这些默认值。
+
+使用 `--wait` 时，从非 working 状态发送的提示必须产生可观察的 `working` 或 `blocked` 活动。提交后，Herdr 最多等待五秒来观察此类活动，无关的 `idle`、`done` 或会话变化不能满足此条件。未观察到活动时返回 `agent_prompt_stalled`，如果调用方超时先到则返回 `timeout`。调用方超时包含提交耗时。未设置超时时，在观察到活动后会无限等待状态稳定。此等待跟踪的是生命周期状态，而不是某一轮工作。如果 agent 已在工作，当前轮完成就可能满足等待条件。
+
+仅在针对特定状态的流程中使用 `--until`，例如等待已运行的 agent 请求输入：
+
+```bash
+herdr agent wait reviewer --until blocked --timeout 120000
+```
+
+不带 `--until` 时，独立的 `agent wait` 与 `agent prompt --wait` 使用相同的默认稳定状态。
+
+使用逻辑按键控制 agent 的交互界面：
+
+```bash
+herdr agent send-keys reviewer esc
+herdr agent send-keys reviewer ctrl+c
+```
+
+Herdr 在写入任何字节前会验证全部按键。通过已解析到的 agent 读取结果：
+
+```bash
+herdr agent get reviewer
+herdr agent read reviewer --source recent-unwrapped --lines 120
+```
+
+如果等待失败或返回 `blocked`，先检查 `agent get` 和 `agent read`，再决定发送什么输入。超时或停滞响应不能证明提示未送达，不要盲目重复提交。只有确实需要原始终端控制时，才使用窗格命令。
+
+## 在其他窗格运行普通命令
+
+按相同的几何规则创建相邻窗格，保留调用方工作目录，且不改变用户焦点：
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+```
+
+从 `.result.pane.pane_id` 读取新窗格 ID，然后运行并检查命令：
+
+```bash
+herdr pane run <returned-pane-id> "just test"
+herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
+herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
+```
+
+`pane run` 将命令文本和 Enter 一起排入队列。成功仅表示提交已被接纳，不代表命令已经执行。在 macOS 上，如果命令超过终端当前的规范模式行输入上限，`pane run` 和 `agent start` 会在排队前拒绝该命令。等待交互式 shell 提示符后再重试。此检查仅覆盖本次提交，不涵盖先前未完成的输入行或之后的终端模式变化。`pane wait-output` 会立即搜索所选快照，因此已存在的输出也可能匹配。`--match <text>` 用于匹配字面子串，`--regex <pattern>` 用于 Rust 正则表达式。省略 `--timeout` 时可以无限等待。
+
+根据任务选择读取来源：
+
+- `visible`：当前渲染的可视区域。
+- `recent`：最近渲染的输出，包含软换行。
+- `recent-unwrapped`：合并软换行后的最近输出，日志和对话记录优先使用它。
+- `detection`：用于 agent 检测的底部缓冲区纯文本快照。
+
+颜色和终端样式属于证据时使用 `--format ansi`，否则使用文本。
+
+`--lines` 请求 Herdr 从窗格可用屏幕和宿主回滚缓冲区中读取更多行。备用屏幕的行不会进入普通宿主回滚缓冲区。对于受支持且处于 idle 的 agent，Herdr 可以收集应用自身的历史记录，并在之后恢复可视区域，但并非每个应用或响应都能以此方式恢复。
+
+如果扩大最近输出的读取范围后仍看不到已完成的响应，让 agent 将响应写为临时目录中的 Markdown 文件，并只回复文件路径，然后在同一机器上读取该文件。仅将此方式作为后备方案，不要在初始提示中要求文件输出。
+
+## 安全与协调规则
+
+- 后台工作使用 `--no-focus`，除非用户要求切换上下文。
+- 使用 `--current`、显式窗格 ID 或唯一 agent 名称。不要依赖其他客户端聚焦的窗格。
+- 从 JSON 响应中解析 ID。不要从侧栏顺序或示例推导 ID。
+- 未经用户明确要求，不要关闭并非由你创建的工作区、标签页、窗格或会话。普通 CLI/API 关闭操作不会继承 TUI 的最后一个窗格确认机制。`workspace close --group` 会关闭主工作区及其关联的 worktree 工作区，绝不能仅为绕过 `workspace_group_close_required` 而添加它。
+- 仅在用户已验证仓库后使用 `--trust-repository`。它授予单次请求的 Git 信任，不是 worktree 命令失败后的常规重试手段。
+- 更新后客户端与服务端版本可能不同。依赖新服务端功能前先检查 `herdr status`。方法缺失不代表可以停止或升级服务端。
+- 除非用户明确打算停止服务端及其窗格进程，否则绝不要从活动会话中运行 `herdr server stop`。
+- 绝不要杀死 Herdr 主进程。需要隔离服务端的实验应使用具名测试会话。
+- CLI 服务端错误以 JSON 输出到 stderr，退出状态为 1。CLI 语法错误退出状态为 2。
+
+## Claude Code & Codex & Pi 的默认启动方式命令
+
+在已有可用 shell 窗格中启动，`<name>` 使用唯一名称，`<returned-pane-id>` 使用实际返回的窗格 ID：
+
+```bash
+herdr agent start <name> --kind claude --pane <returned-pane-id> -- --dangerously-skip-permissions
+herdr agent start <name> --kind codex --pane <returned-pane-id> -- --no-daemon --dangerously-bypass-approvals-and-sandbox
+herdr agent start <name> --kind pi --pane <returned-pane-id>
+```