# team_mgmt：管理 `.minds/`（direct edit）

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

## 总原则

- 增量编辑：单块编辑直接写入；行号范围用 `team_mgmt_file_range_edit`，末尾追加用 `team_mgmt_file_append`，锚点插入用 `team_mgmt_file_insert_after` / `team_mgmt_file_insert_before`，锚点块替换用 `team_mgmt_file_block_replace`。同一字面量多点批量替换优先用 `team_mgmt_prepare_occurrence_replace` 后接 `team_mgmt_apply_occurrence_replace`；若只选中单个 occurrence，prepare 会成功但返回 `notice: NOT_MULTI_OCCURRENCE`。这些编辑工具均支持内联 `content` 或 ws_mod `pad_id/pad_range` 来源。
- 若你承担团队管理职责，执行具体团队管理操作前，先查看 `man({ "toolsetId": "team_mgmt" })` 的相关章节，并按手册标准做法维护 `.minds/**` 团队心智资产。
- 并行约束：同一轮生成中的多个工具调用可能并行执行；同一文件写入会在工具侧串行化，但不要让同轮多个编辑依赖彼此未读到的结果。
- 例外（创建）：`team_mgmt_create_new_file` 只负责用 `content` 或 `pad_id/pad_range` 创建新文件（允许空内容）；若文件已存在会拒绝（避免误用覆盖写入语义）。
- 例外（整文件覆盖）：`team_mgmt_overwrite_entire_file` 会直接写入 `content` 或 `pad_id/pad_range`，必须提供 `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_create_new_file({ path, pad_id, pad_range })`
- 小改动（行号范围）：`team_mgmt_file_range_edit({ path, range, content })` 或 `team_mgmt_file_range_edit({ path, range, pad_id, pad_range })`
- 末尾追加：`team_mgmt_file_append({ path, content, create })`
- 锚点插入：`team_mgmt_file_insert_after|team_mgmt_file_insert_before({ path, anchor, content, occurrence, match })`
- 双锚点块替换：`team_mgmt_file_block_replace({ path, start_anchor, end_anchor, content, occurrence, include_anchors, match, require_unique, strict })`
- 批量字面量 occurrence 替换：`team_mgmt_prepare_occurrence_replace({ path, find, content|pad_id, occurrence_indexes? })` 后接 `team_mgmt_apply_occurrence_replace({ plan_id })`；设计目的偏向多点同字面量替换，单点会成功但返回 `notice: NOT_MULTI_OCCURRENCE`。
- 修改完 `.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" })` 收尾。

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

## 直接行号范围编辑模板（复制即用）

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

## 创建空文件示例

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