@researai/deepscientist 1.5.9 → 1.5.11

package/docs/en/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -1,216 +1,99 @@
-# 04 Lingzhu Connector Guide: Configure Lingzhu for DeepScientist
+# 04 Lingzhu Connector Guide: Bind Rokid Glasses to DeepScientist
 
-This guide explains how to configure the Lingzhu companion endpoint from `Settings > Connectors > Lingzhu`.
+Lingzhu now uses a minimal one-step binding flow.
 
-Scope:
+DeepScientist serves the Lingzhu-compatible routes directly on its own daemon / web port:
 
-- configuration only
-- OpenClaw-compatible Lingzhu bridge values
-- local probe and SSE smoke test
-- what to paste into the Lingzhu platform
+- `GET /metis/agent/api/health`
+- `POST /metis/agent/api/sse`
 
-This guide does not cover cloud deployment architecture. You only need one working OpenClaw gateway and one public IP or public domain that the glasses can reach.
+For a real device binding, the address registered on Rokid must be the public DeepScientist address that external devices can reach. It cannot be `127.0.0.1`, `localhost`, or a private-network address.
 
-Reference sources:
+References:
 
-- Rokid forum setup page: https://forum.rokid.com/post/detail/2831
-- packaged bridge root: `assets/connectors/lingzhu/openclaw-bridge`
-- packaged OpenClaw config template: `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+- Rokid developer forum: https://forum.rokid.com/post/detail/2831
+- Rokid agent platform: https://agent-develop.rokid.com/space
 
-## 1. What DeepScientist now provides
+## 1. Prerequisites
 
-The Lingzhu settings card now generates and validates:
+Make sure:
 
-- local health URL
-- local SSE URL
-- public SSE URL
-- `auth_ak`
-- OpenClaw config snippet
-- local probe `curl`
+- DeepScientist is already running
+- the DeepScientist page you opened is the final public address that external devices should use
+- if the current page is local-only or private-network-only, Lingzhu should not be saved yet
 
-The packaged bridge is configured to:
+## 2. What the UI keeps now
 
-- emit one immediate visible receipt acknowledgement before the model starts
-- keep comment heartbeats alive
-- emit lightweight visible progress heartbeats during long silent upstream phases
+`Settings > Connectors > Lingzhu` now keeps only the necessary pieces:
 
-DeepScientist treats Lingzhu as a companion endpoint, not as a full bidirectional chat connector like QQ.
+- one `Add Lingzhu (Rokid Glasses)` entry point
+- the Rokid platform screenshot
+- the auto-generated copyable fields
+- concise binding instructions
+- one save action
 
-## 2. Before you start
+You no longer need to manually edit host, port, agent, OpenClaw snippets, or extra probe steps in the main flow.
 
-Make sure these are already true:
+## 3. What is auto-generated
 
-- DeepScientist is installed and running
-- your OpenClaw gateway is already running locally
-- the OpenClaw HTTP gateway port is known, usually `18789`
-- you have a public IP or public domain
+After you click `Add Lingzhu (Rokid Glasses)`, the popup shows these copyable values:
 
-Important:
+- Custom agent ID
+- Custom agent URL
+- Custom agent AK
+- Agent name
+- Category
+- Capability summary
+- Opening message
+- Input type
+- Icon PNG URL
 
-- `127.0.0.1` only works for local health checks
-- Lingzhu devices need a public address
+Important details:
 
-## 3. Open the settings page
+- `Custom agent URL` is generated as `https://<your-public-address>/metis/agent/api/sse`
+- `AK` is generated automatically and reused after saving
+- the logo uses a PNG DeepScientist asset so it can be uploaded directly to Rokid
 
-Open:
+![Rokid third-party agent creation form](../images/lingzhu/rokid-agent-platform-create.png)
 
-- `Settings > Connectors > Lingzhu`
+## 4. What the user does
 
-The card is organized into:
+On the Rokid platform:
 
