31 Sophea Agent CLI

Το Sophea Agent CLI είναι client τερματικού για εργασία με έναν χώρο εργασίας Sophea εκτός του browser. Σας δίνει μια διαδραστική συνεδρία coding agent με άγκυρα ένα τοπικό project, μεμονωμένα prompts για script και CI, και απευθείας πρόσβαση στους agents του χώρου εργασίας που δημοσιεύονται μέσω Nous, συμπεριλαμβανομένης της αναζήτησης ιδιωτικής γνώσης.

Αυτή η σελίδα καλύπτει την εγκατάσταση, τη σύνδεση, την επιλογή χώρου εργασίας, τις διαδραστικές συνεδρίες και τα μοντέλα, τα μεμονωμένα prompts, τους agents του χώρου εργασίας και τα artifacts τους, καθώς και τους περιορισμούς εμπιστοσύνης που επιβάλλει το CLI. Χρησιμοποιήστε το CLI όταν θέλετε μια γρήγορη διαδρομή επαλήθευσης που δεν απαιτεί άνοιγμα της εφαρμογής web.

31.1 Εγκατάσταση

Το Sophea Agent CLI διανέμεται ως το πακέτο sophea-cli στο αποθετήριο Sophea. Το πρόγραμμα εγκατάστασης απαιτεί Bun 1.3.14 ή νεότερο στο μηχάνημα.

cd sophea-cli
./install.sh

Το πρόγραμμα εγκατάστασης σταδιοποιεί το CLI στο ~/.local/share/sophea-cli, εγκαθιστά εκεί τις καρφιτσωμένες εξαρτήσεις του και γράφει έναν launcher sophea στο ~/.local/bin (ορίστε το SOPHEA_INSTALL_BIN_DIR για να επιλέξετε διαφορετικό κατάλογο bin). Ο launcher εκτελεί πάντα το εγκατεστημένο αντίγραφο, ποτέ τον πηγαίο κώδικα του checkout. Επιβεβαιώστε την εγκατάσταση με:

sophea --version

sophea 0.1.0

Το πρόγραμμα εγκατάστασης είναι επαναλαμβανόμενο (idempotent): εκτελέστε ξανά το ./install.sh για να μεταβείτε σε νεότερο checkout ή για να επισκευάσετε μια εγκατάσταση. Μια αποτυχημένη ενημέρωση αναιρείται και αφήνει την προηγούμενη εγκατάσταση λειτουργική.

Σημείωση

Το CLI διατηρεί όλη την κατάστασή του, συμπεριλαμβανομένων των διαπιστευτηρίων και των συνεδριών συνομιλίας, σε ένα αποκλειστικό προστατευμένο προφίλ που κατέχει αποκλειστικά. Δεν διαβάζει ούτε μεταφέρει κατάσταση από παλαιότερες εκδόσεις του Sophea CLI ή από άλλα εργαλεία. Η πρώτη χρήση ξεκινά πάντα με ένα νέο sophea login.

31.2 Σύνδεση (έλεγχος ταυτότητας συσκευής)

Εκτελέστε sophea login για να ξεκινήσετε τη ροή ελέγχου ταυτότητας συσκευής μέσω του Sophea Portal.

sophea login

Open the following URL in a browser and enter the code:

  https://portal.example.com/auth/device
  Code: BXKR-7Q2M

Waiting for approval...

Ανοίξτε το URL που εμφανίζεται σε έναν browser. Το Portal εμφανίζει τη σελίδα Authorize Coding Agent. Εισαγάγετε τον κωδικό που εμφανίζει το CLI στο πεδίο Verification code και κάντε κλικ στο Authorize Access.

Σελίδα Authorize Coding Agent του Portal με πεδίο εισαγωγής κωδικού επαλήθευσης, το λογότυπο Sophea Nous Portal και κουμπί Authorize Access — Σελίδα Authorize Coding Agent του Portal, όπου εισάγετε τον κωδικό που εμφανίζει το CLI

Το CLI ελέγχει περιοδικά το Portal μέχρι να εγκρίνετε τον κωδικό και στη συνέχεια αποθηκεύει το διαπιστευτήριο στο προστατευμένο προφίλ του και εμφανίζει τη λίστα χώρων εργασίας.

