chore: import upstream snapshot with attribution

2026-07-13 13:12:33 +08:00
commit aacb60a4af
3387 changed files with 981307 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Durable Agents
+
+OpenSquilla agents are named runtime profiles. Use them when different work
+streams need different defaults, such as a research workspace, a writing
+workspace, or a channel-facing assistant.
+
+The built-in `main` agent is always available. Additional agents are configured
+with `opensquilla agents`.
+
+## When to Create an Agent
+
+Create a durable agent when you want a stable identity for:
+
+- a dedicated workspace;
+- a default model choice;
+- a separate channel or automation target;
+- a recurring task profile;
+- a specialized assistant name and description.
+
+Do not create a new agent for every conversation. Use sessions for ordinary
+conversation continuity.
+
+## List Agents
+
+```sh
+opensquilla agents list
+opensquilla agents list --json
+```
+
+## Add an Agent
+
+```sh
+opensquilla agents add research \
+  --name Research \
+  --description "Research and synthesis workspace" \
+  --workspace /path/to/research \
+  --model gpt-5.4-mini
+```
+
+Agent changes are written to configuration. Restart the gateway before relying
+on the updated agent list:
+
+```sh
+opensquilla gateway restart
+```
+
+## Use an Agent With Sessions
+
+Filter sessions by agent:
+
+```sh
+opensquilla sessions list --agent research
+```
+
+Create scheduled work for an agent:
+
+```sh
+opensquilla cron add \
+  --agent research \
+  --every 1h \
+  --text "Summarize new research notes" \
+  --name research-hourly-summary
+```
+
+Channel configuration can also route incoming messages to configured agents
+depending on the channel setup.
+
+## Delete an Agent
+
+```sh
+opensquilla agents delete research
+opensquilla agents delete research --force
+```
+
+Deleting an agent entry leaves workspace files and state untouched. Clean those
+up separately only when you are sure they are no longer needed.
+
+## Agents vs Sessions vs Skills
+
+| Concept | Use for |
+| --- | --- |
+| Agent | Durable identity and defaults for a work stream. |
+| Session | Conversation history and active task continuity. |
+| Skill | Reusable workflow instructions or tool routines. |
+| Meta-skill | A composed workflow made from multiple skill steps. |
+
+Read next:
+
+- [`sessions.md`](sessions.md)
+- [`features/skills.md`](features/skills.md)
+- [`features/meta-skills.md`](features/meta-skills.md)
+- [`channels.md`](channels.md)
+
+---
+
+[Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)