project-mgr

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）补齐策略（不能为空）：
  1. 优先使用 Git 平台描述（GitHub/GHE，gh repo view 或 API）。
  2. 若平台不可达或描述为空，回退读取 <local_path>/README.md：取首个 # 标题后第一段非空正文作为摘要。
  3. 若仍为空，使用简短占位描述：<name> 项目仓库，并在回复中标注“建议后续人工完善”。

c. 确认

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

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

是否确认？

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

d. 执行步骤

1. 追加到 repos.json（或 private/repos.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 根目录：

{
  "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 绝对路径：

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

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