AgentSmith

AgentSmith is the enterprise control plane for the Microservices-Based Agent System (MBOS). It is used to:

• use Chat for governed model conversations and Agent tasks for file-backed work
• manage AI resources such as Files, Endpoints, Project secrets, and Agent Runners
• govern project resource configuration, usage, and cost with project-scoped policy evidence

Core product positioning:

• enterprise AI agent usage and management platform
• AI resource governance platform
• project-scoped usage and audit control plane

Current product terminology:

• docs/contracts/product-terminology.md is the authoritative source for product-facing object names and IA boundaries.
• Use Model, Endpoint, Project secrets, Shared context, Access guide, and Files in user-facing product descriptions.
• Do not describe Chat or Agent tasks as runner-backed user workflows. Runner configuration belongs in Agent Runners administration surfaces.

Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: TailwindCSS + shadcn/ui
• Icons: Lucide React
• i18n: next-intl (zh-CN / en-US)
• State Management: Zustand
• API Mocking: MSW (Mock Service Worker)
• Component Docs: Storybook

UI Design Guide

Current UI style guidance is defined in DESIGN.md.

Use:

• DESIGN.md for the official getdesign cursor UI design guide and global style direction
• docs/UXUI/ for active interaction and module-specific UX specs that apply the design guide
• docs/testing/visual-baseline-policy-v1.md for visual evidence policy

Getting Started

Runtime baseline: Node 24.14.1 LTS with npm 11.11.0 for local development, CI, build images, and deployment images.

Before you run commands, choose one entry path:

Entry path	Choose it when	Start here
ui_only	You are changing frontend UI, copy, client state, or mock-only behavior.	npm install, npm run dev, then npm run verify for the dry-run plan.
local_manual	You need the real local API, Agent tasks, Terminal, runner, files, or backend behavior.	make local-real-up and make local-real-status (adapter over local-manual).
release_grade	You need an AgentSmith product-side readiness / handoff input completeness answer after a large change, release prep, or incident fix.	Run npm run product:ready; use npm run product:status to read the frozen summary/projection snapshot.

Use the diagnostic catalog when a failure needs maintainer diagnosis and you need the smallest command that can reproduce or narrow it. The catalog is not a default command directory; diagnostic commands help you find the problem, then the clean entrypoint gives the product or gate conclusion for that layer.

# Install dependencies
npm install

# Run development server
npm run dev

# Run Storybook
npm run storybook

# Build for production
npm run build

# Run production server
npm start

Make Quick Commands

Local runtime rule:

• start the shared substrate first
• run one flow at a time
• switch flows by stopping the current one first

Use this minimal command set for daily work.

Current workflow model:

• 环境
• 测试
• 门禁
• 验证通道
• 发布

Authoritative definition:

• Current Engineering Governance Model
• Machine-readable source: scripts/governance/current-workflow-manifest.ts
• Machine-readable gate source: scripts/governance/current-gate-manifest.ts

Command naming rule:

• npm run dev is the canonical frontend/mock development entrypoint
• make is the canonical entrypoint for local-real environment orchestration
• npm run is the canonical entrypoint for clean verification and product readiness wrappers
• Maintainer troubleshooting: gate:*, lane:*, backend-real:*, and release:campaign:* stay internal adapters/evidence producers, not default human entrypoints

Quick path note:

• make help-extended repeats this clean human surface and points owners to manifest-backed internal adapters.
• npm run product:status is read-only; it reads the latest product readiness summary plus the frozen projection/snapshot fields recorded in that summary.
• npm run product:ready and npm run product:status end with a short evidence summary; raw logs stay available, and common setup warnings such as NO_COLOR, already-existing Postgres resources, or containerd deprecations are diagnostic unless the evidence names them as the blocker.
• npm run release:ready and npm run release:status remain deprecated transition aliases; they do not produce deployment, package, or operator verdicts.

环境

npm run dev
make local-real-up
make local-real-status
make local-real-down
make local-real-reset

测试

npm run verify

发布

npm run product:ready
npm run product:status

CI Image Publishing

Image Publish is the CI producer for GHCR image handoff. On main/tag pushes or manual dispatch it publishes the current shared ghcr.io/<owner>/agentsmith-app product image and uploads agentsmith-release-contract-input for the release contract artifact workflow. Release Contract Artifact must also receive the current agentsmith-runner runner-image-publish run id as runner_release_run_id; it downloads the canonical runner-release-manifest and runner-ga-handoff artifacts from that run before writing the release contract.

GA scope lock: AgentSmith does not publish a separate backend/API product image from this repo. Web/API/bootstrap workloads use the shared agentsmith_app image truth; a later backend/API image owner must add its own digest instead of reusing or fabricating one here.

Local Runtime In Plain Words