-- gateway endpoint
-- auth and identity
-- generated values
-- probe and verify
-- advanced debug
+1. Open `Project Development -> Third-party Agent -> Create`
+2. Choose `Custom Agent`
+3. Copy each generated field from the popup into the matching Rokid field
+4. Upload the DeepScientist PNG logo
+5. Return to DeepScientist and click Save
 
-![Lingzhu settings overview](../images/lingzhu/lingzhu-settings-overview.svg)
+After Save, the Lingzhu binding is complete.
 
-## 4. Fill the endpoint fields
+## 5. How it is used afterward
 
-Recommended values:
+The glasses or platform only need to call:
 
-| Field | Recommended value | Notes |
-| --- | --- | --- |
-| `Enabled` | `true` | turn on the companion config |
-| `Transport` | `openclaw_sse` | fixed, do not change |
-| `Local host` | `127.0.0.1` | used only for local probe |
-| `Gateway port` | `18789` | match your OpenClaw gateway |
-| `Public base URL` | `http://<public-ip>:18789` | must be reachable from the glasses |
+- `POST /metis/agent/api/sse`
 
-If you do not know what to fill for the local endpoint, click:
+with:
 
-- `Use local defaults`
+- `Authorization: Bearer <saved-AK>`
 
-## 5. Generate the AK and identity values
+Usage rules:
 
-Fill or keep:
+- a new task must start with `我现在的任务是 ...`
+- only the text after that prefix is treated as a fresh DeepScientist task
+- if you only want buffered progress, do not repeat the prefix; just say `找DeepScientist` or `继续`
 
-| Field | Recommended value |
-| --- | --- |
-| `Auth AK` | click `Generate AK` |
-| `Agent ID` | `main` |
-| `Lingzhu system prompt` | optional |
+## 6. Common questions
 
-Use the same `auth_ak` and `agent_id` in both places:
+### Why can’t I use `127.0.0.1`?
 
-- OpenClaw Lingzhu plugin config
-- Lingzhu platform config
+Because Rokid and external devices cannot reach your local loopback address. Lingzhu must register a public address.
 
-## 6. Use the generated values
+### Why is `AK` generated automatically?
 
-DeepScientist shows the exact values you need:
+Because `AK` is the Bearer secret for this external entrypoint. Generating and persisting it is safer and more reliable than asking users to type it manually.
 
-- local health URL
-- local SSE URL
-- public SSE URL
-- OpenClaw config snippet
-- probe curl
+### Do I still need to tune a lot of extra parameters after saving?
 
-The public value is the one you should paste into the Lingzhu platform.
-
-![Lingzhu platform values](../images/lingzhu/lingzhu-platform-values.svg)
-
-## 7. Update OpenClaw
-
-Use either:
-
-- the generated snippet in the settings page
-- or the packaged template at `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
-
-Install the packaged bridge with:
-
-```bash
-openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
-```
-
-At minimum, OpenClaw must expose:
-
-```json
-{
-  "gateway": {
-    "port": 18789,
-    "http": {
-      "endpoints": {
-        "chatCompletions": {
-          "enabled": true
-        }
-      }
-    }
-  }
-}
-```
-
-DeepScientist also generates the full Lingzhu plugin block for you:
-
-![OpenClaw config snippet](../images/lingzhu/lingzhu-openclaw-config.svg)
-
-## 8. Run the local probe
-
-After saving the values, click:
-
-- `Run Lingzhu probe`
-
-DeepScientist performs:
-
-1. `GET /metis/agent/api/health`
-2. `POST /metis/agent/api/sse`
-
-Expected result:
-
-- `Connection = reachable`
-- `Auth = ready`
-- probe result returns no errors
-
-## 9. What to paste into the Lingzhu platform
-
-Use:
-
-- `Public SSE URL`
-- `Auth AK`
-
-Do not paste:
-
-- `127.0.0.1`
-- any local-only host name
-
-## 10. Common failure causes
-
-### Health is offline
-
-Usually means:
-
-- OpenClaw is not running
-- wrong `gateway_port`
-- wrong `local_host`
-
-### SSE probe fails
-
-Usually means:
-
-- `auth_ak` mismatch
-- Lingzhu endpoint path is not exposed
-- OpenClaw `chatCompletions.enabled` is still off
-
-### Device still cannot connect
-
-Usually means:
-
-- `Public base URL` is not public
-- firewall or reverse proxy still blocks the port
-
-## 11. Practical note
-
-This settings surface is intentionally registry-first:
-
-- Lingzhu stays in `connectors.yaml`
-- generated values come from the same structured config
-- validation, testing, and frontend rendering consume the same connector record
-
-For long-running tasks, the most stable practical behavior is:
-
-- immediate bridge-level receipt acknowledgement
-- visible progress heartbeats from the bridge during silent upstream phases
-- preserved per-user session continuity across follow-up turns
-
-This improves Lingzhu compatibility, but it still does not remove the platform-side single-request timeout limit.
+No. The goal of the current Lingzhu flow is to show only the necessary values, let the user copy them, and finish with one save.

package/docs/en/09_DOCTOR.md

@@ -10,21 +10,35 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    npm install -g @researai/deepscientist
    ```
 
