# agent_settings

**Repository Path**: camesvest/agent_settings

## Basic Information

- **Project Name**: agent_settings
- **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-09-15
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agent_settings

跨 harness（pi / Claude Code / Codex / opencode / Copilot CLI）、跨机器的 **Agent 配置单一真源**。
把"可共享的行为契约与技能"集中在这里，用软链部署到家目录；机器专属配置与密钥**永不入库**。

## 目录结构

```
agent_settings/
├── manifest.tsv                 部署白名单：type / source / target（唯一事实源）
├── packages.tsv                 依赖清单（只声明"装什么"，不含任何配置值）
├── bootstrap.sh                 幂等部署：建链 + 可选装依赖（默认 dry-run）
├── bootstrap.ps1                Windows 入口（同一份 manifest，需管理员）
├── tests/bootstrap_smoke.sh     冒烟测试（沙箱 HOME，绝不碰真实家目录）
├── tests/bootstrap_smoke.ps1   Windows 冒烟测试（沙箱目录，需管理员）
└── shared/                      真源
    ├── AGENTS.md                通用行为契约 → ~/.agents/AGENTS.md
    └── skills/
        ├── software-expert/
        │   ├── SKILL.md         三阶段门禁（设计 → 编码 → 审查）
        │   └── references/      tdd / oo_design / modularity / code_review
        └── karpathy-guidelines/SKILL.md
```

## 文件分三类（核心原则）

| 类别 | 特征 | 代表 | 处理 |
| :--- | :--- | :--- | :--- |
| **A 纯输入** | harness 只读，从不自写 | `AGENTS.md`、`skills/`、`settings.json` 之外的只读配置 | ✅ 软链（本仓库管理） |
| **B 输入+自写混合** | harness 运行时**会改它** | `~/.pi/agent/settings.json`、`~/.claude/settings.json`、`~/.codex/config.toml` | ❌ **不入库**（各 PC 个性文件） |
| **C 机器状态 / 密钥** | 每机不同、密级 | `auth.json`、`models.json`、`trust.json`、`sessions/`、`*.sqlite` | ❌ 永不入库 |

**为什么 B 类不能软链**：软链之后 harness 会直接改写仓库文件 → 换机时 git 冲突；一旦写入密钥还会进 git 历史（不可逆）。
**为什么密钥不会漏**：`bootstrap.sh` 只处理 `manifest.tsv` 声明的条目，未声明文件永不被链接 —— 结构上杜绝。

## 快速开始

```bash
cd ~/gitee/agent_settings

./bootstrap.sh                    # 预览（默认 dry-run，不写任何文件）
./bootstrap.sh --yes              # 执行建链（真文件会先备份为 *.bak.<时间戳>）
./bootstrap.sh --packages         # 预览依赖安装命令
./bootstrap.sh --yes --packages   # 建链 + 联网安装依赖
./bootstrap.sh --rollback         # 回滚上一次执行

bash tests/bootstrap_smoke.sh     # 冒烟测试（沙箱 HOME）
```

安全性：dry-run 零写入；非空目录**跳过并告警**、永不删除；重复执行幂等；每次执行写 state 文件供回滚。

## Windows 部署

同一份 `manifest.tsv` / `packages.tsv`，Windows 侧入口是 `bootstrap.ps1`，语义与 `bootstrap.sh` 对齐。

```powershell
cd E:\gitee\agent_settings

.\bootstrap.ps1                   # 预览（默认 dry-run，不写任何文件）
.\bootstrap.ps1 -Yes               # 执行建链（真文件先备份为 *.bak.<时间戳>）
.\bootstrap.ps1 -Packages          # 预览依赖
.\bootstrap.ps1 -Yes -Packages     # 建链 + 装依赖
.\bootstrap.ps1 -Rollback          # 回滚上一次执行

powershell -NoProfile -ExecutionPolicy Bypass -File tests\bootstrap_smoke.ps1   # 冒烟测试
```

**必须用「以管理员身份运行」的 PowerShell**：建符号链接需要管理员权限（或开发者模式）；dry-run 不需提权。
状态文件写在 `%LOCALAPPDATA%\agent_settings\bootstrap.state`。

| 与 Linux 版的差异 | 说明 |
| :--- | :--- |
| 提权与探测 | 执行前先探测提权、身份一致性、符号链接能力，任一不满足即中止 |
| 身份校验 | 提权账号须与 `%USERPROFILE%` 账号一致，防止链到别的家目录 |
| 状态目录 | `%LOCALAPPDATA%\agent_settings`（Linux 用 XDG） |
| 摘链接 | 用 `[IO.Directory]::Delete` / `[IO.File]::Delete` 只摘链接本身，避免 `Remove-Item -Recurse` 穿透重解析点误删真源 |

