Add files via upload

2026-07-16 00:47:29 +02:00 · 2026-07-13 16:53:08 +08:00
parent d36352e4dc
commit 23ec222b77
8 changed files with 275 additions and 927 deletions
@@ -15,6 +15,11 @@ It brings AI agents, security tools, MCP-native integrations, knowledge systems,
 Built in Go, CyberStrikeAI provides a full-stack foundation for AI-native security operations: 100+ curated tool recipes, role-based testing, Agent Skills, Eino-powered single-agent and multi-agent orchestration, RAG knowledge retrieval, graph workflows, vulnerability and task lifecycle management, WebShell operations, chatbot access, and a lightweight built-in C2 framework for authorized lab and engagement scenarios.
 **Start here:** [Quick start](#quick-start-one-command-deployment) · [Documentation](docs/en-US/README.md) · [Production deployment](docs/en-US/deployment.md) · [API recipes](docs/en-US/api-recipes.md) · [Security hardening](docs/en-US/security-hardening.md)
 > [!IMPORTANT]
 > Use CyberStrikeAI only on systems you own or are explicitly authorized to test. For shared or production environments, review the [security model](docs/en-US/security-model.md) and [hardening guide](docs/en-US/security-hardening.md) before enabling high-risk tools, WebShell, or C2 capabilities.
 <details>
 <summary><strong>WeChat group</strong> (click to reveal QR code)</summary>
@@ -54,6 +59,9 @@ If CyberStrikeAI helps you, you can support the project via **WeChat Pay** or **
 *The dashboard provides a comprehensive overview of system runtime status, security vulnerabilities, tool usage, and knowledge base, helping users quickly understand the platform's core features and current state.*
 <details>
 <summary><strong>More interface screenshots</strong></summary>
 ### Core Features Overview
 <table>
@@ -115,33 +123,48 @@ If CyberStrikeAI helps you, you can support the project via **WeChat Pay** or **
 </tr>
 </table>
 </details>
 </div>
 ## Highlights
- 🤖 Agentic execution layer for translating natural-language intent into precise, governed, auditable security action
+### Agents and orchestration
- 🧩 Eino-powered single-agent and multi-agent orchestration with Deep, Plan-Execute, and Supervisor modes
+
- 🔌 MCP-native tool execution with HTTP/stdio/SSE transports, external MCP federation, and dynamic tool discovery
+- 🤖 **Agentic execution** translates natural-language intent into governed, auditable security actions.
- 🧰 100+ curated security tool recipes, YAML-based extensions, and role-scoped tool control
+- 🧩 **Eino orchestration** supports single-agent execution plus Deep, Plan-Execute, and Supervisor multi-agent modes.
- 📄 Large-result pagination, compression, and searchable archives
+- 🔀 **Graph workflows** combine Agents, tools, conditions, approvals, and outputs into reusable flows.
- 🔗 Attack-chain intelligence with graph views, risk scoring, project facts, and step-by-step replay
+- 🎭 **Role-based testing** provides focused prompts and tool policies for common security scenarios.
- 🧑‍⚖️ Human-in-the-loop governance with approval modes, allowlists, audit-agent review, and traceable decisions
+
- 🔒 Password-protected web UI, audit logs, SQLite persistence, and operational evidence retention
+### Tools and knowledge
- 🔐 **Platform RBAC** with multi-user accounts, system/custom roles, per-permission scopes (`all` / `assigned` / `own`), ownership, and explicit assignments enforced across APIs, Agents, MCP, background jobs, and chatbots; see the [RBAC administration guide](docs/en-US/rbac.md)
+
- 📚 Knowledge base (RAG): **Eino MultiQuery** query rewrite + multi-path vector retrieval + **HTTP rerank** (DashScope `gte-rerank` / Cohere-compatible) + post-processing (dedupe, budget); **Eino Compose** indexing pipeline
+- 🧰 **Security tools** include 100+ curated YAML recipes with custom extensions and role-scoped access.
- 📁 Conversation grouping with pinning, rename, and batch management
+- 🔌 **MCP integration** supports HTTP, stdio, SSE, external federation, and dynamic tool discovery.
- 📂 **Project management**: shared facts (blackboard) across sessions, `upsert_project_fact` + `links` to chain paths; attack-chain and project fact graph views
+- 🎯 **Agent Skills** follow the standard Skill layout and support progressive, on-demand loading.
- 🛡️ Vulnerability management with CRUD operations, severity tracking, status workflow, and statistics
+- 📚 **Knowledge base** combines query rewriting, vector retrieval, reranking, and result post-processing.
- 📋 Batch task management: create task queues, add multiple tasks, and execute them sequentially
+- 🖼️ **Vision analysis** uses a separate vision model for screenshots, captchas, and UI while retaining text summaries only.
- 🎭 Role-based testing: predefined security testing roles (Penetration Testing, CTF, Web App Scanning, etc.) with custom prompts and tool restrictions
+
- 🔀 **Graph orchestration**: visual workflow editor (Start / Agent / Tool / Condition / HITL / Output) with `{{previous.output}}` and `{{outputs.variable_name}}` for inter-node data passing; bind a graph to a role for automatic execution on chat. See [Graph orchestration guide](docs/en-US/workflow-graph.md)
+### Governance and audit
- 🧩 **Agent orchestration (CloudWeGo Eino)**: **single-agent** via **`/api/eino-agent/stream`** (Eino ADK `ChatModelAgent`); **multi-agent** via **`/api/multi-agent/stream`** with **`deep`** (coordinator + `task` sub-agents), **`plan_execute`**, or **`supervisor`** (`orchestration` in the request body). ADK **summarization** compresses long contexts; pre-compaction **transcripts** land at `data/conversation_artifacts/<conversation-id>/summarization/transcript.txt` (full user/assistant/tool turns; static system omitted). Markdown under `agents/`: `orchestrator.md`, `orchestrator-plan-execute.md`, `orchestrator-supervisor.md`, plus sub-agent `*.md` (see [Multi-agent doc](docs/en-US/MULTI_AGENT_EINO.md))
+
- 🖼️ **Vision analysis (`analyze_image`)**: separate VL model (e.g. `qwen-vl-max`) via MCP for local screenshots, captchas, and UI; image bytes stay out of agent history (text summaries only). Configure `vision` in `config.yaml`; see [docs/en-US/VISION.md](docs/en-US/VISION.md)
+- 🧑‍⚖️ **Human in the loop** provides approval modes, tool allowlists, audit-agent review, and traceable decisions.
- 🎯 **Skills (refactored for Eino)**: packs under `skills_dir` follow **Agent Skills** layout (`SKILL.md` + optional files); **multi-agent** sessions use the official Eino ADK **`skill`** tool for **progressive disclosure** (load by name), with optional **host filesystem / shell** via `multi_agent.eino_skills`; optional **`eino_middleware`** adds patchtoolcalls, tool_search, **plantask** (`TaskCreate` / `TaskList` boards under `skills_dir/.eino/plantask/`), reduction, file **checkpoints** (`checkpoint_dir`), ChatModel **retries**, session **output key**, and Deep tuning—20+ sample domains (SQLi, XSS, API security, …) ship under `skills/`
+- 🔐 **Platform RBAC** supports multiple users, system and custom roles, scoped permissions, ownership, and explicit assignments.
- 📱 **Chatbot**: Personal WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot—chat from mobile or IM apps (see [Robot / Chatbot guide](docs/en-US/robot.md))
+- 🔒 **Security and audit** provide authenticated access, audit logs, SQLite persistence, and operational evidence retention.
- 🧑‍⚖️ **Human-in-the-loop (HITL)**: Chat sidebar to set approval mode and tool allowlists (listed tools skip approval); global list in `config.yaml` under `hitl.tool_whitelist`; the Audit Agent can use a separate lightweight model via `hitl.audit_model`; **Apply** can merge new tools into the file and update the running server without restart; dedicated **HITL** page for pending approvals. See [HITL best practices](docs/en-US/hitl-best-practices.md)
+- 📄 **Result governance** supports pagination, compression, archival, and search for large tool outputs.
- 🐚 **WebShell management**: Add and manage WebShell connections (e.g. IceSword/AntSword compatible), use a virtual terminal for command execution, a built-in file manager for file operations, and an AI assistant tab that orchestrates tests and keeps per-connection conversation history; supports PHP, ASP, ASPX, JSP and custom shell types with configurable request method and command parameter.
+
- 📡 **Built-in C2**: AI-oriented lightweight command-and-control—**listeners** (TCP reverse, HTTP/HTTPS beacon, WebSocket), **encrypted** beacon channel, **session** and **task** queues with persistence, **payload** helpers (one-liner / build / download), **SSE** live events, REST under `/api/c2/*`, plus unified MCP tools (`c2_listener`, `c2_session`, **`c2_task`**, `c2_task_manage`, `c2_payload`, `c2_event`, `c2_profile`, `c2_file`); optional **HITL** approval for sensitive operations and OPSEC-style controls (e.g. command deny rules). **Authorized testing only.**
+### Security operations
 - 📁 **Conversation management** provides grouping, pinning, renaming, and batch organization.
 - 📂 **Projects and attack chains** connect cross-session facts, risk scoring, graph views, and step-by-step replay.
 - 🛡️ **Vulnerability management** provides severity classification, lifecycle tracking, filtering, and statistics.
 - 📋 **Batch tasks** provide queued execution, editing, status tracking, and retained results.
 - 📱 **Chatbots** connect Personal WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot.
 ### Authorized security operations
 - 🐚 **WebShell management** provides connection management, a virtual terminal, file operations, and AI-assisted workflows.
 - 📡 **Built-in C2** provides listeners, encrypted beacons, sessions, task queues, payload helpers, and live events.
 > WebShell, C2, and other high-risk capabilities are for systems you own or are explicitly authorized to test. See the [security model](docs/en-US/security-model.md) and [hardening guide](docs/en-US/security-hardening.md).
 ## Plugins
@@ -181,7 +204,7 @@ CyberStrikeAI ships with 100+ curated tools covering the whole kill chain:
 ### Quick Start (One-Command Deployment)
 **Prerequisites:**
- Go 1.21+ ([Install](https://go.dev/dl/))
+- Go 1.25+ ([Install](https://go.dev/dl/); required by `go.mod`)
 - Python 3.10+ ([Install](https://www.python.org/downloads/))
 **One-Command Deployment:**
@@ -207,7 +230,7 @@ The `run.sh` script will automatically:
   - Go to `Settings` → Fill in your API credentials:
     ```yaml
     openai:
-       api_key: "sk-your-key"
+       api_key: "${OPENAI_API_KEY}"
       base_url: "https://api.openai.com/v1"  # or https://api.deepseek.com/v1
       model: "gpt-4o"  # or deepseek-chat, claude-3-opus, etc.
     ```
@@ -243,9 +266,9 @@ If server logs show `client sent an HTTP request to an HTTPS server`, a client i
 **Note:** The Python virtual environment (`venv/`) is automatically created and managed by `run.sh`. Tools that require Python (like `api-fuzzer`, `http-framework-test`, etc.) will automatically use this environment.
-### Version Update (No Breaking Changes)
+### Upgrade and Compatibility
-**CyberStrikeAI one-click upgrade (recommended):**
+**CyberStrikeAI one-click upgrade:**
 1. (First time) enable the script: `chmod +x upgrade.sh`
 2. Upgrade with: `./upgrade.sh` (optional flags: `--tag vX.Y.Z`, `--no-venv`, `--yes`). Local `tools/`, `roles/`, and `skills/` are always preserved.
 3. The script will back up your `config.yaml` and `data/`, upgrade the code from GitHub Release, update `config.yaml`'s `version`, then restart the server.
@@ -260,401 +283,32 @@ Requirements / tips:
 * `rsync` is recommended/required for the safe code sync.
 * If GitHub API rate-limits you, set `export GITHUB_TOKEN="..."` before running `./upgrade.sh`.
-⚠️ **Note:** This procedure only applies to version updates without compatibility or breaking changes. If a release includes compatibility changes, this method may not apply.
+⚠️ **Before upgrading:** review the target release notes for configuration, database, and API changes. Backups are required even for patch upgrades; a version number alone is not a compatibility guarantee.
 **Examples:** No breaking changes — e.g. v1.3.1 → v1.3.2; with breaking changes — e.g. v1.3.1 → v1.4.0. The project follows [Semantic Versioning](https://semver.org/) (SemVer): when only the patch version (third number) changes, this upgrade path is usually safe; when the minor or major version changes, config, data, or APIs may have changed — check the release notes before using this method.
 ### Core Workflows
 - **Conversation testing** – Natural-language prompts trigger toolchains with streaming SSE output.
 - **Single vs multi-agent** – Chat UI switches between **Eino single-agent** (`/api/eino-agent/stream`) and **multi-agent** (`/api/multi-agent/stream` with `orchestration`: `deep` | `plan_execute` | `supervisor`). Multi mode requires `multi_agent.enabled: true`. MCP tools are bridged the same way for both paths.
 - **Role-based testing** – Select from predefined security testing roles (Penetration Testing, CTF, Web App Scanning, API Security Testing, etc.) to customize AI behavior and tool availability. Each role applies custom system prompts and can restrict available tools for focused testing scenarios.
 - **Graph orchestration** – Design flows on the **Graph Orchestration** page (drag nodes, connect edges, save); bind `workflow_id` on a role to run the graph on chat (Agent, MCP tools, condition branches). Use `{{outputs.variable_name}}` to pass data across non-adjacent nodes. See [Graph orchestration guide](docs/en-US/workflow-graph.md).
 - **Tool monitor** – Inspect running jobs, execution logs, and large-result attachments.
 - **History & audit** – Every conversation and tool invocation is stored in SQLite with replay.
 - **Conversation groups** – Organize conversations into groups, pin important groups, rename or delete groups via context menu.
 - **Vulnerability management** – Create, update, and track vulnerabilities discovered during testing. Filter by severity (critical/high/medium/low/info), status (open/confirmed/fixed/false_positive), and conversation. View statistics and export findings.
 - **Batch task management** – Create task queues with multiple tasks, add or edit tasks before execution, and run them sequentially. Each task executes as a separate conversation, with status tracking (pending/running/completed/failed/cancelled) and full execution history.
 - **WebShell management** – Add and manage WebShell connections (PHP/ASP/ASPX/JSP or custom). Use the virtual terminal to run commands, the file manager to list, read, edit, upload, and delete files, and the AI assistant tab to drive scripted tests with per-connection conversation history. Connections are stored in SQLite; supports GET/POST and configurable command parameter (e.g. IceSword/AntSword style).
 - **Built-in C2** – Create/start **listeners**, generate **payloads**, track **sessions**, enqueue **tasks**, and subscribe to **events** (SSE) from the Web UI or `/api/c2/*`. Agents and external clients use the C2 MCP tool family (including **`c2_task`**); when HITL is enabled, high-risk tasks can require human approval. Intended **only** for systems you are explicitly authorized to test.
 - **Settings** – Tweak provider keys, MCP enablement, tool toggles, and agent iteration limits.
 - **Human-in-the-loop (HITL)** – Sidebar sets mode and allowlisted tools (comma- or newline-separated); global list lives in `config.yaml` under `hitl.tool_whitelist`. The Audit Agent can use a separate low-cost model through `hitl.audit_model`, useful when human reviewers cannot keep up. **Apply** updates browser/server and can merge new tools into the file (**no restart**). **New chat** keeps sidebar choices; **HITL** nav shows pending approvals. Removing a tool in the sidebar does not remove it from the global list in `config.yaml`—edit the file if needed.
 ### Built-in Safeguards
 - Required-field validation prevents accidental blank API credentials.
 - Auto-generated 24-character initial `admin` password on first startup when no RBAC users exist (stored in the database only, not in `config.yaml`).
 - Unified auth middleware for every web/API call (Bearer token flow).
 - Timeout and sandbox guards per tool, plus structured logging for triage.
 ## Advanced Usage
 ### Role-Based Testing
 - **Predefined roles** – System includes 12+ predefined security testing roles (Penetration Testing, CTF, Web App Scanning, API Security Testing, Binary Analysis, Cloud Security Audit, etc.) in the `roles/` directory.
 - **Custom prompts** – Each role can define a `user_prompt` that prepends to user messages, guiding the AI to adopt specialized testing methodologies and focus areas.
 - **Tool restrictions** – Roles can specify a `tools` list to limit available tools, ensuring focused testing workflows (e.g., CTF role restricts to CTF-specific utilities).
 - **Skills** – Skill packs live under `skills_dir` and load via the Eino ADK **`skill`** tool (**progressive disclosure**) in both **single- and multi-agent** sessions when **`multi_agent.eino_skills`** is enabled. Optional host **read_file / glob / grep / write / edit / execute** and **`eino_middleware`** (tool_search, plantask, reduction, checkpoints, summarization transcripts, etc.) apply per mode—see docs.
 - **Easy role creation** – Create custom roles by adding YAML files to the `roles/` directory. Each role defines `name`, `description`, `user_prompt`, `icon`, `tools`, and `enabled` fields.
 - **Web UI integration** – Select roles from a dropdown in the chat interface. Role selection affects both AI behavior and available tool suggestions.
 **Creating a custom role (example):**
 1. Create a YAML file in `roles/` (e.g., `roles/custom-role.yaml`):
   ```yaml
   name: Custom Role
   description: Specialized testing scenario
   user_prompt: You are a specialized security tester focusing on API security...
   icon: "\U0001F4E1"
   tools:
     - api-fuzzer
     - arjun
     - graphql-scanner
   enabled: true
   ```
 2. Restart the server or reload configuration; the role appears in the role selector dropdown.
 ### Multi-Agent Mode (Eino: Deep, Plan-Execute, Supervisor)
 - **What it is** – Multi-agent orchestration on CloudWeGo **Eino** `adk/prebuilt` (alongside **Eino single-agent** on `/api/eino-agent*`): **`deep`** — coordinator + **`task`** sub-agents for complex security testing and delegated synthesis; **`plan_execute`** — planner / executor / replanner for structured loops; **`supervisor`** — expert-routing mode with **`transfer`** / **`exit`** for multiple specialist sub-agents. Client sends **`orchestration`**: `deep` | `plan_execute` | `supervisor` (default `deep`).
 - **Markdown agents** – Under `agents_dir` (default `agents/`):
  - **Deep orchestrator**: `orchestrator.md` *or* one `.md` with `kind: orchestrator`. Body or `multi_agent.orchestrator_instruction`, then Eino defaults.
  - **Plan-Execute orchestrator**: fixed name **`orchestrator-plan-execute.md`** (plus optional `orchestrator_instruction_plan_execute` in YAML).
  - **Supervisor orchestrator**: fixed name **`orchestrator-supervisor.md`** (plus optional `orchestrator_instruction_supervisor`); requires at least one sub-agent, and one-sub-agent runs emit a hint that expert routing has limited value.
  - **Sub-agents** (for **deep** / **supervisor**): other `*.md` files (YAML front matter + body). Not used as **`task`** targets if marked orchestrator-only.
 - **Management** – Web UI: **Agents → Agent management**; API `/api/multi-agent/markdown-agents`.
 - **Config** – `multi_agent` in `config.yaml`: `enabled`, `robot_default_agent_mode`, `batch_use_multi_agent`, `max_iteration`, `plan_execute_loop_max_iterations`, per-mode orchestrator instruction fields, optional YAML `sub_agents` merged with disk (`id` clash → Markdown wins), **`eino_skills`**, **`eino_middleware`** (optional ADK middleware and Deep/Supervisor tuning).
 - **Resilience & long runs** – `checkpoint_dir` enables ADK **resume** after process crashes (distinct from trace-based “interrupt & continue”). `deep_model_retry_max_retries` retries transient LLM API failures within a single call. **Summarization** writes a filtered **transcript** when compression fires; the summary message includes the path so the model can `read_file` for scan output and other pre-compaction details.
 - **Details** – **[docs/en-US/MULTI_AGENT_EINO.md](docs/en-US/MULTI_AGENT_EINO.md)** (streaming, robots, batch, middleware caveats).
 ### Skills System (Agent Skills + Eino)
 - **Layout** – Each skill is a directory with **required** `SKILL.md` only ([Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)): YAML front matter **only** `name` and `description`, plus Markdown body. Optional sibling files (`FORMS.md`, `REFERENCE.md`, `scripts/*`, …). **No** `SKILL.yaml` (not part of Claude or Eino specs); sections/scripts/progressive behavior are **derived at runtime** from Markdown and the filesystem.
 - **Runtime refactor** – **`skills_dir`** is the single root for packs. **Multi-agent** loads them through Eino’s official **`skill`** middleware (**progressive disclosure**: model calls `skill` with a pack **name** instead of receiving full SKILL text up front). Configure via **`multi_agent.eino_skills`**: `disable`, `filesystem_tools` (host read/glob/grep/write/edit/execute), `skill_tool_name`.
 - **Eino / RAG** – Packages are also split into `schema.Document` chunks for `FilesystemSkillsRetriever` (`skills.AsEinoRetriever()`) in **compose** graphs (e.g. knowledge/indexing pipelines).
 - **HTTP API** – `/api/skills` listing and `depth` (`summary` | `full`), `section`, and `resource_path` remain for the web UI and ops; **model-side** skill loading in multi-agent uses the **`skill`** tool, not MCP.
 - **Optional `eino_middleware`** – e.g. `tool_search` (dynamic MCP tool list), `patch_tool_calls`, **`plantask`** (Eino `TaskCreate` / `TaskGet` / `TaskUpdate` / `TaskList`; JSON under `skills_dir/.eino/plantask/<conversation-id>/`; Eino clears task files when **all** tasks are marked completed), `reduction`, **`checkpoint_dir`** (`data/eino-checkpoints/`), **`deep_model_retry_max_retries`**, **`deep_output_key`**, task-tool description prefix—see `config.yaml` and `internal/config/config.go`.
 - **Shipped demo** – `skills/cyberstrike-eino-demo/`; see `skills/README.md`.
 **Creating a skill:**
 1. `mkdir skills/<skill-id>` and add standard `SKILL.md` (+ any optional files), or drop in an open-source skill folder as-is.
 2. Use **multi-agent** with **`multi_agent.eino_skills`** enabled so the model can call the **`skill`** tool with that pack **name**.
 ### Tool Orchestration & Extensions
 - **YAML recipes** in `tools/*.yaml` describe commands, arguments, prompts, and metadata.
 - **Directory hot-reload** – pointing `security.tools_dir` to a folder is usually enough; inline definitions in `config.yaml` remain supported for quick experiments.
 - **Large tool outputs** – outputs beyond `reduction_max_length_for_trunc` are summarized via Eino reduction with full content persisted under `tmp/reduction/`; use `read_file` on the path in `<persisted-output>`.
 - **Result compression** – multi-megabyte logs can be summarized or losslessly compressed before persisting to keep SQLite lean.
 **Creating a custom tool (typical flow)**
 1. Copy an existing YAML file from `tools/` (for example `tools/nmap.yaml` or `tools/ffuf.yaml`).
 2. Update `name`, `command`, `args`, and `short_description`.
 3. Describe positional or flag parameters in `parameters[]` so the agent knows how to build CLI arguments.
 4. Provide a longer `description`/`notes` block if the agent needs extra context or post-processing tips.
 5. Restart the server or reload configuration; the new tool becomes available immediately and can be enabled/disabled from the Settings panel.
 ### Attack-Chain Intelligence
 - AI parses each conversation to assemble targets, tools, vulnerabilities, and relationships.
 - The web UI renders the chain as an interactive graph with severity scoring and step replay.
 - Export the chain or raw findings to external reporting pipelines.
 ### WebShell Management
 - **Connections** – From the Web UI, go to **WebShell Management** to add, edit, or delete WebShell connections. Each connection stores: Shell URL, password/key, shell type (PHP, ASP, ASPX, JSP, Custom), request method (GET/POST), command parameter name (default `cmd`), and an optional remark; all records persist in SQLite and are compatible with common clients such as IceSword and AntSword.
 - **Virtual terminal** – After selecting a connection, use the **Virtual terminal** tab to run arbitrary commands with history and quick commands (whoami/id/ls/pwd etc.). Output is streamed in the browser, and Ctrl+L clears the screen.
 - **File manager** – Use the **File manager** tab to list directories, read or edit files, delete files, create folders/files, upload files (including chunked uploads for large files), rename paths, and download selected files. Path navigation supports breadcrumbs, parent directory jumps, and name filtering.
 - **AI assistant** – Use the **AI assistant** tab to chat with an agent that understands the current WebShell connection, automatically runs tools and shell commands, and maintains per-connection conversation history with a sidebar of previous sessions.
 - **Connectivity test** – Use **Test connectivity** to verify that the shell URL, password, and command parameter are correct before running commands (sends a lightweight `echo 1` check).
 - **Persistence** – All WebShell connections and AI conversations are stored in SQLite (same database as conversations), so they persist across restarts.
 ### Built-in C2 (Command & Control)
 - **What it is** – A first-party, **AI-native** C2 stack: listeners accept implants (beacons), the server stores **sessions** and **tasks** in SQLite, pushes updates over an **event bus** (including **SSE**), and exposes everything through authenticated **REST** plus MCP.
 - **Listeners & transports** – `tcp_reverse`, `http_beacon`, `https_beacon`, and `websocket`; per-listener crypto keys; running listeners can be **restored after restart** when marked running in the database.
 - **Agent integration** – MCP exposes a small **C2 tool family** (listeners, sessions, **`c2_task`**, task management, payloads, events, profiles, files) so the same agent loop can orchestrate C2 alongside other tools; dangerous task types can go through the existing **HITL** bridge when your session policy requires it.
 - **Safety** – Use **only** in lab or **fully authorized** engagements; combine network isolation, strong auth, and HITL/allowlists as your policy demands.
 ### MCP Everywhere
 - **Web mode** – ships with HTTP MCP server automatically consumed by the UI.
 - **MCP stdio mode** – `go run cmd/mcp-stdio/main.go` exposes the agent to Cursor/CLI.
 - **External MCP federation** – register third-party MCP servers (HTTP, stdio, or SSE) from the UI, toggle them per engagement, and monitor their health and call volume in real time.
 - **Optional MCP servers** – the [`mcp-servers/`](mcp-servers/README.md) directory provides standalone MCPs (e.g. reverse shell). They speak standard MCP over stdio and work with CyberStrikeAI (Settings → External MCP), Cursor, VS Code, and other MCP clients.
 #### MCP stdio quick start
 1. **Build the binary** (run from the project root):
   ```bash
   go build -o cyberstrike-ai-mcp cmd/mcp-stdio/main.go
   ```
 2. **Wire it up in Cursor**  
   Open `Settings → Tools & MCP → Add Custom MCP`, pick **Command**, then point to the compiled binary and your config:
   ```json
   {
     "mcpServers": {
       "cyberstrike-ai": {
         "command": "/absolute/path/to/cyberstrike-ai-mcp",
         "args": [
           "--config",
           "/absolute/path/to/config.yaml"
         ]
       }
     }
   }
   ```
   Replace the paths with your local locations; Cursor will launch the stdio server automatically.
 #### MCP HTTP quick start (Cursor / Claude Code)
 The HTTP MCP server runs on a separate port (default `8081`) and supports **header-based authentication** so only clients that send the correct header can call tools.
 1. **Enable MCP in config** – In `config.yaml` set `mcp.enabled: true` and optionally `mcp.host` / `mcp.port`. For auth (recommended if the port is reachable from the network), set:
   - `mcp.auth_header` – header name (e.g. `X-MCP-Token`);
   - `mcp.auth_header_value` – secret value. **Leave it empty** if you want the server to **auto-generate** a random token on first start and write it back to the config.
 2. **Start the service** – Run `./run.sh` or `go run cmd/server/main.go`. The MCP endpoint is `http://<host>:<port>/mcp` (e.g. `http://localhost:8081/mcp`).
 3. **Copy the JSON from the terminal** – When MCP is enabled, the server prints a **ready-to-paste** JSON block. If `auth_header_value` was empty, it will have been generated and saved; the printed JSON includes the URL and headers.
 4. **Use in Cursor or Claude Code**:
   - **Cursor**: Paste the block into `~/.cursor/mcp.json` (or your project’s `.cursor/mcp.json`) under `mcpServers`, or merge it into your existing `mcpServers`.
   - **Claude Code**: Paste into `.mcp.json` or `~/.claude.json` under `mcpServers`.
 Example of what the terminal prints (with auth enabled):
 ```json
 {
  "mcpServers": {
    "cyberstrike-ai": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "X-MCP-Token": "<auto-generated-or-your-value>"
      },
      "type": "http"
    }
  }
 }
 ```
 If you do not set `auth_header` / `auth_header_value`, the endpoint accepts requests without authentication (suitable only for localhost or trusted networks).
 #### External MCP federation (HTTP/stdio/SSE)
 CyberStrikeAI supports connecting to external MCP servers via three transport modes:
 - **HTTP mode** – traditional request/response over HTTP POST
 - **stdio mode** – process-based communication via standard input/output
 - **SSE mode** – Server-Sent Events for real-time streaming communication
 To add an external MCP server:
 1. Open the Web UI and navigate to **Settings → External MCP**.
 2. Click **Add External MCP** and provide the configuration in JSON format:
   **HTTP mode example:**
   ```json
   {
     "my-http-mcp": {
       "transport": "http",
       "url": "http://127.0.0.1:8081/mcp",
       "description": "HTTP MCP server",
       "timeout": 30
     }
   }
   ```
   **stdio mode example:**
   ```json
   {
     "my-stdio-mcp": {
       "command": "python3",
       "args": ["/path/to/mcp-server.py"],
       "description": "stdio MCP server",
       "timeout": 30
     }
   }
   ```
   **SSE mode example:**
   ```json
   {
     "my-sse-mcp": {
       "transport": "sse",
       "url": "http://127.0.0.1:8082/sse",
       "description": "SSE MCP server",
       "timeout": 30
     }
   }
   ```
 3. Click **Save** and then **Start** to connect to the server.
 4. Monitor the connection status, tool count, and health in real time.
 **SSE mode benefits:**
 - Real-time bidirectional communication via Server-Sent Events
 - Suitable for scenarios requiring continuous data streaming
 - Lower latency for push-based notifications
 A test SSE MCP server is available at `cmd/test-sse-mcp-server/` for validation purposes.
 ### Knowledge Base
 - **Vector search** – AI agent can automatically search the knowledge base for relevant security knowledge during conversations using the `search_knowledge_base` tool.
 - **RAG pipeline (always on)** – **MultiQuery** (LLM query rewrite) → vector prefetch & fusion → **HTTP rerank** (DashScope `gte-rerank` or Cohere-compatible `/v1/rerank`) → post-processing (normalized dedupe, char/token budget, final top_k). Rerank failures degrade to fusion order without breaking search.
 - **Vector retrieval** – cosine similarity over stored embeddings with configurable threshold, aligned with Eino `retriever.Retriever` usage.
 - **Auto-indexing** – scans the `knowledge_base/` directory for Markdown files and automatically indexes them with embeddings (Markdown header split + recursive chunking via Eino).
 - **Web management** – create, update, delete knowledge items through the web UI, with category-based organization; settings page exposes MultiQuery / rerank / prefetch options.
 - **Retrieval logs** – tracks all knowledge retrieval operations for audit and debugging.
 **Setting up the knowledge base:**
 1. **Enable in config** – set `knowledge.enabled: true` in `config.yaml`:
   ```yaml
   knowledge:
     enabled: true
     base_path: knowledge_base
     embedding:
       provider: openai
       model: text-embedding-v4
       base_url: "https://api.openai.com/v1"  # or your embedding API
       api_key: "sk-xxx"
     retrieval:
       top_k: 5
       similarity_threshold: 0.7
       multi_query:
         max_queries: 4        # LLM rewrite variants (always on)
       rerank:                 # always on; empty fields inherit openai/embedding credentials
         provider: ""          # auto: dashscope | cohere from base_url
         model: ""             # empty: gte-rerank (DashScope) or rerank-multilingual-v3.0 (Cohere)
         base_url: ""
         api_key: ""
       post_retrieve:
         prefetch_top_k: 20    # vector candidates per MultiQuery variant; 0 = max(top_k×4, 20)
         max_context_chars: 0
         max_context_tokens: 0
   ```
 2. **Add knowledge files** – place Markdown files in `knowledge_base/` directory, organized by category (e.g., `knowledge_base/SQL Injection/README.md`).
 3. **Scan and index** – use the web UI to scan the knowledge base directory, which will automatically import files and build vector embeddings.
 4. **Use in conversations** – the AI agent will automatically use `search_knowledge_base` when it needs security knowledge. You can also explicitly ask: "Search the knowledge base for SQL injection techniques".
 **Knowledge base structure:**
 - Files are organized by category (directory name becomes the category).
 - Each Markdown file becomes a knowledge item with automatic chunking for vector search.
 - The system supports incremental updates – modified files are re-indexed automatically.
-### Automation Hooks
+## Configuration
 - **REST APIs** – everything the UI uses (auth, conversations, tool runs, monitor, vulnerabilities, roles) is available over JSON.
 - **Multi-agent APIs** – `POST /api/multi-agent/stream` (SSE, when enabled), `POST /api/multi-agent` (non-streaming), Markdown agents under `/api/multi-agent/markdown-agents` (list/get/create/update/delete).
 - **Role APIs** – manage security testing roles via `/api/roles` endpoints: `GET /api/roles` (list all roles), `GET /api/roles/:name` (get role), `POST /api/roles` (create role), `PUT /api/roles/:name` (update role), `DELETE /api/roles/:name` (delete role). Roles are stored as YAML files in the `roles/` directory and support hot-reload.
 - **Vulnerability APIs** – manage vulnerabilities via `/api/vulnerabilities` endpoints: `GET /api/vulnerabilities` (list with filters), `POST /api/vulnerabilities` (create), `GET /api/vulnerabilities/:id` (get), `PUT /api/vulnerabilities/:id` (update), `DELETE /api/vulnerabilities/:id` (delete), `GET /api/vulnerabilities/stats` (statistics).
 - **Batch Task APIs** – manage batch task queues via `/api/batch-tasks` endpoints: `POST /api/batch-tasks` (create queue), `GET /api/batch-tasks` (list queues), `GET /api/batch-tasks/:queueId` (get queue), `POST /api/batch-tasks/:queueId/start` (start execution), `POST /api/batch-tasks/:queueId/cancel` (cancel), `DELETE /api/batch-tasks/:queueId` (delete), `POST /api/batch-tasks/:queueId/tasks` (add task), `PUT /api/batch-tasks/:queueId/tasks/:taskId` (update task), `DELETE /api/batch-tasks/:queueId/tasks/:taskId` (delete task). Tasks execute sequentially, each creating a separate conversation with full status tracking.
 - **WebShell APIs** – manage WebShell connections and execute commands via `/api/webshell/connections` (GET list, POST create, PUT update, DELETE delete) and `/api/webshell/exec` (command execution), `/api/webshell/fileop` (list/read/write/delete files).
 - **C2 APIs** – manage listeners, sessions, tasks, payloads, files, and events under `/api/c2/*` (e.g. listeners CRUD/start/stop, session sleep, task create/cancel/wait, payload build/download, event stream).
 - **Task control** – pause/resume/stop long scans, re-run steps with new params, or stream transcripts.
 - **Audit & security** – rotate passwords via `/api/auth/change-password`, enforce short-lived sessions, and restrict MCP ports at the network layer when exposing the service.
-## Configuration Reference
+Use [`config.example.yaml`](config.example.yaml) as the authoritative configuration template and copy only the values required for your environment. At minimum, configure the server and an OpenAI-compatible model provider:
 ```yaml
 auth:
  session_duration_hours: 12
 server:
-  host: "0.0.0.0"
+  host: "127.0.0.1"
  port: 8080
 log:
  level: "info"
  output: "stdout"
 mcp:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  auth_header: "X-MCP-Token"       # optional; leave empty for no auth
  auth_header_value: ""            # optional; leave empty to auto-generate on first start
 openai:
-  api_key: "sk-xxx"
+  api_key: "${OPENAI_API_KEY}"
-  base_url: "https://api.deepseek.com/v1"
+  base_url: "https://api.openai.com/v1"
-  model: "deepseek-chat"
+  model: "your-model"
 database:
  path: "data/conversations.db"
  knowledge_db_path: "data/knowledge.db"  # Optional: separate DB for knowledge base
 security:
  tools_dir: "tools"
 knowledge:
  enabled: false  # Enable knowledge base feature
  base_path: "knowledge_base"  # Path to knowledge base directory
  embedding:
    provider: "openai"  # Embedding provider (currently only "openai")
    model: "text-embedding-v4"  # Embedding model name
    base_url: ""  # Leave empty to use OpenAI base_url
    api_key: ""  # Leave empty to use OpenAI api_key
  retrieval:
    top_k: 5  # Number of top results to return
    similarity_threshold: 0.7  # Minimum cosine similarity (0-1)
    multi_query:
      max_queries: 4  # MultiQuery rewrite variants (always on)
    rerank:  # HTTP rerank (always on); empty fields inherit openai/embedding credentials
      provider: ""
      model: ""
      base_url: ""
      api_key: ""
    post_retrieve:
      prefetch_top_k: 20  # per MultiQuery variant; 0 = max(top_k×4, 20)
      max_context_chars: 0
      max_context_tokens: 0
 roles_dir: "roles"  # Role configuration directory (relative to config file)
 skills_dir: "skills"  # Skills directory (relative to config file)
 agents_dir: "agents"  # Multi-agent Markdown definitions (orchestrator + sub-agents)
 multi_agent:
  enabled: false
  default_mode: "eino_single"   # eino_single | multi (UI default when multi-agent is enabled)
  robot_default_agent_mode: eino_single
  batch_use_multi_agent: false
  orchestrator_instruction: ""  # Deep; used when orchestrator.md body is empty
  # orchestrator_instruction_plan_execute / orchestrator_instruction_supervisor optional
  # eino_skills: { disable: false, filesystem_tools: true, skill_tool_name: skill }
  # eino_middleware: plantask_enable, checkpoint_dir, deep_model_retry_max_retries, deep_output_key, ...
 project:
  enabled: true              # Enable project blackboard & fact MCP tools
  fact_index_max_runes: 65000
  fact_summary_max_runes: 24000
  default_inject_deprecated: false
 ```
-### Tool Definition Example (`tools/nmap.yaml`)
+Do not commit real credentials. Review the [configuration reference](docs/en-US/configuration.md), [recommended profiles](docs/en-US/configuration-profiles.md), and [security hardening guide](docs/en-US/security-hardening.md) before exposing the service beyond localhost.
 ```yaml
 name: "nmap"
 command: "nmap"
 args: ["-sT", "-sV", "-sC"]
 enabled: true
 short_description: "Network mapping & service fingerprinting"
 parameters:
  - name: "target"
    type: "string"
    description: "IP or domain"
    required: true
    position: 0
  - name: "ports"
    type: "string"
    flag: "-p"
    description: "Range, e.g. 1-1000"
 ```
 ### Role Definition Example (`roles/penetration-testing.yaml`)
 ```yaml
 name: Penetration Testing
 description: Professional penetration testing expert for comprehensive security testing
 user_prompt: You are a professional cybersecurity penetration testing expert. Please use professional penetration testing methods and tools to conduct comprehensive security testing on targets, including but not limited to SQL injection, XSS, CSRF, file inclusion, command execution and other common vulnerabilities.
 icon: "\U0001F3AF"
 tools:
  - nmap
  - sqlmap
  - nuclei
  - burpsuite
  - metasploit
  - httpx
  - record_vulnerability
  - list_knowledge_risk_types
  - search_knowledge_base
 enabled: true
 ```
 ## Related documentation
- [Documentation index](docs/README.md): deployment, configuration, security model, API, knowledge base, C2, WebShell, MCP, development, testing, and troubleshooting.
+- **New users:** [Deployment](docs/en-US/deployment.md) → [Configuration](docs/en-US/configuration.md) → [Troubleshooting](docs/en-US/troubleshooting.md)
- [Deployment guide](docs/en-US/deployment.md): source/binary startup, HTTPS, reverse proxy, systemd, backup, upgrade, and rollback.
+- **Operators:** [Configuration profiles](docs/en-US/configuration-profiles.md) → [Security hardening](docs/en-US/security-hardening.md) → [Runbooks](docs/en-US/runbooks.md)
- [Runbooks](docs/en-US/runbooks.md): production setup, external MCP, knowledge base, authorized Web testing, and C2 cleanup workflows.
+- **Integrators:** [API reference](docs/en-US/api-reference.md) → [API recipes](docs/en-US/api-recipes.md) → [MCP federation](docs/en-US/mcp-federation.md)
- [Security hardening](docs/en-US/security-hardening.md): launch baseline, HITL allowlist, reverse proxy, file permissions, and periodic review.
+- **Contributors:** [Developer guide](docs/en-US/developer-guide.md) → [Testing](docs/en-US/testing.md) → [Contributing](docs/en-US/contributing-guide.md)
- [API recipes](docs/en-US/api-recipes.md): examples for login, Agent, streaming, multi-agent, uploads, vulnerabilities, KB, and audit export.
+- **All topics:** [English documentation](docs/en-US/README.md) · [Bilingual documentation index](docs/README.md)
 - [Configuration reference](docs/en-US/configuration.md): main `config.yaml` sections, recommended values, and update guidance.
 - [Security model](docs/en-US/security-model.md): authentication, tool execution, HITL, audit, C2/WebShell, and data safety boundaries.
 - [RBAC administration](docs/en-US/rbac.md): platform users, system/custom roles, permission catalog, per-permission scopes, resource assignments, Agent/MCP/robot boundaries, and API examples.
 - [API reference](docs/en-US/api-reference.md): OpenAPI, authentication, Agent, projects, knowledge base, C2, WebShell, and other API entry points.
 - [Multi-agent mode (Eino)](docs/en-US/MULTI_AGENT_EINO.md): **Deep**, **Plan-Execute**, **Supervisor**, `agents/*.md`, `eino_skills` / `eino_middleware`, APIs, and chat/stream behavior.
 - [Graph orchestration guide](docs/en-US/workflow-graph.md): visual workflow design, node configuration, `previous` / `outputs` variable passing, and role binding.
 - [Robot / Chatbot guide](docs/en-US/robot.md): Platform setup, RBAC user-binding/service-account modes, sender allowlists, commands, verification, and troubleshooting.
 - [HITL best practices](docs/en-US/hitl-best-practices.md): reviewer modes, allowlists, Audit Agent prompts, and separate small-model configuration.
 ## Project Layout
@@ -669,6 +323,7 @@ CyberStrikeAI/
 ├── agents/              # Multi-agent Markdown (orchestrator.md + sub-agent *.md)
 ├── docs/                # Topic docs (deployment, config, security, API, knowledge base, C2, WebShell, etc.)
 ├── images/              # Docs screenshots & diagrams
 ├── scripts/             # Repository maintenance checks, including documentation validation
 ├── config.yaml          # Runtime configuration
 ├── run.sh               # Convenience launcher
 └── README*.md
@@ -736,3 +391,4 @@ For vulnerability reporting and deployment hardening guidance, see [SECURITY.md]
 ---
 Need help or want to contribute? Open an issue or PR—community tooling additions are welcome!
@@ -14,6 +14,11 @@
 CyberStrikeAI 基于 Go 构建，为 AI 原生安全运营提供完整底座：100+ 精选工具配方、角色化测试、Agent Skills、基于 Eino 的单智能体与多智能体编排、RAG 知识检索、图工作流、漏洞与任务生命周期管理、WebShell 运营、机器人接入，以及面向授权实验室和安全任务场景的内置轻量 C2 框架。
 **从这里开始：** [快速上手](#快速上手一条命令部署) · [中文文档](docs/zh-CN/README.md) · [生产部署](docs/zh-CN/deployment.md) · [API 示例](docs/zh-CN/api-recipes.md) · [安全加固](docs/zh-CN/security-hardening.md)
 > [!IMPORTANT]
 > 仅可对自有系统或已获得明确授权的目标使用 CyberStrikeAI。在共享或生产环境启用高风险工具、WebShell 或 C2 前，请先阅读[安全模型](docs/zh-CN/security-model.md)和[安全加固指南](docs/zh-CN/security-hardening.md)。
 <details>
 <summary><strong>微信群</strong>（点击展开二维码）</summary>
@@ -53,6 +58,9 @@ CyberStrikeAI 基于 Go 构建，为 AI 原生安全运营提供完整底座：1
 *仪表盘提供系统运行状态、安全漏洞、工具使用情况和知识库的全面概览，帮助用户快速了解平台核心功能和当前状态。*
 <details>
 <summary><strong>查看更多界面截图</strong></summary>
 ### 核心功能概览
 <table>
@@ -114,33 +122,48 @@ CyberStrikeAI 基于 Go 构建，为 AI 原生安全运营提供完整底座：1
 </tr>
 </table>
 </details>
 </div>
 ## 特性速览
- 🤖 面向智能体时代的执行层，将自然语言意图转化为精准、受控、可审计的安全行动
+### 智能体与编排
- 🧩 基于 Eino 的单智能体与多智能体编排，支持 Deep、Plan-Execute、Supervisor 等模式
+
- 🔌 MCP 原生工具执行，支持 HTTP / stdio / SSE 传输、外部 MCP 联邦与动态工具发现
+- 🤖 **智能体执行层**：将自然语言意图转化为受控、可审计的安全行动。
- 🧰 100+ 精选安全工具配方、YAML 扩展机制与按角色收敛的工具控制
+- 🧩 **Eino 编排**：支持单智能体及 Deep、Plan-Execute、Supervisor 多智能体模式。
- 📄 大结果分页、压缩与全文检索
+- 🔀 **图工作流**：通过 Agent、工具、条件、审批和输出节点构建可复用流程。
- 🔗 攻击链智能分析，支持图谱视图、风险打分、项目事实沉淀与步骤回放
+- 🎭 **角色化测试**：为常见安全场景提供聚焦的提示词和工具策略。
- 🧑‍⚖️ 人机协同治理，支持审批模式、免审批白名单、审计 Agent 复核与可追溯决策
+
- 🔒 Web 登录保护、审计日志、SQLite 持久化与行动证据留存
+### 工具与知识扩展
- 🔐 **平台 RBAC**：支持多用户、系统/自定义角色、逐权限 Scope（`all` / `assigned` / `own`）、资源归属与显式授权，并统一约束 API、Agent、MCP、后台任务和机器人；详见 [RBAC 权限管理](docs/zh-CN/rbac.md)
+
- 📚 知识库（RAG）：**Eino MultiQuery** 查询改写 + 多路向量检索 + **HTTP 精排**（DashScope `gte-rerank` / Cohere 兼容）+ 后处理（去重、预算）；索引侧为 **Eino Compose** 流水线
+- 🧰 **安全工具**：提供 100+ 精选 YAML 工具配方，支持自定义扩展和按角色控制。
- 📁 对话分组管理：支持分组创建、置顶、重命名、删除等操作
+- 🔌 **MCP 集成**：支持 HTTP、stdio、SSE、外部 MCP 联邦和动态工具发现。
- 📂 **项目管理**：共享事实（黑板）跨会话沉淀认知，`upsert_project_fact` + `links` 串联攻击路径；聊天攻击链与项目事实图可视化
+- 🎯 **Agent Skills**：遵循标准 Skill 目录结构，支持渐进式按需加载。
- 🛡️ 漏洞管理功能：完整的漏洞 CRUD 操作，支持严重程度分级、状态流转、按对话/严重程度/状态过滤，以及统计看板
+- 📚 **知识库**：组合查询改写、向量检索、精排和结果后处理能力。
- 📋 批量任务管理：创建任务队列，批量添加任务，依次顺序执行，支持任务编辑与状态跟踪
+- 🖼️ **视觉分析**：使用独立视觉模型分析截图、验证码和 UI，对话中仅保留文字摘要。
- 🎭 角色化测试：预设安全测试角色（渗透测试、CTF、Web 应用扫描等），支持自定义提示词和工具限制
+
- 🔀 **图编排**：可视化流程编排（开始 / Agent / 工具 / 条件 / 审批 / 输出），节点间用 `{{previous.output}}` 或 `{{outputs.变量名}}` 传参；绑定角色后对话自动按图执行。详见 [图编排使用说明](docs/zh-CN/workflow-graph.md)
+### 安全治理与审计
- 🧩 **Agent 编排（CloudWeGo Eino）**：**单代理** `POST /api/eino-agent/stream`（Eino ADK）；**多代理** `POST /api/multi-agent/stream`，`orchestration` 选 **`deep`** / **`plan_execute`** / **`supervisor`**。ADK **Summarization** 在上下文过长时压缩历史；压缩前将可恢复 **转录** 写入 `data/conversation_artifacts/<会话ID>/summarization/transcript.txt`（保留完整 user/assistant/tool 轮次，省略静态 system）。`agents/` 下主代理与子代理 Markdown 见 [多代理说明](docs/zh-CN/MULTI_AGENT_EINO.md)
+
- 🖼️ **视觉分析（`analyze_image`）**：独立 Vision 模型（如 `qwen-vl-max`），MCP 工具分析本地截图/验证码/UI；图片仅在单次 VL 调用中出现，对话上下文只保留文字摘要。配置见 `config.yaml` → `vision` 与 [视觉分析说明](docs/zh-CN/VISION.md)
+- 🧑‍⚖️ **人机协同**：支持审批模式、工具白名单、审计 Agent 复核和决策追踪。
- 🎯 **Skills（面向 Eino 重构）**：技能包放在 **`skills_dir`**，遵循 **Agent Skills** 目录规范（`SKILL.md` + 可选文件）；**多代理** 下通过 Eino 官方 **`skill`** 工具 **渐进式披露**（按 name 加载）。**`multi_agent.eino_skills`** 控制是否启用、本机文件/Shell 工具、工具名覆盖；**`eino_middleware`** 可选 patch、tool_search、**plantask**（`TaskCreate` / `TaskList` 任务板，落在 `skills_dir/.eino/plantask/`）、reduction、文件型 **checkpoint**（`checkpoint_dir`）、ChatModel **重试**、会话 **输出键** 及 Deep 调参。20+ 领域示例仍可绑定角色
+- 🔐 **平台 RBAC**：支持多用户、系统及自定义角色、权限 Scope、资源归属和显式授权。
- 📱 **机器人**：个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord、QQ 机器人，在手机或 IM 中与 CyberStrikeAI 对话（详见 [机器人使用说明](docs/zh-CN/robot.md)）
+- 🔒 **安全与审计**：提供登录保护、审计日志、SQLite 持久化和行动证据留存。
- 🧑‍⚖️ **人机协同（HITL）**：对话页侧栏配置协同模式与免审批工具白名单；全局列表在 `config.yaml` 的 `hitl.tool_whitelist`；审计 Agent 可通过 `hitl.audit_model` 使用独立小模型；点「应用」可将新增工具合并写入配置文件且**无需重启**即可生效；导航 **人机协同** 页处理待审批工具调用。详见 [人机协同最佳实践](docs/zh-CN/hitl-best-practices.md)
+- 📄 **结果治理**：支持大结果分页、压缩、归档和检索。
- 🐚 **WebShell 管理**：添加与管理 WebShell 连接（兼容冰蝎/蚁剑等），通过虚拟终端执行命令、内置文件管理进行文件操作，并提供按连接维度保存历史的 AI 助手标签页；支持 PHP/ASP/ASPX/JSP 及自定义类型，可配置请求方法与命令参数。
+
- 📡 **内置 C2**：面向 AI 协同的轻量 **C2**——**多种监听器**（TCP 反向、HTTP/HTTPS Beacon、WebSocket）、**加密** Beacon 信道、**会话与任务**队列及持久化、**Payload** 辅助（一键命令 / 构建 / 下载）、**SSE** 实时事件、REST（`/api/c2/*`）及智能体侧 **一组 C2 MCP 工具**（如 `c2_listener`、`c2_session`、**`c2_task`**、`c2_task_manage`、`c2_payload`、`c2_event`、`c2_profile`、`c2_file`）；敏感操作可对接 **人机协同（HITL）**，并支持 OPSEC 类规则（如命令拒绝正则）。**仅限授权测试。**
+### 安全运营管理
 - 📁 **对话管理**：支持分组、置顶、重命名和批量管理。
 - 📂 **项目与攻击链**：关联跨会话事实、风险评分、图谱视图和步骤回放。
 - 🛡️ **漏洞管理**：支持严重程度分级、状态流转、过滤和统计看板。
 - 📋 **批量任务**：支持任务队列、编辑、状态跟踪和结果留存。
 - 📱 **机器人接入**：支持个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord 和 QQ。
 ### 授权安全操作
 - 🐚 **WebShell 管理**：提供连接管理、虚拟终端、文件操作和 AI 辅助工作流。
 - 📡 **内置 C2**：提供监听器、加密 Beacon、会话、任务队列、Payload 辅助和实时事件。
 > WebShell、C2 及其他高风险能力仅限自有系统或已获得明确授权的测试环境。使用前请阅读[安全模型](docs/zh-CN/security-model.md)和[安全加固指南](docs/zh-CN/security-hardening.md)。
 ## 插件（Plugins）
@@ -180,7 +203,7 @@ CyberStrikeAI 基于 Go 构建，为 AI 原生安全运营提供完整底座：1
 ### 快速上手（一条命令部署）
 **环境要求：**
- Go 1.21+ ([下载安装](https://go.dev/dl/))
+- Go 1.25+（[下载安装](https://go.dev/dl/)，以 `go.mod` 为准）
 - Python 3.10+ ([下载安装](https://www.python.org/downloads/))
 **一条命令部署：**
@@ -206,7 +229,7 @@ chmod +x run.sh && ./run.sh
   - 进入 `设置` → 填写 API 配置信息：
     ```yaml
     openai:
-       api_key: "sk-your-key"
+       api_key: "${OPENAI_API_KEY}"
       base_url: "https://api.openai.com/v1"  # 或 https://api.deepseek.com/v1
       model: "gpt-4o"  # 或 deepseek-chat, claude-3-opus 等
     ```
@@ -242,7 +265,7 @@ go build -o cyberstrike-ai cmd/server/main.go
 **说明：** Python 虚拟环境（`venv/`）由 `run.sh` 自动创建和管理。需要 Python 的工具（如 `api-fuzzer`、`http-framework-test` 等）会自动使用该环境。
-### CyberStrikeAI 版本更新（无兼容性问题）
+### 版本升级与兼容性
 1. （首次使用）启用脚本：`chmod +x upgrade.sh`
 2. 一键升级：`./upgrade.sh`（可选参数：`--tag vX.Y.Z`、`--no-venv`、`--yes`）。本地的 `tools/`、`roles/`、`skills/` 会始终保留不被覆盖。
@@ -258,401 +281,32 @@ go build -o cyberstrike-ai cmd/server/main.go
 * 建议/需要 `rsync` 用于安全同步代码。
 * 如果遇到 GitHub API 限流，运行前设置 `export GITHUB_TOKEN="..."` 再执行 `./upgrade.sh`。
-⚠️ **注意：** 仅适用于无兼容性变更的版本更新。若版本存在兼容性调整，此方法不适用。
+⚠️ **升级前必读：** 请查看目标版本的 Release Notes，确认配置、数据库和 API 是否变化。即使只是补丁版本也应先备份，不能仅凭版本号判断兼容性。
 **举例：** 无兼容性变更如 v1.3.1 → v1.3.2；有兼容性变更如 v1.3.1 → v1.4.0。项目采用语义化版本（SemVer）：仅第三位（补丁号）变更时通常可安全按上述步骤升级；次版本号或主版本号变更时可能涉及配置、数据或接口调整，需查阅 release notes 再决定是否适用本方法。
 ### 常用流程
 - **对话测试**：自然语言触发多步工具编排，SSE 实时输出。
 - **单代理 / 多代理**：聊天可选 **Eino 单代理**（`/api/eino-agent/stream`）与 **多代理**（`/api/multi-agent/stream` + `orchestration`）。多代理需 `multi_agent.enabled: true`。MCP 工具桥接一致。
 - **角色化测试**：从预设的安全测试角色（渗透测试、CTF、Web 应用扫描、API 安全测试等）中选择，自定义 AI 行为和可用工具。每个角色可应用自定义系统提示词，并可限制可用工具列表，实现聚焦的测试场景。
 - **图编排**：在 **图编排** 页拖拽节点、连线并保存流程；在角色中绑定 `workflow_id` 后，该角色对话将按图执行（Agent、MCP 工具、条件分支等）。跨节点传参优先用 `{{outputs.变量名}}`。详见 [图编排使用说明](docs/zh-CN/workflow-graph.md)。
 - **工具监控**：查看任务队列、执行日志、大文件附件。
 - **会话历史**：所有对话与工具调用保存在 SQLite，可随时重放。
 - **对话分组**：将对话按项目或主题组织到不同分组，支持置顶、重命名、删除等操作，所有数据持久化存储。
 - **漏洞管理**：在测试过程中创建、更新和跟踪发现的漏洞。支持按严重程度（严重/高/中/低/信息）、状态（待确认/已确认/已修复/误报）和对话进行过滤，查看统计信息并导出发现。
 - **批量任务管理**：创建任务队列，批量添加多个任务，执行前可编辑或删除任务，然后依次顺序执行。每个任务会作为独立对话执行，支持完整的状态跟踪（待执行/执行中/已完成/失败/已取消）和执行历史。
 - **WebShell 管理**：添加并管理 WebShell 连接（PHP/ASP/ASPX/JSP 或自定义类型）。使用虚拟终端执行命令（带命令历史与快捷命令），使用文件管理浏览、读取、编辑、上传与删除目标文件，并支持按路径导航和名称过滤。连接信息持久化存储于 SQLite，支持 GET/POST 及可配置命令参数（兼容冰蝎/蚁剑等）。
 - **内置 C2**：在 Web 界面或 `/api/c2/*` 创建/启动 **监听器**、生成 **Payload**、查看 **会话**、下发 **任务** 并订阅 **事件（SSE）**。智能体与外部客户端通过 **C2 MCP 工具族**（含 **`c2_task`** 等）编排；开启人机协同时，高风险任务可走审批。**仅用于已获明确授权的目标。**
 - **可视化配置**：在界面中切换模型、启停工具、设置迭代次数等。
 - **人机协同（HITL）**：侧栏设置协同模式与免审批工具（逗号或换行）；全局白名单见 `config.yaml` 的 `hitl.tool_whitelist`。审计 Agent 可通过 `hitl.audit_model` 单独配置低成本模型，适合人工审计压力较大时接管常规审批。点「**应用**」可写浏览器/服务端并合并新增工具进配置（**无需重启**）。**新对话**保留侧栏选择；导航 **人机协同** 处理待审批。从侧栏删掉工具不会自动从配置文件移除全局项，需手改 `config.yaml`。
 ### 默认安全措施
 - 设置面板内置必填校验，防止漏配 API Key/Base URL/模型。
 - 首次启动且无 RBAC 用户时，自动生成 24 位 `admin` 初始密码并在控制台输出（仅存于数据库，不再写入 `config.yaml`）。
 - 所有 API（除登录外）都需携带 Bearer Token，统一鉴权中间件拦截。
 - 每个工具执行都带有超时、日志和错误隔离。
 ## 进阶使用
 ### 角色化测试
 - **预设角色**：系统内置 12+ 个预设的安全测试角色（渗透测试、CTF、Web 应用扫描、API 安全测试、二进制分析、云安全审计等），位于 `roles/` 目录。
 - **自定义提示词**：每个角色可定义 `user_prompt`，会在用户消息前自动添加，引导 AI 采用特定的测试方法和关注重点。
 - **工具限制**：角色可指定 `tools` 列表，限制可用工具，实现聚焦的测试流程（如 CTF 角色限制为 CTF 专用工具）。
 - **Skills**：技能包位于 `skills_dir`；启用 **`multi_agent.eino_skills`** 后，**单代理与多代理**均可通过 Eino **`skill`** 工具按需加载。可选 **`eino_middleware`**（tool_search、plantask、reduction、checkpoint、Summarization 转录等）与本机 read_file/glob/grep 等见文档。
 - **轻松创建角色**：通过在 `roles/` 目录添加 YAML 文件即可创建自定义角色。每个角色定义 `name`、`description`、`user_prompt`、`icon`、`tools`、`enabled` 字段。
 - **Web 界面集成**：在聊天界面通过下拉菜单选择角色。角色选择会影响 AI 行为和可用工具建议。
 **创建自定义角色示例：**
 1. 在 `roles/` 目录创建 YAML 文件（如 `roles/custom-role.yaml`）：
   ```yaml
   name: 自定义角色
   description: 专用测试场景
   user_prompt: 你是一个专注于 API 安全的专业安全测试人员...
   icon: "\U0001F4E1"
   tools:
     - api-fuzzer
     - arjun
     - graphql-scanner
   enabled: true
   ```
 2. 重启服务或重新加载配置，角色会出现在角色选择下拉菜单中。
 ### 多代理模式（Eino：Deep / Plan-Execute / Supervisor）
 - **能力说明**：在 **Eino 单代理**（`/api/eino-agent*`）之外，多代理基于 CloudWeGo **Eino** `adk/prebuilt`：**`deep`**、**`plan_execute`**、**`supervisor`**；客户端 **`orchestration`** 选择（缺省 `deep`）。模式定位按 Eino ADK 最佳实践区分：**Deep** 适合复杂安全测试与 task 子代理协作；**Plan-Execute** 适合目标明确的规划 → 执行 → 重规划闭环；**Supervisor** 适合多个专业子代理动态分派的专家路由场景。
 - **Markdown 定义**（`agents_dir`，默认 `agents/`）：
  - **Deep 主代理**：`orchestrator.md` 或唯一 `kind: orchestrator` 的 `.md`；正文或 `multi_agent.orchestrator_instruction`，再回退 Eino 默认。
  - **Plan-Execute 主代理**：固定 **`orchestrator-plan-execute.md`**（另可配 `orchestrator_instruction_plan_execute`）。
  - **Supervisor 主代理**：固定 **`orchestrator-supervisor.md`**（另可配 `orchestrator_instruction_supervisor`）；至少需一名子代理，只有一名子代理时会提示专家路由价值有限。
  - **子代理**（**deep** / **supervisor**）：其余 `*.md`；标成 orchestrator 的不会进入 `task` 列表。
 - **界面管理**：**Agents → Agent 管理**；API `/api/multi-agent/markdown-agents`。
 - **配置项**：`multi_agent`：`enabled`、`robot_default_agent_mode`、`batch_use_multi_agent`、`max_iteration`、`plan_execute_loop_max_iterations`、各模式 orchestrator 指令字段、可选 YAML `sub_agents` 与目录合并（同 `id` → Markdown 优先）、**`eino_skills`**、**`eino_middleware`**。
 - **长任务与恢复**：`checkpoint_dir` 支持进程崩溃后 ADK **断点续跑**（与基于 trace 的「中断继续」不同）。`deep_model_retry_max_retries` 在同一次 LLM 调用内重试瞬时 API 失败。**Summarization** 触发压缩时会写入过滤后的 **transcript**，摘要消息中带路径，模型可用 `read_file` 找回扫描输出等压缩前细节。
 - **更多细节**：[docs/zh-CN/MULTI_AGENT_EINO.md](docs/zh-CN/MULTI_AGENT_EINO.md)（流式、机器人、批量、中间件差异）。
 ### Skills 技能系统（Agent Skills + Eino）
 - **目录规范**：与 [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 一致，**仅**需目录下的 **`SKILL.md`**：YAML 头只用官方的 **`name` 与 `description`**，正文为 Markdown。可选同目录其他文件（`FORMS.md`、`REFERENCE.md`、`scripts/*` 等）。**不使用 `SKILL.yaml`**（Claude / Eino 官方均无此文件）；章节、`scripts/` 列表、渐进式行为由运行时从正文与磁盘 **自动推导**。
 - **运行侧重构**：**`skills_dir`** 为技能包唯一根目录；**多代理** 通过 Eino 官方 **`skill`** 中间件做 **渐进式披露**（模型按 **name** 调用 `skill`，而非一次性注入全文）。由 **`multi_agent.eino_skills`** 控制：`disable`、`filesystem_tools`（本机读写与 Shell）、`skill_tool_name`。
 - **Eino / 知识流水线**：技能包可切分为 `schema.Document`，供 `FilesystemSkillsRetriever`（`skills.AsEinoRetriever()`）在 **compose** 图（如索引/编排）中使用。
 - **HTTP 管理**：`/api/skills` 列表与 `depth=summary|full`、`section`、`resource_path` 等仍用于 Web 与运维；**模型侧** 多代理走 **`skill`** 工具，而非 MCP。
 - **可选 `eino_middleware`**：如 `tool_search`（动态工具列表）、`patch_tool_calls`、**`plantask`**（Eino `TaskCreate` / `TaskGet` / `TaskUpdate` / `TaskList`；JSON 存于 `skills_dir/.eino/plantask/<会话ID>/`；**全部**任务标为 completed 后 Eino 会清理任务文件）、`reduction`、**`checkpoint_dir`**（如 `data/eino-checkpoints/`）、**`deep_model_retry_max_retries`**、**`deep_output_key`**、task 描述前缀等，见 `config.yaml` 与 `internal/config/config.go`。
 - **自带示例**：`skills/cyberstrike-eino-demo/`；说明见 `skills/README.md`。
 **新建技能：**
 1. 在 `skills/` 下创建 `<skill-id>/`，放入标准 `SKILL.md`（及任意可选文件），或直接解压开源技能包到该目录。
 2. 启用 **`multi_agent.eino_skills`** 并使用 **多代理** 会话，由模型通过 **`skill`** 工具按包 **name** 加载。
 ### 工具编排与扩展
 - `tools/*.yaml` 定义命令、参数、提示词与元数据，可热加载。
 - `security.tools_dir` 指向目录即可批量启用；仍支持在主配置里内联定义。
 - **大工具输出**：超过 `reduction_max_length_for_trunc` 时由 Eino reduction 摘要，完整内容落盘至 `tmp/reduction/`；按 `<persisted-output>` 中的路径用 `read_file` 读取。
 - **结果压缩/摘要**：多兆字节日志可先压缩或生成摘要再写入 SQLite，减小档案体积。
 **自定义工具的一般步骤**
 1. 复制 `tools/` 下现有示例（如 `tools/nmap.yaml` 或 `tools/ffuf.yaml`）。
 2. 修改 `name`、`command`、`args`、`short_description` 等基础信息。
 3. 在 `parameters[]` 中声明位置参数或带 flag 的参数，方便智能体自动拼装命令。
 4. 视需要补充 `description` 或 `notes`，给 AI 额外上下文或结果解读提示。
 5. 重启服务或在界面中重新加载配置，新工具即可在 Settings 面板中启用/禁用。
 ### 攻击链分析
 - 智能体解析每次对话，抽取目标、工具、漏洞与因果关系。
 - Web 端可交互式查看链路节点、风险级别及时间轴，支持导出报告。
 ### WebShell 管理
 - **连接管理**：在 Web 界面进入 **WebShell 管理**，可添加、编辑或删除 WebShell 连接。每条连接包含：Shell 地址、密码/密钥、Shell 类型（PHP/ASP/ASPX/JSP/自定义）、请求方式（GET/POST）、命令参数名（默认 `cmd`）、备注等信息，并持久化存储在 SQLite，兼容冰蝎、蚁剑等常见客户端。
 - **虚拟终端**：选择连接后，在 **虚拟终端** 标签页中执行任意命令，支持命令历史与常用快捷命令（whoami/id/ls/pwd 等），输出在浏览器中实时显示，支持 Ctrl+L 清屏。
 - **文件管理**：在 **文件管理** 标签页中可列出目录、读取/编辑文件、删除文件、新建文件/目录、上传文件（大文件分片上传）、重命名路径以及下载勾选文件，并支持面包屑导航与名称过滤。
 - **AI 助手**：在 **AI 助手** 标签页中与智能体对话，由系统自动结合当前 WebShell 连接执行工具与命令，侧边栏展示该连接下的所有历史会话，支持多轮追踪与查看。
 - **连通性测试**：使用 **测试连通性** 可在执行命令前通过一次 `echo 1` 调用校验 Shell 地址、密码与命令参数是否正确。
 - **持久化**：所有 WebShell 连接与相关 AI 会话均保存在 SQLite（与对话共用数据库），服务重启后仍可继续使用。
 ### 内置 C2（Command & Control）
 - **定位**：平台内置的 **AI 原生** C2 能力栈——监听器接入植入体（Beacon），服务端以 SQLite 持久化 **会话** 与 **任务**，通过 **事件总线** 推送变更（含 **SSE**），并由鉴权后的 **REST** 与 MCP 统一对外。
 - **监听器与传输**：支持 `tcp_reverse`、`http_beacon`、`https_beacon`、`websocket`；按监听器独立密钥；数据库中标记为运行中的监听器可在 **服务重启后尝试恢复**。
 - **与智能体联动**：通过 **`c2_task` 等 C2 MCP 工具** 与现有对话/多代理工具链协同；在会话策略需要时，危险任务类型可走既有 **人机协同（HITL）** 审批流。
 - **安全提示**：**仅**在实验环境或 **已获完整书面授权** 的对抗演练中使用；结合网络隔离、强鉴权及 HITL/白名单等策略管控风险。
 ### MCP 全场景
 - **Web 模式**：自带 HTTP MCP 服务供前端调用。
 - **MCP stdio 模式**：`go run cmd/mcp-stdio/main.go` 可接入 Cursor/命令行。
 - **外部 MCP 联邦**：在设置中注册第三方 MCP（HTTP/stdio/SSE），按需启停并实时查看调用统计与健康度。
 - **可选 MCP 服务**：项目中的 [`mcp-servers/`](mcp-servers/README_CN.md) 目录提供独立 MCP（如反向 Shell），采用标准 MCP stdio，可在 CyberStrikeAI（设置 → 外部 MCP）、Cursor、VS Code 等任意支持 MCP 的客户端中使用。
 #### MCP stdio 快速集成
 1. **编译可执行文件**（在项目根目录执行）：
   ```bash
   go build -o cyberstrike-ai-mcp cmd/mcp-stdio/main.go
   ```
 2. **在 Cursor 中配置**  
   打开 `Settings → Tools & MCP → Add Custom MCP`，选择 **Command**，指定编译后的程序与配置文件：
   ```json
   {
     "mcpServers": {
       "cyberstrike-ai": {
         "command": "/absolute/path/to/cyberstrike-ai-mcp",
         "args": [
           "--config",
           "/absolute/path/to/config.yaml"
         ]
       }
     }
   }
   ```
   将路径替换成你本地的实际地址，Cursor 会自动启动 stdio 版本的 MCP。
 #### MCP HTTP 快速集成（Cursor / Claude Code）
 HTTP MCP 服务在独立端口（默认 `8081`）运行，支持 **Header 鉴权**：仅携带正确 header 的客户端可调用工具。
 1. **在配置中启用 MCP** – 在 `config.yaml` 中设置 `mcp.enabled: true`，并按需设置 `mcp.host` / `mcp.port`。若需鉴权（端口对外暴露时建议开启），可设置：
   - `mcp.auth_header`：鉴权用的 header 名（如 `X-MCP-Token`）；
   - `mcp.auth_header_value`：鉴权密钥。**留空**时，首次启动会自动生成随机密钥并写回配置文件。
 2. **启动服务** – 执行 `./run.sh` 或 `go run cmd/server/main.go`。MCP 端点为 `http://<host>:<port>/mcp`（例如 `http://localhost:8081/mcp`）。
 3. **从终端复制 JSON** – 启用 MCP 后，启动时会在终端打印一段 **可直接复制的 JSON**。若 `auth_header_value` 留空，会自动生成并写入配置，打印内容中会包含 URL 与 headers。
 4. **在 Cursor 或 Claude Code 中使用**：
   - **Cursor**：将整段 JSON 粘贴到 `~/.cursor/mcp.json` 或项目下的 `.cursor/mcp.json` 的 `mcpServers` 中（或合并进现有 `mcpServers`）。
   - **Claude Code**：粘贴到 `.mcp.json` 或 `~/.claude.json` 的 `mcpServers` 中。
 终端打印示例（开启鉴权时）：
 ```json
 {
  "mcpServers": {
    "cyberstrike-ai": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "X-MCP-Token": "<自动生成或你配置的值>"
      },
      "type": "http"
    }
  }
 }
 ```
 若不配置 `auth_header` / `auth_header_value`，则端点不鉴权（仅适合本机或可信网络）。
 #### 外部 MCP 联邦（HTTP/stdio/SSE）
 CyberStrikeAI 支持通过三种传输模式连接外部 MCP 服务器：
 - **HTTP 模式** – 通过 HTTP POST 进行传统的请求/响应通信
 - **stdio 模式** – 通过标准输入/输出进行进程间通信
 - **SSE 模式** – 通过 Server-Sent Events 实现实时流式通信
 添加外部 MCP 服务器：
 1. 打开 Web 界面，进入 **设置 → 外部MCP**。
 2. 点击 **添加外部MCP**，以 JSON 格式提供配置：
   **HTTP 模式示例：**
   ```json
   {
     "my-http-mcp": {
       "transport": "http",
       "url": "http://127.0.0.1:8081/mcp",
       "description": "HTTP MCP 服务器",
       "timeout": 30
     }
   }
   ```
   **stdio 模式示例：**
   ```json
   {
     "my-stdio-mcp": {
       "command": "python3",
       "args": ["/path/to/mcp-server.py"],
       "description": "stdio MCP 服务器",
       "timeout": 30
     }
   }
   ```
   **SSE 模式示例：**
   ```json
   {
     "my-sse-mcp": {
       "transport": "sse",
       "url": "http://127.0.0.1:8082/sse",
       "description": "SSE MCP 服务器",
       "timeout": 30
     }
   }
   ```
 3. 点击 **保存**，然后点击 **启动** 连接服务器。
 4. 实时监控连接状态、工具数量和健康度。
 **SSE 模式优势：**
 - 通过 Server-Sent Events 实现实时双向通信
 - 适用于需要持续数据流的场景
 - 对于基于推送的通知，延迟更低
 可在 `cmd/test-sse-mcp-server/` 目录找到用于验证的测试 SSE MCP 服务器。
-### 知识库功能
+## 配置
 - **向量检索**：AI 智能体在对话过程中可自动调用 `search_knowledge_base` 工具搜索知识库中的安全知识。
 - **RAG 管线（始终启用）**：**MultiQuery**（LLM 查询改写）→ 向量预取与融合 → **HTTP 精排**（DashScope `gte-rerank` 或 Cohere 兼容 `/v1/rerank`）→ 后处理（规范化去重、字符/token 预算、最终 top_k）。精排失败时自动降级为融合排序，检索仍可用。
 - **向量相似度**：基于嵌入余弦相似度与相似度阈值过滤（与 Eino `retriever.Retriever` 语义一致）。
 - **自动索引**：扫描 `knowledge_base/` 目录下的 Markdown 文件，自动构建向量嵌入索引（Eino Markdown 标题切分 + 递归分块）。
 - **Web 管理**：通过 Web 界面创建、更新、删除知识项，支持分类管理；设置页可配置 MultiQuery / 精排 / 预取候选数。
 - **检索日志**：记录所有知识检索操作，便于审计与调试。
-**知识库配置步骤：**
+请以 [`config.example.yaml`](config.example.yaml) 作为权威配置模板，只复制当前环境需要的配置。最少需要配置服务监听地址和一个 OpenAI 兼容模型：
 1. **启用功能**：在 `config.yaml` 中设置 `knowledge.enabled: true`：
   ```yaml
   knowledge:
     enabled: true
     base_path: knowledge_base
     embedding:
       provider: openai
       model: text-embedding-v4
       base_url: "https://api.openai.com/v1"  # 或你的嵌入模型 API
       api_key: "sk-xxx"
     retrieval:
       top_k: 5
       similarity_threshold: 0.7
       multi_query:
         max_queries: 4        # LLM 改写变体上限（始终启用）
       rerank:                 # 精排始终启用；留空则继承 openai/embedding 凭据
         provider: ""          # 空=按 base_url 推断 dashscope | cohere
         model: ""             # 空=DashScope→gte-rerank，Cohere→rerank-multilingual-v3.0
         base_url: ""
         api_key: ""
       post_retrieve:
         prefetch_top_k: 20    # 每条 MultiQuery 变体的向量候选数；0=max(top_k×4, 20)
         max_context_chars: 0
         max_context_tokens: 0
   ```
 2. **添加知识文件**：将 Markdown 文件放入 `knowledge_base/` 目录，按分类组织（如 `knowledge_base/SQL注入/README.md`）。
 3. **扫描索引**：在 Web 界面中点击"扫描知识库"，系统会自动导入文件并构建向量索引。
 4. **对话中使用**：AI 智能体在需要安全知识时会自动调用知识检索工具。你也可以显式要求："搜索知识库中关于 SQL 注入的技术"。
 **知识库结构说明：**
 - 文件按分类组织（目录名作为分类）。
 - 每个 Markdown 文件自动切块并生成向量嵌入。
 - 支持增量更新，修改后的文件会自动重新索引。
 ### 自动化与安全
 - **REST API**：认证、会话、任务、监控、漏洞管理、角色管理等接口全部开放，可与 CI/CD 集成。
 - **多代理 API**：`POST /api/multi-agent/stream`（SSE，需启用多代理）、`POST /api/multi-agent`（非流式）；Markdown 子代理/主代理管理见 `/api/multi-agent/markdown-agents`（列表/读写/增删）。
 - **角色管理 API**：通过 `/api/roles` 端点管理安全测试角色：`GET /api/roles`（列表）、`GET /api/roles/:name`（获取角色）、`POST /api/roles`（创建角色）、`PUT /api/roles/:name`（更新角色）、`DELETE /api/roles/:name`（删除角色）。角色以 YAML 文件形式存储在 `roles/` 目录，支持热加载。
 - **漏洞管理 API**：通过 `/api/vulnerabilities` 端点管理漏洞：`GET /api/vulnerabilities`（列表，支持过滤）、`POST /api/vulnerabilities`（创建）、`GET /api/vulnerabilities/:id`（获取）、`PUT /api/vulnerabilities/:id`（更新）、`DELETE /api/vulnerabilities/:id`（删除）、`GET /api/vulnerabilities/stats`（统计）。
 - **批量任务 API**：通过 `/api/batch-tasks` 端点管理批量任务队列：`POST /api/batch-tasks`（创建队列）、`GET /api/batch-tasks`（列表）、`GET /api/batch-tasks/:queueId`（获取队列）、`POST /api/batch-tasks/:queueId/start`（开始执行）、`POST /api/batch-tasks/:queueId/cancel`（取消）、`DELETE /api/batch-tasks/:queueId`（删除队列）、`POST /api/batch-tasks/:queueId/tasks`（添加任务）、`PUT /api/batch-tasks/:queueId/tasks/:taskId`（更新任务）、`DELETE /api/batch-tasks/:queueId/tasks/:taskId`（删除任务）。任务依次顺序执行，每个任务创建独立对话，支持完整状态跟踪。
 - **WebShell API**：通过 `/api/webshell/connections`（GET 列表、POST 创建、PUT 更新、DELETE 删除）及 `/api/webshell/exec`（执行命令）、`/api/webshell/fileop`（列出/读取/写入/删除文件）管理 WebShell 连接与执行操作。
 - **C2 API**：在 `/api/c2/*` 管理监听器、会话、任务、Payload、文件与事件（如监听器增删改查/启停、会话休眠、任务创建/取消/等待、Payload 构建/下载、事件流等）。
 - **任务控制**：支持暂停/终止长任务、修改参数后重跑、流式获取日志。
 - **安全管理**：`/api/auth/change-password` 可即时轮换口令；建议在暴露 MCP 端口时配合网络层 ACL。
 ## 配置参考
 ```yaml
 auth:
  session_duration_hours: 12
 server:
-  host: "0.0.0.0"
+  host: "127.0.0.1"
  port: 8080
 log:
  level: "info"
  output: "stdout"
 mcp:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  auth_header: "X-MCP-Token"       # 可选；留空则不鉴权
  auth_header_value: ""            # 可选；留空则首次启动自动生成并写回
 openai:
-  api_key: "sk-xxx"
+  api_key: "${OPENAI_API_KEY}"
-  base_url: "https://api.deepseek.com/v1"
+  base_url: "https://api.openai.com/v1"
-  model: "deepseek-chat"
+  model: "your-model"
 database:
  path: "data/conversations.db"
  knowledge_db_path: "data/knowledge.db"  # 可选：知识库独立数据库
 security:
  tools_dir: "tools"
 knowledge:
  enabled: false  # 是否启用知识库功能
  base_path: "knowledge_base"  # 知识库目录路径
  embedding:
    provider: "openai"  # 嵌入模型提供商（目前仅支持 openai）
    model: "text-embedding-v4"  # 嵌入模型名称
    base_url: ""  # 留空则使用 OpenAI 配置的 base_url
    api_key: ""  # 留空则使用 OpenAI 配置的 api_key
  retrieval:
    top_k: 5  # 检索返回的 Top-K 结果数量
    similarity_threshold: 0.7  # 余弦相似度阈值（0-1），低于此值的结果将被过滤
    multi_query:
      max_queries: 4  # MultiQuery 改写变体上限（始终启用）
    rerank:  # HTTP 精排（始终启用）；留空则继承 openai/embedding 凭据
      provider: ""
      model: ""
      base_url: ""
      api_key: ""
    post_retrieve:
      prefetch_top_k: 20  # 每条 MultiQuery 变体；0=max(top_k×4, 20)
      max_context_chars: 0
      max_context_tokens: 0
 roles_dir: "roles"  # 角色配置文件目录（相对于配置文件所在目录）
 skills_dir: "skills"  # Skills 目录（相对于配置文件所在目录）
 agents_dir: "agents"  # 多代理 Markdown（主代理 orchestrator.md + 子代理 *.md）
 multi_agent:
  enabled: false
  default_mode: "eino_single"   # eino_single | multi（开启多代理时的界面默认模式）
  robot_default_agent_mode: eino_single
  batch_use_multi_agent: false
  orchestrator_instruction: ""  # Deep；orchestrator.md 正文为空时使用
  # orchestrator_instruction_plan_execute / orchestrator_instruction_supervisor 可选
  # eino_skills: { disable: false, filesystem_tools: true, skill_tool_name: skill }
  # eino_middleware: plantask_enable、checkpoint_dir、deep_model_retry_max_retries、deep_output_key 等
 project:
  enabled: true              # 启用项目黑板与事实 MCP 工具
  fact_index_max_runes: 65000
  fact_summary_max_runes: 24000
  default_inject_deprecated: false
 ```
-### 工具模版示例（`tools/nmap.yaml`）
+不要提交真实凭证。将服务暴露到 localhost 之外前，请阅读[配置参考](docs/zh-CN/configuration.md)、[推荐配置画像](docs/zh-CN/configuration-profiles.md)和[安全加固指南](docs/zh-CN/security-hardening.md)。
 ```yaml
 name: "nmap"
 command: "nmap"
 args: ["-sT", "-sV", "-sC"]
 enabled: true
 short_description: "网络资产扫描与服务指纹识别"
 parameters:
  - name: "target"
    type: "string"
    description: "IP 或域名"
    required: true
    position: 0
  - name: "ports"
    type: "string"
    flag: "-p"
    description: "端口范围，如 1-1000"
 ```
 ### 角色配置示例（`roles/渗透测试.yaml`）
 ```yaml
 name: 渗透测试
 description: 专业渗透测试专家，全面深入的漏洞检测
 user_prompt: 你是一个专业的网络安全渗透测试专家。请使用专业的渗透测试方法和工具，对目标进行全面的安全测试，包括但不限于SQL注入、XSS、CSRF、文件包含、命令执行等常见漏洞。
 icon: "\U0001F3AF"
 tools:
  - nmap
  - sqlmap
  - nuclei
  - burpsuite
  - metasploit
  - httpx
  - record_vulnerability
  - list_knowledge_risk_types
  - search_knowledge_base
 enabled: true
 ```
 ## 相关文档
- [文档导航](docs/README.md)：部署、配置、安全模型、API、知识库、C2、WebShell、MCP、开发、测试、排错等完整专题入口。
+- **新用户：** [部署指南](docs/zh-CN/deployment.md) → [配置参考](docs/zh-CN/configuration.md) → [排错指南](docs/zh-CN/troubleshooting.md)
- [部署指南](docs/zh-CN/deployment.md)：源码/二进制运行、HTTPS、反向代理、systemd、备份、升级与回滚。
+- **运维人员：** [配置画像](docs/zh-CN/configuration-profiles.md) → [安全加固](docs/zh-CN/security-hardening.md) → [运维 Runbooks](docs/zh-CN/runbooks.md)
- [运维 Runbooks](docs/zh-CN/runbooks.md)：生产部署、外部 MCP、知识库、授权 Web 测试、C2 清理等可执行流程。
+- **集成开发：** [API 参考](docs/zh-CN/api-reference.md) → [API Recipes](docs/zh-CN/api-recipes.md) → [MCP 联邦](docs/zh-CN/mcp-federation.md)
- [安全加固指南](docs/zh-CN/security-hardening.md)：上线前基线、HITL 白名单、反向代理、文件权限和周期巡检。
+- **项目贡献：** [开发者指南](docs/zh-CN/developer-guide.md) → [测试指南](docs/zh-CN/testing.md) → [贡献规范](docs/zh-CN/contributing-guide.md)
- [API Recipes](docs/zh-CN/api-recipes.md)：登录、Agent、流式、多代理、上传、漏洞、知识库和审计导出调用示例。
+- **全部专题：** [中文文档](docs/zh-CN/README.md) · [双语文档索引](docs/README.md)
 - [配置参考](docs/zh-CN/configuration.md)：`config.yaml` 各配置段、推荐值和修改建议。
 - [安全模型](docs/zh-CN/security-model.md)：认证、工具执行、HITL、审计、C2/WebShell 和数据安全边界。
 - [RBAC 权限管理](docs/zh-CN/rbac.md)：平台用户、系统/自定义角色、权限目录、逐权限 Scope、资源授权、Agent/MCP/机器人边界与 API 示例。
 - [API 参考](docs/zh-CN/api-reference.md)：OpenAPI、认证、Agent、项目、知识库、C2、WebShell 等接口入口。
 - [多代理模式（Eino）](docs/zh-CN/MULTI_AGENT_EINO.md)：**Deep**、**Plan-Execute**、**Supervisor**、`agents/*.md`、`eino_skills` / `eino_middleware`、接口与流式说明。
 - [图编排使用说明](docs/zh-CN/workflow-graph.md)：可视化流程搭建、节点配置、`previous` / `outputs` 变量传参与角色绑定。
 - [机器人使用说明](docs/zh-CN/robot.md)：各平台接入、RBAC 逐用户绑定/服务账号模式、发送者白名单、命令、验证与排查。
 - [人机协同最佳实践](docs/zh-CN/hitl-best-practices.md)：审批方模式、白名单、审计 Agent 提示词策略与独立小模型配置。
 ## 项目结构
@@ -667,6 +321,7 @@ CyberStrikeAI/
 ├── agents/              # 多代理 Markdown（orchestrator.md + 子代理 *.md）
 ├── docs/                # 专题文档（部署、配置、安全、API、知识库、C2、WebShell 等）
 ├── images/              # 文档配图
 ├── scripts/             # 仓库维护检查，包括文档校验
 ├── config.yaml          # 运行配置
 ├── run.sh               # 启动脚本
 └── README*.md
@@ -732,3 +387,4 @@ CyberStrikeAI 是一个专业的安全测试平台，旨在帮助安全研究人
 ---
 欢迎提交 Issue/PR 贡献新的工具模版或优化建议！
@@ -1,68 +1,85 @@
 # CyberStrikeAI Documentation
-Documentation is split by language:
+[中文](#中文文档) | [English](#english-documentation)
- [中文文档](zh-CN/)
+CyberStrikeAI documentation is organized by user journey. Start with deployment, then move to the topic that matches your task.
 - [English docs](en-US/)
 ## 中文文档
- [部署指南](zh-CN/deployment.md)
+### 按目标开始
- [运维 Runbooks](zh-CN/runbooks.md)
+
- [配置画像](zh-CN/configuration-profiles.md)
+- **快速体验**：[部署指南](zh-CN/deployment.md) → [配置参考](zh-CN/configuration.md) → [排错指南](zh-CN/troubleshooting.md)
- [安全加固指南](zh-CN/security-hardening.md)
+- **生产部署**：[配置画像](zh-CN/configuration-profiles.md) → [安全加固](zh-CN/security-hardening.md) → [运维 Runbooks](zh-CN/runbooks.md) → [审计与监控](zh-CN/audit-and-monitoring.md)
- [API Recipes](zh-CN/api-recipes.md)
+- **接入与自动化**：[API 参考](zh-CN/api-reference.md) → [API Recipes](zh-CN/api-recipes.md) → [MCP 联邦](zh-CN/mcp-federation.md)
- [贡献规范](zh-CN/contributing-guide.md)
+- **参与开发**：[开发者指南](zh-CN/developer-guide.md) → [测试指南](zh-CN/testing.md) → [贡献规范](zh-CN/contributing-guide.md)
- [配置参考](zh-CN/configuration.md)
+
- [安全模型](zh-CN/security-model.md)
+### 核心概念与编排
- [RBAC 权限管理](zh-CN/rbac.md)
+
 - [架构说明](zh-CN/architecture.md)
- [API 参考](zh-CN/api-reference.md)
+- [安全模型](zh-CN/security-model.md)
 - [排错指南](zh-CN/troubleshooting.md)
 - [审计与监控](zh-CN/audit-and-monitoring.md)
 - [知识库](zh-CN/knowledge-base.md)
 - [C2 使用说明](zh-CN/c2.md)
 - [WebShell 管理](zh-CN/webshell.md)
 - [MCP 联邦](zh-CN/mcp-federation.md)
 - [Agent 与角色](zh-CN/agent-and-role-guide.md)
 - [Skills 指南](zh-CN/skills-guide.md)
- [插件开发](zh-CN/plugin-development.md)
+- [Eino 多代理](zh-CN/MULTI_AGENT_EINO.md)
- [发布流程](zh-CN/release-process.md)
+- [图编排](zh-CN/workflow-graph.md)
 - [测试指南](zh-CN/testing.md)
 - [图编排使用说明](zh-CN/workflow-graph.md)
 - [人机协同最佳实践](zh-CN/hitl-best-practices.md)
- [机器人使用说明](zh-CN/robot.md)
+
 ### 功能指南
 - [知识库](zh-CN/knowledge-base.md)
 - [RBAC 权限管理](zh-CN/rbac.md)
 - [机器人接入](zh-CN/robot.md)
 - [视觉分析](zh-CN/VISION.md)
- [前端国际化方案](zh-CN/frontend-i18n.md)
+- [WebShell 管理](zh-CN/webshell.md)
- [Eino 多代理改造说明](zh-CN/MULTI_AGENT_EINO.md)
+- [C2 使用说明](zh-CN/c2.md)
-## English Docs
+### 开发与发布
 - [开发者指南](zh-CN/developer-guide.md)
 - [插件开发](zh-CN/plugin-development.md)
 - [前端国际化](zh-CN/frontend-i18n.md)
 - [测试指南](zh-CN/testing.md)
 - [贡献规范](zh-CN/contributing-guide.md)
 - [发布流程](zh-CN/release-process.md)
 ## English Documentation
 ### Choose a path
 - **Try locally**: [Deployment](en-US/deployment.md) → [Configuration](en-US/configuration.md) → [Troubleshooting](en-US/troubleshooting.md)
 - **Run in production**: [Configuration Profiles](en-US/configuration-profiles.md) → [Security Hardening](en-US/security-hardening.md) → [Runbooks](en-US/runbooks.md) → [Audit and Monitoring](en-US/audit-and-monitoring.md)
 - **Integrate and automate**: [API Reference](en-US/api-reference.md) → [API Recipes](en-US/api-recipes.md) → [MCP Federation](en-US/mcp-federation.md)
 - **Contribute code**: [Developer Guide](en-US/developer-guide.md) → [Testing](en-US/testing.md) → [Contributing](en-US/contributing-guide.md)
 ### Concepts and orchestration
 - [Deployment Guide](en-US/deployment.md)
 - [Runbooks](en-US/runbooks.md)
 - [Configuration Profiles](en-US/configuration-profiles.md)
 - [Security Hardening](en-US/security-hardening.md)
 - [API Recipes](en-US/api-recipes.md)
 - [Contributing Guide](en-US/contributing-guide.md)
 - [Configuration Reference](en-US/configuration.md)
 - [Security Model](en-US/security-model.md)
 - [RBAC Administration](en-US/rbac.md)
 - [Architecture](en-US/architecture.md)
- [API Reference](en-US/api-reference.md)
+- [Security Model](en-US/security-model.md)
- [Troubleshooting](en-US/troubleshooting.md)
+- [Agents and Roles](en-US/agent-and-role-guide.md)
- [Audit and Monitoring](en-US/audit-and-monitoring.md)
+- [Skills](en-US/skills-guide.md)
- [Knowledge Base](en-US/knowledge-base.md)
+- [Eino Multi-Agent](en-US/MULTI_AGENT_EINO.md)
- [C2 Guide](en-US/c2.md)
+- [Graph Orchestration](en-US/workflow-graph.md)
 - [WebShell Management](en-US/webshell.md)
 - [MCP Federation](en-US/mcp-federation.md)
 - [Agent and Role Guide](en-US/agent-and-role-guide.md)
 - [Skills Guide](en-US/skills-guide.md)
 - [Plugin Development](en-US/plugin-development.md)
 - [Release Process](en-US/release-process.md)
 - [Testing Guide](en-US/testing.md)
 - [Graph Orchestration Guide](en-US/workflow-graph.md)
 - [HITL Best Practices](en-US/hitl-best-practices.md)
- [Robot / Chatbot Guide](en-US/robot.md)
+
 ### Feature guides
 - [Knowledge Base](en-US/knowledge-base.md)
 - [RBAC Administration](en-US/rbac.md)
 - [Robot / Chatbot](en-US/robot.md)
 - [Vision Analysis](en-US/VISION.md)
 - [WebShell Management](en-US/webshell.md)
 - [C2 Guide](en-US/c2.md)
 ### Development and release
 - [Developer Guide](en-US/developer-guide.md)
 - [Plugin Development](en-US/plugin-development.md)
 - [Frontend i18n](en-US/frontend-i18n.md)
- [Eino Multi-Agent Notes](en-US/MULTI_AGENT_EINO.md)
+- [Testing](en-US/testing.md)
 - [Contributing](en-US/contributing-guide.md)
 - [Release Process](en-US/release-process.md)
 ## Documentation conventions
 - Commands assume the repository root unless stated otherwise.
 - Examples use placeholders; never commit real credentials or target systems without explicit authorization.
 - Runtime behavior and configuration defaults are authoritative in `config.example.yaml` and the source code. If a document differs, report it as documentation drift.
@@ -1,30 +1,32 @@
-# English Docs
+# English Documentation
- [Deployment Guide](deployment.md): deployment modes, HTTPS, reverse proxy, systemd, backup, upgrade, and acceptance checks.
+[Documentation home](../README.md) | [中文](../zh-CN/README.md)
- [Runbooks](runbooks.md): operational steps for production setup, external MCP, KB, Web testing, C2 cleanup, and tool debugging.
+
- [Configuration Profiles](configuration-profiles.md): recommended profiles for dev, internal team, knowledge-only, production, C2, and MCP automation.
+## Choose a path
- [Security Hardening](security-hardening.md): pre-launch baseline, reverse proxy, HITL allowlist, file permissions, and periodic review.
+
- [API Recipes](api-recipes.md): examples for login, Agent, streaming, multi-agent, uploads, vulnerabilities, KB, MCP, and audit export.
+- **Try locally**: [Deployment](deployment.md) → [Configuration](configuration.md) → [Troubleshooting](troubleshooting.md)
- [Contributing Guide](contributing-guide.md): checklists for APIs, config, tools, frontend, DB, high-risk features, and docs.
+- **Run in production**: [Configuration Profiles](configuration-profiles.md) → [Security Hardening](security-hardening.md) → [Runbooks](runbooks.md) → [Audit and Monitoring](audit-and-monitoring.md)
- [Configuration Reference](configuration.md): `config.yaml` fields, hot-apply boundaries, recommended values, and source anchors.
+- **Integrate and automate**: [API Reference](api-reference.md) → [API Recipes](api-recipes.md) → [MCP Federation](mcp-federation.md)
- [Security Model](security-model.md): trust boundaries, HITL, tool execution, C2/WebShell, and data safety.
+- **Contribute code**: [Developer Guide](developer-guide.md) → [Testing](testing.md) → [Contributing](contributing-guide.md)
- [RBAC Administration](rbac.md): platform users, system/custom roles, permission catalog, per-permission scopes, resource assignments, Agent/MCP/robot boundaries, and API examples.
+
- [Architecture](architecture.md): request flow, module relationships, complexity hotspots, and design trade-offs.
+## Concepts and orchestration
- [API Reference](api-reference.md): authentication, OpenAPI, SSE, stability tiers, and common endpoints.
+
- [Troubleshooting](troubleshooting.md): diagnostic order, minimal commands, common misdiagnoses, and issue template.
+- [Architecture](architecture.md) · [Security Model](security-model.md) · [RBAC](rbac.md)
- [Audit and Monitoring](audit-and-monitoring.md): platform audit, tool monitoring, HITL logs, and retention.
+- [Agents and Roles](agent-and-role-guide.md) · [Skills](skills-guide.md) · [Eino Multi-Agent](MULTI_AGENT_EINO.md)
- [Knowledge Base](knowledge-base.md): indexing pipeline, retrieval tuning, log analysis, and content writing.
+- [Graph Orchestration](workflow-graph.md) · [HITL Best Practices](hitl-best-practices.md)
- [C2 Guide](c2.md): lifecycle, task classification, event review, and safety guidance.
+
- [WebShell Management](webshell.md): operation tiers, naming, AI guardrails, and troubleshooting.
+## Feature guides
- [MCP Federation](mcp-federation.md): built-in MCP, external MCP, lifecycle, and tool naming.
+
- [Agent and Role Guide](agent-and-role-guide.md): roles, sub-agents, Skills, orchestration modes, and tool visibility.
+- [Knowledge Base](knowledge-base.md) · [Robot / Chatbot](robot.md) · [Vision](VISION.md)
- [Skills Guide](skills-guide.md): Skill structure, progressive disclosure, anti-patterns, and local-tool risk.
+- [WebShell](webshell.md) · [C2](c2.md) · [MCP Federation](mcp-federation.md)
- [Plugin Development](plugin-development.md): API plugins, MCP plugins, resource-pack plugins, and security boundaries.
+
- [Release Process](release-process.md): release risk, config compatibility, DB migrations, and acceptance checks.
+## Operations and reference
- [Testing Guide](testing.md): test layers, regression focus, test data, and failure cases.
+
- [Graph Orchestration Guide](workflow-graph.md)
+- [Deployment](deployment.md) · [Configuration](configuration.md) · [Configuration Profiles](configuration-profiles.md)
- [HITL Best Practices](hitl-best-practices.md)
+- [Security Hardening](security-hardening.md) · [Audit and Monitoring](audit-and-monitoring.md) · [Runbooks](runbooks.md)
- [Robot / Chatbot Guide](robot.md)
+- [API Reference](api-reference.md) · [API Recipes](api-recipes.md) · [Troubleshooting](troubleshooting.md)
- [Vision Analysis](VISION.md)
+
- [Frontend i18n](frontend-i18n.md)
+## Development and release
- [Eino Multi-Agent Notes](MULTI_AGENT_EINO.md)
+
 - [Developer Guide](developer-guide.md) · [Plugin Development](plugin-development.md) · [Frontend i18n](frontend-i18n.md)
 - [Testing](testing.md) · [Contributing](contributing-guide.md) · [Release Process](release-process.md)
@@ -103,6 +103,14 @@ Update:
 - `docs/zh-CN/README.md`
 - `docs/en-US/README.md`
 Before submitting documentation changes, run:
 ```bash
 python3 scripts/check-docs.py
 ```
 The check verifies local links, fenced code blocks, bilingual filename parity, locale index coverage, and the Go version documented by the root READMEs. Keep versioned examples derived from authoritative files such as `go.mod` and `config.example.yaml` whenever possible.
 ## Review Focus
 Prioritize:
@@ -1,30 +1,32 @@
 # 中文文档
- [部署指南](deployment.md)：部署形态、HTTPS、反向代理、systemd、备份、升级和验收。
+[文档首页](../README.md) | [English](../en-US/README.md)
- [运维 Runbooks](runbooks.md)：生产部署、外部 MCP、知识库、Web 测试、C2 清理和工具排障的操作步骤。
+
- [配置画像](configuration-profiles.md)：本地开发、内网团队、知识库、高审计生产、C2 演练等推荐配置。
+## 按目标开始
- [安全加固指南](security-hardening.md)：上线前基线、反向代理、HITL 白名单、文件权限和周期巡检。
+
- [API Recipes](api-recipes.md)：登录、Agent、流式、多代理、上传、漏洞、知识库、MCP 和审计导出示例。
+- **快速体验**：[部署指南](deployment.md) → [配置参考](configuration.md) → [排错指南](troubleshooting.md)
- [贡献规范](contributing-guide.md)：新增 API、配置、工具、前端、数据库、高风险能力和文档的 checklist。
+- **生产部署**：[配置画像](configuration-profiles.md) → [安全加固](security-hardening.md) → [运维 Runbooks](runbooks.md) → [审计与监控](audit-and-monitoring.md)
- [配置参考](configuration.md)：`config.yaml` 字段、热应用边界、参数建议和源码锚点。
+- **接入与自动化**：[API 参考](api-reference.md) → [API Recipes](api-recipes.md) → [MCP 联邦](mcp-federation.md)
- [安全模型](security-model.md)：信任边界、HITL、工具执行、C2/WebShell 与数据安全。
+- **参与开发**：[开发者指南](developer-guide.md) → [测试指南](testing.md) → [贡献规范](contributing-guide.md)
- [RBAC 权限管理](rbac.md)：平台用户、系统/自定义角色、权限目录、逐权限 Scope、资源授权、Agent/MCP/机器人边界与 API 示例。
+
- [架构说明](architecture.md)：请求路径、模块关系、复杂度热点和设计取舍。
+## 核心概念与编排
- [API 参考](api-reference.md)：认证、OpenAPI、SSE、稳定性分层和常用接口。
+
- [排错指南](troubleshooting.md)：诊断顺序、最小命令、常见误判和故障模板。
+- [架构说明](architecture.md) · [安全模型](security-model.md) · [RBAC](rbac.md)
- [审计与监控](audit-and-monitoring.md)：平台审计、工具监控、HITL 日志和保留策略。
+- [Agent 与角色](agent-and-role-guide.md) · [Skills](skills-guide.md) · [Eino 多代理](MULTI_AGENT_EINO.md)
- [知识库](knowledge-base.md)：索引链路、检索调参、日志分析和内容写法。
+- [图编排](workflow-graph.md) · [人机协同最佳实践](hitl-best-practices.md)
- [C2 使用说明](c2.md)：生命周期、任务分级、事件复盘和安全建议。
+
- [WebShell 管理](webshell.md)：操作分层、连接命名、AI 约束和排错。
+## 功能指南
- [MCP 联邦](mcp-federation.md)：内置 MCP、外部 MCP、生命周期和工具命名。
+
- [Agent 与角色](agent-and-role-guide.md)：角色、子代理、Skill、编排模式和工具可见性。
+- [知识库](knowledge-base.md) · [机器人接入](robot.md) · [视觉分析](VISION.md)
- [Skills 指南](skills-guide.md)：Skill 结构、渐进式披露、反模式和本地工具风险。
+- [WebShell](webshell.md) · [C2](c2.md) · [MCP 联邦](mcp-federation.md)
- [插件开发](plugin-development.md)：API 插件、MCP 插件、资源包插件和安全边界。
+
- [发布流程](release-process.md)：发布风险、配置兼容、数据库迁移和验收。
+## 运维与参考
- [测试指南](testing.md)：测试分层、回归重点、测试数据和失败用例。
+
- [图编排使用说明](workflow-graph.md)
+- [部署指南](deployment.md) · [配置参考](configuration.md) · [配置画像](configuration-profiles.md)
- [人机协同最佳实践](hitl-best-practices.md)
+- [安全加固](security-hardening.md) · [审计与监控](audit-and-monitoring.md) · [运维 Runbooks](runbooks.md)
- [机器人使用说明](robot.md)
+- [API 参考](api-reference.md) · [API Recipes](api-recipes.md) · [排错指南](troubleshooting.md)
- [视觉分析](VISION.md)
+
- [前端国际化方案](frontend-i18n.md)
+## 开发与发布
- [Eino 多代理改造说明](MULTI_AGENT_EINO.md)
+
 - [开发者指南](developer-guide.md) · [插件开发](plugin-development.md) · [前端国际化](frontend-i18n.md)
 - [测试指南](testing.md) · [贡献规范](contributing-guide.md) · [发布流程](release-process.md)
@@ -5,7 +5,7 @@ CyberStrikeAI 的主配置文件是 `config.yaml`。大多数配置也可以在
 ## 基础配置
 ```yaml
-version: "v1.6.51"
+version: "vX.Y.Z" # 占位符；请使用 config.example.yaml 中当前发布版本的值
 server:
  host: 0.0.0.0
  port: 8080
@@ -22,7 +22,6 @@ log:
 - `server.host/port`：Web 服务监听地址和端口。
 - `server.tls_*`：HTTPS 配置。生产环境建议使用 `tls_cert_path` 和 `tls_key_path`。
 - `auth.session_duration_hours`：登录会话有效期（小时）。登录密码由 RBAC 用户管理，首次启动时在控制台输出 `admin` 初始密码。
 - `auth.session_duration_hours`：登录会话有效期。
 - `log.output`：可以是 `stdout`、`stderr` 或文件路径。
 ## 模型配置
@@ -103,6 +103,14 @@ docs/en-US/
 - `docs/zh-CN/README.md`
 - `docs/en-US/README.md`
 提交文档变更前运行：
 ```bash
 python3 scripts/check-docs.py
 ```
 该检查会验证本地链接、代码块闭合、中英文文件名对齐、语言导航覆盖率，以及根 README 中的 Go 版本是否与 `go.mod` 一致。版本化示例应尽量从 `go.mod`、`config.example.yaml` 等权威文件派生，避免手工同步。
 ## Review 关注点
 代码评审优先看：