| name | project-mgr |
| description | 通过 repos.json 注册和管理工作区中的项目。 当用户想要接入项目、移除项目、注册项目提供的 skills、询问项目设置规范， 或消息中提到已注册项目名并需要定位 local_path 时使用。
|
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）补齐策略（不能为空）：
- 优先使用 Git 平台描述（GitHub/GHE，
gh repo view 或 API）。
- 若平台不可达或描述为空，回退读取
<local_path>/README.md：取首个 # 标题后第一段非空正文作为摘要。
- 若仍为空，使用简短占位描述：
<name> 项目仓库，并在回复中标注“建议后续人工完善”。
c. 确认
将自动发现的信息汇总后向用户确认，格式示例：
即将添加项目：
- 名称：bkmonitor
- 本地路径：/Users/xxx/bk-monitor/bkmonitor
- 远程仓库：https://github.com/TencentBlueKing/bk-monitor.git
- 默认分支：master
- 可见性：public
- 语言偏好：zh
是否确认？
用户确认后再执行写入操作。
d. 执行步骤
- 追加到
repos.json（或 private/repos.json）：
{
"name": "<name>",
"description": "<description>",
"git_url": "<git_url>",
"branch": "<branch>",
"local_path": "<local_path>",
"language": "<language>"
}
当执行“项目巡检/配置治理”时，允许对现有 registry 做 description 补齐（仅更新空描述字段，不改动其他字段）。
- 创建
knowledge/<name>/INDEX.md（或 private/knowledge/<name>/INDEX.md）
- 更新
knowledge/INDEX.md
0x02 删除项目
a. 输入参数
| 参数 | 必填 | 说明 |
|---|
| name | 是 | 项目名称 |
| visibility | 否 | public（默认） / private |
b. 执行步骤
- 从
repos.json 或 private/repos.json 中移除对应条目
- 询问用户是否删除
knowledge/<name>/（默认保留）
- 更新
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 根目录：
{
"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 时：
- 从
repos.json / private/repos.json 定位项目；未注册时先执行 0x01。
- 确认
dir 存在，并检查候选目录包含 SKILL.md。
- 汇总项目、registry、
dir 和选定 skills，向用户确认。
- 用户确认后写入项目的
skills 字段；不要在交互阶段创建符号链接。
- 提示用户执行
make skills-update 更新工作区挂载。
读取内外部项目依赖的 skill 绝对路径：
python3 .agents/skills/project-mgr/scripts/list_skills.py "$(pwd)"
脚本只读取配置并逐行输出绝对路径。符号链接由工作区 Makefile 管理。
