Assistant
The assistant is a chat page in the admin console. Staff state what they need in plain language, and the model / agent does it with the console's own tools, as that user: looking up data, summarizing, changing data as asked; when it needs outside information, it searches the web and reads pages. Whenever data would change, it first lists which record, each field's current → proposed value and the sources it relied on, and runs the change only after a person confirms it.
You can also tick several records in a list and have the agent run the same skill on each of them (for example 补齐客户信息, "fill in customer details"); the results go to a batch review page where you confirm them one by one or all at once.
The agent acts only through tools: the modules' existing MCP tools (the same tool list and the same checks as MCP agent access), plus built-in tools for the web, a plan checklist and clarifying questions. It runs no commands, reads or writes no files on the server and drives no browser.
Off by default
The assistant is off by default; projects that don't need it can skip this page. It runs on the existing Redis job queue and Socket.IO push, so no new service is needed. The full reference is the repository's in-app agent docs (Chinese).
Turning it on
| Switch | Where | Effect |
|---|---|---|
APP_AGENT | Server environment variable, false by default | Read only at startup; restart every server instance after changing it. While off, the module is not loaded: every /api/agent/* route returns 404, the Agent menu group is hidden from the sidebar, the role grant tree and tenant packages, and the button in the lower-right corner does not appear |
agent.paused | System → Parameters, false by default, only the super administrator (root) can change it | Emergency stop: set to true, new turns and tool calls are refused and running turns stop within half a second; set back to false to resume. No restart needed; it takes effect on all instances together |
APP_AGENT and APP_MCP are independent: with only the assistant on, /api/mcp still does not exist. The tables are always created by the migrations and the menus and sample data always written by the seeds, so turning it on needs no extra migration. For deployment notes (outbound firewall, keys) see Deploy · Assistant (Chinese).
First steps after turning it on:
- The super administrator adds a model provider on the Models tab of Agent → Agent settings (see the next section). Without a usable model, the chat page asks you to contact an administrator and the input box is disabled;
- For web access, add a search provider on the Web search tab;
- In System → Roles, grant Assistant to the business roles; the skills, batch run and usage pages are granted separately;
- With multi-tenancy on, tick the Agent menu group into the tenant package first; only then can the tenant's roles be granted it.
The Agent menu group comes right after Home and has four pages:
| Page | Content |
|---|---|
| Agent → Assistant | The chat page. The batch review page sits under it and is not shown in the menu |
| Agent → Skills | Personal and tenant-wide skills, prompt templates, tenant instructions |
| Agent → Agent settings | Models, web search, external MCP, tool policies, platform skills, instructions and limits. With multi-tenancy on it is a platform-only page, and only the super administrator can change it |
| Agent → Agent usage | Calls and tokens summed by day, user or model |
See the repository's Enabling section (Chinese).
Models
Models connect through an OpenAI-compatible API (Chat Completions), so common hosted model services and a local Ollama all work. On the Models tab of Agent → Agent settings, each provider has a name, an API address, a key and the models it offers, and can be made the default. For each model you can also mark whether it supports reasoning effort (low, medium or high in the chat), whether it can read images, and how large its context window is.
| Service | Notes |
|---|---|
| DeepSeek, Qwen (Alibaba Cloud Model Studio), Kimi (Moonshot AI), Zhipu, OpenAI | Enter the vendor's API address and a key from its console |
| Ollama | Runs on the same machine or the internal network; leave the key empty |
- The agent relies on the model's tool calling (function calling); pick a model that supports it;
- Keys are write-only: encrypted in the database, and the page shows only Stored. Changing the API address requires entering the key again; the old key is never sent to a new address;
- Each conversation can pick one of the configured models; without a choice it uses the first model of the default provider;
- When a model service fails, the page shows only that the call failed and a short reason, never the service's raw reply.
API addresses and sample model names for each vendor are in the repository's model setup section (Chinese).
Web search
The agent has two built-in read-only web tools: one searches the web, one reads a page.
- Search providers are Bocha (for China) and Tavily (outside China), added on the Web search tab; their keys are also encrypted and write-only. Without a search provider, no search is offered;
- The page reader can only read links that appeared in this turn's search results, links the user gave in a message, or sites an administrator allowed. This keeps web content from tricking the agent into putting internal data into a URL;
- Setting the parameter
agent.web.modetooffremoves all web tools.
See the repository's web search section (Chinese).
External MCP servers
On the External MCP tab you can connect MCP servers outside this system (Streamable HTTP transport) so the agent can use their tools too.
- Authentication can be none, a header token, or OAuth client credentials; credentials are encrypted and write-only;
- Only public addresses are allowed by default; pointing at an internal address must be allowed explicitly by the super administrator;
- Sync lists the server's tools. New tools start disabled; an administrator enables them one by one and sets each one's approval policy. A server calling a tool read-only is not trusted: only tools an administrator explicitly sets to run directly skip confirmation;
- When a server asks the user for more information during a call, the chat page shows a form card.
See the repository's external MCP servers section (Chinese).
Tool policies and approval modes
The Tool policies tab lists every tool of this system with an approval policy, applied to all tenants:
| Policy | Meaning |
|---|---|
Run directly (auto) | Default for read-only tools |
Ask (ask) | Stop and wait for the requester to confirm; default for write tools |
Deny (deny) | The agent does not see the tool |
A write tool can only be Ask or Deny, never run directly. A tool switched off as a whole on the MCP tools page cannot be used by the agent either.
Each conversation can also switch its approval mode:
- Read only: only read-only tools are offered;
- Ask (default): every write is confirmed;
- Trust this conversation: once a tool has been confirmed for a record, it is not asked again for that record in this conversation. The super administrator can turn this option off with the parameter
agent.trust_mode.
The approval card shows the tool, the record, each field's current → proposed value and the sources read in this turn, with the buttons Approve, Approve for this conversation, Reject and Cancel turn. You can add a reason when rejecting, and the agent will not retry. Whatever the mode, a write never runs without a person confirming it.
There is also a plan mode: the agent stays read-only and lists its steps first; you confirm, then switch back to run them.
See the repository's tool policies and chat page sections (Chinese).
Clarifying questions and options
When the agent is unsure (for example, it finds several companies with similar names), it stops and asks you: 1 to 4 questions at a time, each with 2 to 4 options (single or multiple choice) plus Other to type your own answer. The turn waits for your answer, and you may also choose not to answer. What you type is passed to the model as data only.
The chat page
Agent → Assistant works much like a desktop chat app:
- Conversation list: create, search (titles and full message text), rename, pin, archive and delete, filtered by all, running, unread or pinned; temporary conversations stay out of the list and are deleted when you leave;
- Answers stream in, with collapsible tool calls; supported models show a reasoning summary; cited pages are listed at the end, followed by a few suggested follow-ups;
- Fork, resend and revert: fork a new conversation from any message, or edit and resend the last one; revert removes the last turn, but changes it already made are not rolled back;
- Share and export: a read-only link that only people in the same tenant can open; export as Markdown;
- Sending while a turn runs: Add to this turn to change direction, or Queue for next turn; you can press Stop at any time;
- Attachments: files already uploaded to file storage; text files, the first sheet of an xlsx and images (for models that read images) are passed to the model;
- Slash commands: type
/to start a conversation, compact the context, switch the model, the approval mode or plan mode, pick a skill, insert a prompt template, see usage and more; - Reminders: an inbox message when a turn waits for your confirmation or answer, or when a long turn finishes;
- Corner button: the Assistant button in the lower-right corner of every page opens the chat with the current page; on a list page the agent also knows which rows you ticked.
See the repository's chat page section (Chinese).
Skills
A skill is a task description plus the tools that task may use. For example, 补齐客户信息 ("fill in customer details"): look up each company's website, industry, city and so on, fill only empty fields, and cite the sources. A skill is only text; it contains no executable code.
| Scope | Maintained by | Used by |
|---|---|---|
| Platform | The super administrator, on the Platform skills tab of Agent settings | Every user of every tenant |
| Tenant | People with the skill management permissions, in Agent → Skills | Users of the tenant |
| Personal | You, in Agent → Skills | You |
With equal names, the personal skill wins, then the tenant's, then the platform's.
- The model normally sees only each skill's name and description and loads the full text when it decides to use it;
- Type
$and the skill name in the input box (or use/skills) to pick a skill directly; if the skill lists tools, only those tools are offered in that turn; - After a good conversation, Save as skill has the model draft a personal skill from it; the draft is saved disabled, so you check it and then enable it;
- Skills can be imported and exported as
SKILL.md.
For the format and how to write one, see the repository's skills section (Chinese).
Instructions, tone and prompt templates
- Instructions are added to the model's system prompt in this order: platform instructions (super administrator) → tenant instructions (on the Skills page) → personal instructions (each user's own, for example "answer with tables");
- Tone is a personal choice: Default, Concise, Detailed, Friendly, Formal;
- Prompt templates are saved questions, personal or tenant-wide, inserted with
/promptsin the input box.
See the repository's instructions, tone and prompt templates section (Chinese).
Limits, emergency stop and usage
The super administrator limits cost with system parameters: steps, time and tokens per turn, tokens per user and per tenant per day, and concurrent turns per user. When a limit is hit, the turn stops and says which limit it reached. The emergency stop agent.paused is described above.
Usage is recorded by user, tenant, model and date: Agent → Agent usage sums the current tenant's calls and input / output tokens by day, user or model; /status in the chat shows this conversation's context use and the usage and limits for this turn and today.
Parameters and defaults are in the repository's limits, emergency stop and usage section (Chinese).
Batch runs and the "fill in customer details" sample
The template ships a sample: Generator samples → Sample customers holds a few well-known companies with some fields left empty on purpose, and the platform skill 补齐客户信息 comes with three tools (search customers, read a customer, update a customer).
- Ask in the chat, for example "fill in the industry of 华为技术有限公司";
- Or tick a few customers in the sample customer list and click Let the agent fill in: one conversation per customer, started in turn within the requester's concurrency limit, with every change stopping for approval;
- The batch review page lists each row's state and pending changes; confirm them one by one, or Approve all / Reject all.
Batch runs are granted separately and can only cover records you can see. To make your own list batchable, see the repository's adding tools, batch targets and skills to your module and the sample (Chinese).
Security model
- Owned by the requester: conversations, approvals and questions can be seen and acted on only by their owner; anyone else gets 404, and only the requester can confirm a change;
- Runs as the user: tools keep MCP's checks (permission, data scope, tenant and package, argument validation, time limit, masking of secret-named output fields). The agent can never do more than the requester could do on the pages; each turn reloads the requester's identity first and stops if the user was disabled or deleted;
- Writes need a person: if permissions, the approval mode or the policy changed after confirmation, the call is still blocked;
- Outside content is untrusted: web pages, search results and external MCP output are passed to the model as data only. Even if a page talks the model into changing data, the change stops at the approval card, which lists the sources;
- Outbound requests go to public addresses only: page reading and external MCP connect only to public addresses and recheck every redirect. The model's API address is not checked this way (so a local or internal Ollama works) and only the super administrator can set it;
- Encrypted keys: credentials of models, search providers and external MCP servers are encrypted with a key derived from
APP_SECRETand are write-only; enter them again after changingAPP_SECRET; - Audit: every tool call (refused ones too) writes a row to System → Logs → Action log, marked as coming from the chat page; changed data records the requester as modifier as usual.
See the repository's security model section (Chinese).
Try it on the live demo
The live demo does not have the assistant turned on. To try it, turn on APP_AGENT on your own installation and configure a model.
Known limits
- The concurrent turn limit is soft: requests arriving together may give a user one extra turn;
- Models, search providers and external MCP servers are platform settings; tenants cannot add their own external MCP servers yet;
- Only remote HTTP MCP servers are supported, not stdio servers that need a process started on the server;
- Reverting a turn does not roll back changes it made; a tool timeout only ends the wait, and a database operation already started cannot be interrupted;
- The model's answers and judgment can be wrong: check each current → proposed value and source on the approval card.
The full list is in the repository's known limits section (Chinese).
Related: