Dev Hub — 轻量级个人项目监控面板

Dev Hub 是一个本地优先、只读的个人开发项目总览页。它把分散在电脑上的智能体、工具和其他项目汇总到一个中文网页中，展示项目入口、Git 状态和明确配置的健康检查结果。

它适合个人开发者管理多个本地项目，但不负责执行任意命令，也不取代各项目自己的管理后台、进程管理器或完整可观测性平台。

主要能力

• 从指定目录发现一级子目录作为候选项，不自动纳管。
• 使用兼容 GitWildMatch 的 .devhubignore 排除目录。
• 使用 config.yaml 中的保护目录阻止扫描和注册敏感路径。
• 通过 .dev-hub.yml 或命令行显式注册项目；同时兼容 .dev-hub.yaml 扩展名。
• 展示项目入口、Git 分支、未提交文件数量及健康状态。
• 只根据显式配置的 TCP/HTTP 检查判断在线状态；未配置时显示"未监控"。
• 健康检查只允许回环地址（127.0.0.1 / localhost / ::1）；外部地址返回"已阻止远程检查"。
• 注册表写入使用单写者锁（Windows 使用 msvcrt，POSIX 使用 fcntl），并追加不含原始路径的审计事件。
• 网页仅允许绑定回环地址，且拒绝所有 POST 请求。
• 设置加载后由 Pydantic v2 全量验证；JSON Schema（schemas/project-v1.schema.json）仅提供编辑器提示，不替代运行时校验。

快速开始

需要 Python 3.13.x（不兼容 3.14+）和 uv。在 PowerShell 中执行：

git clone https://github.com/caozuohua/dev-hub.git
Set-Location .\dev-hub

Copy-Item config.example.yaml config.yaml
Copy-Item .devhubignore.example .devhubignore
Copy-Item registry\projects.example.yaml registry\projects.yaml

uv sync --extra dev
uv run dev-hub validate
uv run dev-hub discover --json

打开 config.yaml，把 scan_roots 改成项目父目录，把不允许扫描的目录加入 safety.protected_roots。本机配置和项目注册表默认不会提交到 Git。

启动本地网页：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_dev_hub.ps1

然后访问 http://127.0.0.1:8790/。在启动终端按 Ctrl+C 即可停止。

也可以直接运行 serve 命令（默认自动打开浏览器）：

uv run dev-hub serve

若不希望自动打开浏览器，使用 --no-open；若需要覆盖绑定地址或端口，使用 --host 和 --port（只允许回环地址）：

uv run dev-hub serve --no-open
uv run dev-hub serve --port 9000

纳管项目

推荐在待纳管项目根目录添加 .dev-hub.yml（或 .dev-hub.yaml）：

version: 1
id: example-agent
category: agent
visibility: private
level: L1
links:
  dashboard: http://127.0.0.1:8900/
  documentation: docs/README.md
health:
  type: tcp
  host: 127.0.0.1
  port: 8900
runtime:
  type: manual

卡片标题默认使用文件夹名。只有需要覆盖显示名称时才添加 name；description 也是可选字段，未配置时保持空白：

name: 智能体实验室
description: 本机智能体实验项目。

字段说明

字段	必填	说明
version	是	固定为 1
id	是	小写字母、数字和连字符，不能以连字符开头
category	是	自由文本，建议使用内置分类（见下文）
visibility	是	private 或 public
level	否	L0–L3，默认 L0
name	否	显示名称，最长 80 字符；未填时使用文件夹名
description	否	摘要，最长 240 字符
links	否	homepage / dashboard / documentation / repository
health	否	健康检查配置（见下文）
runtime	否	运行时信息（见下文）

内置分类：agent（智能体）、knowledge（知识工具）、platform（平台）、portfolio（作品）、tool（工具）、data（数据）、web（网页）、other（其他）。

健康检查配置

health.type 支持三个值：

• none（默认）：不检查，网页显示"未监控"。
• tcp：检查 TCP 连接，需同时填写 host 和 port。
• http：发送 GET 请求，需填写 url（HTTP 状态码 < 400 视为在线）。

