# myharness

**Repository Path**: fflo/myharness

## Basic Information

- **Project Name**: myharness
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# myharness — AI 工具配置中央仓库

> 多个 AI 编码工具（Claude Code / Claude Desktop / Cursor / Qoder / Trae / Codebuddy）的 rules / skills / MCP 配置单一数据源。
> 通过 `sync.py` 将本仓库同步到各目标项目，并按工具格式自动转换。

## 目录结构

```
myharness/
├── AGENTS.md                # 由 rules-source 聚合生成（用于项目根）
├── rules-source/            # 规则源分片（无 frontmatter）
│   ├── 00-ai-behavior.md    → 目标: ai-behavior-rules.md
│   ├── 10-development.md    → 目标: development-rules.md
│   └── 20-security.md       → 目标: security-rules.md
├── skills/                  # 跨工具共享的 skills 源
├── mcp/
│   ├── servers.json         # MCP 服务器统一定义
│   └── templates/           # 各工具 MCP 模板
│       ├── cursor.json.tpl
│       ├── claude-code.json.tpl
│       └── claude-desktop.json.tpl
├── projects.json            # 需要同步的目标项目清单
├── sync.py                  # 同步脚本（标准库，Python 3.8+）
└── README.md
```

## 安装与初始化

```powershell
# Windows PowerShell
# 1. 将本目录移动到用户家目录
Move-Item .\myharness "$env:USERPROFILE\.myharness"

# 2. 初始化 Git 并推送到 GitHub 私有仓库 myharness
cd "$env:USERPROFILE\.myharness"
git init
git add .
git commit -m "feat: initial central config repo"
git branch -M main
git remote add origin git@github.com:<YOUR_USER>/myharness.git
git push -u origin main
```

```bash
# macOS / Linux
mv ./myharness ~/.myharness
cd ~/.myharness
git init && git add . && git commit -m "feat: initial central config repo"
git branch -M main
git remote add origin git@github.com:<YOUR_USER>/myharness.git
git push -u origin main
```

## 使用

> ⚠️ **路径差异提醒**：Windows PowerShell **不会**把 `~` 展开为用户主目录，直接写 `~/.myharness/sync.py` 会被当成相对路径。
> - **Windows PowerShell**：使用 `$HOME\.myharness\sync.py`
> - **macOS / Linux (bash/zsh)**：使用 `~/.myharness/sync.py`
>
> 下面命令分别给出两种平台的写法，可直接无脑复制。

### Windows PowerShell

```powershell
# 同步指定项目（默认同步 rules + skills + mcp）
python $HOME\.myharness\sync.py --project D:\projects\xxx

# 仅同步 rules
python $HOME\.myharness\sync.py --project <path> --component rules

# 同步 projects.json 中的全部项目
python $HOME\.myharness\sync.py --all

# 只同步某个工具
python $HOME\.myharness\sync.py --project <path> --tool cursor

# 干跑（不写入）
python $HOME\.myharness\sync.py --project <path> --dry-run

# 包含用户级（Claude Desktop）
python $HOME\.myharness\sync.py --project <path> --include-user-scope
```

> 💡 也可以用 `$env:USERPROFILE\.myharness\sync.py` 替代 `$HOME\.myharness\sync.py`，效果相同。

### macOS / Linux (bash/zsh)

```bash
# 同步指定项目（默认同步 rules + skills + mcp）
python ~/.myharness/sync.py --project /projects/xxx

# 仅同步 rules
python ~/.myharness/sync.py --project <path> --component rules

# 同步 projects.json 中的全部项目
python ~/.myharness/sync.py --all

# 只同步某个工具
python ~/.myharness/sync.py --project <path> --tool cursor

# 干跑（不写入）
python ~/.myharness/sync.py --project <path> --dry-run

# 包含用户级（Claude Desktop）
python ~/.myharness/sync.py --project <path> --include-user-scope
```

### 常见报错速查

| 报错 | 原因 | 解决 |
|------|------|------|
| `can't open file '...\~\.myharness\sync.py'` | PowerShell 下 `~` 未展开 | 改用 `$HOME\.myharness\sync.py` |
| `No such file or directory: '~/.myharness/...'` | Python 未展开 `~`（参数传入时） | 在 bash/zsh 下命令行使用 `~`；脚本内部交给 `os.path.expanduser` |
| 中文路径乱码 | 控制台编码非 UTF-8 | PowerShell 执行 `chcp 65001` 后再运行 |

## 各工具适配矩阵

| 工具 | rules 策略 | skills 目录 | MCP 路径 |
|------|-----------|-------------|---------|
| Claude Code | 项目根 AGENTS.md + CLAUDE.md（alias/mirror/off） | `.claude/skills/` | 项目级 `.mcp.json` |
| Claude Desktop | 不使用 | 不同步 | Win: `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | 项目根 AGENTS.md + `.cursor/rules/*.mdc`（alwaysApply: true） | `.cursor/skills/` | `.cursor/mcp.json` |
| Qoder | `.qoder/rules/*.md`（trigger: always_on） | `.qoder/skills/` | 暂不同步 |
| Trae | `.trae/rules/*.md`（trigger: always_on） | `.trae/skills/` | 暂不同步 |
| Codebuddy | `.codebuddy/rules/*.md`（无 frontmatter） | `.codebuddy/skills/` | 暂不同步 |

## claude_mode 说明

`projects.json` 中每个项目可配置 `claude_mode`：

- `alias`（推荐）：CLAUDE.md 仅保留一行指向 AGENTS.md，真源在 AGENTS.md
- `mirror`：CLAUDE.md 与 AGENTS.md 内容完全一致（双写）
- `off`：不生成 CLAUDE.md，仅依赖 Claude Code 对 AGENTS.md 的新版支持

## 维护流程

1. **修改规则**：只改 `rules-source/*.md`，提交到中央仓库
2. **新增 skill**：在 `skills/` 下新增目录，包含 `SKILL.md`
3. **新增 MCP server**：在 `mcp/servers.json` 中追加条目，指定 `enabled_in`
4. **运行 `sync.py --all`** 将变更分发到各项目
5. 各项目内的 `AGENTS.md / CLAUDE.md / .mcp.json / <tool>/rules/ / <tool>/skills/` 会被覆盖，禁止直接在项目内修改

## 安全红线

- 禁止在 `mcp/servers.json` 或任何模板中硬编码密钥，使用 `<PROJECT_ROOT>` 等占位符
- `secrets.json` 已在 `.gitignore` 中，本地需要密钥时用它
- 推送前再三确认没有密钥进仓库