Το URL του Portal επιλύεται με αυτή τη σειρά: το flag --portal-url, η μεταβλητή περιβάλλοντος SOPHEA_PORTAL_URL και στη συνέχεια το URL που αποθηκεύτηκε από προηγούμενη σύνδεση. Το CLI ζητά URL μόνο σε διαδραστικό τερματικό.

Συμβουλή

Εάν το τερματικό σας δεν μπορεί να ανοίγει αυτόματα URL, αντιγράψτε το URL που εμφανίζεται σε browser οποιασδήποτε συσκευής. Η ροή κωδικού συσκευής συνδέεται με τον κωδικό και όχι με το μηχάνημα που εκτελεί το CLI. Αυτή είναι η υποστηριζόμενη διαδρομή για συνεδρίες SSH και bastions CI.

31.3 Αποσύνδεση και κατάσταση

Το sophea status εμφανίζει την τρέχουσα σύνδεση, τον ενεργό χώρο εργασίας και το ενεργό μοντέλο. Προσθέστε --json για ένα μηχανικά αναγνώσιμο μεμονωμένο αντικείμενο JSON στο stdout.

sophea status

Signed in as: Demo Workspace Admin
Portal:       https://portal.example.com
Workspace:    Admin Guide Demo Workspace
Model:        <workspace default model>

Το sophea logout ανακαλεί το διαπιστευτήριο στην πλευρά του Portal και στη συνέχεια το αφαιρεί από το τοπικό προφίλ. Χρησιμοποιήστε το πριν παραδώσετε ένα κοινόχρηστο μηχάνημα σε άλλον χειριστή.

sophea logout

Signed out.

Εάν το Portal δεν είναι προσβάσιμο, η αποσύνδεση αποτυγχάνει με ασφάλεια: το τοπικό διαπιστευτήριο διατηρείται, η εντολή τερματίζει με μη μηδενικό κωδικό και σας ζητείται να επαναλάβετε. Μετά από επιτυχημένο logout, κάθε άλλη υποεντολή τερματίζει με κωδικό 2 και σάς ζητά να εκτελέσετε ξανά το sophea login.

31.4 Επιλογή χώρου εργασίας

Εάν ο λογαριασμός σας στο Portal ανήκει σε περισσότερους από έναν χώρους εργασίας, το CLI πρέπει να γνωρίζει σε ποιον θα εκτελεί ενέργειες. Εκτελέστε sophea workspace για να δείτε τη λίστα και να επιλέξετε διαδραστικά, ή περάστε απευθείας ένα id ή όνομα για εναλλαγή.

sophea workspace
sophea workspace "Admin Guide Demo Workspace"

Η εναλλαγή χώρου εργασίας περιστρέφει το διαπιστευτήριό σας στον νέο χώρο εργασίας και τερματίζει οποιαδήποτε ενεργή διαδραστική συνεδρία. Ξεκινήστε μια νέα συνεδρία μετά την εναλλαγή.

Σημείωση

Ο διαδραστικός επιλογέας εμφανίζεται μόνο σε TTY. Για εργασίες CI, εργασίες cron και μη διαδραστικά shells, περάστε το --workspace <id-or-name> στην εντολή sophea login, ώστε να ορίσετε τον χώρο εργασίας κατά τη σύνδεση. Εάν ο λογαριασμός έχει πολλούς χώρους εργασίας και κανένας δεν έχει οριστεί σε shell χωρίς TTY, η σύνδεση τερματίζει με κωδικό 3 και ζητά το --workspace.

31.5 Διαδραστικές συνεδρίες

Η εκτέλεση sophea (ή sophea chat) ανοίγει μια διαδραστική συνεδρία coding agent με άγκυρα τον τρέχοντα κατάλογο εργασίας. Ο agent μπορεί να διαβάζει και να επεξεργάζεται αρχεία του project, να εκτελεί εντολές shell και να καλεί τους agents του χώρου εργασίας σας, μέσα στα όρια που περιγράφονται στην ενότητα Περιορισμοί εμπιστοσύνης παρακάτω.

cd /home/demo/projects/admin-guide
sophea

Η απευθείας μετάβαση prompt στο sophea δεν υποστηρίζεται· χρησιμοποιήστε το sophea run "<prompt>" για μη διαδραστικά prompts.

Flags συνεδρίας:

