makecoder 5.0.23 → 5.0.25

package/docs/agent/README.md

@@ -0,0 +1,15 @@
+# Cowork docs: reading map
+
+> **Purpose**: tell you which page answers a question about working inside Cowork, and how big it is.
+> **Read this when**: the SDK map (`bq docs`) has no page for the question: where a command runs, how results reach the user, where files live, what needs the user's approval.
+
+| You want to | Read | Size |
+|---|---|---|
+| Decide where a command runs; read an `AIStudio:` line | [Two machines: Cowork and AIStudio](runtime.md) | ~1.1k tokens |
+| Hand a result to the user: report, table, chart, document, image | [Results become cards](artifacts.md) | ~900 tokens |
+| Start a task; find the project's files and the user's attachments | [The workspace](workspace.md) | ~400 tokens |
+| Do something that costs money or cannot be undone | [What asks the user first](approvals.md) | ~500 tokens |
+
+These pages exist only inside Cowork (`/opt/cowork/docs`, installed with the Cowork server); the SDK pages from `bq docs`
+apply everywhere. Facts here describe the Cowork server of the same version as these files; when a page and the code
+disagree, the code is right and the page needs a fix.

package/docs/agent/approvals.md

@@ -0,0 +1,16 @@
+# What asks the user first
+
+> **Purpose**: the actions that always stop for the user's confirmation, and how to behave around them.
+> **Read this when**: you are about to place or cancel an order, deploy a strategy, start or change the user's paid compute, or publish something.
+
+| Action | How the confirmation happens |
+|---|---|
+| Real orders and local deployments through the BigTrader terminal: `bq bigtrader terminal fileorder new|cancel …`, `bq bigtrader terminal localdeploy add|remove|start|pause|auto …` | The runtime asks for permission every time, in every permission profile, even when the user chose full access. Run the command; the interface shows the request; wait for the answer. |
+| Platform deployment: `bq trading strategy deploy …` (paper and live; `--dry-run` too) | Same rule. |
+| Task commands that make a strategy trade: `bq task trigger|resume|update …` | Same rule. `bq task pause` and `bq task cancel` do not ask: they reduce risk. |
+| Starting a stopped AIStudio on a paid spec, or switching to a bigger spec | Not intercepted by the runtime: `bq aistudio exec` starts the configured spec by itself and prints its price (`runtime.md`). Before switching specs (`bq aistudio start --spec …`), or when the user has set `BIGQUANT_AISTUDIO_AUTOSTART=0`, ask in the reply and wait for the next message. |
+| Publishing a factor as a daily-updated platform table | The user's 入库 button on the factor card. Do not run the publish mode. |
+
+When a request is denied: stop that action, say in one line what was not done, and continue with the parts that need no
+confirmation. A request that gets no answer within five minutes counts as denied. Scripts that place orders through the SDK
+directly are not intercepted: prefer the `bq` commands above so the user keeps the confirmation step.

package/docs/agent/artifacts.md

@@ -0,0 +1,39 @@
+# Results become cards
+
+> **Purpose**: how a file you produce reaches the user as a card in the Cowork interface, and what you write in the reply instead.
+> **Read this when**: you are about to hand the user a report, a table, a chart, a document or an image; when a backtest or factor run has finished.
+
+The interface renders results; you write conclusions. A file becomes a card when it is registered as an
+artifact of the current turn. Three producers register:
+
+| Producer | When | You do |
+|---|---|---|
+| The SDK (`bigquant.cowork`) | `bigtrader.run` registers its report card the moment the run ends (`BIGTRADER_RENDER=card` is the default here); a factor file (`compute` + `factor.run`) registers the factor card; `bq dai query "<sql>" --out <name>.parquet` registers a table card (rows, columns, first rows, paging). | Nothing. Run it on AIStudio (`runtime.md`); the card is on screen before you write a word. |
+| You, with `bq agent artifact` | A file you wrote yourself: a document, an image, a table, code, a notebook, an HTML page. | `bq agent artifact --type <document|image|table|chart|code|html|notebook|file> --path <file> --title <标题>` |
+| The end-of-turn scan | Files written under the project during the turn that nothing registered (a strategy from `bq examples new`, a saved CSV). | Nothing; the type comes from the extension. |
+
+Charts: `bq agent chart --from <name>.parquet --kind line|bar|area|scatter --x <col> --y <col>[,<col>] --title <标题>`
+draws a saved table as a chart card. Do not write plotting code or chart JSON yourself.
+
+PDF attachments: `bq agent pdf --from <file.pdf>` writes `<file>.pdf.md` (one `[page::N]` block per page) and prints
+which pages carry figures, tables or performance numbers; `--pages N` or `A-B` renders those pages to PNG so you can look
+at a chart or a formula. Read the text first, render only the pages you need.
+
+How it works: for each turn the server sets `COWORK_EVENTS_FILE=<project>/.cowork/turns/<turn>/events.jsonl`; every
+process you start inherits it, on AIStudio too (`bq aistudio exec` forwards the `COWORK_*` variables), and the SDK
+appends `phase` / `progress` / `artifact` lines that the interface shows live. Paths are relative to the session's
+working directory; a file outside it cannot be registered, so write results inside the project.
+
+## What you write
+
+- Never paste a card's tables or rows. The reply is the conclusion, in Chinese, at most five sentences: whether it
+  worked, the numbers against the benchmark, the assumptions you chose, the next steps.
+- Before each step that takes more than a few seconds (reading a report, looking fields up, a query, a backtest), write one
+  line in Chinese of at most 40 characters saying what you are about to do and why; no code, commands or paths in it.
+  When a result changes what comes next, say so in one line too.
+- A task of more than three steps, or whose steps you only know after reading the material, gets a plan once:
+  `bq agent plan "读研报" "分钟数据预处理:data:3600" "滚动训练" "回测" "对比研报" --current 2` (3 to 8 Chinese labels of at
+  most 12 characters, one per step that takes minutes; `label:kind:seconds` adds a kind or your duration guess). Then start
+  the `description` of every tool call with its step, `2/5 拉取分钟数据`, so the plan bar advances. The call returns at once.
+- Publishing a factor as a daily-updated platform table is the user's 入库 button on the factor card. Never run the
+  publish mode yourself; say the button is there.

