# team_mgmt：管理 `.minds/`（prepare-first + single apply）

你拥有对 `.minds/**` 的读写能力，但该 toolset **只允许操作 `.minds/` 子树**（不会也不应触碰 rtws（运行时工作区）其他文件）。

## 总原则

- 增量编辑（推荐）：用 `team_mgmt_prepare_*` 先生成可复核的 YAML + diff + `hunk_id`，再用 `team_mgmt_apply_file_modification({ "hunk_id": "<hunk_id>" })` 显式写入。
- 若你承担团队管理职责，执行具体团队管理操作前，先查看 `man({ "toolsetId": "team_mgmt" })` 的相关章节，并按手册标准做法维护 `.minds/**` 团队心智资产。
- 并行约束：同一轮生成中的多个工具调用可能并行执行；**prepare → apply 必须分两轮**。
- 例外（创建）：`team_mgmt_create_new_file` 只负责创建新文件（允许空内容），不做增量编辑、不走 prepare/apply；若文件已存在会拒绝（避免误用覆盖写入语义）。
- 例外（整文件覆盖）：`team_mgmt_overwrite_entire_file` 会直接写盘（不走 prepare/apply），必须提供 `known_old_total_lines/known_old_total_bytes` 作为对账护栏；建议先用 `team_mgmt_read_file` 从 YAML header 读取 `total_lines/size_bytes` 再填写。
- 规范化：写入遵循“每行以 `\\n` 结尾（含最后一行）”；必要时会补齐并通过输出字段呈现（例如 `normalized_trailing_newline_added` / `normalized.*`）。

## read_file 输出字段（重要）

`team_mgmt_read_file` 的 YAML header 会给出：

- `total_lines`：总行数（空文件为 0），可直接填入 `team_mgmt_overwrite_entire_file.known_old_total_lines`
- `size_bytes`：字节数（等于 stat().size），可直接填入 `team_mgmt_overwrite_entire_file.known_old_total_bytes`

## 路径规则（重要）

- 该 toolset 会把 `path` 解析到 `.minds/` 下：例如 `team.yaml` 会被解析为 `.minds/team.yaml`。
- 任何最终解析不在 `.minds/` 内的路径都会被拒绝。

## 该用哪个工具

- 读取定位：`team_mgmt_read_file` / `team_mgmt_list_dir` / `team_mgmt_ripgrep_*`
- 创建新文件（允许空内容）：`team_mgmt_create_new_file({ path, content })`
- 小改动（行号范围）：`team_mgmt_prepare_file_range_edit({ path, range, content, existing_hunk_id })`
- 末尾追加：`team_mgmt_prepare_file_append({ path, content, create, existing_hunk_id })`
- 锚点插入：`team_mgmt_prepare_file_insert_after|team_mgmt_prepare_file_insert_before({ path, anchor, content, occurrence, match, existing_hunk_id })`
- 双锚点块替换：`team_mgmt_prepare_file_block_replace({ path, start_anchor, end_anchor, content, existing_hunk_id, occurrence, include_anchors, match, require_unique, strict })`
- 应用写入：`team_mgmt_apply_file_modification({ hunk_id })`
- 修改完 `.minds/team.yaml`：务必运行 `team_mgmt_validate_team_cfg({})`；若输出里出现“已解决但未清理的问题”，可用 `team_mgmt_clear_problems({ source: "team", path: "team.yaml" })` 收尾。
- 修改完 `.minds/mcp.yaml`：务必运行 `team_mgmt_validate_mcp_cfg({})`；若输出里出现“已解决但未清理的问题”，可用 `team_mgmt_clear_problems({ source: "mcp", path: "mcp.yaml" })` 收尾。

> 可选字段默认可省略。  
> 若你想显式传入“未指定/默认”，支持以下哨兵值写法：
>
> - `existing_hunk_id: ""`：不覆写旧规划（生成新 hunk）。
> - `occurrence: ""` 或 `0`：不指定 occurrence。
> - `match: ""`：默认 `contains`（注意：`match` 是 match mode，不是要匹配的文本/正则）。

## apply 语义（context_match）

- `exact`：文件与 prepare 时一致，或在原位匹配成功。
- `fuzz`：文件有漂移但仍能安全应用；此时输出会给出 `file_changed_since_preview` 与（planned/current）digest 便于复核。
- `rejected`：无法唯一定位/不安全，必须重新 prepare。

## 两步模板（复制即用）

1. Prepare：

```text
按以下参数调用函数工具 `team_mgmt_prepare_file_range_edit`：
{ "path": "team.yaml", "range": "10~12", "content": "..." }
```

2. Apply（必须单独一轮）：

```text
按以下参数调用函数工具 `team_mgmt_apply_file_modification`：
{ "hunk_id": "<hunk_id>" }
```

## 创建空文件示例

```text
按以下参数调用函数工具 `team_mgmt_create_new_file`：
{ "path": "team/domains/new-domain.md", "content": "" }
```