**编码铁律（改本仓库 `.ps1` 前必读）**：含中文的 `.ps1` 必须存为 **UTF-8 with BOM**。
PowerShell 5.1 在无 BOM 时按系统 ANSI 解析脚本，中文字节会吞掉引号导致语法错误，
且报错位置指向文件末尾、极难定位。`.md` / `.tsv` 等数据文件保持无 BOM。

**其他已知坑**（已写入代码注释）：`,` 优先级高于 `+`，数组元素内的字符串拼接必须先算进变量；
`Resolve-Path` 不解析符号链接，健康度判定改用 `LinkType` 比对；脚本内文本读写一律显式 `-Encoding UTF8`。

---

## 各 harness 如何读到这些内容

| harness | 指令（行为契约） | 技能 |
| :--- | :--- | :--- |
| **pi** | `~/.pi/agent/AGENTS.md` → 软链到真源 | 原生读 `~/.agents/skills`（另有 `.agents/skills`、`.pi/skills`） |
| **Codex** | `~/.codex/AGENTS.md` → 软链 | `~/.codex/skills` → 软链到 `~/.agents/skills` |
| **Claude Code** | `~/.claude/CLAUDE.md` → 软链 | `~/.claude/skills` → 软链到 `~/.agents/skills` |
| **opencode** | 原生读 `AGENTS.md`（全局建议在 `opencode.jsonc` 的 `instructions` 里显式指向 `~/.agents/AGENTS.md`） | 原生读 `~/.agents/skills`（另有 `~/.claude/skills`） |
| **Copilot CLI** | 原生读 `AGENTS.md`（`--no-custom-instructions` 可关闭） | 未发现技能机制 |

**为什么 `~/.agents/skills` 保持真目录、只把技能逐条链进去**：该目录可能被第三方技能安装器托管
（例如 `microsoft-foundry`，`.skill-lock.json` 有记录）。整目录软链会覆盖它们，所以只链接本仓库拥有的技能。

**已知噪声**：opencode 同时自动读 `~/.claude/skills` 与 `~/.agents/skills`，而前者是后者的软链
→ 同一技能被发现两次并产生"同名冲突"告警（first-wins，功能不损）。这是接受的设计代价。

## 新机器人工步骤（脚本不管这些）

`bootstrap.sh` **只建链、只装包，永不写配置文件**。以下需手动完成：

1. **密钥 / 凭证**（必做）
   `~/.pi/agent/auth.json`、`~/.pi/agent/models.json`、`~/.codex/auth.json`、`~/.codex/models.json`、`~/.codex/config.toml` 等 —— 新机器手动填。
2. **pi 用户设置** `~/.pi/agent/settings.json`：至少补 `packages`（也可用 `./bootstrap.sh --yes --packages` 装）、
   `defaultProvider` / `defaultModel` / `defaultThinkingLevel` / `theme`。
3. **Claude Code 用户设置** `~/.claude/settings.json`：`env`（代理地址、模型名映射）等机器专属值，
   例如本机曾使用 `ANTHROPIC_BASE_URL=http://127.0.0.1:15721`。**不同机器端口未必相同，必须逐机确认。**
4. **opencode** `~/.config/opencode/opencode.jsonc`：如需追加指令/技能路径，写 `instructions` 与 `skills.paths`。
5. 运行 `./bootstrap.sh` 预览 → `./bootstrap.sh --yes` 落地 → `bash tests/bootstrap_smoke.sh` 自检。

## 本仓库不做什么

- 不装 harness 本身（只装它们的插件/包）。
- 不写任何配置文件（B 类一律手动）。
- 不碰密钥。
- 不删除任何用户数据（只备份、只跳过）。

## 与项目仓库的分工

项目根目录的 `AGENTS.md` 保留**项目专属**内容（目录结构、命令、领域铁律、项目级规范入口）；
通用部分只在本仓库维护一份，避免双写漂移。项目侧引用写法：

- 项目 `AGENTS.md`：声明"完整行为契约见 `~/.agents/AGENTS.md`"，并保留 3–5 行最关键的硬约束（保证项目自洽）。
- 项目模块化规范：只写**项目特化**（层命名、固定返回结构字段），并声明"未提及处遵循
  `~/.agents/skills/software-expert/references/modularity_rules.md`"。
- 项目技能目录：放 `.agents/skills/`（pi 原生读 `<cwd>/.agents/skills`；opencode 项目级需在
  `opencode.json` 里用 `skills.paths` 显式指向；Claude Code 用插件 manifest 指向）。

---

## 当前部署状态（2026-09-15 首次落地）

> 状态真源就是本文件，**不在项目仓库另存一份**，避免双写漂移。