Flag	Λειτουργία
`--cwd PATH`	Αγκυρώνει τη συνεδρία σε διαφορετικό κατάλογο εργασίας.
`--add-dir PATH`	Δίνει στον agent πρόσβαση σε επιπλέον κατάλογο (επαναλαμβανόμενο).
`--model ID`	Ξεκινά με συγκεκριμένο μοντέλο του χώρου εργασίας αντί για το προεπιλεγμένο.
`--thinking LEVEL`	Ορίζει την προσπάθεια συλλογισμού για μοντέλα που το υποστηρίζουν.
`--hide-thinking`	Αποκρύπτει την έξοδο συλλογισμού στη συνεδρία.
`--no-title`	Παραλείπει την αυτόματη δημιουργία τίτλου συνεδρίας.
`--continue` / `-c`	Ανοίγει ξανά την πιο πρόσφατη συνεδρία.
`--resume` / `-r` / `--session [ID]`	Επιλέγει ή ονομάζει μια αποθηκευμένη συνεδρία για συνέχιση.

Οι συνεδρίες αποθηκεύονται αυτόματα και συνδέονται με τον λογαριασμό Portal και τον χώρο εργασίας που τις δημιούργησε. Μπορείτε να συνεχίσετε μια συνεδρία μόνο όταν είστε συνδεδεμένοι με τον ίδιο λογαριασμό στον ίδιο χώρο εργασίας· μετά από εναλλαγή χώρου εργασίας ή νέα σύνδεση ως διαφορετικός λογαριασμός, οι παλαιότερες συνεδρίες απορρίπτονται (κωδικός εξόδου 3) αντί να αναμειγνύονται σιωπηλά.

Μέσα σε μια συνεδρία, οι εντολές με κάθετο ειδικά για το Sophea είναι:

Εντολή με κάθετο	Λειτουργία
`/sophea-agents`	Εμφανίζει τους τρέχοντες agents του χώρου εργασίας.
`/sophea-agent <slug> <prompt>`	Εκτελεί έναν agent του χώρου εργασίας.
`/sophea-agent-artifacts <slug> <operation-id>`	Εμφανίζει τα artifacts μιας εκτέλεσης agent.
`/sophea-agent-download <slug> <operation-id> <artifact-id> [relative-path]`	Κατεβάζει ένα artifact.
`/sophea-workspace`	Εμφανίζει τον ενεργό χώρο εργασίας.
`/sophea-status`	Εμφανίζει την κατάσταση σύνδεσης, χώρου εργασίας και μοντέλου.
`/sophea-logout`	Ανακαλεί το διαπιστευτήριο και αποσυνδέει.

Είναι επίσης διαθέσιμες οι τυπικές εντολές πλοήγησης συνεδρίας και επιλογής μοντέλου· δείτε τη βοήθεια εντός της συνεδρίας.

31.6 Μοντέλα

Η λίστα μοντέλων είναι ο ζωντανός κατάλογος του χώρου εργασίας σας από το Sophea Portal, ο οποίος ανακτάται εκ νέου πριν από κάθε εκκίνηση. Η πρώτη καταχώριση του καταλόγου είναι το προεπιλεγμένο μοντέλο. Το --model <id> επικυρώνεται έναντι του ζωντανού καταλόγου πριν εκτελεστεί οτιδήποτε· ένα id που δεν υπάρχει στον τρέχοντα κατάλογο απορρίπτεται. Εάν μια αποθηκευμένη συνεδρία ή προηγούμενη επιλογή αναφέρει μοντέλο που δεν δημοσιεύεται πλέον, το CLI μεταβαίνει στο προεπιλεγμένο μοντέλο του χώρου εργασίας και σάς ενημερώνει.

31.7 Εκτέλεση μεμονωμένου prompt

Το sophea run "<prompt>" εκτελεί ένα μεμονωμένο prompt μη διαδραστικά και εμφανίζει την απάντηση στο stdout. Χρησιμοποιήστε το για ελέγχους μέσω script και για διοχέτευση της εξόδου σε άλλα εργαλεία.

sophea run "Summarize the README of the project in the current directory."

Επιλογές: --cwd PATH για να ορίσετε τον κατάλογο εργασίας, --model ID για να παρακάμψετε το μοντέλο, --agent SLUG για να δρομολογήσετε το prompt μέσω συγκεκριμένου agent του χώρου εργασίας, --operation-id ID για να ορίσετε ρητό κλειδί idempotency για μια εκτέλεση agent, και --json για μηχανικά αναγνώσιμη έξοδο.