所有检查目标必须是回环地址（127.0.0.1、localhost、::1）；非回环地址会被阻止并在网页显示"已阻止远程检查"。

# TCP 示例
health:
  type: tcp
  host: 127.0.0.1
  port: 8900
  timeout_seconds: 3   # 可选，默认 3，最大 30

# HTTP 示例
health:
  type: http
  url: http://127.0.0.1:8900/healthz

运行时配置

runtime.type 支持：none（默认）、manual、scheduled-task、docker、remote、static。当前网页仅展示此信息，不执行任何生命周期操作。

runtime:
  type: manual
  name: 可选的运行时标签

显式注册命令

# 读取清单文件注册（优先）
uv run dev-hub add D:\Projects\example-agent --json

# 无清单文件时，手动指定分类（创建 L0 条目）
uv run dev-hub add D:\Projects\example-tool --category tool --json

# 覆盖 id 或显示名称
uv run dev-hub add D:\Projects\example-tool --id my-tool --name "我的工具" --json

发现功能只生成候选项，永远不会自动注册或执行项目。

排除与安全模型

.devhubignore 使用 GitWildMatch 语法，例如：

*-backups/
*.worktrees/
large-generated-project/
!safe-example-backups/

否定规则可以重新包含普通排除项，但无法覆盖 safety.protected_roots。扫描器只查看一级目录名称和少量项目标记路径，不索引项目文件内容。

项目清单和行为配置中禁止保存凭据、令牌、Cookie 或授权头。未来集成如需凭据，只能放在 .env 中，且网页不得返回这些内容。

配置参考

config.yaml 的完整可配置字段（括号内为默认值）：

version: 1
scan_roots:
  - D:/Projects              # 扫描根目录，可填多个

paths:
  registry: registry/projects.yaml   # 注册表文件
  ignore: .devhubignore              # 忽略规则文件
  audit: data/audit.jsonl            # 审计日志
  writer_lock: data/registry         # 写者锁文件前缀

discovery:
  max_depth: 1                       # 固定为 1，仅扫描一级子目录
  manifest_name: .dev-hub.yml        # 清单文件名

web:
  host: 127.0.0.1                    # 绑定地址（只允许回环）
  port: 8790                         # 监听端口
  refresh_seconds: 15                # 前端自动刷新间隔（5–300）

safety:
  protected_roots:
    - D:/PrivateData                 # 禁止扫描和注册的目录

git:
  timeout_seconds: 3                 # git 命令超时（1–30）

可通过 DEV_HUB_CONFIG 环境变量指定配置文件路径（默认为当前目录下的 config.yaml）：

$env:DEV_HUB_CONFIG = "D:\config\dev-hub.yaml"
uv run dev-hub serve

常用命令

uv run dev-hub list --json               # 列出已注册项目
uv run dev-hub discover --json           # 列出发现的候选项
uv run dev-hub validate --json           # 校验注册表（输出 valid/missing_paths/protected_paths）
uv run dev-hub add PATH --category agent --json   # 注册项目
uv run dev-hub serve                     # 启动网页（自动打开浏览器）
uv run dev-hub serve --no-open           # 启动网页（不打开浏览器）

Web API

服务启动后，以下端点可用（均只接受 GET，仅限回环访问）：

路径	说明
GET /	主页面 HTML
GET /api/projects	已注册项目及实时健康/Git 状态
GET /api/discovery	尚未注册的候选项
GET /api/healthz	服务自身健康检查，返回 {"status":"ok","mode":"read-only"}

项目成熟度

• L0：项目目录和 Git 元数据。
• L1：增加 HTTP 或 TCP 健康检查。
• L2：预留给经过审计、列入白名单的生命周期适配器。
• L3：项目自带详细运维控制台。

当前网页刻意保持只读，尚不提供项目启动、停止或任意命令执行能力。

开发检查

uv run ruff check .
uv run mypy src
uv run pytest -q
uv run dev-hub validate --json

或使用一键检查脚本（等同于以上四条命令）：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\check.ps1

许可证

MIT