diff --git a/docs/agent-architecture.md b/docs/agent-architecture.md
index 2426aaa..d0dd8c2 100644
--- a/docs/agent-architecture.md
+++ b/docs/agent-architecture.md
@@ -1,22 +1,16 @@
-# pipeline-core Agent 架构设计：对齐 Hermes CLI 能力
+# pipeline-core Agent 架构设计：可插拔产线能力 + 对齐 Hermes CLI
 
-> 目标：让 pipeline-core 的 agent 达到 Hermes CLI 的能力水平，通过 gateway 服务层 + bricks 适配，
-> 在 Web 界面用 AgentIO 提供与 Hermes CLI 相同的交互体验。
+> 目标：pipeline-core 是产线无关的通用 agent 内核，产线能力（工具+prompt+handler）
+> 以「能力包」形式可插拔注册；agent 可多实例，实例间能力按产线隔离。
+> 通过 gateway 服务层 + bricks 适配，在 Web 界面用 AgentIO 提供与 Hermes CLI 相同的交互。
 
-## 1. 现状盘点
+## 1. 核心原则
 
-pipeline-core 已有"对照 Hermes 重构"的骨架：
+1. **core 产线无关**：pipeline-core 只提供通用 agent 内核，不含任何具体产线（SDLC/KTV/...）的能力。
+2. **能力可插拔**：产线能力 = PipelineAbility（工具定义 + prompt 片段 + handler），独立注册。
+3. **多实例能力隔离**：AgentExecutor 按 pipeline_id 从注册表挂载能力，A 产线 agent 与 B 产线 agent 工具集不同。
 
-| 层 | 现状 | 位置 |
-|----|------|------|
-| 能力定义 | AgentConfig / ToolDefinition / CompressionConfig / MemoryConfig / SkillConfig | pipeline_core/agent_config.py |
-| 工具注册 | ToolRegistry / register_tool / to_openai_schema | pipeline_core/tool_registry.py |
-| 技能系统 | SkillLoader 三级隔离（global/orgs/users） | pipeline_core/skill_loader.py |
-| 记忆系统 | MemoryStore（MySQL pipeline_user_memory + 缓存） | pipeline_core/memory_store.py |
-| 执行引擎 | AgentExecutor（多轮 tool-loop + native function calling） | pipeline_service/agent_loop_v2.py |
-| 通用工具底层 | _run_shell / _write_code_file / _git_* （仅角色 agent 用） | pipeline_service/agent_loop.py |
-
-## 2. 目标架构（四层）
+## 2. 分层架构
 
 ```
 ┌────────────────────────────────────────────────────────────┐
@@ -28,57 +22,64 @@ pipeline-core 已有"对照 Hermes 重构"的骨架：
 ├────────────────────────────────────────────────────────────┤
 │ L2 执行引擎 pipeline-service AgentExecutor                  │
 │   多轮工具循环 + native function calling + 上下文压缩         │
+│   _execute_tool: registry → ability(按pipeline_id) → 通用   │
 ├────────────────────────────────────────────────────────────┤
 │ L1 能力定义 pipeline-core                                   │
-│   AgentConfig + ToolRegistry + SkillLoader + MemoryStore    │
-│   + 通用工具集（terminal/file/session_search/delegation/     │
-│     clarify/todo）                                          │
+│   GENERAL_TOOLS（通用工具） + DEFAULT_AGENT_CONFIG（通用心智）│
+│   PipelineAbility 注册表 + ToolRegistry + Skill + Memory     │
 └────────────────────────────────────────────────────────────┘
 ```
 
-## 3. 差距分析
+## 3. 能力包模型（PipelineAbility）
 
