pipeline_core/docs/agent-architecture.md

pipeline-core Agent 架构设计：可插拔产线能力 + 对齐 Hermes CLI

目标：pipeline-core 是产线无关的通用 agent 内核，产线能力（工具+prompt+handler） 以「能力包」形式可插拔注册；agent 可多实例，实例间能力按产线隔离。 通过 gateway 服务层 + bricks 适配，在 Web 界面用 AgentIO 提供与 Hermes CLI 相同的交互。

1. 核心原则

1. core 产线无关：pipeline-core 只提供通用 agent 内核，不含任何具体产线（SDLC/KTV/...）的能力。
2. 能力可插拔：产线能力 = PipelineAbility（工具定义 + prompt 片段 + handler），独立注册。
3. 多实例能力隔离：AgentExecutor 按 pipeline_id 从注册表挂载能力，A 产线 agent 与 B 产线 agent 工具集不同。

2. 分层架构

┌────────────────────────────────────────────────────────────┐
│ L4 交互层   pipeline-sdlc / bricks                          │
│   AgentIO + slash 命令菜单 + 流式工具预览 + 会话列表          │
├────────────────────────────────────────────────────────────┤
│ L3 Gateway 层 pipeline-core / pipeline-service              │
│   常驻服务 + 会话生命周期 + 通道抽象（Web AgentIO 为第一通道）│
├────────────────────────────────────────────────────────────┤
│ L2 执行引擎 pipeline-service AgentExecutor                  │
│   多轮工具循环 + native function calling + 上下文压缩         │
│   _execute_tool: registry → ability(按pipeline_id) → 通用   │
├────────────────────────────────────────────────────────────┤
│ L1 能力定义 pipeline-core                                   │
│   GENERAL_TOOLS（通用工具） + DEFAULT_AGENT_CONFIG（通用心智）│
│   PipelineAbility 注册表 + ToolRegistry + Skill + Memory     │
└────────────────────────────────────────────────────────────┘

3. 能力包模型（PipelineAbility）

# pipeline_core/ability.py
@dataclass
class PipelineAbility:
    pipeline_id: str                     # 产线标识（对应 pipelines 表 id）
    name: str                            # 产线名称
    tools: List[ToolDefinition]          # 产线专属工具定义
    system_prompt: str                   # 产线专属 prompt 片段
    handlers: Dict[str, Callable]        # {tool_name: async handler(sor, params, ctx)}

register_ability(ability)   # 注册（幂等）
get_ability(pipeline_id)    # 按产线取能力包

• handler 签名统一：async def handler(sor, params, ctx) -> str，ctx = {project_id, user_id, workspace_dir, model_name, config}。
• 依赖方向：pipeline-core（纯定义+注册表）← pipeline-service（sdlc_ability 注册 SDLC 能力）。
• 扩展 B 产线：新增 b_ability.py + register_ability(...)，零侵入 core / AgentExecutor。

4. 完整可插拔维度（能力栈）

每个维度遵循「通用 → 产线 → 角色 → 会话」四级加载（高覆盖低）：

维度	通用(core)	产线(pipeline)	角色(role)	会话/项目	状态
工具 Tools	GENERAL_TOOLS	PipelineAbility.tools	角色工具白名单	临时工具	✅ 通用+产线
技能 Skills	global/	pipelines/{id}/common	pipelines/{id}/roles/{role}	projects/{id}	✅ 六级
slash 命令	/help /status /reset /model /tools /skills	/tasks /diagnose	—	—	✅ 通用+产线
角色 Roles	—	产线定义角色集	角色=工具子集+技能+prompt+模型	—	⏳ 设计定待实现
prompt 片段	通用心智	产线 prompt	角色 prompt	—	✅ 通用+产线
记忆 Memory	通用记忆	产线记忆	—	项目记忆	⏳ 待分域
模型配置	默认	default_model	角色模型	会话覆盖	⚠️ 部分
子代理定义	通用委派	产线子代理形态	角色子代理	—	⏳ delegate 空壳
工作流 step	—	pipeline_register_step_type	—	—	✅ 已可插拔
压缩/隔离策略	默认 config	产线覆盖	—	—	✅ 已有

5. 已落地 vs 待办

项	状态
core 剥离 SDLC（GENERAL_TOOLS + DEFAULT_AGENT_CONFIG）	✅
PipelineAbility 注册表 + 动态挂载 + 多实例隔离	✅
sdlc_ability.py（SDLC 能力包：14 工具+prompt+handler）	✅
技能六级隔离（global/org/pipeline/role/project/user）	✅
slash 命令注册表（通用 6 + SDLC 产线 2）	✅
诚实降级 / 能力自省 / ask_user	✅
通用工具集（terminal/file/search/session/todo/delegate）	✅
角色定义可插拔（RoleSpec）	⏳ 设计定，实现待做
记忆分域（通用/产线/项目）	⏳ 待做
阶段3：gateway 服务层	⏳ 待做

6. 安全约束

• terminal/file 工具必须在 workspace 目录内操作（_resolve_ws_path 越界拦截 + _ALLOWED_WORKDIRS 白名单）
• 危险命令（rm -rf 等）需确认（requires_confirmation）
• 陌生用户入口（Wterm 等）沙箱化 + 最小权限

7. 验证标准

每个阶段完成后：浏览器端到端实测 agent 完整交互流程，不靠声称通过。