weflow-cli 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -2,8 +2,350 @@
 
 The npm package is published separately from GitHub. It may lag behind the `master` branch until a release is published.
 
+**The GitHub Releases page is cut by hand and can therefore lag npm by several versions.** That decoupling is
+deliberate (`docs/RELEASING.md`: "GitHub Release 与本清单解耦：源码、编译包、npm 三者版本差异要对用户可见"), and it comes
+with a requirement: the difference has to stay **visible**. So if a version you expect is missing from the Releases
+page, check the two sources rather than assuming it was withdrawn:
+
+```
+npm view weflow-cli version     # 权威的最新已发布版本
+gh release list                 # GitHub 上手工建过哪些
+```
+
+Everything published to npm has a section in this file. **No version numbers are written into this paragraph on
+purpose** - a hand-written "latest is X" is exactly the claim that goes stale here; those two commands never do.
+
 All notable user-facing changes are recorded here. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.9.0
+
+### Added
+
+- **`draft --pick N --send`: a candidate can now be sent, by a human who names which one.** The hard half already
+  existed - judge the intent, draft three deliberately different candidates, rank them with the decision model - and it
+  ended by saying the candidates are only text and that sending is your call. That call can now be carried out from the
+  same command. Three rules keep it honest: `--send` **requires** `--pick` (no "draft three, let it choose, let it
+  send" path exists); without `--yes` it only returns `CONFIRMATION_REQUIRED` (with the text in the payload) or asks
+  interactively; and the blacklist -> whitelist -> rate limit -> audit chain is now **one shared implementation**
+  (`src/services/outboundSend.ts`) used by both `send` and `draft --send`, because a second copy of that chain is how a
+  send path ends up quietly skipping the whitelist. Sending stays **absent from the assistant and MCP tool tables** (a
+  test asserts it), so nothing model-driven can send; `draft_reply` stays present because drafting is not sending.
+  `--dry-run` means zero egress, and since candidates can only come from a model it cannot preview one - it reports the
+  character count and says so. Usage errors (`--send` without `--pick`, `--pick 9` when there are 3) are reported
+  **before any model call**, which is also what the tests assert (D-063).
+- **`weflow-cli bonds` - relationship temperature: who is going quiet, who is heating up, who is reachable only here.** Not a
+  leaderboard of who you message most (that tells you nothing you did not know); the useful signal is the *shape*. It
+  reports relationships with substantial history that have gone silent (ranked by messages x silent days, so it
+  surfaces "294 messages last year, nothing for 282 days"), relationships whose last 7 days run at least twice the
+  long-run rate, and contacts whose entire history never mentions another channel - phone, email, meeting up - which
+  is the data-derived version of "if this account disappeared tomorrow". Read-only, local, no model, no network.
+  Three measurements shaped it, and all three overturned a simpler design: ranking by volume produced no information;
+  the first irreplaceability rule was **inverted** (it is trivially true of bots, so the top of the list was a coffee
+  shop's bot); and `flag` - the field that looked like a clean human/bot marker - would have silently deleted two
+  real friends, since two of the 38 people on this machine carry extra bits from however they were added. What
+  remains is the **shape of the id** (`@` anything, `filehelper`, `gh_` are out), plus accounts that look structurally
+  like a person but whose name reads as a shop are **flagged for you to decide** rather than dropped, with a skip file
+  and `--skip`. Every exclusion is printed with its reason. Deliberately **not** in the assistant or MCP tool tables:
+  its output is an inference about other people (D-062).
+- **Voice messages reach the conversation cards as text, not as `[语音]`.** The chat line fed the model a bare
+  `[语音]` placeholder for every voice message - no length, no words - while the transcripts were already on disk:
+  the local faster-whisper pass writes a content-addressed cache, and measured over the last 30 days **1,780 of
+  1,869 clips** in the busiest conversations already had a transcript that nothing was reading. `chat-notes` now
+  reads that cache and substitutes the text, labelled `[语音·本机转写·未校对]` - the label is not decoration: it is
+  someone's speech as a machine heard it and it will contain errors, so the model has to know not to treat it as
+  quoted fact (the same discipline as `verified: false` on concept pages). `--transcribe-voice` fills what is
+  missing (local model, never leaves the machine, resumable - the cache is the progress); without it the run only
+  reads, and the count of what is still missing is printed rather than quietly omitted. First real run: **54 of the
+  125 voice messages in the 30-day window** carry text into the cards that previously said `[语音]`.
+  Finding this also surfaced a quieter bug in the same feature: the cache directory was being derived from
+  `chat-notes`'s *card* output directory, so it read a cache it had just created itself (`output/chat-notes/.voice-cache`,
+  16 entries) instead of the real one (`output/.voice-cache`, 1,788) - and the run reported "16 hits" that were
+  internally consistent and wrong. The cache's location is now defined once, in the module that owns the cache, and
+  a test asserts the three readers agree.
+- **The MCP server can speak Streamable HTTP, so clients that cannot spawn a process can use it too.** stdio stays
+  the default and is unchanged; `--http` (or `WEFLOW_MCP_HTTP=1`) serves the **same tools** over HTTP, because the
+  table is derived from one place (`TOOL_DEFS` -> `MCP_TOOL_DEFS`). Serving private messages on a listening socket is
+  a different risk from writing to stdout, so four rules are enforced in code and each is mutation-checked: it is
+  **off unless asked for**; a **token is mandatory with no default** (missing or under 24 characters, the process
+  refuses to start and prints how to generate one); the bind is **loopback only** (`0.0.0.0` is rejected with the
+  tunnel command in the message, because widening the bind is what would put chat data on the network); and
+  **DNS-rebinding protection is on**, which the SDK leaves off by default - the realistic attack on a loopback server
+  is a web page you happen to visit reaching `127.0.0.1`, so the `Host` header must match and any `Origin` must be
+  allowlisted. Requests are stateless and the token is never logged. Default port 8790 (5030 is chatlog's, and two
+  servers fighting over a port is not a useful failure). The decisions live in `mcp-server/httpConfig.ts` as pure
+  functions with 13 offline tests, five of which were shown to go red by mutation.
+- **Tool coverage is now a test-watched table instead of a paragraph.** The list of "which tools have no eval
+  case" used to be prose inside the case file, and prose does not fail when it goes stale - two of its claims had.
+  It is now `EVAL_UNCOVERED`, a map from tool name to reason, with `test/assistant-eval.test.ts` asserting both
+  directions: every tool is either claimed by some case's assertions or registered here, and no registered name has
+  stopped existing. Adding a tool now means writing a case or writing a reason; skipping both fails. That walk also
+  caught two cases whose comments promised a distinction they never asserted - `daily-review` says it is testing
+  "get_review, not get_daily_report" and `skills-health` says the same about `check_skills` vs `list_skills`, and
+  neither had the `mustNotCall` half. Both have it now, verified against the real model.
+- **Five more behaviour-eval cases, and a limitation list that had gone stale.** Walking the 31 tools one by one
+  against `assistantEval.ts` turned up five with no assertions at all - and one stub that made its own case
+  untestable: `getSnsTimeline` returned a hard-coded empty timeline, so `get_sns` could only ever be asserted as "no
+  cached data", the same defect `listContacts` had. The `sns` fixture is per-case now, and the new cases cover
+  `get_sns`, `read_skill` (the body, not just `list_skills`' catalogue), `get_stats`' knowledge-base half,
+  `export_chat` (into a temp root, via `WEFLOW_ASSISTANT_EXPORT_ROOT`), and `draft_reply` under strict privacy - that
+  last one is a guard for a real regression: with `aiEngine=ollama` the old code still handed the conversation to the
+  script, whose two remote calls have nothing to do with that setting. The block of comments claiming which tools
+  were untestable was rewritten too, because two of its claims were no longer true (`get_concepts`/`get_review` had
+  been covered since 2026-09-30, and the harness does set environment variables). `get_weread` was filed as untestable too, for the same reason - which mistook a missing mechanism for an
+  untestable tool, since the harness had been overriding `assistantPrivacy` per case all along without
+  generalising it. A general per-case `config` override fixed that, and `weread-notebooks` now asserts the book
+  title actually reaches the answer (reading `b.title` off the notebooks response returns `undefined` while the
+  output still looks fine - the silent version of that bug is what the case is for). What is genuinely uncovered
+  is **one** tool: `search_semantic`, which needs a `dashscopeApiKey` and a built index. Run against the real
+  model the same day: **37 passed, 0 failed** once `weread-notebooks` was added. The strict-draft case is worth one note for what it did *not* do - it
+  called `get_messages` and then refused, never reaching for `draft_reply`, so an expectation of
+  `mustCall: ['draft_reply']` (that case's first version) would have failed on its first run and sent someone chasing
+  a defect that does not exist. Asserting the outcome rather than the call is what the memory cases already argued
+  for, and here it is what kept the case honest.
+- **`backfill_articles.py --topic` fetches one topic instead of a whole day - and a day fetched that way knows it is
+  partial.** The filter is the classifier the script already had: `_guess_topic` reads only the article's title and its
+  account name, never the body, so `--topic AI` selects exactly the articles a full run would have filed under `AI`.
+  The saving is the point - over 2025-09-05 ~ 2026-03-02 the untouched backlog is 9,207 articles across 156 days
+  (official accounts only: `gh_%`), 1,758 of them AI, and because 5,278 of the 9,207 already hold enough text in the
+  database a full run needs **3,929** network fetches against the AI run's **1,208**. What makes it safe rather than merely convenient is the bookkeeping: the day
+  records `topicFilter` in `.articles.json` and names the missing topics in its README, and `day_done` refuses to call
+  it finished, so a later full run still covers those days. Without that marker the other five topics would have been
+  dropped with nothing to report it - the same shape as the `backfilled`-marker mistake of 2026-09-28 (D-060). The
+  filter is applied inside `write_day` too, so a caller that forgets cannot stamp "only AI" on a directory holding all
+  six topics. An unknown `--topic` is rejected before the database is opened: a typo would otherwise select zero
+  articles and report "nothing to do", which is indistinguishable from a day that genuinely had none.
+- **Two more behaviour-eval cases cover the tools that had no testable data at all.** `daily-review`
+  (`get_review`) and `knowledge-overview` (`get_concepts`) both read directories rather than services, and
+  with the eval running in a temporary home those directories are always empty - which is why neither tool
+  could be asserted beyond "nothing here yet". `WEFLOW_ASSISTANT_VAULT_DIR` was added as a third per-call
+  injection point (the same mechanism `WEFLOW_ASSISTANT_BIZ_DAILY_DIR` and `WEFLOW_ASSISTANT_REVIEWS_DIR`
+  already use), and the eval can now lay down fixture files and set those variables for a case. Same day, a
+  real gap surfaced: `listContacts` had never been stubbed, so `list_contacts` was calling the real service
+  against a temp home and always coming back empty - two cases were running on that accident while the
+  harness claims synthetic data. It is stubbed now, with contacts derived from the case's own sessions.
+- **The assistant's behaviour eval now covers the tools the widened surface added.** Ten tools went in on
+  2026-09-30 and nine of them had no assertions at all - which matters because that is exactly how "did routing get
+  worse once there were ten more tools to choose from" goes unnoticed. Six cases were added (`format-for-wechat`,
+  `themes-listed`, `skills-health`, `wiki-health`, `todo-done`, `todo-ambiguous-refused`); the two that leave the
+  machine cannot be evaluated there by design, and two more have no injection point yet - all four are written down
+  in the case file rather than skipped quietly. The write cases came with a new floor, `neverSucceeds`: if the named
+  tool was called, that call must have produced nothing, so "asked the user instead of writing" and "called the tool
+  and was refused" both pass while an actual write fails. Full run the same day: **29 passed, 0 failed**.
+
+- **Skills: the assistant can read the skill packages you already have.** A skill is a directory with a `SKILL.md`
+  (`name`/`description`), scanned from `skillDirs` - by default `~/.claude/skills` and `~/.weflow-cli/skills` - so the
+  skills already on this machine are usable immediately. The system prompt carries the catalogue and two read-only
+  tools (`list_skills`, `read_skill`) return it and one body; a scene can reference a skill inline with
+  `{{skill:<id>}}`. **A skill grants no new powers**: nothing is installed, nothing is executed, no tool is added to
+  the model's table, and `read_skill` can only return a file named `SKILL.md` that the scan already found. Referencing
+  a skill that is missing, disabled or unreadable renders exactly that state and asks the model to continue and say
+  what it could not do rather than dropping the reference. Disable one with
+  `config set skillDisabled <id, ...>` or with `enabled: false` inside the skill itself.
+  `weflow-cli skill list|show|check|--json`; `skill check` reports unreadable frontmatter, cross-root collisions,
+  non-conforming ids and disabled skills. On this machine `skill check` finds **28 skills, 0 unreadable, 0 collisions**,
+  and warns about 5 ids that are usable here but would not conform to the Anthropic Agent Skills naming rule
+  (`clz_docx_to_mp` and friends). Rationale and the two rules taken from real data (read only the leading `---` block;
+  support block scalars) are in D-056.
+
+- **Scenes: per-conversation prompt presets.** A scene is keywords + an extra instruction + an output spec + required
+  skills, stored in `~/.weflow-cli/assistant_scenes.json` (`weflow-scenes/v1`, unknown version quarantined rather than
+  migrated). Each turn picks at most one through three tiers - **explicit binding → keyword hit → last used in that
+  conversation** - and no match means no scene section at all, leaving the default behaviour byte-identical. Two
+  equally long keyword matches produce **no** scene plus a trace note saying why, instead of picking one. Manage them
+  with `weflow-cli scene list|show|add|remove|enable|disable|bind|unbind` (every mutation is `--dry-run` then `--yes`),
+  or from a conversation with the built-in `场景 <id>` / `场景 无` / `场景`, which accepts only an argument that names an
+  existing scene so an ordinary sentence starting with 场景 is left to the model. **Scenes cannot be read or written by
+  the model** - there is no such tool - and a scene's content enters the prompt through `frameLocalData`. Which scene
+  applied, and which tier matched, is recorded in the turn trace you already see under 「思考过程」 in the panel.
+  Scene ids are validated against quotes and angle brackets before they reach the prompt label. Rationale, the MCP
+  collapse cost and the deliberately skipped fourth tier are in D-057.
+
+- **The assistant can reach everything it already could over MCP, and only what the project allows.** Three
+  surfaces had drifted: the CLI, the 21-tool assistant table, and 11 tools hand-written in the MCP server that the
+  chat path could not call at all. Ten tools are now shared - `list_contacts` (names only: never `wxid`, never the
+  avatar URL), `get_review`, `get_concepts`, `fetch_article`, `search_public`, `format_article`, `list_themes`,
+  `lint_wiki`, `check_skills`, and `set_todo_status` - seven MCP-only tools were **moved** into the shared table
+  (same tool names and arguments, single implementation; the hand-written table went from 11 entries to 4), and four
+  tools were **widened instead of duplicated**: `get_daily_report` now returns the human-readable daily with
+  `full: true` and searches across dates when given a keyword without a date (that was the MCP-only
+  `search_articles`), `get_todos` shows each item's id and groups by urgency (that was `todos remind`), `get_weread`
+  gained `stats` / `book` / `review` / `discover` / `profile` modes, and `get_stats` now reports the knowledge-base
+  half it had been missing while the MCP copy had it. Almost all of this is **alignment rather than new access**:
+  every capability added was already reachable by an MCP client.
+  Two things are genuinely new and both are **recorded with their residual risk** (D-058) rather than left to be
+  found: `search_public` sends a **model-authored query** to a third-party search page with no allowlist and no
+  preview (chosen deliberately - `fetch_article`, by contrast, accepts only `https://mp.weixin.qq.com` and
+  re-validates that allowlist on **every redirect hop**), and `set_todo_status` can flip one existing todo between
+  done/pending - it **cannot create, delete or edit anything else**, it refuses an ambiguous task-text match instead
+  of guessing, and it is deliberately **excluded from the MCP surface** ("mutating todos stays out").
+  What stays out of reach from a model-driven path is unchanged and named in D-058: sending, publishing,
+  configuration, access-list writes, `evidence-review`, `vault promote`, scenes, interactive login, and `decide`.
+  Side effect worth noting: `WEFLOW_ASSISTANT_BIZ_DAILY_DIR` and `WEFLOW_ASSISTANT_REVIEWS_DIR` were added as
+  per-call injection points, which closed the **last uncovered tool branch** - `get_daily_report` had never been
+  executed because its directory was a frozen module constant, so the only possible assertion was a shape check that
+  asserted nothing. All 31 tool branches are now executed against fixtures.
+- **Push the ball to a screen edge and it hides behind it, peeking out; click it to come back.** Drag the ball
+  until it touches the left or right edge of a monitor and let go: the ball ducks behind the edge and reappears as
+  the cat **peeking out from behind it** - head and front paws out, body hidden, with a dedicated drawing whose
+  left side is a straight cut that lands exactly on the screen edge (so it reads as "behind the bezel" rather than
+  "a ball that got clipped"). The first click (or drag) brings the normal ball back; that click deliberately does
+  *not* open the conversation, because on a hidden ball a click means "come back", not "let's talk" - a second
+  click expands as usual. Only the left and right edges: top and bottom would fight the taskbar and Windows' own
+  edge snapping. The window itself stays **fully on screen**, flush against the edge - the illusion comes from the
+  drawing, so nothing is pushed off-screen, the whole thing stays clickable, and a restart just puts the ball back
+  at the edge (not lost). Two rules make or break the effect and both have tests, because everything else stays
+  green without them: the ball's circular clip has to be off in this state (a circle would slice that straight cut
+  into an arc), and hover-zoom has to be off too (scaling by 1.02 lifts the cut 1px off the edge - a visible seam).
+  The detection threshold is deliberately below the normal 24px edge margin, so a ball that is merely parked is
+  never mistaken for one being pushed off (also tested).
+
+- **The ball's eyes follow your mouse.** Move the pointer and the mascot looks that way; stop moving and it settles
+  and stops animating entirely (no 60 fps loop running for decoration on a window that is always open). The cursor
+  position has to come from the main process - the ball is 96x96, so the pointer is outside the window almost all of
+  the time and the page never sees a mousemove - and it is sampled at 120 ms, pushed **only when the coordinates
+  change**, kept strictly in-process, and never logged or sent anywhere (D-059). How far the eyes can travel is
+  **measured from the artwork**, not picked: the iris has about 7 px of sclera to its left and none above it, which
+  at the ball's size is roughly 2.6 px sideways and 0.8 px up - past that the eye reads as a sticker sliding, so the
+  movement is clamped to an ellipse. The eyes drift only on the idle and "pressed" faces; the thinking / offline /
+  tired faces have their eyes drawn in, so the moving layer is hidden there rather than showing two pupils. The ball
+  is otherwise pixel-for-pixel what it was: the new base image plus the iris layer, composited at rest, are asserted
+  to equal the old ball image exactly. If your system asks for reduced motion, the eyes stay still.
+
+
+- **The panel shows what the assistant did, collapsed under each reply.** The user asked for the
+  thinking process to be visible but not in the way - so each answer now carries a `<details>` block
+  ("思考过程") that is **closed by default**: routing decision, any guard that pushed the turn back,
+  each tool call with its argument summary and byte count, the round count and the stop reason. The
+  lines come from the **same** `describeForChat` that the WeChat side's 「轨迹」 command prints, so the
+  two surfaces cannot drift into disagreeing about what happened - and that also means the panel
+  inherits the guarantee that `userId` never appears. When the model actually returns
+  `reasoning_content` it is appended (clipped, marked when cut); the current default model returns
+  none, and the trace says so rather than pretending.
+
+  One thing had to be defended: **the trace is an accessory, the reply is the result.** The first
+  version called the lookup unguarded, and the panel test went red immediately - its stub service
+  had no such method, so every ask became a 500. A throw there would have cost the user their answer
+  to gain nothing, so it is caught, and the test pins both halves (the trace comes through, and a
+  failing trace still returns the reply).
+
+### Fixed
+
+- **A concept name containing a double quote lost a character on every read.** `parse_frontmatter` split
+  list values with `item.strip().strip('"\'')`, and `strip` removes *every* leading and trailing quote character - not a matched
+  pair - so `AI 长出"手脚"` came back as `AI 长出"手脚`; `wiki_lint` then repeated the mistake, stripping
+  quotes a second time off values the parser had already unwrapped. One character, no error, and the visible
+  effect was a page nobody could explain: the card's `[[AI 长出"手脚"]]` matched no page name, so the page was
+  reported as an orphan. Both now unwrap a **matched pair** only. Related and fixed with it: the file name of a
+  concept page is the name sanitised (`:` `/ ? * " < > |` → `_`) and cut to 60 characters, so pages could not be
+  reached by the link that pointed at them - the builder now records the original name in `aliases:`, and
+  `wiki_lint` counts an alias as an inbound edge (it already accepted one as "exists", which is why no broken link
+  was ever reported). Measured on the live knowledge base: **28 orphan pages → 1** (`DESIGN`, which no card mentions
+  at all), with 0 broken links across 26 pages that had been silently unlinked. The case-only half of the same
+  transform is fixed with it: two names differing only in case are one file, and the builder wrote both, so the second
+  overwrote the first - **53 pages were lost this way** in the two builds of 2026-10-01 alone (44 AI, 9 non-AI).
+  Names are now grouped by file name: one page, the other spellings as `aliases` (which is what
+  `wiki compile --merge-duplicates` already did for one concept written two ways), and the **233 pages** that were
+  missing a spelling got it back - `[[AI agent]]` and `[[AI Agent]]` now reach the same page.
+- **Backfilling a day in two passes dropped the first pass from the index.** `--topic` was written for the
+  one-topic-at-a-time case, and `write_day` rewrote `.articles.json` from that run's results - so fetching `AI` on
+  Monday and `学术` on Tuesday left Tuesday's file listing only the 学术 articles while Monday's `AI` files sat on
+  disk, an index shorter than the directory and nothing reported. The index now describes **the day**, not the run:
+  entries for other topics are carried over and merged (de-duplicated on the name the file actually has), the
+  `topicFilter` mark becomes the union, and it is **removed** once the union covers all six topics - otherwise such a
+  day could never converge and every later full run would refetch the whole window. `truncated` is now sticky, and an
+  unreadable index is preserved as `.articles.json.bad` instead of being silently replaced. `--topic` also takes
+  repeated flags now, not only commas: the same flag in `article_notes.py` is repeatable, so `--topic AI --topic 学术`
+  was silently acting on only the last one. Verified on a real day (8 `AI` entries became 42, none lost, directory and
+  index equal) and across the window (8,754 entries over 157 days, 0 days with a mismatch, 0 entries lost).
+- **A day backfilled with `--limit-per-day` reported itself as complete.** The day was sliced, written, and then
+  `day_done` saw a non-empty article list and skipped it from then on, so everything past the limit was silently out
+  of scope - and had been since the flag was added. Such a day now carries a `truncated` marker and is redone on the
+  next run. Note the behaviour change: a limited day is no longer incremental, so re-running it re-fetches the same
+  first N articles. Written down as D-060 alongside `--topic`, because it is the same defect - an incomplete
+  criterion read as "done".
+- **The subscription-account database key was derived in three places, and two of them could never
+  have worked.** `chat_stats.py` and `mcp_bridge.py` read `bizKey` / `bizSalt` from the configuration -
+  two keys that do not exist on this machine, because WeChat 4.x derives each database's key from the
+  account-wide passphrase (PBKDF2 over the file's own 16-byte header salt). Both paths therefore reported
+  "missing key", and the hint they printed (`config set bizKey`) leads somewhere worse: that key is not in
+  the CLI's writable allowlist, so following the advice hits `INVALID_CONFIG_KEY`. `biz_daily.py` held the
+  working derivation - and computed it **twice in a row**, the first result immediately overwritten by the
+  second, which is what a fork in the logic leaves behind. All three now call one shared
+  `_utils.biz_message_db()`, and a source-level test asserts that no other script reads `bizKey` at all -
+  so a script added later is covered too, rather than only today's three. Verified by running the path
+  that used to fail: `daily-stats` now returns per-account counts, and a daily dry run opens the database.
+- **`wiki lint` was O(links x pages) and took 9.5 minutes on the article line.** The link-existence
+  predicate passed `resolvable_names(pages)` *inside a lambda*, so the set of all page names plus aliases was
+  rebuilt once per link instead of once per run - measured on this machine: 3,623 pages took **9m29s**, while the
+  1,527-page chat line took 3.2s. The set is now computed once, outside the lambda: the same page count now takes
+  **3.4s**. Behaviour is unchanged, and that was checked rather than assumed - the old and new versions produce
+  **byte-identical JSON** (sha256 match, 366,638 bytes) on the chat line, and hoisting a pure function out of a
+  per-call position is a no-op by construction. This also unblocked the new `lint_wiki` assistant tool, whose
+  first real-machine run is what surfaced the timeout. Side note for whoever touches that code: two other places in
+  `assistantTools.ts` split a path with `/[\/]/` for the same reason (telling the two knowledge-base lines
+  apart) and one of them had lost a backslash to a shell heredoc, so on Windows both lines were labelled
+  文章线 - silently, because the output still looked plausible. The helper `wikiIndexPath` and the line label are
+  now covered by a mutation-checked test.
+
+
+- **The ball is never backed by anything now - the glow layer is gone entirely.** The user reported
+  it a second time: "the background is not transparent while it is thinking". That is the *same*
+  observation that led to the 2026-09-26 change, where an always-on glow was narrowed to
+  "only while there is a state" - so the remaining case was exactly the busy one. **The same
+  complaint arriving twice means the ask is not "draw less of it" but "not at all"**, so the whole
+  layer is removed: the element, the three state rules, the `radial-gradient`, `@property --hue`,
+  and the `drift` / `breathe` animations, including the two selectors still named inside
+  `prefers-reduced-motion` (the tests caught that leftover - a half-removal is what this change was
+  most likely to leave behind). The state light is not lost: all four states already have their own
+  face (thinking / sorry / tired / idle), and that is the primary signal.
+
+- **The pressed face is preloaded, because fetching it cost a frame.** The user reported that
+  clicking the ball flickers. Measured: a face served from the daemon takes **~15 ms** against a
+  16.7 ms frame at 60 Hz, and the faces are CSS backgrounds - fetched **when first used**, which is
+  the instant the ball is pressed. So the first press can render an empty face for a frame. The
+  repo's own comment had recorded the symptom before ("球在按下的一瞬间会闪成一张空图") and fixed
+  the whitelist at the time; the whitelist is correct, but the first use still waits for the
+  network. All five faces are now fetched when the page loads, inside the `hasShell` branch (the
+  browser fallback never shows the ball).
+
+- **Expanding the ball no longer makes it jump first.** The user described it precisely: click the
+  ball and it flashes off to one side, snaps back, and only then does the bubble open. The cause is
+  an ordering rule the collapse path already followed and the expand path did not: `setMode` resized
+  the window **first** and told the page **afterwards**. The ball is pinned to a *corner* of the
+  window, and which corner depends on the layout (`anchor-top` when the bubble opens upward,
+  `bubble-right` when it opens to the right) - so during those frames the ball was still drawn with
+  the default anchor, i.e. at a **different corner of the already-larger window**. Measured against
+  the real layout the vertical error is (bubble height - ball size), which is why it reads as a jump
+  rather than a flicker. Collapsing had the same trap and dodged it deliberately ("tell the page
+  first, then shrink, and wait at least one frame - otherwise a 76x76 window shows a sliver of the
+  bubble"); expanding now does the same: reposition the anchor, **wait for the page to actually
+  paint** (two `requestAnimationFrame`s via `executeJavaScript`, with a ceiling so a busy renderer
+  cannot stall the expansion), resize, and only then switch modes. It is two messages rather than
+  one because switching modes early shows the bubble inside the still-96px window - the same trap
+  from the other side.
+
+- **Clicking anywhere in the panel threw a `ReferenceError`.** `renderer.js` called
+  `closeQuickMenu()` on every document click and on Escape, and that function **does not exist** -
+  the menu is native now, opened by the main process outside the window, so there is no in-page menu
+  to close. The two calls were leftovers from the in-page implementation. Harmless in that a throw
+  inside one listener does not stop the others, but it fired on every click, and it was the
+  unhandled error jsdom kept reporting while the panel tests passed. Deleted, with the reason left
+  in place.
+
+
+- **Every subprocess now runs without a console window.** The user reported a black command-line
+  window popping up while the assistant was thinking and using tools. The cause was not one bad
+  call: the daemon itself is started with `detached` + `stdio: 'ignore'` + `windowsHide`, so it has
+  **no console** - and Windows therefore creates a fresh one for every child it spawns unless that
+  call site says `windowsHide: true`. Fourteen of the fifteen sites did not, including the assistant
+  tool path itself (`pythonBridge`) and the Python probes (`--version`, `import sqlcipher3`).
+
+  Nothing was watching that before, which is why it was missed everywhere at once, so a test now
+  requires it: it walks `src/`, `bin/` and `resources/panel/`, strips comments (a comment that
+  mentions `spawn(` is not a call - that tripped the first draft), and fails listing any call site
+  without `windowsHide`. Writing the scan found a fifteenth site that a hand pass had missed
+  (`bin/weflow-cli-electron.cjs`), and the mutation check confirms removing one is caught.
+
 ## 1.8.2
 
 ### Changed

package/OPERATIONS.md

@@ -1087,6 +1087,85 @@ npm run eval:assistant -- --json           # 附机器可读报告
 会把守护进程刚写的状态覆盖掉）。用的 key 是你配置里那一个（`lock:` 密文，只在本机解），
 临时配置里只放这一个字段。
 
+### 技能：让助手读上你自己的技能包
+
+技能就是一份 `SKILL.md`（`name` + `description` frontmatter）。助手**不会安装、不会执行**它们——
+它把技能当资料：提示词里列出有哪些，要用时用 `read_skill` 读正文再照着做。所以装一百个技能也不会让模型多出一个工具。
+
+默认扫两个目录：`~/.claude/skills`（你已有的技能立刻可用）和 `~/.weflow-cli/skills`（本项目自己的落脚点）。
+换目录：`weflow-cli config set skillDirs "D:/我的技能,~/.claude/skills"`。
+
+```powershell
+weflow-cli skill list              # 有哪些（带版本与状态）
+weflow-cli skill list --query 日报 # 按 id/名称/说明/触发词过滤
+weflow-cli skill show memory-organizer   # 打印正文
+weflow-cli skill check             # 体检：读不出来的、跨目录同名的、id 不合规的、被禁用的
+```
+
+`skill check` 值得偶尔跑一次：少一个技能不会报错，只会少一个技能——它会告诉你少了哪个、为什么。
+两种禁用方式：`weflow-cli config set skillDisabled "某技能,另一个"`，或在技能自己的 `SKILL.md` 里写 `enabled: false`。
+
+**边界（有意为之）**：`read_skill` 只可能读到名字叫 `SKILL.md`、且被目录扫描扫到的文件，读不到配置、数据库或任意路径。
+符号链接进来的技能**算数**（在 git 仓库里开发技能、再 `ln -s` 到技能目录是常见做法）。
+
+### 助手现在能调哪些工具（以及两条要注意的）
+
+2026-09-29 把三个界面拉平了：助手能调的，基本就是 MCP 客户端早就能调的那一批（详见 `docs/DECISIONS.md` 的 D-058）。
+新增里平时最用得上的几条：
+
+- **抓公众号正文**：贴一个 `https://mp.weixin.qq.com/...` 链接让它读（白名单 + 逐跳复检；非这个域一律拒绝）
+- **搜公开文章**：按关键词搜公开的公众号文章标题与摘要（走第三方搜索页，**搜索词会离开本机且没有预览**）
+- **排版**：「把这段 Markdown 排成公众号格式」→ 它给 HTML 片段，主题用 `list_themes` 查
+- **通讯录**：「我有哪些联系人」——只给名字，**不给 wxid**
+- **学习回顾 / 知识库体检 / 技能体检**：`get_review`、`lint_wiki`、`check_skills`
+- **把待办标记完成**：「交季度报表那条做完了」——它能改状态，**不能删待办**；指代不清（重名）时它会拒绝而不是猜
+
+两条边界要记住：
+
+1. **`search_public` 的搜索词没有闸门**。这是明确的取舍（D-058），不是遗漏——从一条微信消息就能让模型去搜任意词。
+   介意的话就别在群里开助手，或者把它从工具表里去掉（改代码）。
+2. **待办修改在 MCP 那条路上不可达**。助手在微信/面板里能改，外部 MCP 客户端不能（项目自己的天花板：
+   mutating todos stays out）。
+
+### 场景：让某个会话有固定的做法
+
+一个场景 = 关键词 + 附加指令 + 输出规范 + 所需技能。消息进来时按三档挑：**绑定**（你显式指定）→
+**关键词**（这条消息里出现了它的关键词）→ **上次用过的**。都没中就没有场景段，助手行为与以前一字不差。
+
+```powershell
+# 加一个：关键词命中就带上（长文本用 --from-file，别在命令行里塞多行中文）
+weflow-cli scene add --id 日报 --name "日报整理" --keywords 日报,推文 `
+  --instruction "把这些推文按主题分组，标注来源。" --output-spec "先列表后总结" --dry-run
+weflow-cli scene add ... --yes        # 确认执行（所有写操作都要先 --dry-run 再 --yes）
+
+weflow-cli scene list                 # 有哪些、本会话绑的是哪个
+weflow-cli scene show 日报            # 看全部字段
+weflow-cli scene disable 日报         # 停用（不再参与匹配）
+weflow-cli scene remove 日报          # 删掉（连指向它的绑定一起清）
+weflow-cli scene bind wxid_xxx --scene 日报 --yes   # 固定绑到某个会话
+weflow-cli scene unbind wxid_xxx --yes
+```
+
+在对话里（微信或面板）也能用：
+
+- `场景` —— 列出所有场景，标出本会话生效的那个
+- `场景 <id>` —— 把这个场景绑到当前会话
+- `场景 无` —— 解绑
+
+只有后半段**是真实存在的场景 id** 时才算指令，所以「场景切换怎么用」这种问话不会被吃掉。
+指令不调用模型（省一次调用，也省配额）。
+
+**改完场景要重启助手才生效**：场景是助手启动时读一次（和配置一样），而**技能是每一轮现扫的**——
+所以新装一个技能立刻可用，但 `scene add` 出来的场景在运行中的助手那里看不见。
+要 `weflow-cli assistant stop` 再 `assistant start` 之后才生效（**没有 `assistant restart` 这个命令**）。
+
+场景里可以写 `{{skill:技能id}}` 行内引用技能；技能缺失时会明确写成「技能文件不可用，请直接完成」，
+并让助手在回答里说明哪部分没做——**不会静默跳过**。
+
+**场景只由你在电脑上改**：没有任何助手工具能读写场景，一条微信消息改不了它（同 `隐私` 那条的立场）。
+助手回答下面展开的「思考过程」里会写清这一次用了哪个场景、因为哪一档命中；如果有两个场景同样匹配，
+它**不带场景**，并在那里说明原因。
+
 ## 7. 常见问题
 
 | 现象 | 处理 |

package/README.en.md

@@ -98,7 +98,10 @@ Automatic initialization on Linux depends on the WeChat distribution, the Python
 | AI collaboration | Expose article crawling, knowledge-base retrieval, digests, and selected local-data tools to MCP-compatible clients. The inventory follows the current code and `docs/MCP.md`. |
 | Personal review | Monthly chat reports, annual reports, todo extraction, and local Moments cache queries. |
 | WeChat favorites | Read WeChat "Favorites" (official-account articles, text, images, videos, chat records) with type filters, keyword search, and Markdown/JSON export. |
-| Second-brain agent | Chat with a local AI assistant inside WeChat: natural-language queries over chats, favorites, Moments, digests, WeRead, todos, and the knowledge base; three-tier memory across sessions, daemonized background service. |
+| Second-brain agent | Chat with a local AI assistant inside WeChat: natural-language queries over chats, favorites, Moments, digests, WeRead, todos, and the knowledge base; three-tier memory across sessions, daemonized background service. It can also **fetch an official-account article**, search public articles, format Markdown for the WeChat editor, list contacts, read your learning reviews, health-check the knowledge base and skill packages, and mark a todo done (**never delete one**). What it can reach, and what stays out of reach, is in `docs/PROJECT_STATE.md` and `docs/DECISIONS.md` (D-058). |
+| On-device panel | A floating ball on your desktop: click to chat with **the same brain as the WeChat side** (same memory, same quota), and each reply expands into a **thinking process** - what tool it called, how many round trips, why it stopped. The ball itself is transparent with a face per state. |
+| Skill packages | The assistant reads the `SKILL.md` packages already on your machine (by default `~/.claude/skills` and `~/.weflow-cli/skills`): the prompt lists what exists, and a body is read on demand before following it. **A skill grants the assistant no new tools** - it is material: not executed, not installed, and unable to read configuration or databases. `weflow-cli skill check` reports unreadable frontmatter, cross-directory collisions, and non-conforming ids. |
+| Conversation scenes | Give one conversation a fixed way of working: keywords plus an extra instruction, an output spec, and required skills. Each message picks one by **binding → keyword → last used**, and picks none when nothing matches, leaving the previous behaviour untouched. Manage with `weflow-cli scene`, or bind from the conversation with `场景 <id>`. **Scenes are not readable or writable by the model**, and which scene applied is recorded in the thinking process. |
 
 > **⚠️ Intended use**: this tool only accesses data of **your own** WeChat account, on your own machine, with your own consent. Do not use it to monitor a partner, employee, or any third party without explicit consent, deploy it onto someone else's device, or run it remotely and silently. Review WeChat's terms, account-risk policies, and local legal requirements. See [SECURITY.md](SECURITY.md).
 
@@ -229,7 +232,11 @@ weflow-cli panel               # open the on-device panel window (usable without
 
 `weflow-cli panel` opens a small always-on window that talks to **the same brain as the WeChat side** — the same memory, the same daily quota. **No WeChat login is required**: the messaging channel is optional. The window is only a client; its messages go to the daemon's entry point on `127.0.0.1`, so the two entry points never keep separate copies of memory.
 
-The floating ball needs Electron (`npm i -g electron`); without it the panel degrades to an Edge/Chrome `--app` window — same UI, but no frameless always-on-top ball, no tray, no global shortcut. With the ball (a 96px mascot): **click it and the chat bubble opens beside it (the ball itself stays put; click again to collapse)**. The bubble opens to the left of the ball by default, flips to the right when there is no room on the left, and top-aligns when vertical space runs short; drag the ball to move it, and the position is remembered. The ball doubles as a status light — busy, offline, and quota-exhausted are three real states, each with its own face and glow colour, while an idle ball shows no glow at all. **Right-click anywhere in the panel** to draft a reply for someone on your list (`weflow-cli config set quickReplyContacts "Alice,Bob"` — a click sends that conversation to two cloud models and returns text only, never sending for you). The last item in that menu tucks the ball away; the tray icon brings it back.
+The floating ball needs Electron (`npm i -g electron`); without it the panel degrades to an Edge/Chrome `--app` window — same UI, but no frameless always-on-top ball, no tray, no global shortcut. With the ball (a 96px mascot): **click it and the chat bubble opens beside it (the ball itself stays put; click again to collapse)**. The bubble opens to the left of the ball by default, flips to the right when there is no room on the left, and top-aligns when vertical space runs short; drag the ball to move it, and the position is remembered. **The ball is transparent - only the mascot shows through** - calm at rest, and switching to a *thinking* face for the seconds you are waiting on an answer (offline and quota-exhausted have faces of their own).
+
+**Every reply carries a collapsible "thinking process" (closed by default)**: how that turn actually went - the routing decision, which tool it called, its arguments, how many round trips, and why it stopped. It is the same record you get in WeChat by sending 轨迹 (or 思考过程), so the two cannot drift apart.
+
+**Right-click anywhere in the panel** to draft a reply for someone on your list (`weflow-cli config set quickReplyContacts "Alice,Bob"` — a click sends that conversation to two cloud models and returns text only, never sending for you). The last item in that menu tucks the ball away; the tray icon brings it back. Running a tool **never pops up a console window**, and the window recovers by itself after the assistant restarts - you do not have to reopen it.
 
 Then just talk to ClawBot on your phone. The assistant queries local chats and favorites to answer, with memory that survives across sessions:
 

package/README.md

@@ -98,7 +98,10 @@ Linux 的自动初始化能力取决于微信发行版、Python 依赖和当前
 | AI 协作 | 通过 MCP 把文章、知识库、日报和受控的本地数据能力交给兼容客户端；工具清单以 `weflow-cli mcp-config` 和 `docs/MCP.md` 为准。 |
 | 个人回顾 | 聊天月报、年度报告、待办提取与朋友圈本地缓存查询。 |
 | 微信收藏 | 读取微信"收藏"内容（公众号文章、文字、图片、视频、聊天记录），支持类型过滤、关键词搜索与 Markdown/JSON 导出。 |
-| 第二大脑 Agent | 在微信里和本地 AI 助手对话：自然语言查询聊天记录、收藏、朋友圈、日报、微信读书、待办与知识库；三层记忆跨会话延续，守护进程常驻后台。 |
+| 第二大脑 Agent | 在微信里和本地 AI 助手对话：自然语言查询聊天记录、收藏、朋友圈、日报、微信读书、待办与知识库；三层记忆跨会话延续，守护进程常驻后台。也能**抓一篇公众号正文**、在公开文章里搜、把 Markdown 排成公众号格式、列通讯录、读学习回顾、体检知识库与技能包、把待办标记完成（**不能删除**）。它调得到的工具与不可达的边界见 `docs/PROJECT_STATE.md` 与 `docs/DECISIONS.md`（D-058）。 |
+| 本机面板 | 桌面常驻的悬浮球：点开即对话（与微信里**同一个大脑**、同一份记忆与配额），每条回答下面可展开**「思考过程」**（它调了什么工具、几轮、为什么停），球本身有状态表情、透明底。 |
+| 技能包 | 助手能读你机器上已有的 `SKILL.md` 技能包（默认扫 `~/.claude/skills` 与 `~/.weflow-cli/skills`）：提示词里列出有哪些，要用时读正文再照着做。**技能不给助手增加任何工具**——它只是资料，不执行、不安装、读不到配置和数据库。`weflow-cli skill check` 报出读不出来、跨目录同名和 id 不合规的技能。 |
+| 会话场景 | 给某个会话一套固定的做法：关键词 + 附加指令 + 输出规范 + 所需技能。消息进来按「绑定 → 关键词 → 上次用过的」挑一个，都没中就完全按原来的行为。用 `weflow-cli scene` 管理，或在对话里发「场景 <id>」绑定。**场景不让模型读写**，本次用了哪个场景会记在「思考过程」里。 |
 
 > **⚠️ 合法使用边界**：本工具仅限访问**你自己拥有并登录的微信账号**在自己设备上的数据。未经他人明确同意，不得用它监控配偶、员工或任何第三方，也不得部署到他人设备或远程静默运行。请同时留意微信服务条款、账号风控和当地法律要求。详见 [SECURITY.md](SECURITY.md)。
 
@@ -222,7 +225,14 @@ weflow-cli panel               # 打开本机面板窗口 (不扫码也能用)
 悬浮球需要 Electron（`npm i -g electron`）；没装的话会降级成 Edge/Chrome 的 `--app` 小窗，
 界面一样，但没有无边框置顶、没有托盘与快捷键。有球时：**点一下它在旁边展开对话气泡
 （球不动，再点一下收起）**；气泡默认开在球的左边，左边放不下会自己翻到右边，上方不够就
-改成顶对齐；拖动球可以换位置（位置会记住）。**在面板里点右键**可以给名单上的人快速起草回复（`weflow-cli config set quickReplyContacts "某人,另一人"`；点一下就是把那段对话发给两个云端模型，只产出文本、不会替你发送），菜单最后一项能把球收起来（点托盘图标叫回来）。
+改成顶对齐；拖动球可以换位置（位置会记住）。**球是透明底的，只有吉祥物本身**——空闲时一脸
+平静，**在你等它回答的那几秒换成"思考"的表情**（连不上、额度用完时各有各的脸）。
+
+**每条回答下面可以展开「思考过程」（默认收起）**：里面是它这一轮怎么走的——路由判断、
+调了哪个工具、参数摘要、往返几次、为什么结束。在微信里发「轨迹」（或「思考过程」）看的是
+同一份记录，两处不会各说各话。
+
+**在面板里点右键**可以给名单上的人快速起草回复（`weflow-cli config set quickReplyContacts "某人,另一人"`；点一下就是把那段对话发给两个云端模型，只产出文本、不会替你发送），菜单最后一项能把球收起来（点托盘图标叫回来）。助手跑工具时**不会弹出黑色命令行窗口**；助手重启之后窗口也会自己恢复，不用重新打开。
 
 之后在手机微信的 ClawBot 对话里直接说话，助手会自动查询本地聊天记录和收藏作答，并具备跨会话记忆：
 

package/bin/weflow-cli-electron.cjs

@@ -46,6 +46,8 @@ const electronArgs = ['-e', script, '--', ...args];
 
 try {
   execFileSync(electronPath, electronArgs, {
+    // 从无控制台的父进程（守护进程/托盘）跑起来时，不写这个 Windows 会弹一个命令行窗口
+    windowsHide: true,
     stdio: 'inherit',
     env,
     cwd: process.cwd()