wish-agents-kit

English | 简体中文

wish-agents-kit 是发布到 npm 的工具包，用于管理单个 .agents 目录，并更新 Codex AGENTS.md 中的托管区块。

包名和命令名

发布到 npm 的包名是 wish-agents-kit。安装后的主 CLI 命令是：

• wish-agents

为了兼容旧用法，包中也保留 wish-agents-kit 命令。下面的示例中，./bin/agents.mjs 是仓库内本地开发包装脚本，wish-agents 是安装 npm 包后的命令。

MVP 行为

• 在已安装的业务项目中，.agents 是当前生效的事实来源。
• 在共享源仓库中，可分发资产应放在 agent-assets/ 下；仍兼容旧的 .agents/ 源仓库结构。
• .agents/config.yaml 决定业务项目启用哪些规则和技能。
• 规则会动态汇总到 AGENTS.md 中；生成区块只包含规则名、描述和规则文件链接。
• 技能保留在 .agents/skills 下，按渐进披露方式使用，不会被索引到 AGENTS.md。
• 当 .agents/config.yaml 配置了 source 时，sync 会先更新已安装的源资源，然后只替换 AGENTS.md 中 <!-- agents:managed:start --> 到 <!-- agents:managed:end --> 之间的区块。
• 如果有人手动编辑托管区块，除非使用 --force，否则校验和保护会阻止同步。

规则模型

规则是 .agents/rules 下的 Markdown 文件。每个启用的规则都必须写在 .agents/config.yaml 中：

rules:
  enable:
    - common-git
    - domain

每个规则文件都必须包含带 name 和 description 的 YAML frontmatter：

---
name: common-git
description: Git workflow and commit safety.
---

# Git Conventions

Use short commit messages.

wish-agents sync 会读取这些元数据，并在 AGENTS.md 中生成类似下面的摘要：

- `common-git`: Git workflow and commit safety. See `.agents/rules/common-git.md`.

规则正文不会复制进 AGENTS.md。Agent 在编辑前，如果任务触及对应领域，就必须打开链接到的规则文件。

从源仓库初始化时，源资源 ID 可以使用 common/common-git 或 services/lion-wms/domain 这样的斜杠路径。公共资源文件名或 skill 目录名必须自带 common- 前缀；common/common-git 会安装成 common-git，common/git 会直接报错，不自动改名。服务资源会去掉 services/<服务名>/ 前缀，例如 services/lion-wms/domain 会变成 domain。每个业务仓库只能选择一个源服务；如果展开后的 preset 与该服务资源仍映射到相同安装 ID，初始化会直接失败，不会覆盖任一资源。

服务名、服务文件名和 services/<service>/... 资源 ID 应统一使用连字符命名，例如 lion-wms 或 lion-einvoice。服务 manifest 可以 extend preset，也可以 extend 另一个服务 manifest，例如 lion-einvoice 同时 extend services/project-docs 和 presets/backend-java。这些 manifest 中重复的源 ID 会在安装前去重。

命令

需要 Node.js 18 或更高版本。源码使用 TypeScript；运行时代码会生成到 dist/。

npm install
npm run build
npm test
npm run typecheck

./bin/agents.mjs init --source [email protected]:ai/team-agents.git
./bin/agents.mjs init --source [email protected]:ai/team-agents.git --service lion-wms
./bin/agents.mjs init --service lion-wms --preset backend-java
./bin/agents.mjs diff
./bin/agents.mjs sync
./bin/agents.mjs promote skill inventory-check --source-worktree ../team-agents
./bin/agents.mjs check
./bin/agents.mjs help
./bin/agents.mjs init --help
./bin/agents.mjs skill list
./bin/agents.mjs rule list

使用发布后的 npm 包：

npm install -g wish-agents-kit
wish-agents sync
wish-agents help
npx -p wish-agents-kit wish-agents check

仓库里的包装脚本 ./bin/agents.mjs 会运行编译后的 dist/src/index.js。

基于源仓库的初始化

推荐的公司内工作流是从共享 GitLab 源仓库初始化：

./bin/agents.mjs init --source [email protected]:ai/team-agents.git

CLI 会扫描：