Current runtime-line truth:

• Human guides: Runtime Lines Matrix and Local Runtime Flows
• Machine-readable source: scripts/governance/current-runtime-line-manifest.ts

Current local runtime baseline:

• local-real is the supported developer-machine entrypoint; local-manual remains the maintainer adapter behind it.
• local-real and unified deploy substrate share default local substrate ports, so run them serially on one development host.

Still-binding runtime contracts:

• There is one AgentSmith deploy model; current GA operator-facing release paths are online / airgap × use_existing / install_substrates. local-kind and existing-cluster are transition-only focused diagnostic entry names, not release targets, not separate products, and outside product:ready product readiness / handoff scope. install_substrates requires release-kit namespace-scoped installer evidence plus explicit confirmation. The kit_provided compatibility alias remains internal to transition-only diagnostics and is not a GA operator deployment_path.
• Substrates stay outside the app namespace as Docker or operator-provided services; AgentSmith app workloads run in Kubernetes.
• api replicas stay at 1 until a dedicated multi-replica execution routing design is introduced.

Current local developer flow:

• local-manual — Daily development, real-backend manual validation, and focused Agent task / Files checks through the local-real entrypoint.

Use Local Runtime Flows for local commands and switching. Use Unified Deploy Operations for transition-only focused local-kind and existing-cluster deploy diagnostics / 过渡期专项诊断 under artifacts/unified-deploy/; those diagnostics are not part of the AgentSmith product gate.

No-Sandbox Deployment Baseline

make agent-task-no-sandbox-smoke

This validates the no-sandbox fallback diagnostic behavior:

• current API/Web/Agent task path is healthy (make local-real-status)
• sandbox-backed task path is fail-fast with explicit AGENT_SANDBOX_NOT_CONFIGURED

Internal Adapters And Owner Diagnostics

For daily verification, use the generated workflow entry above: npm run verify. For AgentSmith product-side readiness / handoff input completeness, use npm run product:ready and npm run product:status.

Low-level gate:*, lane:*, backend-real:*, and release:campaign:* scripts exist in package.json for CI, product:ready, and evidence-owner runbooks. They are internal adapters, not a default command directory for ordinary development, testing, or release work.

When a product readiness campaign points to a specific owner, use the named adapter family from the owner runbook or manifest rather than copying commands from this README. Examples of readiness evidence owner identities are gate:default, lane:visual, gate:release, and the aggregate-only gate:release:full; unified deploy producers are transition-only focused diagnostics / 过渡期专项诊断, not current AgentSmith product readiness owners.

Dependency Recovery (only when the environment is broken)

make bootstrap
make deps-down
make deps-reset

Environment

Copy .env.local.example to .env.local and configure:

NEXT_PUBLIC_API_BASE=http://localhost:20000/api/v1
NEXT_PUBLIC_USE_MSW=false
NEXT_PUBLIC_KEYCLOAK_URL=http://localhost:18080/realms
NEXT_PUBLIC_KEYCLOAK_REALM=mbos
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=agentsmith

Personal connection secret encryption:

USER_EXTERNAL_CONNECTIONS_SECRET_KEY=<strong-random-secret>

Personal connections currently cover user-scoped custom secret bundles only. They are not project endpoint credentials, a provider registry, or a generic OAuth system.

Permission Token Naming

Use canonical project tokens in all new code:

• project:endpoint:use
• project:agent:manage
• project:agent:public
• project:files:update

Only canonical permission tokens are valid in current code and tests.

Project Structure

src/
├── app/              # Next.js App Router
├── components/       # React components
├── lib/             # Utilities
│   ├── api/         # API client
│   ├── hooks/       # Custom hooks
│   ├── stores/      # Zustand stores
│   └── utils/       # Utilities
├── messages/        # i18n messages (src/messages)
└── types/           # TypeScript types

Documentation

• Current Engineering Governance Model — 当前唯一工程治理模型与术语表
• Current Baseline (Whitelist) — 当前唯一白名单入口
• 项目宪法 (Project Constitution) — 产品目标、设计风格与功能范围之最高指导，防漂移
• Verification Campaigns v1 — AgentSmith product-side readiness campaign、evidence、story、visual 与 gate conclusion 的执行说明
• User Guides Index — 当前用户操作指南总入口
• Personal Connections — 用户级 custom secret bundle 说明
• File Library Access Model — Files Web/API 与 task HOME 展示模型
• Product Doc Artifacts — 生成产品说明截图与配套 Markdown 产物
• Marketing Assets — 刷新 marketing 截图资产
• Product Engineering Governance Methodology — 产品设计、工程交付与治理方法论基线
• UI Design Guide
• Development Guide
• Documentation Index — current docs index, contracts, UXUI, engineering, testing