Proto Forge

ProtoForge——多代理编排器

TL；法学博士：入职和API参考（810+行）。 包含：架构图、代理表、快速启动、完整端点表、， WorkIQ集成指南，项目结构。 这是医生 第7页，共10页 按照阅读顺序。阅读 → 建筑.md 首先是定位。

文档地图——在哪里可以找到什么

推荐人类阅读顺序：

1. 此文件（README）——架构图、代理表、快速入门
2. ARCHITECTURE.md-紧凑模块图和API表面
3. BUILDING_AGENTS.md——AI Foundry实例实践教程
4. Guide2.md-审查、调整和维护清单
5. GUIDE.md——完整参考（使用ARCHITECTURE.md§10作为章节索引）

LLMs的推荐阅读顺序： 看见 .

基于 微软代理框架（Python） 带有声明性 forge/ 代理生态系统、MCP技能分布、上下文窗口管理、动态贡献和平台无关的LLM支持。

建筑

┌──────────────────────────────────────────────────────────────────┐
│                     HTTP Server (FastAPI)                         │
│  /chat  /chat/enriched  /mcp  /agents  /skills  /workflows       │
│  /workiq/*  /inspector                                           │
└──────────────────────────┬───────────────────────────────────────┘
                           │
            ┌──────────────▼──────────────┐
            │      WorkIQ Pre-Router      │ ← (optional enrichment)
            │  ┌──────────────────────┐   │
            │  │ Phase 0: workiq ask  │   │  Query M365 context
            │  │ Phase 1: HITL select │   │  User picks content
            │  │ Phase 2: extract kw  │   │  Keyword hints
            │  │ Phase 2b: HITL hints │   │  User accepts keywords
            │  └──────────┬───────────┘   │
            └─────────────┼───────────────┘
                          │  routing hints
                 ┌────────▼────────┐
                 │   Orchestrator   │ ← Intent Router (keyword + LLM)
                 │     Engine       │   + WorkIQ enrichment hints
                 └────────┬────────┘
                          │  ALWAYS first
                 ┌────────▼────────┐
                 │   Plan Agent    │ ← Top-level coordinator
                 │  (Coordinator)  │    Analyzes, strategizes,
                 │                 │    identifies sub-agents
                 └────────┬────────┘
                          │  HITL: user accepts plan suggestions
                 ┌────────▼────────┐
                 │  Sub-Plan Agent │ ← Resource planner
                 │  (Specialist)   │    Plans prerequisite infra
                 │                 │    "minimum viable resources"
                 └────────┬────────┘
                          │  HITL: user accepts resource plan
        ┌─────────┬───────┼───────┐
        ▼         ▼       ▼       ▼  (max 3 specialists)
   ┌──────────┐ ┌─────────┐ ┌─────────────────┐
   │   Log    │ │  Code   │ │   Remediation   │
   │ Analysis │ │Research │ └─────────────────┘
   └──────────┘ └─────────┘
        ▼              ▼              ▼
   ┌──────────┐ ┌──────────┐ ┌────────────────┐
   │Knowledge │ │  Data    │ │   Security     │
   │  Base    │ │ Analysis │ │   Sentinel     │
   └──────────┘ └──────────┘ └────────────────┘
                      │
                 ┌────▼───────┐
                 │  WorkIQ    │ ← M365 organisational context
                 │  (HITL)    │   2-phase human-in-the-loop
                 └────────────┘

   ─── Standard Flow (/chat) ──────────────────────────
   User Message
     → Intent Router (keyword + LLM)
       → Plan Agent (ALWAYS first — produces strategy)
         → HITL: user accepts plan suggestions & keywords
           → Sub-Plan Agent (resource deployment plan)
             → HITL: user accepts resources & brief
               → Task Agents (parallel fan-out, max 3 specialists)
                 → Aggregated Response
   ────────────────────────────────────────────────────

   ─── Enriched Flow (/chat/enriched) ─────────────────
   User Message
     → WorkIQ query (M365 context)
       → HITL Phase 1: user selects content sections
         → Keyword extraction from selected content
           → HITL Phase 2: user accepts/rejects keywords
             → Intent Router (keyword + hints + LLM)
               → Plan Agent → HITL → Sub-Plan → HITL
                 → Task Agents → Aggregated Response
   ────────────────────────────────────────────────────

┌─────────────────┐  ┌─────────────────┐  ┌──────────────────┐
│  Forge Loader   │  │  Context Budget  │  │  Contribution    │
│  (Agent YAML)   │  │  Manager         │  │  Manager (CRUD)  │
└─────────────────┘  └─────────────────┘  └──────────────────┘
┌─────────────────┐  ┌─────────────────┐  ┌──────────────────┐
│  MCP Server     │  │  Agent Catalog  │  │  Workflow Engine  │
│  (Skills Dist.) │  │  (Registry)     │  │  (Bundling)       │
└─────────────────┘  └─────────────────┘  └──────────────────┘

规划第一代理架构

这 计划代理 是最高级别的协调员。每个请求首先通过Plan Agent，即：

1. 分析请求范围并制定战略计划
2. HITL门：用户接受/拒绝计划建议和关键字
3. 子计划代理 计划先决条件资源（最低可行）
4. HITL门：用户接受/拒绝资源计划，可以覆盖简报
5. 任务代理并行执行，然后聚合结果

10名专业代理（1名协调员+9名分代理）

代理注册表/目录

这 代理目录 (src/registry/catalog.py)是跟踪所有可用代理、其功能、技能、健康指标和依赖关系的中央注册表。它支持运行时注册、搜索和指标跟踪。

通过目录管理子代理

from src.registry.catalog import AgentCatalog, AgentRegistration, CatalogEntry

catalog = AgentCatalog(storage_path=Path(".forge_catalog"))

# Register an agent
catalog.register_agent(AgentRegistration(
    agent_type="log_analysis",
    name="Log Analysis Agent",
    description="Expert in parsing and diagnosing application logs",
    version="1.0.0",
    skills=["analyze_logs"],
    tags=["logs", "errors", "debugging"],
))

# List all active agents
for agent in catalog.list_agents(status="active"):
    print(f"{agent.name} — {agent.description} (skills: {agent.skills})")

# Search agents by tag
security_agents = catalog.list_agents(tag="security")

# Track agent metrics (latency, errors)
catalog.update_agent_metrics("log_analysis", latency_ms=145.2, is_error=False)

# Unregister an agent
catalog.unregister_agent("my_old_agent")

技能目录

技能发现自 forge/ 在启动时自动填充到目录中。您还可以在运行时管理它们：

# Add a skill to the catalog
catalog.add_to_catalog(CatalogEntry(
    skill_name="analyze_dependencies",
    description="Analyze project dependencies for vulnerabilities",
    agent_type="security_sentinel",
    version="1.0.0",
    tags=["security", "dependencies"],
))

# Install / uninstall skills
catalog.install_skill("analyze_dependencies")
catalog.uninstall_skill("analyze_dependencies")

# Search the skill catalog
results = catalog.search_catalog(query="security", installed_only=True)

# Bulk-populate from ForgeLoader skills
catalog.populate_from_skills(forge_registry.skills)

目录的REST API

# List all registered agents with capabilities
GET /agents

# List all available skills
GET /skills

# Full system status including catalog stats
GET /health

目录持续存在 catalog.json 在磁盘上，并在启动时自动加载。

Forge生态系统

这 forge/ 目录是ProtoForge的声明核心——每个代理、提示、技能、工作流和上下文预算都在YAML和Markdown中定义，在启动时由 ForgeLoader.

Forge目录布局

forge/
├── _registry.yaml              # Master registry of all agents
├── _context_window.yaml        # Global token budget configuration
├── plan/                       # Plan Agent (coordinator)
│   ├── agent.yaml              #   Manifest: id, subagents, context_budget
│   ├── prompts/                #   System & strategy prompts (.md)
│   ├── skills/                 #   plan_task, identify_agents, build_strategy
│   ├── instructions/           #   routing_rules, coordination
│   └── workflows/              #   plan_and_execute.yaml
├── agents/                     # 9 agent directories (sub_plan + 8 specialists)
│   ├── sub_plan/               #   Sub-Plan Agent (resource planner + dual HITL)
│   ├── log_analysis/           #   agent.yaml + prompts/ + skills/ + instructions/
│   ├── code_research/
│   ├── remediation/
│   ├── knowledge_base/
│   ├── data_analysis/
│   ├── security_sentinel/
│   └── workiq/                 #   WorkIQ agent (M365 context + HITL selection)
├── shared/                     # Cross-agent resources
│   ├── prompts/                #   error_handling.md, output_format.md
│   ├── instructions/           #   quality_standards.md, security_baseline.md
│   └── workflows/              #   code_review.yaml, incident_response.yaml
└── contrib/                    # Dynamic contributions (CRUD via API)
    ├── audit_log.yaml          #   Timestamped audit trail
    ├── agents/                 #   Community-contributed agents
    ├── skills/                 #   Community-contributed skills
    └── workflows/              #   Community-contributed workflows

代理人清单(agent.yaml)

每个代理都由一个YAML清单完整描述：

id: plan_agent
name: Plan Agent
type: coordinator          # coordinator | specialist
description: >
  Top-level coordinator that analyzes every incoming request,
  produces a strategic execution plan, and identifies which
  specialist sub-agents should be invoked downstream.
version: "1.0.0"
context_budget:
  max_input_tokens: 24000
  max_output_tokens: 8000
  strategy: priority       # priority | sliding_window | summarize
subagents:
  - log_analysis
  - code_research
  - remediation
  - knowledge_base
  - data_analysis
  - security_sentinel
prompts:
  system: system.md
skills:
  - plan_task.yaml
  - identify_agents.yaml
  - build_strategy.yaml
instructions:
  - routing_rules.md
  - coordination.md

上下文窗口管理

代币预算集中配置在 forge/_context_window.yaml 并由 ContextBudgetManager 和 GovernanceGuardian:

• 全球预算： 每次编排运行128K个令牌-- 强制执行 （硬上限上调 ContextWindowExceededError)
• 每个代理的预算： 在每个 agent.yaml 优化信封（专家：默认15K/7K，协调员：默认24K/8K）
• 扇出盖： 每次运行最多3名专家（强制执行 _resolve_sub_agents())
• 预算执行： allocate() → fits_budget() → truncate() 连接到每一个 _dispatch() 呼叫
• 策略： priority （保持最高优先级内容）， sliding_window （保持最新）， summarize （LLM压缩）
• 令牌计数： 味觉令牌(cl100k_base)具有字符估计回退功能
• 最坏情况： 计划（32K）+子计划（20K）+前三名专家（25K+25K+22K）=124K\4项技能|⚠️ HITL已触发 --建议为溢出技能创建自定义子代理|

在清单加载时 GovernanceGuardian 验证每个代理的技能计数。如果超过，则生成 SkillSplitSuggestion 建议保留哪些技能，将哪些技能转移到新的子代理。人类可以接受、定制或覆盖。

支柱3——建筑原则执行

监护人审计显示了架构违规（例如，没有子代理的大额投入预算），并提出了建议。

执行点

上下文窗口分解流程

Orchestration run (128K budget)
  ├── Plan Agent           →  ~8K tokens
  ├── Sub-Plan Agent       →  ~5K tokens
  ├── Log Analysis         → ~15K tokens
  ├── Code Research        → ~20K tokens   ← cumulative: 48K ✅
  ├── Security Sentinel    → ~18K tokens   ← cumulative: 66K ✅
  ├── Knowledge Base       → ~30K tokens   ← cumulative: 96K ✅
  ├── Data Analysis        → ~25K tokens   ← cumulative: 121K ⚠️ WARNING!
  │   └─ GovernanceGuardian triggers HITL
  │   └─ Human accepts decomposition
  │   └─ Remaining work spawns sub-agent with fresh 128K context
  └── [Spawned sub-agent]  → fresh 128K window

动态贡献

这 ContributionManager 提供完整的CRUD操作，用于在运行时添加代理、技能和工作流：

from src.forge.contributions import ContributionManager

contrib = ContributionManager("forge")

# Create a new agent
contrib.create_agent("my_agent", manifest={...}, system_prompt="...", author="team-x")

# Add a skill
contrib.create_skill("my_skill", skill_def={...}, author="team-x")

# All changes are audit-logged in forge/contrib/audit_log.yaml

平台无关LLM支持

与任何LLM提供者合作：

违约： 克劳德作品4.6。还支持Codex 5.3和Gemini Pro 3.1作为一流的替代品。集 DEFAULT_LLM_PROVIDER 或者提供相关的API密钥。

快速开始

# 1. Clone and install
cd ProtoForge
pip install -e ".[dev]"

# 2. Configure
cp .env.example .env
# Edit .env with your credentials

# 2b. Azure AI Foundry (recommended) — requires Azure CLI
az login
# Set AZURE_AI_FOUNDRY_ENDPOINT in .env (e.g. https://your-resource.openai.azure.com/)
# Set AZURE_AI_FOUNDRY_MODEL (e.g. gpt-5.2-chat)
# Set AUTH_METHOD=azure_default

# 3. Run the server
protoforge serve
# → http://localhost:8080/inspector (Agent Inspector)

# 4. Or use interactive chat
protoforge chat

# 5. Check status
protoforge status

MCP集成

ProtoForge通过 模型上下文协议（MCP），使其可用于任何兼容MCP的AI客户端（VS Code Copilot、Claude Desktop等）。

技能是自动发现的 forge/ 创业时——每 skills/*.yaml 在代理目录中或 forge/shared/ 或 forge/contrib/ 作为MCP工具收集和暴露。

// POST /mcp
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

// Response: all agent skills as MCP tools

技能（由YAML定义）

技能位于每个代理的目录下 forge/:

# forge/plan/skills/plan_task.yaml
name: plan_task
description: "Break down a complex task into actionable steps"
agent_type: plan
parameters:
  - name: task_description
    type: string
    description: "The task to plan"
    required: true

工作流捆绑

根据YAML定义编写多代理工作流：

# forge/shared/workflows/incident_response.yaml
name: incident_response
description: "Full incident response: logs → code → security → diagnose → fix"
steps:
  - name: analyze_logs
    agent_type: log_analysis
    prompt_template: "Analyze logs for incident: {incident_description}"
  - name: research_code
    agent_type: code_research
    depends_on: [analyze_logs]
  - name: security_check
    agent_type: security_sentinel
    depends_on: [analyze_logs]
  - name: diagnose
    agent_type: knowledge_base
    depends_on: [research_code, security_check]
  - name: generate_fix
    agent_type: remediation
    depends_on: [diagnose]

没有依赖关系的步骤并行运行。工作流引擎自动处理依赖关系排序。

API终点

当 SERVER_REQUIRE_CONTROL_PLANE_API_KEY=true （默认），包括 X-API-Key 对于所有控制平面端点（例如： /mcp, /agents, /chat, /chat/status/{task_id}, /skills, /workflows, /workiq/*, /plan/*, /sub-plan/*, /github/*, /governance/*, /reviews/pending, /chat/enriched).公共端点仍然存在 /health 和 /inspector.

WorkIQ集成（两阶段人在环）

ProtoForge集成 工作智商 (@microsoft/workiq)将M365组织环境（电子邮件、团队消息、日历事件、SharePoint文档等）作为 预布线富集层 它将选定的关键字直接馈送到Intent Router中。

它是如何工作的——2阶段HITL浓缩

WorkIQ输出在影响路由之前流经两个人在回路门：

User query ("find the Teams discussion about the outage")
  → Phase 0: WorkIQ CLI (`workiq ask "..."`) — returns ranked sections
    → Phase 1 (HITL): user selects relevant content sections
      → Phase 2: extract routing keywords from selected content
        → Phase 2b (HITL): user accepts/rejects keyword hints
          → Phase 3: enriched Intent Router (message + accepted keywords)
            → Plan Agent → Sub-Agents → Aggregated Response

第一阶段——内容选择（HITL）

第一步——查询工作智商

curl -X POST http://localhost:8080/workiq/query \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "latest standup notes from Teams"}'

响应 --原始WorkIQ输出，a request_id，以及排名部分：

{
  "response": "Teams: Daily Standup ...",
  "request_id": "abc123",
  "sections": [
    {"index": 0, "preview": "Teams: Daily Standup ...", "source": "https://..."},
    {"index": 1, "preview": "Teams: Standup Recap ...", "source": "https://..."},
    {"index": 2, "preview": "Email: Standup Summary ...", "source": "https://..."}
  ],
  "pending_selections": [
    {
      "request_id": "abc123",
      "options": [
        {"index": 0, "preview": "...", "source": "https://..."},
        {"index": 1, "preview": "...", "source": "https://..."}
      ]
    }
  ]
}

第2步——查看待定部分并选择部分

# Check pending selections
curl -H "X-API-Key: $CONTROL_PLANE_API_KEY" http://localhost:8080/workiq/pending

# Select sections
curl -X POST http://localhost:8080/workiq/select \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "abc123", "selected_indices": [0, 1]}'

第2阶段——路由关键字接受（HITL）

在第一阶段之后，路由器从所选内容中提取关键字提示（例如“错误”→ 日志分析，“安全性”→ security_sentinel）。这些内容已浮出水面供用户查看：

第3步——复习关键字提示

curl -H "X-API-Key: $CONTROL_PLANE_API_KEY" http://localhost:8080/workiq/routing-hints

答复：

{
  "pending": [
    {
      "request_id": "hint-456",
      "hints": [
        {"index": 0, "agent_id": "log_analysis", "keyword": "error", "matched_text": "...deploy error in the auth..."},
        {"index": 1, "agent_id": "security_sentinel", "keyword": "security", "matched_text": "...security review needed..."}
      ]
    }
  ]
}

第4步——接受关键字提示

curl -X POST http://localhost:8080/workiq/accept-hints \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "hint-456", "accepted_indices": [0]}'

答复：

{
  "request_id": "hint-456",
  "accepted_hints": [{"agent_id": "log_analysis", "keyword": "error"}],
  "status": "resolved"
}

接受的关键字会提高相应代理在Intent Router中的得分，从而影响分派哪些子代理。

通过以下方式丰富路由 /chat/enriched

这 POST /chat/enriched 端点自动运行完整的两相管道：

curl -X POST http://localhost:8080/chat/enriched \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What did the team discuss about the production outage?"}'

这将触发阶段0→ 第一阶段（HITL）→ 第2阶段→ 第2b阶段（HITL）→ 第三阶段强化路线→ 计划代理→ 分代理→ 回应。如果WorkIQ未配置或出现故障，它将恢复到标准 /chat 管道。

先决条件

# Install Work IQ CLI globally
npm install -g @microsoft/workiq

# Accept the EULA (one-time)
workiq --acceptEula

# Verify
workiq --version

隐私与控制

• 2门HITL --用户明确控制内容部分和路由关键字
• 打开超时失败 （每个阶段2分钟）——如果无人值守，所有候选部分/提示都会自动接受，以保持管道运行
• 无持久存储 --所选内容仅存在于当前编排上下文中
• 审计友好 — pending_requests, pending_routing_hint_requests 暴露所有飞行状态

发展

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (485 tests, 12 files)
pytest

# Run live integration tests (requires az login + Azure endpoint)
pytest -m live -v

# Run only mocked tests (no Azure required)
pytest -m "not live"

# Run with coverage
pytest --cov=src

# Lint (ruff, line-length 120)
ruff check src/

# Type check
mypy src/

项目结构

ProtoForge/
├── pyproject.toml              # Project config & dependencies
├── GUIDE.md                    # Developer guide (architecture, extending, ADRs)
├── README.md                   # This file
├── forge/                      # ★ Declarative agent ecosystem
│   ├── _registry.yaml          #   Master agent registry
│   ├── _context_window.yaml    #   Token budget configuration
│   ├── plan/                   #   Plan Agent (coordinator)
│   │   ├── agent.yaml
│   │   ├── prompts/
│   │   ├── skills/
│   │   ├── instructions/
│   │   └── workflows/
│   ├── agents/                 #   9 agent directories (sub_plan + 8 specialists)
│   │   ├── sub_plan/
│   │   ├── log_analysis/
│   │   ├── code_research/
│   │   ├── remediation/
│   │   ├── knowledge_base/
│   │   ├── data_analysis/
│   │   ├── security_sentinel/
│   │   ├── github_tracker/     #   GitHub issue/PR tracking
│   │   └── workiq/             #   WorkIQ (M365 context + HITL)
│   ├── shared/                 #   Cross-agent prompts, instructions, workflows
│   │   ├── prompts/
│   │   ├── instructions/
│   │   └── workflows/
│   └── contrib/                #   Dynamic contributions (CRUD + audit)
│       ├── audit_log.yaml
│       └── README.md
├── src/
│   ├── main.py                 # Entry point & bootstrap
│   ├── config.py               # Settings (pydantic-settings + ForgeConfig)
│   ├── server.py               # FastAPI app factory + route wiring
│   ├── server_routes/          # Modular FastAPI route groups (37 endpoints)
│   ├── agents/                 # 10 agent types (8 dedicated files + GenericAgent handles 2)
│   │   ├── base.py             #   BaseAgent + BaseAgent.from_manifest()
│   │   ├── generic.py          #   GenericAgent (used by code_research & data_analysis)
│   │   ├── plan_agent.py
│   │   ├── sub_plan_agent.py   #   Sub-Plan Agent (resource planner + dual HITL)
│   │   ├── log_analysis_agent.py
│   │   ├── remediation_agent.py
│   │   ├── knowledge_base_agent.py
│   │   ├── security_sentinel_agent.py
│   │   ├── github_tracker_agent.py  #   GitHub Tracker (issues, PRs, milestones)
│   │   └── workiq_agent.py     #   WorkIQ agent (M365 2-phase HITL)
│   ├── forge/                  # ★ Forge runtime modules
│   │   ├── loader.py           #   ForgeLoader — discovers forge/ tree
│   │   ├── context_budget.py   #   ContextBudgetManager — token budgets
│   │   └── contributions.py    #   ContributionManager — CRUD + audit
│   ├── llm/                    # ★ LLM client (Azure AI Foundry + OpenAI)
│   │   ├── __init__.py         #   Exports LLMClient, get_llm_client
│   │   └── client.py           #   Async LLM client, singleton, multi-provider
│   ├── governance/             # ★ Always-on governance enforcement
│   │   ├── guardian.py         #   GovernanceGuardian — 3-pillar enforcement
│   │   └── selector.py         #   GovernanceSelector — HITL gates for violations
│   ├── orchestrator/           # Core orchestration engine
│   │   ├── engine.py           #   Plan-first dispatch + Sub-Plan pipeline
│   │   ├── router.py           #   Intent Router (keyword + LLM + enrichment)
│   │   ├── context.py          #   Shared conversation context
│   │   └── plan_selector.py    #   Dual HITL selector (Plan + Sub-Plan review)
│   ├── mcp/                    # MCP protocol server
│   │   ├── server.py           #   MCP request handler
│   │   ├── protocol.py         #   MCP message types
│   │   └── skills.py           #   YAML skill loader
│   ├── workiq/                 # WorkIQ integration (M365 context)
│   │   ├── client.py           #   Async subprocess wrapper for `workiq ask`
│   │   └── selector.py         #   2-phase HITL selector (content + keywords)
│   └── registry/               # ★ Agent Catalog & workflows
│       ├── catalog.py          #   AgentCatalog — registration, search, metrics
│       └── workflows.py        #   Workflow bundling & execution
└── tests/
    ├── test_copilot_customization.py  # 15 tests — budget math, identity, model enforcement
    ├── test_forge.py           # 36 tests — loader, context budget, contributions
    ├── test_github_tracker.py  # 82 tests — GitHub Tracker agent, all operations
    ├── test_governance.py      # 162 tests — guardian, selector, enforcement hooks
    ├── test_llm.py             # 30 tests — LLM client, all providers, degradation, agent paths
    ├── test_llm_live.py        # 13 tests — live Azure OpenAI integration (requires az login)
    ├── test_mcp.py             #  7 tests — protocol, server, skills
    ├── test_orchestrator.py    # 17 tests — engine, fan-out, aggregation
    ├── test_registry.py        # 11 tests — catalog, workflows
    ├── test_router.py          # 22 tests — keywords, enriched routing, hints
    ├── test_sub_plan.py        # 32 tests — sub-plan agent, plan selector, pipeline
    └── test_workiq.py          # 58 tests — client, selector, agent, enrichment

开发者指南

看 GUIDE.md 用于：

• 为什么选择这种架构（计划优先与扁平调度）
• Forge生态系统的深度（清单、上下文预算、贡献）
• 上下文窗口管理 --为什么代币预算很重要，128K上限是如何运作的，分解策略
• 治理守护者 --始终在线的三支柱实施（上下文窗口、技能上限、架构原则）
• 拆分任务：代理、技能和子代理 --决策矩阵与实用分解模式
• 子计划代理 --用于计划和资源审查的双HITL门，最小可行资源规划
• 如何扩展计划代理和子代理功能
• 如何通过代码或 forge/contrib/ 系统
• 添加新技能、工作流程和共享资源
• WorkIQ集成 -两阶段HITL丰富管道、路由关键字接受、REST API使用
• 代理注册表/目录 --管理子代理、技能目录、健康指标、持久性
• 如何添加预路由器扩展源 --添加通话记录、Jira、Slack等的分步指南。 (§19)
• 使用GitHub Copilot CLI进行多模型代码审查 --并行运行Claude Opus 4.6、Codex 5.3和Gemini Pro 3.1以获得关键反馈
• 架构决策记录（ADR）

下一个工程师快速入门

如果你是第一次使用这个代码库，那么从这里开始。

在哪里改进编排器

如何更改/添加子代理

1. 添加代理：创建 forge/agents// 随着 agent.yaml, prompts/system.md, skills/, instructions/
2. 注册路由：将关键字模式添加到 _BUILTIN_KEYWORD_ROUTES 在 router.py，添加 AgentType 枚举成员
3. 在bootstrap中注册：将条目添加到 _SPECIALISED_CLASSES 在 main.py （或使用 GenericAgent 仅适用于YAML代理）
4. 添加测试：创建 tests/test_.py
5. 完整演练：参见 建筑_建筑.md --规范的分步教程

如何添加预路由器富集源

WorkIQ管道(src/workiq/)是参考实现。要添加 新的丰富来源（例如，通话记录、Jira、Slack）：

1. 创建客户端(src//client.py)获取外部数据
2. 创建选择器(src//selector.py)使用HITL准备/解决模式
3. 电线接入 engine.py → process_with_enrichment() 或 _enrich_routing()
4. 在中添加REST端点 server.py
5. 完整步骤：请参阅 指南md第19条