agent-assets/services/*.yaml

然后打开一个交互式单服务选择器：

? Select one service from source

> lion-tmsbusiness     Lion TMS Business
  lion-wms             Lion WMS

Enter/Space: select  Ctrl+C: cancel

如果要非交互使用，只能传一个服务。一个业务仓库只能选择一个服务：

./bin/agents.mjs init --source [email protected]:ai/team-agents.git --service lion-wms

init --source 会读取源仓库中的 agent-assets/ 目录，展开所选服务 manifest，仅将选中及其扩展出的规则和技能安装到业务项目中，写入 .agents/config.yaml、.agents/lock.yaml，并更新 AGENTS.md。仍然兼容继续使用 .agents/ 存放可分发资产的旧源仓库。

安装到项目中的资源是扁平的，并且只作用于已选服务：

.agents/
  config.yaml
  lock.yaml
  rules/
    common-git.md
    common-security.md
    stacks-spring-boot.md
    domain.md
  skills/
    common-code-review/
      SKILL.md
    inventory-check/
      SKILL.md

未选择的服务不会被复制到业务项目中。

提升本地技能改动

如果业务项目修改了一个从源仓库安装来的 skill，并且这个改动应该沉淀为共享源仓库行为，可以把它提升回源仓库的本地 checkout：

wish-agents promote skill inventory-check --source-worktree ../team-agents

--source-worktree 必须指向包含 agent-assets/ 或旧版 .agents/ 的共享资产源仓库本地 checkout；它不是 wish-agents-kit 工具包仓库，除非该仓库同时存放共享资产。命令会根据当前项目 .agents/config.yaml 中的服务选择解析安装后的 skill ID，把 .agents/skills/inventory-check/ 复制到对应的源路径，例如 agent-assets/skills/services/lion-wms/inventory-check/，然后打印写入路径。它不会提交或推送；请在源仓库中 review、测试、提交和推送。

如果希望写入前在源仓库 worktree 中创建或重置分支，可以传 --branch：

wish-agents promote skill inventory-check --source-worktree ../team-agents --branch update-inventory-check

源仓库结构

共享 GitLab 仓库应当具备如下结构：

agent-assets/
  services/
    lion-wms.yaml
    lion-tmsbusiness.yaml
  presets/
    backend-java.yaml
  rules/
    common/
      git.md
    services/
      lion-wms/
        domain.md
  skills/
    common/
      code-review/
        SKILL.md
    services/
      lion-wms/
        inventory-check/
          SKILL.md

聚合服务可以组合已有 manifest，同时仍然满足单服务选择规则：

name: lion-einvoice
displayName: Lion EInvoice
extends:
  - services/project-docs
  - presets/backend-java

服务配置示例：

name: lion-wms
displayName: Lion WMS
extends:
  - presets/backend-java
rules:
  enable:
    - services/lion-wms/domain
skills:
  enable:
    - services/lion-wms/inventory-check

预设配置示例：

rules:
  enable:
    - common/common-git
skills:
  enable:
    - common/common-code-review

.agents/config.yaml

source:
  type: git
  url: [email protected]:ai/team-agents.git
  ref: master
project:
  service: lion-wms
rules:
  enable:
    - common-git
    - domain
skills:
  enable:
    - common-code-review
    - inventory-check

目录结构

.agents/
  config.yaml
  lock.yaml
  rules/
    common-git.md
    domain.md
  skills/
    common-code-review/
      SKILL.md
    inventory-check/
      SKILL.md

AGENTS.md 占位符

在运行 wish-agents sync 之前，请将人工维护的说明写在托管区块之外，并加入以下占位标记：

# Project Instructions

Human project notes stay here.

<!-- agents:managed:start source=".agents/config.yaml" -->
<!-- agents:managed:end -->

当 .agents/config.yaml 配置了 source 时，wish-agents sync 会先更新已安装的源资源，然后只替换 AGENTS.md 中的托管区块。生成后的区块会自动包含校验和；不要手动编写或修改该校验和。

生成后的 AGENTS.md

# Project Instructions

<!-- agents:managed:start source=".agents/config.yaml" checksum="..." -->
## Agent 执行协议

- 修改文件前，必须读取当前 `AGENTS.md` 指令，以及与任务相关的所有生效规则文件。
- 改动前，必须说明预期影响范围和验证方式。
- 最终回复必须汇报本次实际使用的 `skill`、`rule` 和 `AGENTS.md`。如未使用，必须明确写“未使用”或“未使用独立 rule 文件”。

## 生效规则

以下规则对本项目生效。任务触及对应领域时，编辑前必须打开引用的规则文件。

- `common-git`: Git workflow and commit safety. See `.agents/rules/common-git.md`.
- `domain`: Lion WMS warehouse and inventory domain ownership. See `.agents/rules/domain.md`.
<!-- agents:managed:end -->