june-agent

Readme

# JuneAgent

June 双人格 Agent 包（**June-M** / **June-S**）与配套技能包（**git-backup** / **june-style**）。

本仓库同时提供两种格式的 Agent/技能定义，并可直接作为 **DSH 插件（npm 包 `june-agent`）** 发布：

- **Claude Code 格式**（`agents/` + `skills/`）：遵循 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 的 agents 与 skills 目录规范，可作为项目级（局部）或用户级（全局）扩展安装；
- **DeepSeek Harness 格式**（`presets/`）：遵循 DSH 的 **agent preset** 规范（`agent.cordis.yml` + `preset.yml` + `skills/`），技能格式（`<name>/SKILL.md`）与 Claude Code 通用；
- **DSH 插件**（根目录即 npm 包）：`cordis.patch.yml` + `lib/index.js` 构成 `dsh.bundle`，发布后用 `dsh plugin --profile <name> add june-agent` 一条命令安装。

## 目录结构

```
JuneAgent/                     # 同时也是 npm 包 june-agent（DSH 插件）
├── README.md                  # 本说明文件
├── package.json               # npm 包清单；dsh.bundle.patch 声明插件层
├── cordis.patch.yml           # DSH bundle patch：插入 june-agent 安装器行
├── lib/
│   └── index.js               # 插件模块：启动时把 presets/skills 物化到 DSH 用户根
├── LICENSE                    # MIT
├── agents/                    # Agent 定义（Claude Code 格式）
│   ├── June-M.md              # June-M：执行者人格（猫娘 M）
│   └── June-S.md              # June-S：执行者人格（S）
├── presets/                   # Agent 定义（DeepSeek Harness 格式）
│   ├── june-m/                # June-M preset（自带技能，可整体迁移）
│   │   ├── agent.cordis.yml   # preset 组装：Cordis 插件行列表
│   │   ├── preset.yml         # 展示元信息（name/description/order）
│   │   └── skills/            # 随 preset 注册的技能目录
│   └── june-s/                # June-S preset（同上结构）
└── skills/                    # 技能定义（两种格式通用）
    ├── git-backup/            # Git 备份技能
    │   └── SKILL.md
    └── june-style/            # 设计与编码规范技能
        └── SKILL.md
```

## Agent 说明

### June-M（温度 0.1）

执行代码与设计任务的「猫娘受」人格 Agent：

- 顺从、简洁、直接，回复以 `Meow~` / `喵~` 结尾
- 保留用户对审批与方向的完全控制，重大工作前给出简短计划
- 固定为 UTF-8 文件编码规范，中文文件读取使用 `chcp 65001` + `Get-Content -Encoding UTF8`
- 涉及设计或编码规范时自动应用 `june-style` 技能

### June-S（温度 0.3）

执行代码与设计任务的「S 支配」人格 Agent：

- 直接、克制、带纪律性的反驳与推回，简洁务实
- 保留用户对审批与方向的完全控制，重大工作前给出简短计划
- 相同的 UTF-8 / 中文文件编码规范
- 涉及设计或编码规范时自动应用 `june-style` 技能

## 技能说明

| 技能 | 用途 |
| --- | --- |
| `git-backup` | 提供三种本地 Git 备份策略（自动提交 / 永不提交 / 询问后提交），遵循 Conventional Commits 规范 |
| `june-style` | June 的设计指引（浅蓝描边风格、三层层级设计令牌、横幅/Logo/幻灯片/SVG 图标等）与代码纪律（Karpathy 风格、4 空格缩进、文件头注释等） |

## 安装方式（Claude Code 格式）

> 前置要求：已安装 Claude Code CLI。安装后重启 Claude Code 会话即可生效。

### 局部安装（仅当前项目）

将文件复制到项目内的 `.claude/` 目录，只对该项目生效。

**Windows（PowerShell，在仓库根目录执行）：**

```powershell
$dst = ".claude"
New-Item -ItemType Directory -Force -Path "$dst\agents", "$dst\skills" | Out-Null
Copy-Item "agents\June-M.md", "agents\June-S.md" -Destination "$dst\agents\"
Copy-Item "skills\git-backup" -Destination "$dst\skills\" -Recurse
Copy-Item "skills\june-style" -Destination "$dst\skills\" -Recurse
```

**macOS / Linux（Bash，在仓库根目录执行）：**

```bash
mkdir -p .claude/agents .claude/skills
cp agents/June-M.md agents/June-S.md .claude/agents/
cp -r skills/git-backup skills/june-style .claude/skills/
```

### 全局安装（所有项目）

将文件复制到用户主目录下的 `~/.claude/` 目录，对所有项目生效。

**Windows（PowerShell）：**

```powershell
$dst = "$env:USERPROFILE\.claude"
New-Item -ItemType Directory -Force -Path "$dst\agents", "$dst\skills" | Out-Null
Copy-Item "agents\June-M.md", "agents\June-S.md" -Destination "$dst\agents\"
Copy-Item "skills\git-backup" -Destination "$dst\skills\" -Recurse
Copy-Item "skills\june-style" -Destination "$dst\skills\" -Recurse
```