package/docs/agent/runtime.md

@@ -0,0 +1,46 @@
+# Two machines: Cowork and AIStudio
+
+> **Purpose**: say where each kind of work runs, and what the `AIStudio:` lines printed by `bq aistudio exec` mean.
+> **Read this when**: before running anything that computes; when a command's stderr ends with an `AIStudio:` line; when AIStudio is stopped or a command died.
+
+## Where things run
+
+| Machine | What it is | Runs here |
+|---|---|---|
+| Cowork (you are here) | The agent's workstation: a small pod with `python3`, `bq`, git and ssh, no data plane. | Reading, searching and editing files; writing scripts; git; the `bq` helper commands (`bq agent …`, `bq docs`, `bq examples`). |
+| AIStudio | The user's compute environment next to the data: the full SDK, the data plane, the user's own packages, more CPU and memory. | Everything that produces a computed result: running a strategy or backtest (`python strategy.py`), factor computation, `bq dai query`, training, `pip install`. |
+
+Both machines share the home directory: `~/work`, `~/.bigquant`, `~/.local` are the same files at the same paths, so a file
+you write here is already there and a package the user installed there is importable here. Cowork's own state lives in
+`~/.cowork/` and is not the user's.
+
+```bash
+bq aistudio exec -- python strategy.py                 # argv as given; your current directory is carried over
+bq aistudio sh 'python a.py 2>&1 | tail -n 50'          # one shell line when you need a pipe or a redirection
+bq aistudio exec -C ~/work/cowork/proj -e BIGTRADER_RENDER=card -- python run.py
+bq aistudio exec --timeout 600 -- python train.py       # exit 124 when the limit hits; the remote process is ended
+cat rows.csv | bq aistudio exec -- python etl.py        # local stdin reaches the remote command
+```
+
+- `BIGTRADER_*`, `BIGQUANT_*`, `COWORK_*`, `LANG` and `TZ` travel along, so a backtest run there still reports to this turn
+  (`artifacts.md`); everything else in the environment is AIStudio's own.
+- A command longer than one line goes into a script file under the project first; then run the file. Quoting works like a
+  local command because nothing re-parses the arguments.
+- Packages the user needs: `bq aistudio exec -- pip install --user <pkg>`; never `pip install` here.
+- Killing `bq` (Stop, a timeout) ends the remote process group. Work that must outlive the turn is a job: `bq aistudio jobs`
+  and the "A job that outlives the connection" section of the SDK's `aistudio.md`.
+
+## The `AIStudio:` lines
+
+At most one line, on stderr, and only when something the command's own output cannot show happened. Exit 255 means the
+command did not run or the connection dropped; the line says which.
+
+| The line says | What happened | Do next |
+|---|---|---|
+| `studio is stopped; starting on <spec> ...` | AIStudio was off; it was started and the command then ran. A paid spec bills per minute from now. | Tell the user in one line that their AIStudio was started, with the spec. `bq aistudio stop` only when the user asked for it. |
+| `process killed (exit 137, out of memory); peak memory <n> GB, limit <n> GB` | The command exceeded AIStudio's memory. | Shrink the data first (narrower `filters`, fewer instruments, dates in chunks). A bigger spec is the user's decision (`approvals.md`). |
+| `the studio restarted since the last command: processes, /tmp and background jobs started before are gone` | The pod came back; files under `~` are intact. | Rerun what depended on process state or `/tmp`; files need nothing. |
+| `<n> background process(es) left running in the studio (pid … cmd …); their later output is not shown` | The command forked something that is still running. | Mention it if the user should know; look with `bq aistudio exec -- ps -o pid,etime,cmd -p <pid>`. |
+| `the connection dropped while the command was running; it may have run partially` | Network or pod loss mid-run. | `bq aistudio status`; check what the command wrote before rerunning it. |
+| `cannot reach the studio (ssh exit <n>); the command did not run` | AIStudio is stopped or unreachable and could not be started. | `bq aistudio status`; if `State` is stopped, `bq aistudio start --wait` (paid spec: ask first), then rerun. |
+| `the studio image has no /usr/local/bin/cowork-exec` or `speaks protocol <n>, this bq expects <n>` | The AIStudio image and this `bq` do not match. | Tell the user the AIStudio image must be upgraded; nothing you can do from here. |

