diff --git a/docs/LOCAL_DEPLOY.md b/docs/LOCAL_DEPLOY.md
new file mode 100644
index 0000000..6dedc50
--- /dev/null
+++ b/docs/LOCAL_DEPLOY.md
@@ -0,0 +1,113 @@
+# 本地部署指南(LOCAL_DEPLOY)
+
+> 在一台新机器上从零跑起本地蜂群测试环境。**本机构建即原生架构**(arm64/amd64 自动对),无需镜像仓库。**任何密钥都不要写进本仓**(见末尾清单,自己填)。
+
+## 0. 前提
+- Docker Desktop(开启 Kubernetes)、`kubectl`、`uv`(装 OpenSandbox 用,可选)
+- 若拉 Docker Hub 慢/被挡:`~/.docker/daemon.json` 加
+  ```json
+  { "registry-mirrors": ["https://<你的镜像加速域名>"] }
+  ```
+  改完重启 Docker。
+
+## 1. 拿代码
+```bash
+git clone http://gitee.ath.cx:3000/xiaohei/Agentswarm.git
+cd Agentswarm
+```
+
+## 2. 构建镜像(本机原生架构)
+```bash
+docker build -f Dockerfile.orchestrator -t swarm-orchestrator:local .
+docker build -f Dockerfile.agent        -t swarm-agent:local .
+# redis(Docker Hub 拉不动就用镜像源)
+docker pull redis:7-alpine || { docker pull mirror.gcr.io/library/redis:7-alpine && docker tag mirror.gcr.io/library/redis:7-alpine redis:7-alpine; }
+```
+
+## 3. 让 k8s 用上本地镜像
+- **Docker Desktop 经典 k8s**:本机镜像直接可用,跳过本步。
+- **kind 式(节点名 desktop-control-plane / desktop-worker…)**:镜像不共享,需导进每个节点:
+  ```bash
+  for img in swarm-orchestrator:local swarm-agent:local redis:7-alpine; do
+    docker save "$img" -o /tmp/i.tar
+    for n in $(kubectl get nodes -o name | sed 's|node/||'); do
+      docker exec -i "$n" ctr -n k8s.io images import - < /tmp/i.tar
+    done
+  done
+  ```
+
+## 4. 部署
+```bash
+kubectl create namespace swarm-system
+# 模型 key(见末尾清单,自己填)
+kubectl -n swarm-system create secret generic swarm-model-key --from-literal=OPENAI_API_KEY=<模型KEY>
+kubectl apply -f k8s/rbac/
+kubectl apply -f k8s/redis-statefulset.yaml
+kubectl apply -f k8s/orchestrator-local.yaml
+kubectl -n swarm-system rollout status deploy/orchestrator
+kubectl -n swarm-system port-forward svc/orchestrator-service 8000:8000   # → http://localhost:8000
+```
+`k8s/orchestrator-local.yaml` 关键 env(按需改):
+- `OPENAI_API_BASE` / `AGENT_OPENAI_API_BASE` = 你的 LLM 网关 `/v1`
+- `OPENAI_MODEL` = 默认模型 id(每个 run 也可由请求覆盖)
+- `OPENAI_API_KEY` ← secretKeyRef `swarm-model-key`
+- `AGENT_LAUNCH_BACKEND=kubernetes`、`AGENT_POD_IMAGE=swarm-agent:local`
+- `AGENT_LAUNCH_MIN_POOL=16`/`POOL_SIZE=16`/`MAX_POOL=64`、`MAX_AGENTS_PER_USER=64`、`AGENT_PROPOSAL_BUDGET=8`
+- 本地不走 azkv:**不要**设 `SECRET_RESOLVER`
+
+## 5. 发任务验证 fan-out
+```
+POST http://localhost:8000/api/swarms
+{
+  "mode": "swarm",
+  "orchestration_plan": { "objective": "<目标;greenfield 建项目可加『可覆盖原有仓库内容』>" },
+  "callback": { "url": "http://localhost:9999/cb" },
+  "metadata": { "manager_deployment_id": "test-1" },
+  "billing_context": { "default_model_id": "<模型id>" },
+  "resource_grants": [
+    { "resource_type": "git",
+      "secret_ref": "azkv://local/secrets/g1",
+      "metadata": { "repo_url": "<可写 git 仓>", "base_branch": "main" } }
+  ]
+}
+```
+返回 `data.deployment_id` → 轮询 `GET /api/swarms/{id}/result`。
+绑私有仓要给凭据(本地 dev 解析):
+```bash
+kubectl -n swarm-system set env deploy/orchestrator HEICODE_SECRET_g1='{"git_username":"<u>","git_password":"<p>"}'
+kubectl -n swarm-system rollout restart deploy/orchestrator
+```
+看日志出现 `Decomposed task into N subtask(s)` + 多个 agent 并行执行 = fan-out 成功。
+- pod 连宿主上的服务用 kind 网关 IP `172.19.0.1`(如宿主 redis/网关)。
+
+## 6.(可选)外部底座
+**OpenSandbox(代码执行沙盒)**
+```bash
+uv venv --python 3.11 /tmp/osb
+uv pip install --python /tmp/osb/bin/python opensandbox-server
+/tmp/osb/bin/opensandbox-server init-config ~/.sandbox.toml --example docker-zh
+OPENSANDBOX_INSECURE_SERVER=YES /tmp/osb/bin/opensandbox-server   # 127.0.0.1:8080,docker 运行时
+```
+SDK:`uv pip install --python /tmp/osb/bin/python opensandbox`;`SandboxSync.create("python:3.11-slim", connection_config=ConnectionConfigSync(domain="127.0.0.1:8080", protocol="http"))` → `.commands.run("...")`。
+
+**jina MCP(搜索/web 工具,托管)**
+- 端点 `https://mcp.jina.ai/v1`(Streamable HTTP),Header `Authorization: Bearer <JINA_API_KEY>`,21 个工具(search_web / read_url / …)。
+- Python 验证:`mcp` 包 `streamablehttp_client(url, headers=...)` + `ClientSession`。
+
+## 密钥清单(自己填,切勿写进本仓)
+| 用途 | 出处 / 重建 |
+|---|---|
+| 模型 key `sk-`(k8s secret `swarm-model-key`) | 你的 LLM 网关后台;建议新建 |
+| `JINA_API_KEY` | Jina 后台(已暴露的请吊销换新) |
+| git 凭据(`HEICODE_SECRET_<name>`) | 你的 gitea |
+| Azure(若用 ACR/AKS) | 新机 `az login` |
+
+## 避坑(本次踩过)
+- **不要往 xuanyuan.run 推自建镜像**(只拉不推,push `unsupported`);**ugdocker.link pull 返回 html(坏)**。本机构建就不需要任何 registry。
+- **镜像别跨架构**:在目标机本地构建即原生,别从 arm 机拷镜像到 amd 机(反之亦然)。
+- 用 Gitea 自带容器 registry 托管镜像时:`gitee.ath.cx:3000` 是 http,需加进 docker `insecure-registries` 并重启;推送要 `docker login gitee.ath.cx:3000`(用 gitea 账号)。
+
+## 当前能力 & 未完成
+- ✅ 自底向上分解(#7):一个种子 → 拆 N 子任务 → N 个 agent 并行(已验证)。
+- ⬜ Phase 3:agent 接 jina MCP(MCP client + function-calling)。⬜ Phase 4:代码执行走 OpenSandbox。
+- ⚠️ 架构缺口:只 fan-out 不 convergence——产物碎在各结果分支、无合并/聚合;评审循环封顶 `MAX_REVIEW_CYCLES=2`;`master_agent.synthesize` 仅文字汇总。