**macOS / Linux（Bash）：**

```bash
mkdir -p ~/.claude/agents ~/.claude/skills
cp agents/June-M.md agents/June-S.md ~/.claude/agents/
cp -r skills/git-backup skills/june-style ~/.claude/skills/
```

### 验证安装

```powershell
# Windows：确认文件已就位
Get-ChildItem "$env:USERPROFILE\.claude\agents", "$env:USERPROFILE\.claude\skills" -Recurse | Select-Object FullName
```

```bash
# macOS / Linux：确认文件已就位
ls -R ~/.claude/agents ~/.claude/skills
```

在 Claude Code 中输入 `@` 应能看到 `June-M`、`June-S` 两个 Agent 的补全项。

## 使用方式（Claude Code 格式）

- **调用 Agent**：在提示中输入 `@June-M` 或 `@June-S`（输入 `@` 可查看补全；`/agents` 可列出当前可用 Agent）。
- **调用技能**：Claude Code 会根据上下文自动加载技能，也可手动提及 `#git-backup`、`#june-style` 强制启用。
- **切换角色**：两个 Agent 是独立的固定人格，选定后全程保持，不会中途切换。

## DeepSeek Harness 格式与安装

`presets/` 下的内容遵循 DeepSeek Harness（DSH）的 **agent preset** 规范：preset 是一个目录，含 `agent.cordis.yml`（Cordis 插件行组合，决定该 Agent 的工具、人设与提示词段落）与可选 `preset.yml`（仅承载展示元信息：`name` / `description` / `order`）。技能沿用 `<name>/SKILL.md` 格式；两个 June preset 均通过 `skill-filesystem.customSkillDirs`（相对 `baseUrl` 解析）把自带的 `skills/` 目录注册进本 preset 的技能层，因此复制整个 preset 目录即可连同技能一起迁移。

### 格式对照

| 概念 | Claude Code | DeepSeek Harness |
| --- | --- | --- |
| Agent 定义 | `agents/<Name>.md`（frontmatter 风格） | `presets/<id>/agent.cordis.yml`（`persona` 行承载人格文本） |
| Agent 展示信息 | frontmatter 的 name / description | `preset.yml` 的 name / description / order |
| 技能 | `skills/<name>/SKILL.md` | 同左（`<dshHome>/skills`、项目根或 preset 内 `skills/`） |
| 模型温度 | frontmatter `temperature` | 不支持——模型路由（provider/model/温度）在宿主平面（host plane）配置 |

### 全局安装（DSH，用户级）

```bash
dsh plugin --profile web install github:lemonorangeapple/juneagent
```

### 局部安装（DSH，仅当前项目）

DSH 的 preset 默认没有项目级根目录，局部化有三种方式：

1. **技能局部化（推荐）**：DSH 技能发现包含项目根 `<projectRoot>/.dsh/skills`（rank 100）与 `<projectRoot>/.agents/skills`（rank 200），把技能复制到项目内即可让该项目使用：
   ```powershell
   New-Item -ItemType Directory -Force -Path ".dsh\skills" | Out-Null
   Copy-Item "skills\git-backup", "skills\june-style" -Destination ".dsh\skills\" -Recurse
   ```
2. **部署级 preset 根**：在宿主组装的 `agent-presets` 插件配置中增加 `roots`（每项含 `path` 与 `trust`），指向项目内的 preset 目录。
3. **仅全局**：preset 本质是用户级扩展，直接用上面的全局安装即可，无需每项目复制。

### 选择与验证（DSH）

- 新建会话时在 Web GUI 的 preset 选择器中选择 `June-M` / `June-S`；也可通过用户设置把默认 preset 改为 `june-m`（`agent-presets.default`），此后新建会话默认使用它。
- 验证：确认目录就位后重启 `dsh web` 并新建会话。preset 目录名必须匹配 `[a-z0-9][a-z0-9-]*`（`june-m`、`june-s` 均合法）；组装文件缺失或 YAML 无法解析的目录会被 roster 以 `broken` 原因列出。

### 卸载（DSH）

删除 `<dshHome>/.agent-presets/` 下的 `june-m`、`june-s`（及 `<dshHome>/skills/` 下对应技能）。已加入的会话保留其常驻挂载并继续运行；新会话不再提供该 preset。

## 发布为 DSH 插件

工作区根目录本身就是一个可发布的 npm 包 **`june-agent`**（npm 上该名称当前可用）。包内 `dsh.bundle.patch` 声明插件层，`lib/index.js` 是安装器插件：profile 启动时把 `presets/` 下的两个 preset 物化到用户 preset 根 `<dshHome>/.agent-presets/`、把 `skills/` 物化到 `<dshHome>/skills/`（已存在的目录一律跳过，不覆盖用户编辑）。

