内容
1 align="Forge — 人类与智能代理的项目管理</h1>
<p align="center">
类似Linear的任务管理、冲刺、计划和时间跟踪 — 拥有<br>
一流的MCP界面，让LLM智能代理成为真正的参与者，而非事后补充。
</p>
<p align="center">
<a href="https://github.com/Codename-11/Forge/actions"><img src="https://img.shields.io/github/actions/workflow/status/Codename-11/Forge/ci.yml?branch=master&label=CI" alt="CI"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E=20-brightgreen" alt="Node ≥20"></a>
<a href="https://www.postgresql.org"><img src="https://img.shields.io/badge/postgres-16-336791" alt="Postgres 16"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/M+ 工具-63d2" altCP"></a>
</<p align="center">
href="./docs/">文档</a> ·
<a href="#快速开始">安装</a> ·
<a href="#智能代理与MCP">智能代理与MCP</a> ·
<a href="#快捷键">快捷键</a> ·
<a href="./DEVLOG.md">开发日志</a> ·
<a href="./TODO.md">路线图</a>
</p>
---
## 为什么选择Forge
大多数项目管理工具将自动化视为插件。Forge围绕以下理念构建：智能代理（如`victor`、`mizu`等LLM配置文件）一流的参与者它们拥有具有范围缩ApiKeys，通过Webhook接收工作推送，从队列中认领发出评论，并像人类一样运行时间记录。人类在UI上可以做的一切，智能代理都可以通过MCP做到。
结果是一个简约的、键盘驱动的界面（温暖的土色调，灵感来自Anthropic），感觉类似于Linear，在其下是一个插件层，允许您使用真正的基元组合智能代理、自动化和LLM循环，而不是Webhook配置拼接。
##
- **Next.js 15**路由器，服务器组件，类型化路由 **TypeScript**
- **PostgreSQL 16** + **Prisma 6** — 具有审计日志、事件流、指标汇总和迁移的规范化模式。
- **tRPC 11** 与 **Zod** — 用于Web UI的端到端类型安全API。
- **NextAuth v5** — 凭证 + OAuthHub / Google），Prisma适配器。
- **Redis** — 用于实时通信的发布/订阅，BullMQ队列，。
- **MinIO** （S3兼容）— 多态附件存储。
- **SSE** 用于浏览器实时通信 + **HMAC签名Webhook** 用于智能代理推送。
- **Tailwind CSS** 搭配温暖的土色调设计令牌系统。
- **Vitest** + **Playwright**；GitHub Actions用于CI。
## 基本元素
所有元素均作用于`workspaceId`。
| 基本元素 | 描述 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **工作空间** | 租短`key`（例如`AXI`、`PER`、`WR）是任务前缀，创建后不可Slug/名称可以自由更改。 |
项目** | 分组任务。可选地嵌套在计划 |
| **任务** | 工作单元。可选`projectId`，可选`cycleId`，可选人类指派，可选**智能代理**指派。 |
| **冲刺** | 有时间限制的迭代。默认长度来自`Workspace.cycleLengthDays`可以在冲刺中自由进出。内部存储为`Cycle`；路由（`/）和MCP命名空间（`cycles）保留原始名称以保持兼容性。 |
| **计划** | 项目的结构 — 季度押注、主题。 |
| **任务关系** | 有向的、类型的链接（`BLOCKS`、`BLOCKED_BY`、`DUPLICATES`、`RELATES_TO`）。 |
| **时间记录** | 每个用户针对任务的时长记录，由`Workspace.timeTrackingEnabled`控制。 |
| **附件** | 通过`targetType` + `targetId`实现多态；由MinIO支持。 |
| **智能代理** 一流的非人类参与者。`profileKey`（稳定句柄），`capabilities[]`，`webhookUrl`，`status`，`maxConcurrent`。通过Webhook接收调度；通过链接的ApiKey进行身份验证。 |
## 执行模型
Forge是执行层：批准的工作以任务、待办事项、冲刺、指派、阻塞和完成历史的形式存在。持久性笔记、原始捕获和私有决策日志可以保留在Forge之外；使用任务模板和待办事项来处理需要审查议工作。没有任何内容会自动提升到活跃的中。
默认任务模板涵盖开发任务、智能代理就绪、个人任务、财务跟进、支线任务和审查项目。智能代理就绪模板要求提供目标、系统区域、验收标准、安全边界和。共享家庭或特定于夫妻的工作流程被；目前，Forge仅提供通用工作空间/项目/模板基元。
## 智能代理与MCP
Forge在`/cp/rpc`（JSON-RPC 2.0）和`/api/mcp/:tool`（REST别名）处公开双MCP端点。44种工具涵盖每种基本元素：
```bash
# 列出所有工具
curl -s https.example.com/api/mcp/rpc \
-H "Authorization: Bearer $FORGE_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 作为此智能代理认领下一个排队的curl -s https://forge.example.com/api/mcp/rpc \
-H "Authorization: Bearer $FOR" \
-drpc":"2.0","id":2,"method":"tools/call",
":{"name":"issues.claim","arguments":{}}}'
当前分配给我的curl -s https://forge.example.com/api/mcp/rpc \
-H "Authorization: Bearer $FORGE_KEY" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"issues.assigned","arguments":{}}}'
```
密钥是可缩小的：opes`（粗粒度，是所属插件清单的子集可选的`projectIds` / `labelIds`initiativeIds`数组，以可以查看或操作的内容。每个计划的机器人仅获得该计划；完全信任的智能代理不会被缩小。
**自动调度。** 工作空间可以切换`autoDispatch`并选择一种模式（`ROUND_ROBIN` / `PRIORITY_MATCH` / `CAPABILITY_MATCH`）。排队的任务会自动路由到最佳匹配的智能代理，尊重`maxConcurrent`并触发带有完整决策的`AGIGNED`事件（荷调度。, candidates, chosen, reason} — 操作事件中重放智能代理被选中的哪些智能代理不合格）。
**调度规则** 在的选择之前运行。管理员在`/settings/dispatch-rules`(priority, labelIdId) → target规则；条件与null = 通配符结合使用个匹配项获胜（可排序）。匹配的目标不合格，则会落模式的选择，而不是停在事件原因上保留每个智能代理的任务模板。** 如果设置Agent.templateMarkdown`，则在赋值时（**仅当描述为空时**）将其应用于任务描述 — 智能代理永远不会覆盖人类内容。与赋值路径（自动、手动、重新赋值、初始指派）上的事务**心跳 +线。** 智能代理通过`agent.heartbeat以保持`lastHeartbeatAt`新鲜。BullMQ扫描（`maintenance，每60秒）将翻转为`OFF，当它们的 heartbeat 比.agentIdleTimeoutMinutes时，发出`AGENT_STATUS_CHANGED`。
**通知桥。** `pluginsbridge/`处的内置插件将可配置的`Event转发到Slack + Discord Webhooks，带有格式化的荷。每个工作空间Plugin.manifest.config`；支持`mentionsOnly`过滤和阻止嘈内部类型。
Hermes集成 — 通过单个配置智能代理：yaml
mcp_servers forge:
url: "https://forge.example.comcp/rpc"
Authorization: forge_sk_..."
timeout: 120
connect_timeout: 60
快速开始
```bash
cp .env.example # 填写值（变量已预填充为捆绑的MinIO；部署前轮换pnpm install
```
然后选择一种开发模式：
```bash
# A. 隔离的本地栈（推荐用于UI迭代）— 启动
# docker/docker-compose.yml（Postgres：55432 / Redis：56379 / MinIO
# :59000），迁移，播种丰富的数据，然后运行HMR开发。单个
# 命令，无需手动引导。登录：owner@forge.local / forge-dev。
pnpm dev:local # http://localhost:3000
pnpm dev:local --fresh # 先清除并重新播种本地数据库
pnpm dev:local --no-seed # 跳过播种（例如，在db:clone-prod之后）
# B. 实时数据 — HMR开发服务器指向**已部署**的Postgres / Redis
# / MinIO。针对真实数据的即时前端迭代；编辑是真实的。
pnpm dev # http://localhost:3000
# 可选：克隆已部署的数据库到本地栈中，用于具有真实数据的
# （完整的级副本；附件）。
pnpm db:clone-prod && pnpm dev --no-seed手动数据库引导（仅使用`dev:时需要）：
cd docker && up -d # Postgres + Redis + MinIO
prisma:generate
pnpm prisma:migrate 应用所有迁移
pnpm prisma:seed # 丰富的演示fixture（工作任务、
#、智能代理、关系）
pnpm # 可选的进程
```
在移动数据从** 管理 → 数据导出/导入**
（每工作空间的JSON可移植），或使用`pnpm db:clone-prod`进行完整复制。
```bash
# 文档（可选 — VitePress，在/docs/处提供服务）
pnpm docs:install # 一次性，docs/中的独立安装
pnpm docs:dev # http://localhost:5181/docs/
pnpm dev:all # 应用程序和文档在同一终端中
```
完整的用户文档位于`./docs/`中作为VitePress项目 — 概念、智能代理es / 调度 / SLA / AI）、自动化
（Webhook / 插件 / API密钥）和MCP、tRPC、事件和环境的参考。存储库公开后，`.github/workflows/docs.yml`
将站点部署到GitHub Pages。
## 快捷键
| 快捷键 | 操作 |
| ---------- | ----------------------------- |
| `⌘K` / `/` | 命令面板 |
| `⇧C` | 快速创建（路径感知） |
| `?` 快捷键帮助叠加层 |
| `⌘\` 折叠侧边栏 |
|` `I` 前往收件 |
| `G` `D` | 前往仪表盘 |
G` `S` | 前往任务 |
| `G` `P` | 前往项目 |
| `G` `C | 前往冲刺 |
| `G` `A` | 前往分析 |
| `G` `E` | 前往智能 |
| `⇧A` | 指代理（任务详情） |
完整表格位于`src/lib/shortcuts.ts`并由`?`叠加层渲染。
## 项目布局
```
src/
app/ # 应用路由器页面 + API路由处理程序
components/ # UI（侧边栏、顶部栏、模态基元、调色板）
lib/ # 实用trpc客户端、提供程序
/ # 数据库、Redis、身份验证、trpc路由器、服务
routers/ # 工作空间、项目、任务、周期、智能代理、 services/ # mcp、调度器-key-auth、存储（MinIO）
prisma/ # 模式 + 迁移 + 种子
plugins/ # 本地运行时插件处理程序（scripts/ # seed-agents等
docker/ # 开发组合（pg + redis +）
tests/ 单元（vitest）+ e2e（playwright）
```
##
- **自托管**（推荐）：` up -d`位于Traefik/C。入口点在运行`prisma migrate deploy`。提供`DATABASE_URL`、`REDIS_URL`、`AUTH_SECRET`、`PLUGIN_JWT_SECRET`、S3/MinIO凭证。
- **Vercel**：tRPC、身份验证、SSE和MCP路由兼容Node需要外部Postgres + Redis + S3。
## 许可证
MIT。
