Add files via upload

2026-07-10 14:28:43 +02:00 · 2026-07-07 14:04:18 +08:00
parent 3dfcde7c88
commit 00802a275c
61 changed files with 9460 additions and 24 deletions
@@ -0,0 +1,111 @@
+# Developer Guide
+
+[中文](../zh-CN/developer-guide.md)
+
+This guide is for contributors extending CyberStrikeAI. The project is a Go single-service application with a static frontend, SQLite persistence, Agent/MCP orchestration, and optional high-risk security subsystems.
+
+## Project Layout
+
+```text
+cmd/server/              service entrypoint
+internal/app/            app wiring, routes, MCP tool registration
+internal/handler/        HTTP handlers
+internal/database/       SQLite access
+internal/security/       auth, rate limits, shell execution
+internal/mcp/            MCP server and external MCP manager
+internal/multiagent/     Eino single-agent, multi-agent, middleware
+internal/workflow/       graph orchestration runtime
+internal/knowledge/      indexing and retrieval
+internal/c2/             built-in C2
+internal/project/        project fact blackboard
+web/static/              frontend JS/CSS/assets
+web/templates/           HTML templates
+tools/                   YAML command tools
+roles/                   role YAML
+agents/                  multi-agent Markdown definitions
+skills/                  Agent Skills
+docs/                    documentation
+```
+
+## Development Startup
+
+```bash
+go run ./cmd/server --config config.yaml
+```
+
+The frontend is static. Most JS/CSS/template changes only require a browser refresh.
+
+## Adding a Business Module
+
+Do not add only a handler. A complete module usually needs:
+
+1. Data model and SQLite migration.
+2. Handler: parameters, errors, pagination/filtering.
+3. Audit: management actions.
+4. Monitor: long-running execution state.
+5. MCP: whether Agents should call it.
+6. HITL: approval boundary for MCP tools.
+7. OpenAPI: update `/api/openapi/spec`.
+8. Frontend: i18n, states, empty/error UI.
+9. Tests: DB, handler, edge cases.
+10. Docs: config, usage, troubleshooting, safety impact.
+
+Missing one of these usually becomes a later usability or safety bug.
+
+## Error Response Design
+
+Prefer stable JSON:
+
+```json
+{
+  "error": "machine_readable_code",
+  "message": "human-readable explanation"
+}
+```
+
+Frontend needs stable fields, users need actionable messages, and logs need detailed internal errors.
+
+## Long-Running Tasks
+
+For scanning, indexing, batch tasks, C2, or external operations, answer:
+
+- Can it be cancelled?
+- Can progress be queried?
+- Can it be retried?
+- Where is the result stored?
+- Does state survive page refresh?
+- Does it block the HTTP request?
+
+If not, use task tables, event streams, or monitoring.
+
+## Extending Tools
+
+Prefer `tools/*.yaml` for command tools. Use Go built-in tools when the tool needs internal state or structured integration.
+
+Built-in tools should define clear input schemas, handle timeouts and errors, and respect HITL for risky actions.
+
+## Frontend Changes
+
+Use existing helpers such as `apiFetch`, modal utilities, notifications, and i18n. Update both `web/static/i18n/zh-CN.json` and `web/static/i18n/en-US.json` for new visible text.
+
+Avoid putting secrets or provider keys in frontend code.
+
+## Test Priority
+
+High-value tests:
+
+- config hot-apply;
+- HITL branches;
+- shell timeout/no-output;
+- external MCP recovery;
+- KB indexing and post-processing;
+- WebShell OS/encoding detection;
+- SQLite migration compatibility.
+
+## Source Anchors
+
+- App wiring: `internal/app/app.go`
+- Config apply: `internal/handler/config.go`
+- OpenAPI: `internal/handler/openapi.go`
+- Tool executor: `internal/security/executor.go`
+- Skill package: `internal/skillpackage/`