Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,102 @@
+# Assistants
+
+An **assistant** is a reusable persona package for an agent: display metadata,
+default agent backend, optional model preferences, system prompt, and skill
+selection.
+
+Open the current page at **`/assistants`**. The legacy
+`/settings/assistants` route redirects to `/assistants?tab=assistants`.
+
+![Assistants list and drawer](../images/assistants-01-list.png)
+
+## Sources
+
+Assistants are merged from three sources:
+
+| Source | Where it comes from | Editable? |
+| --- | --- | --- |
+| Builtin | Embedded manifest under `crates/backend/nomifun-app/assets/builtin-assistants/`, loaded by `BuiltinAssistantRegistry`. | Content is read-only; enable/sort/last-used state and builtin `preset_agent_type` override are stored separately. |
+| Custom | User-created rows in the `assistants` table plus files in the data dir. | Fully editable and deletable. |
+| Extension | Installed extensions via `resolvers::assistant`. | Read-only from this page; manage the extension lifecycle instead. |
+
+The merged list is returned by `GET /api/assistants`.
+
+## What an Assistant Owns
+
+Key fields:
+
+- `id`, `source`, `name`, `description`, `avatar`
+- `preset_agent_type`: default backend such as `nomi`, `claude`, `codex`, `gemini`
+- `models`: optional preferred model ids
+- `prompts` / `prompts_i18n`: assistant instructions
+- `enabled_skills`: skills attached when starting a session
+- `enabled`, `sort_order`, `last_used_at`
+- tag metadata used by the picker and filters
+
+Custom assistant rule files live under the data dir:
+
+- `assistant-rules/`
+- `assistant-skills/`
+- `assistant-avatars/`
+
+Deleting a custom assistant removes its associated files.
+
+## Editing Rules
+
+| Field / action | Builtin | Extension | Custom |
+| --- | --- | --- | --- |
+| Enable / disable | yes | yes | yes |
+| Sort / last-used state | yes | yes | yes |
+| Change default agent backend | builtin override only | no | yes |
+| Edit name / description / avatar | no | no | yes |
+| Edit prompt / skill text | no | no | yes |
+| Delete | no | no | yes |
+
+Builtin mutations are stored in `assistant_overrides`. Extension assistants are
+owned by their extension and intentionally read-only here.
+
+![Assistant editor drawer](../images/assistants-02-editor.png)
+
+## Skills
+
+The Skills tab is also under `/assistants`:
+
+- `/assistants?tab=assistants`
+- `/assistants?tab=skills`
+
+Assistant `enabled_skills` are merged with auto-injected builtin skills when a
+session starts. The materialization rules are implemented by the skill routes
+and backend-specific agent adapters; users do not need to copy skill folders
+manually for normal use.
+
+For MCP servers, use `/mcp`; skills and MCP servers are related but managed on
+separate pages now.
+
+## API
+
+| Operation | Endpoint |
+| --- | --- |
+| List / create | `GET`, `POST /api/assistants` |
+| Update / delete | `PUT`, `DELETE /api/assistants/{id}` |
+| State override | `PATCH /api/assistants/{id}/state` |
+| Avatar | `GET /api/assistants/{id}/avatar` |
+| Bulk import | `POST /api/assistants/import` |
+| Tags | `GET`, `POST /api/assistant-tags`; `PUT`, `DELETE /api/assistant-tags/{key}` |
+
+Rule and assistant-skill file reads/writes go through `/api/skills/assistant-*`
+routes so builtin, extension, and user sources can be dispatched correctly.
+
+## Notes
+
+- Creating an assistant without `preset_agent_type` requires at least one
+  configured provider; the service defaults to `nomi` when possible.
+- CLI-backed agents still require their CLI to be installed on the host. Picking
+  `claude`, `codex`, or `gemini` as an assistant backend does not install those
+  tools.
+- Import from legacy JSON is insert-only and idempotent: existing ids are
+  skipped, and invalid rows are reported per assistant.
+
+## Related
+
+- [MCP & Skills](./mcp-and-skills.md)
+- [Model Failover Queue](./model-routing.md)