From 2f75216598b5f5457e1b33cc60ea2b3555e11201 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Wed, 30 Sep 2026 20:59:34 +0000 Subject: [PATCH] kb init(jiuwenswarm): modules --- knowledge/repos/jiuwenswarm/_index.md | 1 + knowledge/repos/jiuwenswarm/_routes.yaml | 310 ++++++++++++++++++ .../repos/jiuwenswarm/components/_index.md | 20 ++ .../components/agent-runtime/_index.md | 22 ++ .../jiuwenswarm-runtime-session.md | 31 ++ .../agent-runtime/jiuwenswarm-runtime.md | 60 ++++ .../components/common-core/_index.md | 24 ++ .../common-core/jiuwenswarm-common-acp.md | 30 ++ .../jiuwenswarm-common-config-panel.md | 35 ++ .../common-core/jiuwenswarm-common-schema.md | 36 ++ .../common-core/jiuwenswarm-common.md | 103 ++++++ .../components/cron-scheduling/_index.md | 21 ++ .../jiuwenswarm-runtime-cron.md | 31 ++ .../components/extensions-plugins/_index.md | 23 ++ .../jiuwenswarm-extensions-agentos.md | 42 +++ .../jiuwenswarm-extensions-video-duplex.md | 43 +++ .../jiuwenswarm-extensions.md | 49 +++ .../components/gateway-channels/_index.md | 22 ++ .../jiuwenswarm-channels-cli.md | 36 ++ .../jiuwenswarm-channels-process-cli.md | 44 +++ .../jiuwenswarm/components/launch/_index.md | 23 ++ .../launch/jiuwenswarm-channels-desktop.md | 30 ++ .../launch/jiuwenswarm-instance-manager.md | 37 +++ .../components/launch/jiuwenswarm.md | 52 +++ .../components/login-auth/_index.md | 21 ++ .../login-auth/jiuwenswarm-common-auth.md | 32 ++ .../components/observability/_index.md | 21 ++ .../jiuwenswarm-observability.md | 32 ++ .../symphony-orchestration/_index.md | 23 ++ .../jiuwenswarm-symphony-evolution.md | 27 ++ .../jiuwenswarm-symphony-shared.md | 30 ++ .../jiuwenswarm-symphony.md | 40 +++ 32 files changed, 1351 insertions(+) create mode 100644 knowledge/repos/jiuwenswarm/components/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime-session.md create mode 100644 knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime.md create mode 100644 knowledge/repos/jiuwenswarm/components/common-core/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-acp.md create mode 100644 knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-config-panel.md create mode 100644 knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-schema.md create mode 100644 knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common.md create mode 100644 knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/cron-scheduling/jiuwenswarm-runtime-cron.md create mode 100644 knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-agentos.md create mode 100644 knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-video-duplex.md create mode 100644 knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions.md create mode 100644 knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-cli.md create mode 100644 knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-process-cli.md create mode 100644 knowledge/repos/jiuwenswarm/components/launch/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-channels-desktop.md create mode 100644 knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-instance-manager.md create mode 100644 knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm.md create mode 100644 knowledge/repos/jiuwenswarm/components/login-auth/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/login-auth/jiuwenswarm-common-auth.md create mode 100644 knowledge/repos/jiuwenswarm/components/observability/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/observability/jiuwenswarm-observability.md create mode 100644 knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md create mode 100644 knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-evolution.md create mode 100644 knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-shared.md create mode 100644 knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony.md diff --git a/knowledge/repos/jiuwenswarm/_index.md b/knowledge/repos/jiuwenswarm/_index.md index a29c6060..c385d5e3 100644 --- a/knowledge/repos/jiuwenswarm/_index.md +++ b/knowledge/repos/jiuwenswarm/_index.md @@ -28,3 +28,4 @@ sources: [] - [JiuwenSwarm 仓库审查规则](rules.md) - [每次审查 jiuwenswarm 的 PR 都先读这份通用审查规则；本仓库自己的约束在 rules 页。](../../general/review/rules.md) - [PR 新增或修改测试、或 CI 失败时读。先看 tests/ 下已有的用例（如 tests/unit_tests/a2ui/）和 pytest.ini 的约定；TESTING.md 里有过期路径，不能照抄。](../../general/ci/guides/inspect-existing-tests-first.md) +- [jiuwenswarm components](components/_index.md) diff --git a/knowledge/repos/jiuwenswarm/_routes.yaml b/knowledge/repos/jiuwenswarm/_routes.yaml index f72a567d..96162e51 100644 --- a/knowledge/repos/jiuwenswarm/_routes.yaml +++ b/knowledge/repos/jiuwenswarm/_routes.yaml @@ -201,3 +201,313 @@ owners: - README.md - README_CN.md - .doc_project_maintainer/ +- owner: launch + path: repos/jiuwenswarm/components/launch/_index.md + signals: + - start_services + - jiuwenswarm-start + - debug launcher + - multi-instance + - --dotenv + - --name + - jiuwenswarm-init + - init workspace + - dotenv_early + - SSE patch + - ModelArts + - compat alias + - desktop + - 桌面端 + - desktop app + - 窗口 + - 关闭行为 + - 最小化到托盘 + - 全屏 + - 自动更新 + scope_prefixes: + - jiuwenswarm/acp/ + - jiuwenswarm/app.py + - jiuwenswarm/channels/acp/ + - jiuwenswarm/cli/ + - jiuwenswarm/debug_launcher.py + - jiuwenswarm/dotenv_early.py + - jiuwenswarm/init_workspace.py + - jiuwenswarm/llm_provider_compat_patch.py + - jiuwenswarm/llm_sse_patch.py + - jiuwenswarm/start_services.py + - jiuwenswarm/channels/desktop/ + - jiuwenswarm/instance_manager/ +- owner: gateway-channels-2 + path: repos/jiuwenswarm/components/gateway-channels/_index.md + signals: + - cli + - chat + - 命令行 + - CLI 频道 + - gateway client + - websocket + - tui + - renderer + - jsonl + - spinner + - SIGINT + - 受信目录 + - process_cli + - process cli + - CLI + - REPL + - slash command + - 斜杠命令 + - one-shot + - machine mode + scope_prefixes: + - jiuwenswarm/channels/cli/ + - jiuwenswarm/channels/process_cli/ +- owner: common-core + path: repos/jiuwenswarm/components/common-core/_index.md + signals: + - common + - config + - 配置 + - 模型选择 + - model catalog + - mode + - 工作区 + - cron + - updater + - doctor + - hooks + - kv cache + - ACP + - acp + - stdio + - AcpStdioClient + - Codex + - Codex CLI + - acp_agents + - JSON-RPC + scope_prefixes: + - jiuwenswarm/common/_build_config.py + - jiuwenswarm/common/chat_final.py + - jiuwenswarm/common/cleanup.py + - jiuwenswarm/common/client/ + - jiuwenswarm/common/coding_memory_paths.py + - jiuwenswarm/common/config.py + - jiuwenswarm/common/context_keys.py + - jiuwenswarm/common/context_window.py + - jiuwenswarm/common/cron_session.py + - jiuwenswarm/common/cron_team_completion.py + - jiuwenswarm/common/debug_dump.py + - jiuwenswarm/common/external_cli_catalog.py + - jiuwenswarm/common/external_cli_runtime.py + - jiuwenswarm/common/git_safe_directory.py + - jiuwenswarm/common/hooks_config.py + - jiuwenswarm/common/kv_cache_affinity_config.py + - jiuwenswarm/common/log_preview.py + - jiuwenswarm/common/mcp_config.py + - jiuwenswarm/common/media_capability_config.py + - jiuwenswarm/common/mode_matrix.py + - jiuwenswarm/common/model_catalog.py + - jiuwenswarm/common/model_config_validation.py + - jiuwenswarm/common/model_errors.py + - jiuwenswarm/common/model_migration.py + - jiuwenswarm/common/model_selection.py + - jiuwenswarm/common/model_vendor_registry.py + - jiuwenswarm/common/openrouter_attribution.py + - jiuwenswarm/common/permission_tools.py + - jiuwenswarm/common/playwright_mcp_runtime.py + - jiuwenswarm/common/process_supervision.py + - jiuwenswarm/common/projectless_workspace.py + - jiuwenswarm/common/protocol_ids.py + - jiuwenswarm/common/reasoning_config.py + - jiuwenswarm/common/reasoning_injector.py + - jiuwenswarm/common/runtime_log_filter.py + - jiuwenswarm/common/runtime_workspace.py + - jiuwenswarm/common/security/ + - jiuwenswarm/common/session_message.py + - jiuwenswarm/common/stage_timer.py + - jiuwenswarm/common/startup_diagnostics.py + - jiuwenswarm/common/task_loop_config.py + - jiuwenswarm/common/team_artifacts.py + - jiuwenswarm/common/todo_snapshot.py + - jiuwenswarm/common/tool_display.py + - jiuwenswarm/common/tool_ownership.py + - jiuwenswarm/common/updater.py + - jiuwenswarm/common/updater_restart_helper.py + - jiuwenswarm/common/upgrade_executor.py + - jiuwenswarm/common/utils.py + - jiuwenswarm/common/version.py + - jiuwenswarm/common/version_source.py + - jiuwenswarm/common/work_mode.py + - jiuwenswarm/common/ws_diagnostics.py + - jiuwenswarm/common/ws_limits.py + - jiuwenswarm/common/acp/ + - jiuwenswarm/common/config_panel/ + - jiuwenswarm/common/schema/ +- owner: login-auth + path: repos/jiuwenswarm/components/login-auth/_index.md + signals: + - 登录 + - 华为账号 + - Account Kit + - OAuth + - PKCE + - id_token + - refresh_token + - 免费模型 + - 积分 + - APIG + - 远端配置 + - auth + scope_prefixes: + - jiuwenswarm/common/auth/ +- owner: extensions-plugins + path: repos/jiuwenswarm/components/extensions-plugins/_index.md + signals: + - extension + - 扩展 + - plugin + - 应用插件 + - hook + - registry + - loader + - manifest + - yuanrong + - openYuanRong + - clawee + - sandbox + - agentos + - AgentOS router + - 沙箱 + - ssh relay + - ephemeral key + - third agent + - agent manager + - stale cleanup + scope_prefixes: + - jiuwenswarm/extensions/agent_client/ + - jiuwenswarm/extensions/application_host.py + - jiuwenswarm/extensions/callback_compat.py + - jiuwenswarm/extensions/clawee.py + - jiuwenswarm/extensions/hook_event.py + - jiuwenswarm/extensions/hooks_context.py + - jiuwenswarm/extensions/loader.py + - jiuwenswarm/extensions/manager.py + - jiuwenswarm/extensions/registry.py + - jiuwenswarm/extensions/sdk/ + - jiuwenswarm/extensions/types.py + - jiuwenswarm/extensions/yuanrong_frontend_client.py + - jiuwenswarm/extensions/agentos/ + - jiuwenswarm/extensions/video_duplex/ +- owner: observability + path: repos/jiuwenswarm/components/observability/_index.md + signals: + - observability + - trajectory + - 轨迹 + - OTLP + - trace + - span + - sink + - SQLite + - retention + - 保留 + - turn + - session delete + scope_prefixes: + - jiuwenswarm/observability/ +- owner: agent-runtime + path: repos/jiuwenswarm/components/agent-runtime/_index.md + signals: + - runtime + - AgentRuntime + - session create/switch/fork + - session.delete + - plan mode + - model catalog + - permission snapshot + - MCP reference + - push handler + - process CLI + - agent definition + - 运行时 + - session + - 会话 + - coordinator + - execution + - cancel + - close_session + - scheduler + - run_stream + scope_prefixes: + - jiuwenswarm/runtime/agent_definition.py + - jiuwenswarm/runtime/context.py + - jiuwenswarm/runtime/events.py + - jiuwenswarm/runtime/evolution.py + - jiuwenswarm/runtime/host_services.py + - jiuwenswarm/runtime/interaction.py + - jiuwenswarm/runtime/mcp_references.py + - jiuwenswarm/runtime/mode_catalog.py + - jiuwenswarm/runtime/model_catalog.py + - jiuwenswarm/runtime/permission_catalog.py + - jiuwenswarm/runtime/plan.py + - jiuwenswarm/runtime/request.py + - jiuwenswarm/runtime/service.py + - jiuwenswarm/runtime/session_catalog.py + - jiuwenswarm/runtime/session_delete.py + - jiuwenswarm/runtime/session_input.py + - jiuwenswarm/runtime/session_lifecycle.py + - jiuwenswarm/runtime/session_provisioner.py + - jiuwenswarm/runtime/session/ +- owner: cron-scheduling + path: repos/jiuwenswarm/components/cron-scheduling/_index.md + signals: + - cron + - 定时任务 + - cron job + - cron 表达式 + - etcd + - 主备 + - HA + - cron store + - work_mode + - proactive + - 钉钉推送 + - timezone + scope_prefixes: + - jiuwenswarm/runtime/cron/ +- owner: symphony-orchestration + path: repos/jiuwenswarm/components/symphony-orchestration/_index.md + signals: + - symphony + - graph build + - 图谱构建 + - fingerprint + - 能力指纹 + - evolution + - 经验演进 + - experience candidate + - recipe + - skill taxonomy + - skill retrieval + - orchestration + - 演化 + - overlay + - 动态图谱 + - dynamic graph + - plan outcome + - failure attribution + - 失败归因 + - skill packs + scope_prefixes: + - jiuwenswarm/symphony/adapter.py + - jiuwenswarm/symphony/build.py + - jiuwenswarm/symphony/config.py + - jiuwenswarm/symphony/experience.py + - jiuwenswarm/symphony/graph_state.py + - jiuwenswarm/symphony/graph_storage.py + - jiuwenswarm/symphony/llm.py + - jiuwenswarm/symphony/service.py + - jiuwenswarm/symphony/skill_retrieval/ + - jiuwenswarm/symphony/evolution/ + - jiuwenswarm/symphony/shared/ diff --git a/knowledge/repos/jiuwenswarm/components/_index.md b/knowledge/repos/jiuwenswarm/components/_index.md new file mode 100644 index 00000000..8c290302 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/_index.md @@ -0,0 +1,20 @@ +--- +title: "jiuwenswarm components" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# jiuwenswarm components + +- [启动与多实例管理](launch/_index.md) +- [Gateway 与频道](gateway-channels/_index.md) +- [公共基础模块与配置](common-core/_index.md) +- [登录鉴权与免费模型](login-auth/_index.md) +- [扩展与插件机制](extensions-plugins/_index.md) +- [可观测性与轨迹存储](observability/_index.md) +- [Agent 运行时与会话](agent-runtime/_index.md) +- [定时任务与调度](cron-scheduling/_index.md) +- [Symphony 编排与能力图谱](symphony-orchestration/_index.md) diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md new file mode 100644 index 00000000..f9b89d66 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md @@ -0,0 +1,22 @@ +--- +title: "Agent 运行时与会话" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# Agent 运行时与会话 + +- [共享 Agent Runtime（jiuwenswarm/runtime）](jiuwenswarm-runtime.md) +- [Runtime Session 协调器（jiuwenswarm/runtime/session/）](jiuwenswarm-runtime-session.md) + +## 代码快速入口（Direct） + + +触发词：runtime、AgentRuntime、session create/switch/fork、session.delete、plan mode、model catalog、permission snapshot、MCP reference、push handler、process CLI、agent definition、运行时。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| runtime、AgentRuntime、session create/switch/fork、session.delete、plan mode、model… | 入口 | `jiuwenswarm/runtime/agent_definition.py`、`jiuwenswarm/runtime/context.py`、`jiuwenswarm/runtime/events.py` | diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime-session.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime-session.md new file mode 100644 index 00000000..8e342f90 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime-session.md @@ -0,0 +1,31 @@ +--- +title: "Runtime Session 协调器（jiuwenswarm/runtime/session/）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# Runtime Session 协调器（jiuwenswarm/runtime/session/） + +负责产品层 Session 的生命周期和执行协调，包括注册与关闭会话、调度单次（unary）和流式执行、投递 control 请求，以及取消执行及其子执行。另外维护一个有容量上限的执行登记表，记录排队中、运行中和最近结束的执行，并为每个 Session 提供一个工作调度器。 + +**从哪里开始读** + +- `jiuwenswarm/runtime/session/coordinator.py` — RuntimeSessionCoordinator 是对外入口，提供 register_session、run_unary/submit_unary、run_stream、deliver_control、cancel_execution、c + +**关键文件** + +- `jiuwenswarm/runtime/session/coordinator.py` — 管理会话记录、执行句柄的创建和取消（含子执行和心跳根）、control 请求的认领与转发，以及会话状态刷新 +- `jiuwenswarm/runtime/session/execution_registry.py` — SessionExecutionRegistry 负责执行状态流转（running/awaiting_control/waiting/terminal），终态记录按容量和 TTL 淘汰 +- `jiuwenswarm/runtime/session/work_scheduler.py` — SessionWorkScheduler 为每个 Session 分配一条 lane（按 generation 区分），负责排队执行、取消排队项、关闭时清空队列 +- `jiuwenswarm/runtime/session/model.py` — 共享模型：会话/执行状态枚举、SessionWorkKind、执行句柄与快照、取消和关闭的结果，以及超时和已结束异常 + +**相关文档** + +- `TESTING.md` — 为本模块新增或修改测试时参考。其中部分路径可能已过期，先对照 tests/ 下已有的用例 + +**改动路由** + +- `jiuwenswarm/runtime/session/` diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime.md new file mode 100644 index 00000000..35389a8b --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/jiuwenswarm-runtime.md @@ -0,0 +1,60 @@ +--- +title: "共享 Agent Runtime（jiuwenswarm/runtime）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 共享 Agent Runtime（jiuwenswarm/runtime） + +本模块是与传输层无关的共享 Agent Runtime。AgentServer 和进程式 CLI 各持有一个 `AgentRuntime`，用它完成请求规范化，处理会话的创建、切换、分叉和删除，编排 Plan 模式，并查询模型、模式、权限和 MCP 引用；WebSocket 帧、连接锁和请求/线路翻译仍由 AgentServer 负责。 + +**从这里读起** + +- `jiuwenswarm/runtime/service.py` — `AgentRuntime` 负责 Runtime 的生命周期，对外提供会话、目录查询、Plan 控制器和准入控制等公共操作 +- `jiuwenswarm/runtime/request.py` — 规范化请求：解析项目目录和模式，准备对话轮次（`prepare_chat_turn`），并处理准入（`admit_request`）和取消（`cancel_request`） +- `jiuwenswarm/runtime/context.py` — 按任务取当前的 Runtime 和 AgentManager（`get_current_runtime` / `get_current_agent_manager`） + +**关键文件** + +- `jiuwenswarm/runtime/session_provisioner.py` — 会话 create/switch/fork 的分阶段 prepare/commit/abort 契约，以及 `session.delete` 的业务事务 +- `jiuwenswarm/runtime/session_lifecycle.py` — 会话生命周期事件、activity/delete 参与者协议和 `RuntimeParticipantRegistry` +- `jiuwenswarm/runtime/session_delete.py` — 永久删除会话的结果类型、会话锁和团队删除锁，以及 `TeamDeletionGate` +- `jiuwenswarm/runtime/session_catalog.py` — 只读的会话查询接口 `get_session` / `list_sessions`，含分页和会话 ID 校验 +- `jiuwenswarm/runtime/agent_definition.py` — 根 Agent 定义的声明式校验、指纹计算，以及 `prepare_agent_execution` +- `jiuwenswarm/runtime/plan.py` — `PlanModeController`：AgentServer 和 CLI 共用的 Plan 模式状态同步、进入和退出 +- `jiuwenswarm/runtime/host_services.py` — 宿主可选注入的能力，包括 push 和 wake handler、xiaoyi channel provider；CLI 不设置这些 +- `jiuwenswarm/runtime/events.py` — `RuntimeEvent`：Runtime 向外发出的事件，与传输层无关 +- `jiuwenswarm/runtime/interaction.py` — `InteractionAnswerInput`：把对交互的回答转成 `AgentRequest`，可恢复被中断的轮次 +- `jiuwenswarm/runtime/model_catalog.py` — 不含凭据的模型目录（`build_model_catalog`）和模型选择解析（`resolve_model_selection`） +- `jiuwenswarm/runtime/permission_catalog.py` — 按会话读取权限层、工具和规则的只读快照 +- `jiuwenswarm/runtime/mcp_references.py` — 对 Runtime 引用的 MCP server 做只读校验，并返回每个引用的状态 + +**相关文档** + +- `docs/zh/MCP配置.md` — 改动 `mcp_references.py` 的 MCP 引用校验，或需要确认 MCP server 的配置来源时读 +- `docs/zh/AgentTeam.md` — 改动 `session_delete.py` 里的团队删除闸门或团队执行控制时，用它了解 Agent Team 的行为 +- `TESTING.md` — 给 Runtime 补测试时参考；其中有过期路径，要先对照 tests/ 下已有的用例 + +**改动路由** + +- `jiuwenswarm/runtime/agent_definition.py` +- `jiuwenswarm/runtime/context.py` +- `jiuwenswarm/runtime/events.py` +- `jiuwenswarm/runtime/evolution.py` +- `jiuwenswarm/runtime/host_services.py` +- `jiuwenswarm/runtime/interaction.py` +- `jiuwenswarm/runtime/mcp_references.py` +- `jiuwenswarm/runtime/mode_catalog.py` +- `jiuwenswarm/runtime/model_catalog.py` +- `jiuwenswarm/runtime/permission_catalog.py` +- `jiuwenswarm/runtime/plan.py` +- `jiuwenswarm/runtime/request.py` +- `jiuwenswarm/runtime/service.py` +- `jiuwenswarm/runtime/session_catalog.py` +- `jiuwenswarm/runtime/session_delete.py` +- `jiuwenswarm/runtime/session_input.py` +- `jiuwenswarm/runtime/session_lifecycle.py` +- `jiuwenswarm/runtime/session_provisioner.py` diff --git a/knowledge/repos/jiuwenswarm/components/common-core/_index.md b/knowledge/repos/jiuwenswarm/components/common-core/_index.md new file mode 100644 index 00000000..7384cb2b --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/common-core/_index.md @@ -0,0 +1,24 @@ +--- +title: "公共基础模块与配置" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 公共基础模块与配置 + +- [jiuwenswarm/common/：公共基础模块](jiuwenswarm-common.md) +- [ACP stdio 客户端（common/acp）](jiuwenswarm-common-acp.md) +- [配置面板 handler（config_panel）](jiuwenswarm-common-config-panel.md) +- [公共 Schema：Agent 请求响应、统一消息与参数契约](jiuwenswarm-common-schema.md) + +## 代码快速入口（Direct） + + +触发词：common、config、配置、模型选择、model catalog、mode、工作区、cron、updater、doctor、hooks、kv cache。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| common、config、配置、模型选择、model catalog、mode、工作区、cron、updater、doctor、hooks、kv cache… | 入口 | `jiuwenswarm/common/_build_config.py`、`jiuwenswarm/common/chat_final.py`、`jiuwenswarm/common/cleanup.py` | diff --git a/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-acp.md b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-acp.md new file mode 100644 index 00000000..8c022321 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-acp.md @@ -0,0 +1,30 @@ +--- +title: "ACP stdio 客户端（common/acp）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# ACP stdio 客户端（common/acp） + +这是一个最小化的 ACP 客户端：启动外部 ACP agent 子进程（如 Codex CLI），通过它的 stdin/stdout 收发 JSON-RPC 消息，负责连接、对话和关闭。它还为这类子进程组装环境变量，密钥和代理设置只从 config.yaml 的 `acp_agents..env` 读取。 + +**入口** + +- `jiuwenswarm/common/acp/stdio_client.py` — `AcpStdioClient`：用 `connect()` 建立会话，`chat()` 发消息并取回文本，`aclose()`/`close()` 结束子进程 +- `jiuwenswarm/common/acp/subprocess_env.py` — `build_acp_subprocess_env()`：为 ACP agent 子进程生成 env + +**关键文件** + +- `jiuwenswarm/common/acp/stdio_client.py` — 缓冲 stdout，用 `raw_decode` 解析可能跨多行的 JSON；处理 JSON-RPC 调用和错误、session update 文本提取、agent 发来的反向请求（路径限定在会话根目录内）、stderr 读取和进程信号 +- `jiuwenswarm/common/acp/subprocess_env.py` — 环境变量隔离规则：密钥和代理只取 profile env（支持 `${VAR}` 占位），不继承父进程，也不读 workspace `config/.env`；PATH、HOME 等系统变量仍取自 `os.environ` + +**相关文档** + +- `docs/zh/ACP插件使用.md` — 改动涉及 ACP agent 的接入、配置或使用方式时先读 + +**路由** + +- `jiuwenswarm/common/acp/` diff --git a/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-config-panel.md b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-config-panel.md new file mode 100644 index 00000000..8e6ea209 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-config-panel.md @@ -0,0 +1,35 @@ +--- +title: "配置面板 handler（config_panel）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 配置面板 handler（config_panel） + +承载 Web 侧和 TUI 侧 config / models 域的 handler 实现，从 gateway 的 app_web_handlers 和 tui_connect 迁出。AgentServer 进程里的 ConfigAdapter 和 gateway 共用这一份实现，只维护一处代码。 + +**入口** + +- `jiuwenswarm/common/config_panel/config_set_handlers.py` — Web 侧入口，register_config_set_handlers 在 channel 上注册 config.set / config.save_all；apply_config_payload 负责写盘（.env 等） +- `jiuwenswarm/common/config_panel/models_handlers.py` — Web 侧入口，register_models_handlers 注册 models.list / models.replace_all / config.validate_model / models.validate +- `jiuwenswarm/common/config_panel/tui_models_handlers.py` — TUI 侧入口，register_tui_config_handlers 注册 config.get / config.set / config.validate_model / models.list，以及 TUI 专属的 command + +**关键文件** + +- `jiuwenswarm/common/config_panel/config_set_handlers.py` — ConfigChangeSet 和 ConfigApplyResult 表示一次改动的结果（改了哪些键、要重载哪些范围）；flatten_* / build_*_config_update 负责 symphony、skill retriev +- `jiuwenswarm/common/config_panel/models_handlers.py` — 处理模型列表：前端传入的模型转成默认配置、replace_all 时的合并、环境变量占位符比较、provider 规范化、reasoning level 序列化；ConfigPanelBadRequest 是请求错误 +- `jiuwenswarm/common/config_panel/tui_models_handlers.py` — TUI 契约与 Web 侧不一致，文件头明确禁止合并；包含 build_config_schema、Auto-Harness 的 git 用户与 gitcode token 设置、模型增删改和切换，以及后台重载配置 + +**相关文档** + +- `docs/zh/E2A-protocol.md` — 改动涉及 AgentOS 多用户的 E2A 代理分叉时读。这部分由 gateway 侧的 _register_config_proxy 包装，本模块只提供本地 handler +- `docs/zh/AutoHarness.md` — 改动 TUI 侧 Auto-Harness 配置项（git user、gitcode token）时读 +- `docs/zh/AgentTeam.md` — 改动 modes team 配置的展开，或 team 相关的 codex 请求判断时读 +- `TESTING.md` — 给 config / models handler 补测试时参考；文中有过期路径，先看 tests/ 下已有用例 + +**路由** + +- `jiuwenswarm/common/config_panel/` diff --git a/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-schema.md b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-schema.md new file mode 100644 index 00000000..35c25bf2 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common-schema.md @@ -0,0 +1,36 @@ +--- +title: "公共 Schema：Agent 请求响应、统一消息与参数契约" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 公共 Schema：Agent 请求响应、统一消息与参数契约 + +定义各层共用的数据契约：Agent 请求、响应和流式分块（含 PermissionContext），统一消息模型 Message 及 ReqMethod/EventType/Mode 枚举，还有 chat.send 与 chat.swarmflow_reply 的入站参数结构。此外内置一个与 openjiuwen EventBase 对齐的最小 HookEventBase，统一扩展事件的命名和作用域，同时避开 extensions 包的循环导入。 + +**从这里读起** + +- `jiuwenswarm/common/schema/message.py` — 统一消息模型 Message，以及请求方法 ReqMethod、事件类型 EventType、运行模式 Mode 的枚举 +- `jiuwenswarm/common/schema/agent.py` — AgentRequest / AgentResponse / AgentResponseChunk，以及权限上下文 PermissionContext + +**关键文件** + +- `jiuwenswarm/common/schema/message.py` — Message 与各枚举；EventType 用 _missing_ 处理未知值，Mode.from_raw/to_runtime_mode 负责模式转换 +- `jiuwenswarm/common/schema/agent.py` — Agent 请求和响应模型；PermissionContext 提供 scene、owner_scope_key 和 to_dict/from_dict 序列化 +- `jiuwenswarm/common/schema/chat_send.py` — chat.send 的参数契约 ChatSendParams（TypedDict，total=False） +- `jiuwenswarm/common/schema/swarmflow_reply.py` — chat.swarmflow_reply 的参数契约，即真人回复 swarmflow human_session 轮次时的入站参数 +- `jiuwenswarm/common/schema/event_base.py` — HookEventBase 以及 build_event_name/parse_event_name，与 openjiuwen 0.1.9+ 的 EventBase 行为保持一致 + +**相关文档** + +- `docs/zh/E2A-protocol.md` — 改动 Message、ReqMethod、EventType 等消息与事件定义时，对照协议文档（文档和源码冲突时以源码为准） +- `docs/zh/AgentTeam人类成员联机协作.md` — 改动 swarmflow_reply 参数契约或真人成员回复链路时读 +- `docs/zh/AgentTeam.md` — 想了解 AgentRequest/AgentResponse 在 Agent Team 运行时里的使用场景时读 +- `docs/zh/A2A.md` — 改动的消息结构涉及 A2A 协议交互时对照 + +**路由** + +- `jiuwenswarm/common/schema/` diff --git a/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common.md b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common.md new file mode 100644 index 00000000..e098c4a4 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/common-core/jiuwenswarm-common.md @@ -0,0 +1,103 @@ +--- +title: "jiuwenswarm/common/：公共基础模块" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# jiuwenswarm/common/：公共基础模块 + +Gateway 和 AgentServer 共用的基础层，负责 config.yaml 的读写与迁移、模型目录、模型选择与校验、运行模式解析、工作区路径，以及南北向客户端契约等共享逻辑。进程监管、启动诊断、自动升级、后台清理和异步状态转储等进程级工具也放在这里。 + +**从这里读起** + +- `jiuwenswarm/common/config.py` — get_config / update_config：读取 config.yaml 并展开环境变量，加锁后原子写回，同时提供各特性开关的读取函数 +- `jiuwenswarm/common/mode_matrix.py` — resolve_request_mode：把 Web 的 agent/team/agent.plan 和 work_mode 组合成 canonical mode，并据此路由到 Deep 或 Code Adapter +- `jiuwenswarm/common/model_catalog.py` — ModelCatalog：只读目录，统一提供默认模型、AgentOS 模型和模型组 +- `jiuwenswarm/common/client/agent_client.py` — AgentServerClient 抽象：与 AgentServer 通信的南北向契约，Gateway 仓另有一份副本 +- `jiuwenswarm/common/process_supervision.py` — supervise：监管 AgentServer 和 Gateway 子进程，判断哪些退出需要重启 +- `jiuwenswarm/common/startup_diagnostics.py` — doctor_main：只依赖标准库的 --doctor 启动诊断，用于排查打包桌面版启动失败 +- `jiuwenswarm/common/updater.py` — UpdaterService：负责版本检查、安装包下载和升级执行 +- `jiuwenswarm/common/cleanup.py` — start_background_cleanup：按保留期定期清理旧会话数据和 file_ops 日志 + +**关键文件** + +- `jiuwenswarm/common/model_selection.py` — ModelSelection 和 Resolved* 等 DTO，描述稳定的模型选择与模型组选择 +- `jiuwenswarm/common/model_config_validation.py` — 校验模型目录和模型组 patch，并探测模型连通性 +- `jiuwenswarm/common/kv_cache_affinity_config.py` — KV cache 亲和配置和 provider 规则的权威定义 +- `jiuwenswarm/common/mcp_config.py` — 把 config.yaml 的 MCP 条目转成运行时配置，也负责预检、探活和预热 +- `jiuwenswarm/common/hooks_config.py` — 定义 config.yaml 中 hooks 段的 schema 和事件匹配逻辑 +- `jiuwenswarm/common/projectless_workspace.py` — 为无项目请求在 Documents/JiuwenSwarm 下分配按日期划分的任务目录，并登记会话 +- `jiuwenswarm/common/team_artifacts.py` — 确定 Team 成员工作目录和共享交付目录的根路径 +- `jiuwenswarm/common/cron_team_completion.py` — Gateway 和 AgentServer 共用的 cron 团队轮次结束判定 +- `jiuwenswarm/common/chat_final.py` — chat.final 的 final_mode 字段（patch_segment / replace_turn / append），决定前端如何落地最终回复 +- `jiuwenswarm/common/client/agent_http_bridge.py` — 解析受认证 HTTP bridge 的基址并执行大文件上传，大文件因此不走 E2A 帧 +- `jiuwenswarm/common/security/ws_origin.py` — 共享的 WebSocket Origin 校验 +- `jiuwenswarm/common/_build_config.py` — 由 scripts/build_config.py --sync 生成，不要手改 + +**相关文档** + +- `docs/zh/E2A-protocol.md` — 改 client/ 下的南北向契约或上传通道时，对照 E2A 线协议 +- `docs/zh/MCP配置.md` — 改 mcp_config.py 里 MCP 条目的解析或凭据处理时读 +- `docs/zh/AgentTeam.md` — 改 team 模式解析、team_artifacts.py 或 cron_team_completion.py 时读 +- `docs/zh/Harness.md` — 改 cron_team_completion.py 里 harness 轮次结束条件时读 +- `TESTING.md` — 给本模块补测试时参考；其中有过期路径，要先核对 tests/ 下已有的用例 + +**改动路由** + +- `jiuwenswarm/common/_build_config.py` +- `jiuwenswarm/common/chat_final.py` +- `jiuwenswarm/common/cleanup.py` +- `jiuwenswarm/common/client/` +- `jiuwenswarm/common/coding_memory_paths.py` +- `jiuwenswarm/common/config.py` +- `jiuwenswarm/common/context_keys.py` +- `jiuwenswarm/common/context_window.py` +- `jiuwenswarm/common/cron_session.py` +- `jiuwenswarm/common/cron_team_completion.py` +- `jiuwenswarm/common/debug_dump.py` +- `jiuwenswarm/common/external_cli_catalog.py` +- `jiuwenswarm/common/external_cli_runtime.py` +- `jiuwenswarm/common/git_safe_directory.py` +- `jiuwenswarm/common/hooks_config.py` +- `jiuwenswarm/common/kv_cache_affinity_config.py` +- `jiuwenswarm/common/log_preview.py` +- `jiuwenswarm/common/mcp_config.py` +- `jiuwenswarm/common/media_capability_config.py` +- `jiuwenswarm/common/mode_matrix.py` +- `jiuwenswarm/common/model_catalog.py` +- `jiuwenswarm/common/model_config_validation.py` +- `jiuwenswarm/common/model_errors.py` +- `jiuwenswarm/common/model_migration.py` +- `jiuwenswarm/common/model_selection.py` +- `jiuwenswarm/common/model_vendor_registry.py` +- `jiuwenswarm/common/openrouter_attribution.py` +- `jiuwenswarm/common/permission_tools.py` +- `jiuwenswarm/common/playwright_mcp_runtime.py` +- `jiuwenswarm/common/process_supervision.py` +- `jiuwenswarm/common/projectless_workspace.py` +- `jiuwenswarm/common/protocol_ids.py` +- `jiuwenswarm/common/reasoning_config.py` +- `jiuwenswarm/common/reasoning_injector.py` +- `jiuwenswarm/common/runtime_log_filter.py` +- `jiuwenswarm/common/runtime_workspace.py` +- `jiuwenswarm/common/security/` +- `jiuwenswarm/common/session_message.py` +- `jiuwenswarm/common/stage_timer.py` +- `jiuwenswarm/common/startup_diagnostics.py` +- `jiuwenswarm/common/task_loop_config.py` +- `jiuwenswarm/common/team_artifacts.py` +- `jiuwenswarm/common/todo_snapshot.py` +- `jiuwenswarm/common/tool_display.py` +- `jiuwenswarm/common/tool_ownership.py` +- `jiuwenswarm/common/updater.py` +- `jiuwenswarm/common/updater_restart_helper.py` +- `jiuwenswarm/common/upgrade_executor.py` +- `jiuwenswarm/common/utils.py` +- `jiuwenswarm/common/version.py` +- `jiuwenswarm/common/version_source.py` +- `jiuwenswarm/common/work_mode.py` +- `jiuwenswarm/common/ws_diagnostics.py` +- `jiuwenswarm/common/ws_limits.py` diff --git a/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md b/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md new file mode 100644 index 00000000..485fcd7b --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md @@ -0,0 +1,21 @@ +--- +title: "定时任务与调度" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 定时任务与调度 + +- [定时任务（Cron）运行时：任务模型、存储后端与投递路由](jiuwenswarm-runtime-cron.md) + +## 代码快速入口（Direct） + + +触发词：cron、定时任务、cron job、cron 表达式、etcd、主备、HA、cron store、work_mode、proactive、钉钉推送、timezone。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| cron、定时任务、cron job、cron 表达式、etcd、主备、HA、cron store、work_mode、proactive、钉钉推送、time… | 入口 | `jiuwenswarm/runtime/cron/` | diff --git a/knowledge/repos/jiuwenswarm/components/cron-scheduling/jiuwenswarm-runtime-cron.md b/knowledge/repos/jiuwenswarm/components/cron-scheduling/jiuwenswarm-runtime-cron.md new file mode 100644 index 00000000..969430f8 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/cron-scheduling/jiuwenswarm-runtime-cron.md @@ -0,0 +1,31 @@ +--- +title: "定时任务（Cron）运行时：任务模型、存储后端与投递路由" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 定时任务（Cron）运行时：任务模型、存储后端与投递路由 + +负责定时任务（CronJob）的数据模型、cron 表达式的校验与下次触发时间计算，以及任务的持久化。持久化有两种后端：个人版用文件存储，主备 Gateway 用 etcd 存储，两者都实现同一个存储协议。模块还负责把钉钉里创建的定时任务推送回发起它的会话。 + +**从这里读起** + +- `jiuwenswarm/runtime/cron/factory.py` — load_cron_store_settings 读取配置，create_gateway_cron_store 据此选用文件存储或 etcd 存储 +- `jiuwenswarm/runtime/cron/store_base.py` — CronJobStoreBackend 协议：定义 list/get/create/update/delete/get_revision/watch/aclose，两种后端都要实现 +- `jiuwenswarm/runtime/cron/models.py` — CronJob、CronTarget、CronRunState 数据模型，以及目标频道、运行模式、超时、MCP、模型字段的规范化与校验 + +**关键文件** + +- `jiuwenswarm/runtime/cron/cron_job_mutations.py` — 文件和 etcd 两种存储共用的任务构建、patch 合并、work_mode 推断与迁移逻辑，以及 proactive 任务的改删保护 +- `jiuwenswarm/runtime/cron/store.py` — FileCronJobStore：在文件锁下读写 JSON，用文件修订号实现 watch，另有 disable_project_jobs +- `jiuwenswarm/runtime/cron/etcd_store.py` — EtcdCronJobStore：主备 Gateway 用的 etcd 存储，更新时带 mod_revision 做 CAS，并监听前缀变化 +- `jiuwenswarm/runtime/cron/etcd_client.py` — 基于 httpx 的精简 etcd v3 gRPC-gateway JSON 客户端（range/put/delete/CAS/watch），不依赖 grpc +- `jiuwenswarm/runtime/cron/cron_expr.py` — cron 表达式规范化、按时区校验、把 ISO 时间转成 7 段 cron、计算下次触发时间 +- `jiuwenswarm/runtime/cron/dingtalk_routing.py` — 钉钉定时任务的会话 ID 编码与解析，以及推送元数据解析（Issue #2449） + +**路由** + +- `jiuwenswarm/runtime/cron/` diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md new file mode 100644 index 00000000..c57eed47 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md @@ -0,0 +1,23 @@ +--- +title: "扩展与插件机制" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 扩展与插件机制 + +- [扩展机制与 openYuanRong 集成（jiuwenswarm/extensions/）](jiuwenswarm-extensions.md) +- [AgentOS 扩展：AgentOS Router 与 SSH/Token 鉴权](jiuwenswarm-extensions-agentos.md) +- [视频全双工扩展（video_duplex）](jiuwenswarm-extensions-video-duplex.md) + +## 代码快速入口（Direct） + + +触发词：extension、扩展、plugin、应用插件、hook、registry、loader、manifest、yuanrong、openYuanRong、clawee、sandbox。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| extension、扩展、plugin、应用插件、hook、registry、loader、manifest、yuanrong、openYuanRong、cl… | 入口 | `jiuwenswarm/extensions/agent_client/`、`jiuwenswarm/extensions/application_host.py`、`jiuwenswarm/extensions/callback_compat.py` | diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-agentos.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-agentos.md new file mode 100644 index 00000000..bafd9a53 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-agentos.md @@ -0,0 +1,42 @@ +--- +title: "AgentOS 扩展：AgentOS Router 与 SSH/Token 鉴权" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# AgentOS 扩展：AgentOS Router 与 SSH/Token 鉴权 + +该扩展由 ExtensionLoader 发现并加载。它的 AgentOSRouter 同时实现 AgentServerClient 和 ThirdAgent 扩展，把 Gateway 请求按用户/会话键路由到 YuanRong 沙箱里的 Agent 实例，管理实例的创建、复用、释放、删除，以及重启后残留沙箱的清理，并通过 registry HTTP API 登记这些实例。auth/ 子目录提供 WebSocket 握手鉴权、AgentOS token 鉴权、临时 SSH 密钥签发和指纹登记，南向 SSH 中继依赖这些功能。 + +**从这里读起** + +- `jiuwenswarm/extensions/agentos/extension.py` — 扩展入口，ExtensionLoader 从这里发现 AgentOS 扩展 +- `jiuwenswarm/extensions/agentos/agentos_router/extension.py` — AgentOSRouter 与 register_extensions：负责初始化、提供 client 和 third agent、注入 key issuer、关闭 +- `jiuwenswarm/extensions/agentos/agentos_router/router_client.py` — AgentOSRouterClient：请求路由、HTTP 鉴权、频道事件、连接预热与延迟清理、文件上传下载路径 + +**关键文件** + +- `jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py` — AgentManager/AgentRuntime：按键 get_or_create、状态流转（creating/ready/failed/deleted）、空闲回收、用户连接计数 +- `jiuwenswarm/extensions/agentos/agentos_router/registry_client.py` — registry HTTP SDK：镜像 launch-spec/list，实例 register/update/list/unregister；endpoint 为空时只在本地运行 +- `jiuwenswarm/extensions/agentos/agentos_router/ssh_relay.py` — YuanrongSshRelay：把北向 SshRelaySession 桥接到 YuanRong 前端 SSH 端点 +- `jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py` — 启动时对照 registry 销毁上个进程留下的沙箱，并跳过已有的 live runtime +- `jiuwenswarm/extensions/agentos/agentos_router/config.py` — RouterConfig 与 SSH 通道端点配置加载，含环境变量覆盖和数值校验 +- `jiuwenswarm/extensions/agentos/agentos_router/third_agent.py` — AgentOSThirdAgent：列出和切换第三方 Agent 类型 +- `jiuwenswarm/extensions/agentos/agentos_router/agentos_authenticator.py` — AgentOSAuthenticator：调用外部 auth service 校验 token +- `jiuwenswarm/extensions/agentos/agentos_router/models.py` — AgentStatus、ImageInfo、AgentInfo 数据模型 +- `jiuwenswarm/extensions/agentos/auth/common.py` — WebSocket 握手鉴权工具：提取 token 和请求头，缓存握手结果并写回 ws +- `jiuwenswarm/extensions/agentos/auth/ssh_key_issuer.py` — 签发短期 SSH 密钥对，并把公钥指纹登记到 KeyRegistry +- `jiuwenswarm/extensions/agentos/auth/ssh_authenticator.py` — SshPublicKeyAuthenticator：通过 KeyRegistry 校验公钥指纹 +- `jiuwenswarm/extensions/agentos/agentos_router/logutil.py` — 格式固定、便于 grep 的 AgentOS 日志行（session_id/sandbox_id 字段） + +**相关文档** + +- `docs/zh/E2A-protocol.md` — 改动涉及 AgentRuntime.attach_to_envelope 或路由用到的 E2AEnvelope 字段时读 +- `docs/zh/AgentTeam.md` — 改动涉及 router_client 的 team 模式判断时读 + +**路由** + +- `jiuwenswarm/extensions/agentos/` diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-video-duplex.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-video-duplex.md new file mode 100644 index 00000000..994042ec --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions-video-duplex.md @@ -0,0 +1,43 @@ +--- +title: "视频全双工扩展（video_duplex）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 视频全双工扩展（video_duplex） + +video_duplex 是一个应用插件，负责 Jiuwen Web 上的实时音视频问答，支持 JoyAI 与 Qwen-Omni Realtime 两类 provider，并提供共用的 ASR/TTS 适配。用户在通话中委派的任务会写入基于 SQLite 的持久化任务服务，再交给 Core Agent 执行，执行时通过根 Agent 回调和 E2A checkpoint 注入需求变更。 + +**从哪里开始读** + +- `jiuwenswarm/extensions/video_duplex/extension.py` — VideoDuplexApplicationPlugin 与 register_extensions：插件初始化和关闭、绑定 Web 频道、设置读写 RPC、WebSocket 路由、前端贡献 +- `jiuwenswarm/extensions/video_duplex/backend/video_live.py` — register_video_live_handler：实时音视频问答的 Web RPC 入口（realtime 配置、JoyAI 帧、遥测、对话追加） +- `jiuwenswarm/extensions/video_duplex/backend/qwen_omni_gateway.py` — serve_qwen_omni_websocket：浏览器与 Qwen-Omni Realtime 之间带鉴权的双向 WebSocket 中继 +- `jiuwenswarm/extensions/video_duplex/backend/task_adapter.py` — VideoSearchManager 的 handle_qwen_tool/status/list/answer/control，对接共享 Host 任务服务的 RPC 适配 +- `jiuwenswarm/extensions/video_duplex/backend/tasks/server_adapter.py` — VoiceTaskServerAdapter：AgentServer 侧处理 checkpoint ACK 和任务产出文件的端点 + +**关键文件** + +- `jiuwenswarm/extensions/video_duplex/backend/tasks/service.py` — TaskService：任务的提交、修改、取消、重排、抢占、回答、进度持久化和并发调度，不依赖媒体层和 RPC +- `jiuwenswarm/extensions/video_duplex/backend/tasks/store.py` — TaskStore：用 SQLite 记录任务事实，并保证用户操作幂等（command/replay） +- `jiuwenswarm/extensions/video_duplex/backend/tasks/rail.py` — VoiceAgentTaskRail：根 Agent 在模型调用前后和工具调用前的回调，注入语音委派任务的需求与身份 +- `jiuwenswarm/extensions/video_duplex/backend/tasks/execution.py` — TaskExecutionBinding（继承 checkpoint.py 的 TaskCheckpoint）：绑定 Host 请求和输出租约，观察原生执行的结算 +- `jiuwenswarm/extensions/video_duplex/backend/tasks/bridge.py` — GatewayTaskEndpoint/RemoteTaskEndpoint：通过 E2A push/ACK 通道下发由 Gateway 发起的 checkpoint 命令 +- `jiuwenswarm/extensions/video_duplex/backend/tasks/interactions.py` — 校验信息类问题和原生审批问题的答案，并确保这些答案不会获得审批权限 +- `jiuwenswarm/extensions/video_duplex/backend/tasks/prompts.py` — 面向模型的任务查询、回执和执行指令，以及简报 prompt；用户需求和结果按不透明数据处理 +- `jiuwenswarm/extensions/video_duplex/backend/qwen_omni_tools.py` — Qwen-Omni Realtime 的工具定义，以及工具调用请求的解析和校验 +- `jiuwenswarm/extensions/video_duplex/backend/joyai_provider.py` — JoyAI 的视频帧、动作解析、ASR 转写和 TTS 合成协议适配，以及限流错误 +- `jiuwenswarm/extensions/video_duplex/backend/video_voice.py` — 各 provider 共用的 ASR/TTS 端点解析，以及 tts 合成、流式、取消和转写 RPC handler +- `jiuwenswarm/extensions/video_duplex/backend/video_search.py` — Core Agent 执行与异步搜索任务，生成结果简报（nonce 标记）和进度 +- `jiuwenswarm/extensions/video_duplex/backend/settings.py` — 插件自有配置写回 env 文件，包括启用开关、provider 和回复语言 + +**相关文档** + +- `docs/zh/E2A-protocol.md` — 改到 tasks/bridge.py 的 checkpoint push/ACK 流程或 server_adapter.py 时读，确认 E2A 通道的字段和语义 + +**按改动找页面** + +- `jiuwenswarm/extensions/video_duplex/` diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions.md new file mode 100644 index 00000000..dab6c13b --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/jiuwenswarm-extensions.md @@ -0,0 +1,49 @@ +--- +title: "扩展机制与 openYuanRong 集成（jiuwenswarm/extensions/）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 扩展机制与 openYuanRong 集成（jiuwenswarm/extensions/） + +负责 JiuwenSwarm 的扩展体系：查找、加载和管理扩展，用 ExtensionRegistry 统一登记 AgentServerClient、加密工具、第三方 Agent、应用插件等扩展点，并提供 Gateway/AgentServer 的 hook 事件与上下文；应用插件的 HTTP、WebSocket 路由和前端资源也在这里挂载。同一目录下还有 openYuanRong 集成：Frontend HTTP 客户端、对应的 AgentServerClient 扩展，以及 clawee FaaS 函数入口。 + +**从这里读起** + +- `jiuwenswarm/extensions/manager.py` — ExtensionManager：从配置解析扩展目录，load_all_extensions / shutdown_all_extensions / list_extensions 管理全部扩展的生命周期 +- `jiuwenswarm/extensions/registry.py` — ExtensionRegistry 单例：注册和获取各类扩展，register/unregister/trigger 负责 hook 事件分发；应用插件在这里绑定 web channel +- `jiuwenswarm/extensions/application_host.py` — 应用插件宿主：生成插件清单，挂载插件的 HTTP 路由和静态资源，枚举插件的 WebSocket 路由 +- `jiuwenswarm/extensions/clawee.py` — openYuanRong 函数入口（init/handler/ahandler/pre_stop），复用 AgentWebSocketServer._handle_message，FaaS 链路和 ws 链路走同一套处理代码 +- `jiuwenswarm/extensions/agent_client/extension.py` — YuanrongAgentServerClientExtension 与 register_extensions：把 Yuanrong 客户端注册为 AgentServerClient 扩展 + +**关键文件** + +- `jiuwenswarm/extensions/loader.py` — ExtensionLoader：在搜索路径中识别扩展根目录，读取 manifest，安装依赖，导入入口模块 +- `jiuwenswarm/extensions/sdk/base.py` — BaseExtension 抽象基类：initialize/shutdown 生命周期，从 YAML 读取元数据和配置 +- `jiuwenswarm/extensions/sdk/application_plugin.py` — ApplicationPluginExtension、ManifestApplicationPlugin，以及 WebSocket 路由和前端贡献的数据结构 +- `jiuwenswarm/extensions/sdk/agent_server_client.py` — AgentServerClientExtension 扩展点：提供 AgentServerClient +- `jiuwenswarm/extensions/sdk/crypto_utility.py` — CryptoUtility 扩展点：提供 CryptoProvider，由 registry 桥接加解密 +- `jiuwenswarm/extensions/sdk/third_agent.py` — ThirdAgentExtension 扩展点：提供第三方 Agent +- `jiuwenswarm/extensions/hook_event.py` — GatewayHookEvents / AgentServerHookEvents：hook 事件名定义 +- `jiuwenswarm/extensions/hooks_context.py` — Memory、Gateway 对话、AgentServer 对话、SystemPrompt 这几类 hook 的上下文对象 +- `jiuwenswarm/extensions/types.py` — ExtensionMetadata / ExtensionConfig 类型 +- `jiuwenswarm/extensions/callback_compat.py` — 兼容 openjiuwen<0.1.9 的 AsyncCallbackFramework：补上缺失的 unregister_sync +- `jiuwenswarm/extensions/yuanrong_frontend_client.py` — YuanrongFrontendAgentClient：调用 openYuanRong Frontend 函数，管理常驻 agent 沙箱，处理 trace id 和 TCP 探针配置 + +**路由** + +- `jiuwenswarm/extensions/agent_client/` +- `jiuwenswarm/extensions/application_host.py` +- `jiuwenswarm/extensions/callback_compat.py` +- `jiuwenswarm/extensions/clawee.py` +- `jiuwenswarm/extensions/hook_event.py` +- `jiuwenswarm/extensions/hooks_context.py` +- `jiuwenswarm/extensions/loader.py` +- `jiuwenswarm/extensions/manager.py` +- `jiuwenswarm/extensions/registry.py` +- `jiuwenswarm/extensions/sdk/` +- `jiuwenswarm/extensions/types.py` +- `jiuwenswarm/extensions/yuanrong_frontend_client.py` diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md new file mode 100644 index 00000000..1befe024 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md @@ -0,0 +1,22 @@ +--- +title: "Gateway 与频道" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# Gateway 与频道 + +- [CLI 频道（jiuwenswarm/channels/cli）](jiuwenswarm-channels-cli.md) +- [进程式 CLI 频道（process_cli）](jiuwenswarm-channels-process-cli.md) + +## 代码快速入口（Direct） + + +触发词：cli、chat、命令行、CLI 频道、gateway client、websocket、tui、renderer、jsonl、spinner、SIGINT、受信目录。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| cli、chat、命令行、CLI 频道、gateway client、websocket、tui、renderer、jsonl、spinner、SIGINT、… | 入口 | `jiuwenswarm/channels/cli/`、`jiuwenswarm/channels/process_cli/` | diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-cli.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-cli.md new file mode 100644 index 00000000..e43c3eca --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-cli.md @@ -0,0 +1,36 @@ +--- +title: "CLI 频道（jiuwenswarm/channels/cli）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# CLI 频道（jiuwenswarm/channels/cli） + +提供根命令 `jiuwenswarm` 的 CLI 入口和命令行聊天频道：解析参数，通过兼容 `/tui` 的 WebSocket 连接 Gateway，再把流式事件渲染成人类可读、JSON 或 JSONL 输出。交互模式下还负责权限确认和用户输入、Ctrl+C（SIGINT）中断，以及受信目录的持久化和清理。 + +**从这里读起** + +- `jiuwenswarm/channels/cli/main.py` — 根命令 `jiuwenswarm` 的 CLI 入口 `main()` +- `jiuwenswarm/channels/cli/chat.py` — chat 命令的编排入口：`build_parser` 定义参数，`run_chat` 连接 Gateway 并运行 interactive、json 或 jsonl 循环 + +**关键文件** + +- `jiuwenswarm/channels/cli/chat.py` — 参数校验、请求构造、spinner、SIGINT 处理（含 Windows 分支）、受信目录状态读写和权限卡片应答 +- `jiuwenswarm/channels/cli/gateway_client.py` — `GatewayClient`：兼容 `/tui` 的 WebSocket 客户端，负责 connect、send_request、recv 和 close；`set_mock_ws` 供测试注入 +- `jiuwenswarm/channels/cli/render.py` — `HumanRenderer`、`JsonRenderer`、`JsonlRenderer`，分别处理三种输出模式下的 delta、reasoning、tool_call、final 和 error 事件 +- `jiuwenswarm/channels/cli/events.py` — 事件判定：内容是否结束、流是否终止、是否需要用户输入，以及事件归类 +- `jiuwenswarm/channels/cli/_terminal.py` — 用 `os.write` 实现的终端输出原语；按 docstring 所说，这是终端 UI，不是日志，所以没有走 `logging`（G.LOG.02） + +**相关文档** + +- `docs/zh/Quickstart.md` — 想了解用户通常怎样启动和使用命令行时读 +- `README_CN.md` — 需要项目总体介绍，或核对 CLI 在整体架构里的位置时读 +- `docs/zh/FAQ.md` — PR 改动连接提示、报错文案或常见使用问题时读 +- `TESTING.md` — PR 新增或修改 CLI 测试时参考；其中有过期路径，要先对照 tests/ 下已有的用例 + +**改动路由** + +- `jiuwenswarm/channels/cli/` diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-process-cli.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-process-cli.md new file mode 100644 index 00000000..99bfd17d --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/jiuwenswarm-channels-process-cli.md @@ -0,0 +1,44 @@ +--- +title: "进程式 CLI 频道（process_cli）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 进程式 CLI 频道（process_cli） + +进程式 JiuwenSwarm CLI 频道：交互式 REPL 给每条命令启动一个独立的 Runtime worker 进程；另有两类入口，一类是面向机器的一次性执行（NDJSON 输出，可选双工应答/取消控制），另一类是只读查询。所有入口都通过进程内客户端调用共享的 Agent Runtime Public API。 + +**入口** + +- `jiuwenswarm/channels/process_cli/main.py` — CLI 总入口：main() 与 build_parser()（中文 argparse），处理工作目录切换、stdio 转发和 Windows worker 的中断 +- `jiuwenswarm/channels/process_cli/repl.py` — run_repl：交互式启动器，给每条命令拉起 worker 进程，并处理 /new、/resume、/branch、/delete 等斜杠命令 +- `jiuwenswarm/channels/process_cli/app.py` — run/execute：单条命令在 worker 进程里的完整生命周期，包括会话创建/切换/分叉/删除、交互应答和事件消费 +- `jiuwenswarm/channels/process_cli/machine_entry.py` — execute_source：机器模式的轻量启动入口，先设置好 stdout/cwd 再导入 Runtime，分文档输入和双工输入两种方式 +- `jiuwenswarm/channels/process_cli/query_entry.py` — execute_query_source：只读查询的启动入口，先校验输入再导入 Runtime + +**关键文件** + +- `jiuwenswarm/channels/process_cli/client.py` — InProcessRuntimeClient：进程内调用共享 Runtime Public API 的客户端，负责会话准备/提交/回滚、流式调用、应答和取消 +- `jiuwenswarm/channels/process_cli/protocol/model.py` — 一次性执行的值契约：OneShotRunInput、OneShotEvent、OneShotRunResult、AgentSpec、WorkspaceSpec 等 +- `jiuwenswarm/channels/process_cli/protocol/jsonl.py` — 一次性执行记录的严格 NDJSON 编解码，并校验记录身份 +- `jiuwenswarm/channels/process_cli/protocol/version.py` — 机器 schema 的版本标记和版本支持校验 +- `jiuwenswarm/channels/process_cli/machine.py` — run_machine：通过共享 Runtime 执行一条机器请求，收集结果并清理资源 +- `jiuwenswarm/channels/process_cli/machine_io.py` — 机器模式的有界单文档输入读取，以及 OneShotWriter 流式输出 +- `jiuwenswarm/channels/process_cli/duplex_control.py` — DuplexController：把单条命令在 stdio 上收到的应答/取消控制路由过去；执行和审批仍由 Runtime 负责 +- `jiuwenswarm/channels/process_cli/duplex_protocol.py` — 双工控制记录（answer/cancel）的严格解码，只携带关联 ID 和应答值 +- `jiuwenswarm/channels/process_cli/duplex_input.py` — DuplexLineReader：可取消、有长度上限的 stdin 行读取，Windows 与 POSIX 走不同实现 +- `jiuwenswarm/channels/process_cli/session_guard.py` — SessionLease：机器模式下同一个 Session 的跨进程所有权租约 +- `jiuwenswarm/channels/process_cli/live_input.py` — LiveSessionInputController：TTY 实时补充输入（steer），以及投递回执的分类 +- `jiuwenswarm/channels/process_cli/render.py` — EventRenderer：把 Runtime 事件流渲染成 human、JSON 或 JSONL 输出 + +**相关文档** + +- `docs/zh/Quickstart.md` — 想了解用户怎样启动和使用 JiuwenSwarm 时读；本模块的机器协议字段以 protocol/ 下的源码为准 +- `TESTING.md` — 为 CLI 改动补测试时参考；其中有过期路径，要先对照 tests/ 下现有的用例 + +**路由** + +- `jiuwenswarm/channels/process_cli/` diff --git a/knowledge/repos/jiuwenswarm/components/launch/_index.md b/knowledge/repos/jiuwenswarm/components/launch/_index.md new file mode 100644 index 00000000..55f07154 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/launch/_index.md @@ -0,0 +1,23 @@ +--- +title: "启动与多实例管理" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 启动与多实例管理 + +- [jiuwenswarm 顶层包：启动入口、多实例与运行时补丁](jiuwenswarm.md) +- [桌面端应用外壳（channels/desktop）](jiuwenswarm-channels-desktop.md) +- [instance_manager：多实例配置、端口与进程管理](jiuwenswarm-instance-manager.md) + +## 代码快速入口（Direct） + + +触发词：start_services、jiuwenswarm-start、debug launcher、multi-instance、--dotenv、--name、jiuwenswarm-init、init workspace、dotenv_early、SSE patch、ModelArts、compat alias。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| start_services、jiuwenswarm-start、debug launcher、multi-instance、--dotenv、--name、… | 入口 | `jiuwenswarm/acp/`、`jiuwenswarm/app.py`、`jiuwenswarm/channels/acp/` | diff --git a/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-channels-desktop.md b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-channels-desktop.md new file mode 100644 index 00000000..c6c4aad2 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-channels-desktop.md @@ -0,0 +1,30 @@ +--- +title: "桌面端应用外壳（channels/desktop）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 桌面端应用外壳（channels/desktop） + +桌面端的启动外壳：解析端口，拉起子进程并记录日志，再等待子进程的 TCP/HTTP 服务就绪。它还通过 `_WindowApi` 给页面提供几类能力：控制窗口、记住关闭行为偏好、打开外部链接、安装更新（Windows 安装器）、下载和保存文件（data URL 或分块传输的 blob）。 + +**从哪里开始读** + +- `jiuwenswarm/channels/desktop/desktop_app.py` — 从 `resolve_desktop_ports`、`_start_process`、`_wait_for_tcp`/`_wait_for_http` 读起，看桌面端如何分配端口、拉起子进程并等它们就绪 + +**关键文件** + +- `jiuwenswarm/channels/desktop/desktop_app.py` — 本模块唯一的文件，包含下面几部分 + +**相关文档** + +- `README_CN.md` — 想先了解产品整体和安装、启动方式时读（没有确认里面是否专门讲桌面端） +- `docs/zh/Quickstart.md` — 想知道桌面端会拉起哪些服务、正常启动流程是什么样时参考 +- `docs/zh/FAQ.md` — 排查启动失败、端口占用这类常见问题时查 + +**改动路由** + +- `jiuwenswarm/channels/desktop/` diff --git a/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-instance-manager.md b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-instance-manager.md new file mode 100644 index 00000000..1aa330f4 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm-instance-manager.md @@ -0,0 +1,37 @@ +--- +title: "instance_manager：多实例配置、端口与进程管理" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# instance_manager：多实例配置、端口与进程管理 + +负责 JiuwenSwarm 多实例的配置与生命周期：维护 instances.yaml、校验实例名、分配端口并检测冲突、为每个实例生成 bootstrap .env。它还用锁文件和 PID 文件控制实例并发启动，并负责查询实例状态和停止实例进程。 + +**从这里开始读** + +- `jiuwenswarm/instance_manager/status.py` — list_all_instances、get_instance_status 查询实例状态，stop_instance_process 停止实例进程 +- `jiuwenswarm/instance_manager/bootstrap.py` — create_bootstrap_env 为实例生成 bootstrap .env；load_instance_bootstrap_by_name 在 argparse 解析后加载它；带有 main() +- `jiuwenswarm/instance_manager/yaml.py` — load_instances_yaml 和 update_instances_yaml 负责读写并校验 instances.yaml + +**关键文件** + +- `jiuwenswarm/instance_manager/config.py` — InstanceConfig、InstanceStatus 数据类，BASE_PORTS、RESERVED_NAMES 等常量，实例名校验，端口计算、探测与冲突检查 +- `jiuwenswarm/instance_manager/lock.py` — InstanceLock（跨平台启动锁，含过期锁清理）、GatewayLock、PID 文件读写和进程存活检测 +- `jiuwenswarm/instance_manager/status.py` — 按 PID、进程组和监听端口判断进程是否属于本实例，再安全停止；这里的判断逻辑较细，审查时重点看 +- `jiuwenswarm/instance_manager/yaml.py` — 实例目录和工作区路径，instances.yaml 结构与端口字段校验，get_instance_index +- `jiuwenswarm/instance_manager/bootstrap.py` — bootstrap .env 的生成与加载，包括不依赖其他模块的早期创建函数 _create_basic_bootstrap_env + +**相关文档** + +- `docs/zh/Quickstart.md` — 想了解用户怎样启动 JiuwenSwarm，从而判断改动对启动流程的影响时读 +- `README_CN.md` — 需要项目整体介绍和启动方式概览时读 +- `docs/zh/FAQ.md` — 改动涉及启动失败、端口占用等用户常见问题时，查看已有说法 +- `TESTING.md` — 给本模块补测试时参考；其中有过期路径，要以 tests/ 下实际存在的用例为准 + +**改动路由** + +- `jiuwenswarm/instance_manager/` diff --git a/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm.md b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm.md new file mode 100644 index 00000000..9fa34c17 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/launch/jiuwenswarm.md @@ -0,0 +1,52 @@ +--- +title: "jiuwenswarm 顶层包：启动入口、多实例与运行时补丁" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# jiuwenswarm 顶层包：启动入口、多实例与运行时补丁 + +负责 JiuwenSwarm 的进程启动和初始化：一条命令拉起 AgentServer 与 Gateway、管理多实例（--dotenv/--name）、本地 debug 构建启动、初始化用户数据目录，并在 import 链最前面解析 dotenv。这里还放着 OpenAI/Anthropic 各家方言和 SSE 网关的运行时补丁，以及 `acp/`、`cli/` 下为迁走模块保留的兼容别名。 + +**入口** + +- `jiuwenswarm/start_services.py` — `jiuwenswarm-start` 主入口：按模式启动前后端服务，处理 --list/--status/--stop/--restart/--name 多实例命令、端口检查和端口回退 +- `jiuwenswarm/app.py` — 先后启动 `server.app_agentserver` 和 `gateway.app_gateway` 两个进程，支持 --dotenv 多实例隔离 +- `jiuwenswarm/debug_launcher.py` — `jiuwenswarm-start debug`：npm install/build 前端、按 config.yaml 里启用的外部 CLI agent 执行 uv sync，再在后台启动服务并写入带时间戳的日志；也负责停止后台服务 +- `jiuwenswarm/init_workspace.py` — `jiuwenswarm-init`：询问语言偏好，把 config.yaml、.env 模板、agent 模板和多语言文件复制到用户数据根目录；支持 -f 强制重建和 --name 命名实例 +- `jiuwenswarm/channels/acp/app_acp.py` — ACP 频道的命令行入口：用 argparse 解析参数，run_acp 负责运行，结果以 JSON 写到 stdout +- `jiuwenswarm/acp/cli.py` — 外部 ACP agent（stdio）的 CLI 冒烟测试，与 acp_chat 工具共用同一份配置 +- `jiuwenswarm/cli/main.py` — 历史远程 CLI 模块路径的兼容入口 + +**关键文件** + +- `jiuwenswarm/dotenv_early.py` — 扫描 sys.argv 里的 --dotenv/--name，设置 JIUWENSWARM_DATA_DIR；必须在导入其他 jiuwenswarm 模块之前调用 +- `jiuwenswarm/llm_provider_compat_patch.py` — 运行时补丁：修正 ModelArts 等 provider 在 Anthropic 参数和 OpenAI tool_choice 上的方言差异 +- `jiuwenswarm/llm_sse_patch.py` — 给 OpenAIModelClient._parse_response 打补丁：非流式 invoke() 收到只含 SSE 文本的响应时，先组装成 ChatCompletion 再交给原逻辑解析 +- `jiuwenswarm/acp/stdio_client.py` — ACP stdio 客户端的 re-export，实现已移到 `jiuwenswarm.common.acp`；console script `jiuwenswarm-acp-chat` 仍引用这个路径 +- `jiuwenswarm/acp/subprocess_env.py` — ACP 子进程环境构造的 re-export，按 docstring 计划在阶段 3 随 `acp/` 目录一起删除 +- `jiuwenswarm/cli/chat.py` — `channels.cli.chat` 的兼容别名；同目录下的 _terminal/events/gateway_client/render 也是同类别名 + +**相关文档** + +- `docs/zh/Quickstart.md` — 改动涉及启动命令、初始化流程或默认启动模式时读 +- `README_CN.md` — 核对 jiuwenswarm-start / jiuwenswarm-init 等命令的对外说明是否与改动一致时读 +- `docs/zh/ACP插件使用.md` — 改动涉及 acp/cli.py、channels/acp/app_acp.py 或 ACP 兼容路径时读 +- `docs/zh/FAQ.md` — 改动影响端口、多实例或启动报错等常见问题的表现时读 +- `TESTING.md` — 给启动器或补丁补测试时参考；里面有过期路径，应以 tests/ 下现有用例为准 + +**路由** + +- `jiuwenswarm/acp/` +- `jiuwenswarm/app.py` +- `jiuwenswarm/channels/acp/` +- `jiuwenswarm/cli/` +- `jiuwenswarm/debug_launcher.py` +- `jiuwenswarm/dotenv_early.py` +- `jiuwenswarm/init_workspace.py` +- `jiuwenswarm/llm_provider_compat_patch.py` +- `jiuwenswarm/llm_sse_patch.py` +- `jiuwenswarm/start_services.py` diff --git a/knowledge/repos/jiuwenswarm/components/login-auth/_index.md b/knowledge/repos/jiuwenswarm/components/login-auth/_index.md new file mode 100644 index 00000000..081d98d0 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/login-auth/_index.md @@ -0,0 +1,21 @@ +--- +title: "登录鉴权与免费模型" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 登录鉴权与免费模型 + +- [华为账号登录与免费模型凭据（common/auth）](jiuwenswarm-common-auth.md) + +## 代码快速入口（Direct） + + +触发词：登录、华为账号、Account Kit、OAuth、PKCE、id_token、refresh_token、免费模型、积分、APIG、远端配置、auth。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| 登录、华为账号、Account Kit、OAuth、PKCE、id_token、refresh_token、免费模型、积分、APIG、远端配置、auth | 入口 | `jiuwenswarm/common/auth/` | diff --git a/knowledge/repos/jiuwenswarm/components/login-auth/jiuwenswarm-common-auth.md b/knowledge/repos/jiuwenswarm/components/login-auth/jiuwenswarm-common-auth.md new file mode 100644 index 00000000..09b65cc7 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/login-auth/jiuwenswarm-common-auth.md @@ -0,0 +1,32 @@ +--- +title: "华为账号登录与免费模型凭据（common/auth）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 华为账号登录与免费模型凭据（common/auth） + +负责华为账号 Account Kit 登录（OAuth2 授权码 + PKCE）、登录会话的加密落盘与 token 续期，并在登录后通过 APIG 通道发现免费模型、查询积分。Gateway 转发请求时附上用户的 id_token。AgentServer 的模型配置里只存 `jiuwen-login:` 占位句柄，请求发出前才换成真 token。 + +**从这里读起** + +- `jiuwenswarm/common/auth/service.py` — AuthService 是各 channel 共用的唯一登录入口，负责发起授权、回调、认领、登出、状态查询和续期；模型层通过 live_session / resolve_id_token 取凭据 +- `jiuwenswarm/common/auth/passthrough.py` — Gateway 侧：normalize_model_auth 先删掉客户端传来的凭据键，再由服务端决定是否挂上该用户的 id_token +- `jiuwenswarm/common/auth/login_credentials.py` — AgentServer 侧：按句柄登记 token，并用 SDK httpx 钩子（inject_login_credential / apply_login_credential_patch）在请求发出前换成真 token +- `jiuwenswarm/common/auth/remote_config.py` — 官网下发的远端配置（get_config / warm_up_in_background），决定登录和免费模型功能是否开启 + +**关键文件** + +- `jiuwenswarm/common/auth/account_kit.py` — OAuth 流程本身：PKCE 生成、待完成登录表 PendingLogins、换码、认领、refresh_token 续期 +- `jiuwenswarm/common/auth/session_store.py` — 登录会话存在内存里，并用 AES-256-GCM 加密落盘（密钥在 ~/.jiuwenswarm/auth/.install_key）；Gateway 与 AgentServer 靠它共享登录态 +- `jiuwenswarm/common/auth/model_catalog.py` — 用 id_token 发现账号可用的模型并缓存，转成 models.defaults 条目；这些模型永远不写进 config.yaml（is_login_model 负责拦截） +- `jiuwenswarm/common/auth/apig.py` — APIG 客户端：模型列表、积分查询（ModelQuota）、推理接入点，积分用完时抛 QuotaExhausted +- `jiuwenswarm/common/auth/session_owners.py` — 记录对话会话由哪个账号选了免费模型，让飞书等 IM 通道中没有登录会话的请求也能找回凭据 +- `jiuwenswarm/common/auth/net.py` — 登录链路的出网请求封装，以及 SSL 校验开关 + +**改动路由** + +- `jiuwenswarm/common/auth/` diff --git a/knowledge/repos/jiuwenswarm/components/observability/_index.md b/knowledge/repos/jiuwenswarm/components/observability/_index.md new file mode 100644 index 00000000..5a67504a --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/observability/_index.md @@ -0,0 +1,21 @@ +--- +title: "可观测性与轨迹存储" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# 可观测性与轨迹存储 + +- [可观测性：Agent 轨迹采集、存储与保留（jiuwenswarm/observability）](jiuwenswarm-observability.md) + +## 代码快速入口（Direct） + + +触发词：observability、trajectory、轨迹、OTLP、trace、span、sink、SQLite、retention、保留、turn、session delete。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| observability、trajectory、轨迹、OTLP、trace、span、sink、SQLite、retention、保留、turn、sessi… | 入口 | `jiuwenswarm/observability/` | diff --git a/knowledge/repos/jiuwenswarm/components/observability/jiuwenswarm-observability.md b/knowledge/repos/jiuwenswarm/components/observability/jiuwenswarm-observability.md new file mode 100644 index 00000000..119a83f9 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/observability/jiuwenswarm-observability.md @@ -0,0 +1,32 @@ +--- +title: "可观测性：Agent 轨迹采集、存储与保留（jiuwenswarm/observability）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# 可观测性：Agent 轨迹采集、存储与保留（jiuwenswarm/observability） + +在 AgentServer 中接收 Core 产出的 OTLP span 记录，按会话写入本地 SQLite 轨迹库，并为轨迹查看器提供读取查询、按页保留清理和会话删除。它也负责维护会话的轮次（turn）身份，并把已提交的轨迹修订提示跨进程推送到 Gateway。 + +**从哪里读起** + +- `jiuwenswarm/observability/runtime.py` — AgentServer 的轨迹运行时生命周期：start/sync/shutdown_trajectory_runtime 向 Core 注册或注销记录消费者；get_trajectory_runtime_sink 返回当前的 sink +- `jiuwenswarm/observability/session_delete.py` — 产品 Session 删除时的轨迹生命周期：begin/abort/commit_trajectory_session_delete，以及 trajectory_session_accepts_records +- `jiuwenswarm/observability/turn.py` — SessionTurnTracker/TurnIdentity：定义一个 ReAct 循环何时开启新轮次，以及 HITL 恢复、steer、supplement、cancel 各自的处理方式 +- `jiuwenswarm/observability/gateway_hints.py` — TrajectoryGatewayHintBridge：把已提交的轨迹更新（CommittedTraceUpdate）作为修订提示，跨进程排队推送给 Gateway + +**关键文件** + +- `jiuwenswarm/observability/sink.py` — 有界的记录消费者和 SQLite 写线程：TrajectoryRecordSink 负责批量写入与重试；TrajectorySessionSinkRouter 按会话路由写入，并处理删除和过期库清扫 +- `jiuwenswarm/observability/store.py` — TrajectoryStore 负责无损写入、按保留规则删除过期数据和写检查点；AsyncTrajectoryReader 提供查看器使用的读取查询 +- `jiuwenswarm/observability/retention.py` — 按页的保留规划：只删除最旧的连续整页轮次，并留下检查点，保证剩余部分的渲染结果不变 +- `jiuwenswarm/observability/otlp_payload.py` — 严格的 OTLP JSON 解析，要求数值有限并限制嵌套深度，决定记录是否可以交给查看器投影；读取和保留两处共用这一规则 +- `jiuwenswarm/observability/models.py` — 持久化边界上的类型化记录，包括 TraceRecordData、StreamFrameData、CommittedTraceUpdate、TraceSinkStats，以及它们从 Core 记录转换而来的方法 +- `jiuwenswarm/observability/config.py` — TrajectoryStoreSettings：读取轨迹存储配置，并解析每个会话的数据库路径 + +**改动路由** + +- `jiuwenswarm/observability/` diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md new file mode 100644 index 00000000..5b2bcfdf --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md @@ -0,0 +1,23 @@ +--- +title: "Symphony 编排与能力图谱" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# Symphony 编排与能力图谱 + +- [Symphony 编排集成（jiuwenswarm/symphony）](jiuwenswarm-symphony.md) +- [Symphony 动态图谱演化（evolution）](jiuwenswarm-symphony-evolution.md) +- [Symphony 共享工具（symphony/shared）](jiuwenswarm-symphony-shared.md) + +## 代码快速入口（Direct） + + +触发词：symphony、graph build、图谱构建、fingerprint、能力指纹、evolution、经验演进、experience candidate、recipe、skill taxonomy、skill retrieval、orchestration。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| symphony、graph build、图谱构建、fingerprint、能力指纹、evolution、经验演进、experience candidate、… | 入口 | `jiuwenswarm/symphony/adapter.py`、`jiuwenswarm/symphony/build.py`、`jiuwenswarm/symphony/config.py` | diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-evolution.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-evolution.md new file mode 100644 index 00000000..29257928 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-evolution.md @@ -0,0 +1,27 @@ +--- +title: "Symphony 动态图谱演化（evolution）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# Symphony 动态图谱演化（evolution） + +本模块把 Symphony 运行时事件（如计划结果、选中的技能、边的成败和失败归因）追加写入图谱目录下的 evolution 存储。它再把这些事件聚合成动态图谱 overlay，按边、节点、路径统计结果并计算运行时权重，供加载和查询状态使用。 + +**从这里读起** + +- `jiuwenswarm/symphony/evolution/service.py` — 对外的服务函数：record_plan_outcome 记录计划结果，load_dynamic_overlay / rebuild_dynamic_overlay 加载或重建 overlay，evolution_status 返回演化状态， + +**关键文件** + +- `jiuwenswarm/symphony/evolution/aggregate.py` — build_overlay_from_events 把事件聚合成 overlay，逐条累计边、节点、路径的结果并计算 _runtime_weight +- `jiuwenswarm/symphony/evolution/store.py` — 只追加的文件存储：events、overlay、skill packs 各自的路径和读写函数，以及 evolution_store_transaction 事务 +- `jiuwenswarm/symphony/evolution/models.py` — 共享的 key 和归一化函数：edge_key、skill_id，以及边、结果（outcome）、失败归因的归一化 +- `jiuwenswarm/symphony/evolution/service.py` — 判断 overlay 是否需要重建（按图谱版本和事件时间），给失败的边加标注，并提供默认失败归因 + +**路由** + +- `jiuwenswarm/symphony/evolution/` diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-shared.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-shared.md new file mode 100644 index 00000000..ffcd890e --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony-shared.md @@ -0,0 +1,30 @@ +--- +title: "Symphony 共享工具（symphony/shared）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# Symphony 共享工具（symphony/shared） + +为 Symphony 提供共享的底层工具：S3 对象存储的读写与目录同步、精简的 LLM 请求载荷、分阶段计时、标签归一化，以及 rich 终端组件的兼容替身。 + +**从这里开始读** + +- `jiuwenswarm/symphony/shared/storage.py` — S3 入口：is_s3_uri、parse_s3_uri、read_s3_text、upload_local_dir_to_s3、materialize_s3_dir、create_s3_client +- `jiuwenswarm/symphony/shared/llm_payload.py` — compact_json 与 prune_empty：用来精简发给 LLM 的请求载荷 +- `jiuwenswarm/symphony/shared/tags.py` — normalize_tags：把各种形式的标签输入整理成去重后的字符串元组 + +**关键文件** + +- `jiuwenswarm/symphony/shared/storage.py` — S3Location 与 S3 URI 的解析和拼接、读取、下载、上传；从环境变量读取载荷签名和寻址风格；判断上传错误能否重试、对象是否缺失 +- `jiuwenswarm/symphony/shared/llm_payload.py` — LLM 请求载荷的共享辅助：去掉空值，再序列化成紧凑 JSON +- `jiuwenswarm/symphony/shared/profiling.py` — StageTimer：按 scope 记录各 phase 的耗时，finish 时输出到 logger +- `jiuwenswarm/symphony/shared/tags.py` — 标签解析：拆分文本、递归展平嵌套值，并用 _seen 防止循环引用 +- `jiuwenswarm/symphony/shared/rich_compat.py` — rich 的兼容替身，提供 Console、Panel、Progress、各种 Column 和 RichTree 的空实现，接口与 rich 一致 + +**路由** + +- `jiuwenswarm/symphony/shared/` diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony.md new file mode 100644 index 00000000..adae7f92 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/jiuwenswarm-symphony.md @@ -0,0 +1,40 @@ +--- +title: "Symphony 编排集成（jiuwenswarm/symphony）" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# Symphony 编排集成（jiuwenswarm/symphony） + +把公开的 openjiuwen.symphony 编排 API 接入 JiuwenSwarm。模块负责进程内的 Symphony 服务、能力图谱的构建与版本化存储、能力指纹、执行经验的演进和候选安装，以及基于 Skill 分类体系（taxonomy）的索引构建。 + +**入口** + +- `jiuwenswarm/symphony/service.py` — SwarmSymphonyService 和 get_swarm_symphony_service：进程内唯一的服务对象。负责图谱状态、刷新、取消构建，也负责 plan、经验候选的列出、请求和安装 +- `jiuwenswarm/symphony/build.py` — SymphonyGraphBuilder、build_graph 和 graph_status：图谱构建流程，包括扫描、指纹、checkpoint 和产物发布 +- `jiuwenswarm/symphony/config.py` — load_symphony_config 和 SymphonyConfig：Symphony 运行时配置的入口，含路径、指纹、构建、演进和编排模式 +- `jiuwenswarm/symphony/skill_retrieval/runtime.py` — SkillTaxonomyRuntime：Skill 分类索引的 build/status/cancel 接口，是公开 taxonomy SDK 的一层薄适配 + +**关键文件** + +- `jiuwenswarm/symphony/adapter.py` — 把 Swarm 配置转换成公开 Symphony API 需要的能力提供者、指纹 LLM 适配器和 orchestration/graph 配置 +- `jiuwenswarm/symphony/graph_state.py` — GraphState 和 GraphStateBuilder：持久化能力哈希，用来做增量构建 +- `jiuwenswarm/symphony/graph_storage.py` — 图谱产物的版本化目录、manifest 指针、发布逻辑，以及查找未完成的构建 +- `jiuwenswarm/symphony/experience.py` — 执行轨迹的截断兼容处理、图谱演进 rail、submit_evolution，以及已发布能力的快照 +- `jiuwenswarm/symphony/llm.py` — LLMConfig、按请求绑定模型、token 用量统计，以及 JiuwenSwarmChatClient 的 JSON 补全 +- `jiuwenswarm/symphony/config.py` — 各子配置的解析和取值约束，以及 symphony/evolution 开关的判定 + +**改动路由** + +- `jiuwenswarm/symphony/adapter.py` +- `jiuwenswarm/symphony/build.py` +- `jiuwenswarm/symphony/config.py` +- `jiuwenswarm/symphony/experience.py` +- `jiuwenswarm/symphony/graph_state.py` +- `jiuwenswarm/symphony/graph_storage.py` +- `jiuwenswarm/symphony/llm.py` +- `jiuwenswarm/symphony/service.py` +- `jiuwenswarm/symphony/skill_retrieval/`