# Project Mgr

> 通过 repos.json 注册和管理工作区中的项目。 当用户想要接入项目、移除项目、注册项目提供的 skills、询问项目设置规范， 或消息中提到已注册项目名并需要定位 local_path 时使用。

- Skill: `zhuozhuocrayon/project-mgr` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zhuozhuocrayon/project-mgr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuozhuocrayon/project-mgr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhuozhuocrayon (https://skillmd.com/u/zhuozhuocrayon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuozhuocrayon/project-mgr

---


# project-mgr — 项目管理

管理工作区中项目的添加、删除和定位，默认 visibility 为 `public`。

项目通过 `repos.json` / `private/repos.json` 注册，`local_path` 记录本地仓库绝对路径，模型可通过该路径 `cd` 到项目目录进行开发。

## 0x01 添加项目

### a. 输入参数

| 参数         | 必填 | 说明                                                          |
|------------|----|-------------------------------------------------------------|
| local_path | 是  | 本地路径（仓库根目录或大仓子目录均可）                                         |
| visibility | 否  | public（默认） / private                                        |
| name       | 否  | 项目名称覆盖（默认从 `local_path` 的 basename 推断）                      |
| language   | 否  | 项目语言偏好：`zh`（默认） / `en`，影响 PR review 评论、commit message 等交互语言 |

### b. 自动发现

先 `cd` 到 `local_path`，再**逐条**执行以下 Git 命令采集信息（Git 在子目录中会自动向上查找 `.git`）：

| 信息     | 命令                                                                    | 说明                                       |
|--------|-----------------------------------------------------------------------|------------------------------------------|
| 远程仓库地址 | `git remote -v`                                                       | 优先取 `upstream`（fetch），其次 `origin`（fetch） |
| 默认分支   | `git symbolic-ref refs/remotes/<remote>/HEAD 2>/dev/null`             | 失败则回退检测 `master` / `main` 分支是否存在         |
| 仓库描述   | `gh repo view <owner>/<repo> --json description -q .description`（可用时） | GH 描述优先，不可用时回退本地 `README.md` 首段摘要        |

推断规则：

- **local_path**：直接使用用户提供的路径，不回退到仓库根目录（大仓场景下用户只关心子目录）
- **项目名称**：取 `local_path` 的 basename（如 `/path/bk-monitor/bkmonitor` → `bkmonitor`），用户可通过 `name` 参数覆盖
- **远程仓库地址**：含 token 或凭据时先**剔除凭据**，统一格式化为 `https://github.com/<owner>/<repo>.git` 记录
- **仓库描述（description）补齐策略**（不能为空）：
  1. 优先使用 Git 平台描述（GitHub/GHE，`gh repo view` 或 API）。
  2. 若平台不可达或描述为空，回退读取 `<local_path>/README.md`：取首个 `#` 标题后第一段非空正文作为摘要。
  3. 若仍为空，使用简短占位描述：`<name> 项目仓库`，并在回复中标注“建议后续人工完善”。

### c. 确认

将自动发现的信息汇总后向用户确认，格式示例：

```text
即将添加项目：
- 名称：bkmonitor
- 本地路径：/Users/xxx/bk-monitor/bkmonitor
- 远程仓库：https://github.com/TencentBlueKing/bk-monitor.git
- 默认分支：master
- 可见性：public
- 语言偏好：zh

是否确认？
```

用户确认后再执行写入操作。

### d. 执行步骤

1. 追加到 `repos.json`（或 `private/repos.json`）：

```json
{
  "name": "<name>",
  "description": "<description>",
  "git_url": "<git_url>",
  "branch": "<branch>",
  "local_path": "<local_path>",
  "language": "<language>"
}
```

> 当执行“项目巡检/配置治理”时，允许对现有 registry 做 description 补齐（仅更新空描述字段，不改动其他字段）。

2. 创建 `knowledge/<name>/INDEX.md`（或 `private/knowledge/<name>/INDEX.md`）
3. 更新 `knowledge/INDEX.md`

## 0x02 删除项目

### a. 输入参数

| 参数         | 必填 | 说明                   |
|------------|----|----------------------|
| name       | 是  | 项目名称                 |
| visibility | 否  | public（默认） / private |

### b. 执行步骤

1. 从 `repos.json` 或 `private/repos.json` 中移除对应条目
2. 询问用户是否删除 `knowledge/<name>/`（默认保留）
3. 更新 `knowledge/INDEX.md`

## 0x03 使用项目

模型在处理项目相关任务时：

1）从 `repos.json` / `private/repos.json` 读取 `local_path`、`language`。

* `local_path` 使模型能直接访问项目源码，`knowledge/<name>/` 提供项目级知识，两者结合即可完成项目任务。
* **【CRITICAL（必须执行不可协商）】** `language`：
  - 对话：以工作区项目配置的 language 字段为准，默认中文。
  - 其他（如代码注释、文档、PR review 等）：以目标项目配置的 `language` 字段为准，默认中文。

2）通过 `cd <local_path>` 切换到项目目录，阅读项目级别规范（如 `CONTRIBUTING.md`、`README.md`、`AGENTS.md` 等）。

3）加载 `knowledge/<name>/` 下的项目知识库作为上下文，**按需**进行检索和写入。

## 0x04 项目 Skills 管理

项目可以在注册信息中声明需要挂载到工作区的 skills。`skills` 是项目级数组，每项对应项目内的一个 skill 根目录：

```json
{
  "name": "ai-docs",
  "local_path": "/Users/xxx/ai-docs",
  "skills": [
    {
      "dir": "apm-rum/skills",
      "skills": ["kube-switch"]
    }
  ]
}
```

字段规则：

- `skills[].dir` 必填，使用相对 `local_path` 的目录路径。
- `skills[].skills` 选填。填写时只加载列出的 skill；省略或使用空数组时扫描 `dir` 的直接子目录，加载包含 `SKILL.md` 的目录。
- 同一个项目可配置多个 skill 根目录。

用户要求注册项目 skills 时：

1. 从 `repos.json` / `private/repos.json` 定位项目；未注册时先执行 `0x01`。
2. 确认 `dir` 存在，并检查候选目录包含 `SKILL.md`。
3. 汇总项目、registry、`dir` 和选定 skills，向用户确认。
4. 用户确认后写入项目的 `skills` 字段；不要在交互阶段创建符号链接。
5. 提示用户执行 `make skills-update` 更新工作区挂载。

读取内外部项目依赖的 skill 绝对路径：

```bash
python3 .agents/skills/project-mgr/scripts/list_skills.py "$(pwd)"
```

脚本只读取配置并逐行输出绝对路径。符号链接由工作区 `Makefile` 管理。