-2. Try to start DeepScientist:
+2. Make sure Codex is installed and authenticated:
+
+   ```bash
+   codex --login
+   ```
+
+   If `codex` is missing, repair it explicitly with:
+
+   ```bash
+   npm install -g @openai/codex
+   ```
+
+   If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+
+3. Try to start DeepScientist:
 
    ```bash
    ds
    ```
 
-3. If startup fails or looks unhealthy, run:
+4. If startup fails or looks unhealthy, run:
 
    ```bash
    ds doctor
    ```
 
-4. Read the checks from top to bottom and fix the failed items first.
+5. Read the checks from top to bottom and fix the failed items first.
 
-5. Run `ds doctor` again until all checks are healthy, then run `ds`.
+6. Run `ds doctor` again until all checks are healthy, then run `ds`.
 
 ## What `ds doctor` checks
 
@@ -49,16 +63,38 @@ Run the package install again so the bundled Codex dependency is present:
 npm install -g @researai/deepscientist
 ```
 
+If `codex` is still unavailable afterward, install it explicitly:
+
+```bash
+npm install -g @openai/codex
+```
+
 ### Codex is installed but not logged in
 
 Run:
 
 ```bash
-codex
+codex --login
 ```
 
+If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+
 Finish login once, then rerun `ds doctor`.
 
+### The configured Codex model is unavailable
+
+DeepScientist blocks startup until Codex passes a real startup hello probe. In the current release, that probe first uses the runner model configured in:
+
+```text
+~/DeepScientist/config/runners.yaml
+```
+
+The default is `gpt-5.4`. If your Codex account or CLI config cannot access that model, DeepScientist now retries with the current Codex default model and persists `model: inherit` for future runs. If you still want a specific model, edit the runner config manually and rerun:
+
+```bash
+ds doctor
+```
+
 ### `uv` is missing
 
 Normally `ds` will bootstrap a local `uv` automatically. If that bootstrap fails, install it manually:

package/docs/en/10_WEIXIN_CONNECTOR_GUIDE.md

@@ -0,0 +1,137 @@
+# 10 Weixin Connector Guide: Bind Personal WeChat To DeepScientist
+
+This guide explains the built-in DeepScientist Weixin connector.
+
+DeepScientist already includes the Weixin iLink runtime. You do not need to install OpenClaw, run `npx`, or configure a separate local bridge. The only required binding action is:
+
+1. open `Settings > Connectors > WeChat`
+2. click `Bind WeChat`
+3. scan the QR code with WeChat
+4. confirm the login inside WeChat
+
+After confirmation, DeepScientist saves the Weixin connector automatically and starts long polling.
+
+## 1. What this connector does
+
+After binding succeeds, DeepScientist can:
+
+- receive WeChat text messages
+- receive WeChat image, video, and file attachments
+- copy inbound attachments into the active quest under `userfiles/weixin/...`
+- send text replies back to the same WeChat context
+- send native WeChat images, videos, and files when the agent attaches a real local file
+
+Inbound media is materialized into the quest, not kept only in an ephemeral connector cache. The current path shape is:
+
+```text
+~/DeepScientist/quests/<quest_id>/userfiles/weixin/<message_batch>/
+```
+
+That makes Weixin media behave much closer to the QQ path: the quest receives durable local files that the agent can read.
+
+![DeepScientist Weixin binding overview](../images/weixin/weixin-settings-bind.svg)
+
+## 2. Before you bind
+
+Check these items first:
+
+- DeepScientist daemon and web UI are already running
+- you can open `Settings > Connectors > WeChat`
+- you have a real personal WeChat account on the phone that will scan the QR code
+
+This reference screenshot is only there to remind you to use the phone that already holds the target WeChat account. The actual binding still happens from the DeepScientist QR modal, not from a separate `npx` tool.
+
+![WeChat app reference](../images/weixin/weixin-plugin-entry.png)
+
+## 3. Bind from the Settings page
+
+Open:
+
+- [Settings > Connectors > WeChat](/settings/connectors#connector-weixin)
+
+Then:
+
+1. click `Bind WeChat`
+2. wait for DeepScientist to generate the QR code
+3. scan it with WeChat
+4. confirm the login on the phone
+
+Important points:
+
+- the modal only shows the QR code because DeepScientist already knows the full iLink login flow
+- there is no manual `bot_token` form during binding
+- there is no extra Save button inside the QR modal
+- when the platform returns `bot_token` and account ids, DeepScientist persists them automatically
+
+After success, the WeChat card shows:
+
+- `Bot account`
+- `Owner account`
+
+That is the saved connector binding.
+
+![QR scan and confirmation flow](../images/weixin/weixin-qr-confirm.svg)
+
+## 4. Verify with one text or media message
+
+After the QR login succeeds:
+
+1. bind a quest to the Weixin connector from `Start Research` or the project surface
+2. send one text, image, video, or file message from WeChat
+3. let DeepScientist ingest it into the quest
+4. confirm the reply arrives in the same WeChat thread
+
+Current behavior:
+
+- inbound text enters the quest as the user message
+- inbound image, video, and file attachments are downloaded and copied into quest-local `userfiles/weixin/...`
+- media-only inbound messages are no longer dropped
+- outbound text replies use the runtime-managed `context_token`
+- outbound image, video, and file delivery works when the agent sends a real local file path
+
+![Quest-local media flow](../images/weixin/weixin-quest-media-flow.svg)
+
+## 5. What the agent should do with Weixin media
+
+For ordinary user guidance, the important rule is simple:
+
+- if the agent only needs to answer with text, normal message replies are enough
+- if the agent needs to send a native WeChat image, video, or file, it must send a real local file from the quest
+
+In practice, that means the agent should prefer quest-local files such as:
+
+```text
+artifacts/...
+experiments/...
+paper/...
+userfiles/...
+```
+
+instead of depending on an arbitrary external URL.
+
+## 6. Troubleshooting
+
+### QR code keeps waiting
+
+Check:
+
+- the phone is scanning with the same WeChat account you want to bind
+- the phone finished the confirmation step inside WeChat
+- DeepScientist is still running while you wait
+
+If the QR expires, DeepScientist refreshes it automatically.
+
+### I only see text, but not inbound media
+
+Re-test with a real image, video, or file. After a successful inbound media message, confirm that the quest now contains:
+
+```text
+userfiles/weixin/<message_batch>/manifest.json
+```
+
+and the copied media file next to it.
+
+## 7. References
+
+- Runoob personal WeChat guide: https://www.runoob.com/ai-agent/openclaw-weixin.html
+- Upstream Weixin protocol reference: https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md