From f6aee1f1575908907d5b736ff9bbac623eaab9f8 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Wed, 30 Sep 2026 20:25:17 +0000 Subject: [PATCH] kb init(jiuwenswarm): skeleton --- knowledge/repos/_index.md | 1 + knowledge/repos/jiuwenswarm/_index.md | 30 +++ knowledge/repos/jiuwenswarm/_routes.yaml | 203 ++++++++++++++++++++ knowledge/repos/jiuwenswarm/architecture.md | 57 ++++++ knowledge/repos/jiuwenswarm/rules.md | 84 ++++++++ 5 files changed, 375 insertions(+) create mode 100644 knowledge/repos/jiuwenswarm/_index.md create mode 100644 knowledge/repos/jiuwenswarm/_routes.yaml create mode 100644 knowledge/repos/jiuwenswarm/architecture.md create mode 100644 knowledge/repos/jiuwenswarm/rules.md diff --git a/knowledge/repos/_index.md b/knowledge/repos/_index.md index e99198ee..6dc029ac 100644 --- a/knowledge/repos/_index.md +++ b/knowledge/repos/_index.md @@ -27,3 +27,4 @@ sources: [] | afd-plugin | `vllm-project/afd-plugin` | [afd-plugin](afd-plugin/_index.md) | | Jianghan roleplay data pipeline | 私有项目 | [jianghan-roleplay-data-pipeline](jianghan-roleplay-data-pipeline/_index.md) | | vLLM-GR | `JiusiServe/vllm-gr` | [vllm-gr](vllm-gr/_index.md) | +| jiuwenswarm | `openJiuwen-ai/jiuwenswarm` | [jiuwenswarm](jiuwenswarm/_index.md) | diff --git a/knowledge/repos/jiuwenswarm/_index.md b/knowledge/repos/jiuwenswarm/_index.md new file mode 100644 index 00000000..a29c6060 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/_index.md @@ -0,0 +1,30 @@ +--- +title: "JiuwenSwarm 仓库经验入口" +created: 2026-09-30 +updated: 2026-09-30 +type: index +tags: [jiuwenswarm] +sources: [] +--- + +# JiuwenSwarm 仓库经验入口 + +本页是 `openJiuwen-ai/jiuwenswarm`（JiuwenSwarm，原名 JiuwenClaw，v0.2.0 起改为现名）的审查入口。它把 PR 标题或改动路径对应到负责的知识页，再指向仓库自己的文档。仓库文档和源码是事实来源，本知识库只负责指路。 + +**什么时候查这里** + +- 审查 jiuwenswarm 的 PR 时，用来判断改动属于哪一块：Gateway 与频道、E2A/A2A/ACP 协议、A2UI、AgentServer 运行时、Agent Team/Harness/Skills、Auto Harness、Web 前端、默认配置、测试与 CI、打包部署，或文档。 +- 想知道某块代码该先读哪篇文档时查这里。中文文档在 `docs/zh/`，英文文档在 `docs/en/`，总导航是 `docs/README.md` 和 `docs/README_EN.md`。 + +**不放什么** + +- 不复述仓库文档。协议字段、命令用法、配置项、环境变量都以 `docs/` 和源码为准；文档和源码冲突时以源码为准（`docs/zh/A2A.md`、`docs/zh/E2A-protocol.md` 开头都这样声明）。 +- 不放换到其他仓库也成立的通用审查方法，这些放在 `general/`。 +- 不放产品使用教程和安装步骤。需要时直接读 `README_CN.md`、`docs/zh/安装指南.md`、`docs/zh/Quickstart.md`、`docs/zh/FAQ.md`。 + +**本仓库页面** + +- [JiuwenSwarm 仓库经验入口 — architecture](architecture.md) +- [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) diff --git a/knowledge/repos/jiuwenswarm/_routes.yaml b/knowledge/repos/jiuwenswarm/_routes.yaml new file mode 100644 index 00000000..f72a567d --- /dev/null +++ b/knowledge/repos/jiuwenswarm/_routes.yaml @@ -0,0 +1,203 @@ +# Direct-mode owner routing for jiuwenswarm, written by kb init (pin f0a69728c96b). +schema_version: 1 +owners: +- owner: gateway-channels + path: repos/jiuwenswarm/architecture.md + signals: + - gateway + - 网关 + - channel + - 频道 + - channel_manager + - message_handler + - feishu + - 飞书 + - wechat + - 微信 + - xiaoyi + - 小艺 + - /join + - HITT + scope_prefixes: + - jiuwenswarm/gateway/ +- owner: protocols + path: repos/jiuwenswarm/architecture.md + signals: + - E2A + - E2AEnvelope + - E2AResponse + - A2A + - agent card + - ACP + - JSON-RPC + - session/prompt + - protocol + - 协议 + scope_prefixes: + - jiuwenswarm/common/e2a/ + - jiuwenswarm/gateway/channel_manager/protocol/ + - scripts/run_gateway_acp.sh + - scripts/run_gateway_acp.cmd +- owner: a2ui + path: repos/jiuwenswarm/architecture.md + signals: + - A2UI + - a2ui + - 生成式界面 + - client_event + - surface + - renderer + - finalizer + scope_prefixes: + - jiuwenswarm/server/runtime/a2ui/ + - jiuwenswarm/channels/web/frontend/src/features/a2ui/ + - tests/unit_tests/a2ui/ + - tests/system_tests/test_a2ui_system_flow.py +- owner: agent-server-runtime + path: repos/jiuwenswarm/architecture.md + signals: + - AgentServer + - agentserver + - agent server + - runtime + - 运行时 + - agent_adapter + - mode + - work_mode + - 模式 + scope_prefixes: + - jiuwenswarm/server/ +- owner: agents-team + path: repos/jiuwenswarm/architecture.md + signals: + - team + - swarm + - 集群模式 + - leader + - teammate + - swarmflow + - rails + - harness + - skill + - 技能 + - memory + - 记忆 + - prompt + scope_prefixes: + - jiuwenswarm/agents/ +- owner: auto-harness + path: repos/jiuwenswarm/architecture.md + signals: + - auto-harness + - auto harness + - AutoHarness + - evolve + - evolution + - 演进 + - 自演进 + - harness package + - schedule + - issue fix + scope_prefixes: + - docs/zh/AutoHarness.md +- owner: web-frontend + path: repos/jiuwenswarm/architecture.md + signals: + - web + - frontend + - 前端 + - UI + - websocket + - react + - npm + - 页面 + scope_prefixes: + - jiuwenswarm/channels/web/ +- owner: config-resources + path: repos/jiuwenswarm/architecture.md + signals: + - config + - 配置 + - config.yaml + - .env + - 环境变量 + - init + - jiuwenswarm-init + - model provider + - 模型配置 + scope_prefixes: + - jiuwenswarm/resources/ +- owner: subpackages + path: repos/jiuwenswarm/architecture.md + signals: + - jiuwenbox + - sdk + - sdks + - packages + - TUI + - jiuwenswarm-tui + scope_prefixes: + - jiuwenbox/ + - packages/ + - sdks/ +- owner: tests-ci + path: repos/jiuwenswarm/rules.md + signals: + - test + - tests + - 测试 + - pytest + - UT + - 单元测试 + - CI + - coverage + - 覆盖率 + scope_prefixes: + - tests/ + - pytest.ini + - run_tests.sh + - TESTING.md + - .gitcode/ +- owner: packaging-deploy + path: repos/jiuwenswarm/rules.md + signals: + - dependency + - deps + - 依赖 + - bump + - release + - 发布 + - version + - wheel + - pip + - uv + - docker + - deploy + - 部署 + scope_prefixes: + - pyproject.toml + - uv.lock + - MANIFEST.in + - Makefile + - Dockerfile.claw + - .dockerignore + - docker/ + - deploy/ + - third_party/ + - OPEN_SOURCE_SOFTWARE_NOTICE.md + - LICENSE +- owner: docs + path: repos/jiuwenswarm/rules.md + signals: + - docs + - doc + - 文档 + - README + - FAQ + - 指南 + - guide + scope_prefixes: + - docs/ + - README.md + - README_CN.md + - .doc_project_maintainer/ diff --git a/knowledge/repos/jiuwenswarm/architecture.md b/knowledge/repos/jiuwenswarm/architecture.md new file mode 100644 index 00000000..407e5546 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/architecture.md @@ -0,0 +1,57 @@ +--- +title: "JiuwenSwarm 仓库经验入口 — architecture" +created: 2026-09-30 +updated: 2026-09-30 +type: architecture +tags: [jiuwenswarm] +sources: [] +--- + +# JiuwenSwarm 仓库经验入口 — architecture + +**怎么用这页** + +本页是一张地图，只列出每块代码在哪里、改它之前该先读哪篇仓库文档。如果审查时发现文档与源码不一致，应要求在同一个 PR 里把文档改对。总导航见 `docs/README.md`（中文）和 `docs/README_EN.md`（英文）。 + +**进程与数据流** + +入口（Web / TUI / 飞书 / 微信 / 小艺 / ACP / A2A） + → Gateway：ChannelManager 注册频道 → MessageHandler + → E2A（请求 E2AEnvelope / 响应 E2AResponse） + → AgentServer 运行时（agent_adapter、a2ui） + → Agent harness（prompts / tools / rails / skills）与 Team / SwarmFlow + +- Gateway 的入口是 `jiuwenswarm/gateway/app_gateway.py`，启动命令为 `python -m jiuwenswarm.gateway.app_gateway`。它会读取 `~/.jiuwenswarm/config/.env` 并注册各个频道。主进程的启动命令是 `python -m jiuwenswarm.app`。 +- Gateway 和 AgentServer 之间只通过 `jiuwenswarm/common/e2a/` 里定义的信封通信。外部协议（A2A、ACP）先在 Gateway 边界转换成 E2A。 +- TUI 是单独发布的 pip 包 `jiuwenswarm-tui`。已提供的文档没有介绍 `jiuwenbox/`、`packages/`、`sdks/` 这三个目录，审查它们时先看目录里的 README 和代码。 + +**各区域的代码与文档** + +| Gateway 与频道 | `jiuwenswarm/gateway/`（`channel_manager/`、`message_handler/`、`app_gateway.py`） | `docs/zh/A2A.md` §0–§2（模块表，以及 Web、ACP、A2A 三种频道的对照） | 改频道注册、消息派发、端口和环境变量绑定时 | +| E2A 内部协议 | `jiuwenswarm/common/e2a/`（`models.py`、`adapters.py`、`constants.py`） | `docs/zh/E2A-protocol.md`，英文版 `docs/en/E2A-protocol.md` | 改信封或响应字段、`method` 的两种含义、`response_kind`/`status`、ACP/A2A 投影时 | +| A2A 入站 | `jiuwenswarm/gateway/channel_manager/protocol/a2a/` | `docs/zh/A2A.md` §3–§9 | 改 AgentCard、A2A parts 与 `Message` 的互转、reasoning 输出、`A2A_SERVER_*` 变量、可选依赖 `jiuwenswarm[a2a]` 时 | +| ACP 接入 | `scripts/run_gateway_acp.sh`、`scripts/run_gateway_acp.cmd`、`jiuwenswarm-acp` 命令 | `docs/zh/ACP插件使用.md` | 改 ACP 启动脚本、命令入口或 VS Code 接入步骤时 | +| A2UI（只支持 Web） | 后端 `jiuwenswarm/server/runtime/a2ui/`；前端 `jiuwenswarm/channels/web/frontend/src/features/a2ui/` | `docs/zh/A2UI.md`（模块关系表、边界原则）、`docs/zh/A2UI-IM-channel-analysis.md`、`docs/zh/A2UI-web-only-pr-record.md` | 任何 A2UI 改动，尤其是想让非 Web 频道也支持 A2UI 的 PR | +| AgentServer 运行时 | `jiuwenswarm/server/`（如 `runtime/agent_adapter`） | `docs/zh/A2UI.md` 模块表中 agent_adapter 那一行、`docs/zh/模式系统.md` | 改输入输出适配、`mode` / `work_mode` 的处理时 | +| Agent harness、Team、Skills、记忆 | `jiuwenswarm/agents/`（如 `agents/harness/common/rails`） | `docs/zh/AgentTeam.md`（§2.4 技能可见性、§2.5 团队记忆、§2.6 SwarmFlow 启停、Q6 本地与分布式模式下的会话规则）、`docs/zh/AgentTeam人类成员联机协作.md`、`docs/zh/SwarmSkills.md`、`docs/zh/记忆.md` | 改 Leader/Teammate 协作、`skills-visibility.json`、团队记忆、SwarmFlow 生命周期，或人类成员的 `/join`、`$成员名` 语法时 | +| Auto Harness | 已提供的文档没有给出代码目录，按 PR 的实际路径定位 | `docs/zh/AutoHarness.md` | 改 `/auto-harness` 命令、Meta/Expert pipeline、Harness Package 热加载、GitCode issue 自动处理时 | +| Web 前端 | `jiuwenswarm/channels/web/frontend/` | `docs/zh/A2UI.md`（其中对 `useWebSocket.ts` 的约束）、`docs/zh/Quickstart.md` | 改前端组件、WebSocket hook、构建脚本时 | +| 默认配置与资源 | `jiuwenswarm/resources/`（`config.yaml`、`.env.template`） | `docs/zh/配置信息.md`、`docs/zh/A2UI.md` 的配置一节、`docs/zh/FAQ.md` 的模型配置部分 | 改默认配置、环境变量名、`jiuwenswarm-init` 初始化流程时 | +| 测试与 CI | `tests/`、`pytest.ini`、`run_tests.sh`、`.gitcode/workflows/` | `TESTING.md`、`tests/README.md` | 新增或修改测试、CI 失败时 | +| 打包与部署 | `pyproject.toml`、`uv.lock`、`MANIFEST.in`、`Makefile`、`Dockerfile.claw`、`docker/`、`deploy/` | `docs/zh/安装指南.md`、`docs/zh/FAQ.md` | 改依赖、可选依赖（如 `a2a`）、镜像或发布流程时 | + +**文档里已知的过期内容** + +- `TESTING.md` 写于 JiuwenClaw 时期，和现状有出入：它同时写了 `tests/unit/` 和 `tests/unit_tests/` 两种路径；CI 部分写的是 `.github/workflows/`，而仓库实际用的是 `.gitcode/`。遇到分歧时，以 `pytest.ini`、`.gitcode/workflows/` 和 `tests/` 的实际结构为准。 +- 由于改过名，仓库里可能还留着 `claw` 字样，例如 `Dockerfile.claw` 和旧的 `JIUWENCLAW_*` 环境变量。`docs/zh/A2UI.md` 已声明 A2UI 不再支持旧前缀，只认 `JIUWENSWARM_A2UI_*`。 +- `docs/zh/A2A.md` §7 说明：出站 A2A（Agent 通过 MCP Hub 调外部）目前不在仓库里。遇到相关 PR 时，以实际接线的代码为准。 +- `docs/zh/FAQ.md` 要求和 `docs/en/FAQ.md` 同步更新。改动只涉及其中一种语言的文档时，要检查另一种语言的版本有没有一起更新。 + +## 代码快速入口（Direct） + + +触发词：gateway、网关、channel、频道、channel_manager、message_handler、feishu、飞书、wechat、微信、xiaoyi、小艺。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| gateway、网关、channel、频道、channel_manager、message_handler、feishu、飞书、wechat、微信、xiaoy… | 入口 | `docs/README.md`、`docs/README_EN.md`、`jiuwenswarm/gateway/app_gateway.py` | diff --git a/knowledge/repos/jiuwenswarm/rules.md b/knowledge/repos/jiuwenswarm/rules.md new file mode 100644 index 00000000..a228ccf9 --- /dev/null +++ b/knowledge/repos/jiuwenswarm/rules.md @@ -0,0 +1,84 @@ +--- +title: "JiuwenSwarm 仓库审查规则" +created: 2026-09-30 +updated: 2026-09-30 +type: rule +tags: [jiuwenswarm] +sources: [] +--- + +# JiuwenSwarm 仓库审查规则 + +## 代码快速入口（Direct） + + +触发词：test、tests、测试、pytest、UT、单元测试、CI、coverage、覆盖率。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。 + +| PR 描述在做什么 | 精确规则 | 第一批 live 源码 | +|---|---|---| +| 代码必须能在 Python 3.11 上运行（支持范围 `>=3.11, <3.14`） | JIUWENSW-I2 | `tests/`、`pytest.ini`、`run_tests.sh` | +| 改依赖必须在同一 PR 里同步 `uv.lock`，可选通道的依赖放进 extras | JIUWENSW-I3 | `tests/`、`pytest.ini`、`run_tests.sh` | +| 改名为 JiuwenSwarm 后不要再引入 `JIUWENCLAW_*`，也不要乱改其他通道的变量名 | JIUWENSW-I6 | `tests/`、`pytest.ini`、`run_tests.sh` | +| 分清几种 `metadata`，不要写错层 | JIUWENSW-I8 | `tests/`、`pytest.ini`、`run_tests.sh` | +| 技能实体只有一份：放在全局技能库，可见性只靠 JSON 声明 | JIUWENSW-I10 | `skills/` | +| Team 会话切换和 SwarmFlow 启停要区分本地/分布式模式和触发来源 | JIUWENSW-I11 | `tests/`、`pytest.ini`、`run_tests.sh` | +| 改协议或接口的实现时同步更新文档，中英文一起改 | JIUWENSW-I12 | `docs/zh/A2A.md`、`docs/zh/E2A-protocol.md`、`jiuwenswarm/common/e2a/models.py` | + +## JIUWENSW-I2 — 代码必须能在 Python 3.11 上运行（支持范围 `>=3.11, <3.14`） + +- 最低版本 3.11 分散写在 README 徽章、ACP 文档和 FAQ 里；CI 矩阵只覆盖 3.11/3.12/3.13。 +- 拒绝只有 3.12 及以上才有的语法或 API，例如 PEP 695 的 `type X = ...` 和 `def f[T]()` 泛型语法、PEP 701 的 f-string 内复用同种引号、`itertools.batched`。 +- 如果调整了 `pyproject.toml` 里的 Python 版本约束，CI 矩阵和 FAQ（中英文）要一起更新。 + + + +## JIUWENSW-I3 — 改依赖必须在同一 PR 里同步 `uv.lock`，可选通道的依赖放进 extras + +- 仓库用 `uv` 管理依赖（`uv sync`、`uv run pytest`、`uv sync --extra a2a`）。`TESTING.md` 里的 `pip install -e ".[test]"` 只是另一种安装入口，不能成为漏更新锁文件的理由。 +- 在 `pyproject.toml` 里增、删、改任何依赖，都要在同一 PR 里重新生成 `uv.lock`。 +- `a2ui-agent-sdk` 保持 `==0.2.1` 这种精确锁定。升级时必须在同一 PR 里更新锁文件、跑协议校验测试，并完成 Web 前端的 `npm run build`。 +- 只有某个可选通道才用到的依赖（例如 A2A 的 `a2a-sdk`）应放进对应的 extra（`jiuwenswarm[a2a]`），不要加进主依赖。 + + + +## JIUWENSW-I6 — 改名为 JiuwenSwarm 后不要再引入 `JIUWENCLAW_*`，也不要乱改其他通道的变量名 + +- v0.2.0 起 JiuwenClaw 升级为 JiuwenSwarm。A2UI 的运行时覆盖项只认 `JIUWENSWARM_A2UI_*`，`JIUWENCLAW_A2UI_*` 从 2026-06-04 起不再兼容。 +- 新代码不能把 `JIUWENCLAW_` 前缀当后备来读，也不要新增这个前缀的变量。用户数据目录统一是 `~/.jiuwenswarm/`，例如 `~/.jiuwenswarm/config/.env`。 +- 各通道已有自己的变量前缀（`A2A_SERVER_*`、`ACP_GATEWAY_*`、`WEB_HOST`/`WEB_PORT`/`WEB_PATH`），不要为了“统一”去改名，那样会破坏现有部署。 + + + +## JIUWENSW-I8 — 分清几种 `metadata`，不要写错层 + +- 请求信封顶层的 `metadata`：旧 `AgentRequest` 留下的字段，只在 `from_dict` 时迁入 `channel_context`，新代码不能写。 +- `envelope_from_a2a_send_message` 的 `metadata` 参数：写入 `a2a_metadata`，只用于和 A2A 互通；`acp_meta` 同理只用于 ACP。 +- `E2AResponse.metadata`：这是合法字段，存放通道或业务的自定义键值（对应旧的 `AgentResponse.metadata`），协议转换失败时也可临时写入兜底内容。旧格式整包 JSON 使用 `E2A_WIRE_LEGACY_AGENT_RESPONSE_KEY` / `E2A_WIRE_LEGACY_AGENT_CHUNK_KEY`，业务自定义键建议加通道前缀，避免冲突。 +- A2A 通道里的元数据写到内部 `Message.metadata`，这不是 E2A 字段。 +- 评审时核对三点：字段写在了哪一层的 `metadata`；有没有把业务键写进 `a2a_metadata`/`acp_meta`；有没有在请求侧重新写顶层 `metadata`。 + + + +## JIUWENSW-I10 — 技能实体只有一份：放在全局技能库，可见性只靠 JSON 声明 + +- 技能安装只写入全局库 `~/.jiuwenswarm/agent/workspace/skills/`。`.agent_teams//team-workspace/` 和 `workspaces/_workspace/` 下都不能出现 `skills/` 目录、软链或副本。 +- 可见性只能通过团队和成员各自的 `skills-visibility.json`，以及 `skills.visibility.get`/`set`/`update` 修改。合并规则：deny 优先于 allow；团队的 deny 成员无法撤销；`allow` 为空表示继承整个技能库。 +- 配置里各角色的 `skills` 只在第一次生成声明文件时作为初始 `allow`。`skills-visibility.json` 已存在时，不能被配置覆盖。 +- FAQ 的升级备份表把自定义技能路径写成 `~/.jiuwenswarm/agent/skills`，和 AgentTeam 文档的 `~/.jiuwenswarm/agent/workspace/skills/` 不一致。涉及技能路径的改动以代码实际路径为准，并顺手修正写错的那份文档。 + + + +## JIUWENSW-I11 — Team 会话切换和 SwarmFlow 启停要区分本地/分布式模式和触发来源 + + - TUI `/exit` 或双击 Ctrl+C：兜底暂停，保留进度。 +- 暂停后不能自动恢复，是否恢复由 Leader 决定。重启后没跑完的 run 显示为“暂停待恢复”，按钮置灰。 + + + +## JIUWENSW-I12 — 改协议或接口的实现时同步更新文档，中英文一起改 + +- `docs/zh/A2A.md` 和 `docs/zh/E2A-protocol.md` 都声明：文档与代码冲突时以源码为准，并要回头修正文档。所以修改 `jiuwenswarm/common/e2a/models.py`（`E2AEnvelope`/`E2AResponse` 的字段）、`constants.py` 里的元组、A2A 环境变量默认值或字段映射时，PR 要同步更新对应文档。 +- 中英文文档成对维护：`docs/zh/<页面>.md` 对应 `docs/en/<页面>.md`（FAQ 和 E2A 明确要求同步，A2UI 的改动也是中英文一起改），`README_CN.md` 对应 `README.md`。只改了一边的，要求补齐另一边。 +- `docs/zh/` 下的新页面沿用末尾的“返回导航”段落，链接 `../README.md` 和 `../../README_CN.md`，并在 `docs/README.md` 的导航里登记。 + +