| name | nexus-manager |
| description | 管理 Nexus 的 Agent、Room、Workspace 与 Skill 系统操作。当用户提到创建 agent、创建 room、邀请成员、查看 room、读写工作区文件、安装或卸载 skill、删除成员或房间、查询系统协作结构时，使用此 skill，即使没有明确说“管理”二字。 |
nexus-manager
管理 Nexus 平台的 Agent、Room、Workspace 与 Skill。通过 CLI 工具执行系统操作。
CLI 工具：优先使用环境变量 NEXUSCTL_COMMAND_PATH 指向的命令；示例里的 nexusctl 只是简写。
不要搜索 cmd/nexusctl，也不要手写 go run ./cmd/nexusctl，运行时入口已经注入。
CLI 输出约定
- Agent 正常调用统一加
--json，让 stdout 始终返回单行 JSON，便于直接提字段。
stdout 只读数据，stderr 只读诊断；失败时不要从 stdout 猜错误。- 参数用法错误返回
64，执行错误返回 1。遇到 64 先修参数，遇到 1 再判断是否重试或换方案。
- 默认不要加
--verbose，只有在排查异常、确认 skill 部署过程或追踪系统初始化问题时才显式打开。
- 子命令按领域拆分：
agent、room、conversation、workspace、skill、launcher。
- 失败时优先读 stderr 里的 JSON 错误，不要假设命令名仍旧是旧 Python 风格。
- 多用户部署下不要把
user_id 写进命令模板；运行时会自动注入当前用户作用域。只有手工在终端直跑 nexusctl 时，才需要显式传 --scope-user-id 或设置 NEXUSCTL_USER_ID。
nexusctl --json agent list
nexusctl --json --verbose agent list
nexusctl --pretty agent list
核心概念
- Agent（成员）：具有独立工作空间的智能体，可被邀请加入 Room 协作。
- Room（群组空间）：多个 Agent 共处的对话空间，支持创建后追加成员。
- Workspace（工作区）：每个 Agent 独立拥有的文件空间，可读写业务文件与运行资料。
- Skill（技能）：部署到 Agent 工作区中的能力包，决定其可用专业动作。
- 主智能体：系统内置的保留 Agent，不能作为 Room 成员，所有 Room 操作由它发起。
- 每个成员创建后自动获得独立工作空间（workspace），用于存放技能、工具配置和文件。
命令参考
Agent 管理
列出成员
nexusctl agent list
创建成员
nexusctl agent create --name "Research"
读取成员详情
nexusctl agent get research
读取成员会话
nexusctl session list --agent-id research
Room 管理
查看 Room 列表
nexusctl room list
读取 Room
nexusctl room get abc123
读取 Room 上下文
nexusctl room contexts abc123
创建 Room
nexusctl room create --agent-id research --agent-id writer --name "内容团队" --title "Kickoff" --description "内容生产协作空间"
更新 Room
nexusctl room update abc123 --name "内容团队" --title "本周计划"
向 Room 追加成员
nexusctl room add-member abc123 --agent-id translator
--room_id 和 --agent_id 均必填。- 仅支持群组类型 Room（
room），不支持私聊（dm）。
- 返回字段：
room_id、room_name、conversation_id、member_agent_ids
移除 Room 成员
nexusctl room remove-member abc123 --agent-id translator
创建 Room directed message
Room runtime 内会自动注入当前 room_id、conversation_id 和 source_agent_id；Agent 正常调用时不要额外传这些字段。recipients 填 Room 成员的 agent_id，不是成员名。
{"tool":"nexus_room.send_directed_message","arguments":{"recipients":["0ed5434a8c13"],"wake_policy":"none","reply_route":{"mode":"none"},"content":"私下提醒"}}
{"tool":"nexus_room.send_directed_message","arguments":{"recipients":["0ed5434a8c13"],"wake_policy":"immediate","reply_route":{"mode":"private","recipients":["<host-agent-id>"],"wake_policy":"immediate"},"content":"请处理后私下回给主持人"}}
{"tool":"nexus_room.send_directed_message","arguments":{"recipients":["0ed5434a8c13"],"wake_policy":"immediate","reply_route":{"mode":"private","recipients":["<host-agent-id>"],"wake_policy":"immediate","next_reply_route":{"mode":"public"}},"content":"请私下回答主持人，主持人随后公开推进"}}
{"tool":"nexus_room.send_directed_message","arguments":{"recipients":["<self-agent-id>"],"wake_policy":"none","reply_route":{"mode":"none"},"content":"只写给自己的上下文"}}
删除 Room
nexusctl room delete abc123
Workspace 操作
列出工作区文件
nexusctl workspace list --agent-id research
读取工作区文件
nexusctl workspace get --agent-id research --path "RUNBOOK.md"
更新工作区文件
nexusctl workspace update --agent-id research --path "RUNBOOK.md" --content "# 新计划"
创建工作区条目
nexusctl workspace create --agent-id research --path "notes/todo.md" --type file --content "- kickoff"
nexusctl workspace create --agent-id research --path "notes" --type directory
重命名工作区条目
nexusctl workspace rename --agent-id research --path "notes/todo.md" --new-path "notes/plan.md"
删除工作区条目
nexusctl workspace delete --agent-id research --path "notes/plan.md"
Skill 管理
列出 Skill
nexusctl skill list
读取成员 Skill 状态
nexusctl skill agent-list --agent-id research
安装 Skill
nexusctl skill install --agent-id research --skill-name planner
搜索社区 Skill
nexusctl skill search-external "pdf"
从 Git 导入 Skill
nexusctl skill import-git --url https://github.com/example/skills --path skills/demo
导入并安装外部 Skill
nexusctl skill install-external --agent-id research --item-file search-result.json
nexusctl skill install-external --agent-id research --import-mode skills_sh --package-spec owner/repo/skill --skill-slug skill
更新导入 Skill
nexusctl skill update demo-skill
nexusctl skill update --all
卸载 Skill
nexusctl skill uninstall --agent-id research --skill-name planner
Workspace 规则
每个成员创建后自动分配独立工作空间。单用户模式位于 ~/.nexus/workspace/<agent_slug>/；多用户模式位于 ~/.nexus/workspace/<user_id>/<agent_slug>/。
目录结构
<workspace>/
.agents/skills/ # 内部技能目录（不可直接操作）
.claude/ # Claude 配置目录（不可直接操作）
AGENTS.md # Agent 身份与行为规则
USER.md # 用户偏好
RUNBOOK.md # 运维手册与任务清单
文件操作约束
- 受保护目录：
.agents/、.claude/ 禁止直接读写，属于内部运行时目录。
- 路径安全：不允许路径穿越（
../），所有操作限定在工作空间根目录内。
- 命名文件：
AGENTS.md、USER.md、RUNBOOK.md 可通过名称直接读写，也可通过相对路径操作。
- 文件大小限制：实时快照推送上限 128KB，超出部分不推送。
模板初始化规则
- 创建成员时自动初始化目录结构和模板文件。
- 已存在的文件不会被覆盖，保证用户修改不丢失。
- 主智能体和普通成员使用不同的模板（主智能体模板包含系统级职责定义）。
技能部署
- 基础 skill 与主智能体专属 skill 由系统管理，不能手动卸载。
- 普通 skill 可通过
install_skill / uninstall_skill 管理。
- 外部 skill 先导入技能库，再安装到指定 Agent；Agent 安装态以 workspace 内
.agents/skills/ 和 .claude/skills/ 文件为准。
- 技能部署到
.agents/skills/<skill_name>/。
.claude/skills/<skill_name> 是指向 .agents/skills/ 的相对符号链接。
操作流程
- 查询结构：
agent list / room get / room contexts
- 管理成员：
agent create / agent get
- 管理协作：
room create / room update / room add-member / room remove-member / room delete
- 管理工作区：
workspace list → workspace get → workspace update
- 管理技能：
list_skills → get_agent_skills → install_skill / uninstall_skill；外部来源使用 search-external → install-external
使用规则
- 主智能体不能作为 Room 成员，创建 Room 时不要把主智能体的
agent_id 放进 agent_ids。
- 创建成员前，先
validate_agent_name 再 create_agent，名称不通过时告知用户原因。
- 创建多人 Room 时，先向用户确认成员列表，再执行创建。
- 涉及文件修改时，先读再写；对路径和覆盖范围说清楚。
- 涉及删除成员、删除房间、删除文件、卸载技能时，默认先确认影响范围。
- 工具统一返回 JSON：先检查
ok 字段，为 true 时读 data，为 false 时读 error 并直接告知用户。
- 工具执行失败时不要假装成功，根据
error 内容给出明确反馈。