> 为什么用"物化"而不是配置 `agent-presets.roots`：profile 启动会把 `agent-presets` 行的 `roots` 整体替换为仅随附根，插件 patch 无法持久注入 preset 根；而 `<dshHome>/.agent-presets` 是 roster 默认自动发现（`includeUserRoot`）且官方 `copy()` 创作 API 写入的同一位置，是最可靠的插件安装通道。

### 发布（npm）

```powershell
# 1. 登录 npm（首次）
npm login

# 2. 在仓库根目录发布（files 已限定为 lib/、presets/、skills/、cordis.patch.yml）
npm publish
```

发布前可先在本地验证包内容：`npm pack --dry-run` 查看将包含的文件；建议在 `package.json` 中补充 `repository` 字段（指向你的 Git 仓库）。

### 安装（作为 DSH 插件）

```powershell
# 安装并自动加入 dsh.profile.bundles（等效于 pnpm add + 自动挂载）
dsh plugin --profile web add june-agent

# 指定版本 / 从本仓库本地安装（测试用）
dsh plugin --profile web add june-agent@0.1.0
dsh plugin --profile web add file:D:\1Repositories\JuneAgent
```

安装后重启 `dsh web`，新建会话即可在 preset 选择器中看到 `June-M` / `June-S`；技能目录会自动出现在 `<dshHome>/skills/` 与两个 preset 内。

### 本地安装（不发布，直接从本仓库安装）

不发布到 npm，把本仓库作为 `file:` 依赖直接装进 profile（等效于"安装 + 自动挂载"一步完成）：

**Windows（PowerShell）：**

```powershell
dsh plugin --profile web add file:D:\1Repositories\JuneAgent
```

**macOS / Linux（Bash）：**

```bash
dsh plugin --profile web add "file:$(pwd)"
```

该命令会做三件事：① pnpm 把包安装到 `<dshHome>/profiles/web/node_modules/june-agent`（`file:` 依赖是 store 拷贝）；② 自动把 `june-agent` 追加到 `dsh.profile.bundles`；③ 下次启动 `dsh web` 时插件挂载，`apply()` 把 `presets/` 物化到 `<dshHome>/.agent-presets/`、把 `skills/` 物化到 `<dshHome>/skills/`（已存在的目录一律跳过，不覆盖用户编辑）。

**不重启就物化**：插件 `apply()` 与启动时执行的是同一段代码，可手动运行一次（Windows PowerShell）：

```powershell
node --input-type=module -e "import('file:///D:/1Repositories/JuneAgent/lib/index.js').then(m => m.apply({ logger: { info: console.log } }))"
```

**验证安装：**

```powershell
# 1. bundles 已含 june-agent
(Get-Content "$env:USERPROFILE\.dsh\profiles\web\package.json" -Raw | ConvertFrom-Json).dsh.profile.bundles

# 2. 组合树已含 june-agent 插件行
dsh --profile web --dump-config | Select-String june-agent

# 3. preset / skill 已物化到用户根
Get-ChildItem "$env:USERPROFILE\.dsh\.agent-presets", "$env:USERPROFILE\.dsh\skills" -Recurse -File
```

preset 目录物化后即被 roster 实时发现（发现无缓存），当前运行中的 GUI 新建会话即可在 preset 选择器中看到 `June-M` / `June-S`；若选择器未刷新，重启 `dsh web` 即可。

**更新**：编辑本仓库内容后重跑 `dsh plugin --profile web add file:...`（拷贝不会自动跟随改动），再手动物化或重启 `dsh web`。

### 卸载（作为 DSH 插件）

```powershell
dsh plugin --profile web rm june-agent   # 从 bundles 移除并卸载依赖
Remove-Item "$env:USERPROFILE\.dsh\.agent-presets\june-m", "$env:USERPROFILE\.dsh\.agent-presets\june-s" -Recurse -Force
Remove-Item "$env:USERPROFILE\.dsh\skills\git-backup", "$env:USERPROFILE\.dsh\skills\june-style" -Recurse -Force
```

注意：插件会在每次启动时把缺失的 preset/skill 目录重新装回（这是插件的所有权语义）；先执行 `dsh plugin rm` 再删除目录，即可保持删除。

## 更新与卸载

- **更新**：拉取本仓库最新代码后，重复执行对应的安装命令覆盖即可。
- **卸载（局部）**：删除项目内 `.claude/agents/June-M.md`、`.claude/agents/June-S.md` 及 `.claude/skills/` 下对应技能目录。
- **卸载（全局）**：删除 `~/.claude/`（或 `%USERPROFILE%\.claude\`）下对应的 agents / skills 文件。

## 兼容性说明

- **Claude Code 系列**：`agents/*.md` + `skills/<name>/SKILL.md` 结构适用于 Claude Code 及支持该规范的工具（如 Roo Code、Cline 等），安装路径遵循各工具自身规范即可。
- **DeepSeek Harness**：`presets/<id>/`（`agent.cordis.yml` + `preset.yml` + `skills/`）是 DSH 的标准 agent preset 布局；技能 frontmatter（`name` + `description`，kebab-case）同时满足两边的格式要求，`skills/` 目录可直接复用。