-| 能力 | Hermes CLI | pipeline 现状 | 缺口 |
-|------|-----------|--------------|------|
-| 多轮工具循环 | ✅ | ✅ AgentExecutor | 无 |
-| 记忆 / 技能 | ✅ | ✅ 雏形 | 无 |
-| 诚实降级 / 澄清 | ✅ | ✅（已修） | 无 |
-| 文件工具 read/write/list/search | ✅ | 仅角色 agent 有 | cockpit 缺 |
-| shell 执行 | ✅ terminal | ✅ _run_shell（run_command 已接） | 需增强 |
-| 会话搜索 | ✅ session_search | ❌ | 缺 |
-| 子代理委派 | ✅ delegate_task | delegate_subtask 只有壳 | 缺实现 |
-| 任务规划 | ✅ todo | ❌ | 缺 |
-| slash 命令 | ✅ 40+ 个 | ❌ | 缺 |
-| gateway 层 | ✅ 多平台 | ❌ 只有 Web | 缺 |
-| 流式 + 工具预览 + 文件上传 + 模型选择 | ✅ | ✅ 部分 | 需打磨 |
+```python
+# 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)}
 
-## 4. 分阶段计划
+register_ability(ability)   # 注册（幂等）
+get_ability(pipeline_id)    # 按产线取能力包
+```
 
-### 阶段1：通用工具集（让 agent 能"干活"）
-新增工具（cockpit AgentExecutor 暴露）：
-- `read_file` / `write_file` / `list_files` / `search_files` —— 复用 agent_loop.py 底层，加 workspace 沙箱限制
-- `run_command` —— 已有，增强（超时/输出截断已具备）
-- `session_search` —— 搜 pipeline_conversations 表
-- `delegate_subtask` —— 真正实现：spawn 子 AgentExecutor 独立执行
-- `ask_user` —— 已修好（合法终止动作）
-- `todo` —— 会话内任务列表（内存态）
+- **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。
 
-交付物：pipeline-core 新增 GENERAL_TOOLS 定义 + pipeline-service 实现 handler。
+## 4. 通用工具 vs 产线工具
 
-### 阶段2：slash 命令 + AgentIO 交互对齐
-- 后端：解析 /new /model /tools /skills /status /reset 等 slash 命令
-- 前端：AgentIO 支持 slash 命令 + 工具调用过程完整展示 + 会话列表
+**GENERAL_TOOLS（core 内核，任何产线 agent 都有，11 个）**：
+switch_project / create_project / run_command / ask_user / delegate_subtask /
+read_file / write_file / list_files / search_files / session_search / todo
 
-### 阶段3：gateway 服务层
-- 常驻服务抽象 + 会话生命周期管理 + 通道抽象
-- 第一通道 = Web AgentIO（bricks），预留多通道接口
+**SDLC 能力包（pipeline_service/sdlc_ability.py，14 个）**：
+create_task / list_tasks / task_detail / start_agents / diagnose_project /
+list_deliverables / view_deliverable / list_questions / answer_question /
+add_repo / list_repos / clone_repo / check_progress / add_bug
 
-## 5. 安全约束（贯穿所有阶段）
+## 5. 已落地 vs 待办
 
-- terminal/file 工具必须在 workspace 目录内操作（`_is_safe_workdir` 白名单）
-- 陌生用户入口（Wterm 等）必须沙箱化 + 最小权限
+| 项 | 状态 |
+|----|------|
+| core 剥离 SDLC（GENERAL_TOOLS + DEFAULT_AGENT_CONFIG） | ✅ 已落地 |
+| PipelineAbility 注册表 + 动态挂载 | ✅ 已落地 |
+| sdlc_ability.py（SDLC 能力包） | ✅ 已落地 |
+| AgentExecutor 按 pipeline_id 挂载（多实例隔离） | ✅ 已落地 |
+| 诚实降级 / 能力自省 / ask_user | ✅ 已落地 |
+| 通用工具集（terminal/file/search/session/todo/delegate） | ✅ 已落地 |
+| 阶段2：slash 命令 + AgentIO 交互对齐 | ⏳ 待办 |
+| 阶段3：gateway 服务层（会话生命周期 + 通道抽象） | ⏳ 待办 |
+
+## 6. 安全约束
+
+- terminal/file 工具必须在 workspace 目录内操作（`_resolve_ws_path` 越界拦截 + `_ALLOWED_WORKDIRS` 白名单）
 - 危险命令（rm -rf 等）需确认（requires_confirmation）
+- 陌生用户入口（Wterm 等）沙箱化 + 最小权限
 
-## 6. 验证标准
+## 7. 验证标准
 
 每个阶段完成后：浏览器端到端实测 agent 完整交互流程，不靠声称通过。