### 已建立的软链（9 条，`bootstrap.sh --yes` 执行结果）

| 目标 | 指向 | 说明 |
| :--- | :--- | :--- |
| `~/.agents/AGENTS.md` | `shared/AGENTS.md` | 跨 harness 单一真源 |
| `~/.pi/agent/AGENTS.md` | `shared/AGENTS.md` | pi 全局上下文 |
| `~/.codex/AGENTS.md` | `shared/AGENTS.md` | 原为 0 字节占位，已替换（未产生备份） |
| `~/.claude/CLAUDE.md` | `shared/AGENTS.md` | 原 70 行 karpathy，已备份为 `CLAUDE.md.bak.<时间戳>` |
| `~/.agents/skills/software-expert` | `shared/skills/software-expert` | 逐技能链入（该目录含第三方技能） |
| `~/.agents/skills/karpathy-guidelines` | `shared/skills/karpathy-guidelines` | 同上 |
| `~/.claude/skills` | `~/.agents/skills` | 整目录链入（该目录原先不存在） |
| `~/.codex/skills/software-expert` | `shared/skills/software-expert` | 逐技能链入（该目录含 Codex 自带 `.system`） |
| `~/.codex/skills/karpathy-guidelines` | `shared/skills/karpathy-guidelines` | 同上 |

### 各 harness 的实际可见性（已实测）

| harness | 用户级指令 | 用户级技能 | 项目级技能 |
| :--- | :--- | :--- | :--- |
| **pi** | ✓ `~/.pi/agent/AGENTS.md` | ✓ 原生读 `~/.agents/skills`（3 个） | ✓ 原生读 `<cwd>/.agents/skills`（10 个） |
| **Codex** | ✓ `~/.codex/AGENTS.md` | ✓ `~/.codex/skills` 软链 | 未配置 |
| **Claude Code** | ✓ `~/.claude/CLAUDE.md` | ✓ `~/.claude/skills` 软链 | ✗ 只读 `.claude/skills`（**有意不补**：项目技能为 pi 视角编写，引用了 Claude Code 不具备的 pi 工具名） |
| **opencode** | 项目级原生读 `AGENTS.md`；用户级建议在其配置里显式指向 `~/.agents/AGENTS.md` | ✓ 原生读 `~/.agents/skills`（另会重复发现 `~/.claude/skills`，产生同名告警，**已接受**） | ✓ 项目 `opencode.json` 的 `skills.paths` |
| **Copilot CLI** | 原生读 `AGENTS.md` | 无技能机制 | — |

### Windows 侧部署状态（2026-10-06 首次落地）

`bootstrap.ps1 -Yes` 已在 Windows 主机建链 9 条，与 Linux 侧同构（含未安装 pi 的那条）：
`.agents\AGENTS.md`、`.pi\agent\AGENTS.md`、`.codex\AGENTS.md`、`.claude\CLAUDE.md`、
`.agents\skills\{software-expert,karpathy-guidelines}`、`.claude\skills`、`.codex\skills\{software-expert,karpathy-guidelines}`（均在 `%USERPROFILE%` 下）。

- 可见性实测：**DSH 已确认**（部署后会话内技能目录即时出现 `software-expert` / `karpathy-guidelines`）；
  Claude Code / Codex / opencode 尚待重启后确认。
- 冒烟测试：`tests\bootstrap_smoke.ps1` 30 项断言全绿（需管理员 PowerShell）。
- 非提权运行冒烟测试会停在符号链接探测并给出明确提示（退出码 1、零残留），此路径已实测。

### 验证方式（可随时复跑）

```bash
./bootstrap.sh                 # dry-run：应显示 link=0 skip=9（幂等）
bash tests/bootstrap_smoke.sh  # 沙箱全量自检（30 项断言）
ls ~/.agents/skills/           # 全局：karpathy-guidelines / microsoft-foundry / software-expert
ls <project>/.agents/skills/   # 项目：10 个技能
```

pi 侧自检要点：**重启 pi** 后 `<available_skills>` 应含 13 个技能（全局 3 + 项目 10），
且项目技能的 location 指向 `<repo>/.agents/skills/<name>/SKILL.md`。

### 注意事项

- `~/.claude/CLAUDE.md.bak.<时间戳>`：确认 Claude Code 下新配置可用后再删。
- 修改本仓库文件 = **同时改变 pi / Claude Code / Codex（及 opencode 全局层）的行为**，改前先想清楚影响面。
- 部署后各 harness 需**重启**才会重新扫描指令与技能。
- `~/.agents/skills` 与 `~/.codex/skills` 属"被占用目录"，**永远不要**整目录链入
  （会覆盖第三方技能 `microsoft-foundry` 与 Codex 自带的 `.system`）。