Με το --json, η εντολή γράφει ακριβώς μία τιμή JSON στο stdout σε επιτυχία ή αποτυχία· όλα τα μηνύματα προόδου και κατάστασης παραμένουν στο stderr, ώστε η διοχέτευση σε εργαλεία όπως το jq να είναι ασφαλής.

31.8 Agents χώρου εργασίας

Το sophea agents list εμφανίζει τους agents που είναι ενεργοποιημένοι για τον ενεργό χώρο εργασίας. Η λίστα ανακτάται ζωντανά από το Nous και αντικατοπτρίζει ό,τι μπορεί πραγματικά να χρησιμοποιήσει ο χώρος εργασίας σας, συμπεριλαμβανομένου του agent αναζήτησης γνώσης nous-rag όταν τον έχει ενεργοποιήσει ο διαχειριστής σας.

sophea agents list

SLUG                  NAME                 DESCRIPTION
nous-rag              Knowledge Search     Searches the workspace knowledge base.
my-research-agent     My Research Agent    Researches a topic across workspace sources.
legal-summarizer      Legal Summarizer     Summarizes contracts and clauses.

Το sophea agents run <slug> "<prompt>" ξεκινά μια εκτέλεση agent:

sophea agents run my-research-agent \
  "Find the most recent contract that mentions Vendor X and quote the renewal clause."

Κάθε εκτέλεση είναι επαναλαμβανόμενη (idempotent). Το CLI εμφανίζει ένα operation id πριν ξεκινήσει η εκτέλεση· περάστε το ίδιο id πίσω με --operation-id και μια επαναλαμβανόμενη εντολή επιστρέφει το αποτέλεσμα της αρχικής εκτέλεσης αντί να ξεκινά διπλότυπη. Εάν διακόψετε μια εκτέλεση με Ctrl+C, το CLI ακυρώνει την απομακρυσμένη εκτέλεση· η επανεκτέλεση με το operation id που εμφανίστηκε συνεχίζει την παρακολούθησή της.

Όλες οι υποεντολές agents δέχονται το --json για τη σύμβαση μίας τιμής JSON στο stdout που περιγράφηκε παραπάνω. Όταν διακόπτετε μια εντολή που αφορά συγκεκριμένη λειτουργία, όπως agents run, agents artifacts ή agents download, αυτή η μία τιμή JSON περιλαμβάνει το operation id. Για παράδειγμα, το Ctrl+C επιστρέφει {"ok":false,"exit_code":130,"operation_id":"agent_9f2c41ab07e3d5126b48f0a1"}. Μια διακοπή της εντολής agents list δεν περιλαμβάνει operation id.

31.9 Artifacts agents

Ορισμένοι agents παράγουν αρχεία όπως αναφορές, εξαγωγές ή παραγόμενα έγγραφα. Εμφανίστε τα με sophea agents artifacts και ανακτήστε τα με sophea agents download:

sophea agents artifacts my-research-agent agent_9f2c41ab07e3d5126b48f0a1
sophea agents download my-research-agent agent_9f2c41ab07e3d5126b48f0a1 vendor-x-report.pdf

Οι λήψεις αποθηκεύονται από προεπιλογή στο .sophea-artifacts/<operation-id>/ κάτω από τον τρέχοντα κατάλογο εργασίας. Χρησιμοποιήστε --output <relative-path> για να επιλέξετε διαφορετική θέση μέσα στο project. Οι λήψεις δεν αντικαθιστούν ποτέ υπάρχον αρχείο, απορρίπτουν μη ασφαλείς διαδρομές και απορρίπτουν αρχεία μεγαλύτερα από 100 MiB.

31.10 Εργαλεία και skills σε διαδραστικές συνεδρίες

Μέσα σε μια διαδραστική συνεδρία, ο coding agent μπορεί να καλέσει τέσσερα εργαλεία Sophea εκ μέρους σας:

sophea_agents: εμφανίζει τον ζωντανό κατάλογο agents του χώρου εργασίας.
sophea_run_agent: εκτελεί έναν agent του χώρου εργασίας βάσει slug.
sophea_agent_artifacts: εμφανίζει τα artifacts μιας εκτέλεσης agent.
sophea_download_agent_artifact: κατεβάζει ένα artifact μέσα στο project.