package/docs/agent/workspace.md

@@ -0,0 +1,17 @@
+# The workspace
+
+> **Purpose**: where a task's files live, what is the user's and what is Cowork's, and where attachments land.
+> **Read this when**: starting a task; looking for the user's files or an uploaded attachment; deciding where to write.
+
+| Path | What | Notes |
+|---|---|---|
+| `~/work/cowork/<project>/` | The session's working directory: a named project, or a chat directory `YYYY-MM-DD-HHMMSS` for a conversation without a project. | Your current directory when the turn starts. Everything you produce goes here or below. AIStudio sees the same directory at the same path. |
+| `<project>/.cowork/` | Cowork's per-project data: `uploads/` (the user's attachments), `turns/<turn>/events.jsonl` (this turn's events), `dashboard.json`, `memory.md`. | Read `uploads/` when the user attached a file. Do not write here except through `bq agent …`. |
+| `~/work/` | The user's other work: repositories, notebooks, data files, exactly as in AIStudio. | Read and edit as asked. An existing directory of the user's can itself be the project. |
+| `~/.bigquant/` | The user's SDK credentials and profiles, shared with AIStudio. | Never copy or print credentials. |
+| `~/.cowork/` | Cowork's own state: the session database, this briefing, the agent runtimes' configuration and transcripts. | Not the user's; leave it alone. |
+
+Conventions: strategy files as `bq examples` shows them (one module-level `run`, parameters through `param`); data
+saved under the project as `.parquet` (`bq dai query --out`); a short `README.md` in a named project when the work spans
+several sessions, so the next session can pick it up from the file. A file written here exists on AIStudio at the same
+path at once: nothing to copy, nothing to sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makecoder",
-  "version": "5.0.23",
+  "version": "5.0.25",
   "description": "MakeCoder Coder: AI Agent Runtime OS that runs and orchestrates Claude Code, Codex, Gemini and more across CLI, API, Web and chat",
   "main": "./dist/coder.js",
   "bin": {
@@ -57,17 +57,18 @@
   "files": [
     "dist",
     "scripts/postinstall.js",
-    "scripts/claude-cell-segmenter-shim.js"
+    "scripts/claude-cell-segmenter-shim.js",
+    "docs/agent"
   ],
   "optionalDependencies": {
-    "makecoder-bin-darwin-arm64": "5.0.23",
-    "makecoder-bin-linux-arm64": "5.0.23",
-    "makecoder-bin-linux-x64": "5.0.23",
-    "makecoder-bin-win-x64": "5.0.23",
-    "makecoder-c-bin-darwin-arm64": "5.0.23",
-    "makecoder-c-bin-darwin-x64": "5.0.23",
-    "makecoder-c-bin-linux-arm64": "5.0.23",
-    "makecoder-c-bin-linux-x64": "5.0.23",
-    "makecoder-c-bin-win-x64": "5.0.23"
+    "makecoder-bin-darwin-arm64": "5.0.25",
+    "makecoder-bin-linux-arm64": "5.0.25",
+    "makecoder-bin-linux-x64": "5.0.25",
+    "makecoder-bin-win-x64": "5.0.25",
+    "makecoder-c-bin-darwin-arm64": "5.0.25",
+    "makecoder-c-bin-darwin-x64": "5.0.25",
+    "makecoder-c-bin-linux-arm64": "5.0.25",
+    "makecoder-c-bin-linux-x64": "5.0.25",
+    "makecoder-c-bin-win-x64": "5.0.25"
   }
 }