Δύο ενσωματωμένα skills καθοδηγούν τον agent: το nous-workspace-agents του διδάσκει πώς να επιλέγει τον κατάλληλο agent του χώρου εργασίας, να τον εκτελεί και να επαληθεύει τα αποτελέσματα, και το nous-knowledge-search του διδάσκει πότε να απαντά από τα τοπικά αρχεία και πότε να αναζητά στην ιδιωτική γνώση του χώρου εργασίας σας μέσω του nous-rag.

Δεν χρειάζεται να εγκαταστήσετε ή να διαχειριστείτε τίποτα από αυτά· διανέμονται μέσα στο πακέτο του CLI.

31.11 Κωδικοί εξόδου

Κωδικός	Σημασία
`0`	Επιτυχία.
`1`	Τοπικό σφάλμα χρήσης ή αποτυχία κατά την εκτέλεση.
`2`	Απαιτείται έλεγχος ταυτότητας ή έχει λήξει· εκτελέστε `sophea login`.
`3`	Ο χώρος εργασίας δεν είναι διαθέσιμος ή ασυμφωνία συνεδρίας/λογαριασμού/χώρου εργασίας.
`4`	Άγνωστος, απενεργοποιημένος ή αποτυχημένος agent χώρου εργασίας.
`130`	Διακοπή με `Ctrl+C` (SIGINT).
`143`	Τερματισμός από SIGTERM.

31.12 Περιορισμοί εμπιστοσύνης

Το CLI περιορίζει τα μοντέλα, τα εργαλεία που φορτώνονται και την απομακρυσμένη ταυτότητα του χώρου εργασίας. Δεν εκτελεί το τοπικό shell σε sandbox:

Μπορούν να χρησιμοποιηθούν μόνο μοντέλα από τον ζωντανό κατάλογο Portal του χώρου εργασίας σας.
Τα επιτρεπόμενα εργαλεία εκτελούνται αυτόματα, χωρίς αίτημα έγκρισης. Σε αυτά περιλαμβάνονται οι εντολές shell, οι εγγραφές και επεξεργασίες αρχείων, οι εκτελέσεις agents χώρου εργασίας και οι λήψεις artifacts.
Το CLI δεν φορτώνει επεκτάσεις, plugins, διακομιστές MCP, skills ή εντολές από το μηχάνημά σας ή από το project· τα μόνα διαθέσιμα εργαλεία και skills είναι εκείνα που διανέμονται μέσα στο πακέτο του CLI.
Τα ενσωματωμένα εργαλεία αρχείων αποκλείουν την πρόσβαση στο προφίλ και την εγκατάσταση του CLI, καθώς και στο παλιό αρχείο διαπιστευτηρίων. Αυτοί οι έλεγχοι δεν ισχύουν για εντολές shell και δεν αποτελούν sandbox του shell.
Οι εντολές shell εκτελούνται με την πρόσβαση του τοπικού σας χρήστη στο σύστημα αρχείων. Μπορούν να προσπελάσουν διαδρομές έξω από το project όταν ο χρήστης σας έχει πρόσβαση σε αυτές.
Οι εκτελέσεις agents πιστοποιούνται ως εσείς και περιορίζονται στον ενεργό χώρο εργασίας σας· η αναζήτηση ιδιωτικής γνώσης μέσω nous-rag χρησιμοποιεί τα δικά σας δικαιώματα εγγράφων.

31.13 Τρέχοντες περιορισμοί

Οι personas του Nous δεν είναι διαθέσιμες μέσω του CLI σε αυτή την έκδοση· χρησιμοποιήστε τους agents του χώρου εργασίας που εμφανίζει το sophea agents list.
Η αυτόνομη δημιουργία εικόνων δεν είναι διαθέσιμη μέσω του CLI.
Το CLI εγκαθίσταται τοπικά από το αποθετήριο Sophea· πακέτο npm ή διανομή αυτόνομου δυαδικού αρχείου δεν είναι ακόμη διαθέσιμα.

Για μια ευρύτερη εικόνα του τρόπου με τον οποίο το CLI σχετίζεται με το Knowledge Search και τους agents του χώρου εργασίας, ανατρέξτε στις ενότητες Αναζήτηση γνώσης και Agents.